Ferramentas do dev¶

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-09-25

Aplica-se a: todo repo em que um agente de IA trabalha.

As receitas que operacionalizam a disciplina do agente: o rtk corta o que entra no contexto (recomendado, opt-in de máquina), o caveman injeta o estilo terso (opcional), o javap confere API de terceiro, e o .claude/settings.json separa o compartilhado do pessoal. rtk e caveman são de máquina de dev; a exceção é o hook do caveman, versionável por repo.

rtk — corta o input¶

Proxy que resume a saída de CLI antes de ela entrar no contexto do agente.

Instalar¶

Repo canônico: rtk-ai/rtk.

macOS / Linux: brew install rtk — ou curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh.
Cargo: cargo install --git https://github.com/rtk-ai/rtk.
Windows: rtk-x86_64-pc-windows-msvc.zip dos releases, rtk.exe no PATH.

rtk --version   # rtk 0.40+
rtk gain         # se falhar, é outro "rtk" (colisão com o Rust Type Kit)

Habilitar (hook transparente)¶

rtk init -g       # instala o hook PreToolUse no config global do Claude Code

Reinicie o Claude Code e confira no ~/.claude/settings.json o PreToolUse → "rtk hook claude": sem o hook ativo a economia é ~0. Dry-run: rtk hook check './gradlew check'.

Configurar¶

rtk config --create cria o arquivo (~/.config/rtk/config.toml; no Windows, %APPDATA%\rtk\config.toml — rtk config mostra o caminho); o padrão da casa ignora os diretórios gerados de toda stack:

[filters]
ignore_dirs = [".git", "node_modules", "target", "build", ".gradle", ".dart_tool",
               "__pycache__", ".venv", "vendor"]

[tee]
enabled = true
mode = "failures"   # em falha, salva o log cheio num tee-file

Regras por stack¶

O hook só corta o comando que ele vê. Furam o hook: | pipe, &&/;, $(...) e prefixo de env (JAVA_HOME=… ./gradlew).

Stack	Regra
Java / Gradle	`./gradlew check` bare. Sem prefixo `JAVA_HOME=…` (fura o hook e o allow-list): use `sdk default java 25` na máquina ou `JAVA_HOME` no `.claude/settings.local.json`. No Windows, o `rtk gradlew` trava (rtk 0.43: mais de 10 min sem saída, contra 33 s direto): rode `.\gradlew.bat check --console=plain` pela ferramenta PowerShell, que o hook não reescreve, ou tire o Gradle da reescrita com `exclude_commands = ["./gradlew"]` na seção `[hooks]` do config (o match é o comando literal: `"gradlew"` não exclui). Confira com `rtk hook check './gradlew check'`.
Flutter	o `rtk` não cobre `flutter`: `flutter test -r failures-only` na fonte.
git	`git diff`/`git status` bare; evite `--porcelain` (o rtk colapsa a lista).
arquivos	Read/Grep/Glob nativos, não `cat`/`sed`/`grep -rn`/`find`.

Comando sem handler (mkdocs, python3, node, os gates): rtk err <cmd> (só erros e avisos; uma linha no sucesso) ou rtk summary <cmd>. Ex.: rtk err mkdocs build --strict. Medir: rtk gain e rtk discover.

caveman — corta o output (opcional)¶

Injeta a regra de estilo terso (Agentes). O mecanismo recomendado é um hook SessionStart, sem plugin — .claude/caveman.sh:

#!/usr/bin/env bash
# Injeta a regra de estilo terso da casa em toda sessão de agente.
cat <<'EOF'
Responda terso: dropa artigo, filler, gentileza, hedging. Fragmentos OK. Termo técnico exato.
Padrão: [coisa] [ação] [razão]. [próximo passo].
VERBATIM (nunca comprimir): conteúdo de docs/, código, nomes de API/CLI, tipos de commit, strings de
erro, a mensagem de commit pronta e a linha de feedback, tabelas de dado, specs/planos .ia/.
Desligar na sessão: "stop caveman".
EOF

Entrada no array SessionStart do .claude/settings.json, somada às que existam:

{ "hooks": { "SessionStart": [ { "hooks": [
  { "type": "command", "command": "bash .claude/caveman.sh" }
] } ] } }

Plugin (atalho /caveman lite|full|ultra): juliusbrussee/caveman — claude plugin marketplace add JuliusBrussee/caveman && claude plugin install caveman@caveman. O caveman-init não serve para o Claude Code. Com o plugin, o modo vem de CAVEMAN_DEFAULT_MODE → .caveman.json do repo → config do usuário → full.

javap — verificar API de terceiro sem sources jar¶

Antes de contratar um método de lib de terceiro numa receita ou em código, confira a assinatura no bytecode — o javap (do JDK) lê direto o .jar do cache do Gradle:

find ~/.gradle -name 'sentry-8.42.0.jar'
javap -cp ~/.gradle/caches/modules-2/files-2.1/io.sentry/sentry/8.42.0/*/sentry-8.42.0.jar \
  io.sentry.SentryOptions | grep -E 'setTag|getTags|isSendDefaultPii|setDiagnosticLevel'

No Windows, ajuste o caminho do cache (%USERPROFILE%\.gradle\...).

`.claude/settings.json` — versionado enxuto, pessoal fora¶

Versionado (.claude/settings.json) — só o compartilhado. A base é o template do kit templates/settings.json: env e o allow-list por ferramenta (Bash(git *), Bash(python *), Bash(mkdocs *), Bash(curl * https://docs.xadm.biz/*)…, espelhados em PowerShell(...)), sem o bloco hooks — o SessionStart do checa-constituicao.sh é cravado pela instalação (/xadm-docs), que preserva os hooks e grants que o repo já tem. Adições por stack, cada uma nos dois namespaces: Java/Gradle ./gradlew *, java *, jar *, javap *, unzip *; Flutter/Dart flutter *, dart *; Node npm *.
Por ferramenta, não por prefixo de argumento: regra por prefixo exato (python3 scripts/*) quebra a cada variação de forma (python/py no Windows, npm i × npm install) e volta a pedir prompt no meio da /xadm-release. O curl fica escopado em docs.xadm.biz. Comando composto continua pedindo prompt.
CLI Python: bare primeiro, python -m <mod> no fallback — no Windows com Python da Microsoft Store o Scripts\ não entra no PATH e mkdocs dá "command not found" com o pacote instalado; python -m mkdocs é o mesmo binário, e o allow-list tem as duas formas.
Pessoal (.claude/settings.local.json) — grants de máquina, caminhos absolutos, experimentos; nunca versionado (a linha exata .claude/settings.local.json no .gitignore; o pipeline.yml reprova o arquivo rastreado). Moram aqui:

"env": { "JAVA_HOME": "C:\\Dev\\graalvm-jdk-25.0.3" },
"permissions": { "allow": [ "Read(//c/Users/<voce>/.claude/projects/<slug>/**)" ] }

env.JAVA_HOME quando o JDK padrão da máquina difere da toolchain do app (sem ele o agente prefixa JAVA_HOME=… e perde o allow-list); Read(...) para o agente ler a própria memória sem prompt. - Proibido no versionado: grant hiper-específico (comando com hash, caminho de scratchpad). Ele suja o git a cada sessão e força git commit --amend, que troca o hash sob a tag da release. Comando novo frequente: alargue o padrão. - Settings editado entra no commit: se a sessão mexeu no settings.json rastreado, ele vai no mesmo commit do trabalho. Bash(git *) tira o prompt de commit/push; a REGRA Nº 2 continua valendo.