scoring-spec-complexity

name

scoring-spec-complexity

description

仕様書・PRD・Design Doc から「仕様の複雑度」と「検証コスト」の2つを定量化するスキル。仕様複雑度はビジネスルール数、条件分岐・例外パス数、状態遷移数、影響ドメイン/チーム数、外部連携、データ移行、後戻り可能性(可逆性)から、検証コストは検証可能性(受け入れ基準の有無と機械検証への委譲可能性)、影響範囲の把握コスト、変更の凝集性から、LLMが構造化JSONとして抽出し決定論的スクリプトで採点、低/中/高のバンドと複雑度/検証コストのドライバーを報告する。「この仕様の複雑度を測って」「認知負荷スコアを出して」「レビューコスト/検証コストを見積もって」「リファインメント前に複雑さを評価して」「このPRDをスコアリングして」等の依頼、または `/scoring-spec-complexity` で起動。補助入力としてソースコードが与えられた場合は抽出値のクロスチェックにも使う。仕様の見積もり・レビュー体制の議論、仕様の簡略化候補やテスト自動化候補の特定にも使うこと。

Spec Complexity Rubric（仕様複雑度・検証コストルーブリック）

仕様書・PRD・Design Doc から (1) 仕様的な複雑度 と (2) 検証コスト の2つを定量化し、チームのコミュニケーション（仕様の簡略化交渉、工数の議論、レビュー体制・テスト戦略の判断）のトリガーとなるレポートを生成するスキル。

2つのスコアは独立した意味を持つ:

• 仕様複雑度 = 作るものそのものの複雑さ（実装・設計の認知負荷）
• 検証コスト = 作ったものが正しいと確認するコスト（レビュー・テストの認知負荷）。設計書レビューが本質的に重いのは「正解が一意でない」「実行して確かめられない」ため判断依存になるからであり、この軸を複雑度と分けて可視化する。

仕様が単純でも検証コストが高い（受け入れ基準がなく目視レビュー依存）案件や、複雑だが検証は機械に委譲できる案件が存在するため、2軸で見る。

設計思想（なぜこの構成か）

• LLMは抽出、スクリプトは採点。 LLMが仕様書から決められたスキーマのJSON（中間表現）を抽出し、採点は scripts/score_complexity.py が決定論的に行う。こうすることで、(1) 採点基準が毎回ブレない、(2) 中間表現を人間がレビューでき、「LLMの誤解の複雑さ」を測ってしまう事故を防げる。
• スコアは会話のトリガーであり、SLAではない。 「10ptだから工数1.5倍」のような機械的換算は指標の目的化（Goodhartの法則）を招くため行わない。レポートは必ず「議論すべき論点」で締める。
• 疑似精度を避ける。 対外的なコミュニケーションは 低/中/高 の3バンドを主とし、点数はバンドの内部計算に留める。10ptと11ptの差に意味を持たせない。
• 相対評価である。 バンド閾値と重みは assets/rubric_config.json でチームが較正する前提。過去案件のアンカー（anchors.json）との比較を重視する。

ワークフロー

Step 1: 入力の確認

想定入力: 仕様書、PRD、Design Doc（テキスト、Markdown、添付ファイル）。補助入力としてソースコード（リポジトリ、ファイル群）が与えられることもある。

• 仕様が複数機能を含む場合、機能単位（開発アイテム単位）で分割して個別に採点するか確認する。粒度が大きすぎるスコアは議論に使えない。
• 仕様がまだ曖昧な場合でも中断しない。曖昧さ自体を open_questions として抽出し、レポートで指摘する（曖昧さの発見はこのスキルの副次的価値）。

Step 2: 構造化抽出（LLMの仕事）

references/extraction-guide.md を読み、カウント規則に従って仕様から以下を抽出し、extraction JSON を作成する。スキーマの詳細と数え方の規則（何を1件と数えるか、重複の扱い、迷った場合の判断）は必ず extraction-guide.md に従うこと。自己流で数えると再現性が失われる。

仕様複雑度の7軸:

1. business_rules — ビジネスルール（ドメイン上の制約・計算規則・ポリシー）のリスト
2. exception_paths — 条件分岐・例外パス（正常系から外れるフロー）のリスト
3. state_transitions — 状態遷移（状態機械の遷移エッジ）のリスト
4. affected_domains — 影響するドメイン・チームのリスト
5. external_integrations — 外部連携のリスト（各項目に new_connection: 初連携かどうか）
6. data_migration — データ移行の種別（none / additive / transform / destructive）
7. reversibility — 後戻り可能性（easy / flag_guarded / hard / irreversible）

検証コストの3軸（verification オブジェクト配下）:

1. acceptance_criteria — 受け入れ基準のリスト。各項目に checkability（automatable: テストコード化・機械検証できる / manual: 手順は明確だが人間の実施が必要 / judgment: 正解が一意でなく人の判断に依存）と、どのビジネスルール・例外パスを検証するかの covers（IDの配列）を付ける。スクリプトはここからカバレッジ（検証手段のないルールの割合）と機械委譲可能性を算出する。
2. impact_surfaces — 変更が波及する既存機能・コンポーネントのリスト。各項目に documented（依存関係がドキュメント・型・テストで追跡可能か、それとも暗黙知か）を付ける。
3. concerns — この開発アイテムに含まれる独立した関心事のリスト（例:「失効ドメインロジック」「通知」「管理画面」）。関心事が混ざると理解コストは加算ではなく乗算的に増えるため、スクリプトは相互作用ペア数 n(n-1)/2 で採点する。

各項目には必ず 仕様書内の根拠（原文の該当箇所の要約や引用位置） を evidence として付ける。根拠のないカウントは水増しの温床になる。受け入れ基準が仕様書に存在しない場合は acceptance_criteria を空配列にする（それ自体が検証コスト高のシグナルとして採点される）。勝手に受け入れ基準を創作して埋めてはならない。

抽出JSONは extraction.json としてファイルに保存し、採点前に必ずユーザーに提示して内容の妥当性を確認できるようにする（インラインで要約を見せる）。中間表現のレビューがこのスキルの品質を担保する。

Step 3: ソースコードによるクロスチェック（コードが与えられた場合のみ）

ソースコードが補助入力として与えられた場合、抽出値の裏取りを行う:

• 状態遷移: enum / ステータス定数 / 状態機械ライブラリの定義を grep し、仕様から抽出した状態・遷移と突き合わせる
• 例外パス: 該当機能の分岐（例外クラス、エラーコード定義、early return）を確認する
• 外部連携: HTTPクライアント、SDK import、API設定を確認する
• 影響範囲: 変更対象のモジュールの呼び出し元・共有モデルの利用箇所を検索し、仕様に書かれていない impact_surfaces がないか確認する。既存テストの有無も確認し、documented の判定材料にする
• 検証可能性: 該当領域に既存の自動テストがあるかを確認する（既存テストが薄い領域は automatable と書かれていても実際の委譲コストが高い）

仕様とコードで数が食い違う場合は どちらかに合わせて黙って修正せず、extraction JSON の code_crosscheck に差分として記録し、レポートで「仕様に書かれていない状態がコードに3つ存在する」のように指摘する。この差分こそ暗黙知・ドキュメント欠落のシグナルであり、チームのドメイン知識蓄積の起点になる。

Step 4: 決定論的採点（スクリプトの仕事）

python3 scripts/score_complexity.py extraction.json \
  --config assets/rubric_config.json \
  --anchors anchors.json \
  --format markdown -o report.md

• --config: 重み・バンド閾値の設定。ユーザーのプロジェクトに較正済み config があればそれを使い、なければ assets/rubric_config.json（デフォルト）を使う。
• --anchors: 過去案件のアンカーファイル（任意）。ユーザーのリポジトリや作業ディレクトリに anchors.json があれば渡す。なければ省略。
• 出力は JSON / Markdown を選択可能。スクリプトは 仕様複雑度と検証コストの2つのスコア・バンド、軸ごとの内訳、上位ドライバー、2軸を組み合わせた総合所見、アンカー比較を出力する。
• 旧形式（verification セクションのない extraction JSON）を渡した場合、検証コストは未採点となり警告が出る。

スクリプトの採点ロジックを LLM が暗算で代替してはならない。必ずスクリプトを実行する。

Step 5: レポートの提示

スクリプト出力をベースに、以下を含むレポートをユーザーに提示する:

1. 2つのバンドとスコア — 「仕様複雑度: 高（14pt）/ 検証コスト: 中（5pt）」のように。バンドを主、点数を従とする。
2. 総合所見 — 2軸の組み合わせに応じた重点。特に「仕様複雑度: 高 × 検証コスト: 高」は最も危険な象限（複雑なものを目視で検証する状態）であり、着手前の対処を最優先で促す。
3. 複雑度ドライバーと検証コストドライバー — それぞれスコアを押し上げている上位項目と、その根拠。
4. 簡略化・検証改善の候補 — ドライバーに対応する具体的な問い。例:「例外パスのうち『期限切れポイントの按分返還』は初期リリースで必要か？」「judgment依存の受け入れ基準3件のうち、期待値を固定して automatable にできるものはないか？」「関心事が3つ混ざっている。通知部分を別PRに分離できないか？」
5. 仕様とコードの差分（クロスチェックを行った場合）
6. 未解決の曖昧さ（open_questions）
7. アンカー比較（あれば）
8. 注意書き — スコアは見積もりの機械的換算やSLA・個人評価に使わないこと。

レポートは議論の材料であり結論ではない。「このスコアを受けて何を話すべきか」を必ず提案して締める（分割・簡略化・受け入れ基準の整備・テスト自動化・レビュー体制強化・スパイク実施など）。

アンカー運用と較正

初回導入時や「アンカーを作りたい」と言われた場合は references/calibration.md を読むこと。過去案件のバックフィル採点によるアンカー作成手順、四半期ごとの実績（リードタイム・手戻り・レビュー往復）との突き合わせ、config 改訂の指針を記載している。検証コスト側は「レビュー往復回数」「QA工数」「リリース後の不具合発見」との突き合わせで較正する。

してはいけないこと

• extraction JSON を作らずに直接点数を宣言する（再現性が失われる）
• スクリプトを実行せずに暗算で採点する
• 根拠（evidence）のないカウントを含める
• 仕様書に存在しない受け入れ基準を創作して acceptance_criteria を埋める
• スコアから工数を自動換算して提示する
• 10ptと11ptの差のような細かい差分に意味づけをする
• 仕様とコードの食い違いを黙って片方に寄せる