21. 모범 사례¶

Claude Code를 효과적으로 쓰는 검증된 패턴과 팁이에요.

핵심: 좋은 결과는 좋은 입력에서 나와요. 컨텍스트를 아끼고, 검증 방법을 미리 정하고, 구체적으로 전달하는 게 전부예요.

원칙 1: 컨텍스트는 가장 소중한 자원¶

왜: Claude의 사고 깊이는 남은 컨텍스트 크기에 정비례해요. 컨텍스트가 차면 성능이 급격히 떨어져요.

컨텍스트 절약 3가지 패턴¶

상황	해결책	효과
새 주제 시작	`/clear` 사용	깨끗한 상태에서 새 사고
대화 너무 길어짐	HANDOFF.md 작성 → `/clear`	작업 이력 보존 + 토큰 절약
진행 중 방향 수정	Esc → `/rewind` 또는 `/clear`	중간 결과 버리고 재시작

실전 패턴: HANDOFF 방식¶

> "지금까지 작업한 내용을 HANDOFF.md로 정리해줘.
> 완료된 것, 실패한 것, 다음 단계를 명확히 적어."

// 그 후
> `/clear`

// 새 세션에서
> "@HANDOFF.md 읽고 작업 이어가줘"

황금 원칙: 하나의 대화 = 하나의 목적. 로그인 기능과 대시보드 UI는 별도 탭에서 진행하세요.

원칙 2: 검증 방법을 미리 정하고 전달¶

왜: "제대로 됐는지 어떻게 알지?"를 AI와 함께 정의하면, 완료도 빨라지고 품질도 올라가요.

Before/After: 검증 없는 vs 있는 요청¶

Before (검증 없음)	After (검증 있음)
"이메일 검증 함수 구현해"	"validateEmail 함수 구현. test@example.com은 true 반환, invalid@는 false 반환해야 함. 구현 후 테스트 실행 결과 보여줘"
"대시보드 디자인 예쁘게 해"	"[스크린샷 붙여넣기] 이렇게 생겼어야 해. 구현 후 결과 스크린샷 찍어서 내가 비교할 수 있게 해"
"API 응답 처리해"	"POST /api/users 응답이 `{ id, name, email, createdAt }`이고, 400 에러는 `{ code, message }` 형태야. 각 경우 처리 후 콘솔로 결과 로그 보여줘"

UI 검증 꿀팁¶

Chrome 확장: "Take Screenshot" → AI와 함께 Before/After 비교

1. 현재 상태 스크린샷 캡처
2. "이렇게 보여야 해" (기대 스크린샷 붙여넣기)
3. AI: 구현 후 스크린샷 자동 캡처
4. 나: 나란히 비교

코드 검증

> "구현 후:
>  1. pnpm test:run으로 테스트 실행
>  2. pnpm check-types로 타입 확인
>  3. 콘솔에 테스트 결과 캡처해줘"

원칙 3: 탐색 → 계획 → 구현 순서¶

왜: 프로젝트를 모를 때 바로 구현하면 실수하기 쉬워요. 작은 것부터라도 계획하세요.

4단계 프로세스¶

1️⃣ 탐색 (Shift+Tab Plan Mode)
   ├─ "프로젝트 구조 설명해줘"
   ├─ "기존 컴포넌트 패턴은?"
   └─ "이 기능 구현할 때 주의할 점?"

2️⃣ 계획 세우기
   ├─ "구현 단계를 정리해줘"
   ├─ "어느 파일에서 작업할지 리스트 업"
   └─ "완료 기준은?"

3️⃣ 구현 (Normal Mode)
   ├─ "첫 번째 단계 시작"
   └─ 한 두 단계씩 진행

4️⃣ 커밋
   ├─ "변경사항 정리해줄래?"
   └─ git add/commit

간단한 작업은 계획 스킵 가능¶

# 간단한 작업: 계획 스킵
> "이 함수에서 에러 처리만 추가해줄래?"

# 복잡한 작업: 계획 필수
> "전체 아키텍처 개편 필요한데 어디서부터 시작할까?"
> (Plan Mode에서 깊이 있게 논의)

원칙 4: 구체적 컨텍스트 제공¶

왜: "뭔가 안 돼"보다 "이 파일 이 줄에서 이런 에러가 났어"가 100배 빨라요.

컨텍스트의 5가지 소스¶

소스	사용법	효과
파일 범위	`src/auth/` 내 파일만 보기	불필요한 코드 필터링
기존 패턴	"@components/Button.tsx처럼 구현해"	일관성 유지
에러 메시지	TypeError 전체 텍스트 복사	정확한 진단
스크린샷	UI 문제는 사진으로	눈으로 확인 가능
URL/파이프	`cat file.ts \\| Claude Code`	바로 분석 가능

실전 예시¶

# ❌ 약한 요청
> "로그인 페이지 개선해"

# ✅ 강한 요청
> "@src/pages/login 파일 읽고,
>  기존 스타일과 동일하게 유지하면서
>  [첨부 스크린샷] 이렇게 보이게 변경해줄래?
>  완료 후 스크린샷 찍어서 비교하자"

원칙 5: 환경 설정으로 반복 최소화¶

CLAUDE.md: 효과적인 작성법¶

# ✅ CLAUDE.md에 들어갈 것 (60줄 이하)
- 기술 스택 버전 (React 18, pnpm 8)
- 팀 핵심 규칙 (커밋 형식, 브랜치 네이밍)
- 절대 하면 안 되는 것 (destructive git command 금지)

# ❌ CLAUDE.md에 넣지 말 것
- 린팅 규칙 → Hooks로 이동
- 자주 바뀌는 정보 → 대화에서 제공
- 긴 코딩 가이드 → 별도 파일 @import로 분리

60줄 원칙: AI가 중요한 규칙을 놓치지 않으려면, 정말 중요한 것만 넣으세요.

권한 & 샌드박스 설정¶

# 권한 확인
/permissions

# 샌드박스 모드 (로컬 테스트용)
/sandbox

CLI 도구 연결¶

# Git 작업 자동화
gh issue create, gh pr create

# AWS/GCP 배포
aws deploy, gcloud deploy

# 도커/쿠버네티스
docker run, kubectl apply

# 데이터베이스
psql, mysql

"CLI 도구 써서 배포 자동화해줄래?" 하면 바로 돼요.

MCP 서버 연결¶

# 공식 MCP 서버
claude mcp add github    # GitHub API
claude mcp add figma     # Figma 디자인
claude mcp add notion    # Notion 데이터

MCP 연결되면 "@figma 이 디자인 구현해" 한 줄로 끝나요.

Hooks 설정¶

// .claude/settings.json
{
  "hooks": [
    {
      "event": "tool-use",
      "tool_name": "bash",
      "command": "pnpm lint --fix"
    }
  ]
}

Skills 커스텀¶

# 나만의 스킬 만들기
/skill create my-deploy "배포 자동화"

# 팀용 스킬
/skill share team-format "코딩 스타일 통일"

원칙 6: 효과적인 소통 방법¶

방법 1: 시니어 엔지니어처럼 질문하기¶

# ❌ 애매한 질문
> "이 코드 맞아?"

# ✅ 구체적인 질문
> "이 useEffect에서 의존성 배열이 비어있는데,
>  마운트 시에만 한 번 실행되는 게 맞나?
>  아니면 user 객체 변경도 감지해야 해?"

방법 2: 인터뷰 방식으로 진행하기¶

> "다음 3가지 물어볼게. 답변해주면 구현 계획 세워줄게.
>  1. 이 폼에서 서버 검증이 필요해?
>  2. 에러 메시지를 사용자한테 어떻게 보여줄래?
>  3. 제출 후 리다이렉트 어디로?"

장점: 요구사항 불명확할 때 조사 시간 50% 절약

방법 3: 브레인스토밍 vs 구현 분리¶

# Plan Mode: 아이디어 수집 (Shift+Tab)
> "이 기능 4가지 방법으로 구현할 수 있는데,
>  각 방법의 장단점 비교해줄래?
>  어느 방법이 우리 코드스타일과 맞을 것 같아?"

# Normal Mode: 선택된 방법만 구현
> "위에서 정한 방법 1로 구현 시작할게"

원칙 7: 세션 관리 기술¶

세션 끝낼 때¶

# 1. 수정 2회 이상 시: /clear 후 재시작
Esc → "수정 안 맞았어" → Esc → `/clear` → 재시도

# 2. 방향 180도 바꿀 때: /rewind
Esc+Esc → `/rewind` → 마지막 Claude 응답을 취소하고 이전 상태로 되돌리기

# 3. 다른 주제로 넘어갈 때
`/clear` 후 새로 시작

세션 이어갈 때¶

# 같은 터미널에서 이어가기
--continue (이전 작업 자동 로드)

# 다른 장소에서 재개하기
--resume (세션 ID로 복구)

# 체크포인트 저장하기
/checkpoint save "로그인 기능 완료"

컨텍스트 절약 팁¶

# 1. 서브에이전트로 조사 위임
"이 라이브러리의 최신 API 문서 찾아줄 수 있어?
 (내 컨텍스트 낭비하지 말고 따로 조사해줘)"

# 2. 병렬 세션 활용
탭 1: 로그인 기능
탭 2: 대시보드 UI
탭 3: API 통합
→ 각각 독립적으로 진행, 마지막에 병합

# 3. 자동 정리
/compact (오래된 대화를 요약하여 컨텍스트 윈도우 확보)

원칙 8: 자동화와 확장¶

헤드리스 모드: 자동 실행¶

# CLI로 스크립트 작업 자동화
claude -p "스크린샷 최적화 배치 작업"

# 예약 작업
cron: claude -p "매일 테스트 레포트 생성"

병렬 세션¶

데스크탑 Claude Code (메인 작업)
├─ 웹 Claude Chat (조사용)
└─ Agent Teams (팀 협업)

→ 각자 독립적 컨텍스트, 토큰 효율 극대화

팬아웃: 파일별 루프¶

큰 프로젝트 개편 시:
1. 파일 A 수정 완료
2. 파일 B 수정 완료  ← 병렬 처리 가능
3. 파일 C 수정 완료
4. 통합 테스트

Writer/Reviewer 패턴¶

Writer 세션: 코드 작성
    ↓ (결과 핸드오프)
Reviewer 세션: 코드 리뷰 + 린팅

작성과 리뷰를 다른 세션에서 하면 훨씬 객관적으로 볼 수 있어요.

원칙 9: 흔한 실패 패턴 5가지¶

패턴 1: Kitchen Sink 세션¶

증상: "이것도 해줄래? 저것도?" → 50줄 대화

해결: 새 탭 열어서 분산. 한 탭 = 하나의 목적

패턴 2: 무한 반복 수정¶

증상: "다시 해줄래?" "아니 이렇게" "이것도"...

해결: 2회 실패 시 /clear + 다시 계획하기

실패 1회: "다시 해봐"
실패 2회: `/clear` → 계획 단계부터 다시

패턴 3: CLAUDE.md 과부하¶

증상: 300줄 이상 → AI가 중요한 규칙을 놓침

해결: 60줄 원칙 유지. 나머지는 Hooks로 관리

패턴 4: Trust-Then-Verify 갭¶

증상: "구현해줘" → 바로 커밋 → 나중에 버그 발견

해결: 항상 검증 방법을 먼저 정의

나쁜 순서: 요청 → 구현 → (알아서 확인해)
좋은 순서: 요청 + 검증방법 정의 → 구현 + 검증 → 커밋

패턴 5: 무한 탐색¶

증상: "코드 봐줄래?" 10분 탐색 → "어떻게 하면 좋을까?" 또 탐색

해결: Plan Mode에서 깊이 있게 한 번에 해결

# 나쁜 방식
탐색 1 → "어때?" → 탐색 2 → "뭐할까?" → 탐색 3

# 좋은 방식
Plan Mode에서 전체 상황 분석 → 계획 수립 → 구현

체크리스트: 다음 작업 시 써보기¶

요청 전 체크¶

컨텍스트 윈도우 여유 있는가? (아니면 /clear)
이 요청의 검증 방법을 미리 정했는가?
파일/함수/에러 메시지처럼 구체적인가?
스크린샷이나 코드 예제가 있는가?
이 작업이 다른 탭과 독립적인가?

작업 중 체크¶

2회 이상 수정했으면 /clear 고려?
검증이 진행 중인가?
컨텍스트가 차고 있지는 않은가?
Plan Mode와 Normal Mode를 구분했는가?

작업 후 체크¶

스크린샷/테스트로 검증했는가?
커밋 메시지가 명확한가?
HANDOFF 필요한가?

다음 단계¶

한 번에 다 바꾸려 하지 말고, 다음 작업부터 하나씩 써보세요.

첫 번째: 검증 방법 먼저 정하고 시작하기
두 번째: Plan Mode로 계획 세운 뒤 구현하기
세 번째: 컨텍스트 먼저 모으고 요청하기

습관이 되면 나머지는 자연스럽게 따라와요.

참고 자료¶

13. 파워 유저 가이드 - ykdojo의 70가지 팁
14. 프로젝트 초기화 - /init으로 환경 셋업
15. CLAUDE.md 마스터하기 - 60줄 원칙 상세
16. Hooks 실전 가이드 - 자동화 레시피
17. 흔한 실수 피하기 - 함정과 해결책
06. 팀 세션 가이드 - 팀 협업