Skip to content

raidenfc/my-skills / source-to-product-doc

source-to-product-doc

Verified

从全栈项目源码梳理业务能力并生成面向运营、商户运营和产品人员的 Markdown 产品文档。用户要求阅读源码、反推产品逻辑、编写运营手册或产品说明书时使用;适用于含前端、后端、数据库、异步任务、配置或既有文档的仓库。

FileKindSize
SKILL.mdskill md6.7 KB
agents/openai.yamlconfig291 B
references/product-document-template.mdmarkdown2.8 KB
---
name: source-to-product-doc
description: 从全栈项目源码梳理业务能力并生成面向运营、商户运营和产品人员的 Markdown 产品文档。用户要求阅读源码、反推产品逻辑、编写运营手册或产品说明书时使用;适用于含前端、后端、数据库、异步任务、配置或既有文档的仓库。
---

# 源码生成产品文档

将代码实现转换为可供业务人员阅读的产品说明。优先保证规则真实、范围明确;不要将目录、接口或推测包装成产品能力。

## 输出与范围

- 默认输出简体中文 Markdown;遵循用户指定的语言、读者、文件位置和范围。
- 默认读者是运营、商户运营和产品人员。说明“谁能做什么、满足什么条件、结果如何”。
- 输出当前实现说明,不替代需求规格、接口文档或发布说明。
- 不在正文展示路由、控制器、表名、接口参数或源码路径,除非用户明确要求技术附录。
- 无法确认是否对外开放的功能不是已上线能力。

## 事实表达规则

先为每条重要结论判断证据类型,再选择措辞。不要将实现意图、默认值或偶发分支写成绝对产品规则。

- **硬性约束**:只有服务端校验、数据库约束或不可绕过的状态机明确阻止某操作时,才使用“仅可”“必须”“不可”等绝对措辞。
- **条件行为**:代码存在阈值、格式、开关、配置或分支时,必须写出触发条件。例如写“图片超过尺寸/体积阈值时会压缩”,不要写“上传时自动压缩”。
- **初始化不变量**:启动、认证或任务入口会自动补齐的数据(例如系统默认分类)应写为初始化机制;不要把正常用户路径不可达的缺失状态写成运营异常边界。
- **前台能力与底层可能性**:区分“当前后台没有提供某入口”与“系统绝不支持”。数据模型或内部接口存在但前台未开放时,不将其描述为正式产品能力或绝对限制。
- **大模型与外部输出**:提示词、模型建议或第三方返回不是业务保证。写“系统要求模型/尝试提取……,结果需人工复核”;只有经本系统校验并保存的字段,才能写成“系统保存/展示”。
- **默认与配置覆盖**:环境默认值、可配置项和线上实际值分别表述。存在配置入口时写“默认……,可配置为……”,不要把默认供应商或模型写成唯一实现。

## 工作流

### 1. 盘点仓库

先执行定向、只读的盘点。识别:

- 应用与端:前台、管理后台、移动端、小程序、服务端、worker。
- 入口与导航:页面注册、路由、菜单、权限守卫、功能开关。
- 业务实现:API 路由、服务/控制器、模型、迁移或 schema、事件与消息。
- 异步和外部依赖:定时任务、队列、回调、支付、物流、通知、第三方身份服务。
- 现有 README、产品文档、测试及仓库内指令。

按业务能力而非目录命名候选业务域,并列出每域涉及的角色、端、主要流程和共享能力。此阶段只输出简短盘点与候选清单,**不得开始正式产品文档**。

### 2. 确认大纲与事实边界

为候选业务域给出一级、二级大纲;标明每域的角色、端和依赖。先向用户集中提出少量阻塞问题,并等待答复,出现以下任一情况时不要继续定稿:

- 代码、测试、配置或已有文档对范围、规则或状态描述冲突。
- 页面、路由或接口可达,但无法确认是否对外开放、灰度或遗留。
- 金额、时限、权限、状态值或外部系统返回值没有足够业务语义。
- 用户指定范围与仓库实际功能不一致。

问题必须说明冲突的业务含义、可选范围与需要用户确认的决定;不要用“待确认”代替必须回答的问题。

### 3. 分域核验

对确认后的每个业务域单独阅读,按以下链路交叉验证:

`用户/后台动作 → 权限与前置条件 → 服务端校验 → 数据或状态变化 → 任务、回调或通知 → 可见结果`

- 先读该域的入口与调用链,再读服务端和数据层;不要从单个页面或 API 推断完整规则。
- 对订单、审批、售后、库存、支付等状态机,至少确认触发条件、状态出口、异常/超时路径与操作者。
- 对资金、时间、库存和权限规则,确认数值/条件来自代码或配置;配置值无业务含义时提问。
- 对图片处理、默认数据、模型识别和第三方服务,按“事实表达规则”复核每个绝对词和每个异常边界。
- 一个业务域完成后,压缩为“已确认的业务结论 + 仍需确认项”,再进入下一域;不要持续携带原始代码细节。

### 4. 跨域一致性检查

在最终成文前,单独对照共享能力:角色与数据可见性、账号/认证、支付/结算、库存、通知、状态命名、定时任务和外部回调。统一术语,消除重复,确保一个模块的结论不与另一模块冲突。

### 5. 成文

在所有阻塞问题解决后,读取 [产品文档模板](references/product-document-template.md),按项目实际能力裁剪章节并写入正式文档。

- 只写已确认或可由完整调用链验证的规则。
- 使用业务语言解释限制和结果;必要时以表格呈现角色差异、状态流转、时间窗口和规则对比。
- 省略无对应实现的章节;不把空目录、孤立接口或注释当作产品功能。
- 外部系统仅描述本项目调用所实现的行为和限制,不推测第三方承诺、后台配置或线上开通状态。

## 大型仓库策略

满足任一条件时强制按“盘点 → 大纲确认 → 分域核验 → 跨域汇总 → 成文”执行:多个应用、至少四个主要业务域、复杂异步流程,或预估文档超过约 30 页。

小型仓库可以合并盘点与大纲阶段,但仍必须先确认范围与冲突。不要一次读取全部源码后直接写长文。

## 交付前检查

- 产品范围、角色和业务域均已明确。
- 每个核心流程包含前置条件、主路径、结果和关键限制。
- 每个关键状态表包含状态、触发、操作者和异常/超时出口。
- 资金、时间、库存、权限与外部依赖的结论没有越过可验证证据。
- 所有“仅/必须/不可/自动/始终”等绝对词均有硬性约束证据;所有条件行为均写明条件。
- 大模型规则区分“提示或尝试”和“已校验、已保存的结果”;默认值与可配置值均未混写。
- 初始化机制不被误写成普通运营异常,前台能力不被误写成底层绝对限制。
- 代码/文档冲突、灰度范围和缺失业务语义均已由用户确认。
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall