rdd-quality-gates
Quality gates universal para qualquer stack backend e frontend Angular — verifica KISS, YAGNI, DRY, SOLID, Clean Code, padrões de teste, segurança e performance. Comandos de automação vêm do playbook da stack carregado (fonte única — IMP-077). Métricas: complexidade, cobertura, duplicação, smell-count. Carregada por rdd-dev-backend (Passo 7.1) e rdd-dev-frontend, ou manualmente via skill. Use junto com "quality gates", "qualidade de código", "SOLID", "KISS", "YAGNI", "DRY", "code review", "métricas". Use quando o usuário pedir para verificar qualidade, rodar quality checks ou auditar código.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-04
- Stars
- ★ 4
- Forks
- 1
01 前言 Front Matter
- name
- rdd-quality-gates
- description
- Quality gates universal para qualquer stack backend e frontend Angular — verifica KISS, YAGNI, DRY, SOLID, Clean Code, padrões de teste, segurança e performance. Comandos de automação vêm do playbook da stack carregado (fonte única — IMP-077). Métricas: complexidade, cobertura, duplicação, smell-count. Carregada por rdd-dev-backend (Passo 7.1) e rdd-dev-frontend, ou manualmente via skill. Use junto com "quality gates", "qualidade de código", "SOLID", "KISS", "YAGNI", "DRY", "code review", "métricas". Use quando o usuário pedir para verificar qualidade, rodar quality checks ou auditar código.
03 SKILL.md 正文
rdd-quality-gates — Checklist Universal de Qualidade de Código
Skill transversal de qualidade para qualquer stack backend. Verifica princípios de código, padrões de teste, segurança e performance. Não substitui o playbook da stack — complementa com verificações transversais que se aplicam a qualquer linguagem.
Lê (upstream)
- Código-fonte do repo alvo (read-only) — arquivos modificados pela task
- Playbook da stack carregado (se existir) — para comandos de verificação
AGENTS.mddo repo — convenções específicas~/.config/opencode/knowledge/security-review/KNOWLEDGE.md— fonte canônica dos critérios de segurança (seção D — OWASP ASVS 5.0.0 e Top 10:2025)
Gera (downstream)
- Nenhum artefato de módulo — esta skill gera checklist e métricas para o relatório do rdd-dev-backend
Nunca edita
- Código-fonte (read-only)
- Artefatos de spec RDD
Tools
read/glob/grep— inspecionar código (read-only)bash— executar comandos de formatação/lint da stack
Modo de erro
warn — ferramenta de automação indisponível ou com falha não bloqueia a
auditoria: pule o comando, registre como "não executado" no relatório e
siga com a verificação manual das seções A-E. Quality gate FAIL não
aborta a skill — apenas bloqueia o [done] da task no rdd-dev-backend.
A — Princípios de Código
KISS (Keep It Simple, Stupid)
Manter soluções o mais simples possível. Se uma solução tem mais de 2 alternativas, escolha a mais direta e legível.
| Regra | Verificação | Severidade |
|---|---|---|
| Método com ≤ 1 nível de abstração | Cada função faz UMA coisa | error |
| Método com ≤ 30 linhas | wc -l ou contagem manual |
error |
| Solução mais direta escolhida | Sem frameworks complexos para problemas simples | warning |
| Sem over-engineering | Classes/interfaces que não são usadas pela task atual | warning |
YAGNI (You Ain't Gonna Need It)
Não implemente funcionalidade futura. Só code o que a spec pede HOJE.
| Regra | Verificação | Severidade |
|---|---|---|
| Sem código "para o futuro" | Classes/métodos que não são chamados pela task | error |
| Sem abstrações genéricas prematuras | Interfaces com 1 implementação | warning |
| Sem features não solicitadas | Tudo que foi implementado mapeia para RN | error |
| Sem parametrização excessiva | Config options que ninguém usa | warning |
DRY (Don't Repeat Yourself)
Extraia lógica duplicada para métodos, services ou herança.
| Regra | Verificação | Severidade |
|---|---|---|
| Code duplication < 3% | Blocos > 10 linhas duplicados | error |
| Lógica de negócio não duplicada | Mesma regra em 2+ lugares → extrair | error |
| Validação não duplicada | Usar framework de validação (FluentValidation, etc.) | warning |
| Config não duplicada | Constantes centralizadas, não hardcoded em vários arquivos | warning |
SOLID
| Princípio | Regra | Verificação | Severidade |
|---|---|---|---|
| SRP | 1 classe = 1 responsabilidade | Max 5 métodos públicos, max 3 concerns | error |
| OCP | Aberto para extensão, fechado para modificação | Strategy para > 3 branches no mesmo tipo | warning |
| LSP | Subtipos são substituíveis | Sem NotImplementedException em overrides |
error |
| ISP | Interfaces pequenas | Max 5 métodos por interface | warning |
| DIP | Depender de abstrações | Constructor injection, nenhum new de serviço |
error |
Clean Code
| Regra | Verificação | Severidade |
|---|---|---|
| Nomes revelam intenção | GetOverdueOrders() não GetOrders() |
warning |
| Parâmetros ≤ 4 | Mais que 4 → usar record/objeto | warning |
| Early return | Evitar if/else aninhado > 2 níveis | warning |
| Funções puras quando possível | Sem side effects em lógica de negócio | warning |
| Constantes nomeadas | Sem números mágicos (MAX_RETRY = 3 não if (count > 3)) |
error |
B — Checklist de Código
Erros (error — bloqueante)
- [ ] Método > 30 linhas → refatore (Extract Method)
- [ ] Classe > 300 linhas → divida por responsabilidade
- [ ] Catch vazio (
catch { }) → registre log ou re-throw - [ ]
Console.WriteLine/printem código de produção → remova ou use logger - [ ]
newdireto de serviço (DI container) → use constructor injection - [ ]
async void(exceto event handlers) → mude paraasync Task - [ ] TODO sem ticket →
TODO(autor): descrição [TICKET-123] - [ ] Código comentado removido → use git history
- [ ] Números mágicos → extraia para constante nomeada
- [ ] SQL concatenado → use parameterized queries / ORM
Warnings (warning — informativo)
- [ ] Método com muitos níveis de abstração → extraia helpers
- [ ] Classe com muitos dependencies → aplique ISP (interfaces menores)
- [ ] Parâmetros > 4 → use record/DTO
- [ ] Método faz muita coisa → divida (SRP)
- [ ] Código duplicado em 2+ arquivos → extraia para service/shared
- [ ] Validação inline → use framework (FluentValidation, etc.)
- [ ] Magic strings → extraia para constants ou enums
C — Padrões de Teste
Pirâmide de Testes
/\
/ E2E \ ~10% — lento, caro, frágil
/--------\
/Integração\ ~20% — velocidade moderada
/--------------\
/ Unitários \ ~70% — rápido, isolado, barato
/------------------\
AAA (Arrange, Act, Assert)
[Fact]
public void CalculateTotal_WithValidItems_ReturnsSum()
{
// Arrange
var items = new[] { new Item(10), new Item(20) };
var calculator = new OrderCalculator();
// Act
var result = calculator.CalculateTotal(items);
// Assert
Assert.Equal(30, result);
}
Naming de Testes
| Stack | Formato | Exemplo |
|---|---|---|
| .NET | Method_Scenario_ExpectedResult |
GetUser_WithValidId_ReturnsUser |
| Java | should ExpectedBehavior when Condition |
shouldReturnUserWhenIdIsValid |
| Rust | fn test_<scenario>_<expected> |
fn test_get_user_valid_id_returns_user |
Checklist de Testes
- [ ] 1 teste por RN mínimamente
- [ ] Cenários de erro cobertos (contrato)
- [ ] Testes independentes (ordem não importa)
- [ ] Sem dependência de estado externo (mock/in-memory)
- [ ] Determinísticos (sem random, sem time-dependent)
- [ ] Nome descreve comportamento testado
- [ ] AAA pattern (sem lógica no teste)
- [ ] Assertions ≤ 3 por teste (ideal: 1 por behavior)
D — Segurança
Fonte canônica dos critérios: knowledge/security-review/KNOWLEDGE.md
(OWASP ASVS 5.0.0 + Top 10:2025 + Secure Code Review Cheat Sheet) —
tabela abaixo atualizada da lista 2021 para a Top 10:2025 (A03
Software Supply Chain Failures e A10 Mishandling of Exceptional
Conditions são novas; Misconfiguration subiu para A02; Injection caiu
para A05; SSRF foi absorvido em A01). Papéis: esta tabela é referência
rasa no gate; a triagem profunda de findings de segurança é da skill
rdd-security-audit (consumida pelo rdd-dev-reviewer, eixo 3).
OWASP Top 10:2025 — Checklist
| # | Risco (2025) | Verificação | Severidade |
|---|---|---|---|
| A01 | Broken Access Control (SSRF absorvido) | Auth + AuthZ server-side por objeto, default deny, sem bypass por API direta (P-03) | error |
| A02 | Security Misconfiguration | Defaults seguros por ambiente, headers/TLS, debug off em prod, segredos fora do código (P-05) | warning |
| A03 | Software Supply Chain Failures | Triagem de CVE, versões pinadas, verificação de integridade de artefato/hash (P-06) | error |
| A04 | Cryptographic Failures | Algoritmos modernos, hash de senha dedicado + salt, CSPRNG, IV/nonce correto (P-07) | error |
| A05 | Injection | Queries parametrizadas / ORM, encode contextual na saída, allowlist (P-02) | error |
| A06 | Insecure Design | Abuse cases em features novas, rate limit/quota em fluxos sensíveis (P-10) | warning |
| A07 | Authentication Failures | Rate limiting, lockout, hash de senha dedicado, gestão de sessão (P-03/P-07) | error |
| A08 | Software or Data Integrity Failures | Pinning/assinatura de artefatos e updates, pipeline protegido (P-06) | warning |
| A09 | Security Logging & Alerting Failures | Eventos de segurança logados sem PII e com alerta correlato (P-08) | warning |
| A10 | Mishandling of Exceptional Conditions | Fail closed, erros sem disclosure de stack/dado sensível (P-04) | error |
Validação de Input
- Usar framework de validação (FluentValidation, Jakarta Validation, etc.)
- Validar no handler/command, não no controller
- Limits de tamanho em strings (MaximumLength)
- Tipos primitivos validados (não confiar em casting)
Secret Management
- [ ] Nenhum segredo hardcoded no código
- [ ] Segredos via environment variables ou secret manager
- [ ]
appsettings.jsonsem segredos reais - [ ]
.gitignoreexclui arquivos com segredos
E — Performance
N+1 Queries
// ERRADO: N+1 queries
var orders = await context.Orders.ToListAsync();
foreach (var order in orders)
{
order.Customer = await context.Customers.FindAsync(order.CustomerId); // N queries!
}
// CORRETO: Eager loading
var orders = await context.Orders
.Include(o => o.Customer)
.ToListAsync(); // 1 query
| Check | Severidade |
|---|---|
| Queries em loop → eager loading | error |
ToList() antes de filtro → filtrar antes |
warning |
AsNoTracking() em queries de leitura |
warning |
Include() faltando → N+1 |
error |
Async/Await
| Check | Severidade |
|---|---|
.Result / .Wait() / .GetAwaiter().GetResult() → deadlock |
error |
Task.Run() sem necessidade → thread pool starvation |
warning |
| CancellationToken não propagado → memória leak | error |
ConfigureAwait(false) em libraries |
warning |
Memória
| Check | Severidade |
|---|---|
IDisposable sem using / await using |
error |
| Coleções estáticas crescendo ilimitado | warning |
| Streams não disposed | error |
| Event handlers não unsubscribed | warning |
Conexões
| Check | Severidade |
|---|---|
| Connection pooling habilitado | warning |
| Connection string com pooling params | warning |
| HttpClient sem IHttpClientFactory | error |
F — Automação por Stack (fonte única: playbook da stack)
Os comandos de automação não são duplicados nesta skill — consulte a
seção "Comandos de build e verificação" / "Quality Checks" do playbook da
stack carregado (rdd-stack-dotnet-csharp, rdd-stack-java-quarkus,
rdd-stack-angular, rdd-stack-rust), que é a fonte única (IMP-077).
Sem playbook carregado, aplique apenas o checklist manual (A-E) e registre
automação como "não executada".
Interpretação de resultados frontend Angular: budget de bundle
excedido (angular.json budgets) = warning; erro de compilação
TypeScript = error; componente sem spec = warning.
G — Métricas
Colete e reporte as seguintes métricas:
Complexidade
| Métrica | Limite | Ação |
|---|---|---|
| Complexidade ciclomática | ≤ 10 por método | Refatorar se > 10 |
| Complexidade cognitiva | ≤ 15 por método | Refatorar se > 15 |
| Linhas por método | ≤ 30 | Extract Method |
| Linhas por classe | ≤ 300 | Dividir responsabilidade |
Cobertura
| Métrica | Mínimo | Ação |
|---|---|---|
| Line coverage (novo código) | ≥ 80% | Adicionar testes |
| Branch coverage | ≥ 75% | Testar todos os caminhos |
| Mutation score | ≥ 70% | Mutation testing |
Duplicação
| Métrica | Limite | Ação |
|---|---|---|
| Code duplication rate | < 3% | Extrair método compartilhado |
| Blocos duplicados > 10 linhas | 0 | Refatorar imediatamente |
Technical Debt
| Métrica | Limite | Ação |
|---|---|---|
| Debt ratio | < 5% | Corrigir issues acumuladas |
| Issue density | < 1/1000 linhas | Resolver issues críticas |
G2 — Triagem de Severidade com Jev (opcional, não bloqueante)
Issues ambíguas entre níveis (ex.: número mágico que pode ser regra de
negócio oculta × simples estilo) podem receber uma segunda opinião
calibrada do modelo Jev antes de classificar. Uso opcional e por exceção:
apenas quando a severidade não for óbvia pelas tabelas A-F. Executor:
o caminho via task ao @rdd-jev-classifier só existe para quem tem a
tool task (ex.: primary rdd-dev executando inline) — subagents como o
rdd-dev-backend usam o curl diretamente abaixo; os dois caminhos são
equivalentes.
Chamada (PowerShell):
$key = [System.Environment]::GetEnvironmentVariable("TYPESAFE_API_KEY", "User")
$state = "Issue: <descricao da issue com trecho do codigo>`nContexto: <RN ou regra relacionada, se houver>"
$body = @{
state = $state; model = "jev-latest"
questions = @{
severidade = @{ type = "choice"; criteria = @{ bloqueia_release = "Violacao de regra de negocio ou risco de bug em producao"; warning = "Divida tecnica ou legibilidade, sem quebra de regra"; info = "Estilo ou sugestao, sem efeito funcional" } }
evidencia = @{ type = "noul"; instructions = "A issue tem evidencia objetiva no codigo, sem depender de contexto adicional?" }
}
} | ConvertTo-Json -Depth 10
$r = Invoke-RestMethod -Uri "https://api.typesafe.ai/v1/systemone" -Method Post -ContentType "application/json" -Headers @{ Authorization = "Bearer $key" } -Body ([System.Text.Encoding]::UTF8.GetBytes($body))
# $r.answers.severidade.choice + .confidence ; $r.answers.evidencia.noul
Regras:
- Sem chave de API, sem rede ou confidence < 0.5 → classifique pelas tabelas A-F e siga (a triagem Jev não aconteceu — não mencione no relatório)
- Confidence ≥ 0.5 → use a severidade sugerida e registre no relatório:
severidade: <nivel> (Jev, conf. <0.00-1.00>) - NUNCA invente "(Jev, conf. ...)" sem chamada real
- Issues com violação clara das tabelas A-F (severity error explícito) não precisam de triagem — use o Jev apenas na zona cinzenta
H — Formato de Relatório
O executor (rdd-dev-backend ou rdd-dev-frontend) deve incluir as métricas no relatório final. Exemplo backend:
══ rdd-dev-backend — <task> ═══
repo: <nome>.<API|CORE> (stack: <stack>)
arquivos: <path:linha> — <change> (por arquivo)
RNs cobertas: RN-XXX, RN-YYY
testes: <N novos/N alterados> — <comando verify>: <PASS|FAIL|not-verified>
métricas: complexidade:<avg>/<max> | cobertura:<N%> | duplicação:<N%> | smells:<N critical/N major> | quality-gate:<PASS|WARN|FAIL>
decisões: <trade-off>
pendências: <lista ou "nenhuma">
No frontend, a linha métricas: usa cobertura/smells/quality-gate
(sem complexidade/duplicação quando não coletáveis) — ver formato do
rdd-dev-frontend.
Interpretação do quality-gate
| quality-gate | Significado |
|---|---|
PASS |
Todos os checks error passaram, warnings≤5 |
WARN |
Todos os error passaram, warnings>5 |
FAIL |
Pelo menos 1 check error falhou — NÃO reportar done |
Algoritmo
- Detectar stack: leia o playbook da stack carregado (se existir) para identificar comandos de verificação
- Rodar automação: execute os comandos de automação do playbook da stack (fonte única — seção F)
- Verificar checklist: passe pelo checklist das seções B+C+D+E
- Coletar métricas: complexidade, cobertura, duplicação
- Classificar: PASS / WARN / FAIL
- Reportar: inclua métricas no relatório do rdd-dev-backend
Casos de Borda
- Repo sem ferramentas de análise: pule automação, faça apenas verificação manual. Sinalize no relatório que faltam tools
- Métricas indisponíveis: se não há como coletar cobertura
(sem testes), reporte
cobertura: N/A - Stack não listada: aplique apenas checklist manual (A-E), sem automação
- Refatoração grande: se a task exige refatoração de classe
500 linhas, divida em sub-tasks
Formato de commit
refactor(<modulo>): <descricao-curta> — quality gates: PASS
04 同仓库更多 Skills
rdd-wiki-lint
Audita integridade dos artefatos RDD: contradições entre seções, artefatos órfãos, referências cruzadas quebradas, links internos inválidos e drift de estrutura. Complementa rdd-validate (que valida a DAG de RNs → downstreams) e rdd-decision-audit (que valida DECISIONS.md) com foco em integridade documental dos artefatos individualmente. Use quando o usuário pedir "lint dos documentos", "verificar integridade dos artefatos", "wiki lint", "contradições nos docs" ou "validar estrutura".
rdd-vps-troubleshoot
Diagnóstico guiado por sintoma para VPS da organização já configurada — container unhealthy / healthcheck expirando, GHCR denied/unauthorized no pull, git "could not read Username for 'https://github.com'", GitHub Actions (appleboy/ssh-action) falhando SSH (handshake failed, ParsePrivateKey), services systemd duplicados do cloudflared em activating (auto-restart), requisições caindo no servidor errado (tunnel compartilhado), porta ocupada, logs (journalctl / docker logs), conectividade (curl local vs público, ss, nc) e banco vazio / migrations não aplicadas. Base de conhecimento: runbook.md nesta pasta (sintomas genéricos de deploy em VPS; lições de produção da organização no pack `rules/<pack-da-organizacao>.md` — IMP-105). Modo guiado — sugere comandos com explicação; o operador executa na VPS. Use quando o usuário reportar "container unhealthy", "deploy falhou", "ssh action erro", "ghcr denied", "tunnel não responde", "banco vazio", "sem tabelas", "service duplicado", "vps com problema" ou pedir troubleshooting de deploy.
rdd-vps-setup
Wizard guiado de setup de VPS nova (OS do perfil — ex.: Amazon Linux) para hospedar uma API — atualização do sistema, Docker + Compose + buildx, permissões de arquivos, autenticação no registry do perfil (ex.: ghcr.io), git via SSH (deploy keys), chave SSH dedicada do GitHub Actions (appleboy/ssh-action), tunnel Cloudflare EXCLUSIVO por servidor + route DNS (domínio do perfil), tunnels como serviço systemd (autostart), logging do cloudflared com rotação, pipeline completo de deploy (push main → build → registry → ssh-action → deploy.sh) e backup automatizado (RClone + cronie + canal de alerta do perfil). Base de conhecimento validada: pack da organização em `rules/<pack-da-organizacao>.md` §infra-vps-setup (IMP-105). Modo guiado — sugere comandos com explicação; o operador executa na VPS. Use quando o usuário pedir "setup de VPS", "configurar VPS nova", "preparar servidor para deploy", "tunnel cloudflare", "ghcr", "deploy key", "backup rclone", "docker compose na vps" ou "pipeline de deploy na VPS".
rdd-validate
Percorre o grafo de documentos do projeto e valida integridade: RN sem downstream esperado, ID quebrado, CR aprovado sem reflexo. Gera relatório VALIDATION_REPORT.md. Suporta flag --fix para auto-correção. Use quando o usuário pedir "validar integridade", "checar a DAG", "validar referências cruzadas" ou "validação do módulo".
rdd-ui-spec
Gera UI_SPEC.md a partir das RNs em REQUIREMENTS.md. Descreve telas, componentes, fluxos de navegação, validações de frontend e regras de exibição condicional. Use quando o usuário pedir "especificação de UI", "spec de telas", "layout de formulários" ou "fluxo de navegação".
rdd-ui-capture
Captura evidência visual em runtime do sistema legado para migração (golden master de UI) via MCP Playwright — screenshots por rota/estado, requisições de rede observadas e erros de console, gravados em reverse/ui/ com manifesto reverse/UI_CAPTURE.md e candidatas visuais na fila reverse/CANDIDATES.md. Complemento runtime da engenharia reversa estática (IMP-144). Use quando o usuário pedir "captura visual", "golden master de UI", "screenshots do legado", "captura de UI" ou "ui capture".