@localsummer/incspec 0.1.1 → 0.1.3
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 +1 -0
- package/package.json +1 -1
- package/templates/AGENTS.md +18 -4
- package/templates/inc-spec-skill/SKILL.md +35 -17
package/README.md
CHANGED
|
@@ -4,6 +4,7 @@
|
|
|
4
4
|
<p align="center">面向 AI 编程助手的增量规范驱动开发工具</p>
|
|
5
5
|
<p align="center">
|
|
6
6
|
<a href="https://github.com/localSummer/IncSpec"><img alt="GitHub" src="https://img.shields.io/badge/GitHub-localSummer%2FIncSpec-blue?style=flat-square&logo=github" /></a>
|
|
7
|
+
<a href="https://www.npmjs.com/package/@localsummer/incspec"><img alt="npm" src="https://img.shields.io/npm/v/@localsummer/incspec?style=flat-square&logo=npm" /></a>
|
|
7
8
|
<a href="https://nodejs.org/"><img alt="node version" src="https://img.shields.io/node/v/@localsummer/incspec?style=flat-square" /></a>
|
|
8
9
|
<a href="./LICENSE"><img alt="License: ISC" src="https://img.shields.io/badge/License-ISC-blue.svg?style=flat-square" /></a>
|
|
9
10
|
</p>
|
package/package.json
CHANGED
package/templates/AGENTS.md
CHANGED
|
@@ -10,8 +10,14 @@ AI 编码助手使用 IncSpec 进行增量规格驱动开发的操作指南。
|
|
|
10
10
|
|
|
11
11
|
**快速模式 (5步)**:
|
|
12
12
|
- 启动: `incspec analyze <path> --quick`
|
|
13
|
-
- 按顺序执行:
|
|
14
|
-
-
|
|
13
|
+
- 按顺序执行:
|
|
14
|
+
- 步骤1: analyze (代码分析)
|
|
15
|
+
- 步骤2: collect-req (需求收集)
|
|
16
|
+
- [跳过步骤3: UI依赖采集]
|
|
17
|
+
- [跳过步骤4: 增量设计]
|
|
18
|
+
- 步骤5: apply (应用代码)
|
|
19
|
+
- 步骤6: merge (合并基线)
|
|
20
|
+
- 步骤7: archive (归档)
|
|
15
21
|
- 适用于: Bug 修复、简单功能、不涉及复杂 UI 依赖的变更
|
|
16
22
|
|
|
17
23
|
**核心约定**:
|
|
@@ -19,13 +25,13 @@ AI 编码助手使用 IncSpec 进行增量规格驱动开发的操作指南。
|
|
|
19
25
|
- 检查状态: `incspec status`
|
|
20
26
|
- 编号引用: `[S1]` 时序步骤, `[D1]` 依赖, `[C1]` 变更
|
|
21
27
|
- 增量标记: `[N1]` 新增, `[S1-Modified]` 修改, `[S1-Deleted]` 删除
|
|
22
|
-
-
|
|
28
|
+
- 验证时机: 步骤 1/4/6 完成后、归档前执行 `incspec validate`，出错时加 `--strict` 用于 CI
|
|
23
29
|
|
|
24
30
|
## 七步工作流
|
|
25
31
|
|
|
26
32
|
```
|
|
27
33
|
完整模式: [1分析] → [2需求] → [3UI依赖] → [4设计] → [5应用] → [6合并] → [7归档] → 循环
|
|
28
|
-
快速模式: [1分析] → [2需求]
|
|
34
|
+
快速模式: [1分析] → [2需求] ─(跳过3,4)─→ [5应用] → [6合并] → [7归档] → 循环
|
|
29
35
|
```
|
|
30
36
|
|
|
31
37
|
### 步骤 1: 分析代码工作流
|
|
@@ -38,6 +44,8 @@ AI 编码助手使用 IncSpec 进行增量规格驱动开发的操作指南。
|
|
|
38
44
|
|
|
39
45
|
**交付物**: Mermaid 时序图 (`[S1]`-`[Sn]`)、依赖图 (`[D1]`-`[Dn]`)、依赖摘要 (`[R1.x]`-`[R3.x]`)
|
|
40
46
|
|
|
47
|
+
**验证**: 完成后执行 `incspec validate` 检查基线格式（必含时序图和依赖图）
|
|
48
|
+
|
|
41
49
|
### 步骤 2: 收集结构化需求
|
|
42
50
|
|
|
43
51
|
**命令**: `incspec collect-req` (别名: `cr`)
|
|
@@ -75,6 +83,8 @@ AI 编码助手使用 IncSpec 进行增量规格驱动开发的操作指南。
|
|
|
75
83
|
6. 潜在风险与副作用
|
|
76
84
|
7. 建议的测试用例 (至少6个)
|
|
77
85
|
|
|
86
|
+
**验证**: 完成后执行 `incspec validate` 检查增量格式（必含5个模块章节）
|
|
87
|
+
|
|
78
88
|
### 步骤 5: 应用代码变更
|
|
79
89
|
|
|
80
90
|
**命令**: `incspec apply [increment-path]` (别名: `ap`)
|
|
@@ -93,12 +103,16 @@ AI 编码助手使用 IncSpec 进行增量规格驱动开发的操作指南。
|
|
|
93
103
|
|
|
94
104
|
**处理**: 移除增量标记 → 合并新节点 → 重新编号为干净序列 → 输出新基线 v{n+1}
|
|
95
105
|
|
|
106
|
+
**验证**: 完成后执行 `incspec validate` 检查新基线完整性
|
|
107
|
+
|
|
96
108
|
### 步骤 7: 归档工作流产出
|
|
97
109
|
|
|
98
110
|
**命令**: `incspec archive [--yes] [<file>] [--keep]`
|
|
99
111
|
|
|
100
112
|
**目的**: 将已完成的工作流产出归档到 `incspec/archives/YYYY-MM/{module}/`
|
|
101
113
|
|
|
114
|
+
**验证**: 归档前执行 `incspec validate` 确保项目健康。归档操作本身会验证文件移动正确性。
|
|
115
|
+
|
|
102
116
|
## 目录结构
|
|
103
117
|
|
|
104
118
|
```
|
|
@@ -31,20 +31,27 @@ description: 设计优先的前端功能增量编码工作流。适用于实现
|
|
|
31
31
|
```
|
|
32
32
|
1. 分析现有代码 → incspec analyze <path> --quick
|
|
33
33
|
2. 收集需求 → incspec collect-req
|
|
34
|
-
3
|
|
35
|
-
4
|
|
36
|
-
5.
|
|
34
|
+
[跳过 3: 依赖收集 - 简单变更无需此步]
|
|
35
|
+
[跳过 4: 增量设计 - 直接基于需求实现]
|
|
36
|
+
5. 应用代码变更 → incspec apply (基于需求文档)
|
|
37
|
+
6. 合并到基线 → incspec merge (重新分析生成)
|
|
38
|
+
7. 归档工作流 → incspec archive --yes
|
|
37
39
|
```
|
|
38
40
|
|
|
39
41
|
首次使用前初始化: `incspec init`
|
|
40
42
|
|
|
41
43
|
## 执行规则
|
|
42
44
|
|
|
43
|
-
|
|
45
|
+
当用户请求满足以下条件时，**立即启动工作流**，无需额外搜索或确认启动意图:
|
|
44
46
|
- 明确指定了模式（完整/快速）
|
|
45
47
|
- 提供了目标路径或基线文件
|
|
46
48
|
- 意图清晰无歧义
|
|
47
49
|
|
|
50
|
+
**重要说明**:
|
|
51
|
+
- "立即启动工作流"指无需确认是否开始执行，但**不跳过**工作流中定义的人工确认点
|
|
52
|
+
- 步骤2(需求收集)和步骤4(增量设计)仍然**必须**等待用户确认后才能继续
|
|
53
|
+
- 步骤7(归档)建议向用户确认归档范围
|
|
54
|
+
|
|
48
55
|
**默认行为**:
|
|
49
56
|
- 未指定模式时，默认使用完整模式
|
|
50
57
|
- 提供 `--baseline=<file>` 时，跳过步骤1的代码分析，直接使用已有基线
|
|
@@ -87,20 +94,21 @@ description: 设计优先的前端功能增量编码工作流。适用于实现
|
|
|
87
94
|
|
|
88
95
|
每个步骤与 `incspec` CLI同步以跟踪工作流状态:
|
|
89
96
|
|
|
90
|
-
| 步骤 | 开始 | 完成 |
|
|
91
|
-
|
|
92
|
-
| 分析 | `incspec analyze <path> --module=<m>` 或 `--baseline=<file>` | `--complete --output=<file>` |
|
|
93
|
-
| 需求 | `incspec collect-req` | `--complete` |
|
|
94
|
-
| 依赖 | `incspec collect-dep` | `--complete` |
|
|
95
|
-
| 设计 | `incspec design --feature=<f>` | `--complete --output=<file>` |
|
|
96
|
-
| 应用 | `incspec apply <report>` | `--complete` |
|
|
97
|
-
| 合并 | `incspec merge <report>` | `--complete --output=<file>` |
|
|
98
|
-
| 归档 | `incspec archive --yes` | - |
|
|
97
|
+
| 步骤 | 模式 | 开始 | 完成 |
|
|
98
|
+
|------|------|------|------|
|
|
99
|
+
| 分析 | 完整/快速 | `incspec analyze <path> --module=<m>` 或 `--baseline=<file>` | `--complete --output=<file>` |
|
|
100
|
+
| 需求 | 完整/快速 | `incspec collect-req` | `--complete` |
|
|
101
|
+
| 依赖 | 仅完整 | `incspec collect-dep` | `--complete` |
|
|
102
|
+
| 设计 | 仅完整 | `incspec design --feature=<f>` | `--complete --output=<file>` |
|
|
103
|
+
| 应用 | 完整/快速 | `incspec apply <report>` | `--complete` |
|
|
104
|
+
| 合并 | 完整/快速 | `incspec merge <report>` | `--complete --output=<file>` |
|
|
105
|
+
| 归档 | 完整/快速 | `incspec archive --yes` | - |
|
|
99
106
|
|
|
100
107
|
管理命令:
|
|
101
108
|
- `incspec status` - 查看工作流状态
|
|
102
109
|
- `incspec list` - 列出规范文件
|
|
103
|
-
- `incspec validate` -
|
|
110
|
+
- `incspec validate` - 验证项目健康状态（步骤1/4/6后、归档前执行）
|
|
111
|
+
- `incspec validate --strict` - 严格模式，有错误时退出码为1（用于CI）
|
|
104
112
|
- `incspec reset` - 重置工作流到初始状态
|
|
105
113
|
- `incspec reset --to=N` - 回退到步骤N，保留1-N，重置N+1至7（示例：`--to=3` 保留1-3，重置4-7）
|
|
106
114
|
|
|
@@ -123,6 +131,8 @@ description: 设计优先的前端功能增量编码工作流。适用于实现
|
|
|
123
131
|
- 组件/Store依赖关系图
|
|
124
132
|
- 数据流摘要
|
|
125
133
|
|
|
134
|
+
**验证:** 完成后执行 `incspec validate` 检查基线格式（必含时序图和依赖图）
|
|
135
|
+
|
|
126
136
|
详见 [references/analyze-codeflow.md](references/analyze-codeflow.md)。
|
|
127
137
|
|
|
128
138
|
### 步骤2: 需求收集
|
|
@@ -165,6 +175,8 @@ description: 设计优先的前端功能增量编码工作流。适用于实现
|
|
|
165
175
|
- 文件修改计划 (新增/修改/删除)
|
|
166
176
|
- 分步实现指导
|
|
167
177
|
|
|
178
|
+
**验证:** 完成后执行 `incspec validate` 检查增量格式（必含5个模块章节）
|
|
179
|
+
|
|
168
180
|
详见 [references/analyze-increment-codeflow.md](references/analyze-increment-codeflow.md)。
|
|
169
181
|
|
|
170
182
|
### 步骤5: 代码应用
|
|
@@ -188,6 +200,8 @@ description: 设计优先的前端功能增量编码工作流。适用于实现
|
|
|
188
200
|
|
|
189
201
|
**输出:** 代表当前系统状态的干净基线(无增量标记)
|
|
190
202
|
|
|
203
|
+
**验证:** 完成后执行 `incspec validate` 检查新基线完整性
|
|
204
|
+
|
|
191
205
|
详见 [references/merge-to-baseline.md](references/merge-to-baseline.md)。
|
|
192
206
|
|
|
193
207
|
### 步骤7: 归档
|
|
@@ -203,6 +217,8 @@ incspec archive <file> --yes # 归档指定文件
|
|
|
203
217
|
incspec archive <file> --keep # 复制而非移动
|
|
204
218
|
```
|
|
205
219
|
|
|
220
|
+
**验证:** 归档前执行 `incspec validate` 确保项目健康，归档后再次验证确保文件移动正确
|
|
221
|
+
|
|
206
222
|
详见 [references/inc-archive.md](references/inc-archive.md)。
|
|
207
223
|
|
|
208
224
|
## 最佳实践
|
|
@@ -220,10 +236,12 @@ incspec archive <file> --keep # 复制而非移动
|
|
|
220
236
|
- 仅在变更范围明确、不涉及复杂依赖时使用快速模式
|
|
221
237
|
|
|
222
238
|
**验证节点:**
|
|
239
|
+
- 步骤1后: `incspec validate` 检查基线格式（必含时序图和依赖图）
|
|
223
240
|
- 步骤2后: 需求中无模糊术语
|
|
224
|
-
- 步骤4后 (完整模式): 编码前审查蓝图
|
|
241
|
+
- 步骤4后 (完整模式): `incspec validate` 检查增量格式 + 编码前审查蓝图
|
|
225
242
|
- 步骤5后: 验证所有文件已正确创建/修改
|
|
226
|
-
- 步骤
|
|
243
|
+
- 步骤6后: `incspec validate` 检查新基线完整性
|
|
244
|
+
- 步骤7前后: 归档前后各执行 `incspec validate` 确保项目健康
|
|
227
245
|
|
|
228
246
|
**工作流重置:**
|
|
229
247
|
- 完全重置: `incspec reset` - 归档所有产出，回到初始状态
|
|
@@ -270,7 +288,7 @@ incspec archive <file> --keep # 复制而非移动
|
|
|
270
288
|
|
|
271
289
|
## 使用示例
|
|
272
290
|
|
|
273
|
-
|
|
291
|
+
**完整任务模式:** 为产品仪表板添加筛选功能
|
|
274
292
|
|
|
275
293
|
```
|
|
276
294
|
步骤1: 分析产品仪表板代码流程
|