claude-code-best-practice 딥다이브
— Claude Code를 제대로 쓰는 법, 83개 팁 + 구현 예제 총정리

1프로젝트 한줄 요약

claude-code-best-practice는 Claude Code를 제대로 쓰는 법을 총정리한 실전 베스트 프랙티스 레포지토리입니다. 서브에이전트, 커맨드, 스킬, 훅, MCP 서버, 에이전트 팀까지 — Claude Code의 모든 아키텍처 패턴을 구현 예제와 함께 문서화했습니다. 83개 커뮤니티 팁, 12개 심층 보고서, 11개 개발 워크플로우를 한 곳에 모아놓은 원스톱 참고서입니다.

2왜 주목받는가

경쟁 레포 대비 위치

3기술 스택 전체 지도

이 레포는 코드 프로젝트가 아니라 문서 + 설정 예제 프로젝트입니다. 다루는 기술 스택은 Claude Code 생태계 전체를 포괄합니다.

4아키텍처 심화 분석

4.1 Command → Agent → Skill 파이프라인

이 레포가 제시하는 핵심 아키텍처 패턴입니다. 날씨 SVG 생성 예제로 설명하면:

4.2 서브에이전트 시스템 (16개 설정 필드)

4.3 에이전트 팀 (Agent Teams)

4.4 설정 계층 시스템 (5단계)

4.5 메모리 시스템 (CLAUDE.md 로딩 전략)

5디렉토리 구조 해부

6학습 포인트 (기술별)

6.1 서브에이전트 설계 패턴

배울 것: 서브에이전트의 16개 설정 필드를 이해하면, Claude Code를 "코딩 비서"가 아니라 "자율 팀"으로 운영할 수 있습니다.

# .claude/agents/code-reviewer.md 예시
---
name: code-reviewer
description: "PROACTIVELY review PRs for bugs and vulnerabilities"
model: opus
tools: [Read, Grep, Glob, Bash]
permissionMode: plan
maxTurns: 30
isolation: worktree
---
PR의 모든 변경 파일을 읽고, 버그/보안/성능 이슈를 찾아 보고서를 작성하라.

6.2 스킬 아키텍처 (Progressive Disclosure)

배울 것: 스킬의 16개 프론트매터 필드를 활용한 지식 모듈화. 직접 호출 스킬(user-invocable: true) vs 주입형 에이전트 스킬(user-invocable: false) 차이.

고급 필드: context: fork(격리 실행), paths: "src/api/**"(경로 자동 활성화), allowed-tools(도구 제한).

6.3 MCP 서버 실전 활용

추천 MCP 서버 5선:

6.4 Hooks 시스템

대표 4가지 이벤트 (전체 30개 중): SessionStart(환경 초기화), PreToolUse(검증/차단), PostToolUse(결과 가공), Stop(정리/알림). 그 외 SessionEnd, PermissionRequest, SubagentStart 등 총 30개 이벤트 지원.

사용 예시:
PreToolUse  → "Write 도구 사용 전 lint 검사 실행"
PostToolUse → "파일 수정 후 자동 포맷팅"
Stop        → "세션 종료 시 Slack 알림 전송"

6.5 개발 워크플로우 패턴

이 레포가 분석한 11개 유명 워크플로우는 모두 같은 패턴으로 수렴합니다:

7하드웨어 / 시스템 요구사항

8직접 해볼 수 있는 실습 과제

{
  "mcpServers": {
    "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] },
    "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp"] }
  }
}

9관련 기술 심화 학습 로드맵

1주차 — Claude Code 기초 마스터

CLAUDE.md 작성법 및 로딩 메커니즘 이해, 내장 명령어 85개 훑어보기(특히 /plan, /compact, /doctor), 설정 계층 5단계 실습.

2주차 — 스킬과 커맨드

스킬 프론트매터 16개 필드 실습, 커맨드 프론트매터 16개 필드 실습, 직접 호출 스킬 vs 주입형 에이전트 스킬 차이 체득, Progressive Disclosure 패턴 적용.

3주차 — 서브에이전트와 MCP

서브에이전트 16개 설정 필드 마스터, 내장 에이전트 5개 활용법, MCP 서버 연결 및 활용(Context7, Playwright), 권한 시스템(deny > ask > allow).

4주차 — 고급 패턴

Agent Teams 구축(tmux + 공유 태스크), Hooks로 워크플로우 자동화, /loop와 /schedule로 반복 작업 자동화, Git worktree를 활용한 병렬 작업.

5주차 — 워크플로우 통합

자신만의 개발 워크플로우 설계, Research → Plan → Execute → Review → Ship 파이프라인 구축, 실제 프로젝트에 적용하여 생산성 측정.

10핵심 키워드 사전

11참고 링크

• GitHub 레포 — shanraisshan/claude-code-best-practice
• Claude Code 공식 문서
• Claude Code GitHub
• MCP 프로토콜 스펙
• Superpowers 워크플로우
• Spec Kit
• Context7 MCP
• Playwright MCP