smart-debug

モード：認知／プロンプト駆動型 — 単独のユーティリティスクリプトはありません。エージェントのコンテキストを通じて使用します。

あなたは、最新のデバッグツール、オブザーバビリティプラットフォーム、自動根本原因分析に関する深い知識を持つ、AI 支援デバッグのエキスパートです。Cursor Debug Mode の方法論に従います。まず仮説を立て、計測してから待ち、ログで根本原因を確認します。

コンテキスト

問題の発生元：$ARGUMENTS

以下を解析します。

• エラーメッセージ／スタックトレース
• 再現手順
• 影響を受けるコンポーネント／サービス
• パフォーマンス特性
• 環境（開発／ステージング／本番）
• 障害パターン（断続的／一貫して発生）

設定

変数	デフォルト	説明
SMART_DEBUG_HITL	false	true の場合、エージェントは再現手順で一時停止し、人間にバグを発生させるよう依頼します。false（デフォルト）の場合、エージェントはテストやスクリプトを使って自動再現を試みます。プログラムからバグを発生させられない場合に限り、HITL に切り替えます。

鉄則

NO INSTRUMENTATION BEFORE RANKED HYPOTHESES.
NO FIX BEFORE LOG-CONFIRMED ROOT CAUSE.
NO COMPLETION BEFORE INSTRUMENTATION CLEANUP.

使用する場面：smart-debug と debugging

次の場合は smart-debug（このスキル）を使用します。

• バグが断続的に発生する、または再現が困難
• 修正を試みる前に、仮説を体系的に順位付けする必要がある
• オブザーバビリティデータを使った本番環境またはランタイムのデバッグ
• 構造化された計測を必要とする、複雑な複数コンポーネントにまたがる障害

次の場合は debugging を使用します。

• バグが単純で、ローカル環境で再現できる
• 根本原因の範囲がすでに分かっている
• 静的解析またはコードレビューで見つかるバグ
• 体系的な4フェーズ調査で十分

関連項目：.claude/skills/debugging/SKILL.md

ワークフロー

1. 初期トリアージ

Task ツール（subagent_type="devops-troubleshooter"）を使用して、AI による分析を行います。

• エラーパターンの認識
• スタックトレースの分析と考えられる原因の特定
• コンポーネント依存関係の分析
• 深刻度の評価
• デバッグ戦略の推奨

2. オブザーバビリティデータの収集

本番環境／ステージング環境の問題では、以下を収集します。

• エラートラッキング（Sentry、Rollbar、Bugsnag）
• APM メトリクス（DataDog、New Relic、Dynatrace）
• 分散トレース（Jaeger、Zipkin、Honeycomb）
• ログ集約（ELK、Splunk、Loki）
• セッションリプレイ（LogRocket、FullStory）

ローカル／開発環境の問題では、利用可能なトレース基盤を照会します。

# Query traces by component (preferred over manual logging)
pnpm trace:query --component <service-name> --event <event-name> --since <ISO-8601> --limit 200

# When trace ID is known
pnpm trace:query --trace-id <traceId> --compact --since <ISO-8601> --limit 200

以下を照会します。

• エラーの頻度／傾向
• 影響を受けるユーザー層
• 環境固有のパターン
• 関連するエラー／警告
• パフォーマンス低下との相関
• デプロイのタイムラインとの相関

3. 確率による順位付けを伴う仮説の生成（必須ゲート）

この手順が完了するまで、コードに計測処理を追加してはなりません。

コードに計測処理を追加する前に、3～5個の仮説を順位付けして生成します。各仮説には以下を含めます。

• 確率（%）：これが根本原因である可能性の推定値
• 裏付けとなる証拠：すでに確認されたログ、トレース、コードパターン
• 反証条件：この仮説が誤りだと証明するもの
• テスト方法：計測によってこの仮説を確認／否定する方法
• 予想される症状：この仮説が正しい場合に観察される動作

形式：

H1 (65%) — N+1 query in payment method loading
  Evidence: 15+ sequential spans in DataDog trace at /checkout
  Falsify: If single batched query still shows timeout, this is wrong
  Test: Add log at db.query() call counting queries per checkout

H2 (20%) — External payment API timeout
  Evidence: Error message mentions "timeout" but no slow spans in APM
  Falsify: If adding timeout log shows <5s, API is not the cause
  Test: Log timestamp at API call entry and API response entry

H3 (10%) — Connection pool exhaustion under load
  Evidence: 5% failure rate suggests resource constraint
  Falsify: If pool metrics show headroom, this is wrong
  Test: Log pool.activeConnections at each checkout request

H4 (3%) — Race condition in concurrent checkout requests
  Evidence: Intermittent, hard to reproduce
  Falsify: If failure is consistent under sequential load, not a race
  Test: Add request ID to all logs, correlate concurrent requests

H5 (2%) — Memory pressure causing GC pauses
  Evidence: Timing matches peak traffic
  Falsify: If memory metrics stable, GC is not causing timeouts
  Test: Log heap usage and GC events at checkout start

一般的なカテゴリ：

• ロジックエラー（競合状態、null の処理）
• 状態管理（古いキャッシュ、不適切な状態遷移）
• 統合の失敗（API の変更、タイムアウト、認証）
• リソース枯渇（メモリリーク、接続プール）
• 設定のずれ（環境変数、機能フラグ）
• データ破損（スキーマの不一致、エンコーディング）

4. 戦略の選択

問題の特性に応じて選択します。

対話型デバッグ：ローカルで再現可能 → VS Code／Chrome DevTools、ステップ実行 可観測性主導：本番環境の問題 → Sentry／DataDog／Honeycomb、トレース分析 タイムトラベル：複雑な状態の問題 → rr／Redux DevTools、記録と再生 カオスエンジニアリング：負荷時に断続的に発生 → Chaos Monkey／Gremlin、障害を注入 統計的手法：一部のケースでのみ発生 → デルタデバッグ、成功時と失敗時を比較

5. 構造化された計装フェーズ

計装ポイントはそれぞれ、ステップ 3 の特定の仮説を対象にする必要があります。

以下の箇所に対象を絞ったログ文を追加します。

• 判断ノード：状態やデータに基づいてコードが分岐する箇所
• 状態の変更箇所：変数やオブジェクトが変更される箇所
• 統合境界：API 呼び出し、データベースクエリ、メッセージキュー操作
• 影響を受ける関数の開始時と終了時：実行フローを追跡

セッション単位のログファイル：本番ログを汚さないよう、一意のセッション ID を使用します。

// Generate a debug session ID (short hex)
const debugSessionId = Math.random().toString(16).slice(2, 8);
// e.g., 'a3f7c2'

// Log to session-scoped file in .claude/context/tmp/
const debugLogPath = `.claude/context/tmp/debug-${debugSessionId}.log`;

Write／Edit ツールを使って、対象ファイルに計装を追加します。

// Example: Targeting H1 (N+1 query hypothesis)
// Add at db.query() call site in payment-service.ts
let _debugQueryCount = 0;
const _debugSessionId = process.env.DEBUG_SESSION_ID || 'unknown';
// ... existing code ...
_debugQueryCount++;
fs.appendFileSync(
  `.claude/context/tmp/debug-${_debugSessionId}.log`,
  JSON.stringify({
    ts: Date.now(),
    sessionId: _debugSessionId,
    location: 'payment-service.ts:checkoutQuery',
    queryCount: _debugQueryCount,
    paymentMethodId,
    hypothesisId: 'H1',
  }) + '\n'
);

計装は次の条件を満たす必要があります。

• 対象を絞る：各ログ行で仮説 ID（H1、H2 など）を参照する
• ノンブロッキング：非同期書き込みには fire-and-forget（.catch(() => {})）を使用する
• セッション単位にする：デバッグセッション ID を使い、確実にクリーンアップできるようにする
• 最小限にする：各仮説を確認または否定するために必要なものだけを追加する

クリーンアップに備えて、計装したファイルをすべて記録します。

計装のために変更したファイルをすべて追跡し、クリーンアップ漏れがないようにします。

6. 再現ゲート（SMART_DEBUG_HITL 条件付き）

デフォルトの動作（SMART_DEBUG_HITL=false または未設定）：自動再現

計装を追加した後、プログラムでバグの発生を試みます。

1. 影響を受けるコードパスを対象とする既存のテストを実行します。

   pnpm test -- --grep "<affected-module-or-test-pattern>"
   

2. 再現スクリプトがあれば実行します（例：scripts/reproduce-bug.ts、フィクスチャ、シードスクリプト）。

3. 最小再現ケースを使い、CLI、API 呼び出し、または単体レベルの呼び出しでコードパスを直接実行します。

4. 自動再現を試みるたびに、セッションログを収集します。

自動再現の結果：

• 成功（プログラムでバグを発生させた）：ログを収集し、ユーザーを待たずにステップ 7（ログ分析）へ直接進みます。
• 失敗（プログラムでバグを発生させられない）：以下の HITL ブロックに記載された方法でユーザーに再現を依頼します。

SMART_DEBUG_HITL=true：人間参加型の再現（従来の動作）

手動の UI 操作、外部サービスによるトリガー、ハードウェア／デバイス固有の条件、または特定のユーザー操作のタイミングが必要な競合状態を伴うバグに使用します。

停止して、ユーザーにバグの再現を依頼します。ユーザーが再現したと確認するまで、ログ分析へ進まないでください。

I've added instrumentation targeting:
- H1 (N+1 query): payment-service.ts:87 — logs query count per checkout
- H2 (API timeout): payment-api-client.ts:43 — logs entry/exit timestamps
- H3 (pool exhaustion): db-pool.ts:112 — logs active connections

Debug session ID: a3f7c2
Log file: .claude/context/tmp/debug-a3f7c2.log

Please reproduce the bug now. For intermittent issues, reproduce at least 3 times.
When ready, let me know and I'll read the log file to analyze the evidence.

競合状態や断続的に発生するバグの場合（HITL モード）：相関分析に十分なサンプルを集めるため、再現を N 回（通常は 3～5 回）依頼します。

待機中に根本原因を推測したり、修正を提案したりしないでください。

7. 修正前のログ分析（必須）

収集したログを読み、仮説と照合します。

# Read session log
cat .claude/context/tmp/debug-a3f7c2.log

各ログエントリについて、次を確認します。

• どの仮説を裏付けていますか、または否定していますか？
• 複数回の再現で、証拠は一致していますか？
• 新たな仮説を示唆する予期しないエントリはありますか？

ログ分析の結論は、次のいずれかにしてください。

1. 根本原因を確認：「H1 を確認しました — ログでは、失敗するチェックアウトはすべて queryCount=15、成功するチェックアウトはすべて 1 と示されています」
2. 証拠が不十分：「ログから H1 または H2 を明確に判断できません — X に計装を追加する必要があります」
3. 新たな仮説：「ログに予期しないパターン Z が示されています — 確率 70% の H6 を追加します」

ログが不十分な場合：追加の計装を行うため、ステップ 5 に戻ります。推測してはいけません。

ログの証拠から根本原因が確認されるまで、修正コードは記述しません。

8. 根本原因分析

ログを確認した後に、AI を活用してコードのフローを分析します。

• 実行パス全体を再構築する
• 判断ポイントでの変数の状態を追跡する
• 外部依存関係との相互作用を分析する
• タイミング図／シーケンス図を生成する
• コードの不吉な臭いを検出する
• 類似するバグパターンを特定する
• 修正の複雑さを見積もる

9. 修正の実装

AI が次の内容を含む修正を生成します。

• 必要なコード変更
• 影響評価
• リスクレベル
• 必要なテストカバレッジ
• ロールバック戦略

10. 検証

修正後の検証を行います。

• テストスイートを実行する
• パフォーマンスを比較する（ベースラインと修正後）
• カナリアデプロイを行う（エラー率を監視する）
• AI による修正コードのレビュー

成功基準：

• テストに合格する
• パフォーマンスの退行がない
• エラー率が変わらない、または低下する
• 新たなエッジケースが発生しない

11. 計測コードのクリーンアップ（必須の最終ステップ）

修正を検証した後、追加したデバッグ用の計測コードをすべて削除してください。

1. Step 5 で追加したログ文をすべて削除する
2. デバッグ関連のインポートや変数を削除する
3. セッションログファイルを .claude/context/tmp/ から削除する
4. アーティファクトが残っていないことを確認する：

# Grep for session ID to confirm no debug code remains in production files
grep -r "debug-a3f7c2\|_debugQueryCount\|_debugSessionId" --include="*.ts" --include="*.js" --include="*.cjs" .

# Should return zero results in production source files
# Delete session log
rm .claude/context/tmp/debug-a3f7c2.log

クリーンアップは必須です。 本番コードにデバッグ用の計測コードを残すと、セキュリティリスク（ログインジェクション、情報漏えい）となり、保守の負担も増大します。

12. 再発防止

• AI を使って回帰テストを生成する
• 根本原因をナレッジベースに追加する
• 類似の問題に対する監視／アラートを追加する
• トラブルシューティングの手順をランブックに記録する

例：Cursor デバッグモードの全セッション

Issue: "Checkout timeout errors (intermittent, ~5% of requests)"

// === Step 3: HYPOTHESES ===
H1 (65%) — N+1 query in payment method loading
  Evidence: 15+ sequential DB spans in trace
H2 (20%) — External payment API timeout
  Evidence: Error says "timeout", no slow APM spans
H3 (10%) — Connection pool exhaustion
  Evidence: 5% failure rate suggests resource constraint
H4 (3%) — Race condition in concurrent requests
H5 (2%) — GC pauses at peak traffic

// === Step 5: INSTRUMENTATION ===
// Added to payment-service.ts and db-pool.ts
// Session ID: a3f7c2, log: .claude/context/tmp/debug-a3f7c2.log

// === Step 6: STOP ===
// "Please reproduce the bug 3 times and let me know"

// User: "Done, reproduced 3 times"

// === Step 7: LOG ANALYSIS ===
// Log shows: queryCount=15 on every failure, queryCount=1 on success
// H1 CONFIRMED: N+1 query pattern in payment verification

// === Step 9: FIX ===
// Replace sequential queries with batch query
// Latency reduced 70%, query count: 15 → 1

// === Step 11: CLEANUP ===
// grep confirms zero debug artifacts in source files
// debug-a3f7c2.log deleted

出力形式

次の形式でレポートを作成します。

1. 問題の概要：エラー、発生頻度、影響
2. 優先順位付き仮説：確率（%）、根拠、反証条件を含む3～5件
3. 計測計画：ファイル、場所、仮説の対象、セッション ID
4. [STOP]：再現の依頼
5. ログ分析：根拠と仮説の相関、確認された根本原因
6. 修正案：コード変更、リスク、影響
7. 検証計画：修正を検証する手順
8. クリーンアップの確認：デバッグ用アーティファクトがゼロであることを示す grep の出力
9. 再発防止：テスト、監視、ドキュメント

実行可能な知見に重点を置いてください。パターン認識、仮説の生成、修正の検証に、全工程を通じて AI の支援を活用してください。バグ再現のゲートやクリーンアップの手順を決して省略しないでください。

---

デバッグする問題：$ARGUMENTS

絶対遵守事項

1. 決して、収集したログを読み、根拠に基づいて根本原因を確認する前に修正を書かないでください
2. 必ず、計測を行う前に確率（%）付きの優先順位を付けた仮説を3～5件生成してください
3. 決して、修正の検証とコミット後にデバッグ用の計測コードを残さないでください
4. 必ず、修正を試みる前にバグを再現してください。テストまたはスクリプトで確認します
5. 決して、トレースの根拠とログの根拠がそれぞれ独立して一致するまで、根本原因を報告しないでください

アンチパターン

アンチパターン	失敗する理由	正しいアプローチ
診断前に修正する	誤った原因を修正しようとするため、バグが残るか再発する	ログを収集し、根拠に基づいて根本原因を確認してから修正する
仮説が1つだけ	最初の考えに固執し、実際の根本原因を見逃す	計測を行う前に、優先順位を付けた仮説を3～5件生成する
再現を省略する	修正が機能したか検証できず、同じバグが再発する	修正に進む前に、自動で再現するか、人間の介入を待つ
デバッグ用の計測コードを残す	本番ログにデバッグノイズが混入し、パフォーマンスが低下する	修正を検証した後、ログ文とデバッグコードをすべて削除する
根拠なしに根本原因を断定する	早まった結論により誤った修正につながり、時間を浪費する	結論を出す前に、トレースとログの両方の根拠が一致することを求める

メモリプロトコル（必須）

開始前： .claude/context/memory/learnings.md を読みます

完了後：

• 新しいパターン -> .claude/context/memory/learnings.md
• 問題の発見 -> .claude/context/memory/issues.md
• 決定事項 -> .claude/context/memory/decisions.md

中断を想定してください：メモリに記録されていなければ、起きていないのと同じです。