Crowi Spec Review

Crowi Spec Review (敵対的・実コード裏取りの spec 検証)

核心原則

spec は、それを書いた本人(= あなた)が鵜呑みにすると診断を外す。 独立した複数観点で 実コードに当てて検証し、結論で spec を是正する。コメントを返すだけでは終わらない。

実績: editor-preview-reliability spec は「desync したクライアント Y.Doc が空 save で本文消失」を 中核に据えていたが、3観点レビューが実コード(Hocuspocus 内部 + yjs 実測)で中核診断の誤り (save はサーバ doc を読む / save 前に必ず seed 済み / CRDT 上空クライアントは消せない)を捕捉し、 真の経路(楽観ロック欠如 + yjsState 空上書き)へ是正できた。鵜呑みレビューなら通過していた。

いつ使う

• 実装(/crowi-feature)前に、correctness critical な spec を検証したい(データ消失 / 並行 / 認証 / セキュリティ / トランザクション境界 / 移行)。
• ユーザーが「この spec で大丈夫? ちゃんとチェックして」と言った。
• spec の根本原因 / 修正の十分性に自信が持てない。
• 使わない: trivial/small で機械的な spec、すでに実装が始まっている(その場合は /code-review)。

非交渉の3ルール(これを外すと検証にならない)

1. 実コード裏取り必須 — spec の各主張を「成立 / 過大 / 誤り」で判定し、file:line を引く。 spec の言い分・記憶・推測で確定しない。必要なら依存ライブラリの実装 (node_modules) や実測まで。
2. 独立レンズ — レビューは並列・互いにブラインドの異なるレンズで走らせる(同じ観点を 複数回ではなく、根本原因 / 修正の red-team / 網羅+アーキ / implementation-ready)。 redundancy では拾えない失敗を拾う。 レンズの定義・実行は review-document.workflow.js が正本(下記)— prose に複製しない。
3. 結論で spec を是正 — 出力はコメント集ではない。是正済み spec(改訂注記を残さず、最初から そう書かれていたかのようにクリーンに書き直す。誤り→是正の二重記載は実装者を混乱させる)か、 問題なければ「検証済み」と明示。是正内容の説明は spec ではなく会話側で返す。 ユーザーには verdict(OK / 要是正 + 何を)を一言で返す。

手順(薄い入口 — レビュー本体は crowi-design Workflow B)

この skill は入口で、レビューの実行系は crowi-design の reviewOnly Workflow に集約 されている(spec レンズは Codex ×4 + critical 固定の Claude ×1。 Codex 不可時は各レンズが Claude に fail-open)。

1. spec(.feature-state/specs/<id>.md)を読み、scope と criticality(消失/並行/認証 が 絡むか)を掴む。これは main がやる。
2. reviewOnly Workflow を起動。spec-review は本質的に correctness-critical 用途なので critical: true 固定(= Codex 4 レンズ + Claude red-team レンズ 1 本):

   Copy code
   Workflow({ scriptPath: '.claude/skills/crowi-design/review-document.workflow.js',
              args: { reviewOnly: true, docPath: '.feature-state/specs/<id>.md',
                      outputType: 'spec', slug: '<id>', critical: true,
                      round: <毎回変える値> } })
   

   返り値 = { status: 'OK'|'ISSUES'|'DEGRADED', blocking[], preexisting[], findings[], reviewStats, reviewSummary, codexFallbacks }。findings[] は {lens, category: 'mustFix'|'carryForward'|'preexisting', text} の dedup 済み構造化指摘 (blocking[] は互換のため残る)。status: 'DEGRADED' のとき、この round の verdict を採用してはならない — 独立した codex 判定を経なかった lens (Claude fallback + 死亡) が閾値以上で、OK でも ISSUES でもその判定は縮退している。codex 復旧後に再実行するか、縮退を承知で使う場合のみ acceptFallback: true を付けて再起動する (spec を approved に上げる根拠には使わない)。reviewStats (lensesPlanned / viaFallback / deadLenses) で縮退の内訳が見える。再実行するときは args.round を必ず変える — Workflow は同一 {scriptPath, args} をセッション全体でキャッシュするので、同じ引数のまま呼び直すと codex が復旧していても DEGRADED がそのまま返る(crowi-design のキャッシュ規則と同じ)。
3. 統合(レビューのレビュー): blocking を main が判断する。レビュアーは過大主張も するので、怪しい指摘は自分で実コードに当てて再確認してから採用する。
4. 是正: 採用した blocking を反映して spec をクリーンに書き直す(改訂注記・ before/after は spec に残さない。「何を・なぜ」是正したかは会話側の報告で返す)。 v2 spec を編集するときは先に status: draft / implementation_ready: false へ戻す。 是正後、provisional に approved/true へ変更して .claude/skills/_shared/validate-implementation-spec.sh を実行する。green なら確定し、 red なら draft/false へ戻す。問題なければ現状 marker を維持する。ユーザーへ verdict を報告し、 codexFallbacks が非空なら 「レンズ X は Claude fallback で実行」も明記する。

観点(定義の正本は review-document.workflow.js の spec 用 lenses)

よくある失敗

• rubber-stamp(「読んだ感じ良さそう」で通す)→ 誤診断を見逃す。実コードに当てるまで OK と言わない。
• 観点が独立していない(同じ問いを3回)→ redundancy では拾えない。レンズを変える。
• file:line を引かない→ 主張が検証されていない。根拠を必須に。
• コードでなく prose をレビュー→ spec の文章だけ読んで満足。実装・依存・実測まで。
• コメントで終える→ 是正された spec を残さない。結論は「直した spec」か明示の verdict。
• レビュアーを鵜呑み→ レビュアーも過大主張する。怪しい指摘は自分で再確認(レビューのレビュー)。
• fallback を黙る→ どのレンズが Claude fallback で走ったかを報告に書かないと、 cross-model 検証が効いていたかをユーザーが判断できない。

crowi-feature との関係

correctness critical な spec は、crowi-spec-review で是正 → /crowi-feature で実装の順。 spec が正しくなければ planner/implementer は正しい間違いを丁寧に作る。レビューは実装前に効く。