🛠️ Comandos e Ferramentas

Os parametros da ferramenta Read: file_path (obrigatorio), offset (linha inicial) e limit (numero de linhas).

Dominar os parametros permite ler arquivos grandes de forma eficiente, economizando tokens e contexto.

Caminho absoluto, offset base 1, limite de 2000 linhas padrao, truncamento automatico.

Claude Code e multimodal e pode ler imagens diretamente, interpretando seu conteudo visual.

Permite analisar screenshots de erros, diagramas de arquitetura, mockups de UI e mais.

Formatos suportados: PNG, JPG, GIF, WebP. Analise de screenshots, OCR implicito.

Read processa PDFs pagina por pagina, extraindo texto e conteudo visual.

Ideal para analisar documentacao, especificacoes tecnicas e relatorios diretamente do terminal.

Extracao de texto, analise visual de graficos, processamento pagina a pagina.

Read interpreta notebooks Jupyter, mostrando celulas, codigo, markdown e outputs.

Perfeito para projetos de data science, analise de dados e machine learning.

Celulas code/markdown, outputs preservados, visualizacoes inline, NotebookEdit para edicao.

Estrategias para ler apenas o necessario, usando offset/limit e leituras paralelas.

Evita desperdicar contexto lendo arquivos inteiros quando so precisa de trechos especificos.

Leitura parcial, chamadas paralelas, 2000 caracteres por linha max, arquivos vazios.

Problemas frequentes: caminhos relativos, arquivos inexistentes, diretorios vs arquivos.

Conhecer os erros comuns acelera a depuracao e evita frustracao.

Sempre usar caminhos absolutos, verificar existencia, Read nao le diretorios.

Write cria novos arquivos ou sobrescreve existentes completamente. Usa file_path e content.

Essencial para criar novos componentes, configs, scripts e qualquer arquivo do zero.

Caminho absoluto, sobrescrita total, preferir Edit para existentes.

Edit faz substituicoes exatas de strings. Usa old_string, new_string e replace_all.

Permite modificar trechos especificos mantendo o resto intacto - mais seguro que Write.

Unicidade de old_string, preserve indentacao, leia antes de editar.

Criterios para escolher entre Write e Edit baseado no escopo da mudanca.

Escolha errada pode perder codigo ou causar erros. Edit e mais seguro para existentes.

Write para novos, Edit para existentes, tamanho do arquivo.

Edit exige que old_string seja unico no arquivo. Se nao for, a edicao falha.

Evita editar o trecho errado. Adicione contexto para garantir unicidade.

Incluir linhas antes/depois, replace_all para todas ocorrencias.

Edit exige correspondencia exata de espacos e tabs. Copie do Read exatamente.

Indentacao errada causa "old_string not found" mesmo que o texto pareca igual.

Copiar apos tab do numero de linha, manter espacos, verificar tabs vs espacos.

Erros frequentes: arquivo nao lido, string nao encontrada, nao unica, identica.

Conhecer erros acelera debug e evita frustracao durante desenvolvimento.

Sempre Read primeiro, verificar espacos, adicionar contexto.

Glob encontra arquivos por padrao de nome. Ex: **/*.js, src/**/*.ts

Essencial para descobrir estrutura de projetos e encontrar arquivos rapidamente.

Padroes glob, ordenacao por data, ** para recursivo.

Grep busca texto dentro de arquivos usando regex. Baseado em ripgrep.

Encontra funcoes, classes, TODOs e qualquer texto em projetos grandes.

Pattern regex, output_mode, filtros glob/type, case insensitive.

Grep tem 3 modos: files_with_matches (nomes), content (linhas), count (quantidade).

Escolha o modo certo para economizar contexto e obter informacao necessaria.

files_with_matches default, content com -A/-B/-C, count para estatisticas.

Sintaxe ripgrep para buscas: \s, \w, +, *, |, escapar caracteres especiais.

Regex poderoso permite buscas complexas como "def func(" ou "TODO|FIXME".

function\s+\w+, escapar {}, multiline mode para padroes multi-linha.

Combinacao eficiente: Glob para estrutura, Grep para localizar, Read para contexto.

Economia maxima de contexto: so le o trecho necessario apos localizar.

Glob descobre, Grep localiza, Read le trecho com offset/limit.

Parametros para limitar resultados: head_limit, offset, type, glob filter.

Projetos grandes podem retornar milhares de resultados - limite para eficiencia.

head_limit=10, type="ts", multiline para padroes cross-line.

Bash executa comandos do sistema. Parametros: command, timeout, description, run_in_background.

Acesso a npm, git, docker, python e qualquer ferramenta do terminal.

Command obrigatorio, timeout em ms, description para clareza.

Timeout padrao 120000ms (2min), maximo 600000ms (10min). Output truncado em 30000 chars.

Comandos longos como build precisam timeout maior ou background execution.

Aumentar timeout para builds, usar background para operacoes longas.

Operadores shell: && (se sucesso), ; (sempre), || (se falha).

Executar sequencias de comandos de forma controlada em uma unica chamada.

Preferir &&, evitar newlines entre comandos, usar ; quando erro OK.

CWD persiste entre comandos, mas estado do shell nao. Prefira caminhos absolutos.

Evita confusao de diretorio e erros de "arquivo nao encontrado".

Evitar cd, usar paths absolutos, aspas para espacos.

Modos de permissao: Ask (pede confirmacao), Bypass (whitelist), YOLO (tudo permitido).

Bash pode executar qualquer comando - entender permissoes evita acidentes.

Comandos destrutivos, rm -rf, force push, protecoes do Claude Code.

Use ferramentas dedicadas (Read, Glob, Grep) em vez de cat, find, grep via Bash.

Ferramentas dedicadas sao otimizadas e evitam problemas de permissao.

Bash para builds, testes, git. Read/Glob/Grep para arquivos.

Regras de seguranca: nunca force push, reset hard, checkout ., branch -D, --no-verify.

Protege repositorio de acoes destrutivas que podem perder codigo.

Nao modificar git config, criar commits novos, adicionar arquivos especificos.

Processo: git status, git diff, git add especifico, git commit com HEREDOC.

Commits bem feitos facilitam historico e revisao de codigo.

HEREDOC para mensagens, Co-Authored-By, evitar git add -A.

Gerenciamento de branches: checkout -b, switch, merge, branch -d (minusculo).

Branches permitem trabalho isolado sem afetar main.

-d vs -D, evitar rebase -i, merge seguro.

gh CLI para GitHub: gh pr view, gh issue list, gh api para endpoints.

Mais eficiente que WebFetch para GitHub, tem autenticacao configurada.

gh pr, gh issue, gh api, preferir sobre WebFetch para GitHub.

Criar PRs com gh pr create: titulo curto, body com Summary e Test plan.

PRs bem estruturados facilitam code review e merge.

Titulo < 70 chars, Summary com bullets, Test plan checklist.

Quando hook falha, commit NAO foi criado. Criar NOVO commit, nunca --amend.

--amend apos hook falhar modifica commit ANTERIOR, perdendo trabalho.

Corrigir problema, re-stage, novo commit (sem --amend).

WebSearch busca na internet. Parametros: query, allowed_domains, blocked_domains.

Acesso a documentacao atualizada, informacoes alem do cutoff do modelo.

Query minimo 2 chars, filtrar dominios, incluir ano nas buscas.

WebFetch acessa URL, converte para markdown, processa com prompt.

Extrai informacoes especificas de paginas web diretamente.

URL completa, prompt de extracao, HTML para markdown.

WebFetch NAO funciona para: URLs autenticadas, GitHub, paginas com login, SPAs.

Evita erros e frustacao tentando acessar conteudo inacessivel.

Use gh CLI para GitHub, curl com token para APIs autenticadas.

WebFetch tem cache de 15 minutos. Redirects sao informados para nova request.

Cache economiza requests, entender redirects evita erros.

Auto-limpeza, HTTP para HTTPS automatico, tratar redirects.

Boas queries: inclua ano, seja especifico, termos tecnicos corretos.

Queries melhores = resultados mais relevantes e atualizados.

Incluir "2026", filtrar dominios, incluir Sources: na resposta.

Para servicos autenticados: gh CLI (GitHub), curl com token, ferramentas MCP.

Permite acessar APIs privadas e servicos que requerem autenticacao.

gh para GitHub, curl -H Authorization, MCP tools especializadas.

TaskCreate cria tarefas estruturadas. Campos: subject, description, activeForm.

Organiza projetos complexos, mostra progresso ao usuario.

Subject imperativo, activeForm continuo, description detalhada.

TaskUpdate modifica tarefas. Status: pending -> in_progress -> completed.

Acompanha progresso real, so marcar completed quando terminado.

Fluxo linear de status, nao completar com erros, deleted para remover.

TaskList mostra todas tarefas. TaskGet traz detalhes de uma tarefa especifica.

Permite ver panorama geral e detalhes antes de comecar trabalho.

TaskList para overview, TaskGet para requisitos completos.

Tarefas podem bloquear ou ser bloqueadas por outras usando addBlocks/addBlockedBy.

Garante ordem correta de execucao em projetos com dependencias.

A blocks B = B espera A. A blockedBy B = A espera B.

Use Task para 3+ passos distintos, planejamento necessario, multiplas tarefas.

Evita overhead desnecessario em tarefas simples.

Nao usar para tarefas triviais, so quando tracking agrega valor.

Subagentes trabalham em tarefas especializadas com contexto isolado.

Permite execucao paralela e especializacao em tarefas complexas.

Pesquisa, analise, geracao de testes, refatoracao isolada.

Pergunte quando: ambiguo/critico, afeta arquitetura, credenciais, irreversivel.

Perguntas desnecessarias interrompem fluxo. Agir > perguntar quando possivel.

Nao perguntar se pode inferir, se trivial, se CLAUDE.md define.

Boa pergunta: contexto do que sabe, opcoes claras, trade-offs, recomendacao.

Perguntas claras recebem respostas uteis, economizam iteracoes.

Evitar "como fazer?", dar opcoes especificas com pros/contras.

Modos de permissao: Ask pede confirmacao, Bypass usa whitelist, YOLO tudo permitido.

Entender quando e por que Claude pede confirmacao antes de agir.

Write, Bash, Git pedem confirmacao em Ask mode.

Estrategias: usar contexto do projeto, inferir padroes, agrupar perguntas.

Muitas perguntas frustram usuario e interrompem fluxo de trabalho.

Fazer escolha razoavel e explicar, agrupar perguntas relacionadas.

CLAUDE.md bem configurado elimina perguntas sobre stack, convencoes, preferencias.

Documentar preferencias antecipadamente evita interrupcoes.

Stack, convencoes, comandos build/test, bibliotecas preferidas.

Comunicacao constante: mostrar progresso, confirmar resultados, oferecer ajustes.

Feedback proativo mantem usuario informado sem perguntas explicitas.

"Vou fazer X", "Fiz X, quer ajustar?", antecipar informacao.