@daniel-da-silva-alves/sddk 2.0.0

package/sddk/skills/code-review/references/anti-ai-design-patterns.md

@@ -0,0 +1,185 @@
+# Anti-Design de IA — 8 Padrões a Detectar e Rejeitar
+
+Estes são padrões que denunciam código gerado por IA sem curadoria humana. O agente DEVE detectar e corrigir todos eles durante o Code Review.
+
+---
+
+## Padrão 1: Emojis em Interface
+
+### O que detectar
+Emojis usados como conteúdo textual em elementos de interface do usuário.
+
+### Onde procurar
+- Textos de botões
+- Labels de formulários
+- Headings e títulos
+- Placeholders de inputs
+- Mensagens de feedback/toast
+- Navegação (menus, breadcrumbs)
+
+### Exemplos
+
+❌ **Ruim**:
+```html
+<button>🚀 Enviar Projeto</button>
+<h1>📊 Dashboard de Vendas</h1>
+<input placeholder="🔍 Pesquisar..." />
+<span>✅ Salvo com sucesso!</span>
+```
+
+✅ **Bom**:
+```html
+<button>Enviar Projeto</button>
+<h1>Dashboard de Vendas</h1>
+<input placeholder="Pesquisar produtos, pedidos ou clientes" />
+<span>Alterações salvas</span>
+```
+
+### Exceção
+Emojis são aceitáveis em: conteúdo gerado por usuários (chat, comentários), campos de dados (não de UI), e quando o design system do projeto explicitamente os inclui.
+
+---
+
+## Padrão 2: CSS/Tailwind Genérico
+
+### O que detectar
+Estilos visuais aplicados sem coerência com um design system. Cores aleatórias, tamanhos inconsistentes, espaçamentos ad-hoc.
+
+### Exemplos
+
+❌ **Ruim**:
+```html
+<div class="bg-blue-500 text-white p-4 rounded-lg shadow-lg">
+  <h2 class="text-2xl font-bold mb-2">Título</h2>
+  <p class="text-gray-200">Descrição aqui</p>
+</div>
+```
+
+✅ **Bom** (com design tokens):
+```html
+<div class="bg-surface-primary text-on-surface p-card rounded-card shadow-card">
+  <h2 class="text-heading-md font-heading mb-spacing-sm">Título</h2>
+  <p class="text-body-md text-on-surface-secondary">Descrição aqui</p>
+</div>
+```
+
+Ou com CSS variables:
+```css
+.card {
+  background: var(--color-surface-primary);
+  padding: var(--spacing-card);
+  border-radius: var(--radius-card);
+  box-shadow: var(--shadow-card);
+}
+```
+
+---
+
+## Padrão 3: Comentários Óbvios
+
+### O que detectar
+Comentários que reescrevem em português/inglês o que o código já diz.
+
+### Exemplos
+
+❌ **Ruim**:
+```typescript
+// Importa o serviço de usuários
+import { UserService } from './user.service';
+
+// Define a variável contador como 0
+let counter = 0;
+
+// Incrementa o contador
+counter++;
+
+// Retorna a resposta
+return response;
+```
+
+✅ **Bom** (sem comentários — o código é autoexplicativo):
+```typescript
+import { UserService } from './user.service';
+let counter = 0;
+counter++;
+return response;
+```
+
+---
+
+## Padrão 4: Nomes Genéricos
+
+### O que detectar
+Variáveis, funções e componentes com nomes que não descrevem seu conteúdo ou propósito.
+
+### Lista de Nomes Proibidos
+
+| Contexto | Nomes Genéricos ❌ |
+|:---|:---|
+| Variáveis | `data`, `result`, `temp`, `item`, `obj`, `val`, `info`, `stuff` |
+| Funções | `handleClick`, `handleChange`, `handleSubmit`, `getData`, `processData`, `doStuff`, `check` |
+| Componentes | `Card`, `Modal`, `List`, `Item`, `Container`, `Wrapper` (sem qualificador) |
+| Tipos | `Props`, `Data`, `Response`, `Payload` (sem qualificador) |
+
+---
+
+## Padrão 5: Componentes Monolíticos
+
+### O que detectar
+Arquivos de componente com mais de ~150 linhas significativas que misturam múltiplas responsabilidades.
+
+### Sinais
+- Múltiplos `useState`/`useEffect` não relacionados no mesmo componente
+- Renderização condicional extensa (múltiplos `if/else` ou ternários aninhados)
+- Lógica de negócio misturada com UI
+- Formulário, tabela e gráfico no mesmo componente
+
+---
+
+## Padrão 6: Código Boilerplate Repetitivo
+
+### O que detectar
+Padrões de código idênticos ou quase idênticos repetidos em múltiplos arquivos sem abstração.
+
+### Sinais
+- Fetch/API calls repetidos sem cliente centralizado
+- Validações duplicadas entre formulários
+- Tratamento de loading/error state repetido
+- Formatações de data/moeda duplicadas
+
+---
+
+## Padrão 7: UI "Tutorial de YouTube"
+
+### O que detectar
+Interfaces que parecem screenshots de tutoriais genéricos — funcionais mas sem identidade visual.
+
+### Sinais
+- Cards com `box-shadow` padrão do framework sem personalização
+- Gradientes genéricos (`linear-gradient(to right, blue, purple)`)
+- Cores padrão do Tailwind sem customização (`blue-500`, `gray-700`)
+- Layout grid básico sem hierarquia visual
+- Tipografia padrão do browser (sem fonte customizada)
+- Ícones genéricos de bibliotecas sem curadoria
+
+---
+
+## Padrão 8: Textos Placeholder Genéricos
+
+### O que detectar
+Textos que demonstram falta de cuidado com o conteúdo real da interface.
+
+### Lista de Textos Proibidos
+
+| Contexto | Textos Genéricos ❌ |
+|:---|:---|
+| Conteúdo | "Lorem ipsum dolor sit amet" |
+| Botões | "Click here", "Submit", "Send", "OK", "Go" |
+| Links | "Read more", "Learn more", "Click here" |
+| Placeholders | "Enter text here", "Type something...", "Search..." |
+| Labels | "Label", "Field", "Input" |
+| Headings | "Title", "Heading", "Section" |
+| Error msgs | "An error occurred", "Something went wrong" |
+
+### O que usar no lugar
+Textos reais e descritivos baseados no domínio da aplicação, extraídos dos requisitos funcionais do SRS.

package/sddk/skills/code-review/references/refactoring-severity-guide.md

@@ -0,0 +1,96 @@
+# Guia de Classificação de Severidade de Refatorações
+
+Use este guia para classificar cada issue encontrada durante o Code Review. A classificação determina a **ação imediata** a ser tomada.
+
+---
+
+## Severidades
+
+### 🔴 Crítica — Execução Imediata
+
+Issues que **devem ser corrigidas na mesma sessão** antes de considerar a feature concluída.
+
+#### Critérios para Classificar como Crítica:
+
+| Categoria | Exemplos |
+|:---|:---|
+| **Segurança** | SQL injection, XSS, IDOR, secrets expostos, senhas em plaintext |
+| **Bug funcional** | Feature não funciona conforme SRS, crash em fluxo principal |
+| **Violação grave do SDD** | Arquitetura implementada diferente do design (ex: lógica de negócio no controller) |
+| **Perda de dados** | Operações destrutivas sem confirmação, falta de validação em deletes |
+
+#### Ação:
+1. Corrigir o código diretamente
+2. Documentar o que foi corrigido no relatório de review
+3. Se houver mais de 5 correções críticas, criar microtasks e voltar para Skill 4
+
+---
+
+### 🟡 Média — Documentar no Backlog
+
+Issues que **afetam qualidade mas não impedem o funcionamento**. Devem ser resolvidas antes do próximo release ou sprint.
+
+#### Critérios para Classificar como Média:
+
+| Categoria | Exemplos |
+|:---|:---|
+| **Code smell** | Duplicação de código, funções muito longas, complexidade ciclomática alta |
+| **Naming** | Nomes inconsistentes entre arquivos, convenções misturadas |
+| **Anti-IA detectado** | Emojis em UI, CSS genérico, comentários óbvios |
+| **Componentização** | Componente com múltiplas responsabilidades (mas funcional) |
+| **Configuração** | CORS aberto, falta de rate limiting, validação apenas no frontend |
+
+#### Ação:
+1. Documentar em `.specs/features/{feature}/refactoring-backlog.md`
+2. Incluir: arquivo, linha, descrição, sugestão de correção
+3. Priorizar dentro do backlog
+
+---
+
+### 🟢 Baixa — Documentar no Backlog (Baixa Prioridade)
+
+Issues que são **melhorias opcionais** de estética, performance ou organização. Não urgentes.
+
+#### Critérios para Classificar como Baixa:
+
+| Categoria | Exemplos |
+|:---|:---|
+| **Otimização** | Queries que poderiam ser mais eficientes (mas funcionam) |
+| **Estilo** | Formatação inconsistente (que um linter resolveria) |
+| **Documentação** | Falta de JSDoc em funções públicas |
+| **Organização** | Arquivo poderia estar em outro diretório (mas funciona onde está) |
+| **DX** | Mensagens de log pouco informativas |
+
+#### Ação:
+1. Documentar em `.specs/features/{feature}/refactoring-backlog.md`
+2. Marcar como baixa prioridade
+3. Resolver quando houver tempo disponível
+
+---
+
+## Árvore de Decisão
+
+```
+O código funciona incorretamente ou tem falha de segurança?
+├── SIM → 🔴 Crítica → CORRIGIR AGORA
+└── NÃO
+    └── O código viola boas práticas, convenções ou o SDD?
+        ├── SIM → 🟡 Média → BACKLOG (prioridade)
+        └── NÃO
+            └── O código pode ser melhorado mas está OK?
+                ├── SIM → 🟢 Baixa → BACKLOG (quando possível)
+                └── NÃO → ✅ Sem issue
+```
+
+## Formato do Backlog Entry
+
+```markdown
+### RB-{número}: {Título descritivo}
+- **Severidade**: 🟡 Média / 🟢 Baixa
+- **Arquivo**: `{caminho/do/arquivo.ext}`
+- **Linha(s)**: {L42-L58}
+- **Categoria**: {Code Smell | Naming | Anti-IA | Segurança | Performance | Organização}
+- **Descrição**: {O que está errado}
+- **Sugestão**: {Como corrigir}
+- **Esforço estimado**: {Baixo | Médio | Alto}
+```

package/sddk/skills/code-review/references/security-checklist.md

@@ -0,0 +1,131 @@
+# Checklist de Segurança para Code Review
+
+Checklist simplificado baseado no OWASP Top 10, adaptado para revisão de código de features individuais.
+
+---
+
+## 1. Injeção (SQL, XSS, Command)
+
+- [ ] **SQL Injection**: Queries usam parametrização/prepared statements (nunca concatenação de strings)
+- [ ] **XSS**: Inputs de usuário são sanitizados antes de renderizar no DOM
+- [ ] **Command Injection**: Inputs de usuário NUNCA são passados diretamente para execução de comandos do sistema
+- [ ] **Template Injection**: Templates (Handlebars, EJS, Jinja) escapam variáveis por padrão
+
+### O que verificar
+```typescript
+// ❌ SQL Injection
+db.query(`SELECT * FROM users WHERE id = '${userId}'`);
+
+// ✅ Parameterizado
+db.query('SELECT * FROM users WHERE id = $1', [userId]);
+```
+
+```typescript
+// ❌ XSS
+element.innerHTML = userInput;
+
+// ✅ Sanitizado
+element.textContent = userInput;
+```
+
+---
+
+## 2. Autenticação
+
+- [ ] Senhas são hasheadas com algoritmo forte (bcrypt, argon2, scrypt) — nunca MD5/SHA1
+- [ ] Tokens JWT têm expiração definida
+- [ ] Refresh tokens são armazenados de forma segura (httpOnly cookies, não localStorage)
+- [ ] Tentativas de login são limitadas (rate limiting / account lockout)
+- [ ] Logout invalida sessão/token no servidor
+
+---
+
+## 3. Autorização
+
+- [ ] Cada endpoint verifica permissões do usuário autenticado
+- [ ] Não há IDOR (Insecure Direct Object Reference) — usuário A não acessa dados do usuário B
+- [ ] Roles/permissions são validadas no backend (nunca apenas no frontend)
+- [ ] Endpoints admin são protegidos adequadamente
+
+### O que verificar
+```typescript
+// ❌ IDOR — qualquer usuário autenticado acessa qualquer pedido
+app.get('/api/orders/:id', async (req, res) => {
+  const order = await orderRepo.findById(req.params.id);
+  return res.json(order);
+});
+
+// ✅ Verificação de propriedade
+app.get('/api/orders/:id', async (req, res) => {
+  const order = await orderRepo.findById(req.params.id);
+  if (order.userId !== req.user.id) return res.status(403).json({ error: 'Forbidden' });
+  return res.json(order);
+});
+```
+
+---
+
+## 4. Exposição de Dados Sensíveis
+
+- [ ] Senhas nunca aparecem em responses de API
+- [ ] Dados sensíveis (CPF, cartão, tokens) não são logados
+- [ ] .env e secrets não estão comitados no git (.gitignore configurado)
+- [ ] Errors de produção não expõem stack traces ou detalhes internos ao cliente
+
+### O que verificar
+```typescript
+// ❌ Expõe senha
+return res.json(user);
+
+// ✅ Omite campos sensíveis
+const { password, ...safeUser } = user;
+return res.json(safeUser);
+```
+
+---
+
+## 5. Configuração de Segurança
+
+- [ ] CORS está configurado para permitir apenas origens necessárias (não `*` em produção)
+- [ ] Headers de segurança configurados (CSP, X-Frame-Options, X-Content-Type-Options)
+- [ ] HTTPS enforced em produção
+- [ ] Secrets/tokens não estão hardcoded no código fonte
+
+### O que verificar
+```typescript
+// ❌ CORS aberto
+app.use(cors({ origin: '*' }));
+
+// ✅ CORS restrito
+app.use(cors({ origin: process.env.ALLOWED_ORIGINS?.split(',') }));
+```
+
+---
+
+## 6. Validação de Input
+
+- [ ] Todos os inputs de formulário são validados no backend (não apenas no frontend)
+- [ ] Uploads de arquivo validam tipo, tamanho e conteúdo
+- [ ] Paginação tem limites máximos (não permite `limit=999999`)
+- [ ] Campos numéricos validam range (não aceita negativos quando não deveria)
+
+---
+
+## Classificação de Issues de Segurança
+
+| Issue | Severidade |
+|:---|:---|
+| SQL/XSS/Command Injection | 🔴 Crítica |
+| IDOR (acesso a dados de outros usuários) | 🔴 Crítica |
+| Senha em plaintext / hash fraco | 🔴 Crítica |
+| Secrets hardcoded no código | 🔴 Crítica |
+| Token sem expiração | 🔴 Crítica |
+| CORS `*` em produção | 🟡 Média |
+| Falta de rate limiting | 🟡 Média |
+| Falta de headers de segurança | 🟡 Média |
+| Stack trace em response de erro | 🟡 Média |
+| Validação apenas no frontend | 🟡 Média |
+| Falta de paginação com limite | 🟢 Baixa |
+
+> [!IMPORTANT]
+> **Toda issue de segurança classificada como Crítica DEVE ser corrigida imediatamente.** Nunca mover para backlog.

package/sddk/skills/fullstack-development/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: fullstack-development
+description: "Desenvolvimento fullstack orientado pelo SDD com auto-review inline e clean code. ATIVE esta skill quando o usuário mencionar: desenvolver, implementar, codar, programar, criar o código, iniciar desenvolvimento, executar microtasks, começar a codar, build da feature. Também acione quando o agente completar a skill de Planejamento e o usuário confirmar a transição para o Desenvolvimento."
+---
+
+# Skill de Desenvolvimento Fullstack
+
+## Identidade
+
+Você é um **Desenvolvedor Fullstack Sênior** que escreve código limpo, seguindo estritamente o System Design Document e as boas práticas da stack utilizada.
+
+## Contexto do Pipeline
+
+Esta é a **Skill 4 de 5** do pipeline Spec-Driven Development (SDD):
+
+```
+1. SRS ✅ → 2. SDD ✅ → 3. Planejamento ✅ → ► [4. Dev] → 5. CodeReview
+```
+
+> [!IMPORTANT]
+> O SRS, SDD e Planejamento DEVEM ter sido concluídos antes desta skill. Verifique que existem:
+> - `.specs/features/{feature-name}/srs.md`
+> - `.specs/features/{feature-name}/sdd.md`
+> - `.specs/features/{feature-name}/manual-tests.md`
+> - Task artifact com microtasks
+
+## Regras Obrigatórias
+
+### Clean Code
+1. **NUNCA escrever comentários óbvios** — o código deve ser autoexplicativo
+2. **SEMPRE usar nomes descritivos** — nunca `data`, `temp`, `handleClick`, `x`, `result`
+3. **NUNCA usar código boilerplate repetitivo** — abstrair em funções/componentes reutilizáveis
+4. **SEMPRE seguir naming conventions da stack** — camelCase, PascalCase, snake_case conforme convenção
+5. **NUNCA criar componentes monolíticos** — dividir em componentes granulares com responsabilidade única
+
+### Aderência ao SDD
+6. **SEMPRE seguir a arquitetura definida no SDD** — respeitar camadas, estrutura de pastas, padrões
+7. **SEMPRE seguir o modelo de dados do SDD** — campos, tipos, constraints exatamente como definido
+8. **SEMPRE seguir o design de API do SDD** — endpoints, request/response bodies, status codes
+9. **NUNCA inventar funcionalidade não especificada** — se não está no SRS/SDD, não implemente
+
+### Anti-Design de IA
+10. **NUNCA usar emojis** em textos de interface (botões, labels, headings, placeholders)
+11. **NUNCA usar CSS/Tailwind genérico** — seguir design tokens definidos no SDD
+12. **NUNCA usar textos placeholder genéricos** — 'Lorem ipsum', 'Click here', 'Submit' são proibidos
+13. **NUNCA criar UI com aparência "tutorial de YouTube"** — cards com sombras genéricas, gradientes sem propósito
+
+## Fluxo de Execução
+
+### Fase 1: Preparação
+
+1. **Ler o Task artifact** com as microtasks do Planejamento
+2. **Carregar os standards do projeto** — ler `.specs/standards/naming-conventions.md` e `.specs/standards/coding-standards.md` para ter as convenções na memória ativa
+3. **Se tem frontend na microtask** — ler também `.specs/standards/design-system.md`
+4. **Se tem API na microtask** — ler também `.specs/standards/api-conventions.md`
+5. Identificar a primeira microtask pendente (marcada `[ ]`)
+
+### Fase 2: Execução por Microtask
+
+Para CADA microtask, seguir este ciclo:
+
+#### 2a. Iniciar Microtask
+1. Marcar a microtask como `[/]` (em progresso) no Task artifact
+2. **Ler as referências (ponteiros)** da microtask:
+   - Abrir e ler a seção específica do SDD referenciada
+   - Abrir e ler a seção específica do SRS referenciada
+   - Abrir e ler o standard referenciado (se houver ponteiro `📎 Ref Standards`)
+3. Anunciar: "Iniciando microtask {Fase.Número}: {título}"
+
+#### 2b. Implementar
+1. Criar/modificar os arquivos listados na microtask
+2. Seguir estritamente o SDD, os **standards do projeto** e as regras de Clean Code
+3. Garantir que o código é funcional e completo para esta microtask
+
+#### 2c. Auto-Review Inline
+Após implementar, verificar usando o checklist em `references/self-review-checklist.md`:
+
+1. **Aderência ao SDD** — o código reflete exatamente o que o SDD especifica?
+2. **Clean code** — nomes descritivos? Sem comentários óbvios? Sem repetição?
+3. **Naming conventions** — consistente com a stack?
+4. **Anti-IA patterns** — sem emojis, sem CSS genérico, sem placeholders?
+
+Se encontrar problemas, corrija ANTES de marcar como concluída.
+
+#### 2d. Concluir Microtask
+1. Marcar a microtask como `[x]` (concluída) no Task artifact
+2. Prosseguir para a próxima microtask pendente
+
+### Fase 3: Transição
+
+Após todas as microtasks estarem `[x]`:
+
+1. Anunciar: "✅ Desenvolvimento concluído. Todas as {N} microtasks foram implementadas. Próxima etapa: **Code Review**. Deseja prosseguir?"
+2. **AGUARDAR** confirmação explícita antes de ativar a próxima skill
+
+## Estratégia de Memória (Leitura Sob Demanda)
+
+> [!IMPORTANT]
+> **NUNCA tente ler o SRS e SDD inteiros de uma vez.** Isso polui o contexto e desperdiça tokens.
+
+A estratégia correta é:
+1. Cada microtask tem **ponteiros** para seções específicas (ex: `SDD#3.1 L45-L78`)
+2. Ao iniciar uma microtask, leia **APENAS** as seções referenciadas
+3. Isso garante que o contexto carregado é preciso e relevante para a tarefa atual
+
+## Consulta de Documentação Técnica
+
+Quando precisar consultar documentação de uma tecnologia da stack (ex: "como usar server actions no Next.js 15?"), siga a hierarquia configurada na **seção 10 do SDD**:
+
+### Passo a passo:
+
+1. **Ler a seção 10 do SDD** — abrir `.specs/features/{feature}/sdd.md` e localizar a tabela de fontes
+2. **Seguir a hierarquia de prioridade**:
+   - **Docs local?** → `view_file` no caminho listado na seção 10.2
+   - **MCP/Skill?** → Usar a ferramenta/skill configurada na tabela 10.1
+   - **URL oficial?** → `read_url_content("{url-da-tabela}/topico-especifico")`
+   - **Nenhum?** → `search_web("{tecnologia} {versão} {tópico} site:{domínio-oficial}")`
+3. **Validar a versão** — confirmar que a documentação consultada corresponde à versão listada na tabela 10.1
+
+> [!WARNING]
+> **NUNCA use seu conhecimento de treino como fonte primária** para APIs e padrões de tecnologias. Sempre consulte a documentação configurada no SDD. Seu conhecimento de treino pode estar desatualizado para a versão específica da stack.
+
+## Routing Table
+
+### References
+
+- Se precisar do checklist de auto-review para aplicar após cada microtask, leia `references/self-review-checklist.md`
+- Se precisar das regras de clean code detalhadas e exemplos, leia `references/clean-code-rules.md`

package/sddk/skills/fullstack-development/references/clean-code-rules.md

@@ -0,0 +1,146 @@
+# Regras de Clean Code
+
+Regras stack-agnostic que o agente deve seguir durante o desenvolvimento. Estas regras são aplicadas automaticamente — não precisam ser mencionadas ao usuário.
+
+---
+
+## 1. Nomenclatura
+
+### Variáveis e Funções
+| ❌ Ruim | ✅ Bom | Razão |
+|:---|:---|:---|
+| `data` | `userProfile` | Descreve o conteúdo |
+| `temp` | `formattedDate` | Descreve o propósito |
+| `handleClick` | `handleLoginSubmit` | Descreve a ação específica |
+| `result` | `validationErrors` | Descreve o que contém |
+| `x`, `y`, `i` (fora de loop) | `index`, `coordinate` | Autodocumentável |
+| `flag` | `isAuthenticated` | Semântico |
+| `arr` | `activeUsers` | Descreve o conteúdo da coleção |
+
+### Funções
+| ❌ Ruim | ✅ Bom | Razão |
+|:---|:---|:---|
+| `process()` | `validateAndSaveUser()` | Descreve o que faz |
+| `doStuff()` | `calculateShippingCost()` | Específico |
+| `getData()` | `fetchUserOrders()` | Especifica o que busca |
+| `check()` | `isEmailAlreadyRegistered()` | Booleans com prefixo `is/has/can` |
+
+### Componentes (React/Vue/Svelte)
+| ❌ Ruim | ✅ Bom | Razão |
+|:---|:---|:---|
+| `Card` (genérico) | `ProductCard` | Específico ao domínio |
+| `Modal` (genérico) | `ConfirmDeleteModal` | Descreve o propósito |
+| `List` (genérico) | `OrderHistoryList` | Específico |
+| `Button` (global catch-all) | `SubmitButton`, `NavigationButton` | Variantes explícitas |
+
+---
+
+## 2. Comentários
+
+### Comentários Proibidos (❌)
+```typescript
+// Incrementa o contador
+counter++;
+
+// Retorna o usuário
+return user;
+
+// Define o estado como true
+setIsLoading(true);
+
+// Cria uma nova instância
+const service = new UserService();
+```
+
+### Comentários Aceitáveis (✅)
+```typescript
+// Regex RFC 5322 simplificada para validação de email corporativo
+const EMAIL_PATTERN = /^[a-zA-Z0-9._%+-]+@empresa\.com$/;
+
+// Delay de 300ms para debounce de busca — evita flood de requests
+// durante digitação rápida no campo de pesquisa
+const SEARCH_DEBOUNCE_MS = 300;
+
+// TODO(#123): Migrar para a v2 da API quando disponível em produção
+const API_BASE = '/api/v1';
+```
+
+### Regra Geral
+> Comente o **porquê**, nunca o **o quê**. Se o código precisa de comentário para explicar o que faz, renomeie variáveis e funções até ficar óbvio.
+
+---
+
+## 3. Abstração e Reutilização
+
+### Código Repetitivo (❌)
+```typescript
+// Repetido em 5 componentes
+const response = await fetch('/api/users', {
+  headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }
+});
+if (!response.ok) throw new Error('Failed to fetch');
+const data = await response.json();
+```
+
+### Com Abstração (✅)
+```typescript
+// Usado em 5+ componentes — fetch centralizado
+const users = await apiClient.get<User[]>('/users');
+```
+
+### Regra: Extrair quando repetir ≥ 2 vezes
+Se um padrão de código aparece 2 ou mais vezes, deve ser extraído para:
+- Uma função utilitária
+- Um componente reutilizável
+- Um hook customizado (React)
+- Um serviço/module
+
+---
+
+## 4. Estrutura de Arquivos
+
+### Arquivo Monolítico (❌)
+```
+src/components/Dashboard.tsx  ← 500+ linhas com tudo junto
+```
+
+### Arquivos Granulares (✅)
+```
+src/components/dashboard/
+├── Dashboard.tsx              ← Composição dos sub-componentes
+├── DashboardHeader.tsx        ← Header isolado
+├── DashboardMetrics.tsx       ← Cards de métricas
+├── DashboardRecentOrders.tsx  ← Lista de pedidos recentes
+└── useDashboardData.ts        ← Hook de dados
+```
+
+### Regra: 1 componente por arquivo, máximo ~150 linhas significativas
+
+---
+
+## 5. Tratamento de Erros
+
+### Genérico (❌)
+```typescript
+try {
+  await saveUser(data);
+} catch (e) {
+  console.log(e);  // Ignora silenciosamente
+}
+```
+
+### Específico (✅)
+```typescript
+try {
+  await saveUser(data);
+} catch (error) {
+  if (error instanceof ValidationError) {
+    showFieldErrors(error.fields);
+  } else if (error instanceof NetworkError) {
+    showRetryNotification('Falha na conexão. Tente novamente.');
+  } else {
+    logger.error('Unexpected error saving user', { error, userId: data.id });
+    showGenericError();
+  }
+}
+```