Claude Code
마스터 가이드

# 세션 1 (Writer) - 코드 작성
"@CLAUDE.md @src/auth/login.ts
로그인 기능을 구현해줘.
완료 후 변경된 파일 목록을 알려줘."

# 세션 2 (Reviewer) - 독립 리뷰
"다음 파일들을 코드 리뷰해줘:
@src/auth/login.ts @src/auth/session.ts

리뷰 체크리스트:
- [ ] 보안 취약점 (SQL injection, XSS, CSRF)
- [ ] 에러 처리 완결성
- [ ] 타입 안전성
- [ ] 성능 이슈 (N+1, 메모리릭)
- [ ] 테스트 커버리지

각 항목에 대해 파일명:라인번호로 구체적으로 지적해줘."

# API 계약 먼저 CLAUDE.md에 정의
## API Contract (세션 간 공유)
POST /api/auth/login
Request: { email: string, password: string }
Response: { token: string, user: User }
Error: { code: string, message: string }

# 세션 1 (Frontend)
"@CLAUDE.md의 API 계약에 맞게
로그인 폼 컴포넌트를 만들어줘.
실제 API 없이 mock으로 먼저 구현."

# 세션 2 (Backend) - 동시 진행
"@CLAUDE.md의 API 계약대로
POST /api/auth/login 엔드포인트를 구현해줘.
JWT 발급 + 비밀번호 bcrypt 검증 포함."

# 세션 3 (Test) - 동시 진행
"@CLAUDE.md의 API 계약 기반으로
로그인 기능 테스트를 먼저 작성해줘.
성공/실패/엣지케이스 모두 포함."}

# 세션 A - 접근법 1 (REST 방식)
"상품 검색 기능을 REST API로 구현해줘.
성능 목표: 100ms 이하 응답
방법 제약: REST + PostgreSQL 전문검색"

# 세션 B - 접근법 2 (GraphQL + Elasticsearch)
"상품 검색 기능을 GraphQL로 구현해줘.
성능 목표: 100ms 이하 응답
방법 제약: GraphQL + Elasticsearch"

# 비교 세션 - 결과물 평가
"두 구현의 장단점을 비교해줘:
@approach-a/search.ts @approach-b/search.ts

평가 기준:
- 성능 (벤치마크)
- 유지보수성
- 확장성
- 팀 학습 곡선"

# MIGRATION.md (세션 간 공유 체크포인트)
# JavaScript → TypeScript 마이그레이션

## 완료
- [x] src/utils/ (2024-01-15)
- [x] src/components/common/ (2024-01-16)

## 진행 중
- [ ] src/components/forms/

## 대기
- [ ] src/pages/
- [ ] src/hooks/

---
# 세션 1 (분석)
"@src/ 전체를 스캔해서 TypeScript 마이그레이션
난이도를 평가해줘. MIGRATION.md를 업데이트해."

# 세션 2~N (각 모듈 마이그레이션)
"@MIGRATION.md 확인 후, 다음 미완료 모듈을
TypeScript로 마이그레이션해줘.
완료 후 MIGRATION.md 체크박스 업데이트."

# 세션 1 (Red - 테스트 작성)
"calculateDiscount() 함수의 테스트를 먼저 작성해줘.
아직 구현체는 없어.
테스트 케이스:
- 10만원 이상 구매: 10% 할인
- VIP 회원: 추가 5% 할인
- 중복 적용: 최대 15%
- 엣지: 음수 금액, null 입력

모든 테스트가 실패하는 것을 확인해줘."

# 세션 2 (Green - 구현)
"@tests/discount.test.ts 의 테스트를 모두 통과하는
calculateDiscount() 함수를 구현해줘.
지금은 테스트 통과에만 집중해."

# 세션 1 (Refactor - 리팩토링)
"@src/discount.ts 를 리팩토링해줘.
@tests/discount.test.ts 의 테스트는 모두 통과해야 해.
코드 가독성과 성능을 개선해."

# tmux 야간 작업 세션 설정
# 1. 현재 작업 커밋
git add -A && git commit -m "chore: 야간 작업 시작 전 체크포인트"

# 2. 새 tmux 세션 시작
tmux new-session -d -s night-work

# 3. Claude 자율 실행
tmux send-keys -t night-work "claude --dangerously-skip-permissions" Enter

# 4. 작업 지시 (tmux 창에서)
# 성공 기준과 체크포인트를 명시
"다음 작업을 자율적으로 완료해줘:
목표: src/components/ 전체를 TypeScript 마이그레이션

성공 기준:
- tsc --noEmit 에러 0개
- 기존 테스트 전부 통과
- 각 파일 완료 시 git commit

실패 시 중단 조건:
- 테스트 실패율 10% 초과 시 중단
- 의존성 변경이 필요하면 BLOCKER.md에 기록 후 중단

진행 상황은 PROGRESS.md에 기록해."

# 5. 아침에 확인
tmux attach -t night-work
git log --oneline -20
cat PROGRESS.md

# 1단계: 세션 1 (코드 작성)
git checkout -b feature/payment-gateway
# [코드 작성 완료]
git commit -m "feat: 결제 게이트웨이 초기 구현"

# 2단계: 세션 2 (보안 리뷰 전문)
"결제 관련 코드를 보안 관점에서 리뷰해줘:
@src/payment/gateway.ts @src/payment/webhook.ts

집중 확인 사항:
- API 키 노출 위험
- HTTPS 강제 여부
- 결제 금액 조작 가능성
- Webhook 서명 검증
- SQL/NoSQL Injection

보안 이슈를 severity별로 분류해서 SECURITY_REVIEW.md에 기록해."

# 3단계: 세션 3 (성능 리뷰 전문)
"결제 코드를 성능 관점에서 리뷰해줘:
@src/payment/

집중 확인:
- 동기/비동기 처리 최적화
- 불필요한 DB 쿼리
- 결제 타임아웃 처리
- 동시성 이슈 (이중 결제 방지)

결과를 PERFORMANCE_REVIEW.md에 기록해."

# 4단계: 이슈 수정 후 PR 생성
cat SECURITY_REVIEW.md PERFORMANCE_REVIEW.md
# [이슈 수정]
git commit -m "fix: 보안/성능 리뷰 반영"

# 공유 타입 패키지 (shared/types.ts)
# 모든 서비스가 이것을 참조
export interface User {
  id: string
  email: string
  role: 'admin' | 'user'
}

export interface Order {
  id: string
  userId: string
  items: OrderItem[]
  status: 'pending' | 'paid' | 'shipped'
}

---
# 터미널 1 - user-service 세션
cd ~/projects/user-service
claude
"@../shared/types.ts 를 참고해서
User 관련 CRUD API를 구현해줘."

# 터미널 2 - order-service 세션 (동시)
cd ~/projects/order-service
claude
"@../shared/types.ts 를 참고해서
Order 관련 CRUD API를 구현해줘.
User 조회는 user-service의 GET /users/:id 호출."

# 터미널 3 - api-gateway 세션 (동시)
cd ~/projects/api-gateway
claude
"@../shared/types.ts 를 참고해서
user-service와 order-service를 연결하는
API Gateway를 구현해줘."

# 통합 테스트 (별도 세션)
cd ~/projects
claude
"docker-compose.yml로 전체 서비스를 실행하고
E2E 통합 테스트를 작성해줘.
@user-service/openapi.yaml @order-service/openapi.yaml"

# CLAUDE.md
## 기술 스택
- TypeScript (strict 모드)
- ESLint + Prettier (기존 설정 유지)
- React 18 + Vite
- Tailwind CSS

## 코딩 컨벤션
- 함수 컴포넌트만 사용 (클래스 컴포넌트 금지)
- 파일명: PascalCase.tsx
- 커밋 메시지: Conventional Commits 형식

# 세션 중 모델 전환
/model claude-haiku-4-5     # 간단한 작업
/model claude-sonnet-4-6    # 일반 개발
/model claude-opus-4-6      # 복잡한 설계

# .claudeignore
node_modules/
dist/
build/
.git/
*.lock
coverage/
.next/
.turbo/
**/*.min.js
**/*.map

# Headless 모드 기본 사용
claude -p "이 PR의 코드를 리뷰해줘" --output-format json

# CI/CD 파이프라인 예시 (GitHub Actions)
- name: Claude 코드 리뷰
  run: |
    claude -p "변경된 파일에서 버그와 개선사항을 찾아줘: $(git diff HEAD~1)" \
      --output-format json \
      --max-turns 5 > review.json

# 반복 파일 처리 스크립트
for file in src/**/*.ts; do
  claude -p "이 파일에 JSDoc 주석을 추가해줘: $(cat $file)" > "$file.new"
done

# 터미널 기초 명령어 연습
pwd                    # 현재 위치 확인
ls                     # 현재 폴더 내용 보기
ls -la                 # 숨김 파일 포함 상세 보기
cd Desktop             # Desktop 폴더로 이동
cd ..                  # 상위 폴더로 이동
mkdir my-project       # 'my-project' 폴더 생성
cd my-project          # 방금 만든 폴더로 이동

이 코드의 보안 취약점을 OWASP Top 10 기준으로 점검해줘.
각 취약점의 위험도(상/중/하)와 구체적인 수정 코드를 함께 제시해.
발견하지 못한 취약점이 있다면 그 이유도 설명해.

이 코드의 성능 병목을 찾아줘.
특히 N+1 쿼리, 불필요한 리렌더링, 메모리 릭 패턴을 중점적으로 봐줘.
각 문제의 예상 성능 영향도와 최적화된 코드를 제시해.

이 코드 구조를 SOLID 원칙 관점에서 평가해줘.
현재 구조의 문제점과 6개월 후 기능이 3배로 늘었을 때 어떤 문제가 생길지 예측해줘.
리팩토링이 필요하다면 단계적 전환 계획도 제시해.

주니어 개발자가 이 코드를 6개월 후에 유지보수해야 한다면 어떤 부분이 혼란스러울까?
변수명, 함수명 중 의도가 불명확한 것을 모두 찾아 개선안을 제시해.
에러 핸들링이 누락된 경로도 찾아줘.

# .github/workflows/ai-code-review.yml
name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get changed files
        id: changed
        run: |
          git diff origin/${"{{ github.base_ref }}"}...HEAD \
            --name-only > changed_files.txt

      - name: Run Claude Code Review
        uses: anthropics/claude-code-action@beta
        with:
          anthropic_api_key: ${"{{ secrets.ANTHROPIC_API_KEY }}"}
          direct_prompt: |
            변경된 파일을 리뷰해줘.
            보안 취약점, 성능 문제, 명백한 버그를 중점으로.
            각 문제에 파일명:줄번호와 수정 제안을 포함해.