《Writing a good CLAUDE.md》

大型语言模型（LLM）如Claude在每次会话开始时是“无状态”的——它们不会记忆之前的对话，只能依赖你当次输入的内容了解项目。因此，CLAUDE.md文件承担了“入门手册”的角色，负责向Claude介绍项目的背景、结构和工作方式。

一个好的CLAUDE.md应清晰回答三个问题：
- WHAT：项目技术栈、代码结构，尤其是多仓库时需要指出各部分职责；
- WHY：项目目的和各模块功能；
- HOW：如何操作项目，比如使用的构建工具、测试流程等。

但写法很关键。文件太长或包含过多细节，Claude可能会选择忽略部分内容，因为Claude Code在系统提醒中会告知模型“只有高度相关时才用此上下文”，避免被无关指令干扰。太多无关指令反而影响效果。

因此，遵循“少即是多”的原则至关重要。研究显示，顶尖LLM能稳定处理约150-200条指令，且越多指令，执行质量越下降。CLAUDE.md应只包含对所有任务普遍适用的核心内容，避免将所有风格指南、命令一股脑塞进去。

为解决大项目中信息过多问题，推荐采用“渐进披露”策略：将特定任务说明拆分成多个文件，CLAUDE.md只提供文件列表和简要说明，让Claude按需调用，从而避免上下文膨胀。

另外，别让Claude当代码风格检查器。代码格式和风格应交给专门的工具（如Biome）处理，既节省算力又保证效率。可以用钩子或命令将格式化和检查结果反馈给Claude，而不是让它自己找错。

最后，别用自动生成工具随便产出CLAUDE.md。它影响所有后续工作流程和产物，必须认真打磨每一句话，确保精准传达项目核心。

总结：CLAUDE.md是让Claude“入职”项目的关键文件，需简洁、聚焦、实用。只告诉Claude最重要的事，教它如何自己找信息，避免信息过载。用好CLAUDE.md，才能发挥AI编程助手的最大潜力。

原文：humanlayer.dev/blog/writing-a-good-claude-md