bugfix

すべてのバグ修正で、再現・診断・修正・検証のループに従ってください。

譲れないルール：

1. 再現手順を用意するか、再現が不可能な理由を明確に記録するまでは、修正コードを書かないでください。
2. 症状ではなく、根本原因を修正してください。
3. 変更は最小限にし、バグの範囲に限定してください。
4. パッチを適用する前に、関連するフレームワークのリファレンスを読み込んでください。
5. バグのカテゴリを分類した後、references/bug-playbooks.md を読み込んでください。
6. 修正を通すためにテストを弱めてはいけません。

バグ修正

入力

• $request：任意のバグの説明、失敗するシナリオ、または検出結果のセレクター

目標

確認済みの不具合を、再現、診断、対象を絞った実装、回帰チェックに裏付けられた、最小限かつ正確な変更で解決します。

ステップ 0：フレームワークを特定し、リファレンスを読み込む

バグを診断する前に、バグがあるファイルのインポート、プロジェクトの依存関係ファイル、ファイル拡張子から、言語とフレームワークを特定します。

シグナル	フレームワーク	リファレンスファイル
package.json に express がある	Express.js	references/expressjs.md
package.json に react があり、JSX/TSX ファイルがある	React	references/react.md
package.json に react-native または expo がある	React Native	references/react-native.md
package.json に next がある	Next.js	references/nextjs.md
package.json に fastify がある	Fastify	references/fastify.md
package.json に hono がある	Hono	references/hono.md
package.json に @remix-run/react がある	Remix	references/remix.md
bun.lockb または bunfig.toml がある	Bun	references/bun.md
composer.json に laravel/framework がある	Laravel	references/laravel.md
go.mod がある	Go	references/golang.md
go.mod に github.com/gin-gonic/gin がある	Go + Gin	references/go-gin.md
go.mod に github.com/labstack/echo がある	Go + Echo	references/go-echo.md
go.mod に github.com/gofiber/fiber がある	Go + Fiber	references/go-fiber.md
.swift ファイルまたは Package.swift がある	Swift	references/swift.md
Cargo.toml があり、.rs ファイルがある	Rust	references/rust.md
Cargo.toml に axum がある	Rust + Axum	references/rust-axum.md
Cargo.toml に actix-web がある	Rust + Actix Web	references/rust-actix.md
Cargo.toml に rocket がある	Rust + Rocket	references/rust-rocket.md
.ts/.js ファイルがある（特定のフレームワークがない場合）	Node.js/TypeScript	references/nodejs-typescript.md

リファレンスの読み込みルール：

1. 必ず基本言語のリファレンスを読み込んでください（例：Node.js では nodejs-typescript.md、Go では golang.md、Rust では rust.md）。
2. 基本リファレンスにフレームワーク固有のリファレンスを重ねて読み込んでください（例：Express では nodejs-typescript.md と expressjs.md の両方、Axum では rust.md と rust-axum.md の両方を読み込みます）。
3. React Native には React が含まれるため、react.md と react-native.md の両方を読み込んでください。
4. Next.js と Remix には React が含まれるため、react.md とフレームワークのリファレンスファイルの両方を読み込んでください。
5. Go のフレームワークには Go のリファレンスを重ねてください。golang.md とフレームワークのリファレンスファイルの両方を読み込みます。
6. Rust のフレームワークには Rust のリファレンスを重ねてください。rust.md とフレームワークのリファレンスファイルの両方を読み込みます。
7. フレームワークが明確でない場合は、言語レベルのリファレンスを使用してください。

成功基準：診断を始める前に、関連する言語とフレームワークのリファレンスが読み込まれていること。

ステップ 1：バグを解析して選択する

次のいずれかの入力を受け付けます。

• 検証済みの /find-bugs の検出結果
• ユーザーからのバグ報告
• 失敗するテスト
• 作業中に発生した実行時クラッシュまたはビルドの失敗

次の情報を抽出します。

• 症状
• 発生条件
• 期待される動作
• 該当する可能性が高いファイルまたはサブシステム
• 提供されている場合は重要度
• 単独のバグか、複数のバグをまとめたものか

/find-bugs の出力については、次のとおりにします。

• ユーザーが修正を依頼した検出結果のみを抽出します
• 重要度と依存関係に基づいて並べ替えます
• 同じファイルまたは関数に関わる検出結果をまとめます

依頼内容で確認済みのバグが説明されていない場合は、手当たり次第に修正せず、作業を中断して確認を求めます。

成功基準：再現して修正するのに十分なほど、バグの範囲が明確になっています。

ステップ 2：まずバグを再現する

影響を受けるコードの近くに、関連する最小限のテストを作成するか、既存のものを特定します。

必須の手順：

1. 具体的なバグのシナリオに対して、失敗するテストを書く
2. その再現テストだけを実行する
3. 想定した理由で失敗することを確認する
4. 修正を直接保護する場合に限り、密接に関連するエッジケースのテストを追加する

再現できない場合は、次を確認します。

• 環境に関する前提
• 正確な発生条件となる入力
• 報告以降にコードがすでに変更されていないか
• バグが断続的に発生するものか、並行処理に関係するものか
• それでも再現できない場合は作業を中断し、試した内容を報告する

成功基準：失敗する再現テストがあるか、再現できない理由を正確に説明できます。

ステップ 3：根本原因を診断する

周辺のローカルコンテキストをすべて確認します。

• 影響を受ける関数またはモジュール
• 直接の呼び出し元
• 直接の依存関係
• 近くにあるテスト
• 関連する型定義または契約

次に、以下を行います。

1. エントリーポイントから障害発生箇所までのデータフローを追跡する
2. 処理の流れの中で、最初に破綻した前提を特定する
3. 影響範囲を把握する：
   • 呼び出し元
   • インポート元
   • 依存するテスト
   • 影響を受けるパブリック API または契約
4. バグのカテゴリを分類する

バグのカテゴリ：

• インジェクション
• XSS
• 認証／認可
• Null 安全性
• 競合状態
• 境界条件／オフバイワン
• 非同期／Promise
• 型安全性
• リソースリーク
• ロジック／ビジネスルール

分類後、references/bug-playbooks.md を読み、該当するセクションを使用します。

成功基準：根本原因を一文で説明でき、適切な修正プレイブックを特定できます。

ステップ 4：最小限の修正を計画する

根本原因を修正するための、最小限の変更を設計します。

編集前に、次を確認します。

• 変更が必要なファイル
• 影響を受ける呼び出し元または依存先
• パブリック API または型が変更されるか
• 多層防御による対策が必要か
• 複数のバグをまとめて修正する場合、依存関係の順に分割すべきか

重要な修正の場合は、パッチを適用する前に簡潔な計画を提示します。

• バグ
• 根本原因
• カテゴリ／プレイブック
• 影響範囲
• 再現テスト
• 変更予定のファイル

成功基準：計画した変更はリファクタリングより明らかに小さく、根本原因に直接結び付いています。

ステップ 5：修正を実装する

実装ルール：

• バグを解決する最小限の範囲にパッチを適用する
• references/bug-playbooks.md にある該当カテゴリのプレイブックに従う
• 読み込まれたフレームワークのリファレンスに従う
• 整理、スタイルの修正、機能追加を混在させない
• コードを確認せずに /find-bugs の提案をそのままコピーしない

論理的な編集ごとに、次を行います。

1. 再現テストを実行する
2. 修正が成功に近づいていることを確認する
3. 修正によって呼び出し元または契約が変わる場合は、依存関係の連鎖を最後まで対応する

成功基準：適切な理由で、再現テストが失敗から成功に変わります。

ステップ 6：リグレッションがないか検証する

再現テストが成功した後、次を行います。

1. 影響を受けるテスト範囲を実行する
2. 影響範囲がモジュールまたはパッケージの境界を越える場合は、より広範囲のテストを実行する
3. 型チェックまたは同等の静的検証を実行する
4. references/bug-playbooks.md にあるカテゴリ固有の検証チェックリストを実行する
5. デバッグ用の成果物や、意図しない整理の変更がないか確認する

修正によって無関係な失敗が発生した場合は、範囲を広げる前に作業を中断して再診断します。

成功基準：修正がローカルで成功し、カテゴリ固有のチェックに合格しており、明らかなリグレッションが発生していません。

ステップ 7：複数のバグをまとめて慎重に対処する

複数の問題が見つかった場合：

• ファイル、関数、依存関係ごとに分類します
• 依存関係のある問題は順番に修正します
• 独立した問題は重要度の高いものから修正します
• 最後にまとめてではなく、各グループの修正後に検証を実行します
• 1つの修正で別の問題も解決した場合は、両方に個別の修正が必要だったかのようにせず、その旨を明記します

成功基準：一連の作業をレビューしやすい状態に保ち、リグレッションを早期に検出できます。

ステップ 8：結果を報告する

修正したバグごとに、次の項目を報告します：

• 根本原因
• カテゴリ／使用したプレイブック
• 変更したファイル
• 再現テスト
• 実施した検証
• 残存リスクや延期したフォローアップ

次の項目を含む概要を記載します：

• 修正したバグ
• 追加または更新したテスト
• 変更したファイル
• より広範な検証に合格したかどうか

バグを修正しなかった場合は、その理由を具体的に示します：

• 再現できなかった
• 情報が不十分だった
• 根本原因が上流にある
• 修正にはバグ修正の範囲を超えるアーキテクチャの変更が必要

成功基準：別のエンジニアが、何を、なぜその方法で修正し、どのように検証したかを理解できます。

ガードレール

• 再現手順がない状態で修正してはいけません。ただし、再現が不可能な理由を明記する場合を除きます。
• 根本原因が残ったまま、症状だけを修正してはいけません。
• テストを弱めたり、スキップしたりしてはいけません。
• リファクタリングとバグ修正を混在させてはいけません。
• バグ修正を機能追加にすり替えてはいけません。
• 実際の修正を完了させず、広範な TODO を残してはいけません。

リファレンスを読み込むタイミング

• フレームワークのリファレンス： ステップ 0 で、該当する言語とフレームワークのドキュメントを読み込みます。
• references/bug-playbooks.md： ステップ 3 でバグを分類した後に読み込みます。

出力の要件

実行内容と証拠に焦点を絞って回答します：

1. 修正するバグ
2. そのバグを再現した方法
3. 判明した根本原因
4. 変更内容
5. 修正の検証方法