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라는 세 가지로 구성됩니다. 이 이름들은 각각의 능력 티어를 나타내며, 예전의 "Instant" 라벨을 대체합니다.

간단히 정리하면 다음과 같습니다.

• Sol은 플래그십이자 셋 중 가장 강력합니다. 새 max 추론 한도와 ultra 모드를 사용할 수 있는 유일한 티어이며, 코딩, 생물학, 사이버 보안에서의 향상이 가장 큽니다.

• Terra는 일상적인 기본값입니다. OpenAI는 이를 GPT-5.5와 경쟁하면서도 가격은 대략 절반 수준으로 포지셔닝합니다.

• Luna는 대량 처리나 지연에 민감한 작업을 위한 빠르고 저렴한 티어이며, 가격 대비 성능이 예상보다 높습니다.

코딩 워크스루에는 Sol이 핵심이므로 여기서는 그것을 사용합니다. Sol에는 두 가지 새로운 설정이 있으며, 실제로 건드릴 만한 것이 무엇인지 알아둘 가치가 있습니다. 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의 모델 선택기에서 사용할 수 있으며, 시작 전에 알아둘 점이 하나 있습니다. 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의 가이드는 익숙한 작업에서는 평소보다 한 단계 낮게 시작하고, 결과가 필요할 때만 올리라는 것입니다. 아래에서도 그 원칙을 따랐기 때문에, 몇몇 단계는 동등한 5.5 튜토리얼보다 낮은 노력으로 실행됩니다.

아래 실습 전반에서 각 작업에 가장 적합한 추론 레벨을 제안하겠지만, 직접 다양한 설정을 시도해 보고 출력이 어떻게 달라지는지 확인해 보세요.

컨텍스트 윈도 크기와 속도 모드 선택

또한 272K와 1M 컨텍스트 윈도 중에서 선택할 수 있고, Fast 모드를 켜면 대략 1.5배 속도로 토큰을 생성하는 대신 크레딧 비용은 약 2.5배가 됩니다. 응답을 기다리는 상호작용 상황에서는 Fast가 종종 그만한 가치가 있습니다. 반면에 백그라운드에서 길게 돌리는 작업이라면 꺼두어도 괜찮습니다.

Cursor 설정

이제 Cursor에서 프로젝트를 설정해 보겠습니다.

사전 준비와 초기 구성

GPT-5.6 Sol을 사용하려면 Cursor 유료 요금제(Pro 이상)가 필요합니다. 또한 Sol은 Max Mode로 실행되므로, 계정에서 사용량 기반 과금이 활성화되어 있어야 합니다. 이 프로젝트에 필요한 다른 로컬 의존성은 Python 3.11+뿐입니다. 아직 Cursor를 install하지 않았다면 cursor.com에서 받아 설치하고, sign in한 다음 터미널에서 다음을 실행하세요:

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

오른쪽에 에이전트 패널이 있고, 왼쪽 파일 탐색기에는 아직 파일이 없습니다. 에이전트에게 구조 생성을 맡기기 전에 바로 이 상태에서 시작하면 됩니다.

Cursor의 AI 인터페이스 살펴보기

본격적인 빌드에 들어가기 전, 상호작용 방식 세 가지와 각 방식이 언제 적절한지 알아두면 좋습니다. 잘못된 방식을 쓰면 불필요한 마찰이 생기는데, 이는 쉽게 피할 수 있습니다.

인라인 완성은 백그라운드 자동 완성 계층입니다. 타이핑할 때 현재 작성 중인 내용과 파일 주변 맥락을 바탕으로 회색 제안이 나타나며, Tab으로 수락합니다. 사용자가 호출하지 않아도 자동으로 나타납니다. 직접 코드를 쓰면서 흐름을 끊지 않고 키 입력을 줄이고 싶을 때 적합합니다.

질문 모드(Ask mode)에서는 모델이 파일을 읽고 답변하지만 아무 변경도 하지 않습니다. 동료에게 코드를 보고 의견을 묻는 것에 가깝습니다. 낯선 코드베이스를 이해하려 하거나, 왜 특정 방식으로 작성되었는지 파악하려 하거나, 특정 접근을 채택하기 전에 생각을 정리할 때 특히 유용합니다.

에이전트 모드는 이 튜토리얼 전체를 이끄는 기능입니다. 에이전트 세션에서 모델은 파일을 편집하고, 터미널 명령을 실행하고, 패키지를 설치하고, 테스트 스위트를 실행하고, 출력을 읽고, 실패 시 다시 반복합니다. 이 모든 것이 하나의 연속된 스레드 안에서 이루어집니다. 이 모드에서는 질문이 아니라 작업 자체를 위임하며, 사전에 제공하는 맥락이 많을수록 결과의 품질이 비례해 향상됩니다. 위 스크린샷에서 왼쪽 아래에 에이전트 모드 선택기가 보입니다.

AGENTS.md로 프로젝트별 가이던스 수립

이 파일은 직접 작성합니다. 아직 모델은 쓰지 않습니다. 다음 프롬프트에서 에이전트가 이 파일을 읽을 것이므로 먼저 High로 전환하세요. 에이전트 세션이 어긋나는 가장 흔한 이유는 모델의 오류라기보다, 프레임워크, 네이밍 컨벤션, 손대면 안 되는 파일, 변경 검증 방법 같은 프로젝트 특이 사항을 몰라서 추측하기 때문입니다.

AGENTS.md의 용도는 바로 그 부분입니다. 여러분에게는 자명하지만 모델에게는 보이지 않는 정보를 적어두는 에이전트용 README입니다. AGENTS.md는 2025년 OpenAI의 이니셔티브로 시작했으며 현재는 여러 도구에서 통용되는 에이전트 지시 파일 표준(Anthropic의 MCP와 함께 Linux Foundation의 Agentic AI Foundation 일부)로 자리 잡았습니다. 한 번 배워 두면 어디서든 활용할 수 있습니다.

프로젝트 루트에 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.

경계(Boundaries) 섹션은 사람들이 가장 자주 빼먹지만, 동시에 가장 중요합니다. 이 부분이 없으면 에이전트가 가끔 요청하지도 않은 부분을 정리하거나 재구성하려고 "도와주려는" 결정을 내립니다. 모델에게 해도 되는 일만큼이나 해서는 안 되는 일도 알려 주는 것이 유용합니다.

AGENTS.md는 도구 간 표준이지만, 동일한 역할을 범위 지정된 .mdc 파일로 수행하는 Cursor 고유 방식이 궁금하다면, 우리의 Cursor Rules 튜토리얼에서 파이썬 웹 프로젝트용 규칙 세트를 만드는 과정을 확인하세요.

GPT-5.5로 예산 추적 API 만들기

이 프로젝트는 개인 예산 항목을 추적하는 REST API입니다. 항목을 생성하고, 선택적 카테고리 필터와 함께 목록을 가져오고, 삭제하고, 월별 지출 요약을 조회할 수 있습니다. 

도메인 로직에 빠지지 않고 따라가기에는 충분히 단순하지만, 데이터베이스 계층, 입력 검증, 타입이 지정된 응답 모델, 여러 라우트 핸들러가 함께 동작하는 구현을 포함하므로 실제 다중 파일 세션에서 에이전트가 무엇을 하는지 보여주기에 충분합니다.

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초 정도 읽는 수고가 들지만, 한 번의 확인으로 수십 개 파일에 퍼지기 전 구조적 결정을 바로잡을 수 있습니다. 

추론을 High로 둔 GPT-5.6 Sol은 실제로 유용한 수준의 구체적인 계획을 제시합니다. 지금 구조를 검토하는 편이 나중에 재구성하는 것보다 훨씬 빠릅니다.

에이전트는 프로젝트 레이아웃을 제안하고, 한 파일도 작성하기 전에 승인을 기다립니다.

"좋습니다, 진행하세요"처럼 회신하면 에이전트가 빌드를 시작합니다. 왼쪽 파일 트리가 실시간으로 채워지는 것을 볼 수 있고, 하단 터미널에는 uv가 패키지를 설치하는 로그가 나타납니다.

에이전트는 스캐폴딩 과정에서 pyproject.toml을 생성했고, 편집기에는 새로 추가된 파일 내용이 표시됩니다.

스캐폴딩이 끝나면 다음으로 넘어가기 전에 app/models.py와 app/database.py를 잠깐 열어 보세요. BudgetEntry 모델에 최소한 id, amount, description, category, date 필드가 있는지, 그리고 database.py가 특별한 것 없이 async SQLite 엔진을 설정하는지 확인하세요. 

이상한 부분이 보이면 계속 진행하지 말고 다음 메시지에서 즉시 지적하세요. 이 단계에서의 수정은 저렴하지만, 스무 개 파일이 수정된 뒤에는 그렇지 않습니다.

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단계: 카테고리 검증 추가

세 번째 단계에서는 모델의 추론을 Low 또는 Medium으로 낮춰도 됩니다. enum 추가와 테스트 두 개는 자체 포함적이고 예측 가능해, 추가적인 숙고가 필요하지 않습니다. 

현재 API는 카테고리에 임의 문자열을 허용하므로, 데이터가 금방 일관성을 잃을 수 있습니다. 이를 고쳐 봅시다:

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에 대해 자동으로 검증하므로, 잘못된 카테고리는 라우트 핸들러가 실행되기 전 단계에서 거절됩니다.

이와 함께 테스트 두 개도 작성해야 합니다. 하나는 유효한 카테고리가 정상 저장되는지, 다른 하나는 유효하지 않은 카테고리에서 422가 반환되는지를 확인합니다.

@ 참조 사용하기

변경을 수락한 뒤, Cursor의 @ 컨텍스트 기능으로 빠르게 확인 질문을 해보세요:

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

@를 에이전트 패널에서 입력하면 파일 선택기가 열리며, app/models.py를 선택하면 해당 파일 내용이 직접 프롬프트에 포함되어, 에이전트가 파일을 찾거나 경로를 추정할 필요가 없습니다.

4단계: 월별 요약 엔드포인트 구축

여기서는 다시 High로 전환하세요. 집계 쿼리는 필터링, 그룹화, 응답 모델 설계를 함께 고려해야 하며, 그중 어느 하나라도 틀리면 세 파일을 다시 건드려야 합니다. 핵심 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.

이 작업은 단순 전체 조회가 아닌 필터링된 집계 쿼리를 요구하므로 데이터베이스 측면에서 더 흥미롭습니다. 에이전트가 database.py에서 쿼리를 어떻게 구성하는지 주의 깊게 보세요. 원시 SQL이 아니라 SQLModel의 쿼리 인터페이스를 사용해야 하며, 결과는 models.py에서 정의한 응답 모델에 깔끔히 매핑되어야 합니다.

변경을 수락한 뒤, 이 엔드포인트에 대한 테스트를 test_entries.py에 직접 하나 작성해 보세요. 특정 월에 두 개의 항목을 만들고, 그 월의 요약 엔드포인트를 호출해 합계를 검증합니다. 이 테스트를 에이전트에 맡기지 않고 직접 작성해 보면 테스트 클라이언트와 픽스처 구조에 익숙해지는 데 도움이 됩니다.

test_entries.py 파일에는 에이전트가 작성한 카테고리 검증 테스트와 수동으로 작성한 test_monthly_summary 함수가 함께 보입니다. 

5단계: 검증 루프 실행

Low 또는 Medium 추론이면 충분합니다. 테스트 실행과 린트 수정은 반응형 작업으로, 에이전트는 오류 출력을 읽고 표적 수정을 적용할 뿐 구조적 결정을 하지는 않습니다. 테스트를 에이전트에 맡기세요:

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 출력이 에이전트 패널에 스트리밍되는 모습을 지켜보세요. 

실패가 발생하면, 에이전트는 트레이스백을 읽고 문제가 생긴 파일을 파악한 뒤 수정을 적용합니다. 이 모든 과정이 하나의 세션 안에서 이루어집니다. 오류를 복사해 새 메시지로 붙여넣을 필요가 없습니다. 디버깅과 수정 루프가 하나의 연속 스레드 안에서 진행됩니다.

스크린샷은 전체 검증 루프를 마친 후 에이전트의 보고입니다. 이 경우 ruff 체크는 로컬 머신의 pyenv/.python-version 불일치 때문에 인터프리터 해석 문제가 발생했으며, 코드 자체의 문제는 아니었습니다. 

여기서 일어난 일을 주목할 만합니다. 에이전트가 코드와 무관한 환경 문제를 만나자, 원인을 추론하고 추가 지시 없이 우회책을 찾았습니다. 이런 도구 실패까지 맥락으로 풀어내는 문제 해결 능력은 GPT-5.6 Sol이 이전 모델을 앞서는 지점입니다.

또한 검증 프롬프트마다 "테스트를 통과시키기 위해 어설션을 변경하지 말라"는 문구를 포함시키는 것이 좋습니다. 이 지시가 없으면, 가끔 에이전트가 실제 동작을 고치기보다 테스트의 검증을 약화시키는 쉬운 길을 택하기도 합니다.

6단계: 코드 리뷰 패스

이 단계는 보내기 전에 추론을 다시 High로, 혹은 Extra High/Max로 올리세요. 단일 High 패스가 스쳐 지나갈 수 있는 에지 케이스까지 꼼꼼히 살피게 하려면 시간이 필요합니다. 이 단계에서 얕은 추론은 잘못된 안도감을 줍니다. 패턴 매칭으로 표면만 훑지 않고 잠재 이슈를 실제로 점검하게 해야 합니다. 

프로젝트를 마무리하기 전, 에이전트에게 리뷰를 요청하세요:

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을 거치지 않고 데이터베이스에 닿는 곳은 없음을 확인했습니다.

목록을 검토한 뒤, 수정 적용을 지시하세요:

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.

7단계: README와 CI 워크플로

프로젝트를 제대로 마무리하는 두 가지 마침표입니다. 둘 다 모델의 추론을 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.

일곱 단계를 마치면 프로젝트 구조는 다음과 같습니다:

마무리

이번에 만든 것은 작은 API지만, 워크플로 자체는 어떤 규모로도 확장 가능합니다. 

AGENTS.md를 에이전트가 단 하나의 파일이라도 건드리기 전에 준비해 두세요. 비사소한 작업에는 실행 전에 계획을 요청하세요. 프롬프트를 단계별로 나누어 한 번에 거대한 diff를 검토하기보다 자연스러운 체크포인트를 만드세요. 특정 파일에 대해 정밀한 질문이 필요하면 @filename을 사용하세요. 그리고 완료로 간주하기 전에 리뷰 패스를 돌리세요. 거의 항상 무언가를 더 잡아냅니다.

Cursor의 GPT-5.6 Sol은 긴 세션에서도 작업에 충실하고, 파일 간 불일치를 잡아내며, 파괴적일 수 있는 작업에서는 돌진하기보다 잠시 멈추고 확인할 때가 언제인지 더 잘 압니다. 하지만 모델은 전체의 일부일 뿐입니다. 사전에 제공하는 맥락, 검증 루프, 마지막 리뷰 패스에서 결과 품질이 크게 좌우됩니다.

추론 레벨에 대한 경험칙: 아키텍처 결정, 다중 파일 조정, 원인이 분명하지 않은 디버깅에는 High를, 문서화, 보일러플레이트, 단일 파일에서 단순 타이핑을 대신시키는 작업에는 Medium 또는 Low를 사용하세요. 코드 리뷰처럼 실수가 비싼 작업에는 Extra High나 Max를 고려하세요.