forjajs 5.0.1 → 5.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +38 -2
- package/README.md +4 -2
- package/README.pt-BR.md +4 -1
- package/boilerplates/02-saas-starter/README.md +58 -293
- package/boilerplates/02-saas-starter/backend/.env.example +13 -0
- package/boilerplates/02-saas-starter/backend/.oxlintrc.json +8 -0
- package/boilerplates/02-saas-starter/backend/nest-cli.json +6 -0
- package/boilerplates/02-saas-starter/backend/package.json +32 -73
- package/boilerplates/02-saas-starter/backend/src/app.module.ts +16 -16
- package/boilerplates/02-saas-starter/backend/src/billing/adapters/http/billing.controller.ts +55 -0
- package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/orm-entities.ts +28 -0
- package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/typeorm-billing.repository.ts +46 -0
- package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.spec.ts +58 -0
- package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.ts +68 -0
- package/boilerplates/02-saas-starter/backend/src/billing/billing.module.ts +11 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.spec.ts +23 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.ts +36 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/ports.ts +27 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.spec.ts +28 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.ts +47 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/auth.dto.ts +22 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/identity.controller.ts +59 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/orm-entities.ts +25 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/typeorm-identity.repository.ts +47 -0
- package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.spec.ts +72 -0
- package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.ts +63 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/model.spec.ts +19 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/model.ts +42 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/password.spec.ts +17 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/password.ts +26 -0
- package/boilerplates/02-saas-starter/backend/src/identity/identity.module.ts +12 -0
- package/boilerplates/02-saas-starter/backend/src/main.ts +19 -19
- package/boilerplates/02-saas-starter/backend/src/platform/auth/jwt-auth.guard.ts +17 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/principal.ts +22 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.spec.ts +23 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.ts +20 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/token.service.ts +54 -0
- package/boilerplates/02-saas-starter/backend/src/platform/config.spec.ts +18 -0
- package/boilerplates/02-saas-starter/backend/src/platform/config.ts +33 -0
- package/boilerplates/02-saas-starter/backend/src/platform/platform.module.ts +14 -0
- package/boilerplates/02-saas-starter/backend/tsconfig.build.json +6 -0
- package/boilerplates/02-saas-starter/backend/tsconfig.json +16 -21
- package/boilerplates/02-saas-starter/backend/vitest.config.ts +7 -0
- package/boilerplates/02-saas-starter/boilerplate.manifest.json +19 -14
- package/boilerplates/02-saas-starter/docker-compose.yml +10 -24
- package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +15 -132
- package/boilerplates/02-saas-starter/memory/30-domains/identity/context.md +20 -0
- package/boilerplates/README.md +9 -10
- package/dist/bin/init-project.js +1 -0
- package/dist/lib/core/journey.js +10 -0
- package/dist/lib/generators/memory-generator.d.ts +0 -11
- package/dist/lib/generators/memory-generator.js +5 -161
- package/dist/lib/generators/readme-generator.js +1 -1
- package/dist/lib/llm/json-output.d.ts +14 -0
- package/dist/lib/llm/json-output.js +77 -0
- package/dist/lib/project-wiring.d.ts +8 -0
- package/dist/lib/project-wiring.js +74 -2
- package/dist/lib/validators/structure-validator.js +0 -1
- package/dist/packages/llm/src/index.js +12 -2
- package/dist/scripts/llm-fit.js +23 -1
- package/docs/llm-fit-loop.md +16 -0
- package/memory/90-decisions/0088-templates-validados.md +3 -0
- package/memory/90-decisions/0089-skills-do-projeto.md +51 -0
- package/memory/90-decisions/0090-adapters-de-agente-somente-leitura.md +47 -0
- package/package.json +1 -1
- package/specs/skills-do-projeto/plan.md +40 -0
- package/specs/skills-do-projeto/spec.md +63 -0
- package/specs/skills-do-projeto/tasks.md +27 -0
- package/templates/project/AGENTS.md +9 -0
- package/templates/project/agents/context-engineer.md +3 -0
- package/templates/project/agents/governance.md +3 -0
- package/templates/project/agents/marketing.md +3 -0
- package/templates/project/agents/orchestrator.md +3 -0
- package/templates/project/agents/product.md +3 -0
- package/templates/project/agents/sdd-architect.md +3 -0
- package/templates/project/skills/README.md +14 -0
- package/templates/project/skills/accessibility-review/SKILL.md +89 -0
- package/templates/project/skills/api-design/SKILL.md +77 -0
- package/templates/project/skills/architecture-decision-record/SKILL.md +92 -0
- package/templates/project/skills/backlog-slicing/SKILL.md +82 -0
- package/templates/project/skills/bounded-context-mapping/SKILL.md +88 -0
- package/templates/project/skills/ci-pipeline-review/SKILL.md +83 -0
- package/templates/project/skills/commit-message/SKILL.md +143 -0
- package/templates/project/skills/data-migrations/SKILL.md +88 -0
- package/templates/project/skills/dependency-upgrade/SKILL.md +75 -0
- package/templates/project/skills/docker-compose-review/SKILL.md +85 -0
- package/templates/project/skills/domain-modeling/SKILL.md +120 -0
- package/templates/project/skills/event-storming/SKILL.md +95 -0
- package/templates/project/skills/executive-writing/SKILL.md +99 -0
- package/templates/project/skills/frontend-architecture/SKILL.md +97 -0
- package/templates/project/skills/incident-postmortem/SKILL.md +93 -0
- package/templates/project/skills/lgpd-compliance/SKILL.md +108 -0
- package/templates/project/skills/llm-provider-routing/SKILL.md +18 -0
- package/templates/project/skills/observability/SKILL.md +93 -0
- package/templates/project/skills/product-evaluation/SKILL.md +130 -0
- package/templates/project/skills/prompt-spec/SKILL.md +83 -0
- package/templates/project/skills/pull-request/SKILL.md +101 -0
- package/templates/project/skills/query-performance/SKILL.md +83 -0
- package/templates/project/skills/release-checklist/SKILL.md +106 -0
- package/templates/project/skills/release-notes/SKILL.md +87 -0
- package/templates/project/skills/requirements-elicitation/SKILL.md +127 -0
- package/templates/project/skills/requirements-gathering/SKILL.md +134 -0
- package/templates/project/skills/technical-spike/SKILL.md +101 -0
- package/templates/project/skills/testing/SKILL.md +109 -0
- package/templates/project/skills/threat-modeling/SKILL.md +87 -0
- package/templates/project/skills/ts-async-patterns/SKILL.md +101 -0
- package/templates/project/skills/ts-code-review/SKILL.md +121 -0
- package/templates/project/skills/ts-module-layout/SKILL.md +104 -0
- package/templates/project/skills/ts-testing/SKILL.md +89 -0
- package/templates/project/skills/web-performance/SKILL.md +72 -0
- package/boilerplates/02-saas-starter/.env.example +0 -25
- package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +0 -190
- package/boilerplates/02-saas-starter/INFO.md +0 -252
- package/boilerplates/02-saas-starter/QUICK_START.md +0 -194
- package/boilerplates/02-saas-starter/START-HERE.md +0 -259
- package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +0 -3
- package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +0 -6
- package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +0 -23
- package/boilerplates/02-saas-starter/backend/src/config/database.ts +0 -26
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +0 -46
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +0 -25
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +0 -145
- package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +0 -30
- package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +0 -24
- package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +0 -19
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +0 -42
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +0 -67
- package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +0 -52
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +0 -36
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +0 -16
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +0 -34
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +0 -40
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +0 -36
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +0 -91
- package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +0 -42
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +0 -14
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +0 -48
- package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +0 -227
- package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +0 -141
- package/boilerplates/02-saas-starter/memory/00-global/index.md +0 -133
- package/boilerplates/02-saas-starter/memory/00-global/mission.md +0 -45
- package/boilerplates/02-saas-starter/memory/00-global/patterns.md +0 -223
- package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +0 -240
- package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +0 -239
- package/boilerplates/02-saas-starter/memory/10-product/personas.md +0 -195
- package/boilerplates/02-saas-starter/memory/10-product/vision.md +0 -63
- package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +0 -232
- package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +0 -186
- package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +0 -85
- package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +0 -262
- package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +0 -176
- package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +0 -100
- package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +0 -81
- package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +0 -97
- package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +0 -57
- package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +0 -90
- package/boilerplates/02-saas-starter/memory/60-runs/index.md +0 -54
- package/boilerplates/02-saas-starter/memory/70-summaries/global.md +0 -50
- package/boilerplates/02-saas-starter/memory/80-data/schema.md +0 -185
- package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +0 -75
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: pull-request
|
|
3
|
+
description: Use quando abrir um pull request ou escrever a descrição dele: lê os commits e o diff do branch, escreve um título e um corpo com o porquê, o quê, como testar, riscos e rollback, e cria o PR só depois da aprovação.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Pull Request
|
|
7
|
+
|
|
8
|
+
Um pull request pede a um revisor que confie numa mudança. A descrição dá a ele o que o diff não consegue: por que a mudança existe, onde olhar, como verificá-la e o que acontece se der errado.
|
|
9
|
+
|
|
10
|
+
A saída padrão é um **título e um corpo propostos**. Crie o PR só depois que o usuário aprovar.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- Entradas: os commits do branch (escritos com `commit-message`), os resultados de teste de `testing`, os IDs de requisito (`RF-NN`, `RN-NN`) de `requirements-gathering`, ADRs quando houve uma decisão.
|
|
15
|
+
- Idioma: o usado nos PRs ou commits recentes. Inglês quando não houver histórico.
|
|
16
|
+
- As regras do repositório prevalecem: `.github/pull_request_template.md`, `CONTRIBUTING.md`. Se houver um template, preencha-o em vez de usar o formato abaixo.
|
|
17
|
+
|
|
18
|
+
## Reúna o contexto
|
|
19
|
+
|
|
20
|
+
Somente leitura, antes de redigir:
|
|
21
|
+
|
|
22
|
+
1. `git branch --show-current` e o branch base (normalmente `main`).
|
|
23
|
+
2. `git log <base>..HEAD --oneline`: a história do branch.
|
|
24
|
+
3. `git diff <base>...HEAD --stat`, e depois o diff dos arquivos que carregam a mudança.
|
|
25
|
+
4. `git status`: trabalho sem commit significa que o branch não está pronto. Diga isso; não abra o PR.
|
|
26
|
+
5. Se o branch já foi enviado (`git rev-parse --abbrev-ref @{u}`).
|
|
27
|
+
6. PRs mesclados recentes (`gh pr list --state merged -L 5`), para o tom e o estilo de título.
|
|
28
|
+
|
|
29
|
+
## Título
|
|
30
|
+
|
|
31
|
+
- No formato Conventional Commits, como o assunto de um commit: `feat(reports): add CSV export`.
|
|
32
|
+
- Um branch com um commit só reutiliza o assunto desse commit.
|
|
33
|
+
- Um branch com vários commits recebe um assunto para o resultado inteiro, não para o último commit.
|
|
34
|
+
- `!` quando qualquer commit do branch for incompatível.
|
|
35
|
+
|
|
36
|
+
## Regras do corpo
|
|
37
|
+
|
|
38
|
+
- **Porquê primeiro.** Uma ou duas frases sobre o problema. Ligue o ticket e os IDs de requisito.
|
|
39
|
+
- **O quê**, no nível que o revisor precisa: a abordagem e os arquivos que a carregam. Não uma lista arquivo por arquivo.
|
|
40
|
+
- **Como testar**: passos que o revisor consegue rodar, com comandos e resultados esperados. Declare o que foi rodado e o resultado. Nunca afirme que os testes passaram sem rodá-los.
|
|
41
|
+
- **Riscos e rollback**: o que pode quebrar, quem é afetado, como desfazer (revert, feature flag, rollback de migração de `data-migrations`).
|
|
42
|
+
- **Mudanças incompatíveis**: o que quebra e como os consumidores migram.
|
|
43
|
+
- **Capturas de tela ou gravações** quando a interface muda.
|
|
44
|
+
- **Orientação de revisão** para PRs grandes: por onde começar, o que pode ser lido por cima.
|
|
45
|
+
- Mantenha fácil de varrer com os olhos: títulos e marcadores curtos. Apague as seções vazias.
|
|
46
|
+
|
|
47
|
+
## Tamanho
|
|
48
|
+
|
|
49
|
+
Um PR que não pode ser revisado de uma vez (cerca de 400 linhas alteradas de código real) deve ser dividido. Proponha a divisão por grupos de commits ou por fatia vertical de `backlog-slicing`. Arquivos gerados, lockfiles e movimentações não contam, mas mencione-os.
|
|
50
|
+
|
|
51
|
+
## Formato
|
|
52
|
+
|
|
53
|
+
```markdown
|
|
54
|
+
## Por quê
|
|
55
|
+
<problema, em uma ou duas frases>. Refs: <ticket>, <RF-NN>
|
|
56
|
+
|
|
57
|
+
## O quê
|
|
58
|
+
- <abordagem e mudança principal>
|
|
59
|
+
- <mudança secundária>
|
|
60
|
+
|
|
61
|
+
## Como testar
|
|
62
|
+
1. <comando ou passo> → <resultado esperado>
|
|
63
|
+
|
|
64
|
+
Rodado: <comando de teste> — <resultado>
|
|
65
|
+
|
|
66
|
+
## Riscos e rollback
|
|
67
|
+
- Risco: <o que pode quebrar, para quem>
|
|
68
|
+
- Rollback: <revert / flag / passo de migração>
|
|
69
|
+
|
|
70
|
+
## Mudanças incompatíveis
|
|
71
|
+
<o que quebra e como migrar>
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Fluxo
|
|
75
|
+
|
|
76
|
+
1. Reúna o contexto.
|
|
77
|
+
2. Redija título e corpo; sinalize uma divisão se o PR for grande demais.
|
|
78
|
+
3. Mostre-os ao usuário.
|
|
79
|
+
4. Com a aprovação: envie o branch se necessário (`git push -u origin <branch>`) e crie o PR com um heredoc:
|
|
80
|
+
```sh
|
|
81
|
+
gh pr create --base <base> --title "<título>" --body-file - <<'EOF'
|
|
82
|
+
<corpo>
|
|
83
|
+
EOF
|
|
84
|
+
```
|
|
85
|
+
5. Mostre a URL do PR.
|
|
86
|
+
|
|
87
|
+
Crie como rascunho (`--draft`) quando o usuário disser que o trabalho não terminou. Nunca faça merge, force-push ou peça revisores, a menos que peçam.
|
|
88
|
+
|
|
89
|
+
## Próximo
|
|
90
|
+
|
|
91
|
+
Depois do merge, `release-notes` transforma os commits mesclados numa versão e num changelog.
|
|
92
|
+
|
|
93
|
+
## Evite
|
|
94
|
+
|
|
95
|
+
- Repetir a lista de commits como corpo.
|
|
96
|
+
- "Veja o código" ou uma descrição vazia.
|
|
97
|
+
- Afirmar que os testes passaram sem rodá-los.
|
|
98
|
+
- Esconder mudanças arriscadas num PR grande e não relacionado.
|
|
99
|
+
- Inventar IDs de ticket ou capturas de tela.
|
|
100
|
+
- Abrir o PR, enviar o branch ou pedir revisores sem aprovação.
|
|
101
|
+
- Ignorar o template de PR do repositório.
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: query-performance
|
|
3
|
+
description: Use quando uma consulta SQL está lenta ou um banco está sob carga: lê planos de EXPLAIN ANALYZE, encontra a causa (índices faltando, estimativas ruins, predicados não sargáveis, N+1, paginação por offset) e propõe índices e reescritas ordenados, com verificação.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Desempenho de Consultas
|
|
7
|
+
|
|
8
|
+
Uma consulta lenta é um problema de plano até prova em contrário. O plano mostra o que o banco de fato fez. Adivinhar índices sem lê-lo aumenta o custo de escrita e muitas vezes não ajuda.
|
|
9
|
+
|
|
10
|
+
A saída padrão é um **diagnóstico e correções ordenadas**. Crie índices ou altere código só quando o usuário pedir, e crie índices via `data-migrations`.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- O dialeto padrão é PostgreSQL. Nomeie o dialeto quando o conselho for específico dele.
|
|
15
|
+
- Entradas: a consulta (com valores reais dos parâmetros), o plano, o esquema e os índices (de `data-migrations`), o tamanho das tabelas e com que frequência a consulta roda (de `observability` ou `pg_stat_statements`).
|
|
16
|
+
- Nunca rode `EXPLAIN ANALYZE` em escritas (`INSERT`/`UPDATE`/`DELETE`) em produção. Ele as executa. Use uma transação com `ROLLBACK`, ou uma cópia.
|
|
17
|
+
|
|
18
|
+
## Reúna
|
|
19
|
+
|
|
20
|
+
1. A consulta com parâmetros realistas, não placeholders.
|
|
21
|
+
2. `EXPLAIN (ANALYZE, BUFFERS, VERBOSE)` sobre dados do tamanho da produção. Um plano de um banco de desenvolvimento com 100 linhas não diz nada.
|
|
22
|
+
3. `\d+ <tabela>` para colunas e índices; quantidade de linhas.
|
|
23
|
+
4. Frequência × duração do `pg_stat_statements`: uma consulta de 5 ms rodando 10.000 vezes por minuto importa mais do que um relatório mensal de 2 s.
|
|
24
|
+
|
|
25
|
+
## Leia o plano
|
|
26
|
+
|
|
27
|
+
Leia de baixo para cima; encontre o nó onde vai a maior parte do tempo (`actual time` × `loops`).
|
|
28
|
+
|
|
29
|
+
| Sinal | Causa provável |
|
|
30
|
+
|---|---|
|
|
31
|
+
| Estimativa `rows=` diferente de `actual rows` em 10× ou mais | Estatísticas desatualizadas ou insuficientes; colunas correlacionadas |
|
|
32
|
+
| `Seq Scan` com filtro seletivo numa tabela grande | Índice faltando, ou um predicado que o índice não consegue usar |
|
|
33
|
+
| `Rows Removed by Filter` grande | Índice nas colunas erradas, ou nenhum índice |
|
|
34
|
+
| `Nested Loop` com muitos `loops` sobre um lado interno grande | Estimativa ruim; índice faltando na chave do join |
|
|
35
|
+
| `Sort` / `Hash` com `external merge` ou `Disk:` | `work_mem` pequeno demais, ou ordenando mais linhas que o necessário |
|
|
36
|
+
| `Buffers: read` alto vs. `hit` | Cache frio ou dados demais tocados |
|
|
37
|
+
| `Index Scan` seguido de muitas leituras do heap | Um índice de cobertura (`INCLUDE`) permitiria um `Index Only Scan` |
|
|
38
|
+
| Muito tempo em `Limit` sobre `Offset` | Paginação por offset varrendo as linhas puladas |
|
|
39
|
+
|
|
40
|
+
## Causas comuns e correções
|
|
41
|
+
|
|
42
|
+
- **Índice faltando**: índice composto com as colunas de igualdade primeiro, depois as de intervalo/ordenação. Índice parcial (`WHERE status = 'open'`) quando as consultas miram um subconjunto pequeno.
|
|
43
|
+
- **Predicado não sargável**: funções ou casts sobre a coluna (`WHERE lower(email) = …`, `WHERE created_at::date = …`), curinga no início `LIKE '%x'`, divergência implícita de tipo. Reescreva, ou use um índice de expressão.
|
|
44
|
+
- **Estatísticas desatualizadas**: `ANALYZE <tabela>`; aumente o alvo de estatísticas em colunas assimétricas; estatísticas estendidas para colunas correlacionadas.
|
|
45
|
+
- **N+1**: uma consulta por linha vinda do código da aplicação. Agrupe com `IN`/`ANY($1)` ou um join. Aparece nos traces, não em planos isolados.
|
|
46
|
+
- **Paginação por offset**: troque por keyset (`WHERE (created_at, id) < ($1, $2) ORDER BY created_at DESC, id DESC LIMIT n`), alinhado à paginação por cursor de `api-design`.
|
|
47
|
+
- **Dados demais**: `SELECT *` em linhas largas, `LIMIT` faltando, agregações sobre o histórico inteiro. Selecione as colunas necessárias; pré-agregue se for um relatório.
|
|
48
|
+
- **`OR` entre colunas** impedindo o uso do índice: reescreva como `UNION ALL`.
|
|
49
|
+
- **Subconsultas correlacionadas**: reescreva como joins ou `LATERAL`.
|
|
50
|
+
|
|
51
|
+
## Verifique
|
|
52
|
+
|
|
53
|
+
Rode de novo o mesmo `EXPLAIN (ANALYZE, BUFFERS)` depois da mudança, sobre os mesmos dados, e compare tempo e buffers. Verifique o custo de escrita de qualquer índice novo em tabelas quentes. Remova os índices que a mudança deixou sem uso (`pg_stat_user_indexes.idx_scan = 0` num período representativo).
|
|
54
|
+
|
|
55
|
+
## Formato
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
## Consulta
|
|
59
|
+
<SQL, parâmetros, frequência, duração atual>
|
|
60
|
+
|
|
61
|
+
## Diagnóstico
|
|
62
|
+
| Nó do plano | Observação (estimado vs. real, tempo, buffers) | Causa |
|
|
63
|
+
|
|
64
|
+
## Correções (ordenadas por efeito esperado / custo)
|
|
65
|
+
| # | Correção | Efeito esperado | Custo (sobrecarga de escrita, migração, mudança de código) |
|
|
66
|
+
|
|
67
|
+
## Verificação
|
|
68
|
+
<plano antes → depois; números>
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Próximo
|
|
72
|
+
|
|
73
|
+
- `data-migrations` para criar índices (`CONCURRENTLY`) ou mudar o esquema.
|
|
74
|
+
- `observability`: SLI de latência do endpoint afetado, para confirmar o efeito em produção.
|
|
75
|
+
|
|
76
|
+
## Evite
|
|
77
|
+
|
|
78
|
+
- Adicionar índices sem ler o plano.
|
|
79
|
+
- Planos de dados pequenos ou não representativos.
|
|
80
|
+
- `EXPLAIN ANALYZE` sobre escritas em produção.
|
|
81
|
+
- Um índice por coluna em vez de um índice composto para a consulta.
|
|
82
|
+
- Hints de consulta ou ajustes do planejador como primeira correção.
|
|
83
|
+
- Afirmar uma melhora sem números de antes e depois.
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: release-checklist
|
|
3
|
+
description: Use antes de implantar uma release em produção: verifica migrações, feature flags, plano de rollback, observabilidade, comunicação e momento, e dá uma recomendação de go/no-go com os bloqueadores.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Checklist de Release
|
|
7
|
+
|
|
8
|
+
Um deploy é seguro quando desfazê-lo é fácil e você vai saber rápido se precisa. Este checklist confirma as duas coisas antes de a mudança chegar aos usuários, para que os problemas apareçam numa revisão e não num incidente.
|
|
9
|
+
|
|
10
|
+
A saída padrão é um **checklist preenchido com uma recomendação de go/no-go**. A decisão é do usuário; implantar nunca faz parte desta skill.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- Entradas: a release de `release-notes` (versão, mudanças incompatíveis); o plano de migração de `data-migrations`; SLOs e alertas de `observability`; riscos em aberto de `threat-modeling`; o status do CI de `ci-pipeline-review`.
|
|
15
|
+
- Cada item é ✅ (feito, com evidência), ⚠ (risco aceito, com motivo e dono), ❌ (bloqueador) ou N/A (com motivo).
|
|
16
|
+
- Evidência é um link, a saída de um comando ou uma pessoa nomeada. "Deve estar tudo bem" não é evidência.
|
|
17
|
+
- Dimensione pela mudança: uma correção de texto precisa dos itens centrais; uma mudança de esquema ou uma API incompatível precisa de todos.
|
|
18
|
+
|
|
19
|
+
## Checklist
|
|
20
|
+
|
|
21
|
+
**Escopo**
|
|
22
|
+
- O que vai: versão, PRs e commits desde a última release. Nada sem revisão ou sem merge.
|
|
23
|
+
- Mudanças incompatíveis listadas, com os consumidores avisados.
|
|
24
|
+
|
|
25
|
+
**Build e testes**
|
|
26
|
+
- CI verde no commit ou artefato exato que será implantado.
|
|
27
|
+
- O artefato é o que foi testado (mesmo digest de imagem), não reconstruído.
|
|
28
|
+
- Staging (ou equivalente) rodou esta versão, com os smoke tests passando.
|
|
29
|
+
|
|
30
|
+
**Banco de dados**
|
|
31
|
+
- As migrações são retrocompatíveis com a versão que está rodando (só a fase de expansão; veja `data-migrations`).
|
|
32
|
+
- Risco de lock e de duração avaliado para tabelas grandes; `lock_timeout` definido.
|
|
33
|
+
- Preenchimentos rodam separados e são retomáveis.
|
|
34
|
+
- Passos de contração (remoções) **não** estão nesta release, a menos que o código antigo já tenha saído.
|
|
35
|
+
- Backup ou recuperação point-in-time confirmados recentes.
|
|
36
|
+
|
|
37
|
+
**Feature flags**
|
|
38
|
+
- Comportamento arriscado atrás de uma flag, desligada por padrão, com interruptor de emergência.
|
|
39
|
+
- Cada flag tem um dono e uma data de remoção.
|
|
40
|
+
- Os estados das flags para este rollout estão escritos (quem vê o quê, quando).
|
|
41
|
+
|
|
42
|
+
**Rollback**
|
|
43
|
+
- Como reverter: artefato anterior, flag desligada ou rollback da migração. Passos escritos e testados pelo menos uma vez.
|
|
44
|
+
- Quem decide, e o gatilho (por exemplo, taxa de erro acima do alerta de consumo do SLO por 10 minutos).
|
|
45
|
+
- O que não pode ser revertido (dados gravados num formato novo, e-mails enviados, chamadas externas) está nomeado.
|
|
46
|
+
|
|
47
|
+
**Observabilidade**
|
|
48
|
+
- Dashboards e alertas para os caminhos alterados existem e funcionam (veja `observability`).
|
|
49
|
+
- Uma janela de observação depois do deploy, com uma pessoa nomeada acompanhando.
|
|
50
|
+
- Sinais de sucesso conhecidos: como "funcionando" aparece nas métricas.
|
|
51
|
+
|
|
52
|
+
**Segurança e compliance**
|
|
53
|
+
- Os itens de `threat-modeling` em aberto para esta mudança estão mitigados ou aceitos com dono.
|
|
54
|
+
- Tratamento novo de dados pessoais revisado sob `lgpd-compliance`.
|
|
55
|
+
- Segredos e configuração presentes no ambiente de destino.
|
|
56
|
+
|
|
57
|
+
**Comunicação**
|
|
58
|
+
- Release notes prontas; suporte avisado das mudanças visíveis.
|
|
59
|
+
- Usuários ou consumidores da API avisados de mudanças incompatíveis e de janelas de manutenção.
|
|
60
|
+
- O time sabe o horário do deploy e o canal para reportar problemas.
|
|
61
|
+
|
|
62
|
+
**Momento**
|
|
63
|
+
- Fora de um congelamento ou de um pico de tráfego; não no fim do último dia útil antes de as pessoas ficarem indisponíveis.
|
|
64
|
+
- As pessoas que conseguem reverter estão disponíveis durante a janela de observação.
|
|
65
|
+
|
|
66
|
+
**Depois do deploy**
|
|
67
|
+
- Smoke tests em produção.
|
|
68
|
+
- Ponto de decisão no fim da janela de observação: manter, reverter ou corrigir para frente.
|
|
69
|
+
|
|
70
|
+
## Recomendação
|
|
71
|
+
|
|
72
|
+
- **Go**: nenhum ❌; todo ⚠ tem dono.
|
|
73
|
+
- **Go com condições**: nenhum ❌, mas itens ⚠ exigem um passo antes (por exemplo, "implantar com a flag desligada").
|
|
74
|
+
- **No-go**: qualquer ❌. Liste o que libera cada um.
|
|
75
|
+
|
|
76
|
+
## Formato
|
|
77
|
+
|
|
78
|
+
```
|
|
79
|
+
# Release <versão> — <data/hora UTC>
|
|
80
|
+
|
|
81
|
+
| Área | Item | Status | Evidência / nota |
|
|
82
|
+
|---|---|---|---|
|
|
83
|
+
|
|
84
|
+
## Bloqueadores
|
|
85
|
+
## Riscos aceitos (dono)
|
|
86
|
+
## Plano de rollback
|
|
87
|
+
## Recomendação: <Go | Go com condições | No-go> — <motivo em uma linha>
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## Próximo
|
|
91
|
+
|
|
92
|
+
- `executive-writing` para uma nota de go/no-go às partes interessadas.
|
|
93
|
+
- `incident-postmortem` se o rollout der errado.
|
|
94
|
+
|
|
95
|
+
## No Forja
|
|
96
|
+
|
|
97
|
+
No Forja, inclua na verificação os gates do projeto: `forja project:check`, `forja spec:check`, `forja tools:doctor` e `forja project:wire --check`. Riscos aceitos com dono podem virar ADR.
|
|
98
|
+
|
|
99
|
+
## Evite
|
|
100
|
+
|
|
101
|
+
- Marcar itens sem evidência.
|
|
102
|
+
- Publicar as migrações e o código que precisa delas como um par incompatível.
|
|
103
|
+
- Flags sem interruptor de emergência ou sem data de remoção.
|
|
104
|
+
- Um plano de rollback nunca testado.
|
|
105
|
+
- Implantar sem ninguém acompanhando.
|
|
106
|
+
- Implantar como parte desta skill.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: release-notes
|
|
3
|
+
description: Use quando gerar uma release ou escrever um changelog: coleta os commits desde a última tag, decide o incremento de versão semântica a partir do Conventional Commits, escreve as notas de release para os usuários e cria a tag só depois da aprovação.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Notas de Release
|
|
7
|
+
|
|
8
|
+
As notas de release dizem a quem usa o software o que mudou **para essas pessoas**: o que dá para fazer agora, o que foi corrigido e o que elas precisam mudar. Não são um log de commits.
|
|
9
|
+
|
|
10
|
+
A saída padrão é uma **versão e uma seção de changelog propostas**. Edite o changelog, crie a tag ou publique uma release só depois que o usuário aprovar.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- Entradas: commits escritos com `commit-message` (Conventional Commits), PRs mesclados de `pull-request`.
|
|
15
|
+
- Versionamento: [Semantic Versioning](https://semver.org/). Changelog: [Keep a Changelog](https://keepachangelog.com/).
|
|
16
|
+
- Idioma: o usado no `CHANGELOG.md` existente. Inglês quando não houver um.
|
|
17
|
+
- As regras do repositório prevalecem: uma ferramenta de release existente (`release-please`, `semantic-release`, `changesets`) é dona do processo. Nesse caso, só redija o texto ou ajude a configurar a ferramenta.
|
|
18
|
+
|
|
19
|
+
## Reúna o contexto
|
|
20
|
+
|
|
21
|
+
1. `git describe --tags --abbrev=0`: a última tag de release. Nenhuma significa a primeira release.
|
|
22
|
+
2. `git log <ultima-tag>..HEAD --format='%h %s%n%b'`: assuntos **e** corpos, para pegar os rodapés `BREAKING CHANGE:`.
|
|
23
|
+
3. O `CHANGELOG.md`, se existir, para o formato e o tom.
|
|
24
|
+
4. PRs mesclados desde a tag (`gh pr list --state merged --search "merged:>=<data da tag>"`), para o contexto voltado ao usuário que os commits não têm.
|
|
25
|
+
|
|
26
|
+
## Incremento de versão
|
|
27
|
+
|
|
28
|
+
| Os commits desde a última tag contêm | Incremento |
|
|
29
|
+
|---|---|
|
|
30
|
+
| `!` ou um rodapé `BREAKING CHANGE:` | major |
|
|
31
|
+
| `feat` | minor |
|
|
32
|
+
| só `fix`, `perf` | patch |
|
|
33
|
+
| só `docs`, `test`, `ci`, `chore`, `build`, `style`, `refactor` | nenhuma release necessária; diga isso |
|
|
34
|
+
|
|
35
|
+
- Antes da `1.0.0`, uma mudança incompatível incrementa a versão minor e uma funcionalidade incrementa a patch. Pergunte se o projeto está pronto para a `1.0.0` em vez de decidir sozinho.
|
|
36
|
+
- Commits que não seguem Conventional Commits: leia o diff, classifique-os e liste-os como incertos.
|
|
37
|
+
- Pré-releases (`-rc.1`, `-beta.1`) só a pedido.
|
|
38
|
+
|
|
39
|
+
## Escrevendo as notas
|
|
40
|
+
|
|
41
|
+
- **Mudanças incompatíveis primeiro**, cada uma com o passo de migração.
|
|
42
|
+
- Agrupe o resto nas seções do Keep a Changelog: Added (`feat`), Fixed (`fix`), Changed (`perf`, mudanças de comportamento), Deprecated, Removed, Security. Use os nomes de seção em português quando o changelog do projeto já os usa (Adicionado, Corrigido, Alterado…).
|
|
43
|
+
- Reescreva cada entrada para os usuários: o efeito, não a implementação. `feat(reports): add CSV export` → "Os relatórios podem ser exportados em CSV."
|
|
44
|
+
- Junte vários commits numa entrada quando eles entregam uma mudança só.
|
|
45
|
+
- Descarte `ci`, `test`, `chore`, `build`, `style` e `refactor` puro, a menos que os usuários os percebam (por exemplo, uma versão mínima de runtime mais alta).
|
|
46
|
+
- Ligue o PR ou o ticket de cada entrada quando houver.
|
|
47
|
+
- Correções de segurança: declare o impacto e as versões afetadas. Não inclua detalhes de exploração antes de os usuários poderem atualizar.
|
|
48
|
+
|
|
49
|
+
## Formato
|
|
50
|
+
|
|
51
|
+
```markdown
|
|
52
|
+
## [<versão>] - <AAAA-MM-DD>
|
|
53
|
+
|
|
54
|
+
### ⚠ Mudanças incompatíveis
|
|
55
|
+
- <o que mudou>. Migração: <o que fazer>.
|
|
56
|
+
|
|
57
|
+
### Added
|
|
58
|
+
- <efeito visível ao usuário> (#<PR>)
|
|
59
|
+
|
|
60
|
+
### Fixed
|
|
61
|
+
- <o que estava quebrado e agora funciona> (#<PR>)
|
|
62
|
+
|
|
63
|
+
### Changed
|
|
64
|
+
- <mudança de comportamento ou de desempenho>
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
A seção nova vai no topo do `CHANGELOG.md`, abaixo de `## [Unreleased]` se esse título existir.
|
|
68
|
+
|
|
69
|
+
## Fluxo
|
|
70
|
+
|
|
71
|
+
1. Reúna o contexto.
|
|
72
|
+
2. Proponha a versão com os commits que a justificam, mais as notas.
|
|
73
|
+
3. Com a aprovação: atualize o `CHANGELOG.md` e os arquivos de versão que o projeto usa (`package.json`, `pyproject.toml` etc.), e faça o commit com `commit-message` (`chore(release): <versão>`).
|
|
74
|
+
4. Só se pedirem: `git tag -a v<versão> -m "<versão>"`, envie a tag, `gh release create v<versão> --notes-file -`.
|
|
75
|
+
|
|
76
|
+
## No Forja
|
|
77
|
+
|
|
78
|
+
No Forja, a entrada de cada versão no `CHANGELOG.md` abre com a subseção `### O que melhorou` (o diff de produto em relação à versão anterior, em linguagem de usuário) e só depois as seções técnicas. Esse bloco é reaproveitado como nota da release no GitHub, e o README é reconciliado na mesma entrega.
|
|
79
|
+
|
|
80
|
+
## Evite
|
|
81
|
+
|
|
82
|
+
- Colar o log de commits cru como notas de release.
|
|
83
|
+
- Detalhes de implementação com os quais os usuários não podem fazer nada.
|
|
84
|
+
- Esconder uma mudança incompatível dentro de "Changed".
|
|
85
|
+
- Incrementar a major numa mudança compatível, ou a patch numa funcionalidade nova.
|
|
86
|
+
- Criar tag, enviar ou publicar sem aprovação.
|
|
87
|
+
- Brigar com uma ferramenta de release existente usando passos manuais.
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: requirements-elicitation
|
|
3
|
+
description: Use quando o conhecimento ainda precisa ser extraído das partes interessadas: prepara roteiros de entrevista, conduz rodadas de perguntas com o usuário como especialista do domínio e registra achados brutos com fonte, conflitos e lacunas.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Elicitação de Requisitos
|
|
7
|
+
|
|
8
|
+
Extrai o que as partes interessadas sabem, inclusive o que elas não percebem que sabem. O produto são **achados brutos, com fonte**, não um documento de requisitos. Estruturá-los é trabalho da skill `requirements-gathering`.
|
|
9
|
+
|
|
10
|
+
A elicitação trata do negócio, nunca da solução. Telas, tabelas e tecnologias vêm depois.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- Termos em pt-BR seguidos do en-US: Parte Interessada (Stakeholder), Ator (Actor), Conhecimento Tácito (Tacit Knowledge), Regra de Negócio (Business Rule), Exceção (Exception), Contorno (Workaround), Linguagem Ubíqua (Ubiquitous Language).
|
|
15
|
+
- Registre as próprias palavras das partes interessadas para termos do domínio. Não as traduza para vocabulário técnico.
|
|
16
|
+
- Todo achado traz sua fonte e sua natureza: **declarado** (alguém disse), **observado** (visto num documento, planilha, formulário ou sistema legado), **inferido** (sua interpretação, pendente de confirmação).
|
|
17
|
+
|
|
18
|
+
## Princípio central
|
|
19
|
+
|
|
20
|
+
As pessoas descrevem o fluxo normal e esquecem as exceções, porque é nas exceções que elas contornam o sistema sem pensar. O valor da elicitação está nas exceções, nos contornos e no "depende". Casos de borda também são requisitos: um retrato só do caminho feliz é incompleto por definição.
|
|
21
|
+
|
|
22
|
+
## Modos
|
|
23
|
+
|
|
24
|
+
1. **Preparar uma sessão**: o usuário vai conversar com as partes interessadas. Produza o mapa de partes interessadas e um roteiro de entrevista.
|
|
25
|
+
2. **Elicitar diretamente**: o usuário é o especialista do domínio. Faça perguntas em rodadas e registre os achados.
|
|
26
|
+
|
|
27
|
+
Quando o modo não estiver claro, pergunte qual é.
|
|
28
|
+
|
|
29
|
+
## Processo
|
|
30
|
+
|
|
31
|
+
### 1. Mapear as partes interessadas
|
|
32
|
+
Quem usa, quem decide, quem paga, quem é afetado, quem audita, quem opera o processo atual. Para cada uma: o que sabe, o que quer, o que teme. Partes interessadas ausentes são um risco: nomeie-as.
|
|
33
|
+
|
|
34
|
+
### 2. Escolher as técnicas
|
|
35
|
+
- **Entrevista**: padrão para entender objetivos e regras.
|
|
36
|
+
- **Observação (shadowing)**: quando o processo é manual ou habitual; as pessoas fazem mais do que descrevem.
|
|
37
|
+
- **Análise de artefatos**: formulários, planilhas, relatórios, telas e bancos legados. Cada coluna de uma planilha mantida à mão é um requisito que ninguém escreveu.
|
|
38
|
+
- **Percurso de cenário**: percorra um caso real e recente do início ao fim.
|
|
39
|
+
- **Exemplos concretos**: peça números e casos reais para fixar as regras ("me dê um exemplo em que o desconto não foi aplicado").
|
|
40
|
+
- **Workshop**: quando várias partes interessadas discordam ou são donas de partes diferentes do fluxo.
|
|
41
|
+
|
|
42
|
+
### 3. Perguntar em camadas
|
|
43
|
+
Faça rodadas de no máximo 5–7 perguntas. Cada rodada aprofunda o que a anterior abriu.
|
|
44
|
+
|
|
45
|
+
- **Contexto**: qual é o objetivo? O que acontece hoje sem o sistema? O que mais dói?
|
|
46
|
+
- **Fluxo**: o que inicia o processo? Quem faz o quê, em que ordem? O que o encerra?
|
|
47
|
+
- **Regras**: o que decide cada passo? Quem pode fazer, e quando não pode? Há limites, prazos, aprovações?
|
|
48
|
+
- **Exceções**: o que acontece quando dá errado, atrasa, é cancelado, é feito duas vezes? Qual foi o caso mais chato do mês passado? Que entradas são inválidas, ausentes ou inesperadas? Que restrições nunca podem ser quebradas?
|
|
49
|
+
- **Contornos**: o que vocês fazem fora do sistema hoje? Qual planilha, mensagem, anotação?
|
|
50
|
+
- **Dados**: que informação é necessária em cada passo? De onde vem? Quem corrige quando está errada?
|
|
51
|
+
- **Volume e frequência**: quantos por dia, nos horários de pico? Quantos usuários ao mesmo tempo?
|
|
52
|
+
- **Resultado**: como vocês sabem que funcionou? O que faria este projeto ser um fracasso?
|
|
53
|
+
|
|
54
|
+
### 4. Perguntar bem
|
|
55
|
+
- Perguntas abertas primeiro; fechadas só para confirmar.
|
|
56
|
+
- Uma pergunta por vez; nada de perguntas compostas.
|
|
57
|
+
- Nada de perguntas indutoras ("você ia querer um dashboard, né?").
|
|
58
|
+
- Pergunte "por quê" até o objetivo aparecer por trás do pedido. Uma funcionalidade pedida muitas vezes é a solução para um problema não dito.
|
|
59
|
+
- Peça exemplos sempre que uma resposta tiver "normalmente", "depende", "às vezes" ou "sempre".
|
|
60
|
+
- Devolva o que entendeu, nas palavras deles, e peça que corrijam.
|
|
61
|
+
|
|
62
|
+
### 5. Registrar os achados
|
|
63
|
+
Capture fatos, não conclusões. Separe o que foi dito do que você acha que significa.
|
|
64
|
+
|
|
65
|
+
### 6. Revelar conflitos e lacunas
|
|
66
|
+
Partes interessadas descrevendo a mesma coisa de formas diferentes é um achado, não ruído. Registre as duas versões e quem disse cada uma. Nunca resolva um conflito escolhendo uma por conta própria.
|
|
67
|
+
|
|
68
|
+
Perguntas são entregáveis. Cada lacuna vira uma pergunta precisa dirigida a uma pessoa nomeada; nunca a preencha com uma suposição.
|
|
69
|
+
|
|
70
|
+
## Formato do roteiro (modo preparar)
|
|
71
|
+
|
|
72
|
+
```
|
|
73
|
+
# Roteiro de elicitação: <tema>
|
|
74
|
+
|
|
75
|
+
## Partes interessadas
|
|
76
|
+
| Parte interessada | Papel | Sabe sobre | Quer | Preocupações |
|
|
77
|
+
|
|
78
|
+
## Objetivo da sessão
|
|
79
|
+
<O que precisa estar entendido ao final.>
|
|
80
|
+
|
|
81
|
+
## Perguntas
|
|
82
|
+
### Contexto
|
|
83
|
+
1. ...
|
|
84
|
+
### Fluxo
|
|
85
|
+
### Regras
|
|
86
|
+
### Exceções e contornos
|
|
87
|
+
### Dados
|
|
88
|
+
### Volume
|
|
89
|
+
### Resultado
|
|
90
|
+
|
|
91
|
+
## Artefatos a pedir
|
|
92
|
+
- <formulários, planilhas, relatórios, telas>
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## Formato dos achados
|
|
96
|
+
|
|
97
|
+
```
|
|
98
|
+
# Achados de elicitação: <tema>
|
|
99
|
+
|
|
100
|
+
## Achados
|
|
101
|
+
| # | Achado | Fonte | Natureza (declarado / observado / inferido) |
|
|
102
|
+
|
|
103
|
+
## Termos do domínio ouvidos
|
|
104
|
+
- <termo>: <significado nas palavras deles> — <quem usa>
|
|
105
|
+
|
|
106
|
+
## Exceções e contornos
|
|
107
|
+
- <caso> — <como é tratado hoje>
|
|
108
|
+
|
|
109
|
+
## Conflitos
|
|
110
|
+
- <tema>: <versão A, fonte> vs <versão B, fonte>
|
|
111
|
+
|
|
112
|
+
## Lacunas e próximas perguntas
|
|
113
|
+
- <o que ainda não se sabe> — perguntar a <quem>
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
## No Forja
|
|
117
|
+
|
|
118
|
+
No Forja, grave os achados em `memory/10-product/elicitacao-<tema>.md` e rode `forja sync:universal`, para que `requirements-gathering` e as outras IAs os encontrem com `forja query:universal "<tema>"`.
|
|
119
|
+
|
|
120
|
+
## Evite
|
|
121
|
+
|
|
122
|
+
- Falar de telas, tabelas, frameworks ou arquitetura.
|
|
123
|
+
- Aceitar uma solução pedida sem perguntar que problema ela resolve.
|
|
124
|
+
- Apresentar inferências como fatos declarados.
|
|
125
|
+
- Questionários com 30 perguntas de uma vez.
|
|
126
|
+
- Resolver conflitos entre partes interessadas por conta própria.
|
|
127
|
+
- Parar no caminho feliz.
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: requirements-gathering
|
|
3
|
+
description: Use quando transformar ideias, achados de elicitação ou documentos numa especificação de requisitos estruturada: escopo, atores, requisitos funcionais com critérios de aceite, regras de negócio, requisitos não funcionais mensuráveis, glossário e prioridades.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Levantamento de Requisitos
|
|
7
|
+
|
|
8
|
+
Consolida o que se sabe sobre um sistema numa especificação de requisitos curta e verificável. Entrada: uma ideia, achados de elicitação (skill `requirements-elicitation`), documentos existentes ou um sistema legado. Saída: a especificação que `domain-modeling` consome.
|
|
9
|
+
|
|
10
|
+
A especificação é uma lista de trabalho, não literatura. Detalhe só o que é incerto e está perto de ser construído; o longo prazo fica como direção.
|
|
11
|
+
|
|
12
|
+
A especificação está pronta quando um desenvolvedor consegue implementá-la sem adivinhar e um testador consegue verificá-la sem interpretar.
|
|
13
|
+
|
|
14
|
+
## Convenções
|
|
15
|
+
|
|
16
|
+
- Termos em pt-BR seguidos do en-US: Requisito Funcional (Functional Requirement), Regra de Negócio (Business Rule), Requisito Não Funcional (Non-Functional Requirement), Critério de Aceite (Acceptance Criterion), Ator (Actor), Parte Interessada (Stakeholder), Escopo (Scope), Linguagem Ubíqua (Ubiquitous Language).
|
|
17
|
+
- IDs: `RF-NN` (funcional), `RN-NN` (regra de negócio), `RNF-NN` (não funcional). Nunca reutilize um ID; marque itens removidos como removidos.
|
|
18
|
+
- Escreva no vocabulário das partes interessadas.
|
|
19
|
+
|
|
20
|
+
## Princípio central
|
|
21
|
+
|
|
22
|
+
Um requisito descreve **o quê** e **por quê**, nunca **como**. "A enfermeira precisa ver a dieta do paciente antes de fazer o pedido" é um requisito; "mostrar um selo de dieta na tela de pedido" é uma solução. Se a entrada trouxer uma solução, registre o problema por trás dela e mantenha a solução como nota.
|
|
23
|
+
|
|
24
|
+
Especifique exatamente o necessário: nem acima (soluções, decisões de design) nem abaixo (lacunas que quem implementa terá de preencher adivinhando).
|
|
25
|
+
|
|
26
|
+
## Qualidade de cada item
|
|
27
|
+
|
|
28
|
+
Todo requisito e regra precisa ser:
|
|
29
|
+
- **Atômico**: uma necessidade por item.
|
|
30
|
+
- **Verificável**: checável por um teste, uma métrica ou um comportamento observável; tem critérios de aceite ou um exemplo. Se não dá para checar, é um desejo, não um requisito: reescreva ou descarte.
|
|
31
|
+
- **Com fonte**: quem disse ou de onde veio.
|
|
32
|
+
- **Sem ambiguidade**: ambiguidade é defeito. Se dá para ler de duas formas, reescreva até sobrar uma leitura só. Nada de "rápido", "fácil", "flexível", "amigável", "etc.", "e/ou" sem definição.
|
|
33
|
+
- **Completo**: cobre os casos de borda, não só o caminho feliz.
|
|
34
|
+
|
|
35
|
+
Itens que falham nessas verificações vão para **Perguntas em aberto**, não para a lista.
|
|
36
|
+
|
|
37
|
+
## Processo
|
|
38
|
+
|
|
39
|
+
### 1. Objetivo e contexto
|
|
40
|
+
Um parágrafo: que problema é resolvido, para quem, e como o sucesso é reconhecido. Sem isso, nada pode ser priorizado.
|
|
41
|
+
|
|
42
|
+
### 2. Atores e partes interessadas
|
|
43
|
+
Quem interage com o sistema (atores) e quem é afetado por ele (partes interessadas). Inclua sistemas externos como atores.
|
|
44
|
+
|
|
45
|
+
### 3. Escopo
|
|
46
|
+
Escopo é um contrato. Listas explícitas de **dentro** e **fora**. O "fora" impede o crescimento silencioso do escopo e é tão importante quanto o "dentro".
|
|
47
|
+
|
|
48
|
+
### 4. Requisitos funcionais
|
|
49
|
+
Frases curtas: `<Ator> precisa conseguir <ação> para <objetivo>`. Para cada um, 1–4 critérios de aceite em Dado/Quando/Então ou exemplos concretos. Os critérios cobrem modos de falha, entradas inválidas ou inesperadas e limites, não só o caminho feliz; um requisito só com critérios de caminho feliz está incompleto.
|
|
50
|
+
|
|
51
|
+
### 5. Regras de negócio
|
|
52
|
+
Separadas dos requisitos funcionais: as regras que governam o domínio independentemente das telas (limites, elegibilidade, cálculos, prazos, estados, quem pode fazer o quê). Enuncie cada regra com um exemplo. Regras que variam ou podem mudar são marcadas como **variáveis**: virarão Políticas em `domain-modeling`.
|
|
53
|
+
|
|
54
|
+
### 6. Requisitos não funcionais
|
|
55
|
+
Só os mensuráveis, e só os que importam aqui: desempenho (latência num volume declarado), disponibilidade, segurança, auditabilidade, retenção de dados, compliance (dados pessoais → sinalize para `lgpd-compliance`), integrações, acessibilidade. Um requisito não funcional sem número ou condição verificável vai para perguntas em aberto.
|
|
56
|
+
|
|
57
|
+
### 7. Glossário
|
|
58
|
+
Termos do domínio com seu significado e o contexto em que se aplicam. É a semente da linguagem ubíqua. Quando um termo tem dois significados, registre os dois: isso sinaliza dois contextos delimitados.
|
|
59
|
+
|
|
60
|
+
### 8. Prioridade
|
|
61
|
+
MoSCoW por requisito funcional: **Must** (sem ele o sistema não tem razão de existir), **Should**, **Could**, **Won't (agora)**. Poucos Musts. Se tudo é Must, pergunte o que seria cortado se o prazo caísse pela metade.
|
|
62
|
+
|
|
63
|
+
### 9. Suposições e perguntas em aberto
|
|
64
|
+
O que foi suposto sem confirmação e o que ainda precisa ser perguntado, e a quem. Incógnitas são listadas, nunca preenchidas com palpites. Quando faltar informação-chave, uma lista precisa e direcionada de perguntas é o entregável; prefira-a a uma especificação construída sobre suposições.
|
|
65
|
+
|
|
66
|
+
### 10. Encaminhamento
|
|
67
|
+
Anote o que vai para onde: regras de negócio e glossário → `domain-modeling`; critérios de aceite → `testing` (mais a skill da linguagem, por exemplo `ts-testing`); dados pessoais → `lgpd-compliance`; incertezas técnicas → `technical-spike`.
|
|
68
|
+
|
|
69
|
+
## Formato de saída
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
# Requisitos: <sistema ou funcionalidade>
|
|
73
|
+
|
|
74
|
+
## Objetivo
|
|
75
|
+
<problema, para quem, critério de sucesso>
|
|
76
|
+
|
|
77
|
+
## Atores
|
|
78
|
+
| Ator | Descrição |
|
|
79
|
+
|
|
80
|
+
## Escopo
|
|
81
|
+
- Dentro: ...
|
|
82
|
+
- Fora: ...
|
|
83
|
+
|
|
84
|
+
## Requisitos funcionais
|
|
85
|
+
### RF-01 — <título curto> [Must]
|
|
86
|
+
<Ator> precisa conseguir <ação> para <objetivo>.
|
|
87
|
+
Fonte: <...>
|
|
88
|
+
Critérios de aceite:
|
|
89
|
+
- Dado ... Quando ... Então ...
|
|
90
|
+
|
|
91
|
+
## Regras de negócio
|
|
92
|
+
| ID | Regra | Exemplo | Variável? | Fonte |
|
|
93
|
+
|
|
94
|
+
## Requisitos não funcionais
|
|
95
|
+
| ID | Requisito | Medida / condição | Fonte |
|
|
96
|
+
|
|
97
|
+
## Glossário
|
|
98
|
+
| Termo | Significado | Contexto |
|
|
99
|
+
|
|
100
|
+
## Suposições e perguntas em aberto
|
|
101
|
+
- <item> — perguntar a <quem>
|
|
102
|
+
|
|
103
|
+
## Encaminhamento
|
|
104
|
+
- domain-modeling: RN-..., glossário
|
|
105
|
+
- testing: critérios de aceite de RF-...
|
|
106
|
+
- lgpd-compliance: <dados pessoais envolvidos>
|
|
107
|
+
- technical-spike: <incertezas>
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
## No Forja
|
|
111
|
+
|
|
112
|
+
No Forja, a especificação vive em `specs/<slug>/spec.md`, criada com `forja spec:new <slug>`. Mapeie as seções:
|
|
113
|
+
|
|
114
|
+
| Esta skill | spec.md do Forja |
|
|
115
|
+
|---|---|
|
|
116
|
+
| Objetivo | §1 Problema e §2 Proposta de valor |
|
|
117
|
+
| Requisitos funcionais (`RF-NN`) | §3 User stories |
|
|
118
|
+
| Critérios de aceite | §4 Critérios de aceite, como `AC-n` (cite o `RF-NN` de origem) |
|
|
119
|
+
| Escopo | §5 Escopo (Dentro / Fora) |
|
|
120
|
+
| Requisitos não funcionais | §6 NFRs / restrições |
|
|
121
|
+
| Riscos e suposições | §7 Riscos e mitigação |
|
|
122
|
+
|
|
123
|
+
Regras de negócio e glossário também vão para `memory/30-domains/<contexto>/`. Ao terminar a revisão: `forja spec:set-status <slug> spec approved`; depois `forja spec:check <slug>`.
|
|
124
|
+
|
|
125
|
+
## Evite
|
|
126
|
+
|
|
127
|
+
- Soluções escritas como requisitos (telas, tabelas, tecnologias).
|
|
128
|
+
- Documentos de casos de uso com dezenas de páginas.
|
|
129
|
+
- Detalhar o futuro distante.
|
|
130
|
+
- Requisitos não funcionais vagos ("o sistema precisa ser rápido").
|
|
131
|
+
- Manter desejos (afirmações não testáveis) como requisitos.
|
|
132
|
+
- Critérios de aceite só de caminho feliz.
|
|
133
|
+
- Regras de negócio escondidas dentro de requisitos funcionais.
|
|
134
|
+
- Preencher lacunas com regras inventadas.
|