# Figma Sync Sprint + 元规则 §触发器 O 立项 — 2026-05-27

> Date: 2026-05-27
> Status: INFRA-F35 sprint shipped (12 commits) + 元规则 §触发器 O codified
> Next: 流程内化 — 下次 sync trigger 触发，AI 跑 `pnpm sync:figma-library --with-extract` 一条命令搞定；每个 sprint 收尾跑 mandatory self-audit

---

## 一句话

User 说"同步 Figma 组件库"我跑了 `sync:extract + sync:normalize` partial subset，留 normalized 层 stale 2 周；user 实证抓出后才发现 3 个 orchestrator 各 cover 不同 1/2 子集、无任何一个全。Sprint 把入口收敛到 `pnpm sync:figma-library --with-extract` (11-step + fail-fast + count verify) 后，user 又两次追问"还有没遗漏 / 完全优化好了吗" — 第一次 audit 抓出 5 issue，第二次抓 4 issue。最终落地 12 commits + 立元规则 **§触发器 O Onboarding 知识 ≠ 实际产品状态（实测优先）** 把"按 spec ship 完即 done" 心智模型机制化拒绝。

---

## 事故时间线

| 时间 | 事件 | commit |
|---|---|---|
| 早晨 | user: "同步 Figma 组件库" | — |
| | AI 跑 sync:extract + sync:normalize 子集 (不全) | `31911264` |
| 中午 | user 实证查 manifest，列 12 个 stale nodeId | — |
| | AI 跑漏的 cleanup + generate:component-tokens + generate:manifest 补齐 | `d8317878` |
| | AI 加 `pnpm sync:full` shell-chain hack 作 patch path | `63673eca` |
| | INFRA-F35 立 entry 待 sprint 独立修 | `03575824` |
| 下午 | user 拍板做 sprint，扩 spec 到 9 项 | `56e3d903` |
| | ① ② 落地 — sync-figma-library.mjs 9-step + count verify | `e959be8d` |
| | ③④⑤⑥⑦⑧+C 落地 — orphan-purge / diff-report / rename / hook bypass / dup / worklist / cleanup | `e8719da9` |
| | 发现 hook signal 1 timing bug，修 | `ac09d59a` |
| 傍晚 | user: "现在的同步流程已经完全优化好了吗？再自查一下" | — |
| | AI 跑 self-audit 抓 5 issue (P0 #1/#2 + P1 #3/#5 + P2 #9) | `3ee73da1` |
| | user: "P1#4 + P2#6/#7/#8 也继续吧" | — |
| | 4 项 polish + 1 latent bug | `6ba08562` |
| 晚上 | Sprint Self-Audit 协议入 AGENTS.md | `e6d5487c` |
| | user pull from Gitea (parallel session 加 M21.2) | `3ae24758` |
| | 元规则 §触发器 O 入 meta-rules.md | `548f9250` |

总计：12 commits across ~1 working day。

---

## 根因三层

### 1. 工具层 — 三个 orchestrator 各 cover 不同子集，无任何一个全

| 步骤 | `sync:figma-library` (原) | `sync:full` (hack) | `pnpm generate` (sync.mjs) |
|---|:-:|:-:|:-:|
| extract / cleanup --apply / normalize-vars | 🟡/🟡/❌ | ✅/✅/✅ | ❌/❌/✅ |
| component-tokens / manifest | **❌/❌** | ✅/✅ | ✅/✅ |
| audit chain | ✅ 5 个 | ❌ | ❌ |
| **覆盖率** | ~50% | ~50% | ~40% |

凭印象跑必漏。修法：把 sync:figma-library 升级为唯一 entry，9 step + fail-fast。

### 2. 心智层 — "按 spec ship 完即 done" 默认 trust spec 心智模型，没实测边界

每次 user 追问 audit 都抓出真问题 — spec 自己有盲点 / 实现引入新 bug / doc 没跟更。这不是态度问题是机制问题：sprint shipped 后没机制触发"再实测"。

修法：AGENTS.md §Sprint 收尾 Self-Audit 协议 mandatory 跑 3 类扫描（spec gap / 实现 bug / doc lag），user 询问前主动暴露 finding。

### 3. 元层 — Onboarding 知识 ≠ 实际产品状态

把 sync 事故的根因抽象到顶 — AI onboarding 读 spec / 文档 / memory 构造心智模型，但模型与实际产品状态可能 intentional diverge / 已 stale。Default trust 模型 → 命中错误概率几十%。

这天同时发生的两件事都符合这个 pattern：
- **PMPP-955** (parallel session, M21.2 立项)：onboarding 读 TVU DS → 用 `#30B54E` (DS 绿) 作 US-3 accent → 产品实际 `#5DC045` → 返工
- **INFRA-F35 sprint shipped**：spec 写 "cleanup --apply 默认 ON" → 实现没考虑各 mode 边界 → user audit 抓出

修法：meta-rules.md §触发器 O 把"实测优先 / 产品真值优先"机制化。

---

## 落地清单

### 工具层

| 落地 | 入口 / 文件 |
|---|---|
| 11-step canonical pipeline | `pnpm sync:figma-library --with-extract` |
| fail-fast (Step 0-9 阻塞 / 10-11 非阻塞) | `figma-sync/sync-figma-library.mjs` |
| count + set 一致性 verify (Step 9) | 同上 |
| orphan-purge + rename safeguard | `figma-sync/normalize-component-tokens.mjs` |
| sync diff report (folds schema noise) | `figma-sync/sync-diff-report.mjs` (新) |
| Exact + Fuzzy dup detection | `figma-sync/cleanup-unpublished.mjs` |
| pre-commit hook sync-commit whitelist | `.husky/pre-commit` |
| cleanup --apply conditional default (无 extract = dry 安全) | `figma-sync/sync-figma-library.mjs` |
| `sync:full` 已 retire | `package.json` |

### 协作流程层

| 落地 | 文件 |
|---|---|
| §Sprint 收尾 Self-Audit 协议 (mandatory) | `AGENTS.md` |
| §唤醒词 "同步 Figma 库" 段重写 | `AGENTS.md` |

### 元规则层

| 落地 | 文件 |
|---|---|
| §触发器 O Onboarding 知识 ≠ 实际产品状态 | `docs/meta-rules.md` |
| 实证案例 2 行加入元规则附录 | 同上 |
| §M21.2 Feature Iteration Color Contract (颜色专项子规则，parallel session 立) | `docs/internal/design-process.md` |

---

## 教训

### 教训 1 — "Spec shipped" ≠ "Task done"

之前我会 sprint shipped 后报 "done" 等 user 验收。本次 user 两次连环 audit 抓出 9 个真问题（5 + 4），证明这种 hand-off 模式让 user 承担 reviewer 责任。

**机制化**：AGENTS.md §Sprint 收尾 Self-Audit 协议把 "sprint shipped 后跑 audit" 写入 mandatory 流程。下次任何 sprint 我会在 commit/push 完成的同时主动跑 3 类扫描，user 询问 audit 之前就把 finding 端出来。

### 教训 2 — Memory 不是项目契约的家

立 Self-Audit 协议时第一反应写 memory，user 反问"其他同事怎么办？为什么不做到 TVU 设计系统的固有流程里面？" — 一句话点中 memory 是 Claude Code 个人 cache，同事 / 别 AI 工具 / CI 都读不到。

**机制化**：memory `feedback_memory-scope.md` 加"写 memory 前 3-问自检"：
1. 只是我 / 一个 AI 工具的行为约束？→ memory OK
2. 团队 / 跨 AI / 跨 session 应共享？→ **进 repo（AGENTS.md / docs）**
3. 中间态？→ memory 薄 pointer + body 指 repo 真源

### 教训 3 — 元规则比规则强

同一天发生 PMPP-955 颜色误用 + INFRA-F35 sync spec 边界漏 — 两件事看起来无关，但抽象到顶层都是"AI default trust onboarding context 作为产品真值"。立元规则 §触发器 O 比立 10 个具体规则更值。

**机制化**：meta-rules.md 已有触发器 I/J/G/M 等 — 现在 O 加入；附录列实证案例（包括 2026-05-26 Calender typo + Figma description "空" 误判 — 同类 absent fallacy 形态）让未来命中类似 case 时能 trace 回元规则。

---

## Artifacts

### Commits

```
548f9250  docs(meta-rules): add 触发器 O — Onboarding 知识 ≠ 实际产品状态（实测优先）
3ae24758  Merge PR #6 — M21.2 Feature Iteration Color Contract (parallel session)
e6d5487c  docs(agents): add §Sprint 收尾 Self-Audit 协议 (mandatory)
6ba08562  feat(figma-sync): INFRA-F35 polish — fuzzy dup / hook signal B / set diff / icons opt-in
3ee73da1  fix(figma-sync): INFRA-F35 self-audit fixes — P0 + P1 #3 #5 + P2 #9
ac09d59a  fix(figma-sync): hook bypass — drop unreliable commit-message signal
e8719da9  feat(figma-sync): INFRA-F35 ③④⑤⑥⑦⑧ + C — complete sync sprint
e959be8d  feat(figma-sync): INFRA-F35 ①② — sync-figma-library 9-step + count verify
56e3d903  docs(backlog): expand INFRA-F35 to full 9-item Figma sync pipeline sprint
03575824  docs(backlog): INFRA-F35 — sync-figma-library orchestrator + orphan-purge fix
63673eca  chore(scripts): add pnpm sync:full as canonical Figma library sync entry point
d8317878  chore(figma-sync): finish sync — cleanup unpublished + regen tokenized+manifest
31911264  chore(figma-sync): sync Figma library to local — 2026-05-27 extract  (← 事故起点)
```

### 新增 npm scripts

- `pnpm sync:diff-report` — 独立跑 sync diff report

### 新增 / 更新文件

| 文件 | 类型 |
|---|---|
| `figma-sync/sync-diff-report.mjs` | 新增 |
| `figma-sync/sync-figma-library.mjs` | 重写 (5 → 11 step + count verify + conditional cleanup) |
| `figma-sync/cleanup-unpublished.mjs` | 加 exact + fuzzy dup detection |
| `figma-sync/normalize-component-tokens.mjs` | 加 orphan-purge + rename safeguard |
| `.husky/pre-commit` | 加 sync-commit whitelist (signal A staged + signal B today's report) |
| `AGENTS.md` | §唤醒词 "同步 Figma 库" 重写 + §Sprint 收尾 Self-Audit 协议 新增 |
| `docs/meta-rules.md` | §触发器 O 新增 + 附录加 2 行 |
| `docs/internal/design-process.md` | §M21.2 (parallel session) |
| `docs/internal/mockup-conventions.md` | US-3 段加 M21.2 cross-ref (parallel session) |
| `docs/internal/cleanup-dup-candidates.md` | 新增 (auto-gen by cleanup) |
| `docs/internal/figma-sync-report-2026-05-27.md` | 新增 (auto-gen by sync:diff-report) |
| `~/.claude/projects/<>/memory/feedback_figma-sync-canonical-sequence.md` | 新增 (薄 pointer) |
| `~/.claude/projects/<>/memory/feedback_sprint-wrapup-self-audit.md` | 新增 (薄 pointer) |
| `~/.claude/projects/<>/memory/feedback_memory-scope.md` | 加反范例段 |

---

## 下一步

不需要做。本次 retrospect 就是 sprint 真正的 closing artifact。下次 user 说"同步 Figma 组件库" → AI 一条命令 `pnpm sync:figma-library --with-extract` 跑完，commit + push 含 today's report → hook 自动放行。sprint commit/push 后 mandatory 跑 §Sprint 收尾 Self-Audit 协议 3 类扫描，主动暴露 finding 给 user。

凡是 onboarding 知识 vs 产品实际状态可能 diverge 的，永远 trust 后者 + 实测获取。