Claude Code Tool 알아보기 - 260314

 

 

 

Claude Code Tool 설계 철학 배우기

 

Claude Code의 도구 설계는 단순히 기능 목록이 아니라 “LLM 기반 개발 에이전트를 운영 가능한 시스템으로 만들기 위한 구조”에 가깝다. 핵심 설계 철학은 네 가지로 압축할 수 있다.

 

첫째, 기능을 작은 단위의 capability로 분해했다. 파일 읽기, 파일 수정, 검색, 명령 실행 같은 기능을 각각 독립된 도구로 나누어 권한 관리와 추적이 가능하도록 만든 구조다. 이렇게 하면 특정 도구만 허용하거나 차단할 수 있고, 어떤 행동이 발생했는지도 명확히 기록할 수 있다.

 

둘째, 컨텍스트를 격리했다. Claude Code에서는 작업을 수행할 때 별도의 서브 에이전트를 실행할 수 있는데, 이 서브 에이전트는 독립적인 컨텍스트와 도구 접근 권한을 가진다. 이 구조는 긴 작업에서 컨텍스트 오염을 줄이고 역할별 책임을 분리하는 데 목적이 있다.

 

셋째, 작업 상태를 LLM 컨텍스트 밖으로 분리했다. TodoRead와 TodoWrite 같은 도구는 단순한 체크리스트 기능이 아니라, 장기 작업에서 상태를 외부에 저장하기 위한 구조다. LLM은 긴 대화에서 컨텍스트가 압축되거나 일부 정보가 사라질 수 있는데, 작업 목록을 외부 상태로 유지하면 계획이 유지된다.

 

넷째, 실행을 통제할 수 있도록 설계했다. Claude Code는 도구 호출을 중심으로 동작하기 때문에 어떤 작업이 실행되는지 항상 추적할 수 있고, 실행 전에 권한 확인이나 정책 검사를 적용할 수 있다. 이 구조는 실제 개발 환경에서 중요한 보안과 운영 통제를 가능하게 만든다.

 

이 설계를 한 문장으로 요약하면 다음과 같다.

Claude Code는 단순히 코드를 수정하는 AI가 아니라, 도구 호출을 중심으로 동작하는 “통제 가능한 개발 에이전트 시스템”으로 설계되어 있다.

 

실제 동작 흐름은 대체로 다음과 같은 패턴을 따른다. 먼저 코드베이스에서 필요한 파일을 검색한다. 그 다음 해당 파일을 읽고 내용을 이해한다. 이후 필요한 수정 계획을 세운 뒤 파일을 수정한다. 마지막으로 명령어를 실행해 결과를 확인한다.

 

즉 일반적인 흐름은 다음과 같이 정리된다.

코드 검색 → 파일 읽기 → 수정 계획 → 코드 수정 → 명령 실행 및 검증.

 

이 구조의 핵심은 모델 자체의 지능에 의존하는 것이 아니라, 작은 도구들을 조합하여 작업을 수행하도록 만드는 것이다.

이 방식 덕분에 작업 과정이 명확해지고, 보안과 운영 측면에서도 안정적인 AI 개발 도구를 만들 수 있다.

 

Claude Code Tool 정리

1. 코드 탐색 및 검색 도구

코드베이스 구조를 파악하거나 특정 코드/파일을 찾을 때 사용

도구	기능
Task (Agent)	다른 도구들을 활용하는 새로운 에이전트를 실행하여 복잡한 탐색이나 작업을 위임
Glob	파일 이름 패턴 기반 검색 (**/*.py, src/**/*.js)
Grep	파일 내부 텍스트를 정규표현식으로 검색
LS	특정 경로의 파일 및 디렉토리 목록 조회

핵심 특징

• 대규모 코드베이스 탐색용
• Task는 여러 검색을 묶어 자동 탐색 에이전트 역할

---

2. 파일 읽기 / 수정 도구

코드나 파일 내용을 읽거나 수정할 때 사용

도구	기능
Read	로컬 파일을 읽음 (기본 최대 2000줄)
Write	새로운 파일 작성 또는 기존 파일 덮어쓰기
Edit	특정 문자열을 찾아서 정확히 교체
MultiEdit	하나의 파일에서 여러 replace 작업 수행

중요 특징

• Edit, Write 사용 전 반드시 Read 수행
• 수정은 string replacement 방식

---

3. 노트북(Jupyter) 전용 도구

 

도구	기능
NotebookRead	.ipynb 파일의 모든 셀과 출력 읽기
NotebookEdit	특정 셀 수정 / 삽입 / 삭제

특징

• Jupyter notebook 구조를 이해하고 수정 가능
• 셀 단위 편집

---

4. 시스템 명령 실행 도구

 

도구	기능
Bash	쉘 명령 실행 (git, pip, docker, ls 등)
exit_plan_mode	계획 모드 종료 요청

특징

• 실제 개발 환경 명령 실행
• Git, 빌드, 테스트 자동화 가능

---

5. 웹 데이터 수집 도구

 

도구	기능
WebFetch	URL 콘텐츠를 가져와 HTML → Markdown 변환 후 분석
WebSearch	최신 웹 검색 수행

특징

• WebFetch → 특정 페이지 분석
• WebSearch → 최신 정보 검색

---

6. 작업 관리 도구

도구	기능
TodoRead	현재 작업 목록 조회
TodoWrite	작업 목록 생성 및 상태 관리

작업 상태

• pending
• in_progress
• completed

특징

• 복잡한 작업 진행 상황 관리
• 사용자에게 진행 상황을 투명하게 표시

 

전체 정리

 

 

 

참고자료

https://code.claude.com/docs/en/settings?utm_source=chatgpt.com

https://gist.github.com/wong2/e0f34aac66caf890a332f7b6f9e2ba8f#file-claude-code-tools-md