# Dev Workflows
**Workflows de agente como arquivos SKILL.md**: frontend, backend, arquitetura e code review de segurança que nunca pulam a verificação.
[](LICENSE)
[](qa/wf_quality_harness.py)
[](https://agentskills.io)
[](https://github.com/evandrodevbr/dev-workflows/pulls)
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](README.md)**
---
## 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](#workflows)
- [Segurança: não confie no cutoff de treino](#segurança-não-confie-no-cutoff-de-treino)
- [Skills usadas e seus donos](#skills-usadas-e-seus-donos)
- [Começo rápido](#começo-rápido)
- [O harness de QA](#o-harness-de-qa)
- [Testes de qualidade e ganhos medidos](#testes-de-qualidade-e-ganhos-medidos)
- [Estrutura do repositório](#estrutura-do-repositório)
- [Licença](#licença)
## Workflows
| Workflow | Arquivo | Cobre |
|---|---|---|
| 🎨 **Frontend / UI** | [workflows/wf-frontend.md](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](workflows/wf-backend.md) | Contrato antes do handler, defaults seguros, auditoria OWASP, testes + caça de bugs adversarial |
| 🏗️ **Arquitetura** | [workflows/wf-architecture.md](workflows/wf-architecture.md) | Requisitos mensuráveis, diagramas C4, ADRs, threat modeling, revisão |
| 🛡️ **Security review** | [workflows/wf-security-review.md](workflows/wf-security-review.md) | Code review (front + back), CVEs conhecidas **e** consulta ao vivo de novas |
| 📄 **README** | [workflows/wf-readme.md](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](https://hermes-agent.nousresearch.com), 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`](skills/NOTICE.md) pra origem exata e licença._
| Skill | O que faz | Dono |
|---|---|---|
| [`safedeps`](https://github.com/Jeneidi/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](https://github.com/Jeneidi) |
| [`sca-audit`](https://github.com/OWASP/secure-agent-playbook) | Auditoria de supply chain de dependências com análise de alcance e mapeamento CWE. | [OWASP](https://github.com/OWASP) |
| [`code-review-security`](https://github.com/OWASP/secure-agent-playbook) | Code review de segurança sistemático mapeado a OWASP Top 10 + ASVS. | [OWASP](https://github.com/OWASP) |
### 🛡️ Security review: skills de apoio
_Também vendorizadas em `skills/`._
| Skill | O que faz | Dono |
|---|---|---|
| [`secrets-scan`](https://github.com/OWASP/secure-agent-playbook) | Encontra credenciais / API keys no código e no git history. | [OWASP](https://github.com/OWASP) |
| [`api-security-review`](https://github.com/OWASP/secure-agent-playbook) | Revisão de API contra OWASP API Security Top 10. | [OWASP](https://github.com/OWASP) |
| [`web-security-review`](https://github.com/OWASP/secure-agent-playbook) | Revisão de web app contra OWASP Top 10. | [OWASP](https://github.com/OWASP) |
| [`cve-triage`](https://github.com/UnitOneAI/SecuritySkills) | Prioriza CVEs com CVSS 4.0 / EPSS / CISA KEV. | [UnitOneAI](https://github.com/UnitOneAI) |
| [`patch-prioritization`](https://github.com/UnitOneAI/SecuritySkills) | Decide a ordem da correção. | [UnitOneAI](https://github.com/UnitOneAI) |
| [`dependency-scanning`](https://github.com/UnitOneAI/SecuritySkills) | Varredura da árvore de dependências. | [UnitOneAI](https://github.com/UnitOneAI) |
| [`hermaguard`](https://github.com/Sahil-SS9/hermaguard) | Review adversarial: pré-scan estático + 3 agentes especialistas (edge cases, ataque, blast radius). | [Sahil-SS9](https://github.com/Sahil-SS9) |
### 🎨 Frontend / UI
| Skill | O que faz | Dono |
|---|---|---|
| [`frontend-design`](https://github.com/anthropics/skills) | Direção visual intencional, tipografia, fugindo do padrão "IA genérica". | [Anthropic](https://github.com/anthropics) |
| [`web-design`](https://github.com/KAOPU-XiaoPu/web-design) | Estética web coesa. | [KAOPU-XiaoPu](https://github.com/KAOPU-XiaoPu) |
| [`vercel-react-best-practices`](https://github.com/vercel-labs/agent-skills) | 40+ regras de performance React/Next da engenharia da Vercel. | [Vercel Labs](https://github.com/vercel-labs) |
| [`vercel-composition-patterns`](https://github.com/vercel-labs/agent-skills) | Compound components, composição limpa. | [Vercel Labs](https://github.com/vercel-labs) |
| [`animate`](https://github.com/emilkowalski/skill) | Motion com propósito. | [emilkowalski](https://github.com/emilkowalski) |
| [`impeccable`](https://github.com/pbakaus/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](https://github.com/pbakaus) |
| [`design-taste-frontend`](https://github.com/Leonxlnx/taste-skill) | Gera UI nova com direção inferida do brief; três controles de 1 a 10 (variância, motion, densidade). Vendorizada em `skills/`. | [Leonxlnx](https://github.com/Leonxlnx) |
| [`redesign-existing-projects`](https://github.com/Leonxlnx/taste-skill) | Audita uma UI existente e melhora sem quebrar o comportamento. Vendorizada em `skills/`. | [Leonxlnx](https://github.com/Leonxlnx) |
| [`anti-ai-slop`](https://github.com/evandrodevbr/dev-workflows) | Detecta padrão visual "gerado por IA" (auto-carregada, local). | skill da comunidade |
| [`avoid-ai-writing`](https://github.com/conorbronsdon/avoid-ai-writing) | Remove AI-isms de microcopy, labels e docs. | [conorbronsdon](https://github.com/conorbronsdon) |
### ⚙️ Backend / API
| Skill | O que faz | Dono |
|---|---|---|
| [`secure-coding`](https://github.com/securityreviewai/secure-coding-skill) | Padrões de codificação segura em 15 stacks. | [securityreviewai](https://github.com/securityreviewai) |
| [`bola-detector`](https://github.com/apisec-inc/apisec-skills) | Object-level authorization quebrada (OWASP API1). | [apisec-inc](https://github.com/apisec-inc) |
| [`auth-rbac-scaffold`](https://github.com/apisec-inc/apisec-skills) | Autenticação + RBAC (OWASP API2 / API5). | [apisec-inc](https://github.com/apisec-inc) |
| [`injection-checker`](https://github.com/apisec-inc/apisec-skills) | Injeção SQL / ORM / shell / template (OWASP API8). | [apisec-inc](https://github.com/apisec-inc) |
| [`openapi-hardener`](https://github.com/apisec-inc/apisec-skills) | Sanear schemas OpenAPI / Zod / Pydantic (OWASP API3). | [apisec-inc](https://github.com/apisec-inc) |
| [`api-security-review`](https://github.com/apisec-inc/apisec-skills) | Review completo OWASP API Top 10. | [apisec-inc](https://github.com/apisec-inc) |
| [`security-test-generator`](https://github.com/apisec-inc/apisec-skills) | Gera suítes de testes de segurança. | [apisec-inc](https://github.com/apisec-inc) |
> ⚠️ `api-security-review` são duas skills diferentes com o mesmo nome: a da OWASP vendorizada em `skills/` (pilar de segurança, acima) e a da apisec-inc nesta tabela. Só a cópia da OWASP vem neste repositório. Instale a que o seu workflow precisa -- com as duas presentes, agentes que resolvem por nome de skill acusam colisão.
### 🏗️ Arquitetura
| Skill | O que faz | Dono |
|---|---|---|
| [`system-design`](https://github.com/Kotivskyi/architecture-governance-skills) | Framework HelloInterview de system design. | [Kotivskyi](https://github.com/Kotivskyi) |
| [`c4-architecture`](https://github.com/Kotivskyi/architecture-governance-skills) | Diagramas C4 (Mermaid / Structurizr). | [Kotivskyi](https://github.com/Kotivskyi) |
| [`isaqb-architecture-governance`](https://github.com/Kotivskyi/architecture-governance-skills) | arc42 + ADRs. | [Kotivskyi](https://github.com/Kotivskyi) |
| [`secure-architecture-governance`](https://github.com/Kotivskyi/architecture-governance-skills) | Threat models STRIDE+CIA, ADRs de segurança. | [Kotivskyi](https://github.com/Kotivskyi) |
> 📖 Instruções completas de instalação de cada skill estão em [docs/SKILLS.md](docs/SKILLS.md).
## Começo rápido
```bash
# 1. Copie os workflows pro diretório de skills do seu agente.
# Cada skill precisa do seu próprio diretório com um SKILL.md dentro -- um
# .md solto numa pasta de categoria não é indexado (nem o Hermes nem o
# Claude Code carregam), por isso o loop abaixo monta a estrutura certa.
SKILLS_DIR="$HOME/.hermes/skills/software-development"
# Claude Code: SKILLS_DIR="$HOME/.claude/skills"
for f in workflows/*.md; do
nome=$(basename "$f" .md)
mkdir -p "$SKILLS_DIR/$nome"
cp "$f" "$SKILLS_DIR/$nome/SKILL.md"
done
# 2. (Opcional, pro security review) as skills de apoio já vêm vendorizadas
# em skills/ -- sem clone externo, só copiar:
cp -r skills/* "$HOME/.hermes/skills/"
# 3. Use
# "review this PR for security" -> wf-security-review carrega
# "build a new page" -> wf-frontend carrega
```
Pra conferir se a instalação pegou: os workflows devem aparecer na lista de
skills do agente (`hermes skills list` no Hermes Agent).
## O harness de QA
O diretório `qa/` mantém os próprios workflows honestos:
```bash
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/baseline-final.json`. 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 as execuções antigas mostram totais menores: `base-364` (13 critérios) → `baseline-v2` (536.7) → `baseline-v3` (675.0) → `baseline-v4` (884.6) → `baseline-final` (1613.2 nos quatro workflows pontuados). Só o snapshot final está commitado, em `qa/snapshots/baseline-final.json` -- é ele que os gates leem e é ele que se atualiza quando a pontuação muda. 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 cinco workflows em SKILL.md
│ ├── wf-frontend.md
│ ├── wf-backend.md
│ ├── wf-architecture.md
│ ├── wf-security-review.md
│ └── wf-readme.md
├── skills/ # o pilar de segurança, vendorizado (ver skills/NOTICE.md)
│ ├── safedeps/ # + arquivos de apoio plays/, templates/, schemas/, docs/
│ ├── sca-audit/
│ ├── code-review-security/
│ ├── api-security-review/
│ ├── web-security-review/
│ ├── secrets-scan/
│ ├── cve-triage/
│ ├── patch-prioritization/
│ ├── dependency-scanning/
│ ├── hermaguard/
│ ├── design-taste-frontend/ # taste-skill (frontend)
│ └── redesign-existing-projects/ # taste-skill (frontend)
├── 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
├── baseline.json
└── snapshots/
└── baseline-final.json
```
## Licença
[MIT](LICENSE) © 2026 [Evandro Fonseca Junior](https://github.com/evandrodevbr)
---
⭐ Se isso te salvar de um "na minha máquina funciona" no merge, dá uma estrela.