migration-checklist — правило для Claude Code: гид по Three.js
Правило migration-checklist подсказывает агенту, как мигрировать код при обновлении Three.js. Перечисляет breaking changes с r125 и актуальные пути импортов.
MIT ★ 4 719 обновлён 2026-10-24
.claude/rules/migration-checklist.mdЧто делает migration-checklist
Правило содержит таблицу поломок API Three.js с версии r125: удалённые конструкторы (BoxBufferGeometry теперь просто BoxGeometry), переименования (outputEncoding стал outputColorSpace), изменения поведения света и теней. Агент видит примеры старого и нового синтаксиса — импорты через three/webgpu вместо addons/renderers/webgpu/, булевый vertexColors вместо константы, новый цикл анимации через setAnimationLoop(). Для WebGPU перечислены обязательные пути TSL и дефолтные настройки PBR.
У каждой поломки — пример кода до и после, диагностика частых ошибок вроде «X is not a constructor» и значения дефолтных параметров decay, bias, roughness. Без внешних библиотек — правило читает сам Three.js.
Какие задачи решает
- исправить ошибку импорта
OrbitControlsпосле обновления Three.js - заменить
BoxBufferGeometryна актуальный конструктор - настроить
colorSpaceвместо устаревшегоoutputEncoding - адаптировать код к изменениям теней и PBR-материалов в r182–r183
Примеры запросов агенту
- Поправь импорты Three.js под r170 в файле
scene.js - Замени устаревшие конструкторы геометрии в
models/ - Проверь, нет ли проблем с
BoxBufferGeometry— агент выдаёт ошибку конструктора
Как установить migration-checklist
Вручную: положить файлы
.claude/rules/migration-checklist.mdПоле paths во frontmatter ограничивает файлы
AGENTS.md
Codex читает AGENTS.md: вставьте текст правила туда
Вручную: положить файлы
.cursor/rules/migration-checklist.mdcВо frontmatter: description, globs, alwaysApply
Вручную: положить файлы
.github/instructions/migration-checklist.instructions.mdПоле applyTo задаёт, к каким файлам применять
Вручную: положить файлы
.devin/rules/migration-checklist.mdВручную: положить файлы
.clinerules/migration-checklist.mdПо шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать
Вопросы о migration-checklist
Как установить migration-checklist в Claude Code?
Положи файл в .claude/rules/migration-checklist.md — агент подтянет его автоматически.
Что делает migration-checklist?
Показывает агенту breaking changes Three.js с r125: какие конструкторы удалены, как переписать импорты, куда переехали свойства рендерера и материалов.
Какие версии Three.js покрывает правило?
С r125 по r183. Подробнее всего разобраны r170 (импорты), r147 (цвет и свет), r180–r183 (WebGPU и PBR).
Исходный текст
migration-checklist.md · MIT
# Migration Checklist
Breaking changes and migration guide for Three.js versions.
## Recent Changes (r180-r183)
### r182 → r183
- Shadow quality improved in WebGPURenderer; reduce/remove bias values
- RoomEnvironment scene position updated; lighting may differ
- Sky/SkyMesh legacy gamma correction removed
- MeshPostProcessingMaterial removed
### r181 → r182
- `PCFSoftShadowMap` deprecated with WebGLRenderer; use `PCFShadowMap`
- WebGPURenderer: `colorBufferType` → `outputBufferType`
- VOXLoader.load() restructured
### r180 → r181
- Indirect specular light computation improved for PBR
- Rough PBR materials now appear brighter
- `renderAsync()`/`computeAsync()` deprecated; use sync versions
- TSL: `PI2` → `TWO_PI`
- New JSDoc-based API documentation
## Import Changes (r170+)
### BAD - Deprecated
```javascript
import { WebGPURenderer } from 'three/addons/renderers/webgpu/WebGPURenderer.js';
import { MeshStandardNodeMaterial } from 'three/addons/nodes/materials/...';
```
### GOOD - Current
```javascript
import * as THREE from 'three/webgpu'; // WebGPURenderer and NodeMaterials
import { ... } from 'three/tsl'; // TSL functions
```
## Color Management (r151+)
### BAD - Old API
```javascript
renderer.outputEncoding = THREE.sRGBEncoding;
texture.encoding = THREE.sRGBEncoding;
```
### GOOD - Current API
```javascript
renderer.outputColorSpace = THREE.SRGBColorSpace;
texture.colorSpace = THREE.SRGBColorSpace;
// ColorManagement.enabled = true by default
```
## Geometry Changes (r125+)
### Removed
```javascript
// REMOVED - use BufferGeometry
const geometry = new THREE.Geometry();
```
### Aliases Removed
```javascript
// These no longer exist
BoxBufferGeometry → BoxGeometry
SphereBufferGeometry → SphereGeometry
PlaneBufferGeometry → PlaneGeometry
// Just use BoxGeometry, SphereGeometry, etc.
```
## Light Decay (r147+)
```javascript
// Default decay is now 2 (physically correct)
const light = new THREE.PointLight(0xffffff, 1);
light.decay = 2; // DEFAULT
// To restore old behavior:
light.decay = 1;
```
## Material Changes (r147+)
```javascript
// vertexColors is now boolean
material.vertexColors = true; // CORRECT
// OLD:
// material.vertexColors = THREE.VertexColors; // REMOVED
```
## Renderer Changes
### setAnimationLoop
```javascript
// GOOD - Modern way
renderer.setAnimationLoop(animate);
// OLD - Still works but less preferred
function animate() {
requestAnimationFrame(animate);
renderer.render(scene, camera);
}
animate();
```
### XR Animation Loop
```javascript
// For WebXR, MUST use setAnimationLoop
renderer.xr.enabled = true;
renderer.setAnimationLoop(animate);
```
## Version Check
```javascript
console.log('Three.js version:', THREE.REVISION);
// Example: "182"
if (parseInt(THREE.REVISION) < 170) {
console.warn('Please update Three.js to r170+');
}
```
## Common Migration Issues
### Issue: "X is not a constructor"
```javascript
// Check import path
// OLD:
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls';
// NEW:
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
```
### Issue: Colors look different
```javascript
// Color management is now enabled by default
// If colors look washed out:
THREE.ColorManagement.enabled = false; // Revert to old behavior (not recommended)
// Better: Fix your color values for linear workflow
```
### Issue: Materials appear different
```javascript
// PBR materials changed in r180+
// Rough surfaces are now brighter
// Adjust roughness values if needed
material.roughness = 0.6; // May need to increase
```
### Issue: Shadows look wrong
```javascript
// Shadow bias may need adjustment
light.shadow.bias = -0.0001; // r183+ may need smaller values
```
## Quick Migration Checklist
- [ ] Update import paths (`addons/` instead of `examples/jsm/`)
- [ ] Replace `encoding` with `colorSpace`
- [ ] Remove BufferGeometry suffix (BoxGeometry, not BoxBufferGeometry)
- [ ] Check light decay values
- [ ] Update vertexColors to boolean
- [ ] For WebGPU: use `three/webgpu` and `three/tsl` imports
- [ ] Test shadows and adjust bias if needed
- [ ] Verify PBR material appearance
## References
- [Three.js Migration Guide](https://github.com/mrdoob/three.js/wiki/Migration-Guide)
- [Three.js Releases](https://github.com/mrdoob/three.js/releases)
© zebbern · MIT · zebbern/claude-code-guide