AGENTS.md とスキルと MCP を、2つの質問で振り分ける

3つの仕組みを見てきました。どれも「同じことを毎回言わずに済ませる」ためのものですが、向く中身が違います。

この回で決めるのは、手元にある情報をどこへ置くかです。判断は2つの質問で足ります。

2つの質問

質問1: それは、どの作業にも関係するか。

するなら AGENTS.md です。コードの書き方、検査の通し方、触ってはいけない場所。作業の種類を選ばずに効くものは、常に読まれる場所に置きます。

しないなら、質問2へ進みます。

質問2: それは、書いておける内容か。

書いておけるならスキルです。手順、テンプレート、判断の基準。内容が固定されていて、ファイルに書き出せるものが当てはまります。

書いておけないなら MCP です。いまの状態、現在の値、外部サービスの中身。見に行かないと分からないものが当てはまります。

質問の順番には理由があります。1つ目で切り分かるものが一番多く、しかも間違えたときの影響が大きいからです。

事例1: ブログの記事を1本書く

いまあなたが読んでいるこの記事を作る作業で、3つがどう働いているかを書きます。

AGENTS.md には、この仕事の性質から来る規約が入っています。事実の出どころを実際のリポジトリと画面と検証結果に限ること、実測していない性能値を書かないこと、不明点を TODO: 要確認 として残すこと、そして検査の通し方。どれも、記事の主題が何であっても効きます。

スキルには3つ置いています。日本語の技術文書の文章規範、読み手の認知の切り替えを設計する書き方、アイキャッチ画像の生成です。3つとも、記事を書くとき以外には呼ばれません。文章規範は分量が多く、常に読ませるには重すぎます。画像生成にいたっては、実行するスクリプトが同梱されています。

MCP は、できあがったものをプルリクエストとして出すところで使っています。リポジトリの状態と、そこに何を作るかは、書いておけません。

割り振りの結果、AGENTS.md は100行ほどに収まっています。文章規範をここに書いていたら、その3倍になっていました。

事例2: 16サイトで計測が届いているか確かめる

性格の違う作業を挙げます。運営している16のサイトで、アクセス解析のタグが正しく動いているかを確認する仕事です。

この作業では、MCP が主役になります。確かめたいのは「いま届いているか」だからです。ソースコードにタグが書かれていることは、リポジトリを読めば分かります。届いていることは、読んでも分かりません。実際にブラウザで開いて、通信が出ているかを見るしかない。

このとき、書いておける知識もあります。「どのサイトを確認するか」「どういう状態なら合格か」といった手順は固定です。これはスキルか、作業のたびに渡す仕様書にまとめられます。

実際にやってみると、3サイトで届いておらず、1サイトで数が合いませんでした。そして、届かない理由の1つは、渡した仕様書の側の誤りでした。この記録は「GPT-6 Astra の Codex に、16サイトの疎通確認を任せた記録」にまとめています。

書いておける知識は古くなるというのが、この事例から得た教訓です。仕様書に「設定はどのリポジトリにもない」と書いてあり、それが事実と違っていました。取りに行けるものは、書き写さずに取りに行かせるほうが安全です。

事例3: Android アプリのビルド環境

3つ目は、開発環境そのものの扱いです。

Android アプリのリポジトリでは、Windows に常設するものを Git と Android Studio と Codex の3つに限り、それ以外の道具は1か所の作業フォルダへ集めています。この方針は AGENTS.md に書いています。作業の種類を選ばず、どの依頼でも効いてほしいからです。

一方、その環境を実際に組み立てる手順は、スクリプトとして書かれています。バージョンを検証して展開し、永続的な環境変数には触らない。手順が決まっていて、間違えると面倒で、環境を作り直すときにしかやらない。第10回で挙げたスキルの3条件がそろっています。

この分け方の効き目は、環境が壊れたときに出ます。方針が規約に書いてあるので、直すときも同じ形に戻ります。手順がスクリプトになっているので、戻す作業は実行するだけで終わります。詳しくは「Codex の導入から、Android 測定アプリが実乗車で動くまで」に書きました。

置き場所を間違えたときに起きること

3つの失敗を挙げます。どれも、壊れるのではなく、静かに効かなくなる形で現れます。

規約をスキルに入れた場合。そのスキルが呼ばれなかった回には、規約が効きません。呼ばれなかったことに気づく手がかりもないので、「たまに規約が守られない」という状態になります。原因が分かりにくい失敗です。

手順を規約に入れた場合。関係ない依頼のときも毎回読まれます。直接の害はありませんが、AGENTS.md が長くなり、他の規則の重みが下がります。第9回で「守られた割合で測る」と書いたのは、この劣化を見るためです。

取りに行くべき情報を規約に書き写した場合。書いた時点では正しく、時間が経つと古くなります。そして、古くなったことに誰も気づきません。事例2で起きたのがこれです。

増やす順番

3つを同時にそろえる必要はありません。順番があります。

最初は AGENTS.md だけです。第3回の /init で作った下書きを育てるところから始めます。多くの作業は、これだけで足ります。

スキルを足すのは、AGENTS.md が長くなってきたときか、手順を3回説明したときです。切り出す対象は、その時点でもう決まっています。

MCP を足すのは、リポジトリの外を見ないと進まない作業が出てきたときだけです。先に用意しても使われません。第11回で書いたとおり、つないだ数が増えると選択の精度が下がるので、必要が出てから足すほうが結果もよくなります。

必要が証明されてから足す。第9回から3回続けて同じことを書いていますが、これがこの部の結論です。

次の回

ここまでで、Codex に規約と手順と経路を渡せるようになりました。ただ、渡したものが守られたかどうかは、まだ人が目で確かめています。

第13回からは、確かめる側を機械にします。GitHub Actions で品質の門を作り、そこを通らないものは反映できない状態にします。

参照した情報

• 引用した規約とスキルは BenriWorks のブログおよび Android アプリのリポジトリで実際に運用しているもの
• 疎通確認の事例は2026年9月に実施した検証の記録