Ch13. 프롬프팅 베스트 프랙티스

Claude Code에서 결과를 끌어올리는 프롬프트 작성 전략 — 명확한 지시, 맥락·예시, effort 조절, 행동 유발, 자율성과 안전

핵심 요약

황금률: 맥락을 모르는 동료가 그대로 따라 할 수 있을 만큼 출력 형식과 제약을 명확히 적습니다.
Opus 4.8은 지시를 문자 그대로 해석하므로, 넓게 적용하려면 "모든 섹션에"처럼 범위를 명시해야 합니다.
예시(few-shot) 3~5개와 XML 태그(<instructions>·<example>)가 출력 형식·구조를 잡는 가장 신뢰도 높은 수단입니다.
코딩·에이전트 작업은 /effort xhigh가 권장값이며, Opus 4.8은 effort를 엄격히 준수하므로 얕은 추론은 effort를 올려 해결합니다.
비가역·파괴적·공유 시스템 영향 작업은 진행 전 확인하도록 지시하고 CRITICAL·MUST 같은 과한 표현은 줄입니다.

CLAUDE.md와 스킬이 영구 지침이라면, 이 챕터는 그때그때 입력하는 프롬프트를 잘 쓰는 법을 다룹니다. Anthropic 공식 프롬프트 엔지니어링 가이드를 Claude Code(CLI) 사용 맥락에 맞게 추렸습니다.

황금률

프롬프트를 맥락을 거의 모르는 동료에게 보여주고 그대로 따라 하게 해 보세요. 동료가 헷갈린다면 Claude도 헷갈립니다.

1. 명확하고 구체적으로 지시

Claude는 명시적이고 구체적인 지시에 잘 반응합니다. 원하는 출력 형식과 제약을 분명히 적고, 순서나 빠짐없음이 중요하면 번호 목록·불릿으로 단계를 나누세요.

모호한 프롬프트에 "알아서 잘"을 기대하지 말고, "기본을 넘어 가능한 한 완성도 높게 구현해줘"처럼 원하는 수준을 명시합니다.
Opus 4.8은 지시를 문자 그대로(literal) 해석합니다. 한 항목의 지시를 다른 항목으로 자동 일반화하지 않으므로, 넓게 적용하려면 범위를 명시하세요. 예: "첫 섹션만이 아니라 모든 섹션에 이 포맷을 적용해줘."

[덜 효과적]  분석 대시보드를 만들어줘
[더 효과적]  분석 대시보드를 만들어줘. 관련 기능과 상호작용을 최대한 포함하고,
            기본을 넘어 완성도 높은 구현으로 만들어줘.

2. 맥락(왜)을 함께 제공

지시에 이유·동기를 덧붙이면 Claude가 목표를 더 잘 이해하고 폭넓게 적용합니다.

[덜 효과적]  말줄임표(…)를 절대 쓰지 마
[더 효과적]  응답이 TTS 엔진으로 읽히니 말줄임표를 쓰지 마. 엔진이 발음하지 못해.

Claude Code에서 맥락을 주입하는 핵심 수단:

@ 파일·디렉터리 참조: @src/utils/auth.ts처럼 경로를 가리키면 해당 파일(및 그 디렉터리의 CLAUDE.md)이 컨텍스트에 들어갑니다.
CLAUDE.md: 매 세션 반복 설명할 규칙은 프롬프트가 아니라 CLAUDE.md에 영구 기록합니다.
첫 턴에 충분히 명세: 인터랙티브 코딩에서 작업·의도·제약을 첫 입력에 명확히 주면 이후 턴의 토큰 사용이 줄고 자율성·성능이 올라갑니다. 모호한 지시를 여러 턴에 걸쳐 조금씩 흘리는 방식은 효율이 떨어집니다.

3. 예시(멀티샷)와 XML 태그로 구조화

예시는 출력 형식·톤·구조를 잡는 가장 신뢰도 높은 수단입니다(few-shot / 멀티샷). 3~5개를 권장하며, 실제 사용 사례를 닮고(relevant) 엣지 케이스까지 포함하도록(diverse) 만드세요.

XML 태그를 쓰면 지시·맥락·입력·예시가 뒤섞인 복잡한 프롬프트도 모호함 없이 파싱됩니다.

<instructions>
아래 변경 로그를 사용자용 릴리스 노트로 바꿔줘.
</instructions>

<example>
입력: "fix: null check in auth"
출력: "- 로그인 시 드물게 발생하던 오류를 수정했습니다."
</example>

<changelog>
{{여기에 git log}}
</changelog>

일관되고 서술적인 태그명을 쓰고, 계층이 있으면 중첩합니다(<documents> 안에 <document>).

4. 출력 형식과 장황함 제어

"하지 마라"보다 "이렇게 하라": "마크다운 쓰지 마" 대신 "매끄럽게 이어지는 산문 단락으로 작성해줘".
XML 형식 지시: "산문 부분은 <prose> 태그 안에 써줘".
프롬프트 스타일을 출력 스타일에 맞추기: 프롬프트에서 마크다운을 줄이면 출력의 마크다운도 줄어드는 경향이 있습니다.
Opus 4.8은 작업 복잡도에 맞춰 길이를 조절합니다(단순 조회는 짧게, 개방형 분석은 길게). 특정 분량·스타일이 필요하면 명시하세요. 부정 예시보다 원하는 모습의 긍정 예시가 더 잘 먹힙니다.
최신 모델은 도구 호출 후 요약을 생략하기도 합니다. 진행 가시성이 필요하면 "도구 사용 후 한 일을 짧게 요약해줘"를 추가합니다.

5. effort와 thinking 조절

Claude Code에서 추론 강도는 /effort로 조절합니다(low·medium·high·xhigh·max·ultracode).

상황	권장 effort
코딩·에이전트 작업	`xhigh`(대부분의 코딩·에이전트에 최적)
지능이 중요한 일반 작업	최소 `high`
비용·지연 민감, 단순 작업	`medium` 또는 `low`

Opus 4.8은 effort를 엄격히 준수합니다. low/medium에서는 요청 범위만 처리하므로, 복잡한 문제에서 얕은 추론이 보이면 프롬프트로 우회하기보다 effort를 high/xhigh로 올리세요.
low를 유지해야 한다면 "이 작업은 다단계 추론이 필요해. 답하기 전에 신중히 단계적으로 생각해줘"처럼 표적 지시를 더합니다.
ultrathink 키워드는 그 턴에서 더 깊은 추론을 요청합니다(세션 effort 자체를 바꾸지는 않음). think/think hard는 키워드로 인식되지 않습니다.

출력 토큰 예산

xhigh·max로 돌릴 때는 모델이 서브에이전트·도구 호출을 거쳐 충분히 사고·실행할 수 있도록 max output token을 넉넉히(예: 64k부터) 잡으세요.

6. 행동 유발 vs 신중 모드

Claude는 지시를 정확히 따르므로, 행동을 원하면 명시적으로 말해야 합니다.

[제안만 함]  이 함수를 개선할 만한 변경을 제안해줄래?
[실제 수행]  이 함수의 성능을 개선하도록 변경해줘.

Opus 4.8은 도구 호출보다 추론을 선호하는 경향이 있습니다. 도구를 더 쓰게 하려면 effort를 올리거나, 언제·어떻게 그 도구를 써야 하는지 명시합니다.
반대로 신중하게 만들려면 "명확히 지시하기 전에는 파일을 수정하지 말고, 모호하면 정보 제공·조사·권고에 머물러줘"처럼 지시합니다.
CRITICAL/MUST 같은 과한 표현은 줄이세요. 최신 모델은 도구·스킬을 과도하게 트리거할 수 있어, "이 도구는 …할 때 쓴다" 정도의 평이한 표현이 더 안정적입니다.

7. 자율성과 안전의 균형

지침이 없으면 모델이 되돌리기 어려운 작업을 벌일 수 있습니다. 위험·비가역·공유 시스템 영향 작업은 진행하기 전에 확인하도록 지시하세요.

되돌릴 수 있는 로컬 작업(파일 편집, 테스트 실행)은 자유롭게 진행하되,
되돌리기 어렵거나 공유 시스템에 영향을 주거나 파괴적인 작업은 진행 전에 확인해줘.

확인이 필요한 예:
- 파괴적: 파일/브랜치 삭제, DB 테이블 드롭, rm -rf
- 비가역: git push --force, git reset --hard, 게시된 커밋 수정
- 외부 영향: 코드 push, PR/이슈 코멘트, 메시지 전송, 공유 인프라 변경

막혔다고 안전장치를 우회(예: --no-verify)하거나 정체불명 파일을 버리지 마.

이 원칙은 Claude Code의 Plan 모드·권한 모드와 같이 쓸 때 효과가 커집니다.

8. 과잉엔지니어링·환각 억제

과잉엔지니어링 방지: "요청했거나 명백히 필요한 변경만. 버그 수정에 주변 코드 정리를 끼워넣지 말고, 가설적 미래 요구를 위한 추상화·방어코드·옵션을 추가하지 마."
환각 방지(코드 단정 금지):

<investigate_before_answering>
열어보지 않은 코드를 추측하지 마. 사용자가 특정 파일을 언급하면 답하기 전에 반드시 그 파일을 읽어.
코드베이스 질문은 관련 파일을 조사·확인한 뒤에만 단정해.
</investigate_before_answering>

테스트 통과에 매몰 금지: "테스트만 통과하는 하드코딩·우회 스크립트 말고, 모든 유효 입력에 동작하는 일반해를 표준 도구로 구현해. 테스트가 이상하면 우회하지 말고 알려줘."

9. 장기·멀티 컨텍스트 워크플로우

긴 작업은 한 번에 다 끝내기보다 조금씩 진행하며 상태를 저장하는 게 핵심입니다. 자세한 패턴은 컨텍스트 관리·서브에이전트 챕터를 참고하세요.

구조화 상태는 JSON(tests.json), 진행 메모는 자유 텍스트(progress.txt), 상태 추적은 git(로그·체크포인트)으로 나눠 관리.
컨텍스트는 한계 근처에서 자동 압축되니 "토큰 예산 걱정으로 작업을 일찍 끝내지 말고 한계 전에 진행 상태를 저장해라"고 지시하면 끊김 없이 이어집니다.
새 컨텍스트 윈도로 이어갈 때는 시작 방법을 구체적으로: "pwd 확인 → progress.txt·tests.json·git log 검토 → 통합 테스트 1회 수동 실행 후 진행."

빠른 처방 체크리스트

증상	처방
결과가 막연·부실	출력 형식·제약 명시, 긍정 예시 3~5개 추가
복잡한 문제에서 얕은 추론	`/effort`를 `high`/`xhigh`로, 또는 `ultrathink`
변경 안 하고 제안만 함	"제안" 대신 "변경/적용/수정"으로 동사 변경
도구를 안 씀	effort↑ 또는 도구 사용 시점을 명시
과도한 파일·추상화 생성	과잉엔지니어링 금지 지시, 범위 한정
코드 추측·환각	"파일 먼저 읽고 답해" 지시
위험 작업을 임의로 실행	비가역 작업 확인 지시 + Plan 모드

참고 문서

프롬프팅 베스트 프랙티스(영어): https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices
effort 레벨·모델 설정(영어): https://code.claude.com/docs/en/model-config
적응형 thinking(영어): https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking
Claude Code 베스트 프랙티스(영어): https://code.claude.com/docs/en/best-practices

핵심 요약

황금률: 맥락을 모르는 동료가 그대로 따라 할 수 있을 만큼 출력 형식과 제약을 명확히 적습니다.
Opus 4.8은 지시를 문자 그대로 해석하므로, 넓게 적용하려면 "모든 섹션에"처럼 범위를 명시해야 합니다.
예시(few-shot) 3~5개와 XML 태그(<instructions>·<example>)가 출력 형식·구조를 잡는 가장 신뢰도 높은 수단입니다.
코딩·에이전트 작업은 /effort xhigh가 권장값이며, Opus 4.8은 effort를 엄격히 준수하므로 얕은 추론은 effort를 올려 해결합니다.
비가역·파괴적·공유 시스템 영향 작업은 진행 전 확인하도록 지시하고 CRITICAL·MUST 같은 과한 표현은 줄입니다.

황금률

프롬프트를 맥락을 거의 모르는 동료에게 보여주고 그대로 따라 하게 해 보세요. 동료가 헷갈린다면 Claude도 헷갈립니다.

1. 명확하고 구체적으로 지시

모호한 프롬프트에 "알아서 잘"을 기대하지 말고, "기본을 넘어 가능한 한 완성도 높게 구현해줘"처럼 원하는 수준을 명시합니다.
Opus 4.8은 지시를 문자 그대로(literal) 해석합니다. 한 항목의 지시를 다른 항목으로 자동 일반화하지 않으므로, 넓게 적용하려면 범위를 명시하세요. 예: "첫 섹션만이 아니라 모든 섹션에 이 포맷을 적용해줘."

[덜 효과적]  분석 대시보드를 만들어줘
[더 효과적]  분석 대시보드를 만들어줘. 관련 기능과 상호작용을 최대한 포함하고,
            기본을 넘어 완성도 높은 구현으로 만들어줘.

2. 맥락(왜)을 함께 제공

지시에 이유·동기를 덧붙이면 Claude가 목표를 더 잘 이해하고 폭넓게 적용합니다.

[덜 효과적]  말줄임표(…)를 절대 쓰지 마
[더 효과적]  응답이 TTS 엔진으로 읽히니 말줄임표를 쓰지 마. 엔진이 발음하지 못해.

Claude Code에서 맥락을 주입하는 핵심 수단:

@ 파일·디렉터리 참조: @src/utils/auth.ts처럼 경로를 가리키면 해당 파일(및 그 디렉터리의 CLAUDE.md)이 컨텍스트에 들어갑니다.
CLAUDE.md: 매 세션 반복 설명할 규칙은 프롬프트가 아니라 CLAUDE.md에 영구 기록합니다.
첫 턴에 충분히 명세: 인터랙티브 코딩에서 작업·의도·제약을 첫 입력에 명확히 주면 이후 턴의 토큰 사용이 줄고 자율성·성능이 올라갑니다. 모호한 지시를 여러 턴에 걸쳐 조금씩 흘리는 방식은 효율이 떨어집니다.

3. 예시(멀티샷)와 XML 태그로 구조화

XML 태그를 쓰면 지시·맥락·입력·예시가 뒤섞인 복잡한 프롬프트도 모호함 없이 파싱됩니다.

<instructions>
아래 변경 로그를 사용자용 릴리스 노트로 바꿔줘.
</instructions>

<example>
입력: "fix: null check in auth"
출력: "- 로그인 시 드물게 발생하던 오류를 수정했습니다."
</example>

<changelog>
{{여기에 git log}}
</changelog>

일관되고 서술적인 태그명을 쓰고, 계층이 있으면 중첩합니다(<documents> 안에 <document>).

4. 출력 형식과 장황함 제어

"하지 마라"보다 "이렇게 하라": "마크다운 쓰지 마" 대신 "매끄럽게 이어지는 산문 단락으로 작성해줘".
XML 형식 지시: "산문 부분은 <prose> 태그 안에 써줘".
프롬프트 스타일을 출력 스타일에 맞추기: 프롬프트에서 마크다운을 줄이면 출력의 마크다운도 줄어드는 경향이 있습니다.
Opus 4.8은 작업 복잡도에 맞춰 길이를 조절합니다(단순 조회는 짧게, 개방형 분석은 길게). 특정 분량·스타일이 필요하면 명시하세요. 부정 예시보다 원하는 모습의 긍정 예시가 더 잘 먹힙니다.
최신 모델은 도구 호출 후 요약을 생략하기도 합니다. 진행 가시성이 필요하면 "도구 사용 후 한 일을 짧게 요약해줘"를 추가합니다.

5. effort와 thinking 조절

Claude Code에서 추론 강도는 /effort로 조절합니다(low·medium·high·xhigh·max·ultracode).

상황	권장 effort
코딩·에이전트 작업	`xhigh`(대부분의 코딩·에이전트에 최적)
지능이 중요한 일반 작업	최소 `high`
비용·지연 민감, 단순 작업	`medium` 또는 `low`

Opus 4.8은 effort를 엄격히 준수합니다. low/medium에서는 요청 범위만 처리하므로, 복잡한 문제에서 얕은 추론이 보이면 프롬프트로 우회하기보다 effort를 high/xhigh로 올리세요.
low를 유지해야 한다면 "이 작업은 다단계 추론이 필요해. 답하기 전에 신중히 단계적으로 생각해줘"처럼 표적 지시를 더합니다.
ultrathink 키워드는 그 턴에서 더 깊은 추론을 요청합니다(세션 effort 자체를 바꾸지는 않음). think/think hard는 키워드로 인식되지 않습니다.

출력 토큰 예산

xhigh·max로 돌릴 때는 모델이 서브에이전트·도구 호출을 거쳐 충분히 사고·실행할 수 있도록 max output token을 넉넉히(예: 64k부터) 잡으세요.

6. 행동 유발 vs 신중 모드

Claude는 지시를 정확히 따르므로, 행동을 원하면 명시적으로 말해야 합니다.

[제안만 함]  이 함수를 개선할 만한 변경을 제안해줄래?
[실제 수행]  이 함수의 성능을 개선하도록 변경해줘.

Opus 4.8은 도구 호출보다 추론을 선호하는 경향이 있습니다. 도구를 더 쓰게 하려면 effort를 올리거나, 언제·어떻게 그 도구를 써야 하는지 명시합니다.
반대로 신중하게 만들려면 "명확히 지시하기 전에는 파일을 수정하지 말고, 모호하면 정보 제공·조사·권고에 머물러줘"처럼 지시합니다.
CRITICAL/MUST 같은 과한 표현은 줄이세요. 최신 모델은 도구·스킬을 과도하게 트리거할 수 있어, "이 도구는 …할 때 쓴다" 정도의 평이한 표현이 더 안정적입니다.

7. 자율성과 안전의 균형

지침이 없으면 모델이 되돌리기 어려운 작업을 벌일 수 있습니다. 위험·비가역·공유 시스템 영향 작업은 진행하기 전에 확인하도록 지시하세요.

되돌릴 수 있는 로컬 작업(파일 편집, 테스트 실행)은 자유롭게 진행하되,
되돌리기 어렵거나 공유 시스템에 영향을 주거나 파괴적인 작업은 진행 전에 확인해줘.

확인이 필요한 예:
- 파괴적: 파일/브랜치 삭제, DB 테이블 드롭, rm -rf
- 비가역: git push --force, git reset --hard, 게시된 커밋 수정
- 외부 영향: 코드 push, PR/이슈 코멘트, 메시지 전송, 공유 인프라 변경

막혔다고 안전장치를 우회(예: --no-verify)하거나 정체불명 파일을 버리지 마.

이 원칙은 Claude Code의 Plan 모드·권한 모드와 같이 쓸 때 효과가 커집니다.

8. 과잉엔지니어링·환각 억제

과잉엔지니어링 방지: "요청했거나 명백히 필요한 변경만. 버그 수정에 주변 코드 정리를 끼워넣지 말고, 가설적 미래 요구를 위한 추상화·방어코드·옵션을 추가하지 마."
환각 방지(코드 단정 금지):

<investigate_before_answering>
열어보지 않은 코드를 추측하지 마. 사용자가 특정 파일을 언급하면 답하기 전에 반드시 그 파일을 읽어.
코드베이스 질문은 관련 파일을 조사·확인한 뒤에만 단정해.
</investigate_before_answering>

테스트 통과에 매몰 금지: "테스트만 통과하는 하드코딩·우회 스크립트 말고, 모든 유효 입력에 동작하는 일반해를 표준 도구로 구현해. 테스트가 이상하면 우회하지 말고 알려줘."

9. 장기·멀티 컨텍스트 워크플로우

구조화 상태는 JSON(tests.json), 진행 메모는 자유 텍스트(progress.txt), 상태 추적은 git(로그·체크포인트)으로 나눠 관리.
컨텍스트는 한계 근처에서 자동 압축되니 "토큰 예산 걱정으로 작업을 일찍 끝내지 말고 한계 전에 진행 상태를 저장해라"고 지시하면 끊김 없이 이어집니다.
새 컨텍스트 윈도로 이어갈 때는 시작 방법을 구체적으로: "pwd 확인 → progress.txt·tests.json·git log 검토 → 통합 테스트 1회 수동 실행 후 진행."

빠른 처방 체크리스트

증상	처방
결과가 막연·부실	출력 형식·제약 명시, 긍정 예시 3~5개 추가
복잡한 문제에서 얕은 추론	`/effort`를 `high`/`xhigh`로, 또는 `ultrathink`
변경 안 하고 제안만 함	"제안" 대신 "변경/적용/수정"으로 동사 변경
도구를 안 씀	effort↑ 또는 도구 사용 시점을 명시
과도한 파일·추상화 생성	과잉엔지니어링 금지 지시, 범위 한정
코드 추측·환각	"파일 먼저 읽고 답해" 지시
위험 작업을 임의로 실행	비가역 작업 확인 지시 + Plan 모드

참고 문서

프롬프팅 베스트 프랙티스(영어): https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices
effort 레벨·모델 설정(영어): https://code.claude.com/docs/en/model-config
적응형 thinking(영어): https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking
Claude Code 베스트 프랙티스(영어): https://code.claude.com/docs/en/best-practices

1. 명확하고 구체적으로 지시

2. 맥락(왜)을 함께 제공

3. 예시(멀티샷)와 XML 태그로 구조화

4. 출력 형식과 장황함 제어

5. effort와 thinking 조절

6. 행동 유발 vs 신중 모드

7. 자율성과 안전의 균형

8. 과잉엔지니어링·환각 억제

9. 장기·멀티 컨텍스트 워크플로우

빠른 처방 체크리스트

참고 문서

목차

Ch13. 프롬프팅 베스트 프랙티스

1. 명확하고 구체적으로 지시

2. 맥락(왜)을 함께 제공

3. 예시(멀티샷)와 XML 태그로 구조화

4. 출력 형식과 장황함 제어

5. effort와 thinking 조절

6. 행동 유발 vs 신중 모드

7. 자율성과 안전의 균형

8. 과잉엔지니어링·환각 억제

9. 장기·멀티 컨텍스트 워크플로우

빠른 처방 체크리스트

참고 문서

목차