writing-investigation-log

Writing Investigation Log

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

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

保存先

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

.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の有無に関係なく、調査をしたとき

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

手順

1. 既存ログを確認する

   • .agent_work/investigations/ に同じトピックのログがないか確認する
   • 既存ログがある場合は追記または更新し、重複ファイルを増やさない

2. テンプレートを使う

   • 新規作成時は references/investigation-log-template.md の構成に従う
   • テンプレートの見出しは、不要なものを消さず「該当なし」と書く
   • 記入粒度に迷う場合は references/investigation-log-example.md を参照する

3. 調査の問いを先に書く

   • 何を確認する調査なのか
   • どの成果物、判断、資料、レビューに使う根拠なのか

4. 根拠を記録する

   • GitHub PRはフルURLで書く
   • GitHub fileは可能な限りbranchのblob URLではなく、行番号付きpermalinkや該当commitのURLを書く
   • esa、Notion、公式docs、WebページはURLと確認した内容を書く
   • ローカルファイルはパスと確認した行や内容を書く

5. コマンドやクエリを記録する

   • 実行したコマンド、クエリ、MCP tool、主要な引数を残す
   • BigQueryなどのクエリは、クエリ本文と結果をセットで残す
   • 結果が長い場合は、重要な出力と保存先を書く

6. 結論と限界を書く

   • 結果から直接言えることを書く
   • 結果からは言えないこと、未確認事項、追加調査が必要な点を書く

7. ユーザーへ能動的に報告しない

   • 調査ログを残したことを、通常の完了報告に含めない
   • ユーザーから「この部分の根拠は?」などと明示的に聞かれたときだけ、調査ログを参照して根拠を答える

記録の粒度

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

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

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

テンプレート

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

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