# xiaoma-prd-clarify · 使用与维护说明

> 面向人的说明文档。Claude 执行时读 `SKILL.md` 与 `references/`，本文件不参与运行。

## 这个 Skill 做什么

以**资深研发视角**审视 PRD，系统识别其中的缺失、模糊、歧义、矛盾，产出结构化的《需求澄清问题清单》（含 P0 / P1 / P2 分级与待确认项），并对 PRD 的**可开发成熟度**量化评分。定位为"需求澄清助手 / 质量守门员"——只提问、不替产品臆测补全。

## 何时被触发

在公司内网 Claude Code / 小码（XiaoMa）框架中，研发承接需求、需求评审、开发前对齐等环节随需触发。常见触发语：PRD 澄清、需求澄清、需求评审、需求看不懂、这个需求不清楚、帮我看看这份 PRD、需求文档哪些没说清楚、字段取值 / 边界 / 逻辑不明确、需求准入评估、PRD 质量检查。也可显式调用，如"用 xiaoma-prd-clarify 帮我澄清这份需求"。

## 怎么用

1. 触发后，向它提供 PRD：上传文件、给出文件路径、或直接粘贴文本（支持 `.docx` / `.md` / `.pdf` / `.txt`）。
2. 可选补充上下文：所属业务域、关联系统、已有数据字典或字段规范，以提升检查针对性。
3. 它会按七维逐项扫描，输出澄清清单 + 成熟度评分，并逐条定位到 PRD 原文。
4. 支持多轮：可针对某条目继续追问，或在补充产品答复后请求重新评估。

## 目录结构

```text
xiaoma-prd-clarify/
├── SKILL.md                      # 主指令：触发说明 + 工作流 + 关键约束
├── README.md                     # 本文件：面向人的使用与维护指引
├── references/
│   ├── checklist.md              # 七维（A~G）检查清单规则库
│   ├── scoring.md                # 可开发成熟度评分模型与权重
│   └── output-template.md        # 澄清清单 + 评分报告输出模板
├── examples/
│   └── example-clarification.md  # 完整示例：PRD 片段 → 清单 + 评分
└── scripts/
    └── export_to_excel.py        # 可选：将澄清清单导出为 .xlsx（纯标准库，内网可用）
```

## 渐进式披露

三层加载，避免 context 膨胀：

1. **元信息**（`SKILL.md` frontmatter 的 `name` + `description`）常驻，用于判断是否触发。
2. **`SKILL.md` 正文**在触发后加载，给出执行框架与关键约束。
3. **`references/`** 下的检查清单、评分模型、输出模板，由 Claude 在对应步骤按需读取。

## 如何维护规则（非开发人员也能改）

- **加检查点**：把历史高频模糊点补进 `references/checklist.md`（对应维度下追加一条，写清"检查要点"）。
- **调评分**：在 `references/scoring.md` 改维度**权重表**（保持合计 100%）、**标尺**或**准入门槛**。
- **改输出**：在 `references/output-template.md` 调整字段与呈现格式。
- **按业务域沉淀**：在 `checklist.md` 末节追加票据 / 信贷等专属检查片段。
- 改完即生效，无需改动 `SKILL.md` 主流程。

## 接入与试点

**接入小码（XiaoMa）/ Claude Code：**

- 随小码框架一同安装：随项目安装后，技能目录平铺到用户项目的 `.claude/skills/xiaoma-prd-clarify/`（`SKILL.md` + `references/` + `examples/` + `scripts/` 全部 verbatim 落地），无需额外配置。
- 三种触发：① 自然语关键词自动触发（见"何时被触发"）；② 菜单码 `PC`（在 `xiaoma-help` 菜单中）；③ 显式调用，如"用 xiaoma-prd-clarify 帮我澄清这份需求"。
- 输出语言默认中文；若项目 `_xiaoma/xmc/config.yaml` 配了 `communication_language` 则跟随。

**试点方法（验证 P0 / P1 召回率 ≥ 80%）：**

1. 选取若干份**真实**且已上线 / 已评审过的 PRD 作为样本。
2. 由资深研发**人工**标注每份 PRD 的 P0 / P1 澄清点，作为基准答案。
3. 对同一份 PRD 运行本技能，将其产出的澄清清单与人工基准比对，统计 P0 / P1 召回率与误报情况。
4. 召回率达标即可推广；未达标时，把漏检的高频模糊点**回填进 `references/checklist.md`** 对应维度，迭代规则库后重测。
5. 按业务域（票据 / 信贷等）分别试点，沉淀专属检查片段。

## 安全与合规

运行于公司内网 Claude Code 环境，PRD 文档不离开受控环境；本 Skill 不引入任何将文档内容外发至不受控外部服务的行为。导出脚本为纯标准库实现，无需联网或额外依赖。

## 边界

帮助开发更快读懂并澄清需求，**而非替产品经理编写或臆测补全 PRD**。无法从原文判断的内容，一律以"待确认提问"呈现。