AIエディタを手間をかけずに使う
–– 最新のAIエディタ制御の状況と、ゆるく整えておきたいポイント
はじめに（異論は大いに認める）
この記事は、「AIエディタを、なるべく手間をかけず、それなりに安定して使いたい」 人向けの整理です。 現場によって正解は違うはずなので、「うちはこうしてる」系の反論・別解あると思います。
また、今回は、MCP / 外部 Tools 連携そのものは話題から外します。AIエディタ／エージェントの“振る舞い”を決める文書・仕組みに絞り説明します。
まず前提：制御は「プロジェクト」と「タスク」で別物
AIエディタ制御がややこしくなる原因は、似たようなファイルやプロンプトが増えるのに、実は解いている問題が2種類あるからです。
-
プロジェクト制御（リポジトリ単位）
セットアップ、テスト、規約、触ってはいけない領域など「この repo での前提」 -
タスク制御（作業単位）
Issue→Spec、README磨き、評価ハーネス作成など「この仕事の手順」
この２つは初めから分かれていたわけでもありませんし、それぞれのAIエディタは相手の機能と競争しながら、開発されています。つまり、２つの“乱立” の歴史が始まるのです。
歴史A：エディタ専用の「プロジェクトルール」乱立 → AGENTS.md → AAIF
1) 乱立の時代（各エディタの競争のはて）
まず起きたのが、**「このプロジェクトではこう動いて」**を伝える“エディタ専用のルールファイル”が増殖したことです。
- Cursor：
.cursorrules（legacy）→.cursor/rules/*.mdc（Project Rules） - Claude Code：
CLAUDE.md（特別扱いのガイドファイル） - Cline：Cline Rules（
.clinerulesなどの運用が広がる）
それぞれのエディタでは合理的なんですが、複数のエディタが使われるとどうなるでしょう？
- 似た目的（プロジェクト前提を教える）のファイルが、ツールごとに名前も置き場所も形式も違う
- エディタの乗り換え・併用のたびに「同じ内容を別フォーマットで書き直す」
- 何個も制御ファイルができると、「どれでプロジェクトのAIエディタを動くの？」かもわからなくなる
やっぱり乱立は混乱のもとになっていきました。
2) 統一の流れへ：AGENTS.md
AGENTS.md は、OpenAI が 2025年8月に公開した「コーディングエージェント向けのガイド（Markdown 1枚）」です。
“突然生まれた新発明”というより、現場の不便が先にあって、あとから形になったタイプのやつです。
- まず OpenAIの社内で「エージェントに この repo の前提 を渡す、共通の置き場が必要」になった
- ツール併用が当たり前になり、ツール固有ファイルに寄せるより repo側に1枚置く方が得になった
- それが 2025年8月に AGENTS.md として公開され、採用が広がるほど“共通の置き場”の価値が上がっていきました。
やりたいことはシンプルで、
- ツール固有のルールファイルを増やすのではなく
- repo側に「必ず読まれる置き場」を1つ固定して
- セットアップ／テスト／規約／禁止事項をそこへ集める
という方向です。 AGENTS.md は評価を集め、複数ツールで共有しやすい形に寄っていきました。
3) “その後”：AAIF（中立な場で標準を育てる）
AGENTS.md のような「プロジェクト標準」が効いてくると、次に出てくるのが ツール間の相互運用です。
併用・乗り換え・引き継ぎが当たり前になるほど、「特定ベンダー配下ではなく、中立な場で標準を育てる」価値が上がります。
2025年12月に Linux Foundation 傘下で Agentic AI Foundation（AAIF） が設立され、初期貢献として MCP / goose / AGENTS.md が挙げられました。
ここで言いたいのは「AGENTS.md という整理が、個々の現場の工夫から一歩進んで、複数ツールで共有される前提になりつつある」ということです。
参考（AAIFの発表。これだけ見ればOK）：
歴史B：カスタムプロンプト（/で呼べるやつ含む）乱立 → Claude Skills → Codex Skills
1) 乱立の時代
次に起きたのが タスク用プロンプトの乱立です。よくやる指示は簡単に呼び出せるようにしたい。それは皆さんが思う事です。
そこで各エディタで以下のようなことが起き始めました。
- 特定のファイルを
/コマンド的に呼び出す - プロンプト集を特別のフォルダで管理
個々のエディタでは最高に便利なのですが、やっぱり時間がたつと混乱のもとになっていきます。
2) 整理の第一波：Claude が Skills を前に出した
乱立してしまったタスクを、どのように扱うか、その方法が標準化されねばなりません。この問題に対し、各タスクを一つのフォルダ（手順書＋参照資料＋スクリプト）としてパッケージにするというアイデアが、Anthropicから Agent Skills として提唱されました。
それまでは、作りこんだカスタムのプロンプトファイルで勝負するとか、先ほどのAGENTS.mdになんでもルールを詰め込んで書くなどバラバラなせかいでしたが、特定の仕事の手順書をパッケージ(フォルダ)として扱うことができるようになったことで、必要なタスクのみエージェントに取り込むことができるようになりました。
参考（Claude Skills。これだけ見ればOK）：
3) 整理の第二波：Codex も Skills に寄ってきた
最近は、Skills が特定陣営だけの概念ではなくなってきていて、Codex 側も skills（skills.md / SKILL.md） という形で寄せています。 ここでも起きているのは乱立からの統一の流れです。
参考（Codex Skills）：
現時点で「Skills が AAIF に採択・寄贈された標準」となったわけではありませんが、いま起きているのは、Claude → Codex の順で標準化の流れがきていると考えてよいと思います。
ここまでの整理：AGENTS.md と Skills は役割が違う
ここまでを整理してみましょう。
- AGENTS.md = プロジェクトの前提（環境・規約・禁止・実行コマンド）
- Skills = タスクの手順（仕事レシピ・テンプレ・参照資料・スクリプト）
ツール固有のルール（.cursor/rules/*.mdc、CLAUDE.md、.clinerules…）は今後も残ると思いますが、標準にのっていく方 が運用が軽くなっていくと予想されます。
なるだけ手をかけない：AGENTS.md + αくらいが丁度いい
今あげられた仕組みを全部使いこなせば、何かすごいことができるかもしれませんが、それには苦労が伴います。「じゃあ結局、どんなファイルを持てばいい？」の落としどころとして、次のAGENTS.md+αくらいがおすすめです。
-
AGENTS.md（ルート） docs/concept.mddocs/spec.mddocs/architecture.md-
docs/plan.md（またはPLANS.md）
.
├─ AGENTS.md
└─ docs/
├─ concept.md
├─ spec.md
├─ architecture.md
└─ plan.md
5ファイルの役割
- AGENTS.md：エージェント向け README（Setup/Test/規約/禁止事項と docs への導線）
- concept：背景・目的・非ゴール
- spec：仕様（API/振る舞いを“最低限”）
- architecture：主要構成と責務（図はなくてもよい）
- plan：今やることの順番、完了条件、進捗の更新（＝作戦書）
AIエディタへの依頼文は、毎回だいたいこれで済みます。
AGENTS.mdを読む- 必要なら
docs/*を参照docs/plan.mdのタスクを上から進める
plan.md（/PLANS.md）はベストプラクティス寄りに定着してきた
そして、5ファイルの中でも、plan.md は特に効きます。
- 「次に何をやるか」
- 「完了条件は何か」
- 「いま（NOW）のチェックリストはどれか」
を **外部メモリ（作戦書）**として固定できるので、AIエディタが迷いにくく、説明の回数も減ります。
チェックリスト形式で記載し、チェックさせると良く機能してくれます。
bon を短く紹介（骨組みをワンコマンドで作る）
「ファイル構成が良さそうなのは分かったけど、最初の雛形を作るのがだるい」場合の小ネタとして、bon-agents-md（bon コマンド）があります。
インストール
npm install -g bon-agents-md
使い方（例）
bon # カレントにガイド＋docs骨格を生成(Python想定)
bon --editor cursor # cursor向け（.cursorrules）
bon --lang ts # 言語ガイダンス変更
bon は、エディタ別のガイドファイル（AGENTS.md / .cursorrules / copilot-instructions.md）と、docs/OVERVIEW.md＋docs/{concept,spec,architecture,plan}.md の骨格をまとめて用意する、という位置づけです。
（生成物はあくまで叩き台なので、ここから自分のプロジェクトに合わせて育てます。）
おわりに
まとめると、
- プロジェクト制御の乱立 → AGENTS.md で統一が進む
- タスク制御の乱立 → Claude Skills → Codex Skills で整理が進みつつある
- そのうえで、なるだけ手を抜いて回すなら、
AGENTS.md + いくつかのファイル(concept/spec/architecture/plan)くらいを先に置いておくとラクになりやすいです。なかでも plan.md は効果が出やすい（作戦書として効く）印象があります。
という整理になります。
どうやらAGENTS.mdもそこまでメジャーではないようです。まずは第一歩としていかがでしょうか。また、「うちはこうしてる」系の運用Tipsは、たぶん次のベストプラクティスの種なので、ぜひコメントにご意見お寄せください。
（補足）「厚く書けば誤生成が減る」、Spec Driven Developmentはなかなか難しい
私はSpec Driven Development(SDD)の品質の高い文書を完璧にそろえるという方法に積極的ではありません。
仕様化せずにバイブスに任せればいいとは 決して思っていません が、個人的にはデメリット部分のしっぺ返しがきつく、なかなかうまく行っていないです。
- SDDのメリット：文書を緻密にして誤生成を減らす狙いは分かりやすい
- SDDのデメリット：設計変更や方針転換で「更新が追いつかない」瞬間に、古い文章がそのまま誤生成の材料になりやすい
このトレードオフを避ける意味でも、まずは AGENTS.md + concept/spec/architecture/plan の “軽い標準” を持っておく方が、
コスパは良いことが多いのではないかと思います。