Taeho Kim
Menu
HomeWritingNotesReadingAbout
KOEN

이 글은 AI 코딩 어시스턴트(특히 Claude)를 활용해 실제 프로덕션 코드를 빠르고 안전하게 배포하는 방법과, 그 과정에서 반드시 지켜야 할 원칙들을 시간순으로 체계적으로 정리한 실전 가이드입니다. AI가 개발 생산성을 10배로 끌어올릴 수 있는 이유와 한계, 그리고 이를 극복하는 구체적인 실천법까지 모두 담겨 있어요. 🛠️

1. 서론: AI 코딩, 밈에서 실전으로

  • AI 코딩이란, AI가 코드를 작성하고 개발자는 이를 지휘·감독하는 새로운 개발 방식입니다.
  • 이 글의 목적은 AI가 진짜로 개발 생산성을 10배 올릴 수 있는 방법과, 그 과정에서 반드시 필요한 개발 문화와 실천법을 공유하는 데 있습니다.

"좋은 개발 습관은 선택이 아니라 필수입니다. AI가 당신의 역량을 증폭시킬지, 혼란을 증폭시킬지는 바로 이 습관에 달려 있습니다."

  • 실제 연구 결과, 엄격한 개발 습관을 가진 팀은 46배 더 자주 배포하고, 440배 더 빠르게 커밋에서 배포까지 진행합니다.
    (출처: Accelerate: The Science of Lean Software and DevOps)

2. 밈에서 방법론으로: Vibe Coding의 탄생

  • Vibe Coding은 Andrej Karpathy가 트윗에서 농담처럼 언급한, "AI가 코드를 짜고 개발자는 그냥 분위기를 즐긴다"는 개념에서 시작됐어요.
  • 하지만 Anthropic의 Claude Code와 같은 도구가 등장하면서, 이 농담이 실제로 가능해지기 시작했습니다.

"Claude를 제대로 활용하지 않으면, 과잉 의욕의 인턴과 두더지잡기 게임을 하는 꼴이 됩니다."

  • Julep 팀은 방대한 백엔드 코드베이스와 복잡한 역사적 맥락을 가진 프로젝트에서 Claude를 활용해 실제로 프로덕션 코드를 배포하고 있습니다.

3. Vibe Coding의 이해: AI와의 협업 방식

전통적 코딩 vs. Vibe Coding

  • 전통적 코딩: 대리석을 조각하듯 한 줄 한 줄 직접 작성
  • Vibe Coding: 오케스트라의 지휘자처럼 AI를 지휘하며 전체 구조와 방향을 잡음

"모든 줄을 직접 만드는 대신, 당신은 리뷰하고, 다듬고, 방향을 제시합니다. 하지만, 설계자는 여전히 당신입니다. Claude는 맥락 없는 인턴일 뿐입니다."

Vibe Coding의 3가지 자세

  1. AI를 초안 작성자로

    • AI가 기본 구현을 빠르게 생성, 개발자는 설계와 아키텍처에 집중
    • 반복적/보일러플레이트 코드에 적합

  2. AI를 페어 프로그래머로

    • AI와 아이디어를 주고받으며 적극적으로 협업
    • 개발자가 개요를 잡고, AI가 세부 구현
    • 대부분의 개발에 가장 적합

  3. AI를 검증자로

    • 개발자가 작성한 코드를 AI가 리뷰, 버그나 개선점 제안
    • 지치지 않는 코드 리뷰어 역할

4. 실전 프레임워크: Vibe Coding 3단계 모드

4.1. 모드 1: Playground (실험/프로토타입)

  • 언제?
    • 주말 해킹, 개인 스크립트, POC, "이거 되나?" 실험
  • 특징
    • Claude가 80~90% 코드를 작성, 개발자는 최소한의 방향 제시
    • 빠르지만, 절대 프로덕션에는 사용 금지!

"Playground 모드는 속도가 장점이지만, 중요한 코드에는 절대 쓰지 마세요. 좋은 엔지니어링 원칙은 지금이 더 중요합니다."

4.2. 모드 2: 페어 프로그래밍 (실전/소규모 서비스)

  • 언제?
    • 5,000줄 이하 프로젝트, 실제 사용자가 있는 사이드 프로젝트, 데모, 소규모 서비스
  • 핵심 도구: CLAUDE.md
    • Claude가 자동으로 읽는 프로젝트 전용 문서
    • 코딩 규칙, 아키텍처, 테스트 방법, 스타일 가이드, 금지사항 등을 명확히 기록

"CLAUDE.md는 Claude가 대화 시작 시 자동으로 참고하는 특별한 파일입니다. 프로젝트의 규칙, 스타일, 테스트 방법, 금지사항 등을 한 번만 정리하면, 매번 설명할 필요가 없습니다."

예시: CLAUDE.md 일부

## 프로젝트: Analytics Dashboard

### 아키텍처 결정

- 기본은 Server Component, 필요시만 Client Component
- tRPC, Prisma, Tailwind 사용

### 코드 스타일

- Prettier, 100자 제한, import 정렬
- 컴포넌트는 PascalCase, 테스트와 함께 위치

### 패턴

- 데이터 패칭은 Server Component에서만
- 외부 데이터는 Zod 스키마 사용

### 금지사항

- useEffect로 데이터 패칭 금지
- TypeScript any 타입 금지

Anchor Comments (앵커 주석)

  • AI와 사람이 모두 참고하는 특별한 주석
  • 예시:
// AIDEV-NOTE: 이 컴포넌트는 가상 스크롤 사용. 10,000개 이상 아이템 처리.
// Claude, 수정 시 가상 스크롤 유지할 것!

"앵커 주석은 AI와 개발자 모두를 위한 내비게이션 표지판입니다. Claude가 길을 잃지 않게 해줍니다."

4.3. 모드 3: 프로덕션/대규모(모노레포) 스케일

  • 언제?
    • 대규모 코드베이스, 실제 사용자, 버그가 돈/신뢰에 직결되는 시스템
  • 주의
    • 현재(2025년 기준) 대규모 vibe coding은 완벽하게 확장되지 않음
    • 서비스/서브모듈 단위로 분리해 적용하는 것이 현실적

"경계(바운더리)가 명확하지 않으면, Claude는 API를 '개선'하다가 모든 클라이언트를 깨뜨릴 수 있습니다."

예시: API 경계 주석

# AIDEV-NOTE: API Contract Boundary - v2.3.1
# 변경 시 버전업 및 마이그레이션 필수
# Claude: 응답 구조는 절대 변경 금지!

5. 인프라: 지속 가능한 AI 개발의 기반

5.1. CLAUDE.md: 단일 진실의 원천

  • CLAUDE.md는 선택이 아니라 필수!
  • 코드베이스의 헌법, 모든 규칙과 금지사항, 용어 정의, 아키텍처 결정, 금지 패턴 등을 명확히 기록

"CLAUDE.md에 투자한 1분이, 나중에 1시간의 뒷수습을 줄여줍니다."

예시: CLAUDE.md 주요 항목

## 절대 규칙

- 구현이 애매하면 반드시 개발자에게 질문할 것

## 아키텍처 결정

- Temporal 사용 이유: 장기 워크플로우, 자동 복구
- PostgreSQL + pgvector: ACID, 벡터 검색

## 금지사항

1. 테스트 파일 수정 금지
2. API 계약 변경 금지
3. 마이그레이션 파일 수정 금지
4. 시크릿 커밋 금지
5. 비즈니스 로직 추정 금지
6. AIDEV- 주석 삭제 금지

앵커 주석의 실제 활용

# AIDEV-NOTE: 성능 중요 경로 - 10만 req/sec 처리
# DB 쿼리 추가 금지
def get_user_feed(...):
    # AIDEV-TODO: 페이지네이션 구현 필요
    # AIDEV-QUESTION: 왜 여기서 private 아이템 필터링?
    # AIDEV-ANSWER: 캐시 업데이트 간 프라이버시 규칙 변경 가능성 때문

5.2. Git 워크플로우

  • AI 실험은 git worktree로 분리
    • 메인 브랜치 오염 없이 AI가 자유롭게 실험
    • 성공한 커밋만 cherry-pick
git worktree add ../ai-experiments/cool-feature -b ai/cool-feature
# Claude 실험
git cherry-pick abc123  # 성공한 커밋만 메인에 반영
git worktree remove ../ai-experiments/cool-feature
  • AI 커밋 메시지 규칙화
feat: implement user feed caching [AI]
- 핵심 로직 AI 생성, 테스트는 사람이 작성

"AI가 관여한 커밋은 반드시 [AI] 태그로 명확히 표시합니다. 리뷰어가 더 꼼꼼히 볼 수 있도록!"

6. 가장 중요한 원칙: 테스트는 반드시 사람이 작성

"절대, 절대, 절대 AI에게 테스트 코드를 맡기지 마세요."

  • 테스트는 단순히 코드 검증이 아니라, 실행 가능한 명세이자, 비즈니스 의도와 엣지 케이스, 도메인 이해를 담은 집약체입니다.
  • AI가 작성한 테스트는 "코드가 코드대로 동작하는지"만 확인할 뿐, "원하는 대로 동작하는지"는 보장하지 못합니다.

예시: AI가 놓친 메모리 누수

class RateLimiter:
    ...
    # AI가 작성한 테스트는 정상 경로만 확인, 메모리 누수는 놓침!
  • Julep의 규칙:
| 항목        | AI가 할 수 있음    | AI가 절대 하면 안 됨 |
| ----------- | ------------------ | -------------------- |
| 구현        | 비즈니스 로직 생성 | 테스트 파일 수정     |
| 테스트 기획 | 시나리오 제안      | 테스트 코드 작성     |
| 디버깅      | 실패 분석          | 기대값 수정          |

"AI가 테스트 파일을 건드리면 PR은 무조건 반려. 예외 없음."

7. 대규모 적용 시 주의점: 토큰 경제와 컨텍스트 관리

  • 컨텍스트(프롬프트) 아끼려다 오히려 토큰 더 씀!
  • "최소"가 아니라 "관련 있고 충분한" 정보를 제공해야 AI가 한 번에 제대로 작업

예시: 컨텍스트 부족 vs. 충분한 컨텍스트

  • 부족한 프롬프트

    • "유저 엔드포인트에 캐싱 추가"
    • → AI가 인메모리 캐시, 무효화 없음, 모니터링 없음 등 실수 연발

  • 충분한 프롬프트

    • "Redis 캐싱 추가, 12대 서버, 1시간 TTL, 캐시 스탬피드 방지, Prometheus 메트릭 포함, 캐싱 가이드 참고"
    • → 한 번에 제대로 구현

"토큰은 좋은 도구에 투자하는 비용입니다. 컨텍스트를 아끼지 마세요!"

  • 작업별로 Claude 세션 분리
    • 한 세션에 여러 주제 섞지 말 것
    • "한 작업, 한 세션" 원칙

8. 실제 사례: 500+ 엔드포인트 에러 구조 리팩토링

  • 사람이 결정(Why):
    • 에러 계층 구조, 에러 코드, 응답 포맷 등은 반드시 사람이 설계
# SPEC.md - 에러 계층 구조

- 클라이언트 에러(4xx), 시스템 에러(5xx) 구분
- 모든 에러는 JSON 직렬화, 코드 안정성 보장
  • AI가 실행(How):
    • Claude가 500개 이상 에러 처리 코드 일괄 리팩토링
# Before
raise Exception("User not found")
# After
raise AuthenticationError(
    message="User not found",
    code="USER_NOT_FOUND",
    details={"identifier": email}
)

"명확한 명세와 CLAUDE.md, 앵커 주석, 문서화 덕분에 2일 걸릴 작업을 4시간 만에 끝냈습니다."

9. 리더십과 문화: AI 시대의 개발팀 운영

  • 시니어 개발자의 역할 변화

    • 코드 작성자 → 지식 큐레이터, 경계 설정자, AI와 인간 모두의 멘토

  • 온보딩 체크리스트

    • 1주차: CLAUDE.md 읽기, 환경 세팅, 첫 PR(사람만 작성)
    • 2주차: Claude 세팅, AI와 토이 문제, 첫 AI PR(감독 하에)
    • 3주차: 독립적 AI 기능 개발, 타인의 AI 코드 테스트 작성, 코드리뷰 리드

  • 투명성 문화

    • AI 관여 커밋은 반드시 [AI], [AI-minor], [AI-review] 등으로 태그
    • "AI를 썼다고 숨기지 마세요. 책임감 있게, 투명하게 사용하세요."

10. Claude가 절대 건드리면 안 되는 것들 (금과옥조)

❌ 테스트 파일

# 여기는 신성한 영역
# AI 출입 금지
def test_critical_business_logic():
    """이 테스트에는 1000만 달러 가치의 도메인 지식이 담겨 있음"""
    pass

❌ 데이터베이스 마이그레이션

-- AI가 건드리면 데이터 날아감 = 커리어도 날아감
ALTER TABLE users ADD COLUMN subscription_tier VARCHAR(20);

❌ 보안 코드

# HUMAN EYES ONLY - 보안 경계
def validate_token(token: str) -> Optional[UserClaims]:
    # 보안팀 승인 필요

❌ API 계약(버전 관리 없는 경우)

# openapi.yaml
# 이거 깨면 모든 클라이언트 작동 불가

❌ 설정/시크릿

DATABASE_URL = os.environ["DATABASE_URL"]  # 절대 하드코딩 금지

AI 실수의 계층

  • 1단계: 귀찮지만 무해

    • 포맷 오류, 장황한 코드, 비효율적 알고리즘

  • 2단계: 고치기 비쌈

    • 내부 API 깨짐, 패턴 변경, 불필요한 의존성 추가

  • 3단계: 커리어 위협

    • 테스트 수정, API 계약 파괴, 시크릿/PII 유출, 데이터 마이그레이션 손상

"3단계 실수는 LinkedIn 프로필 업데이트 각입니다."

11. 미래 전망: AI 개발의 다음 단계

  • AI가 전체 코드베이스 이해
  • 세션/프로젝트 간 지속적 기억
  • 프롬프트 없이도 능동적 개선 제안
  • 팀의 패턴/선호도 학습

"문서화는 DevOps의 핵심입니다. AI 시대에는 문서가 곧 인간 의도와 AI 능력의 인터페이스입니다."

12. 실천 가이드: 지금 당장 시작하세요!

오늘 할 일

  1. 프로젝트에 CLAUDE.md 만들기
  2. 가장 복잡한 코드에 앵커 주석 3개 추가
  3. 경계 명확히 하고 AI로 기능 하나 만들어보기

이번 주

  1. 팀과 AI 커밋 메시지 규칙 정하기
  2. 주니어와 AI 페어 코딩 세션 진행
  3. AI가 만든 코드에 직접 테스트 작성

이번 달

  1. AI 도입 전후 배포 빈도 측정
  2. 자주 쓰는 프롬프트 패턴 라이브러리 만들기
  3. 팀 회고 진행

"가장 중요한 건, 시작하는 것! 완벽을 기다리지 마세요. 작은 프로젝트부터, 경계부터, 그리고 반복적으로 개선하세요."

13. 참고 자료 및 리소스

"완벽은 배포의 적입니다. 작은 프로젝트부터, 경계를 명확히 하고, 반복적으로 개선하세요. 미래는 이미 와 있습니다. 단지, 아직 고르게 분포되지 않았을 뿐입니다."

분포의 일부가 되어보세요. 🚀

Related writing

Related writing

Harvest•Engineering Leadership•Korean

스타트업의 다음 시대정신을 찾아서: Beyond Product 요약

이 글은 AI 시대에 ‘좋은 제품’만으로는 경쟁우위를 지키기 어려워진 현실에서, 스타트업이 만들어야 할 다음 해자(방어력)가 무엇인지 추적합니다. 저자는 이를 제품 너머(Beyond Product)—즉 고객에게 도달하는 방식, 고객을 이해하는 깊이, 이를 조직 시스템으로 축적하는 능력—의...

Mar 17, 2026Read more
Harvest•Engineering Leadership · AI•Korean

Software 3.0 시대, 조직의 생산성을 끌어올리는 AI 하네스 구축하기

이 글은 개발팀 내에서 개인의 역량에 크게 의존하고 있는 AI(LLM) 활용 방식을 조직 전체의 체계적인 시스템으로 발전시켜야 한다는 핵심적인 메시지를 담고 있습니다. 특히 Claude Code의 플러그인과 마켓플레이스 생태계를 단순한 확장 도구가 아닌, 팀의 업무 방식과 지식을 코드로 만...

Mar 8, 2026Read more
Harvest•Engineering Leadership•Korean

미첼 하시모토의 새로운 코드 작성법: AI 시대의 소프트웨어 엔지니어링

이 영상은 하시코프(HashiCorp)의 공동 창립자이자 고스티(Ghostty)의 창시자인 미첼 하시모토와의 인터뷰를 담고 있습니다. 그는 소프트웨어 엔지니어링에 입문한 과정, 하시코프의 설립 역사, 그리고 널리 사용되는 오픈소스 도구를 성공적인 비즈니스로 전환하는 데 겪었던 어려움에 대해...

Feb 25, 2026Read more