ここまで、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エージェントは単発の道具ではなく、開発工程の中で扱える作業者になります。