클로드 코드의 툴 API 상세 정보 공개

Claude Code의 도구 API 구조

레딧 사용자가 Claude Code와의 내부 도구 API에 대한 대화를 기록했습니다. AI 어시스턴트는 환경과 상호작용하는 구체적인 방식을 공개했습니다.

도구 카테고리 및 기능

파일 시스템 도구:

• Read — 절대 경로로 파일을 읽고, 줄 번호와 함께 내용을 반환합니다 (cat -n 스타일). 이미지, PDF, Jupyter 노트북을 지원합니다.
• Write — 파일을 덮어쓰거나 생성합니다. 기존 파일에 쓰기 전에 먼저 Read를 해야 합니다.
• Edit — 정밀한 문자열 교체를 수행합니다. old_string이 파일 내에서 고유해야 하며, 그렇지 않으면 실패합니다. 먼저 Read를 해야 합니다.
• Glob — 패턴(예: *.py)으로 파일을 찾습니다. 수정 시간순으로 정렬됩니다.
• Grep — ripgrep 기반의 내용 검색입니다. 정규식, 파일 유형 필터, 컨텍스트 라인을 지원합니다.

실행 도구:

• Bash — 기본 2분(최대 10분) 타임아웃으로 셸 명령어를 실행합니다. 작업 디렉터리는 호출 간에 유지되지만, 셸 상태는 이어지지 않습니다(환경 변수, 별칭 등 없음). run_in_background 옵션이 있습니다.

웹 도구:

• WebFetch — URL 콘텐츠를 가져옵니다.
• WebSearch — 웹을 검색합니다.

AI 에이전트:

• Agent — 자체 도구 접근 권한과 컨텍스트를 가진 하위 에이전트(범용, Explore, Plan 등)를 생성합니다. 백그라운드에서 실행할 수 있습니다. 완료 시 단일 메시지를 반환합니다.

특수 도구:

• Skill — 명명된 "스킬"(/commit과 같은 슬래시 명령어)을 호출하여 전체 프롬프트로 확장합니다.
• ToolSearch — "지연된 도구"(이름으로는 알지만 스키마를 가져올 때까지 호출할 수 없는 도구)의 스키마를 가져옵니다.

주요 구현 세부 사항

도구 호출 구조: Claude Code는 도구를 트리거하기 위해 특수 토큰을 사용하지 않습니다 — 표준 함수 호출 API입니다. 응답에는 구조화된 도구 호출 블록이 포함되며, 결과는 도구 결과 메시지로 돌아옵니다.

도구 호출 형식: 블록은 antml:function_calls 래퍼를 포함한 XML과 유사한 구문을 사용하며, 하나 이상의 antml:invoke 요소가 도구 이름을 속성으로 가집니다. 각 매개변수는 antml:parameter 요소로, name 속성과 값이 텍스트 콘텐츠로 들어 있습니다.

Bash 호출의 예시 구조:

• 외부 태그: antml:function_calls
• 내부 태그: antml:invoke with attribute name="Bash"
• 매개변수 태그: antml:parameter with name="command" containing the command text

운영 동작

• 린터 상호작용: 파일을 편집할 때, git 훅이나 구성된 "훅"이 도구 호출 후 자동으로 실행되어 파일을 추가로 수정할 수 있습니다. 도구 결과는 "파일이 다른 프로세스에 의해 수정됨"을 나타내며, 다시 편집하기 전에 재읽기가 필요합니다.
• 도구 호출 가시성: 모든 도구 호출은 사용자 승인을 위해 터미널에 표시됩니다(권한 모드에 따라 다름). 사용자는 어떤 도구 호출이든 거부할 수 있습니다.
• 병렬 실행: 여러 도구 호출이 단일 응답에서 발행되어 동시에 실행될 수 있으며, 여러 파일을 한 번에 읽는 데 유용합니다.
• 컨텍스트 관리: 긴 대화는 자동으로 압축됩니다 — 이전 메시지는 요약되어 컨텍스트를 확보합니다. 메모리 지속성은 디렉터리 구조를 통해 이루어집니다: /home/tpreal/.claude/projects/...