---
trigger: always_on
---

# Coding Style

## 规则分层

- 这里写跨项目稳定不变、需要默认自动加载的规则。
- `docs/harness/code-style-and-naming.md` 只补项目特有的业务词典、目录例外和类型边界表，不重复这里的固定规则。

## 不可变性

- 默认使用不可变更新，不直接修改输入对象。
- 状态更新、缓存更新、测试夹具都遵守同一原则。

## 固定命名规则

- 一个业务概念只用一个主名词，不在同一任务里混用多个同义词。
- 发现历史别名时，先判断它是独立概念还是遗留脏别名，再决定兼容方式。
- 项目专属业务词典、别名白名单和历史兼容说明写到 `docs/harness/code-style-and-naming.md`。

## 固定文件命名规则

- 同一层目录只使用一套命名风格。
- 新文件先跟随同目录已有约定，不自行切换成另一套大小写风格。
- 测试文件跟随被测对象命名，不用 `test1`、`temp`、`new` 这类临时名。

## 固定函数命名规则

- 函数名使用“动词 + 对象”或明确状态判断。
- 禁止使用 `doAction`、`processData`、`dealData`、`getInfo`、`check`、`handler` 这类模糊名。
- 事件处理统一使用 `handleXxx`，布尔判断统一使用 `is/has/can` 前缀。

## 固定类型命名规则

- 类型后缀必须有边界语义，`Entity`、`DTO`、`Response`、`FormValues`、`ViewModel` 不混用。
- 输入模型、持久化模型、展示模型和接口模型不要共用一个泛名。
- 如果项目禁用某类后缀，具体禁用表和替代方案写到 `docs/harness/code-style-and-naming.md`。

## 文件组织

- 高内聚、低耦合；按 feature / domain 组织，避免大而杂的工具箱文件。
- 常规文件建议 200-400 行，超过 800 行应先评估是否拆分。

## 错误处理与输入校验

- 错误处理要保留上下文，不吞异常。
- 外部输入统一走 schema / validator / contract，不靠隐式假设。

## 完成前检查

- [ ] 命名是否与项目业务词典一致
- [ ] 同层文件是否遵守同一命名风格
- [ ] 新函数名是否避开模糊万能词
- [ ] 新类型名是否符合边界语义
- [ ] 无 `console.log`、无硬编码临时名、无直接对象突变
