MuhammadUsmanGM/claude-code-best-practices

Claude Code를 사용하여 실제 소프트웨어를 출시하기 위한 커뮤니티 핸드북입니다. 가이드, 작동하는 플러그인 (plugins), 즉시 사용 가능한 스타터 키트 (starter kits), 공개된 벤치마크 (benchmarks), 그리고 복사해서 사용할 수 있는 검증된 .claude/ 설정이 포함되어 있습니다.

최종 업데이트: 2026년 5월 12일 · v1.6 · Claude Code v2.1.139 지원 · Opus 4.7 / Sonnet 4.6 / Haiku 4.5 포함

렌더링된 사이트 보기: MuhammadUsmanGM.github.io/claude-code-best-practices

Claude Code는 기본적으로 강력하지만, "작동한다"와 "프로덕션 코드 (production code)를 안정적으로 출시한다" 사이의 간극은 몇 가지 패턴을 통해 메워집니다: 정교한 CLAUDE.md, 올바른 권한 모드 (permission mode), 실수가 디스크에 기록되기 전에 잡아내는 훅 (hooks), 반복 작업을 위한 기술 (skills), 그리고 추론 가능한 비용 모델 (cost model)입니다. 이러한 지식의 대부분은 블로그 포스트, Discord 스레드, 내부 위키 (wikis) 등에 흩어져 있습니다.

이 저장소 (repo)는 이를 한곳에 모았습니다 — 주관이 뚜렷하며, 테스트되었고, 자체적으로 검증되었습니다 (dogfooded). 이곳의 모든 컨벤션 (convention)은 여러분이 읽고 있는 이 저장소를 구축하는 데 사용되었습니다: .claude/ 디렉토리는 훅 (hooks)을 연결하고, /lint-docs 기술 (skill)은 CI가 수행하는 것과 동일한 체크를 실행하며, 커밋 로그 (commit log)는 plugins/commit-helper/ 아래에 있는 Conventional Commits 기술의 작동 예시입니다.

30개 이상의 가이드: 기초, 워크플로우 (workflows), 권한 (permissions), 고급 아키텍처 (advanced architecture), 비용 관리 (cost management), 보안 (security)을 다룹니다.
11개의 CLAUDE.md 템플릿: React, Python, Go, Rust, Rails, Django, Next.js, Spring Boot, Flutter, 모노레포 (monorepos) 및 최소한의 스타터용.
4개의 스타터 키트: React, Next.js, Python, Go를 위한 프로젝트 전체 드롭인 (drop-ins) (CLAUDE.md + 설정, 기술, 훅이 포함된 .claude/ 디렉토리).
작동하는 플러그인 (commit-helper): Conventional Commits 기술과 비밀 정보가 커밋되기 전에 차단하는 PreToolUse 훅을 포함합니다.
즉시 사용 가능한 기술 및 훅 스크립트 (hook scripts): /changelog, /pr-describe, /test-triage를 비롯하여 block-secrets, format-on-write, test-on-stop이 포함됩니다.

공개된 벤치마크 (Published benchmarks)— 모델 비교, Plan-mode On/Off, CLAUDE.md의 효용성, 그리고 Prompt-cache의 영향력을 다루며, 본인의 리포지토리(repo)에서 직접 다시 실행해 볼 수 있도록 재현 가능한 하네스 (harness)를 제공합니다. 보안 플레이북 (Security playbook)— 프롬프트 인젝션 (Prompt injection), 플러그인 공급망 (Plugin supply chain), 그리고 팀 감사 체크리스트를 다룹니다. 직접 사용해 봄 (Dogfooded)— 그대로 복사해서 사용할 수 있습니다 — .claude/를 참조하세요.

CLAUDE.md 설정 및 .claude/.

개별 개발자— Claude Code를 처음 설정하며 "시행착오" 단계를 건너뛰고 싶은 분들. 팀— 엔지니어들의 Claude Code 사용 방식을 표준화하려는 팀 — 공유 설정 (shared configs), 권한 정책 (permission policies), 그리고 온보딩 문서 (onboarding docs). 도구 제작자 (Tooling authors)— 연구를 위한 참조 구현체 (reference implementations)를 원하는 플러그인, 스킬 (skills), 또는 훅 (hooks) 제작자.

$ claude "Fix the failing test in src/utils/dates.test.ts"
● Reading src/utils/dates.test.ts...
● Reading src/utils/dates.ts...
...

단 하나의 프롬프트. Claude가 코드를 읽고, 버그를 찾아내고, 수정하며, 테스트가 통과하는지 확인합니다. 이 리포지토리의 가이드들은 여러분의 코드베이스에서 이러한 루프 (loop)를 — 신뢰할 수 있고, 저렴하며, 예상치 못한 상황 없이 — 구현하는 방법에 관한 것입니다.

설치 (Install): npm install -g @anthropic-ai/claude-code

인증 (Authenticate): claude를 실행하고 안내에 따라 로그인하세요. 스타터 키트 (Starter kit) 적용 (새 프로젝트에 권장): cp -r starters/<stack>/. /path/to/your/repo/ . 스타터 개요를 참조하세요. 또는 기존 프로젝트를 위한 CLAUDE.md 생성: bash tools/generate-claude-md.sh를 실행하거나, Quickstart Prompt를 사용하여 Claude가 여러분의 코드베이스로부터 직접 작성하게 하세요. 코딩 시작: 프로젝트에서 claude를 실행하세요.

이 모든 것이 처음인가요? Getting Started → CLAUDE.md Guide → Workflow Patterns 순서로 읽어보세요. 각 단계는 약 10분 정도 소요됩니다.

claude-code-best-practices/
├── guides/ 30개 이상의 가이드 — 기초, 워크플로우, 고급, 비용, 보안, 참조
├── examples/ CLAUDE.md 템플릿 (11개 스택) + 즉시 사용 가능한 스킬 (skills) + 훅 스크립트 (hook-script) 레시피
...

가이드 (Guide)	설명 (Description)
시작하기 (Getting Started)	설치, 인증, 첫 실행 및 기본적인 CLI 사용법
...	...
가이드 (Guide)	설명 (Description)
---	---
워크플로우 패턴 (Workflow Patterns)	버그 수정, 기능 구현, 리팩터링(Refactoring) 및 PR 리뷰를 위한 일반적인 워크플로우
...	...
가이드 (Guide)	설명 (Description)
---	---
커스텀 지침 (Custom Instructions)	페르소나 및 역할 기반 동작을 위한 고급 CLAUDE.md 패턴
...	...
가이드 (Guide)	설명 (Description)
---	---
성능 튜닝 (Performance Tuning)	모델 선택, 빠른 모드(fast mode), 속도 및 비용 최적화
...	...
가이드 (Guide)	설명 (Description)
---	---
문제 해결 (Troubleshooting)	일반적인 문제 및 해결 방법
...	...
예시 (Example)	설명 (Description)
---	---
React 프로젝트 (React Project)	React + TypeScript 프론트엔드를 위한 CLAUDE.md
...	...
도구 (Tool)	설명 (Description)
---	---
CLAUDE.md 생성기 (CLAUDE.md Generator)	60초 만에 CLAUDE.md를 생성하는 대화형 셸 스크립트
...	...
항목 (Item)	설명 (Description)
---	---
commit-helper 플러그인 (commit-helper plugin)	v1.3 신규 기능. 작동하는 플러그인: Conventional Commits 스킬 + secret-blocking 훅
...	...

전체 프로젝트 즉시 적용 키트 (Whole-project drop-in kits) — CLAUDE.md

• .claude/

스택별 (settings, skills, hooks).

키트 (Kit)	설명 (Description)
React	v1.4 신규 기능. React + TypeScript, ESLint+Prettier, /component-new 및 /test-component 스킬
...	...
예시 (Example)	설명 (Description)
---	---
훅 스크립트 (Hook Scripts)	일반적인 작업을 위한 즉시 사용 가능한 훅 설정
MCP 설정 (MCP Configs)	인기 있는 서비스를 위한 샘플 MCP 서버 설정

Awesome list— Claude Code와 잘 어울리는 엄선된 플러그인, 스킬, 포스트 및 도구들.
Discussions— 자유로운 질문, 아이디어, 사례 공유. 리포지토리의 Settings → General → Features에서 활성화할 수 있습니다.
Issues— 구체적인 버그 및 도구/가이드 요청. .github/ISSUE_TEMPLATE/ 아래에 템플릿이 있습니다.

스타일 컨벤션(Style conventions) 및 PR 프로세스는 CONTRIBUTING.md를 참조하세요. 모든 PR은 5개의 CI 체크를 거칩니다:

체크 항목	탐지 내용
shellcheck	저장소 내 모든 .sh 파일의 Shell 버그
...

여섯 번째 워크플로(benchmarks)가 연결되어 있으나 수동으로만(manual-only) 실행 가능합니다. 이 워크플로는 Anthropic API를 호출하며, 실행하는 사람에게 토큰 비용이 청구됩니다. ANTHROPIC_API_KEY를 저장소 시크릿(repo secret)으로 설정한 포크(fork)에서 Actions → benchmarks → Run workflow를 통해 실행하세요.

CHANGELOG.md는 Keep a Changelog를 따릅니다.

• 버전은 semver를 따릅니다. 현재 릴리스: v1.6.0.
• 스타터 키트(starter kits), 플러그인(plugins) 또는 훅 스크립트(hook scripts)에 대한 파괴적 변경(Breaking changes)이 발생하면 메이저 버전(major version)이 올라갑니다.

MIT — LICENSE를 참조하세요. 커뮤니티 유지 관리 프로젝트이며, Anthropic과 관련이 없습니다.