write-tech-spec 用于为 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 功能名（如 specs/vertical-tabs-hover-sidecar/TECH.md）。存在同级 PRODUCT.md 时应与其 id 一致；specs/ 的直接子目录只应包含以 id 命名的目录。工单或 issue 引用可选；用户没有时可询问功能名；仅在用户明确要求时才创建新的 Linear 工单或 GitHub issue（分别使用 Linear MCP 工具或 gh CLI，团队、标签或仓库不明确时用 ask_user_question）。
编写前调研：先阅读产品规格（如有）、检查相关代码，识别主要文件、类型、数据流与归属边界，不要臆测当前架构。引用代码片段时优先使用固定 commit 的引用，记录所检查仓库的当前提交 SHA（例如 git rev-parse HEAD），并尽量把文件引用做成指向 GitHub blob/<sha>/...#Lx-Ly URL 的 Markdown 链接。
必要章节：Context——要构建什么、被改动区域当前如何工作，以及最相关文件与行引用，将“问题”“当前状态”“相关代码”合并为一个有依据的章节；行为应引用 PRODUCT.md 而非复述。Proposed changes——实现计划：哪些模块变更、引入的新类型/API/状态、数据流、归属边界，以及设计如何沿用现有模式；存在多条合理路径时说明取舍。Testing and validation——如何对照产品行为验证实现，涵盖单元测试、集成测试、手动步骤、截图、视频等，直接引用 PRODUCT.md 中编号的行为不变量，每条重要不变量应映射到具体测试或验证步骤；验证只在此章节出现。Parallelization——评估通过 run_agents 启动并行子智能体能否显著缩短耗时或隔离工作；若不可用则跳过。提出并行时需为每个智能体给出名称/角色与子任务、执行模式（本地或远程）及理由、本地智能体的工作目录或 git worktree、远程智能体的环境说明、分支与 PR 策略、协调边界（文件/服务归属与同步方式），并区分可并行与须串行的步骤；依赖图复杂时可用简短 Mermaid 图。不建议并行时简要说明理由。应给出 worktree、分支名与执行模式的具体默认值。
可选章节（仅在有信号时包含，空则完全省略标题，不要写“None”）：End-to-end flow、Diagram（Mermaid，仅在视觉比文字更快说明设计时）、Risks and mitigations、Follow-ups。
长度参考：单文件且方案清晰——跳过或约 40 行以内；多模块且有一定模糊——约 80 至 150 行；大型跨切面或架构新颖——可更长，但每节都应有价值。若 Context 与 Proposed changes 从不同角度描述同一文件与状态，应合并。
写作指导：让计划扎根于真实代码库结构与模式；重要代码引用固定到 commit SHA 并尽可能链接到 GitHub 行；偏好具体实现指导而非泛化架构语言；解释设计为何契合本仓库；行为引用 PRODUCT.md 而非复述；每节都应有价值。
保持规格最新：已批准的规格可与实现同一 PR 发布；当模块边界、实现顺序、风险、验证策略或上线假设变化时，应在同一 PR 更新 TECH.md，使其描述实际发布的实现。大型功能可实现者可选维护 DECISIONS.md 汇总具体决策，有助于未来智能体时再提供，否则跳过。
相关技能：implement-specs、write-product-spec、spec-driven-implementation。