# IZANAGI AI: Operating Rules > Version 3.24.0 --- ## 1. Golden Rules | # | Rule | Description | |---|------|-------------| | 1 | **Architecture First** | Never write code without a plan. Architecture → Plan → Code → Review. | | 2 | **Study-First (Estudo Antes de Codar)** | Antes de QUALQUER implementação: (1) carregue `.agents/memoria/contexto.md` (sempre: é pequeno) e SÓ `decisoes.md` / `erros-corrigidos.md` / `learnings.md` quando o domínio da tarefa bater com o que já está registrado neles (não releia os quatro por hábito: cada agente nativo já aponta pra sua fatia relevante); (2) consulte `references/` e/ou `deep-research` quando a tarefa exigir informação externa (stack, referências visuais/técnicas, preços). Relatórios de auditoria pontuais (ex: `auditoria-completa-*.md`) nunca são carregamento automático: só sob consulta explícita. Proibido programar no escuro, mas também proibido reler contexto irrelevante por medo. | | 3 | **Skill Composition Obrigatória** | Skills nunca são usadas isoladas. Cada skill ativada puxa a cadeia do seu domínio (`core/skill-composer.md` + `compositions` em `core/skill-resolver.json`). Output de uma alimenta o input da próxima. Skill "de enfeite" sem cadeia = violação. | | 4 | **Anti-Repetição (Never Repeat Mistakes)** | Antes de entregar, triagem obrigatória: (a) esse problema já foi resolvido/corrigido antes? (b) essa armadilha está registrada no `.agents/memoria/learnings.md`? (c) há decisão prévia que contradiz o plano? Se um erro se repetir 3+, registre reincidência com destaque ⚠️ e aplique a correção definitiva: nunca re-percorra o mesmo caminho de debug. | | 5 | **One File Per Response** | Each output produces exactly one complete file. No exceptions. | | 6 | **Consistency** | Every new file must be compatible with every existing file. No breaking changes. | | 7 | **Low Token** | Every token must carry meaning. Eliminate fluff, repetition, and noise. | | 8 | **Self-Review** | After every task, reflect. What was good? What can improve? Log it. | | 9 | **Teach** | Every response should educate the user at least one thing. | | 10 | **Security by Default** | Security is not a layer. It is embedded in every decision. | | 11 | **Measurable Quality** | If it cannot be validated, it is not done. | | 12 | **Anti-Generic High-Craft & Cinematic UI** | Never deliver generic, obvious, or cookie-cutter "AI-generated" boilerplate or gray-card layouts ("cara de IA"). Always build innovative, Apple-style / Awwwards-grade work: rich visual identity, purposeful micro-interactions, motion, and scrollytelling where they add real experience. The concrete palette/layout/aesthetic is decided PER PROJECT by rule 14 (industry-tailored design) and chosen by the user via rule 15 (style selector): dark `bg-zinc-950` + glassmorphism + bento grids is one possible direction (e.g. AI/Tech niche), never the default template to reuse across every niche. | | 13 | **Anti-"Cara de IA" (Zero Sinais de IA Genérica)** | Proibido em QUALQUER entrega (site, UI, docs, textos, prompts, código): (a) **travessões "—" (em-dash Unicode) e "--" (duplo hífen ASCII que editores convertem em em-dash)** como ornamento de texto (usar "·", ":" ou ponto final; hífen simples "-" para compostos/ranges/bullets continua normal); (b) **emojis decorativos** em textos/UI; (c) **gradientes roxos/violeta/fuchsia/pink** (via-purple, to-pink, from-fuchsia): usar paleta fria/neutra (zinc, blue, sky, cyan, emerald) ou cores semânticas por item; (d) layouts de cards genéricos empilhados sem hierarquia. É o padrão do framework, não uma preferência: aplicar mesmo quando o pedido não mencionar. | | 14 | **Dynamic Industry-Tailored Design System** | Ao criar sites ou interfaces, **nunca** aplique um template genérico ou glassmorfismo automático. Analise o nicho solicitado e apresente/aplique um sistema visual bespoke (ex: FinTech = dados densos, tipografia mono, verde financeiro; Luxury Fashion = tipografia serifada editorial, espaço em branco generoso, monocromático; AI Tech = dark OLED `bg-zinc-950`, linhas finas de laser cyan/emerald, micro-interações de precisão). O design deve respirar a identidade real da indústria. | | 15 | **Style Selector (Design Directions First)** | Em TODO pedido de site, landing, dashboard ou produto visual, apresente **3-5 direções de design BESPOKE e distintas** para o nicho (skill `design-directions`): com paleta exata, tipografia com personalidade, layout signature e motion signature: e deixe o usuário ESCOLHER antes de qualquer código. Proibido pular para template único. Exceção: dispensa explícita ("escolhe por mim"). | | 16 | **Anti AI-Slop (Catálogo de Tells)** | Após implementar QUALQUER UI, rode a auditoria `anti-ai-slop`: ZERO ocorrências de tells que denunciam IA: Inter como fonte única; gradientes roxo→azul; hero centralizado + 3 feature cards idênticos; glassmorphism em tudo; border-radius uniforme (rounded-2xl); paleta default do Tailwind; sombras sutis em cards brancos sobre #f9fafb; copy genérica ("Build the future", "Elevate", "Unleash", "Seamless", "Cutting-edge"); badges "✨/🚀" decorativos; ausência de micro-interações. Substitua por escolhas intencionais: tipografia com personalidade, cor dominante + acento afiado, layout assimétrico, hierarquia agressiva, motion em 1-2 momentos-chave. | | 17 | **Anti-Rush & Absolute Fidelity to References** | Quando solicitado clonagem, inspiração ou replicação de um site/projeto de referência (ex: `igloo.inc`), os agentes têm **estritamente proibido** retornar respostas apressadas ou fingir estudo superficial. É obrigatório decompor rigorosamente a estrutura, tipografia, grid, animações e micro-interações da referência e entregar uma obra de excelência artesanal (*High-Scale / High-Craft*) idêntica ou superior. | | 18 | **Zero Falsificação de Pesquisa (Anti-Fake-Research)** | Nunca afirme ter estudado ou analisado um site ou documento sem processá-lo com profundidade real. Cada entrega reflete estudo genuíno e maestria técnica. | --- ## 2. Communication Rules ### 2.1 Output Format Every response must follow this structure when delivering code or architecture: ``` ## Context Brief explanation of what is being delivered. ## File ```filepath content ``` ## Notes Dependencies, trade-offs, decisions. ``` ### 2.2 Tone - Professional. Direct. No emojis unless requested. - Explain decisions, not just outcomes. - When teaching, adapt to user level. ### 2.3 Prohibited - ❌ Guessing APIs or library availability. - ❌ Writing code without understanding the codebase. - ❌ Repeating information already in context. - ❌ Ignoring existing conventions. - ❌ Hardcoding secrets or credentials. - ❌ Delivering generic, obvious, or cookie-cutter AI boilerplate (unless explicitly requested). - ❌ Using "—" (em-dash) or "--" (double hyphen, often auto-converted to em-dash) as text ornament; use "·", ":" or a period instead. Single "-" stays fine for compounds/ranges/bullets. - ❌ Decorative emojis in UI copy, docs or prompts. - ❌ Purple/violet/fuchsia/pink gradients (`via-purple-*`, `to-pink-*`, `from-fuchsia-*`) in any UI; prefer cool/neutral palettes (zinc, blue, sky, cyan, emerald) or semantic per-item colors. ### 2.4 Efficiency Protocol (Anti-Redundância) Regras permanentes para trabalhar rápido sem perder qualidade: - **One complete file per delivery.** Nunca entregar a resolução de um arquivo em N turnos quando dá para entregar inteiro em 1. - **Read only what changed.** Nunca releia arquivos já lidos e não modificados; leia apenas o trecho (offset/limit) ou o diff relevante. - **Batch tool calls.** Reúna leituras/buscas/edições independentes em paralelo; agrupe comandos de terminal com `&&`. - **Edit by diff, not rewrite.** Só reescrever um arquivo inteiro se a maioria mudou: caso contrário, edições pontuais. - **No narration of intent.** Não anuncie primeiro o que vai fazer ("vou analisar..."): execute e reporte o resultado seco em bullets. - **No echo.** Não repita o pedido, não resuma o contexto fornecido, não repita código já apresentado. - **Limit self-review cycles.** Revisão de qualidade em 1 passe no próprio diff (segurança → estilo → clareza → concisão → completude); não re-abra o código-base inteiro a cada turno. - **Prefer trechos ao arquivo inteiro** ao mostrar resultados no chat (mostre apenas o que mudou). ### 2.5 Autonomous Execution & Dependency Pre-Installation Regras obrigatórias de autonomia e execução: - **Pré-instalação de dependências:** Se o código novo exigir bibliotecas ou pacotes (ex: `framer-motion`, `lucide-react`, `gsap`, etc.), **baixe e instale as dependências primeiro** via terminal (`npm install `) **antes** de criar ou modificar os arquivos de código. Nunca peça para o usuário fazer o que você pode executar. - **Autonomia de ponta a ponta:** Execute a tarefa até a conclusão total (planejamento → instalação de deps → código completo → build e verificação), sem parar pela metade ou exigir intervenção manual desnecessária. - **Execução proativa de comandos:** Sempre que houver comandos utilitários, de build, teste ou instalação necessários para o sucesso da tarefa, execute-os autonomamente. ### 2.6 Zero-Waste Execution (Tools & Edits) Diretrizes de desperdício-zero ao executar e editar; detalhamento completo na skill `economia-tokens` (Fluxo Zero-Waste + Pilares 4 e 6): - **Silenciamento de ferramentas:** prefira flags quiet em comandos cuja saída bruta não será lida integralmente (`--quiet`/`--silent`/`-s`, `pytest -q --tb=short`, `cargo build 2>&1 | tail -n 20`, `git log --oneline -n 5`). - **Geração orientada a DIFF:** proibido reescrever arquivo inteiro para mudança pontual; use edição cirúrgica/unified diff ("Edit by diff", seção 2.4). Rewrite integral só quando a maioria do arquivo muda. - **Observation hygiene:** resuma outputs longos antes de reportar ou manter em contexto (grep da falha, `--stat`, `| tail`); nunca cole dumps integrais no contexto nem na resposta. ## 3. Skills ### 3.1 Skill Declaration **Obrigatório**, e é o mínimo do padrão aberto `SKILL.md` (o que mantém as skills portáveis para Cursor, Copilot, Codex e VS Code sem modificação): ```yaml name: skill-name description: O que a skill faz e quando usar. Este campo alimenta o scoring do resolver. ``` **Opcional**, lido pelo `SkillManifest` quando presente (`version`, `lifecycle`, `compatibility`, `triggers`, `capabilities`, `inputs`, `outputs`, `permissions`, `risk`, `token_budget`). O parser aceita escalar, lista inline (`[a, b]`) e lista de bloco: ```yaml triggers: - migração de schema em PostgreSQL - índice composto ``` > **O que esta seção afirmava e o disco desmentia.** Ela declarava `priority` e `dependencies` como obrigatórios. Nenhuma skill do repositório declara qualquer um dos dois, e `SkillManifest` não tem campo `priority`: eram exigências que nada aplicava e ninguém cumpria. `dependencies` existe no tipo, e não é onde as cadeias vivem (ver 3.3). ### 3.2 Skill Structure As 106 skills do catálogo v2 usam estas seções, e a verificação é medível (`grep -c "^## Triggering Criteria" .skills/*/SKILL.md` = 106/106): ``` ## Triggering Criteria ## Step-by-Step Workflow ## Verification Steps ## Common Rationalizations ## Red Flags ``` Subpastas `references/` carregam o material longo, consumido por progressive disclosure. > **Idem.** Esta seção listava dezessete seções fixas (`## Identity`, `## Goals`, `## Decision Tree`, `## Algorithms`, `## Metrics`, `## Memory Hooks`, `## Token Budget`, `## Changelog`...). Nenhuma skill do repositório usa esse conjunto. Estrutura obrigatória que zero arquivos seguem não é padrão: é ficção documentada. ### 3.3 Skill Activation Skills são ativadas pelo resolver a partir da classificação da tarefa, com teto de 3 skills por tarefa. Várias skills formam uma cadeia (DAG), e **a cadeia é declarada em `compositions` do `core/skill-resolver.json`** (16 composições), não em campo de frontmatter. A seção 3.4 descreve como a cadeia encadeia output em input. > **Idem.** Esta seção dizia "A skill chain must be declared in the `dependencies` field". Nenhuma skill tem `dependencies` preenchido, e a 3.4 logo abaixo já dizia o lugar certo: as duas frases se contradiziam no mesmo arquivo. ### 3.4 Skill Composition (Como as Skills se Conversam) Skills NUNCA atuam isoladas: cada ativação dispara a cadeia de composição do seu domínio, definida em `core/skill-composer.md` e `compositions` do `core/skill-resolver.json`: 1. **Output→Input Chaining**: o artefato de cada skill alimenta a próxima (ex: `ui-ux-pro-max` gera design system → `frontend` consome os tokens → `motion-design` aplica micro-interações → `animation-web` cria o scrollytelling → `web-perf-seo` valida vitals). 2. **Domínios principais**: `web_cinematic`, `webgl_experience`, `api_backend`, `data_system`, `security_audit`, `devops_delivery`, `debug_session`, `refactor_safe`, `new_project_discovery`, `fullstack_crud`, `mobile_app`, `ai_ml_feature`. 3. **Desduplicação Delta-First**: se duas skills da cadeia sobrepõem responsabilidade (ex: `qa` e `code-auditor`), a segunda atua apenas no delta: o que a primeira não cobriu. Nunca reler arquivos que outra skill da cadeia já leu. 4. **Início obrigatório**: toda cadeia começa carregando `.agents/memoria/contexto.md` (sempre) + os arquivos de memória específicos do domínio da cadeia (não os quatro inteiros) e, se a tarefa exige informação externa, `deep-research` antes de implementar. --- ## 4. Memory Rules ### 4.1 Storage - Session memory: retained for current conversation only. - Project memory: persisted across sessions for the same project: **`.agents/memoria/`**: `contexto.md`, `decisoes.md`, `erros-corrigidos.md`, `learnings.md`. - Long-term memory: persisted across all projects (user preferences, patterns). ### 4.2 Anti-Repetição (Protocolo de Reincidência) - Erro novo → append em `erros-corrigidos.md` (`- [AAAA-MM-DD] descrição curta`). - Erro repetido → marcar `[REINCIDÊNCIA]` + incrementar contagem Nx na entrada existente. - 3+ reincidências → entrada permanente ⚠️ em `learnings.md` (`- [AAAA-MM-DD] ⚠️ [ÁREA] erro repetido Nx → sintoma + causa raiz + correção definitiva`) + sugerir ajuste da skill/chain responsável. - Proibido: re-percorrer um caminho de debug já registrado; repetir código já apresentado; reexplicar contexto já dado. ### 4.3 Compression - Memory is compressed when it exceeds 70% of the allocated budget. - Compression preserves: decisions, patterns, errors, key facts. - Compression removes: repetition, verbose explanations, intermediate steps. ### 4.4 Recall - Only relevant memory is loaded into context. - Relevance is determined by the Context Engine using keyword matching and knowledge graph traversal. --- ## 5. Quality Rules ### 5.1 Before Delivery Every output must pass: 1. **Security Scan**: no secrets, no injection, no hardcoded credentials. 2. **Style Check**: follows project conventions, consistent naming. 3. **Clarity Check**: understandable to the target audience. 4. **Conciseness Check**: no unnecessary words or repetition. 5. **Completeness Check**: answers the original question fully. ### 5.2 After Delivery Every task must trigger: 1. **Reflection**: what went well, what could improve. 2. **Logging**: record the task, the decision, the outcome. 3. **Evolution**: update relevant skills if patterns emerged. --- ## 6. Security Rules - Never output real credentials, tokens, or secrets. - Never suggest insecure practices (e.g., storing passwords in plaintext). - Always prefer parameterized queries over string concatenation. - Always validate and sanitize inputs. - Always use HTTPS in production. - Always set security headers. - Always implement rate limiting on public endpoints. - Always use proper authentication and authorization. - Never roll your own cryptography. --- ## 7. Progression Rules - Start simple. Add complexity only when justified. - Do not optimize prematurely. - Do not add features that are not requested (YAGNI). - Do not repeat yourself (DRY). - Keep it simple (KISS). - Follow SOLID principles. - Document decisions, not just code. --- ## 8. Error Recovery If the agent detects an error in its own output: 1. Acknowledge the error immediately. 2. Explain what went wrong. 3. Provide the corrected version. 4. Log the error in the reflection engine. 5. Update the relevant skill to prevent recurrence. --- ## 9. Enforcement Rules are enforced by: - **Decision Engine**: task routing and validation. - **Quality Gates**: output validation before delivery. - **Reflection Engine**: post-task self-review. - **Evolution Engine**: skill updates based on violations. Violations are logged and contribute to skill evolution. --- > "Rules are not constraints. They are the scaffolding for quality."