Claudeのdebugスキルで、再現から修正までを4段で進める

debugスキルは、Anthropicが配布するengineeringプラグインに入っている、構造化されたデバッグの手順書です。エラーメッセージかスタックトレースを渡すと、再現、切り分け、原因特定、修正の4段で進め、最後に「デバッグレポート」の形で結果をまとめます。

この記事では、導入、4段の中身、渡す入力の書き方、返ってくるレポートの形、監視やソース管理をつないだときの変化を順に見ます。名前の食い違いが1つあるので、呼び出し方も確認します。

debugスキルは何をするものか

engineeringプラグインは、knowledge-work-pluginsリポジトリにあるソフトウェア開発向けのプラグインです。READMEには、主にCowork向けに設計されていて、Claude Codeでも動くと書かれています。

debugスキルの説明文は「再現、切り分け、診断、修正という構造化されたデバッグセッション」です。起動のきっかけとして、次の4つが挙がっています。

• エラーメッセージやスタックトレースを渡したとき
• 「ステージングでは動くが本番では動かない」と言ったとき
• 「デプロイのあとから壊れた」と言ったとき
• 期待と違う挙動が出ていて、原因が自明でないとき

最後の1つが大事です。原因が一目で分かるタイプミスにこのスキルは要りません。手がかりが少なく、仮説を立てて潰す必要がある不具合に向いた手順書です。

導入と呼び出し名

導入はREADMEにある2行です。

claude plugin marketplace add anthropics/knowledge-work-plugins
claude plugin install engineering@knowledge-work-plugins

marketplaceの仕組みはプラグインmarketplaceの解説にあります。スキル自体の置き場所と書式はClaude Codeのスキル解説が詳しいので、ここでは省きます。

READMEの/debugと、Claude Codeでの実際の名前

READMEのCommands表には /debug が載っています。SKILL.mdの見出しも /debug で、使い方は /debug $ARGUMENTS です。

ただし、Claude Codeのスキル解説では、プラグイン内のスキルは /プラグイン名:スキル名 の形で名前空間が付くと説明されています。engineeringプラグインのdebugなら /engineering:debug です。

もう1点あります。Claude Codeには --debug フラグと、セッション内の /debug コマンドがあります。こちらはClaude Code自身のログを調べる機能で、別物です。両者が衝突するかどうかは、プラグインのREADMEにも書かれていません。入れたあとのスラッシュコマンド一覧で、実際に出る名前を見てください。以下、プラグインの方を「debugスキル」と呼びます。Claude Code自身の --debug ログの読み方は--debugと/debugの解説にあります。

呼び出しの形はこうなります。

/engineering:debug Users are getting 500 errors on the checkout page

引数に渡す文字列が、SKILL.mdの $ARGUMENTS に入ります。READMEの例も、500エラーの症状をそのまま渡す形です。日本語で書いてもかまいませんが、エラーメッセージは次の節のとおり、原文のまま貼ります。

4段の中身 — 何を確かめ、何を返すか

SKILL.mdには、4つの段階が箇条書きで示されています。

疑う順序は「直近の変更」が先

2段目の切り分けに「直近のデプロイ、設定変更、依存関係」と明記されている点に注目してください。コードを頭から読む前に、最近変わったものから疑う順序です。

SKILL.mdの「Tips」にも同じ趣旨があります。直近のデプロイ、依存関係の更新、設定変更は「最有力の容疑者」だという書き方です。「ステージングでは動くが本番では動かない」「大きなペイロードのときだけ起きる」といった文脈を添えると、絞り込みが速くなるとも書かれています。

つまり入力で差がつくのは、スタックトレースの量ではなく、変化の情報を添えるかどうかです。

入力の書き方 — 何を渡すと切り分けが進むか

スキルが求める入力は、SKILL.mdの「What I Need From You」に5つ並んでいます。

Tipsの1番目は「エラーメッセージは正確に共有する。言い換えない。正確な文面が重要」です。要約すると、検索や照合に使える文字列が消えます。

例えば、次のように渡します。例示のため、サービス名と時刻は架空です。

/engineering:debug 決済APIが 502 を返す。
エラー: upstream connect error or disconnect/reset before headers
発生: 昨日 14:10 のデプロイ後。ステージングでは再現しない。
変更: 接続プールの最大数を 20 から 50 に変更、ORMを minor アップデート
再現: POST /v1/payments を同時 30 リクエストで叩くと約半数が失敗

この入力には、原文のエラー、時刻、環境差、直近の変更、再現条件が揃っています。切り分けの段で、接続プールの変更とORMの更新という2つの容疑者がすぐ挙がります。

Claude Codeで使うときは、再現を実行させる

debugスキルは手順書なので、それ自体はコマンドを実行する仕組みを持ちません。SKILL.mdのフロントマターにも、ツールを制限する記述はありません。Claude Codeでは、再現の段で次のように頼むと、手順が実行に落ちます。

再現の段では、上の再現手順をこのリポジトリで実際に実行し、
失敗の出力をそのまま見せてください。再現できなければ、
できなかった条件を報告してから先に進んでください。

再現できたかどうかを、推測ではなく実行結果で確かめるための追加指示です。実行が難しい本番障害では、この指示を外し、ログと変更履歴の読み取りだけで進めます。

返ってくるレポートの形

スキルは、結果を次の構成のレポートにまとめる形になっています。

4段のうち、診断と修正が「Root Cause」と「Fix」に、再現が「Reproduction」に対応します。切り分けの段に独立した見出しはありません。

注意したいのは、最後の「Prevention」です。回帰テストを足す前提がレポートの型に組み込まれています。修正だけ受け取って閉じず、テストまで反映して初めて4段が終わる、という設計です。

つなげるツールで何が変わるか

debugスキルは、何も接続しなくても使えます。READMEの表では、デバッグセッションは「問題を説明するだけ」で成り立ち、監視を接続すると「ログとメトリクスを引ける」ようになると書かれています。

SKILL.mdの「If Connectors Available」は、3種類を挙げています。

CONNECTORS.mdによると、~~monitoring の同梱サーバーはDatadogで、他の選択肢にNew Relic、Grafana、Splunkが挙がっています。~~source control はGitHubが同梱で、GitLabとBitbucketが別候補です。~~project tracker はLinear、Asana、Atlassian(JiraとConfluence)が同梱です。

プラグインの .mcp.json に、これらのMCPサーバーのURLが事前に設定されています。同梱ではないツールを使うときは、カテゴリに合うMCPサーバーを自分で接続します。仕組みはCONNECTORS.mdの説明どおり、プラグインがカテゴリ名で手順を書いているので、同じカテゴリのサーバーなら差し替えられます。MCPの追加方法はMCP接続の解説にまとめてあります。

設定ファイルで、自分のスタックを覚えさせる

READMEには、engineering/.claude/settings.local.json を作って個人設定を書く方法が載っています。キーは名前、役職、チーム、会社、techStack、defaultBranch、deployProcess です。

{
  "techStack": ["Python", "TypeScript", "PostgreSQL", "AWS"],
  "defaultBranch": "main",
  "deployProcess": "canary"
}

READMEの説明では、未設定のとき、プラグインが対話で聞いてきます。デバッグでは techStack と defaultBranch が効きそうですが、debugスキルのSKILL.mdがこれらのキーを参照するとは書かれていません。効果の有無は、プラグインを入れた環境で設定を変えて出力を比べると分かります。

他のデバッグ系の使い方との分担

デバッグに関する手段は、Claude Codeには複数あります。役割を分けると、迷いません。

debugスキルは「型」を与えるもので、検証を機械に持たせる仕組みは含みません。Preventionで挙がったテストを完了条件にして回す方法は、デバッグ精度の記事にあります。

障害が本番で進行中なら、デバッグより先に被害の抑え込みと連絡が要ります。その場合はincident-responseスキルが先で、原因の調査にdebugスキルを使う順になります。

つまずきやすい点

• READMEのSkills表にdebugがない: 表に並ぶのは6つのスキルで、debugは含まれません。ところがリポジトリの skills ディレクトリには debug フォルダーがあり、READMEのCommands表には /debug が載っています。表が分けて書かれているだけなので、debugは入っています
• エラー文を要約して渡す: 「接続エラーが出る」では、切り分けが始まりません。原文を貼ります
• 変更の情報を渡さない: 切り分けの段が最初に見るのは直近の変更です。デプロイ日と変更内容を1行添えます
• 修正だけ採用する: レポートのPreventionを飛ばすと、同じ不具合が戻ります

まとめ

debugスキルは、再現、切り分け、原因特定、修正の順を固定して、症状だけで修正に飛びつくのを防ぐ手順書です。入力は短くてよく、原文のエラーと直近の変更、再現条件の3点を添えれば、切り分けが始まります。

型が決まっているぶん、何を調べたかが追いやすいのも利点です。ただし、型は検証を保証しません。再現を実行させ、Preventionのテストを足すところまでを自分の依頼に含めて、初めて4段が閉じます。