.cursorrulesは2026年のCursorでも動く。ただし2つの問題がある。1つはCursorのAgent modeで無視されること。もう1つは、CodopilotやClaude Code等の他ツールを追加するたびに別の設定ファイルが必要になること。AGENTS.mdはこの2つを同時に解決する。
この記事では、.cursorrulesからAGENTS.mdへの移行を変換スクリプト付きで具体的に説明する。ハマりやすい罠も全て記載した。
移行で何が変わるのか
まず何を移行するかを正確に把握しておく。
.cursorrulesはフラットなMarkdownファイルだ。1ファイル、スコープはプロジェクト全体。CursorのChatとComposerモードで自動読み込みされる。Agent modeでは読まれない。
AGENTS.mdは本質的に同じコンセプトだが、2点異なる。
- ディレクトリ階層をサポート——深さの異なる複数のAGENTS.mdがそれぞれのサブツリーにスコープされる
- マルチツール標準——Codex、Copilot、Gemini CLI、Windsurf等が対応している
コンテンツのフォーマットはほぼ同一で、どちらも普通のMarkdown。移行の大部分は「構造と配置」の話であり、ルールの書き直しではない。ちゃんと管理されている.cursorrulesなら内容の大半はほぼそのままAGENTS.mdに使える。
移行で変わらないこと:
.cursor/rules/*.mdc（CursorのMDC形式）には影響しない。MDCからも移行したい場合は別の作業- CursorのChat/Composerで
.cursorrulesの代わりにAGENTS.mdを読むようにはならない（互換性維持のため.cursorrulesも残す必要がある）
Step 1: .cursorrules の内容を仕分ける
.cursorrulesを開いて、各ルールを4つに分類する。
カテゴリA: 汎用ルール — どのAIツールにも適用されるもの。アーキテクチャ、技術スタック、コマンド、命名規則、テスト要件など。
カテゴリB: Cursor専用 — CursorのUI・機能への言及がある指示（「Cursorのdiff viewを使って」「マルチ候補表示を使う」等）。これは.cursorrulesに残す。
カテゴリC: 説明・背景 — ルールの「なぜ」を説明するテキスト。人間が読むCONTRIBUTING.mdには有用だが、AI向けの指示ファイルではノイズになる。別ファイルに移す。
カテゴリD: 古いルール — 特定の状況のために追加したが今は不要になったルール。削除。
ほとんどのファイルはカテゴリAが80%以上だ。移行作業の核心はAをAGENTS.mdにコピーし、BをCursorのファイルに残し、CDを整理することだ。
Step 2: 変換スクリプトを実行する
機械的な作業はスクリプトに任せる。ファイルの作成、内容のコピー、Cursor固有の記述の除去、確認用のdiff生成を行う。
#!/bin/bash
# migrate-cursorrules.sh
set -e
CURSORRULES=".cursorrules"
AGENTS_MD="AGENTS.md"
if [ ! -f "$CURSORRULES" ]; then
echo "Error: カレントディレクトリに .cursorrules がありません"
exit 1
fi
if [ -f "$AGENTS_MD" ]; then
echo "Warning: AGENTS.md が既に存在します。AGENTS.md.new として作成します。"
AGENTS_MD="AGENTS.md.new"
fi
CONTENT=$(cat "$CURSORRULES")
# Cursor固有の表現を汎用表現に置換
CONTENT=$(echo "$CONTENT" | sed \
's/Cursorのdiff view/コードレビュー/g' \
's/Cursorで/AIエディタで/g' \
's/Cursor固有/ツール固有/g')
cat > "$AGENTS_MD" << EOF
# AGENTS.md
<!-- .cursorrules から移行: $(date +%Y-%m-%d) -->
<!-- コミット前に標準ヘッダー構造で整理してください -->
$CONTENT
EOF
echo "$AGENTS_MD を作成しました"
echo ""
echo "次のステップ:"
echo "1. $AGENTS_MD を見直して標準ヘッダーで整理"
echo "2. Cursor固有ルールを .cursorrules に戻す"
echo "3. 動作確認: Cursor ChatやCodexで規約を確認する"
echo "4. Cursor Chat/Composer用に .cursorrules を残す"出力はあくまで出発点で、完成品ではない。次のステップで内容を整理する。
Step 3: 標準ヘッダーで整理する
AGENTS.mdはツールが検索しやすい一貫したセクション構造で書くと効果が高い。
# AGENTS.md
## プロジェクト概要
[プロジェクトの説明を1〜2文で]
## アーキテクチャ
[ディレクトリ構造、主要モジュール、設計上の決定事項]
## 技術スタック
[言語、フレームワーク、データベース、バージョン]
## コマンド
[ビルド・テスト・Lint・実行方法]
## コードスタイル
[命名規則、フォーマットルール、使うべきパターン]
## テスト
[テスト方針、カバレッジ要件、テストの書き方]
## 触ってはいけないもの
[事前承認なしに変更禁止のファイル・ディレクトリ]特に ## コマンド セクションは丁寧に書く。ツールはこのセクションを使ってコマンドを正確に生成する。
## コマンド
- インストール: pnpm install（npm installではない——ロックファイルはpnpm-lock.yaml）
- 開発: pnpm dev（Next.jsをポート3000、APIをポート3001で起動）
- テスト: pnpm test（Vitest、ウォッチモード） / pnpm test:run（単発実行）
- E2Eテスト: pnpm test:e2e（先に開発サーバーの起動が必要）
- Lint: pnpm lint（ESLint + Prettierチェック）
- ビルド: pnpm build（tsc + Next.jsビルド）
- 型チェック: pnpm tsc --noEmitStep 4: Cursor互換性の維持
移行後もCursor ChatとComposerには.cursorrules（または.cursor/rules/）が必要だ。CursorのAgent modeはAGENTS.mdを読むが、ChatとComposerは読まない。Cursorが設定読み込みを統一するまで、2ファイルの管理が続く。
対処策は2つ。
戦略1: 両方維持（シンプル、ただしドリフトリスクあり）
小規模チームで.cursorrulesを積極的にメンテしていれば機能する。
project-root/
├── .cursorrules # Cursor Chat/Composer用——同期を保つ
└── AGENTS.md # その他ツール全般用戦略2: AGENTS.mdを真のソースとして.cursorrulesを生成する
より堅牢。AGENTS.mdを正として.cursorrulesを自動生成する。
# オプションA: シンボリックリンク（最もシンプル）
ln -sf AGENTS.md .cursorrules
# オプションB: スクリプト生成（Cursor非対応コンテンツの除去が必要な場合）
python3 scripts/generate-cursorrules.py生成スクリプトの例:
# scripts/generate-cursorrules.py
"""AGENTS.mdから.cursorrulesを生成する。Cursor非対応セクションを除去。"""
from __future__ import annotations
import re
def generate_cursorrules(source: str = "AGENTS.md", output: str = ".cursorrules") -> None:
with open(source) as f:
content = f.read()
# AGENTS.mdのメタデータコメントを除去
content = re.sub(r'^<!-- .*?-->\n', '', content, flags=re.MULTILINE)
# Cursor非対応のセクションを除去（プロジェクトに合わせてパターンを調整）
sections_to_remove = [
r'## Copilot Workspace.*?(?=^##|\Z)',
r'## OpenAI Codex.*?(?=^##|\Z)',
]
for pattern in sections_to_remove:
content = re.sub(pattern, '', content, flags=re.MULTILINE | re.DOTALL)
with open(output, 'w') as f:
f.write(content.strip() + '\n')
print(f"{output} を {source} から生成しました")
if __name__ == "__main__":
generate_cursorrules()pre-commitフックで自動同期:
# .git/hooks/pre-commit
#!/bin/bash
if git diff --cached --name-only | grep -q "AGENTS.md"; then
python3 scripts/generate-cursorrules.py
git add .cursorrules
fiStep 5: Claude Codeとの共存
CLAUDE.mdが既にある場合は、CLAUDE.mdがAGENTS.mdをインポートする形にするとルール競合を防げる。
# CLAUDE.md
@import AGENTS.md
## Claude Code固有設定
### Hooks
# Claudeが書くたびにlintを実行
PostToolUse[Write]: pnpm lint {path}
### サブエージェント委譲
# /src/api/ 配下のタスクはAPIサブエージェントに委譲この構成でAGENTS.mdが共有ルールの単一ソースとなる。CLAUDE.mdは純粋に追加設定。CopilotはAGENTS.mdを直接読む。3ファイル間の同期問題が解消される。
よくあるハマりポイント
「Agent modeでまだルールが無視される」
Cursor Agent modeはAGENTS.mdと.cursor/rules/*.mdcを読む。ルートの.cursorrulesは読まない。.cursorrulesだけを使っていた場合、ルートにAGENTS.mdを置けばAgent modeが解決する。.cursor/rules/ MDCファイルを使っていた場合はそちらも引き続き有効。
「CodexがルールをCursorより厳密に守る」
これは正常な動作。CodexはAGENTS.mdを権威ある設定として厳密に従う。CursorはAGENTS.mdを強いコンテキストとして扱い、日和見的に適用する。ツールごとに期待値を調整する。
「大きいAGENTS.mdでトークン超過」
.cursorrulesが長かった（3,000トークン超）場合、そのままAGENTS.mdにコピーするとCopilot等のツールでアテンション限界に達する。移行後に説明・背景テキストをトリミングし、指示だけを残す。1,500トークンの指示特化ファイルは、4,000トークンの説明混じりファイルより実際の遵守率が高い。
「ディレクトリ固有ルールがグローバルに適用されてしまう」
.cursorrulesにコードベースの特定部分だけに関わるルールがあった場合、ルートのAGENTS.mdにそのままコピーするとグローバルに適用される。サブディレクトリのAGENTS.mdに分割するのが正解。
src/
├── AGENTS.md # フロントエンドルール
└── api/
└── AGENTS.md # バックエンドルール移行前後の実例
移行前（.cursorrules — 480トークン）:
TypeScriptの熟練開発者として、Next.js 15 + Tailwindプロジェクトで作業してください。
TypeScript strictモードを常に使う。anyは禁止。外部データにはunknownを使う。
Reactコンポーネントはサーバーコンポーネントを優先。ブラウザAPIや状態管理が
必要な場合のみ'use client'を追加。変更提案にはCursorのdiff viewを使う。
テストはVitest。全コンポーネントにco-locatedテストファイルが必要。
テスト実行: `pnpm test`
DBはDrizzle ORM経由でPostgreSQL。スキーマは`src/db/schema.ts`。
このファイルを直接変更せず、`pnpm db:generate`でマイグレーションを生成する。
`/migrations/`ディレクトリには絶対に触らない。移行後（AGENTS.md — 同内容を整理）:
# AGENTS.md
## プロジェクト
Next.js 15 + TypeScript + Tailwind。PostgreSQL + Drizzle ORM使用のフルスタックアプリ。
## コマンド
- インストール: pnpm install
- 開発: pnpm dev
- テスト: pnpm test（Vitest、ウォッチ） / pnpm test:run（CI用）
- DB: pnpm db:generate（マイグレーション生成）、pnpm db:migrate（適用）
## コードスタイル
- TypeScript strictモード: any禁止、外部データにはunknownを使う
- React: デフォルトはサーバーコンポーネント、ブラウザAPIや状態が必要な時のみ'use client'
- スキーマファイル（`src/db/schema.ts`）: 直接編集禁止、必ず `pnpm db:generate` を使う
## テスト
- Vitestで単体テスト
- 全コンポーネントにco-locatedテストファイルが必要
## 触ってはいけないもの
- `/migrations/` は直接変更禁止
- `src/db/schema.ts` の直接編集禁止——必ず `pnpm db:generate` を実行する「Cursorのdiff viewを使う」という行は削除。残りは明確なセクションに整理。結果的にCodexやCopilotでの遵守率も上がり、スキャンもしやすい。