debugging について
ソフトウェア開発者向けのデバッグスキルです。エラーの再現から修正の検証までを導き、根本原因の特定を重視します。Noodle のインフラ障害向け診断項目も含みます。
主な機能
- 01エラーの再現と出力全体の確認
- 02永続状態と環境の調査
- 03問題範囲の段階的な絞り込み
- 04根本原因の修正と検証
- 05再発パターンの検索と解消
- 06Noodle 固有の診断項目
活用シーン
- 01再現しにくいエラーの調査
- 02再起動後に起きる状態問題の診断
- 03修正の検証と類似コードの確認
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/debuggingを入力して読み込まれたか確認します。
詳細
デバッグ
開始する前に[[principles/fix-root-causes]]を読んでください。すべてのデバッグセッションでこの原則に従います。根本原因を追跡し、症状を取り繕うだけの対応はしません。
プロセス
-
再現します。 正確なエラーを確認します。失敗するコマンドを実行し、出力全体を読みます。再現できなければ、修正を検証できません。
-
エラーを読みます。 エラーメッセージ、スタックトレース、行番号はデータです。仮説を立てる前に、すべて読みます。多くのバグは、どこに問題があるかを正確に示しています。
-
コードより先に状態を疑います。 コードをデバッグする前に、永続状態を確認します。特に、再起動時のバグや環境のずれがある場合は確認してください。[[principles/fix-root-causes]]を参照してください。
- Noodle の状態：
.noodle/orders.json（古い項目はないか？）、.noodle/sessions/（孤立したセッションはないか？）、.noodle.toml（有効か？） - 環境：tmux セッション（
tmux ls）、ロックファイル、キャッシュ済みの成果物 - 設定：
.noodle.tomlの検証（noodle startで診断結果を報告）、スキルのフロントマター解析エラー - 永続ファイル：brain/ のメモ、プランファイル、TODO。破損や古い参照がないか確認します
- Noodle の状態：
-
切り分けます。 範囲を絞り込みます。どのファイルか？ どの関数か？ どの行か？ 二分探索を使います。半分をコメントアウトして、まだ失敗するか確認し、これを繰り返します。
-
根本原因を見つけます。 最初に思いつく「修正」は、たいてい症状への対処です。実際の原因にたどり着くまで「なぜ？」と問い続けます。
- テストが失敗する → モックが間違っている → インターフェースが変わった → 型が実行時の形状と一致しない → 型を修正する
- ビルドが失敗する → インポートエラー → 循環依存 → モジュールを再構成する
- 実行時にクラッシュする → 値が undefined → null チェックがない → データソースが空の場合に null を返す → データソース側で空のケースを処理する
-
修正して検証します。 症状ではなく、根本原因を修正します。その後、テストを実行し、ビルドを実行し、機能の経路を実際に試して検証します。「コンパイルできる」だけでは検証になりません。
-
同じパターンがないか確認します。 バグが一か所にあった場合、同じパターンがほかにもないか grep で検索します。すべての該当箇所を修正するか、構造上発生しないようにします。
Noodle 固有の診断
Noodle のインフラストラクチャ障害をデバッグする際は、次を確認してください。
| 症状 | 最初に確認する項目 |
|---|---|
| Cook が起動しない | tmux ls、.noodle/orders.json の妥当性、スキルリゾルバーのパス |
| 注文が止まったまま | .noodle/orders.json に古い項目がないか、.noodle.toml のアダプター設定 |
| スキルが見つからない | .noodle.toml の [skills] パス、.agents/skills/<name>/SKILL.md が存在するか |
| mise が古い | .noodle/mise.json の generated_at タイムスタンプ、バックログ同期スクリプト |
| セッションが孤立している | .noodle/sessions/<id>/meta.json の状態、ゾンビセッションがないか tmux ls |
行き詰まったとき
- 推測せず、計測します。 重要な箇所にログを追加し、実際の値を確認します。実際の状態を読み取ってください（[[principles/prove-it-works]]）。
- 変更点を比較します。
git diff、git log、git bisectを使います。ほとんどのバグは最近発生したものです。 - 単純化します。 失敗するケースを最小限の再現例にします。無関係なものをすべて取り除きます。
- 一度に一つだけ変更します。 複数の変更を同時に行うと、何が修正（または悪化）させたのか分からなくなります。
- 前提を確認します。 バグは、正しいと確信している部分にあることがよくあります。すべてを検証してください。
アンチパターン
- 回避フラグ（
--no-verify、--force、SKIP_CHECK=true）は、原因を修正せずに症状を隠します。 - 再試行ループは、断続的なバグを確率の陰に隠します。
- 手当たり次第のデバッグ――「効果があるか見る」ために三つのことを変更する――は、因果関係を見えにくくします。
- x が undefined である理由を問わずに、ガード（
if (x !== undefined)）を追加します。
修正後
このバグが再発する可能性がある場合、または理解に影響した場合は、得られた教訓を記録します。brain のメモを書く、スキルを更新する、または TODO を追加してください。バグが起きるたびに、システムが賢くなるべきです。[[principles/encode-lessons-in-structure]]を参照してください。