Domínio 2 — Tool Design & MCP Integration · Lição 6 de 6

Built-in tools: Read, Write, Edit, Bash, Grep e Glob

Objetivos de aprendizagem

• Selecionar Grep para busca de conteúdo e Glob para padrões de caminho/nome de arquivo.
• Usar Read/Write para operações de arquivo inteiro e Edit para modificações pontuais por correspondência de texto única.
• Aplicar o fallback Read + Write quando Edit falha por match não único.
• Construir entendimento do codebase incrementalmente: começar com Grep nos pontos de entrada e seguir imports com Read, em vez de ler tudo de antemão.
• Rastrear uso de funções através de módulos wrapper: identificar os nomes exportados e buscar cada um no codebase.

Qual ferramenta para qual pergunta

Edit exige match único — e o fallback Read + Write

Edit substitui um trecho localizado por correspondência exata de texto. Se o texto-âncora aparece 0 vezes (âncora errada/desatualizada) ou mais de 1 vez (âncora ambígua), a edição falha — de propósito, para não alterar o lugar errado. Estratégias, em ordem:

1. Ampliar a âncora com linhas vizinhas até ficar única.
2. Quando não dá para tornar a âncora única de forma confiável: Read do arquivo inteiro + Write do conteúdo completo modificado — o fallback determinístico cobrado no exame.

O mesmo contrato aparece na text editor tool da API (str_replace: erro se 0 ou >1 ocorrências). Handler de referência:

from pathlib import Path

def str_replace(path: str, old_str: str, new_str: str) -> dict:
    """Contrato do Edit/str_replace: exatamente 1 ocorrencia, senao erro."""
    text = Path(path).read_text(encoding="utf-8")
    count = text.count(old_str)
    if count == 0:
        return {
            "is_error": True,
            "content": "Nenhuma ocorrencia da ancora. Releia o arquivo (Read) "
                       "e use uma ancora atualizada, ou caia para Read + Write.",
        }
    if count > 1:
        return {
            "is_error": True,
            "content": f"{count} ocorrencias da ancora (ambigua). Amplie a ancora "
                       "com linhas vizinhas ou use Read + Write do arquivo inteiro.",
        }
    Path(path).write_text(text.replace(old_str, new_str, 1), encoding="utf-8")
    return {"is_error": False, "content": "Edicao aplicada com sucesso."}

# Fallback deterministico quando a ancora nao pode ser tornada unica:
def read_write_fallback(path: str, transform) -> None:
    original = Path(path).read_text(encoding="utf-8")
    Path(path).write_text(transform(original), encoding="utf-8")

Exploração incremental do codebase

Ler todos os arquivos de antemão estoura o contexto e dilui a atenção. O fluxo eficiente é incremental:

flowchart TD
    A[Grep: localizar pontos de entrada\nex.: nome da função, mensagem de erro] --> B[Read: abrir só os arquivos com hit]
    B --> C[Seguir imports relevantes com Read]
    C --> D{Entendimento suficiente?}
    D -- não --> A
    D -- sim --> E[Editar com Edit\nou Read + Write]
  

1. Grep pelo sintoma (nome de função, mensagem de erro, import) para achar pontos de entrada.
2. Read apenas nos arquivos com hit; siga os imports que importam para o fluxo.
3. Repita Grep→Read conforme novas pistas surgem — nunca "ler tudo primeiro".

Rastreando wrappers: quando um módulo re-exporta funções (barrel files, wrappers), primeiro identifique todos os nomes exportados (Grep por export no módulo), depois faça Grep de cada nome no codebase — buscar só o nome original perde os call sites que usam o nome re-exportado.

Pegadinhas da prova

• Distrator típico: usar Glob para achar onde uma função é chamada. Glob casa caminhos, não conteúdo — chamadas de função se acham com Grep.
• Distrator típico: quando Edit falha por match duplicado, "rodar o Edit duas vezes" ou "usar replace_all". A resposta cobrada: ampliar a âncora ou cair para Read + Write do arquivo inteiro.
• Distrator típico: "leia todos os arquivos do diretório antes de começar". Exploração incremental (Grep → Read seguindo imports) preserva contexto e escala.
• Pegadinha: Write sobrescreve o arquivo inteiro — no fallback, sempre Read antes para partir do conteúdo atual completo.
• Pegadinha: rastrear uma função re-exportada buscando apenas o nome original perde os call sites do alias — enumere os exports primeiro.

Resumo em 5 linhas

Documentação oficial

• Claude Code — ferramentas disponíveis e settings
• Claude Code — common workflows (explorar codebases)
• Text editor tool (contrato str_replace)

Questões de fixação