diet103/claude-code-infrastructure-showcase

실제 운영 환경에서 검증된 Claude Code 인프라 큐레이션 참조 라이브러리.

복잡한 TypeScript 마이크로서비스 (Microservices) 프로젝트를 6개월 동안 실제로 관리하며 탄생한 이 쇼케이스는, "기술이 자동으로 활성화되지 않는" 문제를 해결하고 Claude Code를 엔터프라이즈 개발 규모로 확장할 수 있는 패턴과 시스템을 제공합니다.

이것은 작동하는 애플리케이션이 아니라, 참조 라이브러리입니다. 필요한 부분을 귀하의 프로젝트에 복사하여 사용하세요.

다음 항목을 위한 운영 환경 검증 인프라:

• ✅ 훅 (Hooks)을 통한 기술 자동 활성화 (Auto-activating skills)
• ✅ 모듈형 기술 패턴 (Modular skill pattern) (점진적 공개를 적용한 500라인 규칙)
• ✅ 복잡한 작업을 위한 특화된 에이전트 (Specialized agents)
• ✅ 컨텍스트 리셋 (Context resets) 상황에서도 유지되는 개발 문서 시스템 (Dev docs system)
• ✅ 일반적인 블로그 도메인을 사용한 포괄적인 예시 (Comprehensive examples)

구축에 소요된 시간: 6개월간의 반복 작업
프로젝트 통합에 소요되는 시간: 15~30분

Claude: AI 보조 설정에 맞춘 단계별 통합 지침을 확인하려면 CLAUDE_INTEGRATION_GUIDE.md를 읽으세요.

혁신적인 기능: 실제로 필요할 때 활성화되는 기술 (Skills).

필요한 사항:

• 기술 활성화 훅 (2개 파일)
• 귀하의 업무와 관련된 한두 개의 기술
• 15분

기술 카탈로그를 살펴보고 필요한 것을 복사하세요.

사용 가능 항목:

• backend-dev-guidelines: Node.js/Express/TypeScript 패턴
• frontend-dev-guidelines: React/TypeScript/MUI v7 패턴
• skill-developer: 기술 생성을 위한 메타 기술 (Meta-skill)
• route-tester: 인증된 API 라우트 테스트
• error-tracking: Sentry 통합 패턴

복잡한 작업을 위한 10개의 운영 환경 검증 에이전트:

• 코드 아키텍처 리뷰
• 리팩토링 (Refactoring) 지원
• 문서 생성
• 에러 디버깅 (Error debugging)
• 기타 등등...

문제점: Claude Code 기술들이 그냥 방치되어 있습니다. 사용자가 직접 사용해야 한다는 것을 기억해야 합니다.

해결책: 다음과 같은 기능을 수행하는 UserPromptSubmit 훅:

• 프롬프트 (Prompts) 분석
• 파일 컨텍스트 (File context) 확인
• 관련 기술을 자동으로 제안
• skill-rules.json 설정을 통해 작동

결과: 스킬은 당신이 기억할 때가 아니라, 필요할 때 활성화됩니다.

이것들은 이론적인 예시가 아닙니다. 다음 환경에서 추출된 실제 사례입니다:

• ✅ 운영 환경(production)의 마이크로서비스 (microservices) 6개
• ✅ 50,000줄 이상의 TypeScript 코드
• ✅ 복잡한 데이터 그리드(data grids)를 포함한 React 프론트엔드
• ✅ 정교한 워크플로 엔진 (workflow engine)
• ✅ 6개월간의 일상적인 Claude Code 사용 경험

이 패턴들이 작동하는 이유는 실제 문제를 해결했기 때문입니다.

대규모 스킬은 컨텍스트 제한(context limits)에 걸립니다. 해결책은 다음과 같습니다:

skill-name/
SKILL.md # 500줄 미만, 상위 수준 가이드 (high-level guide)
resources/
...

점진적 공개 (Progressive disclosure): Claude는 메인 스킬을 먼저 로드하고, 리소스는 필요할 때만 로드합니다.

.claude/
├── skills/ # 5개의 운영 스킬
│ ├── backend-dev-guidelines/ (12개의 리소스 파일)
...

스킬 (Skill)	라인 수	목적	최적 용도
skill-developer	426	스킬 생성 및 관리	메타 개발 (Meta-development)
backend-dev-guidelines	304	Express/Prisma/Sentry 패턴	백엔드 API
frontend-dev-guidelines	398	React/MUI v7/TypeScript	React 프론트엔드
route-tester	389	인증된 경로 테스트	API 테스트
error-tracking	~250	Sentry 통합	에러 모니터링

모든 스킬은 모듈형 패턴 (modular pattern)을 따릅니다 - 점진적 공개를 위해 메인 파일과 리소스 파일로 구성됩니다.

훅 (Hook)	유형 (Type)	필수 여부?	커스텀 가능 여부
skill-activation-prompt	UserPromptSubmit	✅ 예	✅ 필요 없음
...

두 가지 필수 훅(hooks)으로 시작하세요 - 이 훅들은 스킬 자동 활성화를 가능하게 하며 즉시 작동합니다.

독립형 - 복사해서 바로 사용하세요!

에이전트 (Agent)	목적
code-architecture-reviewer	아키텍처 일관성을 위한 코드 리뷰
...
명령어 (Command)	목적
---	---
/dev-docs	구조화된 개발 문서 생성
...

시스템 구조:

skill-activation-prompt 훅은 모든 사용자 프롬프트에서 실행됩니다.

• skill-rules.json에서 트리거 패턴을 확인합니다.
• 관련 스킬을 자동으로 제안합니다.
• 스킬은 필요할 때만 로드됩니다.

이것은 Claude Code 스킬의 가장 큰 문제인 '스스로 활성화되지 않는다'는 점을 해결합니다.

문제점 (Problem): 대규모 스킬은 컨텍스트 제한 (context limits)에 걸립니다.

해결책 (Solution): 모듈형 구조 (Modular structure)

• 메인 SKILL.md < 500행 (개요 + 네비게이션)
• 리소스 파일 (Resource files) 각 < 500행 (심층 분석)
• Claude가 필요에 따라 점진적으로 로드

예시 (Example): backend-dev-guidelines는 라우팅 (routing), 컨트롤러 (controllers), 서비스 (services), 리포지토리 (repositories), 테스트 (testing) 등을 다루는 12개의 리소스 파일을 가지고 있습니다.

문제점 (Problem): 컨텍스트 리셋 (Context resets) 시 프로젝트 컨텍스트를 상실합니다.

해결책 (Solution): 3개 파일 구조 (Three-file structure)

[task]-plan.md

• 전략적 계획 (Strategic plan)

[task]-context.md

• 주요 결정 사항 및 파일 (Key decisions and files)

[task]-tasks.md

• 체크리스트 형식 (Checklist format)

작동 방식: /dev-docs 슬래시 명령어 (slash command)를 사용하여 이를 자동으로 생성할 수 있습니다.

포함된 settings.json은 예시일 뿐입니다:

• 중단 훅 (Stop hooks)은 특정 모노레포 (monorepo) 구조를 참조합니다.
• 서비스 이름 (blog-api 등)은 예시입니다.
• MCP 서버는 사용자의 설정에 존재하지 않을 수 있습니다.

사용 방법:

• UserPromptSubmit 및 PostToolUse 훅만 추출하세요.
• 중단 훅 (Stop hooks)은 커스텀하거나 건너뛰세요.
• 사용자의 설정에 맞춰 MCP 서버 목록을 업데이트하세요.

스킬은 일반적인 블로그 예시 (Post/Comment/User)를 사용합니다:

• 이것들은 교육용 예시이며 요구 사항이 아닙니다. 패턴은 모든 도메인 (이커머스, SaaS 등)에서 작동합니다.
• 패턴을 비즈니스 로직에 맞게 조정하세요.

일부 훅은 특정 구조를 기대합니다:

tsc-check.sh는 서비스 디렉토리를 기대합니다. 사용자의 프로젝트 레이아웃에 따라 커스텀하세요.

권장 접근 방식:

• skill-activation-prompt 훅을 복사하세요.

• post-tool-use-tracker 훅을 복사하세요.

• settings.json을 업데이트하세요.

• 훅 의존성 (hook dependencies)을 설치하세요.

• 관련 있는 스킬을 하나 선택하세요.

• 스킬 디렉토리를 복사하세요.

• skill-rules.json을 생성하거나 업데이트하세요.

• 경로 패턴 (path patterns)을 커스텀하세요.

• 파일을 편집하면 - 스킬이 활성화되어야 합니다.

• 질문을 하면 - 스킬이 제안되어야 합니다.

• 필요에 따라 더 많은 스킬을 추가하세요.

• 유용하다고 생각되는 에이전트 (agents)를 추가하세요.

• 슬래시 명령어 (slash commands)를 추가하세요.

• 중단 훅 (Stop hooks)을 커스텀하세요 (고급).

통합 과정에서 문제가 발생했나요?

• CLAUDE_INTEGRATION_GUIDE.md를 확인하세요.
• Claude에게 질문하세요: "왜 [skill]이 활성화되지 않나요?"
• 프로젝트 구조와 함께 이슈 (issue)를 오픈하세요.

사용자의 통합을 도울 때:

CLAUDE_INTEGRATION_GUIDE.md를 먼저 읽으세요

• 프로젝트 구조에 대해 질문하기
• 맹목적으로 복사하지 말고 커스텀하기
• 통합 후 검증하기

❌ 스킬 (Skills)이 자동으로 활성화되지 않음 ❌ 어떤 스킬을 사용할지 기억해야 함 ❌ 대규모 스킬은 컨텍스트 제한 (Context limits)에 걸림 ❌ 컨텍스트 초기화 시 프로젝트 지식 손실 ❌ 개발 과정 전반의 일관성 부족 ❌ 매번 수동으로 에이전트 (Agent) 호출 필요

✅ 컨텍스트 (Context)를 기반으로 스킬이 스스로 제안됨 ✅ 훅 (Hooks)이 적절한 시점에 스킬을 트리거함 ✅ 모듈형 스킬로 컨텍스트 제한을 유지함 ✅ 개발 문서 (Dev docs)를 통해 초기화 후에도 지식 보존 ✅ 가드레일 (Guardrails)을 통한 일관된 패턴 유지 ✅ 에이전트가 복잡한 작업을 간소화함

이 내용이 유용했나요?

• ⭐ 이 저장소(repo)에 Star 누르기
• 🐛 이슈 (Issues) 보고 또는 개선 사항 제안하기
• 💬 자신만의 스킬/훅/에이전트 공유하기
• 📝 자신의 도메인 사례 기여하기

배경 (Background):
이 인프라스트럭처 (Infrastructure)는 제가 Reddit에 게시한