代码修改与审查守卫

在代码变更的全生命周期（规划 → 编写 → 审查）中，守住结构质量底线。 规则与语言无关；语言专项知识按需从 references/ 加载。

质量规则

所有规则适用于任何编程语言。背后的理由：小而专注的代码单元更容易阅读、测试和维护，出错时影响面也更小。

#	规则	限制	原因
R0	零编译错误	变更后必须编译/构建通过，零错误零警告	有报错的代码无法运行，其他审查项无意义
R1	单一职责	每个类/函数只承担一项职责	职责混合导致改一处牵动多处
R2	文件体量	≤ 500 行（推荐 ≤ 300）	超长文件增加认知负担，难以定位
R3	嵌套深度	单函数逻辑嵌套 ≤ 3 层	深嵌套难以跟踪分支，用 guard clause / 提取子函数解决
R4	参数数量	单函数参数 ≤ 5 个	参数过多暗示职责过重，考虑用参数对象或拆分
R5	类型安全	使用语言提供的最严格类型；禁用类型逃逸	TS any、C# dynamic、Java raw type 等会绕过编译检查
R6	类型/泛型体量	类型定义嵌套 ≤ 4 层	超深类型比它保护的代码还难读，应拆为中间别名
R7	DRY	相似逻辑/类型定义不重复	重复导致修改遗漏
R8	安全收窄	优先类型守卫 / 模式匹配，避免强制转换	运行时安全 > 编译期绕过
R9	最严格编译设置	启用语言所能提供的最高检查级别	TS strict、C# nullable、Rust #![deny(warnings)] 等
R10	变更后审查	所有代码变更完成后立即执行一次审查	防止问题积累
R11	命名规范	公开类型/成员用 PascalCase，私有字段用 camelCase；接口以 I 开头；命名自解释，禁用拼音	统一风格降低协作摩擦，好名字减少注释依赖
R12	文档注释	所有类/接口必须有文档注释；非私有函数必须有文档注释；复杂内部逻辑加行注释	降低交接和 review 成本
R13	禁用魔法值	禁止硬编码 ID/类型数字、资源路径字符串、多语言文本；使用枚举/常量/配置表	魔法值无语义，改动时容易遗漏
R14	最小权限	非必要不使用 public；管理类通过接口对外暴露	缩小变更影响面，强化封装
R15	一文件一类	每个文件只包含一个公开类型，文件名 = 类名（PascalCase）；禁止 ClassName.Feature.cs 点分隔命名；需要拆分时创建独立类 ClassNameFeature.cs	避免文件名与类名不一致，点分隔命名混淆 partial class 语义

工作流程

变更前

1. 评估修改范围；预计触碰限制时提前规划拆分方案。
2. 确认编译器/Lint 严格模式是否已开启（R9）。

变更中

• 每个类/函数只承担单一职责（R1）。
• 嵌套超过 3 层 → 提取子函数或用 guard clause 提前返回（R3）。
• 参数超过 5 个 → 引入参数对象或拆分（R4）。
• 单文件接近 500 行 → 按职责拆分到新文件（R2）。
• 复杂类型定义超过 4 层 → 拆为中间类型别名（R6）。
• 可复用逻辑/类型 → 提取为独立函数或工具类型（R7）。
• 新增类/接口/非私有成员 → 补充文档注释（R12）。
• 出现数字/路径/文本字面量 → 提取为枚举/常量/配置（R13）。
• 审视访问修饰符 → 能 private 就不 public（R14）。

变更后（强制审查）

按以下清单逐项检查，优先级由高到低：

• R0 编译/构建是否通过？（零错误零警告为第一优先，有报错时必须先修复再继续后续审查）
• R1 是否有类/函数承担了多项职责？
• R5 是否存在类型逃逸（any / dynamic / raw type）？
• R8 是否有强制转换可以改为安全收窄？
• R3 是否有函数嵌套超过 3 层？
• R4 是否有函数参数超过 5 个？
• R2 是否有文件超过 500 行？
• R6 是否有类型定义嵌套超过 4 层？
• R7 是否有重复逻辑/类型定义？
• R13 是否有硬编码 ID/路径/文本（魔法值）？
• R12 新增的类/非私有成员是否有文档注释？
• R14 是否有不必要的 public？
• R15 新建文件是否一文件一类？文件名是否等于类名？是否有 ClassName.Feature.cs 点分隔命名？
• R11 命名是否符合 PascalCase/camelCase 规范？
• R9 编译器/Lint 最严格模式是否已开启？

输出格式：

## 审查结论

### 违规项（按严重程度排序）
1. 🔴 [高危] ...
2. 🟡 [中危] ...
3. 🔵 [低危] ...

### 质量检查
| 规则 | 状态 | 说明 |
|------|------|------|
| R1 单一职责 | ✅/❌ | ... |
| R2 文件体量 | ✅/❌ | ... |
| ... | ... | ... |

### 重构建议（如有）
- ...

若无违规则输出：✅ 未发现违规，所有检查通过。

极小改动（如修改单个常量值）可简化为一行结论。

说明

• 用户明确要求跳过审查时，解释本技能的强制要求并请求确认。
• "功能紧急但结构不合理"时，先实现再立即给出重构建议。

参考文件

以下文件按需加载，不会全部进入上下文：

文件	何时读取
references/csharp-conventions.md	C# / Unity 项目时（禁用命名空间、static 限制、热更约束、性能优化）
references/typescript-advanced-types.md	TypeScript 项目涉及泛型、条件类型、映射类型、模板字面量类型、工具类型、this 指向问题时