sdd-flow 2.0.0 → 2.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 +47 -33
- package/README.md +430 -113
- package/README.pt-BR.md +414 -100
- package/bin/cli.js +209 -175
- package/docs/architecture.md +98 -91
- package/docs/formats.md +221 -212
- package/docs/local-testing.pt-BR.md +200 -195
- package/docs/methodology.pt-BR.md +6 -0
- package/docs/migration.md +82 -75
- package/docs/releases.pt-BR.md +108 -186
- package/docs/spec-management.pt-BR.md +169 -0
- package/docs/usage.pt-BR.md +315 -305
- package/docs/validation.md +109 -95
- package/lib/adapters.js +1 -1
- package/lib/catalog.js +162 -0
- package/lib/check.js +25 -9
- package/lib/context.js +139 -117
- package/lib/handoff.js +1 -0
- package/lib/install.js +13 -7
- package/lib/io.js +119 -119
- package/lib/management.js +210 -0
- package/lib/markdown.js +71 -71
- package/lib/project.js +191 -200
- package/lib/verification.js +7 -4
- package/package.json +55 -55
- package/templates/agents/AGENTS.md +66 -54
- package/templates/agents/RULES.md +4 -1
- package/templates/agents/SETUP.md +2 -1
- package/templates/agents/config.yaml +13 -13
- package/templates/agents/prompts/intake.md +23 -23
- package/templates/agents/prompts/rpi-close.md +3 -0
- package/templates/agents/prompts/rpi-implement.md +5 -1
- package/templates/agents/prompts/rpi-plan.md +3 -0
package/docs/usage.pt-BR.md
CHANGED
|
@@ -1,305 +1,315 @@
|
|
|
1
|
-
# Guia de uso do sdd-flow
|
|
2
|
-
|
|
3
|
-
Este guia descreve a evolução 2.x
|
|
4
|
-
|
|
5
|
-
O CLI precisa de Node.js 22+, mas o projeto desenvolvido pode usar outra linguagem ou plataforma.
|
|
6
|
-
|
|
7
|
-
O objetivo é metodológico: organização, contexto pertinente e rastreabilidade. O fluxo não cria um orquestrador.
|
|
8
|
-
Leia methodology.pt-BR.md para a comparação com as versões analisadas e local-testing.pt-BR.md para testar.
|
|
9
|
-
Fases podem ocorrer na mesma conversa; após compactação ou troca de sessão, retome pelos arquivos canônicos.
|
|
10
|
-
|
|
11
|
-
Defina documentation.language: pt-BR em config.yaml para os documentos do aplicativo.
|
|
12
|
-
Preserve português correto e UTF-8. As instruções do método continuam em inglês, sem impor inglês às specs.
|
|
13
|
-
O padrão auto acompanha o idioma do usuário até a escolha da equipe ser registrada no setup.
|
|
14
|
-
|
|
15
|
-
Para qualidade, TDD/BDD e testes sem ambiente real, leia quality-gates.pt-BR.md.
|
|
16
|
-
QUALITY.md é do projeto e só entra automaticamente em plan/validate/close.
|
|
17
|
-
Checks required falhos bloqueiam aprovação; advisory geram avisos. External não executa sem --run-external.
|
|
18
|
-
A ausência de ambiente pode gerar handoff seguro e conclusão limited, com pendências explícitas.
|
|
19
|
-
Isso permite concluir implementação sem afirmar funcionamento externo ou autorizar publicação.
|
|
20
|
-
|
|
21
|
-
## 1. O que o framework controla
|
|
22
|
-
|
|
23
|
-
O sdd-flow organiza intenção, contexto, execução e evidências em arquivos versionáveis.
|
|
24
|
-
O agente interpreta requisitos e implementa; o CLI verifica estrutura, referências, autorização registrada e execução.
|
|
25
|
-
A revisão humana continua responsável por decisões de produto e pela qualidade semântica dos testes.
|
|
26
|
-
|
|
27
|
-
O framework não intercepta mensagens coladas diretamente em qualquer chat, não mede exatamente os tokens de cada modelo
|
|
28
|
-
e não concede permissões nativas às ferramentas. Seus procedimentos orientam o agente; comandos verificam condições objetivas.
|
|
29
|
-
|
|
30
|
-
## 2. Começar do zero ou adotar um projeto existente
|
|
31
|
-
|
|
32
|
-
| Situação | Conduta |
|
|
33
|
-
|---|---|
|
|
34
|
-
| Projeto novo com objetivo pequeno | Configurar o mínimo conhecido e planejar uma primeira entrega verificável |
|
|
35
|
-
| Projeto novo com PRD extenso | Preservar o PRD, mapear capacidades e propor specs coesas com dependências |
|
|
36
|
-
| Aplicação existente sem sdd-flow | Inspecionar código/configurações/testes e registrar uma baseline observada |
|
|
37
|
-
| Aplicação usando sdd-flow 1.x | Atualizar o núcleo com prévia e migrar os artefatos antigos conservadoramente |
|
|
38
|
-
| Correção pequena | Modo light; tarefas e pesquisa podem ser dispensadas |
|
|
39
|
-
| Funcionalidade delimitada | Modo standard, com tarefas por resultado |
|
|
40
|
-
| Mudança ampla ou sensível | Modo rigorous, pesquisa e revisão de impacto explícitas |
|
|
41
|
-
|
|
42
|
-
### Projeto novo
|
|
43
|
-
|
|
44
|
-
Consulte setup-documents.pt-BR.md para perguntas mínimas, papéis dos documentos e presets opcionais.
|
|
45
|
-
sdd init --docs cria os três modelos antigos; sdd docs --types prd,sd,ds,adr,roadmap permite escolher outros.
|
|
46
|
-
Esses rascunhos não substituem o entendimento do agente nem representam decisões aprovadas.
|
|
47
|
-
|
|
48
|
-
Você pode começar com uma descrição do que quer construir. Informe os usuários, o problema, o primeiro
|
|
49
|
-
resultado esperado e restrições conhecidas. PRD, ADR/system design, design system, protótipos e exemplos
|
|
50
|
-
são fontes opcionais; não é necessário produzir todos esses documentos antes do setup.
|
|
51
|
-
O agente registra escolhas conhecidas, propõe decisões materiais em aberto e pede esclarecimentos
|
|
52
|
-
somente quando necessários. Documentos que divergem entre si exigem análise, não escolha silenciosa.
|
|
53
|
-
Preserve as fontes originais. Para PDF/imagens, use o leitor do harness; no contexto do CLI,
|
|
54
|
-
referencie um trecho UTF-8 revisado quando necessário, ligado ao documento de origem.
|
|
55
|
-
|
|
56
|
-
~~~sh
|
|
57
|
-
sdd init --harness claude-code
|
|
58
|
-
# ou: sdd init --harness opencode
|
|
59
|
-
sdd doctor
|
|
60
|
-
~~~
|
|
61
|
-
|
|
62
|
-
Peça ao agente:
|
|
63
|
-
|
|
64
|
-
~~~text
|
|
65
|
-
Leia agents/SETUP.md. Este é um projeto novo. Use os requisitos que forneci,
|
|
66
|
-
registre as decisões autorizadas e proponha a primeira entrega verificável.
|
|
67
|
-
Não invente escolhas de tecnologia quando faltar uma decisão material.
|
|
68
|
-
~~~
|
|
69
|
-
|
|
70
|
-
O setup preenche o mapa em PROJECT.md, as regras particulares em POLICIES.md e os checks reais em config.yaml.
|
|
71
|
-
Cria skills somente para procedimentos recorrentes que já façam sentido. Pode manter perguntas materiais em aberto.
|
|
72
|
-
|
|
73
|
-
### Projeto em desenvolvimento
|
|
74
|
-
|
|
75
|
-
~~~text
|
|
76
|
-
Leia agents/SETUP.md e adote este projeto existente.
|
|
77
|
-
Inspecione a arquitetura e os testes reais. Registre fatos observados e incertezas.
|
|
78
|
-
Não refatore o aplicativo durante a adoção nem crie specs fictícias para todo o passado.
|
|
79
|
-
Depois vamos usar o fluxo na próxima alteração.
|
|
80
|
-
~~~
|
|
81
|
-
|
|
82
|
-
Registre o comportamento relevante em contratos vigentes de capacidade. Não é necessário reconstruir todos os commits antigos.
|
|
83
|
-
Uma inconsistência preexistente vira um achado a avaliar; o setup não autoriza corrigir tudo.
|
|
84
|
-
O levantamento considera manifests, código, contratos de dados/APIs, interface, convenções, testes e documentos.
|
|
85
|
-
Quando esses materiais respondem à questão, o usuário não precisa explicar novamente todo o sistema.
|
|
86
|
-
Se código e documentação discordarem, registre comportamento observado e intenção declarada separadamente;
|
|
87
|
-
o código existente também pode conter um bug. Testes de baseline só devem rodar após conferir ambiente e efeitos.
|
|
88
|
-
A partir daí, cada mudança nova segue o mesmo ciclo de uma aplicação iniciada com o framework.
|
|
89
|
-
|
|
90
|
-
### Análise de impacto e regressões
|
|
91
|
-
|
|
92
|
-
Antes de alterar comportamento compartilhado, examine consumidores, contratos e testes pertinentes.
|
|
93
|
-
Registre na própria SPEC uma nota curta: áreas afetadas, comportamento a preservar, checks de regressão
|
|
94
|
-
e cuidados aplicáveis com dados, migrações, caches ou integrações. Uma alteração isolada pode precisar
|
|
95
|
-
de apenas uma frase; não é necessário criar um documento de impacto para toda tarefa.
|
|
96
|
-
Compare a baseline disponível e execute os testes relevantes dos consumidores depois da mudança.
|
|
97
|
-
Um teste unitário verde da função alterada não basta quando outro módulo depende de seu comportamento.
|
|
98
|
-
Distinga regressões introduzidas, problemas anteriores e falta de acesso. Não mude assertions nem repare
|
|
99
|
-
áreas alheias silenciosamente para obter um relatório verde. Ausência de ambiente segue o handoff limitado.
|
|
100
|
-
|
|
101
|
-
O CLI instala a base e valida registros; é o agente que inspeciona e interpreta o projeto.
|
|
102
|
-
Essa interpretação precisa ser revisada, especialmente em negócios ambíguos, legados sem testes e fontes divergentes.
|
|
103
|
-
|
|
104
|
-
## 3. Da solicitação à entrega
|
|
105
|
-
|
|
106
|
-
~~~mermaid
|
|
107
|
-
flowchart TD
|
|
108
|
-
A["Solicitação"] --> B{"Escopo suficiente?"}
|
|
109
|
-
B -->|"Não"| C["Investigar e recortar"]
|
|
110
|
-
C --> D["Spec e aceitação"]
|
|
111
|
-
B -->|"Sim"| D
|
|
112
|
-
D --> E["Implementar e verificar"]
|
|
113
|
-
E --> F{"Regra mudou?"}
|
|
114
|
-
F -->|"Sim"| G["Revisar impacto e autorização"]
|
|
115
|
-
G --> D
|
|
116
|
-
F -->|"Não"| H["Consolidar e encerrar"]
|
|
117
|
-
~~~
|
|
118
|
-
|
|
119
|
-
~~~sh
|
|
120
|
-
sdd new exportar-dados --mode standard
|
|
121
|
-
sdd context 001-exportar-dados --phase plan
|
|
122
|
-
# O agente preenche requisitos, aceitação e tarefas.
|
|
123
|
-
sdd check 001-exportar-dados
|
|
124
|
-
# Registrar somente autorização realmente dada para esse escopo:
|
|
125
|
-
sdd approve 001-exportar-dados --by "Moisés"
|
|
126
|
-
sdd context 001-exportar-dados --phase implement --task T01
|
|
127
|
-
# Implementar, verificar a tarefa e atualizar seu estado canônico.
|
|
128
|
-
sdd verify 001-exportar-dados --scope partial
|
|
129
|
-
# Consolidar contratos vigentes e concluir as tarefas.
|
|
130
|
-
sdd verify 001-exportar-dados
|
|
131
|
-
sdd close 001-exportar-dados --by "Moisés" --archive
|
|
132
|
-
~~~
|
|
133
|
-
|
|
134
|
-
Se nenhuma capacidade duradoura foi alterada, close exige --note explicando isso.
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
~~~
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
|
200
|
-
|
|
201
|
-
|
|
|
202
|
-
|
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
Use
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
|
278
|
-
|
|
279
|
-
|
|
|
280
|
-
|
|
|
281
|
-
|
|
|
282
|
-
| .
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
1
|
+
# Guia de uso do sdd-flow
|
|
2
|
+
|
|
3
|
+
Este guia descreve a evolução 2.x. Os comandos novos ficam disponíveis ao instalar o pacote 2.x
|
|
4
|
+
(`npm install -g sdd-flow`, ou `sdd-flow@next` enquanto a 2.x não for a tag `latest`) ou este checkout.
|
|
5
|
+
O CLI precisa de Node.js 22+, mas o projeto desenvolvido pode usar outra linguagem ou plataforma.
|
|
6
|
+
|
|
7
|
+
O objetivo é metodológico: organização, contexto pertinente e rastreabilidade. O fluxo não cria um orquestrador.
|
|
8
|
+
Leia methodology.pt-BR.md para a comparação com as versões analisadas e local-testing.pt-BR.md para testar.
|
|
9
|
+
Fases podem ocorrer na mesma conversa; após compactação ou troca de sessão, retome pelos arquivos canônicos.
|
|
10
|
+
|
|
11
|
+
Defina documentation.language: pt-BR em config.yaml para os documentos do aplicativo.
|
|
12
|
+
Preserve português correto e UTF-8. As instruções do método continuam em inglês, sem impor inglês às specs.
|
|
13
|
+
O padrão auto acompanha o idioma do usuário até a escolha da equipe ser registrada no setup.
|
|
14
|
+
|
|
15
|
+
Para qualidade, TDD/BDD e testes sem ambiente real, leia quality-gates.pt-BR.md.
|
|
16
|
+
QUALITY.md é do projeto e só entra automaticamente em plan/validate/close.
|
|
17
|
+
Checks required falhos bloqueiam aprovação; advisory geram avisos. External não executa sem --run-external.
|
|
18
|
+
A ausência de ambiente pode gerar handoff seguro e conclusão limited, com pendências explícitas.
|
|
19
|
+
Isso permite concluir implementação sem afirmar funcionamento externo ou autorizar publicação.
|
|
20
|
+
|
|
21
|
+
## 1. O que o framework controla
|
|
22
|
+
|
|
23
|
+
O sdd-flow organiza intenção, contexto, execução e evidências em arquivos versionáveis.
|
|
24
|
+
O agente interpreta requisitos e implementa; o CLI verifica estrutura, referências, autorização registrada e execução.
|
|
25
|
+
A revisão humana continua responsável por decisões de produto e pela qualidade semântica dos testes.
|
|
26
|
+
|
|
27
|
+
O framework não intercepta mensagens coladas diretamente em qualquer chat, não mede exatamente os tokens de cada modelo
|
|
28
|
+
e não concede permissões nativas às ferramentas. Seus procedimentos orientam o agente; comandos verificam condições objetivas.
|
|
29
|
+
|
|
30
|
+
## 2. Começar do zero ou adotar um projeto existente
|
|
31
|
+
|
|
32
|
+
| Situação | Conduta |
|
|
33
|
+
|---|---|
|
|
34
|
+
| Projeto novo com objetivo pequeno | Configurar o mínimo conhecido e planejar uma primeira entrega verificável |
|
|
35
|
+
| Projeto novo com PRD extenso | Preservar o PRD, mapear capacidades e propor specs coesas com dependências |
|
|
36
|
+
| Aplicação existente sem sdd-flow | Inspecionar código/configurações/testes e registrar uma baseline observada |
|
|
37
|
+
| Aplicação usando sdd-flow 1.x | Atualizar o núcleo com prévia e migrar os artefatos antigos conservadoramente |
|
|
38
|
+
| Correção pequena | Modo light; tarefas e pesquisa podem ser dispensadas |
|
|
39
|
+
| Funcionalidade delimitada | Modo standard, com tarefas por resultado |
|
|
40
|
+
| Mudança ampla ou sensível | Modo rigorous, pesquisa e revisão de impacto explícitas |
|
|
41
|
+
|
|
42
|
+
### Projeto novo
|
|
43
|
+
|
|
44
|
+
Consulte setup-documents.pt-BR.md para perguntas mínimas, papéis dos documentos e presets opcionais.
|
|
45
|
+
sdd init --docs cria os três modelos antigos; sdd docs --types prd,sd,ds,adr,roadmap permite escolher outros.
|
|
46
|
+
Esses rascunhos não substituem o entendimento do agente nem representam decisões aprovadas.
|
|
47
|
+
|
|
48
|
+
Você pode começar com uma descrição do que quer construir. Informe os usuários, o problema, o primeiro
|
|
49
|
+
resultado esperado e restrições conhecidas. PRD, ADR/system design, design system, protótipos e exemplos
|
|
50
|
+
são fontes opcionais; não é necessário produzir todos esses documentos antes do setup.
|
|
51
|
+
O agente registra escolhas conhecidas, propõe decisões materiais em aberto e pede esclarecimentos
|
|
52
|
+
somente quando necessários. Documentos que divergem entre si exigem análise, não escolha silenciosa.
|
|
53
|
+
Preserve as fontes originais. Para PDF/imagens, use o leitor do harness; no contexto do CLI,
|
|
54
|
+
referencie um trecho UTF-8 revisado quando necessário, ligado ao documento de origem.
|
|
55
|
+
|
|
56
|
+
~~~sh
|
|
57
|
+
sdd init --harness claude-code
|
|
58
|
+
# ou: sdd init --harness opencode
|
|
59
|
+
sdd doctor
|
|
60
|
+
~~~
|
|
61
|
+
|
|
62
|
+
Peça ao agente:
|
|
63
|
+
|
|
64
|
+
~~~text
|
|
65
|
+
Leia agents/SETUP.md. Este é um projeto novo. Use os requisitos que forneci,
|
|
66
|
+
registre as decisões autorizadas e proponha a primeira entrega verificável.
|
|
67
|
+
Não invente escolhas de tecnologia quando faltar uma decisão material.
|
|
68
|
+
~~~
|
|
69
|
+
|
|
70
|
+
O setup preenche o mapa em PROJECT.md, as regras particulares em POLICIES.md e os checks reais em config.yaml.
|
|
71
|
+
Cria skills somente para procedimentos recorrentes que já façam sentido. Pode manter perguntas materiais em aberto.
|
|
72
|
+
|
|
73
|
+
### Projeto em desenvolvimento
|
|
74
|
+
|
|
75
|
+
~~~text
|
|
76
|
+
Leia agents/SETUP.md e adote este projeto existente.
|
|
77
|
+
Inspecione a arquitetura e os testes reais. Registre fatos observados e incertezas.
|
|
78
|
+
Não refatore o aplicativo durante a adoção nem crie specs fictícias para todo o passado.
|
|
79
|
+
Depois vamos usar o fluxo na próxima alteração.
|
|
80
|
+
~~~
|
|
81
|
+
|
|
82
|
+
Registre o comportamento relevante em contratos vigentes de capacidade. Não é necessário reconstruir todos os commits antigos.
|
|
83
|
+
Uma inconsistência preexistente vira um achado a avaliar; o setup não autoriza corrigir tudo.
|
|
84
|
+
O levantamento considera manifests, código, contratos de dados/APIs, interface, convenções, testes e documentos.
|
|
85
|
+
Quando esses materiais respondem à questão, o usuário não precisa explicar novamente todo o sistema.
|
|
86
|
+
Se código e documentação discordarem, registre comportamento observado e intenção declarada separadamente;
|
|
87
|
+
o código existente também pode conter um bug. Testes de baseline só devem rodar após conferir ambiente e efeitos.
|
|
88
|
+
A partir daí, cada mudança nova segue o mesmo ciclo de uma aplicação iniciada com o framework.
|
|
89
|
+
|
|
90
|
+
### Análise de impacto e regressões
|
|
91
|
+
|
|
92
|
+
Antes de alterar comportamento compartilhado, examine consumidores, contratos e testes pertinentes.
|
|
93
|
+
Registre na própria SPEC uma nota curta: áreas afetadas, comportamento a preservar, checks de regressão
|
|
94
|
+
e cuidados aplicáveis com dados, migrações, caches ou integrações. Uma alteração isolada pode precisar
|
|
95
|
+
de apenas uma frase; não é necessário criar um documento de impacto para toda tarefa.
|
|
96
|
+
Compare a baseline disponível e execute os testes relevantes dos consumidores depois da mudança.
|
|
97
|
+
Um teste unitário verde da função alterada não basta quando outro módulo depende de seu comportamento.
|
|
98
|
+
Distinga regressões introduzidas, problemas anteriores e falta de acesso. Não mude assertions nem repare
|
|
99
|
+
áreas alheias silenciosamente para obter um relatório verde. Ausência de ambiente segue o handoff limitado.
|
|
100
|
+
|
|
101
|
+
O CLI instala a base e valida registros; é o agente que inspeciona e interpreta o projeto.
|
|
102
|
+
Essa interpretação precisa ser revisada, especialmente em negócios ambíguos, legados sem testes e fontes divergentes.
|
|
103
|
+
|
|
104
|
+
## 3. Da solicitação à entrega
|
|
105
|
+
|
|
106
|
+
~~~mermaid
|
|
107
|
+
flowchart TD
|
|
108
|
+
A["Solicitação"] --> B{"Escopo suficiente?"}
|
|
109
|
+
B -->|"Não"| C["Investigar e recortar"]
|
|
110
|
+
C --> D["Spec e aceitação"]
|
|
111
|
+
B -->|"Sim"| D
|
|
112
|
+
D --> E["Implementar e verificar"]
|
|
113
|
+
E --> F{"Regra mudou?"}
|
|
114
|
+
F -->|"Sim"| G["Revisar impacto e autorização"]
|
|
115
|
+
G --> D
|
|
116
|
+
F -->|"Não"| H["Consolidar e encerrar"]
|
|
117
|
+
~~~
|
|
118
|
+
|
|
119
|
+
~~~sh
|
|
120
|
+
sdd new exportar-dados --mode standard
|
|
121
|
+
sdd context 001-exportar-dados --phase plan
|
|
122
|
+
# O agente preenche requisitos, aceitação e tarefas.
|
|
123
|
+
sdd check 001-exportar-dados
|
|
124
|
+
# Registrar somente autorização realmente dada para esse escopo:
|
|
125
|
+
sdd approve 001-exportar-dados --by "Moisés"
|
|
126
|
+
sdd context 001-exportar-dados --phase implement --task T01
|
|
127
|
+
# Implementar, verificar a tarefa e atualizar seu estado canônico.
|
|
128
|
+
sdd verify 001-exportar-dados --scope partial
|
|
129
|
+
# Consolidar contratos vigentes e concluir as tarefas.
|
|
130
|
+
sdd verify 001-exportar-dados
|
|
131
|
+
sdd close 001-exportar-dados --by "Moisés" --archive
|
|
132
|
+
~~~
|
|
133
|
+
|
|
134
|
+
Se nenhuma capacidade duradoura foi alterada, close exige --note explicando isso.
|
|
135
|
+
O padrão de instalações novas é step: implementar e verificar uma tarefa e parar para revisão.
|
|
136
|
+
Se o usuário autorizar tarefas específicas ou todas as tarefas do escopo, execute esse lote sem parar
|
|
137
|
+
entre elas nem repetir a confirmação; não é necessário alterar config.yaml para esse pedido.
|
|
138
|
+
Aprovar o plano, por si só, não autoriza executar todas as tarefas no modo step.
|
|
139
|
+
Batch também pode ser uma preferência permanente. Atualizações preservam a configuração existente.
|
|
140
|
+
Em ambos os modos, verifique e atualize cada tarefa e respeite suas dependências.
|
|
141
|
+
Pesquisa é opcional quando a informação já é suficiente, exceto em rigorous.
|
|
142
|
+
Validação parcial fornece feedback cedo e nunca encerra a spec.
|
|
143
|
+
|
|
144
|
+
## 4. O limite de contexto
|
|
145
|
+
|
|
146
|
+
O valor padrão é 48.000 bytes do pacote montado pelo comando context.
|
|
147
|
+
Não é um limite para o tamanho total do repositório nem uma conversão exata da janela de tokens de um modelo.
|
|
148
|
+
Um projeto grande pode ter um pacote pequeno quando a seleção é pertinente.
|
|
149
|
+
Vários arquivos pequenos também podem exceder o orçamento quando selecionados juntos.
|
|
150
|
+
|
|
151
|
+
~~~sh
|
|
152
|
+
sdd context 001-exportar-dados --phase implement --inspect
|
|
153
|
+
sdd context 001-exportar-dados --phase implement --task T01 --inspect
|
|
154
|
+
~~~
|
|
155
|
+
|
|
156
|
+
A inspeção mostra tamanho, documentos contribuintes, se o pacote cabe e sugestões, sem incluir seus corpos.
|
|
157
|
+
A inspeção termina normalmente mesmo se o pacote exceder o orçamento; ela é diagnóstica.
|
|
158
|
+
A geração do pacote completo excedido termina com erro CONTEXT_BUDGET_EXCEEDED e código de saída 1.
|
|
159
|
+
Isso não modifica arquivos, não remove requisitos e não reprova a aplicação.
|
|
160
|
+
|
|
161
|
+
O agente deve então:
|
|
162
|
+
1. Selecionar a tarefa correta e as referências pertinentes.
|
|
163
|
+
2. Usar seções explícitas das fontes grandes.
|
|
164
|
+
3. Separar entregas independentes em specs relacionadas, mantendo dependências e contratos compartilhados.
|
|
165
|
+
4. Dividir documentação de referência em assuntos coesos, sem cortar regras ao acaso.
|
|
166
|
+
5. Aumentar o orçamento somente quando houver justificativa e capacidade na ferramenta/modelo utilizado.
|
|
167
|
+
|
|
168
|
+
Exemplo de referência a uma parte do PRD:
|
|
169
|
+
|
|
170
|
+
~~~yaml
|
|
171
|
+
sources:
|
|
172
|
+
- path: docs/prd.md
|
|
173
|
+
section: Exportação de dados
|
|
174
|
+
context:
|
|
175
|
+
- path: docs/contratos.md
|
|
176
|
+
section: Permissões de exportação
|
|
177
|
+
~~~
|
|
178
|
+
|
|
179
|
+
A fonte inteira continua disponível e é considerada na verificação de validade. Só a seção selecionada entra no pacote.
|
|
180
|
+
Um PRD extenso não deve gerar automaticamente uma única spec enorme.
|
|
181
|
+
Também não se deve quebrar uma mudança atômica apenas para atingir um número arbitrário de linhas.
|
|
182
|
+
|
|
183
|
+
Exemplo de pedido ao agente:
|
|
184
|
+
|
|
185
|
+
~~~text
|
|
186
|
+
Antes de implementar este pedido amplo, siga agents/prompts/intake.md.
|
|
187
|
+
Proponha entregas verificáveis e indique quais contratos precisam ser compartilhados.
|
|
188
|
+
Se o pacote de contexto não couber, explique o diagnóstico e proponha o recorte.
|
|
189
|
+
Preserve todas as regras relevantes e as referências ao documento original.
|
|
190
|
+
~~~
|
|
191
|
+
|
|
192
|
+
Existe ainda um limite técnico de leitura de 2 MiB por arquivo no CLI. Fontes maiores precisam de um índice,
|
|
193
|
+
divisão por assunto ou consulta direta por busca antes de formar os artefatos de trabalho.
|
|
194
|
+
O front matter de cada Markdown também tem limite técnico de 64 KiB; mantenha metadados e planos enxutos.
|
|
195
|
+
Nenhum desses controles consegue impedir que uma pessoa cole conteúdo excessivo diretamente no chat.
|
|
196
|
+
|
|
197
|
+
## 5. Onde ficam regras específicas, decisões e skills
|
|
198
|
+
|
|
199
|
+
| Informação | Fonte principal | Carregamento |
|
|
200
|
+
|---|---|---|
|
|
201
|
+
| Regras essenciais e portáveis do processo | RULES.md | Toda mudança |
|
|
202
|
+
| Proibições e obrigações particulares do projeto | POLICIES.md | Toda mudança |
|
|
203
|
+
| Stack, mapa de módulos e fontes das convenções | PROJECT.md | Mapa inicial curto |
|
|
204
|
+
| Comportamento atual e invariantes de uma capacidade | current/ | Quando a capacidade for afetada |
|
|
205
|
+
| Motivo de uma escolha arquitetural | decisions/ | ADR ativo pertinente |
|
|
206
|
+
| Procedimento reutilizável de um domínio/tecnologia | skills/NOME/SKILL.md | Quando pertinente |
|
|
207
|
+
| Padrão verificável automaticamente | Configuração de lint, tipos e testes | Checks configurados |
|
|
208
|
+
|
|
209
|
+
Uma regra como “não tornar públicos os dados institucionais” é obrigatória no projeto e não pode depender
|
|
210
|
+
da seleção opcional de uma skill. Registre-a em POLICIES.md e implemente controles objetivos onde aplicável.
|
|
211
|
+
Um procedimento como “como implementar o acesso a dados neste backend Apps Script” cabe em uma skill.
|
|
212
|
+
A escolha arquitetural e seus motivos pertencem a um ADR; o resumo da stack fica em PROJECT.md.
|
|
213
|
+
Uma regra de negócio de exportação pertence ao contrato da capacidade e à aceitação da mudança.
|
|
214
|
+
|
|
215
|
+
SETUP.md é uma orientação para o agente criar/configurar esses materiais a partir de evidências.
|
|
216
|
+
O CLI não inventa automaticamente skills perfeitas nem ativa toda skill possível.
|
|
217
|
+
Descubra habilidades com sdd skills list e selecione as pertinentes em change.yaml.
|
|
218
|
+
|
|
219
|
+
~~~yaml
|
|
220
|
+
skills: [data-access, export-ui]
|
|
221
|
+
~~~
|
|
222
|
+
|
|
223
|
+
Front matter com name/description permite descoberta estável. O corpo e referências da skill só entram quando necessários.
|
|
224
|
+
Mantenha POLICIES.md curto; detalhes condicionais devem ser referenciados sem inflar o contexto obrigatório.
|
|
225
|
+
|
|
226
|
+
## 6. Regras ou decisões que mudam durante o desenvolvimento
|
|
227
|
+
|
|
228
|
+
### Mudança no escopo ainda ativo
|
|
229
|
+
|
|
230
|
+
1. Registre o motivo e a nova regra no contrato/spec pertinente.
|
|
231
|
+
2. Atualize aceitação e definições das tarefas preservando IDs. Não adapte expectativas apenas para esconder um bug.
|
|
232
|
+
3. Inspecione o impacto e registre a revisão:
|
|
233
|
+
|
|
234
|
+
~~~sh
|
|
235
|
+
sdd revise 001-exportar-dados --by "Moisés" --reason "Novo critério de autorização" --dry-run
|
|
236
|
+
sdd revise 001-exportar-dados --by "Moisés" --reason "Novo critério de autorização"
|
|
237
|
+
sdd approve 001-exportar-dados --by "Moisés"
|
|
238
|
+
~~~
|
|
239
|
+
|
|
240
|
+
A revisão reabre tarefas concluídas/em andamento afetadas e suas dependentes e deixa a aprovação anterior inválida.
|
|
241
|
+
Mudanças de políticas, do corpo normativo ou de referências podem reabrir todas as tarefas conservadoramente.
|
|
242
|
+
O comando compara metadados e ligações; não consegue inferir sozinho todo o impacto semântico. Revise o resultado.
|
|
243
|
+
Depois implemente os ajustes e produza novas evidências. Mudar o código ou o contrato torna o resultado anterior obsoleto.
|
|
244
|
+
|
|
245
|
+
### Mudança de uma decisão arquitetural
|
|
246
|
+
|
|
247
|
+
Crie o ADR substituto, preserve o anterior com status superseded e superseded_by e atualize o mapa/contratos.
|
|
248
|
+
Selecione a decisão ativa nas specs afetadas. Revise o escopo autorizado e os testes pertinentes.
|
|
249
|
+
Não reescreva o passado arquivado para fingir que a nova decisão sempre existiu.
|
|
250
|
+
|
|
251
|
+
### Mudança na configuração do fluxo
|
|
252
|
+
|
|
253
|
+
POLICIES.md, config.yaml e PROJECT.md são do projeto e são preservados por update.
|
|
254
|
+
Alterar regras obrigatórias, checks, exclusões de verificação ou a política de execução invalida aprovações ativas
|
|
255
|
+
que dependam dessa configuração. O orçamento de contexto pode mudar sem alterar a intenção normativa.
|
|
256
|
+
Use revise nas mudanças afetadas; configurações não são congeladas para sempre pelo setup.
|
|
257
|
+
|
|
258
|
+
### Mudança após uma entrega encerrada
|
|
259
|
+
|
|
260
|
+
Prefira uma nova spec relacionada quando existir um novo objetivo.
|
|
261
|
+
Use reopen quando for necessário retomar aquela mesma mudança:
|
|
262
|
+
|
|
263
|
+
~~~sh
|
|
264
|
+
sdd reopen 001-exportar-dados --by "Moisés" --reason "Retomar esta entrega"
|
|
265
|
+
~~~
|
|
266
|
+
|
|
267
|
+
Reabrir remove a evidência corrente de encerramento e exige nova verificação.
|
|
268
|
+
As evidências históricas permanecem. Arquivar conserva IDs; não é necessário carregar todo o arquivo histórico em cada sessão.
|
|
269
|
+
|
|
270
|
+
## 7. Arquivos para rastrear o trabalho
|
|
271
|
+
|
|
272
|
+
Para renomear, renumerar, arquivar, restaurar ou descartar specs, consulte spec-management.pt-BR.md.
|
|
273
|
+
O ID do manifesto é estável e a pasta pode mudar. Status mostra a área ativa; --all inclui registros históricos.
|
|
274
|
+
Related registra proveniência opcional. Depends_on representa pré-requisito real; um histórico ausente não deve forçar refazer a spec.
|
|
275
|
+
Reconcile diagnostica referências ausentes e sincroniza apenas o inventário observado, sem inventar evidência.
|
|
276
|
+
|
|
277
|
+
| Arquivo/conjunto | O que registra |
|
|
278
|
+
|---|---|
|
|
279
|
+
| change.yaml | Identidade, modo, referências, dependências, aprovação atual e estado da mudança |
|
|
280
|
+
| SPEC.md | Requisitos e aceitação; justificativas no corpo |
|
|
281
|
+
| TASK.md | Plano e único estado das tarefas |
|
|
282
|
+
| RESEARCH.md | Pesquisa quando necessária |
|
|
283
|
+
| STATE.md | Ponto de retomada opcional e curto |
|
|
284
|
+
| history/approval-*.json | Cópias dos escopos aprovados e seus responsáveis/data |
|
|
285
|
+
| history/revision-*.json | Motivo e impacto registrado das revisões |
|
|
286
|
+
| history/closure-*.json, history/reopen-*.json, history/cancel-*.json | Eventos correspondentes de ciclo de vida |
|
|
287
|
+
| verification.json | Resultado corrente para os inputs testados |
|
|
288
|
+
| VALIDATION.md | Resumo legível da verificação corrente |
|
|
289
|
+
| runs/ID/receipt.json e logs | Resultado preservado de cada execução |
|
|
290
|
+
| current/ e decisions/ | Conhecimento vigente consolidado e justificativas |
|
|
291
|
+
| archive/ | Mudanças encerradas |
|
|
292
|
+
| .sdd/registry.json | Reserva de identidades, inclusive após arquivamento |
|
|
293
|
+
|
|
294
|
+
Versione os arquivos relevantes no Git e preserve logs/artefatos necessários para reproduzir revisões.
|
|
295
|
+
Backups de manutenção e locks temporários não substituem o histórico de projeto.
|
|
296
|
+
O digest detecta mudança de inputs; não autentica a identidade de um revisor nem prova sozinho que um teste é semanticamente suficiente.
|
|
297
|
+
|
|
298
|
+
## 8. Instalar uma versão nova do framework
|
|
299
|
+
|
|
300
|
+
Publicar no npm e atualizar arquivos copiados nos aplicativos são operações diferentes.
|
|
301
|
+
Para instalar a 2.x publicada (use `sdd-flow@next` se `latest` ainda aponta para a 1.x):
|
|
302
|
+
|
|
303
|
+
~~~sh
|
|
304
|
+
npm install -g sdd-flow
|
|
305
|
+
sdd --version
|
|
306
|
+
cd /caminho/do/aplicativo
|
|
307
|
+
sdd update --dry-run
|
|
308
|
+
sdd update
|
|
309
|
+
sdd doctor
|
|
310
|
+
sdd harness claude-code
|
|
311
|
+
~~~
|
|
312
|
+
|
|
313
|
+
Siga migration.md para specs 1.x. Personalizações de arquivos centrais produzem conflito e são preservadas;
|
|
314
|
+
só use --replace-managed após revisar a prévia e transferir regras do projeto para seus locais apropriados.
|
|
315
|
+
As skills e specs do projeto permanecem sob seu controle.
|