product-implement

product-implement

此技能的作用

使用三阶段 DAG，将已接受的 PDR 转换为全面、独立完整的 PRD.md：

1. Plan Agent：分析 PDR，检测功能领域，生成定制 DAG，并获得用户批准
2. Execute Agent：按功能领域生成各章节，并在需求章节后设置强制检查点
3. Summarize Agent：汇总各章节、解决冲突，并生成统一的 PRD.md

输出：

• docs/adlc/product/PRD.md — 独立完整的产品需求文档（共享布局；旧版仓库根目录 PRD.md 保持读取兼容）
• {REPO_ROOT}/.adlc/product/sections/{feature-area}/{section}.md — 中间章节文件
• 已接受的 PDR 将移至 {REPO_ROOT}/docs/adlc/memory/pdr/（共享布局的规范记忆根目录）

适用情况

• /product-clarify 已批准 PDR 后
• /product-init 之后，为现有产品编写文档
• 需要重新生成 PRD 的 PDR 更新

不适用情况

• 没有已接受的 PDR（先运行 /product-clarify）
• 只需对 PRD 进行小幅修改（直接编辑 PRD.md）

执行前验证

开始前，请确认先决条件：

1. 检查 PDR 是否存在：{REPO_ROOT}/.adlc/drafts/pdr/PDR-*.md
2. 检查是否存在已接受的 PDR：统计状态为 "Accepted" 的文件
   • 如果为零：停止并输出：

     无法继续：未找到状态为 Accepted 的 PDR。
     请先运行 /product-clarify，审查并批准 PDR。
     

   • 如果 ≥1：继续

三阶段 DAG 工作流

┌─────────────────────────────────────────────────────────┐
│ PHASE 1: PLAN (Plan Agent)                              │
│ Load PDRs → Detect Feature-Areas → Generate DAG → Approve│
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│ PHASE 2: EXECUTE (Execute Agent)                        │
│ Overview → Problem → Goals → Metrics → Personas         │
│ → [REQUIREMENTS CHECKPOINT] ← MANDATORY USER APPROVAL   │
│ → NFRs → Out-of-Scope → Risks → Roadmap → PDR-Summary   │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│ PHASE 3: SUMMARIZE (Summarize Agent)                    │
│ Read sections → Detect conflicts → Resolve → PRD.md     │
└─────────────────────────────────────────────────────────┘

执行步骤

阶段 1：规划

步骤 1.1：加载并分析 PDR

1. 从 .adlc/drafts/pdr/ 读取所有 PDR-*.md 文件
2. 仅筛选状态为 Accepted 的文件
3. 解析每份 PDR 的功能领域
4. 按功能领域对 PDR 分组

步骤 1.2：检测功能领域特征

特征	检测模式	DAG 定制方式
B2B SaaS	企业、管理员、SSO	包含合规性章节
消费者应用	移动、免费增值、社交	简化需求
平台	API、集成、开发者	扩展 NFR
市场平台	多边、交易	添加商业模式章节

步骤 1.3：生成定制 DAG

默认 DAG（全部 15 个章节）：

Document Information → Executive Summary → Overview → Problem
→ Market Opportunity → Goals → Metrics → Personas
→ [CHECKPOINT: Requirements]
→ NFRs → Out-of-Scope → Risks → Investment
→ Roadmap → Go-to-Market → PDR-Summary

章节编号（固定）：

• 1. 文档信息
• 1.5 执行摘要
• 2. 概述
• 3. 问题
• 3.5 市场机会
• 4. 目标与目的
• 5. 成功指标
• 6. 用户画像
• 7. 功能需求
• 8. 非功能需求
• 9. 范围之外
• 10. 风险与缓解措施
• 10.5 投资与资源
• 11. 路线图与里程碑
• 11.5 上市策略
• 12. PDR 摘要

步骤 1.4：提交计划以供批准

## DAG Execution Plan

**Feature-Areas detected**: 3
**Total sections**: 15

**Feature-Area: Core**
**PDRs**: PDR-001, PDR-005, PDR-008
**DAG**: Document Info → Executive Summary → Overview → Problem
→ Market Opportunity → Goals → Metrics → Personas
→ [Requirements Checkpoint] → NFRs → Out-of-Scope → Risks
→ Investment → Roadmap → GTM → PDR-Summary

**Approve this plan?** [Yes/Modify/Cancel]

步骤 1.5：写入 state.json

{
  "version": "1.0",
  "phase": "plan_approved",
  "feature_areas": [
    {
      "id": "core",
      "name": "Core",
      "pdrs": ["PDR-001", "PDR-005"],
      "dag": ["document-info", "executive-summary", "overview", "problem", ...],
      "progress": {}
    }
  ],
  "checkpoint": {
    "enabled": true,
    "after_section": "requirements",
    "status": "pending"
  }
}

阶段 2：执行

对于 DAG 中的每个部分：

1. 检查依赖项 — 确保所有前置条件均已完成
2. 加载部分模板 — ../templates/sections/{section}.md
3. 生成内容 — 使用 PDR 派生的内容填充模板
4. 写入部分文件 — .adlc/product/sections/{feature-area}/{section}.md
5. 验证 — 运行 scripts/bash/validate-prd.sh {section}.md
6. 更新 state.json — 将部分标记为“completed”

部分模板用法（强制）：

• 首先读取模板
• 填写所有 [占位符]
• 切勿从头开始生成

部分内图表（强制）：

• 使用 ```mermaid 代码块
• 使用 flowchart 关键字（不要使用已弃用的 graph）
• 禁止使用 ASCII 框线字符
• 将图表嵌入其所属部分

部分	图表类型	子部分
2. 概述	功能层级结构（flowchart TD）	2.4
2. 概述	架构（flowchart TB）	2.5
6. 用户画像	用户旅程（journey）	6.4
7. 需求	需求依赖关系（flowchart LR）	7.4
7. 需求	功能依赖关系（flowchart LR）	7.5
11. 路线图	甘特图（gantt）	11.1

需求检查点（强制）：

生成“需求”部分后：

## CHECKPOINT: Requirements Section Complete

The Requirements section has been generated.

**Why checkpoint here?** Requirements shapes:
- NFRs (how requirements are met)
- Out-of-Scope (what's NOT required)
- Risks (technical feasibility)
- Roadmap (priority and sequencing)

**Options**:
A) Approve — Continue to remaining sections
B) Modify — Edit requirements, then continue
C) Restart — Regenerate from Problem phase
D) Cancel — Stop execution

阶段 3：汇总

步骤 3.1：从磁盘读取所有部分

至关重要：从文件系统读取每个部分文件。不要使用内存中的内容。

1. 扫描 .adlc/product/sections/，查找所有 .md 文件
2. 读取每个文件
3. 验证：至少 20 行，且标题格式正确

步骤 3.2：检测跨功能领域冲突

冲突类型	检测方式	解决方法
需求重复	相同需求，措辞不同	统一为 PDR 术语
优先级不一致	相同功能，优先级不同	以 PDR 为准
指标不一致	相同指标，定义不同	使用 PDR 定义

步骤 3.3：汇总到 PRD.md

至关重要：PRD.md 必须独立完整。

• 所有图表均嵌入部分中
• 不得包含面向读者、指向 .adlc/ 路径的链接
• 仅使用文档内锚点：[Section 2.4](#24-feature-hierarchy)
• PDR 引用使用纯文本：plain-text PDR references（不要添加链接）

PRD 结构（必须与模板一致）：

# Product Requirements Document: [Product Name]

## 1. Document Information
[Quick Stats, revision history, approval]

## 1.5 Executive Summary
[Business case, ROI, recommendation]

## 2. Overview
[Product description, scope]
### 2.4 Feature Hierarchy [MERMAID flowchart TD]
### 2.5 Architecture Overview [MERMAID flowchart TB]

## 3. The Problem
[Problem statement, validation evidence]

## 3.5 Market Opportunity
[TAM/SAM/SOM, competitive landscape]

## 4. Goals & Objectives
[Primary, technical, business goals traced to PDRs]

## 5. Success Metrics
[Adoption, engagement, quality]
### 5.5 Business Outcome Metrics
### 5.6 Financial Metrics

## 6. Personas
[Primary, secondary, anti-personas]
### 6.4 User Journey [MERMAID journey]

## 7. Functional Requirements [CHECKPOINT]
[User stories, REQ-XXX IDs, priority matrix]
### 7.4 Requirement Dependencies [MERMAID flowchart LR]
### 7.5 Feature Dependencies [MERMAID flowchart LR]

## 8. Non-Functional Requirements
[Performance, security, reliability, scalability]

## 9. Out of Scope
[Feature, technical, market exclusions]

## 10. Risks & Mitigation
[Risk summary, technical, market, operational]
### 10.4 Business Risks

## 10.5 Investment & Resources
[Team, budget, ROI, go/no-go criteria]

## 11. Roadmap & Milestones
### 11.1 Roadmap Overview [MERMAID gantt]
[Milestone details with demo sentences]

### 11.2 Milestone Gates & Progress
[Per milestone: done-means definition, feature rollup, gate table, issue/evidence status — sourced from milestone PDRs]

## 11.5 Go-to-Market Strategy
[Launch phases, pricing, messaging]

## 12. PDR Summary
[Key decisions, constitution alignment — NO external links]

阶段 4：PDR 生命周期管理（强制）

需要： product-clarify 技能（提供 pdr-lib.sh）：adlc-cli skills add tikalk/adlc-team-skills --skill product-clarify

步骤 4.1：将已接受的 PDR 移至记忆库（原子操作 — 脚本驱动）

引入 PDR 生命周期库，并为每个已接受的 PDR 调用 move_pdr。此操作会执行原子 mv（避免先复制再删除导致的重复风险），并自动重新生成两个范围的索引。

source "{REPO_ROOT}/.agents/skills/product-clarify/scripts/bash/pdr-lib.sh"
# Or on Windows: . "{REPO_ROOT}/.agents/skills/product-clarify/scripts/powershell/pdr-lib.ps1"

for pdr_id in <list of Accepted PDR IDs>; do
  move_pdr "$pdr_id" drafts memory
done

• 状态为“Accepted”的 PDR 会从 .adlc/drafts/pdr/ 移至 docs/adlc/memory/pdr/（而非复制）。
• 不要将状态改为“Completed” — 保持状态为“Accepted”，确保索引标题（“仅包含已接受的 PDR”）准确无误。
• Proposed/Discovered PDR 保留在草稿中（不移动）。
• drafts/pdr/pdr.md 和 memory/pdr/pdr.md 两个索引均由 move_pdr 重新生成。

步骤 4.2：生成记忆库 PDR 索引（强制 — 脚本驱动）

步骤 4.1 中的 move_pdr 调用已重新生成记忆库索引。若要手动重新生成（例如批量编辑 PDR 文件后）：

source "{REPO_ROOT}/.agents/skills/product-clarify/scripts/bash/pdr-lib.sh"
generate_pdr_index memory

此操作会使用基于 frontmatter 优先、标题回退的解析器写入 {REPO_ROOT}/docs/adlc/memory/pdr/pdr.md，该解析器可处理 ##（旧版 H2）和 ###（当前 H3）元数据。空白单元格会触发 stderr 警告并应用默认值，不会静默生成空行。

生成的索引格式如下：

# Product Decision Records (Memory)

> Auto-generated by /product-implement. Accepted PDRs only.
> Source: docs/adlc/memory/pdr/PDR-*.md

## PDR Index

| ID | Feature-Area | Category | Status | Date | Owner | Title |
|----|--------------|----------|--------|------|-------|-------|
| PDR-001 | control-plane | Governance | Accepted | 2026-08-04 | User/AI collaboration | Lit Factory Operating Model |

team-boot 会使用此索引在会话开始时注入内容（类似于 CDR.md 用于团队级上下文的方式）。

步骤 4.3：更新 state.json

{
  "phase": "completed",
  "pdr_lifecycle": {
    "pdrs_promoted": [N],
    "memory_pdr_moved": true,
    "drafts_retained": true,
    "drafts_reason": "Proposed/Discovered PDRs remain",
    "memory_index_generated": true
  }
}

第 5 阶段：最终验证

标记为完成之前，请验证所有检查项：

#	检查项	预期结果
1	磁盘上的章节文件	.adlc/product/sections/ 中有 N 个文件
2	PRD.md 是否存在	是
3	PRD.md 内容大小	>200 行
4	PRD.md 是否包含所有章节	第 1-12 节及子章节
5	PRD.md 是否自包含	0 个 .adlc/ 链接
6	是否嵌入图表	≥4 个 mermaid 代码块
7	是否已写入记忆库 PDR	docs/adlc/memory/pdr/PDR-*.md 存在
8	是否已生成记忆库 PDR 索引	docs/adlc/memory/pdr/pdr.md 存在且包含正确的表格
9	state.json 是否一致	所有章节均为 "completed"

门禁规则：如果任一检查未通过 → 请勿标记为完成。报告失败项。

PDR 可追溯性规则

• 每个章节都必须引用带 ID 的源 PDR
• 每项需求（REQ-XXX）都必须追溯到某个 PDR
• 所有内容都必须有 PDR 支持
• PDR 是解决冲突的事实来源

配置

• PDR_DRAFTS_DIR — {REPO_ROOT}/.adlc/drafts/pdr
• PDR_MEMORY_DIR — {REPO_ROOT}/docs/adlc/memory/pdr
• PRD_FILE — {REPO_ROOT}/docs/adlc/product/PRD.md
• SECTIONS_DIR — {REPO_ROOT}/.adlc/product/sections
• STATE_FILE — {REPO_ROOT}/.adlc/product/state.json

与 12-Factor 的对应关系

• Factor III（使命定义）：将使命决策编制为可执行的需求
• Factor IV（结构化规划）：DAG 编排将规划与执行分离
• Factor IX（可追溯性）：每个 PRD 要素都可追溯到某个 PDR

常见的自我合理化

自我合理化	实际情况
"我会跳过检查点，直接生成所有内容。"	需求会影响 NFR、范围外事项、风险和路线图。跳过检查点可能导致错误逐级扩散。
"PRD 可以引用章节文件。"	PRD.md 必须自包含。章节文件移动或删除后，外部引用会失效。
"我不需要将 PDR 移入记忆库。"	如果不提升，草稿与记忆库就会出现偏差。下一次 clarify 会话会看到过时数据。

危险信号

• 根据非 Accepted 状态的 PDR 生成 PRD — implement 会跳过 Proposed/Discovered 状态的 PDR；PRD 将不完整。
• 直接根据 PDR 编写 PRD.md — 内容必须来自章节文件，以确保已通过验证。
• 遗漏需求检查点 — 这是核心章节，此处的错误会逐级扩散。
• 在 PRD.md 中保留 .adlc/ 链接 — 会破坏自包含性，读者无法访问内部路径。

验证

• 预检：存在 ≥1 个 Accepted 状态的 PDR
• 计划已获用户批准
• 已写入包含 DAG 的 state.json
• 每个章节文件 ≥20 行
• 每个章节均通过 validate-prd.sh
• 需求检查点已获用户批准
• PRD.md >200 行且包含全部 15 个章节
• PRD.md 中没有 .adlc/ 链接
• 章节中嵌入 ≥4 个 Mermaid 图表
• 所有需求均可追溯到 PDR
• Accepted 状态的 PDR 已移至 docs/adlc/memory/pdr/
• 最终完成验证：全部 8 项检查均通过