Cursorで既存プロジェクトを読み込ませる方法

Cursorで既存projectを扱うときは、folderを開いてすぐ実装を頼むより、最初に「どこから動き、どう検証し、どのfileが重要か」を把握します。CursorのAgentはcodebaseを検索し、fileを読み、terminal commandを実行できます。公式Quickstartも既存projectを開き、Agentにcodebaseの説明を求め、小さい変更を作り、diffと既存checkを確認する流れを案内しています。最初のtaskを調査に使えば、別のframeworkや誤った起動方法を前提に変更するリスクを減らせます。

既存projectを安全に開く

CursorのFile > Open Folderから、実際に作業するrepositoryのrootを選びます。monorepoの場合は、作業対象のpackageやworkspaceだけでなく、rootのREADME、workspace設定、共通ruleが見える場所を選びます。誤った階層を開くと、Agentが必要な設定を見つけられず、同名の別projectを編集することがあります。

Git repositoryなら、開始時にbranchとworking treeの状態も確認します。既存の差分を自分の変更と思い込まないよう、Agentには「現時点で変更済みのfileを列挙し、それらは指示がない限り変更しない」と伝えます。開いたfolderが期待したrepositoryか、terminalで現在位置とGit rootを照合するのも有効です。

初回taskは「理解メモ」を作る

Cursorの現行Quickstartでは、Agentへcodebaseの主要entry point、key module、読むべき箇所を説明させる例が掲載されています。いきなりrefactorを依頼するのではなく、まず回答に根拠fileを含めてもらいます。

表は横にスクロールできます

知りたいこと	Agentに調べさせる内容	人が確認する根拠
起動方法	READMEとpackage script	実際のscript名、必要環境
主要route	router設定とpage構成	実在するfileとURL
data flow	API、state、storage	呼び出し元と返却型
test方法	test設定と既存suite	CIやpackage scriptsとの一致
project固有規則	README、CONTRIBUTING、rule	適用範囲と優先順位
危険な領域	auth、migration、deploy	触る前に必要な承認

依頼例：

このrepositoryを変更せずに調べてください。主要entry point、画面とAPIの構成、開発起動方法、typecheck・test・lintのcommand、project固有ruleを、根拠file pathと一緒に要約してください。読み取れなかった点は推測せず「未確認」としてください。既存の変更fileがあれば一覧にし、変更しないでください。

この依頼の目的は網羅的なarchitecture文書を作ることではありません。次の実装で必要な前提だけ把握し、推測と確認済みの情報を分けることです。

Codebase indexと読み込み完了を区別する

Cursorはprojectを開くとcodebase indexingを開始し、Agentがcodebaseを検索して関連fileを見つけます。indexingの進み具合や対象のfileは設定画面で確認できます。大きなprojectやignore設定によって対象が変わるため、開いた直後に返答があったことだけでrepository全体を読み込んだと考えないでください。

必要なdirectoryがignoreされていないか、意図しないbuild outputやvendorが大量に含まれていないかを確かめます。秘密情報や無関係なfileをAgentのaccess対象から除くには、公式Agent Securityで案内される.ignore系設定を使います。設定の反映範囲や優先順位は現行docsで確認し、重要fileへ本当にアクセスできないことを小さいtaskで確かめます。

Agentの説明にfile pathが含まれない、存在しないscriptを案内する、架空のrouteを挙げる場合は、実装へ進まず、該当情報をrepository内で確認し直します。回答の正しさは、説明の流暢さではなく実fileとの一致で判断します。

Project ruleと既存patternを読む

READMEだけでなく、CONTRIBUTING、package scripts、lint・format設定、directory内rule、CI workflowなどを確認します。project固有の開発ルールがある場合、CursorのAgent ruleとrepositoryの実際の指示を混同しないよう、どれが現在のsource of truthか特定します。

次に、変更予定の近くにある既存実装を一つか二つ読みます。新しいcomponentやAPIを足す場合は、型、error handling、test配置、naming、loggingの既存patternを確認します。同じ役割の実装がすでにあるなら、別方式を追加する前に再利用できるか検討します。

表は横にスクロールできます

見る順	例	何を決めるか
1. Repo入口	README、workspace file	projectの範囲と起動方法
2. 実行契約	package scripts、CI	正しい検証command
3. 実装pattern	近いmodule、test	再利用する構造
4. 制約	rules、ignore、security docs	Agentに触らせる範囲
5. 変更境界	git diff、owner	既存差分や高risk領域

まずは使ってみる

記事の文脈に合うToolへ進めます。報酬の有無で見た目は変えていません。

• 

  Cursor

  公式サイトを見るTool詳細を見る比較を見る

小さな変更で理解が合うか確かめる

初回の実装は、copyや限定されたbugなど影響を追えるtaskが向きます。作業前に、目的、変更してよいfolder、触らないAPIやschema、必要なtest、終了条件を指定します。Cursor Quickstartも、既存project上で小さな変更を作り、diffを確認し、project既存のtestやlintなどを実行する手順を紹介しています。

変更後はdiffをfileごとに見て、意図した範囲か、不要なdependencyやformat差分がないかを確認します。Agentがtestを実行したという報告だけでなく、実際のterminal outputとexit statusを確認します。最初のtaskでscopeが広がったり、projectの前提が違っていたりしたら、止めて理解メモを修正します。

Terminal commandは確認方法を先に決める

Cursor Agentはterminal commandを実行できるため、誤ったcommandはbuildだけでなくfileやdatabaseを変更する可能性があります。最初にpackage scriptやREADMEから既存のcheckを見つけ、実行してよいcommandと実行しない操作を分けます。

• 読み取りだけの調査か

• local生成fileが作られるか

• databaseやexternal serviceへ接続するか

• install、deploy、migrationを伴うか

• command実行前に人の確認が必要か

たとえばtestがfixtureしか使わないか、実databaseを触るかは名前だけで判断できません。scriptの定義と設定を見てから実行します。production credentialを使うcommandやデータ破壊につながる操作を、project理解のために試してはいけません。

Privacyとproject内容の境界

Agentへprojectを開くことは、全fileを無条件で外部処理してよいという意味ではありません。契約や社内規程でAI利用が制限されるrepositoryでは、利用前に承認を取ります。credential、顧客data、dump、private keyなどがcontextへ入らないようignoreとpermissionを確認します。

機密fileを無視する設定を加える場合は、既存のignoreやruleの効果を確認します。設定を追加しただけで処理対象から除外されたと断定せず、Agentへそのfile内容を読まずにpathだけ確認させるなど、安全な形で検証します。秘匿情報の具体値をprompt、log、共有メモへ貼り付けないでください。

次の実装へ移る前の確認

初回理解が終わったら、次の項目を短く埋めます。

• repositoryのrootと対象branch

• 変更前から存在する差分

• 主要entry pointと関連module

• 正しいtest・typecheck・lint command

• 使用する既存patternと関連tests

• Agentが読めない、または根拠を確認できない事項

• 高risk操作や機密領域の承認条件

ここで分からない項目があっても、無理に推測して実装へ進む必要はありません。Reader Jobは「Cursorへprojectを読み込ませる」だけでなく、誤った前提のまま変更を始めない状態を作ることです。情報が足りなければ、対象fileやscriptを人が確認してから範囲を決めます。

AIものさしの判断

既存projectでは、Cursorに最初の変更を頼む前に、repositoryのroot、entry point、実行方法、rule、差分の状態を確かめます。Agentのoverviewは調査の入口であり、fileやcommandのsource of truthではありません。根拠fileを照合し、影響範囲が分かる小さな変更で理解を試してから次へ進みます。これならproject固有の流儀を保ちながら、誤った階層や架空の実行手順を前提にするリスクを減らせます。