用途：为 Hubble 的重要功能编写 TECH.md 技术规格，内容是实现方案的要点清单加上测试计划。审查者应能在一分钟内扫完并发现风险决策。它不是构建日志或教程，每条要点都应说明要做的改动或审查者可能质疑的决策。
前置：优先生成同级 PRODUCT.md（write-product-spec），并在 TECH.md 中引用其流程，而不是重述面向用户的行为。规格写入 specs/<id>/TECH.md，id 与同级产品规格一致；specs/ 下只应包含以 id 命名的目录。只有在用户明确要求时才创建 GitHub 议题，仓库使用 bholmesdev/hubble.md 上的 GitHub Issues，经 gh 操作，参见 docs/agents/issue-tracker.md。
适用时机：跨多个模块、影响共享包、改变同步/工作区行为或引入新数据流的改动；单文件 UI 修复不适用。
写作前研究：阅读产品规格，再检查实际代码，不要凭猜测谈架构。查阅 CONTEXT.md 的领域术语与 docs/adr/* 的约束；阅读 apps/desktop、apps/www、packages/editor、packages/ui、packages/sync、packages/sync-backend、packages/convex-client、packages/cli 下受影响源码；找出已完成部分工作的既有工具与基础组件，指出现有但未使用的工具优于另提新方案。
结构：Approach 是规格核心，用要点说明改动位置并基于真实代码，如新共享工具 classifyHref(href) 用于三处、不改解析器/序列化器、复用已有 normalizePath；跨层时按关注点分组，明确指出不会变的部分，仅在存在多种可行方案时用一句话说明取舍。E2E 测试计划为必需项，依据 PRODUCT.md 流程推导：桌面端按 .agents/skills/test-desktop-app/SKILL.md 写明要打开的 Workspace 状态、执行的动作与应确认的可见结果，并点名界面与控件；Web 端在跨端行为时经开发服务器加 ?test=1 走同样流程（需在 apps/www/.env.local 配置 VITE_TEST_CONVEX_URL 与 VITE_TEST_WORKSPACE_ID）；列出按模块命名的单元/集成测试；命令使用 pnpm check 迭代、pnpm build:desktop 做最终验证。可选内容仅在确有价值时加入：风险（回归、数据丢失或同步隐患，每条给缓解措施）、仅在比文字更快说明数据流时用 Mermaid 图、后续待办切片。不要写样板章节，如受影响包清单、模块架构论述、分步构建顺序或并行计划。
写作指引：每条要点基于读过的代码，点名文件、函数与既有模式；优先本地路径加行号，仅在规格供检出目录之外阅读时用固定 commit 的 GitHub 链接。使用 CONTEXT.md 的项目词汇。前端方案复用设计系统基础组件并在新方案前先考虑附近既有模式；间距使用逻辑 CSS 属性（margin/padding 的 inline/block/start/end），不用物理 left/right/top/bottom。总长度目标 30–80 行；不改变实现者输入或审查者检查内容的要点应删去。
保持更新：当方案、风险或测试计划变化时，在同一 PR 更新 TECH.md，已提交的规格应描述实际发布内容。
相关技能：write-product-spec、to-issues、grill-with-docs。