dev-workflows/README.pt-BR.md

Dev Workflows

Workflows de agente como arquivos SKILL.md: frontend, backend, arquitetura e code review de segurança que nunca pulam a verificação.

Transforme seu agente de código num processo repetível e verificável. Cada workflow define fases, passos de verificação concretos, comandos reais e regras duras. O agente entrega trabalho que dá pra checar, não só afirmar.

🇺🇸 Read this in English

---

Por quê

Agente é ótimo pra gerar código e péssimo pra admitir que não sabe. Este projeto resolve a segunda parte.

Cada workflow força o agente a provar o trabalho em cada fase:

• Passos de verificação: rodar build, rodar testes, chamar a API, consultar o registry. Não "acho que funciona".
• Critérios de aceite: portões com checkbox que precisam estar marcados pra fase fechar.
• Regras duras: "nunca faça merge com build vermelho", "nunca afirme 'sem CVE' sem consultar o OSV.dev".
• Harness de QA: um placar que mede a qualidade dos workflows de forma objetiva, mais meta-testes que corrompem o harness pra provar que ele detecta regressão.

Sumário

• Workflows
• Segurança: não confie no cutoff de treino
• Skills usadas e seus donos
• Começo rápido
• O harness de QA
• Testes de qualidade e ganhos medidos
• Estrutura do repositório
• Licença

Workflows

Workflow	Arquivo	Cobre
🎨 Frontend / UI	workflows/wf-frontend.md	Direção de design antes do código, anti-AI-slop, performance React, QA visual de PDFs
⚙️ Backend / API	workflows/wf-backend.md	Contrato antes do handler, defaults seguros, auditoria OWASP, testes + caça de bugs adversarial
🏗️ Arquitetura	workflows/wf-architecture.md	Requisitos mensuráveis, diagramas C4, ADRs, threat modeling, revisão
🛡️ Security review	workflows/wf-security-review.md	Code review (front + back), CVEs conhecidas e consulta ao vivo de novas
📄 README	workflows/wf-readme.md	Criar/auditar/reescrever READMEs grounded nos fatos reais do repo

Cada arquivo é um SKILL.md padrão. A description no frontmatter é o gatilho: quando o contexto do agente bate, o workflow carrega sozinho. Funciona no Hermes Agent, Claude Code e qualquer coisa que leia o formato Agent Skills.

Segurança: não confie no cutoff de treino

O conhecimento de CVEs de um modelo para na data do treinamento. Qualquer coisa divulgada depois disso, ele nunca viu, então "não tem vulnerabilidade" vindo de memória é um chute, não resposta.

O workflow de segurança nasceu desse fato:

Código/diff → SCOPE → HUNT (CVEs conhecidas) → CONSULT (fontes vivas) → CODE REVIEW → REPORT + GATE
                    │                            │
                    │                            └─ OSV.dev · GitHub Advisory DB · NVD
                    └──────────────┘

Todo security review precisa consultar fontes vivas e carimbar a data. Review sem fonte e sem data vence na hora.

Skills usadas e seus donos

Os workflows carregam essas skills por contexto. Os três pilares do security review vêm de fontes primárias de segurança (OWASP, OSV.dev, UnitOne SecuritySkills), não da memória de um modelo.

🛡️ Security review: os três pilares

Vendorizadas em skills/ — ver skills/NOTICE.md pra origem exata e licença.

Skill	O que faz	Dono
safedeps	Consulta o OSV.dev em tempo real; devolve CVE + severidade + versão corrigida pra um package@version. Cobre o buraco que um modelo congelado não cobre.	Jeneidi
sca-audit	Auditoria de supply chain de dependências com análise de alcance e mapeamento CWE.	OWASP
code-review-security	Code review de segurança sistemático mapeado a OWASP Top 10 + ASVS.	OWASP

🛡️ Security review: skills de apoio

Também vendorizadas em skills/.

Skill	O que faz	Dono
secrets-scan	Encontra credenciais / API keys no código e no git history.	OWASP
api-security-review	Revisão de API contra OWASP API Security Top 10.	OWASP
web-security-review	Revisão de web app contra OWASP Top 10.	OWASP
cve-triage	Prioriza CVEs com CVSS 4.0 / EPSS / CISA KEV.	UnitOneAI
patch-prioritization	Decide a ordem da correção.	UnitOneAI
dependency-scanning	Varredura da árvore de dependências.	UnitOneAI
hermaguard	Review adversarial: pré-scan estático + 3 agentes especialistas (edge cases, ataque, blast radius).	Sahil-SS9

🎨 Frontend / UI

Skill	O que faz	Dono
frontend-design	Direção visual intencional, tipografia, fugindo do padrão "IA genérica".	Anthropic
web-design	Estética web coesa.	KAOPU-XiaoPu
vercel-react-best-practices	40+ regras de performance React/Next da engenharia da Vercel.	Vercel Labs
vercel-composition-patterns	Compound components, composição limpa.	Vercel Labs
animate	Motion com propósito.	emilkowalski
impeccable	O vocabulário de design que faltava pros agentes: 23 comandos (craft, shape, audit, polish, animate, live) e 59 regras determinísticas anti-slop. A skill de design frontend mais usada (230k+ instalações).	pbakaus
anti-ai-slop	Detecta padrão visual "gerado por IA" (auto-carregada, local).	skill da comunidade
avoid-ai-writing	Remove AI-isms de microcopy, labels e docs.	conorbronsdon

⚙️ Backend / API

Skill	O que faz	Dono
secure-coding	Padrões de codificação segura em 15 stacks.	securityreviewai
bola-detector	Object-level authorization quebrada (OWASP API1).	apisec-inc
auth-rbac-scaffold	Autenticação + RBAC (OWASP API2 / API5).	apisec-inc
injection-checker	Injeção SQL / ORM / shell / template (OWASP API8).	apisec-inc
openapi-hardener	Sanear schemas OpenAPI / Zod / Pydantic (OWASP API3).	apisec-inc
api-security-review	Review completo OWASP API Top 10.	apisec-inc
security-test-generator	Gera suítes de testes de segurança.	apisec-inc

🏗️ Arquitetura

Skill	O que faz	Dono
system-design	Framework HelloInterview de system design.	Kotivskyi
c4-architecture	Diagramas C4 (Mermaid / Structurizr).	Kotivskyi
isaqb-architecture-governance	arc42 + ADRs.	Kotivskyi
secure-architecture-governance	Threat models STRIDE+CIA, ADRs de segurança.	Kotivskyi

📖 Instruções completas de instalação de cada skill estão em docs/SKILLS.md.

Começo rápido

# 1. Copie os workflows pro diretório de skills do seu agente
# Hermes Agent:
cp workflows/*.md ~/.hermes/skills/software-development/

# Claude Code: cada skill no seu proprio diretorio (nao aceita .md solto)
mkdir -p ~/.claude/skills
for f in workflows/*.md; do
  nome=$(basename "$f" .md)
  mkdir -p "$HOME/.claude/skills/$nome"
  cp "$f" "$HOME/.claude/skills/$nome/SKILL.md"
done

# 2. (Opcional, pro security review) as skills de apoio ja vem vendorizadas
# em skills/ -- sem clone externo, so copiar (Hermes; pra Claude Code use o
# mesmo loop do passo 1 trocando "workflows" por "skills"):
cp -r skills/* ~/.hermes/skills/

# 3. Use
# "review this PR for security"  -> wf-security-review carrega
# "build a new page"              -> wf-frontend carrega

O harness de QA

O diretório qa/ mantém os próprios workflows honestos:

cd qa

python3 wf_quality_harness.py   # pontua cada workflow em 30+ critérios
python3 test_quality.py         # gates: sem regressão, skills válidas, fases verificadas
python3 test_tests.py           # meta-testes: corrompe o harness, prova que ele detecta a corrupção

Os meta-testes são a parte legal. Eles quebram o harness e os workflows de propósito e confirmam que o placar cai. Se o placar não mudasse, o detetor seria inútil. Esses testes ficam verdes como contrato.

Testes de qualidade e ganhos medidos

Números reais das execuções do harness, guardados em qa/snapshots/. A coluna "Antes" é o estado anterior ao refinamento; "Depois" é o resultado após ele.

Score de qualidade dos workflows (mesma régua, antes → depois)

Workflow	Antes	Depois	Ganho
wf-frontend	201.0	385.5	+92%
wf-backend	215.0	424.0	+97%
wf-architecture	199.9	413.7	+107%
wf-security-review	332.0	390.0	+17%
Total	615.9	1223.2	+98.6%

Isso é quase exatamente o dobro da qualidade dos workflows, medido com a mesma régua.

A própria régua também ficou mais exigente ao longo do projeto (13 → 30+ critérios: verificação por fase, comandos reais, anti-padrões, critérios de aceite, artefatos, fluxo). Por isso os snapshots antigos mostram totais menores: base-364 (13 critérios) → baseline-v2 (536.7) → baseline-v3 (675.0) → baseline-v4 (884.6) → baseline-final (1613.2 com quatro workflows). A comparação justa acima usa a régua final dos dois lados.

Gates (checagens de regressão): todos verdes

Gate	O que verifica	Status
G1	Score não caiu abaixo do baseline	✅
G4	Toda skill referenciada existe	✅ 4/4 workflows
G5	Toda fase tem ≥3 verbos de verificação	✅ 4/4 workflows
Meta-testes	Corrompe harness/workflows → score cai (prova que o detetor funciona)	✅

O que o refinamento adicionou

Cada workflow ganhou o mesmo lote de melhorias reais:

• Passos de verificação com comandos de verdade (curl, grep, python3, git, npm, pytest) em vez de prosa.
• Checklists de aceite por fase (portões [ ] marcáveis).
• Blocos de anti-padrões por fase (o que não fazer, e por quê).
• Seções de comandos executáveis e exemplos trabalhados por fase.
• Checkpoints que pausam pra aprovação do usuário entre fases.

O workflow de segurança ganhou uma regra dura: nunca afirmar "sem CVE" sem consultar OSV.dev / GitHub Advisory. O conhecimento do modelo para no cutoff do treino; as fontes vivas não.

Contexto sobre a meta do "dobro"

O harness tem um teto físico (soma dos caps dos critérios). A meta numérica de "2× do baseline" precisaria de uma régua com mais resolução pra ser expressável, então inflar o score pra bater seria maquiar a métrica. O que foi publicado é a versão honesta: qualidade real ~dobrou na mesma régua (+98.6%), com meta-testes provando que a régua detecta regressão.

Estrutura do repositório

dev-workflows/
├── README.md            # versão em inglês
├── README.pt-BR.md      # este arquivo
├── workflows/           # os quatro workflows em SKILL.md
│   ├── wf-frontend.md
│   ├── wf-backend.md
│   ├── wf-architecture.md
│   └── wf-security-review.md
├── docs/
│   └── SKILLS.md        # inventário completo de skills + instalação
├── CONTRIBUTING.md      # o que melhorar, checks locais, processo de PR
└── qa/                  # harness de qualidade, gates, meta-testes
    ├── wf_quality_harness.py
    ├── test_quality.py
    ├── test_tests.py
    └── snapshots/

Licença

MIT © 2026 Evandro Fonseca Junior

---

⭐ Se isso te salvar de um "na minha máquina funciona" no merge, dá uma estrela.