Referência do sistema de ferramentas

file_read

Recursos:

• Ler o conteúdo completo de arquivos ou intervalos de linhas específicos
• Essencial para entender o código antes de fazer modificações
• Manuseio eficiente de arquivos grandes por meio da especificação de intervalos

Casos de uso:

• Ler arquivos de configuração antes de editá-los
• Entender padrões de implementação existentes
• Revisar arquivos de teste para entender a cobertura

Exemplo:

# Read entire file
file_read("src/components/Button.tsx")

# Read specific range for large files
file_read("package-lock.json", start_line=1, max_lines=50)

file_edit

Recursos:

• Substituição precisa de texto usando correspondência exata de strings
• Múltiplas operações de substituição com a flag multiple
• Preserva a estrutura e a formatação do arquivo

Casos de uso:

• Atualizar implementações de funções
• Modificar valores de configuração
• Refatorar nomes de variáveis em vários arquivos

Boa prática: Use para alterações direcionadas. Para reescritas completas, use file_write.

file_write

Recursos:

• Criar novos arquivos do zero
• Substituir completamente o conteúdo de arquivos existentes
• Lidar com qualquer formato baseado em texto

Casos de uso:

• Gerar novos componentes ou módulos
• Criar arquivos de configuração
• Escrever arquivos de teste

Aviso: Sobrescreve completamente os arquivos existentes. Use file_edit para modificações parciais.

glob

Recursos:

• Encontrar arquivos que correspondam a padrões: **/*.ts, src/**/*.js
• Filtrar por caminho de diretório
• Padrões de exclusão para restringir os resultados
• Controlar o número de resultados

Casos de uso:

• Encontrar todos os componentes em um projeto
• Localizar arquivos de teste
• Identificar arquivos de configuração em diretórios

Exemplos de padrões:

**/*.tsx          # All TypeScript React files
src/**/*.test.js  # All test files in src
**/config.*       # All config files anywhere

grep_content

Recursos:

• Buscar o conteúdo de arquivos usando padrões regex
• Mostrar linhas de contexto antes/depois das correspondências (flags -B, -A)
• Busca sem distinção entre maiúsculas e minúsculas
• Filtrar por tipo de arquivo usando padrões glob

Casos de uso:

• Encontrar definições de funções
• Localizar implementações de endpoints de API
• Buscar mensagens de erro específicas
• Identificar padrões de segurança

Exemplo:

# Find authentication-related code
grep_content("auth.*login", glob="**/*.ts")

# Search with context
grep_content("TODO", glob="src/**", context_before=2, context_after=2)

grep_file

Recursos:

• Listar arquivos que contenham correspondências de padrões
• Mais rápido que grep_content quando você só precisa das localizações dos arquivos
• Suporte a padrões regex
• Filtragem glob para tipos de arquivo

Casos de uso:

• Identificar quais arquivos precisam de refatoração
• Encontrar arquivos que importam módulos específicos
• Localizar arquivos com padrões obsoletos

Boa prática: Use grep_file primeiro para identificar os arquivos relevantes e, em seguida, file_read para um exame detalhado.

list_dir

Recursos:

• Exibir a hierarquia de diretórios
• Controlar a profundidade com o parâmetro max_depth
• Padrões de exclusão para filtrar a saída

Casos de uso:

• Entender a estrutura do projeto
• Verificar a organização dos diretórios
• Encontrar subdiretórios específicos

bash

Recursos:

• Executar comandos de shell
• Tempo limite máximo: 120 segundos (2 minutos, limite rígido)
• Encadear comandos com && para dependências
• Fornecer resumos descritivos para maior clareza

Casos de uso:

• Executar testes
• Compilar projetos
• Instalar dependências
• Operações de Git
• Migrações de banco de dados

Exemplo:

# Run tests
bash("npm test", timeout=60000, summary="Run Jest test suite")

# Chain dependent commands
bash("npm install && npm run build", timeout=120000)

Segurança: Os comandos são executados com as permissões do usuário. Revise os comandos em Manual Accept Mode.

spawn_subagent

Recursos:

• Iniciar subagentes especializados com contextos isolados
• Tipos: explorer, verifier, code-reviewer
• Delegar tarefas complexas sem poluir o contexto principal
• Execução paralela de subagentes para maior eficiência

Casos de uso:

• explorer: Buscar padrões em grandes bases de código
• verifier: Validar a lógica da implementação
• code-reviewer: Avaliação de segurança e qualidade

Boa prática: Delegue pesquisas exploratórias ao subagente Explorer para preservar o contexto da conversa principal.

todo_update

Recursos:

• Criar e gerenciar listas de tarefas
• Atualizar o status das tarefas (pending, in_progress, completed)
• Acompanhar o progresso em implementações complexas

Casos de uso:

• Dividir recursos de várias etapas
• Acompanhar o progresso da refatoração
• Gerenciar tarefas de migração

web_search

Recursos:

• Consultar mecanismos de busca na internet
• Controlar o número de resultados
• Filtrar por atualidade (dias recentes)

Casos de uso:

• Encontrar documentação de APIs desconhecidas
• Pesquisar mensagens de erro
• Verificar as melhores práticas atuais

web_fetch

Recursos:

• Recuperar o conteúdo de páginas web
• Analisar conteúdo com consultas específicas
• Extrair informações estruturadas

Casos de uso:

• Ler páginas de documentação
• Analisar a documentação de API
• Extrair exemplos de tutoriais

Formatos de dados

Arquivos de build e pacotes

Eficiência do file_read

Melhores práticas:

• Use intervalos de linhas para arquivos com mais de 500 linhas para evitar sobrecarga de contexto
• Leia apenas as seções relevantes necessárias para a tarefa
• Para arquivos grandes, use grep_content primeiro para identificar os números de linha relevantes

# Good: Read specific section
file_read("large-config.json", start_line=100, max_lines=50)

# Less efficient: Read entire large file
file_read("large-config.json")  # May consume excessive context

Precisão do file_edit

Melhores práticas:

• Garanta correspondências exatas de strings para evitar edições com falha
• Para várias alterações semelhantes, use a flag multiple=true
• Verifique os caminhos dos arquivos antes de editar

Segurança do file_write

Melhores práticas:

• Confira novamente os caminhos para evitar sobrescritas acidentais
• Use apenas para novos arquivos ou reescritas completas
• Para modificações, prefira file_edit por segurança

Especificidade dos padrões glob

Melhores práticas:

• Use padrões específicos para restringir o escopo: src/**/*.ts em vez de **/*
• Exclua diretórios com padrões de exclusão: !**/node_modules/**
• Limite os resultados para evitar saídas excessivas

# Good: Specific scope
glob("src/components/**/*.tsx", max_results=50)

# Less efficient: Too broad
glob("**/*")  # Returns thousands of results

Estratégia de grep

Fluxo de trabalho recomendado:

1. Use grep_file para identificar os arquivos relevantes
2. Leia arquivos específicos com file_read
3. Use grep_content quando precisar do contexto ao redor

Dicas de desempenho:

• Padrões regex podem levar mais tempo do que strings literais
• Buscas sem distinção entre maiúsculas e minúsculas são mais lentas
• Limite as linhas de contexto (-A, -B) ao necessário

Melhores práticas do bash

Execução segura de comandos:

• Forneça resumos claros para as descrições dos comandos
• Defina tempos limite apropriados para operações de longa duração
• Encadeie comandos dependentes com &&
• Revise comandos destrutivos com cuidado (rm, drop, truncate)

# Good: Clear summary, reasonable timeout
bash("npm run build", timeout=120000, summary="Build production bundle")

# Good: Chained dependencies
bash("npm install && npm run test", timeout=180000)

Considerações de segurança

Regras de segurança críticas:

• Os comandos são executados com as permissões do usuário
• Nunca execute comandos não confiáveis
• Use Manual Accept Mode para revisão em bases de código compartilhadas
• Evite comandos que exponham credenciais ou dados sensíveis

Eficiência na delegação de subagentes

Quando usar subagentes:

• Explorer: Buscas na base de código, questões de arquitetura (economiza o contexto principal)
• Verifier: Verificações rápidas de validação (verificação isolada)
• Code-reviewer: Revisões de segurança e qualidade (análise detalhada)
• General: Tarefas complexas de várias etapas (execução paralela)

Boa prática: Delegue tarefas exploratórias e de pesquisa a subagentes para preservar o contexto da conversa principal para o trabalho de desenvolvimento ativo.

Gerenciamento de contexto

Uso estratégico de ferramentas:

• Leia arquivos de forma estratégica — apenas o necessário
• Use subagentes para pesquisas em segundo plano
• Monitore o consumo de contexto durante sessões longas
• Divida operações complexas em etapas com todo_update

Fluxos de trabalho eficientes:

1. Planejamento: Use glob/grep para identificar o escopo
2. Leitura: Leia apenas os arquivos/seções relevantes
3. Execução: Delegue a subagentes quando apropriado
4. Verificação: Verificações rápidas com o subagente Verifier

Limites de tamanho de arquivo

Manuseio de arquivos grandes: Arquivos muito grandes (>10.000 linhas) devem ser lidos em seções para evitar:

• Esgotamento da janela de contexto
• Tempos de resposta lentos
• Problemas de memória

Padrões de tempo limite das ferramentas

Limites das ferramentas:

• Tempo limite do bash: 120 segundos (2 minutos) no máximo
• Operações com arquivos: Sem limites de tamanho (arquivos grandes são lidos automaticamente em lotes)
• Manuseio de arquivos grandes: Arquivos >256KB retornam apenas os primeiros 256KB de conteúdo
• Resultados de busca: Sem limites para resultados de glob ou grep_content
• Subagentes concorrentes: Sem limites para execução paralela

Configuração de tempo limite:

• Defina tempos limite explícitos para operações de longa duração
• Monitore processos travados
• Comandos que excedam o tempo limite de 2 minutos serão encerrados

Operações concorrentes

Execução paralela: Vários subagentes podem ser executados em paralelo para operações complexas mais rápidas. O agente principal lida automaticamente com a coordenação.

Benefícios de desempenho:

• Redução do tempo total de execução para tarefas de várias etapas
• Utilização eficiente de recursos
• Orquestração automática de tarefas
• Sem limites no número de subagentes concorrentes