# Prompt — TVU Design Process Evolution（unified execution，1 个 session 跑完所有）

> **Source date**: 2026-05-12，from `2026-05-12 SaaS Dashboard chart` session 后期 strategic 讨论
> **Scope**: TVU Design System repo `/Users/nancy/Documents/AICoding/VS_Code/tvu-design-system` 内规则文档 + `~/.claude/skills/design-discovery/` + `~/.claude/agents/`
> **不在 scope**: 任何消费产品 Figma 文件 / 消费产品 docs

---

## 背景（self-contained — 不依赖对话上下文）

### 当前规则文件状态

- `docs/internal/mockup-conventions.md` — 23 条 M-prefix 规则（M0-M22 + sub-rules）
- `docs/internal/code-conventions.md` — 7 条 R-prefix 规则（R0-R6）
- `docs/meta-rules.md` — 反模式清单
- `docs/internal/retrospection/` — 30+ retrospect 文件（含 cross-ref M-codes）

### 3 个 architectural 问题

1. **3 类内容混在一份文件** — `mockup-conventions.md` 同时装 generic process rules（"Library 优先 + 实证搜索"）/ TVU 业务规则（"红=Live 广播 ON AIR"）/ Figma API quirks（"绑变量 + opacity 两步法"）。新 AI session onboard 时三类一起读，通用规则被 noise 稀释。
2. **Process / Discipline 类规则有冗余** — M11/M12/M13 都是 "self-audit 自查方法论"，可合并；M17-M20 是 Figma API 边角不该规则级地位（应当 quirks reference table）。
3. **两条独立 path 通用规则没共享** — Path A（Figma mockup）与 Path B（Code 产品）独立运行，但 user discovery / library 优先 / Phase 0 mapping / self-audit / sibling visual contract / user design ask 这些 process rules 对**两条 path 都适用**，应共享 `design-process.md`。

### 关键 design decisions（已确认）

- ✅ **G1 暂停产新规则** — 本重构期间只整理 / 合并 / 拆分，**不新增 hard rule**
- ✅ **G2 架构方向**：phase-gated single-agent default + opt-in dispatch agent；**不**做 mandatory pipeline
- ✅ **F4 默认决策**：不做 PM agent（用户=PM，AI 替代 = anti-pattern）+ 不做全 pipeline

### 外部依赖（noted，不在本 prompt scope）

- ⏳ **B1** industry benchmark $0.008 灰色参考线 — 需调研真 benchmark 数
- ⏳ **B2** Option 3 sidebar 加 "Out-of-scope / Next phase" 注释卡 — 消费产品 Figma 改动，**不在 TVU repo scope**
- ⏳ **G3** Saved $ baseline 定义 — Finance/PM 拍板
- ⏳ **G4** 真实数据接入 — backend

---

## 总目标（最终态）

```
docs/internal/
  design-process.md            ← 通用 process 原则（path-agnostic, voice-neutral）
  domain-tvu.md                ← TVU 业务规则（红=Live / Monitoring dark / etc.）
  tools/figma-quirks.md        ← Figma API quirks reference table
  tools/code-stack-quirks.md   ← 代码栈 quirks（按需，可暂不建）
  mockup-conventions.md        ← THIN 入口 + Path A specific 段
  code-conventions.md          ← THIN 入口 + Path B specific 段

~/.claude/skills/
  design-discovery/SKILL.md    ← pre-design 用户研究 skill（C3）

~/.claude/agents/
  design-walkthrough.md        ← F1 设计走查
  persona-simulation.md        ← F2 persona 模拟
  product-test.md              ← F3 Path B 测试（按需 defer）
```

---

## 执行计划（dependency-ordered，并行点已标）

```
                                                                                   ┌─→ F3 (按需 defer)
                                                                                   │
Step 1: C (rule edits) ──→ Step 2: D (organize) ──→ Step 3: E (split) ──→ Step 4: F1 ──→ Step 5: F2
   ║                          ║                        ║                       ║              ║
   ║parallel:                 ║parallel: D1‖D2         ║parallel: E1‖E2‖E3     ║独立           ║独立
   ║ C1‖C2‖C3‖C4              ║sequential: D3 last     ║sequential: E5,E6     ║              ║
```

### 自然 commit 断点（每个 Step 完成后 STOP 等审 → 1 commit + 1 复盘）

| Step | Commit message | Retrospect file |
|---|---|---|
| Step 1 完成 | `docs(rules): Step 1 — C 规则修订 + design-discovery skill + meta-rule` | `<date>-evolution-step-1.md` |
| Step 2 完成 | `docs(rules): Step 2 — D 内部合并 + section 重组 + figma-technical-reference` | `<date>-evolution-step-2.md` |
| Step 3 完成 | `docs(arch): Step 3 — E 文件架构拆分 (design-process / domain-tvu / tools/figma-quirks)` | `<date>-evolution-step-3.md` |
| Step 4 完成 | `docs(agents): Step 4 — F1 design-walkthrough agent + dogfood` | `<date>-evolution-step-4.md` |
| Step 5 完成 | `docs(agents): Step 5 — F2 persona-simulation agent + dogfood` | `<date>-evolution-step-5.md` |

**Step 之间用户必审一次**——避免一坨乱改无回头路。**但每个 Step 内部一次性做完，不分小步 commit**。

---

## Step 1 — C series（rule edits，parallelizable）

> **执行模式**：C1/C2/C3/C4 互不依赖，**可并行**。完成全部 4 项后 STOP。

### C1 — `mockup-conventions.md` 修订 M16（评估 + 按需 override）

**现版问题**："任何库组件 instance 后**必须**改 placeholder text / icon swap / variant property" 太硬。反模式实际是"未评估直接交付 placeholder 当真实内容"，不是"未改即违规"。

**修正版措辞**（直接替换 M16 段全文）：

```markdown
### M16 — Library 组件 instance 默认值必须评估，不可直接用 placeholder 当真实内容

库 default placeholder = 预览用占位（如 dropdown 默认 "Option 1/2/3"、Button 占位 
text "Button"、空 icon 占位、Tab/square 默认多余 tab 等）。

#### Instance 后必做（不是必改）

评估每项 default（placeholder text / 默认 icon / variant property）：
- 默认值**符合**当前需求 → **可保留**
- 默认值**不符**需求 → **必须 override**

#### 反模式（违规）

拖出来**不评估**、直接交付 placeholder 当真实内容。

#### 反例

- dropdown 默认 "Option 1/2/3" 没评估直接交 → ❌
- icon-only Button 默认占位 chevron 不换成具体 action icon → ❌
- Tab/square 默认 10 tab，需求只 2 个，不删多余 → ❌
- Tooltip 文字 "Hint" 演示场景符合需求，**保留** → ✅
- Switch on/off 默认就是需求 → ✅

#### Why

区分 **"未改"（可能合理）** 和 **"未评估"（始终不合理）**。一刀切"必须改"会引出
本不必要的 override，instance 失去 library 同步意义。
```

### C2 — `mockup-conventions.md` 强化 M14（加 generic context 维度表）

**背景**：之前 session 发现 sub_nav "Back" 不该照抄（reference 是二级 page，新页是一级 dashboard）—— IA level mismatch。本质是 **generic context-bound element** 问题，**不在 M21 加 specific IA probe 行**，而在 M14 "复刻原 mockup 任一元素前必问适配性" 加 generic context 维度表。

**新增段落**（追加到 M14 已有内容之后）：

```markdown
#### M14 加强 — Context 维度检查（generic 表）

复刻 element 前**必问该 element 在 reference 中 attach 到什么 context**：

| Context 维度 | Probe 方法 | Mismatch → |
|---|---|---|
| **IA level**（一级 / N 级 page）| top bar active menu / sub-nav 是否含父级返回 | 级别绑定 element 不 mirror |
| **Persona**（reference 服务谁 / new page 服务谁）| reference 的 user story → 实际 target persona | persona 不匹配的 element 重判 |
| **时间窗 / 业务状态**（live / draft / archived）| reference 的 state 标识 / status badge | state-bound element 重判 |
| **设备 / 断点**（desktop 1920 / 1440 / mobile）| reference 帧宽 + responsive variant | 断点不同的 element 重设计，不 scale-copy |
| **语言 / 本地化** | reference 的语言版本 | 文案长度差异元素重布局 |

Mismatch → 重判该 element，**不照抄**。任何**未来出现的级别绑定 element**（面包屑 / drill-down hint / 父级面板 / 等）都被此 generic 维度自然覆盖，**不需要逐个加进规则**（举一反三）。

#### 反例（2026-05-12 SaaS Dashboard sub_nav back）

参考是 "Product Usage Dashboard" 下的二级 view（含父级返回），新页是新加一级 dashboard 
本体 → IA mismatch → 父级返回元素不 mirror。M14 IA 维度漏 probe → 照抄 back navigation。
```

### C3 — 新建 `design-discovery` skill

**新建文件**：`~/.claude/skills/design-discovery/SKILL.md`

```markdown
---
name: design-discovery
description: Pre-design 用户研究 + 市场分析。触发：新 feature / 新 persona / 重大重设计。
            产出 5 项 deliverable + pain-to-feature mapping + MVP scope 声明，
            喂给 Pre-Phase 0 / M0 阶段。
---

# Design Discovery 起手协议

## 1. 判断是否触发
AI 复述 user 的 design ask，**先问**："这个 task 需要 discovery 吗？"
- ✅ 触发：新 feature / 新 persona / 重大 redesign / "design proposal" 类 ask
- ❌ 不触发：bug fix / copy 改 / 已有 element 微调

不触发 → 跳过本 skill，直接进 Pre-Phase 0 / M0。

## 2. 5 项 deliverable（必产）

### Personas (3-5)
| Persona | 业务角色 | 频率 | 技术深度 | 主要决策 |
|---|---|---|---|---|

### Use scenarios (5+)
列 "谁 在什么时候 / 什么场景 / 什么目的 用"

### Pain points (5+, ranked)
按严重度 × 频率 排序

### User stories (5+ "As X I want Y so Z" 格式)

### Market / Competitive analysis (3+ 同类产品)
| 产品 | 强项 | 弱项 → 我们差异化机会 |
|---|---|---|

## 3. 后置 deliverable
- **Pain → Feature mapping**：每 pain 哪 feature 解 / 不解 / next phase 解
- **MVP scope 声明**：当前设计服务哪些 persona / pain，缓哪些到 next phase

## 4. Gate
全部 deliverable → user 校 → 进 Pre-Phase 0 / M0。

## 5. 跳过 → 落复盘
若用户选择跳过 discovery，retrospect 必须 record 跳过决策。
```

### C4 — `meta-rules.md` 加规则写作元规则

**新增段落到 `meta-rules.md` 反模式清单**：

```markdown
### 反模式 — 规则正文枚举特例

#### 现象
规则正文里列具体 case：
- "增 alerts 页时把 dashboard 已有的 status badge 重新从 library import → ❌"
- "sub_nav back / breadcrumb / drill-down 元素不 mirror"
- "dropdown 默认 'Option 1/2/3' 没改就交 → ❌"

#### Why 错
- 规则正文 = generic 原则的位置；枚举特例使规则与产品强绑定
- 未来出现新 element 类型就要追加规则 → 规则数量线性增长
- 违反"举一反三"——AI 该从原则推导特例，不是 lookup 特例

#### 修正

| 位置 | 该写什么 |
|---|---|
| **规则正文** | generic 原则；per-case 判断委派 upstream 规则 |
| **probe 表** | 维度 + how-to-probe + 输出格式（不枚举 element） |
| **反例段** | 具体产品 case 可特例化 |
| **决策树** | abstract input → abstract output |

#### 自查
新增 / 修订规则时，问："这是 generic 原则还是 specific case？case 该写在反例段，原则写在 rule body。"
```

### Step 1 结束

完成 C1+C2+C3+C4 后 → **STOP** → 列改动 → 等用户审 → 1 commit。

---

## Step 2 — D series（organize，after C）

> **执行模式**：D1‖D2 可并行；D3 在 D1+D2 之后（section header 需基于最终 rule 状态分组）。

### D1 — `mockup-conventions.md` 合并 M11+M12+M13 → 单条 "M11 Self-audit discipline"

3 条都是"自查方法论"，合并成 **M11 Self-audit discipline** 3 个 sub-section：
- **M11.1** Probe-based 自查（原 M11 4 步法）
- **M11.2** 截图 literacy（原 M12）
- **M11.3** Inverse-question 视觉元素（原 M13）

**Cross-ref 替换**：grep `\bM11\b\|\bM12\b\|\bM13\b` in retrospects + prompts + 其它规则，更新到 `M11.1` / `M11.2` / `M11.3`。

### D2 — M17-M20 移出 → 新文件 `figma-technical-reference.md`

M17（1px 节点查 fills）/ M18（绑变量 + opacity 两步）/ M19（Master force-sync）/ M20（Column 宽度策略）—— Figma API 边角，**不是设计原则**。

移到 `docs/internal/figma-technical-reference.md`，按 quirk type 分类，做成 lookup table。

`mockup-conventions.md` 留 1 句指针 "Figma API quirks → see `figma-technical-reference.md`"。

### D3 — `mockup-conventions.md` 内部 section header（在 D1+D2 之后）

不动顺序、不动内容，加 3 级 section header：

```
## Process Rules (path-agnostic, applies to any product)
  M0 / M2 / M6 / M11 / M14 / M15 / M16 / M21 / M22

## TVU Business Domain Rules (TVU-specific)
  M1 / M3 / M4 / M5 / M7 / M8 / M9 / M10

## Figma Tool Quirks Reference
  → figma-technical-reference.md
```

### Step 2 结束

完成 D1+D2+D3 后 → **STOP** → 列改动 → 等用户审 → 1 commit。

---

## Step 3 — E series（split，after D）

> **执行模式**：E1‖E2‖E3 可并行（创建 3 个新文件）；E5 在 E1-E3 之后（thin entry 引用新文件）；E6 最后（cross-ref 更新到新结构）。E4 按需，可暂不建。

### E1‖E2‖E3 — 创建新文件（并行）

| # | 新文件 | 内容来源 | Path-agnostic 重写 |
|---|---|---|---|
| **E1** | `design-process.md` | mockup `## Process Rules` (Step 2 D3 整理出来) + code `R0/R3/R6` | **必做** voice-neutral 措辞：不说 "画"也不说 "写"，说 "生成 deliverable" |
| **E2** | `domain-tvu.md` | mockup `## TVU Business Domain Rules` | 业务规则本就 path-agnostic |
| **E3** | `tools/figma-quirks.md` | M17-M20（Step 2 D2 已迁，确认 stable）| Path A only |
| ~~E4~~ | ~~`tools/code-stack-quirks.md`~~ | ~~待生 — 当前无~~ | **defer**，按需建 |

### E5 — mockup / code-conventions.md 改 thin（在 E1-E3 之后）

`mockup-conventions.md`:
- 入口：项目说明 + 必读链路
- Path A specific 段：Figma 任务专属内容
- 引用：design-process.md（generic）+ domain-tvu.md（business）+ tools/figma-quirks.md（tool）

`code-conventions.md`:
- 入口：项目说明 + 必读链路
- Path B specific 段：代码生成专属内容
- 引用：design-process.md + domain-tvu.md + tools/code-stack-quirks.md（按需）

### E6 — 更新所有 retrospect cross-ref（最后）

grep retrospects 里 `mockup-conventions.md#M11` 等 → 改成 `design-process.md#m11`（或 stable URL）。

确认 0 broken link。

### Step 3 结束

完成 E1+E2+E3+E5+E6 后 → **STOP** → 列改动 → 等用户审 → 1 commit。

**验收**：新 AI session 上手**只读 `design-process.md` + `domain-tvu.md`**（~10 条规则）就能跑 80% 决策。

---

## Step 4 — F1 设计走查 agent（after E）

**File**: `~/.claude/agents/design-walkthrough.md`

**Inputs**: design deliverable（mockup node-id / code path）+ PRD + discovery output（若有）+ 适用规则集

**Output**: 结构化 walkthrough report

```
1. Sibling Visual Contract 一致性（M21 check）
2. PRD 覆盖率
3. User Story 覆盖率
4. 规则 Compliance（M14 / M16 / M21 / M22 / M11 self-audit 等）
5. Anti-pattern Scan（meta-rules.md）
6. 数据可行性 Audit（若 design 含 derived value）
7. 推荐 next-step actions
```

**Tools**: Figma MCP（Path A）/ Read / Bash

**触发**: `design walkthrough` / `走查这个设计`

**Validation (dogfood)**: 用 SaaS Dashboard `node-id=1780:93` Option 3 跑 walkthrough，report 结构清晰 + 实际 catch issue。

### Step 4 结束

完成 F1 file + dogfood 后 → **STOP** → 列改动 → 等用户审 → 1 commit。

---

## Step 5 — F2 Persona Simulation agent（after F1）

**File**: `~/.claude/agents/persona-simulation.md`

**Inputs**: design + personas list（来自 design-discovery skill 输出）

**Output**: per-persona reaction simulation
```
# Persona 1: CFO
- 第一眼关注 / 心里问的问题 / design 答了几个 / 关心痛点是否被解 / 改进建议
# Persona 2: SRE
...
```

**Validation (dogfood)**: 用 SaaS Dashboard Option 3 模拟 CFO + PM + SRE 3 个 persona 反应。

### Step 5 结束

完成 F2 file + dogfood 后 → **STOP** → 列改动 → 等用户审 → 1 commit。

---

## F3 Product Test agent — **defer 到 v0.4+**

按 Path B Code task 累积量决定何时建。当前不在本 unified plan scope。

---

## 反模式避免（全 Step 通用，执行时自查）

- ❌ 把消费产品 specific case 写进 generic 规则正文（违 C4 元规则）
- ❌ 加新 hard rule（G1 重构期暂停产新）
- ❌ Path-biased 措辞（"画 mockup 前..." / "写代码前..."）
- ❌ 把 Figma API quirks 当 design rule
- ❌ 删除规则不更新 retrospect cross-ref → broken link
- ❌ 建 PM agent / 全 pipeline mandatory dispatch
- ❌ Agent 产新 rules（agent 是 rule consumer，不是 producer）
- ❌ Step 内拆小步 commit（每 Step 1 commit）
- ❌ **未经用户审批就 commit / push**

---

## 提交协议（**严格遵守**）

**每个 Step 完成后**：
1. **STOP**，列改动 + 未解决项给用户
2. **不自行 commit / push** —— 等用户明确说"commit 这批"才提交
3. 一次 commit 内只包含该 Step 的改动 + 对应复盘文件
4. **Push 前再确认**——用户没说 push 就不 push

---

## Quick-start prompt（粘贴给新 session）

```
请按 docs/internal/_prompts/design-process-evolution.prompt.md 执行 unified 重构。

按 Step 1 → Step 2 → Step 3 → Step 4 → Step 5 顺序，每个 Step 内部按 prompt 标的
并行 / 串行规则执行。每 Step 完成 STOP 等用户审，不要自行 commit / push。

Constraints:
- 只 update TVU repo + ~/.claude/skills/design-discovery/ + ~/.claude/agents/
- 不碰消费产品 docs / Figma
- 不加新 hard rule
- Path-agnostic 措辞（voice-neutral）
- 每 Step 1 commit（用户审完后）
```