실제 프로덕션 프로젝트에 Claude Code를 설정해 보았습니다. 실제로 가치를 증명한 것들

모두가 "10가지 AI 코딩 비법" 같은 글을 올립니다. 이 글은 그런 것이 아닙니다. 이 글은 실제 프로젝트 — 미용실을 위한 이중 언어 예약 봇 (Telegram + WhatsApp, Postgres, Google Calendar) — 에 Claude Code를 3주 동안 실행한 후, 새로움이 사라지고 유용한 부분들만 살아남은 결과물입니다.

기본적으로 Claude Code는 기억상실증에 걸린 매우 똑똑한 인턴과 같습니다. 매 세션마다 아주 명석하면서도 동시에 아무것도 모르는 상태로 나타납니다. 핵심은 그 '아무것도 모르는 부분'을 해결하는 것입니다. 저에게는 네 가지가 그 역할을 해주었습니다: CLAUDE.md 파일, 두 개의 커스텀 에이전트 (custom agents), 하나의 스킬 (skill), 그리고 두 개의 훅 (hooks)입니다. 그 외에 제가 시도했던 다른 모든 것들은 삭제했습니다.

CLAUDE.md: 매일 임대료를 지불하는 파일

CLAUDE.md는 레포지토리(repo) 루트에 위치하며 매 세션이 시작될 때 읽힙니다. 제 파일은 처음에는 세 줄로 시작했습니다. 어시스턴트가 제가 되돌려야 했던 작업을 수행할 때마다 파일은 커졌습니다.

솔직히 말해서 그것이 비결입니다. CLAUDE.md를 미리 작성하지 마세요. 실패로부터 키워나가세요. 제 파일에는 현재 다음과 같은 내용들이 포함되어 있습니다:

## Architecture rules (아키텍처 규칙)
- 비즈니스 로직은 src/core/에 위치하며 Telegram이나 WhatsApp에 대해 알면 안 됩니다. 채널 코드는 src/adapters/에 위치합니다.
...

이 각각의 줄은 어시스턴트가 한 번이라도 그 반대로 행동했기 때문에 존재합니다. 어시스턴트가 코어 로직에 Telegram 전용 코드를 넣었습니다 — 새로운 규칙 추가. 어시스턴트가 저장 시점에 변환하는 방식으로 타임존 (timezone) 버그를 "수정"했습니다 — 새로운 규칙 추가. 어시스턴트가 타입 (types) 오류가 있는 상태로 "완료"되었다고 보고했습니다 — 새로운 규칙 추가.

3주가 지난 지금, 저는 지시 사항을 거의 반복하지 않습니다. 그 파일은 어시스턴트와 금붕어의 차이를 만듭니다.

Custom agents: 내가 논쟁하는 리뷰어

커스텀 에이전트 (Custom agents)는 .claude/agents/ 폴더 내에 시스템 프롬프트 (system prompt)를 포함한 마크다운 (markdown) 파일로 존재합니다. 특정 작업을 위해 에이전트를 호출하면, 에이전트는 자신만의 지침과 도구 제한 (tool limits)을 가지고 작업을 수행하며, 메인 세션의 컨텍스트 (context)를 오염시키지 않습니다.

매일 제 몫을 다하는 에이전트는 코드 리뷰어 (code reviewer)입니다:

---
name: code-reviewer
description: "버그 및 보안 문제를 위해 변경 사항을 검토합니다"
...

핵심은 그것이 모든 것을 잡아낸다는 것이 아닙니다. 핵심은 단 하나의 작업만을 수행하는 _다른 컨텍스트 (different context)_라는 점입니다. 메인 세션 (main session)은 코드를 작성했기에 해당 코드를 선호하는 편향 (bias)을 가집니다. 반면 리뷰어 에이전트 (reviewer agent)는 객관적인 상태에서 코드를 읽습니다. 메인 세션이 그냥 지나쳤던 것들을 리뷰어 에이전트는 정기적으로 잡아냅니다. 예를 들어, 서명 (signature)을 확인하지 않고 message_id를 신뢰한 웹훅 핸들러 (webhook handler)나, 자정(midnight)을 기점으로 오류가 발생하는 슬롯 계산 (slot calculation) 같은 것들 말입니다.

이 에이전트는 제 클라이언트의 고객들이 발견하기 전에 자정 버그를 찾아냈습니다. 그 에이전트 하나가 전체 설정 비용을 뽑고도 남았습니다.

단계를 건너뛰지 않게 해주는 기술 (Skill)

기술 (Skills)은 재사용 가능한 워크플로 (workflows)입니다. 즉, 어시스턴트 (assistant)를 호출할 때 어시스턴트가 따를 절차를 기술한 SKILL.md 파일입니다. 저에게 정말 중요한 기술은 딱 하나, /add-feature뿐입니다:

우리가 무엇을 만들고 있는지 다시 진술하고 확인합니다.
변경될 파일 목록과 그 이유를 나열합니다. 가능한 가장 작은 차이 (diff)를 지향합니다.
CLAUDE.md를 준수하며 구현합니다.
변경된 유닛 (units)에 대한 테스트를 작성합니다.
차이 (diff)에 대해 code-reviewer 에이전트를 실행합니다. 발견된 문제를 수정합니다.
요약합니다: 무엇이 변경되었는지, 어떻게 테스트하는지, 그리고 제가 수동으로 해야 할 작업은 무엇인지.

특별히 영리한 것은 없습니다. 그저 체크리스트 (checklist)일 뿐입니다. 하지만 체크리스트에는 중요한 점이 있습니다. 하루의 다섯 번째 기능을 만들 때쯤이면, _저_라면 리뷰 단계를 건너뛰었을 것이라는 점입니다. 기술 (skill)은 밤 11시가 되어도 지치지 않습니다. 조종사들은 이미 수십 년 전에 이 사실을 깨달았습니다. 우리는 그저 뒤늦게 따라가고 있을 뿐입니다.

훅 (Hooks): 두 줄짜리 보험 정책

훅 (Hooks)은 이벤트 발생 시 셸 명령 (shell commands)을 실행합니다. 저는 두 가지만 필요합니다.

첫 번째는 보안 파일 (secrets files)에 대한 모든 수정을 차단하는 것입니다. 어시스턴트는 .env 파일을 건드릴 이유가 전혀 없으며, 이제는 물리적으로도 건드릴 수 없습니다. PreToolUse 훅이 파일 경로를 확인하고, 보안 파일로 보이면 에러를 내며 종료됩니다. 작성하는 데 5분밖에 걸리지 않았습니다. 리팩터링 (refactor) 과정에서 어시스턴트가

두 번째는 모든 파일 수정 후에 타입 체크 (typecheck)를 실행하고, 발생한 문제들을 세션으로 즉시 전달합니다. 어시스턴트는 타입 에러를 마지막에 발견하는 대신 즉시 확인하며, 이는 컨텍스트 (context)가 살아있는 동안 에러를 수정할 수 있음을 의미합니다. 이 한 가지 변화만으로도 "완료되었다고 했지만 아무것도 컴파일되지 않는" 상황의 발생률이 거의 0으로 줄었습니다.

{
  "hooks": {
    "PreToolUse": [{
...

시도했다가 삭제한 것들

솔직하게 말씀드리자면: 커밋 메시지 작성을 위한 에이전트 (메인 세션이 이미 잘 수행함), 배포를 위한 스킬 (자동화하기에는 너무 위험하며, 직접 제어하고 싶음), 그리고 모든 수정 시마다 전체 테스트 스위트 (test suite)를 자동으로 실행하는 훅 (hook)도 만들어 보았습니다 (모든 작업 속도가 너무 느려졌습니다. 타입 체크가 적절한 입도(granularity)이며, 전체 테스트는 리뷰 단계에서 실행하는 것이 맞습니다).

설정의 한 부분이 매일 무언가를 아껴주지 못한다면, 그것은 설정 (configuration)이 아니라 불필요한 잡동사니 (clutter)입니다.

솔직한 요약

설정되지 않은 Claude Code는 매일이 첫 출근인 유능한 프리랜서와 같습니다. 실패를 통해 성장시킨 CLAUDE.md, 냉철한 리뷰어 에이전트 하나, 체크리스트 스킬 하나, 그리고 두 개의 훅이 더해지면, 프로젝트에 한 달 동안 참여한 동료에 더 가까워집니다.

설정에는 며칠에 걸쳐 총 2시간 정도가 소요되었으며, 대부분 저를 짜증 나게 했던 요소들에 대한 대응으로 이루어졌습니다. 그 보상으로, 저는 이제 저녁 시간에 혼자서도 품질 저하 없이 프로덕션 봇의 기능들(결제, 알림, 대기 목록 등)을 배포할 수 있게 되었습니다.

CLAUDE.md부터 시작하세요. 잡았어야 했던 버그를 놓치는 것을 처음 발견했을 때 리뷰어 에이전트를 추가하세요. 나머지는 여러분 자신의 실패를 통해 키워나가세요. 어쨌든 그것들이 제 목록보다 더 좋은 스승이 될 것입니다.