[Claude Code] 에이전트 성능을 올리는 Claude 프롬프트 엔지니어링 정리

1. 도입부 (Introduction)

Claude 4.7의 등장은 LLM을 단순한 '언어 모델'에서 '자율 에이전트'로 진화시켰다. 이제 프롬프트 엔지니어링은 단순히 좋은 질문을 던지는 것을 넘어, 모델의 사고 예산(Thinking Budget)을 관리하고, 도구 사용의 병렬성을 최적화하며, 자율적인 문제 해결 경로를 설계하는 공학적 단계에 접어들었다.

 

2. 전문가 역할 부여 (Role Prompting)

Claude에게 명확한 역할을 부여하면 모델의 응답 톤과 정확도가 특정 도메인에 최적화된다. 이는 단순한 수식이 아니라 모델의 '사고 방식'을 결정하는 가장 기초적인 단계다.

📌 2.1 시스템 프롬프트의 힘

공식 문서에 따르면, 단 한 문장의 역할 부여만으로도 모델의 지침 준수 능력이 비약적으로 상승한다.

• 방법: "당신은 ~입니다(You are a...)"로 시작하는 명확한 정체성을 시스템 프롬프트 맨 앞에 배치한다.
• 예시:
  • You are a helpful coding assistant specializing in Python. (파이썬 전문가)
  • You are an AI physician's assistant helping doctors diagnose illnesses. (의료 보조 전문가)

 

📌 4.2 Claude Code에서 역할 설정 (CLAUDE.md)

Claude Code를 사용할 때는 프로젝트 루트의 CLAUDE.md 상단에 역할을 명시하여 모델의 정체성을 고정할 수 있다.

# CLAUDE.md

## Identity & Role
당신은 'Google 스타일 가이드'를 엄격히 준수하는 **'10년 차 시니어 풀스택 엔지니어'**입니다. 
단순한 코드 생성을 넘어 아키텍처의 안정성과 보안성을 최우선으로 고려하여 답변하고 작업하세요.

 

3. 핵심 메커니즘: 노력(Effort)과 적응형 사고(Adaptive Thinking)

Claude 4.7과 4.6은 사용자가 모델의 '추론 예산'을 직접 결정할 수 있게 설계되었다.

💡 핵심 변화 요약

1. 적응형 사고 (Adaptive Thinking): 고정된 사고량이 아니라 작업 난이도에 맞춰 스스로 생각의 깊이를 보정한다.
2. 노력 매개변수 (Effort): 지능과 비용/속도를 거래(Trade-off)하는 레버다.
3. 엄격한 지침 준수: 특히 낮은 노력 수준에서는 사용자의 말을 '문자 그대로' 해석하며 임의로 작업을 확장하지 않는다.

 

3.1 노력 수준(Effort Level) 상세 분석

effort 매개변수는 모델이 문제 해결에 투입할 '에너지'를 결정한다.

수준	추천 상황	특징
xhigh	코딩 및 에이전트 (강력 추천)	도구 호출과 추론을 가장 조화롭게 사용한다. 복잡한 버그 수정에 필수다.
high	일반적인 전문 작업	지능과 속도의 균형이 가장 좋다.
medium	비용 민감한 대량 처리	적절한 지능을 유지하면서 토큰 사용량을 줄인다.
low	간단한 조회, 단순 요약	매우 빠르지만, 복잡한 문제에서는 '과소 사고'의 위험이 있다.

팁: 만약 low에서 결과가 좋지 않다면 프롬프트를 고치기보다 먼저 노력을 high로 올리는 것도 방법이다.  반대로 모델이 너무 쓸데없이 깊게 생각한다면 "의심스러울 때는 직접 응답하라"는 지침을 추가해야면 좋다.

3.1.1 Claude Code(터미널)에서 설정하는 법

Claude Code 사용자라면 가장 직관적인 두 가지 방법을 사용할 수 있다.

1. /config 대화형 메뉴 (추천)
   1. 터미널 세션 중 /config를 입력하면 설정 패널이 열린다.
   2. Model 또는 Behavior 탭에서 Effort Level 항목을 찾는다.
   3. low, medium, high, xhigh 중 하나를 선택하면 즉시 반영되며, 이후 세션에서도 유지된다.
2. 설정 파일 (settings.json) 고정
   1. 특정 프로젝트나 전역 환경에서 노력을 고정하고 싶을 때 사용한다.
   2. 경로: ~/.claude/settings.json (전역) 또는 프로젝트 루트의 .claude/settings.json (로컬)
   3. 설정 예시:
   4. { "model": "claude-opus-4-7", "effortLevel": "xhigh" }

3.1.2 Anthropic API에서 설정하는 법

직접 코드를 통해 호출할 경우 output_config 파라미터 내부에 정의한다.

# Python SDK 예시
message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={"effort": "xhigh"}, # 바로 여기서 지능 수준 결정
    messages=[{"role": "user", "content": "대규모 리팩토링 수행해줘"}]
)

 

3.2 적응형 사고(Adaptive Thinking) 제어

Claude는 작업의 난이도를 스스로 판단해 생각의 깊이를 결정한다. 만약 모델이 충분히 생각하지 않는다면 다음 지침을 추가하라.

"이 작업은 다단계 추론이 필수적입니다. 최종 응답을 내기 전에 문제의 모든 측면을 신중하게 반영하세요."

반대로 너무 오래 생각하여 지연 시간이 길어진다면 다음과 같이 제어한다.

"사고는 답변 품질을 의미 있게 개선할 때만 사용하세요. 간단한 해결책이 있다면 직접 응답하는 것을 우선시하십시오."

 

 

4. 도구 사용(Tool Use) 마스터하기

Claude 4.7은 도구를 다루는 방식이 이전 모델과 다르다. 더 똑똑해졌지만, 때로는 신중함이 과해 도구 사용을 주저할 수도 있다.

4.1 Claude Code 사용자를 위한 CLAUDE.md 전략

Claude Code 환경에서는 프로젝트 루트의 CLAUDE.md가 모델의 '운영 매뉴얼'이 된다. 여기에 다음과 같은 적극적 액션 트리거를 설정해 두는 것이 좋아.

# CLAUDE.md 예시

## Behavior
<default_to_action>
- 사용자의 허락을 구하기보다 도구(파일 읽기, 검색 등)를 사용해 스스로 답을 찾으세요.
- 의도가 불명확하면 가장 유용한 조치를 추론하여 즉시 실행하세요.
</default_to_action>

## Coding Style
- 타입 힌트를 반드시 포함하고, Google 스타일 가이드를 준수하세요.
- 모든 기능 수정 후에는 반드시 관련 테스트(`npm test`)를 실행하세요.

 

 

4.2 병렬 도구 호출(Parallel Tool Use) 최적화

속도를 높이기 위해 여러 도구를 동시에 사용하도록 유도할 수 있다.

"독립적인 작업(예: 3개의 다른 파일 읽기)은 순차적으로 하지 말고, 한 번에 병렬로 호출하여 효율성을 극대화하세요."

 

4.2.1 병렬 도구 호출 예시

여러 개의 파일을 동시에 읽거나 검색을 수행하여 작업 시간을 단축하는 기능이다. 아래 지침을 추가하여 이 기능을 활성화한다.

<use_parallel_tool_calls>
도구 호출 간에 종속성(A의 결과가 B에 필요함)이 없다면, 모든 독립적인 작업을 병렬로 수행하세요. 
예를 들어 3개의 파일을 읽어야 할 때 하나씩 순차적으로 읽지 말고, 한 번에 호출하여 효율성을 높이십시오.
</use_parallel_tool_calls>

효과: 순차적으로 돌던 스피너가 터미널에서 여러 개 동시에 나타나며 작업 속도가 비약적으로 향상된다.

 

5. 에이전틱 워크플로우: EPIC 사이클

장기적인 자율 작업을 수행할 때 Claude가 길을 잃지 않도록 EPIC 사이클을 적용한다.

1. Explore (탐색): 관련 코드와 문서를 읽고 맥락을 파악한다. (이 단계에서는 수정을 금지함)
2. Plan (계획): 수행할 작업 목록을 todo.md 등에 작성하고 사용자 승인을 받는다.
3. Implement (구현): 계획에 따라 증분적으로 코드를 수정한다.
4. Commit/Verify (검증): 테스트를 실행하고 결과를 확인한 뒤 최종 확정한다.

💡 상태 유지 팁: 에이전트 세션 간에 컨텍스트가 초기화되는 경우, 모델에게 progress.txt나 git log를 먼저 읽게 하여 '기억의 연속성'을 확보하게 하라.

 

 

6. AI Slop 탈피와 커스텀 미학 설계

Claude는 기본적으로 '크림색 & 세리프' 스타일을 가지고 있다. 하지만 모든 앱이 이래야 하는 것은 아니다.

6.1 구체적인 디자인 대안 명시

일반적인 지침("깔끔하게 해줘")은 효과가 없다. 구체적인 수치와 스타일을 던져야 한다.

• 색상: #F4F1EA 대신 #11171B 같은 다크 모드 팔레트 명시.
• 폰트: 시스템 폰트 대신 Alumni Sans SC 같은 구체적인 웹 폰트 지정.
• 여백/곡률: "모든 카드와 버튼에 4px의 border-radius를 일관되게 적용하라."

 

6.2 디자인 옵션 제안 루프

모델에게 구현 전 3~4가지 시각적 방향을 먼저 제안하게 한 뒤, 사용자가 선택한 방향으로 코딩하게 하면 만족도가 비약적으로 상승한다.

[디자인 옵션 제안 예시 프롬프트]

구축하기 전에, 이 브리프에 맞춘 4개의 서로 다른 시각적 방향을 제안하세요.
각 방향에 대해 (배경 Hex / 악센트 Hex / 서체 이름 — 한 줄 근거)를 포함해야 합니다.
내가 하나를 선택하면, 그 방향만 엄격히 준수하여 구현을 시작하세요.

• 효과: Claude의 기본값(크림/세리프)을 깨고 사용자가 원하는 미학적 방향을 먼저 확정할 수 있다.

7. 실무 팁 및 마이그레이션 주의사항

7.1 코드 검토(Code Review) 재현율 최적화

Claude 4.7은 "치명적인 문제만 알려줘"라고 하면 너무 보수적으로 변한다. 버그를 낱낱이 찾아내게 하려면 필터링 책임을 모델에게서 뺏어와야 한다.

"심각도에 관계없이 발견된 모든 잠재적 결함을 보고하세요. 필터링은 다음 단계에서 진행할 것이니, 지금은 최대한 많이 찾아내는 것이 목표입니다."

 

7.2 미리 채우기(Prefilling)에서 구조화된 출력으로

과거에는 Assistant: { 로 시작하여 JSON을 강제했지만, 이제는 구조화된 출력(Structured Outputs) 기능을 사용하거나 XML 태그 내부에 결과를 담으라고 지시하는 것이 표준이다.

 

7.3 긴 맥락에서의 인용(Citation) 전략

200k 토큰을 가득 채운 문서에서 정보를 찾을 때, Claude에게 "답변 전 반드시 해당 정보가 있는 원문 문장을 그대로 인용하라"고 명령하라. 이는 모델이 긴 컨텍스트의 소음을 뚫고 정확한 지점에 집중하게 만든다.

 

 

8. 결론 (Conclusion)

Claude 4.7 시대의 프롬프트 엔지니어링은 '에이전트의 자율성'과 '사용자의 제어권' 사이의 균형점을 찾는 과정이다.

우리는 모델에게 명확한 XML 구조를 제공하고, 적절한 노력 수준을 할당하며, 결과물의 미학적 기준을 구체적으로 제시함으로써 단순한 도구를 넘어선 진정한 AI 동료를 얻게 된다. Claude는 당신이 제공한 맥락과 지침의 수준만큼 똑똑해진다는 점을 항상 기억하자.

추가 학습 리소스:

• Anthropic 프론트엔드 디자인 스킬 가이드
• Claude 4.7 마이그레이션 공식 지침