AI 编程 · 个人文档索引

CLAUDE.md 怎么写 · 个人总结

看了几篇讲 AI 上下文配置的文章 + 对照 Claude Code 官方 best practices 后的自己的理解 · 2026-07-03

---

我踩过的坑

AI 不听话，我第一反应总是「换更强的模型」。后来发现很多时候是上下文给错了——该常驻的没写进文件，该按需加载的全塞根目录，该用 Hook 硬拦的却写成一句「请不要…」。

新会话 AI 是白纸。技术栈、构建命令、团队约定、历史 ADR，你不写它就猜，猜错返工，返工比多写几行配置贵多了。

---

CLAUDE.md 到底是什么

项目根目录（或子目录）的 Markdown，Claude Code 会话开始就读，相当于给 AI 的入职手册。

但它本质是建议，不是强制执行。写得越具体、越短，遵循越好；模糊要求（「写干净代码」）等于没写。

Cursor 侧是 .cursor/rules + AGENTS.md；Claude Code 是 CLAUDE.md。AGENTS.md 已是跨工具开放标准（Agentic AI Foundation 维护），多 Agent 团队可以 AGENTS.md 放通用约定、CLAUDE.md 放 Claude 特有配置，或在 CLAUDE.md 里 @AGENTS.md 导入，避免维护两份 diverge 的内容。

---

篇幅：200 行不是形式主义

官方建议 200 行以内。每一行会话全程占 token——改个 CSS 也带着后端部署规范，纯属浪费。

有社区数据说 50 行遵循率 ~94%、400 行掉到 ~71%（待验证：样本和方法我不清楚，但方向对——越长越稀释）。

还有说法 AI 合理遵循约 150–200 条指令，超过后质量均匀下降。我不数条数，用一句自检：删掉这行 AI 会犯错吗？ 不会就删。

只放事实，不放流程——构建命令、目录结构、命名规范是事实；部署 runbook、审查清单是流程，应进 Skills（见《Claude-Code七种配置方式-个人总结》）。

---

写什么、不写什么

该写

• AI 猜不到的：npm run test、uv sync 这类构建命令
• 跟默认不同的：必须用 Zod 校验、统一 BaseResponse 包装
• 团队 Git 规范、必需 env var、非显而易见的坑
• 正面、可验证的指令

不该写

• 读代码就能知道的结构
• 「写干净代码」「注意性能」
• 大段 API 文档——放 docs/，CLAUDE.md 里写指针

否定句慎用

有文章说 87.5% 规则违反来自否定句（待验证）。白熊效应确实存在——「不要用 class 组件」反而激活 class 组件概念。我习惯改成正面表述：

别这么写	改成
不要用 any	所有变量有明确 TS 类型
别在主分支直接提交	变更走 feature 分支 + PR

---

大项目：别全堆根目录

path-scoped Rules

.claude/rules/ + frontmatter paths，只在 Claude 读匹配文件时加载：

---
paths:
  - "src/api/**"
---
API handler 必须 Zod 校验输入

改前端时不加载 API 规则。无 paths 的 Rule = 第二个 CLAUDE.md，会话开始就全量加载。

子目录 CLAUDE.md

app/api/CLAUDE.md 只在读该目录文件时加载。压缩后会丢，直到再碰那个目录——和根 CLAUDE.md 行为不同，别搞混。

@ 指针做渐进披露

## 参考
- API 架构 → @docs/api-architecture.md（改 API 时读）
- 部署 → /deploy 技能

核心思想：CLAUDE.md 当目录，不当百科全书。官方叫 just-in-time context，和 Skills 按需加载是一脉的。

---

Hooks 管「必须发生」

格式化、提交前 lint、危险命令拦截——写 CLAUDE.md 里 AI 可能忘。Hook 触发必执行，跟模型无关。

PreToolUse + exit code 2 可以硬拦删 migration 等操作。CLAUDE.md 负责建议，Hooks 负责强制——这条和我另一篇「七种配置方式」总结是同一逻辑。

---

多层级配置

层级	位置	特点
组织级	IT/MDM 下发	最早加载，不可 exclude
用户级	~/.claude/CLAUDE.md	本机所有项目，个人偏好
项目级	./CLAUDE.md	团队共享，进 Git
本地级	./CLAUDE.local.md	个人覆盖，不进 Git

优先级大致：本地 > 项目 > 用户；组织级是底线。

口头说的不算：对话里「后面都用 async/await」，压缩后就没了。持久化信息必须落文件。

---

怎么起步

1. /init 自动生成初稿——一定要人工精简，一条烂指令的破坏力超过一行烂代码
2. 从实战沉淀：先协作 1–2 个任务，再让 AI 回顾对话总结规范写成 CLAUDE.md
3. 从 20 行开始：技术栈 + 构建/测试命令 + AI 反复犯的 3–5 条，用着再加

Claude Code 创始人习惯：AI 犯错时不只改代码，让它把纠正写进 CLAUDE.md。Auto Memory（~/.claude/projects/.../memory/）也会自动记模式，用 /memory 查看——和 CLAUDE.md 互补，但不能替代团队级约定。

---

规则不生效时我查什么

1. /memory 看 CLAUDE.md 有没有被加载
2. 指令是否够具体——「格式化好」→「2 空格、单行 80 字符」
3. 有没有矛盾——CLAUDE.md 说 MyBatis Plus，rules 说 Flex
4. 该用 Hook 的是不是错写在 md 里

官方还建议：CLAUDE.md 当代码维护——AI 反复犯同一错，说明规则太长被淹没了，或表述歧义。

---

和我工作流的关系

原则	我的做法
事实进 CLAUDE.md / AGENTS.md	Phase 0 /grill-with-docs 沉淀到 docs/ 和 CONTEXT
流程进 Skills	/grill-with-docs、/implement、/review
≤200 行 + 索引	大文档用 @docs/ 指针，不全量塞
强制检查	待补 Hooks（format/lint/危险命令）

以前 README 给人看，现在 CLAUDE.md 给 AI 看——本质都是「把重要信息组织清楚」，但给 AI 的版本要更短、具体、可执行。

---

待办

• 各 repo 审计 CLAUDE.md：流程迁 Skills、超 200 行拆索引
• 统一 AGENTS.md + CLAUDE.md 分工，避免双份维护 diverge
• 配 PostToolUse format Hook
• AI 犯错后追加规则，定期 prune 过时条目