Dev Principles

---
name: dev-principles
description: "Development principles: ubiquitous language, tracer bullets, deep modules, unidirectional dependencies. Use before non-trivial feature work, cross-module changes, refactoring, dependency or module-boundary changes, or design review; not needed for simple single-point fixes. 开发原则：统一语言、贯通路径、深模块、单向依赖。在开始非琐碎的功能开发、跨模块修改、重构、调整依赖或模块边界、设计评审前使用；简单的单点修复不需要。"
---

# 开发原则

用准确的语言定义问题，用最小的真实路径验证方向，用简单的接口封装复杂性，用单向的依赖控制变化的影响范围。

## 统一语言（Ubiquitous Language）

- 动手前查阅项目术语表（默认 `docs/glossary.md`，不存在时在首次需要时创建）。沿用已有术语，在需求、代码标识符、测试和文档中保持一致。
- 区分相近概念，例如任务、执行、尝试。不同理解会导致不可逆或代价高的差异时，先澄清；否则写明假设后继续。
- 术语只在其业务上下文内统一，不同上下文可以使用不同模型。
- 新增术语或发现冲突时，更新术语表：名称、含义、代码标识符、易混淆的近义词。

## 贯通路径（Tracer Bullet）

- 动手前写出：选定的路径、经过的层、哪些部分用替身、哪些集成暂不验证。
- 选择范围小、能验证关键不确定性的用例，先打通它需要的每一层，再扩展其他场景。
- 路径可以窄，但要保留它需要的校验、权限和错误处理。这条路径的代码要留作骨架继续演进；只用于学习的原型要明确标注为可丢弃。
- 用端到端测试或真实运行证明路径已打通。单条路径成功不代表整个系统正确。
- 单点 bug 修复不需要贯通路径：先复现，再修复，最后验证。

## 深模块（Deep Modules）

- 先复用现有模块。按职责和所需知识划分边界，不按执行顺序拆分。
- 接口要说明行为、错误和使用前提；尽量通过设计消除错误情况，而不是交给调用者处理。
- 自查：
  - 调用者不读实现，能否正确使用？
  - 新增的层是否隐藏了复杂度？只做转发的层不要加。
  - 同一规则或格式是否散落在多个模块？
  - 调用者是否必须按固定顺序组合多个调用？
- 贯通路径跑通后，扩展前检查一遍边界，清理为了打通而临时加的浅层。

## 单向依赖（Unidirectional Dependencies）

- 依赖只朝一个方向：入口、界面和基础设施依赖业务核心；业务核心不依赖框架、数据库、界面或外部服务的具体实现。
- 模块之间不形成环。新增 import 或调用前，确认不会让两个模块互相依赖。
- 下层需要通知上层或调用外部能力时，由下层定义接口、回调或事件，上层实现或订阅；不反向 import 上层。
- 依赖朝更稳定的方向：容易变化的模块依赖不容易变化的模块，而不是相反。
- 项目已有分层或依赖检查规则时，遵守并运行检查（例如 dependency-cruiser、import-linter、ArchUnit）；没有时，在评审中检查新增依赖的方向。
- 贯通路径为了先跑通而临时引入的反向依赖或循环依赖，在扩展前清理。

## 交付

说明已完成的行为、验证方式和结果、未覆盖的限制，以及本次新增或修改的术语。只实现当前需求，不提前增加没有依据的通用能力。