165 lines
11 KiB
Text
165 lines
11 KiB
Text
# Ferramentas Recomendadas para Otimização de IAs no Desenvolvimento
|
||
|
||
Este documento lista ferramentas de linha de comando (CLI) e utilitários que otimizam significativamente o trabalho e a integração de Agentes de IA durante o processo de desenvolvimento. Todas as ferramentas listadas possuem suporte nativo para **Linux** e **macOS**.
|
||
|
||
## 1. Busca e Navegação de Código
|
||
|
||
### ripgrep (`rg`)
|
||
- **Descrição:** Uma ferramenta de busca orientada a linhas que busca recursivamente no diretório atual por uma expressão regular.
|
||
- **Por que ajuda as IAs:** É extremamente rápida para encontrar referências de código, funções e variáveis em repositórios grandes. Ajuda as IAs a varrer bases de código rapidamente sem precisar ler todos os arquivos.
|
||
- **Instalação:**
|
||
- **Mac:** `brew install ripgrep`
|
||
- **Linux (Ubuntu/Debian):** `sudo apt-get install ripgrep`
|
||
|
||
### fd
|
||
- **Descrição:** Uma alternativa simples, rápida e amigável ao comando `find`.
|
||
- **Por que ajuda as IAs:** Permite que as IAs listem a estrutura de arquivos e localizem caminhos específicos com uma sintaxe muito mais amigável e saída mais rápida e limpa que o `find` tradicional, respeitando o `.gitignore` nativamente.
|
||
- **Instalação:**
|
||
- **Mac:** `brew install fd`
|
||
- **Linux (Ubuntu/Debian):** `sudo apt-get install fd-find`
|
||
|
||
### ast-grep (`sg`)
|
||
- **Descrição:** Uma ferramenta de busca e substituição de código baseada em Árvore de Sintaxe Abstrata (AST).
|
||
- **Por que ajuda as IAs:** Diferente do regex padrão, permite que a IA faça buscas estruturais e refatorações complexas compreendendo a semântica da linguagem.
|
||
- **Instalação:**
|
||
- **Mac/Linux:** `npm install -g @ast-grep/cli` ou `brew install ast-grep`
|
||
|
||
## 2. Processamento de Dados
|
||
|
||
### jq
|
||
- **Descrição:** Um processador JSON de linha de comando leve e flexível.
|
||
- **Por que ajuda as IAs:** Sistemas baseados em agentes interagem frequentemente por payloads JSON e chamadas de API. O `jq` é a ferramenta perfeita para que a IA filtre, extraia e transforme grandes payloads de dados diretamente no terminal.
|
||
- **Instalação:**
|
||
- **Mac:** `brew install jq`
|
||
- **Linux (Ubuntu/Debian):** `sudo apt-get install jq`
|
||
|
||
### yq
|
||
- **Descrição:** Uma extensão leve e portável do `jq` voltada para o processamento de arquivos YAML, JSON e XML.
|
||
- **Por que ajuda as IAs:** Útil para a IA inspecionar, modificar e gerar configurações como `docker-compose.yml`, esquemas de CI/CD, e manifestos Kubernetes.
|
||
- **Instalação:**
|
||
- **Mac:** `brew install yq`
|
||
- **Linux:** O binário é baixado direto da distribuição oficial no Github ou via snap.
|
||
|
||
## 3. Qualidade de Código e Formatação
|
||
|
||
### Biome
|
||
- **Descrição:** Ferramenta All-in-One super rápida para formatação e linting de projetos Web (JavaScript, TypeScript, JSX, JSON).
|
||
- **Por que ajuda as IAs:** Como exigido pelos padrões do projeto, garante que o código escrito pela IA passe pela validação, sendo auto-focado e sem configurações complexas (`biome check --write`).
|
||
- **Instalação:**
|
||
- **Mac/Linux:** `npm install -g @biomejs/biome` ou gerenciamento local (`pnpm add -D @biomejs/biome`).
|
||
|
||
### ShellCheck
|
||
- **Descrição:** Ferramenta de análise estática e linting projetada especificamente para scripts de shell (bash/sh).
|
||
- **Por que ajuda as IAs:** Assegura que scripts bash gerados por IAs (seja para deploy ou testes de automação de fluxo) sigam as melhores práticas e não tenham comandos perigosos implícitos.
|
||
- **Instalação:**
|
||
- **Mac:** `brew install shellcheck`
|
||
- **Linux (Ubuntu/Debian):** `sudo apt-get install shellcheck`
|
||
|
||
## 4. Visualização e Visualização de Texto
|
||
|
||
### bat
|
||
- **Descrição:** Um clone do `cat` com suporte nativo a syntax highlighting (destaque de sintaxe) e integração com o Git.
|
||
- **Por que ajuda as IAs:** Ao extrair ou ler recortes de arquivos e logs, o conteúdo é formatado de maneira que facilita eventuais inspeções humanas e recortes por linhas (`bat -r <linha_inicio>:<linha_fim>`).
|
||
- **Instalação:**
|
||
- **Mac:** `brew install bat`
|
||
- **Linux (Ubuntu/Debian):** `sudo apt-get install bat`
|
||
|
||
### tree / eza
|
||
- **Descrição:** Utilitários para listar o conteúdo de diretórios. O `eza` é um substituto moderno para o `ls` com suporte de árvore.
|
||
- **Por que ajuda as IAs:** Permitir que agentes mapeiem mentalmente a árvore de projeto de forma clara. Essencial para IAs auto-localizarem módulos arquiteturais.
|
||
- **Instalação:**
|
||
- **Mac:** `brew install eza tree`
|
||
- **Linux (Ubuntu/Debian):** `sudo apt-get install tree eza`
|
||
|
||
## 5. Integração com APIs e Git
|
||
|
||
### HTTPie / cURL
|
||
- **Descrição:** Ferramenta gráfica ou cli para o teste de endpoints, sendo o HTTPie uma versão "humanizada" do cURL.
|
||
- **Por que ajuda as IAs:** Auxilia nas IAs de codificação que necessitam conferir os status e formatos dos endpoints REST antes de gerar lógicas assíncronas no front-end ou back-end.
|
||
- **Instalação (HTTPie):**
|
||
- **Mac:** `brew install httpie`
|
||
- **Linux:** `sudo apt-get install httpie`
|
||
|
||
### GitHub CLI (`gh`)
|
||
- **Descrição:** Interface de linha de comando nativa para interagir com repositórios no GitHub.
|
||
- **Por que ajuda as IAs:** Permite à IA criar pull requests, listar issues e manipular webhooks diretamente do terminal como parte de fluxos autonomos de entrega contínua.
|
||
- **Instalação:**
|
||
- **Mac:** `brew install gh`
|
||
- **Linux:** `sudo apt install gh`
|
||
|
||
---
|
||
|
||
## 6. Automação e Testes de Interface (Browser)
|
||
|
||
### agent-browser
|
||
- **Descrição:** CLI de automação de navegadores baseada em Rust, projetada especificamente para Agentes de IA.
|
||
- **Por que ajuda as IAs:** Utiliza representação compacta da árvore de acessibilidade com referências determinísticas (`@e1`, `@e2`), consumindo 200–400 tokens (até 90% menos tokens que a leitura do DOM completo). Permite executar testes E2E, interagir com telas, validar fluxos e registrar evidências visuais.
|
||
- **Modo Visível Obrigatório:** Para que o operador acompanhe cada teste em tempo real na tela, execute sempre com a flag `--headed` (ex: `agent-browser --session <modulo>_<contexto?> open --headed <url>`) ou defina `export AGENT_BROWSER_HEADED=true`.
|
||
- **Isolamento Mandatório de Sessão e Contexto:** Toda execução DEVE acompanhar a flag `--session <modulo>_<contexto?>` (onde `<modulo>` é o `modulo-id` extraído de `memorias-ia/modulo.yml` e `<contexto?>` discrimina acessos como `interno`, `externo`, `cliente`, `anonimo`) ou garantir `export AGENT_BROWSER_SESSION=<modulo>_<contexto?>`. Previne fechamento indevido de processos e contaminação cruzada de cookies e tokens JWT entre diferentes perfis de usuário.
|
||
- **Pasta Obrigatória de Evidências (`.evidencias/`):** Todas as evidências geradas pelos testes automatizados (screenshots, capturas anotadas, vídeos, traces, relatórios) devem ser salvas obrigatoriamente na pasta `.evidencias/` na raiz do projeto (`mkdir -p .evidencias`).
|
||
- **Instalação:**
|
||
- Com Bun (padrão): `bun i -g agent-browser && agent-browser install`
|
||
- Com NPM: `npm install -g agent-browser && agent-browser install`
|
||
- **Documentação:** https://agent-browser.dev/
|
||
|
||
---
|
||
|
||
## 7. Utilitários Nativos do Framework .agent
|
||
|
||
### atualizar-submodulo.sh (`.agent/scripts/atualizar-submodulo.sh`)
|
||
- **Descrição:** Script de ciclo de vida acionado automaticamente via hook `PreInvocation` (`.agent/hooks.json`) ou manualmente via CLI.
|
||
- **Por que ajuda as IAs e Operadores:** Garante que o submódulo `.agent` esteja sincronizado na branch `master` remota no início de cada sessão de conversa (`1x por sessão`) e verifica automaticamente **uma vez por dia** se o runtime Bun está atualizado na versão estável mais recente executando `bun upgrade --stable` (controlado via trava diária `/tmp/.antigravity_bun_upgrade_date`).
|
||
- **Uso:** `bash .agent/scripts/atualizar-submodulo.sh`
|
||
|
||
### notificar.sh (`.agent/notificar.sh`)
|
||
- **Descrição:** Utilitário unificado de notificação para o Sistema Operacional, compatível nativamente com **Linux** e **macOS**.
|
||
- **Por que ajuda as IAs e Operadores:** Permite que comandos de longa duração (como `/plano.executar todos` e loops `/goal`) avisem o operador imediatamente no momento da conclusão, emitindo popup no desktop (KDE `kdialog`, FreeDesktop `notify-send` / `gdbus`, macOS Notification Center via `osascript`), som de alerta discreto (PipeWire, PulseAudio ou macOS `afplay`) e campainha no terminal (`\a`). Totalmente assíncrono, não-bloqueante e seguro para ambientes headless.
|
||
- **Uso:** `sh .agent/notificar.sh "<Título>" "<Mensagem>" [sucesso|aviso|erro]`
|
||
|
||
### upload-paiol-wiki.sh (`.agent/scripts/upload-paiol-wiki.sh`)
|
||
- **Descrição:** Utilitário de linha de comando para upload de arquivos e mídias da Wiki para o bucket público `wiki` no MinIO Paiol (`https://paiol.idz.one/wiki/...`).
|
||
- **Por que ajuda as IAs e Operadores:** Previne o inchaço (*bloat*) do Git da Wiki desacoplando binários pesados (PDFs, imagens em alta resolução, vídeos, capturas de tela e anexos), gerando links e snippets Markdown prontos para inclusão imediata na documentação.
|
||
- **Uso:** `sh .agent/scripts/upload-paiol-wiki.sh <caminho-do-arquivo> <slug-funcionalidade-ou-pagina> [modulo-override]`
|
||
|
||
### graphify.sh (`.agent/scripts/graphify.sh`)
|
||
- **Descrição:** Utilitário canônico de Grafo de Conhecimento (*Knowledge Graph*) do código-fonte baseado em `@sentropic/graphify`.
|
||
- **Por que ajuda as IAs:** Permite que o comando `/plano` e os agentes localizem símbolos, mapeiem dependências entre pacotes e calculem o raio de impacto em cascata (*Blast Radius*) em segundos sem varreduras cegas. Instala automaticamente o binário via Bun (`bun i -g @sentropic/graphify`) caso não exista na máquina, atualiza o `.gitignore` (`.graphify/`, `.engram/`, `graphify-out/`) e gera o grafo sob demanda (`ensure`).
|
||
- **Uso:**
|
||
- `bash .agent/scripts/graphify.sh update` (reconstrói/atualiza o grafo AST)
|
||
- `bash .agent/scripts/graphify.sh ensure` (garante instalação, `.gitignore` e grafo existente)
|
||
- `bash .agent/scripts/graphify.sh query "<termo>" [budget]` (busca nós e arquivos no grafo)
|
||
- `bash .agent/scripts/graphify.sh explain "<simbolo-ou-arquivo>"` (detalha conexões e imports)
|
||
- `bash .agent/scripts/graphify.sh impact <arq1> [arq2...]` (calcula raio de impacto e lacunas de testes via `review-delta`)
|
||
- `bash .agent/scripts/graphify.sh summary` (exibe principais hubs e comunidades do projeto)
|
||
|
||
---
|
||
|
||
## 8. Instalação Rápida (Copia e Cola)
|
||
|
||
Para instalar as ferramentas base de forma ágil e em lote, copie os blocos de comando abaixo e os rode inteiramente em seu terminal (requer `npm`, `bun` e `snap` já configurados).
|
||
|
||
### Linux (Debian / Ubuntu)
|
||
|
||
```bash
|
||
# 1. Atualizar e instalar ferramentas base do sistema
|
||
sudo apt-get update
|
||
sudo apt-get install -y ripgrep fd-find jq shellcheck bat tree eza httpie gh
|
||
|
||
# 2. Instalar ferramentas em Node
|
||
npm install -g @ast-grep/cli @biomejs/biome
|
||
|
||
# 3. Instalar automação de navegador e Grafo de Conhecimento para IA via Bun
|
||
bun i -g agent-browser @sentropic/graphify && agent-browser install
|
||
|
||
# 4. Instalar yq via snap
|
||
sudo snap install yq
|
||
```
|
||
|
||
### macOS (via Homebrew)
|
||
|
||
```bash
|
||
# Instalar utilitários essenciais
|
||
brew install ripgrep fd ast-grep jq yq shellcheck bat tree eza httpie gh
|
||
npm install -g @biomejs/biome
|
||
bun i -g agent-browser @sentropic/graphify && agent-browser install
|
||
```
|