Claude Code 실전 활용 완전 가이드
게시일: 2025년 11월 13일 | 원문 작성일: 2025년 11월 2일
작성일: 2025년 10월 | 원저자: Shrivu | 원문 보기
핵심 요약
수십억 토큰을 소비하는 AI 개발팀에서 일하며, 주말엔 사이드 프로젝트에 Claude Code를 쓰는 개발자가 알려주는 실전 노하우. 이 글은 단순한 튜토리얼이 아니라, 수개월간 Claude Code를 메인 도구로 쓰면서 깨달은 ‘진짜 쓸모 있는 것’과 ‘피해야 할 것’을 정리한 레퍼런스 가이드예요.
주요 내용:
- CLAUDE.md가 전부다 - 가드레일로 시작해서, 매뉴얼이 아닌 가이드로 유지하기
- 컨텍스트 관리는 생존기술 - /compact는 피하고, /clear + 커스텀 워크플로우로
- Subagent는 과대평가됐다 - 대신 Task()로 에이전트를 복제하기
- Hook은 진짜 강력하다 - 커밋 단계에서 검증, 작성 중엔 블로킹 금지
- MCP의 새로운 역할 - API 미러링은 그만, 데이터 게이트웨이로 쓰기
- GitHub Action은 숨은 강자 - 자동화와 기록 추적의 끝판왕
1. CLAUDE.md: 에이전트의 헌법
Claude Code를 제대로 쓰려면 가장 중요한 파일이 뭔지 아세요? 바로 루트에 있는 CLAUDE.md입니다. 이 파일은 에이전트의 “헌법”이자, 여러분 레포가 어떻게 돌아가는지 알려주는 primary source of truth (프로젝트의 핵심 참조 문서)예요.
프로젝트 규모에 따른 접근법
| 프로젝트 타입 | CLAUDE.md 관리 방식 | 특징 |
|---|---|---|
| 취미 프로젝트 | Claude가 원하는 대로 끄적이게 둠 | 자유로운 실험, 빠른 반복 |
| 회사 모노레포 | 엄격하게 관리 (현재 13KB) | 30% 이상 엔지니어가 쓰는 도구만 문서화, 각 도구에 토큰 예산 할당 |
CLAUDE.md 작성 철학
CLAUDE.md는 처음엔 작게 시작해서, Claude가 뭘 틀리는지 보면서 그걸 기반으로 문서를 키워야 해요. 처음부터 완벽한 매뉴얼을 만들려고 하면 실패합니다.
- @-File로 문서 참조하기 - 컨텍스트 윈도우를 통째로 차지함. 대신 “FooBarError 만나면 path/to/docs.md 봐라”는 식으로 언제 읽어야 하는지 설명
- 대안 없이 금지만 나열하기 - “Never use —foo-bar flag”라고만 하면 에이전트가 그 플래그를 써야 한다고 판단했을 때 진퇴양난에 빠짐. 항상 대안 제시
- 복잡한 CLI를 장황하게 설명 - 그건 근본 문제를 임시방편으로 덮는 것. 대신 간단한 bash wrapper 만들고 그걸 문서화
실제 구조 예시:
회사에선 이 파일을 AGENTS.md와도 동기화해서 다른 AI IDE 쓰는 엔지니어들과도 호환성을 유지하고 있어요.
2. 컨텍스트 관리: 200k 토큰 생존 가이드
코딩 세션 중간에 /context 명령어를 최소 한 번은 실행해보길 추천해요. 200k 토큰 윈도우를 어떻게 쓰고 있는지 확인할 수 있거든요. Sonnet-1M이 나왔어도, 전체 컨텍스트가 실제로 효과적으로 쓰이는지는 여전히 의심스럽습니다.
회사 모노레포에서 새 세션 시작하면 기본으로 ~20k 토큰(10%)이 들어가고, 나머지 180k로 실제 작업을 하는데… 이게 생각보다 빨리 차요.
컨텍스트 관리 워크플로우
| 방법 | 사용 시기 | 저자 평가 |
|---|---|---|
| /compact | 자동 압축 | ❌ 최대한 피함. 불투명하고, 에러 많고, 최적화 안 됨 |
| /clear + /catchup | 간단한 재시작 | ✅ 기본 리부트 방식. git 브랜치의 모든 변경 파일 읽게 함 |
| ”Document & Clear” | 복잡한 태스크 | ✅ Claude에게 계획과 진행상황을 .md로 덤프하게 하고, /clear 후 그 .md 읽고 계속하게 함 |
3. Slash Commands: 심플하게 유지하기
Slash command는 자주 쓰는 프롬프트의 단순한 단축키일 뿐이에요. 저자의 설정은 최소한:
/catchup- git 브랜치의 모든 변경 파일 읽기/pr- 코드 정리하고 스테이징하고 PR 준비
에이전트의 포인트는 뭐든지 자연어로 타이핑하면 쓸만한 결과가 나온다는 거잖아요. 엔지니어(또는 비엔지니어)가 어딘가 문서화된 “필수 마법 명령어” 리스트를 배워야 한다면, 그건 실패한 겁니다.
4. Subagent vs Task(): 진실의 순간
이론상으로 커스텀 Subagent는 Claude Code의 가장 강력한 기능이에요. 복잡한 작업이 X 토큰의 입력 컨텍스트 + Y 토큰의 작업 컨텍스트가 필요하고, Z 토큰의 답변을 만든다면, N개의 작업은 메인 윈도우에서 (X + Y + Z) * N 토큰을 먹죠.
Subagent 솔루션은 (X + Y) * N 작업을 전문 에이전트한테 시키고, 최종 Z 토큰 답변만 받아서 메인 컨텍스트를 깔끔하게 유지하는 거예요.
하지만 실전에선 두 가지 문제가 생깁니다
PythonTests subagent를 만들면, 모든 테스트 컨텍스트가 메인 에이전트한테서 숨겨져요. 이제 에이전트는 변경사항에 대해 전체적으로 추론할 수 없고, 자기 코드를 검증하려면 subagent를 강제로 호출해야 합니다.
더 나쁜 건, Claude를 사람이 미리 정한 딱딱한 워크플로우에 가두는 거예요. 어떻게 위임해야 하는지 제가 지시하게 되는데, 그건 에이전트가 해결하라고 준 문제 바로 그거잖아요.
더 나은 대안: Task() 활용
Claude의 내장 Task(…) 기능으로 일반 에이전트의 복제본을 생성하고, 모든 핵심 컨텍스트는 CLAUDE.md에 넣어요. 그러면 메인 에이전트가 언제 어떻게 일을 자기 복제본에게 위임할지 스스로 결정합니다. Subagent의 컨텍스트 절약 이점은 다 가져가면서 단점은 없어요. 에이전트가 자기 오케스트레이션을 동적으로 관리하죠.
5. Session History: 과거에서 배우기
간단한 레벨에서, claude —resume과 claude —continue를 자주 써요. 버그 난 터미널 재시작하거나 오래된 세션 빠르게 리부트할 때 좋죠.
며칠 전 세션을 claude —resume해서 에이전트한테 특정 에러를 어떻게 극복했는지 요약하라고 시키고, 그걸 CLAUDE.md랑 내부 툴링 개선에 써요.
더 깊게 들어가면, Claude Code는 모든 세션 히스토리를 ~/.claude/projects/에 저장해요. 여기 raw 히스토리 데이터를 탭해서 메타 분석 스크립트를 돌려서, 흔한 예외, 권한 요청, 에러 패턴을 찾아내서 에이전트용 컨텍스트 개선에 써먹고 있어요.
6. Hooks: 엔터프라이즈의 비밀병기
Hook은 진짜 크죠. 취미 프로젝트엔 안 쓰지만, 복잡한 엔터프라이즈 레포에서 Claude를 조종하는 데 필수예요. CLAUDE.md의 “should-do” 제안을 보완하는 결정론적 “must-do” 규칙이죠.
두 가지 Hook 타입
| Hook 타입 | 타이밍 | 용도 |
|---|---|---|
| Block-at-Submit | 커밋 단계 | ✅ 주요 전략. PreToolUse hook으로 Bash(git commit) 랩핑.
모든 테스트 통과해야 생기는 /tmp/agent-pre-commit-pass 파일
확인. 없으면 커밋 블로킹, 빌드 그린 될 때까지 “test-and-fix” 루프 |
| Hint Hooks | 작업 중 | 간단한 비블로킹 hook. 에이전트가 뭔가 최적이 아닌 짓 하면 “fire-and-forget” 피드백 제공 |
Edit나 Write 시점에 블로킹하지 마세요. 에이전트 계획 중간에 막으면 혼란스러워하거나 심지어 “좌절”해요. 작업 끝내게 두고 커밋 단계에서 최종 완성 결과를 체크하는 게 훨씬 효과적입니다.
7. Planning Mode: 대규모 변경의 필수템
Planning은 AI IDE로 “큰” 기능 변경할 때 필수예요.
- 취미 프로젝트: 내장 planning mode만 써요. 뭘 어떻게 만들지 + 어디서 멈춰서 작업 보여줄지 정의해서 Claude와 사전 합의하는 방식이죠. 이거 자주 쓰면 좋은 계획 얻으려면 최소 컨텍스트가 뭐가 필요한지 직관이 생겨요.
- 회사 모노레포: Claude Code SDK로 만든 커스텀 planning tool 배포 중이에요. 네이티브 plan mode랑 비슷한데, 우리 기술 설계 포맷에 맞게 프롬프트 엔지니어링 되어 있고, 내부 베스트 프랙티스(코드 구조부터 데이터 프라이버시, 보안까지)를 기본으로 강제해요. 엔지니어들이 시니어 아키텍트처럼 “vibe plan” 할 수 있게 하는 게 목표죠.
8. MCP와 Skills: 새로운 패러다임
저자는 대부분의 개발 워크플로우에서 MCP에서 벗어나서 간단한 CLI를 만드는 쪽을 선호해요. 에이전트 자율성의 정신적 모델이 세 단계로 진화했대요:
단계별 설명
- Single Prompt: 에이전트에게 모든 컨텍스트를 하나의 거대한 프롬프트로 주기 (취약, 확장 안 됨)
- Tool Calling: “고전적” 에이전트 모델. 도구를 손으로 만들고 에이전트를 위해 현실을 추상화 (더 나음, 하지만 새로운 추상화와 컨텍스트 병목 생성)
- Scripting: 에이전트에게 raw 환경 접근권 주기—바이너리, 스크립트, 문서—그리고 에이전트가 즉석에서 코드 짜서 상호작용 (가장 강력하고 유연)
Agent Skills: 공식 “Scripting” 계층
이미 MCP보다 CLI를 선호했다면, 이미 Skills의 이점을 암묵적으로 누리고 있던 거예요. SKILL.md 파일은 이런 CLI와 스크립트를 문서화하고 에이전트에게 노출하는 더 조직적이고, 공유 가능하고, 발견 가능한 방식일 뿐입니다.
MCP의 새로운 역할
Skills가 나왔다고 MCP가 죽은 건 아니에요. 예전엔 REST API를 미러링하는 수십 개 도구를 가진 끔찍하고 컨텍스트 헤비한 MCP를 많이 만들었죠 (read_thing_a(), read_thing_b(), update_thing_c()).
”Scripting” 모델(지금은 Skills로 공식화됨)이 더 낫지만, 환경에 접근하는 안전한 방법이 필요해요. 이게 MCP의 새롭고 더 집중된 역할입니다.
MCP는 간단하고 안전한 게이트웨이로:
download_raw_data(filters…)take_sensitive_gated_action(args…)execute_code_in_environment_with_state(code…)
이 모델에서 MCP의 일은 에이전트를 위해 복잡한 현실을 뭉뚱그려주는 게 아니라, 인증, 네트워킹, 보안 경계만 관리하고 비켜서는 거예요. 에이전트가 들어갈 진입점을 제공하고, 에이전트는 자기 스크립팅과 마크다운 컨텍스트로 실제 작업을 합니다.
저자가 아직 쓰는 유일한 MCP는 Playwright인데, 이건 말이 돼요—복잡하고 stateful한 환경이니까요. 모든 stateless 도구들(Jira, AWS, GitHub 같은)은 간단한 CLI로 마이그레이션했어요.
9. Claude Code SDK: 범용 에이전트 프레임워크
Claude Code는 그냥 인터랙티브 CLI가 아니라, 완전히 새로운 에이전트를 만드는 강력한 SDK이기도 해요—코딩과 비코딩 작업 둘 다요. 저자는 대부분의 새 취미 프로젝트에 LangChain/CrewAI보다 이걸 디폴트 에이전트 프레임워크로 쓰기 시작했대요.
세 가지 주요 사용 방식
| 사용 케이스 | 설명 |
|---|---|
| 대규모 병렬 스크립팅 | 대규모 리팩토링, 버그 픽스, 마이그레이션에 인터랙티브 챗 안 써요.
간단한 bash 스크립트로 claude -p “in /pathA change all refs from foo to bar”를
병렬로 호출. 메인 에이전트가 수십 개 subagent 작업 관리하는 것보다 훨씬 확장성 있고 제어 가능 |
| 내부 챗 도구 만들기 | 복잡한 프로세스를 비기술 유저용 간단한 챗 인터페이스로 감싸기 완벽. 에러 나면 Claude Code SDK로 폴백해서 유저한테 문제를 그냥 고쳐주는 인스톨러라든지, 디자인 팀이 사내 UI 프레임워크로 목업 프론트엔드를 vibe-code할 수 있는 “v0-at-home” 도구 같은 거 |
| 빠른 에이전트 프로토타이핑 | 가장 흔한 용도. 코딩만이 아니에요. 에이전틱한 작업 아이디어가 있으면 (예: 커스텀 CLI나 MCP 쓰는 “위협 조사 에이전트”), Claude Code SDK로 빠르게 프로토타입 만들고 테스트하고, 전체 배포 구조를 본격적으로 구축하기 전에 검증 |
10. GitHub Action: 숨은 강자
Claude Code GitHub Action (GHA)는 아마 저자가 가장 좋아하고 가장 저평가된 기능일 거예요. 컨셉은 간단해요: 그냥 Claude Code를 GHA에서 돌리는 거. 하지만 이 단순함이 강력함을 만들어요.
Cursor의 백그라운드 에이전트나 Codex 매니지드 웹 UI랑 비슷하지만 훨씬 커스터마이징 가능해요. 전체 컨테이너와 환경을 제어하니까 더 많은 데이터 접근권을 갖고, 결정적으로 다른 어떤 제품보다 훨씬 강한 샌드박싱과 감사 제어(audit controls)를 할 수 있어요. 게다가 Hook이나 MCP 같은 고급 기능 다 지원하고요.
실전 활용 사례
- ”PR-from-anywhere” 툴링: Slack, Jira, 심지어 CloudWatch alert에서 PR을 트리거할 수 있고, GHA가 버그 고치거나 기능 추가하고 완전히 테스트된 PR을 리턴해요
- 회사 차원의 로그 리뷰: GHA 로그는 전체 에이전트 로그니까, 흔한 실수, bash 에러, 일관성 없는 엔지니어링 프랙티스를 정기적으로 리뷰하는 ops 프로세스가 있어요. 데이터 드리븐 선순환 구조가 만들어져요: 버그 → 개선된 CLAUDE.md / CLI → 더 나은 에이전트
11. settings.json: 고급 커스터마이징
마지막으로, 취미와 업무 양쪽에 필수적인 몇 가지 settings.json 설정들이 있어요.
| 설정 | 용도 |
|---|---|
| HTTPS_PROXY/HTTP_PROXY | 디버깅에 좋아요. raw 트래픽 인스펙트해서 Claude가 정확히 어떤 프롬프트 보내는지 볼 수 있음. 백그라운드 에이전트엔 fine-grained 네트워크 샌드박싱 도구이기도 함 |
| MCP_TOOL_TIMEOUT/BASH_MAX_TIMEOUT_MS | 이거 올려둠. 길고 복잡한 명령어 돌리는 거 좋아하는데 기본 타임아웃이 너무 보수적임. bash 백그라운드 태스크가 생긴 지금도 필요한지 모르겠지만 혹시 몰라서 유지 |
| ANTHROPIC_API_KEY | 회사에서 엔터프라이즈 API key 써요 (apiKeyHelper 통해서). “per-seat” 라이선스에서 “usage-based” 가격 모델로 전환. 개발자별 사용량 편차가 크고(1:100배 차이 봤음), 엔지니어들이 Claude Code 아닌 다른 LLM 스크립트도 모두 하나의 엔터프라이즈 어카운트로 할 수 있음 |
| permissions | 가끔 Claude가 자동 실행하도록 허용한 명령어 리스트를 자체 감사함(self-audit) |
결론
길었지만, 도움이 됐기를 바라요. 아직 Claude Code나 Codex CLI 같은 CLI 기반 에이전트를 안 쓰고 있다면, 아마 써야 할 거예요. 이런 고급 기능들에 대한 좋은 가이드가 드물어서, 배우는 유일한 방법은 직접 뛰어드는 것뿐이에요.
Claude Code는 단순한 코딩 어시스턴트가 아니라 완전한 생태계예요. CLAUDE.md를 헌법으로, Hook을 가드레일로, GHA를 자동화 엔진으로 쓰면 개인 도구에서 팀의 핵심적이고 투명하며 자체 개선되는 엔지니어링 시스템으로 바뀔 수 있어요.
참고: 이 글은 Shrivu가 자신의 Substack에 게시한 아티클을 번역하고 요약한 것입니다.
원문: https://blog.sshh.io/p/how-i-use-every-claude-code-feature
생성: Claude (Anthropic)