텍스트 에디터 도구

이 기능은 Zero Data Retention (ZDR)의 적용 대상입니다. 조직에 ZDR 계약이 체결되어 있는 경우, 이 기능을 통해 전송된 데이터는 API 응답이 반환된 후 저장되지 않습니다.

Claude는 Anthropic 스키마 텍스트 에디터 도구를 사용하여 텍스트 파일을 보고 수정할 수 있으며, 이를 통해 코드나 기타 텍스트 문서를 디버깅하고, 수정하고, 개선하는 데 도움을 줄 수 있습니다. 이를 통해 Claude는 단순히 변경 사항을 제안하는 것이 아니라 파일과 직접 상호작용하여 실질적인 지원을 제공할 수 있습니다.

모델 지원에 대해서는 도구 참조를 참조하세요.

텍스트 에디터 도구를 사용해야 하는 경우

텍스트 에디터 도구를 사용하는 몇 가지 예시는 다음과 같습니다:

코드 디버깅: Claude가 구문 오류부터 로직 문제까지 코드의 버그를 식별하고 수정하도록 합니다.
코드 리팩토링: Claude가 대상을 지정한 편집을 통해 코드 구조, 가독성 및 성능을 개선하도록 합니다.
문서 생성: Claude에게 코드베이스에 docstring, 주석 또는 README 파일을 추가하도록 요청합니다.
테스트 생성: Claude가 구현에 대한 이해를 바탕으로 코드에 대한 단위 테스트를 생성하도록 합니다.

텍스트 에디터 도구 사용하기

Messages API를 사용하여 Claude에 텍스트 에디터 도구(이름: str_replace_based_edit_tool)를 제공하세요.

선택적으로 max_characters 매개변수를 지정하여 대용량 파일을 볼 때 잘림(truncation)을 제어할 수 있습니다.

max_characters는 text_editor_20250728 및 이후 버전의 텍스트 에디터 도구와만 호환됩니다.

텍스트 에디터 도구는 다음과 같은 방식으로 사용할 수 있습니다:

텍스트 에디터 도구 명령

텍스트 에디터 도구는 파일을 보고 수정하기 위한 여러 명령을 지원합니다:

view

view 명령을 사용하면 Claude가 파일의 내용을 검토하거나 디렉터리의 내용을 나열할 수 있습니다. 전체 파일 또는 특정 범위의 줄을 읽을 수 있습니다.

매개변수:

command: "view"여야 합니다
path: 볼 파일 또는 디렉터리의 경로
view_range (선택 사항): 볼 시작 및 끝 줄 번호를 지정하는 두 개의 정수 배열입니다. 줄 번호는 1부터 시작하며, 끝 줄에 -1을 지정하면 파일 끝까지 읽습니다. 이 매개변수는 디렉터리가 아닌 파일을 볼 때만 적용됩니다.

str_replace

str_replace 명령을 사용하면 Claude가 파일의 특정 문자열을 새 문자열로 교체할 수 있습니다. 이는 정밀한 편집을 수행하는 데 사용됩니다.

매개변수:

command: "str_replace"여야 합니다
path: 수정할 파일의 경로
old_str: 교체할 텍스트(공백 및 들여쓰기를 포함하여 정확히 일치해야 함)
new_str: 기존 텍스트 대신 삽입할 새 텍스트

create

create 명령을 사용하면 Claude가 지정된 내용으로 새 파일을 생성할 수 있습니다.

매개변수:

command: "create"여야 합니다
path: 새 파일을 생성할 경로
file_text: 새 파일에 작성할 내용

insert

insert 명령을 사용하면 Claude가 파일의 특정 위치에 텍스트를 삽입할 수 있습니다.

매개변수:

command: "insert"여야 합니다
path: 수정할 파일의 경로
insert_line: 텍스트를 삽입할 줄 번호(파일 시작 부분은 0)
insert_text: 삽입할 텍스트

예시: 텍스트 에디터 도구로 구문 오류 수정하기

이 예시는 Claude가 텍스트 에디터 도구를 사용하여 Python 파일의 구문 오류를 수정하는 방법을 보여줍니다.

먼저 애플리케이션이 Claude에 텍스트 에디터 도구와 구문 오류를 수정하라는 프롬프트를 제공합니다:

Claude는 먼저 텍스트 에디터 도구를 사용하여 파일을 봅니다:

Output

{
  "id": "msg_01XAbCDeFgHiJkLmNoPQrStU",
  "model": "claude-opus-4-8",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you fix the syntax error in your primes.py file. First, let me take a look at the file to identify the issue."
    },
    {
      "type": "tool_use",
      "id": "toolu_01AbCdEfGhIjKlMnOpQrStU",
      "name": "str_replace_based_edit_tool",
      "input": {
        "command": "view",
        "path": "primes.py"
      }
    }
  ]
}

그런 다음 애플리케이션은 파일을 읽고 그 내용을 Claude에 반환해야 합니다:

줄 번호

위 예시에서 view 도구 결과에는 각 줄 앞에 줄 번호가 붙은 파일 내용이 포함되어 있습니다(예: "1: def is_prime(n):"). 줄 번호는 필수는 아니지만, 파일의 특정 섹션을 검토하기 위한 view_range 매개변수와 정확한 위치에 내용을 추가하기 위한 insert_line 매개변수를 성공적으로 사용하는 데 필수적입니다.

Claude는 구문 오류를 식별하고 str_replace 명령을 사용하여 수정합니다:

Output

{
  "id": "msg_01VwXyZAbCdEfGhIjKlMnO",
  "model": "claude-opus-4-8",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I found the syntax error in your primes.py file. In the `get_primes` function, there is a missing colon (:) at the end of the for loop line. Let me fix that for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_01PqRsTuVwXyZAbCdEfGh",
      "name": "str_replace_based_edit_tool",
      "input": {
        "command": "str_replace",
        "path": "primes.py",
        "old_str": "    for num in range(2, limit + 1)",
        "new_str": "    for num in range(2, limit + 1):"
      }
    }
  ]
}

그런 다음 애플리케이션은 편집을 수행하고 결과를 반환해야 합니다:

마지막으로 Claude는 수정 사항에 대한 완전한 설명을 제공합니다:

Output

{
  "id": "msg_01IjKlMnOpQrStUvWxYzAb",
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I've fixed the syntax error in your primes.py file. The issue was in the `get_primes` function at line 19. There was a missing colon (:) at the end of the for loop line.\n\nHere's what I changed:\n\nFrom:\n```python\nfor num in range(2, limit + 1)\n```\n\nTo:\n```python\nfor num in range(2, limit + 1):\n```\n\nIn Python, a colon is required at the end of statements that start a new code block, such as for loops, if statements, function definitions, etc. Without the colon, Python raises a syntax error because it doesn't know where the code block begins.\n\nYour code should now run correctly. The function will properly generate a list of prime numbers up to the specified limit."
    }
  ]
}

텍스트 에디터 도구 구현하기

텍스트 에디터 도구는 스키마가 없는 도구로 구현됩니다. 이 도구를 사용할 때는 다른 도구와 달리 입력 스키마를 제공할 필요가 없습니다. 스키마는 Claude의 모델에 내장되어 있으며 수정할 수 없습니다.

Claude 4 모델의 경우 도구 타입은 type: "text_editor_20250728"입니다.

텍스트 에디터 도구를 구현할 때 다음 사항을 유의하세요:

보안: 이 도구는 로컬 파일 시스템에 접근할 수 있으므로 적절한 보안 조치를 구현하세요.
백업: 중요한 파일에 대한 편집을 허용하기 전에 항상 백업을 생성하세요.
유효성 검사: 의도하지 않은 변경을 방지하기 위해 모든 입력을 검증하세요.
고유 일치: 의도하지 않은 편집을 방지하기 위해 교체가 정확히 한 위치와만 일치하는지 확인하세요.

오류 처리

텍스트 에디터 도구를 사용할 때 다양한 오류가 발생할 수 있습니다. 다음은 이를 처리하는 방법에 대한 지침입니다:

구현 모범 사례 따르기

가격 및 토큰 사용량

텍스트 편집기 도구는 Claude와 함께 사용되는 다른 도구와 동일한 가격 구조를 사용합니다. 사용 중인 Claude 모델을 기준으로 표준 입력 및 출력 토큰 가격 책정을 따릅니다.

기본 토큰 외에도 텍스트 편집기 도구에는 다음과 같은 추가 입력 토큰이 필요합니다:

도구	추가 입력 토큰
`text_editor_20250429` (Claude 4.x)	700 토큰

도구 가격에 대한 자세한 내용은 도구 사용 가격을 참조하세요.

텍스트 에디터 도구를 다른 도구와 통합하기

텍스트 에디터 도구는 다른 Claude 도구와 함께 사용할 수 있습니다. 도구를 결합할 때는 다음 사항을 확인하세요:

사용 중인 모델과 도구 버전을 일치시키세요
요청에 포함된 모든 도구에 대한 추가 토큰 사용량을 고려하세요

변경 로그

날짜	버전	변경 사항
2025년 7월 28일	`text_editor_20250728`	일부 문제를 수정하고 선택적 `max_characters` 매개변수를 추가한 업데이트된 텍스트 에디터 도구 릴리스입니다. 그 외에는 `text_editor_20250429`와 동일합니다.
2025년 4월 29일	`text_editor_20250429`	Claude 4용 텍스트 에디터 도구 릴리스입니다. 이 버전은 `undo_edit` 명령을 제거했지만 다른 모든 기능은 유지합니다. 도구 이름이 str_replace 기반 아키텍처를 반영하도록 업데이트되었습니다.
2025년 3월 13일	`text_editor_20250124`	독립형 텍스트 에디터 도구 문서 도입. 이 버전은 Claude Sonnet 3.7에 최적화되어 있지만 이전 버전과 동일한 기능을 제공합니다.
2024년 10월 22일	`text_editor_20241022`	Claude Sonnet 3.5(지원 종료됨)와 함께 텍스트 에디터 도구 최초 릴리스. `view`, `create`, , , 명령을 통해 파일을 보고, 생성하고, 편집하는 기능을 제공합니다.

다음 단계

텍스트 에디터 도구를 더 편리하고 강력한 방식으로 사용하는 몇 가지 아이디어는 다음과 같습니다:

개발 워크플로와 통합: 텍스트 에디터 도구를 개발 도구나 IDE에 통합하세요
코드 리뷰 시스템 구축: Claude가 코드를 검토하고 개선하도록 하세요
디버깅 어시스턴트 구축: Claude가 코드의 문제를 진단하고 수정하는 데 도움을 줄 수 있는 시스템을 만드세요
파일 형식 변환 구현: Claude가 파일을 한 형식에서 다른 형식으로 변환하는 데 도움을 주도록 하세요
문서화 자동화: Claude가 코드를 자동으로 문서화하는 워크플로를 설정하세요

텍스트 에디터 도구를 통해 Claude는 코드베이스와 직접 작업할 수 있으며, 디버깅부터 자동화된 문서화까지 다양한 워크플로를 지원합니다.

도구 사용 개요

Claude와 함께 사용할 도구 워크플로를 구현하는 방법을 알아보세요.

Bash 도구

Claude로 셸 명령을 실행하세요.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[
        {
            "type": "text_editor_20250728",
            "name": "str_replace_based_edit_tool",
            "max_characters": 10000,
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "There's a syntax error in my primes.py file. Can you help me fix it?",
        }
    ],
)

print(response)

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}],
    messages=[
        {
            "role": "user",
            "content": "There's a syntax error in my primes.py file. Can you help me fix it?",
        }
    ],
)

print(response)

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}],
    messages=[
        {
            "role": "user",
            "content": "There's a syntax error in my primes.py file. Can you help me fix it?",
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I'll help you fix the syntax error in your primes.py file. First, let me take a look at the file to identify the issue.",
                },
                {
                    "type": "tool_use",
                    "id": "toolu_01AbCdEfGhIjKlMnOpQrStU",
                    "name": "str_replace_based_edit_tool",
                    "input": {"command": "view", "path": "primes.py"},
                },
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01AbCdEfGhIjKlMnOpQrStU",
                    "content": '1: def is_prime(n):\n2:     """Check if a number is prime."""\n3:     if n <= 1:\n4:         return False\n5:     if n <= 3:\n6:         return True\n7:     if n % 2 == 0 or n % 3 == 0:\n8:         return False\n9:     i = 5\n10:     while i * i <= n:\n11:         if n % i == 0 or n % (i + 2) == 0:\n12:             return False\n13:         i += 6\n14:     return True\n15: \n16: def get_primes(limit):\n17:     """Generate a list of prime numbers up to the given limit."""\n18:     primes = []\n19:     for num in range(2, limit + 1)\n20:         if is_prime(num):\n21:             primes.append(num)\n22:     return primes\n23: \n24: def main():\n25:     """Main function to demonstrate prime number generation."""\n26:     limit = 100\n27:     prime_list = get_primes(limit)\n28:     print(f"Prime numbers up to {limit}:")\n29:     print(prime_list)\n30:     print(f"Found {len(prime_list)} prime numbers.")\n31: \n32: if __name__ == "__main__":\n33:     main()',
                }
            ],
        },
    ],
)

print(response)

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    tools=[{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}],
    messages=[
        # 이전 메시지...
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I found the syntax error in your primes.py file. In the `get_primes` function, there is a missing colon (:) at the end of the for loop line. Let me fix that for you.",
                },
                {
                    "type": "tool_use",
                    "id": "toolu_01PqRsTuVwXyZAbCdEfGh",
                    "name": "str_replace_based_edit_tool",
                    "input": {
                        "command": "str_replace",
                        "path": "primes.py",
                        "old_str": "    for num in range(2, limit + 1)",
                        "new_str": "    for num in range(2, limit + 1):",
                    },
                },
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01PqRsTuVwXyZAbCdEfGh",
                    "content": "Successfully replaced text at exactly one location.",
                }
            ],
        },
    ],
)

print(response)

에디터 구현 초기화
파일 읽기, 쓰기, 수정과 같은 파일 작업을 처리하는 헬퍼 함수를 만드세요. 실수로부터 복구할 수 있도록 백업 기능 구현을 고려하세요.

에디터 도구 호출 처리

명령 유형에 따라 Claude의 도구 호출을 처리하는 함수를 만드세요:

def handle_editor_tool(tool_call):
    input_params = tool_call.input
    command = input_params.get("command", "")
    file_path = input_params.get("path", "")

    if command == "view":
        # 파일 내용을 읽고 반환합니다
        pass
    elif command == "str_replace":
        # 파일의 텍스트를 교체합니다
        pass
    elif command == "create":
        # 새 파일을 생성합니다
        pass
    elif command == "insert":
        # 지정 위치에 텍스트를 삽입합니다
        pass

보안 조치 구현
유효성 검사 및 보안 검사를 추가하세요:
- 디렉터리 순회(directory traversal)를 방지하기 위해 파일 경로를 검증하세요
- 변경하기 전에 백업을 생성하세요
- 오류를 적절하게 처리하세요
- 권한 검사를 구현하세요

Claude의 응답 처리

Claude의 응답에서 도구 호출을 추출하고 처리하세요:

# Claude의 응답에서 도구 사용 처리
for content in response.content:
    if content.type == "tool_use":
        # 명령에 따라 도구 실행
        result = handle_editor_tool(content)

        # 결과를 Claude에 반환
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result,
        }

str_replace

insert

undo_edit

텍스트 에디터 도구를 사용해야 하는 경우

텍스트 에디터 도구 사용하기

텍스트 에디터 도구 명령

view

view 명령 예시

str_replace

str_replace 명령 예시

create

create 명령 예시

insert

insert 명령 예시

예시: 텍스트 에디터 도구로 구문 오류 수정하기

텍스트 에디터 도구 구현하기

오류 처리

파일을 찾을 수 없음

교체 대상이 여러 개 일치함

구현 모범 사례 따르기

명확한 컨텍스트 제공

파일 경로를 명시적으로 지정

편집 전 백업 생성

가격 및 토큰 사용량

텍스트 에디터 도구를 다른 도구와 통합하기

변경 로그

다음 단계

교체 대상이 일치하지 않음

권한 오류

고유 텍스트 교체를 신중하게 처리

변경 사항 확인

텍스트 에디터 도구를 사용해야 하는 경우

텍스트 에디터 도구 사용하기

텍스트 에디터 도구 명령

view

str_replace

create

insert

예시: 텍스트 에디터 도구로 구문 오류 수정하기

텍스트 에디터 도구 구현하기

오류 처리

구현 모범 사례 따르기

가격 및 토큰 사용량

텍스트 에디터 도구를 다른 도구와 통합하기

변경 로그

다음 단계