菜单
【已于 2026-07-27 退役，请勿触发本 skill】全部能力已并入 issue-pool——框架计划七步流程见 issue-pool/references/plan-writing.md。任何"写计划报告 / 框架计划 / 项目计划 / v1.0 计划 / 版本路线 / 阶段方案"的需求，一律改用 issue-pool。本目录仅作历史存档保留，不再推送到任何目标。
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/yunshu0909/yunshu_skillshub --skill plan-report命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
| name | plan-report |
| description | 【已于 2026-07-27 退役，请勿触发本 skill】全部能力已并入 issue-pool——框架计划七步流程见 issue-pool/references/plan-writing.md。任何"写计划报告 / 框架计划 / 项目计划 / v1.0 计划 / 版本路线 / 阶段方案"的需求，一律改用 issue-pool。本目录仅作历史存档保留，不再推送到任何目标。 |
帮助用户产出一份框架计划报告——位于"项目章程"和"详细设计"之间的文档类型。
它回答:为什么做 / 做到什么程度算完 / 谁用它 / 不做什么 / 分几步走 / 每步停下时业务能问出什么。
它不回答:字段、接口、技术栈、目录命名、cron 表达式——这些是后续"详细设计文档"的事。
核心价值:让计划报告变成读者能看懂的故事,而不是作者给自己确认范围的工作清单。通过 7 步引导跟用户对齐方向、骨架、内容,最后才落盘。
不要凭空推演。先把现状摸清楚——能跑的先跑、能读的代码先读、已知约束先列。
信号:能回答"现状是什么 / 能拿到什么 / 有哪些硬约束 / 谁会消费这份文档"。这四个问题答不上来,就不要进 Stage 2。
拿到诉求第一件事不是动笔,是问自己:这是哪一类文档?
| 类型 | 核心问题 | 写法特征 |
|---|---|---|
| 项目章程 | 为什么立项 | 偏战略,1-2 页 |
| 框架计划(本 skill) | 为什么做 / 分几步 | 不掺字段,讲到阶段验收为止 |
| 业务说明 | 对外提供什么能力 | 功能视角,容易越列越多 |
| 详细设计 | 怎么实现 | 字段 / 接口 / 技术栈齐备 |
| PRD | 用户故事 / 验收 | 用户视角,需求场景化 |
错配的代价:把框架计划当业务说明写 → 变功能清单;当详细设计写 → 陷入字段细节。类型错位让所有后续努力打折扣。
总体目标和验收都用"能 X"句式——"数据能稳定进来"、"客户名单可用"、"失败能被发现"。
为什么:状态描述本身就是验收标准;动作描述只是过程语言。"数据能稳定进来"明确了 done 的定义,"采集数据"只描述工作量。
每个版本只解决一个主问题。不要列"X / Y / Z 一堆功能"——看起来完整,实际无法推进,容易变无底洞。
反例:"v1.0 包含 Metabase / Grafana / SQLite / API / 告警 / 备份 / 模型归并 / 客户名单" 正例:"v0.1 底座能跑 / v0.2 业务主口径进来 / v0.3 监控视角补齐 / v0.4 上层业务能用"
每个阶段先问"怎样算这个阶段完成",再从验收倒推该交付什么。不要先问"要做哪些模块"。
验收最好用"系统已经可以回答 X / Y / Z"的句式——把技术验收和业务价值天然连起来。
"不做"不能只列出来。每条都要配"为什么不放进这个版本"。
为什么:防 scope creep 的关键武器。业务方质疑"为什么不做 X"时,可以直接指到这一行的理由——否则会反复重开讨论。
整篇文档的隐含问题是:
一个完全没接触过这个项目的人,读完,能不能理解项目为什么成立、做到什么程度算完、是否对他有用?
禁止:在框架计划里写"为我们自己确认范围"的内容——目录骨架、技术栈选型、字段细节、并发模型,这些都是详细设计阶段的事。
目标:在动笔前把现状摸清楚,让后面所有设计判断都能指回事实。
进 Stage 1 之前先问两个判断题,如果两个回答都触发"小",直接退出 skill,不要继续——这场景不该用 plan-report:
退出规则:
不做规模快筛 → AI 会用标准骨架硬套小项目,造成过度结构化。这一步是这次 skill 改进的硬约束,不能跳。
追问模板:
硬门:
信息深度自检(防止 Stage 1 被空泛回答糊弄过去):
立项前期的灰度通道:如果项目处于真早期立项阶段,用户确实还没有精确数字,可以用 "量级估算 + 1-2 个具体痛点场景" 代替精确数字(例如"几十个业务线" + "上次某团队配错告警 3 个月才被发现")。但仅限立项早期——已经在做的项目必须给具体数字。
如果硬门没过(信息不足以进 Stage 2),不要硬产出 plan。这时正确的产出是**"卡住状态说明"**,固定格式如下:
# {项目名} v1.0 计划 — Stage 1 卡住,待补信息
## 已收集信息
- 项目背景: {已知部分 / 待补}
- 现状: {已知部分 / 待补}
- 目标消费方: {已知部分 / 待补}
- 硬约束: {已知部分 / 待补}
## 还需要从用户追问的 X 个具体问题
1. {具体问题 1,例如"现在文档散在哪些系统里?多少篇?"}
2. {具体问题 2,例如"使用人数 30 / 300 / 3000?"}
3. {具体问题 3,例如"最近一次'用起来不爽'的具体场景是什么?"}
...
## 进 Stage 2 的最低标准
收到上面问题的回答后,要保证能用 3 行话回答"现状是什么 / 能拿到什么 / 有哪些硬约束 / 谁会消费"。
禁止:用"据我理解你大概想做 X" / "我假设你的现状是 Y" 开头硬补。这是凭空补全的伪装,等价于 Stage 1 闯关。
目标:确认要写的是"框架计划",而不是别的类型;如果是别的类型,提示用户换 skill。
操作要点:
跟用户对齐这份文档的定位:
如果用户说"我要把字段都写清楚"——这是详细设计,本 skill 不适用,建议另起一份。
如果用户说"我要列我们能提供的功能"——这是业务说明,本 skill 不适用,建议另起一份。
追问模板:
硬门:
目标:把框架计划的固定骨架定下来,让用户校验。
框架计划的固定骨架(5 段):
定位 → 痛点 → 边界 → 阶段 → 验收
展开成章节(标准版 10 节):
1. 项目定位 (是什么 / 不是什么)
2. 为什么要做 (核心痛点)
3. 服务/系统边界 (负责 / 不负责)
4. v1.0 总体目标 (做到什么程度算完)
5. 版本路线 (分几步,只一行流程图)
6. v0.1 阶段 (要解决的问题 / 主要交付 / 阶段验收)
7. v0.2 阶段 (同上三段式)
8. v0.3 阶段 (同上三段式)
9. v0.4 阶段 (同上三段式)
10. v1.0 之后再考虑 (后续不做,每条配理由)
11. (可选) 关联文档——如果上层文档全部为空,**整节删除**,不要留"待补"占位符
项目规模自适应(关键,避免小项目过度结构化):
| 项目规模 | 阶段数 | 总体目标行数 | 痛点表行数 | 总节数 |
|---|---|---|---|---|
| 小(1 人 < 6 周 / < 2 人月) | 2-3 个 | 3-4 行 | 3-4 行 | 8-9 节 |
| 中(1-3 人 1-3 月) | 3-4 个 | 4-5 行 | 4-5 行 | 9-10 节 |
| 大(>3 月 / 多人协作) | 4-5 个 | 5-6 行 | 5-7 行 | 10-11 节 |
核心纪律:按真实情况定行数,不要按模板默认值凑数。凑出来的内容读者一眼能看出来。
每个阶段必须用统一三段式,无论项目规模——这一点不变。
操作要点:
追问模板:
硬门:骨架没确认 → 不进 Stage 4。
目标:逐节填内容,每节都按"内容判断 4 原则"落字。
4 原则:
开篇用 "它的目标不是 X,而是 Z" 的句式。先排除常见误解,再立正确定位。
误解数量按场景定:1-3 个,宁缺勿凑。如果想不出第 2 个真实误解,就不要硬塞——硬凑的误解读者一眼能看出来。
对内部工具类项目特别说明:如果项目是面向内部团队的工具(告警平台、巡检工具、CI 平台等),读者可能不带"以为是 X"的误解——这时改用对照式:"它做 X / 不做 Y",而不是强行写"不是 A / 不是 B / 不是 C"。
为什么:读者常带错误预期来(以为是"数据平台"、"业务系统"、"分析工具")。先打掉误解,定位才立得住。但误解不存在就不要造一个。
第 2 节"为什么做"用 "问题 | 影响"表格——每行是名词性短语 + 一句具体后果。
行数按真实痛点数,不要凑:
反例:P1. 多个业务重复抓数据
正例:重复采集 | 日报、客户分析、价值评估都各自拉一遍,浪费维护成本
第 5 节"版本路线"只放一个流程图,不解释。
v0.1 底座能跑 → v0.2 业务主口径进来 → v0.3 监控视角补齐 → v0.4 上层业务能用 → v1.0 正式可用
每个版本只解决一个主问题。如果一个版本要解决 3 件事,通常说明拆得不够。
每个阶段先写"阶段验收"再写"主要交付"。从验收倒推该交付什么,而不是从功能列表正推验收。
追问模板:
硬门:每节内容写完都要让用户看一眼,确认方向对再继续——避免铺完全篇才发现方向偏。
目标:每个版本(v0.1 / v0.2 / ...) 都用同一个三段式结构展开。
三段式:
### v0.X {阶段标题}:{一句话主线}
**要解决的问题**
{2-3 句,说清楚这个阶段为什么存在 / 不做会怎样}
**主要交付**
- {交付物 1}
- {交付物 2}
- {交付物 3,不超过 5-6 个}
**阶段验收**
{按项目类型选一种句式}
阶段验收的 3 种句式备选(选最适合的,不要硬套数据查询型):
| 项目类型 | 验收句式 | 例子 |
|---|---|---|
| 数据 / 查询型 | "系统已经可以回答 X / Y / Z" | "某客户某天调用了多少 / 消耗了多少 Token / 主要模型分布是什么" |
| 工具 / 流程型(dashboard、采集、自动化) | "X 能做到 / Y 能做到" 状态清单 | "新人不读源码能看 dashboard 判断系统状态 / 6 个 SRE 任一人能一键跑完全部巡检" |
| 平台 / 服务型 | 三段:能力陈述 + 客户可观测信号 + 兜底 | "API 能稳定接收告警 / 业务方能在 30 秒内确认是否发出 / 老链路保留不强切" |
禁止强行把工具型验收硬套"系统能回答 X"——会写出"系统能回答'新人能不能上手'"这种语法不顺的句子。句式服从场景,不是场景服从句式。
为什么必须统一:
禁止:
追问模板:
目标:写完初稿后,按 5 个替换写法逐节扫一遍。
5 个替换:
| 不要这样写 | 改成这样写 | 为什么 |
|---|---|---|
| 动作描述("采集数据") | 状态描述("数据能稳定进来") | 状态本身就是验收标准 |
| 技术验收("字段对齐") | 业务问句("系统已经可以回答 X / Y / Z") | 把技术验收和业务价值连起来 |
| 不做项只说"不做 X" | 不做项 + "为什么不放进当前版本" | 防 scope creep |
| 痛点用 P1/P2 编号 + 长句 | 痛点用名词短语 + 一句具体后果 | 简洁有力 |
| 标题堆修饰("v1.0 定位与边界范围说明") | 标题朴素("项目定位") | 少加修饰,标题越短越好 |
追问模板:
目标:写完之后做一次"读者视角自检",通过后才落盘。
自检清单(强制逐项检查):
落盘:
docs/plan/{版本号}-{命题}-{项目名}.md,如 docs/plan/v1.0-框架-customer-metrics-service.md禁止:自检没过就落盘——一旦提交,业务方会按错位的版本理解,后续校正成本高。
两套模板:Stage 1 规模快筛后选用哪套——
适用:1 人 1-6 周 / 工具类 / 单团队内部使用 / 不分多阶段没法独立交付。
# {项目名} {版本} 框架计划
> 状态:框架计划版
> 日期:{YYYY-MM-DD}
> 项目规模:小(1 人 X 周 / Y 阶段)
---
## 1. 项目定位
{项目名} 是一个 **{核心定位 1 句话}**。
**它做**:{X 件具体能做的事,3 行内}
**它不做**:{Y 件明确不做的事,2 行内,跟"v1.0 之后"区别开}
> 内部工具类项目:用"它做 / 它不做"对照式,不强求"不是 A / B / C"误解
---
## 2. 为什么要做
| 问题 | 影响 |
|---|---|
| {真实痛点 1} | {具体后果} |
| {真实痛点 2} | {具体后果} |
| {真实痛点 3} | {具体后果,3-4 行够,不凑数} |
---
## 3. {版本} 总体目标
| 目标 | 说明 |
|---|---|
| {状态 1,"能 X" 句式} | {说明} |
| {状态 2} | {说明} |
| {状态 3,3-4 行够} | {说明} |
---
## 4. 版本路线
```text
v0.1 {阶段口号} → v0.2 {阶段口号} → v0.3 {阶段口号} → {版本} 可用
```
---
## 5. v0.1 {标题}
### 要解决的问题
{...}
### 主要交付
- {...}
### 阶段验收
{用工具型 / 平台型句式,见 Stage 5 三段式备选}
---
## 6. v0.2 {标题}
(同上三段式)
## 7. v0.3 {标题}
(同上三段式)
---
## 8. {版本} 之后再考虑什么
| 后续方向 | 为什么不放进 {版本} |
|---|---|
| {不做项 1} | {理由} |
| {不做项 2} | {理由,2-3 行够} |
小项目骨架的核心约束(对照标准骨架的差异):
适用:1 人 >6 周 / 多人协作 / 4+ 阶段 / 跨团队消费 / 有上层架构基线。
# {项目名} {版本} 框架计划
> 状态:框架计划版,技术细节留待详细设计阶段
> 日期:{YYYY-MM-DD}
> 上层文档:{架构基线 / 立项书 路径,如有}
---
## 1. 项目定位
{项目名} 是一个 **{核心定位 1 句话}**。
它的目标**不是** {常见误解 1} {/ 误解 2 / 误解 3 — 按真实情况,1-3 个,宁缺勿凑},**而是** {正确定位}。
> **如果是内部工具类项目**且想不出真实误解,改用对照式:"它做 X / 不做 Y",不要硬凑误解。
一句话概括:
```text
{核心动作链路,如:统一采集 → 统一沉淀 → 统一口径 → 统一接口 → 给上层业务使用}
```
---
## 2. 为什么要做
现在 {一句话现状}。这样会带来几个长期问题:
| 问题 | 影响 |
|---|---|
| {痛点 1} | {具体后果 1} |
| {痛点 2} | {具体后果 2} |
| {痛点 3} | {具体后果 3} |
| ... | ... |
> **行数按真实痛点数,不要凑**:小项目 3-4 行 / 中型 4-5 行 / 大型 5-7 行。**3 秒判断法**:这条痛点能不能在生产事故复盘 / 业务方吐槽里被点名?能 → 留;不能 → 删。
{版本} 要解决的是这些基础问题,而不是一次性把所有 {业务/能力} 都做完。
---
## 3. 服务边界
{项目名} 只负责 **{核心职责}**。
```text
{上游 / 输入}
↓
{本项目} ← 当前文档
↓
{下游 / 消费方}
```
本项目负责:
- {职责 1}
- {职责 2}
- {职责 3}
本项目不负责:
- {不做 1}
- {不做 2}
- {不做 3}
这些能力属于 {归属方}。
---
## 4. {版本} 总体目标
{版本} 的目标是做出 {状态描述},而不是 {容易被误解的更大目标}。
| 目标 | 说明 |
|---|---|
| {状态 1,"能 X" 句式,如"数据能稳定进来"} | {1 句说明} |
| {状态 2} | {1 句说明} |
| {状态 3} | {1 句说明} |
| ... | ... |
> **行数按真实状态数,不要凑**:小项目 3-4 行 / 中型 4-5 行 / 大型 5-6 行。
> **"老链路可兜底"是 customer-metrics-service 这个示例项目的具体一行(因为有 maas_bot 老链路)——不要把它当成模板必填项。新项目如果没有"老链路",这一行就不要有。**
{版本} 不追求 {显式排除的过度目标},只要 {核心目标} 即可。
---
## 5. 版本路线
{版本} 拆成 N 个内部阶段推进。每个阶段只解决一个主问题。
```text
v0.1 {阶段口号}
↓
v0.2 {阶段口号}
↓
v0.3 {阶段口号}
↓
v0.4 {阶段口号}
↓
{版本} 正式可用
```
---
## 6. v0.1 {阶段标题}:{一句话主线}
### 要解决的问题
{为什么需要这个阶段 / 不做会怎样}
### 主要交付
- {交付物 1}
- {交付物 2}
- {交付物 3}
### 阶段验收
{1-2 句状态描述 + "系统已经可以回答 X" 句式}
---
## 7. v0.2 {阶段标题}:{一句话主线}
### 要解决的问题
...
### 主要交付
...
### 阶段验收
这一阶段结束后,系统已经可以回答:
- {业务问句 1}
- {业务问句 2}
- {业务问句 3}
---
## 8. v0.3 ...
...
---
## 9. v0.4 ...
...
---
## 10. {版本} 之后再考虑什么
{版本} 只解决 "{核心目标}"。以下事项不放进 {版本} 主目标:
| 后续方向 | 为什么不放进 {版本} |
|---|---|
| {不做项 1} | {理由 1} |
| {不做项 2} | {理由 2} |
| {不做项 3} | {理由 3} |
{版本} 的核心原则是:
```text
{一句话原则,如"先把数据底座跑稳,再扩展计算和产品能力"}
```
---
## 关联文档
- 上层文档:{路径}
- 项目记忆:{路径}
- 旧代码参照:{路径}
关键约束:
文件路径:docs/plan/v1.0-框架-customer-metrics-service.md
关键设计决策:
AI 写计划报告时常犯的 6 个反模式(看到自己在写下面任一种,停下重想):
按"输入资源"切版本(数据源 / 客户类型 / 第三方依赖)→ 应该按能力层切(地基 → 业务接入 → 服务对外)。问自己:每个版本能不能独立交付一个"用户能感知的能力"?不能 → 切错了。
把"业务计算 / 上层加工"塞进自己的服务边界 → 应该明确"我只到事实数据层,业务计算归独立模块"。问自己:这个职责被砍掉,我的服务还成立吗?成立就该砍。
按未来最大规模做过度设计(并发池 / 队列 / 聚合告警 / 多租户)→ 应该按当前 1.0 真实规模设计,留接口不实现。问自己:这个复杂度是 v1.0 真需要,还是"假如有 100x 用户"?
把技术细节(目录骨架 / Docker / 技术栈 / cron 表达式 / 字段)写进框架计划 → 应该全部抽走,留到"详细设计文档"。问自己:这一段如果换个技术栈实现,还成立吗?成立 → 它是业务,不是技术,留下;不成立 → 删。
把"框架计划"写成"业务能力清单"(列"提供 X / Y / Z 功能") → 应该把能力融化进"总体目标"的状态表("X 能稳定 / Y 能被读 / Z 能被发现"),不要单独开"提供什么能力"章节。
用"据我理解"开头硬补缺失信息——这是最隐蔽的反模式。Stage 1 信息不足时,AI 会礼貌地写"据我理解你大概想做 X / 我假设现状是 Y / 你的客户量级应该是 Z"——这等价于凭空补全,会让 Stage 2 之后的所有判断悬空。正确反应是按 Stage 1 Step 3 的"卡住产出格式"输出待补问题,不要硬开篇。
实际案例里 customer-metrics-service 的 5 次校正:按数据源切版本 / summary 层塞进底座 / 100 客户过度设计 / 技术细节塞进 plan / 功能清单视角——是这 6 个反模式中前 5 个的具体表现。
场景:为内部业务团队建一个客户标签管理平台,30 个业务线接入。
关键设计决策的逻辑(学逻辑,不抄措辞):
标签定义散在各业务文档 | 同名标签语义不同,数据对账经常吵架标签发布无审计 | 谁改了什么没记录,出问题查不到下游消费方式单一 | 只能查 Excel,程序化集成难v0.1 元数据底座 → v0.2 标签登记上线 → v0.3 审计与变更 → v0.4 分发 API → v1.0 正式可用
画像计算 → 属于上层分析服务,不是登记平台职责多租户隔离 → 30 业务线规模下不需要,过度设计标签生效时间窗口管理 → 复杂度高,留到 v2.0关键陷阱(同 customer-metrics-service 校正经验):
场景 1:新项目立项后第一份"做什么"文档 → 上层有架构基线 / 立项书,需要把"v1.0 做什么、分几步"摊开。本 skill 主战场。
场景 2:已有项目的大版本规划 → 既有项目要做 v2.0 / v3.0,需要重新对齐"这一版的主问题是什么、跟前版有什么差异"。
场景 3:多阶段迁移计划 → 老系统迁新系统,需要拆"几个阶段、每阶段迁什么、迁完什么算成功"。
场景 4:内部工具的演进路线 → 内部脚本 / 工具想升级为正式服务,需要规划"从工具到服务的几步"。
detail-design 类文档,本 skill 不涉及prd-doc-writershare-outlineweekly-reportmeeting本 skill 默认"一个负责人主导写一份计划"。多人协作场景下(多个 owner、跨部门、需要先开会对齐):
本 skill 的 tools/ 子目录下提供 md2html.py 脚本和 style.css,用于把产出的 .md 转成可视化 .html。
.claude/skills/plan-report/
├── SKILL.md ← skill 本身,给 Claude 读
└── tools/
├── md2html.py ← 转换脚本
└── style.css ← 输出 HTML 的样式表
安装依赖(一次性):
pip3 install markdown
使用:
python3 .claude/skills/plan-report/tools/md2html.py docs/plan/v1.0-框架-{项目名}.md
输出会在 md 同目录生成同名 .html。
样式由 tools/style.css 控制,可以按需修改(蓝色 accent / 表格 hover / ASCII 图块等)。脚本会自动找到同目录的 style.css,也可以用 --css 参数指定其他样式表。
基于 SOC 职业分类