review · diff
git:20260728.b57c5d5 to git:20260923.8eb4b09
26 added, 32 removed. Audit A to A.
---
name: review
- description: 当用户要求对明确的需求、设计、计划、代码、diff、MR 或交付物作独立冷读，或需要判断它能否继续合并、测试或交付时使用。锁定准确对象与 baseline，检查完整影响面，独立证伪候选问题，并以证据给出裁决。直接实现、只有解释、没有可审查对象，或低风险小改没有独立审查价值时不触发。
+ description: 用户要求 review、CR，让你看看某个改动、PR、MR、设计或方案有没有问题，或者要判断它能不能合并、交付时使用。独立冷读准确的对象，查完影响范围，每个问题先试着推翻再报告，最后给出结论。只想弄懂改了什么时用 walkthrough；自己刚写完代码的日常自查不用。
---
# review
- ## 从作者之外重建判断
-
- 评审不是替作者润色，也不是复述已有结论。先确认被审查对象的准确版本、工作树状态、任务承诺和比较 baseline；作者摘要、测试名称、先前评审与多数意见都只是线索。对象或基线的缺口会改变结论时，不猜一个方便的版本继续。
-
- ## 看完整影响面，按风险分配深度
+ 像一位没参与编写、熟悉这个项目的维护者那样冷读：不采信作者的说法，自己从代码和证据重建判断。作者的摘要、测试名称和之前的评审意见都只是线索。
- 从原始对象建立变化面：所有变更文件或章节，以及真正受影响的调用者、契约、权限、状态、数据、异步过程和下游消费者。每个实质表面都应被检查、以证据判定无关，或留下具名证据缺口；完整覆盖不等于平均用力，风险决定深度。发现第一个问题后继续看完对象。
+ ## 锁定对象
- 公共接口、信任边界、I/O 与恢复、热路径或高风险组合实际存在时，分别深入兼容、安全、可靠性、性能与组合风险；不适用必须来自对象证据，不能用作者保证或“通常不会发生”代替。
+ 先确认审的是什么：哪个分支、提交或 diff，和哪个版本比较，工作树里有没有未提交的改动，这次改动要达成什么（有 `.agents/tasks/<任务>/shape.md` 时，读其中的目标和验收标准）。对象或比较版本不清楚、又会影响结论时，先查清或问清，不自己挑一个方便的版本。
- 完整影响面也包括变化自身的纪律与项目承担：每个 hunk 是否可追溯到当前承诺，是否夹带 scope 外改动、重复权威来源、绕过项目标准，测试是否真正约束新增行为与回归面，注释、死代码或抽象是否仍表达真实结构；结构是否落在正确的架构边界，新增公共表面、所有权、兼容、运维与长期维护成本由谁承担。更小不自动更诚实，更整齐也不足以支付这些成本。
+ ## 查完影响范围，按风险分配精力
- 变化评审只把本次引入或显著放大的问题归给当前对象。既有问题仅在用户要求整体审计，或它会使当前裁决失真时展开，并明确来源。
+ 从改动出发，列出它真正影响到的东西：改动的每个文件，以及受影响的调用方、公共接口、权限、数据和状态、异步过程和下游消费者。每一项要么检查过，要么有证据说明不受影响，要么写成没查到的缺口。精力按风险分配：公共接口、安全边界、数据与恢复路径、热路径值得深挖，其余看一遍即可。发现第一个问题后继续看完。
- ## Finding 必须走通证据链
+ 除了正确性，也看改动本身是否干净：每处改动能否对应到本次目标，有没有夹带范围外的修改、重复实现或绕开项目已有做法，测试是否真正约束了新行为，新增的抽象和公共接口以后由谁维护。
- 报告的问题必须能够从具体输入、状态、调用者或代码结构，走过实际文件、接口与状态转换，到达错误结果、破坏的承诺或具体长期成本，并给出可打开的代码、命令、日志、规则或运行结果。处理方向要说明正确修复落在哪里、是否属于当前对象，以及仍未确认什么。
+ 只把本次引入或明显放大的问题算在这次改动上。既有问题只在用户要求整体审计，或它会改变本次结论时提出，并注明是既有的。
- 问题优先级由现实影响、触发可达性和恢复代价决定：`P0` 只用于广泛、灾难性或不可逆的发布阻断，`P1` 是现实可达的重要失败，`P2` 是普通但具体、作者知道后应该修的问题，`P3` 只保留低影响但价值明确的改进。优先级不表示证据强弱、scope 关系或处理方式，不能包装猜测，也不能掩盖真实阻断问题。风格偏好、理论可能和没有价格的“应该重构”不是 finding。
+ ## 每个问题都要走通证据
- 报告前把每个候选重新当作未证实假设。主动寻找上游门、类型与权限保证、调用契约、补偿机制和相反运行证据；依赖外部语义时查一手文档、源码或可重放结果。被推翻的候选删除；部分成立的候选修正其机制、影响和优先级；缺少证据的保留为具名缺口。失败于证伪不等于已经确认。
+ 报告的每个问题都要说清：什么输入、状态或调用方会触发它，经过哪些代码，最后导致什么错误结果、破坏什么约定或带来什么长期成本，并附上能打开的证据（代码位置、命令输出、日志或运行结果）。风格偏好、走不通的理论路径、说不出具体代价的"应该重构"，都不算问题。
- ## 用处理标签固定下一步
+ 报告前把每个候选当作未证实的假设，主动找能推翻它的东西：上游校验、类型或权限保证、调用约定、已有的补偿逻辑、相反的运行结果。被推翻的删掉；部分成立的改正描述；证据不够的写成待查的缺口，不当作问题报告。
- 每个成立的 finding 都标记一个处理方式，优先级和问题真实性不能替代它：
+ ## 严重程度和是否需要用户决定
- - `fix-now`：当前对象前进前必须解决，且用户请求或 Context 已经授权这项实现；
- - `needs-owner-decision`：处理需要接受风险、改变承诺、扩大范围，或引入用户无法合理预见且不成比例的行为、契约、迁移、权限、并发或结构成本；责任人决定并重新标记前不得实施；
- - `follow-up`：问题真实，但当前对象可以前进；说明独立任务的责任人和当前由谁承担剩余风险。
+ 每个问题标一个严重程度：
- 责任人决定后，根据决定把 `needs-owner-decision` 改为 `fix-now`、`follow-up` 或删除；不能把问题优先级、仓库规则、技术必要性、已有实现或测试通过当作授权证据。
+ - **高**：现实中会触发的严重错误，如数据损坏、越权、主流程失败，不修不能合并。
+ - **中**：具体、会发生的错误，或明显的维护代价，应该修。
+ - **低**：影响小，但值得改进。
- ## 给出一个诚实裁决
+ 再标明它的处理是否需要用户决定。修复需要改变目标或范围、接受某种风险，或引入超出原请求的机制（迁移、兼容层、新的公共接口、大规模重构）时，需要用户决定；其余可以直接修。
- 最终裁决只有：
+ ## 给出结论
- - `approve`：没有必须先修的问题或未决责任人决定，关键证据足够；
- - `request_changes`：至少一个 `fix-now` 尚未解决，且没有会改变当前方向的未决责任人决定；
- - `needs_owner_decision`：至少一个 `needs-owner-decision` 尚未裁决；
- - `needs_more_evidence`：具名证据缺口可能改变能否前进；
- - `blocked`：准确对象不可用或审查已被取消。
+ 结论只有三种：
- `needs_owner_decision` 必须写清要决定什么、可选方向和代价；不依赖该决定的 `fix-now` 可以继续，但存在未决标签时最终裁决保持 `needs_owner_decision`，不能降为 `approve` 或 `request_changes`。未检查的表面和不稳定证据也不能被沉默写成批准。
+ - **可以合并**：没有高或中的问题，关键证据足够。
+ - **需要修改**：有可以直接修的高或中问题。
+ - **需要你决定**：有问题的处理需要用户决定；写清要决定什么、有哪些选择、各自的代价。
- ## 保持作者与裁决分离
+ 可能改变结论的证据缺口要写明，不能默认当作通过。
- 默认不直接修改自己正在批准的对象。完整审查面不等于完整修改面；用户要求评审后修复时，先保存评审结论，只有 `fix-now` 进入当前 `dev`，`needs-owner-decision` 等待责任人或 `shape`，`follow-up` 进入独立任务。随后复核原 finding、受影响路径和新 diff，而不是把作者信心当成关闭证据。
+ ## 评审和修改分开
- 简单评审直接在对话中让 findings 先行，再给裁决、边界和剩余风险。当前任务有 `context.md`，且结论需要保存或交接时，写 `<task-workspace>/review/review.md`，以 [review.demo.md](references/templates/review.demo.md) 为唯一结构来源，并更新 Current Artifacts。
+ 默认不改正在审的代码。用户要求审完就修时，先给出评审结论，只修不需要用户决定的问题，需要决定的等用户决定；修完后重新核对原问题和新的 diff。
- 完成时，对象与 baseline 明确，完整影响面有去向，所有报告的问题都经过独立复核，证据缺口没有伪装成 finding 或 `approve`，裁决与真实证据一致。
+ 默认在对话里输出：问题在前，按严重程度排序；然后是结论、检查过的范围和没查到的部分。当前任务有 `.agents/tasks/<任务>/` 目录且需要保存时，写到那里的 `review.md`。