AGENTS.md Cursor cursor rules .mdc AIコーディング 2026

CursorでのAGENTS.md完全セットアップガイド — .cursor/rulesと組み合わせる実践パターン（2026年版）

The Prompt Shelf ·

AGENTS.mdはCursorで動く。そして.cursor/rules/と正しく組み合わせれば、二つのシステムが競合せず互いを補完し合う構成になる。このガイドでは、同一プロジェクトで両者を使う場合のセットアップを一通り解説する。

CursorがAGENTS.mdを読み込む仕組み（2026年版）

Cursorは特別な設定なしにAGENTS.mdを読み込む。プロジェクトルートにファイルを置くだけで、Cursorのエージェントが自動的に検出する。

ファイルの探索順序

Cursorは「最近傍の祖先」方式でファイルシステムを走査する。

  1. プロジェクトルートのAGENTS.md — 最初に読み込まれ、プロジェクト全体に適用される
  2. サブディレクトリのAGENTS.md — そのサブディレクトリ内で作業しているとき読み込まれ、ルートレベルの内容よりそのスコープで優先される
  3. CLAUDE.md — CursorはCLAUDE.mdも読み込む（.cursor/rules/やAGENTS.mdに加えて）

つまりモノレポでは次のような構成が可能になる。

repo-root/
├── AGENTS.md          ← 全体に適用
├── packages/
│   ├── api/
│   │   └── AGENTS.md  ← packages/api/内での作業時のみ適用
│   └── web/
│       └── AGENTS.md  ← packages/web/内での作業時のみ適用

Cursor 0.48以降の動作（2026年）

Cursor 0.48からAGENTS.mdはChat、Composer、Agentモードの全モードで読み込まれる。これが.cursorrulesとの決定的な違いだ。.cursorrulesはAgentモードでは読み込まれない。Cursorのエージェントモードを使って自律的なタスク（大規模リファクタリング、テスト生成、複数ファイルの一括編集）を実行するなら、AGENTS.mdが三つのモードすべてをカバーする唯一の命令ファイルになる。

.cursor/rules/との優先関係

AGENTS.mdと.cursor/rules/*.mdcは競合しない。Cursorは両方を読み込んでコンテキストをマージする。内容が重複した場合、alwaysApply: trueやマッチするglobパターンで適用される.mdcルールの方が文脈的な重みを持ちやすい。安全な方針として、二つのシステム間でコンテンツを重複させないこと。

AGENTS.md vs .cursor/rules/ .mdcフォーマット — 何をどちらに書くか

二つのフォーマットは同じ問題の異なる側面を解決する。

AGENTS.md.cursor/rules/*.mdc
ポータビリティ全AIツール対応（Codex、Copilot、Gemini CLI、Claude Code、Cursor）Cursor専用
フォーマットプレーンMarkdownMDC（Markdown + YAMLフロントマター）
スコープ制御ディレクトリベース（最近傍の祖先）YAMLのglobパターン
自動適用スコープ内では常に読み込まれる条件付き（alwaysApplyまたはglobマッチ時）
向いている用途ツール横断の標準、アーキテクチャ、コマンドCursor固有の動作、ファイルタイプ別スコープ

振り分けの基本ルール

  • ツール横断の標準 → AGENTS.md。 CursorでもCodexでもClaude Codeでも適用されるべきルールはAGENTS.mdに書く。技術スタック、コマンド、命名規則、アーキテクチャの境界線。
  • Cursor固有の動作 → .mdcファイル。 Cursor機能を参照するルール、glob起動に依存するルール、Cursorのコンテキストモデル前提のルールは.mdcに書く。*.tsxファイル専用のコンポーネントパターン、src/db/**限定のDB規約など。

.mdcファイルに「TypeScriptのstrictモードを使う」と書くのはAGENTS.mdの仕事を横取りしている。.mdcファイルに「*.tsxファイルではサーバーコンポーネントをデフォルトとし、use clientディレクティブはリーフノードのみで使う」と書くのは、AGENTS.mdにはできないこと（.tsxファイル編集時だけルールを適用する）を実現している。

CursorプロジェクトへのAGENTS.mdセットアップ手順

ステップ1: ファイルを作る

touch AGENTS.md

src/やサブディレクトリではなく、Gitリポジトリのルートに置く。ルートに置くことで、どのファイルを開いていてもCursorが読み込める。

ステップ2: Cursorが特に重視するセクションを記述する

Cursorのエージェントが最も重視するセクション:

  • Commands — ビルド、テスト、リント、開発サーバーのコマンド。Cursor はこれらを使って編集後の検証を実行する。
  • Code Style — 言語、フォーマッター設定、命名規則、リンターが検出できない事項。
  • Architecture — ディレクトリ構成、何がどこにあるか、触ってはいけないファイル。

重要度は下がるが有用なもの: 背景コンテキスト、制約事項、外部サービスに関するメモ。

ステップ3: フルテンプレート（TypeScript/Reactプロジェクト）

# AGENTS.md

## Commands

\`\`\`bash
# インストール
pnpm install

# 開発
pnpm dev             # Next.js 開発サーバー :3000
pnpm dev:api         # Express APIサーバー :4000

# テスト
pnpm test            # Vitest ユニットテスト
pnpm test:e2e        # Playwright E2E（開発サーバー起動が必要）
pnpm test:watch      # Vitest ウォッチモード

# 品質チェック
pnpm lint            # ESLint
pnpm typecheck       # tsc --noEmit
pnpm format          # Prettier

# ビルド
pnpm build           # 本番ビルド
\`\`\`

## Code Style

- TypeScript strictモード; `noUncheckedIndexedAccess: true` 有効
- `any`禁止 — `unknown`を使い型ガードで絞り込む
- 名前付きエクスポートのみ; ページとレイアウト以外のデフォルトエクスポートは禁止
- `const`優先; ミュータブルな操作を避ける
- エラーハンドリング: サービス関数は常に`{ data, error }`タプルを返す — サービス層では例外をthrowしない
- インポート: `src/`は`@/`パスエイリアスを使う; 一段階以上上に遡る相対パスは禁止

## Architecture

- **App層**: `src/app/` — Next.js App Routerのページとレイアウトのみ
- **Components**: `src/components/` — 共有UI; `src/features/` — 機能固有コンポーネント
- **Services**: `src/services/` — 全外部API呼び出し; コンポーネント内でfetch()を直接呼ばない
- **Database**: `src/db/` — Drizzle ORMスキーマとクエリのみ; 他の場所で生SQLを書かない
- **Config**: 環境変数は`src/config/env.ts`で`t3-env`経由; `process.env`に直接アクセスしない

## Constraints

- `src/db/migrations/`内のファイルを手動で修正しない — `pnpm db:generate`を実行する
- 依存関係を追加する前に`src/lib/`に既存ユーティリティがないか確認する
- 認証ロジックは`src/middleware/auth.ts`に集約 — ルートハンドラに認証チェックをインラインで書かない
- 全サーバーアクションは`src/lib/safe-action.ts`の`safeAction`ラッパーを使う

ステップ4: CursorがAGENTS.mdを読んでいるか確認する

新しいChatまたはComposerセッションを開いて、AGENTS.mdに書いてある内容について質問する。

「このプロジェクトのテスト実行コマンドは何ですか？」

AGENTS.mdに記載した正確なコマンド（例: pnpm test、pnpm test:e2e）が返ってくればファイルが読み込まれている。npm testのような推測が返ってくれば何か問題がある。

AGENTS.mdが読み込まれない主な原因:

  • ファイルがプロジェクトルートにない（src/や他のサブディレクトリに置いてしまっている）
  • Cursorのワークスペースがリポジトリルートより上の親ディレクトリで開かれている
  • AGENTS.mdが.gitignoreに含まれている（稀だが起きる）
  • Cursorのバージョンが0.43より古い（AGENTS.mdサポートは0.43で追加された）

AGENTS.md + .mdcルールを矛盾なく組み合わせる

最もよくある失敗はAGENTS.mdと.mdcファイルの間でコンテンツを重複させることだ。ルールが両方に存在すると二つの問題が起きる: Cursorが冗長なコンテキストを受け取りトークンを無駄遣いし、どちらか一方を更新したとき、もう一方が古くなって矛盾が生まれる。

原則: AGENTS.mdに書いたことは.mdcで繰り返さない

AGENTS.mdに「TypeScriptのstrictモードを使う」と書いてあれば、.mdcファイルで同じことを書く必要はない。特定のファイルタイプに対して精度の高い補足ルールを追加することはできるが、基本ルールの繰り返しは保守コストを生む。

ファイルタイプスコープには.mdcを使う

AGENTS.mdは一様に適用される。.mdcファイルはコードベースの特定エリアに異なるルールを当てる手段だ。

.cursor/rules/
├── react-components.mdc     # glob: src/components/**/*.tsx
├── api-routes.mdc           # glob: src/app/api/**/*.ts
├── database.mdc             # glob: src/db/**/*.ts
└── tests.mdc                # glob: **/*.test.ts, **/*.spec.ts

重複なしの階層化の例

AGENTS.md（プロジェクト全体）:

## Code Style
- TypeScript strictモード
- 名前付きエクスポートのみ
- `any`禁止 — `unknown`を使う

.cursor/rules/react-components.mdc（*.tsxにスコープ）:

---
description: Reactコンポーネントパターン
globs: ["src/**/*.tsx", "src/**/*.jsx"]
alwaysApply: false
---

## Reactパターン

デフォルトはサーバーコンポーネント。以下の場合のみ`"use client"`を追加する:
- ブラウザAPI（window、document、localStorage）
- useStateまたはuseReducer
- useEffectまたはライフサイクルメソッド
- クライアントサイドの状態を持つイベントハンドラ

.mdcファイルは.tsxファイル編集時にのみ関係するReact固有の詳細ルールを追加している。AGENTS.mdはどこにでも適用される内容を担う。

モノレポでのAGENTS.md階層設計

モノレポはAGENTS.mdのディレクトリベーススコープから最も恩恵を受ける構成だ。各パッケージが固有のコンテキストを持ちながらも、ルートを汚染しない。

ディレクトリ構成

repo-root/
├── AGENTS.md                    ← 共有: ワークスペースコマンド、全体規約
├── package.json                 ← ワークスペースルート
├── packages/
│   ├── api/
│   │   ├── AGENTS.md           ← API固有: Fastifyパターン、DBアクセスルール
│   │   └── src/
│   ├── web/
│   │   ├── AGENTS.md           ← Web固有: Next.jsパターン、コンポーネントルール
│   │   └── src/
│   └── shared/
│       ├── AGENTS.md           ← 共有ライブラリ: エクスポート対象、内部限定の区別
│       └── src/
└── .cursor/
    └── rules/
        ├── monorepo-root.mdc   # alwaysApply: true — ワークスペース全体のCursorルール
        ├── api-package.mdc     # glob: packages/api/**
        └── web-package.mdc     # glob: packages/web/**

Cursorの最近傍祖先ルールの動作

packages/api/src/routes/users.tsを開いているとき、Cursorは次を読み込む。

  1. repo-root/AGENTS.md（ルート、常に）
  2. repo-root/packages/api/AGENTS.md（スコープ内の最近傍祖先）

packages/web/AGENTS.mdやpackages/shared/AGENTS.mdは読み込まれない — 現在のファイルの祖先ディレクトリではないためだ。

ルートAGENTS.md（共有ワークスペースルール）

# AGENTS.md

## Workspace Commands

\`\`\`bash
# 全パッケージインストール
pnpm install

# 全テスト実行
pnpm test

# 全パッケージビルド
pnpm build

# 特定パッケージの作業
pnpm --filter @repo/api dev
pnpm --filter @repo/web dev
\`\`\`

## 共通規約

- 全パッケージでTypeScript strictモードを使う
- パッケージ名は`@repo/<name>`形式
- 共通ユーティリティは`packages/shared/`に集約 — 新しいユーティリティを追加する前に確認
- クロスパッケージの依存関係は依存グラフを確認してから追加する

## リポジトリ構成

- `packages/api/` — Fastify REST API
- `packages/web/` — Next.jsフロントエンド
- `packages/shared/` — 共有型定義、ユーティリティ、定数

パッケージ別AGENTS.md（API固有）

# packages/api/AGENTS.md

## Commands

\`\`\`bash
pnpm dev        # APIサーバー起動 :4000
pnpm test       # APIテスト実行（Vitest）
pnpm db:push    # 開発DBにスキーマ変更を反映
pnpm db:studio  # Drizzle Studio起動
\`\`\`

## Architecture

- ルート: `src/routes/` — リソースごとに1ファイル
- サービス: `src/services/` — ビジネスロジック; ルートにDBアクセスを書かない
- DB: `src/db/` — DrizzleスキーマとクエリのみKnex

## API規約

- 全ルートは`{ data, error, meta }`形式で返す
- Zodでバリデーション; スキーマは`src/schemas/`に置く
- 認証はJWT; ミドルウェアは`src/middleware/auth.ts`
- エラーコードは`src/lib/errors.ts`で定義済み — 独自のエラーコードを作らない

.cursorrulesからAGENTS.mdへの移行

AGENTS.mdに移すもの

Cursor固有でない内容はそのまま移行できる。

  • ビルド・テストコマンド
  • コードスタイルルール（命名規則、フォーマット設定、インポート構造）
  • アーキテクチャの説明（ディレクトリの役割、触ってはいけないファイル）
  • 技術スタック（フレームワーク、言語バージョン、主要ライブラリ）
  • ワークフローメモ（PRの進め方、レビューが必要なもの）

.mdcに移すもの

Cursor固有またはスコープが有効なもの。

  • 特定のファイルタイプにのみ適用されるべきルール
  • Cursor機能を参照するルール
  • コードベースの特定エリアにしか関係しないコンテキスト

移行スクリプト

既存の.cursorrulesをAGENTS.mdの出発点として分割するスクリプト:

#!/bin/bash
# migrate-cursorrules.sh
# .cursorrulesをAGENTS.mdにコピーする

if [ ! -f ".cursorrules" ]; then
  echo ".cursorrulesが見つかりません"
  exit 1
fi

if [ -f "AGENTS.md" ]; then
  echo "AGENTS.mdが既に存在します。上書きを防ぐため中断します。"
  echo "手動でマージしてください: diff .cursorrules AGENTS.md"
  exit 1
fi

cat > AGENTS.md << 'HEADER'
# AGENTS.md

<!-- .cursorrulesから移行。内容を見直して整理すること。-->
<!-- Cursor固有のルールを削除し、.cursor/rules/*.mdcに移動すること -->

HEADER

cat .cursorrules >> AGENTS.md

echo "AGENTS.mdを.cursorrulesから作成しました"
echo "次のステップ:"
echo "  1. AGENTS.mdを確認し、Cursor固有の内容を削除"
echo "  2. Cursor固有ルールを.cursor/rules/*.mdcに移動"
echo "  3. 後方互換性のため.cursorrulesを残すか削除するか決める"

移行後に.cursorrulesを残すべきか？

.cursorrulesとAGENTS.mdが同一プロジェクトに共存する場合、Cursorは全モードでAGENTS.mdを読み込み、Chat/ComposerではAGENTS.mdの読み込みの前に.cursorrulesを参照する（後方互換）。実用的な判断として: チームメンバーが古いCursorバージョンを使っている過渡期は.cursorrulesを残す。全員が0.43以降に移ったら、二つのファイルを同期させる保守コストを避けるため.cursorrulesを削除する。

新規プロジェクトであれば.cursorrulesは最初から作らず、AGENTS.md + .cursor/rules/*.mdcの構成で始めることを推奨する。

FAQ

CursorはAGENTS.mdを読み込みますか？

はい。Cursorはバージョン0.43以降、Chat・Composer・Agentモードの全モードでAGENTS.mdを読み込む。最近傍祖先の探索モデルを使い、プロジェクトルートと、作業中のファイルの祖先ディレクトリにあるAGENTS.mdをすべて読み込む。設定は不要。

AGENTS.mdと.cursor/rules/の違いは何ですか？

AGENTS.mdはクロスツール標準だ。Codex、Copilot、Gemini CLI、その他のツールも読み込む。ディレクトリベースのスコープを使い、ファイルはそのディレクトリ以下に適用される。.cursor/rules/ファイルはYAMLフロントマターのglobパターンで精密なスコープと条件付き起動を実現する。AGENTS.mdはスコープ内では常に読み込まれる。.mdcルールは条件を満たしたときのみ読み込まれる。

CursorではAGENTS.mdと.cursorrulesどちらを使うべきですか？

新規プロジェクトならAGENTS.md一択。.cursorrulesはCursorのAgentモードで読み込まれないため、エージェンティックなワークフローでは不完全。AGENTS.mdは三つのモードすべてをカバーし、他のAIツールでも読まれるため投資対効果が高い。既存プロジェクトなら段階的に移行する: ツール横断のコンテンツをAGENTS.mdに移し、Cursor固有のルールを.mdcファイルに移動する。

CursorがAGENTS.mdを読んでいるか確認するには？

新しいChatまたはComposerセッションを開き、AGENTS.mdに記載した内容について質問する（例:「このプロジェクトのテスト実行コマンドは？」）。ファイルに書いた正確なコマンドが返ってくれば読み込まれている。Cursorのコンテキストパネルで確認することもできる（バージョンによる）。

AGENTS.mdと.cursor/rules/を両方使えますか？

はい、これが推奨構成だ。AGENTS.mdはツール横断・プロジェクト全体のコンテキストを担当し、.cursor/rules/*.mdcはCursor固有の動作とファイルタイプスコープを担当する。唯一のルール: 両者の間でコンテンツを重複させない。AGENTS.mdにルールがあれば、.mdcファイルはその上に精度の高い補足を追加するのみで、同じルールを繰り返さない。

Cursor AgentモードでもAGENTS.mdは動きますか？

はい — これが.cursorrulesの代わりにAGENTS.mdを使う主な理由の一つだ。CursorのAgentモードはAGENTS.mdを読み込むが.cursorrulesは読み込まない。自律的なタスク（複数ファイルのリファクタリング、テスト自動生成、一括変更）でもプロジェクト指示が有効であってほしいなら、AGENTS.mdが全モード対応の唯一のフォーマットになる。

関連記事

Cursorワークフローでのシークレット管理

AGENTS.mdが内部サービスや環境固有のエンドポイントを参照する場合、認証情報をファイル自体に書かないこと。1Password CLIのop runでシークレットをランタイム注入すれば、チーム全員がAGENTS.mdを安全に共有できる。

Share on X

Related Articles

AGENTS.md in Cursor: Complete Setup Guide (2026)

How Cursor reads AGENTS.md, discovery order, combining with .cursor/rules/ .mdc files, monorepo patterns, and migration from .cursorrules — complete 2026 setup guide.

AGENTS.md vs Cursor Project Rules（.mdc）比較 — どちらを使い、どう共存させるか（2026年版）

CursorのProject Rules（.mdc形式）とAGENTS.mdは似た問題を異なるトレードオフで解決する。フォーマット、スコーピング、アクティベーション、デュアルスタック構成まで実例で比較。

AGENTS.md vs Cursor Project Rules (.mdc): Which to Use and How to Run Both (2026)

Cursor's .mdc Project Rules and AGENTS.md solve similar problems with different trade-offs. Here's a direct comparison of file formats, scoping behavior, activation logic, and the dual-stack setup that gets you the best of both.

Migrating from .cursorrules to AGENTS.md: A Step-by-Step Guide for 2026

Your .cursorrules file works, but it's locked to Cursor and ignored in Agent mode. Here's the complete migration path to AGENTS.md — conversion script, gotchas, and how to keep both working during the transition.

Explore the collection

Browse all AI coding rules — CLAUDE.md, .cursorrules, AGENTS.md, and more.

Browse Rules