write-tech-spec

write-tech-spec

为Warp的重要功能编写TECH.md规范。

概述

技术规范应将产品意图转化为适合现有代码库的实现计划，记录架构选择，并使代理更容易执行、评审者更容易评估。

将规范写入specs/<id>/TECH.md，其中<id>为以下之一：

• Linear工单编号（例如 specs/APP-1234/TECH.md）
• GitHub issue ID，前缀为gh-（例如 specs/gh-4567/TECH.md）
• 短横线分隔的功能名称（例如 specs/vertical-tabs-hover-sidecar/TECH.md）

当存在对应的PRODUCT.md时，使用相同的ID。specs/目录下应只包含以ID命名的子目录。

工单/issue引用是可选的。如果用户有Linear工单或GitHub issue，使用其ID。如果没有，请询问用户一个功能名称作为目录名。仅当用户明确要求时才创建新的Linear工单或GitHub issue；此时分别使用Linear MCP工具或gh CLI（如果团队、标签或仓库不明确，则使用ask_user_question）。

何时使用

当实现涉及多个模块、有重要的架构权衡，或者评审者需要在代码之前或同时看到计划时，使用此技能。对于纯UI更改或简单的修复，通常不需要技术规范。

最好先有PRODUCT.md，以便技术计划锚定在已商定的行为上。如果实现仍然不确定，先构建端到端原型，然后根据经验编写技术规范。

编写前的研究

在起草之前，阅读产品规范（如果有），检查相关代码，并识别主要文件、类型、数据流和所有权边界。当可以直接检查代码时，不要猜测当前架构。
在规范中引用相关代码块时，优先使用提交固定的引用，以便未来读者可以检查您研究的确切代码。捕获您检查的每个仓库的当前提交SHA（例如，git rev-parse HEAD），并尽可能使文件引用成为指向相应GitHub blob/<sha>/...#Lx-Ly URL的Markdown链接。使用链接文本保持路径在规范中可读。

结构

必需部分：

1. 上下文 — 正在构建什么，当前系统在更改区域的工作方式，以及最相关的文件及其行引用。将“问题”、“当前状态”和“相关代码”合并为一个有依据的部分。示例引用：

   • app/src/workspace/mod.rs:42 @ <commit-sha> — 用户流程的入口点
   • app/src/workspace/workspace.rs (120-220) @ <commit-sha> — 可能更改的状态和事件处理
     引用PRODUCT.md以获取用户可见的行为，而不是重复说明。

2. 提议的更改 — 实现计划：哪些模块更改，引入的新类型/API/状态，数据流，所有权边界，以及设计如何遵循现有模式。当存在多个合理路径时，指出权衡。

3. 测试与验证 — 如何根据产品行为验证实现。涵盖证明功能正常的所有内容：单元测试、集成测试、手动步骤、截图、视频以及任何其他验证。直接引用PRODUCT.md中编号的行为不变性，而不是重复说明；每个重要的不变性应映射到具体的测试或验证步骤。此部分是验证所在 — PRODUCT.md有意不包含验证部分。

4. 并行化 — 主动评估并行子代理（通过run_agents启动）是否能显著减少挂钟时间或隔离工作。如果run_agents不可用，跳过此部分。当规范提议使用子代理时，为每个提议的代理包括：

   • 简短名称/角色及其负责的子任务。
   • 执行模式（local或remote）及一行理由。
   • 对于本地代理：应使用的工作目录或git工作树，以便并行代理不会在同一检出或文件上冲突。
   • 对于远程代理：要使用的环境或明确说明代理将在空环境中运行。
   • 分支和PR策略：每个代理工作的分支，每个代理将使用的工作树路径，以及它们的工作如何落地（每个代理一个PR，单个合并PR等）。
   • 协调边界：每个代理拥有的文件/服务以及如何与同级代理同步（消息传递、合并点、验证所有权）。

   区分哪些步骤可以并行运行，哪些必须顺序运行。当依赖图非平凡时，考虑使用简短的Mermaid图（graph TD或flowchart LR），以便读者一目了然地看到扇出和合并点。

   当不提议并行化时，简要说明为什么没有益处（例如任务很小，或子任务紧密耦合），以便评审者可以质疑该判断。

   为工作树、分支名称和执行模式提出具体的默认值，而不是保持开放。

可选部分 — 仅在增加信息时包含。如果为空，则省略标题；不要写“无”作为占位符。

• 端到端流程 — 仅当跟踪系统路径能告诉您提议更改列表未提及的信息时包含。
• 图表 — 仅当可视化比文字更快解释设计时包含Mermaid图（数据流、状态转换、跨层序列）。优先使用一两个重点图表，而不是装饰性图表。
• 风险与缓解措施 — 当存在真实的故障模式、回归、迁移问题或值得指出的发布风险时包含。
• 后续工作 — 当有延迟清理或值得命名的未来工作时包含。

长度启发

根据功能调整规范大小：

• 单文件更改且方法明确：跳过技术规范或保持在约40行以下。
• 多模块更改且有一定模糊性：目标约80–150行。
• 大型跨领域或架构新颖的更改：当每个部分都有其价值时，更长也可以。

如果上下文和提议的更改最终从不同角度描述相同的文件和状态，则合并它们。

编写指导

• 将计划基于实际的代码库结构和模式。
• 将重要的代码引用固定到提交SHA，并在仓库有可访问的远程时链接到相应的GitHub行。
• 优先提供具体的实现指导，而不是通用的架构语言。
• 解释为什么提议的设计适合此仓库。
• 引用PRODUCT.md以获取行为，而不是重复说明。
• 每个部分都应有其存在的理由 — 如果某个部分会重复另一个部分或仅包含模板内容，则省略它。

保持规范最新

已批准的规范可以与实现在同一个PR中发布。当模块边界、实现顺序、风险、验证策略或发布假设发生变化时，在同一PR中更新TECH.md。检入的规范应描述实际发布的实现。

对于大型功能，实现者可以选择保留一个DECISIONS.md文件，总结具体决策。当它有助于未来的代理时提供；否则跳过。

相关技能

• implement-specs
• write-product-spec
• spec-driven-implementation