Files

- CLAUDE.md 운영 규칙
- wiki/ 정리된 지식 페이지 (Nuxt + Claude Code)
- raw/ 원본 자료
- reference/ Nuxt 4.x 공식 문서

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-05-13 00:31:51 +09:00

4.9 KiB

Raw Permalink Blame History

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 문법

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 옵션

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

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

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

# .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

예시: 보안 리뷰어

# .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)

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

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)

4.9 KiB Raw Permalink Blame History