11월과 1월 사이에 무슨 일이 있었나

작년 11월, Andrej Karpathy는 자신의 코딩 워크플로우를 이렇게 설명했다.

"에이전트 20%, 수동 코딩 80%."

그리고 불과 두 달 뒤인 1월 말, 그는 다시 메모를 남겼다.

"에이전트 80%, 손 보정 20%."

두 달 만에 뒤집혔다. 그것도 완전히.

이건 한 사람의 이야기가 아니다. 전 세계 개발자들이 비슷한 시기에 비슷한 반전을 경험했다. 그리고 그 변화의 중심에 Claude Code가 있었다.

"그냥 AI 코딩 도구겠지"라는 착각

한 개발자는 Anthropic 해커톤에서 우승한 뒤 이렇게 고백했다.

"솔직히 처음엔 저도 Claude Code를 과소평가했어요. 그냥 AI 코딩 도구겠지 했는데, 제대로 쓰는 법을 알고 나니까 완전히 달라지더라고요."

Claude Code를 처음 접한 사람들이 흔히 빠지는 함정이 있다. 마치 ChatGPT에 코드 짜달라고 하듯이 쓰는 것이다. "인증 기능 만들어줘"라고 던지고 결과를 기다리는 방식.

결과는 늘 비슷하다. 돌아가는 것 같긴 한데, 어딘가 이상하다. 기존 캐싱 레이어를 무시한 함수, ORM 컨벤션을 모르는 마이그레이션, 반쯤 완성된 API 엔드포인트. 작동하는 것처럼 보이지만 주변 시스템과 어긋나는 코드들이 쌓인다.

문제는 Claude의 능력이 아니다. 사용 방식이다.

첫 번째 원칙: 계획과 실행을 분리하라

9개월째 Claude Code를 주 개발 도구로 쓰고 있는 한 개발자는 자신의 워크플로우를 이렇게 단 한 문장으로 요약한다.

"코드를 작성하게 하기 전에, 반드시 계획을 리뷰하고 승인하라."

그의 프로세스는 세 단계다.

1단계: 리서치. 코딩을 시작하기 전, Claude에게 먼저 코드베이스를 깊이 읽게 한다. 그리고 그 결과를 research.md 파일로 저장하게 한다. 채팅으로 구두 요약하는 게 아니라, 파일로 남기는 이유가 있다. 직접 읽고, Claude가 실제로 시스템을 이해했는지 검증하기 위해서다.

프롬프트 하나가 결과를 완전히 바꾼다. "이 폴더를 읽어줘"가 아니라 "깊이", "세부사항까지", "인트리케이시를 포함해서"라고 명시해야 한다. 이 단어들이 없으면 Claude는 함수 시그니처만 훑고 넘어간다.

2단계: 플랜. research.md를 바탕으로 구체적인 실행 계획을 세운다. 코드는 아직 한 줄도 쓰지 않는다.

3단계: 구현. 계획을 승인한 뒤에야 코딩을 시작한다.

단순해 보이지만, AI 코딩에서 가장 비싼 실패는 잘못된 이해에서 나온다. 계획이 틀리면 구현도 틀린다. 계획이 맞으면 Claude는 원샷에 해낸다.

두 번째 원칙: 컨텍스트는 신선한 우유다

해커톤 우승자의 비유가 정확하다.

"컨텍스트는 신선한 우유예요. 시간이 지나면 상해요."

이론상 Claude Code는 200,000토큰까지 사용할 수 있다. 하지만 실전에서 100,000토큰이 넘어가면 응답 품질이 눈에 띄게 떨어지기 시작한다. 앞뒤가 안 맞는 코드, 초반에 정해둔 규칙을 잊은 것 같은 답변들.

이건 단순한 체감이 아니다. Stanford 연구는 이를 "Lost in the Middle" 현상으로 명명했다. 컨텍스트 중간에 위치한 정보의 처리 성능이 30% 이상 저하된다는 결과다.

해결책은 두 가지다.

/compact는 대화 내용을 압축하면서 중요한 맥락은 유지한다. 작업 흐름이 끊기지 않는다. /clear는 완전 초기화다. 깔끔하게 시작하지만, 반드시 HANDOFF.md를 먼저 만들어야 한다. 지금까지 한 것, 다음에 할 것, 주의사항을 기록한 파일. 새 세션에서 이 파일만 읽어주면 바로 이어서 작업된다.

HANDOFF.md 없이 컨텍스트를 날리면? 2시간치 작업 흐름을 다시 설명하는 시간 낭비가 기다린다.

세 번째 원칙: AI가 멍청해진 게 아니다

세션을 30분만 넘기면 답변이 이상해진다는 불만을 자주 듣는다. 대부분 원인은 같다.

코드 탐색, 파일 읽기, 검색, 구현까지 모든 작업을 메인 세션 하나에 몰아넣는 것이다.

세 개의 파일을 메인에서 직접 탐색하면 원문이 그대로 15,000토큰 넘게 쌓인다. 서브 에이전트 세 개로 나누면? 각각 200토큰짜리 요약만 메인에 돌아온다. 합쳐서 600토큰.

서브 에이전트는 AI를 더 많이 쓰는 게 아니다. 메인 세션을 지키는 구조다.

에이전트 유형도 전략적으로 골라야 한다. 코드 탐색처럼 읽기만 하면 되는 작업은 Haiku 기반의 Explore 에이전트로 충분하다. General 에이전트 대비 비용이 80% 이상 줄어든다. 구현 작업만 General 에이전트를 쓰면 된다.

Ctrl+B를 누르면 실행 중인 에이전트가 백그라운드로 넘어간다. 테스트 스위트가 돌아가는 동안 다음 기능 개발을 바로 시작할 수 있다. 이걸 모르는 사람은 테스트가 끝날 때까지 가만히 기다리고 있다.

Claude Code를 만든 사람이 Claude Code를 쓰는 방법

Claude Code를 직접 만든 Boris Cherny는 터미널에서 5개, 웹에서 10개. 동시에 15개의 Claude를 돌린다.

그가 공개한 워크플로우에서 가장 중요한 문장은 이것이다.

"Claude에게 자기 작업을 검증할 방법을 주면, 결과 품질이 2~3배 올라간다."

단순히 더 많이 쓰는 게 아니다. 구조를 만드는 것이다. 자주 쓰는 워크플로우는 슬래시 커맨드로 만들어두고, PostToolUse 훅으로 코드 포맷팅을 자동화하고, AI가 스스로 결과를 검증하게 한다.

이런 접근법은 어느 개발자의 말처럼 완전히 다른 고민을 낳는다.

"이렇게 일하는 사람들은 '어떤 스킬이 서브에이전트를 어떻게 트리거할지', 'AskUserQuestion을 어떻게 활용하게 할지'를 고민합니다. Claude Code의 제약을 이해하고 목표를 AI에 정렬할 줄 아는 능력이 핵심 역량으로 부상하고 있어요."

팀으로 확장될 때 필요한 것

Claude Code가 팀 단위로 들어오면 완전히 새로운 문제가 생긴다. 여러 세션이 병렬로 돌아가면서 같은 파일을 동시에 수정하기 시작하는 것이다.

해결책은 Git Worktrees다. 같은 리포지토리에서 여러 브랜치를 별도 디렉토리로 체크아웃해, 각 Claude 인스턴스가 서로 방해 없이 독립적으로 작업하는 구조다.

그리고 CLAUDE.md가 팀 표준의 핵심이 된다. 프로젝트 루트에 두면 모든 세션이 자동으로 읽는다. 브랜치 명명 규칙, 커밋 포맷, "절대 하지 말 것" 목록까지. Anthropic 내부 팀도 이 방식으로 실수를 문서화하고, Claude가 점점 더 나은 코드를 쓰게 만들고 있다.

결국 무엇이 달라졌나

Claude Code는 단순한 자동완성 도구가 아니다. 그렇다고 알아서 다 해주는 마법도 아니다.

계획과 실행을 분리하고, 컨텍스트를 의도적으로 관리하고, 서브 에이전트로 작업을 위임하는 구조를 만드는 것. 이게 제대로 쓰는 방식이다.

가장 좋은 Claude Code 강의는 Claude Code 자체라는 말이 있다. 영상을 보면 "아 그렇구나"로 끝나고, 터미널을 열고 직접 대화하면 "이렇게 하면 되는구나"가 된다.

두 달 만에 워크플로우를 뒤집은 사람들은 새로운 도구를 쓴 게 아니었다. 새로운 방식으로 일하기 시작한 것이다.

이 글은 아래 글들을 바탕으로 작성되었습니다.