gil
5f664546cf
- CLAUDE.md 운영 규칙 - wiki/ 정리된 지식 페이지 (Nuxt + Claude Code) - raw/ 원본 자료 - reference/ Nuxt 4.x 공식 문서 Co-authored-by: Cursor <cursoragent@cursor.com>
165 lines
4.9 KiB
Markdown
165 lines
4.9 KiB
Markdown
# 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)
|