Cursorの賢い使い方を学ぶ#1

これまでCursorをうまく使いこなせていないために振り回されている感じがしていたので、Cursorを正しく学ぶトライをしようと思います。

ターゲット

Cursorの機能の中でも、自然言語で相談しながらコードベースを作るための機能を中心に学んでいこうと思います。

開発対象

ユーザーが良し悪しを評価できる必要があるので、今回はユーザーであるKimuraがよく知っている環境を選びます。Ruby on Railsを使ってオーソドックスなSNSを作ります。

まずは公式ページをじっくり見る👀

公式の情報に正しく接すると新しい発見があるもので…CHATタブとCOMPOSERタブの2種類あるんですね。

私の手元のCursor環境を見にいくと…

CHAT画面しかないような？

COMPOSERタブを求めてドキュメントを見にいく

頭から読んでみたり、検索してみたりした結果、以下を見つけました。

What happened to the Composer?
In past versions of Cursor, we had two seperate concepts: the chat, and the composer. The chat was a read-only interface, like the Ask mode, and the composer was what we now call Manual mode. With the addition of the Agent mode, and the idea that the AI was now capable at learning your codebase on its own, we decided to combine the chat and composer into a single interface, and call it Chat.

COMPOSERタブはもうないんですね。その代わり、Agent/Ask/Manualの３モードができたようです。

各モードに関するドキュメントはこちら：

各モードの役割を理解して使ってみる

Askで実装前の相談をする

今回は空のリポジトリの状態で、イメージしているプロダクトの情報を伝えてアーキテクチャーを相談しました。これまでの失敗を踏まえて、以下に気をつけました：

• 一回の質問で求めるのは一つのこと
• できるだけ具体的に情報を与える
• 「相談」をするときは、足りない情報を挙げてもらうのがスムーズ
• セキュリティ関連などは、「最新のベストプラクティスに沿ってほしい」と付け加えて、具体的に参照してほしい時系列を指定しました（それでも検索ワードは去年が指定されていたので、ここは改善が必要そうです。）

Agentで反映する

さっき提案してくれたアーキテクチャーを、文書化してください

この一文だけで、アーキテクチャ決定記録（ADR, Architecture Decision Record）形式を使って文書化してくれました。

Git操作は事故りがちなので、人間がやる→Rulesを追加したらうまくいった

これまでの経験でGit操作はほぼ毎回なんらかの事故を起こしていたので、人間がやります。なんでCursor Agentだと事故るのかについては、今後言語化してRulesを整備していけば解決する気もします。

Git操作は、毎回コンテキストを確認してから慎重に操作する必要があります。その難しさを言語化して、Rulesに追加したところ、うまくいきました。

記述したRuleは以下です

## Git操作に関するガイドライン

Cursor AgentがGit操作を行う際には、以下の点を厳守してください：

1. **作業ブランチ vs ベースブランチの区別がつかない前提で動作する**
   - Agentは、今いるブランチが「main」「develop」などのベースブランチであるか、「feature/」などの作業用ブランチであるかを判断できません。
   - したがって、Agentが変更を検知した場合は、**いきなりコミットせず、必ずブランチを作成する提案を行うこと**。

2. **変更検出時の確認プロンプト**
   - コミット操作や`push`操作を行う前に、以下のような確認を必ず表示してください：

     > 「現在のブランチ（{{branch_name}}）はベースブランチかもしれません。このまま変更を加えてもよろしいですか？  
     > それとも、新しい作業ブランチを作成してから進めますか？」

3. **危険な操作には二重確認を行う**
   - 以下の操作は事故に直結するため、Agentが自動実行してはなりません。使用者に理由と影響範囲を明示し、二重確認を必須としてください：

     - `git push --force`
     - `git reset --hard`
     - `git rebase`
     - コンフリクト未解消状態での `git commit`

4. **明示的なプロジェクト構成がない限り、`main` や `develop` は「保護すべきブランチ」と見なす**
   - ブランチ名の慣例（main, master, develop, release）をベースブランチと仮定し、これらに直接変更を加える前には、必ず警告を提示してください。

このルールは、Cursor Agentがプロジェクトの意図を誤って破壊することを防ぐために必要です。Agentはローカル状態を100%理解しているわけではないことを前提に、安全確認と明示的合意を最優先してください。

PRの概要欄はAskにMarkdownを書いてもらうのが楽

GitHub CLIを使えば、Cursor AgentからPR作成までやってもらえるのですが、PRの概要欄がいつもうまくいきません。改行が\n記号のままになっていたりします。最終的には毎回一時ファイルにMarkdownを書いてPRにつける形で成功するのですが、そこに辿り着くまでに何回分かを消費してしまいます。今回は、LLMの便利さを享受することを優先して、PR自体は自分で作成し、概要欄の内容をAskにお願いしてMarkdownで書いてもらいました。

この部分もCursor的にはUser Rulesの設定が必要そうなので、作成してみました。

## PR作成に関するガイドライン

Cursor AgentがGitHub CLI（`gh`）を使ってPull Request（PR）を作成する際には、以下の点を厳守してください。

### 1. PRの概要欄作成時は、**ベースブランチとの差分に含まれる全てのコミット**を確認すること

- 最新の1コミットだけを対象にするのではなく、`git log`等を使用してベースブランチとの差分すべてを取得してください。
- 各コミットメッセージの要約を含め、PRの目的や背景がわかるMarkdown形式で概要欄を作成してください。

### 2. 概要欄はMarkdownの一時ファイルとして保存・使用すること

- `gh pr create` の `--body` オプションに直接渡すのではなく、以下の手順を踏んでください：

  1. PRの概要欄をMarkdown形式で一時ファイル（例：`.cursor_pr_body.md`）として保存する
  2. `gh pr create --base {{base_branch}} --head {{current_branch}} --body-file .cursor_pr_body.md` を実行してPRを作成する
  3. PR作成後、この一時ファイルは自動的に削除すること

### 3. ベースブランチを明示的に確認して指定すること

- PR作成時には現在の作業ブランチから見た**ベースブランチ（通常は`main`や`develop`）**を確認し、そのブランチに向けてPRを作成してください。
- 自動で推定せず、`git merge-base` などを活用して明示的に差分を確認するのが望ましいです。

---

これらのルールは、PR作成時の情報欠落や改行崩れといった不具合を防ぎ、プロジェクトのレビュー体験を向上させるために必要です。Cursor AgentはGitHub CLIを使って操作する際、ローカル状態やCLIの挙動を正確に把握していない可能性があるため、慎重な操作が求められます。

想定通りに動いていそう：

レビューする

レビューしてくれるAIエージェントが登場してきているので、今後試してみたいとは思っていますが、今回はユーザーが手動でレビューを行います。

今回は開発に向けたドキュメント作成だけでしたが、コミットを重ねていくと、既存のドキュメントで定義した内容との一貫性がない場面に遭遇しました。レビューはやはり必要です。具体的には、Railsベースのアーキテクチャーなのに、環境構築がpnpmでbuildするようになっていました...

Manualモードとは？

AgentモードとAskモードは機能の内容が分かりやすかったのですが、Manualモードはいまいちピンと来ませんでした。Manualモードの説明をじっくり読んでみます。

修正対象のファイルと修正内容をユーザーが直接指示して修正してもらうのがManualモードのようですね。

Chatウィンドウは定期的に新しくする

Chat上で相談しながら修正を加えていくと、急にAI側の物忘れが激しくなることがあります。セッションが長くなると過去の指示を忘れていくそうなので、Chatウィンドウをこまめに切り替えると良いみたいです。

Chatウィンドウをこまめに新しくするということは、プロジェクトの進み具合を断続的に収集できる工夫が必要だということです。

Askモードで断続的な進度を管理したい旨を相談したら、マイルストーン文書の作成を提案されました。とてもありがたい。

1日の終わりにJOURNALを自動で書いてくれるのもありがたい

Askモードでは、コードベースの修正以外にも使えない機能がありそう

Function CallingできるセットがAgentモードとは違いそうですね。

次に向けて

今回は、Cursorのモードや使い方の基本を確認しながら、開発の初期フェーズでつまずきがちなポイントを整理しました。Git操作のように事故が起こりやすい部分は、ルールを整備することで安定してきましたが、PR作成やレビューとの連携にはまだ改善の余地があると感じました。

次回は、実際に機能を実装しながら、Agentモードがどこまで実用的に使えるのかを検証していこうと思います。Cursorを活用して、どこまで省力化できるのか、どのタイミングで人の判断が必要になるのかを見極めていきたいです。