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: 테스트 없이 구현 코드를 먼저 작성하지 않는다.