グローバルルール: rules/archflow-rules.md に準拠します。 コードマッピング # ルール: 新しい行には常に max(existing #) + 1 を使用します。削除された番号を再利用しないでください。

モデル: まずは Sonnet を試してください。複雑なバグ(複数ファイル、フロー分析)の場合は Opus を使用します。

デバッグワークフロー

直接コード実行とドキュメント分析を組み合わせることで、バグを体系的に修正します。

対象範囲

Debug は E2E 問題 に対応し、ユニットテスト失敗には対応しません。

• ユニットテスト失敗 -> /test を使用
• E2E 問題(ユニットテストは成功しても機能が動作しない) -> /debug を使用

一般的な E2E 問題: BE-FE の不一致、API コントラクト違反、統合タイミング、環境固有のバグ。

ツール代替案

ツール	代替案
Read/Grep	ユーザーからファイルパスをリクエスト -> コピペを依頼
AskQuestion	「選択してください: 1) オプションA 2) オプションB 3) オプションC」形式
Shell	ユーザーにコマンド実行とアウトプット貼り付けを依頼

ドキュメント構造

docs/{serviceName}/
  ├── spec.md      # 入力(期待される動作)
  ├── arch-be.md   # 入力(フロー、コードマッピング)
  ├── arch-fe.md   # 入力(フロー、コードマッピング)
  └── trace.md     # 出力(このスキルが生成)

実行パス解決

アーキテクチャドキュメントから読み込み(テックスタックセクション):

フィールド	ソース	例
BE パス	arch-be.md -> Tech Stack -> BE Path	apps/auth-api
FE パス	arch-fe.md -> Tech Stack -> FE Path	apps/auth-web
実行コマンド(BE)	arch-be.md -> Tech Stack -> Run Command	uv run uvicorn main:app
実行コマンド(FE)	arch-fe.md -> Tech Stack -> Run Command	npm run dev

---

フェーズ 0: スキルエントリー

0-0. モデルと環境ガイダンス

必須ドキュメント (docs/{serviceName}/):

• spec.md(必須)、arch.md(必須)、trace.md(オプション - 存在しない場合は作成)

0-1. ドキュメント入力の収集

{"title":"バグ修正開始","questions":[{"id":"has_requirements","prompt":"要件ドキュメントをお持ちですか? (docs/{serviceName}/spec.md)","options":[{"id":"yes","label":"はい - @filepath で提供します"},{"id":"no","label":"いいえ - 持っていません"}]},{"id":"has_design","prompt":"設計ドキュメントをお持ちですか? (docs/{serviceName}/arch.md)","options":[{"id":"yes","label":"はい - @filepath で提供します"},{"id":"no","label":"いいえ - 持っていません"}]},{"id":"has_changelog","prompt":"変更ログをお持ちですか? (docs/{serviceName}/trace.md)","options":[{"id":"yes","label":"はい - @filepath で提供します"},{"id":"no","label":"いいえ - 完了時に作成します"}]}]}

処理:

• 要件または設計が いいえ -> 一般的なデバッグ(以下参照)
• 変更ログが いいえ -> フェーズ 3 で作成
• すべて はい -> ファイルパスをリクエスト -> フェーズ 1

一般的なデバッグ(ドキュメント不可時)

警告: ドキュメントなしで進行します。バグ修正はエラーログとコード分析のみを使用します。 期待される動作や設計フローの追跡を検証できません。

一般的なデバッグフロー:

1. エラーメッセージ/スタックトレースを分析
2. Grep + 関連コードを読む
3. 原因を推定 -> ユーザーに確認
4. 修正を実装
5. 変更ログ用に別の場所を指定

0-2. serviceName を推論

ファイルパスから: docs/alert/spec.md -> serviceName = "alert" -> 出力: docs/alert/trace.md

0-3. エラー情報を検証

収集: エラーメッセージ、スタックトレース、変数の状態(利用可能な場合)。

「エラーの状況を説明してください。エラーメッセージまたはスタックトレースがあれば、お知らせください。」

---

フェーズ 1: ドキュメント分析

1-1. ドキュメントを読み込み

ドキュメント	抽出内容
spec.md	期待される動作、正常なシナリオ
arch.md	フロー(呼び出し順序)、コードマッピング
trace.md	最近の変更(潜在的な原因)

1-2. エラーロケーションと設計フローを相互参照

エラーロケーション(スタックトレース)
  -> コードマッピングを確認(どのメソッド)
  -> 要件を確認(期待される動作)
  -> 不一致を特定

1-3. 分析結果を報告

## 分析結果

**エラーロケーション**: {ファイル}:{行} - {エラーメッセージ}
**設計上の動作**: {設計ドキュメントからのフロー}
**期待される動作**: {要件ドキュメントからの機能説明}
**最近の変更**: {関連する可能性のある最近の変更}
**推定原因**: {原因仮説}
**検証が必要な項目**: {追加確認が必要な項目}

ユーザーに確認: 「この分析は正しいですか? はい の場合、修正を進めます。」

---

フェーズ 2: バグ修正

2-1. 原因を確認

エラーロケーションのコードを読み、正確な問題箇所を検証し、修正方向を決定します。

2-2. 修正を実装

修正は以下に合わせます: 要件、設計フロー、既存コードスタイル。

2-3. E2E 検証(直接実行)

ステップ 1: アーキテクチャドキュメントから実行構成を読み込み(BE/FE パス、実行コマンド)。

ステップ 2: E2E 環境を起動(Shell):

cd {BE Path} && {BE Run Command} &
# サーバー準備完了を待機(ヘルスチェック)
cd {FE Path} && {FE Run Command}  # または: npm run test:e2e

ステップ 3: 修正を検証:

結果	アクション
成功(エラーなし)	フェーズ 3 に進む
同じエラー	再分析 -> 2-1 に戻る
新しいエラー	新しいエラーを分析 -> 2-1 に戻る

短いフィードバックループ: エラーを見る -> 修正 -> 再実行 -> すぐに修正を確認。

---

フェーズ 3: trace スキルを呼び出し(必須)

警告: 分析/修正完了後は trace スキルを呼び出す必要があります。

3-1. trace スキルを呼び出し

修正後: 「このセッションの結果を記録するために trace スキルを呼び出しています。」 またはガイド: 「分析完了。この内容を変更ログに記録しますか?」

3-1.5. trace 用のコードマッピング変更を準備

1. arch.md のコードマッピング表を読む(現在の # 番号を取得)
2. 変更を特定: 修正された行(MODIFY)、新しい行(ADD、# = last+1)、削除された行(DELETE)
3. 構造化形式で trace に渡す:

### コードマッピング変更
| # | 機能 | ファイル | クラス | メソッド | アクション | 変更内容 | 同期済み |
|---|------|--------|--------|---------|----------|--------|---------|
| 3 | 認証 | auth/svc.py | AuthSvc | validate() | null チェック追加 | MODIFY | [ ] |
| 6 | 認証 | auth/svc.py | AuthSvc | refresh() | トークンリフレッシュ | ADD | [ ] |

この構造化形式により、sync スキルは arch.md に直接変更を適用できます。

3-2. 結果タイプ別の記録

結果タイプ	記録内容
コード修正完了	症状、原因、修正内容、設計上の影響
外部原因を特定	症状、外部原因、推奨アクション
調査中/失敗	症状、調査内容、次のステップ

3-3. 呼び出されない場合

ユーザーは手動で呼び出すことができます: 「trace」または「write changelog」。同じセッションコンテキストが使用されます。

---

フェーズ 4: 完了報告

## バグ修正完了

### 分析/修正サマリー
| 項目 | 内容 |
|-----|------|
| 症状 | {元のバグ症状} |
| 原因 | {特定された原因} |
| 結果タイプ | コード修正 / 外部原因 / 調査中 |
| 修正ファイル | {ファイルリスト、または「なし」} |

### 検証方法(修正された場合)
1. {再現シナリオで検証}
2. {正常な動作を検証する方法}

### 再発防止(必須チェックリスト)
- [ ] テストを追加(該当する場合)
- [ ] ガード/検証ロジックを追加(該当する場合)
- [ ] ログ/モニタリングを追加(該当する場合)

**再発確率**: 高 / 中 / 低

警告: 変更ログに記録しましたか? 「trace」または「write changelog」を呼び出してください。 外部原因と調査失敗も記録する価値があります。

---

統合フロー

[spec] -> spec.md -> [arch] -> arch.md -> [build] -> 実装
  -> (バグが発生) -> [debug] -> 分析/修正
    -> [trace] -> trace.md -> (設計上の影響) -> [sync] -> arch.md

重要な注意事項

1. 実行時情報が役立つ - エラーメッセージとスタックトレースを提供すると効果が向上します
2. ドキュメント依存性 - ドキュメントは正確である必要があります。ドキュメント-実装の不一致がある場合は、まず sync を実行してください
3. 変更ログ管理 - すべてのバグ修正は trace に記録する必要があります
4. 複雑なバグ - 複数ファイルのバグ -> Opus を使用。未解決の場合は、分析 -> 確認 -> 再分析を繰り返してください