debug-loop

デバッグループ

実データを使った、自律的な仮説駆動型デバッグです。推測もシミュレーションも行いません。

引数

• <symptom> — バグまたは予期しない動作の説明です。省略した場合は、ユーザーに確認します。

フェーズ

フェーズ 1 — 再現

バグを表示する正確なコマンドを実行します。実際の出力を取得して表示し、バグが確認できることを確かめます。

バグを再現できない場合は、試した内容を説明して終了します。

フェーズ 2 — 仮説と検証（最大 5 回）

各回で、次の手順を実行します。

1. 具体的な仮説を述べます（例：「クエリは v2 テーブルを対象にしていますが、データは v3 テーブルにあります」）
2. 仮説を検証する実際のコマンドを実行します（例：sqlite3 [db path] '.tables' の後に SELECT COUNT(*) FROM [table] を実行します）
3. 仮説が確認されたか、否定されたかを記録します
4. 否定された場合は、判明した内容に基づいて次の仮説を立てます

根本原因を確認するまでは、コードを変更してはいけません。

重要な確認事項：

• データの問題が疑われる場合は、v2 と v3 の SQLite テーブルを必ず両方確認します
• 依存関係のバージョンを確認します（例：sqlite3 と better-sqlite3）
• 見落とされている可能性のあるハードコード値を確認します

フェーズ 3 — 修正

対象を絞った最小限の修正を行います。以下を説明します。

• 根本原因
• 変更内容とその理由
• 影響範囲（影響を受ける他のコードパス）

修正を適用する前に、コードベース全体で問題のパターンが使われている箇所をすべて grep で検索します。

フェーズ 4 — 検証

フェーズ 1 と同じ再現コマンドを実行します。出力に正しい値が表示される必要があります。表示されない場合は、フェーズ 2 に戻ります。

修正前後の出力を比較して示します。

フェーズ 5 — 回帰テスト

npm test

テストスイート全体を実行します。テストが失敗した場合は、コミットする前に修正します。

ルール

• 出力を推測したりシミュレーションしたりしてはいけません。必ず実際のコマンドを実行します
• 根本原因を確認する前にコードを変更してはいけません
• 1 つのファイルだけでなく、コードベース全体でパターンを必ず確認します
• 5 つの仮説を試しても解決できない場合は、作業を止めてユーザーに指示を求めます