---
title: "Claude Thinking, effort, Tool Use를 실무에서 다루는 법"
slug: "claude-prompting-best-practices-03-thinking-tool-use"
canonicalUrl: "https://moonshotnotes.com/posts/claude-prompting-best-practices-03-thinking-tool-use/"
sourceUrl: "https://moonshotnotes.com/posts/claude-prompting-best-practices-03-thinking-tool-use/"
markdownUrl: "https://moonshotnotes.com/agent/posts/claude-prompting-best-practices-03-thinking-tool-use.md"
language: "ko"
category: "AI Development"
updatedAt: "2026-05-02"
agentTokenEstimate: 1647
---

# Claude Thinking, effort, Tool Use를 실무에서 다루는 법

Claude 최신 모델을 운영할 때 프롬프트 내용만큼 중요한 것이 추론 깊이와 도구 사용 정책입니다. 복잡한 작업에서는 더 깊은 thinking이 필요하지만, 모든 요청에 높은 effort를 쓰면 비용과 지연 시간이 커집니다. 반대로 도구 사용 조건이 느슨하면 모델이 필요 이상으로 검색하거나, 위험한 액션을 시도할 수 있습니다.

## Agent metadata

- Source: https://moonshotnotes.com/posts/claude-prompting-best-practices-03-thinking-tool-use/
- Markdown: https://moonshotnotes.com/agent/posts/claude-prompting-best-practices-03-thinking-tool-use.md
- Language: ko
- Category: AI Development
- Tags: Claude, AI Agent, Tool Use, Prompt Engineering
- Updated: 2026-05-02
- Estimated tokens: 1647

Claude 최신 모델을 운영할 때 프롬프트 내용만큼 중요한 것이 **추론 깊이와 도구 사용 정책**입니다. 복잡한 작업에서는 더 깊은 thinking이 필요하지만, 모든 요청에 높은 effort를 쓰면 비용과 지연 시간이 커집니다. 반대로 도구 사용 조건이 느슨하면 모델이 필요 이상으로 검색하거나, 위험한 액션을 시도할 수 있습니다.

이 글은 Claude를 API, 코딩 에이전트, 리서치 자동화에 붙일 때 thinking, effort, tool use를 어떻게 운영 기준으로 삼을지 정리합니다.

분석 기준일: **2026-05-02**
시리즈: **Claude 프롬프트 실무 가이드**
이 글의 범위: Claude Opus 4.7, adaptive thinking, effort, tool use, 에이전트 안전장치

---

## 핵심 요약

- Claude Opus 4.7은 공식 문서 기준으로 복잡한 추론과 agentic coding에 강한 모델로 안내됩니다.
- Opus 4.7에서는 adaptive thinking이 핵심이며, thinking 관련 설정은 모델별 지원 방식을 확인해야 합니다.
- effort는 품질, 비용, 지연 시간의 운영 파라미터입니다. 모든 작업에 최고 수준을 쓰는 것은 비효율적입니다.
- Tool use는 “필요하면 알아서 써”가 아니라 “언제, 어떤 조건에서, 무엇을 금지할지”를 명시해야 합니다.
- 코딩 에이전트 작업에서는 프롬프트보다 권한, 상태, 검증 루프가 더 큰 리스크가 될 수 있습니다.

---

## 1. thinking은 성능 옵션이 아니라 운영 선택이다

복잡한 문제에서 모델이 더 깊게 생각하게 하는 것은 도움이 됩니다. 하지만 모든 요청에 깊은 thinking을 적용하는 것은 비용 대비 효율이 낮을 수 있습니다.

예를 들어 다음 작업은 깊은 추론이 필요하지 않습니다.

| 작업 | 추천 방향 |
|---|---|
| 짧은 문장 교정 | 낮은 effort |
| 단순 분류 | 낮거나 중간 effort |
| 정해진 템플릿 채우기 | 낮거나 중간 effort |
| 간단한 요약 | 중간 effort |

반대로 다음 작업은 더 깊은 추론이 필요합니다.

| 작업 | 추천 방향 |
|---|---|
| 코드 리뷰 | 높은 effort |
| 장애 원인 분석 | 높은 effort |
| 여러 문서 비교 | 높은 effort |
| 장시간 코딩 에이전트 | 높은 effort 또는 xhigh |
| 보안·권한·비용 판단 | 높은 effort |

실무에서는 “높을수록 좋다”가 아니라 “작업 리스크에 맞게 쓴다”가 맞습니다.

## 2. Claude Opus 4.7과 adaptive thinking

Anthropic 모델 문서 기준으로 Claude Opus 4.7은 복잡한 작업과 agentic coding에 강한 최신 상위 모델로 안내됩니다. 또한 Opus 4.7은 adaptive thinking을 지원하지만, 요청에서 `thinking: {type: "adaptive"}`를 명시해야 thinking이 켜집니다. 예전처럼 `thinking: {type: "enabled", budget_tokens: N}`를 보내는 방식은 Opus 4.7에서 더 이상 맞지 않습니다.

이 정보는 시간이 지나면 바뀔 수 있습니다. 모델명, 가격, 컨텍스트 길이, thinking 지원 방식은 공식 문서 기준으로 확인해야 합니다. 운영 코드에 하드코딩할 때는 특히 주의해야 합니다.

실무 기준은 다음과 같습니다.

```text
# 예시
모델명, 가격, context window, max output, thinking 지원 방식은
블로그 글이나 기억이 아니라 공식 모델 문서와 API 응답을 truth source로 삼는다.
Opus 4.7에서 thinking이 필요한 요청은 thinking.type=adaptive와 output_config.effort를 함께 확인한다.
```

모델별 thinking 동작이 다를 수 있으므로, 기존 Claude 4.5 또는 4.6 설정을 Opus 4.7로 옮길 때는 마이그레이션 점검이 필요합니다.

## 3. effort 설정의 판단 기준

effort는 모델에게 어느 정도 깊이로 문제를 풀게 할지 정하는 운영 레버입니다.

| effort 수준 | 추천 상황 | 장점 | 주의점 |
|---|---|---|---|
| low | 짧고 반복적인 작업 | 빠르고 비용 절감 | 복잡한 문제에서 과소 추론 |
| medium | 일반 요약·분류 | 균형형 | 코드·정책 판단에는 부족할 수 있음 |
| high | 리서치·코드 리뷰·정책 판단 | 품질과 안정성 향상 | 단순 작업에는 과함 |
| xhigh | 장시간 에이전트·복잡한 설계 | 깊은 추론 유도 | 비용과 지연 시간 증가 |
| max | 매우 어려운 검증 작업 | 일부 난제에 유리 | 과도한 사고와 비용 가능 |

팀에서 Claude를 운영한다면 작업 유형별 기본값을 정해두는 편이 좋습니다.

```text
# 예시
문장 변환: low
문서 요약: medium
정책 판단: high
코드 리뷰: high
장시간 코딩 에이전트: xhigh
장애 원인 분석: high 또는 xhigh
```

이렇게 기본값을 두면 비용을 예측하기 쉽고, 품질 문제가 생겼을 때 조정할 지점도 명확해집니다.

## 4. tool use는 권한 모델이다

Tool use는 단순히 모델이 외부 기능을 호출하는 기능이 아닙니다. 실제 운영에서는 권한 모델입니다.

Claude가 사용할 수 있는 도구가 늘어나면 다음 리스크도 함께 늘어납니다.

| 도구 | 리스크 |
|---|---|
| 웹 검색 | 오래된 정보, 비공식 출처, 과도한 검색 |
| 파일 읽기 | 민감한 파일 노출 |
| 파일 수정 | 의도하지 않은 변경 |
| 셸 실행 | 파괴적 명령, 비용 큰 작업 |
| 브라우저 조작 | 잘못된 클릭, 로그인 상태 의존 |
| DB/API 호출 | 실제 데이터 변경 |

따라서 프롬프트에는 도구 사용 조건과 금지 행동이 함께 있어야 합니다.

```xml
<!-- 예시 -->
<tool_policy>
- 최신 정보, 가격, 법률, 릴리스 노트는 공식 출처를 확인하세요.
- 입력에 충분한 정보가 있으면 검색하지 마세요.
- 파일을 수정하기 전에는 관련 파일을 먼저 읽고 변경 범위를 요약하세요.
- 테스트 실행이 가능하면 수정 후 테스트를 실행하세요.
- 삭제, force push, reset, 배포, DB 변경은 사용자 확인 없이 하지 마세요.
</tool_policy>
```

이 정책은 모델을 느리게 만들기 위한 것이 아닙니다. 실제 업무에서 안전하게 실행하기 위한 최소한의 경계입니다.

## 5. 도구를 너무 많이 쓰는 문제

Claude가 도구를 과하게 쓰면 비용과 시간이 늘어납니다. 특히 리서치나 코드 탐색에서 이미 충분한 정보가 있는데도 검색이나 파일 읽기를 반복할 수 있습니다.

이때는 사용 조건을 좁힙니다.

```text
# 예시
입력에 충분한 정보가 있으면 도구를 사용하지 말고 직접 답변하세요.
최신 정보나 변경 가능성이 큰 사실이 필요할 때만 공식 출처를 확인하세요.
같은 사실을 확인하기 위해 중복 검색하지 마세요.
```

도구 사용을 줄이는 핵심은 “도구 금지”가 아니라 “도구가 필요한 조건”을 명확히 하는 것입니다.

## 6. 도구를 너무 적게 쓰는 문제

반대로 모델이 확인 없이 답하면 더 위험합니다. 최신 모델명, 가격, API 파라미터, 법률, 보안 권고, 배포 상태처럼 변할 수 있는 정보는 반드시 확인해야 합니다.

```text
# 예시
다음 정보는 기억에 의존하지 말고 공식 출처에서 확인하세요.
- 모델명
- 가격
- API 파라미터
- 릴리스 노트
- 보안 권고
- 법률·정책 변경
```

코드 작업에서도 마찬가지입니다.

```text
# 예시
코드에 대해 주장하기 전에 관련 파일을 반드시 열어 확인하세요.
수정 후 가능한 테스트를 실행하세요.
테스트를 실행하지 못했다면 이유를 명시하세요.
```

이 기준이 없으면 Claude는 그럴듯한 답을 할 수 있지만, 실제 코드나 현재 문서와 어긋날 수 있습니다.

## 7. 에이전트 코딩 프롬프트의 최소 안전장치

코딩 에이전트는 파일을 읽고, 수정하고, 테스트를 실행할 수 있습니다. 그래서 일반 챗봇 프롬프트보다 더 엄격한 경계가 필요합니다.

```xml
<!-- 예시 -->
<task>
{{FEATURE_OR_BUGFIX}}를 구현하세요.
</task>

<constraints>
- 요청 범위를 벗어난 리팩터링은 하지 마세요.
- 함수 시그니처와 공개 API는 필요한 경우에만 변경하세요.
- 기존 테스트를 삭제하거나 약화하지 마세요.
- 임시 파일을 만들면 작업 끝에 삭제하세요.
</constraints>

<workflow>
1. 프로젝트 구조와 관련 파일을 확인하세요.
2. 수정 계획을 짧게 세우세요.
3. 필요한 파일만 수정하세요.
4. 가능한 경우 테스트와 린트를 실행하세요.
5. 변경사항, 테스트 결과, 남은 리스크를 요약하세요.
</workflow>

<safety>
삭제, force push, reset, DB 변경, 배포는 사용자 확인 없이 하지 마세요.
비밀키와 개인정보를 출력하지 마세요.
</safety>
```

이 프롬프트는 모델에게 “코드를 잘 짜라”보다 더 중요한 것을 알려줍니다. 어디까지 수정할 수 있고, 어떻게 검증해야 하며, 어떤 행동은 금지되는지입니다.

## 8. 상태 파일이 필요한 작업

긴 작업에서는 Claude가 중간 상태를 잃을 수 있습니다. 이때는 외부 상태 파일을 쓰게 하는 방식이 도움이 됩니다.

| 파일 | 목적 |
|---|---|
| progress.md | 진행 상황, 다음 작업, 막힌 점 |
| tests.json | 테스트 목록과 통과 여부 |
| decisions.md | 설계 결정과 이유 |
| rollback.md | 되돌리기 방법 |
| git log | 실제 변경 이력 |

예시는 다음과 같습니다.

```text
# 예시
작업을 시작하기 전에 progress.md와 tests.json을 생성하세요.
각 변경 후 어떤 파일을 왜 바꿨는지 progress.md에 기록하세요.
테스트를 추가하거나 실행할 때마다 tests.json의 상태를 업데이트하세요.
테스트를 삭제하거나 약화하는 것은 허용되지 않습니다.
```

단, 짧은 작업에 상태 파일을 강제하면 오히려 과합니다. 여러 파일, 여러 단계, 여러 테스트가 얽힌 작업에서만 쓰는 편이 좋습니다.

## 9. 테스트만 통과하는 하드코딩을 막는 법

코딩 에이전트에게 “테스트를 통과시켜라”만 강하게 말하면 잘못된 최적화를 할 수 있습니다. 테스트에만 맞춘 하드코딩이나 우회 구현을 만들 수 있기 때문입니다.

프롬프트에는 다음 조건을 넣어야 합니다.

```text
# 예시
테스트 케이스에만 맞춘 하드코딩을 하지 마세요.
모든 유효 입력에 대해 동작하는 일반적인 해결책을 구현하세요.
테스트가 잘못되었다고 판단되면 우회하지 말고 문제를 보고하세요.
```

테스트는 요구사항의 일부이지 전체가 아닙니다. 이 문장을 명시해야 모델이 테스트 통과만을 목표로 삼는 것을 줄일 수 있습니다.

## 10. 운영 체크리스트

```text
# 예시
[ ] 최신 모델명과 API 파라미터를 공식 문서에서 확인했다.
[ ] Opus 4.7 thinking 요청은 thinking.type=adaptive를 명시했다.
[ ] 작업 유형별 effort 기본값을 정했다.
[ ] 단순 작업에 과한 thinking을 쓰지 않는다.
[ ] 위험한 작업에는 높은 effort와 검증 루프를 쓴다.
[ ] 도구 사용 조건을 명확히 했다.
[ ] 도구 금지 행동을 명시했다.
[ ] 파일 수정 전 탐색, 수정 후 테스트 원칙을 넣었다.
[ ] destructive action은 사용자 확인 없이 금지했다.
[ ] 비밀키와 개인정보 출력 금지를 명시했다.
[ ] 테스트 하드코딩 금지 조건을 넣었다.
```

## 마무리

Claude의 thinking, effort, tool use는 모델 성능 문제가 아니라 운영 설계 문제입니다. 어떤 작업에 깊은 추론을 쓸지, 언제 도구를 사용할지, 어떤 행동을 금지할지 정하지 않으면 비용과 리스크가 함께 커집니다.

다음 글에서는 바로 복사해서 쓸 수 있는 프롬프트 템플릿과 체크리스트를 정리합니다. 분석, 코드 리뷰, 문서 요약, 프론트엔드 생성, 에이전트 코딩 작업을 반복 가능한 형태로 만들기 위한 실전 템플릿입니다.

## 참고자료

- Models overview: https://platform.claude.com/docs/en/about-claude/models/overview
- Building with extended thinking: https://platform.claude.com/docs/en/build-with-claude/extended-thinking
- Tool use with Claude: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview
- Claude Prompting Best Practices: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices