Evandro Fonseca Junior
45b2259bce
Add pbakaus/impeccable (v4.1.1, 23 design commands, 59 deterministic anti-slop rules) to the frontend workflow and READMEs. Document the QA harness measurements in both READMEs: before/after workflow scores on the same ruler (total +98.6%), the four green gates, the meta-tests, and what the refinement added. Full snapshot history is in qa/snapshots/.
236 lines
14 KiB
Markdown
236 lines
14 KiB
Markdown
<div align="center">
|
||
|
||
# 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)**
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
## 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 |
|
||
|
||
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
|
||
|
||
| 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
|
||
|
||
| 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) |
|
||
| [`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) |
|
||
|
||
### 🏗️ 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
|
||
# Hermes Agent:
|
||
cp workflows/*.md ~/.hermes/skills/software-development/
|
||
|
||
# Claude Code / qualquer agente com diretório de skills:
|
||
mkdir -p ~/.claude/skills && cp workflows/*.md ~/.claude/skills/
|
||
|
||
# 2. (Opcional, pro security review) instale o safedeps + o checker OSV
|
||
git clone --depth 1 https://github.com/Jeneidi/safedeps.git
|
||
cp -r safedeps/skills/safedeps ~/.hermes/skills/safedeps
|
||
cp safedeps/check_deps.py ~/.hermes/skills/safedeps/
|
||
|
||
# 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:
|
||
|
||
```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/`. 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
|
||
└── qa/ # harness de qualidade, gates, meta-testes
|
||
├── wf_quality_harness.py
|
||
├── test_quality.py
|
||
├── test_tests.py
|
||
└── snapshots/
|
||
```
|
||
|
||
## Licença
|
||
|
||
[MIT](LICENSE) © 2026 [Evandro Fonseca Junior](https://github.com/evandrodevbr)
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
⭐ Se isso te salvar de um "na minha máquina funciona" no merge, dá uma estrela.
|
||
|
||
</div>
|