CLAUDE.md 완전 정복 - 워크플로우 자동화

CLAUDE.md로 빌드·테스트·배포를 AI에 맡기는 방법

CLAUDE.md에 빌드나 테스트 커맨드를 적어두는 것에 그치지 않고, 작업 절차 전체를 정의해 두면 Claude Code에 일련의 작업을 통째로 맡길 수 있습니다.

이 장에서는 개발 현장에서 자주 쓰이는 워크플로우 자동화 패턴을 소개합니다.

워크플로우란

워크플로우는 "이런 작업을 할 때는, 이 순서로 진행해줘"라고 Claude Code에 미리 알려두는 절차 정의입니다.

예를 들어 "새로운 API 엔드포인트를 추가할 때"의 워크플로우를 다음처럼 정의해 두면:

## 새로운 API 엔드포인트 추가 절차

1. `app/api/`에 라우트 파일을 생성한다
2. 요청/응답 Zod 스키마를 `schemas/`에 생성한다
3. 비즈니스 로직을 `services/`에 생성한다
4. 라우트 핸들러에서 스키마 검증 → 서비스 호출 → 응답 반환 순으로 구현한다
5. 테스트를 `__tests__/api/`에 생성한다
6. `pnpm test`로 전체 테스트가 통과하는지 확인한다
7. `pnpm typecheck`로 타입 에러가 없는지 확인한다

이후로는 "사용자 목록 API를 만들어줘"라고만 해도, Claude Code가 이 절차에 따라 라우트·스키마·서비스·테스트까지 한 번에 구현해 줍니다.

핵심: 커맨드 목록과 워크플로우의 차이는, 워크플로우가 언제·어떤 순서로·무엇을 확인하면서 실행할지를 함께 정의한다는 점입니다.

빌드 확인 패턴

코드를 변경한 뒤 커밋하기 전에 항상 수행하는 기본 체크 절차입니다.

## 코드 변경 후 체크 절차

코드를 변경한 후, 다음을 반드시 순서대로 실행한다:

1. `pnpm typecheck` — TypeScript 타입 에러가 없을 것
2. `pnpm lint` — ESLint 에러가 없을 것
3. `pnpm test` — 전체 테스트가 통과할 것
4. `pnpm build` — 프로덕션 빌드가 성공할 것

에러가 발생한 경우, 수정 후 해당 스텝부터 다시 실행한다.
4단계 모두 통과하기 전에는 커밋하지 않는다.

이 워크플로우를 정의해 두면, Claude Code가 코드를 변경할 때마다 체크를 자동으로 수행하고, 에러가 있으면 수정까지 해줍니다. "빌드 확인해줘"라고 별도로 말할 필요가 없어집니다.

테스트 주도 개발(TDD) 패턴

테스트를 먼저 작성한 후 구현하는 Red-Green-Refactor 사이클입니다.

## 신규 기능 구현 절차 (TDD)

1. 먼저 테스트 파일을 생성하고, 기대하는 동작을 테스트 케이스로 작성한다
2. `pnpm test`로 테스트가 실패하는지 확인한다 (Red)
3. 테스트를 통과하는 최소한의 구현만 작성한다 (Green)
4. `pnpm test`로 테스트가 통과하는지 확인한다
5. 동작을 유지하면서 코드를 리팩터링한다 (Refactor)
6. `pnpm test`로 리팩터링 후에도 통과하는지 재확인한다

IMPORTANT: 테스트 없이 구현 코드를 먼저 작성하지 않는다.

데이터베이스 스키마 변경 패턴

DB 스키마 변경은 영향 범위가 넓고 롤백이 어렵기 때문에, 단계별 검증이 필수입니다.

## 데이터베이스 스키마 변경 절차

1. `prisma/schema.prisma`를 편집한다
2. `pnpm prisma migrate dev --name <변경내용>`으로 마이그레이션을 생성한다
3. 생성된 SQL 파일을 반드시 검토한다 (의도하지 않은 컬럼 삭제·타입 변경이 없는지)
4. 영향을 받는 쿼리 함수를 `lib/db/`에서 업데이트한다
5. 영향을 받는 API 라우트와 서비스 레이어를 업데이트한다
6. 관련 테스트를 업데이트하거나 새로 추가한다
7. `pnpm test`로 전체 테스트가 통과하는지 확인한다

IMPORTANT: 마이그레이션 파일을 생성 후 수동으로 편집하지 않는다.
IMPORTANT: 컬럼 삭제·타입 변경은 스테이징 환경에서 먼저 검증한 후 프로덕션에 적용한다.

컴포넌트 생성 패턴

UI 컴포넌트를 추가할 때의 표준 절차입니다.

## 새로운 UI 컴포넌트 생성 절차

1. `components/ui/`에 새 파일을 생성한다 (PascalCase.tsx)
2. 같은 파일 안에서 Props 타입을 `type Props = { ... }` 형식으로 정의한다
3. 컴포넌트를 구현한다 (Tailwind CSS로 스타일링)
4. `components/ui/index.ts`에 named export를 추가한다
5. Storybook 스토리를 `stories/`에 생성한다
6. 테스트를 `__tests__/components/`에 생성한다
7. `pnpm test`로 테스트가 통과하는지 확인한다

환경별 배포 패턴

스테이징과 프로덕션의 배포 절차를 명확히 분리합니다.

## 배포 절차

### 스테이징 배포

1. `feature` 브랜치를 `develop` 브랜치에 머지한다
2. GitHub Actions가 자동으로 스테이징 환경에 배포한다
3. 스테이징 URL에서 동작을 확인한다
4. QA 체크리스트를 완료한다

### 프로덕션 배포
IMPORTANT: 프로덕션 배포는 Claude Code가 직접 실행하지 않는다.
반드시 수동으로 GitHub Releases에서 태그를 생성하여 배포한다.

프로덕션 배포 전 체크리스트:
- [ ] 스테이징에서 전체 기능 동작 확인
- [ ] 관련 팀원 슬랙 공유 및 배포 시간 협의
- [ ] 롤백 절차 숙지 (`./scripts/rollback.sh [버전]`)
- [ ] 배포 후 5분간 에러율 모니터링

프로덕션 배포처럼 되돌리기 어려운 조작은, CLAUDE.md에 "Claude Code가 직접 실행하지 않는다" 고 명시해 두는 것이 핵심입니다. AI가 의도치 않게 프로덕션을 건드리는 상황을 방지합니다.

조건부 워크플로우

상황에 따라 절차가 분기하는 패턴입니다.

## 버그 수정 절차

1. 버그를 재현하는 테스트를 먼저 작성한다
2. `pnpm test`로 테스트가 실패하는지 확인한다
3. 버그를 수정하는 최소한의 코드를 작성한다
4. `pnpm test`로 해당 테스트가 통과하는지 확인한다
5. `pnpm test`로 기존 전체 테스트가 모두 통과하는지 확인한다
6. 커밋 메시지에 `fix:` 접두사와 버그 원인 설명을 포함한다

### 보안 버그인 경우 (추가 절차)
- PR 본문에 취약점 설명, 영향 범위, 수정 방법을 기술한다
- 외부 라이브러리 취약점인 경우 `pnpm audit` 결과도 첨부한다
- 머지 전 보안 담당자 리뷰를 필수로 받는다
- 심각도에 따라 Slack `#security` 채널에 공유한다

### 핫픽스인 경우 (추가 절차)
- `main`에서 직접 `hotfix/` 브랜치를 생성한다
- 수정 후 `main`과 `develop` 양쪽에 머지한다
- 배포 후 장애 리뷰 문서를 `docs/postmortem/`에 작성한다

퍼포먼스 체크 패턴

성능에 영향을 주는 변경을 할 때의 워크플로우입니다.

## 퍼포먼스 영향이 있는 변경 절차

데이터베이스 쿼리, API 호출, 렌더링 로직을 변경하는 경우:

1. 변경 전 상태에서 벤치마크를 측정하여 기록한다
- 테스트 실행 시간: `pnpm test --reporter=verbose`
- API 응답 시간: 개발 서버에서 `curl` 또는 Postman으로 측정
2. 변경을 구현한다
3. 변경 후 동일한 방법으로 벤치마크를 측정한다
4. 20% 이상 성능이 저하된 경우, 대안을 검토하고 PR 본문에 측정 결과를 기재한다
5. N+1 쿼리가 발생하지 않는지 쿼리 로그로 확인한다

국내 서비스 특화 워크플로우

한국 서비스 개발 환경에 자주 필요한 워크플로우를 추가합니다.

## 결제 기능 변경 절차 (토스페이먼츠)

결제 관련 코드(`features/payment/`)를 변경하는 경우:

1. 변경 전 결제 플로우 E2E 테스트를 실행한다 (`pnpm test:e2e --grep "payment"`)
2. 결제 금액 계산 로직은 반드시 서버 사이드(`app/api/`)에서만 수정한다
3. 토스페이먼츠 테스트 모드로 전체 결제 시나리오를 수동 검증한다
- 카드 결제 성공 / 실패
- 가상계좌 발급
- 결제 취소
4. `pnpm test`로 결제 관련 유닛 테스트가 모두 통과하는지 확인한다
5. 스테이징 환경에서 테스트 카드로 최종 검증한다

IMPORTANT: 결제 관련 변경은 반드시 팀 리뷰 후 배포한다.
IMPORTANT: 프로덕션 결제 API 키(`TOSS_SECRET_KEY`)를 코드에 하드코딩하지 않는다.

## 개인정보 처리 기능 변경 절차

회원정보, 주문정보 등 개인정보를 다루는 코드를 변경하는 경우:

1. 변경 대상이 개인정보보호법상 개인정보 항목인지 확인한다
2. 수집·저장·전달 흐름을 코드 주석으로 명시한다
3. 암호화 대상 컬럼은 `lib/crypto.ts`의 암호화 함수를 사용한다
4. 개인정보를 로그에 출력하는 코드가 없는지 확인한다 (`grep -r "console.log" src/`)
5. 개인정보 관련 변경은 PR 본문에 처리 목적과 보관 기간을 기재한다

워크플로우 설계 팁

번호 붙인 리스트를 사용한다

절차의 순서가 중요한 경우 반드시 번호 붙인 리스트를 사용하세요. Claude Code는 번호 순서대로 실행합니다. 순서 없는 · 기호 리스트는 순서를 보장하지 않습니다.

검증 스텝을 반드시 포함한다

각 워크플로우에 "확인" 스텝을 넣어두면, Claude Code가 중간에 문제를 발견했을 때 알아서 멈추고 보고합니다. 검증 없이 계속 진행하다가 나중에 더 큰 문제가 생기는 상황을 방지합니다.

1 스텝 = 1 액션으로 설계한다

1 스텝이 너무 크면 Claude Code가 중간에 판단을 잘못하기 쉽습니다. 반대로 너무 세세하면 불필요하게 장황해집니다. "하나의 커맨드 실행 또는 하나의 판단" 을 1 스텝의 기준으로 삼으세요.

IMPORTANT로 금지 사항을 강조한다

프로덕션 배포, 데이터 삭제처럼 되돌리기 어려운 조작은 IMPORTANT:로 강조하여 Claude Code가 자의적으로 실행하지 않도록 명시합니다.

워크플로우 트리거 조건을 명시한다

"어떤 상황에서 이 워크플로우를 실행해야 하는지"를 제목이나 첫 줄에 명시하면, Claude Code가 적절한 시점에 자동으로 워크플로우를 선택합니다.

# 좋은 예 — 트리거 조건이 명확함
## 새로운 API 엔드포인트를 추가할 때의 절차

# 나쁜 예 — 언제 쓰는지 불분명함
## API 개발 절차

---

©2024-2026 MDRules dev., Hand-crafted & made with Jaewoo Kim.

이메일문의: jaewoo@mdrules.dev

AI강의/개발/기술자문, AI 업무 자동화 컨설팅 문의: https://talk.naver.com/ct/w5umt5

MDRules Dev - 네이버톡톡

AI 업무 자동화/에이전트/워크플로우설계 컨설팅/AI교육: https://mdrules.dev

MDRules Dev — AI 에이전트 경영과 AI 교육으로 차세대 경영 모델을 구축합니다