Método · software com IA · código aberto
Urazuke, o método da evidência.
Urazuke (裏付け) é a palavra japonesa para o respaldo que uma afirmação tem: o que a sustenta por trás. É o meu método para construir software com inteligência artificial que saia robusto e pronto para produção, sem que o dono do projeto precise ler uma única linha de código. Destilei-o de três sistemas reais que hoje tenho em produção, apoiado na engenharia de sistemas de sempre e no que esses sistemas me ensinaram sobre onde os modelos a aplicam de forma frágil.
Autor: Pablo Kuschniroff, assistido por Claude Code.
Creative Commons BY-SA 4.0 · Oito idiomas · Neutro em relação à ferramenta · Três sistemas em produção como fonte · Código aberto e colaborativo
A tese
A IA não interrompe o método: ela o continua.
Antes da tese, um esclarecimento que me importa: este método não é uma coleção de remendos que fui pondo depois de cada tombo. Sai de dois fatores combinados. O primeiro é o meu próprio conhecimento de engenharia de sistemas: levantamento, requisitos, dimensionamento, testes como evidência, implantação reproduzível, auditoria; trago-o de muito antes de estes modelos existirem. O segundo é o que três sistemas em produção me mostraram, incidente após incidente: onde os modelos aplicam esses princípios de forma frágil, e portanto onde é preciso apertar por escrito. As cicatrizes provam onde a rigidez é necessária; não são a origem dos princípios.
A indústria deixou de confiar no autor do código há vinte anos. Quando a escrita passou a equipes júnior, terceirizadas ou rotativas, a revisão linha por linha tornou-se impossível de sustentar, e o que cresceu no lugar foi tudo o que hoje damos por certo: testes automatizados, integração contínua, critérios de aceitação, pipelines que não deixam passar nada sem verde. Essa foi a resposta da engenharia de sistemas a "quem escreve não é confiável": não ler o código, exigir evidência. O modelo é o próximo autor, não o primeiro desconfiável.
Para onde vai o esforço do humano
O humano faz só duas coisas: decide e verifica artefatos. Redigir, construir, testar, medir e documentar é o modelo que faz. Cada degrau termina em uma verificação de completude sem ler código.
A evidência se prova a si mesma
Um teste que você nunca viu falhar, você não sabe se prova algo. Um medidor sem teste mente. Um relatório sem pontos cegos esconde. A disciplina de independência do controle de qualidade, levada um passo mais para dentro.
O custo dos artefatos
Antes a documentação era cara e envelhecia. Agora regenerá-la é grátis, então a regra passa a ser "no mesmo commit" e "reproduzível à mão, sem IA". O que era um ideal inalcançável passa a ser uma comporta.
O que é e o que não é
Engenharia de sistemas aplicada a um construtor que não se cansa e em quem não se pode acreditar.
Para quem vem de sistemas soa familiar: levantamento, requisitos, dimensionamento, projeto, construção, teste, implantação, operação, auditoria. Para quem vem do vibecoding dá o que falta, que é justamente o esqueleto.
O que é
- Um método: o que fazer em que ordem, o que pedir ao modelo, o que ele tem que entregar, e como saber que está completo.
- Vinte e quatro degraus em quatro trechos, cada um com um contrato: contexto, prompts, resultado esperado, verificação, sinais de alerta.
- Neutro em relação à ferramenta: Claude Code, Cursor, Codex CLI, Gemini CLI ou Forge. Cada artefato é um arquivo, um teste ou um script.
- Destilado de três sistemas reais em produção, com cada regra amarrada ao commit e ao tombo que a originou.
O que não é
- Um curso de programação nem de um framework.
- Uma coleção de truques de prompts para o modelo escrever melhor.
- Um método para o protótipo da demo de sexta-feira: é para o que precisa continuar funcionando depois.
- Um método que serve para qualquer projeto. O degrau 0 define a fronteira por escrito.
A escada
Vinte e quatro degraus, quatro trechos, na ordem em que se sobem.
Os degraus estão numerados na ordem cronológica em que se sobem. Os de arranque sobem-se uma vez por projeto; os do laço repetem-se a cada mudança; os de saída para produção, uma vez, antes da primeira implantação; os de operação, quando o sistema já está vivo. O 23 fecha o ciclo e volta ao 0. Cada degrau tem uma ficha de oito partes e um contrato com os prompts. Sem prazos: o método é um processo, não uma promessa de velocidade.
Uma vez por projeto, antes de escrever funcionalidade
Os cinco que mais dão tentação de pular e mais caro custa pular.
A cada mudança, durante todo o projeto
Na ordem em que se fazem com cada pendência. Aprendem-se nos dois primeiros blocos e praticam-se o projeto inteiro.
Uma vez, antes da primeira implantação
Convertem "funciona" em "dá para sustentar": auditoria, cadeados, esteira para produção, observabilidade, persistência, vulnerabilidades, desempenho e manuais.
Quando o sistema já está vivo
Os dois monitoramentos com relatório cíclico, o agente residente e a retrospectiva que fecha o ciclo e volta ao 0.
Treze degraus que não se negociam em nenhum projeto
- Elegibilidade (uma hora; economiza meses)
- Contrato de convivência
- Definição curta, com "o que NÃO é"
- Dimensionar com números do negócio
- As pendências como plano
- Decisões com dono e data
- Testes vistos em vermelho
- Relatório verificado / acreditado / pontos cegos
- Retrospectiva com número
- Varredura de dependências e segredos na esteira
- Captura centralizada de erros e relatório
- Qualidade do código na esteira, no mínimo
- Casos de teste manual executados por pessoas
A linha do tempo
Quando se sobe cada degrau, e o que acontece no meio.
Um método sem linha do tempo é uma lista de boas intenções. Esta é a de qualquer projeto: cinco fases, em ordem, e em cada uma o que se faz além dos degraus: a ingestão de requisitos, a infraestrutura, a esteira de integração e implantação, o desenvolvimento, os testes de ponta a ponta, a vista humana, os testes humanos. Sem prazos: cada fase dura o que o sistema pedir.
Ingestão
Levantamento com o dono, com os métodos clássicos da engenharia de requisitos: entrevistas, casos de uso, modelo de domínio com seus estados, protótipos de tela. Em prosa, incompleto de propósito: o agente o completa perguntando.
Arranque (degraus 0 a 4)
Elegibilidade, contrato, definição com árvore semântica, dimensionamento. E toda a infraestrutura inicial e a cadeia CI/CD: repositório, ambiente de teste, integração contínua, primeira implantação com o sistema vazio. O dono abre a URL e vê a tela vazia.
Laço (degraus 5 a 12)
Bloco funcional por bloco. Com cada pendência: especificação, decisões, teste em vermelho, teste de ponta a ponta do fluxo, captura da tela que o dono olha. No fechamento de cada bloco: a bateria completa de ponta a ponta e testes humanos no ambiente de teste.
Saída para produção (13 a 20)
Auditoria por outra sessão. Cadeados antes de construir o que cobra ou envia. Fechamento da cadeia para produção com retorno testado. Os três manuais. Testes de aceitação do dono sobre todos os fluxos. E os quatro degraus de qualidade operacional prévios à implantação: observabilidade, persistência, vulnerabilidades, desempenho.
Operação (21 a 23 e o laço)
Agente residente em nome de uma pessoa. Auditoria periódica. Cada evolução entra pelo laço completo e sai pela cadeia de implantação. Retrospectiva com números no fechamento de cada etapa. Os dois monitoramentos, recursos e erros, montados na semana da primeira implantação, com relatório cíclico que o dono lê.
Os testes de ponta a ponta não são uma vez só no fim
Com cada pendência, o fluxo que ela tocou. No fechamento de cada bloco, todos os fluxos que existem. Antes da produção, todos os fluxos com a versão exata que será promovida. Se você só faz a terceira, chega ao fim com semanas sem testar.
Os três casos de uso
Pasta vazia, sistema feito com o método, ou sistema herdado: por onde se entra.
A escada está escrita olhando para uma pasta vazia, que é o caso mais claro para aprender e não o mais frequente. Antes de abrir o agente convém saber em qual dos três casos você está, porque muda por onde se entra. E o terceiro, o sistema que já existe e não nasceu com o método, tem um caminho próprio: normaliza-se sem reescrever, e só depois se sobe a escada.
Projeto novo
Pasta vazia e um dono com um pedido. Entra-se pelo degrau 0 e sobem-se os vinte e quatro em ordem: uma semana de arranque antes da primeira funcionalidade. É o que descrevem o documento principal, os contratos e o curso.
Evolutivo-corretivo com método
O sistema já subiu a escada: tem contrato, mapa, pendências fechadas com evidência, bateria, implantação e manuais. Entra-se pelo degrau 5, abrindo um bloco, e segue-se o laço. É o 15 voltando ao 0.
Evolutivo-corretivo sem método
Um sistema que roda, com usuários, feito por outro ou por você mesmo sem evidência. Oito estações de normalização (N0 a N7): recuperar por autodescoberta os insumos que ninguém escreveu, com marcas de fonte; um cinto de segurança como comporta dura; a dívida paga à medida que se toca. Depois, o laço em modo corretivo ou evolutivo.
Ler o caminho evolutivo-corretivo → O curso, parte 2: o projeto herdado →
O contrato de cada degrau
Como se pede, o que tem que voltar, e como sei que voltou completo.
Cada degrau se executa com um contrato de cinco seções. Os prompts para o modelo estão em inglês, uma única peça idêntica nas oito versões do documento, e abaixo de cada um a explicação no idioma do leitor do que estamos pedindo e por que cada cláusula está ali.
Contexto requerido
Nomeado de forma genérica. Os levantamentos são por natureza incompletos; não se completam com um formulário, o modelo os completa perguntando.
Prompts
Textuais. Todos com a mesma cláusula: o modelo avalia se o contexto basta, pede o que falta antes de seguir, e não estima nem inventa um dado que só o negócio tem.
Resultado esperado
As características detalhadas do artefato: que arquivo, que seções, o que não pode faltar.
Verificação de completude
O que o dono confere sobre o artefato sem ler código. Se um der "não", o degrau não foi subido.
Sinais de alerta
Os sintomas de que o degrau foi subido mal embora pareça subido. Os que se veem semanas depois, quando já dói.
Um prompt de exemplo · degrau 7
docs/PENDING.md; a mudança já implementada; o comando da bateria em docs/STATUS.md; e o ambiente de teste a correr, com dados para o fluxo que se toca. Na documentação, cada prompt vem precedido de um bloco assim: que ficheiros constróis tu, com que conteúdo, e qual é o estado mínimo aceitável.Por que em inglês: o mesmo conteúdo em outro idioma ocupa entre 30 e 50 % mais tokens, os modelos seguem instruções com mais precisão em inglês, e o vocabulário do ofício é inglês. Mas não quero que o inglês seja uma barreira: na documentação, cada prompt traz sua tradução para o idioma do documento e um botão como este. Ao modelo cola-se o inglês; a tradução é para você entender. Todos terminam com "Reply in my language".
Do requisito à pendência
Engenharia de requisitos de sempre, decomposta em unidades que um modelo pode construir e você pode verificar.
Um requisito não é uma frase do cliente num chat. É essa frase processada por métodos que existem há décadas e que o modelo aplica muito bem se você pedir e muito mal se não: entrevistas, casos de uso, modelo de domínio, critérios de aceitação, protótipos de tela, rastreabilidade. No método, três artefatos os sustentam.
A árvore semântica
O sistema como uma árvore: domínios; abaixo, atores, processos (os casos de uso), entidades com seus estados, telas e integrações; e de cada nó pendem as pendências e as decisões. O agente a constrói, você a corrige, e é o que o agente lê antes de tocar código. Uma pendência que não pende de nenhum nó está fora de escopo, e isso se vê em dez segundos.
A especificação detalhada vive em cada pendência
O documento de especificação longo que envelhecia se decompõe: cada pendência traz seu nó da árvore, a história de origem com as palavras do cliente, a descrição, as regras de negócio com sua decisão e data, os dados, as telas, os casos de borda, os critérios de aceitação e como se verifica. Ler essa especificação é o mais perto que você vai chegar de ler código, e é a distância certa.
As pendências fechadas são documentação
Uma pendência fechada não se apaga: fica com sua especificação, a decisão que a originou, a evidência com que foi fechada, o commit e a data. A fila de pendências fechadas é o histórico funcional do sistema; dali saem o diário de mudanças, o manual do usuário, e a resposta a "por que o sistema faz isso" seis meses depois.
Com qualquer ferramenta
Os artefatos são arquivos, testes e scripts. O que muda é onde vão.
Claude Code
O contrato e as rotinas vão no CLAUDE.md do projeto; os prompts de degrau colam-se no chat ao subir cada degrau.
Cursor
As rotinas vão em .cursor/rules/ como regras sempre ativas; o resto, igual.
Codex CLI / Gemini CLI
Em AGENTS.md ou GEMINI.md na raiz do repositório.
Yujin Forge
O contrato e as rotinas são doutrinas, os prompts se injetam sozinhos ao cruzar cada comporta, e o registro de pendências é nativo. É o mesmo método com menos copiar e colar. Conheça o Forge →
O curso
Vinte e quatro lições com tarefas práticas, até a aplicação em produção.
Um manual tipo curso, uma lição por degrau, para aplicar o método em um projeto próprio ou no projeto guia ("Turnera", uma agenda de consultas com lembretes, sinais e dados pessoais: tudo o que é preciso para que nenhum degrau seja de mentira). Termina com a lista de saída para produção: vinte e quatro condições que o dono verifica sem abrir o código. A parte 2 do curso toma o mesmo consultório com um sistema herdado ("Turnera herdada") e ensina a normalizá-lo antes de corrigi-lo e evoluí-lo.
O que você precisa entender
O conceito de cada degrau, explicado como se explica a uma pessoa, com a falha real que o originou.
A tarefa, passo a passo
Com o prompt exato para o agente e o que fazer com o que ele devolve. Inclui testes de propósito: deixar uma pergunta sem resposta e ver o que ele faz.
A verificação e o entregável
As perguntas que você faz sobre o entregue, sem abrir o código, e o arquivo ou a evidência que tem que existir no fim.
Erros típicos e o projeto guia
O que acontece com quase todos na primeira vez, e como fica cada lição aplicada à Turnera.
Para quem está entrando
O desenvolvedor júnior na era posterior à programação à mão.
Se o modelo escreve o código, como se forma um júnior, o que aprende e para virar o quê? Um documento à parte sobre os focos de capacitação que perdem peso, os que ganham, a alfabetização que continua obrigatória, o objetivo e um plano de doze semanas com mentor. Escrito para iniciantes, como todo o método.
Em equipe
Vários desenvolvedores, cada um com seu agente, sobre um mesmo branch.
O método está escrito no singular. Este documento diz como se aplica quando há vários: as sete regras do branch compartilhado (a pendência como unidade de propriedade, integrar pequeno e com frequência, a integração contínua como árbitro, o que está pela metade atrás de um interruptor, o mapa como detector de conflitos, as decisões com nome, revisar evidência e não código), como se repartem os degraus, e os prompts.
Todo o material, em oito idiomas
Leia no seu idioma.
O espanhol é a fonte da verdade; as outras sete versões são traduções e, se divergirem, prevalece o espanhol. Os prompts são idênticos em todas. Três documentos por idioma: o documento principal (a tese, o levantamento dos três sistemas, os vinte e quatro degraus, as falhas reais e o glossário), os vinte e quatro contratos, e o manual-curso. E desde a versão 5, mais dois documentos por idioma: o caminho evolutivo-corretivo, para sistemas que já existem, e a parte 2 do curso com o projeto guia herdado.
O método é publicado sob Creative Commons Atribuição-CompartilhaIgual 4.0: pode ser usado, traduzido e adaptado, com atribuição e compartilhando igual. O repositório é público e colaborativo: github.com/pkuschnirof/urazuke. As melhorias entram por pull request a partir de um fork, com sua evidência, e eu as fundo depois de revisá-las.
Isto já existe com outro nome? Pesquisei a fundo o que há de parecido até outubro de 2026 (Uncle Bob e seu "gauntlet", Tsumiki, Spec Kit, Consort, IACDM, Osmani e outros), o que convém citar em vez de reivindicar, o que não encontrei em lugar nenhum, e a objeção mais séria com sua resposta. Está na Parte F do documento principal, "Trabalhos relacionados".
Dois manuais de execução no Forge, passo a passo e com capturas, feitos sobre projetos de prática reais: projeto novo (Turnera) e projeto existente (Turnera herdada). Com a evidência coletada em cada degrau (em espanhol).
Mais dois documentos, fora do corpus traduzido: as comportas explicadas, em inglês, porque é documentação de ferramenta e é gerada a partir dos dados; e as avaliações de modelos de IA sobre o método, em espanhol.
Se você vai consumir o método com uma ferramenta, não precisa ler o repositório: a interface de dados está em yujin.app/urazuke/api/. O seu índice lista cada recurso com o seu endereço canônico, a sua versão e o seu hash: gates.json, a definição mecânica das comportas, e prompts.json, os prompts. O hash é recalculado sobre o conteúdo, portanto uma cópia velha se denuncia sozinha.
De onde sai
Três sistemas em produção, e quarenta e seis casos documentados com data e evidência.
Levantei em modo somente leitura três repositórios que hoje estão em produção com gente real os usando: a ferramenta onde o método se formou (mil e noventa commits em cinco meses), um sistema de automação para um ente de saúde com dinheiro e dados sensíveis em jogo (seiscentas e quarenta e uma pendências, todas fechadas), e um balcão omnicanal para uma associação civil (o primeiro onde a medição precede sistematicamente a construção). Cada caso que cito no método está numerado no documento de referências, para que os procedimentos fiquem limpos e o detalhe continue a um clique. Os clientes estão anonimizados; os números, as datas e os commits são reais.
Onde o modelo falha ao aplicar o óbvio
O medidor que mentiu duas vezes. O erro de autenticação reportado como sucesso. As três de quatro asserções que estavam erradas. Cada um me disse onde um princípio que para mim era óbvio precisava virar uma cláusula explícita do prompt.
Retrospectiva com número
Eliminei uma equipe inteira de agentes com sessenta dólares e setenta e três minutos contra noventa minutos. Parti a implantação com vinte e quatro a vinte e sete minutos contra onze. A própria escada é isso.
Pablo Kuschniroff, assistido por Claude Code
RPAForce / Yujin. O método se aplica a si mesmo: suas decisões estão registradas com data e palavras textuais, e o repositório é público desde 18 de outubro de 2026 em github.com/pkuschnirof/urazuke.
Perguntas frequentes
Perguntas frequentes.
- Preciso saber programar?
- Não. Você precisa de um dono do domínio com critério e tempo para decidir, e noções mínimas do que é um repositório, um commit e um push. O método existe justamente para que o dono verifique evidência em vez de ler código.
- Serve para qualquer projeto?
- Não, e isso não é um defeito. Há duas condições excludentes: um repositório padrão onde deixar a evidência, e telas que possam ser operadas por programa para testar de ponta a ponta. O degrau 0 põe a fronteira por escrito.
- Preciso do Forge ou do NAC3?
- Não. O método é neutro em relação à ferramenta; cada artefato é um arquivo, um teste ou um script. O Forge automatiza as comportas e a injeção de prompts, mas o degrau existe sem o Forge. O NAC3 é o meio com que hoje conseguimos a testabilidade de tela, não uma condição.
- Por que os prompts estão em inglês se a documentação está no meu idioma?
- Porque os modelos seguem instruções com mais precisão e menos tokens em inglês. Cada prompt é uma única peça idêntica nas oito versões, explicada no seu idioma abaixo, e termina com "Reply in my language".
- Quanto demora um projeto pequeno de ponta a ponta?
- Não dou prazo, de propósito. O método é um processo para fazer sistemas operáveis e sustentáveis sem entender um bit de código; não é um processo para fazer sistemas mais rápido, mesmo que a velocidade apareça como consequência. O que o método fixa é a ordem e as comportas; quanto demora cada etapa é o tamanho e a complexidade do seu sistema que decidem.
- Como proponho uma melhoria?
- Com evidência: o degrau 15 pede que cada retrospectiva termine em uma proposta concreta de mudança na escada, com o incidente que a justifica. As propostas entram por pull request a partir de um fork em github.com/pkuschnirof/urazuke e eu as reviso antes de fundi-las.
Exija evidência. Não leia o código dele.
Um método para que o modelo construa e você decida e verifique. Em oito idiomas, com licença aberta, e com os tombos de três sistemas reais para que você não precise levar os mesmos.