附录B 工程模板速查
本附录将正文中分散讨论的关键工程制品整理为五份可直接修改使用的结构化模板：AGENTS.md、任务简报、验证证据清单、评审检查表和迁移计划。每份模板只保留基本结构和必要字段，并不试图提供一份适用于所有项目的完整文档。团队应当根据项目规模、技术栈、风险等级和协作方式增删内容。
这些模板的价值，在于提醒使用者覆盖任务目标、约束、验证和责任边界等关键要素，而不在于机械保留所有字段。每份模板后均标注了对应的正文章节；如果需要理解某个字段为什么存在，以及应当如何确定其内容，可以回到相应章节查看完整论述。
B.1 AGENTS.md模板
AGENTS.md是用于记录代码库约定的项目指令文件。支持该机制的编码智能体会根据当前工作目录和文件作用域加载相应内容。第6.5节介绍了它的基本作用，此后各章的实践示例又不断扩展了这类文件可以承载的信息。
在实际项目中，代码库根目录下的AGENTS.md通常保存项目级通用要求，模块目录下的AGENTS.md则补充该模块特有的构建方式、设计约定和操作限制。下层文件应当尽量只记录差异，避免重复上层已经明确的内容。
| # <项目名>/AGENTS.md ## 项目概览 用一两句话说明项目解决什么问题、服务哪些用户，以及当前模块在系统中的职责。 ## 目录结构 列出主要目录及其职责，帮助智能体快速定位代码，避免在无关目录中反复探查。 ## 构建与测试命令 - 安装依赖：<命令> - 运行测试：<命令> - 静态检查：<命令> ## 既有约定 列出代码风格、命名规则、已经采用的设计模式，以及新增实现应当参照的现有文件或模块。 ## 强制的受限子集（如适用） 列出禁止使用的语言特性、库或者写法，并给出相应的确定性检查命令。 ## 自主性边界 - 可自主决定：<允许智能体自行选择的事项> - 必须升级请示：<触发结构化决策请求的条件，例如涉及跨模块共享结构> - 绝对禁止：<不得执行的操作，例如删除生产数据或者绕过安全检查> ## 关键安全区块（如适用） 列出带有稳定编号的强制约束，说明其适用范围、违反后果，以及相关决议记录的编号或链接。 |
|---|
对应正文：第6.5节AGENTS.md的基本设计；第6.3节自主性边界的划分原则；第20.4节受限子集的工程价值；第19.5节关键安全区块的固化方式。
B.2 任务简报模板
任务简报是第6.2节提出的核心工程制品，用于把模糊需求转化为边界清晰、可以执行并能够验收的任务说明。第11.2节进一步提炼了判断任务边界是否充分明确的关键要素。下面的模板将两处内容整合为目标陈述、验收标准、相关背景、约束条件、自主性边界和验证证据要求六个部分。
目标陈述应当明确期望行为和任务范围，但不必把实现方式限定到只剩一种选择。需要由开发者作出的架构或业务决定应当提前确定；允许智能体自主选择的实现细节，则应当在自主性边界中明确授权。
| ## 任务简报：<任务名称> ### 目标陈述 说明需要解决的问题、期望实现的行为、任务范围以及明确不属于本次任务的内容。 ### 验收标准 - 标准一：<可观察、可核验的具体条件> - 标准二：<…> ### 相关背景 提供智能体完成任务所必需、但无法仅通过读取当前代码获得的信息，例如既有决策、历史兼容要求、业务规则和可供参照的相似实现。 ### 约束条件 列出本次实现不得突破的边界，例如不能修改的接口、不能引入的依赖、必须保持的兼容性和资源限制。 ### 自主性边界 - 可自主决定：<允许智能体自行选择的事项> - 必须升级请示：<需要提交结构化决策请求的情况> - 绝对禁止：<不得执行的操作> ### 验证证据要求 列出验收时必须提交的验证命令、结果和证据形式，例如测试结果、静态检查结果、基准测试数据、代码差异和必要的执行日志。 |
|---|
对应正文：第6.2节任务简报的核心构成；第11.2节任务边界四要素与验收要求；第6.3节自主性边界；第9.3节证据驱动监督。
B.3 验证证据清单
证据驱动监督要求重要结论由可以核实的证据支撑。第9.3节从证据包、机器可读清单、渐进式披露和责任链四个方面说明了验证证据应当如何形成；第17.3节进一步讨论了阶段交接时如何通过交接契约传递工作产物、验证证据和必要上下文。
下面的清单用于检查一组验证证据能否支持相应结论。清单本身不能证明实现正确，但可以帮助评审者识别证据是否缺失、能否复现以及是否具备必要的独立性。
| 检查项 | 说明 |
|---|---|
| 工作产物是否明确 | 是否指出代码差异、文档或者分析结果，并提供具体文件路径、提交哈希或者其他稳定标识 |
| 测试证据是否完整 | 是否记录实际执行的测试命令、执行环境、通过与失败数量，以及与本次改动相关的覆盖情况 |
| 基准或性能证据是否提供（如涉及） | 是否给出改动前后的可比数据、测试条件和测量方法，而不只是“性能有所提高”等结论 |
| 决策理由是否可以追溯 | 是否说明为什么选择当前方案、考虑过哪些备选方案，以及其他方案未被采用的原因 |
| 关键结论是否经过独立核验 | 核验关键结论的人、测试或者评估机制，是否与生成该结论的主体保持了必要的独立性 |
| 渐进式披露是否到位 | 是否先提供便于快速判断的摘要，并通过证据指针支持评审者按需查看测试结果、日志和原始数据 |
| 责任链是否完整 | 是否能够追溯验证证据由谁或由哪个系统在什么时间、什么环境和什么条件下生成 |
对应正文：第9.3节证据驱动监督；第9.4节独立验证原则；第17.3节交接契约及交接记录。
B.4 评审检查表
第9.5节提出的分层验证框架，将验证范围从“测试是否通过”扩展到行为一致性、类型与结构、独立复核、安全与供应链、性能与真实负载等层面。第15.3节又引入了P0至P3的四级分级，用于区分阻断提交、当前迭代处理、记录进入技术债务清单和作为建议处理四类不同紧迫程度的问题。
下面的检查表将两处内容整合为一组可以逐项核对的问题。严重程度不能仅凭问题所属层级判断，还应结合影响范围、可利用性、可逆性和发生概率确定。表中给出的等级只是本书采用的一般判断，不替代项目自身的缺陷分级规则。
| 验证层 | 核查要点 | 常见严重程度 |
|---|---|---|
| 行为一致性 | 既有测试是否全部通过；新增测试是否覆盖本次改动的关键路径、边界条件和失败场景 | 关键行为不符合要求通常为P0 |
| 类型与结构健全性 | 静态类型检查和结构检查是否通过；是否新增了绕过类型系统、破坏模块边界或者扩大耦合范围的写法 | 根据影响范围判断 |
| 独立复核与惯用写法 | 实现是否符合项目既有约定；关键逻辑是否经过独立复核；是否存在形式上正确但语义偏离需求的问题 | 根据语义影响判断 |
| 安全与供应链审计 | 是否引入未经评估的新依赖；是否存在硬编码凭证、越权访问或者跨越高风险信任边界的操作 | 凭证泄露、明显越权等通常为P0 |
| 性能与真实负载 | 是否提供可比较的基准测试；是否出现明显性能退化；测试负载是否能够代表预期运行环境 | 根据退化程度和业务影响判断 |
对应正文：第9.5节分层验证；第15.3节P0至P3的四级处置分级；第15.4节工程护栏与安全扫描。
B.5 迁移计划模板
第14章系统讨论了迁移任务从只读探查、风险识别、路径选择、批次执行到分层验证和回滚的完整过程。下面的模板将这些环节整合成一份可以直接修改使用的迁移计划。
需要注意，逐文件迁移、逐模块迁移和新旧系统并行切换描述的是迁移路径；并行子智能体描述的是任务执行方式。两者并不互斥。例如，一项逐模块迁移可以把相互独立的模块分配给多个子智能体并行处理，但仍需分别隔离代码状态和运行时资源。
| ## 迁移计划：<迁移名称> ### 现代化报告摘要 用业务语言说明系统当前承担的功能、主要模块行为、数据模型、外部依赖和已知兼容要求。 ### 风险登记册 - 日期与时区处理：<文件与位置> - 数值舍入和精度：<文件与位置> - 字符编码：<文件与位置> - 隐含排序假设：<文件与位置> - 全局可变状态：<文件与位置> - 其他项目特有风险：<文件与位置> ### 迁移路径选择 选定路径：逐文件迁移 / 逐模块迁移 / 新旧系统并行切换 选择理由：<根据模块耦合度、业务连续性要求、时间压力和回滚成本说明理由> ### 执行方式 执行方式：顺序执行 / 并行子智能体 并行条件：<说明任务在代码范围和运行时资源方面为何相互独立> 隔离措施：<分支或Git Worktree、端口、数据库、缓存目录及其他运行资源> ### 批次划分 - 批次一：<迁移范围>；验证命令：<命令>；通过条件：<条件> - 批次二：<迁移范围>；验证命令：<命令>；通过条件：<条件> 每个批次必须在验证通过后才能进入下一批次。验证失败时，应停止推进并依据失败证据判断是修正当前批次、调整迁移计划，还是退回上一稳定状态。 ### 分层验证清单 全部迁移批次完成后，依次核对表B.4中的五个验证层，并记录每一层使用的验证方法和结果。 ### 回滚方案 为每个批次分别说明： - 触发回滚的具体条件 - 回滚命令或者操作步骤 - 数据兼容与恢复方式 - 回滚后的验证命令 - 负责批准或执行回滚的角色 |
|---|
对应正文：第14.2节只读探查与风险登记册；第14.3节迁移路径和执行方式；第14.4节批次门控；第14.5节大规模重写的分层验证；第16.3节并行任务的代码与运行时隔离。