为什么 markdown 比更长的提示更有用
CLAUDE.md 是语言、包管理器、测试命令和禁碰路径的公开、可持久位置。这些不该每轮重打。
它不是愿景稿。改不了一次编辑的句子，删掉。
官方文档也描述过产品可能保存的额外记忆。本教程仍从一份能在 git 里 diff 的文件开始。
文件放哪
第一份放在仓库根，好让各入口看见同一份简报。嵌套文件等单体仓库真需要再加。
用户级笔记只放个人习惯。若和仓库文件打架，留下你真正想要的那份，删掉另一份。
doctor 和新会话用来确认文件已加载。不要以为保存等于生效。
- 先写根目录 CLAUDE.md。
- 团队要共享就提交。
- 确认新会话能看见。
写什么
始终生效的事实：运行时、包管理器、如何跑测试、不能碰的生成代码、密钥路径。
只写 Agent 会搞错的东西。不要把 README 的架构故事再抄一遍。
短条目。与其贴风格指南，不如链到文档。
- 测试命令必须能在你机器上跑。
- 禁令是路径，不是形容词。
- 先写短的。
仓库、用户和嵌套范围
仓库文件是团队契约。用户文件是你的笔记本。嵌套文件只给真正不同的包。
两份文件对测试命令说法不一，Agent 就会时灵时蠢。只留一个。
- 测试命令只有一个真相。
- 包真不一样再嵌套。
- 任何一份都不要写密钥。
自动记忆代替不了说明书
产品可能跨会话保存收获。把它当彩蛋，不要当成你可以不写的文件。
下一个同事需要的东西，放进 git，而不是只放在你本机记忆里。
- 团队事实进 CLAUDE.md。
- 个人快捷方式可以留在本地。
- 记忆笔记里不要放令牌。
设置不是说明书
权限、模型和 MCP 住在设置文件。不要只把测试命令藏在那里。
改完设置就跑 doctor。那里的笔误看起来像模型失灵。
- 说明书 = markdown 事实。
- 设置 = 客户端行为。
- 改完跑 doctor。
团队怎么用这一份
像代码一样审 CLAUDE.md。顺手加一句禁止某库的话，应该被评论。
篇幅控制在你愿意在 PR 里读完的长度。
- 走 PR。
- 删掉过期禁令。
- 入职时指给新人看。
说明书阶段的错法
整份粘贴别的公司的 CLAUDE.md，包括他们的云名称。
doctor 还找不到文件，你已经写成长文。
- markdown 里有密钥。
- 用户级和仓库级互相打架。
- README 克隆。
做到这样就够了
你能指出三条 Agent 不能忽略的要点。
- 根文件存在。
- 测试命令是真的。
- 禁令是路径。
- 没有密钥。
- 新会话看得到。
下一章：把重复做成技能
技能章会把你反复跑的流程打成剧本。
MCP 再等一章。