ai-spec-tool 0.1.2 → 0.1.4
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/README.md +8 -1
- package/assets/AGENTS.md +1 -30
- package/assets/skills/plan/SKILL.md +166 -0
- package/assets/skills/spec-creator/SKILL.md +22 -0
- package/assets/skills/spec-creator/assets/architecture_gen.md +242 -0
- package/assets/skills/spec-creator/assets/project_architecture_gen.md +128 -0
- package/assets/skills/spec-creator/assets/vision_gen.md +223 -0
- package/bin/ai-spec-tool.js +60 -10
- package/package.json +1 -1
- package/assets/.agents/skills/bugfix/SKILL.md +0 -32
- package/assets/.agents/skills/plan/SKILL.md +0 -336
- package/assets/.agents/skills/plan-executor/SKILL.md +0 -322
- package/assets/.agents/skills/rules-creator/SKILL.md +0 -19
- package/assets/.agents/skills/rules-creator/assets/architecture-gen.md +0 -249
- package/assets/.agents/skills/rules-creator/assets/naming-rule-gen.md +0 -77
- package/assets/.agents/skills/rules-creator/assets/ui-architecture-gen.md +0 -332
- package/assets/.agents/skills/rules-creator/assets/ui-template-gen.md +0 -127
- package/assets/.agents/skills/rules-creator/assets/vision-gen.md +0 -613
- package/assets/.agents/skills/spec-executor/SKILL.md +0 -122
|
@@ -1,336 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: plan
|
|
3
|
-
description: 用户明确需要一个新的系统、模块或功能体系,或对既有系统进行修改;本 skill 用于生成“非确定性架构裁决 Plan”
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
#前置依赖(强制)
|
|
7
|
-
|
|
8
|
-
## 依赖的规范文件(必须全部存在)
|
|
9
|
-
- docs/global/vision.md
|
|
10
|
-
- docs/global/architecture.md
|
|
11
|
-
- docs/global/naming-rule.md
|
|
12
|
-
|
|
13
|
-
## 依赖检查流程(不可跳过)
|
|
14
|
-
- 你必须先尝试读取并理解所有依赖文件内容
|
|
15
|
-
- 若任何依赖文件无法读取 / 不存在 / 内容为空:
|
|
16
|
-
- **只能输出以下内容(禁止输出任何其他文字)**
|
|
17
|
-
> 缺少依赖[<依赖名称>]
|
|
18
|
-
> 回复「Y」开始创建依赖
|
|
19
|
-
- 下一次 run 必须使用 skill: rules-creator
|
|
20
|
-
- 若所有依赖均存在,才可继续
|
|
21
|
-
|
|
22
|
-
---
|
|
23
|
-
|
|
24
|
-
## 1) 框架存在性检查(强制)
|
|
25
|
-
|
|
26
|
-
在进入需求澄清前,必须确认当前项目是否已建立 `docs/global/architecture.md` 中「技术栈选择」指定的框架组合。
|
|
27
|
-
默认项目根目录为 `./projects`(若不存在则视为尚未建立任何框架)。
|
|
28
|
-
|
|
29
|
-
执行规则:
|
|
30
|
-
- 先读取 `docs/global/architecture.md` 的「技术栈选择」
|
|
31
|
-
- 根据「技术栈选择」列出的每个框架,判断 `./projects/<框架目录>` 内是否已具备该框架的标准结构/配置
|
|
32
|
-
- 若任一框架尚未建立:
|
|
33
|
-
- 必须先询问用户是否需要你建立这些缺失框架(可逐个确认)
|
|
34
|
-
- 若用户同意:**只能使用该框架的主流标准初始化指令**(例如官方 CLI/脚手架),且必须初始化在 `./projects/<框架目录>`
|
|
35
|
-
- **禁止在 `./` 根目录初始化**,也禁止手动逐文件创建
|
|
36
|
-
- 若用户拒绝:停止并等待用户自行处理
|
|
37
|
-
- 若已建立框架:
|
|
38
|
-
- 检查 `.vscode/launch.json` 是否存在
|
|
39
|
-
- 若不存在:询问用户是否需要你建立**符合该技术框架组合**的快速启动方案
|
|
40
|
-
- **各框架工程根目录为 `./projects/<框架目录>`,但 `launch.json` 在 `.vscode/launch.json` 而不是 `.vscode/projects/launch.json`**
|
|
41
|
-
|
|
42
|
-
---
|
|
43
|
-
|
|
44
|
-
## 2) UI 规范参照(强制,条件触发)
|
|
45
|
-
|
|
46
|
-
当 `docs/global/architecture.md` 的技术栈选择**包含前端技术栈**时,生成 plan 之前必须:
|
|
47
|
-
- 读取并理解:
|
|
48
|
-
- `docs/global/ui/design-tokens.md`
|
|
49
|
-
- `docs/global/ui/layout-and-responsive.md`
|
|
50
|
-
- `docs/global/ui/patterns.md`
|
|
51
|
-
- 若任一文件缺失 / 为空:**停止并要求补齐**(下一次 run 使用 `rules-creator` 走 UI 规范生成)
|
|
52
|
-
- 在 plan 的 `rules.hard` 或相关 UI module 的 `constraints.must` 中**明确写入**:
|
|
53
|
-
- “所有 UI 交互必须遵守 `docs/global/ui/patterns.md` 的交互模式”
|
|
54
|
-
|
|
55
|
-
---
|
|
56
|
-
|
|
57
|
-
## 3) 需求澄清阶段(强制)
|
|
58
|
-
|
|
59
|
-
### 2.1 澄清目的(不可偏离)
|
|
60
|
-
|
|
61
|
-
* 本阶段**仅用于理解用户真实意图与需求边界**
|
|
62
|
-
* 本阶段**不产出任何设计或结论**
|
|
63
|
-
* 在本阶段中 **严禁**:
|
|
64
|
-
|
|
65
|
-
* 讨论或暗示模块类型(Service / Adapter / Core 等)
|
|
66
|
-
* 讨论架构、分层、依赖关系
|
|
67
|
-
* 讨论技术选型、实现方式、数据结构
|
|
68
|
-
* 产出任何 spec、plan 或设计草案
|
|
69
|
-
|
|
70
|
-
> ⚠️ 本阶段的唯一目标:**把「用户真正想做什么」问清楚**
|
|
71
|
-
|
|
72
|
-
---
|
|
73
|
-
|
|
74
|
-
### 2.2 澄清问题(强制逐题、单题执行)
|
|
75
|
-
|
|
76
|
-
* 以下问题 **必须按顺序逐题完成**
|
|
77
|
-
* **一次只允许提出一个问题**
|
|
78
|
-
* 在当前问题尚未获得用户确认前:
|
|
79
|
-
|
|
80
|
-
* ❌ 不得显示后续问题
|
|
81
|
-
* ❌ 不得列出问题清单
|
|
82
|
-
* ❌ 不得暗示「接下来还会问什么」
|
|
83
|
-
* 每一题都视为一个独立对话回合
|
|
84
|
-
|
|
85
|
-
> ⚠️ 违反上述规则,视为澄清流程失败
|
|
86
|
-
|
|
87
|
-
---
|
|
88
|
-
|
|
89
|
-
### 2.3 提问与回应格式(强制)
|
|
90
|
-
|
|
91
|
-
**每一轮提问必须严格遵守以下结构,不得增删:**
|
|
92
|
-
|
|
93
|
-
1. 提出 **当前问题(仅此一题)**
|
|
94
|
-
2. 基于以下信息,给出一段 **猜测性建议答案**:
|
|
95
|
-
|
|
96
|
-
* 已完成的前序问题回答
|
|
97
|
-
* `vision.md`
|
|
98
|
-
* `architecture.md`
|
|
99
|
-
* `naming-rule.md`
|
|
100
|
-
3. 明确提示用户操作方式:
|
|
101
|
-
|
|
102
|
-
```
|
|
103
|
-
回复「Y」接受上述建议,
|
|
104
|
-
或直接输入你的实际答案。
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
* 猜测性建议答案的目的仅是:
|
|
108
|
-
|
|
109
|
-
* 帮助用户更快理解问题
|
|
110
|
-
* 降低回答成本
|
|
111
|
-
* **不得**:
|
|
112
|
-
|
|
113
|
-
* 引导用户做架构、模块、实现相关决策
|
|
114
|
-
* 在建议答案中偷渡解决方案
|
|
115
|
-
|
|
116
|
-
---
|
|
117
|
-
|
|
118
|
-
### 2.4 澄清问题池(内部使用,不得一次性输出)
|
|
119
|
-
|
|
120
|
-
> 以下问题仅作为**内部顺序控制用**
|
|
121
|
-
> **不得在任何一次输出中同时展示多个问题**
|
|
122
|
-
|
|
123
|
-
#### 问题 1
|
|
124
|
-
|
|
125
|
-
你这次想新增或修改的核心能力是什么?
|
|
126
|
-
(完成后,系统「多了什么」或「哪里不一样」?)
|
|
127
|
-
|
|
128
|
-
#### 问题 2
|
|
129
|
-
|
|
130
|
-
这个能力通常在什么情境下被需要?
|
|
131
|
-
(谁、在什么情况下,会用到它?)
|
|
132
|
-
|
|
133
|
-
#### 问题 3
|
|
134
|
-
|
|
135
|
-
和现在相比,这次变更会让哪些行为或结果发生改变?
|
|
136
|
-
|
|
137
|
-
#### 问题 4
|
|
138
|
-
|
|
139
|
-
你觉得这个能力最容易出问题的地方是什么?
|
|
140
|
-
(例如:状态混乱、规则分散、依赖外部、不稳定)
|
|
141
|
-
|
|
142
|
-
#### 问题 5
|
|
143
|
-
|
|
144
|
-
如果这次改动出错,你最不能接受的失败结果是什么?
|
|
145
|
-
|
|
146
|
-
---
|
|
147
|
-
|
|
148
|
-
### 2.5 推进规则(状态机约束)
|
|
149
|
-
|
|
150
|
-
* 若尚未取得 **问题 N** 的有效回答:
|
|
151
|
-
|
|
152
|
-
* **只能**继续停留在问题 N
|
|
153
|
-
* 当用户:
|
|
154
|
-
|
|
155
|
-
* 回复「Y」→ 视为接受建议答案,记录为该题结论
|
|
156
|
-
* 输入自定义答案 → 以用户答案为准,覆盖建议
|
|
157
|
-
* 完成问题 N 后:
|
|
158
|
-
|
|
159
|
-
* 下一轮对话 **只能**提出问题 N+1
|
|
160
|
-
* 在问题 1~5 全部完成前:
|
|
161
|
-
|
|
162
|
-
* ❌ 不得总结
|
|
163
|
-
* ❌ 不得生成 plan / spec / 模块拆分
|
|
164
|
-
* ❌ 不得进入下一阶段
|
|
165
|
-
|
|
166
|
-
---
|
|
167
|
-
|
|
168
|
-
### 2.6 违规防护(强制)
|
|
169
|
-
|
|
170
|
-
* 若当前问题未完成,却出现以下任一行为,必须立即自我修正并重新提问当前问题:
|
|
171
|
-
|
|
172
|
-
* 提前出现后续问题内容
|
|
173
|
-
* 总结尚未完成的澄清结果
|
|
174
|
-
* 引入架构 / 模块 / 实现讨论
|
|
175
|
-
* 解释「接下来会做什么」
|
|
176
|
-
|
|
177
|
-
---
|
|
178
|
-
|
|
179
|
-
## 3) Plan 生成原则(非常重要)
|
|
180
|
-
|
|
181
|
-
### 3.1 Plan 的角色定义
|
|
182
|
-
- plan.md 是 **非确定性架构裁决的集合**
|
|
183
|
-
- plan.md 是 **plan 执行器的输入**
|
|
184
|
-
- plan.md 的内容应:
|
|
185
|
-
- 让后续 module spec 的生成 **几乎不需要猜**
|
|
186
|
-
- 明确哪些事情已经被裁决,后续不得再推断
|
|
187
|
-
|
|
188
|
-
### 3.2 禁止在 Plan 中出现的内容
|
|
189
|
-
- ❌ 文件创建顺序
|
|
190
|
-
- ❌ 技术选型
|
|
191
|
-
- ❌ 实现细节
|
|
192
|
-
- ❌ 函数名 / API / 参数
|
|
193
|
-
|
|
194
|
-
---
|
|
195
|
-
|
|
196
|
-
## 4) plan.md 输出结构(强制使用,不得增删章节)
|
|
197
|
-
|
|
198
|
-
你**必须**生成符合以下结构的 plan.md:
|
|
199
|
-
|
|
200
|
-
<以下为plan.md输出范例>
|
|
201
|
-
---
|
|
202
|
-
plan_id: <自动生成>
|
|
203
|
-
kind: <feature|update|refactor>
|
|
204
|
-
scope: <系统或子系统>
|
|
205
|
-
version: 1
|
|
206
|
-
---
|
|
207
|
-
|
|
208
|
-
---
|
|
209
|
-
|
|
210
|
-
### intent
|
|
211
|
-
|
|
212
|
-
* goal: 架构目标(列表)
|
|
213
|
-
* non_goals: 明确不做的事(列表)
|
|
214
|
-
* success_criteria: 可验证完成标准(列表)
|
|
215
|
-
|
|
216
|
-
---
|
|
217
|
-
|
|
218
|
-
### modules
|
|
219
|
-
|
|
220
|
-
* 必须以 **module 为单位**
|
|
221
|
-
* 每个 module **必须包含以下字段**:
|
|
222
|
-
|
|
223
|
-
* name
|
|
224
|
-
* type
|
|
225
|
-
* change
|
|
226
|
-
* purpose
|
|
227
|
-
* capabilities(reads / writes / events / subscribes / calls 等)
|
|
228
|
-
* ownership(ssot_facts / state_owner)
|
|
229
|
-
* dependencies(must / forbid)
|
|
230
|
-
* constraints(must / must_not)
|
|
231
|
-
* collaboration
|
|
232
|
-
* 若 state_owner=true,必须包含 state_model
|
|
233
|
-
|
|
234
|
-
---
|
|
235
|
-
|
|
236
|
-
### flows
|
|
237
|
-
|
|
238
|
-
* use_cases:以结构化 chain 描述关键流程
|
|
239
|
-
* 每个 use case 必须明确:
|
|
240
|
-
|
|
241
|
-
* trigger
|
|
242
|
-
* actor
|
|
243
|
-
* action
|
|
244
|
-
* target
|
|
245
|
-
* outcome
|
|
246
|
-
|
|
247
|
-
---
|
|
248
|
-
|
|
249
|
-
### rules
|
|
250
|
-
|
|
251
|
-
* hard: 全局不可违反规则(列表)
|
|
252
|
-
|
|
253
|
-
---
|
|
254
|
-
### execution_steps
|
|
255
|
-
|
|
256
|
-
* 必须提供「建议修改流程」的最小步骤
|
|
257
|
-
* 必须按 **模块依赖关系** 排序:先基础依赖、后上层组合
|
|
258
|
-
* **必须覆盖本次 plan 中所有 modules**
|
|
259
|
-
* 每一步 **只能提到一个 module**(新增或修改),不得合并
|
|
260
|
-
* 每一步必须使用 **有序列表**(1. 2. 3.)来强调顺序
|
|
261
|
-
* 允许引用模块名或章节名,但不得包含实现细节、函数名、API 或文件路径
|
|
262
|
-
* 每一步需可被 spec-executor 按序执行或核对
|
|
263
|
-
* 若依赖顺序无法确定,必须停止并向用户补问
|
|
264
|
-
|
|
265
|
-
---
|
|
266
|
-
<以上为plan.md输出范例>
|
|
267
|
-
|
|
268
|
-
## 5) 若信息不足的处理规则(强制)
|
|
269
|
-
|
|
270
|
-
* 若无法确定 module 边界 / 状态归属 / SSOT:
|
|
271
|
-
|
|
272
|
-
* **必须停止**
|
|
273
|
-
* 明确列出缺失信息
|
|
274
|
-
* 向用户提问补充
|
|
275
|
-
* ❌ 不得在信息不足时生成假设性 plan.md
|
|
276
|
-
|
|
277
|
-
---
|
|
278
|
-
|
|
279
|
-
## 6) 最终输出要求(非常重要)
|
|
280
|
-
- 1.生成一份 Plan 文件
|
|
281
|
-
- 文件路径:`./docs/plan/<index>-<plan目标>.md`
|
|
282
|
-
- `<index>`:根据 `./docs/plan/` 目录下已有文件数量顺序递增生成
|
|
283
|
-
- `<plan目标>`:在完成需求澄清后,根据本次变更的核心意图自动总结生成
|
|
284
|
-
- 输出格式:Markdown
|
|
285
|
-
- 语言:中文为主
|
|
286
|
-
|
|
287
|
-
- 2.文字输出
|
|
288
|
-
> 已完成plan文件的生成<显示文件名(带有超链接)>
|
|
289
|
-
>
|
|
290
|
-
> 接下来
|
|
291
|
-
> 1.讨论修改plan文件细节
|
|
292
|
-
> 2.直接执行plan
|
|
293
|
-
- 直接执行plan → 使用 skill: plan-executor
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
## 6) 最终输出要求(非常重要)
|
|
297
|
-
|
|
298
|
-
### 6.1 Plan 文件生成(强制)
|
|
299
|
-
|
|
300
|
-
- 在完成「需求澄清阶段」全部问题后:
|
|
301
|
-
- **必须生成一份 Plan 文件**
|
|
302
|
-
- **不得将 Plan 文件内容直接输出在对话中**
|
|
303
|
-
|
|
304
|
-
#### 文件路径规则
|
|
305
|
-
- 文件路径:`./docs/plan/<index>-<plan目标>.md`
|
|
306
|
-
|
|
307
|
-
- `<index>`:
|
|
308
|
-
- 根据 `./docs/plan/` 目录下已有文件数量
|
|
309
|
-
- 以递增顺序生成(001, 002, 003 ...)
|
|
310
|
-
|
|
311
|
-
- `<plan目标>`:
|
|
312
|
-
- 在完成需求澄清后
|
|
313
|
-
- 根据本次变更的核心意图自动总结生成
|
|
314
|
-
- 不包含技术名词或实现细节
|
|
315
|
-
|
|
316
|
-
#### 文件格式
|
|
317
|
-
- 内容格式:Markdown
|
|
318
|
-
- 语言:中文为主
|
|
319
|
-
|
|
320
|
-
---
|
|
321
|
-
|
|
322
|
-
### 6.2 对话反馈(唯一允许的文字输出)
|
|
323
|
-
|
|
324
|
-
在 Plan 文件生成完成后,对话中**只允许**输出以下结构:
|
|
325
|
-
|
|
326
|
-
> 已完成 Plan 文件的生成:
|
|
327
|
-
> `<文件名>`(需为可点击超链接)
|
|
328
|
-
|
|
329
|
-
> 接下来你可以选择:
|
|
330
|
-
> 1. 讨论并修改 Plan 文件细节
|
|
331
|
-
> 2. 直接执行 Plan(将进入 plan-executor,并把 plan 改名为 `.processing.md`)
|
|
332
|
-
|
|
333
|
-
- 若用户选择「直接执行 Plan」:
|
|
334
|
-
- **必须使用** `skill: plan-executor`
|
|
335
|
-
- 不得再次生成或修改 Plan 文件
|
|
336
|
-
```
|
|
@@ -1,322 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: plan-executor
|
|
3
|
-
description: 当用户想要执行某个plan
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
#前置依赖(强制)
|
|
7
|
-
|
|
8
|
-
## 依赖的规范文件(必须全部存在)
|
|
9
|
-
- docs/global/vision.md
|
|
10
|
-
- docs/global/architecture.md
|
|
11
|
-
- docs/global/naming-rule.md
|
|
12
|
-
|
|
13
|
-
## 依赖检查流程(不可跳过)
|
|
14
|
-
- 你必须先尝试读取并理解所有依赖文件内容
|
|
15
|
-
- 若任何依赖文件无法读取 / 不存在 / 内容为空:
|
|
16
|
-
- **只能输出以下内容(禁止输出任何其他文字)**
|
|
17
|
-
> 缺少依赖[<依赖名称>]
|
|
18
|
-
> 回复「Y」开始创建依赖
|
|
19
|
-
- 下一次 run 必须使用 skill: rules-creator
|
|
20
|
-
- 若所有依赖均存在,才可继续
|
|
21
|
-
|
|
22
|
-
---
|
|
23
|
-
|
|
24
|
-
## Prompt:Plan → Multi Module Specs Generator
|
|
25
|
-
|
|
26
|
-
你是一個「Spec 產生器」。你的任務是:**讀取使用者提供的 plan.md(YAML)**,然後為 `modules:` 內的每個 module,輸出一份符合「Module Spec 標準格式」的 `spec.md` 文件內容。
|
|
27
|
-
|
|
28
|
-
### 1) 輸入
|
|
29
|
-
|
|
30
|
-
使用者會提供plan文件名称,plan文件都放在`./docs/plan/xxx.md`,每个plan文件都包含:
|
|
31
|
-
|
|
32
|
-
* `intent`:goal / non_goals / success_criteria
|
|
33
|
-
* `modules[]`:每個 module 的定義(name/type/change/purpose/capabilities/ownership/dependencies/constraints/state_model/collaboration…)
|
|
34
|
-
* `flows`:use_cases
|
|
35
|
-
* `rules`:hard 規則
|
|
36
|
-
|
|
37
|
-
---
|
|
38
|
-
|
|
39
|
-
### 1.1 UI 规范文件读取(强制)
|
|
40
|
-
|
|
41
|
-
在执行任何生成之前,若 plan 中存在 UI 显示组件类型模块(见 `./docs/global/ui/module-ui-types.md`),必须先读取并理解:
|
|
42
|
-
- `docs/global/ui/design-tokens.md`
|
|
43
|
-
- `docs/global/ui/layout-and-responsive.md`
|
|
44
|
-
- `docs/global/ui/patterns.md`
|
|
45
|
-
|
|
46
|
-
规则:
|
|
47
|
-
- 若任一文件缺失 / 为空:**停止并要求补齐**(下一次 run 使用 `rules-creator` 走 UI 规范生成)
|
|
48
|
-
|
|
49
|
-
---
|
|
50
|
-
|
|
51
|
-
### 1.2 组件使用规范(Component Rules)生成条件(强制)
|
|
52
|
-
|
|
53
|
-
在执行任何生成之前,必须先检查:
|
|
54
|
-
`./docs/global/ui/module-ui-types.md` 是否存在且包含「UI 显示组件类型」清单
|
|
55
|
-
|
|
56
|
-
规则:
|
|
57
|
-
- 若条件不满足:**禁止生成 Component Rules**(仅生成 Module spec)
|
|
58
|
-
- 若满足:
|
|
59
|
-
- 仅对 **module type 属于 UI 显示组件类型清单** 的模块生成 Component Rules
|
|
60
|
-
- Component Rules 文件路径:`./docs/component/<module-name>.md`
|
|
61
|
-
- 不为非 UI 组件类型生成(例如 ComponentLogic / ComponentView,除非被列入清单)
|
|
62
|
-
|
|
63
|
-
---
|
|
64
|
-
|
|
65
|
-
### 1.3 争议咨询(强制)
|
|
66
|
-
|
|
67
|
-
在生成任何 Module spec **之前**,你必须先完整阅读 plan,并执行以下流程:
|
|
68
|
-
|
|
69
|
-
1. 识别 plan 中**不合理 / 逻辑不通顺 / 相互矛盾**的地方(例如依赖冲突、角色与职责不一致、flows 与 rules 矛盾)
|
|
70
|
-
2. 若发现问题:
|
|
71
|
-
- 必须先与用户讨论并取得结论
|
|
72
|
-
- 根据结论**修改 plan 文件本身**
|
|
73
|
-
- 只有在所有问题都收敛后,才可继续往下执行
|
|
74
|
-
3. 若未发现问题:继续往下执行
|
|
75
|
-
|
|
76
|
-
### 2) Module Spec 標準模板(你必須嚴格依此結構輸出)
|
|
77
|
-
|
|
78
|
-
每個 module spec 必須包含以下章節與順序(標題文字可維持你範例的繁中風格):
|
|
79
|
-
|
|
80
|
-
1. YAML Frontmatter(兩段)
|
|
81
|
-
|
|
82
|
-
* 第一段:
|
|
83
|
-
|
|
84
|
-
* `module name: <name>`
|
|
85
|
-
* `module type: <type>`
|
|
86
|
-
* `source plan: <plan base name>`
|
|
87
|
-
* 保持你示例的 `---` 區塊樣式(兩段)
|
|
88
|
-
|
|
89
|
-
2. `# 為什麼存在`
|
|
90
|
-
|
|
91
|
-
3. `# 如果不存在`
|
|
92
|
-
|
|
93
|
-
4. `# 做什麼`
|
|
94
|
-
|
|
95
|
-
5. `# 不做什么`
|
|
96
|
-
|
|
97
|
-
6. `# 提供什麼能力`
|
|
98
|
-
|
|
99
|
-
7. `# 允許依賴`
|
|
100
|
-
|
|
101
|
-
8. `# 禁止依賴`
|
|
102
|
-
|
|
103
|
-
9. `# 狀態定義(如果有狀態)`(若沒有狀態就輸出「不適用」一行)
|
|
104
|
-
|
|
105
|
-
10. `# 狀態轉換(如果有狀態)`(同上)
|
|
106
|
-
|
|
107
|
-
11. `# 禁止轉換(如果有狀態)`(同上)
|
|
108
|
-
|
|
109
|
-
12. `# 怎麼被用`
|
|
110
|
-
|
|
111
|
-
13. `# 未來可能扩充`
|
|
112
|
-
|
|
113
|
-
14. `# 禁止擴充方向`
|
|
114
|
-
|
|
115
|
-
15. `# 現在不做`
|
|
116
|
-
|
|
117
|
-
> 語言:以**繁體中文**輸出(沿用你範例語氣)。
|
|
118
|
-
> 內容必須是「語義能力」與「邊界規則」,**不可落到具體函式名、HTTP、JSON schema、框架、庫、實作細節**。
|
|
119
|
-
|
|
120
|
-
---
|
|
121
|
-
|
|
122
|
-
### 2.1 Component Rules 標準模板(僅在允許生成時)
|
|
123
|
-
|
|
124
|
-
每個 Component Rules 必須包含以下章節與順序:
|
|
125
|
-
|
|
126
|
-
1. `# 组件定位`
|
|
127
|
-
2. `# 允许使用场景`
|
|
128
|
-
3. `# 禁止使用场景`
|
|
129
|
-
4. `# 输入与输出语义`(仅描述语义,不涉及 props 细节)
|
|
130
|
-
5. `# 交互与状态`(若无状态写「不適用」)
|
|
131
|
-
6. `# 组合与依赖`(仅描述允许组合的模块)
|
|
132
|
-
7. `# 视觉与可访问性要求`(需引用 design-tokens 的语义,并对齐 layout-and-responsive / patterns 的约束)
|
|
133
|
-
8. `# 变更风险提示`
|
|
134
|
-
|
|
135
|
-
> 语言:以**繁體中文**輸出。
|
|
136
|
-
> 内容必须是「使用与边界规则」,不得出现具体实现或 API。
|
|
137
|
-
> **必须引用**:
|
|
138
|
-
> - `docs/global/ui/design-tokens.md`(颜色/字号/间距命名)
|
|
139
|
-
> - `docs/global/ui/layout-and-responsive.md`(布局与响应约束)
|
|
140
|
-
> - `docs/global/ui/patterns.md`(交互模式)
|
|
141
|
-
|
|
142
|
-
### 3) 內容映射規則(Plan → Spec)
|
|
143
|
-
|
|
144
|
-
你必須用以下映射把 plan.md 的資料填入每個 module:
|
|
145
|
-
|
|
146
|
-
#### 3.1 Frontmatter
|
|
147
|
-
|
|
148
|
-
* `module name` ← `modules[].name`
|
|
149
|
-
* `module type` ← `modules[].type`
|
|
150
|
-
* `source plan` ← plan 文件基名(不包含任何副檔名或状态后缀)
|
|
151
|
-
|
|
152
|
-
#### 3.2 為什麼存在 / 如果不存在
|
|
153
|
-
|
|
154
|
-
* `# 為什麼存在`:
|
|
155
|
-
|
|
156
|
-
* 只能使用 `modules[].purpose` 的要點來寫(可改寫更順,但不可新增新職責)
|
|
157
|
-
* 需明確點出此 module 的「唯一正當性」(SSOT、邊界、收斂點等)
|
|
158
|
-
* `# 如果不存在`:
|
|
159
|
-
|
|
160
|
-
* 從 `intent.goal / success_criteria / rules.hard / flows` 推導「會散落在哪些層/誰會重複做、造成什麼不一致」
|
|
161
|
-
* 只能講**規則分叉、依賴混亂、責任漂移、不可驗證**等後果;不要講具體技術災難
|
|
162
|
-
|
|
163
|
-
#### 3.3 做什麼 / 不做什么
|
|
164
|
-
|
|
165
|
-
* `# 做什麼`:
|
|
166
|
-
|
|
167
|
-
* 主要取自:
|
|
168
|
-
|
|
169
|
-
* `modules[].purpose`
|
|
170
|
-
* `modules[].capabilities`(reads/writes/events/transforms/calls/subscribes/orchestrations…)
|
|
171
|
-
* `modules[].ownership`(若是 ssot/state_owner,要寫得更強硬)
|
|
172
|
-
* `modules[].constraints.must`(把 must 的行為落到「做什麼」或「提供什麼能力」)
|
|
173
|
-
* `# 不做什么`:
|
|
174
|
-
|
|
175
|
-
* 主要取自:
|
|
176
|
-
|
|
177
|
-
* `intent.non_goals`
|
|
178
|
-
* `modules[].constraints.must_not`
|
|
179
|
-
* `modules[].dependencies.forbid`
|
|
180
|
-
* 每條以 `❌` 開頭,語氣要像你範例那樣「硬邊界」
|
|
181
|
-
|
|
182
|
-
#### 3.4 提供什麼能力(只講語義)
|
|
183
|
-
|
|
184
|
-
* 從 `modules[].capabilities` 生成:
|
|
185
|
-
|
|
186
|
-
* reads → 「查詢/讀取」語義
|
|
187
|
-
* writes → 「接收/寫入」語義(保持抽象 input)
|
|
188
|
-
* events → 「發布/訂閱」語義(只描述 payload_min 的語義)
|
|
189
|
-
* transforms → 「轉換」語義(adapter 常見)
|
|
190
|
-
* calls → 「呼叫」語義(描述 target,不描述技術)
|
|
191
|
-
* subscribes → 「訂閱」語義
|
|
192
|
-
* orchestrations → 「編排」語義(service 常見)
|
|
193
|
-
* **禁止**出現:函式名、參數型別、HTTP、路由、JSON schema、SDK、框架名
|
|
194
|
-
|
|
195
|
-
#### 3.5 允許依賴 / 禁止依賴
|
|
196
|
-
|
|
197
|
-
* `# 允許依賴`:
|
|
198
|
-
|
|
199
|
-
* 先寫一行規則引用(固定句式):
|
|
200
|
-
|
|
201
|
-
* `规则: <module type> -> ...(依賴邊界由 docs/global/architecture.md 定義)`
|
|
202
|
-
* 再列出 `modules[].dependencies.must`(若空就寫「(無)」)
|
|
203
|
-
* `# 禁止依賴`:
|
|
204
|
-
|
|
205
|
-
* 同樣先寫規則引用
|
|
206
|
-
* 再列出 `modules[].dependencies.forbid`(若空就寫「(無)」)
|
|
207
|
-
* 另外要做一個「領域級補充」:若 plan 中 forbid 出現 `billing/*` 這種模式,要寫成你範例那種領域切割說法
|
|
208
|
-
|
|
209
|
-
#### 3.6 狀態(state_model)
|
|
210
|
-
|
|
211
|
-
* 若存在 `modules[].state_model`:
|
|
212
|
-
|
|
213
|
-
* `# 狀態定義`:對 `states` 每個狀態給一句語義定義(可沿用 plan 或推導,但不可新增與 plan 矛盾的狀態)
|
|
214
|
-
* `# 狀態轉換`:依 plan 的 `forbidden_transitions` 與 `invariants` 推導「允許的轉換敘述」
|
|
215
|
-
|
|
216
|
-
* 若 plan 沒給完整轉換表:你可以列出「必須支持」的轉換(例如 INIT→ANON/AUTH/EXPIRED),但不得與 `forbidden_transitions` 牴觸
|
|
217
|
-
* `# 禁止轉換`:
|
|
218
|
-
|
|
219
|
-
* 必須包含 plan 的 `forbidden_transitions`
|
|
220
|
-
* 也要把 `invariants` 中能轉成禁止/約束句的寫進來(例如 INIT 期間 gating 必須 false)
|
|
221
|
-
* 若不存在 `state_model`:三個狀態章節都輸出 `不適用(本模組不維護狀態機)`
|
|
222
|
-
|
|
223
|
-
#### 3.7 怎麼被用(最重要:協作關係)
|
|
224
|
-
|
|
225
|
-
* 主要來源:
|
|
226
|
-
|
|
227
|
-
* `modules[].collaboration`
|
|
228
|
-
* `flows.use_cases` 中與此 module 有關的 chain(target 命中此 module)
|
|
229
|
-
* 必須寫清楚:
|
|
230
|
-
|
|
231
|
-
* 誰可以讀(readers)
|
|
232
|
-
* 誰可以寫(writers)
|
|
233
|
-
* UI policy(若有)
|
|
234
|
-
* 典型使用流程(用「先…再…若…」語氣,不要寫程式)
|
|
235
|
-
|
|
236
|
-
#### 3.8 未來可能扩充 / 禁止擴充方向 / 現在不做
|
|
237
|
-
|
|
238
|
-
* `# 未來可能扩充`:
|
|
239
|
-
|
|
240
|
-
* 從 `intent.goal` 與 module 的職責,列出合理擴充點(例如新增狀態/新增來源/新增事件)
|
|
241
|
-
* 但必須加上「擴充門檻條件」(像你範例那種:必須同步更新表、必須抽象化成 login-result)
|
|
242
|
-
* `# 禁止擴充方向`:
|
|
243
|
-
|
|
244
|
-
* 直接引用 `rules.hard`、`modules[].constraints.must_not`、`intent.non_goals` 中會導致越界的方向
|
|
245
|
-
* `# 現在不做`:
|
|
246
|
-
|
|
247
|
-
* 必須包含 `intent.non_goals`(若與此 module 無關,要改寫成「本模組不涵蓋…」但仍列出)
|
|
248
|
-
* 若 plan 的 non_goals 很全域,你要挑選「與此 module 最相關」的優先列出,剩下可以簡短合併成「此外,本計畫目前也不做:…」
|
|
249
|
-
|
|
250
|
-
### 4) 全域一致性規則(跨檔必須一致)
|
|
251
|
-
|
|
252
|
-
你必須保證所有 module specs 之間一致:
|
|
253
|
-
|
|
254
|
-
* **SSOT 規則**:若某 module 的 `ownership.state_owner: true` 或 `ownership.ssot_facts` 非空,其他 module 的 spec 裡必須避免暗示「自己也能決定/維護那些事實」
|
|
255
|
-
* **唯一寫入口**:若 `auth-session` constraints 說「會話寫入只有一個入口」,則:
|
|
256
|
-
|
|
257
|
-
* `auth-callback-handler` 的 spec 必須清楚說自己只「轉換/提交」,不保存、不裁決
|
|
258
|
-
* `account-flow` 的 spec 必須清楚說自己只「編排/訂閱/讀 gating」,不寫 session
|
|
259
|
-
* **依賴方向**要符合 module type 語義(例如 service 不可依賴 adapter / UI / component)。若 plan 給的依賴違反,必須在該 module spec 的「禁止依賴」中明確指出,且在「不做什么」加一條「不跨層」
|
|
260
|
-
* **不談 token 協議**:全檔不得出現 token 刷新/簽章/加密協議設計
|
|
261
|
-
|
|
262
|
-
### 5) 自動校驗(輸出前自檢)
|
|
263
|
-
|
|
264
|
-
在輸出每個 module spec 之前,你必須做靜態自檢,若發現以下任一問題,直接修正後再輸出(不要詢問使用者):
|
|
265
|
-
|
|
266
|
-
* 「做什麼」或「提供什麼能力」出現實作細節(HTTP/JSON/schema/函式名/庫名)
|
|
267
|
-
* 模組做了 non_goals 或 must_not 的內容
|
|
268
|
-
* `state_model.forbidden_transitions` 被寫成允許
|
|
269
|
-
* SSOT 事實被其他 module 宣稱擁有
|
|
270
|
-
|
|
271
|
-
---
|
|
272
|
-
|
|
273
|
-
## 6) 輸出(強制格式)
|
|
274
|
-
|
|
275
|
-
### 6.1 Module spec 文件生成(强制)
|
|
276
|
-
|
|
277
|
-
- 在完成以上全部步骤后:
|
|
278
|
-
- **必须生成或修改可能多分 Module spec 文件**
|
|
279
|
-
- **不得将 Module spec 文件内容直接输出在对话中**
|
|
280
|
-
- **若为修改既有 Module spec,必须将输出文件命名为 `.update.md`(可用新增文件或改名方式),作为 spec-executor 的识别信号**
|
|
281
|
-
- **执行完成后,必须将被执行的 plan 文件改名为 `<原文件名>.processing.md`(例如 `001-多语言内容管理.md` → `001-多语言内容管理.processing.md`)**
|
|
282
|
-
- 若符合 Component Rules 生成条件:
|
|
283
|
-
- **仅对 module type = Component 生成**
|
|
284
|
-
- 文件路径:`./docs/component/<module-name>.md`
|
|
285
|
-
- **不得将 Component Rules 内容直接输出在对话中**
|
|
286
|
-
|
|
287
|
-
#### 文件路径规则
|
|
288
|
-
- 文件路径:`./docs/spec/<module-type>/<module-name>.update.md`
|
|
289
|
-
|
|
290
|
-
- `<module-type>`:
|
|
291
|
-
- 根据plan文件下每个module的type标记
|
|
292
|
-
|
|
293
|
-
- `<module-name>`:
|
|
294
|
-
- 根据plan文件下每个module的name标记
|
|
295
|
-
|
|
296
|
-
#### 文件格式
|
|
297
|
-
- 内容格式:Markdown
|
|
298
|
-
- 语言:中文为主
|
|
299
|
-
|
|
300
|
-
---
|
|
301
|
-
|
|
302
|
-
### 6.2 对话反馈(唯一允许的文字输出)
|
|
303
|
-
|
|
304
|
-
在 Plan 文件生成完成后,对话中**只允许**输出以下结构:
|
|
305
|
-
|
|
306
|
-
> 已完成 Module spec 文件的生成:
|
|
307
|
-
> 1.`<文件名>`(需为可点击超链接)
|
|
308
|
-
> 2.`<文件名>`(需为可点击超链接)
|
|
309
|
-
> 3.`<文件名>`(需为可点击超链接)
|
|
310
|
-
|
|
311
|
-
> 已完成 Component Rules 文件的生成(若有):
|
|
312
|
-
> 1.`<文件名>`(需为可点击超链接)
|
|
313
|
-
> 2.`<文件名>`(需为可点击超链接)
|
|
314
|
-
|
|
315
|
-
> 接下来你可以选择:
|
|
316
|
-
> 1. 讨论并修改 Module spec 文件细节
|
|
317
|
-
> 2. 直接依照spec的改动对代码进行修改
|
|
318
|
-
|
|
319
|
-
- 若用户选择「2. 直接依照spec的改动对代码进行修改」:
|
|
320
|
-
- **必须使用** `skill: spec-executor`
|
|
321
|
-
- 不得再次生成或修改 Module spec 文件
|
|
322
|
-
```
|
|
@@ -1,19 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: rules-creator
|
|
3
|
-
description: 当用户指定要创建某个规则文件
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
- 命名规则文件(naming-rule)
|
|
7
|
-
请阅读:assets/naming-rule-gen.md
|
|
8
|
-
|
|
9
|
-
- 专案目标文件(vision)
|
|
10
|
-
请阅读:assets/vision-gen.md
|
|
11
|
-
|
|
12
|
-
- 系统架构文件(architecture)
|
|
13
|
-
请阅读:assets/architecture-gen.md
|
|
14
|
-
|
|
15
|
-
- UI架构文件(ui-architecture)
|
|
16
|
-
请阅读:assets/ui-architecture-gen.md
|
|
17
|
-
|
|
18
|
-
- UI范例界面(ui-template-gen)
|
|
19
|
-
请阅读:assets/ui-template-gen.md
|