Cursor入門：実践ガイド

IDEに怒り狂って投げ出した瞬間を覚えています。Reactコンポーネントをリファクタリングしているとき、カーソルが3つのファイルを行ったり来たり、スニペットをコピーして貼り付け、インポートを修正し、ステート管理を壊さないように祈っていました。5回目の手動編集の後、こう思いました：もっと良い方法があるはずだ。 そこでCursorを試しました。

CursorはVS Codeをベースに構築されたコードエディタですが、単なる外観の変更ではありません。AIをワークフローに直接統合しています。GitHub Copilotを強化したようなもので、コンテキストを認識するチャット、インライン編集、デバッグを支援するターミナルを備えています。本番のNode.jsアプリで3ヶ月間毎日使用した後、何がうまくいき、何が壊れ、週末を無駄にせずに始める方法をご紹介します。

Cursorの理由（そしてスキップすべき時）

Cursorのキラー機能はコンテキストです。Copilotは現在のファイルに基づいて補完を提案します。Cursorはプロジェクト全体の構造、開いているファイル、さらにはターミナルの履歴まで見ることができます。20のパッケージがあるモノレポのような、依存関係が複雑なコードベースで作業している場合、CursorのAIは幻覚を起こす頻度が低くなります。

しかし完璧ではありません。CursorのAIは正しく見えるが、エッジケースのバグを静かに導入するコードを生成することがあります。また、低スペックのラップトップを使用している場合、AIの提案が遅く感じられることがあります（2019年のMacBook Proで1〜2秒の遅延を経験しました）。小さなスクリプトやチュートリアルには、VS Code + Copilotで十分です。実際のリファクタリングには、Cursorが輝きます。

はじめに：インストールとセットアップ

Cursorをダウンロード cursor.comから。個人利用は無料です（月500回のAIリクエスト制限あり）。私はProプラン（月20ドル）を支払い、無制限のリクエストを利用しています。1日6時間以上コーディングするなら価値があります。
VS Codeの設定をインポート CursorはVS Code 1.85をベースにしているため、キーバインド、テーマ、拡張機能が引き継がれます。最初にCursorを開くと、既存のVS Codeインストールから設定をインポートするかどうか尋ねられます。「はい」を選択してください。誤って「いいえ」をクリックして、キーバインドの再設定に1時間を無駄にしました。私のようにならないでください。
AIモデルを設定 設定 > Cursor > AIに移動します。デフォルトのモデルはgpt-4oですが、技術的なタスクにはclaude-3.5-sonnetに切り替えました。コード構造の推論に優れています。他のモデルにアクセスできる場合は、カスタムAPIキーを設定することもできます。

週を救った3つのCursorモード

Cursorには3つの対話モードがあります：チャット、インライン編集、ターミナルAI。それぞれの使い方を説明します。

1. チャット：コンテキストを認識するアシスタント

チャットパネル（Ctrl+K）は、隣に先輩開発者が座っているようなものです。しかしCopilot Chatとは異なり、Cursorのチャットはプロジェクト全体を見渡せます。これをテストするため、/services/payment.tsのファイルにカーソルを置いたまま、「このAPIエンドポイントが500を返すのはなぜですか？」と尋ねました。Cursorはこう答えました：「/utils/webhooks.tsのvalidateWebhook関数が47行目で未処理のエラーをスローしているためです。HMACの不一致をキャッチし忘れています。」

そのレベルのコンテキストは不気味です。しかし欠点があります：Cursorのチャットはコードを実行できません。静的ファイルを読み取るだけです。そのため、バグが実行時の競合状態である場合、チャットは間違った推測をします。Cursorが「問題はデータベース接続にあります」と言ったため、幽霊バグの追跡に2時間を無駄にしましたが、実際の問題はループ内のawaitの欠落でした。

プロのヒント：チャットを使用するときは、エラーメッセージをそのまま含めてください。Cursorは記憶からエラーメッセージを推測するのが苦手です。正確なスタックトレースをコピー＆ペーストしてください。

2. インライン編集：リファクタリングマシン

インライン編集（Ctrl+I）では、コードを選択して変更を依頼できます。ここがCursorの真価を発揮する場所です。ユーザー認証、ロギング、メール送信を処理する200行の関数がありました。古典的な神関数です。全体を選択して次のように入力しました：「これを別々の関数にリファクタリング：認証用、ロギング用、メール用。同じ動作を維持すること。」

Cursorは10秒以内に3つの関数を生成しました。しかし壊れたものがありました：元のファイルのインポート文の更新を忘れていました。新しい関数は定義されましたが、元のコードは依然として古いモノリシック関数を呼び出していました。手動でそれらを接続する必要がありました。そのため、生成されたコードに不足しているインポートがないか常に確認してください。CursorのAIは局所的な変更には優れていますが、全体像を見失うことがあります。

実際の例：Cursorに「このExpressルートにエラー処理を追加して」と依頼しました。ハンドラをtry-catchでラップしましたが、カスタムエラーロギングミドルウェアを削除しました。try-catchで十分だと考えたからです。これにより本番インシデントが発生しました。変更を「承認」する前に常に差分を確認してください。

3. ターミナルAI：デバッグの相棒

Cursorのターミナル（Ctrl+）にはエラーを説明するAIボタンがあります。npm run testと入力すると、不可解なERR_MODULE_NOT_FOUNDが表示されました。AIボタンをクリックすると、Cursorはこう言いました：「package.jsonにtype: moduleフィールドがありますが、テストファイルがCommonJSのrequire()を使用しています。テストファイルを.mjsにリネームするか、テストのサブディレクトリに"type": "commonjs"`を追加してください。」

これで20分のググり時間を節約できました。しかしターミナルAIはコマンドを実行できません。ターミナルの出力を読み取るだけです。エラーがネットワークタイムアウトの場合、Cursorは「インターネット接続を確認してください」と言いますが、これは役に立ちません。構文エラーや設定エラーに最適です。

実践的なワークフロー：実際のプロジェクトのリファクタリング

実際のセッションを説明します。Next.jsアプリに乱雑なAPIルートがありました：

// pages/api/user.js
export default async function handler(req, res) {
  const { method } = req;
  if (method === 'GET') {
    // 50行のユーザー検索
  } else if (method === 'POST') {
    // 60行のユーザー作成
  }
  // ...以下、PUT、DELETEも同様
}

これをHTTPメソッドごとに別々のファイルに分割したかったのです。正確に行った手順は次の通りです：

ハンドラ全体を選択（1〜200行目）。
Ctrl+Iを押してインライン編集を開く。
次のように入力：「これを別々のハンドラに分割：GET、POST、PUT、DELETE用。各ハンドラはpages/api/user/の下の別ファイルにする。ファイルを作成してインポートを更新。」
Cursorが4つのファイルを生成：get.js、post.js、put.js、delete.js。また、それらをインポートする新しいindex.jsも作成。
しかし欠点がありました：Cursorは元のファイルを削除しませんでした。その結果、pages/api/user.js（古いもの）とpages/api/user/index.jsの両方が存在することになりました。ルーターが混乱しました。古いファイルを手動で削除する必要がありました。

教訓：常にCursorに「元のファイルを削除」と明示的に指示してください。デフォルトでは削除しません。

実際の欠点と回避策

Cursorは強力ですが、3つの一貫した壁に直面しました：

幻覚のインポート：Cursorは存在しない関数をインポートすることがよくあります。例えば、import { validateEmail } from './utils'を生成しましたが、実際の関数は./helpers/validation.jsにありました。常にインポートを確認してください。
プロジェクト構造を見失う：プロジェクトに100以上のファイルがある場合、Cursorのコンテキストウィンドウが満杯になります。30分間の集中的な使用後、AIが見えなくなったファイルを参照するコードを提案し始めることに気づきました。修正：コンテキストキャッシュをクリアするために、1時間ごとにCursorを再起動してください。
警告なしにコードを上書き：インライン編集モードで、変更を依頼した後に新しいことを入力すると、Cursorは選択全体を新しいプロンプトで置き換えます。Enterキーの代わりに「# これを修正」と入力したため、動作していた関数を1つのコメントで誤って置き換えてしまいました。修正：新しいインライン編集を開始する前に、必ずEscapeキーを押してキャンセルしてください。

次のステップ：「プロジェクトを説明」機能を試す

リファクタリングから始めないでください。CursorのExplain Project機能から始めましょう。よく知っているコードベース（サイドプロジェクトなど）のフォルダを開き、チャットパネルの「Explain」ボタンをクリックして、「このプロジェクトは何をしますか？」と尋ねてください。Cursorが概要を説明します。何年も触っていなかった古いRailsアプリでこれを試したところ、Cursorはアーキテクチャ、データベーススキーマ、さらにはテストフレームワークまで正確に識別しました。変更を信頼する前に、Cursorがコードを理解しているかどうかをテストする優れた方法です。

最も乱雑なプロジェクトを開いて、Cursorに説明を依頼してください。感心するか恐怖するかのどちらかですが、どちらにしても自分のコードについて何かを学べるでしょう。

Cursor 入門実践ガイド