Por que o Eidos existe

O problema

Pergunte a um time o que ele está construindo e você recebe quatro respostas, nenhuma escrita em um só lugar.

O ticket que descrevia a funcionalidade fechou dezoito meses atrás, e a descrição dele foi escrita para justificar um sprint, não para descrever um produto. A página do wiki era exata na semana em que foi escrita. A decisão sobre por que não se cobre um caso foi tomada verbalmente, e a única pessoa que se lembra dela foi embora. O código te diz o que a coisa faz hoje, mas não o que ela deve ser, nem quais dos seus comportamentos atuais são promessas e quais são acidentes.

Então a resposta honesta para “o que essa coisa deveria ser?” é uma reunião.

Por que os tickets não conseguem sustentar isso

O instinto é recorrer ao rastreador, porque é onde o time já vive. Não funciona, e a razão é estrutural, não cultural.

Uma tarefa descreve trabalho. Ela tem começo e fim, uma pessoa designada, uma estimativa e um estado que vai de aberto a fechado. Todo o propósito dela é deixar de ser relevante. Quando o trabalho é entregue, o ticket está pronto, e tudo o que ele por acaso registrava sobre o produto vence no mesmo instante, porque ninguém mais está olhando.

Um Blueprint descreve a coisa. Ele não tem fim. É escrito antes de o trabalho começar, corrigido enquanto o trabalho acontece e continua sendo a descrição exata muito depois. A exatidão dele não está presa a um estado.

Essa é a razão de o Eidos proibir de saída os campos de acompanhamento de trabalho. Nada de sprint, estimate ou assignee. No momento em que você os acrescenta, um Blueprint vira uma tarefa e começa a apodrecer no mesmo calendário. Conecte com o seu rastreador por meio de um link.

O que o Eidos faz a respeito

Ele mantém a resposta autorizada para “o que é esta coisa” como markdown versionado, no repositório, revisado em pull requests ao lado do código que ela descreve.

Essa escolha de local faz quase todo o trabalho:

Está ao lado do código, então está diante das pessoas que, do contrário, adivinhariam.
Está no git, então cada mudança tem autor, data, diff e motivo, e o Eidos se apoia nesse histórico em vez de inventar a sua própria trilha de auditoria.
É revisado em PRs, então uma mudança no que o produto é recebe o mesmo escrutínio que uma mudança no que ele faz.
É markdown simples, então uma pessoa o lê num editor, numa página web ou num vault do Obsidian, e um agente de código lê exatamente o mesmo arquivo.

Esse último ponto não é acidental. Humanos e agentes lendo duas fontes de verdade diferentes é como o desvio começa. Aqui eles leem o mesmo arquivo.

O laço que dá razão a si mesmo

Esta é a razão de o padrão ser construído do jeito que é, e vale dizer sem rodeios.

Uma spec existe para ser uma checagem do código. É a declaração independente do que a coisa deveria ser, e todo o valor dela está em vir de um lugar diferente da implementação.

Agora deixe um agente escrever as duas.

Ele escreve a spec. Escreve código que satisfaz a spec. Perguntado se o código está certo, ele confere o código contra a spec que ele mesmo escreveu. Tudo concorda. Toda revisão passa. Nada foi verificado: você tem dois artefatos que se corroboram mutuamente, e nenhum deles foi jamais medido contra a intenção de alguém.

A falha é silenciosa, que é o que a torna cara. Uma spec gerada não parece gerada. Ela tem um parágrafo de intenção, critérios de aceitação plausíveis e uma seção de não-objetivos com três entradas razoáveis, e nenhum autor. Ela se lê como algo resolvido enquanto ninguém decidiu nada, e carrega a autoridade de estar escrita, versionada e revisada em um pull request.

Seis meses depois alguém constrói contra o AC4, e a resposta honesta para “quem decidiu isso?” é ninguém.

Então a decisão humana não é um detalhe bonito no Eidos, nem uma etapa a ser automatizada quando o tooling melhorar. Ela é o elemento estrutural inteiro. Uma spec vale exatamente tanta intenção humana quanto foi colocada nela, e uma spec sem nenhuma é pior do que spec nenhuma, porque a versão que estava na cabeça de alguém pelo menos era sabidamente pouco confiável.

Quando não usar o Eidos

O corolário é direto, e é mais útil do que outra funcionalidade seria:

Isso não é uma crítica a trabalhar assim. Para um protótipo, algo descartável ou uma coisa cujo único requisito é funcionar, é a decisão certa, e a resposta honesta é que uma camada de specs seria teatro.

O Eidos é para o caso em que alguém responde pelo que a coisa é. Onde uma pessoa tem que dar a cara por uma decisão de escopo, defender uma fronteira ou explicar daqui a um ano por que aquilo não cobre um caso que alguém supõe que cobre. Se ninguém está nesse assento, o padrão não tem em que se segurar.

O que ele não é

Não é um gerador de documentação. Nada é derivado do seu código. Um Blueprint é escrito por uma pessoa que decidiu alguma coisa.

Não é um modelo que você preenche. O padrão diz claramente: se um Blueprint se lê como um modelo preenchido, remodele-o até que se leia como algo que alguém escreveu. O shape é um andaime para um documento vivo, não um formulário.

Não é um produto que um agente escreve por você. A pessoa escreve; o agente facilita. Veja Trabalhando com agentes: isto é uma restrição de design, não uma limitação esperando para ser removida.

Não é um esquema rígido. O Eidos não nomeia nenhuma coleção, nenhum shape e nenhuma seção. Ele define a máquina (coleções, shapes, flavors, propriedades) e o seu Framework nomeia todo o resto. Um Framework que não se parece com nenhuma das sementes distribuídas está funcionando como deveria.

Quem o sustenta

Uma pessoa: o Framework Owner. Ela sustenta a intenção, o escopo e as decisões.

Esta é a parte menos técnica e mais estrutural do Eidos. Uma raiz sem dono vira um wiki com formatação melhor: todo mundo edita, ninguém decide, e a seção de não-objetivos se esvazia em silêncio porque dizer não é a parte que exige autoridade.

A seguir

Início rápido: coloque uma raiz em disco.
Framework e Blueprint: as duas palavras sobre as quais todo o padrão gira.