Part 1: Architecture Reference

1.4 시작 가이드

Claude Code의 다양한 확장 기능을 어떤 순서로 학습하고 도입해야 할지, 그리고 기능들을 어떻게 조합하면 효과적인지 정리합니다.

시작 권장 순서

💡 점진적 도입 원칙

모든 기능을 한꺼번에 도입하려 하지 마세요. 아래 우선순위에 따라 하나씩 익히면서 점진적으로 확장하는 것이 효과적입니다. 각 단계를 충분히 이해한 후 다음 단계로 넘어가세요.

우선순위	기능	언제	예시
1	CLAUDE.md	프로젝트 시작 시 즉시	프로젝트 규칙, 코딩 스타일, 아키텍처 가이드 등을 정의. 모든 대화에 자동 로드됨.
2	Skills	반복 작업이 생길 때	특정 도메인 지식이 반복 필요할 때 `.claude/skills/`에 스킬 파일 작성. 예: React 컴포넌트 생성 규칙, API 설계 패턴.
3	MCP	외부 서비스 연동이 필요할 때	GitHub Issues 조회, Slack 메시지 전송, DB 쿼리 실행 등 외부 서비스와 연결이 필요할 때 MCP 서버 등록.
4	Hooks	자동화 패턴이 보일 때	커밋 전 자동 린트, 파일 저장 시 테스트 실행, 세션 시작 시 환경 체크 등 반복적인 자동화가 필요할 때.
5	Sub-agents	작업이 병렬 처리 가능할 때	여러 파일을 동시에 리팩토링, 테스트와 코드를 병렬로 작성, 독립적인 마이크로서비스 동시 개발 등.
6	Plugins	팀에 공유할 설정이 생길 때	여러 Skills + MCP + Commands를 하나의 패키지로 묶어 팀원들에게 배포. 예: 프로젝트 전용 개발 환경 플러그인.
7	Agent Teams	대규모 프로젝트를 분할할 때	마이크로서비스 아키텍처 전체 구축, 대형 리팩토링 프로젝트, 다중 모듈 동시 개발 등 대규모 작업을 여러 에이전트가 협업.

기능: CLAUDE.md

언제: 프로젝트 시작 시 즉시

예시: 프로젝트 규칙, 코딩 스타일, 아키텍처 가이드 등을 정의. 모든 대화에 자동 로드됨.

기능: Skills

언제: 반복 작업이 생길 때

예시: 특정 도메인 지식이 반복 필요할 때 .claude/skills/에 스킬 파일 작성. 예: React 컴포넌트 생성 규칙, API 설계 패턴.

기능: MCP

언제: 외부 서비스 연동이 필요할 때

예시: GitHub Issues 조회, Slack 메시지 전송, DB 쿼리 실행 등 외부 서비스와 연결이 필요할 때 MCP 서버 등록.

기능: Hooks

언제: 자동화 패턴이 보일 때

예시: 커밋 전 자동 린트, 파일 저장 시 테스트 실행, 세션 시작 시 환경 체크 등 반복적인 자동화가 필요할 때.

기능: Sub-agents

언제: 작업이 병렬 처리 가능할 때

예시: 여러 파일을 동시에 리팩토링, 테스트와 코드를 병렬로 작성, 독립적인 마이크로서비스 동시 개발 등.

기능: Plugins

언제: 팀에 공유할 설정이 생길 때

예시: 여러 Skills + MCP + Commands를 하나의 패키지로 묶어 팀원들에게 배포. 예: 프로젝트 전용 개발 환경 플러그인.

기능: Agent Teams

언제: 대규모 프로젝트를 분할할 때

예시: 마이크로서비스 아키텍처 전체 구축, 대형 리팩토링 프로젝트, 다중 모듈 동시 개발 등 대규모 작업을 여러 에이전트가 협업.

기능 조합 패턴

개별 기능을 이해했다면, 다음은 이들을 조합하여 더 강력한 워크플로우를 만드는 것입니다. 아래는 자주 사용되는 기능 조합 패턴입니다.

패턴	작동 방식	예시
CLAUDE.md + Skills	CLAUDE.md에서 프로젝트 전체 규칙을 정의하고, Skills에서 세부 도메인 지식을 보충. CLAUDE.md는 항상 로드되고, Skills는 필요할 때만 로드됨.	CLAUDE.md: "TypeScript strict 모드 사용, ESLint 규칙 준수" Skill: "React 컴포넌트 생성 시 Storybook 스토리도 함께 생성"
Skill + MCP	Skill이 작업 방법(How)을 정의하고, MCP가 외부 도구(What)를 제공. Skill의 지식과 MCP의 도구가 결합되어 전문적인 작업 수행.	Skill: "Jira 이슈 기반 브랜치 생성 규칙" MCP: "Jira API 연결로 이슈 정보 조회"
Skill + Sub-agent	Skill이 작업 분할 기준을 정의하고, Sub-agent가 각 부분을 병렬 실행. 메인 에이전트가 Skill 기반으로 작업을 분할하여 Sub-agent에 위임.	Skill: "마이크로서비스 생성 패턴 (API Gateway + Service + DB)" Sub-agents: "각 서비스를 독립적으로 생성"
Hook + MCP	Hook이 이벤트를 감지하고, MCP를 통해 외부 서비스에 알림/작업을 트리거. 자동화된 워크플로우를 구축.	Hook: "커밋 완료 시 트리거" MCP: "Slack에 커밋 메시지 자동 전송" 또는 "GitHub PR 자동 생성"

CLAUDE.md + Skills

작동 방식: CLAUDE.md에서 프로젝트 전체 규칙을 정의하고, Skills에서 세부 도메인 지식을 보충. CLAUDE.md는 항상 로드되고, Skills는 필요할 때만 로드됨.

예시: CLAUDE.md: "TypeScript strict 모드 사용, ESLint 규칙 준수"
Skill: "React 컴포넌트 생성 시 Storybook 스토리도 함께 생성"

Skill + MCP

작동 방식: Skill이 작업 방법(How)을 정의하고, MCP가 외부 도구(What)를 제공. Skill의 지식과 MCP의 도구가 결합되어 전문적인 작업 수행.

예시: Skill: "Jira 이슈 기반 브랜치 생성 규칙"
MCP: "Jira API 연결로 이슈 정보 조회"

Skill + Sub-agent

작동 방식: Skill이 작업 분할 기준을 정의하고, Sub-agent가 각 부분을 병렬 실행. 메인 에이전트가 Skill 기반으로 작업을 분할하여 Sub-agent에 위임.

예시: Skill: "마이크로서비스 생성 패턴 (API Gateway + Service + DB)"
Sub-agents: "각 서비스를 독립적으로 생성"

Hook + MCP

작동 방식: Hook이 이벤트를 감지하고, MCP를 통해 외부 서비스에 알림/작업을 트리거. 자동화된 워크플로우를 구축.

예시: Hook: "커밋 완료 시 트리거"
MCP: "Slack에 커밋 메시지 자동 전송" 또는 "GitHub PR 자동 생성"

ℹ️ 조합의 핵심 원칙

기능 조합 시 가장 중요한 원칙은 "각 기능이 자신의 역할만 수행하도록" 하는 것입니다.

CLAUDE.md — 전체 프로젝트 규칙 (What to follow)
Skills — 도메인 전문 지식 (How to do)
MCP — 외부 도구 연결 (What tools to use)
Hooks — 자동화 트리거 (When to act)
Sub-agents / Agent Teams — 작업 분산 (Who does what)
Plugins — 패키징/배포 (How to share)

⚠️ 주의사항

처음부터 모든 기능을 조합하려 하지 마세요. CLAUDE.md부터 시작하여 점진적으로 확장하는 것이 가장 효과적입니다. 각 기능을 개별적으로 충분히 이해한 후에 조합을 시도하세요.