내장 도구 활용하기

들어가며

이전 차시에서 Agentic Loop의 작동 원리를 다뤘다. Claude Code가 컨텍스트 수집, 행동, 결과 검증을 반복하면서 목표를 달성하는 구조를 살펴봤다.

이 루프를 실제로 구동하는 것이 **도구(Tool)**다. 도구가 없으면 Claude는 텍스트로만 응답할 수 있다. 도구가 있기 때문에 파일을 읽고, 코드를 수정하고, 명령을 실행할 수 있다.

이번 차시에서는 Claude Code의 핵심 내장 도구 6가지를 하나씩 살펴본다. 각 도구의 역할, 사용 시점, 그리고 도구를 조합해서 작업하는 전략까지 다룬다.

내장 도구 전체 그림

도구 카테고리

공식 문서에 따르면, Claude Code의 내장 도구는 다섯 가지 카테고리로 나뉜다.

이번 차시에서는 가장 기본이 되는 6가지 도구에 집중한다.

6가지 핵심 도구

권한이 필요 없는 도구(Read, Glob, Grep)는 자동으로 실행된다. 파일을 변경하거나 명령을 실행하는 도구(Edit, Write, Bash)는 사용자 승인이 필요하다. 읽기는 안전하지만 쓰기는 위험할 수 있기 때문이다.

그 외 내장 도구

6가지 핵심 도구 외에도 Claude Code에는 다양한 내장 도구가 있다.

전체 도구 목록은 Tools reference에서 확인할 수 있다.

파일 작업 도구

Read: 파일 읽기

Read는 파일 내용을 읽어서 Claude의 컨텍스트에 추가하는 도구다. 읽기 전용이므로 권한 없이 자동 실행된다.

기본 동작

[Read] src/components/Button.tsx
→ 파일 내용을 반환
→ Claude의 컨텍스트에 추가

주요 기능

• 텍스트 파일뿐 아니라 이미지(PNG, JPG 등)와 PDF도 읽을 수 있다
• Jupyter 노트북(.ipynb)을 읽으면 코드, 텍스트, 시각화 결과를 모두 반환한다
• 큰 파일은 시작 줄과 줄 수를 지정해서 부분만 읽을 수 있다
• 결과는 줄 번호가 포함된 형태(cat -n 형식)로 반환된다

활용 시나리오

• 코드 구조와 로직 이해
• 버그가 있는 파일 분석
• 기존 코딩 패턴 확인
• 설정 파일 내용 확인

Read는 Agentic Loop의 컨텍스트 수집 단계에서 가장 많이 사용되는 도구다. Claude가 코드를 이해하려면 먼저 읽어야 하기 때문이다.

Edit: 파일 수정

Edit는 기존 파일의 내용을 수정하는 도구다. 파일을 변경하므로 사용자 승인이 필요하다.

기본 동작

[Edit] src/components/Button.tsx

변경사항:
- const Button = (props) => {
+ const Button: React.FC<ButtonProps> = (props) => {

이 변경사항을 적용할까요? [y/n/e]

Edit는 전체 파일을 다시 쓰는 것이 아니라, 변경이 필요한 부분만 정확하게 교체한다. 기존 텍스트(old_string)를 새 텍스트(new_string)로 바꾸는 방식이다.

주요 특징

• 교체할 텍스트가 파일 내에서 유일해야 한다. 동일한 텍스트가 여러 곳에 있으면 더 많은 주변 컨텍스트를 포함해야 한다
• replace_all 옵션으로 파일 내 모든 일치 항목을 한 번에 교체할 수 있다. 변수명 변경 같은 작업에 유용하다
• 변경 전에 반드시 Read로 파일을 먼저 읽어야 한다

활용 시나리오

• 버그 수정
• 기능 추가
• 리팩토링
• 타입 추가

주의사항

변경사항이 표시되면 diff를 주의 깊게 확인해야 한다. Claude가 의도하지 않은 부분을 변경할 수도 있다. y(승인), n(거부), e(편집) 중 선택할 수 있다.

Write: 파일 생성

Write는 새로운 파일을 생성하거나 기존 파일을 완전히 덮어쓰는 도구다. 사용자 승인이 필요하다.

기본 동작

[Write] src/components/Header.tsx
→ 새 파일 생성
→ 전체 내용 작성

Edit와의 차이

기존 파일을 수정할 때는 Edit를 사용하는 것이 효율적이다. Write는 전체 내용을 전송하므로 큰 파일에서는 비효율적이다. Claude도 가능하면 Edit를 우선 사용한다.

활용 시나리오

• 새 컴포넌트 파일 생성
• 테스트 파일 생성
• 설정 파일 추가
• 문서 파일 작성

주의사항

기존 파일에 Write를 사용하면 내용이 완전히 덮어써진다. 의도하지 않은 데이터 손실이 발생할 수 있으므로, 기존 파일은 Edit로 수정하는 것이 안전하다.

검색 도구

Glob: 파일 패턴 검색

Glob은 파일 이름 패턴으로 파일을 찾는 도구다. 읽기 전용이므로 자동 실행된다.

기본 동작

[Glob] **/*.test.ts
→ 프로젝트 내 모든 테스트 파일 목록 반환

패턴 문법

실용적인 패턴 예시

[Glob] src/components/**/*.tsx
→ components 하위의 모든 TSX 파일

[Glob] *.config.{js,ts}
→ 루트의 모든 설정 파일 (JS, TS)

[Glob] src/**/*login*.*
→ src 하위에서 login이 포함된 모든 파일

활용 시나리오

• 특정 유형의 파일 찾기 (테스트 파일, 컴포넌트 파일)
• 설정 파일 위치 확인
• 프로젝트 구조 파악
• 특정 이름 패턴의 파일 검색

Glob은 파일의 이름으로 검색한다. 파일 내용으로 검색하려면 Grep을 사용한다.

Grep: 내용 검색

Grep은 파일 내용에서 텍스트 패턴을 검색하는 도구다. 정규식을 지원하며 자동 실행된다.

기본 동작

[Grep] "TODO" --type ts
→ TypeScript 파일에서 TODO가 포함된 위치 반환

주요 옵션

출력 모드

• files_with_matches (기본값): 일치하는 파일 경로만 반환
• content: 일치하는 줄과 내용을 반환
• count: 파일별 일치 횟수를 반환

실용적인 검색 예시

[Grep] "TODO" --type ts
→ TypeScript 파일의 TODO 주석 찾기

[Grep] "function.*login" --type ts
→ login이 포함된 함수 정의 찾기

[Grep] "API_KEY" src/
→ src 폴더에서 API_KEY 문자열 검색

[Grep] "import.*from.*react" --glob "*.tsx"
→ TSX 파일에서 React import문 찾기

활용 시나리오

• TODO 주석 찾기
• 특정 함수나 변수의 사용 위치 파악
• 하드코딩된 값 검색
• 에러 메시지 추적
• 특정 패턴의 코드 찾기

Glob과 Grep의 차이

실행 도구

Bash: 셸 명령 실행

Bash는 터미널 명령을 실행하는 도구다. 시스템에 직접적인 영향을 미칠 수 있으므로 사용자 승인이 필요하다.

기본 동작

[Bash] npm test
→ 테스트 실행
→ 결과 출력

승인 요청: [y/n]

주요 특징

• 작업 디렉토리는 명령 간에 유지된다
• 환경 변수는 명령 간에 유지되지 않는다. 한 명령에서 export한 변수는 다음 명령에서 사용할 수 없다
• 타임아웃은 기본 2분이며, 최대 10분까지 설정할 수 있다
• 백그라운드 실행도 가능하다

활용 시나리오

[Bash] npm test                    # 테스트 실행
[Bash] npm run build               # 빌드 실행
[Bash] npm install axios           # 패키지 설치
[Bash] git status                  # Git 상태 확인
[Bash] git diff                    # 변경사항 확인
[Bash] python script.py            # 스크립트 실행

보안 고려사항

Bash는 가장 강력하지만 가장 위험한 도구이기도 하다.

• 파괴적인 명령(rm -rf, DROP TABLE 등)에 주의해야 한다
• 프로덕션 환경에서는 특히 신중하게 사용해야 한다
• 권한 설정에서 위험한 명령을 차단할 수 있다

{
  "permissions": {
    "allow": [
      "Bash(npm run test)",
      "Bash(npm run lint)",
      "Bash(git status)",
      "Bash(git diff)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)"
    ]
  }
}

자주 사용하는 안전한 명령은 allow 목록에 추가하면 매번 승인하지 않아도 된다. 위험한 명령은 deny 목록에 추가해서 실행 자체를 차단할 수 있다.

도구 조합 전략

Claude는 단일 도구만 사용하지 않는다. 여러 도구를 조합해서 작업을 수행한다. 자주 사용되는 도구 조합 패턴을 알아두면 Claude의 동작을 이해하고 효과적으로 활용할 수 있다.

패턴 1: 탐색 → 읽기 → 수정

가장 기본적인 패턴이다. 먼저 파일을 찾고, 내용을 읽고, 수정한다.

[Glob] src/**/*login*.ts        # 파일 찾기
[Read] src/pages/Login.tsx       # 내용 읽기
[Edit] src/pages/Login.tsx       # 코드 수정

“로그인 페이지의 버튼 텍스트를 변경해줘” 같은 요청에서 이 패턴이 사용된다.

패턴 2: 검색 → 읽기 → 수정

파일 이름을 모를 때, 코드 내용으로 먼저 검색하는 패턴이다.

[Grep] "validateEmail" --type ts  # 함수 사용 위치 검색
[Read] src/utils/validation.ts    # 해당 파일 읽기
[Edit] src/utils/validation.ts    # 함수 수정

“이메일 검증 로직을 수정해줘” 같은 요청에서 이 패턴이 사용된다. Claude는 먼저 관련 코드가 어디에 있는지 검색한다.

패턴 3: 수정 → 테스트 → 확인

수정 후 검증하는 패턴이다. Agentic Loop의 결과 검증 단계에 해당한다.

[Edit] src/components/Button.tsx   # 코드 수정
[Bash] npm test Button.test.ts     # 테스트 실행
[Read] test-results.json           # 결과 확인

Claude는 코드를 수정한 후 테스트를 실행해서 수정이 올바른지 검증한다. 테스트가 실패하면 에러를 분석하고 다시 수정한다.

패턴 4: 생성 → 읽기 → 통합

새 파일을 생성하고 기존 코드에 통합하는 패턴이다.

[Write] src/components/Header.tsx  # 새 컴포넌트 생성
[Read] src/components/index.ts     # 기존 export 파일 확인
[Edit] src/components/index.ts     # export 추가

“Header 컴포넌트를 만들어줘” 같은 요청에서 이 패턴이 사용된다. 파일을 생성하는 것으로 끝나지 않고, 기존 코드에 통합까지 처리한다.

패턴 5: 병렬 읽기 → 분석 → 수정

독립적인 파일 여러 개를 동시에 읽는 패턴이다.

[Read] src/componentA.tsx  ─┐
[Read] src/componentB.tsx  ─┤ 동시 실행
[Read] src/componentC.tsx  ─┘
→ 전체 구조 분석
[Edit] src/componentB.tsx     # 필요한 파일만 수정

Claude는 독립적인 작업을 병렬로 실행해서 시간을 절약한다. 여러 파일을 읽기만 하는 경우 동시에 처리할 수 있다. 하지만 파일을 수정하려면 먼저 읽어야 하므로, Read → Edit는 반드시 순차 실행된다.

패턴 6: 에러 복구 루프

빌드나 테스트 에러가 발생했을 때 자동으로 수정하는 패턴이다.

[Bash] npm run build           # 빌드 실행
→ TypeScript 타입 에러 발생

[Read] src/utils/helper.ts     # 에러 파일 읽기
[Edit] src/utils/helper.ts     # 타입 수정

[Bash] npm run build           # 다시 빌드
→ 성공

이 패턴이 Agentic Loop의 핵심이다. Claude는 에러가 발생하면 원인을 분석하고 수정을 시도한다. 성공할 때까지 이 과정을 반복한다.

실전 예시

예시 1: TODO 주석 찾아서 구현하기

“모든 TODO 주석을 찾아서 구현해줘”라고 요청하면 Claude는 다음과 같이 작업한다.

[Grep] "TODO" --type ts              # 1. TODO 검색
→ 3개 파일에서 TODO 발견

[Read] src/utils/helper.ts           # 2. 첫 번째 파일 읽기
[Edit] src/utils/helper.ts           # 3. TODO 구현

[Read] src/services/api.ts           # 4. 두 번째 파일 읽기
[Edit] src/services/api.ts           # 5. TODO 구현

[Read] src/hooks/useAuth.ts          # 6. 세 번째 파일 읽기
[Edit] src/hooks/useAuth.ts          # 7. TODO 구현

[Bash] npm test                      # 8. 전체 테스트 실행
→ 모든 테스트 통과

검색(Grep) → 읽기(Read) → 수정(Edit)을 반복하고, 마지막에 테스트(Bash)로 검증한다.

예시 2: 새 컴포넌트 추가

“사이드바 컴포넌트를 만들어줘”라고 요청하면 Claude는 다음과 같이 작업한다.

[Glob] src/components/**/*.tsx       # 1. 기존 컴포넌트 구조 확인
→ 컴포넌트 파일 목록 반환

[Read] src/components/Header.tsx     # 2. 기존 패턴 확인
→ 코딩 스타일, import 패턴 파악

[Write] src/components/Sidebar.tsx   # 3. 새 컴포넌트 생성
[Write] src/components/Sidebar.test.tsx  # 4. 테스트 파일 생성

[Read] src/components/index.ts       # 5. export 파일 확인
[Edit] src/components/index.ts       # 6. export 추가

[Bash] npm test Sidebar.test.tsx     # 7. 테스트 실행
→ 테스트 통과

기존 코드의 패턴을 먼저 확인한 후 같은 스타일로 새 파일을 생성한다. 이것이 Claude가 프로젝트의 코딩 컨벤션을 따르는 방식이다.

Claude에 도움 요청하기

현재 세션에서 사용할 수 있는 도구 목록을 확인하려면 Claude에게 직접 물어볼 수 있다.

> 어떤 도구를 사용할 수 있어?

Claude가 사용 가능한 도구를 요약해서 알려준다. MCP 도구의 정확한 이름을 확인하려면 /mcp 명령을 사용한다.

정리

핵심 요점

1. 6가지 핵심 도구: Read, Edit, Write는 파일을 다루고, Glob, Grep은 코드를 검색하고, Bash는 명령을 실행한다. 이 6가지 도구가 Claude Code의 기본 능력이다

2. 권한 구분: 읽기 전용 도구(Read, Glob, Grep)는 자동 실행되고, 변경 도구(Edit, Write, Bash)는 사용자 승인이 필요하다

3. Glob vs Grep: Glob은 파일 이름으로 찾고, Grep은 파일 내용으로 찾는다. 용도가 다르므로 상황에 맞게 선택해야 한다

4. Edit vs Write: 기존 파일 수정은 Edit(변경 부분만 전송), 새 파일 생성은 Write(전체 내용 전송)를 사용한다. Claude도 가능하면 Edit를 우선한다

5. 도구 조합: Claude는 단일 도구가 아닌 여러 도구를 조합해서 작업한다. 탐색 → 읽기 → 수정 → 검증이 가장 기본적인 흐름이다

6. 확장 가능: 내장 도구 외에도 MCP로 외부 서비스를 연결하고, 스킬로 워크플로우를 추가할 수 있다

확인해볼 링크

• Tools reference - Claude Code
• How Claude Code works - Claude Code
• Configure permissions - Claude Code

다음 단계

다음 차시에서는 Claude Code의 권한 시스템을 다룬다. Ask, Code, Plan, Auto 모드의 차이점과 도구별 권한 설정 방법을 살펴본다.

참고 자료

• Tools reference - Claude Code
• How Claude Code works - Claude Code
• Configure permissions - Claude Code