Decisões
ORG-0027 — Nada inventado; na dúvida, pergunte
- Status: aceita (2026-10-28, pelo mantenedor)
- Data: 2026-10-28
- Decide: o agente só escreve o que tem fonte; o que falta, ou a convenção que ainda não existe, ele pergunta ao mantenedor antes de seguir
- Complementa: ORG-0007, que diz o que é só do mantenedor
Contexto
Um agente de IA preenche lacunas com o que parece plausível: um número de versão, uma data, um nome de arquivo, um formato de texto, o resultado de um comando que não rodou. O valor inventado tem a mesma aparência do valor conferido, e por isso passa pela revisão. Quem lê depois não sabe o que foi decidido e o que foi suposto.
Isso já aconteceu aqui: o site da arquitetura publicou Versão 0.4.0-em-construcao, um sufixo que
nenhum documento decidia. O capítulo 14 já dizia o formato certo, o commit da imagem; o agente
não perguntou e inventou um rótulo.
A ORG-0007 diz o que só o mantenedor faz (Git de escrita, deploy, infraestrutura, segredos). Ela não diz o que o agente faz quando lhe falta uma informação.
Decisão
- Toda informação escrita tem fonte. Número, versão, data, nome, identificador, rótulo, formato, comando, resultado ou fato só entra num arquivo, numa resposta ou numa entrega quando vem do repositório, de uma fonte conferida (documentação oficial, a saída de um comando que rodou) ou do mantenedor.
- Na dúvida, o agente pergunta antes de seguir. Quando a informação falta, é ambígua ou contradiz outra, ou quando a convenção ainda não existe (um sufixo de versão, um formato de texto, um nome), ele para e pergunta ao mantenedor. Ele não completa com um valor plausível nem escolhe a convenção sozinho: isso é decisão do mantenedor.
- O que não foi conferido se diz. Uma entrega separa o que foi verificado do que não foi: um teste que não rodou, uma tela que não foi vista, um valor estimado. Nada é relatado como feito ou verdadeiro sem ter sido.
- Exemplo é exemplo. Valores ilustrativos (
3f9c2e1,atendimento,<VALOR>) são permitidos em documentação e testes quando o texto os apresenta como exemplo ou quando são placeholders. - A regra mora no
AGENTS.md, entre as regras invioláveis, como as da ORG-0007.
Alternativas consideradas
| Alternativa | Por que não |
|---|---|
| Confiar na revisão do mantenedor | Por que não: o valor inventado tem a mesma aparência do conferido; a revisão só pega o que já desconfia |
| Um item novo na ORG-0007 | Por que não: a ORG-0007 está aceita; uma decisão nova vira ORG nova, que a complementa |
| Deixar cada stack escrever a sua regra | Por que não: é uma regra de comportamento do agente, igual em toda stack; escrita em cada uma, sairia diferente em cada uma |
Consequências
- O agente pergunta mais, sobretudo no começo de uma stack, quando as convenções ainda não existem.
- O que ele escreve passa a ter origem rastreável, e a revisão pode se concentrar nas decisões.
- Uma convenção que o agente perguntou e o mantenedor decidiu vira texto (uma ADR, um documento, o
AGENTS.md), para não ser perguntada de novo.
Mais
O detalhe está na documentação da arquitetura.