六、CLAUDE.md项目文档化实战

一、CLAUDE.md 的工作原理

CLAUDE.md 是给 Claude Code 的指令文件，类似于一个"项目规范书"。Claude 在每次对话开始时会自动读取这些文件，将内容作为上下文来指导自己的行为。

通俗地说，CLAUDE.md 就是你在项目中给 Claude 写的一份工作手册——告诉它这个项目是什么、遵循什么规范、有哪些注意事项，让它每次都能以符合项目要求的方式工作，而不是每次对话都重新解释。

• CLAUDE.md≈ 给Claude的.editorconfig+项目规范文档
• 就像 .eslintrc 告诉 ESLint 如何工作，CLAUDE.md 告诉 Claude 如何编码

Claude Code 会从多个位置加载 CLAUDE.md，不同位置的文件作用范围不同。当Claude Code 启动时，会按照固定的层级顺序加载 CLAUDE.md 文件，并将其内容注入到系统提示词（system prompt）中。加载顺序如下：

当多个位置都存在 CLAUDE.md 时，Claude Code 会将它们全部加载并合并，优先级从高到低依次为：

项目本地 → 项目根目录 → 子目录 → 全局用户级

项目根目录的 CLAUDE.md 建议提交到 git，让整个团队共享同一套 AI 工作规范。个人偏好（如不喜欢加分号）放在 .claude/CLAUDE.md 中并加入 .gitignore，不影响他人。

三、CLAUDE.md工程实战

3.1 快速创建 CLAUDE.md

最简单的方式是让 Claude Code 自动生成初始版本。在项目目录中启动 Claude Code 后，执行：

/init# 可以在项目目录中手动创建# touch CLAUDE.md

Claude Code 会分析你的项目结构、代码风格、已有配置文件（如 package.json、pyproject.toml、.eslintrc 等），自动生成一份符合项目实际情况的 CLAUDE.md。但是，Claude 起草的"项目概述"大概率是泛泛的——比如"这是一个 Next.js 项目"，你需要在此基础上补充和调整。

3.2 CLAUDE.md文件内容结构

CLAUDE.md 是一个普通的 Markdown 文件，没有强制的格式要求，但良好的结构能帮助 Claude 更快找到关键信息。以下是推荐的内容结构：

1 项目名称：一句话说明这个项目是什么，方便 Claude 快速定位项目性质。2 技术栈：核心技术和版本,越具体越好3 常用命令：开发、测试、构建的命令4 项目结构：帮助 Claude 快速定位文件，减少不必要的目录扫描5 编码规范：代码风格和约定，确保生成的代码与现有代码库风格一致6 重要约束：禁止的操作,附原因7 业务背景：帮助 AI 理解业务逻辑

这 7 个部分不是硬性要求——有些项目可能业务背景不重要，有些项目可能没什么约束。但至少前 5 个你都该写。

3.3 CLAUDE.md实战案例

下面是一个关于在线个人简历展示系统的 CLAUDE.md 对比表格，展示了与 AI 协作时差的写法与好的写法之间的差异。

通过具体、精确的技术描述替代模糊、口语化的表达，帮助 AI 准确理解项目边界、技术约束与代码规范，从而生成符合预期的代码与方案。

请您顺手点下右下角的“推荐”，方便您收到更多精彩内容。每周一、周三和周六更新。