Cursor の @Codebase、@Docs、@Files — どれを使う？実践シーン別の判断ガイド

Cursor の @ シンボルは一見シンプルです。@Codebase、@Files、@Docs — クリックするだけで AI にコンテキストを渡せます。でも実際に使うと、多くの人が同じところでつまずきます。何を探したいかは分かっているのに、どのシンボルを使えばいいか分からない。

選び方を間違えると、AI は無関係な内容を大量に詰め込むか、本当に必要なファイルを見つけられません。会話履歴には同じクエリが繰り返され、トークンだけ消費して、問題ははっきり解決しない。

本記事では機能定義は扱いません。具体的なシーンで、どの @ シンボルを使うべきか素早く判断する方法だけを解説します。読み終える頃には、毎回迷わない判断の軸が手に入ります。

一、@ シンボルシステムの要点比較：6 機能を一覧で把握

まず重要な結論から。BetterLink Blog の実践統計では、開発時間の 80% は @Codebase を使うべきです。手動でファイルを選ぶ必要はありません。数字は大きく聞こえますが、理由はシンプル — @Codebase の強みは検索ではなく、見落としがちな関連コードを AI に発見させることです。

以下、使用頻度の高い順に 6 つのシンボルを並べます。

@Codebase（60〜80%）：コードベース全体のセマンティック検索。質問を投げると、AI がコードベースから最も関連するファイル、関数、型定義を自動で探します。ファイルの場所を知る必要も、手動選択も不要。プロジェクトアーキテクチャの理解、コードリファクタリング、ファイル横断の問題特定に向いています。コードベース全体をインデックスするため、トークン消費はやや高めです。

@Docs（10〜15%）：外部ドキュメントの参照。React、Vue、Astro など組み込みのフレームワークドキュメントを呼び出せます。URL でカスタムドキュメント源も追加可能。新リリースのライブラリ利用、最新 API 仕様の確認、チームナレッジベースの統合に使います。

@Files（5〜10%）：特定ファイルの全文を精密に参照。ファイル名が明確、または vite.config.ts など設定ファイルを変更するときに使います。600 行を超えるファイルなら @Codebase より精度が高い。代わりにファイル全文がコンテキストに入るため、トークン消費も高くなります。

@Code（5〜10%）：コード片を精密に参照。選択した部分だけを渡し、ファイル全体は含みません。局所的な最適化、小さなロジックのデバッグ、ファイルレベルのコンテキスト汚染を避けたいときに最適。トークン消費は最小。

@Folders（5% 以下）：ディレクトリ全体の構造と内容概要を参照。モジュールリファクタリング、新コンポーネント生成、アーキテクチャの一貫性チェックに向いています。複数ファイルにまたがるため、トークン消費は高めです。

@Repo（特定シーン）：Repository context。マルチリポジトリプロジェクト、バージョン履歴の分析、リポジトリ横断の問題特定に使います。トークン消費は中程度。

この 6 つは排他的ではありません。同じ会話で組み合わせ可能です。例えば @Codebase で全体像を取得し、@Files で重要ファイルを絞り込み、@Docs で公式ドキュメントを補足する。問題の種類に応じて選ぶこと。盲目的に積み重ねないこと — これがポイントです。

二、判断ツリー：問題の種類 → @ シンボル選択

シンボル選択の鍵は、たった 1 つの問いです。コードの場所が分かりますか？

分からなければ @Codebase。分かれば @Files または @Code。ドキュメントが足りなければ @Docs を追加。

具体的に見ていきましょう。

シーン 1：ファイル位置が不明

Next.js プロジェクトをリファクタリング中、ある API のレスポンス形式を変えたい — でも型定義がどのファイルにあるか不明。types/ かもしれないし、components/ かもしれない。ある utils.ts にさりげなく定義されているかもしれない。

このときは @Codebase。Chat にこう書きます：「ApiResponse 型の定義を見つけて、レスポンス形式を変更して」。AI がコードベース全体をスキャンし、この型を参照するすべての箇所 — 見落としていた utils.ts も含めて — を見つけてくれます。

シーン 2：ファイル名が明確

vite.config.ts のプロキシ設定を変更したい、または src/utils/auth.ts の関数をリファクタリングしたい。パスも内容も把握している（600 行超）。

@Files を使います。@Files をクリックして対象ファイルを選択すれば、AI は全文を取得。「関連はあるが本質的に無関係」なファイルが返ってくる @Codebase より精密です。

シーン 3：最新ドキュメントが必要

先週リリースされたばかりのライブラリを使っている、またはフレームワークの最新 API 用法を確認したい（学習データがカバーしていない可能性あり）。

@Docs を使います。@Docs を入力し、組み込みドキュメントを選ぶか URL で新しいソースを追加。プロンプトで「ドキュメントの最新の用法を使う」と強調することが重要 — そうしないと AI は記憶内の旧バージョン API を使うことがあります。

シーン 4：特定のコード片だけに注目

関数のロジックをデバッグ中。数行だけ最適化したい。ファイル全体をコンテキストに入れたくない。

@Code を使います。コードを選択して Cmd+K でインライン編集、または Chat で @Code を参照。トークン消費最小、コンテキストも最もクリーン。

シーン 5：モジュールリファクタリングまたは新コンポーネント生成

components/ ディレクトリ全体をリファクタリングする、または新しい features/ モジュールを生成してアーキテクチャの一貫性を保ちたい。

@Folders を使います。ディレクトリ構造の概要と主要ファイルの内容を取得し、AI がモジュール全体の構成を理解して、既存スタイルに合ったコードを生成できます。

シーン 6：マルチリポジトリまたはバージョン履歴分析

プロジェクトが複数の Git リポジトリに依存している、または特定の commit の影響範囲を分析したい。

@Repo を使います。Repository context — バージョン履歴、リポジトリ横断の依存関係 — を提供します。

---

シンプルに言えば、判断ツリーの要点は 1 文です。位置が不明なら @Codebase、位置が明確なら @Files/@Code、ドキュメント不足なら @Docs。残り 2 つ（@Folders、@Repo）は特定シーンの補助です。

三、@Codebase vs @Files：主な違いと実践ケース

この 2 つは最も混同されやすい。違いは 1 点だけ — AI に探させるか、自分で指し示すか。

@Codebase の価値は「検索」ではなく「発見」。質問を投げると、AI がコードベース全体でセマンティックマッチングを行い、最も関連するファイル、関数、型定義を返します。重要なのは、想定外のファイルも返ってくること。例えば「API のレスポンス形式をどう変更するか」と聞くと、AI は次を返すかもしれません：

• API handler ファイル（想定どおり）
• 型定義ファイル（知っているかも）
• ある utils.ts にさりげなく定義した型エイリアス（見落としていたかも）
• テストファイル内の mock データ（全く気づいていなかったかも）

これが @Codebase の最大の強み — AI が見落としがちな関連コードを発見してくれる。

@Files の価値は「精密」。ファイルを明示指定すれば、AI は全文を取得し、曖昧さはありません。代償として、ファイルの場所を知っている必要があり、トークン消費も高くなります（全文がコンテキストに入るため）。

---

実践ケース 1：API レスポンス形式の変更（@Codebase が適切）

シーン：Next.js API のレスポンス形式は次のとおり：

// src/app/api/users/route.ts
export async function GET(request: Request) {
  const users = await db.query('SELECT * FROM users');
  return Response.json({ data: users, total: users.length });
}

{ users, count } に変更したいが、型定義の場所が不明。

@Files なら、route.ts、想定される types.ts、フロントエンドの呼び出しコンポーネント — 関連ファイルを手動で探す必要があり、漏れやすい。

@Codebase なら、Chat にこう書くだけ：

@Codebase
ユーザー API のレスポンス形式を { data, total } から { users, count } に変更して。
関連する型定義とフロントエンドの呼び出しコードもすべて同期して。

AI の返答例：

以下の関連ファイルを見つけました：
1. src/app/api/users/route.ts - API handler
2. src/types/api.ts - ApiResponse 型定義
3. src/components/UserList.tsx - フロントエンドコンポーネント（この API を呼び出し）
4. src/utils/mock.ts - テスト mock データ（同じ形式を使用）

mock.ts も同じ形式を使っている — 以前は全く気づいていなかったファイルです。

実践ケース 2：vite.config.ts の設定最適化（@Files が適切）

シーン：Vite のプロキシ設定を変更したい。パスは明確：vite.config.ts。

// vite.config.ts
export default defineConfig({
  server: {
    proxy: {
      '/api': 'http://localhost:3000'
    }
  }
})

マルチ環境（開発、テスト、本番）対応のプロキシに変更したい。

この場合 @Files が適切。理由：

1. ファイル位置が明確
2. 内容が短い（通常 50〜200 行）
3. ファイル横断の検索が不要

Chat にこう書きます：

@Files vite.config.ts
プロキシ設定をマルチ環境（開発、テスト、本番）対応に変更して。
環境設定は .env.development、.env.test、.env.production から読み込む。

AI は vite.config.ts の全文を取得し、直接修正案を提示：

// vite.config.ts
export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), '');
  return {
    server: {
      proxy: {
        '/api': env.API_URL || 'http://localhost:3000'
      }
    }
  }
})

---

まとめ：位置が不明、または隠れた関連を発見したいなら @Codebase。位置が明確、または長いファイルの全文理解が必要なら @Files。

四、@Docs：新しいライブラリの利用とドキュメント統合

@Docs が解決する問題 — AI の学習データがドキュメント更新に追いつかない。

先週リリースされたライブラリ、または API 用法が大きく変わったフレームワーク（React 19 の新 hooks、Next.js 15 の Turbopack）。AI の学習データは数ヶ月前のままかもしれず、旧バージョンの API でコードを生成します。

@Docs の仕組み：指定したドキュメントをリアルタイムで検索・解析し、コンテキストに渡します。AI はコード生成時に、ドキュメントの最新仕様を優先参照します。

---

使い方

操作はシンプル：

1. Chat に @Docs と入力
2. 組み込みフレームワークドキュメント（React、Vue、Astro、Tailwind、Next.js など）を選択
3. または URL を貼り付けてカスタムドキュメント源を追加

カスタムソースは実用的です。チーム内部のナレッジベース（Feishu（Lark）ドキュメント、GitHub Wiki など）の URL を追加すれば、AI がチーム規約を参照してコードを生成できます。

---

実践ケース：React 19 の新 hooks

React 19 の useOptimistic hook を使いたいが、最新の用法が不明。

Chat にこう書きます：

@Docs React
optimistic update 機能を実装して。React 19 の useOptimistic hook を使う。
シーン：いいねボタン。クリック後すぐ +1 を表示し、サーバー確認を待つ。

AI は React 公式ドキュメントを検索し、最新の useOptimistic API 説明を取得してから、仕様に沿ったコードを生成：

import { useOptimistic } from 'react';

function LikeButton({ initialLikes, onSubmit }) {
  const [optimisticLikes, addOptimisticLike] = useOptimistic(
    initialLikes,
    (state, newLike) => state + newLike
  );

  async function handleClick() {
    addOptimisticLike(1); // すぐ +1 を表示
    await onSubmit();     // サーバー確認を待つ
  }

  return <button onClick={handleClick}>{optimisticLikes} Likes</button>;
}

---

注意点：学習データが @Docs を上書きする可能性

落とし穴があります。AI は学習データと @Docs の両方を参照する場合があり、旧用法の記憶が強いと、新旧 API が混ざった奇妙なコードを生成することがあります。

対処法：プロンプトで「ドキュメントの最新の用法を使う」と強調する。

例：

@Docs React
ドキュメントの最新の用法（React 19）を使って。学習データの旧 API は使わないで。

こうすれば AI は @Docs を優先し、旧バージョンの影響を抑えられます。

---

いつ @Docs を使うべき？

判断はシンプル。ライブラリ/フレームワークのリリースが AI の学習データ締切日より後、または API に重大な更新があるなら @Docs。

例：

• React 19（2024 年末リリース、重大 API 更新）
• Next.js 15（2024 年末、Turbopack デフォルト有効化）
• Supabase 最新機能（リアルタイム更新のドキュメント）
• チーム内部規約（AI の学習データには存在しない）

ライブラリが安定している場合（React 18、Vue 3、Tailwind 3）、学習データのカバーが十分なら @Docs の必要性は低い。

五、コンテキスト管理のベストプラクティス

@ シンボルを使いこなすのは第一歩。第二歩はコンテキスト管理。多くの人が経験する落とし穴 — 会話履歴が長くなるほど AI の理解がずれ、最終的に意図とかけ離れたコードが生成される。

基本原則：会話は短く、機能は分ける

機能を 1 つ完了したら、会話をリスタート。「API リファクタリング」「バグ修正」「新機能追加」を同じ会話に混ぜない。

なぜか。各機能に必要なコンテキストが異なるから。API リファクタリングには型定義、API handler、フロントエンド呼び出しが必要。バグ修正にはエラーログ、関連コード片、テストケースが必要。混ぜるほどコンテキストは雑になり、AI の理解はぼやけていきます。

操作はシンプル：Chat パネル右上の「Clear Chat」をクリック、またはショートカットで新しい会話を開始。

---

小さな編集 vs 複雑なタスク

2 つのシーンでアプローチを分けます。

小さな編集（1 行変更、パラメータ調整）：インライン編集（Cmd+K）。対象コードを選択して Cmd+K、修正指示を入力。現在のファイルと選択内容が自動的にコンテキストになり、追加設定は不要。

複雑なタスク（モジュールリファクタリング、新コンポーネント生成）：Chat + @-mentions。@Codebase で全体像を取得し、@Files で重要ファイルを絞り込み、タスク説明を明確に書く。コンテキストがより完全になり、AI の理解も正確になります。

---

インデックス最適化：.cursorignore でノイズとなるファイルを除外

@Codebase のインデックスはコードベース全体をカバーしますが、すべてのファイルを AI に見せる必要はありません。

例：

• node_modules/（依存ライブラリ — AI には不要）
• dist/、build/（ビルド成果物）
• .env、.env.local（機密設定）
• 大きな静的リソース（画像、動画）

.cursorignore でこれらを除外。.gitignore とは別管理。原則は 1 つ：AI にこのファイルを見せる必要があるか？

# .cursorignore
node_modules/
dist/
build/
.env
.env.local
*.log
*.png
*.jpg

こうすれば @Codebase のインデックス範囲が精密になり、クエリ速度も向上（5〜10 秒 → 2〜3 秒）、返却結果もより関連性が高くなります。

---

README.md を定期的に更新

見落とされがちな習慣 — README.md にプロジェクトの状態と構造を記録する。

なぜか。README.md は @Codebase インデックスの重要ファイルの 1 つ。AI がプロジェクトアーキテクチャを理解するとき、README を優先参照します。README に以下が明確に書いてあれば：

• プロジェクト構造（ディレクトリ説明）
• 主要モジュール（各ファイルの役割）
• 最近の変更（新機能、リファクタリング計画）

AI は複雑なタスク処理時に全体像をより早く把握し、重複クエリを減らせます。

---

Pro ユーザーの優位性：より広いインデックス範囲

Cursor Pro ユーザーはコードベース全体のセマンティックインデックスが可能。Free ユーザーにはインデックス範囲の制限があります。500 ファイルを超えるプロジェクトなら、Pro 版の @Codebase 効果は明らかに良い。

ただし Free ユーザーが使えないわけではありません。大切なのは変わらない — コンテキストを管理し、正しいシンボルを使い、ノイズとなるファイルを除外する。Pro はあれば便利なオプションで、必須ではありません。

六、よくある問題と解決策 FAQ

問題 1：@Codebase の結果がコードベースと一致しない

症状：ファイルを変更した直後なのに @Codebase が旧内容を返す。または存在するファイルが @Codebase で見つからない。

原因：インデックスが同期更新されていない。

対処法：

1. Cursor Settings →「Reindex Codebase」（強制再インデックス）
2. またはプロジェクトフォルダを削除して再追加（より徹底的）

1〜2 分待てばインデックス完了後、問題は解消されます。

---

問題 2：@Codebase が誤ったマッチを返す

症状：「UserService をどう変更するか」と聞いたのに、想定の services/UserService.ts ではなく utils/user.ts が返る。

原因：セマンティックマッチングの曖昧さ。AI が関連性を誤判断した。

対処法：

1. @Files で正しいファイルを明示指定
2. またはプロンプトでファイルパスを指定：「src/services/UserService.ts を修正」

@Codebase の強みは自動発見ですが、誤差のトレードオフもあります。精密タスクは @Files が確実。

---

問題 3：@Docs を追加したのに AI が旧バージョン API を使う

症状：@Docs React を追加したのに、生成コードは React 18 の書き方。

原因：学習データの記憶が強すぎて @Docs の内容を上書き。

対処法：プロンプトで強調：

@Docs React
ドキュメントの最新の用法（React 19）を使って。学習データの旧 API は使わないで。

この 1 文で AI は @Docs を優先します。

---

問題 4：@Codebase のクエリが遅い（5〜10 秒）

症状：@Codebase を使うたびに長時間待つ。

原因：インデックス範囲が広すぎる（node_modules、dist などを含む）。

対処法：.cursorignore の設定を確認し、不要なファイルを除外：

# .cursorignore
node_modules/
dist/
build/
*.log
*.png

除外後、インデックス範囲が縮小し、クエリ速度は 2〜3 秒に短縮されます。

---

問題 5：会話履歴が長く AI の理解がずれる

症状：会話で 3〜4 機能を議論した後、AI の返答が意図からどんどん離れる。

原因：コンテキスト汚染 — 各機能のコンテキストが混在。

対処法：会話をリスタート。Chat パネル右上の Clear Chat で新しい会話を開始。各機能は個別に扱い、コンテキストをクリーンに保つ。

---

問題 6：トークン消費が高すぎ予算超過

症状：会話のたびに大量のトークンを消費し、Pro 枠がすぐに尽きる。

原因：シンボル選択のミス。無関係な内容を大量に詰め込んでいる。

対処法：

1. 小さな編集は Cmd+K（インライン編集）— @-mention をトリガーしない
2. 精密タスクは @Files/@Code — @Codebase が返す「関連だが無関係」なファイルを避ける
3. .cursorignore で大きなファイル（node_modules、dist）を除外

トークン消費の基本原則：精密に参照し、コードベース全体の検索を避ける。

まとめ

Cursor の @ シンボルシステム、要点は 1 文です。位置が不明なら @Codebase、位置が明確なら @Files/@Code、ドキュメント不足なら @Docs。

開発時間の 80% は @Codebase を使うべき — 大げさではありません。@Codebase の真の価値は「発見」にあります。utils.ts にさりげなく定義した型エイリアス、テストファイル内の mock データ — 見落としていた関連コードを AI が見つけてくれます。

ただし @Codebase は万能ではありません。600 行を超えるファイル、または位置が明確なら @Files の方が精密。小さなコード片のデバッグなら @Code が最もトークン節約。新しいライブラリや最新 API なら @Docs で仕様の正確さを確保。

コンテキスト管理も同じくらい重要。会話は短く、機能は分ける。タスク完了後に会話をリスタートし、履歴を長くしすぎない。.cursorignore でノイズとなるファイルを除外し、README.md を定期更新すれば、AI の理解はより正確になります。

次回開発時、まず自分に問いかけてください：ファイルの位置が分かっているか、それとも AI に関連コードを探してほしいか？ 不明なら @Codebase から — AI が隠れた関連を発見してくれます。明確なら精密に参照し、コンテキスト汚染を避けましょう。

この @ シンボルを使いこなせば、Cursor は大量のコンテンツを返すだけの検索ツールではなく、本当のプログラミングパートナーになってくれます。