# Testany Io Testany Agent Skills Hld Writer

> HLD Writer

- Skill: `tomevault-io/testany-io-testany-agent-skills-hld-writer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/testany-io-testany-agent-skills-hld-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/testany-io-testany-agent-skills-hld-writer/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/testany-io-testany-agent-skills-hld-writer

---


# HLD Writer

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

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

## 核心原则

1. **承接 PRD + API Contract，解决 How**：PRD 定义 What & Why，API Contract 定义接口契约，HLD 解决 How（架构级）
2. **API Contract 是接口唯一事实源**：HLD 中的接口设计必须**引用** API Contract，不得重新定义或产生冲突
3. **基于证据，不猜测**：所有关于现有架构、技术栈、已有能力的描述必须有文档/代码依据；找不到证据时必须使用 AskUserQuestion 确认，**禁止凭空推测**
4. **聚焦高成本决策**：HLD 解决高成本/跨团队/高风险决策，工程师仍可在实现层做局部选择
5. **先读后写**：写 HLD 前必须先读 PRD 和 API Contract，理解需求背景、接口契约和约束
6. **决策成本原则**：用"决策成本"决定内容归属——高成本决策放 HLD，低成本决策留给 LLD 或代码
7. **技术栈对齐**：技术选型必须与既有技术栈/规范对齐，偏离必须给出充分理由
8. **复用优先**：优先复用内部模块/共享服务/第三方成熟方案，避免重复造轮子
9. **需求可追溯**：HLD 必须包含 PRD↔HLD 需求映射表，确保需求变更时可追溯
10. **强制使用 AskUserQuestion**：需要澄清技术细节时必须使用工具提问
11. **先做 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）**：
```markdown
### 缓存策略
- 商品详情使用 Redis 缓存
- 缓存粒度：单商品
- 失效策略：写时失效 + TTL 兜底
```

**错误（越界到 LLD）**：
```markdown
### 缓存策略
- TTL = 3600 秒
- 重试次数 = 3
- 退避策略 = exponential backoff, base = 100ms
```

**正确（HLD）**：
```markdown
### 订单 API
| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 创建订单 | POST | /api/v1/orders | 根据购物车创建订单 |
```

**错误（越界到 LLD）**：
```markdown
### 订单 API
func CreateOrder(ctx context.Context, req *CreateOrderRequest) (*Order, error) {
    // 参数校验
    if req.CartID == "" {
        return nil, errors.New("cart_id required")
    }
}
```

**正确（HLD - 错误契约）**：
```markdown
### 错误码定义
| 错误码 | 含义 | 使用场景 |
|--------|------|---------|
| ORDER_001 | 库存不足 | 创建订单时商品库存不足 |
| ORDER_002 | 订单已取消 | 操作已取消的订单 |
```

**错误（越界到 LLD - 错误消息）**：
```markdown
### 错误处理
- ORDER_001: "抱歉，商品「{name}」库存仅剩 {count} 件，请调整数量后重试"
- ORDER_002: "该订单已于 {time} 取消，无法进行此操作"
```

**正确（HLD - 需求映射表）**：
```markdown
### PRD↔HLD 需求映射表
| PRD 条目 | 验收标准 | HLD 章节 | 状态 |
|----------|---------|---------|------|
| FR-001 用户注册 | 支持邮箱/手机号 | 3.2 认证模块 | ✓ 已覆盖 |
| FR-002 密码重置 | 24h 内有效 | 3.2 认证模块 | ✓ 已覆盖 |
| NFR-001 响应时间 | P99 < 200ms | 5.1 性能策略 | ✓ 已覆盖 |
```

## 支持的 HLD 类型

1. **新功能（有 UI）** - 涉及前后端的新功能
2. **新功能（纯后端）** - 后端服务、API、后台任务
3. **第三方集成** - 接入外部服务的技术方案
4. **重构方案** - 技术重构的设计
5. **性能/安全优化** - 非功能性改进的技术方案

## PRD 拆分为多个 HLD（1:N 场景）

当 PRD 范围较大时，可能需要拆分为多个 HLD。**必须确保所有 PRD 需求在各 HLD 中被完整覆盖，不遗漏。**

### 拆分硬信号（满足其一应拆）

- **数据/事务边界明确且需要独立演进**（强一致事务无法跨边界）
- **发布/回滚必须独立**（灰度、回滚窗口不同）
- **安全/合规域不同**（例如支付/PII 与普通数据隔离）
- **接口契约稳定且需版本化治理**（对外/对内契约边界清晰）
- **性能/可用性目标显著不同**（SLA 与容量目标差异大）

### 拆分软信号（需与硬信号结合）

- 多团队并行交付，需要降低协作阻塞
- PRD 明确分阶段且**阶段可独立验收**
- 前后端生命周期显著不同且接口稳定
- 文档过长影响审查效率（仅触发边界复核，不单独作为拆分依据）

### 不宜拆分（反信号）

- 跨模块强一致事务或共享数据模型导致高耦合
- 需求边界尚未稳定、频繁变更
- 仅因组织/文档长度拆分，但接口仍高度耦合

### 拆分决策流程（3 步）

1. **边界识别**：数据归属/事务范围/接口契约/NFR 差异
2. **独立性验证**：能否独立实现、测试、部署、回滚
3. **仅软信号时默认不拆**，需要用户明确确认拆分边界

### 拆分边界确认（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`

**索引文档模板**：

```markdown
# 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** 中，依赖方引用。

| 接口 | 定义位置 | 使用方 |
|------|---------|-------|
| 用户鉴权 API | HLD-用户系统 4.1 | HLD-订单系统、HLD-通知系统 |
| 订单事件 Schema | HLD-订单系统 5.2 | HLD-通知系统 |
```

### 单个 HLD 的需求映射表（1:N 场景）

在 1:N 场景下，单个 HLD 的需求映射表**只覆盖本 HLD 负责的部分**，但必须明确标注：

```markdown
### PRD↔HLD 需求映射表

**PRD 基线**：[PRD 路径] v[版本]
**本 HLD 覆盖范围**：用户系统（FR-001 ~ FR-010, NFR-001）
**索引文档**：[HLD-INDEX-xxx.md](路径)

| PRD 条目 | 验收标准 | HLD 章节 | 状态 |
|----------|---------|---------|------|
| FR-001 用户注册 | 支持邮箱/手机号 | 3.2 认证模块 | ✓ 已覆盖 |
| FR-002 密码重置 | 24h 内有效 | 3.2 认证模块 | ✓ 已覆盖 |
| NFR-001 响应时间 | P99 < 200ms | 5.1 性能策略 | ✓ 已覆盖 |

**不在本 HLD 范围内的需求**：FR-011 ~ FR-030（见 HLD-订单系统、HLD-通知系统）
```

### 1:N 场景审查要点

- **索引文档必须存在**：没有索引文档 → P0
- **覆盖率必须 100%**：任何 PRD 需求未分配到任何 HLD → P0（覆盖率按“已分配”计算）
- **跨 HLD 依赖必须声明**：依赖未声明 → P1
- **接口契约必须明确**：跨 HLD 接口无契约 → P1

## 工作流程

### 执行进度清单

**执行时使用 TodoWrite 工具跟踪以下进度，完成一项后立即标记为 completed：**

```
□ 阶段零：上下文收集
  □ 0.1 扫描项目文档
  □ 0.2 用户确认参考文档（PRD + API Contract 必须确认）
  □ 0.3 读取 PRD 和 API Contract（必读）
  □ 0.4 读取其他确认的文档
  □ 0.5 识别可复用资源
  □ 0.6 记录关键约束
  □ 0.7 执行 Guardrails trigger check
  □ 0.8 输出上下文收集报告
□ 阶段一：需求理解
  □ 分析 PRD，识别 HLD 类型
  □ 理解 API Contract 中的接口定义
  □ 确认技术选型偏好和约束
□ 阶段二：结构规划
  □ 读取对应 HLD 模板
  □ 规划文档大纲
□ 阶段三：内容撰写
  □ 填充各章节内容
  □ 接口部分引用 API Contract（不重新定义）
  □ 绘制架构图/时序图
  □ 确保决策有理由
□ 阶段四：强制审查
  □ 4.1 完整性检查
  □ 4.2 决策完整性检查
  □ 4.3 边界检查
  □ 4.4 契约一致性检查（HLD 接口引用与 API Contract 一致）
  □ 4.5 可落地检查
  □ 4.6 证据检查
  □ 4.7 Traceability Metadata 生成与校验
```

---

### 阶段零：上下文收集（强制）

写 HLD 前，**必须**先了解项目上下文。**禁止跳过此阶段，禁止在未读取相关文档/代码的情况下猜测技术现状。**

#### 0.1 扫描项目文档（先扫描，不读取）

使用 Glob 工具**广泛扫描**以下类型的文档，**只收集文件路径，暂不读取内容**：

| 文档类型 | 搜索模式 | 目的 |
|---------|---------|------|
| 需求文档 | `**/PRD*`, `**/prd*`, `**/*需求*` | 找到对应的 PRD（必需） |
| API Contract | `**/*contract*`, `**/*openapi*`, `**/*swagger*`, `**/*asyncapi*` | 找到对应的 API Contract（必需） |
| 设计文档 | `**/*HLD*`, `**/*设计*`, `**/*design*`, `**/*架构*` | 了解现有架构 |
| Guardrails | `**/*guardrail*`, `**/*engineering-standard*`, `**/*工程规范*` | 判断现有项目级默认规则是否存在 |
| 技术规范 | `**/ADR*`, `**/adr*`, `**/*规范*`, `**/*standard*` | 了解技术约定 |
| 项目配置 | `package.json`, `pyproject.toml`, `go.mod`, `pom.xml` | 了解技术栈 |
| 共享模块 | `**/shared/*`, `**/common/*`, `**/lib/*`, `**/pkg/*` | 识别可复用资源 |

**排除目录**：扫描时必须排除以下目录，避免噪音：
- `node_modules/`, `.git/`, `dist/`, `build/`, `.next/`
- `vendor/`, `target/`, `__pycache__/`, `.venv/`, `venv/`
- 其他明显的依赖/构建产物目录

#### 0.2 用户确认参考文档（必须执行）

扫描完成后，**先进行初筛，再展示给用户确认**：

**初筛规则**（Agent 自行执行，不展示低置信度结果）：
- **高置信度**（展示给用户）：路径包含 `docs/`, `spec/`, `design/`, `prd/`, `hld/`, `adr/` 等关键词，或文件名明确匹配
- **低置信度**（默认不展示）：路径不明确、位于测试目录、或文件名过于通用
- 如果高置信度结果不足，可适当放宽条件

**使用 AskUserQuestion** 让用户确认：

```
我扫描到以下可能相关的文档，请确认哪些需要我仔细阅读：

**需求文档（PRD）**【必需】：
- [ ] path/to/prd-xxx.md
- ...

**API Contract**【必需】：
- [ ] path/to/api-contract-xxx.md
- [ ] path/to/openapi.yaml
- ...

**设计/架构文档**：
- [ ] path/to/hld-xxx.md
- [ ] path/to/architecture.md
- ...

**技术规范**：
- [ ] path/to/adr-xxx.md
- ...

**问题**：
1. 本次 HLD 对应的 PRD 是哪个？【必须确认】
2. 本次 HLD 对应的 API Contract 是哪个？【必须确认】
3. 以上其他文档中，哪些需要我参考？
4. 是否有我没扫描到但需要参考的重要文档？
```

**门禁规则**：PRD 和 API Contract 必须都确认后才能进入下一阶段。如果用户未提供 API Contract，提示用户先使用 `/api-writer` 生成。

**注意**：
- 只展示初筛后的高置信度结果，避免信息过载
- 这一步是为了避免读入过时/无关的文档，节省上下文
- 用户可能会排除一些过期文档，也可能补充遗漏的文档
- **只有用户确认后，才进入 0.3 阶段读取文档**

#### 0.3 读取 PRD 和 API Contract（必读）

根据用户在 0.2 中确认的文档列表：
- **优先读取 PRD**：理解业务背景、功能需求、非功能目标
- 识别 PRD 中的"建议方案"，HLD 需要做最终决定
- **仔细读取 API Contract**：明确接口边界、兼容性与错误契约
- 记录从 PRD 和 API Contract 中学到的关键信息

#### 0.4 读取其他确认的文档

- 读取用户在 0.2 中确认的其他设计/规范/Guardrails/ADR
- 只提取与当前 HLD 决策直接相关的信息，避免把噪音带入上下文
- 记录从每个文档中学到的关键信息

#### 0.5 识别可复用资源

- 基于已读取的文档，识别可复用的内部模块/共享服务
- 评估第三方成熟方案（优先复用，避免重复造轮子）
- **必须注明来源**：从哪个文档/代码中识别到的

#### 0.6 记录关键约束

- PRD 中的非功能需求（性能、安全目标）
- 技术栈限制
- 团队能力边界
- 已有 API/错误码契约（若有）

#### 0.7 执行 Guardrails trigger check（强制）

在进入阶段一前，基于 `../../references/guardrails-trigger-check.md` 执行一次 `Guardrails trigger check`：

- `no_trigger`：继续进入阶段一
- `suggest_guardrails`：在上下文收集报告中记录原因、影响域和推荐动作后继续
- `require_guardrails_before_design`：停止当前 HLD 写作，明确建议先运行 `guardrails-writer`

#### 0.8 输出「上下文收集报告」（强制）

在进入阶段一之前，必须先输出以下报告：

```markdown
## 上下文收集报告

### 已读取的文档（用户确认）
| 文档路径 | 文档类型 | 关键信息摘要 |
|---------|---------|-------------|
| [路径] | PRD/HLD/API/规范 | [从中学到的关键信息] |

### 识别的技术现状
- 技术栈：[从配置文件/代码识别]
- 现有架构：[从 HLD/代码识别]
- 已有 API 契约：[从 OpenAPI/代码识别]

### 可复用资源
| 资源 | 类型 | 与本需求关系 | 来源 |
|------|------|-------------|------|
| [资源名] | 内部模块/共享服务/第三方 | [关系描述] | [文档/代码路径] |

### Guardrails Trigger Check
- Decision: [no_trigger / suggest_guardrails / require_guardrails_before_design]
- Why: [一句话说明原因]
- Impacted domains: [API / Security / Data / Release / Observability ...]
- Guardrails status: [baseline exists / missing domain / outdated / drift]
- Recommended next action: [continue / update guardrails soon / run guardrails-writer first]

### 未找到信息的领域（需用户补充）
- [列出仍不确定的技术信息]
```

**上下文收集报告无需用户再次确认，可直接进入阶段一。**（因为文档选择已在 0.2 确认过；若 `Guardrails trigger check = require_guardrails_before_design`，则不得进入阶段一）

### 阶段一：需求理解

1. 分析 PRD，识别 HLD 类型
2. 使用 AskUserQuestion 确认：
   - 技术选型偏好（如有）
   - 性能/安全等非功能约束
   - 已知的技术限制

### 阶段二：结构规划

1. 根据 HLD 类型读取对应模板
2. 规划文档大纲
3. 确认章节结构

**模板文档路径**：
- 新功能（有 UI）：`assets/new-feature-ui.md`
- 新功能（纯后端）：`assets/new-feature-backend.md`
- 第三方集成：`assets/integration.md`
- 重构方案：`assets/refactoring.md`
- 性能/安全优化：`assets/optimization.md`

### 阶段三：内容撰写

1. 按照模板结构填充内容
2. 使用 Mermaid 绘制架构图、时序图
3. 确保所有高成本决策都有明确结论
4. 标注"决策理由"

**撰写规范**：
- 默认使用中文（技术术语可保留英文）
- 架构图、时序图用 Mermaid
- 表格用于结构化信息
- 每个技术选型必须有"选型理由"

### 阶段四：强制审查

完成初稿后，**必须**进行以下审查：

#### 4.1 完整性检查
- [ ] PRD↔HLD 需求映射表是否完整（每个 PRD 条目都有对应）
- [ ] 所有 PRD 中的功能需求是否都有技术方案
- [ ] 所有非功能目标是否都有达成策略
- [ ] 关键流程是否都有时序图或状态机

#### 4.2 决策完整性
- [ ] PRD 中的"建议方案"是否都做了最终决定
- [ ] 每个技术选型是否都有理由
- [ ] 技术选型是否与现有技术栈对齐（偏离是否有充分理由）
- [ ] 是否优先复用了内部模块/共享服务
- [ ] 是否存在"待定"项需要澄清

#### 4.3 边界检查（强制）
- [ ] 是否包含了函数签名、类设计？（不应该）
- [ ] 是否包含了具体参数（TTL、超时）？（不应该）
- [ ] 是否遗漏了跨团队约束的 API 契约？（不应该）

#### 4.4 可落地检查
- [ ] 开发团队能否根据此文档开始 LLD/编码
- [ ] 是否有歧义或模糊的技术描述

#### 4.5 证据检查（强制）
- [ ] 「复用盘点」表格中的每一行是否都有「来源」？（必须有）
- [ ] 技术现状描述是否有文档/代码依据？（必须有）
- [ ] 是否存在没有依据的猜测性描述？（不应该）
- [ ] 上下文收集报告是否已输出？（应该；注：报告本身无需用户确认，文档选择已在 0.2 确认过）

**如果发现无依据的猜测性内容，必须删除或通过 AskUserQuestion 确认。**

#### 4.6 Traceability Metadata（强制）

产出的 HLD 必须内嵌 `TRACEABILITY-METADATA` block（格式见 `../../references/traceability-schema/traceability-schema-v1.md` §11）。

**要求：**
- `schema.profile` = `hld-profile-v1`
- `artifact.type` = `HLD`
- `artifact.source_documents` 至少包含 PRD 和 API Contract 的 artifact ID
- `entities.decisions[]` 为每个架构决策建模（`DEC-*`），包含 `decision` 和 `rationale`
- `entities.flows[]` 为关键系统流程建模（`FLOW-*`），标注 `kind`
- 其余桶（requirements/risks/must_not_regress/external_behaviors/test_cases）保留空数组
- `relations[]` 使用 `refines` 将每个 `DEC-*`/`FLOW-*` 连回 `REQ-*`

参考示例：`../../references/traceability-schema/hld-profile-v1.example.yaml`

**校验（写入文件后执行）：**
```bash
python3 plugins/testany-eng/scripts/trace_lint.py --format json <HLD 路径>
```
若存在 blocking issue（error），必须修正后再输出完成结论。若 PRD 路径可用，额外执行：
```bash
python3 plugins/testany-eng/scripts/trace_build_rtm.py --format json <PRD 路径> <HLD 路径>
```

## 交互规范

### 必须使用 AskUserQuestion 的场景

1. PRD 中有多个"建议方案"需要最终选择
2. 非功能目标不明确（如"高性能"但无具体指标）
3. 技术选型存在多个可行方案
4. 涉及跨团队依赖需要确认

### 问题设计原则

```
问题：[清晰的技术问题]
选项：
- 选项 A：[方案描述 + 优劣势]
- 选项 B：[方案描述 + 优劣势]
```

### 禁止行为

**关于猜测（严格禁止）**：
- **禁止**在未搜索/读取相关文档和代码的情况下描述技术现状
- **禁止**猜测现有架构、技术栈、已有接口 — 必须有文档/代码依据
- **禁止**在「复用盘点」中填写没有来源依据的内容
- **禁止**假设技术约定 — 找不到就用 AskUserQuestion 确认

**关于内容边界**：
- 不要在 HLD 中写代码或伪代码
- 不要包含具体参数配置
- 不要遗漏 PRD 中已有的非功能约束
- 不要做 PRD 没有提及的需求假设
- 不要跳过阶段零的上下文收集

## 输出格式

最终输出的 HLD 必须：

1. 使用 Markdown 格式
2. 包含完整的元信息头部（关联 PRD、版本、作者）
3. **包含 PRD↔HLD 需求映射表**（强制）
4. 章节编号清晰
5. 架构图使用 Mermaid
6. 技术选型附带理由
7. 跨团队 API/错误码有契约定义
8. 不包含 LLD 级别的实现细节

## 质量标准

一份合格的 HLD 应该：

- **完整**：覆盖所有 PRD 需求的技术方案
- **可决策**：所有高成本决策都有明确结论
- **可落地**：开发团队可据此开始 LLD/编码
- **可追溯**：关联 PRD，技术选型有理由
- **边界清晰**：不越界到 LLD 领域

## 触发词

以下输入应触发此技能：

- "写 HLD"、"写技术设计文档"
- "帮我写技术方案"
- "HLD 模板"
- "技术设计"、"架构设计"
- "/hld-writer"

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/testany-io) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->