はじめに
AGENTS.md を最初に書いたとき、そこに何を書けばいいのかはあまり分かっていませんでした。
実際に開発を進めると、AIエージェントが迷う場所や、自分が何度も同じ指摘をしている場所が見えてきます。
運用ルールは書き始める前より後から分かることの方がずっと多いです。
以前、AIエージェントの運用ノウハウを複数のプロジェクトで共有するために project-scaffold というSkillを作りました。
その設計意図は以下の記事にまとめています。
前の記事で扱ったのは、あるプロジェクトで育った運用を組織の標準へ戻し、別のプロジェクトへ展開する流れでした。
この記事ではその一段内側の話を書きます。
各プロジェクトの AGENTS.md や運用ルールを、日々の開発からどう更新していくかです。
AGENTS.mdは最初から完成を目指さない
プロジェクトの開始時に、必要なルールをすべて決めるのは難しいです。
AIエージェントがどこで迷うのか、何を何度も指摘することになるのか、どこで更新漏れが起きるのかは、実際に開発してみないと分かりません。
そのため自分は、最初から細かく作り込まないようにしています。
書くのは、そのプロジェクトで確実に必要だと分かっている範囲までにとどめ、あとは開発中に得られた知見を必要に応じて足していく形にしています。
作業が終わったら、ルール候補を洗い出す
一通りの作業が終わったタイミングや、AIエージェントとのセッションを終えるタイミングで、その作業を振り返ります。
見ているのはだいたい次のような観点です。
| 起きたこと | 確認すること |
|---|---|
| AIへ同じ指摘を繰り返した | 恒常的なルールにできないか |
| 更新漏れがあった | 関連ファイルの更新ルールが必要か |
| 毎回同じ判断をした | 判断基準を残せないか |
| 同じ調査や手順を繰り返した | SkillやScriptにできないか |
| 運用上の方針を決めた |
AGENTS.md などへ反映すべきか |
ここで大事なのは、見つけたものを全部 AGENTS.md に追加しないことです。
まずはルール候補として扱い、今回だけの事情なのか、今後も繰り返し必要になるのかを見てから反映します。
一度追加したルールは、その後のすべてのセッションでエージェントが読むことになります。
追加するコストは小さいのに効き続ける範囲は広い。だからこそ、候補と採用の間に一段挟んでいます。
discussionsとdecisionsを振り返る
自分のプロジェクトでは project-scaffold の構成を使って、docs/ 配下に議論と意思決定を残しています。
docs/
├── 01_product/
├── 02_requirements/
├── 03_spec/
├── 04_decisions/
├── 05_discussions/
└── 06_execution/
運用ルールを更新するときに特に見るのが、04_decisions/ と 05_discussions/ です。
05_discussions/ には未解決の論点やAIとの検討内容が残り、それが解決したら、必要に応じて 04_decisions/ に意思決定として残します。
この流れは、そのまま運用ルールの材料になります。
もちろん、AGENTS.md に書くべきことが必ず 05_discussions/ や 04_decisions/ に残っているわけではありません。
それでも、どこでどんな判断をして、それが今後の作業にも影響するのかを探す材料としてはかなり使えます。
記憶を頼りに振り返るより、書いたものを起点にした方が、拾えるものが多いです。
04_decisions/ とAGENTS.mdは役割が違う
04_decisions/ と AGENTS.md には、似た内容が入ることがあります。
ただし役割は違います。
| 書くこと | |
|---|---|
04_decisions/ |
なぜその運用にしたのか |
AGENTS.md |
次回からどう行動するのか |
例えば、
画面仕様と実装のズレを防ぐため、画面一覧を正本として管理する
という意思決定をしたとします。
このとき AGENTS.md に書くのは、
画面追加・変更時は画面一覧も更新する
という行動だけです。
背景まで全部 AGENTS.md に書くのではなく、詳しい理由は 04_decisions/ に任せます。
AGENTS.md は毎回読まれるファイルなので、長くなるほど一つひとつのルールが埋もれます。
理由を知りたくなったときに辿れる場所さえあれば、行動だけを書いておけば足ります。
ルール候補の置き場所を決める
ルール候補が見つかっても、すべてをルートの AGENTS.md に入れるわけではありません。
内容によって置き場所を変えています。
| 内容 | 置き場所 |
|---|---|
| プロジェクト全体で必要 | AGENTS.md |
docs/ 配下だけで必要 |
docs/AGENTS.md |
| 特定ディレクトリだけで必要 | その配下の AGENTS.md
|
| 意思決定の背景 | 04_decisions/ |
| 未解決の論点 | 05_discussions/ |
| 要件・仕様 |
02_requirements/ / 03_spec/
|
| 繰り返し行う複雑な手順 | Skill / Script |
| 機械的に検証できるもの | lint / test / CI |
ルートの AGENTS.md に置くのは、作業するときに必要なルールや判断基準に絞ります。
最後の2行が特に効きます。手順が長くなってきたものはSkillへ、機械的に判定できるものはlintやCIへ寄せた方が、文章で伝えるより確実です。
候補出しはAIに任せ、判断は自分でする
この振り返りは、AIエージェント自身にも任せやすい作業です。
セッションの終了時に、これくらいを頼めば十分でした。
今回の作業、追加・更新されたdiscussions / decisions、実装中の指摘や手戻りを振り返り、今後の作業でも使うべき運用ルール候補を洗い出してください。
既存のAGENTS.mdなどとの重複も確認し、追加・変更・削除の候補を整理してください。
ポイントは、そのまま自動で追記させるのではなく、まず候補として出させることです。
その場のセッションの中では、どの指摘も「今後も必要なルール」に見えます。
一度離れて、他の作業でも当てはまるかを考えてから入れるようにしています。
ただ、個人開発ではそこまで厳密に運用していません。
出てきた候補はざっくり目を通して概要を把握するだけで、一つひとつの中身までは精査していません。
そのまま追加しておいて、後からリファクタリングする形にしています。
それでも、エージェントに直接追記させるのではなく、いったん候補として出させる形は変えていません。
何が追加されたのかを把握していないと、後から整理することもできないからです。
定期的に棚卸しする
追加するだけでは AGENTS.md は徐々に肥大化します。
そのため、定期的に棚卸しします。見ているのは次のような点です。
- 同じルールが重複していないか
- すでに実装と合わなくなっていないか
- 細かすぎるルールをまとめられないか
- 別のファイルへ移した方がよくないか
- lintやCIで自動化できないか
- そもそも削除できないか
例えば、個別のケースごとに書き足していったルールが、
Aの場合はXする
Bの場合はXする
Cの場合はXする
のように増えてきたら、
この種類の変更ではXを確認する
という一つの原則にまとめられることがあります。
ケースを列挙するより原則として書いた方が、想定していなかったケースにも効きます。
実装と合わなくなったルールは特に厄介です。
エージェントはそれを現在の仕様として読むので、古いルールが残っていると正しく従った結果として間違った実装が出てきます。
ルールを追加することだけでなく、減らすことも大事です。
プロジェクト内で育ったルールを、組織へ戻す
ここまでの流れをまとめると、プロジェクト内では次のサイクルを回していることになります。
この中で育ったルールには、他のプロジェクトでも使えそうなものが出てきます。
そこから先が、前の記事で扱った project-scaffold-audit の役割です。
プロジェクト内では、このプロジェクトを次回もっと上手く開発するにはどうするかを考えます。
Org Standardでは、その改善を他のプロジェクトにも広げるべきかを考えます。
判断の基準が違うので、2つは分けて運用しています。
まとめ
AGENTS.md は、CTOやテックリードが一度作って終わるものではありません。
開発で見つかった問題や、そこで下した判断を材料にして、少しずつ足したり減らしたりしながら育てていくものだと考えています。
特に 05_discussions/ や 04_decisions/ を残しておくと、どんな判断をして、それが今後の開発にどう影響するのかを後から振り返りやすくなります。
その中から本当に繰り返し必要なものだけを運用ルールへ反映し、さらに他のプロジェクトでも使えるものはOrg Standardへ昇格させる。
こうして、AIとの会話で得た知見をその場限りにせず、次の開発・他のプロジェクトへ残していくというのが、今の運用です。