mcpField
I
investigation-notes

investigation-notes

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

investigation-notes について

バグ調査を行うコーディングエージェント向けの軽量なメモスキルです。注目点、仮説、コード読解やテストの結果を記録し、作業の重複や調査の脱線を抑えます。

主な機能

  1. 01注目点と仮説の記録
  2. 02コード読解とテスト結果の追跡
  3. 03同時に扱う仮説数の制限
  4. 04テストの作成と実行を優先

活用シーン

  1. 01複数の原因候補があるバグの調査
  2. 02テスト反復をまたいだ知見の記録

インストール

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

$npx skills add https://github.com/cloudflare/workerd --skill investigation-notes

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

詳細

調査メモ

概要

バグを調査する際は、外部メモとして軽量な作業用ドキュメントを維持してください。これにより、すでに分析したコードを読み直したり、検証中の仮説を見失ったり、知らないうちに寄り道へ逸れたりするのを防げます。

基本原則： 一度書き留めて、後から参照します。1行のメモを読み直すほうが、ソースコード200行を読み直すより速いです。

現在の作業対象、仮説、コードの読み取りやテストから得た知見を、常にドキュメントに反映してください。

コードを読み直したり新しい仮説を立てたりする前に、必ずドキュメントを参照してください。情報が記載されていれば、それを使います。不十分であればコードを読み、その後、より適切なメモを書きます。

ドキュメントの更新を、テストの作成や実行より優先してはいけません。 メモの更新とテストの作成で迷ったら、テストを書いてください。メモはその後に更新します。

ドキュメント

/investigate のステップ2（状況把握）で、~/tmp/investigate-<short-name>.md を作成します。

短い名前は、調査内容を特定できる程度に具体的なものにしてください（例： investigate-concurrent-write.md、investigate-pipe-zombie-state.md）。

作成したらユーザーに知らせ、エディターで開けるようファイルパスを提示してください。

書式
# Investigation: <one-line bug description>

## Error

<assertion/crash message, file:line — written once, never changes>

## Current Focus

<single sentence: what you are doing RIGHT NOW>

## Hypotheses

1. [TESTING] <one sentence> — test: <test name or "not yet written">
2. [REJECTED] <one sentence> — disproved by: <one sentence>
3. [CONFIRMED] <one sentence> — evidence: <test name + result>

## Code Read

- `file:line-range` — <what you learned, short paragraph or bullet>

## Tests

- `file:line` "test name" — <result + what it means, one sentence>

## Ruled Out

- <thing you investigated and eliminated, one sentence why>

## Next

1. <concrete next action>
2. <fallback>

作成

次の場合はドキュメントを作成してください。

  • 追跡する仮説が複数ある
  • 3つを超えるファイルや関数を読んだ
  • すでに読んだコードを読み直そうとしている
  • テストの作成と実行を複数回繰り返す調査になる

作成時には、Error、Current Focus、現在の仮説、すでに得た知見を記入してください（これまでに行った作業に基づき、「Code Read」と「Tests」も補完してください）。

ルール

  • 新しい作業に着手する前に、必ず「Current Focus」を更新してください
  • 作業内容に対する仮説を必ず追加してください
  • 重要なアクションの後は、必ずドキュメントを更新してください。
    • 関数やファイルの一部を読んだ後 → 「Code Read」に追加します
    • 仮説を立てたり棄却したりした後 → 「Hypotheses」を更新します
    • テストを実行した後 → ほかの作業に着手する前に更新してください。 実行したテスト、その結果、現在の仮説に対する意味を記録します。これは譲れないルールです。30秒ほどの作業で、複数のテストを実行して何が証明されたかを見失い、コードを読むだけに戻ってしまう流れを防げます。
    • 新しい作業に着手した後 → 「Current Focus」を更新します
  • ドキュメントに大量のコードを貼り付けないでください。代わりに file:line で参照してください。
  • ドキュメントの再構成や書式の変更はしないでください。これは報告書ではなく、作業用メモです。
  • 理解や記憶に役立つ場合は、簡潔でシンプルな図を含めてもかまいません。

仮説の上限

  • 同時に有効にできる仮説は最大3つです。4つ目を追加する場合は、先にいずれかを棄却するか、統合してください。
  • [TESTING] にできる仮説は同時に1つまでです。1つに絞ってテストし、結論を出してから次に進んでください。
  • すべての仮説には、テストまたは具体的なテスト作成計画が必要です。「さらに調査が必要」は有効な状態ではありません。分析麻痺にラベルを貼っただけです。

有効なステータス：

  • [UNTESTED] — 仮説を立てたが、まだテストしていない状態。すみやかに [TESTING] または [REJECTED] にしてください。
  • [TESTING] — 現在テスト中の状態。同時に1つだけです。
  • [CONFIRMED] — テストで予測どおりにバグが再現した状態。
  • [REJECTED] — テストで反証された、または証拠によって除外された状態。その理由も記載してください。
  • [SUPERSEDED] — より具体的な仮説に置き換えられた状態。置き換え先も参照してください。

コメント

Markdown 対応