Claude Code 공식 모범 사례 쉽게 이해하기

학습용 가이드 · Anthropic 공식 문서 기반

Claude Code 공식 모범 사례
쉽게 이해하기

이 문서는 Anthropic의 공식 문서 Claude Code 모범 사례를 바탕으로, 내용을 더 쉽게 이해할 수 있도록 설명과 예시를 추가해 재구성한 학습용 가이드입니다.
공식 문서: code.claude.com/docs/ko/best-practices

0한 줄 요약

Claude Code를 잘 쓰는 핵심은 AI에게 코딩을 맡기는 것이 아니라, AI가 검증 가능한 방식으로 일하게 만드는 것입니다.

좋은 AI 코딩 운영 = 목표 + 맥락 + 검증 기준 + 권한 제한 + 리뷰 구조

1Claude Code는 챗봇이 아니라 "자율 코딩 작업자"다

일반 챗봇은 질문에 답하고 멈춥니다. 하지만 Claude Code는 다음 일을 할 수 있습니다.

파일 읽기
코드 수정
터미널 명령 실행
테스트 실행
빌드 확인
에러 로그 분석
여러 파일에 걸친 리팩터링
PR 작성
독립 리뷰 요청

그래서 Claude Code는 "대답하는 도구"라기보다 일을 맡길 수 있는 개발 작업자에 가깝습니다.

쉽게 비유하면

일반 챗봇	Claude Code
선생님에게 질문하는 느낌	개발자에게 업무를 맡기는 느낌
설명 중심	실행 중심
사용자가 직접 검증	테스트/빌드로 자체 검증 가능
대화가 주된 작업 공간	코드베이스와 터미널이 작업 공간

나쁜 사용 방식

이거 고쳐줘.

좋은 사용 방식

로그인 실패 버그를 수정해줘.

범위:
- src/auth 폴더 중심으로 확인
- 세션 만료 후 재로그인 흐름 확인

완료 기준:
1. 문제를 재현하는 테스트 작성
2. 근본 원인 설명
3. 코드 수정
4. npm test -- auth 실행
5. npm run build 실행
6. 실행 결과와 변경 파일 요약

2가장 중요한 원칙: 완료 기준을 먼저 줘라

Claude Code는 작업이 "끝난 것처럼 보이면" 멈출 수 있습니다. 하지만 실제 업무에서는 "끝난 것처럼 보임"이 아니라 검증된 완료가 중요합니다.

공식 문서가 강조하는 핵심은 이것입니다.

Claude가 실행할 수 있는 확인 방법을 제공하라.
테스트, 빌드, lint, 스크린샷, 고정 출력 비교 등이 검증 기준이 될 수 있다.

3검증 기준의 종류

검증 기준은 꼭 단위 테스트만 의미하지 않습니다.

작업	검증 기준 예시
함수 구현	단위 테스트 통과
API 개발	요청/응답 테스트, 상태 코드 확인
UI 수정	브라우저 스크린샷, 콘솔 에러 없음
빌드 오류 수정	`npm run build` 성공
타입 오류 수정	`npm run typecheck` 성공
코드 정리	기존 테스트 전부 통과
문서 생성	필수 섹션 포함, 링크 유효성 확인
데이터 처리	입력/출력 샘플 비교

4Before / After 예시: 검증 기준 제공

예시 1. 이메일 검증 함수

부족한 요청

이메일 주소 검증 함수를 만들어줘.

좋은 요청

validateEmail 함수를 작성해줘.

다음 케이스를 통과해야 해.
- user@example.com → true
- invalid → false
- user@.com → false
- @example.com → false

구현 후 테스트를 작성하고 실행해줘.
테스트가 실패하면 수정하고 다시 실행해줘.
마지막에는 실행한 명령과 결과를 요약해줘.

이 프롬프트가 좋은 이유

성공/실패 기준이 명확함
테스트 작성을 요구함
실패 시 반복 수정하도록 함
마지막에 증거를 보고하게 함

예시 2. UI 개선

부족한 요청

대시보드를 더 예쁘게 만들어줘.

좋은 요청

첨부한 스크린샷을 기준으로 대시보드를 개선해줘.

완료 기준:
1. 카드 간격이 일정할 것
2. 모바일 화면에서 깨지지 않을 것
3. 주요 버튼이 클릭 가능할 것
4. 브라우저 콘솔 에러가 없을 것
5. 수정 후 결과 스크린샷을 찍고 원본과 차이를 설명할 것

이 프롬프트가 좋은 이유

"예쁘게"라는 추상적인 기준을 구체적인 검증 항목으로 바꾸었습니다.

예시 3. 빌드 오류 수정

부족한 요청

빌드가 실패해. 고쳐줘.

좋은 요청

아래 빌드 오류의 근본 원인을 찾아 수정해줘.

오류:
[빌드 오류 붙여넣기]

주의:
- 에러를 숨기지 말 것
- 타입 검사를 약화하지 말 것
- 임시로 테스트를 제거하지 말 것

수정 후 npm run build를 실행해줘.
실패하면 원인을 다시 분석하고 통과할 때까지 반복해줘.
마지막에는 원인, 변경 파일, 실행 결과를 요약해줘.

5먼저 탐색하고, 그 다음 계획하고, 그 다음 코딩하라

공식 문서는 복잡한 작업에서 바로 코딩하지 말고 다음 흐름을 권장합니다.

탐색→계획→구현→검증→커밋/보고

왜 바로 코딩하면 위험할까?

AI는 매우 빠르게 움직입니다. 문제는 잘못 이해한 상태에서도 빠르게 움직인다는 점입니다.

예를 들어 "Google OAuth 추가해줘"라고만 하면 Claude Code는 다음을 잘못 판단할 수 있습니다.

기존 세션 방식
환경 변수 관리 방식
콜백 라우팅 구조
기존 인증 테스트 패턴
보안 요구사항

그래서 먼저 탐색하고 계획해야 합니다.

6Plan Mode가 필요한 경우와 필요 없는 경우

상황	Plan Mode 필요 여부
오타 수정	필요 낮음
로그 한 줄 추가	필요 낮음
변수명 변경	필요 낮음
여러 파일 수정	필요 높음
인증/결제/권한 관련 작업	필요 매우 높음
낯선 코드베이스 작업	필요 높음
대규모 리팩터링	필요 매우 높음
DB 마이그레이션	필요 매우 높음

판단 기준

변경 내용을 한 문장으로 정확히 설명할 수 있다면 바로 실행해도 된다.
그렇지 않다면 먼저 탐색과 계획을 분리하라.

7탐색 → 계획 → 구현 예시

1단계. 탐색 요청

src/auth 폴더를 읽고 현재 로그인과 세션 처리 방식을 파악해줘.
아직 코드는 수정하지 마.

확인할 것:
1. 로그인 흐름
2. 세션 저장 방식
3. 토큰 만료 처리
4. 환경 변수와 비밀키 관리 방식
5. 기존 테스트 패턴

2단계. 계획 요청

Google OAuth를 추가하려면 어떤 파일을 수정해야 하는지 계획을 작성해줘.

계획에는 다음을 포함해줘.
1. 변경할 파일 목록
2. 새로 추가할 파일 목록
3. 세션 흐름
4. 콜백 처리 방식
5. 환경 변수 목록
6. 테스트 전략
7. 보안상 주의할 점

아직 구현하지 마.

3단계. 구현 요청

위 계획에 따라 Google OAuth 흐름을 구현해줘.

완료 기준:
1. 콜백 핸들러 테스트 작성
2. 로그인 성공/실패 케이스 테스트
3. npm test -- auth 실행
4. npm run build 실행
5. 실패 시 수정 후 재실행

4단계. 보고 요청

작업 결과를 요약해줘.

포함할 것:
- 변경 파일
- 구현한 흐름
- 실행한 테스트 명령
- 테스트 결과
- 남은 위험
- 다음 단계

8프롬프트에는 구체적인 맥락을 넣어라

Claude는 의도를 추론할 수 있지만 마음을 읽지는 못합니다.

맥락에 포함하면 좋은 것

관련 파일 또는 폴더
현재 증상
재현 조건
기대 결과
기존 코드 패턴
테스트 선호도
금지할 작업
완료 후 보고 형식

9Before / After 예시: 맥락 제공

부족한 요청	좋은 요청
테스트 추가해줘	로그아웃 사용자가 `/dashboard`에 접근할 때 `/login`으로 이동하는 테스트를 추가해줘
API 만들어줘	기존 `users` API 패턴을 따라 `projects` 목록 API를 만들어줘. pagination 포함
README 정리해줘	`package.json`의 실제 명령을 확인해서 설치, 실행, 테스트 섹션을 업데이트해줘
에러 고쳐줘	아래 에러는 배포 환경에서만 발생해. 환경 변수 로딩 순서와 production config를 확인해줘
결제 기능 만들어줘	Stripe webhook을 처리해 주문 상태를 업데이트해줘. 서명 검증, 중복 이벤트 방지, 실패 로그를 포함해줘

10풍부한 콘텐츠를 제공하라

공식 문서는 @, 이미지, URL, pipe 입력 등을 적극 활용하라고 말합니다.

1) 파일 직접 참조

@src/middleware/auth.ts 파일을 읽고 인증 흐름을 설명해줘.
특히 토큰 만료와 갱신이 어떻게 처리되는지 확인해줘.

2) 스크린샷 제공

첨부한 디자인 스크린샷과 현재 구현을 비교해줘.
차이점을 목록으로 만들고, 수정 계획을 작성해줘.

3) URL 제공

아래 API 문서를 참고해서 webhook 처리 코드를 구현해줘.
문서: https://example.com/api/webhook

주의:
- 서명 검증 필수
- 중복 이벤트 방지
- 실패 이벤트 로깅

4) 로그를 pipe로 전달

cat error.log | claude -p "이 로그의 근본 원인을 분석하고 수정 계획을 제안해줘."

11CLAUDE.md는 짧은 운영 카드다

CLAUDE.md는 Claude가 세션 시작 시 읽는 프로젝트 지침 파일입니다.

하지만 중요한 점이 있습니다.

CLAUDE.md는 길수록 좋은 문서가 아니다.
짧고 강해야 한다.

넣으면 좋은 것

포함할 것	예시
빌드 명령	`npm run build`
테스트 명령	관련 테스트 먼저 실행, 마지막에 전체 typecheck
코드 스타일 예외	CommonJS 금지, ES Modules 사용
위험 폴더	migrations 폴더는 승인 없이 수정 금지
프로젝트 고유 규칙	인증 변경 시 세션 만료 테스트 필수
PR 규칙	변경 요약과 테스트 결과 포함

빼야 할 것

제외할 것	이유
일반적인 코딩 상식	Claude가 이미 알고 있음
긴 API 문서	링크로 대체하는 편이 좋음
파일별 장황한 설명	context 낭비
자주 바뀌는 정보	금방 낡음
"깨끗한 코드 작성"	너무 추상적

12좋은 CLAUDE.md 예시

# 프로젝트 작업 규칙

## 코드 스타일
- ES Modules import/export 사용
- CommonJS require 사용 금지
- 새 API 응답 필드는 camelCase 사용

## 테스트
- 작은 변경은 관련 테스트를 먼저 실행
- 최종 변경 전 npm run typecheck 실행
- 인증 로직 변경 시 세션 만료 테스트 필수

## 주의사항
- migrations 폴더는 승인 없이 수정하지 말 것
- 새 라이브러리 추가 전 기존 의존성으로 해결 가능한지 확인
- 에러를 숨기기 위해 테스트를 약화하지 말 것

좋은 CLAUDE.md를 판단하는 질문

이 줄을 지우면 Claude가 실제로 실수할까?

답이 "아니오"라면 지워도 됩니다.

13권한은 자동화의 브레이크다

Claude Code는 파일 수정, Bash 명령, MCP 도구 사용 등 위험할 수 있는 작업을 수행할 수 있습니다. 그래서 권한 관리가 중요합니다.

공식 문서의 세 가지 방식은 다음과 같습니다.

방식	설명	사용 예
Auto mode	위험해 보이는 명령만 차단	일반 개발 작업 자동화
권한 허용 목록	특정 도구/명령만 허용	`npm run lint`, `git commit` 등
Sandbox	OS 수준 격리	위험한 실험, 무인 실행

예시

claude --permission-mode auto -p "fix all lint errors"

더 안전한 예시

claude -p "lint 오류를 수정해줘. 새 기능은 추가하지 마." \
  --allowedTools "Read,Edit,Bash(npm run lint),Bash(npm test)"

핵심 원칙

AI가 빨리 움직이게 하되, 망가뜨릴 수 있는 범위는 좁혀라.

14CLI 도구를 적극 활용하라

공식 문서는 gh, aws, gcloud, sentry-cli 같은 CLI 도구를 Claude Code와 함께 쓰라고 권합니다.

이유는 간단합니다.

CLI는 외부 서비스와 상호작용하는 가장 context 효율적인 방법이다.

GitHub 예시

gh CLI를 사용해서 현재 저장소의 열린 이슈 중 bug 라벨이 붙은 항목을 확인해줘.
가장 최근 이슈를 요약하고 수정 계획을 작성해줘.

배포 로그 예시

Vercel CLI를 사용해 최근 배포 실패 로그를 확인하고,
실패 원인과 수정 방법을 제안해줘.

모르는 CLI를 배우게 하는 예시

foo-cli --help를 먼저 읽고 사용법을 파악한 뒤,
이 도구로 현재 프로젝트의 설정 상태를 점검해줘.

15MCP 서버로 외부 업무 시스템을 연결하라

MCP는 Claude Code가 외부 시스템과 연결되는 통로입니다.

예를 들어 다음을 연결할 수 있습니다.

Notion
Figma
데이터베이스
이슈 트래커
모니터링 시스템
내부 업무 도구

Figma 예시

Figma MCP를 사용해 최신 디자인을 확인하고,
현재 React 컴포넌트와 차이를 분석해줘.
그 다음 수정 계획을 작성해줘.

데이터베이스 예시

DB MCP를 사용해서 최근 결제 실패 이벤트를 조회해줘.
공통 패턴을 분석하고, 코드에서 확인해야 할 지점을 알려줘.

16Hooks는 반드시 실행되어야 하는 규칙에 사용하라

CLAUDE.md는 권고입니다. 하지만 hooks는 결정론적으로 실행됩니다.

hooks에 적합한 작업

파일 수정 후 자동 lint 실행
특정 폴더 수정 차단
커밋 전 테스트 실행
비밀키 포함 여부 검사
마이그레이션 파일 임의 수정 방지

예시 요청

모든 TypeScript 파일 편집 후 eslint를 실행하는 hook을 작성해줘.

migrations 폴더는 사용자 승인 없이 수정하지 못하도록 hook을 만들어줘.

차이점

구분	역할
CLAUDE.md	Claude가 참고하는 지침
Hook	반드시 실행되는 자동 규칙

17Skills는 반복 업무를 저장하는 방법이다

반복되는 도메인 지식이나 workflow는 skill로 저장할 수 있습니다.

API 규칙 skill 예시

---
name: api-conventions
description: 우리 서비스의 REST API 설계 규칙
---

# API 규칙
- URL 경로는 kebab-case 사용
- JSON 속성은 camelCase 사용
- 목록 엔드포인트에는 pagination 포함
- API 버전은 URL 경로에 표시: /v1, /v2

GitHub 이슈 처리 skill 예시

---
name: fix-issue
description: GitHub 이슈 수정 워크플로우
---

1. gh issue view로 이슈 확인
2. 관련 파일 검색
3. 문제 재현 테스트 작성
4. 코드 수정
5. 테스트와 lint 실행
6. 변경 내용 요약
7. PR 생성

CLAUDE.md와 skill의 차이

구분	사용 시점
CLAUDE.md	모든 세션에 항상 필요한 규칙
Skill	특정 업무에서만 필요한 지식/절차

18Subagents는 context를 아끼는 강력한 도구다

Claude Code의 핵심 제약은 context window입니다. 조사 작업은 많은 파일을 읽기 때문에 context를 빠르게 채웁니다.

이때 subagent를 사용하면 별도 context에서 조사하고, 메인 세션에는 요약만 가져올 수 있습니다.

조사용 subagent 예시

subagent를 사용해서 인증 시스템의 token refresh 흐름을 조사해줘.

보고할 것:
1. 관련 파일
2. 현재 동작 방식
3. 재사용 가능한 유틸리티
4. 잠재적 문제
5. 구현 시 주의사항

메인 세션에서는 아직 코드 수정하지 마.

리뷰용 subagent 예시

subagent를 사용해서 현재 diff를 리뷰해줘.

확인할 것:
- 요구사항 누락
- 엣지 케이스
- 테스트 부족
- 보안 문제
- 기존 패턴 위반

스타일 취향이나 과도한 추상화 제안은 제외해줘.

19Claude에게 질문도 잘 시켜라

공식 문서는 큰 기능을 만들 때 Claude가 사용자를 인터뷰하도록 하라고 권합니다.

예시

새로운 구독 결제 기능을 만들고 싶어.
AskUserQuestion 도구를 사용한다고 생각하고 나를 인터뷰해줘.

질문할 것:
- 기술 구현
- 결제 플로우
- UI/UX
- 예외 상황
- 보안 요구사항
- 운영 정책
- 트레이드오프

명백한 질문만 하지 말고, 내가 놓쳤을 수 있는 어려운 부분을 물어봐줘.
모든 질문이 끝나면 SPEC.md 형태로 사양을 작성해줘.

좋은 SPEC.md에 들어갈 것

목표
사용자 시나리오
포함 범위
제외 범위
관련 파일/인터페이스
데이터 흐름
에러 처리
보안 고려사항
E2E 검증 단계

20세션 관리는 품질 관리다

Claude Code는 긴 세션에서 context가 쌓입니다. 문제는 관련 없는 정보와 실패한 접근도 같이 쌓인다는 점입니다.

자주 쓰는 명령

명령	용도
`Esc`	진행 중인 작업 중단
`Esc + Esc` 또는 `/rewind`	이전 체크포인트로 되돌리기
`Undo that`	변경 되돌리기
`/clear`	관련 없는 작업 사이에서 context 초기화
`/compact`	긴 대화를 요약해 context 절약
`/continue`	최근 세션 이어가기
`/resume`	저장된 세션 선택해 이어가기
`/rename`	세션 이름 지정

언제 `/clear`를 써야 할까?

로그인 버그 작업 후 UI 디자인 작업으로 넘어갈 때
배포 오류 분석 후 README 작성으로 넘어갈 때
같은 문제로 두 번 이상 실패했을 때
세션에 관련 없는 질문이 많이 섞였을 때

공식 문서의 핵심 조언

누적된 수정이 있는 긴 세션보다,
배운 점을 반영한 깨끗한 새 프롬프트가 더 좋은 결과를 낸다.

21체크포인트와 rewind를 활용하라

Claude Code는 변경 전 체크포인트를 만들 수 있습니다. 작업이 잘못되면 대화나 코드 상태를 되돌릴 수 있습니다.

좋은 사용 방식

이 접근을 실험해봐.
작동하지 않으면 /rewind로 되돌리고 다른 접근을 시도하자.

주의할 점

체크포인트는 git의 대체품이 아닙니다.

Claude가 변경한 파일은 되돌릴 수 있음
외부 프로세스나 DB 변경은 되돌리지 못할 수 있음
중요한 작업은 여전히 git commit/checkpoint가 필요함

22비대화형 모드로 자동화하기

Claude Code는 claude -p로 비대화형 실행이 가능합니다.

일회성 질문

claude -p "이 프로젝트가 무엇을 하는지 설명해줘"

JSON 출력

claude -p "모든 API 엔드포인트를 나열해줘" --output-format json

스트리밍 JSON

claude -p "이 로그 파일을 분석해줘" --output-format stream-json --verbose

활용처

CI 파이프라인
pre-commit hook
자동 코드 리뷰
대량 문서 생성
로그 분석 자동화
반복 품질 점검

23여러 Claude 세션을 병렬로 실행하기

공식 문서는 여러 Claude 세션을 병렬로 운영할 수 있다고 설명합니다.

대표 패턴: Writer / Reviewer

세션	역할
세션 A	구현자
세션 B	리뷰어

세션 A 요청

API rate limiter를 구현해줘.
기존 middleware 패턴을 따르고 테스트를 작성해줘.

세션 B 요청

@src/middleware/rateLimiter.ts 구현을 리뷰해줘.

확인할 것:
- 엣지 케이스
- 경쟁 조건
- 기존 middleware 패턴과의 일관성
- 테스트 부족

세션 A에 피드백 전달

리뷰 결과는 다음과 같아.
[리뷰 내용]

이 문제들을 수정하고 테스트를 다시 실행해줘.

24대량 작업은 fan-out 방식으로 처리하라

많은 파일을 일괄 수정해야 할 때는 파일 단위로 Claude 호출을 분산할 수 있습니다.

예시

for file in $(cat files.txt); do
  claude -p "React에서 Vue로 $file 파일을 마이그레이션해줘. 성공하면 OK, 실패하면 FAIL을 반환해줘." \
    --allowedTools "Read,Edit,Bash(npm test)"
done

중요한 원칙

처음부터 전체 파일에 적용하지 말고, 2~3개 파일에서 먼저 검증하라.

대량 작업 프롬프트 예시

다음 파일 목록에 대해 import 경로를 새 alias 기준으로 변경해야 해.

작업 방식:
1. 먼저 3개 파일에만 적용
2. 테스트 실행
3. 문제점 보고
4. 프롬프트 개선
5. 전체 파일로 확장

각 파일 결과는 OK 또는 FAIL로 기록해줘.

25적대적 리뷰 단계를 추가하라

공식 문서는 자율 실행이 많아질수록 독립 검토가 중요하다고 말합니다.

왜냐하면 구현한 AI가 자기 결과를 직접 평가하면 놓치는 부분이 생길 수 있기 때문입니다.

좋은 리뷰 프롬프트

subagent를 사용해서 PLAN.md와 현재 diff를 비교 검토해줘.

확인할 것:
1. 계획의 모든 요구사항이 구현되었는가?
2. 명시된 엣지 케이스에 테스트가 있는가?
3. 범위 밖 변경이 있는가?
4. 보안상 위험한 변경이 있는가?

주의:
- 스타일 취향은 제외
- 과도한 추상화 제안 금지
- 실제 요구사항 누락만 중요 문제로 보고

리뷰어에게도 기준이 필요하다

리뷰어에게 단순히 "문제 찾아줘"라고 하면 불필요한 제안을 많이 할 수 있습니다. 따라서 무엇을 문제로 볼지 명확히 정해야 합니다.

26흔한 실패 패턴과 해결책

1) 주방 싱크 세션

한 세션에서 로그인 버그, 디자인 수정, 배포 오류, 문서 작성까지 모두 처리하는 경우입니다.

문제

context가 지저분해짐
Claude가 엉뚱한 정보를 참고함
성능이 떨어짐

해결

관련 없는 작업 사이에는 /clear를 사용한다.

2) 반복 수정 루프

Claude가 잘못 구현하고, 사용자가 수정 지시를 하고, 또 잘못하고, 다시 수정하는 상황입니다.

문제

실패한 접근이 context에 계속 남아 같은 실수를 반복할 수 있습니다.

해결

두 번 이상 실패하면 /clear 후, 배운 점을 정리해 새 프롬프트로 시작한다.

3) 너무 긴 CLAUDE.md

모든 규칙과 설명을 CLAUDE.md에 넣는 경우입니다.

문제

중요한 규칙이 노이즈에 묻힙니다.

해결

무자비하게 줄인다. 항상 필요한 규칙만 남긴다.
반드시 실행되어야 하는 규칙은 hook으로 옮긴다.
특정 작업 지식은 skill로 분리한다.

4) 신뢰-검증 간격

Claude가 그럴듯한 구현을 만들었지만 실제 엣지 케이스는 처리하지 못하는 경우입니다.

해결

검증할 수 없으면 배포하지 않는다.
테스트, 스크립트, 스크린샷, 빌드 결과 중 하나 이상의 증거를 요구한다.

5) 무한 탐색

범위를 주지 않고 "이 코드 조사해줘"라고 하는 경우입니다.

문제

Claude가 수백 개 파일을 읽으며 context를 채웁니다.

해결

조사 범위를 좁히거나 subagent로 분리한다.

27실무 시나리오별 완성 프롬프트

시나리오 A. 로그인 버그 수정

사용자가 세션 만료 후 다시 로그인할 때 간헐적으로 실패한다는 제보가 있어.

범위:
- src/auth 폴더
- token refresh 흐름
- session 저장/갱신 로직

작업 순서:
1. 관련 파일을 조사하고 현재 흐름을 설명
2. 문제를 재현하는 실패 테스트 작성
3. 근본 원인 수정
4. npm test -- auth 실행
5. npm run build 실행
6. 실패 시 수정 후 재실행

주의:
- 에러를 숨기지 말 것
- 테스트를 약화하지 말 것
- 임시 우회 처리 금지

마지막 보고:
- 원인
- 변경 파일
- 실행한 명령
- 결과
- 남은 위험

시나리오 B. 결제 webhook 구현

결제 webhook 처리 기능을 구현해줘.

요구사항:
1. 결제 성공 이벤트 수신 시 주문 상태를 paid로 변경
2. 결제 실패 이벤트 수신 시 failed로 기록
3. webhook 서명 검증 필수
4. 중복 이벤트가 와도 상태가 꼬이지 않게 처리
5. 실패 이벤트는 로그로 남김

테스트 케이스:
- 정상 결제 성공
- 결제 실패
- 잘못된 서명
- 중복 이벤트
- 알 수 없는 이벤트 타입

검증:
- npm test -- webhook
- npm run typecheck
- npm run build

시나리오 C. 관리자 대시보드 UI 개선

관리자 대시보드 UI를 개선해줘.

조건:
1. 기존 디자인 시스템 유지
2. 카드 간격과 정렬 개선
3. 모바일 화면 대응
4. 주요 CTA 버튼 시각적 강조
5. 접근성 색상 대비 확인

검증:
1. 데스크톱 스크린샷 생성
2. 모바일 스크린샷 생성
3. 브라우저 콘솔 에러 없음 확인
4. 주요 버튼 클릭 가능 확인

마지막에는 원본 대비 개선점을 요약해줘.

시나리오 D. README 업데이트

README를 실제 프로젝트 상태에 맞게 업데이트해줘.

작업 순서:
1. package.json 확인
2. env example 확인
3. 현재 폴더 구조 확인
4. README의 오래된 명령 찾기
5. 설치, 실행, 테스트, 빌드, 배포 섹션 업데이트

주의:
- 실제로 존재하지 않는 명령을 쓰지 말 것
- 추측하지 말고 파일에서 확인할 것
- 환경 변수는 이름만 설명하고 실제 secret은 포함하지 말 것

시나리오 E. 코드 리뷰

현재 diff를 독립 리뷰어 관점에서 검토해줘.

확인할 것:
- 요구사항 누락
- 엣지 케이스
- 테스트 부족
- 보안 문제
- 기존 패턴 위반
- 범위 밖 변경

제외할 것:
- 취향 기반 스타일 제안
- 과도한 추상화
- 실제 문제 없는 방어적 코드 제안

출력 형식:
1. 치명적 문제
2. 수정 권장
3. 선택 사항
4. 통과 여부

28AI 개발팀 운영 모델

Claude Code를 한 명의 만능 작업자로 쓰기보다 역할을 나누면 더 안정적입니다.

가상 이름	역할	하는 일
리오	기획자	요구사항 정리, 완료조건 정의
미라	구현자	코드 수정, 기능 개발
노아	검증자	테스트, 빌드, 실행 확인
세나	리뷰어	보안, 엣지 케이스, 범위 이탈 검토
유진	기록자	변경 내용과 결과 문서화

운영 흐름

리오 · 요구사항 정리→미라 · 탐색 및 구현→노아 · 테스트/빌드 검증→세나 · 독립 리뷰→유진 · 보고와 문서화

핵심

구현자와 검증자를 분리하라.
코드를 만든 AI가 자기 결과를 스스로 채점하게 하지 마라.

29작업 전 체크리스트

Claude Code에게 일을 맡기기 전에 아래를 확인하세요.

목표가 한 문장으로 명확한가?
수정 범위를 지정했는가?
관련 파일이나 폴더를 알려주었는가?
현재 증상과 기대 결과를 설명했는가?
완료 기준이 있는가?
테스트, 빌드, lint, 스크린샷 등 검증 방법이 있는가?
범위 밖 작업을 금지했는가?
위험한 명령에 권한 제한을 걸었는가?
긴 조사는 subagent로 분리했는가?
구현 후 독립 리뷰를 붙였는가?
결과 보고 형식을 지정했는가?
context가 너무 오래되었거나 지저분하지 않은가?

30바로 복사해서 쓰는 기본 템플릿

버그 수정 템플릿

다음 버그를 수정해줘.

증상:
[문제 설명]

관련 위치:
[파일 또는 폴더]

완료 기준:
1. 문제를 재현하는 실패 테스트 작성
2. 근본 원인 설명
3. 코드 수정
4. 관련 테스트 실행
5. 빌드 또는 typecheck 실행

주의:
- 에러를 숨기지 말 것
- 테스트를 약화하지 말 것
- 범위 밖 리팩터링 금지

마지막에는 변경 파일, 실행한 명령, 결과, 남은 위험을 요약해줘.

기능 개발 템플릿

다음 기능을 구현하고 싶어.

기능:
[기능 설명]

먼저 코드를 수정하지 말고 조사와 계획만 해줘.
계획에는 다음을 포함해줘.

1. 관련 파일
2. 현재 구조
3. 구현 전략
4. 테스트 전략
5. 위험 요소
6. 내가 결정해야 할 질문

내가 승인하기 전까지 구현하지 마.

리뷰 템플릿

현재 diff를 독립 리뷰어 관점에서 검토해줘.

확인할 것:
- 요구사항 누락
- 엣지 케이스
- 테스트 부족
- 보안 문제
- 기존 패턴 위반

제외할 것:
- 취향 기반 스타일 제안
- 과도한 추상화
- 범위 밖 개선 제안

결과는 치명적 문제, 수정 권장, 선택 사항으로 나눠줘.

31최종 정리

Claude Code 공식 문서의 핵심은 단순합니다.

AI 코딩 에이전트는 강력하지만, 그냥 맡기면 불안정하다.
목표, 맥락, 검증 기준, 권한 제한, 리뷰 구조를 함께 줘야 한다.

AI 코딩을 잘하는 사람은 단지 프롬프트를 길게 쓰는 사람이 아닙니다. AI가 실수하지 않도록 일의 구조를 설계하는 사람입니다.

기억해야 할 7가지

Claude Code는 챗봇이 아니라 작업자다.
작업에는 반드시 검증 기준이 있어야 한다.
복잡한 일은 탐색, 계획, 구현을 분리한다.
프롬프트에는 파일, 증상, 기대 결과, 제약조건을 넣는다.
CLAUDE.md는 짧고 강하게 유지한다.
context가 오염되면 /clear, /compact, /rewind를 사용한다.
구현자와 리뷰어를 분리해 독립 검증한다.

마지막으로 가장 중요한 문장은 이것입니다.

AI 코딩의 핵심은 더 좋은 도구를 찾는 것이 아니라, AI가 검증 가능한 방식으로 일하게 만드는 운영 구조를 갖추는 것이다.

참고 자료

Anthropic Claude Code Docs — Claude Code 모범 사례
https://code.claude.com/docs/ko/best-practices
첨부 PDF: Claude Code 모범 사례 - Claude Code Docs.pdf

↑

찰리초이 스토리 블로그