plan-report

Imported from yunshu0909/yunshu_skillshub (plan-report/SKILL.md). Install upstream with npx skills add yunshu0909/yunshu_skillshub --skill plan-report. Copyright stays with the author.

框架计划报告助手

功能说明

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

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

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

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

核心原则

1. 先实证再设计

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

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

2. 文档类型决定一切

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

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

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 周 / 1 周 - 6 周 / > 6 周?
2. 能拆出几个独立交付的阶段: 1 个 / 2-3 个 / 4+ 个?

退出规则:

• 预计 < 1 周 且 只能拆 1 个阶段 → 明确退出:"这场景不需要框架计划,建议改用 1 页'做什么 + 怎么验证'文档"
• 预计 1-6 周 + 拆出 2-3 阶段 → 用小项目骨架(8-9 节,见"模板"节)
• 预计 > 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. (可选) 关联文档——如果上层文档全部为空,**整节删除**,不要留"待补"占位符

项目规模自适应(关键,避免小项目过度结构化):

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

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

操作要点:

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

追问模板:

• "这个骨架对吗?有要加 / 减 / 调顺序的章节吗?"
• "阶段数定几个?——按'每阶段解决一个主问题'反推,通常 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"——会写出"系统能回答'新人能不能上手'"这种语法不顺的句子。句式服从场景,不是场景服从句式。

为什么必须统一:

• 读者一眼能横向对比各阶段(v0.1 vs v0.2 解决的问题、交付、验收分别是什么)
• 不容易写成流水账
• 不会过早陷入技术实现
• 各阶段权重看起来"对等",不会某个阶段写得特别详细某个特别敷衍

禁止:

• v0.1 用"做什么 / 价值",v0.2 用"目标 / 交付",v0.3 又自创格式
• 在某个阶段里加额外的小节(比如"风险点"、"依赖"),除非每个阶段都加

追问模板:

• "每个阶段验收都用'系统能回答 X'句式试一下,看看顺不顺"
• "这个交付清单超过 6 个了,要不要砍?或者说明这个阶段拆得不够细"

Stage 6: 语言精修

目标:写完初稿后,按 5 个替换写法逐节扫一遍。

5 个替换:

追问模板:

• "这段读起来像'我在向你解释一件事',还是'我在罗列我们要做的事'?后者就要改"
• "这个 bullet 换成'X 能 Y'的状态描述还能说清楚吗?"

Stage 7: 自检 + 落盘

目标:写完之后做一次"读者视角自检",通过后才落盘。

自检清单(强制逐项检查):

• 核心问题:陌生读者读完,能不能理解"项目为什么成立 / 做到什么程度算完 / 是否对他有用"?
• 类型纯度:文档里有没有混进字段、接口、技术栈、目录命名、cron 表达式?有 → 删
• 痛点真实性:每条痛点都是业务方能感知的吗?还是只是作者觉得"应该提一下"?用 3 秒判断法:能不能在事故复盘 / 业务方吐槽里被点名
• 版本可拆性:每个版本只解决一个主问题吗?如果某个版本同时做 A B C,要么拆,要么合并到下一版
• 三段式纪律:所有阶段都严格用"要解决的问题 / 主要交付 / 阶段验收"三段?有没有某个阶段自创格式?
• 状态描述:总体目标和验收都是"能 X"句式?还是混进了动作描述?
• 不做项配理由:第 10 节每条"不做"都跟一句"为什么不放进当前版本"?
• 业务问句:验收里有没有"系统已经可以回答 X / Y / Z"句式?
• 统一称呼:全文是叫"v1.0"、"第一阶段"、"首版"——用一个,别混
• 边界 vs 不做去重(新增):第 3 节"不负责"和第 10 节"v1.0 之后再考虑"有没有语义混淆?——前者是"永远不做"(职责边界),后者是"这版不做但后续可能做"(范围边界)
• 技术约束业务化(新增):项目的硬约束(API 限流、数据窗口、合规等)是不是用业务语言写在了"要解决的问题"里,而不是当成技术细节抛出来?
• 过度结构化反向校验(新增):每个表格 / 每个阶段都问一句"这一行 / 这一阶段砍掉,文档还成立吗?成立就砍。"
• 行数没凑数(新增):总体目标 / 痛点表 / 不做项的行数,有没有"为了凑数硬塞的"?——如果有一行特别空泛、特别像"应付任务",删掉

落盘:

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

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

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

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

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

6. 用"据我理解"开头硬补缺失信息——这是最隐蔽的反模式。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 参数指定其他样式表。