# Claude Code 프로젝트 설정 가이드

> **카테고리:** 패턴 & 레시피
> **최종 수정:** 2026-05-13
> **관련:** [[claude-code-overview]], [[claude-code-hooks]], [[claude-code-workflow-patterns]]

## 요약

Claude Code의 5개 핵심 컴포넌트(MCP, CLAUDE.md, Skills, Subagents, Hooks)를 어떻게 조합할지 알아야 진짜 자동화 시스템을 만들 수 있다.

---

## 컴포넌트 선택 가이드

| 컴포넌트 | 사용 시점 |
|---|---|
| **CLAUDE.md** | 영속이 필요한 정적 지식 (코딩 표준, 아키텍처 결정) |
| **Skills** | 재사용 가능한 워크플로우 (자동 또는 수동 트리거) |
| **Subagents** | 병렬 실행, 컨텍스트 격리가 필요할 때 |
| **Hooks** | 표준 강제, 이벤트 자동 반응 (매번 예외 없이 실행) |
| **MCP** | 외부 시스템 연동 (GitHub, Figma, DB 등) |
| **Scheduled Tasks** | 사용자 없는 반복 작업 (cron) |

---

## CLAUDE.md

`/init` 명령으로 현재 프로젝트 기반 초안 자동 생성.

### 포함할 것 vs 제외할 것

| ✅ 포함 | ❌ 제외 |
|---|---|
| Claude가 추측할 수 없는 bash 명령 | 코드 읽으면 알 수 있는 것 |
| 기본값과 다른 코드 스타일 규칙 | 자주 바뀌는 정보 |
| 테스트 실행 방법 | 긴 설명이나 튜토리얼 |
| 레포 규칙 (브랜치 네이밍, PR 컨벤션) | "clean code 작성해" 같은 당연한 것 |
| 프로젝트 아키텍처 결정 사항 | 파일별 코드베이스 설명 |
| 흔한 gotcha / 비직관적 동작 | API 문서 전체 (링크로 대신) |

> ⚠️ 주의: CLAUDE.md가 너무 길면 Claude가 규칙을 무시한다. 매 줄마다 "이걸 제거해도 Claude가 실수할까?"를 자문하라. 그렇지 않으면 삭제하거나 Hook으로 이전하라.

### 파일 위치와 계층 구조

```
Enterprise → User → Project  (계층적으로 병합)
```

| 위치 | 용도 |
|---|---|
| `~/.claude/CLAUDE.md` | 전역 — 모든 세션에 적용 |
| `./CLAUDE.md` | 프로젝트 루트 — git 공유 |
| `./CLAUDE.local.md` | 개인 설정 — .gitignore 추가 |
| `./src/CLAUDE.md` | 하위 폴더 — 해당 폴더 작업 시 자동 로드 |

### Import 문법

```markdown
See @README.md for project overview.
# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md
```

---

## Skills

`.claude/skills/` 에 `SKILL.md` 파일로 정의. CLAUDE.md의 모듈화 버전.

### Frontmatter 옵션

```markdown
---
name: fix-issue
description: GitHub 이슈 수정 워크플로우
disable-model-invocation: true   # 수동 전용 (사이드 이펙트 있을 때)
context: fork                    # 독립 subagent로 실행
---
```

- `auto-invoke`: Claude가 컨텍스트 기반으로 자동 적용
- `/fix-issue 1234` 처럼 수동 트리거도 가능

### 예시: GitHub 이슈 수정 워크플로우

```markdown
# .claude/skills/fix-issue/SKILL.md
---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Fix GitHub issue: $ARGUMENTS.
1. gh issue view로 상세 확인
2. 문제 파악 및 관련 파일 탐색
3. 수정 구현
4. 테스트 작성 및 실행
5. 린트·타입 체크
6. 설명적 커밋 메시지 작성
7. PR 생성
```

---

## Subagents

`.claude/agents/`에 정의. 독립 컨텍스트 윈도우 + 특화된 도구 세트.

- **컨텍스트 오염 방지**: 무거운 탐색·분석 작업 격리
- **Worktree isolation** (2026): 여러 subagent가 파일을 병렬 편집 가능
- 내장 타입: `Explore`, `Plan`, `General-purpose`

### 예시: 보안 리뷰어

```markdown
# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
Senior security engineer로서 다음을 검토:
- Injection 취약점 (SQL, XSS, command injection)
- 인증·인가 결함
- 코드 내 시크릿·자격증명
- 불안전한 데이터 처리

구체적인 라인 참조와 수정 제안을 제공하라.
```

---

## MCP (Model Context Protocol)

외부 도구·데이터 소스를 연결하는 범용 어댑터.

```bash
claude mcp add  # MCP 서버 연결
```

- `/` slash 명령으로 MCP 서버 기능 접근
- HTTP transport + OAuth 2.1 with PKCE 지원
- ⚠️ MCP 서버는 명시적으로 제공하지 않으면 Claude의 native 도구를 상속하지 않는다

---

## 통합 실전 워크플로우 예시

```
1. CLAUDE.md          → 팀 코딩 표준 수립
2. load-context skill → 새 채팅 시작 시 프로젝트 컨텍스트 자동 로드
3. documentation skill (auto-invoke) → 구현 후 자동 문서 업데이트
4. hooks              → 린팅·타입 체크 강제
5. subagents          → 조사·검증 작업 격리
```

---

## 참고 / 출처

- `raw/claude-code-best-practices-official.md` (code.claude.com 공식 문서)
- `raw/claude-code-full-stack-mcp-skills-subagents-hooks.md` (alexop.dev)