Writing a good CLAUDE.md
AI 要約 · Qwen 要約は中国語 収録日
原文を読む 文章建议把 CLAUDE.md 写成简短、通用且高杠杆的项目入门说明，并用渐进披露和确定性工具减少上下文负担。
核心定位
- 文章认为 LLM 在推理时基本是无状态的，不会随时间学习代码库。
- CLAUDE.md 或 AGENTS.md 是默认进入每次会话的文件，用于向 Claude 介绍项目。
- 它应帮助 Claude 了解代码库结构、项目目的和工作方式。
内容框架
- WHAT：说明技术栈、项目结构、应用和共享包的位置。
- WHY：说明项目目的以及各部分的作用。
- HOW：说明如何构建、测试、类型检查、编译或验证改动。
被忽略风险
- Claude Code 会在用户消息中加入 system-reminder，提示上下文可能不相关。
- 如果 CLAUDE.md 包含大量不通用指令，Claude 可能判断其不相关而忽略。
- 文件内容越不普遍适用，被忽略的可能性越高。
少即是多
- 文章引用研究称前沿思考型 LLM 可较稳定地遵循约 150 到 200 条指令。
- 指令数量增加时，模型对指令的遵循质量会整体下降。
- Claude Code 的系统提示约含 50 条指令，因此 CLAUDE.md 应尽量减少指令数量。
长度与适用性
- 上下文窗口中聚焦且相关的内容通常比大量无关内容更有效。
- CLAUDE.md 应尽可能通用，避免放入只在特定任务中相关的说明。
- 文章提到一般共识是少于 300 行较好，HumanLayer 的根文件少于 60 行。
渐进披露
- 任务或项目特定说明可放在独立 markdown 文件中。
- CLAUDE.md 可列出这些文件并简述用途，让 Claude 在需要时读取。
- 优先使用 file:line 指针，而不是容易过时的代码片段。
工具分工
- 文章反对把 LLM 当作昂贵的 linter 或 formatter。
- 代码风格应优先交给确定性工具处理。
- 可用 hooks、slash commands 等方式把实现与格式检查分开。
避免自动生成
- CLAUDE.md 影响工作流的每个阶段，是高杠杆文件。
- 文章建议不要依赖 /init 或自动生成功能。
- 应仔细手工编写每一行，以减少错误被放大。