내가 프로덕션 수준의 Claude Code 설정을 구축하고 오픈 소스로 공개한 방법

나는 몇 달 동안 Claude Code를 진지하게 사용해 왔습니다. 그리고 계속해서 동일한 좌절감을 느꼈습니다:

• 세션 컨텍스트 (Session context)가 사라집니다. 다음 날 다시 시작하면 Claude는 모든 것을 잊어버린 상태입니다.
• 설정 (Config)이 한 대의 머신에만 존재합니다. 다른 머신으로 이동하면 처음부터 다시 구축해야 합니다.
• 훅 (Hooks)을 작성하면 나중에 사라집니다. 이를 보관할 단일 장소가 없습니다.
• Claude는 당신이 문제를 설명하기도 전에 코딩을 시작합니다.

그래서 나는 이 문제들을 해결하는 참조 아키텍처 (reference architecture)를 구축했습니다. 그리고 이를 오픈 소스로 공개했습니다.

이것은 무엇인가?

Claude Code Blueprint는 바로 복사해서 사용할 수 있는 파일들의 라이브러리입니다: CLAUDE.md, 훅 (hooks), 에이전트 (agents), 스킬 (skills), 그리고 규칙 (rules). 당신은 필요한 것만 자신의 프로젝트에 복사하면 됩니다. 그 이상은 필요 없습니다.

이것은 프레임워크 (framework)가 아닙니다. 래퍼 (wrapper)도 아닙니다. Claude Code가 동작하는 방식을 바꾸는 설정 파일 (configuration files)입니다.

12개의 에이전트 (agents) * 17개의 스킬 (skills) * 12개의 훅 (hooks) * 6개의 규칙 (rules)

시작하는 데 60초면 충분합니다:

ash curl -o CLAUDE.md https://raw.githubusercontent.com/faizkhairi/claude-code-blueprint/main/CLAUDE.md

가장 중요한 세 가지 규칙

CLAUDE.md에는 가장 흔한 AI 코딩 실수를 방지하는 세 가지 행동 규칙이 포함되어 있습니다:

1. 진단 우선 (Diagnose-First)

어떤 수정 사항을 작성하기 전에, Claude는 반드시 네 가지 확인 사항을 실행해야 합니다: git 상태 (git state), 에러 원인 (error source), 기존 억제 사항 (existing suppression), 최소 실행 가능한 진단 (minimum viable diagnosis). 이는 가장 흔한 낭비, 즉 이전 커밋에서 이미 해결된 문제에 대해 정교한 수정안을 만드는 일을 방지합니다.

2. 계획 우선 (Plan-First)

하나 이상의 파일에 영향을 미치는 모든 변경 사항은 계획 모드 (plan mode)를 거칩니다. 예외는 없습니다. Claude가 제안하고, 당신이 승인하면, 그 후에 실행합니다. 이는 Claude가 15개의 파일을 리팩터링 (refactor)하러 돌진하여 당신이 요청하지 않은 결과물을 만들어내는 패턴을 방지합니다.

3. 완료 후 검증 (Verify-After-Complete)

어떤 작업을 마친 후에도 Claude는 작업 유형에 적합한 검증 단계 (verification pass)를 실행합니다. API 엔드포인트인가요? 실제 URL로 curl 명령을 실행합니다. 설정 변경인가요? 값이 실제로 반영되었는지 확인합니다. 파일 편집인가요? 변경된 블록을 다시 읽습니다. 이것만으로도 당신이 발견하기 전에 상당한 비율의 오류를 잡아낼 수 있습니다.

메모리 시스템 (The Memory System)

이 부분이 제대로 구현하기 가장 어려운 부분이었습니다. Claude Code는 세션 간에 네이티브한 지속성 메모리 (persistent memory)를 가지고 있지 않습니다. 이 설계도 (blueprint)는 파일 기반 메모리 시스템을 통해 이 문제를 해결합니다.

• 세션별 컨텍스트 (Per-session context): 세션 종료 시 저장되고 세션 시작 시 로드됩니다.
• 사용자 메모리 (User memories): 역할, 선호도, 피해야 할 사항들
• 프로젝트 메모리 (Project memories): 진행 중인 작업, 결정 사항, 마감 기한
• 피드백 메모리 (Feedback memories): 과거 세션에서의 수정 사항

모든 세션은 이 파일들을 읽어들이는 load-session 훅 (hook)과 함께 시작됩니다. 모든 세션은 이 파일들을 기록하는 save-session 훅과 함께 종료됩니다. 그 결과: Claude는 며칠이 지난 후라도 이전에 멈췄던 지점부터 다시 시작할 수 있습니다.

에이전트 (Agents): 단순 작업은 Sonnet, 추론은 Opus

제가 고생하며 배운 것 중 하나는 모든 것을 비싼 모델로 실행하면 단순 반복 작업에 할당량 (quota)을 낭비하게 된다는 점입니다.

이 설계도에는 각각 적절한 모델 계층 (model tier)에 고정된 12개의 에이전트가 포함되어 있습니다:

• Opus: 추론 (reasoning), 계획 (planning), 아키텍처 리뷰
• Sonnet: 단순 작업 (mechanical work): 테스트 작성, 문서 생성, grep 스윕 실행, 리팩터링 (refactoring)

메인 Claude Code 세션 (Opus)이 오케스트레이션 (orchestration)을 담당합니다. Sonnet 서브 에이전트들이 대부분의 작업을 수행합니다. 당신의 비싼 할당량은 그것이 꼭 필요한 결정적인 판단에 사용됩니다.

스킬 (Skills): 반복 가능한 워크플로우

스킬은 다단계 워크플로우 (multi-step workflows)를 호출하는 슬래시 명령어 (slash commands)입니다. 이 설계도에는 17개가 포함되어 있습니다:

스킬	기능
...

훅 (Hooks): 토큰 비용 제로

훅은 Claude의 컨텍스트 윈도우 (context window) 외부에서 실행됩니다. 토큰 비용이 전혀 들지 않습니다. 가드레일 (guardrails)을 추가하기에 가장 레버리지가 높은 지점입니다.

이 설계도에는 12개가 포함되어 있습니다:

• pre-commit-secret-scan: 하드코딩된 자격 증명 (credentials)이 포함된 커밋을 차단합니다.
• protect-config: 확인 절차 없이 CLAUDE.md 및 훅 (hook) 파일이 수정되는 것을 차단합니다.
• cost-tracker: 세션당 토큰 사용량을 추적합니다.
• session-checkpoint: N분마다 자동으로 상태 (state)를 저장합니다.
• block-git-push: 푸시 정책을 강제합니다 (피처 브랜치만 허용, main 브랜치 직접 푸시 금지).

대상 (Who Is It For?)

더욱 신뢰할 수 있고 일관된 동작을 원하는 Claude Code 사용자라면 어떤 개발자든 해당됩니다. 이 설계도 (blueprint)는 프레임워크에 구애받지 않습니다 (framework-agnostic). 즉, 코드가 아닌 Claude의 동작을 설정합니다.

가이드가 포함된 시작을 원하신다면 네 가지 프리셋 (presets)이 있습니다:

ash ./setup.sh --preset=minimal # CLAUDE.md + 핵심 훅 3개 ./setup.sh --preset=standard # + 에이전트 (agents) + 스킬 (skills) ./setup.sh --preset=full # 모든 기능

번역 (Translations)

README와 설정 문서는 일본어, 한국어, 중국어로 제공됩니다. 커뮤니티의 기여로 제작되었습니다.

가져오기 (Get It)

GitHub: github.com/faizkhairi/claude-code-blueprint

MIT 라이선스입니다. 필요한 부분만 가져가세요. 나머지는 남겨두셔도 됩니다.

도움이 되었다면, 스타 (star)를 눌러 다른 사람들이 찾을 수 있도록 도와주세요.