エージェントへの指示は1つの巨大ファイルにせず、AGENTS.md・DESIGN.md・SKILL.mdに分けてgitで管理する
コーディング規約もUIトークンも個人の癖も1枚に詰め込まず、役割ごとにファイルを分け、チーム共通と個人用を層で分け、同じ間違いが続いたら同じPRで指示ファイルを直す。
どんな問題を解決するか / いつ使うか
指示ファイルが肥大化して、デザインのルールがコーディング規約に埋もれたり、人によって別のIDEで挙動が違ったりするとき。
やり方
- 役割でファイルを分ける
- AGENTS.md：リポジトリの規約、テストコマンド、設計上の境界
- DESIGN.md：タイポグラフィ、色のトークン、余白、UIパターン
- SKILL.md：繰り返す作業の手順
- 1つの正本をツール間で共有する：Claude Code、Cursor、OpenCodeなどで同じファイルを読ませる（シンボリックリンクや読み込み設定）。IDEが違ってもチームの挙動をそろえる。
- チームのルールと個人の好みを分ける
- プロジェクト層（gitにコミット）：守るべき規約とビルドの関門
- ユーザー層（例：
~/.agents/）：自分の文体、エディタの癖、ショートカット
- 指示ファイルをコードと同じく版管理する：エージェントが同じミスを繰り返したら、その修正PRの中で指示ファイルも直し、チーム全員に学びを引き継ぐ。
注意点
- DESIGN.mdを分けたら、AGENTS.md側から「UIを触るときは必ずDESIGN.mdを読む」と参照させないと読まれないことがある（DESIGN.md（トークン＋ルール）を置き、AGENTS.md / CLAUDE.md から必ず読ませる）。
- 個人の好みの色やフォントがプロジェクト層に混ざると、他の人の生成結果まで変わる。
出典
- @JadMadi post