효과적인 프롬프팅 — 테크 리드처럼 대화하기

공식 참고 자료: Overview · Best practices · Prompt engineering · CLI usage

커리큘럼 흐름

1. CLAUDE.md Mastery — 저장소 메모리와 규칙
2. Effective Prompting — 작업 framing과 제약 설정 ← 현재 문서
3. MCP Power Tools — 라이브 도구와 컨텍스트 연결
4. Multi-Agent Workflows — 위임과 병렬 실행
5. Hooks Automation — 로컬 가드레일 자동화
6. GitHub Actions Workflows — 반복 작업을 팀 자동화로 옮기기

이 문서에서 참고한 공식 문서

• 프롬프팅 패턴과 모범 사례 — Best practices
• 일반적인 프롬프트 엔지니어링 개념 — Prompt engineering
• Claude Code 사용 모델 — Overview
• CLI 명령과 세션 운용 패턴 — CLI usage

핵심 원칙: 프롬프트는 요청이 아니라 작업 브리프다

Anthropic 문서가 반복해서 강조하는 요지는 단순합니다. Claude Code는 답변만 하는 챗봇이 아니라 파일을 읽고, 명령을 실행하고, 수정하고, 검증까지 시도하는 에이전트형 코딩 환경입니다. 그래서 잘 먹히는 프롬프트도 “좋은 질문”보다 좋은 작업 지시서에 가깝습니다.

• 챗봇식 프롬프트: “왜 느릴까?”
• 에이전트식 프롬프트: “어디가 느린지 확인하고, 원인을 좁히고, 가능한 수정까지 하고, 테스트로 검증해줘”

핵심은 문장을 예쁘게 쓰는 것이 아니라 추측해야 할 영역을 줄이고, 스스로 검증할 수 있게 만드는 것입니다.

가장 잘 먹히는 기본 구조

공식 best practices를 실무용으로 풀어 쓰면, 대부분의 작업은 아래 네 줄기로 정리됩니다.

Goal:
무슨 상태를 만들고 싶은가
 
Context:
어떤 파일, 로그, 스크린샷, 레퍼런스가 중요한가
 
Constraints:
무엇을 건드리면 안 되는가
 
Verification:
무엇으로 완료를 증명할 것인가

이 구조가 좋은 이유는 명확합니다.

• Goal이 목표를 고정합니다.
• Context가 탐색 비용을 줄입니다.
• Constraints가 범위 확장을 막습니다.
• Verification이 “대충 된 것 같은 결과”를 막습니다.

바로 써먹을 수 있는 템플릿

Goal:
checkout 폼 제출 실패 시 사용자에게 원인 메시지를 명확히 보여준다.
 
Context:
- UI는 src/components/checkout/CheckoutForm.tsx
- 서버 액션은 src/app/actions/checkout.ts
- 유사한 에러 처리 패턴은 src/features/auth/LoginForm.tsx 참고
- 재현 조건: 카드 번호가 거절될 때 현재는 generic error만 노출
 
Constraints:
- 결제 API 응답 shape는 바꾸지 말 것
- 새 상태관리 라이브러리 추가 금지
- checkout 이외 화면은 수정하지 말 것
 
Verification:
- 거절 응답 시 사용자 메시지가 구체적으로 보일 것
- 관련 테스트를 추가/수정하고 실행할 것
- 필요하면 lint 또는 typecheck까지 돌릴 것

작업 크기에 따라 framing을 달리하자

모든 작업을 같은 방식으로 프롬프팅하면 비효율적입니다. Anthropic 문서 흐름을 실무에 맞춰 나누면 아래가 가장 실용적입니다.

1) 작고 분명한 작업: 바로 실행

파일 하나, 버그 하나, diff를 한 문장으로 설명할 수 있는 작업은 바로 시켜도 됩니다.

src/auth/login.ts의 세션 만료 후 재로그인 오류를 고쳐줘.
재현 테스트부터 추가하고, fix 후 그 테스트를 다시 돌려줘.

좋은 점:

• 대화가 짧습니다.
• 곧바로 수정과 검증으로 들어갑니다.
• 불필요한 planning overhead가 없습니다.

2) 중간 이상 작업: explore → plan → code

공식 best practices는 “먼저 탐색하고, 그다음 계획하고, 그다음 구현하라”는 흐름을 권합니다. 파일이 여러 개 얽히거나 접근 방식이 불명확할 때 가장 안전한 경로입니다.

먼저 plan mode로 접근해줘.
/src/auth 와 세션 관련 환경변수 처리 방식을 읽고,
Google OAuth를 추가하려면 어떤 파일이 바뀌는지 계획을 만들어줘.
코드는 아직 쓰지 마.

그다음 구현 단계에서:

좋아. 방금 만든 계획대로 구현해줘.
callback handler 테스트를 추가하고, 관련 테스트를 실행해서 통과까지 확인해줘.

핵심은 탐색과 구현을 같은 턴에서 섞지 않는 것입니다. 그래야 잘못된 가정 위에 큰 diff가 생기는 일을 줄일 수 있습니다.

3) 애매하고 큰 작업: 인터뷰 먼저

기능 자체가 아직 덜 정해졌다면, 처음부터 구현을 시키는 것보다 Claude가 질문하게 두는 편이 낫습니다. Anthropic은 큰 feature에서 Claude가 필요한 질문을 먼저 던지게 하는 흐름을 권합니다.

새로운 알림 센터 기능을 만들고 싶어.
바로 구현하지 말고 먼저 나를 인터뷰해줘.
기술 구현, UI/UX, edge case, trade-off를 빠짐없이 물어봐.
다 끝나면 SPEC.md 초안을 정리해줘.

이 방식이 좋은 상황:

• 요구사항이 아직 흐릿할 때
• UI/UX와 기술 결정이 같이 얽혀 있을 때
• 롤백 비용이 클 때
• 구현 전에 팀 합의가 먼저 필요할 때

“좋은 프롬프트”는 로컬 앵커가 많다

Claude는 마음을 읽지 못합니다. 대신 파일, 명령, 로그, 스크린샷, 레퍼런스 링크를 주면 급격히 정확해집니다.

가장 유용한 컨텍스트 앵커

• 관련 파일: src/app/api/users/route.ts
• 따라야 할 패턴: src/features/profile/ProfileForm.tsx
• 실패 로그: pnpm test profile -- --runInBand
• UI 목표: 스크린샷 첨부
• 외부 레퍼런스: 공식 문서 URL
• 검증 기준: 어떤 테스트/빌드/시각 비교를 돌릴지

나쁜 예 vs 좋은 예

나쁨:

로그인 버그 고쳐줘

좋음:

사용자가 세션 만료 후 다시 로그인하면 무한 로딩에 빠져.
src/auth/ 아래 흐름을 확인하고, 특히 token refresh 쪽을 봐줘.
먼저 재현 테스트를 만들고, 고친 뒤 그 테스트를 다시 실행해줘.

추가로 더 좋아지려면:

- 관련 파일: src/auth/session.ts, src/auth/login.ts
- 유사 패턴: src/features/billing/useCheckout.ts
- 수정 범위는 src/auth/ 아래로 제한
- 서버 API 응답 shape는 바꾸지 말 것

제약 조건은 품질을 떨어뜨리지 않는다

프롬프트에서 제약을 많이 주면 AI가 답답해질 것 같지만, 실제로는 반대입니다. 제약은 Claude가 괜히 넓게 파고드는 것을 막아 주는 팀 규칙의 압축본입니다.

자주 쓰는 제약 카테고리

범위 제약

• src/payments/ 밖은 수정하지 마
• public API shape는 유지해
• 이번 작업에서는 문서는 건드리지 마
• 구현 대신 plan만 만들어

기술 제약

• 새 의존성 추가 금지
• 기존 React Query 패턴 재사용
• DB schema 변경 금지
• mocks 대신 실제 테스트 헬퍼 사용

운영 제약

• 관련 테스트만 먼저 실행
• 실패 원인을 숨기지 말고 근본 원인을 고쳐
• diff를 작게 유지
• 커밋 전 lint/typecheck 확인

제약이 없으면 Claude는 “가능한 해결책”을 찾습니다. 제약이 있으면 Claude는 **“이 팀에서 허용되는 해결책”**을 찾습니다.

Verification을 프롬프트에 넣으면 결과 품질이 달라진다

Anthropic은 “Claude가 스스로 검증할 수 있게 해 주라”는 점을 가장 높은 레버리지로 봅니다. 검증 기준이 없으면 Claude는 그럴듯한 결과를 내더라도 실제 동작까지 닫지 못하는 경우가 많습니다.

좋은 Verification 문장 예시

- 새 테스트를 추가하고 그 테스트를 실행해줘
- build가 깨지지 않는지 확인해줘
- 스크린샷을 비교해서 차이가 남으면 수정해줘
- 에러를 suppress하지 말고 root cause를 고쳐줘

UI 작업용 프롬프트 예시

이 스크린샷을 목표 디자인으로 보고 dashboard header를 맞춰줘.
수정 후 스크린샷을 다시 확인해서 차이를 항목별로 적고,
남은 차이가 있으면 한 번 더 다듬어줘.

버그 수정용 프롬프트 예시

현재 build가 이 에러로 실패해: [로그]
에러를 우회하거나 비활성화하지 말고 원인을 찾아 고쳐줘.
수정 후 build가 성공하는지 다시 확인해줘.

실전에서 잘 통하는 프롬프트 패턴

1. 재현 → 수정 → 재검증 패턴

버그 수정에서 가장 안정적인 패턴입니다.

장바구니 수량을 빠르게 두 번 바꾸면 중복 요청이 생겨.
먼저 실패 테스트 또는 재현 절차를 만들고,
그다음 수정하고,
마지막으로 같은 조건에서 다시 검증해줘.

이 패턴의 장점:

• 문제가 실제로 재현됐는지 확인됩니다.
• “고쳤다”고 말하기 쉬운 착시를 줄입니다.
• regression 방지가 자연스럽게 따라옵니다.

2. plan-first 패턴

먼저 구현하지 말고 plan만 제안해.
변경될 파일, 위험한 부분, 비가역 포인트, 검증 방법을 포함해.
작업을 2~4단계로 나눠줘.

추천 상황:

• 여러 파일/도메인이 걸릴 때
• 설계 판단 비중이 클 때
• 롤백 비용이 클 때

3. 기존 패턴 따라가기 패턴

새 calendar widget을 추가해줘.
구현 전에 home page의 기존 widget 패턴을 읽고,
src/components/widgets/WeatherWidget.tsx와 같은 구조와 naming을 따라줘.
기존 라이브러리만 사용하고 새 라이브러리는 추가하지 마.

Claude는 “새로 설계”보다 기존 패턴에 맞춰 확장하는 작업에서 특히 강합니다.

4. 구조화 프롬프트 패턴

Anthropic의 prompt engineering 문서는 XML 태그처럼 구획이 분명한 구조를 추천합니다. 여러 조건이 섞이는 작업에서 특히 유용합니다.

<goal>알림 설정 화면에 주간 요약 토글을 추가한다.</goal>
<context>
- UI: src/settings/NotificationSettings.tsx
- 저장 로직: src/app/actions/settings.ts
- 참고 패턴: src/features/profile/ProfileSettings.tsx
</context>
<constraints>
- 기존 API 응답 shape 유지
- 새 의존성 추가 금지
</constraints>
<verification>
- 설정 저장 테스트 실행
- 토글 상태가 다시 진입해도 유지되는지 확인
</verification>

중요한 점은 태그 이름 자체가 아니라 구획을 일관되게 유지하는 것입니다.

5. 비대화형 one-shot 패턴

반복 대화가 아니라 자동화나 배치 작업이면 claude -p가 더 적합합니다.

# 로그 요약
cat error.log | claude -p "이 에러 로그를 요약하고 가장 가능성 높은 원인 3개를 정리해줘"
 
# 구조화 출력
claude -p "현재 API endpoint 목록을 JSON으로 정리해줘" --output-format json

이 모드는 CI, pre-commit hook, 스크립트, 일괄 리포트 생성에 특히 잘 맞습니다.

반복 루프를 짧게 가져가라

공식 best practices는 early course correction을 강조합니다. 첫 시도에서 완벽함을 기대하기보다 빨리 방향을 바로잡는 편이 훨씬 효율적입니다.

추천 루프

1. 작은 단위로 요청한다.
2. 결과를 확인한다.
3. 어긋나면 즉시 교정한다.
4. 두 번 이상 같은 문제를 반복하면 세션을 새로 시작한다.

예를 들어:

1차: 프로필 편집 폼에 avatar_url 필드 추가해줘.
2차: 좋아. 그런데 서버 validation도 같이 맞춰줘.
3차: 마지막으로 실패 메시지를 사용자 친화적으로 바꿔줘.

이 흐름이 좋은 이유는 매 단계가 검토 가능한 단위이기 때문입니다.

엇나갈 때 바로 쓰는 교정 문장

• “지금 범위가 너무 넓어졌어. src/profile/만 수정해줘.”
• “설명보다 실행이 필요해. 바로 수정하고 테스트까지 해줘.”
• “그 접근은 아니야. 방금 언급한 ProfileForm.tsx 패턴을 따라줘.”
• “이전 시도는 버리고, 실패 로그 기준으로 다시 원인부터 좁혀줘.”

Claude Code에서는 Esc로 진행을 끊고 방향을 바꿀 수 있고, /rewind로 이전 상태로 되돌리거나 요약 지점부터 다시 진행할 수 있습니다. 관련 없는 작업으로 넘어갈 때는 /clear로 컨텍스트를 비우는 것이 오히려 품질에 도움이 됩니다.

컨텍스트 예산을 의식하면 품질이 올라간다

Anthropic 문서는 컨텍스트 윈도우가 가장 중요한 자원이라고 봅니다. 대화, 읽은 파일, 명령 출력이 모두 컨텍스트를 차지하고, 길어질수록 성능이 떨어질 수 있습니다.

그래서 실전에서는 아래 원칙이 중요합니다.

1. 관련 없는 턴을 오래 끌지 말기

• 다른 작업으로 넘어갈 때는 /clear
• 긴 설계 논의가 끝났으면 새 세션에서 구현 시작
• 큰 기능은 인터뷰/명세 작성 세션과 구현 세션을 분리

2. 앵커는 넓게 말고 좁게 주기

나쁨:

• “auth 쪽 전부 살펴봐”

더 좋음:

• “src/auth/session.ts와 src/auth/login.ts를 먼저 읽고 세션 만료 흐름을 파악해줘”

3. verbose한 출력은 최소화하기

• 긴 로그는 파일로 주거나 pipe로 전달
• 필요한 결과 형식을 명시
• 조사만 필요한 작업은 나중에 배울 subagent 패턴으로 분리

4. 세션을 브랜치처럼 다루기

작업이 길어지면 claude --continue나 claude --resume으로 이어갈 수 있습니다. 이름을 잘 붙여 두면 특정 workstream만 다시 불러오기도 쉽습니다.

자주 실패하는 프롬프트 패턴

1. 목표가 아니라 분위기만 전달

❌ 인증 UX 좀 좋게 만들어줘
✅ 세션 만료 후 재로그인 시 보이는 에러 메시지를 더 명확하게 바꿔줘.
   수정 대상은 src/auth/login.ts와 관련 테스트로 제한해.

2. 계획과 구현을 동시에 모호하게 요청

❌ OAuth 붙여줘. 필요한 건 알아서 해줘.
✅ 먼저 어떤 파일이 바뀌는지 계획을 만들고,
   내가 확인하면 그다음 구현해줘.

3. 제약을 뒤늦게 말함

❌ 구현 끝난 뒤: "아, DB schema는 건드리면 안 됐어"
✅ 처음부터: "DB schema 변경 금지, API 응답 shape 유지"

4. 검증 없는 완료

❌ 로그인 오류 고쳐줘
✅ 로그인 오류를 재현하는 테스트를 추가하고, fix 후 같은 테스트를 다시 실행해줘

5. 한 턴에 서로 다른 목적을 과도하게 섞음

❌ 인증 버그 고치고, 문서 업데이트하고, 배포 전략도 제안해줘
✅ 인증 버그 수정 → 문서 반영 → 배포 검토를 별도 단계로 분리

“보여줘”와 “해줘”를 구분하자

Claude Code는 설명도 잘하지만, 본질적으로는 행동하는 도구입니다. 그래서 설명이 필요한지, 실행이 필요한지를 분명히 해야 합니다.

설명 중심:

현재 인증 플로우를 요약해줘. 코드는 변경하지 마.

실행 중심:

현재 인증 플로우를 분석하고,
세션 만료 후 실패 지점을 찾아 수정해줘.
관련 테스트까지 확인해줘.

둘을 섞고 싶다면 순서를 써 주세요.

먼저 현재 인증 플로우를 요약하고,
그다음 취약한 지점이 있으면 수정 제안까지 해줘.
코드 수정은 내 확인 후 진행해.

모델·권한·도구 힌트도 프롬프트 품질의 일부다

프롬프트 자체만큼 중요한 것이 실행 환경입니다.

모델 선택 감각

일반적으로는:

• Haiku: 검색, 분류, 단순 요약, 빠른 triage
• Sonnet: 기본 구현, 코드 리뷰, 대부분의 실무 작업
• Opus: 구조적 설계 판단, 어려운 디버깅, 큰 리팩터링 전 분석

즉 “복잡한 사고가 필요하다”는 말만 반복하기보다, 정말 어려운 작업에서만 더 강한 모델이나 deeper analysis를 쓰는 편이 낫습니다.

권한/환경 힌트

• 자주 쓰는 안전한 명령은 /permissions로 allowlist
• 승인 피로가 크면 auto mode 고려
• 더 강한 격리가 필요하면 sandbox 사용

프롬프트가 좋아도 권한 프롬프트에 계속 막히면 흐름이 끊깁니다. 반대로 권한을 너무 넓게 열면 위험합니다. 반복적으로 필요한 안전한 범위만 허용하는 식이 가장 실무적입니다.

바로 복붙할 수 있는 실전 프롬프트 6개

작은 버그 수정

src/cart/useCart.ts에서 중복 추가 버그를 고쳐줘.
빠르게 연속 클릭할 때 같은 아이템이 두 번 들어가.
먼저 재현 테스트를 만들고, 수정 후 그 테스트를 다시 실행해줘.
수정 범위는 cart 관련 파일로 제한해.

설계 먼저

먼저 구현하지 말고 plan mode로 접근해줘.
실시간 알림을 추가하려고 하는데,
어떤 파일이 바뀌는지, 가장 위험한 지점이 뭔지,
검증은 어떻게 할지 3단계 계획으로 정리해줘.

인터뷰 먼저

새로운 admin dashboard를 만들고 싶어.
나를 먼저 인터뷰해줘.
UI/UX, 권한 모델, edge case, 성능 trade-off까지 빠짐없이 물어보고,
다 끝나면 SPEC.md 초안을 작성해줘.

UI 작업

이 스크린샷을 목표로 settings page 레이아웃을 맞춰줘.
관련 파일을 먼저 찾고,
수정 후 결과를 다시 점검해서 남은 차이를 bullet로 적어줘.
차이가 크면 한 번 더 다듬어줘.

문서/레퍼런스 기반 작업

이 API 문서를 읽고 src/api/client.ts를 최신 스펙에 맞춰 업데이트해줘.
레퍼런스 문서의 변경점만 반영하고,
공개 함수 시그니처 변경이 필요하면 먼저 계획으로 알려줘.

비대화형 자동화

git diff --staged | claude -p "이 변경을 리뷰하고 위험 요소를 priority 순으로 정리해줘"

마무리 체크리스트

프롬프트를 보내기 전에 아래 네 가지만 확인해도 품질이 크게 달라집니다.

• Goal이 한 문장으로 고정돼 있는가?
• Context에 파일/로그/스크린샷 같은 로컬 앵커가 있는가?
• Constraints가 범위를 묶고 있는가?
• Verification이 완료를 증명하는가?

좋은 프롬프트는 길어서 좋은 것이 아닙니다. Claude가 무엇을 해야 하는지, 무엇을 하면 안 되는지, 무엇으로 끝났다고 볼지를 헷갈리지 않게 만드는 프롬프트가 좋은 프롬프트입니다.