Padrões de Eficiência

Problema: Entregar funcionalidades quase idênticas uma a uma queima horas e deixa o código inconsistente entre rondas.

Ganho rápido: Cola este bloco no teu CLAUDE.md. A consistência melhora assim que o Claude o lê:

# Component Generation Framework
 
When creating new [cards/forms/modals], follow the pattern in /components/examples/:
 
1. Copy the closest existing example
2. Replace data fields (keep structure identical)
3. Update types to match new data model
4. Run existing tests as template for new tests

Uma regra curta como esta impede o Claude de reinventar padrões que já existem no teu repositório.

O que são Frameworks de Permutação

Um framework de permutação é um truque. Constróis 8 a 12 funcionalidades irmãs à mão, depois escreves uma template CLAUDE.md que deixa o Claude criar a variação 11, 12 e 13 a partir do mesmo molde. O padrão é capturado uma vez. O Claude trata do resto.

O teu papel muda. Deixas de codificar cada funcionalidade e começas a rever as variações que o Claude extraiu de um blueprint já validado.

As Três Fases

Fase 1: Construção Manual da Base

Começa por codificar 8 a 12 funcionalidades irmãs tu mesmo. À medida que avances, anota cada decisão, padrão e restrição. Esse registo torna-se a biblioteca de referência que o Claude aprende depois.

# Track your patterns
mkdir patterns/user-interfaces
# Build: LoginForm, SignupForm, ProfileForm, etc.
# Document decisions in each component

Um dashboard SaaS com umas tabelas de dados torna isto concreto. UsersTable, OrdersTable, InvoicesTable, ProductsTable. Constróis as três primeiras à mão. Ronda após ronda, as mesmas decisões voltam a aparecer: forma das colunas, assinatura do handler de ordenação, componente de paginação, layout do estado vazio, esqueleto de carregamento.

Na terceira ronda já consegues nomear o que muda entre instâncias (definições de colunas, tipos de dados, endpoint da API) e o que fica fixo (wrapper da tabela, lógica de paginação, estado de ordenação, seleção de linhas). Esse inventário alimenta a Fase 2.

Antes (construindo cada tabela do zero):

// Each table re-implements pagination, sorting, selection...
// UsersTable: 180 lines
// OrdersTable: 195 lines (slightly different pagination)
// InvoicesTable: 210 lines (different sort logic)

Depois (padrão extraído):

// Shared DataTable component: 120 lines
// UsersTable config: 35 lines (just column definitions + endpoint)
// OrdersTable config: 40 lines
// InvoicesTable config: 38 lines

Fase 2: Reconhecimento de Padrões e Templating

Revê as builds manuais e extrai:

• Estruturas de código repetidas que aparecem em todas as implementações
• Elementos variáveis que mudam de uma instância para a outra
• Salvaguardas de qualidade (segurança de tipos, acessibilidade, cobertura de testes)
• Verificações que confirmam que cada nova variação realmente funciona

Agora escreve uma secção CLAUDE.md que codifica esses padrões com exemplos concretos do que passa e do que não passa. O segredo é a concretização. Evita "segue os padrões existentes." Aponta diretamente para ficheiros: "usa a interface de props exata de UsersTable.tsx linhas 12-28, substituindo o tipo de entidade."

Instrução de framework fraca:

Create new table components following existing patterns.

Instrução de framework forte:

# Data Table Framework
 
Reference: /components/tables/UsersTable.tsx (canonical)
 
To create a new [Entity]Table:
 
1. Props: { columns: ColumnDef<Entity>[], endpoint: string, defaultSort: SortConfig }
2. Use DataTable wrapper from /components/shared/DataTable.tsx
3. Column definitions follow the format in UsersTable lines 12-28
4. Include loading skeleton matching the column count
5. Empty state uses /components/shared/EmptyState.tsx with entity-specific message
6. Tests: copy UsersTable.test.tsx, replace User fixtures with [Entity] fixtures

A especificidade faz toda a diferença. A versão forte nomeia ficheiros exatos, números de linha e componentes partilhados. O Claude não tem nada para adivinhar. Segue um caminho verificado em vez de inventar.

Fase 3: Geração Automatizada

Agora usa o framework. Começa pelos casos mais fáceis e deixa a dificuldade aumentar à medida que o Claude prova que se mantém dentro das tuas restrições.

A primeira variação gerada quase nunca volta perfeita. Compara-a linha a linha com os teus exemplos manuais e vais encontrar um ou dois pontos onde o framework não foi específico o suficiente. Afina esses pontos, gera novamente e repete. Após três ou quatro iterações, o framework produz código que passa a revisão sem edições manuais.

Estratégias de Refinamento do Framework

Controlo de Qualidade Baseado em Restrições

Regras de framework rígidas reduzem o espaço criativo do Claude sem eliminar a variação útil. Define as restrições claramente no CLAUDE.md:

CONSTRAINTS:
 
- All components must include PropTypes / TypeScript interfaces
- Use established naming conventions (camelCase for props)
- Include accessibility attributes (aria-label, role, tabIndex)
- Follow existing file structure in /components/
- Every new component gets a co-located test file

Testes de Variância

Testa o framework sob pressão gerando 5 a 10 variações e alinhando-as lado a lado. Se divergirem demasiado, volta a adicionar exemplos mais precisos e restrições mais rígidas à template CLAUDE.md.

Uma execução concreta com um framework de endpoints de API mostrou o problema. Nas primeiras 3 endpoints gerados, o tratamento de erros manteve-se estável mas as formas de resposta divergiram. Uma voltou como { data: ... }. Outra envolveu o payload como { result: ... }. A terceira devolveu o objeto puro sem nenhum wrapper. Uma nova linha no framework resolveu tudo: "All endpoints return { data: T, error: null } or { data: null, error: ErrorShape }." A variância desapareceu nas próximas 8 gerações.

Melhoria Iterativa

Cada iteração do framework afina duas coisas ao mesmo tempo: o quão fielmente o Claude segue o teu padrão, e o quão claramente entendes o que torna o código gerado por IA fiável.

Framework de Permutação em Ação

Uma execução concreta. Imagina que construíste UserCard, ProductCard e OrderCard à mão. Colocas isto no CLAUDE.md:

# Card Component Framework
 
Reference: /components/cards/UserCard.tsx (canonical example)
 
To create a new [Entity]Card:
 
1. Props: { data: [Entity], onClick?: () => void, variant?: 'compact' | 'full' }
2. Structure: Avatar/Icon + Title + Subtitle + Action buttons
3. Styling: Use existing Tailwind classes from UserCard
4. Tests: Copy UserCard.test.tsx, replace User with [Entity]

Pedes ao Claude para "criar um SubscriptionCard" e o resultado encaixa na mesma forma. Mesma estrutura de props, mesma abordagem de estilos, mesma cobertura de testes. Não o distinguirias de um dos cards construídos à mão, porque veio do mesmo blueprint.

Padrões de Eficiência Comuns

Endpoints de API: Frameworks para rotas com tratamento de erros, validação e formas de resposta correspondentes. Define o teu padrão de schema Zod, o teu formato de resposta de erro e a tua cadeia de middleware uma vez cada. Um novo endpoint colapsa de uma hora para 15 minutos.

Componentes de UI: Frameworks para componentes de design system que tratam diferentes tipos de dados. O exemplo do card aplica-se diretamente a modais, formulários, itens de lista e vistas de detalhe. Se um componente já existe em 3+ variantes, qualifica-se como material de framework.

Operações de Base de Dados: Frameworks para CRUD com tratamento de transações partilhado entre modelos. Define o query builder, a abordagem de paginação e o comportamento de soft-delete uma vez. Novos modelos encaixam nos mesmos trilhos.

Quando NÃO Construir um Framework

Frameworks não são gratuitos. Construir um desnecessariamente custa-te, da mesma forma que code desnecessário custa.

Um ou dois exemplos é pouco demais. Três versões construídas à mão é o mínimo. Com dois, o framework fixa-se nesses casos exatos e não generaliza.

Salta frameworks para funcionalidades únicas. Um dashboard de admin personalizado sem equivalentes só adiciona overhead e não retorna nada. Guarda o orçamento de frameworks para padrões que se repetem.

Espera até os padrões estabilizarem. No primeiro mês de um projeto, as formas dos componentes mudam semana a semana. Uma template rígida bloqueada na semana um significa retrabalho na semana dois. Consolida a forma através de 8 a 10 builds manuais primeiro.

Evita over-constraining. Se as regras forem tão rígidas que o Claude não consegue lidar com variação real, o framework custa mais do que dá. Boas restrições bloqueiam a estrutura e deixam espaço para detalhes específicos da entidade.

Métricas de Sucesso para Frameworks

Observa estes indicadores para confirmar que o framework está a compensar:

• Pontuação de Consistência: As variações geradas alinham com os teus exemplos manuais em imports, formas de props e layout de ficheiros? Um framework saudável tem pontuação alta em correspondência estrutural.
• Velocidade de Implementação: Um framework afinado reduz visivelmente o caminho entre pedido e funcionalidade a funcionar. Sem aceleração real significa que são precisos mais detalhes, ou os padrões ainda não estão bloqueados.
• Tempo de Revisão: Quanto tempo demora uma passagem de validação? Esse número deve diminuir à medida que o framework amadurece. Output inicial quer revisão cuidadosa. Output maduro só precisa de uma leitura rápida de correção.
• Frequência de Bugs: Compara bugs por variação gerada com bugs por funcionalidade construída à mão. Um bom framework baixa a contagem porque incorpora padrões que já testaste em campo.

De Escala Linear para Exponencial

O desenvolvimento clássico escala linearmente. Um programador produz uma funcionalidade de cada vez. Frameworks de permutação reescrevem essa matemática. Um único framework produz muitas variações, e a tua velocidade sobe.

O retorno é maior em codebases onde padrões repetidos servem utilizadores diferentes mas partilham o mesmo molde técnico. Os retornos acumulam-se a partir daí. Uma vez que tens frameworks para componentes, endpoints de API e operações de base de dados, uma nova funcionalidade que abrange as três camadas é entregue numa fração do tempo antigo, porque cada camada já tem o seu blueprint à espera.

Próximas Ações:

1. Hoje: Analisa o teu repositório à procura de 3 componentes irmãos próximos. Cards, formulários e modais são os melhores pontos de partida.
2. Esta semana: Transforma esses irmãos no teu primeiro framework escrevendo exatamente o que se mantém constante entre eles.
3. Aprofunda: Estuda as técnicas CLAUDE.md que tornam a documentação de frameworks eficaz.
4. Relacionado: Recorre aos modos de planeamento quando um pedido de framework se torna complexo.
5. Otimiza: Usa estratégias de seleção de modelos para ajustar custo versus qualidade.
6. Automatiza: Configura loops de feedback para que as melhorias se acumulem ao longo do tempo.
7. Experimenta: Executa testes de variância sistemáticos para confirmar que o output do framework se mantém.