writing-investigation-log

Files (3)

• SKILL.md
• investigation-log-example.md · references/
• investigation-log-template.md · references/

SKILL.md (first lines)

# Writing Investigation Log

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

<important>

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

</important>

## 保存先

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

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

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

## 手順

<procedure>

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. ユーザーへ能動的に報告しない
   - 調査ログを残したことを、通常の完了報告に含めない
   - ユーザーから「この部分の根拠は?」などと明示的に聞かれたときだけ、調査ログを参照して根拠を答える

</procedure>

## 記録の粒度

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

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

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

## テンプレート

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

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

From syou6162/agent-skills, MIT.

More from syou6162/agent-skills