vue-componentes/.agent/tools.md

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. 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 e snap já configurados).

Linux (Debian / Ubuntu)

# 1. Atualizar e instalar ferramentas base do sistema
sudo apt-get update
sudo apt-get install -y ripgrep fd-find jq shellcheck bat tree httpie gh

# 2. Instalar ferramentas em Node
npm install -g @ast-grep/cli @biomejs/biome

# 3. Instalar yq via snap 
sudo snap install yq

macOS (via Homebrew)

# Instalar utilitários essenciais
brew install ripgrep fd ast-grep jq yq shellcheck bat tree eza httpie gh
npm install -g @biomejs/biome