Back to Details

write-tech-spec

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

write-tech-spec

撰写TECH.md技术规格

Write a 
TECH.md
spec for a significant feature in Warp.
为Warp的重要功能撰写
TECH.md
技术规格文档。

Overview

概述

The tech spec should translate product intent into an implementation plan that fits the existing codebase, documents architectural choices, and makes the work easier for agents to execute and reviewers to evaluate.
Write specs to 
specs/<id>/TECH.md
, where 
<id>
is one of:
  • a Linear ticket number (e.g. 
    specs/APP-1234/TECH.md
    )
  • a GitHub issue id, prefixed with 
    gh-
    (e.g. 
    specs/gh-4567/TECH.md
    )
  • a short kebab-case feature name (e.g. 
    specs/vertical-tabs-hover-sidecar/TECH.md
    )
Match the id used by the sibling 
PRODUCT.md
when one exists. 
specs/
should contain only id-named directories as direct children.
Ticket / issue references are optional. If the user has a Linear ticket or GitHub issue, use its id. If they don't, ask them for a feature name to use as the directory. Only create a new Linear ticket or GitHub issue when the user explicitly asks for one; in that case use the Linear MCP tools or 
gh
CLI respectively (and 
ask_user_question
if team, labels, or repo are unclear).
技术规格文档需将产品意图转化为适配现有代码库的实施计划，记录架构决策，让Agent更易执行工作，也便于评审人员评估。
请将规格文档写入
specs/<id>/TECH.md
，其中
<id>
可以是以下类型之一：
  • Linear工单编号（例如：
    specs/APP-1234/TECH.md
    ）
  • GitHub问题ID，前缀为
    gh-
    （例如：
    specs/gh-4567/TECH.md
    ）
  • 简短的短横线命名法（kebab-case）功能名称（例如：
    specs/vertical-tabs-hover-sidecar/TECH.md
    ）
如果存在同级的
PRODUCT.md
文档，请使用与之匹配的ID。
specs/
目录下应仅包含以ID命名的子目录作为直接子项。
工单/问题引用为可选内容。若用户提供了Linear工单或GitHub问题，请使用其ID；若未提供，请向用户索要功能名称作为目录名。仅当用户明确要求时，才创建新的Linear工单或GitHub问题；此时需分别使用Linear MCP工具或
gh
CLI（若团队、标签或仓库信息不明确，可使用
ask_user_question
询问）。

When to use

使用场景

Use this skill when the implementation spans multiple modules, has meaningful architectural tradeoffs, or when reviewers will benefit from seeing the plan before or alongside the code. For pure UI changes or straightforward fixes, a tech spec is often unnecessary.
Prefer to have a 
PRODUCT.md
first so the technical plan is anchored to agreed behavior. If the implementation is still too uncertain, build an e2e prototype first and then write the tech spec from what was learned.
当实施工作涉及多个模块、存在重要架构权衡，或者评审人员需要在查看代码之前或同时了解计划时，使用此技能。对于纯UI变更或简单修复，通常无需撰写技术规格文档。
优先确保已有
PRODUCT.md
文档，以便技术计划锚定已达成共识的行为。若实施方案仍存在较多不确定性，请先构建端到端原型，再基于从中获得的经验撰写技术规格文档。

Research before writing

撰写前调研

Before drafting, read the product spec (if any), inspect the relevant code, and identify the main files, types, data flow, and ownership boundaries. Do not guess about current architecture when the code can be inspected directly.
开始撰写前，请阅读产品规格文档（如有），检查相关代码，确定主要文件、类型、数据流和职责边界。当可直接查看代码时，请勿猜测当前架构。

Structure

文档结构

—

必填章节：

Required sections:
  1. Context — What's being built, how the current system works in the area being changed, and the most relevant files with line references. Combine the "problem," "current state," and "relevant code" into one grounded section. Example references:
    • app/src/workspace/mod.rs:42
      — entry point for the user flow
    • app/src/workspace/workspace.rs (120-220)
      — state and event handling that will likely change Reference 
      PRODUCT.md
      for user-visible behavior rather than restating it.
  2. Proposed changes — The implementation plan: which modules change, new types/APIs/state being introduced, data flow, ownership boundaries, and how the design follows existing patterns. Call out tradeoffs when there is more than one reasonable path.
  3. Testing and validation — How the implementation will be verified against the product behavior. Owns everything about proving the feature works: unit tests, integration tests, manual steps, screenshots, videos, and any other verification. Reference the numbered Behavior invariants from 
    PRODUCT.md
    directly rather than restating them; each important invariant should map to a concrete test or verification step. This section is where validation lives — 
    PRODUCT.md
    intentionally does not have a Validation section.
  4. Parallelization — Actively evaluate whether parallel sub-agents (launched via 
    run_agents
    ) would meaningfully reduce wall-clock time or isolate work. Skip this section if 
    run_agents
    is not available. When the spec proposes using sub-agents, include for each proposed agent:
    • A short name/role and the subtask it owns.
    • Execution mode (
      local
      or 
      remote
      ) with a one-line rationale.
    • For local agents: the working directory or git worktree it should use, so parallel agents do not collide on the same checkout or files.
    • For remote agents: which environment to use or an explicit note that the agent will run in an empty environment.
    • Branch and PR strategy: which branch each agent works on, the worktree path each agent will use, and how their work lands (one PR per agent, a single combined PR, etc.).
    • Coordination boundaries: which files/services each agent owns and how it syncs with sibling agents (messaging, merge points, validation ownership).
    Distinguish which steps can run in parallel and which must run sequentially. When the dependency graph is non-trivial, consider a short Mermaid diagram (
    graph TD
    or 
    flowchart LR
    ) so the reader can see fan-out and merge points at a glance.
    When parallelization is NOT proposed, briefly note why it isn't beneficial (e.g. the task is small, or subtasks are tightly coupled) so reviewers can challenge that judgment.
    Propose concrete defaults for worktrees, branch names, and execution mode rather than leaving them open-ended.
Optional sections — include only when they add signal. Omit the heading entirely if empty; do not write "None" as a placeholder.
  • End-to-end flow — Include only when tracing the path through the system tells you something the Proposed changes list doesn't.
  • Diagram — Include a Mermaid diagram only when a visual will explain the design faster than prose (data flow, state transitions, sequence across layers). Prefer one or two focused diagrams over decorative ones.
  • Risks and mitigations — Include when there are real failure modes, regressions, migration concerns, or rollout hazards worth calling out.
  • Follow-ups — Include when there is deferred cleanup or future work worth naming.
  1. 背景 — 说明要构建的内容、当前系统在变更区域的工作方式，以及最相关的文件和行号引用。将「问题」「当前状态」和「相关代码」整合为一个基于实际情况的章节。示例引用：
    • app/src/workspace/mod.rs:42
      — 用户流程的入口点
    • app/src/workspace/workspace.rs (120-220)
      — 可能会变更的状态和事件处理逻辑 请引用
      PRODUCT.md
      中用户可见的行为描述，而非重复说明。
  2. 拟议变更 — 实施计划：说明哪些模块会变更、将引入的新类型/API/状态、数据流、职责边界，以及设计如何遵循现有模式。当存在多种合理实现路径时，需明确指出权衡点。
  3. 测试与验证 — 说明如何验证实施是否符合产品行为。负责证明功能可用的所有事项：单元测试、集成测试、手动步骤、截图、视频及其他验证方式。直接引用
    PRODUCT.md
    中编号的行为约束，而非重复说明；每个重要约束都应对应具体的测试或验证步骤。验证内容需放在此章节中——
    PRODUCT.md
    文档中特意不设置验证章节。
  4. 并行化 — 主动评估是否通过
    run_agents
    启动并行子Agent能有效减少耗时或隔离工作。若
    run_agents
    不可用，可跳过此章节。当规格文档提议使用子Agent时，需为每个拟议的Agent包含以下内容：
    • 简短名称/角色及其负责的子任务。
    • 执行模式（
      local
      或
      remote
      ）及一行理由说明。
    • 对于本地Agent：应使用的工作目录或git工作树，避免并行Agent在同一检出目录或文件上发生冲突。
    • 对于远程Agent：应使用的环境，或明确说明Agent将在空环境中运行。
    • 分支与PR策略：每个Agent工作的分支、使用的工作树路径，以及工作成果的合并方式（每个Agent对应一个PR、合并为单个PR等）。
    • 协调边界：每个Agent负责的文件/服务，以及与同级Agent的同步方式（消息传递、合并点、验证职责）。
    区分可并行执行的步骤和必须按顺序执行的步骤。当依赖图较为复杂时，可考虑添加简短的Mermaid图（
    graph TD
    或
    flowchart LR
    ），让读者能快速了解任务分支和合并点。
    若不提议使用并行化，请简要说明原因（例如：任务规模小、子任务耦合紧密），以便评审人员提出质疑。
    为工作树、分支名称和执行模式提出具体的默认值，而非留空待填。

Length heuristic

可选章节 — 仅当能提供有效信息时才包含。若为空，请完全省略标题；不要用「无」作为占位符。

Right-size the spec to the feature:
  • Single-file change with clear approach: skip the tech spec or keep it under ~40 lines.
  • Multi-module change with some ambiguity: target ~80–150 lines.
  • Large cross-cutting or architecturally novel change: longer is fine when every section earns its place.
If Context and Proposed changes end up describing the same files and state from different angles, collapse them.
  • 端到端流程 — 仅当追踪系统中的流程路径能提供「拟议变更」章节未涵盖的信息时才包含。
  • 图表 — 仅当可视化能比文字更快解释设计（数据流、状态转换、跨层序列）时，才添加Mermaid图表。优先使用1-2个聚焦的图表，而非装饰性图表。
  • 风险与缓解措施 — 当存在实际故障模式、回归风险、迁移问题或发布隐患时才包含。
  • 后续工作 — 当存在需延后处理的清理工作或值得记录的未来工作时才包含。

Writing guidance

长度参考

  • Ground the plan in actual codebase structure and patterns.
  • Prefer concrete implementation guidance over generic architecture language.
  • Explain why the proposed design fits this repo.
  • Reference 
    PRODUCT.md
    for behavior instead of restating it.
  • Each section should earn its place — if a section would repeat another or contain only boilerplate, omit it.
根据功能规模调整规格文档长度：
  • 单文件变更且方案明确：无需撰写技术规格文档，或控制在约40行以内。
  • 多模块变更且存在一定不确定性：目标长度约80–150行。
  • 大型跨模块或架构创新变更：只要每个章节都有存在的必要，篇幅较长也可接受。
若「背景」和「拟议变更」章节从不同角度描述了相同的文件和状态，可将它们合并。

Keep the spec current

撰写指南

Approved specs may ship in the same PR as the implementation. Update 
TECH.md
in the same PR when module boundaries, implementation sequencing, risks, validation strategy, or rollout assumptions change. The checked-in spec should describe the implementation that actually ships.
For large features, the implementer may optionally keep a 
DECISIONS.md
file summarizing concrete decisions. Offer it when it would help future agents; otherwise skip it.
  • 基于实际代码库结构和模式制定计划。
  • 优先提供具体的实施指导，而非通用的架构术语。
  • 说明拟议设计为何适配此代码库。
  • 引用
    PRODUCT.md
    中的行为描述，而非重复说明。
  • 每个章节都应有存在的必要——若某章节会重复其他内容或仅包含模板化内容，请省略。

Related Skills

保持规格文档更新

  • implement-specs
  • write-product-spec
  • spec-driven-implementation
已获批的规格文档可与实现代码提交到同一个PR中。当模块边界、实施顺序、风险、验证策略或发布假设发生变更时，请在同一个PR中更新
TECH.md
。已提交的规格文档应描述实际发布的实现方案。
对于大型功能，实现者可选择保留
DECISIONS.md
文件，总结具体决策。若该文件对未来的Agent有帮助，则提供；否则可省略。
—

相关技能

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