Os contratos de degrau

Um arquivo por degrau. Todos têm o mesmo esqueleto, e o têm de propósito, para que você possa compará-los e para que, com o tempo, o reflexo de lê-los seja automático: o cabeçalho com a fase, o quando, a forma e o tamanho (obrigatório ou proporcional); para que serve; (1) o contexto necessário, nomeado de forma genérica; (2) os prompts, em inglês, cada um precedido por um bloco "Antes de enviar o prompt" (os arquivos e os insumos que você tem que ter prontos antes de colá-lo, com o seu conteúdo e o seu estado mínimo), seguido da sua tradução e, abaixo, da explicação do que estou pedindo ao modelo e por que cada cláusula está ali; (3) o resultado esperado, com suas características; (4) a verificação de completude, que você faz sem ler código; (5) os sinais de alerta, os sintomas de um degrau mal subido.

Os prompts em inglês são uma peça única, idêntica nas oito versões do documento; node build/build.mjs os extrai para prompts/ e verifica que nenhuma tradução os tenha alterado. A tradução que acompanha cada prompt é para que você o entenda; ao modelo se cola o inglês.

Eu os escrevi a partir do que fiz em três sistemas que hoje estão em produção, ainda não os executei tal como estão. O primeiro projeto que os usar de ponta a ponta vai corrigir vários; isso faz parte do degrau 23. Quando um contrato cita um caso real, faz isso com uma marca [Ref. N] que leva ao documento de referências; o procedimento fica limpo e o detalhe continua a um clique.

Fases: arranque se sobe uma vez por projeto; ciclo se repete a cada mudança; operação quando o sistema já está vivo. O 23 volta ao 0 para o projeto seguinte. A linha do tempo completa, com o que acontece entre degrau e degrau, está na Parte B do documento principal. Os nomes dos arquivos ficam em espanhol em todos os idiomas para que as ferramentas de build os reconheçam.

Passo 0 — Este projeto pode ser encarado assim? (contrato do degrau)

Fase: arranque. Quando: uma única vez, antes de abrir o repositório e antes de qualquer outra coisa. Forma: conversa: o agente avalia e pergunta; você decide. Tamanho: obrigatório em todo projeto, por menor que seja. Estado: os critérios excludentes X1 e X2 estão fechados; os critérios que ponderam (D1 a D10) ainda estou calibrando e os marco como hipótese.

Para que serve

Não entre num projeto onde o método não pode funcionar. Se o agente não vai poder se verificar sozinho de ponta a ponta, ou se não há um dono do domínio que decida, o método se degrada em "programar com IA" e você acaba lendo código. Este degrau é a porta de entrada: cruza-se uma vez, e se não se cruza, melhor saber antes do que depois.

E uma ideia de fundo que quero que você tenha clara: o método não serve para qualquer projeto, e isso não é um defeito. Um método que promete servir para tudo não está dizendo nada. O que este degrau faz é colocar a fronteira por escrito, para que a decisão de entrar ou não entrar seja uma decisão e não uma esperança. Os dois critérios excludentes saem de projetos que recusei, não dos que aceitei Ref. 46.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com seu conteúdo e seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

Nomeado de forma genérica; o agente avalia se basta e pede o que faltar.

• Levantamento do pedido: o que o cliente quer, para quem, e o que acontece hoje sem o sistema.
• Levantamento tecnológico: que tecnologia há ou se propõe, se existe um sistema anterior, se esse sistema tem repositório e como é manejado.
• Levantamento de testabilidade: se as telas podem ser executadas por programa e se cada elemento da interface é acessível com seus diferentes métodos (clique, digitação, leitura de estado), de modo que um teste percorra a tela e verifique o efeito no backend.
• Quem é o dono do domínio e quanto tempo tem para decidir.
• Que consequência tem um erro (dinheiro, saúde, operação, nada).
• Ambientes e acessos: se vai haver um ambiente de teste, se o agente pode acessá-lo, se há produção consultável em somente leitura.

2. Prompts

Os prompts vão em inglês, que é o idioma em que os modelos seguem instruções com mais precisão e menos tokens. Cada um traz sua tradução (no HTML, com um botão), e abaixo a explicação do que estou pedindo e por que cada cláusula está ali. Ao modelo se cola o inglês.

Inicial:

O que estou pedindo: que leia os dois insumos (o levantamento e a ficha de critérios); que antes de responder avalie se o levantamento basta e, se não bastar, pergunte em vez de supor (esta é a cláusula central de todos os prompts do método); que preencha a ficha com a fonte de cada resposta, para que depois se possa rastrear; que marque os excludentes em verde ou vermelho; e que não decida, porque a elegibilidade decido eu. A última linha pede que responda no meu idioma, porque o prompt está em inglês mas a conversa não precisa estar.

De fechamento:

O que estou pedindo: que deixe a decisão escrita com data e dono (degrau 6), com as condições se houver, e com o rastro de perguntas e respostas, que é a evidência de que não supôs nada.

3. Resultado esperado

Um arquivo docs/ELIGIBILITY.md (ou o nome que seu projeto usar), de uma página, com:

• Data e quem decidiu.
• Os dois critérios excludentes com sua resposta e sua fonte:
• X1: há repositório acessível e manejado de forma padrão (ou o projeto é novo).
• X2: a interface pode ser executada por programa e cada elemento é acessível com seus diferentes métodos, com verificação do efeito no backend.
• Os critérios que ponderam, cada um com resposta, fonte e peso (quando o peso estiver calibrado).
• A decisão: vai, não vai, ou vai com condições, e as condições escritas.
• As perguntas que o agente fez e as respostas, para que fique o rastro.

4. Verificação de completude (você faz, sem ler código)

• Os dois excludentes têm resposta explícita e fonte? Se algum está em vermelho, a decisão é "não vai" ou tem uma condição que o resolve?
• Há algum critério respondido com "suponho que sim" ou "provavelmente"? Se há, o degrau não foi subido: o agente tinha que perguntar.
• A decisão está escrita com data e com nome?
• As condições (se houver) são verificáveis? ("Ter acesso de leitura à produção antes do degrau 3" sim; "que o cliente colabore" não.)

5. Sinais de alerta

• O agente preencheu a ficha inteira sem fazer uma única pergunta. Ou o levantamento era perfeito (nunca é) ou ele supôs.
• A decisão é "vai com condições" e as condições são mais de três. Provavelmente é um "não vai" que ninguém quer dizer.
• O critério X2 foi respondido "sim, com um pouco de trabalho". Se as telas não podem ser operadas por programa hoje, esse "pouco de trabalho" é o projeto inteiro.

Passo 1 — O contrato de convivência (contrato do degrau)

Fase: arranque. Quando: uma única vez, imediatamente depois da elegibilidade; revisa-se quando um tropeço o exige. Forma: um disparo, com uma volta de ajuste sua. Tamanho: obrigatório em todo projeto. É o degrau mais barato de todos e o que mais frustração evita.

Para que serve

Coloque por escrito, antes da primeira linha de código, como vocês vão trabalhar, você e o agente. Parece uma formalidade e não é: é o que evita que o agente "ajude" expandindo o escopo, deixe dívida para depois, ou relate como feito o que acredita ter feito. Na minha ferramenta este arquivo se chama SQ.md (padrões de qualidade); o nome não importa, o conteúdo sim.

Pense assim: o agente é um colaborador novo que chega cada manhã sem memória de ontem. O contrato é o que você diz a ele no primeiro dia, e o que ele vai reler todos os dias. Se você não o escreve, vai ter que dizer a cada vez, e vai dizer diferente a cada vez. Eu o escrevi pela primeira vez quando já levava duas semanas repetindo a mesma coisa em cada sessão Ref. 1, e nada do que coloquei era novo em engenharia de sistemas; o novo era ter que escrevê-lo para alguém sem memória.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com seu conteúdo e seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

• Nenhum do projeto: é o primeiro arquivo.
• Seu: suas preferências de trabalho (idioma, como quer que lhe perguntem, o que considera uma perda do seu tempo, que nível de autonomia dá ao agente).

2. Prompts

Inicial:

O que estou pedindo: as seis regras mínimas, cada uma com a falha que evita (isso é o que as torna regras e não conselhos); que proponha regras próprias do projeto mas as marque como propostas, para que você as aceite ou rejeite; e que pergunte o que precisar saber sobre você. Um contrato redigido sem uma única pergunta é suspeito: o agente não conhece a pessoa com quem vai trabalhar.

De fechamento:

O que estou pedindo: que feche o contrato com data e versão, e que o engate ao arquivo de projeto para que seja lido em cada sessão. Sem esse engate o contrato existe mas não age.

3. Resultado esperado

Um arquivo docs/WORKING_AGREEMENT.md (ou SQ.md, ou CONTRATO.md) com:

• Data e versão.
• Cada regra numerada, em uma ou duas frases, com a falha que evita.
• As regras próprias do projeto, marcadas como tais.
• Uma linha ao pé que diga que o agente propõe mudanças mas não edita o contrato sozinho.

E uma linha no arquivo de projeto (PROJECT.md ou CLAUDE.md) que ordene lê-lo ao começar cada sessão.

4. Verificação de completude

• Estão as seis regras mínimas, cada uma com a falha que evita?
• Há alguma regra escrita como aspiração ("tentar…", "na medida do possível…")? Se há, não serve: as regras se cumprem ou não.
• O arquivo de projeto ordena lê-lo em cada sessão?
• O agente lhe fez pelo menos uma pergunta sobre como você trabalha? Se redigiu tudo sem perguntar nada, é suspeito: ele não conhece você.

5. Sinais de alerta

• O contrato tem mais de vinte regras. Ninguém, nem humano nem modelo, respeita vinte regras; respeitam-se seis ou oito.
• Uma regra diz "o agente pode modificar este contrato quando considerar necessário". Não.
• Duas semanas depois, o agente faz algo que o contrato proíbe e ninguém nota. O contrato não está sendo lido: revise o engate no arquivo de projeto.

Passo 2 — A definição do projeto, a árvore semântica e a leitura obrigatória (contrato do degrau)

Fase: arranque. Quando: escreve-se uma vez, depois do contrato; a árvore semântica e o estado vivo se mantêm em dia durante todo o projeto, com cada bloco e cada decisão nova. Forma: conversa: o agente redige, pergunta o que falta, você corrige. Tamanho: obrigatório em todo projeto. Num pequeno, o arquivo de projeto pode ter cinquenta linhas e a árvore semântica vinte nós; o que não podem é não existir.

Para que serve

Cada sessão do agente começa do zero: ele não se lembra de ontem. Dê a ele um mapa, curto, que diga o que é o projeto, em que estado está e que decisões já foram tomadas, e obrigue-o a lê-lo antes de tocar em qualquer coisa. A falha que evita é dupla: trabalho descartável por não ler o mapa Ref. 9, e o mapa que cresce até se tornar ilegível Ref. 41. A regra prática: o arquivo de projeto é o programa, não o histórico. O que aconteceu vai para outro lugar.

O mapa tem duas peças, e a segunda é a que mais trabalho faz. A primeira é o arquivo de projeto: o que é o sistema, para quem, o que NÃO é, as decisões tomadas. A segunda é a árvore semântica: o sistema decomposto como uma árvore, com os domínios, e abaixo de cada um seus atores, seus processos (os casos de uso), suas entidades com seus estados, suas telas e suas integrações; e de cada nó pendem as pendências e as decisões que o tocam. A árvore sai do levantamento que você fez com os métodos clássicos da engenharia de requisitos (entrevistas, casos de uso, modelo de domínio), o agente a constrói, você a corrige, e é o que dá ao modelo o contexto exato do nó que vai tocar sem ter que ler todo o projeto. E é o que permite a você verificar, sem ler código, que o sistema que o agente entende é o que o negócio pediu.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com seu conteúdo e seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

• Levantamento do negócio: o que o cliente faz, quem usa o sistema, que problema resolve, o que não tem que fazer. Com as entrevistas, os casos de uso ou histórias de usuário que você puder nomear, e as entidades do negócio com seus estados, mesmo que incompletos.
• O contrato de convivência (degrau 1).
• Se existe um sistema anterior: acesso de leitura ao seu código ou à sua documentação.
• As decisões já tomadas, se houver, mesmo que de boca.
• As palavras que o negócio de fato usa para cada coisa, e quem são os diferentes tipos de pessoa que vão usar o sistema. São as duas entradas prévias do Anexo H, e este degrau é onde se escrevem: sem elas, a matriz de perfis do degrau 8 se inventa e as regras de usabilidade não têm com que comparar.

2. Prompts

Inicial:

O que estou pedindo: que avalie o levantamento e pergunte antes de redigir; que o arquivo de projeto seja curto (o teto de trezentas linhas é arbitrário mas necessário: sem teto, cresce); que diga explicitamente o que o sistema não é, porque o que não está dito é o que o modelo vai inventar; que as decisões tenham data; que construa a árvore semântica com a estrutura completa (domínios, atores, casos de uso com suas partes, entidades com estados e transições, telas, integrações), que é o modelo de domínio da engenharia de requisitos posto em forma de árvore; que marque o que inferiu, porque é ali que se escondem as invenções; e que separe o estado vivo em outro arquivo, para que o mapa não se converta em histórico.

E as duas entradas prévias do Anexo H, que são as que fazem o degrau 2 não ser só um mapa para o modelo. O glossário do usuário é a lista de palavras que as pessoas de fato usam: "consulta", não "reserva de agenda"; "a moça do balcão", não "usuário operacional". Serve para duas coisas que vêm depois: nomear os grupos do menu com trabalhos do usuário, e que o texto das telas diga o que as pessoas dizem. A lista de perfis é quem é cada um e o que vem fazer, e é a coluna de que sai a matriz do degrau 8; se não estiver escrita aqui, no degrau 5 se inventa, e uma matriz inventada é a causa de alguém ver um botão que não lhe corresponde. Peço-lhe explicitamente que as pergunte em vez de deduzi-las, porque são dados do negócio e não do sistema; e que marque o inferido, pelo mesmo motivo que na árvore.

De fechamento:

O que estou pedindo: as suas correções (sobretudo aos nós que ele marcou como inferidos), a data, e duas regras novas no contrato: a que protege o arquivo de projeto de virar histórico, e a que ata cada pendência a um nó da árvore, que é o que mantém a árvore viva e o que permite a você detectar em dez segundos uma pendência fora de escopo.

3. Resultado esperado

• PROJECT.md (ou CLAUDE.md): curto, de leitura obrigatória, com o que é, para quem, o que não é, módulos, decisões com data, e a ordem de lê-lo junto com a árvore. Máximo de trezentas linhas.
• docs/SEMANTIC_TREE.md: a árvore semântica, com os nós inferidos marcados até que você os confirme, e, desde o primeiro bloco, as pendências e decisões pendendo de seus nós.
• docs/STATUS.md: estado vivo, separado dos anteriores.
• As duas entradas prévias do Anexo H, escritas e nomeadas em PROJECT.md: o glossário do usuário (as palavras que as pessoas de fato usam para cada coisa) e a lista de perfis (quem é cada um e o que vem fazer), com o inferido marcado. O método não te impõe o nome desses dois arquivos — ponha o que seu projeto usa —; o que sim exige é que existam, que se possam encontrar a partir do arquivo de projeto e que estejam antes do degrau 5.
• Nos três, uma data de última atualização.
• No contrato, as duas regras novas.

4. Verificação de completude

• PROJECT.md cabe numa leitura de cinco minutos? Se não, está errado: é o programa, não o histórico.
• Diz explicitamente o que o sistema NÃO faz? (O que falta é o que o agente vai inventar.)
• Percorra a árvore semântica como se fosse o cliente: estão todos os atores que você conhece? Cada entidade tem os estados que o negócio usa, nem mais nem menos? Há algum nó que você não reconhece? Esse é um invento: corrija agora.
• Os nós inferidos estão marcados? Você confirmou ou corrigiu todos?
• Cada decisão tem data e quem a tomou?
• O agente perguntou algo sobre o negócio antes de redigir? Se não perguntou nada, revise o que ele supôs.
• O estado vivo está em outro arquivo?
• Está escrito o glossário do usuário, com as palavras que as pessoas de fato usam para cada coisa? Leia-o e procure uma palavra que você não diria: se estiver, foi o sistema que a escreveu e não o negócio.
• Está escrita a lista de perfis, dizendo quem é cada um e o que vem fazer? Conte os perfis com os dedos do seu negócio: se faltar um, falta uma linha da matriz do degrau 8 e uma leva de casos de prova do 10.
• A prova de leitura: feche a sessão, abra uma nova, e pergunte o que o sistema NÃO faz e de que nó da árvore pende tal tela. Se responde com o mapa, o engate funciona.

5. Sinais de alerta

• O arquivo de projeto cresceu mais de 20 % em um mês. Algo que não é programa está entrando.
• O agente começa uma sessão propondo algo que já foi decidido e está escrito. Não leu o mapa: o engate de leitura obrigatória falhou.
• A seção "o que não é" está vazia ou diz "nada em particular". Todo sistema tem limites; se não estão escritos, o modelo vai cruzá-los.
• Há pendências que não pendem de nenhum nó da árvore. Ou a árvore ficou velha ou essas pendências estão fora de escopo; as duas coisas há que olhar.
• Uma entidade da árvore tem um estado que o negócio nunca nomeou. O modelo o inventou porque lhe pareceu lógico, e vai construir sobre ele.
• O glossário do usuário tem as mesmas palavras que a árvore semântica. Não é um glossário do usuário: é o vocabulário do sistema copiado duas vezes. Pergunte ao negócio como ele chama.
• A lista de perfis tem um só perfil, "usuário". Quase nunca é verdade, e é a forma mais comum de chegar ao degrau 8 com uma matriz de uma linha que não protege nada.

Passo 3 — Dimensionar antes de desenhar a arquitetura (contrato do degrau)

Fase: arranque. Quando: uma vez, depois da definição e antes de montar o esqueleto; refaz-se se o negócio muda de escala. Forma: conversa: o agente calcula e apresenta opções; você escolhe. Tamanho: obrigatório sempre, mas proporcional: num projeto pequeno o dimensionamento pode ser meia página e uma única decisão ("cabe em SQLite durante anos"). O que não pode é não ser feito, porque a pergunta "quanto vai crescer?" custa cinco minutos e a resposta errada custa semanas.

Para que serve

Tome as decisões estruturais — que motor de banco de dados, se a interface é síncrona ou assíncrona, quanta concorrência — com números e não com gosto. É o degrau que mais caro custa pular, e digo com conhecimento de causa: num dos meus sistemas comecei com arquivos JSON e quando medi resultou que ia gerar 3,4 milhões de linhas por ano; mudar a interface depois custou uma etapa inteira de reengenharia Ref. 15.

Há um ponto-chave que vale a pena ter presente: há dados que só o negócio tem (quantas entidades, quantos eventos por entidade, quantos operadores no pico, quanto tempo há que conservar) e o modelo não pode inferi-los. O que ele pode inferir é o derivado. Por isso o prompt exige que ele avalie se os dados primários estão completos e peça os que faltam, em vez de estimá-los com cara de quem tem certeza. Quem sabe o que lhe falta para calcular é o modelo, não um formulário.

E uma segunda ideia que quero que você leve: as decisões assimétricas. Há decisões que custam muito pouco se você as toma e resultam desnecessárias, e muitíssimo se não as toma e resultam necessárias. A interface de persistência assíncrona desde a linha um é o exemplo canônico: se o motor acaba sendo síncrono, sobrou um await; se acaba sendo assíncrono e você não previu, há que reescrever tudo. Essas decisões, tome-as sempre que forem baratas, mesmo que hoje não sejam necessárias.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com seu conteúdo e seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

• Levantamento de dados de volumetria do negócio, nomeado assim de forma genérica: entidades principais e seu crescimento, eventos por entidade, operadores simultâneos e horário do pico, tempo de conservação dos dados, cargas excepcionais (campanhas, fechamentos), crescimento esperado. O levantamento é por natureza incompleto; o agente avalia e pede.
• Se há um sistema anterior: acesso de leitura ao seu banco para tirar números reais em vez de estimados.
• PROJECT.md e a árvore semântica (degrau 2): as entidades da árvore são as que há que dimensionar.

2. Prompts

Inicial:

O que estou pedindo, cláusula por cláusula: distinguir primários de derivados (é a distinção que evita o invento); pedir os primários que faltam e nunca estimá-los; usar números reais do sistema anterior quando existir, com sua fonte; calcular o derivado com a conta à vista, para que você possa refazê-la; o cenário "por dez", que é o que revela o que quebra primeiro; três opções com o custo de migrar entre elas, porque a decisão não é só "qual" mas "quanto custa errar"; e que não escolha nem escreva código, porque este degrau é de decisão, não de construção.

De fechamento:

O que estou pedindo: o registro completo, com fontes e contas; a escolhida e a razão; e as decisões assimétricas escritas, porque se ficam implícitas não se respeitam.

3. Resultado esperado

Um arquivo docs/SIZING.md com:

• Data e quem decidiu.
• Tabela de dados primários: valor, fonte (informado pelo negócio / medido no sistema anterior), data. Nenhum com fonte "suposição".
• Tabela de dados derivados: valor, de que primários sai, a conta.
• O cenário "por dez": o que quebra primeiro.
• As três opções numeradas, com o custo de migrar entre elas.
• A escolhida e a razão, em uma ou duas frases.
• As decisões assimétricas, listadas.
• As perguntas que o agente fez e as respostas.

4. Verificação de completude

• Há algum dado primário com fonte "suposição" ou sem fonte? Se há, o degrau não foi subido: o agente tinha que pedi-lo.
• Cada dado derivado mostra de que primários sai e com que conta? Você consegue refazer uma conta à mão e dá o mesmo?
• Há três opções e uma escolhida com razão escrita?
• Diz o que acontece se a volumetria se multiplica por dez?
• As decisões assimétricas estão escritas, ou ficaram implícitas?
• O agente perguntou? Se apresentou números sem ter feito uma única pergunta, desconfie.

5. Sinais de alerta

• Os três cenários de opções levam à mesma conclusão. O agente já tinha escolhido e montou as outras duas para cumprir.
• Um número derivado tem mais precisão do que os primários de que sai ("1.234.567 linhas" a partir de "umas 5.000 famílias"). A precisão é falsa.
• O cenário "por dez" diz "não acontece nada". Sempre acontece algo; se ele não encontrou, não procurou.

Passo 4 — O esqueleto com suas comportas (contrato do degrau)

Fase: arranque. Quando: uma vez, no fechamento do arranque, depois do dimensionamento e antes de qualquer funcionalidade. É aqui que se faz toda a infraestrutura inicial e a cadeia de integração e implantação. Forma: um disparo longo, com aprovação visual sua no final. Tamanho: obrigatório em todo projeto que vá ter usuários. Num protótipo descartável pode-se pular; mas se o protótipo sobrevive (sempre sobrevivem), este degrau é a primeira coisa que há que pagar.

Para que serve

Faça o sistema arrancar, ser testado e ser implantado VAZIO antes de ter funcionalidade. Descobrir a implantação no final é caríssimo: num dos meus sistemas ela chegou um mês depois do arranque e custou cinco pendências seguidas Ref. 32. Se o esqueleto é implantado no arranque, esses tropeços acontecem com zero funcionalidade em jogo.

A ideia geral por trás: o caminho para a produção é parte do produto, não um trâmite do final. Um sistema que funciona na máquina do programador e não pode ser implantado não é um sistema; é uma demo. E a única forma de saber que o caminho funciona é percorrê-lo quando ainda não há nada a perder. Por isso neste degrau se monta tudo o que depois o ciclo vai usar: o repositório com sua estrutura, o ambiente de teste, a integração contínua que roda a bateria em cada push, e a implantação automática no ambiente de teste.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com seu conteúdo e seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

• docs/SIZING.md (degrau 3): a opção escolhida define o esqueleto.
• Levantamento de ambientes: onde vai rodar (nuvem, servidor próprio), se há um ambiente de teste e um de produção, quem tem acesso, como se implanta hoje se já há algo.
• As credenciais do lugar onde vai ser implantado, mesmo que seja um serviço gratuito.
• O tipo de projeto: novo, correção ou evolução de algo existente.

2. Prompts

Inicial:

O que estou pedindo: que verifique que tem os acessos antes de começar (sem isso o esqueleto fica na máquina do agente); a lista exata do que é um esqueleto (estrutura, arranque, um teste, integração contínua, implantação em teste); as comportas escritas; uma captura real do ambiente de teste, que é a única evidência válida de que foi implantado; e a proibição explícita de acrescentar funcionalidade, porque o modelo tende ao "já que estou aqui" e isso rompe o escopo exato.

De fechamento:

O que estou pedindo: deixar os três comandos onde a próxima sessão os encontre, e provar que a implantação é repetível (rodá-la duas vezes sem quebrar nada). Essa segunda execução é a prova de que o procedimento é um procedimento e não uma sorte.

3. Resultado esperado

• O repositório com a estrutura, o servidor e a tela arrancando.
• Um teste de fumaça em verde e a bateria rodando em integração contínua (com o link para a execução em verde).
• A implantação no ambiente de teste funcionando, com a URL, e rodada duas vezes.
• docs/GATES.md: a lista de comportas, cada uma com a condição para passar.
• Uma captura de tela do sistema vazio rodando no ambiente de teste.
• docs/STATUS.md atualizado com os três comandos (rodar, testar, implantar).

4. Verificação de completude

• Você consegue abrir a URL do ambiente de teste e ver a tela vazia? (Você faz isso, não o agente.)
• Há um link para uma execução de integração contínua em verde?
• A implantação foi rodada duas vezes e a segunda não quebrou nada?
• As comportas estão escritas com uma condição verificável cada uma?
• Há alguma funcionalidade que você não pediu? Se há, o agente violou o escopo exato.

5. Sinais de alerta

• O esqueleto "funciona em local" mas a implantação "a gente vê depois". Não: a implantação é o esqueleto.
• A captura de tela é da máquina do agente, não do ambiente de teste. Peça a URL.
• As comportas dizem coisas como "o código tem boa qualidade". Uma comporta é uma condição verificável: "a bateria está em verde", "a implantação em teste funcionou".

Passo 5 — O plano são as pendências: a especificação detalhada vive em cada uma (contrato do degrau)

Fase: ciclo. Quando: o registro se cria ao abrir o primeiro bloco funcional, assim que termina o arranque; cada bloco novo começa convertendo o pedido do cliente em pendências especificadas; a rotina se usa em cada sessão durante todo o projeto; a documentação da pendência feita se escreve ao fechá-la, na mesma sessão. Forma: um disparo ao abrir cada bloco; depois, rotina de cada sessão. Tamanho: obrigatório em todo projeto. É o degrau que faz com que todos os demais possam ser seguidos: sem pendências numeradas e especificadas não há onde pendurar nem a especificação nem a evidência.

Para que serve

Tenha uma única fila de trabalho, com ordem e com comporta, que seja a verdade do projeto. Não há "plano" de um lado e "tarefas" do outro: a lista de pendências É o plano. Evita a especificação longa que é superada em duas semanas e fica obsoleta Ref. 17, e o trabalho do qual ninguém sabe por que foi feito Ref. 7.

Mas há mais, e é o que distingue este degrau de uma lista de tarefas qualquer. No método clássico existia um documento de especificação de requisitos, longo, que descrevia tudo o que o sistema tinha que fazer e que envelhecia antes de ser terminado. Aqui esse documento se decompõe: a especificação detalhada vive em cada pendência. Uma pendência bem escrita traz: o nó da árvore semântica de que pende; a história de usuário ou caso de uso que a origina, com as palavras do cliente; a descrição detalhada; as regras de negócio aplicáveis, com sua decisão e sua data; os dados que entram e saem; as telas afetadas, com o protótipo se houver; os casos de borda e as exceções; os critérios de aceitação na forma "dado, quando, então"; e como se verifica. A soma das pendências é a especificação do sistema, e a rastreabilidade (requisito → pendência → teste → commit) não é uma matriz à parte: é a própria pendência.

E a terceira coisa, que fecha o círculo: as pendências fechadas são documentação. Quando uma pendência se fecha, não se apaga nem se arquiva vazia: fica com sua especificação, a decisão que a originou, a evidência com que se fechou (os números do vermelho e do verde, a captura, o número medido), o commit e a data. A fila de pendências fechadas é o histórico funcional do sistema: o que se construiu, por quê, quando e como se testou. Dali saem o diário de mudanças, as seções novas do manual, e a resposta a "por que o sistema faz isto?" seis meses depois.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com seu conteúdo e seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

• O pedido do cliente para o bloco, em prosa, tal como ele o diria, com suas ambiguidades. Se você fez casos de uso ou histórias de usuário na ingestão, melhor: são a unidade natural de um bloco.
• A árvore semântica (degrau 2), para pendurar cada pendência em seu nó.
• As auditorias e os achados dos testes humanos, se já houve.
• PROJECT.md e docs/STATUS.md.

2. Prompts

Para abrir um bloco:

O que estou pedindo: que converta o pedido em itens verificáveis e que pergunte quando o pedido não dá para escrever um verificável (a ambiguidade se resolve perguntando, não escolhendo); a especificação completa de cada pendência, campo por campo, que é a engenharia de requisitos clássica decomposta em unidades pequenas; o nó da árvore de que pende, que é o que permite a você detectar uma pendência fora de escopo; as regras de negócio com sua decisão ou marcadas como faltantes, que é o engate com o degrau 6; os critérios de aceitação na forma clássica, que são o roteiro do teste de ponta a ponta do degrau 8; e uma ordem proposta com sua razão, para que você a confirme ou mude.

Rotina de cada sessão (vai no contrato de convivência):

O que estou pedindo: a disciplina de cada sessão: anunciar o que pega e reler a especificação (o agente começa sem memória, e a especificação é a sua memória da pendência), citar a pendência em cada commit, fechar com evidência, documentar a pendência feita no mesmo registro, e anotar em vez de fazer o que aparecer fora da lista. Essa última cláusula é a que protege o escopo exato quando o modelo "vê algo mais".

3. Resultado esperado

docs/PENDING.md (ou a ferramenta que seu projeto usar) com, por pendência:

• Número, título, estado (aberta / em curso / fechada), data de abertura e de fechamento.
• O nó da árvore semântica.
• A história ou caso de uso de origem, com as palavras do cliente.
• A especificação detalhada: descrição, regras de negócio com decisão e data, dados, telas, casos de borda, critérios de aceitação, como se verifica.
• Ao fechar: a evidência, o commit, a data, as decisões tomadas no caminho.

E a rotina no contrato de convivência.

4. Verificação de completude

• Leia a especificação de uma pendência ao acaso como se fosse o cliente: descreve o que você pediu, com as suas palavras de origem? Os critérios de aceitação são os que você usaria para dizer "está bom"? Há um caso de borda que você conhece e não está?
• Cada pendência pende de um nó da árvore? Há alguma pendurada num nó que você não reconhece?
• Cada pendência diz como se verifica? Uma pendência sem verificação não pode ser fechada.
• Há regras de negócio marcadas como "faltante, perguntada" que não lhe perguntaram?
• Há pendências "fechadas" sem evidência nem commit? Se há, reabra-as. As fechadas conservam sua especificação e sua documentação de fechamento?
• Pegue três commits ao acaso: citam sua pendência?
• Apareceu no código algo que não tem pendência? Aí o agente saiu do escopo.

5. Sinais de alerta

• Uma pendência leva mais de três sessões "em curso". Ou são três pendências, ou está travada por uma decisão que ninguém tomou (degrau 6).
• Há mais pendências fechadas num dia do que commits nesse dia. Estão sendo fechadas sem evidência.
• As especificações são de uma linha. O agente as escreveu para cumprir, não para construir sobre elas; vai inventar o que falta na hora de construir.
• A lista tem mais de cinquenta pendências abertas. Não é um plano, é um inventário de ansiedades: há que priorizar e arquivar.
• Alguém pergunta por que o sistema faz algo e a resposta não está em nenhuma pendência fechada. A documentação do feito não está sendo escrita.

Passo 6 — As decisões se escrevem junto ao código (contrato do degrau)

Fase: ciclo. Quando: em cada sessão do ciclo, cada vez que o agente topa com uma regra de negócio não escrita ou com uma bifurcação que muda o que o usuário vê. Costumam ser duas ou três por bloco. Também no arranque (degraus 0 e 3) e na saída para produção (14 e 15). Forma: conversa curta: o agente detecta que há uma decisão, pergunta, e a deixa escrita. Tamanho: obrigatório em todo projeto. Num pequeno o registro pode ser uma tabela de dez linhas; o que importa é que as regras de negócio tenham dono.

Para que serve

Faça com que cada regra de negócio e cada decisão estrutural tenha dono, data e lugar. Se não, em seis semanas ninguém sabe se "aprovada mais saldo volta para a fila" foi uma decisão do cliente ou uma ocorrência do agente. E evite o pior: o agente inventando regras de domínio porque lhe pareceram razoáveis.

Isso tem uma consequência que quero dizer em voz alta: o modelo, quando encontra um buraco nas regras, o preenche. Não para; completa com o que lhe parece mais provável, e faz isso com a mesma naturalidade com que escreve o resto. Por isso a rotina deste degrau não é "escreva as decisões" mas "pare e pergunte quando faltar uma". A segunda é a difícil, e é o que há que exigir no contrato. A prática de deixar a regra escrita no commit, com as minhas palavras e a data, eu a impus no Plano de Saúde Ref. 29, e a de congelar as decisões antes de construir vem da minha ferramenta Ref. 5.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com seu conteúdo e seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

• A conversa com o dono: é o único contexto. O agente não pode decidir regras de negócio.
• Um lugar acordado onde se escrevem as decisões: a mensagem do commit, a especificação da pendência, e um registro docs/DECISIONS.md.

2. Prompts

Rotina (vai no contrato de convivência):

O que estou pedindo: que pare diante de uma regra não escrita ou de uma bifurcação visível; que pergunte com recomendação e alternativa (para que você decida em dez segundos, não em dez minutos); que registre a decisão com as suas palavras textuais nos três lugares (o commit, a pendência, o registro), não com uma paráfrase "melhorada"; e, para quando você não responde, a opção mais reversível marcada como "por omissão", que é o que permite seguir sem que a decisão desapareça.

De fechamento (cada decisão):

O que estou pedindo: o formato mínimo de uma decisão: a regra textual, quem, quando. Três coisas; sem qualquer uma das três não é uma decisão registrada.

3. Resultado esperado

• docs/DECISIONS.md: uma linha ou um parágrafo por decisão, com data, quem decidiu, a frase textual, a pendência ou commit onde se aplicou, e se foi "por omissão".
• Na especificação de cada pendência afetada: a regra com sua decisão e data.
• Em cada commit que implementa uma regra de negócio: a frase de origem.

4. Verificação de completude

• Abra três commits que toquem regras de negócio: cada um cita quem decidiu e quando?
• Há decisões "por omissão" sem confirmar? Confirme-as ou reverta-as; não as deixe.
• Há alguma regra no sistema que você não reconhece como sua? Se há, o agente a inventou: é uma falha do degrau, escreve-se como pendência e se revisa.
• As frases estão textuais ou "melhoradas" pelo agente? Têm que ser as suas.

5. Sinais de alerta

• Passou uma semana de trabalho e o registro de decisões não cresceu. Ou o trabalho foi puramente mecânico (raro) ou o agente decidiu sozinho.
• As decisões registradas estão todas redigidas com o mesmo estilo polido. São paráfrases do agente, não as suas palavras.
• Um usuário do sistema pergunta "por que ele faz isto?" e ninguém encontra a decisão.

Passo 7 — Medir antes de construir, com um instrumento que também se verifica (contrato do degrau)

Fase: ciclo. Quando: cada vez que uma pendência depende de um número ou de uma hipótese de causa, ANTES de construir. No arranque, o dimensionamento é o primeiro caso. Num projeto pequeno, "medir" é contar com um comando e anotar o número com a data. Forma: um disparo por medição; às vezes uma conversa quando a hipótese é sua. Tamanho: proporcional. A catraca e o orçamento de consultas são para sistemas com volume. O que não muda com o tamanho: nenhum número que decide algo sai de uma impressão.

Para que serve

Faça com que todo número que alimenta uma decisão saia de um programa com teste, e não de uma busca de texto, de uma impressão, nem de "acho que são uns cem". E faça com que o próprio instrumento seja auditado, porque os medidores mentem: um dos meus não via 84 chamadas com o contador em zero, e outro dizia 27 quando eram 44 Ref. 35, Ref. 36. As cinco regras que escrevi depois disso são: medidor com guarda; se o instrumento não existe, constrói-se; audita-se em duas direções; o aproximado se marca; e quem executa verifica os números de quem planejou.

Este degrau é o que mais demorei a formalizar, e por uma razão que vale a pena contar: dava por certo que um modelo aplicaria sozinho algo tão básico da engenharia como "meça antes de tocar". Não aplica. O modelo é muito bom em produzir afirmações com número ("há uns 120 laços desse tipo") e essas afirmações soam exatamente igual quando estão medidas e quando estão estimadas. Você não tem como distingui-las pelo tom. A única forma é exigir o instrumento: "com que você mediu? mostre-me o comando". Se não há comando, é uma impressão, por mais decimais que tenha. As regras, eu as impus em sessão, corrigindo o agente, antes de que fossem doutrina Ref. 45.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com seu conteúdo e seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

• A hipótese, sua ou do agente: "acho que o problema é X", "devem ser uns cem".
• Acesso ao que se quer medir: o código, o banco em somente leitura, o log.
• Os medidores que já existem no repositório, se houver.

2. Prompts

Inicial:

O que estou pedindo, cláusula por cláusula: o medidor no repositório (não um comando solto que se perde); o teste do medidor contra um caso conhecido (a guarda); a cláusula de completude na sua forma para medir (pedir o acesso, não aproximar em silêncio); marcar o aproximado com sua margem; o número com o comando que o produz, para que você possa rodá-lo; a auditoria em duas direções, que é o que desmascarou os meus dois medidores que mentiam; e a ordem: primeiro medir, depois propor.

Quando há um orçamento:

O que estou pedindo: que o orçamento seja o medido mais pouco, não um número redondo, e que tenha um teste que falhe se for superado. Assim uma regressão de desempenho aparece na bateria e não em produção Ref. 37.

Quando quem planejou deu números (regra cinco):

O que estou pedindo: que quem executa não confie nos números de quem planejou, mesmo que seja o mesmo modelo em outra sessão. No meu caso, três de quatro afirmações do plano estavam erradas; onde havia instrumento, o número era exato.

3. Resultado esperado

• O medidor no repositório (tools/measure_*.py, scripts/meter-*.mjs ou similar), com seu teste.
• O número, com o comando que o produz e a data.
• A auditoria em duas direções, escrita em duas ou três linhas.
• O aproximado marcado como tal, com sua margem.
• Se há orçamento: o valor, a margem, e o teste que o protege.
• No commit: "measured: [number] with [meter]".

4. Verificação de completude

• Você consegue rodar o comando do medidor e dá o mesmo número? (Você roda; não precisa entendê-lo, só executá-lo.)
• O medidor tem teste? Contra que caso conhecido?
• Há algum número no relatório sem medidor por trás? Pergunte de onde saiu.
• O aproximado está marcado?
• Se o plano trazia números, o agente os verificou antes de executar e lhe disse quais não batiam?

5. Sinais de alerta

• Um número mudou entre dois relatórios sem que o código mudasse. Um dos dois não foi medido.
• O medidor dá zero. Quase nunca é zero; quase sempre o medidor não está vendo algo.
• O agente propõe construir "enquanto mede", para ganhar tempo. A ordem é o método: primeiro o número, depois o plano.

Passo 8 — Testes como cadeados, provados em vermelho (contrato do degrau)

Fase: ciclo. Quando: com cada pendência, ao fechá-la: o teste em vermelho e em verde, a regressão das vizinhas e o teste de ponta a ponta do fluxo tocado. A bateria completa de ponta a ponta de todos os fluxos, no fechamento de cada bloco e antes de cada implantação em produção. Forma: um disparo; o agente executa e relata, você lê o relatório. Tamanho: obrigatório em todo projeto. É o coração do método: se há um degrau que não se pode negociar, é este.

Para que serve

Um teste que você nunca viu falhar, você não sabe se prova algo. A regra aqui não é "escreva testes": é "demonstre que o teste fica em vermelho contra o código antigo, e depois em verde com o novo". Evita os testes que passam porque não provam nada, e o verde que esconde um bug Ref. 44.

Por que isto é mais importante com um modelo do que com um programador humano: o modelo escreve o código e o teste na mesma sessão, com o mesmo entendimento. Se entendeu mal o pedido, o teste vai provar o que ele entendeu, e vai passar. O vermelho contra o código antigo é a única forma barata de comprovar que o teste está olhando o que importa: se o código antigo o passa, o teste não distingue o antes do depois, e então não serve. O caso que melhor mostra isso é o dos contadores que não coincidiam Ref. 26.

Há uma objeção séria a este degrau, e quero deixá-la escrita porque vão usá-la contra: o mesmo agente que escreve o teste e o código pode fingir o vermelho. Um estudo publicado em agosto de 2026 mediu que, quando se pede a um agente o ciclo de teste primeiro, às vezes ele pula o vermelho, relata-o sem tê-lo rodado, ou implementa antes do teste para que passe de primeira (está na Parte F do documento principal, a dos trabalhos relacionados). A minha resposta tem três peças, e as três estão na escada. A primeira, aqui: o vermelho não é um relato, é um recibo: o comando exato, o identificador da versão contra a qual rodou, a quantidade de testes que falham e o código de saída, tudo colado tal como saiu, de maneira que você possa voltar a rodá-lo com um único comando sem entender o que ele faz. A segunda, no degrau 13: a auditoria por outra sessão volta a rodar uma amostra desses recibos. A terceira, no degrau 9: os testes de mutação, que plantam erros de propósito e contam quantos os testes capturam; é a única medida que, nesse mesmo estudo, distinguiu os testes que vigiam dos que decoram.

E a segunda metade: os testes de ponta a ponta. Um teste que verifica desde a tela (clica, digita, lê) e comprova o efeito no backend (a linha ficou, o estado mudou) é o que substitui a sua leitura do código. Os critérios de aceitação da pendência ("dado, quando, então") são o seu roteiro. E rodam três vezes em três escalas: o fluxo tocado com cada pendência, todos os fluxos no fechamento de cada bloco, e todos os fluxos com a versão exata antes da produção.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com seu conteúdo e seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

• A mudança já implementada (por padrão os testes vêm depois de implementar; "primeiro o teste" fica como opção para escopos pequenos e bem definidos).
• A pendência que origina a mudança, com seus critérios de aceitação e seu "como se verifica".
• A bateria existente e o comando para rodá-la (degrau 4).

2. Prompts

Rotina (vai no contrato de convivência; aplica-se em cada mudança):

O vermelho do primeiro bloco. No primeiro bloco de um projeto novo não há código anterior: o teste novo falha porque o módulo não existe, e essa falha não prova que o teste distingue comportamento. Por isso, quando a versão anterior não tem o módulo, o vermelho se prova por mutação: o agente planta um defeito de propósito na função que acabou de escrever, mostra o teste em vermelho contra esse defeito (o recibo leva o diff do defeito, para você ver que não foi trivial), reverte-o e mostra o verde. É um só mutante por pendente, executado e registrado como qualquer outro recibo; os testes de mutação sobre toda a base continuam sendo o reforço opcional do degrau 9. (Decisão D-037, a partir da prática Turnera: seis recibos de vermelho que só diziam "o arquivo não carrega".)

O que estou pedindo, cláusula por cláusula: (1) o teste, guiado pelos critérios de aceitação da pendência; (2) o vermelho demonstrado como recibo (comando, versão, números, código de saída), que é a cláusula que distingue este método de "escreva testes" e a que impede que o vermelho seja um relato; (3) o verde; (4) a regressão das vizinhas na mesma sessão, porque uma mudança quebra coisas ao lado; (5) o teste de ponta a ponta do fluxo tocado, com o efeito no backend à vista; (6) não simular justamente o que se testa; e a cláusula de completude adaptada a este degrau: se falta algo para testar de ponta a ponta, pedir, não simular. A mensagem de commit com os números deixa a evidência onde vive o código.

No fechamento de cada bloco e antes de cada implantação em produção:

O que estou pedindo: a segunda e a terceira escala dos testes de ponta a ponta, com a versão exata (não "a última"), com o efeito no backend por fluxo, e com a cláusula de completude: o que não está coberto se declara e vira pendência, não se dá por coberto.

Quando o agente diz que não dá para testar:

O que estou pedindo: que "não dá para testar" não seja o fim da conversa mas o começo de uma pendência. A não-testabilidade é dívida, e a dívida se registra.

3. Resultado esperado

• O teste novo no repositório, nomeado com a pendência que fecha.
• No relatório do agente e na mensagem do commit: a saída em vermelho como recibo (o comando, a versão contra a qual rodou, quantos falham, o código de saída), a saída em verde, e a regressão em verde com seus números.
• O teste de ponta a ponta do fluxo tocado, com a evidência de que o backend mudou (a linha, o registro, o estado).
• No fechamento de cada bloco e antes da produção: a bateria completa de ponta a ponta em verde, por fluxo, com a versão exata.

4. Verificação de completude

• O relatório mostra o vermelho? Com números: "4 de 8 falham contra o critério antigo". Se só mostra verde, o degrau não foi subido.
• O vermelho é um recibo ou um relato? Tem que ter o comando exato, a versão contra a qual rodou, os números e o código de saída. Uma vez por bloco, escolha uma pendência ao acaso e rode você mesmo esse comando: o vermelho tem que voltar a aparecer.
• A regressão rodou na mesma sessão? Quantos testes, quantos em verde?
• Há alguma parte "simulada" (mock) justo onde está a mudança? Pergunte ao agente o que simulou e por quê.
• O commit cita a pendência e diz "provado em vermelho"?
• O teste de tela verifica também o efeito no backend?
• No fechamento do bloco: estão todos os fluxos na bateria de ponta a ponta, ou há algum que "se cobre com os unitários"?

5. Sinais de alerta

• Todos os testes novos da semana passaram em verde de primeira, e nunca se mostrou um vermelho. Ou o agente está omitindo o passo ou os testes não provam nada.
• A bateria demora cada vez mais e ninguém sabe por quê. Costuma ser que os testes de ponta a ponta foram sendo substituídos por simulações "para rodar rápido".
• O agente relata "os testes passam" sem dizer quantos. Sempre com números.
• O vermelho vem contado em prosa ("o teste falhou como se esperava") sem comando, sem versão e sem números. Um vermelho sem recibo vale o mesmo que nenhum.
• Você chega à saída para produção e a bateria completa de ponta a ponta roda pela primeira vez. Faltaram os fechamentos de bloco.

Passo 9 — Qualidade do código verificada por máquina, com comporta (contrato do degrau)

Fase: ciclo. Quando: monta-se uma vez, ao abrir o primeiro bloco funcional (assim que termina o arranque), e a partir daí roda sozinho em cada commit, como comporta da integração contínua; cada pendência se fecha com a qualidade em verde, depois do teste em vermelho (8) e antes do caso de teste manual (10). No fechamento de cada bloco e antes de cada implantação, o relatório de qualidade se lê com o dono. Num legado, a primeira corrida é a linha base e os achados entram na lista de pendências com a sua marca de velocidade. Forma: um único disparo para montar; depois, rotina de cada mudança e leitura por bloco. Tamanho: obrigatório no seu nível mínimo em todo projeto (um linter e um limite de tamanho na cadeia); completo, com testes de mutação incluídos, em qualquer projeto com usuários. Os testes de mutação ficam como reforço opcional só quando não há usuários reais (uma ferramenta interna, um protótipo que mais ninguém roda).

Para que serve

O dono não lê o código, e esse é o ponto do método. Mas o código existe, alguém vai mantê-lo (o próximo agente, o próximo desenvolvedor), e um código que funciona hoje e é ilegível amanhã é dívida que se cobra no mês três. Se ninguém o lê, uma máquina tem que olhá-lo: ferramentas que, em cada commit, medem o que um revisor humano olharia e o convertem num número com um limite. Eu fiz isso em todos os meus projetos, sem nomeá-lo como degrau, e uma auditoria de qualidade me devolveu um componente de mais de duas mil linhas e um arquivo de projeto de quase dez mil Ref. 41: nenhum dos dois teria passado um limite de tamanho escrito. A catraca estática, que impede que um número de qualidade piore Ref. 35, é a forma que dou a este degrau.

O que se mede por máquina, em ordem de importância: que o código respeite um estilo único (o linter e o formatador); que nenhuma função nem nenhum arquivo passe de um tamanho; que a complexidade de cada função fique abaixo de um limite; que não haja código duplicado nem código morto; que as dependências estejam declaradas e usadas; que a cobertura dos testes nunca baixe (a catraca); e, se a linguagem permitir, que os tipos fechem. Nada disto substitui o teste em vermelho: um código impecável pode estar errado. O que evita é o código correto que ninguém pode voltar a tocar.

E a peça que deixo de tratar como reforço opcional em qualquer projeto com usuários: os testes de mutação. Deixei-os como "opcional, recomendado" numa versão anterior deste documento, e uma avaliação externa do método me fez notar a contradição: se a Parte F diz que a mutação é, até onde sei, a única medida que nos estudos de 2026 distinguiu os testes que provam dos que decoram, não faz sentido deixá-la fora de "completo" justamente nos projetos onde mais um teste decorativo prejudica alguém. Uma ferramenta planta erros de propósito no código (troca um "maior" por "maior ou igual", apaga uma linha, inverte uma condição) e roda os testes; cada erro que os testes não capturam é um mutante que sobrevive, e a proporção de capturados é a pontuação. É a medida que complementa o vermelho demonstrado do degrau 8: o vermelho prova que um teste vigia a mudança de hoje; a mutação mede quanto a bateria inteira vigia. E é, até onde sei, a única que nos estudos de 2026 distinguiu os testes que provam dos que decoram (Parte F do documento principal).

Se você está começando. Um linter é um programa que lê o código e marca o que está mal escrito ou é perigoso (uma variável que não se usa, uma comparação que sempre dá o mesmo), como o corretor ortográfico de um processador de texto. Um formatador o arruma com um estilo único (recuos, espaços) para que todo o código pareça escrito pela mesma mão. A complexidade de uma função é quantos caminhos diferentes ela pode tomar (cada "se" a aumenta); uma função com quarenta caminhos ninguém entende. Código duplicado é o mesmo bloco copiado em dois lugares: no dia em que se conserta um, o outro fica errado. A cobertura é que porcentagem do código é executada por algum teste. E uma catraca é um mecanismo que só deixa melhorar: o número de hoje é o piso de amanhã. Os testes de mutação são um programa que quebra o código de propósito, uma mudança pequena por vez, e olha se algum teste percebe; se nenhum percebe, esse pedaço de código não está vigiado.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com o seu conteúdo e o seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

• A integração contínua rodando em cada push (degrau 4).
• O primeiro bloco funcional aberto, com ao menos uma pendência construída: sem código não há qualidade que medir.
• A sua decisão sobre os limites, ou a disposição de aceitar os que o agente propuser, com razão.
• A auditoria anterior (13, ou N3 num legado), se houve.

2. Prompts

Inicial (montar a comporta):

O que estou pedindo: as cinco verificações que um revisor humano faria, feitas por máquina e com a construção em vermelho como consequência, porque uma verificação que não bloqueia é um conselho; os limites com o seu valor medido, para que o limite saia do número e não de uma opinião; a catraca de cobertura, que é a peça que faz com que a qualidade não se degrade sozinha; e não consertar nada ainda, porque num sistema com código já escrito a primeira corrida sempre dá vermelho e a decisão sobre o que se conserta agora e o que se tolera com data é minha.

Rotina (vai no contrato de convivência):

O que estou pedindo: que a qualidade seja parte do fechamento de cada pendência e não uma tarefa à parte; a proibição de silenciar (um modelo diante de um linter em vermelho tende a acrescentar a exceção em vez de consertar, porque é mais rápido) e de subir o limite; e a leitura por bloco, que é o único momento em que você olha os números.

Obrigatório em qualquer projeto com usuários (opcional só sem usuários reais): testes de mutação.

O que estou pedindo: a medida que a cobertura não dá (a cobertura diz que código foi executado; a mutação diz que código está vigiado); o escopo restrito às linhas mudadas, que é o que faz com que o custo se possa pagar em cada pendência; não consertar nada ainda, porque decidir que mutante importa é meu; e a pontuação no fechamento de cada bloco, junto à cobertura, com uma queda tratada como vermelho.

3. Resultado esperado

• O linter, o formatador, os limites, a detecção de duplicação e código morto, a cobertura com catraca e os tipos, rodando em cada push e em vermelho quando corresponde.
• docs/CODE_QUALITY.md com ferramentas, configuração, limites com valor medido, e a lista do que falha com a sua pendência ou a sua data.
• A comporta em docs/GATES.md e a rotina no contrato.
• Em qualquer projeto com usuários: a pontuação de mutação em docs/CODE_QUALITY.md, por bloco, junto à cobertura, e uma pendência por cada mutante que sobrevive em código que importa.

4. Verificação de completude (você a faz, sem ler código)

• Peça a ele o link da última corrida da cadeia: a qualidade está em verde?
• Peça a ele que coloque de propósito, num ramo, uma função de cem linhas e uma variável sem uso: a cadeia fica em vermelho pelas duas coisas?
• A cobertura de hoje é maior ou igual à do fechamento do bloco anterior? Peça os dois números.
• Há alguma exceção ao linter no código? Peça a lista; cada uma tem que ter razão escrita.
• Subiu algum limite desde a primeira corrida? Com que razão e quem o decidiu?
• Se o projeto tem usuários reais: os testes de mutação estão rodando? Se não, que razão escrita justifica não tê-los?
• Se há testes de mutação: quantos mutantes sobreviveram no último bloco, e cada um tem pendência ou razão escrita?

5. Sinais de alerta

• A qualidade passou em verde de primeira sobre código já escrito. Quase nunca é verdade: os limites estão frouxos demais.
• O agente propõe "desativar esta regra porque é muito estrita". Às vezes tem razão; sempre tem que passar por você com a razão escrita.
• A cobertura sobe porque se acrescentaram testes que não provam nada (o verde que esconde um defeito, degrau 8). A catraca mede quantidade; o vermelho demonstrado mede qualidade. Vão juntos.
• Um arquivo cresceu até o limite e se partiu em dois arquivos com o mesmo conteúdo. É a duplicação disfarçada de cumprimento.
• A cobertura é alta e a pontuação de mutação é baixa. São testes que executam o código sem verificar nada: o caso exato que o vermelho demonstrado do degrau 8 tenta evitar.
• O projeto tem usuários reais e ninguém rodou os testes de mutação nem escreveu por quê não. "É opcional" deixou de ser uma razão válida para um projeto com usuários.

Passo 10 — Os casos de teste manual se escrevem junto com a funcionalidade, e quem os executa são pessoas (contrato do degrau)

Fase: ciclo. Quando: com cada pendência, ao fechá-la, depois do teste em vermelho (8) e da qualidade (9): o agente escreve os casos de teste manual do fluxo que tocou. Executam-se por pessoas em três momentos: no fechamento de cada bloco (os testes humanos), antes da primeira implantação em produção (os testes de aceitação com o dono), e depois de cada implantação, numa passada de somente leitura. Cada execução que falha reinjeta um requisito no ciclo como pendência corretiva. Forma: rotina de cada pendência; depois, execução humana por ciclo. Tamanho: obrigatório em todo projeto com usuários: o caso de teste manual é o único teste que o modelo não escreve nem roda.

Para que serve

O método tem provas automáticas de sobra: o teste em vermelho, a regressão, a ponta a ponta em três escalas. Todas as escreve e as roda o modelo, e todas provam o que o modelo entendeu. Falta a prova que faz uma pessoa com os próprios olhos e as próprias mãos, seguindo um roteiro escrito, e que encontra o que nenhum teste encontra: o botão que está onde não deve, a mensagem que não se entende, o fluxo que tecnicamente anda e humanamente não serve. A vista humana e os testes humanos já estavam na linha do tempo; o que faltava era que tivessem roteiro, e que o roteiro fosse escrito por quem construiu a funcionalidade, no mesmo momento, a partir dos critérios de aceitação da pendência. Sem roteiro, o teste humano é "brinque um pouco com o sistema", e o que se encontra depende do humor do dia. Com roteiro, executa-se igual a cada vez, registra-se o que aconteceu, e o que falha volta ao ciclo como requisito. É o fechamento do circuito que o gráfico do processo mostra: a execução manual dos casos de teste reinjeta requisitos no desenvolvimento.

Um caso de teste manual tem sempre a mesma forma: um identificador; a pendência que o origina; a precondição (o que tem que existir antes: um paciente, uma consulta de ontem); os passos, numerados, cada um com o que a pessoa faz e o que tem que ver; o resultado esperado no final, incluído o efeito no backend que uma pessoa pode verificar (um registro que aparece, uma mensagem na caixa falsa); os dados de teste a usar; e o espaço para o resultado de cada execução: data, quem, passou ou falhou, observação.

Se você está começando. Um caso de teste manual é uma receita para que uma pessoa prove uma funcionalidade: o que preparar, o que fazer passo a passo, e o que tem que acontecer em cada passo. Escreve-se para que qualquer um a siga igual, sem saber como o sistema está feito. Executar um caso é seguir a receita e anotar se passou ou falhou. Precondição é o que tem que existir antes de começar. E reinjetar quer dizer que o que a pessoa encontrou de errado volta à lista de pendências como um pedido novo, com as palavras dela.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com o seu conteúdo e o seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

• A pendência que se está fechando, com os seus critérios de aceitação "dado, quando, então" (degrau 5): são a matéria-prima do caso.
• O ambiente de teste com dados, para que os passos se possam seguir de verdade.
• Quem vai executar os casos (o dono, um usuário de confiança) e quando (fechamento de bloco, aceitação, depois de cada implantação).

2. Prompts

Rotina de cada pendência (vai no contrato de convivência):

O que estou pedindo: que o caso saia dos critérios de aceitação (assim prova o que se pediu, não o que o modelo entendeu); que esteja escrito para alguém que não sabe como o sistema funciona, que é a diferença entre um caso de teste e uma nota técnica; que inclua o efeito no backend verificável por uma pessoa, para que o teste manual também olhe do outro lado da tela; que os casos se mantenham no mesmo commit, igual que a documentação; e que o modelo nunca os execute, porque executados pelo modelo são mais um teste, e a graça é que os execute uma pessoa.

Para uma execução (fechamento de bloco, aceitação, depois de uma implantação):

O que estou pedindo: a reinjeção feita operativa: cada falha humana é uma pendência corretiva, com as palavras da pessoa (não as do modelo) como reprodução, e pendurada na árvore; a comparação com a execução anterior, que é o que diz a você se o sistema melhora ou se degrada entre blocos; e a distinção entre "o caso está mal escrito" e "o sistema está mal", que são duas pendências diferentes.

3. Resultado esperado

• docs/MANUAL_TESTS.md com um caso por fluxo tocado por cada pendência fechada, no formato, escrito para uma pessoa.
• As execuções registradas, com data e quem, em cada ciclo.
• Uma pendência corretiva por cada falha e por cada observação.
• A rotina no contrato.

4. Verificação de completude (você a faz, sem ler código)

• Pegue um caso ao acaso e siga-o você mesmo no ambiente de teste sem perguntar nada ao agente: conseguiu? Se teve que perguntar, o caso não está escrito para uma pessoa.
• Cada pendência fechada que toca uma tela tem o seu caso? Peça a lista de pendências sem caso.
• O caso diz que efeito verificar do outro lado da tela, e como uma pessoa o verifica?
• A última execução tem data e nome em cada caso? Há algum "passou" sem data?
• Cada falha da última execução tem a sua pendência, com as palavras da pessoa?

5. Sinais de alerta

• O agente marcou os casos como executados. Executou-os ele, que é o mesmo que não executá-los.
• Os casos são cópias do teste automático em prosa. Um caso manual tem que olhar o que o teste não olha: o que se vê, o que se entende, o que incomoda.
• Todos os casos passam em todas as execuções. As pessoas encontram coisas sempre; se não encontram nada, não estão seguindo o roteiro ou o roteiro não pede que se olhe.
• As falhas se "consertam" na hora, sem pendência. Perdem-se as palavras da pessoa e o rastro do que se repetiu.

Passo 11 — Simetria entre produtor e consumidor, e o registro de antipadrões (contrato do degrau)

Fase: ciclo. Quando: com cada pendência que toca um contrato entre duas partes do sistema. O mapa de contratos se constrói ao abrir o segundo bloco funcional, quando já há tela e servidor. O registro de antipadrões cresce cada vez que algo quebra pela segunda vez. Forma: automática dentro do ciclo; mais um arquivo que cresce com cada tropeço. Tamanho: a simetria é obrigatória sempre; o mapa produtor/consumidor é opcional num projeto de um único módulo, e obrigatório assim que há uma tela e um servidor separados.

Para que serve

Quando você muda uma ponta (o servidor, o robô, o esquema do banco), faça com que a outra ponta (a tela, o contador, o consumidor) mude no mesmo commit. Se não, cedo ou tarde divergem, e o usuário vê um número de um lado e outro número do outro Ref. 26. E os erros que você já pagou uma vez, anote-os para não pagá-los duas vezes Ref. 2.

O princípio geral por trás, que impus no Plano de Saúde e que vale para todo sistema Ref. 27: toda lista tem um único dono. As colunas de uma tabela, os estados possíveis de uma ordem, as causas pelas quais algo espera: define-as uma única parte do sistema (o produtor) e todas as demais as leem dali. Assim que há duas cópias da mesma lista, uma está desatualizada; só falta saber qual. A árvore semântica do degrau 2 é o primeiro lugar onde essas listas se declaram: os estados de uma entidade estão ali, e o código tem que lê-los de uma única fonte.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com seu conteúdo e seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

• Um mapa de que partes do sistema consomem o quê: que telas leem que serviços, que processos escrevem que tabelas. Se não existe, o primeiro prompt o constrói.
• O registro de antipadrões docs/GOTCHAS.md, mesmo que vazio.

2. Prompts

Para construir o mapa (uma vez):

O que estou pedindo: o inventário de contratos com seus dois lados, e a cláusula de completude na sua forma para este degrau: o que não se vê se declara, não se omite. Um mapa com buracos escondidos é pior do que nenhum mapa.

Rotina (vai no contrato de convivência):

O que estou pedindo: a simetria como reflexo (procurar o outro lado antes de fechar), a regra da lista com um único dono, e que o mapa se mantenha sozinho à medida que se usa.

Quando algo quebra pela segunda vez:

O que estou pedindo: o formato fixo de um antipadrão (cheiro, causa raiz, correção, detecção precoce) e, sobretudo, a verificação automática: um antipadrão anotado e não automatizado vai se repetir quando mudar a pessoa ou a sessão.

3. Resultado esperado

• docs/PRODUCER_CONSUMER_MAP.md: a lista de contratos com produtor e consumidores.
• Em cada commit que toca um contrato: os consumidores atualizados, nomeados na mensagem.
• docs/GOTCHAS.md: uma entrada por antipadrão, com as quatro partes (cheiro, causa raiz, correção, como detectá-lo antes), e a data da primeira vez.

4. Verificação de completude

• Escolha um contrato do mapa e peça ao agente que lhe mostre onde cada consumidor o lê. Se algum tem sua própria cópia da lista, há dívida.
• Há um número que se mostra em duas telas diferentes? Compare: dão o mesmo?
• Cada entrada de GOTCHAS tem as quatro partes?
• Repetiu-se um erro que já estava em GOTCHAS? Se sim, falta a verificação automática.

5. Sinais de alerta

• O mesmo valor aparece escrito à mão em mais de um arquivo ("PENDENTE", "APROVADA" no servidor e na tela). Duas cópias; uma vai divergir.
• Uma mudança no servidor foi fechada com o teste do servidor em verde e ninguém tocou na tela.
• GOTCHAS tem entradas sem a parte "como detectá-lo antes". São anedotas, não antipadrões.

Passo 12 — Verificação honesta e relatório proporcional (contrato do degrau)

Fase: ciclo. Quando: em cada relatório, de cada pendência, durante todo o projeto. É a forma que tem que ter tudo o que o agente lhe diz. Forma: rotina; é a forma que cada relatório do agente deve ter. Tamanho: obrigatório em todo projeto, sem exceções. Não custa nada e é o que permite ao dono não ler código.

Para que serve

Se você não vai ler código, o relatório do agente tem que ser confiável. Não otimista, não "completo na aparência": confiável. Isto é o genuinamente novo do método: o autor do código fabrica também a evidência, e faz isso com a mesma segurança na voz quando está certo e quando está errado. Por isso a evidência tem que provar a si mesma, e o relatório tem que separar o verificado do acreditado. A regra, eu a escrevi em junho Ref. 8, e voltei a precisar dela em outubro, quando um erro de autenticação foi relatado com a legenda "success" Ref. 43.

Entenda por que o modelo tende a relatar de mais. Não é má-fé: é que foi treinado para ser útil e completo, e um relatório que diz "isto não consegui verificar" parece menos útil do que um que diz "pronto". Então peça explicitamente as más notícias, os pontos cegos e o que ele não fez. Se você não pede, ele não dá, não porque esconda mas porque não considera isso parte da resposta.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com seu conteúdo e seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

• O trabalho feito e a pendência que o pedia.
• O contrato de convivência (degrau 1), que já proíbe anunciar o não feito.

2. Prompts

Rotina (vai no contrato de convivência; aplica-se em cada relatório):

O que estou pedindo, cláusula por cláusula: os três blocos, que são a estrutura que torna honesto um relatório (o verificado com sua prova, o acreditado com a razão de por que não foi testado, o que ele não consegue ver); a cobertura item por item, para que nada "seja esquecido"; a prova ao lado de cada afirmação; a proibição do "pronto" seco; e as más notícias primeiro, porque o modelo tende a deixá-las para o final ou para nunca.

Diante de um "continua quebrado" seu:

O que estou pedindo: que diante de um "continua quebrado" ele não volte a diagnosticar do zero mas primeiro compare versões. Metade dos "continua quebrado" são correções que estão no repositório mas não no lugar onde você olha Ref. 45.

3. Resultado esperado

Cada relatório do agente com:

• Os três blocos (verificado / acreditado / pontos cegos), mesmo que algum esteja vazio.
• Uma linha por cada item pedido, com seu estado.
• Para cada "verificado": o comando e a saída, ou o teste e seu resultado, ou o número e seu medidor.
• O que deu errado, no começo e não no final.

4. Verificação de completude

• Estão os três blocos? Se "acreditado" e "pontos cegos" estão sempre vazios, o agente não está sendo honesto: sempre há algo que ele não viu.
• Escolha ao acaso uma afirmação do bloco "verificado": tem sua prova ao lado? Você consegue reproduzi-la?
• Cobre cada item do que você pediu, ou há um que "foi esquecido"?
• As más notícias estão no começo?
• Disse "pronto" seco alguma vez? É uma violação do contrato.

5. Sinais de alerta

• Dez relatórios seguidos sem nenhum ponto cego. Ninguém vê tudo; o bloco está vazio por costume, não por verdade.
• O bloco "verificado" tem frases como "deveria funcionar". É "acreditado" disfarçado.
• O relatório é mais longo do que a mudança. Um relatório proporcional diz o que há que dizer; um inflado está tapando algo com volume.

Passo 13 — A auditoria periódica como insumo do plano (contrato do degrau)

Fase: saída para produção. Quando: obrigatória antes da primeira implantação em produção; abre a fase de saída. Depois, em operação, a cada um ou dois meses segundo o ritmo de mudança, e no fechamento de cada etapa grande. Forma: um disparo longo, idealmente a um agente diferente do que constrói. Tamanho: obrigatório antes da primeira implantação em produção, em qualquer projeto; depois, proporcional ao ritmo de mudança (um sistema que muda todas as semanas se audita a cada mês; um estável, a cada seis).

Para que serve

Olhe o sistema inteiro com olhos frescos de vez em quando, e converta o que vir em pendências. A auditoria não é um relatório que se arquiva: é plano. Evita a senha escrita no código que ninguém tinha visto, as consultas que leem tabelas inteiras Ref. 18, a vulnerabilidade conhecida numa dependência, o componente de milhares de linhas Ref. 41. E é a independência do controle de qualidade levada um passo mais para dentro: quem audita não é quem construiu.

Sobre a independência: não precisa de outra empresa nem de outra ferramenta. Basta outra sessão, com outro arquivo de instruções, que não tenha participado da construção. O que você busca é que o auditor não compartilhe os pressupostos do construtor. Um modelo que construiu um módulo "sabe" que a senha hardcoded era provisória; um modelo que o vê pela primeira vez a relata como o que é. Assim se detectaram duas portas de administrador que o construtor tinha deixado num dia Ref. 40.

Se puder escolher, que seja também um modelo diferente do que construiu, não só outra sessão do mesmo: um estudo de 2026 mediu que uma sessão limpa com um modelo diferente encontra mais erros que duas sessões do mesmo modelo (arXiv 2610.01471). Não é uma comporta dura, porque às vezes o modelo do construtor é o único disponível; é uma preferência que vale a pena exercer quando se pode, e quanto mais crítico o sistema, mais vale exercê-la.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com seu conteúdo e seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

• O repositório completo, em somente leitura.
• A produção ou o ambiente de teste, em somente leitura (banco de dados, logs).
• A auditoria anterior, se houve, para medir o que mudou.
• O escopo: integridade, segurança, desempenho, qualidade de código, ou tudo.
• docs/PENDING.md com as pendências fechadas no último ciclo e seus recibos, para que o auditor escolha quais reproduzir.

2. Prompts

Inicial (a um agente diferente do construtor, se possível):

O que estou pedindo, cláusula por cláusula: somente leitura (o auditor não corrige; propõe); a cláusula de completude na sua forma para auditar: o que não se pôde verificar se declara, não se aprova por omissão; todo o código e não uma amostra, porque os achados graves costumam estar onde ninguém olha; a reprodução literal de duas ou três recibos, para que a auditoria verifique evidência em vez de só a ler (esta é a cláusula que fecha o buraco de D-033: um vermelho contado não é um vermelho auditado); cada achado com localização, risco, evidência e prioridade, para que seja acionável sem reler o relatório; notas por dimensão, para comparar com a auditoria anterior; e os P0 já convertidos em pendências propostas.

De fechamento (ao construtor):

O que estou pedindo: que a auditoria se converta em pendências (se não, é um relatório que se arquiva), e que a discordância seja explícita e com evidência, não silenciosa.

3. Resultado esperado

• docs/AUDIT_[data].md com: escopo, o que se pôde verificar e o que não (e por quê), os achados com localização, risco, evidência e prioridade, uma nota por dimensão, o resultado de reproduzir duas ou três recibos do último ciclo, e a lista de pendências propostas.
• Em docs/PENDING.md: uma pendência para cada P0 e P1, citando o achado.

4. Verificação de completude

• O relatório diz o que NÃO pôde verificar? Se diz que verificou tudo, desconfie.
• Escolha dois achados: têm arquivo e linha, e uma evidência que você consegue reproduzir?
• O relatório diz quais recibos reproduziu, com o comando e o resultado, ou só diz que os leu?
• Cada P0 tem sua pendência aberta antes de dar a auditoria por fechada?
• As notas por dimensão vão poder ser comparadas com a auditoria anterior?
• Auditou o mesmo agente que construiu? Se sim, peça um segundo olhar sobre os P0.

5. Sinais de alerta

• A auditoria não encontrou nenhum P0. Num sistema de mais de três meses, quase nunca é verdade; mais provável é que o escopo tenha sido pequeno ou que o auditor compartilhasse os pressupostos.
• Os achados não têm linha de arquivo. São opiniões, não achados.
• O relatório diz que os recibos "foram revisados" sem mostrar o comando que rodou nem a sua saída. Um recibo lido e um reproduzido não são a mesma coisa, e só o segundo fecha a objeção de D-033.
• Passaram-se duas semanas e os P0 continuam sem pendência. A auditoria foi arquivada.

Passo 14 — Fail-closed, cadeados e zero dano silencioso (contrato do degrau)

Fase: saída para produção. Quando: na fase de saída para produção, ANTES de construir qualquer funcionalidade que cobre, envie, aprove ou apague; revisa-se com cada ação nova com consequências. As automações novas começam em modo de ensaio e se habilitam depois de olhar seu registro por uns dias. Forma: conversa: o agente lista as ações com consequência, você confirma quais levam cadeado e de que tipo. Tamanho: obrigatório assim que o sistema faz algo irreversível (cobrar, enviar, apagar, aprovar). Um sistema de somente leitura pode pulá-lo; no momento em que ganha seu primeiro botão que age sobre o mundo, este degrau passa a ser o mais importante.

Para que serve

Faça com que o sistema, diante de uma dúvida ou de uma falha, NÃO aja, e que o diga. Soa óbvio e é o contrário do que o software faz por padrão, que diante da dúvida segue em frente. Evita a dupla cobrança, a aprovação automática sem passar por um humano, o git add -A que sobe uma credencial, e o apagamento de dados do cliente. Os cadeados que coloquei no Plano de Saúde são o modelo: o botão de pânico com dupla trava, o aprovador automático em modo de ensaio, o vigia com guardas Ref. 28; e o reflexo de que uma falha deixe uma linha sem seu botão em vez de quebrar a listagem inteira Ref. 25.

O princípio tem nome, "fail-closed", e vem da segurança física: uma porta de segurança que fica fechada quando a luz acaba. O contrário, "fail-open", é a porta que se abre. Em software a maioria das coisas é fail-open por padrão: se a validação falha, o código segue; se o serviço não responde, assume-se que está tudo bem. O método inverte o padrão: na dúvida, não. E se aplica tanto ao sistema quanto ao agente que o opera.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com seu conteúdo e seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

• Levantamento de ações com consequência, nomeado assim de forma genérica: o que o sistema faz que cobra, envia, aprova, apaga, ou avisa alguém de fora; o que acontece se for feito duas vezes; o que acontece se for feito errado; como se desfaz. O negócio sabe; o agente avalia se a lista está completa e pergunta. A árvore semântica ajuda: cada processo com consequência está ali.
• Que ações o próprio agente pode fazer sobre o sistema (se está embarcado).

2. Prompts

Inicial:

O que estou pedindo: o cruzamento entre o que o negócio disse e o que o código faz (aí aparecem as ações de que ninguém se lembrava); a cláusula de completude na sua forma para este degrau: as diferenças entre as duas listas se perguntam, não se resolvem; para cada ação, reversibilidade, cadeado e caminho de volta; e a regra geral do fail-closed escrita no prompt, para que fique na tabela e no código.

De fechamento:

O que estou pedindo: o teste por cadeado provado em vermelho (sem o cadeado, a ação ocorria; com o cadeado, não), que é o degrau 8 aplicado à segurança; a tabela final; e a regra do modo de ensaio para toda automação nova, que é o que permite ver o que teria feito antes de deixá-la fazer.

3. Resultado esperado

• docs/LOCKS.md: uma linha por ação com consequência: o que faz, se é reversível, o cadeado, o caminho de volta, quem o aprovou e quando.
• Um teste por cadeado, provado em vermelho, que verifica que na dúvida a ação não ocorre.
• As automações novas começando em modo de ensaio, com o registro de "teria feito".
• Se o agente está embarcado: suas permissões escritas (o que pode ler, o que pode mudar, o que exige aprovação).

4. Verificação de completude

• Cada ação que cobra, envia, aprova ou apaga está na tabela? Pense numa que não esteja e pergunte.
• Cada cadeado tem seu teste em vermelho? ("Sem o cadeado, a ação ocorria; com o cadeado, não.")
• Toda ação irreversível tem caminho de volta escrito? Se não tem, precisa de dupla trava.
• As automações novas começaram em modo de ensaio? Você viu o registro de "teria feito" antes de habilitá-las?
• O que acontece se o agente embarcado tenta algo fora de suas permissões? Peça que ele tente e lhe mostre a recusa no log.

5. Sinais de alerta

• Uma automação passou de "não existe" a "roda sozinha" sem um período de modo de ensaio.
• O log não tem nenhuma entrada de "ação não executada por dúvida". Ou o sistema nunca duvida (impossível) ou quando duvida segue em frente.
• Um cadeado pode ser pulado com um parâmetro "para testes". Esse parâmetro vai ficar ligado em produção.

Passo 15 — Integração contínua, ambientes, segredos e implantação como parte do produto (contrato do degrau)

Fase: saída para produção. Quando: a cadeia de integração e a implantação no ambiente de teste se montam no degrau 4. O fechamento rumo à produção — ambiente real, segredos no servidor, promoção, caminho de volta provado, cadeado contra segredos — se faz na fase de saída, depois da auditoria e dos cadeados. A rotina de cada implantação se aplica em toda a operação. Forma: um disparo para montá-lo; rotina para cada implantação. Tamanho: obrigatório em todo projeto com usuários. Num pequeno, "integração contínua" pode ser uma única action do GitHub e "ambientes" podem ser duas pastas no mesmo servidor; o que não se negocia é que os testes rodem sozinhos, que a configuração não esteja no repositório, e que haja caminho de volta.

Para que serve

Faça com que chegar à produção seja um pacote reproduzível: os testes rodam UMA vez, a configuração vive fora do repositório, e os segredos não ficam circulando. Evita os testes rodados três vezes por commit e a cota queimada Ref. 39, a implantação endurecida a golpes de pendências por tê-la descoberto tarde Ref. 32, e os segredos colados no chat Ref. 42.

Sobre os segredos há uma regra que você deve adotar como reflexo, sem exceções: um segredo que foi visto num chat, num log ou num commit já não é um segredo. Não importa se "ninguém viu" ou se "foi apagado depois". Rotaciona-se. A rotação custa dez minutos; descobrir se alguém o usou é impossível.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com seu conteúdo e seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

• Levantamento de ambientes e acessos, de forma genérica: que ambientes há (teste, produção), onde rodam, quem tem acesso, como se promove algo de um para outro, que segredos existem e onde vivem hoje, quanta cota de integração contínua há. O agente avalia se basta e pergunta.
• O esqueleto com sua integração contínua e sua implantação em teste (degrau 4).

2. Prompts

Inicial:

O que estou pedindo, cláusula por cláusula: os acessos antes de começar; os testes uma única vez por commit (rodá-los três vezes é o que queimou a cota); a implantação que só empacota; a configuração fora do repositório; a promoção como procedimento repetível; o caminho de volta provado, com o seu plano de dados (um caminho de volta que nunca foi provado não existe, e uma migração de esquema ou de dados não se desfaz revertendo o commit); o cadeado contra segredos nos commits; e a documentação para uma pessoa, que é o degrau 20 aplicado à infraestrutura.

Rotina de cada implantação:

O que estou pedindo: as três condições prévias (teste em verde com a mesma versão, caminho de volta pronto, mudanças de configuração anunciadas) e as duas provas posteriores (a versão rodando e uma verificação de ponta a ponta sem escrever nada).

Se um segredo apareceu no chat ou num commit:

O que estou pedindo: rotação imediata, inventário de onde mais estava, e a verificação que o teria detectado, para que da próxima vez não chegue ao chat.

3. Resultado esperado

• A integração contínua rodando uma única vez por commit, com o link para uma execução.
• A implantação que espera a integração e só empacota; medido: quanto demora antes e depois.
• A configuração fora do repositório; no repo, só um exemplo sem valores.
• docs/DEPLOYMENT.md: como implantar, promover e voltar atrás, passo a passo, para uma pessoa.
• O caminho de volta provado pelo menos uma vez, com sua evidência.
• A verificação antissegredos ativa (uma tentativa de subir um, recusada).
• Um registro da cota de integração contínua consumida por mês.

4. Verificação de completude

• Quantas vezes roda a bateria por cada commit? Tem que ser uma. Peça o link.
• Há algum valor real de configuração (uma chave, uma senha, uma URL interna) no repositório? Peça ao agente que busque e lhe mostre a busca vazia.
• Você conseguiria seguir docs/DEPLOYMENT.md sozinho, sem o agente? Leia-o com essa pergunta.
• O caminho de volta foi provado? Quando? Que evidência há?
• Se houve uma migração de esquema ou de dados: há um plano escrito para desfazê-la ou compensá-la, além do caminho de volta do código?
• Algum segredo foi colado no chat durante o projeto? Se sim, foi rotacionado?
• Você sabe quanta cota de integração contínua resta este mês?

5. Sinais de alerta

• A implantação em produção se faz "à mão, rápido, porque é uma mudança pequena". As mudanças pequenas são as que quebram a produção, porque ninguém as testa.
• O arquivo de exemplo da configuração tem valores que parecem reais. Provavelmente são.
• Ninguém sabe dizer quando foi a última vez que o caminho de volta foi provado.
• Uma migração mudou dados ou esquema e "o caminho de volta" do qual se fala é só o do código. Para essa migração não há caminho de volta: há, na melhor das hipóteses, um plano para compensá-la.

Passo 16 — Observabilidade e rastreabilidade totais, com nível configurável (contrato do degrau)

Fase: saída para produção. Quando: na fase de saída para produção, depois do 15 (já há cadeia de implantação e configuração por ambiente) e antes dos testes de desempenho (19), porque sem observabilidade os testes de desempenho não dizem o que quebrou. Num legado, o nível mínimo (registros estruturados com nível configurável e um identificador de correlação) entra no cinto de segurança (N4); o nível completo, aqui. A regra de "todo módulo novo registra e propaga" vale durante toda a operação. Forma: um único disparo; o agente monta e demonstra; você lê um rastro real. Tamanho: obrigatório no seu nível mínimo em todo projeto que vá ter usuários; completo em qualquer projeto com consequências.

Para que serve

Quando algo falhar em produção, e vai falhar, quero poder seguir uma ação desde a tela até o banco de dados e até cada chamada externa, com um único identificador, sem abrir o código e sem pedir ao agente que "revise". E quero poder subir o nível de detalhe dos registros em produção, em um minuto, sem voltar a implantar, e baixá-lo depois. Isso é observabilidade: ver o que o sistema faz. E a segunda coisa é rastreabilidade: que toda ação com consequência (cobrou, enviou, apagou, aprovou) deixe um rastro de quem, quando, o quê, de onde e com que resultado, num registro que a aplicação não pode editar. Sem isto, o agente residente do degrau 23 opera às cegas, o monitoramento dos degraus 21 e 22 não tem do que se alimentar, e cada incidente se diagnostica com hipóteses em vez de com evidência. O turno órfão que continuou vivo uma hora e quarenta e três se encontrou pelo log, não pelo código Ref. 16; e o agente residente arrancou, justamente, lendo logs Ref. 13.

"Nível configurável" é a cláusula que distingue isto de "pôr logs": o nível (erro, aviso, informação, depuração, rastreamento) se muda por configuração no servidor, por ambiente, sem tocar código nem implantar, e produção roda em informação salvo quando se está investigando alguma coisa.

Se você está começando. Um registro (log) é uma linha que o sistema escreve cada vez que faz alguma coisa: "10:42:13, módulo agenda, usuário recepcao1, turno 17 cancelado". Estruturado quer dizer que todas as linhas têm as mesmas partes na mesma ordem, para que se possam buscar por máquina. O nível é quanto detalhe se escreve: em "erro", só o que falhou; em "rastreamento", cada passo. O identificador de correlação é um número único que se dá a cada ação quando ela começa (você apertou "cancelar") e que viaja colado a tudo o que essa ação provoca (a consulta ao banco, a mensagem ao paciente), de modo que depois se busca esse número e aparece a história completa. E a auditoria é uma lista que não se pode editar das ações importantes: quem fez o quê e quando.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com seu conteúdo e seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

• A cadeia de implantação e a configuração por ambiente (degrau 15): o nível se configura ali.
• A tabela de cadeados (degrau 14): cada ação com consequência é uma entrada da auditoria.
• O levantamento inicial com os dados pessoais marcados: os registros não podem contê-los.
• Onde vão viver os registros e as métricas (um arquivo rotacionado, um serviço): você decide.

2. Prompts

Inicial:

O que estou pedindo: as cinco peças, e duas demonstrações que são a evidência do degrau: um identificador real seguido por todas as camadas (se não consegue mostrá-lo, a propagação está quebrada em algum lugar) e o nível mudando sem implantar (se é preciso implantar, não é configurável). A auditoria de ações com consequência tem que ser imutável a partir da aplicação, porque um rastro que a aplicação pode apagar não é um rastro. E o mascaramento de dados pessoais vai no mesmo prompt porque os registros são o lugar onde mais dados pessoais vazam sem que ninguém o decida.

Rotina (vai no contrato de convivência):

O que estou pedindo: que a observabilidade não se degrade com cada módulo novo, que é o que acontece sempre se não for regra: o módulo do mês três não registra nada e é justamente o que falha.

3. Resultado esperado

• Registros estruturados com nível configurável por ambiente, mudados sem implantar.
• Um identificador de correlação em cada registro, propagado da tela ao banco e às chamadas externas.
• Um registro de auditoria imutável das ações com consequência.
• Pontos ou arquivos de saúde e métricas, documentados.
• Nenhum dado pessoal nos registros.
• docs/OBSERVABILITY.md e a rotina no contrato.

4. Verificação de completude (você a faz, sem ler código)

• Peça-lhe um identificador de um pedido real e procure-o você nos registros: aparece na tela, no backend, no banco e na chamada externa, se houve?
• Suba o nível para depuração no ambiente de teste, faça uma ação, olhe os registros, baixe-o. Você teve que implantar? Então não está subido.
• Procure um nome ou um telefone de teste nos registros: não pode estar.
• Faça uma ação com consequência em teste (cancelar, enviar para a caixa falsa): ficou na auditoria com quem, quando, o quê e resultado?
• docs/OBSERVABILITY.md basta para você encontrar um registro sozinho às três da manhã?

5. Sinais de alerta

• O agente mostra "logs" mas cada módulo escreve num formato diferente. Não é estruturado; ninguém vai conseguir buscá-los.
• O identificador aparece no backend mas não nas chamadas externas ou nas tarefas programadas. São justamente os lugares onde os incidentes se perdem.
• O nível de produção ficou em depuração "por enquanto". Enche-se o disco e vazam dados.
• A auditoria de ações com consequência vive na mesma tabela que o resto dos dados e a aplicação pode apagá-la.

Passo 17 — Otimização da camada de persistência, medida antes e depois (contrato do degrau)

Fase: saída para produção. Quando: na fase de saída para produção, depois do 16 (é preciso ver as consultas para medi-las) e antes do 19 (os testes de desempenho se rodam sobre a persistência já otimizada; se não, medem o problema que já se conhecia). Repete-se quando um bloco acrescenta uma tabela grande ou muda um fluxo crítico, e quando o monitoramento (21) mostra uma consulta fora de faixa. Num legado, as medições saem de N6 e a maior parte do que se encontra se paga "ao tocar", salvo o que já está fora de faixa. Forma: dois disparos: medir e propor; aplicar com antes e depois. Tamanho: proporcional: num projeto pequeno, os índices das consultas reais e o fim dos laços N+1; num com consequências, completo, com orçamentos por caminho.

Para que serve

A camada de persistência é onde os sistemas morrem devagar: funcionam bem com cem registros, aceitavelmente com dez mil, e aos cem mil cada tela demora vinte segundos, e ninguém sabe quando começou. Este degrau existe para que isso se decida com números e antes da produção, não com reclamações e depois. E para que se decida com o método do degrau 7: cada consulta que o sistema faz se conta e se cronometra com um medidor que tem teste, muda-se o que os números dizem, e mede-se de novo sobre os mesmos dados. A primeira auditoria de consultas sem índice sobre um sistema vivo Ref. 18 e o orçamento de consultas apertado ao medido Ref. 37 são a origem deste degrau; a decisão da interface assíncrona desde a linha um Ref. 15, o seu antecedente no arranque.

O que não é: não é "reescrever o acesso a dados", nem escolher outro motor. Isso foi decidido pelo degrau 3. É ajustar o que há (índices, paginação, lotes, retenção, tamanho do pool) a partir do que as consultas reais fazem.

Se você está começando. A camada de persistência é a parte do sistema que guarda e lê os dados, quase sempre um banco de dados. Um índice é como o índice de um livro: sem ele, para encontrar um turno o banco lê a tabela inteira (isso é um full scan); com ele, vai direto. Um laço N+1 é um erro muito comum: para mostrar cem turnos, o sistema faz uma consulta para a lista e depois mais cem consultas, uma por turno, em vez de uma só. Paginação é mostrar de vinte em vinte em vez de tudo junto. Retenção é quanto tempo se guarda cada dado antes de arquivá-lo ou apagá-lo. E o pool de conexões é a quantidade de "linhas abertas" que o sistema mantém com o banco ao mesmo tempo. Nada disto exige que você leia código: exige que você olhe números antes e depois.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com seu conteúdo e seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

• O dimensionamento e a volumetria (degrau 3, ou N6 num legado): os volumes aos quais é preciso medir.
• O mapa produtor-consumidor (degrau 11): o que consome cada tabela.
• A observabilidade (16): cada consulta visível com o seu tempo.
• O ambiente de teste carregado com dados ao volume esperado.

2. Prompts

Inicial (medir e propor):

O que estou pedindo: medir com o método do degrau 7 (medidor com teste, auditado nas duas direções, número com comando) antes de propor; propor consulta por consulta, com o ganho e o risco, e com os consumidores do mapa que cada mudança toca (um índice novo não toca ninguém; uma retenção por tabela toca todos os que leem essa tabela); e não mudar nada até que eu aprove, porque a otimização é o lugar onde mais se "melhora" o que ninguém pediu.

De fechamento (aplicar com antes e depois):

O que estou pedindo: um commit por mudança, para que o antes e o depois sejam atribuíveis; o mesmo medidor sobre os mesmos dados (se os dados mudam, o número não diz nada); o orçamento com teste, que é o que impede que o laço N+1 volte em três meses; e a simetria do degrau 11 aplicada à persistência.

3. Resultado esperado

• Os medidores de consultas no repositório, com teste.
• docs/PERSISTENCE.md com a tabela de antes e depois por mudança, os orçamentos por caminho e a retenção por tabela.
• Os índices, a paginação, os lotes e a retenção aplicados, um commit cada um, com a regressão e a ponta a ponta em verde.
• Um teste por orçamento que falha se for ultrapassado.

4. Verificação de completude

• Rode você um medidor antes e depois (o agente lhe dá os dois comandos): coincidem com a tabela?
• Há alguma consulta que leia uma tabela inteira num fluxo crítico? Por que ficou?
• Cada tabela tem uma política de retenção escrita, ainda que seja "para sempre"?
• Os orçamentos têm teste? Peça-lhe que ultrapasse um de propósito e lhe mostre o vermelho.
• A tela mais lenta, com os dados ao volume, demora o que o dimensionamento esperava?

5. Sinais de alerta

• As medições foram feitas com os dados de exemplo do esqueleto. Tudo é rápido com dez linhas.
• O agente propõe "migrar para outro banco" ou "reescrever a camada de dados". Isso é o degrau 3, e se for preciso voltar a ele é uma decisão sua, não uma otimização.
• Melhorou o número mas a ponta a ponta de um fluxo deixou de passar. Um índice não quebra um fluxo; uma retenção ou uma paginação sim: faltou um consumidor do mapa.
• Não há orçamentos. Sem orçamento, a otimização dura até o próximo bloco.

Passo 18 — Varredura e solução de vulnerabilidades, na cadeia e com calendário (contrato do degrau)

Fase: saída para produção. Quando: na fase de saída para produção, depois do 15 (a varredura roda na integração contínua) e antes da primeira implantação: nenhum P0 aberto se promove. Depois, em cada push, e com um calendário próprio (semanal) ainda que não haja pushes, porque as vulnerabilidades novas aparecem sem que você mude nada. Num legado, a primeira rodada é parte de N3 (a dimensão de segurança da auditoria) e os achados entram no backlog com a sua marca de velocidade. Forma: um único disparo para montar e rodar; depois, automático, com um relatório que você lê. Tamanho: obrigatório em todo projeto que vá ter usuários: a varredura de dependências e de segredos não se negocia; a análise estática e a linha base de configuração, proporcionais.

Para que serve

A auditoria do degrau 13 olha o sistema com olhos frescos de vez em quando; este degrau olha uma só coisa, a segurança, o tempo todo e por máquina. São complementares: a auditoria encontra o que exige critério (uma porta de administrador que ninguém deveria ter Ref. 40); a varredura encontra o que exige constância (a dependência que ontem não tinha uma vulnerabilidade conhecida e hoje tem Ref. 41). A primeira auditoria de segurança formal me convenceu de que a segurança é uma rotina periódica e não uma lista que se marca uma vez Ref. 23; este degrau é essa rotina feita máquina.

E uma regra que quero escrita: uma atualização de dependência é uma mudança, e entra pelo ciclo como qualquer outra. "Subi a versão para fechar a vulnerabilidade" sem regressão nem ponta a ponta é a forma mais comum de quebrar a produção numa sexta-feira.

Se você está começando. Uma vulnerabilidade é um defeito que alguém pode usar para entrar, roubar dados ou fazer com que o sistema faça algo que não deveria. Há quatro tipos que este degrau busca por máquina. Nas dependências: as peças de software de terceiros que o seu sistema usa (há bases públicas que listam quais têm defeitos conhecidos, identificados com um número CVE). No código: a análise estática lê o código sem executá-lo buscando padrões perigosos, como uma injeção (que um usuário escreva num formulário algo que o banco interprete como uma ordem). No histórico: um segredo (uma senha, uma chave) que alguma vez foi guardado no repositório continua lá mesmo que depois tenha sido apagado. E na configuração: portas abertas que não eram necessárias, senhas padrão, cabeçalhos de segurança (instruções que o servidor manda ao navegador para protegê-lo) que faltam.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com seu conteúdo e seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

• A integração contínua (degrau 4 e 15), onde roda a varredura.
• O levantamento de ambientes: que servidor, que contêiner, que portas, para a linha base de configuração.
• A auditoria anterior (11, ou N3), para não reportar o que já é conhecido.
• O seu critério sobre o que é P0: o que permite entrar, o que expõe dados pessoais, o que permite cobrar ou enviar sem controle.

2. Prompts

Inicial (montar, rodar, propor):

O que estou pedindo: as quatro camadas de varredura (dependências, código, segredos no histórico, configuração), na cadeia e com calendário, porque as vulnerabilidades novas não esperam o seu próximo push; o relatório com a forma do degrau 13, com a cláusula de "não varrido" em vez de "limpo"; o critério de P0 dado por mim; e a proibição de atualizar sem passar pelo ciclo, que é a que evita a sexta-feira quebrada.

De fechamento (corrigir e transformar em comporta):

O que estou pedindo: uma pendência por correção, com o vermelho do degrau 8 onde é possível (uma vulnerabilidade corrigida sem teste volta com a próxima refatoração); a varredura repetida como evidência; e a conversão em comporta, que é o que faz este degrau continuar vivo quando ninguém olha.

3. Resultado esperado

• A varredura em quatro camadas rodando em cada push e semanalmente.
• docs/SECURITY_[data].md com os achados e o não varrido; docs/SECURITY.md com a política, o calendário, a comporta e a cobertura.
• Os P0 e P1 corrigidos, cada um com a sua pendência e o seu teste onde se aplica.
• A comporta em docs/GATES.md.

4. Verificação de completude

• Peça-lhe o link da última rodada da varredura: está em verde, e de que data é?
• O relatório diz o que NÃO varreu?
• Cada P0 tem a sua pendência fechada com evidência, ou aberta com data?
• Peça-lhe que introduza de propósito uma dependência com vulnerabilidade conhecida num ramo: a cadeia fica em vermelho?
• Você sabe quando roda a próxima varredura programada?

5. Sinais de alerta

• A varredura passou limpa de primeira num sistema com mais de um mês. Quase nunca é verdade: falta uma camada, ou varreu-se só o ramo e não o histórico.
• Atualizaram-se dez dependências num commit "para fechar os achados". Esse commit não tem antes nem depois; é a sexta-feira quebrada esperando.
• A varredura está lá mas não é comporta: produz relatórios que ninguém lê.
• Há um P0 "aceito" sem pendência, sem data e sem assinatura.

Passo 19 — Testes de desempenho em volume e ponto de ruptura (contrato do degrau)

Fase: saída para produção. Quando: na fase de saída para produção, depois do 16 (sem observabilidade não se sabe o que quebrou) e do 17 (sobre a persistência já otimizada), e antes da primeira implantação em produção. Repete-se antes de cada implantação que mude a arquitetura, a persistência ou um fluxo crítico, e quando o dimensionamento muda (vende-se a outro cliente, dobra-se o volume). Num legado, roda-se com os volumes medidos em N6, antes da primeira implantação posterior à normalização. Forma: um único disparo; o agente carrega, mede e quebra; você lê os números e o ponto de ruptura. Tamanho: proporcional: num projeto pequeno, uma rodada ao volume esperado e uma ao "vezes dez"; num com consequências, completo, com o ponto de ruptura encontrado e os limiares registrados para o monitoramento.

Para que serve

O degrau 3 dimensionou com contas; este degrau comprova as contas com o sistema real rodando. Quero saber três coisas antes de entrar o primeiro usuário: como se comporta o sistema ao volume que o negócio disse (a tela mais usada responde no que o dono toleraria?), como se comporta no "vezes dez" (aguenta, ou o que deixa de aguentar primeiro?), e onde quebra: a carga exata em que algo cede, e o que é esse algo (as conexões ao banco, a memória, uma fila, um bloqueio). O ponto de ruptura é o número mais útil de toda a fase, porque dele saem os limiares de alerta do degrau 21: um alerta posto "a olho" avisa tarde ou avisa sempre; um alerta posto abaixo do ponto de ruptura medido, com uma margem, avisa quando ainda há tempo. Os padrões de escala que tirei de um sistema em produção Ref. 12 e a bateria que morria por memória e parecia um teste falho Ref. 44 são os dois antecedentes: o primeiro, de medir a carga real; o segundo, de que um ponto de ruptura não encontrado a tempo se disfarça de outra coisa.

Se você está começando. Um teste de carga é um programa que simula muitos usuários usando o sistema ao mesmo tempo, para ver o que acontece. Vazão (throughput) é quantas ações por segundo ele aguenta. Latência é quanto uma ação demora para responder; olha-se a mediana (a metade das ações demorou menos que isto) e o percentil 95 (95 % demorou menos que isto; os 5 % restantes são os usuários que reclamam). O ponto de ruptura é a quantidade de carga em que algo deixa de funcionar: não "fica lento" e sim "as conexões ao banco se esgotaram" ou "a memória encheu". E um limiar é um número limite a partir do qual o monitoramento avisa.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com seu conteúdo e seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

• O dimensionamento (degrau 3 ou N6): o volume esperado e o "vezes dez".
• A observabilidade (16) acesa, para ver o que quebra.
• A persistência otimizada (17) com os seus orçamentos.
• Um ambiente de teste parecido com produção em recursos, ou a consciência de em que difere.
• Os fluxos críticos (os da árvore semântica, ou os da caracterização num legado).

2. Prompts

Inicial (carregar, medir, quebrar):

O que estou pedindo: um script de carga que é mais um medidor (vive no repositório e tem teste, porque um script de carga que não exercita o fluxo mede o ar); três rodadas (esperado, vezes dez, até quebrar); os números com comandos; a comparação com os orçamentos, a tolerância do negócio e os pressupostos do dimensionamento, que é onde se descobre que o degrau 3 errou em alguma coisa; e nada de otimizar ainda, porque otimizar sem ler o diagnóstico é mudar o que não era.

De fechamento (limiares e pendências):

O que estou pedindo: os limiares de alerta derivados do ponto de ruptura, que é o encaixe com o degrau 21; os gargalos como pendências com o número como critério (assim se fecham com evidência e não com "agora anda melhor"); e o teste de carga como comporta arquivada, para que dentro de seis meses se possa comparar.

3. Resultado esperado

• O script de carga no repositório, com teste.
• docs/PERFORMANCE_[data].md com as três rodadas, os números, o ponto de ruptura e o diagnóstico; docs/PERFORMANCE.md com os limiares e a comporta.
• Uma pendência por gargalo abaixo do volume decidido.
• O teste de carga como comporta antes das implantações que o exigem.

4. Verificação de completude

• A tela mais usada, ao volume esperado, demora menos que a tolerância do dono? Se não, há uma pendência aberta com esse número.
• O ponto de ruptura diz o que quebrou e a que carga, ou diz "o sistema ficou lento"?
• Os limiares de docs/PERFORMANCE.md estão abaixo do ponto de ruptura e acima do esperado?
• Rode você o script ao volume esperado com o comando que ele lhe deu: os números se parecem?
• O ambiente de teste difere de produção em recursos, e está anotado como?

5. Sinais de alerta

• "Aguenta o vezes dez sem problemas" sem um ponto de ruptura. Se não encontrou onde quebra, não subiu a carga o suficiente.
• O script de carga bate na API mas não passa pela tela, num sistema em que a tela é a que carrega. Mede outra coisa.
• Os resultados são de uma rodada na máquina do agente, não no ambiente de teste.
• Corrigiram-se gargalos durante o teste, "já que estava". Agora você não sabe que número corresponde a que versão.

Passo 20 — Documentação viva e manuais que uma pessoa pode seguir sem IA (contrato do degrau)

Fase: saída para produção. Quando: o manual de usuário cresce com cada bloco funcional, no fechamento, com as telas novas; alimentado pelas pendências fechadas, que são a documentação do feito. Os três manuais completos se geram na fase de saída para produção, depois do 15, e o teste com uma pessoa que não programa se faz antes da primeira implantação. A rotina do mesmo commit rege durante toda a operação. Forma: rotina; mais um disparo longo quando se geram os manuais. Tamanho: proporcional. Um sistema pequeno precisa, no mínimo, do manual de infraestrutura e recuperação; o de usuário pode ser uma página. O que não muda: se a pessoa que o construiu desaparece, outra tem que poder continuar.

Para que serve

Faça com que o sistema possa ser usado, mantido e recuperado sem o agente e sem você. Se no dia em que não há agente não se pode implantar, não está terminado. No método clássico a documentação era cara e envelhecia; aqui regenerá-la é grátis, então a regra passa a ser "no mesmo commit" e "reproduzível à mão". Os manuais que escrevi para o Plano de Saúde com esse critério são o modelo Ref. 24; e o arquivo de projeto que virou um histórico de milhares de linhas é o contraexemplo Ref. 41.

Um critério de qualidade para o manual de recuperação, que serve para julgá-lo sem ser técnico: tem que poder ser seguido por uma pessoa de confiança que não programe, às três da manhã, com o sistema caído e o agente sem conexão. Se em algum passo diz "consultar o desenvolvedor" ou "conforme o caso", esse passo está incompleto.

E essa prova deixa três coisas escritas, porque se não deixa nada, a comporta se cumpre sem medir nada — que é a forma mais barata de ter uma comporta decorativa. As três são: o tempo medido de ponta a ponta (quando a pessoa começou, quando o sistema voltou a funcionar), o ponto exato onde travou (o passo do manual, com as palavras dela, não com as suas), e cada palavra que não entendeu. As três vão com data e com o nome de quem fez a prova. E cada palavra que não entendeu abre uma pendência: ou se explica no manual, ou se troca o nome da coisa em todo o sistema. Essa lista de palavras é, além disso, o melhor insumo do glossário do usuário do degrau 2, e a retrospectiva do degrau 23 a usa como proposta de mudança.

Sem estes manuais, dito em uma palavra que não precisa de explicação: o dono não é dono, é inquilino. Tem o sistema, paga por ele, e não pode entrar sem pedir permissão a quem o construiu.

E uma fonte que não se deve desperdiçar: as pendências fechadas. Cada uma traz sua especificação, sua decisão, sua evidência e sua data. O manual de usuário não se escreve do zero no final: monta-se, bloco a bloco, a partir das pendências que fecharam, e o diário de mudanças sai diretamente delas.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com seu conteúdo e seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

• Quem são os leitores de cada manual: o usuário final, quem mantém, quem opera a infraestrutura. O negócio sabe; o agente pergunta se não está claro.
• O sistema rodando no ambiente de teste, para tirar capturas reais.
• As pendências fechadas do bloco, com sua documentação de fechamento (degrau 5).
• docs/DEPLOYMENT.md (degrau 15) e docs/LOCKS.md (degrau 14), que são insumos.

2. Prompts

Rotina (vai no contrato de convivência):

O que estou pedindo: a regra do mesmo commit, que é a única que mantém um manual em dia; o fechamento de bloco como momento em que as pendências fechadas viram manual e diário de mudanças; e a pergunta quando não está claro a que manual vai.

Para gerar os manuais:

O que estou pedindo: os três manuais com seus leitores; capturas reais do ambiente de teste (não desenhos nem descrições); o critério das três da manhã para o de recuperação; a cláusula de completude na sua forma para documentar: o que só o negócio sabe se pergunta, e não se deixa um buraco nem se inventa; e data e versão, para que se saiba a que sistema corresponde cada manual.

3. Resultado esperado

• docs/USER_MANUAL.md (ou HTML), com capturas reais e incrustadas, que cresceu bloco a bloco.
• docs/MAINTENANCE_MANUAL.md.
• docs/INFRASTRUCTURE_AND_RECOVERY_MANUAL.md: passo a passo, para uma pessoa.
• docs/CHANGELOG.md, alimentado pelas pendências fechadas.
• Cada um com data e a versão do sistema que documenta.
• Nos commits que mudam telas, operação ou implantação: o manual atualizado.
• O registro da prova do manual de recuperação, com quatro coisas: a data e o nome de quem a fez; o tempo medido de ponta a ponta; o passo exato onde travou, com as palavras dela; e a lista de palavras que não entendeu. Mais uma pendência aberta por cada uma dessas palavras. Onde se escreve é sua escolha — no final do próprio manual de recuperação basta —; o que não é opcional é que exista.

4. Verificação de completude

• Abra o manual de usuário numa tela ao acaso: a captura coincide com o que há hoje no ambiente de teste?
• O manual de recuperação, você conseguiria segui-lo, ou alguém de confiança que não programe? Leia a seção "caiu": diz o que fazer, em ordem, com os comandos?
• Escolha um commit recente que mudou uma tela: tocou no manual?
• O diário de mudanças tem uma entrada para cada pendência fechada do último bloco?
• Há um buraco tipo "[completar]" ou "consultar o responsável"? Aí o agente tinha que perguntar.
• Cada manual diz para que versão do sistema vale?
• A prova do manual de recuperação deixou seu registro: quanto tempo levou, onde a pessoa travou e que palavras não entendeu, com data e nome? E dessas palavras, cada uma abriu uma pendência? Se o registro diz "a prova foi feita" e nada mais, a prova não se pode repetir nem comparar: a comporta está cumprida no papel.

5. Sinais de alerta

• O manual de usuário tem capturas de uma versão que já não existe. Foi gerado uma vez e não se manteve: a regra do mesmo commit não está no contrato ou não está sendo aplicada.
• O manual de recuperação começa com "abra uma sessão com o agente". Se o agente é pré-requisito, não é um manual para uma pessoa.
• Ninguém fora do construtor leu nunca o manual de recuperação. Peça a alguém que o siga no ambiente de teste; o que travar é o que há que corrigir.
• A prova foi feita e não ficou registrada, ou ficou registrada como "deu bem". Então ninguém pode dizer quanto tempo levou nem onde esteve perto de não dar, e na próxima vez se começa de zero.
• O registro não tem nem uma palavra na lista das que não se entenderam. Acontece de vez em quando e é verdade; acontece sempre e significa que ninguém perguntou.

Passo 21 — Monitoramento de recursos, funções e consultas fora de faixa, com relatório cíclico (contrato do degrau)

Fase: operação. Quando: monta-se na fase de operação, com a primeira implantação em produção, com os limiares do 19 e as métricas do 16; a partir daí, roda sozinho, e o relatório cíclico se lê com o dono em cada ciclo (semanal num sistema com consequências, mensal num pequeno). Cada evento fora de faixa entra no ciclo como pendência corretiva. Num legado, igual, com uma diferença: a primeira leitura do relatório é a linha base, e o que já estava fora de faixa no primeiro dia se converte em pendências com a sua marca de velocidade. Forma: um único disparo para montar; depois, rotina cíclica. Tamanho: mínimo num projeto pequeno (um relatório mensal, um alerta de disco e um de erros de banco); completo num com consequências (limiares por função e por consulta, alertas, relatório semanal).

Para que serve

Os testes do degrau 19 dizem como se comporta o sistema um dia, com uma carga que eu escolhi. A produção é todos os dias, com a carga que os usuários escolhem, com os dados crescendo, e com mudanças que entram toda semana. O que estava em faixa em outubro sai de faixa em março sem que ninguém mude nada, só porque a tabela cresceu. Este degrau existe para que isso se veja antes que o usuário o veja: o uso de recursos contra a capacidade, o tempo de resposta de cada função, cada ponto de entrada, cada tarefa e cada consulta, comparado com os limiares do 19 e com a sua própria história; um alerta quando algo sai de faixa; e um relatório cíclico que eu leio com o dono, onde cada desvio tem uma causa ou uma pendência. O teto apertado ao medido Ref. 37 é a ideia de fundo: a faixa não é uma opinião, é o número medido mais uma margem; e a cota de integração contínua que se esgotou sem que ninguém olhasse Ref. 39 é a falha que ele evita: um recurso que se consome sem monitoramento se descobre quando acaba.

Duas regras que não negocio. Um alerta que dispara e ninguém lê é um defeito do alerta, não de quem não o leu: ajusta-se ou elimina-se. E um limiar não se sobe para calar um alerta sem uma razão medida escrita.

Se você está começando. Monitorar é olhar o sistema o tempo todo por máquina e avisar quando algo sai do normal. Os recursos são o que o sistema consome: processador, memória, disco, conexões ao banco, e também cotas de serviços externos (quantas mensagens por mês o provedor deixa você mandar). "*Fora de faixa*" quer dizer acima de um limiar (um limite fixo, que saiu dos testes do degrau 19) ou muito diferente da linha base (o que esse mesmo número vinha dando nos últimos dias). Um alerta é o aviso na hora; o relatório cíclico é o resumo que se lê a cada semana ou a cada mês com calma.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com seu conteúdo e seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

• A observabilidade (16): as métricas e os registros dos quais ele se alimenta.
• Os limiares do 19 e os orçamentos do 17.
• Produção implantada (15), com acesso de somente leitura para o monitoramento.
• O canal de alertas e o ciclo do relatório: você os decide com o dono.

2. Prompts

Inicial (montar e demonstrar):

A janela da medição. O relatório cíclico compara as linhas observadas por ano contra o declarado no degrau 3. Um número correto com uma janela errada abre um pendente falso: na prática Turnera herdada, 30.000 linhas de três anos foram passadas como se fossem de um. Por isso a medição leva a sua janela verificável: o primeiro e o último registro lidos da base ou do registro, não um número digitado à mão. Se a ferramenta não consegue ler a base, declara isso como ponto cego; uma janela digitada à mão é marcada como tal no relatório e só avisa, nunca abre um pendente por si só. (Decisão D-039.)

O que estou pedindo: coleta com história (sem história não há linha base, e sem linha base não há "fora de faixa"); alertas contra duas referências, o limiar absoluto do 19 e o desvio relativo sobre a própria história; o relatório cíclico com a forma de um relatório do degrau 12 (cada desvio com causa ou com proposta, nada de "tudo normal"); a conversão de cada desvio em pendência com número; e as duas demonstrações: o primeiro relatório e um alerta provocado.

Rotina de cada ciclo (vai no contrato de convivência):

O que estou pedindo: que o relatório se leia e se decida, com rastro; e a regra do limiar, que é a que evita que o monitoramento vá ficando silencioso aos poucos.

3. Resultado esperado

• Coleta de recursos e tempos de resposta com história, sem dados pessoais.
• Alertas por limiar e por desvio, para um canal que uma pessoa lê.
• O relatório cíclico, gerado sozinho, com cada desvio causado ou proposto.
• docs/MONITORING.md com limiares, canal, ciclo e como silenciar com razão.
• A rotina no contrato; os desvios como pendências corretivas.

4. Verificação de completude

• Peça que se ultrapasse um limiar de propósito em teste: o alerta chegou até você, pelo canal combinado, com o identificador?
• Leia o último relatório: cada evento fora de faixa tem causa ou proposta? Algum ficou sem nada?
• Há uma pendência para cada desvio que você decidiu atender, com o número como critério?
• Algum limiar subiu desde o 19? Com que razão escrita?
• O relatório menciona a cota dos serviços externos (mensageria, integração contínua)?

5. Sinais de alerta

• Os alertas disparam todos os dias e ninguém os lê. É preciso baixar a sua quantidade até que cada um signifique alguma coisa, não se acostumar.
• O relatório diz "tudo normal" três ciclos seguidos. Ou o sistema não tem usuários, ou o relatório não olha o que importa.
• Um limiar subiu "para que pare de avisar". É o degrau 21 morrendo em silêncio.
• O monitoramento guarda dados pessoais "para poder diagnosticar". É um vazamento com horário.

Passo 22 — Monitoramento de erros e relatório cíclico: nenhum erro sem pendência (contrato do degrau)

Fase: operação. Quando: monta-se na fase de operação, com a primeira implantação, junto com o 21, sobre os registros do 16; a partir daí roda sozinho, com alertas na hora e um relatório cíclico que se lê com o dono. Cada erro novo entra no ciclo como pendência corretiva e se fecha com o teste que o reproduz em vermelho. Num legado, a primeira leitura é a linha base: os erros que já existiam no primeiro dia viram pendências com a sua marca de velocidade, e nenhum fica como "conhecido" sem uma pendência que diga por que se tolera e até quando. Forma: um único disparo para montar; depois, rotina cíclica. Tamanho: obrigatório em todo projeto com usuários: a captura centralizada e o relatório não se negociam; os alertas na hora, proporcionais.

Para que serve

Um sistema em produção produz erros que nenhum usuário reporta: o que viu a tela em branco e tentou de novo, o da tarefa noturna que falhou e ninguém olha, o da chamada externa que devolveu um erro e o código engoliu. Se não os capturo, não existem até que existam demais. Este degrau é a contraparte do 21: aquele vigia o desempenho, este vigia os erros, e os dois terminam no mesmo lugar, o ciclo, como pendências corretivas. As regras de fundo são duas. Nenhum erro sem pendência: um erro novo abre uma, e se fecha com o teste que o reproduz em vermelho, como pede o modo corretivo do caminho evolutivo. E não existe o "erro conhecido" sem uma pendência que diga por que se tolera e até quando; "esse erro sempre esteve aí" é a frase com que um sistema apodrece. O erro de autenticação reportado como sucesso Ref. 43 e as quatro rodadas até a causa raiz Ref. 22 são os dois antecedentes: o primeiro, de que os erros se escondem se não forem capturados por máquina; o segundo, de que um erro sem reprodução se corrige várias vezes.

Se você está começando. Um erro é qualquer coisa que o sistema tentou fazer e não conseguiu: uma tela que não carregou, uma tarefa noturna que se interrompeu, uma chamada a outro serviço que falhou. Uma exceção não tratada é um erro que o código não previu e que corta o que estava fazendo. Capturar um erro é guardá-lo com todos os seus dados (quando, em que versão, com que identificador, a pilha, que é a lista de passos do programa até a falha) num único lugar central, em vez de deixá-lo se perder na tela de um usuário. Agrupar é juntar as mil vezes que aconteceu o mesmo erro numa só entrada com um contador. E a taxa de erro por fluxo é, de cada cem vezes que alguém cadastrou um turno, quantas falharam.

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com seu conteúdo e seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

• A observabilidade (16): os erros chegam com identificador de correlação, versão e ator.
• A tabela de cadeados (14): os erros em ações com consequência são alerta imediato.
• Produção implantada (15), com o navegador do usuário incluído na captura.
• O canal de alertas e o ciclo do relatório, compartilhados com o 21.

2. Prompts

Inicial (montar e demonstrar):

Os erros da ferramenta não são erros do sistema. A captura centralizada separa por fonte: os erros do sistema e os das ferramentas que o observam (o painel, o agente residente, o próprio monitoramento) são guardados com fonte distinta, o relatório os lista em seções separadas, e só os do sistema abrem pendentes. Na prática Turnera, o primeiro relatório cíclico abriu seis "bugs" que eram o painel do Forge falando com um servidor desligado. (Decisão D-038.)

O que estou pedindo: a captura nos três lugares onde os erros se escondem (backend, tarefas, navegador), com o identificador do 16 para poder segui-los; o agrupamento, sem o qual o relatório é uma lista de dez mil linhas; os três alertas que importam (novo, recorrente que cresce, com consequência); o relatório com a taxa por fluxo, que é o número que o dono entende; as duas regras; e a demonstração de ponta a ponta, do navegador ao relatório.

Rotina de cada ciclo (vai no contrato de convivência):

O que estou pedindo: a disciplina do ciclo, e a regra do erro que desaparece, que é a mais contraintuitiva e a que mais vale: um erro que foi embora sozinho volta sozinho.

3. Resultado esperado

• Captura centralizada de erros no backend, nas tarefas e no navegador, agrupados por causa, sem dados pessoais.
• Alertas por erro novo, recorrente que cresce, e com consequência.
• O relatório cíclico com a taxa de erro por fluxo.
• docs/MONITORING.md completo (com o 21); a rotina no contrato.
• Uma pendência para cada erro aberto; nenhum "conhecido" sem pendência.

4. Verificação de completude

• Provoque você um erro no navegador em teste (uma ação que você sabe que falha): apareceu na captura com o seu identificador, e o alerta chegou até você?
• Leia o último relatório: há algum erro recorrente sem pendência nem razão?
• Pegue um erro "corrigido" do relatório: a pendência tem o teste que o reproduziu em vermelho?
• A taxa de erro por fluxo está lá, e baixou ou subiu em relação ao período anterior?
• Procure um dado pessoal na captura de erros: não pode estar.

5. Sinais de alerta

• Zero erros em produção durante um mês com usuários reais. Não existe sistema assim; a captura não está vendo o navegador ou as tarefas.
• Um erro com mil ocorrências e um comentário "conhecido, não afeta". Sem pendência, sem data.
• Os erros se "corrigem" reiniciando o serviço. Desaparecem e voltam.
• O relatório de erros e o de recursos são lidos por gente diferente e ninguém os cruza: a consulta lenta do 21 é a causa do tempo de espera esgotado do 22.

Passo 23 — O agente dentro do sistema, e a retrospectiva com número (contrato do degrau)

Fase: operação. Quando: o agente residente, ao entrar em operação, depois da primeira implantação em produção. A retrospectiva, no fechamento de cada etapa e do projeto; volta ao degrau 0 para o projeto seguinte. Rode também uma retrospectiva curta quando mudar o modelo que constrói: um contrato calibrado para um modelo não necessariamente rende igual com outro, e a mudança de modelo é exatamente o tipo de achado que esta escada pede para virar uma proposta de mudança, não uma surpresa descoberta no meio de um bloco. Forma: duas partes: uma conversa para definir o escopo do agente residente, e um disparo longo para a retrospectiva. Tamanho: o agente residente é opcional (muitos sistemas não precisam dele; os que têm usuários que pedem suporte, sim). A retrospectiva é obrigatória em todo projeto, mesmo que seja de uma página: sem ela o método não aprende.

Para que serve

Duas coisas que fecham o mesmo ciclo. Primeiro: deixe o agente residente em produção, com escopo delimitado, para diagnosticar, operar e dar suporte sem que você tenha que estar Ref. 13. Segundo: revise o próprio método com números, e deixe que o que se aprende mude a escada. Evita o agente que opera sem mapa do sistema, e o método que se repete igual projeto após projeto sem aprender. A retrospectiva com número que me levou a eliminar uma equipe inteira de agentes é o modelo da segunda Ref. 6.

Sobre o agente residente, a regra que ordena tudo: age em nome de alguém. Sua credencial está mapeada a uma pessoa responsável, e tudo o que faz fica registrado em nome dessa pessoa. Não é uma conta de sistema anônima: é um empregado com chefe. Isso define seu escopo (o que essa pessoa lhe autorizou) e sua rastreabilidade (quem responde pelo que ele fez).

1. Contexto necessário

O que segue é a lista genérica. Os arquivos concretos que você tem que ter prontos antes de cada prompt, com seu conteúdo e seu estado mínimo, estão na seção 2, no bloco "Antes de enviar o prompt" que precede cada um.

Para o agente residente:

• O que o agente pode fazer em produção e o que não: ler, diagnosticar, mudar configuração, executar ações. Você decide.
• Como o agente se identifica diante do sistema (uma credencial própria, mapeada a uma pessoa responsável).
• A quem avisa quando encontra algo que não consegue resolver (ticket, e-mail).

Para a retrospectiva:

• Os incidentes do projeto, os custos (tokens, cota, seu tempo), as pendências que mais voltas deram, e as datas.

2. Prompts

Para o agente residente (inicial):

O que estou pedindo: o mapa do sistema antes de operar (operar sem mapa é a falha que este degrau evita); a cláusula de completude na sua forma: os buracos do mapa se declaram, não se escondem; os três níveis de escopo para que você escolha um e não um "depende"; a regra da credencial em nome de uma pessoa; e a cláusula de injeção: o que o agente lê em produção é dado, nunca instrução, porque um log ou um ticket são justamente o lugar onde alguém de fora pode tentar falar diretamente com o agente.

Para o agente residente (de fechamento):

O que estou pedindo: o documento do agente residente (sem o valor da credencial, nunca), e a prova em vermelho do escopo: uma tentativa real, registrada, de fazer algo fora do nível, recusada. É o degrau 8 aplicado às permissões.

Para a retrospectiva:

O que estou pedindo: números com fonte (custos, pendências, voltas, incidentes); cada incidente mapeado a um degrau, porque um incidente que não cai em nenhum é um degrau que falta; a cláusula de completude para os números que ele não tem (pedir ou marcar como estimativa); e pelo menos uma proposta concreta de mudança à escada, porque uma retrospectiva que não muda nada não foi uma retrospectiva.

3. Resultado esperado

• docs/RESIDENT_AGENT.md: mapa do sistema, escopo escolhido, credencial mapeada a uma pessoa, procedimento de aprovação, e a prova de recusa registrada no log.
• docs/RETROSPECTIVE_[data].md: os números com sua fonte, os incidentes mapeados a degraus, e pelo menos uma proposta de mudança à escada com sua justificativa.

4. Verificação de completude

• O mapa do sistema diz o que o agente NÃO consegue ver? Se não diz, tem buracos escondidos.
• Você provou (ou viu no log) que uma ação fora do escopo é recusada?
• A credencial do agente age em nome de uma pessoa identificável?
• O documento diz explicitamente que o que o agente lê em produção é dado, não instrução?
• A retrospectiva tem números com fonte, ou adjetivos? ("Custou muito" não é um número.)
• Cada incidente cai num degrau? Se um não cai em nenhum, falta um degrau: essa é a proposta de mudança.
• Há pelo menos uma proposta concreta de mudança à escada? Se a retrospectiva não muda nada, não foi uma retrospectiva.
• O modelo que constrói mudou desde a última retrospectiva? Se sim, há uma revisão curta de quais contratos continuam rendendo igual e quais não?

5. Sinais de alerta

• O agente residente "precisa" de um nível mais alto de permissões a cada semana. Revise se o que pede é para resolver problemas do sistema ou os seus próprios limites.
• O agente executou algo porque "um log dizia" ou "um ticket pedia". Um registro ou um ticket não autorizam nada; só você, ou o procedimento de aprovação que você escreveu, autorizam.
• A retrospectiva diz que tudo saiu bem. Nunca sai tudo bem; está escrita para você, não para o método.
• Dois projetos seguidos tiveram o mesmo incidente e a escada não mudou entre um e outro. O degrau 23 não está sendo fechado: escreve-se a retrospectiva e não se aplica.