AI 생성 코드의 불일치를 방지하는 FastAPI용 CLAUDE.md 작성법

Stack, Router Design, Dependency Injection, Prohibitions 섹션을 포함한 FastAPI용 CLAUDE.md를 작성하세요. 50줄 이내로 유지하세요. 코드 스니펫과 함께 긍정적인 패턴을 사용하세요. 리포지토리 루트(repo root)에 배치하세요. 변경 사항은 IaC(Infrastructure as Code)로서 팀 리뷰를 거치세요.

핵심 요약 (Key Takeaways)

• Stack, Router Design, Dependency Injection, Prohibitions 섹션을 포함한 FastAPI용 CLAUDE.md를 작성하세요.
• 50줄 이내로 유지하세요.
• 코드 스니펫과 함께 긍정적인 패턴을 사용하세요.
• 변경 사항은 IaC로서 팀 리뷰를 거치세요.

변경 사항 — 구체적인 업데이트

Claude Code를 사용하는 FastAPI 개발자들은 오랫동안 좌절스러운 문제에 직면해 왔습니다. AI 에이전트가 일관되지 않은 구조, 제각각인 의존성 주입 (Dependency Injection) 패턴, 그리고 흩어진 에러 핸들링 (Error Handling)을 가진 엔드포인트를 생성한다는 점입니다. 해결책은 새로운 모델 업데이트가 아니라, 잘 만들어진 CLAUDE.md 파일입니다.

이 글은 커뮤니티의 실제 사용 패턴을 기반으로, FastAPI 프로젝트를 위해 프로덕션에서 테스트된 CLAUDE.md 템플릿을 제공합니다. 이 파일은 Claude Code를 위한 시스템 프롬프트 (System Prompt) 역할을 하며, 전체 리포지토리에 걸쳐 일관된 코드 생성을 강제합니다.

사용자에게 주는 의미

CLAUDE.md가 없으면, Claude Code는 세션마다 달라지는 FastAPI 코드를 생성합니다. 어떤 엔드포인트는 SessionLocal()을 사용하고, 다른 엔드포인트는 Depends(get_db)를 사용합니다. 어떤 라우트 (Route)는 response_model을 사용하지만, 다른 것은 사용하지 않습니다. 이러한 불일치는 기술 부채 (Technical Debt)와 리뷰 오버헤드를 발생시킵니다.

적절하게 구조화된 CLAUDE.md가 있으면, Claude Code는 매번 팀의 컨벤션 (Convention)을 따르는 코드를 생성합니다. 에이전트는 프로젝트 루트에 있는 파일을 읽고 이를 지속적인 지침으로 취급합니다.

주요 이점:

• 일관된 라우터 패턴 (Consistent router patterns): 모든 엔드포인트가 APIRouter(prefix="/v1/xxx", tags=["xxx"])를 사용합니다.
• 균일한 의존성 주입 (Uniform dependency injection): 모든 DB 세션이 Annotated[AsyncSession, Depends(get_db)]를 사용합니다.
• 표준화된 에러 핸들링 (Standardized error handling): 비즈니스 에러가 HTTPException(status_code=422, ...) 형식을 따릅니다.
• 전역 상태 없음 (No global state): 전역적으로 db = SessionLocal()을 사용하는 것을 금지합니다.

지금 바로 시도해보세요 — FastAPI CLAUDE.md 템플릿

저장소 루트(root)에 다음 내용을 포함하는 CLAUDE.md 파일을 생성하세요:

# Project Rules

## Stack
...

프로 팁 (Pro tip): 이 파일은 50행 미만으로 유지하세요. Claude Code의 컨텍스트 윈도우 (context window)는 유한합니다. 규칙이 너무 많으면 에이전트 (agent)가 이를 건너뛸 수 있습니다. 가장 영향력이 큰 패턴을 우선순위에 두세요.

멀티 툴 전략 (Multi-Tool Strategy)

팀에서 Cursor나 OpenAI Codex를 함께 사용한다면, CLAUDE.md를 단일 진실 공급원 (source of truth)으로 유지하고 심볼릭 링크 (symlink)를 생성하세요:

ln -s CLAUDE.md .cursorrules

이렇게 하면 여러 도구에 걸쳐 하나의 정전 (canonical) 규칙 세트를 유지할 수 있습니다. Cursor는 루트 디렉토리의 .cursorrules만 읽지만, Claude Code는 하위 디렉토리의 계층적 CLAUDE.md 파일을 지원합니다.

효과적인 CLAUDE.md를 위한 두 가지 핵심 규칙

1. 금지 사항이 아닌 긍정적인 패턴을 작성하세요

   • 나쁜 예: "print()를 사용하지 마세요"
   • 좋은 예: "디버깅을 위해 logger.info()를 사용하세요"
   • 에이전트는 "하지 마라"는 지침보다 "이렇게 하라"는 지침을 더 안정적으로 따릅니다.

2. 구체적인 코드 스니펫 (code snippets)을 포함하세요

   • "의존성 주입 (dependency injection)을 사용하세요" 대신 Annotated[AsyncSession, Depends(get_db)]를 보여주세요.
   • 스니펫은 에이전트의 생성 결과가 귀하의 정확한 구문 (syntax)에 고정되도록 합니다.

팀 워크플로우 (Team Workflow)

CLAUDE.md를 코드로서의 인프라 (infrastructure-as-code)로 취급하세요. 변경 사항은 Dockerfile이나 docker-compose.yml과 마찬가지로 PR (Pull Request) 리뷰를 거쳐야 합니다. 이를 통해 팀은 다음을 수행할 수 있습니다:

• 에이전트의 동작이 어떻게 변할지 검토
• 모순 발견 (예: 한 규칙은 비동기 (async)를 말하고, 다른 규칙은 동기 (sync)를 암시하는 경우)
• 특정 패턴이 선택된 이유를 문서화

결과

이 CLAUDE.md를 구현한 후, 한 개발자는 Claude Code가 20개 이상의 파일에서 동일한 구조로 엔드포인트 (endpoints)를 생성하여 "모든 엔드포인트가 제각각이다"라는 문제를 해결했다고 보고했습니다. 에이전트는 별도의 프롬프트 (prompt) 없이도 의존성 주입 (dependency injection) 패턴, 응답 모델 (response model) 선언, 그리고 에러 핸들링 (error handling) 형식을 일관되게 적용했습니다.

FastAPI의 관례 중심적 (convention-heavy) 설계는 규칙 파일 기반 개발 (rule-file-driven development)에 특히 적합합니다. 프레임워크는 이미 특정 패턴을 기대하고 있으며, CLAUDE.md는 AI가 이를 일관되게 적용하도록 보장할 뿐입니다.

출처: dev.to

원래 게시된 곳: gentic.news