claude-code-best-practice는 “vibe coding에서 에이전트 엔지니어링으로”를 슬로건으로 내건 Claude Code 커뮤니티 베스트 프랙티스 저장소다. GitHub Trending 일간 1위를 기록했으며, Claude Code의 모든 확장 메커니즘(서브에이전트·커맨드·스킬·훅·MCP·메모리)에 대한 개념 설명·베스트 프랙티스·실제 구현 예시를 한 곳에 정리한다.
GitHub: shanraisshan/claude-code-best-practice
핵심 확장 메커니즘 비교
| 메커니즘 | 위치 | 특징 |
|---|---|---|
| 서브에이전트(Subagent) | .claude/agents/<name>.md | 격리된 새 컨텍스트에서 실행하는 자율 행위자. 커스텀 도구·권한·모델·메모리 보유 |
| 커맨드(Command) | .claude/commands/<name>.md | 기존 컨텍스트에 주입하는 프롬프트 템플릿. 워크플로우 트리거용 |
| 스킬(Skill) | .claude/skills/<name>/SKILL.md | 컨텍스트에 주입하는 설정 가능한 지식. 자동 발견·프로그레시브 디스클로저 지원 |
| 훅(Hook) | .claude/hooks/ | 에이전트 루프 외부에서 특정 이벤트에 실행되는 사용자 정의 핸들러 |
| MCP 서버 | .claude/settings.json | 외부 도구·데이터베이스·API 연결 |
핵심 팁 엄선 (82개 중)
프롬프팅
- “grill me on these changes and don’t make a PR until I pass your test” — Claude에게 직접 검증을 요청해 품질 향상
- 평범한 수정 후 “knowing everything you know now, scrap this and implement the elegant solution” — 우아한 해결책 도출
- 버그는 그냥 붙여넣고 “fix”만 입력. 방법을 지시하지 말 것
플래닝
- 항상 Plan 모드로 시작
- AskUserQuestion 도구로 Claude가 먼저 인터뷰하게 한 뒤 새 세션에서 실행
- 각 단계마다 단위·자동화·통합 테스트를 포함한 단계별 게이트 플랜 수립
- 두 번째 Claude로 스태프 엔지니어 역할 시켜 플랜 리뷰
주목할 최신 기능들
| 기능 | 설명 |
|---|---|
| Ultrareview | 클라우드 멀티 에이전트 코드 리뷰 (Pro/Max 3회 무료) |
| Ultraplan | 클라우드 기반 플랜 작성 후 인라인 댓글·유연한 실행 |
| Auto Mode | 백그라운드 안전 분류기가 권한 프롬프트를 대체 |
| Agent Teams | 동일 코드베이스에서 병렬 작업하는 멀티 에이전트 |
| Remote Control | 로컬 세션을 스마트폰·브라우저에서 원격 계속 |
| Voice Dictation | 푸시 투 토크 20개 언어 음성 입력 |
오케스트레이션 패턴
저장소에서 제안하는 핵심 패턴:
Command → Agent → Skill커맨드로 워크플로우를 트리거 → 에이전트가 격리된 컨텍스트에서 실행 → 스킬로 전문 지식 주입. Weather Orchestrator 예시로 구체적 구현 방법을 시연한다.
최근 확장 범위
2026년 6월 기준 README는 Claude Code 전용 팁을 넘어 cross-model workflow, skill collection, agent collection까지 포함하는 메타 카탈로그 성격이 강해졌다. Codex plugin, Gemini CLI, router, MCP server처럼 다른 모델·CLI와 Claude Code를 함께 쓰는 흐름도 별도 섹션으로 정리한다.
관련 문서
- claude-code — Claude Code 핵심 개요
- agent-skills — 에이전트 스킬 시스템 상세
- claude-code-routines — 스케줄·API·GitHub 이벤트 자동화
참고 자료
- shanraisshan/claude-code-best-practice — GitHub 공식 저장소