우리가 클로드(Claude)로 코드를 배포하며 얻은 교훈들 ①
본문은 요즘IT와 번역가 Jane Heo가 함께 디완크 토머(Diwank Tomer)의 글 <Field Notes From Shipping Real Code With Claude>을 번역한 글입니다. 필자인 디완크 토머는 인공지능 분야에서 혁신적인 시스템과 도구를 구축하는 창업자이자 AI 엔지니어입니다. 현재 ‘Julep AI’의 공동 창업자로 지속적인 메모리를 갖춘 AI 에이전트 인프라 구축하고 있습니다. 이 글은 AI 도구를 개발 프로세스에 효과적으로 통합하고자 하는 개발자들에게 실질적인 가이드라인을 제공하며, AI와의 협업을 통해 생산성과 코드 품질을 동시에 향상시키는 방법을 탐색하는 데 유용한 정보를 제공합니다. *원문이 길어 1, 2편으로 나누어 발행했으니 참고 부탁드립니다.
필자에게 허락을 받고 번역했으며, 글에 포함된 링크는 원문에 따라 표시했습니다. 글에 포함된 각주(*표시)는 ‘번역자주’입니다. (원문에는 필자의 오디오 파일이 포함되어 있으니 필요하신 분들은 참고 바랍니다.)
바이브 코딩(Vibe Coding)은 단순한 ‘분위기’가 아니다.
이 글에서 배우게 될 것
먼저 단순한 마법이 아닌 의도적인 실천을 통해 AI의 강점을 극대화하고, 약점을 보완함으로써 실질적인 10배 생산성 향상을 어떻게 달성할 수 있는지 살펴보겠습니다. 그다음에는 클로드(Claude)의 도움을 받아 우리가 *줄렙(Julep)에서 실제 프로덕션 코드를 매일 배포하는 데 사용하는 인프라를 소개하겠습니다. 여기에는 우리의 CLAUDE.md 템플릿, 커밋 전략, 그리고 다양한 안전장치들이 포함됩니다.
*줄렙(Julep): AI가 만든 오픈소스 서버리스 플랫폼으로, 복잡한 AI 워크플로우와 에이전트를 손쉽게 구축·운영하도록 돕습니다.
그리고 무엇보다도, 테스트 코드를 직접 작성하는 일이 왜 지금도 (오히려 지금이기 때문에 더) 절대적으로 중요한지에 대해 이야기할 겁니다. 이 하나의 원칙만 잘 지켜도, 수많은 심야 디버깅 지옥에서 벗어날 수 있습니다.
핵심 인사이트: 좋은 개발 관행은 단순한 선택 사항이 아닙니다. 그것은 AI가 당신의 역량을 증폭시키느냐, 아니면 혼란을 증폭시키느냐를 가르는 결정적인 요소입니다. 연구 결과도 이를 뒷받침합니다. 엄격한 개발 관행을 따르는 팀은 배포 빈도가 46배 높고, 커밋에서 배포까지 걸리는 시간은 440배 더 빠릅니다. 이러한 효과는 유능한 AI 도우미를 함께 사용할 때 훨씬 더 두드러지게 나타납니다.
이 글이 존재하는 이유: 밈에서 방법론으로
처음 이 모든 일이 시작된 때로 돌아가 보겠습니다. Andrej Karpathy(안드레이 카르파시)가 "바이브 코딩(vibe-coding)"에 대해 트윗을 했죠. AI가 코드를 대신 작성하고 개발자는 그저 분위기를 즐기는다는 개념이었습니다. 개발자 커뮤니티는 이 얘기를 듣고 크게 웃었어요. 커피를 마시며 앉아 있고, 기계가 알아서 코딩해 준다는 건 궁극의 개발자 판타지처럼 들렸으니까요.
그러다 앤트로픽(Anthropic)이 Sonnet 3.7과 Claude Code를 출시했고, 예상치 못한 일이 벌어졌습니다. 그 농담이 더 이상 웃기지 않게 되었어요. 왜냐하면… 현실이 되어가기 시작했기 때문이죠. 물론, 그 이전부터 커서(Cursor) 같은 도구는 있었지만, 이번엔 진짜 바이브 코딩(vibe-coding)처럼 느껴지는 인터페이스가 나타난 겁니다.
우리는 줄렙(Julep)에서 *AI 워크플로우 오케스트레이션을 구축합니다. 우리 백엔드는 수년에 걸쳐 누적된 수많은 결정과 패턴, 그리고 때때로 쌓인 기술 부채로 이루어져 있죠. 우리는 코드 품질을 높게 유지하고, 충분한 문서화를 통해 이를 지키려 최선을 다해 왔습니다. 하지만 이 코드베이스의 방대한 크기와 역사적인 맥락은 숙련된 엔지니어조차 이해하는 데 몇 주가 걸립니다.
*AI 워크플로우 오케스트레이션: 데이터 수집, 모델 호출, 후처리, 결과 저장 등 AI가 수행해야 할 여러 단계들의 실행 순서와 조건, 재시도, 병렬화 등을 관리·조율해 자동화하는 것을 뜻합니다.
이런 상황에서 클로드(Claude)를 쓸 때 적절한 가이드레일 없이 접근하면, 지나치게 열정적인 인턴과 두더지 잡기 게임을 하는 것과 다를 바 없습니다.
바이브 코딩(Vibe-Coding) 이해하기
스티브 예기(Steve Yegge)는 약간 극적인 제목의 글 “주니어 개발자의 종말(The Death of the Junior Developer)”에서 CHOP(Chat-Oriented Programming)이라는 용어를 탁월하게 만들어냈습니다. 이건 허세 없이, 정확하게 클로드(Claude)와 함께 코딩할 때의 경험을 딱 잘라 설명한 말이죠.
전통적인 코딩은 대리석 조각에 비유할 수 있습니다. 처음엔 텅 빈 블록에서 시작해 한 줄 한 줄, 함수 하나하나를 조심스럽게 깎아 나갑니다. 모든 스트로크는 신중하며, 모든 결정은 전적으로 당신의 몫이죠. 만족스럽지만 느립니다.
바이브 코딩(Vibe-coding)은 오케스트라 지휘와 더 비슷합니다. 당신이 직접 악기를 연주하지는 않지만, 전체를 이끌고, 형태를 잡고, 방향을 제시합니다. AI는 원재료로서의 음악적 재능을 제공하지만, 당신의 비전이 없다면 그건 그저 소음에 불과합니다.
바이브 코딩(vibe-coding)에는 개발 주기의 단계에 따라 선택할 수 있는 세 가지 뚜렷한 태도(posture)가 있습니다.
1. AI를 초안 작성자(First-Drafter)로 활용하기
AI가 초기 구현을 생성하고, 당신은 아키텍처와 설계에 집중합니다. 생각의 속도로 타이핑할 수 있지만 끊임없는 피드백이 필요한 유능한 주니어 개발자처럼 행동하죠. 보일러플레이트 코드, CRUD 작업, 표준 패턴에 특히 적합합니다.
2. AI를 페어 프로그래머(Pair-Programmer)로 활용하기
대부분의 개발 상황에서 이상적인 접근입니다. 아이디어를 주고받으며 적극적으로 협업하죠. AI가 접근법을 제안하면, 당신이 그것을 다듬습니다. 당신이 밑그림을 그리면, AI가 디테일을 채워 넣습니다. 모든 프로그래밍 책을 다 읽었지만 실제 제품은 만들어본 적 없는 개발자와 함께하는 페어 프로그래밍 같죠.
3. AI를 검토자(Validator)로 활용하기
때론 코드를 직접 작성하고 현실 점검(sanity check)이 필요할 때가 있습니다. AI는 버그를 찾아내고, 개선점을 제안하며, 당신이 놓쳤을 패턴을 짚어줍니다. 절대 지치거나 까칠해지지 않는 코드 리뷰어라고 생각하세요.
이처럼 모든 줄을 직접 쓰는 대신, 리뷰하고, 다듬고, 이끌어가는 역할을 하게 됩니다. 하지만 이건 아무리 강조해도 부족하지 않아요. 당신이 여전히 설계자(architect)입니다. 클로드(Claude)는 백과사전 수준의 지식을 가진 인턴일 뿐, 당신의 시스템, 사용자, 비즈니스 로직에 대한 맥락은 전혀 모릅니다.
바이브 코딩(Vibe-Coding)의 세 가지 모드: 실용적 프레임워크
몇 달간의 실험과 꽤 여러 번의 프로덕션 사고 끝에, 저는 세 가지 명확한 작업 모드를 정리하게 되었습니다. 각 모드에는 고유한 리듬, 가드레일, 그리고 적합한 사용 사례가 있습니다.
모드 1: Playground
언제 사용하나: 주말 해킹, 개인 스크립트, 프로토타입, 혹은 “이거 되나?” 싶은 실험용 아이디어
Playground에서는 혼돈을 받아들입니다. 클로드(Claude)가 전체 코드의 80~90%를 작성하고, 당신은 최소한의 방향만 제시하죠. 자유롭고, 약간은 무서울 정도입니다.
- 프로 팁: claude-composer를 사용하면 YOLO 모드로 즐길 수 있어요.
- 예시: Spotify 사용 기록을 분석하는 스크립트를 만들고 싶다고 해봅시다. 클로드(Claude)를 열고 자연어로 원하는 기능을 설명하면, 완성된 솔루션을 뚝딱 만들어줍니다. CLAUDE.md도 없고, 프롬프트도 정제하지 않습니다. 그냥 날 것의 AI 코드가 쏟아지죠.
Playground의 장점은 속도입니다. 아이디어에서 작동하는 프로토타입까지 몇 분이면 가능합니다. 하지만 이건 그냥 카우보이 코딩이고, 중요한 시스템엔 절대 쓰면 안 됩니다. 아무리 대단한 사람들이 “괜찮다”라고 말해도, 좋은 엔지니어링 원칙은 여전히 중요하고, 지금은 오히려 더 중요합니다.
모드 2: 페어 프로그래밍
언제 사용하나: 5,000줄 이하의 프로젝트, 사용자 있는 사이드 프로젝트, 망가지면 곤란한 데모, 대규모 시스템 안의 소규모 서비스.
바로 이 모드부터 바이브 코딩(vibe-coding)의 진가가 발휘되기 시작합니다. 어느 정도의 구조는 필요하지만, 속도를 저해할 만큼 과해선 안 됩니다. 여기서 핵심적인 혁신은 CLAUDE.md 파일입니다. 클로드(Claude)가 호출될 때 자동으로 읽는 맞춤형 문서죠. (출처: 앤트로픽(Anthropic)의 Claude Code 모범 사례)
CLAUDE.md는 클로드(Claude)가 대화를 시작할 때 자동으로 맥락에 불러오는 특별한 파일입니다.
- 자주 쓰는 bash 명령어
- 핵심 유틸 함수 및 파일
- 코드 스타일 가이드
- 테스트 지침
- 저장소 사용 규칙 (예: 브랜치 이름 지정, 머지 vs 리베이스 방식 등)
- Claude가 기억했으면 하는 기타 정보
프로젝트의 규칙을 매번 설명하는 대신, 한 번 문서화해두면 됩니다. 다음은 최근에 진행한 사이드 프로젝트에서 실제로 사용한 예시입니다.
## 프로젝트: Analytics Dashboard
이 프로젝트는 사용자 분석 데이터를 시각화하기 위한 Next.js 대시보드입니다.
### 아키텍처
- 기본은 Server Components, 필요할 때만 Client 사용
- tRPC로 타입 안정성 보장된 API 호출
- Prisma 사용, select 명시
- Tailwind 사용 (커스텀 CSS 금지)
### 코드 스타일
- Prettier 사용, 줄 길이 100자
- simple-import-sort로 import 정렬
- 컴포넌트는 PascalCase, 테스트와 같은 위치
- 훅은 항상 'use'로 시작
### 패턴
- 데이터 fetch는 Server Components에서
- Client Components는 props로 데이터 받기
- 외부 데이터는 Zod 스키마로 검증
- 모든 데이터 표시 컴포넌트에 Error boundary 적용
### 하지 말 것
- useEffect로 데이터 fetch 금지
- 명시적 승인 없이 글로벌 상태 생성 금지
- TypeScript에서 'any' 사용 금지
이런 맥락이 갖춰지면 클로드(Claude)는 놀라울 만큼 효과적입니다. 마치 매일 신규 입사자에게 프로젝트를 일일이 설명하는 것과, 한 번 온보딩 문서를 읽게 하는 것의 차이와 같습니다.
하지만 페어 프로그래밍 모드(Pair Programming Mode)는 단순한 문서화만으로는 충분하지 않습니다. AI를 효과적으로 안내하려면, 제가 ‘앵커 코멘트(anchor comments)’라 부르는 주석을 달아야 합니다. 이 주석은 클로드(Claude)가 길을 잃지 않도록 돕는 이정표 역할을 합니다.
// AIDEV-NOTE: 이 컴포넌트는 성능을 위해 가상 스크롤을 사용함
// 참고: https://tanstack.com/virtual/latest
// 일반 map으로 바꾸지 마세요. 1만 개 이상의 항목을 처리합니다
export function DataTable({ items }: DataTableProps) {
// 클로드(Claude)야, 수정 시 가상 스크롤링 유지해야 해
...
}
이러한 주석은 두 가지 역할을 합니다: AI에게는 작업 방향을 안내하고, 인간에게는 코드에 대한 문서를 제공합니다. 즉, AI와 사람 모두에게 유익한 문서화 방식인 셈입니다. 이러한 “앵커 코멘트(anchor comments)”와 일반 주석의 핵심적인 차이점은 다음과 같습니다. 이 주석들은 클로드(Claude)가 직접 읽고, 활용할 수 있도록 작성되고 유지되는 것입니다. 다음은 실제 프로젝트의 CLAUDE.md에 포함된 예시입니다.
## 앵커 코멘트
코드베이스 전반에 걸쳐, 필요에 따라 특정 형식의 주석을 추가하세요. 이 주석은 본인에게 도움이 되는 인라인 지식으로, grep 등으로 쉽게 검색 가능해야 합니다.
### 작성 지침:
AI와 개발자 모두를 대상으로 할 경우, AIDEV-NOTE:, AIDEV-TODO:, AIDEV-QUESTION: 와 같이 대문자 접두어를 사용하세요.
주석은 간결하게 (120자 이내) 작성하세요.
중요: 파일을 스캔하기 전에, 먼저 관련 하위 디렉토리 내의 기존 앵커(AIDEV-*)가 있는지 확인하세요.
관련 코드를 수정할 경우, 반드시 해당 앵커 주석도 업데이트해야 합니다.
명시적인 사람의 지시 없이 AIDEV-NOTE는 삭제하지 마세요.
예시:
# AIDEV-NOTE: 성능에 민감한 경로입니다. 불필요한 메모리 할당을 피하세요. (ADR-24 문서 참고)
async def render_feed(...):
...
모드 3: 프로덕션/모노레포 규모
언제 사용하나: 대규모 코드베이스, 실제 사용자 있는 시스템, 버그가 돈이나 평판으로 이어지는 경우.
Claude는 엄청난 양의 코드를 생성할 수 있지만, 복잡한 시스템에 통합하는 건 완전히 다른 문제입니다.
먼저 중요한 전제부터 말씀드리겠습니다. 이 정도 규모에서의바이브 코딩(vibe-coding)은 아직 그다지 잘 확장되지 않습니다. 물론 이런 시스템들이 대형 코드베이스를 다루는 데 점점 더 능숙해지고 있다는 것은 분명히 느낍니다. 하지만 효과적으로 작동하게 만들려면, AI가 길을 잃지 않고 안전하게 코드를 이해하고 수정할 수 있도록 상당한 수준의 구조화와 지원이 필요합니다. 일반적으로는, 가능한 경우 시스템을 개별 서비스나 하위 모듈(submodule) 단위로 분리하는 것이 더 낫습니다.
보편적인 원칙으로서, 대규모 프로젝트에는 바이브 코딩(vibe-coding) 여부와 상관없이 좋은 엔지니어링 관행이 반드시 적용되어야 합니다. 예를 들어, 프로덕션 규모에 이르면 경계(boundary)가 매우 중요해집니다. 모든 통합 지점에는 명확한 문서화가 필요합니다.
# AIDEV-NOTE: API 계약 경계 - v2.3.1
# 모든 변경 사항은 버전 업과 마이그레이션 플랜이 필요함
# 참조: docs/api-versioning.md
@router.get("/users/{user_id}/feed")
async def get_user_feed(user_id: UUID) -> FeedResponse:
# 클로드(Claude): 이 응답 구조는 매우 중요함
# 변경 시 실제 앱이 깨짐
…
이러한 명확한 경계가 없으면, 클로드(Claude)는 아무렇지 않게 API를 “개선”하려 들고, 결국 프로덕션에 있는 모든 클라이언트를 망가뜨릴 수 있습니다. 결론적으로, 대규모 프로젝트에서도 바이브 코딩(vibe-coding)을 부분적으로 도입하는 것은 확실히 가치가 있습니다. 또한, 그 경험을 개선할 수 있는 적절한 방법론과 구조화도 함께 도입해야 합니다. 하지만, 아직은 대규모 기능을 안정적으로 완성할 수 있을 거라고 기대하진 마세요. (2025년 6월 7일 기준 / AI 시대)
인프라스트럭처: 지속 가능한 AI 개발의 기반
CLAUDE.md: 단 하나의 진실의 원천(Single Source of Truth)
이 점은 반드시 분명히 하고 넘어가고 싶습니다. CLAUDE.md는 선택 사항이 아닙니다. 이 파일을 업데이트하는 데 1분을 쓰는 것이, 나중에 정리 작업에서 1시간을 아껴줍니다.
CLAUDE.md를 당신의 코드베이스를 위한 헌법이라고 생각하세요. 이 문서는 코드가 어떻게 작성되어야 하는지, 시스템이 어떻게 상호작용하는지, 어떤 패턴을 따라야 하고 피해야 하는지를 정의하는 기본적인 법률을 설정합니다. 조직이 팀의 역량과 기술을 개발하는 데 투자할수록 더 나은 결과를 얻습니다. 그리고 CLAUDE.md는 그러한 투자가 문서화되어 구체화된 형태입니다.
다음은 수천 건의 AI 보조 커밋을 통해 다듬어진, 우리가 사용하는 프로덕션 CLAUDE.md의 요약 버전입니다.
# CLAUDE.md – 줄렙(Julep) 백엔드 서비스
## 황금률 (The Golden Rule)
구현 세부사항이 확실하지 않다면, 항상 개발자에게 물어볼 것.
## 프로젝트 컨텍스트
줄렙(Julep)은 개발자가 선언형 워크플로우를 사용하여 상태를 가지는 AI 에이전트를 구축할 수 있게 해줍니다.
## 중요한 아키텍처 결정들
### 왜 *템퍼럴(Temporal)인가?
우리는 **워크플로우 오케스트레이션에 템퍼럴(Temporal)을 사용합니다. 그 이유는 다음과 같습니다.
워크플로우가 며칠 또는 몇 주 동안 완벽한 신뢰성으로 실행될 수 있음
어떤 실패 지점에서도 자동 복구가 가능함
*워크플로우 오케스트레이션 플랫폼입니다.
**여러 시스템·서비스 전반에 걸친 자동화된 작업들을 ‘조율’하고 ‘관리’하는 관행입니다.
### 왜 *포스트그레스큐엘(PostgreSQL) + **피지벡터(pgvector)인가?
워크플로우 상태를 위한 ***ACID 준수 (사용자 데이터를 잃지 않기 위함)
에이전트 메모리를 위한 벡터 유사도 검색 기능
*오픈소스 객체-관계형 데이터베이스 관리 시스템(ORDBMS)입니다.
**PostgreSQL용 확장(extension)으로, 벡터(수치 배열)를 저장하고 유사도 검색(Nearest Neighbor Search)을 할 수 있게 해줍니다.
***데이터베이스 트랜잭션의 신뢰성과 일관성을 보장하는 네 가지 핵심 속성(원자성(Atomicity), 일관성(Consistency), 고립성(Isolation), 지속성(Durability))입니다.
### 왜 *타입스펙(TypeSpec)인가?
API 정의를 위한 단일 진실의 원천:
OpenAPI 스펙
TypeScript/Python 클라이언트
검증 스키마들
*텐서플로우(TensorFlow)에서 함수의 입력·출력으로 주고받는 객체의 메타데이터를 정의하는 추상 클래스입니다.
## 코드 스타일 및 패턴
### 앵커 코멘트 (Anchor comments)
코드베이스 전반에 걸쳐 적절한 위치에, 개인적인 인라인 지식으로 사용할 수 있도록 특정 형식의 주석을 추가하세요. 이 주석들은 쉽게 grep으로 검색될 수 있어야 합니다.
### 가이드라인:
AIDEV-NOTE:, AIDEV-TODO:, AIDEV-QUESTION: 와 같은 대문자 접두어를 사용하세요 (AI 및 개발자 대상)
중요: 파일을 스캔하기 전에 항상 먼저 관련 하위 디렉토리에서 기존의 AIDEV-* 앵커를 찾으세요
관련 코드를 수정할 경우, 해당 앵커도 반드시 업데이트하세요
명시적인 사람의 지시 없이 AIDEV-NOTE를 삭제하지 마세요
아래 경우 중 하나라도 해당된다면 앵커 주석을 반드시 추가하세요.
*코드가 너무 복잡한 경우
*매우 중요한 코드인 경우
*혼란을 일으킬 수 있는 코드인 경우
*버그가 있을 수 있는 코드인 경우
## 도메인 용어 사전 (Claude, 반드시 학습할 것!)
Agent: 메모리, 도구, 정의된 동작을 가진 AI 개체
Task: 여러 단계로 구성된 워크플로우 정의 (Celery 태스크가 아님)
Execution: 하나의 Task가 실행되고 있는 인스턴스
Tool: 에이전트가 호출할 수 있는 기능 (브라우저, API 등)
Session: 메모리를 포함하는 대화 컨텍스트
Entry: 하나의 세션 내에서의 개별 상호작용
## AI가 절대로 해서는 안 되는 일들
테스트 파일을 절대 수정하지 말 것 – 테스트는 인간의 의도를 담고 있음
API 계약을 절대 변경하지 말 것 – 실제 앱이 깨질 수 있음
마이그레이션 파일을 절대 변경하지 말 것 – 데이터 손실 위험
비밀 정보를 절대 커밋하지 말 것 – 환경 변수를 사용할 것
비즈니스 로직을 추측하지 말 것 – 반드시 질문할 것
AIDEV- 주석을 절대 삭제하지 말 것 – 이유가 있어서 존재하는 것임
기억하세요: 우리는 영리함보다는 유지보수 가능성을 최우선으로 합니다.
의심스러울 땐, 지루해 보이더라도 안전한 해결책을 택하세요.
이 문서는 당신과 클로드(Claude) 사이에 공유된 맥락을 제공합니다. 마치 시니어 개발자가 클로드(Claude)에게 코딩 내내 귓속말로 조언을 해주는 것과 같습니다.
앵커 코멘트(Anchor Comments): 대규모 코드베이스를 위한 Breadcrumbs
코드베이스가 커질수록, 단순히 CLAUDE.md만으로는 부족합니다. 인라인 가이던스, 즉 내가 말하는 앵커 코멘트가 필요합니다. 이 주석들은 AI가 로컬(해당 위치)에서 잘못된 결정을 내리지 않도록 도와주는 지역 맥락 역할을 합니다.
코드베이스를 하나의 도시라고 생각해보세요. 앵커 코멘트는 그 도시 안의 도로 표지판 같은 존재입니다. 그것 없이는 아무리 똑똑한 방문객이라도 길을 잃게 됩니다. 우리는 다음과 같은 방식으로 효과적으로 앵커 코멘트를 사용합니다.
# AIDEV-NOTE: 중요한 성능 경로 – 이 함수는 초당 10만 요청을 처리함
# 여기서 데이터베이스 쿼리를 추가하지 말 것
def get_user_feed(user_id: UUID, cached_data: FeedCache) -> List[FeedItem]:
# 캐시된 데이터를 변경하지 않도록 주의할 것
items = cached_data.items[:]
# AIDEV-TODO: 페이지네이션 구현 필요 (티켓: FEED-123)
# 무한 스크롤을 위한 커서 기반 페이지네이션이 필요함
# AIDEV-QUESTION: 왜 여기서 private 항목을 필터링하지? 캐시에서 하면 안 돼?
# AIDEV-ANSWER: 히스토리 배경: 캐시 업데이트 사이에 프라이버시 규칙이 변경될 수 있음
filtered = [item for item in items if user_has_access(user_id, item)]
return filtered
이러한 코멘트들은 단순히 코드가 무엇을 하는지를 넘어서, 왜 그렇게 구현되어 있는지를 AI와 인간 모두가 이해할 수 있도록 돕는 내러티브(맥락 스토리)를 만들어 줍니다.
AI 개발을 위한 Git 워크플로우
AI 기반 개발에서 가장 과소평가되는 부분 중 하나는 바로 Git 워크플로우가 어떻게 바뀌는가입니다. 이제 코드를 생성하는 속도가 훨씬 빨라졌기 때문에, 주의하지 않으면 git 히스토리가 오염되기 쉬워집니다. 이 전략은 매우 큰 코드베이스에 해당하는 이야기이며, 아주 단순한 도구는 아니지만 저는 git worktree를 사용하여 AI 실험을 위한 격리된 환경을 만드는 것을 추천합니다.
# 메인 브랜치를 오염시키지 않고 AI 실험 공간 만들기
git worktree add ../ai-experiments/cool-feature -b ai/cool-feature
# 클로드(Claude)를 격리된 환경에서 자유롭게 실험하게 하기
cd ../ai-experiments/cool-feature
# ... 여러 번의 실험적 커밋들 ...
# 잘된 부분만 메인 브랜치로 가져오기
cd ../main-repo
git cherry-pick abc123 # 잘 작동한 커밋만 골라서 가져옴
# 실험 끝났으면 정리
git worktree remove ../ai-experiments/cool-feature
이 방식은 두 가지 장점을 모두 누릴 수 있는 방법입니다. 클로드(Claude)는 자유롭게 실험할 수 있고, 메인 브랜치의 Git 히스토리는 깔끔하고 의미 있게 유지됩니다.
커밋 메시지의 경우, 우리는 AI가 생성한 커밋임을 명확히 하기 위해 아래와 같은 표준 태깅 방식을 사용합니다.
feat: implement user feed caching [AI]
- 사용자 피드에 대한 Redis 기반 캐시 추가
- 사용자 로그인 시 캐시 예열 기능 구현
- 캐시 히트율 측정용 메트릭 추가
AI-assisted: 핵심 로직은 AI가 생성, 테스트는 사람이 작성
이러한 투명성은 코드 리뷰에서 매우 중요합니다. 리뷰어는 AI가 작성한 부분에 더 집중해서 검토할 수 있게 되기 때문입니다.
*다음 내용은 ‘우리가 클로드(Claude)로 코드를 배포하며 얻은 교훈들 ②’로 이어집니다.
<참고>
<추천 도서>
- Peter Senge – The Fifth Discipline (2010)
- “Beyond the 70 %: Maximising the Human 30 % of AI-Assisted Coding” (2025년 3월 13일) – Addy Osmani
- Mark Richards & Neal Ford – Fundamentals of Software Architecture, 2판 (2025)
- Nicole Forsgren, Jez Humble, Gene Kim – Accelerate: The Science of Lean Software and DevOps
<원문>
Field Notes From Shipping Real Code With Claude
©위 번역글의 원 저작권은 Diwank Tomer에게 있으며, 저작권법의 보호를 받는 바, 무단 전재와 복사, 배포 등을 금합니다
