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行を超える場合、@Files は @Codebase より正確です。代償はトークン消費が高く、完全なファイル内容がコンテキストに入るためです。

@Code（5-10%）：正確なコードスニペットを参照。選択したコード部分だけを送り込み、ファイル全体は含みません。適用シーン：部分的なコード最適化、小さなロジックのデバッグ、ファイルレベルのコンテキスト汚染回避。トークン消費は最低です。

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

@Repo（特定シーン）：リポジトリコンテキスト。適用シーン：マルチリポジトリプロジェクト、バージョン履歴分析、リポジトリ間の問題特定。トークン消費は中程度。

これら6つの記号は排他的ではなく、同じ会話で組み合わせて使用できます。例えば、まず @Codebase で全体情報を取得し、次に @Files で重要ファイルを特定し、最後に @Docs で公式ドキュメントの説明を補完するなど。重要なのは：問題タイプに応じて選択し、無闇に積み重ねないことです。

二、判断ツリー：問題タイプ → @記号の選択

記号選択の核心ロジックは一つの問いだけ：コードがどこにあるか知っているか？

知らないなら、@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 リポジトリに依存している、あるいはあるコミットの影響範囲を分析する必要がある場合。

@Repo を使います。バージョン履歴やリポジトリ間の依存関係を含むリポジトリコンテキストを提供します。

---

簡単に言えば、判断ツリーの核心は一言：場所が不明なら @Codebase、場所が明確なら @Files/@Code、ドキュメントが必要なら @Docs。残りの2つの記号（@Folders、@Repo）は特定シーンでの補助です。

三、@Codebase vs @Files：核心的な違いと実践例

この2つの記号は最も混同しやすいですが、違いは一つだけ：AI に探させるか、自分で指定するか。

@Codebase の価値は「検索」ではなく「発見」にあります。あなたが質問すると、AI はコードベース全体でセマンティックマッチングを行い、最も関連性の高いファイル、関数、型定義を返します。重要なのは：あなたが思いもよらないファイルを返す可能性があります。例えば「API の戻り値フォーマットをどう変更するか」と聞くと、AI は以下を返すかもしれません：

• API handler ファイル（予想通り）
• 型定義ファイル（知っているかもしれない）
• どこかの utils.ts に手軽に定義された型エイリアス（見落としているかもしれない）
• あるテストファイルのモックデータ（全く気づいていないかもしれない）

これが @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、この API を呼び出すフロントエンドコンポーネント。この過程でファイルを見落としやすい。

@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.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 ドキュメント、GitHub Wiki）がある場合、URL を追加すれば、AI はチームの規範を参照してコードを生成できます。

---

実践例：React 19 の新しい hooks

React 19 の useOptimistic hook を使いたいが、最新の使い方が不確定だとします。

Chat で直接以下のように書けます：

@Docs React
React 19 の useOptimistic hook を使って、optimistic update 機能を実装してください。
シーン：いいねボタン、クリック後すぐに +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 を参照する可能性があります。トレーニングデータの旧い使い方の「記憶」が深い場合、AI は新旧の 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 の理解がズレていき、最終的に生成されるコードが当初の目的から完全に外れてしまうのです。

核心原則：会話は短く、機能は分ける

一つの機能が完了したら、会話をリスタートする。「API リファクタリング」「バグ修正」「新機能追加」を同じ会話に混ぜないでください。

なぜ？各機能に必要なコンテキストが異なるからです。API リファクタリングの場合、AI が必要なのは型定義、API handler、フロントエンド呼び出しコード；バグ修正の場合、AI が必要なのはエラーログ、関連コードスニペット、テストケース。混ぜるとコンテキストはますます雑になり、AI の理解はますます曖昧になります。

シンプルな操作：Chat パネル右上の “Clear Chat” をクリックするか、ショートカットキーで新しい会話を開始します。

---

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

2つのシーンで異なる方法を使います：

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

複雑なタスク（モジュールリファクタリング、新コンポーネント生成）：Chat + @-mentions を使う。まず @Codebase で全体情報を取得し、次に @Files で重要ファイルを特定し、最後にタスクの説明を明確に書く。こうするとコンテキストがより完全で、AI の理解がより正確になる。

---

インデックス最適化：.cursorignore で干渉ファイルを除外

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

例えば：

• node_modules/（依存ライブラリ、AI は不要）
• dist/、build/（コンパイル済み成果物）
• .env、.env.local（機密設定）
• 大型静的リソース（画像、動画）

.cursorignore ファイルでこれらのディレクトリを除外します。.gitignore とは別に管理し、原則は：**AI がこのファイルを見る必要があるか？**です。

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

こうすると @Codebase のインデックス範囲がより正確になり、クエリ速度が上がり（5-10秒から2-3秒に）、返される結果もより関連性が高くなります。

---

README.md を定期的に更新

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

なぜ？README.md は @Codebase インデックスの重要なファイルの一つだからです。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 をどう修正するか」と聞くと、AI が返すのは utils/user.ts で、予想していた services/UserService.ts ではない。

原因：セマンティックマッチングに曖昧さがあり、AI が関連性を誤判断した可能性。

解決策：

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

@Codebase の強みは自動発見ですが、代償として誤差があります。精密なタスクでは @Files を使ってください。

---

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

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

原因：トレーニングデータの「記憶」が深く、@Docs の内容を上書きした。

解決策：プロンプトで強調する：

@Docs React
ドキュメントの最新の使用方法を使ってください（React 19）。
トレーニングデータの旧 API は使わないでください。

この文を追加すると、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（インライン編集）を使い、@-mentions をトリガーしない
2. 精密なタスクは @Files/@Code を使い、@Codebase が「関連あるが無関係」なファイルを大量に返すのを避ける
3. .cursorignore で大きなファイル（node_modules、dist）を除外

トークン消費の核心原則：正確に参照し、全ライブラリ検索を避ける。

まとめ

Cursor の @記号システムの核心ロジックは一言：場所が不明なら @Codebase、場所が明確なら @Files/@Code、ドキュメントが必要なら @Docs。

開発時間の80%は @Codebase を使うべきです。これは誇張ではなく、@Codebase の真の価値が「発見」にあるからです——AI はあなたが見落とす可能性がある関連コードを見つけます。例えば utils.ts に手軽に定義された型エイリアスや、あるテストファイルのモックデータなど。

しかし @Codebase が万能なわけではありません。ファイルが600行を超える、または場所が明確な場合は、@Files の方が正確です。小さなコード片をデバッグするなら、@Code が最もトークンを節約します。新しいライブラリや最新 API の場合は、@Docs を追加して正確性を確保します。

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

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

この記号システムを使いこなしてこそ、Cursor は本当のプログラミングパートナーになり、単に大量のコンテンツを返すだけの検索ツールでは終わりません。