Lld Writer

LLD Writer

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

你是一个低层设计（LLD）写作助手。你的目标是把 HLD/Contract 的决策落地为可实现的设计细节，并通过模块化模板确保不漏关键工程约束。

核心原则

内容边界

LLD 应包含：模块结构、接口签名、关键流程/伪代码、错误处理、并发/事务/幂等、测试设计、追溯映射

LLD 不应包含：业务 Why（PRD）、系统级架构决策（HLD）、完整代码、与 Contract 冲突的接口

模块化模板机制

必需产出：LLD 文档 + LLD Manifest + 追溯映射表

---

执行进度清单

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

□ 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 输出自检报告

---

工作流程

Phase 0：基线与上下文

目标：收集上游文档，确认基线版本

1. 文档扫描：Glob 扫描 PRD/HLD/Contract/Guardrails/ADR 2. 基线确认：AskUserQuestion 确认最新批准基线（模板见 references/askuser-templates.md） 3. 读取文档：提取 PRD 需求、HLD 决策、Contract 接口 4. Guardrails 确认：AskUserQuestion 确认是否存在 5. Trigger check：基于 ../../references/guardrails-trigger-check.md 执行一次 Guardrails trigger check

• no_trigger：继续阶段 1
• suggest_guardrails：记录影响域与推荐动作后继续
• require_guardrails_before_design：停止当前 LLD 写作，明确建议先运行 guardrails-writer

6. 输出：「上下文收集报告」（格式见 references/output-templates.md）

---

Phase 1：Profile 与模块选择

目标：确定 LLD 模块组合，生成 Manifest 初稿

1. 提取 Guardrails 强制模块：若存在，提取强制/禁止项 2. 选择 Profile：AskUserQuestion 选择 Profile（详见 references/profiles.md） 3. 识别触发模块：基于 PRD/HLD/Contract 自动识别（触发条件见 references/modules.md） 4. 确认 Add-ons：AskUserQuestion 确认模块选择 5. 生成 Manifest：按 references/lld-manifest.md 模板生成

---

Phase 2：组装 LLD 文档

目标：按模块组合生成完整 LLD 文档

1. 创建骨架：以 references/lld-core-template.md 为基础 2. 填写文档信息：版本、作者、基线引用（格式见 references/output-templates.md） 3. 插入 Manifest：放在文档靠前位置 4. 填写 Core 章节：模块结构、接口、流程、错误处理、测试设计 5. 追加 Add-on 章节：按 Manifest 中 Included 的模块追加 6. 填写追溯映射表：PRD/HLD/Contract → LLD 7. 记录待确认问题

---

Phase 3：一致性自检

目标：确保 LLD 与上游一致，无遗漏无冲突

Traceability Metadata（强制）：

LLD 必须内嵌 TRACEABILITY-METADATA block（lld-profile-v1）。要求：

• artifact.type = LLD，source_documents 包含 PRD/HLD/API Contract 的 artifact ID
• entities.decisions[] 为模块级决策建模（DEC-*），entities.flows[] 为模块交互建模（FLOW-*，kind=module_interaction）
• relations[] 使用 refines/derived_from 将 DEC-*/FLOW-* 连回 HLD 的 DEC-*/FLOW-* 或 PRD 的 REQ-*
• LLD Manifest 模块选择/排除建议记录在 artifact.notes 中
• 参考示例：../../references/traceability-schema/lld-profile-v1.example.yaml

写入文件后执行：python3 plugins/testany-eng/scripts/trace_lint.py --format json <LLD 路径>。blocking issue 必须修正。

输出：「自检报告」（格式见 references/output-templates.md）

---

禁止行为

• 禁止新增边界：LLD 不得引入 HLD 未定义的新服务/接口
• 禁止改写 Contract：接口签名/错误码必须与 Contract 一致
• 禁止猜测：技术现状不明时必须 AskUserQuestion

---

使用示例

示例 1：

基于 PRD/HLD/Contract 写订单服务 LLD，包含 Storage、Async、Observability。

示例 2：

为前端模块写 LLD，强调路由/状态/错误态，引用现有 API Contract。

---

参考文档

AskUserQuestion 模板

本文档定义 lld-writer 写作过程中需要向用户确认的问题模板。

---

基线确认

触发时机：Phase 0 - 确认上游文档基线

question: "请确认以下文档为最新批准基线："
header: "基线确认"
multiSelect: true
options:
  - label: "[PRD 路径]"
    description: "PRD 版本 X.X"
  - label: "[HLD 路径]"
    description: "HLD 版本 X.X"
  - label: "[Contract 路径]"
    description: "API Contract"
  - label: "以上均为最新"
    description: "确认基线"

---

Guardrails 确认

触发时机：Phase 0 - 确认 Guardrails 是否存在

question: "是否有 Project Guardrails/工程约束文档需要遵循？"
header: "Guardrails"
multiSelect: false
options:
  - label: "有，请提供路径"
    description: "已有项目约束文档"
  - label: "无，需要我创建模板"
    description: "创建 guardrails-template"
  - label: "无，不需要"
    description: "确认不存在"

---

Guardrails Trigger 澄清

触发时机：Phase 0 - 无法判断本次 LLD 是否暴露项目级默认规则缺口

question: "这次 LLD 变更是否会改变项目里多个模块都要遵守的默认规则？"
header: "Guardrails Trigger"
multiSelect: false
options:
  - label: "是，会改变项目默认规则"
    description: "应优先判断是否需要更新 Guardrails"
  - label: "否，只影响当前模块"
    description: "通常无需触发 Guardrails"
  - label: "不确定，需要结合现有 Guardrails 一起判断"
    description: "先读取现有 Guardrails 与批准基线再决定"

---

Profile 选择

触发时机：Phase 1 - 选择 LLD 模块组合

question: "请选择 LLD Profile（可作为默认模块组合）："
header: "LLD Profile"
multiSelect: false
options:
  - label: "saas-serverless"
    description: "多服务/云原生/事件驱动"
  - label: "web-app"
    description: "前后端 + API + 数据"
  - label: "data-pipeline"
    description: "数据流/任务/批处理"
  - label: "desktop-app"
    description: "桌面端/本地能力"
  - label: "sdk-library"
    description: "公共库/SDK"
  - label: "custom"
    description: "手工选择模块"

Profile 详情见 profiles.md。

---

Add-ons 选择

触发时机：Phase 1 - 确认需要包含的模块

question: "以下能力模块是否需要包含？"
header: "LLD 模块"
multiSelect: true
options:
  - label: "API Contract"
    description: "有对外/跨团队接口"
  - label: "Storage & Migration"
    description: "涉及数据持久化/迁移/格式"
  - label: "Async/Event"
    description: "消息/队列/事件驱动"
  - label: "Infra/IaC"
    description: "资源变更/IaC"
  - label: "Observability"
    description: "日志/指标/告警"
  - label: "Security/Compliance"
    description: "权限/PII/合规"
  - label: "Deployment/Release"
    description: "发布/回滚/灰度"
  - label: "Frontend UX"
    description: "前端路由/状态/UI"
  - label: "External Integration"
    description: "第三方集成"
  - label: "SDK/Library"
    description: "公共库/SDK"

模块详情见 modules.md。

Project Guardrails 模板

1. 技术栈与强制约束

• 前端技术栈:
• 后端技术栈:
• 基础设施/IaC:
• 共享组件/平台要求:

2. 强制模块清单

• 必须包含的 LLD 模块:
• 禁止使用/禁止变更的模块:

3. 交付与发布规则

• 分支策略:
• CI 要求/测试门槛:
• 发布/回滚策略:

4. 安全与合规

• 权限模型:
• 数据分级/加密:

5. 观测与稳定性

• 必要日志/指标/告警:
• SLA/SLO:

LLD Document Template (Core)

This template is the core chapter of LLD and all LLD must contain these contents. See modules.md for the Add-on module section.

---

1. Document Information

---

2. LLD Manifest

Use the lld-manifest.md template to list the modules included in this LLD.

---

3. Scope and Assumptions

3.1 In-Scope (covered by this LLD)

Clearly list the functions/modules covered by this LLD design:

• {Function/Module 1}
• {Function/Module 2}
• ...

3.2 Out-of-Scope (not covered by this LLD)

Explicitly list what is not within the scope of this LLD (to avoid ambiguity):

• {feature not covered 1} (reason: {covered by other LLD/subsequent iteration})
• ...

3.3 Key assumptions

List the assumptions that the design relies on. If the assumptions are not true, the design needs to be adjusted:

3.4 Dependencies

---

4. Module/package structure

4.1 Directory structure

{module-name}/
├── cmd/ # Entry/Startup
│   └── main.go
├── internal/ # Internal implementation (cannot be imported externally)
│ ├── handler/ # Request processing layer
│ ├── service/ # Business logic layer
│ ├── repository/ # Data access layer
│ └── model/ # Internal model
├── pkg/ # Exportable public package
│ └── dto/ # Data transfer object
├── config/ # Configuration
└── test/ # test
    ├── unit/
    └── integration/

Adjust the directory structure according to the actual technology stack (such as src/main/java for Java and src/ for Python)

4.2 Dependency graph

flowchart TD
subgraph External[external dependency]
        API[API Gateway]
        DB[(Database)]
        MQ[Message Queue]
    end

subgraph Module[this module]
        Handler[Handler Layer]
        Service[Service Layer]
        Repo[Repository Layer]
    end

    API --> Handler
    Handler --> Service
    Service --> Repo
    Repo --> DB
    Service --> MQ

4.3 Package/Module Responsibilities

---

5. Key interfaces and function signatures

5.1 Core interface definition

// OrderService order service interface
type OrderService interface {
// CreateOrder creates an order
// Parameters: ctx - context, req - create request
// Return: order entity, error
    CreateOrder(ctx context.Context, req *CreateOrderRequest) (*Order, error)

// GetOrder query order
    GetOrder(ctx context.Context, orderID string) (*Order, error)

// CancelOrder cancels the order
    CancelOrder(ctx context.Context, orderID string, reason string) error
}

Adjust the syntax to the actual language (TypeScript/Java/Python, etc.)

5.2 Key method signature

5.3 Contract Mapping

Reference the API Contract to explain the mapping relationship between interfaces and functions

---

6. Data structure and DTO

6.1 Core data structure

// Order order entity (internal model)
type Order struct {
    ID          string       `json:"id"`
    UserID      string       `json:"user_id"`
    Items       []OrderItem  `json:"items"`
TotalAmount int64 `json:"total_amount"` // Unit: minutes
    Status      OrderStatus  `json:"status"`
    CreatedAt   time.Time    `json:"created_at"`
    UpdatedAt   time.Time    `json:"updated_at"`
}

// OrderStatus order status enumeration
type OrderStatus string
const (
    OrderStatusPending   OrderStatus = "pending"
    OrderStatusPaid      OrderStatus = "paid"
    OrderStatusCancelled OrderStatus = "cancelled"
)

6.2 DTO (Data Transfer Object)

// CreateOrderRequest creates an order request
type CreateOrderRequest struct {
    UserID string      `json:"user_id" validate:"required"`
    Items  []ItemInput `json:"items" validate:"required,min=1"`
}

// CreateOrderResponse creates an order response
type CreateOrderResponse struct {
    OrderID string `json:"order_id"`
    Status  string `json:"status"`
}

6.3 Data conversion

---

7. Key process/pseudocode

7.1 Main process (Happy Path)

sequenceDiagram
    participant C as Client
    participant H as Handler
    participant S as Service
    participant R as Repository
    participant DB as Database

    C->>H: POST /orders
H->>H: Parameter verification
    H->>S: CreateOrder(req)
S->>S: Business verification
    S->>R: Save(order)
    R->>DB: INSERT
    DB-->>R: OK
    R-->>S: order
    S-->>H: order
    H-->>C: 201 Created

7.2 Key branch pseudocode

def create_order(request):
# 1. Parameter verification
    if not validate(request):
        raise ValidationError("invalid request")

# 2. Business verification
    user = user_service.get_user(request.user_id)
    if not user.is_active:
        raise BusinessError("user not active")

# 3. Inventory Check
    for item in request.items:
        stock = inventory.check(item.product_id)
        if stock < item.quantity:
            raise BusinessError("insufficient stock")

# 4. Create order
    order = Order(
        id=generate_id(),
        user_id=request.user_id,
        items=request.items,
        status=OrderStatus.PENDING
    )

# 5. Persistence
    repository.save(order)

# 6. Send event (if any)
    event_bus.publish(OrderCreatedEvent(order))

    return order

7.3 State machine (if applicable)

stateDiagram-v2
[*] --> Pending: Create order
Pending --> Paid: Payment successful
Pending --> Canceled: User canceled
Paid --> Shipped: Shipped
Paid --> Refunding: Apply for a refund
Shipped --> Completed: Confirm receipt
Refunding --> Refunded: Refund successful
    Cancelled --> [*]
    Completed --> [*]
    Refunded --> [*]

---

8. Error handling and exception branching

8.1 Error classification

8.2 Error code definition

Quote the error code in the Contract and supplement the internal error code

8.3 Exception handling process

try:
    result = service.create_order(request)
except ValidationError as e:
    return error_response(400, e.code, e.message)
except BusinessError as e:
    return error_response(422, e.code, e.message)
except ExternalServiceError as e:
    logger.error(f"External service failed: {e}")
#Downgrade processing
    return fallback_response()
except Exception as e:
    logger.error(f"Unexpected error: {e}")
return error_response(500, "INTERNAL_ERROR", "Service internal error")

---

9. Concurrency/Transaction/Impotent

9.1 Concurrency model

9.2 Transaction Boundaries

@transactional
def create_order_with_stock_deduction(request):
# The following operations are in the same transaction
    order = create_order(request)
    deduct_stock(request.items)
    return order

9.3 Idempotent design

def create_order_idempotent(request_id, request):
# 1. Check idempotent keys
    if redis.exists(f"order:idempotent:{request_id}"):
        return get_existing_order(request_id)

# 2. Set idempotent key (with expiration time)
    redis.setex(f"order:idempotent:{request_id}", 3600, "processing")

# 3. Execute business logic
    order = create_order(request)

# 4. Update idempotent keys
    redis.setex(f"order:idempotent:{request_id}", 86400, order.id)

    return order

---

10. Configuration/Feature Flag

10.1 Configuration items

10.2 Feature Flag

if feature_flag.is_enabled("enable_new_pricing", user_id=user.id):
    price = new_pricing_service.calculate(items)
else:
    price = legacy_pricing_service.calculate(items)

---

11. Test design

11.1 Unit test scope

11.2 Integration testing

11.3 Mock/Fixture strategy

11.4 Key test cases

---

12. Traceability mapping

---

13. Questions to be confirmed

---

14. Change record

LLD 文档模板（Core）

本模板为 LLD 核心章节，所有 LLD 必须包含这些内容。Add-on 模块章节见 modules.md。

---

1. 文档信息

---

2. LLD Manifest

使用 lld-manifest.md 模板，列出本 LLD 包含的模块。

---

3. 范围与假设

3.1 In-Scope（本 LLD 覆盖）

明确列出本 LLD 设计覆盖的功能/模块：

• {功能/模块 1}
• {功能/模块 2}
• ...

3.2 Out-of-Scope（本 LLD 不覆盖）

明确列出不在本 LLD 范围内的内容（避免歧义）：

• {不覆盖的功能 1}（原因：{由其他 LLD 覆盖 / 后续迭代}）
• ...

3.3 关键假设

列出设计依赖的假设，若假设不成立则设计需调整：

3.4 依赖

---

4. 模块/包结构

4.1 目录结构

{module-name}/
├── cmd/                    # 入口/启动
│   └── main.go
├── internal/               # 内部实现（不可外部导入）
│   ├── handler/           # 请求处理层
│   ├── service/           # 业务逻辑层
│   ├── repository/        # 数据访问层
│   └── model/             # 内部模型
├── pkg/                    # 可导出的公共包
│   └── dto/               # 数据传输对象
├── config/                 # 配置
└── test/                   # 测试
    ├── unit/
    └── integration/

根据实际技术栈调整目录结构（如 Java 用 src/main/java，Python 用 src/）

4.2 依赖关系图

flowchart TD
    subgraph External[外部依赖]
        API[API Gateway]
        DB[(Database)]
        MQ[Message Queue]
    end

    subgraph Module[本模块]
        Handler[Handler Layer]
        Service[Service Layer]
        Repo[Repository Layer]
    end

    API --> Handler
    Handler --> Service
    Service --> Repo
    Repo --> DB
    Service --> MQ

4.3 包/模块职责

---

5. 关键接口与函数签名

5.1 核心接口定义

// OrderService 订单服务接口
type OrderService interface {
    // CreateOrder 创建订单
    // 参数: ctx - 上下文, req - 创建请求
    // 返回: 订单实体, 错误
    CreateOrder(ctx context.Context, req *CreateOrderRequest) (*Order, error)

    // GetOrder 查询订单
    GetOrder(ctx context.Context, orderID string) (*Order, error)

    // CancelOrder 取消订单
    CancelOrder(ctx context.Context, orderID string, reason string) error
}

根据实际语言调整语法（TypeScript/Java/Python 等）

5.2 关键方法签名

5.3 Contract 映射

引用 API Contract，说明接口到函数的映射关系

---

6. 数据结构与 DTO

6.1 核心数据结构

// Order 订单实体（内部模型）
type Order struct {
    ID          string       `json:"id"`
    UserID      string       `json:"user_id"`
    Items       []OrderItem  `json:"items"`
    TotalAmount int64        `json:"total_amount"` // 单位：分
    Status      OrderStatus  `json:"status"`
    CreatedAt   time.Time    `json:"created_at"`
    UpdatedAt   time.Time    `json:"updated_at"`
}

// OrderStatus 订单状态枚举
type OrderStatus string
const (
    OrderStatusPending   OrderStatus = "pending"
    OrderStatusPaid      OrderStatus = "paid"
    OrderStatusCancelled OrderStatus = "cancelled"
)

6.2 DTO（数据传输对象）

// CreateOrderRequest 创建订单请求
type CreateOrderRequest struct {
    UserID string      `json:"user_id" validate:"required"`
    Items  []ItemInput `json:"items" validate:"required,min=1"`
}

// CreateOrderResponse 创建订单响应
type CreateOrderResponse struct {
    OrderID string `json:"order_id"`
    Status  string `json:"status"`
}

6.3 数据转换

---

7. 关键流程/伪代码

7.1 主流程（Happy Path）

sequenceDiagram
    participant C as Client
    participant H as Handler
    participant S as Service
    participant R as Repository
    participant DB as Database

    C->>H: POST /orders
    H->>H: 参数校验
    H->>S: CreateOrder(req)
    S->>S: 业务校验
    S->>R: Save(order)
    R->>DB: INSERT
    DB-->>R: OK
    R-->>S: order
    S-->>H: order
    H-->>C: 201 Created

7.2 关键分支伪代码

def create_order(request):
    # 1. 参数校验
    if not validate(request):
        raise ValidationError("invalid request")

    # 2. 业务校验
    user = user_service.get_user(request.user_id)
    if not user.is_active:
        raise BusinessError("user not active")

    # 3. 库存检查
    for item in request.items:
        stock = inventory.check(item.product_id)
        if stock < item.quantity:
            raise BusinessError("insufficient stock")

    # 4. 创建订单
    order = Order(
        id=generate_id(),
        user_id=request.user_id,
        items=request.items,
        status=OrderStatus.PENDING
    )

    # 5. 持久化
    repository.save(order)

    # 6. 发送事件（如有）
    event_bus.publish(OrderCreatedEvent(order))

    return order

7.3 状态机（如适用）

stateDiagram-v2
    [*] --> Pending: 创建订单
    Pending --> Paid: 支付成功
    Pending --> Cancelled: 用户取消
    Paid --> Shipped: 发货
    Paid --> Refunding: 申请退款
    Shipped --> Completed: 确认收货
    Refunding --> Refunded: 退款成功
    Cancelled --> [*]
    Completed --> [*]
    Refunded --> [*]

---

8. 错误处理与异常分支

8.1 错误分类

8.2 错误码定义

引用 Contract 中的错误码，补充内部错误码

8.3 异常处理流程

try:
    result = service.create_order(request)
except ValidationError as e:
    return error_response(400, e.code, e.message)
except BusinessError as e:
    return error_response(422, e.code, e.message)
except ExternalServiceError as e:
    logger.error(f"External service failed: {e}")
    # 降级处理
    return fallback_response()
except Exception as e:
    logger.error(f"Unexpected error: {e}")
    return error_response(500, "INTERNAL_ERROR", "服务内部错误")

---

9. 并发/事务/幂等

9.1 并发模型

9.2 事务边界

@transactional
def create_order_with_stock_deduction(request):
    # 以下操作在同一事务中
    order = create_order(request)
    deduct_stock(request.items)
    return order

9.3 幂等设计

def create_order_idempotent(request_id, request):
    # 1. 检查幂等键
    if redis.exists(f"order:idempotent:{request_id}"):
        return get_existing_order(request_id)

    # 2. 设置幂等键（带过期时间）
    redis.setex(f"order:idempotent:{request_id}", 3600, "processing")

    # 3. 执行业务逻辑
    order = create_order(request)

    # 4. 更新幂等键
    redis.setex(f"order:idempotent:{request_id}", 86400, order.id)

    return order

---

10. 配置/Feature Flag

10.1 配置项

10.2 Feature Flag

if feature_flag.is_enabled("enable_new_pricing", user_id=user.id):
    price = new_pricing_service.calculate(items)
else:
    price = legacy_pricing_service.calculate(items)

---

11. 测试设计

11.1 单元测试范围

11.2 集成测试

11.3 Mock/Fixture 策略

11.4 关键测试用例

---

12. 追溯映射

---

13. 待确认问题

---

14. 变更记录

#LLD Manifest Template

LLD Manifest 模板

LLD 模块清单（Add-ons）

每个模块只在能力触发时包含；缺失需在 Manifest 中 N/A 说明。

API Contract

• 触发：对外/跨团队接口或已有 Contract
• 必含：Contract 引用、接口→函数映射、错误码映射、版本/兼容策略
• 章节建议：
• Contract 引用
• 接口映射表
• 错误/权限映射

Storage & Migration

• 触发：数据库/文件/持久化
• 必含：表/集合/文件格式、索引、迁移/回滚、数据校验
• 章节建议：
• Schema/字段
• 迁移与回填
• 兼容性与历史数据处理

Async/Event

• 触发：队列/事件/异步任务
• 必含：主题/队列、消息 schema、顺序/幂等、DLQ/重试
• 章节建议：
• Topic/Queue 清单
• 消息结构
• 失败处理

Infra/IaC

• 触发：资源变更、Terraform/Cloud 资源
• 必含：资源清单、模块复用、IAM/权限、环境变量
• 章节建议：
• Terraform 模块与资源
• 权限与配置
• 共享组件复用

Observability

• 触发：上线或生产可观测性要求
• 必含：日志/指标/Tracing、告警、Dashboard

Security/Compliance

• 触发：权限/PII/合规
• 必含：认证授权、数据分级、加密/脱敏、审计

Deployment/Release

• 触发：多环境/灰度/回滚
• 必含：CI/CD 或发布步骤、回滚策略、Feature Flag

Frontend UX

• 触发：UI/多端交互
• 必含：路由/状态、交互流程、错误态、性能约束

External Integration

• 触发：第三方依赖
• 必含：接口地址、认证、限流/重试、降级

SDK/Library

• 触发：公共库/SDK
• 必含：API 面、版本策略、兼容性、发布方式

LLD Output Template

This document defines the output format templates for each stage of lld-writer.

---

Context Collection Report

Output timing: Phase 0.5

## Context Collection Report

### Baseline Documentation
| Document Type | Path | Version | Status |
|----------|------|------|------|
| PRD | {path} | {version} | Confirmed |
| HLD | {path} | {version} | Confirmed |
| Contract | {path} | {version} | Confirmed |
| Guardrails | {path/none} | - | Confirmed |

### Key constraint extraction
- Technology Stack: {Extracted from HLD/Guardrails}
- Mandatory module: {extracted from Guardrails}
- Reuse requirements: {extracted from HLD}

---

LLD document information

Output timing: Phase 2.2

## 1. Document Information

| Properties | Values ​​|
|------|-----|
| Document Name | LLD - {Module Name} |
| Version | v1.0 |
| Author | {Author} |
| Creation Date | {YYYY-MM-DD} |
| PRD baseline | {PRD path} v{version} |
| HLD baseline | {HLD path} v{version} |
| Contract Baseline | {Contract Path} |
| Guardrails | {path/none} |

---

Traceback mapping table

Output timing: Phase 2.6

## Traceback mapping

| Upstream entry | Source | LLD Chapter | Status |
|----------|------|----------|------|
| {PRD-001} User Login | PRD | §5.2 Authentication Process | ✅ Covered |
| {HLD-003} Cache Strategy | HLD | §6.1 Cache Design | ✅ Covered |
| POST /api/v1/users | Contract | §5.1 User Interface | ✅ Covered |

Status Description:

• ✅ Covered: The upstream entry has a corresponding design in LLD
• ⚠️ Partial coverage: Supplementary required
• ❌ Not covered: missing, must be added

---

List of issues to be confirmed

Output timing: Phase 2.7

## Questions to be confirmed

| # | Issue | Affected Chapters | Status |
|---|------|----------|------|
| 1 | {Problem description} | §X.X | To be confirmed |
| 2 | {Problem description} | §X.X | To be confirmed |

---

Self-test report

Output timing: Phase 3.7

## Self-test report

### Coverage statistics
| Check items | Results |
|--------|------|
| PRD demand coverage | 100% (X/X) |
| HLD decision making | ✅ Passed |
| Contract consistency | ✅ No conflicts |
| Guardrails Coverage | ✅ Full Coverage / N/A |

### Question list
| # | Problem | Severity | Status |
|---|------|--------|------|
| - | None | - | - |

### Self-examination conclusion
✅ After passing the self-inspection, you can submit it for review

Severity Definition:

• P0 (blocking): Contract violation, Guardrails violation
• P1 (critical): missing modules, insufficient coverage
• P2 (recommendation): readability, details

LLD 输出模板

本文档定义 lld-writer 各阶段的输出格式模板。

---

上下文收集报告

输出时机：Phase 0.5

## 上下文收集报告

### 基线文档
| 文档类型 | 路径 | 版本 | 状态 |
|----------|------|------|------|
| PRD | {路径} | {版本} | 已确认 |
| HLD | {路径} | {版本} | 已确认 |
| Contract | {路径} | {版本} | 已确认 |
| Guardrails | {路径/无} | - | 已确认 |

### 关键约束提取
- 技术栈：{从 HLD/Guardrails 提取}
- 强制模块：{从 Guardrails 提取}
- 复用要求：{从 HLD 提取}

---

LLD 文档信息

输出时机：Phase 2.2

## 1. 文档信息

| 属性 | 值 |
|------|-----|
| 文档名称 | LLD - {模块名} |
| 版本 | v1.0 |
| 作者 | {作者} |
| 创建日期 | {YYYY-MM-DD} |
| PRD 基线 | {PRD 路径} v{版本} |
| HLD 基线 | {HLD 路径} v{版本} |
| Contract 基线 | {Contract 路径} |
| Guardrails | {路径/无} |

---

追溯映射表

输出时机：Phase 2.6

## 追溯映射

| 上游条目 | 来源 | LLD 章节 | 状态 |
|----------|------|----------|------|
| {PRD-001} 用户登录 | PRD | §5.2 认证流程 | ✅ 已覆盖 |
| {HLD-003} 缓存策略 | HLD | §6.1 缓存设计 | ✅ 已覆盖 |
| POST /api/v1/users | Contract | §5.1 用户接口 | ✅ 已覆盖 |

状态说明：

• ✅ 已覆盖：上游条目在 LLD 中有对应设计
• ⚠️ 部分覆盖：需要补充
• ❌ 未覆盖：缺失，必须补充

---

待确认问题清单

输出时机：Phase 2.7

## 待确认问题

| # | 问题 | 影响章节 | 状态 |
|---|------|----------|------|
| 1 | {问题描述} | §X.X | 待确认 |
| 2 | {问题描述} | §X.X | 待确认 |

---

自检报告

输出时机：Phase 3.7

## 自检报告

### 覆盖率统计
| 检查项 | 结果 |
|--------|------|
| PRD 需求覆盖率 | 100% (X/X) |
| HLD 决策承接 | ✅ 通过 |
| Contract 一致性 | ✅ 无冲突 |
| Guardrails 覆盖 | ✅ 全覆盖 / N/A |

### 问题清单
| # | 问题 | 严重度 | 状态 |
|---|------|--------|------|
| - | 无 | - | - |

### 自检结论
✅ 通过自检，可提交审查

严重度定义：

• P0（阻塞）：Contract 冲突、Guardrails 违反
• P1（严重）：模块缺失、覆盖率不足
• P2（建议）：可读性、细节问题

LLD Profiles（默认模块组合）

Profile 仅提供默认模块清单，仍需与 Guardrails 对齐。

saas-serverless

• Core
• API Contract
• Storage & Migration
• Async/Event
• Infra/IaC
• Observability
• Security/Compliance
• Deployment/Release
• External Integration（如有）
• Frontend UX（如有）

web-app

• Core
• API Contract
• Storage & Migration
• Observability
• Security/Compliance
• Deployment/Release
• Frontend UX

data-pipeline

• Core
• Storage & Migration
• Async/Event
• Infra/IaC
• Observability
• Security/Compliance

desktop-app

• Core
• Storage & Migration
• Frontend UX
• Observability
• Deployment/Release

sdk-library

• Core
• SDK/Library
• Observability（如有）