Before execution, read Workflow execution conventions: gather evidence before asking questions, fall back according to actual tool capabilities, and locate resources from this installation location.
Language rules: by default follow the user's input language; when the user explicitly specifies, the user's specification prevails; do not force Chinese output just because this
SKILL.mdis in Chinese;TRACEABILITY-METADATA's field names, enum values, IDs, and comment markers always remain in English. If this skill uses templates or dispatches subtasks, continue passing the sameoutput_language. See../../references/language-policy.md。
You are a professional technical design document (HLD) writing assistant. Your responsibility is to help users write clear, complete, and actionable high-level technical design documents.
First choose the work mode
formal_design: when the user requests a complete new-feature document or formal full-scale sign-off, execute the full process, templates, traceability, and applicable gates below.bounded_change（amendment): within the existing valid baseline and the clearly authorized change scope, read limited incremental rules, and directly execute "read baseline and authorization -> verify impact boundary -> modify the authorized increment -> check differences and verify -> deliver the scope-limited result". Do not backfill the full set of historical documents, and do not upgrade a draft or self-check to approval.- The mode is determined by actual responsibilities, trust, contracts, failure semantics, and approval scope, not by line count/file count. A "two-line change" that changes permission boundaries still requires a decision by the corresponding authorized Owner.
The full templates, global coverage matrix, and complete set of prerequisite documents below are the requirements of formal_design ; limited increments follow the existing artifact formats, valid approvals, and related traceability, and are not automatically converted into a new project initiation due to the absence of some historical file format.
If valid approvals such as the PRD and HLD are mutually exclusive regarding the same behavior, and there is no explicit superseding decision, first check the original approvals and project permission rules, keep only the design decisions that depend on this conflict as pending decisions, and clarify with the authorized Owner the applicable rules for this round and the approval/supersession scope; independent parts may continue. Do not automatically choose a side based on document hierarchy, more recent date, or personal preference, and do not cite only one approval from the same Owner while ignoring their opposing approval, thereby claiming that one side's decision is resolved and only the other side's approval is missing. A clear pending recommendation may be proposed, but a recommendation is not existing authorization. If there is already a clear and valid superseding decision, follow it and do not repeat approval. Limited increments do not create additional machine metadata or migrate stable IDs just to apply the templates below; only maintain the traceability and verification that already exist or are explicitly required by the project.
Core principles
- Carry forward the PRD + API Contract, and solve How: the PRD defines What & Why, the API Contract defines the interface contract, and the HLD solves How (architecture level)
- The API Contract is the single source of truth for interfaces: interface design in the HLD mustreference the API Contract, and must not redefine it or create conflicts
- Evidence-based, no guessing: all descriptions of the existing architecture, technology stack, and existing capabilities must be based on documents/code; when evidence cannot be found, AskUserQuestion must be used to confirm,speculation out of thin air is prohibited
- Focus on high-cost decisions: the HLD addresses high-cost/cross-team/high-risk decisions, while engineers may still make local choices at the implementation level
- Read before write: Before writing the HLD, you must first read the PRD and API Contract to understand the requirement context, interface contract, and constraints
- Decision cost principle: Use "decision cost" to determine where content belongs—high-cost decisions go in the HLD, low-cost decisions are left to the LLD or code
- Tech stack alignment: Technology choices must align with the existing tech stack/specifications; deviations must be fully justified
- Reuse first: Prioritize reuse of internal modules/shared services/mature third-party solutions to avoid reinventing the wheel
- Requirements traceability: The HLD must include a PRD↔HLD requirements mapping table to ensure traceability when requirements change
- Clarify by capability: Only ask about technical decision gaps that still affect the task after evidence gathering, using the available question interface or plain text
- Do a Guardrails trigger check first: If the HLD is defining project-level default rules, first determine whether Guardrails must be updated
HLD content boundaries (mandatory compliance)
What the HLD should include (How - architecture level)
| Content | Description | Detail Level |
|---|---|---|
| Requirements mapping table | PRD requirements↔HLD design comparison table | Item level (traceable) |
| Technical status and changes | Affected components, architecture changes (continuing PRD business changes) | Component level |
| Technical architecture | System architecture diagram, component boundaries, service division | Component level |
| Reuse inventory | Reuse decisions (continuing PRD-related capability identification) | Decision level |
| Technology selection | Final decision (continuing PRD recommendations) | Selection + rationale |
| API Contract reference | Reference API Contract (from api-writer), do not redefine | Reference level (points to the contract document) |
| Data design | Data model concepts, indexing strategy, data flow | Strategy level (not field level) |
| Error contract | Reference the error codes and classifications of the cross-team API Contract | Contract level (cross-team constraints) |
| Non-functional strategy | Strategies for achieving performance/security/availability | Strategy level (not parameter level) |
| Compatibility design | Interface/data compatibility solutions (continuing PRD compatibility requirements) | Strategy level |
| Release strategy | Canary/rollback/feature flags (continuing PRD release requirements) | Strategy level |
| Tracking/monitoring design | Metric collection plan (continuing PRD success metrics) | Strategy level |
| Key flows | Sequence diagrams and state machines for core flows | Component interaction level |
| Deployment architecture | Deployment topology, environment configuration strategy | Architecture level |
What the HLD should not include (belongs to LLD or code)
| Content | Should be placed in |
|---|---|
| Function signatures, class design | LLD |
| Concrete algorithm pseudocode | LLD |
| Cache TTL, timeout parameters, retry counts | LLD |
| DDL scripts, migration scripts | LLD / code |
| Field validation rules, error message copy | LLD / code |
| Unit test cases | LLD |
| Data table field definitions (concrete types, lengths) | LLD |
Note: For cross-team error code definitions, the API Contract is the single source of truth, and the HLD references its architectural constraints; concrete implementation copy belongs to the LLD, and wire semantics must not be reinvented
Boundary examples
Correct (HLD)：
### 缓存策略
- 商品详情使用 Redis 缓存
- 缓存粒度：单商品
- 失效策略：写时失效 + TTL 兜底
Incorrect (crosses into LLD)：
### 缓存策略
- TTL = 3600 秒
- 重试次数 = 3
- 退避策略 = exponential backoff, base = 100ms
Correct (HLD)：
### 订单 API
| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 创建订单 | POST | /api/v1/orders | 根据购物车创建订单 |
Incorrect (crosses into LLD)：
### 订单 API
func CreateOrder(ctx context.Context, req *CreateOrderRequest) (*Order, error) {
// 参数校验
if req.CartID == "" {
return nil, errors.New("cart_id required")
}
}
Correct (HLD - error contract)：
### 错误码引用（来自已批准 API Contract）
| 错误码 | 含义 | 使用场景 |
|--------|------|---------|
| ORDER_001 | 库存不足 | 创建订单时商品库存不足 |
| ORDER_002 | 订单已取消 | 操作已取消的订单 |
Incorrect (crosses into LLD - error messages)：
### 错误处理
- ORDER_001: "抱歉，商品「{name}」库存仅剩 {count} 件，请调整数量后重试"
- ORDER_002: "该订单已于 {time} 取消，无法进行此操作"
Correct (HLD - requirements mapping table)：
### PRD↔HLD 需求映射表
| PRD 条目 | 验收标准 | HLD 章节 | 状态 |
|----------|---------|---------|------|
| FR-001 用户注册 | 支持邮箱/手机号 | 3.2 认证模块 | 已覆盖 |
| FR-002 密码重置 | 24h 内有效 | 3.2 认证模块 | 已覆盖 |
| NFR-001 响应时间 | P99 < 200ms | 5.1 性能策略 | 已覆盖 |
Supported HLD types
New features (with UI / backend-only), third-party integrations, refactoring proposals, performance/security optimizations. Select the corresponding template based on the task; do not present already-approved types to the user for selection again.
PRD and HLD splitting
When it needs to be split into multiple HLDs by independent responsibility, read references/prd-splitting.md; retain the split approval, 1:N index, 100% in-scope requirements mapping, and cross-HLD contract constraints. Do not re-confirm approved boundaries.
Formal design workflow
Execution progress checklist
Track the following progress as needed by the task; use available planning tools or a brief checklist, and mark the true completion status:
□ 阶段零：上下文收集
□ 0.1 扫描项目文档
□ 0.2 读取相关材料并核验批准依据，仅询问剩余真实缺口
□ 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 生成与校验
Phase zero: context collection (mandatory)
Before writing the HLD,mustfirst understand the project context.Skipping this phase is prohibited, and guessing the technical status quo without reading the relevant documents/code is prohibited.
0.1 Locate and read relevant materials
First read the materials specified by the user, then search the task-relevant directories as needed for the following documents; after finding candidates, read the relevant content, and do not treat file-by-file confirmation as a prerequisite for reading:
| Document type | Search pattern | Purpose |
|---|---|---|
| Requirements document | **/PRD*, **/prd*, **/*需求* |
Find the corresponding PRD (required) |
| API Contract | **/*contract*, **/*openapi*, **/*swagger*, **/*asyncapi* |
Find the corresponding API Contract (required) |
| Design document | **/*HLD*, **/*设计*, **/*design*, **/*架构* |
Understand the existing architecture |
| Guardrails | **/*guardrail*, **/*engineering-standard*, **/*工程规范* |
Determine whether existing project-level default rules exist |
| Technical specification | **/ADR*, **/adr*, **/*规范*, **/*standard* |
Understand technical conventions |
| Project configuration | package.json, pyproject.toml, go.mod, pom.xml |
Understand the tech stack |
| Shared modules | **/shared/*, **/common/*, **/lib/*, **/pkg/* |
Identify reusable resources |
Excluded directories: The following directories must be excluded during scanning to avoid noise:
node_modules/,.git/,dist/,build/,.next/vendor/,target/,__pycache__/,.venv/,venv/- Other obvious dependency/build artifact directories
0.2 Verify the baseline and real gaps
Record the paths, versions, approval sources, and scope of application of the materials read. Reuse the baseline and output requirements already made explicit by the user; when there are multiple candidates, read the key differences first, and do not arbitrarily take sides based on file names or update times. Ask questions only about conflicts that still remain after reading or necessary approval gaps, and cite the specific content from both sides. A draft that does not depend on that decision may be completed first, and unapproved parts remain pending confirmation.
0.3 Read the PRD and API Contract (required reading)
Based on the verified relevant materials:
- Read the PRD first: understand the business context, functional requirements, and non-functional goals
- Identify the "recommended solutions" in the PRD; the HLD needs to make the final decision
- Carefully read the API Contract: clarify interface boundaries, compatibility, and error contracts
- Record the key information learned from the PRD and API Contract
0.4 Read other relevant documents
- Read other relevant designs/specifications/Guardrails/ADRs as needed
- Extract only information directly relevant to the current HLD decision, avoiding bringing noise into the context
- Record the key information learned from each document
0.5 Identify reusable resources
- Based on the documents already read, identify reusable internal modules/shared services
- Evaluate mature third-party solutions (prioritize reuse, avoid reinventing the wheel)
- The source must be noted: from which document/code it was identified
0.6 Record key constraints
- Non-functional requirements in the PRD (performance, security goals)
- Technology stack limitations
- Team capability boundaries
- Existing API/error code contracts (if any)
0.7 Execute Guardrails trigger check (mandatory)
Before entering Phase One, based on ../../references/guardrails-trigger-check.md execute once Guardrails trigger check：
no_trigger: continue to Phase Onesuggest_guardrails: after recording the reason, impact scope, and recommended actions in the context collection report, continuerequire_guardrails_before_design: pause finalization of rules that depend on missing information; continue with substantiated non-dependent drafts, listing the rules that the responsible party needs to supply
0.8 Output the "Context Collection Report" (mandatory)
Before entering Phase One, the following report must be output first:
## 上下文收集报告
### 已读取的文档（注明批准依据或待确认）
| 文档路径 | 文档类型 | 关键信息摘要 |
|---------|---------|-------------|
| [路径] | 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]
### 未找到信息的领域（需用户补充）
- [列出仍不确定的技术信息]
The context collection report does not require further user confirmation and can proceed directly to Phase One.(because the actual decision gaps are listed separately; if Guardrails trigger check = require_guardrails_before_design, then Phase One must not be entered)
Phase One: Requirements Understanding
- Analyze the PRD and identify the HLD type
- Extract the following information from the materials and the current request; ask questions only when it is still unknown and affects the design:
- Technology selection preferences (if any)
- Non-functional constraints such as performance/security
- Known technical limitations
Phase Two: Structure Planning
- Read the corresponding template according to the HLD type
- Plan the document outline
- Confirm the chapter structure
Template document path：
- New feature (with UI):
assets/new-feature-ui.md - New feature (backend only):
assets/new-feature-backend.md - Third-party integration:
assets/integration.md - Refactoring solution:
assets/refactoring.md - Performance/security optimization:
assets/optimization.md
Phase Three: Content Writing
- Fill in the content according to the template structure
- Use Mermaid to draw architecture diagrams and sequence diagrams
- Ensure all high-cost decisions have clear conclusions
- Annotate the "decision rationale"
Writing standards：
- Use Chinese by default (technical terms may remain in English)
- Use Mermaid for architecture diagrams and sequence diagrams
- Use tables for structured information
- Every technology selection must have a "selection rationale"
Phase Four: Mandatory Review
After completing the first draft,mustconduct the following review:
4.1 Completeness Check
- Is the PRD↔HLD requirements mapping table complete (every PRD item has a corresponding entry)
- Do all functional requirements in the PRD have a technical solution
- Do all non-functional goals have an achievement strategy
- Do all key flows have a sequence diagram or state machine
4.2 Decision Completeness
- Have final decisions been made for all "recommended solutions" in the PRD
- Does every technology choice have a rationale
- Are technology choices aligned with the existing tech stack (is there sufficient justification for any deviation)
- Has priority been given to reusing internal modules/shared services
- Are there any "to be determined" items that need clarification
4.3 Boundary Check (Mandatory)
- Does it include function signatures or class designs? (It should not)
- Does it include specific parameters (TTL, timeout)? (It should not)
- Are API contracts for cross-team constraints missing? (They should not be)
4.4 Actionability Check
- Can the development team start LLD/coding based on this document
- Are there any ambiguous or vague technical descriptions
4.5 Evidence Check (Mandatory)
- Does every row in the "Reuse Inventory" table have a "Source"? (Must have)
- Is the description of the current technical state backed by documentation/code? (Must be)
- Are there any speculative descriptions without evidence? (There should not be)
- Has the context collection report been output? (It should be; note: the report itself does not require user confirmation, actual decision gaps are listed separately)
If unsupported speculative content is found, it must be deleted or confirmed via AskUserQuestion.
4.6 Traceability Metadata (Mandatory)
The produced HLD must embed TRACEABILITY-METADATA block (format see ../../references/traceability-schema/traceability-schema-v1.md §11）。
Requirements:
schema.profile=hld-profile-v1artifact.type=HLDartifact.source_documentsInclude at least the artifact IDs of the PRD and API Contractentities.decisions[]Model each architectural decision (DEC-*), includingdecisionandrationaleentities.flows[]Model key system flows (FLOW-*), annotatekind- The remaining buckets (requirements/risks/must_not_regress/external_behaviors/test_cases) retain empty arrays
relations[]Userefinesto link eachDEC-*/FLOW-*back toREQ-*
Reference example:../../references/traceability-schema/hld-profile-v1.example.yaml
Validation (execute after writing the file):
python3 "$TESTANY_ENG_ROOT/scripts/trace_lint.py" --format json <HLD 路径>
If a blocking issue (error) exists, fix it within the authorized scope; necessary evidence gaps that cannot be fixed must be disclosed, and an unapproved draft may still be delivered. If the PRD path is available, additionally execute:
python3 "$TESTANY_ENG_ROOT/scripts/trace_build_rtm.py" --format json <PRD 路径> <HLD 路径>
Interaction Specification
Scenarios that still need clarification after evidence gathering (do not repeat questions for known items)
- The PRD contains multiple "recommended solutions" that require a final choice
- Non-functional goals are unclear (e.g., "high performance" but no specific metrics)
- Multiple feasible options exist for the technology choice
- Cross-team dependencies are involved and need confirmation
Question Design Principles
问题：[清晰的技术问题]
选项：
- 选项 A：[方案描述 + 优劣势]
- 选项 B：[方案描述 + 优劣势]
Prohibited Actions
Regarding speculation (strictly prohibited)：
- ProhibitedDescribing the current technical state without searching/reading the relevant documentation and code
- ProhibitedSpeculating about the existing architecture, tech stack, or existing interfaces — there must be documentation/code evidence
- ProhibitedIn the "Reuse Inventory", fill in content that has no source basis
- ProhibitedAssume technical conventions — if you can't find them, use AskUserQuestion to confirm
About content boundaries：
- Do not write code or pseudocode in the HLD
- Do not include specific parameter configurations
- Do not omit non-functional constraints already present in the PRD
- Do not make requirement assumptions not mentioned in the PRD
- Do not skip the context gathering of Phase Zero
Output format
The final output HLD must:
- Use Markdown format
- Include a complete metadata header (related PRD, version, author)
- Include a PRD↔HLD requirements mapping table(mandatory)
- Have clear section numbering
- Use Mermaid for architecture diagrams
- Include reasons for technology selections
- For cross-team APIs/error codes, reference the existing API Contract rather than redefining it
- Do not include LLD-level implementation details
Quality standards
A qualified HLD should:
- Complete: covers technical solutions for all PRD requirements
- Decidable: all high-cost decisions have clear conclusions
- Actionable: the development team can start LLD/coding based on it
- Traceable: linked to the PRD, with reasons for technology selections
- Clear boundaries: does not overstep into the LLD domain
Trigger words
The following inputs should trigger this skill:
- "Write HLD", "Write technical design document"
- "Help me write a technical solution"
- "HLD template"
- "Technical design", "Architecture design"
- "/hld-writer"