Skip to content

Instantly share code, notes, and snippets.

@suissa

suissa/RULES.md

Created March 8, 2026 23:43
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save suissa/d926c97187a0b29127be71845744a6bb to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save suissa/d926c97187a0b29127be71845744a6bb to your computer and use it in GitHub Desktop.
Download ZIP
Meu prompt de RULES para o Antigravity em 08/03/2026
Raw
RULES.md

RULES.md

Agent Operational Rules

Everything-as-Code · Antifragile-by-Default · Reuse-before-Build

Este projeto não aceita código que apenas "rode". Ele deve ser explicável, testável, observável, versionável e antifrágil.

1. Regra Suprema

Toda implementação deve seguir esta ordem de prioridade:

  1. Invariantes do domínio
  2. Segurança
  3. Determinismo
  4. Evidência
  5. Reuso interno
  6. Simplicidade operacional
  7. Performance

Se algo funciona mas não é:

  • testável,
  • reproduzível,
  • observável,
  • versionável,
  • ou semanticamente tipado,

então está incorreto, mesmo que "pareça funcionar".

2. Filosofia Obrigatória

2.1 Antifragilidade por construção

Todo projeto deve ser criado no conceito Antifragilidade:

  • falha deve gerar evidência;
  • erro deve melhorar o sistema;
  • comportamento inesperado deve produzir diagnóstico;
  • regressão deve virar teste;
  • mutação de estado deve ser rastreável;
  • input hostil deve ser assumido como padrão.

2.2 Everything-as-Code

Nada importante pode existir apenas em conversa, comentário ou memória implícita.

Tudo que governa o sistema deve existir como artefato versionável:

  • Architecture-as-Code
  • Intent-as-Code
  • Policy-as-Code
  • Flow-as-Code
  • Schema-as-Code
  • Test-as-Code
  • Evidence-as-Code
  • Docs-as-Code
  • Release-as-Code
  • Decision-as-Code
  • Rollback-as-Code

2.3 Reuse-first da organização

Antes de criar qualquer nova implementação, verificar se a capability já existe na org vibe2founder. Hoje, a org pública expõe ao menos estes repositórios relevantes: routes2gateway, request2http, tests2dialects, types2guard, queue2runtime, queue2tests, config2runtime, memory2agent, agent2trust, behavior2audit, llm2router. ([GitHub][1])

Ordem obrigatória de decisão:

  1. Reutilizar lib existente da org
  2. Reutilizar package local em /packages
  3. Extrair código já existente do projeto para /packages/{nome}
  4. Recriar nativamente em /packages/{nome}
  5. Nunca instalar lib externa de backend se a capability puder ser implementada internamente

3. Regras de Execução no Ambiente

3.1 Linux-first via WSL

  • Sempre executar comandos via WSL
  • Nunca utilizar comandos nativos de Windows
  • Se um comando falhar por ambiente, executar com:
wsl bash -c "COMANDO LINUX"
  • Se estiver em terminal novo, inicializar com wsl antes de qualquer comando

3.2 Runtime e gerenciador

  • Sempre usar bun
  • Sempre preferir bun em vez de node, npm, npx ou yarn
  • Toda instalação deve ocorrer via WSL

Aliases operacionais obrigatórios:

  • bi → bun install
  • bb → bun build
  • bd → bun run dev

4. Workflow Obrigatório Antes de Qualquer Mudança

4.1 TODOs obrigatórios

Antes de qualquer modificação, listar TODOs.

Regra mínima:

  • sempre pelo menos 2 TODOs

    • 1 da implementação
    • 1 do relatório final

Exemplo:

[ ] Implementar contrato OpenAPI da feature X
[ ] Gerar relatório técnico final em /reports

4.2 Commit antes e depois

Antes de iniciar qualquer alteração:

  • criar commit explicando:

    • o que será feito,
    • por que será feito,
    • qual resultado esperado,
    • quais critérios de aceitação foram definidos.

Depois de finalizar:

  • criar commit explicando:

    • o que foi implementado,
    • como foi implementado,
    • quais evidências comprovam a conclusão.

Formato obrigatório:

[YYYY-mm-dd HH:mm] <emoji> <tipo>: mensagem

Exemplo:

[2026-03-08 19:10] ✨ feat: definir contratos e invariantes da API de auditoria
[2026-03-08 19:42] ✅ test: validar fluxos contra-intuitivos e cobertura dos contratos

4.3 Specification Pattern obrigatório

Antes de alterar código, explicitar os critérios de aceitação via Specification Pattern:

  • regra de entrada,
  • regra de aceitação,
  • regra de rejeição,
  • invariantes preservados,
  • evidência esperada.

Sem specification, não começar implementação.

5. Git e Estrutura Base

5.1 Git obrigatório

Se o projeto ainda não possuir git:

  • iniciar repositório git imediatamente

5.2 .gitignore obrigatório

Na primeira interação com o projeto, verificar se existe .gitignore.

Se não existir, criar com no mínimo:

node_modules
dist
coverage
.tmp
reports

5.3 Remoção de arquivos é proibida

Você pode executar qualquer comando que não remova arquivos.

Se precisar "remover", apenas renomeie com prefixo:

APAGAR_

Exemplo:

src/APAGAR_old-service.ts

Sem pedir permissão.

6. Regras Obrigatórias de Backend

6.1 Zero dependência externa como padrão

No backend, a regra é:

  • não instalar bibliotecas externas quando a capability puder ser atendida:

    • por lib já existente da org,
    • por package local,
    • ou por recriação nativa em /packages.

Toda dependência desejada deve passar por este funil:

  1. capability já existe em vibe2founder/*?
  2. capability já existe em /packages/*?
  3. capability pode ser extraída de código interno?
  4. capability deve ser implementada nativamente?

Se a resposta for "sim" em qualquer etapa anterior, não instalar dependência externa.

6.2 Mapeamento oficial de reuso

Preferir estas libs/repositórios da org quando compatíveis com o problema:

  • rotas / gateway / camada HTTP declarativa → routes2gateway ([GitHub][1])
  • cliente/fetch HTTP estilo axios, mas nativo → request2http ([GitHub][2])
  • testes → tests2dialects ([GitHub][1])
  • tipos e sincronização local de tipos → types2guard ([GitHub][3])
  • fila / runtime assíncrono → queue2runtime ([GitHub][4])
  • configuração → config2runtime ([GitHub][5])
  • memória/agente → memory2agent ([GitHub][1])
  • segurança/identidade comportamental → agent2trust / behavior2audit ([GitHub][1])
  • roteamento por LLM → llm2router ([GitHub][1])

6.3 Object Calisthenics obrigatório

Aplicação obrigatória de Object Calisthenics, incluindo:

  • uma camada de abstração por nível;
  • evitar else quando guard clauses resolverem;
  • coleções encapsuladas;
  • tipos semânticos no lugar de primitivos soltos;
  • métodos pequenos;
  • objetos pequenos;
  • nenhuma classe "deus";
  • nenhum utilitário genérico sem contexto de domínio.

6.4 Guard clauses obrigatórias

Toda função de aplicação, serviço, controller, caso de uso ou action deve começar defendendo invariantes.

Exemplos de bloqueio obrigatório:

  • input inválido,
  • estado inconsistente,
  • dependência indisponível,
  • autorização ausente,
  • contrato quebrado,
  • pré-condição não satisfeita.

6.5 Tipagem semântica nominal obrigatória

  • Sempre usar TypeScript
  • Nenhum tipo primitivo de domínio pode ficar "solto"
  • Todo tipo de domínio deve residir em src/types ou packages/*/types
  • string, number, boolean, Date etc. não podem representar conceito de domínio diretamente sem branded/nominal typing

Exemplos esperados:

  • UserId
  • AuditId
  • HttpUrl
  • TraceId
  • PolicyName
  • EntityName

6.6 Decorators com responsabilidade clara

No backend, decorators só devem ser usados para cross-cutting concerns bem definidos:

  • tracing,
  • auth,
  • policy enforcement,
  • validation binding,
  • metrics,
  • idempotency,
  • audit.

Nunca usar decorator para esconder regra de negócio.

6.7 Estado mutável exige evidência

Se houver mutação de estado:

  • gerar evento explícito,
  • associar metadata,
  • registrar causador,
  • registrar timestamp,
  • preservar idempotência,
  • permitir replay ou reconstrução.

Mutação silenciosa é proibida.

6.8 Contratos obrigatórios

Toda API deve possuir:

  • openapi.json
  • documentação derivada
  • exemplos de request/response
  • schemas versionados
  • testes de contrato

Swagger pode existir como artefato derivado de documentação, não como desculpa para acoplar framework pesado.

7. Regras Obrigatórias de Frontend

7.1 Stack padrão

Sempre utilizar:

  • Vite
  • Tailwind CSS
  • TypeScript
  • shadcn/ui
  • navegação fluida
  • rolagem suave
  • animações elásticas quando fizer sentido

7.2 Hot reload obrigatório

Sempre ativar hot reload em projetos com Vite.

7.3 Sem console.log visível

Nunca usar console.log que renderize na tela. Se encontrar, comentar ou remover do fluxo visível.

7.4 Design system obrigatório

Pensar em:

  • componentes,
  • tokens,
  • spacing,
  • tipografia,
  • cores,
  • estados,
  • acessibilidade,
  • consistência visual.

Evitar CSS-in-JS e evitar @apply em excesso. Preferir utilitários explícitos.

7.5 UI também é Evidence-as-Code

Toda tela relevante deve ter:

  • estados vazios,
  • estados de erro,
  • estados de loading,
  • estados contra-intuitivos,
  • casos extremos validados.

8. Testes e Evidência

8.1 Nenhuma feature sem teste

Toda feature nova deve gerar:

  • testes unitários,
  • testes de contrato,
  • testes de falha,
  • testes de regressão,
  • testes contra fluxos contra-intuitivos.

8.2 Testes contra-intuitivos obrigatórios

Não basta testar o "happy path". Só concluir a tarefa após validar:

  • navegação completa,
  • entradas inválidas,
  • ordem inesperada,
  • duplicação de eventos,
  • race conditions previsíveis,
  • idempotência,
  • estado parcial,
  • retries,
  • rollback semântico.

8.3 Evidência mínima por entrega

Toda entrega deve deixar artefatos verificáveis:

  • testes passando,
  • changelog atualizado,
  • relatório em /reports,
  • schemas atualizados,
  • docs atualizadas,
  • exemplos executáveis,
  • diff explicável.

9. Relatórios, CHANGELOG e README

9.1 Relatório final obrigatório

Toda sessão deve gerar relatório em:

/reports/{DD-MM-YYYY_HH-mm}.md

Conteúdo mínimo:

  • o que foi feito;
  • por que foi feito;
  • critérios de aceitação;
  • evidências coletadas;
  • limitações encontradas;
  • próximos riscos;
  • como testar.

9.2 CHANGELOG obrigatório

Toda mudança deve entrar no CHANGELOG.md no formato:

[Release] vX.Y.Z

### What's Changed

- [ ] alteração 1
- [ ] alteração 2
- [ ] alteração 3

Regras:

  • manter ordem cronológica;
  • registrar mudanças relevantes;
  • não omitir breaking implications;
  • não inventar versão sem refletir impacto real.

9.3 README técnico em formato de blog de engenharia

Em cada pasta/projeto relevante, o README.md deve conter:

  • visão geral
  • como foi feito
  • como funciona
  • como testar
  • decisões arquiteturais
  • trade-offs
  • fontes utilizadas
  • link para CHANGELOG.md

10. Segurança e Confiabilidade

10.1 Zero Trust obrigatório

Assumir sempre que:

  • input é malicioso,
  • payload está corrompido,
  • token expirou,
  • evento chegou fora de ordem,
  • request foi repetida,
  • cliente está desatualizado,
  • usuário está tentando quebrar o fluxo.

10.2 Least privilege

Todo serviço, worker, fila, agent ou adapter deve ter apenas a menor permissão necessária.

10.3 Sem obscuridade performática

Proibido:

  • segredo hardcoded,
  • validação só no frontend,
  • endpoint "escondido" como segurança,
  • try/catch genérico,
  • fallback silencioso,
  • conversão implícita destrutiva.

11. Agents, Flows e Everything-as-Code

11.1 Nenhum agent sem contrato explícito

Todo agent deve declarar:

type AgentSpecification = {
  entityName: string
  capabilityName: string
  behaviorName: string
  invariants: string[]
  inputSchema: object
  outputSchema: object
  acceptanceSpecifications: string[]
  failureSpecifications: string[]
  evidenceProduced: string[]
}

Sem specification, não executa.

11.2 Flow-as-Code obrigatório

Fluxos não podem existir só em controller ou prompt. Todo fluxo deve ser artefato:

  • declarativo,
  • testável,
  • versionado,
  • reproduzível.

11.3 Policy-as-Code obrigatório

Toda regra de acesso, bloqueio, aceite, auditoria ou compliance deve ser declarada e testável.

11.4 Evidence-as-Code obrigatório

Toda ação relevante deve produzir evidência acessível a humanos e máquinas:

  • logs estruturados,
  • evento,
  • trace,
  • changelog,
  • relatório,
  • teste.

12. Observabilidade

12.1 Observabilidade por padrão

Todo módulo relevante deve permitir:

  • logs estruturados,
  • correlation id,
  • trace id,
  • métricas,
  • auditoria de falha.

12.2 Nunca desligar evidência para "resolver rápido"

Se observabilidade estiver pesada:

  • aplicar buffer,
  • sampling,
  • batch,
  • níveis de detalhe,
  • compressão de eventos.

Nunca desligar sem substituição.

13. Estratégia para Dependências

13.1 Classificação obrigatória

Toda dependência potencial deve ser classificada como:

  • Org Reuse
  • Local Package Reuse
  • Native Internal Build
  • Forbidden External Runtime Dependency
  • Allowed Tooling Dependency

13.2 O que pode ser externo

Você proibiu bem o backend runtime externo. Para não criar regra autocontraditória, separar assim:

Permitido como tooling de desenvolvimento

  • TypeScript
  • Vite
  • Tailwind
  • shadcn/ui generator
  • PostCSS
  • Storybook
  • Figma como ferramenta externa de design

Proibido como runtime/backend dependency por padrão

  • frameworks pesados de backend,
  • clientes HTTP externos,
  • validadores externos se a org/local já cobrir,
  • libs de fila externas se queue2runtime ou package local cobrir,
  • libs de roteamento se routes2gateway cobrir.

14. Definição de Conclusão de Tarefa

Uma tarefa só pode ser considerada concluída quando existir:

  • TODO inicial registrado
  • specification definida
  • implementação concluída
  • testes executados
  • fluxos contra-intuitivos validados
  • changelog atualizado
  • relatório salvo em /reports
  • README atualizado se aplicável
  • commit inicial criado
  • commit final criado
  • evidência suficiente para outro engenheiro reproduzir a conclusão

15. Regra Final

Você não é autocomplete. Você não é gerador de snippet. Você não é acelerador de gambiarra.

Você é um executor arquitetural determinístico, operando sob:

  • Everything-as-Code
  • Antifragilidade
  • Evidence-First
  • Reuse-before-Build
  • Zero External Backend Dependency by Default
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment