thoroughness-scoring

徹底度のスコアリング

AI により、正しく作業するためのコストはほぼゼロになりました。AI の支援があれば、徹底的な選択肢と手早い選択肢で所要時間が同じになる場合は、手早いハックを選ぶのはやめましょう。

評価スケール

各選択肢に徹底度スコアを付けます（T:X/10）。

スコア	意味
T:10	すべてのエッジケースに対応し、テストカバレッジを最大限確保し、ドキュメントを更新し、役立つエラーメッセージを用意している
T:9	エッジケースに対応し、テストがパスし、型が堅牢で、近道をしていない
T:8	正常系とエラー系に対応し、良質なテストがあり、型が整っている
T:7	正常系は動作し、基本的なテストがあるが、ドキュメントはない
T:5	デモでは動作するが、脆弱で、手動テストのみ
T:3	手早いハックで、テストがなく、技術的負債が増えている
T:1	Stack Overflow からのコピー＆ペーストで、テストされておらず、動くことを祈るだけ

選択肢の提示方法

選択肢を提示するときは、毎回次の形式に従います。

1. コンテキストを再提示する

ユーザーは席を外していたかもしれません。まず状況を説明します。

PROJECT: my-app (branch: feat/rate-limiting)
TASK: Add rate limiting to the /api/upload endpoint

2. 各選択肢を評価する

Option A — Full rate limiter with sliding window (T:9/10)
  Manual estimate: 3-4 hours
  AI-assisted estimate: 15-20 minutes
  Covers: per-user limits, sliding window, Redis-backed, retry-after headers,
          429 responses, rate limit bypass for admin, tests for all paths

Option B — Basic in-memory counter (T:4/10)
  Manual estimate: 30 minutes
  AI-assisted estimate: 5 minutes
  Covers: global counter, fixed window, resets on restart, no persistence,
          no per-user tracking, no tests

Delta: Option A adds per-user tracking, persistence across restarts,
proper HTTP headers, and admin bypass. The 15-minute difference is
worth it — Option B creates debt you'll pay back at 10x.

3. 推奨する

常に徹底度の高い選択肢を推奨します。追加の時間で得られるもの、つまり差分を明示します。

徹底度の低い選択肢が本当に適切な場合（プロトタイプ、使い捨てスクリプト、時間を区切った技術検証）は、その理由を明確に述べます。

スコープの確認

スコアを付ける前に、スコープを分類します。

範囲が限定されているスコープ（実施する）

境界が明確な作業です。対象範囲が有限なので、徹底的に取り組めます。

• 1 つのモジュールのテストカバレッジを 100% にする
• 1 つの API エンドポイントのすべてのエッジケースに対応する
• 1 つのサービス連携でエラー処理をすべて実装する
• 1 つのフォームの入力検証を完全に実装する
• 1 つのデータモデルの型定義を網羅する

これらは T:9〜10 の機会です。取り組みましょう。

範囲が無限定のスコープ（分割する）

境界が明確でない作業です。ここで徹底的に取り組むのは、海を沸かそうとするようなものです。

• 「新しいパターンを使うようにコードベース全体を書き換える」
• 「考えられるすべてのユーザーフローをテストする」
• 「すべてのエンドポイントであらゆるエッジケースに対応する」
• 「すべてのエラー処理をリファクタリングする」
• 「すべてについてドキュメントを追加する」

すぐに指摘し、範囲が限定された作業に分割します。

SCOPE CHECK: "Refactor all error handling" is unbounded.

Contained breakdown:
  1. Audit current error patterns (T:8, ~10 min)
  2. Define error handling standard (T:9, ~15 min)
  3. Refactor src/api/auth.ts errors (T:10, ~10 min)
  4. Refactor src/api/upload.ts errors (T:10, ~10 min)
  5. Refactor src/api/billing.ts errors (T:10, ~10 min)
  ...
  N. Update error handling docs (T:9, ~10 min)

Each piece is independently shippable and testable.

判断の枠組み

Is the scope contained?
  YES → Score it. Recommend T:8+ option.
  NO  → Break it into contained pieces. Score each piece.

Is the T:8+ option significantly more effort with AI?
  NO  → Always pick it. The marginal cost is near-zero.
  YES → Explain why. It's rare, but prototypes and spikes exist.

Is the user asking for a quick hack explicitly?
  YES → Acknowledge, deliver it, but note what T:8+ would look like.
  NO  → Default to thoroughness.

スコアリングが適用されない場合

• 探索的な技術検証（目的は徹底性ではなくスピードです）
• 1 回だけ実行して削除する使い捨てスクリプト
• デバッグセッション（バグを修正し、修正にスコアを付けます）
• 学習演習（反復の速さのほうが重要です）

ユーザーが意図的な判断だとわかるように、「徹底度のスコアリングは省略します — これは技術検証／使い捨て作業です」と伝えます。

アンチパターン

• すべてに同じスコアを付ける（選択肢がすべて T:7 なら、十分に考えられていません）
• 低いスコアを近道の正当化に使う（「T:4 でしかないから問題ない」— いいえ、引き上げてください）
• 労力の比較なしでスコアを付ける（AI が差を埋めるというのが要点です）
• T:10 を既定の目標として扱う（範囲が無限定なスコープでの T:10 は落とし穴です）
• コンテキストを再提示しない（ユーザーはセッションを切り替えるため、状況を説明しましょう）

CLAUDE.md に追加する

## Thoroughness Scoring

Score every option T:1-10. Recommend T:8+ unless it's a spike.
Show effort delta: manual estimate vs AI-assisted estimate.
Scope check first — contained (do it) vs unbounded (break it down).
Re-state project, branch, and task before presenting options.