HyperFrames CLAUDE.md 深度解读：AI Agent 协作规范、Skills 体系与构建验证约定

CLAUDE.md 是 HyperFrames（一个"写 HTML、渲染视频"的开源视频渲染框架，项目定位为 Built for agents）面向 AI 编码代理（Claude Code 等）的入口契约文档：它定义了 20 个 agent 技能（skills）的安装与路由方式、技能目录的同步维护规则、bun 工作区的构建测试命令，以及组合（composition）验证流程。读完全文，你可以掌握：如何在 agent 会话中正确安装/更新 HyperFrames 技能、/hyperframes 路由器的分流逻辑、新增技能时必须同步的 5 处"可发现性表面"，以及仓库的提交钩子与确定性渲染约定——这些信息直接决定了 agent 能否稳定地产出可渲染的 HTML 视频组合。

1. CLAUDE.md 在项目中的角色

CLAUDE.md 与根目录的 AGENTS.md 是一对镜像文件：两者开头同为 "Open-source video rendering framework: write HTML, render video"，均包含 Skills、Build & Test、Project Structure、Key Conventions 章节。差异在于分工——CLAUDE.md 携带完整的"工作流 + 领域技能"清单和 Skill 目录维护规则，而 AGENTS.md 只保留工作流列表（不含领域技能小节），供其他遵循 AGENTS.md 约定的 agent 读取。CLAUDE.md 中的 "Skill catalog maintenance" 章节明确要求两处清单"keep them in sync"。

从仓库结构看，这份文档不是泛泛的项目介绍，而是一份可执行的协作协议：它规定的每一条（技能先于代码安装、lint/check 双闸门、bun 而非 pnpm）都能在源码与钩子配置中找到对应的强制点。

2. Skills 体系：20 个 agent 技能及其安装策略

2.1 安装命令与新鲜度

CLAUDE.md 规定：写任何组合代码之前，先安装技能，因为它们"编码了通用文档不覆盖的框架特有模式"，且默认只装核心集（core set）——/hyperframes 路由器会按需安装各创作工作流，只有用户明确要求全量时才装全部 20 个。四条安装命令：

npx hyperframes skills update                         # 默认：安装/刷新核心集，工作流按需安装
npx skills add heygen-com/hyperframes                 # 交互式选择器（仅限终端；非交互且不带 --skill 时安装全部 20 个）
npx skills add heygen-com/hyperframes --all           # 一次装全 20 个——仅在明确要求时
npx skills add heygen-com/hyperframes --skill <name>  # 只装一个（裸名，不带前导斜杠）

文档同时警告一个新鲜度陷阱：skills add 解析的是 skills.sh 注册表的 blob，它可能比 main 滞后数小时，新加的技能可能"稍微落后"；在意新鲜度时优先用 npx hyperframes skills update（它从当前 main 安装）。

源码印证了这一点。packages/cli/src/commands/skills.ts 中，全局安装参数固定携带 --full-depth（强制完整 git clone 仓库 HEAD），注释里写明验证结果：走 blob 约 9 个技能显示"过期"，而 --full-depth 后全部为最新。安装还先探测 npx 与 git 是否存在（上游 skills CLI 依赖 git clone），并在 spawn 时设置 GIT_CLONE_PROTECTION_ACTIVE=0 与 GIT_LFS_SKIP_SMUDGE=1，规避企业环境 Git 钩子与 LFS smudge 导致的克隆失败。

2.2 技能清单与指纹

仓库根目录的 skills-manifest.json 以 source: "heygen-com/hyperframes" 列出全部 20 个技能，每个技能附带一个 16 位十六进制哈希与文件数（如 media-use 153 个文件、hyperframes-animation 121 个文件、embedded-captions 138 个文件）。这个哈希由 packages/cli/src/utils/skillsManifest.ts 中的 hashSkillBundle() 生成：遍历技能目录（SKILL.md + references/ + 脚本等整个目录），文件按相对路径排序、文本文件做 CRLF→LF 归一化、相对路径本身也折叠进 SHA-256——因此内容相等则哈希相等，文件被移动同样会改变指纹。这解释了 CLAUDE.md 所说的"20 个技能"：manifest 与 skills/ 目录逐一对应，且 pre-commit 钩子会在技能目录变化时自动重新生成 manifest（见 lefthook.yml 的 skills-manifest 钩子，执行 packages/cli/scripts/gen-skills-manifest.ts 并重新暂存，保证 skills-manifest.json 永不漂移）。

2.3 核心集 vs 按需集：两级分层

skillsManifest.ts 中的 "Skill tiers" 注释把技能分成两层：

• core（核心层）：/hyperframes 入口路由器，加上每个创作工作流都以兄弟路径（../hyperframes-animation/…）结构性引用的共享领域技能（hyperframes-*、media-use）。init / skills update 会持续保持它们最新。判定逻辑见 isCoreSkill()：名为 hyperframes、以 hyperframes- 开头或名为 media-use 的技能即为核心。离线时回退到固定枚举 FALLBACK_CORE_SKILLS（8 个 hyperframes-* + media-use），并有单元测试将其钉死在 skills/ 目录上防止漂移。
• on-demand（按需层）：面向最终用户的工作流技能（pr-to-video、embedded-captions 等）与可选集成（figma），在其工作流被触发时才安装（hyperframes skills update <name>），避免把整套技能喷到每台跑过 init 的机器上。

skills update 的语义在源码注释中写得很清楚：它保证"请求的名字 + 核心集 + 已安装项"这一小集合被装齐并保持最新，不带名字时绝不扩展现有的部分安装；check 子命令在技能过期时以非零码退出，支撑 agent/CI 的契约 hyperframes skills check || npx hyperframes skills update。

2.4 /hyperframes：入口技能与意图路由

CLAUDE.md 强调 /hyperframes 是入口技能——先读它。它同时扮演三重角色：下方领域技能的能力地图、确认每一个创作 brief 的"意图层"、以及创作工作流的意图路由器。仓库中的 skills/hyperframes/SKILL.md 给出了具体机制：

1. 从项目状态开始：按"Remotion 移植 → 现有项目操作 → 具体编辑 → BRIEF.md 已存在 → 存在 hyperframes.json/STORYBOARD.md → 全新创作"的优先级表逐行匹配，避免重复访谈。
2. 路由表：按 10 级优先级把请求映射到工作流——Remotion 移植 > 幻灯片/路演 > 纯字幕 > 图形叠加 > 音乐驱动 > 短动态图形 > PR 讲解 > 产品/网站展示 > 无捕获讲解 > 其他（/general-video 兜底）。
3. 路由前读取 references/routes/<workflow>.md：每个路由一个小文件，携带"安装前就可读"的输入/输出/触发契约加访谈入口。仓库中 skills/hyperframes/references/routes/ 下正好是 10 个工作流的契约文件（如 pr-to-video.md、embedded-captions.md、general-video.md）。
4. 一次性路由后离开：意图访谈以写出 BRIEF.md 结束，brief 是工作流唯一读取的路由产物。
5. 进入工作流前先安装：npx hyperframes skills update <workflow-name>（裸名，不带 /）；命令失败就报出错误，"不要凭记忆重建工作流"。

3. 技能目录清单：10 个创作工作流 + 9 个领域技能

CLAUDE.md 的"Creation workflows"小节完整列出了 10 个工作流及其输入/输出契约：

工作流	输入 → 输出	要点
/product-launch-video	任意网站 URL（或免捕获模式下的预写脚本/文本 brief）→ 产品发布/宣传视频，或以站点自身捕获画面为主的站点导览	最长约 3 分钟，甜区 30–90 秒
/faceless-explainer	任意文本，无 URL、无网站捕获 → 无人物讲解视频	所有视觉由 LLM 发明（排版/抽象图形/图示/数据可视化）
/pr-to-video	一个 GitHub PR（URL / owner/repo#N / "this PR"）→ 代码变更讲解（changelog / 功能发布 / 修复 / 重构）	是 PR 链接，不是产品网站
/embedded-captions	现有人物出镜视频（MP4）→ 同一素材叠加字幕（逐字 rail + 内嵌高潮，或纯电影式内嵌）	素材本身不动，非 NLE 式剪辑
/talking-head-recut	现有人物出镜/访谈/播客视频（MP4）→ 同一素材 + 与转录同步的设计图形叠加（动态标题、lower-third、数据 callout、pull-quote、侧栏、PiP）	画面在下方原样播放；纯字幕走 /embedded-captions
/motion-graphics	短（通常 <10s）设计驱动的动态图形，动即信息，无旁白：动态字、数字滚动、图表、logo sting、叠加层、动画推文/头条	输出 MP4 或透明叠加；更长/带旁白 → /general-video
/music-to-video	一首音乐（音频文件、取音频的视频、或从 mood brief 生成）→ 节拍同步视频	音乐驱动节奏，用户素材切到同一节拍网格
/slideshow	演示/路演/交互式 deck——离散幻灯片、fragment 渐显、分支、热点导航、演讲者模式	输出是可导航 deck，不是渲染视频
/general-video	其余所有视频创作（标题卡、长品牌片、多场景混剪、静态循环、自定义组合），且是 companion 模式所在地	原 hyperframes 流程：设计 → 规划 → 布局 → 构建 → 验证，任意长度
/remotion-to-hyperframes	现有 Remotion（React）组合 → 移植为 HyperFrames HTML	单向迁移，不是创作

"Domain skills (loaded on demand)"小节列出 9 个原子能力，创作工作流按需组合它们：

• /hyperframes-core — 组合契约：data-* 时间属性、class="clip"、轨道、子组合、变量、框架托管的媒体播放、确定性规则。写组合 HTML 前先读。
• /hyperframes-animation — 全部动画知识：原子运动规则、场景蓝图、转场、运行时适配器（GSAP 为默认，另有 Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU）。
• /hyperframes-keyframes — 跨运行时的 seek 安全关键帧编写（GSAP 时间线、CSS keyframes、Anime.js、WAAPI、FLIP、路径、遮罩、SVG morph/draw、文字拖尾、3D 深度），外加 hyperframes keyframes 诊断。
• /hyperframes-creative — 非动画创意方向：frame.md / design.md 处理、调色板、字体、旁白、节拍规划、音频响应式视觉。
• /media-use — 媒体 OS：把任意媒体需求（BGM、SFX、图片、图标、logo、人声、调色、LUT）解析为冻结的本地文件或可粘贴代码块 + 台账记录；目录缺位时经 TTS/音乐/图像模型生成；转录、字幕、去背景、跨项目复用。
• /hyperframes-audio — 混音已放入组合的音频：voiceover carve（只压占用人声频段的音乐床）、效果链（EQ、压缩、限幅、门限、饱和、delay、混响、chorus、phaser、bitcrush）、自动化包络、子混音总线（<hf-audio-group>）。
• /hyperframes-cli — CLI 开发循环：init、add、lint、check、snapshot、preview、render、publish、doctor、lambda（AWS Lambda 云渲染）。
• /hyperframes-registry — 通过 hyperframes add 安装并接线注册表的 block 与组件，覆盖贡献上游新 block/组件。
• /figma — 导入 Figma 资产、token、组件与 storyboard 分区（REST/CLI）以及 Motion 动画与 shader（MCP），重构为运动。

这些技能的实体文件位于仓库 skills/ 目录（embedded-captions/、media-use/、music-to-video/ 等各含数十到上百文件），与 manifest 一一对应。

4. Skill catalog maintenance：新增技能时的五步同步规则

这是 CLAUDE.md 最具仓库工程特征的一节。新增技能（或实质性改名/转用）时，必须同步更新所有 agent 可发现性表面——"过时的条目会静默杀死可发现性"：

1. 五个清单表面：CLAUDE.md 上文的技能列表、根 AGENTS.md 的工作流列表（只载工作流）、README.md 的 ## Skills 小节、docs/guides/skills.mdx（渲染为文档站的 guides/skills 页）、以及两张压缩同一描述的设置表——docs/prompting/overview.mdx（"One-time setup"）与 docs/quickstart.mdx。这条列表同样是契约变更的同步集：改了 description: 措辞也要推送到每个表面，否则压缩副本会与技能本意相悖。
2. 脚手架模板：packages/cli/src/templates/_shared/CLAUDE.md 与 AGENTS.md——每个 hyperframes init 项目都会写入这两个文件，"那里的过期条目会随 init 直接发给用户"，且两份模板文件必须保持逐字节一致（仓库中确有其目录：packages/cli/src/templates/_shared/）。
3. 路由面：若技能改变了"make a video"请求的路由面，还要更新 skills/hyperframes/SKILL.md 的路由表 + 意图层，以及该工作流自己的路由文件 skills/hyperframes/references/routes/<workflow>.md（一个文件携带路由器的输入/输出/触发契约与访谈入口两半）。旧的 references/workflow-catalog.md 与 references/route-briefs.md 已变为指向 routes/ 的 "moved" 桩——不要编辑它们。
4. 分组镜像：Router / Creation workflows / Domain skills 三分组在所有表面保持一致，技能始终位于同一列。
5. 技能计数："20 AI agent skills" 出现在 README 与 CLAUDE.md 的导语行，增删技能时更新；而 docs/guides/skills.mdx 页与 CLI 模板刻意不带计数以避免漂移，保持无计数状态。

最后一条规则值得单列：技能自身 SKILL.md frontmatter 的 description: 是"何时使用"一句话的唯一事实源，向目录誊抄时照抄而非转述。此外 skills/hyperframes/SKILL.md 的 frontmatter 本身就是一条"强制入口点"声明：任何"制作/创建/编辑/动画化/渲染视频"的请求都应先读该技能。

5. Build & Test：bun 工作区与 oxlint/oxfmt

CLAUDE.md 的构建测试章节命令极简，但每条都有仓库级约束：

bun install     # 安装依赖（不是 pnpm——不要创建 pnpm-lock.yaml）
bun run build   # 构建所有包
bun run test    # 运行所有测试

根 package.json 证实了这些命令的实际形态：build 是一条按依赖顺序级联的 --filter 链（parsers/lint/studio-server → core → 其余引擎包 → cli → sdk-playground），test 实际委托给 test:unit 即 bun run --filter '*' test（每个工作区各自执行其测试脚本）。仓库使用 bun（bun.lock 在根目录），文档明确排除 pnpm。

Lint 与格式化使用 oxlint 与 oxfmt（"不是 eslint，不是 prettier，不是 biome"）：

bunx oxlint <files>        # Lint
bunx oxfmt <files>         # 格式化
bunx oxfmt --check <files> # 检查格式（CI / pre-commit）

"提交前必须 lint 并格式化改动文件"由 lefthook.yml 的 pre-commit 钩子强制执行，实际钩子比文档描述更完整：

• lint：对暂存的 *.{js,jsx,ts,tsx} 跑 bunx oxlint；
• format：对暂存文件跑 bunx oxfmt 并重新暂存（注释解释：替代只报告的 --check，否则 amend 快照后格式化文件会混进提交）；
• skills-manifest：skills/** 变化时重新生成根目录 skills-manifest.json（无变更时不重写，零 churn）；
• catalog-index：注册表条目变化时重建本地搜索向量（registry/catalog-artifact/），embedding 模型缺失时（退出码 3）放行，不阻塞外部贡献者；
• typecheck：packages/core、packages/studio 与 scripts/ 三处 tsc --noEmit；
• fallow：镜像 CI 的审计门（--base origin/main），只拦截分支新引入的问题；
• largefiles：拒绝把大二进制直接提交进 git pack（阈值经 HF_MAX_NONLFS_KB 调节，LFS 与 registry/ 资产豁免）；
• filesize：packages/studio 下非测试/非生成文件限 600 行——studio 架构拆解工作的产物；
• commit-msg：bunx commitlint，对应 package.json 中的 @commitlint/config-conventional，与下文 Conventional Commits 约定呼应。

6. Composition Validation：lint 与 check 双闸门

CLAUDE.md 规定：创建或编辑任何 .html 组合文件之后，必须跑两道验证，"两者都通过之前不要预览、不要认为工作完成"：

npx hyperframes lint       # 静态 HTML 结构检查
npx hyperframes check      # 浏览器闸门（headless Chrome——运行时错误、布局、运动、WCAG 对比度）

从源码结构看，静态侧对应独立的 packages/lint 包（33 个 TS 源文件），浏览器侧由 CLI 调用无头浏览器对组合做运行时检查（packages/cli/src/commands/ 下可见 check/preview 相关命令实现，预览浏览器管理在 packages/cli/src/browser/manager.ts）。这两道闸门与技能体系的 /hyperframes-cli（init、add、lint、check、snapshot、preview、render、publish、doctor、lambda）共同构成组合从编写到渲染的完整开发循环。

7. Project Structure：包布局速览

CLAUDE.md 的项目结构一节：

packages/
  cli/                  → hyperframes CLI (create, preview, lint, render)
  core/                 → Types, parsers, generators, linter, runtime, frame adapters
  engine/               → Seekable page-to-video capture engine (Puppeteer + FFmpeg)
  player/               → Embeddable <hyperframes-player> web component
  producer/             → Full rendering pipeline (capture + encode + audio mix)
  shader-transitions/   → WebGL shader transitions for compositions
  studio/               → Browser-based composition editor UI (read packages/studio/AGENTS.md first)
registry/
  blocks/               → Installable sub-composition scenes (50+)
  components/           → Installable effects and snippets
  examples/             → Starter project templates
docs/                   → Mintlify documentation site (hyperframes.heygen.com)
skills/                 → AI agent skill definitions

仓库中的实际布局与之对应：packages/ 下另有 aws-lambda/、gcp-cloud-run/、parsers/、studio-server/、sdk/ 等包（CLAUDE.md 的简表未逐一列出）；registry/blocks/ 下有 150 余个可安装子组合场景（data-chart、glitch、transitions-*、liquid-glass-* 等），与文档站 catalog 页一一对应（docs/catalog/blocks/ 下 155 个 mdx）。studio/ 条目特别提示先读 packages/studio/AGENTS.md——该文件在仓库中存在，是 studio 包自身的 agent 协作入口。

8. Key Conventions：六条硬性约定

CLAUDE.md 的 Key Conventions 是 agent 修改代码前的红线清单，每条都有仓库内可验证的落点：

• 包管理器：bun（工作区操作不用 pnpm、不用 npm）——根 bun.lock 与 lefthook 钩子中的 bunx 调用均为佐证。
• 提交格式：Conventional commits（feat:、fix:、docs:、refactor:、test:）——由 commitlint 钩子强制（commitlint.config.js）。
• TypeScript：避免 any 与 as T 断言，优先类型守卫与收窄。
• 组合（Compositions）：HTML 文件 + data-* 属性；clip 必须有 class="clip"；GSAP 时间线必须暂停并注册到 window.__timelines。
• 帧适配器（Frame Adapters）：动画运行时通过"按帧 seek"的适配器模式接入，GSAP 是主适配器——这与 core 包"Types, parsers, generators, linter, runtime, frame adapters"的定位一致，对应 docs/concepts/frame-adapters.mdx。
• 确定性渲染（Deterministic rendering）：不用 Date.now()、不用未播种的 Math.random()、渲染期不做网络请求——详见 docs/concepts/determinism.mdx。这是"HTML → 可 seek 页面 → 逐帧捕获 → 视频"引擎（engine 包，Puppeteer + FFmpeg）可复现的前提。

9. 小结：把 CLAUDE.md 当作可执行协议来用

CLAUDE.md 的价值在于它把"agent 如何在这个仓库里工作"压缩成了可检查的步骤：先装核心技能（npx hyperframes skills update），读 /hyperframes 入口技能并按其路由表进入工作流；写组合 HTML 前先读 /hyperframes-core；改完任何 .html 组合跑 npx hyperframes lint + npx hyperframes check；改动提交前由 lefthook 完成 oxlint/oxfmt/typecheck/manifest 再生成的全套把关。新增技能时则按"五处表面 + 模板 + 路由文件 + 分组 + 计数"清单同步，让 skills-manifest.json 的指纹机制与 skills check || skills update 契约持续收敛。官方文档站入口（introduction 页）与 block catalog 的地址在文档末尾给出，可作进一步延伸阅读的起点。