Plan Report

框架计划报告助手

功能说明

帮助用户产出一份框架计划报告——位于"项目章程"和"详细设计"之间的文档类型。

它回答:为什么做 / 做到什么程度算完 / 谁用它 / 不做什么 / 分几步走 / 每步停下时业务能问出什么。

它不回答:字段、接口、技术栈、目录命名、cron 表达式——这些是后续"详细设计文档"的事。

核心价值:让计划报告变成读者能看懂的故事,而不是作者给自己确认范围的工作清单。通过 7 步引导跟用户对齐方向、骨架、内容,最后才落盘。

---

核心原则

1. 先实证再设计

不要凭空推演。先把现状摸清楚——能跑的先跑、能读的代码先读、已知约束先列。

信号:能回答"现状是什么 / 能拿到什么 / 有哪些硬约束 / 谁会消费这份文档"。这四个问题答不上来,就不要进 Stage 2。

2. 文档类型决定一切

拿到诉求第一件事不是动笔,是问自己:这是哪一类文档?

| 类型 | 核心问题 | 写法特征 | |---|---|---| | 项目章程 | 为什么立项 | 偏战略,1-2 页 | | 框架计划(本 skill) | 为什么做 / 分几步 | 不掺字段,讲到阶段验收为止 | | 业务说明 | 对外提供什么能力 | 功能视角,容易越列越多 | | 详细设计 | 怎么实现 | 字段 / 接口 / 技术栈齐备 | | PRD | 用户故事 / 验收 | 用户视角,需求场景化 |

错配的代价:把框架计划当业务说明写 → 变功能清单;当详细设计写 → 陷入字段细节。类型错位让所有后续努力打折扣。

3. 状态描述 > 动作描述

总体目标和验收都用"能 X"句式——"数据能稳定进来"、"客户名单可用"、"失败能被发现"。

为什么:状态描述本身就是验收标准;动作描述只是过程语言。"数据能稳定进来"明确了 done 的定义,"采集数据"只描述工作量。

4. 拆版本,不堆功能

每个版本只解决一个主问题。不要列"X / Y / Z 一堆功能"——看起来完整,实际无法推进,容易变无底洞。

反例:"v1.0 包含 Metabase / Grafana / SQLite / API / 告警 / 备份 / 模型归并 / 客户名单" 正例:"v0.1 底座能跑 / v0.2 业务主口径进来 / v0.3 监控视角补齐 / v0.4 上层业务能用"

5. 用验收反推交付

每个阶段先问"怎样算这个阶段完成",再从验收倒推该交付什么。不要先问"要做哪些模块"。

验收最好用"系统已经可以回答 X / Y / Z"的句式——把技术验收和业务价值天然连起来。

6. 不做项必须配理由

"不做"不能只列出来。每条都要配"为什么不放进这个版本"。

为什么:防 scope creep 的关键武器。业务方质疑"为什么不做 X"时,可以直接指到这一行的理由——否则会反复重开讨论。

7. 始终为读者服务

整篇文档的隐含问题是:

> 一个完全没接触过这个项目的人,读完,能不能理解项目为什么成立、做到什么程度算完、是否对他有用?

禁止:在框架计划里写"为我们自己确认范围"的内容——目录骨架、技术栈选型、字段细节、并发模型,这些都是详细设计阶段的事。

---

工作流程

Stage 1: 摸现实

目标:在动笔前把现状摸清楚,让后面所有设计判断都能指回事实。

---

Step 0: 规模快筛(进 Stage 1 前先做,防止小项目误用)

进 Stage 1 之前先问两个判断题,如果两个回答都触发"小",直接退出 skill,不要继续——这场景不该用 plan-report:

1. 预计耗时: 6 周?
2. 能拆出几个独立交付的阶段: 1 个 / 2-3 个 / 4+ 个?

退出规则:

• 预计 6 周 / 拆出 4+ 阶段 → 用标准骨架(10 节)

不做规模快筛 → AI 会用标准骨架硬套小项目,造成过度结构化。这一步是这次 skill 改进的硬约束,不能跳。

---

Step 1: 收集以下信息(已知填上,不知道标记待补)

1. 项目背景:项目名称、当前阶段(立项 / 在做 / 改造) / 是否有上层架构基线
2. 现状:已有代码 / 已有系统能跑成什么样 / 能拿到什么数据 / 输出形态是什么
3. 目标消费方:这份计划是给谁看的 / 谁会基于它做事
4. 硬约束:技术约束(API 限流、数据窗口、存储上限)、业务约束(规模、节奏、预算)、组织约束(谁负责、何时上线)

追问模板:

• "现在能跑通的部分是什么?能跑一下让我看到真实输出吗?"
• "有没有上层文档(架构基线、立项书、调研报告)我应该先读?"
• "这份计划是给谁看的——内部产研 / 跨团队 / 客户?"
• "有没有已知的硬约束?比如 API 限流、上线 deadline、客户量上限?"

---

Step 2: 硬门 + 信息深度自检

硬门:

• 不要进 Stage 2,除非你能用 3 行话回答"现状是什么 / 能拿到什么 / 有哪些硬约束 / 谁会消费"
• 凭空设计是这个 skill 最容易踩的坑——没摸现实就动笔 = 后面所有判断没根

信息深度自检(防止 Stage 1 被空泛回答糊弄过去):

• 现状回答里必须有具体数字 / 系统名 / 数据规模(比如"50+ 业务线"、"12 个 bash 脚本"、"2000 万客户"),只有形容词("挺多的"、"不少")不算过门
• 硬约束回答里必须有具体数值 / 时限 / 接口限制(比如"飞书 API 100 QPS"、"Hive 查询 10-30 秒"),"听说有限制"不算过门
• 如果回答都是空泛形容词,返回追问模板逐项问透,不要硬过门

立项前期的灰度通道:如果项目处于真早期立项阶段,用户确实还没有精确数字,可以用 "量级估算 + 1-2 个具体痛点场景" 代替精确数字(例如"几十个业务线" + "上次某团队配错告警 3 个月才被发现")。但仅限立项早期——已经在做的项目必须给具体数字。

---

Step 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 闯关。

---

Stage 2: 定文档类型

目标:确认要写的是"框架计划",而不是别的类型;如果是别的类型,提示用户换 skill。

操作要点:

跟用户对齐这份文档的定位:

• 它回答:为什么做 / 做到什么程度算完 / 谁用 / 不做什么 / 分几步 / 每步验收
• 它不回答:字段、接口、技术栈、目录、cron 表达式、并发模型

如果用户说"我要把字段都写清楚"——这是详细设计,本 skill 不适用,建议另起一份。

如果用户说"我要列我们能提供的功能"——这是业务说明,本 skill 不适用,建议另起一份。

追问模板:

• "这份文档主要给谁看?给做事的人 → 偏详细设计;给理解事的人 → 框架计划"
• "你期望它解决什么问题?——'让团队对齐做什么 / 怎么算完'是框架计划;'让业务方知道能用什么'是业务说明"

硬门:

• 文档类型没明确前,不要搭骨架
• 错位的类型 = 整份文档作废,这一步必须卡住

---

Stage 3: 搭骨架

目标:把框架计划的固定骨架定下来,让用户校验。

框架计划的固定骨架(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 人 3 月 / 多人协作) | 4-5 个 | 5-6 行 | 5-7 行 | 10-11 节 |

核心纪律:按真实情况定行数,不要按模板默认值凑数。凑出来的内容读者一眼能看出来。

每个阶段必须用统一三段式,无论项目规模——这一点不变。

操作要点:

• 骨架先整体抛给用户,让他增删章节、调整顺序
• 禁止:边写边改骨架
• 禁止:用户没确认就开始填内容

追问模板:

• "这个骨架对吗?有要加 / 减 / 调顺序的章节吗?"
• "阶段数定几个?——按'每阶段解决一个主问题'反推,通常 3-5 个合适"

硬门:骨架没确认 → 不进 Stage 4。

---

Stage 4: 填每节内容(按 4 原则)

目标:逐节填内容,每节都按"内容判断 4 原则"落字。

4 原则:

原则 1:先定是什么 / 不是什么

开篇用 "它的目标不是 X,而是 Z" 的句式。先排除常见误解,再立正确定位。

误解数量按场景定:1-3 个,宁缺勿凑。如果想不出第 2 个真实误解,就不要硬塞——硬凑的误解读者一眼能看出来。

对内部工具类项目特别说明:如果项目是面向内部团队的工具(告警平台、巡检工具、CI 平台等),读者可能不带"以为是 X"的误解——这时改用对照式:"它做 X / 不做 Y",而不是强行写"不是 A / 不是 B / 不是 C"。

为什么:读者常带错误预期来(以为是"数据平台"、"业务系统"、"分析工具")。先打掉误解,定位才立得住。但误解不存在就不要造一个。

原则 2:找痛点,不说"要做 X"

第 2 节"为什么做"用 "问题 | 影响"表格——每行是名词性短语 + 一句具体后果。

行数按真实痛点数,不要凑:

• 小项目(6 周 / 4+ 阶段)→ 用标准骨架(10 节)

---

小项目骨架(8-9 节)

适用:1 人 1-6 周 / 工具类 / 单团队内部使用 / 不分多阶段没法独立交付。

````markdown

{项目名} {版本} 框架计划

> 状态:框架计划版 > 日期:{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. 版本路线

v0.1 {阶段口号} → v0.2 {阶段口号} → v0.3 {阶段口号} → {版本} 可用

---

5. v0.1 {标题}

要解决的问题

{...}

主要交付

• {...}

阶段验收

{用工具型 / 平台型句式,见 Stage 5 三段式备选}

---

6. v0.2 {标题}

(同上三段式)

7. v0.3 {标题}

(同上三段式)

---

8. {版本} 之后再考虑什么

| 后续方向 | 为什么不放进 {版本} | |---|---| | {不做项 1} | {理由} | | {不做项 2} | {理由,2-3 行够} |

````

小项目骨架的核心约束(对照标准骨架的差异):

• 没有第 3 节"服务边界"——融化进第 1 节"它做 / 它不做"
• 没有"关联文档"节——小项目通常没上层文档
• 总体目标 3-4 行(不是 6 行)
• 痛点 3-4 行(不是 5 行)
• 2-3 个阶段(不是 4 个)

---

标准骨架(10 节)

适用:1 人 >6 周 / 多人协作 / 4+ 阶段 / 跨团队消费 / 有上层架构基线。

````markdown

{项目名} {版本} 框架计划

> 状态:框架计划版,技术细节留待详细设计阶段 > 日期:{YYYY-MM-DD} > 上层文档:{架构基线 / 立项书 路径,如有}

---

1. 项目定位

{项目名} 是一个 {核心定位 1 句话}。

它的目标不是 {常见误解 1} {/ 误解 2 / 误解 3 — 按真实情况,1-3 个,宁缺勿凑},而是 {正确定位}。

> 如果是内部工具类项目且想不出真实误解,改用对照式:"它做 X / 不做 Y",不要硬凑误解。

一句话概括:

{核心动作链路,如:统一采集 → 统一沉淀 → 统一口径 → 统一接口 → 给上层业务使用}

---

2. 为什么要做

现在 {一句话现状}。这样会带来几个长期问题:

| 问题 | 影响 | |---|---| | {痛点 1} | {具体后果 1} | | {痛点 2} | {具体后果 2} | | {痛点 3} | {具体后果 3} | | ... | ... |

> 行数按真实痛点数,不要凑:小项目 3-4 行 / 中型 4-5 行 / 大型 5-7 行。3 秒判断法:这条痛点能不能在生产事故复盘 / 业务方吐槽里被点名?能 → 留;不能 → 删。

{版本} 要解决的是这些基础问题,而不是一次性把所有 {业务/能力} 都做完。

---

3. 服务边界

{项目名} 只负责 {核心职责}。

{上游 / 输入}
   ↓
{本项目}   ← 当前文档
   ↓
{下游 / 消费方}

本项目负责:

• {职责 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 个内部阶段推进。每个阶段只解决一个主问题。

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} |

{版本} 的核心原则是:

{一句话原则,如"先把数据底座跑稳,再扩展计算和产品能力"}

---

关联文档

• 上层文档:{路径}
• 项目记忆:{路径}
• 旧代码参照:{路径}

````

关键约束:

• 所有阶段(v0.1-v0.4)必须用统一三段式,不要某个阶段加额外小节
• 不出现字段名、表名、接口路径、技术栈、目录路径、cron 表达式
• 不做项必须有"为什么不放进当前版本"列
• 标题朴素,不堆修饰

---

示例参考

实际案例(customer-metrics-service v1.0)

文件路径:docs/plan/v1.0-框架-customer-metrics-service.md

关键设计决策:

• 项目定位先用"不是 X / Y / Z,而是 Z"打掉误解——"不是做客户价值评分、ROI 分析或日报页面,而是把分散的数据统一收口"
• 第 4 节总体目标用 6 行"能 X"句式——数据能稳定进来 / 能稳定沉淀 / 口径能统一 / 能被程序读取 / 失败能被发现 / 老链路可兜底
• 4 个阶段都用统一三段式,验收都用"系统已经可以回答 X / Y / Z"句式
• 第 10 节不做项用 "后续方向 | 为什么不放进 v1.0" 表格,每条配理由
• 最后用一句口号收束:"先把数据底座跑稳,再扩展计算和产品能力"

AI 写计划报告时常犯的 6 个反模式(看到自己在写下面任一种,停下重想):

1. 按"输入资源"切版本(数据源 / 客户类型 / 第三方依赖)→ 应该按能力层切(地基 → 业务接入 → 服务对外)。问自己:每个版本能不能独立交付一个"用户能感知的能力"?不能 → 切错了。

1. 把"业务计算 / 上层加工"塞进自己的服务边界 → 应该明确"我只到事实数据层,业务计算归独立模块"。问自己:这个职责被砍掉,我的服务还成立吗?成立就该砍。

1. 按未来最大规模做过度设计(并发池 / 队列 / 聚合告警 / 多租户)→ 应该按当前 1.0 真实规模设计,留接口不实现。问自己:这个复杂度是 v1.0 真需要,还是"假如有 100x 用户"?

1. 把技术细节(目录骨架 / Docker / 技术栈 / cron 表达式 / 字段)写进框架计划 → 应该全部抽走,留到"详细设计文档"。问自己:这一段如果换个技术栈实现,还成立吗?成立 → 它是业务,不是技术,留下;不成立 → 删。

1. 把"框架计划"写成"业务能力清单"(列"提供 X / Y / Z 功能") → 应该把能力融化进"总体目标"的状态表("X 能稳定 / Y 能被读 / Z 能被发现"),不要单独开"提供什么能力"章节。

1. 用"据我理解"开头硬补缺失信息——这是最隐蔽的反模式。Stage 1 信息不足时,AI 会礼貌地写"据我理解你大概想做 X / 我假设现状是 Y / 你的客户量级应该是 Z"——这等价于凭空补全,会让 Stage 2 之后的所有判断悬空。正确反应是按 Stage 1 Step 3 的"卡住产出格式"输出待补问题,不要硬开篇。

实际案例里 customer-metrics-service 的 5 次校正:按数据源切版本 / summary 层塞进底座 / 100 客户过度设计 / 技术细节塞进 plan / 功能清单视角——是这 6 个反模式中前 5 个的具体表现。

抽象案例(虚构:客户标签平台 v1.0)

场景:为内部业务团队建一个客户标签管理平台,30 个业务线接入。

关键设计决策的逻辑(学逻辑,不抄措辞):

• 定位:"不是 BI 工具 / 不是 CDP / 不是用户画像系统,而是客户标签的统一登记和分发服务"——先打掉 3 个常见误解
• 痛点(虚构示例):
• 标签定义散在各业务文档 | 同名标签语义不同,数据对账经常吵架
• 标签发布无审计 | 谁改了什么没记录,出问题查不到
• 下游消费方式单一 | 只能查 Excel,程序化集成难
• 总体目标(状态描述):标签能登记 / 定义能复用 / 变更能追溯 / 数据能被程序读取
• 版本路线(每阶段一个主问题):

`` v0.1 元数据底座 → v0.2 标签登记上线 → v0.3 审计与变更 → v0.4 分发 API → v1.0 正式可用 ``

• v0.2 验收用业务问句:
• "某个标签当前的定义是什么?"
• "哪些业务线用了这个标签?"
• "这个标签上次什么时候变过?"
• 不做项配理由:
• 画像计算 → 属于上层分析服务,不是登记平台职责
• 多租户隔离 → 30 业务线规模下不需要,过度设计
• 标签生效时间窗口管理 → 复杂度高,留到 v2.0

关键陷阱(同 customer-metrics-service 校正经验):

• 不要按"数据源"切版本(MySQL / Hive / 外部 API),按能力层切
• 不要在 plan 里写字段、表结构、API 路径
• 不要列"提供查询能力 / 提供登记能力 / 提供审计能力"这种功能清单——融化进"总体目标"的状态表

---

使用场景

场景 1:新项目立项后第一份"做什么"文档 → 上层有架构基线 / 立项书,需要把"v1.0 做什么、分几步"摊开。本 skill 主战场。

场景 2:已有项目的大版本规划 → 既有项目要做 v2.0 / v3.0,需要重新对齐"这一版的主问题是什么、跟前版有什么差异"。

场景 3:多阶段迁移计划 → 老系统迁新系统,需要拆"几个阶段、每阶段迁什么、迁完什么算成功"。

场景 4:内部工具的演进路线 → 内部脚本 / 工具想升级为正式服务,需要规划"从工具到服务的几步"。

---

不适用场景

文档类型不匹配

• 详细设计文档(字段 / 接口 / 技术栈齐备)→ 另起 detail-design 类文档,本 skill 不涉及
• PRD / 需求文档(用户故事 / 验收标准)→ 用 prd-doc-writer
• 业务说明(对外列功能清单)→ 业务说明视角不同,本 skill 不适用
• 拜访 / 分享大纲(给外部听众讲一场)→ 用 share-outline
• 周报 / 工作汇总(已发生事项的整理)→ 用 weekly-report
• 客户共识会准备(多方对齐)→ 用 meeting

项目规模太小

• 1 周内的脚本改造 / bug 修复 / 小调整——不需要框架计划,直接写 1 页"做什么 + 怎么验证"即可
• 不需要分阶段的"一次性交付"项目——没有 v0.1 / v0.2 之分的项目,本 skill 会过度结构化
• 判断标准:如果你想出来的"阶段"只有 1 个,或者每阶段做的事都互相依赖无法独立交付——说明这项目不需要框架计划

多人协作场景的注意事项

本 skill 默认"一个负责人主导写一份计划"。多人协作场景下(多个 owner、跨部门、需要先开会对齐):

• Stage 1-3 建议先开 1-2 次小会对齐"现状 / 文档类型 / 骨架",再让一个人主笔
• 不要 3 个人在 Stage 3 骨架上吵几天——硬门是用来卡 AI 跳步骤的,不是用来卡团队讨论的

---

md → html 转换

本 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 参数指定其他样式表。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yunshu0909
• Source: yunshu0909/yunshu_skillshub
• License: MIT

Install and usage instructions live in the source repository linked above.