用途:在涉及架构决策的功能、系统变更或缺陷修复开始前,先产出结构化设计文档,明确要构建什么、为什么以及如何验证。产物写入 docs/plans/YYYY-MM-DD-<topic>-design.md,技能只负责生成该文档并停止,不编写实现计划或代码。
流程:探索代码库与上下文;提出 2-3 种方案(先给推荐并说明理由,每种含架构概述、优缺点、工作量估计,至少一个更简单、一个更健壮可扩展);由用户选择方案,若无合适则重新提出;逐节起草;用 EARS 格式编写需求;提交用户评审,未通过则修订,通过后写入 docs/plans/ 目录。
文档模板含六节:摘要(2-4 句说明内容与原因);项目目标与非目标(目标需具体可度量,非目标为明确排除的合理事项);上下文(催化剂如 Issue、Slack 线程,相关代码库目录与文件,第三方文档 URL,参考博客/RFC,受影响模块);系统设计(架构概述、新增或修改的接口与关键函数的行为契约,而非实现,以及被拒绝的替代方案);所需库与工具(外部依赖表格含包名、版本、用途,内部模块表格,无依赖时写 None);测试与验证(最重要且最详细的一节,含 EARS 格式的验收标准、并发/依赖失败/错误恢复/边界/安全等边界情况,以及可执行验证命令和 lint、格式化检查)。
EARS 要求使用 SHALL,不用 should/may,每条可独立测试,避免模糊用语。附加有按规模调整深度的缩放指南、常见错误对照表,以及 examples/ 下的小型 CLI 标志、中型的带鉴权与限流的 REST API、大型的含重试与死信队列的分布式事件管道三个示例。
限制:资料未说明具体运行平台、安装方式、命令语法与收费信息。