# Evidence First Implementation

> 具体类、方法与局部组件的实现规范，用于功能开发、缺陷修复和重构。依据真实代码和行为契约，落实类职责、字段归属、接口语义、封装与继承、资源清理、局部并发和测试，清理被替代的实现；跨组件设计与 workflow-first-design 衔接，简单修改直接实施。

- Skill: `alibaba/evidence-first-implementation` (Agent Skill)
- Install (CLI): `npx get-skill add alibaba/evidence-first-implementation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alibaba/evidence-first-implementation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: alibaba (https://skillmd.com/u/alibaba)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/alibaba/evidence-first-implementation

---


# 类与方法的实现规范

把明确的行为落实为容易理解、容易修改、能够验证的代码。降低状态、依赖、控制流和维护成本；代码行数或类数只是结果，不是优化目标。

## 1. 接住整体契约，限定本次实现范围

与 [workflow-first-design](../workflow-first-design/SKILL.md) 共用行为契约：整体层决定流程、责任边界与跨组件协议，本层落实到类、字段、方法和测试。契约已有于对话、代码或文档时直接复用，不另做整套设计材料。

局部任务先核对输入、预期行为、相关约束和责任类，即可实施。涉及状态或副作用时，再核对失败动作、生效点和清理责任。简单修改按需缩减，不机械生成表格或测试。

以下发现需要回到整体层调整受影响的契约：必须改变策略语义、转移跨组件状态所有权、改变公共协议，或突破系统性能约束。保持契约的字段组织、私有方法拆分、局部算法和封装选择由本层自行决定。不得为了实现方便改变等待、重试、降级、公平性或性能要求。

反例持续导致新增标志、回调和特例时，先检查被推翻的假设及责任边界；不能用补丁掩盖设计缺口，也不因局部缺陷重写系统。只有未决业务含义会改变方案且无法从上下文确认时才询问用户；这不是新增审批流程。

## 2. 用真实路径确定修改位置

阅读实际入口、关键调用方、目标类、相关依赖和测试，确认当前代码与运行环境版本。只追踪与当前假设相关的路径，不无目标遍历系统。

区分观察到的事实、解释和待验证假设。代码中存在某个机制不等于运行时执行了它，错误表象不等于根因。优先选择能区分不同解释的测试、日志或实验；回归问题必要时对照隔离基线。部署、版本或工作区变化后重新确认相关证据。

确定每项修改如何对应需求或必要依赖，再写代码。沿用项目已有的错误、配置、资源管理和扩展约定，不顺手引入框架或额外能力。

## 3. 为类确定职责和不变量

对本次新增或实质调整的类，能回答：它代表什么、负责什么、对外保证什么、依赖谁、何时创建和结束。优先复用已有责任组件，不机械地为每个阶段创建一个类。

- 数据对象承载明确粒度的事实或结果；维护自身数据约束，不暗中登记资源、调度任务或发起网络请求。
- 行为对象执行语义完整的操作；方法名和返回值必须体现实际副作用与保证，不能让“选择”暗含调用方不知道的生命周期责任。
- 协调对象处理必要的多步交接和部分成功；只有独立的跨组件责任确实存在时才引入，不能只是转调或搬运字段。

以上是职责检查，不要求固定分成三类。对象持有资源时明确关闭或释放契约；不能通过换一个 Result、Context、Manager、Execution 名称掩盖混合职责。

继承仅用于稳定的可替换关系：子类必须遵守父类的输入、输出、失败和生命周期约束。仅为复用字段、资源记账或分支代码时，先考虑组合或已有公共能力。基类不应判断子类类型、承载大量可选字段，或要求子类以空实现绕过契约。不为一次调用创建无实际替换需求的接口体系。

## 4. 把字段归属和生命周期落实到代码

涉及重复数据或状态调整时，用紧凑的字段归属表核对；简单字段修改无需填表：

| 字段／事实 | 粒度与含义 | 唯一权威持有者与修改入口 | 读取者／派生副本 | 生效、失效与清理 |
| ---------- | ---------- | ------------------------ | ---------------- | ---------------- |

- 区分请求、一次尝试、节点和一次操作的身份，不能让旧尝试的字段参与新尝试判断。
- 能从可靠现有事实得到的值，通常不另维护一份可变状态。快照、缓存和估算可以存在，但要明确采样时点、更新或失效规则，以及是否计入同一份资源影响。
- 不因字段相似就合并不同粒度的事实，也不在多个结果对象中复制相同生命周期的字段。判断依据是职责和约束。
- 构造完成时尽量形成合法对象。确需分阶段构建时，限制未完成对象的可见范围，避免调用方依赖 setter 顺序、非空字段或多个布尔值猜测阶段。
- 选择明确的修改入口，避免公开可变集合或通过 getter 绕过不变量。不可变快照与活状态引用须有清楚区别。
- 名称沿用领域术语，同一概念同名。handle、lease 等名称只有在语义确实匹配时使用，并解释它代表的具体权利和责任。

## 5. 让方法和接口表达完整语义

方法应完成一个调用方能够解释的操作。必要的连续操作可以放在同一方法中，不为了行数拆成大量依赖隐含顺序的小函数。

- 明确前置条件、输入身份、返回事实、状态变化和异常后的保证；返回“成功”到底意味着计算完成、登记成功、发布还是执行完成。
- 纯计算只接收必要信息，避免为了方便传入整个可变 Context；执行副作用的入口要清楚，但不强制计算与登记分开到破坏原子性。
- 只向上暴露会改变调用方决策的结果。局部版本冲突、内部代际等可在责任组件内消化，诊断信息按需保留；不要把所有底层细节变成上层状态。
- 区分确定未发生、已发生、结果未知。异常或通知失败不能自动解释为安全重放；遵守整体契约中的等待、清理和重试决定权。
- 避免含义不明的布尔参数、重复重载、转调包装和不一致的错误通道。增加结果类型或参数对象应解决实际歧义，而非仅为形式统一。
- 依赖沿责任边界传递。底层不应通过回调、全局对象或反向引用偷偷决定整个流程的策略。

## 6. 在操作边界完成状态与资源责任

把整体设计规定的取得、交接、释放落实到确定的代码位置。检查正常路径和最关键的异常路径：每一步修改谁的状态，下一步失败由谁清理，何时可以安全开始替代操作。

- 取得资源后、尚未放入主记录前发生异常，也必须有释放负责人。责任交接以约定的生效点为准，不能根据字段非空猜测。
- 多资源部分成功时遵守契约规定的保留或撤销范围；需要整体撤销时清理全部实际取得的资源，不硬编码最先失败的组件。
- 区分允许重试与已经能够重试。撤销、临时任务退出和资源清理达到约定条件后才能重放；保留规定的请求身份、优先级、截止时间及完成对象。
- 释放须针对精确操作身份；重复释放或晚到回调不能影响其他请求和新尝试。幂等保护不替代明确的清理责任。
- 一个资源释放失败不应阻断其他独立资源的清理。保留未完成责任和错误，不能把返回失败当成资源已回收，也不能假装成功回队。

优先使用语言和项目现有的作用域清理机制。只有跨调用、异步或生命周期需要时才引入持久管理对象，不以形式统一增加线程、回调和状态机。

## 7. 把并发与性能约束落实到操作范围

指出需要原子的判断与变化，以及其他调用何时能够看到结果，再选最简单的正确同步方式。不预设必须加锁或无锁。

- 检查锁覆盖的数据、锁顺序和持锁调用链。网络、外部回调、阻塞等待和昂贵计算原则上在锁外；必要例外给出依据。
- 用具体交错核对检查与更新、失效与提交、取消与清理、旧回调与新尝试、释放与等待登记。不能仅以有锁、有版本或有原子变量声称整体线程安全。
- 局部变化优先局部更新；重算前核对依赖，区分复用结果重新比较与重新执行昂贵计算。不要为局部冲突默认全表扫描或全局串行化。
- 核对热路径新增的分配、扫描、锁竞争、排队、通知和重试。无锁方案也要解释可见性、重试成本和进展保证；预算和阈值应有依据。

实现无法满足整体约束时，带着具体证据返回整体层调整受影响的方案，不静默削弱保证或新增常量掩盖矛盾。

## 8. 用测试证明行为，按环境验证性能

从行为契约推导测试，优先覆盖最可能推翻实现的边界，观察可见结果与实际副作用，避免逐行复刻实现或只断言 mock 被调用。

纯逻辑适合单测；所有权交接和通知链需要组件或集成验证；运行环境决定行为时沿真实入口验证。Mock 不能替代正在验证的关键机制。局部单测通过不能代替多组件流程验收。

涉及资源、异步或重试时，按改动风险覆盖部分成功、重复调用、取消或超时、晚到回调及关键竞态。尽量用可控同步构造交错，避免靠随机等待证明并发正确。简单、可逆且低影响的修改不为了形式新增测试。

失败测试先判断契约是否改变、实现是否回归或环境是否异常，必要时对照基线。保留仍有效的行为断言，不改期望迁就实现。

用户指定 UT、perf test 或执行环境时按要求完成，不能以本地替代环境通过宣称完成。性能对比核对代码版本、配置、负载、预热和统计窗口，报告相关的吞吐、尾延迟与错误。不得放宽门槛、换负载或隐去异常；单次达标不能证明没有回退。

区分读过源码、实际运行通过和真实环境验证；记录被替代的依赖及证据限制。检查通过后，仅因新变化、失败或未解决风险扩大验证，避免无理由重复运行。

## 9. 随调用迁移清理旧实现，检查最终 diff

方案替换时给出具体的保留、合并、删除项及理由。迁移调用后清理失去用途的入口、字段、重载、包装、重复登记或回滚、配置、mock、测试夹具和旧术语；仍有效的行为测试保留。确需过渡路径时遵循整体方案的退出条件。

交付前通读最终 diff，确认主流程能直接看出触发、决策、执行和结束；新增抽象确有职责，旧机制已删除，没有覆盖用户的其他工作。注释解释必要约束和非显然取舍，不替难以阅读的控制流辩护。

报告实际改变的行为、关键类的责任变化、执行过的验证及未完成项。复杂任务将证据回传整体层完成集成验收；只完成类实现或单测时，不把整体任务标为完成。

