테마
11. 프롬프트 엔지니어링 & 토큰 최적화
효과적인 프롬프트 작성법과 컨텍스트 관리 전략을 익혀 Claude Code의 잠재력을 최대한 끌어낸다.
1. 프롬프트 엔지니어링이 중요한 이유
Claude Code는 강력한 도구지만, 결국 사용자가 무엇을 어떻게 요청하느냐에 따라 결과 품질이 결정된다. 같은 모델, 같은 설정이라도 프롬프트 하나로 결과물이 완전히 달라진다.
프롬프트 품질이 만드는 차이
| 항목 | 나쁜 프롬프트 | 좋은 프롬프트 |
|---|---|---|
| 범위 | 모호하고 열린 요청 | 구체적이고 제한된 요청 |
| 생성 코드량 | 불필요한 코드 폭발 | 필요한 만큼만 생성 |
| 토큰 소비 | 입출력 토큰 대량 낭비 | 효율적 토큰 사용 |
| 수정 횟수 | 반복 수정 필요 | 한 번에 원하는 결과 |
| 개발 속도 | 오히려 수동보다 느림 | 수동 대비 5~10배 빠름 |
나쁜 프롬프트의 악순환
반대로, 좋은 프롬프트는 다음과 같은 선순환을 만든다.
명확한 프롬프트 → 정확한 범위 파악 → 최소한의 코드 생성 → 토큰 절약
→ 한 번에 원하는 결과 → 수정 불필요 → 컨텍스트 여유 → 다음 작업 가능핵심 원칙
- 범위를 명시하라: 무엇을 만들지뿐 아니라 무엇을 제외할지도 말해야 한다.
- 컨텍스트를 제공하라: 관련 파일, 에러 메시지, 기술 스택 정보를 함께 전달하라.
- 한 번에 하나씩: 거대한 요청 하나보다 작은 요청 여러 개가 낫다.
2. 나쁜 프롬프트 vs 좋은 프롬프트
프롬프트의 품질 차이를 구체적인 예시로 비교한다.
범위를 제한하는 핵심 키워드
좋은 프롬프트에는 범위를 명확히 제한하는 키워드가 포함된다.
| 키워드 | 용도 | 예시 |
|---|---|---|
| ~만 | 사용 기술 제한 | "HTML과 CSS만 사용해서" |
| ~에 한해서 | 작업 범위 제한 | "이 함수에 한해서 리팩토링해줘" |
| ~없이 | 기능 제외 | "인증 기능 없이 구현해줘" |
| ~을 제외하고 | 특정 항목 제외 | "배포 설정을 제외하고 만들어줘" |
| ~하지 마 | 금지 사항 명시 | "새 파일을 생성하지 마" |
| 기존 ~ 유지 | 변경 금지 | "기존 스타일을 유지하면서 기능만 추가해줘" |
비교 예시 상세
예시 1: 새 기능 개발
[나쁜 프롬프트]
"채팅 앱을 만들어줘"
→ Claude가 생성하는 것: WebSocket 서버, 데이터베이스 스키마, 인증 시스템,
프론트엔드 UI, 배포 스크립트, Docker 설정 등
→ 토큰 소비: 막대함
→ 실제로 원했던 것: 간단한 채팅 UI 프로토타입[좋은 프롬프트]
"React와 Tailwind CSS만 사용해서 채팅 UI 컴포넌트를 만들어줘.
백엔드 연동 없이 하드코딩된 더미 데이터로 화면만 구성해줘.
메시지 입력, 전송 버튼, 메시지 목록 표시 기능만 포함해."
→ Claude가 생성하는 것: ChatRoom.tsx, MessageList.tsx, MessageInput.tsx
→ 토큰 소비: 최소한
→ 정확히 원하는 결과예시 2: 버그 수정
[나쁜 프롬프트]
"로그인이 안 돼"
→ Claude: 어떤 프로젝트? 어떤 인증 방식? 어떤 에러?
→ 전체 코드를 스캔하면서 토큰 소비
→ 추측에 기반한 수정 → 다른 곳이 깨질 수 있음[좋은 프롬프트]
"@src/auth/login.ts 에서 로그인 시 다음 에러가 발생해:
'TypeError: Cannot read properties of undefined (reading 'token')'
Supabase signInWithPassword 응답 처리 부분을 확인하고 수정해줘."
→ Claude: 해당 파일의 해당 함수만 확인
→ 에러 원인 정확히 파악 → 최소한의 수정
→ 토큰 절약 + 정확한 결과3. 컨텍스트 제공 전략
Claude Code에게 무엇을 요청하는가도 중요하지만, 어떤 정보를 함께 주는가가 결과 품질을 결정한다. 컨텍스트를 잘 제공하면 Claude가 프로젝트를 탐색하느라 낭비하는 토큰을 크게 줄일 수 있다.
3.1 파일 참조 (@파일명)
Claude Code에서 @를 사용하면 특정 파일을 컨텍스트에 직접 로드할 수 있다. 이것은 Claude가 스스로 파일을 찾아 읽는 것보다 훨씬 효율적이다.
# 파일 참조 기본
@CLAUDE.md 에 어떤 규칙이 적혀있어?
# 참고 파일을 지정한 개발
@roadmap.md 를 참고해서 다음 마일스톤의 기능을 개발해줘
# 여러 파일 동시 참조
@src/types/user.ts 와 @src/api/userService.ts 를 참고해서
새로운 getUserProfile 함수를 추가해줘
# 설정 파일 참조
@tsconfig.json 의 paths 설정을 보고 import alias가 왜 동작하지 않는지 확인해줘왜 @참조가 중요한가?
| 방법 | 과정 | 토큰 소비 |
|---|---|---|
| @참조 없이 요청 | Claude가 프로젝트를 탐색 → 관련 파일 검색 → 여러 파일 읽기 | 높음 |
| @참조로 파일 지정 | 지정된 파일만 로드 → 즉시 작업 시작 | 낮음 |
3.2 이미지/스크린샷 활용
Claude Code는 이미지를 이해할 수 있다. 브라우저 스크린샷이나 디자인 시안을 붙여넣으면 시각적 컨텍스트가 추가된다.
# Mac에서 스크린샷 붙여넣기
Cmd + V
# Windows/Linux에서 스크린샷 붙여넣기
Ctrl + V
# 활용 예시
[스크린샷 붙여넣기 후]
"이 화면에서 헤더의 네비게이션 메뉴가 모바일에서 겹치는 문제를 수정해줘"
[디자인 시안 붙여넣기 후]
"이 Figma 디자인과 동일하게 구현해줘. Tailwind CSS를 사용해."3.3 에러 정보 제공
에러 디버깅 요청 시 가장 중요한 컨텍스트는 에러 메시지 자체다.
# 나쁜 예: 에러 메시지 없이 요청
"빌드가 안 돼"
# 좋은 예: 에러 메시지 포함
"npm run build를 실행하면 다음 에러가 발생해:
error TS2345: Argument of type 'string' is not assignable
to parameter of type 'number'.
src/utils/calculate.ts:42:15
이 타입 에러를 수정해줘."에러 정보가 많을수록 Claude의 디버깅 정확도가 올라간다.
| 제공 정보 | 효과 |
|---|---|
| 에러 메시지 텍스트 | 기본적인 원인 파악 가능 |
| 에러 메시지 + 파일 경로 | 정확한 위치에서 수정 가능 |
| 에러 메시지 + 파일 경로 + 스크린샷 | 시각적 상태까지 파악 가능 |
| 에러 메시지 + 파일 경로 + 재현 절차 | 근본 원인까지 해결 가능 |
3.4 웹 레이아웃 용어 활용
UI 관련 작업에서 웹 레이아웃 용어를 사용하면 Claude가 정확히 어떤 영역을 수정해야 하는지 빠르게 파악한다.
| 용어 | 의미 | 사용 예시 |
|---|---|---|
| Header | 페이지 상단 영역 | "Header에 검색 바를 추가해줘" |
| Hero 섹션 | 메인 배너 영역 | "Hero 섹션의 배경 이미지를 변경해줘" |
| Navigation | 메뉴/네비게이션 | "모바일 Navigation을 햄버거 메뉴로 바꿔줘" |
| Sidebar | 측면 패널 | "Sidebar에 카테고리 필터를 추가해줘" |
| Footer | 페이지 하단 영역 | "Footer에 소셜 미디어 링크를 넣어줘" |
| Container | 콘텐츠 래퍼 | "Container 최대 폭을 1200px로 제한해줘" |
| Card | 카드 컴포넌트 | "Card 간격을 24px로 통일해줘" |
| Modal | 팝업 대화상자 | "Modal이 스크롤 되도록 수정해줘" |
| Breadcrumb | 경로 표시 | "Breadcrumb 네비게이션을 추가해줘" |
용어를 정확히 사용하면 Claude가 "어디를 수정할지 파악하기 위해 전체를 읽는" 과정을 건너뛸 수 있다. 이것만으로도 토큰이 절약된다.
4. COT (Chain of Thought) 프롬프트
COT는 Claude에게 단계별로 사고 과정을 전개하도록 유도하는 프롬프트 기법이다. 복잡한 문제일수록 효과가 크다.
기본 사용법
프롬프트 끝에 다음 문구 중 하나를 추가한다.
"단계별로 생각해주세요"
"하나씩 분석해주세요"
"Think step by step"COT 없이 vs COT 포함 비교
[COT 없이]
"이 코드의 메모리 누수를 수정해줘"
→ Claude: 즉시 코드 수정 시도
→ 표면적인 문제만 수정할 가능성
→ 근본 원인을 놓칠 수 있음[COT 포함]
"@src/hooks/useWebSocket.ts 에서 메모리 누수가 발생하고 있어.
단계별로 분석해서 수정해줘."
→ Claude의 사고 과정:
1. 파일 읽기 및 구조 분석
2. useEffect에서 cleanup 함수 확인
3. WebSocket 연결 해제 여부 확인
4. 이벤트 리스너 제거 여부 확인
5. setInterval/setTimeout 해제 여부 확인
6. 원인 특정: cleanup에서 removeEventListener 누락
7. 수정 코드 작성
→ 근본 원인까지 해결COT가 효과적인 상황
| 상황 | 이유 |
|---|---|
| 복잡한 버그 디버깅 | 여러 원인이 얽혀있을 때 하나씩 분리 |
| 아키텍처 설계 | 요구사항 분석 → 구조 설계 → 구현 계획 순서 |
| 성능 최적화 | 병목 지점 분석 → 원인 파악 → 최적화 전략 |
| 마이그레이션 | 현재 상태 파악 → 차이 분석 → 단계별 전환 |
| 보안 검토 | 각 진입점 분석 → 취약점 식별 → 대응 방안 |
Claude Code Plan 모드와의 조합
Claude Code의 Plan 모드 (/model 명령어에서 "plan" 옵션 선택 또는 Shift+Tab으로 전환)와 COT를 함께 사용하면 더 체계적인 결과를 얻을 수 있다.
[Plan 모드에서 COT 활용]
"우리 Next.js 프로젝트에서 서버 컴포넌트와 클라이언트 컴포넌트가
뒤섞여서 hydration 에러가 자주 발생해.
단계별로 분석해서 개선 계획을 세워줘."
→ Plan 모드 + COT 조합:
1. 현재 컴포넌트 구조 분석
2. 'use client' 지시문 사용 패턴 검토
3. hydration 불일치 원인 분류
4. 수정 우선순위 결정
5. 단계별 수정 계획 수립
→ 계획 검토 후 승인하면 실행5. 역할 부여 프롬프트
Claude에게 특정 분야의 전문가 역할을 부여하면, 해당 도메인에 집중한 심층적인 응답을 얻을 수 있다.
기본 패턴
"당신은 [전문 분야] 전문가입니다. [요청]"분야별 역할 부여 예시
프론트엔드 전문가
"당신은 React 성능 최적화 전문가입니다.
@src/components/Dashboard.tsx 에서 불필요한 리렌더링이 발생하는 부분을
찾아서 useMemo, useCallback, React.memo를 적절히 적용해주세요."백엔드 전문가
"당신은 Node.js 보안 전문가입니다.
@src/api/ 디렉토리의 모든 API 엔드포인트에서
SQL 인젝션, XSS, CSRF 취약점이 있는지 검토해주세요."에러 해결 전문가
"당신은 Next.js + Supabase 에러 해결 전문가입니다.
다음 에러를 단계별로 분석해서 해결해주세요:
[에러 메시지]"접근성 전문가
"당신은 웹 접근성(WCAG 2.1 AA) 전문가입니다.
@src/components/Form.tsx 컴포넌트가 접근성 기준을 충족하는지 검토하고,
부족한 부분을 수정해주세요."DevOps 전문가
"당신은 Docker + Kubernetes 전문가입니다.
현재 docker-compose.yml을 분석하고 프로덕션 환경에 맞게
최적화해주세요. 보안 모범 사례를 반영해주세요."역할 부여가 효과적인 이유
역할을 부여하면 Claude가 응답을 생성할 때 해당 분야의 관점과 기준을 우선적으로 적용한다.
역할 없이: "이 코드를 리뷰해줘"
→ 일반적인 코드 리뷰 (문법, 스타일 위주)
역할 부여: "당신은 보안 전문가입니다. 이 코드를 리뷰해줘"
→ 보안 관점의 심층 리뷰 (인증, 인가, 입력 검증, 취약점 위주)역할 + COT + 컨텍스트 조합
세 가지 기법을 조합하면 가장 효과적인 프롬프트가 된다.
"당신은 TypeScript + Next.js 성능 최적화 전문가입니다. ← 역할 부여
@src/app/page.tsx 와 @src/components/ProductList.tsx 에서 ← 컨텍스트
초기 로딩이 5초 이상 걸리는 문제가 있습니다.
단계별로 분석하고 최적화해주세요. ← COT
번들 사이즈 최적화, 이미지 최적화, 서버 컴포넌트 활용에
집중해주세요. API 변경은 하지 마세요. ← 범위 제한"6. 프롬프트 최적화 체크리스트
프롬프트를 작성한 뒤 전송하기 전에 다음 체크리스트를 확인한다. 습관이 되면 자연스럽게 좋은 프롬프트를 쓰게 된다.
체크리스트 요약표
| 번호 | 체크 항목 | 방법 |
|---|---|---|
| 1 | 범위 명확 | "~만", "~없이", "~을 제외하고" 키워드 |
| 2 | 기술 스택 명시 | "React 19 + TypeScript 5.7" 등 버전 포함 |
| 3 | 파일 참조 | @파일경로로 관련 파일 직접 로드 |
| 4 | 에러 메시지 포함 | 콘솔 에러 복사 + 스크린샷 |
| 5 | Plan 모드 | 복잡한 작업은 계획 먼저 수립 |
| 6 | COT 유도 | "단계별로 생각해주세요" 추가 |
7. 에러 디버깅 프롬프트 패턴
에러 디버깅은 Claude Code를 가장 많이 활용하는 시나리오다. 아래 템플릿을 상황에 맞게 변형하면 대부분의 에러를 효과적으로 해결할 수 있다.
범용 에러 디버깅 템플릿
당신은 [기술스택] 에러 해결 전문가입니다.
[페이지/기능]에서 [증상] 오류가 발생합니다.
에러 메시지:
[콘솔 에러 붙여넣기]
관련 파일: @[파일경로]
단계별로 생각해서 해결해주세요.상황별 템플릿
빌드 에러
당신은 TypeScript + Next.js 빌드 에러 전문가입니다.
npm run build를 실행하면 다음 에러가 발생합니다.
에러 메시지:
[빌드 로그 붙여넣기]
@tsconfig.json 과 @next.config.js 를 참고해서
단계별로 분석하고 수정해주세요.
기존 설정 구조는 유지해주세요.런타임 에러
당신은 React 런타임 에러 전문가입니다.
@src/pages/Dashboard.tsx 페이지에서 데이터를 불러올 때
화면이 하얗게 변하는 에러가 발생합니다.
브라우저 콘솔 에러:
[에러 메시지 붙여넣기]
[스크린샷 붙여넣기]
단계별로 원인을 분석하고 수정해주세요.
다른 페이지에는 영향을 주지 마세요.배포 에러
당신은 Vercel + Next.js 배포 전문가입니다.
로컬에서는 정상 동작하지만 Vercel 배포 시 500 에러가 발생합니다.
Vercel 빌드 로그:
[로그 붙여넣기]
환경 변수는 모두 설정했습니다.
@.env.example 에 필요한 변수 목록이 있습니다.
로컬과 배포 환경의 차이를 단계별로 분석해서 해결해주세요.스타일 에러
@src/components/Header.tsx 의 네비게이션 메뉴가
모바일(375px)에서 겹쳐서 보입니다.
[스크린샷 붙여넣기]
Tailwind CSS의 반응형 클래스를 사용해서 수정해주세요.
데스크톱 레이아웃은 변경하지 마세요.디버깅 프롬프트 작성 원칙
- 증상을 구체적으로: "안 돼" 대신 "화면이 하얗게 변한다", "버튼 클릭 시 반응이 없다"
- 재현 조건 명시: "모바일에서만", "로그인 후에만", "3번째 클릭부터"
- 이미 시도한 것: "useEffect 의존성 배열을 수정해봤지만 해결 안 됨"
- 변경 범위 제한: "이 컴포넌트만 수정해줘", "다른 파일은 건드리지 마"
8. CLAUDE.md에 넣으면 좋은 규칙들
CLAUDE.md는 Claude Code가 모든 대화에서 참고하는 프로젝트 메모리다. 여기에 적절한 규칙을 넣어두면 매번 프롬프트에 반복할 필요가 없고, 실수를 예방할 수 있다.
필수 규칙 두 가지
이 두 가지만 추가해도 오류 발생률이 대폭 줄어든다.
markdown
# CLAUDE.md
## 필수 검증
- 작업 완료 후 반드시 `npm run build` 실행하여 빌드 성공 확인
- TypeScript 에러 체크: `npx tsc --noEmit` 실행 후 에러 0개 확인왜 효과가 큰가?
| 규칙 | 방지하는 문제 |
|---|---|
npm run build 확인 | 빌드 에러를 남긴 채 "완료"라고 보고하는 경우 |
npx tsc --noEmit | 타입 에러를 무시하고 런타임에서 터지는 경우 |
Claude Code는 CLAUDE.md에 적힌 규칙을 충실히 따른다. 빌드 확인을 명시하면 Claude가 코드를 수정한 뒤 자동으로 빌드를 실행하고, 에러가 있으면 스스로 수정한다.
추가 권장 규칙
markdown
# CLAUDE.md
## 프로젝트 정보
- 언어: TypeScript 5.7
- 프레임워크: Next.js 15 (App Router)
- 스타일: Tailwind CSS v4
- 패키지 매니저: pnpm
- Node 버전: 22
## 코딩 규칙
- 새 파일 생성 시 기존 파일 구조와 네이밍 컨벤션을 따를 것
- 컴포넌트는 함수 선언문(function) 대신 화살표 함수로 작성
- API 응답은 반드시 에러 처리를 포함할 것
- console.log는 개발 완료 후 제거할 것
## 필수 검증
- 작업 완료 후 반드시 `pnpm build` 실행하여 빌드 성공 확인
- TypeScript 에러 체크: `pnpm tsc --noEmit` 실행 후 에러 0개 확인
- Lint 검사: `pnpm lint` 실행 후 에러 0개 확인
## 금지 사항
- node_modules, .env, .env.local 파일을 수정하거나 생성하지 말 것
- 기존 API 엔드포인트의 응답 형식을 임의로 변경하지 말 것
- 새로운 외부 패키지를 사전 동의 없이 설치하지 말 것CLAUDE.md 작성 팁
| 원칙 | 설명 |
|---|---|
| 간결하게 | 너무 긴 CLAUDE.md는 오히려 토큰을 낭비한다 |
| 명령형으로 | "~하면 좋겠다" 대신 "~할 것" |
| 검증 가능하게 | "코드를 잘 짜라" 대신 "npm run build가 통과할 것" |
| 예외를 명시 | "테스트 파일에서는 any 타입 허용" |
| 업데이트 | 프로젝트가 변하면 CLAUDE.md도 업데이트 |
9. 컨텍스트 = 핵심 무기
AI 네이티브 개발에서 가장 중요한 자원은 컨텍스트 윈도우다. Claude Code의 컨텍스트 윈도우는 유한하며, 여기에 무엇을 넣느냐가 곧 결과의 질을 결정한다.
컨텍스트 관리 전략
AI 네이티브 개발 = 컨텍스트 싸움
전통적인 개발에서 가장 중요한 역량이 "코딩 능력"이었다면, AI 네이티브 개발에서 가장 중요한 역량은 **"컨텍스트를 관리하는 능력"**이다.
전통적 개발: 개발자의 코딩 실력 = 생산성
AI 네이티브: 개발자의 컨텍스트 관리 능력 = 생산성컨텍스트 관리의 핵심 원칙은 다음과 같다.
1. 컨텍스트 윈도우는 유한하다
Claude Code의 컨텍스트 윈도우에는 한계가 있다. 모든 정보를 넣을 수 없으므로, 꼭 필요한 정보만 선별해야 한다.
2. 불필요한 것을 빼는 것이 추가하는 것보다 중요하다
| 행동 | 효과 |
|---|---|
| 사용하지 않는 MCP 서버 비활성화 | 서버 정보가 컨텍스트를 차지하지 않음 |
| 불필요한 서브에이전트 제거 | 에이전트 메타데이터 공간 절약 |
| CLAUDE.md 간결하게 유지 | 매 대화마다 로드되는 양 최소화 |
/clear 습관화 | 이전 작업의 잔여 컨텍스트 정리 |
3. 새 작업 시 /clear를 습관화하라
Claude Code에서 새로운 작업을 시작할 때는 반드시 /clear로 컨텍스트를 초기화해야 한다.
# 이전 작업: API 엔드포인트 개발
# 새 작업: UI 컴포넌트 수정
/clear ← 이전 API 관련 컨텍스트 완전 제거
"@src/components/Header.tsx 의 ← 깨끗한 상태에서 새 작업 시작
반응형 레이아웃을 수정해줘"/clear 없이 작업을 이어가면 이전 작업의 파일 내용, 코드 변경사항, 대화 내용이 컨텍스트에 남아 있어서 새 작업에 할당할 수 있는 공간이 줄어든다.
4. /compact로 주기적으로 압축하라
긴 대화를 이어갈 때는 /compact로 이전 대화를 요약하여 압축할 수 있다.
[대화가 길어졌을 때]
/compact
→ 이전 대화 내용이 핵심만 남기고 압축
→ 컨텍스트 공간 확보
→ 현재 작업에 더 많은 정보를 넣을 수 있음5. 큰 작업은 반드시 분할하라
하나의 거대한 작업을 한 번에 요청하면 컨텍스트 윈도우가 빠르게 소진된다.
[나쁜 접근]
"전체 웹사이트를 리팩토링해줘"
→ 수십 개 파일을 한꺼번에 처리 → 컨텍스트 폭발 → 자동 압축 → 맥락 손실
[좋은 접근]
"먼저 @src/components/ 디렉토리의 컴포넌트를 리팩토링해줘" ← 1차
/clear
"이번에는 @src/hooks/ 디렉토리의 훅을 리팩토링해줘" ← 2차
/clear
"마지막으로 @src/pages/ 디렉토리의 페이지를 리팩토링해줘" ← 3차
→ 각 단계에서 깨끗한 컨텍스트로 집중 작업 → 높은 품질10. 종합 정리: 프롬프트 작성 플로우
지금까지 배운 모든 기법을 하나의 플로우로 정리한다.
핵심 요약
| 원칙 | 실천 방법 |
|---|---|
| 범위를 제한하라 | "~만", "~없이", "~을 제외하고" |
| 컨텍스트를 제공하라 | @파일 참조, 에러 메시지, 스크린샷 |
| 단계별로 생각하게 하라 | "단계별로 생각해주세요" (COT) |
| 역할을 부여하라 | "당신은 ~전문가입니다" |
| CLAUDE.md를 활용하라 | 빌드 확인, 린트 확인 규칙 |
| 컨텍스트를 관리하라 | /clear, /compact, 작업 분할 |
좋은 프롬프트 = 명확한 범위 + 충분한 컨텍스트 + 구체적 제약이 공식을 습관화하면 Claude Code와의 협업 효율이 비약적으로 향상된다. 프롬프트 작성에 30초를 더 투자하면, 결과 확인과 수정에 드는 30분을 절약할 수 있다.