Claude Opus 5 프롬프팅

이 가이드는 Claude Opus 5에 특화된 프롬프팅 패턴을 다룹니다. 모델의 기능과 API 변경 사항은 Claude Opus 5의 새로운 기능을 참조하세요. 현재의 모든 Claude 모델에 적용되는 기법은 프롬프팅 모범 사례를 참조하세요.

Claude Opus 5는 복잡한 에이전트 코딩과 엔터프라이즈 작업을 위해 만들어졌으며, 특히 장기적인 에이전트 작업에 강점이 있습니다. 기존 Claude Opus 4.8 프롬프트에서도 별도 조정 없이 잘 작동합니다. 다음 패턴들은 가장 자주 튜닝이 필요한 동작들을 다룹니다.

기능 개선 사항

Claude Opus 4.8과 비교하여 프롬프팅과 가장 관련이 깊은 개선 사항은 다음과 같습니다:

• 에이전트 코딩: Claude Opus 5는 어려운 코딩 작업, 즉 다중 파일 기능, 대규모 리팩터링, 엔드투엔드 기능 작업에서 가장 강력합니다. 스텁이나 플레이스홀더를 남기지 않고 전체 작업을 완료하며, 처음부터 완전한 작업 명세를 제공받고 그대로 실행하도록 두었을 때 가장 좋은 성능을 냅니다. 단일 턴 편집과 같은 더 쉬운 작업에서도 잘 작동하지만, 이 경우 이전 모델과의 차이는 더 작습니다.
• 코드 리뷰 및 버그 찾기: Claude Opus 5는 높은 정밀도와 재현율로 코드를 리뷰합니다. 패스당 높은 비율로 실제 버그를 찾아내며, 추가로 발견한 사항도 대부분 거짓 양성이 아닌 실제 문제입니다. 낮은 effort 설정에서도 정확도가 유지되므로, 리뷰 시점에 빠른 패스를 수행하고 나중에 더 철저한 패스를 수행하는 방식을 지원합니다. 리뷰 프롬프트에 "심각도가 높은 문제만 보고하라" 또는 "보수적으로 판단하라"와 같은 내용이 있으면 모델이 그 지시를 문자 그대로 따라 더 적게 보고할 수 있습니다. 대신 모든 것을 보고하도록 요청하고 별도의 패스에서 필터링하세요.
• 낮은 effort에서의 효율성: low 및 medium effort는 더 높은 설정에 비해 훨씬 적은 토큰과 latency(지연 시간)로 우수한 품질을 제공합니다. 기본값(high)으로 시작하여 평가 결과에 따라 조정하세요. 품질이 유지되는 곳이라면 토큰 비용과 응답 시간을 제어하는 주요 수단으로 low와 medium을 적극적으로 사용하고, 까다로운 코딩 및 에이전트 작업에는 xhigh로 올리세요. 이전 모델에서 effort 기본값을 그대로 가져왔다면 자체 평가에서 effort 스윕을 다시 실행하세요. 전체 권장 사항은 Effort를 참조하세요.
• 비전: Claude Opus 5는 차트, 문서, 다이어그램 이해와 UI 및 프런트엔드 시각적 복제에 강합니다. 이전 모델에 맞춰 튜닝했던 프롬프트 측 비전 우회 방법이 있다면 다시 검증하세요. 더 이상 필요하지 않을 수 있습니다. 비전 성능은 모델이 작업을 반복적으로 분석하고, 자르고, 시각적으로 검증할 수 있는 도구를 가지고 있을 때 가장 강력하며, 도구 사용은 사고만 사용하는 것보다 비용 효율적인 수단입니다.
• 긴 컨텍스트 작업: Claude Opus 5는 기본값이자 최대값으로 1M 토큰 컨텍스트 윈도우를 가지며, 지시 따르기, 도구 호출, 추론이 윈도우 전체에 걸쳐 일관되게 유지됩니다.
• 오피스 및 문서 작업: Claude Opus 5는 단순하지 않은 수식이 포함된 복잡한 다중 시트 스프레드시트를 생성하고 다루며, 잘 구조화된 슬라이드 덱을 만들어냅니다. 따라야 할 특정 스타일이나 템플릿이 있다면 프롬프트로 제공하세요.
• 멀티 에이전트 조율: Claude Opus 5는 서브에이전트 팀을 잘 조율하며, 효과적인 작성자-검증자 패턴을 보이고 에이전트들이 서로의 작업을 덮어쓰는 경우가 거의 없습니다. 비용에 민감한 워크로드에서는 위임에 상한을 두세요. 서브에이전트 생성 제어를 참조하세요.

응답 길이와 장황함

Claude Opus 5의 기본 사용자 대상 응답은 이전 Opus 모델보다 깁니다. effort 파라미터는 모델이 얼마나 말하는지가 아니라 얼마나 사고하는지를 제어합니다. effort를 낮추면 사고량은 줄어들 수 있지만 눈에 보이는 응답이 안정적으로 짧아지지는 않습니다. 응답 길이를 제어하려면 명시적으로 프롬프트하세요.

짧은 간결성 지시가 효과적입니다. 예를 들어, 사용자 대상 멀티턴 제품의 경우:

Keep responses focused, brief, and concise. Keep disclaimers and caveats short, and spend most of the response on the main answer. When asked to explain something, give a high-level summary unless an in-depth explanation is specifically requested.

긴 시스템 프롬프트에서는 이 지시를 프롬프트 끝부분 근처의 짧은 리마인더와 함께 사용하세요:

<tone_preference>
Keep outputs reasonably concise.
</tone_preference>

사용자 대상 진행 상황 업데이트

Claude Opus 5는 에이전트 작업 중에 쉽게 내레이션을 합니다. 무엇을 하려는지 미리 알리는 경향이 있으며, 에이전트 세션에서의 메시지당 출력이 이전 모델보다 긴 경우가 많습니다. 작업 중 사용자와 어떻게 소통해야 하는지에 대한 명시적인 안내가 도움이 됩니다. 내레이션을 줄이려면 원하는 빈도와 형태를 설명하세요:

Before your first tool call, say in one sentence what you're about to do. While working, give a brief update only when you find something important or change direction. When you finish, lead with the outcome: your first sentence should answer "what happened" or "what did you find," with supporting detail after it for readers who want it.

내레이션을 늘리거나 스타일을 바꾸려면 같은 수단을 반대 방향으로 적용하면 됩니다. 업데이트가 어떤 모습이어야 하는지 명시적으로 설명하고 예시를 제공하세요. 원하는 소통 스타일의 긍정적 예시가 하지 말아야 할 것에 대한 지시보다 더 효과적인 경향이 있습니다.

작성된 산출물의 길이

대화상의 장황함과는 별개로, Claude Opus 5가 디스크에 작성하는 파일(보고서, Markdown 문서, 요약)은 이전 모델보다 긴 경우가 많습니다. 제품에 Claude가 작성한 문서가 포함된다면 명시적인 길이 보정을 추가하세요:

Match the length of written documents to what the task needs: cover the substance, but do not pad with filler sections, redundant summaries, or boilerplate.

작업 범위와 과도한 검증

Claude Opus 5는 지시받지 않아도 자신의 작업을 검증합니다. 프롬프트에 명시적인 검증 지시("단순하지 않은 모든 작업에 최종 검증 단계를 포함하라", "서브에이전트를 사용해 검증하라")가 있다면 제거하세요. 이런 지시는 Claude Opus 5에서 과도한 검증을 유발하며, 제거하면 품질 손실 없이 낭비되는 토큰이 줄어듭니다. 별도의 검증 단계를 추가하는 레거시 하네스 스캐폴딩에도 동일하게 적용됩니다.

Claude Opus 5는 또한 요청되지 않은 단계를 추가하거나 작업이 무엇이어야 하는지에 대해 자체 판단을 적용하여 작업 범위를 확장할 수 있습니다. 좁은 범위의 작업에서는 범위를 명시적으로 제한하세요:

Deliver what was asked, at the scope intended. Make routine judgment calls yourself, and check in only when different readings of the request would lead to materially different work. If the request seems mistaken or a better approach exists, say so in a sentence and continue with the task as asked rather than quietly narrowing, widening, or transforming it. Finish the whole task, and stop short of actions that are clearly beyond what was asked.

서브에이전트 생성 제어

Claude Opus 5는 이전 모델보다 더 쉽게 서브에이전트에 위임합니다. 위임은 진정으로 독립적이고 규모가 있는 작업 트랙에서는 효과가 있지만, 작은 작업에 적용하면 비용과 시간이 배로 늘어납니다. 하네스가 서브에이전트를 지원한다면 어떤 시나리오에서 위임이 정당한지 명시적인 안내를 제공하거나, 실행할 수 있는 에이전트 수에 결정론적 상한을 설정하세요. 예를 들어:

Delegate to a subagent only for large tasks that are genuinely independent and parallelizable, such as a wide multi-file investigation. Do not delegate work you can finish yourself in a handful of tool calls, and do not use subagents to verify or double-check your own work. If one subagent can complete the task, use one rather than several, and keep spawn counts low.

하네스가 Claude Code 또는 Claude Agent SDK라면, 결정론적 상한은 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 및 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS 환경 변수와 SDK의 max_budget_usd 옵션입니다. 이들은 Claude Code 2.1.217 이상이 필요하므로, 고정된 SDK를 Claude Opus 5에 연결하기 전에 업데이트하세요. Claude Code는 claude_code 시스템 프롬프트 프리셋을 사용할 때에만 Claude Opus 5에 자체 위임 지시를 추가합니다. 커스텀 시스템 프롬프트를 사용하거나 시스템 프롬프트를 생략한 경우에는 이 섹션의 예시와 같은 위임 지시를 직접 추가하세요. Agent SDK 문서의 서브에이전트 깊이, 동시성, 지출 상한 설정을 참조하세요.

자기 수정

Claude Opus 5는 프롬프트 없이도 자신의 실수를 잘 포착하고 수정합니다. 이미 수행하는 재확인을 지시하는 것("답을 다시 확인하라", "응답하기 전에 재검증하라")은 피하세요. 검증 지시와 마찬가지로 이런 지시는 모델 자체의 동작과 중첩되어 결과를 개선하지 않으면서 비용만 추가합니다.

이 모델은 또한 이전 모델보다 자신의 이전 진술에 대한 수정을 더 많이 내레이션하는데, 이는 사용자 대상 제품에서 바람직하지 않을 수 있습니다. 수정 내레이션을 중요한 수정으로만 제한하려면:

Only correct an earlier statement when the error would change the user's code, conclusions, or decisions. State corrections plainly and briefly, then continue the task. For slips that change nothing for the user, make the fix and move on without noting it.

사고를 비활성화한 상태로 실행하기

Claude Opus 5는 기본적으로 사고가 켜진 상태로 실행되며, 사고는 effort high 이하에서만 비활성화할 수 있습니다. 마이그레이션 가이드를 참조하세요. 사고가 비활성화되면 모델의 눈에 보이는 출력에 두 가지 아티팩트가 간혹 나타날 수 있습니다. 두 가지 모두에 대한 주요 완화 방법은 사고를 비활성화하는 대신 사고를 켜 둔 채 더 낮은 effort 수준으로 토큰 비용을 제어하는 것입니다. 대부분의 작업에서 low effort로 사고를 활성화한 것이 비슷한 비용으로 사고를 비활성화한 것보다 더 나은 성능을 냅니다.

텍스트로 출력되는 도구 호출. 사고가 비활성화되면 모델이 간혹 구조화된 tool_use 블록을 내보내는 대신 사용자 대상 텍스트에 도구 호출을 작성합니다. 턴은 정상적으로 완료되지만 호출은 실행되지 않으며, 에이전트 루프에서는 유출된 텍스트가 대화 기록에 남아 이후 턴에도 영향을 미칩니다. 이는 검색과 같이 도구 사용이 많은 워크로드에서 가장 흔합니다.

출력에 포함되는 내부 XML 태그. 사고가 비활성화되면 모델이 <thinking> 태그나 기타 내부 XML 태그를 눈에 보이는 응답에 내보낼 수 있습니다. 시스템 프롬프트에 모델이 사고하지 말거나 추론하지 말라고 지시하는 규칙이 있다면 제거하세요. 그런 종류의 지시는 태그 유출을 증가시킵니다.

사고를 비활성화한 상태로 유지해야 하는 통합의 경우, 하나의 결합된 지시로 두 아티팩트를 모두 완화할 수 있습니다. 이 지시는 모델에게 도구 호출 전에 말할 수 있는 명시적 권한, 적합한 도구가 없을 때 호출을 강제하는 것에 대한 대안, 그리고 내부 태그에 대한 일반 규칙을 제공합니다:

When you use a tool, you may say a brief sentence first. If no tool can express what the user asked for, say so instead of guessing. Do not include internal or system XML tags in your response.

사고 태그를 이름으로 지목하는 지시는 일반적인 형태보다 덜 효과적이므로, 구체적으로 이름을 언급하는 것은 피하세요.