Claude Code를 프로처럼 사용하는 법
Claude Code를 처음 사용하다 보면, 프로젝트 루트에 어느새 .claude라는 폴더가 생겨나 있는 것을 발견하게 됩니다. 대부분의 개발자들은 이 폴더를 그냥 지나치거나, 건드리지 않고 무시합니다. 그러나 이 작은 폴더 안에는 Claude가 어떻게 동작할지를 결정하는 핵심 설정 파일들이 모두 담겨 있습니다. .claude 폴더를 제대로 이해하고 활용하면, Claude는 단순한 코드 보조 도구에서 벗어나 팀의 코딩 규칙을 완벽히 이해하는 전문 AI 동료로 거듭납니다. 이 글에서는 .claude 폴더의 모든 구성요소를 처음부터 끝까지, 일반인도 이해할 수 있도록 상세하게 해부해 보겠습니다.
목 차
1. .claude 폴더란 무엇인가?
.claude 폴더는 Claude Code가 프로젝트 내에서 어떻게 행동해야 하는지를 정의하는 제어 센터(Control Center)입니다. Claude Code는 터미널에서 직접 AI와 대화하며 코드를 작성하고, 파일을 수정하고, 명령을 실행할 수 있는 강력한 CLI 도구입니다. 그런데 이 도구는 단순히 질문에 답하는 것을 넘어, 우리 프로젝트의 구조와 규칙, 팀의 코딩 스타일까지 학습하고 따를 수 있습니다. 그 학습의 근거가 되는 모든 정보가 바로 .claude 폴더 안에 담겨 있습니다.
.claude 폴더가 없으면 Claude는 매번 프로젝트 구조를 새로 파악해야 하고, 팀의 코딩 컨벤션을 모른 채 일반적인 방식으로 코드를 작성합니다. 반면 .claude 폴더가 잘 구성되어 있으면, Claude는 세션 시작 직후부터 프로젝트의 모든 규칙을 이미 알고 있는 상태로 작업을 시작합니다. 이 차이는 생산성에서 엄청난 차이를 만들어냅니다.
2. 두 개의 .claude 폴더 | 프로젝트 vs 글로벌
많은 분들이 .claude 폴더가 하나만 있다고 생각하지만, 실제로는 두 가지 위치에 존재합니다. 이 둘은 각각 다른 역할을 담당하며, Claude는 세션 시작 시 두 폴더를 모두 읽어 하나의 통합된 지시사항을 구성합니다. 역할을 명확히 구분하면 각각을 더욱 효과적으로 활용할 수 있습니다.
아래 표는 두 폴더의 차이점을 한눈에 정리한 것입니다.
| 구분 | 프로젝트 레벨(.claude) | 글로벌 레벨(.claude) |
| 위치 | 프로젝트 루트 내부 | 홈 디렉토리 |
| 적용 범위 | 해당 프로젝트에만 적용 | 모든 프로젝트에 적용 |
| Git 관리 | 커밋하여 팀과 공유 | 로컬 머신에만 존재 |
| 주요 용도 | 팀 규칙, 프로젝트 설정 | 개인 선호도, 전역 설정 |
| 설정 우선순위 | 프로젝트별 설정 우선 | 기본값 역할 |
- 프로젝트 레벨 폴더는 팀 전체가 공유해야 하는 설정을 담습니다. 코딩 스타일, 테스트 명령어, API 설계 규칙 등 팀원 누구나 따라야 하는 내용이 여기에 들어갑니다. Git에 커밋하면 팀원 모두가 동일한 환경에서 Claude를 사용할 수 있습니다.
- 글로벌 레벨 폴더는 나만의 개인 설정을 저장합니다. 특정 언어 선호, 코딩 스타일, 개인 슬래시 명령어 등이 여기에 해당합니다. 이 설정은 어떤 프로젝트에서 Claude를 실행해도 항상 적용됩니다. 단, 로컬 머신에만 존재하므로 팀원에게는 영향을 주지 않습니다.
3. CLAUDE.md | Claude에게 보내는 지시서
.claude 폴더의 모든 파일 중 가장 중요한 파일은 단연 CLAUDE.md입니다. Claude Code는 세션을 시작할 때 가장 먼저 이 파일을 읽고, 그 내용을 시스템 프롬프트(System Prompt)에 그대로 삽입합니다. 즉, CLAUDE.md에 적힌 내용은 Claude가 그 세션 동안 반드시 따르는 핵심 지침이 됩니다. "항상 TypeScript strict mode를 사용하세요"라고 적어두면, Claude는 해당 세션 내내 그 규칙을 지킵니다.
CLAUDE.md는 프로젝트 루트, ~/.claude/ 글로벌 위치, 그리고 하위 디렉토리에도 각각 만들 수 있습니다. Claude는 이 파일들을 모두 읽어서 하나로 합쳐 사용합니다. 예를 들어 src/api/CLAUDE.md를 만들면 API 관련 작업 시에만 적용되는 규칙을 따로 관리할 수 있습니다.
CLAUDE.md에 적어야 할 내용
CLAUDE.md를 처음 작성할 때 많은 분들이 너무 많이 쓰거나, 너무 적게 쓰는 실수를 합니다. 핵심은 Claude가 프로젝트에서 일하기 위해 반드시 알아야 하는 것만 담는 것입니다.
[v] 반드시 포함해야 할 항목:
- 빌드/테스트/린트 명령어 (npm run test, make build 등): Claude가 코드를 수정한 후 직접 테스트를 실행할 수 있어야 합니다. 명령어를 알면 스스로 검증할 수 있습니다.
- 핵심 아키텍처 결정사항: 모노레포 구조, 주요 프레임워크, 디렉토리 구조 같은 전체적인 설계 원칙을 알려주세요. 이를 모르면 잘못된 위치에 파일을 생성하거나 잘못된 방식으로 코드를 작성할 수 있습니다.
- 비직관적인 주의사항: 타 프로젝트와 다른 특이한 규칙, 알아야 할 함정들을 미리 알려주세요. 예를 들어 "테스트는 목(mock)을 사용하지 않고 실제 DB를 사용합니다. 실행 전 npm run db:test:reset을 먼저 실행하세요"와 같은 내용이 이에 해당합니다.
- 임포트 규칙 및 네이밍 패턴: 파일명 규칙, 함수명 규칙, 에러 처리 방식 같은 코딩 컨벤션을 명시하세요.
[!] 넣지 말아야 할 항목:
- .eslintrc, .prettierrc 등 별도 설정 파일로 관리 가능한 내용은 중복 기술하지 않습니다.
- 링크로 대체 가능한 긴 문서는 URL만 기재하세요.
- 이론적 배경이나 긴 설명 문장은 필요하지 않습니다.
[!] 중요: CLAUDE.md는 200줄 이하로 유지하는 것이 좋습니다. 파일이 너무 길면 컨텍스트 창을 과도하게 차지하여 Claude의 지시사항 준수율이 실제로 낮아집니다.
아래는 실무에서 바로 사용할 수 있는 최소한의 효과적인 CLAUDE.md 예시입니다.
# Project: Acme API
## 주요 명령어
npm run dev # 개발 서버 시작
npm run test # Jest 테스트 실행
npm run lint # ESLint + Prettier 검사
npm run build # 프로덕션 빌드
npm run db:test:reset # 테스트 DB 초기화 (테스트 실행 전 필수)
## 아키텍처
- Express REST API, Node 20 기반
- PostgreSQL (Prisma ORM 사용)
- 모든 핸들러는 src/handlers/ 에 위치
- 공유 타입 정의는 src/types/ 에 위치
## 코딩 컨벤션
- 모든 요청 핸들러는 zod 스키마로 입력값 검증 필수
- 응답 형태는 항상 { data, error } 구조 사용
- 클라이언트에 스택 트레이스 노출 금지
- console.log 대신 반드시 logger 모듈 사용
## 주의사항
- TypeScript strict mode 활성화: 미사용 import 절대 금지
- 테스트는 목(mock)이 아닌 실제 로컬 DB 사용
CLAUDE.local.md | 개인 전용 오버라이드
팀 전체의 CLAUDE.md와 별개로, 나만의 개인 설정이 필요할 때는 CLAUDE.local.md를 프로젝트 루트에 만들면 됩니다. 이 파일은 .gitignore에 자동으로 등록되어 Git 저장소에는 커밋되지 않습니다. 예를 들어 특정 파일 열기 방식, 개인 디버깅 명령어, 또는 팀과 다른 테스트 접근 방식을 선호한다면 이 파일에 적어두면 됩니다.
4. rules/ 폴더 | 규칙의 모듈화
프로젝트가 성장하면서 CLAUDE.md가 300줄, 400줄을 넘어가기 시작하면, 아무도 유지보수하지 않는 거대한 문서가 되어버립니다. rules/ 폴더는 바로 이 문제를 해결하기 위해 존재합니다. .claude/rules/ 안에 있는 모든 마크다운 파일은 CLAUDE.md와 함께 자동으로 로드됩니다. 하나의 거대한 파일 대신, 관심사별로 분리된 작고 집중된 파일들로 규칙을 관리할 수 있습니다.
.claude/rules/
├── code-style.md # 코딩 스타일 규칙
├── testing.md # 테스트 작성 규칙
├── api-conventions.md # API 설계 규칙
└── security.md # 보안 관련 규칙
각 파일은 담당자가 있어서 독립적으로 수정할 수 있습니다. API 규칙 담당자는 api-conventions.md만 수정하고, 테스트 표준 담당자는 testing.md만 수정합니다. 이렇게 하면 팀원들이 서로 충돌 없이 Claude의 행동 규칙을 유지보수할 수 있습니다.
경로 기반 조건부 규칙
rules/ 폴더의 가장 강력한 기능은 경로 조건(Path Scoping)입니다. 파일 상단에 YAML frontmatter를 추가하면, 그 규칙은 지정된 경로의 파일을 다룰 때만 활성화됩니다. React 컴포넌트를 수정할 때는 API 규칙이 필요 없고, API 핸들러를 수정할 때는 React 규칙이 필요 없습니다. 경로 조건을 활용하면 불필요한 규칙이 컨텍스트를 차지하는 낭비를 막을 수 있습니다.
아래는 api-conventions.md 파일에 경로 조건을 적용한 예시입니다.
---
paths:
- "src/api/**/*.ts"
- "src/handlers/**/*.ts"
---
# API 설계 규칙
- 모든 핸들러의 응답 형태는 { data, error } 구조를 따릅니다
- 요청 본문 검증은 반드시 zod 스키마를 사용합니다
- 클라이언트에 내부 에러 상세 내용을 노출하지 않습니다
- 인증이 필요한 엔드포인트는 authMiddleware를 반드시 적용합니다
이 파일은 Claude가 src/api/ 또는 src/handlers/ 안의 파일을 작업할 때만 로드됩니다. paths 필드가 없는 규칙 파일은 조건 없이 항상 로드됩니다.
5. commands/ 폴더 | 나만의 슬래시 명령어
Claude Code에는 기본으로 제공되는 /help, /compact 같은 슬래시 명령어가 있습니다. commands/ 폴더를 사용하면 팀만의 커스텀 슬래시 명령어를 만들 수 있습니다. 명령어를 만드는 방법은 매우 간단합니다. .claude/commands/ 폴더 안에 마크다운 파일을 넣으면, 파일명이 그대로 명령어 이름이 됩니다. review.md 파일은 /project:review 명령어가 되고, fix-issue.md 파일은 /project:fix-issue 명령어가 됩니다.
[i]참고 : .claude/commands/ 디렉토리는 레거시 포맷입니다. 현재 권장 포맷은 .claude/skills/<name>/SKILL.md이며, 슬래시 명령 호출(/name)과 Claude의 자율 호출을 모두 지원합니다. Claude API Docs 즉, commands/ 폴더는 하위 호환성 유지를 위해 계속 동작하지만, 신규 작성은 skills/로 통합하는 것이 Anthropic의 공식 권장 방향입니다.
커스텀 명령어의 가장 강력한 기능은 실시간 쉘 명령어 실행입니다. 파일 내에서 ! `명령어` 문법을 사용하면, 명령어가 실행될 때 쉘 명령의 출력이 프롬프트에 자동으로 삽입됩니다. 이를 통해 실제 코드 상태를 반영한 동적인 명령어를 만들 수 있습니다.
---
description: 메인 브랜치와의 diff를 분석하여 코드 리뷰를 수행합니다
---
## 변경된 파일 목록
!`git diff --name-only main...HEAD`
## 상세 변경 내용
!`git diff main...HEAD`
위의 변경사항을 다음 기준으로 리뷰해주세요:
1. 코드 품질 및 가독성 문제
2. 보안 취약점 여부
3. 누락된 테스트 커버리지
4. 성능 우려 사항
파일별로 구체적이고 실행 가능한 피드백을 제공해주세요.
이 파일을 .claude/commands/review.md로 저장하면, /project:review를 실행할 때 실제 git diff가 자동으로 Claude에게 전달됩니다.
$ARGUMENTS로 동적 인자 전달
명령어에 인자를 넘겨야 할 때는 $ARGUMENTS 변수를 사용합니다. 아래 예시는 GitHub 이슈 번호를 인자로 받아 해당 이슈를 분석하고 수정하는 명령어입니다.
---
description: GitHub 이슈를 분석하고 수정 후 테스트를 작성합니다
argument-hint: [이슈 번호]
---
이슈 #$ARGUMENTS 를 분석합니다.
!`gh issue view $ARGUMENTS`
위 이슈의 버그를 근본 원인까지 추적하고, 수정한 뒤,
해당 버그를 감지할 수 있는 테스트를 작성해주세요.
/project:fix-issue 234를 실행하면, 234번 이슈의 내용이 자동으로 Claude에게 전달됩니다. $ARGUMENTS는 명령어 이름 뒤에 오는 모든 텍스트로 대체됩니다.
개인 vs 팀 명령어
.claude/commands/의 명령어는 Git에 커밋되어 팀 전체가 공유합니다. 반면 ~/.claude/commands/에 저장한 개인 명령어는 /user:명령어명 형태로 모든 프로젝트에서 사용할 수 있습니다. 일일 스탠드업 요약, 커밋 메시지 생성, 개인 코드 스타일 검사 등 개인 워크플로우에 특화된 명령어를 여기에 저장하면 좋습니다.
6. skills/ 폴더 | 자동 호출 워크플로우
skills/ 폴더는 commands/와 비슷해 보이지만, 핵심적인 차이가 있습니다. Commands는 사용자가 직접 호출하지만, Skills는 Claude가 대화의 맥락을 분석하여 스스로 호출합니다. "이 코드 보안 검토해줘"라고 말하면, Claude는 스스로 security-review 스킬이 적합하다고 판단하고 자동으로 실행합니다. 사용자는 슬래시 명령어를 외울 필요가 없습니다.
각 스킬은 고유한 서브디렉토리와 SKILL.md 파일로 구성됩니다. 이 구조 덕분에 스킬은 보조 파일을 함께 번들링할 수 있어, 단일 파일인 Commands보다 훨씬 복잡한 워크플로우를 담을 수 있습니다.
.claude/skills/
├── security-review/
│ ├── SKILL.md # 스킬 정의 및 트리거 조건
│ └── DETAILED_GUIDE.md # 보안 기준 상세 문서
└── deploy/
├── SKILL.md
└── templates/
└── release-notes.md
SKILL.md는 YAML frontmatter를 통해 언제 이 스킬을 사용할지를 Claude에게 알려줍니다.
---
name: security-review
description: 코드 보안 감사. 취약점 검토, 배포 전 보안 검사,
또는 사용자가 보안을 언급할 때 사용합니다.
allowed-tools: Read, Grep, Glob
---
코드베이스의 보안 취약점을 분석합니다:
1. SQL 인젝션 및 XSS 위험
2. 노출된 자격 증명 또는 비밀
3. 안전하지 않은 설정
4. 인증 및 인가 취약점
@DETAILED_GUIDE.md 의 보안 기준을 참조하여
심각도 등급과 구체적인 수정 방안을 함께 보고해주세요.
allowed-tools 필드는 이 스킬이 사용할 수 있는 도구를 제한합니다. 보안 검토 스킬은 파일을 읽는 것만 필요하므로, Read, Grep, Glob만 허용합니다. 파일을 쓰거나 쉘을 실행할 권한은 주지 않습니다. 이렇게 최소 권한 원칙을 적용하면 의도치 않은 파일 수정 사고를 예방할 수 있습니다.
7. agents/ 폴더 | 전문 서브에이전트 정의
복잡한 작업을 처리할 때, Claude는 자신의 메인 컨텍스트 안에서 모든 것을 처리하려고 합니다. 이때 수천 개의 토큰이 중간 탐색 과정으로 채워지면 메인 세션이 지저분해집니다. agents/ 폴더는 이 문제를 해결합니다. 각 에이전트는 자신만의 독립된 컨텍스트 창에서 작업하고, 결과만 압축하여 메인 세션에 보고합니다.
에이전트는 전문화된 AI 페르소나라고 생각하면 됩니다. "시니어 코드 리뷰어", "보안 감사 전문가", "테스트 작성 전문가"처럼 특정 역할에 최적화된 시스템 프롬프트, 도구 권한, 모델을 가진 독립적인 AI 에이전트를 정의할 수 있습니다.
---
name: code-reviewer
description: 전문 코드 리뷰어. PR 검토, 버그 발견, 머지 전 구현 검증 시 적극 활용합니다.
model: sonnet
tools: Read, Grep, Glob
---
당신은 정확성과 유지보수성에 집중하는 시니어 코드 리뷰어입니다.
코드를 리뷰할 때:
- 스타일 문제보다 실제 버그를 먼저 찾아냅니다
- 막연한 개선 제안 대신 구체적인 수정 코드를 제안합니다
- 엣지 케이스와 에러 처리 누락을 확인합니다
- 규모에서 실제로 문제가 될 때만 성능 우려를 언급합니다
model 필드를 활용하면 작업 복잡도에 따라 모델을 최적화할 수 있습니다. 읽기 전용 탐색이나 간단한 분석 작업은 빠르고 저렴한 haiku로, 복잡한 설계 결정이나 심층 분석이 필요한 작업은 sonnet이나 opus로 처리합니다. 이를 통해 비용과 성능 사이의 최적 균형을 찾을 수 있습니다.
| 에이전트 예시 | 권장모델 | 역할 | 설명 |
| code-reviewer | sonnet | Read, Grep, Glob | 코드 품질 및 버그 검토 |
| security-auditor | sonnet | Read, Grep | 보안 취약점 탐지 |
| test-writer | sonnet | Read, Write | 테스트 코드 자동 작성 |
| doc-generator | haiku | Read, Write | 코드 문서화 자동화 |
| dependency-checker | haiku | Read, Bash | 패키지 의존성 분석 |
개인 에이전트는 ~/.claude/agents/에 저장하면 모든 프로젝트에서 사용할 수 있습니다.
8. settings.json | 권한과 보안 정책
settings.json은 Claude가 실행할 수 있는 작업의 경계를 정의하는 보안 정책 파일입니다. 이 파일을 통해 어떤 명령어는 확인 없이 바로 실행하고, 어떤 명령어는 완전히 차단할지를 세밀하게 제어할 수 있습니다. 특히 팀 환경에서 Git에 커밋하여 모든 팀원에게 동일한 보안 정책을 적용하는 것이 중요합니다.
Claude의 권한 처리는 3단계로 이루어집니다. 먼저 deny 목록을 검사하여 해당 명령이 있으면 즉시 차단합니다. 그 다음 allow 목록을 검사하여 해당 명령이 있으면 확인 없이 즉시 실행합니다. 두 목록 모두에 없는 명령은 실행 전 사용자에게 확인을 요청합니다.
아래는 실전에서 바로 사용할 수 있는 settings.json 예시입니다.
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(npm run *)",
"Bash(yarn *)",
"Bash(git status)",
"Bash(git diff *)",
"Bash(git log *)",
"Read",
"Write",
"Edit",
"Glob",
"Grep"
],
"deny": [
"Bash(rm -rf *)",
"Bash(curl *)",
"Bash(wget *)",
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/*)"
]
}
}
$schema 필드는 포함하시는것을 추천드립지만 필수사항은 아닙니다. VS Code나 Cursor 같은 편집기에서 자동완성과 인라인 유효성 검사를 제공하여 설정 파일 작성을 훨씬 편하게 만들어 줍니다.
allow 목록 설정 가이드:
- Bash(npm run *) 처럼 와일드카드(*)를 사용하면 npm run dev, npm run test, npm run build 등 모든 npm 스크립트를 한 번에 허용할 수 있습니다.
- Read, Write, Edit, Glob, Grep은 일반적인 파일 작업이므로 대부분의 프로젝트에서 허용하는 것이 좋습니다.
- Bash(git *) 대신 Bash(git status), Bash(git diff *) 처럼 읽기 전용 git 명령만 구체적으로 허용하면 더 안전합니다.
deny 목록 설정 가이드:
- Bash(rm -rf *) 는 반드시 차단하세요. 실수로 중요한 파일이 삭제될 위험을 방지합니다.
- Bash(curl *), Bash(wget *) 같은 네트워크 명령도 차단하는 것이 좋습니다. Claude가 의도치 않은 외부 요청을 보내는 것을 막을 수 있습니다.
- .env 파일과 secrets/ 디렉토리는 민감한 정보가 담겨 있으므로 반드시 차단하세요.
개인 권한 설정은 settings.local.json에 저장하면 .gitignore에 자동 등록됩니다. 이를 통해 팀 정책은 유지하면서 개인적인 권한 조정이 가능합니다.
9. 글로벌 ~/.claude 폴더 완전 정리
~/.claude/ 폴더는 홈 디렉토리에 위치하며, 모든 프로젝트에 걸쳐 적용되는 개인 전용 설정을 저장합니다. 이 폴더는 직접 편집하는 경우가 많지 않지만, 무엇이 들어있는지 알고 있으면 Claude의 동작을 훨씬 더 세밀하게 이해하고 제어할 수 있습니다.
~/.claude/
├── CLAUDE.md # 모든 프로젝트에 적용되는 개인 지시사항
├── settings.json # 전역 권한 설정
├── commands/ # 개인 슬래시 명령어 (/user:명령어명)
├── skills/ # 개인 전용 자동 호출 스킬
├── agents/ # 개인 전용 서브에이전트
└── projects/ # 프로젝트별 세션 기록 및 자동 메모리
├── my-project/
│ └── memory.md # 해당 프로젝트에서 학습한 내용
└── another-project/
└── memory.md
- ~/.claude/CLAUDE.md 에는 어떤 프로젝트에서 작업하든 항상 유효한 개인 원칙을 적어두면 좋습니다. 예를 들어 "타입을 먼저 정의한 후 구현합니다", "함수형 패턴을 클래스 기반보다 선호합니다", "항상 한국어로 주석을 작성합니다" 같은 개인 코딩 철학이 이에 해당합니다.
- ~/.claude/projects/ 는 Claude가 자동으로 관리하는 폴더입니다. Claude Code는 작업하면서 발견한 패턴, 아키텍처 통찰, 중요한 명령어 등을 스스로 이 폴더에 메모로 저장합니다. 이 메모들은 세션이 종료되어도 유지되어, 다음 세션에서 Claude가 이전 작업 내용을 기억하는 것처럼 보이게 합니다. /memory 명령어로 이 내용을 조회하고 편집할 수 있습니다. 특정 프로젝트의 자동 메모리를 초기화하고 싶다면 해당 프로젝트 폴더를 삭제하면 됩니다.
10. 실전 셋업 가이드 | 처음부터 구성하기
이론을 배웠으니 이제 실제로 .claude 폴더를 처음부터 구성하는 방법을 단계별로 살펴보겠습니다. 처음부터 완벽하게 만들려고 하지 말고, 단계적으로 쌓아가는 것이 핵심입니다.
Step 1 | /init 명령으로 기초 생성
Claude Code 터미널에서 /init 명령을 실행하면 Claude가 현재 프로젝트를 분석하여 기본 CLAUDE.md를 자동 생성해줍니다. 생성된 파일을 편집하여 핵심 내용만 남기고 불필요한 내용을 정리하세요.
# Claude Code 터미널에서 실행
/init
Step 2 | settings.json으로 권한 정책 수립
스택에 맞는 allow와 deny 목록을 설정합니다. Node.js 프로젝트라면 npm run *을 허용하고, Python 프로젝트라면 python *을 허용하는 방식으로 조정하세요. .env 파일 읽기는 항상 차단하는 것을 잊지 마세요.
# 프로젝트 루트에 .claude/ 폴더 생성 후 settings.json 작성
mkdir -p .claude
cat > .claude/settings.json << 'EOF'
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(npm run *)",
"Bash(git status)",
"Bash(git diff *)",
"Read", "Write", "Edit", "Glob", "Grep"
],
"deny": [
"Bash(rm -rf *)",
"Bash(curl *)",
"Read(./.env)",
"Read(./.env.*)"
]
}
}
EOF
Step 3 | 자주 쓰는 명령어 등록
가장 자주 반복하는 워크플로우를 커스텀 명령어로 만듭니다. 코드 리뷰와 이슈 수정은 대부분의 개발자에게 적합한 시작점입니다.
# commands 폴더 생성
mkdir -p .claude/commands
# 코드 리뷰 명령어 생성
cat > .claude/commands/review.md << 'EOF'
---
description: 현재 브랜치의 변경사항을 메인과 비교하여 코드 리뷰를 수행합니다
---
## 변경된 파일
!`git diff --name-only main...HEAD`
## 상세 변경 내용
!`git diff main...HEAD`
코드 품질, 보안 취약점, 테스트 누락, 성능 이슈를 파일별로 검토해주세요.
EOF
Step 4 | CLAUDE.md가 커지면 rules/로 분리
CLAUDE.md가 50줄을 넘어가기 시작하면, 관심사별로 rules/ 폴더로 분리할 타이밍입니다. 경로 조건이 필요한 규칙은 frontmatter를 추가하세요.
mkdir -p .claude/rules
# API 규칙 파일 생성 (경로 조건 포함)
cat > .claude/rules/api-conventions.md << 'EOF'
---
paths:
- "src/api/**"
- "src/handlers/**"
---
# API 설계 규칙
- 응답 형태: { data, error } 구조 사용
- 입력 검증: zod 스키마 필수
- 에러: 내부 상세 내용 클라이언트 노출 금지
EOFStep 5 | 개인 글로벌 설정 구성
~/.claude/CLAUDE.md에 모든 프로젝트에 적용할 개인 코딩 원칙을 작성합니다.
cat > ~/.claude/CLAUDE.md << 'EOF'
# 개인 코딩 원칙
## 코딩 스타일
- 타입을 구현보다 먼저 정의합니다
- 클래스보다 함수형 패턴을 선호합니다
- 복잡한 로직에는 한국어 주석을 추가합니다
## 커뮤니케이션
- 코드 변경 시 변경 이유를 함께 설명합니다
- 여러 접근 방식이 있을 때는 트레이드오프를 설명합니다
EOF
완성된 폴더 구조 전체 보기
모든 단계를 완료하면 다음과 같은 구조가 완성됩니다.
my-project/
├── CLAUDE.md # 팀 핵심 지시사항 (Git 커밋)
├── CLAUDE.local.md # 개인 오버라이드 (gitignored)
│
└── .claude/
├── settings.json # 권한 정책 (Git 커밋)
├── settings.local.json # 개인 권한 오버라이드 (gitignored)
│
├── commands/ # 팀 커스텀 명령어
│ ├── review.md # /project:review
│ ├── fix-issue.md # /project:fix-issue
│ └── deploy.md # /project:deploy
│
├── rules/ # 모듈화된 규칙
│ ├── code-style.md
│ ├── testing.md
│ └── api-conventions.md
│
├── skills/ # 자동 호출 스킬
│ └── security-review/
│ ├── SKILL.md
│ └── DETAILED_GUIDE.md
│
└── agents/ # 서브에이전트
├── code-reviewer.md
└── security-auditor.md
12. Hooks | 결정론적 자동화 하네스
지금까지 살펴본 모든 .claude 구성요소들, 즉 CLAUDE.md, rules/, commands/, skills/, agents/는 한 가지 공통적인 한계를 가지고 있습니다. 이 모든 것은 Claude에게 "이렇게 해 달라"고 부탁하는 제안(Suggestion)에 가깝습니다. 대화가 길어지면 컨텍스트 창 밖으로 밀려날 수 있고, 우선순위에 따라 무시될 수도 있습니다. Hooks는 이 근본적인 한계를 해결합니다. 훅은 Claude의 작업 라이프사이클 특정 시점에 반드시 실행되는 보장된 자동화입니다. "항상 저장 후 린트를 실행해줘"라고 CLAUDE.md에 적는 것과, PostToolUse 훅으로 린트를 등록하는 것은 완전히 다른 신뢰도를 가집니다.
훅은 settings.json의 hooks 섹션에 정의하며, 프로젝트 레벨(.claude/settings.json)과 글로벌 레벨(~/.claude/settings.json) 모두에 설정할 수 있습니다. 팀 전체가 따라야 하는 코드 품질 훅은 프로젝트 설정에, 개인 알림이나 로깅 훅은 글로벌 설정에 넣는 것이 좋습니다.
12가지 훅 이벤트 완전 정리
Claude Code는 에이전트 실행 주기 전반에 걸쳐 12가지 이벤트를 제공합니다. 각 이벤트는 Claude의 작동 주기 중 특정 시점을 나타내며, 그 시점에 외부 스크립트나 Claude 모델 자체를 호출할 수 있습니다.
| 이벤트 | 발생시점 | 차단가능 | 주요 용도 |
| PreToolUse | 도구 실행 직전 | [v] 가능 | 위험 명령 차단, 입력값 수정 |
| PostToolUse | 도구 실행 완료 후 | [x] 불가 | 린트/포맷, 결과 검증, 로깅 |
| UserPromptSubmit | 사용자 프롬프트 제출 시 | [v] 가능 | 프롬프트 전처리, 컨텍스트 주입 |
| PermissionRequest | 권한 다이얼로그 표시 전 | [v] 가능 | 권한 정책 자동화 |
| Stop | Claude 응답 완료 시 | [x] 불가 | 테스트 실행, 완료 알림 |
| SubagentStop | 서브에이전트 완료 시 | [x] 불가 | 부분 결과 집계, 상태 추적 |
| SessionEnd | 세션 종료 시 | [x] 불가 | 임시 파일 정리, 사용량 통계 |
| Setup | 저장소 초기화/유지보수 시 | - | 환경 구성, 의존성 설치 |
[!] 가장 중요한 원칙: PreToolUse만이 도구 실행을 차단할 수 있는 유일한 이벤트입니다. 다른 이벤트들은 이미 일어난 일에 반응하거나, 완료 후 처리를 담당합니다.
3가지 훅 핸들러 유형
훅이 실행될 때 실제로 무엇을 실행할지는 핸들러 유형으로 결정합니다. 작업의 복잡도와 성격에 따라 세 가지를 선택적으로 조합할 수 있습니다.
- [command] 쉘 명령 핸들러: 가장 기본적인 유형으로, 쉘 스크립트나 명령어를 직접 실행합니다. 훅 스크립트는 도구 호출 컨텍스트를 JSON 형태로 stdin으로 받고, exit 코드로 결과를 반환합니다. exit 0은 허용, exit 2는 차단입니다. 빠르고 가벼운 검사(정규식 패턴 매칭, 파일 존재 확인 등)에 가장 적합합니다.
- [prompt] AI 평가 핸들러: Claude 모델에게 판단을 위임하는 고급 유형입니다. "이 코드 변경이 인증 로직에 영향을 주는가?"처럼 정규식으로는 표현하기 어려운 의미론적 조건을 평가할 때 사용합니다. $ARGUMENTS 자리에 이벤트 JSON이 삽입되어 모델이 판단합니다.
- [agent] 서브에이전트 핸들러: Read, Grep, Glob 등의 도구를 가진 서브에이전트를 생성하여 심층 분석을 수행합니다. 단순한 패턴 확인을 넘어, 전체 코드베이스를 탐색하며 복잡한 규칙 위반을 찾아야 할 때 적합합니다. 가장 강력하지만 실행 시간이 길어질 수 있으므로 중요한 체크포인트에만 사용하는 것이 좋습니다.
실전 훅 설정 예시
아래는 .claude/settings.json 또는 ~/.claude/settings.json에 작성하는 실전 훅 설정입니다. 이 예시는 위험 명령 차단과 자동 린트를 함께 구현합니다.
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": ["Bash(npm run *)", "Read", "Write", "Edit"],
"deny": ["Bash(curl *)", "Read(./.env)"]
},
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "python3 ~/.claude/hooks/block-dangerous.py"
}
]
}
],
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "bash ~/.claude/hooks/auto-lint.sh"
}
]
}
],
"Stop": [
{
"matcher": ".*",
"hooks": [
{
"type": "command",
"command": "bash ~/.claude/hooks/run-tests-if-changed.sh"
}
]
}
]
}
}
위 설정에서 참조하는 block-dangerous.py 스크립트의 핵심 구조는 다음과 같습니다.
#!/usr/bin/env python3
# ~/.claude/hooks/block-dangerous.py
# PreToolUse 훅: 위험한 Bash 명령 차단
import sys
import json
# 도구 컨텍스트를 stdin에서 JSON으로 읽음
data = json.load(sys.stdin)
tool_name = data.get("tool_name", "")
tool_input = data.get("tool_input", {})
command = tool_input.get("command", "")
# 위험 패턴 목록
DANGEROUS_PATTERNS = [
"rm -rf",
"dd if=",
"> /dev/",
"mkfs",
":(){ :|:& };:" # fork bomb
]
for pattern in DANGEROUS_PATTERNS:
if pattern in command:
# stderr로 전달하면 Claude에게 에러 메시지로 피드백됨
print(f"[BLOCKED] 위험한 명령이 감지되었습니다: {pattern}", file=sys.stderr)
sys.exit(2) # exit 2 = 차단 신호
# 문제없으면 허용
sys.exit(0)
훅은 CLAUDE.md의 지시사항과 settings.json의 권한 정책을 보완합니다. 세 가지 계층이 함께 작동할 때 Claude Code 환경의 안전성과 일관성이 극대화됩니다.
13. Plugin 시스템 | 서브폴더 기능을 한 번에 묶는 확장 패키지
지금까지 commands/, skills/, agents/, rules/, Hooks까지 .claude 폴더의 모든 구성요소를 배웠습니다. 그런데 이 모든 것을 새 팀원에게 설명하고 설치하게 하려면 어떻게 해야 할까요? 수십 개의 파일을 하나씩 복사하고, MCP 서버를 각자 설정하고, 훅 스크립트 위치를 맞춰야 합니다. Plugin은 이 모든 것을 하나의 설치 명령으로 해결합니다. 플러그인은 commands/, skills/, agents/, hooks/, 그리고 MCP 서버 설정까지 하나의 패키지로 묶어 팀 전체가 단일 명령으로 동일한 환경을 구축할 수 있게 합니다.
플러그인 시스템은 2025년 10월 9일에 공식 출시되었으며, 이후 Claude Code 생태계의 핵심 확장 메커니즘으로 자리잡았습니다. 플러그인의 핵심 개념은 분산된 커스터마이징을 패키징하는 것입니다. 개발자가 각자 만든 슬래시 명령어, 에이전트, 스킬을 하나의 저장소에 묶고, 팀원이나 커뮤니티와 공유할 수 있습니다.
플러그인 구조 | plugin.json 매니페스트
플러그인의 핵심은 .claude-plugin/plugin.json 매니페스트 파일입니다. 이 파일을 중심으로 commands/, agents/, skills/ 폴더와 MCP 서버 설정인 .mcp.json을 하나의 패키지로 묶습니다. 플러그인 저장소의 디렉토리 구조는 다음과 같습니다.
my-plugin/
├── .claude-plugin/
│ └── plugin.json # 플러그인 매니페스트 (필수)
├── .mcp.json # MCP 서버 설정 (선택)
├── commands/ # 슬래시 명령어 묶음 (선택)
│ └── quality-review.md
├── agents/ # 서브에이전트 묶음 (선택)
│ └── code-reviewer.md
├── skills/ # 자동 호출 스킬 묶음 (선택)
│ └── security-review/
│ └── SKILL.md
└── README.md # 플러그인 설명 문서
plugin.json 매니페스트 파일의 기본 형태는 다음과 같습니다.
{
"name": "my-team-plugin",
"version": "1.0.0",
"description": "팀 전체 워크플로우 자동화 플러그인",
"author": {
"name": "Dev Team",
"email": "dev@company.com"
},
"components": {
"commands": ["commands/"],
"agents": ["agents/"],
"skills": ["skills/"]
}
}
MCP 서버가 포함된 경우, 플러그인 설치 시 MCP 서버도 자동으로 시작됩니다. 플러그인이 활성화되면 그 안에 정의된 MCP 서버가 자동으로 시작되며, 플러그인 MCP 도구는 수동으로 설정한 MCP 도구들과 나란히 표시됩니다.
// .mcp.json — 플러그인에 번들된 MCP 서버 설정
{
"mcpServers": {
"database-tools": {
"command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
"env": {
"DB_URL": "${DB_URL}"
}
}
}
}
마켓플레이스 | 플러그인 검색과 설치
플러그인 마켓플레이스는 GitHub 등의 저장소에 호스팅된 marketplace.json 카탈로그 파일로 구성됩니다. 사용자는 /plugin marketplace add 명령으로 마켓플레이스를 등록하고, 개별 플러그인을 설치할 수 있습니다.
# 마켓플레이스 등록
/plugin marketplace add anthropics/claude-plugins-official
# 또는 커뮤니티 마켓플레이스 등록
/plugin marketplace add jeremylongshore/claude-code-plugins-plus-skills
# 플러그인 검색 및 설치
/plugin install feature-dev@claude-plugins-official
/plugin install pr-review@claude-plugins-official
# 마켓플레이스 업데이트
/plugin marketplace update
Anthropic 공식 플러그인 주요 목록
Anthropic은 Claude Code 공식 저장소에 여러 번들 플러그인을 제공합니다. Agent SDK 개발 도구, PR 리뷰 툴킷, 커밋 워크플로우 등이 포함되어 있습니다. 각 서브폴더의 기능을 가장 잘 대표하는 플러그인과 그 구성을 살펴보겠습니다.
| 플러그인 | 핵심 | 컴포넌트 설명 |
| feature-dev | skills/ 중심 | 7단계 체계적 기능 개발 워크플로우. 요구사항 수집 → 아키텍처 → 구현 → 테스트 → 리뷰 전 과정 자동화 |
| pr-review | agents/ 중심 | 다중 전문 에이전트(댓글, 테스트, 에러 처리, 타입, 품질, 단순화)가 신뢰도 점수를 매겨 허위 긍정을 필터링 |
| frontend-design | skills/ 중심 | 제네릭한 AI 스타일을 탈피한 프로덕션급 UI 생성. 디자인 철학 기반의 고품질 컴포넌트 제작 |
| agent-sdk-dev | commands/ + agents/ | Agent SDK 신규 프로젝트 설정 명령어 및 Python/TypeScript 검증 에이전트 포함 |
| hook-creator | commands/ + skills/ | 대화 패턴 분석을 통해 원치 않는 동작을 방지하는 커스텀 훅 생성 자동화 |
commands/ 기능 대표 플러그인 | feature-dev
feature-dev 플러그인은 89,000개 이상의 설치 수를 기록한 Claude Code에서 가장 인기 있는 플러그인입니다. /feature-dev를 실행하면 Claude는 단순히 코드를 작성하는 것을 넘어, 요구사항 수집, 코드베이스 탐색, 아키텍처 설계, 구현, 테스트, 리뷰, 문서화의 7단계 워크플로우를 순차적으로 진행합니다.
# feature-dev 플러그인 설치 후 사용
/feature-dev "사용자 인증 모듈에 소셜 로그인(Google OAuth) 추가"
# Claude가 자동으로 다음을 수행합니다:
# 1. 요구사항 명확화 질문
# 2. 기존 코드베이스 아키텍처 탐색 (병렬 에이전트)
# 3. 구현 설계안 제안 및 승인 요청
# 4. 단계적 구현 진행
# 5. 테스트 코드 자동 작성
# 6. 코드 리뷰 수행
# 7. 변경 내용 문서화
skills/ 기능 대표 플러그인 | Context7 MCP
skills/ 폴더가 내부 워크플로우를 자동화한다면, MCP 서버는 외부 지식과 서비스를 연결합니다. Context7은 Upstash가 만든 오픈소스 MCP 서버로, 버전별 최신 라이브러리 문서를 Claude Code 세션에 직접 주입합니다. "use context7"을 프롬프트에 추가하면 Claude는 훈련 데이터에 의존하지 않고 해당 라이브러리의 실제 최신 문서를 참조하여 코드를 생성합니다.
# Context7 MCP 서버 추가
claude mcp add --transport http context7 https://mcp.context7.com/mcp
# 사용 예시 — "use context7"을 붙이면 최신 문서 참조 보장
"Next.js 15의 Server Components 패턴으로 데이터 페칭 구현해줘 — use context7"
"Prisma ORM의 최신 트랜잭션 API 사용법 알려줘 — use context7"
agents/ 기능 대표 플러그인 | pr-review
agents/ 폴더의 서브에이전트 개념을 가장 잘 구현한 플러그인이 pr-review입니다. GitHub MCP 서버와 결합하면 Claude는 PR 차이를 분석하고, 코드 리뷰를 제안하고, 이슈에서 버그 리포트를 생성하며, GitHub Actions 워크플로우까지 모니터링할 수 있습니다. pr-review 플러그인은 이 위에 여러 전문 에이전트를 병렬로 실행합니다.
# pr-review 플러그인 설치
/plugin install pr-review@claude-plugins-official
# PR 리뷰 실행 — 복수의 전문 에이전트가 병렬 분석
/pr-review
# 다음 전문 에이전트들이 동시에 분석합니다:
# - comments-agent: 인라인 코드 코멘트 품질 검토
# - tests-agent: 테스트 커버리지 및 케이스 완전성
# - error-handling-agent: 에러 처리 누락 탐지
# - type-design-agent: TypeScript 타입 설계 검토
# - simplification-agent: 코드 복잡도 개선 제안
# 각 에이전트가 신뢰도 점수를 부여하여 허위 긍정 필터링
팀 내부 플러그인 마켓플레이스 구축
대규모 팀이나 기업 환경에서는 내부 플러그인 마켓플레이스를 직접 구축할 수 있습니다. Git 저장소에 marketplace.json을 만들고 팀원들이 등록하면 됩니다. 이를 통해 팀의 모든 커스터마이징을 표준화하고, 새 팀원 온보딩을 단 두 줄로 완료할 수 있습니다.
// .claude-plugin/marketplace.json — 사내 마켓플레이스 카탈로그
{
"name": "acme-internal",
"owner": {
"name": "Acme Platform Team",
"email": "platform@acme.com"
},
"plugins": [
{
"name": "acme-dev-toolkit",
"source": {
"source": "github",
"repo": "acme-corp/claude-dev-toolkit"
},
"version": "2.1.0",
"description": "Acme 개발 표준: 코드 리뷰, 배포, DB 마이그레이션 자동화",
"category": "internal"
},
{
"name": "acme-security-suite",
"source": {
"source": "github",
"repo": "acme-corp/claude-security-suite"
},
"version": "1.3.0",
"description": "보안 감사, SAST 스캔, 비밀정보 노출 탐지",
"category": "security"
}
]
}
# 새 팀원 온보딩 — 단 두 명령으로 완료
/plugin marketplace add acme-corp/claude-dev-marketplace
/plugin install acme-dev-toolkit@acme-internal
이처럼 플러그인 시스템은 .claude 폴더의 모든 서브폴더 기능(commands/, skills/, agents/, hooks, MCP)을 하나의 설치 단위로 묶어, 팀 전체의 Claude Code 환경을 코드로 관리(Configuration as Code)할 수 있게 합니다. 스택이 성숙해질수록 플러그인은 팀의 개발 표준을 자동화하는 가장 효과적인 수단이 됩니다.
11. .claude 폴더를 인프라처럼 관리하세요
.claude 폴더의 본질을 한 마디로 요약하면, "Claude에게 우리가 누구이고, 프로젝트가 무엇이며, 어떤 규칙을 따라야 하는지 알려주는 프로토콜"입니다. 이 프로토콜이 명확하게 정의될수록, Claude를 수정하는 시간은 줄어들고 실제 생산적인 작업에 쓰는 시간은 늘어납니다. 마치 새로운 팀원에게 온보딩 문서를 잘 준비해두면 교육 시간이 단축되는 것과 같은 이치입니다.
.claude 폴더를 처음부터 완벽하게 만들려고 할 필요는 없습니다. CLAUDE.md부터 시작하여 팀이 성장하고 프로젝트가 복잡해질수록 점진적으로 구성요소를 추가하는 것이 현명한 접근 방식입니다. 가장 중요한 것은 이 폴더를 코드베이스의 일부로 생각하고, 프로젝트 인프라처럼 지속적으로 유지보수하는 습관을 갖는 것입니다. 잘 관리된 .claude 폴더는 매일 개발 생산성에 복리로 쌓이는 투자입니다.
참고 자료
- Claude Code 공식 문서
- Claude Code Hooks 레퍼런스
- Claude Code MCP 연결 가이드
- Claude Code 플러그인 마켓플레이스 공식 저장소
- Claude Code settings.json 스키마
- Anatomy of the .claude/ Folder - Daily Dose of Data Science
FAQ
Q. .claude 폴더 없이도 Claude Code를 사용할 수 있나요?
네, 가능합니다. 하지만 프로젝트 규칙을 모르는 상태로 작업하기 때문에 Claude에게 반복적으로 설명해야 하는 비효율이 발생합니다. 작은 프로젝트라도 최소한 CLAUDE.md 하나만 만들어도 큰 차이가 납니다.
Q. CLAUDE.md를 너무 자세하게 쓰면 안 되나요?
200줄을 초과하면 컨텍스트 창을 과도하게 차지하여 Claude의 지시사항 준수율이 낮아집니다. 200줄 이상이 필요하다면 rules/ 폴더로 분리하세요.
Q. Skills와 Commands의 차이를 한 줄로 요약하면?
Commands는 내가 호출하고, Skills는 Claude가 알아서 호출합니다.
Q. settings.json의 deny 목록에 없으면 실행 가능한가요? deny 목록에도 없고 allow 목록에도 없는 명령은 실행 전 Claude가 사용자에게 확인을 요청합니다. 완전한 차단은 deny 목록에만 있습니다.
'AI 코딩' 카테고리의 다른 글
| Pi Coding Agent 가이드 (0) | 2026.03.31 |
|---|---|
| cmux - AI 코딩 에이전트 시대의 새로운 터미널 (0) | 2026.03.22 |
| vLLM 완벽 가이드 - 대규모 언어 모델 서빙의 새로운 표준 (0) | 2026.03.19 |
| Scrapling 설치부터 쿠팡 스크래핑까지 (0) | 2026.03.14 |
| Tailscale 완벽 가이드 (2편) - 설치부터 Zero Trust 네트워크 구축 (0) | 2026.02.07 |
