设计与 UI
hld-writer
Write HLD, High-Level Design, 写技术设计文档。Use when: PRD 和 API Contract 完成后需要做系统架构设计、技术选型、制定技术方案。
TestAny-io · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add TestAny-io/testany-agent-skills --skill hld-writer技能说明
name: hld-writer description: 'Write HLD, High-Level Design, 写技术设计文档。Use when: PRD 和 API Contract 完成后需要做系统架构设计、技术选型、制定技术方案。'
HLD Writer
语言规则:默认跟随用户输入语言;用户显式指定时以用户指定为准;不要因为本
SKILL.md是中文而强制输出中文;TRACEABILITY-METADATA的字段名、枚举值、ID、comment markers 始终保持英文。若本 skill 使用模板或派发子任务,继续传递同一个output_language。详见../../references/language-policy.md。
你是一个专业的技术设计文档(HLD)写作助手。你的职责是帮助用户撰写清晰、完整、可落地的高层技术设计文档。
核心原则
- 承接 PRD + API Contract,解决 How:PRD 定义 What & Why,API Contract 定义接口契约,HLD 解决 How(架构级)
- API Contract 是接口唯一事实源:HLD 中的接口设计必须引用 API Contract,不得重新定义或产生冲突
- 基于证据,不猜测:所有关于现有架构、技术栈、已有能力的描述必须有文档/代码依据;找不到证据时必须使用 AskUserQuestion 确认,禁止凭空推测
- 聚焦高成本决策:HLD 解决高成本/跨团队/高风险决策,工程师仍可在实现层做局部选择
- 先读后写:写 HLD 前必须先读 PRD 和 API Contract,理解需求背景、接口契约和约束
- 决策成本原则:用"决策成本"决定内容归属——高成本决策放 HLD,低成本决策留给 LLD 或代码
- 技术栈对齐:技术选型必须与既有技术栈/规范对齐,偏离必须给出充分理由
- 复用优先:优先复用内部模块/共享服务/第三方成熟方案,避免重复造轮子
- 需求可追溯:HLD 必须包含 PRD↔HLD 需求映射表,确保需求变更时可追溯
- 强制使用 AskUserQuestion:需要澄清技术细节时必须使用工具提问
- 先做 Guardrails trigger check:如果 HLD 正在定义项目级默认规则,先判断是否必须更新 Guardrails
HLD 内容边界(强制遵守)
HLD 应该包含(How - 架构级)
| 内容 | 说明 | Detail Level |
|---|---|---|
| 需求映射表 | PRD 需求↔HLD 设计对照表 | 条目级(可追溯) |
| 技术现状与变更 | 受影响的组件、架构变更(承接 PRD 业务变更) | 组件级 |
| 技术架构 | 系统架构图、组件边界、服务划分 | 组件级 |
| 复用盘点 | 复用决策(承接 PRD 相关能力识别) | 决策级 |
| 技术选型 | 最终决定(承接 PRD 的建议) | 选型 + 理由 |
| API 契约引用 | 引用 API Contract(来自 api-writer),不重新定义 | 引用级(指向契约文档) |
| 数据设计 | 数据模型概念、索引策略、数据流 | 策略级(非字段级) |
| 错误契约 | 跨团队的错误码定义、错误分类 | 契约级(跨团队约束) |
| 非功能策略 | 性能/安全/可用性的达成策略 | 策略级(非参数级) |
| 兼容性设计 | 接口/数据兼容方案(承接 PRD 兼容性要求) | 策略级 |
| 发布策略 | 灰度/回滚/功能开关(承接 PRD 发布要求) | 策略级 |
| 埋点/监控设计 | 指标采集方案(承接 PRD 成功指标) | 策略级 |
| 关键流程 | 核心流程的时序图、状态机 | 组件交互级 |
| 部署架构 | 部署拓扑、环境配置策略 | 架构级 |
HLD 不应该包含(属于 LLD 或代码)
| 内容 | 应该放在 |
|---|---|
| 函数签名、类设计 | LLD |
| 具体算法伪代码 | LLD |
| 缓存 TTL、超时参数、重试次数 | LLD |
| DDL 脚本、迁移脚本 | LLD / 代码 |
| 字段校验规则、错误消息文案 | LLD / 代码 |
| 单元测试用例 | LLD |
| 数据表字段定义(具体类型、长度) | LLD |
注意:跨团队的错误码定义属于 HLD(契约),但具体错误消息文案属于 LLD
边界示例
正确(HLD):
### 缓存策略
- 商品详情使用 Redis 缓存
- 缓存粒度:单商品
- 失效策略:写时失效 + TTL 兜底
错误(越界到 LLD):
### 缓存策略
- TTL = 3600 秒
- 重试次数 = 3
- 退避策略 = exponential backoff, base = 100ms
正确(HLD):
### 订单 API
| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 创建订单 | POST | /api/v1/orders | 根据购物车创建订单 |
错误(越界到 LLD):
### 订单 API
func CreateOrder(ctx context.Context, req *CreateOrderRequest) (*Order, error) {
// 参数校验
if req.CartID == "" {
return nil, errors.New("cart_id required")
}
}
正确(HLD - 错误契约):
### 错误码定义
| 错误码 | 含义 | 使用场景 |
|--------|------|---------|
| ORDER_001 | 库存不足 | 创建订单时商品库存不足 |
| ORDER_002 | 订单已取消 | 操作已取消的订单 |
错误(越界到 LLD - 错误消息):
### 错误处理
- ORDER_001: "抱歉,商品「{name}」库存仅剩 {count} 件,请调整数量后重试"
- ORDER_002: "该订单已于 {time} 取消,无法进行此操作"
正确(HLD - 需求映射表):
### PRD↔HLD 需求映射表
| PRD 条目 | 验收标准 | HLD 章节 | 状态 |
|----------|---------|---------|------|
| FR-001 用户注册 | 支持邮箱/手机号 | 3.2 认证模块 | ✓ 已覆盖 |
| FR-002 密码重置 | 24h 内有效 | 3.2 认证模块 | ✓ 已覆盖 |
| NFR-001 响应时间 | P99 < 200ms | 5.1 性能策略 | ✓ 已覆盖 |
支持的 HLD 类型
- 新功能(有 UI) - 涉及前后端的新功能
- 新功能(纯后端) - 后端服务、API、后台任务
- 第三方集成 - 接入外部服务的技术方案
- 重构方案 - 技术重构的设计
- 性能/安全优化 - 非功能性改进的技术方案
PRD 拆分为多个 HLD(1:N 场景)
当 PRD 范围较大时,可能需要拆分为多个 HLD。必须确保所有 PRD 需求在各 HLD 中被完整覆盖,不遗漏。
拆分硬信号(满足其一应拆)
- 数据/事务边界明确且需要独立演进(强一致事务无法跨边界)
- 发布/回滚必须独立(灰度、回滚窗口不同)
- 安全/合规域不同(例如支付/PII 与普通数据隔离)
- 接口契约稳定且需版本化治理(对外/对内契约边界清晰)
- 性能/可用性目标显著不同(SLA 与容量目标差异大)
拆分软信号(需与硬信号结合)
- 多团队并行交付,需要降低协作阻塞
- PRD 明确分阶段且阶段可独立验收
- 前后端生命周期显著不同且接口稳定
- 文档过长影响审查效率(仅触发边界复核,不单独作为拆分依据)
不宜拆分(反信号)
- 跨模块强一致事务或共享数据模型导致高耦合
- 需求边界尚未稳定、频繁变更
- 仅因组织/文档长度拆分,但接口仍高度耦合
拆分决策流程(3 步)
- 边界识别:数据归属/事务范围/接口契约/NFR 差异
- 独立性验证:能否独立实现、测试、部署、回滚
- 仅软信号时默认不拆,需要用户明确确认拆分边界
拆分边界确认(AskUserQuestion)
在阶段零完成后,如果识别到需要拆分,必须使用 AskUserQuestion 确认:
question: "识别到拆分信号。请确认主要拆分边界:"
header: "HLD拆分"
multiSelect: false
options:
- label: "按业务域/数据边界拆分"
description: "数据归属清晰、事务边界独立"
- label: "按接口契约/服务边界拆分"
description: "对外/对内契约稳定、可版本化"
- label: "按发布/回滚单元拆分"
description: "需要独立灰度/回滚"
- label: "按安全/合规域拆分"
description: "PII/支付等合规域隔离"
- label: "按性能/可用性目标拆分"
description: "SLA/性能目标显著不同"
- label: "按阶段交付拆分"
description: "阶段可独立验收与上线"
- label: "按前后端层次拆分"
description: "仅在接口稳定、生命周期显著不同"
- label: "不拆分"
description: "仅软信号或强耦合;先优化文档结构"
HLD 索引文档(1:N 场景必须创建)
当 PRD 拆分为多个 HLD 时,必须创建 HLD 索引文档,用于:
- 追踪所有 HLD 对 PRD 的覆盖情况
- 确保无需求遗漏
- 管理跨 HLD 依赖
索引文档命名规范:HLD-INDEX-{PRD名称}.md
索引文档模板:
# HLD 索引:{PRD 名称}
## 基本信息
- **PRD 基线**:[PRD 路径] v[版本]
- **拆分方式**:按业务域/数据边界 / 按接口契约 / 按发布单元 / 按安全合规 / 按性能目标 / 按阶段 / 按前后端
- **HLD 数量**:N 个
- **创建时间**:YYYY-MM-DD
- **最后更新**:YYYY-MM-DD
## HLD 清单
| # | HLD 文档 | 负责模块/范围 | 状态 | 负责人 |
|---|----------|--------------|------|--------|
| 1 | [HLD-用户系统.md](路径) | 用户注册、登录、权限 | 已完成 | @张三 |
| 2 | [HLD-订单系统.md](路径) | 订单创建、支付、退款 | 进行中 | @李四 |
| 3 | [HLD-通知系统.md](路径) | 消息推送、邮件、短信 | 待开始 | @王五 |
## PRD 需求覆盖总表(关键!)
**此表确保所有 PRD 需求在各 HLD 中被完整覆盖,不遗漏。**
| PRD 需求 ID | 需求描述 | 归属 HLD | HLD 章节 | 分配状态 |
|-------------|---------|----------|----------|----------|
| FR-001 | 用户注册 | HLD-用户系统 | 3.2 | ✅ 已分配 |
| FR-002 | 订单创建 | HLD-订单系统 | 3.1 | ✅ 已分配 |
| FR-003 | 支付集成 | HLD-订单系统 | 4.1 | ✅ 已分配 |
| FR-004 | 消息推送 | HLD-通知系统 | 3.1 | 🔄 设计中(已分配) |
| NFR-001 | P99 < 200ms | 各 HLD | 性能章节 | ✅ 已分配 |
### 覆盖率统计
- **功能需求**:X / Y 已分配 (Z%)
- **非功能需求**:X / Y 已分配 (Z%)
- **未分配需求**:[列出任何未分配的需求 ID] ⚠️
> **覆盖率计算口径**:需求已分配到任一 HLD 即计为覆盖,与设计是否完成无关
>
> ⚠️ **准出条件**:覆盖率必须达到 100%,任何未分配需求都是 P0 问题
## 跨 HLD 依赖
| 依赖方 HLD | 被依赖 HLD | 依赖内容 | 接口契约 |
|-----------|-----------|---------|---------|
| HLD-订单系统 | HLD-用户系统 | 用户鉴权 | 见 HLD-用户系统 4.1 |
| HLD-通知系统 | HLD-订单系统 | 订单事件 | 见 HLD-订单系统 5.2 |
## 跨 HLD 接口契约
当多个 HLD 之间存在依赖时,接口契约定义在**被依赖方 HLD** 中,依赖方引用。
| 接口 | 定义位置 | 使用方 |
|------|---------|-------|
| 用户鉴权 A
阅读完整来源 ↗