도구 시스템 레퍼런스

file_read

기능:

• 전체 파일 내용 또는 특정 줄 범위를 읽습니다
• 수정 전에 코드를 이해하는 데 필수적입니다
• 범위 지정으로 큰 파일을 효율적으로 처리합니다

사용 사례:

• 편집 전에 설정 파일 읽기
• 기존 구현 패턴 이해하기
• 커버리지를 이해하기 위해 테스트 파일 검토하기

예시:

# 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

기능:

• 정확한 문자열 일치를 사용해 텍스트를 정밀하게 교체합니다
• multiple 플래그로 여러 교체 작업을 수행합니다
• 파일 구조와 서식을 보존합니다

사용 사례:

• 함수 구현 업데이트
• 설정 값 수정
• 여러 파일에서 변수 이름 리팩터링

모범 사례: 대상이 명확한 변경에 사용합니다. 전체를 다시 작성하려면 대신 file_write를 사용합니다.

file_write

기능:

• 새 파일을 처음부터 생성합니다
• 기존 파일 내용을 완전히 교체합니다
• 모든 텍스트 기반 형식을 처리합니다

사용 사례:

• 새 컴포넌트 또는 모듈 생성
• 설정 파일 생성
• 테스트 파일 작성

경고: 기존 파일을 완전히 덮어씁니다. 부분 수정에는 file_edit를 사용합니다.

glob

기능:

• 패턴과 일치하는 파일 찾기: **/*.ts, src/**/*.js
• 디렉터리 경로로 필터링합니다
• 제외 패턴으로 결과 범위를 좁힙니다
• 결과 수를 제어합니다

사용 사례:

• 프로젝트의 모든 컴포넌트 찾기
• 테스트 파일 찾기
• 여러 디렉터리에서 설정 파일 식별하기

예시 패턴:

**/*.tsx          # All TypeScript React files
src/**/*.test.js  # All test files in src
**/config.*       # All config files anywhere

grep_content

기능:

• 정규식 패턴으로 파일 내용을 검색합니다
• 일치 항목 앞/뒤의 컨텍스트 줄을 표시합니다(-B, -A 플래그)
• 대소문자 무시 검색을 지원합니다
• Glob 패턴을 사용해 파일 유형으로 필터링합니다

사용 사례:

• 함수 정의 찾기
• API 엔드포인트 구현 찾기
• 특정 오류 메시지 검색하기
• 보안 패턴 식별하기

예시:

# 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_content보다 빠릅니다
• 정규식 패턴을 지원합니다
• 파일 유형에 대한 Glob 필터링을 지원합니다

사용 사례:

• 리팩터링이 필요한 파일 식별하기
• 특정 모듈을 가져오는 파일 찾기
• 사용 중단된 패턴이 있는 파일 찾기

모범 사례: 먼저 grep_file로 관련 파일을 식별한 다음, 자세히 확인하려면 file_read를 사용합니다.

list_dir

기능:

• 디렉터리 계층 구조를 표시합니다
• max_depth 매개변수로 깊이를 제어합니다
• 제외 패턴으로 출력을 필터링합니다

사용 사례:

• 프로젝트 구조 이해하기
• 디렉터리 구성이 올바른지 확인하기
• 특정 하위 디렉터리 찾기

bash

기능:

• 셸 명령을 실행합니다
• 최대 타임아웃: 120초(2분, 하드 리밋)
• 의존성이 있는 경우 &&로 명령을 체이닝합니다
• 명확성을 위해 설명 요약을 제공합니다

사용 사례:

• 테스트 실행
• 프로젝트 빌드
• 의존성 설치
• Git 작업
• 데이터베이스 마이그레이션

예시:

# 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

기능:

• 격리된 컨텍스트를 가진 전문 서브에이전트를 실행합니다
• 유형: explorer, verifier, code-reviewer
• 메인 컨텍스트를 오염시키지 않고 복잡한 작업을 위임합니다
• 효율성을 위해 서브에이전트를 병렬로 실행합니다

사용 사례:

• explorer: 대규모 코드베이스에서 패턴 검색
• verifier: 구현 로직 검증
• code-reviewer: 보안 및 품질 평가

모범 사례: 메인 대화 컨텍스트를 보존하기 위해 탐색성 조사는 Explorer 서브에이전트에 위임합니다.

todo_update

기능:

• 작업 목록을 생성하고 관리합니다
• 작업 상태를 업데이트합니다(pending, in_progress, completed)
• 복잡한 구현 전반의 진행 상황을 추적합니다

사용 사례:

• 여러 단계로 이루어진 기능 분해
• 리팩터링 진행 상황 추적
• 마이그레이션 작업 관리

web_search

기능:

• 인터넷 검색 엔진에 쿼리합니다
• 결과 수를 제어합니다
• 최신성(최근 일수)으로 필터링합니다

사용 사례:

• 익숙하지 않은 API의 문서 찾기
• 오류 메시지 조사하기
• 최신 모범 사례 확인하기

web_fetch

기능:

• 웹 페이지 내용을 가져옵니다
• 특정 쿼리로 콘텐츠를 분석합니다
• 구조화된 정보를 추출합니다

사용 사례:

• 문서 페이지 읽기
• API 문서 분석
• 튜토리얼에서 예시 추출하기

데이터 형식

빌드 및 패키지 파일

file_read 효율성

모범 사례:

• 컨텍스트 과부하를 피하려면 500줄이 넘는 파일에는 줄 범위를 사용합니다
• 작업에 필요한 관련 섹션만 읽습니다
• 큰 파일의 경우 먼저 grep_content로 관련 줄 번호를 식별합니다

# 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 정밀성

모범 사례:

• 편집 실패를 피하려면 정확한 문자열 일치를 확인합니다
• 비슷한 변경이 여러 개라면 multiple=true 플래그를 사용합니다
• 편집 전에 파일 경로를 확인합니다

file_write 안전성

모범 사례:

• 실수로 덮어쓰는 일을 막기 위해 경로를 다시 확인합니다
• 새 파일 또는 전체 재작성에만 사용합니다
• 수정에는 안전을 위해 file_edit를 우선 사용합니다

glob 패턴 구체성

모범 사례:

• 범위를 좁히려면 구체적인 패턴을 사용합니다: **/* 대신 src/**/*.ts
• 제외 패턴으로 디렉터리를 제외합니다: !**/node_modules/**
• 출력이 과도해지지 않도록 결과 수를 제한합니다

# Good: Specific scope
glob("src/components/**/*.tsx", max_results=50)

# Less efficient: Too broad
glob("**/*")  # Returns thousands of results

grep 전략

권장 워크플로:

1. grep_file로 관련 파일을 식별합니다
2. file_read로 특정 파일을 읽습니다
3. 주변 컨텍스트가 필요할 때 grep_content를 사용합니다

성능 팁:

• 정규식 패턴은 리터럴 문자열보다 더 오래 걸릴 수 있습니다
• 대소문자 무시 검색은 더 느립니다
• 컨텍스트 줄(-A, -B)은 필요한 만큼만 제한합니다

bash 모범 사례

안전한 명령 실행:

• 명령 설명에는 명확한 요약을 제공합니다
• 오래 실행되는 작업에는 적절한 타임아웃을 설정합니다
• 의존 관계가 있는 명령은 &&로 체이닝합니다
• 파괴적인 명령은 신중하게 검토합니다(rm, drop, truncate)

# 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를 사용합니다
• 자격 증명이나 민감한 데이터를 노출하는 명령은 피합니다

서브에이전트 위임 효율성

서브에이전트를 사용할 때:

• Explorer: 코드베이스 검색, 아키텍처 질문(메인 컨텍스트 절약)
• Verifier: 빠른 검증 확인(격리된 검증)
• Code-reviewer: 보안 및 품질 리뷰(상세 분석)
• General: 복잡한 여러 단계 작업(병렬 실행)

모범 사례: 활성 개발 작업을 위한 메인 대화 컨텍스트를 보존하려면 탐색 및 조사 작업을 서브에이전트에 위임합니다.

컨텍스트 관리

전략적인 도구 사용:

• 파일은 전략적으로 읽습니다. 필요한 것만 읽습니다
• 백그라운드 조사에는 서브에이전트를 사용합니다
• 긴 세션 동안 컨텍스트 사용량을 모니터링합니다
• 복잡한 작업은 todo_update로 단계별로 나눕니다

효율적인 워크플로:

1. 계획: glob/grep으로 범위를 식별합니다
2. 읽기: 관련 파일/섹션만 읽습니다
3. 실행: 적절한 경우 서브에이전트에 위임합니다
4. 검증: Verifier 서브에이전트로 빠르게 확인합니다

파일 크기 제한

큰 파일 처리: 매우 큰 파일(10,000줄 초과)은 다음을 피하기 위해 섹션별로 읽어야 합니다:

• 컨텍스트 창 고갈
• 느린 응답 시간
• 메모리 문제

도구 타임아웃 기본값

도구 제한:

• Bash 타임아웃: 최대 120초(2분)
• 파일 작업: 크기 제한 없음(큰 파일은 자동으로 배치 단위로 읽음)
• 큰 파일 처리: 256KB를 초과하는 파일은 처음 256KB 콘텐츠만 반환합니다
• 검색 결과: glob 또는 grep_content 결과에는 제한이 없습니다
• 동시 서브에이전트: 병렬 실행 제한 없음

타임아웃 설정:

• 오래 실행되는 작업에는 명시적인 타임아웃을 설정합니다
• 멈춘 프로세스가 있는지 모니터링합니다
• 2분 타임아웃을 초과하는 명령은 종료됩니다

동시 작업

병렬 실행: 복잡한 작업을 더 빠르게 처리하기 위해 여러 서브에이전트를 병렬로 실행할 수 있습니다. 메인 에이전트가 조율을 자동으로 처리합니다.

성능상 이점:

• 여러 단계 작업의 총 실행 시간 단축
• 효율적인 리소스 활용
• 자동 작업 오케스트레이션
• 동시 서브에이전트 수 제한 없음