AI-to-AI Handoff Pipeline

该工作流在本质上是一个以「协议（Protocols）」对抗「不确定性（Entropy）」的工业化生产手册。它放弃了对 AI “一键生成”的热烈幻想，转而建立了一套严密的、基于“工件（Artifacts）”的层压式架构。

“AI 的不确定性和弱点，应由另一位 AI 来对冲，而非由人类增加心智负担。”

核心理念：对抗重力的 AI 哲学

这条流水线的核心不是“让 AI 写代码”，而是**「用 AI 的长处（高并发出力）去对冲 AI 的弱点（上下文漂移/幻觉）」**。

1. 以 AI 对抗 AI (AI vs. AI Strategy)

我们不再试图让一个人去盯着 AI 的每一行代码。相反，我们调用高阶 AI（如 Opus）去规划提示词、通过交叉审阅（Critic Mode）去校验 DB 设计。

• 目标：缩小 AI 不确定性的影响范围，而不是让开发者陷入文档编写的泥潭。
• 手段：如果 PRD.md 太重，让 AI 帮人类写；如果 DB.md 可能出错，让另一模型审阅。
• 贯穿全流程的交叉审阅：不仅限于 Stage 4 的 Planner，每个 Stage 的产出物都可以（并应该）让另一个 AI 做交叉审阅。人类不需要逐字校验 Schema/API/UI 的每个字段，而是读 AI Critic 的审阅报告，做 Yes/No 决策。

2. 动态的人类参与 (Variable Human Role)

在这条流水线中，人的作用是指挥、定调、策展（Curator）：

• 指定大致正确的方向：AI 填细节，AI 做初审。
• 做最终的验证与调整：人类拥有终审权。
• 按需调节心智支出：开发者应深刻理解手头 AI 的能力边界。在 AI 弱时多做（如手写 Schema），在 AI 强时少做（如仅审阅 AI 生成的 Schema）。

3. 规格驱动的契约 (Spec-Driven Contracts)

所有的中间文档（PRD/API/DB/UI）不是负担，而是**“数字栅栏”**。它们将一个模糊的业务念头，在流转过程中逐步固化为不可动摇的契约，确保下游的执行 AI 不会因信息过载而产生幻觉。

适用场景：什么时候用这个 Pipeline？

不是所有任务都需要 Pipeline。 判断标准：

这个任务有没有「需要独立设计的 Schema（数据库）」？

├── 没有 Schema（运维脚本、爬虫、Tampermonkey、docker-compose…）
│       → 直接自然语言描述给 AI，一次生成即可
│
└── 有 Schema + CRUD + 状态机/工作流
        → 使用本 Pipeline（分阶段、先锁 Schema、再建上层）

为什么有 Schema 的系统不能「一锅出」

Schema 是最昂贵的错误来源，因为所有层都依赖它：

Schema 改动 →  DB migration 要改
            →  后端 API 返回值要改
            →  前端组件字段要改
            →  测试要改
            =  4 层联动返工

「一锅出」Vibe Coding 把 Schema 验证和所有层的生成混在一起。等发现 Schema 有问题，已经有 4 层东西需要返工。AI 改数据库的同时要改前端，即使模型再强也会在反复返工中消耗大量 context 和时间。

本 Pipeline 在 Stage 2 单独验证 Schema，稳定后才向上构建——Schema 问题只在 Stage 2 内部消化，不扩散到其他层。

注：当前 AI 模型无法从一段自然语言需求直接生成「精准的 Schema」。Schema 设计需要人参与并审阅，这是本 Pipeline 存在的根本原因。

典型项目类型

• ✅ 内部工具 / 管理后台（CRUD 为主，有数据库 Schema）
• ✅ 数据驱动型应用（有业务状态机、工作流）
• ✅ 独立开发者 / 超级个体构建复杂系统
• ✅ 内网隔离环境（用 Coding Agent 直出代码，替代 V0）
• ⚠️ 重交互动效（前端生成 AI 的动画质量需额外打磨）
• ⚠️ 需求模糊的探索型项目（先用 Vibe Coding 探索，稳定后再切换，见下方）
• ❌ 纯营销落地页（无 Schema，直接描述给 UI 生成 AI 即可）
• ❌ 运维脚本 / 爬虫 / Tampermonkey（无 Schema，直接 AI 生成）

渐进式切换：Vibe Coding → Pipeline

很多项目不是从第一天就需求明确的。正确的做法是分阶段进入：

探索期（需求模糊）→ Vibe Coding / 一锅出，快速出原型
    ↓ 需求稳定后
固化期 → 从原型中提炼 Schema → 进入 Pipeline Stage 2a
    ↓
生产期 → 正常执行 Pipeline Stage 2-6

Vibe Coding 和 Pipeline 不是互斥的。Vibe Coding 是探索工具，Pipeline 是工程化工具。探索出的原型一旦需要长期维护，就是切换的时机。

4. 角色分工速查

每个阶段的 artifact 是下一阶段的契约输入，与具体 AI 工具无关。

人的核心能力要求

在这条流水线中，人从「执行者」转变为「指挥官 + 终审员」。具体审阅工作可以委托给 AI Critic，人只需要做三件事：

1. 判断力：读懂 AI 审阅报告，做 Yes/No 决策

人类不需要逐字校验 Schema 的每个字段或 API 的每个参数。让 AI Critic 做交叉审阅，人类读审阅报告，判断问题是否成立，拍板确认。

衡量标准：把任意 artifact 单独交给另一个 AI，它能否不问任何问题就完成下一阶段任务？

2. 编排力：知道什么时机调用哪个 AI

不同模型在长上下文理解、前端代码生成、Agent 稳定性、中文语义理解上表现差异显著。人需要：

• 持续跟踪当前最优模型（参考 LMArena、SWE-bench 等排行）
• 知道哪个 Stage 对哪种能力最敏感
• 在成本/质量之间做取舍（专用工具 vs 通用模型）

3. 方向感：架构、审美与提示词表达

这是 AI 无法替代人类的最后一环：

• 架构方向：这个 Schema 是否建模了正确的现实世界？（AI Critic 能查一致性，但无法判断业务合理性）
• 审美：能用设计语言（spacing、hierarchy、color intent）描述想要的 UI
• 提示词：用技术语言精确表达需求，把模糊的意图转化为 AI 可执行的规格

完整流程

人：口述需求
    ↓
[Stage 1]  对话 AI → 人审阅 → PRD.md
    ↓
[Stage 2a] Coding Agent + 人 → Schema 设计（反复调整）
[Stage 2b] Coding Agent → API 实现 → 验证端点可用
[Stage 2c] 导出 API 契约文档 + DB.md
    ↓
    ◆ Schema Lock Gate（人确认 → Schema 冻结）
    ↓
[Stage 3]  Coding Agent 读三份文档 → UI.md → 人审阅
    ↓
[Stage 4]  UI 生成 AI 读四件套 → 前端代码
    ↓
[Stage 5]  Coding Agent 集成合并
    ↓
[Stage 6]  Coding Agent 生成测试 → CI 运行

🔑 人的四个控制点：Stage 1 审阅 PRD、Stage 2 Schema Lock Gate（最关键）、Stage 3 审阅 UI.md、Stage 5 验收。时间分布参考：Stage 2 后端 30-40% │ Stage 4 UI 20-30% │ Stage 5 集成 20-30%。

工具选型参考

Stage 4 前端生成 不依赖特定工具，任何能读取 Markdown + JSON 规范并输出前端代码的模型均可胜任。V0/Stitch/Figma Make 有沙盒预览优势；通用大模型更适合内网隔离环境或需要直出代码文件的场景。

Stage 4 前端工具定位：Stitch vs v0 vs Figma Make

三类工具的底层设计理念不同，在 Pipeline 里位于不同层次：

关键原则：

• Stitch 不应喂 API.md / DB.md——它是设计工具，技术 schema 是噪声，会导致输出质量下降
• v0 / Figma Make 应喂 API.md（分批，按页面/feature）——它们是代码工具，字段精确是它们的价值
• 数据密集型 CRUD 应用（如任务管理系统）：Stitch 价值有限，可直接用 Coding Agent + shadcn/ui 跳过设计工具

设计优先型应用（营销页 / 强交互）: Stitch → v0 / Figma Make → Coding Agent
数据优先型应用（企业 CRUD）:        v0 / Figma Make（或 Coding Agent）→ Coding Agent

各阶段详解

Stage 1 — PRD（产品需求文档）

角色：对话 AI（任意模型）
输入：人的需求想法（口述/碎片化）
输出：PRD.md

做法：与 AI 反复讨论，澄清以下内容：

• 核心用户场景（做什么、为谁做）
• 功能边界（MVP 范围）
• 数据实体与关键业务规则
• 非功能需求（认证方式、并发、部署环境）

质量标准：PRD 需明确到「AI 可以独立实现」的程度，不需要再猜测业务意图。

PRD.md 标准结构（固定模板，缺少其中任一章节是 Stage 2 返工的最常见原因）：

US-001 等 ID 将在 API 契约文档和 Page Inventory 中被引用，形成三层覆盖度追踪：需求→接口→页面。

Stage 2 — 后端实现

角色：Coding Agent
输入：PRD.md
输出：纯后端代码 + API 契约文档 + DB.md + 可选 FLOW.md

耗时参考：Stage 2 约占整个 Pipeline 30-40%。下面拆为三个子阶段，不要试图一步完成。

API 契约文档是 Stage 2 最重要的产物，是下游所有 Stage 的上下文锚点。 具体形式由技术栈决定，两种等价：

• openapi.json：机器可读的 OpenAPI 规范，适合 REST API（FastAPI / Hono）
• API.md：TypeScript Zod schema 格式的契约文档，适合 Server Actions / tRPC（等价于 openapi.json，AI 读取效果相同）

Stage 2a — Schema 设计（人 + AI 协作最密集）

目标：确定所有数据表、字段、关联关系、状态机。

操作步骤：

1. 将 PRD.md 交给 Coding Agent，要求其生成 Schema 定义（SQLAlchemy models / Drizzle schema）
2. 人审阅：表结构是否合理？字段命名是否一致？外键关系是否正确？ENUM 值是否完整？
3. 反复调整，直到满足 Schema Lock Checklist（见下方门禁）
4. 有状态机的系统：在此步骤同步生成 FLOW.md（格式见下方）

Context Anxiety 警示：如果模型开始主动收尾、回答变得敷衍或忽略细节，这是 Context Anxiety 的信号。正确做法：将当前设计决策写入一个外部文件（handoff artifact），开始一个全新的 Agent 会话继续。

Stage 2b — API 实现（Coding Agent 主导）

目标：基于已锁定的 Schema，实现所有 API 端点 / Server Actions。

操作步骤：

1. Coding Agent 按 PRD 的 User Story 逐个实现端点
2. 所有接口必须有完整的 schema 定义（Pydantic / Zod），确保契约文档质量
3. 后端不包含任何前端代码，严格解耦
4. API Response 必须通过独立的 DTO/响应模型返回，禁止直接暴露 ORM/DB 模型

DTO 约束的具体写法因技术栈而异：

[!TIP] DTO 层是 Schema 迭代的减震器：DB 表加字段、改内部字段名、拆表重构时，只要 DTO 不变，API 契约不变，前端零影响。大约 60-70% 的 Schema 变更可以在 DTO 层吸收，不传导到 Stage 4。

验证方式：

• REST API：运行后端，确认 /docs（FastAPI）或 swagger UI 可正常渲染所有端点；手动 curl 核心端点
• Server Actions：运行 integration test（vitest + testcontainers），核心 CRUD 全通

此阶段的「测试」是设计验证，不是自动化 E2E。正式 E2E 测试套件在 Stage 6 生成。

Stage 2c — 契约文档导出（机械操作）

目标：从稳定的后端代码中导出 API 契约文档和 DB.md。

API 契约文档生成方式（按技术栈）：

DB.md 生成（按技术栈）：

DB.md 目标格式（速查表，去掉叙述性内容）：

API.md 严格格式（Server Actions 项目，每个 Action 必须包含以下字段）：

// actionName
// US: US-001, US-003              ← 对应的 User Story ID
// Permission: authenticated / admin / owner
// Input:  { field: type; optionalField?: type }
// Output: { success: true; data: ReturnType } | { success: false; error: string }
export async function actionName(input: InputType)

缺少 Permission 字段是最常见的遗漏，Stage 5 集成时会造成权限校验空白。

Schema Lock Gate（Stage 2 → Stage 3 的门禁）

Stage 2 全部完成后，必须通过以下 Checklist 才能进入 Stage 3：

• 所有 CRUD 端点/Actions 可用（手动 curl 通过 或 integration test 全绿）
• 状态机转换全部验通（如有 FLOW.md，每个转换至少手动触发一次）
• Schema 定义中没有 TODO / FIXME / 占位字段
• 人审阅确认：字段命名、关联关系、ENUM 值——锁定后不再修改表结构
• API 契约文档已导出/生成（openapi.json 或 API.md）
• DB.md 已生成

→ 通过后 Schema 进入「冻结」状态，开始 Stage 3
→ 后续如需 Schema 变更，走「迭代协议」（见文档末尾）而非重走 Stage 2

可选 Artifact：FLOW.md（状态机文档）

当系统有较复杂状态机时（任务工作流、审批流、订单流转），在 Stage 2a 同步生成 FLOW.md：

## [实体名] 状态机

状态: state1 | state2 | state3 | state4

允许的转换:
state1 → state2  (trigger: actionName, 权限: owner)
state2 → state3  (trigger: actionName, 权限: owner)
state2 → state4  (trigger: system error)
任意   → cancelled (权限: admin)

前端含义:
- state1: 显示「开始」按钮
- state2: 显示进度UI + 「取消」按钮
- state3/state4: 只读，不显示操作按钮

简单 CRUD 无需 FLOW.md。有工作流则必备——不明确状态转换就是前端按钮逻辑 bug 的根源。

Stage 3 — UI 设计规范生成

角色：Coding Agent
输入：API 契约文档（openapi.json 或 API.md）+ DB.md + PRD.md + FLOW.md（如有）
输出：UI.md（AI 生成建议，人审阅修订）

提示词模板：

读取 API 契约文档（openapi.json 或 API.md）、DB.md、PRD.md 和 FLOW.md（如有），生成 UI.md，严格按以下顺序：
1. Page Inventory（页面目录）：以 PRD User Story 为准，列出每个页面的名称、User Story ID、调用的 API 端点。缺页 = 功能缺失，必须覆盖所有 User Story。
2. 技术栈要求（框架/组件库/状态管理）
3. 色彩系统（CSS 变量）
4. 布局结构（ASCII 线框图）
5. 每个页面的核心组件和交互设计
6. 如有 FLOW.md，读取状态机定义，确保每个状态对应的 UI 操作（按钮显示/隐藏）在页面设计中体现
7. 关键 TypeScript 组件接口定义
8. Mock 数据示例（对应 API schema）
9. 项目目录结构

Page Inventory 放第一位是因为它是 Stage 4 的执行清单、Stage 5 的验收依据。人审阅 UI.md 时第一件事就是检查 Page Inventory 是否覆盖了所有 User Story。

Page Inventory 格式示例（新增 User Story 列，实现 PRD → 页面 覆盖度可追踪）：

判断页面是否必要的依据是 PRD 用户任务，不是端点数量。查找类参数端点（GET /categories）和后台操作端点（token refresh）不需要独立页面。

质量标准：UI.md 需让前端生成 AI 无需猜测任何 UI 决策。

Stage 4 — 前端生成

角色分工：

1. Master Planner (Opus 等高阶模型)：负责上下文切片与提示词规划。
2. Frontend UI AI (V0 / Stitch / Figma Make)：负责 UI 代码执行。
3. Coding Agent（数据密集型场景）：直接读取全量四件套生成前端代码，跳过 Planner 和设计工具。

[!TIP] AI-to-AI 提示词规划策略：利用高阶模型的“推理边界”来保护低阶前端 AI 的“生成精度”。

阶段 4.0：上下文切片与提示词规划 (The Planner Agent)

在进入 v0/Stitch 前，先开启一个 Opus 会话，投喂全量 PRD.md、API.md、DB.md 和 UI.md。

Planner 专用提示词：

你是一个「前端生成专家级规划员」。我的目标是让 v0/Stitch 生成「{{页面名称}}」。
由于全量文档过大，请你：
1. 深入理解全量 PRD/API/DB/UI 关联。
2. 为我提取一个「针对该页面的上下文最小集」（仅包含该页面必用的端点、字段、UI规格）。
3. 为我生成一个「直接可粘贴给 v0 的提示词」，该提示词需包含：
   - 该页面的交互逻辑（来自 PRD）
   - 该页面的 API 数据结构 Mock 指令（来自 API.md）
   - 该页面的校验规则（来自 DB.md）
   - 该页面的布局规格（来自 UI.md）
请直接输出该提示词块，不带多余解释。

阶段 4.1：全局初始化（The Foundation）

输入文件：由 Planner 生成的全局 Layout 提示词。 目标：建立项目骨架、设计系统（Colors/Tokens）、全局 Layout（Nav/Sidebar）。

阶段 4.2：页面/功能切片（The Feature Slice）

输入文件：由 Planner 针对特定页面生成的「切片提示词」。 目标：高保真实现单一页面。

阶段 4.3：工具偏差处理（Tool-Specific Playbooks）

• v0：侧重“功能性真实性”。提供精确的 JSON Schema，让 v0 生成带类型定义的 Fetch 层。
• Stitch：侧重“视觉一致性”。只投喂 UI.md，避免 backend 逻辑干扰其设计决策。
• Figma Make：侧重“结构化转换”。利用 UI.md 中的 ASCII 线框图作为视觉引导。

⚠️ 执行建议：向前端生成 AI 明确说明：以 UI.md 中的 Page Inventory 为准，每一行对应一个页面或路由，不得遗漏。

注意：生成的 API 调用层通常为 mock，接缝工作在 Stage 5 完成。

回退协议（任意 Stage 失败时的标准操作）

Pipeline 不是只有 happy path。以下是各 Stage 失败时的标准回退流程：

回退原则：

• 回退时只更新受影响的 artifact，不全量重做
• 每次回退后重新通过对应 Stage 的门禁/Checklist 再继续
• 如果同一个 Stage 连续回退 3 次，暂停并复盘 artifact 质量（通常是上游输入有问题）

Stage 5 — 集成合并

角色：Coding Agent
输入：前端代码 + 后端代码 + API 契约文档（openapi.json / API.md）
输出：可运行的完整应用

标准 Checklist（逐项执行）：

• 替换所有 mock 为真实 API endpoint
• Authorization header 注入（Bearer token）
• 所有 API 错误码映射到用户提示（401→重新登录，422→表单反显，500→通用弹窗）
• 日期/数字格式化（修复 Invalid Date 等 mock 遗留问题）
• CORS 配置验证
• 安全检查：env 变量未硬编码、敏感 token 不出现在前端 log、权限校验未遗漏

⚠️ AI 生成代码的常见安全盲点：secret 硬编码、接口权限校验遗漏、直接透传用户输入到 API。Stage 5 是注入 auth 逻辑的关键节点，需人工重点复核。

执行前先约定「完成标准」（Sprint Contract）：

在 Coding Agent 开始工作前，先让它写出本次集成的验收条件，人确认后再执行：

请列出本次集成的验收标准：
1. 哪些 mock 需要替换为真实接口（列出每个文件名和函数名）
2. auth 注入需要修改哪些地方
3. 验收方式：如何确认集成成功（人工运行哪些步骤？）

这个步骤来自 Anthropic 内部实验的「Sprint Contract」模式：先就「什么叫完成」达成共识，再执行，减少「完成了但方向错了」的返工。

Stage 6 — 测试

角色：Coding Agent + 测试框架
输入：后端代码 + 前端代码 + API 契约文档（openapi.json / API.md）
输出：测试报告

API E2E 测试

测试框架：pytest + httpx（Python 后端）/ Jest + supertest（Node 后端）
覆盖范围：

• 所有 CRUD 端点的正常路径（创建/读取/更新/删除）
• 认证流程（login → refresh → me）
• 业务操作端点（按 PRD 中的核心业务动词覆盖）
• 错误码校验（404 / 422 / 403）

提示词模板：

读取 API 契约文档（openapi.json 或 API.md），为所有写操作端点/Actions 生成对应测试（REST: pytest + httpx；Server Actions: vitest），
覆盖正常路径和常见错误路径（422 参数校验、404 未找到、401 未认证）。
使用 fixtures 管理 test DB 和认证 token。

UI 测试

测试框架：Playwright / Cypress
覆盖范围（按实际业务替换示例）：

• 关键用户流程（登录 → 创建资源 → 触发业务操作 → 查看结果）
• 表单提交和验证提示
• 异步状态轮询（长时操作状态自动刷新）
• 复杂交互组件（拖拽、多步向导等，如有）

提示词模板：

读取 UI.md 和 PRD.md，为 PRD 中的核心用户流程生成 Playwright 测试脚本，
覆盖：登录、主要资源的创建与操作、结果查看。
断言关键 UI 元素、状态变化和错误提示。

测试策略：

• API E2E 在 CI 每次 push 时运行
• UI 测试在 staging 环境部署后运行
• running 状态的实时功能用 mock WebSocket/polling 替代，避免 CI 超时

各阶段输出物清单

企业基座扩展模式 [推测/尚未大规模验证]

将本流水线的 Stage 1-2 产出物固化为「企业基座仓库」，后续业务需求在此之上叠加，无需从零开始。 ⚠️ 本章节是基于个人项目经验的向上推测，尚未在多项目间验证复用效果。

基座包含的公共能力

• 能用成熟库就不要让 AI 重写：better-auth/CASL 已有大量线上案例验证，AI 写的 auth 逻辑安全漏洞概率更高。 • 内部定制层（公司内部 OAuth 加密、内部 IM）是 AI 应该封装适配器的地方，而不是从零实现协议。

基座仓库结构

enterprise-base/
├── PRD-base.md          # 基座业务规范（用户/权限/审计的需求定义）
├── openapi-base.json    # 基座 API spec（auth / users / orgs / activity）
├── DB-base.md           # 基座数据库设计
├── UI-base.md           # 基座 UI 规范（登录页/用户设置/权限管理）
├── backend/             # 后端实现（按选定技术栈，如 FastAPI / Hono）
├── frontend/            # 登录、用户中心、权限管理页面
└── tests/               # 基座 E2E 测试

叠加业务需求时的流程

基座仓库（fork / extend）
    ↓
[Stage 1] 业务 PRD.md（增量需求，引用基座能力）
    ↓
[Stage 2] 业务后端 → 业务 API 契约文档 + 业务 DB.md
           ↑ 复用基座 auth / RBAC / audit API
    ↓
[Stage 3] 业务 UI.md（读业务 API 契约文档 + DB.md + PRD.md）
    ↓
[Stage 4] 业务前端（基座 UI 组件可直接引用）
    ↓
[Stage 5 / 6] 集成 + 测试（基座测试已通过，只需覆盖业务逻辑）

关键优势：

• PRD 层：业务 PRD 只写「业务特有需求」，权限/审计等写「复用基座」
• API 层：业务 API 契约文档只包含业务端点，基座端点已测试稳定
• 测试层：基座测试作为回归基线，每次业务迭代只需新增业务测试用例

成本参考（参数级别，具体以实测为准）

运维操作手册

操作 1 — Artifact 持久化与版本控制

所有 artifact 与代码一起进 Git，放在 docs/ 目录：

project/
├── docs/
│   ├── PRD.md
│   ├── openapi.json 或 API.md
│   ├── DB.md
│   ├── UI.md
│   ├── FLOW.md（如有）
│   └── PIPELINE.md        ← 本项目流水线执行偏差与解法记录
├── backend/
├── frontend/
└── tests/

操作规则：

• 每次迭代在 commit message 中注明变更的 artifact：docs(api): add /jobs/cancel endpoint
• git diff docs/ 可直接看本次变更范围，作为增量更新的依据
• PIPELINE.md 记录本项目特有的偏差：格式 [Stage][工具][问题描述][解法]
• 企业基座仓库额外维护全局 LESSONS.md，沉淀跨项目通用经验

操作 2 — 上下文窗口管理

问题：四件套合计可达 50k+ token，部分模型无法一次处理。

⚠️ 模型名称迭代很快，不在此硬写具体型号。按以下能力维度在当时的排行榜（如 LMArena、SWE-bench）选型。

各 Stage 所需模型能力：

渐进性披露策略（Context Progressive Disclosure）：

如果使用了 Stage 4.0 的 Planner Agent，以下表格可跳过（Planner 已自动完成切片）。本表格适用于不使用 Planner 的场景（如直接在 Coding Agent 中生成前端）。

不要一次性全量投喂。先投优先文件，发现信息不足再补充：

先投优先文件启动生成，发现缺信息时再投下一个文件补充，不要「投满等结果」。

操作 3 — 自动化「上下文切片」（Context Preparation）

问题：后端生成的 API.md 可能包含 50+ 个端点，但某个页面只用其中 2 个。全量投喂会导致前端 AI 在无关信息中迷失。

解法：使用 Stage 4.0 的 Planner Agent（详见「各阶段详解 → Stage 4 → 阶段 4.0」）自动完成切片。Planner 读取全量文档，针对每个页面输出「可直接粘贴给 v0/Stitch 的切片提示词」。

[!IMPORTANT] 切片原则：宁可少给（让 AI 报错找不到字段再补），不可多给（导致 AI 乱用字段产生返工）。

操作 4 — 测试门禁

测试是 Stage 之间交接的唯一客观验收标准。

测试数据隔离：

• API E2E：每个 test session 创建独立 test DB，结束后销毁（或事务内 rollback）
• UI 测试：使用 mock server 替代真实后端，避免环境依赖

操作 5 — Artifact 质量自检（AI Critic 模式）

在将 artifact 交给下一个 Stage 前，先运行独立评审提示词。

PRD.md 评审：

你是一个持怀疑态度的高级工程师。读取 PRD.md，检查：
1. 是否有未定义的数据实体或字段？
2. 是否有业务规则缺失（过渡状态、删除行为未定义）？
3. 非功能需求是否完整（认证方式、部署环境、并发级别）？
列出所有问题，不要自己补充假设，不要说「总体不错」。

API 契约文档评审：

持怀疑态度。读取 API 契约文档和 PRD.md，检查：
1. PRD 中的每个 User Story 是否都有对应的端点/Action？
2. 是否有缺少错误响应 schema 的端点/Action？
3. 分页参数或返回类型是否一致？
4. 每个端点/Action 是否标注了 Permission？
列出所有漏洞。

LLM 的系统性偏差是宽容——必须在提示词中显式要求「持怀疑态度」「不要说总体不错」才能突破默认倾向。

操作 6 — 部署

最低可行部署策略：

• 容器化：后端 + 前端各一个 Dockerfile，Coding Agent 参考 PRD 中的「部署环境」章节生成
• 环境变量：所有 secret 通过 .env / Vault / K8s Secret 注入，不进代码
• CI/CD：测试通过后触发 Docker build → push → 滚动部署
• 提示词：参考 PRD.md 的部署环境要求，生成 Dockerfile 和 docker-compose.yml，数据库连接通过环境变量注入

部署策略应在 PRD.md 里明确（容器/VM/K8s），Stage 2 实现时按此约束。

操作 7 — 需求迭代协议

v1 交付后新需求进入时的标准流程（即前文回退协议中引用的「迭代协议」）：

1. PRD.md 追加增量需求（不覆盖，保留历史上下文）
   ↓
2. Coding Agent 只修改受影响的后端模块
   → 按需增量更新 API 契约文档 / DB.md
   ↓
3. Coding Agent 增量更新 UI.md 对应章节
   ↓
4. 前端 AI 只重新生成受影响的页面/组件
   ↓
5. 运行回归测试 + 新增业务测试，全部通过后合并

Schema 变更必须走 Stage 2a 的 Schema Lock Gate 后才能继续下游。

v1 交付后的迭代策略

本 Pipeline 主要解决「如何构建 v1 绿地项目」。 v1 交付后，进入迭代模式——工具和粒度均需调整。

两个结构性约束

约束 1：设计工具是单向门

v0 / Stitch / Figma Make 导出后，代码库与设计工具脱离同步。这是所有 design-to-code 工具的特性，无法绕过。

正确心态：v0/Stitch/Figma Make 是脚手架，不是持续维护的设计系统。 脚手架用完即拆，价值在于 v1 的生成速度。

应对方式：

• 导出前在 v0 内多迭代几轮，满意后再导出
• 导出后 UI.md 成为 source of truth，后续所有 UI 改动交给 Coding Agent
• 局部大改时：用更新后的 UI.md 重新生成该组件，手工合并进代码库

约束 2：v1 之后回到前后端一体

v1 交付后，前后端代码在同一代码库。分阶段构建的窗口关闭，进入正常的迭代开发节奏。

约束 3：文档从「驱动代码」翻转为「由代码驱动」

初建期（v1 之前），文档是第一手来源，代码从文档生成。v1 交付后，地位反转——代码成为 Single Source of Truth，文档从代码自动生成或按需维护：

核心原则：文档是脚手架，不是最终建筑。v1 之前它们支撑建设，v1 之后它们被代码本身替代。手动维护 5 份互相引用的文档是不可持续的——让代码生成文档，而不是反过来。

迭代策略按粒度选工具

迷你 Pipeline：针对单个新 Feature 执行缩减版 Pipeline——设计新 Schema → 验证 API → 实现 UI。原则不变，范围缩小。

Coding Agent 是 v1 后的主力工具

v1 之后，v0/Stitch/Figma Make 的使用频率大幅降低。Coding Agent（Claude Code 等）成为日常迭代的主力：

• 读取现有代码库上下文
• 参考 UI.md / API.md 做增量修改
• 保持与现有代码风格一致

随着模型能力提升，今天需要反复修改 5 次的整合工作，未来可能只需 2 次。Pipeline 结构不变，只是每步的人工干预量逐步减少。