复杂系统里开发最难的不是写代码而是让所有人在同一套认知里对齐。我翻过不少项目的技术债发现很大一部分债都埋在同一种问题里需求文档写得模棱两可、架构图停留在 PPT、代码注释只解释了“怎么实现”却没解释“为什么这么设计”。后来我开始认真用 IDDIntent-Driven Development意图驱动开发推进项目把设计重心前移到一套叫“构块规格说明书”的交付物上情况才明显好转。IDD 不是新一波概念炒作它解决的其实是老问题团队讨论的时候说得明明白白可一到编码阶段就各自理解最终做出来和预期差好几条街。IDD 的核心是先把“要解决的问题”和“系统应该表现出的行为意图”固定下来再把这些意图映射到具体的构块Build Block上并用一份规格说明书把这些构块的边界、职责、接口、状态变化、验收标准写清楚。作为从业者我把它当成了项目启动阶段最重要的检查点也在多个嵌入式、后端和前后端项目里验证过它的价值。这份构块规格说明书听起来像是个文档工作但它真正的价值不在文档本身而在“迫使团队把意图写明白”这个过程。今天我把这套方法、模板、实践案例以及踩过的坑整体梳理出来希望能帮到正在被需求漂移、接口混乱和返工问题折磨的人。1. 为什么要聊 IDD 和构块规格说明书先说个实际场景。有一次我们接了一个内部工具的需求对方说得很简单做一个设备状态看板能让现场人员实时看到运行数据。结果到联调阶段才发现需求方要的不仅是看板还要能远程调整设备参数、按角色做权限隔离、告警要能推送到企业微信。原计划两周的迭代硬生生拖了两个月。问题就出在前期所有人都在聊“功能”却没人把“意图”这件事拆开看。IDD 的思路是把“意图”放在最前面。所谓意图不是一句“我要一个看板”而是清晰的目标结构系统为谁解决什么问题用户在这个系统里想完成什么任务系统在什么约束条件下运行又该通过哪些表现来证明它完成了任务把这些问清楚再去谈功能列表和界面原型才不容易跑偏。构块就是承接意图的最小设计单元。它不完全是传统意义上的“模块”也不是代码里的“类”而是一个有明确职责边界、可以被独立测试、独立评估的行为单元。比如设备看板项目里“实时数据采集”是一个构块“告警通知”是另一个构块“权限控制”又是一个构块。它们之间有调用关系、数据依赖但各自的成功标准必须能单独写清楚。构块规格说明书就是把每个构块的“意图契约”落到纸面上。它回答了三个问题这个构块干什么不干什么怎么证明它干成了通常我们在需求评审阶段就产出这套说明书拿它当开发和测试的共同基准。实践证明这份文档越早产出返工越少越晚产出等于把混乱推迟到了联调阶段。2. IDD 的核心逻辑从意图到可交付模块2.1 意图不是需求也不是用户故事很多团队会把 IDD 里的“意图”误当成 PRD 或者用户故事实际上差别挺大。用户故事关注的是“作为某角色我想要某功能以便获得某价值”它仍然是站在用户视角描述功能诉求。意图则更进一步它要求把“为什么要有这个功能”以及“系统应该表现出什么行为”一并描述清楚。举个例子。“作为运维人员我想要看到设备 CPU 温度”是用户故事。而意图是“设备在长时间高负载运行时有出现过热风险运维人员需要及时发现异常状态以便在故障发生前介入处理”。同样的功能后一种表达方式会自然引出“温度阈值可配置”“告警需要分级”“历史趋势需要展示”等更深层需求。意图驱动本质上是在帮团队避免“把手段当目的”。在实际项目里我习惯把意图拆成几个层次业务意图为什么做这件事、使用意图用户想达成什么结果、系统意图系统应该保持什么行为和约束。每个构块说明书的第一部分就必须写明它承接了哪一层意图。判断意图写得是否到位有一个简单标准去掉所有解决方案词汇后这句话仍然成立。如果成立说明意图是成立的如果不成立说明我们还在功能列表阶段。2.2 构块到底是什么构块在 IDD 语境里是一个偏架构味道的概念它是系统可以独立运作的最小单元。它不一定要对应代码目录或者软件包更多时候对应的是“职责边界”。一个构块通常具备三个特征有清晰的输入和输出、有明确的内部状态、可以被单独测试和评价。比如做后台管理系统“用户认证”是一个构块它接收账号密码或令牌输出会话状态“数据权限过滤”是一个构块它接收用户身份和请求数据输出过滤后的数据集“审计日志”是另一个构块它监听关键操作输出不可篡改的操作记录。这些构块之间有依赖关系但你把其中任何一个抽出来都能单独讲清楚它的行为。划分构块粒度需要权衡。太小了说明书数量爆炸管理成本上去了太大了一个构块承担的职责混杂测试和验收目标又说不清。我常用的判断是一个构块应该能够由一个小团队在一到两次迭代内完成并给出验收结论。如果超过这个范围就该继续拆。2.3 规格说明书解决的痛点构块规格说明书直接打在需求传递链路的三个断点上。一是消除口头理解偏差。开发、测试、产品经理对同一个功能的理解经常不一样。有了一份明确写定“输入输出、状态变化、异常处理”的说明书误会会大大减少。二是让验收有客观依据。传统项目里测试人员靠测试用例猜需求开发人员靠代码注释猜逻辑两边对“完成”的理解经常不一致。规格说明书里的验收标准就是裁判它写清楚了给什么输入、期待什么输出、异常时怎么表现。三是为变更提供锚点。项目到后期最怕改需求但没有说明书更怕。因为没有人能快速判断“这个改动会影响哪些模块”。有了构块及它们之间的关系变更影响范围只需要看依赖图就能定位出来比翻代码高效得多。3. 构块规格说明书的编写方法3.1 第一步识别并拆解意图我会先和需求方开一个意图工作坊用一个问题开场“我希望系统最终为用户改变什么”把答案写在一张白板上然后不断追问“为什么”直到挖出最原始的目标。举个例子如果答案是“让用户能在线报名活动”追问后可能发现原始目标是“扩大活动参与人数并减少线下登记环节”。这个原始目标会直接影响后续设计如果重点是扩大人数那么分享裂变、社交登录就是核心构块如果重点是减少登记环节那么表单自动填充、支付集成才是核心构块。意图拆解完成后我习惯画一张意图树。顶层是业务目标中间是用户使用目标底层是系统行为和约束条件。意图不要急于追求全面覆盖先把最核心的三四个目标说清楚再逐步细化和补全。这个阶段凡是描述里出现具体技术方案的我都会打回去重写。3.2 第二步提取构块清单与依赖关系意图树稳定后开始从意图树中提取构块。方法和功能模块划分有点类似但思路不同我关注的是“哪些行为必须拥有独立边界”而不是“哪些功能要放一起”。比如“通知”这个意图可能同时被告警、审核、营销三个功能使用。如果把它做成独立构块就能避免在三个地方重复实现。判断是否要独立成构块可以看三条规则是否承担了不可再拆的职责、是否需要在多个地方复用、是否有可能独立变化。确定构块清单后梳理依赖关系。依赖关系一般两类强依赖A 必须调用 B 才能完成职责和弱依赖A 在 B 异常时仍可降级运作。在说明书里我会专门用一节记录依赖清单并且注明“如果上游异常本构块应该表现出什么行为”。这个细节在系统联调时非常省心。3.3 第三步为每个构块填写规格说明书模板我用的模板是经过多次项目迭代打磨出来的不同团队可以根据自己的领域裁减。模板固定在八个区块构建块名称: 意图编号: 所属系统: 版本: 1. 职责描述: - 一句话说明本构块存在的意义 - 明确说明不负责什么边界 2. 输入与前置条件: - 输入数据/事件/调用来源 - 前置条件什么情况下构块才会被激活 3. 处理逻辑: - 核心规则与算法描述 - 涉及的分支与异常处理 4. 输出与后置条件: - 正常输出内容 - 后置条件构块执行完成后系统状态 5. 状态模型: - 核心状态及流转条件 6. 接口定义: - 对外提供的关键接口包括参数与返回值 7. 验收标准: - 输入样例、预期输出、异常场景 8. 依赖关系: - 上游依赖、下游影响、变更影响范围这个模板看起来繁琐但一旦填起来就会发现很多模块在设计阶段就暴露了问题。比如接口定义和状态模型填不下去往往意味着职责划分不清楚或者行为没有想完整。此时修改成本很低等代码写完再改就晚了。3.4 第四步评审与基线化说明书写完不是完事必须经过评审会。评审会上我会要求开发、测试、运维、产品每个角色各派代表参加各自只回答一个角度开发看实现可行性测试看验收标准是否可执行运维看部署和监控是否被覆盖产品看意图是否被完整承接。评审通过后把说明书纳入配置管理标记为基线。后续任何需求变更首先要评估变更涉及哪些构块然后更新对应构块的说明书再走评审和基线更新流程。这个动作是为了防止“说明书写完就变成了假文档”它必须和代码一样是被持续维护的一等公民。4. 实例用 IDD 写一个逆变器控制系统的构块规格说明书为了把方法说透这里用一个实际场景来演示逆变器控制系统的固件开发。之所以选这个例子是因为它既能体现“意图驱动”在嵌入式/工业控制领域的应用也能解释“inverter IDD”为什么能成为近期不少工程师讨论的热点。逆变器本身是电力电子里的常见设备而它内部的软件控制逻辑又是出了名的复杂拿它当 IDD 的试金石非常合适。4.1 项目意图描述假设我们要开发一款支持并网和离网模式的双模式逆变器控制系统。先不急着讨论 PWM 周期和通信协议先把意图写清楚。业务意图为用户提供在电网异常时无缝切换到离网供电的能力保障关键负载不断电。使用意图用户在电网正常时不感知设备存在电网掉电时系统应在 10ms 内切换到离网模式并保持输出电压稳定。系统意图控制算法必须支持并网/离网模式切换、具备过压过流保护、故障自恢复、远程监测能力并且所有异常行为要有日志记录。那我们把意图转成构块清单初步会得到模式切换决策构块电压电流闭环控制构块保护逻辑构块状态监控与日志构块通信接口构块每个构块对应一份规格说明书。这里重点看两个典型构块。4.2 重点构块规格说明书示例先看“模式切换决策构块”。它的职责是监测电网状态决定当前控制模式是并网还是离网并触发平滑切换。它的输入是电网电压采样值、电网频率采样值、本地负载功率信息。前置条件是系统已上电并完成自检。处理逻辑里包含“连续 5 个采样点电压低于额定值 70% 判定为电网失效”这个判定阈值和次数必须在说明书中写死否则开发和测试的理解可能不一样。再看“电压电流闭环控制构块”。它的职责是根据当前模式生成 PWM 占空比使输出电压稳定在 220V/50Hz。它接收模式切换构块传来的模式信号以及电压电流反馈量。处理逻辑中需要写明用哪种控制算法如 PI 控制PI 参数初值怎么设定以及输出限幅是多少。这部分如果不写清楚联调时两个人调的参数互相覆盖进度会非常折磨。为了方便阅读我把这两个构块的说明书关键字段整理成一张表字段模式切换决策构块电压电流闭环控制构块职责检测电网状态确定并网/离网模式根据模式与反馈生成 PWM 控制量输入电压采样、频率采样、自检状态模式信号、电压反馈、电流反馈前置条件完成启动自检模式切换已稳定核心规则电压低于额定 70% 连续 5 点判定失效PI 控制输出限幅 0~95% 占空比输出模式信号、切换请求PWM 占空比、控制状态验收标准10ms 内完成模式切换无冲击电压稳态电压误差小于 3%依赖关系依赖采样模块、状态监控模块依赖模式切换模块、PWM 硬件接口4.3 从规格说明书到测试和验收的线索说明书编写完成后最大的受益者是测试人员。比如验收标准里写明了“10ms 内完成模式切换”测试就可以设计一个电网跌落实验在某个时间点切断电网输入通过示波器抓取输出电压波形计算切换所需时间。如果测试结果不符合验收标准可以直接定位到模式切换决策构块的控制逻辑而不是在整套系统里瞎猜。这就是 IDD 的价值所在每个构块的规格说明书都变成了测试用例的来源。负责固件验证的测试工程师可以直接依据说明书里的验收标准编写自动化测试脚本不用再花大量时间翻文档、问开发。我们在实际项目里还专门用一份脚本将说明书中的参数自动生成测试配置把测试启动时间缩短了将近一半。4.4 关于“inverter IDD”的延展思考最近网上“inverter IDD”这个搜索词的讨论度上来了我想不只是因为逆变器这个产品热更多是硬件工程师开始意识到控制系统的软件复杂度已经高到不能靠“直接写代码”来迭代了。一个 50kW 三相逆变器的控制代码动辄几万行涉及不同模式、故障保护、低电压穿越、谐波抑制团队如果没有统一的设计契约靠个人记忆和零散注释根本扛不住。IDD 里的“意图”构块和“规格说明书”把这些复杂度拆成了可管理、可量化、可验收的单元。这种做法在软件行业已经跑通现在开始往逆变器、电机驱动、机器人控制这类嵌入式领域渗透算是顺理成章的事。无论你叫它 intent-driven development还是叫它结构化规格设计核心本质都是先管住意图再动代码。5. 实操中的常见问题与排查5.1 把意图和功能需求混为一谈我见过最普遍的问题就是把“意图”写成了功能清单。比如写了“系统需要显示实时功率”但没有说明谁要看这个功率、看了之后要做什么决策、如果功率异常系统应如何表现。这样的说明书就算写出来和传统需求文档没区别。排查方法很简单每句话都尝试追问一个“为什么”追问到某个目的不再依赖任何系统功能为止。5.2 构块粒度过大或过小粒度太大说明书里会塞进太多逻辑状态模型和接口定义变得很复杂评审会根本开不下去。粒度太小一个微小的参数调整也要改一堆说明书版本管理成了噩梦。我通常以“是否能独立编写测试用例”作为粒度校准线如果一个构块的测试用例写不满三条说明它拆得太碎了如果测试用例写出来像写作文说明粒度太大该继续拆分。5.3 规格说明书要么太重要么太轻有些团队为了追求“全面”把说明书写成了几百页的详细设计维护成本直接压垮团队。有些团队则走另一个极端只写几句话。我的准则很简单说明书里有价值的内容是“别人靠代码和注释看不出来的信息”。比如“为什么采用这个阈值”“变更后会影响哪个模块”这类内容一定要写至于“调用哪个函数”这种代码里一目了然的信息完全没有必要写进说明书。5.4 说明书和代码脱节这是最危险的问题。说明书一旦和代码不一致团队对文档的信任就没了最后回到“一切以代码为准”的原始状态。想要避免脱节必须把说明书的更新纳入开发流程只要代码合并关联了构块行为变更就必须同步更新对应说明书并在 Code Review 中检查。我们团队的做法是在合并请求模板里增加一个选项“是否涉及构块行为变更”如果勾选了提交时必须附带说明书 diff 链接。5.5 变更管理形同虚设说明书定为基线后变更流程如果太松散基线就失去了意义。常见的情况是产品经理临时加一个需求开发为了赶进度直接在代码里改了只留下“相关文档后续再补”的一句话。针对这个情况我会在项目启动时定一个硬规则变更必须先更新构块说明书评审通过后才能安排开发。这条规则第一次执行时会遇到阻力但两三次之后团队体会到好处就再也不会走回头路了。6. 工具选型与协同流程6.1 用什么工具管理 IDD 构块工具不重要习惯才重要。但选对工具确实能降低维护成本。我分别用过几种主流工具各有优缺点简单整理成表工具优点缺点适合场景Confluence结构清晰支持富文本版本对比弱离线不便团队已有协作规范Notion灵活数据库视图方便复杂依赖关系难表达中小团队快速启动GitLab/GitHub Markdown版本管理强可关联代码阅读门槛略高技术团队、代码即文档JetBrains Space与项目管理结合好使用者少使用 JetBrains 工具链的团队纯 Markdown 仓库轻量适应性强需自行维护结构极客风格团队如果让我给一个不折腾的方案我推荐“Git 仓库 Markdown 静态站点生成器”。理由很简单说明书必须和代码一起做版本管理而 Markdown 可以方便地写表格、列表和代码块也方便做 Diff 审查。配合 CI 脚本甚至可以在每次合并请求时自动检查哪些构块被改动过。6.2 一个可直接复用的模板前面给过模板骨架这里再给一份更接近实战的完整模板你可以直接抄去用# 构块规格说明书模式切换决策模块 | 项目 | 内容 | |------|------| | 构块ID | M-01 | | 构块名称 | 模式切换决策模块 | | 意图编号 | I-03 | | 版本 | v1.2 | | 负责人 | 张三 | | 变更记录 | 2025-03-01 初稿2025-03-10 调低阈值 | ## 1. 职责与边界 - 本模块负责电网状态监测与并网/离网模式判定。 - 不负责 PWM 波形的生成该职责由电压电流闭环控制模块承担。 ## 2. 输入与前置条件 - 输入电压采样值1ms 周期、频率采样值、自检结果。 - 前置条件系统上电完成自检通过。 ## 3. 核心处理逻辑 - 电网有效判定电压有效值 额定值 80% 且频率在 49.5~50.5Hz。 - 电网失效判定连续 5 个采样点电压有效值低于额定值 70%。 ## 4. 输出与后置条件 - 输出modeGRID/OFF_GRID触发切换事件。 - 后置条件切换事件被模式管理总线广播切换完成后状态稳定。 ## 5. 状态模型 - IDLE → DETECTING自检完成后进入。 - DETECTING → GRID判定电网有效。 - DETECTING → OFF_GRID判定电网失效。 - OFF_GRID → GRID判定电网恢复。 ## 6. 接口定义 - int getGridState(void); - void setGridThreshold(float voltage, float frequency); - EventHandle registerModeChangeEvent(callback); ## 7. 验收标准 - 模拟电网跌落输入电压降至额定值 60%持续时间 3ms判定 OFF_GRID。 - 模拟电网恢复输入电压升至额定值 95%持续时间 500ms判定 GRID。 - 切换时间从电网失效到输出模式切换信号不超过 10ms。 ## 8. 依赖关系 - 上游依赖采样模块数据源。 - 下游影响影响闭环控制模块、保护逻辑模块。6.3 与现有研发流程的融合很多团队会说“我们已经在用敏捷看板和 DevOps为什么还需要 IDD”。其实 IDD 不是替代品而是这些流程的“前置放大器”。敏捷里每个迭代都在拆用户故事IDD 帮你在拆故事之前先把故事背后的意图和构块定义清楚。DevOps 强调持续交付IDD 保证了每次交付的东西都满足明确的验收标准让自动化测试有据可依。具体落地时可以把构块规格说明书的编写放在迭代规划会之前或者在迭代规划会里分配前几个 story 专门负责输出说明书。这样迭代开发一开始团队拿到的不是含糊的卡片而是带边界、接口、验收标准的构块契约。开发完一个构块直接按验收标准写自动化测试。测试通过构块就算完成进入下一轮集成。7. 一些个人体会和建议这套方法论我实践下来最深的感受是它的价值不是“写文档”而是“逼着团队思考”。很多时候需求方其实不知道自己要什么开发也不知道自己该做什么两个团队就在一片混沌里互相观望。IDD 和构块规格说明书像是一盏探照灯把那些模糊地带全部照出来。写说明书的过程就是在逼所有人回答“你到底想让它怎样表现”这一个问题。我建议第一次落地时不要贪心不要想着把整个系统的构块说明书一次性写全。挑一个核心业务流程比如登录认证、订单处理或者设备控制先写透两三个构块跑完一个完整迭代。只要团队体会到了“按说明书开发”和“自由发挥开发”的差别后面再往其他模块推广阻力就很小了。另外一个容易忽略的点说明书要有一个明确的负责人。这个负责人不一定是架构师但必须对构块的行为边界和验收标准有最终话语权。没有负责人的文档最后一定会失去维护动力变成没人管的僵尸文件。如果你手头有一个正在“写着写着就偏掉”的项目不妨找个最小的模块试试用这套方式写一份构块规格说明书。你可能会发现问题比想象中少得多而返工也比想象中便宜得多。最后分享一个小技巧写说明书时尽量用一个独立的“意图编号”来命名文档而不是用模块名。这样即使模块后来拆分了或者合并了意图还能保持追溯不会断链。