AI 코딩 실무 가드레일

핵심 원칙

AI가 코드를 쓰는 시대에도 좋은 개발 습관이 성패를 가른다. 습관이 잡힌 팀에서 AI는 능력을 키우고, 그렇지 않은 팀에서는 혼란을 키운다. Claude는 백과사전급 지식을 가졌지만 우리 시스템·사용자·비즈니스는 전혀 모르는 인턴이다. 설계자는 여전히 사람이다.

AI와 일하는 자세는 세 가지다.

자세	사람의 역할	어울리는 일
초안 작성자(First-Drafter)	구조와 설계	보일러플레이트, CRUD, 정형 패턴
페어 프로그래머	함께 아이디어를 다듬는다	대부분의 개발
검증자(Validator)	내가 쓴 코드를 검토받는다	버그·개선점 찾기

규모에 따른 세 가지 모드

모드	언제	방식
1. 놀이터	주말 실험, 개인 스크립트, PoC	AI가 80–90%를 쓴다. 빠르지만 프로덕션에는 절대 쓰지 않는다
2. 페어 프로그래밍	5,000줄 안팎, 실사용자가 있는 사이드 프로젝트, 잘 나뉜 작은 서비스	CLAUDE.md + 앵커 주석으로 구조를 준다
3. 프로덕션·모노레포	큰 코드베이스, 버그가 돈·평판으로 이어지는 시스템	경계마다 명시적 문서. 큰 기능을 통째로 맡기지 말고 서비스·모듈 단위로 나눠 맡긴다

인프라: CLAUDE.md와 앵커 주석

CLAUDE.md는 코드베이스의 헌법

Claude가 대화를 시작할 때 자동으로 읽는 파일이다. 매일 신입에게 프로젝트를 설명하는 대신 온보딩 문서를 한 번 읽히는 것과 같다. 업데이트에 쓴 1분이 나중의 정리 1시간을 아낀다.

섹션	내용 예
황금률	구현 세부가 확실하지 않으면 항상 개발자에게 묻는다
프로젝트 맥락	무엇을 만드는 서비스인가
핵심 아키텍처 결정	왜 Temporal인가, 왜 PostgreSQL + pgvector인가: 결정과 이유
코드 스타일·패턴	포맷터, import 정렬, 따를 패턴
도메인 용어집	Task는 Celery 태스크가 아니라 워크플로 정의, 헷갈리는 용어를 못 박는다
하지 말 것	테스트·API 계약·마이그레이션 수정 금지, 비밀값 커밋 금지, 비즈니스 로직 추측 금지

정기적으로 Claude에게 최근 변경을 훑어 CLAUDE.md에 맥락을 보태게 한다. 파일은 200줄 안쪽으로 짧게 두고, 특정 경로에만 해당하는 규칙은 .claude/rules/로 나눈다.

앵커 주석: 코드 속 표지판

CLAUDE.md만으로는 큰 코드베이스에서 국소적으로 나쁜 결정을 막지 못한다. 그래서 코드 안에 AI와 사람이 함께 읽는 주석을 둔다.

# AIDEV-NOTE: Critical performance path - this serves 100k req/sec
# DO NOT add database queries here
def get_user_feed(user_id: UUID, cached_data: FeedCache) -> List[FeedItem]:
    items = cached_data.items[:]  # 캐시 원본을 바꾸지 않는다
 
    # AIDEV-TODO: Implement pagination (ticket: FEED-123)
 
    # AIDEV-QUESTION: Why filter private items here instead of in cache?
    # AIDEV-ANSWER: Privacy rules can change between cache updates
    return [item for item in items if user_has_access(user_id, item)]

규칙	이유
접두어는 `AIDEV-NOTE` / `AIDEV-TODO` / `AIDEV-QUESTION`	`grep`으로 바로 찾는다
120자 이내	짧아야 읽힌다
파일을 훑기 전에 관련 폴더의 앵커부터 찾는다	맥락을 먼저 얻는다
코드를 고치면 앵커도 고친다	낡은 안내는 해롭다
사람 지시 없이 `AIDEV-NOTE`를 지우지 않는다	이유가 있어서 둔 것이다
복잡하거나, 중요하거나, 헷갈리거나, 버그가 의심되는 곳에 단다	필요한 곳에만

API 계약처럼 바꾸면 운영 중인 클라이언트가 깨지는 경계에는 "응답 모양은 신성하다", "변경 시 버전 업과 마이그레이션 계획 필요" 같은 앵커를 꼭 단다. 없으면 Claude는 기꺼이 API를 "개선"한다.

테스트는 사람이 쓴다

가드레일 가운데 가장 중요한 원칙이다. 테스트는 실행 가능한 명세다. 의도, 엣지 케이스, 도메인 이해가 담긴다. AI가 쓴 테스트는 "코드가 해야 할 일"이 아니라 "코드가 하는 일"을 확인할 뿐이다.

예: AI가 rate limiter와 테스트를 함께 만들면 둘 다 그럴듯하지만, 한 번 요청하고 다시 오지 않는 사용자의 기록이 메모리에 영원히 남는 누수 같은 문제를 테스트가 짚지 못하기 쉽다. 같은 모델이 정상 경로만 확인하기 때문이다.

영역	AI가 해도 되는 것	AI가 하면 안 되는 것
구현	비즈니스 로직 생성	테스트 파일 수정
테스트 계획	시나리오 제안	테스트 코드 작성
디버깅	실패 원인 분석	기대값 수정

규칙으로 굳히려면 AI가 테스트 파일을 건드린 PR은 예외 없이 반려한다. Claude Code라면 테스트 경로에 대한 쓰기를 권한 규칙이나 hook으로 막을 수 있다.

맥락과 세션 관리

맥락을 아끼면 더 비싸다

"유저 엔드포인트에 캐시 추가해 줘"만 주면 Claude는 서버가 여러 대인데 인메모리 캐시를 쓰고, 무효화·지표·캐시 스탬피드를 빠뜨린다. 결국 서너 번 더 고치느라 토큰을 몇 배 쓴다. 처음부터 맥락을 준다.

GET /users/{id}에 Redis 캐시 추가.
- 분당 5만 요청, API 서버 12대 + 로드 밸런서
- 유저 데이터는 하루 몇 번만 바뀜
- Redis는 cache.redis.internal:6379, 키 패턴 "user:v1:{id}"
- Prometheus로 hit/miss 지표
- cache-aside, TTL 1시간, 확률적 조기 만료로 스탬피드 방지
- 참고: docs/patterns/caching.md

"집중된 프롬프트"는 최소한이 아니라 관련 있고 빠짐없는 프롬프트다.

작업 하나에 세션 하나

긴 대화 하나를 계속 쓰면 앞의 맥락이 엉뚱하게 스며든다. 프론트엔드 스타일 얘기를 하던 세션으로 DB 마이그레이션을 하지 않는다. 작업이 끝나면 새 세션을 연다(Claude Code에서는 /clear).

Git 워크플로

큰 코드베이스에서는 git worktree로 AI 실험 공간을 분리하고(Claude Code는 claude --worktree <이름>), 잘된 커밋만 메인으로 가져온다.
AI가 도운 커밋에 표시를 단다. 리뷰어가 더 주의해서 보고, 나중에 디버깅할 사람이 출처를 안다. 숨기지 않고 책임 있게 쓰는 문화가 목적이다.

태그	뜻
`[AI]`	절반 이상 AI가 생성
`[AI-minor]`	절반 미만
`[AI-review]`	리뷰에만 사용

큰 리팩터링: 왜는 사람이, 어떻게는 AI가

대규모 반복 변경은 사람이 SPEC.md에 원칙과 형식을 정하고, 범위와 순서("auth 모듈부터, 구현 전에 계획을 보여 달라")를 정해 맡긴다. 예를 들어 에러 처리 통일이라면 분류 체계(4xx·5xx 계층), 응답 형식, 에러 코드 원칙은 사람이 정하고, 수백 곳의 raise Exception(...) 교체는 AI가 맡는다.

AI가 건드리면 안 되는 것

영역	이유
테스트 파일	사람의 의도와 도메인 지식이 담긴 명세
DB 마이그레이션	운영에서 되돌릴 수 없다. 데이터 패턴·배포 시점·롤백 전략이 필요하다
보안 핵심 코드 (인증·토큰 검증)	한 줄씩 보안 검토를 거친 경계
버전 없는 API 계약	깨면 모든 클라이언트가 깨진다. AI는 모바일 앱 출시 주기를 모른다
설정과 비밀값, 기능 플래그	하드코딩 금지, 플래그는 제품 결정

AI 실수의 등급

등급	예	대응
1. 귀찮지만 무해	포맷, 장황한 코드, 덜 최적인 알고리즘	린터·리팩터링·프로파일링이 잡는다
2. 고치기 비쌈	내부 API 깨기, 팀 패턴 바꾸기, 불필요한 의존성	리뷰와 CLAUDE.md 규칙
3. 경력을 위협	테스트를 고쳐 통과시키기, API 계약 깨기, 비밀값·개인정보 유출, 마이그레이션 손상	접근 자체를 막는다

가드레일의 강도는 실수 등급에 비례시킨다.

정리

AI는 지렛대일 뿐이고 방향은 사람이 정한다. "왜"는 사람이, "어떻게"는 AI가 맡는다.
맥락은 CLAUDE.md(전역)와 앵커 주석(국소)으로 문서화해 둔다. 사람에게도 그대로 문서다.
테스트·마이그레이션·보안·API 계약·비밀값은 AI 손이 닿지 않게 한다.
프롬프트에는 맥락을 아끼지 말고, 작업마다 새 세션을 연다.
실수의 비용에 맞춰 가드레일을 세운다.

버그 제보