面向 AI 时代的创新编程方法论

执行摘要

期望驱动的智能体开发（Expectation Driven Agentic Development，EDAD）是一套为 AI 时代设计的软件开发方法论：人类开发者与 AI 智能体协同构建复杂系统。与传统“先写规格/需求、再按规格实现”的路径不同，EDAD 把重心放在**期望（Expectation）**上——你对“系统完成后用起来会是什么感觉、会如何表现”的清晰想象。

该方法论来自真实经验：一位开发者借助 AI 智能体，在两个月内构建了三个可投入生产、彼此互联的系统，总代码量 10 万行以上，相当于做出一套 HuggingFace + WandB 生态的完整替代方案。

---

核心哲学

从 Vibe Coding 到 Agentic Coding

Vibe Coding（凭感觉写代码）：

<目标>: 我想做一个价格监控系统

这能提供方向，但对“你真正期待它如何工作”缺乏清晰描述，AI 智能体只能猜测你的意图，输出就更容易跑偏。

Agentic Coding（智能体式编码）：

示例 1：价格监控系统

<期望>: 
做一个价格追踪系统，能跨多个电商站点监控商品价格。用户应该可以：
- 通过 URL 添加商品
- 设置降价提醒阈值
- 当价格低于阈值时收到通知
- 以交互式图表查看价格历史
- 系统应每 6 小时检查一次价格，且不阻塞主流程

<实现细节>:
- 用 Playwright 抓取网页（可处理动态 JS 渲染页面）
- 用 SQLite 存储数据，分别建 products、price_history、alerts 三张表
- 用 APScheduler 做周期任务（非阻塞后台作业）
- 图表渲染用 Chart.js，展示 90 天价格历史
- 限流：同一域名最多每 5 秒 1 次请求

<约束>:
- 抓取代码必须优雅处理网络故障（重试 3 次，指数退避）
- 遵守每个域名的 robots.txt
- 代码必须用 async/await 风格（不写回调）
- 使用 Python 3.10+，全程加类型注解
- 所有面向用户的文本都用英文

示例 2：文档处理流水线

<期望>:
处理用户上传的 PDF：提取文本、图片和表格。用户通过网页上传，
系统在后台处理并展示进度，允许用户下载提取结果。处理需要支持：
- 多页 PDF（最多 100 页）
- 混合内容（文本 + 图片 + 表格）
- 低质量扫描件（需要时使用 OCR）
- 多个并发上传且不会明显变慢

<实现细节>:
- 用 PyMuPDF 直接提取文本（对数字版 PDF 很快）
- 用 Tesseract OCR 处理扫描页（通过“图像/文本比例”检测）
- 用 Camelot 提取表格
- 用 Celery + Redis 队列做后台处理
- 结果存到 S3 兼容存储（本地用 MinIO，生产用 S3）
- 前端用 WebSocket 实时展示进度

<约束>:
- 内存限制：一次只处理 1 页，避免大 PDF OOM
- 超时：每页 30 秒，超时则跳过并记录日志
- 处理完要清理所有临时文件
- 错误状态必须对用户友好（例如“第 15 页失败：图像质量差”，
  而不是直接把堆栈抛给用户）
- 遵循 PEP 8，使用 black 格式化

与 Vibe Coding 的关键差异：

• Vibe coding：只说“我想要 X”（含糊，AI 需要猜实现与边界）
• Agentic coding：给出清晰期望 + 人类做出的关键决策 + 约束
• AI 智能体知道需要实现哪些行为
• AI 智能体知道哪些关键设计已由你定好
• AI 智能体有明确的代码质量边界

关键定义

期望（Expectation）：把某件事“想象成现实”的图景。期望包含：

• 所需功能
• 针对特定功能的技术栈/方案选择
• 针对特定功能的需求与规格

关键区别：期望不同于传统“规格说明书”，它是一种整体性的想象：覆盖从实现过程到用户体验的完整旅程。

实现细节（Implementation Details）：当你让 AI 去实现某个功能/算法时，你可能已经基于期望想好了具体做法，这些具体做法就是“实现细节”。

约束（Constraints）：额外要求，用于让 AI 生成的代码更易于人类审查与维护。

---

EDAD 循环（EDAD Loop）

1. 目标 → 想象（探索阶段）

目标：想象一切已经做完。既要想象“构建它的过程”，也要想象“使用它的体验”。

关注点：

• 行为：系统如何表现？用户交互后会发生什么？
• 用户体验：用起来是什么感觉？是否顺滑、直觉、甚至令人愉悦？
• 结果：它实现了什么？解决了什么问题？
• 可能性：不急着承诺，先探索多种方案

不关注：

• 代码结构（那是问题求解）
• 实现细节（那是问题求解）
• 技术架构（那是问题求解）

活动：

• 整理并表达需求
• 盘点你想要的行为与体验
• 调用过往经验与教训
• 问：**“做完以后会是什么感觉？”**而不是“我该怎么实现？”

关键洞察：这是探索阶段，广度比深度更重要。生成多个潜在方案与愿景。停留在“想象层”，不要进入“实现层”。

重要：想象阶段持续时间取决于目标清晰度：

• 目标很清晰且你很受挫：几天（例：KohakuHub——某次政策变化引发强烈挫败 → 几天集中想象）
• 目标含糊：需要更长探索
• 陌生领域：想象期更长
• 质量比时长重要：3 天的清晰想象 > 3 周的模糊想象

2. 想象 → 期望（收敛/利用阶段）

目标：从你想象出的多种可能性中做选择，并承诺为具体的“期望”。

关注点：“选一个”——选定要构建的方案、行为和体验。

活动：

• 回顾想象阶段的所有可能性
• 选择最有前景/最适合的方案
• 把选择写清楚
• 按层级组织功能与需求
• 识别核心行为与目标结果
• 把期望整理成 AI 智能体可消费的形式

产出：一组已选定、可用于指导开发的期望。

重要：期望应保持一定流动性。你记录期望，是为了看清自己的心智模型，而不是写死规格。等你看到真实代码后，你的期望一定会变化——这很健康，也是正常现象。

3. 期望 → 实现细节（问题求解阶段）

目标：弄清楚如何把期望落地。

关注点：“怎么做？”——此时才决定代码结构、架构和实现方式。

活动：

• 把期望拆成具体特性与组件
• 设计代码结构与架构
• 为每个组件找可行解
• 做架构决策
• 规划实现路线

人类 vs 智能体的职责分工

人类负责：

• 关键的“怎么做”逻辑：复杂算法、非平凡业务逻辑、架构模式
• 系统设计：组件如何交互、数据流、状态管理
• 方案选择：用什么库、什么路线、什么架构模式
• 示例：“使用事件驱动架构 + 消息队列来处理异步流程”

智能体负责：

• 简单的“怎么做”逻辑：直观控制流、数据变换、标准模式
• “把它变成真代码”的怎么做：写代码、补样板、处理语法/格式
• 示例：在你做出架构决策后，负责把实际代码全部写出来

关键原则：开发者拥有重要逻辑与方案设计权；AI 智能体是执行者，不是替代开发者。难的 “how” 你来定，AI 来实现你的决策。

4. 智能体式编码（实现阶段）

流程：期望 + 实现细节 → AI 智能体 → 代码

原则：

• 给 AI 清晰且细致的期望
• 必要时补充具体实现细节
• 设定合适的代码质量约束
• 让 AI 处理机械重复的编码工作

关键洞察：期望会变化

当你看到真实代码成形，你的期望一定会改变。这不是失败，而是方法论在正确工作：

• 实现前：“我觉得用户会想要 X 这么工作”
• 看到真实代码后：“现在看起来，Y 方式更合理”
• 更新后的期望：回到步骤 2（期望）重新整理

为什么会这样：

• 抽象想象和具体代码不是一回事
• 实现会暴露你之前没意识到的限制与机会
• 亲眼看到它跑起来（或跑不起来）会带来新信息

该怎么做：

• 不要抗拒变化，拥抱它
• 根据学习到的新信息更新期望
• 这就是 EDAD 循环的快速迭代
• 记录变化是为了理解你心智模型的演进，而不是把你锁死在旧想法里

5. 验证与修复

目标：验证 AI 生成的代码是否满足期望与实现细节，并能正确运行。

决策点：

如果多次尝试仍然不工作：

• 回到步骤 2（期望）
• 你的目标可能需要调整期望
• 考虑更换技术栈或路线

如果成功：

• 进入下一个目标
• 记录经验教训
• 更新你的期望库（Expectation Library）

6. 更新期望（持续改进）

触发更新期望的典型原因：

• 用户反馈暴露新需求
• 团队成员建议
• 项目目标变化
• 实现过程中发现技术限制
• 性能或可扩展性问题

---

成功的关键

1. 一次想象对应多个期望

一次想象可以分叉出多个期望。方法论难点主要在“探索 + 收敛”两阶段，因为它要求开发者具备：

• 足够的项目经验
• 探索时的广度（能想到多种可能）
• 收敛时的精度（能选对方案）

2. 想象阶段的关注点

在想象阶段，重点是**“做完后会是什么感觉？”而不是“我该怎么做？”**

“怎么做”属于问题求解阶段。把两者分开，能做出更好的架构决策。

3. 动态期望管理

由于一次想象会产生多个期望，真正实现时需要动态调整期望以：

• 适应现实约束
• 响应变化的需求
• 利用实现中发现的新机会做优化

为什么“个人满足感”是最关键指标

期望—满足感的连接

EDAD 与传统方法论的本质不同，在于它围绕期望运转——也就是你对“将会发生什么”的想象。当实现成功时，你不只是“完成任务”，而是把你的想象具象化成现实。

传统开发：

规格 → 实现 → “能跑” → 满足感（较小）

EDAD：

深度想象 → 期望 → 实现 → 现实匹配想象 → 满足感（巨大）

满足感为什么会这么强

1) 先有想象

• 你花时间把完成态想象得很具体
• 你想清楚体验、行为与感觉
• 当现实匹配：强烈的创造满足

2) 意志显化

• 不是在实现别人的规格
• 不是在实现含糊需求
• 是你的想象、你的期望变成现实
• 这对人类心理极其满足

3) 形成反馈回路

• 高满足感 → 更有能量开启下一轮循环
• 低满足感 → 信号：期望不对，需要回到想象/期望阶段
• 满足感成为你判断质量的“指南针”

把满足感当作开发工具

满足感不仅是奖励，还是一种诊断手段：

高满足感：

• ✓ 想象足够现实
• ✓ 期望足够清晰
• ✓ 实现符合愿景
• ✓ 你正在正确使用 EDAD
• → 继续前进，基于成功迭代

成功但满足感低：

• ✗ 想象阶段出了问题
• ✗ 期望没有抓住你真正想要的
• ✗ 想象与期望之间存在断层
• → 回头改进“如何想象、如何形成期望”

失败导致满足感低：

• ✗ 期望不现实
• ✗ 需要调整想象或改方案
• → 学习并迭代

效率—满足感关系

EDAD 同时优化效率（最小时间成本）与满足感（期望被实现）。

传统方法更偏向优化可预测性，代价往往是效率与满足感的牺牲。

EDAD 为什么两者兼得：

1. 少做不必要流程 → 更高效
2. 构建你想象的东西 → 更满足
3. AI 承担枯燥部分 → 你专注创造性工作 → 更满足
4. 快速迭代 → 更快看到想象落地 → 持续满足

代价（trade-off）：

• 你放弃：可预测的排期、提前精确计划
• 你获得：最高效率、巨大满足感、创造性成就

实用建议

把满足感当作反馈：

• 每天结束问：“今天做完的东西我满意吗？”
• 每个功能结束问：“它和我想象的一样吗？”
• 项目结束问：“我还愿意再来一遍吗？”

如果满足感低，做诊断：

1. 我想象得够清晰吗？
2. 我从想象中选对期望了吗？
3. 实现有没有偏离期望？
4. 我的期望现实吗？

让满足感驱动迭代：

• 高满足感 → 对方法更有信心
• 低满足感 → 学习并调整
• 随着熟练度提升，满足感应该逐步上升

---

优势

1. 单人 + AI 的生产力乘数（效率）

EDAD 针对“单开发者 + AI 智能体”的工作流特别设计。真实验证包括：

• 构建 10 万行以上、可投产的全栈应用
• 用 1 个月完成传统团队数月工作量
• 全程保持高代码质量

2. 虚拟实验室与远程优先协作

EDAD 特别适合：

虚拟实验室（Virtual Lab）：

• 一个人负责一个完整项目/模块
• 其他成员作为用户或顾问
• 反馈回路通过调整“期望”而非纠结具体代码

远程协作（Remote-Oriented）：

• 异步反馈循环
• 清晰的所有权边界
• 极低的协作/对齐成本

3. 可扩展的团队结构

面对大项目：

• 产品经理：掌控产品级期望
• 工程师：掌控模块级期望
• 一人一模块：同一时间一个模块只由一人（及其 AI 工具）修改
• 结果：协作效率最大化，合并冲突最小化

4. 清晰的责任边界

• 每个模块都有清晰负责人
• 期望作为模块之间的“契约”
• 期望变更触发明确讨论
• 降低集成噩梦

---

缺点与局限

1. 对开发者要求高

EDAD 要求开发者具备：

• 清晰理解目标
• 对技术栈选择有经验
• 强架构直觉
• 能提出多个方案
• 能评估取舍

缓解：沉淀“期望库”。新手可以通过复用资深开发者的期望模板来学习。

2. 项目中途交接困难

被打断后，很难交接，因为：

• 大量上下文存在于原开发者的想象里
• 期望可能不完整或隐含
• 决策背后的“为什么”未必写清

缓解：

• 维护详细的期望文档
• 记录决策理由
• 每个模块写完善 README
• 与团队定期做期望评审

3. 需要极强的模块化

根据智能体式编码的特性，项目需要：

• 高度模块化架构
• 小而聚焦的模块
• 清晰的组件边界
• 原因：AI 在小型代码库上效果更好；每次智能体编码会话最好只改一小部分

缓解：

• 前期投入架构规划
• 采用微服务等模式
• 尽量让模块控制在 ~1000–2000 行以内
• 定义清晰接口

4. 依赖 AI 能力

• 受限于 AI 智能体能力
• 对前沿/小众技术可能吃力
• 需要一定 prompting 技能

---

实操指南

搭建你的 EDAD 环境

1. 选择 AI 智能体：Claude、GPT‑4 或专门的 coding agent
2. 建立模块结构：项目设计时划清模块边界
3. 准备期望模板：标准化记录方式
4. 配置验证体系：自动化测试、linter、formatter

期望文档模板

重要：这只是帮助你入门的“快速启动模板”，不是硬规则。熟练后，你的期望可以是：

• 与 AI 的对话式提示词（见下例）
• 你脑中的要点
• 粗略草图
• 期望 + 实现细节的混合体
• 任何能捕捉你思考的形式

下面的模板是“训练轮（training wheels）”，用到你形成自己的自然风格为止。

## 功能：[功能名]

### 期望
[从用户视角描述功能做什么]
[包含具体行为与边界情况]

### 技术栈选择
[指定选用技术及原因]

### 实现细节
[具体实现路线]
[关键算法或模式]

### 约束
[代码质量要求]
[性能要求]
[兼容性要求]

### 成功标准
[如何验证功能正确工作]

真实案例（KohakuBoard 的 run 管理重构）

这是实践中真实的“期望长相”——一段对话式提示词，混合期望与关键实现细节：

我想重新设计本地日志结构和 run id 的方案：
  1. 在本地日志中，我们用 <folder>/<project>/<random_str>_<annotation(run_name)>
     这意味着本地日志仍然可以包含多个 project，用户也可以直接
     通过“删除文件夹/重命名文件夹”来管理 runs
  2. random_str 只用 4 位字符（0-9a-z，36^4 大约 160 万，对单个 project
     来说足够用来做文件夹名）
  3. 这套方案对本地与远端都适用（远端则是 folder/user/project/...）
  4. 你需要修改 frontend/backend 的 kobo open，让它能列出 project 级视图
  5. 你需要修改 logger/server，让它正确处理这种文件夹命名
  6. “run_id” 仍然是文件夹名，但现在我们用 run_id 作为标题，
     预定义的 run_name 作为副标题，因为在本地目录里用户可能会直接改文件夹名
  7. 确保相关功能也都能工作（比如 kobo inspect）

  试着查看我们当前代码库，并给我你的实现计划

为什么这是 EDAD 风格：

• 期望清晰：用户通过文件夹操作（删/改名）来管理 run
• 关键逻辑由人类决定：4 位随机串（并给出理由：36^4 ≈ 160 万）
• 贴近现实：第 6 点承认用户会直接改文件夹名
• AI 的任务明确：检查代码库并给出实现计划
• 不拘泥模板：自然沟通，抓住本质

注意：

• 没有死板结构
• “what”（期望）与 “how”（实现细节）混在一起
• 写进去的 “how” 是你的关键决策，不是把 AI 绑死在细枝末节
• 对话式，而非正式规格
• 这就是 EDAD 的真实样子

分层 EDAD 循环（Hierarchical EDAD Loops）

关键原则：EDAD 没有固定的“每日工作流”。它是分层的、长度可变的循环，复杂度越高，循环尺度越大。

分层结构

项目级期望（数月到数年）

目标：“做一个 HuggingFace + WandB 的替代品”
├─ 想象：多年积累的愿景
├─ 期望：包含多个组件的完整生态
└─ 循环时长：数月实现，数年演进

模块级期望（数周到数月）

子目标：“构建高性能的 ML 实验追踪器”
├─ 想象：数周的设计权衡
├─ 期望：KohakuBoard —— 零开销日志记录
└─ 循环时长：数周实现核心，数月打磨成熟

功能级期望（数天到数周）

子子目标：“实现基于 WebGL 的图表渲染”
├─ 想象：数天的 UX 思考
├─ 期望：10 万+ 数据点也要顺滑
└─ 循环时长：数天实现，数周迭代优化

Bug/增强级期望（数小时到数天）

微目标：“修复直方图压缩算法”
├─ 想象：数小时问题分析
├─ 期望：保持 99.8% 压缩率
└─ 循环时长：数小时实现，数天验证

来自真实项目的实践例子

最小循环（小时/天）：

• 修复生产环境发现的 bug
• 加一个用户提出的小功能
• 优化一个性能瓶颈
• 例：“改进 CSV 导出格式” → 想象 30 分钟 → 实现 2 小时

最大循环（年级别）：

• 整个生态系统的设计与演进
• 多个互联系统
• 例：“做 HuggingFace 替代品” → 想象（多年累积的挫败与愿景） → 实现（2 个月密集开发） → 演进（持续进行）

关键特征

循环时长不一致：

• 可能从小时到多年不等
• 无法强行塞进 sprint 或固定节奏
• 每个循环在“期望被满足”时结束
• 高层循环通常包含多个嵌套循环

并行循环：

• 多个模块级循环可并行推进
• 模块负责人各自决定节奏
• 项目级期望负责协调，但不强制同步

自适应节奏：

• 开发者按自然问题求解节奏工作
• 有些天能跑完 5 个功能级循环
• 有些天会深挖一个架构决策
• EDAD 接受这种波动，而不是对抗它

---

与传统方法论对比

根本差异：关注“心智模型”

其他“XX 驱动”方法论大多忽略一个基本事实：人类开发者的认知方式。EDAD 正面承认并利用这一点，而不是试图对抗。

为什么人类无法预测实现时间

两个基本事实：

1) 如果你能预测，就不该重新实现

能预测时间 → 你做过类似的 → 应该复用/复制粘贴，而不是重写

• 可预测任务往往是重复任务
• 你能准确估时，说明你已有模式
• 正确做法：复用代码，不要重造

2) 人类不是神

无法预测 bug → 无法预测调试时间 → 无法预测总时间

• 你不知道你不知道什么
• bug 往往来自意想不到的交互
• 调试时间常常超过编码时间
• 边界情况会在实现时才暴露

这对方法论选择意味着什么

传统方法论（瀑布、敏捷等）：

• 前提：开发者应该估时、可预测
• 现实：开发者在猜，而且经常猜错
• 结果：为了赶不现实的排期 → 技术债、压力与倦怠

EDAD：

• 前提：新工作不可预测
• 现实：把焦点放在效率，而不是可预测性
• 结果：最高速度、高质量、可持续节奏、高满足感

真实的权衡：

• 传统：可预测（但慢且压力大）
• EDAD：高效（但不可预测）
• 两者不可兼得——按你的优先级选择

“心智模型”关注为何能带来效率

传统路径：

外部需求 → 被迫理解 → 实现 → 不满足
(不是你的想象) → (不自然) → (枯燥) → (能量低)

EDAD 路径：

内部想象 → 自然期望 → AI 协助实现 → 深度满足
(你的愿景) → (你的选择) → (高效) → (更有能量继续)

关键洞察：当开发者构建的是“自己想象的东西”（而不是别人塞给你的东西），效率与满足感都会最大化。EDAD 只是把这种自然创造过程形式化。

---

与传统方法论对比（更具体）

vs. 瀑布（Waterfall）

• EDAD：期望会动态演进
• 瀑布：需求前期固定
• EDAD 优势：更能适应变化

vs. 敏捷/ Scrum

• EDAD：单人 + AI、异步协作
• 敏捷：团队仪式、同步协调
• EDAD 优势：模块负责人几乎没有协调开销

vs. 测试驱动开发（TDD）

• EDAD：期望优先
• TDD：测试优先
• 协同点：EDAD 的期望可以指导测试编写
• 差异：EDAD 覆盖 UX/行为，不止是“正确性”

vs. 领域驱动设计（DDD）

• EDAD：与 DDD 兼容
• 共同点：强调理解领域问题
• EDAD 增量：显式利用 AI 来做实现

---

谁适合用 EDAD

理想适用场景

1) 虚拟实验室 / 全远程组织

为什么适合：

• 天生异步——几乎没有协调成本
• 每个人完全拥有自己的模块
• 期望充当沟通契约
• 不需要每日站会或 sprint 规划

例子：研究团队成员分别做一个更大系统的不同部分，通过共享期望而不是会议对齐。

2) 追求速度但不需要固定排期的创业团队

为什么适合：

• 功能一旦满足期望就上线
• 通过更新期望快速转向
• 没有人为 sprint 边界
• 质量达到期望就发版

例子：早期 MVP，优先级随用户反馈频繁变动，目标是“尽快”，而不是“周五必须”。

3) 研究型开发

为什么适合：

• 探索阶段与研究心态一致
• 循环时长的可变性符合研究不确定性
• 可以花数天/数周攻克难题而不内疚
• 关注 “what”（研究问题）而非 “when”（截止日期）

4) 开源社区项目

为什么适合：

• 贡献者按兴趣与节奏参与
• 不需要时间线管理
• 创新改进比可预测交付更重要
• 期望文档记录 “why”，便于后来贡献者理解

不推荐的场景

需要可预测时间线的项目（注意：不是“需要更快”）

为什么不适合：

• EDAD 优化的是效率，不是可预测性
• 你无法提前精确回答“什么时候做完”
• 高效与不可预测并不矛盾，两者同时成立
• 多人同时修改同一代码会冲突
• EDAD 最适合清晰模块所有权

重要澄清：

• EDAD 是最高效的方法——最小化时间成本
• 但你不能事先预测时间成本
• 关键原则：如果你在 deadline 内都无法用 EDAD 完成（考虑到它已是最有效方法），那你很可能用任何方法都做不出来
• 问题是时间不可预测，不是速度不够
• 传统管理通过牺牲效率换来可预测性

例子：企业团队需要提前 2 个月对利益相关方承诺“确切什么时候交付”。EDAD 只能说“尽可能高效”，无法给出高置信的精确日期。

需要紧密协调的项目

为什么不适合：

• 需要清晰模块边界
• 多人必须同时改同一代码时会吃力
• 中途交接困难

例子：游戏开发中，美术、策划、工程不断迭代同一资产。

领域新手

为什么不适合：

• 需要经验才能写出好期望
• 想象阶段需要领域知识
• 初级开发者可能难以做方案选择

缓解：让初级开发者与资深 EDAD 实践者配对，复用期望模板。

---

开始使用 EDAD

前置条件

经验要求：

• 在你的领域有 3 年以上开发经验
• 熟悉多种技术栈与解决方案模式
• 能做架构决策
• 理解系统设计的取舍

心态转变：

• 接受节奏可变：有的功能几小时，有的几个月
• 认可“想象”是一种正当工作
• 相信期望而不是细到每行的计划
• 放下可预测性，换取质量与效率

你的第一个 EDAD 项目

第 1 步：选对项目

适合的首个项目：

• 只有你会改代码的 side project
• 时间线宽松的内部工具
• 开源实验
• 研究原型

避免：

• 硬 deadline 项目
• 多人共享频繁修改的代码库
• 需要 24/7 高可用的生产系统（至少起步阶段别选）

第 2 步：搭环境

1. 选 AI 智能体：Claude、GPT‑4 或 Cursor（合适模型）
2. 建期望文档：先开一个 markdown 文件
3. 规划模块结构：边界要清晰
4. 配置验证：测试、linter、formatter

第 3 步：跑一轮循环

第 1 周：想象

• 花 2–3 天只做思考与可视化
• 先别写代码——会不适应，但很关键
• 问：“做完后会是什么感觉？”
• 画用户流程，不画架构

第 1–2 周：期望

• 把想象写成结构化文字
• 用上面模板
• 聚焦行为而非实现
• 写清成功标准

第 2–3 周：问题求解

• 现在才进入 “how”
• 为每个期望找解法
• 研究技术栈
• 记录实现细节

第 3–4 周：实现

• 用“期望 + 细节”驱动 AI 产出
• 快速迭代
• 别追求完美——相信循环

第 4 周：验证与复盘

• 它符合期望吗？
• 哪些地方出乎意料？
• 下次会怎么做？
• 必要时更新期望

第 4 步：构建期望库

项目完成后沉淀：

• 有效的期望模板
• 常见实现模式
• 成功的技术栈组合
• 经验教训文档

未来复用它们，加速想象与期望阶段。

新手常见错误

错误 1：跳过想象

• 表现：直接开写代码
• 纠正：强制自己先想几天
• 原因：想象差 → 期望差 → 实现差

错误 2：把实现写得太死

• 表现：期望写得像代码
• 纠正：关注行为/体验，不写代码结构
• 原因：会限制 AI 找到更好解法

错误 3：强行固定排期

• 表现：“周五前必须做完”
• 纠正：“当它满足期望时就完成”
• 原因：EDAD 强在质量与效率，不在可预测

错误 4：在共享代码库上做

• 表现：合并冲突、所有权不清
• 纠正：一人一模块，边界清晰
• 原因：EDAD 最适合明确所有权

错误 5：过度写期望文档

• 表现：写成厚厚的规格说明书
• 纠正：期望要流动；写是为了看清思路，不是锁死自己
• 原因：太“规格化”会让期望失去弹性，而期望本就应该在看到真实代码时调整

衡量成功

不要用这些衡量：

• 每个 sprint 的 story points（EDAD 没 sprint）
• 估时准确度（EDAD 优化效率，不优化可预测）
• 用 velocity 预测交付时间（你预测不了 “WHEN”，即使很高效）

应该衡量：

1) 个人满足感（最关键指标）

• 期望被实现会带来巨大满足
• 现实匹配想象 → 高满足感 = EDAD 用对了
• 成功但满足感低 → 期望阶段可能有问题

2) 交付质量

• bug 率
• 用户满意度
• 现实是否符合期望

3) 时间成本（我们在最小化它，但无法预测）

• 记录完成特性的实际耗时
• 观察趋势：期望库越大，是否越快？
• 注意：你在最小化成本，但永远无法提前知道下次要花多久
• EDAD 依然是最高效方法，即使不可预测

4) 期望修订频率

• 实现过程中期望改变的频率
• 熟练后应逐步下降

5) 代码可复用性

• 模块是否能跨项目复用？
• 期望是否导向清晰抽象？

关键原则：EDAD 优化效率与满足感，而不是可预测性。你能最小化时间成本，但无法提前预测。把想象落地的巨大满足感，是这套方法的核心回报。

进阶路径

第 1–3 个月

• 用小项目掌握基本循环
• 建期望库
• 试不同 AI 智能体

第 4–6 个月

• 做中等项目（1–2 万行）
• 练分层循环
• 打磨期望写法

第 7–12 个月

• 大项目（5 万+ 行）变得可行
• 多模块并行循环
• 试着指导他人实践 EDAD

第 2 年+

• 复杂多系统项目（如 KohakuHub 生态）
• 年级别想象 → 月级别实现
• 参与 EDAD 方法论演进

---

EDAD 的未来

随着 AI 能力提升，EDAD 会继续演进：

近期

• AI 更好理解复杂期望
• 更强的整模块代码生成
• 更强的验证与测试能力

长期

• AI 能提出多个“期望备选方案”
• 基于使用数据自动优化期望
• 与 no-code / low-code 平台整合
• 跨团队的期望市场（Expectation Marketplaces）

---

结语

期望驱动的智能体开发（EDAD）代表 AI 时代软件构建方式的一次范式转移。通过聚焦清晰期望、让个体开发者借助 AI 获得强大执行力、并拥抱动态迭代，EDAD 能在保持高代码质量的同时带来前所未有的效率。

它并不适合所有人——它需要有经验、并愿意用不同方式思考开发过程的开发者。但一旦掌握，你将更快构建复杂系统，同时获得“做出架构、而不是被实现细节拖累”的创造满足感。

**EDAD 优化效率与满足感，而不是可预测性。**它是目前最快的方法，即使你无法预测何时完成。把想象变成现实的巨大满足感，是这套方法的核心回报。

从想象开始，以现实收尾，让 AI 架起桥梁。

如需一个完整的现实案例，请参见 附录 A：KohakuHub 生态——三个互联的生产系统（10 万+ 行）在 2 个月内完成。

---

关于这套方法论

EDAD 源自构建 KohakuHub 生态的实践：一个开发者借助 AI 智能体在 2 个月内完成三个互联系统，总计 10 万行以上代码。这篇文档总结了那段密集开发的经验，并会随着新实践持续演进。

该方法论尤其适合：

• 虚拟实验室与全远程研究组织
• 以速度与创新优先、而非排期可预测的创业公司
• 重视探索的研究型开发
• 异步贡献的开源项目

这是一个“活的”方法论。欢迎贡献、改进与案例分享。

---

作者：KohakuBlueleaf（Shih‑Ying Yeh）
联系：kohaku@kblueleaf.net
社区：Discord

最后更新：2025 年 11 月
版本：1.0

---

附录 A：真实案例——KohakuHub 生态

概览

目标：做一个可自托管的 HuggingFace 与 WandB 替代方案
周期：2 个月
团队：单人开发者 + AI 智能体
产出：三个互联系统，总计 10 万+ 行生产级代码

三个系统

1. KohakuHub（约 6–7 万行）

用途：可自托管的 HuggingFace 替代品

核心期望：“为 AI 模型提供 Git 一样的版本管理，并保持 HuggingFace 的即插即用兼容性”

实现的关键特性：

• HuggingFace 兼容 API（可替代 huggingface_hub）
• Git 式版本管理（通过 LakeFS 集成）
• S3 存储后端（MinIO/AWS S3/Cloudflare R2）
• 原生 Git clone 支持（含 LFS）
• Vue 3 Web 界面：文件浏览、编辑、提交历史
• 完整 CLI 工具（带交互式 TUI 模式）
• 管理后台：用户与仓库管理
• 组织（Organizations）与基于角色的访问控制
• 配额管理系统

技术栈：

• 后端：FastAPI、LakeFS（REST API）、PostgreSQL/SQLite
• 存储：S3 兼容（MinIO），LakeFS 用于版本管理
• 前端：Vue 3
• 纯 Python 实现的 Git 服务器

EDAD 循环：

• 想象：在多年对 HuggingFace 政策变化的挫败积累后，集中想象只用了几天
• 关键洞察：目标足够清晰时，想象期无需很长——这就是极致效率
• 期望：“把 HuggingFace 仓库像 Git 仓库一样 clone 到我的服务器，像 Git 一样版本化，兼容标准工具，API 完整兼容”
• 实现：2 个月（与其它项目重叠推进）
• 验证：与 HuggingFace 生态“即插即用”兼容

示例：DatasetViewer（功能级循环）

• 触发：“想不 clone 就能看数据集，用查询模式浏览”
• 想象：花 1–2 天思考 UX——“浏览文件结构、预览内容、搜索/过滤”
• 期望：“提供 Web 界面在不下载的情况下探索数据集结构与内容”
• 实现：几天（FastAPI 路由 + Vue 组件 + S3 集成）
• 结果：可直接在 Web UI 浏览与查询数据集

2. KohakuBoard（约 3–4 万行）

用途：高性能 ML 实验追踪（WandB 替代品）

核心期望：“本地优先（local-first），训练零开销（zero training overhead）”

实现的关键特性：

• 非阻塞日志记录（<0.1ms 延迟）
• 持续吞吐 20,000+ 指标/秒
• 后台 writer 进程 + 50,000 容量消息队列
• 丰富数据类型：标量、图片、视频、表格、直方图
• 基于 WebGL 的可视化，可处理 100K+ 数据点
• 本地优先：kobo open 直接查看实验，不需要服务器
• 混合存储：KohakuVault（列式）+ SQLite
• 直方图压缩：体积减少 99.8%

技术栈：

• 客户端：纯 Python + 后台 writer 进程
• 存储：KohakuVault（自研 Rust + SQLite 引擎）
• 后端：FastAPI
• 前端：Vue 3 + Plotly.js WebGL 图表

EDAD 循环：

• 想象：“如果记录日志永远不拖慢训练？如果不用服务器也能立刻看结果？”
• 期望：“日志调用要在微秒级返回，viewer 必须能顺滑显示 100K+ 点”
• 实现：核心用数周完成，持续迭代
• 验证：真实训练循环中零开销；100K+ 点图表顺滑渲染

3. KohakuVault（约 1.5–2 万行）

用途：高性能存储库

核心期望：“基于 SQLite 的存储，但速度接近内存结构”

实现的关键特性：

• Rust 核心 + Python 绑定（PyO3）
• KVault：带 B+Tree 索引的键值 blob 存储
• ColumnVault：时序数据列式存储
• DataPacker：零拷贝序列化
• 写回缓存：16 KiB payload 下 24k ops/s
• 列操作：缓存下 12.5M ops/s
• CSBTree 与 SkipList 实现，支持有序访问

技术栈：

• 核心：Rust + rusqlite
• 绑定：PyO3
• 存储：单 SQLite 文件 + WAL

EDAD 循环：

• 想象：“SQLite 很适合，但我需要它更快”
• 期望：“Rust 加速 I/O，同时保留 Python 友好 API，缓存友好，微秒级延迟”
• 实现：核心接口数周完成，持续优化
• 验证：基于 benchmark 驱动开发，比朴素方案快 450 倍

项目级 EDAD 循环

全局想象（多年）

多年积累的 ML 基础设施经验：

• HuggingFace：生态很强，但有供应商锁定、难自托管、版本管理有限
• WandB：记录慢、依赖云、团队规模大时昂贵
• 传统方案：搭建复杂、开发体验差

愿景：“如果我能像 clone Git 仓库一样 clone HuggingFace 仓库，同时用零开销追踪实验，会怎样？”

项目级期望（数月）

概念版期望文档：

系统：自托管 ML 基础设施

组件：
1. 模型/数据集托管 + Git 式版本管理
   - HuggingFace API 兼容
   - 原生 Git 操作
   - S3 存储后端

2. 零开销实验追踪
   - 非阻塞日志
   - 本地优先查看
   - 丰富可视化

3. 高性能存储引擎
   - SQLite 基础
   - Rust 性能
   - Python 友好

成功标准：
- 可替代 HuggingFace hub（即插即用）
- 训练开销 < 0.1ms
- 图表可处理 100K+ 点
- 2 个月完成实现

模块级循环（并行）

三条并行 EDAD 循环同时推进：

KohakuHub 循环：

• 第 1–2 周：LakeFS 集成的期望与实现
• 第 2–4 周：API 兼容性的期望与实现
• 第 3–6 周：Git server 的期望与实现
• 第 5–8 周：Web UI 的期望与实现
• 持续：根据使用反馈迭代

KohakuBoard 循环：

• 第 1 周：非阻塞架构的期望
• 第 1–2 周：后台 writer 实现
• 第 2–3 周：存储层期望（引出 KohakuVault）
• 第 3–5 周：WebGL 可视化期望与实现
• 第 5–8 周：丰富数据类型与直方图压缩
• 持续：性能优化

KohakuVault 循环：

• 第 2 周：“SQLite 不够快”的发现
• 第 2–3 周：Rust 引擎期望与初版实现
• 第 3–4 周：KVault 与 ColumnVault 接口
• 第 4–6 周：缓存系统与优化
• 第 6–8 周：高级特性（CSBTree、SkipList）
• 持续：基准驱动的迭代

功能级示例

示例 1：直方图压缩（日级循环）

• 触发：“直方图太占空间”
• 想象：“能不能压到 99% 且不损信息？”
• 期望：“量化 + 变长编码，目标 99.8% 减小”
• 实现：1 天（算法设计 + 实现）
• 验证：用真实梯度数据跑 benchmark
• 结果：达到 99.8% 体积减少

示例 2：DatasetViewer（周级循环）

• 触发：“不 clone 全仓库也要看数据集”
• 想象：“浏览文件、预览内容、过滤/搜索，不下载”
• 期望：“Web 文件浏览 + 预览 + 查询模式”
• 实现：1 周（后端路由 + 前端组件 + S3 流式）
• 验证：可浏览/查询多 GB 数据集而无需 clone
• 结果：完整的数据集探索 Web UI

示例 3：WebGL 图表优化（周级循环）

• 触发：“图表在 50K+ 点卡顿”
• 想象：“商业平台这么顺滑，为什么我的不行？”
• 期望：“用 Plotly.js WebGL 模式 + 智能降采样”
• 实现：3 天（调研 + 实现）
• 验证：测试 100K、500K、1M 点
• 结果：100K+ 点顺滑渲染

示例 4：Run 管理重构（周级循环）

• 触发：“当前 run 管理繁琐，用户想要更简单”
• 想象：“如果用户就直接用文件夹呢？大家都懂文件夹管理”
• 期望：用自然语言传给 AI：

  本地日志结构：<folder>/<project>/<4char_random>_<run_name>
  用户通过删/改文件夹名直接管理 runs
  run_id = 文件夹名（承认用户会改名）
  同时适用于本地与远端

• 实现：1 周（前端 + 后端 + logger 修改）
• 验证：文件夹操作管理 run；kobo open/inspect 等工具正常
• 结果：UX 大幅简化，用户以最自然的方式管理 runs
• 关键点：这体现了 EDAD 的实践形态——对话式期望 + 关键逻辑（4 位随机串、目录结构），而非死板模板

观察到的关键 EDAD 模式

1) 期望级联（Expectation Cascade）

项目级期望（“HuggingFace 替代品”）向下级联：

• → 模块级期望（“Git 式版本管理”）
  • → 功能级期望（“LakeFS 集成”）
    • → 实现细节（“REST API 封装”）

2) 跨模块依赖

KohakuBoard 的存储需求催生了 KohakuVault：

• 原计划：用标准 SQLite
• 现实：对 20K ops/s 太慢
• 新期望：做自研存储引擎
• 结果：KohakuVault 成为独立项目

3) 期望演进

HuggingFace 兼容性期望逐步提升：

• 初期：“支持基本上传/下载”
• 现实：用户需要完整 Git 操作
• 修订：“加入 Git clone 支持”
• 后来：“加入 Git LFS 协议”

4) 循环时长可变

• 小功能/修 bug：小时级
• 核心系统：周级（后台 writer、Git server）
• 整体生态：月级（2 个月密集开发）
• 持续演进：年级（根据使用反馈不断迭代）

结果与影响

量化：

• 约 10–13 万行生产代码
• 3 个互联系统
• 2 个月交付
• 单人开发者 + AI 智能体
• 没有技术债累积

质化：

• 达成 HuggingFace 即插即用兼容
• 实验追踪零训练开销
• 100K+ 点可视化顺滑
• 自托管基础设施真正可用
• 社区开始采用

效率对比：

• 传统团队估算：5–8 工程师、12–18 个月
• EDAD：1 人 + AI，2 个月
• 生产力倍数：约 30–50 倍

经验教训

1. 从用户体验出发：三个系统都从“用起来是什么感觉”开始
2. 让期望驱动架构：KohakuVault 来自 KohakuBoard 的性能期望
3. 相信循环：当 Git server 看似不可能，EDAD 找到了纯 Python 方案
4. 拥抱可变节奏：有些天一口气做完功能，有些天只打磨一个算法
5. 记录期望，而非计划：不要甘特图，不要 sprint，只要清晰期望
6. 把 AI 当实现伙伴：你专注 “what/why”，AI 负责 “how” 的实现细节
7. 以集成为中心，而非计划为中心：系统能自然集成，因为它们共享根期望

---

原文链接：
https://hackmd.io/@KBlueLeaf/Hyoj4qj1bx