Padrões de Qualidade de Repositório
Definition
Padrões de qualidade de repositório (repository-quality standards) é o conjunto de políticas compartilhadas de lint, hygiene, analyzer, pin de versões, adaptadores de hook e regras de revisão que uma organização mantém num repo central e distribui para todos os seus repos consumidores. O modelo de referência é o repo melodic-software/standards: a “fonte normativa” das convenções — mudanças de padrão acontecem no repo central; cada repo downstream recebe o resultado via referências/packages nativos ou PRs de sincronização revisados. Um downstream repo é dono apenas do próprio comportamento de produto, escopo do projeto e exceções locais explícitas.
A ideia central para o founder/PM não-técnico: em vez de cada repo reinventar regras de qualidade, uma organização mantém um único lugar onde as convenções vivem, e cada projeto herda delas. Isso separa a pergunta “como esta empresa escreve código com qualidade” da pergunta “o que este produto específico faz”.
Key Points
-
Ownership boundaries separam o que é regra de org do que é regra de produto. O repo central é dono de lint, hygiene, analyzer, texto, runtime-pin, hook-adapter e review policy — regras que fazem sentido em todos os repos da organização. O repo consumidor é dono do comportamento de produto e de exceções locais explícitas. “Está errado impor a um repo que você não controla” uma política que só faz sentido dentro da sua org.
-
Modelo de componentes com dono único. Um componente é a menor capability com um owner normativo e um ciclo de vida de update. Ele pode exportar um único arquivo ou um grupo atômico de arquivos heterogêneos. Testes, fixtures e documentação de manutenção ficam no repo central (upstream); o consumidor só recebe o que operacionalmente precisa. Uma ferramenta sem consumer vivo fica como experimento local, não como componente órfão no catálogo.
-
Cadeia de delivery preferida — sem templating genérico. A preferência de distribuição segue a ordem: control plane da plataforma → package/reference nativo → extensão nativa da ferramenta → sincronização exata de arquivos → ownership local explícito. Não existe camada de templating genérico nem partial-merge. Arquivos gerenciados são read-only downstream: uma mudança reutilizável sobe primeiro, depois desce para os consumidores.
-
Separar o determinístico do que exige raciocínio.
conventions/guarda padrões de engenharia, revisão e processo que não podem ser reduzidos honestamente a tooling automatizado; o resto vira config raiz canônica. O design reconhece que existe um limite real do que lint automatiza — o que sobra deixa de ser regra de ferramenta e vira convenção documentada. -
CI dogfooda a própria política. A CI exercita cada policy raiz, roda os contract tests de cada componente, valida o adaptador Lefthook composto e agrega as lanes bloqueantes em
ci-status. O “repo das regras” segue as próprias regras — a definição de pronto se aplica também a quem define o pronto.
Implications
Para quem constrói produto com IA, esse modelo de referência valida o mesmo instinto que agent-rules-books concretiza: regras de engenharia devem viver uma vez e ser reutilizadas — o alternativo é cada projeto ter convenções divergentes e cada agente reler livros de novo. A distinção org-policy vs. product-behavior é transferível como princípio: num projeto pequeno, o founder é simultaneamente a org e o produto, mas a separação delimita o que é regra durável (“este projeto sempre faz X”) do que é decisão de produto (“este feature faz Y”).
A separação determinístico/convenção explica por que lint automatiza o que dá e documenta o resto — o mesmo desenho que este vault usa. E a cadeia de delivery (package nativo antes de sync de arquivos) é uma lição de higiene: preferir o mecanismo que a plataforma já oferece antes de inventar distribuição manual.
Open Questions
- O repo tem 1 star e 0 forks — é o padrão interno de uma única organização, não necessariamente canônico na comunidade. Aplicabilidade ampla não está testada.
- Não fica claro o custo operacional do modelo para uma org pequena (quantos repos justificam manter um repo central de standards vs. configs locais repetidas).
Related Concepts
- vibe-coding — universo ao qual pertencem estas convenções de construção com IA
- ciclo-issue-branch-pr-merge — o loop de entrega cujas etapas estas políticas de qualidade verificam
- branch-isolation-for-agents — isolamento por branch/worktree que sustenta a entrega disciplinada
- system-design — alfabetização técnica da qual faz parte a higiene de repositório
- lint — o lado automatizado (cross-wiki, rota main) do que estas políticas impõem
- agent-rules-books — a mesma intuição de “regras uma vez, reutilizadas em tudo”