ai-development-guide

AI 开发者指南 - 技术决策标准与反模式汇总

价值优先的工程实践

持续检查，直到证据表明找到复杂度最低的解决方案；该方案应能实现所需的用户、运营者或维护者价值，同时确保系统正确且易于维护。

• 在已确认的范围内解决已核实的问题，或解决实现目标所需的依赖项；其他发现应连同其所属边界和证据一并报告，不要扩大当前变更范围。
• 只有当当前目标、已核实的约束或有证据支持的重大风险要求时，才引入功能、基础设施、抽象或针对推测性边缘情况的处理。
• 如果仓库证据表明，在已确认的职责范围内进行保持行为不变的维护，可以降低变更歧义、重复归属、缺陷风险，或未来的实现与验证成本，且不会扩大产品的可观察范围，那么应将其视为维护者当前需要的价值。

评估所有已启用方面的总复杂度：用户决策、设置、模式、概念、输出、持久化状态和实现路径，以及相应的用户体验、运行时、实现、测试、文档和维护成本。仅比较可行方案之间存在差异的维度。如果复用现有机制或不新增机制能够以更低的总复杂度实现相同的已确认价值和验证效果，则优先采用。

技术反模式（危险信号模式）

发现以下模式时，暂停受影响的决策并审查设计：

代码质量反模式

1. 在独立维护的位置重复实现同一职责 - 审查重复逻辑是否有相同的变更原因，以及是否应由一个所有者负责
2. 在单个文件中混合多项职责 - 违反单一职责原则（SRP）
3. 在多个文件中定义相同内容 - 违反 DRY 原则
4. 未检查依赖关系就进行变更 - 可能造成意外影响
5. 通过注释禁用代码 - 应使用版本控制
6. 抑制错误 - 隐藏问题会造成技术债
7. 绕过安全机制（类型系统、验证、契约） - 规避语言对正确性的保障

设计反模式

• “先让它能用再说”的想法 - 技术债不断累积
• 拼凑式实现 - 对现有代码进行未经规划的添加
• 对不确定技术的乐观实现 - 假设未知部分“应该能用”，并据此进行设计
• 治标不治本的修复 - 只解决表面问题，未解决根本原因
• 未经规划的大规模变更 - 缺乏渐进式方法

快速失败回退设计原则

核心原则

让所有错误都清晰可见，并能在完整上下文中追踪。优先保证主要代码的可靠性，而非依赖回退实现。过多的回退机制会掩盖错误，增加调试难度。

实施指南

默认做法

• 为每种失败明确规定处理结果：向上抛出、转换为边界的错误契约，或通过获准的回退方式恢复
• 明确呈现失败：错误应清晰可见且可追踪
• 保留错误上下文：重新抛出时包含原始错误信息

可接受回退的情形

• 获准的恢复契约：需求、设计文档、现有边界契约或项目政策明确规定了为何降级行为优于失败
• 业务关键连续性：部分功能优于完全不可用时
• 平滑降级路径：明确定义了降级后的服务级别

层级职责

• 基础设施层：

  • 保留原始原因和运行上下文
  • 按调用方边界契约要求的形式传播、转换或返回故障
  • 仅在边界由基础设施层负责时执行基础设施层所有的清理或重试；业务恢复决策仍由应用层负责

• 应用层：

  • 做出由业务驱动的错误处理决策
  • 仅当已接受的恢复契约定义了降级结果时才实现回退
  • 当诊断或恢复需要时，通过项目既定的日志、指标或用户可见状态，让回退的触发可被观察

错误屏蔽检测

审查触发条件（需要设计审查）：

• 添加的错误处理程序重复或割裂了现有的恢复职责
• 同一故障在多个层级被捕获，却没有唯一的恢复责任方
• 嵌套处理程序掩盖了哪些状态已提交、已回滚或已暴露
• 处理程序将故障转换为成功或默认输出，却没有可观察的降级状态契约
• 错误处理程序返回默认值但不记录日志

如果另一个处理程序负责不同的故障模式，且有文档明确规定其恢复责任方、状态结果和可观察信号，则可以保留。

实现任何回退之前：

1. 找出定义该回退的已接受需求、边界契约、项目策略或设计文档条目
2. 记录业务理由
3. 在负责诊断或恢复的边界处，通过一种现有的 UI、日志或指标渠道，让回退的触发可被观察；若使用日志作为该渠道，则记录一次并对敏感数据进行脱敏
4. 仅当运维需求或项目策略要求时，才添加新的监控或告警

实现模式

AVOID: Silent fallback that hides errors
    <handle error>:
        return DEFAULT_VALUE  // Error hidden, debugging impossible

PREFERRED: Explicit failure with context
    <handle error>:
        <attach operation context>
        IF this boundary owns diagnosis: <log once>
        <propagate error>  // Re-throw exception, return Error, return error tuple

适配：使用适合该语言的错误处理方式（异常、Result 类型、错误元组等）

代码重复的判断标准

当具体实现之间的相似只是偶然，或它们的变更原因不同时，应保持分离。当代码库证据表明多个位置维护着相同的业务规则、算法、验证契约或协同变更职责时，则应进行合并。

合并标准

适合合并的情况

• 业务逻辑重复
• 复杂的处理算法
• 可能需要批量修改的部分
• 验证规则

应避免合并的情况

• 偶然相似（代码恰好相同）
• 可能朝不同方向演进
• 合并会显著降低可读性
• 测试代码中的简单辅助函数

常见故障模式及避免方法

模式 1：错误修复链

症状：修复一个错误后出现新的错误 原因：只修复表面问题，没有理解根本原因 避免方法：修复前用 5 Whys 找出根本原因

模式 2：规避正确性保障

症状：绕过安全机制（类型系统、验证、契约） 原因：为了避免正确性错误而冲动行事 避免方法：使用适合该语言的安全机制（静态检查、运行时验证、契约、断言）

模式 3：未充分测试便实现

症状：实现后出现许多 bug 原因：忽略 Red-Green-Refactor 流程 避免方法：从一个失败的测试开始实现，以验证预期行为

模式 4：忽视技术不确定性

症状：引入新技术时频繁遇到意外错误 原因：未事先调查，就认定“根据官方文档应该能正常工作” 避免方法：

• 在确定性会影响实现或验证决策时，记录确定性

  Certainty: low (Reason: no working examples found for this integration)
  Exploratory implementation: true
  Fallback: use established alternative approach
  

• 对于低确定性的情况，先编写最小化验证代码

模式 5：对现有代码调查不足

症状：实现重复、架构不一致、集成失败、采用过时模式 原因：实现前对现有代码了解不足；只参考附近文件，却未确认其是否具有代表性 避免方法：

• 实现前，始终搜索类似功能（使用领域、职责、配置模式作为关键词）
• 找到类似功能 → 确认其契约、生命周期和仓库中的用法是否具有代表性；兼容时复用或扩展，否则记录其为何不是有效参考
• 类似功能属于技术债务 → 若其阻碍当前目标、由当前变更导致，或属于已确认的范围，则修复；否则单独报告。如果修复需要架构决策，则创建 ADR
• 不存在类似功能 → 遵循现有设计理念实现新功能
• 在适用的实现或设计记录中，保留每项复用、扩展、分离或修复决策的依据
• 参考模式代表性检查：采用附近代码中的模式或依赖时，先确认它在整个仓库中具有代表性，再予以采用——仅凭附近文件不足以作为依据

质量保障机制意识

执行质量检查前，先识别变更区域适用的质量机制：

• 主要检测：检查变更区域的文件类型、项目清单和配置，确定适用的质量工具
  • 检查 CI 流水线定义中覆盖受影响路径的检查
  • 检查领域专用的 linter 或验证器配置（例如，架构验证器、API 规范验证器、配置文件 linter）
  • 检查项目配置中的领域专用约束（命名规则、长度限制、格式要求）
• 将工作制品提供的验证方法作为针对变更的检查运行
• 将发现的领域专用检查与下方的标准质量阶段一并纳入

质量检查工作流

查明仓库已配置的质量检查入口及其覆盖的类别。将以下类别作为适用的证据检查清单：

• 静态检查：格式化、lint、未使用代码检测、类型检查和已配置的静态分析
• 构建检查：编译或生产构建、依赖项解析，以及已配置的资源验证
• 行为检查：能够测试变更行为的最小已配置测试，以及在变更跨越其边界、生成的骨架要求执行，或仓库门禁包含这些测试时运行的集成或端到端测试套件

若仓库声明了命令组合方式或执行顺序，则遵循该声明；否则，选择符合命令依赖关系且能及时提供有效反馈的顺序。只有所有适用的已配置检查均通过，才算完成。

需要技术决策的情形

抽象的时机

• 只有在仓库证据表明存在共同职责和协同变更模式后，才提取共享抽象
• 注意 YAGNI，只实现当前需要的功能
• 优先考虑当前的简洁性，而非未来的可扩展性

性能与可读性

• 除非性能分析发现可量化的瓶颈（例如响应时间超过 SLA、内存超出分配限额），否则优先考虑可读性
• 优化前先测量
• 优化时通过注释说明原因

契约和接口的粒度

• 过于细致的契约会降低可维护性
• 设计接口时，确保每个方法对应单一领域操作，参数类型采用领域术语
• 使用抽象机制减少重复

范围扩展

• 将实现／编辑指示应用于已接受的结果及其约束范围。
• 将约束请求或已确认结果、期望的未来要求和非目标中的明确限制与数量（“一个”“此文件”“仅 X”）视为硬性边界；若仓库证据表明技术制品的实现方式不成立，且修正不会改变这些边界，则将其视为可修正的基线
• 将提及或预期的路径视为调查起点，除非约束来源明确规定这些路径为唯一范围
• 复制／移动／镜像请求要求原样保留内容；只有在提出编辑要求时才编辑内容
• 移植／翻译请求要求保留意图和行为；仅在目标环境有所要求时进行适配
• 如果证据表明相关文件、对称位置和相邻行为是同一已接受结果或一致性约定所必需的，则一并纳入；将无关改进单独报告

实现完整性保障

影响分析：按风险分级的三阶段流程

在实现前依次完成这些阶段。对于不影响公共约定、数据流、集成或配置的独立变更，简要记录或搜索证据即可。对于跨边界、高风险或涉及多个使用方的变更，请使用结构化报告。

1. 发现 - 找出所有受影响的代码：

• 实现引用（导入、调用、实例化）
• 接口依赖（约定、类型、数据结构）
• 与行为相关的测试证据
• 配置（构建配置、环境设置、功能标志）
• 文档（注释、文档、图表）

2. 理解 - 分析发现的每个位置：

• 在系统中的角色和用途
• 依赖方向（使用方或提供方）
• 数据流（来源 → 转换 → 目标）
• 耦合强度

3. 确定 - 根据变更所需的深度，记录受影响单元、风险和实现顺序。对于扩展分析，请使用：

## Impact Analysis
### Direct Impact
- [Unit]: [Reason and modification needed]

### Indirect Impact
- [System]: [Integration path → reason]

### Data Flow
[Source] → [Transformation] → [Consumer]

### Risk Assessment
- High: [Complex dependencies, fragile areas]
- Medium: [Moderate coupling, test gaps]
- Low: [Isolated, well-tested areas]

### Implementation Order
1. [Start with lowest risk or deepest dependency]
2. [...]

只有在发现和理解已涵盖已接受的结果、约束边界和所需的相邻依赖，且每项重大风险都有实现、验证或待解决决策的处理方案后，才能继续。

删除未使用的代码

检测到某项制品因所请求的变更而过时时：

• 检查其调用方和生成／运维用途后，在同一变更中删除
• 如果是否过时尚不确定，或删除会超出已接受结果和约束边界，则予以保留并报告
• 将无关的休眠代码留在实现范围之外

修改现有代码

Required by the requested change? No → Preserve unless the change proves it obsolete
                               Yes → Working and compatible? Yes → Fix/Extend
                                                             No → Repair or replace with migration/rollback evidence

原则：优先采用干净的实现方式，而不是修补有问题的代码