企业官网建设流程全解析

两小时跑通，四天返工

你接到一项紧急需求：开发一个自动化线上故障诊断agent。它定时巡检Grafana上各节点的性能指标；发现异常后，查询Elasticsearch中对应时段的业务日志，分析可能的故障节点和原因，再通过只读SSH权限登录服务器核对。确认原因后，agent通过企微发送止血与修复建议，通知负责人参与分析并决定如何处理。

需求很急，交付期限只有一周。你想到Claude Code，把需求输入终端。不到 2h，核心链路已经跑通：Spring AI基本骨架、向量库、Elasticsearch、Grafana API 和企微通知都完成了初步集成。你又用几条简单提示词做了调整，便验收通过，心想照这个速度，三天就能完成任务。

第二天，你开始把 agent 接入公司内部服务系统。你再次输入需求，等待 Claude Code 交付。不到 2h，代码生成完成，验收结果却让你崩溃：

1. 为适配内部系统的数据结构，原有inspection-agent的输出逻辑被塞入大量胶水代码，功能出现多处异常；
2. Claude Code 为保证数据隔离，引入了多个安全框架，验收时你却连最基本的登录入口都找不到；
3. 为避免模型接口因负载等原因请求失败，Claude Code添加了一套复杂的降级逻辑，配置和调试成本随之增加。

你只能重新梳理代码、整理问题清单。从第二天下午一直修到第四天下午，才完成内部系统适配。

项目交付那天，领导对结果表示满意，并提出了新的要求：能否在现有基础上，让 agent 自动创建 fix 分支并完成代码订正，同时为自动化部署预留接口，为后续的全自动化无人值守做准备？

于是，你组织了一次技术评审，邀请各个项目负责人参加。负责风控业务的同事问你：“由于历史和安全原因，我们的代码仓库不在团队内部的 GitLab，而是托管在别的平台上。当前 Git 认证和授权采用什么方式？是否支持配置化？有对应的设计文档吗？”

你一问三不知。项目初期没有完成设计和澄清，关键决策都散落在已经关闭的会话窗口里。Git 地址和认证方式被写死在代码、数据库配置或 Nacos 配置中。如今若要支持灵活配置，几乎等于重新进行一次大规模重构。

你陷入崩溃，只好找到技术负责人，说明这几天从零开始快速构建、反复返工，以及设计文档缺失、后续维护困难等问题。他听完后思考片刻，只说了六个字：

你 TM 在 vibe coding。

Vibe Coding：把需求、架构和决策留在对话里

Vibe Coding 这一概念由 Andrej Karpathy 于 2025 年提出。他用略带自嘲的说法，描述了一种日益流行的编程方式：开发者坐在 AI 辅助工具前，仅凭自然语言描述意图，由 AI 即时生成代码；代码能运行就先接受，报错了再继续描述和修复。

这套方式把三个关键动作留在了对话里：

1. 需求在聊天中传递
2. 架构在脑海中构建
3. 决策在终端中做出

问题不在于 AI 能不能生成代码，而在于人是否把需求、方案和验收标准想清楚。Vibe Coding通常表现为三种“凭感觉”：

1. 凭感觉整理需求：需求都在对话中确认，没有经过严谨梳理
2. 凭感觉做方案：技术栈和架构选择跟着 AI 的推荐走，没有继续追问动机、约束和失败条件。下面是一个常见场景：

你：当前核心模块发布频率太频繁，我想减小发布频率保证系统稳定性，告诉我如何解决 AI：结合代码上下文分析，a 模块频繁迭代，可以考虑拆分服务，降低核心系统的发布频率。

更稳妥的方案思考，需要先澄清目标，再追问方案为什么成立；如果反例能推翻方案，就继续追到真正的根因，最后才确定要做什么：

技术leader：当前核心模块发布频率太频繁，我想减小发布频率保证系统稳定性，告诉我如何解决 你：结合代码上下文分析，a 模块频繁迭代，可以考虑拆分服务。 技术leader：为什么要拆服务？拆服务的目的是什么？ 你：把频繁迭代的代码拆出去，降低核心系统的发布频率。 技术 leader：有些模块依赖 a 模块的迭代修改，它们仍然会频繁迭代；核心系统的发布频率没有下降，依赖风险也还在，怎么办？ 你：......技术leader：所以核心矛盾是什么？要如何解决？ 你：先查清 a 模块为什么频繁迭代，再判断能否减少迭代次数、降低风险。 技术leader：最终结论是什么？ 你：经排查，a 模块频繁发布主要是因为配置项写死在代码中；将这类配置改为页面维护并由运行时读取，可减少因配置变更而发版。

3. 凭感觉验收代码：没有明确的验收标准，生成代码对你来说就像黑盒，验收只能简化为“能不能运行”。

想象一下，你是一名 NBA 球队主教练，组建了一支全明星队伍。面对弱队时，你只下达一个指令：尽最大努力，拿下这场比赛。球员凭个人能力就能轻松拉开分差。

问题很快出现：遇到实力相当的球队，你仍然只下达同样的指令，个人能力就会被对方的周密策略抵消。联防无法破解，持球无法推进，传导也无法顺利进行。

球员越努力，越能说明一个事实：没有明确的战术设计和执行标准，努力并不能替代规划。

Vibe Coding用即时对话替代系统化的需求澄清和设计。它能让 AI 在数小时内跑通核心链路，却也可能让未经分析的设计决策直接进入代码。系统继续适配和迭代后，这些遗漏会变成返工、行为冲突和无法追溯的决策，逐步积累成技术债务。

五个问题：从需求蒸发到不可维护

开发者只需在屏幕前用几句话描述需求，AI 便能迅速生成一批可运行的功能代码。短期来看，功能很快得到反馈；但验收结束后，问题会沿着后续迭代逐步暴露：

1. 修改一处代码，另一处功能却出现异常；
2. 负责人追问技术细节时，你无法解释当初的设计取舍，后续迭代也无从下手；
3. 需求和设计没有形成可核对的标准，最终只能用“能不能跑”判断是否交付。

这像信用卡消费：刷卡时的即时满足是真实的，还款日到来时，积累的债务也同样真实。

这些问题不是五个孤立的故障，而是一条从决策丢失走向维护失控的链条：

1. 需求蒸发：决策做过，却没有留下来

在上述流程中，需求澄清和方案讨论都留在对话里，没有被正式沉淀。每一次头脑风暴和技术选型，往往只是从 Claude Code 给出的选项中选一个：

• 评审和选型的依据是什么？
• 这块业务逻辑为什么这样处理？
• 这块核心逻辑的配置有哪些约束？

这就是需求蒸发：决策已经做出，却没有留下可追溯的记录。如果一个长期迭代的工程制品只靠对话完成实时决策，需求和设计就会在会话关闭、上下文压缩或人员更替后变得难以追溯，技术债务也因此持续累积。

2. 上下文漂移：前后代码各自自洽，合起来却冲突

内部系统对接时，前期已经明确了目标和协议；会话推进后，后期代码却逐渐偏离约定。单看每段代码都自洽，整合后才暴露冲突。这就是上下文漂移：会话变长并触发上下文压缩后，早期约定可能被截断，后续决策因此偏离。

3. 不可审查：看得到代码，看不到设计

技术评审时，负责人问“有没有设计文档”，本质是在追问：我凭什么确信这套架构合理且可靠？

代码审查（code review）时，审查员查看 PR 中的代码 diff，并结合可获取的功能设计文档和架构决策（architecture decision）记录，理解设计意图，再核对实现是否符合设计。这些材料为审查提供依据，但不能单独保证审查质量。审查的职责不仅仅针对代码准确性，还在于：

• 技术选型是否准确
• 架构设计是否合理
• 需求理解是否准确
• 接口的设计是否规范

在 Vibe Coding 模式下，如果需求和设计决策只保留在对话窗口中，相关信息可能随会话关闭或上下文压缩而丢失。审查者只能看到交付代码，难以还原业务背景和架构取舍。评审范围因此容易从需求、方案和实现的综合审查，收缩为局部实现与编码规范检查，最终失去审查设计决策的价值。

4. 不可复现：看得到“是什么”，找不到“为什么”

假设现在要修复inspection-agent自动修改 fix 分支的逻辑。你必须结合设计文档，理解这套代码的处理方式和安全边界；但在 Vibe Coding 中，这些细节往往只存在于一次性的对话里。一个看似简单的扩展，也会因此无从下手。

个人项目或许还能依靠原作者记忆维持；在多人维护的项目中，一旦原作者离职或调岗，继任者面对的就是一套缺少设计背景的系统。即使只是小改动，也可能牵一发动全身。

这就像一栋缺失图纸的大楼：我们看得到外墙和房间，却看不到地下管线和承重结构。此时，任何一处看似微小的改动，都可能牵一发动全身。

5. 不可维护：每次修改都像数字考古

前面四个问题最终汇聚为一个核心问题：不可维护。软件系统的全生命周期中，维护成本占总成本的 60%~80%，开发者会不断阅读、修改、扩展和重构代码。若设计意图没有被记录，每次维护都像一次数字考古：只能从缺少业务背景的代码里反推原作者的意图，再依据猜测修改。

Vibe Coding 产出的代码，就像一位缺失完整病历的患者。医生看得到当前症状，却不知道既往病史、用药记录和手术方案；每一次治疗，都可能变成盲人摸象。

SDD 不是万能药，但规范不能缺

缺乏规范约束的 AI 代码生成会把未经验证的决策直接带进系统，这正是 SDD 要解决的问题：用可追溯的规范约束 AI 的生成过程。

但 SDD 也不是万能药。一位开发者在社区分享过这样一段经历：他严格遵循 SDD，先写需求，再做架构设计，随后拆解任务，最后让 AI 生成代码。系统上线后，产线出现大量业务超时。结合日志分析，发现 AI 在一个延迟敏感的接口中增加了同步远程调用。进一步对照最初的设计文档，才发现需求规范没有写明性能要求。结合这一根因，他很快完成止血并将接口进行优化，同时将这一非业务性需求加入 agents.md 规范中。

这个案例说明，SDD 不能保证设计没有遗漏；但设计文档保留了当时的决策依据，开发者至少可以对照实现，发现缺失的性能约束，并据此修正。缺少这些记录时，问题诊断就少了一项可核对的依据。

下图对比了 SDD 和 Vibe Coding 的问题回溯路径：有明确设计不代表结果完美，但至少能沿着记录追问、定位和修正。

从瀑布到敏捷，再到 SDD：重新平衡规范与迭代

软件研发方法论的演进，本质是人类对“如何在不确定中保证可靠交付”的持续探索。

每次技术环境发生重大变化，软件开发方法论都会随之调整。AI 辅助编程的出现，也在推动新的范式迁移：

瀑布模型：规范完整，但难以拥抱变化

1970 年，温斯顿·罗伊斯（Winston Royce）提出了著名的“瀑布模型”。它的核心思路简单而严谨：先确定做什么（需求分析），再决定怎么做（方案设计），然后编码、实现并测试。各个阶段顺序执行，前一阶段的输出作为后一阶段的输入，像瀑布一样自上而下流动。

瀑布模型的优点在于结构清晰，每个阶段都有明确交付物。从需求分析、概要设计到详细设计和测试文档，这些产物构成完整的决策链条，便于追溯。

但这一切建立在需求可以稳定确定的假设上。现实中的软件系统会随外部环境变化，一旦客户反馈“这不是我想要的”，前面的设计就可能需要重新评估，甚至推倒重来。

若用建筑图纸来比喻，瀑布模型就像在施工前把每根管线、每个开关都设计清楚，再让施工队按图施工。一旦甲方提出变更，图纸就要重新评估和调整，交付效率随之下降。

敏捷开发：迭代更快，但设计容易失去留痕

可工作的软件，胜过无数详细的文档。

2001 年，17 位软件研发者共同提出敏捷宣言，倡导以短周期迭代规划和研发。需求不必一步到位，可以在迭代中逐步澄清。

长期维护同一系统时，开发者通常了解项目背景和既有设计。部分团队因此只用口头说明或简短文字交接需求，并省略技术设计文档，以提高交付速度。这样做依赖维护者的个人记忆，设计依据并没有被正式记录。

AI 却不一样：新的对话请求往往拿不到前序背景，单靠简短的口头表述难以保证可靠交付。

如果用装修来比喻，敏捷开发像边施工边调整方向：同一批施工队熟悉设计背景，简短的口头表述通常尚可勉强推进迭代。AI 却像每个周期都换一批施工队；它们不了解前一周期的决策，简短表述自然不足以保证可靠交付。

SDD：规范先行，代码跟随迭代

随着 AI 工具普及，一种新的软件开发方式逐渐出现。它来自开发者在大量 AI 协作和踩坑中的实践沉淀，通过明确的规格驱动 AI 生成代码。

SDD（Specification Driven Development，规范驱动开发）可以概括为一句话：

规范是第一手工件，代码只是规范的衍生物

在 SDD 工作流中，人类工程师的核心产出不只是代码，而是需求规范、设计规范、开发规范和测试规范。AI 按这些规范生成代码，人类再据此验收。读到这里，你可能会问：SDD 不就是瀑布模型吗？区别在于，SDD 只约束本次工作的标准，不假设软件需求永远不变；需求发生变化时，规范也随之更新。

同时，SDD 有助于弥补部分敏捷团队在轻文档实践中造成的留痕不足：在设计阶段提取关键决策，固化为 proposal、design 和 task 文档，再驱动 AI 开发。

结语：让决策留下来，让代码能够被接手

这篇文章从一次线上自动化诊断 agent 的返工开始，追问 Vibe Coding 为什么会让系统越改越难接手。答案不是“AI 写得不够好”，而是需求、设计和决策没有被沉淀：需求会蒸发，上下文会漂移，评审看不到设计，维护者找不到“为什么”，最后每次改动都像数字考古。

SDD 给出的答案也不是回到瀑布模型，而是把规范变成第一手工件，同时保留敏捷的迭代能力。规范写得足够清楚，AI 才能按图生成代码；需求发生变化时，规范和代码一起更新。

AI 时代，开发者要记住：

规范是AI开发时代的第一手工件，代码只是规范化后的产物

参考资料

《SDD 实战 规划驱动开发之道》