bb-prd - SKILL.md Agent Skill

name: bb-prd description: "生成芯片/IP 产品需求文档（PRD），从市场需求和技术约束输出专业 PRD 规范。Generate Product Requirements Document for chip/IP design projects. Trigger: /bb-prd, PRD生成, 产品需求文档, 芯片立项, IP需求, chiplet specification" user-invocable: true self-adaptive: true self-evolving: true version: "1.0.0" arguments:

name: input_dir description: "包含市场需求文档或 idea 文件的目录路径（markdown 格式）" required: true
name: project_dir description: "项目目录路径，默认自动检测" required: false
name: scope description: "设计范围：chip（芯片级/Chiplet）或 ip（IP模块级）" required: false default: "chip"
name: auto_approve description: "跳过用户批准点，自动生成所有章节" required: false default: "false"
name: finetune description: "启用详细调试输出模式" required: false default: "false"
name: update description: "更新模式：auto（自动检测变更）| full（强制归档+全量重建）| patch（强制就地更新，不归档）" required: false default: "auto" handoffs:
target: bb-arch condition: "PRD document completed and approved" session_note: "PRD 完成后可进入架构设计阶段，调用 bb-arch" transfer_files:
- "{{OUTPUT_DIR}}/*.md" evolution: enabled: true trigger: on_failure max_attempts: 3 protected_zones:
- frontmatter.name
- frontmatter.description
- HARD-GATE section
- Self-Adaptive 初始化 section depth_policy: conservative: auto local: auto system: confirm data_sources:
- execution_log
- evolution_history
- failed_paths

output_dir: ./prd scope: chip language: zh-CN finetune: false auto_approve: false update: auto

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 存在

加载配置文件

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"]

创建执行日志目录

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: 输入解析

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

输出产物：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：

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

scope=ip：

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

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

Phase 4: Use Cases & User Stories

设计内容：

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

格式：

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

输出产物：PRD.md §2

Phase 5: Functional Requirements

根据 scope 分章节：

scope=chip 章节

Compute Requirements (REQ-COMPUTE-xxx)
- FP16/INT8 吞吐量
- 核心数量、频率
Memory Requirements (REQ-MEM-xxx)
- HBM 容量、带宽
- Cache 规格
Connectivity Requirements (REQ-IO-xxx)
- PCIe、CXL、Ethernet 规格
- D2D 互连带宽（UCIe）

scope=ip 章节

Function Requirements (REQ-FUNC-xxx)
- IP 核心功能定义
- 操作模式
Interface Requirements (REQ-INTF-xxx)
- 信号列表、协议（AXI/APB）
- 时序规格

输出产物：PRD.md §3

Phase 6: Non-Functional Requirements

设计内容：

Performance (REQ-PERF-xxx)
- 最大频率、延迟
Power & Thermal (REQ-PWR-xxx, REQ-THERM-xxx)
- TDP、空闲功耗
- 温度范围、冷却方式
Cost & Area (REQ-COST-xxx, REQ-AREA-xxx)
- BOM 成本预算
- Die 面积约束
Reliability (REQ-REL-xxx)
- MTTF、软错误率
- ESD 规格

输出产物：PRD.md §4

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

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

设计内容：

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

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

Phase 8: 软件与生态需求

设计内容：

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

输出产物：PRD.md §10

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

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

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

设计内容：

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

输出产物：PRD.md §11

Phase 10: 安全需求（可选）

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

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

设计内容：

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

输出产物：PRD.md §12

Phase 11: 标准合规与里程碑

设计内容：

Standards Compliance Summary（UCIe、IEEE、JEDEC）
Milestones 定义（PRR、Arch Sign-off、RTL Freeze、Tape-out）
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 特有原则

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

Agent-aware 文档设计

REQ ID 唯一且易追溯（REQ-COMPUTE-001）
表格优于文字（指标表、规格表）
Mermaid 图表代替手绘流程
引用明确的文档路径（→ 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:

Detect failure: Read {{ OUTPUT_DIR }}/execution.log

Invoke framework:

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

Framework handles: Analyze, modify, validate, rollback
Retry or escalate