実戦テンプレート集──Plan、Work、Review、Compoundをそのまま貼って使う

ここまで、AIエージェントを開発工程に入れる方法を分けて書いてきました。

Plan。
Work。
Review。
Compound。
sandbox。
tools。
調査。
Codex App。

今回はテンプレート集です。

考え方だけでは、毎日の作業に戻りにくい。

だから、貼って使える形にします。

そのまま使ってもいいですし、自分のリポジトリに合わせて削ってもいいです。

使い方

テンプレートは、全部を毎回使うものではありません。

タスクに合わせて選びます。

調査だけしたい     -> read-only investigation
仕様を整理したい   -> spec draft
小さく実装したい   -> limited implementation
検品したい         -> diff review
障害を調べたい     -> incident investigation
画面を見せたい     -> screen review
次回に残したい     -> compound note

大事なのは、最初から実装に飛ばないことです。

1. read-only調査

このタスクは read-only 調査です。
まだファイルを変更しないでください。

目的：
- `<調べたいこと>` を理解する。

読んでよいもの：
- 関連コード
- 関連テスト
- docs
- issue / PR
- logs

禁止：
- ファイル変更
- package追加
- migration作成
- 外部サービスへの書き込み

出力：
1. 調査したファイル
2. 現在の処理の流れ
3. 事実
4. 仮説
5. 未確認のこと
6. 変更が必要そうな場所
7. 実装前に確認すべきリスク

2. 実装前Plan

まだ実装しないでください。
まず実装Planだけ作ってください。

目的：
- `<やりたいこと>`

非目的：
- `<今回はやらないこと>`

制約：
- API変更なし
- DB schema変更なし
- unrelated refactorなし
- 変更対象は最小にする

出力：
1. 触るファイル
2. 触らないファイル
3. 実装手順
4. 必要なテスト
5. リスク
6. 止まるべき条件

3. 仕様書作成

以下の要求から、AIエージェントに渡す仕様書を作ってください。

要求：
- `<要求を書く>`

仕様書に含めるもの：
- 目的
- 非目的
- 背景
- 変更範囲
- 入力文脈
- 受け入れ条件
- テスト条件
- 停止条件

注意：
- 曖昧な部分は勝手に決めず、未決定として分ける。
- 実装指示ではなく、作業境界として書く。

4. 小さな実装

以下の範囲だけ実装してください。

目的：
- `<目的>`

変更してよいファイル：
- `<file 1>`
- `<file 2>`

変更しないファイル：
- `<file>`

やること：
- `<小さな実装内容>`

やらないこと：
- refactor
- package追加
- API変更
- DB変更

実行するテスト：
- `<test command>`

失敗した場合：
- 原因を説明してから修正する。
- 今回の変更範囲外なら、修正せず止まる。

5. failing testだけ追加

まだ実装は変更しないでください。
まず今回のバグを再現する failing test だけ追加してください。

出力：
- 追加したテスト
- 何を再現しているか
- 期待結果
- 現在の失敗内容
- このテストが最小ケースである理由

禁止：
- 実装修正
- snapshot大量更新
- 既存テスト削除

6. 障害調査

これは障害調査です。
まだ修正しないでください。

入力：
- error:
- time range:
- request id:
- recent change:

出力：
1. Timeline
2. Facts
3. Hypotheses
4. Reproduction steps
5. Missing information
6. Smallest failing test candidate
7. Risk before fix

止まる条件：
- production DB write が必要
- secret / PII が必要
- 原因候補が絞れない
- 修正範囲が認証、課金、権限に広がる

7. ログ読み

以下のログを読んでください。
原因断定はまだしないでください。

出力：
- 明確な事実
- request id でつながるイベント
- エラー直前の変化
- 関係ありそうな行
- 関係が薄そうな行
- 追加で必要なログ
- 原因候補

注意：
- 推測は推測として書く。
- secret / PII は表示しない。

8. diff review

この diff を review してください。

見るもの：
- 仕様に合っているか
- 変更範囲が広すぎないか
- 既存パターンに沿っているか
- テストが足りているか
- 既存挙動を壊していないか
- 認証、権限、DB、課金に触っていないか
- 不要な refactor が混ざっていないか

出力：
- Blocker
- Should fix
- Nit
- 良い点
- 追加テスト候補
- 人間が判断すべき点

9. UI / screen review

この画面を review してください。
まだ修正しないでください。

見るもの：
- text overflow
- mobile layout
- loading state
- empty state
- error state
- keyboard 操作
- 既存デザインとの違い

出力：
- 画面上の事実
- 原因候補
- 疑うべきファイル
- 最小修正案
- 修正前に確認すべきこと

10. tool使用前確認

外部 tool を使う前に、次を出してください。

- tool name
- 操作内容
- 対象
- read / write / destructive の分類
- 外部状態がどう変わるか
- 戻し方
- 実行しない場合の影響

人間が確認するまで実行しないでください。

11. DB read-only調査

DBを read-only で調査してください。

許可：
- staging DB
- read-only query
- row limit 100
- non-PII table

禁止：
- production DB
- write query
- migration
- PII column
- data repair

出力：
- 見た table
- query の要約
- 分かったこと
- 未確認のこと
- 修正が必要ならコード変更案だけ

12. PRコメント下書き

PRコメントの draft を作ってください。
投稿はしないでください。

含めるもの：
- 何が問題か
- なぜ問題か
- どこを見るべきか
- 修正案
- 追加テスト案

文体：
- 短く
- 攻撃的にしない
- 判断と質問を分ける

13. AGENTS.md更新案

今回の作業から、AGENTS.md に戻すべきルールを提案してください。

分けるもの：
- repo-wide rule
- 今回だけのメモ
- checklist に入れる項目
- test に落とす項目
- skill にする候補

注意：
- 抽象的な精神論にしない。
- agent が実行できる行動として書く。
- 長くなりすぎる場合は guide / skill に分ける。

14. Compound Note

今回の作業を Compound Note にしてください。

形式：

## What happened

## What failed / worked

## Pattern

## Return to

- AGENTS.md:
- checklist:
- test:
- INDEX.md:
- runbook:
- skill:

## Do not persist

- 今回だけの情報

15. Codex App project調査

この project を read-only で調査してください。
まだ変更しないでください。

出力：
- 主要ディレクトリ
- アプリの入口
- テストコマンド
- docs
- AGENTS.md / INDEX.md の有無
- 最初に整備した方がよい文脈
- 注意すべきファイル

16. 非エンジニア向けバグ報告作成

この画面とメモから、開発者に渡すバグ報告を作ってください。

含めるもの：
- 何をしようとしたか
- 操作手順
- 期待結果
- 実際の結果
- 再現条件
- 画面から読み取れるエラー
- 追加で必要そうな情報

注意：
- 事実と推測を分ける。
- 技術的に断定しない。
- 開発者が次に調査できる形にする。

17. 導入前チェック

この作業を AIエージェントに任せてよいか判定してください。

見るもの：
- 失敗時の影響
- 必要な権限
- テストしやすさ
- 仕様の明確さ
- review しやすさ
- rollback しやすさ
- secret / PII の有無

出力：
- 任せてよい
- 下書きまで
- 調査だけ
- 任せない
- 理由
- 安全に任せるための条件

18. 作業終了時チェック

作業終了前に確認してください。

- diff は目的に合っているか
- unrelated change はないか
- テストは実行したか
- 失敗したテストを説明したか
- 変更範囲外の問題を勝手に直していないか
- 外部tool使用ログは残っているか
- 次回に戻すべき学びはあるか

まとめ

テンプレートは、agent を縛るためだけのものではありません。

人間の判断を楽にするためのものです。

毎回同じ説明をしない。
毎回同じ失敗を見ない。
毎回同じ review をしない。

よく使う依頼はテンプレートにする。

繰り返す確認は checklist にする。

毎回効かせたいルールは AGENTS.md に戻す。

この流れができると、AIエージェントは単発の道具ではなく、開発工程の中で扱える作業者になります。