From testany-eng
Writes High-Level Design (HLD) documents for system architecture, tech selection, data models, error contracts, and non-functional strategies. Use after PRD and API Contract completion.
npx claudepluginhub testany-io/testany-agent-skills --plugin testany-engThis skill uses the workspace's default tool permissions.
> **语言规则**：默认跟随用户输入语言；用户显式指定时以用户指定为准；不要因为本 `SKILL.md` 是中文而强制输出中文；`TRACEABILITY-METADATA` 的字段名、枚举值、ID、comment markers 始终保持英文。若本 skill 使用模板或派发子任务，继续传递同一个 `output_language`。详见 `../../references/language-policy.md`。
agents/openai.yamlassets/integration.en.mdassets/integration.mdassets/new-feature-backend.en.mdassets/new-feature-backend.mdassets/new-feature-ui.en.mdassets/new-feature-ui.mdassets/optimization.en.mdassets/optimization.mdassets/refactoring.en.mdassets/refactoring.mdassets/testany-logo-small.pngassets/testany-logo.svgReviews High-Level Design (HLD) documents simulating design review meetings, detecting PRD-HLD drift, technical risks, and quality issues before LLD/implementation.
Generates architecture/design documents from approved SRS docs when no prior design exists, proposing 2-3 approaches with trade-offs and securing section-by-section approval.
Designs system architecture, defines component boundaries, writes ADRs, selects technologies, defines API contracts, and evaluates trade-offs. Translates requirements into components, data flows, and tech choices.
Share bugs, ideas, or general feedback.
语言规则：默认跟随用户输入语言；用户显式指定时以用户指定为准；不要因为本
SKILL.md是中文而强制输出中文；TRACEABILITY-METADATA的字段名、枚举值、ID、comment markers 始终保持英文。若本 skill 使用模板或派发子任务，继续传递同一个output_language。详见../../references/language-policy.md。
你是一个专业的技术设计文档（HLD）写作助手。你的职责是帮助用户撰写清晰、完整、可落地的高层技术设计文档。
| 内容 | 说明 | Detail Level |
|---|---|---|
| 需求映射表 | PRD 需求↔HLD 设计对照表 | 条目级（可追溯） |
| 技术现状与变更 | 受影响的组件、架构变更（承接 PRD 业务变更） | 组件级 |
| 技术架构 | 系统架构图、组件边界、服务划分 | 组件级 |
| 复用盘点 | 复用决策（承接 PRD 相关能力识别） | 决策级 |
| 技术选型 | 最终决定（承接 PRD 的建议） | 选型 + 理由 |
| API 契约引用 | 引用 API Contract（来自 api-writer），不重新定义 | 引用级（指向契约文档） |
| 数据设计 | 数据模型概念、索引策略、数据流 | 策略级（非字段级） |
| 错误契约 | 跨团队的错误码定义、错误分类 | 契约级（跨团队约束） |
| 非功能策略 | 性能/安全/可用性的达成策略 | 策略级（非参数级） |
| 兼容性设计 | 接口/数据兼容方案（承接 PRD 兼容性要求） | 策略级 |
| 发布策略 | 灰度/回滚/功能开关（承接 PRD 发布要求） | 策略级 |
| 埋点/监控设计 | 指标采集方案（承接 PRD 成功指标） | 策略级 |
| 关键流程 | 核心流程的时序图、状态机 | 组件交互级 |
| 部署架构 | 部署拓扑、环境配置策略 | 架构级 |
| 内容 | 应该放在 |
|---|---|
| 函数签名、类设计 | 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 性能策略 | ✓ 已覆盖 |
当 PRD 范围较大时，可能需要拆分为多个 HLD。必须确保所有 PRD 需求在各 HLD 中被完整覆盖，不遗漏。
在阶段零完成后，如果识别到需要拆分，必须使用 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: "仅软信号或强耦合；先优化文档结构"
当 PRD 拆分为多个 HLD 时，必须创建 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** 中，依赖方引用。
| 接口 | 定义位置 | 使用方 |
|------|---------|-------|
| 用户鉴权 API | HLD-用户系统 4.1 | HLD-订单系统、HLD-通知系统 |
| 订单事件 Schema | HLD-订单系统 5.2 | HLD-通知系统 |
在 1:N 场景下，单个 HLD 的需求映射表只覆盖本 HLD 负责的部分，但必须明确标注：
### 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-通知系统）
执行时使用 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 前，必须先了解项目上下文。禁止跳过此阶段，禁止在未读取相关文档/代码的情况下猜测技术现状。
使用 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/扫描完成后，先进行初筛，再展示给用户确认：
初筛规则（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.2 中确认的文档列表：
在进入阶段一前，基于 ../../references/guardrails-trigger-check.md 执行一次 Guardrails trigger check：
no_trigger：继续进入阶段一suggest_guardrails：在上下文收集报告中记录原因、影响域和推荐动作后继续require_guardrails_before_design：停止当前 HLD 写作，明确建议先运行 guardrails-writer在进入阶段一之前，必须先输出以下报告：
## 上下文收集报告
### 已读取的文档（用户确认）
| 文档路径 | 文档类型 | 关键信息摘要 |
|---------|---------|-------------|
| [路径] | 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，则不得进入阶段一）
模板文档路径：
assets/new-feature-ui.mdassets/new-feature-backend.mdassets/integration.mdassets/refactoring.mdassets/optimization.md撰写规范：
完成初稿后，必须进行以下审查：
如果发现无依据的猜测性内容，必须删除或通过 AskUserQuestion 确认。
产出的 HLD 必须内嵌 TRACEABILITY-METADATA block（格式见 ../../references/traceability-schema/traceability-schema-v1.md §11）。
要求：
schema.profile = hld-profile-v1artifact.type = HLDartifact.source_documents 至少包含 PRD 和 API Contract 的 artifact IDentities.decisions[] 为每个架构决策建模（DEC-*），包含 decision 和 rationaleentities.flows[] 为关键系统流程建模（FLOW-*），标注 kindrelations[] 使用 refines 将每个 DEC-*/FLOW-* 连回 REQ-*参考示例：../../references/traceability-schema/hld-profile-v1.example.yaml
校验（写入文件后执行）：
python3 plugins/testany-eng/scripts/trace_lint.py --format json <HLD 路径>
若存在 blocking issue（error），必须修正后再输出完成结论。若 PRD 路径可用，额外执行：
python3 plugins/testany-eng/scripts/trace_build_rtm.py --format json <PRD 路径> <HLD 路径>
问题：[清晰的技术问题]
选项：
- 选项 A：[方案描述 + 优劣势]
- 选项 B：[方案描述 + 优劣势]
关于猜测（严格禁止）：
关于内容边界：
最终输出的 HLD 必须：
一份合格的 HLD 应该：
以下输入应触发此技能：