AI 어시스턴트가 구식 FastAPI 코드를 작성하는 것을 막는 12가지 Cursor 규칙

AI 코딩 어시스턴트는 여전히 몇 년 전의 FastAPI 패턴을 사용합니다: .dict(), orm_mode, session.query(), 서비스 코드 깊은 곳에서 발생한 HTTPException, 테스트에서의 SQLite 등. 코드는 작동하지만, 오늘날 작성할 코드가 아닙니다.

Cursor의 프로젝트 규칙이 이 문제 대부분을 해결해 줍니다. 규칙(rule)이란 .cursor/rules/ 디렉터리에 있는 작은 .mdc 파일이며, glob 패턴을 사용하여 일치하는 파일을 편집할 때만 로드됩니다:

---
description: "FastAPI 라우터, 의존성 및 Pydantic v2 스키마"
globs: src/app/**/router.py,src/app/**/schemas.py,src/app/**/deps.py
...

이것들이 저에게 가장 큰 차이를 만든 12가지 컨벤션입니다.

라우터 및 스키마

1. Pydantic v2 API만 사용. model_validate, model_dump, ConfigDict, field_validator를 사용합니다. 절대 .dict(), parse_obj, orm_mode, class Config 또는 v1의 @validator 데코레이터를 사용하지 마세요.

2. 라우터는 얇고 비동기(async)여야 합니다. 파싱하고, 서비스 함수를 호출하며, 스키마를 반환합니다. 라우터에는 SQL이나 비즈니스 규칙이 없어야 합니다.

3. 항상 response_model (또는 반환 주석)과 명시적인 status_code (생성 시 201, 삭제 시 204)를 선언해야 합니다.

4. 스키마는 이름이 XCreate / XUpdate / XRead여야 합니다. 입력 모델은 ConfigDict(extra="forbid")을 사용하여 은밀한 `

5. 서비스는 HTTPException 대신 자체 AppError 서브클래스를 발생시키세요. 하나의 예외 핸들러가 이를 {"error": {"code": ..., "message": ...}}로 매핑합니다.

6. 설정은 pydantic-settings 기반의 캐시된 get_settings()를 통해서만 하세요. 다른 곳에서 절대로 os.environ을 읽지 말고, 비밀값은 SecretStr로 유지하세요.

7. f-string으로 SQL을 절대 구성하지 마세요. 바운드 파라미터(bound parameters)나 text(...).bindparams()를 사용하세요.

테스트

1. **pytest + pytest-asyncio + httpx.AsyncClient(transport=ASGITransport(app=app))**를 사용하여 실제 Postgres에 대해 테스트하고, 테스트마다 롤백을 수행하세요. 각 테스트 후에는 app.dependency_overrides를 지우세요. SQLite 대체재는 사용하지 마세요.

사용하기

이러한 규칙들을 .cursor/rules/ 디렉토리에, 영역별로 하나의 파일씩, 레이아웃과 일치하는 glob을 사용하여 넣어주세요. Claude Code의 경우, 레포지토리 루트에 있는 짧은 CLAUDE.md와 동일한 관례를 따릅니다.

공개 고지: 저는 이러한 규칙들을 7개의 스코프가 지정된 .mdc 파일과 CLAUDE.md로 작성하여 FastAPI 규칙 패키지를 만들었고, codebaserules.com에서 $12에 판매하고 있습니다. 두 개의 파일은 이메일 주소 필요 없이 무료 다운로드입니다. 위에 언급된 모든 것은 아무것도 구매하지 않고도 작동합니다. 여러분이 이 중 무엇을 변경할지 듣고 싶습니다.