# 执行前宣言：先立规约，再写代码——文件创建顺序

> **AI Harness Engineering 系列 · 第七篇** · 王海涛（GitHub：derekwang85 · 腾讯云 TVP / 架构师名人堂）

![00-intro.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/640de7258de8a7b90e554608577d9f98.jpg)

克劳塞维茨在《战争论》里给过一句冷的话：**"作战计划什么都不是，规划却是一切。"** 普鲁士人用了几十年想明白：真正决定一场战役走向的，不是那张画得再漂亮的作战计划，而是战前那一次次推演、那一条条假设的先后顺序。计划在执行中一定会碎掉，但规划让执行者知道自己站在哪、朝哪走、什么时候该停。AI 编码正在犯的，恰恰是跳过了"规划"，直接奔着"计划"里最费劲的那部分去了。

这也正是"磨刀不误砍柴工"的完整意思——人人都知道要磨刀，却很少有人真做对顺序：磨刀永远在砍柴**之前**。反过来就荒谬了：你先砍完三亩地的柴，刀钝得卷了刃，再坐下来磨刀——磨得再亮，柴也已经砍废了。

前面六篇，我们把约束体系的**结构**看完了——五层金字塔，战略、架构、契约、门禁、实现，边界长什么样，一层层叠成一座塔。但结构只回答了"长什么样"，还欠一个问题：**先建什么、再建什么？** 同一个体系的两只眼，前六篇睁开的是"结构"那只，这一篇睁开"顺序"这只。

---

## 一、让 AI 先写代码，是刻进默认里的错误

![01-wrong-default.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/e3c3f55ff6b2787b4189fedf101b71e3.jpg)

现在几乎所有人的用法都一样：打开编辑器，唤出 AI，一句话描述需求，然后看着它哗哗地吐代码。等它写完，你开始 review、改、追着补。

问题不在"让 AI 写代码"这个动作，而在**顺序**——你让 AI 一上来就进入了"砍柴"环节，把"磨刀"（定义边界、钉死决策、立门禁）一股脑推到了后面，甚至永远不做。

AI 编码工具的设计者也没帮你把这关扛下来。它们的默认交互是"prompt 进、代码出"，把"先想清楚"这件事完全交给了你，而且一个字都不催。于是大多数项目长成这样：代码先于约束存在，跑得越来越快，也歪得越来越远。

我早期就是这种用法，代价很具体。一个交易系统项目，我让 AI 直接开写，结果：

- 同一个"订单状态"，前一个 Controller 叫 `OrderStatus`，下一个叫 `Status`，第三个写成了字符串常量；
- 数据库字段今天多一个 `quote_id`，明天 AI"顺手"又在 DTO 里造了个 `quoteNo`，两个字段谁也找不到谁；
- 写到最后，我花在"统一风格、对齐字段"上的时间，比让 AI 重写一遍还多。

这不是 AI 笨。这是**我没告诉它"先建什么、再建什么"**，它只能靠猜。而 AI 猜出来的东西，每次都是"看起来合理、跟上次不一样"。

于是我换了个思路：**不是约束 AI 别乱写，而是规定"文件创建的顺序"，让正确的文件先于代码存在。** 代码反而是最后才出现的东西。

这就是本篇要讲的核心——**Project Anatomy**，一个项目的"解剖学"：一个项目从头长出来，哪些文件先长、哪些后长，是有确定顺序的。顺序对了，AI 是"按蓝图施工"；顺序错了，AI 是"边想边砌"。

---

## 二、四阶段：正确的文件创建顺序

![02-four-phases.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/b2f8e3e751535e233018a7003675200c.jpg)

我把它整理成一张"文件创建序列表"，四个阶段，代码永远殿后：

```
Phase 1 · Manifest（动手前的最后一问）
    └─ Pre-Execution Manifest：WHAT / WHY / APPROACH / FILES / SUCCESS / STOP

Phase 2 · Spec + ADR（钉死"做什么"和"为什么"）
    └─ .spec.md：范围、假设、验收标准
    └─ ADR：每个重大决策一个记录

Phase 3 · Gate（先立门禁，再放 AI）
    └─ 门禁脚本：提交前自动检查，约束的闭环

Phase 4 · Manual + Runbook（边做边沉淀）
    └─ 产品手册：怎么用
    └─ Runbook：怎么跑、怎么部署、怎么回滚

────────────────────────────────────────
实现层 · 代码（N 个文件）—— 永远是最后出现的产物
```

注意这张表读起来有一个反直觉的地方：**前四个 Phase 一个代码文件都没有。** 全是"约束文件"。

这正是整套方法论跟"让 AI 直接写代码"最本质的分野。普通人看到"写一个功能"，第一反应是"写代码"；我第一反应是"先把四个约束文件落下来"。

德鲁克区分过"效率"和"效能"：效率是把事情做对，效能是做对的事情。让 AI 直接写代码，是在**效率**上狂奔——做得飞快；但可能一上来就做错了方向。这四个 Phase 的文件，是在**效能**上踩刹车——先确认"做的到底是不是该做的那件事"。

顺序的价值，恰恰藏在这个反直觉里：**文件不产生一行可运行的代码，但它决定了代码长出来对不对。**

---

## 三、Phase 1：Manifest——动手前的最后一问

![03-manifest.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/dc2e5d362200801b7d35142dd89a2ddd.jpg)

四个 Phase 里，我最先想讲的是第一个，因为它最反人性，也最值钱。

它的名字叫 **Pre-Execution Manifest**——"执行前宣言"。规则很粗暴：**凡是改动超过 3 个文件，或预计耗时超过 30 分钟，动手前必须先写这份宣言。**

它不是废话文档，而是一个有固定格式的"思考外化器"：

| 字段 | 问的问题 |
|------|---------|
| **WHAT** | 我要改什么？（一句话） |
| **WHY** | 为什么改？现在出了什么问题 / 需要什么新能力 |
| **APPROACH** | 怎么改？方案选择、技术路径、不走寻常路的决策 |
| **FILES** | 涉及哪些文件？每个文件做什么改动 |
| **SUCCESS** | 怎么算成功？（可验证的条件） |
| **STOP** | 什么情况该停下？ |

Manifest 的价值，不在于它写得多漂亮，而在于它逼你在**花一小时写代码之前**，先把"为什么、怎么做、怎么算成功"想清楚。写代码是机器的事，回答问题是你的事——Manifest 是把你的脑子，从"跟 AI 抢键盘"里抽出来，挪到"回答这六个问题"上。

我踩过一个坑，最能说明它为什么是"最后一问"：有一次我让 AI 给一个报表接口加缓存，它两分钟写完了，看着完美。结果验收时才发现——那个接口本来就被上游限流了，加缓存是**在错误的地方做正确的事**。如果当时先写 Manifest，`WHY` 那一栏逼我写"因为接口慢"，我立刻会反问自己一句："慢，是因为缓存没加，还是因为上游限流？"——答案一目了然。两分钟的代码，因为省了三分钟的 Manifest，让我搭进去一下午。

Manifest 里最狠的一栏，其实是 `STOP`。它提前规定"什么情况该停下"，等于给 AI（也给跑偏的自己）装了一个**急停按钮**。这跟后面要讲的"门禁"一脉相承——把判断，从"事后后悔"提前到"事前刹车"。

但要诚实说一句：STOP 这一栏是**软约束**——它靠人（或靠 AI 被要求先读它）自律执行，本身不会自动拦住谁。真正会自动执行的硬约束，是后面 Phase 3 的门禁脚本。所以 STOP 的意义，不是"机器会替你刹车"，而是"把刹车的判断提前到动手之前"。

---

## 四、Phase 2：Spec + ADR——把"做什么"钉死

![04-spec-adr.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/4e9317bbf589dae4fe89ca50b4513e4a.jpg)

Manifest 管的是回答了"要不要做、怎么做"，但它是粗粒度的。接下来要把"做什么"钉成白纸黑字。

**Spec（`.spec.md`）** 是范围契约。它必须包含三样东西：**范围**（这次到底做不做这个边界）、**假设**（哪些前提我默认成立）、**验收标准**（做到什么程度算完成）。缺了假设，AI 就会用它的"常识"填补你的空白；缺了验收标准，AI 写完了你也没法说"对"还是"不对"。

**ADR（Architecture Decision Record）** 是决策记录。每个"影响结构"的决定——选哪个库、模块怎么划、接口要不要向后兼容——都单独写成一个文件，记录"为什么这么选、否决了哪些方案、带来什么后果"。

Spec 管"这一次做什么"，ADR 管"这一次为什么"。它们合起来，把 AI 最容易产生"幻觉"和"不一致"的两个地方——**范围**和**决策**——提前焊死。

有个反例我一直记得：我在一个项目里换过消息队列，从 A 换到 B，理由当时在脑子里清清楚楚。半年后新同事问"当初为什么不用 C"，我哑口无言——决策只存在于我一个人的记忆里，我一走，它就蒸发了。ADR 就是为了治这个病：**让"为什么"活得比"谁"更久。**

关于 ADR 怎么写，第三篇已经完整讲过，这里不再展开。这一篇只说顺序：Spec 和 ADR 必须在代码之前落盘，因为它们是代码的"施工图"，而不是代码的"事后解说词"。

---

## 五、Phase 3：Gate——先立门禁，再放 AI

![05-gate-first.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/55088c6ae08a9e2983d750bf73d16bc3.jpg)

这个 Phase 的顺序最容易被忽视：**门禁脚本，要在代码之前写，而不是之后。**

大多数人把"检查"放在最后——代码写完了，跑一遍 lint、跑一遍测试，过关就合并。这当然有用，但它只能**兜住已经发生的错误**。

先立门禁的意义在于：它给了 AI 一个**确定的、可自动验证的靶子**。AI 写代码时，如果它知道"提交前会被这段脚本检查"，它生成的方向就会自动朝"能通过检查"靠拢——这比事后抓错高效一个数量级。

这背后是一个朴素的心理机制，对人、对 AI 都一样：**规则提前立好，行为才会提前对齐；规则事后再定，只能惩罚已经发生的偏差。**

关于门禁怎么设计、怎么从五道演进到 G0-G6 七阶段，我上一篇刚详细讲过，这里只补一个顺序上的提醒：**门禁层是金字塔里唯一会自动执行的一层，没有它，前面所有的约束文件都只是"建议"。** 所以它不能等代码写完再补，必须在放 AI 进场之前就位。

---

## 六、Phase 4：Manual + Runbook——边做边沉淀

前三个 Phase 都是"写代码之前"的。第四个 Phase 是"写代码过程中"的，但它也不是代码——是**沉淀**。

- **Manual（产品手册）**：这个系统怎么用，给下一个接手的人（或下一个 AI）看。
- **Runbook**：怎么跑、怎么部署、怎么回滚、出了某类故障怎么处理——是可复制执行的命令序列，不是散文。

为什么要"边做边沉淀"，而不是"做完了再补文档"？因为做完了，你一定会忘。文档的价值在于**当下一份代码要被下一个 AI 接手时，它能无缝接上**。

这里就引出了这套方法论的"元"主题：**你的约束体系，本质上是在给"下一个 AI"（和"下一个人"）铺路。** 文件是有顺序的，是为了让这条路上每一个后来者，都能一眼看懂"边界在哪、决策为什么、门禁怎么过、怎么跑起来"。

一个简单的检验：**如果明天你突然休假一个月，你的项目能靠文件自己撑住吗？** 撑不住的，缺的大概率不是代码，而是这一层沉淀。

---

## 七、活的注脚：这个顺序在 derekinside 里长什么样

这套"先建约束文件、再让实现长出来"的顺序，我那个本地副脑 **derekinside** 身上有个很干净的对应。

derekinside 是个知识库副脑，它的"代码"是不断涌入的知识。如果让知识随便进，它很快就会变成一锅乱炖。它的文档里没有"四阶段"这个词，但**把它的机制对应到上面四个 Phase，会得到这样的类比**：

- **Phase 1（Manifest）**：一个 wing 的边界声明——这个"知识翼"收什么、不收什么；
- **Phase 2（Spec + ADR）**：记忆晋升规则——什么样的内容够格从临时记忆升为长期记忆，什么时候该遗忘；
- **Phase 3（Gate）**：导入时的校验与去重——脏数据、重复数据，进门就被拦住；
- **Phase 4（Manual + Runbook）**：chunk 切分契约 + 实体关系定义——知识怎么切、实体怎么连，固定格式。

这四层约束立好之后，数千页沉淀、上万个实体节点，才是有序地、而不是混乱地长出来的。一个"会自我记忆、自我检索、自我进化"的系统，它的秩序，恰恰来自它被规定好的"解剖顺序"。

---

## 八、第一天就能用的清单

![06-checklist.jpg](https://developer.qcloudimg.com/http-save/yehe-11918656/673e3c5362f8593072498b864a7ac75b.jpg)

前几篇的清单都在讲"怎么加一层机制"，这篇的清单反过来，讲的是一套"动手前的自检"——不是加东西，而是改掉一个动作顺序。今天就生效：

- [ ] 下一次给 AI 派活前，先花 3 分钟写一份 **Manifest**——至少填 `WHY` 和 `SUCCESS` 两栏，再让它动手。如果这 3 分钟里你写不出 `WHY`，说明这活本身还没想清，先别派。
- [ ] 在 Manifest 里顺手落一栏 **STOP**：动手前写下"什么情况该停下"，等 AI 开始跑偏时，你（或下一个 AI）能一眼启动急停。
- [ ] 你的"范围"和"决策"，是写在**文件**里，还是只存在于**聊天记录**里？（后者会被下一次对话冲走）
- [ ] 有没有一个**提交前自动检查**的脚本，还是全靠人肉 review？
- [ ] 你的项目有没有一份 **Runbook**，能让一个陌生 AI 在 30 分钟内看懂"怎么跑、怎么部署、怎么回滚"？

这五条，是"按蓝图施工"和"边想边砌"的分水岭。做到两条，你的 AI 就已经在正确的顺序里干活了——剩下的是让这条纪律养成习惯。

---

*（《驾驭 AI · AI Harness Engineering》系列第八篇。下一篇：多 Agent 编排——从单点到分工；当约束体系在一个 Agent 上跑通，怎么把它复制到一群 Agent 身上。）*

---

AI Harness Engineering 系列 · 第七篇 · 王海涛（GitHub：derekwang85 · 腾讯云 TVP / 架构师名人堂）

驾驭 AI · AI Harness Engineering ·规约文件构造

五层金字塔，战略、架构、契约、门禁、实现，一层层叠成一座塔，但除了了"长什么样"，还欠一个问题：先建什么、再建什么？

 CTO

人工智能

编程语言

架构设计

AI编码正确顺序：先写约束文件再写代码。四阶段法——Manifest明确需求、Spec+ADR钉死范围决策、Gate门禁前置、Manual+Runbook边做边沉淀，让AI从"边想边砌"转为"按蓝图施工"，避免字段混乱与返工浪费。

消息队列

代码解释

数据库

GitHub

Agent

2026上云采购 | AI焕新·智启新局

coding

腾讯云BI特惠9.9元起！


lexiang

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

驾驭 AI · AI Harness Engineering ·规约文件构造-腾讯云开发者社区-腾讯云

驾驭 AI · AI Harness Engineering ·规约文件构造

驾驭 AI · AI Harness Engineering ·规约文件构造

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐