Cross Verified Feature Development

Cross-Verified Feature Development

A structured workflow for high-stakes backend features. After implementation, it runs 4 independent verification passes to catch bugs that self-review and standard code review miss — particularly concurrency races, idempotency gaps, and cross-service contract breaks.

Prerequisites · 前置条件

本 skill 编排 Superpowers 生态中的子 skill 完成各阶段工作。

Install Superpowers（一次性）：

claude mcp add --transport http superpowers https://superpowers.anthropic.com/mcp

本 skill 依赖的子 skill：

没有 Superpowers 也能用（fallback）：

Overview · 概览

这是一套多轮交叉验证的严谨特性开发方法论，用于开发关键业务特性时最小化生产事故概率。

Core Insight · 核心洞察

单一视角的 review 有系统性盲点。即使最有经验的开发者也会：

• 被自己的设计思路"带偏"
• 默认某些字段语义是唯一的（实际可能多义）
• 假设"应该幂等"的操作真的幂等（实际不是）
• 看漏并发窗口
• 忘记更新文档导致设计文档与代码失联

独立视角产生的信号彼此独立。用 N 个互不知情的 reviewer 轮询一个特性，发现的 bug 集合接近是并集而不是重复。所以这个工作流的本质是：

设计 → 实施 → 多轮独立交叉验证 → 修复 → 谨慎简化 → 文档同步

Comparison with Standard Workflow · 与普通开发工作流的差异

When to Use · 适用场景

本工作流值得的成本：预估实施工作量 ≥ 3 人日、且失败代价高的特性。

典型适用领域（按"bug 代价高低"排序，任意一项命中即建议使用）：

不适用：

• 纯 UI / 前端展示调整
• 纯 CRUD 无状态机语义
• 一次性数据处理脚本
• 修个小 bug
• 实施工作量 < 1 人日

判定启发式：如果你能用一句话回答"这个 feature 最坏的 bug 会造成什么？"并且答案包含资金损失 / 数据错乱 / 订单卡死 / 用户权限越权 / 生产事故之一，那就值得走本工作流。

Decision tree · 决策树：

Does the feature involve any of the following?
│
├── 💰 Financial transactions, payments, refunds, settlements?      ──→ YES → Use this workflow
├── 🔄 Order / inventory state machines with status transitions?    ──→ YES → Use this workflow
├── 🔒 Distributed locks, concurrency control, idempotent retry?    ──→ YES → Use this workflow
├── 🔗 Cross-service MQ/RPC contracts or shared proto/model change? ──→ YES → Use this workflow
├── 🗄️  Online schema migration or dual-write strategy?             ──→ YES → Use this workflow
└── ⏱️  Estimated effort ≥ 3 person-days?
    └── AND worst-case bug causes: money loss / data corruption /
        stuck orders / privilege escalation / production incident?  ──→ YES → Use this workflow

None of the above?  ──→  Standard workflow is fine ✓

7-Phase Workflow · 完整 7 阶段工作流

① 需求/设计        → superpowers:brainstorming
①.5 架构决策评审   → ADR（高风险特性必做）
② 实施计划        → superpowers:writing-plans（含部署策略）
③ 实施           → superpowers:subagent-driven-development
④ 🔥 多轮交叉验证  ← 本 skill 的核心创新
⑤ 迭代修复        → writing-plans round 2 + executing（含回归保护）
⑥ 谨慎简化        → 带怀疑的优化
⑦ 文档同步        → 回填 evolution log + 下游通知

Phase 1: Requirements & Design · 需求/设计

目标：把模糊的业务诉求变成结构化的设计文档。

怎么做：调用 superpowers:brainstorming。产出一份 spec，通常保存在 docs/superpowers/specs/YYYY-MM-DD-<feature>-design.md。

关键输出检查点：spec 必须包含

• 问题陈述与业务边界
• 技术方案与决策点（每个决策都要有"为什么不选 B"的论证）
• 不变式清单（业务层硬约束）
• 失败模式分析（至少 4 种崩溃/失败场景）
• 风险表格
• 工作量评估

反模式：把 brainstorming 省掉，直接进实施。→ 后面的验证阶段会反复翻车。

✅ Exit Criteria — Phase 1 完成标准：

• Spec 文档已创建（docs/superpowers/specs/YYYY-MM-DD-<feature>-design.md）
• Spec 包含：问题陈述、技术方案、不变式清单、≥4 种失败模式、风险表格、工作量评估
• 每个决策点有"为什么不选备选方案"的论证
• 利益相关方已确认需求范围

Phase 1.5: Architecture Decision Review · 架构决策评审（高风险特性必做）

触发条件：设计中涉及以下任一项时必做——分布式锁方案、幂等机制设计、状态机转换图、跨服务数据一致性方案、在线 schema 迁移策略、共享 proto/model 变更。

目标：在动代码之前，把架构层面的关键决策显式验证一遍。设计阶段发现错误的代价是讨论成本；Phase 4 发现设计本身有误的代价是推翻 + 重写。

怎么做：对 spec 中每个关键技术决策，写一份 Architecture Decision Record (ADR)，回答：

1. 选了什么：具体方案（例：用 Redis + DB CAS 双保险实现幂等）
2. 备选方案是什么，为什么不选（每个备选都要有论证，不能只说"不合适"）
3. 选定方案的失败模式：列举 3 种最可能的失败场景（不是假设不会失败）
4. 不变式在设计层面能满足吗：逐条检查 Phase 1 的不变式清单，确认设计有对应的保证机制

典型输出：1-3 个 ADR，追加到 spec 文档末尾（不是单独文件，避免碎片化）。

何时可以跳过：特性是纯新增接口、无并发控制要求、无状态机、无跨服务数据写入时可跳过。

反模式：把 ADR 写成"我们选了 X"然后只写 X 的优点。ADR 的价值在于记录为什么不选备选方案，这是日后维护者最需要的信息。

✅ Exit Criteria — Phase 1.5 完成标准：

• 每个关键技术决策（分布式锁 / 幂等机制 / 状态机 / 一致性方案 / schema 迁移）有对应 ADR
• 每个 ADR 回答：选了什么、为什么不选备选方案、选定方案的失败模式
• Phase 1 的所有不变式均已确认在架构层有对应保证机制

Phase 2: Implementation Plan · 实施计划

目标：把 spec 拆成可独立执行、可独立验证的 task 清单。

怎么做：调用 superpowers:writing-plans。保存到 docs/superpowers/plans/YYYY-MM-DD-<feature>.md。

关键输出检查点：

• 每个 task 有明确文件 + 行号 + 代码示例
• 依赖关系清晰
• 验证方式具体（build / lint / test 命令）
• commit message 模板
• TDD 结构（先写失败测试再实现）
• 上线策略：全量 / feature flag / 灰度比例 / 双写切换窗口（任选其一，但必须明确）
• 回滚标准：什么指标异常时触发回滚？谁来决定？（不能留到上线时再想）
• 新增监控/告警：本 feature 上线后需要增加哪些 metric 和 alert？
• 运维 SOP 变化：DBA/SRE 需要做什么特殊操作？（如有）

反模式：task 里写 "TODO"、"稍后处理"、"类似 Task N"。→ 执行时会卡住或生成不一致代码。上线策略留白 → Phase 3 实施时没有 feature flag hook → 临时改代码上线。

✅ Exit Criteria — Phase 2 完成标准：

• 每个 task 有明确文件路径 + 行号 + 代码示例
• 每个 task 有具体验证命令（make build / make test / lint 等）
• TDD 结构：失败测试先于实现写入 plan
• 上线策略已明确（全量 / feature flag / 灰度 / 双写切换）
• 回滚标准已定义：什么指标触发回滚、谁来决定
• 新增监控/告警已列入 plan

Phase 3: Implementation · 实施

目标：按 plan 逐 task 落地，每个 task 有独立 review。

怎么做：调用 superpowers:subagent-driven-development。每个 task：

1. Dispatch implementer subagent（fresh context）
2. Implementer 自 review + commit
3. Dispatch spec compliance reviewer（验证是否建了要求的东西）
4. Dispatch code quality reviewer（验证代码质量）
5. 任何 reviewer 找到问题 → implementer 修 → re-review
6. 全通过 → 下一 task

关键心态：每个 task 独立的 fresh subagent 比一个大 context 连续写完更不容易犯错，因为没有累积偏见。

反模式：图省事把多个 task 合并给一个 subagent 写完 → 冗长 context → 关键约束被忘记。

✅ Exit Criteria — Phase 3 完成标准：

• Plan 中所有 task 标记完成，有对应 commit SHA
• 构建通过：make build（或项目等效命令）
• 测试通过：make test（或项目等效命令）
• 每个 task 经过 spec compliance review + code quality review
• 关键路径无遗留 TODO / stub

Phase 4: 🔥 Cross-Verification Rounds · 多轮交叉验证（本 skill 核心）

Phase 3 结束后，代码表面已经能工作。但是能编译 + 能过单测 ≠ 生产就绪。

这一阶段用 4 种独立视角 轮流审查代码，每种视角提供的信号彼此独立。详细操作见 references/cross-verification-techniques.md。

4.1 Systematic Debugging（内部自查）

视角：以 superpowers:systematic-debugging 为框架，从"假如此时出 bug，会是什么 bug"角度扫描自己的代码。

何时停：没有发现新的 critical issue，且已检查过所有声称的不变式。

典型产出：发现 1-3 个 pre-existing bug（不是本次引入但顺路发现的）。

4.2 Cold-Context Code Review（外部独立评审）⭐

这是本工作流最高价值的验证。启动一个 fresh reviewer agent，不给它设计文档，只给它：

• Feature 一句话目标
• 分支名 + 仓库路径
• "找 bug" 的 prompt

关键约束：DO NOT read the design document。这句话要写进 agent prompt。

为什么有效：设计文档代表"作者相信系统应该如何工作"。给 reviewer 看文档会让它被作者的盲点感染。Cold-context reviewer 只看代码实际做什么，反而能发现设计本身的漏洞。

典型产出：5-15 个 critical / high 级别的并发 / 一致性 / 幂等漏洞。

4.3 Behavior-Preservation Diff（master vs feature 行为差异）

视角：枚举 master 分支的所有副作用（DB 写、MQ 发布、RPC 调用、缓存写、日志告警），与 feature 分支逐条对比，回答"是否改变了原有业务逻辑"。

何时需要：当 feature 包含对"已有流程的改造"而不仅仅是"加新功能"时必须做。

典型产出：发现 2-5 处副作用的顺序/语义变化，每一处都需要确认是预期的。

4.4 Cross-Repo Impact Scan（跨仓库影响）

视角：识别本次 feature 是否影响其他仓库的代码行为，需不需要对应改动。

典型检查维度：

• MQ 消费者是否要改去重逻辑（feature 可能让重复消息变得更频繁）
• RPC 调用方是否要处理新错误码
• 共享 DB 表的读/写方是否要适应新状态
• 共享 proto / model 是否向后兼容

典型产出：识别 0-3 个其他仓库的影响点，大多数情况是"不需要改"但需要确认。

4.5 Business Invariant 矩阵（资金/状态机/库存/权限场景必做）

视角：列出 feature 必须保持的业务层硬约束（例如"一个业务单据最多产生一次资金变动"、"retry_count 单调递增"、"状态只能前进不倒退"），逐条验证代码在所有路径下都保持。

何时做：命中以下任一项时必做，与 4.2 并列（不是可选）：

• 资金流 / 支付 / 退款 / 余额变动
• 订单 / 库存状态机（有明确的状态转换约束）
• 库存扣减 / 预占 / 归还
• 权限授予 / 鉴权链路

其余场景（纯新增接口、无状态机语义）可跳过。

✅ Exit Criteria — Phase 4 完成标准：

• 4.1 完成：并发点 / 失败模式 / 幂等性 / 状态机 / 边界均已检查；所有发现已记录
• 4.2 完成：cold-context reviewer 未获得设计文档；所有 Critical/High 问题已记录
• 4.3 完成（如适用）：所有副作用已标注 ✅/🟢/🟡/🟠/🔴/🆕/❌
• 4.4 完成（如适用）：所有跨仓库影响已确认或 flagged
• 4.5 完成（如适用）：所有不变式逐条验证通过
• 所有发现已汇总为 issue 表（来源 / 严重度 / 位置 / 修复方向），准备交给 Phase 5

Phase 5: Fix Iteration · 迭代修复

目标：把 Phase 4 发现的问题修到干净。

怎么做：把所有发现的 issue 汇总成一个新的 plan（docs/superpowers/plans/YYYY-MM-DD-<feature>-review-fixes.md），再走一遍 writing-plans + subagent-driven-development。

关键原则：

• 按严重程度分批：Critical → High → Medium → Low
• 每个修复独立 commit，便于回滚
• 每个 Critical fix 必须有对应的自动化测试覆盖——没有测试的 fix 不算完成，因为下次迭代极容易 regression
• 所有 fix 合入后必须重跑一次 4.2 cold-context review（不能跳过）——修复本身可能引入新 bug；reviewer 可以把注意力集中在 diff 上，不需要重新审查全量代码
• 如果重跑 4.2 发现超过 2 个新 High 级别问题，停下来评估：是继续打补丁，还是重新考虑设计方案

常见量级：冷评审找到 10+ 个问题 → 修复 plan 10-15 个 task → 3-5 人日。

✅ Exit Criteria — Phase 5 完成标准：

• 所有 Critical 问题已修复，每个修复有对应自动化测试
• 所有 High 问题已修复，或有明确的接受风险说明（含批准人）
• 重跑 4.2 cold-context review：新发现 High 级别问题 < 2 个
• 每个修复有独立 commit（便于单独回滚）
• 回归测试套件全部通过

Phase 6: Careful Simplification · 谨慎简化

触发点：Phase 5 结束后，有时会发现代码"似乎有冗余"、"看起来可以简化"。

⚠️ 核心纪律：简化前必须验证所有隐藏假设。详见 references/anti-patterns.md 的"Simplification Trap"章节。

最容易中招的陷阱：

1. 多义字段陷阱：以为某字段只存一种语义，实际另一分支存的是别的。简化掉某个"看似冗余"的存储/缓存，结果数据错乱。

2. 重新推导陷阱：以为某值能从 DB 状态重建，实际有的值是局部变量快照，没有确定性 DB 来源。

3. 过度自信陷阱：被 review 的代码跑过压测、通过了所有验证，开发者有"这代码我非常理解了"的感觉。这种时候最容易判断失误。

正确做法：

• 简化前显式列出你要去掉的代码为什么存在
• 对每个原因，找代码证据证明它"真的可以不要了"
• 无法证明的，保留
• 简化后再跑一遍 cold-context review（新视角）确认没有退化

遇到翻车：果断 git revert，把教训写进 evolution log，不要试图"再简化一次"。

✅ Exit Criteria — Phase 6（如做了简化）：

• anti-patterns.md Simplification Checklist 所有项已勾选（有代码证据，不是"感觉可以"）
• 简化后运行了新一轮 cold-context review，无新 High 级别问题
• 简化失败并回滚时：教训已写入 evolution log

Phase 7: Doc Sync · 文档同步

目标：把最终代码状态回填到原设计文档。

为什么重要：

• Phase 5 的修复会让代码偏离原设计，如果不同步，文档会误导下一个维护者
• 每次偏离背后都有决策理由，这些理由是宝贵的知识资产，只在代码里找不到

怎么做：详见 references/doc-sync-playbook.md。核心原则：

1. 不要完全重写 spec，保留原始设计意图
2. 在偏离处标注"原设计 vs 实际实现"
3. 文档末尾追加 Implementation Evolution Log 章节，按时间线记录 Phase 1/2/3...
4. Plan 文档在每个 task 标注实际 commit SHA + 偏离点
5. 失败的简化尝试（Phase 6 回滚）一定要记录，教训比成功更有价值

不要：

• 只 commit 代码，不 commit 文档更新
• 默认"代码就是文档"——半年后没人能从代码反推决策
• 删掉原设计内容"因为跟实际不一致"——那是历史，是教训

✅ Exit Criteria — Phase 7 完成标准：

• Spec 文档中每处偏离原设计的地方已标注 > ⚠️ 原设计 vs 实际实现
• Spec 末尾追加了 Implementation Evolution Log（按时间线记录 Phase 1→7 关键决策）
• 失败的简化尝试（如有）已记录在 evolution log
• Plan 文档中每个 task 有实际 commit SHA + 偏离点标注
• 下游团队已收到接口 / 协议 / MQ 变更通知（如有）

Superpowers Integration · 与 Superpowers 生态的协作关系

本 skill 不重复造轮子，只做编排：

Getting Started · 启动本工作流

Trigger Modes · 两种触发方式

A. 用户显式触发（必须走）：用户说 /cross-verified-workflow <feature 需求>、"按交叉验证方式开发"、"走严谨工作流"、"用 cross-verified 工作流" 等。

B. 主动识别并建议：当用户的任务描述命中"适用场景"表中的任一领域（资金流、订单状态机、并发控制、数据迁移等），或用户提及"重构核心 X / 改造支付 / 幂等 / 分布式锁 / 跨服务新接口"等关键词，即使用户没有显式要求，也应主动提出：

我注意到这个任务涉及 <命中的领域>，属于 bug 代价较高的场景。我建议走一个更严谨的 cross-verified 工作流（brainstorm → plan → implement → 多轮交叉验证 → 修复 → 文档回填），会比普通做法多花约 40-50% 时间，但能把 critical bug 发现率从 ~40% 提到 ~95%。你要不要走这个流程？

或者如果你觉得成本太高，我们也可以走常规流程。

不要硬性拉人走工作流——告知价值和代价，让用户选择。但不要默默跳过让用户在高风险改动上裸奔。

Startup Steps · 启动步骤

1. 第一步：确认用户意图，如果需求还不够明确，先让用户澄清
2. 第二步：评估是否真的适合（参考"适用场景"章节）——不适合的话建议走更简单的流程
3. 第三步：如果合适，调用 Phase 1 (superpowers:brainstorming) 开始

Progress Tracking · 进度追踪

每个 Phase 完成后，明确标注进度：

✅ Phase 1   (Brainstorming) → docs/superpowers/specs/<file>.md
✅ Phase 1.5 (Arch Pre-flight) → ADR 追加到 spec（或 N/A）
✅ Phase 2   (Planning) → docs/superpowers/plans/<file>.md
⏳ Phase 3   (Implementation) → 进行中 (5/12 tasks done)
⬜ Phase 4a  (Systematic Debugging)
⬜ Phase 4b  (Cold-Context Review)
⬜ Phase 4c  (Diff Audit + Cross-Repo + Invariant，并行)
⬜ Phase 5   (Fix iteration)
⬜ Phase 6   (Careful simplification)
⬜ Phase 7   (Doc sync + 下游通知)

Common Rationalizations · 常见自我合理化

These are the thoughts that mean stop — you're about to skip something important. 以下想法出现时，立刻停下——你正在为跳过关键步骤找理由。

Reference Files · 关键参考文件

本 skill 主体保持精炼，细节在 references：

FAQ · 常见问题

Q：每个 Phase 都必须做吗？

A：Phase 1-3 + 7 必做。Phase 4 至少做 4.1 和 4.2。Phase 5-6 按需。4.3-4.5 视特性复杂度。

Q：Phase 4 的 4 轮验证要按顺序吗？

A：4.1 建议最先（自查成本低），4.2（cold-context）紧跟。4.3-4.5 可以并行 dispatch（独立的 subagent），能显著节省时间。

Q：发现新的一批 issue 时，Phase 4 要不要重新再来一遍？

A：修复后只需重点重验被改动的部分。不需要每次改动都完整跑 4 轮。但是在最终 merge 前，建议至少再跑一次 4.2（cold-context）确认没有新引入问题。

Q：这个工作流会不会太慢？

A：一个中等复杂度特性（~5 人日实施）用本工作流总共约 7-10 人日。多出的 40-50% 时间换来的是：Critical bug 发现率从典型的 40% 提升到 95%。对于关键特性，这个 ROI 是压倒性的正收益。

Q：前端/UI 特性能用这个工作流吗？

A：不建议。纯展示、纯 CRUD、无状态机语义的 UI 改动不值得这个成本。只有当前端改动涉及支付流程、订单确认、权限授权、关键数据提交这类场景时才考虑。