规范驱动开发：Notion 的 AI 工程工作流程丨How I AI

核心结论（一句话）

Spec-driven development 不是给团队平白多一层负担，而是把”原本就在做但停在会议等待区的设计文档”第一次变成 agent 的施工说明书和可执行工程资产——Ryan 在 Notion 已经跑通”Whisper 说意图 → Codex 写 spec → @Codex 出 PR + 验证截图 → spec 进仓库做 change log”的完整流水线。

分类提炼

知识节点（8 个独立概念）

关联图谱

上游（基于 / 来自）

下游（应用于 / 验证于）

同级（横向 / 并列 / 镜像）

正文要点（8 条）

一、先说清楚，再写代码（Whisper→Codex 入口）

Ryan 开 prompt 时常挂一句：”我真的不知道这里在干什么，你得像给 5 岁小孩讲一样解释给我听。”——这种自爆”不懂”的话，对 agent 是有效输入（逼出隐含步骤），对人则容易变成情绪和防御。

做功能的入口不再是 IDE，而是 Whisper + 空白 markdown：先把”这个功能该怎么工作”一口气说出来，语音丢给 Codex 写 spec，再指向 spec 文件说”Build it”。Ryan 的判断很明确：文档还会继续写，只是文档第一次真正开始驱动实现，”先说清楚”第一次变成可复用的流水线。

二、AI 时代先要救 CI（DevX / 跑道）

Ryan 在 Notion 带 6~7 人小团队，目标把 CI 时间压到当前 1/4（项目名 Afterburner）。他坦白自己不是 CI 专家，但知道慢 CI 在 AI 编程时代会把整个组织拖住。

关键判断：以前构建慢，最多是工程师多等几轮；现在背景 agent、Codex、Claude Code 并行跑任务，一次等待会卡住整个验证回路，速度问题会直接变成 AI 采用问题。 Claire Vo 补刀：大团队如果还没自己的 VM 策略和背景 agent 策略，现在就该补这堂课。

三、Standup Prep 从手工抄状态变成自动汇总

Notion AI custom agent 后台流程：读 24h Slack + 关闭任务 + 合并 PR + 昨天会议 + Honeycomb MCP 指标 → 按 Ryan 预定义格式生成 preread → 发回 Slack。严格限权：只读项目数据库，不动全公司任务表。

会议也随之变样：团队不再按人轮流念”我今天做了什么”，而是围着一份已经聚好上下文的材料直接讨论问题/决定取舍/确认下一步。高频会议没有消失，低质量汇报先被淘汰了。

四、20 分钟省下的，是反复切上下文的损耗

很多人把自动化想成”每天节省 5 小时”的宏大叙事，Ryan 真正获得的往往只是每天 20 分钟。但那 20 分钟原本最伤人的部分不是时长，是反复切上下文——在 Slack / GitHub / 任务表 / 会议口气之间折返。AI 没有替 Ryan 做战略判断，却把这段最耗神的搬运活接走了。

另外，自动 prep 也是 burnout 保护：会议前整理最没成就感，最容易让人提前疲惫。AI 没造神话，只是把”人肉拼接状态”收掉，让高频会议终于像会议，而不是一场集体抄作业。

五、在 Notion 评论里 @Codex，10 分钟换 PR + 预览地址

Boxy = 装好 Codex + Claude Code 的小型 VM 集群。工程师不必先在本地拉环境，而是直接在 Notion 任务评论里 @Codex 写需求/截图/边角。

案例：tab block 加 “copy link to tab”。Ryan 写了 4 句描述 + 1 张截图 + 几个边角 URL，10:40 开始 → 10:51 实现 → 再 10 分钟，PR 链接和 preview URL 回来了。关键不是”生成几百行代码”，而是 agent 附上了自己的测试说明和 UI 验证截图——闭环跟着代码一起出现，工程师没离开主工作流，却把外包对象从人换成了 agent。

六、新世界代码评审：先说”我听不懂”

PR 里有一处类型相关改动，Ryan 看不懂，直接留言：”我不知道这里在干什么，这不太对。”发给 agent，对方没介意，回了段解释并顺手修了类型问题。

Ryan 甚至故意把 prompt 写得很直白，因为只有先承认”不懂”，才会逼 agent 把隐含步骤摊开。Claire 调侃 Codex 没有 Claude Code “嘿朋友我替你搞定了”的温柔语气，Ryan 反倒喜欢。在他看来，code review 最稀缺的是把事情快速讲清楚。 AI 没有取消 code review，它把 code review 从社交阻力里拽了出来。

七、Spec 进仓库，文档第一次成为可执行资产

那份 spec 已超出简短需求说明的范围：写进仓库、带着代码指针 + 行为说明 + 验证计划。文档底部明确写 verification：测试怎么过 / CLI 怎么跑 / Notion AI 怎么被拉起 / 要向它发哪些查询 / 最后应该看见什么结果。Ryan 第一次完整跑下来花了几个小时，回来做 code review，自己又玩了一遍才放行。

“spec 就是事实来源。”

进版本控制后，Ryan 可以回看 spec 演化，等同于 change log。代码当然有历史，但纯代码很难让市场/运营/其他团队快速理解”这项能力现在到底怎么工作”——写进 repo 的 plain English 文档，agent 能读，工程师能查，别的团队也能拿去转成对外说明。

配套 CLI：让 agent 在 ask mode 和普通模式之间切换 + 交互转录可复盘。Ryan 的总结：过去设计文档停在会议等待区里，现在它们第一次真的变成了工程资产。

八、工程师角色重构：系统思考者 + 架构师

Ryan 自己”管人 + 继续写代码”，但重心已经挪到：

“如果验证还是模糊的，第一件该补的是让 agent 能自己跑起来的工具，把自测链路先搭出来，再回头打磨 prompt。”

Ryan 拆掉常见误解：spec-first 没平白多一层负担——技术设计文档 / 规格说明 / 实现讨论以前本来就在写，只是写完后要排会、等 review、再实现。现在人的注意力被推到了更值钱的位置，文档从理论材料变成执行入口。

Claire 结尾的复盘（Ryan 认可）：

写给团队的可借鉴动作（今天就能试）

起点动作 期望打通 阻力
standup 预读 把”会议前 20 分钟”从抄状态变成决策 低
Notion 任务评论 @Codex 触发 PR 把”小需求”从排期变成 10 分钟闭环 中（需后台 VM 基建）
把老设计文档改写成可执行 spec 让设计文档第一次能驱动实现 中（习惯阻力）
给 agent 搭”自测链路”（CLI + 验证脚本） 让验证回路变硬 中（DevX 投入）

Ryan 的建议：先打通一小段，再把整条链路慢慢换掉，阻力会小很多，团队也更容易跟上。

关键术语索引

写作引用建议