feat: add the dev-router, lean-code, bugfix/refactor workflows and agents
Every workflow used to run all of its phases for any request, so a one-line fix paid the cost of a feature. dev-router classifies the request into tiers 0-3 with security triggers that raise the tier, and picks the workflow, agents and gate tier. Agents get only the tools their role needs. Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
EvandroandClaude Opus 5.5 committed
1 parent
768b5f6d83
commit
c18d3356ae
13 files changed
+409
No files matched your search
@@ -0,0 +1,68 @@
|
||||
---
|
||||
name: dev-router
|
||||
description: Use no início de qualquer pedido de código (feature, bug, refactor, UI, API, migração, review; "implement", "fix", "build", "add", "change"). Classifica o pedido em nível 0 a 3 e decide quais workflows, agentes e checagens rodar, para um pedido pequeno não pagar o custo de um grande.
|
||||
---
|
||||
|
||||
# Dev Router
|
||||
|
||||
A primeira linha da resposta declara o nível: `Nível N: <motivo em uma frase>`.
|
||||
|
||||
## 1. Classificar
|
||||
|
||||
| Nível | Quando | Exemplos |
|
||||
|---|---|---|
|
||||
| 0, trivial | nenhum comportamento muda; 1 arquivo | texto, cor, typo, renomear variável local |
|
||||
| 1, pequeno | comportamento muda em 1 a 3 arquivos, sem superfície pública nova | bug localizado, ajuste de validação, refactor local |
|
||||
| 2, feature | superfície nova ou contrato alterado; 4+ arquivos; dependência nova | endpoint, tela, módulo, integração |
|
||||
| 3, grande ou de risco | vários módulos ou serviços, dados existentes, arquitetura, release | migração com dados, troca de auth, novo serviço |
|
||||
|
||||
Na dúvida entre dois níveis, escolha o menor e suba quando aparecer um gatilho.
|
||||
|
||||
## 2. Gatilhos que sobem o nível a qualquer momento
|
||||
|
||||
| Gatilho | Mínimo | Soma |
|
||||
|---|---|---|
|
||||
| autenticação, autorização, sessão, tokens, criptografia | 2 | `security-auditor` |
|
||||
| dinheiro, cobrança, dados pessoais (LGPD) | 2 | `security-auditor` |
|
||||
| upload, SQL montado à mão, shell/exec, desserialização, template com entrada do usuário | 2 | `security-auditor` |
|
||||
| dependência nova | 1 | `safedeps` antes de instalar |
|
||||
| migração de schema | 2 (3 se mexe em dado existente) | rollback testado |
|
||||
| feature que chama um LLM | 2 | OWASP LLM Top 10 no `security-auditor` |
|
||||
|
||||
Depois que um gatilho disparou, não rebaixe por conta própria.
|
||||
|
||||
O usuário pode forçar: "modo rápido" vira nível 0 ou 1, mas gatilho de segurança continua valendo (avise); "modo completo" vira nível 3.
|
||||
|
||||
## 3. O que cada nível roda
|
||||
|
||||
| Nível | Fluxo | Workflow | Agentes |
|
||||
|---|---|---|---|
|
||||
| 0 | fazer, rodar o gate | nenhum | nenhum |
|
||||
| 1 | entender ou reproduzir, mudar, teste de regressão, gate | `wf-bugfix` ou `wf-refactor` | `explorer` só se não souber onde está o código |
|
||||
| 2 | explorar, plano curto, TDD, revisão independente, gate | `wf-backend` e/ou `wf-frontend`; full-stack começa pelo contrato do backend | `explorer`, `implementer`, `reviewer`; `security-auditor` com gatilho; `ui-critic` com UI |
|
||||
| 3 | spec EARS com IDs e ADR, aprovação do usuário, tarefas pequenas com TDD, revisões, gate | `wf-architecture` antes; `wf-backend`/`wf-frontend` na execução; `wf-security-review` no fim | `planner`, `implementer`, `reviewer`, `security-auditor`, `ui-critic` com UI, `verifier` |
|
||||
|
||||
Em todo nível: aplique `lean-code`. Peça aprovação do usuário só quando houver uma decisão que é dele (produto, custo, dado existente); no nível 3, a spec sempre passa por ele.
|
||||
|
||||
Delegue a um agente quando o trabalho dele não precisa voltar inteiro para esta conversa (mapear código, revisar um diff). Tarefa que cabe em poucos passos você mesmo faz.
|
||||
|
||||
## 4. Gate de qualidade
|
||||
|
||||
Antes de dizer que terminou, rode:
|
||||
|
||||
```bash
|
||||
"${CLAUDE_PLUGIN_ROOT}/scripts/quality-gate" --tier N
|
||||
```
|
||||
|
||||
- `fail`: corrija. Se não der, explique ao usuário o que falhou e por quê.
|
||||
- `incomplete`: diga ao usuário quais checagens ficaram "não verificado" (ferramenta ausente). Nunca chame de testado o que não rodou.
|
||||
- `dependências novas`: justifique cada uma (ver `lean-code`).
|
||||
|
||||
O hook de `Stop` bloqueia o encerramento enquanto houver código alterado sem gate atualizado ou com gate falho. Configuração por projeto e lista de checagens: [references/quality-gate.md](references/quality-gate.md).
|
||||
|
||||
## 5. Relatório final (nível 1 ou mais)
|
||||
|
||||
1. Nível e motivo.
|
||||
2. O que mudou: arquivos e linhas líquidas (`diff` do gate).
|
||||
3. Evidência: veredito do gate; checagens ok, falhas e não verificadas.
|
||||
4. O que ficou de fora ou é risco conhecido.
|
||||
@@ -0,0 +1,71 @@
|
||||
# Quality gate: checagens e configuração
|
||||
|
||||
`scripts/quality-gate --tier N` roda as checagens do nível N e dos níveis abaixo, só sobre os arquivos
|
||||
alterados em relação à branch base (merge-base com `origin/HEAD`, `main` ou `master`). O resultado vai
|
||||
para `.dev-workflows/gate.json` (ignorado pelo git automaticamente) e uma linha resumida vai para
|
||||
`.dev-workflows/log.jsonl`.
|
||||
|
||||
`--list` mostra o que rodaria e o que está faltando, sem rodar nada.
|
||||
|
||||
## Checagens
|
||||
|
||||
| Nível | Checagem | Ferramenta | Como é detectada |
|
||||
|---|---|---|---|
|
||||
| 0 | lint | script `lint` do package.json, eslint, ruff, `go vet`, clippy | primeira que existir |
|
||||
| 0 | typecheck | script `typecheck`, `tsc --noEmit`, pyright, mypy | tsconfig ou config do checker |
|
||||
| 0 | test | script `test`, pytest (usa `.venv` se existir), `go test`, `cargo test` | stack do projeto |
|
||||
| 0 | secrets | gitleaks, só nos arquivos alterados | binário no PATH |
|
||||
| 1 | diff-coverage | diff-cover sobre `coverage.xml` | relatório de cobertura presente |
|
||||
| 1 | semgrep | `semgrep --config p/default --baseline-commit <base>` | binário no PATH |
|
||||
| 1 | dead-code (info) | knip, vulture | binário no projeto ou PATH |
|
||||
| 2 | build | script `build` | package.json |
|
||||
| 2 | mutation | Stryker nos arquivos alterados; mutmut (paths configurados) | config do Stryker ou `[tool.mutmut]` |
|
||||
| 2 | osv-scanner | `osv-scanner scan source --recursive .` | binário no PATH |
|
||||
| 2 | architecture | dependency-cruiser, import-linter | arquivo de config |
|
||||
| 2 | duplication (info) | jscpd | binário no projeto |
|
||||
| 3 | trivy | vulnerabilidades, misconfig e segredos, HIGH e CRITICAL | binário no PATH |
|
||||
| 3 | traceability | todo `REQ-NNN` da spec aparece em algum teste | `[spec]` na config |
|
||||
|
||||
Estados: `pass`, `fail`, `unverified` (ferramenta ou config ausente, nunca conta como aprovado) e
|
||||
`info` (só relatório). Veredito: `fail` se algo falhou; `incomplete` se algo ficou não verificado; senão `pass`.
|
||||
|
||||
## `.dev-workflows.toml` (opcional, na raiz do projeto)
|
||||
|
||||
```toml
|
||||
timeout = 600 # segundos por checagem
|
||||
|
||||
[commands] # substitui o que foi detectado
|
||||
test = "pnpm vitest run --coverage"
|
||||
lint = "pnpm eslint ."
|
||||
mutation = "pnpm stryker run --incremental"
|
||||
|
||||
[thresholds]
|
||||
diff_coverage = 80
|
||||
|
||||
[coverage]
|
||||
report = "coverage/cobertura-coverage.xml"
|
||||
|
||||
[spec] # nível 3: rastreabilidade requisito -> teste
|
||||
file = "docs/spec.md"
|
||||
tests = ["tests", "e2e"]
|
||||
|
||||
[[check]] # checagem extra; kind = "gate" (padrão) ou "info"
|
||||
name = "lighthouse"
|
||||
cmd = "npx lhci autorun"
|
||||
tier = 2
|
||||
|
||||
[[check]]
|
||||
name = "a11y"
|
||||
cmd = "npx playwright test e2e/a11y.spec.ts"
|
||||
tier = 2
|
||||
|
||||
[[check]]
|
||||
name = "api-fuzz"
|
||||
cmd = "schemathesis run http://localhost:8000/openapi.json --checks all"
|
||||
tier = 2
|
||||
```
|
||||
|
||||
Frontend, API e carga dependem do app estar de pé, então entram como `[[check]]` do projeto
|
||||
(Lighthouse CI com orçamento, Playwright com `@axe-core/playwright`, schemathesis, k6 com thresholds).
|
||||
|
||||
`DW_GATE=off` desliga o hook de `Stop` numa sessão.
|
||||
@@ -0,0 +1,48 @@
|
||||
---
|
||||
name: lean-code
|
||||
description: Use sempre que for escrever ou mudar código. Escolhe a menor solução que resolve de verdade - reaproveitar antes de escrever, apagar antes de somar, sem abstração especulativa e sem dependência desnecessária.
|
||||
---
|
||||
|
||||
# Lean Code
|
||||
|
||||
Primeiro entenda o problema e o código que ele toca. Depois suba a escada e pare no primeiro degrau
|
||||
que resolve.
|
||||
|
||||
## Escada
|
||||
|
||||
1. **Precisa existir?** Pedido especulativo ("para depois", "vai que") não entra. Diga isso em uma linha.
|
||||
2. **Já existe no projeto?** Procure helper, componente, tipo ou padrão parecido antes de escrever (`grep` por nomes e por comportamento; o agente `explorer` faz isso).
|
||||
3. **A biblioteca padrão resolve?**
|
||||
4. **A plataforma resolve?** HTML/CSS nativo antes de JS, constraint do banco antes de código, recurso do framework antes de utilitário próprio.
|
||||
5. **Uma dependência já instalada resolve?**
|
||||
6. **Cabe em poucas linhas?**
|
||||
7. Só então: o mínimo de código novo.
|
||||
|
||||
## Regras
|
||||
|
||||
- **Bug se corrige na causa.** Antes de editar uma função, ache todos os chamadores. Uma correção no ponto por onde todos passam é menor que uma por chamador, e não deixa os outros quebrados.
|
||||
- **Sem abstração sem uso:** interface com uma implementação, factory de um produto, configuração para valor que nunca muda.
|
||||
- **Dependência nova exige justificativa** em uma linha (o que ela faz que os degraus 3 a 6 não fazem) e consulta ao `safedeps` antes de instalar. O gate lista as novas.
|
||||
- **Apague o que ficou morto** por causa da mudança.
|
||||
- **Entre duas soluções do mesmo tamanho**, fique com a que está certa nos casos de borda.
|
||||
|
||||
## Nunca simplifique
|
||||
|
||||
Validação na fronteira do sistema, tratamento de erro que evita perda de dado, controles de segurança,
|
||||
acessibilidade básica e qualquer coisa que o usuário pediu explicitamente.
|
||||
|
||||
## Orçamento de diff (linhas líquidas, referência)
|
||||
|
||||
| Nível | Orçamento |
|
||||
|---|---|
|
||||
| 0 | 20 |
|
||||
| 1 | 100 |
|
||||
| 2 | 400 |
|
||||
| 3 | 400 por fatia entregue |
|
||||
|
||||
Estourou: justifique no relatório ou quebre em partes menores.
|
||||
|
||||
## Atalho consciente
|
||||
|
||||
Quando cortar caminho de propósito (lock global, busca O(n²), heurística simples), deixe um comentário
|
||||
`lean:` dizendo o limite e quando evoluir: `# lean: lock global; trocar por lock por conta se a vazão importar`.
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
name: wf-bugfix
|
||||
description: Use para corrigir bug, erro, exceção, falha, regressão, comportamento errado ("não funciona", "quebrou", "fix"). Reproduz, acha a causa raiz e prova a correção com um teste de regressão que falha antes e passa depois.
|
||||
---
|
||||
|
||||
# Workflow Bugfix
|
||||
|
||||
## 1. Reproduzir
|
||||
|
||||
Encontre o comando, teste ou requisição que mostra o erro, e rode. Sem reprodução, colete mais dado
|
||||
(stack trace, log, entrada exata) em vez de chutar uma correção.
|
||||
|
||||
## 2. Achar a causa raiz
|
||||
|
||||
- Siga o fluxo real do ponto de entrada até o erro.
|
||||
- Ache todos os chamadores da função que você pretende mudar (`grep -rn "nomeDaFuncao(" .`).
|
||||
- Escreva a causa em uma ou duas frases antes de editar. Se não consegue, ainda não achou.
|
||||
- Corrija no ponto por onde todos os chamadores passam, não só no caminho que o relato citou.
|
||||
|
||||
## 3. Provar com teste de regressão
|
||||
|
||||
1. Escreva o teste que reproduz o bug.
|
||||
2. Prove que ele falha sem a correção: `git stash push <arquivos da correção>`, rode o teste, veja vermelho, `git stash pop`.
|
||||
3. Rode de novo com a correção: verde.
|
||||
|
||||
Um teste que passa com e sem a correção não prova nada; reescreva.
|
||||
|
||||
## 4. Gate
|
||||
|
||||
`"${CLAUDE_PLUGIN_ROOT}/scripts/quality-gate" --tier 1` (ou o nível que o `dev-router` definiu).
|
||||
|
||||
## 5. Relatório
|
||||
|
||||
Causa em uma frase, o que mudou, o teste que prova (nome e saída vermelho/verde) e o veredito do gate.
|
||||
|
||||
## Não faça
|
||||
|
||||
- Silenciar o erro com `try/except` ou `catch` vazio.
|
||||
- Mudar o teste até ele passar em vez de corrigir o código.
|
||||
- Corrigir o sintoma num chamador e deixar a causa na função compartilhada.
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
name: wf-refactor
|
||||
description: Use para refatorar, reorganizar, renomear, extrair, simplificar ou limpar código sem mudar o comportamento. Congela o comportamento com testes antes de mexer e mexe em passos pequenos.
|
||||
---
|
||||
|
||||
# Workflow Refactor
|
||||
|
||||
## 1. Rede de segurança
|
||||
|
||||
Os testes atuais cobrem o comportamento que você vai tocar? Se não, escreva **testes de
|
||||
caracterização** antes de mudar qualquer coisa: eles registram o que o código faz hoje, mesmo que
|
||||
pareça estranho. Rode e confirme que estão verdes.
|
||||
|
||||
## 2. Passos pequenos
|
||||
|
||||
Cada passo deixa o código compilando e os testes verdes. Rode os testes a cada passo, não só no fim.
|
||||
Renomeação: procure também em strings, configs, rotas e docs (`grep -rn`), não só nos imports.
|
||||
|
||||
## 3. Comportamento não muda
|
||||
|
||||
Os testes de caracterização não são editados. Se você precisa editar um deles, a mudança não é
|
||||
refactor: pare e pergunte ao usuário.
|
||||
|
||||
## 4. Gate e relatório
|
||||
|
||||
`"${CLAUDE_PLUGIN_ROOT}/scripts/quality-gate" --tier 1` (nível 2 se o refactor atravessa módulos).
|
||||
No relatório, as linhas líquidas: um bom refactor costuma reduzir. Se aumentou, explique.
|
||||
|
||||
## Não faça
|
||||
|
||||
- Misturar refactor com feature ou correção de bug no mesmo diff.
|
||||
- Mudar API pública sem o usuário pedir.
|
||||
- Criar camada ou abstração nova "para ficar mais limpo" sem um uso concreto hoje.
|
||||
Reference in new issue
Block a user