통합아키텍처 : 전체 구성 요소 조합
목차
CLAUDE.md, 스킬, MCP, Hooks... 이것들을 어떻게 조합해야 할까요?
개별 기능을 아는 것과 전체를 설계하는 것은 다릅니다.
이 글에서는 Claude Code의 구성 요소들을 통합하는 아키텍처를 알아봅니다.
구성 요소 정리
CLAUDE.md, 스킬, settings.json... 다 비슷해 보이는데 어떤 걸 써야 하는지 헷갈려요.
회사로 비유하면 이해하기 쉬워!
CLAUDE.md = 회사 규정 (항상 적용)
스킬 = 업무 매뉴얼 (필요할 때 참조)
settings.json = 시스템 설정 (백그라운드)
MCP = 외부 협력사 연결
| 구성 요소 | 역할 | 적용 시점 |
|---|---|---|
| CLAUDE.md | 기본 지침, 프로젝트 규칙 | 항상 로드 |
| 스킬 (SKILL.md) | 특정 작업 수행 가이드 | 키워드/명령으로 활성화 |
| settings.json | 권한, 동작, MCP 설정 | 백그라운드 적용 |
| Hooks | 이벤트 기반 자동화 | 이벤트 발생 시 |
| MCP 서버 | 외부 도구/서비스 연결 | 연결된 서버 도구 사용 시 |
권장 폴더 구조
프로젝트 레벨 (.claude/ 폴더)
my-project/
├── .claude/
│ ├── settings.json # 프로젝트 설정
│ └── skills/
│ ├── code-reviewer/
│ │ ├── SKILL.md
│ │ └── knowledge/
│ │ ├── typescript.md
│ │ └── react.md
│ └── deploy-helper/
│ └── SKILL.md
└── CLAUDE.md # 프로젝트 기본 지침전역 레벨 (~/.claude/ 폴더)
~/.claude/
├── settings.json # 전역 설정
├── CLAUDE.md # 전역 지침
└── skills/
├── blog-writer/
│ └── SKILL.md
└── daily-briefing/
└── SKILL.md설계 원칙
CLAUDE.md에 넣을지 스킬로 만들지 어떻게 결정해요?
세 가지 질문을 해봐!
① 항상 필요? → CLAUDE.md
② 특정 작업용? → 스킬
③ 이벤트 기반? → Hooks
CLAUDE.md에 넣을 것
- 코딩 컨벤션 (들여쓰기, 네이밍)
- 프로젝트 구조 설명
- 금지 사항 (특정 라이브러리 사용 금지 등)
스킬로 만들 것
- 블로그 작성, 코드 리뷰 등 특정 작업
- 복잡한 워크플로우
- 반복 사용하는 패턴
통합 예제
실제 프로젝트에서 어떻게 조합하는지 살펴봅시다.
시나리오: 개발 팀 프로젝트
💡 CLAUDE.md - 기본 규칙
# 프로젝트 가이드 ## 코딩 컨벤션 - TypeScript strict 모드 사용 - 함수명은 camelCase - 컴포넌트는 PascalCase ## 금지 사항 - console.log 프로덕션 코드에 금지 - any 타입 사용 금지 ## 브랜치 전략 - feature/* : 기능 개발 - fix/* : 버그 수정
💡 스킬 - 코드 리뷰 (code-reviewer/SKILL.md)
--- name: code-reviewer description: PR 코드 리뷰 수행 keywords: ["코드 리뷰", "PR 리뷰"] --- # 코드 리뷰 스킬 ## 검토 항목 1. CLAUDE.md의 컨벤션 준수 여부 2. 보안 취약점 (OWASP Top 10) 3. 성능 이슈 ## 출력 형식 - 심각도: 🔴 High / 🟡 Medium / 🟢 Low - 위치: 파일:라인 - 설명: 문제점 및 수정 제안
💡 settings.json - 권한 및 MCP
{
"permissions": {
"allowedCommands": ["npm run", "git status"]
},
"hooks": {
"PostToolUse": [{
"matcher": "Edit",
"command": "npm run lint --fix"
}]
},
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"]
}
}
}
베스트 프랙티스
💡 통합 설계 체크리스트
- CLAUDE.md는 간결하게 - 500줄 이내 권장
- 스킬은 단일 목적 - 하나의 스킬 = 하나의 역할
- settings.json은 공유 주의 - API 키 노출 금지
- Hooks는 빠른 명령만 - 느린 명령은 작업 지연 유발
- MCP는 필요한 것만 - 연결 많으면 복잡도 증가
처음부터 완벽하게 설계하지 마세요! 필요할 때마다 하나씩 추가하면서 자연스럽게 성장시키는 게 좋습니다.
CLAUDE.md = 항상 적용되는 기본 규칙
스킬 = 특정 작업 전문 가이드
settings.json = 권한, Hooks, MCP 설정
설계 원칙 = 단순하게 시작, 필요시 확장
👉 보안과 운영 : 안전하고 효율적인 스킬 관리법
구성 요소를 조합해 나만의 AI 시스템을 만드세요!
부품을 알면 전체를 설계할 수 있습니다! 🏗️
댓글
댓글 쓰기