教程内容规范

本文件约定本教程各章的写法。章节目录见 README。

技术基线

Three.js 固定为本仓库的 r174（0.174.0）；示例优先从 build/three.module.js 导入。
使用 WebGLRenderer 和 ShaderMaterial 作为入门基线。讲解内置声明时明确限定为 ShaderMaterial；讲到 RawShaderMaterial 时另行列出必须自行声明的变量。
入门示例在 shader 源码中使用 attribute、varying、gl_FragColor 等易于学习的写法。r174 会将普通 ShaderMaterial 编译为 GLSL ES 3.00，并注入兼容定义；不要把示例源码的写法误称为实际编译的 GLSL 版本。需要 GLSL 3 专属语法时，单独说明 glslVersion 和输入输出声明的改变。
数值计算和颜色先按线性 RGB 理解；直接输出颜色的示例使用 #include <colorspace_fragment> 转换至渲染器的输出色彩空间。讨论纹理颜色时注明纹理本身的色彩空间设置。
每段 shader 代码注明运行阶段（顶点或片元）与所使用的坐标空间。自定义 uniform 使用 u 前缀，传给片元着色器的变量使用 v 前缀。
position、normal、uv 的声明由 Three.js 提供，但属性数据来自几何体。自定义几何体可能缺少其中的属性；uv 也不会自动传到片元着色器。

文件布局

shader-tutorial/
├─ 01-*.md ... 23-*.md            # 教程正文
├─ WRITING-GUIDE.md              # 本文件
├─ README.md                     # 阅读目录与运行方式
├─ appendix-a-troubleshooting.md # 常见错误与排查顺序
├─ exercises/                    # 练习题，不混入正文
│  ├─ README.md
│  └─ 01-*.md ... 23-*.md         # 对应章节的练习与参考解答
└─ examples/                     # 浏览器可运行示例
   └─ stage-00/ ... stage-12/

正文文件名以两位章节号开头。一个主题可以有多个示例页面；每个示例需明确对应的章节、预期画面和启动方法。练习文件沿用对应正文的章节号，参考解答放在同一文件末尾。

正文、练习与答案的边界

正文按“现象 → 原理 → 最小代码 → 参数变化 → 排错”推进。正文中的参数实验属于讲解示例，不写成要求读者提交结果的练习题。
练习题只写在 exercises/：写清目标、起始示例、限制条件和可观察的验收结果。不要在题目中直接给出完整解法。
参考解答写在对应练习文件的末尾：给出可运行解法，解释关键步骤，说明合理的其他实现。
章节末尾可以链接对应练习，但不直接链接答案，也不复制题目或答案。练习文件中的题目与答案之间保留清晰的分隔和跳转；没有相应练习的章节不放占位链接。
编辑章节时，同时检查正文、练习、答案和示例间的链接，以及代码与预期画面是否一致。

示例代码标准

示例尽量从最小运行示例扩展。保留可辨认的 scene、camera、renderer、geometry、material；静态或控件驱动的效果按需渲染，需要时间变化时使用动画循环。
展示顶点位移时，明确给出几何体的分段数；展示片元图案时，说明分段数通常不影响图案细节。
使用 1.0 这类明确的浮点字面量，避免把整型值无意传入浮点运算。
涉及比例修正时同时说明画布比例、几何体比例和图片比例各是什么，不混用。
涉及法线时写明它属于局部、世界、观察还是切线空间；顶点位移后的法线必须按新表面计算或明确说明只使用近似结果。
涉及 noise 时说明函数的输入范围、输出范围、连续性和设备精度限制；示例中避免无解释的大常数 hash。
每个完整示例均应可以从仓库根目录的静态服务器访问，不依赖未声明的 CDN 或构建步骤。