6aspec 2.0.0-dev.9 → 3.0.0-dev.2

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 (96) hide show
  1. package/.6aspec/rules/biz/code.md +122 -28
  2. package/.6aspec/rules/biz/code_implementation_sop.md +77 -0
  3. package/.6aspec/rules/brown/brown_analyze_sop.md +289 -0
  4. package/.6aspec/rules/brown/brown_archive_sop.md +43 -78
  5. package/.6aspec/rules/brown/brown_constitution.md +11 -0
  6. package/.6aspec/rules/brown/brown_continue_sop.md +6 -13
  7. package/.6aspec/rules/brown/brown_design_sop.md +210 -95
  8. package/.6aspec/rules/brown/brown_explore_sop.md +314 -0
  9. package/.6aspec/rules/brown/brown_ff_sop.md +27 -64
  10. package/.6aspec/rules/brown/brown_impact_sop.md +101 -45
  11. package/.6aspec/rules/brown/brown_implement_sop.md +90 -58
  12. package/.6aspec/rules/brown/brown_list_sop.md +12 -12
  13. package/.6aspec/rules/brown/brown_new_sop.md +56 -77
  14. package/.6aspec/rules/brown/brown_proposal_sop.md +243 -76
  15. package/.6aspec/rules/brown/brown_quick_sop.md +5 -5
  16. package/.6aspec/rules/brown/brown_review_sop.md +4 -4
  17. package/.6aspec/rules/brown/brown_rollback_sop.md +27 -45
  18. package/.6aspec/rules/brown/brown_specs_sop.md +364 -120
  19. package/.6aspec/rules/brown/brown_status_sop.md +16 -32
  20. package/.6aspec/rules/brown/brown_tasks_sop.md +205 -87
  21. package/.6aspec/rules/brown/brown_understand_sop.md +97 -23
  22. package/.6aspec/rules/brown/brown_update_sop.md +283 -0
  23. package/.6aspec/rules/brown/brown_verify_sop.md +71 -309
  24. package/.6aspec/rules/brown/subagents/implementer.md +68 -0
  25. package/.6aspec/rules/brown/subagents/spec-compliance-reviewer.md +65 -0
  26. package/.6aspec/rules/green/{6A_archive_sop.md → green_archive_sop.md} +3 -3
  27. package/.6aspec/rules/green/{6A_clarify_sop.md → green_clarify_sop.md} +1 -1
  28. package/.6aspec/rules/green/{6A_code_implementation_sop.md → green_code_implementation_sop.md} +18 -3
  29. package/.6aspec/rules/green/{6A_continue_sop.md → green_continue_sop.md} +3 -3
  30. package/.6aspec/rules/green/{6A_new_sop.md → green_new_sop.md} +90 -11
  31. package/.6aspec/rules/green/green_status_schema.md +4 -4
  32. package/.6aspec/rules/green/{6A_status_sop.md → green_status_sop.md} +3 -3
  33. package/.6aspec/rules/green/{6A_tasks_sop.md → green_tasks_sop.md} +1 -1
  34. package/.claude/agents/implementer.md +6 -0
  35. package/.claude/agents/spec-compliance-reviewer.md +6 -0
  36. package/.claude/commands/6aspec/brown/analyze.md +11 -0
  37. package/.claude/commands/6aspec/brown/archive.md +11 -11
  38. package/.claude/commands/6aspec/brown/continue.md +11 -11
  39. package/.claude/commands/6aspec/brown/design.md +11 -11
  40. package/.claude/commands/6aspec/brown/explore.md +11 -0
  41. package/.claude/commands/6aspec/brown/ff.md +11 -11
  42. package/.claude/commands/6aspec/brown/impact.md +11 -11
  43. package/.claude/commands/6aspec/brown/implement.md +11 -11
  44. package/.claude/commands/6aspec/brown/list.md +11 -11
  45. package/.claude/commands/6aspec/brown/new.md +11 -11
  46. package/.claude/commands/6aspec/brown/proposal.md +11 -11
  47. package/.claude/commands/6aspec/brown/quick.md +11 -11
  48. package/.claude/commands/6aspec/brown/review.md +11 -11
  49. package/.claude/commands/6aspec/brown/status.md +11 -11
  50. package/.claude/commands/6aspec/brown/tasks.md +11 -11
  51. package/.claude/commands/6aspec/brown/understand.md +11 -11
  52. package/.claude/commands/6aspec/brown/update.md +11 -0
  53. package/.claude/commands/6aspec/brown/verify.md +11 -11
  54. package/.claude/commands/6aspec/code.md +10 -0
  55. package/.claude/commands/6aspec/green/archive.md +1 -1
  56. package/.claude/commands/6aspec/green/clarify.md +2 -2
  57. package/.claude/commands/6aspec/green/continue.md +1 -1
  58. package/.claude/commands/6aspec/green/design.md +2 -2
  59. package/.claude/commands/6aspec/green/{execute-task.md → implement.md} +1 -1
  60. package/.claude/commands/6aspec/green/import-model-table.md +1 -1
  61. package/.claude/commands/6aspec/green/init.md +2 -2
  62. package/.claude/commands/6aspec/green/model.md +2 -2
  63. package/.claude/commands/6aspec/green/new.md +2 -2
  64. package/.claude/commands/6aspec/green/rollback.md +1 -1
  65. package/.claude/commands/6aspec/green/status.md +1 -1
  66. package/.claude/commands/6aspec/green/tasks.md +2 -2
  67. package/.claude/commands/6aspec/green/visual-logic.md +2 -2
  68. package/.claude/settings.local.json +21 -1
  69. package/.cursor/commands/6aspec/brown/explore.md +11 -0
  70. package/.cursor/commands/6aspec/brown/update.md +9 -0
  71. package/.cursor/commands/6aspec/code.md +8 -0
  72. package/.cursor/commands/6aspec/green/archive.md +1 -1
  73. package/.cursor/commands/6aspec/green/clarify.md +2 -2
  74. package/.cursor/commands/6aspec/green/continue.md +1 -1
  75. package/.cursor/commands/6aspec/green/design.md +2 -2
  76. package/.cursor/commands/6aspec/green/{execute-task.md → implement.md} +1 -1
  77. package/.cursor/commands/6aspec/green/import-model-table.md +1 -1
  78. package/.cursor/commands/6aspec/green/init.md +2 -2
  79. package/.cursor/commands/6aspec/green/model.md +2 -2
  80. package/.cursor/commands/6aspec/green/new.md +2 -2
  81. package/.cursor/commands/6aspec/green/rollback.md +1 -1
  82. package/.cursor/commands/6aspec/green/status.md +1 -1
  83. package/.cursor/commands/6aspec/green/tasks.md +2 -2
  84. package/.cursor/commands/6aspec/green/visual-logic.md +2 -2
  85. package/README.md +1 -1
  86. package/lib/cli.js +2 -2
  87. package/lib/installer.js +19 -2
  88. package/package.json +1 -1
  89. /package/.6aspec/rules/green/{6A_constitution.md → green_constitution.md} +0 -0
  90. /package/.6aspec/rules/green/{6A_design_sop.md → green_design_sop.md} +0 -0
  91. /package/.6aspec/rules/green/{6A_import_model_table_sop.md → green_import_model_table_sop.md} +0 -0
  92. /package/.6aspec/rules/green/{6A_init_event_list_sop.md → green_init_event_list_sop.md} +0 -0
  93. /package/.6aspec/rules/green/{6A_init_map_sop.md → green_init_map_sop.md} +0 -0
  94. /package/.6aspec/rules/green/{6A_model_sop.md → green_model_sop.md} +0 -0
  95. /package/.6aspec/rules/green/{6A_rollback_sop.md → green_rollback_sop.md} +0 -0
  96. /package/.6aspec/rules/green/{6A_visual_logic_sop.md → green_visual_logic_sop.md} +0 -0
@@ -4,129 +4,94 @@
4
4
 
5
5
  **输入**:`/6aspec:brown:archive` 后可选需求名称。
6
6
 
7
- **步骤**
7
+ ---
8
+
9
+ ## 步骤
8
10
 
9
11
  1. **选择需求并检查状态**
10
12
 
11
13
  - 读取 `6aspecdoc/brown/<name>/status.json`
12
- - 确认 `phases.review` 为 "done"
13
- - 如果未完成 Phase 7,询问是否强制归档
14
+ - 根据流程深度检查前置条件:
15
+ - **轻量级流程**:确认 `phases.implement` 为 "done"
16
+ - **标准级流程**:确认 `phases.implement` 为 "done"
17
+ - 如果未满足前置条件,警告用户并询问是否强制归档
14
18
 
15
19
  2. **确认归档**
16
20
 
17
21
  询问用户确认:
18
22
  ```
19
- 问题:"确认归档需求 <name>?归档后需求将移至归档目录。"
20
- 选项:
23
+ 确认归档需求 <name>?归档后需求将移至归档目录,操作不可逆。
21
24
  - 是,归档此需求
22
25
  - 否,取消归档
23
26
  ```
24
27
 
25
28
  3. **执行归档操作**
26
29
 
27
- a. **创建归档目录**
28
- ```bash
29
- mkdir -p 6aspecdoc/brown/.archived/<timestamp>-<name>
30
- ```
30
+ a. 创建归档目录:`6aspecdoc/brown/.archived/<timestamp>-<name>/`
31
31
 
32
- b. **移动需求目录**
33
- ```bash
34
- mv 6aspecdoc/brown/<name> 6aspecdoc/brown/.archived/<timestamp>-<name>/
35
- ```
32
+ b. 将 `6aspecdoc/brown/<name>/` 整体移入归档目录
36
33
 
37
- c. **更新归档状态**
38
- 在归档目录中创建 `archive-info.json`:
34
+ c. 在归档目录中创建 `archive-info.json`:
39
35
  ```json
40
36
  {
41
37
  "name": "<name>",
38
+ "flowDepth": "<flowDepth>",
42
39
  "archivedAt": "<timestamp>",
43
- "archivedBy": "6aspec:brown",
44
- "originalPath": "6aspecdoc/brown/<name>",
45
- "archivePath": "6aspecdoc/brown/.archived/<timestamp>-<name>",
46
- "completedPhases": 7,
47
- "totalTasks": 8,
48
- "priority": "P0/P1/P2"
40
+ "completedPhases": ["analyze", "specs", "design", "tasks", "implement"],
41
+ "tasks": {
42
+ "total": <N>,
43
+ "completed": <N>
44
+ }
49
45
  }
50
46
  ```
51
47
 
52
48
  4. **生成归档摘要**
53
49
 
54
50
  创建 `6aspecdoc/brown/.archived/<timestamp>-<name>/ARCHIVE-SUMMARY.md`:
51
+
55
52
  ```markdown
56
53
  # 归档摘要:<name>
57
54
 
58
- > **归档时间**: <timestamp>
59
- > **优先级**: P0/P1/P2
60
- > **完成阶段**: 7/7
61
- > **总任务数**: 8
62
- > **总工时**: <工时>
55
+ **归档时间**:<timestamp>
56
+ **流程深度**:轻量级 / 标准级 / 完整级
57
+ **任务完成**:<N>/<N>
63
58
 
64
59
  ## 需求概述
65
60
 
66
- <从 requirement.md 提取>
67
-
68
- ## 关键成果
69
-
70
- - 数据库变更:<数量> 个表
71
- - 代码变更:<数量> 个类
72
- - 前端变更:<数量> 个页面
73
- - 测试用例:<数量> 个
61
+ <从 proposal.md 或 analysis.md 提取需求描述>
74
62
 
75
63
  ## 关键文档
76
64
 
77
- - 01-understanding.md - 需求理解与现状分析
78
- - 02-impact-analysis.md - 影响面分析
79
- - 03-technical-design.md - 技术方案设计
80
- - 04-tasks-overview.md - 任务拆解
81
- - 05-verification-report.md - 验证报告
82
- - 06-post-implementation-review.md - 实施后评估
83
- - ADR-<name>.md - 架构决策记录(P0)
65
+ - proposal.md 需求提案
66
+ - analysis.md 需求分析(如果存在)
67
+ - specs.md 需求规格
68
+ - design.md 技术方案
69
+ - tasks-overview.md 任务拆解
70
+ - verification-report.md 验证报告(如果存在)
71
+ - review.md 实施后评估(如果存在)
84
72
 
85
73
  ## 经验教训
86
74
 
87
- <从 06-post-implementation-review.md 提取>
88
-
89
- ## 可复用方案
90
-
91
- <从 06-post-implementation-review.md 提取>
92
-
93
- ## 归档位置
94
-
95
- 6aspecdoc/brown/.archived/<timestamp>-<name>/
75
+ <从 review.md 提取(如果存在),否则省略此节>
96
76
  ```
97
77
 
98
- **输出**
78
+ ---
79
+
80
+ ## 输出
99
81
 
100
82
  ```
101
83
  ## 需求已归档:<name>
102
84
 
103
- **归档时间**: <timestamp>
104
- **归档位置**: 6aspecdoc/brown/.archived/<timestamp>-<name>/
105
-
106
- ### 需求统计
107
- - 优先级:P0/P1/P2
108
- - 完成阶段:7/7
109
- - 总任务数:8
110
- - 总工时:<工时>
111
-
112
- ### 关键成果
113
- <列出关键成果>
114
-
115
- ### 归档文件
116
- 所有需求文档已移至归档目录,包括:
117
- - 分析文档(Phase 1-4)
118
- - 验证报告(Phase 6)
119
- - 实施后评估(Phase 7)
120
- - 任务详情
121
- - 归档摘要
122
-
123
- ### 查看归档
124
- 可以随时查看归档的需求文档:
125
- 6aspecdoc/brown/.archived/<timestamp>-<name>/
85
+ **归档时间**:<timestamp>
86
+ **归档位置**:6aspecdoc/brown/.archived/<timestamp>-<name>/
87
+ **任务完成**:<N>/<N>
126
88
  ```
127
89
 
128
- **防护措施**
129
- - 如果未完成所有阶段,警告用户并询问是否强制归档
130
- - 归档前必须确认
90
+ ---
91
+
92
+ ## 防护措施
93
+
94
+ - 根据流程深度检查不同的前置条件
95
+ - 未满足前置条件时警告用户,询问是否强制归档
96
+ - 归档前必须用户确认
131
97
  - 归档操作不可逆(除非手动恢复)
132
- - 保留完整的归档信息和摘要
@@ -6,6 +6,17 @@
6
6
 
7
7
  **所有生成的文档内容必须使用中文**,包括标题、字段名、描述等所有文本内容。
8
8
 
9
+ ## 时间格式规范
10
+
11
+ **所有时间戳必须使用东八区(北京时间)格式**:`yyyy-MM-dd HH:mm:ss`
12
+
13
+ 示例:`2026-02-20 12:36:23`
14
+
15
+ 适用范围:
16
+ - status.json 中的 `createdAt`、`lastModified`、`completedAt` 等字段
17
+ - 所有 artifacts 文档中的时间戳(创建时间、完成时间、评估时间等)
18
+ - 归档时使用的时间戳
19
+
9
20
  ## 核心行为规则
10
21
 
11
22
  1. **阶段化推进**:每个阶段完成后必须停止,等待用户通过显式命令推进
@@ -30,7 +30,7 @@
30
30
  **如果所有阶段都完成 (`phases` 全部为 "done")**:
31
31
  - 祝贺用户
32
32
  - 显示最终状态
33
- - 建议:"所有阶段已完成!可以运行 `/6aspec:brown:implement` 开始实施,或运行 `/6aspec:brown:archive` 归档。"
33
+ - 提示:"所有阶段已完成!可以运行 `/6aspec:brown:verify` 进行质量检查(可选),或运行 `/6aspec:brown:archive` 归档。"
34
34
  - 停止
35
35
 
36
36
  **如果有待执行的阶段**:
@@ -39,27 +39,20 @@
39
39
 
40
40
  **轻量级流程(lightweight)**:
41
41
  - `proposal` → 调用 `/6aspec:brown:proposal`
42
- - `design` → 调用 `/6aspec:brown:design`
43
- - `tasks` → 调用 `/6aspec:brown:tasks`
44
- - `implement` → 调用 `/6aspec:brown:implement`
45
-
46
- **标准级流程(standard)**:
47
- - `understand` → 调用 `/6aspec:brown:understand`
48
42
  - `specs` → 调用 `/6aspec:brown:specs`
49
- - `impact` → 调用 `/6aspec:brown:impact`
50
43
  - `design` → 调用 `/6aspec:brown:design`
51
44
  - `tasks` → 调用 `/6aspec:brown:tasks`
52
45
  - `implement` → 调用 `/6aspec:brown:implement`
46
+ - 如果 implement 已完成且无待执行阶段 → 提示:"所有阶段已完成!可以运行 `/6aspec:brown:verify` 进行质量检查(可选),或运行 `/6aspec:brown:archive` 归档。"
53
47
 
54
- **完整级流程(complete)**:
55
- - `understand` → 调用 `/6aspec:brown:understand`
48
+ **标准级流程(standard)**:
49
+ - `analyze` → 调用 `/6aspec:brown:analyze`
50
+ - `proposal` → 调用 `/6aspec:brown:proposal`
56
51
  - `specs` → 调用 `/6aspec:brown:specs`
57
- - `impact` → 调用 `/6aspec:brown:impact`
58
52
  - `design` → 调用 `/6aspec:brown:design`
59
53
  - `tasks` → 调用 `/6aspec:brown:tasks`
60
54
  - `implement` → 调用 `/6aspec:brown:implement`
61
- - `verify`调用 `/6aspec:brown:verify`
62
- - `review` → 调用 `/6aspec:brown:review`
55
+ - 如果 implement 已完成且无待执行阶段 提示:"所有阶段已完成!可以运行 `/6aspec:brown:verify` 进行质量检查(可选),或运行 `/6aspec:brown:archive` 归档。"
63
56
 
64
57
  **如果所有阶段都被阻塞**:
65
58
  - 这不应该发生
@@ -1,155 +1,270 @@
1
1
  # 棕地需求 - Design SOP
2
2
 
3
- Phase 3: 技术方案设计
3
+ 技术方案设计(Design)- 适用于所有流程级别
4
+
5
+ > **阶段定位**:Design 的目标是输出"可评审的技术蓝图",聚焦模块划分、服务边界、数据模型、接口/入口规范、集成方案与迁移/兼容策略。
6
+ > - ✅ 写:架构与模块边界、关键决策(可含 ADR)、数据语义与演进策略、接口/入口规范(含幂等/并发/异常语义)、集成点与失败边界、迁移/兼容/灰度/回滚策略、风险清单(含缓解措施)、验证矩阵(测试分类与测试方式,断言值见 Specs)。
7
+ > - ❌ 不写:代码片段/伪代码/注解、前端逐字段交互表、API 具体出入参字段清单(放 Tasks)、存量表改动的全量 DDL(放 Tasks)。类名/方法名可以出现(用于定位),但不写其实现逻辑。
8
+ > - ✅ 例外:**若新增数据库表**,Design 必须给出 DDL(用于评审关键约束与整体形态)。
9
+ > - **影响粒度**:Design 描述到**类/方法级**(哪个 Service、哪个 Job、哪个 Factory 受影响);行级精确定位留给 Tasks 阶段。
10
+ > - **格式自由**:各章节用表格还是分节散文,由内容复杂度决定,不强制统一格式。
4
11
 
5
12
  **输入**:`/6aspec:brown:design` 后可选需求名称。
6
13
 
7
- **步骤**
14
+ ---
15
+
16
+ ## 步骤
8
17
 
9
18
  1. **选择需求并检查状态**
10
19
 
11
20
  - 读取 `6aspecdoc/brown/<name>/status.json`
12
- - 确认 `phases.impact` 为 "done"
13
- - 如果未完成 Phase 2,提示先运行 `/6aspec:brown:impact`
21
+ - 检查前置阶段:确认 `phases.specs` 为 "done";如未完成,提示先运行 `/6aspec:brown:specs`
14
22
 
15
23
  2. **读取前置文档**
16
24
 
17
- - `6aspecdoc/brown/<name>/requirement.md`
18
- - `6aspecdoc/brown/<name>/artifacts/01-understanding.md`
19
- - `6aspecdoc/brown/<name>/artifacts/01.5-specs.md`(标准级/完整级)
20
- - `6aspecdoc/brown/<name>/artifacts/02-impact-analysis.md`
25
+ 根据 `flowDepth` 读取不同的前置文档:
21
26
 
22
- 3. **设计数据库变更方案**
27
+ **轻量级流程**:
28
+ - `6aspecdoc/brown/<name>/artifacts/proposal.md`
29
+ - `6aspecdoc/brown/<name>/artifacts/specs.md`
30
+ - `6aspecdoc/brown/<name>/explore-summary.md`(如果存在)
23
31
 
24
- - 字段名、类型、约束
25
- - 默认值和历史数据处理
26
- - 索引建议
27
- - 数据迁移脚本(如需要)
32
+ **标准级/完整级流程**:
33
+ - `6aspecdoc/brown/<name>/artifacts/proposal.md`
34
+ - `6aspecdoc/brown/<name>/artifacts/specs.md`
35
+ - `6aspecdoc/brown/<name>/artifacts/analysis.md`
28
36
 
29
- 4. **设计代码实现方案**
37
+ 3. **补充探索代码库(按需,轻量)**
30
38
 
31
- - 实体类字段添加(含注解)
32
- - 业务逻辑实现(含关键代码示例)
33
- - 校验逻辑(必填、值域、约束)
34
- - 错误提示(使用多语言资源)
39
+ analyze 阶段已完成主要的代码探索,analysis.md 中已有现有系统结构分析。Design 阶段只在以下情况补充查阅:
40
+ - 需要了解 analysis.md 未覆盖的**具体实现细节**(如某个 Job 的分页策略、事务边界)
41
+ - 需要参考**现有类似实现**来决定技术方案(如其他定时任务的幂等方案)
42
+ - 用户明确要求补充探索
35
43
 
36
- 5. **设计前端 UI 方案**
44
+ 探索结果直接用于方案设计,不生成独立文档。轻量级流程无 analysis.md,按需探索现有架构模式与集成点。
37
45
 
38
- - 各页面字段状态(可编辑/只读/隐藏)
39
- - 交互逻辑(下拉选择、提示信息)
40
- - 错误提示
41
- - 多语言支持
46
+ 4. **设计技术方案**
42
47
 
43
- 6. **设计测试方案**
48
+ 基于前置文档和补充探索,先判断本次需求的核心复杂度在哪里(数据模型?入口逻辑?集成方案?),从最关键的维度开始设计,其他维度跟随。按需取舍(无关的维度直接省略):
44
49
 
45
- - 单元测试(函数级别)
46
- - 集成测试(流程级别)
47
- - 数据一致性验证(SQL 验证)
50
+ > **多路径决策**:当某个维度存在多种可行的实现路径时(如同步 vs 异步、加字段 vs 加表、事务边界选择等),先列出选项并说明选择理由,再展开该维度的详细设计。
48
51
 
49
- 7. **架构决策记录(P0 需求必须)**
52
+ **模块划分**:列出本次变更涉及的模块/子系统,明确每个模块的职责边界(1-3 条)和模块间依赖关系。
50
53
 
51
- 如果是 P0 级需求,创建 ADR:
54
+ **服务边界**:明确数据所有权(source of truth)、状态流转责任、事件发布/消费关系、失败边界与业务表现。
52
55
 
53
- 创建 `6aspecdoc/brown/<name>/artifacts/ADR-<name>.md`:
54
- ```markdown
55
- # ADR: <决策标题>
56
+ **接口/入口规范**:将 Specs 的触发类型映射为技术入口,只设计本需求实际存在的入口类型。
56
57
 
57
- **状态**: 提议中 / 已接受
58
- **日期**: <timestamp>
59
- **需求**: <name>
58
+ Specs 触发类型 技术入口映射:
60
59
 
61
- ## 背景
62
- <为什么需要做这个决策>
60
+ | Specs 触发类型 | Design 技术入口 |
61
+ |---|---|
62
+ | 用户操作 | REST API(Command API) |
63
+ | 外部系统触发 | REST API(Command API,对外暴露) |
64
+ | 事件订阅 | Event Subscribers |
65
+ | 定时任务 | Scheduled Tasks |
63
66
 
64
- ## 决策
65
- <我们决定采用什么方案>
67
+ > 后台任务(@Async)不是独立触发类型,在对应入口的执行逻辑中说明即可。
66
68
 
67
- ## 备选方案
69
+ 每个入口必须覆盖以下维度(格式自由):
70
+ - **执行逻辑**:步骤级,到类/方法级,不写代码
71
+ - **幂等设计**:如何防止重复执行
72
+ - **并发控制**:是否需要加锁,锁的粒度
73
+ - **边界与异常**:失败如何处理,是否影响其他数据
74
+ - **性能考虑**:批量大小、超时、瓶颈
75
+ - **补偿/重试**:失败后是否重试(REST API 无此项)
68
76
 
69
- | 方案 | 优点 | 缺点 | 为何不选 |
70
- |------|------|------|----------|
71
- | 方案A | ... | ... | ... |
72
- | 方案B | ... | ... | ... |
77
+ 明确各入口的一致性要求(强一致/最终一致)。REST API 的入参/出参字段结构放 Tasks 阶段落地。
73
78
 
74
- ## 后果
79
+ **集成方案**:列出所有集成点,明确集成方式(同步/异步/回调)、责任边界、失败语义、可观测性要求。
75
80
 
76
- - 正面影响:...
77
- - 负面影响:...
78
- - 技术债务:...
79
- - 风险:...
81
+ **数据模型与数据库方案**:对齐 Specs 的 Key Entities,说明关键业务对象如何落库(表级),列出受影响的表与改动原因,明确关键数据约束。新增表必须给出 DDL;修改存量表只写字段语义/约束/迁移策略,具体 ALTER 放 Tasks。
80
82
 
81
- ## 验证方式
82
- <如何验证这个决策是正确的>
83
- ```
83
+ **迁移 / 兼容**:存量数据处理策略、行为兼容、数据兼容、集成兼容、发布策略(是否灰度)、回滚策略。
84
+
85
+ **风险与验证矩阵**:
86
+ - 风险清单:3-7 个关键风险,每条附缓解措施
87
+ - 验证矩阵:将 Specs 的 AC / Scenarios 映射为测试分类和测试方式
88
+
89
+ 验证矩阵格式("测试方式"列只写如何测,不重复 Specs 的断言值):
90
+
91
+ | Specs AC / Scenario | 测试类型 | 测试方式 |
92
+ |---------------------|----------|----------|
93
+ | <AC 组或 Scenario 名> | 单元/集成/回归/人工 | <Mock 策略或测试数据构造方式> |
94
+
95
+ 5. **创建技术方案文档**
96
+
97
+ 创建 `6aspecdoc/brown/<name>/artifacts/design.md`
98
+
99
+ **必须覆盖的章节**(格式自由,按内容复杂度选择表格或散文):
100
+ - 背景与目标 / 非目标
101
+ - 模块划分
102
+ - 服务边界
103
+ - 接口/入口规范
104
+ - 集成方案
105
+ - 数据模型与数据库方案(新增表附 DDL)
106
+ - 迁移 / 兼容 / 灰度 / 回滚
107
+ - 风险与验证矩阵
108
+
109
+ **可选章节**(按需加入):
110
+ - **What Changes**(变更摘要对比表,适合改动范围清晰的需求):
111
+
112
+ ```markdown
113
+ ## What Changes
114
+
115
+ | 变更前 | 变更后 |
116
+ |--------|--------|
117
+ | <旧行为/旧结构> | <新行为/新结构> |
118
+ | <不变的部分> | 不变 |
119
+ ```
120
+
121
+ - **ADR**(涉及关键架构决策时,创建 `artifacts/ADR-<name>.md`):
122
+
123
+ ```markdown
124
+ # ADR: <决策标题>
125
+
126
+ **状态**: 提议中 / 已接受
127
+ **日期**: <timestamp>
128
+
129
+ ## 背景
130
+ <为什么需要做这个决策>
131
+
132
+ ## 决策
133
+ <我们决定采用什么方案>
134
+
135
+ ## 备选方案
136
+ | 方案 | 优点 | 缺点 | 为何不选 |
137
+ |------|------|------|----------|
84
138
 
85
- 8. **技术债务识别**
139
+ ## 后果
140
+ - 正面影响:...
141
+ - 负面影响:...
142
+ - 风险:...
143
+ ```
86
144
 
87
- 识别实现过程中可能引入的技术债务:
145
+ - **技术债务**(本次变更引入或暴露的债务,说清楚描述、类型、影响、优先级)
88
146
 
89
- | 债务ID | 描述 | 类型 | 影响 | 偿还成本 | 优先级 |
90
- |--------|------|------|------|----------|--------|
91
- | DEBT-001 | 临时的硬编码逻辑 | 代码质量 | 中 | 2人日 | P1 |
147
+ 6. **更新状态**
92
148
 
93
- 9. **创建技术方案文档**
149
+ 更新 `6aspecdoc/brown/<name>/status.json`:
94
150
 
95
- 创建 `6aspecdoc/brown/<name>/artifacts/03-technical-design.md`
151
+ **轻量级流程**:
152
+ ```json
153
+ {
154
+ "status": "tasks_pending",
155
+ "flowDepth": "lightweight",
156
+ "phases": {
157
+ "proposal": "done",
158
+ "specs": "done",
159
+ "design": "done",
160
+ "tasks": "pending",
161
+ "implement": "blocked"
162
+ },
163
+ "artifacts": ["proposal.md", "specs.md", "design.md"]
164
+ }
165
+ ```
166
+
167
+ **标准级流程**:
168
+ ```json
169
+ {
170
+ "status": "tasks_pending",
171
+ "flowDepth": "standard",
172
+ "phases": {
173
+ "analyze": "done",
174
+ "proposal": "done",
175
+ "specs": "done",
176
+ "design": "done",
177
+ "tasks": "pending",
178
+ "implement": "blocked"
179
+ },
180
+ "artifacts": ["analysis.md", "proposal.md", "specs.md", "design.md"]
181
+ }
182
+ ```
96
183
 
97
- 10. **更新状态**
184
+ 同时更新 `6aspecdoc/brown/<name>/requirement.md`:
185
+ - 更新"状态"字段为 `📋 Tasks 待开始`
186
+ - 更新"最后修改"时间戳
187
+ - 更新"当前阶段"为 `Design - 技术方案设计(已完成)`
188
+ - 更新"下一步操作"为 `运行 /6aspec:brown:tasks 继续下一阶段`
189
+ - 在"进度概览"中标记 Design 阶段为已完成 `[x]`
98
190
 
99
- 更新 `6aspecdoc/brown/<name>/status.json`:
100
- ```json
101
- {
102
- "status": "tasks_pending",
103
- "phases": {
104
- "understand": "done",
105
- "impact": "done",
106
- "design": "done",
107
- "tasks": "pending",
108
- ...
109
- }
110
- }
111
- ```
191
+ ---
112
192
 
113
- **输出**
193
+ ## 输出
114
194
 
195
+ **轻量级流程**:
115
196
  ```
116
- ## Phase 3 完成:技术方案设计
197
+ ## Design 完成:<name>
117
198
 
118
- **需求**: <name>
119
- **进度**: 4/5 阶段完成(标准级)或 4/6 阶段完成(完整级)
199
+ **流程**: 轻量级
200
+ **进度**: 3/5 阶段完成
120
201
 
121
202
  ### 方案概要
122
- - 数据库变更:<数量> 个表
123
- - 代码变更:<数量> 个类
124
- - 前端变更:<数量> 个页面
125
- - 测试用例:<数量>
203
+ - 模块划分:<数量> 个模块(新增/调整:<数量>)
204
+ - 接口/入口:<数量>
205
+ - 集成点:<数量>
206
+ - 迁移/兼容:<是否需要 + 简述>
126
207
 
127
208
  ### 关键设计决策
128
- <列出 2-3 个关键决策>
209
+ <列出 2-3 个关键决策(含是否创建 ADR)>
210
+
211
+ ### 文档位置
212
+ - 6aspecdoc/brown/<name>/artifacts/design.md
213
+
214
+ ### 下一步
215
+ - 直接回复修正设计方案或补充细节 → 我会更新本阶段文档(design.md)
216
+ - 运行 `/6aspec:brown:tasks` → 进入任务拆解阶段
217
+ - 运行 `/6aspec:brown:continue` → 自动进入下一阶段
218
+ ```
219
+
220
+ **标准级/完整级流程**:
221
+ ```
222
+ ## Design 完成:<name>
129
223
 
130
- ### 技术债务
131
- <列出识别的技术债务>
224
+ **流程**: <标准级/完整级>
225
+ **进度**: <N/M 阶段完成>
226
+
227
+ ### 方案概要
228
+ - 模块划分:<...>
229
+ - 接口/入口:<...>
230
+ - 集成点:<...>
231
+ - 数据模型:<新增表/改表概览>
232
+ - 迁移/兼容:<策略摘要>
233
+
234
+ ### 风险与验证
235
+ - 关键风险:<数量>
236
+ - 验证矩阵:已覆盖 Specs 的 AC / Scenarios
132
237
 
133
238
  ### 文档位置
134
- - 6aspecdoc/brown/<name>/artifacts/03-technical-design.md
135
- - 6aspecdoc/brown/<name>/artifacts/ADR-<name>.md (P0)
239
+ - 6aspecdoc/brown/<name>/artifacts/design.md
240
+ - 6aspecdoc/brown/<name>/artifacts/ADR-<name>.md(如涉及)
136
241
 
137
242
  ### 下一步
138
- - 直接回复修正设计方案或补充细节 → 我会更新本阶段文档(03-technical-design.md)
243
+ - 直接回复修正设计方案或补充细节 → 我会更新本阶段文档(design.md)
139
244
  - 运行 `/6aspec:brown:tasks` → 进入任务拆解阶段
140
245
  - 运行 `/6aspec:brown:continue` → 自动进入下一阶段
141
246
  ```
142
247
 
143
- **用户补充信息时的处理**
248
+ ---
249
+
250
+ ## 用户补充信息时的处理
144
251
 
145
- 当用户修正设计方案、补充技术细节、或对设计决策提出异议时(未使用阶段命令):
146
- 1. 将用户的修正/补充整合到 `03-technical-design.md` 的对应章节
252
+ 当用户修正设计方案、补充决策信息、或对设计决策提出异议时(未使用阶段命令):
253
+ 1. 将用户的修正/补充整合到 `design.md` 的对应章节
147
254
  2. 展示变更摘要
148
255
  3. 再次提示:可以继续补充,或通过命令进入下一阶段
149
256
  4. **禁止**:不得自动进入下一阶段
150
257
 
151
- **防护措施**
152
- - 必须先完成 Phase 2
153
- - P0 需求必须创建 ADR
154
- - 代码示例必须完整可用
155
- - 技术债务必须明确标注
258
+ ---
259
+
260
+ ## 防护措施
261
+
262
+ - 必须先完成 specs 阶段(`phases.specs == done`)
263
+ - Design 文档必须覆盖:模块划分、服务边界、接口/入口规范、集成方案、数据模型、迁移/兼容、风险与验证
264
+ - 接口/入口规范必须覆盖:执行逻辑、幂等、并发、异常、性能、补偿/重试(REST API 无补偿项);格式不限
265
+ - 影响粒度到类/方法级,类名/方法名可以出现(用于定位),不写实现逻辑;行级定位留给 Tasks
266
+ - **禁止**:代码片段/伪代码/注解/前端逐字段交互/API 出入参字段清单
267
+ - **新增表**:必须提供 DDL;**改表**:不得在 Design 展开全量 DDL(放 Tasks)
268
+ - 涉及关键架构决策时必须创建 ADR
269
+ - 标准级/完整级:技术债务应明确标注(如有)
270
+ - 验证矩阵的"测试方式"列不得重复 Specs 中已有的断言值