Boas Práticas no Desenvolvimento com Agentes

Um guia prático para manter fluxos de trabalho eficientes ao integrar LLMs, servindo como base para as heurísticas detalhadas em harness-llm.

No ecossistema de desenvolvimento guiado por Agentes (Inteligências Artificiais Autônomas e Subagentes), algumas práticas são essenciais para garantir um workflow eficiente, seguro e contínuo.

Contexto e Estado

Documentação Master (CLAUDE.md / DESIGN.md): Agentes são amnésicos por padrão. Todas as regras de negócio, heurísticas de estilo, permissões e processos críticos de um projeto devem estar firmemente ancoradas em arquivos de instrução mestre, preferencialmente usando Markdown.
Skills (Customizações): Isolar fluxos de trabalho complexos (como compilação, validação de interface, deploys) em Skills dedicadas na pasta .claude/skills/. O CLAUDE.md age como o roteador apontando para elas.
Micro-validação: Agentes tendem a falhar ou alucinar silenciosamente. Implemente validação forçada após cada bloco de edição de código (usando Lint, Testes Unitários ou ferramentas de inspeção como Playwright).

Tratamento de Falhas e Cache

O cache do Node.js, npm run dev rodando em background e instâncias fantasma no terminal podem enganar agentes que modificam o ambiente. Agentes confiam muitas vezes no feedback visual. Se um servidor em background não atualizar, o agente pode assumir incorretamente que o código falhou. Regra: Se o agente modificar bibliotecas fundamentais (como no package.json), ele deve explicitamente reiniciar processos ou pedir para o usuário fazer isso.

Ferramentas de Linha de Comando (CLI)

Agentes dependem de ferramentas CLI que geram saídas parseáveis.

Ferramentas interativas (nano, vim, ou prompts que pedem yes/no) devem ser evitadas ou alimentadas via pipes (yes | command).
Use comandos específicos para lint e grep com saída crua, evitando truncamentos em outputs longos.

Relacionadas: harness-llm · skill-ui-validation