Claude Code 실무 패턴

이 장에서 배울 것

이 장에서는 Claude Code를 단순한 코드 생성기가 아니라 프로젝트 안에서 함께 일하는 코딩 에이전트로 다루는 방법을 배운다. 목표는 네 가지다.

• 프로젝트 구조를 읽게 하고, 변경 범위를 좁히는 법

• CLAUDE.md, spec.md, plan.md로 작업 기준을 고정하는 법

• 코드 리뷰, 리팩터링, 테스트 실행을 반복 루프로 만드는 법

• 긴 세션에서 생기는 품질 저하를 줄이고, 새 세션과 리뷰어 세션을 활용하는 법

Claude Code의 핵심은 "대신 코딩해줘"가 아니다. 더 정확히 말하면 "이 규칙 안에서, 이 계획대로, 검증하면서 고쳐줘"에 가깝다.

왜 이 주제가 중요한가

코딩 에이전트는 파일을 읽고, 명령어를 실행하고, 코드를 수정할 수 있다. 그래서 빠르다. 동시에 위험하다. 요구사항이 흐릿하면 엉뚱한 파일을 고치고, 테스트 기준이 없으면 작동하지 않는 코드를 그럴듯하게 완성한다.

Claude Code 공식 가이드도 에이전트형 코딩 환경에서는 컨텍스트가 빠르게 차고, 컨텍스트가 복잡해질수록 모델의 실수가 늘어날 수 있다고 설명한다.¹ 여기서 컨텍스트란 대화 내용, 읽은 파일, 명령어 출력, 오류 로그처럼 Claude가 현재 판단에 참고하는 모든 정보다.

따라서 실무에서 중요한 능력은 "프롬프트를 멋지게 쓰는 능력"보다 작업 환경을 안전하게 설계하는 능력이다. 규칙 파일, 계획 문서, 테스트 명령, 리뷰 절차가 있을 때 Claude Code는 훨씬 안정적으로 일한다.

핵심 개념 설명

CLAUDE.md는 프로젝트의 작업 규칙이다

CLAUDE.md는 Claude Code가 세션을 시작할 때 읽는 프로젝트 지침 파일이다. 여기에 모든 지식을 몰아넣으면 안 된다. 핵심 규칙만 넣어야 한다.

좋은 CLAUDE.md에는 보통 다음이 들어간다.

# Project Rules

## Stack
- Next.js, TypeScript, Prisma, PostgreSQL

## Commands
- Type check: npm run typecheck
- Unit test: npm test
- Lint: npm run lint

## Coding Rules
- any 타입 금지
- 새 의존성 설치 전 반드시 확인 요청
- 기존 API 응답 형식 유지

## Danger Zones
- prisma/migrations/ 는 명시 승인 없이 수정 금지
- src/lib/auth/ 는 수정 전 계획 제출
- 결제, 인증, 데이터 삭제 로직은 테스트 없이 변경 금지

## Workflow
- 큰 변경 전에는 먼저 계획만 제시
- 구현 후 변경 파일 목록과 검증 결과를 보고

중요한 원칙은 짧고 강하게 쓰는 것이다. Claude가 코드만 읽어도 알 수 있는 내용은 빼고, 코드만 읽어서는 알 수 없는 팀 규칙과 위험 구역을 적는다. Anthropic 문서도 CLAUDE.md에는 테스트 명령, 코드 스타일, 워크플로 규칙처럼 반복 적용되는 내용을 넣고, 긴 API 문서나 자주 바뀌는 정보는 분리하라고 권한다.¹

프로젝트가 커지면 CLAUDE.md는 안내판 역할만 하게 만든다.

## References
- Architecture: @docs/architecture.md
- API rules: @docs/api-rules.md
- Database schema notes: @docs/db.md

이 방식은 필요한 문서만 읽게 하는 "점진적 공개"다. 매번 모든 자료를 컨텍스트에 넣지 않으므로 비용과 오류를 줄인다.

Plan 모드는 구현 전 안전장치다

코딩 에이전트의 기본 원리에서 배운 문장, "아직 파일을 수정하지 말고 계획만 제시해줘"는 Claude Code 실무의 출발점이다. Claude Code에는 변경 전에 읽고 계획하는 흐름이 중요하다. 공식 워크플로 문서도 계획 모드에서 파일을 읽고 제안만 하게 한 뒤, 승인 후 수정하도록 안내한다.²

실무에서는 다음 네 단계로 나눈다.

1. 조사 모드: 관련 파일, 테스트, 기존 패턴을 찾는다.

2. 계획 모드: 어떤 파일을 왜 바꿀지 계획한다.

3. 수정 모드: 승인된 범위만 구현한다.

4. 리뷰 모드: diff, 테스트, 타입 체크, 누락된 예외를 확인한다.

큰 기능은 spec.md와 plan.md로 고정한다.

# spec.md

## 목표
사용자가 할 일을 완료 처리할 수 있다.

## 범위
- 체크박스 클릭 시 상태를 done으로 변경
- 목록에서 완료 항목 스타일 변경

## 제외
- 알림 기능
- 반복 일정 기능

## 완료 기준
- 기존 목록 조회 테스트 통과
- 완료 처리 API 테스트 추가
- npm test 통과

# plan.md

1. 기존 task 모델과 API 확인
2. 완료 상태 업데이트 함수 추가
3. UI 체크박스 이벤트 연결
4. 단위 테스트와 API 테스트 추가
5. npm test, npm run typecheck 실행

이 두 파일은 Claude와 사람 사이의 계약서다. 구현 중 방향이 흔들리면 다시 spec.md와 plan.md로 돌아간다.

슬래시 커맨드는 반복 업무를 버튼처럼 만든다

자주 쓰는 요청은 매번 새로 쓰지 말고 .claude/commands/에 저장한다. 예를 들어 코드 리뷰 명령을 만들 수 있다.

# .claude/commands/review-changes.md

현재 브랜치의 변경사항을 리뷰하라.

확인할 것:
1. 버그 가능성
2. 테스트 누락
3. 타입 오류 가능성
4. 보안상 위험한 입력 처리
5. 프로젝트 규칙 위반

출력:
- 파일별 이슈
- 심각도: BLOCKER / MAJOR / NIT
- 수정 제안

파일을 수정하지 말고 보고서만 작성하라.

이후에는 "/review-changes 실행해줘"처럼 사용할 수 있다. 테스트 생성, PR 설명 작성, 리팩터링 계획 수립, 문서 업데이트도 같은 방식으로 명령화한다.

서브에이전트는 컨텍스트를 분리한다

긴 세션에서 "이 파일도 봐줘", "보안도 확인해줘", "테스트도 찾아줘"를 모두 한 대화에 넣으면 컨텍스트가 빠르게 더러워진다. 이때 서브에이전트가 유용하다. Claude Code의 서브에이전트는 특정 유형의 작업을 맡는 특화 AI 어시스턴트이며, 별도 컨텍스트에서 작업한 뒤 요약을 반환한다.³

대표적인 역할은 다음과 같다.

• code-reviewer: 변경 파일을 읽고 리뷰만 한다. 수정 권한 없음.

• test-writer: 누락된 테스트를 찾고 테스트 계획을 만든다.

• security-auditor: 인증, 권한, 입력 검증 위험을 확인한다.

• docs-agent: 변경된 코드에 맞춰 문서를 갱신한다.

리뷰어 서브에이전트는 읽기 전용으로 두는 것이 좋다. "검토하는 사람"과 "고치는 사람"을 분리하면 AI가 자기 실수를 스스로 합리화하는 일을 줄일 수 있다.

Hooks는 잊으면 안 되는 일을 강제한다

CLAUDE.md는 판단을 돕는 규칙이다. 하지만 긴 세션에서는 규칙을 놓칠 수 있다. 반드시 지켜야 하는 일은 Hooks로 자동화한다. Hooks는 Claude Code의 특정 시점에 실행되는 사용자 정의 명령이다. 공식 Hooks 문서는 PreToolUse, PostToolUse, SessionStart, Stop, PreCompact 같은 이벤트를 제공한다고 설명한다.⁴

실무에서 자주 쓰는 패턴은 다음과 같다.

• PreToolUse: 위험한 Bash 명령 차단
  예: rm -rf, git push --force, 운영 DB 변경 명령

• PostToolUse: 파일 수정 후 포맷터 실행
  예: prettier, eslint --fix, ruff format

• SessionStart: 세션 시작 시 프로젝트 상태 출력
  예: 현재 브랜치, 변경 파일, TODO 표시

• Stop: 작업 종료 시 요약 로그 저장
  예: 변경 파일, 실행한 테스트, 남은 이슈 기록

• PreCompact: 컨텍스트 압축 전 현재 진행 상황 저장

규칙은 Claude가 기억하게 하고, 안전장치는 시스템이 강제하게 한다. 이 구분이 중요하다.

쉬운 비유 또는 사례

Claude Code를 신입 개발자라고 생각하면 쉽다. 신입에게 "회원 기능 만들어줘"라고만 말하면 결과가 들쭉날쭉하다. 반대로 다음을 주면 훨씬 잘한다.

• 프로젝트 소개 문서

• 코딩 규칙

• 건드리면 안 되는 파일 목록

• 요구사항 문서

• 단계별 작업 계획

• 테스트 명령

• 리뷰 기준

Claude Code도 같다. 능력은 강하지만, 기준이 없으면 추측한다. 실무형 Claude Code 사용법은 AI에게 더 많은 자유를 주는 것이 아니라 좋은 울타리 안에서 빠르게 움직이게 하는 것이다.

예를 들어 "로그인 버그 고쳐줘"는 위험하다. 더 나은 요청은 다음과 같다.

아직 파일을 수정하지 마.

사용자가 세션 만료 후 다시 로그인하면 실패하는 문제가 있다.
관련 위치는 src/auth/와 src/api/session 쪽일 가능성이 높다.

먼저 다음을 조사해줘.
1. 로그인 흐름
2. 토큰 갱신 흐름
3. 관련 테스트 존재 여부
4. 재현 가능한 실패 테스트를 어디에 추가할지

그다음 plan.md 형식으로 수정 계획만 제시해줘.

이 요청은 Claude를 바로 코딩으로 밀어 넣지 않는다. 먼저 지도를 만들게 한다.

직접 해보는 실습

이번 실습은 작은 기능 하나를 선택해 Claude Code로 조사, 계획, 구현, 테스트, 리뷰까지 진행하는 것이다.

준비

작은 프로젝트를 하나 고른다. 예제 기능은 다음 중 하나면 충분하다.

• 버튼 문구 변경이 아니라 작은 상태 변경 기능

• 유효성 검사 하나 추가

• 정렬 옵션 하나 추가

• 테스트가 부족한 유틸 함수 개선

먼저 새 브랜치를 만든다.

git checkout -b feature/claude-small-change

CLAUDE.md 점검

Claude Code에서 /init을 실행하거나 기존 CLAUDE.md를 열어 다음을 확인한다.

• 테스트 명령이 있는가?

• 타입 체크 명령이 있는가?

• 수정 금지 영역이 있는가?

• 새 의존성 설치 전 확인 규칙이 있는가?

• "계획 없이 큰 변경 금지" 규칙이 있는가?

없다면 추가한다.

spec.md 작성 요청

아직 코드를 수정하지 마.

이 기능에 대한 spec.md 초안을 작성해줘.
포함할 것:
- 목표
- 사용자 시나리오
- 범위
- 제외할 것
- 영향을 받을 가능성이 있는 파일
- 완료 기준
- 실행할 테스트 명령

초안을 그대로 믿지 말고 직접 고친다. 특히 "제외할 것"을 명확히 써야 한다. 범위 밖의 리팩터링을 막기 위해서다.

plan.md 작성 요청

spec.md를 기준으로 구현 계획을 작성해줘.
아직 파일을 수정하지 마.
각 단계마다 변경할 파일, 검증 방법, 실패 시 되돌릴 기준을 포함해줘.

계획이 너무 크면 줄인다. 한 번에 10개 파일을 고치겠다는 계획은 초보자에게 위험하다.

구현

plan.md의 1~3단계만 구현해줘.
범위 밖 리팩터링은 하지 마.
완료 후 변경 파일 목록을 보여주고 테스트는 아직 실행하지 마.

처음부터 모든 단계를 맡기지 않는다. 작은 단위로 진행한다.

테스트와 수정 반복

이제 plan.md에 적힌 테스트 명령을 실행해줘.
실패하면 원인을 설명하고, 가장 작은 수정으로 고쳐줘.
테스트를 통과할 때까지 반복하되 새 의존성은 설치하지 마.

테스트 로그는 사람이 요약하지 말고 원문 그대로 Claude에게 주는 것이 좋다. 오류 메시지에는 중요한 단서가 많다.

리뷰어 세션 실행

가능하면 새 Claude Code 세션을 열고, 기존 대화 내용을 많이 주지 않은 상태에서 리뷰만 맡긴다.

현재 브랜치의 diff를 main과 비교해 리뷰해줘.
파일을 수정하지 말고, 다음만 보고서로 작성해줘.

- 버그 가능성
- 테스트 누락
- 과한 변경
- CLAUDE.md 규칙 위반
- 배포 전 확인할 점

새 세션은 이전 구현 과정의 자기합리화가 적다. 사람으로 치면 별도 리뷰어에게 PR을 맡기는 것과 같다.

흔한 실수와 오류 분석

실수 1: "전체 리팩터링 해줘"라고 요청한다

범위가 넓으면 Claude는 많은 파일을 읽고 고친다. 그 과정에서 컨텍스트가 커지고, 작은 실수가 여러 파일에 퍼진다. 리팩터링은 파일 하나, 모듈 하나, 규칙 하나씩 진행한다.

나쁜 요청:

프로젝트 전체를 깔끔하게 리팩터링해줘.

좋은 요청:

src/services/orderService.ts의 createOrder 함수만 대상으로 해줘.
동작은 바꾸지 말고 validation, 계산, 저장 로직을 함수로 분리해줘.
기존 테스트가 통과해야 해.

실수 2: CLAUDE.md가 너무 길다

CLAUDE.md가 길면 중요한 규칙이 묻힌다. 반복되는 실수가 보이면 파일을 더 늘리기보다 줄여야 할 때가 많다. 핵심 규칙은 루트에 두고, 긴 설명은 별도 문서로 분리한다.

실수 3: 테스트 없이 "작동할 것 같다"로 끝낸다

AI가 만든 코드는 그럴듯해 보이는 경우가 많다. 검증 기준이 없으면 사람도 속기 쉽다. 최소한 다음 중 하나는 실행해야 한다.

• 단위 테스트

• 타입 체크

• 린트

• 빌드

• 특정 재현 명령

• 화면 변경이라면 스크린샷 비교

실수 4: 긴 세션을 계속 끌고 간다

한 세션에서 조사, 구현, 디버깅, 다른 기능, 문서화까지 모두 하면 품질이 떨어진다. 기능 하나가 끝나면 /clear로 새로 시작하거나, 중요한 요약만 남기고 /compact를 사용한다. 단, 압축은 정보 손실이 있을 수 있으므로 spec.md, plan.md, TODO.md처럼 파일에 남길 것은 먼저 남긴다.

실수 5: 구현 세션과 리뷰 세션을 분리하지 않는다

같은 세션에서 "내가 방금 만든 코드 리뷰해줘"라고 하면 놓치는 것이 생길 수 있다. 가능하면 새 세션이나 읽기 전용 서브에이전트로 리뷰한다. 리뷰어는 수정하지 않고 지적만 하게 한다.

요약

Claude Code는 스펙, 계획, 규칙, 검증 루프가 있을 때 가장 강력하다. CLAUDE.md는 프로젝트의 기본 규칙을 알려주고, spec.md는 무엇을 만들지 고정하며, plan.md는 어떻게 만들지 합의한다. 슬래시 커맨드는 반복 업무를 재사용 가능하게 만들고, 서브에이전트는 컨텍스트를 분리하며, Hooks는 반드시 지켜야 할 안전 규칙을 자동으로 강제한다.

좋은 실무 흐름은 다음과 같다.

조사 → 스펙 → 계획 → 작은 구현 → 테스트 → 리뷰 → 커밋

이 순서를 지키면 Claude Code는 위험한 자동 수정 도구가 아니라, 반복 작업을 빠르게 처리하는 실무 파트너가 된다.

퀴즈

1. CLAUDE.md에 넣기 좋은 내용과 넣지 말아야 할 내용의 차이는 무엇인가?

2. "아직 파일을 수정하지 말고 계획만 제시해줘"라는 문장이 중요한 이유는 무엇인가?

3. 서브에이전트를 사용하면 긴 세션의 어떤 문제를 줄일 수 있는가?

4. Hooks로 처리하기 좋은 작업을 두 가지 말해보라.

5. 구현 세션과 리뷰어 세션을 분리하면 어떤 장점이 있는가?

체크리스트

• 프로젝트 루트에 CLAUDE.md가 있다.

• 테스트, 타입 체크, 빌드 명령이 문서화되어 있다.

• 수정 금지 영역과 확인 필요 영역이 적혀 있다.

• 큰 작업 전에는 spec.md와 plan.md를 만든다.

• 구현 전 Plan 모드 또는 읽기 전용 조사 단계를 거친다.

• 한 번에 너무 많은 파일을 고치지 않는다.

• 테스트 실패 로그는 원문으로 제공한다.

• 리뷰는 가능하면 새 세션이나 읽기 전용 서브에이전트에서 한다.

• 긴 작업 후에는 /clear, /compact, 세션 분리를 사용한다.

• 반복 리뷰, 테스트, 문서화 요청은 슬래시 커맨드로 만든다.

다음 장 연결

다음 장에서는 Codex 실무 패턴을 다룬다. Claude Code에서 배운 원칙은 그대로 이어진다. 다만 도구의 인터페이스와 강점이 다르므로, Codex에서는 작업 지시, 코드 변경 검토, 테스트 반복, 저장소 기반 협업 흐름을 어떻게 설계할지 비교하며 살펴본다.

참고

¹Best practices for Claude Code

²Common workflows - Claude Code Docs

³Sub agents - Claude Code Docs

⁴Hooks reference - Claude Code Docs