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