product-specify

product-specify

此技能的作用

通过交互式探索和权衡分析，将高层次的产品构想转化为有文档记录的产品决策记录（PDR）。

关键要点：在正式记录决策之前，先进行讨论和探索。目标是揭示权衡因素、验证假设，并通过协作做出明智的决策。

输出：在 .adlc/drafts/pdr/ 中生成各个 PDR-{NNN}.md 文件（状态为 Proposed），以及自动生成的 pdr.md 索引。

适用场景

注意：常规决策记录由 team-boot 的持续记录机制处理，该机制会直接将简要草稿写入 .adlc/drafts/。此技能用于交互式深入探索——当你希望在记录决策前获得引导式权衡分析、多方案比较或结构化决策协助时使用。

• 从头开始打造新产品
• 产品重大转型
• 正式记录口头决策
• 团队入职培训——讲解产品设计依据

不适用场景

• 现有产品（改用 /product-init）
• PDR 的小幅更新（改用 /product-clarify）

执行步骤

阶段 0：环境设置

sh: scripts/bash/setup-product-specify.sh [--json]
ps: scripts/powershell/setup-product-specify.ps1

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

设置输出（JSON）：

{
  "REPO_ROOT": "/path/to/project",
  "PDR_DRAFTS_DIR": "/path/to/project/.adlc/drafts/pdr",
  "PRD_FILE": "/path/to/project/PRD.md",
  "next_pdr": "001"
}

阶段 1：功能领域拆分（可选）

分析产品，找出不同的业务领域。如果检测到多个领域，则自动拆分。使用 --no-decompose 可跳过。

展示检测到的领域：

## Detected Feature Areas

| # | Feature Area | Key Domains | Rationale |
|---|--------------|-------------|-----------|
| 1 | **Auth** | Authentication, Authorization | Core user entry |
| 2 | **Core** | User Management, Profiles | Core data |
| 3 | **Business** | Payments, Subscriptions | Revenue domain |

Reply: Y to confirm, n for monolithic, or suggest changes.

阈值：

• ≤3 个领域：自动批准
• 4-6 个领域：与用户确认

• 6 个领域：建议分组

阶段 2：产品分析

提取产品驱动因素：

1. 问题驱动因素：核心问题、受影响人群、当前的变通方案
2. 市场驱动因素：目标细分市场、竞争格局、趋势
3. 业务驱动因素：收入模式、规模增长预期、战略重要性
4. 约束驱动因素：技术要求、预算、团队技能、监管要求
5. 加载章程：如果 {REPO_ROOT}/docs/adlc/memory/constitution.md 或旧版路径 {REPO_ROOT}/.adlc/memory/constitution.md 存在，则读取前者（回退至旧版路径——双重读取）
6. 检查现有文档：扫描 README.md、AGENTS.md、CONTRIBUTING.md 以获取上下文

阶段 3：产品探索（交互式）

针对每个主要决策领域，提供选项并引导讨论：

决策领域（5-7 项关键决策）：

1. 问题范围
2. 目标用户画像
3. 解决方案（自建、采购或合作）
4. 盈利模式
5. 上市策略
6. 成功指标

探索形式：

## Product Decision: [Decision Area]

**Context**: [Why this decision matters]

**Options**:
| Option | Description | Trade-offs |
|--------|-------------|------------|
| A | [Option A] | Pros: [X] / Cons: [Y] |
| B | [Option B] | Pros: [X] / Cons: [Y] |

**Recommended**: Option [X]

**Questions**:
1. [Question about constraints]
2. [Question about trade-off priorities]

规则：

• 每次只展示一个决策领域
• 始终提供推荐选项并说明理由
• 提出有针对性的问题，以发掘隐藏需求
• 跳过已由上下文或章程确定的决策
• 限定在 5-7 项关键决策

阶段 4：跨功能领域预分析

在探索过程中，留意以下模式：

模式	检测方式	操作
共享用户画像	多个领域中出现相同用户类型	记录为跨领域元数据
优先级冲突	各领域的优先级不同	⚠️ 标记潜在冲突
功能重叠	不同领域存在相似功能	⚠️ 标记以便整合
指标冲突	指标相同，但目标不同	⚠️ 标记以便协调

阶段 5：决策文档记录

每项决策确认后，创建一个 PDR 文件。

PDR 文件格式（单独文件，包含 YAML frontmatter——使用共享模板）：

使用 {REPO_ROOT}/.agents/skills/product/templates/pdr-template.md 中的模板作为规范的 PDR 格式。该模板包含 YAML frontmatter（status、date、owner、category、feature-area、title），作为生成索引的唯一事实来源；还包含标准 PDR 正文部分（Context、Decision、Consequences、Alternatives、Links）。

---
status: proposed
date: YYYY-MM-DD
owner: [User/AI collaboration]
category: Feature
feature-area: [core | business | growth | ...]
title: [Decision Title]
---

# PDR-[NNN]: [Decision Title]

## Context
**Problem/Opportunity:**
[Clear description]

**Market Forces:**
- [Market factor 1]
- [Customer feedback]

## Decision
**Decision Statement:**
[Clear statement of what was decided]

**Rationale:**
[Why this option was chosen]

### Consequences
#### Positive
- [Benefit 1]

#### Negative
- [Trade-off 1]

#### Risks
- [Risk with mitigation]

### Success Metrics
| Metric | Target | Measurement Method |
|--------|--------|-------------------|
| [Metric] | [Target] | [Method] |

### Alternatives Considered
#### Option A: [Alternative Name]
**Description:** [Brief description]
**Trade-offs:** [Neutral comparison]

### Constitution/Vision Alignment
| Principle | Alignment | Notes |
|-----------|-----------|-------|
| [Vision Principle] | ✅ Compliant / ⚠️ Deviation | [Explanation] |

阶段 6：编写 PDR 文件并重新生成索引

1. 按顺序编号：从现有最高 PDR 编号 + 1 开始
2. 编写单独的文件：{REPO_ROOT}/.adlc/drafts/pdr/PDR-{NNN}.md
3. 重新生成索引：{REPO_ROOT}/.adlc/drafts/pdr/pdr.md

索引格式：

# Product Decision Records

## PDR Index

| ID | Feature-Area | Category | Status | Date | Owner |
|----|--------------|----------|--------|------|-------|
| PDR-001 | System | Target Market | Proposed | 2026-03-09 | User/AI |
| PDR-002 | Auth | Primary Persona | Proposed | 2026-03-09 | User/AI |

---

*Individual PDR files: PDR-*.md in this directory*

阶段 7：总结报告

## Feature Area Decomposition Summary

### Feature Areas Identified: 3

| # | Feature Area | PDRs Created |
|---|--------------|--------------|
| 1 | System-Level | PDR-001: Target Market |
| 2 | Auth | PDR-002: Primary Persona, PDR-003: Authentication Approach |
| 3 | Business | PDR-004: Pricing Model, PDR-005: Payment Integration |

### Next Steps
1. Review PDRs with /product-clarify
2. Generate PRD.md with /product-implement

PDR 编号规则

• 扫描 {REPO_ROOT}/.adlc/drafts/pdr/ 中现有的 PDR-*.md 文件
• 提取数字后缀，找出最大值
• 下一个 PDR = 最大值 + 1，并补零至 3 位数
• 不得重复使用编号

关键规则

先探索

• 不要直接根据产品描述生成 PRD
• 通过讨论验证假设
• 在做出决定前说明权衡
• 允许迭代——用户可以重新审视之前的决定

遵循宪章

• PDR 必须符合宪章原则
• 标记产品需求与宪章之间的冲突
• 违反宪章必须明确说明覆盖该原则的理由

增量式 PDR

• 创建聚焦的 PDR——每个 PDR 只记录一个决定
• 决策相互影响时，关联相关 PDR
• 推迟可以以后再做的决定
• 标记可能需要修订的暂定决定

配置

• PDR_DRAFTS_DIR — {REPO_ROOT}/.adlc/drafts/pdr
• PDR_INDEX — {REPO_ROOT}/.adlc/drafts/pdr/pdr.md
• PRD_FILE — {REPO_ROOT}/docs/adlc/product/PRD.md
• CONSTITUTION — {REPO_ROOT}/docs/adlc/memory/constitution.md（旧版 .adlc/memory/constitution.md 回退路径）

与 12-Factor 的对齐

• Factor III（任务定义）：在执行前定义产品任务
• Factor XI（将指令作为代码）：PDR 是受版本控制的决策记录

常见借口

借口	实际情况
“我们直接写 PRD 吧。”	没有 PDR 的 PRD 缺少可追溯的理由。决策会变成未记录的假设。
“我们已经知道要构建什么。”	即使是“显而易见”的决策也存在其他方案。记录下来可以避免日后推翻决定。
“探索太耗时了。”	现在花 10 分钟讨论，可以避免日后数周的返工。

危险信号

• 在 PDR 获批前生成 PRD——/product-implement 要求状态为 Accepted；Proposed 状态的 PDR 将被跳过。
• 跳过宪章检查——不一致的决策会延续到 PRD 中，之后修复代价高昂。
• 未记录备选方案——没有备选方案的 PDR 只是陈述，而不是决策。

验证

• 设置脚本返回包含所有路径的有效 JSON
• .adlc/drafts/pdr/ 目录存在
• 至少创建一个状态为 "Proposed" 的 PDR-*.md 文件
• 自动生成的 pdr.md 索引包含正确的表格
• 已检查与宪章的一致性（如果宪章存在）
• 已标记跨功能领域冲突
• 无重复的 PDR ID
• 每个 PDR 至少记录 2 个备选方案