diagnose
作成者 mattpocockdiagnose は、手強いバグ、フレークしやすいテスト、パフォーマンス劣化のための構造化されたデバッグ手順です。問題の再現、失敗ケースの最小化、仮説を1つずつ立てること、計測の追加、根本原因の修正、回帰テストによる固定化までを一連で支援します。「debug this」だけでは足りないときに、diagnose ガイドを使ってください。
この skill の評価は 74/100 で、規律あるバグ診断ワークフローを求めるユーザーには掲載価値があります。ただし、現時点ではインストール判断用のページとして非常に洗練されている段階ではありません。リポジトリには、一般的なプロンプトよりも迷いを減らして使える具体的なプロセス指針が十分にあり、特に決定論的なフィードバックループの構築と再現方法の選定に強みがあります。
- frontmatter で、手強いバグ、thrower/failure、パフォーマンス回帰の明確なトリガーと適用範囲が示されている。
- 運用面のガイダンスが強く、Reproduce → minimise → hypothesise → instrument → fix → regression-test の流れに沿って、成否ループの作り方まで具体的に示している。
- 人手を介した実行用の shell テンプレートがあり、対話的な再現ワークフローで agent が起動しやすくなる。
- 公開されている証拠は診断手法に寄っており、エンドツーエンドの全体ワークフローは見えていないため、導入時に一部の実行詳細を補う必要があるかもしれない。
- 実験的なテストシグナルであることと、SKILL.md に install コマンドがないことから、成熟した skill よりも導入がやや手軽ではない可能性がある。
diagnose skill の概要
diagnose skill は何のためのものか
diagnose skill は、バグの原因がつかみにくいとき、テストが不安定なとき、あるいは性能が劣化していて原因を確実に切り分けたいときのための、構造化されたデバッグワークフローです。単なる debug this プロンプト以上のものを求めるエージェントや開発者に向いています。症状の把握から再現、仮説立て、計測、修正、回帰テストまでを、再現性のある手順で進められるようにします。
どんな人がインストールすべきか
失敗が断続的に起きるコードベース、環境依存の不具合、または UI や本番相当のフローでしか表に出ない問題をよく扱うなら、diagnose skill の導入がおすすめです。特に Debugging では、ざっとコードを流し読みするだけでは足りず、実装に手を入れる前に合否のシグナルをきちんと作る必要があるプロジェクトで力を発揮します。
何が違うのか
diagnose skill の中心にあるのは、まず高速なフィードバックループを作ることです。ここが最大の差別化ポイントで、早すぎるコード変更よりも、再現性と観測可能性を優先します。また、プロジェクトの用語集や ADR を使うことを促すため、エージェントがモジュールの意図を推測ではなくドメイン言語に合わせて理解しやすくなります。
diagnose skill の使い方
diagnose skill をインストールする
リポジトリにある skill のインストールパスを使い、ローカルの skills ディレクトリに skill ファイルが揃っていることを確認してください。このリポジトリで案内されているインストールコマンドは次のとおりです。
npx skills add mattpocock/skills --skill diagnose
インストール後は、まず SKILL.md を開きます。そのうえで、ワークフローを形作る補助ファイルも確認してください。特に重要なのは scripts/hitl-loop.template.sh と、用語・アーキテクチャ・テスト境界を説明しているプロジェクト固有のドキュメントです。
あいまいなバグを、よい diagnose プロンプトに変える
diagnose skill は、具体的な症状、発生箇所、成功条件が入っているほど強く機能します。弱いプロンプトは「これを診断して」です。より強いプロンプトは、たとえば次のようになります。
「staging で export ボタンがときどき失敗する理由を診断してください。ブラウザで再現し、手順を最小化し、問題がサーバー側かクライアント側かを切り分け、可能なら回帰テストも追加してください。」
diagnose の利用時は、次を含めてください。
- 観測されている失敗の形
- それが起きる環境
- すでに判明している成功例・失敗例
- テスト、dev server、browser harness を実行できるかどうか
最初に読むべきおすすめのワークフローとファイル
まず SKILL.md でループ全体を把握し、バグの再現に人の操作が必要なら scripts/hitl-loop.template.sh を読みます。この script は、エージェントがユーザーに手順をクリックしてもらったり、エラーを取得したり、挙動確認をしてもらい、その結果を解析する必要がある場面で役立ちます。
実践的なワークフローは次のとおりです。
- 失敗する範囲をできるだけ狭く特定する
- 決定的なシグナルを作る
- 仮説は一つずつ検証する
- シグナルが不明瞭な箇所だけを計測する
- 回帰テストまたは再実行可能な harness で修正を固定する
出力を大きく改善するコツ
Debugging の結果をより良くしたいなら、使ってよいツールをエージェントに明示してください。たとえば unit tests、CLI commands、HTTP requests、browser automation、取得済み trace の replay などです。また、不具合が deterministic なのか、flaky なのか、performance-related なのかも伝えてください。ループの作り方が変わるためです。観測できるシグナルが具体的であるほど、エージェントが推測に費やす時間は減ります。
diagnose skill の FAQ
diagnose は普通の debug プロンプトより優れているか
多くの場合は yes です。特に、問題の再現が難しい場合や複数レイヤーにまたがる場合は有効です。通常のプロンプトだとすぐにコード変更へ進みがちですが、diagnose は先に証拠を作るよう設計されており、flaky bugs や regressions に対してより安全です。
diagnose を使わないほうがよいのはいつか
構文エラーが明らかな場合、見れば分かる null check の不足、あるいは 1 ファイルだけの小さな修正で、失敗原因がすでに完全に分かっている場合には使わないでください。そのようなケースでは、フルの diagnose ガイドはオーバーヘッドのほうが大きくなりがちです。
diagnose skill は初心者向けか
症状をはっきり説明でき、提案されたチェックを実行できるなら、初心者でも使えます。特に、バグがどこにあるか分からないときに有用で、深い事前知識を要求するのではなく、調査に構造を与えてくれます。
diagnose はどんな stack にも合うか
test、script、browser check、replayable input などで成功・失敗を観測できる stack には、たいてい適しています。一方で、成功か失敗かを決定的に観測する方法がない system では効果が下がります。skill は信頼できる feedback loop に依存しているからです。
diagnose skill をどう改善するか
skill に強い最初のシグナルを与える
最も効く改善は、再現情報をより具体的にすることです。「アプリが壊れている」ではなく、正確な操作、data shape、期待結果と実際の結果を示してください。logs、失敗する URL、payload sample、最小限の fixture があるなら、最初から添えるとよいです。
根本原因を求める前に、あいまいさを減らす
複数の失敗候補があるなら、まずどれを診断したいのかを明示してください。たとえば、「ボタンを押しても何も起きない」と「request が 500 を返す」と「ページが遅い」は分けて考えます。diagnose は、最初の問題定義が一つの観測可能な失敗パターンに対応しているときに最も強く機能します。
最初の出力を、次の実験選びに使う
最初の結果が出たら、次のどれかに答える形で diagnose skill の成果をさらに良くできます。再現が決定的になったか、仮説によって探索範囲が狭まったか、あるいは別のシグナルが必要か、です。まだあいまいなら、広い説明をもう一度求めるのではなく、より小さな harness、別の test seam、または browser/CLI replay path を依頼してください。