Claude Code Execution 도구 운영법: REPL 상태와 90초 제한을 안전하게 다루기

요약: Anthropic은 2026년 6월 Claude API의 code execution tool 관련 업데이트를 공개했습니다. SDK들이 code_execution_20260120을 지원하고, 이후 code_execution_20260521은 셀당 90초 실행 제한을 도구 설명에 명시해 Claude가 긴 작업을 더 잘 예산화할 수 있게 했습니다. 개발자에게 중요한 포인트는 “코드를 실행할 수 있다”가 아니라, 실행 상태·시간 제한·재현성을 어떻게 통제하느냐입니다.

AI 에이전트에 코드 실행 도구를 붙이면 할 수 있는 일이 크게 늘어납니다. CSV 분석, 로그 파싱, 간단한 시뮬레이션, 테스트 데이터 생성, 그래프 계산, 정규식 검증 등을 모델이 직접 처리할 수 있습니다. 반대로 운영 리스크도 늘어납니다. 오래 걸리는 코드, 상태가 남은 REPL, 재현되지 않는 결과, 외부 네트워크 접근, 파일 출력 관리가 모두 문제가 됩니다.

code execution tool 업데이트의 핵심

공식 release notes 기준으로 code_execution_20260120은 REPL state persistence와 programmatic tool calling의 최소 버전으로 설명됩니다. SDK 지원 언어는 Python, TypeScript, Go, Java, Ruby, PHP, C# 등입니다. 이후 code_execution_20260521은 셀당 90초 실행 제한을 도구 설명에 노출해 Claude가 긴 작업을 계획할 때 제한을 고려할 수 있게 했습니다.

이 말은 모델이 “무한히 오래 걸리는 분석”을 마음대로 실행하는 구조가 아니라는 뜻입니다. 각 셀은 시간 제한을 갖고, 상태는 이어질 수 있으며, 도구 호출 방식은 코드로 제어할 수 있습니다.

실무에서는 이 세 가지가 중요합니다.

• 상태 지속: 이전 셀의 변수와 파일이 다음 셀에 영향을 줄 수 있다.
• 시간 제한: 90초를 넘는 작업은 분할하거나 샘플링해야 한다.
• 도구 호출 제어: 어떤 상황에서 코드 실행을 허용할지 애플리케이션이 결정해야 한다.

REPL 상태 지속의 장점과 위험

REPL 상태가 유지되면 사용성이 좋아집니다. 첫 번째 셀에서 데이터를 로드하고, 두 번째 셀에서 전처리하고, 세 번째 셀에서 분석하는 흐름이 가능합니다. 매번 파일을 다시 읽거나 라이브러리를 다시 import할 필요가 없습니다.

하지만 상태 지속은 디버깅을 어렵게 만들기도 합니다. 이전 셀에서 만든 df가 남아 있는데 사용자가 새 파일을 올렸고, 모델이 예전 변수와 새 변수를 섞어 쓰면 결과가 틀릴 수 있습니다. 노트북을 오래 쓰다 보면 “위에서부터 다시 실행하면 깨지는” 문제가 생기는 것과 같습니다.

그래서 운영 앱에서는 상태 정책을 정해야 합니다.

• 한 사용자 세션 안에서는 상태를 유지한다.
• 파일이 바뀌면 관련 변수는 폐기한다.
• 분석 결과를 저장할 때는 실행 셀과 입력 파일 해시를 함께 기록한다.
• 중요한 계산은 최종 단계에서 clean run으로 재실행한다.
• 장기 세션은 일정 시간 후 새 sandbox로 시작한다.

이 정책이 없으면 모델은 편하게 분석하지만 사용자는 같은 결과를 재현할 수 없습니다.

90초 제한을 기준으로 작업을 쪼개는 법

셀당 90초 제한은 작은 분석에는 충분하지만, 큰 CSV, 이미지 처리, 웹 크롤링, 대규모 시뮬레이션에는 짧을 수 있습니다. 제한을 우회하려고 한 셀에 모든 작업을 넣는 방식은 실패 확률만 높입니다.

좋은 패턴은 작업을 단계별로 나누는 것입니다.

1. 입력 크기 확인: 행 수, 컬럼 수, 파일 크기, 결측치 비율
2. 샘플 분석: 1,000~10,000행으로 로직 검증
3. 전체 처리 계획 수립: chunk size, 필요한 컬럼, 출력 형식 결정
4. chunk 실행: 제한 시간 안에 끝나는 단위로 나눔
5. 중간 결과 저장: 각 chunk 결과를 파일로 저장
6. 최종 집계: 저장된 중간 결과를 합침

모델에게도 이 원칙을 system prompt나 tool instruction에 알려주는 것이 좋습니다. “90초를 넘길 가능성이 있으면 먼저 샘플로 검증하고, 전체 실행은 chunk로 나누라”는 식입니다.

programmatic tool calling을 어디에 써야 하나

코드 실행을 모델에게 완전히 맡기면 편하지만, 제품에서는 위험합니다. programmatic tool calling은 애플리케이션이 도구 호출을 더 명시적으로 제어할 수 있게 해주는 방향입니다.

예를 들어 다음 상황에서는 코드 실행을 허용할 수 있습니다.

• 사용자가 CSV, JSON, 로그 파일을 업로드했다.
• 답변에 계산이나 집계가 필요하다.
• 정규식, SQL, 파싱 로직을 검증해야 한다.
• 사용자가 “실행해서 확인해줘”라고 명시했다.

반대로 다음 상황에서는 막거나 확인을 받아야 합니다.

• 외부 네트워크 접근이 필요한 코드
• 대량 파일 생성
• 민감한 파일 경로 접근
• 무한 루프 가능성이 있는 코드
• 사용자가 의도하지 않은 데이터 변환

AI 분석 기능에서 가장 위험한 것은 “모델이 알아서 해줬다”입니다. 도구 실행은 사용자 의도와 제품 권한 모델 안에 있어야 합니다.

결과 신뢰도를 높이는 출력 형식

코드 실행 결과를 그냥 자연어로 요약하면 검증이 어렵습니다. 최소한 아래 항목을 함께 보여주는 것이 좋습니다.

• 사용한 입력 파일명과 해시 또는 업로드 id
• 실행한 주요 코드 단계 요약
• 샘플 크기와 전체 크기
• 제외한 행 또는 에러 건수
• 생성된 파일 목록
• 재현 가능한 코드 또는 notebook export
• 한계와 가정

예를 들어 매출 CSV를 분석했다면 “총 매출은 1.2억입니다”보다 “업로드 파일 A의 42,118행 중 결측 12행을 제외하고 집계했으며, 날짜 컬럼은 KST 기준으로 파싱했습니다”가 훨씬 낫습니다.

보안 기본값

코드 실행 도구는 sandbox가 있더라도 보안 기본값을 보수적으로 잡아야 합니다.

• 네트워크 접근은 기본 차단, 필요한 도메인만 allowlist
• 파일 시스템은 세션별 임시 디렉터리로 제한
• secret 환경변수는 기본 미주입
• 출력 파일 크기 제한
• 실행 시간과 메모리 제한
• 사용자가 업로드한 파일은 바이러스/형식 검사 후 전달
• 로그에는 원본 민감 데이터 대신 참조 id 저장

특히 데이터 분석 SaaS에서는 사용자가 업로드한 파일에 개인정보가 들어갈 수 있습니다. 모델이 생성한 코드와 출력 결과가 로그에 과도하게 남지 않도록 주의해야 합니다.

실행 체크리스트

• code_execution_20260120 이상을 기준으로 SDK와 tool type을 맞춘다.
• 90초 제한을 전제로 샘플 실행, chunk 실행, 최종 집계 흐름을 prompt에 명시한다.
• REPL 상태 유지 범위와 초기화 조건을 문서화한다.
• 파일이 바뀌면 이전 변수와 캐시를 폐기하는 규칙을 둔다.
• 중요한 결과는 clean run으로 재실행해 재현성을 확인한다.
• 코드 실행 허용 조건과 차단 조건을 제품 권한 모델에 넣는다.
• 출력에는 입력 파일, 처리 행 수, 제외 건수, 가정을 함께 표시한다.
• 네트워크, 파일 크기, 실행 시간, secret 주입을 기본 제한한다.

Claude code execution tool은 에이전트에 계산 능력을 붙이는 강력한 기능입니다. 하지만 운영 품질은 모델이 아니라 실행 정책에서 갈립니다. REPL 상태를 어떻게 초기화할지, 90초 제한을 어떻게 쪼갤지, 결과를 어떻게 재현할지부터 정해두면 코드 실행은 위험한 마술이 아니라 믿을 수 있는 분석 도구가 됩니다.