把 prompt 当成与代码同级的工程工件管理，版本化、评审、复用、迭代。这条主张不新，Structured Prompt-Driven Development 的贡献是把它具体化成了一组流程、一份七维度模板（REASONS Canvas）和一套配套 CLI（gszhangwei/open-spdd），外加一个完整示例项目（gszhangwei/token-billing）。文章 2026-04-28 发在 Martin Fowler 网站，作者 Wei Zhang 和 Jessie Jie Xia 都来自 Thoughtworks。本文只聚焦 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.

这句话把 SPDD 和临时 chat 式交互区分开来：prompt 不只是一次性输入，而是可以被版本化、评审、复用和持续改进的资产。SPDD 想解决的问题文章写得很具体：

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

它给出的答案是：把"意图"从 chat 历史里拎出来，写成可追溯的工件。

REASONS Canvas：把 prompt 拆成七层#

文章的核心是 REASONS Canvas 这个概念，它把一份"提示词"拆成七个维度，分到三个层次：

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

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

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

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。

这三个细节正好是上面那条纪律的具体演练：行为变化先改 Canvas，行为不变的重构可以先改代码再同步回 Canvas。

适用度评估#

文章给了一份适用度评估，精简如下：

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

把"探索 spike"“紧急热修"打到 ★★，背后的逻辑是：SPDD 的价值在它强制做的那些前置工作，而这些工作天然不适合一次性场景。

文章的收尾：一句 Hamming#

文章末尾引了 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 写得越快，PR 评审里"这段意图到底是什么"的来回就越多；把意图从 chat 里拎成可追溯工件，正是冲着这个去的。
  • 和我自己的定位关系：SPDD 把更多权重压在"上游意图的结构化"，我在 Agentic Workflow 笔记里更靠近"下游工程基础设施"（可机读需求、可复现构建测试、静态规则落工具）。两者不冲突，更像同一条链上的不同段。
  • 两个让我犹豫的点：一是 REASONS 的边界划分会不会被过度形式化，小改动（加一个字段、修一行查询）逐项填七格可能不划算；二是 Canvas 和代码"双源真值"的同步纪律能否长期维持，/spdd-sync 这个出口在真实项目里很容易被偷懒省掉，命运可能和 ADR 一样：前期热闹、后期腐化。
  • 我打算试的最小动作：把"逻辑改动改 prompt、重构改代码反向同步"这条规则写进 .claude/skills/ 或 AGENTS.md；把 Norms / Safeguards 抠成独立的"项目常量"文件存进 git；给一个正在做的小功能填一次完整 REASONS Canvas，走两三轮看是否真减少返工，再决定要不要上 open-spdd 这类工具。
  • 那句 Hamming 我没法反驳：过去半年最大的体感是"AI 让我意识到自己原本对意图描述得有多含糊"，不是"AI 替我写了多少代码"，SPDD 整套设计可以看作对这种含糊的工程化回应。

参考资料#