write-tech-spec

write-tech-spec

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

概述

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

将规范写入 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 时，才创建新的工单或 issue；这种情况下，分别使用 Linear MCP 工具或 gh CLI（如果团队、标签或仓库不明确，请使用 ask_user_question）。

适用场景

当实施涉及多个模块、存在重要的架构权衡，或评审者会受益于在代码编写之前或期间查看计划时，请使用此技能。对于纯 UI 更改或简单修复，通常不需要技术规范。

最好先准备 PRODUCT.md，以便技术计划基于已达成一致的行为。如果实施方案仍不够明确，请先构建端到端原型，再根据验证结果编写技术规范。

编写前的调研

开始起草前，请阅读产品规范（如果有），检查相关代码，并找出主要文件、类型、数据流和所有权边界。只要可以直接检查代码，就不要猜测当前架构。 在规范中引用相关代码片段时，优先使用固定到提交的引用，方便后续读者检查你所调研的确切代码。记录所检查的每个仓库的当前 commit 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. 并行化 — 主动评估并行子 Agent（通过 run_agents 启动）能否有效缩短实际耗时或隔离工作。如果无法使用 run_agents，请省略此部分。规范提出使用子 Agent 时，请为每个拟议的 Agent 列出：

   • 简短的名称/角色及其负责的子任务。
   • 执行模式（local 或 remote）及一行理由。
   • 对于本地 Agent：指定其应使用的工作目录或 Git worktree，避免并行 Agent 在同一检出目录或文件上发生冲突。
   • 对于远程 Agent：指定使用哪个环境，或明确说明 Agent 将在空环境中运行。
   • 分支和 PR 策略：每个 Agent 使用哪个分支、各自使用的 worktree 路径，以及其工作如何合并（每个 Agent 提交一个 PR，还是合并为一个 PR 等）。
   • 协作边界：每个 Agent 负责哪些文件/服务，以及如何与其他 Agent 同步（消息沟通、合并节点、验证职责）。

   区分哪些步骤可以并行执行，哪些必须按顺序执行。如果依赖关系图并不简单，可考虑添加简短的 Mermaid 图（graph TD 或 flowchart LR），让读者一目了然地看出分支任务和合并节点。

   如果不计划并行化，请简要说明原因（例如，任务很小，或子任务耦合紧密），以便评审者审视这一判断。

   为 worktree、分支名称和执行模式给出具体默认方案，不要将这些留待后续决定。

可选部分——仅在能提供有价值信息时纳入。若内容为空，请完全省略标题；不要用“无”作为占位内容。

• 端到端流程 — 仅当追踪系统中的路径能提供“拟议改动”列表未涵盖的信息时才纳入。
• 图示 — 仅当视觉呈现能比文字更快地解释设计时，才纳入 Mermaid 图（例如数据流、状态转换、跨层调用顺序）。优先选择一两个重点明确的图示，而非装饰性图示。
• 风险与缓解措施 — 存在值得指出的真实故障模式、回归问题、迁移顾虑或发布风险时纳入。
• 后续事项 — 存在值得说明的延后清理工作或未来工作时纳入。

长度启发

根据功能规模合理确定规格说明的长度：

• 单文件改动，且方案明确：跳过技术规格，或控制在约 40 行以内。
• 涉及多个模块，且存在一定歧义：目标为约 80–150 行。
• 涉及多个领域或架构上较新颖的大型改动：只要每个章节都有必要，篇幅可以更长。

如果「背景」和「拟议改动」从不同角度描述了相同的文件和状态，就将它们合并。

编写指南

• 根据代码库的实际结构和模式制定计划。
• 如果仓库有可访问的远程地址，请将重要的代码引用固定到某个提交 SHA，并链接到对应的 GitHub 代码行。
• 优先提供具体的实现指导，避免泛泛而谈的架构描述。
• 解释拟议设计为何适合此代码库。
• 关于行为，请参考 PRODUCT.md，不要重复说明。
• 每个章节都应有其存在的价值；如果某个章节会重复其他内容，或只有套话，就省略。

保持规格说明最新

获批的规格说明可能会与实现一起在同一个 PR 中交付。如果模块边界、实现顺序、风险、验证策略或发布假设发生变化，请在同一个 PR 中更新 TECH.md。已纳入代码库的规格说明应描述最终实际交付的实现。

对于大型功能，实现者可以酌情保留 DECISIONS.md 文件，概述具体决策。在有助于后续 Agent 时提供；否则省略。

相关技能

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