Debug Mode

実行時証拠に基づく構造化デバッグ。 推測するな。観察せよ。

基本原則

• ログなしに修正なし — コードを読むだけでは不十分

• 複数の仮説 — 最低3つ、理想は5つ

• 証拠に基づく判定 — CONFIRMED / REJECTED / INCONCLUSIVE

• 検証前にクリーンアップしない — 修正が確認されるまで計装を残す

ワークフロー

問題把握 → ログ準備 → 仮説生成 → 計装挿入 → ログクリア → 再現 → 分析 → 修正 → 検証 → クリーンアップ

Step 1: 問題を理解する

ユーザーから以下を聞き取る（不明なら質問する）:

• 症状（期待した動作 vs 実際の動作）

• 再現手順

• 最近の変更

Step 2: ログ収集の準備

環境に応じて選択する。ログフォーマットとregion構文は references/common.md を参照。

言語別パターン:

• JavaScript/TypeScript

ブラウザ（React）: コレクターサーバーを起動

node -e "require('http').createServer((q,s)=>{s.setHeader('Access-Control-Allow-Origin','*');s.setHeader('Access-Control-Allow-Methods','POST,OPTIONS');s.setHeader('Access-Control-Allow-Headers','Content-Type');if(q.method==='OPTIONS'){s.writeHead(204).end();return}let b='';q.on('data',c=>b+=c);q.on('end',()=>{require('fs').appendFileSync('debug.log',b+'\n');s.writeHead(204).end()})}).listen(4567,()=>console.log('Collector: http://localhost:4567'))"

サーバーサイド（Node.js / Lambda）: ファイル直接書き込み。サーバー不要。

Step 3: 仮説を立てる

3-5個の仮説を生成する。1つに固執しない。

仮説

H1: [タイトル]

• 原因: ...
• 検証方法: XをYの前後で確認する

H2: [タイトル]

• 原因: ...
• 検証方法: ...

H3: [タイトル]

• 原因: ...
• 検証方法: ...

Step 4: 計装を挿入する

各仮説に対応するログを挿入する。3-8箇所。

計装ポイント:

• 関数の入口（引数）

• 関数の出口（戻り値）

• 重要な処理の前後

• 分岐パス（どのif/elseを通ったか）

• 状態変更の前後

必須: #region debug:{hypothesisId} で囲む

テンプレートは言語別リファレンスを参照。

Step 5: 古いログを削除

rm -f debug.log

Step 6: 再現を依頼する

再現手順

1. ログ収集の準備ができていることを確認（必要ならコレクターを起動）
2. debug.log が削除されていることを確認
3. アプリを起動/再起動
4. [バグを発生させる具体的な操作]
5. 完了したら教えてください

Step 7: ログを分析する

cat debug.log | jq . # 全件表示 jq 'select(.h == "H1")' debug.log # 仮説でフィルタ cat debug.log | jq -s 'group_by(.h)' # 仮説ごとにグルーピング tail -f debug.log | jq . # リアルタイム

各仮説を評価する:

判定 意味

CONFIRMED ログがこの仮説を明確に支持する

REJECTED ログがこの仮説と矛盾する

INCONCLUSIVE データ不足で判断できない

Step 8: 修正する

仮説がCONFIRMEDの場合のみ。

• 根本原因を修正する。症状が出た箇所ではなく、原因の発生元を直す

• エラーが出た関数をtry-catchで握り潰すのは修正ではない

• 不正な値が渡されるなら、渡す側を直す（受け取る側でガードするだけでは対症療法）

• コールチェーンを遡り、最初に問題が発生した地点を特定してそこを修正する

根本原因が実装方針の誤りだった場合: 勝手に直さず、ユーザーに報告する。

以下の構造で説明し、修正方針の判断をユーザーに委ねる:

調査結果

現状（何がどうなっているか）

• [コードの現在の実装・データフローを事実として記述]

不一致（なぜバグになるか）

• [ユーザーが期待する動作と、現状の実装がどう矛盾しているか]

修正案（どこをどう変える必要があるか）

• [修正が必要なファイル・関数・ロジックと、変更内容の概要]

• [影響範囲があれば明記]

• 最小限の差分で修正する

• 計装はそのまま残す

全仮説がREJECTEDの場合: 別のサブシステムに着目して新しい仮説を立てる → Step 3へ。

修正が3回失敗した場合: 立ち止まる。個別のバグではなくアーキテクチャの問題を疑う。ユーザーに状況を共有し、方針を相談する。

Step 9: 検証する

1. rm -f debug.log
2. アプリを再起動
3. 同じ操作を実行
4. 完了したら教えてください

修正前後のログを比較する。

Step 10: クリーンアップ

ユーザーが修正の動作を確認した後にのみ実施。

grep -rn "#region debug:" src/

計装コードを削除し、debug.log を削除し、コレクターを停止する。

ログフォーマット

NDJSON（1行1JSON）:

{"h":"H1","l":"state_before","v":{"userId":"123"},"ts":1702567890123}

フィールド 意味

h 仮説ID

l ラベル

v 値

ts タイムスタンプ（ms）

禁止事項

• ログ分析前に修正を提案すること

• 仮説を1つしか立てないこと

• 検証前に計装を削除すること

• 「たぶんこれ」という推測

• setTimeout/sleep による「修正」

• 対症療法的な修正（エラーを握り潰す、表示を隠す、条件分岐で回避する等）

リファレンス

• references/common.md — ログフォーマット、region構文

• references/javascript.md — JavaScript/TypeScript