plan-docs

name	plan-docs
description	项目规划与文档化技能。当用户要为一个项目做需求梳理、产品规划、建立/完善文档体系、 把模糊想法细化成可开发的功能定义、或想约束 AI 按文档精确实现时使用。以产品经理视角 讨论需求与实用性，把需求拆解到「功能模块→子模块→按钮级交互」的递归文档树，并据此生成 高保真原型、开发追踪与可直接交给 AI 执行的微观化任务提示词。支持新项目从零引导， 也支持老项目逆向构建文档树。覆盖：项目规划、PRD、需求文档、架构文档、原型设计、 任务拆分、开发计划。Use when planning a project, writing PRDs/requirements, building a documentation tree, or turning vague ideas into granular, AI-executable specs.

plan-docs：项目规划与文档化技能

这个技能是做什么的

为一个项目建立一套从宏观到微观、有索引、前后逻辑通顺且互相关联的文档网络，并用它来达成两个核心目的：

1. 约束 AI —— 给 AI 套上明确边界与依据，让它只在被界定的范围内行动，不自由发挥。
2. 细节化功能开发 —— 把需求与实现拆到足够细的颗粒度（细到"点这个按钮的逻辑"、细到"一条 debug 语句"），让每一步都有清晰、可执行的定义。

底层原则：人和 AI 有"代沟"。人用原始口语表达，AI 理解有偏差。本技能的工作就是不断把"人话"翻译/收敛成"AI 能精确执行、可自检"的结构化文档与提示词。

五大功能

#	功能	一句话	详细 SOP
一	原话留存	逐字记录用户每句话，可溯源	references/功能1-原话留存.md
二	需求讨论 + 分层文档	PM 视角讨论实用性，产出递归模块文档树	references/功能2-需求讨论与分层文档.md
三	高保真原型	据微观文档按需生成 HTML/CSS 可交互原型	references/功能3-高保真原型.md
四	开发追踪 + 顺序	依赖推导开发顺序 + 状态看板	references/功能4-开发追踪与顺序.md
五	任务微观化 + 提示词	拆到极细，生成 AI 友好提示词（可选 /goal）	references/功能5-任务微观化与提示词.md
六	codex-workflows 交接	生成执行合同，让 codex-workflows 按文档执行	templates/09-codex-workflow交接包.md

两种入口模式

• 新项目 → 引导式：从零按流程走全程。详见 references/模式-新项目引导.md
• 老项目 → 初始化式：先读懂现有项目，逆向构建文档树。详见 references/模式-老项目初始化.md

启动时，先判断目标项目是新是老（看是否已有代码/文档），再进入对应模式。

调用粒度

• 引导式串行：新项目从头到尾走一遍完整流程。
• 单独调用：任意功能可独立触发，无需重走全程。例如"更新开发追踪""新增一个模块文档""只给某模块生成原型""为某任务生成提示词"。 → 识别用户意图，直接跳到对应功能的 SOP 执行即可。

新需求文档隔离规则（2026-07-02 起）

• 已有旧文档不迁移、不重排：如果目标项目已经有 docs/00-08*.md、docs/modules/ 等历史文档，保持原样；除非用户明确要求，否则不要把旧内容搬家。
• 以后每个新需求按日期建隔离文件夹：新需求默认写入 docs/changes/YYYY-MM-DD-需求短名/，避免继续把所有新内容追加到 00-08 总文档里。
• 总文档只做轻量索引：已有 00-08*.md 和根 03-索引.md 只追加一条短链接/状态（必要时），不写长篇需求、架构、API、测试细节。
• 隔离文件夹内放完整规划：新需求的原话、需求、架构、索引、开发追踪、API、测试、模块文档都放在该日期文件夹内。
• 执行交接包同目录生成：用户确认微观文档与开发追踪后，在同一目录补 09-codex-workflow交接包.md，作为 codex-workflows 的执行合同。
• 读取优先级：处理某个新需求时，优先读对应 docs/changes/YYYY-MM-DD-需求短名/，只在需要全局背景时再读根文档，降低长文档读取成本。

产出的文档体系

技能在目标项目根下创建/维护 docs/：

docs/
├── 用户原话.md            ← 功能一：原始输入，溯源用
├── 00-项目说明书.md       ← 项目是什么、为谁做、目标与边界
├── 01-需求文档.md         ← 产品需求总览（功能清单、优先级、用户场景）
├── 02-架构文档.md         ← 技术架构、技术栈、模块划分、数据流
├── 03-索引.md             ← 全局导航：模块树 + 横向依赖总表【单一事实来源】
├── 04-开发追踪.md         ← 开发顺序 + 状态看板（链接到各模块文档）
├── 05-术语表.md           ← 统一术语/命名
├── 06-数据字典.md         ← 字段/数据结构定义
├── 07-API文档.md          ← 接口清单与出入参
├── 08-测试用例.md         ← 验收用例（也可作 /goal 完成条件来源）
├── changes/               ← 2026-07-02 起：新需求按日期隔离
│   └── YYYY-MM-DD-需求短名/
│       ├── 用户原话.md
│       ├── 01-需求文档.md
│       ├── 02-架构文档.md
│       ├── 03-索引.md
│       ├── 04-开发追踪.md
│       ├── 07-API文档.md
│       ├── 08-测试用例.md
│       ├── 09-codex-workflow交接包.md
│       └── modules/
└── modules/               ← 功能二：微观实现文档（可无限递归）
    └── 模块A/
        ├── _A.md
        ├── 子模块A1/
        │   ├── _A1.md
        │   └── 按钮X.md   ← 最小叶子文档（场景/触发/逻辑/上级/依赖）
        └── ...

各文档的填写模板见 templates/。

关联关系规范（C 方案：中心索引 + 文档内上下游）

这是整套文档"前后逻辑通顺且关联"的核心机制：

• 纵向（包含/父子）：模块 → 子模块 → 子子模块……可无限递归。这棵树本身就是开发关联关系。
• 横向（依赖/调用）：跨树枝的触发/调用（如"按钮X"触发"模块B 的某流程"）。
• 中心索引：03-索引.md 是单一事实来源，用缩进画全局模块树 + 横向依赖总表，改结构以它为准。
• 文档内上下游：每个文档头部统一标注 上级 / 下级 / 依赖，逐层可追。

微观文档头部模板：

上级：[[_A1]]
下级：[[子模块A1a]]、[[按钮X]]
依赖：[[模块B-流程Y]]   ← 横向，可空
---
场景：……
触发：……
逻辑：……

核心纪律（执行时务必遵守）

1. 原话优先：贯穿全程持续记录用户原话到 用户原话.md，不改写不总结；AI 自己的查证/推断要明确标注区分。
2. PM 视角，不急于写代码：先讨论需求与产品实用性，主动质疑"这个功能用户真的会用吗"，再落文档。
3. 细到独立成文：哪怕只有几十个字（如一个按钮的逻辑），也单独成文档，且带上下游标注。
4. 改结构先改索引：任何模块增删改，先更新 03-索引.md，再动具体文档，保持单一事实来源。
5. 功能五需前置确认：必须等用户完全确认微观文档 + 开发追踪后，才进入任务拆分、提示词与 09-codex-workflow交接包.md 生成。
6. 提示词是给 AI 的源数据：贴合 AI 理解，不堆砌辞藻；/goal 用法需带可验证完成条件，但 /goal 非必须，"直接复制发送"是基础形态。
7. 交接包不是新规划：09-codex-workflow交接包.md 只抽取本次执行所需的目标、非目标、允许/禁止范围、顺序、验收、建议 harness/sandbox/budget/checkpoint；不要在里面重写长篇 PRD。
8. 默认链路：模糊项目/功能想法 → 先用 plan-docs 澄清并落 docs/changes/... → 用户确认 → 生成交接包 → 再把交接包交给 codex-workflows 执行。