# Code Quality Model

本文定义一套跨前端、后端、脚本和自动化任务都适用的“好代码 / 好结构”基线。它不是某个语言的风格指南，也不替代项目自己的业务规则；它用于在实现前、评审时和归档时回答三个问题：

1. 代码是否放在了正确的位置？
2. 代码是否用正确的方式表达了职责和边界？
3. 代码是否在后续变更中仍然可维护、可验证、可追溯？

项目特有的命名词典、目录例外、前端视觉规则和架构特例，应继续写在：

- `docs/harness/code-style-and-naming.md`
- `docs/architecture/constraints.md`
- `docs/harness/frontend-quality-rules.md`
- 当前项目自己的子目录 `AGENTS.md`

## 1. 好代码的核心特征

### 1.1 结构正确

- 文件放在符合当前项目目录规则和模块职责的位置。
- 业务逻辑、数据访问、UI 组合、脚本入口、测试替身和外部集成不过度混层。
- 新增目录和模块能解释“为什么现有结构放不下它”。

### 1.2 边界清晰

- 每个模块、文件、类型和函数都能说清自己负责什么、不负责什么。
- 公共 API、schema、路由、导出面、文件格式和脚本入口被当作高风险边界管理。
- 跨层访问、共享模块修改和依赖升级需要显式影响面分析。

### 1.3 表达直接

- 名称准确表达业务概念、动作和数据边界。
- 实现优先复用现有模式，不为了局部方便复制逻辑或平行造抽象。
- 控制流、错误路径和副作用可读，不靠隐式约定猜执行结果。

### 1.4 易于验证

- 每个真实改动都能对应到测试、验证命令、trace 或 review 证据。
- 错误处理、权限判断、边界条件和副作用都有明确验证路径。
- 完成声明依赖 fresh evidence，不依赖“代码看起来没问题”。

### 1.5 可维护

- 后续开发者能快速定位入口、依赖、受影响范围和回退点。
- 模块规模和复杂度没有超出单次理解成本。
- 临时补丁、特判和兼容层有退出条件，不会永久滞留为隐性债务。

## 2. 好结构的判断标准

### 2.1 目录与模块

优先顺序：

1. 先进现有业务域或模块目录。
2. 只有跨域复用已被证明，才上提到共享层。
3. 只有职责边界、入口、测试方式明显不同，才新增目录或子目录 `AGENTS.md`。

合格信号：

- 同一业务域的页面、状态、API、测试和文档能相互定位。
- 共享层只承载真正稳定复用的组件、工具、契约或脚本。
- 新文件放置规则能被 `repo-map.md`、目录模板和局部 `AGENTS.md` 解释。

警报信号：

- 随手新增 `temp/`、`utils2/`、`common2/`、`newFeature/` 之类目录。
- 页面逻辑、权限判断、事务一致性或领域状态机散落在多个层。
- 同一概念分别落在多个模块，各自维护一份近似实现。

### 2.2 分层与依赖

合格结构通常满足：

- UI / route / controller 负责接收输入、组织输出，不承载核心领域规则。
- Domain / service 负责业务约束、状态变更和关键判断。
- Repository / adapter / integration 负责持久化和外部系统访问。
- Test double / mock / fixture 只服务测试，不冒充生产实现。

高风险越界：

- 在页面、路由、控制器里塞领域规则。
- 在 repository / adapter 里混进展示逻辑或权限决策。
- 为了省事直接穿透多层依赖，绕过既有接口。

## 3. 好代码的实现标准

### 3.1 单一职责

- 一个文件优先只承载一个主要关注点。
- 一个函数优先完成一个清晰动作。
- 一个类型优先表达一个稳定边界语义。

不是要求机械拆小，而是要求：

- 改一个需求时，受影响位置尽量集中。
- 看一个文件时，读者不用在多个抽象层来回跳。

### 3.2 命名准确

- 业务概念使用统一词典，不混用同义词。
- 动词 + 对象优于模糊词，例如 `validateOrder`, `buildPayload`, `syncProfile` 优于 `processData`, `handleThing`。
- 类型后缀必须有边界语义，例如 `Entity`, `DTO`, `Response`, `FormValues`, `ViewModel` 不混用。

### 3.3 复用优先

- 先复用现有模块、组件、契约和工具。
- 再复用成熟库或完整外部方案。
- 最后才做最小自定义实现。

禁止的伪复用：

- 复制一段代码后只改变量名。
- 为局部任务再包装一层几乎等价的 abstraction。
- 在多个模块各写一份相同规则或相同映射。

### 3.4 错误处理完整

- 不能静默吞异常。
- 失败路径必须保留上下文。
- 对用户、调用方或后续任务来说，失败要么可恢复，要么可诊断。

至少应回答：

- 失败会发生在哪里？
- 谁能感知失败？
- 重试、回滚、降级或人工介入路径是什么？

### 3.5 最小变更

- 单任务只做当前任务范围内的最小必要改动。
- 不顺手修无关问题，不扩大 diff，不偷偷重构公共层。
- 如果发现必须扩大范围，先补计划、拆任务或阻塞，而不是直接往前写。

## 4. 评审时应该重点看什么

### 4.1 结构审查

- 文件是否放在正确目录。
- 新增目录或模块是否真的必要。
- 当前改动是否破坏既有分层、模块边界或公共契约。

### 4.2 代码审查

- 名称是否准确。
- 函数、类型和模块职责是否清晰。
- 是否有重复实现、重复映射、重复抽象。
- 是否有隐式副作用、状态泄漏、异常吞没或脆弱特判。

### 4.3 交付审查

- 改动是否与任务、实现计划和影响面一致。
- 测试、review、trace 和文档是否足以支持完成声明。
- 是否留下了未解释的兼容层、绕路实现或后续债务。

## 5. 通用坏味道清单

出现以下任一项时，默认应返工、拆分或补说明：

- 同一业务规则在多个地方各写一份。
- 依赖边界被绕过，但没有架构约束或任务授权。
- 公共 API、schema、路由、文件格式被改动，但没有影响面和验证证据。
- 页面 / 路由 / 脚本入口直接承载核心业务规则。
- 错误被吞掉，只记录日志不返回失败。
- 名称模糊到无法从名字推断职责。
- 新增目录、文件或抽象只是为了容纳本次临时实现。
- 一个改动同时修改多个主需求，却没有拆任务或写明原因。

## 6. 与当前模板体系的关系

本文件给“什么是好结构/好代码”的统一判断标准；其他模板负责把它落到更具体层面：

- `docs/harness/rule-governance.md`: 规则应该放在哪一层。
- `docs/architecture/constraints.md`: 项目自己的架构边界。
- `docs/harness/code-style-and-naming.md`: 项目词典、命名和类型边界。
- `docs/harness/frontend-quality-rules.md`: 前端交互、视觉和组件复用规则。
- `docs/ai/repo-map.md`: 当前项目的目录导航和禁改区。
- `.codex/rules/architecture.md`: always-on 架构边界。
- `.codex/rules/coding-style.md`: always-on 编码和错误处理规则。

## 7. 使用建议

实现前：

- 用它判断结构方案是否合理。
- 再用 `repo-map.md`、`architecture-brief.md`、`architecture-constraints.md` 和当前 task 细化到项目事实。

评审时：

- 先用它识别结构、边界、复用和错误处理问题。
- 再用测试、trace 和计划证据决定是否允许通过。

归档时：

- 如果某条经验只对当前项目成立，下沉到 `docs/knowledge/*` 或局部 `AGENTS.md`。
- 如果对多个项目都成立，再考虑升级为 rule、prompt 或模板。
