Cursor の Agent 設定フォルダ構成をざっくり整理

Cursor で Agent を使い込むと、「ルールはどこ？」「Skills はどこに置く？」「Cloud 用の設定は？」と、設定ファイルの置き場所が気になってくる。

この記事では、Cursor の Agent 関連設定のフォルダ構成をざっくり地図化して、何をどこに置けばいいかを整理する。Commands や ナレッジ（@Docs / 索引） など、似た概念も含めて触れる。

先に結論

プロジェクトで共有したいものは .cursor/ とルートの AGENTS.md
自分だけ全プロジェクトに効かせたいものは ~/.cursor/（User 設定）
短い規約 → Rules / AGENTS.md、長い手順 → Skills、定型プロンプト（/ で呼ぶ） → Commands
外部ドキュメント → @Docs（設定画面で URL 索引）、リポジトリ内の知識 → 索引 + @ファイル + Skills の references/
Cloud Agent 用の実行環境は .cursor/environment.json
ホーム配下（~/.cursor/*）は Cloud では基本使えない。共有したい設定はリポジトリ側へ

似た概念の整理（Rules / Skills / Commands / ナレッジ）

まず混同しやすいものを表にまとめる。詳細は後述の各節へ。

概念          主な置き場              何を入れる              どう効く
──────────────────────────────────────────────────────────────────────
AGENTS.md     ルート / サブDir       プロジェクト地図・方針   作業Dirに応じて自動
Rules         .cursor/rules/*.mdc   短い規約・制約          常時 / glob / 賢く / @
Skills        .cursor/skills/       多段階ワークフロー       /skill または Agent 自動
Commands      .cursor/commands/     定型プロンプト           /command で明示呼び出し
Subagents     .cursor/agents/       専門エージェント定義     Agent が委譲
Plugins       Marketplace 等        上記を束ねた配布物       インストールで一括
@Docs         設定画面（Features）   外部ドキュメント URL     @Docs でコンテキスト追加
コード索引     （自動）              リポジトリ全体           Agent 検索・grep
@ メンション  チャット入力           ファイル / フォルダ等    会話に明示添付

Commands と Skills … どちらも / から呼べるが、Commands は「短い再利用プロンプト」、Skills は「手順・スクリプト付きワークフロー」向き。新規は Skills 優先でよく、旧 Commands は /migrate-to-skills で移行できる。

Rules と AGENTS.md … どちらも「Agent に常に読ませたい文脈」。AGENTS.md は frontmatter 不要の Markdown、Rules は glob や適用条件を細かく書ける。

ナレッジ … ファイルとして1か所に置くものではなく、(1) リポジトリ索引、(2) @Docs の外部ドキュメント、(3) @ で明示添付、(4) Skills の references/、の組み合わせで足すイメージ。

全体地図（どこに何があるか）

リポジトリ（プロジェクト）
├── AGENTS.md                 # Agent 向け指示（簡易・推奨）
├── CLAUDE.md                 # 互換用（AGENTS.md と同様に読まれる）
├── .cursorrules              # レガシー（非推奨）
├── .cursorignore             # 索引 / コンテキスト除外
└── .cursor/
    ├── rules/                # Project Rules（*.mdc）
    ├── skills/               # Skills（各フォルダに SKILL.md）
    ├── commands/             # Commands（*.md — / で呼ぶ定型プロンプト）
    ├── agents/               # カスタム Subagents
    ├── mcp.json              # プロジェクト MCP
    ├── hooks.json            # Hooks 定義
    ├── hooks/                # Hook スクリプト
    ├── environment.json      # Cloud Agent 環境
    └── Dockerfile            # environment.json から参照（任意）

ユーザーホーム（自分のマシン）
~/.cursor/
├── mcp.json                  # グローバル MCP
├── skills/                   # グローバル Skills
├── commands/                 # グローバル Commands（Cloud では届きにくい）
├── agents/                   # グローバル Subagents
├── plugins/local/            # ローカル開発中の Plugin
├── hooks.json / hooks/       # グローバル Hooks（Cloud では無効）
└── ...（CLI 設定・worktrees など）

設定画面 / ダッシュボード（ファイルではない）
├── User Rules / Team Rules   # Customize → Rules
├── @Docs 索引                # Settings → Features → Docs
├── Team Commands             # Teams ダッシュボード
└── Plugins / Team MCP        # Customize / Dashboard

加えて、User Rules / Team Rules はファイルではなく、Cursor の Customize 画面・ダッシュボード側にある。

1. 指示・ルール系

AGENTS.md（ルート / サブディレクトリ）

プレーンな Markdown で Agent に読ませる指示
ルートだけでなくサブディレクトリにも置ける（より近いものが優先）
Cloud 向けには「Cursor Cloud specific instructions」節を置くのが定石

.cursor/rules/*.mdc

Project Rules。frontmatter 付き .mdc（.md は無視される）
関心ごとに分割して git 管理するのが基本
サブフォルダも可。インポート先は .cursor/rules/imported/

User Rules / Team Rules

User Rules … Customize → Rules（自分の全プロジェクト）
Team Rules … ダッシュボード（組織全体、優先度最高）
競合時の目安: Team → Project → User

レガシーの .cursorrules は非推奨。.cursor/rules か AGENTS.md へ寄せる。

2. Skills（SKILL.md）

「この手順でやって」系の多段階ワークフロー。1 Skill = 1 フォルダ + SKILL.md。

.cursor/skills/
└── my-skill/
    ├── SKILL.md
    ├── scripts/      # 任意：Agent が実行するスクリプト
    ├── references/   # 任意：長い Runbook・ナレッジ
    └── assets/       # 任意：テンプレ等

置き場所

プロジェクト: .cursor/skills/ または .agents/skills/
グローバル: ~/.cursor/skills/（Cloud では非推奨）
モノレポ: apps/web/.cursor/skills/ のようにサブツリーにも置ける

短い規約は Rules、長い手順は Skills。詳細資料は references/ に逃がすと本体が読みやすい。

3. Commands（/ で呼ぶ定型プロンプト）

チャットで /command-name と打って呼ぶ、再利用可能なプロンプト。Skills より短く、明示呼び出し専用向き。

.cursor/commands/
├── write-tests.md        # /write-tests
├── review-pr.md          # /review-pr
└── fix-build.md          # /fix-build

置き場所（重要）

プロジェクト: .cursor/commands/（リポジトリルートのみ）
グローバル: ~/.cursor/commands/（手元専用。Cloud では届きにくい）
Team: ダッシュボードの Team Commands
Plugins: Plugin パッケージ内の commands/

Skills との違い・移行

Commands … 短い定型プロンプト。毎回 / で呼ぶ想定
Skills … 長い手順 + scripts/references。Agent が文脈で自動選択も可
新規は Skills を優先。既存 Commands は /migrate-to-skills で Skills へ変換可能

注意: Commands はサブディレクトリの .cursor/commands 非対応（Rules / Skills / AGENTS.md とは異なる）。モノレポではルートに集約し、ファイル名で区別する（例: api-write-tests.md）。

4. ナレッジ・コンテキスト（ファイル以外も含む）

「ナレッジ」は単一フォルダではなく、Agent に渡す参照情報の総称。次の 4 層で考えると整理しやすい。

① コードベース索引（自動）

リポジトリを開くと Cursor が索引。Agent は grep / セマンティック検索で参照
除外: .cursorignore（追加除外）、.gitignore（自動尊重）
秘密情報・巨大生成物は ignore して索引対象から外す

② @Docs（外部ドキュメント索引）

設定: Settings → Features → Docs で URL を追加。Cursor がクロールして索引
使い方: チャットで @Docs → 索引済みドキュメントを選択
向いている例: EF Core / ASP.NET Core / 社内 API 仕様など、学習データより新しい公式ドキュメント
リポジトリ内ファイルではないので、チーム共有は URL と設定の運用で揃える

③ @ メンション（会話への明示添付）

@ファイル / @フォルダ … 関連箇所を会話に直接載せる
@Git … 差分・ブランチ diff
@Terminals … ターミナル出力
対象がはっきりしているとき有効。不明なら Agent の検索に任せてもよい

④ Skills の references/（リポジトリ内ナレッジ）

長いチェックリスト・Runbook は Skill 本体ではなく references/ に置く
git 管理でき、Cloud Agent からも読める（プロジェクト配下のため）
例: .cursor/skills/ef-migration/references/rollback-checklist.md

5. MCP / Hooks / Subagents / Plugins

MCP（mcp.json）

プロジェクト: .cursor/mcp.json
グローバル: ~/.cursor/mcp.json
外部 API・DB・Issue トラッカー等を Agent ツールとして接続
Cloud では Team MCP や Dashboard 側の設定も重要

Hooks

プロジェクト: .cursor/hooks.json + .cursor/hooks/（Cloud でも有効）
ユーザー: ~/.cursor/hooks.json（Cloud では無効）

Subagents

プロジェクト: .cursor/agents/*.md
グローバル: ~/.cursor/agents/
探索・レビューなど、専門タスクを別コンテキストで委譲

Plugins（Marketplace / Team Marketplace）

Rules / Skills / Commands / MCP / Hooks / Subagents を1 パッケージにまとめた配布物
インストール: Customize サイドバー / Marketplace
自作テスト: ~/.cursor/plugins/local/
Teams では Dashboard → Plugins で Team Marketplace 共有可能

6. Cloud Agent 用（environment.json）

Cloud Agent は隔離されたリモート環境で動く。依存関係や起動手順はここに寄せる。

パス: .cursor/environment.json
Dockerfile 等は .cursor からの相対パスで参照
Secrets はダッシュボード側。ファイルにハードコードしない
解決の目安: リポジトリの environment.json → 個人環境 → チーム環境

あわせて AGENTS.md に Cloud 専用の注意（テストの回し方、禁止事項など）を書いておくと安定する。

7. ローカルと Cloud で違うところ

~/.cursor/*（グローバル Skills / Commands / Hooks / MCP など）は手元では効くが Cloud では基本届かない
チームで共有したい設定は .cursor/ と AGENTS.md に置く
Project Hooks（リポジトリ内）は Cloud でも使える。User Hooks は Cloud 無効
@Docs はユーザー設定依存。Cloud 単体では同じ索引が効かない場合がある
実行環境の差は environment.json と Secrets で埋める

現場向けの置き方（おすすめ）

まず AGENTS.md に「どう動いてほしいか」を短く書く
繰り返し出る規約は .cursor/rules/ に分割
手順が長いものは .cursor/skills/<name>/SKILL.md（詳細は references/）
毎回同じプロンプトなら .cursor/commands/ か Skills へ（新規は Skills 優先）
外部ライブラリは @Docs で索引、リポジトリ内は .cursorignore を整える
外部ツール連携は .cursor/mcp.json（秘密情報は Secrets）
Cloud を使うなら .cursor/environment.json + AGENTS.md の Cloud 節

ざっくりまとめ

地図の中心は .cursor/ と AGENTS.md
Rules = 規約、Skills = 手順、Commands = / 呼び出しプロンプト、MCP = 外部道具
ナレッジ = コード索引 + @Docs + @ メンション + Skills references/
Plugins = 上記をまとめて配布。Customize から管理
自分専用は ~/.cursor/、チーム / Cloud 共有はリポジトリへ

「設定が増えて何が効いているかわからない」ときは、プロジェクト配下かホーム / 設定画面かを切り分けると早い。