bb-prd

bb-prd — 芯片/IP 产品需求文档生成器

从市场需求和技术约束生成专业的 PRD（Product Requirements Document），为后续架构设计提供规范输入。

Self-Adaptive 初始化

初始化目录结构 .skills_local/bb-prd/，收集项目上下文，解析路径。

---

HARD-GATE 定义

<HARD-GATE>
在任何 PRD 生成操作前，必须完成以下步骤：

1. Self-Adaptive 初始化 + 项目上下文收集
   ```bash
   SCRIPT_DIR=~/.claude/scripts
   python3 "$SCRIPT_DIR/adaptive/adaptive_init.py" \
     --skill "bb-prd" \
     --project-dir "{{ PROJECT_DIR }}"

成功标志：

• .skills_local/bb-prd/local.json 存在
• .skills_local/bb-prd/project_context.json 存在
• .skills_local/bb-prd/paths.json 存在

2. 加载配置文件

   import json
   
   with open(".skills_local/bb-prd/project_context.json") as f:
       CONTEXT = json.load(f)
   
   SCOPE = CONTEXT.get("config", {}).get("scope", "chip")
   INPUT_DIR = CONTEXT["resolved_paths"]["INPUT_DIR"]
   OUTPUT_DIR = CONTEXT["resolved_paths"]["OUTPUT_DIR"]
   

3. 创建执行日志目录

   mkdir -p "${LOG_DIR}"
   LOG_FILE="${LOG_DIR}/prd-$(date -u +%Y%m%dT%H%M%S).log"
   echo "[$(date -u +%Y%m%dT%H%M%SZ)] [INFO] HARD-GATE: 初始化完成" >> "${LOG_FILE}"
   

禁止行为（在完成初始化前）：

• 加载市场需求输入
• 启动 PRD 生成流程
• 输出规范文档

---

## Pipeline Position

市场需求/idea ──→ [bb-prd] ──→ prd/ ──→ bb-arch ──→ spec_arch/ ──→ bb-mas ──→ spec_mas/ OUTPUT_DIR

PRD 是芯片设计流程的第一个正式文档，定义产品目标、功能需求、性能指标、成本约束。

---

## 铁律（违反即停止）

> 以下规则不受 auto_approve 影响，任何模式下均不得绕过。

1. **输入先行铁律**：`INPUT_DIR` 无有效 `.md` 文件 → 拒绝执行，提示用户提供需求文档
2. **SMART 铁律**：需求含"大约/适当/较好/尽量"等模糊词 → 停止，要求澄清为可量化指标
3. **Margin 铁律**：Power/Area budget 未预留 ≥10% margin → 不输出 PRD（PVT corner + IR drop + aging 通常消耗 15%+）
4. **REQ ID 铁律**：需求 ID 重复或缺失 → 不进入 Phase 14 对抗评审
5. **追溯完整铁律**：每条 REQ 无后续文档追溯列 → 不声明 PRD 完成，追溯矩阵事后补必然漏项

---

## 设计范围分类

| Scope | 适用场景 | 文档重点 |
|-------|---------|---------|
| **chip** | Chiplet、SoC、ASIC、FPGA | 系统级需求、Chiplet组合、D2D互连 |
| **ip** | IP模块（CPU、Memory、Interconnect） | IP级功能、接口规范、集成要求 |

---

## Global Paths

PROJECT_DIR = {{ project_dir 参数 或 auto-detect }} INPUT_DIR = {{ input_dir 参数 }} OUTPUT_DIR = {{ PROJECT_DIR }}/prd TEMPLATE_DIR = ~/.claude/skills/bb-prd/templates REFERENCE_DIR = ~/.claude/skills/bb-prd/references SCRIPT_DIR = ~/.claude/scripts SKILL_FILE = ~/.claude/skills/bb-prd/SKILL.md LOG_DIR = {{ OUTPUT_DIR }}/.logs

---

## 知识库引用

以下文件按需加载，用于特定章节生成：

| 文件 | 加载时机 | 用途 |
|------|----------|------|
| `references/ic-terminology.md` | 全流程 | IC 专业术语参考 |
| `references/chiplet-standards.md` | Phase 5 | UCIe、IEEE 1838 等标准 |
| `references/functional-safety.md` | Phase 9 | ISO 26262 功能安全 |
| `references/security-requirements.md` | Phase 10 | 安全需求模板 |

---

## 输入

- `INPUT_DIR/*.md`：市场需求文档、产品定义、技术备忘录
- 支持格式：
  - 市场分析报告（目标市场、竞争分析）
  - 技术可行性分析（性能目标、成本预算）
  - 初步 idea 描述（功能构想、应用场景）

---

## 输出目录结构

### scope=chip（芯片级）

prd/ ├── PRD.md # 主 PRD 文档 ├── market_analysis.md # 市场分析附录（可选） ├── competitor_matrix.md # 竞品对比矩阵（可选） ├── cost_model.md # 成本模型（可选） ├── timeline.md # 项目时间线 ├── traceability_matrix.md # 需求追溯矩阵 └── .logs/ # 执行日志

### scope=ip（IP模块级）

prd/ ├── IP_PRD.md # IP 级 PRD 文档 ├── interface_requirements.md # 接口需求详解 ├── integration_spec.md # 集成规范 ├── verification_requirements.md # 验证需求 └── .logs/ # 执行日志

---

# 执行流程

## 增量更新机制

每次成功完成后，将输入文件哈希写入 `<output_dir>/.archive/input_snapshot.json`。下次执行时在 Phase 0 之前自动比对。

### 输入快照格式

```json
{
  "snapshot_time": "<ISO8601+08:00>",
  "skill": "bb-prd",
  "input_files": {
    "<relative-path>": "<sha256>"
  }
}

Phase -1: 变更检测（所有 Phase 前强制执行）

IF update=full  → 跳过检测，走 MAJOR 路径
IF update=patch → 跳过检测，走 MINOR 路径
ELSE (auto):
  IF input_snapshot.json 不存在
    → FULL RUN（首次执行，不归档）
  ELSE
    sha256sum 所有 input_dir/*.md 及 parsed_idea.json（若存在）
    与 snapshot 对比
    IF 哈希全部一致 → 输出 "输入未变更，跳过生成" 并退出
    IF 哈希有差异   → 按下表分类

变更分类

条件（满足任意一条）	分类
design_name 变更	MAJOR
protocols[] 增删或重命名	MAJOR
target_pdk 变更	MAJOR
target_freq_mhz 变化 > 20%	MAJOR
scope 变更（chip ↔ ip）	MAJOR
输入总字符数变化 > 30%	MAJOR
其他所有变更（描述文字、预算调整等）	MINOR

MAJOR 路径：归档 + 全量重建

TIMESTAMP=$(date -u +%Y%m%dT%H%M%S)
ARCHIVE="{{ OUTPUT_DIR }}/.archive/$TIMESTAMP"
mkdir -p "$ARCHIVE"
# 移入归档（mv，可恢复）
for f in "{{ OUTPUT_DIR }}"/*.md "{{ OUTPUT_DIR }}"/*.json; do
  [ -f "$f" ] && mv "$f" "$ARCHIVE/"
done
echo "{\"reason\":\"MAJOR\",\"timestamp\":\"$TIMESTAMP\"}" > "$ARCHIVE/CHANGE_REASON.json"

归档完成后执行 FULL RUN（从 Phase 0 正常继续）。

MINOR 路径：就地更新

根据变更字段决定重跑的最早 Phase：

变更内容	从此 Phase 重跑
核心技术指标（freq、协议、面积/功耗预算）	Phase 3（Executive Summary）起
描述/上下文文字修改	Phase 3（Executive Summary）起
安全/合规要求变更	Phase 9 起
里程碑/时间表变更	Phase 11 起

未受影响的 Phase 输出保持不变。完成后更新 {{ OUTPUT_DIR }}/.archive/input_snapshot.json。

---

Phase 0: 输入解析

1. 读取 INPUT_DIR 目录内容
2. 解析 .md 文件提取关键需求
3. 分类输入内容：
   • 市场需求（目标市场、用户场景）
   • 技术需求（性能、功耗、成本）
   • 约束条件（时间、预算、技术栈）

输出产物：parsed_requirements.json（暂存上下文）

Phase 1: 需求澄清

auto_approve 模式：基于文档推断需求，不使用 AskUserQuestion。

澄清重点：

• 产品定位（HPC/AI/汽车/网络/消费）
• 目标性能指标（吞吐量、延迟、功耗）
• 技术节点选择（28nm/40nm/65nm/FPGA）
• 成本预算范围
• 时间约束（里程碑时间点）
• 安全等级需求（是否需要功能安全）

输出产物：

clarified_requirements:
  product_positioning: [...]
  performance_targets: [...]
  technology_node: [...]
  cost_budget: [...]
  timeline_constraints: [...]
  safety_level: [...]
  open_questions: [...]

Phase 2: 市场与竞品调研

并行启动多个 Agents：

Agent 配置

Agent_1:
  name: "Market-Search"
  subagent_type: "Explore"
  prompt: |
    Search for market data and industry trends:
    - Query: "{{芯片类型}} market size {{年份}}"
    - Query: "{{应用场景}} semiconductor demand forecast"

    Report:
    1. Market size and growth rate
    2. Key players and market share
    3. Emerging trends

    Thoroughness: medium

Agent_2:
  name: "Competitor-Analysis"
  subagent_type: "general-purpose"
  prompt: |
    Search for competing products:
    - "{{芯片类型}} competing products"
    - "{{目标市场}} alternative solutions"

    Summarize:
    1. Feature comparison matrix
    2. Performance benchmarks
    3. Price points

Agent_3:
  name: "Tech-Trends"
  subagent_type: "docs-lookup"
  prompt: |
    Fetch documentation for:
    - Latest chiplet standards (UCIe 2.0/3.0)
    - Packaging technologies (CoWoS, EMIB, Foveros)
    - Memory technologies (HBM3e, DDR5)

    Return: key specifications, trends

整合调研结果到 ${OUTPUT_DIR}/market_analysis.md（可选）。

Phase 3: Executive Summary 生成

根据 scope 选择模板：

scope=chip：

1. 使用 templates/chip_prd_template.md
2. 填写产品定位、目标市场、关键差异化

scope=ip：

1. 使用 templates/ip_prd_template.md
2. 填写 IP 功能定位、目标应用

输出产物：PRD.md §1 Executive Summary

Phase 4: Use Cases & User Stories

设计内容：

1. 定义主要用例（UC-01 ~ UC-N）
2. 每个用例关联目标工作负载
3. 定义定量 KPI

格式：

| UC ID | Use Case | Target Workload | KPI |
|-------|----------|-----------------|-----|
| UC-01 | {{场景}} | {{benchmark}} | {{定量目标}} |

输出产物：PRD.md §2

Phase 5: Functional Requirements

根据 scope 分章节：

scope=chip 章节

1. Compute Requirements (REQ-COMPUTE-xxx)

   • FP16/INT8 吞吐量
   • 核心数量、频率

2. Memory Requirements (REQ-MEM-xxx)

   • HBM 容量、带宽
   • Cache 规格

3. Connectivity Requirements (REQ-IO-xxx)

   • PCIe、CXL、Ethernet 规格
   • D2D 互连带宽（UCIe）

scope=ip 章节

1. Function Requirements (REQ-FUNC-xxx)

   • IP 核心功能定义
   • 操作模式

2. Interface Requirements (REQ-INTF-xxx)

   • 信号列表、协议（AXI/APB）
   • 时序规格

输出产物：PRD.md §3

Phase 6: Non-Functional Requirements

设计内容：

1. Performance (REQ-PERF-xxx)

   • 最大频率、延迟

2. Power & Thermal (REQ-PWR-xxx, REQ-THERM-xxx)

   • TDP、空闲功耗
   • 温度范围、冷却方式

3. Cost & Area (REQ-COST-xxx, REQ-AREA-xxx)

   • BOM 成本预算
   • Die 面积约束

4. Reliability (REQ-REL-xxx)

   • MTTF、软错误率
   • ESD 规格

输出产物：PRD.md §4

Phase 7: Chiplet/IP 组成定义（仅 scope=chip）

加载知识库：references/chiplet-standards.md

设计内容：

1. Die Inventory（计算Die、I/O Die、Memory Die）
2. Process Node 分配
3. D2D Interconnect Requirements（UCIe 规格）
4. Package Requirements（封装类型、bump pitch）

输出产物：PRD.md §5-7

Phase 8: 软件与生态需求

设计内容：

1. ISA 定义（x86/ARM/RISC-V）
2. OS 支持（Linux/Windows/ESXi）
3. Framework 支持（PyTorch/TensorFlow）
4. Driver stack 要求

输出产物：PRD.md §10

Phase 9: 功能安全需求（可选）

当需求包含汽车/工业安全等级时启用。

加载知识库：references/functional-safety.md

设计内容：

1. ASIL 等级定义（ISO 26262）
2. Safety mechanisms（lockstep、ECC、DMR）
3. SPFM/LFM/PMHF 目标

输出产物：PRD.md §11

Phase 10: 安全需求（可选）

当需求包含安全场景时启用。

加载知识库：references/security-requirements.md

设计内容：

1. Root-of-Trust 位置
2. Secure Boot 流程
3. Side-channel 防护等级
4. Supply-chain 威胁模型

输出产物：PRD.md §12

Phase 11: 标准合规与里程碑

设计内容：

1. Standards Compliance Summary（UCIe、IEEE、JEDEC）
2. Milestones 定义（PRR、Arch Sign-off、RTL Freeze、Tape-out）
3. Timeline 制定

输出产物：PRD.md §13-14

Phase 12: Quality Checklist 验证

自动检查 PRD 质量：

- [ ] 所有 REQ-xxx 有唯一 ID
- [ ] 每条需求符合 SMART
- [ ] 性能指标有 min/typ/max
- [ ] Chiplet/IP 需求分层清晰
- [ ] UCIe 合规等级明确
- [ ] Power budget ≤ TDP（含 ≥10% margin）
- [ ] Area budget ≤ target
- [ ] Variability 已标注（corner/temp/voltage）

输出产物：PRD.md §16

Phase 13: Traceability Matrix 生成

生成需求追溯矩阵（RTM），关联 REQ ID 与后续文档：

| REQ ID | ARCH Ref | MAS Ref | VPlan Ref |
|--------|----------|---------|-----------|
| REQ-COMPUTE-001 | §3.1 | M01-MAS | VP-COMP-01 |

输出产物：traceability_matrix.md

Phase 14: 对抗性评审

调用评审：

Skill(skill="it.spec-review", args="--spec-path {{ OUTPUT_DIR }} --output-dir {{ OUTPUT_DIR }}/.review")

评审维度：

• 需求完整性
• 指标合理性
• 约束一致性
• 标准合规性

---

设计原则

PRD 特有原则

1. SMART 需求：每条需求必须 Specific/Measurable/Achievable/Relevant/Time-bound
2. 量化优先：避免"约"、"大约"、"最好"等软指标
3. 分层需求：系统级 vs 模块级需求清晰区分
4. Margin 预留：Power/Area budget 预留 ≥10% margin
5. Variability 标注：所有指标标注 corner/temperature/voltage

Agent-aware 文档设计

1. REQ ID 唯一且易追溯（REQ-COMPUTE-001）
2. 表格优于文字（指标表、规格表）
3. Mermaid 图表代替手绘流程
4. 引用明确的文档路径（→ DOC-D2-01-ARCH）

---

常见借口（均无效）

Agent 的借口	为什么错
"需求文档不完整，但可以先生成 PRD 框架"	PRD 空框架比没有更危险——下游 bb-arch 会基于错误假设展开，修正成本以人月计
"这个产品定位很明显，不需要澄清"	IC 设计 Tape-out 返工成本百万级，澄清成本为零；明显的定位往往隐藏分歧
"Margin 预留 5% 应该够用了"	PVT corner + IR drop + aging + 制造偏差通常吃掉 15%+；5% 在 silicon 验证时必然爆
"追溯矩阵可以事后补"	事后补的追溯矩阵几乎必然漏项，而漏项在 silicon debug 时才暴露，成本以周计
"性能指标暂时用 TBD，后续再定"	TBD 指标会传播到 bb-arch 的 timing budget，导致整个设计基础不稳
"竞品调研花时间，可以跳过"	不看竞品等于主动重复已知错误；IC 领域竞品失败案例是最宝贵的免费学习资源

---

降级策略

工具 / 资源缺失	降级方案
WebSearch 不可用	使用 parallel_search CLI：uv run parallel-search "{{query}}"
parallel_search CLI 不可用	跳过 Phase 2 竞品调研，在 PRD 中标注 "⚠️ 竞品分析待补充"
it.spec-review 不可用	使用 Phase 12 内置 Quality Checklist 代替对抗评审，结果内联到 PRD §16
市场数据不完整	使用保守估计，在 PRD 明确标注数据来源和置信度等级（High/Medium/Low）
安全等级未定义	根据应用场景推断（汽车→ASIL-D，工业→SIL-2，消费→无），标注 "⚠️ 推断值待确认"

---

输出模板

详见 templates/ 目录：

• chip_prd_template.md — Chiplet/SoC PRD 模板
• ip_prd_template.md — IP 模块 PRD 模板

---

参考文档

详见 references/ 目录：

• ic-terminology.md — IC 专业术语
• chiplet-standards.md — Chiplet 相关标准
• functional-safety.md — 功能安全规范
• security-requirements.md — 安全需求模板

---

最终验证实证（完成标准）

以下条件全部满足才可声明 PRD 完成，并触发 bb-arch handoff。缺一不可。

• prd/PRD.md 存在且所有章节非空（无 "TODO" 占位）
• 所有 REQ-xxx 有唯一 ID，无重复，无缺号
• 所有性能指标有 min/typ/max 三值（无 TBD）
• Power/Area budget 均预留 ≥10% margin
• traceability_matrix.md 存在且覆盖全部 REQ（覆盖率 100%）
• Phase 12 Quality Checklist 全部通过（无 ❌）
• it.spec-review 未报告 CRITICAL 级别问题（或已修复并记录）

禁止在上述条件未满足时声明 PRD 完成或触发 bb-arch。

---

Evolution Trigger Point

When any Phase fails:

1. Detect failure: Read {{ OUTPUT_DIR }}/execution.log
2. Invoke framework:

   bash {{ EVOLUTION_FRAMEWORK }}/evolve.sh \
     --skill "{{ SKILL_FILE }}" \
     --output "{{ OUTPUT_DIR }}" \
     --failure-phase "{{ FAILED_PHASE }}"
   

3. Framework handles: Analyze, modify, validate, rollback
4. Retry or escalate