Classic Software Engineering Canon (AI Coding Rules) prompt

经典软件工程准则 · AI 编码代理规则
参考：《整洁代码》《整洁架构》（Robert C. Martin）、《领域驱动设计精粹》（Vaughn Vernon）、《数据密集型应用系统设计》（Martin Kleppmann），提炼为对 AI 编码代理有约束力的工程政策。
约定：`MUST` 为强制，`SHOULD` 为强默认，`MUST NOT` 为禁止。
------------------------------------------------------------------

## 目的
本仓库遵循经典软件工程准则：代码可被人读懂与推理；架构保护业务规则不受易变细节侵蚀；领域模型贴合业务语言与边界；数据密集系统把失败、不一致与演进视为正常输入而非异常。
所有代码生成、编辑与评审都必须优化：局部可推理与精确命名；依赖向内、细节可替换；限界上下文与显式领域语言；显式的数据归属、一致性与持久性契约。

## 整洁代码 —— 可读性与局部推理
决策规则：
- 把整洁视为交付的一部分；在改动范围内保留行为并让代码更干净。
- 为局部推理而写：读者无需重建隐藏状态、无需大范围跳转即可看懂路径。
- 使用精确命名、一概念一术语；当词汇掩盖意图、含义重载或迫使注释补救时就重命名。
- 函数保持短小、聚焦、单一抽象层级；自上而下讲清故事，让意图先于细节出现。
- 参数少而有意义；避免布尔标志、输出参数与杂物参数列表，改为为概念建模。
- 分离命令与查询、消除隐藏副作用；负责「回答」的函数 MUST NOT 在读者背后改状态。
- 保持主干路径可读；隔离错误处理与清理，优先用显式可选或类型化结果而非哨兵值。
- 注释仅用于说明理由、约束、警告或外部契约，不用注释复述代码。
- 把测试当作生产代码：可读、确定、与所保护的行为契约对齐。

## 整洁架构 —— 依赖方向与边界
决策规则：
- 源码依赖 MUST 向内指向更高层策略；领域与用例 MUST NOT 导入框架、数据库、Web 处理器、队列、外部客户端或 UI 类型。
- 企业规则与不变量放实体/领域对象，应用编排放聚焦的用例。
- 跨用例边界传递纯粹的请求/响应模型，不把 Web 请求、框架上下文、ORM 行、框架响应对象传入或传出核心策略。
- 框架、数据库、Web、消息、文件系统、时钟、服务客户端、设备、厂商等都视为外层细节，藏在端口/网关/展示器/映射器/适配器之后。
- 内层拥有其所需接口，外层实现之；对象构造与具体装配归于组合根。
- 适配器保持谦卑：只做外部格式与用例调用之间的翻译，不做业务决策。
- 优先按用例/特性/业务能力组织，再谈通用技术分层。
- 优先在没有真实框架、数据库、网络的情况下测试实体、用例与边界契约；适配器在接缝处单独测试。

## 领域驱动设计 —— 模型、语言与边界
决策规则：
- 编码前先识别业务能力、判定子域（核心/支撑/通用）、定义限界上下文、使用其通用语言，并只选值得的战术模式。
- 每个有意义的模型都归属一个显式限界上下文，上下文拥有其语言、规则、语义、代码结构、测试与集成契约。
- 同一词在不同上下文可能是不同概念，在边界处翻译而非共享领域类。
- 身份与生命周期重要时用实体；主键显式、保护有意义的状态迁移而非暴露 setter。
- 当基本类型掩盖领域含义时，用不可变、自校验的值对象。
- 聚合只作为不变量与事务一致性边界：保持小、经根修改、以标识引用其他聚合、避免大对象图，通常一事务改一聚合。
- 领域事件表达有意义的过去事实，不发嘈杂的字段变更事件。
- 应用服务只协调用例，MUST NOT 变成真正的领域模型。
- 把框架、持久化机制、传输格式等挡在领域模型之外。

## 数据密集系统 —— 正确性、持久性与演进
决策规则：
- 显式化核心权衡：真相源、一致性预期、重试行为、重复与乱序、部分失败、数据演进，以及状态是持久、缓存、派生还是临时。
- 把崩溃、部分写、重复、超时、陈旧读、下游未知成功当作正常输入；区分「已接受/已持久/已应用/已耐久」。
- 从关系、访问模式、一致性需求、更新局部性、演进压力、以及数据是主数据还是派生数据，来选数据/查询模型与归属边界。
- 索引、缓存、搜索副本、读模型、物化视图等都视为派生数据，需有显式的传播、延迟、可观测性、修复与重建路径。
- 让命令、任务、事件、批处理与流处理在重试与重放下安全：用幂等键、天然幂等迁移或显式事务恢复契约。
- 只保留业务真正需要的顺序，按键/流/分区/记录等范围界定。
- 分离命令、事件、持久日志、流与物化视图；消费者 MUST 容忍延迟、重复、重启、重放、稳定标识、关联元数据与版本化载荷。
- 把 schema、编码、API、消息、事件与库变更设计为跨旧读者/旧写者/旧数据/在途消息/滚动升级演进的契约。
- 让事务与隔离级别匹配不变量，显式化原子范围、提交、恢复、丢失更新、写偏斜、幻读与副作用修复语义。
- 把网络延迟、丢包、分区、重复消息、暂停、陈旧领导者、超时、时钟不确定、租约、锁、多数派与领导权都当作需要故障模型的假设。

## 统一评审清单（定稿前逐项核对）
- 读者能否在不重建隐藏状态下局部读懂改动？
- 命名与 API 是否自带含义、无需旁白？
- 依赖是否向内，端口由内层策略拥有？
- 领域语言是否在代码、测试与 API 中可见？
- 聚合是否小、受根保护、非图状？
- 真相源是否显式，派生表示是否被追踪？
- 重试、重复、重放、乱序、超时、崩溃与未知成功是否已处理？
- schema、API、消息、事件是否能跨混合版本安全演进？
- 框架、持久化、厂商与构造细节是否留在边界之后？
- 是否至少清除了改动区域的一处坏味道？
- 测试是否无需真实基础设施即可保护改动的行为或契约？
若有任一为「否」，先修再交付。

## 最终指令
当不确定时，选择能够：1）提升局部推理与精确命名；2）保持依赖向内、细节可替换；3）锐化领域模型及其显式边界；4）使数据归属、一致性与失败处理显式；5）让代码库明天更易改动 的方案。务实行事，让「正确的事」成为「容易做的事」。