wesammustafa/Claude-Code-Everything-You-Need-to-Know는 Claude Code 입문부터 프롬프트 엔지니어링, Skills, Hooks, MCP, 서브에이전트, 팀 워크플로까지 한 번에 훑는 커뮤니티 가이드다. 기존 문서가 기능별로 흩어져 있다면, 이 저장소의 가치는 “무엇을 언제 써야 하는가”를 빠르게 판단하게 해주는 비교표와 예시 흐름에 있다.
네 가지 확장 지점
Claude Code의 생산성은 모델 자체보다 프로젝트에 어떤 확장 지점을 붙였는지에 크게 좌우된다.
| 확장 지점 | 쓰기 좋은 상황 | 피해야 할 상황 | 위치 |
|---|---|---|---|
| Skills / Slash Commands | 같은 프롬프트·절차를 3번 이상 반복한다 | 일회성 질문이나 탐색 | .claude/commands/*.md, .claude/skills/*/SKILL.md |
| Hooks | 도구 호출, 파일 편집, 세션 시작 시 자동 검사를 실행해야 한다 | 사람이 수동으로 눌러야 안전한 작업 | .claude/settings.json, .claude/hooks/ |
| Subagents | 큰 하위 작업을 별도 컨텍스트에서 병렬 처리해야 한다 | 메인 세션 안에서 충분히 끝나는 작은 작업 | .claude/agents/*.md |
| MCP servers | 브라우저, DB, SaaS, 내부 API 같은 외부 시스템이 필요하다 | 로컬 파일과 셸만으로 충분하다 | 클라이언트별 MCP 설정 |
이 네 가지는 대체재가 아니라 조합 가능한 부품이다. 예를 들어 /review 커맨드가 리뷰 절차를 트리거하고, 전용 reviewer 서브에이전트가 검토하며, 훅이 테스트와 포맷을 자동 실행하고, MCP가 GitHub 이슈를 읽는 식으로 연결할 수 있다.
초보자에게 적합한 시작 순서
처음부터 모든 기능을 켜면 설정만 복잡해진다. 다음 순서가 실용적이다.
- 설치와 인증:
npm install -g @anthropic-ai/claude-code후claude로 로그인한다. - 프로젝트 규칙 생성:
/init으로CLAUDE.md를 만들고, 테스트 명령·금지 경로·코딩 스타일을 적는다. - 반복 프롬프트를 커맨드화: 리뷰, 테스트, 릴리스 노트처럼 반복되는 요청을
.claude/commands/에 넣는다. - 자동화가 필요한 지점에 Hooks 추가: 포맷, 민감 파일 차단, 감사 로그처럼 명확한 규칙부터 시작한다.
- 외부 시스템이 필요할 때 MCP 추가: 브라우저, GitHub, DB, 문서 저장소처럼 로컬 파일 밖의 컨텍스트를 연결한다.
- 작업이 커질 때 서브에이전트 도입: 보안 리뷰, 프론트엔드 구현, 데이터베이스 설계를 분리한다.
Skills는 절차를 저장하는 곳이다
Skills는 단순한 “프롬프트 저장소”가 아니라 반복 가능한 작업 절차다. 좋은 스킬은 다음 요소를 포함한다.
- 언제 발동해야 하는지
- 어떤 파일과 정보를 먼저 읽어야 하는지
- 어떤 체크리스트를 통과해야 하는지
- 실패하면 어떤 순서로 디버깅해야 하는지
- 최종 출력 형식은 무엇인지
보안상 주의할 점도 있다. 스킬은 모델이 읽고 따르는 실행 지침이며, 셸 권한을 가진 에이전트에게 영향을 준다. 외부 스킬을 가져올 때는 스크립트처럼 검토해야 한다.
Hooks는 자동 실행되는 정책이다
Hooks는 강력하지만 가장 조심해야 하는 확장 지점이다. Claude Code의 라이프사이클 이벤트에 맞춰 임의 스크립트를 실행하므로 다음 용도에 적합하다.
| 용도 | 예시 |
|---|---|
| 자동 포맷 | 편집 후 prettier, ruff, gofmt 실행 |
| 민감 경로 차단 | .env, secrets/, 프로덕션 인프라 파일 변경 거부 |
| 감사 로그 | 도구 호출과 파일 변경을 별도 로그에 기록 |
| 테스트 게이트 | 특정 파일 변경 후 관련 테스트 명령 제안 또는 실행 |
반대로 배포, 결제, 메일 발송처럼 되돌리기 어려운 작업은 자동 훅보다 명시적 승인 흐름이 낫다.
Subagents는 컨텍스트 분리 도구다
서브에이전트는 “더 많은 AI”가 아니라 “컨텍스트를 분리하는 방법”으로 봐야 한다. 다음 조건을 만족할 때 효과가 크다.
- 하위 작업이 명확하고 독립적이다
- 메인 세션이 모든 세부사항을 들고 있을 필요가 없다
- 결과를 요약해 합치기 쉽다
- 파일 쓰기 범위가 충돌하지 않는다
예를 들어 보안 리뷰어, 프론트엔드 엔지니어, 데이터베이스 엔지니어를 분리하면 각 에이전트가 다른 관점으로 같은 코드베이스를 볼 수 있다. 하지만 작은 수정 하나를 여러 에이전트로 나누면 조율 비용이 더 커진다.
MCP는 외부 세계와 연결하는 레이어다
MCP(Model Context Protocol)는 Claude Code가 로컬 파일 밖의 시스템을 도구처럼 쓰게 한다. 브라우저 자동화, GitHub, 데이터베이스, 문서 저장소, 내부 API가 대표적이다.
MCP를 붙일 때는 “이 연결이 컨텍스트 품질을 높이는가”를 먼저 봐야 한다. 단순히 도구 수를 늘리면 모델의 선택지가 많아져 오히려 행동이 불안정해질 수 있다. 자주 쓰는 외부 시스템부터 좁게 연결하고, 프로젝트 규칙에 언제 어떤 MCP를 써야 하는지 적는 편이 좋다.
실무 적용 패턴
| 워크플로 | 조합 |
|---|---|
| PR 리뷰 | /review 커맨드 + reviewer 서브에이전트 + 테스트 훅 |
| 신규 기능 개발 | /plan 커맨드 + 구현 서브에이전트 + 포맷 훅 |
| 이슈 기반 작업 | GitHub MCP + CLAUDE.md 작업 규칙 + 커밋 체크리스트 |
| 대규모 리팩터링 | git worktree + 서브에이전트 + 단계별 테스트 게이트 |
| 문서 업데이트 | 스킬 + 링크 검사 훅 + 스타일 규칙 |
이 가이드는 Claude Code를 처음 도입하는 팀의 온보딩 자료로 유용하다. 다만 저장소 안의 모델명·최신 기능 설명은 빠르게 낡을 수 있으므로, 가격·모델 스펙·공식 CLI 동작은 Anthropic 공식 문서로 재확인해야 한다.
관련 문서
- claude-code — Claude Code 핵심 개요
- claude-code-tips-best-practice — 확장 메커니즘과 베스트 프랙티스 모음
- agent-skills — 에이전트 스킬 시스템 개요
- mcp — AI 에이전트와 외부 시스템을 연결하는 표준 프로토콜
참고 자료
- wesammustafa/Claude-Code-Everything-You-Need-to-Know — GitHub 공식 저장소