5 dicas e truques de codificação Agentic
Imagem por Editor
Introdução
A codificação Agentic só parece “inteligente” quando envia diferenças corretas, passa nos testes e deixa um rastro de papel em que você pode confiar. A maneira mais rápida de chegar lá é parar de pedir a um agente para “criar um recurso” e começar a fornecer a ele um fluxo de trabalho do qual ele não possa escapar.
Esse fluxo de trabalho deve forçar clareza (o que muda), evidências (o que foi aprovado) e contenção (o que pode afetar). As dicas abaixo são padrões concretos que você pode implementar no trabalho diário com agentes de código, esteja você usando um agente CLI, um assistente IDE ou um modelo personalizado de uso de ferramentas.
1. Use um mapa de repositório para evitar refatorações cegas
Agentes tornam-se genéricos quando não entendem a topologia da sua base de código. Eles adotam refatoradores amplos como padrão porque não conseguem localizar com segurança as costuras corretas. Dê ao agente um mapa de repositório que seja curto, opinativo e ancorado nas partes que importam.
Crie um instantâneo legível por máquina da estrutura do seu projeto e dos principais pontos de entrada. Mantenha-o abaixo de algumas centenas de linhas. Atualize-o quando as pastas principais forem alteradas. Em seguida, alimente o mapa ao agente antes de qualquer codificação.
Aqui está um gerador simples que você pode manter instruments/repo_map.py:
de pathlib importar Caminho INCLUDE_EXT = {“.py”, “.ts”, “.tsx”, “.ir”, “.Java”, “.rs”} SKIP_DIRS = {“node_modules”, “.git”, “dist”, “construir”, “__pycache__”} raiz = Caminho(__arquivo__).resolver().pais(1) linhas = () para p em classificado(raiz.rglob(“*”)): se qualquer(papel em SKIP_DIRS para papel em p.peças): continuar se p.é_arquivo() e p.sufixo em INCLUDE_EXT: rel = p.relativo_para(raiz) linhas.acrescentar(str(rel)) imprimir(“n”.juntar(linhas(:600))) |
Adicione uma segunda seção que nomeie os arquivos “quentes” reais, não todos. Exemplo:
Pontos de entrada:
api/server.ts(Roteamento HTTP)core/agent.ts(planejamento + chamadas de ferramentas)core/executor.ts(executor de comando)packages/ui/App.tsx(shell de front-end)
Principais Convenções:
- Nunca edite arquivos gerados em
dist/ - Todas as gravações do banco de dados passam
db/index.ts - Sinalizadores de recursos residem em
config/flags.ts
Isso reduz o espaço de pesquisa do agente e impede que ele reescreva “de forma útil” metade do repositório porque ele se perdeu.
2. Forçar as primeiras edições do patch com um orçamento diferente
Agentes descarrilam quando eles editam como um humano com tempo ilimitado. Power-os a se comportarem como colaboradores disciplinados: proponha um patch, mantenha-o pequeno e explique a intenção. Um truque prático é um orçamento diff, um limite explícito de linhas alteradas por iteração.
Use um fluxo de trabalho como este:
- O agente produz um plano e uma lista de arquivos
- O agente produz apenas uma diferença unificada
- Você aplica o patch
- Testes executados
- Próximo patch somente se necessário
Se você estiver construindo seu próprio loop de agentes, certifique-se de aplicá-lo mecanicamente. Exemplo de pseudo-lógica:
MAX_CHANGED_LINES = 120 definitivamente contagem_linhas_alteradas(diferença_unificada: str) -> interno: retornar soma(1 para linha em diferença_unificada.linhas divididas() se linha.começa com((“+”, “-“)) e não linha.começa com((“+++”, “—“))) mudado = contagem_linhas_alteradas(diferença) se mudado > MAX_CHANGED_LINES: elevação Erro de valor(f“Diferença muito grande: {modified} alterou linhas”) |
Para fluxos de trabalho manuais, inclua a restrição em seu immediate:
- Produza apenas uma diferença unificada
- Limite rígido: complete de 120 linhas alteradas
- Nenhuma formatação ou refatorações não relacionadas
- Se precisar de mais, pare e peça um segundo patch
Os agentes respondem bem a restrições mensuráveis. “Mantenha o mínimo” é vago. “120 linhas alteradas” é aplicável.
3. Converta requisitos em testes de aceitação executáveis
Solicitações vagas podem impedir que um agente edite adequadamente sua planilha e muito menos crie o código adequado. A maneira mais rápida de tornar um agente concreto, independentemente do seu padrão de designé traduzir os requisitos em testes antes da implementação. Trate os testes como um contrato que o agente deve satisfazer, e não como um complemento de melhor esforço.
Um padrão leve:
- Escreva um teste com falha que seize o comportamento do recurso
- Execute o teste para confirmar se ele falhou pelo motivo certo
- Deixe o agente implementar até que o teste passe
Exemplo em Python (pytest) para um limitador de taxa:
importar tempo de meu aplicativo.limite de taxa importar Limitador de janela deslizante definitivamente test_allows_n_requests_per_window(): limão = Limitador de janela deslizante(limite=3, janela_segundos=1) afirmar limão.permitir(“u1”) afirmar limão.permitir(“u1”) afirmar limão.permitir(“u1”) afirmar não limão.permitir(“u1”) tempo.dormir(1.05) afirmar limão.permitir(“u1”) |
Agora o agente tem um alvo que é objetivo. Se “pensar” que está feito, o teste resolve.
Mix isso com o suggestions da ferramenta: o agente deve executar o conjunto de testes e colar a saída do comando. Esse único requisito mata uma classe inteira de conclusões confiantes, mas erradas.
Snippet de immediate que funciona bem:
- Passo 1: Escreva ou refine testes
- Etapa 2: Execute testes
- Etapa 3: Implemente até que os testes sejam aprovados
Sempre inclua os comandos exatos que você executou e o resumo remaining do teste.
Se os testes falharem, explique a falha em um parágrafo e depois corrija.
4. Adicione uma etapa de “pato de borracha” para capturar suposições ocultas
Os agentes fazem suposições silenciosas sobre formatos de dados, fusos horários, tratamento de erros e simultaneidade. Você pode trazer à tona essas suposições com um momento forçado de “pato de borracha”, brand antes da codificação.
Peça três coisas, em ordem:
- Suposições que o agente está fazendo
- O que poderia quebrar essas suposições?
- Como iremos validá-los?
Seja curto e obrigatório. Exemplo:
- Antes de codificar: liste 5 suposições
- Para cada: uma etapa de validação usando código ou logs existentes
- Se alguma suposição não puder ser validada, faça uma pergunta de esclarecimento e pare
Isso cria uma pausa que geralmente evita confirmações arquiteturais incorretas. Também oferece um ponto de verificação de revisão fácil. Se você discordar de uma suposição, poderá corrigi-la antes que o agente escreva o código que a incorpora.
Uma vantagem comum é detectar antecipadamente incompatibilidades de contratos de dados. Exemplo: o agente assume que um carimbo de information/hora é ISO-8601mas a API retorna milissegundos de época. Que uma incompatibilidade pode se transformar em rotatividade de “correção de bugs”. O passo do pato de borracha libera tudo.
5. Torne a saída do agente reproduzível com receitas de execução
A codificação agente falha nas equipes quando ninguém consegue reproduzir o que o agente fez. Corrija isso exigindo uma receita de execução: os comandos exatos e as notas de ambiente necessárias para repetir o resultado.
Adote uma convenção simples: toda operação de agente termina com um RUN.md snippet que você pode colar em uma descrição de PR. Deve incluir configuração, comandos e resultados esperados.
Modelo:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | ## Executar receita Ambiente: – SO: – Tempo de execução: (nó/píton/ir versão) Comandos: 1) <comando> 2) <comando> Esperado: – Testes: <resumo> – Fiapos: <resumo> – Guide verificar: <o que para clique ou enrolar> Exemplo para um Nó API mudar: ## Executar receita Ambiente: – Nó 20 Comandos: 1) npm ci 2) npm teste 3) npm correr fiapos 4) nó roteiros/fumaça.js Esperado: – Testes: 142 passou – Fiapos: 0 erros – Fumaça: “OK” impresso |
Isso torna o trabalho do agente portátil. Também mantém a autonomia honesta. Se o agente não conseguir produzir uma receita de execução limpa, provavelmente não validou a alteração.
Concluindo
A codificação Agentic melhora rapidamente quando você a trata como engenharia, não como vibração. Os mapas repo impedem a perambulação cega. As diferenças do primeiro patch mantêm as alterações revisáveis. Testes executáveis transformam requisitos indefinidos em metas objetivas. Um ponto de verificação de pato de borracha expõe suposições ocultas antes que elas se transformem em bugs. As receitas de execução tornam todo o processo reproduzível para os colegas de equipe.
Esses truques não reduzem a capacidade do agente. Eles afiam isso. A autonomia torna-se útil quando é limitada, mensurável e vinculada ao suggestions actual da ferramenta. É quando um agente para de parecer impressionante e começa a enviar um trabalho que você pode mesclar.