Estou fazendo commit de especificações em coreano no lugar de código — app PWA + servidor em 3 documentos de especificação

Enquanto mandava a IA programar, havia uma coisa que continuava me incomodando. O código resultante fica, mas a conversa e a intenção que geraram esse código desaparecem. Três meses depois, não há a quem perguntar: "por que este código está assim?"

Então inverti a direção. A ideia é fazer commit no git das especificações com a intenção embutida e tratar o código como artefato de build. Como teste, criei e publiquei um app pequeno do início ao fim.

É um PWA chamado Rimlog, no qual a IA conecta anotações antigas a registros de leitura e estudo. Não há servidor, não há cadastro, e os dados ficam apenas no navegador.

O app é comum. O que quero compartilhar é a forma como ele foi feito.

Método

Na pasta eux/ do repositório, há 3 documentos de especificação em coreano. Todo o esqueleto do app tem 40 linhas, o widget de cartões de IA tem 25 linhas, e o servidor de insights cabe em um documento. Eles são compostos por frases assim.

saveCapture : salvar formulário de captura (nome da fonte·citação·meu pensamento·tags) — inserir no início de captures + refletir no local storage + toast "salvo" + mudar para a aba de registros.

Se você colocar esse arquivo em uma ferramenta chamada EstreUX, o código é gerado (isso é chamado de brew). O código gerado recebe o hash da especificação, e se você alterar só a especificação ou só o código, o commit é bloqueado no pre-commit. A ideia é bloquear por meio desse gate o problema de a especificação virar mentira no momento em que fica desatualizada.

Também medi isso numericamente. Fiz uma medição real revertendo um teclado numérico de 152 linhas que já existia no framework para uma especificação de 28 linhas, e a quantidade de linhas mantidas por humanos caiu de 60% a 82%. O código gerado em si às vezes fica maior que o original. O que diminui é a parte que humanos precisam ler e modificar. O registro de medições está no repositório.

O servidor também é um único documento de especificação

A demo no Pages é serverless, então a IA ajuda apenas com fallback de sobreposição de tags. Para fazê-lo funcionar de verdade, adicionei um servidor self-hosted, e isso também é um único arquivo Node sem dependências, gerado por brew a partir de um documento de especificação. É possível escolher o backend.

• nvidia (padrão): é a API gratuita do build.nvidia.com. Ela fornece chave sem exigir cadastro de cartão e, sendo algo como 40 chamadas por minuto em modo compatível com OpenAI, é mais do que suficiente para um diário pessoal
• claude-cli / codex-cli: a cada requisição, chama claude -p / codex exec como processo filho. É um caminho para reaproveitar a assinatura do Claude/ChatGPT que você já paga, sem usar chave de API
• openai / google: apenas proxy de chave

As chaves e a autenticação ficam apenas no servidor e não vão para o navegador.

Pontos dos quais ainda não tenho certeza

Estou expandindo o julgamento de consistência entre especificação ↔ código, indo além de diff estático para inspeções dinâmicas baseadas em propriedades, mas a calibração dos pesos ainda não está pronta. Também encontrei uma classe de falso positivo em que a renderização do framework, em ambiente DOM headless, se comporta de forma diferente do navegador real; por isso, elevar o ambiente de validação para um navegador real também ficou como tarefa. Se você olhar o histórico de commits desde o início, verá em sequência o processo de scaffold → especificação → geração → refinamento.

• Ao vivo: https://soliestre.github.io/Rimlog/
• Repositório: https://github.com/SoliEstre/Rimlog
• Registro de build (detalhado): https://estreui.tistory.com/5

Tenho curiosidade sobre duas coisas. Qual vocês acham que é a armadilha de usar a especificação como SSoT? Em especial, gostaria de saber em que ponto vocês encontraram situações em que a expressividade da especificação não consegue acompanhar o código. E, quanto ao caminho de reaproveitar assinatura usando claude -p como backend do app, o que pode pegar no uso real (do ponto de vista de taxa, termos de uso e latência)?