| name | plan-review |
| description | 实现计划审批后、开始编码前使用,从架构视角审查计划的完整性和风险。 |
架构审查 (Plan Review)
概览
在 Plan 模式完成(Step 2)和 Code 模式开始(Step 4-5)之间插入的架构审查环节。以工程经理视角逐项审视计划,发现实现前能发现的问题。
何时使用
- 计划涉及跨模块或跨服务的变更。
- 计划涉及数据库 schema 变更或数据迁移。
- 计划涉及公共 API 设计或协议变更。
- 任何 complex 级别的任务在进入 Code 模式前。
审查维度
1. 数据流完整性
- 输入 -> 处理 -> 存储 -> 输出,每个环节是否有明确定义。
- 错误路径:每个环节失败时的行为是否考虑。
- 数据校验:边界在哪里做,是否有遗漏。
2. 并发与一致性
- 并发访问模式:读写比例、热点资源。
- 锁策略:乐观锁 vs 悲观锁,锁粒度是否合理。
- 事务边界:哪些操作必须原子,是否存在长事务风险。
- 幂等性:重试是否安全。
3. 接口契约
- 向后兼容:新变更是否破坏已有调用方。
- 版本策略:是否需要 API 版本化。
- 错误码与错误信息:是否有一致的规范。
4. 测试策略
- 单元测试:核心逻辑的覆盖点。
- 集成测试:跨模块交互的验证。
- 边界条件:空值、溢出、并发竞争、超时。
- 性能基准:是否需要 benchmark,阈值是什么。
5. 可运维性
- 可观测性:日志、指标、链路追踪是否覆盖关键路径。
- 回滚方案:出问题时如何回退,数据迁移是否可逆。
- 配置管理:新增配置项是否有默认值和文档。
执行协议
- 逐维度审查计划,对每个维度给出 pass / warn / fail。
- 对 warn 和 fail 项给出具体问题和修改建议。
- 所有 fail 项必须在进入 Code 模式前解决。
- warn 项由用户决定是否立即处理或记录为技术债。
快速参考
| 维度 | 关注点 | 常见遗漏 |
|---|
| 数据流 | 端到端完整性 | 错误路径未定义 |
| 并发 | 锁与事务 | 幂等性未考虑 |
| 接口 | 向后兼容 | 破坏性变更未标注 |
| 测试 | 边界覆盖 | 只有 happy path |
| 运维 | 可回滚性 | 迁移不可逆 |
常见错误
- 审查流于形式:逐维度打勾但不深入思考具体场景。
- 忽略非功能性需求:只看"能不能跑",不看"跑得怎么样"。
- 计划过于粗糙就通过:实现时发现大量未定义行为,被迫回到 Plan 模式。
质量评估标准
以下为二元(pass/fail)评估项,用于验证本 skill 输出质量。可配合 autoresearch 工具自动化运行。
EVAL 1: 五维度全覆盖
问题: 审查报告是否逐一覆盖了数据流、并发、接口、测试、运维全部 5 个维度?
Pass: 5 个维度各有独立段落和明确评判
Fail: 遗漏了任何一个维度,或多个维度合并为一段敷衍带过
EVAL 2: pass/warn/fail 评级
问题: 每个维度是否给出了明确的 pass、warn 或 fail 评级?
Pass: 每个维度都有 pass/warn/fail 中的一个明确标注
Fail: 存在维度只有描述没有评级,或使用了模糊表述("大体可以")
EVAL 3: fail 项有具体修改建议
问题: 每个 fail 项是否附带了具体的修改建议(不是泛泛的"需要改进")?
Pass: fail 项有可操作的建议,指出改什么、怎么改
Fail: fail 项只说"不行"但没有建议,或建议过于模糊
EVAL 4: 错误路径覆盖
问题: 数据流维度是否分析了至少一个错误路径(不只是 happy path)?
Pass: 明确讨论了某个环节失败时的行为(超时、异常、数据不合法等)
Fail: 只分析了正常流程,未提及任何错误场景
EVAL 5: 可回滚性评估
问题: 运维维度是否评估了变更的可回滚性?
Pass: 明确说明了回滚方案或指出不可回滚的风险
Fail: 未提及回滚,或只说"可以回滚"但没有具体方案