Cursorのエージェントモードチュートリアル：GPT-5.6 SolでREST APIを構築する

Cursorとは？

CursorはAI機能を織り込んだVS Codeとして始まり、見た目は今もそれに近いままです。エディタ、ファイルツリー、ターミナル、拡張機能——どれもおなじみです。

ただし裏側では、AIが横で質問に答えるだけでなく、実際に並走して作業するという前提に作り直されています。そのため、エージェントモード、コードベースのインデクシング、セッション中に最先端モデルを切り替えられるモデルピッカー、直前の操作文脈全体を踏まえて次の一手を予測するインライン補完が用意されています。

Cursorの最新機能をさらに知りたい場合は、Cursor AutomationsやCursor SDKのチュートリアルをおすすめします。

GPT-5.6とは？

GPT-5.6はOpenAIの最新世代で、単一モデルではなくSol、Terra、Lunaの3つから成ります。これらの名称は旧来の「Instant」ラベルを置き換える、明確に分かれた能力ティアです。

概要は次のとおりです。

• Solはフラッグシップで3つの中で最も強力です。新しいmaxの推論努力レベルとultraモードを解放する唯一のティアであり、コーディング、生物学、サイバーセキュリティの伸びが最も大きい層です。

• Terraは日常使いのデフォルト。OpenAIはGPT-5.5と競合しつつ価格はおよそ半分と位置づけています。

• Lunaは高速・低コストのティアで、大量処理やレイテンシに敏感な用途向け。価格以上の実力があります。

このウォークスルーではSolが重要なので、ここでもSolを使います。Solには新しい設定が2つあり、どちらを実際に触るか知っておく価値があります。maxはxhighの上に位置する推論努力レベルで、単一エージェントが難題により長く取り組めます。これはCursor側で設定する階段の最上段です。ultraは並列サブエージェントに仕事を分割し、OpenAIのベンチマーク最良値（Terminal-Bench 2.1で91.9%）を出しますが、動作するのはCodexとAPIのみで、Cursorのピッカーには出てきません。

完全なベンチマーク表と3ティアの価格はGPT-5.6 Sol、Terra、Lunaガイドをご覧ください。

CursorでGPT-5.6 Solへアクセス・設定する方法

GPT-5.6 SolはCursorのモデルピッカーから選べますが、最初に知っておくべきことが1つあります。Cursorの他の最近のフロンティアモデルと同様に、SolはCursorのMax Mode専用で動作します。つまりフルのコンテキストウィンドウとすべてのツールを使用し、請求はリクエスト単位ではなく使用量ベースです。長い実行ではトークン消費に注意してください。

モデルを選ぶには：

1. エージェントパネルをCmd+L（Mac）またはCtrl+L（Windows/Linux）で開きます。
2. 入力欄下部のModelボタン（小さなアイコンと現在のモデル名が表示）をクリックします。
3. もしAutoがオンならオフに切り替えます。
4. リストからGPT-5.6 Solを見つけ、隣のEditをクリックします。
5. 右側に開くパネルで、コンテキストウィンドウ、推論レベル、Fastトグルを個別に設定できます。

適切な推論努力レベルを選ぶ

Solを選ぶとモデル自体は決まります。推論努力は、そのタスクに対してどれだけ深く考えるかを決めます。選択肢は以下です。

• None
• Low
• Medium
• High
• Extra High
• Max

NoneやLowは最速・最安で、オートコンプリートや、やることがほぼ見えている機械的なリファクタに向いています。

HighやExtra Highは、最初に問題をきちんと考え抜くため時間がかかります。複数ファイルにまたがる計画を立てる際や、原因がすぐには見えない失敗をデバッグする際に、その差が特に効きます。

MaxはExtra Highの上に位置し、単一エージェントに最も多くの時間を与えます。SolのultraのマルチエージェントモードはCodexとAPI専用で、Cursorのピッカーには現れません。

GPT-5.5から移ってくる場合の注意点として、レベルは対応しません。OpenAI自身のガイダンスでは、慣れたタスクなら以前より1段低いレベルから始め、必要な場合にのみ上げることを推奨しています。本稿でもそれに従っており、5.5の同等チュートリアルより低い努力で走らせているステップがあります。

以下のハンズオンでは、各タスクに最適と思われる推論レベルを提案しますが、ぜひ設定を変えて出力の違いも試してみてください。

コンテキストウィンドウと速度モードの選択

コンテキストウィンドウは272Kと1Mから選べ、Fastモードをオンにすると、クレジットコスト約2.5倍でトークン生成が約1.5倍速くなります。応答を待つ対話型のやり取りではFastが有用なことが多いです。バックグラウンドで任せている長めのタスクでは、オフのままでも問題ありません。

Cursorのセットアップ

それでは、Cursorでプロジェクトをセットアップします。

前提条件と初期設定

GPT-5.6 Solの利用には有料のCursorプラン（Pro以上）が必要で、SolはMax Modeで動作するため、アカウントで使用量ベースの課金を有効化しておく必要があります。このプロジェクトで必要なローカル依存はPython 3.11+のみです。Cursorがまだインストールされていない場合は cursor.comから入手し、サインインして、ターミナルから次を実行します：

mkdir budget-api && cd budget-api
git init
cursor .

右側にエージェントパネル、左側のファイルエクスプローラにはまだファイルがありません。これは、エージェントに構成を作らせる前の理想的な出発点です。

CursorのAIインターフェースを使い分ける

実装に入る前に、主なインタラクションモード3つとその使いどころを把握しておくとよいでしょう。間違ったモードを使うと、避けられる摩擦が生まれます。

インライン補完はバックグラウンドのオートコンプリート層です。入力に合わせ、ファイル内の周辺文脈を元に灰色の提案が表示され、Tabで確定します。呼び出す必要はなく、自然に現れます。手書きでコードを書きつつ、フローを中断せずにタイプ数を減らしたいときに最適です。

Askモードは、モデルにファイルを読ませ、変更を加えずに質問へ回答させる場です。コードを読んでもらい見解を聞く、同僚への相談に近いイメージです。未知のコードベースで、なぜそう書かれているかを理解したいときや、方針を固める前の思考整理に役立ちます。

エージェントモードは本チュートリアルの主役です。エージェントセッションでは、モデルがファイルを編集し、ターミナルコマンドを実行し、パッケージをインストールし、テストスイートを走らせ、出力を読み、失敗にループバックします。これは「質問」ではなく「タスクを任せる」モードで、成果の質は事前に与えるコンテキスト量に正比例します。モードのセレクタは、上記スクリーンショットのパネル左下にあります。

AGENTS.mdでプロジェクト固有の指針を確立する

このファイルは自分で書きます。まだモデルは使いません。次のプロンプトでエージェントがこれを読むため、まずHighに切り替えてください。エージェントセッションが脱線する原因の多くは、モデルのミスではなく、プロジェクト固有の前提を知らずに推測してしまうことです。採用フレームワーク、命名規約、触ってはいけないファイル、変更の検証方法など。

そこでAGENTS.mdの出番です。人間のREADMEのエージェント版として、あなたには当然でもモデルには不可視な事項を書き留めます。AGENTS.mdは2025年にOpenAIの取り組みとして始まり、現在ではツール横断のエージェント指示ファイル標準（Linux FoundationのAgentic AI Foundationの一部。AnthropicのMCPと並ぶ）です。一度学べばどこでも使えます。

プロジェクトルートにAGENTS.mdを作成し、ツールスタック、コーディング規約、境界を次の内容で定義してください：

# AGENTS.md

## Stack
Python 3.11, FastAPI, SQLModel, SQLite (via aiosqlite), pytest, httpx

## Conventions
- All endpoints under /api/v1/
- Pydantic models in app/models.py
- Database logic in app/database.py
- Route handlers in app/routers/
- Type hints required on all function signatures
- Explicit imports only, no wildcards

## Boundaries
- Do not delete or modify any file in tests/ without asking first
- Do not change the DATABASE_URL; it reads from .env
- Never touch pyproject.toml dependencies without showing the diff first

## Verification
Before considering any task complete:
  pytest tests/ -v
  ruff check .
Both must pass.

境界セクションは見落とされがちですが最重要です。これがないと、エージェントが「善意」で、頼んでいない再構成や掃除をすることがあります。やるべきことだけでなく、触ってはいけないことを明示するのが同じくらい有効です。

AGENTS.mdはツール横断の標準ですが、Cursorネイティブの同等機能（スコープ付き.mdcファイル）を使いたい場合は、Cursor Rulesチュートリアルで、Python Webプロジェクトに向けたセットの構築を解説しています。

GPT-5.5で予算管理APIを構築する

本プロジェクトは、個人の予算エントリを記録するためのREST APIです。エントリの作成、（任意のカテゴリフィルタ付きでの）一覧取得、削除、月次の支出サマリ取得ができます。

ドメインロジックで迷子にならない程度にシンプルですが、実装にはデータベース層、入力バリデーション、型付きレスポンスモデル、複数のルートハンドラの連携が含まれます。これは、実際の複数ファイルセッションでエージェントが何をするのかを示すのに十分です。

Step 1: プロジェクト構成をスキャフォールドする

エージェントパネルを開き、送信前に推論努力をHighに設定します。コードを書く前に提示される計画の有用性は、その背後の推論の深さ次第です。ここで浅い回答だと、後で構造的な決定を解きほぐす羽目になります。最初のプロンプトとして次を送ってください：

Set up a FastAPI project for a budget tracker API using SQLModel with 
async SQLite. Structure it with separate files for models, database, and 
routes under an app/ directory. Set up pyproject.toml with uv, install 
dependencies, and create a main.py that starts the app.

Before writing any code, show me the planned directory structure 
and wait for my approval.

この最後の一文は、非トリビアルなエージェントプロンプトには常に入れておく価値があります。実行前の計画を求めるのにかかるのは15秒程度の読書時間ですが、十数ファイルに広がる前に構造上の判断を検知できます。

GPT-5.6 SolのHighは、曖昧な要約ではなく実際に役に立つ具体的な計画を出します。いま構成を確認しておく方が、後から再編するよりはるかに速いです。

エージェントはプロジェクトのレイアウトを提案し、1ファイルも書く前に承認を待ちます。

「良さそう。進めてください」のように返信すると、エージェントが構築を開始します。左のファイルツリーがリアルタイムに増えていく様子や、下部のターミナルでuvがパッケージをインストールする様子を確認できます。

スキャフォールドの一環としてpyproject.tomlが作成され、その内容が新規追加としてエディタに表示されます。

スキャフォールドが完了したら、次に進む前にapp/models.pyとapp/database.pyを開いて確認しましょう。BudgetEntryモデルに最低でもid、amount、description、category、dateがあり、database.pyが特異な点なくasync SQLiteエンジンをセットアップしていることを確認してください。

気になる点があれば、次のメッセージで伝えてから進んでください。この段階での修正は安上がりですが、20ファイル変更後ではそうはいきません。

Step 2: コアエンドポイントの実装

推論努力はHighのままでよいですが、まずMediumでも試せます。SolのMediumは、GPT-5.5ではHighが必要だった複数ファイル連携をこなします。実装プロンプトを送ってください：

Implement endpoints for budget entries under /api/v1/entries/. Include:
- POST /api/v1/entries/ to create a new entry, returning 201
- GET /api/v1/entries/ to list all entries, with an optional ?category= filter
- DELETE /api/v1/entries/{id} to delete an entry, returning 404 if not found

Use typed Pydantic response models and dependency injection for the DB session.
After implementing, start the app and confirm the /docs endpoint loads.

エージェントはmodels.py、database.py、routers/entries.py、main.pyを一度に調整します。各ファイルの変更が終わると、Cursorはエディタで新しい内容をハイライト表示するので、受け入れる前に確認できます。変更ファイル下部にはUndo/Keepのコントロールが表示されます。

スクリーンショットは、エージェントがentries.pyのルーターを実装し、サーバー起動と/docsの正常表示を確認した場面です。

実装を受け入れてサーバーが起動したら、ブラウザでhttp://localhost:8000/docs を開き、配線が正しいことを確認します。

FastAPIの自動生成ドキュメント（/docs）に、3つのエンドポイントが正しく登録されています。

Step 3: カテゴリのバリデーションを追加

このステップは推論レベルをLowまたはMediumに下げても構いません。Enum追加と2つのテストは自己完結的で予測可能なので、余分な熟考は要りません。

現状では任意の文字列をカテゴリとして受け付けるため、すぐに不整合なデータがたまります。これを修正しましょう：

Budget entries should only accept these categories: 
food, transport, housing, entertainment, health, other.

Reject any entry with an invalid category using a 422 status and a clear 
error message. Use a Python Enum for the category type. 
Add tests for both a valid category submission and an invalid one in tests/test_entries.py.

エージェントはmodels.pyにカテゴリのEnumを追加し、Pydanticモデルをそれに合わせて更新します。PydanticはEnumに対して自動的にバリデーションを行うため、無効なカテゴリはルートハンドラに到達する前に弾かれます。

あわせてテストを2つ書くはずです。1つは有効なカテゴリが正しく保存されること、もう1つは無効なカテゴリで422が返ることを確認します。

@参照の活用

変更を受け入れたら、Cursorの@コンテキスト機能で簡単な確認質問を投げてみましょう：

@app/models.py Does the CategoryEnum cover all six categories I listed?

@をエージェントパネルでタイプするとファイルピッカーが開き、app/models.pyを選ぶと、そのファイル内容が直接プロンプトに取り込まれます。エージェントが検索したりパスを推測したりする必要がありません。

Step 4: 月次サマリエンドポイントを実装

ここではHighに戻します。集計クエリでは、フィルタ、グルーピング、レスポンスモデル設計を同時に考える必要があります。どれか1つでも誤ると3ファイルすべてに手戻りが発生します。CRUDが整ったら、サマリエンドポイントを追加します：

Add a GET /api/v1/entries/summary endpoint that accepts month (1-12) and year as query parameters. 
It should return total spending per category for that month and an overall total. 
Use a typed Pydantic response model. 
If no entries exist for the requested month, return an empty summary with zero totals rather than a 404.

これは全件取得ではなく、フィルタ付き集計が必要なため、より面白いDBタスクです。database.pyでエージェントがクエリをどう組むか注目してください。SQLModelのクエリインターフェースを使い、生のSQLは避け、models.pyで定義するレスポンスモデルにきれいにマッピングされるべきです。

変更を受け入れたら、test_entries.pyにこのエンドポイントのテストを1つ自分で書いてみましょう。特定の月に2つのエントリを作成し、その月のサマリエンドポイントを呼び、合計が一致することをアサートします。エージェントに頼らず自分で1つ書くと、テストクライアントやフィクスチャの構造に慣れる良い機会になります。

test_entries.pyには、エージェントが書いたカテゴリ検証テストと、手書きのtest_monthly_summaryが並びます。

Step 5: 検証ループを実行

LowまたはMediumで十分です。テスト実行とLint修正は反応的な作業で、エージェントはエラー出力を読み、狙い撃ちで修正するだけで、アーキテクチャの判断は伴いません。テストをエージェントに任せます：

Run pytest tests/ -v and fix any failing tests. 
Do not modify test assertions to make them pass, fix the implementation instead.
Once all tests pass, run ruff check . and fix any linting issues.

pytestの出力がエージェントパネルにストリーム表示されるのを見守りましょう。

失敗があれば、エージェントはトレースバックを読んで原因ファイルを特定し、修正までを同一セッション内で行います。エラーをコピペして新規メッセージを送る必要はありません。デバッグから修正までが1つの連続スレッド内で完結します。

スクリーンショットは、検証ループ全体の報告です。このケースでは、ruffチェックがローカルのpyenv/.python-version不一致によるインタプリタ解決の問題で止まりました。コード自体の問題ではありません。

ここで起きたことは重要です。エージェントは、我々のコードとは無関係な環境問題に遭遇し、その原因を推論して、促されずとも回避策を見つけました。ツール障害をまたいだ文脈的な問題解決こそが、GPT-5.6 Solが以前のモデルをリードする部分です。

また、検証プロンプトには「テストのアサーションを変えて通すのではなく、実装を直すこと」を毎回含める価値があります。これがないと、エージェントが楽な道を選んでテストの厳しさを下げ、振る舞いを直さない場合があります。

Step 6: コードレビューのパス

送信前に推論をHighへ戻すか、エッジケースを徹底的に詰めたい場合はExtra High/Maxでも構いません。この段階での浅い推論は、誤った安心感を生みます。パターンマッチではなく、潜在的な問題を実際にすべて洗い出してほしいからです。

プロジェクトを完了と見なす前に、エージェントでレビューします：

Review the current codebase and report on:
1. Query params or path params that are missing validation
2. Database sessions that might not be closing properly
3. Endpoints returning incorrect HTTP status codes
4. Any places where user input reaches the database without going 
   through the ORM

Do not make any changes yet. List each issue with file and line number.

エージェントは、DELETE /api/v1/entries/{entry_id}が204と404を正しく返すこと（file:line参照付き）、GETルートが適切な200デフォルトに依拠していること、ユーザー入力がORMを介さずDBに到達する箇所がないことを確認しました。

一覧を確認したら、修正適用のフォローアップを送ります：

Apply the fixes for the status code issues and the session handling. 
Skip any rate-limiting suggestions, that's out of scope for this version.
Run the tests again after applying.

Step 7: READMEとCIワークフロー

仕上げに2点。どちらもモデルの推論はLowで十分です。READMEの構成は予測可能で、CIのYAMLはほぼ定型です。ここで高い推論に支払うのは無駄です。

Write a README.md with setup instructions, a table of all endpoints (method, path, description), and example curl commands for each endpoint.

続いて：

Create a .github/workflows/ci.yml that runs pytest and ruff on Python 3.11 for every push and pull request to main.

7つのステップを終えると、プロジェクト構成は次のようになります：

まとめ

ここで作ったのは小さなAPIですが、ワークフローはどれだけでもスケールします。

AGENTS.mdは、エージェントが1ファイルでも触る前に用意してください。非トリビアルな作業では、実行前の計画を求めましょう。プロンプトを段階化し、一度に巨大な差分をレビューするのでなく、自然なチェックポイントを作ってください。特定ファイルに関するピンポイントの質問には@filenameを使いましょう。そして、完了とみなす前にレビューのパスを入れてください。たいてい何かしら見つかります。

CursorのGPT-5.6 Solは、長いセッションでもタスクに集中し、ファイル横断の不整合を捉え、破壊的に突き進むのでなく適切に立ち止まって確認できる点で、これまでの組み合わせより明らかに優れています。ただし、モデルは絵の一部にすぎません。事前のコンテキスト付与、検証ループ、最後のレビュー——そこにこそ成果物の質を大きく押し上げる要因があります。

推論レベルの目安としては、Highはアーキテクチャ判断、複数ファイルの連携、原因が明白でないデバッグに、MediumやLowはドキュメント、ボイラープレート、単一ファイルのタイピング代行に適しています。コードレビューや、ミスのコストが高く入念なエージェント実行が望まれる場面ではExtra HighやMaxも検討してください。