spec-writing

Spec Writing

概述

把一个还没动手的方案写成可评审、可追溯、可验收的设计文档。核心：spec 是决策的固化——它记录"为什么这么定、定了什么、没定什么、怎么算实现成功"，而不是知识的搬运（堆背景介绍）或愿望的罗列（只说要做什么不说怎么做）。

何时使用

• 要做一个非平凡功能/重构/迁移，想先写设计再动手
• 要把脑里模糊的方案固化成可给同事评审的文档
• 已有设计草稿，想审查写得好不好

不该用：小到一目了然的改动（直接做，写 spec 是负担）；纯研究性命题还没结论时（先做 spike 调研，有了结论再写 spec——spec 记录决策，调研产出结论）。

与相邻 skill 的衔接：spec-writing 在"需求澄清 → 写 spec → 拆任务"流水线的中间。spec 定稿后，把方案交给 task-breakdown 拆成可执行任务；需求还太模糊连方案都形不成时，先澄清（见 clarifying-questions，未实现）再写 spec。

核心内容

先判断时机：spec 之前还有没有重大未知

不是所有"写个 spec"的需求都该直接开写。如果方案的核心决策还依赖未澄清的未知，硬写出来的 spec 就是空架子或一堆猜测。先问自己：写 spec 需要的决策，我都有依据了吗？

判断标准——把"影响方案结构的关键决策"列出来，看每条是哪种状态：

• 已明：有依据、能定。直接写进 spec 的决策部分。
• 需要澄清：用户一句话能定（范围、约束、目标）。写 spec 前先问，不要替用户猜。
• 需要调研：一句话定不了，得查/试/比（技术选型、性能可行性）。先做 spike（专门的调研任务，产出结论而非代码），有结论再写 spec——否则 spec 里只能写"待定"，决策部分就空了。

如果大量关键决策都是"需要调研"状态，说明现在不是写 spec 的时机——先做调研。澄清和调研占 spec 前置工作的大头，跳过它们直接写，是最常见的失败模式。

判断后的产出顺序（很重要，别把几步混在一起让用户困惑）：

• 关键决策大多"已明" → 直接写 spec。
• 有"需要澄清"项 → 先把澄清问题列给用户（阻塞项优先），等回答。这一步的产出就是"澄清问题清单"，不要同时甩一份假设性 spec——用户分不清该先回答问题还是改 spec。
• 有"需要调研"项 → 标出该做哪些 spike，说明"结论出来才能填 spec 的哪几节"。产出是"spike 清单 + 这些 spike 解锁的 spec 章节"，同样不提前硬写。
• 混合 → 澄清问题 + spike 清单一起给，标注各自解锁什么。把"前置工作"和"spec 本体"分开交付。

澄清问题怎么问（这一步的产出质量直接决定 spec 质量）：

• 每条带"为什么问"：让用户理解这个未知为什么影响方案，而非凭空盘问。差："QPS 多少？"；好："读 QPS 大概多少？（决定能否用单机 Redis 还是必须集群）"。
• 给默认假设让用户确认，而非开放式追问："我假设日读 < 1k QPS、单机够用，不对请纠正"——用户一句话能校正；纯开放式问题用户得从头想，消耗耐心。
• 问影响方案结构的，不问实现细节：问"实时还是离线计算"（改变架构），不问"用 Flink 还是 Spark"（实现细节，spec 阶段还太早）。
• 一次别超过 6-8 条：多了用户接不住。真有更多未知，先问阻塞第一刀的，其余用默认假设推进。把未知按"阻塞/非阻塞"分类（阻塞项先问、非阻塞用假设推进）很关键——task-breakdown 的"澄清未知"对此有更细的分类法，可参考。

反例：用户说"写个限流 spec"，你直接套模板写"背景/方案/步骤"——但"限流维度（接口/用户/IP）、算法（令牌桶/漏桶）、单机/分布式"都没定，写出来的方案部分全是占位符。

spec 写什么：决策，不是知识

spec 的价值密度集中在决策上。每写一段问自己：**这是决策，还是背景知识？**两者的篇幅分配严重失衡是 spec 写差的信号：

• 决策（spec 的核心）：选了什么方案、为什么选它、放弃了什么、怎么算成功。这是别人来评审、未来回溯时要看的东西，值得详细写。
• 背景（spec 的脚手架）：问题是什么、为什么做、相关技术是什么。点到决策够用为止，不要写成技术科普。读者不需要在限流 spec 里学"什么是令牌桶算法"——他们需要知道"我们为什么在令牌桶和漏桶之间选了令牌桶"。