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,97 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: frontend-architecture
|
|
3
|
+
description: Use quando organizar ou revisar um front-end React ou Next.js: estrutura por funcionalidade, fronteira entre Server e Client Components, estado do servidor vs. estado do cliente, busca de dados e cache, formulários com validação, fronteiras de erro e de carregamento, e um plano de mudança incremental.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Arquitetura de Front-end
|
|
7
|
+
|
|
8
|
+
Um front-end apodrece de dois jeitos: tudo vira estado global, ou cada tela reimplementa a busca de dados do seu jeito. A primeira pergunta para qualquer dado é **de quem ele é**: do servidor (vem de uma API e tem uma cópia mais nova em outro lugar) ou do cliente (existe só nesta tela, nesta sessão). Errar essa pergunta é a origem da maior parte dos bugs de sincronia.
|
|
9
|
+
|
|
10
|
+
A saída padrão é uma **avaliação e uma estrutura alvo com um plano de mudança**. Escreva componentes só quando o usuário pedir.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- Entradas: as histórias de `backlog-slicing`, o contrato de `api-design`, a estrutura atual e o `package.json`.
|
|
15
|
+
- O framework e as bibliotecas que o projeto já usa prevalecem (Next.js App Router ou Pages Router, Vite, React Query, Zustand, Redux, React Hook Form…). Proponha trocar só por um problema concreto.
|
|
16
|
+
- Os nomes de pastas e componentes seguem a linguagem ubíqua do domínio, não os nomes técnicos.
|
|
17
|
+
|
|
18
|
+
## Avalie primeiro
|
|
19
|
+
|
|
20
|
+
Somente leitura:
|
|
21
|
+
|
|
22
|
+
1. Rotas e páginas: quais existem, o que cada uma carrega e de onde.
|
|
23
|
+
2. Onde os dados são buscados: em componentes, em hooks, num cliente central. `fetch` espalhado em `useEffect` é um mau sinal.
|
|
24
|
+
3. Estado global: o que está nele. Dados do servidor copiados para uma store global são o problema mais comum.
|
|
25
|
+
4. Pastas genéricas (`components/` com tudo, `utils/`, `hooks/` sem dono).
|
|
26
|
+
5. Ciclos e acoplamento: `npx madge --circular --extensions ts,tsx src` (veja `ts-module-layout`).
|
|
27
|
+
6. No Next.js: quais componentes são `'use client'` e por quê. Um `'use client'` no topo de uma árvore grande puxa tudo para o bundle do cliente.
|
|
28
|
+
|
|
29
|
+
## Estrutura alvo
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
src/
|
|
33
|
+
app/ (ou pages/) # roteamento do framework; páginas finas que compõem funcionalidades
|
|
34
|
+
features/<contexto>/ # uma por contexto ou funcionalidade do domínio
|
|
35
|
+
components/ # componentes desta funcionalidade
|
|
36
|
+
api.ts # chamadas à API e chaves de cache desta funcionalidade
|
|
37
|
+
hooks.ts # hooks de dados e de comportamento
|
|
38
|
+
schema.ts # schemas de validação (formulários, respostas)
|
|
39
|
+
shared/ui/ # componentes de design system sem regra de negócio (Button, Dialog)
|
|
40
|
+
shared/lib/ # infraestrutura com comportamento real: cliente HTTP, i18n, telemetria
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Regras:
|
|
44
|
+
|
|
45
|
+
- **Organize por funcionalidade.** Uma página compõe funcionalidades; uma funcionalidade não importa os arquivos internos de outra (use o que ela exporta).
|
|
46
|
+
- **Estado do servidor fica num cache de servidor** (React Query/TanStack Query, SWR, ou o cache do framework), não numa store global. Cada consulta tem uma chave estável e uma política de invalidação depois das mutações.
|
|
47
|
+
- **Estado do cliente o mais local possível**: no componente, depois na URL (filtros, paginação, abas), depois num contexto, e só então numa store global.
|
|
48
|
+
- **Server Components por padrão no Next.js App Router**; `'use client'` só nas folhas que precisam de interatividade, de estado ou de APIs do navegador. Dados sensíveis e segredos nunca chegam a um Client Component.
|
|
49
|
+
- **Valide nas fronteiras**: respostas da API e entradas de formulário passam por um schema (`zod`, `valibot`), não por uma anotação de tipo.
|
|
50
|
+
- **Formulários**: uma biblioteca de formulário quando há validação ou muitos campos; mensagens de erro ligadas aos campos; o servidor revalida sempre.
|
|
51
|
+
- **Carregamento e erro são estados de primeira classe**: cada tela define o que mostra carregando, vazia, com erro e com sucesso. No Next.js, `loading.tsx` e `error.tsx`; no React, `Suspense` e fronteiras de erro.
|
|
52
|
+
- **Sem regra de negócio em componente de UI.** Cálculos e decisões vão para funções puras testáveis (`ts-testing`).
|
|
53
|
+
|
|
54
|
+
## Plano de mudança
|
|
55
|
+
|
|
56
|
+
Cada passo funciona sozinho e pode ser um commit:
|
|
57
|
+
|
|
58
|
+
1. Introduza o cache de servidor numa funcionalidade e migre a busca de dados dela.
|
|
59
|
+
2. Tire da store global os dados de servidor que agora estão no cache.
|
|
60
|
+
3. Mova os componentes da funcionalidade para `features/<contexto>/`.
|
|
61
|
+
4. Empurre `'use client'` para as folhas.
|
|
62
|
+
5. Repita por funcionalidade; apague as pastas genéricas que esvaziaram.
|
|
63
|
+
|
|
64
|
+
## Formato
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
## Estado atual
|
|
68
|
+
| Problema | Onde | Efeito |
|
|
69
|
+
|
|
70
|
+
## Estrutura alvo
|
|
71
|
+
<árvore>
|
|
72
|
+
|
|
73
|
+
## Dados
|
|
74
|
+
| Dado | Dono (servidor/cliente) | Onde vive | Invalidação |
|
|
75
|
+
|
|
76
|
+
## Plano de mudança
|
|
77
|
+
| # | Passo | Arquivos | Commit |
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## Próximo
|
|
81
|
+
|
|
82
|
+
- `accessibility-review` para cada tela nova ou alterada.
|
|
83
|
+
- `web-performance` quando houver metas de Core Web Vitals.
|
|
84
|
+
- `ts-code-review` revisa as mudanças; `ts-testing` para hooks e funções puras.
|
|
85
|
+
|
|
86
|
+
## No Forja
|
|
87
|
+
|
|
88
|
+
No Forja, a estrutura alvo e as regras de dados ficam em `memory/20-architecture/frontend.md`; trocas de biblioteca ou de estratégia de renderização viram ADR em `memory/90-decisions/`. Rode `forja sync:universal` depois de gravar.
|
|
89
|
+
|
|
90
|
+
## Evite
|
|
91
|
+
|
|
92
|
+
- Dados do servidor duplicados numa store global.
|
|
93
|
+
- `fetch` em `useEffect` espalhado pelos componentes.
|
|
94
|
+
- `'use client'` no topo de árvores grandes.
|
|
95
|
+
- Uma pasta `components/` com todos os componentes do app.
|
|
96
|
+
- Regra de negócio dentro de componentes.
|
|
97
|
+
- Reescrever o front-end inteiro de uma vez.
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: incident-postmortem
|
|
3
|
+
description: Use depois de um incidente em produção: escreve um postmortem sem culpados, com o impacto em números, uma linha do tempo em UTC, fatores contribuintes encontrados com os 5 Porquês, o que deu certo e ações com dono para prevenir, detectar e mitigar uma recorrência.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Postmortem de Incidente
|
|
7
|
+
|
|
8
|
+
Um postmortem transforma um incidente em aprendizado. Ele é **sem culpados**: as pessoas agiram de forma razoável com a informação e as ferramentas que tinham, então a pergunta é o que no sistema deixou a falha acontecer e se espalhar, não quem errou.
|
|
9
|
+
|
|
10
|
+
A saída padrão é um **documento de postmortem**. Ele é escrito a partir das evidências que o usuário fornece; o que não tem evidência é marcado como não confirmado.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- Entradas: alertas, dashboards e logs de `observability`; transcrições do chat e do canal do incidente; histórico de deploys e mudanças (`git log`, execuções do CI); as pessoas envolvidas, por meio do usuário.
|
|
15
|
+
- Horários em UTC, com a fonte de cada entrada.
|
|
16
|
+
- Refira-se às pessoas pelo papel ("a pessoa de plantão"), não pelo nome.
|
|
17
|
+
- Idioma: o do usuário. Termos técnicos como o time os usa.
|
|
18
|
+
- Incógnitas vão para **Perguntas em aberto**. Nunca invente uma entrada na linha do tempo ou uma causa.
|
|
19
|
+
|
|
20
|
+
## Linguagem sem culpados
|
|
21
|
+
|
|
22
|
+
- Descreva ações e decisões, e o contexto que as tornou razoáveis: "O deploy rodou sem canary porque o pipeline não tinha etapa de canary."
|
|
23
|
+
- Não "X esqueceu", "X deveria ter", "erro humano". Erro humano é um sintoma; pergunte o que tornou o erro fácil e o efeito dele grande.
|
|
24
|
+
- Contrafactuais ("se ao menos tivessem…") vão para as ações, não para a narrativa.
|
|
25
|
+
|
|
26
|
+
## Processo
|
|
27
|
+
|
|
28
|
+
### 1. Impacto
|
|
29
|
+
Em números: duração (início → mitigado → resolvido), usuários ou requisições afetados, taxa de erro, dados perdidos ou corrompidos, dinheiro, orçamento de erro do SLO consumido, implicações contratuais ou de LGPD (um incidente com dados pessoais pode exigir comunicação à ANPD: verifique com `lgpd-compliance`).
|
|
30
|
+
|
|
31
|
+
### 2. Linha do tempo
|
|
32
|
+
Do primeiro gatilho (muitas vezes uma mudança dias antes) até a resolução. Marque os momentos-chave: **gatilho**, **detecção** (como: alerta, cliente, acaso), **início da resposta**, **mitigação**, **resolução**. Calcule o tempo até a detecção e o tempo até a mitigação.
|
|
33
|
+
|
|
34
|
+
### 3. Fatores contribuintes
|
|
35
|
+
Sistemas complexos raramente falham por uma causa só. Liste os fatores que se combinaram: o gatilho, as condições latentes que permitiram que ele quebrasse as coisas, o que atrasou a detecção e o que desacelerou a mitigação. Para cada um, pergunte "por quê?" até chegar a algo que o time consiga mudar (5 Porquês), e pare aí.
|
|
36
|
+
|
|
37
|
+
### 4. O que deu certo, o que deu errado, onde tivemos sorte
|
|
38
|
+
Sorte é um achado: ela marca uma defesa que ainda não existe.
|
|
39
|
+
|
|
40
|
+
### 5. Ações
|
|
41
|
+
- Cada uma trata de um fator contribuinte e é de um destes tipos: **prevenir** (impedir o gatilho ou a condição latente), **detectar** (alertar mais cedo), **mitigar** (impacto menor, recuperação mais rápida).
|
|
42
|
+
- Específicas, com dono (um papel ou time), com ticket e com data. "Ter mais cuidado" não é uma ação.
|
|
43
|
+
- Prefira mudanças no sistema (testes, proteções, automação, alertas) a lembretes de processo.
|
|
44
|
+
- Poucas ações concluídas valem mais que uma lista longa que apodrece.
|
|
45
|
+
|
|
46
|
+
## Formato
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
# Postmortem: <título> — <data>
|
|
50
|
+
Status: <rascunho | revisado> · Severidade: <SEV-n> · Autores: <papéis>
|
|
51
|
+
|
|
52
|
+
## Resumo
|
|
53
|
+
<3–4 frases: o que aconteceu, impacto, causa em resumo, estado atual>
|
|
54
|
+
|
|
55
|
+
## Impacto
|
|
56
|
+
| Métrica | Valor |
|
|
57
|
+
|
|
58
|
+
## Linha do tempo (UTC)
|
|
59
|
+
| Horário | Evento | Fonte |
|
|
60
|
+
Tempo até detectar: … · Tempo até mitigar: … · Tempo até resolver: …
|
|
61
|
+
|
|
62
|
+
## Fatores contribuintes
|
|
63
|
+
### <fator>
|
|
64
|
+
<descrição> — Cadeia de porquês: … → …
|
|
65
|
+
|
|
66
|
+
## O que deu certo / errado / onde tivemos sorte
|
|
67
|
+
|
|
68
|
+
## Ações
|
|
69
|
+
| # | Ação | Tipo (prevenir/detectar/mitigar) | Fator | Dono | Ticket | Prazo |
|
|
70
|
+
|
|
71
|
+
## Perguntas em aberto
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Próximo
|
|
75
|
+
|
|
76
|
+
- `requirements-gathering`: `RNF-NN` novos a partir das ações.
|
|
77
|
+
- `testing`: um teste de regressão para o modo de falha.
|
|
78
|
+
- `observability`: alertas novos ou mudanças de SLO para as lacunas de detecção.
|
|
79
|
+
- `architecture-decision-record` quando a correção for uma mudança de design.
|
|
80
|
+
- `executive-writing` para um resumo curto à liderança ou aos clientes.
|
|
81
|
+
|
|
82
|
+
## No Forja
|
|
83
|
+
|
|
84
|
+
No Forja, registre o incidente no grafo de engenharia com `forja incident:record --title "<título>" --description "<resumo>"`; incidentes parecidos aparecem em `forja incident:similar`. O documento do postmortem fica em `memory/60-runs/postmortems/<data>-<slug>.md`.
|
|
85
|
+
|
|
86
|
+
## Evite
|
|
87
|
+
|
|
88
|
+
- Nomes e culpa, inclusive culpa implícita ("apesar do runbook…").
|
|
89
|
+
- Uma única causa raiz quando vários fatores se combinaram.
|
|
90
|
+
- Ações sem dono ou sem data.
|
|
91
|
+
- "Monitorar mais de perto" ou "ter mais cuidado" como ações.
|
|
92
|
+
- Linhas do tempo reconstruídas de memória, sem fontes.
|
|
93
|
+
- Publicar antes de as pessoas envolvidas revisarem.
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: lgpd-compliance
|
|
3
|
+
description: Use quando desenhar ou revisar um sistema, funcionalidade ou modelo de dados que trata dados pessoais sob a LGPD: classifica os dados, atribui bases legais, retenção e direitos dos titulares, e deriva os controles técnicos.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Conformidade com a LGPD
|
|
7
|
+
|
|
8
|
+
Aplica a LGPD (Lei nº 13.709/2018) a um sistema, funcionalidade ou modelo de domínio, pelo lado da engenharia: que dados existem, por que são tratados, com qual base legal, por quanto tempo, quem pode acessá-los e quais controles técnicos decorrem disso.
|
|
9
|
+
|
|
10
|
+
Isto é **conformidade desde a concepção** (privacy by design), não aconselhamento jurídico. Toda saída termina com os pontos que precisam ser validados pelo Encarregado ou pelo jurídico.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- Termos jurídicos em pt-BR seguidos do en-US: Titular (Data Subject), Controlador (Controller), Operador (Processor), Encarregado (DPO), Tratamento (Processing), Base Legal (Legal Basis), Dado Pessoal Sensível (Sensitive Personal Data), Anonimização (Anonymization), Pseudonimização (Pseudonymization), RIPD (Data Protection Impact Assessment), ANPD (National Data Protection Authority).
|
|
15
|
+
- Cite os artigos da LGPD ao enunciar uma obrigação, para que possa ser verificada.
|
|
16
|
+
- Não invente bases legais nem prazos de retenção. Itens desconhecidos vão para **Perguntas em aberto**.
|
|
17
|
+
- As regulamentações da ANPD mudam. Quando um prazo ou procedimento depender de regulamento da ANPD, sinalize-o para verificação contra o texto vigente.
|
|
18
|
+
|
|
19
|
+
## Princípio central
|
|
20
|
+
|
|
21
|
+
A conformidade começa pela **finalidade**. Todo dado pessoal precisa responder: para quê, com qual base, por quanto tempo. Um dado que não consegue responder é um dado que não deveria ser coletado (princípio da necessidade, Art. 6º, III).
|
|
22
|
+
|
|
23
|
+
## Processo
|
|
24
|
+
|
|
25
|
+
### 1. Inventariar os dados
|
|
26
|
+
Liste cada dado pessoal que o sistema coleta, deriva ou recebe de outros sistemas. Inclua os não óbvios: endereços IP, IDs de dispositivo, logs, geolocalização, campos de texto livre, uploads de arquivos, dados dentro de eventos e filas, backups.
|
|
27
|
+
|
|
28
|
+
### 2. Classificar cada dado
|
|
29
|
+
| Classe | Definição | Artigo |
|
|
30
|
+
|---|---|---|
|
|
31
|
+
| Dado pessoal | Identifica ou pode identificar uma pessoa natural. | Art. 5º, I |
|
|
32
|
+
| Dado pessoal sensível | Origem racial ou étnica, convicção religiosa, opinião política, filiação a sindicato ou a organização de caráter religioso, filosófico ou político, dado referente à saúde ou à vida sexual, dado genético ou biométrico. | Art. 5º, II |
|
|
33
|
+
| Dados de crianças e adolescentes | Exigem tratamento no seu melhor interesse; dados de crianças seguem regras específicas. | Art. 14 |
|
|
34
|
+
| Dado anonimizado | Não pode ser reidentificado por meios razoáveis. Fora do escopo enquanto permanecer anônimo. | Art. 5º, III; Art. 12 |
|
|
35
|
+
| Dado pseudonimizado | Continua sendo dado pessoal: a reidentificação é possível com a chave mantida separada. | Art. 13, §4º |
|
|
36
|
+
|
|
37
|
+
### 3. Ligar o tratamento à finalidade e à base legal
|
|
38
|
+
Para cada finalidade (não para cada campo), declare a finalidade em uma frase, os dados usados e a base legal.
|
|
39
|
+
|
|
40
|
+
- **Dados pessoais** (Art. 7º): consentimento; cumprimento de obrigação legal ou regulatória; administração pública; estudos por órgão de pesquisa; execução de contrato; exercício regular de direitos; proteção da vida; tutela da saúde por profissionais ou serviços de saúde; interesse legítimo; proteção do crédito.
|
|
41
|
+
- **Dados sensíveis** (Art. 11): lista mais restrita. Interesse legítimo, execução de contrato e proteção do crédito **não** estão disponíveis. Tutela da saúde, obrigação legal ou regulatória, proteção da vida, exercício regular de direitos e prevenção à fraude e à segurança do titular são os candidatos habituais.
|
|
42
|
+
- O **consentimento** precisa ser livre, informado, inequívoco e para uma finalidade determinada, e pode ser revogado (Art. 8º). Prefira outra base quando uma de fato se aplicar; um sistema construído sobre consentimento precisa suportar a revogação.
|
|
43
|
+
- O **interesse legítimo** exige um teste de balanceamento e só os dados estritamente necessários (Art. 10).
|
|
44
|
+
|
|
45
|
+
### 4. Definir a retenção e o término do tratamento
|
|
46
|
+
Para cada finalidade: por quanto tempo o dado é mantido, o que dispara o término (Art. 15) e o que acontece depois: exclusão, anonimização ou conservação sob uma exceção do Art. 16 (por exemplo, obrigação legal). Um prazo legal de retenção precisa ser nomeado, não suposto.
|
|
47
|
+
|
|
48
|
+
### 5. Atender aos direitos dos titulares (Art. 18)
|
|
49
|
+
Para cada direito, declare como o sistema o atende ou por que não se aplica:
|
|
50
|
+
confirmação da existência de tratamento; acesso; correção; anonimização, bloqueio ou eliminação de dados desnecessários ou excessivos; portabilidade; eliminação dos dados tratados com consentimento; informação sobre compartilhamento; informação sobre a possibilidade de não consentir; revogação do consentimento. E também a revisão de decisões automatizadas (Art. 20), quando o sistema as toma.
|
|
51
|
+
|
|
52
|
+
Consequência para a engenharia: os dados pessoais precisam ser localizáveis por titular em tabelas, arquivos, eventos e backups. Se não podem ser encontrados, não podem ser devolvidos nem excluídos.
|
|
53
|
+
|
|
54
|
+
### 6. Mapear compartilhamentos e transferências
|
|
55
|
+
Liste cada destinatário: operadores (nuvem, e-mail, analytics, provedores de IA), outros controladores, órgãos públicos. Para transferências para fora do Brasil, identifique o mecanismo do Art. 33. Os operadores agem segundo as instruções do controlador (Art. 39).
|
|
56
|
+
|
|
57
|
+
### 7. Derivar os controles técnicos (Art. 46)
|
|
58
|
+
Escolha de forma proporcional ao risco:
|
|
59
|
+
- **Minimização**: não colete o que não tem finalidade; evite campos de texto livre que atraem dados sensíveis.
|
|
60
|
+
- **Segregação**: dados sensíveis em tabelas ou schema próprios, com acesso restrito.
|
|
61
|
+
- **Criptografia**: em trânsito, sempre; em repouso para dados sensíveis (no nível da coluna ou da aplicação quando o nível do banco não for suficiente).
|
|
62
|
+
- **Pseudonimização**: para analytics, BI e réplicas que não precisam da identidade.
|
|
63
|
+
- **Controle de acesso**: privilégio mínimo, por papel e por finalidade; segurança por linha (row-level security) onde uma tabela atende vários contextos.
|
|
64
|
+
- **Trilha de auditoria**: registro somente de acréscimo de quem acessou ou alterou dados pessoais, quando e por quê. Na prática, exigido para responder a direitos e incidentes.
|
|
65
|
+
- **Logs e observabilidade**: nada de dados pessoais em logs, traces, labels de métricas ou mensagens de erro. Mascare por padrão.
|
|
66
|
+
- **Exclusão de verdade**: soft delete não é exclusão. Defina como a exclusão ou a anonimização chega a réplicas, caches, índices de busca, filas e backups.
|
|
67
|
+
- **Ambientes fora de produção**: nada de dados pessoais reais em desenvolvimento ou teste sem anonimização.
|
|
68
|
+
|
|
69
|
+
### 8. Avaliar a necessidade de um relatório de impacto
|
|
70
|
+
Recomende um RIPD (Art. 38) quando o tratamento envolver dados sensíveis em escala, tratamento em larga escala, monitoramento sistemático, tecnologias novas, decisões automatizadas com efeito significativo, ou interesse legítimo como base para um tratamento de alto risco.
|
|
71
|
+
|
|
72
|
+
### 9. Preparar-se para incidentes
|
|
73
|
+
Declare como um incidente de segurança seria detectado e dimensionado (quais titulares, quais dados). A comunicação à ANPD e aos titulares é obrigatória quando o incidente puder acarretar risco ou dano relevante (Art. 48); verifique o prazo no regulamento vigente da ANPD.
|
|
74
|
+
|
|
75
|
+
## Formato de saída
|
|
76
|
+
|
|
77
|
+
```
|
|
78
|
+
## Inventário de dados
|
|
79
|
+
| Dado | Classe | Origem | Onde é armazenado | Finalidades |
|
|
80
|
+
|
|
81
|
+
## Mapa de tratamento
|
|
82
|
+
| Finalidade | Dados | Base legal (artigo) | Retenção / gatilho de término | Destinatários |
|
|
83
|
+
|
|
84
|
+
## Direitos dos titulares
|
|
85
|
+
| Direito | Como é atendido | Lacunas |
|
|
86
|
+
|
|
87
|
+
## Controles técnicos
|
|
88
|
+
- <controle> — aplica-se a <dado/fluxo> — motivo
|
|
89
|
+
|
|
90
|
+
## Relatório de impacto
|
|
91
|
+
<necessário / não necessário, e por quê>
|
|
92
|
+
|
|
93
|
+
## Perguntas em aberto
|
|
94
|
+
- <base legal, prazo de retenção, contratos, transferências a validar com o Encarregado/jurídico>
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## No Forja
|
|
98
|
+
|
|
99
|
+
No Forja, decisões de base legal, retenção e transferência viram ADR em `memory/90-decisions/`, e os requisitos derivados entram em §6 da spec (`specs/<slug>/spec.md`).
|
|
100
|
+
|
|
101
|
+
## Evite
|
|
102
|
+
|
|
103
|
+
- Tratar o consentimento como base padrão para tudo.
|
|
104
|
+
- Supor que dados pseudonimizados estão fora da LGPD.
|
|
105
|
+
- Guardar dados "por via das dúvidas", sem finalidade nem prazo.
|
|
106
|
+
- Dados pessoais em logs, URLs, eventos de analytics ou fixtures de teste.
|
|
107
|
+
- Soft delete apresentado como exclusão.
|
|
108
|
+
- Apresentar conclusões como aconselhamento jurídico.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: llm-provider-routing
|
|
3
|
+
description: Use quando uma tarefa exige trocar de provedor ou modelo de LLM no Forja: seleciona, configura e verifica perfis, executa com contexto pela CLI, retoma sessões do Codex e valida as respostas com evidências.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Roteamento de LLMs
|
|
7
|
+
|
|
8
|
+
Siga o `AGENTS.md` do projeto. Para sintaxe e limites de cada comando, use `forja help <comando>`; não carregue catálogos de provedores sem necessidade.
|
|
9
|
+
|
|
10
|
+
1. Identifique papel, tarefa, privacidade e restrições de custo/latência. Respeite a escolha autorizada pelo usuário; não troque modelo silenciosamente.
|
|
11
|
+
2. Use `forja llm:profiles:init` e revise `.context/llm-profiles.json` no workspace. Configure um executável em `command`, argumentos em `commandArgs` e o identificador real do modelo. Não inclua credenciais nem comandos de shell.
|
|
12
|
+
3. Execute `forja llm:probe <perfil>`. Registre versão e recursos detectados. Probe bem-sucedido não comprova autenticação nem acesso ao modelo.
|
|
13
|
+
4. Consulte `forja llm:recommend --role <papel> --task <tipo>` como evidência auxiliar, sem tratar ranking como garantia de qualidade.
|
|
14
|
+
5. Execute `forja llm:run --profile <perfil> --task <arquivo>`. Se necessário, use `--context <arquivo>` repetido. Confira o conteúdo antes de enviá-lo ao provedor.
|
|
15
|
+
6. Para Codex compatível, use `--resume <session-id>` apenas com sessão conhecida no mesmo projeto/perfil. Use `--output-schema <arquivo>` e `--validation <manifest>` para formato e checks independentes. Revise os executáveis do manifest: eles rodam com permissões do Forja.
|
|
16
|
+
7. Informe execução, validação, origem do uso de tokens e custo separadamente. Schema sozinho não comprova qualidade. Não afirme custo zero quando ele é desconhecido.
|
|
17
|
+
|
|
18
|
+
Se não houver adapter ou CLI compatível, explique a lacuna e configure um wrapper revisável somente dentro do escopo autorizado. Não invente suporte a API, MCP ou recursos de sessão. Não recomende um provedor por reputação sem evidência atual da tarefa.
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: observability
|
|
3
|
+
description: Use quando preparar um serviço ou funcionalidade para produção: deriva SLIs e SLOs dos requisitos não funcionais, planeja métricas, logs estruturados e traces, e define alertas baseados em sintomas, cada um com um esboço de runbook.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Observabilidade
|
|
7
|
+
|
|
8
|
+
Um sistema é observável quando você consegue responder a uma pergunta nova sobre o comportamento dele em produção sem publicar código novo. O objetivo não são dashboards: é saber que os usuários estão sofrendo antes que eles avisem, e descobrir o porquê rápido.
|
|
9
|
+
|
|
10
|
+
A saída padrão é um **plano de observabilidade**: SLOs, sinais e alertas. Escreva código de instrumentação só quando o usuário pedir.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- Entradas: `RNF-NN` mensuráveis de `requirements-gathering`; endpoints de `api-design`; classificação de dados pessoais de `lgpd-compliance`; eventos de segurança de `threat-modeling`.
|
|
15
|
+
- Siga o código existente: a biblioteca de log, o backend de métricas e a configuração de tracing. Use [OpenTelemetry](https://opentelemetry.io/) e suas convenções semânticas como padrão quando não houver nada.
|
|
16
|
+
- Tráfego, metas ou escalas de plantão desconhecidos vão para **Perguntas em aberto**. Não invente metas de SLO; derive-as ou pergunte.
|
|
17
|
+
|
|
18
|
+
## SLIs e SLOs
|
|
19
|
+
|
|
20
|
+
- Um **SLI** mede o que o usuário experimenta, como a razão entre eventos bons e eventos válidos: disponibilidade (respostas não-5xx / todas as respostas), latência (requisições abaixo de X ms / todas as requisições), atualidade, correção.
|
|
21
|
+
- Um **SLO** é a meta de um SLI numa janela: "99,5% dos `POST /orders` abaixo de 300 ms em 28 dias".
|
|
22
|
+
- Derive cada SLO de um `RNF-NN`. Quando o requisito não for mensurável, devolva-o para `requirements-gathering`.
|
|
23
|
+
- O **orçamento de erro** (100% − SLO) é o que os alertas e as decisões de release consomem.
|
|
24
|
+
- Poucos SLOs, nas jornadas de usuário que importam. Não um por endpoint.
|
|
25
|
+
|
|
26
|
+
## Métricas
|
|
27
|
+
|
|
28
|
+
- **RED** para serviços guiados por requisições: Taxa (Rate), Erros, Duração (como histograma, nunca média).
|
|
29
|
+
- **USE** para recursos: Utilização, Saturação, Erros (pools, filas, CPU, memória).
|
|
30
|
+
- **Métricas de negócio** que dizem se a funcionalidade funciona: pedidos criados, pagamentos que falharam.
|
|
31
|
+
- Só labels com cardinalidade limitada: template da rota, método, classe do status. Nunca IDs de usuário, e-mails ou URLs cruas.
|
|
32
|
+
|
|
33
|
+
## Logs
|
|
34
|
+
|
|
35
|
+
- Estruturados (JSON), um evento por linha, com `timestamp`, `level`, `message`, `service`, `trace_id` e os identificadores de domínio necessários para investigar (ID do pedido, não o nome do cliente).
|
|
36
|
+
- Os níveis significam algo: `error` exige ação; `warn` é inesperado mas tratado; `info` é um evento de negócio ou de ciclo de vida; `debug` fica desligado em produção.
|
|
37
|
+
- **Nada de dados pessoais, segredos ou tokens** nos logs (conforme `lgpd-compliance`). Quando for preciso um identificador, use um ID pseudônimo.
|
|
38
|
+
- Registre nas fronteiras e nas decisões, não em toda linha. Registre cada erro uma vez, onde ele é tratado.
|
|
39
|
+
- Os eventos de segurança de `threat-modeling` (falhas de autenticação, permissões negadas, acionamentos do limite de taxa) são registrados com o ator e o objeto.
|
|
40
|
+
|
|
41
|
+
## Traces
|
|
42
|
+
|
|
43
|
+
- Propague o contexto em toda fronteira: HTTP, filas, jobs (W3C Trace Context).
|
|
44
|
+
- Spans para requisições de entrada, chamadas de saída, consultas ao banco e operações de fila, com atributos semânticos.
|
|
45
|
+
- Amostre por taxa, mas mantenha todos os traces de erro e os lentos quando o backend suportar amostragem na cauda (tail sampling).
|
|
46
|
+
|
|
47
|
+
## Alertas
|
|
48
|
+
|
|
49
|
+
- Alerte sobre **sintomas** que os usuários sentem (taxa de consumo do SLO), não sobre causas (CPU em 80%).
|
|
50
|
+
- Use alertas de taxa de consumo com múltiplas janelas: consumo rápido aciona plantão (por exemplo, 2% do orçamento em 1 h), consumo lento abre um ticket (por exemplo, 10% em 3 dias).
|
|
51
|
+
- Todo acionamento de plantão é acionável, urgente e precisa de um humano. O resto é ticket ou dashboard.
|
|
52
|
+
- Todo alerta aponta para um esboço de runbook: o que significa, primeiras verificações, mitigação, escalonamento.
|
|
53
|
+
|
|
54
|
+
## Formato
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
## SLOs
|
|
58
|
+
| SLO | SLI (bons / válidos) | Meta | Janela | Origem |
|
|
59
|
+
|---|---|---|---|---|
|
|
60
|
+
| Latência de criação de pedido | POST /orders < 300 ms / todos os POST /orders | 99,5% | 28d | RNF-03 |
|
|
61
|
+
|
|
62
|
+
## Métricas
|
|
63
|
+
| Nome | Tipo | Labels | Finalidade |
|
|
64
|
+
|
|
65
|
+
## Logs
|
|
66
|
+
<eventos por caso de uso: nível, mensagem, campos>
|
|
67
|
+
|
|
68
|
+
## Traces
|
|
69
|
+
<fronteiras instrumentadas, amostragem>
|
|
70
|
+
|
|
71
|
+
## Alertas
|
|
72
|
+
| Alerta | Condição | Severidade (plantão/ticket) | Runbook |
|
|
73
|
+
|
|
74
|
+
## Esboços de runbook
|
|
75
|
+
### <Alerta>
|
|
76
|
+
Significado: … Primeiras verificações: … Mitigação: … Escalonamento: …
|
|
77
|
+
|
|
78
|
+
## Perguntas em aberto
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Próximo
|
|
82
|
+
|
|
83
|
+
- `testing`: verifique que os eventos de negócio críticos e os erros são registrados e medidos.
|
|
84
|
+
- `pull-request`: liste os sinais e alertas novos em "O quê".
|
|
85
|
+
|
|
86
|
+
## Evite
|
|
87
|
+
|
|
88
|
+
- Alertar sobre toda métrica de causa.
|
|
89
|
+
- Médias para latência.
|
|
90
|
+
- Labels de alta cardinalidade.
|
|
91
|
+
- Dados pessoais, segredos ou corpos inteiros de requisição em logs ou atributos de span.
|
|
92
|
+
- SLOs em 100%, ou metas tiradas do nada.
|
|
93
|
+
- Dashboards que ninguém olha em vez de alertas que importam.
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: product-evaluation
|
|
3
|
+
description: Use quando uma ideia de produto, startup, app, SaaS ou modelo de negócio precisa de uma avaliação crítica de viabilidade: põe à prova problema, mercado, escopo, concorrência, go-to-market e economia unitária, e devolve um veredito GO / WEAK GO / NO-GO com riscos e recomendações.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Avaliação de Produto
|
|
7
|
+
|
|
8
|
+
Põe um conceito de produto à prova contra a realidade do mercado antes que alguém gaste dinheiro para construí-lo. Entrada: um conceito (app, SaaS, plataforma, ferramenta ou serviço) com o que se sabe sobre público, funcionalidades, monetização e mercado. Saída: um veredito com a evidência por trás dele. Não é para dúvidas de implementação nem para redação de negócios em geral.
|
|
9
|
+
|
|
10
|
+
A avaliação não existe para encorajar. Existe para revelar os problemas enquanto ainda são baratos.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- Termos em pt-BR seguidos do en-US: Proposta de Valor (Value Proposition), Adequação Produto-Mercado (Product-Market Fit), Custo de Aquisição de Cliente (Customer Acquisition Cost, CAC), Valor do Tempo de Vida do Cliente (Customer Lifetime Value, LTV), Custo de Troca (Switching Cost), Partida a Frio (Cold Start), Canal de Aquisição (Acquisition Channel).
|
|
15
|
+
- Toda afirmação traz sua natureza: **confirmada** (evidência fornecida ou encontrada), **suposta** (afirmada sem evidência), **desconhecida** (ninguém sabe ainda).
|
|
16
|
+
- Nomeie segmentos de forma concreta: não "PMEs", mas "uma agência de 3 pessoas que fatura 5+ clientes à mão, sem ninguém de operações".
|
|
17
|
+
|
|
18
|
+
## Princípio central
|
|
19
|
+
|
|
20
|
+
O ceticismo é o padrão; o otimismo se conquista com evidência. Avalie o produto como descrito, não o pitch no melhor cenário: "vai viralizar" é uma suposição não validada, não uma estratégia de crescimento. Mas a falsa negatividade é tão prejudicial quanto a falsa positividade: se o produto é sólido, diga isso com clareza.
|
|
21
|
+
|
|
22
|
+
Seja específico. "Pode ser difícil de vender" é inútil; "a aquisição depende de SEO num espaço dominado por domínios de 10 anos" é útil.
|
|
23
|
+
|
|
24
|
+
## Processo
|
|
25
|
+
|
|
26
|
+
### 1. Problema e mercado
|
|
27
|
+
Interrogue o problema antes da solução.
|
|
28
|
+
- É real e recorrente, ou episódico e de nicho?
|
|
29
|
+
- Quem exatamente o tem?
|
|
30
|
+
- Qual o contorno atual? Se é uma planilha, por que ninguém construiu isso, ou por que as ferramentas existentes falharam?
|
|
31
|
+
- É analgésico (precisa resolver agora) ou vitamina (bom de ter)?
|
|
32
|
+
- O mercado cresce, está estável ou encolhe, e por quê? Há forças regulatórias, sazonais ou estruturais?
|
|
33
|
+
|
|
34
|
+
### 2. Produto e escopo
|
|
35
|
+
Julgue as funcionalidades contra o problema e o usuário real, não contra o roadmap.
|
|
36
|
+
- A **ação de valor central**: a única coisa que o usuário precisa conseguir fazer para o produto ter entregado valor. Ela está priorizada?
|
|
37
|
+
- Quais funcionalidades a servem, e quais são especulativas ou exageradas antes de o núcleo ser validado?
|
|
38
|
+
- Que capacidade crítica um usuário sentiria falta de imediato?
|
|
39
|
+
- Superfície de risco técnico: APIs externas, qualidade dos dados, custo de infraestrutura em escala.
|
|
40
|
+
- O fluxo é realista para o usuário de verdade: atrito de onboarding, curva de aprendizado, comportamento inesperado?
|
|
41
|
+
|
|
42
|
+
### 3. Concorrência e posicionamento
|
|
43
|
+
- Concorrentes diretos e indiretos, incluindo processos manuais, ferramentas estabelecidas e soluções adjacentes.
|
|
44
|
+
- Diferenciação estrutural (abordagem, modelo, execução), não "fazemos melhor".
|
|
45
|
+
- É defensável por 18 meses, ou será copiado assim que um player maior vir o nicho comprovado?
|
|
46
|
+
- Custos de troca criados. Sem eles, a retenção é uma luta constante.
|
|
47
|
+
- Risco de comoditização: está construído sobre uma camada que pode se tornar irrelevante (por exemplo, um invólucro fino sobre uma API de LLM que muda rápido)?
|
|
48
|
+
|
|
49
|
+
### 4. Go-to-market e distribuição
|
|
50
|
+
Falha de distribuição mata mais produtos do que falha de produto.
|
|
51
|
+
- **Canal zero**: os 10 primeiros clientes, conquistados como, por quem?
|
|
52
|
+
- É executável pelos fundadores agora, ou exige recursos que eles não têm?
|
|
53
|
+
- Há um ciclo viral ou de indicação embutido, ou o crescimento vem só de mídia paga ou SEO?
|
|
54
|
+
- Ciclo de venda: autosserviço B2C vs. B2B com várias partes interessadas.
|
|
55
|
+
- Porteiros: lojas de apps, compras, jurídico, revisões de segurança de TI.
|
|
56
|
+
- A mensagem é específica o bastante para ressoar com alguém?
|
|
57
|
+
|
|
58
|
+
### 5. Monetização e economia unitária
|
|
59
|
+
Verifique se o modelo é internamente consistente, não só plausível.
|
|
60
|
+
- O modelo de preço está alinhado a como os usuários percebem o valor?
|
|
61
|
+
- Há evidência de disposição a pagar (benchmarks, produtos análogos, pesquisa), ou é suposição?
|
|
62
|
+
- CAC:LTV com conversão e churn realistas, não otimistas.
|
|
63
|
+
- Vetores de custo em escala: computação, suporte, licenciamento de dados, compliance.
|
|
64
|
+
- Caminho até a economia unitária positiva, e em que escala?
|
|
65
|
+
- E se o principal canal de aquisição ficar 2× mais caro?
|
|
66
|
+
|
|
67
|
+
### 6. Testes transversais
|
|
68
|
+
Aplique a todas as áreas acima:
|
|
69
|
+
- **Partida a frio**: o valor exige massa crítica? Como ela é formada?
|
|
70
|
+
- **Cadeias de dependência**: quais sistemas, APIs, plataformas ou regulações precisam se manter? O que quebra se mudarem?
|
|
71
|
+
- **Execução**: o time descrito consegue construir? O que está subestimado?
|
|
72
|
+
- **Momento**: cedo demais, agora, ou já passou do pico?
|
|
73
|
+
- **Uso real**: o que acontece quando os usuários fazem o inesperado?
|
|
74
|
+
- **Efeitos de segunda ordem**: o sucesso cria problemas novos (carga de suporte, custo de infraestrutura, atenção regulatória)?
|
|
75
|
+
|
|
76
|
+
### 7. Veredito
|
|
77
|
+
- **GO**: o problema é real, existe um canal até os primeiros clientes, a conta fecha; os riscos restantes são conhecidos.
|
|
78
|
+
- **WEAK GO**: viável só se incógnitas específicas forem resolvidas antes; nomeie-as.
|
|
79
|
+
- **NO-GO**: uma falha estrutural que nenhum esforço razoável corrige.
|
|
80
|
+
|
|
81
|
+
Nomeie o único fator mais decisivo.
|
|
82
|
+
|
|
83
|
+
### 8. Encaminhamento
|
|
84
|
+
Incógnitas a investigar → `requirements-elicitation`; escopo de um GO → `requirements-gathering`; riscos técnicos → `technical-spike`; dados pessoais → `lgpd-compliance`; veredito para as partes interessadas → `executive-writing`.
|
|
85
|
+
|
|
86
|
+
## Formato de saída
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
# Avaliação de produto: <produto>
|
|
90
|
+
|
|
91
|
+
## Veredito
|
|
92
|
+
<GO | WEAK GO | NO-GO> — <um parágrafo nomeando o fator mais decisivo>
|
|
93
|
+
|
|
94
|
+
## Pontos fortes
|
|
95
|
+
- <ponto forte específico> (ou: nenhum ponto forte claro)
|
|
96
|
+
|
|
97
|
+
## Pontos fracos
|
|
98
|
+
1. <problema estrutural ou de execução, do mais grave ao menos grave>
|
|
99
|
+
|
|
100
|
+
## Riscos e incógnitas
|
|
101
|
+
- Conhecidos: <visíveis, gerenciáveis com esforço>
|
|
102
|
+
- Desconhecidos: <pontos cegos que exigem descoberta antes de seguir>
|
|
103
|
+
- Dependências externas: <fora do controle do time>
|
|
104
|
+
|
|
105
|
+
## Recomendações
|
|
106
|
+
1. <ação específica> — impacto: <...> — dificuldade/custo: <...>
|
|
107
|
+
|
|
108
|
+
## Uso realista vs. idealizado
|
|
109
|
+
| Projetado para | Provavelmente usado para | Diferença |
|
|
110
|
+
|
|
111
|
+
## Dependências e restrições
|
|
112
|
+
- Técnicas: ...
|
|
113
|
+
- Regulatórias: ...
|
|
114
|
+
- Momento de mercado: ...
|
|
115
|
+
- Time: ...
|
|
116
|
+
- Capital: ...
|
|
117
|
+
|
|
118
|
+
## Encaminhamento
|
|
119
|
+
- <skill>: <o que vai para lá>
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
## Evite
|
|
123
|
+
|
|
124
|
+
- Consolo, rodeios ou enchimento.
|
|
125
|
+
- Feedback genérico que serviria para qualquer produto.
|
|
126
|
+
- Tratar as projeções do fundador ("viral", "todo mundo precisa disso") como evidência.
|
|
127
|
+
- Apresentar suposições como confirmadas.
|
|
128
|
+
- Negatividade sem razão estrutural; um produto sólido recebe um GO claro.
|
|
129
|
+
- Recomendações sem ordem, custo ou dificuldade.
|
|
130
|
+
- Desenhar a solução: telas, stack, arquitetura.
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: prompt-spec
|
|
3
|
+
description: Use quando passar trabalho de implementação para um agente de IA de código: transforma uma história ou requisito em prompts diretivos, prontos para colar, separados para backend e frontend, que exigem que o agente analise o código existente antes de mudar qualquer coisa e definem escopo, restrições e critérios de pronto.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Especificação de Prompt
|
|
7
|
+
|
|
8
|
+
Um agente de código faz o que o prompt torna fácil. Um prompt vago recebe uma implementação plausível que ignora os padrões do código, adiciona dependências e mexe em arquivos não relacionados. Um prompt diretivo declara o objetivo, obriga o agente a aprender o código antes, cerca o escopo e define "pronto" como comandos que passam.
|
|
9
|
+
|
|
10
|
+
A saída padrão é **um prompt por lado (backend, frontend), pronto para colar**, mais a ordem de execução. Esta skill escreve prompts; não executa o agente.
|
|
11
|
+
|
|
12
|
+
## Convenções
|
|
13
|
+
|
|
14
|
+
- Entradas: uma história com critérios de aceite de `backlog-slicing`; o contrato de `api-design`; o modelo de `domain-modeling`; o próprio repositório (leia o README, o CLAUDE.md/AGENTS.md e a estrutura antes de escrever).
|
|
15
|
+
- Idioma do prompt: o do usuário, a menos que a documentação do código e os arquivos de agente estejam em outro.
|
|
16
|
+
- Frases imperativas e específicas. Sem gentilezas de enchimento, sem texto motivacional.
|
|
17
|
+
- Referencie caminhos, tipos e comandos reais do repositório. Leia-os antes; nunca invente um arquivo ou script.
|
|
18
|
+
- Um prompt = uma história ou fatia. Um prompt que precisa de "e também…" são dois prompts.
|
|
19
|
+
|
|
20
|
+
## Por que separar backend e frontend
|
|
21
|
+
|
|
22
|
+
Eles têm bases de código ou pastas, convenções, testes e revisores diferentes. O **contrato da API é a costura**: o prompt de backend o implementa, o prompt de frontend o consome. Os dois citam o mesmo contrato, então podem rodar em paralelo ou em sequência sem divergir. Rode o backend primeiro quando o contrato é novo; em paralelo quando ele já existe.
|
|
23
|
+
|
|
24
|
+
## Estrutura do prompt
|
|
25
|
+
|
|
26
|
+
Todo prompt tem estas seções, nesta ordem:
|
|
27
|
+
|
|
28
|
+
1. **Objetivo**: uma ou duas frases, o resultado visível ao usuário. Referencie o ID da história.
|
|
29
|
+
2. **Passo 0, analisar antes de implementar** (obrigatório): liste o que ler e o que relatar **antes de escrever código**:
|
|
30
|
+
- os arquivos e módulos que tratam de funcionalidades parecidas (nomeie-os);
|
|
31
|
+
- os padrões a copiar (tratamento de erro, validação, testes, nomes);
|
|
32
|
+
- os arquivos de agente (CLAUDE.md, AGENTS.md) e as configurações dos linters;
|
|
33
|
+
- um plano curto: arquivos a criar ou alterar, e por quê.
|
|
34
|
+
Instrua o agente a parar depois do relatório se algo contradisser o prompt.
|
|
35
|
+
3. **Contexto**: as regras do domínio (`RN-NN`), o contrato (especificação do endpoint ou tipos), os ADRs relevantes. Cite-os; não parafraseie regras.
|
|
36
|
+
4. **Requisitos**: os critérios de aceite em Dado/Quando/Então, literalmente.
|
|
37
|
+
5. **Restrições**:
|
|
38
|
+
- seguir as convenções encontradas no passo 0;
|
|
39
|
+
- nenhuma dependência nova sem perguntar;
|
|
40
|
+
- os testes vão junto com a mudança (conforme `testing` / `ts-testing`);
|
|
41
|
+
- nada de refatorações, renomeações ou formatação não relacionadas;
|
|
42
|
+
- nenhuma mudança no contrato (o outro lado depende dele).
|
|
43
|
+
6. **Fora do escopo**: o que não fazer, explicitamente (o outro lado, histórias futuras, migrações que são de outra pessoa).
|
|
44
|
+
7. **Pronto quando**: comandos que precisam passar (`tsc --noEmit`, `npm test`, linters, build, como o repositório os define), e os critérios de aceite demonstrados.
|
|
45
|
+
8. **Pare e pergunte se**: o contrato for impossível como escrito, uma regra for ambígua, a mudança precisar de uma migração ou de uma dependência nova, ou o passo 0 encontrar uma implementação existente.
|
|
46
|
+
9. **Entregue**: um resumo dos arquivos alterados, como foi testado e uma mensagem de commit proposta (`commit-message`).
|
|
47
|
+
|
|
48
|
+
## Formato
|
|
49
|
+
|
|
50
|
+
````
|
|
51
|
+
## Ordem de execução
|
|
52
|
+
<backend → frontend | paralelo>, porque <motivo>
|
|
53
|
+
|
|
54
|
+
## Prompt de backend
|
|
55
|
+
```text
|
|
56
|
+
<seções 1–9>
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Prompt de frontend
|
|
60
|
+
```text
|
|
61
|
+
<seções 1–9>
|
|
62
|
+
```
|
|
63
|
+
````
|
|
64
|
+
|
|
65
|
+
Omita um lado quando a história só mexe no outro, e diga isso.
|
|
66
|
+
|
|
67
|
+
## Próximo
|
|
68
|
+
|
|
69
|
+
- Depois que o agente rodar: `ts-code-review` (ou a revisão da linguagem), depois `commit-message` e `pull-request`.
|
|
70
|
+
- Se o passo 0 revelar uma questão de design: `architecture-decision-record` ou `technical-spike` antes de continuar.
|
|
71
|
+
|
|
72
|
+
## No Forja
|
|
73
|
+
|
|
74
|
+
No Forja, além de colar o prompt, registre a entrega como handoff (ADR-0005), com os 7 campos: `forja hermes:handoff '<json>'`, mapeando *context* ← Contexto, *acceptance* ← Requisitos + Pronto quando, *constraints* ← Restrições + Fora do escopo, *return* ← Entregue. Quem recebe lista os seus com `forja agent:route list --open --mine` e fecha com `forja agent:route done <id>`.
|
|
75
|
+
|
|
76
|
+
## Evite
|
|
77
|
+
|
|
78
|
+
- "Implemente a funcionalidade X" sem contexto.
|
|
79
|
+
- Pular o passo 0, ou deixar o agente codificar antes de relatar a análise.
|
|
80
|
+
- Um prompt só para backend e frontend juntos.
|
|
81
|
+
- Caminhos, scripts ou tipos que não existem no repositório.
|
|
82
|
+
- Deixar o agente mudar o contrato ou adicionar dependências em silêncio.
|
|
83
|
+
- "Pronto" sem comandos que o provem.
|