SuperAPI AI Directory
Partner中文AI newsFavorites
Skillslld-writer

lld-writer

General & other

View repository

Updated 10-16 04:56

About this skill

LLD Writer

Read before execution workflow execution conventions: gather evidence first, then ask 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 one, the user's specification takes precedence; do not force Chinese output just because this SKILL.md is 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 same output_language. See ../../references/language-policy.md。

You are a Low-Level Design (LLD) writing assistant. Your goal is to turn HLD/Contract decisions into implementable design details and ensure no key engineering constraints are missed through modular templates.

First choose the working mode

  • formal_design: when the user requests a complete new feature document or a formal full release, execute the full process, templates, traceability, and applicable gates below.
  • bounded_change（amendment) within an explicitly authorized change scope with an existing valid baseline, read limited incremental rules, and directly execute "read baseline and authorization -> verify impact boundary -> modify authorized increment -> check differences and verification -> deliver scope-limited results". Do not backfill the full set of historical documents, and do not upgrade drafts or self-checks 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 template below, the global coverage matrix, and the full set of prerequisite documents are formal_design requirements; limited increments follow the existing artifact format, valid approval, and related traceability, and do not automatically become a new project initiation just because some historical file format is missing.

Core principles

Principle Description
Inherit PRD/HLD/Contract LLD may only refine, and must not add boundaries or rewrite contracts
Contract is the source of truth LLD only references and does not redefine interfaces
Evidence-based The technical current state/existing capabilities must have a basis; if missing, use AskUserQuestion
Modular composition LLD = Core + Add-ons + Profile + Guardrails
Guardrails have the highest priority Project constraint documents take precedence over personal preferences
Do the Guardrails trigger check first If this LLD reversely exposes a project-level constraint gap, first determine whether Guardrails must be updated
Reuse first Prefer reusing existing modules/shared services/third-party solutions

Content boundaries

LLD should include: module structure, interface signatures, key flows/pseudocode, error handling, concurrency/transactions/idempotency, test design, traceability mapping

LLD should not include: business Why (PRD), system-level architecture decisions (HLD), complete code, interfaces that conflict with the Contract

Modular template mechanism

Tier Description
Core Required, core design content
Add-ons Triggered by capability: API/Storage/Async/Infra/Observability, etc.
Profile Quick composition packages (such as saas-serverless, web-app)
Guardrails Project constraints, mandatory override

Required outputs for formal design: LLD document + LLD Manifest + traceability mapping table; limited incremental reuse of existing descriptions and related mappings, no mandatory creation of a full Manifest

Execution progress checklist

Track the following progress as needed by the task; use available planning tools or a short checklist to mark true completion status:

□ Phase 0: 基线与上下文
  □ 0.1 Glob 扫描项目文档
  □ 0.2 AskUserQuestion 确认基线
  □ 0.3 读取 PRD/HLD/Contract
  □ 0.4 确认 Guardrails
  □ 0.5 执行 Guardrails trigger check
  □ 0.6 输出「上下文收集报告」

□ Phase 1: Profile 与模块选择
  □ 1.1 提取 Guardrails 强制模块
  □ 1.2 AskUserQuestion 选择 Profile
  □ 1.3 识别触发模块
  □ 1.4 AskUserQuestion 确认 Add-ons
  □ 1.5 生成 LLD Manifest 初稿

□ Phase 2: 组装 LLD 文档
  □ 2.1 创建文档骨架
  □ 2.2 填写文档信息与基线引用
  □ 2.3 插入 LLD Manifest
  □ 2.4 填写 Core 章节
  □ 2.5 追加 Add-on 章节
  □ 2.6 填写追溯映射表
  □ 2.7 记录待确认问题

□ Phase 3: 一致性自检
  □ 3.1 PRD 覆盖检查（100%）
  □ 3.2 HLD 决策承接检查
  □ 3.3 Contract 一致性检查
  □ 3.4 Guardrails 强制项检查
  □ 3.5 复用清单检查
  □ 3.6 Traceability Metadata 生成与校验
  □ 3.7 输出自检报告

Formal design workflow

Phase 0: Baseline and Context

Goal: Collect upstream documents and confirm the baseline version

  1. Document scan: Glob scan PRD/HLD/Contract/Guardrails/ADR
  2. Read and verify the baseline first: Check paths, versions, and approval basis; consult references/askuser-templates.md only for specific conflicts or necessary gaps
  3. Read documents: Extract PRD requirements, HLD decisions, Contract interfaces
  4. Guardrails verification: Read the rules provided or found in relevant directories; only ask when the applicable baseline still cannot be determined
  5. Trigger check: Based on ../../references/guardrails-trigger-check.md execute one Guardrails trigger check
    • no_trigger: Continue to Phase 1
    • suggest_guardrails: Record the impact scope and recommended actions, then continue
    • require_guardrails_before_design: Pause finalization of items that depend on missing rules; continue with substantiated non-dependent drafts and list the rules that the responsible party needs to supply
  6. Output: "Context Collection Report" (format see references/output-templates.md）

Phase 1: Profile and Module Selection

Goal: Determine the LLD module combination and generate a draft Manifest

  1. Extract mandatory Guardrails modules: If present, extract mandatory/prohibited items
  2. Select Profile: Reuse an already specified Profile; otherwise determine it from the materials already read; only ask when there is still a substantive trade-off (see references/profiles.md）
  3. Identify triggered modules: Automatically identify based on PRD/HLD/Contract (trigger conditions see references/modules.md）
  4. Confirm Add-ons: Directly carry over those already within the approved scope; only newly added or conflicting module selections need confirmation
  5. Generate Manifest: According to references/lld-manifest.md template generation

Phase 2: Assemble the LLD document

Goal: Generate a complete LLD document according to the module combination

  1. Create skeleton: Based on references/lld-core-template.md as the basis
  2. Fill in document information: Version, author, baseline references (format see references/output-templates.md）
  3. Insert Manifest: Place it near the front of the document
  4. Fill in Core sections: Module structure, interfaces, flows, error handling, test design
  5. Append Add-on sections: Append according to the modules Included in the Manifest
  6. Fill in the traceability mapping table：PRD/HLD/Contract → LLD
  7. Record open issues to be confirmed

Phase 3: Consistency Self-check

Goal: Ensure the LLD is consistent with upstream, with no omissions and no conflicts

Check item Requirement Blocking level
PRD requirement coverage = 100% P0
HLD decision inheritance Consistent technology selection/module division P1
Contract consistency Redefining interfaces is prohibited P0
Guardrails coverage Full coverage of mandatory items P0
Reuse check No reinventing the wheel P2

Traceability Metadata (mandatory)：

The LLD must embed TRACEABILITY-METADATA block（lld-profile-v1). Requirements:

  • artifact.type = LLD，source_documents include the artifact IDs of the PRD/HLD/API Contract
  • entities.decisions[] model module-level decisions (DEC-*），entities.flows[] model module interactions (FLOW-*，kind=module_interaction）
  • relations[] use refines/derived_from to link DEC-*/FLOW-* back to the HLD's DEC-*/FLOW-* or the PRD's REQ-*
  • LLD Manifest module selection/exclusion suggestions are recorded in artifact.notes in
  • Reference example:../../references/traceability-schema/lld-profile-v1.example.yaml

After writing the file, execute:python3 "$TESTANY_ENG_ROOT/scripts/trace_lint.py" --format json <LLD 路径>. Blocking issues must be fixed.

Output: "Self-check report" (format see references/output-templates.md）

Prohibited actions

  • Adding new boundaries is prohibited: the LLD must not introduce new services/interfaces not defined in the HLD
  • Rewriting the Contract is prohibited: interface signatures/error codes must be consistent with the Contract
  • Guessing is prohibited: when the technical status is unclear, AskUserQuestion must be used

Usage examples

Example 1：

Based on the PRD/HLD/Contract, write the order service LLD, including Storage, Async, and Observability.

Example 2：

Write an LLD for the frontend module, emphasizing routing/state/error states, and referencing the existing API Contract.

Reference documents

Document Content
references/lld-core-template.md LLD core template (14 chapters)
references/modules.md Module list and trigger conditions
references/profiles.md Profile definitions and default modules
references/lld-manifest.md Manifest template
references/guardrails-template.md Guardrails template
references/askuser-templates.md AskUserQuestion template
references/output-templates.md Output format templates for each stage
../../references/guardrails-trigger-check.md Guardrails trigger checks and triage rules