AGENTS.mdとは、AIエージェントが作業前に読むプロジェクトのルールファイルです。
短いのに効く理由は、やることを増やすのではなく、迷ったときの選び方を固定するからです。この記事を読むと、Marcos Hernanzさんの原文、自然な日本語訳、Grill Meに通じる短い言葉の効き方、attripthemaに追加した7項目がわかります。
約60Bトークンという数字は投稿者自身の説明です。独立したログやベンチマークまでは確認できていません。
Marcos Hernanzさんの原文：7つのルール
原文は、Marcos Hernanzさん本人のX投稿で先に確認できます。投稿画像にある英語を、読みやすい形で載せます。
# AGENTS.md
- Do not preserve backward compatibility. Remove obsolete paths instead of adding compatibility layers, fallbacks, or migrations.
- Choose the simplest implementation that fully meets the current requirements. Avoid speculative abstractions, configuration, and indirection.
- Grow the system in layers. Start from the smallest version that works end to end, and add each new capability on top of a product that already works. Never trade a working product for unfinished complexity.
- Keep components modular and concerns clearly separated.
- Prefer established, well-maintained libraries when they reduce overall complexity or improve reliability. Do not reimplement common functionality without a clear reason.
- Lean on the dependencies already in the project before writing your own implementation or adding packages. Do not assume a library lacks a capability without checking its documentation and types.
- Make architectural decisions for the long term. Do not accept a stopgap that only works for now and is meant to be replaced later.原文の日本語訳
- 後方互換を維持しない。互換層、fallback、migrationを追加するのではなく、古い経路を削除する。
- 現在の要件を完全に満たす、最も単純な実装を選ぶ。推測による抽象化・設定・間接化を避ける。
- システムを層で育てる。まず動く最小のend-to-endから始め、すでに動いている製品の上に新しい機能を足す。未完成の複雑さのために、動く製品を犠牲にしない。
- コンポーネントをモジュール化し、関心事を明確に分ける。
- 複雑さを減らしたり信頼性を上げたりするなら、実績があり保守されているライブラリを優先する。明確な理由なく一般機能を再実装しない。
- 自前実装やパッケージ追加の前に、プロジェクトにすでにある依存関係を使う。ドキュメントと型を確認せず、ライブラリに能力がないと決めつけない。
- 長期のためにアーキテクチャを決める。今だけ動き、後で置き換える予定のstopgapを受け入れない。
Marcos HernanzさんはVercel・Next.jsの開発者
本人のGitHubプロフィールによると、Marcos HernanzさんはサンフランシスコでVercelのNext.jsチームに参加するソフトウェアエンジニアです。コーディングエージェント、評価基盤、機械学習システム、性能が重要な開発者向けツールに取り組んでいると説明しています。
プロフィールには、Next.jsのAIメンテナー、パフォーマンス改善、39.85Bの学習トークンを扱ったllm-lab、RustとWASMを使ったローカル検索なども掲載されています。
ここで重要なのは、肩書きだけではありません。エージェントを実際の開発環境に置き、長い時間使い、速度・依存関係・保守性まで考える立場の人が、経験を7行に圧縮している点です。
Grill Meと同じく、短い言葉が行動を変える
私の運用でいうGrill Meは、短い言葉でAIの役割を変える合図です。答えを急がず、前提を質問し、計画の弱いところを詰めるモードに切り替えます。
Marcos Hernanzさんの7項目も同じです。長い説明を毎回繰り返さず、「迷ったらどちらを選ぶか」を短い言葉で呼び出します。
simplestは、先回りした設定や抽象化を止めるalready worksは、未完成の複雑さで動くものを壊さないdocumentation and typesは、調べずに自作する癖を止めるlong termは、あとで捨てる前提の設計を止める
短い言葉が効くのは、単なる合言葉だからではありません。行動、禁止事項、判断の向きが一緒に入っているからです。
7つのルールがAIの迷いを減らす
一つひとつは、経験のある開発者なら知っていることです。それでも価値があります。AIエージェントは、知らないから失敗するだけではありません。選択肢が多いと、もっともらしい複雑さを足して失敗します。
この7項目は、エージェントの選択肢を減らします。
「念のため互換層を足す」
「将来必要になるかもしれない設定を入れる」
「あとで置き換える仮実装を先に置く」
こうした判断を、実装前に止めます。つまり、これはコーディング規約というより、曖昧さに対する判断ポリシーです。
研究では、長さより内容が効く
Codexの公式ドキュメントによると、Codexは作業前にAGENTS.mdを読みます。グローバル設定、プロジェクト設定、下位ディレクトリの設定を組み合わせ、より近い指示を優先できます。
ただし、ファイルがあるだけで品質が上がるわけではありません。
AGENTS.mdに関する小規模な研究では、10リポジトリ・124件のPRを対象に、AGENTS.mdがある場合に実行時間の中央値が28.64%、出力トークン量が16.58%少なかったと報告されています。これは有望な関連ですが、対象が小さく、因果関係まで確定した結果ではありません。
一方、別の評価研究では、コンテキストファイルを置いただけでは正確さが大きく改善しない場合があり、コストが20%以上増える傾向も報告されています。開発者が書いたファイルは、モデルが自動生成したファイルより平均7%良い結果でした。
ここからの解釈は明快です。
AGENTS.mdの価値は、長さではありません。プロジェクト固有の判断を、人間が先に決めていることです。
私がattripthemaに追加したのは、この7項目
この流れを受けて、attripthema/AGENTS.mdに## 実装原則を追加しました。追加したのは、次の7項目です。
## 実装原則
- 現行要件や公開契約に不要な後方互換は増やさない。古い経路は互換層・fallback・migrationで温存せず、必要性を確認して整理する。
- 現行要件を満たす最も単純な実装を選ぶ。推測による抽象化・設定・間接層を増やさない。
- 動く最小のend-to-endから段階的に育てる。未完成の複雑さのために、動いているものを壊さない。
- コンポーネントを分離し、責務の境界を明確にする。
- 複雑さや不具合を減らせる、保守された既存ライブラリを優先する。明確な理由なく一般機能を自作しない。
- 新規実装やパッケージ追加の前に、既存依存のドキュメントと型を確認する。
- 後で捨てる前提のstopgapを採用せず、長期運用できる設計判断をする。元の考え方は保ちつつ、現行要件と公開契約という言葉を加えました。attripthemaでは、既存のURL、公開記事、アイキャッチ、本文画像がすでに読者との契約になっているからです。
そのため「後方互換を増やさない」は、「既存の公開資産を壊してよい」という意味ではありません。不要な古い実装は整理しますが、公開中のURLや画像を変えるときは、別の確認が必要です。
今回追加したのは、ここまでです。コード、CSS、既存記事の本文はこの原則追加のためには変更していません。変更履歴はlog.mdに残しました。
Solの改善点まで考えると、さらに実用的になる
この7項目には、実装をよくする力があります。ただし、そのまま強く適用すると、別の問題が起きます。
「単純にする」と「将来の公開契約を守る」は、いつも同じ方向ではありません。
「stopgapを避ける」と「まず小さく検証する」も、同じではありません。
「責務を分ける」と「先回りして抽象化する」も、境界を間違えると複雑になります。
そこで、設計判断をするSolには、実装ではなく次の役割を持たせるのがよいと考えました。
- 曖昧な要件、不可逆な変更、横断的な設計をレビューする
- 反対案とリスクを出す
VERDICT: PASS | CHANGE | BLOCKEDで判断を残す- 根拠、確認したこと、非対象を明記する
- 最終的な公開判断は人間が行う
調査はExplorer、要件が固まった実装はWorker、難しい設計判断はSolに分けます。役割を増やすことが目的ではありません。判断と作業を混ぜないことが目的です。
この役割分担は、プロジェクト内のdocs/repair-loop.mdに詳しく書いてあります。次にAGENTS.mdを改善するなら、本文にすべてを詰め込まず、例外と役割の境界だけを短く追加します。
自分のAGENTS.mdに入れる前に決める3つ
この7項目をそのままコピーする必要はありません。先に、次の3つを決めると機能します。
- このプロジェクトで絶対に壊してはいけない公開契約は何か
- どこまでなら単純化・整理してよいか
- 完了と判断する証拠は何か
たとえばWordPressテーマなら、公開URL、既存記事の画像、アイキャッチ、モバイル表示、公開後のURL確認が契約になります。
AGENTS.mdには判断原則だけを書き、詳しい手順や履歴はdocs/README.mdからたどれるようにすると、短さも保てます。
60Bではなく、短い判断基準をまねる
Marcos Hernanzさんの投稿から学ぶべきなのは、60Bという数字ではありません。長い経験を、エージェントが迷う場面だけに絞っていることです。
私がattripthemaに追加したのも、7つの実装原則だけです。次の改善候補は、公開契約の例外、Solのレビュー境界、完了証拠の書式です。
短いAGENTS.mdは、AIを命令で縛るファイルではありません。人間が先に決めた「ここではこう判断する」を、毎回の作業に渡すファイルです。
参照元
- Marcos HernanzさんのX投稿：約60Bトークン後のAGENTS.mdという本人の投稿
- Marcos HernanzさんのGitHubプロフィール：所属、担当領域、公開プロジェクト
- Codex公式ドキュメント：AGENTS.md：読み込みと階層ルール
- agents.mdのオープン形式：AGENTS.mdの考え方と形式
- AGENTS.mdと開発効率に関する研究：10リポジトリ・124PRの分析
- コンテキストファイルの効果に関する評価研究：コスト、正確さ、開発者作成ファイルの比較
