SuperAPI AI 工具集

write-tech-spec

编程与开发

查看项目

更新于 10-16 07:17

技能介绍

用途:为 Warp 的重要功能编写 TECH.md 技术规格。适合实现跨多个模块、存在明显架构取舍,或评审者需要在写码前/同时看到计划的场景;纯 UI 改动或简单修复通常无需写技术规格。建议先有 PRODUCT.md,使技术方案锚定已确认的行为;若实现仍不确定,可先做 e2e 原型再据其撰写。

输出位置:写入 specs/<id>/TECH.md,id 可为 Linear 工单号(如 specs/APP-1234/TECH.md)、以 gh- 前缀的 GitHub issue id(如 specs/gh-4567/TECH.md)或短 kebab-case 功能名(如 specs/vertical-tabs-hover-sidecar/TECH.md)。存在同名 PRODUCT.md 时沿用其 id;specs/ 下只应包含以 id 命名的目录。用户没有工单或 issue 时,应询问其功能名作为目录。仅当用户明确要求时才新建 Linear 工单或 GitHub issue,分别使用 Linear MCP 工具或 gh CLI;团队、标签或仓库不明确时使用 ask_user_question。

撰写前调研:阅读产品规格(如有)、检查相关代码,识别主要文件、类型、数据流与归属边界;能直接查看代码时不要猜测现有架构。

结构:必需章节包括 Context(要构建什么、当前系统在改动区域如何运作、相关文件与行引用,并引用 PRODUCT.md 说明用户可见行为而非复述)、Proposed changes(实现计划:哪些模块变化、新增的类型/API/状态、数据流、归属边界、如何沿用现有模式,存在多条合理路径时说明取舍)、Testing and validation(单元测试、集成测试、手工步骤、截图、视频等验证方式,引用 PRODUCT.md 的行为不变量并映射到具体测试或验证步骤)、Parallelization(评估通过 run_agents 并行子智能体是否显著减少耗时或隔离工作;若不可用则跳过该节)。可选章节仅在增加信息时加入:End-to-end flow、Diagram、Risks and mitigations、Follow-ups;为空则省略标题,不要写“None”。

并行化细节:提出使用子智能体时,为每个智能体写明名称/角色与子任务、执行模式(本地或远程)及一句理由;本地智能体给出工作目录或 git worktree 以避免冲突;远程智能体说明使用哪个环境或注明在空环境运行;写明分支与 PR 策略(各智能体使用的分支、worktree 路径、工作如何落地:每个智能体一个 PR 还是合并为单个 PR)、协调边界(各智能体负责的文件/服务及与同类智能体的同步、合并点、验证归属);区分可并行与必须串行的步骤,依赖关系复杂时可用简短 Mermaid 图(graph TD 或 flowchart LR)。不提议并行化时,简要说明原因。应给出 worktree、分支名与执行模式的具体默认值。

长度:单文件且方案明确的可跳过或控制在约 40 行内;多模块且有一定不确定性的约 80–150 行;大型跨切面或架构新颖的改动可更长。若 Context 与 Proposed changes 从不同角度描述相同文件与状态,应合并。

保持更新:已批准的规格可与实现同 PR 交付;模块边界、实现顺序、风险、验证策略或发布假设变化时,在同一 PR 更新 TECH.md,检入的规格应描述实际发布的实现。大型功能实施者可选择性维护 DECISIONS.md 汇总具体决策。相关技能:implement-specs、write-product-spec、spec-driven-implementation。