mcpField
D
diagnose

diagnose

github.com/akillness開発5356 回インストール今日更新
リポジトリ

diagnose について

難解な不具合、断続的な失敗、性能問題を調査する 6 段階のスキルです。まず迅速で決定性のあるフィードバックループを作り、その後に仮説検証と修正を進めます。

主な機能

  1. 01迅速な合否フィードバックの構築
  2. 02障害の安定した再現
  3. 03反証可能な仮説の順位付け
  4. 04仮説に絞った検査の実施
  5. 05修正と回帰の検証
  6. 06原因と予防策の記録

活用シーン

  1. 01すぐに直せない不具合の調査
  2. 02性能低下の原因特定
  3. 03断続的な失敗の証拠収集

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/akillness/jeo-skills --skill diagnose

インストール後、Claude Code で/diagnoseを入力して読み込まれたか確認します。

詳細

診断

体系的なバグ調査のための6フェーズのループです。重要なポイントは、フェーズ1に通常よりも多くの労力を費やすことです。信頼できるフィードバックループがあれば、フェーズ2〜6は機械的に進められます。

このスキルを使用する場面

  • すぐに修正できない難しいバグ
  • 根本原因が不明なパフォーマンスのリグレッション
  • 複数回の実行による証拠が必要な不安定な失敗
  • 過去の修正が失敗したあらゆる問題

このスキルを使用しない場面

  • 根本原因が明らかな、すぐに対応できる的を絞った修正 → debugging を使用します
  • 症状から始めるログのトリアージ → log-analysis を使用します
  • テスト方針の広範な設計 → testing-strategies を使用します

6つのフェーズ

フェーズ1 — フィードバックループを構築する（まずここに注力）

バグの合否を素早く、確定的かつ自動的に判定できる仕組みを作成します。

Goal: < 10 second feedback cycle
Signal: automated pass/fail, not manual inspection
Determinism: same input → same result every time

自問してください。「1つのコマンドを実行するだけで、10秒以内にバグの有無がわかるだろうか？」

  • まだ存在しない場合は、失敗するテストを書きます
  • 最小限の再現スクリプトを作成します
  • トリガーを、可能な限り小さな入力に絞り込みます
  • 失敗が明白で、観測できるようにします

フィードバックループの信頼性が確保されるまで、フェーズ2に進まないでください。

フェーズ2 — 再現する

管理された条件下で、失敗が再現可能であることを確認します。

  • フィードバックループを複数回実行し、再現性を確認します
  • 入力、環境、手順を正確に記録します
  • これが新たな挙動（リグレッション）なのか、以前から常に壊れていたのかを特定します
フェーズ3 — 仮説を立てる

根本原因について、可能性の高い順に仮説を立てます。

  • 原因候補を2〜4個、可能性の高い順に列挙します
  • 各仮説は反証可能でなければなりません
  • 最も興味深いものではなく、最も可能性の高いものから始めます
H1 (most likely): [specific cause]
H2: [alternative cause]
H3: [edge case cause]
フェーズ4 — 計測する

各仮説を見分けるためのチェックを1つずつ実行します。

  • 有用な範囲で最も狭い箇所に、ログ、アサーション、ブレークポイントを追加します
  • フィードバックループを使い、各仮説を素早く検証します
  • 証拠を記録します：確認済み／反証済み／結論なし
  • 仮説が反証されたら、次の仮説に進みます
フェーズ5 — 修正してテストする

修正を適用し、ループが閉じることを検証します。

  • 可能であれば、修正前にリグレッションテストを書きます
  • 根本原因に対処する最小限の変更を適用します
  • 対象のテストだけでなく、テストスイート全体を実行します
  • フィードバックループが正常に通過することを確認します
フェーズ6 — クリーンアップと事後分析
  • 診断用の計測コードを削除します
  • 根本原因と、それが意外だった理由を記録します
  • コードベースのほかの場所にも同様のパターンがないか特定します
  • 予防的なチェック（リンタールール、テスト、アサーション）を導入することで、この種のバグを自動的に検出できるか検討します

クイックリファレンス

# Phase 1: make the feedback loop
# Write a failing test or minimal repro script

# Phase 4: instrument at the narrowest point
console.error('[diagnose] value at boundary:', value)

# Phase 5: verify fix closes the loop
npm test -- --testPathPattern=failing-test

手順

  1. タスクのきっかけと期待される出力を特定します。
  2. このスキルのワークフロー手順に、最初から最後まで従います。
  3. 次のステップに進む前に、出力を検証します。
  4. いずれかのステップで失敗した場合は、ブロッカーと代替手段を記録します。

例

  • 例：まず小さな範囲でこのスキルを適用し、検証に合格してから全体の範囲に拡大します。

ベストプラクティス

  • 出力の再現性と監査可能性を確保します。
  • 広範でリスクの高い編集より、小規模で元に戻せる変更を優先します。
  • 前提を明示的に記録します。

参考資料

  • プロジェクト標準：.agent-skills/skill-standardization/SKILL.md
  • バリデータースクリプト：.agent-skills/skill-standardization/scripts/validate_skill.sh

コメント

Markdown 対応