# Claude Code 마스터 가이드 — 핵심 지식 정리

> 출처: "Claude Code 마스터하기" (황민호, 2025)
> GitHub: revfactory/claude-code-mastering
> 원본 클론: /tmp/claude-code-mastering/book/
> 작성일: 2026-03-01

---

## 1. EPCC 워크플로우 (Ch.7) — 가장 핵심

**Explore → Plan → Code → Commit** 순환 사이클.
우리 시스템의 보리스 워크플로우(Research→Plan→Annotate→Todo→Implement→Feedback)와 유사하지만, EPCC는 더 짧은 반복 단위.

### Explore (탐색)
- 코드베이스 아키텍처 분석 (고수준 → 세부)
- 기술 스택, 데이터 흐름, 의존성 방향 파악
- 기술 부채 식별, 성능 병목 사전 탐지
- **"충분한 이해 없이 코딩 시작 = 잘못된 설계 + 기술 부채"**

### Plan (계획)
- 구현 전략 수립 + 작업 분해
- 각 단계가 독립적으로 테스트 가능해야 함
- 리스크 평가: 기존 코드에 미칠 영향 분석

### Code (코딩)
- 스켈레톤(인터페이스+빈 메서드) → 핵심 로직 → 통합 순서
- TDD 적용: Red(실패 테스트) → Green(최소 구현) → Refactor(개선)

### Commit (커밋)
- 커밋 전 자동 검증: 테스트, 린팅, 타입체크, 커버리지
- Conventional Commits 형식

**우리 시스템 적용**: dispatch 위임 시 EPCC 단계를 팀장 프롬프트에 내장 가능.

---

## 2. CLAUDE.md 설계 전략 (Ch.4) — 우리가 이미 실천 중

### 핵심 원칙
- **README.md ≠ CLAUDE.md**: README는 사람용, CLAUDE.md는 AI용
- 우선순위 구조: 중요 규칙(항상 준수) → 일반 가이드 → 권장사항
- 프로젝트 특화 지식: 도메인 용어, 비즈니스 규칙 포함
- **버전 관리**: CLAUDE.md 자체도 변경 이력 추적

### 포함해야 할 내용
1. 프로젝트 아키텍처 (패턴, 스택, 디렉토리 구조)
2. 코딩 스타일 (명명규칙, Import 순서, 함수 길이 제한)
3. 개발 환경 (필수 도구, 초기 설정 스크립트, Git Hooks)
4. 팀 협업 규칙 (PR 작성, 리뷰 체크리스트, 브랜치 전략)
5. 코드 품질 기준 (함수 50줄 이하, 매개변수 3개 이하, 복잡도 10 이하)

### 우리 시스템과의 비교
- 이미 CLAUDE.md 경량화 완료 (200줄 이하 원칙)
- Skills/Hooks/AGENTS.md 분리 전략 적용 중
- **개선점**: 프로젝트별 CLAUDE.md에 도메인 용어 섹션 추가 고려

---

## 3. 멀티태스킹과 병렬 처리 (Ch.8) — 우리 아키텍처의 근간

### 멀티 인스턴스 전략
- 각 인스턴스에 **특화된 역할** 부여 (프론트/백엔드/DevOps/QA/통합)
- 컨텍스트 스위칭 비용 절감 = 각 인스턴스가 전문 영역만 담당
- **Integration Hub (인스턴스 #5)**: 전체 아키텍처 일관성 조정자

### Git Worktree 활용
- 브랜치별 격리된 개발 환경
- 각 Worktree에 특화된 CLAUDE.md 설정
- 워크트리 자동 생성/정리 스크립트

### 컨텍스트 관리
- 작업 중단 시 반드시 상태 요약 저장
- 공유 문서(shared/context.md)로 인스턴스 간 정보 동기화
- 정기 동기화 포인트 설정

### 우리 시스템과의 비교
- **우리는 이미 5인스턴스 구조**: 아누(오케스트레이터) + 1팀 + 2팀 + 3팀 + 횡단조직
- 가이드의 "Integration Hub" = 아누(개발실장) 역할과 동일
- **차이점**: 가이드는 같은 개발자가 여러 터미널. 우리는 별도 봇이 독립적으로 작업.
- **개선점**: 인스턴스별 CLAUDE.md 특화 → 이미 팀별 CLAUDE.md로 적용 중

---

## 4. Headless 모드와 CI/CD 자동화 (Ch.9)

### Headless 모드 핵심
```bash
claude --headless --output-format json "분석 요청"
```
- 환경별 적응: production(최고품질)/staging(표준)/development(빠른피드백)
- 조건부 실행: 브랜치/변경사항 분석 → 품질 검증 수준 자동 결정
- 품질 게이트: pass/fail + 상세 개선 방안 JSON 출력

### CI/CD 통합 패턴
- PR 자동 리뷰 (보안, 성능, 아키텍처, 테스트, 문서화 병렬 분석)
- 배포 전 종합 위험도 평가
- 문서 자동 생성 + 배포

### 우리 시스템 적용 가능성
- dispatch.py로 위임 시 headless 모드 검증 단계 추가 가능
- 마아트(QC센터)의 독립 검증에 headless 패턴 활용 가능
- 야누스(DevOps)의 배포 파이프라인에 품질 게이트 통합 가능

---

## 5. GitHub Actions + Claude Code Action (Ch.11)

### 핵심 개념
- PR에서 `@claude` 멘션 → 코드 분석/수정/커밋 자동화
- 이벤트 기반: PR, Issue, 코멘트, 스케줄, 수동 트리거
- 능력: 코드 분석, 버그 수정, 리팩토링, 테스트 작성, 문서화
- 브랜치 관리: 이슈→새 브랜치, 열린 PR→직접 푸시, 닫힌 PR→새 브랜치

### 보안 설정
- AWS Bedrock / Google Vertex AI 멀티 프로바이더 지원
- 시크릿 관리, 권한 최소화 원칙
- 감사 로그와 활동 추적

### 우리 시스템 적용
- 현재 GitHub Actions 미사용 → 향후 프로젝트에서 도입 검토
- Claude Code Action은 레드팀(로키)의 보안 자동 스캔에 활용 가능

---

## 6. 프레임워크별 베스트 프랙티스 (Ch.5)

### React/Next.js
- 함수형 컴포넌트 + TypeScript + Storybook 필수
- 상태 관리: 로컬(useState) / 서버(React Query) / 전역(Zustand) 분리
- 성능: React.memo, useMemo, useCallback, 코드 스플리팅, 가상 스크롤
- Next.js: App Router, Server Components, ISR

### Node.js/Express
- Controller-Service-Repository 계층 아키텍처
- JWT 인증 + RBAC + Rate Limiting
- Prisma ORM, Redis 캐싱

### Python/Django
- 앱별 기능 분리, 앱당 최대 10개 모델
- ViewSet + Serializer, Celery 비동기 태스크
- Factory Boy 테스트 데이터, 커버리지 80%+

### 모바일 (React Native / Flutter)
- MVVM 패턴, 가상화 리스트, 60fps 애니메이션
- 플랫폼별 스타일 분기

### 데이터 과학
- 노트북은 실험용, 프로덕션은 .py
- MLflow 실험 추적, 모델 레지스트리
- 데이터 드리프트 탐지, 자동 재학습

---

## 7. 팀 도입 전략 (Ch.12)

### 조직 성숙도 5단계
1. **기초**: 개별 작업 중심 → 개인 역량 강화 우선
2. **발전**: 팀워크 시작 → 팀 규칙/워크플로우 구축
3. **성숙**: 체계적 프로세스 → 고급 자동화+측정
4. **최적화**: 데이터 기반 → AI-native 워크플로우
5. **혁신**: 지속적 학습 → 실험적 기술 리더

### 규모별 전략
- **스타트업 (3-10명)**: 1주 전체 온보딩, MVP 속도 극대화
- **성장기 (50-200명)**: 표준화, 계층별 역할 정의, 교육 체계
- **대기업 (1000+)**: 거버넌스, 보안 컴플라이언스, 변화 관리

### 우리 시스템 위치
- 성숙도 4단계 수준 (AI-native 워크플로우 구축 중)
- 이미 멀티봇 + 위임 + QC 독립 검증 체계 보유
- 다음 단계: 데이터 기반 성과 측정 (task-timer 활용)

---

## 8. 프롬프트 엔지니어링 핵심 (Ch.3)

### 효과적인 요청 패턴
1. **구체적 요청**: "UserService 클래스에 이메일 검증 메서드를 추가해줘"
2. **탐색적 질문**: "이 프로젝트에서 인증은 어떻게 처리되고 있어?"
3. **복합 작업**: "버그를 찾아서 수정하고, 테스트도 작성한 다음, 커밋 메시지까지 만들어줘"

### 코드 수정 4가지 패턴
1. **현대화**: var→const/let, 콜백→async/await
2. **리팩토링**: 긴 함수 분리, 중복 제거, 조건문 단순화
3. **기능 추가**: 에러 처리, 유효성 검사, 로딩 상태
4. **버그 수정**: null 참조, 메모리 누수, 경쟁 조건

### 컨텍스트 유지 팁
- 체크포인트 생성: 각 단계 완료 시 진행 상황 요약
- 명확한 단계 구분: 번호/라벨로 작업 단계 명시
- 중요 결정사항은 별도 문서로 저장

---

## 9. 실전 프로젝트 구축 (Ch.10)

### "CollabSpace" 사례 — 엔터프라이즈 협업 플랫폼
- WebSocket 실시간 통신 (1000+ 동시 사용자)
- 마이크로서비스: Auth/User/Workspace/Project/Chat/File/Search/Notification/Realtime/Analytics/Audit/Email
- 데이터 계층: PostgreSQL + Redis + Elasticsearch + MinIO + Kafka + TimescaleDB + Vault
- 아키텍처 원칙: DDD, 관심사 분리, 느슨한 결합, 높은 응집도

---

## 10. 핵심 교훈 (결론)

1. **AI는 증강(Augmentation)이지 대체(Replacement)가 아니다**
   - 인간: 문제 정의, 요구사항, 창의적 해결책
   - AI: 빠른 구현, 패턴 인식, 최적화 제안

2. **지속적 학습이 핵심**
   - 기초 원리(알고리즘, 시스템 설계)는 여전히 중요
   - 프롬프트 엔지니어링 + 도메인 전문 지식이 새 역량

3. **품질은 자동화의 핵심**
   - AI 생성 코드도 반드시 테스트
   - 인간의 검증은 여전히 필수

4. **팀 문화가 성공을 좌우**
   - 심리적 안전: 실험과 실패 허용
   - 지식 공유 + 지속적 개선

---

## 우리 시스템에 적용할 액션 아이템

### 즉시 적용 가능
- [ ] 프로젝트별 CLAUDE.md에 도메인 용어 섹션 추가 (Phase 0 템플릿에 반영)
- [ ] dispatch 프롬프트에 EPCC 단계 힌트 내장
- [ ] 팀장 프롬프트에 "탐색→계획→구현→검증" 명시

### 중기 검토
- [ ] 마아트(QC)에 headless 모드 패턴 적용 (자동 품질 게이트)
- [ ] task-timer 데이터 기반 팀 성과 대시보드 구축
- [ ] GitHub Actions + Claude Code Action 도입 (프로젝트 시작 시)

### 장기 비전
- [ ] 조직 성숙도 5단계 달성 (AI-native → 혁신 리더)
- [ ] 데이터 기반 프로세스 최적화 (자동 병목 탐지)