规格说明书撰写：给 AI 代理足够的上下文，让它自己把功能做出来
- 定位：这不是一个"帮你写文档"的通用写作技能，而是一套面向 AI 代理（Agent）的技术规格文档方法论——用结构化的章节，把"为什么做、做过什么研究、选了哪条路、还剩什么问题"交代清楚。
- 核心理念：提供上下文而非指令、记录研究而非结论、留出开放问题、支持自主实施。好的规格是"启动平台"，不是"照做的脚本"。
- 产出结构固定：头部、概述、动机、研究发现、设计决策、架构、实施计划、边缘案例、开放问题、成功标准、参考，共 11 个区块，可按功能大小裁剪。
- 最适合谁：需要把需求交给 AI 代理或其他开发者独立实现的独立开发者、技术负责人、架构师，以及正在做重构、迁移、新功能规划的人。
- 最大差异点：它明确反对"把每一步都写成教程"，把"没想清楚的问题"当成文档的一等公民，这恰好解决了 AI 编程中最常见的两个极端：代理盲从、代理困惑。
1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？
技能中文名：规格说明书撰写 技能英文名：specification-writing 技能 ID：11863
它解决的是一个非常具体的问题：当你把需求丢给 AI 代理（或同事）去实现时，上下文给少了，对方只能猜；上下文给多了，对方只会照抄。传统的 PRD 或需求文档往往走向两个极端——
- 写成"操作手册"：一步一步规定怎么实现，实施者没有任何判断空间，一旦中途出现意料之外的情况就卡死；
- 写成"愿望清单"：只说要什么，不说现状是什么、调研过什么、放弃了哪些方案，实施者只能从头摸索，甚至重复走一遍你已经排除过的弯路。
这个技能给出的答案是一份"甜点区"文档：足够上下文以开始，足够开放以拥有实施。
一键安装的思路与步骤（具体命令、入口地址与版本要求，以官方说明为准）：
- 确认安装前提：你的 AI 编程助手 / 代理环境已经支持 AI 技能（Skill）机制，并且你手上有正在推进的项目仓库——规格文档一般是放在项目里、作为实施者上下文的。
- 找到技能入口：在技能市场、技能管理面板或技能列表中，用中文名"规格说明书撰写"、英文名
specification-writing或技能 ID11863进行搜索。 - 执行安装/启用：按界面提示完成添加。若你的环境支持命令行安装，具体命令请以官方说明为准，不要照搬他人环境中的示例。
- 验证是否生效：安装后对助手发一句"请用规格说明书撰写技能，为’给接口增加缓存层’写一份规格"，观察输出是否包含头部（日期/状态/作者）、概述、动机、研究发现、设计决策、架构、实施计划、边缘案例、开放问题、成功标准、参考这些区块。如果它只是给你一段普通的需求描述，说明技能没有被正确加载。
- 让技能长期可用：把生成的规格文件放在项目内固定目录（例如文档目录下的规格子目录），并在与代理对话时指明"请先读这份规格再动手"，这样"一键安装"才真正转化为"一键提效"。
2. 该技能的主要功能和特点
- 提供一套可直接套用的文档骨架：11 个区块覆盖从背景到验收的完整链路，并用"占位符"标注哪些内容必须由你填写、哪些可以让实施者后续补充。
- 强制区分"研究"与"结论"：研究发现部分要求用对比表格记录同类项目做了什么、你搜索过但没找到什么、参考了哪些文档，并明确写出"关键发现"和"对设计决策的影响"。
- 设计决策必须可追溯：每个决策点写进表格，包含"选择"与"理由"两列；暂时不做的决策要显式标注为"延迟"并说明原因，避免留下隐性债务。
- 架构优先可视化：鼓励用 ASCII 图表表达组件关系和多步骤流程，而不是用大段散文描述结构。
- 实施计划分阶段、带复选框：第一阶段要求拆到"具体、原子"的任务级，后续阶段可以粗粒度，由实施者自己细化——这是刻意留白，不是偷懒。
- 开放问题是特性而非缺陷：每个未决问题要给出选项和推荐意见，但明确"不关闭问题"，把决策权交还实施者。
- 自带好坏规格对照：好规格的六个特征（研究有记录、决策有理由、问题留开放、代码显示现状、架构可视化、阶段可操作）与坏规格的六个反模式（处方性步骤、无研究假设、关闭所有问题、抽象描述、散文墙等）一一对应，方便自查。
- 面向代理实施者的写作路径：明确写出代理阅读规格后的五步理解路径，以及它接下来会做什么（生成子代理验证研究、探索开放问题、充实后续阶段、在你留白处决策）。
- 附带快速参考清单：一份可勾选的检查表，写完规格后逐条对照，防止漏项。
和"让大模型直接写需求文档"相比，它强在约束了写作者的行为：不许编造结论、不许替实施者做完所有决定、不许用散文墙掩盖信息缺失。
3. 如何使用该技能？
第 1 步：明确要写哪种规格。 技能说明了适用场合——规划功能、记录架构决策、创建实施指南。先想清楚这次是"新功能规划"还是"迁移/重构指南"，因为后者可以弱化研究发现、强化边缘案例。
第 2 步：让助手加载技能并起稿。 输入示例：
请使用"规格说明书撰写"技能，为"订单导出接口增加缓存层"写一份技术规格。当前状态是每次导出都全量查询数据库，高峰期接口超时。先给我骨架，动机部分我会补充真实代码。
第 3 步：补齐"头部"与"概述"。 填入日期、状态（草稿/进行中/已实现）、作者、可选分支名。概述控制在一段、一到两句话，只说明"增加了什么能力"，不要写宣传语。
第 4 步：把动机写成"当前状态 → 问题 → 期望状态"。 当前状态必须贴真实代码或配置，问题用编号列表逐条列痛点。输出示例大致是：
## 动机
### 当前状态
（贴出导出接口的查询代码片段）
这造成问题：
1. 单次导出全量扫描，高峰期响应超过超时阈值
2. 相同参数重复导出时无复用，数据库压力翻倍
### 期望状态
（贴出期望的缓存调用方式示意）
第 5 步：写研究发现。 用表格对比两三个同类方案的做法，然后写"关键发现"和"影响"。如果你查过但没找到成熟模式，就直说"无既定模式存在"——这本身就是有价值的研究结论。
第 6 步：填设计决策表与架构图。 每个决策写清"选了什么、为什么不是另一个"。架构部分优先画图，把组件、字段、关系用 ASCII 图形表达。
第 7 步：拆分实施计划并划定留白。 第一阶段拆成原子任务并加复选框，第二、三阶段只写高层任务，交给实施者展开。
第 8 步：写边缘案例、开放问题、成功标准、参考。 开放问题按"问题 + 选项 a/b/c + 推荐意见"的格式写；成功标准要可验证（测试通过、构建成功、文档更新）；参考部分列出相关文件路径和它的相关性。
第 9 步：用快速参考清单自查。 逐条勾选，确认没有"散文墙"、没有替实施者做完所有决定。
4. 同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
规格说明书撰写（本技能，specification-writing） |
面向 AI 代理的技术规格写作方法论 | 固定 11 区块结构、研究对比表、决策理由表、开放问题、分阶段计划、好坏规格对照 | 需支持 Skill 的环境，安装入口以官方说明为准；使用门槛低，会填表即可 | 新功能规划、架构决策记录、交给代理自主实现的实施指南 | 优势：强制留白、可追溯、直接服务代理实施；不足：区块较多，微小改动需要主动裁剪 |
| 通用大模型对话直接写需求文档 | 通用写作 | 靠提示词自由生成 | 极低 | 快速出草稿 | 优势：零成本起步；不足：结构不稳定、容易写成教程式步骤或空泛描述，缺乏研究记录与决策理由 |
| 开源的规格驱动开发工具包（如 GitHub Spec Kit 一类） | 规格驱动开发流程工具 | 提供命令化的规格/计划/任务流程与模板 | 需要安装工具链、学习其命令体系 | 团队级规格驱动开发 | 优势：流程完整、可自动化；不足：偏重流程编排，对"留白尺度"的写作指导较弱，具体用法以官方说明为准 |
| 规格驱动型 IDE（如 Kiro 一类） | 编辑器内置规格工作流 | 在 IDE 内生成需求、设计、任务文档 | 需切换到该 IDE | 从零开发新项目 | 优势：工具与文档一体化；不足：与现有编辑器/仓库工作流绑定，具体能力与收费以官方说明为准 |
| 团队自有 PRD / 设计文档模板 | 传统文档规范 | 章节模板 + 评审流程 | 无工具门槛 | 人类团队内部协作 | 优势：团队熟悉；不足：通常面向人类读者，缺少"让代理自主研究"的显式留白设计 |
选择建议：如果你主要和 AI 代理协作、希望文档能被代理直接"读懂并动手"，本技能的贴合度最高；如果你要的是端到端的命令化流程编排，可以再叠加规格驱动工具链。
5. 该技能的典型应用场景与实际体验情况
场景一：独立开发者规划新功能。 角色是单人开发者，痛点是一边写代码一边改需求，最后文档和实现对不上。用法是先用技能生成骨架，动机部分贴现有代码，研究发现部分花十分钟对比两三个同类项目。实际体验：上手几乎无门槛，因为技能给的是"填空题"；效果最明显的是动机部分——逼你把"当前状态"用真实代码写出来，很多模糊需求在这一步就暴露了。
场景二：技术负责人记录架构决策。 痛点是半年后没人记得当初为什么不用某个方案。用法是把设计决策表当成决策日志，把被否决的方案写进"理由"列，把暂缓的事项写进"延迟"行。实际体验：表格形式比散文好评审，会上可以逐行过；注意不要把"延迟"当成"遗忘"，要写清触发重新评估的条件。
场景三：把中大型重构交给 AI 代理自主实现。 痛点是把任务丢给代理后，它要么机械照做、要么在细节上反复问你。用法是完整写出研究结论、阶段一原子任务和开放问题，明确告诉代理"开放问题由你调查后决定"。实际体验：代理会更早发现你没想到的边界情况，甚至反过来补充研究发现；注意事项是阶段一必须拆细，否则代理容易在第一阶段就开始自由发挥。
场景四：迁移类需求。 技能里专门提到迁移规格可以重点写边缘案例、弱化研究发现。痛点是迁移最容易在数据边界上翻车。用法是把每个异常场景按"初始条件 → 发生什么 → 预期结果"三段式列出。实际体验：边缘案例部分写得越具体，返工越少；但要注意，如果某个场景你也不确定结果，就写"见开放问题"，不要硬编一个预期。
整体上手难度与注意事项：技能本身易用，难点在于"克制"——习惯写详细方案的人会忍不住把实施细节写满，反而破坏了留白。另一个注意点是：不是每个规格都要写全 11 个区块，小功能可以跳过研究发现，按需裁剪是技能明确允许的。
6. 该技能能为用户带来的价值
- 提升协作效率：把"口头解释 + 反复答疑"变成一份结构固定的文档，人读一遍、代理读一遍，后续沟通成本大幅下降。
- 降低协作门槛：不需要懂复杂的架构文档规范，按占位符填空即可产出专业规格；对不擅长写长文档的开发者尤其友好。
- 减少返工：动机用真实代码说话、边缘案例逐条列举、成功标准可验证，这三点直接对应返工的三个主要来源——需求理解偏差、边界遗漏、验收标准模糊。
- 让 AI 代理真正发挥作用：开放问题与留白设计，把代理从"执行器"变成"研究者 + 决策者"，这是从"AI 帮我敲代码"升级到"AI 帮我把功能做成"的关键一步。
- 长期知识沉淀：设计决策表天然是一份可追溯的决策档案，几个月后回看，为什么这么选、当初排除了什么，一目了然。
7. 常见问题 FAQ
Q1：这个技能怎么安装？需要付费吗？
在支持 AI 技能（Skill）的环境里，通过技能市场或技能管理面板搜索"规格说明书撰写"、英文名 specification-writing 或技能 ID 11863 即可添加；具体入口、命令与是否收费以官方说明为准。
Q2：它和普通的 AI 写作技能有什么区别？ 普通写作技能面向人类读者，追求表达完整；这个技能面向实施者（尤其是 AI 代理），追求"刚好够用"——刻意保留开放问题、刻意不写死实现步骤，让实施者自己研究和决策。
Q3：适合哪些人用？我一个人写小项目有必要吗？ 适合独立开发者、技术负责人、架构师，以及任何要把需求交给 AI 代理或他人实现的人。小项目可以裁剪——跳过研究发现，只保留头部、概述、动机、实施计划、成功标准五个区块就够用。
Q4：开放问题会不会让代理"乱做决定"？ 不会。技能要求每个开放问题都给出选项（a/b/c）和你的推荐意见，只是不替你关闭问题。这相当于给了实施者一张地图和一个建议方向，而不是一条必须走的路线。
Q5：和规格驱动开发工具包、规格驱动 IDE 怎么选？ 如果你需要的是"把规格写好、写对、写得能被代理自主实施"，选这个技能，它专注写作方法论本身，不与编辑器或工具链绑定；如果你需要端到端的命令化流程编排和任务自动拆解，可以配合规格驱动工具链使用，具体能力与限制以各自官方说明为准。