CLAUDE.md 작성법부터 플러그인/MCP/스킬 관리, 크로스 환경 동기화까지 — 한국어로 정리된 실전 가이드
Claude Code를 효과적으로 사용하기 위한 종합 설정 가이드입니다.
웹에서 한눈에 보기 (추천)
전체 내용을 한 페이지에서 보고 싶다면 웹 가이드를 이용하세요.
GitHub에서 섹션별로 보기
필요한 부분만 골라 읽고 싶다면 아래 목차에서 선택하세요. 웹 가이드와 동일한 내용이 섹션별 마크다운 파일(
docs/)로 분리되어 있습니다.
Claude Code가 처음이라면 이 순서로 읽어보세요:
- CLAUDE.md 계층 구조 — 설정 파일이 어디에 있고 어떻게 작동하는지
- CLAUDE.md 작성 가이드 — 60줄 안에 효과적으로 작성하는 법
- 7가지 안티패턴 — 흔한 실수 피하기
- 실전 예시 — 복사해서 바로 쓸 수 있는 템플릿
이미 사용 중이라면 → 비용 최적화, Hooks 자동화, 커뮤니티 팁
| # | 주제 | 핵심 내용 |
|---|---|---|
| 01 | 계층 구조 | Global → Project → Local → Rules 우선순위 |
| 02 | 작성 가이드 | WHY-WHAT-HOW, 60~80줄 제한, 주의 예산 |
| 03 | 포함/제외 | Progressive Disclosure, 토큰 효율성 |
| 04 | 안티패턴 | 과적재, Kitchen Sink, 반복 수정 등 7가지 |
| 05 | 실전 예시 | 글로벌/프로젝트 CLAUDE.md 전체 예시 |
여기서부터는 Claude Code에 좀 익숙해진 후 읽어도 됩니다. 위의 기본기(01~05)만으로도 충분합니다.
| # | 주제 | 핵심 내용 |
|---|---|---|
| 06 | 모듈화 | .claude/rules/, 경로 기반 조건부 적용 |
| 07 | settings.json | 5단계 우선순위, 권한 체인 |
| 08 | MCP 서버 | 필수 Top 5, .mcp.json 설정 |
| 09 | 스킬 관리 | 3-Tier 로딩, SKILL.md 구조 |
| 10 | Hooks | 6개 이벤트, 자동 포맷팅/보호 |
| # | 주제 | 핵심 내용 |
|---|---|---|
| 11 | Dotfiles | GNU Stow, 동기화 도구 |
| 12 | 비용 최적화 | 모델 분담, 캐싱, 70% 절감 |
| 13 | 커뮤니티 | Boris Cherny, YK Dojo, 엔터프라이즈 |
| 14 | 리소스 | 공식 문서, GitHub 레포, 한국어 자료 |
| 15 | FAQ & 트러블슈팅 | 자주 묻는 질문, 문제 해결 |
Claude Code가 설치되어 있어야 합니다. 처음 실행하면 ~/.claude/ 디렉토리가 자동 생성됩니다.
# Claude Code 설치 확인
claude --version
# ~/.claude/ 디렉토리가 없다면 Claude Code를 한 번 실행
claude설치 방법은 공식 문서를 참고하세요.
examples/global-claude.md를 ~/.claude/CLAUDE.md에 복사하고 커스터마이즈:
cp examples/global-claude.md ~/.claude/CLAUDE.mdexamples/project-claude.md를 프로젝트 루트에 복사:
cp examples/project-claude.md ./CLAUDE.mdexamples/rules/의 파일들을 프로젝트에 복사:
mkdir -p .claude/rules
cp examples/rules/*.md .claude/rules/예시 파일 설명은
examples/README.md를 참고하세요.
Claude Code를 실행하여 설정이 반영되었는지 확인합니다:
claude
# 세션에서 "CLAUDE.md 내용을 요약해줘"라고 입력하여 확인| 항목 | 수치 | 출처 |
|---|---|---|
| CLAUDE.md 이상적 길이 | 60줄 이하 | HumanLayer 벤치마크 |
| 안정적 명령어 수 | 150~200개 | 커뮤니티 테스트 |
| 비용 절감 가능 | 50~90% | 모델 분담 + 프롬프트 캐싱 조합 |
| 프롬프트 캐싱 절감 | 90% | Anthropic 공식 |
| 엔터프라이즈 가속 | 2~10x | Altana 등 공식 사례 |
claude-code-guide-kr/
├── README.md # 이 문서
├── CLAUDE.md # Claude Code 프로젝트 지침
├── index.html # GitHub Pages 진입점 (= guide.html)
├── guide.html # 풀 HTML 가이드 (다크 테마)
│
├── docs/ # 섹션별 분리 문서 (01~15)
│ ├── AGENTS.md # docs 에이전트 가이드
│ └── 01-hierarchy.md ~ 15-faq.md
├── examples/ # 바로 사용 가능한 설정 예시
│ ├── AGENTS.md # examples 에이전트 가이드
│ ├── README.md # 예시 파일 안내
│ ├── global-claude.md # 글로벌 CLAUDE.md 템플릿
│ ├── project-claude.md # 프로젝트 CLAUDE.md 템플릿
│ ├── settings.json # settings.json 예시
│ ├── mcp.json # MCP 서버 설정 예시
│ ├── hooks.json # Hooks 설정 (참고용, settings.json hooks 섹션)
│ └── rules/ # .claude/rules/ 예시
│
├── CONTRIBUTING.md # 기여 가이드
└── LICENSE # MIT License
이 가이드를 더 좋게 만들어주세요! CONTRIBUTING.md를 참고하세요.
- 새로운 팁이나 사례 추가
- 오류 수정 및 최신 정보 업데이트
- 예시 파일 개선
- 번역 (영문 버전)
이 가이드는 아래 리소스들을 참고하여 작성되었습니다:
전체 참고 리소스 목록: docs/14-resources.md
MIT — 자유롭게 사용, 수정, 배포하세요.