내장 도구 이해하기

Claude Code가 "직접 일한다"고 할 때 그 손에 해당하는 것이 내장 도구입니다. 어떤 도구가 있고 언제 쓰이는지 알면, 왜 특정 지시가 잘 먹히고 다른 지시는 헛도는지 이해할 수 있습니다.

도구 묶음

읽기 계열

• 파일 읽기 — 특정 파일의 전체 또는 일부 구간. 이미지와 PDF도 읽습니다.
• 패턴 검색 — 정규식으로 코드베이스 전체를 훑습니다. "이 함수를 어디서 호출하지?"에 쓰입니다.
• 파일 찾기 — 이름 패턴으로 파일 목록을 얻습니다.

쓰기 계열

• 편집 — 기존 파일의 특정 문자열을 정확히 치환합니다. 읽지 않은 파일은 편집할 수 없습니다.
• 생성 — 새 파일을 만들거나 기존 파일을 통째로 대체합니다.

실행 계열

• 셸 명령 — 빌드, 테스트, Git, 패키지 설치 등. 실행 결과가 다음 판단의 근거가 됩니다.

위임 계열

• 서브 에이전트 — 독립적인 조사·작업을 별도 맥락에서 처리하고 결론만 받아옵니다.

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

낯선 코드베이스에서 파일을 하나씩 열어보는 건 비효율적입니다. 그래서 보통 패턴 검색으로 후보를 좁힌 다음, 그 파일들만 읽습니다.

지시할 때 검색 키워드를 함께 주면 이 단계가 훨씬 빨라집니다.

`createOrder`를 호출하는 곳을 전부 찾아서 트랜잭션 처리가 빠진 데가 있는지 봐줘.

편집이 실패하는 흔한 이유

편집 도구는 정확히 일치하는 문자열 하나를 요구합니다. 다음 경우 실패합니다.

• 대상 문자열이 파일에 여러 번 등장 → 더 넓은 범위를 지정해 유일하게 만들어야 함
• 들여쓰기나 공백이 다름 → 파일을 다시 읽어 실제 내용을 확인해야 함
• 파일을 읽지 않고 편집 시도 → 먼저 읽기가 강제됨

이 제약은 불편해 보이지만, 의도하지 않은 대량 치환을 막는 안전장치입니다.

명령 실행에서 주의할 점

셸 명령은 가장 강력하고 가장 위험한 도구입니다. 다음은 사람이 확인해야 할 유형입니다.

• 파일 삭제 (rm -rf)
• 이력 재작성 (git push --force, git reset --hard)
• 외부 전송 (배포, API 호출)
• 패키지 전역 설치

이런 명령을 아예 차단하거나 확인을 강제하려면 훅을 사용하세요.

도구 선택을 유도하는 법

지시에 행동 동사를 담으면 도구 선택이 정확해집니다.