企业官网建设流程全解析

先说一个我这阵子的感受：给大模型智能体写提示词，写到第七八版的时候，真的会崩溃。你可能也会遇到类似情况——上一版还是好用的，改了一个句式之后，某个分支突然就疯了；产品经理提了一个新需求，你在几千字的 system prompt 里翻来翻去找插入点；到了验收阶段，测试同事问“那这个行为到底应该在哪条规则里改？”你发现自己完全回答不上来。

“初识 GitHub Spec Kit”这件事就是从这个痛点开始的。我一开始以为它就是又一个提示词模板仓库，用下来才发现，它背后是一整套“规范驱动开发”的思路：把原本放在提示词里的角色设定、行为边界、交互流程，全部拆成结构化的规范文件，再由工具生成最终给模型用的指令和配置。这篇文章不打算把官方文档搬一遍，而是结合我们团队实际落地一个内部知识助手的过程，讲讲 Spec Kit 的核心思路、操作步骤，以及真正使用时最容易踩的坑。

1. 为什么提示词工程的尽头是规范工程

1.1 提示词开发模式的三重困境

以前我们做大模型应用，思路特别简单：把需求写进 system prompt，模型表现不对就微调提示词。小 demo 这么玩没问题，一旦进入正式项目，三个问题会同时冒出来。

第一是没有版本和结构。system prompt 本质是一大段自然语言，你改掉一句话，模型理解顺序可能就变了。而且没人能说清楚“这句话到底管不管用”，只能靠在线调、看日志、猜测效果。Git 只能告诉你改了什么，不能告诉你为什么这么改。

第二是不可测试。代码有单元测试，提示词没有。你很难写一条断言说“当用户输入 X 时，模型必须走 Y 分支”。普通人写的提示词天然不是结构化数据，想做回归测试要自己造一套外部工具，等于重复造轮子。

第三是协作混乱。提示词通常由开发一个人维护，但真正需要参与决策的往往是产品、运营、法务、客服负责人。你不可能让不懂代码的同事去 review 一段 2000 字、塞满英文指令的 system prompt，他们只能口头提意见，最后由开发忍着烦躁手工修改。

这三个困境叠加起来，会形成一个非常反直觉的结论：项目越复杂，提示词越不应该存在。真正应该存在的是规范。

1.2 规范驱动开发到底是什么

所谓规范驱动开发，就是把“模型应该做什么”这件事，从一段不可量化的叙述，变成一份可以阅读、可以校验、可以生成代码引用的结构化资产。

我用盖房子来类比。传统提示词模式，相当于你给施工队长发一段微信语音：“你看着弄，客厅要敞亮，厨房别太小，最好有个书房，但也不一定……”队长理解成什么样，房子就盖成什么样。而规范驱动开发，是先出一套施工图：哪里是承重墙、哪里留门窗、电路怎么走，每一处都有明确标注。施工队拿到图纸只需要按图执行，就算工人换了，房子也能盖得八九不离十。

Spec Kit 正式把这个思路变成了可操作的工具链。它不替你把业务想好，而是给你一套写规范的方法和生成机制。你在规范文件里定义角色、目标、允许行为和禁止行为，定义用户和智能体之间的交互规则，然后工具自动帮你把这些规范编译成模型运行所需的系统提示词、交互协议和验证规则。这样做的好处是，团队 review 的是规范，不是提示词；测试测的是规范，也不是提示词。

这句话值得反复琢磨：规范的抽象层次比提示词高得多，可维护性也高得多。提示词是给模型看的“最后成品”，规范才是项目团队真正应该维护的“源文件”。

2. Spec Kit 到底做了什么，又不是什么

2.1 它不是提示词收藏夹，而是一套工作流

第一次进 GitHub 仓库淘 Spec Kit 的时候，我一度以为它跟上面那些“精选提示词合集”差不多：一堆 Markdown 文件，配几个示例。后来认真跑通流程才意识到，项目的核心是**“先写规范、再生成提示词”这条流水线**，文件组织方式只是这条流水线的产物。

它的完整工作流是这样的：

1. 你在一系列规范标记文件里，用自然的、结构化的写法描述智能体的角色、职责、边界和交互方式。
2. 工具读取这些规范，检查格式是否完整、约束是否冲突。
3. 校验通过后，工具生成真正喂给大模型的内容，比如 system prompt、few-shot 示例、交互字段的 JSON 定义。
4. 如果后续改了规范，重新跑一遍生成命令，产物会自动同步更新。

这个模式最大的价值在于，你终于不用再面对 Unicode 转义满屏飞、写了一万字的提示词文件了。规范文件是给人看的，生成产物才是给模型看的。人看的文件可以很详细、很结构化，机器生成的产物可以临时删改，只要下次重新生成，一切归位。

2.2 规范文件的常见组织和结构

以我们去跑通的默认脚手架为例，目录结构大致长这样：

support-agent/ ├── spec/ │ ├── overview.md # 智能体全局定位、服务对象、主要目标 │ ├── role.md # 角色设定与语气边界 │ ├── policies.md # 禁止行为、合规要求、兜底策略 │ ├── interactions/ │ │ ├── order-status.json # 按钮/表单等结构化交互 │ │ └── refund-request.json ├── build/ │ ├── system-prompt.md # 生成的最终系统提示词 │ └── interactions.json # 生成的交互配置 ├── tests/ │ └── scenarios.md # 验收场景和回归用例 └── spec-kit.config.json # 项目级配置

这里最关键的三个文件是overview.md、role.md和policies.md。

overview.md解决的是“这个智能体为什么存在”。很多团队跳过的就是这一步，直接写细节，结果模型表现得像个什么都会、但什么都不精的万能聊天机器人。写清楚服务对象、主要目标和成功标准，后续所有规则都从这里推演。

role.md解决的是“智能体怎么说话”。它不只是语气，还包含信息详略、敏感话题怎么处理、什么时候坚持立场、什么时候让步。比如一个客服助手，面对情绪激动的用户，是先道歉还是先给方案，必须在规范里明确。

policies.md是“绝对不能做的事”。它往往比正向规则更重要。把“员工不能承诺法律条款”“遇到疑似诈骗信息必须转人工”这类硬约束写清楚，生成提示词时会保留，不会因为在上下文窗口里被冲淡。

2.3 用表格理解 Spec Kit 的关键命令

跑通了几个项目之后，我把常用的命令整理成了下面这个表格，方便新同事快速入手。

用惯了之后你会发现，日常开发其实集中在validate和build两个命令上。前者是“改完规范到底合不合法”，后者是“合法之后怎么变成可执行的指令”。这两步分离得非常清楚，也正好对应传统工程里 lint 和 compile 的职责。

3. 我们如何用 Spec Kit 把一个内部知识助手跑通

3.1 背景：为什么选这个场景试水

我们当时接到的需求是做一个内部 IT 支持助手，员工可以问“怎么申请远程访问权限”“电脑连不上打印机怎么排查”这类问题。第一版开发直接用了一段提示词，但团队很快发现，知识库里有一百多篇操作手册，提示词不可能全塞进去，只能靠智能体自己决定是否调用知识库接口。这非常容易出现行为漂移：同一个问题，早上答得挺好，下午突然就输出了一份完全错误的指导。

选择用 Spec Kit 重构这个项目，理由有三个：任务边界清晰、知识库有系统接口、需要频繁迭代规则。这三条恰好是规范驱动开发最擅长的场景。

3.2 第一次初始化与最小规范编写

第一步是用脚手架初始化项目，命令如下。

spec-kit init it-support cd it-support

命令执行后，目录里会出现一堆模板文件。我的建议是不要急着全填满，只改三个文件：overview.md、role.md、policies.md。

我们当时的overview.md写了这样一段内容：

# 项目定位 本智能体面向公司内部员工，专职处理 IT 支持问题。 # 服务范围 1. 账号与权限申请查询 2. 办公设备故障排查 3. 软件安装与授权问题 # 成功标准 - 70% 的常规问题能在 3 轮对话内解决 - 不准确回答不属于自身职责范围内的业务问题 - 涉及安全事件时，必须转人工，不自行处理

写完这样的概述之后，模型的行为有了一个“锚”。之后写的所有规则，都要能回答“它跟这个目标有关系吗”这个问题。

3.3 把“规则”变成可执行的条目，而不是形容词

在写policies.md的时候，我们反复纠正一种写法：喜欢用形容词，不喜欢用条件句。比如“要提供清晰、准确的帮助”，这句话等于没说。“清晰”对模型来说是主观的，“准确”也很难自动判断。Spec Kit 的校验器最不能接受的其实是这种模糊规则。

后期我们把模糊规则改成了可测试的行为描述：

## 规则 001 - 触发条件：员工询问“如何申请远程访问权限” - 行为要求：输出申请步骤前，必须先确认员工是否已经提交直属主管审批 - 禁止行为：直接推送申请链接，忽略审批状态 ## 规则 002 - 触发条件：员工反馈公司电脑无法连接公司 WiFi - 行为要求：优先按“重启网卡流程”排查，再引导检查公司证书 - 禁止行为：要求员工自行修改 DNS 设置，除非已升级到人工支持

这样改完之后，测试脚本终于能写断言了。我们可以在测试场景里模拟一段员工对话，然后断言“模型输出中是否包含审批确认步骤”“是否提到修改 DNS”。虽然 Strictly 是在测生成结果，但规则的源头已经变成了规范文件。

3.4 接入业务接口与回归测试闭环

规范文件只是静态规则，真正让智能体干活，还需要把它接到后端的 IT 服务系统上。我们的做法是：用interactions文件定义交互动作，让模型在对话过程中返回结构化的动作指令，由后端服务解释执行。

一个典型的interactions文件片段长这样：

{ "interaction_id": "req_permission", "trigger": "员工申请远程访问权限", "fields": [ { "name": "employee_id", "type": "text", "label": "工号" }, { "name": "manager_email", "type": "text", "label": "主管邮箱" } ], "on_submit": { "api": "it_support.create_ticket", "mapping": { "employee_id": "submitter", "manager_email": "approver" } } }

这里有一点要提醒：Spec Kit 本身不帮你调后端接口。它负责生成“模型应该输出哪些字段”的定义，真正请求后端网关的逻辑还是得由业务代码处理。我们最开始误以为它是个低代码机器人平台，浪费了不少时间理解边界。其实它的角色很纯粹：稳定地告诉你，当前对话状态下，模型应该输出什么结构化动作。

跑通后，我们把 30 个常见问题场景写进了tests/scenarios.md，每次改完规范先跑一遍回归，再合并发布。这套流程做完之后，最明显的变化是：以前处理规则调整要开半天会，现在只需要改一条 markdown、跑一次验证、放两个测试用例就结束了。

4. 真实迭代三个版本后，我们总结的几个坑

4.1 把规范写成了项目说明书，模型根本不看

这是刚上手最容易犯的毛病。我们因为“模板很完整、很方便填”，一口气把背景、历史、价值观全写了，结果生成的 system prompt 长达四千多字。模型输入长度是有限的，太多冗余内容会挤占真正关键的行为规则。

后来我们把规范文件按照“越重要的越靠前、越具体的越靠前”的原则重排，把过去一大段“公司介绍”压缩到两句话，把行为约束和触发条件提前。效果立竿见影，模型的边界感明显强了很多。

有个经验值可以供参考：如果一份规范生成的系统提示词超过 2500 字，大部分内容可能都不该出现在 prompt 里。该放到知识库检索的就放到知识库检索，该放到后台配置的就放后台配置，不要一股脑塞给模型。

4.2 规范和运行时代码各改各的，漂移随后就到

第二个坑是因为团队协作不默契产生的。开发同学觉得改后端接口里的提示词字符串“更快”，就直接在代码里改了一句话，没有动 spec 文件。结果过了两周，spec 仓库里的脚本是旧的，线上行为是新的，验证器和实际表现完全对不上，出了问题也没法定位。

要解决这个问题，必须在 CI 里加一道检查：构建产物是否与规范文件完全匹配。具体做法是，规范变更 MR 合入后自动执行spec-kit build，然后把生成的产物文件与仓库里提交的产物文件做 diff。如果不一致，CI 直接报错。这样任何绕过规范的修改都会被卡住。

我强烈建议所有使用类似规范工具链的团队都做这一步。规范文件和产物文件的同步，应该像源代码和编译产物一样，要么二者一致，要么构建失败。否则规范文档又退化成了一堆没人看的模板。

4.3 交互泳道定义得太细，模型反而失去了应变能力

Spec Kit 很推崇把交互分成“按钮点击”和“自由文本输入”等不同泳道。一开始我们特别兴奋，把几十种操作都定义成了表单按钮，结果模型开始变得非常机械：所有对话都被它导向某一个按钮，用户稍微说一句超出定义的话，模型就不知道怎么接。

教训是，泳道适合用在“用户意图相对固定、步骤有明确顺序”的环节上，比如申请流程、账单查询、权限审批。而在开放式问答，比如“打印机怎么连接”“电脑蓝屏了怎么办”这种高度分散的问题，最好的交互模式仍然是自由输入，把泳道留给后端动作。

我们最后采用的原则是：只把后端必须依赖参数的动作定义成表单，其他一律让模型自由回答，仅在回答末尾给出引导按钮。这样既保持了规范的约束力，又没有把模型的表达能力压死。

4.4 多人协作时，规范评审比代码评审更费心力

编写规范不需要编程经验，但需要极强的逻辑一致性。产品说“要热情”，合规说“不能承诺不可控时效”，客服负责人说“要先道歉再处理”，这些意见单独看都对，放进同一份规范里就可能互相矛盾。

我们的做法是，把规范 review 分成两个环节：先由业务方确认“行为描述写的是不是业务真实流程”，再交给技术方确认“这些描述能否被测试逻辑覆盖”。业务和技术不在同一时间同一评论里拉扯。虽然没有直接证据证明这一做法更高效，但对团队情绪的影响是实打实的——大家终于不用在一条帖子里从产品吵到法务了。

5. 我把 Spec Kit 放在团队技术栈里的什么位置

5.1 适合用 Spec Kit 的项目类型

综合几次项目经验，我会把适合场景归纳为这几类：

• 规则频繁变化但核心目标稳定的智能体。比如客服、合规审查助手、行业知识问答，这类项目最大问题是每次改规则都要影响全局，规范正好提供单一入口。
• 需要强审计和追溯的合规场景。规范文件天然是清晰的文本记录，谁改了哪个行为、改成了什么，都有完整的 Git 历史可查。这个能力在传统提示词工程里几乎不存在。
• 多人协作、多角色评审的团队项目。产品、运营、法务可以分别维护自己领域的规范片段，由流水线合并统一生成，不用互相在同一个 prompt 里改来改去。
• 已经有知识库 API，但对话策略不稳定的项目。利用interactions把模型输出与流程引擎解耦，让后端服务负责执行，模型只负责理解意图和填充参数。

5.2 哪些场景我反而不推荐硬上

照例也得说点劝退话。如果你只是想快速验证一个原型、做一个单文件命令行助手、或者智能体只有三五个固定指令，那用 Spec Kit 绝对是过度设计。你要先写一堆之辈文件、配置命令、维护流程，这些成本比多写两行提示词的代价高多了。

另外，如果你需要的是一个完全开放式的创作类智能体，写诗歌、写文案、头脑风暴，规范的强约束反而会成为想象力瓶颈。这种情况下，传统提示词加上少量上下文管理会好用得多。

工具没有放之四海而皆准的道理，Spec Kit 也一样。它是为“确定性”设计的，如果你的需求场景天然追求不确定性，那它就不是你的答案。

5.3 我个人用过之后的体会

如果只让我总结一条使用建议，那就是：从最小规范开始。千万不要因为模板提供了二十个文件就全都填满。我们当初试水只保留了overview.md、role.md、policies.md和两个交互文件，直到业务真正出现重复迭代，才逐步把影子文件补上。规范文件和提示词一样，多不等于好，少不等于糙。

最后再分享一个操作细节。在团队提交规范变更时，我们可以要求描述里带上“目标行为变化”和“回归测试用例”，不用写长篇大论的说明。这样一来，reviewer 能快速看懂变更意图，测试人员也知道该关注哪些行为。很多人觉得规范驱动开发是大项目的束缚，但真正坚持下来之后，我发现它给团队带来的不是束缚，而是一种难得的“确定感”：你知道行为改动会自动同步、会进测试、可以被追溯，不会再出现线上表现和 Git 历史对不上的悬案。