.

TOOLS.md

@@ -0,0 +1,133 @@
+# 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 open --headed <url>`) ou defina `export AGENT_BROWSER_HEADED=true`.
+- **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. 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 para IA (visível com --headed)
+bun i -g agent-browser && 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 && agent-browser install
+```