01 · 用好 AI 编程：从会生成到能交付

开篇 · 真实案例：B 端控制台登录，周五下午的“完美翻车”

00 / 案例背景

一项看似毫无技术门槛的认证需求，为何在 AI 的极速生成下，演变成了一场险些酿成事故的交付灾难？让我们把时钟拨回那个令人窒息的周五下午，从一个 B 端控制台的真实翻车现场说起。

01 / 初始任务：一句 Prompt 开启的“盲盒”

团队正在推进一套内部 B 端控制台。迭代目标非常克制且明确：仅打通基础的邮箱注册、登录与登出流程，确保运营同学能顺利进入系统配置数据。OAuth、多租户架构以及“记住我”等复杂功能，都被明确划入后续排期。

后端已经搭好 Express + TypeScript 骨架，会话管理沿用现有的 session 方案，密码哈希与错误体规范也早已沉淀在仓库文档中。周五上午，负责该模块的阿明接到口头需求：“认证先做起来，下午最好能联调。”

他打开 Cursor，将仓库根目录作为上下文喂给 AI，并敲下了一句极其经典的提示词：

帮我实现用户认证，要安全一点，最好用现在流行的写法。

02 / 虚假繁荣：把“生成成功”错当“交付成功”

仅仅四十分钟，Agent 就吐出了一大坨 Diff。注册、登录、JWT 中间件、各类工具函数……事后统计，涉及文件超过 40 个。本地 npm test 跑下来，进度条几乎全绿，尽管其中不少是新写的、断言极其宽松的测试。

阿明自信地提交了 PR，描述仅有一行：“AI 生成认证模块，请 review。”中午前，他觉得自己“赢麻了”：需求虽然含糊，但 AI 的输出却“看起来无懈可击”。而这，恰恰是整场翻车中最危险的一刻——他错把 AI 的“生成成功”当成了工程的“交付成功”。

03 / 事实证据：联调与 Review 扯下的“遮羞布”

下午 14:30，前端联调开始，灾难接踵而至：

会话失效漏洞：运营使用测试账号登录后点击退出，再次请求 GET /me，响应依然是 200，用户信息赫然在列。
敏感信息泄露：错误弹窗中，竟然直接暴露了服务器的绝对路径。
破坏性重构：Code Review 揪出更刺眼的改动——密码哈希相关文件被 AI “顺手优化”成了另一套算法，导致与库中已有用户数据完全不兼容；它甚至还“自作聪明”地起草了一截根本没人要的 OAuth 草稿代码。

时间	发生了什么	表面结论	实际隐患
10:20	一句 Prompt + 整仓上下文开工	很快有代码	任务未被定义
11:10	大 Diff PR，测试“基本绿”	好像做完了	验收标准缺失
14:30	登出后 `/me` 仍 200	会话没真正失效	逻辑未闭环
14:45	错误体泄路径；哈希被改；OAuth 多余	禁区与范围都失控	上下文未对齐
15:00	想“再生成一次整模块”	差点在错误方法上加码	缺乏反馈回路

04 / 破局之道：从“会回答”到“能交付”的范式转移

阿明没有选择换模型硬刚，而是和 Reviewer 达成了共识：问题不在模型够不够强，而在输入、拆步、验收全没立住。这次翻车事故，本质上是因为阿明只把 AI 当作了一个“问答机器”，而忽略了工程化的约束。

正如“AI 编程工程化”框架所强调的，要让 AI 从“会回答”走向“能交付”，必须建立一套可靠的系统。这套系统由四个核心要素组成，缺一不可：

Prompt

把目标说清楚

失败始于“要安全一点”。Prompt 不是聊天，而是任务定义，需要明确边界、约束和验收标准，而不是让 AI 去猜什么是“流行写法”。

Context

把事实补齐

丢进根目录不等于提供了依据。必须明确沿用现有 Session 方案、禁止修改哈希算法等关键事实，让业务规则和历史决策进入上下文。

Harness

把执行跑稳

40 个文件的 Diff 没有执行边界。Harness 用脚手架、Lint 规则和测试护栏限制 AI 的行动范围，防止它“脱缰”乱改。

Loop

把反馈带回

测试全绿不是终点。Loop 要求小步快跑、持续验证，把人工验收、CI 和联调结果写回下一轮，而不是“一把梭哈”后听天由命。

flowchart LR A[说清任务 Prompt] --> B[给足上下文 Context] B --> C[可靠执行 Harness] C --> D[持续验收 Loop] D -->|失败写回约束| A D --> E[能合并的交付结果]

05 / 核心公式：重新定义可靠交付

这次翻车让团队痛定思痛，总结出了 AI 编程时代的交付公式：

可靠交付 = 说清任务（Prompt） × 给足上下文（Context） × 可靠执行（Harness） × 持续验收（Loop）

在这个公式中，任何一项如果是 0，结果就是 0。阿明的案例中，正是因为缺失了后三项的支撑，导致第一项 Prompt 的威力变成了破坏力。

后文整条线，就是阿明团队如何把这个公式落地，把这次认证模块从“会生成”修到“能合并”的过程——先归层，再写契约、收证据、拆工序、失败写回，直到 PR 带上手动验收三步、CI 实打实转绿。

思考笔记：生成结果为什么不能直接等于交付结果

生成结果为什么不能直接等于交付结果？因为 AI 擅长的是“概率预测”，而工程追求的是“确定性交付”。只要任务定义、依据来源、验证手段这三个问题没有答案，代码生成得越快，错误扩散得也可能越快。

带着这个问题继续：失败不是一个点。先把现场归到正确层级，再决定下一轮输入、证据和检查点如何补齐。

Part 01 · 翻车归层：失败不是一个点，而是一条链

01 / 诊断

先别让 AI“再生成一次”。面对同一个失败现象，先判断它属于目标、依据、执行还是反馈哪一层，再决定下一轮修什么。

flowchart LR A["翻车现场"] --> B["L1 说不清"] A --> C["L2 依据错"] A --> D["L3 步骤不可检"] A --> E["L4 无闭环"] B --> F["先归层，再修复"] C --> F D --> F E --> F

01 / 诊断：别急着换药，先看病灶在哪

面对阿明 15:00 时的崩溃现场，第一反应往往是：“把整段认证模块删掉，换个更强的模型，再生成一遍。”这是 AI 编程中最常见的坏习惯。

危险点在于：“再生成”默认假设上次失败只是因为模型不够聪明。但回顾阿明的案例，认证模块同时爆了四类问题：范围跑偏（做了 OAuth）、依据没读（改了哈希）、步骤不可检（40+ 文件大 Diff）、失败没写回（登出无效）。

先归层：这就像病人同时发烧、骨折且营养不良，不能只给他吃退烧药。应先把现场现象映射到具体责任层，再决定下一轮输入该改什么。

正如「01 / 问题地图」所示，失败不是孤立的一个点，而是一条因果链。归层不是给问题贴标签，而是为下一步选择正确的修复入口。

02 / 核心拆解：四层缺陷与修复地图

每一层都看四件事：核心缺陷 · 现场症状 · 错误反应 · 正确修复动作

归属层	核心缺陷	现场症状（阿明案例）	错误反应	正确修复动作
L1：Prompt	说不清（目标 / 边界模糊）	Diff 里冒出本期没人要的 OAuth 草稿；Prompt 只有“安全一点”。	继续加功能，或让 AI“再完善一下登录”。	先写清 Goal、Non-goals、Acceptance，再让 AI 动代码。
L2：Context	依据错（知识 / 规范缺失）	哈希被“顺手优化”；错误体暴露服务器路径；会话方案不一致。	整仓 @ 进上下文，指望模型自己找对文件。	补事实：只挂最小充分证据，如会话实现、错误体规范和哈希禁区。
L3：Harness	步骤不可检（执行 / 验证失控）	单次 PR 超过 40 个文件；测试“松绿”；联调才发现登出后 `/me` 仍 200。	一口气重生整模块，继续大 Diff。	拆成可中断步骤，每步设命令和手动检查点，过了再往下。
L4：Loop	无闭环（反馈 / 状态丢失）	联调红了，下一轮仍是“帮我修一下认证”；已知约束没有进入 Prompt。	同一句话重试，或换模型硬刚同一输入。	把失败现象写成下一轮硬约束，再小步回流。

03 / 事实证据：如何按顺序补缺

这四层问题往往会叠加出现，阿明那次就是四层同时中招。为了避免修复动作互相干扰，建议固定顺序：先说清楚 → 再给依据 → 再拆步骤 → 最后谈回流。

快速诊断：停在第一个回答“否”的地方

有没有可观测的验收句？没有 → L1 说不清。此时猛加证据没用，生成得越完整，交付越对不上。
AI 是否读对了现行代码、规范和禁区？没有 → L2 依据错。此时换更强模型没用，同一错误上下文下，引擎越强，幻觉越自信。
能否指出“做到哪一步、怎么证明过了”？不能 → L3 步骤不可检。此时整模块重生只会带来更大的 Diff、更难的 Review。
失败后下一轮输入有没有新增约束？没有 → L4 无闭环。此时同一 Prompt 重试，只会让你在同一个坑里踩第二遍。

现场现象	归属层	根因一句话	下一动作
做了 OAuth 草稿，本期没人要	说不清	目标与非目标没写死	补契约，再动代码
哈希被「优化」、错误体泄路径	依据错	没指定必读规范与禁区	收证据包，标禁区
一次 PR 改了 40+ 文件	步骤不可检	没有一步一验收	拆 T01→Tn，设检查点
测松绿、联调才爆，仍想整模块重生	无闭环	失败没有写回下一轮输入	失败写进回流 Prompt

04 / 诊断结论：归层是为了精准用药

归错层的代价很大。明明说不清，却猛加 Context，结果只是生成得更完整，仍然不是我要的；明明依据错，却换更强 Model，哈希和禁区问题可能复现得更自信；明明步骤不可检，却整模块重生，PR 会更大、Review 会更难；明明无闭环，却同一 Prompt 重试，只是在同一个坑里踩第二遍。

执行口令：先找到第一个缺口，补齐它，再进入下一层。四层可以叠加，但药不能混着开。

补充说明：归错层会怎样

误判	你实际在做的事	典型结果
明明说不清，却猛加证据	@ 更多文件，仍无验收句	生成更完整，交付仍对不上
明明依据错，却换更强模型	同一错误上下文，换引擎	哈希/禁区问题复现
明明步骤不可检，却整模块重生	更大 Diff、更难 review	联调继续爆，PR 更难合
明明无闭环，却同一 Prompt 重试	失败信息没进入下一轮	同一坑踩第二遍

思考笔记：诊断比重新生成更重要

同样是“登录失败”，可能是需求没有说清、现行规范没有读到、步骤无法验证，或是失败没有写回下一轮输入。症状相同，不代表根因相同；根因不同，修复动作也不该相同。

因此，归层不是给问题贴标签，而是为下一步选择正确的修复入口。先找到第一个缺口，再补齐它，才能避免把“换模型、加上下文、重生整模块”变成条件反射。

带着这个判断进入下一章：既然四层问题需要按顺序补缺，具体该如何把修复动作组织成一套可执行的计划？

这一幕带走：翻车先归层。四层可以叠加，但药不能混着开——先对症，再生成。

Part 02 · 修复计划：四种 Engineering，把「会生成」变成「能交付」

02 / 总图

认证要救回来，不是换一个更强的模型，而是把 Prompt、Context、Harness、Loop 四种 Engineering 按顺序补齐，让每一轮 Diff 都更接近可合并的交付结果。

flowchart LR P["Prompt 说清楚"] --> C["Context 给依据"] C --> H["Harness 跑可靠"] H --> L["Loop 变更好"] L --> R["可合并的 Diff"]

01 / 总图：从单点修补到系统加固

在 Part 01 中，我们诊断出阿明的翻车并非单一原因，而是四层缺陷的叠加。面对这种复合型失败，简单的“换个模型”或“重写 Prompt”只是隔靴搔痒。

要救回这个认证模块，需要一套系统性的修复计划。正如「Part 02 · 四种 Engineering」所示，这不仅仅是四个技巧，而是一套覆盖从任务表达到持续交付的工作系统。每一种 Engineering 都解决一类特定失败，共同构成 AI 编程的工程化底座：

Prompt Engineering（说清楚）解决“目标模糊”的问题。

Context Engineering（给依据）解决“知识幻觉”的问题。

Harness Engineering（跑可靠）解决“执行失控”的问题。

Loop Engineering（变更好）解决“缺乏进化”的问题。

总原则：这四件事必须按顺序补齐，缺一不可。模型负责写 Diff，而这四件事负责让 Diff 变得可合并。

02 / 核心拆解：四种 Engineering 的分工与协作

每一行都回答：翻车前怎么做 · 修复后怎么做 · 解决哪类问题

Engineering	核心定义	翻车前（阿明做法）	修复后（工程化做法）	解决的问题
1. Prompt	任务契约（目标 · 约束 · 验收）	“做个登录，安全一点。” 模糊指令	Goal + Boundary + Acceptance；明确“不要 OAuth”“登出后 `/me` 必须 401”。	说不清避免范围蔓延与标准虚化
2. Context	事实依据（代码 · 规则 · 证据）	整仓 @，指望模型自己找。大海捞针	最小充分证据包；只提供 Session 实现、错误体规范、哈希禁区文件。	依据错避免破坏现有规范与数据结构
3. Harness	可靠执行（拆分 · 状态 · 恢复）	一口气生成 40+ 文件。黑盒交付	T01 → T06 工序化；每步有命令或手动检查点，一步一验，过了再往下。	步骤不可检避免大 Diff 导致 Review 失效
4. Loop	持续改进（验收 · 复盘 · 下一轮）	测红了重试，或换模型。原地打转	失败回流机制；把报错信息写成下一轮硬约束，小步闭环。	无闭环避免同一坑反复踩

03 / 执行逻辑：为什么顺序不能乱？

这四种 Engineering 不是菜单上的四道菜，不能随意点选；它们是串联的加固工序。阿明案例的最短修复路径，严格遵循以下逻辑：

先说清楚（Prompt）：如果没有可否决的验收句（Acceptance Criteria），后面的 Context 给得再多，模型也不知道该优先遵守哪条规则，容易生成“正确但无用”的代码，例如多余的 OAuth。
再给依据（Context）：契约有了，但如果禁区（如密码哈希算法）与现行实现没进视野，模型仍会自作聪明地“优化”代码，导致数据不兼容。
再跑可靠（Harness）：证据齐了，如果仍一口气生成大 Diff，Reviewer 和测试者依然无法有效拦截错误，联调时还是会爆雷。
最后变更好（Loop）：只有前三层立住了，失败才有地方“写回”。否则，所谓“修改”只是在错误的基础上换皮重试。

干货总结：四件事是串联加固，不是互斥工具。常见误用是“只加强 Prompt”或“只多 @ 文件”——那是单点补丁，救不回认证这种复合翻车。真正有效的修复，不是让模型一次做得更多，而是让每一步都知道为什么做、依据什么做，以及怎样证明做对了。

思考笔记：修复计划不是更长的 Prompt

很多人误以为“工程化”就是写更长的文档或 Prompt。其实，“说清楚、给依据、跑可靠、变更好”实质上是在把产品判断、仓库事实、执行检查和失败学习重新放回工程流程中。

它们不是为 AI 增加仪式，而是为每一次变更建立可判断的边界。如果只补其中一项，问题仍可能从另一个缺口进入。

带着这个思考进入下一章：四件事中的第一件——“说清楚”，怎样被写成 AI 和 Reviewer 都能执行、检查并否决的任务契约？

这一幕带走：修复计划 = 说清楚 → 给依据 → 跑可靠 → 变更好。下一章从「说清楚」开始，把「做个登录」写成可否决的契约。

Part 03 · 说清楚：先把任务说清楚，AI 才不会自作主张

03 / 契约

Prompt Engineering 的核心不是话术，而是定义。把模糊意图写成目标、范围、约束、输出和验收，AI 才知道做什么、不做什么，以及什么结果才算正确。

flowchart LR G["Goal 目标"] --> S["任务契约"] B["Boundary 范围"] --> S C["Constraints 约束"] --> S O["Output 输出"] --> S A["Acceptance 验收"] --> S S --> D["可执行的变更"]

01 / 契约背景：Prompt 不是聊天，是“任务契约”

在 AI 编程工程化中，Prompt Engineering 的核心不在于“话术”，而在于定义。正如「Part 03 · Prompt Engineering」图示所强调的：Prompt 不是一句话，而是一份可执行的任务契约。

阿明翻车的根源，在于他把 Prompt 当成了“口头需求”的传声筒。

反例（一句话交付）：“帮我做一个用户认证系统。”

后果：缺少目标、范围、禁区和验收标准。AI 只能用它的“默认知识”去猜测空白，导致 OAuth 乱入、JWT 误用。

正例（五个字段）：必须包含目标、范围、约束、输出、验收。

价值：把模糊的意图转化为结构化指令，让 AI 知道“做什么”“不做什么”，以及“做成什么样才算对”。

契约不是为了把 Prompt 写得更长，而是为了建立一套 AI、开发者和 Reviewer 都能对齐的判断标准。当验收句能够指出具体接口、状态码、文件范围和安全约束时，后续的证据包才有筛选标准，工序才有检查点。

02 / 核心拆解：从“翻车版”到“五字段契约”

结合图示中的“正例：五个字段”，我们将阿明的需求重构为一份标准任务契约。这不是文字堆砌，而是从目标到验收的逻辑闭环。

字段	定义	❌ 翻车版（阿明原话）	✅ 可交付版（五字段契约）
1. 目标	要完成什么？ Goal	“做个登录”	实现注册、登录、登出；受保护接口在未登录或登出后必须返回 401。
2. 范围	做到哪里为止？ Boundary	未提及	仅修改 auth 相关模块：路由、session、中间件和对应测试。
3. 约束	什么不能做？ Constraints	“安全一点” 模糊指令	禁止修改密码哈希算法；禁止触碰生产密钥与 `.env` 文件。
4. 输出	要留下什么？ Output	未提及	更新后的路由代码、Session 管理逻辑和配套单元测试文件。
5. 验收	什么算完成？ Acceptance	未提及	auth 单测全绿；手动验证“登录 → GET /me 200 → 登出 → GET /me 401”；错误响应不泄露堆栈与绝对路径。

验收原则：任一验收项失败 = 任务未完成。

03 / 落地执行：验收句怎么写才算数？

核心标准就一条：别人能不能根据这句话说“没过”而不吵架。

不合格（无法否决）	合格（可一票否决）
尽量安全一点	错误响应不出现堆栈与绝对路径。
登录体验好一点	正确账号登录后 `GET /me` 返回 200 与用户字段。
会话处理好	登出后再请求 `GET /me` 必须返回 401。
测试差不多绿就行	auth 相关单测全绿；任一红则本步未完成。

写 Acceptance 的三问：

失败时，我能指出哪一条命令或哪一次手动请求证明它挂了吗？
成功时，reviewer 能不能复现同一条路径？
这条验收是否依赖「感觉」「看起来」？有 → 重写。

思考笔记：为什么“说清楚”比“写代码”更重要？

在传统开发流程中，我们习惯于“边做边想”，或者在代码里通过注释补充逻辑。但在 AI 辅助编程中，思维必须前置。

消除“默认值”陷阱：AI 模型训练于海量通用数据，它的默认值往往是通用的、流行的，但不一定是当前项目需要的。如果不明确指定“不做 OAuth”，它可能因为 OAuth 是“流行写法”而擅自添加。契约的本质，就是用项目的特异性覆盖 AI 的通用性。
从“人治”到“法治”：阿明之前靠 Reviewer 的经验发现 OAuth 不对、哈希被改；现在则把规则写进契约，让 AI 在生成前自我审查，让 Reviewer 在验收时有据可依。
降低沟通熵值：模糊需求是高熵的，包含无数种可能性；结构化契约是低熵的，能够收敛可能性。写契约的过程，就是给 AI 降噪，让正确代码的信号更清晰地传输。

带着这个思考进入下一章：契约已经说明“要什么、不要什么、怎样算过”，还需要哪些仓库事实来约束 AI 的判断？

这一幕带走：契约 = Goal + Boundary + Acceptance + Non-goals（Evidence 索引可选）。少一项，就给翻车留门。下一章：把禁区与现行实现收成刚好够用的证据包。

Part 04 · 给依据：上下文不是越多越好，而是刚好够用

04 / 证据

契约回答“要什么、不要什么、怎样算过”，证据包回答“仓库里的现行事实是什么”。上下文不是越多越可靠，而是刚好足以约束这一次变更。

flowchart LR L1["L1：现行实现"] --> P["最小充分证据包"] L2["L2：规则与测试"] --> P L3["L3：历史决策（按需）"] --> P X["密钥与无关噪音"] -.不进入.-> P P --> D["受约束的判断"]

01 / 证据背景：为什么“整仓投喂”反而误事？

在 Part 03 中，我们确立了契约。但契约只回答“要什么、不要什么”，证据包则要回答“仓库里的现行事实是什么”。

阿明翻车的核心原因之一，就是把整个仓库根目录丢进了上下文。他以为这样最保险，结果模型“看见”了大量无关模块，却没稳定锚定到 Session 实现与错误体规范。于是，AI 用通用的“流行写法”替换了哈希算法，用调试友好的错误体把服务器路径打到了前端。

最小充分：证据包不是“上下文越多越好”，而是少到会猜错关键路径就补，多到开始稀释信号就减。缺少 Context，AI 只能用默认知识补齐未知，这正是幻觉的温床。

02 / 核心拆解：分层结构与最小充分原则

证据包不能一股脑全塞进去，而应按优先级分层投喂。先用必须材料锚定主干，再根据报错或 Review 意见递进补充。

层级	内容类型	对应阿明案例的文件	作用
L1 必须	报错、复现、目标文件	`src/auth/session.ts` `src/routes/auth/*.ts`	锚定现行实现，防止登出逻辑失效或路由漂移。
L2 常需	技术栈、API、项目规则	`docs/error-envelope.md` `tests/auth/*.spec.ts`	确立错误体规范与测试标准，防止泄露路径或断言过松。
L3 按需	历史决策、关联模块	本次暂不需要	仅在涉及复杂交互或历史坑点时引入。

最小充分拿掉任意一项，是否会导致某条 Acceptance 必然漂移？是则保留，否则删除。

分层递进先给 L1 文件跑通主干，再根据报错或 Review 意见补充 L2 / L3。

可追溯所有依据必须来自现行主分支事实，拒绝旧分支、闲聊结论或外部博客。

有边界明确 .env、密钥文件和无关模块等禁区，绝不进入上下文。

03 / 执行结论：用“三问”筛选最小充分证据

每想多 @ 一个文件，先过三问；任一问答不上，就别加：

缺了它，AI 会猜错什么？说不出具体猜错点，多半是安慰剂，不加。
它是现行事实，还是过期意见？分支实验、聊天结论和外部博客，默认不进包。
它是否含密钥或无关噪音？有密钥，永不进；噪音大于信号，就剪到相关片段或换摘要。

最小充分自检：

拿掉包里任意一项，是否会导致某一条 Acceptance 必然漂？会，则该项必要。
包里是否存在“与验收无关、只是顺手 @”的文件？有，则删除。
禁区是否同时以文字出现在 Prompt 里？只靠“没 @ 哈希文件”不够，模型仍可能新建一套。

思考笔记：上下文不是越多越可靠

证据包的难点不在于“找到多少文件”，而在于判断哪些事实足以约束这一次变更。把整仓内容交给 AI，看起来减少了遗漏，实际上可能让会话实现、错误体规范和禁区声明淹没在无关信息里。

最小充分不是追求最少，而是让每一项材料都能回答一个明确问题：缺少它，AI 会在哪一条验收上判断错误？答不上来，就不应让它占据上下文。

带着这个思考进入下一章：当目标和依据都已明确，怎样把认证任务拆成可以逐步检查、失败也能定位的工序？

这一幕带走：证据包追求最小充分：按 L1 → L2 → L3 递进，所有材料可追溯，禁区不进上下文。下一章：有了契约与依据，把认证拆成可检查步骤。

Part 05 · 跑可靠：大任务要拆开、可恢复、可交接，AI 才做得完

05 / 工序

契约解决“做什么”，证据包解决“依据是什么”；Harness 进一步解决“怎样把大任务跑完”。大任务要拆开、可恢复、可交接，AI 才做得完。

flowchart LR T1["T01 契约确认"] --> T2["T02 登录可用"] T2 --> T3["T03 鉴权通过"] T3 --> T4["T04 登出失效"] T4 --> T5["T05 错误体安全"] T5 --> T6["T06 收束 PR"] T2 -.检查点失败.-> T2 T4 -.检查点失败.-> T4

01 / 工序背景：Harness 把“一次性生成”变成“可控流水线”

在 Part 03 和 Part 04 中，我们解决了“做什么”和“依据是什么”的问题。但即使契约完美、证据充分，如果执行过程失控，依然会翻车。

正如“Part 05 · Harness Engineering”图示所强调的：大任务要拆开、可恢复、可交接，AI 才做得完。

阿明之前的失败模式是典型的“瀑布式生成”：一口气生成注册、登录、JWT 草稿、中间件和测试，单次 PR 包含 40+ 个文件。本地测试“松绿”就敢开 PR；下午联调发现登出后 /me 仍返回 200，此时面对巨大 Diff，根本分不清是哪一段逻辑导致会话失效失败，只能全盘重来。

Harness 的核心价值：把一次性的大生成变成一组有输入、有输出、可检查、可继续的步骤。它不是把任务写细为了好玩，而是让每一小步都有失败停点——过了才准往下，红了立刻停步。

02 / 核心拆解：三条执行纪律与 T01—T06 工序

不要给 AI 一个模糊的“开始”，要给它明确的护栏。Harness 的第一步不是生成，而是先确定每个步骤如何启动、如何证明、如何停下和如何交给下一步。

纪律	定义	阿明案例的修正
① 小粒度	每一步有输入、输出和完成条件。	禁止“顺便重构”；T04 只负责登出失效，不准动注册表单。
② 可恢复	每一步留下状态、Diff、测试和 Checkpoint。	如果 T04 挂了，只回滚 T04 的代码，保留 T01—T03 的成果。
③ 可交接	统一使用 Brief → Report → 下一步。	上一步的输出（如 Session 实现）必须明确成为下一步的输入。

② 过程证据：认证交付的 T01 → T06

阿明修复轮实际采用的人侧工序；每步检查点不过，禁止进入下一步

步骤	任务内容	关键检查点（Checkpoint）	失败停点（Stop Point）
T01	契约确认	团队对 Goal / Boundary / Acceptance 无歧义。	未对齐前，禁止写代码。
T02	登录可用	正确账号能拿到会话；登录单测全绿。	登录失败，禁止做鉴权。
T03	受保护接口	无会话访问受保护路由 → 401；中间件测试绿。	鉴权失效，禁止做登出。
T04	登出失效	登出后再请求 `GET /me` → 401；会话测试绿。	阿明翻车点：登出无效，禁止改错误体。
T05	错误体安全	错误响应不泄露堆栈 / 路径；快照断言绿。	泄露敏感信息，禁止收束 PR。
T06	收束 PR	CI 全绿；Acceptance 清单全部勾选。	任何一项未达标，禁止合并。

顺序逻辑：先钉契约 → 再登录 → 再鉴权 → 再登出失效（最容易漏，需单独成步）→ 再错误体安全 → 最后收 PR。这样能让核心业务闭环在早期验证，避免最后联调时“大爆炸”。

03 / 落地执行：开跑前的“30 秒自检”

让 AI 开始每一个步骤前，必须完成以下确认；否则就是给未来埋雷：

前置确认：当前是 Tn，上一步 Tn-1 的检查点是否已经确认为绿？
要素完备：本步的输入、输出、检查点、失败停点是否都已写进 Prompt？
边界控制：本步 Boundary 是否严格小于或等于契约 Boundary？
失败预案：若红，下一动作是回流写约束，还是整模块重生？后者直接否决。

干货：工序是人侧的 Harness。模型可以在一步内多改几个文件，但跨步合并验收不行——那会把“哪一步坏了”重新变模糊。一步一验收，才是 AI 编程的“稳”。

思考笔记：拆步不是为了繁琐，而是为了减少返工

拆步不是为了制造流程，而是为了对抗大模型生成带来的熵增。一次生成 500 行代码看似高效，实则将验证成本后置到了最昂贵的联调阶段。错误发生后，面对一团乱麻的 Diff，开发者往往被迫放弃修复而选择重写，这才是最大的浪费。

Harness 的本质，是将“黑盒交付”转变为“白盒验证”：让每一次前进都有据可依，让每一次失败都止步于当下。只有把大任务拆解为机器可执行、人类可验证的原子单元，AI 才能真正从“玩具”变成生产力工具。

带着这个思考进入下一章：当 T04 的检查点真实失败时，怎样把这条红证写回下一轮输入，而不破坏已经通过的步骤？

这一幕带走：Harness = 小粒度 + 可恢复 + 可交接。每步有输入、输出、检查点和失败停点；红了就停，不把局部失败扩散成整模块重生。下一章：T04 红了之后，如何把失败写回下一轮。

Part 06 · 变更好：真正的效率来自闭环，而不是一次生成

06 / 闭环

验收不是终点，而是下一轮的输入。真正的效率来自把失败沉淀为约束、锁定在当前步骤并持续回流，而不是一次又一次地整模块生成。

flowchart LR A["验收"] --> B["定位"] B --> C["沉淀失败证据"] C --> D["写回新增约束"] D --> E["锁定当前 Tn 重跑"] E --> A

01 / 闭环背景：验收不是终点，而是下一轮的输入

在 Part 05 中，我们建立了 Harness 工序，确保任务被拆解为可检查的步骤。然而，当 T04（登出失效）检查点变红时，真正的考验才刚刚开始。

正如“Part 06 · Loop Engineering”图示所强调的：真正的效率来自闭环，而不是一次生成。

阿明在 T04 翻车了：登出后 GET /me 接口依然返回 200。此时，他面临三种选择：

错误选择 A

盲目重试

“帮我修一下认证，登出有问题。”失败细节只在他脑子里，模型下一轮仍从模糊目标起步。

错误选择 B

全盘重来

“把认证模块删了再生成。”这会毁掉已绿的 T01—T03，并把失败信息重新变糊。

正确选择

闭环回流

留证 → 归层 → 写回，把红测结果写成下一轮 Prompt 里的硬约束。

Loop Engineering 的核心：每一轮都留下可复用结果，并把反馈带入下一轮。如果失败没有变成文字约束，就等于没发生过。

02 / 核心拆解：四步闭环法与回流 Prompt

不要只盯着代码看，要盯着输入输出看。结合“验收 → 定位 → 沉淀 → 调整”的流程，阿明的修复过程可以标准化为四步闭环法：

步骤	动作	阿明 T04 案例执行
① 验收	确认结果是否符合预期。	自动化测试 `auth.session.spec` 报红；手动复现 `GET /me` 返回 200。
② 定位	识别问题根因与改进方向。	判定为“依据不足”：现行 Session 清理路径未被遵守，而非简单的逻辑错误。
③ 沉淀	沉淀方法与知识，形成资产。	将“必须清理服务端 Session”从隐性知识转化为显性约束。
④ 调整	优化策略与执行，进入下一轮。	锁定 T04 范围，禁止改动哈希算法，只改 Session 清理路径。

② 事实证据：构建“回流 Prompt”

回流 Prompt 是 Loop Engineering 的实战载体。不要把失败当作终点，要把它当作下一轮的 Context。

错误的回流方式：还是不行，登出后还能访问，你再检查一下代码。——AI 会再次猜测，并可能引入新 Bug。

正确的回流 Prompt：

# Role: 继续 T04（登出失效修复）
# ⛔ 范围锁：继续 T04，绝对不要重做 T01—T03（登录与鉴权已验证通过）

## 🔴 失败证据（Evidence）
- 测试名：auth.session.spec.ts
- 期望：登出后 GET /me 返回 401
- 实际：返回 200（用户信息仍在）
- 手动复现：相同路径，确认 Session ID 在服务端未被销毁

## 🛡️ 新增约束（Constraints）
1. 必须清理服务端 Session / 令牌黑名单（以仓库现行实现为准，不要自行发明存储方式）
2. 禁止改动密码哈希逻辑（T02 已绿）
3. 只允许修改 Session 清理路径与对应测试文件

## ✅ 完成条件（Acceptance）
- 上述测试转绿
- 手动复现必须返回 401

03 / 执行结论：让改动具备累积性

Loop Engineering 的本质是保护已验证的成果。闭环的质量 = 下一轮输入比上一轮多了哪些不可省略的约束。若两轮 Prompt 几乎一样，你只是在重试，不是在“变更好”。

阿明使用上述回流 Prompt 后，仅一轮回流 T04 即转绿。随后顺利推进 T05（错误体安全）和 T06（收束 PR）。PR 描述中清晰写上手动三步验收与禁区，Reviewer 可按同一路径复核，CI 实打实全绿。

结论：测试失败本身不会让系统变好；只有当期望、实际、范围和新增约束被写成下一轮可执行输入，失败才从一次挫折变成一次学习。

思考笔记：Loop 不是重聊，而是状态机

很多人误以为 AI 编程就是“对话”，聊错了就重聊。但工程化的 Loop 更像状态机：每一次报错都不应只被“解决”掉，而应被记录下来，成为系统的一部分。

当失败被结构化后，AI 不再是需要反复教导的实习生，而成为能够继承历史反馈、严格恪守边界的执行器。所谓智能，正在于精准继承上下文和约束，而不是每轮都从头猜起。

带着这个思考进入下一章：当步骤、反馈和约束不断积累后，最初模糊的 Spec 如何一步步进化为可交付的工程规格？

这一幕带走：验收 → 定位 → 沉淀 → 调整。失败变成下一轮文字，才算进入闭环；保护已绿步骤，让每一次改动都能累积。下一章：同一认证需求，三版 Spec 如何决定三种命运。

Part 07 · Spec 演进：从“模糊需求”到“可交付契约”

07 / 实战

同一个认证需求会走向三种不同结局。Spec 的演进不是文档变长，而是将 Prompt、Context、Harness、Loop 逐层整合，把产品决定权从模型手中收回。

flowchart LR V01["v0.1 模糊需求"] --> X["范围与验收缺失"] X --> F["联调翻车"] F --> V10["v1.0 可交付 Spec"] V10 --> R["按 T01-T06 交付"]

01 / 演进背景：同一需求，三种结局

在 Part 03 到 Part 06 中，我们分别建立了契约、证据、工序和闭环。现在需要将这些能力整合，看它们如何共同决定一个项目的命运。

正如“Part 07 · 贯穿案例”图示所强调的：四种 Engineering 不是四套替代技巧，而是把同一个任务逐层加固。阿明的认证需求经历了三个版本的迭代；这不仅是文档修改，更是控制权的转移。

版本	写法特征	核心缺失	最终结局
v0.1	“做个登录，安全一点”	目标 / 边界 / 验收全无	翻车：功能看似全，联调即炸，哈希被改，登出失效。
v0.5	列了注册 / 登录 / JWT，仍有“尽量”	Acceptance 虚、Non-goals 弱、禁区口头	假绿：觉得写清了，实则仍是 v0.1 精装版，修不完 Bug。
v1.0	Goal / Boundary / Acceptance + Risk / Rollback	—	交付：按 T01—T06 推进，回流可控，PR 顺利合并。

读法：不是「写得越长越好」，而是每一版是否关掉一类翻车通道。v0.5 比 v0.1 长，但关掉的通道不够，所以仍然翻车。

02 / 核心拆解：为什么 v0.1 注定失败，而 v1.0 能赢？

① v0.1 的陷阱：把决定权交给“流行写法”

帮我实现用户认证，要安全一点，最好用现在流行的写法。

看起来像赢

生成很快、Diff 很全

实际输掉

验收与禁区为零

没人能一票否决「完成」；OAuth 可进、哈希可改、登出可假绿。

结论：v0.1 把产品决定权交给了模型的「流行写法」默认值。

② v0.5 的错觉：“已写清”的幻觉

实现邮箱注册、登录、JWT 鉴权。
要支持受保护路由。尽量安全，参考业界最佳实践。
可以的话把登出也做了。

比 v0.1 多了什么	仍然致命的缺口
点出了注册 / 登录 / 鉴权	无可否决 Acceptance（「尽量」「可以的话」）
提到受保护路由	未写登出后 `/me` 必须 401
提到「安全」	未禁改哈希、未禁泄路径、未写 Non-goals
暗示 JWT	与仓库现行 session 方案可能冲突（依据错）

干货：v0.5 最危险——它让人觉得「已经写清楚了」。功能清单 ≠ 契约；没有否决句，就仍是 v0.1 的精装版。

③ v1.0 的执行结论：可交付 Spec 的结构

阿明修复轮定稿的 v1.0 Spec，直接对应了前几章的工程化要求。它不再是一段话，而是一个结构化的数据块：

阿明修复轮定稿；可直接复制改领域词

【认证 · Spec v1.0】
Goal: 注册/登录/登出；登出后受保护接口 401
Boundary: 只改 auth 模块；禁止动哈希与密钥
Acceptance:
  - auth 单测绿
  - 手动：登录→/me 200→登出→/me 401
  - 错误体不泄堆栈/绝对路径
Non-goals: OAuth / 多租户 / 长期「记住我」
Evidence: session.ts · auth 路由 · error-envelope · auth 测试
Risk: 会话清理遗漏；错误体回退
Rollback: 回退至 T03 通过的 commit

前五块

契约本体

Goal / Boundary / Acceptance / Non-goals / Evidence——对应 Part 03–04，关掉说不清与依据错。

Risk

已知高危点

显式写出「会话清理遗漏」「错误体回退」，提醒 T04 / T05 检查点不可省。

Rollback

可回退点

回退到 T03 已绿 commit，避免 T04 回流失败时整段认证不可救。

用法

挂进每一步

T01 评审本 Spec；后续每步 Prompt 引用同一版，回流只追加约束，不另起炉灶。

03 / 补充清单：你的 Spec 到了哪一版？

在开启下一个任务前，用以下清单自检；若答案是否定的，请停留在当前版本继续打磨，不要进入编码阶段。

有没有可否决的 Acceptance？没有 → 仍是 v0.1 / v0.5。
有没有硬 Boundary + 明文禁区？没有 → 哈希与密钥仍可能被「优化」。
有没有Non-goals挡住流行写法扩容？没有 → OAuth / JWT 草稿随时回来。
有没有Evidence 索引指向现行实现？没有 → 模型会发明第二套方案。
高风险任务有没有Risk + Rollback？没有 → 工序中断后难以安全回退。

演进原则：

每一版只为关掉上一版真实踩过的坑（阿明：登出 401、禁哈希、禁泄路径、禁 OAuth）。
不加无法检查的形容词（「安全」「优雅」「最佳实践」）。
定稿后改 Spec 要升小版本号，并同步改检查点——避免口头改、文档旧。

思考笔记：Spec 的成熟度不由篇幅决定

Spec 从 v0.1 到 v1.0 的变化，本质上是将“隐性知识”转化为“显性约束”的过程。它不只是写给 AI 的需求说明书，更是写给人类自己的风险防御协议。

v0.1 失败，是因为它假设 AI 拥有资深工程师一样的上下文理解力和业务判断力；v1.0 成功，则是因为它承认 AI 的局限：它不知道什么是“安全”，除非你定义“不泄露堆栈”；它不知道什么是“完成”，除非你定义“登出后返回 401”。

最好的 Spec 不是一次写成的长文档，而是随着真实反馈持续升级的工程协议。每新增一条约束，都应指向一个曾经踩过的坑、一条明确验收，或一个具体回退动作。成熟度不由篇幅决定，而由它消灭了多少模糊地带决定。

带着这个思考进入下一章：当问题再次出现时，怎样根据症状先找到正确层级，而不是拿同一种修复方式到处试？

这一幕带走：功能清单不是契约。v1.0 = 可否决验收 + 禁区 + 非目标 + 证据 +（高风险时）Risk/Rollback。下一章：翻车后再修，按层分诊，别乱开枪。

Part 08 · 分诊台：按层修，别乱开枪

08 / 分诊

系统报红时，先把失败表现映射到契约、证据、工序或闭环，再确定修复顺序。分诊不是“再生成一次”，而是决定本轮究竟修哪一层。

flowchart TD S["发现失败"] --> Q1{"验收能否否决？"} Q1 -- 否 --> P["补契约"] Q1 -- 是 --> Q2{"关键事实是否齐？"} Q2 -- 否 --> C["补证据"] Q2 -- 是 --> Q3{"能指出 Tn 与检查点？"} Q3 -- 否 --> H["补工序"] Q3 -- 是 --> L["留证写回，进入闭环"]

01 / 分诊背景：为什么不能“有红就再生成”

在 Part 03 到 Part 07 中，我们建立了契约、证据、工序和闭环。当系统报错时，很多人第一反应是“换模型”或“重新生成”，但这往往是无效劳动。

正如“Part 08 · 缺陷映射”图示所强调的：先看问题发生在哪一层，再确定修复顺序。

阿明走过的弯路：T04 红后先「换模型再生成」整段认证，耗掉约两小时，哈希禁区差点再被踩。按序分诊后，只回流 T04，一轮就过。

分诊台的核心逻辑：把症状映射到层 → 只修那一层（或按固定顺序补缺）→ 再开下一轮生成。乱序等于赌博。

02 / 核心拆解：60 秒分诊法与四层修复顺序

结合图示的阅读方式——找到失败表现、对照编号、查看主责 Engineering、执行修复——可以建立一套标准化排查流程。不要只看表象，要看根源。

① 症状映射：相同症状，为何修错层？

现场症状	错误动作（乱开枪）	正确归因	修复动作（正解）
做了没要的功能 / 漏了登出验收 / “完成”无法否决	猛加 @ 文件，试图用上下文覆盖需求。	契约病	补 Acceptance / Non-goals / Goal（升 Spec）。
改错文件、用错约定、动了哈希、错误体泄路径	换更强模型，以为模型不够聪明。	证据病	收窄 @ 范围，挂现行实现，声明明文禁区。
Diff 巨大、说不清卡在哪步、中断只能重来	整模块重生，试图一次搞定。	工序病	拆 Tn，恢复上一检查点，禁止跨步。
同一失败重复出现、两轮 Prompt 几乎一样	同一句话重试，或只换模型不换 Prompt。	闭环病	留证写回，锁步回流，新增约束。

② 修复优先级：按什么顺序判断问题层？

修复有优先级。如果上一层没修好，下一层的努力都会白费。

契约（Priority 1）：验收与非目标若仍糊，修证据 / 工序只是在错误完成标准上加速。Acceptance 能否一票否决？否 → 停在契约。
证据（Priority 2）：契约清了但现行实现与禁区没进视野，模型仍会发明第二套方案。现行关键文件与禁区是否在上下文？否 → 停在证据。
工序（Priority 3）：依据齐了仍大 Diff，失败无法定位，回流也无从锁步。能否指出当前 Tn 与检查点？否 → 停在工序。
闭环（Priority 4）：前三层立住后，才把红证写进下一轮；否则写回也只是换皮重试。下一轮是否新增失败约束？否 → 停在闭环。

60 秒分诊口令：按契约 → 证据 → 工序 → 闭环依次提问；遇到第一个“否”，就停在该层修复，不向后跳步。

03 / 执行结论：按层修，别乱开枪

❌ 乱开枪的后果

乱开枪

契约病，却猛加 @

上下文更满，完成标准仍虚 → 生成更完整，交付仍对不上。

乱开枪

证据病，却换更强模型

同一错误视野换引擎 → 哈希 / 会话方案冲突复现。

乱开枪

工序病，却整模块重生

更大 Diff → 更难指出卡点，已绿步骤被冲掉。

乱开枪

闭环病，却同一 Prompt 重试

失败未写回 → 同一坑第二遍（阿明换模型那两小时）。

✅ 按层修的正解

按层修（正）	动作示例
契约缺口	先升 Spec（见 Part 07），T01 重新对齐后再写码
证据缺口	只挂 session / 错误体规范 + 禁区声明，再开轮
工序缺口	回退到最近绿检查点，按 Tn 重跑，禁止跨步
闭环缺口	用 Part 06 回流模板，锁步 + 留证 + 新约束

补充说明：叠症怎么拆（认证常见）

真实翻车很少只中一层。阿明下午是四层叠加；分诊时仍按顺序补缺，不要试图一轮 Prompt 治百病。

组合	拆法
契约虚 + 大 Diff	先写 v1.0 Acceptance，再把已生成 Diff 按 Tn 切开验收，不整段留用
禁区被踩 + 测试松绿	先收回证据包与禁区，再补强检查点，最后才回流修功能
T04 红 + 想换模型	先完成留证写回；模型可换，但回流 Prompt 结构不能少

干货：分诊的产出不是「再生成一次」，而是一张本轮只修哪一层的决定。修完再跑检查点；过了，才进入下一层或下一步。

思考笔记：分诊是在控制修复的范围

分诊的价值不只是更快找到原因，更重要的是防止一次局部失败扩大成整段系统的不确定性。明确“本轮只修哪一层”，才能保护已经验证通过的内容，让每一次修复都有边界。

面对叠加问题时，最容易犯的错误是希望一轮 Prompt 同时解决所有缺口。更可靠的方式是按固定顺序补齐：先统一完成标准，再补足依据，再恢复检查点，最后让失败进入回流。

带着这个思考进入下一章：当每一步都已可检查，哪些步骤可以并行，哪些又必须因为共享状态而保持串行？

这一幕带走：症状对层，按「契约 → 证据 → 工序 → 闭环」修。乱序开枪，越修越远。下一章：步骤之间谁依赖谁，哪一步才能并行。

Part 09 · 画清依赖：哪步能并行，哪步必须串行

09 / 执行图

图告诉我们任务如何连接，Harness 决定这些连接如何被可靠执行。先画清依赖，再让 AI 动手，才能判断哪些步骤必须串行、哪些才能真正并行。

01 / 依赖背景：为什么工序拆完还要画依赖图

在 Part 05 中，我们通过 Harness 将认证任务拆解为 T01–T06，解决了“一步一检”的问题。但拆解不等于可以随意并行。依赖图解决的是下一个关键问题：哪些步骤必须串行，哪些才能真正并行？

正如“Part 09 · Graph Engineering”图示所强调的：图告诉我们任务如何连接；Harness 决定这些连接如何被可靠执行。

常见误用：看到六步就开两个 Agent——一个写登录，一个写登出与错误体。会话状态、中间件、错误形状同时被改，合并时冲突；更糟的是两边都「测绿」，合在一起登出后 /me 又 200。

规则很硬：能并行的，是无共享可变状态（或无共享同一验收路径）的步骤；会话链路默认串行。

02 / 核心拆解：串行与并行的判断标准

结合图示中的“任务依赖关系”与“执行产生 Diff”，先明确每一步的上下游关系，再决定是否启动第二条执行支路。

① 任务依赖链：认证系统的执行图

flowchart LR T01["T01 契约确认"] --> T02["T02 登录可用"] T02 --> T03["T03 受保护接口"] T03 --> T04["T04 登出失效"] T04 --> T06["T06 收束 PR"] T02 --> T05["T05 错误体安全"] T05 --> T06 classDef main fill:#dbeafe,stroke:#2563eb,color:#1e3a8a classDef parallel fill:#fef3c7,stroke:#d97706,color:#78350f classDef finish fill:#dcfce7,stroke:#16a34a,color:#14532d class T01,T02,T03,T04 main class T05 parallel class T06 finish

边	依赖原因	若强行并行
T01 → T02	无契约则登录「完成」无法否决	功能写完仍对不齐验收
T02 → T03	受保护接口测试需要合法会话夹具	401 测不稳定或假绿
T03 → T04	先分离「从未登录」与「登出后」	200/401 原因混杂，回流难归层
T02 ─┐→ T05	错误体可相对独立改	可并行；但须约定错误形状单一来源
* → T06	PR 收束依赖各步检查点已绿	带红合入，review 与联调再爆

② 事实证据：如何判断能否并行

不要凭感觉，用以下标准硬约束：

类型	判定依据	案例表现
必须串行	共享会话状态	登录 → 鉴权 → 登出失效，读写同一套 Session。阿明主链 T02 → T03 → T04 绝不拆并行。
必须串行	验收互相定义	后一步的“过”以前一步的绿为前提，例如 T04 假设未登录 401 已成立。
可并行	无共享可变点	T05 错误体规范主要动错误封装与快照；与会话主链文件重叠少时可并行。
需汇合	合并前统一	并行支路进 T06 前，做一次错误体与会话路径的联合冒烟，避免“各绿合红”。

并行三问（全是「是」才开第二路）：

两步是否会改同一批文件或同一数据结构？
一步的检查点是否依赖另一步的输出？
合并时是否需要人工解冲突才能保持两边验收？

任一问为「会 / 是」→ 串行。不要用「两个窗口更快」压过依赖。

03 / 执行结论：五分钟画出依赖图

列出 Tn（沿用 Part 05），每步只写一个主检查点。
对每对步骤问：A 的输出是否是 B 的输入？是则画边 A→B。
标出共享可变状态（session、用户表、错误中间件）——相关步骤默认串进一条链。
无边且无共享状态的步骤，标为可并行候选；汇合点通常是 T06 或「联合冒烟」。
把图贴进 Spec / PR 描述，开 Agent 前先定「本轮只跑哪条边」。

案例用法：阿明修复时主链一人串行；错误体 T05 曾与 T03 短并行，合并前补了错误体快照 + 登出路径联合检查，再进 T06。

补充说明：盲并行会长什么样

做法	典型结果	改成
登录与登出两 Agent 同时改	session API 冲突；假绿	T02→T03→T04 串行
未画边就「全都交给 AI」	回到 40+ 文件一锅端	先图后跑，每轮只推进一条边
并行后不做汇合检查	各步绿、合入红	T06 前联合冒烟
用并行「赶联调」	冲突 Diff 更耗时	串行主链通常更快收敛

干货：依赖图是给人看的执行合同，不是装饰。AI 不会自动尊重你没写进 Prompt 的边——开跑时写明「只做 Tn，依赖 T(n-1) 已绿，禁止改 T(n+1) 范围」。

思考笔记：并行不是默认的加速方式

并行只在依赖已经被排除后才会带来速度；如果两个步骤共享会话状态、文件或验收路径，提前并行只是把等待时间换成合并冲突和更难定位的失败。

依赖图的意义，是先让人决定工作如何分叉与汇合，再让 AI 在清楚的边界内执行。主链保持串行、独立支路谨慎并行，通常比“同时开多个 Agent”更快得到可合并的结果。

带着这个思考进入下一章：依赖明确之后，任务风险不同，应该把流程拆到多细、验收到多严？

这一幕带走：能并行的是无共享可变状态的步骤；会话链路通常必须串行。先画边，再动手。下一章：按风险档决定拆多细、查多严。

Part 10 · Harness 选择：按风险定拆法，拒绝一刀切

10 / 选型

先定风险档，再决定拆多细、查多严。任务越接近安全、数据与共享状态，越需要完整的 Harness。

flowchart LR R["评估失败代价"] --> L["低风险：单步 + 冒烟"] R --> M["中风险：2-4 步 + 检查点"] R --> H["高风险：细工序 + 人工门 + 回滚"] H --> A["认证 / 支付 / 权限"]

01 / 选型背景：为什么拆法要跟风险走

契约、证据、工序、闭环是同一套能力，但用多深、拆多细不该一刀切。改一句文案却上完整 T01–T06 是浪费；认证需求却用「短 Prompt 一次生成」，则是阿明周五翻车的结构原因——这并非运气差，而是档位定错。

选型错误的典型想法：「都是让 AI 写代码，流程一样就行。」事实是，风险不同，失败代价天壤之别：文案错了改一行；会话清不掉，可能是安全事故与联调全军覆没。

正如「PART 10 · HARNESS 选择」图示所强调的：任务简单时不要引入复杂 Harness；任务复杂时不要依赖单步生成。本层只回答一件事：开干前先定档，再选配套拆法。

02 / 核心拆解：三档任务的风险与应对策略

① 风险分级矩阵：不同风险为何不能用同一套流程

档位	典型场景	失败代价	推荐 Harness 能力	阿明案例对照
低风险	改文案、加日志字段、调样式	易回滚、影响面窄	单步执行 + 即时检查短契约 + 一次生成 + 冒烟	若认证按此档操作，即为开篇翻车复刻。
中风险	新查询接口、内部工具脚本、非核心 CRUD	功能错、局部回归	串行 Pipeline + Checkpoint 2–4 步 + 每步测试 + 最小证据	接口任务若动到鉴权中间件，需立即升档。
高风险	认证、支付、权限、数据迁移、密钥相关	安全 / 数据 / 大面积不可用	可恢复 Pipeline + Parallel + 决策门完整契约 + 细工序 + 人工门 + 可回滚点	B 端控制台登录 / 登出 / 会话 → 高。

阿明案例定档：应用 Spec v1.0、证据包、T01–T06、关键回流；若按「低」档一次生成，就是开篇翻车的复刻。

② 事实证据：三档任务的具体执行差异

低风险

轻量交付

契约：Goal + 1 条 Acceptance 即可。

证据：只挂被改文件。

工序：一步生成 + 本地冒烟。

闭环：红了改一句再生成，通常够用。

中风险

标准交付

契约：四块齐全，Acceptance ≥2。

证据：相关模块 + 现有测试。

工序：2–4 步，每步有测试检查点。

闭环：失败写回；可不必上 Risk/Rollback 长文。

高风险

加固交付

契约：v1.0 + Risk + Rollback。

证据：最小充分 + 明文禁区。

工序：细拆（如 T01–T06）+ 依赖图；关键路径人工看。

闭环：锁步回流；禁止整模块重生当默认。

人工门

高档必留

会话清理、权限判断、支付状态机、迁移脚本——至少一条路径人眼过一遍，不交给「测绿 = 可合」。

03 / 执行结论：开工前三问如何定档

炸了会怎样？仅展示错 / 局部功能错 / 安全或数据错 → 大致对应低 / 中 / 高。
共享状态多吗？会话、权限、余额、迁移——共享可变状态越多，越往高档靠，并强制串行主链（Part 09）。
回滚容易吗？难回滚（已写库、已发令牌、已迁数据）→ 至少中档起，高档要写 Rollback 点。

拿不准时：

偏安全、鉴权、钱、数据 → 直接按高。
纯展示、文案、日志 → 按低，但 Acceptance 仍要可否决。
介于中间 → 按中起步；一旦出现禁区被踩或联调关键路径，立刻升档，而不是硬扛。

补充说明：定错档会长什么样

错法	样子	后果	纠正
高当低	认证一句 Prompt 一次生成	阿明式周五翻车	升到高：完整契约 + 细工序
低当高	改文案也上六步依赖图	流程疲劳，下次反而跳过	降到低：短契约 + 冒烟
中档漏禁区	接口任务却动到鉴权中间件	范围漂移成高风险事故	Boundary 写死；越界即升档
档位口头不定	边做边觉得「好像挺重要」	检查点忽严忽松	T01 前写明档位，写进 Spec

干货：风险档是开工参数，不是事后复盘标签。阿明若在上午把任务标成「高」，下午的大 Diff 与口头禁区根本过不了自己的门禁。

思考笔记：流程强度应该匹配失败代价

低风险任务不需要被复杂流程拖慢，高风险任务也不能因为赶时间就跳过门禁。真正需要判断的不是“AI 能不能做”，而是这次变更失败后，影响范围有多大、是否容易发现、是否容易回滚。

风险档的作用，是在开工前把这些判断转成具体约束：需要多完整的契约、多少证据、多少检查点，以及哪条路径必须由人复核。档位一旦确定，后续流程就不再依赖临场感觉。

带着这个思考进入下一章：如果人不主动承担契约、证据和验收责任，最容易滑入哪些 AI 编程反模式？

这一幕带走：先定低 / 中 / 高，再选拆多细、查多严。认证默认高档。下一章：把翻车里出现过的坏习惯收成避坑清单。

Part 11 · 避坑：乘客心态清单

11 / 反模式

认证翻车里出现过的，全是可复现的坏习惯。根子往往不是模型弱，而是人坐在副驾——只负责「喊一句、等 Diff」。

flowchart LR P["乘客心态"] --> A["一句 Prompt"] A --> B["整仓上下文"] B --> C["大 Diff"] C --> D["测试红了再生成"] D --> P P -.切换.-> E["司机心态：契约、证据、工序、回流"]

01 / 反模式背景：什么是“乘客心态”

乘客心态：把 AI 当成自动驾驶，自己只负责发车与抱怨路况。组织输入、钉验收、看禁区、做分诊——全甩给模型「看着办」。

阿明上午的乘客时刻：一句「安全一点、流行写法」→ 整仓 @ → 大 Diff PR 写「AI 生成，请 review」。人在流程里缺席，模型就用默认值填空；默认值不等于可交付。

司机心态：你负责契约、证据、工序、闭环与风险档；AI 负责在门禁内写 Diff。你不是乘客，你是组织输入与验收的人。

02 / 核心问题：六种坏习惯如何让责任外置

每一行：坏习惯 · 案例里的样子 · 替换成什么

坏习惯	案例里的样子	替换成
无验收开干	「做个登录」「尽量安全」	先写可否决的 Acceptance
整仓塞上下文	@src 全家桶	最小充分证据包 + 明文禁区
大爆炸 Diff	一次改 40+ 文件	按风险档拆 Tn，一步一检
测红只重试	「再生成一次」/ 换模型硬刚	留证 → 归层 → 写回约束
禁区口头说	聊天里提一句别改哈希	写进 Boundary，每轮 Prompt 再声明
PR 无验证步骤	「AI 写的请看」	贴上手动验收三步 + 检查点结果

03 / 事实证据：坏习惯为何会反复出现

短快感

生成成功 ≠ 交付成功

Diff 铺满屏幕的上午最容易自我奖励；联调才是真实考核。

把「检查点全绿 + 手动路径过」当奖励点。

责任外置

「AI 写的」当挡箭牌

PR 把 review 负担甩给同事，自己不写验证步骤。

作者先按 Acceptance 自测，再请人复核。

工具迷信

换模型当万能药

输入结构不变，只换引擎——闭环病治不好。

先分诊、先写回；模型可换，门禁不能少。

流程疲劳

高档任务偷用低档拆法

「赶联调，先生成再说」——风险档口头取消。

赶工时更要锁步；并行只开无依赖支路（Part 09–10）。

04 / 执行结论：用司机动作替换乘客习惯

开干前：四产物齐（契约 / 证据 / 执行图 / 回流位）——详见 Part 12；缺一不开生成。
生成中：只推进当前 Tn；检查点不过不扩范围；禁区每轮写进 Prompt。
变红时：禁止「同一句重试」；走留证 → 归层 → 写回（Part 06 / 08）。
开 PR 时：描述里贴 Acceptance 勾选结果与手动三步；不写「AI 生成请看」。
复盘时：问「哪条坏习惯又冒头了」，升一版 Spec 或加一条门禁，而不是只骂模型。

一分钟自检（乘客警报）：

我是否说不清「哪一句能否决完成」？
我是否说不清「本轮禁止改什么」？
我是否说不清「当前卡在 Tn 的哪条检查点」？
红了之后，下一轮 Prompt 是否几乎没变？

任一「是」→ 你在坐客运；先补门禁，再呼叫 AI。

补充速查：反模式替换卡

你脱口而出	背后坏习惯	立刻改口
「先做出来再收」	无验收开干	「先写 Acceptance 再生成」
「全丢给它看吧」	整仓塞上下文	「只挂这几份现行文件」
「一口气搞定」	大爆炸 Diff	「本轮只做 Tn」
「再试一次 / 换个模型」	测红只重试	「先贴红证再写回」
「别改哈希啊」（仅口头）	禁区口头说	「Boundary：禁止改哈希」
「AI 写的，帮忙看下」	PR 无验证步骤	「已按下列三步自测通过：…」

干货：避坑清单不是道德说教，是可观察行为替换表。改口令、改 Prompt 结构、改 PR 模板，比「下次注意」有效。

思考笔记：使用 AI 的责任不能外包

“AI 写的”只能说明代码的生成方式，不能说明需求已经正确、变更已经安全，或结果已经通过验收。真正承担交付责任的人，仍然要组织输入、维护边界、检查证据并决定是否合并。

司机心态也不是拒绝自动化，而是把自动化放进清楚的门禁里：让 AI 在当前步骤内提高执行速度，让人保留对目标、风险和最终结果的判断权。

带着这个思考进入下一章：如何把这些司机动作整理成一张开工前即可打勾的清单？

这一幕带走：你不是乘客。你是组织输入与验收的人。下一章：把司机动作收成开干前打勾清单。

Part 12 · 开工清单：把四种 Engineering 变成可执行的检查表

12 / 清单

四产物齐备、四问答清晰，才开第一轮生成。开始后按图推进，变红时按层分诊。

flowchart LR P["Prompt：契约"] --> G{"四产物齐备？"} C["Context：证据包"] --> G H["Harness：执行图"] --> G L["Loop：回流位"] --> G G -- 是 --> S["开始第一轮生成"] G -- 否 --> R["补齐后再开工"]

01 / 清单背景：开工前需要拦住什么

清单不是文档仪式，而是开干门禁。它的核心作用，是防止我们滑回「一句 Prompt + 整仓 @ + 大 Diff」的乘客模式。

用法原则：全部打勾才开第一轮生成。缺一项 = 仍在乘客座位上。高风险任务（认证 / 支付 / 权限）允许清单更长，不允许更短。若阿明上午勾完再生成，OAuth 乱跑与哈希被改的问题，多半进不了第一轮。

正如「PART 12 · 明天就用」图示所强调的：你不是 AI 的被动使用者，而是在设计一套可交付的工作系统。

02 / 核心拆解：四产物与四问答

① 四产物缺一会怎样？

① 契约Goal / Boundary / Acceptance / Non-goals

② 证据包必读文件 ≤ 必要集合

③ 执行图步骤、依赖、检查点

④ 回流位失败如何留证并写回

核心模块	对应产物	打勾标准（可否决）	缺了会怎样
1. Prompt	契约（Spec）	至少一条 Acceptance 能一票否决「做完了」；禁区与 Non-goals 已写。	模型用「流行写法」填空，需求对不齐。
2. Context	证据包	现行关键文件已列；密钥不进包；禁区有文字声明。	发明第二套实现，或踩中哈希 / 权限禁区。
3. Harness	执行图	Tn 列表 + 依赖边 + 每步检查点；风险档已定。	大爆炸 Diff，失败无法锁步，并行导致冲突。
4. Loop	回流位	预留「留证字段」与「只回流当前 Tn」的写法。	红了只会重试或整模块重生，陷入死循环。

② 事实证据：开干前四问如何验收

在点击生成前，请自问以下四个问题，确保逻辑闭环：

完成标准：要完成什么？哪一句能一票否决「做完了」？
依据与禁区：依据是哪些现行文件？禁区写清了吗？
第一步：T01/T02 的检查点是什么？失败停在哪？
变红预案：若红了，下一轮 Prompt 将新增哪条约束？（现在就写草稿，不要等红了再想）

加问（高风险必答）：

风险档是低 / 中 / 高？写进 Spec 了吗？
主链哪些步必须串行？有没有误开并行？
Rollback 点在哪（例如回退到 Tn 已绿 commit）？
哪条路径必须人工看一眼（人工门）？

03 / 执行结论：按风险档裁剪清单

低

可裁短，不可删核

契约可短到 Goal + 1 条 Acceptance；证据只挂被改文件；工序一步 + 冒烟；回流可简化，但仍要「红了改哪句」。

中

四产物标准版

契约四块齐全；证据含测试；2–4 步带检查点；回流模板备用。

高

全量 + 人工门

v1.0 Spec（含 Risk/Rollback）；最小充分证据；细工序 + 依赖图；锁步回流；关键路径人眼过。

禁止

赶工删门禁

「先生成再补清单」= 乘客心态复辟。赶联调时更要先勾四问。

补充示例：认证任务勾完长这样

以下是阿明修复轮开干前的压缩填写，可作为模板修改领域词：

【开工勾选 · 认证 · 高风险】
① 契约：Spec v1.0（注册/登录/登出；登出后 /me → 401；禁改哈希；非目标含 OAuth）
② 证据：session.ts · auth 路由 · error-envelope · auth 测试 · 契约全文
③ 执行图：T01→T02→T03→T04→T06；T05 可短并行；检查点见 Part 05
④ 回流位：红则锁当前 Tn；贴测试名+期望/实际；追加约束后重跑

四问答：
- 否决句：登出后 GET /me 必须 401（另：单测绿、错误体不泄路径）
- 禁区：哈希 / .env / 密钥；不进上下文
- 第一步检查点：T01 验收句无歧义；T02 登录测绿
- 变红预案：继续 Tn，不重做已绿步；写回 session 清理约束

人工门：T04 登出路径人眼过一遍
Rollback：回退至 T03 已绿 commit

Go / No-Go：上面每一行都能指到具体文字或文件 → Go。仍停留在「大概安全、相关文件都给它」→ No-Go，先补产物再开干。

干货：清单打勾的终点不是「表格填满」，而是第一轮 Prompt 已经写得出来——契约摘要、证据列表、本步 Tn、失败停点，同屏粘贴即可开跑。

思考笔记：清单的价值在于阻止错误开始

开工清单不是把流程变得繁琐，而是把最容易被忽略的判断提前完成。只要目标、依据、步骤和失败预案中有一项空缺，第一轮生成就可能把不确定性放大成大 Diff。

清单也不要求所有任务使用同样的重量。低风险任务可以缩短表格，高风险任务则必须保留人工门、回滚点和关键路径验收；可以裁短，但不能删掉判断核心。

带着这个思考进入结语：当清单、工序和回流都成为习惯，AI 编程最终改变的究竟是模型能力，还是个人的交付方式？

这一幕带走：四产物齐 + 四问答清，才开干。开始了就按图推进，按层分诊。下一章收束：认证修完之后，带走可复用的用法。

结语 · 认证修完之后：从「会生成」到「能交付」

收束

从「会生成」到「能交付」，靠的不是更长的 Prompt，而是一套可重复的交付方式。

flowchart LR A["会生成"] --> B["契约"] B --> C["证据"] C --> D["工序"] D --> E["回流"] E --> F["能交付"]

01 / 收束背景：阿明那天后来怎样

周五上午一句模糊的 Prompt 导致下午联调四连爆。停手之后，阿明没有选择换模型硬刚，而是按本篇路径走完：归层 → 修复计划 → 契约 / 证据 / 工序 / 回流。

最终，Spec 升到 v1.0，T04 锁步回流转绿，PR 带上手动验收三步与禁区说明，CI 实打实绿，Reviewer 按同一路径复核后合并。真正换掉的不是模型，是用法。

阶段	翻车上午（乘客模式）	可合并时（司机模式）
输入	「安全一点、流行写法」+ 整仓 @	Spec v1.0 + 最小证据包 + 明文禁区
执行	一口气 40+ 文件	T01–T06，一步一检；T04 单独回流
失败时	再生成 / 换模型	留证 → 归层 → 写回约束
PR	「AI 生成，请 review」	验收勾选 + 手动三步 + 禁区说明
结果	登出后 `/me` 仍 200；哈希被踩	联调路径过；CI 绿；可合并

真正换掉的不是模型，是用法：人回到司机座——组织输入、钉验收、看禁区、按层分诊；AI 在门禁内写 Diff。

02 / 核心拆解：从个人案例带走什么

这套方法论的核心在于四件套与配套能力。骨架不动，把认证验收句换成新领域的可否决句即可迁移。

① 四件套：钉死交付标准

任务契约Goal · Boundary · Acceptance · Non-goals

证据包最小充分 · 明文禁区

可检查工序Tn · 检查点 · 依赖图

失败回流留证 · 归层 · 写回

件套	核心要素	钉死什么	缺了会回到哪
契约	Goal · Boundary · Acceptance · Non-goals	验收与范围；模型不能替你做产品决定	OAuth 乱跑、「看起来完整」当完成
证据包	最小充分 · 明文禁区	现行实现与禁区；挡住「流行写法」改哈希	第二套 session / 错误体泄路径
工序	Tn · 检查点 · 依赖图	检查点与停点；大 Diff 拆成可续跑步骤	联调才爆、不知回滚到哪
回流	留证 · 归层 · 写回	失败进下一轮文字；禁止同一句重试	换模型空转、同一坑第二遍

② 配套能力：归层、分诊与定档

翻车先归层（Part 01）：先判断是契约、证据、工序还是闭环问题。
再修按序（Part 08）：契约 → 证据 → 工序 → 闭环。
开干前定档（Part 10）：低 / 中 / 高风险决定拆分粒度。

配套能力

归层 · 分诊 · 定档

翻车先归层（Part 01）；再修按契约→证据→工序→闭环（Part 08）；开干前定低/中/高（Part 10）。

胜利标准

不是「生成成功」

别人能合并、联调过得去、上线不埋雷——才是个人交付的胜利。

一句话：用法先于模型。四件套齐了，再生成。

03 / 执行结论：下次换题只换领域词

这套流程可以无缝迁移到其他高风险任务，例如支付退款：

【迁移示例 · 支付退款 · 高风险】
Goal: 已支付订单可发起退款；退款成功后余额与订单状态一致
Boundary: 只改 refund 模块；禁止改账本写入旁路；禁止碰密钥
Acceptance:
  - 退款单测绿
  - 手动：支付成功 → 退款 → 余额回滚正确 → 重复退款被拒
  - 错误体不泄内部账本路径
Non-goals: 本期不做部分退款、不做跨境
Evidence: 账本服务现行实现 · refund 路由 · 错误体规范 · 退款测试
（其后：拆 Tn、定依赖、红了锁步写回——与认证同一套）

执行五步法

定档——支付 / 权限 / 迁移默认高；文案日志可低。
勾清单——四产物 + 四问（Part 12）；No-Go 不开干。
按序加固——说清楚 → 给依据 → 跑可靠 → 变更好。
红了分诊——契约 → 证据 → 工序 → 闭环；乱序不开枪。
人工门——关键路径必须人眼过一遍。

思考笔记：可复用的不是答案，而是交付方式

这次认证案例的具体接口、文件路径和测试名称都属于当前项目，但它背后的交付方式可以迁移到支付、权限、迁移和其他高风险任务。变化的是领域词，不变的是契约、证据、工序、回流和验收。

当 AI 从“替我完成一项功能”变成“在明确边界内推进一组可验证步骤”，人的角色也从等待结果，转为设计约束、判断证据和承担最终决策。

全文留给你的问题：下一次呼叫 AI 之前，你能否先写出目标、依据、第一步检查点，以及失败后准备写回的约束？

全文带走：会生成不是胜利。契约 · 证据 · 工序 · 回流——齐了，再生成；红了，先归层，再写回。

← AI Agent 总览吃透 AI Agent →