yongol — A quilha do SaaS codificado com IA

O 200º endpoint

Você constrói um SaaS com vibe coding. No começo é rápido. 5 tabelas, 12 endpoints — vinte minutos e funciona.

Mas depois de 50 endpoints, algo estranho acontece. A IA produz hoje um padrão que contradiz o de ontem. Depois de 100, funcionalidades existentes quebram silenciosamente. Depois de 200, adicionar uma única funcionalidade custa 10x o que custaram as primeiras dez.

Não é que o modelo seja burro.

Decisões e implementação

Três coisas estão entrelaçadas no código-fonte:

Decisões do usuário — esta coluna é BIGINT, este endpoint é somente para o proprietário, a paginação é por cursor.
Lógica de negócios — precificação, fluxos de trabalho, regras de ciclo de vida.
Detalhes de implementação — nomes de variáveis, ordem de chamadas de biblioteca, encapsulamento de erros.

Quando a IA lê este código, não consegue distinguir qual linha é uma decisão e qual é um detalhe. Então, quando “refatora” ou “limpa”, sobrescreve silenciosamente decisões que confundiu com detalhes. O usuário só percebe quando o comportamento já está errado.

É por isso que o vibe coding colapsa em 200 endpoints. Um modelo maior não resolve. O meio — código bruto — simplesmente não preserva decisões. Todo modelo acaba batendo no mesmo muro.

A quilha

A quilha é o primeiro osso colocado ao construir um navio. Sustenta o peso do casco, previne a oscilação lateral, e toda outra estrutura é construída sobre ela. Um navio sem quilha flutua em águas calmas, mas se deforma quando as ondas chegam.

Um SaaS construído com vibe coding é igual. Flutua quando é pequeno. Deforma quando cresce.

yongol é a quilha do SaaS codificado com IA.

Tirar as decisões do código

O núcleo do yongol é simples. Separar decisões do código.

Dez especificações declarativas (SSOTs) lidam cada uma com uma única preocupação:

SSOT	Preocupação
features.yaml	Catálogo de funcionalidades — o que construir
manifest.yaml	Configuração do projeto — autenticação, middleware, infraestrutura
OpenAPI	Contrato de API — rotas, parâmetros, respostas
SQL DDL + sqlc	Modelo de dados — tabelas, colunas, restrições, consultas
SSaC	Fluxo de serviço — sequência de decisões dentro de um endpoint
Rego	Autorização — quem pode fazer o quê
Mermaid stateDiagram	Transições de estado — ciclos de vida de entidades
FuncSpec	Funções customizadas — lógica que não pode ser expressa como CRUD
Hurl	Cenários de teste — verificação em tempo de execução
STML	Frontend — estrutura de página e vinculação de dados

Oito das dez são padrões da indústria (OpenAPI, SQL, sqlc, Rego, Mermaid, Hurl, YAML). Apenas SSaC e STML são DSLs criadas pelo yongol. O que a IA precisa aprender do zero é minimizado.

Cada SSOT contém apenas decisões. Sem detalhes de implementação. A IA edita os SSOTs; yongol generate renderiza código a partir deles. Decisões vivem permanentemente nos SSOTs; o código é uma projeção descartável.

Impondo consistência

Decisões estão agora espalhadas por dez arquivos, então contradições podem surgir. DDL diz BIGINT mas OpenAPI diz string? SSaC declara @auth mas Rego não tem regra correspondente? O diagrama de estados tem uma transição mas SSaC não tem função correspondente?

Um SSOT contraditório é uma decisão corrompida. Por mais limpo que o código esteja, se as decisões se contradizem, o comportamento está errado.

yongol validate captura isso.

✓ manifest        ✓ openapi_ddl       ✓ ssac_rego
✓ openapi         ✓ openapi_ssac      ✓ ssac_authz
✓ ddl             ✓ hurl_openapi      ✓ ssac_sqlc
✓ query           ✓ hurl_statemachine ✓ ddl_statemachine
✓ ssac            ✓ hurl_manifest     ✓ ddl_rego
✓ statemachine    ✓ openapi_manifest  ✓ rego_manifest
✓ rego            ✓ ssac_ddl          ✓ stml_openapi
✓ hurl            ✓ ssac_statemachine
✓ funcspec        ✓ ssac_func

0 errors, 0 warnings

Primeiro valida cada SSOT individualmente, depois executa verificações cruzadas entre camadas. ~287 regras inspecionam cada referência simbólica entre todos os dez SSOTs. Se existir uma única contradição, a compilação é recusada.

A IA escreve livremente. Saia dos trilhos e validate captura instantaneamente. Liberdade nos trilhos.

operationId é a pedra angular

Como unir dez camadas? Com um único identificador PascalCase.

Digite o operationId ExecuteWorkflow:

── Feature Chain: ExecuteWorkflow ──

  OpenAPI    api/openapi.yaml                POST /workflows/{id}/execute
  SSaC       service/workflow/execute_workflow.ssac   @get @empty @auth @state @call @publish @response
  DDL        db/workflows.sql                CREATE TABLE workflows
  DDL        db/execution_logs.sql           CREATE TABLE execution_logs
  Rego       policy/authz.rego               resource: workflow
  StateDiag  states/workflow.md              diagram: workflow → ExecuteWorkflow
  FuncSpec   func/billing/check_credits.go   @func billing.CheckCredits
  FuncSpec   func/billing/deduct_credit.go   @func billing.DeductCredit
  FuncSpec   func/worker/process_actions.go  @func worker.ProcessActions
  FuncSpec   func/webhook/deliver.go         @func webhook.Deliver
  Hurl       tests/scenario-happy-path.hurl  scenario: scenario-happy-path.hurl

Da especificação de API ao esquema de banco de dados, das políticas de autorização às transições de estado, das implementações de funções aos cenários de teste — a topologia completa de uma funcionalidade em uma tela. Dezenas de greps substituídos por um comando.

operationId é a pedra angular porque em uma aplicação full-stack, a unidade de uma funcionalidade é o endpoint de API. O usuário pressiona um botão, uma API é chamada, e essa API atravessa todas as outras camadas. Um nome encadeia fisicamente dez camadas.

Benchmark: ZenFlow

ZenFlow — um SaaS de automação de fluxos de trabalho multi-tenant. Claude Sonnet 4.6 escreveu os SSOTs; yongol os validou.

Etapa	Descrição	Tempo	Acumulado
Build inicial	multi-tenant, auth, máquina de estados, 6 tabelas, 10 endpoints	23 min	23 min
+ Versionamento	clone de workflow, lista de versões, cópia de ações INSERT…SELECT	16 min	39 min
+ Webhooks	publicação de eventos, CRUD de webhooks, backend de fila	8 min	47 min
+ Marketplace de templates	paginação por cursor, clone cross-org, endpoints públicos	7 min	54 min
+ Anexos de arquivo	relatórios de execução, backend de arquivos	7 min	61 min
+ Agendamento	cron baseado em sessão, TTL	10 min	71 min
+ Logs de auditoria	backend de cache, paginação, filtros	6 min	77 min
+ Dashboard	API agregada, joins relacionais, views de detalhe	14 min	91 min
+ Operações em lote	salvamento em massa, serialização JSON	10 min	101 min
+ API externa	importação de API de geocodificação, armazenamento de coordenadas	14 min	115 min
+ Atualização condicional	auto-atribuição, pontuação de confiança, ramificação condicional	16 min	131 min

Final: 30 endpoints, 12 tabelas, 64 requisições de teste. Tudo verde.

Dez funcionalidades adicionadas sequencialmente. Adicionar funcionalidades nunca desacelerou. Testes existentes nunca quebraram. O muro dos 200 endpoints não existiu.

Executando a mesma especificação com Opus: 30 endpoints, 73 requisições de teste, ~76 min. O modelo muda, os trilhos permanecem os mesmos.

Por que um modelo maior não é a resposta

“GPT-6 vai resolver isso.”

Não vai. O problema não é a inteligência do modelo — é o meio.

Código como meio não distingue decisões de implementação. Qualquer modelo que leia código vê texto onde decisões e detalhes estão entrelaçados. Por mais inteligente que o modelo seja, se o meio não fornece a distinção, o modelo não pode fazê-la.

yongol muda o meio. Move o que a IA edita do código para especificações declarativas. Como as especificações contêm apenas decisões sem detalhes de implementação, a IA nunca confunde uma decisão com um detalhe. A sobrevivência das decisões se torna independente do tamanho do modelo.

Um LLM pequeno editando apenas SSOTs, com validate fornecendo feedback preciso a cada erro, pode manter a mesma integridade de decisões que um modelo muito maior editando código bruto. yongol preenche essa lacuna.

Comece

npx skills add park-jun-woo/yongol

Instale o skill yongol no seu agente de IA (Claude Code, Cursor, Copilot e outros). O agente aprende o fluxo de trabalho na instalação.

Para usar o CLI diretamente:

go install github.com/park-jun-woo/yongol/cmd/yongol@latest

git clone https://github.com/park-jun-woo/yongol && cd yongol
yongol validate examples/zenflow

0 errors, 0 warnings.

Aponte uma IA para essas especificações e peça para adicionar uma funcionalidade. validate coloca os trilhos; a IA corre neles. Não há muro.