写开发设计书这件事在我过去几年的项目生涯里一直是“知道重要但总是做不好”的典型。需求改一版文档改两版代码还没动手光是同步文档消耗的精力就能吃掉一整个下午。尤其是当我带过几个项目之后越发觉得设计书不是写给流程看的而是给未来三个月的自己、给新加入的同事、给评审会上每一位提反对意见的人看的。所以当我看到 Claude Skills 能把“需求 → 开发设计书”这个过程变成一条可复用的标准化流水线时我几乎没犹豫就上手试了。这篇文章就是我这段实践的完整记录Claude Skills 到底怎么手动装、怎么设计一个专属的“开发设计书生成器”、从一两行原始需求到一版能拿到评审会上讨论的设计书要经过哪几步以及我跑了一个月之后踩过的那些坑。如果你也是被文档拖累的程序员、技术负责人或者正在带新人做需求交接这篇文章应该能给你一套可以直接抄作业的方案。1. 写设计书这件事为什么值得自动化1.1 设计书不是“写文档”而是第一道质量闸门先说个可能反直觉的结论设计书最大的价值不是“记录”而是“提前发现想错了”。我见过太多项目需求评审会上大家拍脑袋说“没问题”然后开发到一半发现模块边界没定义清楚、接口字段对不上、异常路径没人管。这些问题如果落到代码里再返工成本至少是设计阶段的五到十倍。而一份合格的设计书恰恰能把这些问题挡在编码之前。但现实是让大家“好好写设计书”几乎不可能。写文档本身是一项需要高度结构化思维的工作而大多数程序员擅长的是在代码里探索不是在一张空白页面里凭空搭建逻辑。结果就是要么文档写得像流水账要么干脆不写等代码写完再补 doc补出来的东西和实际实现早就脱节了。我自己就见过一份周报式的“设计书”通篇只有“用户点击按钮系统返回结果”连字段类型都没有——这种东西写和不写没有区别。自动化生成的意义不是替你思考而是把“结构化输出”这个脏活累活接过去让你把有限的脑力花在真正需要判断的地方需求假设是否成立、方案取舍是否合理、风险是否可接受。1.2 大多数设计书失败的真正原因仔细想一想一份设计书写不好很少是因为作者笨而是因为两个现实约束。第一结构化成本太高。一份像样的设计书至少要包含背景、范围、模块拆分、接口设计、数据模型、业务流程图、异常处理、验收标准。光是把这些章节组织出来就已经是沉重负担更别说每个章节还要互相咬合、前后一致。人脑在连续写两三个小时后很难维持逻辑一致性于是后面章节就开始注水。第二评审对象太宽泛。设计书要给产品、后端、前端、测试、运维一起看。每个角色关心的重点完全不同如果没有清晰的结构评审会就会变成“大家一起看一本小说”效率极低。自动化的思路很简单把“章节骨架、内容组织、一致性检查”这些确定性高的部分交给 AI把这些确定性的规则写进一个 Skill 文件让 Claude 每次输出都按同一套标准来。人只保留两件事输入正确的需求以及对结果说“行”或者“不行”。1.3 为什么偏偏是 Claude Skills而不是普通 prompt 模板有人可能会问我直接把设计书模板贴进 Claude 对话框里不行吗为什么非要搞 Skills我在早期确实就是这么干的后来吃了不少亏。每次都要复制粘贴大段模板对话一长模板就被冲散换了项目还得重新准备团队里每个人手里的 prompt 版本都不一样有的用 Markdown 模板有的用纯文本生成出来的东西风格差异大得离谱。Claude Skills 解决的就是“模板复用”的问题。它把设计书生成的整套方法——包括触发条件、生成步骤、模板结构、自检规则——打包成一个独立模块。Claude 看到你的任务和 Skill 的触发描述匹配时会自动加载这个模块按里面定义的流程走。你不需要每次重复交代背景和格式要求只要说一句“用设计书生成器处理这个需求”就行。而且 Skill 天然适合沉淀团队经验。你可以把团队内部的设计规范、评审要点、命名约定写进 SKILL.md 里以后每个人生成的设计书都是同一套标准。这比我之前用的“复制粘贴 prompt 收藏夹”方案靠谱太多。2. 先搞懂 Claude Skills 的加载机制才能“手动安装”2.1 Skills 的目录结构与触发逻辑最近不少朋友问我“Claude Code 怎么手动装 GitHub 上的 Skills”这背后其实是没搞懂 Skills 的机制。Claude Skills 本质上是一组目录和文件。在 Claude Code 中Skills 通常放在两个位置用户级目录~/.claude/skills/放在这里的技能对所有项目生效项目级目录.claude/skills/放在这里的技能只在当前项目里生效。每个技能是一个独立的子目录里面至少要有一个SKILL.md文件也就是这个技能的核心说明书。SKILL.md的开头有一段 YAML 格式的元信息其中最重要的字段是name和description。不要小看这段description它决定了 Claude 在什么情况下会想起这个技能。Claude 会扫描你当前可见目录下的 Skills然后读description如果发现你正在做的事和描述匹配才把整个SKILL.md加载进上下文。所以description是给模型的调度器看的不是给人看的得写得像一条搜索索引什么场景、什么任务、什么时候用。我见过有人装完 Skills 之后不生效先把整个目录结构和SKILL.md路径贴出来检查往往就是description写得含糊。比如写成“用于开发设计书”就太宽泛写成“当用户需要将产品需求、PRD、功能描述转化为结构化开发设计书时使用”就清晰得多。2.2 手动安装 GitHub Skills 的标准步骤先声明一下我下面写的是社区里最通用的做法针对 Claude Code 环境。不同版本可能在路径细节上有差异但大方向一致。第一步确认 Claude 能读取的 Skills 根目录。你可以在终端里执行# 检查用户级目录是否存在不存在就创建 mkdir -p ~/.claude/skills # 检查项目级目录是否存在 mkdir -p .claude/skills第二步克隆或下载 GitHub 上的技能仓库到对应目录。以用户级安装为例git clone https://github.com/你的账号/你的-skill.git ~/.claude/skills/你的-skill如果只想在单个项目里用就把目标路径改成.claude/skills/你的-skillgit clone https://github.com/你的账号/你的-skill.git .claude/skills/你的-skill第三步验证安装是否完整。进入技能目录检查SKILL.md是否存在ls -la ~/.claude/skills/你的-skill cat ~/.claude/skills/你的-skill/SKILL.md重点确认三件事SKILL.md里面有没有name和description字段是否有其他依赖文件比如模板目录、脚本目录没克隆完整目录名和name字段不要出现明显冲突。第四步重启 Claude Code 会话让技能被重新扫描。装完后你在对话里直接说“列出你当前有哪些可用的技能”如果它能正确说出刚安装的技能名称说明加载成功了。2.3 装完不生效的四个常见原因我帮好几个同事排查过“明明装好了Claude 就是不调用”的问题原因基本集中在下面几类目录层级放错了。技能必须放在skills/技能名/SKILL.md如果你多套了一层目录比如skills/xxx/技能名/SKILL.mdClaude 可能扫描不到。frontmatter 格式不对。name和description必须写在文件最开头外面包着---如果少了前面的---整段元信息就不会被识别。description 太短或太泛。前面已经说过description 是触发索引写得太模糊模型死活不会想到用它。会话没重启。Skills 一般在会话启动时完成扫描你中途装完再继续聊它可能完全不知道你装了什么东西。我自己的习惯是装完任何一个技能之后第一轮对话先让它复述一遍这个技能的职责和步骤确认它真的读懂了再开始干正事。这一步看着多余但能省掉后面大量“我明明说了你为什么不按流程走”的拉扯。3. 手工打造“开发设计书生成器”Skill 的完整设计3.1 先定输入需求描述的统一格式装别人写好的技能只是第一步真正让这套流程在团队里落地通常得自己改一个专门生成开发设计书的 Skill。动手之前第一件事不是写模板而是定义清楚输入。我踩过最大的坑就是你让 AI 从一句“帮我写个请假系统”开始生成设计书它一定会编得天花乱坠。原因很简单信息不足的时候模型只能用平均概率去补全。真的想让它产出可用的设计书必须在一开始就建立一套“需求要素清单”让 Claude 在进入正文之前先按清单萃取信息。这份清单我最终敲定如下目标用户和角色谁会使用这个系统有哪些参与者核心场景用户在这个系统里的主线操作是什么数据对象系统需要管理哪些关键数据数据从哪来、到哪去核心规则有哪些业务规则必须遵守比如审批阈值、余额校验、权限限制。系统边界哪些功能包含在本次范围内哪些明确不做技术约束已经确定的技术栈、平台、集成依赖。非功能要求性能、安全、审计、可用性等。验收口径怎么判断开发完没输入给 Skill 的原始需求可以很粗糙比如说“需求在 docs/requirements.md 里生成设计书”。但 Skill 内部的规定是如果这些要素不齐全第一步必须是向用户提问或列出假设清单而不是直接闷头生成正文。这一步可以说是整个自动化流程质量的分水岭。3.2 SKILL.md 的内部设计逻辑SKILL.md本质上是一个给模型的“标准操作手册”。它不需要写得像教科书但必须让 Claude 知道我这个技能负责什么工作分几步每一步产出什么输出必须满足什么标准。我写的设计书生成器SKILL.md大致长这样--- name: design-doc-generator description: 当用户需要把产品需求、PRD、功能描述、会议纪要等原始需求转化为一份可评审、可落地的结构化开发设计书时使用。适用场景包括新模块开发、接口设计、功能迭代、技术方案评审。需要能获取到原始需求描述或需求文档路径。 --- # 开发设计书生成器 ## 职责 将原始需求转化为结构化、可评审的开发设计书全程保持业务规则、数据模型、接口定义三者一致。 ## 工作步骤 1. 需求萃取 - 提取目标用户、核心场景、数据对象、业务规则、边界、技术约束、非功能要求、验收口径。 - 缺失信息先向用户提问最多列 5 个问题如果用户要求直接生成就列“待确认假设清单”并放入文中。 2. 章节生成 - 严格按模板章节输出背景与目标、范围与边界、总体方案、模块拆分、接口设计、数据模型、业务流程图、异常与降级、非功能需求、验收标准。 - 每个章节必须有实质内容禁止空话。 3. 一致性自检生成后必须执行 - 接口字段是否和数据模型字段一致 - 业务规则是否在流程、异常、验收三处同时出现 - 范围章节说“不做”的事是否在后文悄悄设计进去了 4. 输出 - Markdown 格式使用数字编号标题。 - 在文末附“待决策问题”清单列出需要人工拍板的分叉点。这段SKILL.md很精简但已经能把 Claude 的工作边界框得很死。关键在于第 1 步和第 3 步先萃取需求再自检一致性。这两步不做输出就是披着模板外壳的“一本正经胡说八道”。3.3 设计书模板每一章放在这里的理由模板章节不是越多越好每个章节都必须有明确的服务对象。我自己用下来的版本是这样的模板章节核心要回答的问题主要读者背景与目标为什么做成功长什么样产品、管理层范围与边界做什么、不做什么所有角色总体方案技术上怎么实现架构师、后端模块拆分与职责系统拆成几个部分谁依赖谁后端、前端、测试接口设计各部分之间怎么通信前后端、测试数据模型核心实体和字段是什么后端、DBA业务流程图主线流程、分支、异常路径是什么产品、测试异常与降级出错时系统怎么办后端、运维非功能需求性能、安全、可观测性指标运维、后端验收标准怎么算完成如何验证项目经理、测试你可能会问为什么非要有“范围与边界”和“验收标准”我自己的体会是这两章是设计书里最容易让团队打起精神的部分。范围与边界能把“顺便做个导出”这种需求蔓延挡在评审会验收标准能让测试拿到断言依据而不是临场发挥。模板不是形式主义它是让不同角色在同一张图上各取所需的目录。3.4 内嵌自检规则让输出稳定的关键前几年大家都在吹“AI 帮你写文档”实际用起来最大的痛点是AI 写的东西看起来无比自信但一旦你较真就会发现自己被它带沟里了。所以我的做法是在 SKILL.md 里加了一段强制自检规则让 Claude 自己在输出前逐项打钩接口章节里的每个参数是否都有类型、是否必填、含义说明数据模型里出现的字段和接口参数是否一一对得上异常章节是否至少覆盖了超时、参数非法、权限不足、数据冲突这四类验收标准里是否出现具体数字或可测试的断言而不是“体验良好”“性能稳定”这类废话“范围与边界”里明确不做的内容后面有没有又冒出来这个自检清单看起来不起眼但它把生成过程从“自由写作”变成了“基于约束的生成”。模型在输出之前先自查一遍前后矛盾的几率会大幅下降。我的切身感受是加不加自检规则产出的设计书质量差距是肉眼可见的。4. 一次完整流程从原始需求到可评审设计书4.1 从两行需求开工实际案例推演理论说够了我拿一个真实场景走一遍完整的流程。假设现在接手一个需求原始描述只有一句话“员工可以在系统里提交请假申请主管审批HR 归档超过三天的假期要额外让经理审批。”第一步我不会直接说“开始生成设计书”而是先让 Claude 按 Skill 里的需求萃取流程提问。它会要求我补充员工类型和职级请假类型有哪些余额从哪来主管和经理的关系审批拒绝后能不能重新提交如果不补充它就会在文档开头放一个“待确认假设清单”。这一步的价值在评审会上最能体现。以前大家拿到设计书第一反应是“这方案对不对”。现在拿到手看到的是一份写明了“我按年假、病假、事假三种类型设计余额由 HR 系统同步主管为直属上级超过三天追加经理审批”的假设清单。评审会可以直接围绕假设拍板而不是在发散讨论。第二步Claude 按模板生成正文。它会先给出背景与目标然后限定本次范围“不做加班申请、不做考勤统计、不做薪酬计算”再给出总体方案后端采用单表状态机实现审批流暂不引入工作流引擎原因是当前规则简单、避免过度设计。第三步也是我特别看重的一步自检。生成完之后它会主动检查自己前后文的字段一致性比如接口里的approver_id和数据模型里处理人ID是不是同一个字段。如果发现歧义它会自己在文档里修正而不是把问题留给你。4.2 实际产出长什么样一次完整运行后得到的设计书骨架大概是这样# 请假申请模块开发设计书 ## 1. 背景与目标 - 目标将请假申请流程线上化实现提交、审批、归档闭环。 - 成功标准员工从提交到完成审批的平均耗时不超过 24 小时。 ## 2. 范围与边界 - 范围员工提交申请、主管审批、经理审批、HR 归档。 - 不做加班申请、考勤统计、薪资计算、移动端推送。 ## 3. 总体方案 - 前后端分离后端提供 REST API前端使用 Vue 3。 - 审批流采用状态机模型不引入独立工作流引擎。 ## 4. 模块拆分 - 请假申请服务接收申请、校验余额、生成待办。 - 审批流服务状态流转、审批人计算、超时提醒。 - HR 归档服务审批通过后推送至 HR 系统。 ## 5. 接口设计节选 - POST /v1/leave-requests - employee_id: 必填员工ID - leave_type: 必填枚举ANNUAL/SICK/PERSONAL - start_time / end_time: 必填时间戳 - reason: 选填原因说明 ## 6. 数据模型节选 - leave_request 表 - id, employee_id, leave_type, start_time, end_time - statusDRAFT/SUBMITTED/APPROVED/REJECTED - current_approver_id, created_at, updated_at ## 7. 业务流程图 - 主线DRAFT - SUBMITTED - APPROVED - 分支超过3天 - 增加 MANAGER_APPROVED 状态 - 异常余额不足 - 拒绝提交并返回原因 ## 8. 异常与降级 - HR 系统调超时允许提交归档改为异步重试。 - 审批人离职系统自动转移到上级主管。 ## 9. 验收标准 - 提交时余额不足接口返回 422。 - 三天以上假期未经理审批状态不能变为 APPROVED。 - 审批通过后 10 分钟内 HR 归档任务必须创建。你可能注意到这份文档最大的特点不是“字数多”而是每个章节都有可被验证的结论。评审会可以逐条质疑超时异步重试的间隔是多少审批人离职是查 HR 系统还是本地表这些问题一旦被提出来就意味着设计书真正发挥了作用。4.3 如何把设计书推向开发落地设计书生成之后我会做两件事让它驱动开发过程。第一抽取“任务清单”。让 Claude 基于模块拆分和接口设计生成开发任务拆分比如后端 5 个任务、前端 4 个任务、测试 3 个任务每个任务对应验收标准的某一条。这等于从设计书直接长出排期表而不是项目经理另外凭感觉估点。第二抽取“评审检查单”。把待决策问题和验收标准汇总成一张清单评审会上只讨论这张清单。以请假系统的例子来说评审会真正需要拍板的通常不超过三个问题要不要引入工作流引擎HR 系统同步用什么方式审批人离职后的自动转移规则由谁维护其余细节设计书已经替你回答了。这一步做完“需求到落地”就不再是口头禅了。设计书变成任务、测试用例、评审检查单的共同源头团队所有人都盯着一份文档说话。5. 跑了一个月后踩过的坑与取舍5.1 坑一不加约束输出好看但没法用第一次让 Claude 自由生成设计书的时候它给了我一份六千多字的文档排版精美章节齐全看起来非常专业。但我仔细一读发现问题大了总体方案里写着“极简架构”后面却设计了三个微服务接口参数在前端章节叫user_id在后端章节叫employee_id完全对不上。后来我才明白大模型在没有约束的情况下“表达流畅”和“逻辑自洽”是两回事。设计书不是散文它是一个严密的参数系统需要每一处定义互相咬合。这个坑的解法就是我前面写的模板章节 内嵌自检清单。模型输出受约束后质量才有保障。这里需要明确自检清单不能依赖 Claude“自觉”执行必须写死在 SKILL.md 里并且要加一句“每次生成后必须逐项检查并汇报结果”。否则它写嗨了根本不会回头去看。5.2 坑二上下文一长就前后矛盾第二个坑出现在设计书内容变长之后。请假系统比较简单模型还能撑住但做一个包含十几个模块的中型系统生成到后面章节的时候模型已经忘了前面写过的字段定义。接口章节里新冒出一个manager_id数据模型里却从来没有这个字段。解决办法不是逼模型记住所有内容而是主动减少单次生成的负载。我现在会把设计书生成拆成两到三轮第一轮生成总体方案和模块拆分把结论压缩成十条以内的“事实卡片”第二轮再基于事实卡片生成接口和数据模型。这样每一轮 Claude 要维护的上下文都有限前后不一致的概率大幅降低。另外Claude Code 项目里的CLAUDE.md也是个好帮手。我会在开始生成前把关键决策同步进去比如“本次状态机节点只有 DRAFT、SUBMITTED、APPROVED、REJECTED、MANAGER_APPROVED”。这样即使对话窗口切换关键决定也不会丢。5.3 坑三需求和设计书“两张皮”前半个月我最大的挫败感来自一个现象设计书写得漂漂亮亮但开发出来的东西跟设计书不是一回事。后来我认真复盘发现问题根本不在设计书而在需求萃取阶段。很多时候需求方自己也没想清楚。我拿到一句话需求直接让 Claude 生成设计书结果是 AI 用自己的常识补完了所有缺失信息。这种“补全”看着合理实际上掩盖了业务方没有回答的问题。所以我现在强制在流程里加了一个环节需求萃取完成后先把“假设清单”发给需求方确认。确认通过之前绝对不生成正文。这一步会把整个流程拉长一两天但它避免的是设计书中后期的大返工性价比极高。5.4 坑四自动生成不等于自动评审还有一个容易被忽略的问题设计书生成得再规范也不能替代评审。我曾经有一段时间过于信任输出结果把设计书直接丢给团队“大家看看有没有问题”结果评审会开得安静如鸡——不是因为文档完美而是因为大家默认 AI 生成的东西轮不到自己说话。后来我调整了用法让 Claude 在生成完设计书之后额外附一份“待决策问题”清单和一份“风险点清单”。评审会上只讨论这两个清单让团队成员明确“AI 可以提供方案但拍板的是人”。这一招下去评审会的质量反而回来了因为大家的注意力被集中到了真正需要判断的地方。我把这些坑整理成了一张速查表方便用到的时候对号入座症状根因解法输出流畅但前后矛盾缺少一致性命中的约束内嵌自检清单强制逐项检查内容长了就丢字段上下文超载分轮生成先出事实卡片再细化设计与实际需求脱节需求萃取不完整先输出假设清单人工确认后再生成评审会无人提意见大家默认 AI 输出不可挑战增加待决策清单把矛盾摆上桌面5.5 实践中保留的“人工检查点”自动化做得越多越需要明确哪些步骤不能省。我现在保留了三个人工介入点需求假设确认Claude 列出的假设清单必须由熟悉业务的人逐条确认。接口评审涉及对外系统联调的接口定义必须后端负责人过目。验收标准核对测试负责人需要对照设计书里的验收标准确认每一条都具备可测性。这三个检查点都不是为了质疑 AI而是为了把“自动生成”和“责任人决策”分开。毕竟文档可以自动写责任不能自动背。6. 设计书生成之后这条流水线还能延伸到哪里6.1 从设计书到测试用例和 UI 自动化脚本设计书一旦变成结构化的标准产物它就不仅仅是开发人员的输入还可以成为测试链路的起点。我在第一批设计书稳定产出之后试着让 Claude 基于接口设计章节自动生成 API 测试用例效果比预期好不少。思路是这样接口设计里有明确的路径、参数、类型、必填标记数据模型里有字段约束业务流程图里有状态流转。这些信息本身就是测试用例的雏形。Claude 把这些章节转成测试用例清单可以直接覆盖正常路径、参数非法、权限不足、余额不足等场景。更进一步如果团队用的是 Playwright 这类 UI 自动化工具设计书里的前端页面流程可以作为脚本骨架的输入自动生成操作步骤和断言。当然这一步不会像设计书生成那么完美。UI 自动化脚本还需要结合真实的选择器、页面元素不能完全甩锅给 AI。但设计书把“测什么、按什么顺序测、预期是什么”这个问题解决了剩下的就是机械实现。6.2 团队沉淀把 Skill 变成标准作业流程我目前的做法是把design-doc-generator这个 Skill 纳入团队仓库统一管理任何成员新增需求时只要把原始需求丢进 docs 目录然后让 Claude 跑一遍流程就会得到一份质量稳定、结构一致的设计书。这带来一个额外好处新成员入项目不需要再花一周时间去读那些散落在 wiki、群聊、代码注释里的“历史设计”。他们只需要看最近几份设计书就能快速理解项目里每个模块存在的理由、边界在哪、有什么历史包袱。Skill 本身也应该持续迭代。比如我们团队用了两周之后在模板里加了一节“对外依赖”专门记录第三方服务接口、定时任务、消息队列等外部因素。这个需求最开始不在模板里是在一次线上事故复盘后补上的。Skill 的优势就是它是文件改起来非常方便改完以后全团队立刻生效。6.3 什么情况下别用自动化讲了这么多好处我也想泼一盆冷水不是所有设计书都适合自动生成。探索型方案不适合。如果项目本身还在验证技术路线比如“要不要自研规则引擎”“新架构方案能不能支撑未来三倍流量”这种设计书的价值在思辨过程AI 生成的书面表达反而会掩盖思考深度。强合规领域要谨慎。医疗、金融结算、审计等场景下设计书往往需要为合规审查服务措辞和依据都有特殊要求自动生成的文档最多只能作为初稿离可直接提交还差很远。还有一种情况也建议慎用团队里没有资深评审者的时候。设计书自动生成只是把起草成本降下来了判断质量的责任仍然在人。如果团队里没人能看出方案里隐含的风险自动化只会让错误方案更快地扩散。我自己现在接到新需求第一件事已经不是打开编辑器而是跑一遍这套流程。先把需求萃取清楚再让 Claude 生成设计书最后拉着团队把待决策问题逐条过掉。踩过前面那些坑之后我最大的体会是自动化生成的不是一份文档而是一个让所有人都能围绕同一套事实说话的框架。下一步我准备把设计书里的接口定义直接转成 OpenAPI 文件再把测试用例生成也做成独立的 Skill。到时候从需求到接口文档再到测试脚本整条链路就能真正连起来了。