Claude Code 제대로 쓰는 법 — 실전 베스트 프랙티스 정리

Claude Code, 설치는 5분이면 되지만 제대로 쓰는 법은 다릅니다. 같은 도구로 누구는 하루치 일을 30분에 끝내고, 누구는 헤맵니다. 차이는 몇 가지 습관에서 갈립니다. 공식 문서와 실전 관행에서 검증된 핵심 베스트 프랙티스를 정리했습니다.

이 글은 특정 리스티클을 옮긴 게 아니라, Anthropic 공식 문서와 검증된 실전 관행을 바탕으로 재구성했습니다. 다섯 개의 습관으로 묶었습니다. 하나씩만 몸에 붙여도 체감이 확 달라집니다.

1. CLAUDE.md — 매 세션 읽히는 설명서

CLAUDE.md는 Claude가 세션마다 자동으로 읽는 프로젝트 안내서입니다. 여기에 무엇을 담느냐가 결과의 8할을 좌우합니다.

• 빌드·테스트·린트 명령, 코드 컨벤션, 자주 밟는 지뢰(gotcha)를 적는다. Claude가 매번 물어보지 않게.
• `/init`으로 초안을 만들고 다듬는다. 빈 파일부터 시작하지 말 것.
• 간결하게 유지한다. 너무 많이 적으면 정작 중요한 지시가 소음에 묻혀 무시된다. Claude가 이미 잘 지키는 규칙은 지우거나 훅으로 옮긴다.

2. 컨텍스트: 다 넣지 말고 좁혀라

Claude Code의 성능은 컨텍스트 관리에서 갈립니다. 컨텍스트 창은 유한한 자원이라, 어떻게 채우느냐가 정확도를 좌우합니다.

• 범위를 좁혀 지시한다. "이 레포 다 봐줘"가 아니라, 관련 파일·폴더를 짚어준다.
• 대화가 길어져 컨텍스트가 붐비면 `/clear`(초기화)나 `/compact`(요약 압축)로 정리한다.
• 큰 조사는 서브에이전트에 맡긴다(3번 참고). 파일을 잔뜩 읽는 작업일수록 별도 컨텍스트에서 돌리고 요약만 받는 게 유리하다.

3. 계획하고, 검증하라

바로 코드를 고치게 두는 대신, 계획 → 실행 → 검증의 리듬을 만드세요.

• plan 모드를 먼저 쓴다. 큰 변경은 Claude가 계획을 제시하게 하고, 검토·승인 후 실행한다.
• 작게 반복한다. 한 번에 거대한 변경보다, 작은 단위로 나눠 확인하며 진행한다.
• 믿지 말고 검증한다. 테스트를 돌리고, `/code-review`(다중 에이전트 리뷰)로 확인한다. "됐다"는 말이 아니라 실제 동작으로.
• 엇나가면 바로 개입한다. Esc로 끊고 방향을 잡아준다. 끝까지 두고 나서 갈아엎지 말 것.

4. 서브에이전트로 병렬화

서브에이전트(subagent)는 Claude Code의 가장 강력한 도구 중 하나입니다. 각자 독립된 컨텍스트·도구·시스템 프롬프트로 돌아, 본 대화를 어지럽히지 않고 일합니다.

• 독립적인 큰 작업은 팬아웃한다. 여러 파일 조사, 병렬 리팩터링 등을 서브에이전트로 나눠 동시에 처리.
• 리뷰어 패턴: 최근 버전에선 서브에이전트가 자기 서브에이전트를 다시 띄울 수 있어(중첩), 발견 항목마다 검증 에이전트를 붙이는 식의 심층 검토가 가능하다.
• 병렬로 파일을 고칠 땐 worktree 격리로 충돌을 막는다.

"하나의 워크플로우에서 여러 에이전트를 부린다"는 흐름은 이제 Claude Code만의 것이 아닙니다. 오픈소스 대안 OpenCode도 같은 개념(plan/build·스킬·AGENTS.md)을 제공합니다.

5. 권한·훅·확장으로 안전하게 자동화

마지막은 안전한 자동화입니다. 반복은 도구에 넘기고, 위험은 미리 막습니다.

• 권한을 잠근다. 허용 목록(allowlist)으로 자주 쓰는 안전한 명령만 자동 허용하고, 위험한 작업은 확인을 받게 한다(`/permissions`).
• 훅(hooks)으로 자동화한다. 저장 시 포맷·린트·테스트를 자동 실행하거나, 위험한 명령을 사전 차단한다.
• 커스텀 슬래시 명령과 스킬로 반복 작업을 자산화한다. 자주 쓰는 프롬프트·절차를 저장해두고 재사용.
• MCP로 외부 도구를 붙인다. 이슈 트래커·DB·디자인 툴 등을 Claude가 직접 다루게.

이 다섯 습관의 공통점은 하나입니다. Claude에게 더 좋은 '환경'을 만들어 주는 것. 더 똑똑한 프롬프트보다, 잘 정리된 CLAUDE.md·좁은 컨텍스트·명확한 검증 루프가 결과를 더 크게 바꿉니다.

오늘 정리하고 갈 체크리스트

• CLAUDE.md: 빌드·테스트 명령과 컨벤션을 간결하게. `/init`로 시작, 과하면 덜어내기.
• 컨텍스트: 범위 좁히기, `/clear`·`/compact`, 큰 조사는 서브에이전트.
• 계획·검증: plan 모드로 계획→승인, 테스트·`/code-review`로 검증, Esc로 조기 개입.
• 서브에이전트: 독립 작업 팬아웃, 리뷰어 패턴, worktree 격리.
• 자동화: 권한 allowlist, 훅, 커스텀 명령·스킬, MCP.

자주 묻는 질문 (FAQ)

출처

• Anthropic, Best practices for Claude Code (공식 문서) — 본문 관행의 근거
• Claude Code 공식 문서, Claude Code Docs
• 착안: Agent Cookbook — Claude Code 40 Best Practices