텍스트 에디터 도구

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

​

텍스트 에디터 도구 사용 전

​

호환되는 모델 사용

Anthropic의 텍스트 에디터 도구는 Claude 3.5 Sonnet과 Claude 3.7 Sonnet에서만 사용할 수 있습니다:

• Claude 3.7 Sonnet: text_editor_20250124
• Claude 3.5 Sonnet: text_editor_20241022

두 버전 모두 동일한 기능을 제공합니다 - 사용하는 버전은 작업 중인 모델과 일치해야 합니다.

​

사용 사례 평가

텍스트 에디터 도구를 사용하는 경우의 예시:

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

​

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

Messages API를 사용하여 텍스트 에디터 도구(str_replace_editor)를 Claude에 제공합니다:

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

​

텍스트 에디터 도구 명령

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

​

view

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

매개변수:

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

// 파일 보기 예시
{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "str_replace_editor",
  "input": {
    "command": "view",
    "path": "primes.py"
  }
}

// 디렉토리 보기 예시
{
  "type": "tool_use",
  "id": "toolu_02B19r91rw91mr917835mr9",
  "name": "str_replace_editor",
  "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_editor",
  "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_editor",
  "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)
• new_str: 삽입할 텍스트

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "str_replace_editor",
  "input": {
    "command": "insert",
    "path": "primes.py",
    "insert_line": 0,
    "new_str": "\"\"\"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"
  }
}

​

undo_edit

undo_edit 명령을 사용하면 Claude가 파일에 대한 마지막 편집을 취소할 수 있습니다.

매개변수:

• command: “undo_edit”여야 함
• path: 마지막 편집을 취소할 파일의 경로

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

​

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

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

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

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

{
  "id": "msg_01XAbCDeFgHiJkLmNoPQrStU",
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "primes.py 파일의 구문 오류를 수정하는 것을 도와드리겠습니다. 먼저 문제를 파악하기 위해 파일을 살펴보겠습니다."
    },
    {
      "type": "tool_use",
      "id": "toolu_01AbCdEfGhIjKlMnOpQrStU",
      "name": "str_replace_editor",
      "input": {
        "command": "view",
        "path": "primes.py"
      }
    }
  ]
}

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

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

{
  "id": "msg_01VwXyZAbCdEfGhIjKlMnO",
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "primes.py 파일에서 구문 오류를 찾았습니다. `get_primes` 함수에서 for 루프 줄 끝에 콜론(:)이 누락되었습니다. 이를 수정하겠습니다."
    },
    {
      "type": "tool_use",
      "id": "toolu_01PqRsTuVwXyZAbCdEfGh",
      "name": "str_replace_editor",
      "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는 수정에 대한 완전한 설명을 제공할 것입니다:

{
  "id": "msg_01IjKlMnOpQrStUvWxYzAb",
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "end_turn",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "primes.py 파일의 구문 오류를 수정했습니다. 문제는 19번 줄의 `get_primes` 함수에 있었습니다. for 루프 줄 끝에 콜론(:)이 누락되어 있었습니다.\n\n다음과 같이 변경했습니다:\n\n이전:\n```python\nfor num in range(2, limit + 1)\n```\n\n이후:\n```python\nfor num in range(2, limit + 1):\n```\n\nPython에서는 for 루프, if 문, 함수 정의 등과 같이 새로운 코드 블록을 시작하는 문장 끝에 콜론이 필요합니다. 콜론이 없으면 Python이 코드 블록이 어디서 시작하는지 알 수 없어서 구문 오류가 발생합니다.\n\n이제 코드가 올바르게 실행될 것입니다. 이 함수는 지정된 한계까지의 소수 목록을 제대로 생성할 것입니다."
    }
  ]
}

​

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

텍스트 에디터 도구는 type: "text_editor_20250124"로 식별되는 스키마 없는 도구로 구현됩니다. 이 도구를 사용할 때는 다른 도구와 달리 입력 스키마를 제공할 필요가 없습니다. 스키마는 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
    elif command == 'undo_edit':
        # 백업에서 복원
        pass

# 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": "오류: 파일을 찾을 수 없습니다",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "오류: 대체할 텍스트가 3곳에서 발견되었습니다. 고유한 일치를 위해 더 많은 컨텍스트를 제공해주세요.",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "오류: 대체할 텍스트를 찾을 수 없습니다. 텍스트를 확인하고 다시 시도해주세요.",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "오류: 권한이 거부되었습니다. 파일에 쓸 수 없습니다.",
      "is_error": true
    }
  ]
}

​

구현 모범 사례 따르기

def backup_file(file_path):
    """편집하기 전에 파일 백업을 생성합니다."""
    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):
    """정확히 한 번 일치하는 경우에만 텍스트를 대체합니다."""
    with open(file_path, 'r') as f:
        content = f.read()
    
    count = content.count(old_text)
    if count == 0:
        return "오류: 일치하는 항목을 찾을 수 없습니다"
    elif count > 1:
        return f"오류: {count}개의 일치하는 항목을 찾았습니다"
    else:
        new_content = content.replace(old_text, new_text)
        with open(file_path, 'w') as f:
            f.write(new_content)
        return "텍스트를 성공적으로 대체했습니다"

def verify_changes(file_path):
    """변경 후 테스트나 검사를 실행합니다."""
    try:
        # Python 파일의 경우 구문 오류 확인
        if file_path.endswith('.py'):
            import ast
            with open(file_path, 'r') as f:
                ast.parse(f.read())
            return "구문 검사 통과"
    except Exception as e:
        return f"확인 실패: {str(e)}"

​

가격 책정 및 토큰 사용량

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

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

도구 가격 책정에 대한 자세한 정보는 도구 사용 가격 책정을 참조하세요.

​

텍스트 에디터 도구를 컴퓨터 사용과 통합

텍스트 에디터 도구는 컴퓨터 사용 도구와 다른 Anthropic 정의 도구와 함께 사용할 수 있습니다. 이러한 도구들을 결합할 때는 다음 사항을 고려해야 합니다:

1. 적절한 베타 헤더 포함(컴퓨터 사용과 함께 사용하는 경우)
2. 도구 버전을 사용 중인 모델과 일치시키기
3. 요청에 포함된 모든 도구에 대한 추가 토큰 사용량 고려

컴퓨터 사용 컨텍스트에서 텍스트 에디터 도구 사용에 대한 자세한 정보는 컴퓨터 사용을 참조하세요.

​

변경 로그

​

다음 단계

텍스트 에디터 도구를 더 편리하고 강력하게 사용하는 방법에 대한 아이디어입니다:

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

텍스트 에디터 도구로 애플리케이션을 구축하면서, 여러분이 Claude의 기능을 활용하여 개발 워크플로우와 생산성을 향상시키는 방법을 보게 되어 기대됩니다.