SpecForge — Framework de Especificação para IA Construir Software

Um conjunto enxuto de artefatos em Markdown que o engenheiro de software produz para que uma IA consiga gerar um sistema completo (front-end + back-end) sem ambiguidade, sem alucinação e sem pontas soltas.

SpecForge combina o que há de mais eficaz hoje: DDD (núcleo semântico), BDD (comportamento verificável), UX-first (telas e jornadas reais), Ágil/evolutivo (modelagem leve, viva) e Arquitetura orientada a eventos (quando faz sentido). É flexível: você pode pular artefatos que não fazem sentido para o seu cenário (ex.: não quer modelar classes nem banco — basta omitir 08-data-model.md e a IA inferirá entidades a partir do domínio e dos comportamentos, registrando o que assumiu).

---

Princípios

1. Uma fonte de verdade por dimensão. Cada arquivo cobre uma camada distinta — sem sobreposição.
2. Linguagem ubíqua obrigatória. Todo termo usado em qualquer arquivo precisa estar no 02-glossario.md.
3. Comportamento antes de implementação. Cenários Gherkin valem mais do que descrições em prosa.
4. Ambiguidade é dívida. Toda dúvida vai para 14-open-questions.md — a IA nunca "chuta", ela consulta.
5. Modelagem evolutiva. Os arquivos vivem com o produto; versionados em Git como código.
6. Flexível por omissão. Artefatos ausentes = liberdade controlada para a IA inferir, desde que ela registre o que assumiu.

---

Ordem de leitura (e de produção)

#	Arquivo	O que define	Obrigatório?
00	00-visao.md	Problema, público, valor, métricas de sucesso	Sim
01	01-escopo.md	O que está dentro e o que está fora	Sim
02	02-glossario.md	Linguagem ubíqua (DDD)	Sim
03	03-personas-jornadas.md	Personas e jornadas de usuário	Sim
04	04-dominio.md	Bounded contexts, entidades, agregados, invariantes	Sim
05	05-regras-de-negocio.md	Regras explícitas, fórmulas, exceções	Sim
06	06-features.md	Catálogo de funcionalidades priorizadas	Sim
07	07-comportamentos.bdd.md	Cenários Gherkin (Given/When/Then)	Sim
08	08-data-model.md	Entidades persistidas, relações, restrições	Opcional
09	09-telas.md	Inventário de telas, componentes, estados, validações	Sim (se UI)
10	10-api-contracts.md	Endpoints, payloads, eventos	Opcional
11	11-arquitetura.md	C4-lite, decisões, integrações, limites	Sim
12	12-nao-funcionais.md	Performance, segurança, LGPD, observabilidade	Sim
13	13-aceitacao.md	Definition of Done, matriz de testes	Sim
14	14-open-questions.md	Premissas, dúvidas, decisões pendentes	Sim (vivo)

Dica: Comece pelos 00–07. Esses sete arquivos sozinhos já permitem uma IA gerar um MVP funcional e coerente.

---

Cenário "sem modelagem de banco/classes"

Se você não quer especificar classes ou esquema de banco:

• Omita 08-data-model.md e (opcionalmente) 10-api-contracts.md.
• Reforce 04-dominio.md listando entidades como conceitos (nome, propósito, propriedades essenciais, invariantes).
• A IA, ao consumir os artefatos, irá:
  1. Derivar entidades adicionais necessárias à lógica.
  2. Registrar essas entidades inferidas em um arquivo gerado 99-inferencias.md.
  3. Pedir confirmação antes de implementar qualquer coisa que toque dado sensível ou regra crítica.

Esse comportamento é garantido pela skill em skill/SKILL.md, que você instala na IA antes de pedir a geração do código.

---

Como usar

1. Copie a pasta templates/ para o seu repositório (ex.: docs/spec/).
2. Preencha os artefatos na ordem 00 → 14. Não pule o glossário.
3. Instale a skill skill/SKILL.md na IA (Claude, Cursor, etc.).
4. Peça: "Leia os artefatos em docs/spec/ seguindo a SKILL e gere o sistema."
5. A IA irá: validar consistência → listar lacunas → propor entidades inferidas → gerar código por feature → marcar cada cenário BDD como coberto.

---

Estrutura do repositório

specforge/
├── README.md                ← este arquivo
├── templates/               ← templates prontos para copiar
│   ├── 00-visao.md
│   ├── 01-escopo.md
│   ├── 02-glossario.md
│   ├── 03-personas-jornadas.md
│   ├── 04-dominio.md
│   ├── 05-regras-de-negocio.md
│   ├── 06-features.md
│   ├── 07-comportamentos.bdd.md
│   ├── 08-data-model.md
│   ├── 09-telas.md
│   ├── 10-api-contracts.md
│   ├── 11-arquitetura.md
│   ├── 12-nao-funcionais.md
│   ├── 13-aceitacao.md
│   └── 14-open-questions.md
└── skill/
    └── SKILL.md             ← instruções para a IA consumir os artefatos