# AI-Native / Agent-First 软件工程开发指南与落地规范

> **适用范围**：采用自主编码 Agent（CLI / ADE / 多 Agent 协同）开展需求发现、研发规划、特性研发、架构演进、缺陷修复与交付复盘的工程团队。  
> **核心原则**：人类负责人明确意图与红线，Agent 负责探索与实施；以可核验的客观证据验收；按最高风险确定设计、审查和验证深度。  
> **版本基准**：2026-10-14 完整研发流程审校版；统一需求、规划、实施、验收、发布与运行反馈的衔接，补齐适用条件与状态口径。  
> **项目形态**：适用于单仓、Monorepo 及跨服务多仓项目；按模块、服务与实际交付边界选择落地流程，不预设仓库物理形态。  
> **效力边界**：本文是一份供工程团队采纳的实践指南。仓库既有的硬性约束、有效业务决策与已授权范围仍按各自权威入口执行；本文不自动新增 CI 门禁，亦不替代既有决策；文内模板用于说明应记录的信息，不代表已取得验证证据。

---

## 〇、完整研发流程：从需求线索到版本效果

> **阅读方式**：本章说明需求与规划；快速上手串联单任务操作；第二章明确开工准备；第三至八章展开实施、审查、发布和治理；第十章用于核对，附录 A 提供模板，附录 B 说明公开方法依据。全文可独立阅读。流程状态、角色分工和检查要求是本文的综合建议，须经团队采纳并接入实际机制后生效。

### 0.1 全流程与责任分工

研发从识别问题开始，以交付后的效果核验形成反馈。需求发现可以与当前迭代的交付并行；新证据可以使条目退回澄清、重新排序或取消，不要求所有需求一次性完成设计。

```mermaid
flowchart TD
    Signal["需求收集<br/>用户反馈 · 业务目标 · 故障与技术债"] --> Intake["统一登记、分类与初审<br/>合并重复 · 确认归属 · 保留来源"]
    Intake --> Discovery["问题验证与需求澄清<br/>证据 · 目标 · 范围 · 验收草案"]
    Discovery --> Decision{"是否值得推进？"}
    Decision -->|信息不足| Learn["访谈、数据分析或限时验证"]
    Learn --> Discovery
    Decision -->|否或暂缓| Park["记录理由与复查条件"]
    Decision -->|是| Order["优先级与依赖排序<br/>强制约束 · 必备能力 · 普通收益"]
    Order --> Plan["滚动规划<br/>版本目标与迭代容量相互校准"]
    Plan --> Ready["开工准备<br/>决策 · 契约 · 验收 · 资源"]
    Ready --> Delivery["快速上手第 1—5 步与第三章内、中循环<br/>切片 · TDD · 审查 · 验证 · 合入"]
    Delivery --> NeedDeploy{"本次成果是否需要部署？"}
    NeedDeploy -->|否| Handoff["完成验收与交接<br/>部署标为不适用"]
    Handoff --> Outcome
    NeedDeploy -->|是| Release{"版本范围是否齐备？"}
    Release -->|否| Ready
    Release -->|是| Ship["第七章发布流程<br/>构建候选 · 隔离验收 · 准入固化 · 发布核验"]
    Ship --> Outcome["效果评估与复盘<br/>用户结果 · 质量 · 交付瓶颈"]
    Outcome --> Intake
    Park -.->|复查条件满足| Discovery
```

| 环节 | 主责与参与者 | 最小产物 | 转入下一步的条件 |
| :--- | :--- | :--- | :--- |
| 收集、分类与初审 | 产品负责人或具名需求负责人；业务、客服、研发提供线索 | 需求条目及来源 | 问题、对象、归属可辨认；紧急事项已分流 |
| 需求澄清 | 需求负责人牵头；设计、领域专家、研发参与 | 问题证据、范围、验收草案、未决项 | 能说明为何做、如何判断有效，以及还不知道什么 |
| 排序与取舍 | 产品或业务负责人决定价值顺序；技术负责人说明风险与依赖 | 有序候选队列及取舍理由 | 已区分必备条件、普通收益与待验证假设 |
| 迭代与版本规划 | 交付团队评估容量；负责人确认目标与对外承诺 | 迭代计划、版本计划 | 依赖、资源、审查与验证时间可安排；不超售容量 |
| 研发与验收 | 执行 Agent、研发、独立审查者及领域责任人 | 实现、审查结论、受测证据 | 满足该切片及目标环境的完成条件 |
| 发布与效果评估记录 | 发布负责人、运维负责人、需求负责人 | 部署回执、效果记录、后续需求 | 发布事实与业务效果分别核验，剩余问题有归属 |

同一人可承担多个角色，但仍须遵守现有独立审查、权限和审批要求。Agent 可以整理反馈、检索证据、提出排序及估算建议；不得编造访谈、使用量或收益，也不得自行代表团队承诺发布日期。

### 0.2 需求收集：统一入口，保留原始证据

建立一个可检索的需求池，复用团队已有 Issue、任务系统或文档索引，不要求另购工具。每条线索先记录“谁遇到什么问题”，再讨论实现方案。需求发现应持续结合用户问题、业务目标和反馈，而非只在开发前做一次需求交接。[方法依据：Atlassian Product discovery](https://www.atlassian.com/agile/product-management/discovery)

| 需求来源 | 最少记录的信息 | 常见误判 |
| :--- | :--- | :--- |
| 用户访谈、客服反馈、实际操作观察 | 来源链接、日期、用户角色、触发场景、影响及现有替代操作方式 | 把某位用户提出的按钮或页面直接当成最终方案 |
| 业务目标与对外承诺 | 目标、责任人、期限依据、未完成的后果 | 把期望日期写成已经确认的交付承诺 |
| 故障、安全或账务问题 | 可核查的现象、影响范围、复现或运行证据、处置状态 | 把未经验证的推测直接写成已确认根因 |
| 研发与运维技术债 | 失败记录、人工成本、阻塞的能力、现有权威条目 | 只按 `todo!()` 数量或代码行数判断欠账轻重 |
| 技术探索与新机会 | 待验证假设、潜在价值、验证成本、停止条件 | 把技术可行或模型演示成功等同于用户需要 |

原始反馈、合并后的需求、实施任务与目标版本保留关联；同一需求可拆成多个任务，多个任务也可共同支撑一个版本。发现问题不成立时可以关闭条目，无需为关闭而进入开发。

每条需求至少包含：**稳定 ID、问题描述、受影响对象、来源、需求负责人、当前状态、关联目标、期限及其依据、已知依赖、下次处理动作**。合并重复项时保留原来源；敏感客户材料只留受控引用。

分类与初审后可进入“待澄清、候选、待决策、暂缓、拒绝”等状态。暂缓与拒绝须说明理由；暂缓项还应注明复查日期或触发条件。生产事故和已确认的紧急风险按现有应急流程处理，不等待普通需求评审；应急处置仍须保留任务与证据记录。

### 0.3 需求澄清：把问题转成可验证的交付目标

对准备进入近期规划的条目，补齐以下信息；远期想法只保留足够判断是否继续投入的材料。

1. **问题与证据**：当前行为是什么，影响谁，发生频率或影响量如何，证据有哪些局限。
2. **目标与效果**：希望用户或业务获得什么结果；记录可观测指标、当前基线、目标值及观察窗口。暂无基线时先安排采集，不填猜测数值。
3. **范围与非目标**：本次支持的角色、环境、业务路径及明确不包含的内容；涉及界面时说明用户流程、交互状态与无障碍要求。
4. **验收与约束**：成功、失败、权限和恢复场景；金额、隐私、资源或性能边界。
5. **未决与依赖**：需要由谁作出决策、依赖哪些接口或外部资源；阻塞的是哪一部分。

不确定性较大时，先安排限时调研、原型或技术验证，写清预算、问题和退出条件。验证结果应能支持继续、调整或停止；涉及新交互流程时，可通过原型或可用性测试验证方案。原型须经过正式设计、审查与验收后，才能作为生产实现交付。

**进入实现的准备条件**：需求负责人明确、目标与验收可判定、关键决策有效、阻塞依赖已解决或有可执行安排、验证入口与环境可获得。它是本文建议的开工检查，不是 Scrum Guide 规定的统一“Definition of Ready”，也不要求每项探索都提前写完完整规格。进入编码后，按 §2.3 与快速上手六步法执行。

### 0.4 优先级排序：先判断约束，再比较收益

**优先级、变更风险和准备状态是三个独立维度。** L3 决定审查与验证深度，不自动等于“马上做”；高收益也不能覆盖安全红线或绕过依赖。编号、评分和排列顺序均不能代替正式业务决策。

建议按以下顺序讨论候选队列，具体紧急等级沿用项目定义：

| 类别 | 排序依据 | 需要留下的记录 |
| :--- | :--- | :--- |
| 紧急处置与硬性期限 | 已确认的事故影响、约束或承诺期限，以及延迟的后果 | 事实依据、负责人、处置时限、被挤出的计划 |
| 当前目标的必备条件 | 不完成就无法验收或发布的能力、必须先完成的决策和满足的依赖 | 被阻塞的目标、前置链、最小可交付范围 |
| 普通功能与改善 | 用户价值、覆盖范围、证据强度、总投入及维护成本 | 比较口径、估算依据、最终取舍 |
| 探索与远期机会 | 不确定性、潜在价值、获得新证据的成本 | 验证预算、复查条件、是否进入近期队列 |

对同类、可比较的普通需求，可选用 RICE：`覆盖范围 × 影响程度 × 置信度 ÷ 投入`。覆盖范围使用相同统计窗口，影响针对同一目标，投入采用相同单位；置信度应来自证据，不能直接取模型自评。Intercom 明确指出，依赖项和必备能力可以先于高分项，分数不应成为僵硬的执行规则。[方法依据：Intercom RICE](https://www.intercom.com/blog/rice-simple-prioritization-for-product-managers)

本文建议：缺少可比数据时使用说明理由的序数排序，不制造精确小数；对投入区间做敏感性检查，若轻微调整就改变排名，应先补证据。需求负责人记录最终顺序及偏离评分的原因；待决策项安排澄清动作，不让执行 Agent 靠猜测解除阻塞。

### 0.5 迭代排期：按完整交付容量承接工作

排期回答的是“在本轮可用资源下，能够完成哪个结果”。采用固定迭代或持续流动均可，但应明确规划周期、进度检查和重排时机。Scrum Guide 将迭代预测与历史表现、即将可用的容量和完成标准联系起来；这不等于按人数平均分配任务。[方法依据：Scrum Guide，Sprint Planning](https://scrumguides.org/scrum-guide.html#sprint-planning)

本指南建议按以下步骤编排：

1. **确定本轮目标**：用一句用户或业务结果表达，避免只列文件或提交数量。
2. **盘点真实容量**：列出人员可用时间、值班与请假、领域审查窗口、测试环境、CI 及外部服务约束。编码、评审、修复、集成和发布准备均计入；同一开销不得重复扣减。
3. **按依赖选择切片**：先安排阻塞关键路径的工作；确认依赖允许、责任明确且资源不冲突的切片才并行。跨仓工作明确契约提供方、消费方、联合验收责任人和集成节点。
4. **给出估算区间与假设**：区分工作量与日历时长。没有历史数据时先交付小批次建立基线，不用 Agent 数量、Token 预算或生成速度直接推算工期。
5. **限制在制工作**：按实际瓶颈设置开发、审查、验证的在制上限。评审或测试积压时优先疏通，不继续大量开新任务。DORA 的 WIP 方法强调看见从分析到运行的全部工作，而非只限制编码列。[方法依据：DORA WIP limits](https://dora.dev/capabilities/wip-limits/)
6. **保留变更空间**：依据历史插单、返工与运行支持负荷留出容量，比例由团队实际数据决定，不统一规定一个百分比。

迭代开始后，持续记录剩余工作、阻塞及新增证据。插入紧急项时同时说明移出或延期什么；若目标失效，由有权负责人决定重排或终止。普通计划调整不降低质量门槛，也不自动修改业务规格。

迭代结束时，分别记录已实现、已验证、已合入、已部署和未完成内容。未完成项根据剩余工作与最新优先级重新评估，不默认为下一轮必做，也不把部分完成计作验收通过。复盘至少选出一项可执行改进，明确负责人、验证方式和复查时间。

### 0.6 版本规划：分清方向、目标窗口与发布事实

| 规划层次 | 回答的问题 | 建议记录的内容 |
| :--- | :--- | :--- |
| 产品路线图 | 接下来先解决哪些问题 | Now / Next / Later 或较粗时间窗口、目标、依赖、信心与变更原因 |
| 版本计划 | 哪个交付组合面向哪些用户和环境 | 版本目标、必备范围、可调整范围、非目标、目标窗口、退出条件与责任人 |
| 迭代计划 | 本轮能完成什么 | 可用容量、已选切片、依赖顺序、验证与审查安排 |
| 发布清单与回执 | 实际验收并发布了什么 | 受测 SHA、制品摘要、配置和迁移组合、部署结果及剩余范围 |

Atlassian 建议路线图保持对目标和策略的关注，可使用月度、季度窗口或 Now / Next / Later，避免把远期探索过早写成精确日期承诺。[方法依据：Atlassian Agile roadmaps](https://www.atlassian.com/agile/product-management/roadmaps)

本文建议区分“探索中的方向、基于当前信息的预测、已确认的外部承诺”，记录承诺主体和依据。有固定日期约束时先划定必备范围，再调整可选项；有固定范围约束时，应让时间预测反映真实容量和依赖。无法兼顾时公开取舍，不以压缩验证或隐藏 OPEN 项维持表面进度。

版本计划至少说明：

- **发布对象与环境**：内部演示、受控试用、staging 或生产；面向谁开放哪些能力。
- **范围与退出条件**：必备能力、可调整项、明确非目标，以及各项业务和运行验收。
- **版本组合与依赖**：涉及的仓库、接口与消费者兼容关系、迁移顺序、配置及运行时前提；多仓允许不同版本号，但组合必须可追溯。
- **窗口与责任**：目标窗口、预测依据、最迟决策点、发布负责人及运维负责人。
- **停止与恢复**：何种结果阻止发布，何种运行异常触发停止或恢复，谁作出判断。
- **效果观察**：发布后何时、由谁核对需求目标，使用什么数据及指标。

研发中维护的是可调整计划；发布准入时按第七章固定 Release Manifest，发布后记录实际回执。一个版本可以跨多个迭代，一个迭代也可以产生多个可发布增量；迭代结束不自动证明版本可发布。

### 0.7 发布后的效果验证与需求回流

工程验收说明实现是否符合约定，效果验证说明约定的方案是否解决了问题，两者分别记录。对每个主要版本目标，核对发布前基线、观察窗口、目标用户覆盖、实际使用与失败情况；样本不足或归因不清时写“尚不能判断”，不能只凭发布前后的数值变化归因。

未达目标时，由需求负责人结合用户反馈、使用数据和运行问题，决定继续观察、改善、缩小范围或退出。研发复盘发现的测试、契约、工具和运维技术债进入同一候选队列，与功能需求一起接受取舍；事故修复仍按既有紧急机制执行。已部署但尚在观察中的需求可以关闭工程交付子项，同时保留效果评估项及负责人。纯文档、工具等无需部署的成果，在使用或交接后核对其目标；不适用的运行指标注明理由。退出已发布能力时，按 §7.4 处理使用方、数据与资源的收尾。

建议按约定周期复查需求池，关闭已失效或重复的条目，并通知相关提出方；涉及通知动作时，Agent 遵守现有授权范围。本节规定的是工作记录方式，不要求 Agent 自动向外部系统发消息。

### 0.8 采纳方式与状态衔接

本指南描述完整流程，团队可按风险、规模和实际交付形态裁剪。首次采纳时明确负责人、状态含义、验证入口和例外处理；已有等价机制可直接映射，无需额外建立一套台账。重要信息可以集中在同一份任务或设计文档的不同章节，不要求每种记录各建一个文件。

| 记录对象 | 建议区分的状态或信息 | 不能据此推断的结论 |
| :--- | :--- | :--- |
| 需求 | 待澄清、候选、待决策、已选入、暂缓、拒绝或关闭；记录理由与下一步 | 已选入不代表承诺发布日期 |
| 决策与规格 | 草案、已接受、当前有效、已替代；保留适用范围和替代关系 | 已接受不代表实现或验证完成 |
| 实施任务 | 待开始、进行中、受阻、待验收、已完成；同时记录切片范围 | 某切片完成不代表整个需求完成 |
| 工程交付 | 已实现、已验证、已合入、已部署分别记录版本与证据 | 合入不代表发布，发布不代表业务目标达成 |
| 版本 | 规划中、候选、准入通过、发布中；结果区分成功、失败、部分完成与结果未知，恢复状态单独记录 | 计划窗口不代表实际发布时间 |
| 效果评估 | 未观察、观察中、已达目标、未达目标或尚不能判断 | 样本不足不能记为成功 |

上述状态描述不同对象，不能混成一条线性进度条。团队可以沿用自己的名称，但须明确转入、退出条件和决定人。`OPEN` 表示尚未解决的事项，不是风险豁免；每项应记录影响、负责人、后续动作及是否阻断当前验收或发布。仅非阻断事项可在有权负责人接受后留待后续处理。

本文统一使用以下术语：**候选源码版本**标识待审查的代码；**受测输入摘要**覆盖源码、配置、夹具、契约等实际验证输入；**发布制品组合**标识准备部署的不可变产物及配套配置、迁移；**部署回执**记录实际执行结果。这四者相互关联，不能相互替代。

---

## 【快速上手】从一个真实任务开始（Quickstart）

**需求尚未明确或尚未排期时，先按第〇章完成收集、澄清与规划；已有明确任务时，可按本节六个步骤跑通一个最小切片闭环。后续章节提供实施、审查、发布与治理规范。**  
*附录 A 以同一个业务示例贯穿各环节，提供相应的文档模板，不要求一次性创建所有文件。*

### 诊断：你的项目当前处于什么状态？

| 你的项目当前处于什么状态 | 首要动作 | 推进准则 / 阶段完成标准 |
| :--- | :--- | :--- |
| **已有代码库，且启动与测试命令可用** | 选取一个边界清晰的真实任务，建立一张任务卡 | 任务具备可判定的验收标准，现有验证命令可在本地实际跑通 |
| **已有代码库，但测试或构建不可用** | 先修复与本任务直接相关的环境和验证入口，登记已有失败项 | 能够区分历史遗留失败与本次改动引入的新失败；核心门禁按既定规则处理 |
| **全新项目，或尚无规范工程入口** | 先按 §2.8 建立最小可运行环境 | Agent 明确应当读取哪些文档、如何启动服务、如何运行测试，以及关键技术和业务事项由谁作出决定 |

---

### 第一步：建立一张结构化任务卡

沿用团队现有的任务跟踪系统（如 Jira / GitHub Issue）；若团队尚无统一约定，可直接创建并使用本地任务卡文件（如 `docs/tasks/T-001.md`）。执行 Agent 应先填写以下内容，确保信息具体、可核验：

```markdown
# T-001：<一个可交付的用户结果>
阶段：需求澄清；风险等级：<L1/L2/L3 及判定理由>；负责人：<责任人或对应角色>

业务目标：<用户面临什么痛点，本次改动交付何种具体价值>
需求与规划关联：<需求 ID、排序依据、所属迭代/批次及目标版本；不适用时说明>
实现范围与非目标：<明确本次要完成的内容及不包含的内容（Non-goals）>
依据来源：<现行规范、业务需求与有效决策；若缺失则明确标注待补齐>
验收准则：AC-01 <特定输入或触发动作 ➔ 明确可观察的预期结果>
执行入口：<从本项目实际查明并成功试跑的启动与检查命令>
执行边界：<授权来源、运行身份、允许的工具/资源/环境、禁止动作、有效期、预算与停止入口>
待决事项：<未决问题、备选方案与指定决策人；无则填“无”>
```

---

### 第二步：将“想要什么”转化为可验证的验收准则

由人类负责人或产品负责人界定业务意图与安全红线，Agent 协助整理为明确无歧义的验收准则（Acceptance Criteria, AC）。不得使用“处理好并发”“界面好看”“做好容错”等无法直接验证的模糊描述。

**AC 编写范例（以本指南贯穿的“异步报表导出”为例）：**以下为候选验收准则，作用域指租户与认证主体；期限、规模、错误码等须由有权负责人确认。示例不表示相关需求已经获批或实现。

* **AC-01**：在去重保留期内，同一作用域下使用相同请求标识和相同筛选参数重复提交时，服务端返回同一任务标识，任务表仅保有一条对应记录；不同请求标识不因参数相同自动合并；
* **AC-02**：在去重保留期内，同一作用域下使用相同请求标识但携带不同参数时，服务端返回 409 冲突，原任务不被覆盖；
* **AC-03**：服务端已受理但提交响应丢失后，在原作用域仍获授权且请求映射仍在保留期内的条件下，客户端能依据原请求标识查回任务，恢复过程不创建新任务，也不发起新的提交；超出保留期不保证仍可查回，不得自动换键或重新提交；
* **AC-04**：无权主体尝试读取任务或下载文件时，按已确认的权限契约返回拒绝结果；本例采用 403，并记录安全审计事件；
* **AC-05**：在约定规模与依赖正常的条件下，有效请求按已确认的筛选条件、格式与数据读取口径生成正确文件；只有当前执行代际成功发布结果后，任务才进入 READY；
* **AC-06**：生成失败与文件到期按契约显示真实状态；重启或租约失效后按恢复规则继续处理，旧执行代际不能覆盖新结果，也不产生多个可见的最终结果。

---

### 第三步：将任务拆分为可验证的切片，建立测试映射

Agent 将任务拆解为若干独立的工程切片，每个切片都应明确对应的验收准则（AC）。根据实际影响面选用测试手段，不得在开工前不加区分地堆砌或勾选无关测试。

| 切片标识 | 本切片完成的核心能力 | 对应验收 / 验证方式 | 本切片不包含的交付内容 |
| :--- | :--- | :--- | :--- |
| **S1：受理与查询** | 原子持久化任务与请求身份；实现同键处理与权限过滤 | 覆盖 AC-01/02 及 AC-04 的任务查询部分；规则、真实数据库并发与鉴权测试 | 尚未完成文件实际生成逻辑与用户交互界面 |
| **S2：执行与结果** | Worker 异步生成、文件存储、超时与到期处理、重启恢复 | 覆盖 AC-05/06；文件完整性、状态流转、执行代际（Epoch）与恢复测试 | 尚未完成前端与真实浏览器交互体验 |
| **S3：用户端闭环** | 页面提交、网络异常恢复、进度轮询与安全下载 | 覆盖 AC-03、AC-04 的下载与界面部分，以及 AC-05/06 的用户可见结果；浏览器、无障碍与端到端测试 | 尚未完成目标发布组合的制品验收与部署核验 |

> [!NOTE]
> 候选规格文档必须先通过适用的文档审查（Documentation Review），方可进入编码实施。

---

### 第四步：驱动 Agent 完成单个切片（TDD 与自查）

向 Agent 提供任务卡、当前切片目标及已确认的规范依据。已明确授权的常规操作允许 Agent 自主推进，无需步步请示。

> [!TIP]
> **切片实施指令（Prompt 范例）：**  
> “请依据任务卡实现切片 S1，严禁超出本切片范围。严格遵循 TDD 循环：先编写并运行目标测试，捕获符合预期的失败日志（保留红灯证据）；编写最小实现，使测试转绿；按规范对核心判据实施变异测试，随后准确恢复变异前的实现。完成后，运行本切片适用的检查命令，将实际输出、受测输入摘要和剩余问题写回任务卡，提交后关联完整 Commit SHA。若遇到关键规格冲突，立即暂停受阻部分并向我反馈，继续推进不受影响的工作。”

**切片完成标准**：本切片的各项验收准则均有实际执行的验证证据；适用门禁全部通过；当前交付内容与受测输入摘要一致；尚未完成的范围已明确标注。“S1 完成”仅代表当前切片完成，严禁直接宣告整个需求交付完毕。

---

### 第五步：双轴独立审查与合入检查

锁定候选源码版本、变更差异与相关依据，由独立 Reviewer Agent 或独立审查者复核。Standards 轴（规范一致性）与 Spec 轴（需求符合度）分别给出结论，可在同一报告中分节记录。L3 及团队另有规定的任务，须由对应的人类领域责任人独立签字；具体深度按 §2.2 执行。

> [!TIP]
> **审查指令（Prompt 范例）：**  
> “请对照指定基线审查当前候选版本。Standards 轴检查代码及文档是否符合现行规范（并发安全、契约破坏、架构违例、盲区声明）；Spec 轴逐项核对任务卡验收准则、未覆盖边界与异常恢复。每个发现项必须明确指出具体位置、违规依据、触发条件与影响，并如实列出未审查范围。只做审查，严禁代为修改；不得以作者‘已自测’的口头声明作为通过证据。”

Agent 修复审查发现的问题并重新运行受影响门禁，审查者复核并关闭问题。通过后，遵循仓库分支保护规则完成提交、CI 验证与代码合并。**随后选择下一个切片，重复第四步与第五步，直至全部切片完结。**

---

### 第六步：发布交付与状态记录

先在最终交付组合上逐项核对全部任务验收准则及端到端结果；各切片分别通过不能替代整任务验收。无需部署的任务也须完成组合验收与交接；只交付部分范围时保留 OPEN，不宣告整个需求完成。

全部必备切片合入且范围齐备后，按第七章构建不可变候选制品并登记候选清单，在隔离环境完成适用的制品、迁移、业务与恢复验收。准入通过后固化发布清单（Release Manifest），再按已验证顺序向获准的目标环境发布，记录核验结果与部署回执。无部署任务完成验收和交接即可。

任务卡应如实记录各项交付状态：**已实现、已验证、已合入、已部署、仍未完成（OPEN）**。未涉及部署的任务明确标注“不适用”，严禁虚构上线事实。新增的架构决策、契约定义或运维操作说明，仅回写至对应的权威文档，严禁将任务卡全文机械复制到多个位置。发布后按 §0.7 核对需求效果，未达目标或新发现的问题回到需求池；部署完成不自动代表业务目标达成。

---

## 一、核心工程定位与基本原则

### 1.1 人机协作边界定义

* **人类负责人**：确定业务目标、关键取舍、权限边界与验收口径；澄清不能由实现者自行判断的业务歧义；承担领域审查与交付责任。
* **执行 Agent**：探索代码与文档、拟定方案、切片实施、运行验证、定位失败、维护证据与交付资料；在授权边界内自主推进。
* **Reviewer Agent / 独立审查者**：以固定的规范和需求为依据，独立复核代码及文档，指出缺陷、证据盲区与未覆盖场景。
* **工具与流水线**：通过确定性、可重复的构建、检查与测试执行工程约束。模型推断与确定性工具的执行结果分别记录，严禁互相替代。

### 1.2 三项工程原则

1. **证据验收（Evidence over Attestation）**：
   * 任务完成声明必须对应明确的**受测版本（Commit SHA / 内容摘要）、实际执行命令、运行环境、退出码及可访问证据**；
   * PR 勾选框、截图数量、Agent 自述或单纯“CI 配置已存在”，均不能作为完成证据。
2. **基础设施先行（Harness First）**：
   * 明确的规则、可运行的环境、可信契约与验证入口是工程交付的基础；
   * 缺失的门禁应明确登记负责人与补齐计划，不得以更换能力更强的模型代替工程基础设施建设。
3. **按风险准备资料（Proportional Artifacts）**：
   * 关键上下文必须存入可追踪的任务系统或版本化文档中；
   * 充分复用既有文档链接，小任务合并记录，仅为新的重要决策、安全边界或核心证据创建新材料，避免不必要的文书负担。

本文将阻止不合格变更进入下一阶段的检查称为**质量门禁**（下文简称“门禁”）；将需求拆成可独立验证的增量称为**任务切片**。判定任务完成的标准、版本发布条件和业务效果目标分别记录，避免混用。

### 1.3 文档权威与真实状态

每个项目应设立清晰的规范入口，明确哪些记录分别规定**强制约束、业务决策、当前规格、实施顺序与运行操作**。历史审计与废弃方案应保留其历史语境。

重要文档必须显式标注生命周期元数据：
> **核心元数据格式**：  
> `{ 状态, 适用范围, 责任人, 依据版本/日期, 关联决定, 替代关系, OPEN 项 }`

* **状态定义**：通用文档可采用 `Draft`（草案）、`Accepted`（已接受）、`Effective`（当前有效）、`Superseded`（已替代）、`Archived`（历史归档）；实现与验证状态另行独立登记。决策记录的 `Proposed` 对应草案阶段，另保留 `Rejected` 表达否决，不能与“已替代”混用；
* **执行机制与落实状态声明**：规范声明“由 CI 阻断”时，必须能定位到实际执行入口与流水线中的实际阻断点；人工判断项明确标注“人工复核”；未落地的能力统一标注为“计划中”。

---

## 二、任务分级标准与最高风险等级原则

### 2.1 按最高风险等级执行（Highest Risk Overrides）

> [!IMPORTANT]
> **凡改动触及以下任一核心语义或运行行为，无论代码增删行数多少（哪怕仅改动 1 行），必须按 L3 级标准执行，不得降级：**
> 1. **资金与记账**：金额计算、数值精度、舍入截断、账本流水、账户余额、支付/退款流转、订单资金状态机；
> 2. **身份与权限**：认证机制、JWT 校验、mTLS、Session、授权策略、租户数据隔离、密钥与敏感数据边界；
> 3. **数据与持久化**：数据库 Schema、数据迁移、破坏性 DDL/DML、数据订正/清理、数据恢复与重建脚本；
> 4. **边界与对外契约**：公开 API、事件消息 Schema、跨模块/跨服务分布式状态协作，以及引发多方契约变动的联合交付。
> 
> *注：纯排版、错别字等不改变业务语义的修改按实际风险处理；修改规范中的业务决定、权限要求或验收口径，仍属于高危语义变更。*

### 2.2 任务分级管控矩阵

| 级别 | 适用场景与边界 | 最小上下文载体 | 审查深度与方式 | 验证与环境隔离要求 |
| :--- | :--- | :--- | :--- | :--- |
| **L1 (轻量)** | 非敏感局部修正、文案或开发辅助改动 | 单张任务卡（目标、边界、依据、验收一体化） | 对照任务卡与适用规范；单份报告分两轴输出 | 仓库规定的编辑期/提交前检查；按冲突风险选择工作区 |
| **L2 (标准)** | 模块内常规特性、非破坏性重构、多文件联动 | `spec.md` + 简短计划，引用现有架构与规范 | Standards / Spec 双轴审查 | 受影响闭包验证、全量回归节拍；隔离工作目录及冲突资源 |
| **L3 (高危/跨仓)** | **命中任一高风险条件**，或跨仓联合交付 | 需求与验收、设计/契约、必要 D-ID/ADR、测试与恢复方案 | 双轴审查；**由具备领域责任的人类独立审查并签字（Sign-off）** | 适用的全量验证与真实依赖集成测试、故障/幂等/持久化检查、制品冒烟；独立隔离测试资源 |

> [!NOTE]
> * 级别决定验证深度，不代表机械运行所有无关测试；每项测试的适用性应在计划中说明，不适用、未运行和失败绝不能记为通过；
> * L3 所需信息可整合在单一设计或任务文档中，不强制创建空文件；独立审批按领域职责判定，不以堆砌审查人数代替专业判断。

### 2.3 开工准备与就绪条件

本节承接第〇章已澄清并选入近期计划的需求，说明具体实现前的准备；它不替代需求价值判断、容量评估或版本取舍。

1. **确认现状与权威**：查阅项目入口、现行规范、有效决定与相关代码；检查工作区状态及并发任务，区分已实现的功能、设计目标与技术欠账；
2. **明确需求与边界**：明确用户画像、核心痛点、交付范围、非目标、成功与失败分支，确保验收口径可判定；
3. **确定领域与契约**：锁定数据责任方、领域不变量、状态机流转、接口契约、权限规则及失败恢复语义；
4. **选择技术方案**：优先复用成熟方案与现有依赖；对比必要备选方案，评估技术风险与环境约束；
5. **完成必要决策**：引用既有决策编号；对新权衡、设计冲突或推翻旧决定的事项取得正式决策，不得自行猜测；
6. **设计验证与交付**：将验收准则逐条映射至测试类型、环境要求、命令入口、责任人、证据形式与恢复步骤；
7. **形成切片计划**：按契约与依赖拆分为可独立验证的切片，明确各自完成条件，再进入第三章的实施循环；适用行为变更采用 TDD。

### 2.4 项目级文档体系与维护矩阵

以下定义信息职责而非硬性文件名；小项目可合并承载，每类事实只保留一个权威来源。

| 文档类型 | 适用时机 | 核心要素 | 维护责任人 |
| :--- | :--- | :--- | :--- |
| **需求池 / 产品路线图** | 持续收集、定期复查 | 需求来源、问题证据、目标、排序、依赖、取舍理由与状态权威链接 | 产品 / 需求负责人 |
| **README / 项目总览** | 项目存续期间持续维护 | 项目定位、快速启动、核心模块、文档索引、关键联系人 | 仓库维护者 |
| **AGENTS / 规范强制约束**| 多 Agent / 人员协作期间 | 开发强制约束、门禁与阻断规则、文档读取条件、命令入口映射 | 架构师 / 工程负责人 |
| **工程规范** | 技术栈选定或规则变更时 | 命名、分层调用、错误通道、并发、依赖准入、日志脱敏、配置演进 | 各技术领域负责人 |
| **产品需求与业务规则** | 功能立项及范围变更时 | 用户任务、业务规则、Non-goals、交付里程碑与验收范围；引用需求池和路线图的排序事实 | 产品 / 业务负责人 |
| **领域模型 / 术语词典** | 业务逻辑演进全周期 | 领域概念定义、实体关系、状态机流转、核心业务不变量 | 领域专家 / 业务架构师 |
| **架构总览与拓扑图** | 系统结构重大调整时 | 模块划分、数据流向、上下游依赖、网络拓扑与安全域划分 | 系统架构师 |
| **决策台账 (D-ID / ADR)**| 涉及关键技术/业务选型时 | 决策编号、背景痛点、备选评估、决策结果、影响与后果、状态 | 决策发起人 / 审批人 |
| **接口契约 (SPEC / Schema)**| 跨模块/跨服务接口设计时 | 协议规范、数据结构、幂等键、错误码、向后兼容性、结果未知时的处理方式 | 接口提供方负责人 |
| **安全设计 / 威胁模型** | 鉴权、敏感数据流向变更时 | 数据流图、潜在威胁、凭据范围、攻击面分析、缓解控制、验证责任 | 安全团队 / 核心研发 |
| **Agent / 工具治理记录** | 首次接入 Agent、工具或权限变动 | 所有者、运行身份、工具来源、数据边界、拦截机制、审计与停止入口 | 工程负责人 / 安全管理员 |
| **测试策略与执行入口** | 业务实现前或测试体系演进时 | 测试分层、真实依赖与替身依赖、执行时机、命令、阻断规则、证据与盲区 | 测试架构师 / 研发负责人 |
| **UI / 交互 / 无障碍规范**| 涉及人机交互界面开发时 | 信息架构、组件状态、响应式断点、键盘/焦点流、读屏语义、设计基线 | 前端负责人 / UI/UX 设计师 |
| **发布与运维手册 (Runbook)**| 服务进入部署与持续运行时 | 构建打包、环境配置、数据迁移、观测指标、告警策略、故障处置 | SRE / 服务负责人 |

### 2.5 任务级文档清单

| 文档类型 | 编制时机 | 核心要素 | 裁剪与简化规则 |
| :--- | :--- | :--- | :--- |
| **迭代 / 批次计划** | 开始前及范围变化时 | 目标、容量、切片、依赖、审查与验证窗口、变更记录 | 复用现有计划或任务系统，不复制实现状态 |
| **版本计划** | 确定交付目标时 | 用户与环境、必备/可调整范围、目标窗口、退出条件、恢复与效果观察 | 发布准入时关联 Release Manifest；不以计划冒充回执 |
| **任务卡 / Intent** | 开工前 | 痛点描述、目标用户、交付范围、非目标、强制约束、风险等级 | L1 任务单卡承载；已有需求直接引用链接 |
| **SPEC 规格** | 实现具体行为前 | 输入输出契约、状态迁移、成功与失败语义、OPEN 范围、验收标准 | 可与任务卡或技术方案合并编写 |
| **技术方案 / RFC** | 架构调整或关键取舍前 | 现状、备选方案、选型权衡、数据模型影响、风险、回退方案 | 沿用成熟设计时仅记录本次差异 |
| **D-ID / ADR** | 依赖该决定的实现前 | 最终决定、决策人、依据、收益与代价、替代关系 | 普通局部实现细节不单独立项 |
| **实施计划** | 切片前并动态维护 | 依赖拓扑、执行切片、跨仓协同人、资源预算、完成条件 | 文件清单属于可演进计划，严禁替代业务承诺 |
| **本次执行授权与例外** | 执行动作前，范围变化时更新 | 明确主体、工具、资源、环境、期限、预算、停止入口及例外到期时间 | 默认置于任务卡内；已有配置仅引用版本及差异 |
| **测试计划 / 向量** | 实现前设计，实现中扩充 | 验收映射、独立预期、边界用例、真实依赖、故障注入与变异测试 | 允许直接以可读代码用例与测试夹具承载 |
| **数据迁移方案** | 持久化变更前 | 版本基线、读写兼容策略、执行顺序、权限要求、回滚/向前修复 | 无数据变更的任务不创建 |
| **Review 报告** | 规格就绪及实现冻结后 | 比较基线、两轴依据、缺陷发现、处置记录、复核确认、未审查范围 | Standards / Spec 两轴可合并在单份文档分节呈现 |
| **EVIDENCE 验证记录** | 关键验证完成后 | 受测 Commit、执行命令、环境摘要、退出码、日志路径、覆盖边界 | 原始日志独立归档，正文保留可检索索引与结论 |
| **Release Manifest** | 跨仓联合交付或发布前 | 源码 SHA、制品摘要（Digest）、兼容矩阵、迁移校验和、配置引用、恢复方案 | 简单单仓发布复用原有发布记录 |
| **效果评估 / 复盘** | 版本观察窗口到期、迭代结束或问题处置后 | 目标与实际结果、交付瓶颈、故障证据、必要的根因分析、改进责任人 | 优先补充类型约束与自动化用例，最后补充规则文档 |

### 2.6 D-ID（决策编号）与 ADR 的联动机制

* **D-ID（Decision ID）**：项目内部业务与技术决策的唯一追踪编号（如 `D-001`）；
* **ADR（Architecture Decision Record）**：重大技术与架构选型的论证记录。

两者互为补充：重大决策由 ADR 记录详细论证，由 D-ID 台账统一索引并指向最终决策；新项目亦可仅使用 ADR 承载完整的决策过程。

* **决策记录核心要素**：问题背景、备选方案（含未选理由与调研日期）、最终决定、决策人、签署日期、收益与代价、退出/重评条件、生命周期状态（`Proposed` / `Accepted` / `Rejected` / `Superseded`）、受影响依赖链；
* **决策演进原则**：已接受的决定发生改变时，必须新增记录并建立替代关系链接；
* **状态独立性**：`Accepted` 仅代表决策本身获批，不等于代码已实现或已验收；
* **完整追溯链**：  
  > `需求/Issue` ➔ `D-ID / ADR` ➔ `当前 SPEC/契约` ➔ `提交 Commit` ➔ `测试向量` ➔ `执行证据` ➔ `Manifest/OPEN 项`

### 2.7 协作契约与依赖协同顺序

接口双方开始编码前，必须明确：**由哪个服务负责接口与数据的权威定义、数据如何产生、消费方需兼容哪些版本，以及各方的运行身份和对接负责人**。

* **标准协作顺序**：权威方发布契约 ➔ 消费方按约对接 ➔ 按依赖顺序完成对接 ➔ 验证权限与业务语义 ➔ 跨服务联合验收；
* **跨仓交付要求**：源码之间存在依赖关系，并不能证明相关服务已部署到目标环境；各模块各自跑通单元测试，绝不能替代跨仓交付组合的端到端联合验收。

### 2.8 新项目或首次接入：建立最小可运行环境

首次建立基础设施后持续复用；工具链、契约或运行环境变化时维护并重新核验相关入口。若已有等价入口、文档和流水线，只需修补缺口，无需推翻现有目录或重命名。

#### 第一步：整理入口，明确四类核心信息

以下是示例组织方式；也可合并为同一文档中的不同章节，保持每类信息只有一处正式记录。

```text
AGENTS.md                 开发强制约束、执行规则、其他文档的读取条件
docs/project.md           项目目标、模块/数据权威、现行方案与决策入口
docs/testing.md           真实命令、测试环境、触发条件、证据归档与失败处理
docs/tasks/T-001.md       首个任务卡：需求、验收、切片、实施与审查证据
```

*完成标准：新接手的 Agent 能顺利定位现行规则、本次任务与验证方式；每类结论仅保留单一权威位置。*

#### 第二步：查明命令并实际运行

Agent 从构建配置、包管理脚本与已有 CI 中查明执行入口，填写下表并实际运行，建立初始基线：

| 用途分类 | 登记与填写内容 | 首次接入时的验证动作 |
| :--- | :--- | :--- |
| **环境准备** | 工具链版本、基于锁文件的依赖安装命令、配置来源 | 在约定环境中完成安装；密钥仅记录引用 |
| **服务启动** | 实际启动命令、依赖服务、监听端口、健康检测、退出方式 | 应用真实启动并能正常响应退出信号 |
| **定向验证** | 如何指定当前模块或单条用例 | 修改目标代码后能获得稳定且可复现的反馈 |
| **提交前检查** | 实际脚本/命令、工作目录、触发时机 | 真实运行并确认退出码；如实记录失败或通过 |
| **完整回归** | 全量回归入口、条件门及真实依赖是否需单独启动 | 明确适用范围；缺失入口登记补齐责任人 |
| **集成与恢复** | 依赖服务启动、数据夹具、权限配置、库重建与清理入口 | 在自有测试资源上完整运行代表性用例 |
| **证据留存** | 日志落盘目录、版本与环境摘要记录方式 | 团队成员能依据路径找到并确认本次运行结果 |

*完成标准：本次试点所需命令均已真实执行并留存基线记录，缺失项已登记补齐责任人。*

#### 第三步：让工具接管规则与执行

1. 优先将重复操作封装为项目原生脚本，确保本地与 CI 执行完全相同的命令；
2. 维护者配置并验证 CI 保护链路：事件触发 ➔ 干净环境执行 ➔ 命令失败使 Job 失败 ➔ 分支保护阻止合并 ➔ 由指定责任人处理失败；
3. 验证 Agent 执行边界：在无敏感数据的隔离环境中，依次测试一次允许动作、一次越界拒绝与一次停止/撤权；无法拦截的操作严禁授予对应凭据。

#### 第四步：用一个真实需求验收全套机制

按前文“快速上手”的六个步骤跑通首个真实任务（T-001），完成端到端验证，形成可复用闭环。

---

## 三、核心工程循环模型（The Three Engineering Loops）

本章承接第二章的开工准备，分别说明切片实现、合并准入和版本交付。图中的 TDD、领域签字、系统测试与部署均按任务适用范围执行；无须部署的任务在验收与交接后结束工程交付。

```mermaid
flowchart TD
    Planning["需求与规划<br/>问题证据 · 排序 · 容量 · 版本目标"] --> Ready["开工就绪<br/>需求 · 契约 · 决策 · 验收与资源"]

    subgraph INNER["内循环：切片实现与本地验证"]
        Slice["明确当前切片与验收映射"] --> Implement["实施与验证<br/>适用时先红后绿 · 变异测试 · 恢复与重构"]
        Implement --> Freeze["冻结受测输入<br/>源码 · 配置 · 夹具 · 环境摘要"]
        Freeze --> LocalGate["运行适用本地门禁<br/>按团队节拍选择范围"]
        LocalGate --> LocalResult{"结果通过且输入一致？"}
        LocalResult -->|否：诊断修复| Implement
        LocalResult -->|是| Commit["提交受测内容<br/>关联完整 Commit SHA 与证据"]
    end

    subgraph MIDDLE["中循环：独立审查与合并准入"]
        Candidate["锁定审查基线与候选源码版本"] --> Standards["Standards 轴：规范一致性"]
        Candidate --> Spec["Spec 轴：需求符合度"]
        Candidate --> CI["适用的 CI 检查<br/>保留实际结果与证明范围"]
        Candidate --> Expert["L3 或另有规定时<br/>领域责任人独立签字"]
        Standards --> Admission{"阻断项已关闭且准入通过？"}
        Spec --> Admission
        CI --> Admission
        Expert --> Admission
    end

    subgraph OUTER["外循环：交付、运行与效果反馈"]
        Merge["合入主干"] --> NeedDeploy{"本次成果需要部署？"}
        NeedDeploy -->|否| Handoff["完成验收与交接<br/>部署记为不适用"]
        NeedDeploy -->|是| Scope{"版本必备范围齐备？"}
        Scope -->|是| Build["构建不可变候选制品<br/>登记候选清单"]
        Build --> Artifact["隔离验收<br/>制品 · 业务链路 · 迁移与恢复"]
        Artifact --> ReleaseGate{"发布准入通过？"}
        ReleaseGate -->|是| Manifest["固化发布清单与批准范围"]
        Manifest --> Deploy["按序发布至获准目标环境<br/>健康与业务核验"]
        Deploy --> Healthy{"发布结果满足条件？"}
        Healthy -->|是| Receipt["成功回执与运行交接"]
        Healthy -->|否或结果未知| Recover["暂停扩大发布范围 · 核查事实<br/>按预案恢复并记录失败或未知回执"]
        Receipt --> Outcome["效果观察与交付复盘<br/>目标达成 · 运行问题 · 改进动作"]
        Handoff --> Outcome
    end

    Ready --> Slice
    Commit --> Candidate
    Admission -->|否：修复后重新验证与审查| Implement
    Admission -->|是| Merge
    Scope -->|否：继续后续切片或调整计划| Ready
    ReleaseGate -->|否：保留阻断记录| Ready
    Recover --> Ready
    Outcome --> Planning
```

### 3.1 【内循环】切片实现与本地验证（Local Micro-Loop）

本指南在 TDD 的“红—绿—重构”基础上增加核心判据的变异测试，用于验证测试确实能够发现目标缺陷：

1. **先红（Red）**：编写针对目标行为的测试，实际运行并捕获预期的失败。目标接口尚未声明导致的编译失败可作为初始红的一部分；依赖缺失、环境未启动或无关语法错误不能作为有效红灯。
2. **转绿（Green）**：编写满足目标契约的最小实现，确认目标测试通过。
3. **变异测试（Mutation Testing）**：在隔离环境临时移除核心校验、破坏目标不变量或修改关键业务规则，再运行对应测试。测试应由通过转为失败，以证明该断言能发现这类缺陷；这不等于证明测试已覆盖所有错误。
4. **恢复与重构（Restore & Refactor）**：准确恢复变异前的实现，确认测试重新转绿；在测试持续通过的前提下重构，再运行受影响检查。

> [!TIP]
> * **先红豁免**：纯文档或注释修改、生成产物刷新，以及既有测试无需改变期望且持续通过的局部机械重构，可豁免先红。仍须执行适用检查并记录依据；行为变化不能以“重构”为名豁免。
> * **变异测试范围**：依据风险与测试计划选择核心业务判据；不得为无可执行行为的改动编造测试结果。
> * **重复失败处置**：同一失败在无新证据、无新假设时连续出现 3 次，暂停该路径的盲目重试，转入根因诊断；不受影响的工作可继续。

#### 3.1.1 受测输入冻结与证据绑定

* **明确输入**：登记本次验证实际使用的源码、配置、夹具、契约、依赖与环境。Git Commit SHA 或代码树 Hash 只标识其中一部分；参与验证的未跟踪文件、生成文件和外部输入须单独纳入清单或明确排除，敏感值仅记录安全引用。
* **冻结与运行**：格式化和自动修复在冻结前完成；验证时使用工具支持的只检查模式，禁止隐式改写受测输入。构建与日志输出放在约定目录，不因正常生成输出误判输入漂移；生成物若参与后续验证，应登记其摘要。
* **关联版本**：运行前后核对输入摘要，记录真实结果；提交后将证据关联到对应的完整 Commit SHA。后续改动不会抹去历史证据，但旧证据不能直接证明新版本通过，应按影响重新验证。
* **受控重绑定**：仅在团队已定义并实现证据复用机制，且工具校验受测输入、比较基线、环境、检查集合及有效期均满足政策时，才可把已有证据关联到新提交。不能仅凭“只是 Rebase”或“只改文档”放行；条件不满足或无可用校验机制时，重新运行适用检查。重绑定不等于重新测试。摘要覆盖完整内容树，或由项目正式登记且有遗漏校验的输入闭包；同时核对工具版本、门禁清单版本与环境。无法归类的变更、闭包不完整或基线失效时按项目规则回退完整验证，不能用人工猜测复用旧绿。

#### 3.1.2 分层门禁与执行节拍

下表是本文的分层示例，名称、触发点和范围须映射到团队真实入口。T0—T3 表达执行节拍，不代表测试技术，也不要求每个任务依次运行所有层级。

| 节拍层级 | 建议触发时机 | 验证职责与边界 |
| :--- | :--- | :--- |
| **T0（编辑内环）** | 编辑期间 | 当前模块的类型检查、Lint 与快速测试，提供及时反馈 |
| **T1（提交门禁）** | 提交前，按团队规则执行 | 受影响闭包及规定的轻量检查；影响范围未知时回退全量 |
| **T2（完整回归）** | 任务验收、合并前或团队规定的全量节拍 | 项目定义的全量回归与条件门；明确是否包含外部依赖 |
| **T3（系统验证）** | 相关高风险变更、定时构建或发布前 | 真实依赖集成、迁移、端到端、故障及恢复验证；范围由本次影响决定 |

每个入口均按 §6.2 登记执行者、阻断位置、证据与盲区。若门禁受阻，先诊断并记录责任人与下一步；不得把受阻、未运行或历史失败改记为通过。

### 3.2 【中循环】合并准入（PR Admission Loop）

* PR 或等价变更单关联需求、适用规格、两轴审查和验证记录；涉及重要决定时补充 D-ID / ADR。上述信息可位于同一张任务卡中，不要求小任务创建多份文件。
* 核对本次适用的 Required Checks，分别记录未运行、取消、跳过、受阻、失败与通过。不适用项注明依据，不计作通过；历史失败是否允许例外，按既定规则由有权负责人处理。
* 审查发现按第四章完成处置与复核。候选内容或合并基线变化后，重新判断验证和审查范围；必须绑定实际合入的内容。
* 合并权限由分支保护等机制执行；未配置自动阻断时，明确人工责任人，不能宣称已由 CI 强制。

### 3.3 【外循环】发布、运行与效果反馈（Release & Evolution Loop）

* 切片合入后先判断版本必备范围是否齐备；未齐备时继续实施或调整计划，不能把每次合入都当成一次完整发布。
* 需要部署的版本按第七章完成“候选构建与登记 → 隔离验收 → 准入固化 → 目标环境发布 → 核验与回执”。运行问题按预案处置，结果未知时先查证。
* 完成运行交接后，按 §0.7 观察用户结果和业务目标，按第九章分析交付瓶颈。正常交付做效果评估与改进；发生事故或已确认缺陷时再开展相应的根因分析。
* 缺陷改进优先落入类型或编译约束、确定性回归测试、可靠工具，再补充必要规则；同步清理失效规则。未完成项带责任人与复查条件回到需求池。

### 3.4 测试资产矩阵与验收映射

```text
验收条目 → 断言/用例 → 真实或替身依赖 → 执行入口 → 触发节拍 → 责任人 → 阻断位置 → 结果证据 → 已知盲区
```

同一验收条目可由多类测试共同证明；同一端到端用例也可覆盖多个条目。用户验收按已接受的目标与环境核对最终结果，不因端到端用例通过而自动完成业务验收。预期值须独立于被测实现推导，替身通过不能代替真实依赖验证。

| 测试类别 | 核心验证目的 | 必须声明的边界与已知盲区 |
| :--- | :--- | :--- |
| **静态 / 架构检查** | 类型安全、分层依赖方向、禁用 API、代码规范 | 无法验证动态运行时语义与业务逻辑正确性 |
| **单元测试** | 纯函数、算法实现、值对象、领域不变量 | 无法验证跨模块集成协作与真实持久化副作用 |
| **组件测试** | 组件生命周期、状态机迁移、内部模块交互 | 明确哪些依赖真实、哪些外部依赖被 Mock 替换 |
| **性质 / 模糊测试** | 在广义输入域内校验数学性质与不变量，搜寻极端反例 | 声明随机输入域范围、种子（Seed）及可复现用例 |
| **业务数值向量测试** | 精确校验金额公式、舍入规则、量纲换算及边界临界点 | 预期值必须独立推导，严禁在测试体内复制生产代码实现 |
| **编译契约 / 诊断测试**| 类型推导约束、正反编译断言（如 Rust trybuild）、文档用例 | 区分编译期类型拦截与运行时逻辑断言 |
| **API / 跨语言契约** | 服务边界字段类型、错误编码、向下兼容性 | 区分通信 Schema 兼容性与业务授权语义兼容性 |
| **真依赖集成测试** | 事务隔离级别、真实 SQL 行为、缓存失效、分布式锁 | 声明真实服务版本、运行身份、初始 Fixture、迁移基线 |
| **端到端业务测试** | 从入口请求至最终业务终态的全链路流转 | 明确起止边界，声明中间环节的替身依赖与未覆盖路径 |
| **冒烟测试** | 验证构建发布产物是否具备基本可运行性 | 属于关键路径探针，严禁等同于全量回归或生产验收 |
| **确定性故障恢复测试**| 在受控时序下模拟重试风暴、租约过期、宕机接管 | 区分软件模拟故障与真实物理网络/硬件故障的差距 |
| **浏览器 / App 行为** | 客户端真实渲染、路由导航、交互反馈、权限提示 | 模拟器环境不等于真机硬件；连接真实浏览器不代表后端真实 |
| **视觉 / 无障碍测试** | 界面布局、多端适配、焦点流动、键盘导航、读屏语义 | 视觉截图完全正确无法证明业务状态、金额及授权正确 |
| **性能 / 压力 / 容量** | 吞吐上限、P99 延迟、内存泄漏、背压机制 | 声明负载模型、硬件规格、数据基数与噪音过滤方式 |
| **覆盖率 / 变异评估** | 评估测试集的行/分支覆盖深度与对逻辑缺陷的击杀率 | 代码被执行不代表被有效断言；严禁追求无意义的覆盖率数字 |
| **Agent 治理 / 对抗验证**| 越权拒绝、注入隔离、审批绑定、预算拦截、停止与委派边界 | 确定性策略拦截与模型对抗评测分别记录；观察真实系统副作用 |
| **安全与权限验证** | 越权、租户隔离、敏感数据边界及威胁模型中的场景 | 工具扫描不能穷尽业务逻辑缺陷；按风险安排人工审查 |
| **迁移与发布制品验收** | 迁移顺序、不可变产物启动、配置与恢复前提 | 使用真实候选制品；禁止依赖源码挂载补齐缺失文件 |

---

## 四、审查体系：双轴 × 双轨审查模型（Dual-Axis & Dual-Track Review）

```mermaid
flowchart TD
    Baseline["固定审查输入<br/>比对基线 · 变更差异 · 权威规范 · 原始需求"] --> Review["代码与文档审查"]

    subgraph WHAT["两条审查轴：审查什么 (What)"]
        StandardsAxis["Standards 轴：规范一致性<br/>架构分层 · 契约兼容 · 规则冲突 · 盲区声明"]
        SpecAxis["Spec 轴：需求符合度<br/>意图对齐 · 边界遗漏 · 失败恢复 · 显式划定 OPEN"]
    end

    subgraph WHO["两条执行轨：由谁判定 (Who)"]
        AgentTrack["Reviewer Agent 轨 (独立 Context)<br/>范围内缺陷检查 · 竞态分析 · 反例推演<br/>结论具非确定性，需校准"]
        HumanTrack["人类决策轨 (业务/技术负责人)<br/>业务目标确认 · 商业取舍 · 风险接受<br/>高危模块领域独立 Sign-off"]
    end

    Review --> StandardsAxis
    Review --> SpecAxis
    StandardsAxis --> AgentTrack
    StandardsAxis --> HumanTrack
    SpecAxis --> AgentTrack
    SpecAxis --> HumanTrack
    AgentTrack --> Reports["两轴分别给出审查结论<br/>发现项 · 依据索引 · 处置状态 · 复核记录 · 盲区声明"]
    HumanTrack --> Reports
    Reports --> Gate["阻断项清零后准入 (Gate)<br/>声明自动阻断必须有实际生效的 CI 检查，否则由人工负责"]
```

### 4.1 审查两轴定义（What to Review）

代码与文档变更均按风险开展双轴独立审查，审查前必须固定比较基线、变更差异、权威规范与需求来源。

| 审查对象 | Standards 轴：是否符合规范 (Compliance) | Spec 轴：是否满足需求 (Fulfillment) |
| :--- | :--- | :--- |
| **代码实现** | 架构分层、并发竞态、协程泄漏、错误通道、向后兼容性、假测试排查 | 业务意图吻合度、领域不变量、权限判定、异常恢复、验收映射、显式界定 OPEN 范围 |
| **技术文档** | 权威冲突、术语统一性、版本有效性、引用真实性、门禁执行主体、盲区声明 | 需求遗漏、逻辑歧义、状态机完备性、可判定验收口径、失败语义、未决假设、跨服务责任 |
| **交付记录** | 制品 Digest、验证证据范围、迁移校验和、配置引用安全、审批机制是否实际生效 | 本次实际交付范围、端到端业务验收证据、回滚/恢复前置条件、未覆盖场景声明 |
| **Agent 治理事实** | 授权依据、身份归因、工具版本、权限拦截点、审计完整性与例外期限 | 工具动作是否落在本任务边界内；停止后副作用、未知结果及人工接管预案是否就绪 |

#### 失败语义与“结果未知”处理规范

编写规格和开展审查时，至少区分以下状态，并说明各自可观察的证据：

1. **确定拒绝（Definite Rejection）**：系统明确拒绝业务受理；不得发生契约禁止的业务副作用，但可能写入审计或幂等记录，不能笼统称为“零持久化”。
2. **确定未提交（Definite Not Submitted）**：有可靠证据证明请求未进入受理路径，例如在本地发送前被拦截；仅凭超时或一次查询未找到，不能作此判断。
3. **已受理在途（Accepted & Processing）**：服务端已确认受理，处理尚未完成。
4. **已确认终态（Confirmed Terminal Result）**：已确认成功或失败；失败时仍须按契约核对部分副作用、资源清理与补偿状态。
5. **结果未知（Result Unknown）**：调用方因超时、断连或崩溃而无法确认实际结果；这是调用方的认知状态，不能覆盖服务端的业务状态。

> [!WARNING]
> **不得将“结果未知”直接判定为失败，也不得由客户端自动换键重发或盲目执行反向补偿：**
> * 必须保留原操作作用域（Tenant ID + Actor ID）、原请求幂等键及请求参数摘要；
> * 优先通过只读查询核验原请求；查询不可用、未找到或超出保留期时继续标注不确定性。只有契约明确允许且幂等前提仍成立时，才可按规定使用原键同参重试；不得自行改键；
> * 明确声明超时重试策略、同键同参/异参处理、数据保留期与跨重启恢复机制；
> * 涉及资金场景时，必须核验不可变原凭证、唯一副作用、账务守恒、重启恢复屏障及权限漂移后的安全边界。

### 4.2 两条审查轨道与自动化支撑（Who Reviews）

自动化检查为两条审查轨道提供基础证据：执行确定性规则工具，产出结构化原始数据。

* **Reviewer Agent 轨**：使用独立上下文开展审查，减少实现过程中的既有判断影响；独立上下文不是准确性保证，结论仍须依据证据与反例校准；对照规范与需求分别产出两轴审查报告，逐项列出违规依据、具体代码/文档位置、触发条件与修改建议；
* **人类决策轨**：负责重大业务目标的确认、架构权衡、风险接受及 OPEN 范围签署；凡命中 L3 级高风险红线，必须由对应的领域责任人独立签字审批（Sign-off）。
* **发现项定级**：使用 `BLOCKER`（阻断）、`WARNING`（警告）、`NIT`（建议），写明位置、触发条件、依据与影响。
* **处置与复核**：“接受、部分接受、拒绝、延期”表示处置决定；另记“待处理、已修待复核、已关闭”等解决状态。拒绝发现须提供反证并由审查者复核；非阻断项延期须有负责人和期限。所有有效且未解决的 `BLOCKER` 均阻止合入，不能仅凭“接受风险”或调整标签关闭。修复后补充验证，变更审查结论时保留理由与记录。

---

## 五、Web / App 视觉验证与 Computer Use

```mermaid
flowchart TD
    subgraph EXPLORE["【阶段一】交互探索与自适应调优 (Exploration & Tuning)"]
        Start["启动本地 Dev Server / 模拟器"] --> Observe["Computer Use / 浏览器视觉观察<br/>布局错位 · 状态流转 · 异常恢复 · 响应式断点"]
        Observe --> Fix["修改样式 (CSS) 与交互逻辑 (JS)"]
        Fix --> Observe
        Observe --> Ready["界面渲染符合设计 · 交互体验流畅"]
    end

    subgraph FREEZE["【阶段二】内容冻结与基线锁定 (Baseline Freeze)"]
        Ready --> Content["冻结实际验证输入并登记摘要<br/>源码 · 构建配置 · 夹具 · 环境"]
        Content --> Baseline["固化设计基线与受信任的渲染快照<br/>声明设备、视口规格、色彩空间、容差阈值"]
    end

    subgraph ACCEPT["【阶段三】同版本验收 (Acceptance)"]
        Baseline --> Behavior["行为与无障碍断言<br/>状态机 · 网络契约 · 焦点流动 · 键盘路径"]
        Baseline --> Visual["按影响选择视觉验证<br/>像素差异比对或人工核验"]
        Baseline --> Replay["留存交互回放证据<br/>关键路径 Trace、录屏或等价证据"]
        Behavior --> Evidence["组装视觉交付证据包 (Visual Artifacts)"]
        Visual --> Evidence
        Replay --> Evidence
        Evidence --> Pass{"适用门禁全部通过？"}
        Pass -->|是| Commit["提交完全一致的内容<br/>绑定最终 Commit SHA 与交付证据"]
    end

    Pass -->|否: 回退修复并重新冻结| Fix
```

### 5.1 探索、冻结与验收的三阶段流程

1. **阶段一：交互探索与自适应调优**：在隔离环境中，利用 Computer Use、浏览器或模拟器观察真实渲染结果，自主排查并修复布局错乱、交互死锁、异常状态与响应式适配缺陷。
2. **阶段二：基线冻结**：按 §3.1.1 登记受测输入与环境摘要，固定设计参考和可信的渲染基线；验证时不修改受测输入。内容变化后重新冻结，并根据影响重新执行验收，不能直接沿用旧结论。
3. **阶段三：同版本验收**：针对受影响的用户流程执行行为与无障碍检查，按测试计划选择视觉比对、人工核验及回放证据。记录设备、浏览器和容差等条件；通过后关联相同内容的最终 Commit SHA。具体范围以 §5.2 为准，未执行项不得标为通过。

### 5.2 前端 / App 验收范围与证据规范

| 验收维度 | 核心核验内容 | 边界声明与注意事项 |
| :--- | :--- | :--- |
| **交互行为** | 用户任务入口、表单校验、权限阻断、异常恢复、请求响应状态与最终数据落地 | 无未解释的非预期错误及未处理的 Promise 拒绝；故障注入产生的预期错误须被正确处理并单独记录 |
| **视觉呈现** | 覆盖产品支持的视口、设备及加载、空、成功、失败、超长文本等受影响状态；1920×1080 与 375×812 仅为示例 | 像素比对基于同环境渲染基线，严禁直接与 Figma 原始矢量图计算差分 |
| **无障碍 (a11y)**| 键盘 Tab 路径、焦点恢复、ARIA 标签、读屏播报、色彩对比度、减少动态效果适配 | 无障碍语义须独立核验，视觉截图不能代替 a11y 检查 |
| **故障留痕** | 关键用户流程留存 Playwright Trace、录屏（WebM/MP4）或等价交互轨迹 | 关键路径留存回放证据；微小文案修正按风险裁剪，不要求全流程录屏 |

```text
候选标识：<完整 Commit SHA 或代码树 Hash>；构建配置摘要：<Hash/版本>
测试场景：<用户任务名称与页面核心状态>
运行环境：<操作系统、浏览器内核/设备型号、版本号、视口尺寸、DPR、语言、时区>
依赖拓扑：<真实服务 / Mock 替身 / 网络数据夹具>
证据路径：<Baseline 图、Actual 图、Diff 差分图绝对路径；Trace 归档文件 URI>
最终结论：<PASS / FAIL / NOT_RUN / BLOCKED / NOT_APPLICABLE>
预期异常：<列出符合预期的拦截错误及对应处理理由>
已知盲区：<未覆盖的屏幕规格、深色模式、网络中断等声明>
```

---

## 六、工程基础设施与资源隔离建设（Harness Engineering）

### 6.1 Git Worktree 安全管理与多维隔离矩阵

Git Worktree 仅实现了工作目录的物理分离，**并非完全安全隔离的独立沙箱**（底层仍共享部分 Git 引用、全局配置及系统级资源）。

#### 1. Worktree 安全回收五步核验（严禁强制删除）

- [ ] **任务状态确认**：任务已完成、已移交或已取消，所需成果已保存且不再依赖此工作目录；部署状态单独记录；
- [ ] **工作成果归档**：所有工作分支与提交已安全推送到远端仓库，或完成本地快照备份；
- [ ] **工作区状态核查**：确认无未提交修改（Dirty Files）、无未跟踪的关键代码资产；
- [ ] **需保留的 Git 忽略文件**：核验并备份需要持久保留的本地调试配置（如 `.env.local`），严禁未授权上传；
- [ ] **关联进程安全退出**：确认没有其他使用者，关联的开发服务器、调试会话与容器已退出；不得误停共享进程或删除其他任务的资源。

#### 2. 并发资源隔离与配额

| 资源类别 | 隔离约束与分配规范 |
| :--- | :--- |
| **源码与构建** | 独立工作目录；冲突的 `build` / `dist` / `target` 目录物理隔离，受控复用安全的底层编译器缓存 |
| **网络与服务** | 分配互不重叠的端口段（BasePort + TaskOffset）；登记进程 PID 与所有者，严禁单纯按端口号盲目杀进程 |
| **数据与存储** | 优先分配独立临时数据库实例；采用 Schema 隔离时，必须确认权限系统与全局表未被跨任务污染 |
| **中间件隔离** | 仅在协议允许时为 Redis Key、Kafka Topic 与 Consumer Group 分配任务命名空间；固定协议名称须以独立实例或集群隔离，保持测试契约真实，严禁篡改生产环境协议定义 |
| **容器与计算** | Docker Compose 项目名隔离（`-p proj_task_123`）；为单任务设置 CPU 核心数、内存和磁盘使用上限 |
| **迁移序列号** | 涉及数据库变更时，统一预留迁移版本号，防止并发分支合并时发生迁移拓扑冲突 |

### 6.2 门禁契约五要素与结构化验证记录

每个仓库应在 `AGENTS.md` 或团队指定的规范入口中登记质量门禁，或引用其唯一记录位置，并明确以下五要素：
> **门禁五要素契约**：  
> `{ 适用范围, 执行命令与执行者, 阻断位置, 结果证据形式, 已知盲区与非目标场景 }`

```text
核验依据：<需求编号 / SPEC 章节 / D-ID / 验收条目>
受测对象：<仓库名及完整 Commit SHA / 受测代码树 Hash>
输入摘要：<构建参数、API 契约、数据夹具、迁移基线与依赖版本 Hash>
执行时间：<包含时区偏移的时间戳，如 2026-10-13T12:00:00+08:00>
执行环境：<操作系统、运行时版本、依赖服务版本、执行身份类型、计算规格>
执行命令：<完整可复现的 CLI 启动入口>
退出状态：<退出码 Exit Code，未执行填 N/A>
统计摘要：<Passed / Failed / Skipped / Cancelled 精确统计数值>
最终结论：<PASS / FAIL / NOT_RUN / BLOCKED / NOT_APPLICABLE>
证据资产：<完整日志文件绝对路径、生成报告 URI、产物校验和>
内容一致性：<前后代码树 Hash 比对校验结果，确认无隐式篡改>
证明范围与已知盲区：<本门禁成功证明了什么；本门禁抓不到什么/未覆盖哪些场景>
异常处置记录：<若发生失败或例外，记录处置人、原因分析及后续闭环要求>
```

---

## 七、发布准入、交付清单与运行维护

本章承接 §0.6 的版本计划和第三章的工程交付。版本计划描述目标与预期范围；候选清单登记待验收组合；发布清单（Release Manifest）固化获准部署的组合；部署回执记录实际结果。清单适用于单仓、多制品及跨仓交付，简单发布可复用现有发布记录。

### 7.1 发布清单的必要信息

| 信息 | 记录要求 |
| :--- | :--- |
| **范围与责任** | 版本目标、目标用户与环境、必备范围、负责人及适用审批 |
| **源码与制品** | 实际源码的完整 Commit SHA、构建记录、不可变镜像 Digest 或制品校验和 |
| **契约与运行前提** | 接口和消费者兼容范围、工具链与运行时版本、外部依赖 |
| **数据与迁移** | 迁移基线、文件与校验和、执行身份、顺序及数据核验方式 |
| **配置与密钥** | 配置版本或摘要、开关状态、密钥引用；不记录密钥明文 |
| **验收与已知问题** | 受测组合的证据、准入结论、非阻断 OPEN 项及接受人 |
| **发布与恢复** | 执行顺序、分批或灰度策略（适用时）、停止阈值、恢复前提与负责人 |
| **运行与交接** | 健康和业务探针、监控告警、值班与支持责任、用户可理解的发布说明 |

唯一可填写的完整示例见附录 A.15。所有摘要与阈值须来自真实产物或已接受的方案，模板中的占位值不能作为证据。候选组合变化后，按影响重新验收并生成新的清单版本；已固化的清单不直接覆盖修改。

### 7.2 从候选构建到发布回执

**准备：构建与登记候选。** 确认版本必备范围齐备，使用可追溯的构建输入生成不可变制品，记录候选清单。验证与后续部署引用相同摘要；验收后重新构建的产物属于新候选，除非已验证其内容完全一致并满足既定复用规则。

1. **阶段 A：隔离验收。** 将候选制品组合部署到预发或独立测试环境，先直接启动真实制品核对依赖装配、引导与版本，严禁挂载源码补齐运行依赖；再在真实依赖的隔离环境执行适用的契约、集成、业务与容量检查，核对最终业务终态、持久化、适用的账务不变量、幂等重试和服务重启恢复，验证迁移顺序、配置和恢复前提。涉及数据恢复时，核验备份可用性与恢复后的数据一致性。失败或受阻须处理后重新验证，不能进入下一阶段。
2. **阶段 B：发布准入。** 核对必备验收项、证据有效性、非阻断问题、发布与恢复责任。L3 及另有规定的变更取得相应独立签字；运维接手方确认监控、告警路由、支持安排和操作手册可用。随后固化发布清单版本、摘要及批准范围。
3. **阶段 C：发布、核验与回执。** 向获准的目标环境按顺序发布，执行迁移、配置、开关与服务部署，并核对实际部署身份、健康及获准范围内的受控业务读写探针、指标与告警链路。适用时先发布至有限范围，达到条件后扩大。失败或结果未知时暂停扩大发布范围、核查事实并执行恢复预案；成功、失败、部分完成和结果未知均如实留存回执，不得只记录成功发布。

预发环境验收不能直接证明生产运行正常。实际部署后仍须核对运行制品、配置、数据状态与关键业务结果；生产发布还应满足团队规定的生产授权和运维接管条件。无部署任务不创建虚构回执。

### 7.3 恢复策略与紧急修复

设计阶段选择适用策略，不将“回滚镜像并执行 down.sql”视为通用恢复方案：

* **向前修复（Forward Fix）**：保留已有数据事实，通过补丁或新增迁移修复问题；修复版本仍须有验证与发布记录。
* **代码回滚（Code Rollback）**：确认旧版应用兼容当前数据结构、配置及已产生的数据，再恢复旧制品；先按预案停止新增写入并排空或隔离在途任务，核对执行代际、业务状态及恢复后仍会运行的旧消费者。不能满足兼容或排空条件时拒绝直接回滚，改用另行验证的向前修复或数据恢复方案。
* **数据回滚或恢复（Data Rollback / Restore）**：明确可恢复时间点、允许的数据损失、停写顺序、备份有效性、业务核对与补偿方式。无法保证数据正确性时，禁止直接执行逆向迁移或恢复覆盖。

紧急修复可以按预先授权的应急流程调整顺序，但仍须保留事故编号、影响范围、负责人、最小必要验证、批准依据和部署回执。因应急延期的非关键检查须登记负责人和完成期限；受阻检查不能记为通过。恢复后核对真实副作用，再补齐复盘与改进任务。

### 7.4 运行维护与能力退役

发布后的运行责任持续存在。运维负责人跟踪可用性、容量、积压、错误、数据一致性与依赖维护，验证告警能够送达并被处理；需求负责人按 §0.7 评估目标效果。事故和紧急风险进入应急通道，常规缺陷、用户反馈及技术债回到统一需求池。

决定停止某项能力时，明确使用方与消费者、通知和支持期限、替代方式、停止受理及在途任务处理、数据保留或删除规则、资源和凭据回收、验收责任人。涉及真实数据和共享资源的操作按权限执行；完成收尾后记录退役事实，更新有效规格与支持范围。未发布的探索可以直接关闭，不套用生产退役步骤。

---

## 八、运行时治理与安全边界（Agent Governance）

> 本章主要治理**参与软件开发的 Agent**（包括本地编码 Agent、CI Agent、浏览器操作 Agent 及其工具链）。开发质量门禁与运行时控制必须并行：前者验证变更是否可交付，后者约束动作在何种身份与边界内发生。

### 8.1 最小权限原则与按环境授权（Least Privilege）

* **隔离测试环境**：在已授权的独立沙箱内，允许 Agent 自动化执行准备、数据库重建与清理；破坏性操作仍需程序化核验目标资源归属；
* **共享与生产环境**：任何破坏性改动必须纳入严格的人工审批流程；凭据按环境实施强隔离，严禁将生产环境长期有效的凭据直接暴露给编码 Agent；
* **授权多维约束**：授权同时限定工具、资源、数据类别、目标环境、网络出口、有效期与预算限额；“只读工具”亦可能引发敏感数据外泄，须严格审查外发目的地；
* **授权内执行与人工检查点**：有效授权内的常规操作自动化执行；仅当超出边界、授权到期或触碰规定红线时，才触发人工检查点；模型自述“置信度高”不构成越权依据。

### 8.2 提示词注入与执行授权隔离

* **不可信数据隔离**：Agent 读取的外部网页、Issue 评论、日志堆栈、第三方依赖文档等，**均被视为不可信外部数据**；
* **防止注入指令导致越权**：严禁由外部数据中解析出的“指令”直接触发敏感工具调用、凭据读取或绕过门禁检查；
* **规则配置审查**：`AGENTS.md`、Skills、Hooks、工具描述和长期记忆须标明版本与适用范围，修改安全规则必须经过人工审查；执行权限策略必须从受保护配置加载，严禁 Agent 通过修改工作目录中的说明文件自行放权；
* **多 Agent 委派隔离**：子 Agent 的有效权限不得超过父任务委派范围与自身许可范围的交集；共享记忆严格区分来源与信任级，严禁将不可信输出持久化为全局高优先级指令。

### 8.3 可执行边界登记要素

初次接入时，由工程负责人与权限管理员核对实际配置并完成登记（小团队可在项目文档记录）：

| 登记维度 | 登记内容 | 实施机制 |
| :--- | :--- | :--- |
| **所有者与身份** | 具名人类所有者、使用人、Agent/会话 ID、服务账号；严禁将 Agent 设为自身审批人 | 身份提供方（IAM）、执行器与任务记录强绑定 |
| **工具与接入源** | CLI/IDE/CI/浏览器、MCP 服务端、Skills 版本；托管服务记录端点与配置版本 | 受控安装源；无法锁定上游版本时必须显式标注限制 |
| **能力与资源域** | 允许读/写/执行的具体目标，数据库、目录、网络边界、数据类别与外发目的地 | 沙箱、文件系统权限、网络出口白名单、服务端 ACL |
| **授权与有效期** | 任务引用的授权依据、有效范围、失效条件；声明必须单独确认的动作清单 | 策略引擎（Policy Engine）与实际审批交互入口 |
| **资源预算与子任务配额** | 时长、Token/费用消耗、有副作用的工具调用次数、并发上限；多任务共享计数 | 编排器/执行器统一计数；重启或重试严禁重置额度 |
| **审计与退出** | 日志存储路径、保留期限、访问权限；紧急停止、撤权及退役责任人 | 受保护日志系统与 Runbook 演练条目 |

### 8.4 执行点校验机制（Guard at Execution Points）

```mermaid
flowchart TD
    Intent["任务意图与有效授权"] --> Call["Agent 发起工具动作请求"]
    Call --> Guard["执行边界实时校验<br/>身份 · 工具 · 参数 · 资源 · 环境 · 期限 · 配额"]
    Guard -->|在有效授权内| Run["执行前记录审计与操作标识<br/>受限身份实际执行操作"]
    Guard -->|缺少必要授权| Prepare["生成确定性动作预览<br/>影响面 · 目标对象 · 恢复预案"]
    Prepare --> Human["有权负责人判定"]
    Human -->|批准并绑定范围| Guard
    Human -->|拒绝审批| Deny["拦截并记录审计；允许继续其他任务"]
    Guard -->|越界或校验服务不可用| Deny
    Run --> Result["记录真实执行结果<br/>成功 · 失败 · 结果未知"]
    Result --> Check["核查真实副作用与预算消耗<br/>继续推进 · 终止任务 · 人工接管"]
```

1. **工具执行前校验**：校验受信任身份与实际解析参数，严禁仅凭提示词内的“已获批”放行；前缀字符串检查不能代替底层沙箱与 ACL 隔离；
2. **人工介入点控制**：高风险一次性审批必须将授权绑定至规范化参数、操作对象、有效时限与唯一操作标识（Operation ID），防范参数篡改与审批重放；
3. **执行器控制**：执行器重新校验授权与实际参数，原子检查并消费一次性审批，同时预留或扣减共享配额，防范审批重放和并发击穿预算；重试复用 Operation ID 查询既有结果，一次性审批不能代替业务幂等；
4. **控制机制不可用时的处理**：若授权服务中断或审计日志无法写入，高危动作强制挂起，严禁降级放行。

### 8.5 结构化操作审计留痕

操作事实由执行器或服务端如实记录，并以 Task ID 和 Operation ID 关联至验证记录：
> **最小审计事件字段**：  
> `{ 时间, Task ID, Run ID, Parent ID, Actor/Agent ID, 授权引用, 工具及版本, 目标资源, 参数摘要, 策略版本及决策, Operation ID, 执行状态, 结果证据 }`

* 执行前记录“拟执行/已放行”，执行后记录“实际回执”；若存在执行前记录但缺少回执，标记为**结果未知待核查**；
* 审计记录实施访问控制与防篡改保护，参数与返回值按规则脱敏，密钥只存引用。

### 8.6 紧急停止与事后状态处置（Kill Switch）

针对预算超限、持续异常、越界攻击及人工紧急中止，制定明确的响应预案：

1. **阻断准入**：立即关闭新任务准入，吊销相关临时令牌（Token），切断执行入口；
2. **排查在途**：枚举在途请求、后台进程与子 Agent，调用安全退出接口；严禁仅靠关闭聊天窗口判定停止；
3. **状态核查**：对结果未知的操作，使用受限核查身份依据原 Operation ID 读取真实落盘状态，严禁盲目重新写入；
4. **受控恢复**：有权负责人评估停止原因，补偿与回滚按恢复预案执行，严禁借“收尾”之名继续原业务操作。

撤权可能受令牌缓存、连接或远端作业影响，应实测生效与排空时间。已发出的请求仍可能完成，停止不会自动撤销既有副作用。临时例外记录范围、批准人、补偿措施、到期和处置责任，到期后撤销或重新评估；Agent 退役同时回收凭据、计划任务与入口，按保留规则处理日志和记忆。

### 8.7 治理能力落地验收矩阵

| 验证场景 | 必须观察到的客观事实 |
| :--- | :--- |
| **授权内正常操作** | 动作实际执行成功，身份、任务与系统副作用严格关联可查 |
| **越界目标 / 凭据过期 / 参数篡改 / 一次性审批并发重放** | 对应拒绝在执行点生效；同一一次性批准至多获准执行一次，底层无额外副作用；结构化日志记录具体原因 |
| **提示词诱导越权 / 敏感外发** | 权限未被放大；隔离接收端未收到标记数据；拦截依据不依赖模型自述 |
| **并发任务 / 重试耗尽配额** | 共享限额得到执行；超出预算的操作被挂起，在途状态完整落盘 |
| **写入已发送但回执丢失后停机** | 依据原 Operation ID 查回最终事实且不重复写入；停止后尝试原本获准的新标记动作，确认因停止被拒且目标无新增副作用；存在后台或子任务时核查其停止或排空 |
| **策略服务 / 审计服务宕机** | 敏感与高危操作自动阻断，未发生静默放行 |

---

## 九、效能与工程质量度量体系（Health Metrics）

度量指标用于识别交付瓶颈和质量问题，并指导流程与基础设施改进。**不得仅凭代码生成量、PR 数或规则数量评价团队与个人**；应结合交付价值、质量和成本解读。统计前统一对象、时间窗口与数据来源。

| 度量指标 | 建议口径与统计规范 |
| :--- | :--- |
| **需求效果达成情况** | 按目标用户、基线与观察窗口核对实际结果；区分已部署、已观察与已达目标，证据不足时不判定成功 |
| **需求与交付等待时间** | 分别记录登记到选入、开工到验收、验收到部署的历时，以及决策/审查/环境阻塞时长；不混作编码耗时 |
| **计划变更与预测偏差** | 记录插单、移出、依赖变更和估算偏差及原因，用于调整容量与规划，不用于个人排名 |
| **门禁首次通过率** | 同一统计窗口内，首次验证即通过全部适用门禁的候选版本数 ÷ 首次验证的候选版本总数；不统计 TDD 开发阶段的预期失败 |
| **审查返工耗时 (Review Rework)**| 统计从审查者首次提出已确认缺陷到修复并复核通过的总耗时，扣除外部环境阻塞造成的等待时间 |
| **测试稳定性与检查误报** | 分别记录相同输入下结果波动的用例（Flaky Tests）和经复核的误报；与基础设施故障、已确认代码缺陷分开统计 |
| **缺陷逃逸率（Defect Escape Rate）** | 本文口径：同一版本在观察窗口内首次于生产发现的已确认缺陷数 ÷ 该版本上线前后发现的已确认缺陷总数；按严重度分组，分母为零时不计算 |
| **单位交付成本** | 统一“已验收需求”或“发布版本”等计量单位，综合核算实现与返工、人工审查、模型和 CI 资源成本 |
| **运行期稳定性指标** | 监控生产服务错误率、MTTR（平均恢复时间）、重复副作用发生率与核心不变量破坏事件 |
| **治理记录覆盖率** | 对活跃 Agent 实例与工具集成分别统计：具备负责人、有效授权和审计关联的对象数 ÷ 同类对象总数 |
| **越界与停止处置表现** | 分类统计阻断尝试与真实越权事件；记录停止响应耗时、在途排空耗时与过期例外数量 |

---

## 十、研发流程检查清单（Checklist）

本章用于核对前文要求，不新增审批或验证条件。各项按任务风险与实际范围适用；不适用项注明理由，豁免项记录依据，未执行与受阻项如实保留。

### 10.0 需求与规划

- [ ] 需求有来源、问题证据、负责人和目标，未知项未被写成事实。
- [ ] 排序理由、期限依据和依赖明确；优先级、风险等级与准备状态分别记录。
- [ ] 迭代容量包括实现、审查、测试、返工与运行支持；范围变化有取舍记录。
- [ ] 版本用户、环境、必备范围和退出条件明确；预测与外部承诺已区分。

### 10.1 开工准备

- [ ] 风险等级及所需资料明确；有效规则、需求和决定可追溯。
- [ ] 适用的领域术语、数据责任、契约、不变量及失败语义已确定。
- [ ] 必要设计与决策已确认；未决项有负责人，并明确阻断范围。
- [ ] 验收准则已映射到切片、测试、环境、责任人和证据；规格完成适用审查。
- [ ] Agent 授权、工具与资源隔离明确；相应的拦截和停止机制已验证。

### 10.2 实施与验证

- [ ] 需要采用 TDD 的行为变更按 §3.1 先红后绿、验证核心判据并恢复；豁免有依据。
- [ ] 关键设计变化已更新，未擅自扩大范围或改变业务规则。
- [ ] 真实依赖、替身、模拟器和目标环境的证明范围分别记录。
- [ ] 重复失败已按规则转入诊断，验证期间未隐式修改受测输入。
- [ ] 权限与预算按有效范围执行，结果未知的操作未被盲目重复执行。

### 10.3 合并准入

- [ ] 适用的提交与合并检查有真实结果，证据对应实际候选内容和基线。
- [ ] Standards 与 Spec 两轴有明确结论，有效 `BLOCKER` 均已修复并复核关闭。
- [ ] L3 及另有规定的变更已取得人类领域责任人的独立签字。
- [ ] 涉及 UI 时，按第五章完成适用检查；预期异常与非预期错误已区分。
- [ ] 变更单明确本次完成范围、剩余工作和验证盲区，未宣称已经发布。

### 10.4 发布准入与运行交接

- [ ] 版本必备范围齐备，候选源码、构建记录、制品、配置和迁移可追溯。
- [ ] 相同候选组合已完成适用的隔离验收；恢复前提和演练结果可核查。
- [ ] 阻断项已解决，非阻断 OPEN 项有责任人及接受依据。
- [ ] 发布清单已固化；目标环境、授权、顺序、停止条件与恢复责任明确。
- [ ] 运维接手方确认监控告警、支持安排、操作手册和发布说明就绪。

### 10.5 发布后、效果评估与收尾

- [ ] 实际部署结果、运行核验、异常与恢复事实已形成回执；无部署任务记录交接。
- [ ] 效果观察负责人、基线、数据来源、观察窗口和下一步明确。
- [ ] 已部署、未观察、未达目标与不适用分别记录，新反馈已进入需求池。
- [ ] 必要复盘有改进项、负责人和验证方式，不能只以“加强注意”结案。
- [ ] 不再需要的工作目录、临时权限和资源已按归属清理；退役事项按 §7.4 完成。

---

## 附录 A：常用文档模板（贯穿式业务示例）

> **示例业务背景**：虚构的**“异步报表导出”**功能（涵盖任务受理、后台 Worker 生成、下载与状态恢复）。可落地于单仓多模块架构，亦可拆分为 API、Worker、Web 多个独立服务仓。所有编号、阈值与状态均为演示设定，重点展示信息架构与契约职责。

### A.1 README / 文档索引示例

```markdown
# 报表中心服务 (Report Service)
用途：用户导出本人有权查看的报表，生成文件后再下载。

阅读入口：
- 开发：AGENTS.md → 工程规范 → 本次 SPEC
- 理解业务：领域模型 → 决策索引
- 验证：测试策略 → 本次测试计划与 EVIDENCE
- 发布和故障：发布记录 → Runbook

当前边界：本示例只设计 CSV 导出；Excel、定时发送暂不包含。
启动和验证命令：链接到仓库真实脚本及配置，不在这里复制第二套。
维护人：项目负责人；入口或能力范围变化时更新。
```

### A.2 AGENTS / 工程规范示例

```markdown
# 开发约束
适用：本项目全部模块；子目录额外规则由明确指针说明。

工程约定：
- API 负责认证和请求接入，Worker 负责生成文件。
- 导出任务状态只有任务服务可以修改；页面只展示服务端事实。
- 异步任务明确适用的超时、停止、排空与资源释放路径。
- 本例暂不提供用户取消功能；如需支持，须补充取消状态、竞态及资源清理契约。
- 日志记录关联 ID 与错误分类，不记录令牌或报表内容。

门禁登记：
| 规则与适用范围 | 执行命令与执行者 | 阻断位置 | 结果证据 | 已知盲区 |
| :--- | :--- | :--- | :--- | :--- |
| 类型与格式：受影响模块 | <命令/执行者> | <提交/CI入口> | <日志与报告> | 不能判断权限语义 |
| 模块依赖：项目定义的依赖范围 | <检查器/执行者> | <实际阻断机制> | <报告与版本> | 不能发现复制实现的业务规则 |

人工复核项：
- 当前权限是否在下载时重新检查；
- 测试是否真正观察了重复提交产生的副作用。

*尚未接入执行流程的工具明确标为计划中，不能填写为已强制。*
```

### A.3 需求说明（Intent / PRD）示例

本模板承接 A.19 的需求线索，表达待确认的交付范围；来源和问题证据保留在需求记录中，不重复维护两份事实。

```markdown
# 异步报表导出需求说明
状态：草案；负责人：<填写>；关联需求：REQ-EXAMPLE-001（见 A.19）。
问题证据：沿用 A.19；当前假设尚待核实，不代表已完成用户调研。
目标用户：有报表查看权限的登录用户。
交付目标：用户能确认原请求、查看进度，并取得有权访问的 CSV 文件。
范围：提交、原请求查询、生成、下载、失败及到期提示。
非目标：Excel、邮件发送、定时导出、批量共享与用户取消。

验收准则：采用快速上手 AC-01～AC-06，经需求负责人确认后生效。
效果评估：基线、指标口径和观察窗口在 A.19 确认，在 A.22 回写实际结果。
待决策：去重期限、文件保留期限、最大导出规模和数据读取口径。
依赖决定：D-EXAMPLE-001；接口与状态细节见 A.7。
```

### A.4 术语 / 领域模型 / 架构示例

```markdown
# 导出领域与责任边界
ExportRequest：用户提交的规范化筛选条件与请求标识。
ExportJob：服务端受理后持久化的任务。
ExportArtifact：生成并发布的文件。
UNKNOWN：客户端尚未确认提交结果；不是服务端任务失败状态。

状态（候选设计，决策被接受后才可用于实现）：
QUEUED → RUNNING → READY → EXPIRED
RUNNING → FAILED
RUNNING → QUEUED：仅由租约过期后的恢复机制触发，并增加执行代际。

权威：
- 身份模块提供经过认证的 tenant_id 和 actor_id。
- 任务模块维护任务状态、请求摘要和当前执行代际。
- 存储适配器保存文件；页面不能自行推导 READY。

不变量：
- 去重保留期内，同一作用域的同键同请求对应同一任务。
- 旧执行代际不能覆盖新代际发布的结果。
- 文件生成成功并不意味着所有用户都具备下载权限（仍须按租户与权限校验）。
```

### A.5 技术方案 / RFC 示例

```markdown
# RFC：导出执行方式
状态：候选方案，待决策。
约束：单任务可能超过 HTTP 超时；已有关系数据库；需跨重启恢复。

备选：
A. 同步 HTTP 生成：简单，但长请求与断线恢复成本高。
B. 数据库任务表 + Worker：复用已有存储，需实现租约、重试和代际保护。
C. 外部工作流平台：能力完整，但增加运维与依赖成本。

建议 B：当前规模先复用数据库任务表。
实现前验证：并发认领任务、租约失效，以及拒绝旧 Worker 发布结果的机制。
风险：热点轮询、长任务租约、孤儿文件。
退出条件：达到已约定容量阈值或工作流复杂度后，重新评估 C。

发布影响、恢复方法和验证方式链接到迁移方案与测试计划。
```

### A.6 D-ID / ADR 决策记录示例

```markdown
# D-EXAMPLE-001：导出提交去重
状态：Proposed；负责人：产品与服务负责人。
关联：上述 RFC、导出 SPEC。
替代：无；若未来改变保留期限，新建决定并链接本条。

候选决定：
- 作用域 = tenant_id + actor_id；幂等唯一键 = 作用域 + request_id。
- 同键同摘要返回原任务；同键异摘要返回冲突。
- 示例去重期限为受理后 24 小时；文件 READY 后保留 1 小时。
- 文件过期不清除仍在去重期内的请求映射。
- 去重期限外不保证仍能查回；客户端不得自动换键重发。

后果：多保存请求映射；减少断线后重复导出的不确定性。
待确认：容量估算、最大导出规模、数据读取时点或一致性口径，以及用户恢复体验。
交付状态：未实现；未验证；未部署。
```

### A.7 SPEC / 接口契约示例

```markdown
# SPEC：导出提交与结果恢复
前置：D-EXAMPLE-001 已被有权负责人接受。
本示例状态：待实现；上述前置条件尚未满足，也尚未交付。

POST /exports
- tenant_id、actor_id 来自服务端认证上下文，不信任客户端自报值。
- 请求含 request_id、筛选条件和 format=CSV。
- 校验权限与参数后，原子建立请求映射和任务。
- 新请求返回任务 ID；同键同摘要返回原任务 ID。
- 同键异摘要返回 409，不创建任务。

GET /export-requests/{request_id}
- 只查当前认证作用域内的原请求，不产生写入。
- 在认证作用域仍获授权且请求映射处于保留期内时查回原任务。
- 文件到期不提前清除仍在去重期内的映射；保留期外不保证仍可查回。
- 未找到、拒绝或暂不可用不自动触发新提交，也不自行换键。

GET /exports/{id}
GET /exports/{id}/download
- 分别检查任务访问权限与当前数据权限。
- READY 才能下载；到期返回明确的过期状态。
- 生成与下载须覆盖 AC-05/06；筛选、格式、数据读取口径及到期计算以已接受决定为准。
- 任务查询与下载均不能绕过已撤销的权限。

结果未知：
保留原 request_id 与原参数，通过只读查询确认实际状态；
长期未查回时给出用户可理解的处理入口，不伪造失败。
```

### A.8 UI / 交互与无障碍示例

```markdown
# 导出交互
入口：报表页“导出 CSV”。
状态：可提交、提交中、结果未知、排队、生成中、可下载、失败、已过期。

结果未知：
- 显示“正在确认本次导出是否已受理”；
- 保留原 request_id，暂时阻止重复提交同一意向；
- 查询恢复沿用原请求，不因刷新页面而创建新意向。

失败：显示服务端分类后的原因与适用恢复动作。
过期：显示文件已过期，新建导出需用户明确发起。
可访问性：状态变化有读屏提示，焦点不因轮询跳动；
键盘能完成提交、查询和下载。

视觉验收：桌面与项目支持的窄屏；长报表名、无数据、权限撤销。
后端真实性：布局阶段可以用夹具；真实受理与下载权限另行验证。
```

### A.9 安全与威胁模型示例

```markdown
# 导出安全设计
资产：报表内容、任务元数据、身份令牌。
信任边界：浏览器 → API → Worker → 文件存储。

威胁与控制：
- 猜测他人任务 ID：每次读取与下载都验证当前主体权限。
- 客户端篡改 tenant_id：服务端只使用认证上下文。
- 权限撤销后仍下载：下载入口再次授权，文件存储不直接公开。
- 重复提交消耗资源：作用域去重、频率和容量上限。
- 文件生成后任务发布失败：孤儿文件按所属任务和代际清理。

验收：验证跨用户、跨租户、撤权、过期与并发提交的预期响应；
无权限访问应被拒绝，同键同参并发提交应返回原任务。
日志：保留关联 ID、分类和耗时，不保存令牌、筛选敏感值或文件正文。
```

### A.10 实施计划与切片示例

```markdown
# 异步导出实施计划
状态：候选计划；关键决定尚未接受，不得据此宣称已开工或完成。
前置：确认 A.6 的决定，完成 A.7 契约与测试计划审查。

S1：受理与查询
- 任务与请求映射、唯一约束、认证作用域、提交及查询 API。
- 验证 AC-01/02 和 AC-04 的任务查询部分。

S2：执行与结果（依赖 S1）
- Worker 认领、租约、执行代际、文件生成与结果发布。
- 验证 AC-05/06：结果正确、失败/到期、重启恢复和旧代际隔离。

S3：用户端闭环（依赖 S1/S2）
- 页面提交、响应丢失恢复、真实状态展示及安全下载。
- 验证 AC-03、AC-04 的下载与界面部分及 AC-05/06 的用户可见结果。

版本验收与发布准备：
- 对完整候选组合执行端到端、权限、容量、迁移及恢复验收。
- 核对运行监控、告警、操作手册与发布准入条件。

每个切片记录负责人、验收入口、证据及剩余问题。
模块可在同一仓库；跨仓时补充契约版本和集成节点。
```

### A.11 测试策略与用例设计示例

| 验收项 | 测试设计 | 依赖与执行安排 | 本示例状态 |
| :--- | :--- | :--- | :--- |
| **相同请求规范化摘要一致** | 单元／性质：字段顺序变化不改变语义摘要 | 纯计算，编辑中与提交检查 | NOT_RUN |
| **并发重复只建一个任务** | 集成：并发 20 次同键请求，独立查询任务数为 1 | 真实数据库，相关改动及完整验证 | NOT_RUN |
| **同键异参数拒绝** | 契约：返回冲突，原任务不被覆盖 | 真实存储，提交／集成入口 | NOT_RUN |
| **提交后响应丢失** | 故障 E2E：截断受理回复，页面重载并查回原任务 | 真实 API、Worker、DB、浏览器 | NOT_RUN |
| **旧 Worker 不能发布** | 故障：旧租约过期后新代际认领，旧代际 CAS 被拒 | 真实存储或独立声明的模拟 | NOT_RUN |
| **无权读取或下载** | 安全契约：跨用户、跨租户及权限撤销后拒绝 | 真实授权路径 | NOT_RUN |
| **生成正确文件** | 内容验收：筛选、格式、数据口径与独立预期一致 | 受控数据集、真实 Worker 与文件存储 | NOT_RUN |
| **失败与到期** | 状态契约：失败分类正确，到期后不能下载 | 注入可控失败，使用可控时钟或等价机制 | NOT_RUN |
| **重启恢复** | 故障集成：处理期间重启，恢复后状态正确且仅有一个可见最终结果 | 真实存储与执行代际校验 | NOT_RUN |
| **产物可启动** | 冒烟：运行真实发布产物的启动／版本入口 | 发布制品，不挂载源码补依赖 | NOT_RUN |
| **队列处理达标** | 性能：按已接受的任务大小、并发和资源预算测量 | 固定环境，预算确认后填写 | NOT_RUN |

```text
Given：同一认证主体提交 request_id=REQ-DEMO-01，参数摘要 H1。
When：任务已提交，第一次响应丢失；客户端在原作用域仍获授权且请求映射保留期内重载并查询原请求。
Then：查回同一任务 ID，展示服务端返回的合法实际状态，任务总数仍为 1；客户端没有发起新的提交。
说明：任务可能已完成，不固定断言为 QUEUED/RUNNING；
若专门验证在途状态，夹具须明确控制 Worker 的执行时序。
本用例负控：临时让重载丢失原 request_id，或让恢复路径重新提交；
            原请求查回或新增提交次数的断言应失败。
并发重复用例负控：临时破坏去重保护，执行多次同键写入；
                  任务计数应捕获重复，未捕获须检查变异与判据。
每次负控后精确恢复，再重新验证。
```

### A.12 数据库变更与迁移方案示例

```markdown
# 导出任务存储变更
状态：设计，未执行。
新增：任务表、请求映射、租约与执行代际；具体类型按数据库契约确定。
唯一约束：(tenant_id, actor_id, request_id)，字段非空。

向前顺序：先执行兼容的新增迁移 → 部署可识别新表的服务 → 开启入口。
权限：API 与 Worker 使用各自最小运行权限；迁移使用单独身份。
核验：唯一约束、运行 ACL、已有业务不受影响、重复迁移符合工具语义。

恢复：
- 新表已有任务时不直接 DROP；
- 先停止受理，处理／记录在途任务，确认旧代码兼容性；
- 是否允许 down 由数据前提与演练决定；不能保证时采用向前修复。
```

### A.13 Standards / Spec 双轴审查报告示例

```markdown
# Review：异步导出候选
基线：<旧稿/旧提交摘要>；候选：<新稿/新提交摘要>。
依据：需求、已接受决定、工程规范、SPEC。
以下为示例发现，不是本项目实测结果。

Standards：
- BLOCKER S-01：接口从请求 body 取 actor_id；
  违反身份来源规范，恶意客户端可修改任务作用域。
- 处置：待修；修后检查所有读取与下载入口的认证来源。

Spec：
- BLOCKER R-01：页面重载丢失原 request_id；
  无法满足“响应丢失后查询原任务”的验收准则。
- 处置：待修；补持久化与重载用例，独立复核不产生新提交。

文档核查：
- 决定状态仍为 Proposed 时，不得宣称已裁定；
- 测试计划中真实/模拟依赖与实际入口一致；
- 未覆盖的性能、部署与告警验证保留 OPEN。
```

### A.14 验证记录 (EVIDENCE) 归档示例

```markdown
# 导出验收证据
状态：NOT_RUN（模板，尚未执行）。
受测版本：<完整 SHA / 内容摘要>。
配置与依赖：<数据库/浏览器/运行身份类别/配置摘要>。
命令：<实际执行入口>；退出码：N/A。
结果：未执行；不能填写预期的通过数量。

执行后补充：
- 先红：原始输出、对应目标与失败位置；
- 转绿：实际统计与日志；
- 变异测试：变异内容、实际失败与精确恢复摘要；
- 相同内容的最终检查：实际结果与输入一致性；
- 浏览器/真实依赖边界、skip、异常与 OPEN。

证据地址：<实际可访问的日志/截图/Trace 路径>。
```

### A.15 发布清单与部署回执模板

发布清单记录获准部署的组合，部署回执记录实际结果。两者可以保存在同一文件的不同记录区，通过 ID 关联；追加回执时不改写已固化的清单。

```markdown
# 发布清单：REL-EXAMPLE-01
状态：候选，尚未验收或发布；所有结果初始为 NOT_RUN。
清单版本与摘要：<准入后填写>；生成时间：<带时区>。
目标用户、环境与范围：<填写>；版本负责人：<填写>。
适用审批：<负责人、批准依据与时间；不适用时说明>。

源码与构建：
- 仓库/模块：<名称>；源码：<完整 Commit SHA>。
- 构建记录：<工具链、依赖锁定、参数、环境与日志引用>。
- 制品：<镜像 Digest 或文件及完整校验和>；按实际数量逐项记录。

契约、配置与数据：
- 接口/消费者兼容范围、运行时与外部依赖：<填写>。
- 配置版本或摘要、开关状态：<填写>；密钥仅记录受控引用。
- 迁移基线、文件校验和、执行身份与顺序：<填写>。

准入与执行：
- 隔离验收证据、受测组合与结论：<真实记录>。
- 必备范围与阻断项：<逐项核对>。
- 非阻断 OPEN：<影响、接受人、后续负责人及期限>。
- 发布步骤与批次、健康/业务探针、停止阈值：<填写>。
- 恢复策略、前提、演练证据和责任人：<填写>。
- 运维接手人、告警与支持安排、发布说明：<填写>。

# 部署回执：<独立 ID，实际执行后填写>
引用清单：<已固化清单 ID、版本与摘要>。
执行人、目标环境、开始及结束时间：<实际记录>。
实际制品、配置和迁移结果：<实际记录>。
结果：<成功/失败/部分完成/结果未知；不提前填成功>。
探针与业务核验：<实际结果及证据>。
异常、停止或恢复：<动作、数据核验、当前状态和责任人>。
运行交接：<接收确认与剩余问题>。
效果观察：<引用 A.22 的负责人、窗口及后续结论>。
```

### A.16 运维手册与故障处置 (Runbook) 示例

```markdown
# 导出积压处理
触发：队列最老任务等待时间超过项目已接受阈值。
观察：队列长度、最老任务、执行时长、失败分类、租约与 Worker 存活。
告警：接收渠道、当班责任人、确认与升级时限均需配置并验证。

处理：
1. 核对正在运行的制品、配置和数据库状态。
2. 区分任务过大、存储失败、Worker 异常和租约问题。
3. 需要停受理时使用既定开关，保留任务与请求映射。
4. 恢复前确认执行代际，避免旧 Worker 覆盖新结果。
5. 验证处理进度、唯一结果、权限与告警恢复。

禁止将批量删除任务作为默认“清积压”动作。
演练状态：NOT_RUN；阈值和操作命令在项目采纳时补齐。
```

### A.17 复盘与知识更新示例

```markdown
# 示例复盘：重复导出
状态：假设场景，用于展示复盘结构。
现象：响应丢失后客户端创建新 request_id，生成了两个任务。
需收集：客户端请求、服务端受理记录、任务状态、关联时间线。
根因判定：只有证据能关联上述链路后，才确认新键重发是原因。

改进：
- SPEC 明确未知结果恢复流程；
- 页面保存原请求身份；
- 增加响应丢失 + 重载 + 独立任务计数测试；
- 审查模板增加“未知不等于失败”的检查点；
- 若保留期决定变化，新增 ADR 并关联旧决定。

验证与负责人：逐项登记；不要以“提醒大家注意”关闭复盘。
```

### A.18 Agent 执行授权、审计与停止演练示例

> 本例约束的是**负责实现报表导出功能的编码 Agent**，不要求报表业务本身具备 Agent 能力。以下为待项目采纳的任务边界记录模板：

```markdown
# T-001：编码 Agent 执行边界与授权记录
状态：Proposed；控制验证：NOT_RUN；实际授权：尚未授予。
人类所有者：<填写实际任务所有者与应急联系人>
授权依据：任务卡 T-001 发起记录及现行项目授权范围
运行关联：task=T-001；run=<执行器生成的 UUID>；agent=coder-export
执行身份：专用本地测试身份 (test-runner)；严禁继承个人生产凭据或全量浏览器 Session

允许动作范围（须由维护者填入真实资源标识）：
- 读写当前任务专属的隔离 Worktree 工作目录；只读本项目现行规范文件；
- 运行该工作目录下的原生构建与测试脚本；
- 连接并重建归本任务专有的 export_test_T001 测试数据库；
  (执行前核对主机地址、DB 名称与所有权 Tag，严禁仅按模糊前缀匹配)；
- 浏览器仅登录合成测试账号，访问已登记的本地端点（localhost）；
- 模型上下文数据遵循项目数据发送策略：凭据、真实客户数据与未核准文档严禁发送。

明确越权动作（严禁执行）：
- 生产环境访问、共享集成库重建、对外发送通知消息、镜像发布部署、
  新增未登记网络出口、放宽当前门禁或修改审计日志文件。

资源与调用预算：
- 本轮最长执行 60 分钟；最多分派 2 个并行子任务；
- 父子任务合计上限 100 次有副作用的工具调用（含失败重试）；
- 预算由执行器以原子操作扣减共享配额，到期自动暂停，重启无法续期。

停止与应急责任：
- 停止责任人：<填写实际可执行停止操作的负责人>
- 停止入口：<实际已验证的停止命令或管理控制台入口>
- 事实核查身份：只读查询任务表与执行器审计日志，严禁执行修复写入
- 日志保留位置：<任务执行身份无法删改的受保护存储>；审计保留期限：<按项目数据规则填写>
- 临时例外：无 (新增例外须记录范围、批准人与到期时间)
```

将上述文本约束落地为实际控制机制（由维护者配置）：

| 管控目标 | 实际控制配置 | 验收与测试动作 |
| :--- | :--- | :--- |
| **工作区与库隔离** | 沙箱仅挂载任务工作目录；数据库连接串仅授权测试库 | 写入测试标记成功；尝试写入隔离区外文件被 OS 权限拒绝 |
| **数据目的地限制** | 锁定获准的模型服务端点；受控工具网络出口白名单 | 向未获准的测试接收端发送标记数据，网络出口强制丢包拦截 |
| **并发与调用预算** | 执行器按 task/run 绑定配额，工具调用前原子扣减 | 临时设预算为 2 次，发起 3 个原本合法的并发动作；确认恰有 2 次执行，其余被拒；不依赖并发完成顺序 |
| **操作可审计留痕** | 执行前后分别记录，目标动作绑定唯一 Operation ID | 比对任务库状态与执行日志，确认调用次数与操作身份严格吻合 |
| **停止与未知状态** | 关闭新增准入、吊销临时授权，仅保留受限事实核查通道 | 在写入提交但回执丢失时停止并查回状态；再尝试原本获准的新标记动作，确认因停止被拒且无新增副作用；适用的后台或子任务已退出或排空 |

```text
结构化审计事件格式示例：
事件 1 (放行执行): 
  task=T-001 run=R-DEMO operation=OP-DEMO actor=coder-export
  tool=test_db.write_marker target=<已核验测试库 ID>
  authorization=<有效授权引用> policy=v1.2 decision=ALLOW
  state=DISPATCHED params=<脱敏参数摘要>
事件 2 (回执丢失): 
  task=T-001 run=R-DEMO operation=OP-DEMO state=UNKNOWN reason=REPLY_TIMEOUT
事件 3 (状态对齐): 
  operation=OP-DEMO actor=auditor-readonly state=RECONCILED
  result=<目标库真实记录引用> side_effects_count=1
```

---

### A.19 需求收集与澄清示例

```markdown
# REQ-EXAMPLE-001：大报表导出后，用户能确认请求与结果
状态：待澄清；需求负责人：<项目采纳时填写>。
说明：本条为虚构示例，不代表已访谈用户或已批准排期。

来源：<访谈、客服工单或运行证据的受控链接与日期>。
问题假设：同步导出容易超时；响应丢失后，用户无法确认是否已受理。
受影响对象：有报表查看权限、需要导出大报表的用户。
现有替代操作：<待调查，不假定用户一定会重复提交>。
业务目标：让用户能确认原请求并取得有权访问的导出结果。
效果指标：导出结果确认成功率、重复提交相关求助量；统计口径待确认。
当前基线：待采集；目标值与观察窗口：待确认，不填模拟数据。
范围：CSV 提交、原请求查询、进度和安全下载。
非目标：Excel、定时导出、邮件发送和批量共享。

验收草案：引用快速上手 AC-01～AC-06，需求简报见 A.3。
风险：涉及权限与持久化，按 L3 准备审查和验证。
未决：D-EXAMPLE-001 的去重期限、保留期限、最大规模与数据读取口径。
下一步：核查问题证据，确认目标和未决规则，再进入候选队列。
关联：任务卡 T-001；排序见 A.20；版本计划见 A.22。
```

### A.20 优先级与取舍记录示例

```markdown
# 导出能力候选排序
状态：讨论稿；负责人：<填写>；复查时间或触发条件：<填写>。
本示例只展示取舍方式，不代表真实评分或批准结果。

候选项：
- REQ-EXAMPLE-001：异步 CSV 导出与原请求恢复。
- REQ-EXAMPLE-002：Excel 格式导出。
- REQ-EXAMPLE-003：导出邮件通知。

前置约束：
- 001 中的权限检查、幂等和恢复共同构成安全可交付范围；
- 待决策的期限与规模先澄清，不能由执行 Agent 自行补值；
- 002/003 是其他能力，不得用高评分挤掉 001 的必要安全验证。

暂定顺序：先验证并细化 001；002/003 暂缓，补充需求证据后重评。
理由：先形成一个可用的导出闭环，避免同时扩展格式与通知渠道。
RICE：暂不评分；覆盖人数、影响和总投入尚无可比证据。
最终决定：待需求负责人确认；如沿用既有授权决定，填写引用。
影响：未承诺发布日期；未授权发送邮件或启用新外部服务。
```

### A.21 迭代计划与变更记录示例

```markdown
# ITER-EXAMPLE-01：导出受理与原请求查询
状态：候选计划；不是已开始的迭代。
周期：<起止日期/批次边界与时区>；负责人：<填写>。
本轮目标：对重复提交和原请求查询给出一致、可核验的服务端结果。
关联需求：REQ-EXAMPLE-001；目标版本：REL-EXAMPLE-01。

准入前提：需求与关键规则已确认；适用规格审查通过；测试资源可用。
本轮范围：T-001 / S1；验收映射与未交付边界沿用快速上手切片表。
不在本轮：Worker 生成、完整页面及生产发布。

容量记录：
- 人员可用时间、值班/请假：<填写>；
- 领域审查与复核窗口：<填写>；
- 实现、测试、真实依赖集成、返工预算：<填写，避免重复扣减>；
- 独立数据库、CI、并发工作目录与工具预算：<填写>；
- 估算区间、依据与待验证假设：<填写>。

顺序：关键决策 → 契约确认 → S1 的 TDD 与验证 → 独立审查 → 合入。
在制上限：开发 <数量>、审查 <数量>、验证 <数量>；由实际容量确定。
重排记录：变更原因、决定人、加入项、移出项、目标和版本影响。
结束记录：已验证结果、未完成项及原因、重新排序、下一轮改进。
边界：即使 S1 通过，也不将 REL-EXAMPLE-01 标为可发布。
```

### A.22 版本计划与效果评估记录示例

```markdown
# REL-EXAMPLE-01：用户可恢复的异步 CSV 导出
状态：候选版本；未承诺时间、未发布。
需求来源：REQ-EXAMPLE-001；版本负责人：<填写>。
路线图位置：<Now/Next/Later 或约定窗口>；依据：<填写>。
目标用户与环境：<内部演练/受控试用/生产，按实际批准范围填写>。
目标窗口、预测依据与信心：待填写；对外承诺需另记主体与依据。

必备范围：
- S1 受理与查询、S2 执行与结果、S3 用户端闭环；
- 同键处理、权限、到期、未知结果与重启恢复；
- 目标环境的容量、运行观测、发布和恢复验收。
可调整范围：不影响安全与基本可用性的展示优化，逐项确认。
非目标：Excel、邮件发送、定时导出与批量共享。

依赖：D-EXAMPLE-001；真实存储、身份与权限、文件存储配置。
仓库与制品：<按实际组合填写，单仓无需虚构多仓依赖>。
迭代安排：ITER-EXAMPLE-01 完成 S1；后续切片按容量滚动规划。
发布退出条件：引用 AC、测试计划、运行手册及各项实际证据。
停止与恢复：<条件、前置、动作与责任人>。
发布记录：先按 A.15 登记候选组合，验收并准入后固化清单；实际部署回执另行追加。

效果评估记录：
- 观察负责人、数据来源、统计窗口：<填写>；
- 发布前基线、目标、实际结果：<有实测依据后填写>；
- 当前结论：尚未观察，不能判定达标；
- 后续动作：继续观察/改善/退出，记录理由与关联需求。
```

---

## 附录 B：公开方法来源与适用边界

以下资料提供方法依据。本文的角色划分、双轴审查、门禁节拍与模板属于综合设计，不应视为各来源的原文规定。2026-10-14 核对了下列可访问页面的标题与相关引用段落；IMDA 的访问限制见下。在线文档可能持续更新，采纳具体规范时应登记所用版本。

### B.1 工程与治理方法

| 主题 | 公开来源 | 本文采用的范围与边界 |
| :--- | :--- | :--- |
| 架构决策记录 | Michael Nygard：[Documenting Architecture Decisions](https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions)；AWS：[Architectural decision record process](https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/adr-process.html) | 记录背景、决定、状态与后果；目录、编号和审批方式由团队选择 |
| 代码审查 | Google：[How to do a code review](https://google.github.io/eng-practices/review/reviewer/)；[What to look for](https://google.github.io/eng-practices/review/reviewer/looking-for.html) | 对设计、功能、复杂度和测试等方面开展审查；Standards / Spec 双轴是本文归纳，并非 Google 命名的标准 |
| 测试规模与范围 | Adam Bender：[Software Engineering at Google，第 11 章](https://abseil.io/resources/swe-book/html/ch11.html) | 区分测试规模与验证范围；本文的执行节拍、依赖类型和验收映射为进一步设计 |
| 请求标识与幂等 | Google：[AIP-155: Request identification](https://google.aip.dev/155) | 支持请求 ID 和幂等重试；作用域、参数冲突、保留期与恢复流程须由具体契约确定 |
| 威胁建模 | OWASP：[Threat Modeling Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Threat_Modeling_Cheat_Sheet.html) | 识别资产、边界、威胁与缓解措施，不据此推导统一审批人数或研发阶段 |
| 视觉回归 | Playwright：[Visual comparisons](https://playwright.dev/docs/test-snapshots) | 使用可控环境与渲染基线进行截图比对；截图不能替代业务或无障碍验收 |
| AI 辅助编码安全 | OWASP：[Secure Coding with AI Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Secure_Coding_with_AI_Cheat_Sheet.html) | 关注上下文注入、工具权限、运行隔离及代码验证 |
| Agent 安全 | OWASP：[AI Agent Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/AI_Agent_Security_Cheat_Sheet.html) | 关注参数绑定授权、执行侧校验、防重放与日志；具体字段和状态机仍由实现定义 |
| MCP 安全 | MCP：[Security Best Practices，2025-11-25 文档路径](https://modelcontextprotocol.io/docs/2025-11-25/tutorials/security/security_best_practices) | 参考令牌受众、代理授权及禁止令牌透传等要求；不将该路径称为最新版本 |
| AI 治理 | IMDA：[Agentic AI 治理框架发布公告](https://www.imda.gov.sg/resources/press-releases-factsheets-and-speeches/press-releases/2026/new-model-ai-governance-framework-for-agentic-ai)；NIST：[AI RMF Core](https://airc.nist.gov/airmf-resources/airmf/5-sec-core/)；ISO：[ISO/IEC 42001:2023](https://www.iso.org/standard/42001)；[官方解释](https://www.iso.org/insights/iso-42001-explained) | 用于理解治理责任与风险管理；不据此宣称本文、团队或 Agent 已获认证 |

IMDA 补充入口：[官方 AI 索引](https://www.imda.gov.sg/AI)；[框架更新说明入口](https://www.imda.gov.sg/resources/press-releases-factsheets-and-speeches/factsheets/2026/updated-model-ai-governance-framework-for-agentic-ai)。

核验限制：上述三个 IMDA 入口的直接访问均遇到机器人验证，本次未核实其正文或框架后续版本号，因此不列未经确认的更新日期或版本结论。ISO 仅核验公开说明与产品介绍页，未审读付费标准全文，不据此宣称满足认证要求。

### B.2 需求与规划方法

| 来源 | 本文采用的范围 | 不据此推导的结论 |
| :--- | :--- | :--- |
| [Atlassian：Product discovery](https://www.atlassian.com/agile/product-management/discovery) | 需求发现持续联系用户反馈、问题证据与交付 | 不要求采用 Jira，不把所有反馈视为承诺 |
| [Intercom：RICE](https://www.intercom.com/blog/rice-simple-prioritization-for-product-managers) | 使用覆盖范围、影响、置信度与投入进行比较，保留依赖和必备项的例外 | 不以模型自评代替证据，不以分数覆盖安全要求或业务决定 |
| [Scrum Guide 2020](https://scrumguides.org/scrum-guide.html) | 历史表现、可用容量与完成标准共同支持迭代预测 | 不声称本文完整实施 Scrum，不强设双周迭代或故事点 |
| [Atlassian：Agile roadmaps](https://www.atlassian.com/agile/product-management/roadmaps) | 采用目标导向的滚动路线图与时间窗口 | 不将远期方向自动变成发布日期承诺 |
| [DORA：Work in process limits](https://dora.dev/capabilities/wip-limits/) | 识别全流程工作和瓶颈，按容量限制在制工作 | 不按 Agent 数量直接换算团队交付能力 |

这些方法的适用说明已整合在第〇章，执行模板集中在附录 A，无需另读项目文档或补充调研稿才能理解本指南。