Construir um SaaS com um agente de código: um fluxo prático

Começa por um resultado observável

Um agente de código pode produzir uma interface de aspeto convincente antes de teres decidido o que ela deve fazer. Começa por um pequeno resultado de utilizador: um utilizador ligado edita um perfil, guarda e vê o nome guardado após recarregar. Isso dá à implementação e à revisão um alvo concreto.

Inclui no brief o comportamento atual, o comportamento esperado e os casos de falha que importam. Nomeia o módulo existente que detém o trabalho. Um pedido para adicionar edição de perfil deve apontar para a camada de autenticação em vez de deixar o agente inventar um segundo armazenamento de utilizadores. Mantém credenciais fora de prompts e capturas de ecrã — um apps/web/.env.local colado ou um cookie de sessão passa a fazer parte do registo da conversa.

Um brief utilizável lê-se assim: «No ecrã de conta, permite que um utilizador com sessão iniciada edite o nome de apresentação e o veja após recarregar. O módulo de auth detém o registo de utilizador; não adiciones uma tabela. Um nome vazio, ou um pedido que nomeie o registo de outro utilizador, deve ser rejeitado. Prova-o com pnpm test e uma gravação manual num ecrã estreito.» Cinco frases, e a maior parte das suposições desaparece.

O resultado visível ao utilizador, formulado de forma a poderes verificá-lo na app em execução.
O ficheiro ou módulo que hoje detém o comportamento — e as áreas que devem ficar intocadas.
Pelo menos um caso de falha: uma tentativa não autenticada, entrada inválida ou um pedido repetido.
A verificação que o prova — um comando de teste, um fixture ou um percurso manual explícito.

Faz o repositório explicar-se a si próprio

Documenta como correr a aplicação, que verificações são deterministas e onde a propriedade é aplicada. No supastack, o AGENTS.md regista o limite do workspace e o .ai/ regista decisões ao nível do ficheiro. Estas notas são mais úteis quando dizem ao próximo contribuidor — humano ou agente — porque existe uma implementação, e não apenas que ficheiros mudaram. O guia de configuração de agentes mostra como o kit expõe esse material, e o guia de configuração local é o percurso que o agente vai realmente seguir.

Pede ao agente para ler o código relevante antes de modificar. Uma alteração estreita normalmente precisa da interface, da sua fronteira de servidor e dos testes em torno dessa fronteira. Carregar o repo inteiro é menos útil do que compreender os poucos lugares que decidem se o novo comportamento está correto: a verificação de propriedade, o schema, a permissão.

Quando uma funcionalidade toca em configuração, nomeia o ficheiro em vez de o transcrever — «adiciona a chave ao apps/web/.env.local» mantém os segredos no disco. A mesma disciplina aplica-se aos painéis dos fornecedores: descreve o destino, não coles a credencial.

Trabalha em alterações pequenas e fáceis de rever

Os agentes são mais fiáveis quando uma alteração tem um só dono e um só resultado verificável. «Adicionar edição de perfil» é fácil de rever; «melhorar a área de conta» convida a refatorações que ninguém pediu. Se uma funcionalidade se decompõe numa mudança de schema, uma fronteira de servidor e um ecrã, executa-as como briefs separados que deixam cada um o build verde.

Faz commit ou checkpoint antes de cada execução do agente. Uma base limpa transforma um mau resultado num diff apagado em vez de um exercício de arqueologia, e dá à tua revisão um antes-e-depois estável para comparar.

Revê uma alteração completa de cada vez

Escreve uma verificação de aceitação antes de mudar o comportamento. Para edição de perfil, cobre uma atualização válida e uma tentativa não autorizada. Constrói a implementação mínima que satisfaça esses casos, depois inspeciona a interação real com texto realista e um viewport estreito.

Revê o diff tal como o resultado. Procura lógica de negócio duplicada, tratamento de exceções demasiado amplo e novas dependências que resolvem um problema que o stack existente já trata. Executa as verificações do projeto e regista o que estabelecem. Um fixture de browser pode verificar uma interação de formulário; não pode estabelecer que a base de produção ou um fornecedor externo está corretamente configurado.

Cada comando responde a uma pergunta diferente. O pnpm test exercita o comportamento contra adaptadores fake e locais deterministas, o pnpm check cobre lint, typechecking e formatação, e o pnpm build expõe os erros de integração que só aparecem em tempo de bundle. Juntos são um piso para a revisão — a checklist de lançamento cobre o que ainda tem de ser provado no ambiente real.

pnpm test
pnpm check
pnpm build

Quando o agente se engana

Quando um resultado está errado, resiste a empilhar prompts de seguimento sobre um diff mau. Reverte para o checkpoint, aperta o brief em torno do que foi mal compreendido — normalmente um requisito não dito ou um dono em falta — e executa de novo. Cada nova tentativa deve trazer informação nova, não apenas nova urgência.

Uma falha persistente normalmente significa que o brief pressupõe contexto que o repositório não contém. Se o agente continua a inventar um segundo lugar para guardar utilizadores, a correção é uma frase no AGENTS.md sobre onde vive a identidade, não um tom mais firme. Atualiza o documento e tenta a tarefa de novo — o guia de agentes é onde o kit guarda este fluxo.

Perguntas frequentes sobre fluxos com agentes

Algumas perguntas surgem sempre que um fundador começa a confiar trabalho real de produto a um agente de código.

Um agente de código consegue construir um SaaS inteiro sozinho? — Consegue montar as partes visíveis depressa, mas as partes duradouras — autorização, ciclo de vida de faturação, isolamento de dados — continuam a precisar de um brief, uma verificação e uma revisão. Velocidade sem esse ciclo transforma-se em retrabalho.
Qual deve ser o tamanho de uma tarefa para um agente de código? — Pequena o suficiente para verificares o resultado na app em execução em poucos minutos: um resultado visível ao utilizador, um módulo dono, uma verificação de aceitação.
O que nunca deve entrar num prompt? — Segredos de fornecedor, cookies de sessão, o conteúdo do .env.local e dados de clientes. Nomeia os ficheiros e deixa a ferramenta lê-los localmente em vez de copiar valores para um registo de chat.
O código escrito por agente muda a forma de rever? — A revisão passa de escrever para ler: inspeciona o diff à procura de lógica duplicada, tratamento de exceções demasiado amplo e dependências que voltam a resolver um problema que o stack já trata.
Que testes importam mais no resultado de um agente? — Os que fixam propriedade e comportamento de falha: pedidos não autorizados, entrada inválida e submissões repetidas, não apenas o caminho feliz que a demo mostra.