Como dar a um agente de coding com IA conhecimento confiável do domínio

Um agente de coding genérico pode escrever uma resposta plausível e ainda perder o detalhe importante do seu stack: uma API que mudou recentemente, um limite do repositório que não deve ser cruzado ou uma convenção que mantém a produção estável. A solução nem sempre é um prompt maior. Um padrão melhor é oferecer orientação de domínio pequena e reutilizável, com uma definição de pronto verificável.

1. Separe regras do projeto de procedimentos do domínio

Comece com duas camadas. A primeira é um contrato curto do repositório: o que é o projeto, como está organizado, quais comandos fazem build e testam, quais arquivos estão proibidos e o que significa “pronto”. A documentação da JetBrains sobre comportamento de agentes descreve arquivos como AGENTS.md e CLAUDE.md como instruções que viajam com o repositório e podem ser compartilhadas entre ferramentas.

Mantenha essa camada estável e operacional. Ela deve responder onde está a lógica de domínio, como executar as verificações e o que não editar. Uma regra específica de um único fluxo deve ficar em uma skill separada.

A segunda camada é conhecimento de domínio: uma receita focada para uma tarefa recorrente, como migrar a navegação Android, mudar um schema ou preparar um release. Uma skill precisa de um gatilho claro, uma sequência curta e validação explícita, mantendo pequeno o contexto padrão.

2. Escreva uma skill para uma lacuna de conhecimento

Uma boa skill existe porque o modelo erra repetidamente ou redescobre a mesma coisa. A filosofia das Android Skills sugere procurar lacunas verificáveis, principalmente quando APIs mudam ou a arquitetura é personalizada. Ela também recomenda fontes confiáveis, em vez de coleções grandes e não testadas que podem conter instruções maliciosas.

Um exemplo pequeno:

---
name: navigation-upgrade
description: Use when changing the app's Navigation 3 setup or upgrading its related APIs.
---

Before editing:
1. Inspect the current dependency versions and existing navigation tests.
2. Read the project's navigation conventions.
3. Confirm the target API in the approved platform documentation.

While editing:
- Make the smallest vertical change that satisfies the requested behavior.
- Do not replace the navigation architecture without approval.
- Preserve existing deep-link and back-stack behavior unless the task says otherwise.

Done means:
- The focused tests pass.
- The relevant build or lint command passes.
- The response names changed files, checks run, and unresolved risks.

O exemplo é estreito de propósito. Ele não cola um manual inteiro em cada prompt; define quando o procedimento se aplica, o que inspecionar, quais limites importam e como comprovar a conclusão. Troque os checks pelos comandos e convenções reais do seu repositório.

3. Faça o agente inspecionar antes de agir

Agentes de coding combinam um pedido com o contexto do ambiente, raciocinam sobre ele e executam alterações, testes e builds. Esse é o fluxo descrito em AWS Prescriptive Guidance. Suas instruções devem mostrar essas fases.

Um pedido prático tem quatro partes:

1. Contexto: recurso, diretórios relevantes e restrições.
2. Plano: arquivos e checks previstos antes de editar.
3. Mudança: a implementação mínima para os critérios de aceitação.
4. Evidência: testes, lint, build ou verificações manuais exatas.

Isso evita começar pela frase do usuário, descobrir tarde a arquitetura e compensar com uma reescrita ampla. Inspecionar é como o agente obtém o contexto de que suas decisões dependem.

4. Dê um ciclo de feedback curto

A orientação de domínio explica o projeto, mas os checks executáveis dizem se a mudança funciona. O guia atual de TDD do VS Code separa red, com teste falhando, green, com implementação mínima, e refactor, melhorando a estrutura sem quebrar os testes.

Você não precisa de três agentes elaborados. Para uma tarefa pequena, peça primeiro um teste falho ou de caracterização; depois implemente. Termine com um teste focado e os quality gates normais. Se o check falhar, isso informa algo sobre o requisito ou o ambiente; não é motivo para esconder a falha em um resumo confiante.

5. Revise e aposente a orientação

Trate uma skill como infraestrutura de engenharia versionada. Revise quando o framework mudar, quando o agente repetir um erro ou quando um check ficar ruidoso. A orientação sobre Android Skills apresenta skills como candidatas à depreciação: modelos melhoram e novas APIs criam novas lacunas.

Um ciclo simples:

• Mantenha uma tarefa de exemplo que exercite a skill.
• Registre arquivos esperados e comandos de validação.
• Execute após mudanças na skill ou no modelo.
• Remova instruções que já não são necessárias.
• Deixe ações sensíveis à segurança opcionais e revisáveis.

O objetivo não é fazer o agente parecer mais especialista, mas tornar o comportamento correto reproduzível: um contrato curto do repositório, um procedimento de domínio específico e uma definição de pronto executável.