byteforce

CPN 한국어 자습서 · 러닝패스 2 / 4 — Building with the Claude API

도구 사용

텍스트 편집 도구

The text edit tool

지금까지는 우리가 도구를 직접 작성했지만, Claude에 기본 내장된 도구가 하나 있습니다 — 텍스트 편집 도구입니다. 파일을 열어 읽고, 일부 텍스트를 보거나 바꾸고, 새 파일을 만들고, 되돌리는 등 텍스트 편집기로 할 일을 거의 다 할 수 있습니다. 다만 스키마만 내장이고, 실제 동작 함수는 우리가 작성해야 합니다.

전체 내레이션영상 나레이션 한국어 번역 (전체)›

Stephen Grider · Anthropic 기술 스태프

이 모듈에서 보았듯, 보통은 우리 개발자가 Claude에 넘길 도구를 모두 직접 작성합니다. 그런데 Claude가 기본으로 접근할 수 있는 도구가 하나 있습니다 — Text Editor 도구로, Claude에 직접 내장돼 있습니다. 이 도구는 표준 텍스트 편집기에서 할 수 있는 거의 모든 일을 Claude에 부여합니다. 예컨대 파일이나 디렉터리를 열어 내용을 읽고, 파일의 특정 텍스트 범위를 보고, 텍스트를 추가·교체하고, 새 파일을 만들고, 되돌리기(undo)를 할 수 있습니다. 사실상 일반 텍스트 편집기에서 하는 모든 것입니다. 그래서 Claude의 능력이 크게 확장되고, 거의 곧바로 소프트웨어 엔지니어처럼 동작하게 됩니다.

다만 텍스트 편집 도구는 조금 헷갈리므로 다이어그램으로 정리하겠습니다. 첫째로 이해할 점 — 실제로 Claude에 내장된 것은 JSON 스키마 부분뿐입니다. 기억하세요, 도구를 쓰려면 우리는 두 가지를 작성해야 합니다. 왼쪽에는 JSON 스키마 명세 — Claude에 전달돼 어떤 도구가 있고 어떤 인자가 필요한지 알려 줍니다. 오른쪽에는 그 스키마와 짝을 이루는 도구 함수 구현 — Claude가 도구를 쓰려 할 때 실제로 호출되는, 우리 코드베이스 안의 진짜 함수입니다. 두 쪽을 모두 우리가 써야 했습니다.

텍스트 편집 도구를 쓸 때, 실제로 제공되거나 내장된 것은 JSON 스키마뿐입니다 — 이 도구를 어떻게 쓰는지 Claude에 알려 주는 지시 모음이죠. Claude의 모든 텍스트 편집 요청을 처리할 실제 구현은 존재하지 않습니다. 그건 우리가 코드베이스 안에 직접 작성해야 합니다. 즉 Claude가 새 파일을 만들고 싶다며 tool_use를 보내오면, 실제로 하드 드라이브 어딘가에 새 파일을 만드는 함수를 우리가 제공해야 합니다. 그래서 텍스트 편집 도구는 공짜가 아니며, 우리 쪽에서 몇 가지 함수를 작성하는 약간의 수고가 듭니다.

Jupyter 노트북으로 가서 시연하겠습니다. 005 Text Editor Tool 노트북(강의에 첨부)입니다. 지금까지 쓰던 헬퍼 코드가 거의 그대로 있고, 세 번째 셀(맨 위에 'implementation of the text editor tool' 주석)에는 코드가 아주 많습니다. 미리 만들어 둔 클래스로, 텍스트 편집 도구에 필요한 모든 함수를 담고 있습니다 — 즉 '우리가 작성해야 하는 구현' 조각입니다. 안에는 파일·디렉터리 내용을 보는 view, 파일 안 문자열을 바꾸는 str_replace, 파일을 만드는 create 같은 메서드가 들어 있습니다.

다음으로 짚을 셀은 'make the text edit schema based upon the model version being used'입니다. 여기서 살짝 헷갈리는 부분 — 스키마가 내장이라 포함하지 않아도 된다고 했지만, 사실 작은 단서가 있습니다. 요청을 보낼 때 텍스트 편집 도구를 쓰려면 아주 작은 스키마를 포함해야 합니다. 그 안의 정확한 type 문자열에는 날짜가 들어 있고, 이 값은 사용하는 Claude의 정확한 모델 버전에 따라 달라집니다. 그래서 함수에서 모델 버전을 확인해 알맞은 날짜의 스키마를 돌려줍니다(예: Claude 3.7 Sonnet과 3.5는 날짜가 다릅니다).

이 아주 작은 스키마를 Claude에 보내면, 내부적으로 훨씬 큰 스키마로 자동 확장됩니다. Claude는 우리가 보낸 작은 스텁 스키마(name과 정확한 type)를 보고, 뒤에서 그것을 텍스트 편집 도구 사용법을 자세히 나열한 훨씬 큰 스키마로 바꿔 받습니다.

이제 시연입니다. 노트북과 같은 폴더에 main.py를 새로 만들고, 그 안에 'hi there'를 출력하는 간단한 greeting 함수를 넣고 저장합니다. 노트북 맨 아래에는 빈 user 메시지를 추가해 run_conversation에 보내는 셀을 두었습니다. Claude에게 ./main.py 파일을 열어 내용을 요약해 달라고 요청하고 실행합니다. 응답을 보면 Claude가 실제로 그 파일의 내용을 받아 요약합니다. 메시지 목록을 보면 tool_use 블록이 있는데, Claude가 main.py 내용을 보려고(view) 요청한 것입니다. 우리 클래스 코드가 그 명령을 받아 자동으로 파일을 열고 내용을 Claude에 돌려보냅니다.

그런데 이 도구가 왜 필요할까요? 무엇을 해 줄까요? 지금 여러분은 아마 멋진 AI 어시스턴트가 내장된 코드 편집기를 쓰고 있을 겁니다 — 파일 리팩터링·생성 등을 시킬 수 있죠. 사실 그 멋진 편집기의 기능 상당수를 이 텍스트 편집 도구만으로 재현할 수 있습니다. 예컨대 프롬프트를 바꿔, 그 파일을 열어 파이를 다섯째 자리까지 계산하는 함수를 작성하고, 그다음 ./test.py 파일을 만들어 구현을 테스트하라고 요청합니다.

실행 후 주고받은 메시지를 보면 — 처음 user 메시지, 다음 assistant 메시지에서 Claude가 텍스트 편집 도구로 먼저 파일을 보려(view) 합니다. 우리가 그 내용을 돌려주면, Claude는 '좋아, 이 파일 안을 알았으니 새 내용으로 교체하겠다'며 str_replace로 파이 계산 구현을 써넣습니다. 우리가 '업데이트 성공'으로 응답하면, Claude는 create로 test.py를 만들고 그 안에 테스트를 써넣습니다. 새로 갱신된 main.py와 함께 생긴 test.py를 열어 보면 모두 실제로 일어났음을 확인할 수 있습니다.

정리하면, 이 도구로 꽤 멋진 코드 편집기를 손쉽게 흉내 낼 수 있습니다. '그냥 내 편집기를 쓰면 되지 않나?' 싶을 수 있지만, 네이티브 완전 기능 편집기에 접근할 수 없는 환경에서 어떤 파일 시스템의 파일을 편집해야 하는 등의 시나리오가 있습니다. 그럴 때 텍스트 편집 도구를 쓰면 됩니다.

이 장에서 배우는 것What you'll learn

약 8분
1

텍스트 편집 도구는 Claude 기본 내장 — view·str_replace·create·insert·undo

2

내장된 것은 JSON 스키마뿐 — 실제 동작 함수는 우리가 작성

3

요청엔 작은 스텁 스키마(type에 모델 버전 날짜) 포함 → API가 큰 스키마로 확장

4

TextEditorTool 클래스가 명령(view/str_replace/create…)을 실제 파일에 수행

5

run_tool이 command에 따라 알맞은 메서드로 라우팅

6

이 도구만으로 멋진 AI 코드 편집기를 흉내 — 파일 읽기·교체·생성

먼저 짚고 갈 용어
text editor tool
Claude에 내장된 도구. 파일을 보고·바꾸고·만들고·되돌린다. 스키마만 내장.
스텁 스키마(stub)
요청에 넣는 아주 작은 스키마. type(모델 버전 날짜 포함)과 name만. API가 큰 스키마로 확장.
command
tool_use 입력의 핵심 키. view·str_replace·create·insert·undo_edit 중 하나.
str_replace
파일 안에서 정확히 한 곳의 문자열을 새 문자열로 교체하는 명령.
TextEditorTool
명령을 실제 파일 시스템 작업으로 수행하는, 우리가 구현하는 클래스.

내장 도구 = 스키마만 내장

Schema built in, code is yours

지금까지는 도구를 우리가 다 만들었지만, 텍스트 편집 도구는 Claude에 기본 내장돼 있습니다. 파일을 열어 읽고·일부 텍스트를 보거나 바꾸고·새 파일을 만들고·되돌릴 수 있어, Claude가 거의 소프트웨어 엔지니어처럼 동작합니다. 단, 내장된 것은 JSON 스키마뿐입니다.

내장JSON 스키마

텍스트 편집 도구 사용법을 Claude에 알려 주는 명세. Claude에 이미 내장돼 있어, 우리는 작은 스텁 스키마(type·name)만 요청에 넣으면 API가 큰 스키마로 확장합니다.

우리 몫도구 함수 구현

Claude의 모든 편집 요청을 실제로 수행하는 함수. 내장돼 있지 않습니다 — view·str_replace·create… 를 우리 코드베이스에 직접 작성해야 합니다.

그래서 도구의 양쪽 중 구현 쪽은 우리가 작성합니다. 노트북에는 모든 편집 명령을 실제 파일 작업으로 수행하는 TextEditorTool 클래스가 미리 들어 있습니다.

005_text_editor_tool.ipynb · TextEditorTool (구현 쪽)
import os, shutil
from typing import Optional, List

class TextEditorTool:
    def __init__(self, base_dir="", backup_dir=""):
        self.base_dir = base_dir or os.getcwd()
        self.backup_dir = backup_dir or os.path.join(self.base_dir, ".backups")
        os.makedirs(self.backup_dir, exist_ok=True)

    def view(self, file_path, view_range=None):
        # 디렉터리면 목록, 파일이면 줄 번호와 함께 내용을 돌려준다
        abs_path = self._validate_path(file_path)
        ...

    def str_replace(self, file_path, old_str, new_str):
        # old_str이 정확히 1번 매칭될 때만 교체 (0개/2개 이상이면 에러)
        ...

    def create(self, file_path, file_text):
        # 새 파일 생성 (이미 있으면 에러, str_replace를 쓰라고 안내)
        ...

    def insert(self, file_path, insert_line, new_str): ...
    def undo_edit(self, file_path): ...   # 백업에서 복원

작은 스텁 스키마 → 큰 스키마로 확장

The stub schema

살짝 헷갈리는 부분 — 스키마가 내장이어도, 요청에는 아주 작은 스텁 스키마를 넣어야 합니다. 그 type 문자열에는 날짜가 들어 있고, 이 값은 사용하는 모델 버전에 따라 달라집니다(예: 3.7과 3.5는 날짜가 다름). 이 작은 스키마를 보내면 API가 내부적으로 훨씬 큰 스키마로 자동 확장합니다.

get_text_edit_schema · 모델 버전에 맞춘 스텁
# 사용하는 모델 버전에 맞춰 작은 스텁 스키마를 만든다
def get_text_edit_schema(model):
    return {
        "type": "text_editor_20250728",   # 날짜는 모델 버전에 따라 다름
        "name": "str_replace_based_edit_tool",
    }

# 이 작은 스키마를 보내면 API가 자동으로 훨씬 큰 스키마로 확장한다

그리고 Claude가 보내온 tool_use의 command에 따라 알맞은 메서드로 라우팅합니다.

run_tool · command 라우팅
import json

text_editor_tool = TextEditorTool()

def run_tool(tool_name, tool_input):
    if tool_name == "str_replace_based_edit_tool":
        command = tool_input["command"]
        if command == "view":
            return text_editor_tool.view(
                tool_input["path"], tool_input.get("view_range")
            )
        elif command == "str_replace":
            return text_editor_tool.str_replace(
                tool_input["path"], tool_input["old_str"], tool_input["new_str"]
            )
        elif command == "create":
            return text_editor_tool.create(
                tool_input["path"], tool_input["file_text"]
            )
        elif command == "insert":
            return text_editor_tool.insert(
                tool_input["path"], tool_input["insert_line"], tool_input["new_str"]
            )
        elif command == "undo_edit":
            return text_editor_tool.undo_edit(tool_input["path"])
왜 작은 스키마라도 넣나

전부 내장이면 좋겠지만, 정확한 도구 버전(날짜)이 모델마다 달라 API가 그 단서를 필요로 합니다. 우리가 보내는 건 type+name 정도의 스텁이고, 사용법을 나열한 큰 스키마는 API가 채워 Claude에 전달합니다.

명령 시연 — view · str_replace · create

view / str_replace / create

Claude에게 ./main.py를 열어 파이를 다섯째 자리까지 계산하는 함수를 쓰고, ./test.py를 만들어 테스트하라고 시키면, Claude는 먼저 view로 파일을 보고 → str_replace로 내용을 바꾸고 → create로 새 파일을 만듭니다. 아래 탭으로 각 명령이 무엇을 주고받는지 살펴보세요.

텍스트 편집 명령 시연 · 탭을 눌러 같은 main.py에 명령을 적용
main.py


tool_result (role: user)






run_conversation · tool_use이면 우리 함수로 실제 수행
def run_conversation(messages):
    while True:
        response = chat(
            messages,
            tools=[get_text_edit_schema(model)],   # 작은 스텁 스키마만 넘김
        )

        add_assistant_message(messages, response)
        print(text_from_message(response))

        if response.stop_reason != "tool_use": break

        tool_results = run_tools(response)   # 우리 함수가 실제 파일 작업 수행
        add_user_message(messages, tool_results)
    return messages
요청 · 함께 따라 하기
messages = []
add_user_message(
    messages,
    """
    Open the ./main.py file and write a function to
    calculate pi to the fifth digit. Then create a
    ./test.py file to test your implementation.
    """,
)

run_conversation(messages)
정리 & 점검
Recap & check
핵심 정리
  • 텍스트 편집 도구는 Claude 기본 내장 — view·str_replace·create·insert·undo_edit.
  • 내장된 것은 JSON 스키마뿐. 실제 동작 함수(TextEditorTool)는 우리가 작성.
  • 요청엔 작은 스텁 스키마(type에 모델 버전 날짜 + name)를 넣고, API가 큰 스키마로 확장.
  • run_tool이 command로 라우팅 → 이 도구만으로 AI 코드 편집기를 흉내.
Q1텍스트 편집 도구에서 실제로 Claude에 내장된 것은?
Q2요청에 넣는 스텁 스키마의 type에 날짜가 들어가는 이유는?
Q3Claude의 편집 요청은 어떻게 처리되나요?






  MEMBER SESSION REQUIRED · REGISTRATION IS FREE
  
여기부터는 등록한 분에게 열립니다.

  
전 코스는 계속 무료입니다. 등록하면 이 코스의 남은 76개 레슨을 끝까지 읽을 수 있습니다.

  
등록하고 이어서 읽기

  

    
이미 등록하셨다면 그때 쓰신 이메일을 넣어 주세요.