为编码项目或功能生成结构化的实施规范文档。当用户提供需求、功能创意、错误描述或……时使用。
Spec Writer — 结构化执行 Spec生成器.
功能概述
Spec Writer — 结构化执行 Spec生成器.是一项面向实际任务的技能，主要用于Generalate 高质量,AI- agent- 方便的 Spec文档, 来自模糊的要求.；When to Use.；
核心要点
- User 拥有一个要求, 特性想法, bug represent。
- 它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。
- 使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。
使用与执行
从功能定位来看，该技能强调把分散的操作要求整理成清晰、可复用的处理流程，使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数，再依据技能说明逐步执行；若输入条件不完整，应先补齐信息或采用保守配置，避免因错误假设导致结果偏离需求。
结果检查与注意事项
执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期，并对异常提示、缺失字段和边界情况进行处理；涉及批量任务时，还应保存进度，避免中断后重复操作。该技能适合用于一次性任务，也可以接入自动化工作流，与其他技能或上层代理配合完成更完整的业务链路；在组合使用时，应明确每一步的输入输出关系，并避免不同步骤之间出现参数冲突。
Spec Writer — 结构化实现规格说明书生成器
从模糊的需求出发，生成高质量、面向 AI Agent 友好的规格说明书文档。
适用场景
- 用户已提出某项需求、功能构想、缺陷报告或 GitHub Issue
- 用户希望在编码开始前获得一份结构化的文档
- 用户明确表达“撰写一份规格说明书”、“规划该任务”、“为该功能编写规格说明”等意图
- dev-workflow 第二阶段需要一份详细规格说明书（可作为子步骤调用）
输出结果
一份独立的 Markdown 格式规格说明书，保存至项目目录中（默认路径为 SPEC.md 或 spec/）。
工作流程
步骤 1：收集上下文
从可用信息源中系统性地收集信息。切勿向用户索取你本可自行获取的内容。
来自用户的输入：
- 要构建什么，以及为何构建
- 任何显式的约束条件或偏好设置
来自项目本身（若可访问）：
- 技术栈（
package.json、Cargo.toml、pyproject.toml、go.mod等） - 项目结构（目录布局）
- 现有架构文档（
llmdoc/、README、ARCHITECTURE.md等） - 代码风格模式（参考已有代码样例）
- 测试配置（测试框架、测试文件存放位置、运行方式）
- Git 工作流（分支命名规范、CI 配置）
来自外部引用源（如被提及）：
- GitHub Issue 详情（标题、正文、评论、标签）
- 关联的设计文档、API 参考资料或其他链接文档
步骤 2：起草规格说明书
使用模板文件 references/spec-template.md。生成前请务必通读该模板。
依据已收集的上下文，完整填写模板中每一项内容。关键原则如下：
- 具体明确，避免含糊。 例如写 “React 18 with TypeScript and Vite”，而非 “React 项目”。
- 优先聚焦“做什么”与“为什么”。 用户故事与成功标准是整个规格说明书的锚点。
- 包含真实可执行命令。 提供带完整参数标志的完整命令，而非仅列出工具名称。
- 以示例代替描述。 一段有效代码示例胜过三段文字解释。
- 明确指出“不做什么”。 显式排除项可防止 AI Agent 行为偏移。
- 采用三层边界机制。 ✅ 总是执行 / ⚠️ 需先确认 / 🚫 绝不执行。
步骤 3：与用户共同评审
将草案提交给用户审阅。常见讨论点包括：
- 用户故事是否完整？是否存在遗漏场景？
- 所选技术方案是否可接受？是否存在替代架构选项？
- 边界定义是否准确？是否存在过于严格或过于宽松之处？
- 验证标准是否具备可测性且充分完备？
- 任务拆分粒度是否合理？
根据反馈持续修订，直至用户确认无误。批准后将状态标记为 “✅ Confirmed”。
步骤 4：保存并交付
将经确认的规格说明书保存至项目中。推荐存放位置如下：
- 单一功能：项目根目录下的
SPEC.md - 多个规格说明书：存于
spec/.md - 配合 dev-workflow 使用时：该规格说明书将在 Phase 2 中替代原始需求文档
通知用户规格说明书已就绪，并建议后续操作：
- 交由编码 Agent 执行（如 dev-workflow、Claude Code、Codex 等）
- 作为人工实现的参考依据
- 共享给团队成员进行评审
适配不同项目规模
小型任务（缺陷修复、微小功能）：
- 跳过或压缩不适用的章节
- 重点关注：目标、变更内容、边界定义、验证方式
- 全文长度建议：约 50–100 行
中型任务（功能开发、重构）：
- 完整使用模板
- 全文长度建议：约 100–250 行
大型任务（新模块、重大功能）：
- 完整使用模板，并扩展任务分解层级
- 可考虑拆分为多个规格说明书（每个组件/模块一份）
- 建议包含架构图描述或数据模型说明
- 全文长度建议：约 200–400 行
核心原则
本设计源自行业最佳实践（GitHub 对 2500+ 份 Agent 文件的研究、Anthropic 的上下文工程研究成果，以及实际的规格驱动开发模式）：
规格说明书即唯一事实来源（Source of Truth） —— 它跨会话持久存在，在上下文变长或会话重启时为 Agent 提供稳定锚点。
结构化以提升可解析性 —— 使用清晰的 Markdown 标题与统一格式。AI 模型对结构良好文本的处理能力显著优于自由文本。
六大核心领域 —— 命令、测试、项目结构、代码风格、Git 工作流、边界定义。可用作完整性检查清单。
三层边界机制 —— ✅ Always do（无需询问即可执行）/ ⚠️ Ask first（需人工审批）/ 🚫 Never do（硬性禁止）。相比扁平化的规则列表更有效。
模块化设计 —— 各章节应能独立使用。例如，仅负责后端开发的编码 Agent 无需在其上下文中包含前端规格说明部分。
活文档（Living Document） —— 当决策发生变更时，同步更新规格说明书。过时的规格说明书比没有规格说明书危害更大。
热门AI工具
相关专题
本专题介绍Gradle插件开发的基本流程，涵盖插件类编写、自定义任务注册、扩展参数设计和插件应用方法，帮助你理解插件如何组织构建逻辑，减少多个项目之间的重复配置。
0
2026.10.22
本专题介绍Gradle Wrapper的基本作用，涵盖文件组成、生成方法、版本配置和任务调用，帮助你理解项目如何使用指定的Gradle版本，减少不同开发环境带来的构建差异。
0
2026.10.22
本专题整理Golangci-lint常用Linters的用途与配置方法，覆盖错误处理、无效代码、安全、复杂度、命名和依赖检查，帮助项目合理选规则。
0
2026.10.22
本专题介绍Gradle Java项目构建方法，涵盖Java插件配置、依赖声明、源码编译、测试执行和打包检查，帮助你理解各阶段的任务关系，逐步完成项目构建。
0
2026.10.22
本专题汇总PHP常见时间戳漏洞，包括2038年溢出、时区漂移、时间戳伪造、重放攻击、时间盲注与日志审计失效等，并给出升级64位环境、使用 DateTimeImmutable、统一UTC、严格超时校验、预处理绑定、hash_equals 比对等修复方案，帮助开发者快速排查和加固时间相关代码。
0
2026.10.22
本专题聚焦Golangci-lint YAML配置文件，讲清运行参数、规则启停、目录排除、问题过滤及严重级别设置，便于团队统一检查标准。
0
2026.10.22
本专题讲解Golangci-lint的安装、初始化、基础命令和首次代码检查，覆盖本地环境、Docker及多平台用法，帮助Go开发者快速上手。
0
2026.10.22
PHP2Shell漏洞是什么，哪些PHP版本和运行环境会受到影响，服务器应该如何检测与修复？本专题提供版本自查脚本、Linux与Docker升级命令、PHP-FPM和Apache排查步骤，以及修复验证、临时缓解和应急响应方案。
0
2026.10.22
热门下载
相关下载
精品课程
共6课时 | 12.1万人学习
共79课时 | 161.5万人学习
共6课时 | 54.7万人学习
最新文章
