spec-first-claude 0.2.0 → 0.4.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.
Files changed (37) hide show
  1. package/README.md +144 -147
  2. package/bin/cli.js +52 -52
  3. package/lib/init.js +89 -93
  4. package/package.json +24 -23
  5. package/templates/.ai/memory/napkin.md +68 -68
  6. package/templates/.claude/agents/backend-coder.md +215 -215
  7. package/templates/.claude/agents/db-coder.md +165 -165
  8. package/templates/.claude/agents/doc-writer.md +51 -51
  9. package/templates/.claude/agents/frontend-coder.md +222 -222
  10. package/templates/.claude/agents/infra-coder.md +341 -341
  11. package/templates/.claude/agents/reviewer.md +99 -99
  12. package/templates/.claude/agents/security-reviewer.md +153 -153
  13. package/templates/.claude/commands/design.md +107 -107
  14. package/templates/.claude/commands/dev.md +189 -167
  15. package/templates/.claude/commands/extract.md +137 -137
  16. package/templates/.claude/commands/feature.md +60 -60
  17. package/templates/.claude/commands/merge-delta.md +70 -70
  18. package/templates/.claude/commands/plan.md +86 -86
  19. package/templates/.claude/commands/{pausar.md → session-finish.md} +83 -83
  20. package/templates/.claude/commands/setup-projeto.md +68 -68
  21. package/templates/.claude/settings.local.json +6 -6
  22. package/templates/CLAUDE.md +198 -199
  23. package/templates/docs/Desenvolvimento/rules.md +229 -229
  24. package/templates/docs/_templates/estrutura/ADRs.template.md +91 -91
  25. package/templates/docs/_templates/estrutura/API.template.md +144 -144
  26. package/templates/docs/_templates/estrutura/Arquitetura.template.md +82 -82
  27. package/templates/docs/_templates/estrutura/Infraestrutura.template.md +104 -104
  28. package/templates/docs/_templates/estrutura/Modelo_Dados.template.md +99 -99
  29. package/templates/docs/_templates/estrutura/Seguranca.template.md +138 -138
  30. package/templates/docs/_templates/estrutura/Stack.template.md +78 -78
  31. package/templates/docs/_templates/estrutura/Visao.template.md +82 -82
  32. package/templates/docs/_templates/feature/Progresso.template.md +136 -136
  33. package/templates/docs/_templates/feature/backlog-extraido.template.md +154 -154
  34. package/templates/docs/_templates/feature/context.template.md +42 -42
  35. package/templates/docs/_templates/feature/extract-log.template.md +38 -38
  36. package/templates/docs/_templates/feature/projetos.template.yaml +73 -73
  37. package/templates/docs/_templates/global/progresso_global.template.md +57 -57
@@ -1,144 +1,144 @@
1
- # Convenções de API
2
-
3
- > Padrões globais para todas as APIs do sistema: versionamento, autenticação, paginação, erros.
4
-
5
- ---
6
-
7
- <!--
8
- =============================================================================
9
- INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
10
- =============================================================================
11
-
12
- ORIGEM: Gerado pelo /setup-projeto a partir do TRD §5.
13
- ATUALIZAÇÃO: /merge-delta quando features adicionam endpoints (Delta Specs do SDD §5 e §11).
14
-
15
- COMO GERAR:
16
- 1. Ler TRD §5 (Convenções de API) — padrão geral, versionamento, autenticação
17
- 2. Padrão geral e convenções são FIXOS após setup — definidos uma vez
18
- 3. Catálogo de endpoints é DINÂMICO — cresce a cada feature
19
- 4. Formatos de paginação, filtro e erro são FIXOS — toda API segue
20
-
21
- REGRAS:
22
- - Convenções são LEI — todo SDD §5 (endpoints) deve seguir estes padrões
23
- - Catálogo de endpoints atualizado a cada merge-delta
24
- - Mudanças em convenções (raro) devem gerar ADR
25
- - Rate limiting definido por categoria de endpoint, não individual
26
-
27
- =============================================================================
28
- -->
29
-
30
- ## Padrão Geral
31
-
32
- | Aspecto | Padrão |
33
- |---------|--------|
34
- | Estilo | <!-- REST / GraphQL / gRPC --> |
35
- | Formato | <!-- JSON / Protobuf --> |
36
- | Versionamento | <!-- /api/v1/ no path? Header? --> |
37
- | Autenticação | <!-- Bearer JWT? API Key? --> |
38
- | Content-Type | <!-- application/json --> |
39
- | Encoding | <!-- UTF-8 --> |
40
-
41
- ## Convenções de Rotas
42
-
43
- | Operação | Método | Rota | Exemplo |
44
- |----------|--------|------|---------|
45
- | Listar | GET | `/api/v1/{recurso}` | |
46
- | Detalhar | GET | `/api/v1/{recurso}/:id` | |
47
- | Criar | POST | `/api/v1/{recurso}` | |
48
- | Atualizar completo | PUT | `/api/v1/{recurso}/:id` | |
49
- | Atualizar parcial | PATCH | `/api/v1/{recurso}/:id` | |
50
- | Remover/Inativar | DELETE | `/api/v1/{recurso}/:id` | |
51
-
52
- ### Convenções de nomenclatura
53
- | Regra | Exemplo |
54
- |-------|---------|
55
- | Recursos no plural, kebab-case | `/api/v1/order-items` |
56
- | Ações não-CRUD como sub-recurso | `/api/v1/users/:id/activate` |
57
- | Filtros via query params | `/api/v1/users?status=active` |
58
- | Relações aninhadas (max 2 níveis) | `/api/v1/users/:id/orders` |
59
-
60
- ## Paginação
61
-
62
- ```json
63
- {
64
- "data": [],
65
- "meta": {
66
- "page": 1,
67
- "per_page": 20,
68
- "total": 0,
69
- "total_pages": 0
70
- }
71
- }
72
- ```
73
-
74
- Query params: `?page=1&per_page=20&sort=campo&order=asc`
75
-
76
- | Parâmetro | Default | Máximo | Descrição |
77
- |-----------|---------|--------|-----------|
78
- | `page` | 1 | — | Página atual |
79
- | `per_page` | 20 | <!-- Ex: 100 --> | Itens por página |
80
- | `sort` | — | — | Campo para ordenação |
81
- | `order` | `asc` | — | `asc` ou `desc` |
82
-
83
- ## Filtros
84
-
85
- Query params: `?busca=termo&campo=valor`
86
-
87
- | Tipo de filtro | Formato | Exemplo |
88
- |----------------|---------|---------|
89
- | Igualdade | `?campo=valor` | `?status=ativo` |
90
- | Busca textual | `?busca=termo` | `?busca=joao` |
91
- | Range de data | `?de=YYYY-MM-DD&ate=YYYY-MM-DD` | `?de=2026-01-01&ate=2026-12-31` |
92
- | Múltiplos valores | `?campo=a,b,c` | `?status=ativo,pendente` |
93
-
94
- ## Respostas de Erro
95
-
96
- ```json
97
- {
98
- "error": {
99
- "code": "ERROR_CODE",
100
- "message": "Mensagem legível para o usuário",
101
- "details": [
102
- { "field": "campo", "message": "Detalhe do erro" }
103
- ]
104
- }
105
- }
106
- ```
107
-
108
- ### Códigos HTTP
109
-
110
- | Código | Quando usar | Exemplo |
111
- |--------|-------------|---------|
112
- | 200 | Sucesso (GET, PUT, PATCH) | Recurso retornado/atualizado |
113
- | 201 | Criado com sucesso (POST) | Recurso criado, retorna o objeto |
114
- | 204 | Sucesso sem conteúdo (DELETE) | Recurso removido |
115
- | 400 | Dados inválidos (formato) | JSON malformado |
116
- | 401 | Não autenticado | Token ausente ou expirado |
117
- | 403 | Sem permissão | Papel sem acesso ao recurso |
118
- | 404 | Recurso não encontrado | ID inexistente |
119
- | 409 | Conflito (duplicidade) | Email já cadastrado |
120
- | 422 | Validação de negócio falhou | CPF inválido, regra RN-XXX violada |
121
- | 429 | Rate limit excedido | Muitas requisições |
122
- | 500 | Erro interno | Bug não tratado |
123
-
124
- ### Códigos de erro do domínio
125
-
126
- | Código | Descrição | HTTP |
127
- |--------|-----------|------|
128
- | <!-- Ex: DUPLICATE_EMAIL --> | <!-- Email já cadastrado --> | <!-- 409 --> |
129
-
130
- ## Catálogo de Endpoints
131
-
132
- > Atualizado a cada feature via /merge-delta. Visão consolidada de todas as APIs.
133
-
134
- | Método | Rota | Feature | Descrição |
135
- |--------|------|---------|-----------|
136
- | | | | |
137
-
138
- ---
139
-
140
- ## Changelog
141
-
142
- | Data | Feature | Tipo | Descrição |
143
- |------|---------|------|-----------|
144
- | | | | |
1
+ # Convenções de API
2
+
3
+ > Padrões globais para todas as APIs do sistema: versionamento, autenticação, paginação, erros.
4
+
5
+ ---
6
+
7
+ <!--
8
+ =============================================================================
9
+ INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
10
+ =============================================================================
11
+
12
+ ORIGEM: Gerado pelo /setup-projeto a partir do TRD §5.
13
+ ATUALIZAÇÃO: /merge-delta quando features adicionam endpoints (Delta Specs do SDD §5 e §11).
14
+
15
+ COMO GERAR:
16
+ 1. Ler TRD §5 (Convenções de API) — padrão geral, versionamento, autenticação
17
+ 2. Padrão geral e convenções são FIXOS após setup — definidos uma vez
18
+ 3. Catálogo de endpoints é DINÂMICO — cresce a cada feature
19
+ 4. Formatos de paginação, filtro e erro são FIXOS — toda API segue
20
+
21
+ REGRAS:
22
+ - Convenções são LEI — todo SDD §5 (endpoints) deve seguir estes padrões
23
+ - Catálogo de endpoints atualizado a cada merge-delta
24
+ - Mudanças em convenções (raro) devem gerar ADR
25
+ - Rate limiting definido por categoria de endpoint, não individual
26
+
27
+ =============================================================================
28
+ -->
29
+
30
+ ## Padrão Geral
31
+
32
+ | Aspecto | Padrão |
33
+ |---------|--------|
34
+ | Estilo | <!-- REST / GraphQL / gRPC --> |
35
+ | Formato | <!-- JSON / Protobuf --> |
36
+ | Versionamento | <!-- /api/v1/ no path? Header? --> |
37
+ | Autenticação | <!-- Bearer JWT? API Key? --> |
38
+ | Content-Type | <!-- application/json --> |
39
+ | Encoding | <!-- UTF-8 --> |
40
+
41
+ ## Convenções de Rotas
42
+
43
+ | Operação | Método | Rota | Exemplo |
44
+ |----------|--------|------|---------|
45
+ | Listar | GET | `/api/v1/{recurso}` | |
46
+ | Detalhar | GET | `/api/v1/{recurso}/:id` | |
47
+ | Criar | POST | `/api/v1/{recurso}` | |
48
+ | Atualizar completo | PUT | `/api/v1/{recurso}/:id` | |
49
+ | Atualizar parcial | PATCH | `/api/v1/{recurso}/:id` | |
50
+ | Remover/Inativar | DELETE | `/api/v1/{recurso}/:id` | |
51
+
52
+ ### Convenções de nomenclatura
53
+ | Regra | Exemplo |
54
+ |-------|---------|
55
+ | Recursos no plural, kebab-case | `/api/v1/order-items` |
56
+ | Ações não-CRUD como sub-recurso | `/api/v1/users/:id/activate` |
57
+ | Filtros via query params | `/api/v1/users?status=active` |
58
+ | Relações aninhadas (max 2 níveis) | `/api/v1/users/:id/orders` |
59
+
60
+ ## Paginação
61
+
62
+ ```json
63
+ {
64
+ "data": [],
65
+ "meta": {
66
+ "page": 1,
67
+ "per_page": 20,
68
+ "total": 0,
69
+ "total_pages": 0
70
+ }
71
+ }
72
+ ```
73
+
74
+ Query params: `?page=1&per_page=20&sort=campo&order=asc`
75
+
76
+ | Parâmetro | Default | Máximo | Descrição |
77
+ |-----------|---------|--------|-----------|
78
+ | `page` | 1 | — | Página atual |
79
+ | `per_page` | 20 | <!-- Ex: 100 --> | Itens por página |
80
+ | `sort` | — | — | Campo para ordenação |
81
+ | `order` | `asc` | — | `asc` ou `desc` |
82
+
83
+ ## Filtros
84
+
85
+ Query params: `?busca=termo&campo=valor`
86
+
87
+ | Tipo de filtro | Formato | Exemplo |
88
+ |----------------|---------|---------|
89
+ | Igualdade | `?campo=valor` | `?status=ativo` |
90
+ | Busca textual | `?busca=termo` | `?busca=joao` |
91
+ | Range de data | `?de=YYYY-MM-DD&ate=YYYY-MM-DD` | `?de=2026-01-01&ate=2026-12-31` |
92
+ | Múltiplos valores | `?campo=a,b,c` | `?status=ativo,pendente` |
93
+
94
+ ## Respostas de Erro
95
+
96
+ ```json
97
+ {
98
+ "error": {
99
+ "code": "ERROR_CODE",
100
+ "message": "Mensagem legível para o usuário",
101
+ "details": [
102
+ { "field": "campo", "message": "Detalhe do erro" }
103
+ ]
104
+ }
105
+ }
106
+ ```
107
+
108
+ ### Códigos HTTP
109
+
110
+ | Código | Quando usar | Exemplo |
111
+ |--------|-------------|---------|
112
+ | 200 | Sucesso (GET, PUT, PATCH) | Recurso retornado/atualizado |
113
+ | 201 | Criado com sucesso (POST) | Recurso criado, retorna o objeto |
114
+ | 204 | Sucesso sem conteúdo (DELETE) | Recurso removido |
115
+ | 400 | Dados inválidos (formato) | JSON malformado |
116
+ | 401 | Não autenticado | Token ausente ou expirado |
117
+ | 403 | Sem permissão | Papel sem acesso ao recurso |
118
+ | 404 | Recurso não encontrado | ID inexistente |
119
+ | 409 | Conflito (duplicidade) | Email já cadastrado |
120
+ | 422 | Validação de negócio falhou | CPF inválido, regra RN-XXX violada |
121
+ | 429 | Rate limit excedido | Muitas requisições |
122
+ | 500 | Erro interno | Bug não tratado |
123
+
124
+ ### Códigos de erro do domínio
125
+
126
+ | Código | Descrição | HTTP |
127
+ |--------|-----------|------|
128
+ | <!-- Ex: DUPLICATE_EMAIL --> | <!-- Email já cadastrado --> | <!-- 409 --> |
129
+
130
+ ## Catálogo de Endpoints
131
+
132
+ > Atualizado a cada feature via /merge-delta. Visão consolidada de todas as APIs.
133
+
134
+ | Método | Rota | Feature | Descrição |
135
+ |--------|------|---------|-----------|
136
+ | | | | |
137
+
138
+ ---
139
+
140
+ ## Changelog
141
+
142
+ | Data | Feature | Tipo | Descrição |
143
+ |------|---------|------|-----------|
144
+ | | | | |
@@ -1,82 +1,82 @@
1
- # Arquitetura
2
-
3
- > C4 Níveis 2-3 — Containers, componentes, comunicação e padrões adotados.
4
-
5
- ---
6
-
7
- <!--
8
- =============================================================================
9
- INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
10
- =============================================================================
11
-
12
- ORIGEM: Gerado pelo /setup-projeto a partir do TRD §3.
13
- ATUALIZAÇÃO: /merge-delta quando features adicionam containers, componentes significativos ou novos padrões.
14
-
15
- COMO GERAR:
16
- 1. Ler TRD §3 (Arquitetura) — containers, padrões de comunicação, padrões de design
17
- 2. Ler Stack.md — tecnologias já definidas para cada container
18
- 3. Criar diagrama textual C4 Nível 2 (containers e suas conexões)
19
- 4. Para cada container: listar componentes internos (C4 Nível 3)
20
- 5. Documentar padrões de comunicação (sync/async, protocolos)
21
- 6. Documentar padrões de design com justificativa
22
-
23
- REGRAS:
24
- - Diagrama deve mostrar TODOS os containers e suas conexões
25
- - Cada container deve ter: tecnologia, responsabilidade, porta
26
- - Padrões de design precisam de justificativa (não apenas nome)
27
- - Se o sistema usa filas/eventos: documentar tópicos e consumers
28
- - Componentes são internos ao container — não confundir com containers
29
-
30
- =============================================================================
31
- -->
32
-
33
- ## Diagrama de Containers (C4 Nível 2)
34
-
35
- ```
36
- <!-- Representação textual dos containers e suas conexões -->
37
- <!-- Usar formato: [Container] --protocolo--> [Container] -->
38
- ```
39
-
40
- ## Containers
41
-
42
- | Container | Tecnologia | Responsabilidade | Porta | Comunicação |
43
- |-----------|-----------|-----------------|-------|-------------|
44
- | | | | | |
45
-
46
- ## Componentes Principais (C4 Nível 3)
47
-
48
- <!-- Repetir esta seção para cada container que tenha componentes internos relevantes -->
49
-
50
- ### {{Container}}
51
-
52
- | Componente | Responsabilidade | Dependências internas | Dependências externas |
53
- |------------|-----------------|----------------------|----------------------|
54
- | | | | |
55
-
56
- ## Padrões de Comunicação
57
-
58
- ### Síncrona (request/response)
59
-
60
- | De | Para | Protocolo | Formato | Observações |
61
- |----|------|-----------|---------|-------------|
62
- | | | | | |
63
-
64
- ### Assíncrona (eventos/filas)
65
-
66
- | Produtor | Tópico/Fila | Consumer | Formato | Garantia |
67
- |----------|-------------|----------|---------|----------|
68
- | | | | | at-least-once / exactly-once |
69
-
70
- ## Padrões de Design Adotados
71
-
72
- | Padrão | Onde é usado | Justificativa | Ref ADR |
73
- |--------|-------------|---------------|---------|
74
- | | | | |
75
-
76
- ---
77
-
78
- ## Changelog
79
-
80
- | Data | Feature | Tipo | Descrição |
81
- |------|---------|------|-----------|
82
- | | | | |
1
+ # Arquitetura
2
+
3
+ > C4 Níveis 2-3 — Containers, componentes, comunicação e padrões adotados.
4
+
5
+ ---
6
+
7
+ <!--
8
+ =============================================================================
9
+ INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
10
+ =============================================================================
11
+
12
+ ORIGEM: Gerado pelo /setup-projeto a partir do TRD §3.
13
+ ATUALIZAÇÃO: /merge-delta quando features adicionam containers, componentes significativos ou novos padrões.
14
+
15
+ COMO GERAR:
16
+ 1. Ler TRD §3 (Arquitetura) — containers, padrões de comunicação, padrões de design
17
+ 2. Ler Stack.md — tecnologias já definidas para cada container
18
+ 3. Criar diagrama textual C4 Nível 2 (containers e suas conexões)
19
+ 4. Para cada container: listar componentes internos (C4 Nível 3)
20
+ 5. Documentar padrões de comunicação (sync/async, protocolos)
21
+ 6. Documentar padrões de design com justificativa
22
+
23
+ REGRAS:
24
+ - Diagrama deve mostrar TODOS os containers e suas conexões
25
+ - Cada container deve ter: tecnologia, responsabilidade, porta
26
+ - Padrões de design precisam de justificativa (não apenas nome)
27
+ - Se o sistema usa filas/eventos: documentar tópicos e consumers
28
+ - Componentes são internos ao container — não confundir com containers
29
+
30
+ =============================================================================
31
+ -->
32
+
33
+ ## Diagrama de Containers (C4 Nível 2)
34
+
35
+ ```
36
+ <!-- Representação textual dos containers e suas conexões -->
37
+ <!-- Usar formato: [Container] --protocolo--> [Container] -->
38
+ ```
39
+
40
+ ## Containers
41
+
42
+ | Container | Tecnologia | Responsabilidade | Porta | Comunicação |
43
+ |-----------|-----------|-----------------|-------|-------------|
44
+ | | | | | |
45
+
46
+ ## Componentes Principais (C4 Nível 3)
47
+
48
+ <!-- Repetir esta seção para cada container que tenha componentes internos relevantes -->
49
+
50
+ ### {{Container}}
51
+
52
+ | Componente | Responsabilidade | Dependências internas | Dependências externas |
53
+ |------------|-----------------|----------------------|----------------------|
54
+ | | | | |
55
+
56
+ ## Padrões de Comunicação
57
+
58
+ ### Síncrona (request/response)
59
+
60
+ | De | Para | Protocolo | Formato | Observações |
61
+ |----|------|-----------|---------|-------------|
62
+ | | | | | |
63
+
64
+ ### Assíncrona (eventos/filas)
65
+
66
+ | Produtor | Tópico/Fila | Consumer | Formato | Garantia |
67
+ |----------|-------------|----------|---------|----------|
68
+ | | | | | at-least-once / exactly-once |
69
+
70
+ ## Padrões de Design Adotados
71
+
72
+ | Padrão | Onde é usado | Justificativa | Ref ADR |
73
+ |--------|-------------|---------------|---------|
74
+ | | | | |
75
+
76
+ ---
77
+
78
+ ## Changelog
79
+
80
+ | Data | Feature | Tipo | Descrição |
81
+ |------|---------|------|-----------|
82
+ | | | | |
@@ -1,104 +1,104 @@
1
- # Infraestrutura
2
-
3
- > Ambientes, deploy, CI/CD, variáveis de ambiente, domínios e estratégia de rollback.
4
-
5
- ---
6
-
7
- <!--
8
- =============================================================================
9
- INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
10
- =============================================================================
11
-
12
- ORIGEM: Gerado pelo /setup-projeto a partir do TRD §6.
13
- ATUALIZAÇÃO: /merge-delta quando features adicionam variáveis de ambiente, serviços ou mudam infra.
14
-
15
- COMO GERAR:
16
- 1. Ler TRD §6 (Infraestrutura) — ambientes, deploy, CI/CD
17
- 2. Listar TODOS os ambientes com URLs e propósitos
18
- 3. Pipeline CI/CD deve ser concreto (passos reais, não genéricos)
19
- 4. Variáveis de ambiente: NUNCA colocar valores reais (só exemplos)
20
- 5. Estratégia de rollback é OBRIGATÓRIA
21
-
22
- REGRAS:
23
- - Variáveis de ambiente com valores reais NÃO vão pro repositório
24
- - Cada variável precisa de descrição (não só o nome)
25
- - Pipeline CI/CD deve ter passos claros e ferramentas definidas
26
- - Rollback strategy obrigatória — "como voltar se der errado?"
27
- - Novas variáveis adicionadas via merge-delta devem entrar na tabela
28
-
29
- =============================================================================
30
- -->
31
-
32
- ## Ambientes
33
-
34
- | Ambiente | URL | Banco | Propósito | Branch |
35
- |----------|-----|-------|-----------|--------|
36
- | Local | `localhost:{{PORT}}` | local | Desenvolvimento | qualquer |
37
- | Staging | | | Testes e homologação | develop |
38
- | Produção | | | Usuários finais | main |
39
-
40
- ## Deploy
41
-
42
- ### Estratégia
43
-
44
- | Aspecto | Decisão |
45
- |---------|---------|
46
- | Plataforma | <!-- Docker? Serverless? VPS? Cloud provider? --> |
47
- | Orquestração | <!-- Kubernetes? ECS? PM2? --> |
48
- | Build | <!-- Docker multi-stage? Build nativo? --> |
49
- | Estratégia de deploy | <!-- Rolling? Blue-green? Canary? --> |
50
-
51
- ### Pipeline CI/CD
52
-
53
- ```
54
- push → lint → test → build → deploy(staging) → aprovação → deploy(prod)
55
- ```
56
-
57
- | Etapa | Ferramenta | Trigger | Timeout |
58
- |-------|-----------|---------|---------|
59
- | Lint | <!-- eslint, ruff --> | push | |
60
- | Testes | <!-- jest, pytest --> | push | |
61
- | Build | <!-- docker build --> | push em main/develop | |
62
- | Deploy staging | <!-- CD tool --> | push em develop | |
63
- | Deploy produção | <!-- CD tool --> | aprovação manual | |
64
-
65
- ### Rollback
66
-
67
- | Cenário | Procedimento | Responsável |
68
- |---------|-------------|-------------|
69
- | Bug em produção | <!-- Reverter deploy? Hotfix? --> | |
70
- | Migration com erro | <!-- Rollback da migration? --> | |
71
- | Serviço externo fora | <!-- Fallback? Circuit breaker? --> | |
72
-
73
- ## Variáveis de Ambiente
74
-
75
- > NUNCA colocar valores reais aqui. Apenas nomes, descrição e exemplos.
76
-
77
- | Variável | Ambientes | Obrigatória | Descrição | Exemplo |
78
- |----------|-----------|-------------|-----------|---------|
79
- | `DATABASE_URL` | todos | sim | Conexão com banco | `postgres://user:pass@host:5432/db` |
80
- | `JWT_SECRET` | todos | sim | Chave de assinatura JWT | `sua-chave-secreta-aqui` |
81
- | `NODE_ENV` | todos | sim | Ambiente atual | `development` / `production` |
82
-
83
- ## Domínios e DNS
84
-
85
- | Domínio | Aponta para | Certificado | Gerenciado por |
86
- |---------|-------------|-------------|----------------|
87
- | | | <!-- Let's Encrypt? AWS ACM? --> | |
88
-
89
- ## Monitoramento e Observabilidade
90
-
91
- | Aspecto | Ferramenta | O que monitora |
92
- |---------|-----------|----------------|
93
- | Logs | <!-- Ex: CloudWatch, Datadog --> | |
94
- | APM | <!-- Ex: New Relic, Sentry --> | |
95
- | Uptime | <!-- Ex: Pingdom, UptimeRobot --> | |
96
- | Alertas | <!-- Ex: PagerDuty, Slack --> | |
97
-
98
- ---
99
-
100
- ## Changelog
101
-
102
- | Data | Feature | Tipo | Descrição |
103
- |------|---------|------|-----------|
104
- | | | | |
1
+ # Infraestrutura
2
+
3
+ > Ambientes, deploy, CI/CD, variáveis de ambiente, domínios e estratégia de rollback.
4
+
5
+ ---
6
+
7
+ <!--
8
+ =============================================================================
9
+ INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
10
+ =============================================================================
11
+
12
+ ORIGEM: Gerado pelo /setup-projeto a partir do TRD §6.
13
+ ATUALIZAÇÃO: /merge-delta quando features adicionam variáveis de ambiente, serviços ou mudam infra.
14
+
15
+ COMO GERAR:
16
+ 1. Ler TRD §6 (Infraestrutura) — ambientes, deploy, CI/CD
17
+ 2. Listar TODOS os ambientes com URLs e propósitos
18
+ 3. Pipeline CI/CD deve ser concreto (passos reais, não genéricos)
19
+ 4. Variáveis de ambiente: NUNCA colocar valores reais (só exemplos)
20
+ 5. Estratégia de rollback é OBRIGATÓRIA
21
+
22
+ REGRAS:
23
+ - Variáveis de ambiente com valores reais NÃO vão pro repositório
24
+ - Cada variável precisa de descrição (não só o nome)
25
+ - Pipeline CI/CD deve ter passos claros e ferramentas definidas
26
+ - Rollback strategy obrigatória — "como voltar se der errado?"
27
+ - Novas variáveis adicionadas via merge-delta devem entrar na tabela
28
+
29
+ =============================================================================
30
+ -->
31
+
32
+ ## Ambientes
33
+
34
+ | Ambiente | URL | Banco | Propósito | Branch |
35
+ |----------|-----|-------|-----------|--------|
36
+ | Local | `localhost:{{PORT}}` | local | Desenvolvimento | qualquer |
37
+ | Staging | | | Testes e homologação | develop |
38
+ | Produção | | | Usuários finais | main |
39
+
40
+ ## Deploy
41
+
42
+ ### Estratégia
43
+
44
+ | Aspecto | Decisão |
45
+ |---------|---------|
46
+ | Plataforma | <!-- Docker? Serverless? VPS? Cloud provider? --> |
47
+ | Orquestração | <!-- Kubernetes? ECS? PM2? --> |
48
+ | Build | <!-- Docker multi-stage? Build nativo? --> |
49
+ | Estratégia de deploy | <!-- Rolling? Blue-green? Canary? --> |
50
+
51
+ ### Pipeline CI/CD
52
+
53
+ ```
54
+ push → lint → test → build → deploy(staging) → aprovação → deploy(prod)
55
+ ```
56
+
57
+ | Etapa | Ferramenta | Trigger | Timeout |
58
+ |-------|-----------|---------|---------|
59
+ | Lint | <!-- eslint, ruff --> | push | |
60
+ | Testes | <!-- jest, pytest --> | push | |
61
+ | Build | <!-- docker build --> | push em main/develop | |
62
+ | Deploy staging | <!-- CD tool --> | push em develop | |
63
+ | Deploy produção | <!-- CD tool --> | aprovação manual | |
64
+
65
+ ### Rollback
66
+
67
+ | Cenário | Procedimento | Responsável |
68
+ |---------|-------------|-------------|
69
+ | Bug em produção | <!-- Reverter deploy? Hotfix? --> | |
70
+ | Migration com erro | <!-- Rollback da migration? --> | |
71
+ | Serviço externo fora | <!-- Fallback? Circuit breaker? --> | |
72
+
73
+ ## Variáveis de Ambiente
74
+
75
+ > NUNCA colocar valores reais aqui. Apenas nomes, descrição e exemplos.
76
+
77
+ | Variável | Ambientes | Obrigatória | Descrição | Exemplo |
78
+ |----------|-----------|-------------|-----------|---------|
79
+ | `DATABASE_URL` | todos | sim | Conexão com banco | `postgres://user:pass@host:5432/db` |
80
+ | `JWT_SECRET` | todos | sim | Chave de assinatura JWT | `sua-chave-secreta-aqui` |
81
+ | `NODE_ENV` | todos | sim | Ambiente atual | `development` / `production` |
82
+
83
+ ## Domínios e DNS
84
+
85
+ | Domínio | Aponta para | Certificado | Gerenciado por |
86
+ |---------|-------------|-------------|----------------|
87
+ | | | <!-- Let's Encrypt? AWS ACM? --> | |
88
+
89
+ ## Monitoramento e Observabilidade
90
+
91
+ | Aspecto | Ferramenta | O que monitora |
92
+ |---------|-----------|----------------|
93
+ | Logs | <!-- Ex: CloudWatch, Datadog --> | |
94
+ | APM | <!-- Ex: New Relic, Sentry --> | |
95
+ | Uptime | <!-- Ex: Pingdom, UptimeRobot --> | |
96
+ | Alertas | <!-- Ex: PagerDuty, Slack --> | |
97
+
98
+ ---
99
+
100
+ ## Changelog
101
+
102
+ | Data | Feature | Tipo | Descrição |
103
+ |------|---------|------|-----------|
104
+ | | | | |