CLAUDE.md 怎么写？Claude Code 项目配置文件完整指南

如果你经常让 Claude Code 读项目、改代码或运行测试，CLAUDE.md 往往比一段很长的临时提示词更值得维护。它可以被理解成项目给 AI 助手准备的“入场说明书”，帮助工具快速知道项目怎么启动、哪些文件重要、哪些约定不能违反。

但 CLAUDE.md 不是越长越好，也不是把所有背景资料都塞进去。好的文件应该短、准、可执行，并且只写真正稳定、反复有用的规则。下面从文件位置、内容结构到维护流程，整理一套适合中文开发者的写法。

CLAUDE.md 适合解决什么问题

模型第一次进入一个陌生仓库时，通常不知道以下信息：

• 项目使用哪个运行时、包管理器和启动命令。
• 源代码、测试、文档和构建产物分别位于哪里。
• 修改某类文件前必须运行哪些检查。
• 团队使用什么命名、格式化和提交约定。
• 哪些目录或文件包含敏感内容，不能读取或修改。

这些内容如果每次都临时说明，容易遗漏；如果写在 CLAUDE.md 中，就能成为每次任务的共同起点。它尤其适合多成员协作、经常更换 AI 工具，或需要让新同事快速熟悉仓库的项目。

文件应该放在哪里

最简单的做法是在项目根目录创建 CLAUDE.md。根目录文件适合放整个仓库通用的信息，例如安装、开发、测试和构建命令。

当项目包含多个独立模块时，可以在模块目录再放一份更具体的说明。例如前端、后端和脚本目录的测试方式可能不同，这时可以让根目录文件记录共通规则，子目录文件只写模块差异。

建议先确认当前 Claude Code 版本对层级文件、个人规则和项目规则的读取方式，再决定目录结构。不要因为网上某篇旧教程写了一个路径，就默认所有版本和客户端都完全一致。

一份实用的 CLAUDE.md 结构

下面的结构可以作为起点，按实际项目删减：

# 项目名称

## 项目简介
- 一句话说明项目解决什么问题
- 主要技术栈和运行环境

## 目录说明
- `src/`：业务源码
- `tests/`：自动化测试
- `docs/`：项目文档

## 常用命令
- 安装依赖：`npm install`
- 本地开发：`npm run dev`
- 测试：`npm run test`
- 构建：`npm run build`

## 开发约定
- 修改前先定位相关文件和调用链
- 保持现有命名和格式化风格
- 不修改生成目录和锁文件，除非任务明确要求

## 验收要求
- 修改后查看 diff
- 运行与改动相关的测试
- 报告未验证的部分和已知风险

## 安全边界
- 不读取或输出 `.env`、令牌和客户数据
- 不执行删除、发布和生产操作，除非得到明确确认

关键不是照搬模板，而是把命令和目录换成项目真实情况。不存在的命令不要写进去，已经失效的规则也要及时删除。

常用内容怎么写才有效

把描述改成动作

“代码质量要高”对模型帮助有限；“修改 TypeScript 后运行 npm run check，不要跳过类型错误”更容易执行。规则最好包含对象、动作和验收方式。

写清楚修改范围

可以明确“只修改 src/ 和测试文件”“不要手动编辑 dist/”“涉及数据库结构时先给出迁移计划”。范围越清楚，代理误改文件的概率越低。

说明事实，不写猜测

开发命令、部署平台、环境变量名称和目录结构都应以仓库当前状态为准。版本变化后要同步更新，不能把临时排错结论写成永久规则。

把验证放在规则旁边

如果某个模块有专门测试，直接写出测试命令和通过标准。这样 Claude Code 不仅知道“要改什么”，也知道“怎么证明改对了”。

哪些内容不应该写进去

不要把 API Key、数据库密码、客户资料、内部域名或生产环境连接信息写入 CLAUDE.md。这个文件通常会进入代码仓库，敏感内容不应因为方便上下文而扩大暴露范围。

也不要把一整套产品需求、几十页接口文档或每次任务的临时指令都堆在里面。过长的说明会稀释真正重要的规则，还可能和代码现状发生冲突。详细资料可以放在文档目录，并在需要时通过明确的路径引用。

如何从零生成和维护

第一次创建时，可以让 Claude Code 先只读项目：

请先阅读项目的 package.json、README 和目录结构，只输出一份项目地图。
不要修改文件，不要读取 .env、密钥或客户数据。
列出开发、测试和构建命令，并标记你无法确认的内容。

人工核对项目地图后，再要求它生成初稿。提交前重点检查命令是否能运行、路径是否存在、规则是否与现有脚本冲突，以及是否意外包含敏感信息。

日常维护可以在每次大版本升级、目录重构或测试命令改变后进行。把 CLAUDE.md 当成代码一样参与评审，而不是创建一次就永远不管。

CLAUDE.md 与临时提示词怎么配合

CLAUDE.md 适合稳定的项目背景和长期约定，临时提示词适合本次任务的目标、范围、输入和验收标准。两者配合时，临时任务不应悄悄推翻安全规则；如果确实需要改变约定，应该明确说明原因并在完成后更新项目文档。

一个清晰的任务提示可以包含：目标文件、禁止触碰的范围、预期行为、测试命令和输出格式。更多任务拆解方法可以参考Claude Code 中文教程以及Claude Code 故障排查清单。

需要 API 或开发工具接入时

如果你的工作流需要把 Claude 或其他模型接入编辑器、脚本或自建应用，可以了解 ZeoAPI。它是独立第三方 API 网关，不是 Anthropic 官方 API；模型可用性、费率、数据处理方式和服务条款应以其控制台及文档为准。无论选择哪种渠道，生产密钥都应放在环境变量或密钥管理服务中。

结论

CLAUDE.md 的价值在于让项目规则可见、可复用、可验证。先写最重要的目录、命令、安全边界和验收方式，再随着项目变化维护；不要把它写成夸张的“万能提示词”，也不要让它承担代码审查和权限控制的职责。