用 CLAUDE.md 固化项目约束
2026/04/05·9 分钟阅读·Claude 中文站
系统介绍 CLAUDE.md 的作用、编写范式与常见反模式，让项目规范在每次会话中自动生效。
CLAUDE.md 是什么
CLAUDE.md 是项目级"给 AI 的说明书"。Claude Code 每次启动会自动读取，把里面的规则作为硬约束遵守。
一、加载规则
1.1 三级加载顺序
| 位置 | 作用范围 | 优先级 |
|---|---|---|
~/.claude/CLAUDE.md | 全局个人偏好 | 最低 |
仓库根 CLAUDE.md | 项目级规范 | 中 |
子目录 CLAUDE.md | 局部规则 | 最高 |
子级覆盖父级同名条目。
1.2 自动加载时机
claude启动时/clear重置上下文后/memory手动重载
二、标准结构（五段式）
# 项目名
## 技术栈
[Node 版本、框架、数据库、部署方式]
## 目录约定
[哪些目录放什么]
## 编码规范
[命名、格式、风格]
## 禁止事项
[绝对不能做什么]
## 验收标准
[提交前必须满足的条件]三、实操示例
# 某电商后端
## 技术栈
- Node.js 22 + NestJS 10
- PostgreSQL 15，ORM 用 Prisma
- 部署：Docker + K8s
## 目录约定
- src/modules/ 按业务域拆分
- src/common/ 放公共工具
- test/ 仅存 E2E，单测与源码同目录
## 编码规范
- 类型：禁止 any，所有返回值显式标注
- 命名：业务服务用 XxxService，DTO 用 XxxDto
- 日志：统一用 logger，禁用 console
## 禁止事项
- 不得绕过 Prisma 直接写 SQL
- 不得提交敏感信息（.env、key）
- 不得使用未审核的第三方库
## 验收标准
- npm run lint 通过
- npm test 全绿
- npm run build 构建成功四、编写范式
4.1 硬约束用强动词
- "必须" / "禁止" / "不得" —— 强约束
- "建议" / "优先" —— 弱约束
AI 对强动词敏感度更高。
4.2 用示例替代描述
❌ "数据库查询要规范"
✅ "数据库查询示例：await prisma.user.findMany({ ... })，禁止 raw SQL"
4.3 给出正反例
正例：await userService.create(dto);
反例：new User().save(); // 不得绕过 service 层五、常见反模式
| 反模式 | 问题 | 纠正 |
|---|---|---|
| 几千字长文 | 占 context，模型只看前半 | 分层拆分 |
| 只有描述没有示例 | AI 难以判断边界 | 加正反例 |
| 忘记更新 | 规则与代码不符 | 纳入 PR checklist |
| 写得像文档而非指令 | AI 不把它当约束 | 用祈使语气 |
六、提交前检查清单
- [ ] 技术栈版本具体（Node 22 而非 Node latest）
- [ ] 禁止事项至少 3 条
- [ ] 验收标准可执行（有具体命令）
- [ ] 无过时规则
- [ ] 全文 < 200 行（超出拆分到子目录）
本文为骨架版，第二阶段将补充：不同行业（前端、后端、数据、AI）的 CLAUDE.md 模板库。