AI Coding Assistant의 SW Tool SDK 명세

Claude Code · Anthropic API · GitHub Copilot의 호출 가능 도구 전체 정리

AI Coding Assistant가 사용자 질의를 처리하기 위해 호출하는 SW 도구의 전체 명세를 정리한다. Claude Code 네이티브 도구, Anthropic Claude API Tool Use 스펙, GitHub Copilot 도구를 역할·동작 방식·공식 문서 링크와 함께 비교한다.

Agent
Architecture
저자

Kwangmin Kim

공개

2026년 03월 29일

1 왜 SW Tool이 필요한가

LLM은 텍스트 생성 모델이다. 파일을 직접 읽거나, 터미널 명령을 실행하거나, 웹에서 정보를 검색하는 능력은 모델 자체에 내재되어 있지 않다. 이 간극을 메우는 것이 SW Tool(소프트웨어 도구)이다.

사용자 요청
    ↓
LLM: 요청 분석 → 필요한 Tool 식별
    ↓
Tool 호출 (Read, Bash, WebSearch 등)
    ↓
Tool 실행 결과 → LLM에 반환
    ↓
결과를 바탕으로 최종 응답 생성

Tool은 LLM이 단순 텍스트 생성기를 넘어 실제 시스템을 조작하는 에이전트가 되도록 하는 핵심 메커니즘이다.

2 Claude Code 네이티브 도구

Claude Code CLI는 사용자 요청 처리를 위해 다음 도구들을 직접 호출한다. 각 도구는 고유한 역할과 파라미터 스펙을 갖는다.

도구 승인 모델

각 도구 호출은 사용자 설정한 권한 모드에 따라 자동 승인 또는 사용자 확인 절차를 거친다. 파일 삭제·git push 등 비가역적 작업은 명시적 승인이 필요하다.

2.1 파일 시스템 도구

도구 역할 핵심 파라미터
Read 파일 내용 읽기. PDF·이미지·노트북 지원 file_path, offset, limit, pages
Write 파일 생성·완전 덮어쓰기 file_path, content
Edit 파일 내 정확한 문자열 치환 file_path, old_string, new_string, replace_all
Glob glob 패턴으로 파일 검색 pattern, path
Grep ripgrep 기반 콘텐츠 검색 pattern, path, glob, type, output_mode
NotebookEdit Jupyter 노트북 셀 편집 (셀 인덱스, 내용)

Read 는 단순 텍스트 파일 외에도 PDF(페이지 범위 지정), 이미지(멀티모달 처리), .ipynb 노트북(셀+출력 통합)을 읽는다. offset과 limit으로 대형 파일의 일부만 읽어 토큰을 절약한다.

Edit 는 diff 방식으로 동작한다. old_string이 파일 내에서 유일해야 하며, 중복이 있으면 더 많은 컨텍스트를 포함해 unique하게 만들어야 한다. replace_all: true 옵션으로 전체 치환도 가능하다.

Grep 은 내부적으로 ripgrep을 사용한다. output_mode를 files_with_matches(기본), content, count 중 선택한다. 멀티라인 패턴은 multiline: true로 활성화한다.

2.2 실행 도구

도구 역할 특이사항
Bash 셸 명령 실행 타임아웃 최대 10분, run_in_background 지원

Bash 는 bash 셸 환경에서 명령을 실행한다. 작업 디렉토리는 세션 간 유지되나 셸 상태(환경 변수 등)는 각 호출마다 초기화된다. run_in_background: true로 실행하면 완료 시 알림을 받고 다른 작업을 병행할 수 있다.

Bash vs 전용 도구

파일 읽기에 cat을 사용하는 것보다 Read 도구가 권장된다. 전용 도구는 권한 모델·감사 로그·UX 처리가 최적화되어 있다. 구체적으로, Read는 파일 크기에 따라 자동으로 페이징하여 토큰 낭비를 막고, 권한 모드에 따라 읽기 작업을 감사 로그에 기록하며, 이미지나 PDF처럼 바이너리 파일도 멀티모달로 처리한다. cat으로 Bash를 통해 읽으면 이 세 가지 이점이 모두 없어진다. Bash는 셸 실행이 꼭 필요한 경우에만 사용한다.

2.3 검색 도구

도구 역할 핵심 파라미터
WebSearch 웹 검색 query
WebFetch 특정 URL 콘텐츠 가져오기 url

WebSearch 는 외부 검색 엔진을 호출하여 최신 정보, 공식 문서, 패키지 버전 등을 조회한다.

WebFetch 는 사용자가 제공한 URL의 페이지 콘텐츠를 직접 읽는다. 단, 확인되지 않은 URL은 생성하지 않으며 사용자가 제공한 URL만 사용한다.

2.4 에이전트·오케스트레이션 도구

도구 역할 사용 시점
Agent 서브에이전트(하위 프로세스) 실행 복잡한 멀티스텝 태스크, 독립적 병렬 작업
Skill 슬래시 커맨드 스킬 실행 /commit, /review-pr 등 정의된 스킬
ToolSearch 지연 로드된 도구 스키마 조회 사용 가능한 도구 목록 확인, 스키마 페치
AskUserQuestion 사용자에게 질문 판단 불가 상황에서 선택지 요청

Agent 도구는 전문화된 서브에이전트를 생성한다:

general-purpose  — 복잡한 연구·코드 탐색·멀티스텝 태스크
Explore          — 코드베이스 탐색 전용 (빠른 파일/키워드 검색)
Plan             — 구현 계획 설계 (아키텍처 설계, 트레이드오프 분석)
claude-code-guide — Claude Code/API/SDK 관련 질문 응답
statusline-setup — status line 설정

서브에이전트는 독립적인 컨텍스트 창에서 실행되어 메인 컨텍스트를 보호한다. isolation: "worktree" 옵션으로 임시 git worktree에서 격리 실행도 가능하다.

2.5 태스크 관리 도구

도구 역할
TaskCreate 새 태스크 생성 (진행 상황 추적)
TaskGet 특정 태스크 상태 조회
TaskList 태스크 목록 조회
TaskUpdate 태스크 상태 업데이트 (in_progress, completed)
TaskStop 태스크 중단
TaskOutput 태스크 출력 조회

태스크 도구는 장기 작업의 진행 상황을 추적하고 사용자에게 투명하게 보여주기 위해 사용된다.

예를 들어 “대규모 코드베이스 전체 리팩토링”처럼 수십 개 파일을 순서대로 수정하는 작업에서 TaskCreate로 태스크를 생성하고, 각 파일 수정이 끝날 때마다 TaskUpdate로 상태를 갱신하면 사용자가 진행 상황을 실시간으로 추적할 수 있다. 태스크 도구가 없으면 에이전트가 내부적으로 무슨 작업을 하고 있는지 사용자가 알 수 없어, 오랜 작업 중간에 개입하거나 중단시킬 타이밍을 잡기 어렵다.

2.6 스케줄링·플래닝 도구

도구 역할
CronCreate 크론 잡 생성 (정기 실행)
CronList 크론 잡 목록 조회
CronDelete 크론 잡 삭제
RemoteTrigger 원격 트리거 실행
EnterPlanMode 계획 모드 진입 (실행 없이 계획만)
ExitPlanMode 계획 모드 종료
EnterWorktree git worktree 진입
ExitWorktree git worktree 종료

EnterPlanMode 는 코드 수정 없이 구현 계획만 작성하는 모드이다. 사용자가 실행 전 계획을 검토하고 방향을 수정할 수 있게 한다.

CronCreate 는 정기 실행이 필요한 작업(예: 매일 자정 테스트 실행, 주 1회 의존성 버전 점검)을 스케줄링한다. 에이전트를 수동으로 매번 깨울 필요 없이 반복 작업을 자동화한다. EnterWorktree/ExitWorktree 는 실험적 변경을 main 브랜치에 영향을 주지 않고 격리된 git worktree에서 수행할 때 사용한다. 리스크가 큰 리팩토링이나 대규모 자동화 작업을 안전하게 실행하는 보호막 역할을 한다.

3 Anthropic Claude API Tool Use

Claude API는 모델이 외부 함수(tool)를 호출할 수 있는 Tool Use 기능을 제공한다. 개발자가 툴 스펙을 정의하면 Claude가 적절한 시점에 호출 결정을 내린다.

공식 문서: docs.anthropic.com/en/docs/build-with-claude/tool-use

3.1 도구 정의 스키마

import anthropic

client = anthropic.Anthropic()

# 도구 정의: JSON Schema 기반
tools = [
    {
        "name": "get_weather",
        "description": "지정한 위치의 현재 날씨를 조회한다.",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "도시명 또는 위도/경도 (예: '서울' 또는 '37.5665,126.9780')"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "온도 단위"
                }
            },
            "required": ["location"]
        }
    }
]

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    tools=tools,
    messages=[
        {"role": "user", "content": "서울 날씨 알려줘"}
    ]
)

3.2 Tool Use 흐름

1. 사용자 메시지 → Claude
2. Claude: stop_reason="tool_use" → tool_use 블록 반환
3. 개발자: 실제 함수 실행 → 결과 획득
4. 결과를 tool_result로 다시 전달
5. Claude: 최종 텍스트 응답 생성
# Claude가 tool_use를 요청한 경우 처리
if response.stop_reason == "tool_use":
    tool_use = next(b for b in response.content if b.type == "tool_use")
    tool_name = tool_use.name       # "get_weather"
    tool_input = tool_use.input     # {"location": "서울"}

    # 실제 함수 실행 (개발자 구현)
    result = get_weather(**tool_input)

    # 결과를 모델에 전달
    follow_up = client.messages.create(
        model="claude-opus-4-6",
        max_tokens=1024,
        tools=tools,
        messages=[
            {"role": "user",      "content": "서울 날씨 알려줘"},
            {"role": "assistant", "content": response.content},
            {
                "role": "user",
                "content": [
                    {
                        "type": "tool_result",
                        "tool_use_id": tool_use.id,
                        "content": str(result)
                    }
                ]
            }
        ]
    )

3.3 tool_choice 제어

값 동작
{"type": "auto"} 모델이 판단 (기본값)
{"type": "any"} 도구 중 하나 반드시 사용
{"type": "tool", "name": "get_weather"} 지정 도구 강제 사용
{"type": "none"} 도구 사용 금지

3.4 내장 도구 (Computer Use)

Claude API는 컴퓨터 화면을 직접 제어하는 내장 도구도 제공한다:

# Computer Use (beta)
tools = [
    {"type": "computer_20241022", "name": "computer", "display_width_px": 1024, "display_height_px": 768},
    {"type": "text_editor_20241022", "name": "str_replace_editor"},
    {"type": "bash_20241022",        "name": "bash"}
]
내장 도구 기능
computer 스크린샷, 마우스 클릭, 키 입력, 커서 이동
str_replace_editor 파일 보기, 생성, 문자열 치환
bash 터미널 명령 실행

공식 문서: docs.anthropic.com/en/docs/build-with-claude/computer-use

4 GitHub Copilot의 SW Tools

GitHub Copilot은 VS Code·JetBrains·GitHub.com 등 다양한 환경에서 도구를 제공한다. 크게 Chat Participants, Chat Variables, Agent Mode Tools로 구분된다.

공식 문서: docs.github.com/en/copilot

4.1 Chat Participants (@ 명령어)

Chat Participant는 특정 컨텍스트에 특화된 에이전트이다. @이름 형식으로 호출한다.

Participant 역할 사용 예
@workspace 프로젝트 전체 코드베이스 탐색·분석 @workspace 이 프로젝트의 인증 흐름 설명해줘
@vscode VS Code 설정·명령·확장 관련 작업 @vscode 테마 변경하는 방법
@terminal 터미널 명령 제안·디버깅 @terminal 이 오류 어떻게 고쳐?
@github GitHub 리포지토리·PR·이슈 조회 @github 최근 PR 목록 보여줘

@workspace 는 가장 강력한 participant로, 프로젝트 전체를 인덱싱하여 파일 간 관계, 함수 호출 체인, 패턴 등을 파악한다. 코드베이스 규모가 크면 내부적으로 벡터 검색을 활용한다.

공식 문서: code.visualstudio.com/docs/copilot/chat/copilot-chat

4.2 Chat Variables (# 참조)

Chat Variable은 특정 컨텍스트를 대화에 직접 포함시키는 참조 메커니즘이다.

Variable 포함되는 컨텍스트
#file 지정 파일 전체 내용
#selection 에디터에서 현재 선택된 코드
#codebase 코드베이스 전체 (임베딩 기반 검색)
#editor 현재 열린 파일 전체
#terminalLastCommand 마지막 터미널 명령과 출력
#terminalSelection 터미널에서 선택된 텍스트
#VSCodeAPI VS Code Extension API 문서

사용 예시:

// 특정 파일을 컨텍스트로 포함
#file:src/auth.ts 이 파일의 토큰 갱신 로직 설명해줘

// 현재 선택 코드에 대한 설명
#selection 이 코드를 리팩토링해줘

// 마지막 터미널 오류 디버깅
#terminalLastCommand 이 오류 원인이 뭐야?

4.3 Copilot Agent Mode (자율 도구 실행)

VS Code 1.99+에서 제공하는 Agent Mode는 Copilot이 사용자 승인 하에 파일 조작·터미널 실행 등을 자율 수행한다.

도구 역할
read_file 파일 내용 읽기
write_file 파일 생성·수정
create_directory 디렉토리 생성
delete_file 파일 삭제
run_in_terminal 터미널 명령 실행
search_codebase 코드베이스 의미론적 검색
get_errors 에디터 진단(오류·경고) 수집
list_directory 디렉토리 목록 조회

각 도구 실행 전 사용자가 확인할 수 있으며, “계속” 또는 “모두 허용” 선택으로 일괄 승인도 가능하다.

공식 문서: code.visualstudio.com/docs/copilot/copilot-edits

4.4 Copilot 내장 슬래시 커맨드

커맨드 동작
/explain 선택 코드 설명
/fix 버그 수정 제안
/tests 테스트 코드 생성
/doc 문서 주석 생성
/new 새 파일·프로젝트 스캐폴딩
/clear 대화 초기화
/help 도움말

4.5 Copilot Extensions와 MCP

GitHub Copilot은 2025년부터 MCP(Model Context Protocol) 서버를 통해 외부 서비스와 연동한다. settings.json에 MCP 서버를 등록하면 Copilot이 해당 서버의 도구를 자동 탐색하여 사용한다.

// .vscode/settings.json
{
  "github.copilot.chat.mcp.enabled": true,
  "mcp": {
    "servers": {
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": { "GITHUB_TOKEN": "${env:GITHUB_TOKEN}" }
      },
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
      }
    }
  }
}

공식 문서: docs.github.com/en/copilot/customizing-copilot/extending-the-capabilities-of-github-copilot

5 도구 체계 비교

관점 Claude Code Claude API Tool Use GitHub Copilot
도구 정의 주체 Anthropic (내장) 개발자 (JSON Schema) Microsoft + 사용자 (MCP)
실행 환경 CLI / 로컬 셸 서버 (API 호출) IDE (VS Code, JetBrains 등)
파일 시스템 접근 Read/Write/Edit/Glob/Grep 개발자 구현 Agent Mode 도구
웹 검색 WebSearch/WebFetch 개발자 구현 @workspace (인덱싱)
서브에이전트 Agent 도구 (병렬 실행) 직접 구현 필요 없음 (단일 에이전트)
스케줄링 CronCreate 등 외부 인프라 필요 없음
외부 서비스 연동 MCP 서버 (자동) 개발자 구현 MCP + Extensions
승인 모델 권한 모드별 자동/수동 개발자 구현 실행 전 사용자 확인

5.1 어떤 경우에 무엇을 선택하는가

코드베이스 탐색·수정·자동화가 주 목적
    → Claude Code (네이티브 도구의 조합이 가장 강력)

API 기반 제품에 tool calling 추가
    → Anthropic Claude API Tool Use (유연한 정의, 서버 사이드)

IDE 내 대화형 코딩 보조
    → GitHub Copilot (@workspace로 코드베이스 파악, Agent Mode로 자율 실행)

기존 외부 서비스와 에이전트 연동
    → MCP 서버 (Claude Code·Copilot 모두 지원하는 표준 프로토콜)

6 관련 주제

선행 지식

후속 주제

다른 카테고리 연결

Subscribe

Enjoy this blog? Get notified of new posts by email: