Claude Code가 "파일을 고쳐줘"라는 요청을 받으면 어떻게 처리할까요? 텍스트를 출력하는 것이 아니라 실제로 파일을 열어 수정합니다. 이 과정이 Tool Use입니다.
Claude Code가 외부 세계와 상호작용하는 방법입니다. 언어 모델은 텍스트만 처리할 수 있지만, 도구를 통해 파일 시스템, 셸, 웹 등에 접근합니다.
사용자 요청 → Claude 판단 → 도구 호출 → 결과 수신 → 다음 판단 → ...
Claude Code는 목표를 달성하기 위해 필요한 도구를 순서대로 선택하고 호출합니다.
Read("src/user/user.service.ts")
→ 파일 내용 반환
코드를 수정하기 전에 현재 상태를 파악합니다.
Edit("src/user/user.service.ts", old_string="...", new_string="...")
→ 정확한 문자열 교체
특정 문자열을 찾아 새 내용으로 교체합니다. 전체 파일을 덮어쓰지 않고 변경 부분만 수정합니다.
Write("src/user/user.dto.ts", content="...")
→ 새 파일 생성
Bash("npm test")
→ 테스트 실행 결과 반환
Bash("git log --oneline -5")
→ 최근 커밋 목록 반환
빌드, 테스트, Git 작업 등 모든 셸 명령을 실행할 수 있습니다.
Glob("src/**/*.service.ts")
→ 매칭되는 파일 목록 반환
Grep("UserService", type="ts")
→ UserService가 언급된 파일과 위치 반환
Claude Code는 목표를 달성할 때까지 도구를 반복 호출합니다.
1. 사용자: "getUserById 함수에 캐시 추가해줘"
2. Glob("**/*.service.ts") → service 파일 목록 파악
3. Grep("getUserById") → 함수 위치 찾기
4. Read("user.service.ts") → 현재 코드 확인
5. Read("user.module.ts") → Redis 설정 확인
6. Edit("user.service.ts") → 캐시 로직 추가
7. Bash("npm test user") → 테스트 실행
8. 테스트 통과 → 완료
각 단계에서 이전 도구 호출 결과를 바탕으로 다음 행동을 결정합니다. 중간에 오류가 나면 원인을 파악해 수정합니다.
에이전트 루프(Agent Loop): 에이전트가 목표 달성까지 도구 호출을 반복하는 사이클. Plan → Act → Observe → Plan 과정이 반복됩니다.
내부적으로 Claude는 도구 호출을 구조화된 형태로 요청하고 결과를 받습니다.
// Tool Call
{
"tool": "Bash",
"input": { "command": "npm test" }
}
// Tool Result
{
"output": "✓ 15 tests passed\n✗ 2 tests failed\n..."
}
이 결과가 다시 Claude의 컨텍스트로 들어가 다음 판단에 활용됩니다.
위험할 수 있는 작업은 실행 전에 사용자에게 확인을 요청합니다.
Claude: npm run migration:run 을 실행하려 합니다.
계속 진행할까요? [Y/n]
파일 삭제, 프로덕션 관련 명령, 외부 서비스 호출 등이 해당됩니다. 권한 설정에 따라 자동 허용 범위를 조정할 수 있습니다.
Tool Use 없이는 Claude Code가 텍스트를 출력하는 것 이상을 할 수 없습니다. Tool Use가 있기 때문에 실제 파일을 수정하고, 테스트를 돌리고, 커밋을 만들고, 오류를 직접 확인하고 수정하는 전체 개발 워크플로를 자율적으로 수행할 수 있습니다.
Claude Code의 모든 기능은 결국 Tool Use 위에 구축되어 있습니다.