들어가며
Claude Code를 쓰다 보면 대부분 CLAUDE.md까지는 자연스럽게 만든다. 프로젝트 규칙 적어두고, 커맨드 몇 개 등록하고. 그런데 딱 거기서 막힌다. "서브에이전트는 뭐지?", "agents/는 어떻게 만드는 거지?", "rules/랑 skills/는 뭐가 다른 거야?"
나도 이 세팅 단계가 제일 헷갈렸다. 검색해보면 블로그마다 말이 다 다르고, 심지어 서로 모순되기도 한다. 이유는 단순하다. Claude Code는 체감상 거의 매주 바뀐다. 몇 달 전 글은 이미 틀린 내용일 가능성이 높다.
그래서 이 글은 공식 문서 기준으로 실제로 손대게 되는 것들을 추려서 정리했다.
기준 버전: 이 글은 2026년 8월 기준으로 작성했다. Claude Code는 업데이트가 매우 잦아서 세부 동작이 바뀔 수 있다. 핵심 개념을 잡은 뒤, 버전에 민감한 부분은 공식 문서(
code.claude.com/docs)로 교차 검증하는 걸 권장한다.
1. 모든 설정은 .claude/ 안에 있다
CLAUDE.md 이후의 세팅은 대부분 프로젝트 루트의 .claude/ 폴더 안에서 이뤄진다. 전체 그림부터 보자.
project/
├── CLAUDE.md # 매 세션 로드되는 프로젝트 지침
├── .mcp.json # 팀 공유 MCP 서버 (루트에 위치, .claude 밖!)
└── .claude/
├── settings.json # 권한 + 훅 + env + 모델 기본값
├── settings.local.json # 개인 오버라이드 (자동 gitignore)
├── rules/ # 주제별 지침 (파일 경로로 조건부 로드)
├── skills/ # /명령어로 부르는 재사용 워크플로우
├── commands/ # 단일 파일 슬래시 명령어 (레거시)
├── agents/ # 서브에이전트
├── workflows/ # 여러 서브에이전트 오케스트레이션
├── agent-memory/ # 서브에이전트 영속 메모리 (자동 생성)
└── output-styles/ # 응답 스타일 커스터마이징 (보통 개인용)핵심은 이거다. 대부분의 사용자는 CLAUDE.md와 settings.json만 편집한다. 나머지는 전부 선택 사항이고, 폴더가 없어도 되며, 필요할 때 Claude Code가 알아서 만들어준다. 그러니 처음부터 다 만들려고 스트레스받을 필요 없다.
.mcp.json은 .claude/ 안이 아니라 프로젝트 루트에 있다는 것만 주의하자. 자주 틀리는 부분이다.
2. 각 폴더가 하는 일
| 폴더/파일 | 역할 | 언제 손대나 |
|---|---|---|
CLAUDE.md | 매 세션 로드되는 프로젝트 지침 | 항상 (제일 먼저) |
settings.json | 권한, 훅, 환경변수, 모델 기본값 | 자주 |
settings.local.json | 개인용 오버라이드 (자동 gitignore) | 개인 설정 필요할 때 |
rules/ | 주제별로 쪼갠 지침, 경로 기반 조건부 로드 | CLAUDE.md가 길어지면 |
skills/ | /이름으로 부르는 워크플로우 (폴더 번들) | 반복 작업 자동화 |
commands/ | 단일 파일 슬래시 명령어 (레거시) | 신규는 skills 권장 |
agents/ | 서브에이전트 정의 | 격리된 특화 작업 |
workflows/ | 다중 서브에이전트 스크립트 | 복잡한 오케스트레이션 |
agent-memory/ | 서브에이전트 영속 메모리 | 자동 생성 (직접 X) |
output-styles/ | 응답 스타일 커스터마이징 | 대부분 개인용 |
이 중에서 현실적으로 손대는 건 위쪽 4~5개다. 아래로 갈수록 "나중에 필요하면 그때" 영역이다.
3. settings.json — 권한과 훅
settings.json은 CLAUDE.md와 함께 제일 많이 만지는 파일이다. CLAUDE.md가 Claude에게 주는 "가이드"라면, settings.json은 Claude Code가 실제로 강제하는 "규칙"이다. 크게 권한(permissions) 과 훅(hooks) 두 가지를 담는다.
권한 — 매번 승인 누르기 지겨울 때
Claude Code는 명령을 실행하기 전에 매번 물어본다. 자주 쓰는 안전한 명령은 allow에 등록해두면 확인 없이 바로 실행된다.
{
"permissions": {
"allow": [
"Bash(pnpm test *)",
"Bash(pnpm run *)",
"Bash(pnpm lint *)"
],
"deny": [
"Bash(rm -rf *)"
]
}
}allow— 확인 없이 실행deny— 아예 차단- 둘 다 없으면 → 실행 전에 물어봄 (기본값)
규칙 평가 순서는 deny → ask → allow다. 즉 deny가 allow보다 항상 우선한다. 위험한 명령을 deny에 박아두면 실수로도 안 돌아간다. Bash(pnpm test *)처럼 뒤에 *를 붙이면 그 명령으로 시작하는 모든 형태를 매칭한다.
훅 — 파일 저장하면 자동으로 포맷
훅은 세션의 특정 시점에 내 스크립트를 실행하는 기능이다. 프론트엔드에서 제일 바로 체감되는 건 파일 편집 직후 Prettier 자동 실행이다.
{
"hooks": {
"PostToolUse": [{
"matcher": "Edit|Write",
"hooks": [{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs pnpm exec prettier --write"
}]
}]
}
}PostToolUse는 도구 사용 "후"에 실행되고, matcher로 어떤 도구일 때 돌릴지 고른다. 위 예시는 Claude가 파일을 Edit/Write할 때마다 그 파일에 Prettier를 돌린다. ESLint 자동 수정이나 타입체크도 같은 방식으로 걸 수 있다.
헷갈리기 쉬운 점: 훅은
settings.json의hooks키에 설정한다. 여러 레포에서 보이는.claude/hooks/폴더는 Claude Code가 특별히 읽는 디렉토리가 아니라, 훅이 실행할 스크립트를 관습적으로 모아두는 곳일 뿐이다.command경로만 맞으면 스크립트는 프로젝트 어디에 있어도 된다.
한 가지 더. settings.local.json은 같은 형식이지만 자동으로 gitignore된다. 나만 쓰는 권한(예: Bash(docker *))은 여기에 두면 팀 설정을 건드리지 않고 개인 오버라이드를 얹을 수 있다.
4. 서브에이전트 세팅하기
개념부터
서브에이전트는 메인 대화창과 별도의 독립된 컨텍스트 창에서 도는 특화 에이전트다. 테스트 실행이나 코드베이스 탐색처럼 출력이 지저분하게 많은 작업을 서브에이전트한테 던지면, 그 로그는 서브에이전트 컨텍스트에 남고 메인에는 요약만 돌아온다.
브라우저 탭에 비유하면 이해가 쉽다. 옆길로 새는 작업을 새 탭에서 처리하고, 메인 흐름은 깨끗하게 유지하는 개념이다.
만드는 방법 1 — Claude에게 시키기
가장 쉬운 방법. Claude Code 안에서 자연어로 요청하면 된다.
readability, 성능, 접근성 관점에서 React 컴포넌트를 리뷰하는
code-reviewer 서브에이전트를 .claude/agents/에 만들어줘.
읽기 전용(Read, Grep, Glob)으로, sonnet 모델로.그러면 Claude가 프론트매터를 알아서 채워서 파일을 써준다.
참고: 예전에는
/agents명령어가 인터랙티브 생성 마법사를 열었지만, v2.1.198부터 제거됐다. 지금은 Claude에게 시키거나 파일을 직접 만드는 방식이다. 옛날 블로그에서 "/agents로 마법사가 뜬다"고 하면 그건 구버전 기준이다.
만드는 방법 2 — 직접 작성
서브에이전트는 그냥 YAML 프론트매터 + Markdown 본문 파일이다. name과 description만 필수다.
---
name: code-reviewer
description: React/TS 코드 품질·보안·접근성 리뷰 전문. 코드 작성/수정 직후 사용.
tools: Read, Grep, Glob, Bash
model: sonnet
---
당신은 프론트엔드 시니어 리뷰어입니다.
호출되면 git diff로 최근 변경을 확인하고 다음을 점검하세요:
- 컴포넌트 네이밍/구조, 불필요한 리렌더
- 타입 안정성 (any 남용, 제네릭)
- 접근성 (aria, 시맨틱 태그)
- 하드코딩된 시크릿/키
Critical / Warning / Suggestion 3단계로, 고치는 예시 코드까지 제시하세요.프론트엔드 실전 조합
React/Next/TS/Tailwind 스택 기준으로 이 조합이 잘 먹힌다.
code-reviewer (읽기 전용) — 위 예시. tools에서 Edit/Write를 빼는 게 핵심이다. 안 주면 리뷰하다가 멋대로 코드 고치는 사고를 막는다.
ui-builder (쓰기 가능) — 컴포넌트 생성 담당이라 Edit/Write가 필요하다.
---
name: ui-builder
description: 팀 컨벤션에 맞춰 React 컴포넌트/페이지 구현. Tailwind 사용.
tools: Read, Write, Edit, Grep, Glob
model: inherit
---
기존 컴포넌트 패턴을 먼저 grep으로 파악한 뒤 그 스타일에 맞춰 구현하세요.
- 함수형 컴포넌트 + 명시적 props 타입
- Tailwind 유틸리티 우선, 매직 넘버 지양
- 접근성 속성 기본 포함test-runner (테스트 격리 실행) — 테스트 실행처럼 출력이 긴 작업. 로그를 메인에서 격리하는 대표 케이스다. 실패한 케이스만 요약해서 돌려받는다.
---
name: test-runner
description: 테스트를 실행하고 실패한 케이스만 요약 보고. 테스트 관련 요청 시 사용.
tools: Bash, Read, Grep, Glob
model: haiku
---
호출되면 프로젝트의 테스트를 실행하세요 (pnpm test).
- 전체 로그를 그대로 붙여넣지 말 것
- 실패한 테스트의 이름, 파일 위치, 에러 메시지만 요약
- 실패 원인에 대한 짧은 가설을 덧붙일 것a11y-checker (접근성 검수) — 프론트엔드에 특히 유용하다. 컴포넌트의 접근성 문제만 집중적으로 잡는다.
---
name: a11y-checker
description: React 컴포넌트의 웹 접근성(a11y) 문제를 검수. UI 작업 후 사용.
tools: Read, Grep, Glob
model: sonnet
---
당신은 웹 접근성 전문가입니다. 컴포넌트를 읽고 다음을 점검하세요:
- 시맨틱 태그 사용 (div 남용 대신 button, nav, main 등)
- 이미지 alt, 폼 요소와 label 연결
- 키보드 내비게이션 (tabIndex, 포커스 관리)
- aria 속성의 오남용 여부
- 색상 대비만으로 정보를 전달하지 않는지
WCAG 기준 위반을 심각도와 함께 보고하고, 수정 코드를 제시하세요.파일을 어디에 두느냐로 범위가 갈린다.
.claude/agents/에 두면 git으로 팀과 공유되고,~/.claude/agents/(홈 디렉토리)에 두면 모든 프로젝트에서 쓰는 내 개인 에이전트가 된다.
model 필드 정리
| 값 | 의미 |
|---|---|
haiku | 빠르고 저렴. 단순 탐색/리뷰용 |
sonnet | 균형. 일반 작업 |
opus | 고성능. 복잡한 추론 |
inherit | 메인 세션 모델을 따라감 (생략 시 기본값) |
리뷰·탐색은 haiku로 비용 아끼고, 실제 구현은 inherit로 두는 식이 무난하다.
호출 방법
# 자연어 — Claude가 위임 여부 판단
code-reviewer로 방금 auth 변경 리뷰해줘
# @-멘션 — 그 에이전트가 확실히 실행됨
@code-reviewer 로 auth 변경 봐줘
# 세션 전체 고정
claude --agent code-reviewer함정 하나: 첫 폴더 생성 시 재시작
파일을 디스크에서 추가/수정하면 Claude Code가 몇 초 안에 감지해서 다음 위임부터 반영되고, 재시작이 필요 없다. 단, 해당 스코프의 agents 디렉토리를 처음 만드는 경우엔 재시작이 필요하다.
.claude/agents/ 폴더를 처음 만들고 "왜 인식이 안 되지?" 하는 경우가 이것 때문이다. 한 번만 재시작하면 그 뒤로는 자동 감지된다.
5. rules/로 CLAUDE.md 쪼개기
CLAUDE.md가 길어지면(대략 200줄 넘어가면) rules/로 쪼개는 게 좋다. 핵심은 paths: 프론트매터다.
paths:가 없는 규칙 → 세션 시작 시 항상 로드 (CLAUDE.md와 동일)paths:가 있는 규칙 → 매칭되는 파일이 컨텍스트에 들어올 때만 로드
즉 테스트 파일 작업할 때만 테스트 규칙이 붙는다. 컨텍스트를 아끼는 방식이다.
---
paths:
- "**/*.test.ts"
- "**/*.test.tsx"
---
# 테스트 규칙
- 서술적인 테스트명: "should [기대결과] when [조건]"
- 내부 모듈이 아니라 외부 의존성을 목킹
- afterEach에서 사이드이펙트 정리프론트엔드에선 컴포넌트 규칙 / 테스트 규칙 / API 규칙을 이렇게 나눠두면 딱 좋다.
6. skills vs commands (최근 변경점)
이 둘이 헷갈리는데, 지금은 커맨드와 스킬이 사실상 같은 메커니즘이고 신규 워크플로우는 skills/를 쓰라고 권장한다.
| skills/ | commands/ | |
|---|---|---|
| 구조 | 폴더 (SKILL.md + 참고 파일 번들) | 단일 파일 |
| 호출 | /이름 | /이름 |
| 상태 | 권장 | 레거시 (여전히 지원) |
둘 다 /이름으로 호출되지만, skills는 참고 문서·템플릿·스크립트를 함께 번들할 수 있어서 더 강력하다. 그래서 이제 commands/는 사실상 레거시 취급이다.
실제 skill 예시
PR 설명 초안을 자동 생성하는 /pr-desc 스킬을 만든다고 하자. .claude/skills/pr-desc/SKILL.md를 만들면 된다.
---
description: 현재 브랜치의 변경사항으로 PR 설명 초안을 작성한다
argument-hint: <base-branch>
---
## 변경 내역
!`git diff $ARGUMENTS...HEAD --stat`
위 변경사항을 바탕으로 PR 설명을 작성하세요:
## 요약
- 무엇을, 왜 바꿨는지 2~3줄
## 변경 상세
- 주요 변경점을 불릿으로
## 테스트
- 어떻게 검증했는지이제 /pr-desc main이라고 치면 두 가지가 일어난다. $ARGUMENTS에 "main"이 들어가고, !` 로 시작하는 줄이 셸에서 먼저 실행돼 그 출력(git diff 결과)이 프롬프트에 주입된다. 이렇게 셸 명령 결과를 프롬프트에 끼워넣을 수 있다는 게 skill의 강력한 점이다. 단순 프롬프트 저장을 넘어서, 실행 컨텍스트까지 자동으로 채워준다.
마치며
한 번에 다 세팅하려고 하면 지친다. 나는 이 순서를 추천한다.
- CLAUDE.md — 프로젝트 규칙 (항상)
- settings.json — 자주 쓰는 명령 권한 등록 + Prettier 자동 실행 훅
- agents/ —
code-reviewer하나만 먼저. 읽기 전용이라 위험 없고 바로 유용하다 - rules/ — CLAUDE.md 길어지면 주제별로 쪼개기
- skills/ — 반복하는 작업이 생기면 그때 스킬로
workflows/, output-styles/ 같은 건 나중에 필요하면 그때 봐도 충분하다.
그리고 가장 중요한 것 하나. Claude Code는 정말 자주 바뀐다. 이 글도 언젠가 낡을 것이다. 개념을 잡는 용도로 쓰되, 버전에 민감한 부분은 항상 공식 문서로 확인하자.
