The "living documentation" mechanism of the Remotion workbench. Goals:The rule docs evolve along with every session, without relying on people remembering to change them. Learn one thing → route it to the correct source-of-truth file → write it back → keep the entire routing chain consistent.
⚠️ This is not a retrospective / QA (that checks "did we do it right or not"). This isevolution: distilling "what was learned" into "the starting point for next time", so the videos get better and better. ⚠️ Nor does it replace official verification or hard rules—it is only responsible for "changing the rules themselves correctly, completely, and in the right place".
When it triggers
- Manual: the user says "evolve / update the docs / write back the rules / write what we learned this time into the rules".
- Automatic: the wrap-up "documentation evolution gate" hook (
.claude/hooks/evolve-on-stop.mjs, at Stop time; partnerrecord-evolve-touch.mjsrecords this round's changes) detects that this round touched shot/final-cut code while the rule docs were untouched → blocks once to remind you to run this skill, and lets you wrap up on the next attempt. - Proactive: when "corrections / new decisions / new techniques / old rules overturned" appear in the conversation, proactively propose running it once.
Iron rules (remember these first, then act)
- Never change docs silently. Always produce a diff proposal first, grouped by file, explaining clearly "why write this file", andonly write after the user approves. The rule docs are your constitution.
- Single source of truth. Each fact is written in full in only one source of truth; elsewhere only pointers are placed.Copying the same rule into multiple files is forbidden—when duplication is found, merge it and leave a pointer.
- CLAUDE.md is a router, not a warehouse. Specific rules go into the corresponding source-of-truth file; CLAUDE.md keeps only one line pointing there; do not pile content into the body of CLAUDE.md.
- Changing visual values goes through the single source of truth. Visual [values] (color / font size / motion tokens) are changed in
kit/theme.ts(or the generator you built for it); do not inline hardcoded color values all over the components. - Moving a rule requires updating pointers. When a rule moves from file A to file B, all routing lines pointing to it must be changed in sync; do not leave broken links.
Execution division of labor (preventing context pollution)
The main conversation does only two things: ① collect signals (gather them from this session's conversation/diff, compress into a brief—only the main conversation knows what happened this round); ② follow iron rule 1 to present a proposal to the user and get approval. After approval, dispatch a subagent to execute(general-purpose; feed it the brief + the routing table below + the target file paths): read the source of truth → consistency deduplication (step 3 of 4) → write back → record the history → return a diff summary, and the main conversation just relays it. Why: routing/deduplication requires reading a large number of source-of-truth files; doing it all in the main conversation would eat up the main context; the subagent burns its own window, and the main conversation keeps only the conclusions. BoundariesThe approval step must not be delegated — subagents cannot converse with the user, and "write only after user approval" must happen in the main conversation; subagents only execute already-approved content, and discoveries beyond the proposal's scope are brought back to the main conversation for further discussion.
Routing chain map (anchor = repo root)
CLAUDE.md 根路由 + 三层真源索引
kit/CLAUDE.md 共享层(kit)索引 + 组件晋升规则
template/CLAUDE.md 出片层(各工程自己的禁区)
docs/HARD_RULES.md 工程红线唯一真源(frame 驱动 / clamp / 确定性 / public…)
Evolution in four steps
1. Collect (find evolution signals)
From this session's conversation + git diff / git log(the projects touched) fish out:
- Corrections: the user said "that's wrong / I never said that / it should be X / you misunderstood".
- New decisions: a new practice / new default / new boundary was set.
- New techniques / new capabilities: a useful technique was created that will repeat across pieces, or some engine usage was verified (3D / anime / native weapons…).
- Old rules overturned / outdated descriptions: the docs say X, but reality or the code is Y.
- Creation vs reuse events: was this truly created, or reflexively reused again? (builds the ledger for the "creative-stance gate")
2. Classify + route (check the routing table)
Each signal lands in exactly one source of truth:
| What was learned | Which source of truth to write it into (anchor = repo root) | CLAUDE.md |
|---|---|---|
| Operational discipline / process | Corresponding layer CLAUDE.md main text (root / kit / output layer) |
It is itself |
| Pitfalls / framework red lines / battle scars | docs/HARD_RULES.md |
Leave a pointer |
| Visual [values] (color / font size / motion tokens) | kit/theme.ts(or a generator you build) |
— |
| Visual intent / composition / color semantics | Your own design specification (not included in this repo; recommended to build your own) | Leave a pointer |
| Motion techniques / rhythm / spring feel | Your own motion notes (not included in this repo; recommended to build your own) | Leave a pointer |
| Engine capabilities / usage (3D · anime · native weapons) | Your own engine notes (not included in this repo; recommended to build your own) | Leave a pointer |
| Creative stance (creation vs reuse judgment) | .claude/skills/cyxj-remotion-overlay/SKILL.md |
— |
If you can't tell where it goes → ask the user, don't force it in. One signal may need to land in two places (write it fully in the source of truth + leave a pointer in the upper layer), butthe content exists only in that one copy in the source of truth。
The author's complete source-of-truth system also includes many other files such as the design specification / motion notes / engine capability manual / subtitling and post-production SOP / evolution archive (private accumulation,not included in this repo). The table above marks them as "recommended to build your own" — use the same "single source of truth + leave a pointer" mechanism to accumulate your own.
3. Consistency check (mandatory before writing)
- In the target source of truth,is there already a similar entry written? If yes → merge / rewrite, do not add a duplicate.
- Was this rule originally in another file? If yes → this is a "move": delete the old location + update all pointers that point to it.
- After writing, is the routing chainstill connected? (the files / sections pointed to by pointers in CLAUDE.md actually exist)
4. Proposal → approval → write
- Group diff proposals by file, each group accompanied by one sentence on "why this file".
- Write only after the user approves.
Run the self-check
- Have you piled content into the CLAUDE.md main text (it should go into the source of truth + leave a pointer)?
- Is there duplicate creation (the same message fully written in two files)?
- Is there inline hard-coded color value in the component (which should have been changed to
kit/theme.ts)?