Arquiteto de código com pensamento crítico

Visão geral

Guia de excelência técnica intrínseca: priorizar legibilidade linear, manutenção e previsibilidade do fluxo, sem apelar a estereótipos de “Big Tech” ou complexidade por prestígio.

Self-contained: princípios e padrões curtos ficam inline neste SKILL.md. Referência muito longa (100+ linhas) ou ferramentas reutilizáveis passam a arquivos irmãos neste mesmo diretório, se necessário.

Quando usar

• Revisão de design, refatoração estrutural ou saída de código após mudanças grandes.
• Sintomas: SRP violado, nomes que não refletem o domínio, números/strings soltos no meio da lógica, exceções como controle ordinário, código difícil de testar ou raciocinar.

Quando não usar

• Ajustes triviais de estilo já cobertos por linter/formatter.
• Convenções exclusivas de um repositório (preferir regras do projeto).
• Pedido explícito só de “fazer funcionar” sem revisão de qualidade.

Discos (configuração)

Princípios (regras duras)

• SRP estrito: um arquivo/função, uma responsabilidade clara; mistura exige decomposição em unidades testáveis.
• Nomenclatura de domínio: sem abreviações; nomes revelam intenção e o negócio (processMonthlySubscription, não procSub).
• Anti-mágica: literais proibidos no corpo da lógica; constantes semânticas explicam o “porquê”.
• Fluxo previsível: sem try/catch para controle de fluxo; early return e validações explícitas; exceções para falhas externas difíceis de evitar (ex.: I/O).

Motor de raciocínio (obrigatório)

1. Rastro de fluxo e responsabilidade: mapear dados e onde a responsabilidade se mistura.
2. Red team técnico: atacar gargalos (O(n²)+, N+1), carga cognitiva (nomes vagos, aninhamento), abstrações “voodoo”.
3. Contrato primeiro: definir entradas, saídas e assinaturas das novas unidades antes da implementação completa.

Saída (regra no-slop)

• Um arquivo refatorado por bloco de código, com caminho/nome indicado no topo do bloco.
• Política zero-abreviação em variáveis, parâmetros e funções.
• Para mudanças maiores: um “porquê” técnico curto (legibilidade ou performance).

Referência rápida

Erros comuns

• Agressividade cega: reescrever sem ganho mensurável de clareza ou testabilidade.
• Nomes longos genéricos: comprimento não substitui significado de domínio.
• Constantes órfãs: nome semântico que não liga ao requisito ou à regra de negócio.

Checklist final

• [ ] Coeso, legível e mantível por outro desenvolvedor sem contexto privilegiado.
• [ ] Zero mágica: literais substituídos por constantes semânticas.
• [ ] Nomes completos, sem abreviações; nada de identificadores “curtos demais” só por hábito.
• [ ] SRP: cada unidade com um motivo claro para mudar.
• [ ] Eficiência: Big-O e padrões de acesso a dados considerados.
• [ ] Pragmatismo: solução mais simples que resolve o problema (KISS/YAGNI).

Racionalizações a ignorar

Violar a letra destas regras é violar o espírito: atalhos “só desta vez” contaminam o restante da revisão.