Manual de voo
O agente entende o projeto antes de tocar no código.
AGENTS.md
Harness engineering, sem mistério
Uma conversa visual sobre como transformar um agente de IA talentoso em um colaborador previsível.
A pergunta de abertura: você confiaria num ótimo piloto sem instrumentos?
A ideia em 30 segundos
O agente entende o projeto antes de tocar no código.
AGENTS.md
Ele enxerga rápido quando algo saiu do esperado.
testes · lint · types
Cada mudança é verificada de novo, fora da conversa.
CI
Ações perigosas podem ser bloqueadas de verdade.
hooks
O mecanismo
Regras, contexto e exemplos reduzem tentativas no escuro.
O agente planeja, edita e executa dentro do projeto.
Testes, lint, tipos e CI devolvem fatos, não opiniões.
O limite que continua valendo mesmo quando o modelo erra.
O objetivo não é eliminar erros. É encurtar a distância entre errar, perceber e corrigir.
A escala de maturidade
Testes, linter, checagem de tipos e CI permitem que o agente comprove a própria mudança com ferramentas determinísticas.
O que entra na conta
A peça de maior retorno
Propósito e fronteiras do projeto.
Build, teste, lint e desenvolvimento.
Arquitetura e caminhos importantes.
Restrições e decisões irreversíveis.
# Projeto
Site estático da palestra.
# Verificação
npm run check
npm run scan:gate
# Regras
- Preserve a ordem dos slides.
- Não adicione dependência de runtime.
- Explique termos antes de usá-los.
Escreva para reduzir descoberta, não para documentar o óbvio.
Progressive disclosure
Carregam instruções apenas quando o agente toca em arquivos relacionados.
Quando: ao editar HTML, CSS ou JS
Empacota uma sequência reutilizável ou delega uma revisão com foco específico.
Exemplo: talk-reviewer revisa clareza e fatos
Expõe um workflow que a pessoa decide iniciar explicitamente.
Quando: sob demanda
O restante entra por escopo ou por demanda.
Feedback determinístico
A fronteira L3 → L4
“Nunca execute um comando destrutivo.”
O modelo precisa lembrar, interpretar e obedecer.
provavelmentegit push --force
BLOCKED
A máquina intercepta a ação antes da execução.
sempreAgora, no terminal
$ npm run scan
Mostre as seis dimensões e as evidências por arquivo.
Conecte a pontuação a um artefato legível.
Explique por que o resultado é L3, não L4.
npm run scan:gate protege o nível mínimo no CI.
Três ideias para levar
O modelo é só uma parte do desempenho.
Contexto orienta; sensores ensinam; guardrails protegem.
Maturidade é o que o repositório consegue provar.