weigre/interaction-doc

interaction-doc · 交互式产品文档

interaction-doc 是一个 Claude Code 技能，它接收模糊的产品诉求、一句话功能想法或完整 PRD，通过多轮交互式问答将其澄清，并产出一份可用、闭环、可落地的交互文档（交互文档.md）——一份前端、后端和 QA 工程师可以直接据此开发的规格说明。

提炼自真实企业级项目经验（一个 DAM 数字资产管理一期项目：20 章 / 1700+ 行交互文档）。

为什么需要它

产品需求很少一开始就清晰。直接撰写文档常见的坑包括：

- 术语未定义（例如从未有人定义过的“资产负责人”）
- 状态机死锁（例如空子分类无法删除，但也没有其他方式清理它）
- 孤立引用（“见 11/18”，而实际章节是 11/19）
- 定义缺失：入口点未定义功能、权限矩阵与页面级描述相互矛盾

这些问题会在开发阶段暴露，修复成本极高。interaction-doc 通过三层机制在文档阶段就将其消除：交互式提问、冲突检测和闭环检查。

对模糊需求效果显著：需求只有两句话？没问题——该技能会逐步提问（业务目标 → 角色与权限 → 实体状态机 → 流程 → 字段级校验），并随着回答的推进同步撰写文档。

让不负责任的 PM 无处遁形：每一条未经确认的规则都会被明确标记为“待确认”，并记录在待解决问题附录中。该技能绝不会替用户臆造规则。

功能特性

| 功能 | 说明 |
|---------|-------------|
| 交互式澄清 | 从高层到低层的多轮问答（通过 AskUserQuestion），每轮之后进行冲突检测；未解决的问题绝不会被悄悄决定 |
| 可直接投产的输出 | 每个功能规格都包含：入口点、步骤、校验规则（含边界值）、后置条件、权限、空/错误状态以及文案——模糊的文档无法据此开发 |
| 闭环保障 | 交付前检查清单：无状态机死锁、无孤立交叉引用、权限矩阵与页面可见性一致、每个入口点都有完整流程 |
| 需求覆盖审计 | 交付前，每条输入需求都会在覆盖表中映射到其文档章节（需求 → 来源 → 章节 → 状态），实现完全可追溯 |
| 关键 API 契约 | 核心业务模块包含接口表（名称 / 方法 / 路径 / 关键参数 / 返回值 / 权限），使前后端直接对齐 |
| 版本管理 | 版本头加上修订历史附录，便于清晰地跟踪迭代 |
| 源自企业实践经验 | 基于真实 DAM 项目复盘构建：问答轮次记录、死锁案例和交叉检查遗漏（见 references/dam_case.md） |

安装

方式一：插件市场（推荐，自动更新）

/plugin marketplace add weigre/interaction-doc
/plugin install interaction-doc@interaction-doc

方式二：手动安装

git clone https://github.com/weigre/interaction-doc.git
cp -r interaction-doc/plugins/interaction-doc/skills/interaction-doc ~/.claude/skills/

方式三：.skill 包

下载 dist/interaction-doc.skill 并解压到 ~/.claude/skills/interaction-doc/。

使用

只需说明你的需求，例如：

- “根据这份 PRD 生成一份交互文档”（你可以附上 PRD 文件）
- “我想构建一个内部设计资产管理系统，包含前端和后端”
- “把这份遗留交互文档修订成闭环、可交付的规范”
- “带我梳理一下这个功能的流程”

工作流

阶段 0    理解输入      → 模糊需求 / 完整 PRD / 遗留文档迭代；构建事实清单
阶段 1    问答循环      → 高层（目标/角色/状态机）→ 低层（字段/校验/文案）；
每轮进行冲突检查；已确认的决策立即写入文档
阶段 2    构建文档      → 按页面组织 + 每页布局草图 + 关键 API 契约表
阶段 3    闭环检查      → 引用 / 权限 / 状态机 / 流程 / 错误 / 空状态 / 术语 / 数值一致性
阶段 3.5  需求审计      → 将每条输入需求映射到对应章节
阶段 4    交付          → 交互文档.md（包含版本、覆盖表、修订历史、附录）

质量

在开发过程中，使用/不使用该技能对 4 组场景进行了评估（模糊需求 / 完整 PRD / 矛盾文档迭代 / 企业 DAM PRD），并持续迭代直至稳定：

- 使用技能：30/30 断言通过（权限矩阵、状态机、校验规则、接口列表、需求覆盖表、孤立引用等）
- 不使用技能的基线在接口列表和覆盖审计等关键断言上显示出明显差距

仓库结构

interaction-doc/
├── marketplace.json              # 插件市场清单
├── plugins/interaction-doc/
│   ├── .claude-plugin/plugin.json
│   └── skills/interaction-doc/
│       ├── SKILL.md              # 核心工作流（阶段 0-4 + 闭环检查清单）
│       └── references/
│           ├── doc_structure.md  # 推荐章节结构模板
│           └── dam_case.md       # 企业案例复盘（真实世界参考）
└── dist/
└── interaction-doc.skill     # 打包后的 .skill 文件

许可证

MIT 许可证