목차
Claude 가이드 - 이 글은 시리즈의 일부입니다.
이 글은 Claude API 공식 문서의 Code execution tool 페이지를 정리한 글입니다. 원문: https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool 마지막 확인: 2026-05-23
1. 한 줄 요약 #
Claude에게 “직접 계산해보고 그래프도 그려본 다음 알려줘"라고 부탁할 수 있는, 안전한 작은 컴퓨터 한 대를 빌려주는 기능입니다.
2. 무엇이고 왜 좋을까 #
비유 한 줄: 옆자리에 작은 계산기와 노트북을 놓아두고, Claude가 필요할 때마다 그걸 두드려보고 답을 가져오게 하는 것과 같습니다.
지금까지의 Claude는 머릿속에서만 답을 짜냈습니다. 그런데 “이 엑셀 파일의 평균을 알려주세요” 같은 질문은, 실제로 숫자를 더해보고 나눠봐야 정확해집니다. 코드 실행(Code Execution) 도구는 Claude에게 샌드박스(sandbox, 외부와 단절된 안전한 실험 공간) 하나를 빌려주고, 그 안에서 파이썬 코드와 간단한 명령어를 직접 돌려본 뒤 결과를 가져오게 합니다.
핵심 수치는 이렇습니다 — 모든 조직(가입한 계정 단위)에 매달 1,550시간이 무료로 주어집니다. 하루에 50시간 가까이 쓸 수 있는 양이라, 입문자가 이 한도를 넘기는 일은 거의 없습니다.
3. 이런 상황에서 써요 #
상황 1: 강의 노트 정리하고 싶은 학생 #
“이번 학기 시험 점수를 엑셀로 정리해뒀는데, 과목별 평균이랑 표준편차를 한눈에 보고 싶어요. 그리고 막대그래프로도 좀…”
원래라면 엑셀 함수를 찾아서 입력하고, 차트를 그리고, 캡처해서 노트에 붙여야 했죠. 이제 엑셀 파일을 올린 뒤 “과목별 평균과 표준편차를 계산하고, 막대그래프 한 장 만들어주세요"라고 한국어로 부탁하면 Claude가 작업실 안에서 직접 계산하고 그림 파일까지 만들어 돌려줍니다.
상황 2: 회사 보고서를 정리해야 하는 직장인 #
“부서별 매출 자료가 CSV(Comma-Separated Values, 쉼표로 구분된 표 파일) 형식인데요. 이번 달 매출이 작년 같은 달과 얼마나 차이 나는지 비교표 하나만 뽑아주면 좋겠어요.”
회사에 들어온 지 얼마 안 됐는데 파이썬 같은 건 배운 적 없다면 막막한 일입니다. 코드 실행 도구를 켜두면, Claude가 직접 표를 읽고 비교 계산을 한 뒤 “작년 5월 대비 12% 증가했습니다” 같은 답과 함께 정리된 표를 만들어 보내줍니다. 사용자는 결과만 확인하면 됩니다.
상황 3: 책 한 권을 정리하려는 일반 독자 #
“PDF로 받은 200쪽짜리 자기계발서를 한 번에 다 읽기는 부담스러워요. 챕터별로 핵심 문장 세 개씩, 그리고 단어 등장 빈도가 가장 높은 키워드 20개를 정리해줄 수 있을까요?”
이런 작업은 단순한 요약을 넘어 “글자를 세고, 통계를 내는” 일이 섞여 있습니다. 코드 실행 도구가 있으면 Claude가 PDF를 직접 펼쳐 문장을 세고, 빈도 표를 만든 뒤, 보기 좋은 형태로 정리해서 돌려줍니다. 독서 노트가 한결 풍성해집니다.
4. 가볍게 시작하기 #
💻 개발 경험이 있으신가요? 아래 코드는 파이썬 기준 가장 짧은 예시입니다. 비개발자라면 “아, 이런 식으로 한 줄만 끼워 넣으면 켜지는구나” 정도로 보고 넘어가셔도 충분합니다.
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=4096,
messages=[{
"role": "user",
"content": "1부터 100까지 숫자 중 짝수의 합과 평균을 계산해주세요."
}],
# ↓ 이 한 줄이 Claude에게 '작업실'을 빌려주는 부분
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)위 코드는 정말 단순합니다. tools=[...] 한 줄을 추가해주면, Claude는 머릿속으로만 답하지 않고 실제로 파이썬을 한 번 돌려본 뒤 답을 가져옵니다. 답변에는 “짝수의 합은 2550, 평균은 51"처럼 검증된 숫자가 담겨 돌아옵니다. 어떤 도구가 필요한지는 Claude가 알아서 판단하니, 사용자는 “코드 실행이 가능하다"는 사실만 알려주면 충분합니다.
5. 흔한 오해와 함정 #
⚠️ 함정 1: “그럼 인터넷에 접속해서 자료도 가져오게 할 수 있겠네요?” #
아쉽지만 아닙니다. 안전을 위해 이 작업실은 외부 인터넷이 완전히 차단되어 있습니다. 사이트 주소를 알려주고 “여기 내용 가져와줘"라고 부탁해도 가져오지 못합니다. 인터넷 자료가 필요하면 웹 검색 도구나 웹 가져오기 도구(다음 시리즈에서 다룹니다)를 함께 켜주셔야 합니다. 좋은 소식 하나 — 이 두 도구를 함께 쓰면 코드 실행은 무료입니다.
⚠️ 함정 2: “엑셀 파일을 그냥 메시지에 첨부하면 되겠죠?” #
❌ 채팅창에 파일을 끌어다 놓는 식으로는 안 됩니다.
✅ 먼저 Files API(파일 업로드 전용 통로)에 파일을 올리고, 그 파일의 ID를 메시지에 끼워 넣어 줘야 작업실 안에서 열어볼 수 있습니다. 이때 베타 헤더 "anthropic-beta": "files-api-2025-04-14" 한 줄이 필요한데, 입문자 입장에서는 “특별 출입증 한 장 같이 보내야 한다"고만 기억해두시면 됩니다.
⚠️ 함정 3: “어제 만든 결과 파일이 오늘도 작업실에 그대로 있겠죠?” #
작업실(컨테이너)은 30일이 지나면 자동으로 정리됩니다. 그 전이라도 새 대화를 시작하면 보통 새 작업실이 열려서, 어제 만든 파일은 그 안에 없습니다. 결과를 두고두고 쓰고 싶다면 Claude가 만든 파일을 내려받아 본인 컴퓨터에 저장해두는 습관을 들이세요. 같은 작업실을 이어서 쓰고 싶다면 응답에 들어 있는 container_id를 다음 요청에 다시 넣어주면 됩니다.
6. 한 단계 더 (관심 있는 분만) #
🎯 여기까지 오신 분 환영합니다. 이 섹션은 본인이 가지고 있는 파일을 직접 분석시켜보고 싶은 분을 위한 보너스입니다. 본문만 읽으셔도 충분합니다.
본인의 CSV 파일을 올려서 분석시키는 방법은 두 단계입니다 — 먼저 파일을 올리고, 그 다음 그 파일을 가리키며 질문하는 거죠.
import anthropic
client = anthropic.Anthropic()
# 1단계: 분석할 CSV 파일을 먼저 업로드
file_object = client.beta.files.upload(
file=open("매출.csv", "rb"),
)
# 2단계: 업로드한 파일을 가리키며 질문하기
response = client.beta.messages.create(
model="claude-opus-4-7",
betas=["files-api-2025-04-14"], # 파일 기능 출입증
max_tokens=4096,
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "이 표에서 매출 1위 부서와 그 비결을 분석해주세요"},
{"type": "container_upload", "file_id": file_object.id}, # 파일 가리키기
],
}],
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
print(response)작업실 안에는 pandas(표 다루기), matplotlib(그래프 그리기), openpyxl(엑셀 읽기) 같은 도구가 이미 설치되어 있어서, 추가 설정 없이 바로 분석이 가능합니다. CSV, 엑셀, PDF, 이미지, 텍스트 파일 모두 받아들입니다.
비용 감 잡기: 무료 1,550시간을 넘는다면 컨테이너 1개당 1시간에 0.05달러(약 70원)가 청구됩니다. 보통 한 번 질문하고 답을 받는 데 몇 분이면 끝나니까, 가벼운 분석으로는 몇 십 원도 안 나오는 셈입니다. 다만 파일을 첨부한 요청은 작업실이 곧장 켜지므로 실제로 분석을 안 시켜도 시간이 흐른다는 점은 살짝 기억해두세요.
7. 한 마디 #
처음 보면 “샌드박스, 컨테이너, Files API… 단어가 많네"라고 느끼실 수 있습니다. 하지만 사용자가 하는 일은 결국 두 가지뿐이에요 — 도구 한 줄 켜기, 그리고 필요하면 파일 한 번 올리기. Claude가 직접 숫자를 더해보고 그림을 그려본 뒤 답을 들고 오기 때문에, 어림짐작이 줄고 답이 한층 단단해집니다.
만약 잘 안 되는 것 같다면 위의 함정 1~3 중 하나일 가능성이 큽니다 — 인터넷이 필요한데 안 켜져 있거나, 파일을 메시지에 그냥 붙여서 못 읽거나, 작업실이 새로 열려 어제 파일이 없거나. 천천히 한 번 확인해보세요.
다음 글에서는 #14 — 웹 검색 도구를 다룹니다. 오늘의 작업실에 “인터넷 연결선"까지 더해지면, Claude는 자료를 찾아와 그 자리에서 정리·분석까지 한 번에 해주는 든든한 친구가 됩니다.
Claude API 공식 문서를 한국어로 풀어쓴 시리즈입니다. 원문 정확성이 가장 우선, 의역과 친근함은 그 위에서.
