Spec Coding 编辑部
这个站如何生产内容
Spec Coding 于 2026 年初上线，是一个独立的编辑项目。它存在的原因很简单：需求歧义是返工和线上事故的主要可预防来源，而市面上多数关于规格的内容停留在抽象层面，无法在交付压力下直接落地。
每个页面都遵循同一条生产路径：草稿基于具体交付场景撰写，模板和示例在站内的浏览器生成器中实际运行验证，成稿按编辑政策公布的评审标准检查后才发布。
我们使用 AI 工具辅助起草和翻译，并坦率说明这一点：任何 AI 辅助的草稿都必须经过人工编辑、事实核查并配有可运行示例后才会发布。完整披露见编辑政策"AI 工具使用"一节。
责任与声明边界
本页是 Spec Coding 维护团队的权威资料页。公开链接集中列出，方便读者核实站点维护者身份。
- 公开资料：GitHub 与 X / Twitter。
- 编辑联系：纠错与来源问题发送至 [email protected]。
- 声明边界：示例为匿名化的工程场景，不构成任何雇主、客户或平台的背书声明。
- 更新记录：本页的重大变更会反映在页面更新日期，必要时同步到站点更新日志或编辑政策。
我们写什么
Spec Coding 的每篇文章都围绕一个真实交付场景展开：某个未充分定义的决策造成了（或险些造成）实际损失。主题包括：
- Spec-First 落地 — 如何在不打断节奏的前提下，给一个已在冲刺中的团队引入规格纪律。
- API 契约 — 版本策略、契约测试流水线、错误分类与向后兼容评审。
- 验收标准 — 写出 QA 不用追问作者就能执行的 Given/When/Then 场景。
- 高风险模式 — 幂等、并发、发布/回滚设计，以及常见计费事故背后的复盘。
- 可复用模板 — 可下载的规格文档、PRD 转规格指南和评审打分工具。
编辑责任
Spec Coding 的文章在发布前经过评审，并在读者报告示例过时、表述不清或事实错误时更新。完整的发布与纠错流程见编辑政策。
事实纠错、反馈或合作咨询，请使用联系页面或发邮件至 [email protected]。编辑类消息会在三个工作日内处理。
建议如何形成
Spec Coding 的建议源于反复出现的交付失败：范围不清、验收标准不可测、不安全的 API 变更、没有回滚路径的数据库迁移、AI 生成代码偏离既定规格。我们把这些失败模式转化为团队在实现开始前就能使用的检查清单、模板和示例。
本站刻意偏向实际约束而非宏大方法论。如果某篇指南推荐一个模式，它应该说明该模式控制什么风险、评审者应查验什么证据、以及对小改动而言它何时过重。
当读者反馈表明某个示例过于笼统时，我们通常会补充决策规则、失败路径或评审问题，而不是单纯把文章写长。编辑目标是实战判断力，不是篇幅。
从素材到文章的转化轨迹
Spec Coding 不发布客户名称或私有事故细节。我们保留操作模式、去除可识别上下文，成稿仍需保留让这个场景有价值的决策压力。
私有素材模式： - 支付服务超时后计费退款被重试 - 第一笔退款待定时客服仍可创建第二笔退款 - 回滚依赖支付服务商的确认 发布出的教学模式： - 幂等键必须定义重放行为 - 客服界面必须尊重服务商的待定状态 - 回滚说明必须指出逆转不再安全的临界点
这是核心编辑测试：去掉私有事实，保留能帮其他团队避开同一失败的决策。
示例的证据规则
当示例无法回答评审者的三个问题——改了什么、谁对决策负责、发布前用什么证据验证行为——它就会被修订。这也是近期更新都在增加可直接复制的评审块、实战注记和明确停止条件，而不是更多抽象解释的原因。
- API 示例：指明消费方、兼容级别和契约证据。
- AI 编码示例：指明允许范围、生成风险等级和人工确认点。
- 迁移示例：指明表规模、回填阶段、回滚边界和演练证据。
- 验收标准：指明参与者、触发条件、可观察结果和至少一条失败路径。
失败模式如何塑造示例
我们把示例当作真实交付工作的微型模拟。一个有用的示例应当指明参与者、系统边界、状态变化、失败路径，以及评审者在发布前要查验的证据。这就是为什么 Spec Coding 的许多示例会提到幂等键、回滚触发器、权限检查、迁移风险和可观察的生产信号，而不是停留在泛泛的最佳实践。
文章更新时，第一遍检查不是"还能不能写得更长"，而是"读者本周能不能用它避免一个具体错误"。如果答案不清晰，该节会围绕一个具体决策点、评审问题或前后对比重写。
公开项目信号
Spec Coding 将公开参考点与私有客户历史分开。读者可以通过列出的 GitHub 和 X 账号核实维护者资料，再通过公开更新日志检查站点级政策与内容变更。
- 仓库信号：公开模板工作通过 spec-templates 链接。
- 编辑信号：政策、命名、策展和主题中心的重大变更记录在更新日志页。
- 纠错信号：读者纠错通过联系页提交，按编辑政策处理。
精选文章
开源项目
- spec-kit — Spec-First 软件开发的 Markdown 规格模板，包含功能规格、API 契约、数据库迁移规格、事故复盘和评审清单。
- openapi-spec-starter — 集成 CI 契约测试的 OpenAPI 起步套件，包含 Spectral 校验、Prism mock 验证、Schemathesis 模糊测试和 GitHub Actions 工作流。
当前编辑重点
当前重点是让每个核心页面无需额外上下文即可使用：模板页有更强的示例，工具页有更清晰的评审门槛，中文页面与英文保持同等深度，资源和政策页有更明确的维护说明。目标是让读者离开每个页面时带走一个具体的下一步行动，而不只是一个定义。
- 模板页：补充填好的示例、实战注记和证据门槛，避免页面沦为千篇一律的骨架。
- 案例页：发布完整的前后对照规格包，覆盖真实的产品和工程变更。
- 信任页：保持编辑部、联系、纠错、广告与编辑政策与最新评审周期同步。
- 本地化：检查中文页面的技术表述是否自然，细节是否与英文页面同等可执行。
联系方式与公开资料
- GitHub：github.com/virus5945 — Spec-First 开发资源
- 邮箱：[email protected]
- 站点：spec-coding.dev