Writing Investigation Log Skill

Writing Investigation Log

調査や裏取りの結果を、後続のエージェントが再利用できる内部ログとして残すスキルです。ユーザー向けの清書用Markdownや資料本文に、調査ログ、試行錯誤、コマンド履歴を混ぜないために使います。

調査したら、ユーザーが明示しなくても .agent_work/investigations/ に記録すること
調査ログはユーザー向け成果物ではなく、エージェント向けの内部作業ログとして扱うこと
清書用ドキュメント、提案書、発表資料、PR本文、esaやNotionに貼る本文には調査ログを混ぜないこと
結論だけを書かず、根拠URL、ローカルパス、実行コマンド、クエリ、結果、未確認事項を残すこと
調査結果、確認したこと、結論、未確認事項は日本語で書くこと。URL、コマンド、クエリ、引用は原文のままでよい
推測と確認済みを混ぜないこと。根拠が弱い内容は「未確認」または「推測」と明記すること
シークレット値やトークン値は記録しないこと。存在確認やマスク済みの状態だけを書くこと

</important>

保存先

調査ログは以下に保存します。

.agent_work/
  investigations/
    <topic>.md

<topic> は短い英数字とハイフンのファイル名にします。例:

conformed-fact-usage.md
periodic-snapshot-examples.md
planned-work-minutes-definition.md

既存の .claude_work は過去作業の参照対象にはなり得ますが、新規の標準保存先には使いません。

発動タイミング

以下を行うときは、このスキルを使って調査ログを作成または更新します。

GitHub PR、Issue、review comment、file permalink を調べる
esa、Notion、公式ドキュメント、社内ドキュメント、Webページを調べる
rg、git、gh、bq、SQL、MCP tool などで裏取りする
BigQueryなどにクエリを投げる
資料、設計判断、レビュー、計画、PR説明の根拠になる情報を集める
同じ調査を繰り返しそうなとき
コンテキスト圧縮やhandoffの有無に関係なく、調査をしたとき

短い事実確認でも、後から根拠として使うなら記録します。単なるファイル一覧確認や一時的な作業で、後続の判断材料にならないものは省略して構いません。

手順

既存ログを確認する
- .agent_work/investigations/ に同じトピックのログがないか確認する
- 既存ログがある場合は追記または更新し、重複ファイルを増やさない
テンプレートを使う
- 新規作成時は references/investigation-log-template.md の構成に従う
- テンプレートの見出しは、不要なものを消さず「該当なし」と書く
- 記入粒度に迷う場合は references/investigation-log-example.md を参照する
調査の問いを先に書く
- 何を確認する調査なのか
- どの成果物、判断、資料、レビューに使う根拠なのか
根拠を記録する
- GitHub PRはフルURLで書く
- GitHub fileは可能な限りbranchのblob URLではなく、行番号付きpermalinkや該当commitのURLを書く
- esa、Notion、公式docs、WebページはURLと確認した内容を書く
- ローカルファイルはパスと確認した行や内容を書く
コマンドやクエリを記録する
- 実行したコマンド、クエリ、MCP tool、主要な引数を残す
- BigQueryなどのクエリは、クエリ本文と結果をセットで残す
- 結果が長い場合は、重要な出力と保存先を書く
結論と限界を書く
- 結果から直接言えることを書く
- 結果からは言えないこと、未確認事項、追加調査が必要な点を書く
ユーザーへ能動的に報告しない
- 調査ログを残したことを、通常の完了報告に含めない
- ユーザーから「この部分の根拠は?」などと明示的に聞かれたときだけ、調査ログを参照して根拠を答える

</procedure>

記録の粒度

1つの調査トピックにつき1ファイルを基本にします。会話ログ、清書本文、調査メモを同じMarkdownに混ぜないでください。

調査ログには、以下を優先して残します。

その調査で確認した問い
根拠URLやローカルパス
実行したコマンドやクエリ
重要な出力やクエリ結果
そこから言えること
そこからは言えないこと

テンプレート

新規ログは references/investigation-log-template.md を参照して作成します。

記入粒度に迷う場合は references/investigation-log-example.md を参照します。

Agent Skills: Writing Investigation Log

Install this agent skill to your local

Skill Files