Todo projeto que conduzi com um agente de IA ao teclado começou do mesmo jeito, e durante muito tempo eu não percebi que começava. Antes da primeira linha de código havia uma conversa sobre como o trabalho iria acontecer: quem decide o que um pedido realmente pede, quem escreve a mudança, quem olha para ela com olho desconfiado, quando o agente deve parar e perguntar em vez de adivinhar, e o que “pronto” significa para quem está pagando. Eu tinha essa conversa comigo mesmo, depois com o agente, depois de novo no projeto seguinte, e a cada vez ela saía um pouco diferente, porque morava em quem tinha feito o projeto anterior, e essa pessoa estava cansada, ou com pressa, ou simplesmente tinha esquecido metade.
O agente, enquanto isso, fazia o que agentes fazem quando as regras chegam tarde ou incompletas: preenchia as lacunas com o seu melhor palpite. Às vezes o palpite era bom. Às vezes ele revisava o próprio trabalho e aprovava, o que não é uma revisão, mas o mesmo raciocínio concordando consigo mesmo; às vezes rodava um teste à mão de um jeito que ninguém conseguiria repetir; às vezes me fazia uma pergunta que eu já tinha respondido em outro projeto, e às vezes não fazia a única pergunta que importava. Nada disso era culpa do agente. O jeito de trabalhar nunca tinha sido escrito, então não havia nada para ele seguir.
Esta é a história de como aquela conversa virou um documento, de como o documento virou algo que se instala em dois passos, e do que sai do outro lado: um jeito de construir e entregar software que corre AI-first do pedido ao código em funcionamento, com o humano decidindo nos portões e em nenhum outro lugar.
Escrever uma vez
Numa plataforma de um cliente, depois de meses disso, a conversa finalmente virou um documento, e o documento se revelou feito de três camadas que eu vinha misturando desde sempre.
A primeira camada são as regras, escritas para qualquer agente, num arquivo que não nomeia fornecedor nem modelo. Ele diz, em frases simples, que quem decide não executa, que quem executa só toca no que a tarefa nomeia, que o plano passa por alguém cujo trabalho é objetar antes que qualquer pessoa comece a construir, que o resultado é atacado depois por um time que não o escreveu, e que existe exatamente um portão humano, que fica depois de o trabalho estar no ar e não antes. Diz também a coisa que fez toda a diferença numa tarde ruim: não pergunte nada que você mesmo possa decidir. Uma pergunta ao humano é uma interrupção, para ser gasta só quando as regras realmente não cobrem o caso.
A segunda camada são os papéis, quatro, escritos como contratos e não como programas. Um arquiteto, que lê o pedido, duvida dele, o confronta com o código, escreve o que vai mudar e por quê, e divide o trabalho. Um revisor, que trabalha no mesmo nível do arquiteto, porque um revisor um degrau abaixo só consegue revisar ortografia, e cujo sucesso se mede em objeções que mudaram o plano, nunca em planos aprovados depressa. Executores, que recebem uma fronteira e devolvem o que encontraram, incluindo a linha que diz que esbarraram em algo que não lhes pediram para tocar. E um time de qualidade com um líder próprio, que decide o que os testes precisam cobrir e qual pode ser o tamanho do ataque, e que reporta uma fraqueza mesmo quando ela não é defeito deste trabalho em particular. Os papéis puxam uns contra os outros de propósito, e quando discordam o arquiteto decide e escreve o porquê, para que a mesma objeção não volte um mês depois sem que ninguém saiba dizer o que foi feito dela.
A terceira camada é a que eu nunca tinha separado, e é onde a cultura encontra o projeto: cinco registros de fatos que uma cultura não tem como saber sozinha. Quais bases de código existem e como se relacionam. Como o trabalho viaja pelos ramos até um ambiente em funcionamento, e o que “entregue” significa ali. Como a aplicação sobe, desce e é testada. Onde um pedido mora enquanto está sendo trabalhado, e qual evento o move de um estado ao seguinte. E como a qualidade se sustenta, quais camadas de teste uma mudança deve, e com quais ferramentas. As regras diziam algo desconfortável sobre esses cinco: se qualquer um deles falta, você para. Não começa um pedido, não adivinha a convenção, não a infere do código. Diz qual registro está faltando, e espera.
Essa regra era o ponto. Era também o problema, para quem chegava.
Transformar em algo que se instala
Uma cultura que para quando falta um registro é uma cultura que, num projeto novo, para imediatamente. Escrever os cinco registros à mão me custou boa parte de uma semana na primeira plataforma, com a história do projeto diante dos olhos. Ninguém adotando o jeito de trabalhar pela primeira vez faria isso, e eu não queria explicar tudo de novo. Então o documento virou uma ferramenta, e a ferramenta se chama foreman, o nome em inglês do papel do arquiteto: aquele que decide e não executa. Ela é pública, e adotá-la são dois passos. O primeiro instala. O segundo, executado dentro de qualquer projeto, faz o resto.
O que “o resto” significa é a parte de que mais me orgulho, porque inverte a regra sem quebrá-la. O foreman primeiro lê o projeto, o que lhe é permitido desde que leia só o que o projeto versiona: encontra as peças e como estão costuradas, quais ramos existem e o que a história recente diz sobre como o time trabalha, os comandos que sobem as coisas e rodam os testes, se as mensagens de commit estão em inglês ou em português, se há um lugar onde as decisões já são registradas. Depois pergunta, e pergunta o mínimo que consegue. No máximo cinco perguntas, uma por registro, em linguagem simples, cada uma com a resposta que detectou já marcada como recomendada, e a primeira de todas oferece aceitar todos os padrões de uma vez. Então escreve os cinco registros, preenchidos, com cada valor detectado, respondido ou assumido por padrão, e cada registro diz na primeira página como foi preenchido, para que ninguém mais tarde confunda um padrão com uma decisão que alguém tomou sobre o seu projeto.
O agente que abre o projeto na manhã seguinte encontra os cinco registros no lugar, e a regra que diz “se algum falta, você para” está satisfeita sem que ninguém tenha sido parado. O projeto edita os registros sempre que discorda, porque são arquivos comuns dentro da sua própria base de código, e o foreman nunca mais pergunta. Mudar um registro é editar um arquivo.
Como o próprio foreman foi construído
Quero contar esta parte porque o foreman foi construído do jeito que a cultura diz que software deve ser construído, e a tarde que isso levou foi o melhor argumento que já vi a favor da cultura.
Começou com um documento de design, e antes que eu escrevesse uma linha da ferramenta, um leitor que nunca tinha visto a conversa recebeu esse documento com uma única pergunta: o que você ainda precisaria saber para construir isto? Vieram quatro perguntas de volta, e três eram reais. Uma delas, sobre o que acontece quando a ferramenta encontra um projeto feito de várias bases de código em vez de uma, mudou o design.
Depois veio um plano em que cada peça chegava com o seu teste primeiro. A detecção da forma do projeto, a entrevista, a escrita de arquivos dentro do projeto de outra pessoa sem jamais sobrescrever um byte que já estava lá: cada uma existiu como um teste falhando antes de existir como código, e o teste foi visto falhando, para que quando passasse houvesse um motivo para acreditar nele. No fim eram cento e noventa e cinco dessas verificações, e elas rodam contra quatro pequenos projetos de mentira, construídos do zero a cada vez: um vazio, um comum, um feito de várias peças com os detalhes incômodos que projetos reais têm, e um que já tinha passado pela ferramenta.
Então um revisor que não tinha visto nada daquilo leu o todo. Encontrou um jeito de a ferramenta quebrar no tipo mais comum de notebook, e mais dez defeitos que valiam a correção, e cada um deles foi corrigido na mesma tarde, cada um com o seu próprio teste escrito antes. Eu não reli o meu trabalho e chamei isso de revisão; a cultura não permite, e tinha razão.
E então o primeiro cliente encontrou mais três. Antes que um único arquivo fosse escrito nele, o foreman leu o DOP, a plataforma que estou construindo, que tem a forma oposta à do projeto em que a cultura nasceu: seis peças em vez de uma, três linguagens de programação, duas dúzias de decisões de arquitetura já registradas, e um modelo inteiramente diferente fazendo o papel de revisor. A leitura encontrou um projeto que mencionava os números das próprias decisões nas mensagens de commit e foi confundido com um que usava um sistema de chamados; um projeto com um lugar para ocorrências que nunca tinha guardado nenhuma; e uma base de código de topo que só movia ponteiros e documentação, e portanto não era o tipo de lugar onde código muda, o que a ferramenta se recusava a acreditar. Três correções, três testes, mais uma versão, e então a instalação, que me fez exatamente uma pergunta, porque aceitei os padrões, e deixou os registros que passei meia hora refinando à mão em seguida.
Um pedido, de ponta a ponta
Com a cultura instalada, é por isto que um pedido passa, e é aqui que o humano aparece.