背景：我为什么会去读这篇#

整理 Agentic Workflow 那篇笔记时，我反复卡在同一个问题上：**当 AI 真的开始替我写代码，“需求"和"设计"这两件事到底应该长成什么样？**Spec Kit、AGENTS.md、ADR 都能算是答案，但它们各自只覆盖了一部分。

正好在 Martin Fowler 的网站上看到 Wei Zhang 和 Jessie Jie Xia（两位都来自 Thoughtworks）2026-04-28 发的这篇 Structured Prompt-Driven Development。文章的核心主张比较干脆：把 prompt 当成与代码同级的工程工件管理——版本化、评审、复用、迭代。

这条主张其实不新，但作者把它具体化成了一组流程、一份七维度模板和一套配套 CLI（gszhangwei/open-spdd），加上一个完整示例项目（gszhangwei/token-billing），值得花时间读完整理。

关于 SPDD 与 PDD、Spec Kit、PromptOps 这些相邻概念的差别，我另起了一篇速写：prompt-driven vs spec-driven：把 PDD、SPDD、Spec Kit 几支理清楚。本文只聚焦 SPDD 这一篇文章本身。

这篇文章不是教程，是我读完后留下的几条笔记 + 对照我自己经验的取舍判断。

文章主张：prompt 是一级交付物#

文章开头给的一句话很直接：

Instead of relying on ad hoc chats, SPDD turns prompts into assets that can be: version controlled, reviewed, reused, and improved over time.

如果你把这句拆开看，几乎每个词都在反 vibe 风格：“ad hoc chats”、“assets”、“version controlled”、“reviewed”。SPDD 想解决的问题在文章里也写得很具体：

  • 模糊的需求被快速翻译成代码，误解随之扩散
  • 评审里要处理的改动越来越多
  • 集成 / 测试问题增加
  • 难以推理生产风险

我这段时间使用 AI coding 的体感能对应上前两条——AI 写得越快，PR 评审里"这段意图是什么"的来回越多。SPDD 给出的答案是：把"意图"从 chat 历史里拎出来，写成可追溯的工件。

REASONS Canvas：把 prompt 拆成七层#

文章里我最想抄走的概念是 REASONS Canvas，它把一份"提示词"拆成七个维度，分到三个层次：

抽象层（意图与设计）
  R — Requirements   问题陈述 + DoD
  E — Entities       领域实体与关系
  A — Approach       解决策略
  S — Structure      系统内适配点、组件依赖

执行层
  O — Operations     把策略落成可测试的实现步骤

治理层（横切标准）
  N — Norms          命名、可观测性、防御性编码……
  S — Safeguards     不可协商的边界：不变量、性能、安全

我之前自己写 prompt 时，大部分内容会糊在一起：业务背景、字段定义、要写哪个文件、不要破坏什么——全在一段长描述里。REASONS 的好处不是它的字母好记，而是它强迫你回答"这一段属于哪一层”。Norms 和 Safeguards 单独拎出来之后，那些"通用规则"就不需要每次重写一遍。

Operations 这一格我会盯得最紧：作者要求它精确到方法签名、参数类型、执行顺序。这意味着生成阶段更接近于"忠实翻译已同意的计划"，不是再让模型"发挥"。

六步工作流和一条我最想记住的纪律#

我按六个检查点来理解这个示例流程，其中几步由 CLI 命令支撑：

步骤 命令 / 动作 目的
1 /spdd-story 把大需求按 INVEST 拆成用户故事
2 人工澄清 确保团队对故事的理解一致
3 /spdd-analysis 提取领域关键词、扫相关代码、生成战略分析
4 /spdd-reasons-canvas 生成完整 Canvas，作为可执行蓝图
5 /spdd-generate + /spdd-api-test + 评审 按 Canvas 生成代码，先做行为验证，再审意图对齐
6 生成 unit test prompt / unit tests 在实现稳定后补回归测试

流程本身不算稀奇，但作者夹了一条我读完后最想记住的纪律：

When reality diverges, fix the prompt first — then update the code.

意思是：当评审发现代码与意图有出入，不要直接改代码——先回到 Canvas 里修意图，再让 /spdd-generate 按更新后的意图重新出代码。

为什么这条很重要？因为它直接决定 Canvas 是不是真的"一级工件"。如果手改代码不同步回去，Canvas 就很容易退化成只在第一次起作用的脚手架，再过几个 sprint 没人会去信它，后面也可能又退回 chat-driven 的状态。

作者也在示例里展示了反向情况——纯重构（比如把 magic number 提成常量）行为没变，那就允许先改代码，再用 /spdd-sync 把 Canvas 同步回去。这两条规则合起来：

逻辑变化（行为改变） → 改 prompt → 重新生成代码
重构清理（行为不变） → 改代码    → 同步回 prompt

这是我读完之后会真的考虑试一下的一个细节。

一个具体场景：计费引擎增强#

文章用的示例是一个 Token 计费引擎，从静态定价升级到按方案（Standard / Premium）分档的动态、模型感知定价。三个细节让我印象比较深：

  • 故事整合：两个原始故事被合成一个简化故事，仅保留背景、业务价值、in/out of scope、Acceptance Criteria。AC 用 Given/When/Then 写得很具体，例如 “Given a Standard customer with 100,000 monthly quota… When submitting 30,000 tokens… Then bill shows: 10,000 from quota, 20,000 overage, $0.20 charge.”
  • modelId 字段的可空性问题：评审里发现 modelId 应该是必填、默认 fast-model。作者没有直接改代码，而是先跑 /spdd-prompt-update 修 Canvas，确认后再让 /spdd-generate 做目标性更新。
  • 常量提取：把魔法数提常量是纯重构，直接改代码，再 /spdd-sync 把改动反映回 Canvas。

这三个细节合起来正好是上面那条纪律的具体演练，文章这部分写得比较克制，没有过度推销。

这些主张和我自己在做的事情对得上吗#

我把 SPDD 主张和我前面在 Agentic Workflow 笔记里整理出来的几条前提对一下：

我之前的前提 SPDD 怎么处理
仓库内可机读的需求与设计 REASONS Canvas 本身就是机读形态，存进 git
可复现的本地构建与测试 /spdd-api-test 把行为验证内嵌成步骤
静态可判规则落工具 部分等价于 Norms / Safeguards，但文章没具体推 ArchUnit / Semgrep 这一层
至少一条鉴权可控的 LLM 入口 文章没提，属于团队基础设施层
测试是主要质量反馈手段之一 默认成立——文章里的"行为正确"很大程度上靠 API test

整体方向上是一致的。差别在于：SPDD 把更多权重压在"上游意图的结构化"上，而我之前的笔记更靠近"下游工程基础设施"。两者并不冲突，更像是同一条链上的不同段。

但我也得诚实记录两个让我犹豫的点：

  1. REASONS 的边界划分会不会被过度形式化。Approach、Structure、Operations 三层在大型功能里很有用，但在小改动上（比如加一个字段、修一行查询）逐项填写七格的成本可能不划算。作者自己也把 SPDD 在"紧急热修"和"探索 spike"这两类场景里标成 ★★。
  2. Canvas 和代码"双源真值"的同步纪律能不能长期维持。文章里有 /spdd-sync 这个出口，但实际项目里同步动作会不会被偷懒省掉，我没把握。这跟 ADR 的命运很像——前期热闹，后期容易腐化。

适用度：作者自己也没把它包装成万能答案#

文章里给的适用度评估我比较欣赏，照抄了一份并稍作精简：

适用度 场景
★★★★★ 规模化、标准化交付：高重复业务逻辑、长期可维护
★★★★★ 高合规与硬约束：金融、多渠道部署
★★★★☆ 团队协作与可审计性：多人交付、端到端可追溯
★★☆☆☆ 紧急热修：速度优先于纪律
★★☆☆☆ 探索性 spike：治理开销过高
★☆☆☆☆ 上下文黑洞：领域定义不清
★☆☆☆☆ 创意 / 视觉工作：品味驱动而非逻辑驱动

把"探索 spike"和"紧急热修"打到 ★★ 这一点我比较认同——SPDD 的价值在它强制做的那些前置工作，这些工作天然不适合一次性场景。

我打算抄走的几个最小动作#

读完之后我不打算立刻把整套 SPDD 套到自己项目上。比较小、能立刻试的动作：

  • 把"逻辑改动改 prompt、重构改代码反向同步"这条规则写进自己的 .claude/skills/ 或者 AGENTS.md，至少先约束一下我自己。
  • 把 Norms 和 Safeguards 这两层从每次的 prompt 里抠出来，作为独立的"项目常量"文件存进 git，让 agent 按需引用。
  • 给当前正在做的一个小功能填一次完整 REASONS Canvas，看七格是否真的能减少返工。如果走完两到三次仍然嫌冗长，再砍掉冗余维度，比照"对小改动也成立"的简化版本。

这几步可以先跑一两轮，再考虑要不要装 open-spdd 这类工具；目前没有动机直接上工具。

一个让我停下来想了一下的引用#

文章末尾引了 Richard Hamming 的一句话：

In science, if you know what you are doing, you shouldn’t be doing it. In engineering, if you don’t know what you are doing, you shouldn’t be doing it.

作者用它来论证 SPDD 的本质——AI 时代的软件开发，比拼的不再是模型本身的智商，而是工程师把问题想清楚、框定清楚、做决定的"认知带宽"。

至少这段我没法反驳：过去半年我自己最大的体感不是"AI 替我写了多少代码"，而是"AI 让我意识到自己原本对意图描述得有多含糊"。SPDD 的整套设计可以看作是对这种含糊的一种工程化回应。

参考资料#