cyxj-remotion-evolve(文档进化引擎)
Remotion 工作台的"活文档"机制。目标:规则文档每次都跟着进化,不靠人记得改。 学到一条东西 → 路由到正确的真源文件 → 回写 → 保持整条路由链一致。
⚠️ 这不是复盘 / QA(那是查"做对没做对")。这是进化:把"学到的"沉淀成"下次的起点",让视频越做越好。
⚠️ 也不替代官方核查或硬规则——它只负责"把规则本身改对、改全、放对地方"。
什么时候触发
- 手动:用户说"进化 / 更新文档 / 回写规则 / 把这次学到的写进规则"。
- 自动:收工"文档进化闸"hook(
.claude/hooks/evolve-on-stop.mjs,Stop 时机;搭档 record-evolve-touch.mjs 记本轮改动)检测到本轮动过镜头/出片代码而规则文档未动 → 拦一次提醒跑本 skill,再次收工放行。
- 主动:对话里出现"纠正 / 新决策 / 新手法 / 旧规则被推翻"时,主动提议跑一次。
铁律(先记住,再动手)
- 绝不静默改文档。 一律先出 diff 提案、按文件分组、说清"为什么写这个文件"、用户批准才写。规则文档是你的宪法。
- 单一真源。 每条事实只在一个真源里写全,别处只放指针。禁止把同一条规则复制进多个文件——发现重复要合并、留指针。
- CLAUDE.md 是路由器,不是仓库。 具体规则进对应真源文件,CLAUDE.md 只留一行指过去;不要把内容堆进 CLAUDE.md 正文。
- 改视觉值走单一真源。 视觉【值】(色 / 字号 / 动效 token)改
kit/theme.ts(或你为它建的生成器),别在组件里到处内联硬编码色值。
- 移动规则要补指针。 一条规则从 A 文件挪到 B 文件,必须同步改掉所有指向它的路由行,别留断链。
执行分工(防上下文污染)
主对话只做两件事:① 采集信号(从本会话对话/diff 里捞,压缩成一段简报——只有主对话知道这轮发生了什么);② 按铁律 1 向用户出提案、拿批准。
批准后派子代理执行(general-purpose,把简报 + 下方路由表 + 目标文件路径喂给它):读真源 → 一致性查重(四步之3)→ 回写 → 记沿革 → 返回 diff 摘要,主对话转达即可。
为什么:路由/查重要读大量真源文件,全在主对话做会吃掉主上下文;子代理烧自己的窗口,主对话只留结论。
边界:批准环节不许下放——子代理不能与用户对话,「用户批准才写」必须发生在主对话;子代理只执行已批准的内容,超出提案范围的发现带回主对话再议。
路由链地图(锚点 = 仓库根)
CLAUDE.md 根路由 + 三层真源索引
kit/CLAUDE.md 共享层(kit)索引 + 组件晋升规则
template/CLAUDE.md 出片层(各工程自己的禁区)
docs/HARD_RULES.md 工程红线唯一真源(frame 驱动 / clamp / 确定性 / public…)
进化四步
1. 采集(找进化信号)
从本会话对话 + git diff / git log(动过的工程)里捞:
- 纠正:用户说过"不对 / 我没说过 / 应该是 X / 你理解错了"。
- 新决策:定了新做法 / 新默认 / 新边界。
- 新手法 / 新能力:造出了好用且会跨片重复的手法,或验证了某引擎用法(3D / anime / 原生武器…)。
- 旧规则被推翻 / 过时描述:文档说 X,现实或代码是 Y。
- 创造 vs 复用事件:这次是真创造,还是又反射式复用了?(给"创作姿态闸"攒账)
2. 分类 + 路由(查路由表)
每条信号落到唯一真源:
| 学到什么 |
写进哪个真源(锚点 = 仓库根) |
CLAUDE.md |
| 操作纪律 / 流程 |
对应层 CLAUDE.md 正文(根 / kit / 出片层) |
它本身就是 |
| 踩坑 / 框架红线 / 战疤 |
docs/HARD_RULES.md |
留指针 |
| 视觉【值】(色 / 字号 / 动效 token) |
kit/theme.ts(或你建的生成器) |
— |
| 视觉意图 / 构图 / 色彩语义 |
你自己的设计说明书(本仓不含,建议自建) |
留指针 |
| 动效手法 / 节奏 / spring 手感 |
你自己的动效笔记(本仓不含,建议自建) |
留指针 |
| 引擎能力 / 用法(3D·anime·原生武器) |
你自己的引擎笔记(本仓不含,建议自建) |
留指针 |
| 创作姿态(创造 vs 复用判断) |
.claude/skills/cyxj-remotion-overlay/SKILL.md |
— |
判不准放哪 → 问用户,别硬塞。一条信号可能要落两处(真源写全 + 上层留指针),但内容只在真源那一份。
作者的完整真源体系还有设计说明书 / 动效笔记 / 引擎能力手册 / 字幕与后期 SOP / 沿革档案等多份文件(私有沉淀,本仓不含)。上表把它们标成"建议自建"——按同样的"单一真源 + 留指针"机制沉淀你自己的。
3. 一致性检查(写之前必做)
- 目标真源里有没有已经写过的相近条目?有 → 合并 / 改写,不新增重复。
- 这条规则原来在别的文件吗?是 → 这是"移动":删旧处 + 改所有指向它的指针。
- 写完后路由链还连得上吗?(CLAUDE.md 里的指针指向的文件 / 小节真实存在)
4. 提案 → 批准 → 写
- 按文件分组出 diff 提案,每组配一句"为什么是这个文件"。
- 用户批准后才写入。
跑完自检
1---2name: cyxj-remotion-evolve3description: Remotion 文档进化引擎。把一次制作 / 对话里学到的东西(纠正、新决策、新手法、被推翻的旧规则、过时描述)路由到正确的真源文件并回写,保持路由链单一真源、指针不断、不重复。用户说"进化 / 更新文档 / 把这次学到的写进规则 / 回写规则 / 文档该改了"时使用。这不是复盘 QA,是让规则越长越准、视频越做越好的活文档机制。4---56# cyxj-remotion-evolve(文档进化引擎)78Remotion 工作台的"活文档"机制。目标:**规则文档每次都跟着进化,不靠人记得改。** 学到一条东西 → 路由到正确的真源文件 → 回写 → 保持整条路由链一致。910> ⚠️ 这不是复盘 / QA(那是查"做对没做对")。这是**进化**:把"学到的"沉淀成"下次的起点",让视频越做越好。11> ⚠️ 也不替代官方核查或硬规则——它只负责"把规则本身改对、改全、放对地方"。1213## 什么时候触发1415- **手动**:用户说"进化 / 更新文档 / 回写规则 / 把这次学到的写进规则"。16- **自动**:收工"文档进化闸"hook(`.claude/hooks/evolve-on-stop.mjs`,Stop 时机;搭档 `record-evolve-touch.mjs` 记本轮改动)检测到本轮动过镜头/出片代码而规则文档未动 → 拦一次提醒跑本 skill,再次收工放行。17- **主动**:对话里出现"纠正 / 新决策 / 新手法 / 旧规则被推翻"时,主动提议跑一次。1819## 铁律(先记住,再动手)20211. **绝不静默改文档。** 一律先出 diff 提案、按文件分组、说清"为什么写这个文件"、**用户批准才写**。规则文档是你的宪法。222. **单一真源。** 每条事实只在一个真源里写全,别处只放指针。**禁止把同一条规则复制进多个文件**——发现重复要合并、留指针。233. **CLAUDE.md 是路由器,不是仓库。** 具体规则进对应真源文件,CLAUDE.md 只留一行指过去;不要把内容堆进 CLAUDE.md 正文。244. **改视觉值走单一真源。** 视觉【值】(色 / 字号 / 动效 token)改 `kit/theme.ts`(或你为它建的生成器),别在组件里到处内联硬编码色值。255. **移动规则要补指针。** 一条规则从 A 文件挪到 B 文件,必须同步改掉所有指向它的路由行,别留断链。2627## 执行分工(防上下文污染)2829**主对话只做两件事**:① 采集信号(从本会话对话/diff 里捞,压缩成一段简报——只有主对话知道这轮发生了什么);② 按铁律 1 向用户出提案、拿批准。30**批准后派子代理执行**(general-purpose,把简报 + 下方路由表 + 目标文件路径喂给它):读真源 → 一致性查重(四步之3)→ 回写 → 记沿革 → 返回 diff 摘要,主对话转达即可。31**为什么**:路由/查重要读大量真源文件,全在主对话做会吃掉主上下文;子代理烧自己的窗口,主对话只留结论。32**边界**:批准环节不许下放——子代理不能与用户对话,「用户批准才写」必须发生在主对话;子代理只执行已批准的内容,超出提案范围的发现带回主对话再议。3334## 路由链地图(锚点 = 仓库根)3536```37CLAUDE.md 根路由 + 三层真源索引38kit/CLAUDE.md 共享层(kit)索引 + 组件晋升规则39template/CLAUDE.md 出片层(各工程自己的禁区)40docs/HARD_RULES.md 工程红线唯一真源(frame 驱动 / clamp / 确定性 / public…)41```4243## 进化四步4445### 1. 采集(找进化信号)46从本会话对话 + `git diff` / `git log`(动过的工程)里捞:47- **纠正**:用户说过"不对 / 我没说过 / 应该是 X / 你理解错了"。48- **新决策**:定了新做法 / 新默认 / 新边界。49- **新手法 / 新能力**:造出了好用且会跨片重复的手法,或验证了某引擎用法(3D / anime / 原生武器…)。50- **旧规则被推翻 / 过时描述**:文档说 X,现实或代码是 Y。51- **创造 vs 复用事件**:这次是真创造,还是又反射式复用了?(给"创作姿态闸"攒账)5253### 2. 分类 + 路由(查路由表)54每条信号落到唯一真源:5556| 学到什么 | 写进哪个真源(锚点 = 仓库根) | CLAUDE.md |57|---|---|---|58| 操作纪律 / 流程 | 对应层 `CLAUDE.md` 正文(根 / kit / 出片层) | 它本身就是 |59| 踩坑 / 框架红线 / 战疤 | `docs/HARD_RULES.md` | 留指针 |60| 视觉【值】(色 / 字号 / 动效 token) | `kit/theme.ts`(或你建的生成器) | — |61| 视觉意图 / 构图 / 色彩语义 | 你自己的设计说明书(本仓不含,建议自建) | 留指针 |62| 动效手法 / 节奏 / spring 手感 | 你自己的动效笔记(本仓不含,建议自建) | 留指针 |63| 引擎能力 / 用法(3D·anime·原生武器) | 你自己的引擎笔记(本仓不含,建议自建) | 留指针 |64| **创作姿态(创造 vs 复用判断)** | `.claude/skills/cyxj-remotion-overlay/SKILL.md` | — |6566> 判不准放哪 → 问用户,别硬塞。一条信号可能要落两处(真源写全 + 上层留指针),但**内容只在真源那一份**。67>68> 作者的完整真源体系还有设计说明书 / 动效笔记 / 引擎能力手册 / 字幕与后期 SOP / 沿革档案等多份文件(私有沉淀,**本仓不含**)。上表把它们标成"建议自建"——按同样的"单一真源 + 留指针"机制沉淀你自己的。6970### 3. 一致性检查(写之前必做)71- 目标真源里**有没有已经写过的相近条目**?有 → 合并 / 改写,不新增重复。72- 这条规则原来在别的文件吗?是 → 这是"移动":删旧处 + 改所有指向它的指针。73- 写完后路由链**还连得上吗**?(CLAUDE.md 里的指针指向的文件 / 小节真实存在)7475### 4. 提案 → 批准 → 写76- 按文件分组出 diff 提案,每组配一句"为什么是这个文件"。77- 用户批准后才写入。7879## 跑完自检80- [ ] 有没有把内容堆进了 CLAUDE.md 正文(本该进真源 + 留指针)?81- [ ] 有没有制造重复(同一条话两个文件都写全)?82- [ ] 有没有在组件里内联硬编码色值(本该改 `kit/theme.ts`)?
chenyuxiaojin