CLAUDE.md 指南

编写最佳的 CLAUDE.md

CLAUDE.md 是决定 Claude 如何理解你项目的唯一文件。写得好意味着更少的修正、更好的代码，以及真正了解工作内容的代理。

本指南将带你了解 CLAUDE.md 文件的每个部分，从技术栈声明到代理特定提示。跟着步骤一步步构建你自己的文件。

什么是 CLAUDE.md

CLAUDE.md 是放在项目根目录的 Markdown 文件。当 Claude Code 启动会话时，它会首先读取这个文件。文件中的所有内容都会成为 Claude 的上下文：技术栈、文件结构、团队规范，以及你希望每个代理遵循的具体指令。

可以把它看作简报文档。没有它，Claude 只能猜测项目的组织方式。有了好的 CLAUDE.md，Claude 已经知道文件在哪里、该遵循什么模式、该避免什么。输出质量的差异是显著的。

“在 CLAUDE.md 上投入 10 分钟，可以省去数小时修正不符合项目模式的 AI 生成代码的时间。”

来自数百个 Claude Code 项目的观察

差的 vs. 好的 CLAUDE.md

CLAUDE.md 的结构和具体程度直接影响 Claude 在代码库中的表现。

薄弱的 CLAUDE.md

✗没有具体内容的模糊指令，如「遵循最佳实践」
✗没有文件结构映射，Claude 只能猜测新代码的放置位置
✗缺少编码规范，每次会话的输出风格不一致
✗没有列出构建或测试命令，导致建议无法运行

优秀的 CLAUDE.md

✓带版本号的明确技术栈：React 19、Vite 6、Zustand 5、Tailwind 4
✓清晰的文件映射，展示关键目录及其用途
✓命名模式、错误处理、样式偏好已记录在案
✓构建、测试和开发命令可直接复制运行

6 个必备部分

结构良好的 CLAUDE.md 涵盖这六个方面。每个部分都为 Claude 提供可立即使用的具体信息。

技术栈声明

明确列出你的框架、库及其版本。包括包管理器、Node 版本和任何运行时要求。Claude 使用这些信息生成兼容的代码，无需猜测。

文件结构映射

描述你的关键目录以及每个目录中存放的内容。组件、状态管理、服务、API 路由、类型定义。每个文件夹附带一行说明的简短树状图效果很好。

编码规范

记录你的命名模式（文件用 camelCase，组件用 PascalCase）、错误处理方式、import 排序和项目特定规则。这确保 Claude 的输出与现有代码保持一致。

构建和测试命令

包含你的 dev、build、test 和 lint 命令。当 Claude 需要验证某些功能或建议脚本时，它会使用你项目期望的确切命令。

代理角色提示

如果你使用多个代理（QA、前端、后端、DevOps），添加一个描述每个角色应关注什么的部分。这在 AgentsRoom 的多代理设置中特别有用。

禁止区域

告诉 Claude 不要做什么。不要修改配置文件，不要更改认证系统，不要重构数据库层。明确的边界防止代理做出不必要的改动。

4 步构建你的 CLAUDE.md

不需要一次写完所有内容。从基础开始，在发现 Claude 需要了解的信息时逐步扩展。

审查你的项目

打开 package.json，列出项目使用的所有框架、库和工具。记录版本号，检查运行时要求（Node 版本、Python 版本、数据库）。这将成为你的技术栈部分。

package.json + 运行时版本 + 数据库

映射文件树

快速输出 src 目录的树状结构。识别顶层文件夹，为每个文件夹写一行说明。重点关注组件、状态管理、服务、类型定义和 API 路由的位置。

带用途注释的 src/ 树状图

记录规范

查看现有代码，记录其中的模式：文件命名方式、错误处理方式、import 的组织方式、使用默认导出还是命名导出。将这些写成简短的规则。

命名、import、错误处理、导出

添加代理专属部分

如果你使用专业代理，为每个角色添加关注领域。前端代理应了解你的组件库，DevOps 代理应了解你的部署流程，QA 代理应了解你的测试框架。

按角色划分的关注领域 + 禁止区域

为什么用 AgentsRoom 管理 CLAUDE.md

AgentsRoom 将 CLAUDE.md 作为核心概念构建，而非附加功能。

内置 CLAUDE.md 编辑器

在 AgentsRoom 内直接编辑 CLAUDE.md，支持语法高亮和实时保存。无需切换到文本编辑器或 IDE。

按代理实时预览

实时查看每个代理如何解读你的 CLAUDE.md。通过观察终端输出，验证代理是否遵循你的规范并尊重禁止区域。

按项目独立上下文

AgentsRoom 中的每个项目都有自己的 CLAUDE.md。切换项目时，每个代理自动加载该代码库对应的上下文文件。

代理角色集成

AgentsRoom 的 14 个代理角色与 CLAUDE.md 的部分直接对应。按角色定义关注领域和禁止区域，每个代理只获取针对自己的指令。

Watch what your CLAUDE.md does to Claude Code token usage

CLAUDE.md is prepended to every Claude turn. A bloated CLAUDE.md silently inflates Claude Code token usage on every message. AgentsRoom puts a per-session token meter on each agent so you can see exactly how much your CLAUDE.md is costing you, with a live cache hit rate to confirm it stays cached.

See the Claude Code token usage tracker