CLAUDE.md 与配置体系入门：让 AI 真正了解你的项目

ccAiHub
4 阅读5分钟

合集：Claude Code Skills 系列 · 初级篇（三）

前言

前两篇我们学会了创建 Skills，但 Claude Code 的配置体系远不止于此。本篇聚焦两个关键基础设施：CLAUDE.md（项目说明文档）和 settings.json（配置文件），让 Claude 真正理解你的项目上下文和工作习惯。国内使用Claude Code 访问ccAiHub.com

一、CLAUDE.md：给 AI 的项目入职文档

1.1 它是什么？

CLAUDE.md 是每次 Claude Code 会话启动时自动读取的 Markdown 文件。你可以把它理解成"给 AI 的入职文档"——每次 Claude 开始工作前，都会先读这份文档了解项目背景。

文件位置：

my-project/
├── CLAUDE.md          ← 项目根目录（最重要）
├── src/
│   └── CLAUDE.md      ← 子目录级别（覆盖父级，只在该目录有效）
└── .claude/
    └── CLAUDE.md      ← 备选位置

1.2 快速生成

不知道怎么写？让 Claude 帮你生成：

cd my-project
claude

# 在 Claude Code 中输入：
/init

/init 命令会扫描你的项目结构，自动生成一份 CLAUDE.md 草稿。

1.3 推荐内容结构

# 项目名称

## 项目概述
一句话说明项目是什么、解决什么问题。

## 技术栈
- 语言：TypeScript 5.3
- 框架：Next.js 14（App Router）
- 数据库：PostgreSQL 16 + Prisma ORM
- 测试：Vitest + Playwright
- 包管理：pnpm 8

## 目录结构
\```
src/
├── app/          # Next.js App Router 页面
├── components/   # 共享 React 组件
├── lib/          # 工具函数和服务
├── types/        # TypeScript 类型定义
└── tests/        # 测试文件
\```

## 开发规范
- 组件使用函数式写法，配合 hooks
- 禁止使用 `any` 类型，用 `unknown` 替代
- CSS 使用 Tailwind，禁止写内联 style
- 提交信息遵循 Conventional Commits 规范

## 常用命令
\```bash
pnpm dev        # 启动开发服务器（端口 3000）
pnpm test       # 运行单元测试
pnpm e2e        # 运行 E2E 测试
pnpm build      # 生产构建
pnpm lint       # ESLint 检查
\```

## 环境变量
所有环境变量在 `.env.example` 中有说明，复制为 `.env.local` 后填写。

## 重要注意事项
- `src/lib/payments/` 目录涉及支付逻辑，修改前必须通知后端团队
- 数据库 Migration 文件不要手动修改，使用 `prisma migrate dev` 生成

1.4 CLAUDE.md 最佳实践

✅ 应该写的内容：

  • 技术栈和版本（让 Claude 给出准确的代码）
  • 关键目录说明（防止在错误的地方写代码）
  • 团队规范（代码风格、命名约定）
  • 常用命令（让 Claude 运行正确的命令）
  • 禁区和注意事项

❌ 不应该写的内容：

  • 详细的 API 文档（太长，用链接指向）
  • 完整的代码示例（浪费上下文，放到 Skills 里）
  • 所有历史变更记录（这是 git log 的工作）

长度控制：CLAUDE.md 建议控制在 200-400 行以内，超出部分用链接引用。

二、settings.json：三层配置体系

Claude Code 的配置系统是三层叠加的，优先级从低到高：

全局配置（低优先级）
    ~/.claude/settings.json

项目共享配置（中优先级）
    .claude/settings.json         ← 提交到 Git，团队共用

本地个人配置（高优先级）
    .claude/settings.local.json   ← 加入 .gitignore，个人专属

2.1 配置文件基本结构

.claude/settings.json：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [],
    "deny": [],
    "ask": []
  },
  "env": {}
}

添加 $schema 字段可以在 VS Code 中获得自动补全和校验。

2.2 权限配置：Allow / Ask / Deny

权限系统控制 Claude 能执行哪些操作。规则格式：工具名(参数模式)

常见配置示例：

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Bash(git *)",
      "Bash(npm run *)",
      "Bash(pnpm *)",
      "Bash(npx vitest*)"
    ],
    "ask": [
      "Bash(rm *)",
      "Write(**/*.sql)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "WebFetch",
      "Write(**/.env*)"
    ]
  }
}

规则说明：

规则效果
allow直接执行，不询问用户
ask每次执行前向用户确认
deny永远拒绝执行

通配符支持：

Bash(git *)        # 所有 git 子命令
Write(**/*.test.*) # 所有测试文件的写入
Read(src/**)       # src 目录下所有文件的读取

2.3 实用权限配置模板

前端项目：

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Glob",
      "Grep",
      "Bash(git *)",
      "Bash(pnpm *)",
      "Bash(npx *)"
    ],
    "ask": [
      "Bash(rm *)",
      "Write(**/.env*)"
    ],
    "deny": [
      "Bash(curl *)",
      "Bash(wget *)"
    ]
  }
}

Python 后端项目：

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Bash(git *)",
      "Bash(python *)",
      "Bash(pip *)",
      "Bash(pytest *)",
      "Bash(alembic *)"
    ],
    "ask": [
      "Bash(rm *)",
      "Bash(psql *)"
    ],
    "deny": [
      "Bash(DROP *)",
      "Write(**/.env)"
    ]
  }
}

三、环境变量配置

不想每次都手动传 API Key？在 settings.json 中配置：

本地配置文件（.claude/settings.local.json，加入 .gitignore）：

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-...",
    "GITHUB_TOKEN": "ghp_..."
  }
}

注意：包含 secrets 的配置文件必须放在 settings.local.json，绝不能提交到 Git。

.gitignore 中添加：

.claude/settings.local.json

四、查看当前配置状态

# 在 Claude Code 中
/status

输出示例：

配置层级：
  全局配置:  ~/.claude/settings.json ✓
  项目配置:  .claude/settings.json ✓
  本地配置:  .claude/settings.local.json ✓

已加载 Skills：
  - commit-msg (project)
  - code-review (project)
  - deploy (global)

权限摘要：
  Allow: Read, Edit, Bash(git *), Bash(pnpm *)
  Ask:   Bash(rm *)
  Deny:  Bash(rm -rf *)

五、Plan Mode：只读不写的安全模式

在做危险操作（大范围重构、删除文件）前，先用 Plan Mode：

# 快捷键：Shift + Tab
# 或在提示中说：
先帮我规划一下怎么重构这个模块，不要修改任何文件

Plan Mode 下 Claude 只会阅读和分析，不会执行任何写入操作。确认方案后，切回普通模式再执行。

六、完整项目配置示例

一个完整的 Claude Code 项目配置应该是这样的：

my-project/
├── CLAUDE.md                          # 项目说明（提交到 Git）
├── .claude/
│   ├── settings.json                  # 团队共用配置（提交到 Git）
│   ├── settings.local.json            # 个人配置（加入 .gitignore）
│   └── skills/
│       ├── commit-msg/
│       │   └── SKILL.md
│       ├── code-review/
│       │   └── SKILL.md
│       └── deploy/
│           ├── SKILL.md
│           └── scripts/
│               └── pre-deploy-check.sh
└── .gitignore

.gitignore 中：

.claude/settings.local.json

七、本篇小结

文件作用是否提交 Git
CLAUDE.md项目入职文档，每次会话自动读取✅ 提交
.claude/settings.json团队共用配置（权限、MCP 等）✅ 提交
.claude/settings.local.json个人配置（API Key 等 secrets）❌ 不提交
~/.claude/settings.json全局个人偏好N/A

初级篇到这里就完整了。你已经掌握了 Claude Code Skills 的核心概念，接下来中级篇将深入讲解更强大的特性：自动触发机制、工具权限控制和 Hooks 自动化。

系列导航

  • 初级篇（一）：什么是 Skills，为什么需要它
  • 初级篇（二）：从零创建你的第一个斜杠命令
  • 初级篇（三）：CLAUDE.md 与配置体系入门 ← 当前
  • 中级篇（一）：自动触发机制与工具权限控制
  • 中级篇（二）：Hooks 钩子与确定性自动化
  • 中级篇（三）：团队协作与 Git 共享实践
  • 高级篇（一）：CI/CD 集成与无头模式
  • 高级篇（二）：动态上下文注入与多文件 Skill
  • 高级篇（三）：多智能体编排与复杂工作流
avatar
文章
阅读
粉丝