Claude Code 활용의 5단계: 각 단계의 한계를 인식하는 법

TL;DR Highlight

Claude Code 실전 경험담이 날것의 프롬프트부터 멀티 에이전트 오케스트레이션까지 5단계로 체계화하며, 각 단계에서 마주치는 기술적 한계를 명확하게 짚어낸다.

Who Should Read

Claude Code를 이미 써보고 있거나 도입을 고려 중인 개발자. 특히 프로젝트 규모가 커지면서 AI 코딩 어시스턴트의 일관성이 떨어지는 문제를 겪고 있는 사람에게 유용하다.

Core Mechanics

Level 1(Raw Prompting)은 소규모 단발성 작업엔 잘 되지만, 프로젝트가 커져 단일 대화 컨텍스트를 넘어서는 순간 에이전트가 기존 컨벤션을 잊어버리고 엉뚱한 패턴을 도입하기 시작한다.
Level 2(CLAUDE.md)는 프로젝트 루트에 마크다운 파일로 기술 스택, 파일 구조, 네이밍 컨벤션 등을 정의하는 방식인데, 145줄까지 늘렸더니 Anthropic 권장 200줄 한도 이전에 이미 준수율이 떨어졌다. 77줄로 줄이자 즉시 개선됐으므로 짧고 핵심만 남기는 게 중요하다.
Level 3(Skills)은 특정 작업 유형을 위한 단계별 워크플로우를 담은 마크다운 프로토콜 파일로, 필요할 때만 로드하므로 미사용 시 토큰 비용이 0이다. 매 세션마다 컴포넌트 빌드 방법을 재설명하는 수고를 없애준다.
Level 4(Hooks)는 세션 특정 시점에 자동으로 실행되는 라이프사이클 스크립트다. 예를 들어 PostToolUse 훅으로 파일 수정 후마다 해당 파일만 타입체크하면, 프로젝트 전체 200개 이상의 에러를 에이전트에 쏟아붓는 상황을 피할 수 있다. 에이전트한테 검증하라고 말하는 대신 검증 인프라 자체를 구축하는 단계다.
Level 5(Orchestration)는 격리된 worktree에서 병렬 에이전트를 돌리고, 세션을 넘나드는 persistent 캠페인 파일로 상태를 유지하며, 동일 파일 충돌을 막는 조율 레이어를 두는 방식이다. 작성자는 32개 fleet 세션에서 198개 에이전트를 돌려 3.1% merge conflict rate를 기록했다고 한다.
단계를 건너뛰려 하면 안 된다. 작성자가 Level 4 훅 없이 Level 5로 점프했다가 엉망이 됐다고 직접 밝혔다. 각 단계의 인프라가 다음 단계를 가능하게 하는 토대이기 때문에, 현재 단계에서 마찰과 한계를 느낄 때 자연스럽게 올라가는 것이 맞다.

Evidence

CLAUDE.md를 145줄로 운영하다 규칙 준수율이 눈에 띄게 떨어지는 걸 경험하고 77줄로 줄였더니 즉각 개선됐다. Anthropic이 200줄을 권장하지만 실제로는 그보다 훨씬 낮은 지점에서 에이전트가 상단 규칙만 따르고 나머지는 조용히 무시하기 시작한다.
Level 5 오케스트레이션을 실제로 운영해 32개 fleet 세션에서 198개의 병렬 에이전트를 실행했고, merge conflict 발생률은 3.1%였다. 개발자 한 명이 조직 단위의 규모로 작업할 수 있는 수준이라고 표현했다.
Level 4의 PostToolUse 훅을 활용하면 에이전트가 파일을 편집할 때마다 해당 파일에 대한 타입체크만 실행되므로, 프로젝트 전체를 한 번에 검사해 200개 이상의 에러를 에이전트 컨텍스트에 밀어넣는 비효율을 방지할 수 있다.
Level 5로 바로 점프하려 했다가 실패한 직접 경험을 공유했다. 훅 기반 자동 검증 인프라(Level 4)가 없는 상태에서 멀티 에이전트를 돌리면 품질 관리가 무너진다는 게 핵심 교훈이다.

How to Apply

현재 Claude Code 사용 중 '에이전트가 컨벤션을 자꾸 잊어버린다'는 문제를 겪고 있다면 CLAUDE.md를 80줄 이내로 작성해 프로젝트 루트에 두자. 내용이 많아질수록 하단 규칙은 무시되니, 가장 중요한 규칙만 남기고 나머지는 과감히 삭제하거나 Skills 파일로 분리한다.
반복적으로 설명하는 작업 유형(예: React 컴포넌트 생성 방식, API 엔드포인트 추가 절차)이 있다면 해당 내용을 Skills 마크다운 파일로 만들어두고 필요할 때 에이전트에게 참조하도록 지시한다. 미사용 시 토큰을 소모하지 않으므로 여러 개를 만들어도 부담이 없다.
TypeScript/Python 프로젝트에서 Claude Code 사용 중 타입 에러가 많아 에이전트 컨텍스트가 오염된다면, PostToolUse 훅을 설정해 파일 편집 직후 해당 파일만 타입체크하도록 구성한다. 전체 프로젝트 검사 결과를 한꺼번에 에이전트에 던지는 것보다 훨씬 효율적이다.

Terminology

CLAUDE.mdClaude Code 에이전트에게 프로젝트 규칙을 알려주는 마크다운 설정 파일. 프로젝트 루트에 두면 에이전트가 세션 시작 시 자동으로 읽어 기술 스택, 코딩 컨벤션, 금지 패턴 등을 인식한다.

HooksClaude Code 세션에서 특정 이벤트(파일 편집 완료, 세션 시작, 태스크 완료 등) 시점에 자동으로 실행되는 스크립트. PostToolUse, Stop, SessionStart 등의 종류가 있으며, 에이전트가 스스로 하도록 기다리는 대신 외부에서 자동으로 검증이나 컨텍스트 로드를 처리한다.

WorktreeGit의 기능으로, 하나의 저장소에서 여러 브랜치를 동시에 다른 디렉토리에 체크아웃할 수 있게 해준다. 멀티 에이전트 오케스트레이션에서 각 에이전트가 서로 충돌 없이 독립된 작업 공간을 갖도록 할 때 활용된다.

Fleet 세션여러 Claude Code 에이전트를 병렬로 묶어 동시에 운영하는 세션 집합. 단일 개발자가 대규모 작업을 병렬로 처리하기 위해 오케스트레이션 레이어와 함께 사용된다.