Technical Plan
这是一个技能命令,用于创建《技术方案》文档,记录架构决策、技术栈与实现阶段。文档内容包括:架构决策(为何做出这些选择)、技术栈(库、版本、考虑过的替代方案)、实现阶段(功能将如何构建)、风险与缓解(可能出现什么问题)。
概述
在 specs.brainstorm 生成功能规格之后,使用该命令记录:带精确版本的技术栈选择、要遵循的架构模式、实现阶段/里程碑、带指标的性能目标、风险及如何检测。
使用方式
从已有规格创建:
/skill:specs-kit-technical-plan --spec=docs/specs/001-feature/
自定义焦点创建:
/skill:specs-kit-technical-plan docs/specs/001-feature/
参数:--spec(可选,规格文件夹路径);--from-spec(可选,从规格生成,提供规格路径时隐含)。
工作流位置
brainstorm → technical-plan(本技能)→ spec-to-tasks → implementation → review,在需要架构决策时插入。
核心原则
- 决策由用户拥有:你提议,用户决定。未被规格、ADR 或现有代码库固定的技术或架构选择必须询问,绝不自行采用。
- 一次一个决策:每次只问一个问题,附带推荐答案与理由,等待回复后再问下一个,不批量呈现待决事项。
- 先推导再确认:从现有架构读出候选方案是正确做法,但不等于可以跳过确认。
- 具体优于抽象(“Node 20.11 LTS”而非“Node ≥18”);决策需附理由;每个依赖固定精确版本;风险优先;性能作为需求,指标不可省略。
阶段流程
第一阶段:规格分析——加载功能规格并提取技术含义,读取主规格文件、user-request.md、brainstorming-notes.md,识别所需组件类型、外部集成、数据模型、性能期望、安全考量,列出待决策的技术关注点。
第二阶段:技术栈定义——检查 docs/architecture.md 等现有架构并继承已有选择,仅按需新增库;逐个询问语言、运行时、框架、关键库的精确版本、数据库与基础设施组件;生成技术栈表格(Component、Technology、Version、Rationale),框架行必须含精确可解析版本(不得用范围或“latest”),因为 spec-to-tasks 技能会读取该表注入任务的技术上下文;同时记录禁用技术及原因与替代方案。
第三阶段:架构决策——识别 3-5 个影响实现的关键决策,检查并引用现有 ADR;每个决策记录背景、决策内容、备选方案(优缺点)、后果(正面/负面/风险)、关联 ADR、应用阶段;决策类别涵盖数据架构、API 设计、认证、错误处理、组件结构、集成;当计划在事务也会修改的数据前引入缓存时,需记录每条变更路径的读取来源(缓存值、持久化实体或双读)、缓存失效相对事务提交的时机及相关竞态风险,并作为架构决策留存。
第四阶段:实现阶段——按复杂度拆为 2-4 个阶段(基础、核心功能、集成、打磨),每阶段记录目标、进入条件、里程碑、关键交付物、依赖、阻塞项、风险与缓解;定义阶段间依赖链、关键路径、可并行工作,以及阶段交接完成标准与评审要求。
第五阶段:性能需求——从规格提取性能期望,定义响应时间、吞吐量、资源使用、数据与存储的量化目标及测量方式;记录负载测试策略(基线负载、稳态/峰值/压力/尖峰场景、验收标准)和监控告警表(指标、阈值、动作、工具)。
第六阶段:风险评估——头脑风暴技术、运维、外部、进度风险,按可能性×影响评估,输出风险表(风险、可能性、影响、总体、缓解、检测);对高/中风险记录触发条件、检测手段、响应流程(发现、分诊、缓解、解决)与诊断/缓解命令剧本;按技术、依赖、数据、安全、运维分类并生成风险摘要。
第七阶段:文件结构——审查现有项目结构约定,定义该功能的目录组织(控制器、服务、仓储、模型、DTO、错误、校验器、映射器、配置、测试等)与文件命名规范。
适用场景
已完成功能规格或头脑风暴、需要把“做什么”落成“怎么做”的技术方案时使用,尤其适合需要固化技术栈版本、架构决策记录和风险清单以便后续任务拆分的项目。
限制
资料未提供该技能的具体运行环境依赖、支持的模型或平台、安装方式、收费信息,暂未提供;文档生成质量取决于已有规格的完整程度。