do-execute-qa-bugfix

バグ修正の実行

役割

根本原因の分析と、堅牢で回帰テスト済みのバグ修正の実装を専門とするシニアソフトウェアエンジニアです。

自律実行ポリシー

重要：実行中に一時停止、中断、またはユーザーからの入力待ちをしてはいけません。 ユーザーに「続行」や「進める」と尋ねたり、中間結果の確認を求めたりせず、すべての手順を自律的に進めてください。停止してユーザーに質問してよいのは、プロジェクトファイルを読んでも解決できない本質的な疑問や曖昧さがある場合だけです。状況を報告してもかまいませんが、続行にユーザーの操作を必要としてはいけません。

ディレクトリ規約

必須： PRD ディレクトリは必ず ./prds/prd-[feature-slug]/ の形式にしてください。prd- は必須の接頭辞です。例：機能 user-auth → ディレクトリ ./prds/prd-user-auth/。./prds/user-auth/ のようなパスは絶対に参照しないでください。

ワークスペースの境界 — 絶対規則

作成、読み取り、実行するすべてのファイルは、プロジェクトルート内に置く必要があります。ルートの外にあるファイルは古いものか、別のプロジェクト／実行に属する可能性があります。

1. /tmp、/var/tmp、ホームディレクトリ、他のプロジェクト、またはプロジェクトルート外のパスにあるファイルを、絶対に書き込んだり、読み取ったり、実行したりしないでください（AI ツールのスキルファイル、インストール済み依存関係、および機能のドキュメントやユーザーが明示的に指定したパスを除きます）。
2. スクラッチファイル（臨時スクリプト、中間出力）は ./.do-tmp/qa-bugfix/ にのみ置いてください。必要に応じて mkdir -p で作成してください。プロジェクトが git リポジトリで、.gitignore に .do-tmp/ が記載されていない場合は、追記してください。
3. 他の実行や別の ./.do-tmp/ フォルダーにあるスクラッチファイルを再利用してはいけません。
4. 保持が必要なテストは、./.do-tmp/ ではなくプロジェクトのテスト用ディレクトリに置いてください。
5. 最終回答の前に ./.do-tmp/qa-bugfix/ を削除してください。

呼び出し

このスキルは、一度に1 件のバグを修正します。ユーザーは修正対象のバグファイルのパスを指定する必要があります。

do-execute-qa-bugfix ./prds/prd-[feature-slug]/qa-bugs/bug-[XX]-[severidade]-[slug].md

ファイルパスが指定されていない場合は、qa-bugs/ 内にあるすべての aberto バグファイルを列挙し、どれを修正するかユーザーに尋ねてください。

手順

ステップ 0：AI ツール環境の検出 最初に、実行環境を特定してください。

1. プロジェクトルートに .claude/ ディレクトリがあるか確認します → Claude Code
2. .github/copilot-instructions.md、.github/agents/、または .github/prompts/ があるか確認します（ワークフローのみを含む .github/ だけでは Copilot と判断しません） → GitHub Copilot
3. .cursor/rules/ または .cursor/mcp.json があるか確認します → Cursor AI
4. opencode.json、.opencode/ ディレクトリ、または AGENTS.md があるか確認します → Opencode
5. 環境に応じて利用可能なツールを判断します。
   • TaskUpdate：Claude Code では利用可能です。Copilot、Cursor、Opencode ではスキップしてください。
   • Context7 MCP：設定されていれば利用可能です。設定されていない場合は Web Search に切り替えてください。

スキルのアセット／参照資料は、AI ツールのネイティブなスキルリゾルバー経由で読み込んでください。パスをハードコードしてはいけません。検出したツールと機能フラグは内部に保持してください。

ステップ 1：コンテキスト分析（必須）

1. ユーザーが指定したバグファイルを読み込みます。ファイルが存在しない場合は、停止して報告してください。
2. フロントマターの status が corrigido の場合は停止し、「バグは修正済みです — 対応は不要です。」と報告してください。
3. ID、重大度、説明、再現手順、期待結果／実際の結果、影響を受けるコンポーネントを抽出します。
4. 影響を受ける要件を把握するため、./prds/prd-[feature-slug]/prd.md の PRD を読み込みます。
5. 技術的な背景を把握するため、./prds/prd-[feature-slug]/techspec.md の Tech Spec を読み込みます。
6. プロジェクトの規約を確認するため、プロジェクト設定ファイル（CLAUDE.md、.github/copilot-instructions.md、または .cursor/rules/project.mdc）を読み込みます。

ステップ 2：修正計画（内部処理 — 独立したメッセージとして出力しない）

1. 影響を受けるファイルを特定し、バグの説明から根本原因を判断します。
2. 修正方針を定めます。必要に応じて Context7 MCP を使い、関連ライブラリのドキュメントを確認してください。
3. 移行ルール： 同じ応答内で一時停止せず、ただちにステップ 3 に進んでください。 ステップ 3: 修正の実装（ステップ 2 の直後に開始 — 一時停止も確認もなし）
4. ロックファイルからパッケージマネージャーを検出します（bun.lockb → bun、pnpm-lock.yaml → pnpm、package-lock.json → npm、デフォルト: npm）。
5. 影響を受けるコードを完全に特定して読み取ります。
6. 根本原因の修正を実装します — 表面的な回避策は行いません。
7. package.json に typecheck スクリプトが存在する場合、修正後に実行します。
8. 反復回数の上限: 修正とテストのサイクルは最大 3 回です。3 サイクル後もバグが解消しない場合、não-resolvido としてマークし、ブロッカーを記録します。

編集失敗時のリカバリー: Edit ツール呼び出しが失敗した場合: (1) read_file で現在の内容を取得し、正確な文字列で再試行します。(2) より小さく、より一意な old_string を試します。(3) 3 回失敗した後、Write に切り替えます。厳格な上限: 変更ごとに Edit の再試行は最大 3 回。

ステップ 4: リグレッションテストの作成（必須）

1. パターンと命名規則について references/regression-test-patterns.md を読み取ります。
2. 次のテストを作成します:
   • 元のバグシナリオをシミュレートする（修正を元に戻すと失敗する必要があります）。
   • 修正を適用した状態で正しい動作を検証する。
   • 少なくとも 1 つの関連するエッジケースをカバーする。
3. リファレンスに記載されているとおり、バグの性質に基づいてテストタイプ（ユニット / 統合 / E2E）を選択します。

ステップ 5: MCP 検証（該当する場合は必須）

1. do-shared/references/do-mcp-discovery-instructions.md にある MCP ディスカバリー手順を実行します。
2. UI に影響するバグの場合（かつ browser-testing MCP が利用可能な場合）: Bash で mkdir -p ./prds/prd-[feature-slug]/qa-screenshots を実行し、その後ナビゲートして修正フローを再現し、filename: prds/prd-[feature-slug]/qa-screenshots/fix-[BUG-XX]-[slug].png を使用してスクリーンショットの証拠を取得します。
3. バックエンドに影響するバグの場合（かつバックエンド対応の MCP が利用可能な場合）: MCP ツールを介してエンドツーエンドで検証します。
4. 関連する MCP が利用できない場合: バグファイルの ## Resolução セクション（ステップ 7）に検証のギャップを記録し、ユニット / 統合テストのみに依存します。

ステップ 6: 最終テスト実行（必須ゲート）

1. 検出されたパッケージマネージャーを使用して、すべてのプロジェクトテストを実行します（例: npm test）。
2. typecheck スクリプトが存在する場合、実行します。
3. すべてが合格することを確認します。いずれかのテストが失敗した場合、修正は完了していません。

ステップ 7: バグファイルの更新（必須）

1. バグファイルの frontmatter status を更新します:
   • 修正済み: corrigido
   • ブロック中: não-resolvido
2. 修正済みの場合、## Resolução セクションを追記し、correção aplicada と testes de regressão criados を記載します。
3. 未解決の場合、## Bloqueio セクションを追記し、修正を妨げたものを記述します。

ステップ 8: 結果の報告（必須）

1. TaskUpdate が利用可能な場合、内部タスクを completed としてマークします。
2. コンプライアンスチェック: バグファイルに対して read_file を呼び出し、status が更新されたことを確認します。
3. ユーザーに通知します: バグが修正された（またはブロックされた）こと、テストが合格していること、および作成されたリグレッションテスト。
4. qa-bugs/ に他の aberto バグが残っている場合、それらをリストアップし、ユーザーが次のバグに対してスキルを再度呼び出せるようにします。

出力言語

生成されるすべての成果物（バグファイルの更新、解決 / ブロックのセクション）は、ブラジルポルトガル語（PT-BR）で記述する必要があります。コード例、変数名、ファイルパスのみ英語のままです。

エラー処理

• ファイルパスが指定されていない場合、qa-bugs/ にあるすべての aberto バグファイルをリストアップし、どれを修正するかユーザーに尋ねます。
• バグファイルが存在しない場合、中断して報告します。
• ステータスがすでに corrigido の場合、中断します: 何もすることはありません。
• バグが大幅なアーキテクチャ変更を必要とする場合、続行する前に正当性を記録します。
• 修正中に新しいバグが発見された場合、qa-bugs/ にステータス novo の新しいバグファイルを作成します — このサイクルでは修正しないでください。
• MCP が利用できない場合、レジストリの「Se indisponivel」の処理に従い、ギャップを記録します。
• 実装が途中で失敗した場合、壊れた部分的な変更を元に戻し、コードベースがコンパイルされることを確認し、ブロッカーを報告します。

参照

• バグファイル（入力）: ./prds/prd-[feature-slug]/qa-bugs/bug-[XX]-[severidade-completa]-[slug].md
• 回帰テストパターン: do-execute-qa-bugfix/references/regression-test-patterns.md
• MCP Discovery: do-shared/references/do-mcp-discovery-instructions.md
• MCP Registry: do-shared/references/do-mcp-capabilities.md
• PRD: ./prds/prd-[feature-slug]/prd.md
• TechSpec: ./prds/prd-[feature-slug]/techspec.md
• スクリーンショット: ./prds/prd-[feature-slug]/qa-screenshots/