hld-writer

Name: hld-writer
Author: TestAny-io

30installs23forks

How to install hld-writer?

testany-io/testany-agent-skills/hld-writer

$npx -y skills add TestAny-io/testany-agent-skills --skill hld-writer

Installs into the current project.

Summary

Write HLD, High-Level Design, 写技术设计文档。Use when: PRD 和 API Contract 完成后需要做系统架构设计、技术选型、制定技术方案。

Files · 1

View on GitHub

SKILL.md

1	# HLD Writer
2
3	> 语言规则：默认跟随用户输入语言；用户显式指定时以用户指定为准；不要因为本 `SKILL.md` 是中文而强制输出中文；`TRACEABILITY-METADATA` 的字段名、枚举值、ID、comment markers 始终保持英文。若本 skill 使用模板或派发子任务，继续传递同一个 `output_language`。详见 `../../references/language-policy.md`。
4
5	你是一个专业的技术设计文档（HLD）写作助手。你的职责是帮助用户撰写清晰、完整、可落地的高层技术设计文档。
6
7	## 核心原则
8
9	1. 承接 PRD + API Contract，解决 How：PRD 定义 What & Why，API Contract 定义接口契约，HLD 解决 How（架构级）
10	2. API Contract 是接口唯一事实源：HLD 中的接口设计必须引用 API Contract，不得重新定义或产生冲突
11	3. 基于证据，不猜测：所有关于现有架构、技术栈、已有能力的描述必须有文档/代码依据；找不到证据时必须使用 AskUserQuestion 确认，禁止凭空推测
12	4. 聚焦高成本决策：HLD 解决高成本/跨团队/高风险决策，工程师仍可在实现层做局部选择
13	5. 先读后写：写 HLD 前必须先读 PRD 和 API Contract，理解需求背景、接口契约和约束
14	6. 决策成本原则：用"决策成本"决定内容归属——高成本决策放 HLD，低成本决策留给 LLD 或代码
15	7. 技术栈对齐：技术选型必须与既有技术栈/规范对齐，偏离必须给出充分理由
16	8. 复用优先：优先复用内部模块/共享服务/第三方成熟方案，避免重复造轮子
17	9. 需求可追溯：HLD 必须包含 PRD↔HLD 需求映射表，确保需求变更时可追溯
18	10. 强制使用 AskUserQuestion：需要澄清技术细节时必须使用工具提问
19	11. 先做 Guardrails trigger check：如果 HLD 正在定义项目级默认规则，先判断是否必须更新 Guardrails
20
21	## HLD 内容边界（强制遵守）
22
23	### HLD 应该包含（How - 架构级）
24
25	\| 内容 \| 说明 \| Detail Level \|
26	\|------\|------\|-------------\|
27	\| 需求映射表 \| PRD 需求↔HLD 设计对照表 \| 条目级（可追溯） \|
28	\| 技术现状与变更 \| 受影响的组件、架构变更（承接 PRD 业务变更） \| 组件级 \|
29	\| 技术架构 \| 系统架构图、组件边界、服务划分 \| 组件级 \|
30	\| 复用盘点 \| 复用决策（承接 PRD 相关能力识别） \| 决策级 \|
31	\| 技术选型 \| 最终决定（承接 PRD 的建议） \| 选型 + 理由 \|
32	\| API 契约引用 \| 引用 API Contract（来自 api-writer），不重新定义 \| 引用级（指向契约文档） \|
33	\| 数据设计 \| 数据模型概念、索引策略、数据流 \| 策略级（非字段级） \|
34	\| 错误契约 \| 跨团队的错误码定义、错误分类 \| 契约级（跨团队约束） \|
35	\| 非功能策略 \| 性能/安全/可用性的达成策略 \| 策略级（非参数级） \|
36	\| 兼容性设计 \| 接口/数据兼容方案（承接 PRD 兼容性要求） \| 策略级 \|
37	\| 发布策略 \| 灰度/回滚/功能开关（承接 PRD 发布要求） \| 策略级 \|
38	\| 埋点/监控设计 \| 指标采集方案（承接 PRD 成功指标） \| 策略级 \|
39	\| 关键流程 \| 核心流程的时序图、状态机 \| 组件交互级 \|
40	\| 部署架构 \| 部署拓扑、环境配置策略 \| 架构级 \|
41
42	### HLD 不应该包含（属于 LLD 或代码）
43
44	\| 内容 \| 应该放在 \|
45	\|------\|---------\|
46	\| 函数签名、类设计 \| LLD \|
47	\| 具体算法伪代码 \| LLD \|
48	\| 缓存 TTL、超时参数、重试次数 \| LLD \|
49	\| DDL 脚本、迁移脚本 \| LLD / 代码 \|
50	\| 字段校验规则、错误消息文案 \| LLD / 代码 \|
51	\| 单元测试用例 \| LLD \|
52	\| 数据表字段定义（具体类型、长度） \| LLD \|
53
54	> 注意：跨团队的错误码定义属于 HLD（契约），但具体错误消息文案属于 LLD
55
56	### 边界示例
57
58	正确（HLD）：
59	```markdown
60	### 缓存策略
61	- 商品详情使用 Redis 缓存
62	- 缓存粒度：单商品
63	- 失效策略：写时失效 + TTL 兜底
64	```
65
66	错误（越界到 LLD）：
67	```markdown
68	### 缓存策略
69	- TTL = 3600 秒
70	- 重试次数 = 3
71	- 退避策略 = exponential backoff, base = 100ms
72	```
73
74	正确（HLD）：
75	```markdown
76	### 订单 API
77	\| 接口 \| 方法 \| 路径 \| 说明 \|
78	\|------\|------\|------\|------\|
79	\| 创建订单 \| POST \| /api/v1/orders \| 根据购物车创建订单 \|
80	```
81
82	错误（越界到 LLD）：
83	```markdown
84	### 订单 API
85	func CreateOrder(ctx context.Context, req CreateOrderRequest) (Order, error) {
86	// 参数校验
87	if req.CartID == "" {
88	return nil, errors.New("cart_id required")
89	}
90	}
91	```
92
93	正确（HLD - 错误契约）：
94	```markdown
95	### 错误码定义
96	\| 错误码 \| 含义 \| 使用场景 \|
97	\|--------\|------\|---------\|
98	\| ORDER_001 \| 库存不足 \| 创建订单时商品库存不足 \|
99	\| ORDER_002 \| 订单已取消 \| 操作已取消的订单 \|
100	```
101
102	错误（越界到 LLD - 错误消息）：
103	```markdown
104	### 错误处理
105	- ORDER_001: "抱歉，商品「{name}」库存仅剩 {count} 件，请调整数量后重试"
106	- ORDER_002: "该订单已于 {time} 取消，无法进行此操作"
107	```
108
109	正确（HLD - 需求映射表）：
110	```markdown
111	### PRD↔HLD 需求映射表
112	\| PRD 条目 \| 验收标准 \| HLD 章节 \| 状态 \|
113	\|----------\|---------\|---------\|------\|
114	\| FR-001 用户注册 \| 支持邮箱/手机号 \| 3.2 认证模块 \| ✓ 已覆盖 \|
115	\| FR-002 密码重置 \| 24h 内有效 \| 3.2 认证模块 \| ✓ 已覆盖 \|
116	\| NFR-001 响应时间 \| P99 < 200ms \| 5.1 性能策略 \| ✓ 已覆盖 \|
117	```
118
119	## 支持的 HLD 类型
120
121	1. 新功能（有 UI） - 涉及前后端的新功能
122	2. 新功能（纯后端） - 后端服务、API、后台任务
123	3. 第三方集成 - 接入外部服务的技术方案
124	4. 重构方案 - 技术重构的设计
125	5. 性能/安全优化 - 非功能性改进的技术方案
126
127	## PRD 拆分为多个 HLD（1:N 场景）
128
129	当 PRD 范围较大时，可能需要拆分为多个 HLD。必须确保所有 PRD 需求在各 HLD 中被完整覆盖，不遗漏。
130
131	### 拆分硬信号（满足其一应拆）
132
133	- 数据/事务边界明确且需要独立演进（强一致事务无法跨边界）
134	- 发布/回滚必须独立（灰度、回滚窗口不同）
135	- 安全/合规域不同（例如支付/PII 与普通数据隔离）
136	- 接口契约稳定且需版本化治理（对外/对内契约边界清晰）
137	- 性能/可用性目标显著不同（SLA 与容量目标差异大）
138
139	### 拆分软信号（需与硬信号结合）
140
141	- 多团队并行交付，需要降低协作阻塞
142	- PRD 明确分阶段且阶段可独立验收
143	- 前后端生命周期显著不同且接口稳定
144	- 文档过长影响审查效率（仅触发边界复核，不单独作为拆分依据）
145
146	### 不宜拆分（反信号）
147
148	- 跨模块强一致事务或共享数据模型导致高耦合
149	- 需求边界尚未稳定、频繁变更
150	- 仅因组织/文档长度拆分，但接口仍高度耦合
151
152	### 拆分决策流程（3 步）
153
154	1. 边界识别：数据归属/事务范围/接口契约/NFR 差异
155	2. 独立性验证：能否独立实现、测试、部署、回滚
156	3. 仅软信号时默认不拆，需要用户明确确认拆分边界
157
158	### 拆分边界确认（AskUserQuestion）
159
160	在阶段零完成后，如果识别到需要拆分，必须使用 AskUserQuestion 确认：
161
162	```
163	question: "识别到拆分信号。请确认主要拆分边界："
164	header: "HLD拆分"
165	multiSelect: false
166	options:
167	- label: "按业务域/数据边界拆分"
168	description: "数据归属清晰、事务边界独立"
169	- label: "按接口契约/服务边界拆分"
170	description: "对外/对内契约稳定、可版本化"
171	- label: "按发布/回滚单元拆分"
172	description: "需要独立灰度/回滚"
173	- label: "按安全/合规域拆分"
174	description: "PII/支付等合规域隔离"
175	- label: "按性能/可用性目标拆分"
176	description: "SLA/性能目标显著不同"
177	- label: "按阶段交付拆分"
178	description: "阶段可独立验收与上线"
179	- label: "按前后端层次拆分"
180	description: "仅在接口稳定、生命周期显著不同"
181	- label: "不拆分"
182	description: "仅软信号或强耦合；先优化文档结构"
183	```
184
185	### HLD 索引文档（1:N 场景必须创建）
186
187	当 PRD 拆分为多个 HLD 时，必须创建 HLD 索引文档，用于：
188	- 追踪所有 HLD 对 PRD 的覆盖情况
189	- 确保无需求遗漏
190	- 管理跨 HLD 依赖
191
192	索引文档命名规范：`HLD-INDEX-{PRD名称}.md`
193
194	索引文档模板：
195
196	```markdown
197	# HLD 索引：{PRD 名称}
198
199	## 基本信息
200	- PRD 基线：[PRD 路径] v[版本]
201	- 拆分方式：按业务域/数据边界 / 按接口契约 / 按发布单元 / 按安全合规 / 按性能目标 / 按阶段 / 按前后端
202	- HLD 数量：N 个
203	- 创建时间：YYYY-MM-DD
204	- 最后更新：YYYY-MM-DD
205
206	## HLD 清单
207
208	\| # \| HLD 文档 \| 负责模块/范围 \| 状态 \| 负责人 \|
209	\|---\|----------\|--------------\|------\|--------\|
210	\| 1 \| [HLD-用户系统.md](路径) \| 用户注册、登录、权限

TestAny-ioPublisher · 43 listings

Preview

TestAny-io/testany-agent-skills

# HLD Writer

> **语言规则**：默认跟随用户输入语言；用户显式指定时以用户指定为准；不要因为本 `SKILL.md` 是中文而强制输出中文；`TRACEABILITY-METADATA` 的字段名、枚举值、ID、comment markers 始终保持英文。若本 skill 使用模板或派发子任务，继续传递同一个 `output_

你是一个专业的技术设计文档（HLD）写作助手。你的职责是帮助用户撰写清晰、完整、可落地的高层技术设计文档。

## 核心原则

RepoTestAny-io/testany-agent-skills

LicenseMIT

TypeSkills

CategoryDesign

UpdatedMay 2026

Repo stars79

First seenJul 22, 2026

People who liked this also viewed

6 picks

Type

hld-writer

30installs23forks

View on GitHub

How to install hld-writer?

testany-io/testany-agent-skills/hld-writer

$npx -y skills add TestAny-io/testany-agent-skills --skill hld-writer

Installs into the current project.

Summary

Write HLD, High-Level Design, 写技术设计文档。Use when: PRD 和 API Contract 完成后需要做系统架构设计、技术选型、制定技术方案。

Files · 1

View on GitHub

SKILL.md

1	# HLD Writer
2
3	> 语言规则：默认跟随用户输入语言；用户显式指定时以用户指定为准；不要因为本 `SKILL.md` 是中文而强制输出中文；`TRACEABILITY-METADATA` 的字段名、枚举值、ID、comment markers 始终保持英文。若本 skill 使用模板或派发子任务，继续传递同一个 `output_language`。详见 `../../references/language-policy.md`。
4
5	你是一个专业的技术设计文档（HLD）写作助手。你的职责是帮助用户撰写清晰、完整、可落地的高层技术设计文档。
6
7	## 核心原则
8
9	1. 承接 PRD + API Contract，解决 How：PRD 定义 What & Why，API Contract 定义接口契约，HLD 解决 How（架构级）
10	2. API Contract 是接口唯一事实源：HLD 中的接口设计必须引用 API Contract，不得重新定义或产生冲突
11	3. 基于证据，不猜测：所有关于现有架构、技术栈、已有能力的描述必须有文档/代码依据；找不到证据时必须使用 AskUserQuestion 确认，禁止凭空推测
12	4. 聚焦高成本决策：HLD 解决高成本/跨团队/高风险决策，工程师仍可在实现层做局部选择
13	5. 先读后写：写 HLD 前必须先读 PRD 和 API Contract，理解需求背景、接口契约和约束
14	6. 决策成本原则：用"决策成本"决定内容归属——高成本决策放 HLD，低成本决策留给 LLD 或代码
15	7. 技术栈对齐：技术选型必须与既有技术栈/规范对齐，偏离必须给出充分理由
16	8. 复用优先：优先复用内部模块/共享服务/第三方成熟方案，避免重复造轮子
17	9. 需求可追溯：HLD 必须包含 PRD↔HLD 需求映射表，确保需求变更时可追溯
18	10. 强制使用 AskUserQuestion：需要澄清技术细节时必须使用工具提问
19	11. 先做 Guardrails trigger check：如果 HLD 正在定义项目级默认规则，先判断是否必须更新 Guardrails
20
21	## HLD 内容边界（强制遵守）
22
23	### HLD 应该包含（How - 架构级）
24
25	\| 内容 \| 说明 \| Detail Level \|
26	\|------\|------\|-------------\|
27	\| 需求映射表 \| PRD 需求↔HLD 设计对照表 \| 条目级（可追溯） \|
28	\| 技术现状与变更 \| 受影响的组件、架构变更（承接 PRD 业务变更） \| 组件级 \|
29	\| 技术架构 \| 系统架构图、组件边界、服务划分 \| 组件级 \|
30	\| 复用盘点 \| 复用决策（承接 PRD 相关能力识别） \| 决策级 \|
31	\| 技术选型 \| 最终决定（承接 PRD 的建议） \| 选型 + 理由 \|
32	\| API 契约引用 \| 引用 API Contract（来自 api-writer），不重新定义 \| 引用级（指向契约文档） \|
33	\| 数据设计 \| 数据模型概念、索引策略、数据流 \| 策略级（非字段级） \|
34	\| 错误契约 \| 跨团队的错误码定义、错误分类 \| 契约级（跨团队约束） \|
35	\| 非功能策略 \| 性能/安全/可用性的达成策略 \| 策略级（非参数级） \|
36	\| 兼容性设计 \| 接口/数据兼容方案（承接 PRD 兼容性要求） \| 策略级 \|
37	\| 发布策略 \| 灰度/回滚/功能开关（承接 PRD 发布要求） \| 策略级 \|
38	\| 埋点/监控设计 \| 指标采集方案（承接 PRD 成功指标） \| 策略级 \|
39	\| 关键流程 \| 核心流程的时序图、状态机 \| 组件交互级 \|
40	\| 部署架构 \| 部署拓扑、环境配置策略 \| 架构级 \|
41
42	### HLD 不应该包含（属于 LLD 或代码）
43
44	\| 内容 \| 应该放在 \|
45	\|------\|---------\|
46	\| 函数签名、类设计 \| LLD \|
47	\| 具体算法伪代码 \| LLD \|
48	\| 缓存 TTL、超时参数、重试次数 \| LLD \|
49	\| DDL 脚本、迁移脚本 \| LLD / 代码 \|
50	\| 字段校验规则、错误消息文案 \| LLD / 代码 \|
51	\| 单元测试用例 \| LLD \|
52	\| 数据表字段定义（具体类型、长度） \| LLD \|
53
54	> 注意：跨团队的错误码定义属于 HLD（契约），但具体错误消息文案属于 LLD
55
56	### 边界示例
57
58	正确（HLD）：
59	```markdown
60	### 缓存策略
61	- 商品详情使用 Redis 缓存
62	- 缓存粒度：单商品
63	- 失效策略：写时失效 + TTL 兜底
64	```
65
66	错误（越界到 LLD）：
67	```markdown
68	### 缓存策略
69	- TTL = 3600 秒
70	- 重试次数 = 3
71	- 退避策略 = exponential backoff, base = 100ms
72	```
73
74	正确（HLD）：
75	```markdown
76	### 订单 API
77	\| 接口 \| 方法 \| 路径 \| 说明 \|
78	\|------\|------\|------\|------\|
79	\| 创建订单 \| POST \| /api/v1/orders \| 根据购物车创建订单 \|
80	```
81
82	错误（越界到 LLD）：
83	```markdown
84	### 订单 API
85	func CreateOrder(ctx context.Context, req CreateOrderRequest) (Order, error) {
86	// 参数校验
87	if req.CartID == "" {
88	return nil, errors.New("cart_id required")
89	}
90	}
91	```
92
93	正确（HLD - 错误契约）：
94	```markdown
95	### 错误码定义
96	\| 错误码 \| 含义 \| 使用场景 \|
97	\|--------\|------\|---------\|
98	\| ORDER_001 \| 库存不足 \| 创建订单时商品库存不足 \|
99	\| ORDER_002 \| 订单已取消 \| 操作已取消的订单 \|
100	```
101
102	错误（越界到 LLD - 错误消息）：
103	```markdown
104	### 错误处理
105	- ORDER_001: "抱歉，商品「{name}」库存仅剩 {count} 件，请调整数量后重试"
106	- ORDER_002: "该订单已于 {time} 取消，无法进行此操作"
107	```
108
109	正确（HLD - 需求映射表）：
110	```markdown
111	### PRD↔HLD 需求映射表
112	\| PRD 条目 \| 验收标准 \| HLD 章节 \| 状态 \|
113	\|----------\|---------\|---------\|------\|
114	\| FR-001 用户注册 \| 支持邮箱/手机号 \| 3.2 认证模块 \| ✓ 已覆盖 \|
115	\| FR-002 密码重置 \| 24h 内有效 \| 3.2 认证模块 \| ✓ 已覆盖 \|
116	\| NFR-001 响应时间 \| P99 < 200ms \| 5.1 性能策略 \| ✓ 已覆盖 \|
117	```
118
119	## 支持的 HLD 类型
120
121	1. 新功能（有 UI） - 涉及前后端的新功能
122	2. 新功能（纯后端） - 后端服务、API、后台任务
123	3. 第三方集成 - 接入外部服务的技术方案
124	4. 重构方案 - 技术重构的设计
125	5. 性能/安全优化 - 非功能性改进的技术方案
126
127	## PRD 拆分为多个 HLD（1:N 场景）
128
129	当 PRD 范围较大时，可能需要拆分为多个 HLD。必须确保所有 PRD 需求在各 HLD 中被完整覆盖，不遗漏。
130
131	### 拆分硬信号（满足其一应拆）
132
133	- 数据/事务边界明确且需要独立演进（强一致事务无法跨边界）
134	- 发布/回滚必须独立（灰度、回滚窗口不同）
135	- 安全/合规域不同（例如支付/PII 与普通数据隔离）
136	- 接口契约稳定且需版本化治理（对外/对内契约边界清晰）
137	- 性能/可用性目标显著不同（SLA 与容量目标差异大）
138
139	### 拆分软信号（需与硬信号结合）
140
141	- 多团队并行交付，需要降低协作阻塞
142	- PRD 明确分阶段且阶段可独立验收
143	- 前后端生命周期显著不同且接口稳定
144	- 文档过长影响审查效率（仅触发边界复核，不单独作为拆分依据）
145
146	### 不宜拆分（反信号）
147
148	- 跨模块强一致事务或共享数据模型导致高耦合
149	- 需求边界尚未稳定、频繁变更
150	- 仅因组织/文档长度拆分，但接口仍高度耦合
151
152	### 拆分决策流程（3 步）
153
154	1. 边界识别：数据归属/事务范围/接口契约/NFR 差异
155	2. 独立性验证：能否独立实现、测试、部署、回滚
156	3. 仅软信号时默认不拆，需要用户明确确认拆分边界
157
158	### 拆分边界确认（AskUserQuestion）
159
160	在阶段零完成后，如果识别到需要拆分，必须使用 AskUserQuestion 确认：
161
162	```
163	question: "识别到拆分信号。请确认主要拆分边界："
164	header: "HLD拆分"
165	multiSelect: false
166	options:
167	- label: "按业务域/数据边界拆分"
168	description: "数据归属清晰、事务边界独立"
169	- label: "按接口契约/服务边界拆分"
170	description: "对外/对内契约稳定、可版本化"
171	- label: "按发布/回滚单元拆分"
172	description: "需要独立灰度/回滚"
173	- label: "按安全/合规域拆分"
174	description: "PII/支付等合规域隔离"
175	- label: "按性能/可用性目标拆分"
176	description: "SLA/性能目标显著不同"
177	- label: "按阶段交付拆分"
178	description: "阶段可独立验收与上线"
179	- label: "按前后端层次拆分"
180	description: "仅在接口稳定、生命周期显著不同"
181	- label: "不拆分"
182	description: "仅软信号或强耦合；先优化文档结构"
183	```
184
185	### HLD 索引文档（1:N 场景必须创建）
186
187	当 PRD 拆分为多个 HLD 时，必须创建 HLD 索引文档，用于：
188	- 追踪所有 HLD 对 PRD 的覆盖情况
189	- 确保无需求遗漏
190	- 管理跨 HLD 依赖
191
192	索引文档命名规范：`HLD-INDEX-{PRD名称}.md`
193
194	索引文档模板：
195
196	```markdown
197	# HLD 索引：{PRD 名称}
198
199	## 基本信息
200	- PRD 基线：[PRD 路径] v[版本]
201	- 拆分方式：按业务域/数据边界 / 按接口契约 / 按发布单元 / 按安全合规 / 按性能目标 / 按阶段 / 按前后端
202	- HLD 数量：N 个
203	- 创建时间：YYYY-MM-DD
204	- 最后更新：YYYY-MM-DD
205
206	## HLD 清单
207
208	\| # \| HLD 文档 \| 负责模块/范围 \| 状态 \| 负责人 \|
209	\|---\|----------\|--------------\|------\|--------\|
210	\| 1 \| [HLD-用户系统.md](路径) \| 用户注册、登录、权限