你是来找技术设计文档模板的——章节、标题,能在动手前粘进去的东西。它在下面,拿走就是。但你得知道顺带继承了什么坑:技术设计文档是对着一份 PRD 写一次的,而 PRD 从不停下。有人把需求换了个说法,docs/design/ 里或者 Confluence 上那份设计文档没跟着动,实现就和全队仍然相信的那份 spec 跑偏了。Draftlize 给你同样的八个章节——再把每一节做成一张卡片,连上它所依赖的决策。上游某个判断一变,设计文档当场翻成 drift_detected,你的 coding agent 读到的是改过的设计,而不是那份过期的。
这就是整份模板——工程师真正在用的那种软件设计文档形状。放进 markdown、wiki 还是 Google Doc 都行,照抄即可。下一节讲的是:当每个标题不再是一段挂在没人回看的 PRD 下面的散文、而变成一张知道自己前提何时变动的卡片时,会发生什么。
你在做什么、它解决的那一句话问题,并向上链到提出它的 PRD。PRD 说"做什么、为什么";这份文档从那里接手,说"怎么做"。
这份设计负责什么——以及同样吃重的、它故意不负责什么。六周后有人问"系统为什么不做某件事",非目标就是你指给他看的那条线;那件事本就不在范围里。
有哪些组件、它们怎么通信、边界在哪。一张图,加上为它辩护的文字。评审第一眼看的就是这一节,也是上游决策一变最容易被悄悄作废的一节。
实体、字段、关系、迁移。状态存在哪、谁拥有它。这里错了,下面每一个接口都会继承这个错——所以它排在接口之上,而不是和接口并列。
端点或接口、请求与响应的形状、错误语义、版本策略。别的团队照着它来开发——所以它必须对系统真正暴露的东西保持诚实,而不是停在设计当天暴露的样子。
你权衡过的方案,以及最后选的那个,带上理由。这是你未来回头翻"为什么是这么建的"那一节。多数 TDD 跳过它;写了的话,它恰恰是最经得起时间的部分。
你能预见的失败模式——规模、一致性、那个可能靠不住的依赖——以及每一个你打算怎么应对。诚实的风险,写在这里比在事故里发现要便宜得多。
阶段、功能开关、迁移顺序、回滚方案。这份设计怎么不靠一刀切就变成一个跑起来的系统——以及某个前提在线上被证伪时,你怎么退回去。
模板就这些。下面讲:它为什么写完第二天就开始和 PRD 脱节——以及我们怎么治。
很多人把"设计文档"和"PRD"混着叫,而实现跑偏往往就是这么开始的。它们回答的是不同的问题,而 TDD 在 PRD 的下游——这正是 PRD 一动、它就悄悄烂掉的原因。
产品需求文档讲的是问题——用户、要达成的结果、成功指标、约束。它故意不讲怎么做。"用户不用联系客服就能找回账号"是一句 PRD,它对 token、表、端点只字不提,这是有意为之。
技术设计文档讲的是解法——架构、数据模型、接口、让你从那条需求走到能跑的代码所需的取舍。就是在这里,"不联系客服就找回"变成一个签名 token、一张 password_reset 表,和一个带上线计划、做了限流的端点。
因为设计是搭在需求上的,PRD 每一次改动都往下传。把需求收紧成"60 秒内找回、不发邮件",那套 token + 邮件的设计当场就错了——但设计文档不知道,也没人回去翻它一眼。
TDD 最准的时刻是你写完它那一小时——钉死在 PRD 当天的样子。但 PRD 不停在动:需求在会上被换了说法、约束松了、上游一个决策翻了。设计文档冻在落笔那一刻,而它当初对着设计的那个东西已经走开了。
你的架构方案搭在某个决策上——"我们是多租户"、"我们不需要实时"。在 markdown 里,这个前提是一句话,不是一条链接。决策一变,没有任何信号传到设计文档,于是架构悄悄描述了一个你已经不打算建的系统。
把设计文档改到和新 PRD 对齐,是一桩和写代码抢时间的杂活,而代码永远赢。于是 docs/design/ 冻住,实现改追 PR 里的对话,被记录下来的设计和跑着的系统之间,每个迭代都拉开一点。
在 Draftlize 里,TDD 不是一墙散文——每个章节都是一张带类型的卡片:概述、目标与非目标、架构方案、数据模型、接口设计、关键取舍、风险与对策、上线计划。结构化、按 ID 可寻址,能从一个 thread 或另一份 spec 里直接引用,而不是埋在 Confluence 的树里。
每一节都连着它所依赖的上游 PRD 条目和决策。改其中一个,搭在它上面的每张设计卡片就翻成 drift_detected——就像构建系统让改动文件下游的一切全部失效。设计文档在它刚一失同步时就告诉你,而不是接着误导下一个读它的人。
Claude Code 或 Cursor 经 MCP,在写代码前把相关的设计卡片拉出来——因为 drift 会浮出来,它读到的是改过的架构,而不是和上个月 PRD 对齐的那版。设计文档不再是写一次就完的产物,而成了 agent 每一轮都会读的上下文。
设计文档是押在一份不肯停下的 spec 上的赌注。别再靠手去同步它——让它在 spec 动的时候自己举手。留下这八个章节。把它们连到底下的决策,让 drift 自己浮出来。
技术设计文档在你动手造之前，描述你打算怎么造——架构、数据模型、API 设计、关键取舍、风险。它存在，是为了让那些难决策在纸面上被做出、被评审，因为纸面上改起来便宜，而不是等实现做到一半才发现。
概述、目标与非目标、拟采用架构、数据模型、API 设计、关键取舍、风险与缓解、发布计划。非目标和取舍是最经得起时间的部分：它们记下你有意排除的东西，于是半年后没人再去翻一个早已定下的问题。
PRD 说造什么、为什么——问题、用户、需求。技术设计文档说怎么造——满足 PRD 的架构和工程决策。PRD 是输入，TDD 是对它的工程回答。
靠手同步设计文档，每次都输给发版。Draftlize 把每一节接到它所依赖的 PRD 行和决策上，于是其中一个一动，那张设计卡片就翻成 drift_detected——文档在它脱节那一刻就告诉你，编码 agent 读到的是修正后的设计，而不是那份还对着上一版 PRD 的旧设计。
把上面的模板拿走,或者新建一个项目,把 TDD 的各个章节连到它们所依赖的 PRD 和决策,再把你的 coding agent 经 MCP 接上——让设计一直跟 spec 同步,需求一动就把 drift 标出来。
注册送 $5,直接开始