AIコーディングツールが増え続けた結果、プロジェクトルートが見慣れないファイルだらけになってきた。
.cursorrules、CLAUDE.md、AGENTS.md、.windsurfrules、GEMINI.md——それぞれが微妙に異なるフォーマットを持ち、何のためのファイルか一見わからない。チームに新しいメンバーが入るたびに「これ何ですか？」と聞かれる。
この記事では、現在メジャーなAIコーディングツールが定義するMDファイルをすべて整理し、複数ツールを使う現場でどう管理するかを実践的に解説する。テンプレートと図付きで、読み終わったらそのまま自分のプロジェクトに適用できる構成にした。
主要10ツール × MDファイルの早見表
CLAUDE.md・.cursorrules・AGENTS.md・GEMINI.md・copilot-instructions.mdの書き方テンプレート
DESIGN.md・SOUL.md・CONTEXT.md・PLAN.mdという新トレンド
複数ツール併用時のファイル管理戦略
.gitignoreとの付き合い方
ミニマル構成 vs フル装備構成の比較
MDファイルが増えた背景——なぜこうなったのか
2023年以前、AIコーディングツールはほぼGitHub Copilotだけだった。設定ファイルはなく、補完精度はモデル任せだった。
状況が変わったのは2024年。Cursor、Cline、Aider、そしてClaude Codeが登場し、それぞれが「AIにプロジェクトのルールを教える」仕組みを実装し始めた。統一規格はない。各ツールが独自のファイル名とフォーマットを定義した。
2026年現在、主要AIコーディングツールが定義するMDファイルは30種類以上に達している。プロジェクトルートに10個近いAI設定ファイルが並ぶのは珍しくない。
なぜ統一されないのか。理由は単純で、各社がツールの差別化要因としてこの「コンテキスト注入」の仕組みを位置づけているからだ。Claude CodeはCLAUDE.mdを、CursorはCursorrulesを、それぞれの製品体験に最適化した形で設計している。W3CやIETFのような標準化機関が動き始めてもいない。
一方で、現場エンジニアからの「もう少し整理してほしい」という声は大きい。後述するCONTEXT.mdのようなツール横断ファイルが生まれているのも、この不満への実践的な答えだ。
ツール別MDファイル早見表
現在のメジャーAIコーディングツールが定義するファイルを一覧化した。
| ツール | ファイル | 用途 | 備考 |
|---|---|---|---|
| Claude Code | CLAUDE.md |
ルール・コーディング規約 | グローバル: ~/.claude/CLAUDE.md、プロジェクト: リポジトリルート |
| Claude Code | .claude/skills/*/SKILL.md |
カスタムスキル定義 | スキルごとにディレクトリ分割 |
| Claude Code | .claude/settings.json |
権限・ツール設定 | .claude/settings.local.jsonは個人設定 |
| Cursor | .cursorrules（旧） |
コーディングルール | 2024年末以降は非推奨だが動作継続 |
| Cursor | .cursor/rules/*.mdc（新） |
ルール（複数ファイル対応） | .mdc形式、frontmatterで適用条件を指定 |
| Cursor | .cursorignore |
インデックス除外 | .gitignoreと同形式 |
| GitHub Copilot | .github/copilot-instructions.md |
リポジトリ全体の指示 | GitHub公式サポート |
| GitHub Copilot | .instructions.md |
ディレクトリ単位の指示 | サブディレクトリに配置可 |
| GitHub Copilot | .github/agents/*.agent.md |
エージェント定義 | Copilot Agents機能 |
| OpenAI Codex | AGENTS.md |
エージェント命令 | ルートとサブディレクトリ両対応 |
| OpenAI Codex | AGENTS.override.md |
個人・環境別上書き | AGENTS.mdの設定を上書き |
| Windsurf | .windsurfrules（旧） |
コーディングルール | 旧形式、現在も動作 |
| Windsurf | .windsurf/rules/*.md（新） |
ルール（複数ファイル対応） | .cursor/rulesに近い構造 |
| Gemini CLI | GEMINI.md |
コンテキスト・ルール | ~/.gemini/GEMINI.mdでグローバル設定 |
| Gemini CLI | .aiexclude |
ファイル除外 | .gitignoreと同形式 |
| Cline | .clinerules |
命令ファイル | プロジェクトルートに配置 |
| Aider | CONVENTIONS.md |
コーディング規約 | 任意のファイル名をconfig指定可能 |
| Aider | .aider.conf.yml |
ツール設定 | モデル・温度・ファイルパターン等 |
| Continue.dev | ~/.continue/config.yaml |
全体設定 | ユーザーホームに配置、プロジェクト単位なし |
| JetBrains AI | .aicontext |
コンテキスト情報 | JetBrains IDE専用 |
| Replit Agent | /.agents/skills/ |
エージェントスキル | Replit固有のディレクトリ構造 |
この表のファイルを全部作っても、使っていないツールのファイルはただの飾りになる。自分のチームが実際に使うツールのファイルだけを管理するのが基本だ。
ファイル配置の全体像
プロジェクトルートにすべてのファイルが存在する場合のディレクトリ構造を図示する（実際にはここまで揃えることはまずない）。
(Claude Code)"] ROOT --> AGENTS["AGENTS.md
(OpenAI Codex)"] ROOT --> GEMINI["GEMINI.md
(Gemini CLI)"] ROOT --> CR[".cursorrules
(Cursor 旧)"] ROOT --> WR[".windsurfrules
(Windsurf 旧)"] ROOT --> CLR[".clinerules
(Cline)"] ROOT --> CONV["CONVENTIONS.md
(Aider)"] ROOT --> DESIGN["DESIGN.md
(横断トレンド)"] ROOT --> SOUL["SOUL.md
(横断トレンド)"] ROOT --> CONTEXT["CONTEXT.md
(横断トレンド)"] ROOT --> CLAUDE_DIR[".claude/"] ROOT --> CURSOR_DIR[".cursor/"] ROOT --> GH_DIR[".github/"] ROOT --> WINDSURF_DIR[".windsurf/"] CLAUDE_DIR --> SETTINGS[".claude/settings.json"] CLAUDE_DIR --> SKILLS[".claude/skills/*/SKILL.md"] CURSOR_DIR --> RULES[".cursor/rules/*.mdc"] GH_DIR --> COPILOT[".github/copilot-instructions.md"] GH_DIR --> AGENTS2[".github/agents/*.agent.md"] WINDSURF_DIR --> WR2[".windsurf/rules/*.md"]
主要5ファイルの書き方テンプレート
1. CLAUDE.md — Claude Code向け
Claude Codeが最初に読むファイル。プロジェクトの「憲法」に相当する。Claude Codeのベストプラクティスガイドでも詳しく解説しているが、ここでは最小限の実用テンプレートを示す。
# プロジェクト名
## 概要
- 用途: Webアプリ / CLIツール / ライブラリ 等
- 技術スタック: TypeScript + Next.js + PostgreSQL
## コーディング規約
- インデント: スペース2つ
- 命名: キャメルケース（変数・関数）、パスカルケース（クラス・型）
- コメント: 英語
- テスト: Vitest、カバレッジ80%以上
## 禁止事項
- console.logをコミットに含めない
- any型の使用禁止
- 直接のDOM操作禁止（Reactのstateで管理）
## よく使うコマンド
- 開発サーバー: `npm run dev`
- テスト: `npm test`
- 型チェック: `npm run typecheck`
- ビルド: `npm run build`
## ファイル構造
- `src/app/` — Next.js App Router
- `src/components/` — 共通コンポーネント
- `src/lib/` — ユーティリティ・API クライアント
CLAUDE.mdはシンプルであるほどよい。100行を超えたら整理するサインだ。読まれない詳細な規約より、守ってほしい5つのルールの方が効果が高い。
2. .cursor/rules/project.mdc — Cursor向け（新形式）
.mdc形式はfrontmatterで「どのファイルに適用するか」を指定できる。旧.cursorrulesとの違いはここだ。
---
description: プロジェクト全体のコーディングルール
globs:
- "**/*.ts"
- "**/*.tsx"
alwaysApply: true
---
# TypeScript コーディングルール
## 型定義
- 戻り値の型を明示する
- `interface`より`type`を優先
- ジェネリクスの型パラメータには意味のある名前をつける
## エラーハンドリング
- try-catchはasync関数の外側で使わない
- エラーはResult型でラップする
## コンポーネント
- PropsはP接尾辞で命名: `ButtonProps`
- デフォルトエクスポートのみ使用
---
description: テストファイル専用ルール
globs:
- "**/*.test.ts"
- "**/*.spec.ts"
alwaysApply: false
---
# テストルール
- describe/it形式を使う
- モックは最小限に
- テストファイルは実装ファイルと同じディレクトリに配置
3. AGENTS.md — OpenAI Codex向け
AGENTS.mdはサブディレクトリにも配置でき、そのディレクトリ内での動作を上書きできる。
# Agent Instructions
## Role
このリポジトリはeコマースAPIサーバーです。
Python 3.12 + FastAPI + PostgreSQL で構成されています。
## Coding Standards
- PEP 8に従う
- 型ヒントを必ず書く
- docstringはGoogle形式
## Testing
- pytestを使う
- フィクスチャは`tests/conftest.py`に定義する
- DBテストは実DBを使う（モック禁止）
## Important Paths
- `app/` — アプリケーション本体
- `tests/` — テストスイート
- `alembic/` — マイグレーション
## Forbidden
- `eval()`の使用禁止
- シークレットをコードにハードコードしない
- グローバル変数の使用禁止
4. GEMINI.md — Gemini CLI向け
Gemini CLIはGoogleが2025年にリリースしたCLIツール。GEMINI.mdの構造はCLAUDE.mdに近い。
# Gemini Context
## Project Overview
This is a Go microservice for payment processing.
Runtime: Go 1.22, PostgreSQL 16, Redis 7.
## Code Style
- Follow effective Go guidelines
- Use `fmt.Errorf` with %w for error wrapping
- Avoid global state; use dependency injection
## Testing
- Use `testing` package (no testify)
- Table-driven tests for edge cases
- Integration tests in `*_integration_test.go`
## Architecture
- `cmd/` — entrypoints
- `internal/` — private packages
- `pkg/` — public packages
## Do NOT
- Use `panic` outside of main()
- Skip error handling
- Use `init()` functions
5. .github/copilot-instructions.md — GitHub Copilot向け
GitHub Copilotの指示ファイルはGitHub公式にサポートされており、PRコメントやコードレビューでも参照される。
# Copilot Instructions
## Repository Overview
This monorepo contains:
- `packages/api` — Node.js REST API
- `packages/web` — React frontend
- `packages/shared` — Shared utilities
## Code Style
- Use TypeScript strict mode
- Prefer functional components with hooks
- Use Zod for runtime validation
## API Design
- Follow RESTful conventions
- Return `{ data, error, meta }` shape
- Use HTTP status codes correctly (201 for create, etc.)
## Pull Request Guidelines
- Keep PRs under 400 lines changed
- Include test coverage for new features
- Update CHANGELOG.md for user-facing changes
## Security
- Sanitize all user input
- Never log sensitive data
- Use parameterized queries only
新トレンド——ツール横断で広がるMDファイル
2025年以降、特定ツールに紐づかない「汎用コンテキストファイル」が増えている。4つのファイルを紹介する。
UIデザインシステム
カラー・コンポーネント・タイポ"] SOUL["SOUL.md
AIの人格・トーン
話し方・絵文字・敬語"] CONTEXT["CONTEXT.md
要件・アーキテクチャ
技術的制約・ゴール"] PLAN["PLAN.md
実行計画
TODOリスト・フェーズ"] CONTEXT --> DESIGN CONTEXT --> SOUL CONTEXT --> PLAN CLAUDE["CLAUDE.md
(Claude Code)"] AGENTS["AGENTS.md
(Codex)"] CR[".cursorrules
(Cursor)"] DESIGN --> CLAUDE DESIGN --> AGENTS DESIGN --> CR SOUL --> CLAUDE SOUL --> AGENTS CONTEXT --> CLAUDE CONTEXT --> AGENTS CONTEXT --> CR
DESIGN.md — UIデザインシステムをAIに教える
DESIGN.mdはデザインシステムをAIコーディングツールに伝えるための新しい慣習ファイルだ。カラーパレット、タイポグラフィ、コンポーネントの命名規則をMarkdownで記述する。
# Design System
## Colors
- Primary: `#3B82F6` (blue-500)
- Secondary: `#8B5CF6` (violet-500)
- Danger: `#EF4444` (red-500)
- Background: `#0F172A` (slate-900)
- Surface: `#1E293B` (slate-800)
- Text: `#F8FAFC` (slate-50)
## Typography
- Heading: Inter, 600 weight
- Body: Inter, 400 weight
- Code: JetBrains Mono, 400 weight
- Base size: 16px, scale: 1.25
## Components
- Button: `<Button variant="primary|secondary|ghost">`
- Input: `<Input label="" error="" hint="">`
- Card: `<Card padding="sm|md|lg">`
## Layout
- Max width: 1280px
- Grid: 12 columns, gap 24px
- Breakpoints: sm(640), md(768), lg(1024), xl(1280)
## Icons
- Library: lucide-react
- Size: 16px (inline), 20px (standalone), 24px (featured)
SOUL.md — AIの「話し方」を統一する
SOUL.mdはAIの人格・トーンを定義するファイルだ。チームで複数人がAIツールを使う場合、AIの応答スタイルをそろえるために使われる。
# Soul
## Personality
あなたはシニアエンジニアのペアプロパートナーです。
経験豊富で、率直で、技術的に正確です。
## Communication Style
- 丁寧体（〜です/〜ます）を使う
- 絵文字は使わない
- 箇条書きより文章を優先する
- 「なぜそうするか」の理由を必ず説明する
## Code Review Tone
- 指摘は「〜の方がよい理由は」形式で説明する
- 良い点も必ずコメントする
- 重大な問題と軽微な問題を区別する
## Avoid
- 「すごいですね」「完璧です」のような空虚な称賛
- 不確実なことを断言する
- 聞かれていないことを自主的に変更する
CONTEXT.md — プロジェクトの「なぜ」を伝える
CONTEXT.mdはプロジェクトの技術的背景、制約、ゴールをまとめるファイルだ。新しいAIツールを使い始めるたびにこのファイルを読ませることで、プロジェクト固有の文脈を素早く共有できる。
# Project Context
## Goal
請求書管理SaaSの月次処理エンジンを再構築する。
旧システム（PHP 7.4）からGo 1.22に移行中。
## Constraints
- 既存のPostgreSQLスキーマは変更不可（他チームとの共有DB）
- 月末処理は500万件のトランザクションを2時間以内に完了すること
- 外部APIはStripe・freee・マネーフォワードの3つと連携
## Current Phase
Phase 2: 月次集計ロジックの移植（2026年Q2）
Phase 1完了: 単票発行・PDF生成（2026年Q1）
## Key Decisions
- Goのgoroutineで並列処理（旧PHPのキューは廃止）
- Redisをジョブキューとして使用（Kafkaは過剰）
- DBマイグレーションはAlembicからgooseに移行
PLAN.md — タスクの現状をAIと共有する
PLAN.mdは実行中のタスクリストをAIと共有するためのファイルだ。長いセッションをまたいで作業する場合、AIが「今どこまで進んでいるか」を把握するために使う。
# Plan
## In Progress
- [ ] POST /invoices エンドポイントの実装
- [x] バリデーション層
- [x] DBアクセス層
- [ ] 外部API連携（Stripe）
- [ ] テスト
## Done
- [x] GET /invoices 一覧取得
- [x] GET /invoices/:id 詳細取得
- [x] DBマイグレーション（invoicesテーブル）
## Next
- PUT /invoices/:id 更新
- DELETE /invoices/:id 論理削除
- 月次バッチジョブのスケルトン作成
PLAN.mdはセッション内の作業メモに近い。タスクが完了したらファイルを削除してもよいし、アーカイブとして残してもよい。gitに入れる必要はないので、.gitignoreに追加する運用も一般的だ。
複数ツールを使う場合の管理戦略
同じチームでClaude CodeとCursorを両方使う——今やよくある状況だ。
問題は「同じ内容を複数のフォーマットで書き続けなければならない」こと。リポジトリのスタックが変わるたびにCLAUDE.mdと.cursorrulesとAGENTS.mdを同時に更新しなければならない。
3つの戦略を比較する。
| 戦略 | 概要 | メリット | デメリット |
|---|---|---|---|
| 個別管理 | ツールごとに独立したファイルを管理 | ツール固有機能を最大限活用できる | 更新が2〜3箇所に分散する |
| シングルソース | CONTEXT.mdに共通ルールを書き、各ファイルから参照 |
更新箇所が1つに集約 | 参照先を読まないツールには効かない |
| コード生成 | スクリプトで全ファイルを自動生成 | 確実に同期できる | スクリプトの保守コストが発生 |
現実的には「シングルソース戦略」が多くのチームに合う。共通ルールをCONTEXT.mdに書き、CLAUDE.mdや.cursorrulesではそれをコピー＋ツール固有の設定を追加する構成だ。
project-root/
├── CONTEXT.md ← 共通ルール（ツール非依存）
├── CLAUDE.md ← CONTEXT.md の内容 + Claude Code固有設定
├── .cursorrules ← CONTEXT.md の内容 + Cursor固有設定
├── AGENTS.md ← CONTEXT.md の内容 + Codex固有設定
└── .github/
└── copilot-instructions.md ← CONTEXT.md の内容 + Copilot固有設定
CONTEXT.mdに変更があれば、各ファイルに反映する。変更頻度は低い（スタックが変わる時くらい）ので、手動でも十分管理できる。
ミニマル構成 vs フル装備構成
どこまでファイルを用意するかは、チームのサイズとツールの使い方による。
シンプル、保守コスト最小"] D --> D1["CONTEXT.md（共通）
+ 使うツールごとのファイル
更新箇所を最小化"] E --> E1["CONTEXT.md + DESIGN.md + SOUL.md
+ 全ツールのファイル
スクリプト生成を推奨"]
ミニマル構成（個人プロジェクト・小規模チーム向け）
project-root/
└── CLAUDE.md ← これだけ（Claude Codeを主に使う場合）
マルチツール構成（2〜5人チーム向け）
project-root/
├── CONTEXT.md ← 共通ルール
├── CLAUDE.md ← Claude Code
├── .cursor/
│ └── rules/
│ └── project.mdc ← Cursor
└── .github/
└── copilot-instructions.md ← Copilot
フル装備構成（大規模チーム・多ツール環境向け）
project-root/
├── CONTEXT.md ← 共通ルール
├── DESIGN.md ← デザインシステム
├── SOUL.md ← AI人格設定
├── CLAUDE.md ← Claude Code
├── AGENTS.md ← OpenAI Codex
├── GEMINI.md ← Gemini CLI
├── .clinerules ← Cline
├── .cursor/
│ └── rules/
│ ├── general.mdc
│ └── testing.mdc
├── .windsurf/
│ └── rules/
│ └── project.md
└── .github/
├── copilot-instructions.md
└── agents/
└── reviewer.agent.md
10個のファイルを用意しても、実際に使っていないツールのファイルは誰にも読まれない。ファイルの数より「今使っているツールのファイルが正確か」の方が重要だ。
.gitignoreとの付き合い方
AI設定ファイルには「チームで共有すべきもの」と「個人設定で管理すべきもの」の2種類がある。
| ファイル | git管理 | 理由 |
|---|---|---|
CLAUDE.md |
✅ コミット | チームルールはバージョン管理すべき |
.cursorrules |
✅ コミット | チームルール |
.cursor/rules/*.mdc |
✅ コミット | チームルール |
AGENTS.md |
✅ コミット | チームルール |
GEMINI.md |
✅ コミット | チームルール |
.github/copilot-instructions.md |
✅ コミット | GitHub統合のため必須 |
.claude/settings.json |
✅ コミット | プロジェクト権限設定（APIキー等は含めない） |
.claude/settings.local.json |
❌ 除外 | 個人設定（パス・個人トークン等） |
PLAN.md |
❌ 除外（任意） | 作業メモ的な用途なら除外してよい |
.aider.conf.yml |
⚠️ 状況次第 | APIキーを含む場合は除外 |
~/.continue/config.yaml |
- | ホームディレクトリのためgit管理外 |
.gitignoreに追加すべき行：
# AI tool personal settings
.claude/settings.local.json
.aider*
.env.local
# Optional: work-in-progress plan files
PLAN.md
「セキュリティ上のリスクがないか」を確認してからコミットする。特に.aider.conf.ymlはAPIキーを直接書ける仕様があるため注意が必要だ。
よくある失敗と対処法
AIツールを使い始めてMDファイルを書き慣れていないチームがやりがちな失敗を3つ挙げる。
失敗1: ルールが多すぎて守られない
50行を超えるCLAUDE.mdを書いても、AIがすべてを equally 重要視するわけではない。特に重要なルールは箇条書きの先頭に置き、全体は20〜30行に収める。
失敗2: 古くなっても更新しない
「Jestを使う」と書いてあるのに実際はVitestに移行済み——というケースが起きやすい。スタックを変更したときのチェックリストに「MDファイルの更新」を追加する習慣が必要だ。
失敗3: ツールを増やすたびに0から書く
前述のCONTEXT.mdシングルソース戦略を使えば、新しいツールを追加するときは「共通ルールをコピー + ツール固有の設定を追加」で済む。テンプレートを作っておくと負担が減る。
Claude Codeでの実践——CLAUDE.mdを段階的に育てる
Claude Codeのコーディング自動化システムを組む場合、CLAUDE.mdは最初から完璧を目指さず「使いながら育てる」のが実用的だ。
# Claude CodeにCLAUDE.mdの改善を提案させる
claude "このプロジェクトのCLAUDE.mdをレビューして、追加すべきルールを提案してください"
このコマンドを週1回実行するだけで、実際の作業から生まれた「暗黙のルール」を明文化できる。
また、Claude Codeには.claude/settings.jsonでツールの権限を設定する機能もある。
{
"permissions": {
"allow": [
"Bash(git status)",
"Bash(git log:*)",
"Bash(npm run:*)",
"Bash(cat:*)",
"Edit",
"Read"
],
"deny": [
"Bash(rm -rf:*)",
"Bash(git push --force:*)"
]
}
}
設定ファイルはコードレビューの対象に含める。チームメンバーが追加したルールがプロジェクト方針と矛盾していないか、PRで確認する習慣をつけるとよい。
これから——MDファイルは統一されるのか
現時点では各ツールが独自フォーマットを持つ状況が続いているが、いくつかの動きがある。
一つはCONTEXT.md・DESIGN.mdのような「ツール非依存ファイル」の普及だ。特定ツールに依存しない形でプロジェクトのコンテキストを記述する流れは今後も続くと思われる。
もう一つはLSPやIDEのプロトコルへの統合の可能性だ。AIコーディングツールがLanguage Server Protocolの拡張としてコンテキスト情報を共有する仕組みが提案されているが、まだ実用段階ではない。
当面は「ツール固有ファイル + 共通コンテキストファイル」という二層構造が現実解だ。今この記事で紹介した管理戦略は、仮に1年後に新しい標準が生まれても、移行コストが最小になるよう設計されている。
まとめ——自分のプロジェクトに合った構成を選ぶ
この記事で整理した内容を3行でまとめる。
- ツール別ファイルは30種以上あるが、使うツールのファイルだけを管理する
- 複数ツールを使う場合はCONTEXT.mdをシングルソースにして他を派生させる
- git管理はチームルールを含む全ファイルをコミット、個人設定（settings.local.json等）は除外
Claude Codeの詳細な使い方やDESIGN.mdの活用方法についても合わせて参照してほしい。
