weichen
7d4d3352b5
Why: The 2026-10-09 diagnosis showed behavior-surface regressions (gate deadlocks, silently broken lint, wrong artifact verdicts) passing every unit test because no task-level check ran the real model. User ruling 6 approved making before/after live-eval evidence a delivery requirement for prompt, skill, tool-description, context-assembly and gate changes. Evidence: SELF - clause drafted to reference modules/backend/eval/live and the GATE/REPLAY/SELF sourcing already defined in AGENTS.md; task card for feature/agent-quality-phase01 filled with the P0+P1 scope and requirements. Impact: policy/delivery.md gains the 智能体行为面的真实验证 subsection; NOT_RUN stays legal but must be explicit. Phase01 task card records scope, requirements R1-R4 and the before/after eval protocol. Refs: modules/documents proposal 2026-10-09-agent-quality-improvement-plan.md (ruling 6).
151 lines
12 KiB
Markdown
151 lines
12 KiB
Markdown
# 需求、试验与迭代交付
|
||
|
||
适用：本项目的需求、修复、规范修改和其他交付任务。依据固定版本的
|
||
[通用交付流程](../deps/development-guidelines/workflows/delivery.md)，本项目收紧为
|
||
**默认逐阶段人工评审；阶段内迭代，按影响回退，按增量交付**。
|
||
本文件是阶段与评审的权威表述；启动、同步、命令证据和回收操作见
|
||
[开发门禁](governance.md)。规则的执行能力见 [能力矩阵](tool-adaptation-matrix.md)。
|
||
|
||
## 授权与阶段评审
|
||
|
||
任务卡默认记为 `manual`。完成当前阶段产物并取得人工评审结论后，才进入下一阶段。
|
||
评审记录包含阶段、对象版本、评审人、时间、结论、意见及可追溯依据；结论使用
|
||
未评审、通过、需修改、拒绝、不适用。人工结论与命令执行证据分开记录；Agent 自审、
|
||
测试通过、工具写入或用户沉默均不能代替人工批准，也不能由作者代签独立审核。
|
||
|
||
只有用户明确要求自动或连续推进时，才将对应范围记为 `authorized-continuous`，记录
|
||
授权来源、覆盖阶段、允许动作、交付终点、资源约束和停止条件。未覆盖阶段仍逐阶段评审。
|
||
授权连续推进不免除需求分析、试验判定、测试、代码 Review、证据和平台准入；
|
||
既有独立审核要求及高后果操作双钥匙仍有效。单独的合入授权不补齐尚不存在的前序产物。
|
||
|
||
阶段内已授权的调查、编辑、自检、缺陷修复和等价实现可以持续进行，无需逐命令批准。
|
||
需求拆解、评估、需求表可以共用一份任务卡，但分别保留阶段结论。小任务缩短篇幅；
|
||
确实不适用的内容说明原因，经人工确认或在明确授权的裁剪范围内处理，不能静默跳步。
|
||
任务启动检查、独立工作区和收据用于准备现场，不表示任何阶段评审已通过。
|
||
|
||
## 阶段与出口
|
||
|
||
| 阶段 | 必需产物 | 进入下一阶段的条件 |
|
||
|---|---|---|
|
||
| 1 需求拆解 | 目标、用户场景、子需求、边界、非目标及待澄清问题 | 人工确认拆解与原始意图一致 |
|
||
| 2 需求评估 | 价值、可行性、成本、风险、依赖、现有能力及在途任务重叠；与项目定位、模块职责和公开契约的符合度 | 人工确认取舍；重大未知转入下述受控试验 |
|
||
| 3 需求表确认 | 稳定 ID、描述、适配依据、优先级、可判定验收条件、依赖和处理结论 | 人工确认本增量范围；影响实施的关键待核实项已处理 |
|
||
| 4 方案设计 | 推荐方案与主要备选、职责和接口、数据与权限影响、失败恢复、待验证假设及试验结论 | 人工批准当前方案版本及剩余风险处理方式 |
|
||
| 5 实施计划 | 关联需求的工作项、依赖顺序、责任人、文件或模块范围、测试方法与环境、完成条件及停止条件 | 人工批准当前实施和测试计划；远期工作可保留粗粒度 |
|
||
| 6 实施与自检 | 可审查变更、局部测试、计划偏差与迭代记录 | 人工确认当前增量实现产物，必要设计调整已重新获批 |
|
||
| 7 正式测试与验收 | 需求到证据映射；正常、异常、边界、回归结果及缺项 | 人工审阅当前候选的验证结果；正式验收前同步并固定被测对象 |
|
||
| 8 代码 Review | 需求符合性、正确性、维护性、测试充分性及问题闭合记录 | 完成必要重放、整改、补测和复审，由有权评审者放行当前版本 |
|
||
| 9 合入 | 最新 base/head、必要检查及评审、冲突处置、合入授权 | 合入前再次同步核验；经 PR 合入后取得真实合入结果 |
|
||
| 10 合入核验与收口 | 实际合入内容及组件版本、验证依据、成果保存位置、写者状态、清理清单、任务归档安排及适用规划的进展与下一步建议 | 清理前取得人工批准或对应连续推进授权；安全回收后核对结果、闭合任务卡 |
|
||
|
||
表中的人工节点仅在明确的连续推进授权范围内按授权执行；阶段产物及验证条件保留。
|
||
正式测试和最终 Review 的顺序不限制设计阶段试验、实施期测试或提前审阅。
|
||
文本合并无冲突不证明组合兼容；合入后仍核验真实内容与被测候选是否一致。
|
||
|
||
## 长期方向与任务衔接
|
||
|
||
用户提出大方向、长期目标或跨任务规划时，必须在项目中留存可接续的主记录，不能仅保留
|
||
在聊天、IDE 私有计划或执行者记忆中。优先更新已有相关规划；确需新文档时，沿用
|
||
过程仓的 `modules/documents/docs/proposals/`，并在 [项目入口](../PROJECT.md) 提供链接。
|
||
正文只维护一处，任务卡和其他入口引用文档及版本，不复制另一份规划状态。
|
||
|
||
主记录至少包括：目标及背景、范围及成功标准、阶段或里程碑、关联方案和任务、来源、
|
||
负责人、确认状态、推进状态及更新时间。只有方向时可以先写简短目标记录，未知项标待定。
|
||
未确认的想法标“待确认”；确认依据与版本另记，不能由“已记录”推断“已批准”。
|
||
方向、范围或优先级调整时保留原决定、变更原因及批准依据，更新受影响的方案和任务引用。
|
||
|
||
启动或恢复相关任务时，先读取适用方向及规划的当前有效版本，核对本任务所属里程碑、
|
||
已有实现和在途任务。多个规划相互冲突或优先级不明时，记录冲突并提交人工决定，
|
||
不凭文档标题、日期或本地旧副本擅自选择权威。
|
||
|
||
任务完成时，如果存在适用方案或规划，必须依据实际结果更新其进展，并在任务主记录和
|
||
最终交付说明中给出下一步任务建议：
|
||
|
||
- 说明本任务推进了哪个目标或里程碑，以及剩余差距；区分已实现、已验证、已合入和已部署。
|
||
- 优先推荐一个下一任务，说明要解决的问题、关联规划及版本、推荐理由和优先顺序依据。
|
||
- 写明前置条件、依赖、待确认事项、预期产物和可判定验收条件；必要时补充备选及取舍。
|
||
- 建议前核对已有或在途任务；已有任务覆盖时引用该任务及待续办内容，避免重复安排。
|
||
- 无适用规划或规划已经完成时如实说明；存在阻塞时列出阻塞条件，优先建议澄清、验证假设
|
||
或解除阻塞的任务，不为凑出下一步虚构工作。
|
||
|
||
进展更新和建议属于当前任务的收尾产物。跨仓更新遵循对应工作区、版本和评审要求；
|
||
更新尚未获批或合入时，任务卡保留待更新内容、负责人和下一动作，不能声称原规划已更新。
|
||
**下一步建议不等于启动授权**：没有覆盖该任务的明确授权，建议停留在待确认状态；
|
||
当前任务的完成、批准或连续推进授权不自动扩展到新任务。
|
||
|
||
## 需求表与追溯
|
||
|
||
需求表以任务卡为主记录。项目符合度使用“符合 / 需调整后符合 / 不符合 / 待核实”，
|
||
附当前源码、项目约束或实测依据。处理结论使用“纳入本增量 / 后续处理 / 拒绝 / 待定”，
|
||
与符合度分开；关键依据缺失时保留待核实，不凭推测判定通过。
|
||
|
||
每个纳入实施的需求必须能追溯到：
|
||
|
||
`需求 ID 与验收条件 → 方案及工作项 → 测试或审阅方法 → 当前版本结果与证据`。
|
||
|
||
没有可判定验收方法的需求先澄清；待定或不符合的需求未经重新评审不得进入正式实施。
|
||
跨模块、权限、持久化、异步和恢复需求按实际风险补充真实链路及故障场景。
|
||
规范和文档任务采用差异、链接、规则一致性及相关工具行为检查，不制造无关业务测试。
|
||
|
||
## 设计探索循环
|
||
|
||
需求分析和设计阶段允许先试验再完善方案，无须先批准尚未能确定的完整设计。
|
||
执行试验前提交最小试验计划：待回答的问题或假设、对象和隔离环境、方法、预期判据、
|
||
允许副作用、时间或成本边界、停止条件及产物保存或处置方式，并取得人工批准；
|
||
已有连续推进授权明确覆盖该试验范围时，引用该授权。
|
||
|
||
在已批准范围内可以反复尝试：
|
||
|
||
`初步方案 → 批准试验范围 → 原型或测试 → 分析证据 → 修订方案与计划 → 结果评审`。
|
||
|
||
记录成功、失败及不确定结果，以及下一步继续探索、采用、换方案或暂停的理由。
|
||
超出范围、触及未授权共享环境、达到预算或持续无有效进展时，暂停受影响试验并提交决策。
|
||
无需强求全部未知一次消除；影响下一步的关键假设必须有结论，其余风险有责任人与处理安排。
|
||
|
||
原型标明用途和限制，不自动成为正式实现。决定复用时纳入方案、计划、代码 Review 与正式验证。
|
||
试验成功仅证明相应假设，不能替代验收；失败结果用于调整方案，不能静默降低验收标准。
|
||
|
||
## 实施、测试与 Review 的反馈循环
|
||
|
||
按可独立验证的增量推进；近期工作细化到可执行，后续工作根据证据逐步细化。
|
||
每轮形成“发现与证据 → 原假设或困难 → 调整及影响 → 重审和补测范围 → 决策 → 结果”。
|
||
记录放在同一任务卡，较长材料只引用文件或 PR，避免多份状态。
|
||
|
||
### 智能体行为面的真实验证（2026-10-09 裁定）
|
||
|
||
改动智能体行为面的 PR——提示词库、技能配方（SKILL 与 housestyle）、工具描述与
|
||
注册面、上下文组装与回放、终轮门禁与评分——须附**真实模型的任务级前后对照**
|
||
（`modules/backend/eval/live/` 基线，或等价的最小重放集），写入任务卡并标注来源
|
||
（GATE/REPLAY/SELF）。单测与 mock 回放不覆盖模型实际行为，只能证明机制，不能
|
||
替代该对照。确无条件跑真实模型时，在任务卡显式标注 `NOT_RUN` 并说明原因与
|
||
补救计划；不得以“预期改善”措辞代替证据。评测材料不进仓（沿用 eval/README 口径）。
|
||
|
||
| 变化 | 执行动作与评审边界 |
|
||
|---|---|
|
||
| 已批准范围内的内部组织、等价实现、局部缺陷修正 | 当前阶段继续调整、自测并记录；阶段出口统一人工评审 |
|
||
| 技术路线、模块职责、公开契约、数据或权限设计、外部影响，或计划的关键依赖、交付顺序和资源约束变化 | 暂停受影响工作，修订方案或计划，经人工重审后继续；已有明确授权覆盖该类调整时按其边界执行 |
|
||
| 目标、范围、优先级或验收条件变化 | 返回需求评估和需求表，取得对应批准后更新下游方案、计划和验证 |
|
||
| 影响不明 | 先调查；仍无法判定时提交人工决定，不自行归入细节调整 |
|
||
|
||
未受影响且已有授权的工作可以继续。测试或 Review 发现实现缺陷，返回实施修复；
|
||
发现设计缺陷返回方案；发现需求理解错误返回需求阶段。只重走受影响环节，并说明
|
||
未重走部分为何仍有效。新版本不能沿用已受影响的批准、测试或 Review 结论。
|
||
|
||
批准对象使用文档修订或提交标识；正式验证固定源码、组件组合与相关配置。
|
||
对 head/base、依赖、需求或契约变化重新判断证据及评审的有效性，按影响补测和复审。
|
||
阶段状态、测试状态、代码审核状态及合入状态分别记录，不以一个“完成”互相替代。
|
||
|
||
## 合入、清理与恢复
|
||
|
||
合入与清理分别核对授权及条件。仅回收本任务登记工作区，按开发门禁核对当前权威目标、
|
||
父子仓成果、未跟踪和 ignored 文件、独有提交与引用、活动 Git 操作以及所有写者退出。
|
||
无法证明成果已保存时保留现场；本地删除与远端分支删除分别报告。
|
||
|
||
清理前保存任务主记录与证据。执行回收时将命令输出用 evidence 的 `RECEIPT` 模式保存到
|
||
待删目录之外；回收后的结果写入后续闭合记录，不能向已删除的任务卡补写收据。
|
||
任务卡须回填真实主 PR 和完成状态并归档；闭合 PR 的创建、合入均依当前授权执行。
|
||
post-merge 默认只提示，不因 pull 或 merge 自动提交、推送或创建闭合 PR。
|
||
|
||
中断或交接时记录当前有效版本、批准范围、未决假设、最新试验结论、剩余事项及下一动作。
|
||
恢复后核对现场和授权，从最早未满足的环节续办；不重做仍有效的工作，不省略失效环节。
|