Loading... # CLAUDE.md 编写最佳实践技术分析 # 一、概述 ## 1. 简介 ### A. 是什么 CLAUDE.md 是 Claude Code 的高杠杆配置点，也是每个会话中默认注入的唯一文件。学习如何编写高质量的 CLAUDE.md（或 AGENTS.md）是代理驱动软件工程的关键技能。 ### B. 为什么重要 - LLM 是无状态函数，每个会话开始时对代码库一无所知 - CLAUDE.md 是让 Claude 了解代码库的主要方式 - 编写质量直接影响 AI 代理的工作效率 ### C. 学完能做什么 - 编写简洁有效的 CLAUDE.md 文件 - 使用渐进式信息披露原则优化上下文 - 避免常见陷阱，最大化 Claude Code 的效能 ## 2. 核心原理 LLM 的权重在推理时被冻结，不会随时间学习。模型对代码库的了解完全取决于输入的 token。因此： - 每次会话开始时，编码代理对代码库一无所知 - 必须在每次会话中告诉代理重要信息 - CLAUDE.md 是实现这一目标的首选方式 # 二、LLM 的无状态特性 ## 1. 无状态函数 LLM 是无状态的，模型权重在推理时冻结。这意味着： - 模型不会跨会话学习 - 每个会话都是独立的 - 所有知识必须通过上下文提供 ## 2. 代理记忆管理 编码代理框架（如 Claude Code）通常需要显式管理代理记忆。CLAUDE.md 是默认进入每个对话的唯一文件。 ```mermaid graph LR A[新会话开始] --> B[CLAUDE.md 注入] B --> C[系统提示加载] C --> D[用户消息] D --> E[代理生成响应] E --> F[会话结束] F --> A ```  ## 3. 三层含义 - 代理在每次会话开始时对代码库一无所知 - 必须在每次会话开始时告诉代理代码库的重要信息 - CLAUDE.md 是实现这一目标的首选方式 # 三、CLAUDE.md 的核心作用 ## 1. 代码库入职引导 CLAUDE.md 应该将 Claude 接入代码库，高层面上应覆盖： - WHAT：技术栈、项目结构、代码库地图 - WHY：项目目的、各部分功能 - HOW：工作方式、验证方法、测试运行 ## 2. 内容组成 ```mermaid mindmap root((CLAUDE.md)) WHAT 技术栈 项目结构 代码库地图 monorepo 布局 WHY 项目目的 各部分功能 设计意图 HOW 运行命令 测试方法 类型检查 编译步骤 验证变更 ```  ## 3. 编写原则 不要试图将所有可能需要的命令都塞进 CLAUDE.md，这会导致次优结果。 # 四、Claude 对 CLAUDE.md 的处理机制 ## 1. 系统提醒包装 Claude Code 在系统提醒中包装 CLAUDE.md 内容： ``` <system-reminder> IMPORTANT: this context may or or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task. </system-reminder> ``` ## 2. 忽略机制 当 Claude 认为 CLAUDE.md 内容与当前任务不相关时，会忽略这些内容。文件中不普遍适用的信息越多，Claude 越可能忽略指令。 ## 3. 设计原因 许多用户将 CLAUDE.md 作为添加行为热修复的方式，附加了大量不普遍适用的指令。通过告诉 Claude 忽略不良指令，框架实际上产生更好的结果。 # 五、编写高质量 CLAUDE.md 的原则 ## 1. 少即是多 ### A. 指令跟随能力研究 - 前沿思考型 LLM 可以合理跟随约 150-200 条指令 - 较小模型的能力衰减更快，呈现指数级衰减 - 较大模型呈现线性衰减 ### B. 注意力偏向 LLM 倾向于关注提示边缘的指令： - 最开始：Claude Code 系统消息和 CLAUDE.md - 最结尾：最近的用户消息 ### C. 指令数量影响 随着指令数量增加，指令跟随质量均匀下降。模型不会只忽略新指令，而是开始均匀忽略所有指令。 ```mermaid graph XY x-axis["指令数量"] --> 0 --> 50 --> 100 --> 150 --> 200 --> 250 y-axis["指令跟随质量"] --> 0.0 --> 0.2 --> 0.4 --> 0.6 --> 0.8 --> 1.0 line["小模型（指数衰减）"] : [0, 1.0] : [50, 0.6] : [100, 0.3] : [150, 0.1] : [200, 0.05] : [250, 0.02] line["大模型（线性衰减）"] : [0, 1.0] : [50, 0.85] : [100, 0.7] : [150, 0.55] : [200, 0.4] : [250, 0.25] ``` ### D. Claude Code 系统提示 Claude Code 的系统提示包含约 50 条独立指令，这已接近代理可可靠跟随指令的三分之一。 ## 2. 文件长度与适用性 ### A. 上下文窗口原则 当上下文窗口充满专注、相关的上下文（示例、相关文件、工具调用、工具结果）时，LLM 在任务上的表现更好。 ### B. 普遍适用性要求 由于 CLAUDE.md 进入每个会话，应确保其内容尽可能普遍适用。 ### C. 长度建议 - Anthropic 没有官方建议长度 - 一般共识：少于 300 行最佳，越短越好 - HumanLayer 的根 CLAUDE.md 少于 60 行 ## 3. 渐进式信息披露 ### A. 概念 编写简洁的 CLAUDE.md 文件可能具有挑战性，特别是在大型项目中。渐进式信息披露原则确保 Claude 只在需要时看到任务或项目特定的指令。 ### B. 实现方式 将任务特定的指令保存在单独的 markdown 文件中： ``` agent_docs/ |- building_the_project.md |- running_tests.md |- code_conventions.md |- service_architecture.md |- database_schema.md |- service_communication_patterns.md ``` ### C. 引用机制 在 CLAUDE.md 中包含这些文件的列表及简要描述，指示 Claude 决定哪些文件相关并在开始工作前阅读它们。 ### D. 指针优于副本 尽可能不要在这些文件中包含代码片段，它们会很快过时。相反，应包含 file:line 引用以指向权威上下文。 ```mermaid graph TD A[CLAUDE.md 主文件] -->|引用| B[agent_docs/] B --> C[构建文档] B --> D[测试文档] B --> E[代码规范] B --> F[架构文档] C -->|file:line 引用| G[实际代码文件] D -->|file:line 引用| G E -->|file:line 引用| G F -->|file:line 引用| G ```  ## 4. Claude 不是昂贵的 linter ### A. 常见错误 最常见的做法之一是在 CLAUDE.md 中放入代码风格指南。 ### B. 问题分析 - LLM 相比传统 linter 和 formatter 昂贵且缓慢 - 代码风格指南会添加大量指令和大多不相关的代码片段 - 降低 LLM 性能和指令跟随能力，占用上下文窗口 ### C. 正确做法 - 始终在可能时使用确定性工具 - LLM 是上下文学习者，会倾向于遵循现有代码模式和约定 - 可以设置 Claude Code Stop 钩子运行 formatter 和 linter - 创建包含代码指南的斜杠命令 ### D. 推荐工具 使用可以自动修复问题的 linter（如 Biome），仔细调整规则以实现最大（安全）覆盖。 ## 5. 避免自动生成 ### A. 高杠杆点 CLAUDE.md 进入每个会话，是框架的最高杠杆点之一。 ### B. 影响层次 - 一行不良代码只是一行不良代码 - 实施计划中的一行不良代码可能创建大量不良代码 - 研究中的一行不良代码可能误解系统工作方式，导致计划中的大量不良行 - CLAUDE.md 影响工作流程的每个阶段和每个工件 ### C. 杠杆作用分析 ```mermaid graph LR A[CLAUDE.md] -->|影响| B[研究阶段] A -->|影响| C[计划阶段] A -->|影响| D[实施阶段] B -->|产生| E[研究文档] C -->|产生| F[实施计划] D -->|产生| G[代码变更] E -->|指导| F F -->|指导| G ```  ### D. 建议 不要使用 /init 或自动生成 CLAUDE.md，应该仔细 crafting 其内容以获得最佳结果。 # 六、最佳实践总结 ## 1. 核心要点 - CLAUDE.md 用于将 Claude 接入代码库，应定义项目的 WHY、WHAT 和 HOW - 少即是多，应包含尽可能少的合理指令 - 保持内容简洁且普遍适用 - 使用渐进式信息披露，告诉 Claude 如何找到重要信息 - Claude 不是 linter，应使用 linter 和代码 formatter - CLAUDE.md 是框架的最高杠杆点，避免自动生成 ## 2. 实施建议 - 仔细考虑放入的每一行内容 - 使用单独的文档文件存储任务特定信息 - 优先使用 file:line 引用而非代码副本 - 利用钩子和斜杠命令处理特定任务 - 保持文件简短（少于 60 行理想） ## 3. 常见陷阱 - 塞入过多命令和指令 - 包含不普遍适用的代码风格指南 - 自动生成而不仔细审查 - 忽略渐进式信息披露原则 - 将 CLAUDE.md 作为行为热修复机制 # 七、实际应用建议 ## 1. monorepo 项目 在 monorepo 中，CLAUDE.md 尤为重要。应该： - 说明有哪些应用 - 说明有哪些共享包 - 说明每个部分的用途 - 帮助 Claude 知道在哪里查找内容 ## 2. 验证方法 告诉 Claude 如何验证其变更： - 如何运行测试 - 如何执行类型检查 - 如何执行编译步骤 ## 3. 工具链集成 - 使用 bun 而非 node 等特定工具 - 项目特定的构建命令 - 自定义脚本和工具 # 八、进阶技巧 ## 1. 钩子机制 使用 Claude Code 的 Stop 钩子： - 在每次变更时运行 formatter 和 linter - 将错误呈现给 Claude 进行修复 - 实现代码质量自动化 ## 2. 斜杠命令 创建专用斜杠命令： - 包含代码指南 - 指向版本控制中的变更 - 指向 git status - 分离实施和格式化 ## 3. 文档组织 ``` project_root/ |- CLAUDE.md（主文件，<60 行） |- agent_docs/ |- building_the_project.md |- running_tests.md |- code_conventions.md |- service_architecture.md ``` # 九、案例对比 ## 1. 不良示例 ``` # CLAUDE.md - 过于冗长 ## 项目概述 这是一个使用 React、TypeScript、Node.js、MongoDB、Redis、 Kubernetes、Docker... 的项目... ## 代码风格 - 使用 2 空格缩进 - 使用单引号 - 函数名使用 camelCase - 类名使用 PascalCase - 常量使用 UPPER_SNAKE_CASE ...（100 行代码风格指南） ## 数据库模式 - users 表包含... - orders 表包含... ...（50 行数据库模式） ## API 端点 - GET /api/users... - POST /api/orders... ...（80 行 API 文档） ``` ## 2. 良好示例 ``` # CLAUDE.md - 简洁有效 ## 项目概述 E-commerce 平台，前端使用 React + TypeScript， 后端使用 Node.js + Express，数据存储为 MongoDB。 ## 项目结构 - frontend/：React 前端应用 - backend/：Node.js API 服务 - shared/：共享类型定义 - infra/：Kubernetes 配置 ## 如何运行 详见 agent_docs/building_the_project.md ## 测试 详见 agent_docs/running_tests.md ## 架构 详见 agent_docs/service_architecture.md ``` *** ## 参考资料 1. [Writing a good CLAUDE.md](https://www.humanlayer.dev/blog/writing-a-good-claude-md) 最后修改：2026 年 01 月 16 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏