Claude Code 활용 팁

Claude Code는 단순한 자동완성 도구가 아니다. 잘 쓰면 설계 파트너가 되고, 잘못 쓰면 설명하기 어려운 코드 덩어리를 생성하는 기계가 된다. 이 챕터에서는 AI/ML 엔지니어 관점에서 Claude Code를 실무에 녹이는 핵심 패턴을 다룬다.

프롬프트 구조: 배경 + 목표 + 제약 + 산출물

모든 효과적인 프롬프트는 네 가지 요소를 담는다.

요소	역할	예시
배경(Context)	지금 무엇을 만들고 있는지	”FastAPI + SQLite 기반 Todo API를 개발 중이다”
목표(Goal)	이번에 원하는 결과	”할 일 항목에 우선순위 필드를 추가하고 싶다”
제약(Constraint)	건드리면 안 되는 것, 지켜야 할 것	”기존 Alembic 마이그레이션을 깨지 말 것, Pydantic v2 사용”
산출물(Output)	원하는 결과물의 형식	”마이그레이션 파일, 스키마 수정, 라우터 변경까지 diff 형태로”

이 구조를 지키면 Claude Code가 불필요한 추론을 줄이고 정확한 범위로 작업한다.

좋은 프롬프트 vs 나쁜 프롬프트

예시 1 — 기능 추가

나쁜 프롬프트:

우선순위 기능 추가해줘

좋은 프롬프트:

배경: FastAPI + SQLAlchemy ORM으로 구현된 Todo 앱(models.py, routers/todos.py)이 있다.
목표: Todo 항목에 priority 필드(low/medium/high enum)를 추가한다.
제약:
  - 기존 Alembic 마이그레이션 파일은 수정하지 말고 새 revision을 생성할 것
  - Pydantic v2 모델(TodoCreate, TodoUpdate)도 함께 수정할 것
  - GET /todos 에 ?priority=high 쿼리 필터를 추가할 것
산출물: 변경되는 파일 목록과 각 파일의 diff, 실행할 alembic 명령어

예시 2 — 버그 수정

나쁜 프롬프트:

CORS 에러가 난다 고쳐줘

좋은 프롬프트:

배경: FastAPI 앱이 포트 8000에서 실행되고, React 앱은 포트 5173(Vite dev server)에서 실행된다.
목표: 개발 환경에서 프론트엔드가 백엔드 API를 호출할 때 CORS 에러를 없앤다.
제약:
  - 프로덕션(nginx 통합 배포)에서는 CORS 설정이 필요 없으므로, 환경변수로 분기할 것
  - allow_credentials=True가 필요하다 (JWT 쿠키 사용 예정)
산출물: main.py의 CORSMiddleware 설정 코드와 .env.development 예시

예시 3 — 코드 이해

나쁜 프롬프트:

이 코드 설명해줘

좋은 프롬프트:

배경: 아래 코드는 SQLAlchemy async session을 FastAPI dependency로 주입하는 패턴이다.
목표: 이 패턴이 왜 필요한지, contextvar 기반 스코핑이 어떻게 동작하는지 이해하고 싶다.
제약: 초급자가 아닌 Python async에 익숙한 ML 엔지니어 대상으로 설명할 것
산출물: 동작 원리를 단계별로, 그리고 이 패턴을 쓰지 않으면 생기는 문제 설명
[코드 붙여넣기]

Review Loop 패턴

코드를 생성한 뒤 같은 컨텍스트에서 리뷰를 요청하면 일관된 피드백을 얻는다.

# 1단계: 구현 요청
위의 프롬프트 구조로 기능 구현을 요청한다.

# 2단계: 같은 세션에서 리뷰 요청
방금 작성한 코드에서 다음 관점으로 문제를 찾아줘:
1. N+1 쿼리 문제
2. 에러 핸들링 누락
3. Pydantic 모델과 DB 모델 간 불일치
개선이 필요한 부분만 bullet point로 나열하고, 각각 수정 코드를 제시해줘.

Review loop의 핵심은 같은 컨텍스트 유지다. 세션을 끊으면 Claude Code가 코드의 의도를 재추론해야 하므로 정확도가 떨어진다.

TDD 스타일 요청

테스트를 먼저 작성하게 시키면 구현 범위가 명확해진다.

배경: FastAPI의 POST /todos 엔드포인트를 구현하려 한다.
목표: pytest + httpx를 사용한 integration test를 먼저 작성해줘.
제약:
  - 테스트는 실제 SQLite in-memory DB를 사용할 것 (mock 금지)
  - 성공 케이스, 유효성 검사 실패, DB 에러 케이스를 포함할 것
산출물: tests/test_todos.py 파일 전체

테스트가 완성되면, 이 테스트를 통과하는 최소한의 구현 코드를 작성해줘.

이 방식은 ML 파이프라인에서 단위 테스트를 먼저 정의하는 것과 같은 원리다. 테스트가 스펙 문서 역할을 한다.

보안 취약점 리뷰 요청

배경: 아래는 사용자 로그인을 처리하는 FastAPI 라우터 코드다.
목표: OWASP Top 10 기준으로 보안 취약점을 찾아줘.
제약: 각 취약점마다 (1) 취약점 이름, (2) 해당 코드 라인, (3) 공격 시나리오, (4) 수정 코드를 제시할 것
산출물: 심각도(Critical/High/Medium/Low) 순으로 정렬된 리포트
[코드 붙여넣기]

보안 리뷰에서 특히 유용한 점은 Claude Code가 SQL Injection, 인증 우회, 비밀번호 평문 저장 같은 패턴 기반 취약점을 빠르게 탐지한다는 것이다. 단, 비즈니스 로직에 특화된 취약점은 직접 확인해야 한다.

실무 팁 요약

• 컨텍스트를 파일로 제공하라 — 코드를 텍스트로 붙이는 것보다 @파일명 또는 파일 첨부가 더 정확하다.
• 한 번에 하나씩 — 여러 기능을 동시에 요청하면 Claude Code가 범위를 넓게 잡는다. 작은 단위로 쪼개라.
• “하지 말 것”을 명시하라 — 제약 조건에 “기존 테스트를 깨지 말 것”, “타입 힌트를 제거하지 말 것” 같은 네거티브 요구사항을 넣으면 불필요한 리팩토링을 막는다.
• 결과를 검증하라 — Claude Code가 생성한 코드는 반드시 직접 실행하고 테스트한다. 특히 마이그레이션 코드, 보안 관련 코드는 더 꼼꼼히 확인해야 한다.

핵심 정리

• 프롬프트는 배경 + 목표 + 제약 + 산출물 구조로 작성하면 결과 정확도가 크게 올라간다.
• Review loop — 구현 직후 같은 세션에서 리뷰를 요청해 N+1, 에러 처리, 모델 불일치를 잡는다.
• TDD 스타일 — 테스트를 먼저 작성하게 하면 구현 범위가 명확해지고 회귀 방지 코드가 자동으로 생긴다.
• 보안 리뷰 — OWASP Top 10 기준으로 요청하면 패턴 기반 취약점을 빠르게 발견할 수 있다.
• Claude Code는 도구다. 결과는 항상 직접 실행하고 검증해야 한다.