上篇：不要只让 AI 进入 Plan 模式，要先给 AI 一套工程制度
这两篇文章的核心目的只有一个：通过业务决策和技术决策，让我们向 AI 提需求时，AI 在 Plan/决策阶段就能更精准。
AI 写代码并不难，难的是让 AI 在一开始做方案时，就知道项目的业务边界、技术边界和执行流程。
这篇是上篇，主要讲为什么要把业务决策和技术决策沉淀下来，以及它们如何帮助 AI 更准确地做方案。
下篇会继续讲：技术决策、rules 和 skills 到底怎么分工，避免文档越写越多，AI 反而越容易混乱。
一、为什么有了 Plan 模式，还是会反复返工？
很多团队刚开始用 Claude Code 时，已经不会直接让 AI 上来就写代码了。
更常见的流程是这样的：
1我说需求 2 ↓ 3AI 进入 Plan 模式，先分析方案 4 ↓ 5我确认方案 6 ↓ 7AI 开始实现 8 ↓ 9我 Review 发现：方案本身不符合项目规范 10 ↓ 11重新调整方案 12 ↓ 13再次确认 14 ↓ 15再实现 16
这比“直接让 AI 写代码”已经好很多。
但问题并没有完全解决。
因为 Plan 模式只能保证：
1AI 会先想一想。 2AI 会先给一个方案。 3AI 会等你确认后再动手。 4
它不能天然保证：
1这个方案一定符合你的业务边界。 2这个方案一定符合你的技术决策。 3这个方案一定符合你的目录结构。 4这个方案一定不会越过已有架构红线。 5
比如一个真实前后端项目里，AI 在 Plan 阶段就可能问错方向：
- 新接口应该放
auth-service，还是backend？ - 公共日志能力应该放
services/log-service，还是packages/shared-logging？ - 前端页面应该放
apps/web，还是新建一个应用？ - 服务间能不能直接共享数据库？
- Controller 能不能直接操作 Prisma？
- 请求参数校验应该写在 Controller 里，还是 DTO 里？
- 新增模块需要同步 API 契约审查吗？
如果这些判断只存在团队成员脑子里，AI 在 Plan 模式里也不知道。
于是就会出现另一种更隐蔽的返工：
1AI 不是代码写错了。 2而是方案一开始就偏了。 3 4AI 不是不会执行。 5而是不知道项目真正的边界。 6
所以真正要解决的问题不是：
要不要让 AI 先进入 Plan 模式？
而是：
AI 进入 Plan 模式之前，能不能先加载一套项目制度，让它从一开始就在正确边界里规划。
二、我的做法：把 Claude Code 分成四层治理
我把 Claude Code 的项目配置理解成四层：
1决策层：说明为什么这么做 2 ↓ 3规则层：说明具体必须怎么做 4 ↓ 5角色层：说明谁来做 6 ↓ 7流程层：说明按什么步骤做 8
对应到项目文件，大致是：
1DECISIONS / BUSINESS-DECISIONS → 决策层 2rules/ → 规则层 3agents/ → 角色层 4skills/ → 流程层 5
如果用一个更通俗的比喻：
1决策文件像公司战略和技术方案 2rules 像团队制度 3agents 像不同岗位的人 4skills 像办事流程手册 5
这四层组合起来，AI 就不再是“自由发挥”，而是在一套项目制度里工作。
三、为什么第一层必须是“决策”？
很多人一开始会直接写 rules 或 skills。
比如：
1禁止页面直接调用 axios。 2创建页面时必须创建 index、store、constant、style。 3Controller 不允许直接操作数据库。 4
这些规则当然有用。
但如果只有规则，没有决策，AI 只知道“必须这样做”，却不知道“为什么必须这样做”。
这会带来两个问题。
1. 遇到新场景时 AI 不知道怎么判断
比如 rules 里写：
1页面请求必须走 service。 2
但遇到一个非常简单的静态页面，AI 可能会问：
1这个页面没有接口，还要不要建 service？ 2
如果决策层写清楚了：
1API 分层封装是为了统一处理认证、错误、缓存和接口契约。 2没有接口请求的页面不需要创建 service。 3
AI 就知道怎么判断边界。
2. 规则变化时没有依据
比如团队以后想把某个状态管理方案换掉。
如果只有 skill 里写了具体步骤，改起来就会很乱：
1这个 skill 里写了旧方案。 2那个模板里也写了旧方案。 3某个 Agent 说明里还写了一遍旧方案。 4
但如果技术决策里明确记录：
1当前状态管理方案是什么？ 2为什么选它？ 3哪些场景必须用？ 4哪些场景不需要用？ 5
后续演进时，就能先改决策，再同步 rules 和 skills。
四、决策层应该怎么拆？
我更推荐把决策文件拆清楚，而不是只写一个很大的“项目规范”。
一个通用前后端项目，可以拆成 5 类决策文件：
1BUSINESS-DECISIONS.md 2FRONTEND-BUSINESS-DECISIONS.md 3BACKEND-BUSINESS-DECISIONS.md 4FRONTEND-DECISIONS.md 5DECISIONS.md 6
它们分别解决不同问题。
| 文件 | 解决的问题 | 典型内容 |
|---|---|---|
| BUSINESS-DECISIONS | 全局业务边界 | 系统定位、业务事实源、前后端职责 |
| FRONTEND-BUSINESS-DECISIONS | 前端业务职责 | 页面边界、展示缓存、交互校准 |
| BACKEND-BUSINESS-DECISIONS | 后端业务职责 | 服务边界、数据归属、一致性规则 |
| FRONTEND-DECISIONS | 前端技术方案 | 技术栈、页面拆分、状态管理、API 封装 |
| BACKEND-DECISIONS | 后端技术方案 | 服务拆分、认证、数据库、异常、缓存 |
拆开之后，AI 在处理任务时能更精准地加载上下文。
比如：
1改前端页面 → 重点看 FRONTEND-DECISIONS + FRONTEND-BUSINESS-DECISIONS 2改后端接口 → 重点看 DECISIONS + BACKEND-BUSINESS-DECISIONS 3改跨端流程 → 重点看 BUSINESS-DECISIONS + 前后端业务决策 4做安全审查 → 重点看认证、Token、权限、日志相关决策 5
这比一个几千行的“大规范文档”更容易维护，也更容易让 AI 执行。
五、决策文件推荐写法
决策文件不要只写结论。
更推荐使用下面这种结构：
1### 编号: 决策标题 2 3**状态**: 已采纳 / 待治理 / 待实现 4 5**决策**: 6- 做什么 7- 采用什么方案 8- 哪些边界已经明确 9 10**为什么**: 11- 为什么选这个方案 12- 为什么不选其他方案 13- 这个方案解决什么问题 14 15**边界约束**: 16- 禁止什么 17- 必须什么 18- 哪些情况需要后续补充决策 19
这种格式有三个好处：
- 人能快速看懂背景；
- AI 能知道哪些是硬约束；
- 后续架构变化时有依据可查。
六、一个完整决策案例就够了
文章里不需要把所有决策都展开。
读者真正需要先理解的是：决策文件长什么样，以及它为什么能约束 AI。
所以完整案例保留一个就够了。
🏗️ 架构与系统边界决策
ADR-001: 采用 Monorepo 多微服务架构
状态: ✅ 已采纳
决策:
- Monorepo 单仓库管理多个独立微服务。
apps/web/: 前端应用。services/auth-service/: 认证授权服务。services/backend/: 主业务服务。services/log-service/: 日志服务。packages/shared-logging/: 跨系统共享日志 SDK。
为什么:
- 微服务可以独立部署、独立扩展。
- 共享代码通过
packages/目录统一管理。 - 每个服务有明确职责边界，符合单一职责原则。
边界约束:
- 新增系统必须放入对应目录：
apps/、services/或packages/。 - 服务间通过 HTTP API 调用，不直接共享数据库。
- 共享包只能放通用能力，不能反向依赖具体业务服务。
这个案例看起来只是目录和服务拆分，但它会影响很多后续执行：
1创建前端页面时：应该放到 apps/web。 2创建认证接口时：应该放到 services/auth-service。 3创建主业务接口时：应该放到 services/backend。 4创建日志 SDK 时：应该放到 packages/shared-logging。 5服务通信时：应该通过 HTTP API，而不是直接共享数据库。 6
这就是决策层的价值。
它不是为了把文档写厚，而是为了让 AI 知道边界。
七、技术决策不需要全部展开，抓重点即可
技术决策很容易写得很细，比如技术栈、目录结构、接口封装、异常处理、缓存策略等。
但在文章里没必要全部展开。
可以用清单说明：
| 方向 | 决策重点 |
|---|---|
| 前端页面 | 页面怎么拆、状态放哪、请求放哪 |
| 前端组件 | 什么是通用组件，什么是页面私有组件 |
| 前端 API | 是否允许页面直接请求接口，错误在哪里统一处理 |
| 后端分层 | Controller、Service、DTO 各自负责什么 |
| 后端数据 | 能不能直接返回数据库实体，敏感字段怎么过滤 |
| 安全认证 | Token 放哪、权限谁校验、日志不能打印什么 |
这里想表达的核心观点是：
技术决策不是为了炫技术，而是为了告诉 AI：代码应该放在哪里，边界不能越到哪里。
八、有了决策之后，后面三层才有依据
决策层定方向之后，后面三层才有依据。
1决策层：为什么这么做 2rules：具体必须怎么做 3agents：谁来做 4skills：按什么步骤做 5
比如决策层写：
1采用 Monorepo 多微服务架构。 2前端放 apps/web。 3认证服务放 services/auth-service。 4主业务服务放 services/backend。 5日志能力放 services/log-service 或 packages/shared-logging。 6服务之间通过 HTTP API 通信，不直接共享数据库。 7
rules 可以翻译成：
1新增前端应用必须放在 apps/ 目录。 2新增后端服务必须放在 services/ 目录。 3跨系统共享能力必须放在 packages/ 目录。 4服务间不得直接访问彼此数据库。 5服务间通信必须通过明确的 API 契约。 6
agents 可以定义：
1frontend-developer 负责 apps/web 下的页面和组件。 2backend-architect 负责 services 下的服务边界、Controller、Service、DTO。 3api-contract-reviewer 负责检查服务间 API 契约是否清晰。 4security-auditor 负责检查认证、权限和跨服务调用风险。 5
skills 可以落成步骤：
1新增后端接口时： 21. 先判断接口属于 auth-service、backend 还是 log-service。 32. 在对应服务目录下创建 Module、Controller、Service、DTO。 43. 通过 DTO 定义请求和响应结构。 54. 如需跨服务调用，走 HTTP API，不直接访问对方数据库。 65. 最后执行后端检查清单和接口契约审查。 7
这样一条决策就能从“方向”一路传导到“执行”。
九、决策文件写好了，Claude 怎么加载？
决策文件拆好之后，还差最后一步：在 CLAUDE.md 里建立引用关系。
否则这些文件只是放在项目里的文档，AI 不一定每次都会主动读取。
更稳的做法是：
1CLAUDE.md 2 ↓ 3引用业务决策和技术决策文件 4 ↓ 5Claude 启动时先知道这些决策文件在哪里 6 ↓ 7Plan 阶段遇到相关问题时，先读取对应决策再做方案 8
比如可以在 CLAUDE.md 里加一段决策索引。
下面是一个简化后的写法示例。
1## 决策文档索引 2 3- 后端架构决策：`.claude/DECISIONS.md` 4 - 认证安全、数据库规范、微服务边界、异常处理等。 5 6- 前端架构决策：`.claude/FRONTEND-DECISIONS.md` 7 - 技术栈、状态管理、页面拆分、路由、API 封装、样式方案等。 8 9- 前端业务决策：`.claude/FRONTEND-BUSINESS-DECISIONS.md` 10 - 前端职责、页面边界、登录体验、缓存边界、交互规则等。 11 12- 后端业务决策：`.claude/BACKEND-BUSINESS-DECISIONS.md` 13 - 服务边界、认证规则、用户资料、内容规则、数据一致性等。 14
这样写的重点不是把所有决策内容都塞进 CLAUDE.md，而是让它成为一个清晰的入口。
举个例子，用户提需求时可能只说：
1帮我新增一个文章详情页，并支持点赞。 2
如果没有这个索引，AI 可能直接开始设计页面和接口。
但有了这个索引之后，AI 在 Plan 阶段就应该先判断：
1这是前端页面需求 → 先看 FRONTEND-DECISIONS。 2涉及文章展示和点赞 → 再看 FRONTEND-BUSINESS-DECISIONS。 3涉及点赞结果是否生效 → 还要看 BACKEND-BUSINESS-DECISIONS。 4
这样它就会知道：
1前端只负责展示和交互。 2点赞结果必须以后端返回为准。 3页面不能自己用本地状态裁决业务结果。 4
这才是决策索引的价值：不是替代决策文件，而是在关键任务开始前，提醒 AI 先找到正确的决策依据。
十、这套体系真正解决了什么？
1. 减少 AI 自由发挥
AI 最大的问题不是不会写，而是太会发挥。
它经常会自己补设计、自己选目录、自己改结构。
四层治理的作用，就是把发挥空间收住：
1该放哪，提前规定。 2该怎么写，提前规定。 3谁来做，提前规定。 4做几步，提前规定。 5
2. 把团队经验变成项目资产
过去很多经验都在资深同学脑子里：
1这个接口不能这么改。 2这个组件不能直接调接口。 3这个字段前后端都要同步。 4这个命令不能全局跑。 5这个逻辑应该放 Service。 6Token 不能放 localStorage。 7数据库异常不能直接返回前端。 8
现在这些经验可以沉淀到：
1BUSINESS-DECISIONS 2FRONTEND-BUSINESS-DECISIONS 3BACKEND-BUSINESS-DECISIONS 4FRONTEND-DECISIONS 5DECISIONS 6rules 7agents 8skills 9
这样新人能看，AI 也能执行。
3. 把 Review 前移
传统方式是：
1代码写完 2 ↓ 3Review 发现问题 4 ↓ 5返工 6
有了 Claude Code 治理体系后，更像是：
1写代码前先加载决策和规则 2 ↓ 3按角色和流程执行 4 ↓ 5生成时就尽量符合规范 6
它不能替代人工 Review，但可以减少很多低级返工。
十一、总结
Claude Code 真正有价值的地方，不只是“帮我写代码”。
更重要的是：
当我们向 AI 提需求时，它能带着业务决策和技术决策一起思考，从而在 Plan/决策阶段就更精准。
上篇主要讲了第一层：决策层。
1业务决策：告诉 AI 系统边界是什么。 2技术决策：告诉 AI 架构方向是什么。 3rules：把决策翻译成具体规则。 4agents：把任务交给合适角色。 5skills：把高频动作变成标准流程。 6
一句话总结：
不要只让 AI 进入 Plan 模式，要先让 AI 带着项目制度去规划。
不过，到这里会出现一个很常见的问题：
1技术决策里写了页面怎么拆。 2skill 里也写了页面怎么创建。 3 4技术决策里写了 API 要封装。 5skill 里也写了请求要走 service。 6 7那技术决策和 skill 到底是不是重复了？ 8
这就是下篇要重点聊的问题：
技术决策定方向，rules 定红线，skills 定步骤。三者边界如果划不清，文档越写越多，AI 反而越容易混乱。
