8장: Claude Code를 활용한 개발 자동화

Claude Code의 핵심 장점:
 
  1. 프로젝트 전체 맥락 이해
     - 파일 시스템을 직접 탐색하여 코드 구조 파악
     - 수천 개의 파일에 걸친 맥락 수집
     - 의존성 관계와 아키텍처 패턴 분석
 
  2. 자율적 작업 수행
     - 여러 파일에 걸친 변경을 자율적으로 수행
     - 빌드, 테스트 실행 후 에러 자동 수정
     - Git 명령어를 활용한 버전 관리
 
  3. CLAUDE.md 기반 컨텍스트
     - 프로젝트별 지침을 파일로 관리
     - 팀 컨벤션, 아키텍처 결정을 지속적으로 참조
     - 새 팀원에 대한 온보딩 문서 역할
 
  4. 확장성
     - MCP 서버를 통한 외부 도구 통합
     - 커스텀 슬래시 명령어
     - 훅(Hooks)을 통한 자동화

# 프로젝트명 - CLAUDE.md
 
## 프로젝트 개요
프로젝트의 목적과 핵심 기능을 간결하게 설명
 
## 기술 스택
사용 중인 프레임워크, 라이브러리, 도구 목록
 
## 프로젝트 구조
디렉토리 구조와 각 디렉토리의 역할
 
## 개발 명령어
빌드, 테스트, 린트, 배포 명령어
 
## 코딩 컨벤션
팀의 코딩 규칙과 패턴
 
## 아키텍처 결정
주요 아키텍처 결정과 그 이유
 
## 주의 사항
알려진 제약 조건, 주의해야 할 패턴

# OrderService - CLAUDE.md
 
## 프로젝트 개요
주문 관리 마이크로서비스. 주문 생성, 조회, 취소, 결제 연동을 담당.
 
## 기술 스택
- Runtime: Node.js 20 + TypeScript 5.4
- Framework: NestJS 10
- Database: PostgreSQL 16 + Prisma ORM
- Message Queue: RabbitMQ
- Cache: Redis
- Test: Vitest + Supertest
 
## 개발 명령어
- pnpm dev: 개발 서버 실행
- pnpm build: 프로덕션 빌드
- pnpm test: 전체 테스트 실행
- pnpm test:e2e: E2E 테스트 실행
- pnpm prisma:migrate: DB 마이그레이션
- pnpm lint: ESLint + Prettier 검사
 
## 코딩 컨벤션
- 함수 선언: function 키워드 사용
- 에러 처리: AppError 클래스 상속, 에러 코드 반드시 포함
- 네이밍: camelCase (변수/함수), PascalCase (클래스/타입)
- 파일: kebab-case.ts
- 모든 공개 함수에 JSDoc 필수
- 비즈니스 로직은 Service 계층에만 존재
- Controller는 요청 검증과 응답 변환만 담당
 
## 아키텍처
- Clean Architecture: Controller -> Service -> Repository
- CQRS: 조회와 명령을 분리 (QueryService / CommandService)
- Event-driven: 주문 상태 변경 시 이벤트 발행 (RabbitMQ)

좋은 지시의 예:
 
  "주문 취소 API를 추가해 줘.
   - PATCH /api/orders/:id/cancel
   - 취소 가능 상태: PENDING, CONFIRMED
   - 이미 취소/완료된 주문은 409 에러
   - 취소 시 order.cancelled 이벤트 발행
   - 기존 createOrder의 패턴을 따라 구현해 줘"
 
  이 지시가 효과적인 이유:
  1. 엔드포인트 명세가 구체적
  2. 비즈니스 규칙이 명확
  3. 에러 시나리오가 정의됨
  4. 참조할 기존 패턴을 제시

나쁜 지시의 예:
 
  "주문 취소 기능 만들어 줘"
 
  이 지시가 비효과적인 이유:
  1. API 명세가 없음
  2. 어떤 상태에서 취소 가능한지 불분명
  3. 에러 처리 기준이 없음
  4. 기존 패턴 참조가 없음

리팩터링 지시 템플릿:
 
  "다음 리팩터링을 수행해 줘:
 
  대상: [파일 또는 모듈]
  목표: [달성하고자 하는 것]
  제약:
    - 공개 API는 변경하지 않을 것
    - 기존 테스트가 모두 통과할 것
    - [추가 제약 조건]
  참고:
    - [관련 파일이나 패턴]"

"src/services/order-service.ts 파일을 리팩터링해 줘.
 
  대상: OrderService 클래스 (현재 600줄)
  목표: CQRS 패턴에 따라 조회와 명령을 분리
  결과물:
    - src/services/order-query.service.ts (조회 로직)
    - src/services/order-command.service.ts (명령 로직)
  제약:
    - Controller의 기존 메서드 시그니처는 유지
    - 기존 테스트가 모두 통과해야 함
    - OrderModule의 DI 설정도 함께 수정"

디버깅 지시 예시:
 
  "다음 에러가 발생합니다. 원인을 찾아 수정해 줘.
 
  에러 메시지:
  TypeError: Cannot read property 'status' of undefined
    at OrderService.cancelOrder (order-service.ts:142)
    at OrderController.cancel (order-controller.ts:58)
 
  재현 조건:
  - POST /api/orders/invalid-id/cancel 호출 시 발생
  - 존재하지 않는 주문 ID로 요청할 때
 
  기대 동작:
  - 404 Not Found 에러를 반환해야 합니다"

훅의 동작 시점:
 
  PreToolUse:
    - Claude Code가 도구를 사용하기 전에 실행
    - 파일 수정 전 백업, 위험한 명령어 차단
 
  PostToolUse:
    - Claude Code가 도구를 사용한 후에 실행
    - 파일 수정 후 포맷팅, 린트 자동 실행
 
  Notification:
    - 권한 요청, 작업 완료 등의 알림
    - 슬랙 알림, 로깅 등과 연결 가능

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "write|edit",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }
    ],
    "PreToolUse": [
      {
        "matcher": "bash",
        "command": "echo 'Command: $CLAUDE_TOOL_INPUT' >> /tmp/claude-audit.log"
      }
    ]
  }
}

name: Claude Code Automation
 
on:
  issues:
    types: [labeled]
 
permissions:
  contents: write
  pull-requests: write
  issues: write
 
jobs:
  run-claude:
    if: github.event.label.name == 'claude-code'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
 
      - name: Run Claude Code
        env:
          ANTHROPIC_API_KEY: $ANTHROPIC_KEY_VALUE
        run: |
          ISSUE_BODY=$(gh issue view $ISSUE_NUMBER --json body -q .body)
          claude -p "$ISSUE_BODY" --allowedTools "Edit,Write,Bash" --yes
 
      - name: Create PR
        env:
          GITHUB_TOKEN: $GITHUB_TOKEN_VALUE
        run: |
          BRANCH="claude/issue-$ISSUE_NUMBER"
          git checkout -b $BRANCH
          git add -A
          git diff --staged --quiet && exit 0
          git commit -m "feat: implement issue #$ISSUE_NUMBER"
          git push origin $BRANCH
          gh pr create \
            --title "feat: implement issue #$ISSUE_NUMBER" \
            --body "Automated implementation by Claude Code" \
            --base main

서브에이전트 활용 시나리오:
 
  주 에이전트: 전체 작업 조율
    서브에이전트 1: 백엔드 API 구현
    서브에이전트 2: 프론트엔드 컴포넌트 구현
    서브에이전트 3: 테스트 작성
 
  각 서브에이전트는 독립적으로 작업하며,
  주 에이전트가 결과를 통합합니다.

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    },
    "github": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    },
    "sentry": {
      "command": "npx",
      "args": ["mcp-server-sentry"],
      "env": {
        "SENTRY_TOKEN": "..."
      }
    }
  }
}

MCP 연동 활용 예시:
 
  데이터베이스:
    "users 테이블의 스키마를 확인하고,
     활성 사용자 수를 조회해 줘"
 
  GitHub:
    "최근 열린 이슈 중 버그 라벨이 붙은 것을
     우선순위별로 정리해 줘"
 
  Sentry:
    "최근 24시간 동안 가장 많이 발생한 에러를
     분석하고 수정 방안을 제안해 줘"

일일 개발 루틴:
 
  아침:
    1. "어제 남긴 TODO를 확인하고 정리해 줘"
    2. "최근 이슈 중 내게 할당된 것을 정리해 줘"
 
  개발 중:
    3. "이 기능을 구현해 줘" (구체적 명세 제공)
    4. "테스트를 작성하고 실행해 줘"
    5. "빌드가 통과하는지 확인해 줘"
 
  리뷰 대응:
    6. "이 리뷰 코멘트를 반영해 줘" (PR 링크 제공)
    7. "수정 사항이 기존 테스트를 깨지 않는지 확인해 줘"
 
  마무리:
    8. "오늘 변경 사항을 커밋해 줘"
    9. "PR을 생성해 줘"

팀 워크플로우 통합:
 
  코드 표준 유지:
    - CLAUDE.md에 팀 컨벤션 기록
    - 새 팀원이 작성한 코드를 자동으로 컨벤션에 맞게 조정
 
  이슈 기반 개발:
    - GitHub 이슈에 명세 작성
    - claude-code 라벨로 자동 구현 트리거
    - 생성된 PR을 팀원이 리뷰
 
  지식 관리:
    - 아키텍처 결정을 CLAUDE.md에 기록
    - 새 팀원의 온보딩 시 Claude Code가 코드 설명