【実務・中級編】Cursorの「Context Management」完全攻略：@Filesと@Foldersを使い分ける精度の高いAI回答術 – 軽量・高機能テキストエディタ生産性向上バイブル

はじめに：なぜあなたのCursorのAIは「的外れなコード」を吐き出すのか

テックリードとしてチームのコードレビューや開発生産性の計測を行っていると、AIコーディングアシスタントの導入効果に大きな個人差があることに気づく。

「Cursorはすごい」と聞きかじり、適当にチャットウィンドウを開いて「このバグを直して」と指示を投げ、生成された怪しいコードの修正に結局何十分も費やしている――。もしチームメンバーにそんな姿が見受けられるなら、それはAIの能力不足ではない。「コンテキストの解像度」をエンジニア側がコントロールできていないことが原因だ。

AIモデル（Claude 3.5 SonnetやGPT-4oなど）は優秀だが、テレパシーは使えない。プロジェクト全体の構造、依存関係、そして「今、どのスコープの変更を意図しているのか」を正確に与えなければ、確率的にそれらしいだけのコード（ハルシネーション）を吐き出す。

Cursorの真髄は、その高度なエディタ機能ではなく、コードベースへのアクセスを直感的に制御する Context Management（コンテキスト管理） にある。特に `@Files` と `@Folders` という2つのアノテーションをいかに使い分けるかが、AIの回答精度、ひいては開発スピードを劇的に左右する。

本記事では、AIの内部トークン消費の仕組みから逆算し、実務で即座に使えるコンテキスト制御の極意を、設定ファイルやショートカットと共に徹底解説する。

—

1. コンテキストの正体：なぜ「丸投げ」は失敗するのか

トークンエコノミーとアテンション機構の限界

Cursorのチャット機能（Cmd/Ctrl + L や Cmd/Ctrl + I）で `@` を入力すると、様々なコンテキストソースを指定できる。ここでエンジニアが理解しておくべきなのは、LLMのアテンション機構（Attention Mechanism）の挙動だ。

プロジェクト全体のファイルを無造作にコンテキストとして渡すと、LLM側で以下のような弊害が起きる：
1. ノイズの増大: 関連性の低いコードがアテンションを分散させ、本当に重要なドメインロジックの重みが相対的に低下する。
2. コンテキストウィンドウの圧迫: 長大なファイルや不要なログ・ビルド成果物が含まれると、モデルが古い指示を「忘れる」（ロスト・イン・ザ・ミドル問題）。

つまり、「必要な情報だけを、適切な解像度でAIに切り取って渡すこと」こそが、テックリードが身につけるべき現代のプログラミング作法なのだ。

—

2. `@Files` と `@Folders` の実践的な使い分け戦略

`@Files`：外科手術的なピンポイント参照

特定の関数定義、インターフェース、単一のモジュールに修正を加える場合は `@Files` を使う。

得意なユースケース:
既存のユーティリティ関数を特定の仕様に合わせて改修する
ある特定のモデルスキーマ（例: `user.go` や `schema.prisma`）に基づいたバリデーションロジックを書かせる
アーキテクトの知見:

ファイル単位で指定すると、AIはそのファイルの「完全なAST（抽象構文木）に近い解像度」でコードを把握する。ただし、他のファイルとの依存関係が不明な場合があるため、関連する型定義などが別ファイルにある場合は、複数の `@Files` を並べるか、後述の `@Folders` を併用する。

`@Folders`：アーキテクチャ全体を俯瞰させる戦略的参照

新機能の追加、レイヤーをまたぐリファクタリング、あるいは新規モジュールの設計など、ディレクトリ構造全体のルールをAIに理解させるには `@Folders` を使う。

得意なユースケース:
クリーンアーキテクチャの原則に則った新しいユースケース層（UseCase）の実装
既存のテストパターンに準拠したモックテストの大量生成
アーキテクトの知見:

フォルダを指定すると、その配下のファイルツリーと主要なファイルがコンテキストに含まれる。ここで注意すべきは「不要なディレクトリの除外」だ。`node_modules` や `dist`、巨大なアセットフォルダが含まれていると、AIの注意力が致命的に散漫になる。

—

3. 誤情報を防ぐスコープ指定のベストプラクティス

ハルシネーション（幻覚）や的外れな提案を防ぐためには、以下の3ステップでプロンプトのコンテキストを構築するレイヤリング手法が極めて有効である。

[プロンプト構造の黄金比]
1. 役割の定義 -> “あなたはシニアバックエンドエンジニアです”
2. スコープの限定 -> “@Folders(src/domains/auth) と @Files(src/types/user.ts)”
3. 制約とゴール -> “既存のJWT認証フローを破壊せず、リフレッシュトークンのローテーションを追加してください”

この構造を守ることで、AIは「どこを見て、何を変えてはいけないか」を正確に認識し、生産性の高いコードを生成する。

—

4. 開発スピードを極限まで引き上げるキーボードショートカット

マウス操作は思考のコンテキストスイッチを発生させる。Cursorの高速な操作を支えるショートカットを体に叩き込め。

—

5. 絶対に入れるべき神プラグイン（Cursor連携拡張機能）

CursorはVS Codeベースであるため、既存の豊富な拡張機能エコシステムをそのまま利用できる。その上で、AIの文脈理解をさらに助けるために必須のプラグインを厳選する。

1. Error Lens

理由: AIが生成したコードや自身が書いたコードの静的解析エラー（TypeScriptの型エラーやLinterの警告）をインラインで即座に可視化する。AIとの対話ループにおいて、エラーの早期発見は効率を倍増させる。

2. GitLens — Git supercharged

理由: 「このコードは誰が、なぜ書いたのか」のコンテキストを瞬時に引き出せる。AIに「直近のコミット履歴を踏まえてリファクタリングして」と指示する際の前提情報を人間側が正確に把握するために不可欠。

—

6. チーム開発で役立つ設定の共有化ルール

個人がバラバラの設定でCursorを使っていては、チーム全体のコード品質やAIの出力傾向が統制できない。プロジェクトルートに `.cursorrules` ファイルを配置し、チーム全体でAIの振る舞いをコード化して共有すべきである。

推奨 `.cursorrules` 構成例（JSON/YAML形式）

プロジェクトのルートディレクトリに `.cursorrules`（または `.cursor/rules/` 配下）として配置し、リポジトリにコミットすることで、チーム全員のCursorが同じポリシーで動作するようになる。

{
“version”: “1.0.0”,
“project_context”: {
“framework”: “Next.js 14 (App Router)”,
“language”: “TypeScript (Strict Mode)”,
“styling”: “Tailwind CSS + shadcn/ui”,
“state_management”: “Zustand”
},
“coding_standards”: {
“indentation”: “2 spaces”,
“naming_convention”: {
“components”: “PascalCase”,
“functions”: “camelCase”,
“constants”: “UPPER_SNAKE_CASE”
},
“rules”: [
“any型やunknown型の安易な使用を禁止し、厳密な型定義を行うこと。”,
“サーバーコンポーネントとクライアントコンポーネント（’use client’）の境界を明確に意識すること。”,
“エラーハンドリングは必ずResult型（またはtry-catch）を用いて明示的に行うこと。”
]
},
“ai_behavior”: {
“language”: “Japanese”,
“verbosity”: “concise”, //冗長な説明を避け、コードと要点のみを出力させる
“prohibit”: [
“破壊的なマイグレーションスクリプトの自動実行提案”,
“非推奨となったNext.jsのAPI（旧pages routerの書き方など）の利用”
]
}
}

この設定がもたらす効果:
AIはチャットやComposerを起動した瞬間から、この `.cursorrules` を暗黙の前提として読み込む。結果として、メンバーが個別に「TypeScriptで書いて」「Tailwindを使って」とプロンプトで指示する手間が一切不要になり、チーム全体で統一された美しいコードベースが維持される。

—

おわりに：道具に振り回されるな、道具を支配しろ

AIエディタは、魔法の杖ではない。それは「極めて高速だが、文脈に忠実すぎる超優秀なジュニアエンジニア」のようなものだ。

あなたが `@Files` で適切なファイルを与え、`@Folders` でアーキテクチャの境界を示し、`.cursorrules` でチームの規律を教え込むことで初めて、Cursorはその真価を発揮する。

今日からあなたのプロジェクトに適切なコンテキスト管理を導入し、AIを真の「開発パートナー」へと昇華させてほしい。チームの生産性は、あなたの指示の解像度にかかっている。