텍스트 편집기 도구

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

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

텍스트 편집기 도구를 사용해야 하는 경우

텍스트 편집기 도구를 사용하는 몇 가지 예시는 다음과 같습니다:

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

텍스트 편집기 도구 사용하기

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

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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)

텍스트 편집기 도구는 다음과 같은 방식으로 사용합니다:

1. 1

   Claude에게 텍스트 편집기 도구와 사용자 프롬프트 제공

   • API 요청에 텍스트 편집기 도구를 포함합니다
   • "제 코드의 구문 오류를 수정해 줄 수 있나요?"와 같이 파일을 검토하거나 수정해야 할 수 있는 사용자 프롬프트를 제공합니다
2. 2

   Claude가 도구를 사용하여 파일 또는 디렉터리를 검토

   • Claude는 무엇을 살펴봐야 하는지 판단하고 view 명령을 사용하여 파일 내용을 검토하거나 디렉터리 내용을 나열합니다
   • API 응답에는 view 명령이 포함된 tool_use 콘텐츠 블록이 포함됩니다
3. 3

   view 명령을 실행하고 결과 반환

   • Claude의 도구 사용 요청에서 파일 또는 디렉터리 경로를 추출합니다
   • 파일의 내용을 읽거나 디렉터리 내용을 나열합니다
   • 도구 구성에 max_characters 매개변수가 지정된 경우, 파일 내용을 해당 길이로 자릅니다
   • tool_result 콘텐츠 블록이 포함된 새 user 메시지로 대화를 이어가며 결과를 Claude에게 반환합니다
4. 4

   Claude가 도구를 사용하여 파일 수정

   • 파일 또는 디렉터리를 검토한 후, Claude는 str_replace와 같은 명령을 사용하여 변경하거나 insert를 사용하여 특정 줄 번호에 텍스트를 추가할 수 있습니다.
   • Claude가 str_replace 명령을 사용하는 경우, Claude는 이전 텍스트와 이를 대체할 새 텍스트가 포함된 올바른 형식의 도구 사용 요청을 구성합니다
5. 5

   편집을 실행하고 결과 반환

   • Claude의 도구 사용 요청에서 파일 경로, 이전 텍스트, 새 텍스트를 추출합니다
   • 파일에서 텍스트 교체를 수행합니다
   • 결과를 Claude에게 반환합니다
6. 6

   Claude가 분석 및 설명 제공

   • 파일을 검토하고 필요한 경우 편집한 후, Claude는 발견한 내용과 변경한 사항에 대한 완전한 설명을 제공합니다

텍스트 편집기 도구 명령

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

view

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

매개변수:

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

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "str_replace_based_edit_tool",
  "input": {
    "command": "view",
    "path": "primes.py"
  }
}

{
  "type": "tool_use",
  "id": "toolu_02B19r91rw91mr917835mr9",
  "name": "str_replace_based_edit_tool",
  "input": {
    "command": "view",
    "path": "src/"
  }
}

str_replace

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

매개변수:

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

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "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):"
  }
}

create

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

매개변수:

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

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "str_replace_based_edit_tool",
  "input": {
    "command": "create",
    "path": "test_primes.py",
    "file_text": "import unittest\nimport primes\n\nclass TestPrimes(unittest.TestCase):\n    def test_is_prime(self):\n        self.assertTrue(primes.is_prime(2))\n        self.assertTrue(primes.is_prime(3))\n        self.assertFalse(primes.is_prime(4))\n\nif __name__ == '__main__':\n    unittest.main()"
  }
}

insert

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

매개변수:

• command: "insert"여야 합니다
• path: 수정할 파일의 경로
• insert_line: 텍스트를 삽입할 기준 줄 번호(해당 줄 뒤에 삽입, 파일 시작은 0)
• insert_text: 삽입할 텍스트

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "str_replace_based_edit_tool",
  "input": {
    "command": "insert",
    "path": "primes.py",
    "insert_line": 0,
    "insert_text": "\"\"\"Module for working with prime numbers.\n\nThis module provides functions to check if a number is prime\nand to generate a list of prime numbers up to a given limit.\n\"\"\"\n"
  }
}

예시: 텍스트 편집기 도구로 구문 오류 수정하기

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

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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)

Claude는 먼저 텍스트 편집기 도구를 사용하여 파일을 봅니다:

{
  "id": "msg_01XAbCDeFgHiJkLmNoPQrStU",
  "model": "claude-opus-5-5",
  "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에게 반환해야 합니다:

response = client.messages.create(
    model="claude-opus-5-5",
    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)

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

{
  "id": "msg_01VwXyZAbCdEfGhIjKlMnO",
  "model": "claude-opus-5-5",
  "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):"
      }
    }
  ]
}

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

response = client.messages.create(
    model="claude-opus-5-5",
    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는 수정 사항에 대한 완전한 설명을 제공합니다:

{
  "id": "msg_01IjKlMnOpQrStUvWxYzAb",
  "model": "claude-opus-5-5",
  "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."
    }
  ]
}

텍스트 편집기 도구 구현하기

텍스트 편집기 도구는 스키마 없는(schema-less) 도구로 구현됩니다. 이 도구를 사용할 때는 다른 도구처럼 입력 스키마를 제공할 필요가 없습니다. 스키마는 Claude 모델에 내장되어 있으며 수정할 수 없습니다.

도구 유형은 Claude 4 및 이후 모델의 경우 type: "text_editor_20250728"입니다.

1. 1

   편집기 구현 초기화

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

2. 2

   편집기 도구 호출 처리

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

   PythonTypeScriptC#GoJavaPHPRuby

   

   def handle_editor_tool(tool_call):
       input_params = tool_call.input
       command = input_params.get("command", "")
       file_path = input_params.get("path", "")
   
       match command:
           case "view":
               # 파일 내용을 읽어 반환합니다
               pass
           case "str_replace":
               # 파일의 텍스트를 바꿉니다
               pass
           case "create":
               # 새 파일을 생성합니다
               pass
           case "insert":
               # 지정한 위치에 텍스트를 삽입합니다
               pass

3. 3

   보안 조치 구현

   유효성 검사 및 보안 검사를 추가하세요:

   • 디렉터리 순회(directory traversal)를 방지하기 위해 파일 경로를 검증합니다
   • 변경하기 전에 백업을 생성합니다
   • 오류를 적절하게 처리합니다
   • 권한 검사를 구현합니다
4. 4

   Claude의 응답 처리

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

   PythonTypeScriptC#GoJavaPHPRuby

   

   # 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,
           }

오류 처리

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

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: File not found",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Found 3 matches for replacement text. Please provide more context to make a unique match.",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: No match found for replacement. Please check your text and try again.",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Permission denied. Cannot write to file.",
      "is_error": true
    }
  ]
}

구현 모범 사례 따르기

def backup_file(file_path):
    """Create a backup of a file before editing."""
    backup_path = f"{file_path}.backup"
    if os.path.exists(file_path):
        with open(file_path, "r") as src, open(backup_path, "w") as dst:
            dst.write(src.read())

def safe_replace(file_path, old_text, new_text):
    """Replace text only if there's exactly one match."""
    with open(file_path, "r") as f:
        content = f.read()

    count = content.count(old_text)
    if count == 0:
        return "Error: No match found"
    elif count > 1:
        return f"Error: Found {count} matches"
    else:
        new_content = content.replace(old_text, new_text)
        with open(file_path, "w") as f:
            f.write(new_content)
        return "Successfully replaced text"

def verify_changes(file_path):
    """Run tests or checks after making changes."""
    try:
        # Python 파일의 경우 구문 오류를 확인합니다
        if file_path.endswith(".py"):
            import ast

            with open(file_path, "r") as f:
                ast.parse(f.read())
            return "Syntax check passed"
    except Exception as e:
        return f"Verification failed: {str(e)}"

가격 및 토큰 사용량

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

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

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

텍스트 편집기 도구를 다른 도구와 통합하기

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

• 사용 중인 모델에 맞는 도구 버전을 사용합니다
• 요청에 포함된 모든 도구에 대한 추가 토큰 사용량을 고려합니다

변경 로그

다음 단계

텍스트 편집기 도구를 더 편리하고 강력하게 사용하는 방법에 대한 몇 가지 아이디어는 다음과 같습니다:

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

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