GitHubで20万を超えるスターを集めているリポジトリ「mattpocock/skills」を実機検証しました。TypeScript教育者として知られるMatt Pocock氏が公開しているエンジニアリング向けSkill集の1本、複雑なバグの原因究明を6つの段階に固定する「diagnosing-bugs」を、意図的に仕込んだバグで実際に動かして検証しています。

どんなSkillか

リポジトリを取得して確認したところ、engineering配下に16本のSkillが並び、その1本であるdiagnosing-bugsのSKILL.mdには、フロントマターのdescriptionに「厄介なバグやパフォーマンス低下の診断ループ。ユーザーが『診断して』『デバッグして』と言ったとき、あるいは何かが壊れている・例外が出る・失敗する・遅いと報告したときに使う」と明記されています。本文は6つのフェーズで構成されています。①フィードバックループの構築（決定的で高速な再現手段を用意する）②再現と最小化（症状が一致することを確認し、無関係な要素を削ぎ落とす）③仮説立て（3〜5個の反証可能な仮説を尤度順に並べる）④計測（デバッガやログで狙った予測を検証する）⑤修正と回帰テスト（正しい箇所にテストを書いてから直す）⑥後片付けと振り返り（計測用コードを消し、根本原因を記録する）という流れです。

外部への通信や認証情報へのアクセスを行う処理は含まれておらず、Claude Codeに手順を指示するプレーンテキストのSkillであることをコードレベルで確認しました。危険な処理を伴わないため、精読レビューに加えて実際に動かす検証に進みました。

実際に使ってみた

検証のため、括弧の対応をチェックする関数に、意図的にバグを仕込みました。

def is_balanced(expr):
    pairs = {')': '(', ']': '[', '}': '{'}
    stack = []
    for ch in expr:
        if ch in '([{':
            stack.append(ch)
        elif ch in ')]}':
            if not stack:
                return False
            if stack[-1] != pairs[ch]:
                return False
            stack.pop()
    return True  # バグ: ループ終了時に未消化の開き括弧が残っていてもTrueを返す

ユーザー報告を「一部の入力で、閉じ括弧が足りないのにTrueが返ることがある」とだけ設定し、この状態から2パターンで原因究明を進めました。

ガイドラインなし（勘で直すパターン）では、目につきやすい「括弧の対応関係」を疑いがちです。実際、対応関係が食い違う入力（"(a+b]"）を最初に試すと正しくFalseが返るため、この方向の疑いは外れているのに気づかず時間を使う、という遠回りが起きやすい構造になっていました。

diagnosing-bugsの手順に沿うと、まず再現と最小化を行い、"(a+b"から更に削って"("単体でも同じ症状（Trueが返る）が再現することを確認しました。次に仮説を立てる段階で「ループ終了時に未消化の開き括弧が残っている可能性」を上位に置き、最後にstackの中身を出力する計測コードを1行差し込んで実行したところ、stack = ['(']が残ったままTrueが返っていることを直接確認できました。

DEBUG: ループ終了時点のstack = ['(']

原因が「ループを抜けた後にstackが空かどうかを確認していない」ことだと特定できたため、最終行をreturn not stackに直し、元のバグを含む4パターンの回帰テストを書いて全て通ることを確認しました。

良かった点

  • 「再現と最小化」を仮説立てより先に固定していることで、遠回りな思い込みに時間を使う前に、症状を再現する最小の入力にたどり着けました。今回は6文字の入力を1文字まで削れています。
  • 仮説を「尤度順に並べてから検証する」という順序があることで、目につきやすいが的外れな仮説（括弧の対応関係）を後回しにし、実際の原因（終了条件の見落とし）を先に検証する動きが自然に取れました。
  • 「計測してから直す」という順序が明記されているため、憶測で修正して終わりにせず、stackの中身を実際に出力して原因を確認したうえで直せました。

思ったようにならなかった点

  • 今回のような数十行規模のバグでは、6フェーズすべてを律儀に踏むと、勘で直す場合に比べて手順の分だけ手数は増えます。効果が大きいのは、今回のように「目につきやすい原因候補が実は的外れ」なケースだと感じました。
  • SKILL.md単体は簡潔なため、フェーズの意図（なぜその順番なのか）を掴むには、実際に手を動かして体験したほうが早いと感じました。

向いている使い方

今回の検証から、原因の見当がつきにくい、あるいは「ここが怪しい」という直感が外れがちな複雑なバグに向いていると感じます。逆に、エラーメッセージから原因が一目でわかるような単純なバグにまで機械的に適用すると、回り道になる場面もありそうです。SKILL.md形式で提供されており、公式マーケットプレイス（claude plugins install mattpocock-skills）からインストールできるため、まずは原因究明に手こずった過去のバグを題材に試してみるのが良さそうです。

検証環境: Claude Code。検証日2026-08-12