القائمة
Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments. TRIGGER ao escrever ou revisar qualquer código no projeto.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Checklists de entrega — verificações antes de fechar feature/PR/commit: type-check (npm run build no Docker), comportamento verificado (não só compila), leis do projeto respeitadas (migração via ensureColumn, permissão grupo vs bot, concorrência fire-and-forget, backup antes de destrutivo). TRIGGER antes de commit/PR de feature, ao finalizar implementação, na verification phase do spec-implement, ou quando o usuário pede "está pronto?" / "revisa antes de mergear".
StickerBot — leis always-on do sistema. TRIGGER ao mexer com: banco de dados / schema / migração (Drizzle + MySQL, sem framework de migração → ensureColumn), criar ou editar comando (auto-loader em src/handlers/text.ts, permissões admin-do-grupo vs admin-do-bot), handlers fire-and-forget / estado em memória / concorrência, config em runtime (Settings + cache), envio de mensagem/menção/mídia via Baileys, ou ao fazer operação destrutiva no banco em produção. Estas leis são a autoridade máxima sobre restrições do sistema.
Estratégias de refatoração segura — quebrar arquivos grandes, extrair função/handler quando um bloco fica grande demais, Dispatcher Pattern para orquestradores grandes, refator incremental (slice, não big-bang), preservar API pública estável, 1 commit = 1 transformação reversível, NUNCA misturar refator + feature no mesmo commit. TRIGGER quando um arquivo/função cresce demais, ou quando o usuário pede "refatora", "extrai", "limpa esse arquivo", "quebra esse monolito", ou ao revisar PR pra detectar code smell de tamanho.
Spec-Driven Development unificado em 3 fases + Modo Retroativo. Plan (design.md + impact.md + tasks.md em .specs/<feature>/ com gates de aprovação), Implement (executa tasks uma a uma com checkpoint + post-task verification + 3-Strike Error Protocol, mantém journal.md vivo registrando desvios, erros+soluções e pedidos extras), Reflect (análise pós-implementação visitando journal.md, propondo criar workflow-<feature> skill, atualizar CLAUDE.md, cross-references e aprendizados em rules). Modo Retroativo faz engenharia reversa de feature já implementada SEM spec. TRIGGER ao iniciar feature nova, planejar implementação complexa multi-arquivo, executar spec já planejado em .specs/, capturar desvios durante implementação, ou consolidar/documentar conhecimento de um módulo.
Como criar e editar comandos do StickerBot. TRIGGER ao adicionar um comando novo em src/commands/, editar um comando existente, mexer com permissões (admin do grupo vs admin do bot), parsing de argumentos, respostas/reações, menções ou subcomandos. Cobre o auto-loader, a interface StickerBotCommand, checkCommand, os helpers de baileysHelper e os padrões de permissão.
Camada de persistência do StickerBot — Drizzle ORM sobre MySQL (mysql2). TRIGGER ao adicionar/alterar tabela ou coluna, escrever query, mexer em src/db/schema.ts ou src/handlers/db.ts, criar migração, ou padrão de config em runtime (Settings + cache). Cobre: schema tipado, CREATE TABLE IF NOT EXISTS no boot, migração idempotente via ensureColumn (sem framework de migração), padrões de query/upsert, e o script SQLite→MySQL.
| name | clean-code |
| description | Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments. TRIGGER ao escrever ou revisar qualquer código no projeto. |
| allowed-tools | Read, Write, Edit |
Be concise, direct, and solution-focused.
| Principle | Rule |
|---|---|
| SRP | Single Responsibility - cada função/classe faz UMA coisa |
| DRY | Don't Repeat Yourself - extraia duplicação, reutilize |
| KISS | Keep It Simple - a solução mais simples que funciona |
| YAGNI | You Aren't Gonna Need It - não construa o que não vai usar |
| Boy Scout | Deixe o código mais limpo do que encontrou |
| Elemento | Convenção |
|---|---|
| Variáveis | Revelam intenção: userCount não n |
| Funções | Verbo + substantivo: getUserById() não user() |
| Booleanos | Forma de pergunta: isActive, hasPermission, canEdit |
| Constantes | SCREAMING_SNAKE: MAX_RETRY_COUNT |
Se precisa de comentário pra explicar um nome, renomeie.
| Regra | Descrição |
|---|---|
| Pequenas | Idealmente 5-20 linhas |
| Uma coisa | Faz uma coisa, bem feita |
| Um nível | Um nível de abstração por função |
| Poucos args | Máx 3, prefira 0-2 |
| Sem efeito colateral | Não mutar inputs inesperadamente |
Estrutura: guard clauses (early return), flat > nested (máx 2 níveis), composição de funções pequenas.
Propagar tipos frouxos (any) em interfaces públicas é débito que se espalha: refactor não pega erro em compilação e o bug vaza em runtime; autocompletar morre. Defina tipos explícitos em fronteiras públicas. Quando inevitável (lib sem tipos), isole o any numa única função wrapper. (No StickerBot, typeof tabela.$inferSelect do Drizzle dá os tipos do banco de graça — use.)
| ❌ | ✅ |
|---|---|
| Comentar cada linha | Apague comentários óbvios |
| Helper pra one-liner | Inline |
| utils com 1 função | Coloque onde é usado |
| Deep nesting | Guard clauses |
| Magic numbers | Constantes nomeadas |
| God functions | Divida por responsabilidade |
| "Primeiro a gente importa..." | Só escreva o código |
| Pergunta | Por quê |
|---|---|
| O que importa este arquivo? | Pode quebrar |
| O que este arquivo importa? | Mudança de interface |
| É componente/helper compartilhado? | Vários lugares afetados |
Edite o arquivo + todos os dependentes na MESMA task. Nunca deixe import quebrado.
O usuário quer código funcionando, não uma aula de programação.
