three-audit
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseThree.js / R3F Audit
Three.js / R3F 审计
Purpose
目的
A curated catalog of WebGL performance and correctness checks for Three.js and
React Three Fiber projects. Each check is one self-contained file describing
what to look for, why it matters, and how to fix it. The skill walks you
through running them against a target codebase and producing a structured
findings report.
This is not a linter — most checks need contextual judgment, not just
pattern-matching. The agent is expected to read the offending code and reason
about whether the pattern actually applies in this scene.
Detection commands assume (ripgrep) and are on . Substitute
and a manual read of where they are not.
rgjqPATHgrep -rnpackage.json这是一份针对Three.js和React Three Fiber项目的WebGL性能与正确性检查清单。每项检查都是一个独立文件,说明检查内容、影响原因及修复方法。本技能将引导你针对目标代码库执行这些检查,并生成结构化的审计结果报告。
这不是代码检查工具(linter)——大多数检查需要结合上下文判断,而非仅依赖模式匹配。Agent需要阅读问题代码并分析该模式是否确实适用于当前场景。
检测命令假设环境变量中已配置(ripgrep)和。若未配置,可替换为并手动读取。
PATHrgjqgrep -rnpackage.jsonWhen to Use This Skill
适用场景
- Reviewing a 3D scene's performance, or before shipping a Three.js / R3F build
- Investigating a frame-rate regression, especially one that tracks window size
- Reviewing a change that touches renderer setup, , materials, shadows, instancing, or texture loading
useFrame
- 审查3D场景性能,或在Three.js / R3F项目发布前进行检查
- 排查帧率下降问题,尤其是与窗口大小相关的帧率回归
- 审查涉及渲染器设置、、材质、阴影、实例化或纹理加载的代码变更
useFrame
Workflow
工作流程
Step 1 — Confirm the project actually uses Three.js / R3F
步骤1 — 确认项目是否使用Three.js / R3F
bash
jq -r '
((.dependencies // {}) + (.devDependencies // {}) + (.peerDependencies // {}))
| to_entries
| map(select(.key | test("^(three$|@react-three/)")))
| .[].key
' package.json 2>/dev/nullIf nothing matches, stop and tell the user the audit doesn't apply.
bash
jq -r '
((.dependencies // {}) + (.devDependencies // {}) + (.peerDependencies // {}))
| to_entries
| map(select(.key | test("^(three$|@react-three/)")))
| .[].key
' package.json 2>/dev/null若没有匹配结果,停止操作并告知用户本审计不适用。
Step 2 — Find renderer entry points
步骤2 — 查找渲染器入口点
These are the anchors most checks key off of:
bash
undefined这些是大多数检查的核心锚点:
bash
undefinedVanilla Three.js renderer construction
原生Three.js渲染器构造
rg -n 'new\s+(THREE.)?WebGLRenderer\b' --type ts --type tsx --type js --type jsx
rg -n 'new\s+(THREE.)?WebGLRenderer\b' --type ts --type tsx --type js --type jsx
React Three Fiber Canvas mounts
React Three Fiber Canvas挂载
rg -n '<\s*Canvas\b' --type tsx --type jsx
rg -n '<\s*Canvas\b' --type tsx --type jsx
R3F imperative GL access
R3F命令式GL访问
rg -n "useThree(|gl\s*[:=]" --type tsx --type jsx
Note the file paths — each check refers back to them.rg -n "useThree(|gl\s*[:=]" --type tsx --type jsx
记录文件路径——每项检查都会引用这些路径。Step 3 — Decide which conditional checks apply
步骤3 — 确定适用的条件检查项
The convention checks encode project conventions, not Three.js rules. Running
them against a project that never adopted the convention produces noise, so
activate each one only on its signal:
bash
undefined约定检查项基于项目约定而非Three.js规则。若项目未采用相关约定,执行这些检查会产生无效结果,因此仅在检测到信号时激活对应检查项:
bash
undefineduseframe-priority — is a priority argument used anywhere?
useframe-priority — 是否使用了优先级参数?
rg -n 'useFrame([^)]},\s-?\d' --type tsx --type jsx
rg -n 'useFrame([^)]},\s-?\d' --type tsx --type jsx
scene-dom-separation — is there a scene directory distinct from components?
scene-dom-separation — 是否存在与components目录分离的scene目录?
ls -d src/scene src/three src/webgl src/components 2>/dev/null
ls -d src/scene src/three src/webgl src/components 2>/dev/null
store-wiring — is there an external atom store?
store-wiring — 是否使用外部原子状态库?
jq -r '((.dependencies // {}) + (.devDependencies // {})) | keys[]' package.json 2>/dev/null
| rg 'nanostores|zustand|jotai|valtio'
| rg 'nanostores|zustand|jotai|valtio'
No signal → skip that check and say so in the report's skipped list. Each check
file restates its own activation condition; follow that over this summary if
they disagree.jq -r '((.dependencies // {}) + (.devDependencies // {})) | keys[]' package.json 2>/dev/null
| rg 'nanostores|zustand|jotai|valtio'
| rg 'nanostores|zustand|jotai|valtio'
若无信号→跳过该检查项,并在报告的跳过列表中说明。每个检查文件都会重新说明其激活条件,若与本摘要冲突,以检查文件中的条件为准。Step 4 — Run checks from the catalog
步骤4 — 执行清单中的检查项
For each row in the Checks tables below, open
and follow its detection and assessment
guidance. If the user passed , run only that one.
references/checks/<name>.md--check=<name>Read every candidate site before reporting it. Most checks list legitimate
uses of the pattern they detect — a grep hit is a candidate, not a finding.
对于下方检查项表格中的每一行,打开并遵循其检测和评估指南。若用户传入,则仅执行该检查项。
references/checks/<name>.md--check=<name>在报告前需阅读所有候选代码位置。大多数检查项会列出检测模式的合法使用场景——grep命中仅为候选,而非确定问题。
Step 5 — Report findings
步骤5 — 报告审计结果
Group findings by severity (, , ) and emit one section per
check that produced a finding. Format:
highmediumlowmarkdown
undefined按严重程度(、、)分组结果,每个产生结果的检查项对应一个章节。格式如下:
highmediumlowmarkdown
undefined<check-name> — <severity>
<检查项名称> — <严重程度>
Where: <file>:<line> [+ more]
What's wrong: <one sentence>
Suggested fix:
```<lang>
<canonical pattern>
```
Why it matters: <one sentence on the user-visible impact>
Each check file ends with a **How to report this finding** section — use its
wording so findings from different checks read consistently.
Skip checks that produced no finding (don't pad the report). End with a tally:
`<N> findings: <high> high, <medium> medium, <low> low`, followed by one line
naming any conditional checks skipped for lack of a signal.位置: <文件>:<行号> [更多位置]
问题描述: <一句话说明>
建议修复方案:
```<语言>
<标准修复代码>
```
影响说明: <一句话说明对用户的可见影响>
每个检查文件末尾都有**如何报告该结果**章节——使用其中的表述,确保不同检查项的结果报告风格一致。
跳过未产生结果的检查项(不要填充报告)。结尾添加统计信息:`<N> 项问题: <high> 高风险, <medium> 中风险, <low> 低风险`,随后用一行说明因无信号而跳过的条件检查项。Lens Mode
透镜模式
review:changes-review- The caller supplies the scope. Audit exactly the files it resolved and no more — a whole-scene audit returns findings the run cannot attribute to the change
- Skip Step 1's project detection; the caller already matched on the imports
- Return findings in the shape the caller asked for, not the report format above
- Conditional convention checks map to the caller's lowest severity
Standalone invocation is unaffected and stays the primary path.
当代码变更涉及Three.js或R3F文件时,会将本技能作为堆栈透镜调用。在此模式下:
review:changes-review- 调用方会提供检查范围。仅审计其指定的文件,不要进行全场景审计(否则会返回无法归因于本次变更的结果)
- 跳过步骤1的项目检测——调用方已通过导入匹配确认项目类型
- 按照调用方要求的格式返回结果,而非上述报告格式
- 条件约定检查项映射为调用方指定的最低严重程度
独立调用不受影响,仍遵循主流程。
Checks
检查项
Catalog of checks. Each one is defined in .
references/checks/<name>.md检查项清单。每个检查项都定义在中。
references/checks/<name>.mdPerformance and correctness
性能与正确性
| Check | Topic | Severity |
|---|---|---|
| Cap | High (perf) |
| Stacked transparency and post-processing passes shading the same pixels many times over | High (perf) |
| | High (perf) |
| Geometries, materials, textures, and render targets leaking VRAM without | High (memory) |
| | High (perf) |
| A distinct geometry/material per object where one shared instance would do | Medium (perf/memory) |
| Hundreds of identical meshes that should be one | Medium (perf) |
| Shadow map resolution, casting light count, and shadow cameras fitted to nothing | Medium (perf) |
| Shader-define changes at runtime causing main-thread GLSL recompiles | Medium (perf) |
| Oversized or uncompressed textures, wrong colour space, mipmaps disabled | Medium (memory/perf) |
| Culling disabled, stale bounding volumes, or one merged mesh spanning the scene | Medium (perf) |
| 检查项 | 主题 | 严重程度 |
|---|---|---|
| 通过像素预算限制 | 高(性能) |
| 堆叠的透明效果和后期处理通道导致同一像素被多次着色 | 高(性能) |
| 在 | 高(性能) |
| 几何体、材质、纹理和渲染目标未调用 | 高(内存) |
| | 高(性能) |
| 每个对象使用独立的几何体/材质,而实际上可共享单个实例 | 中(性能/内存) |
| 数百个相同网格应合并为一个 | 中(性能) |
| 阴影贴图分辨率、投射光源数量及阴影相机设置不合理 | 中(性能) |
| 运行时修改着色器定义导致主线程GLSL重新编译 | 中(性能) |
| 纹理尺寸过大、未压缩、颜色空间错误或禁用mipmaps | 中(内存/性能) |
| 剔除功能禁用、边界盒过期或单个合并网格覆盖整个场景 | 中(性能) |
Project conventions (conditional)
项目约定(条件性)
Run only when Step 3 found the activation signal.
| Check | Topic | Severity |
|---|---|---|
| Atom store reads that don't subscribe, and unbatched related writes | Medium (perf/convention) |
| Gameplay at priority 1, effects at priority 2, so effects don't sample stale transforms | Medium (correctness/convention) |
| 3D components under | Low (convention) |
仅在步骤3检测到激活信号时执行。
| 检查项 | 主题 | 严重程度 |
|---|---|---|
| 原子状态库读取未订阅,以及相关写入未批量处理 | 中(性能/约定) |
| 游戏逻辑优先级设为1,特效优先级设为2,避免特效采样过时变换 | 中(正确性/约定) |
| 3D组件放在 | 低(约定) |
Severity Guide
严重程度指南
- High — measurable frame-rate or memory impact under realistic load, or a correctness bug that ships visible artifacts. Worth fixing before release.
- Medium — perf hit on stress paths or older hardware, or a fragile pattern that's likely to break later. Worth scheduling.
- Low — minor cleanup, style nit, or a pattern that's only suspect in unusual scenes. Note it; don't block on it.
The severity in the table is the check's default. Adjust it for the scene you
are looking at and say why — 300 unshared materials in a 12-object scene is
still low.
- 高风险 — 在实际负载下可测量到帧率或内存影响,或存在会导致可见缺陷的正确性问题。发布前必须修复。
- 中风险 — 在压力场景或旧硬件上存在性能损耗,或属于易出问题的脆弱模式。需安排修复。
- 低风险 — 轻微清理项、风格问题,或仅在特殊场景下存在风险的模式。记录即可,无需阻塞发布。
表格中的严重程度为检查项的默认值。可根据当前场景调整,并说明原因——例如在仅含12个对象的场景中,300个未共享材质仍属于低风险。
Adding a New Check
添加新检查项
- Create using the existing checks as a template. Required sections: What it is, Why it matters, How to detect, Anti-patterns, Canonical fix, Notes, and How to report this finding.
references/checks/<name>.md - Append a row to the appropriate Checks table above with topic and severity.
- If the check is conditional on a project convention, state the activation
signal in a line in its header block and add the detection command to Step 3.
**Conditional:** - If the check needs special detection (beyond grep + read), describe it in the check file itself rather than baking shell scripts into the skill — keeps each check portable across Claude / Codex / future hosts.
- 以现有检查项为模板,创建。必填章节:检查内容、影响原因、检测方法、反模式、标准修复方案、注意事项和如何报告该结果。
references/checks/<name>.md - 在上方对应的检查项表格中添加一行,包含主题和严重程度。
- 若检查项为基于项目约定的条件性检查,在其头部块中添加行说明激活信号,并将检测命令添加到步骤3中。
**条件:** - 若检查项需要特殊检测(超出grep+人工阅读),在检查文件中说明,而非将shell脚本硬编码到技能中——确保每个检查项可在Claude/Codex/未来宿主环境中移植。
Out of Scope
超出范围
- GLSL shader correctness (covered by shader-specific tooling)
- Model authoring — mesh topology, UV layout, rigging, DCC export settings
- Browser-level perf tracing (use Chrome DevTools / Spector.js directly)
- General React patterns — effects, memoization, state architecture (use
; this skill only covers React as it meets the Canvas)
react-audit
The audit reads the JS/TS source. The one exception is
, which also sizes the
texture files on disk, because how a texture is delivered — dimensions,
format, colour space — is a renderer concern that the source alone cannot
answer. How it was authored is not.
texture-budget- GLSL着色器正确性(由着色器专用工具覆盖)
- 模型创作——网格拓扑、UV布局、绑定、DCC导出设置
- 浏览器级性能追踪(直接使用Chrome DevTools / Spector.js)
- 通用React模式——副作用、 memoization、状态架构(使用;本技能仅覆盖与Canvas交互的React部分)
react-audit
本审计仅读取JS/TS源码。唯一例外是,它还会检查磁盘上的纹理文件大小,因为纹理的交付方式——尺寸、格式、颜色空间——属于渲染器相关问题,仅通过源码无法完全判断。但纹理的创作方式不在本审计范围内。
texture-budget