cursor-best-practices

cursor-best-practices

エージェントと LLM 向けに最適化された Cursor のベストプラクティスを作成・管理するための、構造化されたリポジトリです。このスキルには、ルール、コマンド、スキル、サブエージェント、無視ファイル、Agent のセキュリティ、ワークフロー、コミュニティのリソースを網羅する references/（必要に応じて参照するドキュメント）と assets/templates/（ルール、コマンド、サブエージェントのテンプレート）が含まれています。

---

使用するタイミング

次のようなユーザーの依頼があった場合に、このスキルを適用します。

• Cursor をセットアップまたは初期化する、.cursor フォルダーを作成する、または「.cursor フォルダーをセットアップして」と依頼する
• .cursor/rules、AGENTS.md、またはルールのフロントマターを作成・編集する
• スラッシュコマンド、スキル、またはサブエージェントを作成・使用する
• .cursorignore または .cursorindexingignore を設定する
• Agent モード（Agent、Ask、Plan、Debug）、セマンティック検索、または @メンションを使用する
• TDD、git 形式のコマンド、大規模なコードベース、または Cursor のワークフローについて質問する
• ルールや MCP（cursor.directory）、またはスキルのおすすめ（skills.sh）を探す
• プラグイン、フック、Cloud Agent、CLI、ワークツリー、またはディープリンクについて質問する

---

ルール

配置場所： プロジェクトの .cursor/rules/（.md／.mdc）、ユーザーの Cursor Settings → Rules、チームのダッシュボード。優先順位： チーム → プロジェクト → ユーザー。

種類と使用するタイミング：

種類	使用するタイミング
常に適用	すべてのリクエストに影響させる必要がある場合（例：「TS で any を使わない」「完了前にテストを実行する」）。使用は控えめにします。
状況に応じて適用	関連する場合に適用する一般的なガイダンス（例：「関数コンポーネントを優先する」）。
特定のファイルに適用	globs を使用します（例：**/*.test.ts、**/api/**）。該当するファイルがコンテキストに含まれる場合にのみ、ルールが読み込まれます。
手動で適用	必要に応じて、ユーザーが @rule-name で呼び出します（例：リリース手順、レガシーな仕様）。

フロントマター： description（関連性の判断に役立つキーワードを含めます）、globs（ファイルごとの指定）、alwaysApply（使用はまれにします）。各ルールは <500 lines に収め、内容ごとに分割して references/ へのリンクを追加します。AGENTS.md はプロジェクトルートに置くプレーンな Markdown の代替手段で、フロントマターはありません。

ベストプラクティス： 組み合わせて使えるルールを作成し、具体例を示します。長い運用手順書はコピーせず、参照します。まずはシンプルに始め、エージェントが同じ間違いを繰り返すようになったらルールを追加します。レガシーな .cursorrules は、Project Rules または AGENTS.md に移行します。

参照： ルール。assets/templates/rules/_sections.md | references/templates-index.md | references/rules-and-commands.md。

---

コマンド

場所： プロジェクトの .cursor/commands/、ユーザーの ~/.cursor/commands/、Team ダッシュボード。形式： プレーンな Markdown .md。ファイル名がコマンド名になります。チャットで / を入力して実行します。パラメーター： コマンドの後に続くテキストがコンテキストとして渡されます（例：/fix-issue 123 → 「123」）。

利用可能なテンプレート（.cursor/commands/ にコピーしてください）：

コマンド	目的
/code-review	正確性、セキュリティ、品質、テストをレビューします。出力：重大／提案／あれば望ましい項目。
/pr	変更を要約し、PR のタイトルと説明を提案し、レビュー用チェックリストを提案します。
/run-tests-and-fix	テストを実行し、失敗を修正して、すべて成功するまで再実行します。変更内容を要約します。
/security-audit	セキュリティに焦点を当てたレビューを行います（インジェクション、認証、シークレット、依存関係）。
/setup-new-feature	計画（ファイル、モジュール、パターン）を提示し、実装手順を提案します。
/fix-issue	Issue 番号または説明に基づいて、バグや機能を修正します。
/update-deps	依存関係を更新し、テストを実行して、破壊的変更を報告します。
/docs	@ で指定したコードまたは現在の機能について、ドキュメントを生成または更新します。
/make-cursor-compatible	.cursor フォルダー、.cursorignore、AGENTS.md、ルール、コマンド、インデックスを追加して、コードベースを Cursor 対応にします。
/lint-and-fix	リンターを実行し、問題を自動修正して、残った問題を報告します。
/format	プロジェクトの標準に従ってコードをフォーマットします。
/check-coverage	テストカバレッジを確認し、不足箇所を特定して、改善策を提案します。
/analyze-deps	依存関係ツリーを分析し、未使用または重複した依存関係を特定して、最適化を提案します。
/generate-types	スキーマ、API、JSON から TypeScript／型を生成します。

参照： コマンド。assets/templates/commands/。

---

スキルとサブエージェント

スキル： .agents/skills/、.cursor/skills/、または ~/.cursor/skills/（互換性のため、.claude/skills/、.codex/skills/も対象）から読み込まれます。各スキルは SKILL.md を含むフォルダーです。scripts/、references/、assets/ は任意です。フロントマター：name、description（必須）、license、compatibility、metadata、disable-model-invocation（任意。true の場合、スキルは /skill-name で呼び出されたときのみ適用されます）。エージェントは、関連性がある場合、または /skill-name で呼び出された場合に適用します。対象となるルールとコマンドは、/migrate-to-skills（Cursor 2.4 以降）を使ってスキルに変換できます。サブエージェント： .cursor/agents/ または ~/.cursor/agents/ に配置します。Markdown と YAML の name、description、任意の model、readonly、background で構成されます。フォアグラウンドとバックグラウンドのほか、組み込みのサブエージェント（Explore、Bash、Browser）があります。

使い分け： サブエージェント — コンテキストの分離、並行作業、複数ステップにわたる専門的なタスク（テストや lint のみを実行する検証役など）。スキル — 単一目的で繰り返し行うタスク（変更履歴、フォーマット、ドメイン固有のワークフローなど）。

テンプレート： サブエージェントのテンプレートを assets/templates/agents/ から .cursor/agents/ にコピーします。利用可能なサブエージェント：

読み取り専用（レビュー／分析）：

• verifier.md — テストと lint を実行し、結果のみを報告します
• reviewer.md — 正確性、セキュリティ、品質、テストの観点からコードをレビューします
• security-auditor.md — セキュリティに重点を置いてレビューします
• linter.md — lint とコードスタイルをレビューします
• architect.md — アーキテクチャのパターンと設計をレビューします

編集可能（コードを変更できます）：

• documenter.md — ドキュメントを生成／更新します
• tester.md — テストを作成／更新します
• refactorer.md — 機能を維持しながらコードをリファクタリングします
• debugger.md — バグを調査して特定します
• performance-analyzer.md — パフォーマンスの問題とボトルネックを分析します
• accessibility-checker.md — a11y 準拠の観点からコードをレビューします
• migrator.md — コードの移行を体系的に処理します
• dependency-manager.md — 依存関係を確認、管理します
• formatter.md — 標準に従ってコードをフォーマットします
• type-generator.md — スキーマ／API から型を生成します

スキルのおすすめ： assets/recommended-skills.md と skills.sh のみを参照し、npx skills add <owner/repo> を提案します。

参照： スキル、サブエージェント。

---

無視ファイル

.cursorignore： プロジェクトのルートに置きます。構文は .gitignore と同じです。除外されたパスは、セマンティック検索、Tab、Agent、Inline Edit、@メンションで使用されません。ただし、ターミナル／MCP では使用されます。理由： セキュリティ（シークレット、キー、認証情報）とパフォーマンス（大規模なリポジトリ）のためです。.cursorindexingignore： インデックス作成のみを対象とします。@メンションで指定すれば、ファイルは引き続き使用できます。

必ず除外： .env、.env.*、*.key、*.pem、credentials.json、**/secrets/**。プロジェクト固有のパスも追加してください。! の使用には注意してください。親ディレクトリを除外すると、再包含にも制限がかかります。

参照： 無視ファイル。assets/templates/rules/ignore-cursorignore-secrets.md。

---

エージェントとセキュリティ

エージェント： ルール、ツール（検索、読み取り、編集、ターミナル、MCP）、およびメッセージで構成されます。要約（/summarize）とチェックポイントがあります。キューに追加（Enter）とすぐに送信（Ctrl+Enter）を使い分けられます。

セキュリティ： ファイルの編集が許可されています（保護された設定を除く）。VCS を使用してください。ターミナル： デフォルトでは承認が必要です。「Run everything」は避けてください。MCP： 接続と各ツール呼び出しを承認してください。ネットワーク： GitHub、リンクの取得、検索のみです。シークレットは .cursorignore に記載してください。

参照： エージェントの概要、エージェントのセキュリティ。references/agent-and-security.md。

---

エージェントのモード

モード	目的	ツール
Agent	実装、リファクタリング、複数ファイルにまたがる作業。	すべて（検索、読み取り、編集、ターミナル、MCP）。
Ask	学習、Q&A、調査。	検索と読み取りのみ。編集はできません。
Plan	調査 → 明確化 → 計画 → レビュー → 「Build」。	検索と読み取り。計画は .cursor/plans/ に保存されます。切り替えるには Shift+Tab を押します。
Debug	再現可能なバグへの対応。仮説 → 計測 → 再現 → 修正 → 検証。	すべて。

切り替え： チャットのモード選択メニューを使います。モードを切り替えるには Ctrl+. を押します。ベストプラクティス： Ask/Plan で計画し、Agent で実装します。Agent が誤ったものを作った場合は、元に戻す → 計画を見直す → 再実行します。

参照： Plan Mode、Debug Mode。assets/templates/rules/modes-plan-then-agent.md。references/modes-context-tools.md。

---

ワークフローと大規模なコードベース

TDD： テストを書く → 実行する（失敗することを確認）→ テストをコミットする → 実装する → 合格するまで実行する → 実装をコミットする。完了前にテストを実行： assets/templates/rules/workflows-run-tests-before-done.md。

Git スタイルのコマンド： .cursor/commands/ にある /pr、/fix-issue、/review、/update-deps、/docs。コードベースの理解： 「X はどのように動作しますか？」「Y を追加するにはどうすればよいですか？」と質問します。広い範囲から狭い範囲へと絞り込みます。図： Mermaid でアーキテクチャ図やデータフロー図を作成するよう依頼します。フック： 長時間実行するループには .cursor/hooks.json を使います。デザインからコードへ： モックアップを貼り付け、Browser でプレビューします。

大規模なコードベース： .cursor/rules に glob を使ってドメインルールを設定します。Ask で計画し、Agent で実装します。Tab は手早い編集に、Inline Edit（Ctrl+K）は単一ファイルの編集に、Chat/Agent は複数ファイルにまたがる作業に使います。@files、@folder、@Code を使い、対象範囲を絞ります。コンテキストが煩雑になったら、新しいチャットを開始します。

参照： Agent workflows、Large codebases。references/workflows-and-codebases.md。

---

セマンティック検索、@メンション、Tab

セマンティック検索： 意味に基づいて検索します。自然言語で質問できます。ワークスペースを開くとインデックス作成が始まり、完了率が約80%になると利用できます。grep とセマンティック検索の両方を使います（完全一致と概念検索）：assets/templates/rules/context-use-grep-and-semantic.md。

@Files と Folders： パスで参照します。サイドバーからドラッグすることもできます。@Code： 特定のスニペットを参照します（最も正確です）。@Docs： バンドル済みのドキュメントを使うか、新しいドキュメントを追加します（URL）。/summarize — コンテキストを圧縮します。ベストプラクティス： assets/templates/rules/context-use-at-mentions.md。

Tab： インライン補完。Tab で承認、Esc で却下、Ctrl+Right で一部を承認します。速度を優先するときに使い、大きな変更には Inline Edit または Chat を使います。

参照： Semantic search、@ Mentions、Tab。

---

Bugbot、MCP、ショートカット

Bugbot： PR をレビューします（バグ、セキュリティ、品質）。プロジェクトのルートにある .cursor/BUGBOT.md は常に含まれ、各ディレクトリにあるファイルは、そのパス配下のファイルをレビューするときに含まれます。ダッシュボードの Team ルールはすべてのリポジトリに適用されます。実行するには、cursor review または bugbot run とコメントします。リクエスト ID を確認するには verbose=true を指定します。Autofix は Cloud Agent を起動して報告された問題を修正します（ブランチにコミットするか、新しいブランチを作成します）。MCP： 外部ツールを使います。接続とツールの呼び出しを承認してください。コミュニティのルールと MCP については cursor.directory を参照してください。スキル： skills.sh のみです。

ショートカット： Ctrl+I Agent | Ctrl+K Inline Edit | Ctrl+. モードを切り替え | Enter キューに追加、Ctrl+Enter 送信 | Tab 補完を承認、Esc 却下。

参照： Bugbot、MCP。

---

プラグイン、フック、Cloud Agent、CLI、ワークツリー、ディープリンク

プラグイン： ルール、スキル、エージェント、コマンド、MCP サーバー、フックを配布可能なパッケージにまとめます。.cursor-plugin/plugin.json マニフェストを使用します。Cursor Marketplace またはチームのマーケットプレイス（Teams／Enterprise）からインストールできます。参照： プラグイン。

フック： .cursor/hooks.json（プロジェクト）または ~/.cursor/hooks.json（ユーザー）を使用します。エージェントのループの各段階（例：beforeShellExecution、afterFileEdit、sessionStart）を監視または制御します。コマンドベース（スクリプト）またはプロンプトベース（LLM）です。参照： フック。

Cloud Agent： エージェントはクラウドで実行されます。API、Linear、GitHub、Slack、デスクトップ（ドロップダウンの Cloud）、または cursor.com/agents（Web／PWA）からアクセスできます。MCP に対応し、利用上限を設定できます。「Apply」を使うと、ワークツリーの変更をブランチに反映できます。参照： Cloud Agent。

CLI： 対話型または非対話型で使用できる agent コマンドです。モードは Agent、Plan、Ask です。クラウドへの引き継ぎ：チャットで & を使うか、agent -c "prompt" を実行します。セッション：agent ls、agent resume。参照： CLI。

ワークツリー： 複数のエージェントを別々の Git ワークツリーで並列実行します。セットアップには .cursor/worktrees.json を使用します（例：setup-worktree、OS 固有の設定）。Best-of-N：同じプロンプトを複数のモデルで実行し、Apply で結果をマージします。参照： ワークツリー。

ディープリンク： cursor://anysphere.cursor-deeplink/ または https://cursor.com/link/ を使って、プロンプト、コマンド、ルールを共有します。最大 8,000 文字です。参照： ディープリンク。

---

.cursor の構成とセットアップのワークフロー

フォルダー： rules/、commands/、skills/、agents/。任意：hooks.json、worktrees.json。AGENTS.md はルールのシンプルな代替手段です。

.cursor フォルダーをセットアップする

ユーザーが .cursor フォルダーのセットアップ、初期化、または作成を依頼した場合：

1. 作成： .cursor/rules/、.cursor/commands/、.cursor/skills/、.cursor/agents/。
2. 任意の .cursorignore： 存在しない場合は、最小限の内容（例：node_modules/、.env、*.log、dist/）を追加します。.gitignore の構文を使い、技術スタックに応じて調整します。
3. 任意のテンプレート： このスキルからコピーするかどうかをユーザーに確認します。ユーザーが同意した場合：
   • コマンド： assets/templates/commands/ から .cursor/commands/ にコピーします（例：code-review.md、lint-and-fix.md、format.md など）。
   • エージェント： assets/templates/agents/ から .cursor/agents/ にコピーします（例：verifier.md、reviewer.md、linter.md、formatter.md など）。
   • ルール： 必要に応じて assets/templates/rules/ からコピーするか、スタータールールを 1 つ追加するか、AGENTS.md を追加します。
4. 確認： 作成したものと使い方を一覧で示します（例：「チャットで /code-review を使う」、「.cursor/rules/ にルールを追加する」）。

参照： assets/templates/rules/context-setup-cursor-folder.md。references/templates-index.md。

---

トラブルシューティング

ルールが適用されない場合： タイプ（Always／Intelligent／Globs／Manual）、description（キーワード）、globs（パスが一致するか）を確認します。リクエスト ID： 報告時に「Get request ID」または cursor review verbose=true を使用します。参照： よくある問題、トラブルシューティングガイド。references/modes-context-tools.md。

---

関連項目

• テンプレートの索引： references/templates-index.md
• テンプレート： assets/templates/commands/（14 個のコマンドテンプレート）、assets/templates/agents/（15 個のサブエージェントテンプレート）、assets/templates/rules/_sections.md、assets/recommended-skills.md
• リファレンス： rules-and-commands | agent-and-security | workflows-and-codebases | modes-context-tools | quick-reference
• 公式情報： Cursor のドキュメント | cursor.directory（ルールと MCP） | skills.sh（スキル）
• 安全なスキルの作成： プロンプトインジェクションのパターン、ハードコードされたシークレット、安全でないダウンロード／実行の例は含めないでください。references/agent-and-security.mdを参照してください。