Manage Prd Docs

Manage PRD Docs

围绕产品需求进行讨论，把已生效、未来已成型和正在实施的产品决策放在不同生命周期层，并保持单一权威来源。

自动推进需求生命周期

• 检测到用户在讨论、澄清、变更、计划、实现或完成产品需求时，立即进入本工作流，不要等待用户说“讨论需求”“落盘”或“合并 PRD”。
• 先判断需求是否成型：目标、范围、核心需求和可验证的验收标准已经明确，且不存在会改变产品或实施方向的关键未决项。
• 需求未成型时继续讨论，只询问对方向有实质影响的问题；不为低风险细节阻塞推进。
• 需求成型后立即按状态落盘：已生效的行为更新现行 PRD；未开始实施的未来需求进入 docs/plans/；已开始或本轮同时要求实现的需求进入 docs/work/。不再请求额外落盘授权。
• 只写入已经明确的当前结论；尚在比较的方案、随口设想和无法判断是否确认的内容暂不写入。
• 实现过程中持续同步 PRD 和 Todo。当本轮需求的实现、验证和必要文档全部完成时，主动收口，不等待用户再说“合并 PRD”。
• 把纯讨论或 PRD 编写任务的结束与实现完成区分开：未开始的成型需求保留在 docs/plans/；部分实现、验证失败、存在阻塞或仍有未决项时保留在 docs/work/。
• 只自动删除本轮已完成需求对应的精确工作目录。迁移或删除旧 Phase、历史 PRD 和其他非本轮临时文档前，仍取得用户明确授权。

识别文档约定

1. 定位仓库根目录，先读取适用的 AGENTS.md 和仓库级说明。
2. 默认使用根目录下的 docs/，优先遵循仓库已有的文档入口和命名约定。
3. 如果存在 docs/index.md，先按索引定位现行 PRD、未来计划、进行中需求和其他权威文档。
4. 读取相关 PRD、上下游计划、Todo、用户文档、README 和代码契约，避免建立重复或冲突的权威来源。
5. 增量修改并保留无关的人工内容。

使用三层文档

把文档分成现行、未来计划和进行中三层：

docs/
├── index.md                 # 稳定的文档类别与生命周期导航
├── PRD.md                   # 现行产品决策与跨主题边界
├── prd/                     # 按稳定产品模块拆分的现行 PRD
│   └── <topic>.md
├── plans/                   # 已成型但尚未开始的未来需求
│   └── <requirement>/
│       ├── PRD.md
│       └── prd/             # 计划 PRD 需按主题拆分时使用
│           └── <topic>.md
└── work/                    # 仅在存在进行中需求时使用
    └── <feature-name>/
        ├── PRD.md
        ├── TODO.md
        └── prd/             # 当前需求 PRD 过长时按主题拆分
            └── <topic>.md

• 不创建空目录。
• 把已经生效的行为或稳定承诺写入现行 PRD，把未开始的成型需求写入 docs/plans/，把正在实施的需求写入 docs/work/。
• 全新产品尚未形成现行能力时，未开始实施就使用 docs/plans/initial-release/，已开始实施就使用 docs/work/initial-release/，不要为了结构完整创建空的 docs/PRD.md。
• 版本对用户或产品确实有意义时，允许在 plans/ 和 work/ 使用 <requirement>-v2 等名称；完成后不把版本目录保留为永久历史档案。
• 只有能独立排期、验收、延期或取消的 v2、v3 才分开维护；仅为开发顺序服务的 Phase 留在同一进行中 PRD 和 Todo 中。
• 允许在进行中 PRD 或 Todo 内规划实施阶段，但完成后不保留阶段档案。
• 不强制创建发布文档、用户文档或其他项目特有文件；已有时维护链接和一致性。

维护现行 PRD

把 docs/PRD.md 视为产品当前有效决策的唯一入口。在根 PRD 保留产品级范围、跨模块行为、统一术语、全局边界和模块导航；把稳定产品模块的详细当前决策放在 docs/prd/<module>.md。

每个主题只保留：

## 翻译存储与人工覆盖

- 当前决策：……
- 为什么：……
- 边界 / 非目标：……
- 权威入口：链接到用户文档、README 或源码契约。

• 直接修改被扩展或替代的旧结论，不追加 Phase 让读者自行判断优先级。
• 不在根 PRD 枚举未来计划、进行中需求或其他文档类别；这些属于 docs/index.md 的导航职责。
• 根 PRD 只链接模块 PRD 并保留跨模块决策，不在根文件和模块文件重复同一决策。
• 保留仍成立的用户行为、产品承诺、设计原因、边界和非目标。
• 移除已失效需求、已完成 Todo、验收数量、临时 Spike 和被替代方案；使用 Git、测试和代码追溯历史。
• 不重复 API 参数表、配置步骤或实现细节；链接到对应的用户文档、README 或源码契约。
• 不强制维护创建日期和更新日期；需要时间线时使用 Git 历史或仓库已有约定。

维护未来计划

为已经成型并确认保留、但尚未开始实施的需求创建 docs/plans/<requirement>/PRD.md，使用稳定的英文 slug。不为随口设想、未决方案或不确定是否保留的内容创建计划。

在计划 PRD 中至少写明：

# 需求名称 v2

- 基线：当前 PRD 或另一未来计划
- 依赖：无或具体计划链接

## 背景与目标

## 新增、变更与移除

## 范围与非目标

## 验收标准

## 对后续计划的影响

• 只写基于指定基线的增量需求，不复制完整现行 PRD。
• v3 依赖 v2 时，链接 v2 计划并只写基于 v2 的增量。
• 上游计划发生变更、取消或完成时，主动检查并更新所有下游计划的基线、依赖和验收标准。
• 计划尚未开始时不创建 TODO.md；Todo 只表达正在实施的工作。

激活未来计划

当用户开始实施某个计划时：

1. 将对应目录从 docs/plans/<requirement>/ 移到 docs/work/<requirement>/，不在两处保留 PRD 副本。
2. 核对计划的基线和依赖仍然有效；如果上游尚未完成且会阻塞实现，保留在 plans/ 并说明阻塞。
3. 把 PRD 更新为当前可实施的完整范围，并创建 TODO.md。
4. 在同一次变更中更新 docs/index.md 及所有指向旧路径的链接。

如果用户在需求成型的同一轮就要求实现，直接创建 docs/work/<requirement>/，不先创建再移动 plans/ 中间文档。

维护进行中需求

为已经开始实施的需求维护 docs/work/<requirement>/，使用稳定的英文 slug 命名。如果需求来自 plans/，沿用原 slug 和 PRD，不另建重复入口。

在 PRD.md 中写明：

# 功能名称

## 背景与目标

## 范围与非目标

## 已确认需求与决策

## 验收标准

## 文档与兼容性影响

• 只写可验证的已确认内容，不写 TBD、猜测或未定方案。
• 使用 TODO.md 维护当前实施任务，以 - [ ] 和 - [x] 表示状态，并按合理实施顺序排列。
• 开始实现时不另等待用户下达文档维护指令；每完成一项就同步勾选 Todo，需求改变时同步修改 PRD。
• 需求变化时直接把 PRD 和 Todo 更新为当前有效内容，不用删除线维护文档内变更日志。
• 开发期间可以保留已完成任务用于观察进度；需求收口后删除整个工作目录。
• 如果现行产品决策并未改变，不要把施工过程提前写入总 PRD。

维护稳定索引

把 docs/index.md 作为文档类别和生命周期的稳定地图，不作为另一份 PRD；把 docs/PRD.md 作为现行产品模块的地图。

• 存在多个文档类别、未来计划、进行中需求或其他文档时创建 docs/index.md。一旦建立就持续维护，不因临时只剩单一 PRD 自动删除；只在仓库约定改变或用户明确要求时删除。
• 按需要提供“现行产品决策”“未来计划”“进行中的需求”和“其他文档”分类。
• 现行决策只链接根 docs/PRD.md，不在索引里再枚举 docs/prd/ 的各产品模块。
• 只列名称、链接和理解顺序所必需的基线或依赖提示；不复制 PRD 摘要、不记录历史 Phase。
• 新增、激活、收口、取消、删除、改名或移动文档时，在同一次变更中更新索引并确认链接指向存在的文件。

推荐结构：

# 文档索引

## 现行产品决策

- [产品 PRD](./PRD.md)

## 未来计划

- [团队权限 v2](./plans/team-permissions-v2/PRD.md)

## 进行中的需求

- [计费重构](./work/billing-refactor/PRD.md)

## 其他文档

- [发布流程](./release.md)

收口完成的需求

在每次实现任务结束前主动判断对应需求是否已经完成，不等待用户确认或发出收口指令。Todo 全部勾选是必要证据，但不是唯一证据。只有同时满足以下条件时自动收口：

• 已完成进行中 PRD 定义的全部范围，没有被无声遗漏的有效需求。
• 相关测试、检查或其他合理验证已通过。
• 需要同步的用户文档、API、配置或操作说明已经更新。
• Todo 全部完成，且没有阻塞项、失败验证或会影响交付的未决问题。

满足条件后立即执行：

1. 对照进行中 PRD、实现、测试和用户文档，确认没有未处理或仍未决的内容。
2. 把仍长期成立的行为、原因和边界合并到 docs/PRD.md 或对应模块 PRD；把跨模块决策保留在根 PRD。
3. 把用户 API、配置、接入方式和操作说明同步到其权威文档。
4. 把尚未完成但仍有效的内容按状态分流：继续实施的移入新 work/，推迟但已成型的移入 plans/，不要无声丢弃。
5. 检查所有依赖该需求的未来计划；将已完成的上游基线改为当前 PRD，并同步依赖、增量内容和验收标准。
6. 更新 docs/index.md 和所有受影响链接，不因当前只剩单一 PRD 就删除已建立的索引。
7. 删除已完成需求的整个 docs/work/<requirement>/，不保留验收快照、完成 Todo 或临时调研档案。
8. 在最终回复中告知用户已自动合并的长期决策、已重审的下游计划和已删除的工作目录。

任一条件不满足时不要假定已完成，保留工作目录，更新 Todo 为真实状态，并说明剩余工作或阻塞。如果一项尚在实现的行为是否属于稳定承诺会改变合并结果，先请用户明确。

用户明确取消未来计划时，先检查并更新所有下游依赖，再更新索引并删除对应 docs/plans/<requirement>/。不仅因为计划长期未开始就自动删除。

迁移旧 Phase 文档

取得用户明确授权后再迁移已有的 phase-*、历史 PRD 或永久 Todo：

1. 把当前仍成立的行为、原因和边界合并到现行 PRD。
2. 把已成型但未开始的有效需求移到 docs/plans/<requirement>/，把正在实施的移到 docs/work/<requirement>/。
3. 把 API、配置和使用细节移动到其权威用户文档，并在 PRD 中保留链接。
4. 删除已完成任务、验收快照、临时 Spike、过时需求和被替代方案。
5. 对仍有实现但产品承诺不清的历史行为逐项请求决策，不得无声丢弃。
6. 确认索引、模块导航、计划依赖和链接正确后，删除已被吸收的旧阶段目录。

审计并按语义拆分 PRD

在主题具有独立产品边界、可独立演进或验收、拥有稳定术语、修改时通常不需要理解其他主题，或已形成明确跨模块关系时，即使不足 400 行也按模块拆分。不为拆文件制造没有语义边界的小模块。

把每个 PRD 正文文件的 400 个物理行作为必须审计的软上限，不作为拆分的唯一触发条件：

1. 修改后统计相关 PRD 的物理行数。
2. 达到或超过 400 行时，使用 $file-line-audit，阈值设为 400，并扫描：
   • docs/PRD.md
   • docs/prd/**/*.md
   • docs/plans/**/PRD.md
   • docs/plans/**/prd/**/*.md
   • docs/work/**/PRD.md
   • docs/work/**/prd/**/*.md
3. 先删除重复、过时和过细的实现过程。
4. 清理后仍超过 400 行时，按领域或完整主题拆分，不在固定行号机械截断。
5. 现行 PRD 的模块文件放在 docs/prd/<topic>.md，根 docs/PRD.md 保留产品地图和跨主题决策。
6. 未来计划和进行中需求的主题文件分别放在其 prd/<topic>.md，根 PRD.md 保留需求概览和内部导航。
7. 不创建 PRD-part-1.md、requirements-part-2.md 等按序号切分的文件。
8. 再次使用 $file-line-audit 确认所有 PRD 正文文件均未超过上限。

不要扫描或拆分 TODO.md 和纯导航用途的 index.md。

完成检查

• 已在需求讨论开始时自动进入工作流，没有要求用户记住阶段口令。
• 只写入已明确且成型的需求，并在成型后按已生效、未来计划或正在实施自动落到正确层。
• docs/PRD.md 只表达当前有效的产品决策，并保留跨模块决策和模块导航。
• docs/plans/ 只包含已成型但尚未开始的未来需求，每个计划的基线和依赖有效。
• docs/work/ 只包含真正进行中的需求。
• 计划激活时已从 plans/ 移到 work/，没有重复 PRD 权威来源。
• 已完成实现的需求已自动回填长期决策，并删除对应临时工作目录。
• 纯讨论、部分实现、验证失败或仍有阻塞的需求没有被过早收口。
• API、配置和使用细节位于其权威文档，PRD 没有重复维护。
• docs/index.md 反映现行、未来计划、进行中和其他文档，没有失效链接，也没有重复枚举现行产品模块。
• 稳定产品主题已按语义边界拆分，400 行只作为必须审计的软上限。
• 旧 Phase 文档没有未经判断地被拼接或删除。
• 所有 PRD 正文文件符合 400 行规则。