adspecs 0.1.34 → 0.1.36
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/.adspecs/templates/02-/344/272/247/345/223/201/351/234/200/346/261/202/350/257/264/346/230/216/344/271/246/346/250/241/346/235/277.md +784 -626
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/.codebuddy-plugin/plugin.json +1 -1
- package/.qoder-plugin/plugin.json +1 -1
- package/.workbuddy-plugin/plugin.json +1 -1
- package/package.json +1 -1
- package/skills/adspecs-adversarial-review/SKILL.md +1 -1
- package/skills/adspecs-analyze/SKILL.md +564 -574
- package/skills/adspecs-prd/SKILL.md +98 -19
|
@@ -1,574 +1,564 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: "adspecs-analyze"
|
|
3
|
-
description: "对 PRD、系统设计文档（_system-design.md）和 tasks.md
|
|
4
|
-
agent_created: true
|
|
5
|
-
argument-hint: "指定功能名或系统设计文档路径，如 M06-01 或 docs/30-system-design/crm/M06-01-销售预测_system-design.md"
|
|
6
|
-
compatibility: "需要 docs/ 目录体系：docs/20-prd（PRD）+ docs/30-system-design（系统设计+tasks）+
|
|
7
|
-
metadata:
|
|
8
|
-
author: "qingwen"
|
|
9
|
-
source: "基于 adspecs-analyze 通用模板 +
|
|
10
|
-
user-invocable: true
|
|
11
|
-
disable-model-invocation: false
|
|
12
|
-
---
|
|
13
|
-
|
|
14
|
-
## 用户输入
|
|
15
|
-
|
|
16
|
-
```text
|
|
17
|
-
$ARGUMENTS
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
在处理之前**必须**考虑用户输入（若不为空）。用户输入应为功能名称（如 `M06-01`）或系统设计文档路径。若为空则从上下文推导。
|
|
21
|
-
|
|
22
|
-
## 执行前检查
|
|
23
|
-
|
|
24
|
-
**检查扩展钩子（分析前）**：
|
|
25
|
-
|
|
26
|
-
- 检查项目根目录下是否存在 `.adspecs/extensions.yml` 文件。
|
|
27
|
-
- 如果存在，读取该文件并查找 `hooks.before_analyze` 键下的条目。
|
|
28
|
-
- 如果 YAML 无法解析或无效，则静默跳过钩子检查并继续正常流程。
|
|
29
|
-
- 过滤掉 `enabled` 显式为 `false` 的钩子。将没有 `enabled` 字段的钩子默认为启用状态。
|
|
30
|
-
- 对于每个剩余的钩子，**不要**尝试解释或评估钩子的 `condition` 表达式：
|
|
31
|
-
- 如果钩子没有 `condition` 字段，或该字段为 null/空，则视为可执行钩子。
|
|
32
|
-
- 如果钩子定义了非空的 `condition`，则跳过该钩子，将条件评估交由 HookExecutor 实现处理。
|
|
33
|
-
- 从钩子命令名称构建斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如，`adspecs.git.commit` → `/adspecs-git-commit`。
|
|
34
|
-
- 对于每个可执行钩子，根据其 `optional` 标志输出以下内容：
|
|
35
|
-
- **可选钩子**（`optional: true`）：
|
|
36
|
-
|
|
37
|
-
```
|
|
38
|
-
## 扩展钩子
|
|
39
|
-
|
|
40
|
-
**可选前置钩子**：{extension}
|
|
41
|
-
命令：`/{command}`
|
|
42
|
-
描述：{description}
|
|
43
|
-
|
|
44
|
-
提示：{prompt}
|
|
45
|
-
执行方式：`/{command}`
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
- **强制钩子**（`optional: false`）：
|
|
49
|
-
|
|
50
|
-
```
|
|
51
|
-
## 扩展钩子
|
|
52
|
-
|
|
53
|
-
**自动前置钩子**：{extension}
|
|
54
|
-
正在执行：`/{command}`
|
|
55
|
-
EXECUTE_COMMAND: {command}
|
|
56
|
-
|
|
57
|
-
等待钩子命令执行结果后再继续进入目标阶段。
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
- 如果没有注册任何钩子，或 `.adspecs/extensions.yml` 不存在，则静默跳过。
|
|
61
|
-
|
|
62
|
-
## 目标
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
|
69
|
-
|
|
|
70
|
-
| **PRD（需求规格说明书）** | `
|
|
71
|
-
| **系统设计文档**
|
|
72
|
-
| **tasks.md**
|
|
73
|
-
|
|
74
|
-
## 操作约束
|
|
75
|
-
|
|
76
|
-
**严格只读**：**不**修改任何文件。输出结构化的分析报告。提供可选的修复方案（用户必须明确批准后，方可手动调用后续编辑命令）。
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
- §
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
- §
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
- §
|
|
124
|
-
- §
|
|
125
|
-
- §
|
|
126
|
-
- §
|
|
127
|
-
- §
|
|
128
|
-
- §
|
|
129
|
-
- §
|
|
130
|
-
- §
|
|
131
|
-
- §
|
|
132
|
-
- §
|
|
133
|
-
- §
|
|
134
|
-
- §
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
-
|
|
143
|
-
-
|
|
144
|
-
- TDD
|
|
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
|
-
|
|
257
|
-
-
|
|
258
|
-
-
|
|
259
|
-
-
|
|
260
|
-
-
|
|
261
|
-
|
|
262
|
-
####
|
|
263
|
-
|
|
264
|
-
-
|
|
265
|
-
-
|
|
266
|
-
-
|
|
267
|
-
-
|
|
268
|
-
|
|
269
|
-
####
|
|
270
|
-
|
|
271
|
-
- tasks.md
|
|
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
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
-
|
|
312
|
-
-
|
|
313
|
-
-
|
|
314
|
-
-
|
|
315
|
-
|
|
316
|
-
-
|
|
317
|
-
-
|
|
318
|
-
-
|
|
319
|
-
-
|
|
320
|
-
-
|
|
321
|
-
|
|
322
|
-
-
|
|
323
|
-
-
|
|
324
|
-
-
|
|
325
|
-
-
|
|
326
|
-
|
|
327
|
-
-
|
|
328
|
-
-
|
|
329
|
-
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
|
345
|
-
|
|
|
346
|
-
|
|
|
347
|
-
|
|
|
348
|
-
|
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
| US
|
|
355
|
-
|
|
|
356
|
-
|
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
| # |
|
|
363
|
-
| --- |
|
|
364
|
-
| 1 | Entity 规范
|
|
365
|
-
| 2 | DTO 规范
|
|
366
|
-
| 3 | DAO 规范
|
|
367
|
-
| 4 |
|
|
368
|
-
| 5 | Service 规范
|
|
369
|
-
| 6 | Controller 规范
|
|
370
|
-
| 7 | Ro 规范
|
|
371
|
-
| 8 | 异常处理规范
|
|
372
|
-
| 9 | i18n
|
|
373
|
-
| 10 | 注入与工具规范
|
|
374
|
-
|
|
375
|
-
### TDD 健康度评分
|
|
376
|
-
|
|
377
|
-
| 故事阶段 | [TDD] 任务数 | 实现任务数 | 先行率 | 场景覆盖（正常/异常/边界） | 评分 |
|
|
378
|
-
| ------------------ | ------------ | ---------- | ----------- | -------------------------- | :--: |
|
|
379
|
-
| Phase 3 (US-01) | 5 | 8 | ✅ 5/5 先行 | 3/3 全场景 | 🟢 |
|
|
380
|
-
| Phase 4 (US-02) | 4 | 3 | ✅ 4/4 先行 | 3/3 全场景 | 🟢 |
|
|
381
|
-
|
|
|
382
|
-
|
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
| 文件
|
|
391
|
-
|
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
|
408
|
-
|
|
|
409
|
-
|
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
|
421
|
-
|
|
|
422
|
-
|
|
|
423
|
-
|
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
-
|
|
449
|
-
-
|
|
450
|
-
-
|
|
451
|
-
-
|
|
452
|
-
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
|
517
|
-
|
|
|
518
|
-
|
|
|
519
|
-
|
|
|
520
|
-
|
|
|
521
|
-
|
|
|
522
|
-
|
|
|
523
|
-
|
|
|
524
|
-
|
|
|
525
|
-
|
|
|
526
|
-
|
|
|
527
|
-
|
|
|
528
|
-
|
|
|
529
|
-
|
|
|
530
|
-
|
|
|
531
|
-
|
|
|
532
|
-
|
|
|
533
|
-
|
|
|
534
|
-
|
|
|
535
|
-
|
|
|
536
|
-
|
|
|
537
|
-
|
|
|
538
|
-
|
|
|
539
|
-
|
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
-
|
|
559
|
-
-
|
|
560
|
-
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
- **绝不修改文件**（此为只读分析）
|
|
566
|
-
- **绝不虚构缺失的章节**（若缺失，如实报告）
|
|
567
|
-
- **优先处理 ECP 编码规范违规和宪章冲突**（这些始终是 CRITICAL）
|
|
568
|
-
- **使用 ECP 真实示例而非穷举规则**（引用具体 US-ID、Task ID、文件路径）
|
|
569
|
-
- **优雅地报告零问题**（输出带有全链路覆盖统计的成功报告）
|
|
570
|
-
- **三产物联动检测**：不孤立地分析单一文件，始终检查 PRD↔系统设计↔tasks 之间的 ID 追溯一致性
|
|
571
|
-
|
|
572
|
-
## 上下文
|
|
573
|
-
|
|
574
|
-
$ARGUMENTS
|
|
1
|
+
---
|
|
2
|
+
name: "adspecs-analyze"
|
|
3
|
+
description: "对 PRD、系统设计文档（_system-design.md）和 tasks.md 进行非破坏性的全链路一致性分析，项目规范以 docs/40-project_conventions/ 目录为准（由 /project-init 按技术栈生成）。"
|
|
4
|
+
agent_created: true
|
|
5
|
+
argument-hint: "指定功能名或系统设计文档路径，如 M06-01 或 docs/30-system-design/crm/M06-01-销售预测_system-design.md"
|
|
6
|
+
compatibility: "需要 docs/ 目录体系：docs/20-prd（PRD）+ docs/30-system-design（系统设计+tasks）+ docs/40-project_conventions/（项目规范，按技术栈由 /project-init 生成）"
|
|
7
|
+
metadata:
|
|
8
|
+
author: "qingwen"
|
|
9
|
+
source: "基于 adspecs-analyze 通用模板 + 全链路追溯 ID 体系 + 项目规范一致性检测改造"
|
|
10
|
+
user-invocable: true
|
|
11
|
+
disable-model-invocation: false
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 用户输入
|
|
15
|
+
|
|
16
|
+
```text
|
|
17
|
+
$ARGUMENTS
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
在处理之前**必须**考虑用户输入（若不为空）。用户输入应为功能名称（如 `M06-01`）或系统设计文档路径。若为空则从上下文推导。
|
|
21
|
+
|
|
22
|
+
## 执行前检查
|
|
23
|
+
|
|
24
|
+
**检查扩展钩子（分析前）**：
|
|
25
|
+
|
|
26
|
+
- 检查项目根目录下是否存在 `.adspecs/extensions.yml` 文件。
|
|
27
|
+
- 如果存在，读取该文件并查找 `hooks.before_analyze` 键下的条目。
|
|
28
|
+
- 如果 YAML 无法解析或无效，则静默跳过钩子检查并继续正常流程。
|
|
29
|
+
- 过滤掉 `enabled` 显式为 `false` 的钩子。将没有 `enabled` 字段的钩子默认为启用状态。
|
|
30
|
+
- 对于每个剩余的钩子，**不要**尝试解释或评估钩子的 `condition` 表达式：
|
|
31
|
+
- 如果钩子没有 `condition` 字段，或该字段为 null/空，则视为可执行钩子。
|
|
32
|
+
- 如果钩子定义了非空的 `condition`，则跳过该钩子，将条件评估交由 HookExecutor 实现处理。
|
|
33
|
+
- 从钩子命令名称构建斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如，`adspecs.git.commit` → `/adspecs-git-commit`。
|
|
34
|
+
- 对于每个可执行钩子，根据其 `optional` 标志输出以下内容：
|
|
35
|
+
- **可选钩子**（`optional: true`）：
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
## 扩展钩子
|
|
39
|
+
|
|
40
|
+
**可选前置钩子**：{extension}
|
|
41
|
+
命令：`/{command}`
|
|
42
|
+
描述：{description}
|
|
43
|
+
|
|
44
|
+
提示：{prompt}
|
|
45
|
+
执行方式：`/{command}`
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
- **强制钩子**（`optional: false`）：
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
## 扩展钩子
|
|
52
|
+
|
|
53
|
+
**自动前置钩子**：{extension}
|
|
54
|
+
正在执行：`/{command}`
|
|
55
|
+
EXECUTE_COMMAND: {command}
|
|
56
|
+
|
|
57
|
+
等待钩子命令执行结果后再继续进入目标阶段。
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
- 如果没有注册任何钩子，或 `.adspecs/extensions.yml` 不存在，则静默跳过。
|
|
61
|
+
|
|
62
|
+
## 目标
|
|
63
|
+
|
|
64
|
+
在实现之前，识别项目三大核心产物——**PRD（需求规格说明书）**、**系统设计文档（\_system-design.md）**、**tasks.md**——之间的不一致、重复、歧义、欠明确项及**项目规范违反**。此命令**必须**仅在 `/adspecs-tasks` 成功产出完整的 `tasks.md` 之后运行。
|
|
65
|
+
|
|
66
|
+
**产物定位**（实际目录以 `.adspecs/paths.json` 配置为准，默认为 `docs/20-prd` 与 `docs/30-system-design`）：
|
|
67
|
+
|
|
68
|
+
| 产物 | 路径模式 | 负责 Skill | 关键 ID 体系 |
|
|
69
|
+
| --------------------- | ------------------------------------------------------------ | ---------------- | ------------------------------------------------------------- |
|
|
70
|
+
| **PRD（需求规格说明书）** | `{PRD_DIR}/{模块}/` | `/adspecs-prd` | US-###, BR-###, PERM-###（PRD 阶段赋予） |
|
|
71
|
+
| **系统设计文档** | `{DESIGN_DIR}/{模块}/{功能名}_system-design.md` | `/adspecs-plan` | FUNC-###, PERM-###（需求分析阶段 AI 赋予）+ 13 章统一 OOA+OOD |
|
|
72
|
+
| **tasks.md** | `{DESIGN_DIR}/{模块}/{功能名}_tasks.md` | `/adspecs-tasks` | T### 全局任务 ID + `[TDD]` 标记 + `[US#]` 故事标签 |
|
|
73
|
+
|
|
74
|
+
## 操作约束
|
|
75
|
+
|
|
76
|
+
**严格只读**：**不**修改任何文件。输出结构化的分析报告。提供可选的修复方案（用户必须明确批准后，方可手动调用后续编辑命令）。
|
|
77
|
+
|
|
78
|
+
**项目规范权威**：项目编码规范存放于项目根目录 `docs/40-project_conventions/` 下，由 `/project-init` 按所选技术栈生成（不同技术栈规范不同）。后端规范入口为 `docs/40-project_conventions/end-integration/index.md`，其约定在此分析范围内是**不可协商的 MUST 原则**。任何违反项目规范的设计或任务均自动视为 **CRITICAL**。
|
|
79
|
+
|
|
80
|
+
- 若该目录不存在或 `index.md` 缺失，**中止执行**并提示用户先运行 `/project-init` 选择技术栈。
|
|
81
|
+
- 具体基类、注解、命名、响应包装、异常处理、DB 迁移、模块路径规则等内容**以运行时加载的规范文件为准，禁止凭记忆硬编码**。
|
|
82
|
+
- 若规范本身需要更改，必须通过独立的、显式的规范更新流程（如 `/project-init` 的 40-project_conventions 更新检查）完成。
|
|
83
|
+
|
|
84
|
+
## 执行步骤
|
|
85
|
+
|
|
86
|
+
### 1. 定位三产物
|
|
87
|
+
|
|
88
|
+
从 `$ARGUMENTS` 或上下文推导三产物路径（`{PRD_DIR}` / `{DESIGN_DIR}` 以 `.adspecs/paths.json` 为准，默认为 `docs/20-prd` / `docs/30-system-design`）：
|
|
89
|
+
|
|
90
|
+
**方式 A：从 $ARGUMENTS 直接指定**
|
|
91
|
+
|
|
92
|
+
- 若用户提供了功能名（如 `M06-01`）→ 搜索 `{DESIGN_DIR}/{模块}/M06-01*_system-design.md` 和 `{DESIGN_DIR}/{模块}/M06-01*_tasks.md`
|
|
93
|
+
- 若用户提供了完整路径（如 `docs/30-system-design/crm/M06-01-销售预测_system-design.md`）→ 直接使用
|
|
94
|
+
|
|
95
|
+
**方式 B：从上下文推导**
|
|
96
|
+
|
|
97
|
+
- 搜索 `{DESIGN_DIR}/` 下最新修改的 `*_system-design.md`
|
|
98
|
+
- 搜索同目录下对应的 `*_tasks.md`
|
|
99
|
+
- 从系统设计文档 §1.1 定位关联的 PRD 文件路径
|
|
100
|
+
|
|
101
|
+
**必须定位的三文件**：
|
|
102
|
+
|
|
103
|
+
- **PRD**：`{PRD_DIR}/{模块}/` 下的需求规格说明书（含 US-###/BR-###）
|
|
104
|
+
- **SYSTEM_DESIGN**：`{DESIGN_DIR}/{模块}/{功能名}_system-design.md`
|
|
105
|
+
- **TASKS**：`{DESIGN_DIR}/{模块}/{功能名}_tasks.md`
|
|
106
|
+
|
|
107
|
+
若任意文件缺失，则终止并提示用户运行对应的前置命令（如 `/adspecs-plan` 或 `/adspecs-tasks`）。
|
|
108
|
+
|
|
109
|
+
### 2. 加载产物与项目规范（渐进式披露）
|
|
110
|
+
|
|
111
|
+
仅加载每个产物中最低限度的必要上下文。
|
|
112
|
+
|
|
113
|
+
**从 PRD 加载：**
|
|
114
|
+
|
|
115
|
+
- §2.1 用户故事（US-### + 优先级 + 验收场景）
|
|
116
|
+
- §3.2 业务规则（BR-### + 规则简述）
|
|
117
|
+
- §4.1 功能清单（功能编号 → 与系统设计 FUNC-### 关联）
|
|
118
|
+
- §5.1 权限矩阵（权限标识 → 角色 → 与系统设计 §5.4 关联）
|
|
119
|
+
- §6.1 验收标准（归约到 US/BR ID）
|
|
120
|
+
|
|
121
|
+
**从系统设计加载：**
|
|
122
|
+
|
|
123
|
+
- §1.1 需求 ID 映射（4 张表：用户故事映射 / 业务规则映射 / 功能条目映射 / 权限映射）
|
|
124
|
+
- §2.2 实体清单（Entity 完整字段 + 注解要求）
|
|
125
|
+
- §2.3 DTO 清单（DTO 字段 + 校验规则 + 分组）
|
|
126
|
+
- §2.4 Ro 清单（Ro 字段）
|
|
127
|
+
- §3.2 数据库表设计（表的 DDL 约束）
|
|
128
|
+
- §3.3 ORM 映射（DAO 接口 + 映射文件结构）
|
|
129
|
+
- §4.1 业务行为清单（行为 + 触发方 + 前置/后置条件）
|
|
130
|
+
- §4.4 Service 接口设计（方法签名 + 事务边界）
|
|
131
|
+
- §5.1 端点清单（HTTP + 路径 + 请求/响应包装）
|
|
132
|
+
- §5.4 权限矩阵（接口 → 权限要求）
|
|
133
|
+
- §6.1 枚举定义（每个枚举的值 + 编码）
|
|
134
|
+
- §7.1 业务异常清单（消息码 + 触发条件 + 抛出位置）
|
|
135
|
+
- §7.3 消息码汇总（properties 内容）
|
|
136
|
+
- §9 领域事件（发布/消费事件）
|
|
137
|
+
- §10 跨模块依赖（远程调用契约）
|
|
138
|
+
- §13 附录代码结构（文件目录树）
|
|
139
|
+
|
|
140
|
+
**从 tasks.md 加载：**
|
|
141
|
+
|
|
142
|
+
- 文件路径速查表（所有目标文件路径）
|
|
143
|
+
- Phase 结构（阶段号 → 故事/基础设施/收尾）
|
|
144
|
+
- Task ID（T001~TNNN）+ `[P]` 标记 + `[TDD]` 标记 + `[US#]` 标签
|
|
145
|
+
- 每个任务的精确文件路径
|
|
146
|
+
- 项目规范检查清单（逐项确认状态，如有）
|
|
147
|
+
- 依赖关系与执行顺序
|
|
148
|
+
- TDD 执行指南（RED→GREEN→REFACTOR）
|
|
149
|
+
|
|
150
|
+
**从项目规范加载（必选）：**
|
|
151
|
+
|
|
152
|
+
1. 读取 `docs/40-project_conventions/end-integration/index.md`
|
|
153
|
+
2. 按 `index.md` 中"推荐读取顺序"依次加载所有关联规范文件
|
|
154
|
+
3. 重点提取：基类/注解/命名规范、响应包装、异常处理、DB 迁移、i18n、模块结构与路径规则、外部依赖调用方式
|
|
155
|
+
4. 后续所有一致性判断（任务描述中的基类、注解、命名、路径、包装、异常、迁移格式等）均以该规范为准
|
|
156
|
+
5. 如该目录不存在或 `index.md` 缺失，中止执行并提示先运行 `/project-init` 选择技术栈
|
|
157
|
+
|
|
158
|
+
### 3. 构建语义模型
|
|
159
|
+
|
|
160
|
+
创建内部表示（切勿将原始产物包含在输出中）：
|
|
161
|
+
|
|
162
|
+
#### 3.1 全链路 ID 模型
|
|
163
|
+
|
|
164
|
+
从系统设计 §1.1 的 4 张映射表一次性提取所有可追溯 ID：
|
|
165
|
+
|
|
166
|
+
| ID 类型 | 来源 | 含义 | 设计文档映射 | tasks 映射 |
|
|
167
|
+
| ------------ | --------------- | -------- | ------------------------------------------- | -------------------------------- |
|
|
168
|
+
| **US-###** | PRD §2.1 | 用户故事 | 系统设计 §1.1.1 | tasks Phase 3~10 的 `[US#]` 标签 |
|
|
169
|
+
| **BR-###** | PRD §3.2 | 业务规则 | 系统设计 §1.1.2 → §4 Service 方法 → §7 异常 | tasks 中校验/异常相关实现任务 |
|
|
170
|
+
| **FUNC-###** | 系统设计 §1.1.3 | 功能条目 | 系统设计 §5.1 端点 | tasks 中 Controller 端点任务 |
|
|
171
|
+
| **PERM-###** | 系统设计 §1.1.4 | 权限标识 | 系统设计 §5.4 权限矩阵 | tasks 中认证/权限配置任务 |
|
|
172
|
+
|
|
173
|
+
#### 3.2 任务类型模型
|
|
174
|
+
|
|
175
|
+
将 tasks 中的每个任务按类型分类（具体类型集合以运行时加载的项目规范为准，以下为通用参考）：
|
|
176
|
+
|
|
177
|
+
```
|
|
178
|
+
Entity | DTO | Ro | DAO接口 | DAO XML | Service接口 | Service实现 | Controller | 远程客户端 | 枚举 | 消息码常量 | 消费者/监听 | i18n | DB迁移 | 配置类 | 工具类 | 测试
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
#### 3.3 TDD 标记模型
|
|
182
|
+
|
|
183
|
+
提取每个故事阶段内的 `[TDD]` 标记位置和数量：
|
|
184
|
+
|
|
185
|
+
- 每个 `[Story]` 阶段的第一个 `[TDD]` 任务索引
|
|
186
|
+
- `[TDD]` 任务总数 vs 该阶段实现任务总数
|
|
187
|
+
- 场景覆盖（正常 / 异常 / 边界）
|
|
188
|
+
|
|
189
|
+
### 4. 检测扫描（令牌高效分析）
|
|
190
|
+
|
|
191
|
+
聚焦高信号发现。限制最多 50 条发现；超出部分在溢出摘要中汇总。
|
|
192
|
+
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
#### A. 重复检测
|
|
196
|
+
|
|
197
|
+
- 识别 PRD/系统设计/tasks 中近似重复的 US/BR/FUNC 描述
|
|
198
|
+
- 标记表述较差者，建议合并
|
|
199
|
+
|
|
200
|
+
#### B. 歧义检测
|
|
201
|
+
|
|
202
|
+
- 标记缺乏可度量标准的模糊形容词（快速、可扩展、安全、直观、健壮）
|
|
203
|
+
- 标记未解决的占位符（TODO、TKTK、???、`<placeholder>` 等）
|
|
204
|
+
- 标记 PRD 中 "待后续版本补充" 但系统设计仍缺少的设计元素
|
|
205
|
+
|
|
206
|
+
#### C. 欠明确性检测
|
|
207
|
+
|
|
208
|
+
- BR 规则在系统设计 §4 中缺少对应 Service 方法
|
|
209
|
+
- US 故事在 tasks 中缺少完整的 Phase
|
|
210
|
+
- 系统设计实体字段在 tasks Entity 任务中未完整列出
|
|
211
|
+
|
|
212
|
+
#### D. 项目规范一致性
|
|
213
|
+
|
|
214
|
+
> **来源**：`docs/40-project_conventions/` 下运行时加载的项目规范（后端入口 `end-integration/index.md`）。**违反任意一条 MUST 规则 = CRITICAL**。具体基类/注解/命名/格式以加载的规范为准，禁止凭记忆判断。
|
|
215
|
+
|
|
216
|
+
逐条检测 tasks.md 和系统设计 §13 中的文件/描述是否合规：
|
|
217
|
+
|
|
218
|
+
| # | 校验维度 | 检测方式（按加载的项目规范核对） |
|
|
219
|
+
| --- | -------------- | ------------------------------------------------------------ |
|
|
220
|
+
| 1 | Entity 规范 | 基类继承、表名注解、主键策略、审计字段继承是否与规范一致 |
|
|
221
|
+
| 2 | DTO 规范 | 基类继承、校验分组、日期格式注解、消息码格式是否与规范一致 |
|
|
222
|
+
| 3 | DAO 规范 | 基类继承、ORM 映射文件位置、软删除过滤是否与规范一致 |
|
|
223
|
+
| 4 | 数据访问约束 | 任务描述中是否出现规范禁止的数据访问方式 |
|
|
224
|
+
| 5 | Service 规范 | 接口/实现命名、对象转换策略、软删除、分页排序是否与规范一致 |
|
|
225
|
+
| 6 | Controller 规范 | 基类继承、认证注解、标准端点路径、请求/响应包装是否与规范一致 |
|
|
226
|
+
| 7 | Ro（只读视图） | 序列化接口、字段声明方式、日期注解是否与规范一致 |
|
|
227
|
+
| 8 | 异常处理 | 异常抛出位置、消息码枚举使用、禁止硬编码字符串是否与规范一致 |
|
|
228
|
+
| 9 | i18n 规范 | 语言文件数量、命名、内容要求是否与规范一致 |
|
|
229
|
+
| 10 | 注入与工具 | DI 方式、序列化工具、工具类选型、日志框架是否与规范一致 |
|
|
230
|
+
|
|
231
|
+
#### E. 覆盖缺口
|
|
232
|
+
|
|
233
|
+
- 每个 US 故事是否在 tasks 中有对应的 Phase
|
|
234
|
+
- 每个 BR 规则是否在 tasks 中有对应的实现任务
|
|
235
|
+
- 每个 FUNC 功能是否在 tasks 中有对应的 Controller 端点任务
|
|
236
|
+
- 每个 PERM 权限是否在 tasks 中有对应的认证/权限配置任务
|
|
237
|
+
- 系统设计 §10 中每个外部依赖是否在 tasks 中有对应远程调用客户端任务
|
|
238
|
+
- 系统设计 §6.1 中每个枚举是否在 tasks 基础阶段中有独立任务
|
|
239
|
+
- 系统设计 §9.1/§9.2 中每个事件是否在 tasks 中有对应消费者或通知任务
|
|
240
|
+
- 系统设计 §12 中每个测试场景是否有对应的 `[TDD]` 任务
|
|
241
|
+
|
|
242
|
+
#### F. 不一致性
|
|
243
|
+
|
|
244
|
+
- 术语漂移（同一概念在不同文件中命名不一致）
|
|
245
|
+
- 消息码不匹配（系统设计 §7.3 定义的码 vs tasks 中引用的码）
|
|
246
|
+
- 文件路径漂移（系统设计 §13 目录树 vs tasks 文件路径速查表）
|
|
247
|
+
- 用户故事优先级漂移（PRD P1/P2 vs tasks Phase 排列顺序）
|
|
248
|
+
- 行为数量不一致（系统设计 §4.1 定义的行为数 vs tasks 中对应 Service 方法数量）
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
#### G. 项目规范语义一致性（新增）
|
|
253
|
+
|
|
254
|
+
> 此维度在 D 基础上做更细粒度的语义检查，全部以运行时加载的项目规范为唯一依据。
|
|
255
|
+
|
|
256
|
+
- 任务描述中的基类/父类拼写是否正确（按规范核对，勿凭记忆）
|
|
257
|
+
- Entity 任务是否声明"审计字段继承不重复"（如规范要求）
|
|
258
|
+
- ORM 映射任务是否声明 `resultMap` 含全字段+审计（如规范要求）
|
|
259
|
+
- Service 任务是否区分新增/修改的对象转换策略（按规范要求的工具）
|
|
260
|
+
- 任务描述中是否使用了规范禁止的数据访问 API 或工具
|
|
261
|
+
|
|
262
|
+
#### H. TDD 顺序一致性（新增）
|
|
263
|
+
|
|
264
|
+
- 每个 `[US#]` Phase 内，第一个任务是否带有 `[TDD]` 标记
|
|
265
|
+
- 每个故事内是否存在无对应 `[TDD]` 测试的实现任务
|
|
266
|
+
- 是否存在 `[TDD]` 任务位于实现任务**之后**的情况（违反 TDD 铁律）
|
|
267
|
+
- `[TDD]` 任务粒度：是否为每个 Service 方法的正常/异常/边界场景都配置了测试任务（对照系统设计 §12 的三个测试场景表）
|
|
268
|
+
|
|
269
|
+
#### I. i18n 覆盖完整性（新增）
|
|
270
|
+
|
|
271
|
+
- tasks.md 收尾阶段是否包含**规范要求数量**的 i18n 文件任务（具体数量/语言/命名以规范为准）
|
|
272
|
+
- 语言覆盖：是否包含规范要求的所有语言（如 default / zh_CN / en_US ...）
|
|
273
|
+
- 消息码覆盖：系统设计 §7.3 中的消息码是否在至少 1 个 i18n 文件任务中提到
|
|
274
|
+
- 文件命名格式：是否符合规范约定的命名规则
|
|
275
|
+
|
|
276
|
+
#### J. 模块路径精度（新增）
|
|
277
|
+
|
|
278
|
+
- tasks.md 中每个文件路径是否遵循规范定义的模块/分层目录结构
|
|
279
|
+
- 文件所在模块是否与其类型匹配（以规范为准，如 Entity→数据层、DTO→契约层、Service/Controller→实现层、i18n→资源目录等）
|
|
280
|
+
- 路径格式完整（含规范要求的包路径）
|
|
281
|
+
|
|
282
|
+
#### K. 外部依赖映射完整性（新增）
|
|
283
|
+
|
|
284
|
+
- 系统设计 §10 列出 N 个外部依赖 → tasks 中是否有 N 个对应远程调用客户端任务（Feign Client / HTTP Client 等，以规范为准）
|
|
285
|
+
- 每个客户端任务的文件路径是否为规范指定的目录
|
|
286
|
+
- 客户端接口路径/方法签名是否与系统设计 §10 中的契约一致
|
|
287
|
+
|
|
288
|
+
#### L. DB 迁移覆盖完整性（新增）
|
|
289
|
+
|
|
290
|
+
- 系统设计 §3.2 定义 N 张表 → tasks 中 DB 迁移 DDL 是否覆盖全部表
|
|
291
|
+
- 索引覆盖：系统设计 §3.2 定义的所有索引是否在 DDL 中
|
|
292
|
+
- 迁移文件结构是否完整（changelog/迁移入口/DDL 文件名等以规范为准）
|
|
293
|
+
|
|
294
|
+
#### M. 专项任务类型覆盖（新增）
|
|
295
|
+
|
|
296
|
+
- 枚举类数量：系统设计 §6.1 定义 N 个枚举 → tasks 基础阶段是否有 N 个枚举任务
|
|
297
|
+
- 消息码常量：系统设计 §7 定义消息码 → tasks 是否有对应消息码常量任务（如规范要求）
|
|
298
|
+
- 消费者/监听：系统设计 §9 定义的消费事件 → tasks 是否有对应消费者任务
|
|
299
|
+
- 配置类：系统设计 §8 缓存策略/并发控制等 → tasks 是否有对应配置任务
|
|
300
|
+
- 工具类：系统设计 §4 引用的工具类 → tasks 是否有对应工具类任务
|
|
301
|
+
|
|
302
|
+
---
|
|
303
|
+
|
|
304
|
+
### 5. 严重级别分配
|
|
305
|
+
|
|
306
|
+
使用以下启发式规则对发现进行优先级排序：
|
|
307
|
+
|
|
308
|
+
- **CRITICAL**：
|
|
309
|
+
- 违反项目规范任一条 MUST 规则（以 `docs/40-project_conventions/` 加载的规范为准）
|
|
310
|
+
- 核心产物缺失（PRD/系统设计/tasks 三缺一）
|
|
311
|
+
- US 故事零覆盖（tasks 中无对应 Phase）
|
|
312
|
+
- 所有端点缺失认证/权限注解（按规范要求的认证机制）
|
|
313
|
+
- i18n 文件任务数 ≠ 规范要求数量
|
|
314
|
+
- 违反 TDD 铁律（实现任务在 `[TDD]` 测试之前）
|
|
315
|
+
- **HIGH**：
|
|
316
|
+
- BR 业务规则在 tasks 中无对应实现
|
|
317
|
+
- 系统设计 §10 外部依赖在 tasks 中无对应远程调用客户端
|
|
318
|
+
- 消息码不匹配（不同文件中同一概念码不同）
|
|
319
|
+
- 校验字段消息码格式错误（非规范约定格式）
|
|
320
|
+
- 文件路径模块归属错误
|
|
321
|
+
- **MEDIUM**：
|
|
322
|
+
- 术语漂移（同一概念在不同文件中命名不一致）
|
|
323
|
+
- 单个枚举漏覆盖（如 6/7 通过）
|
|
324
|
+
- 测试场景覆盖不完整（只覆盖正常场景，缺异常/边界）
|
|
325
|
+
- 欠明确的边界情况
|
|
326
|
+
- **LOW**：
|
|
327
|
+
- 风格/措辞改进（任务描述可更精确）
|
|
328
|
+
- 不影响执行顺序的轻微冗余
|
|
329
|
+
- 非关键的命名不一致
|
|
330
|
+
|
|
331
|
+
### 6. 生成一致性分析报告
|
|
332
|
+
|
|
333
|
+
输出 Markdown 报告（不写文件），结构如下：
|
|
334
|
+
|
|
335
|
+
---
|
|
336
|
+
|
|
337
|
+
## 全链路一致性分析报告
|
|
338
|
+
|
|
339
|
+
### 分析概要
|
|
340
|
+
|
|
341
|
+
| 指标 | 数值 |
|
|
342
|
+
| ------------- | ---------------- |
|
|
343
|
+
| 分析功能 | [功能名称] |
|
|
344
|
+
| PRD 路径 | [PRD 文件路径] |
|
|
345
|
+
| 系统设计路径 | [设计文档路径] |
|
|
346
|
+
| tasks.md 路径 | [tasks 文件路径] |
|
|
347
|
+
| 项目规范来源 | [规范文件路径] |
|
|
348
|
+
| 分析时间 | [时间戳] |
|
|
349
|
+
|
|
350
|
+
### 全链路追溯矩阵
|
|
351
|
+
|
|
352
|
+
| US ID | 优先级 | BR ID | FUNC ID | PERM ID | Task Phase | Task IDs | 覆盖状态 |
|
|
353
|
+
| ----- | ------ | ----------------- | --------------- | --------------- | ---------- | --------- | :------: |
|
|
354
|
+
| US-01 | P1 | BR-01,BR-02,BR-14 | FUNC-03,FUNC-05 | PERM-01,PERM-02 | Phase 3 | T022~T034 | ✅ |
|
|
355
|
+
| US-02 | P1 | — | FUNC-11,FUNC-12 | PERM-07,PERM-08 | Phase 4 | T035~T041 | ✅ |
|
|
356
|
+
| ... | ... | ... | ... | ... | ... | ... | ... |
|
|
357
|
+
|
|
358
|
+
### 项目规范合规检查
|
|
359
|
+
|
|
360
|
+
> 依据 `docs/40-project_conventions/` 下加载的规范逐项核对。
|
|
361
|
+
|
|
362
|
+
| # | 规范维度 | 检测结果 | 发现 |
|
|
363
|
+
| --- | --------------- | :------: | ---------- |
|
|
364
|
+
| 1 | Entity 规范 | ✅ / ❌ | [具体发现] |
|
|
365
|
+
| 2 | DTO 规范 | ✅ / ❌ | [具体发现] |
|
|
366
|
+
| 3 | DAO 规范 | ✅ / ❌ | [具体发现] |
|
|
367
|
+
| 4 | 数据访问约束 | ✅ / ❌ | [具体发现] |
|
|
368
|
+
| 5 | Service 规范 | ✅ / ❌ | [具体发现] |
|
|
369
|
+
| 6 | Controller 规范 | ✅ / ❌ | [具体发现] |
|
|
370
|
+
| 7 | Ro 规范 | ✅ / ❌ | [具体发现] |
|
|
371
|
+
| 8 | 异常处理规范 | ✅ / ❌ | [具体发现] |
|
|
372
|
+
| 9 | i18n 规范 | ✅ / ❌ | [具体发现] |
|
|
373
|
+
| 10 | 注入与工具规范 | ✅ / ❌ | [具体发现] |
|
|
374
|
+
|
|
375
|
+
### TDD 健康度评分
|
|
376
|
+
|
|
377
|
+
| 故事阶段 | [TDD] 任务数 | 实现任务数 | 先行率 | 场景覆盖（正常/异常/边界） | 评分 |
|
|
378
|
+
| ------------------ | ------------ | ---------- | ----------- | -------------------------- | :--: |
|
|
379
|
+
| Phase 3 (US-01) | 5 | 8 | ✅ 5/5 先行 | 3/3 全场景 | 🟢 |
|
|
380
|
+
| Phase 4 (US-02) | 4 | 3 | ✅ 4/4 先行 | 3/3 全场景 | 🟢 |
|
|
381
|
+
| ... | ... | ... | ... | ... | ... |
|
|
382
|
+
| **全局** | **23** | **33** | **100%** | **85%** | 🟢 |
|
|
383
|
+
|
|
384
|
+
### 文件路径校验表
|
|
385
|
+
|
|
386
|
+
| 文件 | 期望模块（按规范） | 实际路径模块 | 归属正确？ |
|
|
387
|
+
| ------------------------- | ------------------ | ------------ | :--------: |
|
|
388
|
+
| [Entity 文件].java | [数据层模块] | [数据层模块] | ✅ |
|
|
389
|
+
| [DTO 文件].java | [契约层模块] | [契约层模块] | ✅ |
|
|
390
|
+
| [Service 文件].java | [实现层模块] | [实现层模块] | ✅ |
|
|
391
|
+
| ... | ... | ... | ... |
|
|
392
|
+
|
|
393
|
+
### 发现清单
|
|
394
|
+
|
|
395
|
+
| ID | 类别 | 严重级别 | 位置 | 摘要 | 修复建议 |
|
|
396
|
+
| --- | ------- | -------- | ------------- | ---- | -------- |
|
|
397
|
+
| G1 | 规范违反 | CRITICAL | tasks.md:Lxxx | ... | ... |
|
|
398
|
+
| H2 | TDD顺序 | CRITICAL | tasks.md:Lxxx | ... | ... |
|
|
399
|
+
| ... | ... | ... | ... | ... | ... |
|
|
400
|
+
|
|
401
|
+
**覆盖摘要表：**
|
|
402
|
+
|
|
403
|
+
| 需求标识 | 类型 | 是否有任务？ | Task IDs | 备注 |
|
|
404
|
+
| -------- | -------- | :----------: | --------- | --------------------------- |
|
|
405
|
+
| US-01 | 用户故事 | ✅ | T022~T034 | Phase 3 |
|
|
406
|
+
| BR-01 | 业务规则 | ✅ | T032 | Service.submitForecastOrder |
|
|
407
|
+
| FUNC-03 | 功能条目 | ✅ | T032,T033 | Controller.save+Service |
|
|
408
|
+
| PERM-01 | 权限 | ✅ | T033 | 认证/权限配置 |
|
|
409
|
+
| ... | ... | ... | ... | ... |
|
|
410
|
+
|
|
411
|
+
**外部依赖映射表：**
|
|
412
|
+
|
|
413
|
+
| 外部依赖（系统设计 §10） | 客户端任务 | 模块 | 路径正确？ |
|
|
414
|
+
| ------------------------ | ------------- | ---- | :--------: |
|
|
415
|
+
| [依赖名称] | [客户端任务] | [模块] | ✅ |
|
|
416
|
+
| ... | ... | ... | ... |
|
|
417
|
+
|
|
418
|
+
**i18n 覆盖表：**
|
|
419
|
+
|
|
420
|
+
| 语言文件（按规范） | 任务 ID | 消息码覆盖数 |
|
|
421
|
+
| ------------------ | ------- | ------------ |
|
|
422
|
+
| [语言文件 1] | T084 | 19/19 ✅ |
|
|
423
|
+
| ... | ... | ... |
|
|
424
|
+
|
|
425
|
+
**未映射任务：**（若有）
|
|
426
|
+
|
|
427
|
+
**指标汇总：**
|
|
428
|
+
|
|
429
|
+
- 用户故事总数：10
|
|
430
|
+
- 业务规则总数：14
|
|
431
|
+
- 功能条目总数：21
|
|
432
|
+
- 权限标识总数：13
|
|
433
|
+
- 任务总数：95
|
|
434
|
+
- 全链路覆盖率：XX%（至少关联 1 个任务的需求占比）
|
|
435
|
+
- 歧义数量：X
|
|
436
|
+
- 重复数量：X
|
|
437
|
+
- CRITICAL 问题数量：X
|
|
438
|
+
- 项目规范违规数量：X
|
|
439
|
+
- TDD 先行率：XX%
|
|
440
|
+
- i18n 覆盖完整性：X/规范要求数
|
|
441
|
+
|
|
442
|
+
---
|
|
443
|
+
|
|
444
|
+
### 7. 提供后续行动
|
|
445
|
+
|
|
446
|
+
在报告末尾输出简洁的后续行动块：
|
|
447
|
+
|
|
448
|
+
- 若存在 **CRITICAL** 问题：建议在 `/adspecs-implement` 或 `/adspecs-tasks` 迭代之前解决。禁止进入实现阶段。
|
|
449
|
+
- 若存在 **HIGH** 问题：强烈建议在实现前修复，否则可能存在功能缺失。
|
|
450
|
+
- 若仅有 **LOW/MEDIUM**：用户可以继续实现，但提供改进建议。
|
|
451
|
+
- 提供明确的命令建议：
|
|
452
|
+
- "运行 `/adspecs-tasks` 重新生成 tasks.md 以修复覆盖缺口"
|
|
453
|
+
- "运行 `/adspecs-clarify` 澄清欠明确的 PRD 条目"
|
|
454
|
+
- "手动编辑 tasks.md 添加缺失的 `[TDD]` 测试任务"
|
|
455
|
+
- "手动编辑系统设计文档修正消息码不一致"
|
|
456
|
+
|
|
457
|
+
### 8. 提供修复方案
|
|
458
|
+
|
|
459
|
+
询问用户："是否需要我为前 N 个问题提供具体的修复编辑建议？"（切勿自动应用修复。）
|
|
460
|
+
|
|
461
|
+
### 9. 检查扩展钩子
|
|
462
|
+
|
|
463
|
+
在报告之后，检查项目根目录下是否存在 `.adspecs/extensions.yml` 文件。
|
|
464
|
+
|
|
465
|
+
- 如果存在，读取该文件并查找 `hooks.after_analyze` 键下的条目。
|
|
466
|
+
- 如果 YAML 无法解析或无效，则静默跳过钩子检查并继续正常流程。
|
|
467
|
+
- 过滤掉 `enabled` 显式为 `false` 的钩子。将没有 `enabled` 字段的钩子默认为启用状态。
|
|
468
|
+
- 对于每个剩余的钩子，**不要**尝试解释或评估钩子的 `condition` 表达式：
|
|
469
|
+
- 如果钩子没有 `condition` 字段，或该字段为 null/空，则视为可执行钩子。
|
|
470
|
+
- 如果钩子定义了非空的 `condition`，则跳过该钩子，将条件评估交由 HookExecutor 实现处理。
|
|
471
|
+
- 从钩子命令名称构建斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如，`adspecs.git.commit` → `/adspecs-git-commit`。
|
|
472
|
+
- 对于每个可执行钩子，根据其 `optional` 标志输出以下内容：
|
|
473
|
+
- **可选钩子**（`optional: true`）：
|
|
474
|
+
|
|
475
|
+
```
|
|
476
|
+
## 扩展钩子
|
|
477
|
+
|
|
478
|
+
**可选钩子**：{extension}
|
|
479
|
+
命令：`/{command}`
|
|
480
|
+
描述：{description}
|
|
481
|
+
|
|
482
|
+
提示：{prompt}
|
|
483
|
+
执行方式：`/{command}`
|
|
484
|
+
```
|
|
485
|
+
|
|
486
|
+
- **强制钩子**（`optional: false`）：
|
|
487
|
+
|
|
488
|
+
```
|
|
489
|
+
## 扩展钩子
|
|
490
|
+
|
|
491
|
+
**自动钩子**：{extension}
|
|
492
|
+
正在执行：`/{command}`
|
|
493
|
+
EXECUTE_COMMAND: {command}
|
|
494
|
+
```
|
|
495
|
+
|
|
496
|
+
- 如果没有注册任何钩子，或 `.adspecs/extensions.yml` 不存在，则静默跳过。
|
|
497
|
+
|
|
498
|
+
---
|
|
499
|
+
|
|
500
|
+
## 项目规范专项检测规则速查表
|
|
501
|
+
|
|
502
|
+
> 以下 G~M 维度是执行步骤 §4（检测扫描）的具体检测条款。每条规则对应一个 ID 前缀，出现在报告"发现清单"的 ID 列中。
|
|
503
|
+
> **所有具体类名、注解、文件名、数量、路径均以 `docs/40-project_conventions/` 下运行时加载的规范为准，下表仅描述通用检测意图。**
|
|
504
|
+
|
|
505
|
+
| ID 前缀 | 检测维度 | 检测规则（按项目规范核对） |
|
|
506
|
+
| ------- | -------------- | ----------------------------------------------------------------------------------- |
|
|
507
|
+
| G | **编码规范** | Entity/DTO/DAO/Service/Controller/Ro 描述中的基类/接口/注解是否正确（10 条逐条检查） |
|
|
508
|
+
| G1 | 编码规范 | Entity: 基类继承、表名注解、主键策略、审计字段（按规范） |
|
|
509
|
+
| G2 | 编码规范 | DTO: 基类继承、校验分组、日期格式注解、消息码格式（按规范） |
|
|
510
|
+
| G3 | 编码规范 | DAO: 基类继承、映射文件位置、软删除过滤（按规范） |
|
|
511
|
+
| G4 | 编码规范 | 任务描述中无规范禁止的数据访问 API/工具字样 |
|
|
512
|
+
| G5 | 编码规范 | Service: 接口/实现命名、对象转换策略、分页排序（按规范） |
|
|
513
|
+
| G6 | 编码规范 | Controller: 基类继承、认证注解、标准端点路径、响应包装（按规范） |
|
|
514
|
+
| G7 | 编码规范 | Ro: 序列化接口、字段声明方式、日期注解（按规范） |
|
|
515
|
+
| G8 | 编码规范 | 异常: Service 层抛出、消息码枚举、禁止硬编码字符串（按规范） |
|
|
516
|
+
| G9 | 编码规范 | i18n: 语言文件数量、命名、内容要求（按规范） |
|
|
517
|
+
| G10 | 编码规范 | 注入: DI 方式、序列化工具、工具类选型、日志框架（按规范） |
|
|
518
|
+
| H | **TDD 顺序** | 每个故事 Phase 内 `[TDD]` 任务必须在所有实现任务之前 |
|
|
519
|
+
| H1 | TDD 顺序 | 第一个实现任务之前至少存在 1 个 `[TDD]` 任务 |
|
|
520
|
+
| H2 | TDD 顺序 | 不存在实现任务在前、`[TDD]` 在后的排序错误 |
|
|
521
|
+
| H3 | TDD 顺序 | `[TDD]` 任务覆盖正常/异常/边界三场景（对照系统设计 §12） |
|
|
522
|
+
| I | **i18n 覆盖** | 规范要求的语言文件完整 |
|
|
523
|
+
| I1 | i18n 覆盖 | tasks 中 i18n 文件任务数 = 规范要求数量 |
|
|
524
|
+
| I2 | i18n 覆盖 | 系统设计 §7.3 中每个消息码在至少 1 个 i18n 任务中被覆盖 |
|
|
525
|
+
| J | **模块路径** | 文件路径遵循规范定义的模块/分层结构，归属正确 |
|
|
526
|
+
| J1 | 模块路径 | 各类型文件不在错误模块（按规范分层归属） |
|
|
527
|
+
| J2 | 模块路径 | 路径格式完整（含规范要求的包路径） |
|
|
528
|
+
| K | **外部依赖** | 系统设计 §10 外部依赖 → tasks 中远程调用客户端一一对应（按规范） |
|
|
529
|
+
| K1 | 外部依赖 | 依赖数量 = 客户端任务数量 |
|
|
530
|
+
| K2 | 外部依赖 | 客户端文件路径在规范指定目录下 |
|
|
531
|
+
| L | **DB 迁移** | 系统设计 §3.2 每张表 → DDL/迁移脚本中有完整建表语句 |
|
|
532
|
+
| L1 | DB 迁移 | 表数量匹配（系统设计 §2.2 实体数 = 迁移中表数） |
|
|
533
|
+
| L2 | DB 迁移 | 索引数量匹配（系统设计 §2.2 索引数 = 迁移中索引数） |
|
|
534
|
+
| L3 | DB 迁移 | 迁移文件结构完整（changelog/入口/DDL 文件名按规范） |
|
|
535
|
+
| M | **专项任务** | 枚举/消息码/消费者/配置/工具类任务数匹配系统设计 |
|
|
536
|
+
| M1 | 专项任务 | 枚举数 = 系统设计 §6.1 中枚举数量 |
|
|
537
|
+
| M2 | 专项任务 | 消费者数 = 系统设计 §9.2 中消费事件数量 |
|
|
538
|
+
| M3 | 专项任务 | 配置类覆盖：系统设计 §8 引用的缓存/并发等配置 |
|
|
539
|
+
| M4 | 专项任务 | 工具类覆盖：系统设计 §4 引用的所有工具类 |
|
|
540
|
+
|
|
541
|
+
---
|
|
542
|
+
|
|
543
|
+
## 操作原则
|
|
544
|
+
|
|
545
|
+
### 上下文效率
|
|
546
|
+
|
|
547
|
+
- **最少高信号令牌**：聚焦可操作的发现，而非详尽的文档
|
|
548
|
+
- **渐进式披露**：增量加载产物；不要将所有内容倾泻到分析中
|
|
549
|
+
- **令牌高效输出**：发现表最多 50 行；汇总溢出部分
|
|
550
|
+
- **确定性结果**：无更改重新运行应产生一致的 ID 和计数
|
|
551
|
+
|
|
552
|
+
### 分析准则
|
|
553
|
+
|
|
554
|
+
- **绝不修改文件**（此为只读分析）
|
|
555
|
+
- **绝不虚构缺失的章节**（若缺失，如实报告）
|
|
556
|
+
- **优先处理项目规范违规**（以 `docs/40-project_conventions/` 加载的规范为准，这些始终是 CRITICAL）
|
|
557
|
+
- **规范核对以运行时加载为准**：任务描述中的基类、注解、命名、路径等判断，一律对照规范文件原文，禁止凭记忆硬编码
|
|
558
|
+
- **使用真实示例而非穷举规则**（引用具体 US-ID、Task ID、文件路径）
|
|
559
|
+
- **优雅地报告零问题**（输出带有全链路覆盖统计的成功报告）
|
|
560
|
+
- **三产物联动检测**：不孤立地分析单一文件，始终检查 PRD↔系统设计↔tasks 之间的 ID 追溯一致性
|
|
561
|
+
|
|
562
|
+
## 上下文
|
|
563
|
+
|
|
564
|
+
$ARGUMENTS
|