Visão
02 · Princípios e regras
As regras que valem para toda stack, qualquer que seja a tecnologia. No modelo
zerado, elas estão no AGENTS.md (para os agentes) e nas ORGs (para as
pessoas), e as que podem ser conferidas por máquina estão em hooks e na CI.
Os princípios
- Decidir antes de construir. A stack é definida — e as lacunas do modelo preenchidas — antes de qualquer código de produto. Toda decisão técnica com alternativas vira ADR. Toda mudança de comportamento vira change do OpenSpec.
- Tudo versionado, nada flutuante. Ferramenta, biblioteca, imagem Docker, action
de CI, CLI chamada por
npx: sempre com versão exata.latest,^,~,*,ubuntu-latest,postgres:16(sem o patch) não existem numa stack da Hibex. - O humano publica, o agente prepara. Git de escrita, GitHub, deploy, infraestrutura real e valores de segredos são exclusivos do mantenedor. O agente entrega o conteúdo pronto e as instruções.
- Teste primeiro. Nenhum código de produção sem um teste que falhou antes dele.
- Uma mudança por vez, especificada. A change do OpenSpec é a unidade de trabalho; código de produto só depois de a change ser aprovada.
- Tudo reproduzível na máquina. O ambiente local sobe do zero com um comando, com dados de exemplo e um usuário por perfil, sem nenhum segredo real.
- Segurança por padrão. Toda aplicação com área restrita é autenticada e autorizada por permissões finas; uma aplicação pública (site, landing) é declarada como tal; toda porta interna fica interna; nenhum segredo em arquivo versionado.
- Operável desde o primeiro deploy. Logs, métricas, traces, sonda de vida e backup existem antes da primeira funcionalidade de produto.
- A camada de cima vence. Plataforma > arquitetura > stack. O que falta em cima vira pedido, nunca exceção local.
As regras invioláveis
Cada regra diz como é garantida. Regra que só depende de disciplina é anotada como tal — e é candidata a virar verificação automática.
Git, GitHub e infraestrutura
| Regra | Garantia |
|---|---|
O agente nunca executa Git de escrita (init, add, commit, push, tag, mv, restore, checkout, stash, worktree…) | Garantia: hook block-git-writes.py (PreToolUse) |
| O agente nunca cria repositório, issue, PR ou recurso no GitHub | Garantia: hook block-git-writes.py (gh de escrita) |
O agente nunca roda kamal (fora de version, help, docs, init), ssh para fora da máquina, bws, nem chamadas administrativas a Keycloak/banco/Grafana reais | Garantia: hook block-infra.py (PreToolUse) |
| Toda entrega termina com instruções de commit (mensagem sugerida) e, se houver, instruções de deploy | Garantia: AGENTS.md (protocolo de entrega) |
Segredos
| Regra | Garantia |
|---|---|
Segredos vivem no Bitwarden Secrets Manager; o repositório só tem referências (deploy/*/.kamal/secrets) | Garantia: revisão + CI (busca de padrões de segredo) |
Valores em documentação e exemplos são sempre placeholders (<VALOR>) | Garantia: AGENTS.md |
| O agente nunca lê, exibe nem ecoa valores de segredos | Garantia: AGENTS.md |
Segredos de desenvolvimento são óbvios e falsos (dev-secret-<app>) e só existem no ambiente local descartável | Garantia: revisão |
Credenciais de terceiros no desenvolvimento (ex.: OAuth do Google) ficam em arquivo *.local ignorado pelo Git e nunca em exports versionados | Garantia: .gitignore + revisão |
Versões
| Regra | Garantia |
|---|---|
Toda dependência com versão exata, numa fonte única por ecossistema (catálogo de versões, lockfile, Dockerfile, compose.yaml, workflow) | Garantia: CI: eng/pinned-versions.sh falha com latest, faixas ou tags sem patch |
Imagens Docker com tag completa (postgres:16.6), e de preferência com digest nas imagens de produção | Garantia: CI |
Actions de CI fixadas por versão (de preferência por SHA) e runner fixado (ubuntu-24.04) | Garantia: CI |
| Toda ferramenta usada em script ou guia aparece como pré-requisito com versão | Garantia: revisão; o script confere em tempo de execução |
| Adicionar uma dependência exige registrar o porquê (ADR quando houve alternativa) | Garantia: AGENTS.md + revisão |
Mudança e decisão
| Regra | Garantia |
|---|---|
| Comportamento de produto só entra por change do OpenSpec aprovada | Garantia: AGENTS.md; openspec validate --strict na CI |
Decisão técnica com alternativas → ADR em docs/decisoes/ | Garantia: AGENTS.md; rules.design do openspec/config.yaml |
| ADR criada pelo agente nasce proposta; só o mantenedor promove para aceita | Garantia: AGENTS.md |
| ADR aceita não é reescrita; uma decisão revertida vira substituída, com link | Garantia: revisão |
| Atualizar o design system, a arquitetura ou uma versão maior de dependência também é change | Garantia: AGENTS.md |
Código e testes
| Regra | Garantia |
|---|---|
| TDD: o teste é escrito e visto falhando antes do código, em qualquer camada | Garantia: as regras do openspec/config.yaml; tasks.md com tarefa de teste antes da de código, conferido por eng/tdd-order.sh na CI; relato do agente |
| Testes de integração usam dependências reais em container (banco, Keycloak), nunca simulacros que fingem ser outra tecnologia | Garantia: ORG-0015 (testes) |
| Todo cenário de spec tem cobertura: unidade, integração ou E2E | Garantia: revisão da change (tasks.md) |
| Nenhuma tela muda sem o caso E2E correspondente ajustado na mesma change | Garantia: AGENTS.md |
| A CI roda build, testes, verificador do design system, validação do OpenSpec, lacunas, versões e a ordem do TDD | Garantia: .github/workflows/ci.yml |
Interface
| Regra | Garantia |
|---|---|
Toda tela segue o design system da Hibex; vendor/hibex/ nunca é editado à mão | Garantia: hook block-vendor-hibex.py + verificador na CI |
O que falta no design system vira hibex-pendente: NNNN <assunto> e um pedido | Garantia: verificador (conta pendentes) |
Plataforma e operação
| Regra | Garantia |
|---|---|
| Scripts, guias e instruções assumem Linux | Garantia: revisão |
Scripts falham cedo com ERRO: claro, conferem os próprios pré-requisitos e são idempotentes sempre que possível | Garantia: revisão; padrão de eng/ |
Toda aplicação: observável (contrato de telemetria), com /up; com área restrita, autenticada no Keycloak; pública, declarada como pública | Garantia: testes de integração do contrato |
| Todo banco: backup diário com restauração testada | Garantia: ORG-0022 (backup); guia |
Idioma
| Regra | Garantia |
|---|---|
| Documentação, specs, ADRs, textos de tela e respostas do agente em português brasileiro | Garantia: AGENTS.md |
| Identificadores, código, nomes de serviço, realm e client em inglês | Garantia: revisão |
| Termos técnicos consagrados não se traduzem (commit, deploy, container, realm…) | Garantia: revisão |
Nas specs: prosa pt-BR, palavras-chave SHALL/MUST/WHEN/THEN em inglês | Garantia: openspec validate |
O que não é regra da arquitetura
Para não engessar o que deve variar:
- a escolha de linguagem, framework, banco, ferramenta de build;
- se a interface é renderizada no servidor ou no navegador (desde que siga o design system e seja testável pelo E2E);
- quantas aplicações a stack tem e como se dividem os módulos;
- o domínio do produto e o seu vocabulário.
Essas escolhas são obrigatórias de fazer — são lacunas — mas o conteúdo é livre.