focused-fix

集中的な修正 — 機能の徹底的な修復

使用するタイミング

ユーザーが特定の機能／モジュール／領域の修正、デバッグ、または動作するようにすることを求めている場合に実行します。主なきっかけ：

• 「Xを動作するようにして」
• 「Y機能を修正して」
• 「Zモジュールが壊れている」
• 「［領域］に集中して」
• 「この機能を正しく動作させる必要がある」

これは、単一のバグをすばやく修正するためのものではありません（その場合は systematic-debugging を使用してください）。機能またはモジュール全体を体系的に修復する必要がある場合に使います。すべての依存関係をたどり、ログを読み、テストを確認し、依存関係グラフ全体を把握します。

digraph when_to_use {
    "User reports feature broken" [shape=diamond];
    "Single bug or symptom?" [shape=diamond];
    "Use systematic-debugging" [shape=box];
    "Entire feature/module needs repair?" [shape=diamond];
    "Use focused-fix" [shape=box];
    "Something else" [shape=box];

    "User reports feature broken" -> "Single bug or symptom?";
    "Single bug or symptom?" -> "Use systematic-debugging" [label="yes"];
    "Single bug or symptom?" -> "Entire feature/module needs repair?" [label="no"];
    "Entire feature/module needs repair?" -> "Use focused-fix" [label="yes"];
    "Entire feature/module needs repair?" -> "Something else" [label="no"];
}

鉄則

NO FIXES WITHOUT COMPLETING SCOPE → TRACE → DIAGNOSE FIRST

フェーズ 3 を完了していない場合、修正案を提案してはいけません。例外はありません。

これらのフェーズの文言に違反することは、集中的な修復の趣旨に違反することです。

手順 — 次の 5 つのフェーズを必ず順番に実行すること

digraph phases {
    rankdir=LR;
    SCOPE [shape=box, label="Phase 1\nSCOPE"];
    TRACE [shape=box, label="Phase 2\nTRACE"];
    DIAGNOSE [shape=box, label="Phase 3\nDIAGNOSE"];
    FIX [shape=box, label="Phase 4\nFIX"];
    VERIFY [shape=box, label="Phase 5\nVERIFY"];

    SCOPE -> TRACE -> DIAGNOSE -> FIX -> VERIFY;
    FIX -> DIAGNOSE [label="fix broke\nsomething else"];
    FIX -> ESCALATE [label="3+ fixes\ncreate new issues"];
    ESCALATE [shape=doubleoctagon, label="STOP\nQuestion Architecture\nDiscuss with User"];
}

フェーズ 1：範囲 — 機能の境界を把握する

コードに触れる前に、機能の全範囲を把握します。

1. まだ明確でない場合は、ユーザーに「どの機能／フォルダーに集中すればよいですか？」と尋ねます
2. この機能の主要なフォルダー／ファイルを特定します
3. そのフォルダー内のすべてのファイルを把握します。各ファイルを読み、目的を理解します
4. 機能マニフェストを作成します：

FEATURE SCOPE:
  Primary path: src/features/auth/
  Entry points: [files that are imported by other parts of the app]
  Internal files: [files only used within this feature]
  Total files: N
  Total lines: N

フェーズ 2：追跡 — すべての依存関係を把握する（内外）

この機能とコードベースの他の部分とのあらゆるつながりを追跡します。

内部（この機能がインポートするもの）：

1. 機能フォルダー内のすべてのファイルにあるインポート文ごとに：
   • インポート元までたどります
   • ソースファイルが存在することを確認します
   • インポートされたエンティティ（関数、型、コンポーネント）が存在し、エクスポートされていることを確認します
   • 型／シグネチャが機能の想定と一致するか確認します
2. 以下を確認します：
   • 使用されている環境変数（process.env、import.meta.env、os.environ などを grep します）
   • 参照されている設定ファイル
   • 使用されているデータベースモデル／スキーマ
   • 呼び出されている API エンドポイント
   • インポートされているサードパーティパッケージ

外部（この機能をインポートするもの）：

1. コードベース全体を検索し、この機能フォルダーからのインポートを探します
2. 使用箇所ごとに：
   • 実際に存在するエンティティをインポートしていることを確認します
   • 正しい API／インターフェースを使用しているか確認します
   • 非推奨のパターンを使用している使用箇所があれば記録します

出力形式：

DEPENDENCY MAP:
  Inbound (this feature depends on):
    src/lib/db.ts → used in auth/repository.ts (getUserById, createUser)
    src/lib/jwt.ts → used in auth/service.ts (signToken, verifyToken)
    @prisma/client → used in auth/repository.ts
    process.env.JWT_SECRET → used in auth/service.ts
    process.env.DATABASE_URL → used via prisma

  Outbound (depends on this feature):
    src/app/api/login/route.ts → imports { login } from auth/service
    src/app/api/register/route.ts → imports { register } from auth/service
    src/middleware.ts → imports { verifyToken } from auth/service

  Env vars required: JWT_SECRET, DATABASE_URL
  Config files: prisma/schema.prisma (User model)

フェーズ 3：診断 — すべての問題を見つける

問題がないか、体系的に確認します。以下のチェックをすべて実行してください。

コード品質：

• すべてのインポートが実在するファイル／エクスポートを参照している
• 機能内に循環依存がない
• 境界をまたいで型に一貫性がある（インターフェースに any がない）
• すべての非同期処理にエラー処理がある
• 既知の問題を示す TODO／FIXME／HACK コメントがない

実行時：

• 必要な環境変数がすべて設定されている（.env を確認）
• データベースのマイグレーションが最新である（該当する場合）
• API エンドポイントが想定どおりの形式を返す
• 設定可能にすべき値がハードコードされていない

テスト：

• この機能に関連するテストをすべて実行する：機能のフォルダーからのインポートを検索してテストを特定する
• 失敗をすべて、エラー出力全体とともに記録する
• テストカバレッジを確認する — テストされていないコードパスはないか

ログとエラー：

• ログファイル、エラーレポート、Sentry のようなエラートラッキングがないか検索する
• この機能に関する最近の変更について git log を確認する：git log --oneline -20 -- <feature-path>
• 最近のコミットが何かを壊していないか確認する：git log --oneline -5 --all -- <files that this feature depends on>

設定：

• この機能が依存する設定ファイルがすべて有効であることを確認する
• 開発環境と本番環境の設定に不一致がないか確認する
• サードパーティサービスの認証情報が有効であることを確認する（テスト可能な場合）

根本原因の確認： 見つかった重大な問題ごとに、修正リストに追加する前に根本原因を確認してください。

• 「Y であるため、X が根本原因だと考えます」と明確に述べる
• データ／制御フローをさかのぼって検証する — 表面的な症状をうのみにしない
• 問題が複数のコンポーネントにまたがる場合は、各境界に診断ログを追加し、どのレイヤーで失敗するかを特定する
• 複雑なバグの場合は、先に根本原因を調査する：障害を確実に再現し、エラーとスタックトレース全体を読み、最近の変更を確認し（git log、git diff）、仮説を一度に一つ立てて、可能な限り小さな変更で検証する。仮説が検証に耐えるまでは、バグを修正リストに追加しない。

リスクの分類： 各問題にリスクラベルを割り当てます。

リスク	基準
HIGH	パブリック API サーフェス／インターフェース契約の破壊／DB スキーマ／認証またはセキュリティロジック／広くインポートされるモジュール（呼び出し元が 3 件超）／git ホットスポット
MED	テストのある内部モジュール／共有ユーティリティ／実行時に影響する設定／変更された関数の内部呼び出し元
LOW	リーフモジュール／独立したファイル／テストのみの変更／呼び出し元のない単機能ヘルパー

出力形式：

DIAGNOSIS REPORT:
  Issues found: N

  CRITICAL:
    1. [HIGH] [file:line] — description of issue. Root cause: [confirmed explanation]
    2. [HIGH] [file:line] — description of issue. Root cause: [confirmed explanation]

  WARNINGS:
    1. [MED] [file:line] — description of issue
    2. [LOW] [file:line] — description of issue

  TESTS:
    Ran: N tests
    Passed: N
    Failed: N
    [list each failure with one-line summary]

フェーズ 4：修正 — すべてを体系的に修復する

次の順序を厳守して問題を修正します。

1. まず依存関係 — 壊れたインポート、不足しているパッケージ、誤ったバージョンを修正します
2. 次に型 — 機能の境界で発生している型の不一致を修正します
3. 次にロジック — 実際のビジネスロジックのバグを修正します
4. 次にテスト — 修正ごとにテストを修正または作成します
5. 最後に統合 — 利用側と連携して機能がエンドツーエンドで動作することを確認します

ルール：

• 一度に修正する問題は 1 つだけにします
• 修正のたびに、関連するテストを実行して動作を確認します
• 修正によって別の問題が発生した場合は、作業を停止して再評価します（診断に戻ります）
• 行った変更をすべて継続的に記録します
• 理由を明示せずに機能フォルダー外のコードを変更してはいけません
• リスクの高い問題から修正し、MED の前に MED、LOW の前に MED を修正します

エスカレーションルール — 3 ストライクのアーキテクチャチェック： このフェーズで 3 件以上の修正によって新たな問題（既存の問題ではないもの）が発生した場合は、直ちに作業を停止します。

このパターンは、バグが多いのではなく、アーキテクチャに問題があることを示しています。

• それぞれの修正によって、別の場所に新たな共有状態、結合、問題が見つかります
• 修正の実施に「大規模なリファクタリング」が必要です
• それぞれの修正によって、別の場所に新たな症状が発生します

対応： 修正を中止します。ユーザーに次のように伝えます：「3 件以上の修正が連鎖的に新たな問題を引き起こしました。これは、パッチを当てるのではなく、機能のアーキテクチャを見直す必要があることを示唆しています。調査で分かったことは次のとおりです：[summary]。症状への修正を続けますか、それとも構成の見直しについて話し合いますか？」

この話し合いを行うまでは、修正 #4 に着手してはいけません。

各修正後の出力：

FIX #1:
  File: auth/service.ts:45
  Issue: signToken called with wrong argument order
  Change: swapped (expiresIn, payload) to (payload, expiresIn)
  Test: auth.test.ts → PASSES

フェーズ 5：検証 — すべてが動作することを確認する

すべての修正を適用した後：

1. 機能フォルダー内のすべてのテストを実行します。1 つ残らず成功する必要があります
2. この機能をインポートするファイル内のすべてのテストを実行します。成功する必要があります
3. 利用可能な場合は、テストスイート全体を実行してリグレッションがないか確認します
4. 機能に UI がある場合は、手動での確認方法を説明します
5. 行った変更をすべて要約します

最終出力：

FOCUSED FIX COMPLETE:
  Feature: auth
  Files changed: 4
  Total fixes: 7
  Tests: 23/23 passing
  Regressions: 0

  Changes:
    1. auth/service.ts — fixed token signing argument order
    2. auth/repository.ts — added null check for user lookup
    3. auth/middleware.ts — fixed async error handling
    4. auth/types.ts — aligned UserResponse type with actual DB schema

  Consumers verified:
    - src/app/api/login/route.ts ✅
    - src/app/api/register/route.ts ✅
    - src/middleware.ts ✅

要注意の兆候 — 作業を停止し、現在のフェーズに戻る

次のように考えていることに気付いたら、フェーズを飛ばしています。

• 「バグは見つかった。すぐに修正しよう」→ 停止してください。依存関係をまだ追跡していません。
• 「スコープの確認はやりすぎだ。明らかにこのファイルだけだ」→ 停止してください。機能レベルの修正では、これは必ず誤りです。
• 「明らかなところを修正してから依存関係を整理しよう」→ 停止してください。根本原因を見落とします。
• 「ユーザーは X の修正を求めているから、X だけ見ればよい」→ 停止してください。機能には依存関係があります。
• 「テストに通ったから終わりだ」→ 停止してください。利用側のテストも実行しましたか？
• 「この件で環境変数を確認する必要はない」→ 停止してください。設定の問題がコードのバグに見えることがあります。
• 「あと 1 つ修正すれば大丈夫だ」（連鎖的な失敗が 2 件以上発生した後）→ 停止してください。エスカレーションしてください。
• 「診断レポートは省略しよう。修正点は明らかだ」→ 停止してください。記録に残してください。

これらはすべて、本来取り組むべきフェーズに戻る必要があることを意味します。

よくある自己正当化

言い訳	実際のところ
「機能は小さいから、5 つすべてのフェーズは必要ない」	小さな機能にも依存関係はあります。小さな機能ならフェーズ 1～2 は数分で済みます。必ず実施してください。
「このコードベースのことはもう分かっている」	知識は古くなります。記憶に頼らず、実際のインポートを追跡してください。
「ユーザーが求めているのはプロセスではなくスピードだ」	フェーズを省略すると手戻りが発生します。無駄に試行錯誤するより、体系的に進めるほうが速いです。
「壊れているのは 1 つのファイルだけだ」	本当に 1 つのファイルだけが壊れているなら、ユーザーは「機能を動作させて」ではなく「このバグを直して」と言うはずです。
「テストを修正したから、動作する」	利用側が壊れていてもテストは成功することがあります。フェーズ 5 を最後まで実施して確認してください。
「依存関係マップが大きすぎて追跡できない」	それなら、追跡せずに修正するには機能が大きすぎるということです。だからこそ依存関係マップが必要です。
「根本原因は明らかだから、確認する必要はない」	「明らかな」根本原因は、40% の確率で誤っています。根拠をもって確認してください。
「大規模な修正なら、連鎖的な失敗が 3 件起きても普通だ」	連鎖的な失敗が 3 件起きたということは、アーキテクチャの問題の症状にパッチを当てているということです。

アンチパターン — 絶対に行わないでください

アンチパターン	問題となる理由
すべての依存関係を洗い出す前にコードの修正を始める	根本原因を見落とし、いたちごっこのような修正を繰り返すことになります
ユーザーが言及したファイルだけを修正する	関連ファイルにも問題がある可能性が高いです
環境変数や設定を無視する	「コードのバグ」の多くは、実際には設定の問題です
テストの実行を省略する	テストを実行しなければ、修正を検証できません
理由を説明せずに機能フォルダーの外を変更する	予期しない副作用によってユーザーを混乱させます
機能の根本原因ではなく、利用側のファイルで症状を修正する	その場しのぎの修正は、次の利用側が現れたときに破綻します
検証テストを実行せずに「完了」と宣言する	テストされていない修正は、検証されていない修正です
すべての利用側を更新せずに公開 API を変更する	その機能に依存するすべてのものが壊れます

関連スキル

• self-eval（このリポジトリ、engineering/skills/self-eval）— 修正完了を報告する前に、フェーズ 5 の後で使用し、修正を正直に評価します
• incident-commander（このリポジトリ、engineering-team/skills/incident-commander、別のプラグイン）— 破損した機能がローカルの修復対象ではなく、本番環境で発生しているインシデントの場合はこちらを使用します
• 任意（インストールされている場合）： サードパーティの superpowers プラグインにある systematic-debugging と verification-before-completion のスキルは、フェーズ 3 の根本原因の特定手順とフェーズ 5 の確認事項を同様に扱います。このスキルでこれらを使う必要はありません。上記の手順だけで完結します。

クイックリファレンス

フェーズ	主な作業	出力
SCOPE	すべてのファイルを読み、エントリーポイントを洗い出す	機能マニフェスト
TRACE	入力方向と出力方向の依存関係を洗い出す	依存関係マップ
DIAGNOSE	コード、ランタイム、テスト、ログ、設定を確認する	診断レポート
FIX	依存関係 → 型 → ロジック → テスト → 統合の順に修正する	問題ごとの修正ログ
VERIFY	すべてのテストを実行し、利用側を確認して、要約する	完了レポート