AI 코딩 에이전트와 DRF 실무 - CLAUDE.md와 가이드라인 프롬프트 활용 노하우

작년부터 업무에서 Claude Code 같은 코딩 에이전트를 붙여서 쓰고 있습니다.

처음에는 "코드 좀 짜주는 자동완성의 연장" 정도로 생각했는데, 지금은 프로젝트 맥락을 어떻게 주입하느냐에 따라 결과물의 품질이 완전히 달라진다는 것을 체감하고 있습니다.

같은 도구를 쓰는데도 어떤 요청은 리뷰 없이 못쓸 코드가 나오고, 어떤 요청은 바로 PR에 올릴만한 코드가 나옵니다. 그 차이의 대부분은 모델 성능이 아니라 컨텍스트 관리에 있었습니다.

이 글에서는 DRF 프로젝트 기준으로 CLAUDE.md 작성법과 가이드라인 프롬프트 운영 노하우를 기록합니다.

1. CLAUDE.md는 에이전트의 온보딩 문서다
2. DRF 가이드라인 프롬프트
3. 실무에서 자리잡은 사용 패턴
4. 운영 규칙
참고 자료

1. CLAUDE.md는 에이전트의 온보딩 문서다

Claude Code는 세션을 시작할때 프로젝트 루트의 CLAUDE.md를 자동으로 읽습니다.

이 파일을 어떻게 생각하느냐가 활용도를 가릅니다. 저는 "신규 입사자가 첫 주에 물어볼 것들을 미리 적어둔 온보딩 문서"라고 생각하고 관리합니다.

실제로 운영중인 CLAUDE.md의 뼈대를 일반화하면 이렇습니다.

# my-service

## 중요 지침
- 모든 출력과 코드 주석은 한글로 작성합니다.
- 항상 제안을 먼저 하고, 사용자의 확인을 받은 뒤 실행하세요.

## 프로젝트 개요
서비스의 메인 백엔드 API 서버. Django + DRF 기반.

## 주요 앱 구조
- payment: 결제 및 트랜잭션
- reservation: 수업 및 예약 관리
- notification: 알림 시스템

## API 엔드포인트 prefix
/api/admin/    - 관리자 전용
/api/member/   - 회원용
/api/partner/  - 파트너용

## 테스트
python manage.py test apps.payment --keepdb

## 코딩 규칙
### Serializer
- 프로젝트 공통 DefaultSerializer 상속
- 비즈니스 로직은 services.py로 분리
### ViewSet
- 권한 클래스 명시적 지정
- queryset 최적화 (select_related, prefetch_related) 필수

## 주의사항
- 마이그레이션 파일은 반드시 리뷰 후 커밋
- API 변경 시 하위 호환성 유지

작성하면서 정리된 기준 몇가지입니다.

첫번째, 자주 틀리는 것 위주로 적습니다. 에이전트가 이미 잘하는 일반론(REST 원칙 같은)을 적는건 지면 낭비이고, "우리 프로젝트만의 규칙"(엔드포인트 prefix 체계, 공통 베이스 클래스, 앱 구조)을 적어야 효과가 있습니다.

두번째, 무한정 길게 쓰지 않습니다. 문서가 길어질수록 개별 규칙의 무게가 희석됩니다. 저는 200줄 안쪽을 유지하려고 합니다. 상세한 내용은 별도 문서로 빼고 CLAUDE.md에서는 참조만 겁니다.

세번째, "제안 먼저, 실행은 확인 후" 같은 행동 지침을 최상단에 둡니다. 에이전트가 마음대로 파일을 수정하며 달려나가는 것을 막는 안전장치인데, 체감상 가장 효과가 좋았던 한 줄입니다.

2. DRF 가이드라인 프롬프트

CLAUDE.md가 프로젝트 전반의 컨텍스트라면, API를 생성시킬때는 DRF 코드 스타일을 강제하는 가이드라인을 함께 줍니다.

반복적으로 쓰는 가이드라인을 파일로 만들어두고 재사용하는 방식입니다.

# DRF API 작성 가이드라인

## ViewSet
- ModelViewSet 대신 필요한 mixin만 조합해서 사용
- get_queryset()에서 반드시 요청 유저 기준 스코프 필터링
- N+1이 발생하지 않도록 select_related/prefetch_related 적용
- 목록 API는 페이지네이션 필수

## Serializer
- 응답 전용/요청 전용 Serializer를 분리
- SerializerMethodField 안에서 쿼리 호출 금지
  (필요한 데이터는 View에서 annotate 하거나 context로 전달)

## 에러 처리
- 도메인 에러코드 체계(DOMAIN_0000) 사용
- 커스텀 예외는 CustomAPIException 사용

## 테스트
- 생성한 API마다 정상/권한없음/유효성실패 3가지 케이스 테스트 작성

이 가이드라인의 내용은 사실 사람에게 하는 코드리뷰 코멘트를 모아둔 것과 같습니다.

실제로 효과가 컸던 항목은 "SerializerMethodField 안에서 쿼리 호출 금지"입니다. 에이전트가 만드는 DRF 코드의 단골 문제가 Serializer 안에서의 N+1인데, 이 한 줄이 있고 없고의 코드 품질 차이가 명확했습니다.

가이드라인이 없으면 "동작하는 코드"가 나오고, 가이드라인이 있으면 "우리 팀 스타일의 코드"가 나옵니다.

3. 실무에서 자리잡은 사용 패턴

몇달 써보면서 잘 맡기게 된 일과 안 맡기는 일이 자연스럽게 나뉘었습니다.

잘 맡기는 일들입니다.

레거시 코드 분석. 수백줄짜리 결제 생성 로직의 분기 흐름을 단계별로 요약시키는 것으로 시작하는데, 사람이 읽으면 반나절 걸릴 코드의 지도를 몇분만에 받을 수 있습니다. 분석 결과는 검증하며 읽어야 하지만, 출발점으로서의 가치가 큽니다.
정형화된 CRUD/어드민 API 생성. 위의 가이드라인 프롬프트와 함께 맡기면 리뷰에서 고칠게 별로 없는 수준으로 나옵니다.
회귀 테스트 초안. 버그를 고친 뒤 "이 수정에 대한 회귀 테스트를 작성해줘"는 이제 습관이 되었습니다.
일괄 변경 작업의 사전 계획. 여러 파일에 걸친 rename이나 마이그레이션 전에 대상 목록과 순서를 뽑게 합니다.

반대로 안 맡기는 일들입니다.

도메인 정책 판단 (환불 정책, 결제 검증 조건 같은 것)
스키마/아키텍처 설계 결정. 제안은 받아도 결정은 사람이 합니다.
마이그레이션과 배포의 실행. 계획까지만 시키고 실행은 직접 합니다.

경계선의 기준은 단순합니다. 틀렸을때 되돌리기 어려운 일은 맡기지 않습니다.

4. 운영 규칙

팀에서 에이전트를 쓰면서 자리잡은 규칙들도 짧게 남깁니다.

에이전트가 만든 코드도 전부 동일한 리뷰를 거칩니다. "AI가 짰으니까"는 리뷰를 건너뛸 이유도, 더 깐깐하게 볼 이유도 아닙니다. diff는 diff입니다.
CLAUDE.md도 코드처럼 관리합니다. 프로젝트 구조가 바뀌었는데 문서가 옛날 것이면, 에이전트는 잘못된 컨텍스트로 그럴듯한 코드를 대량생산합니다. 이게 가장 위험한 상태입니다.
자격증명이나 시크릿은 CLAUDE.md에 넣지 않습니다. 이 파일은 레포에 커밋되는 문서라는 것을 잊으면 안됩니다.

도구를 "시키면 해주는 것"이 아니라 "온보딩시켜야 하는 팀원"으로 대하면서부터 생산성이 달라졌습니다.

온보딩 문서(CLAUDE.md)를 만들고, 코드리뷰 기준(가이드라인)을 전달하고, 권한의 경계(맡기는 일/안 맡기는 일)를 정하는 것. 결국 사람 팀원에게 하는 것과 똑같은 일이었습니다.

1. CLAUDE.md는 에이전트의 온보딩 문서다

2. DRF 가이드라인 프롬프트

3. 실무에서 자리잡은 사용 패턴

4. 운영 규칙

참고 자료