cyxj-remotion-evolve

name	cyxj-remotion-evolve
description	Remotion 文档进化引擎。把一次制作 / 对话里学到的东西(纠正、新决策、新手法、被推翻的旧规则、过时描述)路由到正确的真源文件并回写,保持路由链单一真源、指针不断、不重复。用户说"进化 / 更新文档 / 把这次学到的写进规则 / 回写规则 / 文档该改了"时使用。这不是复盘 QA,是让规则越长越准、视频越做越好的活文档机制。

cyxj-remotion-evolve(文档进化引擎)

Remotion 工作台的"活文档"机制。目标:规则文档每次都跟着进化,不靠人记得改。 学到一条东西 → 路由到正确的真源文件 → 回写 → 保持整条路由链一致。

⚠️ 这不是复盘 / QA(那是查"做对没做对")。这是进化:把"学到的"沉淀成"下次的起点",让视频越做越好。 ⚠️ 也不替代官方核查或硬规则——它只负责"把规则本身改对、改全、放对地方"。

什么时候触发

• 手动:用户说"进化 / 更新文档 / 回写规则 / 把这次学到的写进规则"。
• 自动:收工"文档进化闸"hook(.claude/hooks/evolve-on-stop.mjs,Stop 时机;搭档 record-evolve-touch.mjs 记本轮改动)检测到本轮动过镜头/出片代码而规则文档未动 → 拦一次提醒跑本 skill,再次收工放行。
• 主动:对话里出现"纠正 / 新决策 / 新手法 / 旧规则被推翻"时,主动提议跑一次。

铁律(先记住,再动手)

1. 绝不静默改文档。 一律先出 diff 提案、按文件分组、说清"为什么写这个文件"、用户批准才写。规则文档是你的宪法。
2. 单一真源。 每条事实只在一个真源里写全,别处只放指针。禁止把同一条规则复制进多个文件——发现重复要合并、留指针。
3. CLAUDE.md 是路由器,不是仓库。 具体规则进对应真源文件,CLAUDE.md 只留一行指过去;不要把内容堆进 CLAUDE.md 正文。
4. 改视觉值走单一真源。 视觉【值】(色 / 字号 / 动效 token)改 kit/theme.ts(或你为它建的生成器),别在组件里到处内联硬编码色值。
5. 移动规则要补指针。 一条规则从 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 提案,每组配一句"为什么是这个文件"。
• 用户批准后才写入。

跑完自检

• 有没有把内容堆进了 CLAUDE.md 正文(本该进真源 + 留指针)?
• 有没有制造重复(同一条话两个文件都写全)?
• 有没有在组件里内联硬编码色值(本该改 kit/theme.ts)?