npm - create-sdd-ai-stack - Versions diffs - 0.1.17 - Mend

create-sdd-ai-stack 0.1.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (72) hide show

package/AGENTS.md +164 -0
package/APP-STACK.md +31 -0
package/APP.md +46 -0
package/ARCHITECTURE.md +115 -0
package/DESIGN.md +219 -0
package/LICENSE +21 -0
package/NEXT.md +345 -0
package/NODE.md +107 -0
package/REACT.md +92 -0
package/README.md +260 -0
package/SKILLS/check-docs/SKILL.md +24 -0
package/SKILLS/check-docs/check-docs.mjs +56 -0
package/SKILLS/create-feature/SKILL.md +40 -0
package/SKILLS/create-feature/create-feature.mjs +128 -0
package/SKILLS/create-feature.sh +112 -0
package/SKILLS/install-submodule/SKILL.md +42 -0
package/SKILLS/install-submodule/install-submodule.mjs +119 -0
package/bin/create-sdd-ai-stack.mjs +93 -0
package/docs/CHANGELOG.md +209 -0
package/docs/PLANNING.md +68 -0
package/docs/PRODUCT.md +76 -0
package/docs/RELEASE.md +332 -0
package/lib/check-links.mjs +42 -0
package/lib/constants.mjs +60 -0
package/lib/scaffold.mjs +253 -0
package/package.json +80 -0
package/specs/BACKLOG.md +24 -0
package/specs/PLAN.md +57 -0
package/specs/ROADMAP.md +35 -0
package/specs/history/phases/phase-0-bootstrap.md +67 -0
package/specs/tasks/TASK_TEMPLATE.md +46 -0
package/src/cli.mjs +119 -0
package/stacks/README.md +33 -0
package/stacks/ai.md +52 -0
package/stacks/ci.md +59 -0
package/stacks/database.md +56 -0
package/stacks/git.md +51 -0
package/stacks/shadcn.md +52 -0
package/stacks/tailwind.md +65 -0
package/stacks/testing.md +74 -0
package/stacks/typescript.md +58 -0
package/template/next/.env.example +4 -0
package/template/next/README.md +47 -0
package/template/next/biome.json +36 -0
package/template/next/gitignore +32 -0
package/template/next/next.config.ts +12 -0
package/template/next/package.json +47 -0
package/template/next/playwright.config.ts +21 -0
package/template/next/postcss.config.mjs +7 -0
package/template/next/src/app/(app)/app/page.tsx +18 -0
package/template/next/src/app/(app)/error.tsx +30 -0
package/template/next/src/app/(app)/layout.tsx +25 -0
package/template/next/src/app/(marketing)/page.tsx +73 -0
package/template/next/src/app/globals.css +437 -0
package/template/next/src/app/layout.tsx +41 -0
package/template/next/src/app/not-found.tsx +11 -0
package/template/next/src/features/example/actions.ts +43 -0
package/template/next/src/features/example/application/create-example.usecase.ts +26 -0
package/template/next/src/features/example/container.ts +16 -0
package/template/next/src/features/example/domain/IExampleRepository.ts +11 -0
package/template/next/src/features/example/domain/example.schema.ts +18 -0
package/template/next/src/features/example/infrastructure/example.repository.ts +26 -0
package/template/next/src/features/example/ui/create-example-form.tsx +56 -0
package/template/next/src/proxy.ts +23 -0
package/template/next/src/shared/lib/cn.ts +6 -0
package/template/next/src/shared/server/auth.ts +32 -0
package/template/next/src/shared/server/env.ts +14 -0
package/template/next/src/shared/ui/index.ts +3 -0
package/template/next/tests/e2e/routes.spec.ts +34 -0
package/template/next/tests/unit/create-example.test.ts +55 -0
package/template/next/tsconfig.json +37 -0
package/template/next/vitest.config.ts +19 -0

package/NEXT.md ADDED Viewed

@@ -0,0 +1,345 @@
+# ⚛️ NEXT.JS — REGRAS OFICIAIS (STACK PADRÃO)
+> **STACK PADRÃO DESTE TEMPLATE.** Toda aplicação nova sai em Next.js.
+> Node.js puro (workers, CLIs, cron, webhooks) é **complemento**, não o padrão — ver [NODE.md](./NODE.md).
+> Alvo de versão: **Next.js 16** (App Router, React 19.2, Turbopack).
+---
+## 🧭 1. ROTEADOR (leia só o que precisa)
+| Você está fazendo...                              | Leia                     |
+| ------------------------------------------------- | ------------------------ |
+| Criando página/rota                              | §2 Estrutura, §3 Server |
+| Buscando dados                                    | §4 Data                  |
+| Escrevendo mutação (create/update/delete)         | §5 Server Actions        |
+| Mexendo em cache                                  | §6 Cache Components      |
+| Autenticação / rota protegida                    | §7 Segurança             |
+| Criando API para terceiro                        | §8 Route Handlers        |
+| Formulário                                        | §9 Forms                 |
+| Metadata / SEO                                    | §10 Metadata             |
+| Desempenho                                        | §11 Performance          |
+| Testes                                            | [stacks/testing.md](./stacks/testing.md) |
+---
+## 📂 2. ESTRUTURA DE PASTAS
+Enxuta, Next-first. **Não existe `client/` nem `server/` separado** — o App Router já é a fronteira.
+```text
+src/
+├── app/                    # ROTEAMENTO (só isto é "framework")
+│   ├── (marketing)/        # Route groups (não afetam a URL)
+│   ├── (app)/              # Área logada
+│   │   ├── layout.tsx
+│   │   ├── page.tsx
+│   │   ├── loading.tsx     # Skeleton/Suspense fallback
+│   │   ├── error.tsx       # Error Boundary (precisa ser "use client")
+│   │   └── not-found.tsx
+│   ├── api/                # Route Handlers (exceção, não padrão)
+│   ├── proxy.ts            # Network boundary (substitui middleware.ts)
+│   ├── layout.tsx          # Root layout: <html>, fontes, metadata base
+│   └── globals.css         # Tokens do DESIGN.md via @theme
+│
+├── features/               # 🌟 SLICES DE DOMÍNIO (a fatia vertical)
+│   └── billing/
+│       ├── domain/         # Entidades, value objects, contratos (I*.ts)
+│       ├── application/    # Use cases, services, orquestração
+│       ├── infrastructure/ # Prisma, HTTP clients, filas, storage
+│       ├── actions.ts      # Server Actions (entrypoint de mutação)
+│       ├── queries.ts      # Leitura (entrypoint de query)
+│       ├── schemas.ts      # Zod: validação de entrada
+│       └── ui/             # Componentes do domínio (client ou server)
+│
+├── shared/                 # Genérico compartilhado entre features
+│   ├── ui/                 # Design system (shadcn + customizados)
+│   ├── lib/                # Helpers puros (cn, formatadores)
+│   ├── server/             # server-only: db, auth, config, logger
+│   └── types/              # Tipos GLOGAIS de infra (não de domínio)
+│
+├── proxy.ts                # OU na raiz, se preferir (só 1 arquivo)
+└── DI/
+    └── container.ts        # Container de DI manual (server-side)
+```
+### Regras de ouro da estrutura
+1. **`app/` só roteia.** Ele delega para `features/`. Nenhuma regra de negócio dentro de `page.tsx`.
+2. **Feature não importa feature.** Precisa de algo de outra? Promova a extração para `shared/` ou evento de domínio.
+3. **Interface (`I*.ts`) mora dentro do slice, junto da implementação.** Proibido `src/types/` global de domínio.
+4. **UI de domínio vive em `features/*/ui/`.** `shared/ui/` é para o que é genérico de verdade (Button, Modal, Input).
+5. **Route Handler é exceção.** Pense 10x antes de criar `/api`. Server Action é o padrão para mutação da própria UI.
+---
+## 🧊 3. SERVER-FIRST (a regra que mais economiza bundle)
+| Situação                              | Diretiva          | Onde fica                    |
+| ------------------------------------- | ----------------- | ---------------------------- |
+| Layout, página, listagem, form estático | (nenhuma)         | **Server Component**         |
+| Busca de dados no render              | (nenhuma)         | **Server Component**         |
+| Botão com `onClick`, input controlado | `"use client"`    | Client Component             |
+| `useState`, `useEffect`, `useRef`     | `"use client"`    | Client Component             |
+| Integração com lib de browser         | `"use client"`    | Client Component             |
+### Regras
+1. **O padrão é Server Component.** `"use client"` é uma decisão deliberada, não automática.
+2. **O `"use client"` só pode estar na folha mais baixa possível.** Se ele sobe, ele **arrasta a árvore inteira** para o bundle do cliente. Errou? Extraia o trecho interativo para um arquivo só.
+3. **Client Component só pode passar para Server Component: `children`, `action` (bound), e dados serializáveis.** Jamais uma função comum, nunca um objeto de DI.
+4. **Proibido `useEffect` para buscar dados.** Se precisa buscar, é Server Component ou Server Action.
+5. **Event handler que é uma requisição ao servidor → `<form action={serverAction}>`**, não `onClick` + `fetch`.
+### Exemplo do padrão "folha cliente"
+```tsx
+// features/billing/ui/subscribe-button.tsx
+"use client";
+import { useFormStatus } from "react-dom";
+import { subscribeAction } from "../actions";
+// ✅ FOLHA: só isto vai pro bundle do cliente
+export function SubscribeButton({ planId }: { planId: string }) {
+  return (
+    <form action={subscribeAction.bind(null, planId)}>
+      <button type="submit" className="btn-primary">
+        <SubmitLabel />
+      </button>
+    </form>
+  );
+}
+function SubmitLabel() {
+  const { pending } = useFormStatus();
+  return <span>{pending ? "Processando..." : "Assinar"}</span>;
+}
+```
+```tsx
+// app/(app)/billing/page.tsx  — continua NO SERVER
+import { SubscribeButton } from "@/features/billing/ui/subscribe-button";
+export default async function BillingPage() {
+  const subscription = await getSubscription(); // direto, sem useEffect
+  return (
+    <main>
+      <PlanList />
+      <SubscribeButton planId={subscription.planId} />
+    </main>
+  );
+}
+```
+---
+## 📦 4. DATA LAYER
+1. **Toda leitura passa por `features/*/queries.ts`.** Nenhum `fetch`/Prisma direto em `page.tsx`.
+2. **Query = função `async` simples.** Sem react-query no server. O cache é do Next (§6).
+3. **Client-side com estado remoto e interativo → TanStack Query.** Mas a fonte da verdade é o servidor; se não precisa de optimistic/background refetch, nem use.
+4. **`unstable_cache` / `revalidate` do modelo antigo = PROIBIDO.** Vai para `'use cache'`.
+5. **Tipagem no limite:** todo retorno de repository/query é tipado. `any` é proibido em fronteira.
+```ts
+// features/billing/queries.ts
+import "server-only";
+import { db } from "@/shared/server/db";
+import { cache } from "react";
+export const getSubscription = cache(async (userId: string) => {
+  return db.subscription.findUnique({ where: { userId } });
+});
+```
+> `cache()` do React deduplica a mesma chamada dentro do mesmo render. Use à vontade.
+---
+## ⚡ 5. SERVER ACTIONS
+```ts
+// features/billing/actions.ts
+"use server";
+import { z } from "zod";
+import { requireUser } from "@/shared/server/auth";
+import { db } from "@/shared/server/db";
+import { updateTag } from "next/cache";
+import { revalidatePath } from "next/cache";
+const SubscribeSchema = z.object({
+  planId: z.string().min(1),
+  coupon: z.string().optional(),
+});
+export async function subscribeAction(_prev: State, formData: FormData) {
+  // 1. AUTENTICAÇÃO — primeira linha, sempre
+  const user = await requireUser();
+  // 2. VALIDAÇÃO — Zod no server é a ÚNICA fonte de verdade
+  const parsed = SubscribeSchema.safeParse(Object.fromEntries(formData));
+  if (!parsed.success) {
+    return { ok: false, errors: parsed.error.flatten().fieldErrors };
+  }
+  // 3. AUTORIZAÇÃO (foco/objeto) — depois da auth, antes do dado
+  if (user.role === "banned") {
+    return { ok: false, error: "Acesso negado" };
+  }
+  // 4. MUTAÇÃO via use case da camada application (nada de regra aqui)
+  await new CreateSubscriptionUseCase(db).execute({ userId: user.id, ...parsed.data });
+  // 5. CACHE — read-your-writes em UI interativa
+  updateTag(`subscription-${user.id}`);
+  revalidatePath("/billing");
+  return { ok: true };
+}
+```
+### Regras de Server Actions
+1. **São endpoints HTTP públicos.** Tudo que é validação/auth que importa TEM que ser dentro da action. Nunca confie no form.
+2. **Ordem fixa:** `auth → validação → autorização → mutação → cache`.
+3. **Input sempre via Zod.** `FormData`, `searchParams`, `params` e JSON do body entram crus.
+4. **Nunca exponha objeto de DB.** Faça `select` explícito do que a UI precisa.
+5. **Erro: retorne estado, não lance.** `throw` só para erro inesperado (vai pro `error.tsx`).
+6. **`revalidateTag(tag)` (1 arg) está DEPRECIADO.** Use `revalidateTag(tag, 'max')` ou `updateTag(tag)` em actions.
+7. **Ação só pode importar de `features/*` e `shared/`.** Nunca de `app/`.
+---
+## ⚡ 6. CACHE COMPONENTS (Padrão Next 16)
+Ative no `next.config.ts`:
+```ts
+const nextConfig = { cacheComponents: true };
+export default nextConfig;
+```
+| Quero...                                   | Use                                     |
+| ------------------------------------------ | --------------------------------------- |
+| Cache de leitura (HTML shell)              | `'use cache'` + `cacheLife('max')`      |
+| Marcar cache para invalidação              | `cacheTag('user-123')`                  |
+| Invalidação com leitura na mesma request   | `updateTag('user-123')` (só em Action)  |
+| SWR (usuário vê velho, revalida em bg)      | `revalidateTag('tag', 'max')`           |
+| Atualizar dado NÃO cacheado (contador, etc) | `refresh()` (só em Action)              |
+| Given time-varying (agora, Math.random)     | `connection()` + `<Suspense>`           |
+**PROIBIDO:** `export const dynamic`, `export const revalidate`, `export const fetchCache`, `unstable_cache`, `fetch(..., { next: { revalidate } })`. Todos substituídos pelo modelo acima.
+```ts
+// ✅ Correto
+export async function getBlogPosts() {
+  "use cache";
+  cacheLife("hours");
+  cacheTag("blog-posts");
+  return db.post.findMany();
+}
+// ❌ Proibido
+export const revalidate = 3600;
+```
+**Regra de ouro:** `use cache` o mais perto possível da leitura. Envolva a página inteira só como último recurso.
+---
+## 🔐 7. SEGURANÇA
+1. **`proxy.ts` NÃO é fronteira de segurança.** É otimização de UX (redirect rápido). Por causa do CVE-2025-29927, o header interno `x-middleware-subrequest` é confiavel por padrão — **nunca** confie nele.
+2. **Autorização vai na camada de dado.** `requireUser()` / `requireRole()` dentro de cada action/query, o mais perto possível do banco.
+3. **Zero validação só no client.** Client-side Zod é UX. O Zod do servidor é segurança.
+4. **Env:** `NEXT_PUBLIC_*` vai pro bundle do browser. Nunca coloque secret lá. Valide env com Zod em `shared/server/env.ts` no boot.
+5. **Imagens remotas:** só `images.remotePatterns` no `next.config.ts`. `images.domains` está deprecado.
+6. **Server-only:** adicione `import "server-only"` no topo de todo módulo com credencial/DB.
+7. **`next/image` com `src` local + query string** exige `images.localPatterns`. Sem isso, quebrou.
+---
+## 🔌 8. ROUTE HANDLERS (`app/api/*/route.ts`)
+Use **só** para: webhook de terceiro, endpoint público de terceiro, ou download de arquivo.
+Para o resto: Server Action.
+```ts
+// app/api/webhooks/stripe/route.ts
+import { z } from "zod";
+import { headers } from "next/headers";
+const StripeEvent = z.object({ id: z.string(), type: z.string() });
+export async function POST(request: Request) {
+  const raw = await request.text();                    // ← assinatura precisa do corpo cru
+  const parsed = StripeEvent.safeParse(JSON.parse(raw));
+  if (!parsed.success) return Response.json({ error: "invalid" }, { status: 400 });
+  await new ProcessStripeEventUseCase(db).execute(parsed.data);
+  return Response.json({ received: true });
+}
+```
+Regras: valide **tudo** (inclusive o body cru), sempre responda com `Response.json`, `await` em `headers()`/`cookies()`, e nunca exponha stack trace.
+---
+## 📝 9. FORMS
+1. **Padrão:** `<form action={serverAction}>` com `useFormStatus` para o loading. Zero JS de estado.
+2. **Precisa de controlled input / validação ao vivo?** → Client Component isolado com `useActionState`.
+3. **Erro de campo** renderize **próximo ao campo**, com `aria-invalid` e `aria-describedby`.
+4. **Desabilite o botão no `pending`.** Sem duplo submit.
+5. **Sucesso:** `toast` (shadcn `sonner`) + `updateTag`/`revalidatePath`. Erro: toast vermelho + mensagem no formulário.
+---
+## 🔍 10. METADATA & SEO
+```ts
+// app/(marketing)/page.tsx
+export const metadata: Metadata = {
+  title: { default: "Marca", template: "%s | Marca" },
+  description: "...",
+};
+export async function generateMetadata({ params }): Promise<Metadata> { /* por rota */ }
+```
+- `metadata` **sempre estático** quando possível. `generateMetadata` só quando o dado é o assunto da rota.
+- `params` e `searchParams` são **Promises** no Next 16: `const { slug } = await params;`
+- Cacheie o que for possível: `async function getMetadata(){ "use cache"; cacheLife('hours'); ... }`
+- `viewport` e `themeColor` vão no `viewport` export, não em `metadata`.
+- Gera `sitemap.ts` e `robots.ts` em `app/`.
+---
+## ⚡ 11. PERFORMANCE
+| Regra | Como |
+| --- | --- |
+| `next/image` sempre, com `sizes` explícito em grid/list | `<Image src fill sizes="(max-width:768px) 100vw, 33vw" />` |
+| `next/font` para tudo (zero layout shift, zero request externo) | `import { Manrope, JetBrains_Mono } from "next/font/google"` |
+| `next/link` para navegação interna | `<Link href>` |
+| `Suspense` no limite, não na página inteira | streamed shell |
+| `use cache` em tudo que é leitura de DB em rota estável | §6 |
+| Bundle client mínimo | `"use client"` na folha (§3) |
+| Analise antes de otimizar | `next build` mostra o custo de cada rota |
+---
+## 🚨 ARMADILHAS DO NEXT 16 (não caia nelas)
+1. `params`/`searchParams` são **async**. `const { id } = params` → undefined silencioso.
+2. `cookies()`, `headers()`, `draftMode()` são **async**.
+3. `middleware.ts` foi **renomeado para `proxy.ts`** (função exportada `proxy`). `middleware.ts` é ignorado em silêncio no build.
+4. `revalidateTag(tag)` de 1 argumento está **depreciado**.
+5. `next lint` **foi removido**. Use Biome/ESLint direto.
+6. Turbopack é o **padrão**. `--webpack` só em Emergency Exit.
+7. Parallel routes exigem `default.js` explícito, senão **o build falha**.
+8. Route segment configs (`dynamic`, `revalidate`, `fetchCache`) **não existem** com `cacheComponents`.
+9. `images.domains` → `images.remotePatterns`.
+10. AMP removido. `next/legacy/image` removido.
+---
+## 📎 REGRAS complementares
+- **Node.js puro (workers, cron, filas, webhooks pesados):** [NODE.md](./NODE.md)
+- **React (quando a lógica é puramente de componente):** [REACT.md](./REACT.md)
+- **Design/UI:** [DESIGN.md](./DESIGN.md)
+- **TypeScript, Tailwind, shadcn, testes:** [stacks/](./stacks/README.md)

package/NODE.md ADDED Viewed

@@ -0,0 +1,107 @@
+# 🟢 NODE.JS (complemento)
+> **Stack padrão é Next.js** ([NEXT.md](./NEXT.md)). Node.js puro entra **só** quando o App Router não dá conta.
+> Vertical Slices, igual. Sem MVC. Foco no domínio.
+## 🤔 Quando usar Node.js puro (e quando NÃO)
+| ✅ USE Node.js | ❌ NÃO USE — use Next.js |
+| --- | --- |
+| Worker de fila (processa job em background) | API/rota/mutação de UI |
+| Cron / scheduler | Server Action |
+| Consumer de webhook pesado / alto volume | Route Handler em `app/api` |
+| CLI de batch / script de importação | Script pontual |
+| Processamento longo que não pode segurar request | Qualquer coisa que responde a request |
+| Processo de streaming de IA de longa duração | AI SDK dentro de Server Action |
+> **Heurística:** "isso roda porque alguém clicou num botão?" → Next.js. "isso roda porque o relógio tocou / a fila encheu?" → Node.js.
+## 📂 ESTRUTURA
+```text
+server/                 (ou worker/, jobs/)
+├── main.ts              # Entry point: boot, graceful shutdown
+├── api/                 # Só se precisar HTTP (Fastify/Hono). Vazamento controlado.
+├── core/                # Config, logger, erros, DI, conexão de DB
+└── features/            # 🌟 MESMA estrutura do Next (vertical slices)
+    └── billing/
+        ├── domain/
+        ├── application/
+        └── infrastructure/
+```
+## 🧠 REGRAS
+1. **Desacoplamento:** o use case NUNCA recebe `req`/`res`. Recebe dados puros, retorna dados puros.
+2. **Isolamento:** uma `feature` não importa a outra. Compartilhe via `core/` ou extraia para um novo slice.
+3. **Contrato na entrada:** worker/cron entra por uma **porta de entrada** com payload validado por Zod. Mesma lei das Server Actions ([NEXT.md](./NEXT.md) §5).
+4. **Ordem fixa:** `auth/escopo → validação → autorização → lógica → I/O`.
+5. **Idempotência:** job de fila pode rodar duas vezes. Use chave de idempotência.
+6. **Retry com backoff exponencial** em falha transitória. **Dead-letter queue** em falha permanente.
+7. **Graceful shutdown:** pegue `SIGTERM`, feche servidor e conexões antes de sair.
+8. **Uma responsabilidade por processo.** Worker e API no mesmo processo = dívida.
+## 💻 EXEMPLO: use case puro
+```typescript
+// features/billing/application/ProcessInvoice.ts
+import type { IInvoiceRepository } from "../domain/IInvoiceRepository";
+import { z } from "zod";
+export const ProcessInvoiceInput = z.object({
+  invoiceId: z.string().min(1),
+  idempotencyKey: z.string().min(8),
+});
+export class ProcessInvoice {
+  constructor(private readonly repo: IInvoiceRepository) {}
+  async execute(raw: unknown) {
+    const input = ProcessInvoiceInput.parse(raw);   // 1. valida na fronteira
+    const invoice = await this.repo.findById(input.invoiceId);
+    if (!invoice) throw new Error("INVOICE_NOT_FOUND");
+    if (await this.repo.wasProcessed(input.idempotencyKey)) {
+      return { status: "skipped" as const };        // 2. idempotência
+    }
+    const total = invoice.lines.reduce((sum, l) => sum + l.amount, 0);
+    await this.repo.markProcessed(input.idempotencyKey, total);
+    return { status: "processed" as const, total };  // 3. efeito
+  }
+}
+```
+## ▶️ Boot de worker
+```typescript
+// main.ts
+import { logger } from "./core/logger";
+import { createBillingUseCases } from "./features/billing/container";
+process.on("SIGTERM", async () => {
+  logger.info("shutdown signal");
+  await closeDb();
+  process.exit(0);
+});
+const billing = createBillingUseCases();
+logger.info("worker online", { version: process.env.npm_package_version });
+```
+## 🧪 Testes
+- Use case = unit test com repositório falso. Zero mock de infra.
+- Integração: teste contra o broker real em container de teste.
+- **Obrigatório:** cenário de "processa 2×" (idempotência) e "falha no meio do job".
+## 🚫 Proibido
+| Padrão | Por quê |
+| --- | --- |
+| Express/Fastify como default | App Router já é a API |
+| `setInterval` para job crítico | Use cron/queue real |
+| `process.exit()` no meio de job | Graceful shutdown |
+| `any` no payload | Zod na fronteira |
+| Segredo em log | Redact obrigatório |
+| lógica de negócio no handler HTTP | Vai pro `application/` |

package/REACT.md ADDED Viewed

@@ -0,0 +1,92 @@
+# ⚛️ REACT (complemento)
+> **O padrão NÃO é React Client.** Next.js 16 usa **Server Components** por padrão.
+> Leia este doc só quando o problema for de **componente/estado de cliente**, não de servidor.
+> Regras de Next.js: [NEXT.md](./NEXT.md) §3 (Server-First).
+## 🧭 Roteador
+| Situação | Faça |
+| --- | --- |
+| Busca de dado no render | **Server Component.** Nem precisa deste doc. |
+| Mutação vinda de formulário | **Server Action** ([NEXT.md](./NEXT.md) §5) |
+| Só o botão tem `onClick` | Folha `"use client"` isolada (§3 do NEXT.md) |
+| Estado local de UI (abrir/fechar) | `useState` neste arquivo |
+| Estado que sobrevive a rota | Cookie/DB, não contexto |
+| Cache remoto com optimistic update | TanStack Query (`@tanstack/react-query`) |
+| Zustand/Redux | **Evite.** Substitua por props, contexto local ou `cache()` do React |
+## 🚨 Regras não-negociáveis
+1. **Server Component é o padrão.** `"use client"` é exceção deliberada — sempre na folha mais baixa (ver [NEXT.md](./NEXT.md) §3).
+2. **Server Component pode ser async; Client Component NÃO pode** (exceto com `use()`, dentro de Suspense).
+3. **Client Component nunca importa módulo `server-only`.** Isso quebra o build — e é o objetivo.
+4. **Props de Server → Client precisam ser serializáveis.** Nada de função, class, Date é preciso (Date vira string).
+5. **`useEffect` não busca dado.** Ele sincroniza efeito colateral. Busca = Server Component / Server Action.
+6. **Estado é do mais local possível:** `useState` > contexto > store global.
+7. **Lista com key estável, nunca índice.**
+8. **Componente cliente pequeno e burro.** Lógica vai pro use case (`features/`).
+## 🪝 Hooks — regras do React 19.2
+```tsx
+// ✅ Coloca hooks antes de qualquer return condicional
+function Panel({ open }: { open: boolean }) {
+  const [tab, setTab] = useState("overview");
+  useEffect(() => { /* sync externo */ }, [open]);
+  if (!open) return null;
+  return <div>{tab}</div>;
+}
+// ✅ Lógica não-reativa isolada em useEffectEvent
+useEffectEvent(() => { onSubmitRef.current(value); });
+// ✅ Atividade em background sem desmontar estado
+<Activity mode="hidden">…</Activity>
+```
+| Hook | Use para | Não use para |
+| --- | --- | --- |
+| `useState` | estado local de UI | estado derivado (calcule na render) |
+| `useReducer` | máquina de estado complexa | 2 estados booleanos |
+| `useEffect` | sincronizar com sistema externo (DOM, socket, subscription) | buscar dado, derivar estado |
+| `useMemo` | cálculo caro | performance "por garantia" |
+| `useCallback` | dep de hook/estabilizar referência | performance "por garantia" |
+| `useContext` | dado de UI compartilhado na subárvore | estado global de domínio |
+| `useOptimistic` | UI otimista em Server Action | cache geral |
+> **React Compiler está ligado** no template (`reactCompiler: true` no `next.config.ts`). `useMemo`/`useCallback` manuais são, na maioria das vezes, ruído.
+## 🧩 Composição
+1. **Compound components** para UI complexa (`<Select>`, `<SelectItem>`). Menos props, mais API.
+2. **Composição > configuração.** 3 componentes pequenos > 1 com 15 props booleanas.
+3. **Server Component compose Client Components** ("children pattern"):
+```tsx
+// ✅ Passa markup, não função
+<Shell sidebar={<ServerRenderedSidebar />}>
+  <InteractiveChart />
+</Shell>
+```
+## 📁 Onde cada coisa mora
+| Tipo | Caminho |
+| --- | --- |
+| UI primitiva genérica | `src/shared/ui/` |
+| UI com regra de negócio | `src/features/<x>/ui/` |
+| Hook transversal | `src/shared/hooks/` |
+| Provider de contexto | junto do hook que consome |
+## 🚫 Anti-padrões
+| ❌ | ✅ |
+| --- | --- |
+| `"use client"` no topo do layout/page | folha isolada |
+| `useEffect` + `fetch` para buscar dado | Server Component / Action |
+| Zustand/Redux para estado de servidor | `cache()` do React / Server |
+| Props drilling de 5 níveis | contexto local ou composição |
+| `key={index}` em lista | id estável |
+| `useMemo` em tudo | deixe o Compiler fazer |
+| Context com objeto que muda a cada render | separe value e actions |