Cursor 入門実践ガイド

# 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が輝きます。

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

1. **Cursorをダウンロード** cursor.comから。個人利用は無料です（月500回のAIリクエスト制限あり）。私はProプラン（月20ドル）を支払い、無制限のリクエストを利用しています。1日6時間以上コーディングするなら価値があります。

2. **VS Codeの設定をインポート** CursorはVS Code 1.85をベースにしているため、キーバインド、テーマ、拡張機能が引き継がれます。最初にCursorを開くと、既存のVS Codeインストールから設定をインポートするかどうか尋ねられます。「はい」を選択してください。誤って「いいえ」をクリックして、キーバインドの再設定に1時間を無駄にしました。私のようにならないでください。

3. **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ルートがありました：

```javascript

// 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. **ハンドラ全体を選択**（1〜200行目）。

2. **Ctrl+Iを押して**インライン編集を開く。

3. **次のように入力**：「これを別々のハンドラに分割：GET、POST、PUT、DELETE用。各ハンドラは`pages/api/user/`の下の別ファイルにする。ファイルを作成してインポートを更新。」

4. **Cursorが4つのファイルを生成**：`get.js`、`post.js`、`put.js`、`delete.js`。また、それらをインポートする新しい`index.js`も作成。

5. **しかし欠点がありました**：Cursorは**元のファイルを削除しませんでした**。その結果、`pages/api/user.js`（古いもの）と`pages/api/user/index.js`の両方が存在することになりました。ルーターが混乱しました。古いファイルを手動で削除する必要がありました。

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

## 実際の欠点と回避策

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

1. **幻覚のインポート**：Cursorは存在しない関数をインポートすることがよくあります。例えば、`import { validateEmail } from './utils'`を生成しましたが、実際の関数は`./helpers/validation.js`にありました。常にインポートを確認してください。

2. **プロジェクト構造を見失う**：プロジェクトに100以上のファイルがある場合、Cursorのコンテキストウィンドウが満杯になります。30分間の集中的な使用後、AIが見えなくなったファイルを参照するコードを提案し始めることに気づきました。**修正**：コンテキストキャッシュをクリアするために、1時間ごとにCursorを再起動してください。

3. **警告なしにコードを上書き**：インライン編集モードで、変更を依頼した後に新しいことを入力すると、Cursorは**選択全体を新しいプロンプトで置き換えます**。Enterキーの代わりに「# これを修正」と入力したため、動作していた関数を1つのコメントで誤って置き換えてしまいました。**修正**：新しいインライン編集を開始する前に、必ず`Escape`キーを押してキャンセルしてください。

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

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

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