claude-md

CLAUDE.md 编写指南

核心原则

对每一行都进行以下检验：“删掉这行会导致 Claude 犯错吗？”

如果 Claude 能从代码、README 或标准惯例中推断出来，就删掉它。CLAUDE.md 会在每次会话中加载，占用宝贵的上下文。每一行都要视为有成本。

CLAUDE.md 应包含的内容

只包含没有明确指示时 Claude 会出错的内容：

• Claude 无法猜到的构建／测试／代码检查命令（make test-integration、自定义脚本）
• 不同于语言默认设置或格式化工具配置的代码风格规则
• 特定于此代码库、不明显的注意事项和易踩的坑
• 测试说明——首选的运行工具、必需的设置、测试数据库惯例
• 仓库协作规范——分支命名、PR 惯例、提交消息格式
• 无法从代码结构中显而易见地看出的架构决策
• 开发环境的特殊要求——必需的环境变量、版本固定、本地设置中的陷阱
• 文档指引（@path/to/file），而不是文档副本

不应包含的内容

不要再添加这些内容——它们会浪费每次会话的上下文：

• 项目概述／简要介绍——这些内容应放在 README 中
• 目录树／文件说明——Claude 可以读取文件系统
• 语言的标准惯例——Claude 已经了解
• 代码片段——它们会过时；应改用 @file:line 引用
• API 文档——提供链接，不要粘贴内容
• 通用最佳实践——“编写简洁的代码”毫无帮助
• README 或文档中已有的内容——不要重复已提交的文件
• 经常变化的信息——这些内容会过时并造成误导

结构规则

• 控制在 300 行以内。 越少越好。接近 300 行时要进行审查。
• 使用路由——超过几行的内容应放到 @path/to/detailed-doc.md。
• 将关键规则放在顶部和底部——首因和近因偏差会让中间内容容易被忽略。
• 优先使用正向指示——用“使用命名导出”，而不是“不要使用默认导出”。
• 硬性规则使用钩子——如果规则绝不可违反，就用提交前钩子强制执行，而不是写成文字。

创建新的 CLAUDE.md

1. 先阅读现有 README、文档和代码库结构。
2. 只找出 Claude 容易出错的地方，而不是它能推断出的内容。
3. 检查父级／同级目录中的 CLAUDE.md 文件，避免重复。
4. 编写精简的文件，然后根据这些规则自行审核，再提交给用户。
5. 对于子目录中的 CLAUDE.md 文件：严格限定在该目录相关的事项内。

输出： 呈现草稿并附上行数。先让用户审阅，再写入文件。

编辑现有的 CLAUDE.md

1. 阅读当前文件。
2. 按照这些规则修改，不要添加冗余内容。
3. 验证新内容是否通过检验。
4. 如果文件超过 300 行，指出这一点，并建议删减或拆分到其他文件。

输出： 进行编辑。如果超过 300 行，请指出。

审查现有的 CLAUDE.md

1. 同时阅读该文件，以及可能与之重复的 README 和文档。
2. 逐行应用检验。
3. 给出结论：保留／删除／提取到单独文件（并说明理由）。
4. 对于应保留但过于详细的内容，建议路由方式。
5. 检查行数。

输出： 提供包含结论、当前行数和预计行数的结构化报告。询问用户要应用哪些更改。

助手配置检测

如果 CLAUDE.md 定义了角色或人设（“You are...”、个性、辅导指示、沟通风格），它就是一份助手配置文件——用途完全不同。请指出：“这看起来是 AI 助手配置，而不是项目惯例文件。标准的 CLAUDE.md 规则不适用于此文件。”然后继续执行用户请求，不应用检验；只有结构规则（行数、路由）仍然适用。

不在范围内

• 不是代码检查器 — 此技能旨在引导你的思路，不会自动修复文件。
• 不是模板 — 强调原则，而非僵化的结构。CLAUDE.md 的格式有意保持灵活。
• 不会修改非 CLAUDE.md 文件 — 如果内容应移至 README 或文档文件中，会建议你移动，但不会代为修改。

边界情况

• 文件不存在，但用户要求“审查”： 告知用户，并提出可以创建文件。
• 存在多个 CLAUDE.md 文件： 操作上下文最相关的文件。如果无法确定，请询问用户。审查时，可提出审查所有文件。
• 用户明确要求采用反模式： 按要求执行，但指出这类内容通常属于 README，而将其放在这里会在每次会话中消耗上下文。用户指令始终优先。
• Monorepo： 检查父级 CLAUDE.md 文件，避免重复继承的指令。

参考资料

• 最佳实践 — 官方的包含/排除表
• CLAUDE.md 文档 — CLAUDE.md 文件的工作方式