超越Plan模式：AI工程制度如何提升开发效率

许多团队在初次使用Claude Code时，已掌握不让其直接编写代码的技巧。他们首先进入Plan模式，分析方案并确认后再执行。这种方法比直接编写代码更可靠。

然而，问题并未完全解决。Plan模式只能确保两点：AI先思考并生成方案，确认后再执行。但该模式无法天然保证方案符合业务边界、技术决策和目录结构，更无法确保不触及架构红线。

例如，在真实的前后端项目中，AI在Plan阶段可能误判方向：

• 新接口应置于auth-service还是backend？
• 公共日志能力应放在services/log-service，还是packages/shared-logging？
• 前端页面应归入apps/web，还是新增一个应用？
• 服务间能否直接共享数据库？
• Controller是否允许直接操作Prisma？
• 请求参数校验，应写在Controller还是DTO里？
• 新增模块是否需要同步进行API契约审查？

若这些判断仅存在于资深成员脑中，AI在Plan模式下也会迷茫。因此，会出现一种更隐蔽的返工：AI并非代码错误，而是方案从一开始就偏离方向；并非不会执行，而是不知项目真实边界。

因此，核心问题并非AI能否写代码，而是如何让AI在正确约束下编写代码。

高效治理：将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分层封装旨在统一处理认证、错误、缓存和接口契约”，AI便能理解：无接口请求的页面，无需创建service。

2. 规则变化时，缺乏依据

假设团队未来要更换状态管理方案。如果只有skill里写了具体步骤，修改会混乱：这个skill里是旧方案，那个模板也是旧方案，某Agent的说明仍保留旧方案。但若技术决策明确记录“当前方案、选择原因、应用场景、例外情况”，后续演进时就能先改决策，再同步rules和skills，逻辑清晰。

决策层如何拆解？

建议将决策文件拆分明细，而非只写一个庞大的“项目规范”。对于通用前后端项目，可拆为5类决策文件：

拆分开来后，AI在处理不同任务时能更精准加载上下文。例如：改前端页面，重点看FRONTEND-DECISIONS和FRONTEND-BUSINESS-DECISIONS；改后端接口，重点看DECISIONS和BACKEND-BUSINESS-DECISIONS；改跨端流程，重点看BUSINESS-DECISIONS和前后端业务决策；做安全审查，则重点看认证、Token、权限、日志相关决策。这比一个数千行的“大规范文档”更易维护和执行。

决策文件推荐写法

决策文件不应只写结论。推荐使用以下结构：

### 编号: 决策标题
**状态**: 已采纳 / 待治理 / 待实现
**决策**:
- 做什么
- 采用什么方案
- 哪些边界已经明确
**为什么**:
- 为什么选这个方案
- 为什么不选其他方案
- 这个方案解决什么问题
**边界约束**:
- 禁止什么
- 必须什么
- 哪些情况需要后续补充决策

这种格式有三个优势：人能快速理解背景，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知道边界。

技术决策无需全部展开，抓住重点即可

技术决策容易写得过细，如技术栈、目录结构、接口封装、异常处理、缓存策略等。但在文章中无需全部展开，用清单说明核心方向即可：

决策确立后，后三层才有依据

决策层确定方向后，后三层才有依据。例如决策层写明“采用Monorepo多微服务架构，前端放apps/web，认证服务放services/auth-service……”，那么rules可翻译为具体规则：“新增前端应用必须放在apps/目录，新增后端服务必须放在services/目录，服务间不得直接访问彼此数据库”。agents可定义不同角色职责，“frontend-developer负责apps/web下的页面和组件，backend-architect负责services下的服务边界”。skills则可落地为标准化步骤：“新增后端接口时，先判断接口所属服务，再在对应目录下创建Module、Controller、Service、DTO……”。如此，一条决策就能从“方向”一路传导至“执行”。

决策文件完成后，Claude如何加载？

决策文件拆好后，还需在CLAUDE.md中建立引用关系。否则这些文件只是项目中的文档，AI不一定每次都会主动读取。

这里有一个常见误区：在CLAUDE.md中写“决策文档索引”，不代表Claude会自动读取这些文档的全文。例如只写“技术决策见.claude/FRONTEND-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. 将团队经验转化为项目资产
过去许多经验存在于资深成员脑中：“这个接口不能这么改”“这个组件不能直接调接口”“Token不能放localStorage”“数据库异常不能直接返回前端”……现在这些经验可沉淀到决策文件、rules、agents和skills里，新人能看，AI也能执行。

3. 将Review前移
传统方式是代码写完后再Review，发现问题再返工。有了这套治理体系后，变为写代码前先加载决策和规则，按角色和流程执行，生成时即尽量符合规范。它不能替代人工Review，但能大幅减少低级返工。

总结

Claude Code的真正价值，不仅在于辅助编程，更在于：

上篇主要阐述了第一层：决策层。业务决策告知AI系统边界，技术决策明确架构方向，rules将决策转化为具体规则，agents将任务交给合适角色，skills将高频动作标准化。

核心总结：先建立制度，再让AI执行。

不过，这里会出现一个常见问题：技术决策里写了页面拆分方式，skill里也写了页面创建流程；技术决策里写了API需封装，skill里也写了请求要走service。那么技术决策和skill是否重复？这正是下篇要重点讨论的内容。