ARTIGO
Só prompts não bastam: como estruturo o desenvolvimento com agentes de IA
Como organizo agentes, instruções e documentos para planejar, implementar, revisar e validar software com IA.
- IA
- Agentes
- Harness
- Spec-Driven Development
O problema que encontrei
Conforme comecei a usar IA em projetos com fluxos mais complexos, um problema ficou recorrente: o código gerado nem sempre seguia os padrões que já existiam no software.
Eu precisava explicar novamente como organizar os componentes, quais decisões de arquitetura deveriam ser respeitadas e até qual era o objetivo do produto e quem iria utilizá-lo.
Essas explicações se repetiam entre tarefas e sessões, gerando retrabalho.
Em tarefas maiores, havia outra dificuldade: verificar se a implementação realmente seguia o que tinha sido definido.
O que é um harness de desenvolvimento?
Foi para lidar com esses problemas que comecei a estruturar meu harness de desenvolvimento: um conjunto de instruções, agentes, skills e documentos que organiza como a IA trabalha no projeto.
Essa estrutura mantém referências sobre o produto, as decisões de arquitetura e os padrões de desenvolvimento. Também define as responsabilidades de quem planeja, implementa, revisa e valida cada entrega.
Componentes do Harness de desenvolvimento
AGENTS.md: as regras do projeto
O AGENTS.md é o ponto de entrada das instruções do projeto: reúne orientações para o agente e indica quais regras e documentos consultar durante o trabalho.
No meu harness, além das regras gerais, o AGENTS.md estabelece os princípios de coordenação e as responsabilidades dos agentes especializados, já que o agente raiz também atua como orquestrador.
Por exemplo: uma funcionalidade precisa de um PRD executável ou uma spec aprovada antes de ser implementada; quem implementa não aprova sozinho o próprio trabalho; e testes ou verificações informados como concluídos precisam ter evidência real.
O arquivo estabelece essas exigências, enquanto as definições dos agentes e as skills detalham responsabilidades e procedimentos. O orquestrador aplica as regras durante a execução, evitando que precisem ser repetidas a cada conversa.
O orquestrador: quem coordena o trabalho
No meu harness, o orquestrador é o próprio agente principal com quem converso, também chamado de agente raiz. Ele assume essa função diretamente, sem um subagente separado para coordenar os demais.
Antes de avançar, consulta as regras e os documentos do projeto e verifica se as condições da próxima etapa foram atendidas. Por exemplo, a definição do produto precisa estar com status ready antes da definição da base técnica ou do planejamento de funcionalidades. A base técnica, por sua vez, precisa estar ready antes da implementação. Esses critérios para avançar ou concluir uma etapa são os chamados quality gates.
Com as condições atendidas, ele seleciona os especialistas necessários, encaminha o trabalho e acompanha suas entregas. Se houver uma pendência ou a revisão apontar uma falha, direciona a questão ao responsável e verifica o retorno antes de liberar a etapa dependente. Ao final, reúne o resultado, as verificações realizadas e o que ainda ficou em aberto. A skill Primary Agent Coordination detalha como o agente raiz coordena esse fluxo.
A base do projeto: produto e arquitetura
Product Definition: o que estamos construindo e por quê?
O product-definition.md registra o problema que o produto resolve, quem são seus usuários, os objetivos e as principais regras de negócio.
Com essa referência, os agentes conseguem avaliar se uma funcionalidade faz sentido para o produto, evitando implementações tecnicamente corretas que não atendem às necessidades do negócio.
Technical Foundation: como o sistema deve ser construído?
O technical-foundation.md registra os acordos técnicos do projeto: arquitetura, responsabilidades dos módulos, dependências permitidas, contratos de integração e estratégias de teste.
Isso permite que os agentes desenvolvam novas funcionalidades respeitando a estrutura existente, sem precisar analisar todo o código para redescobrir padrões ou tomar decisões arquiteturais já estabelecidas.
Esses documentos evoluem conforme o projeto, preservando uma referência compartilhada para o planejamento, a implementação e a revisão.
Planejamento: Spec-Driven Development
Planejar antes de escrever código permite identificar ambiguidades, dependências e decisões pendentes antes de investir na implementação. No meu harness, isso segue a abordagem Spec-Driven Development (SDD): definimos o comportamento esperado, o escopo e os critérios que serão usados para verificar a entrega. Esse planejamento orienta tanto a implementação quanto a revisão, reduzindo a necessidade de interpretar novamente o pedido em cada etapa.
Uma referência externa é o GitHub Spec Kit, que organiza o trabalho em especificação, esclarecimento, planejamento, tarefas, implementação e verificação. O meu harness usa sua própria organização de PRDs, specs e agentes; os formatos não precisam ser iguais para aplicar a ideia de desenvolver a partir de expectativas explícitas.
PRD e specs
Toda iniciativa ou funcionalidade recebe um PRD (Product Requirements Document), que registra o problema, o objetivo, o escopo e os resultados esperados. Quando representa uma entrega suficientemente clara e verificável, o próprio PRD pode ser executável. Quando há múltiplas entregas, ele é dividido em specs, cada uma cobrindo um fluxo completo que possa ser implementado e verificado.
As specs descrevem comportamento, contratos, estados, erros e critérios de aceite, sem antecipar o código de produção. Cenários Given/When/Then — dado um contexto, quando uma ação ocorre, então um resultado é esperado — tornam essas expectativas verificáveis. O planejamento define o que precisa ser provado; os implementadores escrevem os testes e o agente de qualidade avalia a aderência da entrega.
Tarefas simples de manutenção podem seguir um fluxo curto, com escopo e verificações proporcionais, sem exigir um novo PRD ou uma spec.
Agentes e skills: quem faz e como faz
Um agente assume uma responsabilidade; uma skill descreve como executar um procedimento. A mesma skill pode orientar agentes diferentes, mantendo critérios comuns entre planejamento, implementação e revisão.
Por exemplo, uma skill de padrão técnico pode orientar a separação entre regras de negócio e acesso a dados. O diagrama abaixo é ilustrativo: mostra como essa referência pode ser compartilhada, não uma execução realizada.
No Harness, os especialistas participam conforme a tarefa — não é necessário chamar todos a cada entrega.
| Agente | Responsabilidade |
|---|---|
| Root (Orquestrador) | Coordena os agentes, aplica os critérios de avanço e governa as decisões de produto. |
| Planner | Transforma demandas em PRDs e especificações verificáveis. |
| Architect | Define e preserva a arquitetura, os limites técnicos e as decisões estruturais. |
| Backend | Implementa serviços, integrações e testes de backend. |
| Frontend | Implementa interfaces, componentes e testes de frontend. |
| Quality | Revisa planejamento e entregas, riscos, regressões e cobertura; realiza verificações técnicas de backend quando aplicável. |
| Frontend Verifier | Executa fluxos reais no navegador, verifica comportamento e registra evidências. |
| Skill Guard | Analisa impactos nas skills e audita a consistência entre regras, agentes e instruções. |
Adaptando os agentes ao projeto
Essa composição é um ponto de partida, não uma lista obrigatória. Em projetos com necessidades específicas, já utilizei outros especialistas:
| Agente adicional | Quando utilizo |
|---|---|
| Orchestrator | Em projetos com muitos agentes e fluxos complexos, quando a coordenação, distribuição de tarefas e controle das etapas começam a sobrecarregar o Root. Separo a orquestração para que o Root se concentre na interação comigo e nas decisões gerais. |
| Product | Quando o domínio possui muitas regras de negócio e exige acompanhamento especializado. |
| Backend Verifier | Executa testes e verifica contratos, integrações e o comportamento real do backend independentemente da implementação. |
| Database | Apoia modelagem, consultas, performance e migrações de banco de dados. |
| Security Reviewer | Analisa autenticação, permissões, vulnerabilidades e riscos de segurança. |
Quando separo a verificação do backend em um agente próprio, redistribuo as responsabilidades sem abrir mão de avaliações independentes.
A composição dos agentes evolui conforme os resultados do fluxo. Observo principalmente o retrabalho — inclusive aquele que os agentes corrigem internamente antes da entrega — e problemas recorrentes de qualidade que ainda exigem minha intervenção. Quando esses sinais aparecem, avalio primeiro as especificações, skills e responsabilidades existentes; se necessário, especializo ou redistribuo agentes. O objetivo é reduzir retrabalho e consumo de recursos, mantendo entregas consistentes.
As definições ficam em .codex/agents/ e os procedimentos em .codex/skills/. Elas precisam ser disponibilizadas em um ambiente com suporte a agentes; copiar os arquivos, por si só, não registra os especialistas em qualquer ferramenta.
Um Harness que evolui com o projeto
Meu Harness não é uma estrutura estática, e acredito nenhum deveria ser. Conforme o software evolui, suas instruções, regras de negócio e padrões técnicos precisam acompanhar essas mudanças.
Para isso, o agente principal acompanha as decisões tomadas durante o desenvolvimento, verifica sua consistência com a documentação existente e atualiza as referências do projeto quando necessário, mesmo que a mudança tenha sido comunicada apenas pelo chat.
Já o Skill Guard analisa o impacto dessas alterações, identifica skills que precisam ser criadas, atualizadas ou removidas e verifica se as correções foram aplicadas. Caso encontre pendências, informa o agente raiz para que os responsáveis realizem os ajustes necessários.
Assim, o Harness evolui junto com o software, preservando conhecimento e reduzindo a necessidade de repetir instruções ou atualizar manualmente cada documento.
E o modelo nessa equação?
No início do desenvolvimento assistido por IA, a escolha do modelo fazia bastante diferença na minha experiência. Mas, trabalhando em uma startup, comecei a questionar essa dependência por uma necessidade prática: mesmo com um plano de aproximadamente US$ 200 mensais, a demanda já ultrapassava os limites disponíveis.
Passei então a experimentar formas de aproveitar melhor os recursos. Conforme evoluí o Harness, com planejamento, especificações, skills e validações, percebi ganhos que iam além da padronização: menos intervenções manuais, menos necessidade de reanalisar grandes partes do código e maior autonomia dos agentes. Com isso, consegui avançar em mais tarefas dentro do mesmo limite mensal, embora não tenha medido se o consumo total de tokens por tarefa diminuiu.
Mas será que precisamos sempre do melhor modelo para desenvolver software? Minha hipótese é que um Harness bem estruturado pode reduzir essa dependência, embora modelos avançados continuem importantes para decisões complexas. Pretendo investigar isso em um artigo próprio, comparando modelos com e sem Harness, suas taxas de sucesso, qualidade e custo de implementação.
Como isso funciona na prática
Imagine o pedido: adicionar recuperação de senha a um produto. Este exemplo é ilustrativo, inspirado nos fluxos do README do harness.
Com produto e base técnica prontos, o planejamento define o comportamento esperado: solicitar a recuperação, cadastrar uma nova senha com um link válido e recusar um link inválido ou expirado. A implementação e os testes seguem esses critérios.
- Pedido
Adicionar recuperação de senha.
- Planejamento
Definir comportamento e critérios.
- Implementação
Criar o fluxo e os testes.
Conferir os critérios, incluindo recusar um link expirado.
Reunir a entrega e as evidências.
Encaminhar a falha ao responsável.
Correção → nova revisão e verificação
Se um teste mostrar que um link expirado ainda permite trocar a senha, a entrega volta para correção. Depois do ajuste, a revisão e as verificações são repetidas conforme o impacto da mudança; corrigir o código, por si só, não encerra o trabalho.
Assim, o pedido ganha um critério observável de conclusão. O diagrama representa esse caminho possível, não uma execução comprovada do exemplo.
Resultados na prática
Em uma execução de cerca de três horas, minha participação se concentrou no planejamento: conversei bastante para esclarecer a necessidade, li o plano e revisei o que seria feito. Depois que autorizei a implementação, não precisei intervir durante aquela execução.
O trabalho seguiu o fluxo de agentes, incluiu testes no navegador e me entregou capturas de tela das verificações. Depois, testei por conta própria e tudo funcionou como eu esperava. Esse resultado descreve aquela experiência, não uma garantia de que toda implementação seguirá sem intervenção ou erros.
Em outro cenário, criei um harness específico para backfill, com agentes responsáveis por coordenar a execução, corrigir erros e validar os dados processados. A estrutura mudou para atender às necessidades daquele fluxo: agentes, skills e verificações precisam acompanhar o objetivo e os riscos de cada trabalho.