AI 驱动的全流程研发实践：从原型到上线的一人开发探索

本文是一次 30 分钟内部分享的完整底稿，基于两个真实项目的先后交付经历：

• UTP/ui-automation：React 编辑器 1:1 重写为 Vue 2
• KC/fe-super-assistant：Electron 智能终端（KC-CLI / Kooky）

两个项目没有继承关系，但共用同一套 AI 研发工作流。本文试图回答：当 AI 能写代码之后，人做什么、AI 做什么、两者如何对齐才不出事。

0. 为什么要分享这个

过去一年，我用同一套流程先后一个人交付了两个中大型项目。一个是把已有的 React 编辑器逐字复刻为 Vue 2，另一个是从零开始的 Electron 智能终端。它们的技术栈、领域、难点完全不同，但流程是同一套。

这说明这套流程不是"某个项目的巧合"，而是当 AI 深度介入研发时，能稳定落地的一种工作方式。

先看结果

在讲方法之前，先报一组数字——都是从两个项目的 handoff 文件系统时间 + git log 里直接拉的。

口径说明：下面的"流程期"指 handoff 文件从创建到最后修改的时间窗口——也就是这套流程真正在上岗的那段时间。handoff 建立之前的探索期不算，因为那时候还没成体系。

项目一：UTP / UICaseDetailV3（React → Vue 2 1:1 复刻，三端：前端 + agent + 服务端）

项目二：KC / fe-super-assistant（Electron 智能终端 Kooky）

两个项目加起来（仅前端可见部分）：

• 跨度 19 个日历天（UTP 12 + KC 7）
• 严格串行：UTP 4-02 收尾 → 中间空档 6 天 → KC 4-09 启动
• 210 次提交 / 平均每天 ~11 个提交
• 约 7.9 万行净增前端代码
• UTP 的 agent + 服务端不在本地仓库，未计入，三端合计实际更高
• 同期我是一个人，没有队友分担

对比传统意义的产出直觉："一个人 19 个日历天，从零做出两个中大型项目的前端主体（含 React→Vue 1:1 复刻 + Electron crash-safe 恢复这种复杂状态机子系统），另加一个项目的后端三端对接"——这个密度在传统流程下基本不成立。

更关键的是：这个节奏不是"AI 写得快"带来的，是"流程让返工少"带来的。下面讲这套流程是什么。

1. 问题：AI 编码的三个失控点

在有任何流程之前，先看一下不加约束的 AI 编码会出什么问题。我实际踩过的有三类：

1.1 上下文失控

• 同一个需求开了三个会话，三个会话各自对项目状态有不同假设
• 昨天定好的设计方案，今天新会话完全不知道
• 子 agent 不知道主 agent 做过什么决定
• 结果：不断"重新解释项目"、不断回到原点

1.2 意图漂移

• 让它改一个 bug，它顺手重构了周围三个函数
• 让它加一个字段，它觉得"既然改到这儿了"顺便优化了错误处理
• 你看 diff 一半都是你没要的

1.3 质量黑箱

• 跑通 ≠ 对齐 PRD
• 尤其在 1:1 复刻场景：代码能编译、页面能打开、跟源版完全不像
• AI 自己说"已完成"，但没人验证过它真的对齐了参考实现

这三件事不解决，AI 写得越快，返工越多。下面是我这一年总结的对策。

2. 整体架构：控制塔 + SDD 双层

我的工作流分两层：

• 项目层：控制塔（Control Tower） —— 管项目整体状态、规则、历史
• 任务层：SDD（Spec-Driven Development，由 superpowers 驱动） —— 管单个需求怎么从想法走到实现

控制塔回答"我们在哪"，SDD 回答"我们怎么走下一步"。

2.1 控制塔：项目级的"大脑备份"

每个项目根目录下有一份 control-tower.md，回答三件事：

1. 项目整体在什么阶段
2. 新会话怎么启动
3. 遵守什么规则

它不记录具体 bug 修复细节，那些细节在 handoff 里。控制塔是索引页。

KC 项目的控制塔截选：

## 新会话启动流程
1. 读本文件 — 了解项目阶段和规则
2. 读当前 handoff — 了解具体做什么、做到哪了、下一步
3. 读护栏 — 按需求类型读对应护栏
4. 读当前 spec / plan（如有活跃的）
5. 开始工作
6. 每次提交 — 同步更新 handoff
7. 实现完成后 — 派审计 agent 对照参考实现审查，修复后再标记完成

这段被 CLAUDE.md 引导每次会话开头读一遍。所以即使换了会话、换了模型、换了人，开场白是一样的。

Handoff：工作线的进度单

每条独立工作线一份 handoff。KC 项目同时跑着 12 条 handoff：

handoff 的关键约束是"每次 git commit 同步更新 handoff"。这条规则保证了：

• 任何人（包括未来的我、包括 AI）打开 handoff 看到的都是"截至最新 commit 的真实状态"
• Commit message 里写一句话，handoff 里展开写是非、证据、下一步
• 会话被砍掉、上下文丢失都不怕，handoff 是唯一真相源

护栏（Guardrails）：事故驱动的规则沉淀

这是整套流程里我最骄傲的一块。

规则是：只记录事故，没出过事的规则不写。

UTP 项目的 API 对接护栏里有一条 Rule 12：

后端数据结构必须查 Swagger + 真实数据验证

事故案例：录制步骤不显示。外层 text: "打开网址【...】" 被当 JSON 使用；parentId: "root" 被 !step.parentId 过滤为子步骤。

每条规则后面都跟着一个具体事故。好处是：

• AI 下次不会犯同一个错（因为会话启动就读了护栏）
• 人也不会犯（因为 CLAUDE.md 里"编码铁律"写着"每次修改代码前默念"）
• 规则有可追溯的正当性，不是拍脑袋教条

UTP 项目现在有 Rule 12-25 共 14 条，每一条背后都是一个"当时想死"的 bug。

2.2 SDD：任务级的执行流水线

控制塔管的是"这些事在做"，SDD 管的是"这件事怎么做"。

SDD 由 superpowers skill 套件驱动，完整流水线是：

brainstorming → spec → plan → implement → audit

• brainstorming：跟用户对齐到底要做什么。产出是一份 open questions 被消化完的简要方案
• spec：把方案写成规范文档。技术细节、数据结构、接口形态、边界条件
• plan：把 spec 拆成可执行步骤。每一步有验收标准
• implement：按 plan 走。严禁"顺便"做 plan 之外的事
• audit：派一个独立 agent 对照参考实现/PRD 逐条审查

这里面最反直觉的是 audit。为什么要派一个独立的 agent？因为让写代码的同一个 agent 自审，它会选择性地"觉得已经做完了"——不是撒谎，是认知盲区。独立 agent 没有上下文负担，只拿 spec 和代码对照，能发现"差不多"和"一模一样"的差别。

2.3 两层如何配合

Handoff 是两者的接缝：

• 每个需求在 control tower 里登记
• 创建对应 handoff
• SDD 流水线产出 spec/plan 登记在 handoff 中
• 实施进度同步到 handoff（不是 superpowers 自建的 task 列表，那个是 AI 内部用的）
• 完成后 spec/plan 归档，handoff 标记完成

这套机制让"长程项目"成为可能。KC 项目已经跑了三个月、几十次会话、多个模型切换，但任何时候进入都能三分钟找到位置。

3. 开发提效：并行化与模型分工

流程跑顺之后，下一个问题是速度。一个人做两个项目，加起来代码量不小，靠单线程对话是做不完的。

3.1 worktree + 多窗口：把自己变成一个团队

Git worktree 允许一个仓库同时检出多个分支到不同目录。我的用法是：

kc/fe-super-assistant/              # 主工作区
kc/fe-super-assistant-terminal-info/ # worktree 1
kc/fe-super-assistant-context-menu/  # worktree 2
kc/fe-super-assistant-fork-session/  # worktree 3

每个 worktree 开一个 Claude Code 窗口，各跑一条 handoff。物理上就是三个终端窗口在同时工作。

适用场景：

• 任务之间没有代码耦合（改不同模块）
• 任务之间没有决策依赖（不需要先决定 A 再决定 B）
• 每条 handoff 都已经有 spec/plan，不需要我频繁介入

反模式：

• 多个 worktree 同时改同一个文件（合并时地狱）
• 前期方案未定就开并行（会产生分叉的设计，后面合不回来）
• 超过 3 个并行（人脑就跟不上了，AI 会开始"幻觉别的 worktree 的状态"）

实际体感：并行 2-3 个稳定收益，4 个开始边际递减，5 个净亏。

3.2 不同模型干不同的事：四阶段流水线

这是我这一年最关键的一个认知升级：不是"哪个模型更强就用哪个"，而是按阶段选模型。

最终沉淀下来的工作流是一条四阶段流水线：

flowchart LR
    subgraph P1["Phase 1 · 快速实现"]
        A["Claude Code<br/>(Opus)"]
    end
    subgraph P2["Phase 2 · 并行修 bug"]
        B["Codex<br/>(GPT-5.4-thinking)"]
    end
    subgraph P3["Phase 3 · 反向生成 PRD"]
        C["Claude Code<br/>(Opus)"]
        D["人工审核 ✅"]
    end
    subgraph P4["Phase 4 · 逐章对齐"]
        E["Codex<br/>(GPT-5.4-thinking)"]
    end

    P1 -->|主流程跑通| P2
    P2 -->|bug 批量清完| P3
    C --> D
    P3 -->|PRD 定稿为唯一真源| P4
    P4 -->|未对齐事项逐一修复| F((上线))

    classDef claude fill:#dbeafe,stroke:#2563eb
    classDef codex fill:#fef3c7,stroke:#d97706
    classDef human fill:#dcfce7,stroke:#16a34a
    classDef done fill:#f3e8ff,stroke:#9333ea

    class A,C claude
    class B,E codex
    class D human
    class F done

Phase 1：Claude Code 快速实现（Opus）

目标：功能完全实现，只保证主流程没问题。

不追求完美，不修边角 bug，不做代码清洁。核心是让所有功能路径都"跑得通"。Opus 的特性——快速多回合、容忍试错、会话启停灵活——在这个阶段最大化发挥。

配合 worktree 多窗口并行（3.1 节），可以同时推进多条 handoff，Phase 1 的吞吐非常高。

Phase 2：Codex 并行修 bug（GPT-5.4-thinking）

Phase 1 留下的 bug 丢给 Codex（OpenAI 的 cloud agent，跑 GPT-5.4-thinking）。Codex 的优势：

• 并行：多个 bug 同时开 task，各自独立修复
• 深度思考：GPT-5.4-thinking 模式擅长长链路推理，适合"根因不明显"的 bug
• 隔离环境：每个 task 有独立沙箱，不会交叉污染

这一轮的目标是把主流程之外的边角都修干净，为下一阶段的 PRD 审阅做准备——如果代码本身还一堆 bug，审阅实现度没有意义。

Phase 3：Claude Code 反向生成 PRD + 人工审核

这是整条流水线里最反直觉的一步：先实现，后写 PRD。

传统流程是"PRD → 设计 → 实现"。我的流程是反过来的：

1. Claude Code 从工程代码、handoff、spec 等文档中反向生成 PRD——它已经"看见"了完整实现，所以产出的 PRD 非常贴合实际
2. 人工审核 PRD——我逐章阅读、修正、补充，确保 PRD 反映的是"应该做成什么样"而不是"代码碰巧做成了什么样"
3. 审核定稿后，这份 PRD 成为唯一真源（Single Source of Truth）

为什么要反向？因为在快速迭代中，实现往往比文档跑得远。与其维护一份不断过期的 PRD，不如在实现稳定后一次性提取，再由人定性。

Phase 4：Codex 逐章审阅实现度（GPT-5.4-thinking）

拿 Phase 3 定稿的 PRD，让 Codex 逐章对照代码审阅：

• 每一章产出"对齐 / 未对齐"清单
• 未对齐事项标记具体文件和行号
• 逐一修复，修完再审，直到全部对齐

为什么用 Codex 而不是 Claude Code 自审？

• 隔离上下文：Codex 没有参与 Phase 1 的实现，它不会"觉得自己做过所以一定对"
• GPT-5.4-thinking 的审计特性：慢想、长链路推理、不急于给"通过"——正好是审计需要的气质
• 并行审阅：多章可以同时开 task，速度不受限于单线程

为什么是这个顺序

四个阶段的顺序不是随意的，每一步都依赖前一步：

核心洞察：人的判断力集中在 Phase 3 的审核——这是整条流水线里唯一的人工瓶颈，也是质量的最终锚点。其余三个阶段全部由 AI 执行。

模型分工总结

4. 工具链：让 AI 在真实环境里工作

光有流程不够，需要一组"AI 的工具箱"。我现在的配置：

4.1 spec-tower：多 spec 的调度中心

一个项目同时存在多个 spec/plan。spec-tower 负责：

• 登记所有活跃 spec
• 跟踪每个 spec 的状态（draft / reviewed / implementing / done）
• 引导"新会话先读哪个 spec"

实际作用类似"所有 spec 的控制塔"，避免散落。

4.2 spec-twin：实现镜像审计

做 1:1 复刻时非常关键。它的思路是把参考实现作为"twin"，审计时拿你写的代码跟 twin 对照着看。

UTP 项目里，.spec_control/真相源 指向 React 源码 controller_ui，所有审计 agent 都会去那里对照。KC 项目里，真相源 指向 /Users/icesword/Documents/AIProjects/x（竞品参考实现）。

"审计时对照"这件事听起来平平无奇，但落地后威力巨大——人工审计会偷懒（肉眼对 500 行代码谁都会走神），AI 不会。

4.3 gitnexus：代码知识图谱

传统 grep 的问题：找不到动态引用、间接调用、跨文件的逻辑链。

GitNexus 基于代码知识图谱，能查：

• gitnexus_context({name}) —— 这个函数/组件被谁调用
• gitnexus_impact({target, direction}) —— 改它会影响哪里
• gitnexus_query({query}) —— 按概念搜索相关代码
• gitnexus_cypher({query}) —— 自定义图查询

UTP 护栏里有一条 Rule 22：修改代码后，必须用 GitNexus 评估影响范围。
Rule 23：修改数据流前，列出全部消费场景逐一验证。

这两条都是在 grep 漏掉调用者、改完一处漏改三处之后写下的。

4.4 superpowers：SDD 的骨架

superpowers 是一整套 skill 的集合，涵盖：

• brainstorming（需求对齐）
• writing-plans（写实施计划）
• debugging（结构化 debug 流程）
• code-reviewer（审计 agent）
• using-superpowers（元 skill，告诉 AI 什么时候该用哪个）

核心理念是"过程类任务必须按流程走"——debug 不是"看一眼猜一下"，写 plan 不是"随手列几条"。这些流程都沉淀成 skill，AI 每次都会严格走。

4.5 superdesign：让 AI 长出项目的设计语言

普通 AI 画 UI 的问题：出的设计单看很漂亮，放回项目里很违和——配色、间距、字重都跟既有组件对不上。

superdesign 的工作方式是三段式：

1. Design System Extraction —— 从项目的截图/现有组件提取设计系统：色板、字体、间距、圆角、阴影，输出结构化 JSON
2. Design Generation —— 在这个 system 约束下，根据文字描述生成新页面。比如我说"加一个通知中心，支持按 workspace 分组"，它会用项目已有的颜色、字体、卡片样式来画
3. Design Iteration —— 在生成好的设计上继续改

一句话概括：superdesign 不是让 AI 画图，是让 AI 先把项目的设计语言提取出来，再在这个语言内造句——所以出的设计不会突兀，像是项目自己长出来的。

KC 项目的通知中心、功能介绍悬浮层、Tab 溢出折叠都是这么出的，一版就能用。

4.6 CDP：让 AI 自己打开前端看

这个是效率放大器里最狠的一个。

CDP（Chrome DevTools Protocol）让 AI 可以：

• 自己打开前端页面
• 自己点击、输入、操作
• 自己读 console、读 DOM、读 network
• 自己发现 bug，自己验证修复

等于AI 有了眼睛和手。

下面两个真实案例。

5. 关键实战一：两个硬核 CDP 案例（KC 项目）

案例 A：污染 transcript 的视口清洁

背景：KC 的 ko teams 功能支持 leader + teammate 协作。leader 通过 SendMessage 给 teammate 派任务。重启应用后，这些会话要能恢复。

bug 现象：
重启后，leader 的首屏把几个小时前创建过、后来已经删掉的旧 alias（pm-2、backend-2）也回放出来了。用户感觉"重启之后莫名其妙多出两个不存在的团队成员"。

根因：

• 磁盘上的 transcript（session history）里确实有 pm-2 / backend-2 相关行
• Claude CLI 恢复会话时会把 transcript 全文回放
• UI 没做视口层的"旧 alias 过滤"

修复方向：

• main-process 检测到 restored leader 有 generatedAliases 时，回传 restoreHints.clearStaleLeaderHistoryOnRestore
• renderer 在 Claude resume 成功且稳定后，只清洁本地 leader 视口，不改 transcript、不改 sessionId
• 关键约束：磁盘上的 transcript 保持不动（保留审计、避免误删），只做 UI 视口过滤

AI 自检流程（这里是重点）：

传统做法：我改完代码，手动打开应用、手动触发重启、手动截图对比。慢、容易漏、不 repeatable。

CDP 做法：我让 AI 自己做完整回归：

1. 拿一个真实的 polluted transcript ID：31ada4e3-c208-4735-8a97-bb53c465e302（磁盘里确实有 pm-2 / backend-2 段落）
2. AI 自己启动应用
3. AI 通过 CDP 让应用进入 restored leader 状态
4. AI 读取首屏 DOM 文本
5. AI 断言："文本中应不含 pm-2 / backend-2，但磁盘 jsonl 应仍含这两段"
6. AI 分别验证两个断言，都通过才算完成

为什么这个案例好讲：
这是一个"双面"验证——UI 必须干净，磁盘必须保留。只验证 UI 会漏掉"是不是顺手删了磁盘"；只验证磁盘会漏掉"UI 到底清没清"。AI 自己跑完两端，比人手工快一个量级，而且 repeatable——下次再改这块，同一套断言能继续跑。

Handoff 里的原话是这样的：

2026-04-14 用真实 polluted transcript 31ada4e3-c208-4735-8a97-bb53c465e302 做 CDP 复验：磁盘仍有 pm-2 / backend-2，但恢复后的 leader 首屏文本已经不再出现这两段旧污染

这一句话，AI 自己打出来，自己验证完，人只看这一句。

![[handoff-case-A.png]]

[!tip] 截图素材
来源：.spec_control/handoffs/terminal-persistent-session-handoff.md 第 62 行附近（"用真实 polluted transcript ... 做 CDP 复验"那一段）
建议截：整个自然段 + 上下两条 bullet 点，展示"根因 → 修复 → CDP 复验"的完整叙事链

案例 D：高风险 prompt 的行为验证

背景：leader 看到用户输入 让pm调研下有哪些好用的cli 这种指令时，早期版本会错误地调用 Agent(name=pm) 新建一个 pm 角色，而不是 SendMessage(to=pm) 给现有的 pm 派任务。结果就是产生了一堆 pm-2、pm-3 脏 alias，跟案例 A 里的 transcript 污染问题联动。

bug 现象：

• 用户意图：让现有的 pm teammate 做调研
• 实际行为：leader 创建了一个新的 pm-2
• 长期副作用：transcript 污染、inbox 路径错乱

修复方向：

• 调整 leader 的 system prompt，明确"已存在 teammate 时优先 SendMessage，不要新建 Agent"
• 主进程层面加 canonical inbox 别名机制，即使 leader 写错了路径，也能落到 canonical inbox

AI 自检（这里是重点——行为类验证）：

行为类 bug 的难点是：它不像视觉 bug 一样肉眼就能看见。页面看起来一切正常，但交互路径错了。

传统做法：读代码、猜路径、写单测、祈祷覆盖全。

CDP 做法：

1. AI 通过 CDP 注入 prompt：让pm调研下有哪些好用的cli
2. AI 监听 Claude 的 tool-call 序列
3. AI 断言：
   • 不应看到 Agent(name=pm) 调用
   • 应看到 SendMessage(to=pm) 调用
   • 应在 leader 回复里看到"直接让 pm 执行调研，不新建角色"这种意图说明
4. AI 继续验证副作用：
   • 检查 research-dev-team/inboxes/pm.json —— 应有新任务、应被标记为已读
   • 检查是否有新产生的 pm-2 inbox 内容 —— 应为空

为什么这个案例好讲：
这把 "AI 自测" 从"页面对不对"推进到了"行为对不对"。最终的断言非常干净：

leader 不再调用 Agent(name=pm)，而是先输出"直接让 pm 执行调研，不新建角色"，随后只调用 SendMessage(to=pm)

这是真正意义上的交互路径回归。未来任何人改 leader system prompt，这个回归都能自动跑一遍，确保不会把关键行为改坏。

![[handoff-case-D.png]]

[!tip] 截图素材
来源：.spec_control/handoffs/claude-agent-team-auto-split-handoff.md 第 43-45 行（"2026-04-14 07:05 再次对高风险 prompt 让pm调研下有哪些好用的cli 做 CDP 注入验证"那一段）
建议截：整段断言列表，展示 "leader 不再调用 Agent(name=pm)" + "只调用 SendMessage(to=pm)" + "未再产生 pm-2 inbox 内容" 三条行为断言

小结：CDP 自检的三个层次

• Level 1：视觉自检 —— 页面长对了吗？（传统 UI 回归）
• Level 2：状态自检 —— DOM/store/磁盘状态对了吗？（案例 A）
• Level 3：行为自检 —— 用户意图触发了对的交互路径吗？（案例 D）

Level 2、3 是过去需要 QA 或端到端测试团队才能做的事，现在 AI 能自己做。人的角色从"手动验证"变成"定义断言"。

6. 关键实战二：如何 1:1 从 React 复刻为 Vue（UTP 项目）

这是另一个项目的核心挑战。把一个在线上跑的 React 编辑器（UICaseDetailNew + UICaseDetail）用 Vue 2 重写为 UICaseDetailV3，要求：

• 完全相同的后端对接能力（所有 API 不能变，旧版后端不改）
• 更好的交互体验（可以优化）
• 不改旧版代码，全部改动限制在 UICaseDetailV3/ 目录
• 涉及三端：前端、agent、服务端

6.1 先定目标与策略

目标很明确：1:1 复刻，strict PRD-level parity。

但怎么并行？67 个 PRD 模块，从 M01 到 M67，涵盖页面加载、连接状态机、URL 导航、Tab 管理、远程投屏、录制、步骤编辑（18 种 action + 5 种定位方式）、AI 对话（SSE 流式）、脚本保存加载、执行、设置面板……

第一步不是写代码，而是做依赖分析。产出了一份 dependency-parallelization-matrix.md，核心结论是：

没有任何 PRD 模块是完全独立的。 但可以按文件所有权拆成 4 个并行车道（lane），每个车道有明确的文件边界。

flowchart TB
    subgraph 策略层
        DM["dependency-parallelization-matrix.md<br/>67 个 PRD 模块的依赖分析"]
        MWO["multi-worktree-agent-orchestration.md<br/>4 车道 + 审计 agent 调度方案"]
        DM --> MWO
    end

    subgraph 执行层[4 个 worktree 并行]
        L1["Lane 1: Toolbar / Nav / Settings<br/>M03-M08, M18, M26-M29, M63, M65"]
        L2["Lane 2: Stage / Remote / Transport<br/>M09-M17, M19-M25, M61-M62, M66"]
        L3["Lane 3: Dock / Logs / Convo<br/>M30-M41, M35-M37"]
        L4["Lane 4: Steps / Execution / Persistence<br/>M42-M60"]
    end

    subgraph 审计层
        RA["驻场审计 agent<br/>在每个 guardrail checkpoint 做多维度对比"]
    end

    MWO --> L1
    MWO --> L2
    MWO --> L3
    MWO --> L4

    L1 -->|checkpoint| RA
    L2 -->|checkpoint| RA
    L3 -->|checkpoint| RA
    L4 -->|checkpoint| RA

    classDef strategy fill:#fef3c7,stroke:#d97706
    classDef lane fill:#dbeafe,stroke:#2563eb
    classDef audit fill:#fee2e2,stroke:#dc2626

    class DM,MWO strategy
    class L1,L2,L3,L4 lane
    class RA audit

6.2 两种角色分离：实现只管实现，审计只管审计

这是整个 UTP 复刻流程的核心设计——严格的角色分离：

实现 agent（每 lane 一个 dev agent）

• 只管实现，不做自我审计
• 每个 lane 有明确的文件所有权（Forbidden 列表写死不能碰哪些文件）
• 多路并行，每个 agent 在自己的 worktree 里工作，物理隔离
• 主会话作为 Program Manager：不写代码，只调度、合并、仲裁冲突

审计 agent（1 个驻场审计，跨 lane 复用）

审计 agent 在每个 guardrail checkpoint 触发，做多维度对比：

审计产出不是"通过 / 不通过"，而是一份覆盖矩阵（fidelity-matrix），精确到每个 PRD 模块：

Strict 1:1 parity complete: 49 / 67 (73.1%)
Mock-only (intentionally out of scope): 18 / 67 (26.9%)
Missing / blocked: 0 / 67 (0%)

"49 个模块 strict 1:1 parity"不是 AI 自己说的"差不多了"——是审计 agent 逐模块对照 React 源码签的字。

6.3 审计的严厉程度：比人做 code review 还狠

看看审计 handoff 里的执行规则就知道这不是走过场：

• Excel 驱动的逐行代码审计，必须遵守 gitnexus-agent-audit-sop.md
• 每一行都必须完成旧版源码深读、V3 源码深读、服务端深读、日志深读，不能因为行看起来简单就跳过
• 如果预期包含结果语义，不能只因为"入口 / API / 服务端都还在"就下 ALIGNED；必须补齐成功 / 失败信号
• 代码审计必须同时对照旧版实现、Swagger 文档和护栏，不接受"只看当前 V3 自洽"

甚至还有结果语义专项复扫——发现审计自己也会犯错：把"链路存在"误判成"创建成功"。于是再开一轮复扫，把所有带结果语义（保存 / 创建 / 执行 / 上传 / 切换 / 关闭）的审计行重新校准。

审计在审计自己。 这就是为什么最终产出的覆盖率数字可信。

6.4 UI 保真护栏：二选一，禁止混用

护栏里有一条 Non-Negotiable Rule：

任意用户可见区域，必须选一种所有权模式：

1. Source-aligned mode —— 保留 React DOM 结构 + 复用原 CSS
2. Rewrite mode —— Vue 自己的 DOM + Vue 自己的样式契约

永远不要在同一个交互单元里混用。

混用的后果是：改一个 DOM 节点，旧 CSS 断一半；加一条 Vue 样式，旧 layout 飘；最后变成打补丁地狱。

这条规则决定了每个区域在开工前就得表态——选 A 还是选 B——而不是写着写着凭感觉。

6.5 API 对接：Rule 12-25 背后的血泪

API 对接护栏的每一条都是事故。挑三条最有代表性的讲：

Rule 12：Swagger + 真实数据双重验证

对接后端 API 前，禁止仅靠读前端代码推断字段含义。必须：

1. 先查 Swagger 文档确认数据结构
2. 用真实数据验证（console.log 打印真实响应）
3. 特别注意同名字段在不同层级含义不同

事故：录制步骤不显示，因为外层 text 是自然语言、内层 text 是 JSON action，前端把外层当 JSON 用了。

Rule 15：旧版 API 调用方式必须读旧版调用方源码

不能只看 api/*.js 的函数签名（如 saveElementOrBindStep(model)），必须读旧版组件中实际调用这个函数的代码。

事故：

• 元素保存旧版传 FormData + imageFile 二进制，V3 传 JSON 导致 image 类型元素保存失败
• sessionStorage.getItem('userInfo') 返回 {value: {domainAccount: ...}}，V3 没解包导致 account 永远为空

这条规则的深层含义：函数签名是谎言，调用方才是真相。AI 也容易被函数签名骗，护栏强制它去读 caller。

Rule 22 + 23：改代码前先查影响

Rule 22: 修改代码后，用 GitNexus 评估影响范围
Rule 23: 修改数据流前，列出全部消费场景逐一验证

事故：改了 store 里一个字段的结构，主路径验证通过，但有两个边缘消费点（一个在 debug 面板，一个在导出 JSON）漏掉了，上线之后才被用户发现。

这两条是工具 + 流程的组合：工具（GitNexus）提供影响范围图，流程（逐一验证）确保不偷懒。

6.6 真相源体系

UTP 项目对"真相源"做了显式分层，审计 agent 按优先级引用：

"任何 UI / 交互上的取舍，先问'React 原页是什么'，再问'Vue2 怎么实现'。"

6.7 小结：1:1 复刻的方法论

回顾整个 UTP 复刻流程：

1. 定目标：strict 1:1 PRD parity（67 模块）
2. 定策略：依赖分析 → 4 车道并行 + 文件所有权隔离
3. 分角色：实现 agent 只管写、审计 agent 只管比、主会话只管调度
4. 多维审计：UI 保真 + API 协议 + 行为语义 + 护栏规则 + 交叉影响
5. 覆盖矩阵：精确到每个 PRD 模块，"全绿才算完"
6. 审计审计自己：发现审计口径偏差后开结果语义复扫

核心理念：AI 做的"完成"和人认的"完成"之间有一道鸿沟——审计 agent + 覆盖矩阵就是那座桥。

7. KC 项目的其他 handoff 精华

两个项目的核心案例讲完了，再从 KC 的 handoff 里挑几个通用的经验：

7.1 crash-safe 恢复：spec 驱动复杂子系统

终端异常中断恢复是个大坑：

• 用户 kill -9 整个应用怎么办？
• 写了一半的 journal 怎么办？
• 结构损坏的 checkpoint 怎么修？
• 各种 crash 时机的组合（crash matrix）要覆盖多少？

这种子系统绝对不能"看着写"。KC 在做这块时走的是完整 SDD：

1. 2026-04-12 terminal-crash-safe-recovery-design.md —— 主进程 journal + checkpoint 的初版设计
2. 2026-04-14 terminal-crash-safe-recovery-phase-2-design.md —— 结构 journal + repair + compaction + crash matrix（二阶段）
3. 2026-04-14 terminal-restore-strategy-design.md —— 默认 Claude-only，普通 shell 恢复为新终端

经验：越是复杂的状态机子系统，越要先写 spec。spec 不是"写给别人看"，是写给自己想清楚。写 spec 的过程会暴露 60% 的设计漏洞。

7.2 PRD 对齐专项：结构化复核 + 子 agent 分工

KC 有一份 _ENGINEERING-TODO.md，是最早的工程待办。到了某个阶段，我们不确定所有条目都按 PRD 做对了，于是开了一个专项：

1. 先派多个子 agent 并行复核（一个负责 UI 条目、一个负责交互、一个负责数据流）
2. 每个 agent 产出"候选问题清单"
3. 主会话整合去重
4. 按验证后的清单逐条修复

经验：对齐类任务非常适合子 agent 并行。每个 agent 只看自己那部分，结果干净；主会话做整合判断，成本低。

7.3 渐进式披露：references/full-capabilities.md

KC 的 Claude skill kc-terminal 有一个设计：主入口 skill 文件只讲最常用的 20%，其余 80% 放在 references/full-capabilities.md。

AI 默认只加载主入口。需要用到高级能力时，主入口会说"详见 references/full-capabilities.md"，AI 才去读。

经验：skill/spec 不要一次塞满。分层披露让 AI 在简单任务上不被长文档拖累，在复杂任务上又能查到细节。这跟 control-tower 是索引页是一个道理。

7.4 真相源的意义

KC 的 control-tower 里明确写了：

真相源

| 来源 | 路径 | 说明 |
| 参考代码 | /Users/icesword/Documents/AIProjects/xxxxxx | 竞品/参考实现，审计时对照 |

每当设计拿不准、实现疑点多时，审计 agent 会去真相源对照。这避免了"两个 AI 互相说服对方"的荒谬场景——永远有一个外部基准。

8. 反思与边界

分享到这里可能听起来"这套流程完美无缺"。其实不是。

8.1 这套流程什么时候是过度工程

• 一次性脚本 —— 写完就扔的 100 行 Python，不需要 spec
• 纯探索性原型 —— 核心是"看看能不能做到"，流程反而拖慢探索
• 很小的 bug 修复 —— 一行 typo，直接改就行，不要开 handoff

判断标准：这件事做错了会不会有代价？代价大就用流程，代价小就直接做。

8.2 一人开发 vs 团队协作

这套流程看起来很"团队化"——handoff 像是交接单、spec 像是技术评审、审计像是 code review。其实对一人开发反而更重要：

一个人意味着没有同事帮你兜底。队友的价值一半是审你的代码，一半是当你断片时帮你找回上下文。一个人开发，这两件事都得自己做。Handoff + 审计 agent = 把"队友"内化到流程里。

团队协作用这套流程也成立，但边际收益小一些——团队已经有 code review 和每日站会顶住了一部分。

8.3 AI 不能替代的

这套流程让 AI 做了很多事，但以下这些我从来不让 AI 做主：

1. 产品价值判断 —— "这个功能要不要做"、"优先级怎么排"。这是战略问题，AI 缺少业务上下文
2. 架构大取舍 —— 选 Electron 还是 Tauri、用 Pinia 还是 Vuex、单体 store 还是分片 store。这类决策影响几个月后的成本，AI 看不到那么远
3. 护栏规则入库 —— 什么样的事故值得沉淀为规则？这需要 judgment，不是机械归纳
4. PRD 定稿 —— 四阶段流水线里，Phase 3 的人工审核是唯一的人工瓶颈。AI 生成 PRD 草稿，但"这份文档代表产品的应然状态"这句话只有人能签字。如果这步放手给 AI，后面整条审计链的基准就是 AI 自说自话

我的分工是：人做战略 + 判断 + 定稿签字；AI 做实现 + 修复 + 审计 + 整合。

8.4 护栏不是教条

护栏的本意是"从事故中学习"，不是"永远遵守"。如果一条规则在新场景下不适用，应该改规则、加例外，而不是硬套。

规则只增不删，但可以加"例外条款"。规则文件本身也是活的。

9. 可复制的最小起步套装

如果你想试用这套流程，最小起步是这四步：

Step 1：写一份 CLAUDE.md

项目根目录。内容：

• 技术栈
• 目录结构
• 文件命名规范
• "开始任何工作前，先读 control-tower"

Step 2：写一份 control-tower.md

放在 .spec_control/ 或任何统一目录。内容：

• 项目背景（3 段话说清楚做什么、不做什么）
• 项目阶段表
• 新会话启动流程（照抄我上面那段）
• 活跃文件索引（空的也写，后面会慢慢填）

Step 3：建立 handoff 习惯

每条工作线一份 handoff。模板：

# xxx handoff

Last updated: YYYY-MM-DD

## 定位
本 handoff 管什么

## 当前状态
🟢/🟡/🔴 一句话状态

## 已完成
- 具体事项 + 证据链接

## 下一步
- 具体事项 + 阻塞项

## 决策记录
- 某决策 + 理由

硬规则：每次 git commit 同步更新 handoff。

Step 4：装上 superpowers + gitnexus

• superpowers 提供 SDD 流水线
• gitnexus 提供代码知识图谱

CDP、spec-tower、spec-twin、superdesign 可以按需加。

10. 一张图总结

flowchart TB
    subgraph 项目层
        CT["control-tower.md<br/>· 新会话启动流程<br/>· handoff 索引<br/>· 护栏索引<br/>· 真相源"]
        H1[handoff-1]
        H2[handoff-2]
        H3[handoff-3]
        CT --> H1
        CT --> H2
        CT --> H3
    end

    subgraph 任务层SDD[任务层 · SDD 流水线]
        direction LR
        B[brainstorming] --> S[spec] --> P[plan] --> I[implement] --> A[audit]
    end

    H1 --> B
    H2 --> B
    H3 --> B

    subgraph 工具链
        T1[superpowers<br/>流水线本身]
        T2[spec-tower / spec-twin<br/>spec 管理]
        T3[gitnexus<br/>代码知识图谱]
        T4[superdesign<br/>设计语言提取]
        T5[CDP<br/>前端自测]
    end

    subgraph 模型分工[模型分工 · 四阶段流水线]
        M1["P1 Claude Code (Opus)<br/>快速实现主流程"]
        M2["P2 Codex (GPT-5.4-thinking)<br/>并行修 bug"]
        M3["P3 Claude Code → 人工审核<br/>反向 PRD + 定稿真源"]
        M4["P4 Codex (GPT-5.4-thinking)<br/>逐章审阅对齐"]
    end

    任务层SDD -.使用.-> 工具链
    任务层SDD -.分派.-> 模型分工

    classDef tower fill:#fef3c7,stroke:#d97706,stroke-width:2px
    classDef handoff fill:#dbeafe,stroke:#2563eb
    classDef sdd fill:#dcfce7,stroke:#16a34a
    classDef tool fill:#f3e8ff,stroke:#9333ea
    classDef model fill:#fee2e2,stroke:#dc2626

    class CT tower
    class H1,H2,H3 handoff
    class B,S,P,I,A sdd
    class T1,T2,T3,T4,T5 tool
    class M1,M2,M3 model

11. 结语

AI 能写代码，但不能替代研发流程。

让 AI 真正产出价值的，不是更好的 prompt，而是：

1. 稳定的上下文（控制塔 + handoff）
2. 事故驱动的约束（护栏）
3. 结构化的执行（SDD + 四阶段流水线）
4. 自动化的验证（CDP + 审计 agent）
5. 人卡关键节点（PRD 定稿是整条流水线的唯一人工锚点）

这五件事做对了，一个人能做三个人的活；做错了，AI 写得越快，项目塌得越快。

这一年最大的体会是：AI 把编码的成本降到了接近零，但把"判断"的权重推到了 100%。四阶段流水线的设计核心就是——让 AI 跑满四条赛道，但在 Phase 3 留一个人工闸门。那个闸门就是判断力的支点：PRD 签了字，后面的审计才有基准。

流程的作用不是限制 AI，而是保护人的判断力不被快速迭代的节奏冲淡。

附录 A：实际项目文件结构参考

KC 项目（.spec_control/ 目录）

.spec_control/
├── control-tower.md
├── handoffs/
│   ├── ui-changes-handoff.md
│   ├── terminal-enhancement-handoff.md
│   ├── terminal-persistent-session-handoff.md
│   ├── claude-agent-team-auto-split-handoff.md
│   ├── prd-alignment-fixes-handoff.md
│   └── ... (共 12 份)
├── specs/
├── plans/
├── guardrails/
├── archive/
└── api-specs/

UTP 项目

docs/high-fidelity-demo-spec/artifacts/
├── program-control-tower.md
├── api-integration-guardrails.md      ← Rule 12-25
├── ui-fidelity-guardrails.md
├── logic-step-syntax-guardrails.md
├── *-handoff.md                       ← 多份
└── archive/