AGENTS.md・Skills・MCPの役割を分ける

AIエージェントの設定を増やしていくと、「このルールは毎回必要か」「この手順はSkillにすべきか」「外部サービスへの接続はどこで宣言するか」が分かりにくくなります。全部をAGENTS.mdへ書けば、今度は毎回読み込むコンテキストが大きくなります。

そこで、公式資料とOpenCodeの設定を並べて、情報の置き場所を責務で分けた。結論は、プロジェクトの常時ルールをAGENTS.md、条件付きの手順をSkill、外部システムへの入口をMCPに置く構成です。個人設定はチームの契約へ混ぜません。

まず4つの責務を表にする

置き場所	いつ効くか	置くもの	置かないもの
`AGENTS.md`	そのプロジェクトで常に	構成、コマンド、禁止事項、完了条件	長い専門手順、秘密情報
Skill	条件に合う依頼のとき	入力、手順、検証、テンプレート	全作業に共通する短い規約
MCP	外部データや操作が必要なとき	GitHub、DB、ブラウザー、社内APIへの接続	コーディング規約
個人設定	自分の環境だけ	口調、表示、既定値	チーム必須のルール

Codexの資料は、AGENTS.md、Skills、MCPを別々の拡張点として説明しています。OpenCodeもRules、Skills、MCP serversを用意しています。ツールごとに探索するファイルと設定形式が異なります。

この表が便利なのは、ファイル名ではなく「いつ必要か」で判断できるからです。

エージェントが毎回知らないと危険な情報だけを置きます。

詳細な背景や長い手順は別ドキュメントへ移し、AGENTS.mdからリンクします。入口が短ければ、重要な制約が長い説明に埋もれにくいです。

リポジトリ内のAGENTS.mdはチームで再現する方針なのでGit管理しやすいです。一方、ホームディレクトリの設定は個人の既定値であり、チームの必須ルールを代わりに置く場所ではありません。

Skillには、全タスクでは不要だが、同じ種類の作業で繰り返す知識をまとめます。本文だけでなく、テンプレート、検証スクリプト、参考資料も含められます。

最低限、次の順序が分かるように書きます。

たとえば「PDFを作成してリンク切れを検査する」はSkill向きです。「このリポジトリではpnpmを使う」は、毎回必要な短い契約なのでAGENTS.md向きになります。

MCPは、エージェントが外部のデータや操作へ到達する入口です。GitHubのIssueを読む、DBを検索する、ブラウザーを操作する、といった能力を扱います。ローカルの手順書とは性質が違います。

ここで確認したいのは、接続できるかだけではありません。

「MCPで操作できる」と「エージェントが自由に操作してよい」は別の判断です。最小権限と明示的な承認境界を先に決めます。

@fileのような記法は、特定のハーネスがファイルをコンテキストへ追加するためのUIであることが多いです。AGENTS.md、Skill、MCPの共通規格として永続的な依存関係にしない方がよいです。

長期的に参照する情報は実ファイルとして保存し、各ツールの公式形式から相対パスで案内します。会話中だけ解決する添付記法へ、チームの運用を預けません。

複数のハーネスで共有しやすいのは、命名規約、コーディング規約、代表的な検証コマンド、公開可能な文章テンプレートです。

反対に、次はツールごとに分ける方が安全です。

共通の原本から各ツール用の薄い設定を生成するなら、変換規則と生成先をスクリプトへ書き、差分をレビューできるようにします。暗黙のシンボリックリンクだけで全てを共有すると、片方の更新が別のハーネスへ予期せず伝わります。

新しい情報をどこへ置くか迷ったら、次の順で確認します。

1つのルールを複数箇所へコピーせず、原本を1つ決めてリンクします。この分離で、コンテキストの膨張、設定の矛盾、過剰な外部権限を同時に抑えられます。