バグを体系的に修正

バグはアウトソーシングプロジェクトにおいて最も時間を消費する中断です。クライアントのバグレポートには通常、スクリーンショット、曖昧な説明、そして締め切りが含まれています。QAのリグレッションシートには20行のエントリーがありながら、スタックトレースは一切ありません。本番インシデントでは、クライアントの朝のスタンドアップ前に修正が必要です。Sun Agent Kitは、バリデーションメッセージの単純なタイポから決済ワーカーの競合状態まで、あらゆるバグを追跡可能な修正を伴う構造化された調査に変えます。

概要

目標: 根本原因を特定し、修正を実装し、隣接する動作を壊すことなく検証する
所要時間: バグ1件あたり5〜20分（手動では1〜4時間）
使用エージェント: debugger、tester、reviewer
コマンド: /sk:fix、/sk:fix --quick、/sk:debug、/sk:test

前提条件

• Sun Agent Kitがインストール済みで、プロジェクトがインデックス済みであること（複雑なコードベースでは少なくとも1回 /sk:scout を実行済み）
• 再現可能なバグの説明 — エラーメッセージ、再現手順、または失敗するテストケース
• テストスイートが整備されていること（本番コードを修正する前に強く推奨）
• 本番問題の場合はログへのアクセス（/sk:debug はログファイルを直接読み込めます）

ステップバイステップのワークフロー

ステップ1：シンプルで明確なバグに対するクイック修正

明確な説明のあるバグ — バリデーションエラー、間違ったステータスコード、エラーメッセージのタイポ — に対して使用します:

/sk:fix --quick "the POST /api/users endpoint returns 500 instead of 422 when the email field is missing from the request body"

処理内容: エージェントが以下を実行します：

1. 影響を受けるエンドポイントのルートハンドラーと関連コントローラーを特定
2. 根本原因を診断 — 通常はバリデーションの欠落、間違ったステータスコード、未処理のパス
3. 最小限の修正を適用し、正しい動作を確認

ステップ2：複雑なバグに対する深い修正

複数のファイルやモジュールにまたがる根本原因分析が必要なバグに対して使用します:

/sk:fix "users report that after resetting their password, they're immediately logged out when they try to sign in with the new password — this is intermittent, happens about 1 in 5 times"

処理内容: エージェントが以下を実行します：

1. 関連するサービスファイルを読み込み、パスワードリセットフロー全体をトレース
2. 根本原因を特定 — 通常は競合状態、セッション無効化の欠落、またはトークンライフサイクルの問題
3. 影響を受けるすべてのファイル（サービス、ミドルウェア、マイグレーション）に修正を実装
4. バグの再発を防ぐためのリグレッションテストを作成

ステップ3：ログから本番エラーをデバッグする

/sk:debug "production logs show: UnhandledPromiseRejection: Cannot read properties of undefined (reading 'stripe_customer_id') — this started at 14:32 UTC yesterday, affecting the checkout flow"

処理内容: エージェントが以下を実行します：

1. 参照されるプロパティまたは変数のすべてのコールサイトを検索
2. HTTPリクエストから障害発生行までのクラッシュパスをトレース
3. トリガーを特定 — 多くの場合、制約を変更した最近のマイグレーションまたはデプロイ
4. 必要な具体的なコード変更を含む修正推奨事項を作成

ステップ4：CI/CDパイプラインの失敗を修正する

/sk:fix "GitHub Actions build is failing on the test step — error: ECONNREFUSED 127.0.0.1:5432 in the auth integration tests"

処理内容: エージェントが以下を実行します：

1. CI設定ファイルを読み込み、失敗しているステップを特定
2. 根本原因を診断 — 多くの場合はタイミングの問題、サービス依存関係の欠落、または環境の不一致
3. CI設定ファイルに直接修正を適用

ステップ5：UIバグを修正する（表示 + 機能）

/sk:fix "the mobile nav menu doesn't close when a user taps outside of it on iOS Safari — it just stays open"

処理内容: エージェントが以下を実行します：

1. 関連するコンポーネントを特定し、イベントハンドラーのロジックをトレース
2. 根本原因を診断 — 多くの場合はブラウザ固有のイベント処理の問題
3. 適切なフォールバックパターンを含むクロスブラウザ互換の修正を適用

完全な実例：QAが最新テストラウンドから5件のバグを報告

シナリオ: 金曜日の午後、QAからクライアントプロジェクトのリグレッションテストで見つかった5件のバグのスプレッドシートが届きます。スプリントレビューは月曜日です。バグの内容は、些細なものから微妙な競合状態まで様々です。

QAのバグリスト:

1. POST /api/orders が不正なペイロードで JSONではなくHTML エラーページを返す
2. パスワードリセットメールがGmailアドレスに送信されない（Yahooは正常）
3. EUロケールのユーザーに対してカート合計に誤った通貨記号が表示される
4. 注文確認ページがSafari 16でJSエラーによりクラッシュする
5. StripeのWebhookが時々2回発火し、重複した注文レコードが作成される

金曜日の午後 — 5件すべてを修正する:

# バグ1: 些細なバリデーション/レスポンスフォーマットの問題
/sk:fix --quick "POST /api/orders returns HTML error page instead of JSON 400 when request body is malformed"

# バグ2: メール配信 — 調査が必要
/sk:fix "password reset emails not delivered to Gmail addresses — Yahoo works fine. Check SendGrid config, DKIM, and any email filtering happening in the notification service"

# バグ3: i18n表示バグ
/sk:fix --quick "cart total shows wrong currency symbol for EU locale users — should be € not $ — check the currency formatting utility and locale detection"

# バグ4: SafariのJSクラッシュ
/sk:debug "order confirmation page crashes on Safari 16 with: TypeError: undefined is not an object (evaluating 'e.dataset.orderId'). Find the component and the Safari-incompatible pattern."
# その後、デバッグレポートから修正を適用する:
/sk:fix --quick "apply the fix recommended in the debug report for the Safari 16 crash on the order confirmation page"

# バグ5: べき等性 — 最も難しいもの
/sk:fix "Stripe webhook fires twice causing duplicate order records. Implement idempotency key checking so the same webhook event can never create two orders"

# すべての修正後にテストスイート全体を実行する
/sk:test "run all tests and flag any regressions from today's fixes"

結果: 5件のバグすべてが修正され、テストは合格し、月曜日のスプリントレビューに向けたクリーンなコミットが準備できています。バグ5（べき等性）の修正だけで、手動では調査と実装に半日かかっていたでしょう。

時間の比較

ベストプラクティス

1. 明確な説明のあるバグには —quick を使用する ✅

バグを1文で説明でき、どのエンドポイントやコンポーネントが影響を受けているかが分かっている場合、--quick は深い分析をスキップして修正を直接適用します。調査が必要なバグには完全な /sk:fix を使用してください。

2. 修正プロンプトに再現手順を含める ✅

「カートの合計が間違っている」では浅い修正しか生まれません。「ユーザーの Accept-Language ヘッダーが de-DE で、カートに3件以上のアイテムがある場合に、カートの合計が€ではなく$を表示する」のように記述すると、エージェントは正確な障害個所を特定できます。

3. バグのバッチ修正後に常に /sk:test を実行する ✅

個々の修正は独立していますが、5件のバグを順番に修正すると、リグレッションが生じることがあります。バッチ後のテスト実行は、レビュー前にクロスカッティングの問題を検出します。

4. 差分を読まずに修正を適用する ❌

エージェントは変更内容を表示します。必ず読んでください。誤った関数を編集する4行の修正は、さらに悪いバグを生み出す可能性があります。1分のレビューがクライアントへのエスカレーションを防ぎます。

5. 原因ではなく症状を修正するよう /sk:fix に頼む ❌

「500を消してください」は、エラーが処理されるのではなく飲み込まれる結果を招くことがあります。正しい動作を説明してください：「メールフィールドが欠けている場合にJSONエラー本文を含む422を返す」。

トラブルシューティング

問題：/sk:fix —quick が変更を加えてもバグが再現される

解決策: クイックモードは最短経路を取ります。完全モードに切り替えてください：--quick なしの /sk:fix "..." で、より深い調査とより包括的な修正を実行します。

問題：/sk:debug がログのスニペットから根本原因を見つけられない

解決策: エラーメッセージだけでなく、完全なスタックトレースを貼り付けてください。スタックトレースにはファイル名と行番号が含まれており、デバッグエージェントがそれを使用して実行パスをトレースします。

問題：修正によってTypeScriptエラーが発生する

解決策: /sk:fix --quick "fix the TypeScript error introduced in src/services/billing.ts:89 — expected string, got string | null" を実行してください。エージェントは自分自身の副作用を解決できます。

問題：バグがサードパーティの統合にあり、ソースコードがリポジトリにない

解決策: /sk:ask を使用して統合の境界を理解し、自分のコードのアダプター層を修正してください。エージェントはサードパーティのコードを変更できませんが、それを呼び出す方法を修正することはできます。

次のステップ

• 新機能を追加 — バグのバックログをクリアした後、フィーチャー作業に移行する
• 既存コードベースの引き継ぎ — バグだらけのプロジェクトを引き継いだ場合は、まず完全なオリエンテーションから始める
• 認証を実装 — 多くのバグレポートは認証のエッジケースに起因している

重要なポイント: 5件のバグがあるQAシートは、1スプリント全体ではなく金曜日の午後でクリアすべきです。/sk:fix は数時間ではなく数分で根本原因と検証済みの修正を提供します。