클로드 코드(Claude Code)를 그냥 터미널에서 질문만 던지는 용도로 쓰고 있다면 아직 절반도 못 쓰고 있는 겁니다. CLAUDE.md로 프로젝트 규칙을 고정하고, 서브에이전트로 작업을 나누고, 훅(Hooks)으로 자동화를 강제해두면 매번 같은 설명을 반복하지 않고도 일관된 결과를 받을 수 있습니다. 오늘은 클로드 코드를 제대로 쓰기 위한 고급 세팅 네 가지를 정리했습니다.
1. CLAUDE.md – 프로젝트의 '헌법' 만들기
프로젝트 최상위 폴더에 CLAUDE.md 파일을 만들어두면, 클로드 코드가 세션을 시작할 때마다 자동으로 읽어들입니다. 이 저장소가 어떻게 동작하는지, 어떤 규칙과 컨벤션을 따르는지, 자주 쓰는 명령어가 무엇인지를 여기에 적어두면 매번 새로 설명할 필요가 없습니다.
한 번 정리해두면 이후 모든 대화에서 같은 맥락을 자동으로 공유
하기 때문에, 프로젝트가 커질수록 CLAUDE.md의 효과도 커집니다.
2. 서브에이전트(Subagents)로 작업 분리하기
서브에이전트는 별도의 컨텍스트 창을 가진 독립된 클로드 세션입니다. 메인 대화의 맥락을 어지럽히지 않고 특정 작업만 따로 맡기고 싶을 때, 혹은 여러 작업을 동시에 병렬로 처리하고 싶을 때 유용합니다.
프로젝트 폴더의 .claude/agents/(또는 개인 설정인 ~/.claude/agents/)에 마크다운 파일로 역할·도구 권한을 정의해두면, 필요할 때마다 해당 서브에이전트를 호출해 일을 위임할 수 있습니다.
3. 훅(Hooks)으로 자동화 규칙 강제하기
훅은 클로드 코드에서 특정 이벤트가 발생할 때 자동으로 실행되는 스크립트입니다. 프롬프트는 모델의 해석에 의존하지만, 훅은 정해진 코드를 결정적으로 실행하기 때문에 "반드시 지켜야 하는 규칙"을 강제할 때 훨씬 확실합니다.
| PreToolUse | 도구 실행 전 – 위험한 명령을 사전 차단할 때 |
| PostToolUse | 도구 실행 후 – 결과를 검증하거나 후처리할 때 |
예를 들어 특정 명령어 실행을 막고 싶다면 PreToolUse 훅에서 종료 코드 2를 반환해 호출을 거부시킬 수 있고, 경고만 주고 진행시키고 싶다면 종료 코드 1을 쓰면 됩니다.
4. 슬래시 커맨드와 스킬로 반복 작업 등록하기
자주 쓰는 프롬프트는 슬래시 커맨드로 등록해두면 짧은 명령 하나로 바로 실행할 수 있습니다. 2026년부터는 커스텀 슬래시 커맨드가 스킬 체계로 통합되어, .claude/skills/이름/SKILL.md 형태로 만드는 것이 권장되는 방식입니다. 기존 .claude/commands/ 방식도 그대로 동작하니 마이그레이션은 여유 있게 진행해도 됩니다.
💡 TIP 처음엔 CLAUDE.md와 슬래시 커맨드/스킬부터 채우고, 프로젝트가 커지면서 반복 작업이 늘어날 때 서브에이전트와 훅을 하나씩 추가하는 순서를 추천합니다.
⚠️ 주의 훅은 결정적으로 실행되는 만큼, 잘못 설정하면 정상적인 작업까지 막힐 수 있습니다. 처음 설정할 때는 종료 코드 1(경고만)로 시작해 동작을 확인한 뒤 종료 코드 2(차단)로 강화하는 게 안전합니다.
네 가지 기능, 언제 뭘 써야 할까
기능이 늘어날수록 뭘 어디에 써야 할지 헷갈리기 쉽습니다. 아래처럼 "항상 적용"vs"필요할 때만", "제안"vs"강제" 기준으로 나눠보면 정리가 쉬워집니다.
| CLAUDE.md | 프로젝트 전체, 항상 | 맥락 제공(제안) |
| 서브에이전트 | 위임한 작업에 한정 | 역할·권한 분리 |
| 훅(Hooks) | 특정 이벤트 발생 시 | 코드로 강제 실행 |
| 슬래시 커맨드·스킬 | 호출했을 때만 | 반복 절차 재사용 |
첫째, "이 규칙은 모델이 알아서 판단해도 되는가"를 먼저 물어보세요.
그렇다면 CLAUDE.md나 스킬로 충분하고, 무조건 지켜야 하는 규칙이라면 훅으로 넘어가야 합니다.
둘째, 작업량이 많아 메인 대화가 복잡해진다면 서브에이전트로 쪼개세요.
독립된 컨텍스트에서 처리되기 때문에 메인 세션이 훨씬 가벼워집니다.
자주 묻는 질문
Q. CLAUDE.md와 서브에이전트에 주는 지시는 뭐가 다른가요?
CLAUDE.md는 프로젝트 전체에 항상 적용되는 기본 원칙이고, 서브에이전트는 특정 작업을 위임할 때만 그 세션에 한정해서 적용되는 별도의 역할·권한 설정입니다. 반복적으로 위임하는 작업이 있다면 서브에이전트로 따로 만들어두는 게 효율적입니다.
Q. 훅과 슬래시 커맨드/스킬 중 뭐부터 배워야 하나요?
슬래시 커맨드·스킬부터 시작하는 걸 추천합니다. 반복 프롬프트를 등록하는 정도라 진입장벽이 낮고, 익숙해진 뒤 "반드시 강제해야 하는 규칙"이 생기면 그때 훅으로 넘어가면 자연스럽습니다.
마무리하며
클로드 코드를 제대로 활용하려면 CLAUDE.md로 기본 맥락을 고정하고, 서브에이전트로 작업을 분리하고, 훅으로 규칙을 강제하고, 슬래시 커맨드·스킬로 반복 작업을 등록하는 네 가지를 순서대로 채워보세요. 프로젝트가 커질수록 이 세팅의 효과가 훨씬 크게 체감됩니다.