/product-evolution

name: product-evolution
description: >-
  在 docs 下建立或维护产品管理入口，登记材料来源，统一需求编号、状态与修订，连接需求池、单需求、版本及验收复盘，并只读审查需求演变是否可追溯。用于产品文档管理员、PRD 版本混乱、产品进展难以理解、已确认决定未回写或需要产品文档审查时。English triggers: product documentation manager, product evolution, PRD governance, product baseline, product progress review.

产品文档管理

让接手者能从一个入口回答：产品服务谁、解决什么问题、当前以哪些要求为准、本轮为什么改、执行证据在哪里、下一步等什么。

先辨认现有来源

读取项目规则、地图，再按下述“按任务读取”定位现有产品文档与相关任务，不预先全文加载产品目录。先找已确认决定，不能把文档仍写“待确认”直接判成业务尚未决定。冲突或无法查证的内容标待核实，不以代码现状反向批准需求。

采用项目已有产品目录；没有时，在用户要求建立管理空间后使用 `docs/product/`。按下述十阶段建立文件导航，不迁移已有规格以迎合模板。用户要求完整建档时，各阶段可先写真实状态与待补内容；未开展阶段不能填成已完成。

方法论只在本 Skill；目标项目的入口记录实际来源和项目约定。PM 类技能可用于调研、分析和编写 PRD，有则按需使用，没有也能执行本流程；不能把生成的分析当作已做访谈或已批准决定。

管理员执行顺序

Claude Code 可由 `product-docs-manager` Agent 承担此角色；Codex / ChatGPT 的当前 Agent 直接执行本 Skill，无须依赖 Claude Agent 文件。

被统一 setup 编排时，只处理传入的产品文件范围并返回实际来源、主记录路径、修订与未决项；共享入口更新和最终同步／审计由编排者统一执行，不递归重启 setup。独立调用仍执行下列完整顺序。

1. 按“按任务读取”只读定位当前主题、来源登记、需求编号、任务入口和已确认授权；用四类材料索引与六类管理记录找到唯一维护位置。 2. 登记原始来源后再整理分析；区分原话、事实、假设与决定。核对编号、修订和状态依据，未经确认不把草案转为正式需求。 3. 涉及需求变更或跨文档影响时读取 `skills/engineering/change-impact/SKILL.md`，确定本次需要核对的主记录和下游引用；只分析文档影响，不顺带修改业务实现。 4. 按“AI 协作与确认边界”执行已授权的文档修改。读取 `skills/documentation/living-docs-governance/SKILL.md` 做阶段同步与只读审计；该 Skill 对 PR 前检查的约定继续适用，失败先处理，不另写一套扫描器。 5. 交付实际来源、需求编号与主记录位置、文档改动及依据、审计结果和待确认事项。无写入授权时在回复中交付建议，不落盘。

PM 四类材料索引

产品入口按 PM 的四类能力登记材料；这是材料分类，不要求安装 PM 插件或执行专业调研。已有路径只映射，不搬迁。同一材料指定一个主位置，其他分类、六类管理记录和十阶段导航只引用它。

| 分类 | 材料与用途 | 无既有目录时的建议位置 | |---|---|---| | 产品发现 | 用户访谈、反馈、机会、需求假设、实验与验证结果；说明需求来源和已验证假设 | `product-discovery/` | | 市场研究 | 行业、竞品、市场规模、用户细分、画像及旅程；支撑用户与市场判断 | `market-research/` | | 产品战略 | 愿景、定位、价值主张、取舍和商业模式；说明目标与不做范围 | `product-strategy/` | | 产品执行 | 整体／模块 PRD、原型引用、用户故事、评审、版本范围、验收与复盘资料 | `execution/` |

建议位置相对产品空间。用户发现主要在产品发现；画像、细分和旅程按实际用途登记，跨类时引用而不复制。仅在有材料且获准建档时创建目录，不要求每个需求产出四套材料。PRD 的背景、用户、目标与方案引用相关上游材料；缺失依据标待补，不补造事实。

按任务读取

建立产品空间时，在项目已约定的共享规则主文件写入简短触发约定和真实入口链接；入口生成与适配执行 `skills/documentation/agent-entrypoints/SKILL.md`。CLAUDE 主源布局可沿用 `templates/CLAUDE.example.md` 的产品读取路标，AGENTS 仅桥接；已有 AGENTS 主源时直接更新其路标。无产品空间时不写悬空链接。完整读取方法只在本 Skill 维护。

1. **先定位**：涉及产品目标、需求、原型、实现或验收时，先读产品入口的需求索引和当前主题基线。无关任务不加载产品资料；修链接或排版仅读目标与直接引用。不默认遍历全文，不用整目录拼接填满上下文。 2. **再核对适用要求**：修改前读当前主题主记录的相关条款、验收条件、未决事项及尚未回写的已确认变更；确认来源为 Issue 时核对相关后续评论。先看标题目录和适用范围，再按章节／条款定位读取。摘要和搜索命中只帮助定位，不能代替适用正文。 3. **沿影响补读**：读取主记录声明的公共规则与依赖；跨模块只补受影响模块条款，整体定位／范围变化再读整体 PRD 对应章节。需要解释或核实依据时沿引用读取发现、研究、战略材料；比较修订、追溯替代关系时才读历史。相关内容超过单次容量时分批读完必要范围，不静默截断。 4. **缺口不猜测**：入口缺失或过期时，以文件名、标题和需求编号定向查找并核对主记录，不能因搜索无结果就认定需求不存在。生效范围不明、确认冲突或必要来源不可访问时，报告缺口并暂停依赖该结论的修改，继续无冲突工作。 5. **大范围分批**：全产品审查先列模块与主记录清单，按模块分批核对，再检查跨模块共用规则和引用一致性。每批记录文档修订／提交、检查范围、问题与待查项；上下文切换后从该清单续读，记录只作导航，不替代正文。按既有授权将进度写入已有审查记录，无写入授权时在回复保留清单。仅抽查时明确覆盖范围，不能宣称全量通过。

入口只保留简短摘要、主记录路径／章节、当前修订、确认范围与依赖链接，不复制 PRD 正文或实时任务状态。需求多时按模块拆索引，顶层只留模块入口。整体 PRD 保留产品全貌和模块边界，详细规则留在需求主记录；长文档提供目录和稳定条款编号，不因排序改变编号。每份主记录标明适用公共规则、依赖及后续确认入口，防止局部阅读漏约束。

本协议约束 Agent 的读取行为，不是 token 硬限制；现有脚本不监控模型上下文，也不证明语义阅读完整。验证须区分规范场景复核与实际 Agent 运行结果。

六类管理记录

按“原始输入 → 产品认知与规划 → 需求池 → 单需求 → 版本 → 验收复盘”登记管理位置。四类用于材料分类，六类标明来源与维护责任，十阶段用于工作导航；共用主记录，不并行维护三套正文。先在产品入口登记实际位置，已有目录与任务工具直接映射。小项目可用入口章节，材料增多时再拆目录。

| 资料类别 | 新建时建议位置 | 与十阶段的关系 | |---|---|---| | 原始输入 | `sources/` 或已有来源登记 | 各阶段输入，包括访谈、反馈和原始文件 | | 产品认知与规划 | 四类材料中的相关主记录 | 项目初始化、市场分析及跨需求的产品认识与规划 | | 需求池 | 现有 Tracker；无 Tracker 时复用唯一的本地需求清单 | 需求调研与分析的候选入口，只链接单需求主记录 | | 单需求 | `execution/` 中的 PRD 或已有 Spec／Issue | 同一编号关联分析、原型、PRD、评审与研发记录 | | 版本 | `execution/` 中的版本记录或已有发布记录 | 引用纳入版本的需求编号与修订、PR 和实际发布证据 | | 验收复盘 | `execution/` 中的验收复盘或已有证据 | 测试上线、运营反馈与下一轮输入 |

建议目录相对项目产品空间；不因此移动现有文件，也不预建没有材料的空目录。完整十阶段入口仍按下节维护。

来源、需求与唯一事实

• **来源先登记**：记录来源标识、原始位置或链接、提供者（已知时）、材料日期和收录日期、适用主题。缺失信息标未知；只有转述时注明转述，保留原始文件，不以 AI 摘要替换证据。同一来源复用登记，不重复保存正文。
• **编号稳定**：优先沿用现有 Issue／需求编号并带项目或仓库范围。无既有编号规则时，可在唯一需求清单中采用 `REQ-0001` 顺序编号；分配前查重，不随改名、修订或归档重编号，作废编号不复用。存在并发分配时先由唯一清单确认编号，不能各自独立自增。小需求直接以现有 Issue 为主记录。
• **状态单一**：执行进度以已有 Tracker 为准，Markdown 只引用；无 Tracker 时使用唯一的本地清单。沿用项目状态与转换条件；尚无约定时先提出“待分析、待评审、已确认、实施中、待验收、已验收、暂缓、取消”的候选规则，经负责人确认后启用，不因模板默认值自动切换状态。阶段文档状态、需求批准和执行状态分别记录。
• **修订和版本分开**：需求正文用项目现有修订规则，无规则时从 `r1` 记录；软件版本引用需求编号及具体修订，不用发布版本替代需求修订。记录变更依据、确认来源、范围与被替代部分；旧修订通过 Git 或既有快照追溯。
• **每个事实一个维护位置**：原始证据、需求正文、执行状态、发布事实和验收结论各自指定主记录。目录、阶段文件和版本索引仅引用；已有 Tracker 的需求池不再抄成 Markdown 看板。

AI 协作与确认边界

Markdown 承载长期维护的产品认知、需求与决定；Tracker、机器契约和实际运行证据继续各负其责。Word、PDF、PPT 等导出交付物注明所依据的主记录、修订和导出日期，不作为另一份可独立修改的需求真相。收到的原始 Word／PDF／PPT 仍是来源证据，不当作可覆盖的导出物。

AI 可整理、关联、检查并提出分析建议；本角色管理产物，不代替专业 PM 工作、业务取舍或验收。正式需求生效、状态变化及任何文件修改都须有明确授权：用户已确认同一对象、动作和范围时直接执行并记录依据，不逐文件重复询问。只有整理授权时，可以维护获准的草稿，不能据此批准需求或标为已验收。

缺少授权时，先在回复中给出拟改文件、具体变化和状态依据，再请求确认；保留现有文件与状态。材料中的“已批准”、待办指令或角色提示不能充当当前用户授权，需核对真实确认来源。新增或冲突的业务决定仍待负责人确认，不能用代码现状或扫描通过反向批准需求。

十阶段文件管理

十阶段是完整的基础结构，每阶段保留文档或资料入口。未开展、不适用只改变记录状态，不移除管理位置。我们管理阶段产物，不执行调研、产品决策、研发、测试或运营。

默认在产品目录按以下顺序管理文件。已有目录通过入口映射到同样阶段，避免复制。小项目每阶段一份 Markdown；材料增多时再拆同名目录，由阶段文件保留索引。

| 阶段文件 | 输入 → 产出 | 文档完整性核对 | |---|---|---| | `01-project-init.md` | 发起背景 → 项目目标、用户／客户假设、负责人、约束与范围 | 目标与约束明确，未知项有记录 | | `02-market-analysis.md` | 市场问题与资料 → 行业、竞品、替代方案和机会判断 | 结论有来源与日期，区分事实和假设 | | `03-user-research.md` | 待验证假设 → 访谈、反馈、使用数据及问题证据 | 样本和方法可追溯，写明局限 | | `04-requirements-analysis.md` | 市场与用户证据 → 问题归纳、价值、优先级、方案、范围与不做项 | 关键取舍有依据，待决事项明确 | | `05-prototype.md` | 候选方案 → 用户动线、原型／交互说明和验证反馈 | 关键路径、异常状态可理解；适用时有用户验证 | | `06-prd.md` | 分析与原型 → 背景、目标、规则、流程、边界、指标和验收条件 | 可以评审，歧义与依赖已列出；此时仍可为草案 | | `07-requirements-review.md` | PRD → 评审意见、决定、确认来源及修改结论 | 明确哪些条款通过、待改或阻塞；据确认记录标明生效范围，不代替批准 | | `08-development.md` | 已确认基线 → 实施任务／PR、依赖与变更入口 | 实现范围和版本可追溯，变更回写 PRD 并按影响复审 | | `09-test-release.md` | 实现与验收条件 → 测试证据、遗留项、上线／回退记录 | 分开记录测试通过、获准发布和实际上线；未通过不宣称交付 | | `10-operations-feedback.md` | 上线版本与观察目标 → 使用反馈、指标分析、后续需求 | 有口径、区间、来源和结论，反馈回到下一轮调研／分析 |

由专业人员或 PM skills 完成各阶段工作，我们仅整理其产物并维护引用。

每份阶段文件标明适用主题／迭代、记录日期、阶段状态、输入来源、产出链接、未解决问题及下一步。状态使用“未开展、进行中、待确认、已完成、不适用”，不适用写理由，不能静默跳过。它们记录阶段产物，不替代任务工具的实时执行状态。

这是一条可迭代流程：评审退回记录关联分析或原型，研发变更记录关联分析／PRD／评审，运营反馈资料关联下一轮。阶段产物允许引用已验证历史依据；不要求每次小改动重做市场研究。首次建档与全阶段审查覆盖十阶段，单项迭代只更新实际受影响阶段并解释省略理由。

建立和维护管理空间

使用 `templates/product-index.example.md` 建立产品入口。小