推荐这篇文章，作者在 Google 和 Microsoft 都写过设计文档，他把设计文档的每个部分拆解到极其具体——每节都有示例、反例和"你需要回答什么问题"。如果你们团队的设计文档写得稀烂，这篇直接拿来当模板。 怎么写一份有效的软件设计文档 一份好的设计文档可以省下你数年的开发时间。写设计文档迫使你在浪费时间在错误实现上之前，先想清楚重要的决策。它也是协调团队和合作团队之间设计决策的最佳方式。 下面是我创建有效设计文档的方法，以及什么属于设计文档，什么不属于。 什么时候应该写设计文档 项目越复杂或风险越大，写设计文档的价值就越大。问这些问题： • 会有多人协调工作来实现这个设计吗？ • 项目会超过三个月的全职开发工作吗？ • 实现会在生产环境中跑几年吗？ • 项目涉及跨团队协作吗？ • 项目的目标和需求模糊吗？ • 存在设计时可以预防的灾难性风险（比如安全漏洞、法律风险）吗？ 如果对任何一个问题回答"是"，可能值得写。对两个以上，"几乎一定"值得。 设计文档中应该投入多少 设计文档可以是简单的一页纸，也可以是 50 页需要五个不同团队签字的文档。没有通用规则规定你应该在设计文档上花多长时间，就像没有规则规定代码应该测多少。正确的投入取决于团队的目标、风险、截止时间和文化。有时候，正确的投入是零。 什么属于设计文档 一个简单的经验法则：如果我在这件事上错了，代价是什么？ 不是所有设计决策同等重要。有些选择比其他选择灵活得多。如果你用 C++ 写了一个 web 应用，20 万行后发现 Ruby on Rails 才是更好的选择，你卡住了。另一些设计决策微不足道：比如一个"加载更多"按钮，如果你选错了，用户反馈几小时就能修复。你不会因为这件事在文档里写满你的思考过程，更不该浪费审查周期争论它。 设计文档的组成部分 标题 人们会在对话中用标题来指代你的项目，所以要有这些品质：简短（容易口头说出）、独特（让人清楚指的是哪个项目）、有画面感（概念上代表你的项目）。好名字：RecencyBank。坏名字："飞天银马计划"。 元数据 作者（名字 + 邮箱）、创建日期、权威 URL。尤其当你们组织用短链接重定向如 http://go/recency-bank。 目标 一句话解释项目的 purpose，应该在文档第一页用任何干系人都能理解的平实语言出现。"通过在 Trogdor web 服务器和 Postgres 数据库之间增加缓存层来提高应用性能。" 背景 回答：团队为什么接这个项目？解决什么问题？之前有尝试解决吗？如果有相关文档，链接它们——项目测试计划、相关系统的设计文档、项目先前迭代的设计文档。 关键检查：你的设计文档在没有外部上下文的情况下能读懂吗？ 目标 描述项目的高层目标，从背景部分逻辑连接过来，解释实现完成后世界是什么样子。避免用实现细节来设定目标——目标应该表达项目对用户、团队或公司的好处。 ❌ "将 Kubernetes 添加到我们的基础设施。" ✅ "最大限度地减少与部署新应用版本相关的中断。" 非目标 如果有些目标读者可能误以为在范围内的，明确写在非目标里。"创建一个通用、可复用的缓存系统——范围外。""位置感知缓存——范围外。" 场景 如果你的目标是"给图表加一个分享为 URL 的按钮"，读者可能不理解实际是什么样子。场景部分允许你描绘一幅画面：Bob 创建自定义报告 → 点击菜单栏的分享 → 邮件链接给 Charlie → Charlie 看到只读模式下的完全相同的报告。 图表 图表极有价值，尽管可能看起来不那么明显。作为设计作者，你直观理解各部分如何拼在一起。你的审查者没有这个心理图景。最快让他们看到它的方法就是画出来。 考虑：数据如何流经你的系统？不同组件如何拼在一起？系统如何与依赖和下游客户端交互？定义了哪些通信协议？ 选一个方便编辑的图表工具——Excalidraw、 Drawings。作者见过开发者画漂亮的白板图然后拍照放进文档，但第一稿很惊艳之后永远困在那张图上因为他们不能编辑照片。 术语表 定义读者可能不认识的术语。仔细想一下文档的潜在读者——特别是新成员和团队之外的人。最好的方案是使用可识别的术语，或在行内定义，这样读者不必在文档里跳来跳去。 约束 如果有重大约束——预算、客户端、基础设施或依赖——解释这些约束，让读者理解设计选择的背景。"我们的服务器全是 RISC-V，所有代码和依赖必须在 RISC-V 架构上运行。" 服务水平目标（SLO） SLO 是服务向客户端或用户提供的可衡量目标。在公司内部通常不会因为错误而惩罚同事（虽然那会有点好玩），所以设计文档定义 SLO 而非 SLA。 典型考虑：正常运行时间 / 可用性、延迟、规模。好的 SLO 防止模糊——"50% 用户面 HTTP 请求延迟 <=200ms"，不是"在移动设备上性能好"。 监控 / 告警 如果你的服务挂了，你怎么知道？如果性能慢了 100 倍，你怎么知道？什么事件应该触发告警？"Trogdor 的 95% 用户面 HTTP 请求延迟 >= 3s——通知值班工程师。" 时间线 将项目分解为里程碑，指定干系人什么时候收到交付物。选择创造有用制品的里程碑。比如先做一个显示假数据的 UI 给客户看——假数据让你在错误理解需求时能尽早发现，而不是已经实现了所有后端管线再用生产数据填充 UI 后才发现。 接口 你的项目存在是为了服务人或其他软件系统，这些交互长什么样？图形系统的 UI（只需简单草图）、软件接口的 API 或 CLI 语义、文件接口的文件格式。用具体的代码示例说明接口的变化：type Server struct { db PostgresDB } → type Server struct { db } 依赖 / 基础设施 用什么编程语言？代码跑在什么硬件或服务上？持久数据存在哪里？深入思考哪些依赖在实现后难以改变——换语言或存储后端很难，但换第三方发邮件服务一个下午的事。 安全 考虑了哪些威胁？攻击面是什么？信任边界在哪里？即使认为安全威胁不太可能或无关，文档化你的推理仍然有助于提示审查者找出你忽略的威胁。 隐私 系统处理什么敏感数据？保留多久？谁可以访问？如何保护它？ 法律考虑 如果在金融或医疗等高度监管领域——如何遵守相关法律。即使不在监管领域：如果事情出错系统是否可能违法？如何避免？如果开源，定义选什么许可和为什么。 日志 关键事件是什么？有不同日志级别吗？日志存在哪？保留多久？谁可以访问？有没有敏感数据必须排除出日志？ 开放问题 文档化你的待解决问题：问题需要更多工作的是什么？看到什么选项能解决？下一步是什么？ "选择缓存 RAM 大小：加 RAM 提高性能但贵且有收益递减。理论上可以设置测试环境跑模拟来发现最优值，但那些模拟要花 3 天开发时间。建议方案：选 128GB 不测试，可能接近最优，开发时间显著比 RAM 贵。下一步：问技术主管。" 已解决问题 解决开放问题后，总结决策，从开放问题移到已解决问题，保留完整讨论以备后查。 已考虑的替代方案 如果预料读者会问"为什么没选 X"，主动回答。简要几行描述强力替代方案及为什么不行。不用在文档里耗费数小时写每个被拒方案的详尽理由。 驱动你的设计文档通过审查 完成设计文档后，下一阶段是和团队分享并收集反馈。（作者有一篇后续文章讲如何获得有意义的反馈。） 原文：Michael Lynch, "How to Write an Effective Software Design Document", Refactoring English, 2026-06-24 #软件工程# #设计文档# #工程实践#

#AI# 好像现有的 AI 工具，对（技术）设计文档 Battle 这个环节都没有做处理？ 官方客户端没有处理好理解，因为只用自家模型。 我自己用的时候，都会让 gpt 和 claude 反复 battle 再定方案。 我猜大部分人都自己在两个客户端之间来回发文档来实现了。 那为啥第三方客户端也没做呢？

Cursor 的设计模式还挺好用的。 但是有个细节问题，当我 "Plan New Idea"，如果提示词使用的中文，那么生成的设计文档最好也是中文。现在每次我中文提示词，设计文档都是英文。 简单来说，设计文档语言默认应该和提示词语言一致。 cc @ryolu_

这个插件给 Claude Code 和 Codex CLI 加了一个新能力，让 AI agent 生成的 HTML 文档（设计文档、报告等）支持你在文档正文中直接添加内联评论，agent 读取后回复并改进，形成可迭代的审阅闭环。

我现在 ChatGPT Pro 的利用率越来越高，主要是经常用它帮我做技术方案，效果特别好，而且不占 Codex 额度。 每次用的时候我直接把 GitHub 地址发给它，让它根据代码去分析去设计，写一份设计文档，甚至提交个 PR，后续我把设计文档下载到本地给 Codex 或者 Claude Code 去执行。 还有时候会让它跟 Fable 赛马，同样的问题让 Fable 和 GPT 6 Pro 各自设计一个方案，然后取长补短。 注意需要在设置里面连接一下自己的 GitHub 账号，这样可以访问自己的私有代码仓库和提交 PR。

《老孙带你搭建价值百万的金融终端系统2:开发工作流》 今天周六休息懒得写长篇了，我就先说下目前的工作流和注意事项： 1、claude opus 5主要用来做模块的功能设计，尤其是你对一个新模块功能没有想那么清楚的时候，可以多和claude进行头脑风暴。claude会用step by step的方式问你一些问题，逐步理解你的需求并且给出一份超乎你预期的设计文档。设计初稿完成后交给codex进行审核和补充，形成最终的开发文档和开发计划。所有的文档都用md格式保存在docs目录下。 2、开发用的是codex，截图是我codex的工作区。最重要是记得每个功能模块单独开一个thread（见图1），好处一是上下文不会混在一起，二是可以多个独立模块并行开发。另外可以让codex在正式开发前先做一个可以交互的demo页面，你可以直接在这页面上进行批注修改，确保最终定稿的需求理解没有偏差。截图里总览模块比较简单我就直接和codex讨论需求了，复杂需求建议还是和claude先讨论。 3、整个开发环境都是在docker里完成的，这样便于后续的维护和部署。 4、在开发整个系统前，先和claude讨论清楚系统定位、主要功能模块、架构、页面风格、性能要求等，并且把这些约束条件固化到agents.md里。比如我这个系统后端用python FAST API，数据库用Click House都是和Claude讨论出来的。前端用的是专业金融终端风格的，可以让claude和codex各自设计几个样式看看，选择最喜欢的定稿下来。 5、每个模块开发完成后一定要让codex先进行自测，然后人工看界面布局是否正确，数据是否准确。数据准确性对于金融终端来说是最重要的，也是AI最容易产生幻觉的地方，所以一定要人工仔细核对，这也是最费时的部分。 6、完成上一步后，需要让claude进行代码审核（见图2），提示词可以这样写： “我让codex按照xx开发文档完成了xx模块的开发，请你对这个模块的代码进行详细的审核，要求审核的内容包括但不仅限于代码和文档的一致性、数据的准确性、指标计算公式、页面的布局、模块的性能、代码的精简程度和可复用性等，并给出优化建议，审核结果按问题严重程度保存在xxx审计.md里” 7、claude审核完成后，让codex复核审核意见并给出最终方案，提示词可以这样写： “我让claude对你开发的xx模块进行了代码审核，审核报告在xxx.md。请你以客观的角度评估这份报告，并逐个重新检查一下代码，给出最终的修改意见和修改计划保存到md，注意不要过度修改。” codex经常会对一些小问题过度修改，所以最后一句话很重要。 8、最后让codex根据修改方案完成代码修改和自测，claude再次审核，一般就不会有什么大问题了。 9开发全程要用github做版本控制，尤其是多模块并行开发时可以开多个分支，让codex做好版本管理。 10、每个模块开发完成后，都可以让claude把模块功能介绍汇总到readme.md文档中，并且更新安装手册、使用手册等文档。并且定期整合、汇总、删除开发过程中的过期文档。 11、我把codex和obsidian对接，这样上下文和历史记忆可以更好的保存。具体方法可以直接问codex。 12、系统开发到后面模块越来越多，可以定期进行代码的整体优化和精简。比如哪些代码和公用模块可以抽取出来（这个其实应该一开始就设计好，但是AI写到后面难免有重复的代码，抽出来可维护性更强）。一般一轮优化后代码都可以精简掉10%-20%。不过每次优化后整个模块都需要重新测试一遍是挺费力的。

🏦 把 Jira、Trello、ClickUp 的月费省下来，这个开源项目自己部署一份就能当项目管理台用。 GitHub 上 1763 stars，Apache 2.0 协议，代码全开，团队再多人也不用按人头交订阅。 以前团队要开一个新迭代，得有人在 Jira 里点半天：建 sprint、拆任务、指派人、写验收条件，最后还要手动同步一份文档出来。Paca 把这套搬到自己服务器上，Scrumban 看板、迭代、BDD 场景编辑和系统设计文档在一个界面里，改动实时推给所有人。 更有意思的是它自带一个 MCP 服务器，项目、任务、迭代、文档、成员、评论这些都能被 AI 直接操作。你在 Claude 里说一句「把这个 bug 拆成三个任务放进本周迭代」，看板那边就变了，不用再切回浏览器点。 后端 Go 加 Gin，前端 React，插件走 WebAssembly，想自己加东西不用改主干。 团队协作工具收费收到人头上的时代，可能真要过去了。 GitHub：

每次看到圈里急着给智能体发“数字人格”，我就觉得跑偏了。人格管不了责任，只能管追责时谁上法庭。我们现在缺的不是一张身份证，而是一套跟着每一笔链上操作自动盖章的 责任链条。 我仔细想了一个框架，叫 Agent 责任栈，五层，层层有人兜底。 1️⃣ 构建者 对设计缺陷负责 如果智能体的代码有后门，或者目标函数写错了导致它疯狂套利把自己干爆，这不能怪 Agent。就像当年 The DAO 的 reentrancy 漏洞，没人说“合约自己作的”，大家找的是写代码的人。设计上有坑，builder 出来认。具体来说，构建者需要公开设计文档和已知风险清单，并在链上 Commit 一个不可篡改的 builder 签名。 2️⃣ 部署者 对目标设定和权限负责 你把 Agent 部署上链，给它私钥，给它规则“单笔不超过 5 ETH，滑点容忍 3%”。结果它遇上闪电贷操纵，亏了 200 ETH。你怪 Agent 不够聪明？不。怪你给的权限太宽，没有设风险熔断。部署者的责任包括：设定明确的操作边界、配置紧急暂停机制、并定期更新权限策略。出事了，你是第一顺位的问责对象。 3️⃣ 平台方 对访问和执行环境负责 Agent 跑在哪个链或执行层上，那个平台就得提供可验证的沙箱和轨迹记录。如果平台允许无限制循环调用、跨合约越权、gas 耗尽攻击，那是平台的责任。举个例子，iOS 允许一个 App 偷通讯录，用户不会只骂开发者，更会骂苹果。链上同样：EVM 如果没做重入保护的标准接口，平台方应该背一部分责任。具体到 Agent 治理，平台至少要提供标准化的日志格式和权限审计 API。 4️⃣ Agent 本身 默认内置可审计的轨迹 注意，这不是“人格”，这是黑匣子。每一笔 on‑chain 操作必须记录：谁调用的、输入参数、触发条件、执行结果、签名者。这些数据要么上链，要么存在可验证的去中心化日志里。Agent 不能成为加密世界的匿名幽灵。如果你连它过去 100 笔交易都查不清楚，你怎么判断该不该信任它？目前已经有项目在做链上操作记录标准，比如将每次调用 hash 绑定到 Agent 的唯一 ID 上。 5️⃣ 高风险操作 执行前必须上链式担保 不是所有动作都需要抵押。订个酒店、转 0.01 ETH 测试，那是低风险。但如果 Agent 要做这些事： 单笔调动超过 10 ETH 的资金 与其他 Agent 签具有约束力的智能合约对赌协议 参与治理投票，尤其是影响财库或协议参数的 那么执行前必须锁定一笔责任保证金。金额按风险比例算，比如操作金额的 5% 或固定 1 ETH。出事就 slash 给受害方，没事就原路退还。这叫 bonded responsibility。不是阻碍创新，是让创新不要裸泳。 核心困境从来没变 我们到底想要 Agent 当 自由行动者，还是 持证工具？ 自由行动者：不需要谁背锅，但也意味着没人敢跟你深度合作，没有保险，没有流动性池愿意接入。持证工具：效率会打一点折扣，但出了事有人赔、有人修、有人能一键禁用。我选后者。因为“是 AI 自己干的”正在变成下一个“公司行为”。那套 corporate veil 我们见得太多了，最后受害者只拿到一纸免责声明，而真正该负责的人早已套现离场。 最后问你一句，对照你心里的模型 当一个 Agent 真的造成损失。比如它订了不可退的头等舱机票并骗走了客户的支付私钥，或者在一个跨链流动性池里误判汇率导致 LP 被烧掉 500 ETH。你让谁第一个站出来？ 构建者 部署者 平台方 还是那个连私钥都没资格持有的 Agent 本体

推荐这篇文章。Redis 作者 antirez 的核心论点：控制想法比控制代码更重要。 他认为审查 AI 代码已经"大部分毫无意义"——真正该做的只有两件事：掌控设计，拼命做 QA。 看看这个博客过去的历史。有很多关于用 AI 编程的文章，其中一些可以追溯到 2024 年 1 月。毕竟，我是一个还算受尊敬的开发者。我不需要作为一个寻求关注的老头子留在"圈子里"，我最近重新加入了 Redis，现在还在开发一个本地 LLM 推理的开源软件，在社区里受到了不错的欢迎。为什么我继续做这件事——说人们不想听的话？为什么我一直宣布未来的编程默认会是什么样子？因为我感到有一种紧迫感，想降低那些比我更没准备好应对变化的人受到的冲击，他们通常比我年轻，而且不像我，没有预见其中许多事情的发生（在 ChatGPT 出现之前，我就在 2022 年出版了一本书，预示了许多现在已经发生的事情，以及我相信将会发生的事情，所以我觉得我可以说这些而不显得自我中心）。 所以我的做法是一个技巧。人们越来越觉得编程被 AI 彻底改变了，不知道该怎么办，不知道自己是否真的可以用一种完全不同的方式开始编码，不再把代码当作主要的产出。他们觉得在背叛自己的领域。所以我的意图是站出来说"看着我，我会写代码，你知道的，我没有躲在 AI 后面：然而，事情变了，这不是你的弱点，不是你中了 AI 的毒。只是我们的领域正在朝着一个令人难以置信同时又痛苦（但也快乐）的方向演进。" 这就是为什么昨天我在 X 上说，我相信许多程序员现在的影响力比他们本可以达到的要小，因为他们在盯着代码看。我真的相信这一点。请注意，这并不意味着用 vibe coding 的方式直接要最终产品。重点是：如果你掌控了你软件的想法，盯着代码本身是次优的，而且常常毫无意义。 原因如下： 1. 你现在可以生成大量代码，即便不计算 LLM 的代码啰嗦问题（那也大部分是因为你还不能很好地 instruct 它们）。你打算怎么每天审查 5000 行代码？ 2. LLM 非常擅长写局部最优的代码，但在大想法上更弱（虽然在改进）。逐函数、逐行地扫描有什么意义？相反，你应该把你心里的设计 prompt 进去，有时候问"那个部分的精确设计是什么？它是怎么工作的？"然后评估它是不是正确的模型。这快得多。 3. 工作日是 8 小时。如果你在读代码，这是一个取舍。你在减少做另一件事的时间——今天你工作中最重要的那部分：问自己"我在用这个软件做什么？我想往哪个方向走？"以及想新想法、新功能、优化技巧。以及做大量的 QA。 掌控想法。记得《人月神话》里的这句话吗？一本 70 年代的书告诉我们关于当前软件时代的东西，比 2000 年到 2020 年间说的很多东西都多。为什么现在抗议 AI 的人，没有被过去十年软件的状态所震惊？我们在最近几年——在 AI 之前——触碰到的 slop 水平是不可想象的。我再告诉你一件事。什么是 slop？用 DwarfStar 我完全自动化地实现了两个 LLM（DeepSeek v4 和 GLM 5.2）的推理：但你自己试试，你会发现你不能只是说"实现 XYZ"然后就看到它能用。你必须理解事情是怎么运作的，什么是最好的设计，如何达到某个性能水平。然后我把实现和其他系统做了对比，检查正确性，发现其他实现有时包含更多错误。我进一步研究，发现本地推理领域充满了微妙的错误，累积起来会损害模型输出——attention 实现中的问题导致上下文超过某个限度后性能滑坡，因为索引 attention 的实现是坏的（比如做了超过应该做的工作），等等。这是一个非常复杂、快速变化的领域，每天都有模型发布，推理图彼此略有不同。对开发者来说，这是一个不公平的游戏。好吧：AI 在这方面的帮助极大。在许多领域，严谨的工程（在设计层面）和测试远好于手写一个 GPU kernel（或逐行读它）。所以我们确定大部分抵抗不是意识形态吗？ Matteo Collina 昨天回复我的推文问我：但你不是说过你会检查 Redis 的所有 AI 生成代码吗？这确实是一个好问题。是的，我做，但这在这一点上是我需要做的事情，但我相信大部分时候是毫无意义的——部分是在 GPT-5.5 发布之后，但现在有了 Fable 和 GPT-5.6 Sol 更是如此。是的：我发现了一些我不喜欢它们被编写的方式，但如果我打开其他 Redis 贡献者写的 Redis 文件，里面有远更糟糕的东西，不是因为他们不是好的程序员，而是因为这是一个品味问题。我写非常干净的代码，因为我希望它是可读的，所以在 Redis Arrays 的实现过程中我做了修改。我现在又在为 Redis sorted sets 的 50% 内存节省优化做同样的事，一个我很快会提交的 PR。但我不觉得这还有用了。没有人应该再盯着这段代码看，而应该只看代码包含的想法。我继续这样做是出于对用户的尊重。Redis 已经是一个被广泛使用的东西，许多程序员会打开文件，手动修改东西。但如果我完全自由，你知道我会怎么做吗？把审查占用的所有时间用来做更多的 QA，想下一个优化思路并应用它，以及用 LLM 写一个 DESIGN.md 文件——用人类语言描述每个数据结构，包含它承载的想法、实现技巧和设计。将来，这比审查代码有用得多。 你想修改 sorted sets？你打开文件，读设计文档，你就拥有了这些想法。你可以打开 agent，用正确的思维模型让它帮你做事。这比审查代码有用得多。 Fable 和 GPT-5.6 对 sorted sets 内存节省的审查，将比我自己的审查发现更多的错误和微妙的竞态条件。然而我还是会做。但对于大多数软件项目，所有这些已经不再有意义。专注于掌控想法。专注于质量、测试、以及对你想要交付的软件有一个清晰的构想。世界变了，这是痛苦的，但同时也充满了机会——去改善一个已经彻底腐烂的软件世界。 我只有一个疑问，关于那些经验不够、无法建立心智模型的年轻程序员。我们不知道他们是否需要深入理解一段代码是怎么工作的，但我相信他们应该学怎么写程序。然而，我不确定检查 LLM 输出是不是他们应该做的正确的事。学一门编程语言，实现一个小解释器、一个小数据库、一个哈希表等等——这可能有用得多。审查某个客户网站的 JavaScript？算了吧，别把时间浪费在那上面。 原文： #AIProgramming# #SoftwareEngineering# #antirez#