程序员の小满

第 11 章 CLAUDE.md——给 Claude 写说明书

Mr.Tong...
  • AI
  • Claude Code
大约 7 分钟

❓ 引导问题：如何让 Claude 每次对话都「记住」项目规范？CLAUDE.mdopen in new window 应该放什么内容？怎么写才有效？

📖 11.1 CLAUDE.mdopen in new window 的本质

CLAUDE.mdopen in new window 是 Claude Code 的「项目说明书」——每次新会话启动时，Claude 会自动读取并将其加载为系统提示的一部分。它解决了「每次对话都要重新解释项目」的问题。

没有 CLAUDE.mdopen in new window：Claude 每次都从零开始，你需要反复告诉它包管理器、代码风格、测试命令、哪些文件不能动。

有了 CLAUDE.mdopen in new window：这些信息只需写一次，Claude 每次都会遵守。提交到 Git 后，整个团队共享同一套 AI 工作规范。

具体价值：

  • 统一团队行为：所有成员使用 Claude Code 时遵循相同规范
  • 减少重复沟通：项目约定、架构规则只写一次，永久生效
  • 降低出错概率：明确告知风险操作，避免错误决策
  • 加速 AI 理解：帮助 Claude 快速定位关键文件和项目结构

📖 11.2 四级文件位置

级别位置作用范围是否提交 Git
用户级~/.claude/CLAUDE.md当前用户的所有项目❌ 个人配置
项目根目录{项目根}/CLAUDE.md当前项目所有会话✅ 团队共享
项目本地{项目根}/.claude/CLAUDE.md当前项目（仅自己）❌ 加入 .gitignore
子目录{任意子目录}/CLAUDE.md处理该目录文件时自动加载✅ 适合多模块仓库

加载优先级（从高到低）：项目本地 → 项目根目录 → 子目录 → 用户级。最具体的规则覆盖上层同类规则。

💡 项目根目录的 CLAUDE.mdopen in new window 提交到 Git 供团队共享；个人偏好（如不喜欢加分号）放在 .claude/CLAUDE.md 并加入 .gitignore。

📖 11.3 快速创建

最简单的方式——让 Claude 自动生成初始版本：

/init

Claude 会分析项目结构、代码风格、已有配置文件（package.json、pyproject.toml、.eslintrc 等），30 秒内生成符合项目实际情况的 CLAUDE.mdopen in new window，然后你补充和调整即可。

📖 11.4 推荐内容结构

完整模板

# 项目名称
一句话说明这个项目是什么。

## 技术栈
- 语言：Python 3.11
- 框架：FastAPI 0.110
- 数据库：PostgreSQL 15 + SQLAlchemy ORM
- 测试：pytest

## 常用命令
### 开发
uv run uvicorn main:app --reload   # 启动开发服务器
uv run pytest                       # 运行所有测试

### 代码检查
uv run ruff check .                 # 代码检查
uv run ruff format .                # 代码格式化

## 项目结构
- `src/api/` — API 路由和请求处理
- `src/models/` — 数据库模型定义
- `src/services/` — 业务逻辑层
- `tests/` — 测试文件，与 src/ 结构镜像对应

## 编码规范
- 使用 `uv` 管理依赖，不使用 pip 直接安装
- 所有函数必须有类型注解
- 字符串一律使用双引号

## 注意事项
- 不要修改 `migrations/` 目录下的已有文件，只能新增
- `config/secrets.py` 包含敏感配置，禁止输出其内容
- 数据库操作必须通过 Service 层，不要在路由层直接操作 ORM

核心模块详解

1. 常用命令（最高频被参考）

## 常用命令
### 安装依赖
npm ci                    # CI 环境使用，严格按 lock 文件安装

### 开发
npm run dev               # 启动开发服务器（端口 3000）
npm run build             # 构建生产版本

### 测试
npm test                  # 运行所有测试
npm test -- --coverage    # 生成覆盖率报告

### 代码质量
npm run lint              # ESLint 检查
npm run lint:fix          # 自动修复
npm run typecheck         # TypeScript 类型检查

Claude 在执行测试、构建等任务时，会优先查找这里定义的命令，避免猜测或使用错误命令。

2. 项目结构说明 — 帮助 Claude 快速定位文件，减少不必要的目录扫描：

## 项目结构
src/
├── app/                  # Next.js App Router 页面
├── components/
│   ├── ui/               # 基础 UI 组件（Button、Input 等）
│   └── features/         # 业务组件
├── lib/
│   ├── db/               # 数据库客户端和查询
│   └── auth/             # 认证相关逻辑
└── types/                # TypeScript 类型定义

关键文件：
- `src/lib/db/client.ts` — 数据库连接配置
- `src/middleware.ts` — 认证中间件

3. 编码规范 — 确保生成的代码风格一致：

## 编码规范
### 通用
- 文件名使用 kebab-case，类名使用 PascalCase
- 优先使用具名导出（named export），避免默认导出
- 异步函数一律使用 async/await，禁止 .then() 链式调用

### 错误处理
- API 路由使用统一错误响应：`{ error: string, code: string }`
- 客户端错误通过 Error Boundary 捕获

4. 架构约束与禁止事项 — 防止 Claude 犯"聪明但错误"的决策：

## 注意事项（重要）
- `legacy/` 目录下的代码是遗留代码，**禁止修改**，只能读取
- `.env.local` 和 `.env.production` 包含真实密钥，**禁止输出文件内容**
- `prisma/migrations/` 中已有文件**禁止修改**，只能新增迁移
- 修改 `src/middleware.ts` 前必须先告知我

5. 开发环境说明 — 避免因环境差异导致命令执行失败：

## 开发环境
- Node.js：需要 v20 或以上（通过 `.nvmrc` 指定）
- 包管理器：pnpm（禁止使用 npm 或 yarn）
- 本地数据库：Docker Compose 启动（`docker compose up -d`）
- 端口：前端 3000，API 3001

📖 11.5 写好 CLAUDE.mdopen in new window 的黄金法则

用命令式语言——指令越明确，Claude 遵守的概率越高：

❌ 模糊描述✅ 明确指令
代码应该比较整洁函数不超过 50 行，超过时必须拆分
尽量写测试每个新增函数都必须有对应的单元测试
注意安全用户输入必须通过 sanitize() 函数处理后才能传入数据库查询
legacy 目录不太重要禁止修改 legacy/ 目录下的任何文件
用 pnpm 比较好依赖管理只使用 pnpm，禁止使用 npm 或 yarn

保持精简：建议总字数控制在 500 字以内。每条规则只写一次，能通过代码本身传达的信息（如 ESLint 已定义风格）不需要重复。超过 200 行的文件，超出部分不会被加载。

持续更新时机：更换包管理器或构建工具时、添加/移除重要依赖时、发现 Claude 反复犯同一类错误时、某个文件变得不能随意修改时。

📖 11.6 高级用法

Monorepo 分层配置

my-monorepo/
├── CLAUDE.md                  ← 全局规范：共用命令、整体架构
├── packages/
│   ├── web/
│   │   └── CLAUDE.md          ← 前端专属：React 规范、样式约定
│   ├── api/
│   │   └── CLAUDE.md          ← 后端专属：API 设计规范、数据库约定
│   └── shared/
│       └── CLAUDE.md          ← 共享包：导出规则

@ 引用外部文件

当项目已有规范文档，不需要复制内容到 CLAUDE.mdopen in new window 中，直接用 @ 引用：

## 规范文档
详细的 API 设计规范请参考：
@docs/api-design-guide.md

数据库设计约定：
@docs/database-conventions.md

引用的文件内容会占用上下文窗口，建议单个引用文件不超过 500 行。

全局 CLAUDE.mdopen in new window（用户级）

~/.claude/CLAUDE.md 适合存放跨项目通用的个人偏好：

# 个人全局配置
## 回答偏好
- 回复使用中文
- 代码修改前先简要说明修改思路
- 遇到有多种实现方案时，列出选项让我选择

## 安全习惯
- 修改认证相关代码前主动提示我注意安全影响
- 不要在代码注释或日志中输出任何密钥或 token

📖 11.7 常见问题

问题答案
CLAUDE.mdopen in new window 的规则 Claude 不遵守？检查表述是否足够明确（用命令式语言）。将重要规则放到文件靠前位置——Claude 对前半部分注意力更高。
CLAUDE.mdopen in new window 越长越好吗？不是。过多内容占用上下文窗口，重要规则淹没在文字中。建议定期删除过时或低价值条目。
子目录 CLAUDE.mdopen in new window 何时加载？Claude 打开或编辑该子目录下的文件时自动加载，无需手动告知。
可以在 CLAUDE.mdopen in new window 中引用另一个 CLAUDE.mdopen in new window？不能直接引用。提取共享规范到独立文档，再在各 CLAUDE.mdopen in new window 中用 @ 引用。

📖 11.XX 要点总结

  1. 四级文件位置：用户级（个人全局）→ 项目根目录（团队共享）→ 项目本地（自己）→ 子目录（模块专属）
  2. /init 一键生成：自动分析项目，30 秒出初始版本，然后按需调整
  3. 最高频模块是「常用命令」——Claude 执行任务时优先参考这里
  4. 命令式语言是关键：禁止用模糊描述（"注意安全"），必须写明具体规则（"用户输入必须通过 sanitize() 处理"）
  5. 定期维护：发现 Claude 反复犯同类错误 → 立即更新 CLAUDE.mdopen in new window；保持精简，超过 200 行部分不加载

你认为这篇文章怎么样？

  • 0
  • 0
  • 0
  • 0
  • 0
  • 0
0  字
评论
  • 按正序
  • 按倒序
  • 按热度
Powered by Waline v2.14.1