troubleshooting-regression

リグレッションのトラブルシューティング

フレームワークが古い状態になっている、応答しなくなっている、またはリグレッションが発生しているように見え、決定的な診断と修正の検証が必要な場合に、このスキルを使用します。

使用するタイミング

• エージェントの起動後に Claude のデバッグセッションが停止します。
• フックが想定外にアクションをブロックします。
• メモリ／検索／トークン節約の適用に一貫性がないように見えます。
• 再現可能な再現手順と検証の実行が必要なリグレッションが発生しています。

絶対原則

次の項目を満たさずに、リグレッションが修正されたと判断してはいけません。

1. 再現可能なトリガープロンプト
2. pnpm trace:query のトレース証拠
3. デバッグログのフック／ツールの証拠
4. 変更範囲を対象とするテストの合格

ワークフロー

1. セッションとログのソースを特定します。
2. まずトレースクエリを実行します（pnpm trace:query --trace-id <traceId> --compact --since <ISO-8601> --limit 200）。
3. 重要度の高いエラーを抽出します（既知の MCP 認証／起動時のノイズは除外します）。
4. 各エラーを担当するフック／モジュールに関連付けます。
5. 最小限のコードパスを修正し、リグレッションテストを追加または更新します。
6. 対象を絞ったチェック（テストと、変更したファイルの lint／format）を実行します。
7. デバッグプロンプトを再実行し、エラーの種類が再現しなくなったことを確認します。
8. 得られた知見や問題をメモリに記録します。

証拠のモデル

• 信頼できる情報源：C:\\Users\\<user>\\.claude\\debug\\*.txt
• トレースの信頼できる情報源：同じインシデント期間の pnpm trace:query の出力
• フィルター：外部 MCP のトランスポート／認証ノイズは無視し、フレームワーク／ランタイムエラーは残します
• エラーの種類：
  • ルーティング／タスクのライフサイクル
  • メモリ／検索／トークン節約のガードレール
  • フックのコントラクト／スキーマ違反
  • ワークフローのフェーズ／冪等性の失敗

コマンド一覧

主なラッパー：

node .claude/skills/troubleshooting-regression/scripts/main.cjs --prompt "search the codebase for any issues or bugs"
pnpm trace:query --trace-id <traceId> --compact --since <ISO-8601> --limit 200

任意の直接ログ分析：

node .claude/skills/troubleshooting-regression/scripts/main.cjs --log-path "C:\\Users\\<user>\\.claude\\debug\\<session>.txt"

出力の仕様

• ok：ブール値
• logPath：分析対象のログパス
• findings[]：重要度と担当ファイルのヒントを含む、正規化された調査結果
• nextActions[]：具体的な修正／検証アクション

関連する成果物

• ワークフロー：.claude/workflows/troubleshooting-regression-skill-workflow.md
• ツール：.claude/tools/troubleshooting-regression/troubleshooting-regression.cjs
• コマンド：.claude/commands/troubleshooting-regression.md

例

# Analyze latest log
node .claude/skills/troubleshooting-regression/scripts/main.cjs --mode quick

# Analyze specific log and fail when critical findings exist
node .claude/skills/troubleshooting-regression/scripts/main.cjs --log-path "<path>" --strict

絶対原則

1. 変更を加える前に、必ず証拠（ログ、トレース ID、エラーメッセージ）を収集します
2. 失敗を決定的に再現する前に、フックやルーティングの設定を絶対に変更しません
3. 変更のたびにリグレッションテストスイート全体を実行して、修正を必ず検証します
4. 正確な失敗シナリオがエンドツーエンドで成功するまで、リグレッションを解決済みにしては絶対にいけません
5. 今後の参照のため、根本原因、修正、検証の証拠を issues.md に必ず記録します

アンチパターン

アンチパターン	失敗する理由	正しいアプローチ
失敗を再現せずに変更する	変更が正しい問題を修正したか検証できません	まず決定的に再現し、その後に修正します
根本原因を分析せずに症状だけを修正する	条件が変わると問題が再発します	5 Whys を使って根本原因までたどります
修正後にリグレッションスイートを省略する	修正によって他の機能が壊れる可能性があります	変更のたびにテストスイート全体を実行します
修正を記録しない	今後のセッションで同じリグレッションが再発します	根本原因、修正、検証を issues.md に記録します
エンドツーエンド検証なしに解決済みにする	統合上の問題を見逃します	正確な失敗経路をエンドツーエンドで検証します

メモリプロトコル

開始前：

cat .claude/context/memory/learnings.md

完了後：

• リグレッションのパターン → .claude/context/memory/learnings.md
• 未解決の欠陥またはリスク → .claude/context/memory/issues.md
• 新しい適用方針の決定 → .claude/context/memory/decisions.md

中断されることを想定してください。コンテキストがリセットされることがあります。メモリに記録されていなければ、起きていないのと同じです。