# O código da IA vem "quase certo". A Síntese acha que o erro começa antes da primeira linha. > Planejar um sistema é a etapa que mais trava quem trabalha com agentes. O Blueprint tira esse peso: ele entrevista você, pesquisa, registra decisões e entrega a especificação, pronto para desenvolver. Por Erick Mendes · 15 de outubro de 2026 · Comunidade e open source, Inteligência Artificial, Ferramentas internas · 17 min de leitura Publicado em https://sinteselabs.com/artigos/o-codigo-da-ia-vem-quase-certo-a-sintese-acha-que-o-erro-comeca-antes-da-primeira-linha --- ### Resumo - O Blueprint leva uma ideia dita em linguagem natural até os requisitos e a um repositório pronto para desenvolver com agentes de código. É aberto (MIT), feito de arquivos Markdown, e não tem servidor, conta nem telemetria. - Ele existe por causa de dois problemas que o código não resolve. O primeiro é que agentes preenchem lacunas sozinhos quando você esquece de mencionar algo. O segundo é que o agente não aprende com os projetos que já viveu com você. - Acreditamos que criar software com IA não é sobre "vibecoding", é sobre arquitetura. Nesse sentido, o Blueprint foca no que a maioria das pessoas ignora: alinhar perfeitamente os requisitos antes de escrever qualquer linha de código. - A ferramenta roda com qualquer agente de código. - Repositório: [github.com/sinteselabs/Blueprint](https://github.com/sinteselabs/Blueprint) --- ## Onde o trabalho com agentes trava Na pesquisa de desenvolvedores do Stack Overflow de 2025, com 49 mil respostas de 160 países, 84% disseram que já usam ou pretendem usar IA no trabalho. No mesmo levantamento, a confiança na precisão dessas ferramentas caiu de 43% para 33%, 66% afirmaram que as respostas são *"quase certas, mas não totalmente"*, e 45% disseram que corrigir código gerado por IA leva mais tempo do que esperavam ([Tecnoblog](https://tecnoblog.net/noticias/mais-devs-usam-ia-no-trabalho-mas-nivel-de-confianca-cai-aponta-pesquisa/)). Essa pesquisa não tem recorte brasileiro. Em entrevista ao [Xataka Brasil](https://www.xataka.com.br/informatica/nosso-desafio-nao-e-tecnico-e-cultural-brasil-e-destaque-global-no-uso-do-copilot-ainda-precisa-vencer-a-barreira-da-delegacao-a-ia), um executivo do GitHub disse que o obstáculo no país é cultural: reaprender o ciclo de desenvolvimento, aprender a delegar, conferir o resultado e confiar numa IA como se confia em uma pessoa. > Nossa leitura é que boa parte desse "quase certo" nasce antes de existir código. O agente escreve rápido, e escreve com fidelidade àquilo que foi dito. **O problema é que o que foi dito quase nunca é o projeto inteiro.** ## Dois problemas que o código não resolve #### O plano que parece completo Qualquer pessoa consegue pedir à uma IA que escreva os requisitos de um sistema. O difícil é garantir que o documento seja fiel ao que a pessoa realmente quer. Isso falha por dois motivos que se somam. O primeiro é senioridade. Quem tem menos experiência não sabe quais perguntas fazer, nem reconhece quando um requisito ficou vago. O segundo é tempo. Mesmo quem sabe raramente consegue parar para pesquisar a fundo as opções de stack, os limites conhecidos das ferramentas e como projetos parecidos foram resolvidos. O resultado é um documento com cara de completo, em que a IA preencheu as lacunas com o que é provável** e não com o que a pessoa queria**. As perguntas que ninguém fez são as mais caras: o que fica fora da primeira versão, o que acontece quando algo falha, se existe dado pessoal, quem paga o quê. O agente responde essas perguntas sozinho e em silêncio, e as respostas viram arquitetura. #### O agente que não aprende com você O segundo problema é menos discutido mas, para mim, é igualmente importante. É difícil fazer uma IA aprender o seu jeito de trabalhar e guardar registros permanentes dos projetos que você desenvolve, de modo que esses registros melhorem o próprio método com que você planeja o projeto seguinte. Na prática,** cada projeto começa do zero**. Você explica de novo que prefere decisões de arquitetura recomendadas e não listadas, que já tem conta numa hospedagem, que da última vez o banco escolhido pausava sem uso. Troca de agente, troca de máquina, e a conversa em que tudo isso foi dito não existe mais. O que o projeto aprendeu fica preso numa sessão que acabou. A Síntese é um venture studio com uma comunidade tech própria. Desenvolvemos produtos e startups nossos e também software sob medida, e isso significa pessoas de perfis diferentes entrando em projetos diferentes, cada uma com o seu agente e o seu jeito. Para a gente, **o que um projeto ensinou precisa sobreviver ao projeto**, sem exigir que alguém se lembre de copiar manualmente. ## Engenharia de requisitos, a parte que todo mundo quer pular A engenharia de requisitos é uma das partes mais difíceis e mais chatas da análise e projeto de sistemas. Difícil porque exige tirar da cabeça de alguém, em palavras, algo que muitas vezes ainda não está claro nem para ela. Chata porque é trabalho de perguntar, escrever, conferir e reescrever, longe da parte que dá satisfação imediata, que é ver o sistema rodando. Por isso é a etapa mais pulada, e a que mais cobra depois. O Blueprint foi pensado para facilitar essa passagem. Ele conduz a entrevista, faz as perguntas que uma pessoa com menos tempo ou menos experiência talvez não fizesse, pesquisa as opções enquanto você responde e registra tudo em documentos que você pode conferir. O que antes dependia da disciplina de cada um passa a ter um caminho. Achamos que isso importa para o desenvolvimento com agentes por uma razão de postura. Uma coisa é descrever o que se quer e aceitar o que vier, o que é o vibecoding e funciona bem para explorar uma ideia ou montar um protótipo. Outra é tratar o trabalho com agentes como engenharia de software assistida por IA: requisitos escritos, decisões registradas com o motivo, arquitetura, um plano com especificação por tarefa e uma forma de testar cada entrega. A IA acelera cada uma dessas etapas, mas as etapas continuam existindo — e **as escolhas caras de desfazer continuam sendo da pessoa**. A objeção mais honesta a esse caminho vem de quem o testou. Birgitta Böckeler, da Thoughtworks, ao experimentar ferramentas de desenvolvimento guiado por especificação, escreveu: > “To be honest, I’d rather review code than all these markdown files.” E disse que achou o volume exagerado para um bug pequeno ([Martin Fowler](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html), 2025). Entendemos o incômodo. Por isso, no Blueprint, uma mudança pequena vira uma tarefa com especificação, e ler os documentos nunca é obrigatório: o agente trabalha a partir deles, você lê o que quiser. Isso não é um julgamento sobre quem prefere um jeito ou outro. A diferença aparece quando o projeto precisa durar, passar por mais de uma pessoa ou chegar a um cliente. Nesse ponto, o que sustenta o resultado é o que foi pensado antes do código, e o que confirmamos é que um agente rende mais quando recebe um plano do que quando recebe um desejo. ## O que o Blueprint faz O Blueprint é a parte que vem antes do código, feita pelo agente que você já usa. Você diz o que quer, nas suas palavras. Ele entrevista, pesquisa enquanto você responde, escreve os documentos e entrega um repositório em que qualquer agente, em qualquer sessão, abre a pasta e sabe quais são as regras, qual é o plano e onde registrar o que fez. ```text VOCÊ o que você diz, nas suas palavras │ v SEU AGENTE DE CÓDIGO ◄────── as sete skills do Blueprint │ │ um bloco de perguntas por vez, pesquisa entre os blocos v ┌──────────────────────────────────────────────────────┐ │ docs/ requisitos, pesquisa, decisões, │ │ arquitetura, plano, specs │ │ .blueprint/ onde o projeto está, o diário │ │ AGENTS.md as regras, para a próxima sessão │ └──────────────────────────────────────────────────────┘ │ v DESENVOLVIMENTO, tarefa por tarefa, a partir do plano ``` Existe uma entrada só. A pessoa não precisa dizer se está começando, continuando, melhorando ou reorganizando algo. O agente olha a pasta e conclui, e diz o que concluiu. Há quatro pontos de partida: | Você tem | Você diz | O que acontece | | --- | --- | --- | | Só uma ideia | “quero começar um projeto novo” | Entrevista, pesquisa, documentos e repositório preparado | | Um projeto que passou pelo Blueprint e parou | “vamos continuar” | Lê o que existe e retoma da pergunta em que parou | | Um projeto existente e algo a acrescentar | “quero adicionar pagamentos” | Lê o código primeiro e especifica só a mudança | | Um projeto existente para reorganizar por dentro | “esse arquivo faz coisa demais” | Documenta o que existe, escreve o que precisa continuar funcionando e depois a mudança | Uma mudança pequena não vira documento. **Vira uma tarefa com a sua spec.** Essa entrevista que você passa tem cinco etapas: descrição do sistema, requisitos, modelagem, arquitetura e plano. Cada mensagem abre com uma linha dizendo onde a conversa está, por exemplo: *“Etapa 2 de 5 · Requisitos. Ficou decidido quem usa o sistema. Agora: o que cada um precisa conseguir fazer.”* Depois vem o que o agente entendeu da última resposta, em poucas linhas, e no máximo três perguntas sobre um assunto só. Mais pro final, há algo que eu acho particularmente interessante: todo projeto sai com seis documentos padrão (descrição do sistema, requisitos, pesquisa com fontes datadas, arquitetura, decisões com o motivo de cada uma e o plano com uma spec por tarefa) + outros documentos que aparecem conforme o tipo de projeto: fluxos e casos de uso, modelo de dados, classificação de dados, telas, contrato de interface, recursos de IA do produto, plano de testes ou playbooks por papel. ## Fidelidade: as decisões de desenho Gerar documento virou commodity. O que importa é se o plano reflete a intenção de quem idealizou, com cada escolha justificada. Essa é a ideia que organiza o Blueprint, e ela aparece em seis decisões. **O agente não inventa o que você não disse.** O que ele deduz e você não afirmou fica marcado como dedução. Uma dedução pequena, barata de mudar depois, ele decide, avisa em uma linha e oferece explicar. A pergunta que só você pode responder, ele faz. **Decisão cara de desfazer é sua.** Stack, arquitetura, hospedagem, tratamento de dado pessoal e qualquer coisa que gere custo de tempo e dinheiro são decisões em que mudar depois significa reescrever o que foi construído ou mover dados já guardados. Nesses casos o agente traz a pergunta em palavras simples, a recomendação primeiro com o motivo em uma linha, e de duas a quatro opções. Depois espera. Um exemplo, tirado da própria documentação no gihtub: > **1. Onde o site fica hospedado, junto com o banco de dados?** Trocar depois seria mover o site e as encomendas já guardadas. > Recomendo a **Cloudflare**: site e banco cabem num plano gratuito que não pausa. > Alternativas: > - **Supabase:** banco mais completo, mas o plano gratuito pausa depois de uma semana sem uso. > - **Firebase:** não pausa, mas o código de servidor exige o plano pago. Uma coisa que me esforcei pra deixar claro: **a recomendação segue o critério que a pessoa declarou**. Quem disse que não tem verba recebe, antes de tudo, o que tem plano gratuito. Se ela escolher contra a recomendação, a escolha dela é registrada e o agente não insiste. **A pesquisa tem fonte e data.** Antes de cada decisão cara, o agente pesquisa e lê as fontes na própria sessão, começando pela página oficial e pela página de preços, e diz a data de cada uma. Ferramentas mudam de nome, de limite e de preço, e um número lido de memória parece igual a um número lido hoje. Quando o agente não consegue pesquisar, ele diz que não conseguiu em vez de responder como se tivesse pesquisado, e o que ficou por conferir vira item do plano de testes. **Nada espera um “sim” e ninguém é obrigado a ler.** Uma etapa avança quando as perguntas principais dela foram respondidas. O documento é escrito naquele momento e o agente avisa em uma linha onde ele está. A pessoa só precisa revisar algo quando discorda. A razão é prática: um processo que exige a leitura integral de documentos longos a cada etapa termina com gente aprovando sem ler. **O estado é um arquivo.** O ponto em que o projeto está fica em `~/.blueprint/state.md`: o que foi respondido, o que foi decidido, o que está em aberto e qual é a próxima pergunta. Por isso a entrevista pode parar hoje e continuar amanhã, em outra máquina, com outro agente, sem repetir nenhuma pergunta. Quando o estado está atrasado em relação aos documentos, o agente diz o que falta, reconstrói marcando como reconstruído e só salva depois da confirmação. **Mudança pequena não vira cerimônia.** Num projeto preparado pelo Blueprint, o que cabe numa tarefa, não traz decisão cara e não revela fato novo sobre o projeto, o agente faz direto. O resto passa antes pela spec. Toda tarefa que o agente termina diz como testar: o que você roda ou abre, e o que deve ver. ## Memória que acompanha a pessoa Esse é o pedaço que responde ao segundo problema, e é também o que temos menos certeza de ter acertado. A regra é separar duas memórias. O que o Blueprint aprende sobre o projeto fica no projeto: o estado, o diário de sessões, os marcos e o registro de decisões, com a decisão, o motivo, as alternativas e as fontes. O que ele aprende sobre a pessoa e vale em qualquer projeto vai para uma pasta dela, `~/.blueprint/`, com dois arquivos. Um guarda como ela gosta de trabalhar, o que já usa e as lições do que deu errado. O outro tem uma linha por projeto que passou pelo Blueprint, com nome, caminho e data, e é o que permite ao agente achar um projeto que mora em outra pasta da máquina. Algumas regras mantêm isso honesto: - Ele pergunta uma vez, na primeira vez que há algo que vale guardar, e explica o que aprendeu e para onde iria. Se a resposta é não, nada é escrito fora do projeto e o aprendizado fica no diário. Tudo continua funcionando, só não atravessa para o projeto seguinte. - Sobe apenas o que é verdade em qualquer projeto. O que o sistema faz, seus requisitos, seus dados, nomes de pessoas atendidas e qualquer chave nunca saem do projeto. - Ele nunca escreve na memória própria do agente, como o `CLAUDE.md` da sua pasta pessoal. Aquilo pertence ao agente e a você, e o Blueprint não toca. No máximo oferece o texto para você colar, se quiser. - No início de um projeto novo ele lê a pasta e diz em uma linha o que está usando: “estou usando o que está na sua pasta: você segue as recomendações de arquitetura e usa Cloudflare”. O que você disser na conversa vale mais que a pasta, e então ele corrige a pasta. O limite desse desenho é conhecido: o que o agente escolhe escrever é um resumo, e a qualidade depende do que ele decide que vale guardar. Para quem trabalha em equipe, existe o [Lore](https://lore.lunico.dev), nossa ferramenta de memória de longo prazo compartilhada entre pessoas e agentes, que o Blueprint recomenda, mas não exige. Observabilidade segue a mesma lógica de nunca ser obrigatória. O diário do projeto é o padrão e funciona sem instalar nada. Uma ferramenta como *Langfuse*, por exemplo, entra quando o projeto justifica, e a página sobre isso no repositório diz também quando não compensa: projeto curto, uma pessoa só, ou quem trabalha por um chat no navegador, onde nenhum registro alcança o que o agente fez. A maior parte das pessoas nunca ouviu falar da ferramenta, então a página existe para que dê para decidir com ela na mão. ## Como testamos Uma skill é um texto que um agente segue, e **a única prova de que funciona é uma sessão de verdade**. Por isso o repositório tem doze testes que sobem um agente real numa pasta descartável, conduzem a conversa com uma pessoa simulada por roteiro e depois conferem o que ficou em disco. Eles cobrem a entrada em cinco situações (pasta vazia, pasta com estado, pasta com código, projeto parecido ao lado e sem acesso às pastas em volta), a entrevista inteira, a retomada de um projeto parado, a pesquisa, a decisão, o preparo do repositório, a memória pessoal e os três caminhos de mudança em projeto existente: mudança pequena, melhoria e reorganização. Uma entrevista completa nesse teste leva por volta de catorze minutos de agente e menos de quatro dólares a preço de API. A CLI tem 41 testes próprios, que rodam em Windows, macOS e Linux, com Node 22 e 24, e há verificações automáticas de links, de estrutura das skills e do formato do estado. Nos outros agentes a medição foi dividida pelo que cada um permite. No Codex, o agente achou sozinho a skill de entrada, disse em que etapa estava e continuou um projeto começado no Claude Code a partir da pergunta que o estado marcava como a próxima. No Antigravity CLI, medimos que as sete skills são descobertas onde a nossa CLI as instala. Foi ali que aprendemos algo que muda a forma como preparamos um repositório: ele lê o `GEMINI.md` e não abre o `AGENTS.md`. Por isso a CLI e a skill de preparo escrevem os dois arquivos, e a verificação do projeto reclama se algum deles não apontar para as regras. Um turno completo com modelo nesse agente ainda não foi medido. Em uso real, uma entrevista leva em torno de **44 minutos**, já com as rodadas de ajuste. Medimos no *Langfuse *que um projeto inteiro, do plano ao código, passa de 500 milhões de tokens em média, e é nessa escala que registrar o porquê de cada decisão deixa de ser capricho: sem o registro, o agente reabre perguntas que já foram respondidas e gasta contexto para descobrir de novo o que o projeto já sabia. O próprio Blueprint foi especificada seguindo o caminho que hoje ela conduz: descrição do sistema, requisitos, modelagem, arquitetura e plano, com as decisões e a pesquisa registradas. ## O que ele não faz Vale dizer com clareza: a ferramenta não é uma solução para tudo. - **Não escreve o código.** O Blueprint para no plano e no repositório preparado. Desenvolver é com o seu agente, tarefa por tarefa. - **Não garante que o agente vai seguir o plano.** O arquivo de entrada, a spec com a definição de pronto e o “como testar” ajudam muito, mas continuam sendo instruções em texto, e agentes ignoram instrução às vezes. - **Ainda não mede fidelidade com um número.** Vale acumular uma quantidade maior de uso real e medir para cada um a taxa de aceite que um desenvolvedor tem sobre as recomendações do agente. - **É neutro quanto a país.** O documento de classificação de dados só nomeia a lei quando se sabe qual é e, caso contrário, diz que a lei não foi conferida. Para quem trabalha no Brasil, adaptar esse documento à LGPD é uma contribuição que faria muita diferença. - **Por enquanto, funciona melhor no Claude Code**, que é onde foi desenvolvido e medido mais a fundo. ## Por que deixamos livre O Blueprint é uma **ferramenta aberta**. A licença é MIT, não há servidor nem conta, e o projeto de quem usa nunca sai da máquina por causa dele. Instalar não executa nada: o plugin carrega skills, não hooks nem servidores, e o único script do produto é a verificação do projeto, que só lê. Fizemos assim por três razões. A primeira é de convicção. Eu acredito que a diferença entre quem tira proveito de agentes de código e quem apenas gera código rápido está em planejar bem, e planejar bem é um conhecimento que hoje fica concentrado em quem tem anos de estrada. Uma ferramenta que faz o papel de sênior para quem está começando, na língua da pessoa, vale mais aberta do que fechada. A entrevista acontece no idioma de quem usa, e os arquivos da ferramenta ficam em inglês para qualquer agente ler (o motivo é economia de tokens de leitura). A segunda é prática. A Síntese reúne uma comunidade de engenheiros, desenvolvedores, analistas, designers e gestores de produto que entram em projetos reais. Quem está nessa comunidade vive exatamente a situação que descrevemos no começo, e uma ferramenta que a comunidade usa e critica melhora mais rápido do que uma que a gente testa sozinho. A terceira é o que ainda não sabemos. Os testes que fizemos mostram que o desenho se sustenta. Eles não mostram o que acontece quando o Blueprint encontra o hábito, a pressa e a teimosia de quem trabalha de verdade. **Como contribuir****.** O repositório aceita issues e pull requests, e a revisão é nossa. A contribuição mais útil é uma execução que deu errado: o que você pediu, o que o agente fez e o que você esperava no lugar. E se você quer fazer parte de uma comunidade que constrói produtos e aprende fazendo, a candidatura é em [sinteselabs.com/comunidade](https://sinteselabs.com/comunidade). ## Como começar São quatro caminhos, e todos entregam as mesmas **sete skills**. ```bash # 1. Claude Code, pelo terminal claude plugin marketplace add sinteselabs/Blueprint claude plugin install blueprint@sinteselabs # 2. claude.ai, app desktop e Cowork: # Customize → Plugins → Add → Add marketplace → sinteselabs/Blueprint # 3. Pelo instalador de skills do seu agente npx skills add https://github.com/sinteselabs/Blueprint # 4. A CLI, numa pasta de projeto (Node 22 ou mais novo, sem dependências) npx blueprintlabs init ``` Depois, abra o seu agente na pasta e diga o que quer fazer. A CLI nunca sobrescreve um arquivo que já existe, tem `--dry-run` para mostrar o que faria sem escrever, e o `update` mexe apenas nos arquivos do próprio Blueprint que você não editou. Seus documentos, seu estado e seu diário nunca são tocados. --- **Fontes** - Tecnoblog, [Mais devs usam IA no trabalho, mas nível de confiança cai, aponta pesquisa](https://tecnoblog.net/noticias/mais-devs-usam-ia-no-trabalho-mas-nivel-de-confianca-cai-aponta-pesquisa/), sobre a pesquisa de desenvolvedores do Stack Overflow de 2025. - Xataka Brasil, [Nosso desafio não é técnico, é cultural](https://www.xataka.com.br/informatica/nosso-desafio-nao-e-tecnico-e-cultural-brasil-e-destaque-global-no-uso-do-copilot-ainda-precisa-vencer-a-barreira-da-delegacao-a-ia). - Birgitta Böckeler, [Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html), em martinfowler.com, 2025. - [Agent Skills](https://agentskills.io), o formato aberto em que as skills do Blueprint são escritas. - Repositório do Blueprint: README, `AGENTS.md`, `tooling/README.md` e a página de observabilidade em `skills/blueprint-setup/references/`. --- Síntese Labs · https://sinteselabs.com/artigos/o-codigo-da-ia-vem-quase-certo-a-sintese-acha-que-o-erro-comeca-antes-da-primeira-linha