TRAE-AI编程
你给 Claude Code 下了个"帮我加个登录功能"的指令，它却从头把项目结构问了一遍，还把数据库字段猜错，写了半天全得返工。问题往往不在模型，而在你没把项目背景告诉它。核心答案很简单：写一份好的 CLAUDE.md，把项目上下文、技术栈和协作规矩一次性喂给 AI，它就能从"每次重新认识你"变成"闭眼都懂你"。本文给你 3 种 CLAUDE.md 的写法，从最简的"项目说明书"到带自定义指令的结构化版本，并附上验证步骤。看完你就能写出一份让 AI 更懂你项目的配置。
先看结论
三种写法由浅入深，先选最贴合你当前阶段的那种，别一上来就追求大而全。
| 写法 | 适合阶段 | 内容重心 | 维护成本 | 收益 |
|---|---|---|---|---|
| 项目说明书式 | 刚接入 AI 编程 | 技术栈与目录约定 | 低 | 快速消除"反复问背景" |
| 指令清单式 | 有固定协作规矩 | 禁止项与步骤顺序 | 中 | 减少越界与返工 |
| 结构化分节式 | 多人 / 多模块 | 角色、环境、边界 | 高 | 大型项目长期可控 |
💡 小提示：
CLAUDE.md不是越厚越好。它要的是"AI 每次都必须知道的硬事实"，而不是把所有文档都贴进去。先翻 Claude Code 编程技能教程 建立基础认知。
一、项目说明书式：先把背景讲清楚
最基础的写法，就是一份给 AI 看的项目简介：用什么语言、目录怎么分、跑起来要什么命令。目标只有一个——让 Claude Code 第一次对话就能正确定位文件，不再到处乱猜。
在你的项目根目录新建 CLAUDE.md：
# 项目背景
这是一个用 FastAPI 写的用户中台，Python 3.11，数据库用 PostgreSQL。
## 目录约定
- `app/` 放接口与业务逻辑
- `tests/` 放 pytest 用例，运行命令 `pytest -q`
- 禁止改动 `migrations/` 下的历史迁移文件
## 常用命令
- 启动：uvicorn app.main:app --reload
- 格式化：ruff format .上面这段就是一份最小可用的项目上下文。它不长，但把"技术栈、目录、命令、红线"四件套都说清了。AI 读完后，再让你加功能就不会先问"这是什么项目"。
⚠️ 注意：命令要写你真的在用的，别照抄教程。写错的命令比不写更糟，AI 会照着你给的错命令去跑。更细的字段可参考 CLAUDE.md 核心技能。
二、指令清单式：把规矩写死
当你的项目有了固定协作习惯，比如"改代码前先给计划""删除操作必须问我"，就该升级成指令清单式。它把软性的团队规矩变成 AI 会遵守的自定义指令。
在 CLAUDE.md 里加一节"协作规则"：
## 协作规则
- 任何写文件动作前，先列出"改哪些文件、为什么"，等我确认。
- 新增接口必须同步补 `tests/` 用例，否则视为未完成。
- 不要修改 `migrations/` 与 `.env`；涉及它们先提问。
- 注释用中文，变量名用英文，保持和现有代码一致。运行边界（未在本机执行，依据官方文档）：当你让 AI 加功能，它会先输出计划再动手；想跳过计划直接改，会被这条规定拦下。这类自定义指令的价值，是把"你每次都要口头交代的话"固化成文件，省掉重复沟通。若你想用别的工具做类似隔离，Trae 插件能力 也提供了角色化思路。
三、结构化分节式：多模块项目的长期方案
项目变大、模块变多后，一份平铺的 CLAUDE.md 会没人愿意维护。结构化分节式按"角色 / 环境 / 边界"组织，并在每个模块下放各自的 CLAUDE.md，让 AI 进入子目录时自动加载对应上下文。
根目录只放总纲，子模块各自补充：
# 总纲
本项目含 `order/`（订单）与 `pay/`（支付）两个子域。
## 各域自述
- 进 `order/` 读 `order/CLAUDE.md`
- 进 `pay/` 读 `pay/CLAUDE.md`
## 全局红线
- 跨域调用必须走 `gateway/`，禁止子域直连。
验证步骤（未在本机执行）：新建子域的 CLAUDE.md 后，进入该目录让 AI 改代码，观察它是否引用了子域专属约定；没引用就说明加载链路没通，需检查文件名与路径。这种分节写法的版本差异在于——老版本只认根目录一份，新版本支持子目录级加载，具体以你装版本为准。更多工程化视角见 AI 编程技能教程。
写之前先想清楚给谁看：CLAUDE.md 不是写给你自己看的日记，而是写给"第一次打开项目、对你毫无背景"的 AI。动笔前先问自己——如果 AI 只看这一份文件，能不能不靠你口头补充就少犯错？能，就说明写得到位；不能，就补齐技术栈、目录边界和那条最容易踩的红线。
四、上线前自检清单
CLAUDE.md 写完后别直接合进主干，先用这张清单核对，避免"写了但 AI 没用上"。
- 是否只留"每次都必须知道"的硬事实？把无关文档整段贴进去，只会稀释重点、拖慢读取。
- 命令是否写你真在用的？写错命令比不写更糟，模型会照着你给的错指令去执行，坑的是你自己。
- 自定义指令是否可验证？挑一条让 AI 做一次，看它是否真的遵守了那条规矩。
- 多模块项目是否用了子目录
CLAUDE.md？只靠根目录一份，子域约定根本加载不到。 - 改完是否开新会话验证过？问一个只有新文档才答得对的问题，确认它真的引用到了。
清单全过，这份配置才算真正生效；任一项存疑，先补再交付。
总结
写 CLAUDE.md 的诀窍是"由薄到厚、由浅入深"：先用项目说明书式消除反复问背景，再用指令清单式把规矩写死减少返工，最后用结构化分节式撑住多模块长期维护。它本质上是一份让 AI 编程助手更懂你项目的上下文资产，越用越值钱。下一步建议从一个真实小项目写起，先薄后厚，别一上来就堆文档。
常见问题
Q：CLAUDE.md 写太长会不会拖慢 AI？
A：会有一点点，但比起每次重新解释背景，这点开销可以忽略。真正该避免的是把无关文档整段贴进去——只留"每次都必须知道"的硬事实即可。
Q：一份 CLAUDE.md 能让多个 AI 工具共用吗？
A：格式通用，但字段侧重不同。Claude Code 认 CLAUDE.md，别的工具可能认别的文件名。可以共用内容、按工具各存一份，别强求单一文件通吃。
Q：改了 CLAUDE.md 要重启会话才生效吗？
A：通常新开一轮对话就会重新读取；部分场景下显式重开会话最稳。验证方法很简单——改完问 AI 一个只有新文档才答得对的问题，看它是否引用到了。
Q：CLAUDE.md 和 README 有什么区别？
A：README 是给人看的工程说明，CLAUDE.md 是给 AI 看的协作契约。两者内容可以相通，但 CLAUDE.md 要更强调"禁止项、步骤顺序、目录边界"这类 AI 会直接照做的硬规则，少写抒情和背景铺垫。
延伸学习
把 AI 协作这套补齐，可以按这个顺序：
- 想直接上手实战项目，TRAE AI 开发实战课程 是边学边练的形式；
- 也看看这篇笔记 Claude Code 多项目打开方法，了解多项目下怎么隔离上下文；
- 想补 Python 基础，Python3 教程 能帮你读懂配置里的代码。
