Ferramenta de editor de texto

Claude pode usar uma ferramenta de editor de texto definida pela Anthropic para visualizar e modificar arquivos de texto, ajudando você a depurar, corrigir e melhorar seu código ou outros documentos de texto. Isso permite que o Claude interaja diretamente com seus arquivos, fornecendo assistência prática em vez de apenas sugerir mudanças.

​

Antes de usar a ferramenta de editor de texto

​

Use um modelo compatível

A ferramenta de editor de texto da Anthropic está disponível apenas para Claude 3.5 Sonnet e Claude 3.7 Sonnet:

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

Ambas as versões fornecem capacidades idênticas - a versão que você usa deve corresponder ao modelo com o qual está trabalhando.

​

Avalie a adequação do seu caso de uso

Alguns exemplos de quando usar a ferramenta de editor de texto são:

• Depuração de código: Faça o Claude identificar e corrigir bugs em seu código, desde erros de sintaxe até problemas de lógica.
• Refatoração de código: Deixe o Claude melhorar a estrutura, legibilidade e desempenho do seu código através de edições direcionadas.
• Geração de documentação: Peça ao Claude para adicionar docstrings, comentários ou arquivos README ao seu código-base.
• Criação de testes: Faça o Claude criar testes unitários para seu código com base em seu entendimento da implementação.

​

Use a ferramenta de editor de texto

Forneça a ferramenta de editor de texto (chamada str_replace_editor) ao Claude usando a API de Mensagens:

A ferramenta de editor de texto pode ser usada da seguinte maneira:

​

Comandos da ferramenta de editor de texto

A ferramenta de editor de texto suporta vários comandos para visualizar e modificar arquivos:

​

view

O comando view permite que o Claude examine o conteúdo de um arquivo ou liste o conteúdo de um diretório. Ele pode ler o arquivo inteiro ou um intervalo específico de linhas.

Parâmetros:

• command: Deve ser “view”
• path: O caminho para o arquivo ou diretório a ser visualizado
• view_range (opcional): Um array de dois inteiros especificando os números das linhas inicial e final para visualizar. Os números das linhas começam em 1, e -1 para a linha final significa ler até o fim do arquivo. Este parâmetro só se aplica ao visualizar arquivos, não diretórios.

// Exemplo para visualizar um arquivo
{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "str_replace_editor",
  "input": {
    "command": "view",
    "path": "primes.py"
  }
}

// Exemplo para visualizar um diretório
{
  "type": "tool_use",
  "id": "toolu_02B19r91rw91mr917835mr9",
  "name": "str_replace_editor",
  "input": {
    "command": "view",
    "path": "src/"
  }
}

​

str_replace

O comando str_replace permite que o Claude substitua uma string específica em um arquivo por uma nova string. Isso é usado para fazer edições precisas.

Parâmetros:

• command: Deve ser “str_replace”
• path: O caminho para o arquivo a ser modificado
• old_str: O texto a ser substituído (deve corresponder exatamente, incluindo espaços em branco e indentação)
• new_str: O novo texto a ser inserido no lugar do texto antigo

{
  "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

O comando create permite que o Claude crie um novo arquivo com conteúdo especificado.

Parâmetros:

• command: Deve ser “create”
• path: O caminho onde o novo arquivo deve ser criado
• file_text: O conteúdo a ser escrito no novo arquivo

{
  "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

O comando insert permite que o Claude insira texto em um local específico em um arquivo.

Parâmetros:

• command: Deve ser “insert”
• path: O caminho para o arquivo a ser modificado
• insert_line: O número da linha após a qual inserir o texto (0 para o início do arquivo)
• new_str: O texto a ser inserido

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "str_replace_editor",
  "input": {
    "command": "insert",
    "path": "primes.py",
    "insert_line": 0,
    "new_str": "\"\"\"Módulo para trabalhar com números primos.\n\nEste módulo fornece funções para verificar se um número é primo\ne para gerar uma lista de números primos até um determinado limite.\n\"\"\"\n"
  }
}

​

undo_edit

O comando undo_edit permite que o Claude reverta a última edição feita em um arquivo.

Parâmetros:

• command: Deve ser “undo_edit”
• path: O caminho para o arquivo cuja última edição deve ser desfeita

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

​

Exemplo: Corrigindo um erro de sintaxe com a ferramenta de editor de texto

Este exemplo demonstra como o Claude usa a ferramenta de editor de texto para corrigir um erro de sintaxe em um arquivo Python.

Primeiro, seu aplicativo fornece ao Claude a ferramenta de editor de texto e um prompt para corrigir um erro de sintaxe:

O Claude usará a ferramenta de editor de texto primeiro para visualizar o arquivo:

{
  "id": "msg_01XAbCDeFgHiJkLmNoPQrStU",
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Vou ajudar você a corrigir o erro de sintaxe no seu arquivo primes.py. Primeiro, deixe-me dar uma olhada no arquivo para identificar o problema."
    },
    {
      "type": "tool_use",
      "id": "toolu_01AbCdEfGhIjKlMnOpQrStU",
      "name": "str_replace_editor",
      "input": {
        "command": "view",
        "path": "primes.py"
      }
    }
  ]
}

Seu aplicativo deve então ler o arquivo e retornar seu conteúdo ao Claude:

O Claude identificará o erro de sintaxe e usará o comando str_replace para corrigi-lo:

{
  "id": "msg_01VwXyZAbCdEfGhIjKlMnO",
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Encontrei o erro de sintaxe no seu arquivo primes.py. Na função `get_primes`, há um dois-pontos (:) faltando no final da linha do loop for. Vou corrigir isso para você."
    },
    {
      "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):"
      }
    }
  ]
}

Seu aplicativo deve então fazer a edição e retornar o resultado:

Por fim, o Claude fornecerá uma explicação completa da correção:

{
  "id": "msg_01IjKlMnOpQrStUvWxYzAb",
  "model": "claude-3-7-sonnet-20250219",
  "stop_reason": "end_turn",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Corrigi o erro de sintaxe no seu arquivo primes.py. O problema estava na função `get_primes` na linha 19. Havia um dois-pontos (:) faltando no final da linha do loop for.\n\nAqui está o que eu mudei:\n\nDe:\n```python\nfor num in range(2, limit + 1)\n```\n\nPara:\n```python\nfor num in range(2, limit + 1):\n```\n\nEm Python, um dois-pontos é necessário no final de declarações que iniciam um novo bloco de código, como loops for, declarações if, definições de funções, etc. Sem o dois-pontos, Python gera um erro de sintaxe porque não sabe onde o bloco de código começa.\n\nSeu código agora deve executar corretamente. A função irá gerar adequadamente uma lista de números primos até o limite especificado."
    }
  ]
}

​

Implemente a ferramenta de editor de texto

A ferramenta de editor de texto é implementada como uma ferramenta sem esquema, identificada por type: "text_editor_20250124". Ao usar esta ferramenta, você não precisa fornecer um esquema de entrada como com outras ferramentas; o esquema está incorporado no modelo do Claude e não pode ser modificado.

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':
        # Lê e retorna o conteúdo do arquivo
        pass
    elif command == 'str_replace':
        # Substitui texto no arquivo
        pass
    elif command == 'create':
        # Cria novo arquivo
        pass
    elif command == 'insert':
        # Insere texto na localização
        pass
    elif command == 'undo_edit':
        # Restaura do backup
        pass

# Processa uso de ferramenta na resposta do Claude
for content in response.content:
    if content.type == "tool_use":
        # Executa a ferramenta com base no comando
        result = handle_editor_tool(content)
        
        # Retorna resultado ao Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result
        }

​

Trate erros

Ao usar a ferramenta de editor de texto, vários erros podem ocorrer. Aqui está a orientação sobre como tratá-los:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Erro: Arquivo não encontrado",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Erro: Encontradas 3 correspondências para o texto de substituição. Por favor, forneça mais contexto para fazer uma correspondência única.",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Erro: Nenhuma correspondência encontrada para substituição. Por favor, verifique seu texto e tente novamente.",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Erro: Permissão negada. Não é possível escrever no arquivo.",
      "is_error": true
    }
  ]
}

​

Siga as melhores práticas de implementação

def backup_file(file_path):
    """Cria um backup de um arquivo antes de editar."""
    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):
    """Substitui texto apenas se houver exatamente uma correspondência."""
    with open(file_path, 'r') as f:
        content = f.read()
    
    count = content.count(old_text)
    if count == 0:
        return "Erro: Nenhuma correspondência encontrada"
    elif count > 1:
        return f"Erro: Encontradas {count} correspondências"
    else:
        new_content = content.replace(old_text, new_text)
        with open(file_path, 'w') as f:
            f.write(new_content)
        return "Texto substituído com sucesso"

def verify_changes(file_path):
    """Executa testes ou verificações após fazer alterações."""
    try:
        # Para arquivos Python, verifica erros de sintaxe
        if file_path.endswith('.py'):
            import ast
            with open(file_path, 'r') as f:
                ast.parse(f.read())
            return "Verificação de sintaxe passou"
    except Exception as e:
        return f"Verificação falhou: {str(e)}"

​

Preços e uso de tokens

A ferramenta de editor de texto usa a mesma estrutura de preços que outras ferramentas usadas com o Claude. Ela segue o preço padrão de tokens de entrada e saída com base no modelo do Claude que você está usando.

Além dos tokens base, os seguintes tokens de entrada adicionais são necessários para a ferramenta de editor de texto:

Para informações mais detalhadas sobre preços de ferramentas, veja Preços de uso de ferramentas.

​

Integre a ferramenta de editor de texto com uso de computador

A ferramenta de editor de texto pode ser usada junto com a ferramenta de uso de computador e outras ferramentas definidas pela Anthropic. Ao combinar essas ferramentas, você precisará:

1. Incluir o cabeçalho beta apropriado (se usar com uso de computador)
2. Corresponder a versão da ferramenta com o modelo que você está usando
3. Contabilizar o uso adicional de tokens para todas as ferramentas incluídas em sua solicitação

Para mais informações sobre o uso da ferramenta de editor de texto em um contexto de uso de computador, veja Uso de computador.

​

Registro de alterações

​

Próximos passos

Aqui estão algumas ideias de como usar a ferramenta de editor de texto de maneiras mais convenientes e poderosas:

• Integre com seu fluxo de trabalho de desenvolvimento: Incorpore a ferramenta de editor de texto em suas ferramentas de desenvolvimento ou IDE
• Crie um sistema de revisão de código: Faça o Claude revisar seu código e fazer melhorias
• Construa um assistente de depuração: Crie um sistema onde o Claude pode ajudar você a diagnosticar e corrigir problemas em seu código
• Implemente conversão de formato de arquivo: Deixe o Claude ajudar você a converter arquivos de um formato para outro
• Automatize documentação: Configure fluxos de trabalho para o Claude documentar automaticamente seu código

Enquanto você constrói aplicativos com a ferramenta de editor de texto, estamos ansiosos para ver como você aproveitará as capacidades do Claude para melhorar seu fluxo de trabalho e produtividade de desenvolvimento.