create-sdd-ai-stack 0.1.17

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "create-sdd-ai-stack",
+  "version": "0.1.17",
+  "description": "Cria um projeto pronto para agentes de IA com Spec-Driven Development: regras SDD + template Next.js 16 + design system.",
+  "keywords": [
+    "sdd",
+    "spec-driven-development",
+    "ai",
+    "agent",
+    "agents",
+    "claude",
+    "cursor",
+    "nextjs",
+    "template",
+    "boilerplate",
+    "scaffold"
+  ],
+  "homepage": "https://github.com/marcelinosandroni/sdd-ai-stack#readme",
+  "bugs": {
+    "url": "https://github.com/marcelinosandroni/sdd-ai-stack/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marcelinosandroni/sdd-ai-stack.git"
+  },
+  "license": "MIT",
+  "author": "Marcelino Sandroni <marcelino.sandroni@gmail.com>",
+  "type": "module",
+  "bin": {
+    "create-sdd-ai-stack": "bin/create-sdd-ai-stack.mjs"
+  },
+  "main": "lib/scaffold.mjs",
+  "exports": {
+    ".": "./lib/scaffold.mjs",
+    "./scaffold": "./lib/scaffold.mjs",
+    "./constants": "./lib/constants.mjs",
+    "./check-links": "./lib/check-links.mjs",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "lib",
+    "template",
+    "AGENTS.md",
+    "APP.md",
+    "APP-STACK.md",
+    "ARCHITECTURE.md",
+    "DESIGN.md",
+    "NEXT.md",
+    "NODE.md",
+    "REACT.md",
+    "stacks",
+    "specs",
+    "docs",
+    "SKILLS",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "check:docs": "node SKILLS/check-docs/check-docs.mjs",
+    "check:pack": "npm pack --dry-run",
+    "version:patch": "npm version patch --git-tag-version",
+    "version:minor": "npm version minor --git-tag-version",
+    "version:major": "npm version major --git-tag-version",
+    "prepublishOnly": "npm run test && npm run check:pack"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "directories": {
+    "doc": "docs",
+    "lib": "lib",
+    "test": "tests"
+  }
+}

package/specs/BACKLOG.md

@@ -0,0 +1,24 @@
+# 📥 BACKLOG
+
+> Ideias soltas, débito técnico e explorações. **Nada aqui é promessa.**
+> Quando virar trabalho de verdade, promova para `specs/PLAN.md` como task.
+
+## 💡 Ideias
+
+- [ ] Definir regras de refinamento/produto em `docs/PLANNING.md` (artefatos visuais de planejamento)
+- [ ] Gerar PR template que force o preenchimento da evidência de teste
+- [ ] Script de release que abre PR automático do changelog
+- [ ] Storybook para os componentes de `src/shared/ui`
+- [ ] Integração com GitHub Actions para o Next.js DevTools MCP
+
+## 🧾 Débito técnico
+
+_(adicionado quando algo fica pra depois — com o motivo)_
+
+- [ ] Nenhum registrado ainda
+
+## 🗑️ Descartado
+
+_(ideias que testamos e não valem o custo — registre o porquê pra não repetir)_
+
+- _(vazio)_

package/specs/PLAN.md

@@ -0,0 +1,57 @@
+# 🎯 PLAN (O Cérebro do Projeto)
+
+> 🛑 **REGRA FIXA (Agente IA, LEIA ISSO ANTES DE CODAR):**
+> O desenvolvedor (Marcelino) tem TDAH. As tarefas AQUI devem ser **microscópicas**.
+> Se uma tarefa levar mais de 1 hora pra fazer, QUEBRE ELA EM DUAS.
+> Nunca pule um passo. Nunca comece o Passo 2 sem testar e commitar o Passo 1.
+> Atualize os status rigorosamente no final de cada prompt: `[ ]` (To Do), `[-]` (In Progress), `[x]` (Done).
+
+> **Existe exatamente UMA task `[-]` em todo momento.** Se houver duas, o agente parou errado.
+
+---
+
+## Fase atual: 0 — Bootstrap
+
+> Status: ✅ concluída (template + regras + CLI)
+> Histórico: [`history/phases/phase-0-bootstrap.md`](./history/phases/phase-0-bootstrap.md)
+
+### Como usar este arquivo
+
+1. Substitua o bloco abaixo pela fase atual do seu projeto.
+2. Nomeie a task `TASK-<FASE>-<NÚMERO>` e crie o arquivo em `specs/tasks/TASK-<FASE>-<NÚMERO>.md`
+   (use o [template](./tasks/TASK_TEMPLATE.md)).
+3. Marque `[-]` **antes** de começar a codar. Marque `[x]` **depois** de colar a evidência verde do terminal.
+4. Ao fechar a fase, arquive em `history/phases/` e gere a tag SemVer.
+
+---
+
+```markdown
+## Fase atual: [N] — [NOME DA FASE]
+
+[ ] - [TASK-1.1](./tasks/TASK-1.1.md) - [fazer]
+[-] - [TASK-1.2](./tasks/TASK-1.2.md) - [fazendo]   ← única task em progresso
+[ ] - [TASK-1.3](./tasks/TASK-1.3.md) - [fazer]
+
+### Critério de saída da fase
+- [ ] Todas as tasks `[x]` com evidência de teste colada
+- [ ] `npm run typecheck && npm run lint && npm run test && npm run build` verdes
+- [ ] `docs/CHANGELOG.md` atualizado
+- [ ] `specs/history/phases/phase-N-finished.md` escrito
+- [ ] Tag SemVer gerada
+```
+
+---
+
+## 📋 Checklist de entrega (cole no fim de cada task)
+
+```markdown
+**Evidência:**
+- `npm run typecheck` → exit 0
+- `npm run lint` → 0 erros
+- `npm run test` → N passed
+- `npm run test:e2e` → N passed
+- `npm run build` → ✓ Compiled successfully
+
+**Arquivos tocados:** (liste — máximo 5 por passo)
+**Commit:** `tipo(escopo): descrição. (Agent: <Ferramenta> - <Modelo>)`
+```

package/specs/ROADMAP.md

@@ -0,0 +1,35 @@
+# 🗺️ ROADMAP
+
+> Visão macro. **Não use isto para trabalhar** — use [`PLAN.md`](./PLAN.md) para a task de agora.
+
+## Fase 0 — Bootstrap ✅
+
+Template Next.js 16, regras SDD, design system, CLI `npx create-sdd-ai-stack`, instalação por submodule.
+
+## Fase 1 — Fundação do produto
+
+Entregar o primeiro slice de ponta a ponta (vertical): domínio → use case → repository → rota → UI → teste.
+
+## Fase 2 — Escala
+
+Multi-tenant, autorização por papel, auditoria, filas, observabilidade.
+
+## Fase 3 — Produto
+
+Billing, onboarding, growth loop, o que o negócio pedir.
+
+---
+
+## 🧭 Como este roadmap conversa com o PLAN
+
+```text
+ROADMAP.md   →  macro, anos              (visão)
+    ↓
+PLAN.md      →  esta semana              (1 task por vez)
+    ↓
+tasks/       →  esta task, em detalhe     (micro-passos)
+    ↓
+commit       →  esta task, um passo       (evidência)
+```
+
+> Regra: **nenhuma task entra no PLAN sem existir no ROADMAP** (nem que seja uma linha só).

package/specs/history/phases/phase-0-bootstrap.md

@@ -0,0 +1,67 @@
+# ✅ Fase 0 — Bootstrap (CONCLUÍDA)
+
+> **Período:** reestruturação do core SDD
+> **Resultado:** template Next.js 16 funcional + regras Next-first + CLI `npx create-sdd-ai-stack`
+
+---
+
+## 🧭 O que era
+
+- Stack focada em **React (Vite) + Node.js** (monorepo `client/` + `server/`)
+- Sem template de projeto
+- Sem regras de Next.js
+- Sem CLI / pacote npm
+- Regras espalhadas na raiz
+- Design system genérico (Vercel/Linear padrão)
+
+## 🧭 O que virou
+
+| Antes | Depois |
+| --- | --- |
+| React + Vite como padrão | **Next.js 16 (App Router)** como padrão |
+| `NODE.md` genérico | `NODE.md` como **complemento** (worker/cron/fila) |
+| `REACT.md` como doc de frontend | `REACT.md` como **complemento** (Server-First) |
+| — | **`NEXT.md`** com 11 seções de regra |
+| regras soltas na raiz | **`stacks/`** (typescript, tailwind, shadcn, testing, database, ai, git, ci) |
+| `DESIGN.md` genérico | **`DESIGN.md`** Executive Engineering com tokens completos |
+| — | **`APP-STACK.md`** (ponteiro de stack) |
+| — | **`template/next/`** — Next.js 16 completo e testado |
+| — | **CLI npm `create-sdd-ai-stack`** |
+| — | **SKILL `install-submodule`** para projeto existente |
+| — | **SKILL `check-docs`** (valida links entre documentos) |
+| — | **`.github/workflows/ci.yml`** que revalida o template a cada push |
+
+## 🧪 Evidência
+
+```text
+# CLI e documentação (21 testes)
+npm test  →  tests 20 | pass 20 | fail 0
+node SDD/SKILLS/check-docs/check-docs.mjs  →  ✓ 29 documentos, links OK
+
+# Template gerado (evidence real)
+npm run typecheck  →  exit 0
+npm run lint       →  Checked 28 files, 0 erros, 0 warnings
+npm run test       →  Test Files 1 passed, Tests 3 passed
+npm run test:e2e   →  4 passed
+npm run build      →  ✓ Compiled successfully (Turbopack, Cache Components)
+                     ┌ ○ /   ├ ○ /_not-found   └ ○ /app   ƒ Proxy
+```
+
+## 🐛 Bugs encontrados e corrigidos durante a validação
+
+1. `import type { CreateExampleInput }` de arquivo errado (typecheck pegou)
+2. Import de path errado no `container.ts` do slice (typecheck pegou)
+3. `error.tsx` sem `"use client"` (build pegou)
+4. `reactCompiler: true` sem `babel-plugin-react-compiler` instalado (build pegou)
+5. `biome.json` no schema antigo (`recommended` → `preset`) (lint pegou)
+6. `prepare: "husky || true"` quebrava `npm install` no Windows (install pegou)
+7. `proxy.ts` redirecionava `/` e escondia a landing marketing (E2E pegou)
+8. Dupla rota em `/` (`app/page.tsx` + `(marketing)/page.tsx`) (E2E pegou)
+
+> **Isso é a razão de existir a regra "prova de vida anti-alucinação" do AGENTS.md.**
+
+## 🏷️ Release
+
+```bash
+git tag v0.1.17
+```

package/specs/tasks/TASK_TEMPLATE.md

@@ -0,0 +1,46 @@
+# ✅ TASK [NOME DA TASK]
+
+> 🛑 **REGRA FIXA (Agente IA, LEIA ISSO):**
+> 1. O dev (Marcelino) tem TDAH, cegueira temporal e zero paciência pra lixo.
+> 2. Se a task inteira levar mais de 1 hora, QUEBRE EM DUAS TASKS AGORA.
+> 3. Entregue o código de um passo, espere ele testar, e SÓ DEPOIS vá para o próximo.
+> 4. O nome do arquivo da TASK deve ser sempre `TASK-PHASE-TASK` (ex: `TASK-1.1.md`).
+> 5. Manter sempre na pasta `tasks/` e subpasta da fase (`tasks/phase-1/`).
+> 6. **PROIBIDO EDITAR ACIMA DO TRAÇO.** Você SÓ tem permissão para preencher os dados ABAIXO da linha `---`.
+
+---
+
+## 🎯 Objetivo da Task
+
+[1 linha. O que você quer fazer. Ex: "Criar o botão de gerar vídeo IA na feature video".]
+
+## 📂 Onde mexer
+
+- [ ] `src/features/[x]/application/` — regra de negócio
+- [ ] `src/features/[x]/infrastructure/` — repo/adaptador
+- [ ] `src/features/[x]/actions.ts` — entrada de escrita
+- [ ] `src/features/[x]/ui/` — componente
+- [ ] `src/app/...` — rota (só roteia)
+- [ ] `tests/` — testes
+
+## 🛠️ Micro-Passos (Checklist Dopamina)
+
+*(Passos RIDICULAMENTE pequenos. Máximo 5 por task.)*
+
+- [ ] Passo 1: [Ex: Criar a interface `IVideo.ts` em `domain/`]
+- [ ] Passo 2: [Ex: Criar o layout burro do botão]
+- [ ] Passo 3: [Ex: Ligar o botão no hook de DI]
+- [ ] Passo 4: [Ex: Teste unit do use case]
+- [ ] Passo 5: [Ex: E2E do fluxo]
+
+## 🏁 Definition of Done (Critério de Sucesso)
+
+- [ ] `npm run typecheck` → exit 0
+- [ ] `npm run lint` → 0 erros, 0 warnings
+- [ ] `npm run test` → todo verde
+- [ ] `npm run test:e2e` → todo verde
+- [ ] `npm run build` → ✓ Compiled successfully
+- [ ] Zero `any` no código novo
+- [ ] Cores/estilos usando tokens do `DESIGN.md` (se tocou em UI)
+- [ ] Evidência verde colada na resposta
+- [ ] `specs/PLAN.md` atualizado para `[x]`

package/src/cli.mjs

@@ -0,0 +1,119 @@
+import { DEFAULT_SUBMODULE_URL, DEFAULT_TEMPLATE, TEMPLATES } from "../lib/constants.mjs";
+
+export const HELP = `
+create-sdd-ai-stack — projeto pronto para agentes de IA (Spec-Driven Development)
+
+USO
+  npx create-sdd-ai-stack <nome-do-app> [opções]
+
+EXEMPLO
+  npx create-sdd-ai-stack meu-dashboard
+  npx create-sdd-ai-stack meu-dashboard --no-install
+  npx create-sdd-ai-stack meu-dashboard --submodule
+  npx create-sdd-ai-stack meu-dashboard --rules-only
+
+OPÇÕES
+  --template <${TEMPLATES.join("|")}|none>   Template de projeto (padrão: ${DEFAULT_TEMPLATE})
+  --rules-only            Instala só as regras (sem app), em ./SDD
+  --submodule [url]       Instala ./SDD como git submodule (padrão: repo oficial)
+  --no-install            Não roda npm install
+  --install               Roda npm install (padrão: não roda)
+  --git / --no-git        git init + primeiro commit (padrão: não roda)
+  --shortcuts <auto|stub|symlink>
+                          Como criar os atalhos da raiz (padrão: auto)
+  -y, --yes               Não pede confirmação
+  -h, --help              Esta ajuda
+  -v, --version           Versão
+
+O QUE É CRIADO
+  <app>/
+  ├── src/ …            template Next.js 16 (App Router, Tailwind v4, Biome, Vitest)
+  ├── SDD/              as regras: AGENTS.md, NEXT.md, DESIGN.md, stacks/, specs/…
+  ├── AGENTS.md         atalho → ./SDD/AGENTS.md
+  ├── CLAUDE.md, GEMINI.md, .cursorrules, .github/copilot-instructions.md …
+  └── package.json
+
+DOCS
+  https://github.com/marcelinosandroni/sdd-ai-stack
+`;
+
+export function parseArgs(argv) {
+  const opts = {
+    name: null,
+    template: DEFAULT_TEMPLATE,
+    install: false,
+    git: false,
+    submodule: null,
+    rulesOnly: false,
+    shortcutMode: "auto",
+    help: false,
+    version: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = () => argv[++i];
+
+    switch (arg) {
+      case "-h":
+      case "--help":
+        opts.help = true;
+        break;
+      case "-v":
+      case "--version":
+        opts.version = true;
+        break;
+      case "-y":
+      case "--yes":
+        break;
+      case "--rules-only":
+        opts.rulesOnly = true;
+        opts.template = "none";
+        break;
+      case "--install":
+        opts.install = true;
+        break;
+      case "--no-install":
+        opts.install = false;
+        break;
+      case "--git":
+        opts.git = true;
+        break;
+      case "--no-git":
+        opts.git = false;
+        break;
+      case "--submodule": {
+        const value = argv[i + 1];
+        if (value && !value.startsWith("-")) {
+          opts.submodule = value;
+          i++;
+        } else {
+          opts.submodule = DEFAULT_SUBMODULE_URL;
+        }
+        break;
+      }
+      case "--template": {
+        const value = next();
+        if (!value) throw new Error("--template exige um valor");
+        if (value !== "none" && !TEMPLATES.includes(value)) {
+          throw new Error(`Template inválido: "${value}". Use: ${TEMPLATES.join(", ")} ou none.`);
+        }
+        opts.template = value;
+        break;
+      }
+      case "--shortcuts": {
+        const value = next();
+        if (!["auto", "stub", "symlink"].includes(value)) {
+          throw new Error(`--shortcuts inválido: "${value}". Use: auto, stub, symlink.`);
+        }
+        opts.shortcutMode = value;
+        break;
+      }
+      default:
+        if (arg.startsWith("-")) throw new Error(`Opção desconhecida: ${arg}`);
+        if (!opts.name) opts.name = arg;
+    }
+  }
+
+  return opts;
+}

package/stacks/README.md

@@ -0,0 +1,33 @@
+# 🧱 STACKS — REGRAS POR LINGUAGEM E FERRAMENTA
+
+> **Leia o índice, depois abra só o arquivo do que você está tocando.**
+> Stack padrão do projeto: **[Next.js](../NEXT.md)**. React e Node são complementos.
+
+## 📇 Índice
+
+| Arquivo | Quando abrir |
+| --- | --- |
+| [typescript.md](./typescript.md) | Tipos, interfaces, genéricos, strict mode |
+| [tailwind.md](./tailwind.md) | Estilo, tokens, classes utilitárias |
+| [shadcn.md](./shadcn.md) | Componentes de UI, primitives, variações |
+| [testing.md](./testing.md) | Unit, integração, E2E, cobertura |
+| [database.md](./database.md) | Prisma, migrations, queries, transações |
+| [ai.md](./ai.md) | Integrações com LLM/IA, streaming, tokens |
+| [git.md](./git.md) | Commits, branches, PRs, releases |
+| [ci.md](./ci.md) | GitHub Actions, lint, typecheck, deploy |
+
+## 🎯 Módulos de regra fora desta pasta
+
+| Arquivo | Escopo |
+| --- | --- |
+| [../NEXT.md](../NEXT.md) | Next.js 16 (App Router, RSC, Cache Components) — **PADRÃO** |
+| [../NODE.md](../NODE.md) | Node.js puro (workers, cron, filas, scripts) |
+| [../REACT.md](../REACT.md) | React (hooks, estado, composição) |
+| [../DESIGN.md](../DESIGN.md) | Design system completo (tokens, tipografia, componentes) |
+| [../ARCHITECTURE.md](../ARCHITECTURE.md) | Arquitetura global e vertical slices |
+
+## 🚫 Regra de ouro
+
+> **Antes de instalar qualquer lib, prove que o nativo resolve.**
+> `fetch` > axios. `<dialog>` > lib de modal. CSS > tailwind plugin.
+> Se a lib entrar, ela entra com uma nota em `docs/CHANGELOG.md` explicando o porquê.

package/stacks/ai.md

@@ -0,0 +1,52 @@
+# 🤖 AI / LLM
+
+> Regras para integrar modelos de linguagem. Custo, latência e segurança importam tanto quanto a resposta.
+
+## 🚨 Regras não-negociáveis
+
+1. **Chamada de LLM NUNCA acontece dentro de um Server Component.** Vai para uma Server Action ou um use case em `application/`.
+2. **NUNCA exponha a `OPENAI/ANTHROPIC_API_KEY` no client.** Sempre `import "server-only"` no módulo.
+3. **Toda chamada a LLM tem `timeout` e tratamento de erro.** O usuário nunca fica em loading eterno.
+4. **Streaming para UX longa.** Resposta de LLM > 1s é streaming (ver AI SDK / `ReadableStream`).
+5. **Limite de tokens SEMPRE explícito** (`max_tokens`/`maxOutputTokens`). Nunca deixe o modelo "falar à vontade".
+6. **Custo é requisito, não detalhe.** Modelos caros (Opus/GPT-4o) só com justificativa em `docs/CHANGELOG.md`.
+7. **Nada de dado sensível no prompt** sem necessidade (LGPD).Anonimize antes.
+
+## 🧩 Padrão de chamada
+
+```ts
+// features/chat/application/generate-reply.ts
+import "server-only";
+import { generateText } from "ai";
+
+export async function generateReply(prompt: string) {
+  const { text } = await generateText({
+    model: "openai/gpt-4o-mini",
+    prompt,
+    maxTokens: 1024,          // SEMPRE limite
+    abortSignal: AbortSignal.timeout(15_000),  // SEMPRE timeout
+  });
+  return text;
+}
+```
+
+## 🎯 Escolha de modelo (custo vs qualidade)
+
+| Caso | Modelo típico |
+| --- | --- |
+| Classificar/extrair/formatar | mini / small |
+| Copy de marketing, resumo | mini / small |
+| Raciocínio complexo, código | big / Opus |
+| Embedding | `*-embed` dedicado |
+
+## 🛡️ Segurança
+
+- **Valide a saída do LLM antes de usar.** Saída é input não-confiável. Zod no retorno, sempre.
+- **Never inlined secrets em prompt de cliente.**
+- **Rate limit por usuário/rota** em qualquer endpoint que chame LLM (evite key draining).
+- **Log de chamada** com modelo + tokens (custo visível em produção).
+
+## 📊 O que observar
+
+- **Streaming vs não:** UX (streaming) vs complexidade.
+- **Caching:** mesmo prompt → cache sem custo. Use `'use cache'` quando a entrada for estável.

package/stacks/ci.md

@@ -0,0 +1,59 @@
+# ⚙️ CI / CD
+
+## 🚨 Regras não-negociáveis
+
+1. **Pipeline mínimo obrigatório em todo repo:** `lint` → `typecheck` → `test` → `build`. Nessa ordem.
+2. **CI é o portão.** Se passou local mas falha no CI, o CI está certo.
+3. **Node e pnpm/npm fixados por versão** (Node 20.9+ para Next 16). Sem `latest` em CI.
+4. **Deploy só da `main`.** Feature branch nunca faz deploy de produção.
+5. **Segredo só via secrets do repositório.** Nunca no código do workflow.
+6. **Ambiente de preview por PR** é obrigatório (qualidade de review).
+
+## 🔧 Pipeline padrão (GitHub Actions)
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+on:
+  pull_request: { branches: [main] }
+  push: { branches: [main] }
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22, cache: npm }
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run typecheck
+      - run: npm run test:unit -- --run
+      - run: npm run build
+```
+
+## 📦 Deploy (Vercel / Node)
+
+- **Vercel:** conecte o repo. Preview por PR é automático. `SDD/` é ignorado no build.
+- **Node (workers/CLI):** build no CI, artefato, deploy no `main` com approval manual.
+
+## 🔒 Segurança no pipeline
+
+- `npm audit --production` como gate de aviso (não bloqueia minor).
+- Dependabot ativo.
+- Nunca logar `.env`/tokens no output do job.
+
+## 🏷️ Release
+
+1. Fechou fase → tag SemVer (`vX.Y.Z`).
+2. CI roda em tag → build de release.
+3. Changelog atualizado ([../docs/CHANGELOG.md](../docs/CHANGELOG.md)).
+
+## 🚫 Anti-padrões
+
+| ❌ | ✅ |
+| --- | --- |
+| `continue-on-error: true` em tudo | Deixar o gate barrar de verdade |
+| `npm install` (sem lock) em CI | `npm ci` |
+| Deploy manual sem aprovação | Preview + approval em main |
+| Rodar build sem typecheck | build sempre depois de typecheck |

package/stacks/database.md

@@ -0,0 +1,56 @@
+# 🗄️ DATABASE
+
+> Padrão: **Prisma ORM + PostgreSQL**. Acesso **sempre** dentro de `features/*/infrastructure/` ou `shared/server/db.ts`.
+
+## 🚨 Regras não-negociáveis
+
+1. **Query fora de `infrastructure/` é PROIBIDA.** O domínio só conhece a interface `I*Repository`.
+2. **`select` explícito em toda query.** Nunca `findMany()` sem filtro de colunas. Vaza dado e pesa payload.
+3. **Toda query que filtra por usuário filtra por `userId`/`tenantId`.** Autorização no dado, não na UI.
+4. **N+1 é proibido.** Use `include` aninhado ou `Promise.all` com mapa explícito.
+5. **Escrita que precisa de 2+ tabelas = `prisma.$transaction`.** Sem exceções.
+6. **Migration é feita via `npx prisma migrate dev --name <descricao>`** e vai pro repo. **Proibido `db push` em produção.**
+7. **Índice todo campo usado em `where` ou `orderBy` quente.** Antes de reclamar de performance no banco, indexa.
+
+## 🧱 Onde fica o quê
+
+```text
+features/billing/
+├── domain/IBillingRepository.ts     # contrato puro (interface)
+└── infrastructure/
+    ├── billing-repository.ts        # implementa a interface com Prisma
+    └── billing.mapper.ts            # <row do Prisma> <-> <entidade de domínio>
+```
+
+## 🧩 Exemplo
+
+```ts
+// infrastructure/billing-repository.ts
+import "server-only";
+import { db } from "@/shared/server/db";
+import type { IBillingRepository } from "../domain/IBillingRepository";
+
+export class PrismaBillingRepository implements IBillingRepository {
+  async findActiveByUser(userId: string) {
+    return db.subscription.findFirst({
+      where: { userId, status: "ACTIVE" },   // SEMPRE filtra por userId
+      select: { id: true, planId: true, status: true, renewsAt: true },
+    });
+  }
+}
+```
+
+## 🚫 Proibido
+
+| Padrão | Por quê | Faça |
+| --- | --- | --- |
+| `db.x.findMany()` sem `select` | Vaza dado, pesa payload | Sempre `select` |
+| Query sem filtro de dono | Vazamento entre tenants | `where: { userId }` |
+| `db` importado em Server Component direto | Quebra o slice | via `queries.ts` do feature |
+| `db push` / `db seed` em prod | perde dado | `migrate deploy` |
+| `$transaction` aninhado profundo | lock demais | achatar /Batch |
+
+## 🧪 Testes
+
+- **Integração:** use **banco de verdade separado** (ou SQLite/Mongo in-memory via adapter). Mock do client Prisma só em unit.
+- **Migrations:** rode `migrate deploy` no setup do CI antes dos testes de integração.