为重要功能编写 TECH.md 技术方案：当实现跨模块…

需要技术规格、实现计划或与产品规格绑定的架构文档，且实现跨多模块或存在架构取舍时，基于现有代码调研产出 TECH.md。

适用场景

解决思路

1. 将技术方案写入 `specs/<id>/TECH.md`，其中 `<id>` 可以是 Linear ticket number（如 `specs/APP-1234/TECH.md`）、以 `gh-` 为前缀的 GitHub issue id（如 `specs/gh-4567/TECH.md`），或短 kebab-case 功能名（如 `specs/vertical-tabs-hover-sidecar/TECH.md`）。
2. 如果存在同级 `PRODUCT.md`，`TECH.md` 使用与它相同的 id。
3. `specs/` 的直接子目录应只包含按 id 命名的目录。
4. Ticket/issue 引用是可选的；用户有 Linear ticket 或 GitHub issue 时使用其 id，没有则向用户询问一个功能名作为目录名。
5. 只有用户明确要求时才创建新的 Linear ticket 或 GitHub issue；创建时分别使用 Linear MCP tools 或 `gh` CLI；如果团队、标签或 repo 不清楚，使用 `ask_user_question`。
6. 当实现跨多个模块、存在有意义的架构取舍，或评审者需要在代码之前或同时看到计划时，使用本技能。
7. 对纯 UI 改动或直接修复，通常不写技术方案。
8. 优先先有 `PRODUCT.md`，让技术计划锚定已商定的行为；如果实现仍太不确定，先构建 e2e prototype，再根据学到的内容写技术方案。
9. 起草前先阅读产品规格（如有），检查相关代码，并识别主要文件、类型、数据流和所有权边界。
10. 不要猜测当前架构，因为代码可以直接检查。
11. 在方案中引用相关代码块时，优先使用 commit-pinned references，以便未来读者检查你研究时的确切代码。
12. 记录你检查过的每个 repository 的当前 commit SHA，例如运行 `git rev-parse HEAD`。
13. 尽量把文件引用做成指向对应 GitHub `blob/<sha>/...#Lx-Ly` URL 的 Markdown 链接；用链接文本保持路径可读。
14. 必写 section Context：写清楚正在构建什么、当前系统在被修改区域如何工作、最相关文件及行号引用；把“问题”“当前状态”“相关代码”合并成一个有依据的 section。示例引用如 [`app/src/workspace/mod.rs:42 @ <commit-sha>`](https://github.com/warpdotdev/warp/blob/<commit-sha>/app/src/workspace/mod.rs#L42) 表示用户流程入口，[`app/src/workspace/workspace.rs (120-220) @ <commit-sha>`](https://github.com/warpdotdev/warp/blob/<commit-sha>/app/src/workspace/workspace.rs#L120-L220) 表示可能变化的 state 和 event handling；用户可见行为引用 `PRODUCT.md`，不要重述。
15. 必写 section Proposed changes：写实现计划，包括哪些模块变化、引入的新类型/API/状态、数据流、所有权边界、设计如何遵循现有模式；当存在不止一条合理路径时，明确指出 tradeoffs。
16. 必写 section Testing and validation：写如何对照产品行为验证实现；该 section 拥有证明功能可用的所有内容，包括 unit tests、integration tests、手动步骤、截图、视频和其他验证；直接引用 `PRODUCT.md` 中编号的 Behavior invariants，不要重述；每个重要 invariant 都应映射到具体测试或验证步骤；validation 放在这里，`PRODUCT.md` 故意没有 Validation section。
17. 必写 section Parallelization：主动评估通过 `run_agents` 启动的并行 sub-agents 是否能显著减少 wall-clock time 或隔离工作；如果 `run_agents` 不可用，跳过此 section。
18. 当方案提议使用 sub-agents 时，为每个提议 agent 包含：短名称/角色及其负责的子任务。
19. 为每个提议 agent 包含：执行模式（`local` 或 `remote`）及一行理由。
20. 对 local agents：包含它应使用的 working directory 或 git worktree，使并行 agents 不会在同一 checkout 或文件上冲突。
21. 对 remote agents：包含使用哪个 environment，或明确说明 agent 将在空环境中运行。
22. 为每个提议 agent 包含 branch 和 PR 策略：每个 agent 在哪个 branch 工作、使用哪个 worktree path、工作如何落地（每个 agent 一个 PR、单个合并 PR 等）。
23. 包含 coordination boundaries：每个 agent 拥有哪些文件/服务，以及如何与兄弟 agents 同步，例如 messaging、merge points、validation ownership。
24. 区分哪些步骤可以并行、哪些必须顺序执行。
25. 当依赖图非平凡时，考虑用简短 Mermaid 图（`graph TD` 或 `flowchart LR`），让读者一眼看到 fan-out 和 merge points。
26. 当不提议并行化时，简要说明为什么没有收益，例如任务小或子任务紧耦合，以便评审者质疑该判断。
27. 为 worktrees、branch names 和 execution mode 提出具体默认值，而不是开放式留空。
28. 可选 section End-to-end flow：仅当追踪系统路径能提供 Proposed changes 列表没有的信息时包含。
29. 可选 section Diagram：仅当可视化能比文字更快解释设计时包含，例如数据流、状态转换、跨层 sequence；优先一两个聚焦图，而不是装饰性图。
30. 可选 section Risks and mitigations：当存在真实 failure modes、regressions、migration concerns 或 rollout hazards 值得指出时包含。
31. 可选 section Follow-ups：当有 deferred cleanup 或未来工作值得命名时包含。
32. 可选 sections 只在增加信号时包含；如果为空，完全省略 heading；不要写“None”作为占位。
33. 长度启发：单文件改动且方法清晰，跳过技术方案或保持在约 40 行以内。
34. 长度启发：多模块改动且有一些歧义，目标约 80–150 行。
35. 长度启发：大型横切或架构新颖改动可以更长，但每个 section 都要值得存在。
36. 如果 Context 和 Proposed changes 最终从不同角度描述相同文件和状态，合并它们。
37. 写作指导：把计划建立在真实代码库结构和模式上。
38. 写作指导：将重要代码引用固定到 commit SHA，并在仓库有可访问 remote 时链接到对应 GitHub 行。
39. 写作指导：优先给出具体实现指导，而不是通用架构语言。
40. 写作指导：解释为什么提议的设计适合这个 repo。
41. 写作指导：引用 `PRODUCT.md` 说明行为，而不是重述。
42. 写作指导：每个 section 都应值得存在；如果会重复另一个 section 或只含 boilerplate，就省略。
43. 保持方案最新：已批准方案可与实现同一 PR 发布。
44. 当 module boundaries、implementation sequencing、risks、validation strategy 或 rollout assumptions 变化时，在同一 PR 更新 `TECH.md`。
45. 签入的 spec 应描述实际发布的实现。
46. 对于大型功能，实现者可可选维护 `DECISIONS.md` 总结具体决策；当对未来 agents 有帮助时提供，否则跳过。
47. 相关技能可参考 `implement-specs`、`write-product-spec` 和 `spec-driven-implementation`。

适用边界 · 注意事项

• 纯 UI 改动或直接、简单的修复通常不需要技术方案。
• 实现仍过于不确定且未先做 e2e prototype 时，不应硬写技术方案。
• 不需要跨模块、没有有意义的架构取舍、评审者也不需要提前看计划时，技术方案价值较低。