用途
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,使用其 id;若没有,则询问用户用作目录的功能名。仅在用户明确要求时才新建 Linear 工单或 GitHub issue,此时分别使用 Linear MCP 工具或 gh CLI(若团队、标签或仓库不明确则先询问用户)。
写作前的研究
起草前应阅读产品规格(如有)、检查相关代码,识别主要文件、类型、数据流和职责边界。不要凭猜测判断当前架构,应直接查看代码。
结构
必需章节:
- Context:说明要构建什么、所改动区域当前系统如何工作,以及最相关的文件及行号引用。将“问题”“当前状态”“相关代码”合并为一个有依据的章节。示例引用如 app/src/workspace/mod.rs:42(用户流程入口)和 app/src/workspace/workspace.rs (120-220)(可能改动到的状态与事件处理)。用户可见行为应引用 PRODUCT.md,而非重述。
- Proposed changes:实现计划,包括哪些模块会改动、引入的新类型/API/状态、数据流、职责边界,以及设计如何沿用现有模式。当存在多条合理路径时指出权衡。
- Testing and validation:如何依据产品行为验证实现,涵盖单元测试、集成测试、手动步骤、截图、视频及其他验证。应直接引用 PRODUCT.md 中编号的行为不变量,而非重述;每个重要不变量应映射到具体的测试或验证步骤。验证内容放在此章节,PRODUCT.md 有意不设 Validation 章节。
可选章节:仅在能提供信号时包含,若为空则完全省略标题,不要写“None”占位。
- End-to-end flow:仅当追踪系统路径能提供 Proposed changes 列表之外的额外信息时包含。
- Diagram:仅当可视化比文字更快解释设计时包含 Mermaid 图(数据流、状态转换、跨层时序)。优先一到两张聚焦图,而非装饰性图。
- Risks and mitigations:当存在真实失败模式、回归、迁移顾虑或值得指出的发布风险时包含。
- Parallelization:当工作可清晰拆分给多个智能体且这种拆分不显而易见时包含。
- Follow-ups:当存在延迟清理或值得命名的未来工作时包含。
篇幅建议
根据功能合理确定篇幅:单文件改动且方案明确时跳过技术规格或控制在约 40 行以内;跨模块且有一定歧义时目标约 80–150 行;大型跨领域或架构新颖的改动可以更长,前提是每个章节都有其价值。若 Context 与 Proposed changes 从不同角度描述了相同文件与状态,应合并二者。
写作指导
计划应基于实际代码库结构与模式;优先给出具体实现指导而非通用架构语言;解释所提设计为何契合本仓库;行为应引用 PRODUCT.md 而非重述;每个章节都应体现价值,若会重复其他章节或只含套话则省略。
保持规格最新
已批准的规格可与实现同 PR 发布。当模块边界、实现顺序、风险、验证策略或发布假设发生变化时,应在同一 PR 中更新 TECH.md。签入的规格应描述实际交付的实现。对于大型功能,实现者可选择维护 DECISIONS.md 汇总具体决策;若有助于后续智能体则提供,否则跳过。
相关技能
implement-specs、write-product-spec、spec-driven-implementation。