dev-playbooks-cn 1.0.4 → 1.0.5
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/package.json
CHANGED
|
@@ -21,18 +21,75 @@ tools:
|
|
|
21
21
|
|
|
22
22
|
- `<truth-root>`：当前真理目录根
|
|
23
23
|
- `<change-root>`：变更包目录根
|
|
24
|
+
- `<devbooks-root>`：DevBooks 管理目录（通常是 `dev-playbooks/`）
|
|
24
25
|
|
|
25
26
|
执行前**必须**按以下顺序查找配置（找到后停止）：
|
|
26
27
|
1. `.devbooks/config.yaml`（如存在）→ 解析并使用其中的映射
|
|
27
28
|
2. `dev-playbooks/project.md`（如存在）→ DevBooks 2.0 协议，使用默认映射
|
|
28
29
|
4. `project.md`（如存在）→ template 协议，使用默认映射
|
|
29
|
-
5. 若仍无法确定 →
|
|
30
|
+
5. 若仍无法确定 → **创建 DevBooks 目录结构并初始化基础配置**
|
|
30
31
|
|
|
31
32
|
**关键约束**：
|
|
32
33
|
- 如果配置中指定了 `agents_doc`（规则文档），**必须先阅读该文档**再执行任何操作
|
|
33
34
|
- 禁止猜测目录根
|
|
34
35
|
- 禁止跳过规则文档阅读
|
|
35
36
|
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## 核心职责
|
|
40
|
+
|
|
41
|
+
存量项目初始化包含以下职责：
|
|
42
|
+
|
|
43
|
+
### 1. 基础配置文件初始化（新增）
|
|
44
|
+
|
|
45
|
+
在 `<devbooks-root>/`（通常是 `dev-playbooks/`）下检查并创建：
|
|
46
|
+
|
|
47
|
+
| 文件 | 用途 | 创建条件 |
|
|
48
|
+
|------|------|----------|
|
|
49
|
+
| `constitution.md` | 项目宪法（GIP 原则） | 文件不存在时 |
|
|
50
|
+
| `project.md` | 项目上下文（技术栈/约定） | 文件不存在时 |
|
|
51
|
+
|
|
52
|
+
**创建方式**：
|
|
53
|
+
- **不是简单复制模板**，而是根据代码分析结果定制内容
|
|
54
|
+
- `constitution.md`：基于默认 GIP 原则，可根据项目特性调整
|
|
55
|
+
- `project.md`：根据代码分析结果填充：
|
|
56
|
+
- 技术栈（语言/框架/数据库）
|
|
57
|
+
- 开发约定（代码风格/测试策略/Git 工作流）
|
|
58
|
+
- 领域上下文（核心概念/角色定义）
|
|
59
|
+
- 目录根映射
|
|
60
|
+
|
|
61
|
+
### 2. 项目画像与元数据
|
|
62
|
+
|
|
63
|
+
在 `<truth-root>/_meta/` 下生成：
|
|
64
|
+
|
|
65
|
+
| 产物 | 路径 | 说明 |
|
|
66
|
+
|------|------|------|
|
|
67
|
+
| 项目画像 | `_meta/project-profile.md` | 三层架构的详细技术画像 |
|
|
68
|
+
| 术语表 | `_meta/glossary.md` | 统一语言表（可选但推荐） |
|
|
69
|
+
| 领域概念 | `_meta/key-concepts.md` | CKB 提取的概念（增强模式） |
|
|
70
|
+
|
|
71
|
+
### 3. 架构分析产物
|
|
72
|
+
|
|
73
|
+
在 `<truth-root>/architecture/` 下生成：
|
|
74
|
+
|
|
75
|
+
| 产物 | 路径 | 数据来源 |
|
|
76
|
+
|------|------|----------|
|
|
77
|
+
| 模块依赖图 | `architecture/module-graph.md` | `mcp__ckb__getArchitecture` |
|
|
78
|
+
| 技术债热点 | `architecture/hotspots.md` | `mcp__ckb__getHotspots` |
|
|
79
|
+
|
|
80
|
+
### 4. 基线变更包
|
|
81
|
+
|
|
82
|
+
在 `<change-root>/<baseline-id>/` 下生成：
|
|
83
|
+
|
|
84
|
+
| 产物 | 说明 |
|
|
85
|
+
|------|------|
|
|
86
|
+
| `proposal.md` | 基线范围、In/Out、风险 |
|
|
87
|
+
| `design.md` | 现状盘点（capability inventory） |
|
|
88
|
+
| `specs/<cap>/spec.md` | 基线 spec deltas（ADDED 为主） |
|
|
89
|
+
| `verification.md` | 最小验证锚点计划 |
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
36
93
|
## COD 模型生成（Code Overview & Dependencies）
|
|
37
94
|
|
|
38
95
|
在初始化时自动生成项目的"代码地图"（需要 CKB MCP Server 可用，否则跳过）：
|
|
@@ -101,15 +158,19 @@ tools:
|
|
|
101
158
|
|
|
102
159
|
### 检测流程
|
|
103
160
|
|
|
104
|
-
1. 检测 `<
|
|
105
|
-
2. 检测
|
|
106
|
-
3.
|
|
161
|
+
1. 检测 `<devbooks-root>/constitution.md` 是否存在
|
|
162
|
+
2. 检测 `<devbooks-root>/project.md` 是否存在
|
|
163
|
+
3. 检测 `<truth-root>/` 是否为空或基本为空
|
|
164
|
+
4. 检测 CKB 索引是否可用
|
|
165
|
+
5. 检测项目规模和语言栈
|
|
107
166
|
|
|
108
167
|
### 本 Skill 支持的模式
|
|
109
168
|
|
|
110
169
|
| 模式 | 触发条件 | 行为 |
|
|
111
170
|
|------|----------|------|
|
|
112
|
-
|
|
|
171
|
+
| **全新初始化** | devbooks-root 不存在或为空 | 创建完整目录结构 + constitution + project + 画像 |
|
|
172
|
+
| **补充配置** | constitution/project 缺失 | 只补充缺失的配置文件 |
|
|
173
|
+
| **完整初始化** | truth-root 为空 | 生成所有基础产物（画像/基线/验证） |
|
|
113
174
|
| **增量初始化** | truth-root 部分存在 | 只补充缺失产物 |
|
|
114
175
|
| **增强模式** | CKB 索引可用 | 使用图分析生成更精确的画像 |
|
|
115
176
|
| **基础模式** | CKB 索引不可用 | 使用传统分析方法 |
|
|
@@ -118,10 +179,13 @@ tools:
|
|
|
118
179
|
|
|
119
180
|
```
|
|
120
181
|
检测结果：
|
|
182
|
+
- devbooks-root：存在
|
|
183
|
+
- constitution.md：不存在 → 将创建
|
|
184
|
+
- project.md：不存在 → 将创建
|
|
121
185
|
- truth-root：为空
|
|
122
186
|
- CKB 索引：可用
|
|
123
187
|
- 项目规模：中型（~50K LOC）
|
|
124
|
-
-
|
|
188
|
+
- 运行模式：补充配置 + 完整初始化 + 增强模式
|
|
125
189
|
```
|
|
126
190
|
|
|
127
191
|
---
|
|
@@ -6,18 +6,20 @@
|
|
|
6
6
|
- 在执行本提示词前，先阅读 `_shared/references/通用守门协议.md` 并遵循其中所有协议。
|
|
7
7
|
|
|
8
8
|
目录根（强制）：
|
|
9
|
-
- 在写任何文件前，必须先确定 `<truth-root>` 与 `<change-root>` 的实际路径；禁止猜测。
|
|
10
|
-
- 若存在 `dev-playbooks
|
|
9
|
+
- 在写任何文件前，必须先确定 `<devbooks-root>`、`<truth-root>` 与 `<change-root>` 的实际路径；禁止猜测。
|
|
10
|
+
- 若存在 `dev-playbooks/` 目录：视为 DevBooks 项目，默认：
|
|
11
|
+
- `<devbooks-root>` = `dev-playbooks/`
|
|
11
12
|
- `<truth-root>` = `dev-playbooks/specs`
|
|
12
13
|
- `<change-root>` = `dev-playbooks/changes`
|
|
13
|
-
-
|
|
14
|
-
-
|
|
14
|
+
- 如存在 `dev-playbooks/project.md`：必须先阅读并遵循其中说明。
|
|
15
|
+
- 否则：必须先询问用户确认目录根；用户未确认不得落盘。
|
|
15
16
|
|
|
16
|
-
|
|
17
|
-
1)
|
|
18
|
-
2)
|
|
17
|
+
你是"存量项目初始化负责人（Brownfield Bootstrapper）"。你的任务是在**存量项目**中，当 `<truth-root>/` 为空或缺失时，一次性补齐：
|
|
18
|
+
1) **基础配置文件**（constitution.md、project.md）
|
|
19
|
+
2) 项目画像与约定（技术栈/命令/边界/闸门/契约入口）
|
|
20
|
+
3) 现状规格基线（baseline specs，以 ADDED 为主）
|
|
19
21
|
|
|
20
|
-
|
|
22
|
+
最终效果：后续任何变更都能像"项目从一开始就按规格化流程开发"一样，有稳定真理源、稳定落点与可验证锚点。
|
|
21
23
|
|
|
22
24
|
输入材料（由我提供）：
|
|
23
25
|
- 代码库（只读分析，允许运行只读命令）
|
|
@@ -26,6 +28,9 @@
|
|
|
26
28
|
- 我指定的基线范围（对外契约优先/关键链路优先/模块边界优先）
|
|
27
29
|
|
|
28
30
|
产物目标（目录约定，协议无关）：
|
|
31
|
+
- **基础配置文件**（如缺失则创建）：
|
|
32
|
+
- `<devbooks-root>/constitution.md`：项目宪法（GIP 原则）
|
|
33
|
+
- `<devbooks-root>/project.md`：项目上下文（技术栈/约定/领域）
|
|
29
34
|
- 项目画像（当前真理的一部分）：
|
|
30
35
|
- `<truth-root>/_meta/project-profile.md`
|
|
31
36
|
- 统一语言表（可选但推荐）：
|
|
@@ -33,21 +38,83 @@
|
|
|
33
38
|
- 变更包：`<change-root>/<baseline-id>/`
|
|
34
39
|
- `proposal.md`：基线范围、为什么先做基线、In/Out、风险与未知
|
|
35
40
|
- `design.md`（可选但推荐）：现状盘点（capability inventory）与边界/依赖方向
|
|
36
|
-
-
|
|
41
|
+
- `specs/<capability>/spec.md`：基线 spec deltas（只用 ADDED Requirements）
|
|
37
42
|
- `verification.md`：最小验证锚点计划 + 追溯矩阵 + MANUAL-*
|
|
38
|
-
- 当前真理源：`<truth-root
|
|
43
|
+
- 当前真理源：`<truth-root>/`（本阶段先不直接写入；由后续"归档/合并"动作把基线变更合并进去）
|
|
39
44
|
|
|
40
45
|
硬约束（必须遵守）：
|
|
41
46
|
1) **只写现状，不做重构**：本次初始化不引入行为变化建议，不输出实现计划。
|
|
42
47
|
2) **基线 delta 以 ADDED 为主**：当 `<truth-root>/` 为空时，优先只写 ADDED，避免 MODIFIED/RENAMED/REMOVED（这些通常要求已有当前真理）。
|
|
43
48
|
3) **delta 格式必须匹配项目所用协议的校验器**：
|
|
44
|
-
-
|
|
49
|
+
- 先在仓库里查找"delta 标题/场景标题"的既有模板或约定（例如搜索 `ADDED Requirements`/`新增需求`/`Scenario:`/`场景：`）
|
|
45
50
|
- 若仍不确定：不要臆测；在 `<truth-root>/_meta/project-profile.md` 标注 `TBD` 并给出验证动作（例如运行协议的 validate 命令）
|
|
46
51
|
4) **证据优先**：任何不确定的地方必须标注 `TBD`，并在 `verification.md` 写清验证动作；禁止臆测补齐。
|
|
47
52
|
5) **MECE 聚类**：capability 控制在 3–8 个；每个 capability 的 Requirements 控制在 3–15 条（先薄后厚）。
|
|
48
53
|
6) **每条 Requirement 至少 1 个 Scenario**，并尽量在 Scenario 末尾补一行 Evidence（指向代码入口/测试/命令/日志关键字）。
|
|
49
54
|
7) **遗留安全网优先**：若后续计划涉及重构/迁移，`verification.md` 中优先加入 Snapshot/Golden Master 测试策略。
|
|
50
55
|
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## `constitution.md` 创建要求
|
|
59
|
+
|
|
60
|
+
当 `<devbooks-root>/constitution.md` 不存在时，必须创建。
|
|
61
|
+
|
|
62
|
+
**内容要求**：
|
|
63
|
+
1) 包含 Part Zero（强制指令）
|
|
64
|
+
2) 包含 GIP-01 到 GIP-04（角色隔离/测试不可篡改/设计优先/真理源唯一）
|
|
65
|
+
3) 包含逃生舱口（紧急修复/原型验证/人工裁决）
|
|
66
|
+
4) 可根据项目特性新增项目特有的 GIP（如 GIP-05），但不得删除核心 GIP
|
|
67
|
+
|
|
68
|
+
**推荐结构**：
|
|
69
|
+
```markdown
|
|
70
|
+
# 项目宪法 (Project Constitution)
|
|
71
|
+
|
|
72
|
+
## Part Zero: 强制指令
|
|
73
|
+
## 全局不可违背原则 (Global Inviolable Principles)
|
|
74
|
+
### GIP-01: 角色隔离原则
|
|
75
|
+
### GIP-02: 测试不可篡改原则
|
|
76
|
+
### GIP-03: 设计优先原则
|
|
77
|
+
### GIP-04: 真理源唯一原则
|
|
78
|
+
### GIP-05: [项目特有原则，可选]
|
|
79
|
+
## 逃生舱口 (Escape Hatches)
|
|
80
|
+
## 宪法变更流程
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## `project.md` 创建要求
|
|
86
|
+
|
|
87
|
+
当 `<devbooks-root>/project.md` 不存在时，必须创建。
|
|
88
|
+
|
|
89
|
+
**内容要求**（根据代码分析结果填充）：
|
|
90
|
+
1) 目的：项目的核心目标
|
|
91
|
+
2) 技术栈：从 package.json/go.mod/pom.xml/requirements.txt 等推断
|
|
92
|
+
3) 项目约定：代码风格/架构模式/测试策略/Git 工作流
|
|
93
|
+
4) 领域上下文：核心概念/角色定义
|
|
94
|
+
5) 重要约束：角色隔离等
|
|
95
|
+
6) 目录根映射：truth-root/change-root 的路径
|
|
96
|
+
|
|
97
|
+
**推荐结构**：
|
|
98
|
+
```markdown
|
|
99
|
+
# 项目上下文 (Project Context)
|
|
100
|
+
|
|
101
|
+
## 目的
|
|
102
|
+
## 技术栈
|
|
103
|
+
## 项目约定
|
|
104
|
+
### 代码风格
|
|
105
|
+
### 架构模式
|
|
106
|
+
### 测试策略
|
|
107
|
+
### Git 工作流
|
|
108
|
+
## 领域上下文
|
|
109
|
+
### 核心概念
|
|
110
|
+
### 角色定义
|
|
111
|
+
## 重要约束
|
|
112
|
+
## 外部依赖
|
|
113
|
+
## 目录根映射
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
51
118
|
`<truth-root>/_meta/project-profile.md` 写作要求（必须遵守）：
|
|
52
119
|
1) 只写你能从仓库证据推导出的结论；不确定必须标注 `TBD` 并给出验证动作（命令/文件路径/下一步）。
|
|
53
120
|
2) 不改业务代码、不改 tests、不引入依赖；你只产出文档。
|
|
@@ -99,17 +166,19 @@
|
|
|
99
166
|
|
|
100
167
|
输出要求（按顺序）：
|
|
101
168
|
1) 先输出你将创建/更新的文件路径清单（只列路径）
|
|
102
|
-
2)
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
4)
|
|
106
|
-
5)
|
|
107
|
-
6) 输出 `
|
|
108
|
-
7)
|
|
169
|
+
2) 若 `<devbooks-root>/constitution.md` 不存在：输出其内容（Markdown）
|
|
170
|
+
3) 若 `<devbooks-root>/project.md` 不存在：输出其内容（Markdown），根据代码分析结果填充
|
|
171
|
+
4) 输出 `<truth-root>/_meta/project-profile.md` 内容（Markdown）
|
|
172
|
+
4.1) 若能从仓库识别稳定术语：输出 `<truth-root>/_meta/glossary.md` 草案
|
|
173
|
+
5) 输出 `proposal.md` 内容（Markdown）
|
|
174
|
+
6) 输出 `design.md` 内容（若你认为必要；否则输出"不需要"的理由）
|
|
175
|
+
7) 对每个 capability 输出 `<change-root>/<baseline-id>/specs/<capability>/spec.md` 的 delta 内容（优先只包含 ADDED Requirements）
|
|
176
|
+
8) 输出 `verification.md` 草案（至少包含：主线计划区、追溯矩阵、MANUAL-*）
|
|
177
|
+
9) 最后给出一个"合并建议"：如何把本基线变更合并进 `<truth-root>/`（如果你知道项目使用的协议命令，可以顺带给出命令；不知道就给出人工合并步骤）
|
|
109
178
|
|
|
110
179
|
现在开始执行，不要输出额外解释。
|
|
111
180
|
|
|
112
181
|
注意事项：
|
|
113
|
-
- 本文档中的 `<truth-root>` 与 `<change-root>` 是**占位符**，实际取值必须来自项目的上下文协议/指路牌。
|
|
114
|
-
- DevBooks 项目默认取值：`dev-playbooks/specs` 与 `dev-playbooks/changes`。
|
|
182
|
+
- 本文档中的 `<devbooks-root>`、`<truth-root>` 与 `<change-root>` 是**占位符**，实际取值必须来自项目的上下文协议/指路牌。
|
|
183
|
+
- DevBooks 项目默认取值：`dev-playbooks/`、`dev-playbooks/specs` 与 `dev-playbooks/changes`。
|
|
115
184
|
- 只有在用户明确确认时才允许使用默认 `specs/` 与 `changes/`。
|