用途:为 Warp 的重要功能编写 TECH.md 技术规格,把产品意图翻译成契合现有代码库的实现计划,记录架构选择,方便代理执行与评审者评估。适合实现跨多个模块、存在明显架构取舍,或评审者需要先看计划的场景;纯 UI 改动或简单修复通常无需技术规格。建议先有 PRODUCT.md,让技术方案锚定已确认的行为;实现不确定性过高时,可先做端到端原型再写规格。
产出位置:specs/<id>/TECH.md,<id> 可为 Linear 工单号(如 specs/APP-1234/TECH.md)、加 gh- 前缀的 GitHub issue id(如 specs/gh-4567/TECH.md),或短 kebab-case 功能名。若已有同级 PRODUCT.md,沿用其 id;specs/ 直接子项只放 id 命名目录。工单/issue 引用可选;没有时向用户要功能名作目录名;只有用户明确要求时才新建 Linear 工单或 GitHub issue,分别使用 Linear MCP 工具或 gh CLI(团队、标签、仓库不清时用 ask_user_question)。
写前调研:读产品规格、检查相关代码,识别主要文件、类型、数据流与所有权边界,不凭猜测谈现有架构。引用代码时优先提交钉定(commit-pinned)引用,记录所查仓库的提交 SHA(如 git rev-parse HEAD),尽量把文件引用做成指向 GitHub blob/<sha>/...#Lx-Ly 的 Markdown 链接。
必备章节:Context(要构建什么、当前系统如何工作、最相关文件及行引用);Proposed changes(哪些模块改动、新增类型/API/状态、数据流、所有权边界、如何遵循现有模式,存在多条合理路径时点明取舍);Testing and validation(单测、集成测试、手动步骤、截图、视频等全部验证,直接引用 PRODUCT.md 的编号行为不变量并映射到具体测试或验证步骤);Parallelization(评估并行子代理是否显著缩短耗时或隔离工作,若不可用则跳过;提及时需给出角色、本地/远程执行模式及理由、工作目录或 git worktree、分支与 PR 策略、协调边界,并区分并行与串行步骤,依赖图复杂时可用 Mermaid 图,不提出时简要说明原因,worktree、分支名与执行模式应给出具体默认值)。可选章节:端到端流程、图示、风险与缓解、后续工作;为空则省略标题,不写“None”占位。
长度与维护:单文件改动或方案明确时跳过规格或控制在约 40 行内;多模块有歧义约 80–150 行;大型横切或架构创新可更长。Context 与 Proposed changes 若从不同角度描述同样文件与状态,应合并。写明方案为何契合本仓库,用 PRODUCT.md 描述行为而非复述。获批规格可与实现同一 PR 交付;模块边界、实现顺序、风险、验证策略或发布假设变化时须在同一 PR 更新 TECH.md,使签入规格描述实际发布的实现。大功能可选维护 DECISIONS.md 汇总具体决策。相关技能:implement-specs、write-product-spec、spec-driven-implementation。