AI 코딩 도구를 쓰다 보면 이런 경험 한 번쯤 있으시죠? “분명 좋은 도구인데, 왜 내가 원하는 대로 안 움직이지?” Claude Code, Cursor, Codex CLI 같은 도구들이 우후죽순 나오는 요즘, 정작 중요한 건 도구 자체가 아니라 ‘어떻게 설정하느냐’입니다.
월 수십억 토큰을 사용하는 엔지니어링 팀에서 Claude Code를 운영하는 개발자 Shrivu Shankar가 자신의 실전 노하우를 공개했습니다. 공식 문서에는 나오지 않는, 실제로 써보고 부딪혀본 사람만이 알 수 있는 인사이트가 가득합니다.
CLAUDE.md: 가장 중요한 파일
Claude Code를 효과적으로 쓰려면 단 하나의 파일만 제대로 관리하면 됩니다. 바로 프로젝트 루트의 CLAUDE.md입니다. 이 파일은 AI 에이전트의 “헌법”이자, 여러분의 코드베이스가 어떻게 작동하는지 알려주는 1차 정보원이죠.
Shankar의 회사에서는 이 파일을 13KB 크기로 엄격하게 관리합니다. 여기에 들어갈 내용은 엔지니어의 30% 이상이 사용하는 도구와 API만 포함하고, 각 도구마다 할당된 “토큰 예산”이 있습니다. 마치 광고 지면을 파는 것처럼요. 간결하게 설명할 수 없는 도구는 CLAUDE.md에 들어갈 자격이 없다는 철학입니다.
효과적인 CLAUDE.md 작성 4원칙:
첫째, 매뉴얼이 아닌 가드레일로 시작하세요. Claude가 자주 틀리는 부분만 문서화하는 겁니다. 처음부터 완벽한 문서를 만들려고 하지 마세요.
둘째, @로 다른 파일을 언급하지 마세요. 다른 곳에 방대한 문서가 있다고 @docs.md 같은 식으로 파일을 임베드하면 컨텍스트 윈도우가 금방 차버립니다. 대신 “복잡한 사용법이나 FooBarError를 만나면 path/to/docs.md를 참고하라”처럼 언제, 왜 그 파일을 읽어야 하는지 설명하세요.
셋째, “절대 하지 마라”만 말하지 마세요. “절대 --foo-bar 플래그를 쓰지 마라”처럼 부정형 제약만 주면 에이전트가 막힙니다. 항상 대안을 제시하세요.
넷째, CLAUDE.md를 짧게 유지하는 것 자체를 목표로 삼으세요. 예를 들어 팀의 배포 명령어가 docker build --platform linux/amd64 --build-arg ENV=prod --tag myapp:latest . && kubectl apply -f k8s/prod/deployment.yaml --namespace=production처럼 복잡하다고 가정해봅시다. 이걸 CLAUDE.md에 장황하게 설명하는 대신, deploy.sh prod 같은 간단한 래퍼 스크립트를 만드는 겁니다. 그러면 CLAUDE.md에는 “배포하려면 ./deploy.sh [환경]“이라는 한 줄만 쓰면 되죠. CLAUDE.md를 짧게 유지하려다 보면 자연스럽게 복잡한 명령어를 단순화하게 되고, 이게 인간 개발자에게도 도움이 됩니다.
Subagent의 함정과 Task의 우아함
이론상으로는 Custom Subagent가 Claude Code의 가장 강력한 기능입니다. 복잡한 작업을 전문화된 에이전트에게 나눠주고, 메인 에이전트는 최종 결과만 받아 컨텍스트를 깔끔하게 유지한다는 아이디어죠.
하지만 실전에서는 두 가지 문제가 생깁니다.
첫째, 컨텍스트를 가둬버립니다. 예를 들어 PythonTests라는 서브에이전트를 만들면, 테스트 관련 모든 정보가 메인 에이전트로부터 숨겨집니다. 이제 메인 에이전트는 자기가 작성한 코드를 검증하려면 서브에이전트를 일일이 호출해야 하죠. 전체적인 맥락을 보며 판단할 수 없게 됩니다.
둘째, 인간의 워크플로우를 강제합니다. 서브에이전트를 만드는 순간, 에이전트가 언제 무엇을 위임해야 하는지 당신이 미리 정해버리는 겁니다. 바로 이게 우리가 에이전트에게 해결하라고 맡긴 문제인데 말이죠.
Shankar의 대안은 간단합니다. Custom Subagent 대신 Claude Code에 내장된 Task 도구를 쓰는 거죠.
차이를 이렇게 생각해보세요. Custom Subagent는 “파이썬 테스트 전문가”, “API 호출 전문가” 같은 전문 팀원을 미리 만들어두는 겁니다. 각자 자기 분야만 알고 있죠. 반면 Task 도구는 똑같은 지식을 가진 “나 자신”을 여러 명 복사하는 겁니다.
구체적으로는 이렇습니다. 모든 핵심 정보를 CLAUDE.md에 넣어두면, 메인 에이전트가 일이 많아졌을 때 Task 도구로 자기 자신의 복사본을 여러 개 만들어 작업을 나눠줍니다. 복사본들은 원본과 똑같은 지식(CLAUDE.md)을 가지고 있으니까, 전체 맥락을 이해하면서 각자 맡은 일을 처리하죠. 언제 어떤 일을 나눌지는 에이전트가 상황에 맞게 알아서 판단합니다.
그는 이걸 “Master-Clone” 아키텍처라고 부르는데, Custom Subagent가 만드는 “Lead-Specialist” 모델보다 훨씬 유연하고 강력하다고 강조합니다.
컨텍스트 관리: 200K를 어떻게 써야 할까
Claude Code는 200K 토큰의 컨텍스트 윈도우를 제공하지만, 실제로는 금방 차버립니다. Shankar의 팀 모노레포에서는 새 세션을 시작하면 기본적으로 20K 토큰(10%)이 소모됩니다. 나머지 180K로 실제 변경 작업을 해야 하는데, 이것도 빠르게 채워지죠.
그는 컨텍스트 관리를 위해 /context 명령어로 토큰 사용량을 주기적으로 확인하라고 조언합니다. 그리고 세 가지 워크플로우를 제안합니다.
/compact는 피하세요. 자동 압축은 불투명하고 오류가 많으며 잘 최적화되지 않았습니다.
간단한 재시작에는 /clear + /catchup을 쓰세요. 상태를 지우고 커스텀 /catchup 명령어로 현재 git 브랜치의 변경된 파일들을 다시 읽게 합니다.
복잡한 작업에는 “Document & Clear” 방식을 쓰세요. Claude에게 현재 계획과 진행 상황을 .md 파일로 덤프하게 하고, /clear로 상태를 지운 뒤, 새 세션에서 그 파일을 읽고 계속하게 합니다. 외부 “메모리”를 만드는 거죠.
Hooks: 빌드가 통과해야 커밋된다
취미 프로젝트에서는 필요 없지만, 복잡한 엔터프라이즈 환경에서는 Hooks가 결정적입니다. CLAUDE.md의 “해야 한다” 제안을 보완하는 “반드시 해야 한다” 규칙을 만드는 거죠.
Shankar의 팀은 두 가지 타입을 씁니다.
Block-at-Submit Hooks가 주력 전략입니다. PreToolUse 훅으로 모든 Bash(git commit) 명령을 감싸서, 테스트가 통과했을 때만 생성되는 /tmp/agent-pre-commit-pass 파일이 있는지 확인합니다. 파일이 없으면 커밋을 막고, Claude를 “테스트-수정” 루프에 갇히게 해서 빌드가 통과할 때까지 계속 고치게 만듭니다.
Hint Hooks는 에이전트가 최적이 아닌 작업을 할 때 가벼운 피드백을 주는 비차단 훅입니다.
중요한 건, 절대로 “block-at-write” 훅을 쓰지 않는다는 겁니다. 에이전트가 계획을 실행하는 도중에 막으면 혼란스러워하거나 심지어 “좌절”하기도 합니다. 작업을 끝까지 하게 두고 커밋 단계에서 최종 결과를 검증하는 게 훨씬 효과적입니다.
GitHub Actions: 잠자는 거인
Claude Code GitHub Action은 아마 가장 과소평가된 기능일 겁니다. 개념은 단순합니다. GHA에서 Claude Code를 실행하는 거죠. 하지만 이 단순함이 강력함을 만듭니다.
Cursor의 백그라운드 에이전트나 Codex의 관리형 웹 UI와 비슷하지만, 훨씬 커스터마이징이 자유롭습니다. 전체 컨테이너와 환경을 제어할 수 있어 데이터 접근성이 높고, 더 강력한 샌드박싱과 감사 제어가 가능합니다. 게다가 Hooks나 MCP 같은 고급 기능도 모두 지원하죠.
Shankar의 팀은 이걸로 “어디서나 PR” 도구를 만들었습니다. Slack, Jira, 심지어 CloudWatch 알림에서도 PR을 트리거할 수 있고, GHA가 버그를 고치거나 기능을 추가해서 완전히 테스트된 PR을 반환합니다.
더 흥미로운 건, GHA 로그가 전체 에이전트 로그라는 점입니다. 회사 차원에서 이 로그를 정기적으로 리뷰하면서 흔한 실수, bash 에러, 일치하지 않는 엔지니어링 관행을 찾아냅니다. 이게 데이터 기반 플라이휠을 만듭니다. 버그 → 개선된 CLAUDE.md/CLI → 더 나은 에이전트.
심지어 이런 명령어를 실행한다고 합니다:
query-claude-gha-logs --since 5d | claude -p "다른 Claude들이 어디서 막혔는지 보고 고쳐서 PR 올려"에이전트가 에이전트를 개선하는 메타 루프죠.
도구가 아니라 사용법이다
결국 중요한 건 도구 자체가 아닙니다. Claude Code든 Cursor든, 어떤 AI 코딩 도구를 쓰든 ‘어떻게 가르치느냐’가 승부를 갑니다.
CLAUDE.md 하나를 제대로 관리하고, Custom Subagent의 함정을 피하고, 컨텍스트를 전략적으로 관리하고, Hooks로 품질을 강제하고, GitHub Actions로 프로세스를 자동화하면, 같은 도구도 완전히 다른 수준의 생산성을 낼 수 있습니다.
Shankar는 마지막으로 이렇게 말합니다. “내 목표는 ‘쏘고 잊는 것(shoot and forget)’입니다. 위임하고, 컨텍스트를 설정하고, 알아서 작동하게 두는 거죠. 도구를 판단할 때는 과정이 아니라 최종 PR을 보세요.”
참고자료:
답글 남기기