manage-prd-docs
Skill0 starsChanged 4 days agoMITView on GitHub
Automatically manage product requirements across current decisions in docs/PRD.md and docs/prd/, mature future plans under docs/plans/, and active implementation under docs/work/. Use whenever the conversation discusses, clarifies, versions, plans, implements, completes, splits, or migrates a product requirement or PRD, including v1/v2/v3 roadmaps, module PRDs, 讨论需求、未来版本、实现需求、收口需求. Enter implicitly, materialize mature requirements in the correct lifecycle layer, maintain docs/index.md navigation, activate plans without duplicate PRDs, and automatically merge and clean up verified completed work.
In this repository17 other files it gives its agents.
- AGENTS.mdAGENTS.md
- apply-yliu-frontend-practicesSkill
- build-mcp-appSkill
- build-mcpbSkill
- build-mcp-serverSkill
- chinese-article-writingSkill
- claude-md-improverSkill
- file-line-auditSkill
- frontend-designSkill
- git-step-commitSkill
- integrate-ai-i18nSkill
- modernize-ecmascriptSkill
- publish-npm-packagesSkill
- skill-creatorSkill
- skill-developmentSkill
- use-ai-i18n-mcpSkill
- use-lociSkill
The file
Files
Manage PRD Docs
围绕产品需求进行讨论,把已生效、未来已成型和正在实施的产品决策放在不同生命周期层,并保持单一权威来源。
自动推进需求生命周期
- 检测到用户在讨论、澄清、变更、计划、实现或完成产品需求时,立即进入本工作流,不要等待用户说“讨论需求”“落盘”或“合并 PRD”。
- 先判断需求是否成型:目标、范围、核心需求和可验证的验收标准已经明确,且不存在会改变产品或实施方向的关键未决项。
- 需求未成型时继续讨论,只询问对方向有实质影响的问题;不为低风险细节阻塞推进。
- 需求成型后立即按状态落盘:已生效的行为更新现行 PRD;未开始实施的未来需求进入
docs/plans/;已开始或本轮同时要求实现的需求进入docs/work/。不再请求额外落盘授权。 - 只写入已经明确的当前结论;尚在比较的方案、随口设想和无法判断是否确认的内容暂不写入。
- 实现过程中持续同步 PRD 和 Todo。当本轮需求的实现、验证和必要文档全部完成时,主动收口,不等待用户再说“合并 PRD”。
- 把纯讨论或 PRD 编写任务的结束与实现完成区分开:未开始的成型需求保留在
docs/plans/;部分实现、验证失败、存在阻塞或仍有未决项时保留在docs/work/。 - 只自动删除本轮已完成需求对应的精确工作目录。迁移或删除旧 Phase、历史 PRD 和其他非本轮临时文档前,仍取得用户明确授权。
识别文档约定
- 定位仓库根目录,先读取适用的
AGENTS.md和仓库级说明。 - 默认使用根目录下的
docs/,优先遵循仓库已有的文档入口和命名约定。 - 如果存在
docs/index.md,先按索引定位现行 PRD、未来计划、进行中需求和其他权威文档。 - 读取相关 PRD、上下游计划、Todo、用户文档、README 和代码契约,避免建立重复或冲突的权威来源。
- 增量修改并保留无关的人工内容。
使用三层文档
把文档分成现行、未来计划和进行中三层:
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 只表达正在实施的工作。
激活未来计划
当用户开始实施某个计划时:
- 将对应目录从
docs/plans/<requirement>/移到docs/work/<requirement>/,不在两处保留 PRD 副本。 - 核对计划的基线和依赖仍然有效;如果上游尚未完成且会阻塞实现,保留在
plans/并说明阻塞。 - 把 PRD 更新为当前可实施的完整范围,并创建
TODO.md。 - 在同一次变更中更新
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 全部完成,且没有阻塞项、失败验证或会影响交付的未决问题。
满足条件后立即执行:
- 对照进行中 PRD、实现、测试和用户文档,确认没有未处理或仍未决的内容。
- 把仍长期成立的行为、原因和边界合并到
docs/PRD.md或对应模块 PRD;把跨模块决策保留在根 PRD。 - 把用户 API、配置、接入方式和操作说明同步到其权威文档。
- 把尚未完成但仍有效的内容按状态分流:继续实施的移入新
work/,推迟但已成型的移入plans/,不要无声丢弃。 - 检查所有依赖该需求的未来计划;将已完成的上游基线改为当前 PRD,并同步依赖、增量内容和验收标准。
- 更新
docs/index.md和所有受影响链接,不因当前只剩单一 PRD 就删除已建立的索引。 - 删除已完成需求的整个
docs/work/<requirement>/,不保留验收快照、完成 Todo 或临时调研档案。 - 在最终回复中告知用户已自动合并的长期决策、已重审的下游计划和已删除的工作目录。
任一条件不满足时不要假定已完成,保留工作目录,更新 Todo 为真实状态,并说明剩余工作或阻塞。如果一项尚在实现的行为是否属于稳定承诺会改变合并结果,先请用户明确。
用户明确取消未来计划时,先检查并更新所有下游依赖,再更新索引并删除对应 docs/plans/<requirement>/。不仅因为计划长期未开始就自动删除。
迁移旧 Phase 文档
取得用户明确授权后再迁移已有的 phase-*、历史 PRD 或永久 Todo:
- 把当前仍成立的行为、原因和边界合并到现行 PRD。
- 把已成型但未开始的有效需求移到
docs/plans/<requirement>/,把正在实施的移到docs/work/<requirement>/。 - 把 API、配置和使用细节移动到其权威用户文档,并在 PRD 中保留链接。
- 删除已完成任务、验收快照、临时 Spike、过时需求和被替代方案。
- 对仍有实现但产品承诺不清的历史行为逐项请求决策,不得无声丢弃。
- 确认索引、模块导航、计划依赖和链接正确后,删除已被吸收的旧阶段目录。
审计并按语义拆分 PRD
在主题具有独立产品边界、可独立演进或验收、拥有稳定术语、修改时通常不需要理解其他主题,或已形成明确跨模块关系时,即使不足 400 行也按模块拆分。不为拆文件制造没有语义边界的小模块。
把每个 PRD 正文文件的 400 个物理行作为必须审计的软上限,不作为拆分的唯一触发条件:
- 修改后统计相关 PRD 的物理行数。
- 达到或超过 400 行时,使用
$file-line-audit,阈值设为400,并扫描:docs/PRD.mddocs/prd/**/*.mddocs/plans/**/PRD.mddocs/plans/**/prd/**/*.mddocs/work/**/PRD.mddocs/work/**/prd/**/*.md
- 先删除重复、过时和过细的实现过程。
- 清理后仍超过 400 行时,按领域或完整主题拆分,不在固定行号机械截断。
- 现行 PRD 的模块文件放在
docs/prd/<topic>.md,根docs/PRD.md保留产品地图和跨主题决策。 - 未来计划和进行中需求的主题文件分别放在其
prd/<topic>.md,根PRD.md保留需求概览和内部导航。 - 不创建
PRD-part-1.md、requirements-part-2.md等按序号切分的文件。 - 再次使用
$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 行规则。
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

