架构文档是核心,代码留给CC

2025 年，”Vibe Coding” 意味着敲一条 Prompt，看着 AI 生成一点东西。到了 2026 年，行业给出了一个名字来解释这条路在真实项目上为什么走不通：Spec-Driven Development（规格驱动开发）。AWS 推出了 Kiro，一个围绕 Specify → Plan → Execute 工作流构建的 IDE。GitHub 开源的 Spec Kit 突破了 84,000 颗星。分析师在 2026 年 3 月 盘点出 30 多个竞争中的规格优先框架。

盘点出 30 多个竞争中的规格优先框架：https://medium.com/@visrow/spec-driven-development-is-eating-software-engineering-a-map-of-30-agentic-coding-frameworks-6ac0b5e2b484

它们都在收敛到同一个洞见：任务需要的上下文越多，直接扔给 Agent 一条 Prompt 就碰运气的做法就越失败。

要应用这条教训，你不需要 Kiro，也不需要 Spec Kit。在仓库根目录放一份朴素的 ARCHITECTURE.md 就能做到大部分工作。FIRE51 就是从头到尾这样构建的。

我最初犯的错

构建 FIRE51 时，我做错的第一件事就是跳过这一步。我让 Claude 在模块间的数据契约定义清楚之前就动手写模拟引擎。每一个单独的决策听起来都合理——类型清晰、函数签名干净、JSON 结构看起来也没问题。两个会话后，当引擎输出喂进报告构建器，什么都对不上。字段名不匹配。单位在一个模块里是隐式的，在另一个模块里是显式的。两天的重构，本来只要两小时的前期接口设计就能避免。

AI 并没有做出坏决策。它做出的是不协调的决策，因为没有任何东西告诉它其他模块期望什么。

架构优先是什么样子

在任何实现之前，ARCHITECTURE.md 应该回答四个问题：

• 模块边界 — 每个部分负责什么，仅此而已

• 数据契约 — 穿越每个边界的 JSON 数据结构

• 技术选型及其理由

• 明确的范围外内容 — 这个项目不做什么

有了这份文档，每个实现请求都有参考点。”按照 §Interface M1→M2 中定义的输出来构建模块 2。” 没有歧义，没有自行发明的决策。

FIRE51 的拓扑，直接取自它的 ARCHITECTURE.md：

一个后端，三个前端。图旁边写着一条规则：计算引擎和数据库永远不在客户端运行。 后面每一个架构问题，都能对着这张图直接回答。

FIRE51 的实际用法

在写第一行服务器代码之前，五个模块就连同具名的接口契约一起定义好了：

• 输入收集 — 对话式问答，输出 SimInput

• 模拟引擎 — 纯 TypeScript，无 I/O，消费 SimInput，生成逐年账本

• 报告输出 — 消费账本，渲染 HTML/图表/PDF

• 建议 — 跨账本的场景对比

• PolicyEngine 税务验证器 — 引擎的外部事实来源

年度模拟循环有一条写下来的步骤顺序：收入 → 支出 → RMD → Roth 转换 → 税 → 提款 → 增长 → 标记。这一句话就防住了无数个 Bug。没有它，AI 会按每次会话里最直觉的顺序重排这些步骤。

引擎完工时，集成没有任何意外。每个模块消费的正是上游模块生产的内容，因为接口在两边动笔之前就已冻结。

保持文档诚实

第二个纪律不太显眼但更重要：在修改代码之前更新架构文档，而不是之后。

“根据 ARCHITECTURE.md §3，这超出范围”是对抗 AI 范围蔓延的完整答案。也是对抗你自己想在冲刺中途偷偷塞功能的诱惑的完整答案。文档给了你一个可以指着的地方。

当 AI 提出与文档不一致的内容时，这是一个真正的决策点：要么有意识地更新架构——附一句理由——要么回绝这个提案。两者都可以。悄无声息的偏离不行。

实践规则

从一份空白文件开始。写下你在构建什么、不构建什么、模块边界在哪里、跨边界的数据长什么样。不需要很长。FIRE51 最初的 ARCHITECTURE.md 不到 200 行。

AI 在每次会话开始时读它。架构保持在范围内。集成的意外保持在最小。而你不会再在第三个会话里重新发现第一个会话就做过的设计决策。

Spec-Driven Development 正是出于这个原因在变成行业方向。工具会更光滑，格式会标准化。但核心动作——开车之前先画地图——在 AI 能写代码之前就是正确答案，AI 之后也还是正确答案。

FIRE51 是一款完全通过 Vibe Coding 构建的退休规划工具。这是 Vibe Coding 系列的第四篇文章。