17. 흔한 실수 피하기¶

Claude Code를 쓰다 보면 누구나 같은 함정에 빠집니다. 미리 알면 피할 수 있어요.

"같은 실수를 반복하는 건 AI 탓이 아니라, 사용법을 모르기 때문입니다"

실수 1: 컨텍스트를 관리하지 않는다¶

증상: 앞에서 한 이야기를 AI가 까먹는다. 대화가 길어질수록 답변 품질이 뚝 떨어진다.

원인: Claude의 컨텍스트 창은 유한합니다. 대화가 길어지면 초반 내용이 희석됩니다. 오래된 컨텍스트는 상한 우유와 같아요.

상황	해결책
새로운 주제로 전환	`/clear`로 깨끗하게 시작
맥락 유지하며 토큰 절약	`/compact`로 압축
대화가 너무 길어진 경우	HANDOFF.md 작성 후 `/clear`

대화가 길어지면 HANDOFF.md를 만들어서 컨텍스트를 인계하세요.

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

그다음 /clear 후 @HANDOFF.md 읽고 작업 이어가줘로 새 세션을 시작합니다.

# 잘못된 패턴
> "로그인 기능 구현해줘"  ← 500줄 대화
> "아 참, 대시보드 UI도 개선해줘"  ← 컨텍스트 오염

# 올바른 패턴
> (탭 1) 로그인 기능 구현
> (탭 2) 대시보드 UI 개선  ← 별도 세션

황금 원칙: 하나의 대화 = 하나의 목적

여러 주제를 한 대화에서 섞으면 성능이 크게 떨어질 수 있어요. 새 터미널 탭을 여는 습관을 들이세요.

실수 2: CLAUDE.md에 모든 걸 넣는다¶

증상: CLAUDE.md에 적었는데 AI가 안 따른다. 파일이 300줄을 넘어간다.

원인: CLAUDE.md는 매 대화마다 통째로 컨텍스트에 올라갑니다. 너무 많은 지시는 지시가 없는 것과 같아요.

60줄 원칙: 핵심 컨벤션만 유지합니다.

# ✅ CLAUDE.md에 넣을 것
- 기술 스택 버전 (React 18, Node 20)
- 팀 핵심 컨벤션 (pnpm, 커밋 형식)
- 절대 하면 안 되는 것 (DO NOT 목록)

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

@import로 파일 분리

<!-- CLAUDE.md -->
## 코딩 스타일
@docs/coding-style.md

자주 바뀌는 규칙은 Hooks로 처리하세요. 실행 시 동적으로 주입되니까 CLAUDE.md를 오염시키지 않습니다.

60줄 원칙을 지키면 AI가 중요한 규칙을 더 잘 따릅니다.

실수 3: "고쳐줘" 한 마디만 던진다¶

증상: AI가 엉뚱한 곳을 고친다. 의도와 전혀 다른 방향으로 수정된다.

원인: "고쳐줘"는 정보가 없습니다. AI는 추측으로 채울 수밖에 없고, 추측은 틀립니다.

컨텍스트 4요소를 갖춰서 요청하세요.

요소	예시
파일/함수 위치	`src/auth/login.ts`의 `handleLogin` 함수
에러 메시지	`TypeError: Cannot read properties of undefined`
기대 동작	로그인 성공 시 `/dashboard`로 이동해야 함
추정 원인	`user` 객체가 null일 때 처리가 없는 것 같음

# ❌ 나쁜 요청
> "로그인이 안 돼, 고쳐줘"

# ✅ 좋은 요청
> "src/auth/login.ts의 handleLogin 함수에서
> 'Cannot read properties of undefined (reading name)' 에러가 납니다.
> 로그인 성공 후 /dashboard로 이동해야 하는데,
> user 객체가 null일 때 처리가 없는 것 같아요."

에러 메시지는 그대로 붙여넣으세요. 요약하면 중요한 정보가 사라집니다.

"이 파일의 X 함수에서 Y 에러가 나는데, Z가 원인인 것 같아" 형태가 가장 좋아요.

실수 4: 큰 작업을 한 번에 시킨다¶

증상: "전체 리팩토링 해줘" 요청 후 일부만 됨. 중간에 컨텍스트가 소진되어 끊긴다.

원인: 거대한 요청은 AI도 감당하기 어렵습니다. 컨텍스트가 소진되면 검증도 안 됩니다.

직접 경로 (실패 확률 높음):   A ──────────────────→ B
단계적 경로 (성공 확률 높음): A → A1 → A2 → A3 → B
                                   ✓     ✓     ✓

한 번에 3-5개 파일 이하로 제한하고, 각 단계마다 검증합니다.

# ✅ 좋은 요청 (단계 분해)
> 1단계: "users 테이블 스키마 확인하고 타입 정의 작성해줘"
> (검증 후)
> 2단계: "로그인 API 엔드포인트 리팩토링해줘"
> (검증 후)
> 3단계: "JWT 토큰 갱신 로직 분리해줘"

Plan 모드 (Shift+Tab ×2)로 계획 먼저 세우고 승인 후 실행하세요. "두 번 생각하고, 한 번 실행"입니다.

각 단계에서 문제가 생기면 그 단계만 고치면 돼요. 전체를 다시 할 필요가 없거든요.

실수 5: AI의 답변을 검증하지 않는다¶

증상: AI가 생성한 코드를 그대로 커밋한다. 나중에 숨겨진 버그나 보안 취약점이 발견된다.

원인: AI는 자신감 있게 틀립니다. 할루시네이션, 구버전 API 사용, 엣지 케이스 누락이 언제든 일어납니다.

AI 결과물도 코드 리뷰 대상입니다.

검증 방법	언제
코드 diff 직접 확인	매번
테스트 실행	로직 변경 시
추가 리뷰 요청	중요한 기능
GitHub Desktop 시각적 확인	커밋 전

> "방금 작성한 코드를 리뷰해줘.
> 잠재적 버그, 엣지 케이스, 보안 이슈를 확인하고
> 검증 가능한 것과 불확실한 것을 구분해줘."

02. AI 마인드셋에서 다룬 인지 오프로딩의 위험성을 기억하세요. 검증을 건너뛰면 실력도 같이 멈춥니다.

테스트도 AI에게 함께 요청하세요.

> "이 함수의 단위 테스트를 작성해줘.
> 성공 케이스, 실패 케이스, 엣지 케이스를 모두 포함해줘."

실수 6: `/init`이나 CLAUDE.md 없이 시작한다¶

증상: AI가 팀 컨벤션을 무시한다. 쓰지 않는 라이브러리를 사용한다. 매번 같은 설명을 반복한다.

원인: 컨텍스트 없이는 AI가 범용 코드를 씁니다. 팀의 패턴, 금지 사항, 기술 스택을 모르니까요.

새 프로젝트 시작 시 /init 필수입니다.

/init

Claude가 코드베이스를 분석해서 CLAUDE.md 초안을 만들어줘요. 초안에 팀 고유 규칙을 추가하고 팀원과 공유하세요. CLAUDE.md는 팀의 공유 지식이에요.

# CLAUDE.md 최소 구성
## 기술 스택
- React 18, TypeScript 5.3
- pnpm (npm, yarn 금지)

## 금지 사항 (DO NOT)
- console.log 커밋 금지
- any 타입 사용 금지

실수 7: 하나의 세션에서 모든 걸 한다¶

증상: 구현, 리뷰, 문서화를 같은 대화에서 한다. 리뷰가 형식적이 된다.

원인: 구현자 모드의 AI는 자기 코드에 관대합니다. 같은 세션에서 리뷰를 요청하면 "잘 작성되었습니다"로 끝나기 쉬워요.

역할별로 세션을 분리하세요.

세션	역할	특징
구현 세션	코드 작성	빠른 속도
리뷰 세션	비판적 검토	편견 없는 새 관점
문서화 세션	설명 작성	독자 관점

> (새 세션에서)
> "@src/auth/login.ts 코드를 보안 관점에서 리뷰해줘.
> 구현자가 아닌 보안 전문가 입장에서 취약점을 찾아줘."

07. 왜 CLI인가에서 다룬 멀티 인스턴스 전략을 활용하면 더 좋아요.

같은 코드를 두 번 보는 것처럼, 다른 세션의 AI는 편견 없이 문제를 발견합니다.

실수 8: 버전/환경 정보를 제공하지 않는다¶

증상: AI가 deprecated된 API를 사용한다. 코드가 내 환경에서 안 돌아간다.

원인: "React에서..."라고 하면 AI는 어떤 버전인지 모릅니다. React 16의 답변을 React 18 환경에서 쓰면 당연히 문제가 생겨요.

CLAUDE.md에 기술 스택 버전을 명시하세요.

## 기술 스택
- React 18.3.1
- Next.js 15.1.0
- TypeScript 5.7.2
- Node.js 20 LTS
- pnpm 9.x

# ❌ 모호한 요청
> "React에서 상태 관리하는 방법 알려줘"

# ✅ 구체적인 요청
> "React 18.3 환경에서 Server Actions와 함께 폼 상태 관리하는 방법 알려줘"

Context7 MCP를 설치하면 AI가 최신 라이브러리 문서를 알아서 참조해요. deprecated API 사용 문제가 대폭 줄어듭니다.

claude mcp add -s user context7 npx context7-mcp

실수 9: 하나의 대화에서 여러 주제를 섞는다¶

증상: 대화 중반부터 AI가 이전 맥락을 잃거나 엉뚱한 답을 한다.

원인: 로그인 기능을 만들다가 "아 참, 대시보드 UI도 수정해줘"라고 하면 두 주제의 컨텍스트가 섞여서 컨텍스트 오염이 생깁니다.

해결:

# 나쁜 패턴
> (같은 대화에서)
> "로그인 API 구현해줘"
> ... 200줄 대화 ...
> "아 참, 대시보드 차트도 바꿔줘"  ← 컨텍스트 오염!

# 좋은 패턴
> (터미널 탭 1) 로그인 API 구현
> (터미널 탭 2) 대시보드 차트 수정  ← 독립 세션

황금 원칙: 하나의 대화 = 하나의 목적

터미널 탭을 여는 건 공짜예요. 주제가 바뀌면 새 탭을 여세요.

실수 10: /clear를 쓸 타이밍을 모른다¶

증상: 언제 /clear를 해야 하는지 몰라서 품질이 떨어진 대화를 계속 끌고 간다. 반대로 필요한 맥락까지 날려버리기도 한다.

원인: /clear와 /compact의 차이를 모르면 타이밍을 잡기 어렵습니다.

명령	동작	사용 시점
`/clear`	대화 전체 초기화	주제 전환, 새 작업 시작
`/compact`	기존 맥락 요약 압축	같은 작업 중 토큰 절약

/clear 해야 할 때: - 이전 주제와 완전히 다른 새 작업을 시작할 때 - AI 답변 품질이 눈에 띄게 떨어질 때 - 논리적 단위의 작업이 끝났을 때

/clear 하면 안 될 때: - 현재 작업이 진행 중일 때 (맥락 손실!) - 아직 참조할 대화 내용이 남아 있을 때

💡 Status Line 활용 팁: Status Line에서 컨텍스트 사용량을 실시간으로 확인할 수 있어요. 게이지가 80%를 넘으면 /clear 또는 /compact를 고려하세요.

실수 11: HANDOFF.md를 활용하지 않는다¶

증상: 긴 대화 후 /clear를 하면 모든 맥락이 날아간다. 다음 날 이어서 하려면 처음부터 다시 설명해야 한다.

원인: 세션 간 컨텍스트를 인계하는 방법을 모릅니다.

해결: 작업을 마무리하기 전에 HANDOFF.md를 만드세요.

> "지금까지 작업 내용을 HANDOFF.md로 정리해줘.
> 완료된 것, 실패한 것, 다음 단계, 핵심 결정사항을 포함해줘."

HANDOFF.md 템플릿:

# Handoff: [작업명]

## 완료된 것
- 로그인 API 엔드포인트 구현 (src/auth/login.ts)
- JWT 토큰 발급 로직 완성

## 실패한 것 / 미해결
- 리프레시 토큰 갱신 시 race condition 발생
- 테스트 2개 실패 중

## 핵심 결정사항
- 토큰 만료 시간: 1시간 (보안팀 요구)
- Redis 대신 인메모리 캐시 사용 (MVP 단계)

## 다음 단계
1. race condition 해결 (src/auth/refresh.ts:45)
2. 실패 테스트 수정
3. 로그아웃 엔드포인트 추가

워크플로우: 작업 → HANDOFF.md 생성 → /clear → @HANDOFF.md 읽고 이어서 작업해줘

HANDOFF.md를 만들어야 할 때: - 대화가 길어져서 /clear가 필요할 때 - 퇴근 전, 내일 이어서 할 작업이 있을 때 - 컨텍스트 한도가 가까워졌을 때 - 다른 사람이나 다른 세션에 작업을 넘길 때

자가 진단 체크리스트¶

지금 당장 확인해보세요. 체크 안 된 항목이 바로 개선 포인트에요.

6개 이상이면 좋은 습관이에요. 체크 안 된 항목부터 하나씩 바꿔보세요.

작은 습관 하나가 매일 쌓이면 큰 차이를 만듭니다.

다음 단계¶

흔한 실수를 알았다면 18. 추천 리소스에서 더 깊이 배울 수 있는 자료를 찾아보세요.