지난주에 3시간짜리 리팩토링을 40분 만에 끝냈다. Claude Code한테 “이 레거시 코드 타입스크립트로 마이그레이션해줘”라고 했더니 진짜로 해냈다. 물론 100% 완벽하진 않았고, 타입 추론이 틀린 부분을 직접 고쳐야 했다. 그래도 3시간이 40분이 된 건 사실이다.
근데 솔직히 처음부터 이렇게 잘 쓴 건 아니다. 한 달 전까지만 해도 Claude Code가 엉뚱한 파일을 수정하거나, 같은 버그를 세 번이나 다른 방식으로 잘못 고치는 일이 잦았다. 뭐가 달라졌을까. 결국 도구 자체보다 쓰는 습관이 문제였다.
CLAUDE.md를 코드처럼 관리하라
Claude Code에는 CLAUDE.md라는 특수 파일이 있다. 매 대화 시작 시 Claude가 자동으로 읽는 파일인데, 여기에 프로젝트의 빌드 명령, 코드 스타일, 아키텍처 결정 같은 정보를 넣어둔다. 쉽게 말하면 “이 프로젝트에서는 이렇게 일해”라고 알려주는 프로젝트 헌법이다.
처음에는 /init 명령으로 자동 생성한 뒤 그냥 방치했다. 그랬더니 Claude가 CommonJS로 코드를 쓰고, 테스트 러너를 잘못 호출하고, 브랜치 컨벤션을 무시하는 일이 반복됐다. Anthropic 공식 문서에서는 이 파일을 “코드처럼 관리하라”고 권한다. PR 리뷰에서 발견한 반복 실수를 규칙으로 추가하고, 정기적으로 불필요한 내용을 정리하라는 뜻이다.
핵심은 짧게 유지하는 것이다. SFEIR Institute의 분석에 따르면 CLAUDE.md가 길어질수록 중요 규칙이 노이즈에 묻혀서 오히려 무시당한다. 매 줄마다 “이걸 빼면 Claude가 실수할까?” 자문해보고, 아니라면 지우는 게 맞다. 개인적으로는 50~100줄 정도가 적당하다고 느낀다.
포함해야 할 것과 빼야 할 것
Claude가 코드를 읽어서 알 수 있는 정보는 넣을 필요 없다. 반대로 Claude가 절대 추측할 수 없는 것, 예를 들어 npm run test:integration이 실제 DB를 건드린다는 사실 같은 건 반드시 넣어야 한다. “깔끔한 코드 작성” 같은 자명한 관행도 빼자. 그건 CLAUDE.md가 아니라 상식이다.
컨텍스트를 청결하게 유지하라
Claude Code의 200k 토큰 컨텍스트 윈도우(Context Window)는 작업 메모리다. 모든 대화, 파일 읽기, 명령 출력이 이 공간을 소비한다. 문제는 이 공간이 채워질수록 성능이 눈에 띄게 떨어진다는 것이다. 앞서 지시한 내용을 슬슬 “잊기” 시작하고, 실수가 늘어난다.
가장 자주 써야 할 명령어는 /clear다. 작업 전환 시마다 컨텍스트를 초기화하는 게 핵심이다. SFEIR Institute의 측정에 따르면 30분 단위 스프린트를 유지할 경우 4시간 세션에서도 85%의 성능을 유지할 수 있다. 반면 컨텍스트를 청소하지 않고 여러 작업을 한 세션에 때려 넣으면 금세 품질이 떨어진다.
토큰을 아끼는 구체적 방법
파일을 읽을 때 전체를 읽지 말고 관련 라인만 읽게 하면 토큰 소비를 50~70% 줄일 수 있다. 전체 파일 읽기가 약 3,000 토큰을 소비하는 반면, grep으로 필요한 부분만 찾으면 200 토큰 정도면 충분하다. 에러 로그를 붙여넣을 때도 200줄 전체가 아니라 핵심 에러 메시지 5~10줄만 복사하는 것만으로도 큰 차이가 난다.
그리고 탐색 작업은 Subagent에게 위임하는 게 좋다. Subagent는 별도 컨텍스트에서 실행되니까 메인 세션의 공간을 오염시키지 않는다. “이 인증 시스템이 토큰 갱신을 어떻게 처리하는지 조사해줘”라고 Subagent에게 맡기면, 수십 개 파일을 읽는 과정이 메인 컨텍스트에 영향을 주지 않는다.
검증 수단을 먼저 준비하라
이건 Anthropic 공식 문서에서 “가장 높은 레버리지를 가진 단일 행동”이라고 표현한 부분이다. Claude에게 기능을 설명하기 전에 “이게 제대로 동작하는지 어떻게 확인할 것인가”를 먼저 생각하라는 뜻이다.
“이메일 검증 함수 구현해줘”라고 하면 그럴듯하지만 실제로는 작동하지 않는 코드가 나올 수 있다. 대신 “validateEmail 함수 구현해줘. 테스트 케이스: user@example.com은 true, invalid는 false, user@.com은 false. 구현 후 테스트 실행해줘”라고 하면 Claude가 스스로 피드백 루프를 형성한다. 이 차이가 수정 횟수를 극적으로 줄인다.
비슷한 맥락에서 AskUserQuestion 인터뷰 패턴도 쓸 만하다. 큰 기능을 구현하기 전에 Claude한테 먼저 질문하게 하는 방식이다. “이 기능 구현해줘. 근데 먼저 인터뷰해줘. 기술 구현, 엣지 케이스, 트레이드오프를 물어봐”라고 하면 내가 놓친 부분을 사전에 잡아준다.
초급에서 고급까지, 단계별로 익히면 된다
한 번에 다 적용하려면 부담스럽다. 처음 2주는 CLAUDE.md 작성, Plan Mode 습관화(Shift+Tab), /clear 루틴화만으로도 충분하다. 그다음 2주는 테스트 케이스 함께 제공하기, @파일 참조 활용하기를 더하면 된다. 한 달이 지나면 Subagent 설정, Git Worktree 기반 병렬 세션, Hooks 자동화 같은 고급 기법에 도전해볼 수 있다.
Claude Code 창시자인 Boris Cherny가 Git Worktree를 자신의 “넘버원 생산성 팁”이라고 말한 적 있는데, 실제로 5개 에이전트를 병렬로 돌리면 처리량이 대략 5배 늘어난다. incident.io 팀은 이미 4~5개 병렬 에이전트를 일상적으로 운영하고 있다.
마무리
한 가지 확실한 건, CLAUDE.md 파일 하나 제대로 관리하는 게 프롬프트 10개 짜는 것보다 낫다는 거다. 컨텍스트를 깨끗하게 유지하고, 검증 수단을 먼저 준비하는 습관만 들여도 Claude Code는 꽤 쓸 만한 개발 파트너가 된다. 도구는 계속 복잡해지지만 원칙은 단순하다. 컨텍스트를 관리하고, 검증하고, 반복하라.
