클로드 코드 6개월 쓴 개발자가 알려주는 "진짜" 세팅법

Reddit에서 난리 난 글이 하나 있어요. "Claude Code is a Beast – Tips from 6 Months of Hardcore Use." 6개월 동안 타입스크립트 마이크로서비스 6개, 코드 5만 줄 넘게 클로드 코드로 작업한 개발자가 자기 세팅을 통째로 공개한 거예요.

그냥 "이렇게 쓰면 좋아요~" 수준이 아니에요. GitHub에 프로덕션급 인프라를 통째로 올려버렸어요. 스타가 40시간 만에 1,100개가 찍혔고, 지금은 8,800개를 넘겼어요. 포크만 1,100개가 넘고요.

오늘은 이 글을 깊게 뜯어보면서, 왜 이렇게 반응이 폭발적이었는지, 그리고 우리가 실제로 뭘 가져다 쓸 수 있는지 하나하나 짚어볼게요.

이 사람이 도대체 뭘 만든 건가요?

먼저 배경부터 볼게요. 이 개발자(diet103)는 복잡한 타입스크립트 마이크로서비스 프로젝트를 클로드 코드로 매일 개발하고 있었어요. 서비스 6개, 코드 5만 줄 이상. 단순한 사이드 프로젝트가 아니라 프로덕션 환경이에요.

6개월 동안 매일 쓰면서 느낀 거예요. 클로드 코드, 날것 그대로 쓰면 50%밖에 못 쓴다. 왜냐하면:

이 문제들을 하나하나 해결한 결과물이 바로 이 레포예요. .claude/ 디렉토리 하나에 스킬 5개, 훅 6개, 에이전트 10개, 슬래시 명령어 3개를 구축한 거예요.

.claude/ ├── skills/ → 5개 스킬 (500줄 규칙) ├── hooks/ → 6개 훅 (자동화의 핵심) ├── agents/ → 10개 특화 에이전트 └── commands/ → 3개 슬래시 명령어 dev/ └── active/ → 개발 문서 패턴 (컨텍스트 리셋 대응)

하나씩 뜯어볼게요.

1. 게임 체인저: 훅(Hook) 기반 스킬 자동활성화

클로드 코드 써본 분들은 공감하실 텐데요. 스킬(Skills)이 자동으로 안 켜져요. 분명 만들어 놨는데, 매번 "아 그 스킬 써줘"라고 직접 말해야 하는 거죠. 마치 비서를 고용했는데 매번 "지금 일해"라고 말해야 움직이는 느낌이에요.

이 개발자가 찾은 돌파구는 UserPromptSubmit 훅이에요.

그게 뭔데요?

훅은 클로드 코드의 워크플로우 특정 시점에 자동으로 실행되는 스크립트예요. 클로드 코드는 4가지 훅 타이밍을 지원해요:

이 중에서 이 개발자가 **"이것만큼은 반드시 세팅하세요"**라고 강조한 게 2개예요.

필수 훅 #1: skill-activation-prompt

이게 핵심 중의 핵심이에요. 작동 방식을 보면:

1) 여러분이 프롬프트를 입력해요 2) 훅이 자동으로 실행돼요 3) skill-rules.json에서 패턴을 확인해요 4) 현재 작업 중인 파일도 체크해요 5) 매칭되는 스킬을 자동 제안해요

예를 들어, 여러분이 **"백엔드 API 라우트 하나 만들어줘"**라고 치면, 훅이 이걸 분석해요. "백엔드", "API", "라우트" 같은 키워드가 skill-rules.json의 backend-dev-guidelines 트리거와 매칭되는 거죠. 그러면 클로드가 알아서 "backend-dev-guidelines 스킬을 사용할까요?"라고 제안해주는 거예요.

설정은 이렇게 생겼어요:

{"hooks":{"UserPromptSubmit":[{"hooks":[{"type":"command","command":"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-activation-prompt.sh"}]}]}}

더 이상 "아 그 스킬 먼저 로드해줘"라고 말할 필요가 없어요. 클로드가 문맥을 파악해서 알아서 제안해줘요.

필수 훅 #2: post-tool-use-tracker

이건 Edit, Write, MultiEdit 같은 파일 수정 도구가 실행된 후에 자동으로 돌아가는 훅이에요. 하는 일은:

{"hooks":{"PostToolUse":[{"matcher":"Edit|MultiEdit|Write","hooks":[{"type":"command","command":"$CLAUDE_PROJECT_DIR/.claude/hooks/post-tool-use-tracker.sh"}]}]}}

이 2개만 세팅해도 클로드 코드 경험이 완전히 달라진다고 해요. 여기에 선택적으로 추가할 수 있는 훅이 4개 더 있어요:

다만 Stop 훅은 모노레포 구조에 맞춰져 있어서 그대로 쓰면 안 되고, 자기 프로젝트에 맞게 수정해야 해요.

2. skill-rules.json: 자동화의 두뇌

훅이 "언제" 실행할지 정하는 거라면, skill-rules.json은 "무엇을" 제안할지 정하는 설정 파일이에요. 이 파일이 없으면 훅이 실행돼도 뭘 제안해야 할지 모르겠죠.

구조를 보면:

{"backend-dev-guidelines":{"type":"domain","enforcement":"suggest","priority":"high","promptTriggers":{"keywords":["api","route","controller","service","repository"],"intentPatterns":["create.*endpoint","add.*route","build.*api"]},"fileTriggers":{"pathPatterns":["src/api/**/*.ts","backend/**/*.ts"],"contentPatterns":["import.*Express","import.*Prisma"]}}}

여기서 주목할 점이 2가지 있어요.

첫째, 트리거가 2종류예요:

"백엔드 API 만들어줘"라고 말하든, 백엔드 파일을 편집하든, 둘 다 스킬이 활성화돼요.

둘째, enforcement 레벨이 있어요:

"block"이 흥미로운데요. 예를 들어 frontend-dev-guidelines는 enforcement가 "block"으로 설정돼 있어요. MUI v6에서 v7으로 바뀌면서 Grid 컴포넌트의 size prop 방식이 완전히 달라졌거든요. 이걸 가드레일로 걸어놓으면 클로드가 실수로 구버전 문법을 쓰는 걸 원천 차단할 수 있어요.

핵심: skill-rules.json은 단순한 설정 파일이 아니에요. 팀의 개발 규칙을 코드화한 거예요. "우리 팀은 이렇게 개발한다"를 클로드에게 자동으로 주입하는 시스템이에요.

3. 500줄 규칙: 스킬 모듈화의 비밀

이 레포에는 5개의 프로덕션 스킬이 있어요:

여기서 눈에 띄는 게 있어요. 모든 파일이 500줄 이하예요. 이게 우연이 아니에요. 이 개발자가 의도적으로 만든 규칙이에요.

왜 500줄인가요?

클로드 코드의 컨텍스트 윈도우는 유한해요. 스킬 파일이 1,000줄, 2,000줄 되면 그것만으로 컨텍스트를 상당 부분 잡아먹어요. 그러면 정작 중요한 코드 분석이나 생성에 쓸 공간이 부족해지는 거죠.

그래서 이 개발자는 점진적 공개(Progressive Disclosure) 패턴을 도입했어요:

backend-dev-guidelines/ ├── SKILL.md (< 500줄 - 진입점, 전체 개요) └── resources/ ├── routing.md (< 500줄 - 라우팅 패턴) ├── controllers.md (< 500줄 - 컨트롤러 패턴) ├── services.md (< 500줄 - 서비스 레이어) ├── repositories.md (< 500줄 - 데이터 접근) ├── validation.md (< 500줄 - Zod 검증) ├── error-handling.md (< 500줄 - 에러 처리) ├── testing.md (< 500줄 - 테스트 패턴) ├── prisma.md (< 500줄 - Prisma ORM) ├── sentry.md (< 500줄 - Sentry 통합) ├── di.md (< 500줄 - 의존성 주입) ├── performance.md (< 500줄 - 성능 최적화) └── security.md (< 500줄 - 보안 패턴)

클로드가 "API 라우트 만들어줘"라고 받으면, 먼저 SKILL.md에서 전체 구조를 파악하고, 필요한 routing.md와 controllers.md만 추가로 로드하는 거예요. 나머지 10개 파일은 건드리지도 않아요.

마치 백과사전을 통째로 읽는 게 아니라, 필요한 항목만 펼쳐보는 거죠. 12개 리소스 파일을 한꺼번에 로드하면 수천 줄이지만, 필요한 2~3개만 로드하면 1,000줄 이내로 끝나요.

핵심: 스킬이 크다고 좋은 게 아니에요. 작고 모듈화된 스킬이 컨텍스트를 아끼고, 더 정확한 결과를 만들어요. 500줄은 "클로드가 소화하기 딱 좋은 크기"예요.

4. 각 스킬 깊이 보기

backend-dev-guidelines — 백엔드의 교과서

이 스킬은 Express/Prisma/TypeScript 환경에서의 개발 패턴을 담고 있어요. 12개 리소스 파일로 구성되어 있고, 핵심은 **계층 아키텍처(Layered Architecture)**예요:

Routes → Controllers → Services → Repositories

각 계층의 책임이 명확하게 분리돼 있어요:

Sentry 에러 추적, Zod 검증, 의존성 주입까지 실무에서 쓰는 패턴이 다 들어있어요.

frontend-dev-guidelines — 프론트엔드 가드레일

이 스킬은 React/MUI v7/TanStack 환경 전용이에요. 11개 리소스 파일에 이런 내용이 담겨있어요:

특히 이 스킬은 enforcement가 "block"이에요. MUI v6 문법을 쓰면 클로드가 자동으로 막아요. 이게 "가드레일로서의 스킬" 개념인데, 정말 똑똑한 접근이에요.

skill-developer — 메타 스킬

이건 좀 특별해요. 스킬을 만드는 스킬이에요. 새 스킬을 작성할 때 YAML 프론트매터 구조, 리소스 파일 조직, 트리거 패턴 설계를 가이드해줘요. 7개 리소스 파일, 총 426줄.

커스터마이징 없이 그대로 복사해서 쓸 수 있어요.

route-tester — API 테스트 전문

JWT 쿠키 기반 인증 엔드포인트를 테스트하는 스킬이에요. test-auth-route.js 스크립트 패턴, cURL 인증 테스트, POST/PUT/DELETE 테스트를 다뤄요. 단, JWT 쿠키 인증을 쓰는 프로젝트에서만 의미 있어요.

error-tracking — Sentry 통합

Sentry v8 초기화, 에러 캡처 패턴, 브레드크럼, 퍼포먼스 모니터링을 다뤄요. Express와 React 양쪽 통합 패턴이 모두 포함돼 있어요.

5. 에이전트 10개: 반복 작업의 자동화

에이전트는 복잡한 다단계 작업을 자동으로 처리하는 전문가예요. 이 레포에는 10개가 있는데, 크게 4가지 카테고리로 나뉘어요.

코드 품질 & 아키텍처 (3개)

code-architecture-reviewer 새 기능을 구현한 후, 코드가 아키텍처 패턴을 잘 따르는지 자동 검토해요. "이 컨트롤러에서 직접 DB를 호출하고 있는데, Repository 레이어를 거쳐야 해요" 같은 피드백을 줘요.

code-refactor-master 대규모 리팩토링을 계획하고 실행해요. 파일 구조 재조직, 큰 컴포넌트 분리, import 경로 업데이트까지 추적해요.

plan-reviewer 구현을 시작하기 전에 개발 계획을 검증해요. "이 접근법에서 놓친 엣지 케이스가 있어요" 같은 선제적 리뷰를 해줘요.

문서화 & 분석 (3개)

documentation-architect API 문서, 개발자 가이드, 아키텍처 개요를 자동 생성해요.

refactor-planner 코드 재구성과 현대화 전략을 수립해요. 리팩토링의 "설계도"를 만들어주는 거죠.

web-research-specialist 기술 문제 해결을 위해 온라인 조사를 해요. GitHub 이슈, Stack Overflow, Reddit 등에서 유사 사례를 찾아줘요.

에러 처리 (2개)

frontend-error-fixer 브라우저 콘솔 에러, TypeScript 컴파일 에러, React 에러를 진단하고 수정해요.

auto-error-resolver 타입스크립트 컴파일 에러를 자동으로 수정해요. Stop 훅의 tsc-check와 연동하면, 빌드 실패 → 에러 감지 → 자동 수정이라는 파이프라인이 만들어져요.

인증 관련 (2개)

auth-route-tester JWT 쿠키 기반 인증 엔드포인트를 테스트해요. 라우트가 데이터를 올바르게 처리하는지, DB 레코드를 제대로 생성하는지 검증해요.

auth-route-debugger 401/403 에러, 쿠키 문제, JWT 토큰 이슈, 라우트 등록 문제를 디버깅해요.

핵심: 이 에이전트들은 대부분 독립형이에요. 레포에서 .md 파일 하나 복사하면 바로 작동해요. 다만 auth 관련 2개는 JWT 쿠키 인증 환경이 필요해요.

6. 컨텍스트 리셋 문제: 개발 문서 패턴

클로드 코드의 고질적 문제 중 하나 — 컨텍스트가 리셋되면 앞에서 한 작업을 통째로 까먹어요. 긴 작업을 하다가 컨텍스트가 압축되거나, 새 세션을 시작하면 "처음부터 다시 설명해야 하는" 상황이 오는 거죠.

이 개발자는 3파일 구조의 개발 문서 패턴으로 이걸 해결했어요:

dev/active/ ├── [task]-plan.md → 전략적 계획 (왜 이걸 하는지) ├── [task]-context.md → 핵심 결정사항과 관련 파일 목록 └── [task]-tasks.md → 체크리스트 형태의 할 일 목록

각 파일의 역할

plan.md — "왜" 이 작업을 하는지

# 인증 시스템 리팩토링 계획## 목표- JWT 쿠키 인증에서 OAuth2로 전환 - 기존 엔드포인트 호환성 유지 ## 접근법- Phase 1: OAuth2 프로바이더 통합 - Phase 2: 기존 JWT 엔드포인트 마이그레이션 - Phase 3: 레거시 JWT 제거

context.md — "무엇을" 결정했고, 어떤 파일이 관련되는지

# 핵심 결정사항- Prisma 스키마에 OAuth 테이블 추가 (마이그레이션 필요) - 기존 /auth/login은 유지하되 내부적으로 OAuth 흐름으로 변환 # 관련 파일- src/auth/controller.ts - src/auth/service.ts - prisma/schema.prisma

tasks.md — "어디까지" 했는지

- [x] OAuth2 프로바이더 설정 - [x] Prisma 스키마 업데이트 - [ ] 마이그레이션 실행 - [ ] 컨트롤러 리팩토링 - [ ] 테스트 작성

자동 생성과 업데이트

이 파일들을 수동으로 만들 필요는 없어요. 슬래시 명령어로 자동화돼 있어요:

컨텍스트가 리셋돼도, 새 세션에서 이 파일들을 읽으면 이전 작업을 바로 이어갈 수 있어요. 클로드에게 "dev/active/ 폴더 읽어봐"라고 하면 끝이에요.

7. 커뮤니티 반응과 파급 효과

이 Reddit 글과 GitHub 레포의 반응은 폭발적이었어요:

왜 이렇게 반응이 컸을까요?

사실 클로드 코드의 스킬, 훅, 에이전트 기능은 공식 문서에도 잘 설명돼 있어요. 하지만 문제는 **"그래서 실제로 어떻게 조합해서 쓰는 건데?"**에 대한 답이 없었다는 거예요. 이 레포는 그 빈칸을 메워준 거죠. 이론이 아니라 6개월 실전에서 검증된 조합이니까요.

비슷한 시기에 다른 유용한 레포들도 등장했어요:

다만 diet103의 레포가 특별한 이유는 인프라 아키텍처에 집중했다는 거예요. 다른 레포들이 "이렇게 써보세요" (사용법)에 집중했다면, 이건 "이렇게 구축하세요" (시스템)에 집중한 거예요.

8. 솔직한 평가: 좋은 점과 아쉬운 점

좋은 점

실전 검증됨. 6개월, 5만 줄, 마이크로서비스 6개. 이론이 아니라 매일 쓰면서 다듬은 패턴이에요. 이 차이는 커요. 이론적으로 멋진 구조와 실제로 작동하는 구조는 다르거든요.

30분이면 기본 세팅 가능. 가이드가 Phase 1~4로 나뉘어 있고, 필수 훅 2개 세팅(Phase 1)은 15분이면 돼요. 전체 세팅도 30분 안에 끝나요.

모듈화 철학이 탄탄. 500줄 규칙, 점진적 공개, 훅 기반 자동화 — 각 요소가 유기적으로 연결돼 있어요. 하나만 가져다 써도 되고, 전체를 도입해도 돼요.

MIT 라이선스. 상업적으로도 자유롭게 쓸 수 있어요.

통합 가이드가 친절. CLAUDE_INTEGRATION_GUIDE.md에 "먼저 프로젝트 구조를 물어보라", "pathPatterns을 반드시 수정하라" 같은 실수 방지 가이드가 있어요.

아쉬운 점

TypeScript/Express/Prisma 환경에 최적화. Python/Django, Go, Java/Spring 같은 다른 스택이면 백엔드/프론트엔드 스킬은 상당한 커스터마이징이 필요해요. 통합 가이드에서도 3가지 옵션을 제시하긴 해요: (1) 기존 스킬 적응, (2) 패턴만 추출, (3) 참고용으로만 사용.

settings.json은 절대 그대로 못 씀. 도메인, MCP 서버 목록, 디렉토리 구조가 예제용 블로그 도메인으로 돼 있어요. 그대로 복사하면 오작동해요.

Stop 훅은 위험할 수 있어요. tsc-check나 trigger-build-resolver 같은 Stop 훅은 특정 모노레포 구조를 가정하고 있어요. 잘못 설정하면 클로드 코드 워크플로우가 블로킹될 수 있어요. 이 개발자도 "선택적 훅은 테스트 없이 복사하지 마세요"라고 경고하고 있어요.

초보자에겐 진입장벽 있음. 훅, 스킬, 에이전트, skill-rules.json의 트리거 시스템 — 이 개념들을 이미 알고 있어야 제대로 활용할 수 있어요. 클로드 코드를 처음 쓰는 분이라면 먼저 공식 문서나 기본 사용법부터 익히는 게 좋아요.

레포가 더 이상 업데이트되지 않아요. 마지막 푸시가 2025년 10월 31일이에요. 클로드 코드는 계속 업데이트되고 있으니, 일부 패턴은 현재 버전에서 다르게 작동할 수 있어요.

9. 우리가 가져다 쓸 수 있는 것들

이 레포의 모든 걸 도입할 필요는 없어요. 핵심만 골라서 가져다 쓰면 돼요.

바로 적용 가능 (커스터마이징 거의 불필요)

적응 후 적용 가능 (약간의 커스터마이징)

참고만 하면 될 것 (다른 스택이라면)

10. 더 큰 그림: 클로드 코드 생태계의 방향

이 레포가 보여주는 건 단순한 팁 모음이 아니에요. 클로드 코드가 "도구"에서 "개발 플랫폼"으로 진화하고 있다는 신호예요.

생각해보면, 이 개발자가 만든 건 사실상 **"클로드 코드 위에 올린 개발 인프라"**예요:

이건 IDE 플러그인이나 린트 규칙을 세팅하는 것과 비슷한 레벨의 인프라 작업이에요. 예전에는 ESLint 규칙 세팅하고, CI/CD 파이프라인 만들고, 코드 리뷰 체크리스트 정리하는 게 "개발 인프라"였잖아요. 이제 거기에 "AI 에이전트 인프라"가 추가된 거예요.

앞으로 이런 .claude/ 디렉토리 구조가 .github/ 디렉토리처럼 프로젝트의 표준 구성 요소가 될 수도 있어요. 실제로 Anthropic 공식 문서에서도 스킬과 훅 시스템을 점점 강화하고 있고요.

결국 이 글이 말하고 싶은 건 하나예요. 클로드 코드는 날것 그대로 써도 강력하지만, 인프라를 갖추면 차원이 달라진다는 거예요. 마치 Git을 쓸 줄 아는 것과, Git + CI/CD + 코드 리뷰 프로세스를 갖추는 것의 차이처럼요.

30분이면 기본 세팅이 끝나요. 오늘 한번 만져보는 건 어때요?

이런 정보와 실전 AI 팁과 코드를 얻고 싶다면?

AI 인사이더 클럽에 들어와 주세요!