Dev.to AI 🤖 Ai 👁 0 📖 34 min read

Vibe Coding ou Spec-Driven Development?

Vibe Coding ou Spec-Driven Development? Acho que o segredo está em saber quando usar cada um. O desenvolvimento de software está passando por uma transformação importante. Hoje, temos uma demanda cada vez maior por prod

Vibe Coding ou Spec-Driven Development? Acho que o segredo está em saber quando usar cada um.

O desenvolvimento de software está passando por uma transformação importante. Hoje, temos uma demanda cada vez maior por produtividade, entregas mais rápidas e soluções capazes de atender a sistemas cada vez mais complexos. Nesse cenário, a inteligência artificial deixou de ser apenas uma novidade tecnológica e passou a ocupar um papel importante no fluxo de desenvolvimento.

Mais do que simplesmente acelerar a escrita de código, a IA trouxe novas possibilidades para planejar, estruturar, implementar e manter aplicações. Entretanto, acredito que aproveitar essas possibilidades exige algo que continua sendo fundamental: conhecimento técnico.

Afinal, utilizar IA no desenvolvimento não significa deixar de compreender programação, arquitetura, banco de dados ou regras de negócio. Pelo contrário, quanto maior o nosso domínio sobre essas áreas, melhor conseguimos orientar as ferramentas, avaliar as soluções propostas e identificar quando uma implementação realmente faz sentido.

Minha relação com esse universo também não começou com a popularização da IA generativa. Acompanhei um pouco dessa evolução desde a época em que o assunto estava muito mais associado a Machine Learning, inclusive tendo desenvolvido um pequeno projeto nessa área. Isso me permitiu ter um primeiro contato com alguns dos conceitos que hoje fazem parte de uma discussão muito maior sobre inteligência artificial.

Com a evolução dessas ferramentas, ficou cada vez mais interessante observar como elas podem transformar nossa forma de trabalhar. Continuo considerando essencial saber desenvolver tanto no Front-end quanto no Back-end, entender o código e ter autonomia para construir soluções sem depender dessas ferramentas. A diferença é que, quando bem utilizadas, elas permitem chegar a determinados resultados em muito menos tempo.

E é justamente nesse contexto que comecei a observar duas abordagens que considero particularmente interessantes: o Vibe Coding e o Spec-Driven Development.

Tenho visto muita gente utilizando o chamado Vibe Coding praticamente para tudo. A pessoa abre uma conversa, descreve o que quer construir, recebe uma implementação, pede alguns ajustes e continua nesse ciclo até chegar a um resultado que parece funcionar.

E não acho que isso seja necessariamente ruim. Na verdade, o Vibe Coding tem seu espaço e pode ser extremamente produtivo.

O problema começa quando tentamos utilizar a mesma abordagem para qualquer tipo de desenvolvimento, independentemente da complexidade do projeto.

Acredito que existem dois caminhos muito interessantes para trabalhar com IA: o Vibe Coding e o Spec-Driven Development. Eles não são necessariamente concorrentes. Na minha visão, são abordagens que se complementam, e entender a diferença entre elas faz bastante diferença no resultado.

Afinal, o que é Vibe Coding e o que é Spec-Driven?

O Vibe Coding é uma forma mais espontânea de desenvolver utilizando IA. Você descreve o que deseja, recebe uma implementação, testa, observa o resultado e vai refinando a solução conforme necessário.

É um processo mais exploratório. Você não precisa necessariamente ter toda a estrutura definida antes de começar. Muitas vezes, a própria implementação ajuda a descobrir o que realmente precisa ser feito.

Isso funciona muito bem quando estamos falando de pequenas funcionalidades, protótipos, scripts, ajustes pontuais, componentes isolados ou até experimentações para validar uma ideia.

Já o Spec-Driven Development segue uma lógica diferente.

Em vez de começar diretamente pelo código, você começa pela especificação. Primeiro define o problema, o objetivo, as regras, as restrições, os comportamentos esperados e como aquela funcionalidade deve se integrar ao restante do sistema. Só depois parte para a implementação.

A IA deixa de trabalhar apenas com uma descrição genérica do que você deseja e passa a trabalhar com um conjunto de informações que orienta o desenvolvimento.

Isso muda bastante a qualidade das respostas, principalmente em projetos maiores, porque reduz ambiguidades e evita que a IA precise tomar decisões importantes com base em suposições.

Na prática, eu vejo a diferença da seguinte maneira:

Aspecto Vibe Coding Spec-Driven
Abordagem Exploratória Planejada
Contexto Mais imediato Estruturado e persistente
Planejamento Durante a implementação Antes da implementação
Melhor aplicação Tarefas pontuais e protótipos Features complexas e sistemas
Flexibilidade Alta Maior controle sobre mudanças
Risco principal Acumular soluções improvisadas Excesso de planejamento e documentação
Consumo de tokens Pode crescer com tentativas e contexto repetido Pode ser reduzido com contexto organizado

Não significa que o Spec-Driven sempre será mais rápido ou consumirá menos tokens. Isso depende da implementação, do modelo e da organização do contexto. Mas, quando bem estruturado, ele tende a evitar muitas interações desnecessárias, retrabalho e repetição de instruções.

E é justamente essa parte que considero mais interessante.

Quando eu escolheria cada abordagem?

Se estou criando um pequeno componente, ajustando um formulário, fazendo uma consulta simples ou testando uma ideia, não vejo necessidade de criar uma documentação inteira antes de começar.

Nesse cenário, o Vibe Coding resolve muito bem. Eu descrevo o que quero, informo as restrições necessárias, analiso o resultado e vou refinando.

Agora, imagine que estou desenvolvendo uma funcionalidade de ordens de serviço dentro de um sistema que já possui autenticação, usuários, permissões, banco de dados, APIs, regras de negócio e diferentes módulos.

Nesse caso, simplesmente pedir para a IA implementar uma funcionalidade de ordens de serviço pode ser um problema.

Ela precisa entender como o projeto está organizado, quais convenções são utilizadas, como funciona a autenticação, como as permissões são verificadas, quais entidades existem, como os dados são persistidos e como aquela nova funcionalidade deve conversar com o restante da aplicação.

Se não fornecemos esse contexto, a IA começa a preencher as lacunas por conta própria. E é justamente aí que surgem implementações duplicadas, serviços desnecessários, componentes fora do padrão, regras de negócio inconsistentes e decisões arquiteturais que não combinam com o projeto.

É nesse tipo de situação que prefiro utilizar Spec-Driven Development.

Como organizo o contexto de um projeto

Uma coisa que considero muito importante é não colocar todas as informações do projeto em um único prompt gigantesco.

Prefiro dividir o conhecimento em arquivos menores, cada um com uma responsabilidade. Assim, consigo reaproveitar as instruções, atualizar uma parte sem precisar reescrever tudo e fornecer à IA somente o contexto necessário para determinada tarefa.

Por exemplo, em um projeto de ordens de serviço, eu começaria criando uma estrutura geral de contexto.

Uma possível organização seria:

project/
├── docs/
│   ├── project-context.md
│   ├── architecture.md
│   ├── stack.md
│   ├── conventions.md
│   ├── coding-standards.md
│   ├── security.md
│   ├── performance.md
│   ├── database.md
│   ├── testing.md
│
│   ├── frontend/
│   │   ├── frontend-context.md
│   │   ├── components.md
│   │   ├── ui-guidelines.md
│   │   ├── routing.md
│   │   ├── state-management.md
│   │   └── security.md
│
│   ├── backend/
│   │   ├── backend-context.md
│   │   ├── api-guidelines.md
│   │   ├── services.md
│   │   ├── validation.md
│   │   ├── authorization.md
│   │   └── security.md
│
│   ├── database/
│   │   ├── database-context.md
│   │   ├── schema.md
│   │   ├── permissions.md
│   │   └── security.md
│
│   ├── agents/
│   │   ├── general-agent.md
│   │   ├── frontend-agent.md
│   │   ├── backend-agent.md
│   │   ├── database-agent.md
│   │   └── reviewer-agent.md
│
│   └── specs/
│       ├── work-orders/
│       │   ├── feature.md
│       │   ├── api.md
│       │   ├── ui.md
│       │   ├── database.md
│       │   ├── security.md
│       │   └── tasks.md
│       │
│       └── customers/
│           └── feature.md
│
└── src/

Essa estrutura é apenas uma referência. Não significa que todo projeto precise de tantos arquivos. A organização deve acompanhar a complexidade real da aplicação.

A ideia é separar duas coisas: aquilo que define o projeto como um todo e aquilo que define uma funcionalidade específica.

1. Contexto geral do projeto

O primeiro arquivo seria o project-context.md.

Nele, colocaria uma visão geral da aplicação: o que o sistema faz, qual problema resolve, quais são seus principais módulos, quem são seus usuários e quais são as regras gerais do negócio.

Exemplo de project-context.md:

# Project Context

## 1. Visão geral

Sistema de gerenciamento de ordens de serviço
desenvolvido para controlar solicitações,
atendimentos técnicos e acompanhamento de serviços.

## 2. Objetivos

- Centralizar o gerenciamento de ordens de serviço.
- Permitir o acompanhamento dos atendimentos.
- Organizar clientes e técnicos.
- Manter histórico de alterações.
- Facilitar a gestão operacional.

## 3. Principais módulos

- Autenticação
- Usuários
- Clientes
- Técnicos
- Ordens de serviço
- Relatórios

## 4. Perfis de usuário

### Administrador
Possui acesso completo ao sistema.

### Atendente
Pode cadastrar clientes e abrir ordens de serviço.

### Técnico
Pode visualizar suas ordens atribuídas
e atualizar o andamento dos atendimentos.

## 5. Regras gerais

- Todas as operações devem respeitar
  as permissões do usuário autenticado.
- Registros importantes devem possuir histórico.
- Dados obrigatórios devem ser validados.
- Operações críticas devem possuir tratamento
  adequado de erros.

## 6. Diretrizes para a IA

- Consulte a documentação antes de implementar.
- Não invente regras de negócio.
- Respeite a arquitetura existente.
- Não altere funcionalidades não relacionadas
  à tarefa solicitada.
- Solicite esclarecimentos quando houver
  requisitos ambíguos.

Perceba que esse arquivo não precisa conter todos os detalhes da aplicação. Ele funciona como uma referência inicial para que a IA entenda o ambiente em que está trabalhando.

Também criaria um stack.md, descrevendo as tecnologias utilizadas, versões, bibliotecas principais e decisões técnicas já estabelecidas.

Exemplo de stack.md:

# Technology Stack

## Front-end

- React
- TypeScript
- Vite
- Tailwind CSS
- React Router

## Back-end

- Node.js
- Express
- TypeScript

## Database

- PostgreSQL

## ORM

- Prisma

## Testing

- Vitest
- Supertest

## Guidelines

- Utilizar TypeScript em todo o projeto.
- Priorizar tipagem explícita.
- Evitar dependências desnecessárias.
- Utilizar as bibliotecas já existentes
  antes de adicionar novas dependências.
- Respeitar as versões instaladas.

Outro arquivo importante seria o de convenções. É nele que definiria como o código deve ser escrito, como os arquivos devem ser organizados, como nomear funções, classes, componentes, serviços e variáveis.

Exemplo de conventions.md:

# Development Conventions

## Naming

- Componentes React: PascalCase.
- Funções e variáveis: camelCase.
- Constantes globais: UPPER_SNAKE_CASE.
- Arquivos de componentes: PascalCase.
- Arquivos de serviços: camelCase.

## Code Organization

- Manter cada módulo com responsabilidades claras.
- Evitar componentes excessivamente grandes.
- Separar regras de negócio da interface.
- Reutilizar funções compartilhadas quando necessário.

## TypeScript

- Evitar o uso de any.
- Definir interfaces e tipos explicitamente.
- Utilizar unknown quando apropriado.
- Evitar tipagens desnecessariamente complexas.

## General Rules

- Seguir o princípio DRY.
- Respeitar o princípio SRP.
- Evitar duplicação de lógica.
- Não criar abstrações sem necessidade.
- Preservar os padrões já utilizados no projeto.

Parece algo simples, mas faz bastante diferença.

Não adianta pedir para a IA criar uma funcionalidade seguindo a arquitetura existente se ela não sabe qual arquitetura está sendo utilizada.

2. Agentes com responsabilidades específicas

Outra coisa que considero interessante é trabalhar com agentes especializados.

Não necessariamente precisamos criar dezenas deles. Na verdade, acredito que poucos agentes bem definidos sejam mais úteis do que vários agentes sem responsabilidades claras.

Eu começaria com um agente geral, responsável por conhecer o projeto como um todo, entender a stack, consultar a documentação e respeitar as convenções estabelecidas.

Depois, dependendo da complexidade, dividiria responsabilidades.

  • Agente geral: entende o contexto do projeto, identifica dependências e orienta a execução.
  • Agente Front-end: trabalha com componentes, UI, rotas, estado, acessibilidade e integração com APIs.
  • Agente Back-end: trabalha com regras de negócio, serviços, endpoints, persistência e validações.
  • Agente de banco de dados: trabalha com modelagem, relacionamentos, migrations, consultas e permissões.
  • Agente de revisão: analisa a implementação, procura inconsistências, problemas de segurança, duplicações e possíveis melhorias.

Esses agentes podem compartilhar os mesmos arquivos de contexto, mas possuem instruções específicas sobre o que devem fazer.

Por exemplo, um agente de Back-end não precisa receber instruções detalhadas sobre como construir componentes visuais. Ele precisa entender as regras de negócio, a arquitetura da API, os serviços, a persistência e as validações.

Exemplo de backend-agent.md:

# Backend Agent

## Role

Você é responsável pela implementação e manutenção
das funcionalidades do Back-end.

## Responsibilities

- Implementar endpoints e serviços.
- Respeitar as regras de negócio.
- Trabalhar com validações e persistência.
- Manter a separação de responsabilidades.
- Garantir tratamento adequado de erros.

## Required Context

Antes de implementar qualquer funcionalidade,
consulte:

- ../project-context.md
- ../architecture.md
- ../stack.md
- ../conventions.md
- ../security.md
- ../backend/backend-context.md
- ../backend/security.md

## Architecture Rules

- Controllers devem coordenar requisições HTTP.
- Services devem concentrar regras de negócio.
- Repositories devem isolar a persistência.
- Validators devem validar os dados recebidos.
- Middlewares devem tratar responsabilidades
  transversais.

## Restrictions

- Não alterar a estrutura do banco sem especificação.
- Não ignorar validações existentes.
- Não duplicar serviços já implementados.
- Não instalar dependências sem necessidade.
- Não modificar módulos fora do escopo.

## Before Finishing

- Verificar erros de implementação.
- Executar testes relevantes.
- Revisar tratamento de exceções.
- Verificar controles de autorização.
- Apresentar um resumo dos arquivos modificados.

Um agente de Front-end teria instruções semelhantes, mas voltadas à interface, componentes, acessibilidade, responsividade e integração com APIs.

Uma observação: criar um agente não significa necessariamente criar um processo autônomo separado. Dependendo da ferramenta, ele pode ser apenas uma configuração de instruções e responsabilidades. O importante é a separação de papéis, não a quantidade de agentes.

3. Especificações por funcionalidade

Depois de estabelecer o contexto geral, começaria a documentar cada funcionalidade individualmente.

Vamos continuar com o exemplo de ordens de serviço.

Antes de pedir a implementação, criaria um feature.md descrevendo:

  • Qual é o objetivo da funcionalidade.
  • Quem pode criar uma ordem de serviço.
  • Quais informações são obrigatórias.
  • Quais são os estados possíveis.
  • Quais regras determinam uma alteração de status.
  • Quais usuários podem visualizar ou editar os registros.
  • Quais são os critérios de aceite.
  • Como a funcionalidade se relaciona com clientes, técnicos e serviços.

Mas como isso ficaria na prática?

Exemplo de feature.md:

# Feature: Work Orders

## 1. Objetivo

Implementar o módulo de ordens de serviço,
permitindo o cadastro, acompanhamento e
gerenciamento dos atendimentos técnicos.

## 2. Funcionalidades

- Criar ordem de serviço.
- Consultar ordens existentes.
- Editar informações permitidas.
- Atribuir técnico responsável.
- Atualizar status.
- Consultar histórico de alterações.

## 3. Regras de negócio

- Toda ordem deve possuir um cliente.
- Toda ordem deve possuir uma descrição.
- Uma ordem pode possuir um técnico responsável.
- O status inicial deve ser OPEN.
- Somente usuários autorizados podem alterar
  o status da ordem.
- Toda alteração de status deve gerar histórico.

## 4. Status disponíveis

- OPEN
- IN_PROGRESS
- WAITING
- COMPLETED
- CANCELED

## 5. Critérios de aceite

- O usuário autorizado consegue criar uma ordem.
- Campos obrigatórios são validados.
- Ordens são persistidas corretamente.
- O sistema registra alterações de status.
- Usuários sem permissão não conseguem
  modificar registros.

## 6. Integrações

- Módulo de clientes.
- Módulo de usuários.
- Módulo de técnicos.
- Serviço de autenticação.

## 7. Restrições

- Respeitar a arquitetura existente.
- Não duplicar funcionalidades.
- Não alterar regras de outros módulos.
- Manter compatibilidade com a API atual.

Depois dividiria os detalhes em arquivos específicos.

O api.md descreveria os endpoints, métodos HTTP, parâmetros, respostas esperadas, erros e regras de autenticação.

Exemplo de api.md:

# Work Orders API

## POST /api/work-orders

Cria uma nova ordem de serviço.

### Authentication

JWT obrigatório.

### Authorization

Permissão necessária: work-orders:create.

### Request Body

{
  "customerId": "uuid",
  "technicianId": "uuid",
  "description": "Manutenção preventiva"
}

### Success Response

Status: 201 Created

{
  "id": "uuid",
  "customerId": "uuid",
  "technicianId": "uuid",
  "description": "Manutenção preventiva",
  "status": "OPEN",
  "createdAt": "2026-11-22T10:00:00Z"
}

### Possible Errors

- 400: Dados inválidos.
- 401: Usuário não autenticado.
- 403: Usuário sem permissão.
- 404: Cliente ou técnico não encontrado.
- 500: Erro interno.

O ui.md explicaria como a interface deve funcionar, quais componentes serão necessários, quais estados precisam ser apresentados e como será a experiência do usuário.

Exemplo de ui.md:

# Work Orders UI

## Screen: Create Work Order

### Components

- WorkOrderForm
- CustomerSelect
- TechnicianSelect
- DescriptionField
- SubmitButton

### Fields

| Field | Type | Required |
|---|---|---|
| Customer | Select | Yes |
| Technician | Select | No |
| Description | Textarea | Yes |

### Behaviors

- Exibir loading durante o envio.
- Desabilitar o botão durante a requisição.
- Apresentar mensagens de validação.
- Exibir confirmação após o cadastro.
- Tratar erros retornados pela API.

### Layout

- Interface responsiva.
- Utilizar componentes existentes.
- Seguir os padrões visuais do projeto.
- Manter consistência com os demais formulários.

### Accessibility

- Todos os campos devem possuir labels.
- Garantir navegação por teclado.
- Exibir mensagens de erro acessíveis.

O database.md descreveria as entidades, relacionamentos, campos, índices e restrições.

Exemplo de database.md:

# Database Specification

## Entity: WorkOrder

| Field | Type | Nullable |
|---|---|---|
| id | UUID | No |
| customer_id | UUID | No |
| technician_id | UUID | Yes |
| description | TEXT | No |
| status | VARCHAR | No |
| created_at | TIMESTAMP | No |
| updated_at | TIMESTAMP | No |

## Relationships

- WorkOrder belongs to Customer.
- WorkOrder belongs to Technician.
- WorkOrder has many WorkOrderHistory records.

## Constraints

- customer_id must reference an existing customer.
- technician_id must reference an existing technician.
- status must contain a valid status.
- Every order must have a description.

## Indexes

- customer_id
- technician_id
- status
- created_at

O security.md especificaria as permissões, validações, proteção de dados e regras de acesso.

Exemplo de security.md:

# Work Orders Security

## Authentication

All endpoints require JWT authentication.

## Authorization

- ADMIN: Full access.
- ATTENDANT: Create and view orders.
- TECHNICIAN: View assigned orders and update
  permitted statuses.

## Data Validation

- Validate all incoming data.
- Never trust client-side validation alone.
- Validate UUIDs and required fields.
- Reject unexpected input.

## Access Control

- Verify ownership and permissions.
- Do not expose sensitive customer information.
- Prevent unauthorized status changes.

## General Rules

- Use parameterized database queries.
- Avoid exposing internal errors.
- Do not log sensitive information.

Perceba que não estou pedindo para a IA simplesmente construir uma tela ou criar uma API. Estou fornecendo as informações necessárias para que ela entenda o que está construindo e como aquilo deve se encaixar no restante do sistema.

E esses arquivos não precisam ser escritos manualmente do zero. Inclusive, considero muito interessante utilizar a própria IA para ajudar a criá-los.

A etapa que exige mais atenção é a análise inicial do projeto, porque é necessário entender a arquitetura existente, identificar padrões e descobrir como as diferentes partes se relacionam.

Depois disso, boa parte da documentação é textual, relativamente leve e pode ser gerada, revisada e mantida com auxílio da própria IA.

4. Transformando especificações em tarefas

Outra parte interessante é transformar a documentação em etapas menores de implementação.

Não gosto muito da ideia de simplesmente entregar toda a especificação para a IA e pedir que ela desenvolva tudo de uma vez.

Prefiro dividir o trabalho em tarefas que possam ser implementadas, testadas e revisadas individualmente.

Para isso, utilizaria um tasks.md.

Exemplo de tasks.md:

# Work Orders - Implementation Tasks

## Phase 1 - Database

- [ ] Create WorkOrder entity.
- [ ] Create WorkOrderHistory entity.
- [ ] Define relationships.
- [ ] Create migrations.
- [ ] Add required indexes.

## Phase 2 - Backend

- [ ] Create WorkOrderRepository.
- [ ] Create WorkOrderService.
- [ ] Create WorkOrderController.
- [ ] Implement request validation.
- [ ] Implement authorization.
- [ ] Create API routes.
- [ ] Implement error handling.

## Phase 3 - Frontend

- [ ] Create WorkOrderForm.
- [ ] Create CustomerSelect.
- [ ] Create TechnicianSelect.
- [ ] Implement API integration.
- [ ] Implement loading states.
- [ ] Implement error messages.
- [ ] Add form validation.

## Phase 4 - Testing

- [ ] Test work order creation.
- [ ] Test required fields.
- [ ] Test authorization.
- [ ] Test invalid requests.
- [ ] Test API integration.
- [ ] Validate frontend behavior.

## Phase 5 - Review

- [ ] Review architecture.
- [ ] Check for duplicated logic.
- [ ] Review security.
- [ ] Review database relationships.
- [ ] Verify acceptance criteria.

A partir disso, podemos orientar a IA a trabalhar em uma etapa por vez, respeitando as dependências entre elas.

Por exemplo, antes de implementar o formulário no Front-end, precisamos saber qual contrato a API oferece. Da mesma forma, antes de criar um endpoint, precisamos ter clareza sobre as regras de negócio e a estrutura dos dados.

Isso torna o desenvolvimento mais previsível e facilita a identificação de problemas.

Separar UI, API, regras de negócio e infraestrutura

Uma das coisas que mais gosto nessa abordagem é poder separar a implementação por responsabilidades.

Imagine novamente a funcionalidade de ordens de serviço. Ela possui interface, comunicação com APIs, regras de negócio, validações, controle de acesso e persistência de dados.

Não vejo vantagem em pedir para a IA implementar tudo de uma vez, principalmente quando estamos trabalhando em uma aplicação maior.

No Front-end, por exemplo, gosto de separar a definição visual da lógica de integração. Se existe uma estrutura de componentes, faz sentido ter orientações específicas para a UI, incluindo padrões visuais, reutilização de componentes, acessibilidade, responsividade e organização.

No Back-end, a separação também é importante. Controllers não deveriam concentrar todas as regras de negócio, assim como serviços não deveriam assumir responsabilidades que pertencem à camada de persistência.

Uma estrutura possível para o nosso exemplo seria:

src/
├── frontend/
│   ├── components/
│   ├── pages/
│   ├── features/
│   │   └── work-orders/
│   │       ├── components/
│   │       ├── hooks/
│   │       ├── services/
│   │       ├── types/
│   │       └── index.ts
│   ├── services/
│   ├── shared/
│   └── utils/
│
└── backend/
    ├── modules/
    │   └── work-orders/
    │       ├── controllers/
    │       ├── services/
    │       ├── repositories/
    │       ├── validators/
    │       ├── schemas/
    │       ├── types/
    │       └── routes/
    │
    ├── middlewares/
    ├── database/
    ├── shared/
    ├── utils/
    └── config/

Não estou dizendo que essa é a única estrutura correta. Existem diferentes arquiteturas e formas de organizar uma aplicação. O importante é que a organização faça sentido para o projeto e que cada camada tenha uma responsabilidade bem definida.

Um exemplo mais prático: Front-end e Back-end com Node.js

Vamos imaginar que estamos construindo a funcionalidade de criação de uma ordem de serviço.

No Front-end, a IA precisa saber como a aplicação trabalha com componentes, formulários, validações, estado e requisições HTTP.

Eu definiria algumas regras no ui-guidelines.md:

  • Componentes devem ter responsabilidades bem definidas.
  • Evitar duplicação de código, seguindo o princípio DRY (Don't Repeat Yourself).
  • Cada módulo deve ter uma responsabilidade clara, seguindo o princípio SRP (Single Responsibility Principle).
  • Componentes visuais não devem concentrar regras de negócio complexas.
  • Chamadas à API devem ser isoladas em serviços ou módulos apropriados.
  • Tipos e interfaces devem ser definidos explicitamente.
  • Evitar o uso de any no TypeScript, priorizando tipos seguros, unknown quando apropriado e validações explícitas.
  • Utilizar carregamento sob demanda (lazy loading) quando fizer sentido.
  • Evitar renderizações e cálculos desnecessários.
  • Utilizar debounce em operações que realmente precisam controlar a frequência de execução, como buscas enquanto o usuário digita.
  • Reaproveitar componentes e funções compartilhadas sem criar abstrações desnecessárias.

Também considero importante separar a parte de segurança.

Por exemplo, se existe conteúdo HTML vindo de usuários ou de fontes externas, precisamos avaliar os riscos de XSS e utilizar sanitização adequada, como DOMPurify, quando houver necessidade de renderizar HTML não confiável.

Não basta pedir para a IA criar uma tela bonita. É preciso estabelecer como aquela tela deve funcionar, como os dados serão tratados e quais riscos precisam ser considerados.

Segurança no Front-end

O Front-end é uma das primeiras camadas de contato com o usuário e também uma superfície de ataque. Embora não seja possível confiar nele para proteger os dados ou garantir as permissões de acesso, existem diversas medidas que ajudam a reduzir riscos.

Um erro comum é acreditar que esconder um botão ou uma opção na interface significa impedir que o usuário execute determinada operação.

Não significa.

Um usuário pode utilizar ferramentas de desenvolvedor, alterar requisições HTTP ou chamar diretamente os endpoints da API. Por isso, qualquer controle de segurança importante precisa ser aplicado também no Back-end.

No Front-end, eu documentaria algumas diretrizes no arquivo frontend/security.md.

Exemplo de frontend/security.md:

# Frontend Security Guidelines

## 1. XSS Protection

- Nunca confiar em conteúdo recebido de usuários.
- Evitar o uso de dangerouslySetInnerHTML.
- Quando a renderização de HTML for necessária,
  utilizar sanitização adequada.
- Não inserir dados externos diretamente no DOM.
- Utilizar mecanismos seguros de renderização.

## 2. Authentication and Sessions

- Não armazenar senhas no navegador.
- Evitar armazenar tokens de longa duração
  em localStorage.
- Preferir cookies HttpOnly, Secure e SameSite
  quando a arquitetura utilizar autenticação
  baseada em cookies.
- Implementar expiração e renovação de sessão.
- Tratar corretamente sessões expiradas.

## 3. API Communication

- Utilizar HTTPS em todas as comunicações.
- Não enviar credenciais em URLs.
- Não expor tokens em logs.
- Tratar erros sem revelar informações internas.
- Não confiar em dados enviados pelo cliente.

## 4. Input Validation

- Validar campos antes do envio.
- Limitar tamanhos de entradas.
- Validar formatos esperados.
- Nunca considerar a validação do Front-end
  como substituta da validação no Back-end.

## 5. Content Security Policy

- Definir uma Content Security Policy adequada.
- Restringir fontes de scripts.
- Evitar scripts inline quando possível.
- Restringir origens externas desnecessárias.

## 6. Permissions

- Exibir funcionalidades de acordo com
  as permissões do usuário.
- Não considerar controles visuais como
  mecanismos de autorização.
- Toda autorização deve ser validada no servidor.

## 7. Dependencies

- Evitar bibliotecas desnecessárias.
- Manter dependências atualizadas.
- Verificar vulnerabilidades conhecidas.
- Não utilizar pacotes de procedência duvidosa.

Alguns pontos merecem atenção especial.

XSS (Cross-Site Scripting): acontece quando um invasor consegue inserir conteúdo executável em uma página, podendo executar scripts no contexto de outros usuários. É importante evitar renderizações inseguras e tratar corretamente qualquer conteúdo não confiável.

CSP (Content Security Policy): é uma política de segurança que permite restringir quais origens podem fornecer scripts, estilos, imagens e outros recursos. Ela ajuda a reduzir o impacto de determinadas vulnerabilidades, mas não substitui a correção da origem do problema.

Tokens e sessões: o armazenamento de credenciais exige cuidado. localStorage, por exemplo, pode ser acessado por JavaScript e, consequentemente, por scripts maliciosos executados na página. Uma alternativa comum é utilizar cookies com as propriedades HttpOnly, Secure e SameSite, acompanhados de proteção contra CSRF quando aplicável.

Também é importante entender que esconder informações na interface não significa protegê-las. A autorização precisa acontecer no servidor.

Segurança no Back-end

No Back-end, temos uma responsabilidade ainda maior sobre a proteção da aplicação, porque é nele que ficam as regras de negócio, a autenticação, a autorização e o acesso aos dados.

Não basta verificar se o usuário está autenticado. Também precisamos verificar se ele tem permissão para executar aquela operação específica e se pode acessar aquele registro.

Por exemplo, imagine um técnico que tenta consultar uma ordem de serviço pertencente a outro técnico.

Mesmo que ele esteja autenticado, isso não significa que tenha autorização para acessar aquele registro.

É nesse ponto que entram conceitos como RBAC (Role-Based Access Control) e ABAC (Attribute-Based Access Control).

O RBAC organiza permissões com base em papéis, como administrador, atendente e técnico.

Já o ABAC permite avaliar atributos adicionais, como propriedade do registro, departamento, contexto da operação e outras condições.

Para esse tipo de aplicação, documentaria as regras no arquivo backend/security.md.

Exemplo de backend/security.md:

# Backend Security Guidelines

## 1. Authentication

- Implementar autenticação segura.
- Validar tokens e sessões no servidor.
- Verificar expiração de credenciais.
- Nunca confiar em informações de identidade
  fornecidas diretamente pelo cliente.
- Utilizar mecanismos seguros de renovação
  de sessão.

## 2. Authorization

- Implementar controle de acesso RBAC.
- Avaliar ABAC quando necessário.
- Validar permissões em cada operação protegida.
- Verificar propriedade dos registros.
- Aplicar princípio do menor privilégio.
- Não depender de permissões controladas
  exclusivamente pelo Front-end.

## 3. Input Validation

- Validar todas as entradas.
- Utilizar schemas de validação.
- Rejeitar campos inesperados quando apropriado.
- Limitar tamanho de payloads.
- Validar tipos e formatos.
- Evitar confiar em dados enviados pelo cliente.

## 4. SQL Injection

- Utilizar consultas parametrizadas.
- Evitar concatenar entradas em comandos SQL.
- Não executar SQL dinâmico sem validação adequada.
- Revisar consultas construídas pelo ORM.

## 5. API Protection

- Implementar rate limiting.
- Configurar CORS com origens permitidas.
- Utilizar HTTPS.
- Configurar headers de segurança.
- Limitar tamanho das requisições.
- Implementar proteção contra abuso de endpoints.

## 6. Error Handling

- Não retornar stack traces em produção.
- Não expor detalhes internos da aplicação.
- Padronizar respostas de erro.
- Registrar informações relevantes em logs seguros.

## 7. Sensitive Data

- Não armazenar senhas em texto puro.
- Utilizar algoritmos próprios para hash de senhas,
  como Argon2id.
- Não registrar tokens ou credenciais em logs.
- Proteger dados pessoais e informações sensíveis.

## 8. Secrets Management

- Não armazenar credenciais no código.
- Utilizar variáveis de ambiente e secret managers.
- Nunca versionar arquivos com credenciais reais.
- Rotacionar secrets quando necessário.

## 9. Logging and Monitoring

- Registrar eventos relevantes de segurança.
- Monitorar tentativas de acesso indevido.
- Registrar falhas de autenticação.
- Evitar armazenar dados sensíveis nos logs.
- Implementar alertas para comportamentos suspeitos.

Na prática, eu dividiria a segurança do Back-end em algumas responsabilidades.

Autenticação: verificar quem está realizando a requisição. Isso pode envolver JWT, sessões, OAuth ou outro mecanismo adequado à arquitetura.

Autorização: verificar o que aquele usuário pode fazer. Não basta verificar se ele é um administrador ou técnico. Em determinadas operações, também precisamos verificar se o registro pertence a ele ou se existe uma condição específica para permitir o acesso.

Validação: toda entrada precisa ser validada no servidor, mesmo que já tenha passado por validações no Front-end. Bibliotecas como Zod podem ajudar a definir schemas e validar os dados recebidos.

Rate limiting: limitar a frequência de requisições para reduzir abusos, tentativas automatizadas e determinados ataques de força bruta. Os limites devem considerar o tipo de endpoint e o comportamento esperado da aplicação.

CORS: restringir quais origens podem realizar requisições ao servidor. CORS não substitui autenticação ou autorização, mas ajuda a controlar o acesso entre origens no navegador.

CSRF: quando a aplicação utiliza autenticação baseada em cookies enviados automaticamente pelo navegador, é necessário avaliar proteção contra requisições forjadas, utilizando mecanismos como tokens CSRF e políticas adequadas de SameSite.

Também considero importante implementar headers de segurança, como os relacionados à proteção contra clickjacking, MIME sniffing e políticas de conteúdo.

Uma biblioteca como Helmet, no ecossistema Express, pode ajudar a configurar diversos desses headers.

Segurança no Banco de Dados

Outra camada que não pode ser negligenciada é o banco de dados.

Mesmo que o Front-end e o Back-end estejam bem estruturados, uma configuração inadequada do banco pode comprometer toda a aplicação.

É importante lembrar que o banco de dados não deve ser tratado apenas como um lugar onde armazenamos informações. Ele também precisa possuir controles de acesso, integridade, proteção e mecanismos de recuperação.

Por exemplo, imagine que a aplicação possui diferentes perfis de usuários e diversas informações de clientes. Não faria sentido utilizar uma única credencial com permissões administrativas para todas as operações da aplicação.

O ideal é trabalhar com contas e permissões adequadas às responsabilidades de cada serviço.

Exemplo de database/security.md:

# Database Security Guidelines

## 1. Access Control

- Aplicar o princípio do menor privilégio.
- Não utilizar credenciais administrativas
  na conexão padrão da aplicação.
- Criar usuários específicos para cada serviço
  quando necessário.
- Restringir permissões de leitura e escrita.
- Revogar acessos que não são mais necessários.

## 2. SQL Injection

- Utilizar consultas parametrizadas.
- Não concatenar dados externos em comandos SQL.
- Revisar consultas dinâmicas.
- Validar parâmetros antes da execução.

## 3. Data Integrity

- Utilizar foreign keys quando apropriado.
- Definir constraints.
- Aplicar NOT NULL em campos obrigatórios.
- Garantir integridade referencial.
- Utilizar transações em operações críticas.

## 4. Sensitive Information

- Não armazenar senhas em texto puro.
- Proteger dados pessoais.
- Avaliar criptografia de campos sensíveis.
- Utilizar criptografia em trânsito.
- Proteger backups e arquivos de exportação.

## 5. Network Security

- Não expor o banco diretamente à internet.
- Restringir conexões por rede e firewall.
- Utilizar conexões criptografadas.
- Permitir acesso somente aos serviços autorizados.

## 6. Backup and Recovery

- Realizar backups periódicos.
- Definir política de retenção.
- Proteger os arquivos de backup.
- Testar procedimentos de restauração.
- Documentar estratégias de recuperação.

## 7. Auditing

- Registrar operações críticas.
- Monitorar alterações de permissões.
- Rastrear alterações em dados importantes.
- Proteger os registros de auditoria.

Algumas medidas merecem uma atenção especial.

Princípio do menor privilégio: cada usuário, serviço ou processo deve possuir somente as permissões necessárias para executar suas funções. Se uma aplicação precisa apenas consultar determinadas tabelas, não deveria utilizar uma credencial com permissão para apagar todo o banco.

SQL Injection: acontece quando entradas não confiáveis conseguem interferir na estrutura de uma consulta SQL. Consultas parametrizadas são uma das principais formas de prevenção. Utilizar um ORM ajuda, mas não significa que estamos automaticamente protegidos, principalmente quando existem consultas SQL brutas ou construções dinâmicas.

Integridade referencial: utilizar chaves estrangeiras, constraints e transações ajuda a impedir que a aplicação mantenha dados inconsistentes. Não devemos depender exclusivamente das validações feitas pelo Back-end.

Criptografia: é importante proteger as comunicações entre aplicação e banco de dados utilizando TLS, além de avaliar criptografia em repouso e proteção de campos especialmente sensíveis. Senhas de usuários devem ser armazenadas por meio de algoritmos próprios para hash de senhas, como Argon2id, e não por criptografia reversível.

Backups: não adianta ter uma estratégia de backup se nunca testamos a restauração. É importante definir retenção, proteger os arquivos e verificar se realmente conseguimos recuperar os dados em uma situação de falha.

Também consideraria, dependendo da arquitetura, utilizar recursos como Row-Level Security (RLS) no PostgreSQL. Ele permite implementar políticas de acesso diretamente no banco, restringindo quais registros podem ser consultados ou modificados por determinadas sessões.

Isso pode funcionar como uma camada adicional de proteção, mas exige uma configuração cuidadosa para que o contexto de usuário e as permissões sejam aplicados corretamente.

Segurança não deve ficar restrita a uma única camada

Uma coisa que considero fundamental é entender que essas proteções precisam trabalhar em conjunto.

Imagine o seguinte fluxo:

             USER
               |
               v
       FRONT-END SECURITY
       - Input validation
       - XSS protection
       - Secure session
       - CSP
               |
               v
          HTTPS / API
               |
               v
        BACK-END SECURITY
        - Authentication
        - Authorization
        - Rate limiting
        - Request validation
        - Business rules
               |
               v
        DATABASE SECURITY
        - Least privilege
        - SQL parameterization
        - Constraints
        - Transactions
        - Encryption
               |
               v
          DATABASE

O objetivo é evitar que a segurança dependa de apenas um mecanismo.

Por exemplo, validar um campo no Front-end melhora a experiência do usuário, mas não impede que alguém envie uma requisição manualmente com dados inválidos.

Validar novamente no Back-end reduz esse risco.

Utilizar consultas parametrizadas protege a interação com o banco.

Aplicar permissões diretamente no banco pode oferecer uma proteção adicional em determinados cenários.

Essa abordagem é conhecida como Defense in Depth, ou defesa em profundidade.

Em vez de depender de uma única barreira, criamos diferentes mecanismos de proteção, de modo que a falha de uma camada não comprometa automaticamente todas as outras.

Também é importante considerar a segurança durante todo o ciclo de desenvolvimento, incluindo revisão de código, testes automatizados, análise de dependências, atualização de bibliotecas e monitoramento em produção.

Eu também manteria um security.md geral para documentar as políticas de segurança que se aplicam ao projeto inteiro.

Exemplo de docs/security.md:

# Application Security Policy

## Security Principles

- Defense in Depth.
- Least Privilege.
- Secure by Default.
- Fail Securely.
- Separation of Responsibilities.

## Frontend

- Prevent XSS.
- Use secure session management.
- Apply Content Security Policy.
- Validate user inputs.
- Never trust client-side permissions.

## Backend

- Enforce authentication and authorization.
- Validate all incoming requests.
- Protect APIs against abuse.
- Use secure password hashing.
- Apply rate limiting.
- Avoid sensitive information in responses.

## Database

- Apply least privilege.
- Use parameterized queries.
- Enforce data integrity.
- Protect credentials.
- Encrypt sensitive information.
- Maintain tested backups.

## Infrastructure

- Enforce HTTPS.
- Protect environment variables.
- Use secret management.
- Restrict network access.
- Monitor security events.

## Development Process

- Review security-sensitive changes.
- Run dependency vulnerability checks.
- Execute automated tests.
- Review authentication and authorization.
- Document security-related decisions.

## Before Production

- Verify security configurations.
- Review exposed endpoints.
- Check dependency vulnerabilities.
- Validate access control.
- Confirm backup and recovery procedures.

O mais interessante é que esses documentos também podem orientar um agente de revisão de segurança, responsável por verificar se a implementação realmente respeitou as especificações.

Por exemplo, podemos solicitar que ele procure problemas de autorização, exposição de dados, consultas inseguras, configurações inadequadas e dependências vulneráveis.

Mas é importante lembrar: uma IA pode ajudar bastante nessa revisão, porém não substitui testes de segurança, análise especializada ou auditorias quando o nível de risco da aplicação exige esse tipo de avaliação.

A parte que considero mais delicada: banco de dados e segurança

Existe uma coisa que eu particularmente não gosto de deixar totalmente nas mãos da IA: decisões importantes relacionadas à modelagem de dados e segurança.

A IA pode ajudar bastante a desenhar entidades, relacionamentos, migrations, índices e consultas. Mas considero fundamental revisar essas decisões individualmente.

No nosso exemplo, uma ordem de serviço pode estar relacionada a um cliente, um técnico responsável, diversos itens, serviços executados e um histórico de alterações.

É necessário entender como esses relacionamentos serão representados, quais informações são obrigatórias, quais podem ser nulas e quais restrições precisam existir.

Também precisamos saber quando faz sentido utilizar um banco relacional ou não relacional.

Um banco relacional pode ser mais adequado quando temos relacionamentos bem definidos, integridade referencial e operações transacionais importantes. Já um banco não relacional pode fazer sentido em cenários com estruturas de dados mais flexíveis ou necessidades específicas de escalabilidade e acesso.

Não existe uma escolha universalmente melhor.

Além disso, é necessário pensar em proteção de dados, controle de acesso, consultas parametrizadas, validação de entrada, permissões no banco e proteção contra exposição indevida de informações.

A IA pode gerar boa parte dessa estrutura, mas eu faria um pente-fino depois, olhando principalmente para modelagem, integridade dos dados, segurança e possíveis problemas de concorrência.

É uma parte em que prefiro gastar mais tempo entendendo o que foi feito do que simplesmente aceitar uma implementação aparentemente funcional.

E quanto à performance e à qualidade do código?

Outra coisa que considero importante é não deixar a IA tomar decisões de implementação sem entender os impactos que elas podem causar.

Por exemplo, quando falamos de performance em JavaScript, precisamos saber que determinadas operações podem ter custos diferentes dependendo do volume de dados e da frequência com que são executadas.

É importante entender quando utilizar determinados métodos de iteração, quando uma operação pode gerar processamento desnecessário, quando vale aplicar debounce ou throttle e quando faz sentido utilizar lazy loading.

No Back-end, temos questões como quantidade de consultas ao banco, índices, paginação, processamento de grandes volumes de dados, operações concorrentes e gerenciamento de recursos.

Não adianta a IA produzir um código aparentemente limpo se a implementação gera consultas desnecessárias, carrega dados que não serão utilizados ou executa operações pesadas em momentos inadequados.

Por isso, gosto da ideia de ter arquivos específicos de performance, segurança, convenções e arquitetura.

Eles funcionam como referências permanentes para as implementações, em vez de precisarmos repetir todas essas preocupações em cada conversa.

E existe outro detalhe: quanto mais modularizado o projeto, maior tende a ser a necessidade de planejamento e definição das interfaces entre os módulos. Modularização não significa simplesmente criar mais arquivos. Abstrair demais também pode aumentar a complexidade.

O objetivo é encontrar um equilíbrio entre isolamento, reutilização e simplicidade.

No final, o mais importante continua sendo entender o que estamos construindo

Uma coisa que tenho percebido é que a IA pode facilitar muito a implementação, mas também pode criar uma falsa sensação de domínio sobre aquilo que estamos desenvolvendo.

Você pode ter uma aplicação inteira gerada, com componentes organizados, serviços separados, APIs funcionando e documentação aparentemente completa. Mas será que realmente entende as decisões que foram tomadas?

Será que sabe explicar como os dados percorrem a aplicação? Por que determinada camada existe? Como funciona a autenticação? Onde estão as validações? Como as permissões são aplicadas? Quais são os possíveis gargalos? Como aquela estrutura se comportaria diante de um aumento de usuários?

Essas são perguntas que considero importantes.

E acho que existe uma relação direta entre a qualidade dos nossos prompts e o nosso conhecimento técnico.

Quando entendemos o que queremos construir, conseguimos fornecer instruções muito melhores. Sabemos questionar uma implementação, identificar inconsistências, definir restrições e perceber quando a IA está propondo algo que não faz sentido.

Não precisamos necessariamente escrever tudo sozinhos, mas precisamos ter conhecimento suficiente para avaliar aquilo que estamos delegando.

Também não acho que precisamos transformar qualquer tarefa em um processo complexo de especificação. Isso seria apenas trocar um problema por outro.

Para mim, o Vibe Coding continua sendo extremamente útil quando queremos resolver algo pontual, experimentar uma ideia ou acelerar uma implementação simples. Já o Spec-Driven faz muito mais sentido quando existe uma quantidade maior de regras, dependências, integrações e decisões arquiteturais envolvidas.

O interessante é que podemos começar uma funcionalidade com uma especificação bem definida e, durante a implementação, utilizar uma abordagem mais livre para resolver pequenos detalhes. Uma coisa não impede a outra.

No fim, acredito que o melhor caminho seja aprender a utilizar essas abordagens de acordo com o problema que estamos tentando resolver.

A IA já faz parte do desenvolvimento de software, e não vejo muito sentido em tentar ignorar isso. Mas também não acho interessante entregar todas as decisões a ela.

Quero continuar entendendo o código que estou produzindo, as tecnologias que estou utilizando e, principalmente, os motivos por trás de cada decisão.

Porque, independentemente de quanto a IA consiga implementar, a responsabilidade sobre aquilo que colocamos em produção continua sendo nossa.

Minha opinião: o Spec-Driven não deve ser encarado como burocracia ou documentação por documentação. Para mim, é uma forma de organizar o raciocínio antes de começar a implementar.

E o Vibe Coding não deve ser visto como desenvolvimento de baixa qualidade. É uma ferramenta de exploração e produtividade que funciona muito bem quando o problema permite esse nível de liberdade.

O que realmente faz diferença é saber quando precisamos de velocidade e quando precisamos de estrutura. E, principalmente, não confundir código gerado com conhecimento adquirido.

📰 Read the original article on Dev.to AI

Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.