mcpField
R
root-cause-tracing

root-cause-tracing

github.com/bobmatnyc開発78377 回インストール15 週間前に更新
リポジトリ

root-cause-tracing について

呼び出し経路の深い箇所に現れるエラーを調査するデバッグスキルです。経路をさかのぼって最初の引き金を特定し、発生源で修正したうえで各層に検証を加えます。

主な機能

  1. 01呼び出し経路の逆追跡
  2. 02最初の引き金の特定
  3. 03発生源での修正
  4. 04各層への検証追加

活用シーン

  1. 01実行の深い箇所で起きるエラーの調査
  2. 02不正なデータの発生元の特定
  3. 03障害を引き起こすテストの追跡

インストール

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

$npx skills add https://github.com/bobmatnyc/claude-mpm-skills --skill root-cause-tracing

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

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

metadata.json
references/
advanced-techniques.md
examples.md
integration.md
tracing-techniques.md

詳細

根本原因の追跡

概要

バグは、コールスタックの深い場所で現れることがよくあります（間違ったディレクトリでの git init、間違った場所へのファイル作成、間違ったパスでのデータベースのオープンなど）。エラーが現れた場所を修正したくなりますが、それでは症状への対処にすぎません。

基本原則： 呼び出しチェーンをさかのぼり、元のトリガーを見つけてから、発生源を修正します。

このスキルは、体系的なデバッグのワークフローにおける専門的な手法です。通常、深いコールスタックに対処する際、フェーズ 1（根本原因の調査）で適用します。

このスキルを使う場面

根本原因の追跡を使う場面：

  • 実行の深い箇所でエラーが発生する（エントリポイントではない）
  • スタックトレースに長い呼び出しチェーンが示されている
  • 無効なデータがどこで発生したのか不明
  • 問題を引き起こすテストやコードを見つける必要がある
  • 症状が実際の原因から遠く離れた場所に現れる

体系的なデバッグとの関係：

  • systematic-debugging：全体的なフレームワーク（フェーズ 1～4）
  • root-cause-tracing：フェーズ 1 の調査で使う具体的な手法
  • systematic-debugging のフェーズ 1 内で root-cause-tracing を使う

鉄則

NEVER FIX JUST WHERE THE ERROR APPEARS
ALWAYS TRACE BACK TO FIND THE ORIGINAL TRIGGER

症状を修正すると、根本的な問題を覆い隠す、その場しのぎの解決策になります。

基本原則

  1. さかのぼって追跡する：症状から発生源まで呼び出しチェーンをたどります
  2. 元のトリガーを見つける：不正なデータや状態がどこで発生したかを特定します
  3. 発生源を修正する：症状ではなく、根本原因に対処します
  4. 多層防御：発生源を修正した後、各層に検証を追加します

クイックスタート

5 ステップの追跡プロセス
  1. 症状を確認する：どのようなエラーメッセージですか？どの操作に失敗しましたか？
  2. 直接の原因を特定する：このエラーを直接引き起こしているコードは何ですか？
  3. これを呼び出したものを確認する：コールスタックを 1 レベル上にさかのぼります
  4. さらにさかのぼって追跡する：元のトリガーを見つけるまで続けます
  5. 発生源を修正して防御する：根本原因を修正し、各層に検証を追加します
判断ツリー
Error appears deep in stack?
  → Yes: Start tracing backward
    → Can identify caller? → Trace one level up → Repeat
    → Cannot identify caller? → Add instrumentation (see advanced-techniques.md)
  → No: May not need tracing (error at entry point)

追跡プロセス

例：間違ったディレクトリでの Git 初期化

Error symptom → execFileAsync('git', ['init'], { cwd: '' })
  ← WorktreeManager.createSessionWorktree(projectDir='')
  ← Session.create() → Project.create() → Test code
  ← ROOT CAUSE: setupCoreTest() returns { tempDir: '' } before beforeEach

各レベルで確認すること： この値はどこから来ましたか？ここが発生源ですか？

詳細な追跡方法については、追跡手法を参照してください。 実際の例については、例を参照してください。

根本原因を見つけた後

発生源を修正する（初期化前にアクセスされた場合は例外をスローする）とともに、多層防御を追加する（Project.create、WorkspaceManager、環境ガード、計装で検証する）。

これにより、同様のバグを防ぎ、問題を早期に検出できます。

ナビゲーション

詳細については、以下を参照してください。

  • 追跡手法：追跡方法、パターン、判断ツリーの全容
  • 例：追跡チェーン全体を示した、実際のデバッグシナリオ
  • 高度な手法：スタックトレース、計装、テスト汚染の検出
  • 連携：体系的なデバッグやその他のスキルとの併用方法

主な注意事項

  • エラーが現れた場所だけを修正してはいけません
  • 必ず元のトリガーを見つけるためにさかのぼって追跡してください
  • テストでのデバッグには console.error() を使ってください（logger は出力が抑制されている場合があります）
  • 危険な操作の後ではなく、実行前にログを記録してください
  • ディレクトリ、cwd、環境、タイムスタンプなどのコンテキストを含めてください
  • 発生源を修正した後、多層防御を追加してください
  • 追跡しながら記録してください（呼び出しチェーンを書き留めます）

危険信号 — 中止

次のように考えたら、作業を中止してください。

  • 「ここに検証を追加すればいいだけだ」（発生源を見つけずに）
  • 「これでエラーを防げる」（症状への対処）
  • 「さかのぼって追跡するのは難しすぎる」（代わりに計装を追加する）
  • 「とりあえずの簡単な修正をする」（技術的負債を生む）

いずれの場合も、根本原因を見つけるために追跡を続けてください。

他のスキルとの連携

  • systematic-debugging：フェーズ 1 で根本原因の追跡を行います
  • defense-in-depth：根本原因の特定後に追加します
  • verification-before-completion：ソースで修正が機能したことを検証します
  • test-driven-development：症状ではなく、根本原因を対象としたテストを作成します

完全なワークフローの例については、Integration をご覧ください。

実社会への影響

デバッグセッション（2025-10-03）より：

  • 5 段階の追跡で根本原因を発見しました
  • ソース（getter の検証）で修正しました
  • 4 層の防御を追加しました
  • 1847 件のテストが合格し、汚染はゼロでした
  • 時間の節約：症状を修正するアプローチと比べて 3 時間以上

**要点：**追跡には 15～30 分かかります。症状の修正には、モグラたたきのような対応で何時間もかかります。

コメント

Markdown 対応