syou6162 Writing Investigation Log
調査や裏取りの結果を、後続のエージェントが再利用できる内部ログとして残すスキルです。ユーザー向けの清書用Markdownや資料本文に、調査ログ、試行錯誤、コマンド履歴を混ぜないために使います。
- 調査したら、ユーザーが明示しなくても
.agent_work/investigations/に記録すること - 調査ログはユーザー向け成果物ではなく、エージェント向けの内部作業ログとして扱うこと
- 清書用ドキュメント、提案書、発表資料、PR本文、esaやNotionに貼る本文には調査ログを混ぜないこと
- 結論だけを書かず、根拠URL、ローカルパス、実行コマンド、クエリ、結果、未確認事項を残すこと
- 調査結果、確認したこと、結論、未確認事項は日本語で書くこと。URL、コマンド、クエリ、引用は原文のままでよい
- 推測と確認済みを混ぜないこと。根拠が弱い内容は「未確認」または「推測」と明記すること
- シークレット値やトークン値は記録しないこと。存在確認やマスク済みの状態だけを書くこと
保存先
調査ログは以下に保存します。
.agent_work/
investigations/
<topic>.md
<topic> は短い英数字とハイフンのファイル名にします。例:
conformed-fact-usage.mdperiodic-snapshot-examples.mdplanned-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などのクエリは、クエリ本文と結果をセットで残す
- 結果が長い場合は、重要な出力と保存先を書く
結論と限界を書く
- 結果から直接言えることを書く
- 結果からは言えないこと、未確認事項、追加調査が必要な点を書く
ユーザーへ能動的に報告しない
- 調査ログを残したことを、通常の完了報告に含めない
- ユーザーから「この部分の根拠は?」などと明示的に聞かれたときだけ、調査ログを参照して根拠を答える
記録の粒度
1つの調査トピックにつき1ファイルを基本にします。会話ログ、清書本文、調査メモを同じMarkdownに混ぜないでください。
調査ログには、以下を優先して残します。
- その調査で確認した問い
- 根拠URLやローカルパス
- 実行したコマンドやクエリ
- 重要な出力やクエリ結果
- そこから言えること
- そこからは言えないこと
テンプレート
新規ログは references/investigation-log-template.md を参照して作成します。
記入粒度に迷う場合は references/investigation-log-example.md を参照します。