클로드로 실제 코드를 배포하며 느낀 실전 노트

• AI 도구인 Claude를 실제 서비스에 적용하며, 개발 생산성 10배 향상 효과의 현실적 달성 방법과 적용 노하우를 정리함
• ‘vibe-coding’은 단순 유행이 아닌 실질적 방법론으로, 올바른 개발 습관과 인프라를 갖추면 AI의 강점을 극대화하고 약점을 보완할 수 있음
• AI의 역할을 ‘초안 작성자’, ‘페어프로그래머’, ‘코드 검토자’ 세 가지 모드로 명확히 구분하며, 각 단계에 맞는 문서화와 가드레일이 필수임
• 핵심은 프로젝트마다 ‘CLAUDE.md’ 파일을 활용해 컨벤션, 아키텍처, 패턴, 금지사항 등을 명확히 문서화하고, 코드 내 ‘anchor comment’로 AI를 효과적으로 가이드하는 것
• 테스트 코드는 반드시 사람이 작성해야 하며, AI가 테스트·마이그레이션·보안·API 계약·시크릿 등 핵심 영역을 수정하지 못하도록 경계를 엄격히 설정해야 함
• 올바른 경계와 습관 아래서 AI 코딩을 도입한 팀은 배포 빈도·안정성·개발 속도 모두 대폭 개선할 수 있으며, 실제 운영 노하우와 패턴 공유가 AI 개발 문화의 핵심이 되고 있음

Vibe Coding Isn’t Just a Vibe

• 이 글은 AI를 활용한 새로운 소프트웨어 개발 방식의 현장 가이드로, 단순한 사용법이 아니라 실제로 효과적인 AI 개발의 '이유'까지 설명함
• 신화처럼 여겨진 10배 생산성 향상도, AI의 강점은 최대화하고 약점은 보완하는 실천적 습관을 통해서만 가능함을 실제 사례로 보여줌
• 실제 서비스 중인 Julep 코드베이스에서, CLAUDE.md 템플릿, 커밋 전략, 운영상 재난을 방지하는 가드레일 등 실전 인프라와 운영 노하우를 공개함
• 특히 테스트 코드는 반드시 직접 작성해야 하며, AI에게 과도하게 의존할 경우 심각한 장애와 디버깅 악몽을 초래할 수 있음
• AI 개발에는 세 가지 모드(초안 작성, 페어프로그래밍, 검토자) 가 존재하며, 상황에 따라 AI에 주도권을 주거나 인간이 직접 조정해야 하는 리듬과 원칙이 다름
• 핵심 메시지: 좋은 개발 습관과 경계가 있을 때만 AI가 역량을 증폭시키며, 실제 연구 결과도 "철저한 개발 습관을 가진 팀이 배포 속도, 품질 모두에서 압도적으로 앞선다"는 사실을 보여줌

왜 이 글을 쓰게 되었나: 밈(Meme)에서 실전 방법론(Method)으로

• AI에게 코드를 맡기고 개발자는 "바이브만 타는"다는 개념(‘vibe-coding’)은 원래 Andrej Karpathy의 농담 트윗에서 시작된 유행임
• 당시 개발자 커뮤니티는 “AI가 대신 일해주고 우리는 커피나 마신다”는 최고의 판타지로 여기며 웃어넘겼음
• 하지만 Anthropic의 Sonnet 3.7과 Claude Code 출시 이후, 이 농담이 실제로 가능한 현실로 바뀌기 시작함. 기존 Cursor 같은 도구도 있었지만, Claude Code는 진짜 '바이브 코딩' 느낌을 주기 시작함
• 필자가 몸담은 Julep은 방대한 코드베이스와 다양한 설계 패턴, 기술적 부채까지 안고 있음. 코드 품질과 문서화는 철저히 유지하지만, 각 파트의 의도와 히스토리를 파악하는 데만 수주가 걸릴 정도로 복잡함
• Claude를 guardrail 없이 쓰면, 과잉 열정의 인턴이 곳곳에서 실수를 저지르는 것과 같은 혼란이 발생
• 이 글은 그런 시행착오와 새벽 3시의 디버깅, 실제 서비스 운영에서 살아남은 진짜 실전 패턴과 노하우만을 정리해서 공유함

바이브 코딩(Vibe-Coding)의 본질

• Steve Yegge가 CHOP(Chat-Oriented Programming) 라는 용어를 만들었듯, ‘바이브 코딩’은 AI와 대화하며 코드를 완성하는 새로운 개발 방식임
• 전통적인 코딩이 대리석을 조각하듯 한 줄 한 줄 신중하게 만드는 작업이라면,
  • 바이브 코딩은 오케스트라의 지휘자에 가깝고, AI는 원석(기본 코드 능력)을 제공하는 연주자임
  • 개발자는 전체 방향성과 구조를 설계하고, AI가 그 흐름을 따라 코드로 풀어냄
• 바이브 코딩의 3가지 태도(Postures)
  • 1. AI를 초안 작성자로 활용 (First-Drafter)
    • 아키텍처·설계에 집중하며, 반복 작업(CRUD, 보일러플레이트 등)을 AI가 빠르게 생성
    • 생각하는 속도로 코드를 작성하는 주니어 엔지니어를 둔 느낌이지만, 지속적 가이드 필요
  • 2. AI와 페어프로그래밍 (Pair-Programmer)
    • 가장 실용적이며 효과적인 모드
    • 개발자와 AI가 아이디어를 주고받으며, 큰 틀은 사람이 그리고 세부 구현은 AI가 채움
    • 수많은 프로그래밍 지식은 있지만 실제 배포 경험이 없는 동료와 짝코딩하는 느낌
  • 3. AI를 검토자/코드 리뷰어로 활용 (Validator)
    • 사람이 작성한 코드를 AI가 검토, 버그·개선점·놓친 패턴을 제안
    • 언제나 피곤하지 않고 꼼꼼한 리뷰어 역할
• 핵심 통찰: 개발자는 ‘작가’에서 ‘편집자’로 역할이 전환됨. 모든 코드를 직접 작성하는 대신, AI가 만든 결과물을 검토·수정·방향 제시함.
• 단, 전체 아키텍처와 맥락은 인간이 반드시 직접 주도해야 하며, AI는 ‘백과사전적 지식의 인턴’일 뿐 우리 서비스·비즈니스의 맥락은 알지 못함

바이브 코딩 3가지 실전 모드: 프레임워크

수개월의 실험과 실제 배포 사고를 거쳐, 바이브 코딩에는 각기 다른 리듬과 가드레일, 최적의 용도가 있는 3가지 모드가 있음

• 모드 1: Playground (실험/프로토타입/개인 프로젝트)

  • 사용 시점: 주말 해킹, 개인 스크립트, PoC, 즉흥적 아이디어 테스트 등
  • 특징: 설계·문서·가드레일 없이, AI가 코드의 80~90%를 작성. 아이디어 → 결과물까지 몇 분 만에 도달하는 속도
  • 위험: 실서비스/중요 코드에는 부적합. 장난/실험용으로만 사용. 엔지니어링 원칙은 오히려 더 중요해짐

• 모드 2: Pair Programming (실사용·소규모 서비스)

  • 사용 시점: 5,000라인 이하 프로젝트, 실사용자 있는 사이드 프로젝트, 데모, 소규모 모듈 등
  • 핵심: 프로젝트의 관습·아키텍처·패턴·테스트 가이드 등을 CLAUDE.md로 한 번에 명확히 정의
  • 장점: 새 개발자 온보딩하듯, Claude에게 한 번만 설명하면 일관성 있게 코드 생성
  • 실전 포인트:
    • 코드 곳곳에 anchor comment(AIDEV-NOTE, AIDEV-TODO, AIDEV-QUESTION 등)로 Claude가 맥락을 잃지 않게 가이드
    • 이런 주석은 AI와 사람이 모두 참고할 수 있는 지침 역할, CLAUDE.md에 관리 기준과 예시까지 명시

• 모드 3: Production/Monorepo Scale (대규모 서비스)

  • 사용 시점: 수십~수백 명 개발, 실사용자 있는 대형 서비스, 한 번의 실수로 큰 피해 발생 가능한 상황
  • 주의: 현시점(2025년 6월) 기준, 대규모 일괄 바이브 코딩은 완벽하게 확장되지 않음
  • 원칙: 개별 서비스/서브모듈 단위로 바이브 코딩 도입 권장, 모든 통합지점(API·DB 등)에 명확한 경계와 버전 관리, 주요 인터페이스·API에 변경 주의 주석 필수
  • 실전 예시:
    • # AIDEV-NOTE: API Contract Boundary - v2.3.1
    • # Changes require version bump and migration plan
    • 이런 경계선이 없으면 Claude가 함부로 개선하다가 실제 서비스 전체를 깨뜨릴 수 있음
• 결론: 대규모 프로젝트는 바이브 코딩을 점진적으로, 분리된 서비스 단위로 도입하고, 반드시 문서화·가이드라인·리뷰 등 전통적 원칙을 병행해야 신뢰성 확보 가능

인프라 중심의 지속가능한 AI 개발 환경 만들기

• CLAUDE.md: AI와 사람 모두를 위한 단일 진실(The Single Source of Truth)

  • CLAUDE.md는 모든 프로젝트 규칙, 아키텍처, 주의사항, 코드스타일, 금지 대상, 도메인 용어집 등을 체계적으로 담는 ‘헌법’ 역할을 함
  • AI와 새로운 팀원이 공유할 ‘지식의 뼈대’로 기능, 예시와 함께 구체 가이드라인과 금지사항을 노동집약적으로 관리
  • 좋은 CLAUDE.md에 투자하는 팀일수록 더 나은 결과를 만들어냄
  • 우리의 프로덕션 CLAUDE.md 참고
  • 코드베이스가 커질수록 CLAUDE.md만으로는 부족하고, 각 코드 곳곳에 anchor comment(AIDEV-NOTE/TODO/QUESTION 등)로 로컬 컨텍스트를 명확히 전달해야 함
  • 코드베이스를 도시로 비유한다면 anchor comment는 AI와 사람이 모두 길을 잃지 않게 해주는 표지판
  • 이런 주석은 단순 코드 설명을 넘어, "왜" 이렇게 동작하는지의 스토리를 남김

• Git 워크플로우, AI 코드의 체계적 관리

  • AI 코드 생성 속도가 빨라질수록, 잘못 관리하면 git 히스토리가 오염될 수 있음
  • git worktree 방식 등으로 메인 브랜치에서 분리한 AI 실험 공간 마련해, 코드는 자유롭게 생성하되 기록은 체계적으로 구분/관리
    • how to use worktrees 및 wt 도구도 참조
  • 커밋 메시지엔 AI 관여 내역을 반드시 명시([AI] 태그 활용 등), 리뷰어가 추가로 주의 검토할 수 있도록 함

불문율: 테스트 코드는 반드시 사람이 작성

• AI 보조 개발에서 가장 중요한 원칙: "테스트 코드는 절대 AI에게 맡기지 말 것"
• 테스트는 단순히 동작 확인용 코드가 아님
  • 실제 문제 맥락, 엣지 케이스 인식, 사업적 요구 해석, 도메인에 대한 인간의 이해와 경험이 녹아든 실행 가능한 명세임
  • 속도와 안정성 모두 놓치지 않는 고수 팀은, 바로 이 테스트를 철저히 인간이 관리
• AI가 자동 생성한 테스트는 피상적 경로(happy path)만 검증하며, 예기치 않은 심각한 문제(예: 메모리릭 등)는 놓침
• 우리팀의 경우 AI가 테스트 파일을 건드리면 PR은 자동 반려 (예외 없음)
• 테스트는 코드의 명세이자 안전망, 누적된 모든 버그와 엣지케이스의 지혜
• 반드시 사람의 손으로 작성하고, AI가 만질 수 없도록 강력하게 보호해야 함

확장과 맥락관리: 토큰 경제와 컨텍스트 최적화

• AI 코드 개발에서 흔히 저지르는 실수:
  "토큰 절약"을 위해 맥락(프롬프트, 요구사항, 환경 등)을 최소화하면 오히려 반복 작업이 늘고 전체 토큰 소비가 증가함
• 적절한 맥락 제공이 장기적으로 더 효율적
  • "최소"가 아니라 "관련성 있고 충분한 맥락" 을 미리 주는 것이 핵심
• 나쁜 예시: 맥락 부족 프롬프트 "Add caching to the user endpoint"
  • Claude는 단순 인메모리 캐싱, 무효화 전략/모니터링 없음, 멀티 서버 고려 없음, 캐시 스탬피드 무대책
  • 결과적으로 3번 이상 반복 수정을 거쳐, 총 4배 이상의 토큰이 소모됨
• 좋은 예시: 맥락이 풍부한 프롬프트 Add Redis caching to the GET /users/{id} endpoint. Context: * 엔드포인트 트래픽 5만 req/분, 12대 API 서버, 데이터 변동 적음 * 기존 Redis 인프라 위치, 표준 키 패턴, Prometheus 기반 메트릭 요구 * 캐시 어사이드 패턴, TTL 1시간, 캐시 스탬피드 방지(확률적 조기 만료) * 캐싱 가이드 문서 참조
  • 처음부터 구체적 맥락을 제공해, 반복 없는 정확한 구현 가능
• 결론:
  • "토큰은 좋은 도구에 투자하는 셈"
  • 미리 맥락을 충분히 넣으면, 장기적으로 반복과 수정이 줄어 비용이 절약됨
• 실전 팁: 모든 프로젝트는 코드 변경 시마다 Claude에게 코드베이스 변화와 관련 맥락을 CLAUDE.md에 갱신하도록 요청

세션 관리와 맥락 오염 방지

• 작업별로 Claude 세션을 새로 시작하는 것이 중요
  • 하나의 긴 대화에 여러 작업(예: DB 마이그레이션, 프론트엔드 디자인 등)을 혼합하면 컨텍스트가 섞여 의도하지 않은 결과 초래
• 규칙: 한 작업 = 한 세션, 완료 시 세션 새로 시작
  • Claude의 '멘탈 모델'을 항상 깨끗하고 집중된 상태로 유지
  • 마치 생닭과 야채용 도마를 구분해서 쓰는 것처럼 맥락을 분리

실전 사례: 에러 처리 구조 전환

• 실제로 500+ 엔드포인트에서의 ad-hoc 에러 처리방식을 구조화된 에러 계층(hierarchy) 으로 대체한 사례 소개
• 사람(아키텍트)이 사전에 핵심 설계(SPEC.md/요구사항/에러 분류)를 작성하고, Claude가 실제 코드 대량변환(기계적 작업)의 실행자 역할을 맡는 방식
• 아키텍처 원칙과 구체적 명세, 설계문서 예시/개념 도출 -> AI에 명확한 작업 지시 -> 정확 4시간 내 전체 리팩터링 완료 경험

AI 시대의 리더십과 조직문화

• 시니어 엔지니어의 역할은 직접 코드 작성에서, 지식 큐레이션·경계 설정·AI/사람 모두를 가이드하는 일로 진화
• 린(Lean) 매니지먼트, 지속적 배포 등 현대 개발 문화가 AI 협업 관리에도 그대로 중요함

• 신규 입사자 온보딩 체크리스트(인간 + AI 협업 분리)

  • 1주차: 기본기 다지기
    • 팀의 CLAUDE.md(공통/서비스별) 읽기
    • 개발 환경 세팅
    • 첫 PR 제출(100% 직접 코딩, AI 금지)
  • 2주차: AI 협업 실습
    • Claude에 팀 템플릿 적용, 설정
    • '장난감 문제'를 AI와 함께 풀기
    • 프롬프트 패턴 연습
    • AI 보조 첫 PR(멘토/시니어와 함께)
  • 3주차: 독립적 실무
    • AI 보조로 주요 기능 개발 및 배포
    • 동료의 AI 코드에 대해 직접 테스트 작성
    • 코드리뷰 세션 1회 주도

투명한 문화 구축하기 : AI 활용의 적극적 공개

• 모든 AI 활용 커밋에는 아래와 같이 커밋 메시지 태그로 명확히 표시 feat: add Redis caching to user service \[AI] # \[AI] - 50% 이상 AI 생성, \[AI-minor] - 50% 미만, \[AI-review] - 리뷰만 AI 사용 # AI가 캐시/클라이언트 코드 작성, 캐시키 설계/테스트/검증은 사람이 직접
• 효과
  1. 리뷰어가 AI 코드에 특별히 주의
  2. 디버깅 시 코드 출처 파악 용이
  3. AI 사용에 대한 부끄러움·은폐 문화 제거, "책임감 있게 AI를 쓴다"는 팀 문화 확립
• 누구나 부담 없이 AI를 활용하고, 고성과 문화에 기여할 수 있도록 적극적인 공개와 문화적 장치가 중요

Claude의 금지사항: AI는 여기엔 절대 손대지 말 것

• 테스트 파일/데이터베이스 마이그레이션/보안 핵심코드/API계약(버전관리 미포함)/환경 설정 및 시크릿 등은 AI의 자동화 절대 사용 불가
• 실수 등급별(포맷·의존성부터 비즈니스 핵심영역 데이터 파괴까지)로 구분해, 고위험 영역엔 추가적인 강제 가드레일 적용 강조
• AI 실수의 위험 등급(Hierarchy of AI Mistakes)
  • Level 1: 귀찮지만 치명적이지 않음
    • 포맷 오류(린터로 잡힘)
    • 장황한 코드(나중에 리팩터링)
    • 비효율적 알고리즘(프로파일링 시 발견)
  • Level 2: 비용 많이 드는 오류
    • 내부 API 호환성 깨짐(팀 조율 필요)
    • 기존 패턴 변경(혼란 초래)
    • 불필요한 의존성 추가(코드 비대화)
  • Level 3: 경력에 치명적(Career-Limiting)
    • 테스트 결과를 맞추기 위해 테스트 자체 수정
    • API 계약 파괴
    • 시크릿/개인정보 유출
    • 데이터 마이그레이션 손상
  • 실수의 레벨에 따라 가드레일 수준도 달라져야 하며, Level 3 실수는 커리어에도 중대한 위협이 됨

개발의 미래: 앞으로의 변화와 방향

• 2025년 현재, AI 보조 개발은 사춘기 청소년처럼 강력하지만 아직 어색하고 거칠음
• 그러나 성장 곡선은 명확하게 '가속' 중
• 좋은 문서화(Documentation)는 AI 시대 DevOps 구현의 핵심 인프라
  • 문서는 이제 '참고자료'를 넘어, 인간 의도와 AI 실행 사이의 직접적 '인터페이스'
  • 고성과 팀은 테스트만큼 CLAUDE.md 등 문서 관리에 철저함

• 앞으로 예상되는 변화

  • 코드 전체 맥락을 이해하는 AI
    • 파일 단위가 아닌 서비스/시스템 레벨까지 파악
  • 세션·프로젝트를 넘는 지속적 메모리
    • 대화와 작업 맥락을 장기적으로 기억·활용
  • 적극적 개선 제안을 하는 AI
    • 요청 없이도 문제·개선점을 미리 진단
  • 팀별 패턴·선호도를 학습하는 AI
    • 조직만의 스타일/관례에 맞는 코드를 자동 생성
• 하지만, 기본은 변하지 않음:
  • 방향 설정은 인간, 실행·지렛대는 AI
  • 도구가 아무리 강력해져도, 우리는 여전히 ‘도구를 쓰는 사람’임

결론: 지금, 여기서 시작하세요

• 여기까지 읽었다면 기대와 동시에 약간의 두려움도 느낄 것임
  • 그 반응이 정상, AI 보조 개발은 강력하지만 '의도적이고 체계적인 실천'이 필수

• 오늘 바로 실천할 액션 플랜

  • 오늘
    • 1. 현재 프로젝트에 CLAUDE.md 파일 만들기
    • 2. 본인이 가장 복잡하다고 생각하는 코드에 anchor comment 3개 직접 추가
    • 3. 명확한 경계(가이드) 아래 AI 보조 기능 1개 시도
  • 이번 주
    • 1. 팀 단위로 AI 커밋 메시지 규칙 만들기
    • 2. 주니어 개발자와 함께 AI 코딩 세션 한 번 운영
    • 3. AI가 만든 코드에 대해 직접 테스트 코드 작성
  • 이번 달
    • 1. AI 도입 전후의 배포 빈도 변화 측정
    • 2. 팀 내 반복 작업에 대한 프롬프트 패턴 라이브러리 구축
    • 3. 팀 전체 AI 협업 회고 미팅 진행
• 핵심은 "지금 당장, 작게, 신중하게, 그러나 반드시 시작"
• 이 흐름을 빨리 마스터한 개발자는 더 똑똑해서가 아니라,
  • 더 일찍 시작해서 더 많이 실수하며 학습했기 때문
• 소프트웨어 배포 성과가 곧 조직의 성과를 좌우
  • 속도와 품질이 경쟁력인 시대, AI 보조 개발은 선택이 아닌 '필수 역량'
  • 단, 올바른 방법으로 접근해야 함
• 바이브 코딩은 장난처럼 들리지만,
  • 인간의 역량을 증폭하는 진지한 개발 방식
  • 도구와 패턴은 이미 충분히 준비됨
  • 이젠 누가 오케스트라를 지휘할지, 누가 혼자서 모든 악기를 연주할지 선택할 때

실전 자료와 추천 리소스

• CLAUDE.md 실전 템플릿 : github.com/julep-ai/julep/blob/main/AGENTS.md
• Peter Senge – 『The Fifth Discipline』 :
• "Beyond the 70%: Maximising the Human 30% of AI-Assisted Coding" – 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』