| name | plan-report |
| description | 帮助梳理一份"框架计划报告"(项目 v1.0 计划、版本路线、阶段方案等)。通过"摸现实 → 定文档类型 → 搭骨架 → 填内容 → 统一结构 → 语言精修 → 自检" 7 步引导,产出"讲为什么做 / 做到什么程度算完 / 分几步走"的框架计划,而不是功能清单或技术方案。当用户说"写计划报告"、"项目计划"、"框架计划"、"v1.0 计划"、"版本路线"、"阶段方案"、"plan-report"、"/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 周 / 1 周 - 6 周 / > 6 周?
- 能拆出几个独立交付的阶段: 1 个 / 2-3 个 / 4+ 个?
退出规则:
- 预计 < 1 周 且 只能拆 1 个阶段 → 明确退出:"这场景不需要框架计划,建议改用 1 页'做什么 + 怎么验证'文档"
- 预计 1-6 周 + 拆出 2-3 阶段 → 用小项目骨架(8-9 节,见"模板"节)
- 预计 > 6 周 / 拆出 4+ 阶段 → 用标准骨架(10 节)
不做规模快筛 → AI 会用标准骨架硬套小项目,造成过度结构化。这一步是这次 skill 改进的硬约束,不能跳。
Step 1: 收集以下信息(已知填上,不知道标记待补)
- 项目背景:项目名称、当前阶段(立项 / 在做 / 改造) / 是否有上层架构基线
- 现状:已有代码 / 已有系统能跑成什么样 / 能拿到什么数据 / 输出形态是什么
- 目标消费方:这份计划是给谁看的 / 谁会基于它做事
- 硬约束:技术约束(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 人 < 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 节 |
核心纪律:按真实情况定行数,不要按模板默认值凑数。凑出来的内容读者一眼能看出来。
每个阶段必须用统一三段式,无论项目规模——这一点不变。
操作要点:
- 骨架先整体抛给用户,让他增删章节、调整顺序
- 禁止:边写边改骨架
- 禁止:用户没确认就开始填内容
追问模板:
- "这个骨架对吗?有要加 / 减 / 调顺序的章节吗?"
- "阶段数定几个?——按'每阶段解决一个主问题'反推,通常 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 周 / <2 人月):3-4 行通常够
- 中型项目:4-5 行
- 大型项目:5-7 行
- 痛点筛选标准(3 秒判断法):这条痛点能不能在生产事故复盘 / 业务方吐槽里被点名?能 → 留;不能 → 删。
反例:P1. 多个业务重复抓数据
正例:重复采集 | 日报、客户分析、价值评估都各自拉一遍,浪费维护成本
原则 3:拆版本,不堆功能
第 5 节"版本路线"只放一个流程图,不解释。
v0.1 底座能跑 → v0.2 业务主口径进来 → v0.3 监控视角补齐 → v0.4 上层业务能用 → v1.0 正式可用
每个版本只解决一个主问题。如果一个版本要解决 3 件事,通常说明拆得不够。
原则 4:用验收反推交付
每个阶段先写"阶段验收"再写"主要交付"。从验收倒推该交付什么,而不是从功能列表正推验收。
追问模板:
- "这一节如果换个项目,还成立吗?成立说明在写空话,要重写得更具体"
- "这条痛点是真的痛,还是我们想象的痛?业务方能感知到吗?"
- "这个版本能不能再拆?如果一个版本同时要做 A B C 三件不同的事,可能拆得不够"
- "这个验收是技术指标还是业务能问出的问题?"
硬门:每节内容写完都要让用户看一眼,确认方向对再继续——避免铺完全篇才发现方向偏。
Stage 5: 每个版本用统一三段式
目标:每个版本(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"——会写出"系统能回答'新人能不能上手'"这种语法不顺的句子。句式服从场景,不是场景服从句式。
为什么必须统一:
- 读者一眼能横向对比各阶段(v0.1 vs v0.2 解决的问题、交付、验收分别是什么)
- 不容易写成流水账
- 不会过早陷入技术实现
- 各阶段权重看起来"对等",不会某个阶段写得特别详细某个特别敷衍
禁止:
- v0.1 用"做什么 / 价值",v0.2 用"目标 / 交付",v0.3 又自创格式
- 在某个阶段里加额外的小节(比如"风险点"、"依赖"),除非每个阶段都加
追问模板:
- "每个阶段验收都用'系统能回答 X'句式试一下,看看顺不顺"
- "这个交付清单超过 6 个了,要不要砍?或者说明这个阶段拆得不够细"
Stage 6: 语言精修
目标:写完初稿后,按 5 个替换写法逐节扫一遍。
5 个替换:
| 不要这样写 | 改成这样写 | 为什么 |
|---|
| 动作描述("采集数据") | 状态描述("数据能稳定进来") | 状态本身就是验收标准 |
| 技术验收("字段对齐") | 业务问句("系统已经可以回答 X / Y / Z") | 把技术验收和业务价值连起来 |
| 不做项只说"不做 X" | 不做项 + "为什么不放进当前版本" | 防 scope creep |
| 痛点用 P1/P2 编号 + 长句 | 痛点用名词短语 + 一句具体后果 | 简洁有力 |
| 标题堆修饰("v1.0 定位与边界范围说明") | 标题朴素("项目定位") | 少加修饰,标题越短越好 |
追问模板:
- "这段读起来像'我在向你解释一件事',还是'我在罗列我们要做的事'?后者就要改"
- "这个 bullet 换成'X 能 Y'的状态描述还能说清楚吗?"
Stage 7: 自检 + 落盘
目标:写完之后做一次"读者视角自检",通过后才落盘。
自检清单(强制逐项检查):
落盘:
- 默认路径:
docs/plan/{版本号}-{命题}-{项目名}.md,如 docs/plan/v1.0-框架-customer-metrics-service.md
- 同步生成 HTML(用本 skill 的 md → html 工具,见末尾)
禁止:自检没过就落盘——一旦提交,业务方会按错位的版本理解,后续校正成本高。
模板
两套模板:Stage 1 规模快筛后选用哪套——
- 小项目(1-6 周 / 2-3 阶段)→ 用小项目骨架(8-9 节)
- 中大项目(>6 周 / 4+ 阶段)→ 用标准骨架(10 节)
小项目骨架(8-9 节)
适用: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 行够} |
小项目骨架的核心约束(对照标准骨架的差异):
- 没有第 3 节"服务边界"——融化进第 1 节"它做 / 它不做"
- 没有"关联文档"节——小项目通常没上层文档
- 总体目标 3-4 行(不是 6 行)
- 痛点 3-4 行(不是 5 行)
- 2-3 个阶段(不是 4 个)
标准骨架(10 节)
适用: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
{一句话原则,如"先把数据底座跑稳,再扩展计算和产品能力"}
```
---
## 关联文档
- 上层文档:{路径}
- 项目记忆:{路径}
- 旧代码参照:{路径}
关键约束:
- 所有阶段(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.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 个的具体表现。
抽象案例(虚构:客户标签平台 v1.0)
场景:为内部业务团队建一个客户标签管理平台,30 个业务线接入。
关键设计决策的逻辑(学逻辑,不抄措辞):
关键陷阱(同 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 参数指定其他样式表。
