5만 스타를 기록한 Claude Code 팁 모음, 본질은 단 2가지

이 리포지토리는 무엇인가

shanraisshan/claude-code-best-practice

는 GitHub Trending 1위를 차지하며 현재 5만 스타 가까이 성장하고 있는 Claude Code의 베스트 프랙티스 (Best Practice) 모음집입니다.

내용을 한마디로 정의하자면, 설정 파일을 배포하는 템플릿 모음이 아니라, "Claude Code를 잘 사용하기 위한 지식"을 링크와 함께 정리한 레퍼런스 (Reference) 입니다. 크게 다음 세 가지 파트로 구성되어 있습니다.

개념 레퍼런스 (CONCEPTS) — Subagents / Commands / Skills / Hooks / MCP / Memory 등, Claude Code의 각 기능이 "어느 파일에 위치하며 무엇을 하는 것인가"를 일람화
Tips & Tricks (82개) — Prompting / Planning / Context / CLAUDE.md / Agents / Hooks / Git 등 14개 카테고리로 분류된 실전 팁. 하나하나에 출처 링크가 달려 있는 것이 특징
개발 워크플로우 비교 — Superpowers, Spec Kit, BMAD-METHOD 등 10개 이상의 수법을 비교표로 나열한 카탈로그

저자인 Shayan Rais 씨는 Anthropic의 직원이 아니라 커뮤니티의 개인입니다. 가치의 원천은 독자적인 노하우가 아니라, Claude Code를 만들고 있는 Anthropic 측의 발신(창시자 Boris Cherny, Claude Code 팀의 엔지니어 Thariq, 프로덕트 책임자 Cat Wu 등)을 1차 정보로서 정성스럽게 집약하고 있다는 점에 있습니다. 팁의 출처가 거의 모두 본인의 X나 팟캐스트에 링크되어 있어, 재인용으로 인한 왜곡 없이 원전으로 거슬러 올라갈 수 있습니다.

이 글의 읽는 법

82개의 팁을 전부 훑어보는 것은 "리스트를 구경하는 것"으로 끝날 수 있습니다. 그래서 이 글에서는 리포지토리 전체를 관통하는 2가지 설계 사상을 축으로 하여, 관련 팁들을 묶어서 해설합니다.

CLAUDE.md는 심플하게 유지한다 (너무 많이 담지 않는다)
하네스 엔지니어링 (Harness Engineering) (Claude 본체가 아니라 "Claude를 둘러싼 메커니즘"을 정비한다)

둘 다 팁 모음집 속에서 Boris Cherny가 반복해서 주장하고 있는 내용입니다. "만든 이가 실제로 하고 있는 것 → 왜 그렇게 하는가 → 자신의 환경에 어떻게 도입할 것인가" 순서로 살펴보겠습니다.

대전제: 제작자의 설정은 "놀라울 정도로 바닐라(Vanilla)"

두 가지 축을 다루기 전에, 리포지토리를 읽을 때 가장 중요한 전제를 짚고 넘어갑니다. Claude Code의 창시자인 Boris Cherny 자신이 자신의 설정을 "surprisingly vanilla" (놀라울 정도로 순수한 상태) 라고 표현하고 있다는 점입니다.

Claude Code는 그대로 두어도 충분히 잘 작동하기 때문에 그다지 커스터마이징(Customizing)하지 않았습니다. 팀은 "사용하기, 커스터마이징하기, 해킹하기"를 자유롭게 할 수 있도록 의도적으로 만들어졌으며, 팀원 모두가 각기 전혀 다른 방식으로 사용하고 있습니다.

즉, "엄청난 설정을 대량으로 쌓아 올리는 것"이 정답은 아닙니다. 오히려 반대로, 필요 최소한으로 유지하며 효과가 확실한 것만 넣는 것이 제작자의 사상입니다. 이 온도감을 파악해 두면, 5만 스타의 리포지토리를 마주했을 때 "전부 다 넣어야 해"라며 부담을 가질 필요가 없습니다. 읽어야 할 것은 설정의 양이 아니라, 다음 두 가지 축의 사고방식입니다.

축 1: CLAUDE.md는 심플하게 유지한다

왜 짧게 만드는가

CLAUDE.md는 매 세션의 서두에 통째로 읽히는, 말하자면 상주 메모리입니다. 그렇기 때문에 길게 쓴다고 해서 더 효과적인 것은 아닙니다. 오히려 반대의 현상이 보고되고 있습니다.

• 공식 문서에서는 파일당 200행 이하를 목표로 제시하고 있으며, Boris도 유사한 기준을 언급하고 있습니다. 파일이 길어지면 컨텍스트 (Context)를 소비하며, 오히려 지시 준수율을 떨어뜨린다고 합니다.
• HumanLayer의 Dex 씨는 60행이라는 실례를 들었지만, 그럼에도 "지시를 100% 지키게 할 보장은 없다"고 주석을 달았습니다.
• 실제로 r/ClaudeCode에서는 "CLAUDE.md에 '반드시 에이전트를 사용하라'고 적었는데 80%는 무시된다"라는 보고도 올라오고 있습니다.

길수록 잘 지켜지는 것이 아니라, 파일이 부풀어 오르면 개별 지시 사항이 묻혀 무시되기 쉬워진다는 것이 공통된 인식입니다.

짧게 유지하기 위한 구체적 방안

리포지토리의 팁(Tips)에서 CLAUDE.md를 비대하게 만들지 않기 위한 실천 방안을 추출하면 다음과 같습니다.

1. .claude/rules/로 분리하여 필요할 때만 읽어오게 하기

.claude/rules/*.md 파일은 아무런 조치를 취하지 않으면 CLAUDE.md와 마찬가지로 매 세션마다 읽힙니다. 여기에 paths: 프론트매터(frontmatter)를 추가하면, Claude가 해당 glob 패턴에 일치하는 파일을 읽었을 때만 로드되도록 설정할 수 있습니다(매 도구 사용 시가 아니라, Read가 트리거될 때).

도메인 특화 규칙(domain-specific rules)은 이 방식으로 분리하는 것이 정석입니다.

---
paths:
- "src/payments/**/*.ts"
...

paths를 가지지 않은 규칙 파일은 CLAUDE.md와 마찬가지로 조건 없이 매 세션마다 읽힙니다. 결제 관련 파일을 읽을 때만 이 규칙이 나타나므로, 관련 없는 세션의 컨텍스트(context)를 오염시키지 않습니다.

2. 잘 지켜지지 않는 규칙은 <important>로 감싸기

파일이 길어지면 무시되기 쉬운 규칙은 <important if="..."> 태그로 감싸면 더 효과적이라는 Dex 씨의 팁이 있습니다.

3. 모노레포(Monorepo)에서는 여러 개의 CLAUDE.md를 계층적으로 배치하기

루트에 모든 것을 작성하는 대신, 각 패키지에 CLAUDE.md를 두면 Claude는 조상(ancestor)과 자손(descendant) 규칙을 모두 읽습니다. 서브 프로젝트의 규칙은 해당 서브 디렉토리에 두는 방식의 분할입니다.

4. CLAUDE.md의 "최소 기준" 테스트

이것이 개인적으로 가장 와닿았던 팁입니다 (Dex 씨).

어떤 개발자라도 Claude를 실행하고 "테스트를 실행해줘"라고 말했을 때 단번에 통과해야 합니다.

만약 통과하지 못한다면, 당신의 CLAUDE.md에는 설정(setup)/빌드(build)/테스트(test)를 위한 기본 명령어가 누락되어 있는 것입니다.

즉, CLAUDE.md에 써야 할 것은 "예의 바른 지시"보다 먼저, 프로젝트를 구동하기 위한 기본 명령어라는 뜻입니다. 이 부분이 빠져 있으면 Claude는 매번 갈피를 잡지 못하고 컨텍스트를 소모하게 됩니다.

"설정으로 결정되는 것"을 CLAUDE.md에 쓰지 않기

또 하나 중요한 구분이 있습니다. 결정론적(deterministically)으로 설정할 수 있는 것을 요청 기반의 자연어로 CLAUDE.md에 쓰지 않는 것입니다.

예를 들어, CLAUDE.md에 "커밋에 Co-Authored-By를 붙이지 마"라고 쓰는 것보다, settings.json의 attribution.commit: ""를 통해 기계적으로 차단하는 것이 훨씬 확실합니다. 공식 문서에서도 이를 명확히 구분하고 있는데, CLAUDE.md는 "컨텍스트(부탁)"이지 강제 사항이 아니며, 확실하게 적용하고 싶은 동작은 설정이나 훅(hook) 같은 클라이언트 측 메커니즘으로 보장해야 한다고 명시합니다. 자연어 지시는 확률적으로 흔들릴 수 있지만, 설정값은 클라이언트가 강제합니다.

이것은 다음 축인 "하네스 엔지니어링(Harness Engineering)"으로 직결됩니다.

축 2: 하네스 엔지니어링 ── Claude를 둘러싼 메커니즘 만들기

하네스(Harness)란 무엇인가

**하네스(harness)**란 Claude라는 모델 본체가 아니라, **그 주변을 둘러싼 발판이나 지그(jig)**를 의미합니다. 훅(hook), 권한 설정, 검증 스크립트, 슬래시 명령어(slash command), 서브 에이전트(sub-agent) ── 이들을 통칭하여 "하네스"라고 부릅니다.

Boris의 주장을 한마디로 요약하면, **"모델을 똑똑하게 만들려 하지 마라. 모델이 실패하기 어려운 구조를 만들어라"**입니다. 프롬프트를 고민하는 것보다 Claude가 스스로 정답에 도달할 수 있는 발판을 짜주는 것이 결과물의 질을 더 안정적으로 만든다는 사고방식입니다.

최우선 사항: Claude에게 "검증 수단"을 제공하기

Boris가 "가장 중요하다"고 명시한 팁이 바로 이것입니다.

Claude에게 자신의 작업을 검증할 방법을 주는 것입니다. 이 피드백 루프(feedback loop)가 있으면 최종 결과물의 질이 2~3배 향상됩니다. Boris가 반영(land)하는 모든 변경 사항은 Claude가 테스트를 거칩니다.

핵심은 사람이 나중에 리뷰하는 것이 아니라, Claude 스스로 그 자리에서 검증할 수 있도록 하는 것입니다. 테스트, 타입 체크(type check), E2E, 브라우저 조작 ── 무엇이든 좋으니 "정답이었는지 스스로 확인할 수 있는 경로"를 제공하면, Claude는 실패를 스스로 찾아내고 수정하게 됩니다.

이를 체계화한 것이 Boris의 /go 스킬입니다.

/go

스킬: (1) bash/브라우저/computer use를 통해 end-to-end로 테스트 → (2) /simplify로 정리 → (3) PR을 올린다. 따라서 다시 돌아왔을 때는 코드가 작동한다는 것을 알고 있는 상태가 된다.

후크(Hook)로 「마지막 10%」를 기계적으로 채우기

검증을 시스템으로 구현하는 또 다른 전형적인 방법은 후크 (Hook) 입니다. Boris의 PostToolUse 후크 예시입니다.

"PostToolUse": [
{
"matcher": "Write|Edit",
...

Claude는 원래 잘 포맷팅된 코드를 작성합니다. 후크는 나머지 10%를 처리하여, 나중에 CI가 포맷팅 에러로 인해 실패하는 것을 방지합니다.

여기에서의 사고방식이 중요한데, **「Claude에게 포맷팅을 지키라고 시키는 것」이 아니라 「후크로 기계적으로 정돈하는 것」**입니다. 확률적인 지시가 아니라 결정론적인 후처리(deterministic post-processing)로 만드는 것입니다. CLAUDE.md에 "console.log를 남기지 마라"라고 쓰는 대신, 편집 후 후크에서 grep을 실행하여 경고를 띄우는 것도 같은 발상입니다.

그 외에도 실용적인 후크 팁이 있습니다.

• Stop 후크를 사용하여 턴 종료 시 Claude에게 "계속하라/검증하라"고 촉구한다.
• 권한 요청을 Opus로 넘겨 공격을 자동 스캔하고, 안전한 것은 자동 승인하게 한다.
• PreToolUse 후크로 스킬 사용 횟수를 측정하여, 효과가 없는 스킬을 찾아낸다.

--dangerously-skip-permissions는 사용하지 마라

권한은 "pre-allow"이며, 하네스(harness) 관점에서 중요한 것이 권한 설계입니다. Boris는 위험한 전체 허용 플래그를 사용하지 않고, 안전하다고 판단되는 명령만 사전 허용합니다.

--dangerously-skip-permissions를 사용하지 마세요. 대신 /permissions를 통해 자신의 환경에서 안전하다고 알고 있는 bash 명령을 사전 허용하십시오. 이것들은 .claude/settings.json에 체크인하여 팀과 공유합니다.

/permissions
# 예: Bash(npm run *), Edit(/docs/**)

더 최신 옵션으로는 Auto 모드(모델 기반 분류기가 각 명령의 안전성을 판단하여 자동 승인하고, 위험하면 중단)가 있으며, 이것이 전체 허용 플래그의 올바른 대안으로 여겨집니다. Shift+Tab으로 Ask → Plan → Auto를 전환할 수 있습니다.

여기까지를 CLAUDE.md / 설정에 반영하면

축 1과 축 2를 고려하면, 최소 구성은 대략 다음과 같습니다. "모두 포함"하는 것이 아니라 "효과가 있는 것만" 의식한 형태입니다.

CLAUDE.md (짧게, 기본 명령 중심)

# 프로젝트 개요
[1~2줄]
# 셋업 / 빌드 / 테스트
...

.claude/settings.json (결정론적으로 작동하는 것)

• 포맷팅을 위한 PostToolUse 후크
• 안전한 명령의 사전 허용
• attribution 등 기계적으로 결정되는 설정

.claude/rules/*.md (paths:로 지연 로딩)

• 도메인 특화된 세부 규칙

포인트는, 「부탁」은 CLAUDE.md에 최소한으로, 「강제」는 settings.json에라는 역할 분담입니다.

보충: 워크플로우 비교표의 핵심

서두에서 언급한 3개 파트 중 「개발 워크플로우 비교」에는 10개 이상의 방법론(Superpowers, Spec Kit, BMAD-METHOD 등)이 스타 수와 함께 나열되어 있습니다. 숫자가 많아 압도될 수 있지만, 저자는 모든 것이 동일한 골격으로 수렴한다고 정리합니다.

Research → Plan → Execute → Review → Ship

그리고 Boris의 세션 운용은 이를 뒷받침하는 형태로 심플합니다.

• 대부분의 세션을 Plan 모드로 시작 (Shift+Tab

2회）。PR이 목적이라면 계획에 만족할 때까지 왕복한 후 auto-accept로 전환한다. '좋은 계획'이 정말 중요하다. - 코딩은 Opus + thinking을 사용한다. 크게 느리지만, 조향(steering)이 줄어드는 만큼 결국 빠르다. - 하루에도 여러 번 하는 '이너 루프'는 슬래시 명령어화하여 git에 체크인한다. - 하루 한 번 이상 하는 것은 스킬이거나 명령어로 만든다.

'똑똑한 프롬프트를 매번 입력하는 것'보다 '반복 작업을 시스템으로 만드는 것'── 여기서도 하네스(Harness)의 사상이 일관됩니다.

요약: 이 리포지토리에서 어디를 보면 좋은가

claude-code-best-practice는 5만 스타라는 규모이지만, 설정을 통째로 복사하기 위한 것이 아닙니다. Anthropic 개발자들이 수집한 일차 정보의 참고 자료이며, 여기서 읽어낼 핵심은 화려한 커스터마이징이 아니라 다음 두 가지에 있습니다.

CLAUDE.md는 심플하게. 길게 쓰는 것보다 기본 명령어를 갖추고, 도메인 규칙은 rules/에 맡기며, 강제하고 싶은 것은 설정으로 기계적으로 작동시킨다. -
하네스를 구축한다. Claude를 똑똑하게 만들려고 하기보다는, Claude가 스스로 검증 및 수정할 수 있는 발판(검증 수단・훅・권한 설계)을 마련하는 것이다.

'설정을 쌓아 올리는 것'이 아니라 '실패하기 어려운 시스템을 만드는 것'. 개발자들이