Claude로 실제 코드 배송하며 얻은 필드 노트

Vibe 코딩은 그냥 Vibe가 아니다

Image 1: Shimmering Substance - Jackson Pollock Shimmering Substance - Jackson Pollock

참고: 이 글에는 NotebookLM 팟캐스트(1), 그리고 _세 개_의 생성된 오디오 녹음이 함께 제공됩니다.

이 글을 준비하며 ChatGPT와 나눈 대화 기록도 읽어볼 수 있습니다.

관련 HN 포스트에서 댓글과 토론도 확인하세요.

이 글은 소프트웨어를 새롭게 만드는 법에 대한 여러분만의 현장 안내서입니다. 다 읽고 나면, AI 지원 개발을 실제로 제대로 활용하는 "방법"뿐 아니라 그 "이유"까지 이해하게 될 겁니다.

이 글에서 무엇을 배우게 될까?

먼저 진짜로 10배 생산성 향상을 이루는 법을 살펴봅니다. 이는 마법이 아니라, AI의 강점을 극대화하고 약점은 보완하는 의도적인 실천을 통해 가능합니다.

다음으로 Julep에서 Claude의 도움을 받아 매일 실제 코드를 배포하는 인프라 구조, CLAUDE.md 템플릿, 커밋 전략, 각종 가드레일(안전장치)을 하나씩 공개합니다.

가장 중요한 건, AI 시대에도, 아니 오히려 AI 시대에 더더욱, "직접 테스트 코드를 쓰는 것"이 얼마나 신성한 원칙인지를 이해하는 것입니다. 이 하나로 수많은 야근 디버깅을 피할 수 있습니다.

핵심 통찰: 좋은 개발 습관은 선택이 아니라 필수다. 이것이 AI가 당신의 역량을 증폭시키는 비결이며, 그렇지 않으면 혼란만 키울 뿐입니다. 실제 연구가 이를 뒷받침합니다. 2엄격한 개발 관행을 지키는 팀은 배포 빈도가 46배 높고, 커밋에서 배포까지 440배 더 빠릅니다. 강력한 AI가 추가되면 이 효과는 더욱 커집니다.

왜 이 글을 쓰게 되었나: 밈에서 방법론으로

처음 이 모든 것이 시작됐던 때로 돌아가 보죠. 3Andrej Karpathy4가 “vibe-coding”에 트윗을 남겼습니다. AI가 코드를 써주는 동안 개발자는 그저 "진동(vibe)"만 느끼면 된다는 아이디어죠. 개발 커뮤니티는 한바탕 웃었습니다. 이건 마치 궁극의 개발자 판타지 같았죠: 커피를 들고 편히 앉아 기계가 알아서 다해주는 세상.

Image 3: The birth of “vibe coding” “vibe coding”의 탄생

그러다 _Anthropic_이 Sonnet 3.7과 Claude Code를 출시하자 상황이 바뀌었습니다. 농담 같던 소리가, 이제는... 진짜 가능해진 것 아닐까? 싶은 거죠. 친숙한 Cursor도 이미 있었지만, 이 새로운 인터페이스로 드디어 "진짜 vibe coding"을 경험할 수 있었습니다.

Julep에선 AI 워크플로우 오케스트레이션을 만듭니다. 백엔드에는 다년간 축적된 결정, 패턴, 부채가 쌓여 있죠. 코드 품질을 최대한 높게, 문서도 빼곡히 관리했지만, 이 방대한 규모와 왜 그렇게 구조가 잡혔는지의 역사적 맥락 때문에 실력 좋은 엔지니어도 맥락을 파악하는 데만 몇 주가 걸립니다.

Claude 사용할 때 제대로 된 가드레일 없이 접근하면, 과도하게 열정적인 인턴과 두더지잡기 게임을 하는 셈입니다.

Vibe-Coding이란 무엇인가

Image 4: ‘pls fix’ ‘pls fix’

5_Steve Yegge_는 자신의 다소 극적인 글 “The death of the junior developer”에서 CHOP—Chat-Oriented Programming이란 말을 썼습니다. 이건 Claude와 코딩하는 현실을 완벽, 그리고 솔직하게 묘사해줍니다.

전통적인 코딩은 대리석 조각하기와 비슷합니다. 빈 블록에서 시작해, 한 줄 한 줄, 함수 하나하나 직접 깎으며 만듭니다. 모든 결정은 오롯이 내 몫, 느리지만 뿌듯하죠.

vibe-coding은 오히려 오케스트라 지휘 같아요. 모든 악기를 직접 연주하는 게 아니라, 방향을 제시하고, 형태를 만들고, 가이드를 하는 것. AI는 원재료(연주자)를 제공하지만, 비전이 없다면 잡음에 불과합니다.

vibe-coding에는 개발 단계별로 적합한 아래 세 가지 태도가 있습니다:

AI를 초안작성자(First-Drafter)로: AI가 초초안을 자동 생성, 개발자는 설계·구조에 집중. 생각보다 빠른 타자 속도의 쥬니어가 늘 옆에 있는 느낌. 반복 작업과 CRUD 등에 적합함.
AI를 페어프로그래머로: 개발의 핵심. 함께 아이디어를 나누고, AI가 방법을 제안하면 내가 다듬고, 뼈대만 주면 AI가 채워감. 모든 프로그래밍책을 읽었지만 코드 '배송'은 해본 적 없는 파트너와 페어하는 느낌.
AI를 검증자(Validator)로: 내가 코드를 쓰면 sanity check해줌. 버그 찾기, 개선 제안, 놓치기 쉬운 패턴을 집어줌. 무한 체력의 코드 리뷰어 같음.

한줄 한줄 만드는 게 아니라, 리뷰·수정·지휘에 집중하는 셈이죠. 하지만 중요한 건, 아키텍트는 여전히 본인! Claude는 맥락은 없지만 지식은 방대한 인턴에 불과합니다.

vibe-coding 실전: 세 가지 프레임워크

수개월의 실험과 여러 번의 실전 사고(!) 이후, 저는 아래 세 가지 모드를 도출했습니다. 각기 리듬과 가드레일, 사용 장면이 다릅니다.

모드 1: Playground (놀이터)

이미지 5: 라이터액체 라이터액체

언제? 주말 해킹, 개인 스크립트, 프로토타입, “이거 되려나?” 같은 실험용

놀이터 모드에선 혼돈을 즐깁니다. Claude가 80~90% 코드를 쓰고, 나는 최소한의 가이드만 던져줍니다. 해방감+약간의 공포가 섞인 느낌! 팁:claude-composer 참고하세요.

예시: Spotify 이용 기록을 분석하는 스크립트 아이디어가 떠올라요. Claude에 영어로 원하는 걸 설명하면, 완전한 코드를 뚝딱 생성해줍니다. CLAUDE.md도, 신경 쓴 프롬프팅도 없이, 그냥 100% 날코딩.

놀이터의 장점은 스피드! 아이디어→동작하는 프로토타입까지 몇 분. 단점은... 이 야생 코딩은 "중요한" 모든 곳에선 절대 비추천. 부실한 엔지니어링 원칙은, 이제 더더욱 위험합니다. 참고

모드 2: 페어프로그래밍

이미지 6: 컴파일 중 컴파일 중

언제? 코드 5,000줄 미만 사이드 프로젝트, 실제 사용자 있는 데모, 잘 분리된 소규모 서비스 등

이때부터 vibe-coding이 본격적으로 빛을 발합니다. 어느 정도 구조(Structure)가 필요하지만, 느려지지 않을 정도까지! 여기서 중요한 것은 CLAUDE.md 파일—Claude가 대화 시작 시 자동 맥락으로 삼는 커스텀 문서입니다. Anthropic의 Best practices for Claude Code 참고:

CLAUDE.md는 Claude가 자동 참조하는 특수 문서입니다:

자주 쓰는 bash 명령어

핵심 파일 및 유틸리티

코드 스타일 가이드라인

테스트 지침

저장소 규칙(브랜치 이름, 머지/리베이스 등)

기억시킬 추가 정보 등

프로젝트 관행을 일일이 설명하는 대신, 한 번만 문서에 적으면 끝. 실제 예시:

## Project: Analytics Dashboard  
이건 Next.js 대시보드입니다.  

### Architecture Decisions  
- 기본 Server Components, 꼭 필요할 때만 Client Components  
- tRPC로 타입 안정 API 호출  
- Prisma: 쿼시 select 지정 필수  
- Tailwind만 사용(커스텀 CSS 금지)

### Code Style  
- Prettier: 100자 라인  
- 단순-import-sort로 정렬  
- 컴포넌트: Pascal Case, 테스트와 코로케이션  
- 훅: 'use' 프리픽스 필수

### Patterns to Follow  
- 데이터 패칭은 서버 컴포넌트에서  
- 클라이언트 컴포넌트엔 props로 데이터 전달  
- 외부 데이터는 Zod 스키마 필수  
- 모든 데이터 컴포넌트에 error boundary 추가

### What NOT to Do  
- 데이터 패칭용 useEffect 사용 금지  
- 승인 없이 글로벌 상태 생성 금지  
- any 타입 자제

이런 맥락이 준비되면 Claude의 효율성이 극도로 높아집니다. 매일 신규입사자 온보딩 시키는 게 아니라, 한 번에 문서를 준 셈!

단, _페어프로그래밍 모드_는 문서만으론 부족. AI에 ‘앵커 코멘트(anchor comments)’라는 단서도 꼭 남깁니다. Claude가 산으로 가는 걸 막는 내비게이션:

js
// AIDEV-NOTE: 이 컴포넌트는 가상 스크롤 사용(https://tanstack.com/virtual/latest 참고)
// 일반 map 변환 금지—1만개 이상 처리
export function DataTable({ items }: DataTableProps) {
  // Claude, 수정시 가상 스크롤 구조 꼭 유지!
  ...
}

이런 주석은 사람도, Claude도 위한 이중 도우미 역할을 합니다. 특히 앵커 코멘트와 일반 코멘트의 차이: 이건 Claude를 위해 작성, 수정, 활용되는 주석이라는 것! 실제 우리 프로젝트 CLAUDE.md 일부를 소개하면:

## Anchor comments  

코드 곳곳에, 필요시, 본인 또는 AI를 위한 인라인 지식으로 특수형식 주석을 추가.  

### 지침:  
- AI·개발자 모두를 위한 코멘트엔 `AIDEV-NOTE:`, `AIDEV-TODO:`, `AIDEV-QUESTION:` (대문자) 접두어 사용  
- 최대 120자 내외로 간단하게  
- **중요:** 파일 스캔 전, 반드시 관련 하위 디렉토리에 ‘AIDEV-*’ 앵커 코멘트 있는지 우선 검색
- 코드 수정시 관련 앵커 업데이트 필수  
- **앵커 코멘트는 직접 삭제 말고 반드시 지시 필요**

예시:
# AIDEV-NOTE: perf-hot-path; 추가 할당 자제(ADR-24 참고)
async def render_feed(...):
    ...

모드 3: 프로덕션/모노레포 규모

이미지 8: RTFM RTFM

언제? 대형 코드베이스, 실제 사용자가 있는 시스템, 결함이 돈이나 명성에 직결되는 곳

Claude는 대량의 코드를 생성할 수 있지만, 복잡한 시스템에 통합하는 것은 매우 세심한 오케스트레이션이 필요합니다.

초대형 프로젝트일수록 vibe-coding이 아직은 완벽하게 확장되지 않습니다. 앞으로 개선이 클 예정이지만, 지금은 직접 네비게이션, 안전성 확보, 맥락 제공에 큰 공이 들어가야 효과적입니다. 일반적으로는 서브서비스별로 모듈화해 작업하는 게 효과적이고, 6git submodule 대신 자체 분리 모듈 추천합니다.

실무자라면, 대규모 시스템일수록 클래식 엔지니어링 원칙이 그대로 적용됩니다. 경계(Boundary)는 치명적! 모든 인터페이스에, 사람이 이해할 수 있도록 명확한 문서가 필요합니다.

# AIDEV-NOTE: API Contract Boundary - v2.3.1  
# 모든 변경에는 버전업과 마이그레이션 플랜 필수  
# docs/api-versioning.md 참고

@router.get("/users/{user_id}/feed")  
async def get_user_feed(user_id: UUID) -> FeedResponse:  
    # Claude: 여기는 응답 shape 절대 변경 금지  
    # 변경시 실제 앱 전부 깨짐
    ...

경계 없이 두면 Claude가 "개선"한다며 API 구조를 조작, 결국 전체 서비스가 깨질 수도 있습니다. 요점: 대규모 프로젝트라도 부분적으로 vibe-coding을 도입해보고, 경험을 넓혀가세요. 단, 대형 신규기능을 오로지 AI로 믿고 맡기진 마세요.(2025년 6월 기준)

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

`CLAUDE.md`: 진리의 소스

명확히 밝힙니다: CLAUDE.md는 선택사항이 아닌 필수! 한 번 업데이트할 때마다, 나중에 1시간의 대청소를 절약합니다.

CLAUDE.md는 코드베이스의 헌법과 같습니다. 코드 작성, 시스템 상호작용, 추천/금지 패턴 등 기초 법칙을 정의합니다. 조직 차원의 ‘역량 투자’이기도 하죠.

수천 커밋 이상 걸쳐 적립, 다듬은 우리 프로덕션 CLAUDE.md 구조 일부 예시:

# `CLAUDE.md` - Julep Backend Service  

## The Golden Rule  
불확실하면 반드시 개발자에게 물어볼 것  

## Project Context  
Julep은 선언적 워크플로우로 상태 유지형 AI agent 개발 지원

## Critical Architecture Decisions  

### Why Temporal?  
- 장기(수 일/수주) 워크플로우 신뢰성 유지  
- 실패 대비 자동 복구

### Why PostgreSQL + pgvector?  
- ACID 준수로 사용자 상태 손실 없음  
- 벡터 서칭으로 agent 메모리 관리

### Why TypeSpec?  
- API 명세 단일 소스(오픈API,타입스크립트·파이썬클라이언트,검증스키마)

## Code Style and Patterns  

### Anchor comments  

코드 곳곳에 필요시, 본인·AI 위한 인라인 지식 주석 추가

### Guidelines:  

- AI·개발자 모두 대상 주석: 대문자 접두사 사용(AIDEV-NOTE:,AIDEV-TODO:,AIDEV-QUESTION:)
- **중요:** 파일 스캔 전, 반드시 관련 하위디렉토리 'AIDEV-*' 앵커 먼저 grep
- 관련 코드 수정시 앵커도 반드시 최신화  
- `AIDEV-NOTE` 삭제는 명시적 인간 지시 있어야  
- 복잡/중요/혼란 가능/버그 우려시엔 앵커 주석 필수

## Domain Glossary (Claude, 꼭 익혀라!)  
- **Agent**: 메모리·도구·행동정의 갖춘 AI 엔티티  
- **Task**: 단계 기반 워크플로우(셀러리 task 아님)  
- **Execution**: task 인스턴스 실행  
- **Tool**: agent가 호출 가능한 함수 등  
- **Session**: 메모리 갖춘 대화 컨텍스트  
- **Entry**: 세션 내 단일 상호작용

## AI가 절대 하면 안 되는 것  
1. 테스트 파일 수정 금지 – 테스트는 사람의 의도
2. API 계약 변경 금지 – 실제 앱 깨짐
3. 마이그레이션 파일 변경 금지 – 데이터 손실
4. 시크릿 커밋 금지 – 환경변수 활용
5. 비즈니스 로직 임의 해석 금지 – 항상 질문
6. AIDEV- 코멘트 삭제 금지 – 이유 있음

우리는 '트릭'보다 '유지보수성'을 항상 우선.
애매하면, 심플하게 간다.

이 문서는 Claude와 나, 개발자 모두의 공유 맥락이 됩니다.

코드베이스가 커질수록 CLAUDE.md만으론 부족. 이때는 앵커 코멘트(주석)로 인라인 맥락 제공이 중요합니다.

코드베이스를 도시로, 앵커 코멘트를 거리 표지판으로 생각해보세요. 표지판이 없다면 똑똑한 방문자도 길을 잃죠. 사용 예시:

# AIDEV-NOTE: 매우 중요한 퍼포먼스 경로 - 10만 req/sec 처리
# 데이터베이스 쿼리 여기선 금지!
def get_user_feed(user_id: UUID, cached_data: FeedCache) -> List[FeedItem]:
    # 캐시 데이터 변형 금지
    items = cached_data.items[:]

    # AIDEV-TODO: 페이지네이션 구현(ticket: 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 worktrees 추천합니다:

# 메인 브랜치 오염 없는 AI 놀이터 만들기
git worktree add ../ai-experiments/cool-feature -b ai/cool-feature

# Claude 자유 실험
tcd ../ai-experiments/cool-feature
# … 실험 커밋 쌓기 …

# 쓸만한 결과 cherry-pick으로 main에 반영
cd ../main-repo
git cherry-pick abc123

# 다 쓰고 정리
git worktree remove ../ai-experiments/cool-feature

추가팁: worktree 실전 가이드도 읽어보시고, wt 툴도 참고하세요.

이 방법으로 Claude 실험은 마음껏, 메인 브랜치는 깨끗하게!

커밋 메시지는 AI 지원 커밋임을 태그로 통일합니다:

feat: implement user feed caching [AI]

- Add Redis-based cache for user feeds
- Implement cache warming on user login
- Add metrics for cache hit rate

AI-assisted: 핵심 로직은 AI 생성, 테스트는 직접 작성

이렇게 하면 리뷰어는 AI가 생성한 부분을 더욱 면밀히 살필 수 있습니다.

신성한 원칙: 테스트는 무조건 사람이 직접 작성

AI 지원 개발의 가장 중요한 원칙입니다. 여러 번 강조해도 지나치지 않아요:

Never. Let. AI. Write. Your. Tests.

테스트는 단순히 코드가 동작함을 검증하는 코드가 아닙니다. 바로 실행 가능한 "사양(specification)"이며, 실제 의도, 엣지 케이스, 도메인 이해까지 모두 담깁니다. 고성과 팀은 빠름+안정성을 모두 잡습니다. 테스트가 유일한 방법입니다.

이미지 9: 조심하라… 조심하라…

예를 들어봅니다. Claude에게 rate limiter를 구현하라 했다고 칩시다:

class RateLimiter:  
    def __init__(self, max_requests: int, window_seconds: int):  
        self.max_requests = max_requests  
        self.window_seconds = window_seconds  
        self.requests = defaultdict(list)  

    def is_allowed(self, user_id: str) -> bool:  
        now = time.time()  
        user_requests = self.requests[user_id]  

        # Clean old requests  
        self.requests[user_id] = [  
            req_time for req_time in user_requests  
            if now - req_time < self.window_seconds  
        ]  

        if len(self.requests[user_id]) < self.max_requests:  
            self.requests[user_id].append(now)  
            return True  
        return False

겉보기에 그럴듯하고, Claude는 테스트도 생성해줍니다:

def test_rate_limiter():  
    limiter = RateLimiter(max_requests=3, window_seconds=60)  

    assert limiter.is_allowed("user1") == True  
    assert limiter.is_allowed("user1") == True  
    assert limiter.is_allowed("user1") == True  
    assert limiter.is_allowed("user1") == False  # Limit reached

하지만 Claude 테스트가 놓친 것이 있습니다. 바로 실무 경험과 맥락을 가진 개발자만 챙기는 부분: 이 구현은 메모리 릭이 납니다! 단 한 번 호출 후 이탈한 유저의 데이터가 영원히 남아버리죠. AI 테스트는 성공 경로만 체크, 실전 품질 이슈는 걸러내지 못합니다.

이미지 10: vibe coding의 끝판왕 vibe coding at its best

그래서 테스트는 사람이 직접 쓰는 게 필수! 우리는 문맥, 운영환경, 초기 경험, 진짜 중요 엣지 케이스를 이해합니다. Julep 규칙은 절대적입니다:

## Testing Discipline  

| What | AI CAN Do | AI MUST NOT Do |  
|------|-----------|----------------|  
| Implementation | Generate business logic | Touch test files |  
| Test Planning | Suggest test scenarios | Write test code |  
| Debugging | Analyze test failures | Modify test expectations |  

AI가 테스트 파일을 건드리면 PR 거부, 예외 없음.

테스트는 명세, 안전망, 누적 지혜. 반드시 신성하게 지키세요.

스케일링의 실전: 토큰 경제와 컨텍스트 관리

AI 지원 개발에서 가장 역설적 교훈: 토큰 아깝다고 최소 맥락만 주면 결과적으로 훨씬 더 많은 비용(토큰, 시간)이 듭니다. 마치 휘발유를 절약하겠다며 반만 채우고 달렸다가 더 자주 주유소 들르는 격.

토큰 관리 중요합니다. 프롬프트를 간결(하지만 충분히 연관성 있게) 만들고, Diff 줄이고, 장파일은 의도를 먼저 요약해서 전달하세요. "간결"이란 "최소"가 아니라 "연관되고 완전하게"입니다!

빈약 프롬프트의 허상 예시:

빈약한 프롬프트:

"Add caching to the user endpoint"

Claude의 동작:

메모리 캐시만 도입(멀티서버에서 문제)
캐시 만료 및 전략 없음
모니터링 빠짐
캐시 스탬피드 케어 없음

→ 수정이 3번 반복, 총 토큰 4배 소모

충분한 맥락 제공 프롬프트:

GET /users/{id} 엔드포인트에 Redis 캐싱 추가
컨텍스트:
- 초당 5만 요청 
- API서버 12대 LB운용
- 데이터 변경 적음(하루 몇번)
- 이미 Redis 있음: cache.redis.internal:6379
- 캐시키패턴: "user:v1:{id}"
- Prometheus로 캐시 hit/miss 측정
- 1시간 TTL 캐시 어사이드 패턴 사용
- 캐시 스탬피드: early expiration 처리
caching.md 참고

교훈: 좋은 맥락을 처음에 제공해라! 반복 작업/수정(Iterate) 줄이고, 토큰은 좋은 도구에 투자한다고 생각하세요.

실제로 전 프로젝트마다 Claude로 변화 내역 검토 후, CLAUDE.md에 맥락을 보강하는 루틴을 권장합니다.

신선한 세션과 멘탈모델 유지

또 하나의 역설: 각각의 작업마다 새로운 Claude 세션을 사용하세요. 대화 하나만 길게 이어가면 맥락 오염이 생깁니다.

이유: 생닭 썬 도마로 바로 채소를 자르지 않듯, DB 마이그레이션 내용을 다룬 직후에 스타일 프론트엔드를 같은 세션에서 논하는 건 위험!

규칙: 한 작업, 한 세션. 작업 끝나면 새로 시작. Claude의 멘탈모델을 깨끗하고 집중력 있게 유지하세요.

실전: 프로덕션 Structured Error 배송 사례

실제로 우리가 Julep에서 시행한 vibe-coding 프로덕션 리팩토링 사례를 공유합니다. 500개가 넘는 엔드포인트 전체에 체계적 오류 계층 구조를 도입해야 했습니다.

사람의 결정(Why):

에러 분류(taxonomy) 결정은 100% 설계/비즈니스 맥락! Claude는 이걸 판단 못합니다. 대표 사양 예시:

# SPEC.md - Error Hierarchy Design (Human-Written)

## Error Philosophy
- 4xx(클라이언트) 오류는 반드시 actionable 메시지 제공
- 5xx(서버) 오류엔 trace ID 필수
- 무조건 JSON 직렬화
- 에러코드는 반드시 고정(클라이언트 사용)

## Hierarchy
BaseError
├── ClientError (4xx)
│   ├── ValidationError
│   │   ├── SchemaValidationError
│   │   ├── BusinessRuleError
│   │   └── RateLimitError
│   └── AuthError
│       ├── AuthenticationError
│       └── AuthorizationError
└── SystemError (5xx)
    ├── DatabaseError
    ├── ExternalServiceError
    └── InfrastructureError

## Error Response Format
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Email already exists",
    "details": { ... },
    "trace_id": "abc-123-def"
  }
}

AI의 실행(How):

이제 사양이 명확하니, Claude에게 반복 리팩토링을 맡깁니다:

### Claude에 준 프롬프트:
SPEC.md에 맞춰 오류 처리 리팩토링. auth 모듈을 가장 먼저. 플랜 보여주고 시작.

Claude가 짠 플랜:

error 계층을 common/errors.py 생성
오류 응답 포매터 작성
모든 모듈 systematic하게 업데이트
error handling 미들웨어 설치

그리고 500개 이상 사용처 전부 실수 없이 자동변경(사람은 리뷰 집중):

# Before
if not user:
    raise Exception("User not found")

# After
if not user:
    raise AuthenticationError(
        message="User not found",
        code="USER_NOT_FOUND",
        details={"identifier": email}
    )

CLAUDE.md·문서·앵커 주석·명확 가이드가 뒷받침되면:

총 시간: 4시간(직접 했으면 2일)

적용범위: 500+ 위치 실시간 자동반영

AI 시대 리더십과 문화

시니어 엔지니어의 역할이 바뀌었습니다! 이제 단순히 코드만 작성하지 않아요. 지식 큐레이팅, 경계 설정, 개발자와 AI 모두에 대한 교육/가이드가 주 임무입니다.

린 매니지먼트·지속적 배포 같은 현대적 실천이 소프트웨어/조직 전체 성과를 증대합니다. AI 협업 관리도 예외가 아닙니다.

새 온보딩 체크리스트

신규 개발자 입사 땐 아래처럼 두 가지(사람/AI) 온보딩 트랙을 제공합니다.

1주: 기본기 세우기

□ 팀 CLAUDE.md(루트→서비스별) 읽기
□ 개발환경 세팅
□ 첫 PR 직접 작성(AI 도움없이)

2주: 가이드 하에 AI 협업 시작

□ Claude에 팀 템플릿 적용
□ 토이문제 AI와 함께 완성해보기
□ 대표 프롬프트 패턴 연습
□ 첫 AI-assisted PR 제출(멘토 동행)

3주: 독립작업

□ 첫 메이저 AI 지원 기능 배송
□ 동료 AI코드의 테스트 커버 작성
□ 코드리뷰 1회 주도

투명성 문화 만들기

중요한 문화 변화 중 하나: AI 지원 여부를 당당히 드러내는 것입니다. 숨기지 말고, 책임 있게 씁니다. 모든 AI 작업 커밋에는 태그 부착:

# .gitmessage 템플릿
# feat/fix/docs: <설명> [AI]?
#
# [AI] - 50% 이상 AI 생성
# [AI-minor] - 50% 미만 AI 생성
# [AI-review] - AI는 코드 리뷰에만 동원
#
# 예시:
# feat: user service에 Redis 캐싱 추가 [AI]
#
# AI: 캐싱 구현/Redis 클라이언트 세팅 자동 생성
# 사람: 캐시 키 설계·테스트 직접 작성
# 캐시 만료 직접 검증

이 투명성의 효과:

리뷰어가 더 꼼꼼히 체크
디버깅시 코드 출처 식별 쉬움
AI 사용에 대한 불쾌감/수치심 최소화

즉, 누구나 AI를 책임감 있게 활용할 수 있는 안전망 제공이 곧 고성과 조직의 비결입니다.

Claude가 절대 건드리면 안 되는 것(절대불변)

경계는 불변입니다. 아래는 조언이 아니라 계명!

AI 절대금지 영역

❌ 테스트 파일

# SACRED GROUND
# AI 접근 금지
 def test_critical_business_logic():
    """이 테스트엔 10억짜리 도메인 지식 집약"""
    pass

테스트는 인간 인지, 명세, 누적 지혜의 총체. AI가 테스트를 쓰면, 결국 "코드가 코드를 검증"할 뿐입니다.

❌ DB 마이그레이션

-- migrations/2024_01_15_restructure_users.sql
-- AI 접근 금지
-- 한 줄 실수 = 데이터 손실 = 경력 손실
ALTER TABLE users ADD COLUMN subscription_tier VARCHAR(20);
UPDATE users SET subscription_tier = 'free' WHERE subscription_tier IS NULL;
ALTER TABLE users ALTER COLUMN subscription_tier SET NOT NULL;

프로덕션 마이그레이션은 한 번 실수면 회복 불가! 데이터 패턴, 배포 타이밍, 롤백 모두 고려 필요. AI는 이런 맥락 모릅니다.

❌ 보안·치명 경계 코드

# auth/jwt_validator.py
# 인간만 – 보안 경계
 def validate_token(token: str) -> Optional[UserClaims]:
    # 한 줄 한 줄 보안팀 검증 필요
    # 변경시 보안팀 승인 필수
    # AI 추천은 특히 위험

❌ API 계약(버전관리 없는) 코드

# openapi.yaml
# 잘못하면 전체 클라이언트까지 파급
# AI는 모바일앱 릴리즈 사이클 개념 없음
paths:
   /api/v1/users/{id}:
    get:
      responses:
        200:
          schema:
            $ref: '#/definitions/UserResponse'  # 절대불변

❌ 설정/시크릿

# config/production.py
DATABASE_URL = os.environ["DATABASE_URL"]  # 절대 하드코딩 금지
STRIPE_SECRET_KEY = os.environ["STRIPE_SECRET_KEY"]
FEATURE_FLAGS = {
    "new_pricing": False,  # 제품팀 승인 필요
}

AI 실수 계급표

모든 실수가 동등하지 않습니다:

1단계: 귀찮으나 치명적아님

포맷팅(린터 처리)
장황한 코드(나중에 리팩터링)
비최적화 알고리즘(프로파일링시 개선)

2단계: 복구 비용 큼

내부API 손상(팀 전체 디버깅)
관행 변경(팀 혼란)
불필요 의존성 추가

3단계: 경력 위협/치명적

테스트를 맥락에 맞게 수정
API 계약 깨뜨림
시크릿/PII 노출
데이터 마이그레이션 손상

가드레일은 실수 등급별로 다르게. 1단계는 쥬니어 교육용, 3단계는 LinkedIn 업데이트용!

개발의 미래: 어디로 가는가

2025년 현재, AI 지원 개발은 성장통을 겪고 있습니다. 도구는 강력하나 아직은 미숙한 십대와 같습니다. 그러나 변화는 빠르고, 방향은 명확합니다.

좋은 문서는 DevOps 성공의 기반입니다. ‘문서도 코드’로, CLAUDE.md도 테스트만큼 철저히 관리하는 팀이 결국 승리할 것입니다.

곧 이렇게 변할 것입니다(도입 순서 예측):

무언/비프롬프트 개선 제안 AI
팀의 패턴/스타일을 학습하는 AI
세션/프로젝트 간 영구 메모리
파일 단위가 아닌 코드베이스 전체 파악이 가능한 AI

하지만 핵심은 동일합니다: 인간이 방향을 제시하면, AI가 레버리지 제공. 우리는 도구 사용자—이제 그 도구가 훨씬 강력해졌을 뿐입니다.

결국, 지금 시작해야 할 일

여기까지 읽으셨다면, 설렘+불안이 복합적으로 들 것. 바로 그 반응이 정상입니다. AI 지원 개발은 강력하지만, 규율·의도가 꼭 필요합니다.

오늘:

지금 프로젝트에 CLAUDE.md를 만들기
본인의 가장 고통스러운 코드에 앵커코멘트 3개 직접 달기
명확한 경계 내에서 AI 지원 기능 1개 시도

이번 주:

팀에 AI 커밋 메시지 규칙 도입
쥬니어와 함께 AI-지원 코딩 세션
AI 생성 코드 1개 직접 테스트 작성

이번 달:

AI 도입 전/후 배포 빈도 측정
자주 쓰는 프롬프트 패턴 라이브러리 구축
팀 전체 회고 세션 진행

가장 중요한 건? 그냥, 시작하는 것! 작게 시작하고, 신중하게, 꾸준히. 마스터들은 천재여서가 아니라, 일찍 시도하고 많이 실수했기 때문!

소프트웨어 배송 성과가 조직 성과를 결정합니다. 속도·품질 모두 필요한 이 업계에서, AI 지원은 단순한 옵션이 아닌, 경쟁력의 기반입니다. 단, 옳게 사용해야만 그 효과를 보장합니다.

장난스러운 이름과 달리, vibe-coding은 진지한 비즈니스. 인간의 역량을 증폭시키는 새로운 소프트웨어 개발 방식입니다. 마스터하면 누구보다 빠르게, 더 좋은 소프트웨어를 내놓을 수 있습니다. 외면하면 남들 다 할 때 혼자 boilerplate 쓰며 뒤처질 수도!

도구는 준비됐습니다. 패턴은 검증됐습니다. 이제 남은 건, 내가 지휘자가 될 것인지, 악기 하나하나 직접 연주만 하고 있을지 뿐.

시작할 준비 됐나요? 참고 자료

📄 실전 CLAUDE.md 템플릿: github.com/julep-ai/julep/blob/main/AGENTS.md

🤝 문의는 Twitter: @diwanksingh

💬 토론 참여: 직접 경험 패턴 공유

📚 추천도서:

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

기억하세요: 완벽은 배송의 적! 작은 프로젝트 하나서 경계부터 정하고, 반복하세요. 개발의 미래는 이미 와 있습니다—다만 아직 ‘균등하게’ 퍼지진 않았을 뿐.

배포를 리드하는 시대의 일원이 되세요.

00:00 / 00:00

NotebookLM Podcast 본문 ↩︎ 2. 위 통계는 Nicole Forsgren, Jez Humble, Gene Kim의 “Accelerate: The Science of Lean Software and DevOps”에서 따옴.

저자들은 4년에 걸친 엄격한 연구(31,000명/2,000+개 조직)를 통해 고성과와 저성과 조직의 차이를 조사했습니다.

구체적 통계: 상위성과 vs. 저성과 비교

46배 더 많은 배포
커밋→배포 440배 ↗
평균 복구시간 170배 빠름
변경 실패율 5배↓

"Accelerate"의 결론: 도구보다 관행이 중요. AI도 마찬가지! 연속통합·테스트·메인라인 개발·모니터링 등 관행 없인 수치 효과가 안나옵니다. CLAUDE.md, 직접작성 테스트, 경계설정이 바로 이 시대의 관행. ↩︎ 3. Andrej Karpathy는 테슬라, OpenAI 출신 AI 전문가. https://karpathy.ai/↩︎ 4. ↩︎ 5. Steve Yegge는 유명 개발자·블로거. https://en.wikipedia.org/wiki/Steve_Yegge ↩︎ 6. 여기서 말하는 'submodule'은 git submodule이 아님! AI코딩과 조합은 피하세요.↩︎

Vibe Engineering

Vibe 코딩은 그냥 Vibe가 아니다

Image 1: Shimmering Substance - Jackson Pollock Shimmering Substance - Jackson Pollock

참고: 이 글에는 NotebookLM 팟캐스트(1), 그리고 _세 개_의 생성된 오디오 녹음이 함께 제공됩니다.

이 글을 준비하며 ChatGPT와 나눈 대화 기록도 읽어볼 수 있습니다.

관련 HN 포스트에서 댓글과 토론도 확인하세요.

이 글에서 무엇을 배우게 될까?

핵심 통찰: 좋은 개발 습관은 선택이 아니라 필수다. 이것이 AI가 당신의 역량을 증폭시키는 비결이며, 그렇지 않으면 혼란만 키울 뿐입니다. 실제 연구가 이를 뒷받침합니다. 2엄격한 개발 관행을 지키는 팀은 배포 빈도가 46배 높고, 커밋에서 배포까지 440배 더 빠릅니다. 강력한 AI가 추가되면 이 효과는 더욱 커집니다.

왜 이 글을 쓰게 되었나: 밈에서 방법론으로

Image 3: The birth of “vibe coding” “vibe coding”의 탄생

Claude 사용할 때 제대로 된 가드레일 없이 접근하면, 과도하게 열정적인 인턴과 두더지잡기 게임을 하는 셈입니다.

Vibe-Coding이란 무엇인가

Image 4: ‘pls fix’ ‘pls fix’

vibe-coding에는 개발 단계별로 적합한 아래 세 가지 태도가 있습니다:

AI를 초안작성자(First-Drafter)로: AI가 초초안을 자동 생성, 개발자는 설계·구조에 집중. 생각보다 빠른 타자 속도의 쥬니어가 늘 옆에 있는 느낌. 반복 작업과 CRUD 등에 적합함.
AI를 페어프로그래머로: 개발의 핵심. 함께 아이디어를 나누고, AI가 방법을 제안하면 내가 다듬고, 뼈대만 주면 AI가 채워감. 모든 프로그래밍책을 읽었지만 코드 '배송'은 해본 적 없는 파트너와 페어하는 느낌.
AI를 검증자(Validator)로: 내가 코드를 쓰면 sanity check해줌. 버그 찾기, 개선 제안, 놓치기 쉬운 패턴을 집어줌. 무한 체력의 코드 리뷰어 같음.

한줄 한줄 만드는 게 아니라, 리뷰·수정·지휘에 집중하는 셈이죠. 하지만 중요한 건, 아키텍트는 여전히 본인! Claude는 맥락은 없지만 지식은 방대한 인턴에 불과합니다.

vibe-coding 실전: 세 가지 프레임워크

수개월의 실험과 여러 번의 실전 사고(!) 이후, 저는 아래 세 가지 모드를 도출했습니다. 각기 리듬과 가드레일, 사용 장면이 다릅니다.

모드 1: Playground (놀이터)

이미지 5: 라이터액체 라이터액체

언제? 주말 해킹, 개인 스크립트, 프로토타입, “이거 되려나?” 같은 실험용

모드 2: 페어프로그래밍

이미지 6: 컴파일 중 컴파일 중

언제? 코드 5,000줄 미만 사이드 프로젝트, 실제 사용자 있는 데모, 잘 분리된 소규모 서비스 등

CLAUDE.md는 Claude가 자동 참조하는 특수 문서입니다:

자주 쓰는 bash 명령어

핵심 파일 및 유틸리티

코드 스타일 가이드라인

테스트 지침

저장소 규칙(브랜치 이름, 머지/리베이스 등)

기억시킬 추가 정보 등

프로젝트 관행을 일일이 설명하는 대신, 한 번만 문서에 적으면 끝. 실제 예시:

## Project: Analytics Dashboard  
이건 Next.js 대시보드입니다.  

### Architecture Decisions  
- 기본 Server Components, 꼭 필요할 때만 Client Components  
- tRPC로 타입 안정 API 호출  
- Prisma: 쿼시 select 지정 필수  
- Tailwind만 사용(커스텀 CSS 금지)

### Code Style  
- Prettier: 100자 라인  
- 단순-import-sort로 정렬  
- 컴포넌트: Pascal Case, 테스트와 코로케이션  
- 훅: 'use' 프리픽스 필수

### Patterns to Follow  
- 데이터 패칭은 서버 컴포넌트에서  
- 클라이언트 컴포넌트엔 props로 데이터 전달  
- 외부 데이터는 Zod 스키마 필수  
- 모든 데이터 컴포넌트에 error boundary 추가

### What NOT to Do  
- 데이터 패칭용 useEffect 사용 금지  
- 승인 없이 글로벌 상태 생성 금지  
- any 타입 자제

이런 맥락이 준비되면 Claude의 효율성이 극도로 높아집니다. 매일 신규입사자 온보딩 시키는 게 아니라, 한 번에 문서를 준 셈!

단, _페어프로그래밍 모드_는 문서만으론 부족. AI에 ‘앵커 코멘트(anchor comments)’라는 단서도 꼭 남깁니다. Claude가 산으로 가는 걸 막는 내비게이션:

js
// AIDEV-NOTE: 이 컴포넌트는 가상 스크롤 사용(https://tanstack.com/virtual/latest 참고)
// 일반 map 변환 금지—1만개 이상 처리
export function DataTable({ items }: DataTableProps) {
  // Claude, 수정시 가상 스크롤 구조 꼭 유지!
  ...
}

## Anchor comments  

코드 곳곳에, 필요시, 본인 또는 AI를 위한 인라인 지식으로 특수형식 주석을 추가.  

### 지침:  
- AI·개발자 모두를 위한 코멘트엔 `AIDEV-NOTE:`, `AIDEV-TODO:`, `AIDEV-QUESTION:` (대문자) 접두어 사용  
- 최대 120자 내외로 간단하게  
- **중요:** 파일 스캔 전, 반드시 관련 하위 디렉토리에 ‘AIDEV-*’ 앵커 코멘트 있는지 우선 검색
- 코드 수정시 관련 앵커 업데이트 필수  
- **앵커 코멘트는 직접 삭제 말고 반드시 지시 필요**

예시:
# AIDEV-NOTE: perf-hot-path; 추가 할당 자제(ADR-24 참고)
async def render_feed(...):
    ...

모드 3: 프로덕션/모노레포 규모

이미지 8: RTFM RTFM

언제? 대형 코드베이스, 실제 사용자가 있는 시스템, 결함이 돈이나 명성에 직결되는 곳

Claude는 대량의 코드를 생성할 수 있지만, 복잡한 시스템에 통합하는 것은 매우 세심한 오케스트레이션이 필요합니다.

# AIDEV-NOTE: API Contract Boundary - v2.3.1  
# 모든 변경에는 버전업과 마이그레이션 플랜 필수  
# docs/api-versioning.md 참고

@router.get("/users/{user_id}/feed")  
async def get_user_feed(user_id: UUID) -> FeedResponse:  
    # Claude: 여기는 응답 shape 절대 변경 금지  
    # 변경시 실제 앱 전부 깨짐
    ...

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

`CLAUDE.md`: 진리의 소스

명확히 밝힙니다: CLAUDE.md는 선택사항이 아닌 필수! 한 번 업데이트할 때마다, 나중에 1시간의 대청소를 절약합니다.

수천 커밋 이상 걸쳐 적립, 다듬은 우리 프로덕션 CLAUDE.md 구조 일부 예시:

# `CLAUDE.md` - Julep Backend Service  

## The Golden Rule  
불확실하면 반드시 개발자에게 물어볼 것  

## Project Context  
Julep은 선언적 워크플로우로 상태 유지형 AI agent 개발 지원

## Critical Architecture Decisions  

### Why Temporal?  
- 장기(수 일/수주) 워크플로우 신뢰성 유지  
- 실패 대비 자동 복구

### Why PostgreSQL + pgvector?  
- ACID 준수로 사용자 상태 손실 없음  
- 벡터 서칭으로 agent 메모리 관리

### Why TypeSpec?  
- API 명세 단일 소스(오픈API,타입스크립트·파이썬클라이언트,검증스키마)

## Code Style and Patterns  

### Anchor comments  

코드 곳곳에 필요시, 본인·AI 위한 인라인 지식 주석 추가

### Guidelines:  

- AI·개발자 모두 대상 주석: 대문자 접두사 사용(AIDEV-NOTE:,AIDEV-TODO:,AIDEV-QUESTION:)
- **중요:** 파일 스캔 전, 반드시 관련 하위디렉토리 'AIDEV-*' 앵커 먼저 grep
- 관련 코드 수정시 앵커도 반드시 최신화  
- `AIDEV-NOTE` 삭제는 명시적 인간 지시 있어야  
- 복잡/중요/혼란 가능/버그 우려시엔 앵커 주석 필수

## Domain Glossary (Claude, 꼭 익혀라!)  
- **Agent**: 메모리·도구·행동정의 갖춘 AI 엔티티  
- **Task**: 단계 기반 워크플로우(셀러리 task 아님)  
- **Execution**: task 인스턴스 실행  
- **Tool**: agent가 호출 가능한 함수 등  
- **Session**: 메모리 갖춘 대화 컨텍스트  
- **Entry**: 세션 내 단일 상호작용

## AI가 절대 하면 안 되는 것  
1. 테스트 파일 수정 금지 – 테스트는 사람의 의도
2. API 계약 변경 금지 – 실제 앱 깨짐
3. 마이그레이션 파일 변경 금지 – 데이터 손실
4. 시크릿 커밋 금지 – 환경변수 활용
5. 비즈니스 로직 임의 해석 금지 – 항상 질문
6. AIDEV- 코멘트 삭제 금지 – 이유 있음

우리는 '트릭'보다 '유지보수성'을 항상 우선.
애매하면, 심플하게 간다.

이 문서는 Claude와 나, 개발자 모두의 공유 맥락이 됩니다.

코드베이스가 커질수록 CLAUDE.md만으론 부족. 이때는 앵커 코멘트(주석)로 인라인 맥락 제공이 중요합니다.

코드베이스를 도시로, 앵커 코멘트를 거리 표지판으로 생각해보세요. 표지판이 없다면 똑똑한 방문자도 길을 잃죠. 사용 예시:

# AIDEV-NOTE: 매우 중요한 퍼포먼스 경로 - 10만 req/sec 처리
# 데이터베이스 쿼리 여기선 금지!
def get_user_feed(user_id: UUID, cached_data: FeedCache) -> List[FeedItem]:
    # 캐시 데이터 변형 금지
    items = cached_data.items[:]

    # AIDEV-TODO: 페이지네이션 구현(ticket: 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 worktrees 추천합니다:

# 메인 브랜치 오염 없는 AI 놀이터 만들기
git worktree add ../ai-experiments/cool-feature -b ai/cool-feature

# Claude 자유 실험
tcd ../ai-experiments/cool-feature
# … 실험 커밋 쌓기 …

# 쓸만한 결과 cherry-pick으로 main에 반영
cd ../main-repo
git cherry-pick abc123

# 다 쓰고 정리
git worktree remove ../ai-experiments/cool-feature

추가팁: worktree 실전 가이드도 읽어보시고, wt 툴도 참고하세요.

이 방법으로 Claude 실험은 마음껏, 메인 브랜치는 깨끗하게!

커밋 메시지는 AI 지원 커밋임을 태그로 통일합니다:

feat: implement user feed caching [AI]

- Add Redis-based cache for user feeds
- Implement cache warming on user login
- Add metrics for cache hit rate

AI-assisted: 핵심 로직은 AI 생성, 테스트는 직접 작성

이렇게 하면 리뷰어는 AI가 생성한 부분을 더욱 면밀히 살필 수 있습니다.

신성한 원칙: 테스트는 무조건 사람이 직접 작성

AI 지원 개발의 가장 중요한 원칙입니다. 여러 번 강조해도 지나치지 않아요:

Never. Let. AI. Write. Your. Tests.

이미지 9: 조심하라… 조심하라…

예를 들어봅니다. Claude에게 rate limiter를 구현하라 했다고 칩시다:

class RateLimiter:  
    def __init__(self, max_requests: int, window_seconds: int):  
        self.max_requests = max_requests  
        self.window_seconds = window_seconds  
        self.requests = defaultdict(list)  

    def is_allowed(self, user_id: str) -> bool:  
        now = time.time()  
        user_requests = self.requests[user_id]  

        # Clean old requests  
        self.requests[user_id] = [  
            req_time for req_time in user_requests  
            if now - req_time < self.window_seconds  
        ]  

        if len(self.requests[user_id]) < self.max_requests:  
            self.requests[user_id].append(now)  
            return True  
        return False

겉보기에 그럴듯하고, Claude는 테스트도 생성해줍니다:

def test_rate_limiter():  
    limiter = RateLimiter(max_requests=3, window_seconds=60)  

    assert limiter.is_allowed("user1") == True  
    assert limiter.is_allowed("user1") == True  
    assert limiter.is_allowed("user1") == True  
    assert limiter.is_allowed("user1") == False  # Limit reached

이미지 10: vibe coding의 끝판왕 vibe coding at its best

그래서 테스트는 사람이 직접 쓰는 게 필수! 우리는 문맥, 운영환경, 초기 경험, 진짜 중요 엣지 케이스를 이해합니다. Julep 규칙은 절대적입니다:

## Testing Discipline  

| What | AI CAN Do | AI MUST NOT Do |  
|------|-----------|----------------|  
| Implementation | Generate business logic | Touch test files |  
| Test Planning | Suggest test scenarios | Write test code |  
| Debugging | Analyze test failures | Modify test expectations |  

AI가 테스트 파일을 건드리면 PR 거부, 예외 없음.

테스트는 명세, 안전망, 누적 지혜. 반드시 신성하게 지키세요.

스케일링의 실전: 토큰 경제와 컨텍스트 관리

빈약 프롬프트의 허상 예시:

빈약한 프롬프트:

"Add caching to the user endpoint"

Claude의 동작:

메모리 캐시만 도입(멀티서버에서 문제)
캐시 만료 및 전략 없음
모니터링 빠짐
캐시 스탬피드 케어 없음

→ 수정이 3번 반복, 총 토큰 4배 소모

충분한 맥락 제공 프롬프트:

GET /users/{id} 엔드포인트에 Redis 캐싱 추가
컨텍스트:
- 초당 5만 요청 
- API서버 12대 LB운용
- 데이터 변경 적음(하루 몇번)
- 이미 Redis 있음: cache.redis.internal:6379
- 캐시키패턴: "user:v1:{id}"
- Prometheus로 캐시 hit/miss 측정
- 1시간 TTL 캐시 어사이드 패턴 사용
- 캐시 스탬피드: early expiration 처리
caching.md 참고

교훈: 좋은 맥락을 처음에 제공해라! 반복 작업/수정(Iterate) 줄이고, 토큰은 좋은 도구에 투자한다고 생각하세요.

실제로 전 프로젝트마다 Claude로 변화 내역 검토 후, CLAUDE.md에 맥락을 보강하는 루틴을 권장합니다.

신선한 세션과 멘탈모델 유지

또 하나의 역설: 각각의 작업마다 새로운 Claude 세션을 사용하세요. 대화 하나만 길게 이어가면 맥락 오염이 생깁니다.

이유: 생닭 썬 도마로 바로 채소를 자르지 않듯, DB 마이그레이션 내용을 다룬 직후에 스타일 프론트엔드를 같은 세션에서 논하는 건 위험!

규칙: 한 작업, 한 세션. 작업 끝나면 새로 시작. Claude의 멘탈모델을 깨끗하고 집중력 있게 유지하세요.

실전: 프로덕션 Structured Error 배송 사례

사람의 결정(Why):

에러 분류(taxonomy) 결정은 100% 설계/비즈니스 맥락! Claude는 이걸 판단 못합니다. 대표 사양 예시:

# SPEC.md - Error Hierarchy Design (Human-Written)

## Error Philosophy
- 4xx(클라이언트) 오류는 반드시 actionable 메시지 제공
- 5xx(서버) 오류엔 trace ID 필수
- 무조건 JSON 직렬화
- 에러코드는 반드시 고정(클라이언트 사용)

## Hierarchy
BaseError
├── ClientError (4xx)
│   ├── ValidationError
│   │   ├── SchemaValidationError
│   │   ├── BusinessRuleError
│   │   └── RateLimitError
│   └── AuthError
│       ├── AuthenticationError
│       └── AuthorizationError
└── SystemError (5xx)
    ├── DatabaseError
    ├── ExternalServiceError
    └── InfrastructureError

## Error Response Format
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Email already exists",
    "details": { ... },
    "trace_id": "abc-123-def"
  }
}

AI의 실행(How):

이제 사양이 명확하니, Claude에게 반복 리팩토링을 맡깁니다:

### Claude에 준 프롬프트:
SPEC.md에 맞춰 오류 처리 리팩토링. auth 모듈을 가장 먼저. 플랜 보여주고 시작.

Claude가 짠 플랜:

error 계층을 common/errors.py 생성
오류 응답 포매터 작성
모든 모듈 systematic하게 업데이트
error handling 미들웨어 설치

그리고 500개 이상 사용처 전부 실수 없이 자동변경(사람은 리뷰 집중):

# Before
if not user:
    raise Exception("User not found")

# After
if not user:
    raise AuthenticationError(
        message="User not found",
        code="USER_NOT_FOUND",
        details={"identifier": email}
    )

CLAUDE.md·문서·앵커 주석·명확 가이드가 뒷받침되면:

총 시간: 4시간(직접 했으면 2일)

적용범위: 500+ 위치 실시간 자동반영

AI 시대 리더십과 문화

린 매니지먼트·지속적 배포 같은 현대적 실천이 소프트웨어/조직 전체 성과를 증대합니다. AI 협업 관리도 예외가 아닙니다.

새 온보딩 체크리스트

신규 개발자 입사 땐 아래처럼 두 가지(사람/AI) 온보딩 트랙을 제공합니다.

1주: 기본기 세우기

□ 팀 CLAUDE.md(루트→서비스별) 읽기
□ 개발환경 세팅
□ 첫 PR 직접 작성(AI 도움없이)

2주: 가이드 하에 AI 협업 시작

□ Claude에 팀 템플릿 적용
□ 토이문제 AI와 함께 완성해보기
□ 대표 프롬프트 패턴 연습
□ 첫 AI-assisted PR 제출(멘토 동행)

3주: 독립작업

□ 첫 메이저 AI 지원 기능 배송
□ 동료 AI코드의 테스트 커버 작성
□ 코드리뷰 1회 주도

투명성 문화 만들기

중요한 문화 변화 중 하나: AI 지원 여부를 당당히 드러내는 것입니다. 숨기지 말고, 책임 있게 씁니다. 모든 AI 작업 커밋에는 태그 부착:

# .gitmessage 템플릿
# feat/fix/docs: <설명> [AI]?
#
# [AI] - 50% 이상 AI 생성
# [AI-minor] - 50% 미만 AI 생성
# [AI-review] - AI는 코드 리뷰에만 동원
#
# 예시:
# feat: user service에 Redis 캐싱 추가 [AI]
#
# AI: 캐싱 구현/Redis 클라이언트 세팅 자동 생성
# 사람: 캐시 키 설계·테스트 직접 작성
# 캐시 만료 직접 검증

이 투명성의 효과:

리뷰어가 더 꼼꼼히 체크
디버깅시 코드 출처 식별 쉬움
AI 사용에 대한 불쾌감/수치심 최소화

즉, 누구나 AI를 책임감 있게 활용할 수 있는 안전망 제공이 곧 고성과 조직의 비결입니다.

Claude가 절대 건드리면 안 되는 것(절대불변)

경계는 불변입니다. 아래는 조언이 아니라 계명!

AI 절대금지 영역

❌ 테스트 파일

# SACRED GROUND
# AI 접근 금지
 def test_critical_business_logic():
    """이 테스트엔 10억짜리 도메인 지식 집약"""
    pass

테스트는 인간 인지, 명세, 누적 지혜의 총체. AI가 테스트를 쓰면, 결국 "코드가 코드를 검증"할 뿐입니다.

❌ DB 마이그레이션

-- migrations/2024_01_15_restructure_users.sql
-- AI 접근 금지
-- 한 줄 실수 = 데이터 손실 = 경력 손실
ALTER TABLE users ADD COLUMN subscription_tier VARCHAR(20);
UPDATE users SET subscription_tier = 'free' WHERE subscription_tier IS NULL;
ALTER TABLE users ALTER COLUMN subscription_tier SET NOT NULL;

프로덕션 마이그레이션은 한 번 실수면 회복 불가! 데이터 패턴, 배포 타이밍, 롤백 모두 고려 필요. AI는 이런 맥락 모릅니다.

❌ 보안·치명 경계 코드

# auth/jwt_validator.py
# 인간만 – 보안 경계
 def validate_token(token: str) -> Optional[UserClaims]:
    # 한 줄 한 줄 보안팀 검증 필요
    # 변경시 보안팀 승인 필수
    # AI 추천은 특히 위험

❌ API 계약(버전관리 없는) 코드

# openapi.yaml
# 잘못하면 전체 클라이언트까지 파급
# AI는 모바일앱 릴리즈 사이클 개념 없음
paths:
   /api/v1/users/{id}:
    get:
      responses:
        200:
          schema:
            $ref: '#/definitions/UserResponse'  # 절대불변

❌ 설정/시크릿

# config/production.py
DATABASE_URL = os.environ["DATABASE_URL"]  # 절대 하드코딩 금지
STRIPE_SECRET_KEY = os.environ["STRIPE_SECRET_KEY"]
FEATURE_FLAGS = {
    "new_pricing": False,  # 제품팀 승인 필요
}

AI 실수 계급표

모든 실수가 동등하지 않습니다:

1단계: 귀찮으나 치명적아님

포맷팅(린터 처리)
장황한 코드(나중에 리팩터링)
비최적화 알고리즘(프로파일링시 개선)

2단계: 복구 비용 큼

내부API 손상(팀 전체 디버깅)
관행 변경(팀 혼란)
불필요 의존성 추가

3단계: 경력 위협/치명적

테스트를 맥락에 맞게 수정
API 계약 깨뜨림
시크릿/PII 노출
데이터 마이그레이션 손상

가드레일은 실수 등급별로 다르게. 1단계는 쥬니어 교육용, 3단계는 LinkedIn 업데이트용!

개발의 미래: 어디로 가는가

2025년 현재, AI 지원 개발은 성장통을 겪고 있습니다. 도구는 강력하나 아직은 미숙한 십대와 같습니다. 그러나 변화는 빠르고, 방향은 명확합니다.

좋은 문서는 DevOps 성공의 기반입니다. ‘문서도 코드’로, CLAUDE.md도 테스트만큼 철저히 관리하는 팀이 결국 승리할 것입니다.

곧 이렇게 변할 것입니다(도입 순서 예측):

무언/비프롬프트 개선 제안 AI
팀의 패턴/스타일을 학습하는 AI
세션/프로젝트 간 영구 메모리
파일 단위가 아닌 코드베이스 전체 파악이 가능한 AI

하지만 핵심은 동일합니다: 인간이 방향을 제시하면, AI가 레버리지 제공. 우리는 도구 사용자—이제 그 도구가 훨씬 강력해졌을 뿐입니다.

결국, 지금 시작해야 할 일

여기까지 읽으셨다면, 설렘+불안이 복합적으로 들 것. 바로 그 반응이 정상입니다. AI 지원 개발은 강력하지만, 규율·의도가 꼭 필요합니다.

오늘:

지금 프로젝트에 CLAUDE.md를 만들기
본인의 가장 고통스러운 코드에 앵커코멘트 3개 직접 달기
명확한 경계 내에서 AI 지원 기능 1개 시도

이번 주:

팀에 AI 커밋 메시지 규칙 도입
쥬니어와 함께 AI-지원 코딩 세션
AI 생성 코드 1개 직접 테스트 작성

이번 달:

AI 도입 전/후 배포 빈도 측정
자주 쓰는 프롬프트 패턴 라이브러리 구축
팀 전체 회고 세션 진행

가장 중요한 건? 그냥, 시작하는 것! 작게 시작하고, 신중하게, 꾸준히. 마스터들은 천재여서가 아니라, 일찍 시도하고 많이 실수했기 때문!

도구는 준비됐습니다. 패턴은 검증됐습니다. 이제 남은 건, 내가 지휘자가 될 것인지, 악기 하나하나 직접 연주만 하고 있을지 뿐.

시작할 준비 됐나요? 참고 자료

📄 실전 CLAUDE.md 템플릿: github.com/julep-ai/julep/blob/main/AGENTS.md

🤝 문의는 Twitter: @diwanksingh

💬 토론 참여: 직접 경험 패턴 공유

📚 추천도서:

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

배포를 리드하는 시대의 일원이 되세요.

00:00 / 00:00

NotebookLM Podcast 본문 ↩︎ 2. 위 통계는 Nicole Forsgren, Jez Humble, Gene Kim의 “Accelerate: The Science of Lean Software and DevOps”에서 따옴.

저자들은 4년에 걸친 엄격한 연구(31,000명/2,000+개 조직)를 통해 고성과와 저성과 조직의 차이를 조사했습니다.

구체적 통계: 상위성과 vs. 저성과 비교

46배 더 많은 배포
커밋→배포 440배 ↗
평균 복구시간 170배 빠름
변경 실패율 5배↓

Vibe Engineering

Claude로 실제 코드 배송하며 얻은 필드 노트

Vibe 코딩은 그냥 Vibe가 아니다

이 글에서 무엇을 배우게 될까?

왜 이 글을 쓰게 되었나: 밈에서 방법론으로

Vibe-Coding이란 무엇인가

vibe-coding 실전: 세 가지 프레임워크

모드 1: Playground (놀이터)

모드 2: 페어프로그래밍

모드 3: 프로덕션/모노레포 규모

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

CLAUDE.md: 진리의 소스

AI 개발을 위한 Git 워크플로우

신성한 원칙: 테스트는 무조건 사람이 직접 작성

스케일링의 실전: 토큰 경제와 컨텍스트 관리

신선한 세션과 멘탈모델 유지

실전: 프로덕션 Structured Error 배송 사례

AI 시대 리더십과 문화

새 온보딩 체크리스트

투명성 문화 만들기

Claude가 절대 건드리면 안 되는 것(절대불변)

AI 절대금지 영역

AI 실수 계급표

개발의 미래: 어디로 가는가

결국, 지금 시작해야 할 일

시작할 준비 됐나요? 참고 자료

관련 추천 글

첫 시도는 95%가 쓰레기다: 스태프 엔지니어의 Claude Code 6주 여정 | Sanity

내가 Claude Code를 쓰는 방법

Claude 코드 베스트 프랙티스

Claude Code는 어떻게 만들어졌나

Vibe 코딩은 그냥 Vibe가 아니다

이 글에서 무엇을 배우게 될까?

왜 이 글을 쓰게 되었나: 밈에서 방법론으로

Vibe-Coding이란 무엇인가

vibe-coding 실전: 세 가지 프레임워크

모드 1: Playground (놀이터)

모드 2: 페어프로그래밍

모드 3: 프로덕션/모노레포 규모

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

CLAUDE.md: 진리의 소스

AI 개발을 위한 Git 워크플로우

신성한 원칙: 테스트는 무조건 사람이 직접 작성

스케일링의 실전: 토큰 경제와 컨텍스트 관리

신선한 세션과 멘탈모델 유지

실전: 프로덕션 Structured Error 배송 사례

AI 시대 리더십과 문화

새 온보딩 체크리스트

투명성 문화 만들기

Claude가 절대 건드리면 안 되는 것(절대불변)

AI 절대금지 영역

AI 실수 계급표

개발의 미래: 어디로 가는가

결국, 지금 시작해야 할 일

시작할 준비 됐나요? 참고 자료

관련 추천 글

첫 시도는 95%가 쓰레기다: 스태프 엔지니어의 Claude Code 6주 여정 | Sanity

내가 Claude Code를 쓰는 방법

Claude 코드 베스트 프랙티스

Claude Code는 어떻게 만들어졌나

`CLAUDE.md`: 진리의 소스

`CLAUDE.md`: 진리의 소스