この記事は、ある調整上の問題と、チームがそれを解決するために用いたファイルについて述べている。同社の新しい Global App を開発しているメルカリの Web チームは、多様なバックグラウンドを持つメンバーで構成されており、使うツールや環境も大きく異なる。記事は目標を、エンジニアにまったく異なる環境を強いることなく AI ツールを使えるようにすることだと述べている。ツールがばらばらであることへの答えは全員に同じツールを使わせることではなかった — AI をめぐる状況は依然として急速に進化し続けているとされる — というのが記事の立場であり、むしろ異なる仕事のスタイルを共通の目標に向けてそろえる方法を見つけることだった。
記事が挙げる問題は、共有されたコンテキストを持たないエージェントである。Cursor、Claude Code、GitHub Copilot、そして後には Codex CLI がすべて使われていた。前の 2 つのユーザーはそれぞれのツールが求める形式でルールを書き、ルールの保守担当者の間で作業が重複し、それらを同期させておくプロセスもなかったため、ルールセットは徐々に乖離していった。記事によれば、あまり普及していないツールを使うエンジニアは、プロンプトのセッションを始めるたびに同じ修正や注意を与えなければならないことが多かった。記事はこの状況を、多様なツールへの習熟は進んだものの、どの 1 つのツールでも生産性はうまくスケールしなかった、とまとめている。
これを解決したものとして示されるのが AGENTS.md である。チームは、ツールに依存しないこの設定の標準を唯一の信頼できる情報源として採用し、CLAUDE.md やその他のルールファイルはそれへのシンボリックリンクとなった。記事の締めくくりの枠組みは、このファイルが共有のルールブック以上のもの — 人、ツール、アイデアをつなぐ橋 — となり、すべてのエンジニアが自分の環境を保ちながら同じ方向へ進めるようになった、というものである。
要点
- チームのルールが乖離していたのは、ツールごとに独自の形式が求められたためである。Cursor と Claude Code のルールは別々に保守され、作業は保守担当者の間で重複し、それらを同期させるプロセスもなかった。
- 著者自身の出発点は、少しずつ育ててきた
CLAUDE.mdだった。エージェントとのセッションが終わるたびに、将来のセッションのために覚えておく価値があると Claude が判断した内容を要約させ、それをファイルに追記していた。記事によれば、これは著者にとっては機能したが、チームにはまだあまり価値をもたらしていなかった。 - チームは、記事が最初に単数形の
AGENT.mdとして見つけた標準 — Sourcegraph が AmpCode プロジェクトを通じて提案した RFC として説明されている — を採用し、既存の Cursor と Claude のルールをそうしたファイル 1 つに統合した。記事は、当時チームの他のメンバーはまだその RFC が長続きするのかどうかを気にしていたと記録している。 - このファイルが複数形になったのは、OpenAI が agents.md のドメインを確保した後のことである。記事は、それが標準を複数形の表記にするのを妨げていた唯一の要因だったとしており、またこれは OpenAI 自身の Codex がすでに使っていたファイル名でもあった。記事は、OpenAI の後押しによってこの標準がチームの使うツールの間で — とりわけ Cursor で — はるかに広く受け入れられるようになったとしており、チームはその後、複数形の形式を唯一の信頼できる情報源として採用した。
- このファイルはルールそのものではなく入口である。示されているのは短い
AGENTS.mdで、その各セクションがdocs/配下の個別のドキュメント — ビルドとテストのコマンド、コードスタイルと規約、プロジェクトのアーキテクチャ、認証のパターン、テスト戦略 — を指している。 - リポジトリがモジュール型のアプローチをとっていることから、アーキテクチャのドキュメントはとりわけ重要なものとして取り上げられている。記事によれば、そのコンテキストを省くと、毎回同じ初期コンテキストを注意深くプロンプトで与えない限り、ほとんどのツールの出力は開発者が完全に作り直さなければならなくなる。示されている抜粋には、モジュールタイプ
@app/*、@feature/*、@domain/*、@core/*を持つ pnpm workspaces、eslint-plugin-boundariesによって強制される core → domain → feature → app という依存関係の流れ、そして各アーキテクチャ層が何を持つかが記録されている。 - デザインシステムのルールはエージェントに明示的に教え込まれている。記事が挙げる理由は、プロジェクトはデザインシステムに従わなければならず、バイブコーディングで書かれた CSS に頼ることはできないというものである。抜粋では ALWAYS／NEVER という強い指示が使われている。コンポーネントは常にソースファイルからではなく社内のデザインシステムパッケージからインポートすること、デザインシステムのコンポーネントやネイティブの HTML 要素にインラインスタイルを決して追加しないこと、そして独自のスタイリングにはデザインシステムのカラートークンと Panda CSS のユーティリティを使うこと、である。
- チームのドキュメント保守のワークフローは、上位レベルの設計に大きな影響を与えるプルリクエストについて、そのプルリクエストの変更内容とルールフォルダをあわせてエージェントにかけ、モデル自身にルールの修正を提案させたり、コードの不整合を指摘させたりするというものである。これを自動化した理由として記事は、タスクに集中しているエンジニアにとって、別のフォルダにある手元以外の Markdown ファイルを編集するのは面倒なことが多いからだと述べている。記事はその結果を、自動的に自らを強制し自らを更新するドキュメントと呼んでいる。
- 執筆時点でチームが取り組んでいたのは、すべてのプルリクエストに対して実行され、人間が書いたものか機械が書いたものかを問わず、これらのルールから外れたコードを自動的に指摘するエージェントである。その狙いとして、質の悪い AI の出力を検出すること、新しいメンバーをより速く育成すること、そして意図的な構造変更を行うシニアエンジニアが関連するルールへのパッチを自動生成できるようにすることが挙げられている。
- 記事は測定結果を報告していない。エンジニアのオンボーディングの迅速化やプロンプトの定型文の削減についての主張は、チーム自身の経験に基づく説明である。
背景
記事はこの取り組みを、メルカリによる AI-Native な開発原則の採用の中に位置づけており、ツールに依存しないアプローチをとった理由を率直に述べている。全員が自分の選んだツールを採用する権限を与えられ、新しい技術を試すためのリソースも与えられていた。それによってチームは幅広いツールについて素早く学ぶことができたが、同じチーム内であっても、ツールの有効性や出力の形は大きく異なっていた。
標準の歴史についての記事の説明は、当事者ではなく採用者の立場から書かれている — チームが何を見つけたか、名前がいつ変わったか、それがチームの重視するツールでの普及にどう影響したか、である。記事はモノレポのアーキテクチャについての同僚の以前の記事や、名称に関する AmpCode の発表に言及しているが、いずれについても自らの物語の中で果たす役割以上のことは説明していない。
著者が最後に述べる狙いは、これらの学びをメルカリ全体で共有し、AI-Native な開発を模索する他のチームに刺激を与えることであり、目標は人間とエージェントが肩を並べて働けるようにすることだとされている。