Cm prd

cm-prd — 需求文档 → 开发规格生成

执行前读取 ../../runtime/project-context.md、../../runtime/review.md 与 ../../runtime/logging.md。Codex 入口为 $cm-prd；Claude Code 跨平台入口为 /cm-prd，macOS/Linux 另有历史别名 /cm:prd。

用户明确要求外部专家，或为本次规格任务开启 AUTO 时，读取 ../../runtime/external-expert.md 并执行 ../external-expert/SKILL.md 的任务路由。 AUTO 可把复杂方案比较路由到 CONSULT、权威事实查证路由到 VERIFY，其余保持 LOCAL。 外部结论属于需求/设计输入，必须在本地对照项目事实并进入正常规格人审；AUTO 不 授权外发 docs 或代码内容。

支持两种模式：新建需求和需求变更。

输入参数

用户本轮输入 格式：

• 新建模式：$cm-prd {项目文件夹路径}
• 变更模式：$cm-prd --change {N}.{feature-name} 变更内容描述
• 可选用例输入：追加 --cases {json/md/txt路径}，或在本轮消息直接粘贴用例

用户提供一个项目文件夹路径，文件夹结构约定：

{项目文件夹}/
├── docs/           ← 需求文档（必须存在，PRD 从这里读取）
├── 1.xxx/          ← 已有的 specs（如有）
├── 2.xxx/          ← 本次生成的 specs
└── ...

项目角色路由

路径验证通过后，使用 {CM_WORKFLOW_ROOT}/scripts/cm_workflow_config.py 读取有效配置， 分别解析 analyst（需求分析）和 planner（方案/任务拆分）：

python3 {CM_WORKFLOW_ROOT}/scripts/cm_workflow_config.py \
  --project {CODE_PROJECT} --role analyst --runtime {codex|claude} --print-role
python3 {CM_WORKFLOW_ROOT}/scripts/cm_workflow_config.py \
  --project {CODE_PROJECT} --role planner --runtime {codex|claude} --print-role

把返回的 adapter、model、source 和 route_state 当作本轮的请求路由元数据， 在对应分析/规划提示中注明；model 是别名，不能声称为已观测的后端模型。每次角色 边界按 runtime/workflow-routing.md 写一条 decision/phase: route 事件。配置未提供 时使用内置默认值；resolver 返回非零或配置错误时立即 BLOCKED 并报告字段路径， 不得进入分析/规划或生成规格。配置的适配器当前运行时不可用时记录 warning/degrade， 不得伪造调用成功或把外部专家变成编码执行器。

项目/specs 路径验证通过后按 runtime/logging.md 写 run_start。生成规格、重置 审批位或终止时分别写 spec_lifecycle 与 run_done；详细需求和设计内容不进入主日志。

模式判断

如果 用户本轮输入 以 --change 开头 → 读取 references/change-mode.md 执行变更模式（C1–C8） 否则 → 进入新建模式

---

新建模式

Step 1: 解析输入，读取需求文档

从 用户本轮输入 提取项目文件夹路径，记为 SPECS_DIR。

读取 {SPECS_DIR}/docs/ 下的所有文件作为需求源：

• 支持 .md、.txt、.pdf、.html 等文档格式

• HTML 交互原型（可点击 PRD）→ 执行交互遍历协议，禁止只做静态截图。可交互原型是一份可执行的需求文档，必须用无头浏览器（Playwright / Chrome DevTools）主动遍历：

  1. 枚举每个页面的全部可交互元素（按钮/链接/tab/表单/开关/列表项…）
  2. 逐个操作并记录三元组：元素 → 动作 → 结果（跳转到哪/弹了什么/状态怎么变/无响应）
  3. 产出功能点清单：每个有响应的交互 → 对应一条 [F-xxx]；点了没反应的 → 列为"原型死区"进开放问题（问用户：是原型没做完，还是本就不需要？不许静默丢弃）
  4. 覆盖率自检：可交互元素总数 = 功能需求数 + 死区数，对不上不得进入 Step 6
  5. 遍历过程中逐状态截图（Step 8.5 的候选基准）；三元组记录直接生成交互流 AC 与 E2E 走查清单

  原型首先是需求，其次才是视觉候选。注意原型通病：只画理想态——异常态/空态/边界值靠 Step 5.5 歧义五问补齐

• 如果 docs/ 下有多个文件，全部读取并综合分析

• 输入含 --cases 或本轮粘贴了测试用例时，将其作为用户来源交给 Step 10.4； JSON 先做语法校验，Markdown/文本在生成时归一化为测试合同

• 如果 docs/ 不存在或为空，报错提示用户先在 docs/ 下放入需求文档

Step 2: 获取项目名称

• 从当前目录的 package.json name 字段、Cargo.toml、go.mod 等提取项目名
• 如无法提取，使用当前目录名
• 转为 kebab-case，记为 PROJECT_NAME

Step 3: 探测项目架构类型

代码项目根的确定（防在错误目录生成脏规格）：用户本轮输入 中显式给了代码项目路径（如 代码在~/code/app）→ 以其为准；未给 → 用当前工作目录（约定:在代码项目内运行本命令），但必须先自检——当前目录含项目描述文件或源码、且其内容与需求文档所述业务相符；明显不符（如当前目录是另一个项目/工具仓库）→ 停下询问代码项目路径，不得静默把错误目录当项目上下文（空目录检测只兜全空 case，兜不住"错但有效"的目录）。

扫描项目根目录、配置文件、目录结构、依赖声明，自行判断架构类型（monorepo / 多仓库 / 单体应用 / Web3 等）。记录 ARCH_TYPE。

空项目检测：代码项目不存在、或为空目录（无 package.json / Cargo.toml / go.mod 等项目描述文件，且无源码目录）→ 先问用户确认空目录的含义，不得自行假设：

"代码目录为空——这是【全新项目】（走 0→1 分支，我来推荐架构和脚手架），还是【存量项目还没 clone】（请先 clone 到该目录，再重新运行 $cm-prd）？"

• 确认全新项目 → 标记 GREENFIELD=true，读取 references/greenfield.md 叠加 G1–G4 规则，Step 4 跳过
• 确认未 clone → 中止本次执行，提示 clone 完成后重跑（在不存在的项目上下文上生成 design.md 是有毒规格）

Step 4: 读取项目上下文（存量项目 = 二开模式，叠加 B 规则）

• 读取各仓库的 .claude/CLAUDE.md 了解技术栈
• 读取 .claude/rules/ 下所有规则文件
• 扫描目录结构，了解现有模块划分
• B1 加载代码库参考文档：先读代码项目根 CLAUDE.md 的「业务地图」字段（多层仓库下以代码项目根为准，仓库根 CLAUDE.md 无此字段再看地图 00-index 头部；init 已判定过，不重复判断）：字段=已生成/已刷新 或 docs/codebase-context/ 存在 → 按 codebase-context skill dev 模式加载 10 份文档（后续步骤查重与波及面分析的数据源）；字段=跳过(小项目) → 不建议 scan，直接读代码（小项目全量读的成本本来就低）；字段缺失且文档不存在 → 建议先执行 /codebase-context scan；skill 本身未安装 → 提示重装最新包，本次降级为直接读代码，波及面分析降级为 grep 推断（照常可跑，只是更贵更粗）

二开模式追加规则（GREENFIELD=false 且本次需求会修改存量代码时生效）→ 读取 references/brownfield.md 执行 B2 波及面 / B3 防护网基线 / B4 增量 specs / B5 拆分锚定地图。

Step 5: 分析需求

调用 cm-product-manager skill 执行本步和 Step 5.5——用户故事、编号功能需求、验收标准的编写方法和歧义五问以该 skill 为准。

需求涉及交易/资产/支付/代币/证券/金融营销时，同时加载 cm-finance-expert skill 协同：领域正确性审核 + 营销合规红线扫描 + 合规开放问题（并入 Step 5.5）。法域确认结果须写入代码项目 .claude/rules/finance.md 头部字段；文件不存在时，以 {CM_WORKFLOW_ROOT}/templates/rules/finance.md 为骨架现场补生成，并在 AGENTS.md 与 CLAUDE.md 的相关规则说明中补充引用。

从文档中提取功能目标、用户故事、验收标准、约束条件、依赖。

Step 5.5: 开放问题确认

分析需求后，如果存在以下情况，必须暂停并与用户对话确认，不要自行假设：

• 需求描述模糊或有歧义的功能点
• 多种技术实现方案且差异较大
• 缺少关键信息（如目标平台、兼容性要求、第三方服务选型）
• 业务逻辑有矛盾或不完整
• 涉及权限、支付、敏感操作等需要明确确认的功能

格式：

❓ 需要确认以下问题：

1. {问题描述} — {为什么需要确认}
2. {问题描述} — {为什么需要确认}

请逐一回复后继续生成 specs

所有问题确认完毕后再进入 Step 6。

Step 6: 推断 feature 名称

根据需求内容生成一个简洁的 kebab-case 英文名称。

Step 7: 生成 specs 目录

检查 {SPECS_DIR}/ 下已有的编号目录（如 1.xxx/、2.xxx/），取最大编号 +1。

{SPECS_DIR}/
├── docs/                        ← 需求文档（输入）
├── 1.比如这是一个已有的标题/     ← 已有 specs
└── 2.{feature-name}/            ← 本次新建
    ├── requirements.md
    ├── design.md
    ├── tasks.md
    └── test-cases.json           ← 有可观察行为时生成

Step 8: 生成 requirements.md

# {Feature 名称} — 需求规格

## 概述

{一句话描述}

## 项目信息

- 项目名: {PROJECT_NAME}
- 架构类型: {ARCH_TYPE}

## 需求版本

| 日期         | 版本 | 说明     |
| ------------ | ---- | -------- |
| {YYYY-MM-DD} | v1   | 初始需求 |

## 用户故事

- 作为 {角色}，我想要 {功能}，以便 {价值}

## 功能需求

1. [F-001] {需求描述}
2. [F-002] {需求描述}

## 非功能需求

- 性能: {要求}
- 安全: {要求}
- 兼容性: {要求}

## 验收标准

- [ ] [AC-001] {标准描述}

## 依赖

- {外部服务/库}

## 开放问题

- {待确认事项}

Step 8.5: UI 设计基准（涉及 UI 的 feature）

feature 涉及页面/界面时，在生成 design.md 前确定设计基准：

• 有 Figma/设计稿 → 通过 MCP 导出截图 + token 提取物，落盘 {SPECS_DIR}/{N}.{feature-name}/design-baseline/（防链接失效与云端改版导致基准漂移）
• 有 Stitch 项目 → 通过 Stitch MCP 拉取设计并导出 HTML/CSS 落盘 design-baseline/；导出的 HTML 按 Step 1 交互遍历协议处理（多屏/流转设计可直接提取交互流与功能点）——Stitch 导出物默认按像素基准对待（它就是设计本体，不是示意）
• 有 HTML 交互原型（Step 1 已截图）→ 必须人工三选一确认基准档位（中性提问不带引导；高保真原型建议像素档，线框灰稿建议结构档）：
  • ① 像素基准：UI 与交互 1:1 还原——截图落盘 design-baseline/ 作 BackstopJS 基准（≤1%），且交互流提取为 E2E 走查清单（每个跳转/状态切换/反馈逐条断言，交互不 1:1 视为验收失败）
  • ② 结构基准（多数原型的合理档）：页面结构、信息层级、交互流程必须一致，视觉样式可再设计——验收为逐页元素清单核对 + 流程走查
  • ③ 纯参考：仅辅助理解需求，无对照验收——选此档即明确接受 UI 由 AI 自行发挥（历史事故：原型被降为参考后，产出与原型完全不符） 档位写入 design.md「设计基准」节；无论哪档，原型的页面清单与跳转流程都已是需求的一部分（Step 1 规则），流程不允许自由发挥
• 无设计稿且环境已安装 huashu-design skill → 调用其生成高保真原型（要求包含 hover/空态/错误态等交互态），落盘同上；人审规格时一并确认设计方向（复用既有强制卡点，执行期零设计决策）
• 两者皆无 → 不建基准、不生成 UI 还原任务，该 feature 的 UI 由前端任务按 design.md 自行实现；可提示用户 npx skills add alchaincyf/huashu-design

基准机读化(四种来源统一要求——截图给人看,规格表给 AI 抄):design-baseline/ 除截图外必须含逐元素规格表(spec-sheet.json:字体五件套/色值/几何/间距)。AI 看图估值的精度天花板极低,是还原度不理想的头号根因(实跑反馈);规格表按基准形态产出:

• Figma MCP → 直接读取节点精确值(排版/填充/自动布局间距)导出成表,不经截图转译
• Stitch 导出 / HTML 原型 → 用 {CM_WORKFLOW_ROOT}/templates/ui-lens/cm-ui-lens-extract.mjs 对基准页提取计算值成表；样式值优先移植改造而非重新想象
• 纯截图(最弱形态) → 色板可精确采样成表;几何只能估算——规格表标注「几何估算档」,并明确提示用户:有 Figma/原型源尽量给源,纯截图基准的还原精度天花板显著更低
• 基准字体文件一并落盘(还原页先加载同款字体再对比,防字体回退噪声淹没真差异)

有基准时，design.md 记录基准路径，且「接口契约」节须包含组件契约（组件名 / props / 事件）。

Step 9: 生成 design.md

必须先读取项目 .claude/CLAUDE.md 和 .claude/rules/ 下所有规范文件，设计方案必须遵循项目已有的技术规范和约定。

按功能模块设计，每个模块说明涉及哪些层（前端、后端、数据库、合约等），具体分层根据项目实际架构决定，不做硬编码限制。

# {Feature 名称} — 技术设计

## 设计版本

| 日期         | 版本 | 说明     |
| ------------ | ---- | -------- |
| {YYYY-MM-DD} | v1   | 初始设计 |

## 项目架构

- 架构类型: {ARCH_TYPE}
- 涉及层: {根据项目实际情况列出}

## 功能模块设计

### 模块 1: {模块名}

{技术方案，遵循 .claude/rules/ 中的规范}

**涉及层及关键设计:**

{根据项目实际分层描述，如数据模型、API 接口、组件设计、合约接口等}

### 模块 2: {模块名}

...

## 接口契约

{API、RPC、合约接口等 — 根据项目类型决定}

## 数据模型

{数据表/模型/链上存储 — 根据项目类型决定}

## 安全考虑

{基于 .claude/rules/security.md 和项目特有的安全规范}

## 技术决策

| 决策 | 选项 | 理由 |
| ---- | ---- | ---- |

Step 9.5: 方案对抗审查（最贵的决策补上第二双眼睛）

design.md 生成后，满足任一触发条件 → 按 runtime/review.md 交新上下文的独立审查者对抗审查一轮：

• GREENFIELD 的 ADR（架构选型是最贵决策）
• 二开且修改存量模块（方案错误会伤及老功能）
• design 含新模块、依赖方向变化或跨模块数据流
• 功能点 F ≥ 5 的大 feature

投喂内容：requirements.md + design.md 全文 + 项目上下文中的相关规范 +（二开）「波及面」段与被改存量模块现状代码。 提示词要义："这是隔壁同事做的方案，详细审查一下"——重点查架构隔离、模块边界、与现有管线的耦合、数据流缺口；只报告有具体失败场景的问题，零发现明说（审查产出纪律同 N4）。仅 1 轮：采纳项修正 design.md 后进 Step 10；分歧项写入摘要卡「风险点」交人裁决。小 feature 不触发，零额外负担。 凭证落盘:审查原文 tee 到 {SPECS_DIR}/.reviews/prd-{feature}-design-r1.md——摘要卡「方案对抗审查」行必须与凭证对得上,无凭证的数字是自报(凭证教义全框架一体,规格期不豁免)。

依据：代码有 N4 对抗、规格有 10.5 自检，唯独技术方案此前无第二模型把关——而方案错误是最贵的错误（行业重度实践的最大单笔收益正是方案期拦截架构缺陷）。

Step 10: 生成 tasks.md

按功能拆任务。 AI 执行时根据 design.md 自动判断每个任务涉及哪些层。

# {Feature 名称} — 任务清单

## 任务版本

| 日期         | 版本 | 说明     |
| ------------ | ---- | -------- |
| {YYYY-MM-DD} | v1   | 初始任务 |

## 项目信息

- 项目名: {PROJECT_NAME}
- 架构类型: {ARCH_TYPE}
- specs 路径: {SPECS_DIR}/{N}.{feature-name}/

## 任务列表

### UI 还原（仅当存在 design-baseline 时生成本节）

- [ ] T-001: 还原 {页面/组件} ~30min（基准: design-baseline/；本 feature 的前端功能任务依赖本任务）

### 功能 1: {功能名}

- [ ] T-002: {任务描述} ~{预估时间}
- [ ] T-003: {任务描述} ~{预估时间}

### 功能 2: {功能名}

- [ ] T-003: {任务描述} ~{预估时间}

### 集成与测试

- [ ] T-010: 联调测试 ~{预估时间}
- [ ] T-011: E2E 测试 ~{预估时间}
- [ ] T-012: 部署 staging 并冒烟验证 ~15min（依赖本 feature 全部开发与测试任务）

> 部署任务前提：项目存在部署形态（Dockerfile / CI 配置 / 部署脚本，或 0→1 项目——bootstrap 已建 CI 骨架）才生成 T-012；**纯本地工具、库等无部署形态的项目不生成**，避免执行期反复触发"无 staging 环境"上报。

## 依赖关系

- T-002 依赖 T-001

## 风险点

- {可能遇到的问题及应对}

任务拆解原则：

• 按功能拆，AI 执行时读 design.md 自动识别涉及哪些层；二开项目按 B5 锚定业务地图（feature 沿 07 线路、任务尽量单模块）
• 原子性，可独立完成和验证
• 同一组件/同一文件内的行为不拆分为多个任务（如"渲染列表项"和"列表项的删除确认"归一个任务）——拆开会导致执行时自然合并、任务标记与提交失配（实跑验证的教训）
• 预估完成时间（5min / 15min / 30min / 1h）
• 粒度控制：每个子 specs（feature 目录）不宜过大，单个 tasks.md 控制在 10-15 个任务以内。如果需求过大，应在 Step 6 之前拆成多个独立的 feature 目录（如 2.user-auth-login、3.user-auth-register），每个 feature 有自己的 requirements/design/tasks 三件套。这样 cm:ai 执行时上下文可控，不会因为 specs 太大导致丢失关键信息。

Step 10.4: 生成 AI 测试合同（条件触发）

读取 ../../runtime/test-contract.md，按其中的生成条件为适用 feature 写 test-cases.json。用户或需求源提供的用例优先且标记 origin: "user"；其余根据 AC、design 和 tasks 补齐，保证 AC→TC→Task 可追踪。纯文档/注释/类型/无行为重构 不生成空文件。写完执行 scripts/validate-test-cases.py。

Step 10.5: 规格自检（机器项，AI 自查自修，人不参与）

读取 references/spec-self-check.md 并逐项执行；测试合同必须调用 scripts/validate-test-cases.py，不得靠目测。

Step 10.6: 独立规格审查

10.5 自检是机器项，查不出「拆得对不对」。自检通过后，按 runtime/review.md 把拆分结果交给新上下文的独立审查者：

• 投喂内容：requirements.md 功能点清单 + tasks.md 全文 + design.md「波及面」段（二开）——喂拆分结果，不喂三件套全文
• 提示词要义："这是隔壁同事拆的开发任务单，审查拆分质量：①任务边界有无重叠/遗漏 ②依赖顺序会不会卡死 ③粒度是否适合单任务交付验证 ④二开：波及面清单有没有漏掉会被牵连的模块。只报有具体后果的问题，没有问题就明说。"
• 处置：采纳项修正 specs 后重跑一次 10.5 自检；分歧项写入摘要卡「风险点」交人裁决。仅 1 轮，不与 Codex 拉扯
• 凭证落盘：原始审查结果写入 {SPECS_DIR}/.reviews/prd-{feature}-split-r1.md，文件头使用 review contract 的 reviewer/independent/at/scope 字段
• 降级：无法建立独立上下文时，由主执行者对抗式复查，凭证写 self-degraded / independent: false；这是增益层，不单独因降级停车

依据：拆分质量是二开乱改的最后闸门——10.5 只能查机器项（引用真实性、依赖环），"这个任务拆得会不会漏改关联模块"需要第二模型的判断力。

Step 11: 输出总结（附规格摘要卡 + 审查清单）

先输出规格摘要卡——人审的第一入口是这张一屏卡片，不是三个长文件（实跑教训：直接丢长文件，人审会退化成扫一眼就"通过"）：

┌─ 📋 规格摘要卡 ────────────────────────────
│ 交付形态: {Web/App/小程序…}   ← 第一分叉,看错全错
│ Feature: {N 个}: {名称列表}
│ 功能点: {N} 个 | AC: {N} 条 | 任务: {N} 个(预估 {x}h)
│ 开放问题: {已答 N / 共 N}——{逐条一行: 问题→答案}
│ 风险点: {金融/合规/破坏性操作等敏感项,无则"无"}
│ UI 基准: {像素级/结构级/纯参考/无}
│ 🧪 AI 测试合同: {N 条(user N/generated N) / 跳过(无可观察行为)}
│ 🔎 规格自检: {N}/{N} 通过{（未过项已列入风险点）}
│ 🧠 方案对抗审查: {通过 / {N}条已修 / 跳过(未触发)}
│ 🤖 独立规格审查: {通过 / {N}条已修 / 降级自审}
└────────────────────────────────────────────
有疑问的行,点开对应文件细看;摘要卡没问题再走下面的审查清单。

完成后报告：

• Feature 名称和序号、Specs 路径、涉及的技术层、总任务数和预估总时间

并输出规格审查清单——人审规格不是"看一眼"，按此逐项检查：

📋 规格审查清单（人审时逐项勾选）
- [ ] 任务跨 feature 查重：同一产物（文件/模块）未出现在多个任务中（实跑教训：bootstrap 底座与 feature 数据层重复）
- [ ] 依赖关系完整：每个任务的前置依赖已声明，无环
- [ ] AC 可测试：每条验收标准都能回答"怎么验证"
- [ ] 粒度合规：同一组件/文件的行为未拆成多任务；单 feature ≤15 个任务
- [ ] 开放问题已全部回答，敏感决策（法域/支付/权限）有人工确认记录
- [ ] **交付形态与需求意图一致**（要 App 别画成网页），且已写入 ADR 与 CLAUDE.md 字段
- [ ] **原型功能点覆盖 100%**（有交互原型时）：遍历记录中每个可交互元素都有对应 [F-xxx] 或死区标注，无静默丢弃

规格审批位落盘：报告输出后，按 runtime/test-contract.md 计算已生成 test-cases.json 的 SHA-256，并写入 {SPECS_DIR}/.cm-specs-status 单行 JSON： {"status":"awaiting_review","at":"{时间}","features":["1.xxx",...],"testCases":[{"path":"1.xxx/test-cases.json","sha256":"..."}]} 随后写 spec_lifecycle/generated、spec_lifecycle/awaiting_review 和 run_done，仅记录 feature/task/case 数量、状态与 specs 路径。

硬停车（不可违反）：本命令的终点就是摘要卡与审查清单——任何情况下不得在本会话顺势启动开发，对话里的"继续"不构成开发授权。提示用户：逐项审查通过后，运行 $cm-ai 开始开发（N1 有入口闸：未审批的 specs 会先要求确认摘要卡）