Vibe coding é divertido, rápido e, sinceramente, uma das melhores formas de ganhar ritmo. Eu também uso.

Mas quando passamos da exploração para produção, apenas o ritmo não é suficiente. Se ignorarmos o loop de feedback, vamos pagar depois com retrabalho, incompatibilidades de versão, falhas de segurança e deriva de arquitetura.

Este artigo é um guia prático para um público diverso: engenheiros, tech leads e profissionais de produto que colaboram na entrega de software assistida por IA.

Os exemplos ao longo do texto usam Angular e Java/Spring porque essa é a minha stack principal. O ciclo em si se aplica a qualquer framework, linguagem ou plataforma — problemas como divergência de versões e escolhas padrão inadequadas acontecem em todos os lugares.A Ideia Central

A proposta não é abandonar o vibe coding.

A proposta é colocar controle de engenharia ao redor dele, permitindo manter a velocidade sem abrir mão da qualidade.

Encare assim:

• Vibe coding é excelente para descoberta e prototipação rápida
• Loops de feedback baseados em especificações são fundamentais em produção
• O melhor modelo não é escolher entre um ou outro, mas usar ambos de forma sequencial

Quando usar Vibe e quando usar Specs

Uma regra simples ajuda:

• Na fase inicial de descoberta: comece com vibe coding
• Em qualquer funcionalidade voltada ao usuário em produção: comece com specs
• Em migrações ou trabalho de plataforma: sempre valide versões e suporte explicitamente

Dessa forma, você mantém velocidade onde ela faz sentido e rigor onde ele é necessário.

Dois fluxos de trabalho, dois resultados

Fluxo A: Prompt direto para implementação

Fluxo comum:

• Solicitar à IA a criação do projeto
• Aceitar as configurações padrão
• Começar a desenvolver funcionalidades
• Descobrir problemas apenas na integração ou no release

Problemas frequentes:

• A versão do framework escolhida pela IA não segue o padrão do time
• Requisitos não funcionais ficam de fora (segurança, observabilidade, manutenção)
• A intenção do produto se perde porque o desenvolvimento começa sem clareza de design
• Equipes confundem código funcional com arquitetura correta

Fluxo B: Ciclo orientado por especificações

Fluxo estruturado:

• Definir intenção e restrições
• Criar um design técnico de alto nível
• Detalhar decisões de baixo nível
• Pedir à IA para implementar com base na especificação
• Validar versões, dependências, arquitetura e testes
• Usar o aprendizado na próxima iteração

Esse modelo continua ágil, mas evita surpresas custosas.

O que se diz vs o que acontece na prática

Discurso comum

• “É só melhorar o prompt”
• “A IA já é inteligente, pode entregar”
• “Depois a gente ajusta”

Realidade

• Bons prompts ajudam, mas não substituem design
• Código rápido não significa arquitetura correta
• Ajustar depois normalmente custa mais caro e leva mais tempo

Desenvolvimento corporativo vai além de gerar código

Um erro comum é tratar a geração de código como se fosse todo o processo.

Não é.

Desenvolver software envolve também:

• Validação
• Segurança
• Conformidade
• Operação
• Preparação para entrega

Em empresas, o código gerado precisa passar por várias validações antes de ir para produção:

• Regras de qualidade (como Sonar)
• Cobertura mínima de testes
• Testes de segurança (SAST)
• Testes mais avançados, como pentests
• Verificação de vulnerabilidades em dependências

Ou seja, escrever código é apenas uma parte do todo.

O papel do engenheiro está evoluindo

Se a IA escreve código, o que sobra para o engenheiro?

O foco deixa de ser digitar cada linha e passa a ser:

• Definir intenção
• Estabelecer restrições
• Revisar decisões técnicas
• Garantir qualidade
• Assumir responsabilidade pelo resultado

Quem aprova código gerado por IA é responsável por ele — da mesma forma que ao revisar código de um desenvolvedor júnior.

Isso não simplifica o trabalho. Torna mais exigente.

As habilidades continuam sendo essenciais:

• Arquitetura
• Debug
• Segurança
• Performance
• Conhecimento de negócio

A IA não substitui isso — ela amplifica.

Exemplo prático

Você pede para a IA criar um serviço com Spring Boot.

O sistema funciona, compila e passa nos testes.

Mas ao revisar, você percebe que a query foi feita com concatenação de strings, abrindo brecha para SQL Injection.

Se você tem conhecimento, detecta rápido.
Se não, isso pode ir para produção com uma falha crítica.

Essa é a diferença entre gerar código e fazer engenharia.

Por que produto também deve se preocupar

Isso não é só um tema técnico.

Sem especificação:

• O escopo muda constantemente
• Estimativas ficam imprecisas
• A confiança na entrega diminui
• Decisões são tomadas no código, não no planejamento

Com specs:

• A intenção do produto se mantém
• Decisões ficam claras
• Riscos aparecem cedo
• A IA trabalha alinhada ao negócio

Estimativas mais confiáveis

Um grande benefício desse modelo é melhorar estimativas.

Com specs claras, design definido e cenários de teste:

• Você entende o que será feito
• Sabe como as partes se conectam
• Enxerga os edge cases
• Define claramente o que significa “pronto”

Isso transforma estimar de um chute para um processo estruturado.

Antes de usar IA: configure o ambiente

O maior ganho vem antes do primeiro prompt:

Criar arquivos de instrução e skills no repositório.

Eles funcionam como regras que a IA segue automaticamente.

O que incluir:

• Política de versões
• Regras de testes
• Regras de dependência
• Padrões de arquitetura
• Convenções de código
• Diretrizes de segurança

Skills

São fluxos reutilizáveis que já carregam contexto.

Exemplo: uma skill de TDD já entende que precisa escrever testes antes de implementar.

O ciclo orientado por especificações

Passo 1: Definir intenção

• Problema
• Usuário
• Métricas
• Escopo
• Riscos

Passo 2: Design de alto nível

• Estrutura do sistema
• Componentes
• Fluxos
• Segurança
• Operação

Passo 3: Design detalhado

• APIs
• Modelos de dados
• Regras de erro
• Dependências
• Cenários de teste

Plano detalhado

Antes de codar, quebre em tarefas pequenas.

Isso ajuda a:

• Identificar erros cedo
• Melhorar revisão
• Evitar lacunas

Revisão antes de implementar

Revisar design antes de gerar código evita retrabalho.

Velocidade de geração não substitui qualidade de decisão.

Passo 4: Implementação com TDD

• Escrever testes
• Validar falha
• Implementar mínimo
• Testar
• Refatorar

Tipos de teste

• Unitário
• Integração
• End-to-end

Passo 5: Verificação

Validar:

• Versões
• Dependências
• Segurança
• Testes
• Arquitetura

Depois:

• Commits pequenos
• PRs organizados
• Iteração contínua

Exemplo real: Angular

Problema comum:

A IA gera uma versão antiga do Angular.
O time só percebe depois.

Por isso: Validação de versão deve acontecer antes de avançar no desenvolvimento.

# always check CLI and framework versions first
ng version

# generate project with latest version (example)
npx @angular/cli new my-app --routing --style=scss

# validate dependency tree and update recommendations
ng update

Exemplo com Spring Boot: padrão não significa certo para o seu contexto

Outro padrão comum:

O time pede para a IA gerar a estrutura de um projeto Spring Boot.
O resultado utiliza uma linha de versão que pode não estar alinhada com a política do time ou com as restrições da plataforma.
As verificações de compatibilidade acontecem tarde demais.

Um ponto importante:

“Spring Boot 3” não representa um único estado de ciclo de vida.

Algumas versões 3.x são mais antigas, enquanto a linha atual 3.5.x ainda possui suporte.
O Spring Boot 4.x já está disponível e continua evoluindo ativamente.

Assim como no caso do Angular, trate os números de versão aqui como exemplos de um momento específico e sempre confirme o status de suporte antes de avançar na implementação.

Portanto, a pergunta correta não é “3 ou 4?” isoladamente. A pergunta certa é:

Qual linha de versão suportada melhor se encaixa na nossa versão de Java, no ecossistema de dependências e no nosso orçamento de migração neste momento?

Lição principal: utilize canais oficiais de geração e documentação de suporte como fonte de verdade, e use a IA para acelerar os detalhes da implementação.

Exemplos de prompts que você pode reutilizar

Abaixo estão prompts práticos para cada etapa.

Prompt A: Especificação de intenção do produto

**Context:**
You are a product engineering assistant. You are helping a team prepare specification documents for feature development before any design or implementation work begins.

Feature idea:


**Objective:**
Produce a one-page product intent specification that aligns engineering and product teams on scope, success criteria, and constraints for this feature.

**Audience:**
Product managers, engineers, tech leads, and stakeholders making planning and prioritization decisions.

**Style:**
Structured. Numbered sections. Explicit, actionable language. Avoid ambiguity.

**Tone:**
Collaborative and clarifying. If information is missing or ambiguous, ask focused questions instead of making assumptions. Assume stakeholders want precision.

**Response:**
Deliver exactly these six sections in this order:
1) Problem statement (one paragraph)
2) Target users (bullet list)
3) Success metrics (specific, measurable)
4) Out of scope (explicit non-goals)
5) Risks and assumptions (potential blockers or dependencies)
6) Acceptance criteria in Given/When/Then format
   - Include happy path, validation/failure cases, and at least one edge case per criterion

**Context:**
You are a senior software architect designing solutions. You have reviewed the product intent spec and are now translating business requirements into system design.

Intent spec:


**Objective:**
Produce a high-level technical design that translates the product intent into architecture and system boundaries, without implementation details or code.

**Audience:**
Engineers, tech leads, and architects who will review this design and decide if it aligns with technical strategy and team capabilities.

**Style:**
Text-based diagrams and structured sections. Visual representations in ASCII or text form are preferred (not code). Annotate relationships and data flows clearly.

**Tone:**
Clear and architectural. Explain trade-offs between alternatives. Flag constraints or concerns early.

**Response:**
Deliver exactly these sections in this order:
- Architecture diagram in text form (ASCII or text-based visualization)
- Component responsibilities (what each major component owns)
- Data flow (how data moves between components)
- Security and observability requirements (non-functional needs)
- Key trade-offs and alternatives considered (why this design, not another)
- High-level test scenario map (happy path, failure paths, and edge-case families)

Do not generate implementation code or tests. Do not write code in any language.

**Context:**
You are a staff engineer preparing an implementation plan. You have the high-level design and must now specify concrete interfaces, data models, and version constraints so implementation work can be precise and testable.

High-level design:


**Objective:**
Produce a detailed low-level design and implementation plan that specifies what to build, version constraints, and test strategy — enabling unambiguous work assignments.

**Audience:**
Implementation engineers, QA, and architects who need to know exactly what to build and verify, including which versions are acceptable.

**Style:**
Detailed and concrete. Specify interfaces, data models, and error handling explicitly. Include specific version and dependency requirements.

**Tone:**
Precise. No ambiguity about version policy or technical decisions. Flag any gaps or assumptions.

**Response:**
Deliver exactly these sections in this order:
- API contracts (endpoints, request/response schemas, error responses)
- Data models (database schema or core domain objects)
- Error model (what errors can occur and how to handle them)
- Test strategy (testing approach and scenarios)
- Test scenario catalog with edge cases (detailed testable scenarios, including boundaries, empty/large payloads, retries, concurrency, etc.)
- Dependency/version policy (which versions of which dependencies are acceptable)

Version policy requirements must include:
- Angular: must be aligned with actively supported major versions
- Spring Boot: must use a currently supported release line and compatible Java version

**Context:**
You are a senior engineer working in strict test-driven development (TDD) mode. You have a low-level design and acceptance criteria. Tests must be written first, before any production code.

Low-level design:


Acceptance criteria:


**Objective:**
Write test files that directly correspond to the acceptance criteria and test scenarios. These tests will drive implementation. Do not write production code yet.

**Audience:**
Engineers who will run these tests immediately and implement code to make them pass.

**Style:**
Test code in the project's native test framework. One test per clearly named scenario. Include brief comments explaining what each test validates.

**Tone:**
Explicit. Each test must map to one acceptance criterion. Leave no ambiguity about what passes or fails.

**Response:**
Deliver:
- Test files (write actual test code using the project's test framework)
- One test per acceptance criterion, plus at least one edge case test per criterion
- Brief comments for each test explaining what it validates
- Commands to run the test suite

Imperative: Write tests only. Do not write any production code. Do not implement any features. Your output is test files only.

**Context:**
You are a senior engineer continuing strict TDD. Tests have been written and are currently failing. Your job is to write the minimal production code needed to make all tests pass — nothing more.

Low-level design:


Existing failing tests:


**Objective:**
Implement only the production code required to make all existing tests pass. Do not add features not covered by tests. Do not refactor unless tests fail.

**Audience:**
Engineers and code reviewers verifying that implementation matches the low-level design and test intentions.

**Style:**
Production code written in the project's native language. Follow existing code style and architecture conventions. Keep implementation focused and minimal.

**Tone:**
Strict. Only code that makes tests pass. No speculative features. If tests pass, you are done with this slice.

**Response:**
Deliver:
- Production code files (write implementation code only, no tests)
- Commands to run the existing tests (to verify they pass)
- Commands to verify framework/runtime versions (to confirm the environment)
- Assumptions checklist (what assumptions did you make? are they in the low-level design?)
- Expected test output summary (show which tests now pass)

Imperative: Do not modify the tests. Do not add features. Do not refactor. If the low-level design seems wrong, propose a design amendment instead of changing architecture.

Prompt F: Relatório de Verificação e Feedback

**Context:**
You are reviewing completed implementation against the low-level design spec. It is time to audit whether the work matches intent and identify gaps, risks, or compliance issues before release.

Spec:


Implementation summary:


**Objective:**
Produce a gap report that compares the implementation against the spec and identifies what matches, what is missing, what risks remain, and whether the work is production-ready.

**Audience:**
Engineers, tech leads, QA, and release managers deciding whether this work is ready to merge and ship.

**Style:**
Structured report with matrices, lists, and clear status indicators (met/partial/missing). Prioritize risks by severity.

**Tone:**
Critical and honest. Flag every gap and risk. Provide actionable remediation steps. Give a clear yes/no on production readiness.

**Response:**
Deliver exactly these sections in this order:
1) Compliance matrix (spec requirement → implementation status: met/partial/missing)
2) Version and dependency validation (are versions correct and supported?)
3) Risk list by severity (high/medium/low)
4) Suggested remediation steps (how to fix gaps before release)
5) Decision: ready for production? yes/no and why. If no, list the top 3 blockers.

De Prompts para Padrões Reutilizáveis de Time

Executar esses prompts manualmente como mensagens isoladas é um bom começo. O próximo passo é incorporá-los ao seu código para que todos os engenheiros do time utilizem o mesmo ponto de partida, sempre.

A maioria das ferramentas de desenvolvimento assistido por IA oferece suporte a três tipos de artefatos reutilizáveis:

Instruções / prompts de sistema: arquivos de contexto persistentes versionados no repositório que informam à IA as convenções do projeto, política de versões, regras de teste e padrões de código. Em ferramentas compatíveis, os prompts podem herdar esse contexto automaticamente.

Arquivos de prompt / comandos: templates de prompts nomeados e parametrizados armazenados no repositório. Em vez de reescrever o Prompt C a cada sprint, um engenheiro executa /low-level-design (ou comando equivalente) e preenche os campos necessários.

Agentes / modos: fluxos compostos que encadeiam múltiplos prompts com acesso a ferramentas definido. Um agente de revisão de specs pode executar os Prompts D, E e F em sequência, sem necessidade de copiar e colar manualmente.

O ganho está em consistência e velocidade:

• O onboarding se torna mais rápido porque as regras estão no repositório, não na cabeça das pessoas
• As revisões ficam mais fáceis porque todos os PRs gerados por IA seguem a mesma estrutura
• O processo evolui ao longo do tempo, pois melhorias em prompts beneficiam todo o time imediatamente

Trate seus prompts e definições de agentes como código: revise, versione e refine continuamente.

Indo além: MCP Servers fecham o ciclo com dados reais

Instruções, prompts e agentes tornam o processo consistente. MCP servers tornam esse processo vivo.

MCP (Model Context Protocol) é um padrão aberto que permite que ferramentas de IA se conectem diretamente a sistemas externos: arquivos, APIs, registries, pipelines de CI, executores de teste e mais.

Em vez de copiar e colar contexto, você dá à IA acesso direto e autorizado à fonte de verdade.

Cada etapa do ciclo orientado por specs se beneficia disso:

Passo 1 — Intenção do Produto

Um servidor MCP conectado ao seu gerenciador de tarefas (GitHub Issues, Jira, Linear) pode ler o ticket real, dependências e decisões anteriores, permitindo que a IA escreva a especificação com base no contexto real do projeto.

Pré-requisito — Leitura do Código

Substitui o copia-e-cola manual. Com acesso via MCP ao repositório, a IA pode analisar estrutura, módulos e PRs diretamente. O resumo do código passa a ser baseado em dados reais.

Passo 2 — Design de Alto Nível

Um MCP pode buscar informações atualizadas de suporte de frameworks (Angular, Spring Boot, Node.js). Assim, decisões de versão são baseadas em dados atuais, não em conhecimento desatualizado.

Passo 3 — Design de Baixo Nível

MCPs de banco de dados e APIs permitem que a IA veja schemas reais, contratos existentes e especificações OpenAPI. O design passa a refletir a realidade do sistema.

Passo 4 — Loop de TDD

Um MCP de execução de testes permite rodar testes e retornar resultados dentro da conversa.

O ciclo fica automático:

• Escrever testes
• Executar
• Ver falha real
• Corrigir
• Executar novamente

Para testes end-to-end, o MCP do Playwright permite que a IA controle um navegador real:

• Navegar
• Clicar
• Preencher formulários
• Validar resultados

Tudo sem sair da conversa.

Você pode iniciar com Playwright Codegen:

• Gerar testes a partir da interface real
• Refinar com IA
• Cobrir edge cases

Passo 5 — Verificação

MCPs de CI e segurança permitem rodar pipelines reais e retornar resultados diretamente.

Assim, a validação é feita com dados reais, não suposições.

Resultado geral

Você sai de um loop manual para um loop baseado em dados reais.

A IA continua raciocinando — os MCPs fornecem os fatos.

Como começar na prática

• Conectar MCP do GitHub (código e PRs)
• Conectar MCP de dependências (npm/Maven)
• Conectar executor de testes
• Conectar Playwright para testes end-to-end

Não precisa implementar tudo de uma vez. Comece pelo ponto que mais gera esforço manual no seu time.

Acordo leve de trabalho para times

Para garantir consistência entre produto e engenharia:

• Não gerar código antes de validar intenção e design
• Todo projeto com IA deve validar versões
• Mudanças de arquitetura exigem registro
• PRs devem incluir checklist de conformidade
• Releases exigem validação de suporte

Pequenas regras, grande impacto.

Conclusão

Você não precisa escolher entre criatividade e disciplina.

Vibe coding acelera.
Specs trazem controle.

Times de alto desempenho usam ambos.

Se quiser começar com uma mudança simples:

Nunca vá de um prompt direto para produção sem passar por especificação e validação.