| 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：项目规划与文档化技能
这个技能是做什么的
为一个项目建立一套从宏观到微观、有索引、前后逻辑通顺且互相关联的文档网络，并用它来达成两个核心目的：
- 约束 AI —— 给 AI 套上明确边界与依据，让它只在被界定的范围内行动，不自由发挥。
- 细节化功能开发 —— 把需求与实现拆到足够细的颗粒度（细到"点这个按钮的逻辑"、细到"一条 debug 语句"），让每一步都有清晰、可执行的定义。
底层原则：人和 AI 有"代沟"。人用原始口语表达，AI 理解有偏差。本技能的工作就是不断把"人话"翻译/收敛成"AI 能精确执行、可自检"的结构化文档与提示词。
五大功能
两种入口模式
启动时，先判断目标项目是新是老（看是否已有代码/文档），再进入对应模式。
调用粒度
- 引导式串行：新项目从头到尾走一遍完整流程。
- 单独调用：任意功能可独立触发，无需重走全程。例如"更新开发追踪""新增一个模块文档""只给某模块生成原型""为某任务生成提示词"。
→ 识别用户意图，直接跳到对应功能的 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]] ← 横向，可空
---
场景：……
触发：……
逻辑：……
核心纪律（执行时务必遵守）
- 原话优先：贯穿全程持续记录用户原话到
用户原话.md，不改写不总结；AI 自己的查证/推断要明确标注区分。
- PM 视角，不急于写代码：先讨论需求与产品实用性，主动质疑"这个功能用户真的会用吗"，再落文档。
- 细到独立成文：哪怕只有几十个字（如一个按钮的逻辑），也单独成文档，且带上下游标注。
- 改结构先改索引：任何模块增删改，先更新
03-索引.md，再动具体文档，保持单一事实来源。
- 功能五需前置确认：必须等用户完全确认微观文档 + 开发追踪后，才进入任务拆分、提示词与
09-codex-workflow交接包.md 生成。
- 提示词是给 AI 的源数据：贴合 AI 理解，不堆砌辞藻；
/goal 用法需带可验证完成条件，但 /goal 非必须，"直接复制发送"是基础形态。
- 交接包不是新规划：
09-codex-workflow交接包.md 只抽取本次执行所需的目标、非目标、允许/禁止范围、顺序、验收、建议 harness/sandbox/budget/checkpoint；不要在里面重写长篇 PRD。
- 默认链路：模糊项目/功能想法 → 先用 plan-docs 澄清并落
docs/changes/... → 用户确认 → 生成交接包 → 再把交接包交给 codex-workflows 执行。
