도구 연결하기 — allowed-tools의 세계

도구 없는 셰프의 비극

세계 최고의 셰프를 상상해보세요. 미슐랭 3스타를 받은, 어떤 요리든 만들 수 있는 천재 셰프.

근데 이 셰프에게 도구를 하나도 주지 않는다면?

칼도 없고, 팬도 없고, 오븐도 없고, 냉장고도 없어요. 맨손이에요.

지금까지 우리가 만든 스킬이 바로 이 상태예요.

챕터 8의 인사하기 스킬, 챕터 9의 요약 스킬 — 다 좋아요. 근데 이 스킬들은 "텍스트를 받아서 텍스트를 내보내는 것"밖에 못 해요. 파일을 읽지 못하고, 명령어를 실행하지 못하고, 코드를 검색하지 못해요.

셰프에게 주방 도구를 주면 요리의 차원이 달라지듯, 스킬에 도구(tools)를 연결하면 스킬의 차원이 달라져요.

이번 챕터에서 배울 것: allowed-tools — 스킬에게 초능력을 부여하는 열쇠.

Claude Code의 도구들

"도구"가 정확히 뭘 말하는 걸까요?

Claude Code에는 AI가 사용할 수 있는 여러 가지 내장 도구(built-in tools)가 있어요. 각각 다른 능력을 가지고 있죠.

이걸 주방 도구에 비유하면:

• Read = 눈 (재료를 볼 수 있음)
• Write = 도마와 칼 (새로운 것을 만들 수 있음)
• Edit = 양념통 (기존 것에 뭔가를 추가/수정)
• Bash = 만능 조리기구 (뭐든 할 수 있음)
• Glob = 냉장고 정리함 (필요한 재료를 찾기)
• Grep = 돋보기 (재료 안에서 특정 성분을 찾기)

allowed-tools: 권한을 주는 열쇠

자, 여기서 중요한 포인트. AI가 이 도구들을 아무 때나 막 쓸 수 있는 게 아니에요.

스킬을 만들 때, "이 스킬은 이 도구들만 쓸 수 있어"라고 명시적으로 허가해줘야 해요. 그게 바로 allowed-tools 필드예요.

---
description: "프로젝트의 코드 줄 수를 세는 스킬"
allowed-tools: ["Bash", "Glob"]
---

이 스킬은 Bash와 Glob만 쓸 수 있어요. Write나 Edit은 못 써요. 파일을 수정하는 건 이 스킬의 역할이 아니니까.

왜 이렇게 제한을 둘까요?

자주 쓰는 도구 조합

도구를 어떻게 조합하느냐에 따라 스킬의 성격이 완전히 달라져요.

읽기 전용 스킬: 보기만 해요

allowed-tools: ["Read", "Glob", "Grep"]

파일을 찾고, 읽고, 검색할 수 있지만 절대 수정하지 않아요. 코드 분석, 리뷰, 감사(audit) 같은 스킬에 적합해요.

비유하면: 미술관 관람객. 작품을 보고 감상할 수는 있지만, 절대 건드리지 않아요.

빌더 스킬: 만들고 고쳐요

allowed-tools: ["Read", "Write", "Edit", "Bash"]

파일을 읽고, 새로 만들고, 수정하고, 명령어도 실행해요. 코드 생성, 프로젝트 설정 같은 스킬에 적합해요.

비유하면: 인테리어 디자이너. 집을 둘러보고, 가구를 배치하고, 벽지를 바꾸고, 도구를 사용해요.

풀 파워 스킬: 다 할 수 있어요

allowed-tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]

모든 도구를 사용할 수 있어요. 강력하지만, 그만큼 신중하게 만들어야 해요.

비유하면: 집주인. 뭐든 할 수 있지만, 책임도 커요.

실전: "코드 카운터" 스킬 만들기

이론은 충분해요. 실제로 도구를 사용하는 스킬을 만들어봅시다!

우리가 만들 스킬: 프로젝트의 코드 줄 수를 세는 "코드 카운터" 스킬

이 스킬이 하는 일:

• 프로젝트 폴더를 살펴보고
• 프로그래밍 파일들을 찾고
• 각 언어별로 코드가 몇 줄인지 세서
• 깔끔한 보고서로 보여주기

폴더 구조:

code-counter/
  └── SKILL.md

SKILL.md 전체 내용:

---
description: "프로젝트의 코드 줄 수를 언어별로 세서 보고서를 만들어주는 스킬"
allowed-tools: ["Bash", "Glob", "Grep"]
---

# 코드 카운터 스킬

당신은 코드 분석 전문가입니다. 프로젝트의 코드 줄 수를 정확하게
세고, 알기 쉬운 보고서로 정리해주세요.

## 수행 절차

1. **파일 탐색**: Glob 도구를 사용해서 프로젝트 내 소스 코드 파일을 찾으세요
   - 대상: `*.js`, `*.ts`, `*.py`, `*.java`, `*.go`, `*.rs`, `*.html`, `*.css`
   - 제외: `node_modules/`, `.git/`, `dist/`, `build/` 폴더
2. **줄 수 계산**: Bash 도구로 각 파일의 줄 수를 계산하세요
   - 빈 줄과 주석을 제외한 실제 코드 줄 수
   - 명령어 예시: `wc -l` 또는 언어별 분석
3. **결과 정리**: 아래 형식으로 보고서를 작성하세요

## 출력 형식

```
📊 코드 분석 보고서
====================

📁 프로젝트: [프로젝트 이름]
📅 분석 일시: [현재 날짜/시간]

언어별 코드 줄 수:
┌─────────────┬──────────┬──────────┐
│ 언어         │ 파일 수   │ 코드 줄 수 │
├─────────────┼──────────┼──────────┤
│ JavaScript  │ XX개      │ X,XXX줄   │
│ TypeScript  │ XX개      │ X,XXX줄   │
│ Python      │ XX개      │ X,XXX줄   │
│ ...         │ ...      │ ...      │
├─────────────┼──────────┼──────────┤
│ 합계         │ XX개      │ X,XXX줄   │
└─────────────┴──────────┴──────────┘

💡 인사이트:
- 가장 많은 비중을 차지하는 언어: [언어]
- 가장 큰 파일: [파일명] (XX줄)
```

## 주의사항
- node_modules, .git 등 외부 라이브러리 폴더는 반드시 제외
- 자동 생성된 파일(*.min.js, dist/ 등)도 제외
- 파일을 수정하지 않을 것 (읽기만!)

주목할 부분:

allowed-tools: ["Bash", "Glob", "Grep"]

이 스킬은 Bash(줄 수를 세는 명령어 실행), Glob(파일 찾기), Grep(내용 검색)만 사용해요. Write나 Edit은 없어요 — 이 스킬은 분석만 하지, 파일을 건드리지 않으니까!

이렇게 만들고, 이전 챕터에서 배운 대로 설치한 뒤, Claude Code에서 이렇게 말해보세요:

이 프로젝트의 코드 줄 수를 세줘

그러면 AI가 Glob으로 파일을 찾고, Bash로 줄 수를 세고, 깔끔한 보고서를 만들어줘요. 도구 없이는 절대 불가능한 일이에요!

보안 마인드: 권한은 항상 최소로

마지막으로 중요한 이야기를 하나 할게요.

스킬에 도구를 연결하는 건 강력하지만, 그만큼 책임도 커져요.

기억하세요: 필요한 만큼만, 딱 그만큼만.