AI 摘要：本文介绍了如何编写一个高质量的 CLAUDE.md （或AGENTS.md）文件，以帮助大型语言模型如 Claude 在每次会话中准确理解项目上下文。作者强调 Claude 是无状态（stateless）的，需要通过 CLAUDE.md 主动引导项目背景和结构。文中指出主文件应聚焦通用信息、减少冗余指令、避免让模型充当代码检查工具，并提出了“渐进揭示(Progressive Disclosure)”原则来管理上下文信息。结论是：精简、聚焦、人工精心编写的 CLAUDE.md 才能真正成为助力开发的高杠杆点。

1. LLM 基础与 CLAUDE.md 的角色
• 强调 LLM 是无状态的，推理时并不会记忆过往对话。
• CLAUDE.md 文件是让模型理解代码库的唯一常驻入口，每次对话都会自动加载。
• 它的作用类似于为 Claude 提供项目结构图与工作指南。

2. CLAUDE.md 的内容原则：WHAT / WHY / HOW
• WHAT：介绍项目栈、架构与子模块结构，是 Claude 的“路线图”。
• WHY：说明项目目标与各部分用途，帮助 Claude 理解设计动机。
• HOW：告诉 Claude 如何执行任务，如构建流程、测试方式、工具链（例如使用 bun 还是 node）。
• 提醒不要塞入所有命令，应保持“够用、通用、可解释”。

3. Claude 忽略 CLAUDE.md 的原因及机制
• Claude 会根据系统提醒(<system-reminder>)判断上下文是否相关。
• 若文件含过多不相关信息，Claude 会选择性忽略。
• 这种机制是为防止用户使用 CLAUDE.md 添加无关“热修复”指令所设计。

4. 编写高质量 CLAUDE.md 的建议
• 遵循 context engineering best practices。
• 少即是多 (Less is more)：避免过多指令或与代码无关的规则。
• 研究表明 LLM 对 150–200 条指令的响应最为稳定，超过会急剧下降。
• Claude Code 的系统提示占掉约 50 条指令空间，因此应控制在极简范围内。

5. 文件长度与通用性建议
• 上下文窗口应专注于高相关的内容，而非填充冗余背景。
• 建议文件 <300 行，理想情况下 <60 行。
• 仅包含“通用适用”的指令与信息。

6. 渐进揭示 (Progressive Disclosure) 原则
• 将不同任务的指令拆分为独立的 Markdown 文件（如 agent_docs/ 目录）。
• 在主文件中只列出这些文件及简要说明，让 Claude 按需访问。
• 避免代码复制，推荐使用 file:line 引用；引用比拷贝更可维护。

7. Claude 不是代码检查工具
• 不应让 Claude 替代 linter 或 formatter。
• 代码风格应由确定性工具（如 Biome）自动处理。
• 可使用 Stop hook 或 Slash Command 将检查与格式化过程外挂给 Claude 参考，而非直接放入主文档中。

8. 避免自动生成或使用 /init
• 自动生成的文件通常内容冗余或缺乏针对性。
• CLAUDE.md 是高杠杆点，一旦草率配置，会对所有阶段输出产生负面连锁影响。
• 建议人工精雕细琢每一行指令，使其精准可靠。

9. 结论与最佳实践总结
• 明确项目的 WHY / WHAT / HOW。
• 内容简洁、普适、避免多余。
• 采用渐进式信息揭示策略。
• 使用独立工具执行语法或格式检查任务。
• 谨慎维护 CLAUDE.md——它影响整个代理（agent）表现的核心。

www.humanlayer.dev

Writing a good CLAUDE.md

`CLAUDE.md` is a high-leverage configuration point for Claude Code. Learning how to write a good `CLAUDE.md` (or `AGENTS.md`) is a key skill for agent-enabled software engineering.