# 도구 시스템 레퍼런스 (/ko/docs/verdent-for-vscode/advanced-features/tool-reference)
> Verdent의 도구 시스템 전체 레퍼런스
### 학습 내용 [#학습-내용]
파일 작업, 검색 기능, 명령 실행, 연동 도구를 포함한 Verdent의 내장 도구 시스템 전체 레퍼런스입니다.
***
## 사용 가능한 도구 개요 [#사용-가능한-도구-개요]
Verdent for VS Code는 코드 수정, 탐색, 외부 상호작용을 위한 포괄적인 도구 모음을 제공합니다.
| 도구 | 목적 | 주요 기능 |
| ------------ | ------------- | -------------------------------------- |
| `file_read` | 파일 내용 읽기 | 큰 파일을 위한 줄 범위를 지원하며, 모든 텍스트 형식에서 작동합니다 |
| `file_edit` | 대상 지정 수정 | 정확히 일치하는 텍스트 교체, 여러 교체, 서식 보존을 지원합니다 |
| `file_write` | 파일 생성 또는 덮어쓰기 | 전체 파일 생성/교체를 지원하며, 텍스트 콘텐츠를 처리합니다 |
| 도구 | 목적 | 주요 기능 |
| -------------- | ---------------- | ----------------------------------------- |
| `glob` | 패턴 기반 파일 검색 | Glob 패턴(`**/*.ts`), 제외 패턴, 결과 수 제한을 지원합니다 |
| `grep_content` | 컨텍스트가 포함된 콘텐츠 검색 | 정규식 지원, 컨텍스트 줄, 대소문자 무시 옵션을 제공합니다 |
| `grep_file` | 일치 항목이 있는 파일 나열 | 내용을 읽기 전에 파일을 빠르게 식별합니다 |
| `list_dir` | 디렉터리 구조 | 계층 구조 표시, 제외 패턴, 깊이 제어를 지원합니다 |
| 도구 | 목적 | 주요 기능 |
| ---------------- | ----------- | -------------------------------------------------------- |
| `bash` | 셸 명령 실행 | 타임아웃 설정, 요약 설명, 명령 체이닝을 지원합니다 |
| `spawn_subagent` | 전문가에게 위임 | general, explorer, verifier, code-reviewer 서브에이전트를 실행합니다 |
| `todo_update` | 작업 진행 상황 추적 | 작업 목록 관리, 상태 업데이트, 진행 상황 추적을 지원합니다 |
| 도구 | 목적 | 주요 기능 |
| ------------ | ------------- | ------------------------------ |
| `web_search` | 인터넷 검색 | 쿼리 실행, 결과 수 제어, 최신성 필터링을 지원합니다 |
| `web_fetch` | 페이지 가져오기 및 분석 | 콘텐츠를 가져오고, 쿼리로 정보를 추출합니다 |
***
## 도구 기능 및 사용 사례 [#도구-기능-및-사용-사례]
### file\_read [#file_read]
**기능:**
* 전체 파일 내용 또는 특정 줄 범위를 읽습니다
* 수정 전에 코드를 이해하는 데 필수적입니다
* 범위 지정으로 큰 파일을 효율적으로 처리합니다
**사용 사례:**
* 편집 전에 설정 파일 읽기
* 기존 구현 패턴 이해하기
* 커버리지를 이해하기 위해 테스트 파일 검토하기
**예시:**
```bash
# Read entire file
file_read("src/components/Button.tsx")
# Read specific range for large files
file_read("package-lock.json", start_line=1, max_lines=50)
```
***
### file\_edit [#file_edit]
**기능:**
* 정확한 문자열 일치를 사용해 텍스트를 정밀하게 교체합니다
* `multiple` 플래그로 여러 교체 작업을 수행합니다
* 파일 구조와 서식을 보존합니다
**사용 사례:**
* 함수 구현 업데이트
* 설정 값 수정
* 여러 파일에서 변수 이름 리팩터링
**모범 사례:** 대상이 명확한 변경에 사용합니다. 전체를 다시 작성하려면 대신 `file_write`를 사용합니다.
***
### file\_write [#file_write]
**기능:**
* 새 파일을 처음부터 생성합니다
* 기존 파일 내용을 완전히 교체합니다
* 모든 텍스트 기반 형식을 처리합니다
**사용 사례:**
* 새 컴포넌트 또는 모듈 생성
* 설정 파일 생성
* 테스트 파일 작성
**경고:** 기존 파일을 완전히 덮어씁니다. 부분 수정에는 `file_edit`를 사용합니다.
### glob [#glob]
**기능:**
* 패턴과 일치하는 파일 찾기: `**/*.ts`, `src/**/*.js`
* 디렉터리 경로로 필터링합니다
* 제외 패턴으로 결과 범위를 좁힙니다
* 결과 수를 제어합니다
**사용 사례:**
* 프로젝트의 모든 컴포넌트 찾기
* 테스트 파일 찾기
* 여러 디렉터리에서 설정 파일 식별하기
**예시 패턴:**
```bash
**/*.tsx # All TypeScript React files
src/**/*.test.js # All test files in src
**/config.* # All config files anywhere
```
***
### grep\_content [#grep_content]
**기능:**
* 정규식 패턴으로 파일 내용을 검색합니다
* 일치 항목 앞/뒤의 컨텍스트 줄을 표시합니다(`-B`, `-A` 플래그)
* 대소문자 무시 검색을 지원합니다
* Glob 패턴을 사용해 파일 유형으로 필터링합니다
**사용 사례:**
* 함수 정의 찾기
* API 엔드포인트 구현 찾기
* 특정 오류 메시지 검색하기
* 보안 패턴 식별하기
**예시:**
```bash
# Find authentication-related code
grep_content("auth.*login", glob="**/*.ts")
# Search with context
grep_content("TODO", glob="src/**", context_before=2, context_after=2)
```
***
### grep\_file [#grep_file]
**기능:**
* 패턴 일치 항목이 포함된 파일을 나열합니다
* 파일 위치만 필요할 때 `grep_content`보다 빠릅니다
* 정규식 패턴을 지원합니다
* 파일 유형에 대한 Glob 필터링을 지원합니다
**사용 사례:**
* 리팩터링이 필요한 파일 식별하기
* 특정 모듈을 가져오는 파일 찾기
* 사용 중단된 패턴이 있는 파일 찾기
**모범 사례:** 먼저 `grep_file`로 관련 파일을 식별한 다음, 자세히 확인하려면 `file_read`를 사용합니다.
***
### list\_dir [#list_dir]
**기능:**
* 디렉터리 계층 구조를 표시합니다
* `max_depth` 매개변수로 깊이를 제어합니다
* 제외 패턴으로 출력을 필터링합니다
**사용 사례:**
* 프로젝트 구조 이해하기
* 디렉터리 구성이 올바른지 확인하기
* 특정 하위 디렉터리 찾기
### bash [#bash]
**기능:**
* 셸 명령을 실행합니다
* 최대 타임아웃: 120초(2분, 하드 리밋)
* 의존성이 있는 경우 `&&`로 명령을 체이닝합니다
* 명확성을 위해 설명 요약을 제공합니다
**사용 사례:**
* 테스트 실행
* 프로젝트 빌드
* 의존성 설치
* Git 작업
* 데이터베이스 마이그레이션
**예시:**
```bash
# Run tests
bash("npm test", timeout=60000, summary="Run Jest test suite")
# Chain dependent commands
bash("npm install && npm run build", timeout=120000)
```
**보안:** 명령은 사용자 권한으로 실행됩니다. Manual Accept Mode에서 명령을 검토합니다.
***
### spawn\_subagent [#spawn_subagent]
**기능:**
* 격리된 컨텍스트를 가진 전문 서브에이전트를 실행합니다
* 유형: `explorer`, `verifier`, `code-reviewer`
* 메인 컨텍스트를 오염시키지 않고 복잡한 작업을 위임합니다
* 효율성을 위해 서브에이전트를 병렬로 실행합니다
**사용 사례:**
* **explorer:** 대규모 코드베이스에서 패턴 검색
* **verifier:** 구현 로직 검증
* **code-reviewer:** 보안 및 품질 평가
**모범 사례:** 메인 대화 컨텍스트를 보존하기 위해 탐색성 조사는 Explorer 서브에이전트에 위임합니다.
***
### todo\_update [#todo_update]
**기능:**
* 작업 목록을 생성하고 관리합니다
* 작업 상태를 업데이트합니다(pending, in\_progress, completed)
* 복잡한 구현 전반의 진행 상황을 추적합니다
**사용 사례:**
* 여러 단계로 이루어진 기능 분해
* 리팩터링 진행 상황 추적
* 마이그레이션 작업 관리
### web\_search [#web_search]
**기능:**
* 인터넷 검색 엔진에 쿼리합니다
* 결과 수를 제어합니다
* 최신성(최근 일수)으로 필터링합니다
**사용 사례:**
* 익숙하지 않은 API의 문서 찾기
* 오류 메시지 조사하기
* 최신 모범 사례 확인하기
***
### web\_fetch [#web_fetch]
**기능:**
* 웹 페이지 내용을 가져옵니다
* 특정 쿼리로 콘텐츠를 분석합니다
* 구조화된 정보를 추출합니다
**사용 사례:**
* 문서 페이지 읽기
* API 문서 분석
* 튜토리얼에서 예시 추출하기
***
## 파일 형식 지원 [#파일-형식-지원]
Verdent는 파일 작업 도구를 통해 모든 텍스트 기반 파일 형식을 지원합니다.
| 범주 | 언어/확장자 |
| -------- | --------------------------------------------------- |
| **웹** | JavaScript, TypeScript, HTML, CSS, SCSS, LESS |
| **백엔드** | Python, Java, Go, Rust, C, C++, C#, Ruby, PHP, Perl |
| **모바일** | Swift, Kotlin, Dart (Flutter), Objective-C |
| **함수형** | Haskell, Scala, Elixir, Clojure, F# |
| **스크립팅** | Bash, PowerShell, Zsh, Fish |
| **데이터** | SQL, R, Julia, MATLAB |
| 형식 | 일반적인 예시 |
| -------- | ------------------------------------------------------ |
| **JSON** | package.json, tsconfig.json, settings.json |
| **YAML** | docker-compose.yml, GitHub Actions, Kubernetes configs |
| **TOML** | Cargo.toml, pyproject.toml |
| **XML** | pom.xml, web.xml, config files |
| **INI** | .gitconfig, .editorconfig |
| **ENV** | .env files, environment configuration |
| **HCL** | Terraform configuration |
| 형식 | 사용 사례 |
| -------------------- | ------------------------------------- |
| **Markdown** | README.md, documentation files |
| **HTML** | Templates, web pages |
| **LaTeX** | Scientific documents, academic papers |
| **reStructuredText** | Python documentation |
| **AsciiDoc** | Technical documentation |
### 데이터 형식 [#데이터-형식]
| 형식 | 설명 |
| -------------- | ------------- |
| **CSV/TSV** | 표 형식 데이터 파일 |
| **텍스트 기반 데이터** | 로그 파일, 데이터 덤프 |
| **JSON/YAML** | 구조화된 데이터 교환 |
### 빌드 및 패키지 파일 [#빌드-및-패키지-파일]
| 파일 | 목적 |
| -------------------- | ----------- |
| **Makefile** | 빌드 자동화 |
| **package.json** | Node.js 의존성 |
| **requirements.txt** | Python 패키지 |
| **Gemfile** | Ruby gem |
| **Cargo.toml** | Rust 패키지 |
| **build.gradle** | Gradle 빌드 |
| 형식 유형 | 예시 | 편집 가능 여부 |
| ------------- | --------------------------- | ----------- |
| **이미지** | PNG, JPG, GIF, SVG (binary) | 직접 편집할 수 없음 |
| **동영상** | MP4, AVI, MOV | 직접 편집할 수 없음 |
| **컴파일된 바이너리** | EXE, DLL, SO | 직접 편집할 수 없음 |
| **아카이브** | ZIP, TAR, GZ | 직접 편집할 수 없음 |
| **Office 문서** | DOCX, XLSX, PPTX | 직접 편집할 수 없음 |
| **PDF** | PDF files | 직접 편집할 수 없음 |
바이너리 파일은 코드에서 참조할 수 있지만 파일 도구로 수정할 수는 없습니다.
***
## 프로그래밍 언어 지원 [#프로그래밍-언어-지원]
Verdent는 모든 텍스트 기반 프로그래밍 언어와 프레임워크를 폭넓게 지원합니다.
| 언어/프레임워크 | 지원 수준 | 일반적인 사용 사례 |
| ---------- | ----- | ------------------------------- |
| JavaScript | 우수 | 프론트엔드 로직, Node.js 백엔드, 도구 |
| TypeScript | 우수 | 타입 안전 웹 앱, 대규모 프로젝트 |
| React | 우수 | 컴포넌트 기반 UI, hooks, 상태 관리 |
| Vue | 우수 | Progressive web app, 싱글 파일 컴포넌트 |
| Angular | 우수 | 엔터프라이즈 애플리케이션, TypeScript 연동 |
| Svelte | 매우 좋음 | 컴파일된 컴포넌트, 반응형 프로그래밍 |
| HTML/CSS | 우수 | 마크업, 스타일링, 반응형 디자인 |
| SCSS/LESS | 우수 | 고급 스타일링, 변수, mixin |
| 언어/프레임워크 | 지원 수준 | 일반적인 사용 사례 |
| -------------------- | ----- | -------------------------- |
| Python | 우수 | APIs, 데이터 처리, 자동화 |
| Django/Flask/FastAPI | 우수 | 웹 프레임워크, REST APIs |
| Node.js/Express | 우수 | JavaScript 백엔드, 마이크로서비스 |
| Java/Spring | 우수 | 엔터프라이즈 애플리케이션, Spring Boot |
| Go | 우수 | 고성능 서비스, CLI |
| Rust | 매우 좋음 | 시스템 프로그래밍, 성능이 중요한 코드 |
| C/C++ | 매우 좋음 | 시스템, 임베디드, 게임 엔진 |
| C# / .NET | 우수 | Windows 앱, 웹 서비스, Unity |
| Ruby/Rails | 매우 좋음 | 웹 애플리케이션, 빠른 개발 |
| PHP | 좋음 | WordPress, Laravel, 레거시 앱 |
| 언어/프레임워크 | 지원 수준 | 일반적인 사용 사례 |
| ------------ | ----- | ------------------- |
| Swift | 우수 | iOS/macOS 네이티브 앱 |
| Kotlin | 우수 | Android 네이티브 앱 |
| Dart/Flutter | 우수 | 크로스 플랫폼 모바일 앱 |
| React Native | 우수 | JavaScript 기반 모바일 앱 |
| Objective-C | 좋음 | 레거시 iOS/macOS 앱 |
| 언어 | 지원 수준 | 일반적인 사용 사례 |
| ------ | ----- | --------------------------------------- |
| Python | 우수 | NumPy, Pandas, scikit-learn, TensorFlow |
| R | 매우 좋음 | 통계 분석, 데이터 시각화 |
| SQL | 우수 | 데이터베이스 쿼리, 스키마 설계 |
| Julia | 좋음 | 과학 계산, 수치 해석 |
| 언어 | 지원 수준 | 일반적인 사용 사례 |
| -------- | ----- | ----------------- |
| C | 매우 좋음 | 시스템 프로그래밍, 임베디드 |
| C++ | 매우 좋음 | 성능이 중요한 애플리케이션 |
| Rust | 매우 좋음 | 메모리 안전 시스템 프로그래밍 |
| Go | 우수 | 동시성 시스템, 클라우드 서비스 |
| Assembly | 좋음 | 로우레벨 최적화, 디버깅 |
**지원 품질:** 일반적으로 많이 쓰이는 언어(JavaScript, Python, TypeScript)는 방대한 학습 데이터 덕분에 더 강력하게 지원됩니다. 덜 일반적이거나 도메인 특화 언어는 지원 품질이 낮을 수 있지만 계속 사용할 수 있습니다.
***
## 사용 제한 및 모범 사례 [#사용-제한-및-모범-사례]
### file\_read 효율성 [#file_read-효율성]
**모범 사례:**
* 컨텍스트 과부하를 피하려면 500줄이 넘는 파일에는 줄 범위를 사용합니다
* 작업에 필요한 관련 섹션만 읽습니다
* 큰 파일의 경우 먼저 `grep_content`로 관련 줄 번호를 식별합니다
```bash
# Good: Read specific section
file_read("large-config.json", start_line=100, max_lines=50)
# Less efficient: Read entire large file
file_read("large-config.json") # May consume excessive context
```
***
### file\_edit 정밀성 [#file_edit-정밀성]
**모범 사례:**
* 편집 실패를 피하려면 정확한 문자열 일치를 확인합니다
* 비슷한 변경이 여러 개라면 `multiple=true` 플래그를 사용합니다
* 편집 전에 파일 경로를 확인합니다
***
### file\_write 안전성 [#file_write-안전성]
**모범 사례:**
* 실수로 덮어쓰는 일을 막기 위해 경로를 다시 확인합니다
* 새 파일 또는 전체 재작성에만 사용합니다
* 수정에는 안전을 위해 `file_edit`를 우선 사용합니다
### glob 패턴 구체성 [#glob-패턴-구체성]
**모범 사례:**
* 범위를 좁히려면 구체적인 패턴을 사용합니다: `**/*` 대신 `src/**/*.ts`
* 제외 패턴으로 디렉터리를 제외합니다: `!**/node_modules/**`
* 출력이 과도해지지 않도록 결과 수를 제한합니다
```bash
# Good: Specific scope
glob("src/components/**/*.tsx", max_results=50)
# Less efficient: Too broad
glob("**/*") # Returns thousands of results
```
***
### grep 전략 [#grep-전략]
**권장 워크플로:**
1. `grep_file`로 관련 파일을 식별합니다
2. `file_read`로 특정 파일을 읽습니다
3. 주변 컨텍스트가 필요할 때 `grep_content`를 사용합니다
**성능 팁:**
* 정규식 패턴은 리터럴 문자열보다 더 오래 걸릴 수 있습니다
* 대소문자 무시 검색은 더 느립니다
* 컨텍스트 줄(`-A`, `-B`)은 필요한 만큼만 제한합니다
### bash 모범 사례 [#bash-모범-사례]
**안전한 명령 실행:**
* 명령 설명에는 명확한 요약을 제공합니다
* 오래 실행되는 작업에는 적절한 타임아웃을 설정합니다
* 의존 관계가 있는 명령은 `&&`로 체이닝합니다
* 파괴적인 명령은 신중하게 검토합니다(rm, drop, truncate)
```bash
# Good: Clear summary, reasonable timeout
bash("npm run build", timeout=120000, summary="Build production bundle")
# Good: Chained dependencies
bash("npm install && npm run test", timeout=180000)
```
***
### 보안 고려 사항 [#보안-고려-사항]
**중요한 안전 규칙:**
* 명령은 사용자 권한으로 실행됩니다
* 신뢰할 수 없는 명령은 절대 실행하지 않습니다
* 공유 코드베이스에서는 검토를 위해 Manual Accept Mode를 사용합니다
* 자격 증명이나 민감한 데이터를 노출하는 명령은 피합니다
공유 코드베이스나 프로덕션 환경에서 작업할 때는 항상 Manual Accept Mode에서 bash 명령을 검토합니다.
### 서브에이전트 위임 효율성 [#서브에이전트-위임-효율성]
**서브에이전트를 사용할 때:**
* **Explorer:** 코드베이스 검색, 아키텍처 질문(메인 컨텍스트 절약)
* **Verifier:** 빠른 검증 확인(격리된 검증)
* **Code-reviewer:** 보안 및 품질 리뷰(상세 분석)
* **General:** 복잡한 여러 단계 작업(병렬 실행)
**모범 사례:**
활성 개발 작업을 위한 메인 대화 컨텍스트를 보존하려면 탐색 및 조사 작업을 서브에이전트에 위임합니다.
***
### 컨텍스트 관리 [#컨텍스트-관리]
**전략적인 도구 사용:**
* 파일은 전략적으로 읽습니다. 필요한 것만 읽습니다
* 백그라운드 조사에는 서브에이전트를 사용합니다
* 긴 세션 동안 컨텍스트 사용량을 모니터링합니다
* 복잡한 작업은 todo\_update로 단계별로 나눕니다
**효율적인 워크플로:**
1. **계획:** glob/grep으로 범위를 식별합니다
2. **읽기:** 관련 파일/섹션만 읽습니다
3. **실행:** 적절한 경우 서브에이전트에 위임합니다
4. **검증:** Verifier 서브에이전트로 빠르게 확인합니다
### 파일 크기 제한 [#파일-크기-제한]
**큰 파일 처리:**
매우 큰 파일(10,000줄 초과)은 다음을 피하기 위해 섹션별로 읽어야 합니다:
* 컨텍스트 창 고갈
* 느린 응답 시간
* 메모리 문제
최적의 성능을 유지하려면 500줄이 넘는 파일에는 항상 `file_read`로 줄 범위를 사용합니다.
***
### 도구 타임아웃 기본값 [#도구-타임아웃-기본값]
**도구 제한:**
* **Bash 타임아웃:** 최대 120초(2분)
* **파일 작업:** 크기 제한 없음(큰 파일은 자동으로 배치 단위로 읽음)
* **큰 파일 처리:** 256KB를 초과하는 파일은 처음 256KB 콘텐츠만 반환합니다
* **검색 결과:** `glob` 또는 `grep_content` 결과에는 제한이 없습니다
* **동시 서브에이전트:** 병렬 실행 제한 없음
**타임아웃 설정:**
* 오래 실행되는 작업에는 명시적인 타임아웃을 설정합니다
* 멈춘 프로세스가 있는지 모니터링합니다
* 2분 타임아웃을 초과하는 명령은 종료됩니다
***
### 동시 작업 [#동시-작업]
**병렬 실행:**
복잡한 작업을 더 빠르게 처리하기 위해 여러 서브에이전트를 병렬로 실행할 수 있습니다. 메인 에이전트가 조율을 자동으로 처리합니다.
**성능상 이점:**
* 여러 단계 작업의 총 실행 시간 단축
* 효율적인 리소스 활용
* 자동 작업 오케스트레이션
* 동시 서브에이전트 수 제한 없음
***
## 함께 보기 [#함께-보기]
전문 에이전트에 대해 알아봅니다
모드로 도구 실행을 제어합니다