에이전트에 도구 하나를 붙일 때 무엇부터 적어야 하나? 함수의 입력과 출력은 정했는데 언제 호출되고 무엇을 바꿀지까지 설명하려면 막막할 수 있다. 설계자가 먼저 적을 것은 입력 형식뿐 아니라 사용 조건, 권한 판단, 실행 결과, 사용자에게 보일 상태다. 이 글은 그 질문들을 여섯 가지 계약으로 묶어 새 도구를 점검하는 기준으로 삼는다.

Claude Code의 공개 훅 문서에는 Bash 호출의 입력 필드와 권한 판정 값이 나와 있다. 이 글은 그 문서를 직접 확인하고, 소스 스냅샷의 BashTool 파일 구성을 세어 여섯 계약에 대응해 본다. 여섯 묶음은 필자가 정한 편집 기준이며, Claude Code의 비공개 내부 구현을 해부한 글은 아니다. 공식 문서에 적힌 사양과 새 도구를 설계할 때의 판단을 나누어 읽으면 된다.

도구는 함수가 아니다

에이전트 하니스(agent harness)는 AI가 도구를 골라 실행하는 실행 틀이다. 도구 하나를 설계할 때 적을 항목을 세면 이름, 입력 스키마, 프롬프트 설명, 권한 판단, 실행, 정규화된 결과, 진행과 결과 UI, 기능 게이트의 8가지가 나온다. 이 글은 이름을 스키마에, 정규화된 결과를 실행에 포함해 여섯 계약으로 묶었다. 여섯이라는 개수는 필자의 편집 기준이며, 이 칸들을 채웠다는 사실만으로 도구의 안전성이 입증되는 것은 아니다.

도구 하나를 설계할 때 적는 여섯 계약을 두 줄 세 칸으로 나눈 그림이다. 윗줄은 이름과 입력 스키마, 프롬프트 설명, 권한 판단이고 아랫줄은 실행과 정규화된 결과, 진행과 결과 UI, 기능 게이트이다. 권한 판단 칸이 강조되어 있으며, 권한이 실행을 허용해도 입력의 의미와 실제 변경, 결과 표시까지 보장하지는 않는다는 점을 보여 준다.
각 칸에 무엇을 맡겼는지 적어 두면 빠진 검증 책임을 검토할 수 있다.

권한 계약은 실행 전에 허용·거부·확인이 필요한지를 가르는 자리다. 권한 판정이라는 주제는 Claude Code의 allow·deny·ask 권한 게이트에서 별도로 다룬다. 여기서는 권한과 다른 계약의 경계를 본다. 권한이 실행을 허용하더라도 입력의 의미, 실제 변경, 결과 표시까지 대신 보장하지는 않는다.

각 계약이 약할 때의 위험도 구분해 볼 수 있다. 스키마가 입력 형태를 충분히 제한하지 않으면 기본 검증을 실행부가 더 맡아야 할 수 있다. 애매한 프롬프트는 과잉·과소 호출을 유도할 수 있고, UI에 실행 정보가 부족하면 사용자가 결과를 해석하기 어려울 수 있다. 기능 게이트가 없다면 현재 환경에서 쓸 수 없는 도구가 목록에 남을 수 있다.

파일 삭제 도구를 설계하는 가상의 예를 보자. 스키마는 경로 문자열을 필수값으로 받도록 정하되, 실제 경로의 존재·권한·프로젝트 경계는 실행 직전 별도로 확인하도록 한다. 프롬프트에는 도구를 쓸 조건을 적고, 권한 계약에는 삭제 전에 필요한 확인을 정한다. 실행부는 삭제 결과를 확인하고, UI는 변경된 파일 목록을 남기며, 기능 게이트는 읽기 전용 환경에서 도구를 노출할지 판단한다.

이 예시의 목적은 여섯 칸이 안전을 보장한다고 주장하는 데 있지 않다. 입력 형식으로 해결할 문제와 실행 직전에 확인할 문제를 구분하는 데 있다. 각 칸에 무엇을 맡겼는지 적어 두면 빠진 검증 책임을 검토할 수 있다.

Bash로 확인하는 Claude Code의 공개 계약

Claude Code 훅 문서(조회 2026-10-30)는 PreToolUse 훅이 Bash 호출에서 받는 tool_input 필드를 command, description, timeout, run_in_background 4개로 든다. 이 중 command는 실행할 문자열이고, timeout은 밀리초 단위다. 이 네 필드가 스키마 계약을 확인할 수 있는 공개 지점이다.

같은 필드를 소스 스냅샷의 BashTool.tsx.md에서 보면 다르다. 입력 정의 fullInputSchema(z.strictObject)에는 6개가 있다. command, timeout, description, run_in_background, dangerouslyDisableSandbox, 그리고 내부용 _simulatedSedEdit이다. 모델에 노출되는 inputSchema는 _simulatedSedEdit을 뺀 5개이고, 환경 변수 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS가 참이면 run_in_background도 빼서 4개가 된다(258–294행). 두 자료가 가리키는 범위가 같은지는 이번 점검에서 확인하지 못했으므로, 샌드박스 관련 필드를 다룰 때는 확인한 버전을 함께 적어야 한다.

훅 문서는 PreToolUse 훅의 permissionDecision에 들어갈 값을 4가지로 든다. 각 값의 의미는 아래 표와 같다.

값의미
allow허용
deny거부
ask사용자에게 확인을 요청
defer턴을 끝내고 도구를 나중에 재개할 수 있게 한다. claude -p로 돌리는 비대화형 실행에서만 동작하며, 대화형 세션에서는 경고 후 무시된다

문서는 updatedInput이 입력 객체 전체를 교체한다고 설명한다. 그래서 수정한 필드뿐 아니라 그대로 둘 필드도 함께 넘겨야 한다. 권한 판정과 입력 수정이 한 훅에서 함께 발생하는 만큼, 이 두 계약은 따로 점검하는 편이 낫다.

스냅샷에서 BashTool 디렉터리를 세면 다음과 같다. 스냅샷은 원본을 .md 파일로 옮긴 사본이므로 파일 이름은 원본과 조금 다를 수 있다.

# 작업 디렉터리: 스냅샷의 src/tools
$ ls BashTool | wc -l
19
# 작업 디렉터리: 스냅샷 루트(src의 상위)
$ find src/tools -mindepth 1 -maxdepth 1 -type d | wc -l
42

파일 이름만으로 여섯 계약에 대응시키면 아래와 같다. 파일 이름에 근거한 대응은 추정이며, 파일 내용을 읽어 확인한 것은 스키마 정의뿐이다.

계약스냅샷의 파일(이름 기준)확인 수준
스키마BashTool.tsx.md입력 스키마 정의를 직접 확인(258–294행)
프롬프트prompt.ts.md파일 이름만 확인
권한bashPermissions.ts.md, readOnlyValidation.ts.md, modeValidation.ts.md, pathValidation.ts.md파일 이름만 확인
실행shouldUseSandbox.ts.md, destructiveCommandWarning.ts.md파일 이름만 확인
UI·로그UI.tsx.md, BashToolResultMessage.tsx.md파일 이름만 확인
기능 게이트BashTool.tsx.md(258–260행, 288–292행)환경 변수 조건을 직접 확인

스키마와 프롬프트: 입력을 가두고 언제 쓸지 알려준다

입력 스키마(schema)는 모델이 채워 넣을 값의 형태를 정하는 규격이다. 필드 이름, 타입, 필수 여부, 허용 범위를 여기에 적는다. 경로 필드에 문자열을 받는다는 선언만으로 실제 경로의 존재나 프로젝트 경계까지 보장되지는 않는다. 형식 검증과 실행 직전의 의미 검증을 나누어 설계할 필요가 있다.

두 열로 나눈 비교 그림이다. 왼쪽 열 입력 스키마는 필드 이름과 타입, 필수 여부, 허용 범위처럼 모델이 채울 값의 형식을 정한다. 오른쪽 열 실행 직전 검증은 경로가 실제로 존재하는지와 프로젝트 경계 안에 있는지처럼 의미를 확인하며, 경로 필드에 문자열을 받는다는 선언만으로는 이를 보장하지 못한다.
형식 검증과 실행 직전의 의미 검증은 역할이 달라 나누어 설계해야 한다.

프롬프트와 도구 설명에는 언제 이 도구를 쓰는지, 비슷한 도구와 어떻게 구분하는지, 어떤 입력이 적절한지를 적는다. 설명이 부족하거나 애매하면 도구의 오용이나 과잉·과소 호출을 유도할 수 있다. 이는 관측된 실패 결과가 아니라 설명을 검토할 때 확인할 위험이다. 스냅샷에서도 BashTool의 프롬프트는 prompt.ts.md로 입력 스키마와 다른 파일에 있다. 파일 이름만 본 구조이지만, 설명을 스키마와 따로 관리한다는 점은 같다.

두 계약은 함께 읽어야 한다. 스키마는 입력의 형식을 정하고 프롬프트는 그 입력을 언제 채울지 안내한다. 형식이 정확해도 사용 시점이 맞지 않을 수 있고, 사용 목적이 맞아도 입력이 잘못될 수 있다. 설계 검토에서는 두 질문을 따로 확인하는 편이 낫다.

실행: 부작용과 결과를 가른다

셸과 파일 도구는 명령 해석, 경로 처리, 격리 판단, 파괴적 작업의 경고, 출력 수집, 변경 내용 표시가 함께 얽힌다. 명령을 전달하는 함수만 적어서는 이 책임들이 어디에 있는지 드러나지 않는다. 도구 설계에는 실행 전 확인과 실행 후 결과 처리까지 포함해야 한다.

스냅샷의 BashTool 파일 이름에도 이 책임이 나뉘어 있다. pathValidation.ts.md, shouldUseSandbox.ts.md, destructiveCommandWarning.ts.md가 그 예다. 이름으로 보면 실행 책임이 한 함수에 모여 있지 않다. 어느 파일이 어떤 판정을 실제로 내리는지는 파일 내용을 읽어야 한다.

부작용은 파일 변경이나 명령 실행처럼 실제 상태가 바뀌는 일이다. 결과는 그 상태 변화를 모델과 사용자에게 전달하는 값이다. 둘을 구분하지 않고 실행이 끝나기 전에 성공 결과를 만들면, 실제 작업은 실패했는데 성공으로 표시되는 어긋남이 생길 수 있다. 결과를 만들 때는 무엇이 실행됐고 무엇이 확인됐는지를 구분해야 한다.

도구가 하려던 일과 실제로 확인된 결과를 구분해 전달한다.

앞서 든 삭제 도구에서도 같은 위험을 생각해 볼 수 있다. 삭제 명령을 내리자마자 성공 메시지를 만들었는데 실제 삭제는 권한 문제로 막혔다면, 사용자는 잘못된 결과를 전달받게 된다. 이 가상 상황에서는 삭제 결과를 확인한 뒤 응답을 만드는 순서가 필요하다. 실행 요청을 보냈다는 사실을 작업 완료와 같은 뜻으로 쓰지 않는 것이다.

검색·조회 도구는 결과를 모델에 넘길 때 범위를 제한해야 한다. 방대한 결과를 그대로 넘기면 맥락을 낭비하므로, 검색이 실행됐는지뿐 아니라 어떤 결과를 남기고 어떤 범위에서 잘랐는지도 정해야 한다.

에이전트나 하위 작업을 부르는 도구는 위임한 작업의 생애주기를 다룬다. 이 글은 시작, 진행, 완료 상태를 나누어 보는 것을 기준으로 삼는다. 작업을 시작한 응답과 완료한 응답이 구분되지 않으면 사용자가 아직 진행 중인 작업을 끝난 것으로 오해할 수 있다.

UI·로그와 기능 게이트: 보이는 것과 되는 것을 맞춘다

UI·로그 계약에는 사용자가 진행과 결과를 어떻게 구분할지 적는다. 실행한 명령, 변경된 경로, 실패 이유 같은 정보가 빠지면 승인이나 디버깅 판단이 어려울 수 있다. 스냅샷에는 UI 표시를 맡는 것으로 보이는 UI.tsx.md와 BashToolResultMessage.tsx.md가 있다. 이름만 확인했으므로 어떤 정보를 실제로 보여 주는지는 파일을 열어 확인해야 한다.

위임한 작업의 상태를 보여줄 때도 같은 기준을 적용할 수 있다. 시작 응답만으로 완료처럼 보이지 않도록 진행 상태와 최종 결과를 구분한다. 이 구분은 실행 계약에서 정한 상태를 UI가 어떻게 표현할지 연결하는 질문이다.

기능 게이트(feature gate)는 현재 환경에서 기능을 제공할 수 있는지 판단하는 장치다. 이 글의 체크리스트로는 연결되지 않은 통합이나 지원되지 않는 기능을 도구 목록에 노출할지 확인한다. 쓸 수 없는 도구가 목록에 남으면 모델이 호출을 시도했다가 실패할 수 있다. 스냅샷의 BashTool.tsx.md에는 기능 게이트가 있다. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS 환경 변수가 모듈 로드 시점에 참이면 run_in_background 필드를 스키마에서 뺀다(258–260행, 288–292행). 이 게이트는 입력 필드 단위에서 작동한다. 도구 자체를 목록에 노출할지는 이 점검에서 확인하지 못했다.

삭제 도구의 UI에는 무엇이 지워졌는지 확인할 수 있는 결과를 남기도록 설계할 수 있다. 읽기 전용 환경에서는 기능 게이트가 도구 노출을 제한하도록 정할 수 있다. 실행 시 거부하는 정책과 목록에 노출하는 정책은 별도로 검토할 질문이다.

계약 조각무엇을 정하나확인할 위험
스키마도구 이름과 입력의 형태·필수값·범위기본 검증 책임이 실행부에 남을 수 있음
프롬프트언제·왜 이 도구를 쓰는지오용이나 과잉·과소 호출을 유도할 수 있음
권한실행 전 허용·거부·확인 판단필요한 판단 없이 실행될 수 있음
실행부작용 확인과 결과 생성실제 실패가 성공으로 표시될 수 있음
UI·로그진행·성공·실패 상태 표시승인·디버깅 판단이 어려울 수 있음
기능 게이트현재 환경의 기능 지원 여부지원하지 않는 호출을 시도할 수 있음

새 도구를 붙일 때는 함수 시그니처와 함께 이 질문들에 답을 적어 볼 수 있다. 어떤 입력을 받을지, 언제 호출할지, 어디서 권한을 판단할지, 실제 결과를 어떻게 확인할지 연결한다. 사용자가 볼 상태와 현재 환경의 지원 여부도 함께 확인한다. 권한 판단이라는 주제는 Claude Code 권한 게이트 글로 이어진다.

자주 묻는 질문

스키마가 경로 문자열을 제한하면 실행 직전 경계 검증은 생략해도 되나요?

아니다. 스키마는 입력 형식과 허용값 범위를 좁힐 뿐, 실제 경로의 존재·권한·프로젝트 경계까지 보장하지 않는다. 실행 직전에 경로를 정규화하고 경계를 별도로 확인해야 한다.

권한 판정만 단단하면 나머지 계약이 허술해도 안전한가요?

아니다. 권한은 실행을 허용할지 판단하는 한 조각이다. 스키마·프롬프트·실행·UI/로그·기능 게이트는 각각 다른 위험을 점검하기 위한 계약이므로 함께 검토해야 한다.

지원하지 않는 도구를 실행 단계에서 거부하면 기능 게이트는 없어도 되나요?

실행 단계의 거부와 도구 목록의 노출은 별도로 검토해야 한다. 환경에서 쓸 수 없는 도구가 목록에 보이면 모델이 호출을 시도했다가 실패할 수 있다. 기능 게이트는 지원 여부에 따라 도구 노출을 조정하기 위한 설계 항목이다.