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

관련 논문

• 프로덕션 AI 에이전트를 GPT-5.6으로 마이그레이션: 2.2배 빠르고 27% 저렴

  마케팅 웹사이트를 자동 생성하는 프로덕션 AI 에이전트를 Claude Opus 4.8에서 GPT-5.6 Sol로 전환한 실전 경험담으로, 단순 모델 교체가 아니라 eval 하네스, 툴 스키마, 캐싱, 추론 리플레이까지 손봐야 했던 과정을 구체적인 수치와 함께 정리했다.

• xAI Grok Build CLI가 xAI 서버로 전송하는 데이터: 네트워크 레벨 분석

  xAI의 공식 코딩 CLI 도구 Grok Build가 사용자 동의 없이 전체 Git 저장소와 .env 시크릿 파일을 xAI 서버로 업로드한다는 사실이 네트워크 트래픽 분석으로 밝혀졌다.

• 중요할 때 기억하라: Long-Horizon 에이전트를 위한 Proactive Memory Agent

  LLM 에이전트가 긴 작업 중 중요한 정보를 잊어버리는 문제를 별도의 메모리 에이전트가 '적절한 타이밍에' 끼어들어 해결하는 방법

• WebSwarm: 깊고 넓은 웹 검색을 위한 재귀적 Multi-Agent Orchestration

  복잡한 웹 검색을 재귀적으로 분해하고 각 노드에 적합한 검색 모드를 동적으로 할당하는 멀티에이전트 프레임워크

• 웹 앱을 리버스 엔지니어링해서 AI Agent 도구로 자동 변환하기

  로그인된 웹 앱의 API 호출을 브라우저에서 감시해 자동으로 MCP 도구로 변환하는 에이전트를 만들었다. 소스 코드나 공식 API 문서 없이도 Jira, Spotify 같은 서비스에 AI 어시스턴트를 붙일 수 있다.

• FableCut – AI 에이전트가 조작할 수 있는 브라우저 기반 비디오 에디터 (zero deps)

  타임라인 전체를 JSON 파일 하나로 표현하고 MCP/REST로 AI 에이전트가 직접 편집할 수 있는 브라우저 비디오 에디터로, Claude 같은 AI가 프롬프트 하나로 영상을 자동 컷편집하고 결과를 실시간으로 UI에 반영해준다.

Related Resources

• 원문 Reddit 포스트
• Citadel - 오픈소스 Claude Code 오케스트레이션 시스템 (GitHub)