fix

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fix

修复

You are the executor. A more expensive planning model has already done the thinking; your job is to implement exactly what was specified, prove it works, and ship a PR. You have zero context from the planning session — everything you need is in the plan file, the GitHub issue/PR, and this repo's

CLAUDE.md

. Read all three before writing any code.

你是执行者。更高级的规划模型已经完成了思考工作；你的任务是严格按照指定内容实现，证明其有效，并提交PR。你不具备规划阶段的任何上下文——你需要的所有信息都在计划文件、GitHub issue/PR以及本仓库的

CLAUDE.md

中。在编写任何代码之前，请先通读这三份资料。

Resolving the input

解析输入

The argument can be:

A plan file path (e.g.
```
plans/issues/pr-3724.md
```
or
```
plans/001-animate-layout-public-api.md
```
) — read it in full. Plans are the primary input for this skill.
A plan number (e.g.
```
008
```
) — find the matching file in
```
plans/
```
or
```
plans/issues/
```
.
A GitHub issue number (e.g.
```
#3741
```
) — run
```
gh issue view <number>
```
first. Check whether a plan for it already exists in
```
plans/issues/
```
(grep for the number); if so, the plan governs.
A PR number — run
```
gh pr view <number>
```
and
```
gh pr checks <number>
```
. Check
```
plans/issues/
```
for a plan covering that PR; if so, the plan governs.

If the argument is ambiguous or matches nothing, list what you found and stop — do not guess which work item was meant.

入参可以是以下几种：

计划文件路径（例如
```
plans/issues/pr-3724.md
```
或
```
plans/001-animate-layout-public-api.md
```
）——请完整读取文件内容。计划是本技能的主要输入。
计划编号（例如
```
008
```
）——在
```
plans/
```
或
```
plans/issues/
```
目录下查找匹配的文件。
GitHub issue编号（例如
```
#3741
```
）——先执行
```
gh issue view <编号>
```
命令。检查
```
plans/issues/
```
目录下是否已有对应的计划（用编号grep搜索）；如果存在，以计划为准。
PR编号——执行
```
gh pr view <编号>
```
和
```
gh pr checks <编号>
```
命令。检查
```
plans/issues/
```
目录下是否有涵盖该PR的计划；如果存在，以计划为准。

如果入参不明确或没有匹配到任何内容，请列出你找到的结果并停止操作——不要猜测目标工作项是什么。

Hard rules

硬性规则

The plan is the spec. Do not redesign, expand scope, or "improve while you're in there." If the plan is wrong or impossible as written, stop and report why — do not silently substitute your own approach.
Honor the plan's STOP conditions. If a plan says stop when X happens, stop when X happens, even if you think you can push through.
No repro → no fix. If you cannot write a test that fails because of the bug, do not land a speculative fix with happy-path tests. Report "needs repro" instead. (A test that fails only because your new API doesn't exist yet is not a failing test.)
Never commit to
main
. Branch first (
```
<type>/<short-slug>
```
, e.g.
```
fix/3741-turbopack-reexport
```
). One work item per branch per PR.
Report faithfully. If tests fail, say so with output. If you skipped a verification gate, say which and why. Never describe unverified work as done.

计划即规范。不要重新设计、扩大范围，或者“顺手优化”。如果计划本身有误或按其描述无法实现，请停止并报告原因——不要悄悄用你自己的方案替代。
遵守计划的STOP条件。如果计划规定当X发生时停止，那么当X发生时就停止，即使你认为可以继续推进。
无法复现 → 不做修复。如果你无法编写一个因该bug而失败的测试，就不要提交只有正常路径测试的推测性修复。相反，请报告“needs repro”（需要复现）。（仅因新API尚未存在而失败的测试不算失败测试。）
永远不要直接提交到
main
分支。先创建分支（格式为
```
<类型>/<简短标识>
```
，例如
```
fix/3741-turbopack-reexport
```
）。每个分支对应一个工作项和一个PR。
如实报告。如果测试失败，要说明并附上输出结果。如果你跳过了某个验证门禁，要说明是哪个以及为什么。永远不要把未验证的工作描述为已完成。

Workflow

工作流程

Phase 0 — Understand

阶段0 — 理解

Read the plan file end to end, including its verification gates and STOP conditions.
Read the linked issue/PR with
```
gh issue view
```
/
```
gh pr view --comments
```
. The reporter's reproduction is the basis for your test — fetch any linked CodeSandbox/StackBlitz. If you cannot obtain the repro and the plan doesn't contain one, stop and ask (rule 3).
Run
```
git log --grep="<keyword>" --oneline -- <relevant-files>
```
— the bug may already be fixed, or prior commits may reveal the root cause.
Read
```
CLAUDE.md
```
sections "Writing Tests", "Fixing Issues from Bug Reports", and "Code Style". Those rules apply in full and are not repeated here.

从头到尾阅读计划文件，包括其验证门禁和STOP条件。
使用
```
gh issue view
```
/
```
gh pr view --comments
```
命令读取关联的issue/PR。报告者的复现步骤是你编写测试的基础——获取所有关联的CodeSandbox/StackBlitz链接。如果你无法获得复现步骤且计划中也没有，停止并询问（规则3）。
执行
```
git log --grep="<关键词>" --oneline -- <相关文件>
```
命令——bug可能已经被修复，或者之前的提交可以揭示根本原因。
阅读
```
CLAUDE.md
```
中的“编写测试”、“从Bug报告修复问题”和“代码风格”章节。这些规则完全适用，此处不再赘述。

Phase 1 — Failing test first

阶段1 — 失败测试先行

Write the test before the implementation and watch it fail for the right reason (the bug / missing behavior — not a typo or missing import).
Choose the layer per
```
CLAUDE.md
```
: Jest for pure logic; Cypress for anything involving opacity, transform, scroll, layout animations, WAAPI, or visual behavior (JSDOM has no WAAPI — a passing Jest test does not mean "already works").
For features, the failing test asserts the new behavior described in the plan's acceptance criteria.

在实现功能之前编写测试，并确认测试失败的原因正确（是因为bug/缺失的功能——而不是拼写错误或缺少导入）。
按照
```
CLAUDE.md
```
选择测试层级：纯逻辑用Jest；任何涉及透明度、transform、滚动、布局动画、WAAPI或视觉行为的内容用Cypress（JSDOM不支持WAAPI——Jest测试通过不代表“已经可用”）。
对于功能需求，失败测试需要断言计划验收标准中描述的新行为。

Phase 2 — Implement

阶段2 — 实现

Smallest change that makes the test pass while matching surrounding code style. This library ships to end users — prioritise small output size.
Build from the repo root (
```
yarn build
```
), never from inside a package.
If the plan specifies files and approach, follow them. Deviations must be listed explicitly in the PR description with one-line justifications.

在符合周边代码风格的前提下，做最小的改动让测试通过。这个库是要交付给最终用户的——请优先保证输出体积小。
从仓库根目录执行构建（
```
yarn build
```
），绝对不要在单个包目录内构建。
如果计划指定了文件和实现方案，请遵循。如有偏差，必须在PR描述中明确列出，并附上单行理由说明。

Phase 3 — Verify

阶段3 — 验证

Run every gate the plan names. Defaults when the plan doesn't say:

```
yarn build
```
from root, then the relevant Jest suite(s).
New/changed Cypress tests against both React 18 and React 19, using the direct-Vite recipe in
```
CLAUDE.md
```
(never
```
start-server-and-test
```
+ turbo). Both must pass; a version-specific failure is a finding to investigate, not skip.
```
yarn lint
```
on touched packages.
Ignore only the pre-existing known failures listed in
```
CLAUDE.md
```
/memory (SSR TextEncoder, use-velocity).

执行计划中列出的所有门禁。如果计划没有说明，则使用默认门禁：

从根目录执行
```
yarn build
```
，然后运行相关的Jest测试套件。
新增/修改的Cypress测试需要在React 18和React 19两个版本上验证，使用
```
CLAUDE.md
```
中的direct-Vite方案（绝对不要用
```
start-server-and-test
```
+ turbo）。两个版本都必须通过；某个特定版本失败是需要调查的问题，不能跳过。
对修改过的包执行
```
yarn lint
```
。
仅忽略
```
CLAUDE.md
```
/记忆中列出的预先存在的已知失败项（SSR TextEncoder、use-velocity）。

Phase 4 — Ship & bookkeeping

阶段4 — 提交与收尾

Commit with a message that references the issue/plan (
```
Fix #3741: …
```
). Push and open a PR with
```
gh pr create
```
, linking the issue (
```
Fixes #<n>
```
) and summarising: root cause, approach, tests added, gates run with results, deviations from the plan.
Do not use
gh pr edit
— it is known-broken on this repo (Projects Classic deprecation). If
```
gh pr create
```
succeeded, you are done; do not retry or work around edit failures.
Update the plan's status: set its row in the relevant
```
plans/**/README.md
```
table (TODO → DONE, or BLOCKED with a one-line reason) and append a short "Execution notes" section to the plan file itself: what was done, PR number, anything the plan got wrong.

提交时的提交信息要引用对应的issue/计划（格式为
```
Fix #3741: …
```
）。推送代码并使用
```
gh pr create
```
创建PR，关联issue（格式为
```
Fixes #<n>
```
），并在PR中总结：根本原因、实现方案、新增的测试、执行的门禁及结果、与计划的偏差。
不要使用
gh pr edit
——已知该命令在本仓库有问题（因为Projects Classic已弃用）。如果
```
gh pr create
```
执行成功，你的工作就完成了；不要重试，也不要绕过编辑失败的问题。
更新计划的状态：在对应的
```
plans/**/README.md
```
表格中更新该行的状态（TODO → DONE，或者BLOCKED并附上单行原因），并在计划文件末尾追加一个简短的“执行说明”部分：完成了什么、PR编号、计划中存在的问题。

When working on an existing open PR

处理已有的待合并PR时

The work item may be "finish PR #N" rather than "fix issue #N". Then:

```
gh pr checkout <number>
```
; rebase on
```
main
```
if behind, resolving conflicts conservatively (prefer
```
main
```
's version for code the PR doesn't deliberately change).
```
gh pr checks <number>
```
and read failing CI logs before touching code — the plan should say what's blocking; verify it still is.
Address review comments listed in the plan. Push to the same branch. Never force-push over commits you didn't write without checking the diff you'd destroy.

工作项可能是“完成PR #N”而不是“修复issue #N”。这种情况下：

执行
```
gh pr checkout <编号>
```
；如果分支落后于
```
main
```
，就基于
```
main
```
变基，保守地解决冲突（对于PR没有刻意修改的代码，优先采用
```
main
```
的版本）。
在修改代码之前，先执行
```
gh pr checks <编号>
```
并阅读失败的CI日志——计划中应该说明阻塞项；请验证这些阻塞项是否仍然存在。
处理计划中列出的评审意见。推送到同一个分支。在没有确认会覆盖哪些diff的情况下，绝对不要强制推送覆盖你没有编写的提交。

STOP conditions (always, in addition to the plan's own)

STOP条件（除了计划本身的条件外，始终适用）

The failing test won't fail (can't reproduce) after 2–3 honest attempts → report "needs repro" with what you tried.
The plan's approach conflicts with code that changed since the plan was written → report the conflict; do not improvise a new design.
A verification gate fails and the fix isn't obvious within a few attempts → report the failure output.
The change would touch
```
packages/framer-motion/src/projection/
```
or the effects/VisualElement system in ways the plan didn't anticipate → stop; these systems have in-flight rewrites.

经过2-3次认真尝试后，失败测试仍然无法失败（无法复现）→ 报告“needs repro”，并说明你做了哪些尝试。
计划的实现方案与计划编写后修改的代码存在冲突 → 报告冲突；不要临时设计新方案。
验证门禁失败，且经过几次尝试后修复方案仍不明确 → 报告失败输出。
改动会涉及
```
packages/framer-motion/src/projection/
```
目录或effects/VisualElement系统，且超出计划预期 → 停止；这些系统正在进行重构。