AIエージェントに仕事を頼むとき、多くの人はすぐ実装を頼みます。
このバグを直して。
この機能を追加して。
このエラーを解決して。
もちろん、動くこともあります。
でも既存リポジトリでは、いきなり実装に入るほど事故が増えます。
似た名前のファイルがある。
古い実装が残っている。
テストの入口が分かりにくい。
仕様が issue、PR、Slack、docs に散っている。
ログに出ているエラーと本当の原因が違う。
小さな修正に見えて、実は認証やDBに触る。
こういう場所で、agent にいきなり直させると、速く迷います。
第5回では、MCP と tools の権限を分けました。
今回は、コードを書く前の使い方です。
読ませる。
整理させる。
再現させる。
仮説を出させる。
止まるべきところで止める。
実装より前の工程で agent を使えるようになると、既存リポジトリでの安定感がかなり変わります。
まず「修正」ではなく「調査」を頼む
最初の依頼を変えます。
悪い依頼です。
商品検索が壊れているので直してください。
これは、agent に調査、判断、実装、検証を全部まとめて渡しています。
良い依頼です。
商品検索が壊れている原因を調査してください。
まだファイルは変更しないでください。
出力してほしいもの：
- 関連しそうなファイル
- 既存の検索処理の流れ
- 既存テスト
- 再現に必要な条件
- ありそうな原因を3つ
- 追加で確認すべきこと
- 実装に入る前に止まるべきリスク
これなら、agent はまず読む役になります。
読むだけでも価値があります。
人間が30分かけて見ていた入口探しを、かなり短くできます。
ただし、ここではまだ直しません。
直す前に、地図を作らせます。
read-only調査の型
read-only 調査には、型があります。
## Investigation Task
Goal:
- 何を調べたいか
Do not:
- ファイルを変更しない
- package を追加しない
- migration を作らない
- 外部サービスへ書き込まない
Read:
- issue
- 関連docs
- 関連コード
- 関連テスト
- logs
Output:
- 調査したファイル
- 現在の処理の流れ
- 事実
- 仮説
- 未確認のこと
- 次に確認すべきこと
- 修正に入る前のリスク
ここで大事なのは、「事実」と「仮説」を分けることです。
agent は、もっともらしい説明を作るのが得意です。
だから、こう分けさせます。
## Facts
- `ProductSearch.tsx` は `useProductQuery` を呼んでいる。
- `useProductQuery` は URL query の `q` を読む。
- 既存テストは category filter のみを見ている。
## Hypotheses
- keyword と category を同時に使うと query builder が片方を上書きしているかもしれない。
- URL query と内部 state の同期がずれているかもしれない。
- API 側ではなく UI 側で空文字を送っているかもしれない。
## Unknowns
- 本番で起きている入力条件。
- category と keyword を同時に指定したログ。
- pagination と組み合わせた場合の挙動。
この出力なら、人間が判断できます。
「たぶんここです」と言われるより、ずっと扱いやすいです。
入口ファイルを探させる
既存リポジトリで最初に面倒なのは、入口探しです。
UIなら、画面の入口。
APIなら、route の入口。
バッチなら、job の入口。
DBなら、query の入口。
テストなら、既存ケースの入口。
agent には、まず入口を探させます。
この機能の入口を探してください。
実装はしないでください。
出力：
- UI entry
- API entry
- service / domain logic
- DB access
- tests
- docs
- 旧実装や触らない方がよいファイル
出力例です。
## Entry Points
UI:
- `app/products/page.tsx`
- `components/products/ProductSearch.tsx`
State:
- `hooks/useProductQuery.ts`
Service:
- `services/product-search.ts`
API:
- `app/api/products/route.ts`
DB:
- `repositories/product-repository.ts`
Tests:
- `tests/product-search.test.ts`
- `tests/product-list-ui.test.tsx`
Do not start here:
- `legacy/product-search-old.ts`
- `components/products/SearchBoxDeprecated.tsx`
これだけで、次の作業がかなり楽になります。
毎回この調査が出るなら、INDEX.md に戻します。
既存パターンを読ませる
次に、既存パターンです。
AIエージェントは、何も言わないと自分が書きやすい形で実装します。
でも既存リポジトリでは、揃える方が大事です。
実装前に、このリポジトリで同じ種類の処理がどう書かれているか調べてください。
見るもの：
- 似たUI
- 似たAPI
- 似たservice
- 似たtest
- error handling
- loading / empty state
出力：
- 既存パターン
- 今回も合わせるべき点
- 合わせない方がよい古い実装
出力例です。
## Existing Pattern
- filter state は URL query と同期する。
- service は plain object を受け取り、UI state を直接知らない。
- API route は validation 後に service を呼ぶ。
- empty state は `EmptyResult` component を使う。
- test は service の組み合わせ条件を先に見る。
## Avoid
- `legacy/` 以下の検索実装は古い。
- UI component 内で query string を直接組み立てない。
ここまで読ませてから実装に入ると、差分が既存設計に寄ります。
障害調査では時系列を作らせる
障害調査では、まず時系列です。
ログがあると、agent はすぐ原因を言いたがります。
でも、いきなり原因に飛ぶと危ない。
まず、何が起きたかを時系列にします。
以下のログとエラー報告を読んで、時系列を作ってください。
まだ原因断定はしないでください。
出力：
- 時刻
- 起きたこと
- 関連する request / user / job
- 事実
- 推測
- 追加で必要なログ
出力例です。
## Timeline
10:03
- deploy completed
- search API version changed
10:07
- first 500 error on `/api/products`
- only category + keyword combination failed
10:09
- retry succeeded for keyword-only request
10:12
- error count increased on mobile traffic
Facts:
- keyword-only request is not failing.
- category-only request is not failing.
- combined request fails.
Hypotheses:
- query builder composition issue.
- URL encoding issue on mobile.
- pagination default missing only in combined path.
この形なら、原因の候補を絞れます。
先に再現条件を作る
バグ修正でいちばん大事なのは、再現です。
再現できていないバグを直すと、たいてい広がります。
agent には、まず再現条件を作らせます。
まだ実装修正しないでください。
このバグを最小条件で再現する方法を作ってください。
出力：
- 再現手順
- 最小入力
- 期待結果
- 実際の結果
- 既存テストで足りない点
- 追加すべき failing test
再現テストだけ作らせるのも有効です。
実装は変更しないでください。
まず failing test だけ追加してください。
そのテストが今回の報告を再現している理由を説明してください。
これができると、修正の前に勝ち筋が見えます。
直したつもりで別の挙動を壊すことも減ります。
再現テストをreviewする
failing test を作らせたら、それも review します。
テストがあるから安心、ではありません。
agent が作ったテストは、実装の都合に寄ることがあります。
見るべき点はこれです。
## Reproduction Test Review
- 本当に報告されたバグを再現しているか。
- 実装詳細に寄りすぎていないか。
- 期待結果は仕様として正しいか。
- 既存テストと重複していないか。
- 最小ケースになっているか。
- 失敗理由が分かりやすいか。
- 修正後に回帰テストとして残せるか。
再現テストが弱いと、その後の修正も弱くなります。
だから、実装修正の前に test review を挟みます。
仮説を3つ出させる
障害調査では、仮説を1つに絞りすぎない方がいいです。
agent に最初から「原因は何？」と聞くと、1つの説明に寄りやすい。
代わりに、仮説を複数出させます。
原因候補を3つ出してください。
それぞれについて、支持する証拠、反証になる確認、次に見るファイルを書いてください。
出力例です。
## Hypothesis 1: query builder composition
Supports:
- combined filter only fails
- service recently changed
To disprove:
- direct service test with keyword + category passes
Next:
- `services/product-search.ts`
- `tests/product-search.test.ts`
## Hypothesis 2: URL state sync
Supports:
- mobile traffic has higher error rate
- UI path changed recently
To disprove:
- API request reproduced directly without UI
Next:
- `hooks/useProductQuery.ts`
- `components/products/ProductSearch.tsx`
## Hypothesis 3: pagination default
Supports:
- error only happens on combined query with page omitted
To disprove:
- request with explicit page still fails
Next:
- `repositories/product-repository.ts`
この形だと、次に何を見るべきかが決まります。
仮説は、説明ではなく調査の道具です。
ログを読ませるときの注意
ログを agent に渡すときは、そのまま大量に貼らない方がいいです。
まず、必要な範囲に切ります。
- 時刻範囲
- request id
- user id は必要なら匿名化
- error code
- deploy 前後
- 関連 service
そして、こう頼みます。
以下のログを読んでください。
原因断定はまだしないでください。
出力：
- 明確な事実
- 同じ request id でつながるイベント
- エラー直前の変化
- ノイズだと思われる行
- 追加で必要なログ
- 仮説
ログ読みで大事なのは、ノイズを分けることです。
agent は関係ありそうなものを拾いすぎることがあります。
だから、
今回の原因と関係なさそうなログも分けてください。
なぜ関係が薄いと判断したかも書いてください。
と頼みます。
関係あるものだけでなく、関係なさそうなものも分ける。
これで調査が少し締まります。
修正前レビューを挟む
調査、再現、仮説がそろったら、すぐ実装してもよさそうに見えます。
でも、その前に一度 review します。
まだ実装しないでください。
ここまでの調査結果を review してください。
見るもの：
- 事実と仮説が混ざっていないか
- 再現条件は十分か
- もっと小さい再現ケースにできないか
- 変更範囲は広すぎないか
- 触ってはいけない領域に入っていないか
- 先に確認すべきログやテストは残っていないか
これは地味ですが効きます。
実装前に一度止まるだけで、無駄な修正が減ります。
修正は最小単位にする
調査が終わっても、修正は小さくします。
まず service の query builder だけ修正してください。
UI は触らないでください。
テストは `tests/product-search.test.ts` だけ実行してください。
または、
まず failing test を通す最小修正だけしてください。
refactor はしないでください。
既存リポジトリでは、正しい修正でも広がりすぎると review が難しくなります。
だから、最小修正と改善を分けます。
今回：
- bug fix
- 回帰テスト
次回：
- query builder の整理
- UI state の重複削除
- test helper の共通化
この分け方ができると、PRが読みやすくなります。
実務テンプレート：既存リポジトリ調査
そのまま使えるテンプレートです。
## Task
既存リポジトリで、`<機能名>` の実装箇所と変更リスクを調査する。
## Do Not
- ファイルを変更しない。
- package を追加しない。
- migration を作らない。
- 外部サービスへ書き込まない。
## Read
- 関連する UI / API / service / repository
- 既存テスト
- docs
- issue / PR
## Output
1. Entry points
2. Current flow
3. Existing patterns
4. Tests
5. Risks
6. Unknowns
7. Suggested next step
## Stop If
- 認証、権限、課金、個人情報に触る必要がある。
- DB schema変更が必要に見える。
- 変更対象が広すぎる。
- 仕様が矛盾している。
実務テンプレート：障害調査
障害調査なら、こうです。
## Incident Investigation
Goal:
- `<症状>` の原因候補を整理する。
Do Not:
- まだ修正しない。
- production data を変更しない。
- secret / PII を表示しない。
Inputs:
- error message
- request id
- time range
- recent deploy
- related issue / alert
Output:
1. Timeline
2. Facts
3. Hypotheses
4. Reproduction steps
5. Smallest failing test candidate
6. Missing information
7. Risk before fix
Stop If:
- write access が必要。
- production DB が必要。
- 原因候補が1つに絞れない。
- 修正範囲が認証、課金、権限に広がる。
実務テンプレート：修正前レビュー
修正前に挟むテンプレートです。
## Pre-Fix Review
ここまでの調査結果を review してください。
まだ実装しないでください。
Check:
- 事実と仮説は分かれているか。
- 再現条件は今回の問題を表しているか。
- failing test は最小か。
- 変更範囲は十分に小さいか。
- 既存パターンに沿っているか。
- 触るべきでない領域に入っていないか。
- 先に確認すべきログ、テスト、仕様はないか。
Output:
- 実装に進んでよいか
- 進むなら最小変更範囲
- 進まないなら追加調査
runbookに戻す
障害調査で得たものは、次回に戻します。
たとえば、今回分かったことがこうだったとします。
- combined filter は壊れやすい
- pagination default が抜けやすい
- mobile path だけ URL query の同期が違う
- logs では request id を追う必要がある
これを、その場のPRコメントだけに残すと消えます。
runbook に戻します。
## Product Search Incident Runbook
When product search fails:
1. Check whether keyword-only request works.
2. Check whether category-only request works.
3. Check combined keyword + category.
4. Check pagination default.
5. Compare desktop and mobile URL query.
6. Follow request id across API and repository logs.
7. Add or update combination test before implementation.
次に同じ種類の障害が起きたとき、agent にこう頼めます。
Product Search Incident Runbook に沿って調査してください。
まだ修正しないでください。
これが Compound です。
AGENTS.mdに戻す
毎回効かせたい調査ルールは、AGENTS.md に戻します。
## Investigation Rules
- Bug fix の前に、再現条件と failing test 候補を出す。
- 事実と仮説を分ける。
- 既存パターンを読んでから実装する。
- 変更範囲が認証、権限、課金、DB schema に広がる場合は止まる。
- 修正前に Pre-Fix Review を挟む。
ここまで書いておくと、次回の agent は最初から違う動きになります。
「直して」ではなく、「調査して、再現して、止まる」が基本になります。
まとめ
既存リポジトリで AIエージェントを使うなら、いきなり実装させない方が安定します。
まず read-only で調査する。
入口ファイルを探す。
既存パターンを読む。
ログを時系列にする。
事実と仮説を分ける。
再現条件を作る。
failing test を review する。
修正前レビューを挟む。
最小修正に絞る。
学びを runbook と AGENTS.md に戻す。
これだけで、agent はかなり実務の流れに乗ります。
コードを書く力より前に、読む力と止まる力を使う。
既存リポジトリでは、ここが効きます。
次回は Codex App を扱います。
CLIだけではなく、画面、ファイル、thread、review をどう作業台として使うか。
特に、非エンジニアや周辺職種の人が Codex App をどう使えるかまで踏み込みます。