debugger

debugger skill の概要

debugger skill は何のためのものか

debugger skill は、汎用的な「何が悪いの？」という聞き方よりも、根本原因に素早くたどり着くための構造化されたデバッグ手順です。コードがエラーを投げる、想定外の挙動をする、変更後にリグレッションが起きる、あるいは特定環境でだけ失敗するといった場面に向いています。いきなり修正案に飛ぶのではなく、debugger skill は実際のデバッグで重要な順番――再現、切り分け、分析、修正、検証――をきちんと踏ませます。

どんな人に debugger skill の導入が向いているか

この debugger skill は、場当たり的なトラブル対応ではなく、再利用できる Debugging の進め方を持ちたい開発者、AI coding agents、技術チームに適しています。特に、スタックトレース、ログ、不完全なバグ報告、あいまいな再現手順から調査を始めることが多いなら効果的です。特定フレームワークの深い専門知識を提供するというより、プロジェクト横断でデバッグの規律を底上げするタイプの skill です。

この skill で片付けたい本当の仕事

この skill の役割は、単に「エラーメッセージを説明する」ことではありません。曖昧な障害を、調査可能な筋道に変えることです。つまり、何が変わったのか、どう再現するのか、どこまで範囲を絞るのか、どんな証拠を集めるべきか、最終的な修正をどう検証するか、を整理します。チームが推測に時間を取られていたり、原因ではなく症状ばかり直してしまっているなら、この debugger の導入価値は高くなります。

なぜこの debugger skill が目立つのか

この skill の強みは、実運用しやすい形になっていることです。リポジトリには次のものが含まれています。

• SKILL.md に段階的なデバッグフロー
• references/checklist.md、references/errors.md、references/patterns.md にすぐ使えるデバッグ補助資料
• scripts/debug_report.py に実務向けのレポート生成スクリプト

単なる prompt template より、実際の障害対応に強いのはこの組み合わせがあるからです。プロセス、チェックリスト、よくある障害カテゴリ、そして引き継ぎに使える成果物までそろっています。

この skill がやろうとしていないこと

これは言語特化の debugger でも、IDE extension でも、tracing platform でもありません。runtime tools、profiler、framework docs の代わりにはなりません。もし主な目的が対話的なステップ実行、メモリ調査、プロトコル単位のトレースなら、そうした専用ツールを直接使い、この debugger ガイドはその周辺で考え方を整理するレイヤーとして使うのが適切です。

debugger skill の使い方

インストール時の前提と repo path

この skill は zhaono1/agent-playbook の skills/debugger にあります。GitHub ソースを扱える skill loader を使っているなら、リポジトリからインストールして debugger skill を指定します。よくある形は次のとおりです。

npx skills add https://github.com/zhaono1/agent-playbook --skill debugger

セットアップ方法が異なる場合でも、重要なのは skills/debugger ディレクトリを読み込むことです。そうすれば agent が SKILL.md と、補助ファイルの references/、scripts/ にアクセスできます。

最初に読むべきファイル

素早く使い始めるなら、次の順番で読むのがおすすめです。

1. skills/debugger/SKILL.md
2. skills/debugger/references/checklist.md
3. skills/debugger/references/patterns.md
4. skills/debugger/references/errors.md
5. skills/debugger/scripts/debug_report.py

この順番は、実際の debugger の使い方に沿っています。まずフローを押さえ、その次に調査のヒューリスティクス、次にエラー分類、最後にドキュメント化の支援を見る流れです。

実運用で debugger skill はどう起動されるか

このリポジトリは、ユーザーが次のように報告したときに動かす想定です。

• error や exception が出る
• 想定外の挙動をしている
• “debug this”
• “why isn’t this working?”

実際には、依頼を明示的に「デバッグタスク」として伝え、証拠も添えると debugger skill は最も力を発揮します。たとえば次のような依頼です。

“Use the debugger skill. This API returns 500 only in staging. Expected 200. Started after yesterday’s deploy. Here is the stack trace, the endpoint, and the last 3 commits.”

これは単に “fix this bug.” と言うより、はるかに強い依頼です。

debugger skill に必要な入力

debugger skill をうまく使うには、具体的な入力が重要です。可能な限り、次の情報を渡してください。

• 正確なエラーテキスト
• stack trace
• expected と actual の挙動
• 再現手順
• 直近のコード変更や設定変更
• 環境情報
• 関連ログ
• 絞り込んだファイルやコンポーネントの範囲

この skill のワークフローは証拠収集を前提にしています。実装詳細が多少不足していても回りますが、再現手順や実際の出力が欠けると、出力品質は大きく落ちます。

粗い依頼を強い debugger prompt に変える

弱い prompt:

“Why does this fail?”

より強い prompt:

“Use the debugger skill to diagnose this failure. After upgrading dependencies, npm test fails in auth.spec.ts with TypeError: Cannot read properties of undefined. Expected tests to pass. Actual behavior: 6 failures on CI, 0 locally. Recent changes: lockfile update and config edit. Please help reproduce, isolate likely causes, rank hypotheses, and suggest the smallest safe fix.”

これがうまく機能する理由は次のとおりです。

• デバッグの目的を明示している
• expected と actual の差を示している
• 環境差分を含めている
• 直近の変更を含めている
• パッチ提案の前に調査を求めている

推奨される debugger ワークフロー

実務で使いやすい debugger ガイドとしては、次の流れです。

1. 問題を正確に再現する
2. expected と actual の挙動を記録する
3. git log --oneline -10 で最近の変更を確認する
4. ログやトレースを集める
5. 最小再現または二分探索で切り分ける
6. 障害をエラーカテゴリに当てはめる
7. 根本原因の仮説を立てる
8. 最小限で有力な修正を試す
9. リグレッションを防ぐ確認まで行う

skill 自体もほぼこの流れをコード化していますが、agent が早い段階で修正案に飛びつきそうなときは、明示的にこの順番を守らせると効果的です。

参考ファイルを判断材料として使う

補助ファイルは短いですが、出力の質に効きます。

• references/checklist.md は、再現、切り分け、根本原因、修正、リグレッション確認という基本を漏らさないためのものです。
• references/patterns.md は、問題の範囲が広い、あるいはノイズが多いときに有効で、二分探索、狙ったログ出し、最小再現への縮約といった手法を示します。
• references/errors.md は、null access、race conditions、config mismatches、data shape drift のような典型的な失敗を分類するのに役立ちます。

最初の debugger 出力が抽象的すぎると感じたら、これらを使わせてください。構文を学ぶためというより、調査の進め方をシャープにするための資料です。

再利用できる debug report を生成する

調査内容を成果物として残したいなら、次を使います。

python skills/debugger/scripts/debug_report.py --name "Checkout timeout in staging" --owner payments

これで、summary、environment、repro steps、logs、root cause、fix、regression tests、follow-ups を含む markdown レポートのテンプレートが生成されます。チームでの Debugging では、これがリポジトリ内でも特に実用的な部分です。一時的な調査を、レビュー可能な記録に変えられます。

Debugging における debugger の向いている使いどころ

この debugger skill が特に役立つのは、次のようなケースです。

• バグは再現するが、原因がすぐ見えない
• ログはあるがノイズが多い
• 変更後に障害が出始めた
• 問題が code、config、environment にまたがっている
• コード編集前に規律ある triage フローが必要

逆に、一目で分かる小さな syntax mistake や、agent がアクセスできない proprietary な運用文脈が前提のドメイン固有障害には、そこまで刺さりません。

debugger の使い方を良くする実践的なコツ

skill には次を分けて出すよう求めるのがおすすめです。

• facts
• hypotheses
• next checks
• proposed fix
• verification steps

この構成にすると、早すぎる確信を避けられます。さらに、あり得る原因を優先度順に並べさせ、それぞれを否定できる証拠も言わせるとよいです。そうすると debugger skill は「賢い当て推量」ではなく、より良い調査パートナーになります。

debugger skill FAQ

この debugger skill は普通の prompt より良いか

多くの場合、問題が複数ステップにまたがるなら yes です。一般的な prompt は、症状から推測ベースの修正にすぐ飛びがちです。debugger skill は、体系的な切り分け、証拠収集、検証が必要なときに向いています。バグがごく単純で、1つの snippet を見れば十分な場合は、普通の prompt でも足りることがあります。

debugger の導入は初心者でも使いやすいか

はい。コアのワークフローがシンプルで具体的だからです。初心者にとっても、段階的な進め方とチェックリストは助けになります。ただし注意点として、この skill はログ、stack trace、再現手順など、ある程度の証拠を出せることを前提にしています。それらがないと、どんな debugger ガイドでも推測が増えます。

この debugger skill はどの言語や stack でも使えるか

概ね yes です。debugger skill は言語依存ではなく、プロセス志向です。エラー例も特定 framework に寄りすぎず、汎用的なものが中心です。そのぶん移植性は高い一方で、最良の結果を得るには stack 固有の事情を自分で補う必要があります。

どんなときはこの debugger skill を使わないほうがよいか

次のような場合は見送ってください。

• 推論支援より、対話的な runtime debugging が必要
• 問題が純粋に運用上のもので、agent がシステムにアクセスできない
• バグがすでに特定済みの一行 typo にすぎない
• リポジトリに含まれていない vendor 固有の知識が必要

こうしたケースでは、まず専用ツールや domain docs を優先するのが適切です。

チームへの引き継ぎや incident 後のフォローにも役立つか

はい。debug_report.py があること自体、この debugger skill が単発のチャット以上を想定して設計されている強い証拠です。ownership、repro steps、root cause、fix、follow-ups を備えた再利用可能なレポートに、デバッグセッションを変換できます。

debugger skill を改善する方法

症状だけでなく、証拠を debugger skill に渡す

debugger の出力を最も早く改善する方法は、生の証拠を含めることです。

• 実行した正確な command
• 完全な error text
• 失敗する input
• 問題が起きる environment
• 直近の commit range
• すでに試したこと

“Here is the stack trace and the last good commit” は、“it’s broken after my changes.” よりはるかに有効です。

早い段階で最小再現を作らせる

debugger 利用でよくある失敗は、調査対象の表面積が広すぎることです。最小の再現ケースを作る支援を skill に依頼してください。これにより framework のセットアップ、無関係な service、古い state などのノイズが落ち、根本原因が見えやすくなります。

仮説の優先順位付けを求める

複数の原因があり得るなら、debugger skill に「もっともらしさ」と「検証コストの低さ」の両方で順位付けさせてください。調査順序が良くなります。たとえば次のように依頼します。

“List the top 3 root-cause hypotheses, what evidence supports each, and the next cheapest check to confirm or reject them.”

これは flaky tests、integration failures、config drift のようなケースで特に有効です。

根本原因と修正の出来を分けて考える

よくある問題として、症状が消えた最初の fix をそのまま採用してしまうことがあります。debugger ガイドを使って、次を確認させてください。

• なぜこれが起きたのか
• どんな条件で起きるようになったのか
• 直ったままであることを、どの regression test で証明するのか

これは null handling、race conditions、config の不一致のように再発しやすい問題では特に重要です。

リポジトリの文脈を渡して最初の出力を改善する

自分の codebase のバグであれば、次の情報を渡してください。

• 怪しい file
• package または service の境界
• deploy のタイミング
• 関係する config files
• 問題が local、CI、staging、production のどこでだけ起きるか

debugger skill は、貼り付けた stack trace だけから推論するよりも、証拠をシステム境界に結び付けられると精度がかなり上がります。

参考ファイルで弱い回答を sharpen する

最初の回答が汎用的すぎると感じたら、agent に明示的に次を使わせてください。

• references/checklist.md でプロセスの抜け漏れを防ぐ
• references/patterns.md で切り分け手法を使う
• references/errors.md でエラー系統を照合する

これは prompt 全体を書き直さなくても debugger の結果を改善できる、実務的なやり方です。

最初のデバッグ結果のあとに反復する

debugger をうまく使うには、反復が前提です。最初の出力のあとに次を行ってください。

1. 提案された確認を1つ実行する
2. その結果を持ち帰る
3. skill に仮説を更新させる
4. そのあとでコードを編集する

このループがあることで、debugger skill は静的な debugger ガイド以上の価値を持ちます。大きく推測的な回答を1回出すのではなく、収束に向けて調査を進められます。

クローズ前にリグレッション防止の証拠を足す

リポジトリのチェックリストにも明示的に regression coverage が入っており、締めどころとして正しいポイントです。debugger skill に、次回同じ問題を検出できる最小の test、assertion、monitoring check を提案させてください。検証のない fix は、たいてい Debugging として不十分です。特に、断続的なバグや環境依存の不具合ではその傾向が強くなります。