按需查阅，逐章深入。
10 章规范 / 4 张流程图 / 18 份 Demo适用范围与使用说明
适用范围：采用自主编码 Agent（CLI / ADE / 多 Agent 协同）进行特性研发、架构演进和缺陷修复的工程团队。
核心原则：人类负责人明确意图与红线，Agent 负责探索与实施；以可核验的客观证据验收；按最高风险确定设计、审查和验证深度。
版本基准：2026-10-14 精修校订版（保留完整章节、测试矩阵与文档示例）。
项目形态：适用于单仓、Monorepo 及跨服务多仓项目；按模块、服务与实际交付边界选择落地流程，不预设仓库物理形态。
效力边界：本文是一份供工程团队采纳的实践指南。仓库既有的硬性约束、有效业务裁决与已授权范围仍按各自权威入口执行；本文不自动新增 CI 门禁，亦不替代既有决策；文内模板用于说明应记录的信息，不代表已取得验证证据。
【快速上手】从一个真实任务开始（Quickstart）
初次使用时，请按本节的六个步骤跑通一个最小切片闭环；后文十章提供详细规范，可在各步骤遇到具体问题时查阅。
附录 A 以同一个业务示例贯穿各环节，提供相应的文档模板，不要求一次性创建所有文件。
诊断：你的项目当前处于什么状态？
| 你的项目当前处于什么状态 | 首要动作 | 推进准则 / 阶段完成标准 |
|---|---|---|
| 已有代码库，且启动与测试命令可用 | 选取一个边界清晰的真实任务，建立一张任务卡 | 任务具备可判定的验收标准，现有验证命令可在本地实际跑通 |
| 已有代码库，但测试或构建不可用 | 先修复与本任务直接相关的环境和验证入口，登记已有失败项 | 能够严格区分历史遗留失败与本次改动引入的新失败；核心门禁按项目既有规则处理 |
| 全新项目，或尚无规范工程入口 | 先按 §2.8 建立最小可运行底座 | Agent 明确应当读取哪些文档、如何启动服务、如何运行测试，以及关键技术与业务由谁裁决 |
第一步：建立一张结构化任务卡
沿用团队现有的任务跟踪系统（如 Jira / GitHub Issue）；若团队尚无统一约定，可直接创建并使用本地任务卡文件（如 docs/tasks/T-001.md）。执行 Agent 应先填写以下内容，确保信息具体、可核验：
# T-001：<一个可交付的用户结果>
阶段：勘察；风险等级：<L1/L2/L3 及判定理由>；负责人：<责任人或对应角色>
业务目标：<用户面临什么痛点，本次改动交付何种具体价值>
实现范围与非目标：<明确本次要完成的内容及不包含的内容（Non-goals）>
依据来源：<现行规范、业务需求与有效决策；若缺失则明确标注待补齐>
验收条件：AC-01 <特定输入或触发动作 ➔ 明确可观察的预期结果>
执行入口：<从本项目实际查明并成功试跑的启动与检查命令>
执行边界：<授权来源、运行身份、允许的工具/资源/环境、禁止动作、有效期、预算与停止入口>
待决事项：<未决问题、备选方案与指定决策人；无则填“无”>第二步：将“想要什么”转化为可验证的验收条件
由人类负责人或产品负责人界定业务意图与安全红线，Agent 协助整理为明确无歧义的验收条件（Acceptance Criteria, AC）。不得使用“处理好并发”“界面好看”“做好容错”等无法直接验证的模糊描述。
AC 编写范例（以本指南贯穿的“异步报表导出”为例）：
- AC-01：在去重保留期内，同一认证主体在同一请求作用域内，以相同请求标识（Request ID）和相同参数重复提交时，服务端返回同一任务标识，任务表仅保有一条对应记录；不同请求标识不因参数相同自动合并；
- AC-02：在去重保留期内，同一作用域下使用相同请求标识但携带不同参数时，服务端返回 409 冲突，原任务不被覆盖；
- AC-03：网络断开导致提交响应丢失后，在约定的请求映射保留期内，客户端能依据原请求标识查回任务，恢复过程不创建新任务；超出保留期不保证仍可查回，也不得自动换键或重新提交；
- AC-04：无权主体不能读取或下载其他主体的任务文件；按已接受的接口契约返回拒绝（例如 403，或为避免泄露资源存在性而统一返回 404），并按审计策略记录。
第三步：将任务拆分为可验证的切片，建立测试映射
Agent 将任务拆解为若干独立的工程切片，每个切片都应明确对应的验收条件（AC）。根据实际影响面选用测试手段，不得在开工前不加区分地堆砌或勾选无关测试。
| 切片标识 | 本切片完成的核心能力 | 对应验收 / 验证方式 | 本切片不包含的交付内容 |
|---|---|---|---|
| S1：受理与查询 | 原子持久化任务与请求身份；实现同键处理与权限过滤 | 覆盖 AC-01/02/04；规则测试、真实数据库并发与鉴权测试 | 尚未完成文件实际生成逻辑与用户交互界面 |
| S2：执行与结果 | Worker 异步生成、文件存储、超时与到期处理、重启恢复 | 文件完整性、状态机流转、执行代际（Epoch）与恢复测试 | 尚未完成前端与真实浏览器交互体验 |
| S3：用户端闭环 | 页面提交、网络异常恢复、进度轮询与安全下载 | 覆盖 AC-03/04；真实浏览器行为、无障碍与端到端链路测试 | 尚未完成适用的联合交付验证与生产发布冒烟测试 |
说明
候选规格文档必须先通过适用的文档审查（Documentation Review），方可进入编码实施。
第四步：驱动 Agent 完成单个切片（TDD 与自查）
向 Agent 提供任务卡、当前切片目标及已确认的规范依据。已明确授权的常规操作允许 Agent 自主推进，无需步步请示。
提示
切片实施指令（Prompt 范例）：
“请依据任务卡实现切片 S1，严禁超出本切片范围。严格遵循 TDD 循环：先编写并运行目标测试，捕获符合预期的失败日志（保留红灯证据）；编写最小实现，使测试转绿；按规范对核心判据实施变异负控，随后准确恢复变异前的实现。完成后，运行本切片适用的检查命令，将实际输出、受测 Commit SHA 和剩余问题写回任务卡。若遇到关键规格冲突，立即暂停受阻部分并向我反馈，继续推进不受影响的工作。”
切片完成标准：本切片的各项验收条件均有实际执行的验证证据；适用门禁全部通过；代码树摘要与受测版本完全一致；尚未完成的范围已明确标注。“S1 完成”仅代表当前切片完成，严禁直接宣告整个需求交付完毕。
第五步：双轴独立审查与合入检查
锁定候选代码树、变更差异与相关依据，由独立 Reviewer 及适用的人类领域专家复核。审查者独立读取必要上下文，分别产出 Standards 轴（规范一致性）与 Spec 轴（需求符合度）报告；小任务可在同一份报告中分轴记录。不同会话仍可能共享错误假设，不能把“独立上下文”当作准确性保证。
提示
审查指令（Prompt 范例）：
“请对照指定基线审查当前候选版本。Standards 轴检查代码及文档是否符合现行规范（并发安全、契约破坏、架构违例、盲区声明）；Spec 轴逐项核对任务卡验收条件、未覆盖边界与异常恢复。每个发现项必须明确指出具体位置、违规依据、触发条件与影响，并如实列出未审查范围。只做审查，严禁代为修改；不得以作者‘已自测’的口头声明作为通过证据。”
Agent 修复审查发现的问题并重新运行受影响门禁，审查者复核并关闭问题。通过后，遵循仓库分支保护规则完成提交、CI 验证与代码合并。随后选择下一个切片，重复第四步与第五步，直至全部切片完结。
全部切片完成后，在最终组合上逐项执行整张任务卡的验收，补齐跨切片联合验证，再进入整项交付。可独立交付的切片可以提前发布，但只声明本片已完成，其余任务保持 OPEN。
第六步：交付发布与真实状态回写
代码合入后，按本次范围执行发布、Schema 迁移、不可变制品冒烟、业务核验与 Runbook 演练。涉及多制品或多仓联合交付时，固化发布清单（Release Manifest）。
任务卡应如实记录各项交付状态：已实现、已验证、已合入、已部署、仍未完成（OPEN）。未涉及部署的任务明确标注“不适用”，严禁虚构上线事实。新增的架构决策、契约定义或运维操作说明，仅回写至对应的权威文档，严禁将任务卡全文机械复制到多个位置。