내장 도구 이해하기

앞 글에서 컨텍스트를 채우는 것이 도구 결과라고 했습니다. 이 글은 그 도구들을 직접 봅니다. 도구 이름은 권한 규칙과 훅 매처에서 그대로 쓰는 문자열이라 정확히 알아 두면 설정에 바로 씁니다. 읽고 나면 왜 검색부터 하는지, 왜 편집이 가끔 실패하는지 알고 원하는 도구가 쓰이도록 요청을 다듬을 수 있습니다.

핵심 요약

• 내장 도구는 파일 작업, 검색, 실행, 웹, 코드 인텔리전스의 다섯 묶음입니다.
• Read·Grep·Glob은 작업 디렉토리 안에서 확인 없이 실행되고, Bash·Edit·Write는 기본 모드에서 승인을 요구합니다.
• Edit은 정확 문자열 교체라 대상이 한 글자라도 다르거나 두 번 이상 나타나면 실패합니다.
• Bash는 명령마다 별도 프로세스이며 기본 2분 타임아웃, 3만 자 출력 제한이 있습니다.

도구 묶음

이 밖에 서브에이전트를 만드는 Agent, 객관식 질문 AskUserQuestion, 스킬 실행 Skill 같은 오케스트레이션 도구가 있습니다. 특정 도구를 막으려면 permissions.deny에 이름을 넣습니다.

왜 "검색"이 "읽기"보다 먼저인가

Read는 파일 하나를 통째로 컨텍스트에 넣고, 크면 첫 페이지만 PARTIAL view로 돌려줍니다. 반면 Glob은 이름 패턴으로 파일 목록만(최대 100개), Grep은 ripgrep 기반으로 일치 파일 경로만 돌려주는 것이 기본입니다. 검색은 싸고 읽기는 비쌉니다. 좁힌 뒤 읽는 것이 컨텍스트를 아끼는 순서입니다. Grep은 .gitignore를 존중하지만 Glob은 무시 파일도 찾습니다.

편집이 실패하는 흔한 이유

Edit은 old_string을 new_string으로 바꾸는 정확 교체입니다. 실패 원인은 세 가지입니다.

1. 읽지 않은 파일: 같은 대화에서 읽었어야 하며 PARTIAL view로 잘린 읽기는 인정되지 않습니다.
2. 불일치: 공백 한 글자만 달라도 실패합니다. 마지막 읽기 뒤 디스크에서 파일이 바뀐 경우가 흔한 원인입니다.
3. 중복: 대상이 두 번 이상 나타나면 실패합니다. 문맥을 더 넣거나 replace_all: true로 전부 바꿉니다.

Write는 새 파일 생성 또는 통째 덮어쓰기라 기존 파일 수정에 쓰이면 최소 수정이 아닙니다. 우리 5주차 황금 문장의 "최소 수정"은 도구 수준에서 Edit 사용을 유도하는 말이기도 합니다.

명령 실행에서 주의할 점

Bash는 명령마다 별도 프로세스라 export는 다음 명령에 남지 않고 cd는 프로젝트 폴더 안에서만 이월됩니다. 타임아웃은 기본 2분, 최대 10분이고, 출력이 3만 자를 넘으면 파일로 저장하고 미리보기만 돌려줍니다. 끝나지 않는 명령은 백그라운드로 띄우고 /tasks로 관리합니다.

권한 쪽이 더 중요합니다. 우리 7주차의 "운영 DB는 성역" 원칙대로 Bash(psql *) 같은 위험 명령은 deny나 ask에, Bash(pnpm test *) 같은 검증 명령만 allow에 둡니다. rm·mv로 바꾼 파일은 체크포인트가 추적하지 않아 되감기로 복구되지 않습니다.

도구 선택을 유도하는 법

• @src/api/apply.ts처럼 경로를 적으면 검색 없이 바로 읽습니다.
• "원인 분석 후 최소 수정"이라고 쓰면 Grep·Read 뒤에 Edit이 옵니다.
• "테스트를 실행해 통과를 확인해 줘"라고 쓰면 Bash로 증거를 남기고 끝냅니다.
• 못 박고 싶으면 --disallowedTools "WebSearch"처럼 설정으로 막습니다.

정리

• 도구 이름은 설정에서 그대로 쓰는 식별자입니다.
• 검색은 싸고 읽기는 비싸므로 좁힌 뒤 읽습니다.
• Edit 실패는 읽지 않음, 불일치, 중복 중 하나입니다.
• 위험 명령은 권한 규칙으로 막습니다.

자주 묻는 질문