最初に書いた AGENTS.md を3週間後に開いてみたら、ほとんど別物に書き直されていました。同じプロジェクトを Antigravity と一緒に進めていくなかで、想定していなかった失敗パターンや、逆に「ここまで書かなくても伝わる」という手応えが少しずつ見えてきたからです。
AGENTS.md は、書いた瞬間が完成形ではありません。週1で振り返り、エージェントの失敗ログから1〜2行ずつ書き加えていく運用を始めてから、Antigravity の挙動が目に見えて落ち着きました。ここではその「運用ループ」を具体的な手順とテンプレートとして共有します。
なぜ AGENTS.md は「最初の1回」では仕上がらないのか
書き始めた頃の AGENTS.md は、私の頭の中にあるルールを言葉にしただけのものでした。Antigravity と何回かやりとりしてみると、書いてあるはずの指示が空回りしている瞬間が必ずあります。
理由は3つあります。1つ目は、自分のメンタルモデルと AI の解釈にはどうしてもズレが残ること。「テストを書く」と書いておけば伝わるつもりでも、Antigravity からすると「どのテストフレームワークで」「どのレベルの粒度で」が抜けていることがあります。
2つ目は、プロジェクト自体が進化していくこと。先週まで使っていなかった zod のバリデーションを今週から導入したら、AGENTS.md にも一文追加しないと、エージェントは古いやり方で書き続けます。
3つ目が、いちばん重要です。エージェントの失敗パターンは事前に予測できません。実際に動かしてみて初めて「ここがズレるのか」と気づきます。AGENTS.md は仕様書ではなく、ライブラリのチェンジログのように更新していく文書だと考えると、運用が楽になります。
週1の失敗ログレビューで集める3つの情報
私が振り返るときに集めているのは、次の3カテゴリの「気になった瞬間」です。完璧に記録する必要はなく、その週に違和感があった会話を Antigravity の履歴から拾うだけで十分です。
- やってほしくないことをやられた記録: 関係ないファイルにまで手が入った、不要な依存関係を追加された、コミットを勝手に分割された、など。Antigravity の差分表示を見返すと痕跡が残っています
- やってほしいのにやられない記録: テストを書いてくれない、PR の説明文が雑、
@types/*のインストールを忘れる、など。「もう一度頼まなくてはいけなかった」場面を思い出します - 曖昧で迷っているように見える記録: Antigravity が複数の選択肢を提示してきた瞬間や、最初の実装をすぐにやり直した瞬間。これは AGENTS.md に判断基準が足りていないサインです
ノートアプリでも、リポジトリ内の _retro/ ディレクトリでも、書き残す場所はどこでも構いません。重要なのは「一週間に一度、必ず10分だけ目を通す」というリズムです。
失敗ログを AGENTS.md に落とす実例
ログをそのまま AGENTS.md に貼り付けても効きません。「どんな指示があれば次は失敗しなかったか」に翻訳する一手間が必要です。
例えば、先週私が遭遇した失敗を Before/After で書くと、こうなります。
# Before（最初に書いていた指示）
- TypeScript で書く
- テストも書く
# After（失敗ログを反映した指示）
- 新規ファイルは TypeScript の strict モードで書く（`tsconfig.json` 参照）
- テストは Vitest で `*.test.ts` として同階層に置く
- 1コミット1機能。テストとプロダクトコードは同じコミットに含める
- `any` 型は禁止。型推論で解決できないときは Discriminated Union を検討する差分は4行ですが、エージェントの行動は明確に変わります。「テストを書く」だけでは、ジェスチャーとして書いているのと変わりません。「どこに置くか・どのフレームワークで・コミット粒度はどうするか」まで含めて初めて、エージェントが迷わずに動けるルールになります。
私はこの書き換え作業を、Antigravity 自身に手伝ってもらっています。「先週のこの失敗ログから、AGENTS.md に1〜2行追記する案を3パターン出して」と頼むと、自分では思いつかない言い回しが出てくることがあります。最終的に採用するかは自分で決めますが、たたき台としてかなり優秀です。
関連記事として、AGENTS.md の基本構成はAGENTS.md ガイド — Antigravity でエージェントに伝わるドキュメントの作り方で、効かないときの原因切り分けはAGENTS.md が効かないときのトラブルシューティングでまとめています。あわせて読むと、書く・直す・治すの3面が揃います。
AGENTS.md の肥大化を防ぐ3つのルール
毎週ルールを足し続けると、半年もすれば AGENTS.md は読まれない長文になります。エージェント自身もコンテキストウィンドウを浪費して、肝心の指示を見落とします。私は次の3つのルールで肥大化を抑えています。
- 「2回以上発生した失敗」だけ取り込む: 一度きりの偶発的なミスはルール化しません。再発したときに初めて成文化します
- 同じ意図のルールはまとめる: 「テストを書く」「Vitest を使う」「
*.test.tsの場所」を3行に分けず、1ブロックにまとめます - 古くなった制約は明示的に消す: 移行期の暫定ルールは、移行が終わったら削除します。「もう守らなくていいのか守るべきか」が曖昧なルールはエージェントを混乱させてしまいます
特に3つ目を忘れがちです。古いルールが残っていると、エージェントは新しいコードベースに対して古いやり方を提案してきます。git log AGENTS.md を月に一度眺めて、半年以上触っていないセクションは見直すようにしています。
週1レビューの定型ワークフロー（30分）
毎週のリズムを決めておくと、運用が長続きします。私の場合、金曜の午後に30分だけ確保して、次の手順を回しています。
- 5分: 直近1週間の Antigravity 会話履歴を眺めて、引っかかりのあった瞬間を3つメモする
- 5分: 同じ期間のコミット履歴 (
git log --since="1 week ago" --oneline) を見て、AI が書いたコードに不自然な箇所がなかったか確認する - 10分: メモを AGENTS.md の差分案に翻訳する（必要なら Antigravity 自身に補助させる）
- 5分: 差分を
git diff AGENTS.mdで確認しながら、肥大化していないかチェックする - 5分: 古くなった制約を1つ削除候補として印を付ける（次週に判断）
このうち1〜2が「観察」、3が「変換」、4〜5が「整理」です。観察と変換だけだとファイルがどんどん膨らむので、整理を必ず混ぜることが続けるコツです。
私が運用している AGENTS.md の階層構造
プロジェクトの規模が大きくなってくると、ルートの AGENTS.md だけでは足りなくなります。私は次の3階層に分けています。
- ルート
AGENTS.md: プロジェクト全体の方針、全ディレクトリで守ってほしいこと、コミット規約 apps/{app-name}/AGENTS.md: アプリ固有のフレームワーク、ディレクトリ規約、認証方針packages/{package-name}/AGENTS.md: パッケージごとの API スタイル、テスト方針、外部依存
Antigravity は作業対象のファイルから近い AGENTS.md を優先的に読むので、深い階層に書いた制約が効きやすくなります。ルートに全部書いてしまうと、別のアプリにも適用されてしまって混乱の元になります。
階層構造の運用ノウハウはAntigravity のカスタムルールとプロジェクト設定マスターでも触れているので、合わせて確認してみてください。
書籍で系統立てて
今週、1行だけ追記してみる
完璧な AGENTS.md を一気に書き上げる必要はありません。今週の Antigravity との会話のなかで、もう一度頼みなおさなくてはいけなかった瞬間がきっと1つはあります。その瞬間を思い出して、AGENTS.md に1行だけ追記してみてください。
来週、同じ失敗が再発するか、それとも回避できているか。その手応えが、AGENTS.md が「育つ」ファイルだと感じられる瞬間になります。