企业官网建设流程全解析

最近 Agent 编程的热度越来越高，但你有没有发现一个怪现象：模型越强，反而越多人觉得“AI 写代码不可控”？原因是很多人把 Agent 当成一个“一句话生成完整项目”的许愿机，而不是一个需要流程约束的工程执行器。需求描述得越模糊，模型自由发挥的空间就越大，结果自然越不可控。这也是为什么社区里开始出现一个词：Agentic SDD，基于规范驱动的 Agent 开发。而最近这个 Show HN 项目提供了一种比较有意思的实现思路：它没有做成重平台，而是强调 minimal、composable、based on superpowers。这篇文章就围绕这四个关键词展开，讲清楚 Agentic SDD 是什么、superpowers 在其中的作用、怎么搭一个最小可运行的框架，以及实际使用中容易踩哪些坑。

先说我的核心判断：这类框架真正降低的不是“写代码”的成本，而是“需求对齐”和“Agent 行为约束”的成本。如果你只是随便写一个小脚本，直接对话也没什么问题；但当你希望 Agent 稳定地产出可维护、可测试、可交付的代码时，就必须把任务描述从聊天消息升级成结构化规范。SDD（Spec-Driven Development，规范驱动开发）正是这个思路，superpowers 则负责把 Agent 的通用能力沉淀成可组合的“技能”。读完这篇文章，你可以搭建一套最小框架，用一份 spec 加几个 skill 让 Agent 按规范干活，并且知道怎么验证它有没有“跑偏”。

1. 这篇文章真正要解决的问题

如果你用过 Claude Code、Codex 这类工具，大概率遇到过下面几种情况：第一次对话生成的效果不错，但继续加需求之后，代码开始出现重复模块；你明明只让它改一个接口，它却顺手改了数据库表结构；更常见的是，你提出一个需求，它给出的实现和你脑子里的预期差了十万八千里。这些问题的共同根源不是模型不够聪明，而是输入的任务结构不够严谨。

传统 prompt 工程的本质是“在聊天窗口里把需求说清楚”。这种方式对一次性脚本和小型原型有效，但对多文件、多步骤、需要验收标准的工程任务来说，约束力太弱。Agent 每调用一次模型，都有随机性；对话轮次越长，上下文漂移越严重。最后你发现自己在做的不是开发，而是“代码校对员”。

Agentic SDD 的思路是把“自然语言需求”和“AI 代码生成”之间插入一层“规范层”。开发者在动手前先把目标、接口、数据结构、验收标准写成 spec，然后 Agent 按照这份 spec 去实现代码，而不是凭感觉自由发挥。superpowers 在这一层提供了另一项关键能力：把实现过程中反复出现的操作，比如初始化项目、创建目录、运行测试、提交代码，封装成可复用的 skill，让 Agent 不用每个项目都从头推理一遍。

所以这篇文章面向的读者很明确：已经在用或者准备用 Agent 写代码的开发者，尤其是做多模块、需要长期维护项目的团队。你不需要立刻搞一个复杂的 Agent 平台，可以先从“最小可组合”的思路开始，用一份规范、几个技能、一个执行循环，把 Agent 开发从“碰运气”变成“按合同施工”。

2. 四个关键词拆解：Agentic、Composable、SDD、Superpowers

2.1 Agentic：不只是聊天，而是“带工具的执行链路”

Agentic 指的是智能体具备自主规划、调用工具、执行动作、观察结果并修正行为的能力。传统聊天机器人是“你问我答”，Agent 则是“你给目标，它拆步骤并执行”。在这个过程中，Agent 可以读文件、执行命令、写代码、跑测试，甚至调用外部 API。

但能力越强，越需要约束。如果一个 Agent 可以自由执行 Shell 命令，却没有明确目标和边界，风险直线上升。Agentic 开发模式真正要解决的是“如何让 Agent 在可接受的范围内自主完成多步任务”，而 SDD 正是用来划清这个范围的。

2.2 Composable：把技能当函数组合

Composable 这个词在 Vue 3 的组合式函数（composable）概念里也出现过，核心思想是“把逻辑拆成小块，再用组合的方式复用”。在 Agent 框架里，Composable 指的是 skill 可以被拆分、复用、嵌套。比如create-dir是一个基础技能，bootstrap-express可以组合create-dir和init-npm完成项目初始化，run-tests又可以单独调用。

这种设计带来的好处是低耦合。你不必在某个技能里写满所有步骤，而是像函数组合一样，把复杂任务拆成多个简单技能。每个技能只做一件事，却有清晰的输入输出，这样 Agent 的执行路径更容易被审查和追溯。

2.3 SDD：先写规格，再写代码

SDD（Spec-Driven Development）的直接含义是“规范驱动开发”。它要求先有一份足够精确的规格说明，再开始实现。规格里需要包含目标、范围、接口定义、数据模型、验收标准，甚至可以包含“明确不做的事”。

有人会问：这不就是传统的需求文档吗？区别在于，传统需求文档是给人看的，Agent 并不在乎；SDD 中的 spec 是给人与 Agent 共同看的一份“契约”。人靠它对齐预期，Agent 靠它减少随机发挥。很多 Agent 项目失控，正是因为 spec 缺失，导致模型只能在 conversation 里不停猜测需求。

2.4 Superpowers：Agent 的“技能插件体系”

Superpowers 在社区中更多以技能插件体系的形式出现，可以和 Claude Code、Codex 等 Agent 工具配合使用。它解决的是“Agent 每次都要重新发明轮子”的问题：你把常用操作沉淀成 skill，之后 Agent 遇到同类任务时直接调用，而不是从零推理。

从热词搜索中能看到，很多开发者关心“superpowers 安装”“superpowers skill”“superpowers 配合 Openspec 一起使用”。这其实反映了一个趋势：大家已经不再满足于“给 Agent 一个 prompt”，而是希望有一套可管理、可复用的技能库。Superpowers 就是这类探索中的一种较有影响力的实践。这篇文章说的框架，就是把 Agentic、Composable、SDD、Superpowers 组合在一起的最小落地方式。

3. 为什么是“极简 + 可组合”，而不是一个重量级平台

现在一提到 Agent 框架，很多人第一反应是“要不要上个平台、配一堆工作流节点、接一堆模型供应商”。但对大多数开发者来说，这个成本太高了，而且维护复杂。这个 Show HN 项目反而选择了另一个方向：极简。它只保留三个核心部分：spec 定义需求，skill 定义能力，agent 执行循环负责把前两者闭环。

重量级平台的优缺点都很明显。优点是一站式方案，调度、监控、权限都有；缺点是抽象层太多，出问题很难排查，而且学习成本高。对个人开发者和中小团队而言，很多功能根本用不上。极简框架的思路是“保留最核心的循环，让用户自己填充业务逻辑”，这更像一个脚手架而不是操作系统。

可组合则解决另一个问题：积累。如果你所有流程都写死在一个框架里，那么换项目、换 Agent 工具，之前的经验就浪费了。但如果能力被拆成一个个 skill，这些 skill 可以在不同项目间复用。比如你为 Node.js 项目写了一个bootstrap-express技能，下一个 Node 后端项目还能继续用；你在旧包里封的run-test技能，也可以接入新的 Agent 工作流。

所以我的判断是：极简和可组合并不是“功能少”，而是把复杂性放到正确的位置。框架不替你决定所有的事情，它只提供一套清晰约定。你不需要理解上百个概念，只需要会写 spec、会写 skill、会跑命令，就可以开始。

4. 环境准备与前置条件

实践这部分之前，先确认你的环境包含以下内容：

我没有在这里写死具体版本号，因为 superpowers 和相关 Agent 工具更新很快，不同时间的安装方式差异较大。更稳妥的做法是在动手前先查看对应项目的 README，确认当前版本的安装命令。

另外，如果你在 Windows 上使用，需要注意 Shell 兼容性。Claude Code 和 Codex 通常都支持跨平台，但如果你的 skill 里包含 Shell 脚本，尽量用跨平台写法，或者在容器中运行 Agent，避免目录分隔符和环境变量差异导致执行失败。

安装完之后，建议先试跑一个最小的 skill 验证链路。比如让 Agent 执行“创建一个hello.txt文件并写入hello sdd”，确认它能调用工具、读写文件，再开始真正的项目。这一步能提前暴露权限、路径、网络等问题。

5. 核心流程拆解：Spec → Skill → Execute → Verify

Agentic SDD 框架的最小循环可以拆成四步：

5.1 定义 Spec

这是最关键的一步，但也是最容易被忽略的一步。Spec 不需要写成长篇大论，但必须覆盖四个关键部分：目标、范围、接口或数据模型、验收标准。推荐格式是 Markdown，因为它的可读性强，Agent 也容易解析。

写 Spec 时有一个技巧：把验收标准写成“可勾选清单”。比如“GET /health返回 200”比“接口要健康检查”更可验证。Agent 在实现完后能按清单逐项确认，而不是含糊地说“做完了”。

5.2 拆解 Skill

Skill 对应 Agent 的可复用能力。好的 Skill 应该像函数：有明确的名字、描述、输入、执行步骤、验证方式。建议一个 Skill 只做一件事，然后通过组合完成复杂任务。

比如创建一个 Express 项目，可以拆成：

• create-dir：创建目录结构
• bootstrap-express：初始化 package.json 并安装依赖
• run-tests：运行测试命令

这样做的好处是，日后某个步骤变了，你只需要改对应的 Skill，而不需要改整个 Agent 流程。

5.3 执行 Agent

将 Spec 和 Skill 交给 Agent，让它按顺序执行。执行时最好给 Agent 一个明确指令：“读取specs/todo-api.md，使用skills/下的技能完成实现，并运行验收清单。”不要让它先做别的事，也不要给它太多无关上下文，任务范围越聚焦，结果越可靠。

5.4 验证结果

验证不只看“代码有没有生成”，还要看“验收标准是否通过”。可以在 Spec 里明确指出“完成标准是测试通过”，也可以额外要求“运行npm test并输出结果”。这一步是整个框架闭环的保障。

6. 完整示例：用 Agentic SDD 构建一个小型待办 API

下面用一个最小项目演示完整流程。这里不依赖特定的 Agent CLI，重点理解文件结构和写法。

6.1 项目结构

agent-sdd-demo/ ├── specs/ │ └── todo-api.md ├── skills/ │ ├── create-dir.md │ ├── bootstrap-express.md │ └── run-tests.md ├── superpowers.config.json └── README.md

specs目录放规格文档，skills目录放可复用技能，superpowers.config.json用来声明技能注册信息。不同版本的 superpowers 对配置文件要求不同，这里以通用结构演示。

6.2 编写 Spec 文件

# Todo API 规格 ## 目标 提供一个最小可用的待办事项 REST API，支持增删改查。 ## 范围 - 使用 Node.js + Express 实现 - 数据存储使用内存数组，不引入数据库 - 提供 /health 健康检查接口 ## 接口定义 - GET /health - 返回 200，body 为 { "status": "ok" } - GET /todos - 返回待办列表，结构为数组 - POST /todos - 请求体 { "title": string } - 返回新创建的 todo 对象，包含 id、title、done 字段 - PUT /todos/:id - 请求体 { "title"?: string, "done"?: boolean } - 更新指定 id 的 todo，返回更新后的对象 - DELETE /todos/:id - 删除指定 id 的 todo，返回 204 ## 数据结构 { "id": "string", "title": "string", "done": "boolean" } ## 验收标准 - [ ] 启动后访问 GET /health 返回 200 - [ ] 创建 todo 后，GET /todos 能查到新数据 - [ ] 更新 todo 的 done 字段后，查询结果返回更新后的值 - [ ] 删除 todo 后，GET /todos 不再包含该数据 - [ ] 所有接口在请求非法数据时返回 400 ## 非目标 - 不实现用户认证 - 不引入数据库 - 不处理跨域

这份 Spec 的亮点是“验收标准”全部可勾选，“非目标”清晰标出了边界。Agent 在实现时不会因为“顺手优化”而引入数据库或认证，因为规范里明确说不需要。

6.3 配置 Skill

下面以skills/bootstrap-express.md为例，展示一个技能描述文件。这个格式是社区常见的“Markdown + frontmatter”写法，实际字段名以你用的 superpowers 版本为准。

--- name: bootstrap-express description: 初始化一个 Express 应用骨架 trigger: 需要创建 Express 项目时 inputs: projectDir: 项目目录 steps: - 在 projectDir 中初始化 package.json - 安装 express - 创建 src/index.js - 添加 /health 路由 verification: - 运行 node src/index.js - 请求 /health 应返回 200 ---

这个 Skill 描述了“什么时候用、输入什么、做什么、怎么验证”。Agent 读到一个 Skill 时，实际上拿到了一份可执行的“操作手册”。

同样，skills/run-tests.md可以简单描述为运行测试命令并输出结果。如果团队使用统一测试框架，还可以把固定命令写进去，避免 Agent 自创测试方式。

6.4 编写 Agent 调用逻辑

假设你有一个自定义 Agent 入口，可以在 orchestration 脚本中按顺序加载 Spec 和 Skill。下面是一段 Python 演示代码，它模拟“读取 Spec → 遍历 Skill → 调用外部 Agent CLI”的整个过程。

# file: orchestrator.py import subprocess import sys SPEC_PATH = "specs/todo-api.md" SKILLS = [ "create-dir", "bootstrap-express", "run-tests", ] def read_spec(path: str) -> str: with open(path, encoding="utf-8") as f: return f.read() def run_skill(skill_name: str, spec_path: str) -> None: print(f"run skill: {skill_name}") # 这里需要替换成你实际使用的 agent CLI 命令 cmd = ["agent-cli", "run", skill_name, "--spec", spec_path] result = subprocess.run(cmd, capture_output=True, text=True) if result.returncode != 0: print(result.stdout) print(result.stderr) raise SystemExit(f"skill failed: {skill_name}") print(result.stdout) def main() -> None: spec = read_spec(SPEC_PATH) print("spec loaded, length:", len(spec)) for skill in SKILLS: run_skill(skill, SPEC_PATH) print("all skills executed. please verify acceptance checklist.") if __name__ == "__main__": main()

这段脚本不是某个真实 CLI 的完整封装，而是一种模式：框架本身不关心 Agent 是 Claude Code 还是 Codex，只关心“你是否按流程执行”。你只需要把cmd换成实际命令。比如使用 Claude Code 时，可以直接传递一个 prompt 风格的命令，让 Agent 按路径读取 Spec 并执行。

如果你不想自己写编排脚本，也可以直接在终端里运行：

cd agent-sdd-demo claude "请读取 specs/todo-api.md，按规范实现代码。先执行 create-dir，再执行 bootstrap-express，最后执行 run-tests 并报告结果。"

用哪种方式取决于你的 Workflow。极简框架并不限制你使用单一工具，你甚至可以在 CI 里运行编排脚本，实现“提交 Spec 后自动生成代码”。

6.5 实现完成后的人工验证

Agent 生成代码后，不要立刻信任它。先按验收清单逐项跑一遍：

cd agent-sdd-demo npm install npm start

然后打开另一个终端：

curl http://localhost:3000/health

预期返回{"status":"ok"}。接着创建一条待办：

curl -X POST http://localhost:3000/todos \ -H "Content-Type: application/json" \ -d '{"title":"Write blog"}'

正常情况会返回带id的对象。再执行GET /todos，如果能查到刚创建的记录，说明 Agent 生成的接口基本符合 Spec。

如果这里返回的是空数组，不要急着改代码，先检查 Agent 是否真的实现了数据存储逻辑，还是只写了接口签名。这个排查过程，其实就是在验证 Spec 是否足够清晰。

7. 运行结果与效果验证

判断一个 Agentic SDD 框架是否真正跑通，建议按下面的顺序验证：

1. Spec 是否能被 Agent 正确读取。执行前打印 Spec 内容，确认 Agent 拿到的就是你想让它实现的那份文件。
2. Skill 是否能被正确触发。观察 Agent 输出，看它是否按 Skill 中的步骤执行，而不是自创步骤。
3. 验收清单是否逐项通过。每个 checkbox 对应一个可以自动或手动验证的点，不能存在“差不多完成”的模糊状态。
4. 生成代码中是否出现 Spec 之外的模块。如果 Spec 没提认证，Agent 却加了一层登录逻辑，说明约束不够。

如果失败，先看执行日志。日志里通常能看到 Agent 在哪个 Skill 步骤出错、哪个命令返回非零、哪个文件读取失败。先用最小范围定位，再决定是改 Spec、改 Skill 还是换工具，避免反复对话消耗 context。

8. 常见问题与排查思路

上面这些问题的共性原因是“规范不够可执行”。尤其是第一项，如果 Agent 随心所欲，先不要怪模型，先看你的 Spec 是否把“做什么、不做什么、怎么验收”写清楚了。这也是 Agentic SDD 和直接写 prompt 最大的区别。

9. 最佳实践与工程建议

基于目前社区和工程实践经验，下面几条建议比较有价值：

第一，一次只定义一个薄 Spec。很多团队一上来就写完整业务流程，Agent 一次处理不了，中间还会不断加需求。更推荐的做法是每次只定义一个模块，甚至一个接口。把大需求拆成多次小任务，每次 Agent 只完成一个清晰目标。

第二，Skill 命名使用动词，比如create-dir、bootstrap-express、run-tests、commit-changes。这类命名让 Agent 更容易识别调用时机，也让维护者一看就知道这个技能做什么。

第三，把 Skill 当作函数来写。一个 Skill 的输入输出越明确，组合起来越容易。如果某个 Skill 中出现了“先后做 A、B、C 再恢复环境”这种长步骤，考虑拆成多个 Skill。

第四，Spec、Skill 和生成代码全部纳入版本管理。这样当 Agent 生成的结果有问题时，可以快速反查是 Spec 变了吗，还是 Skill 执行方式变了，或者 Agent 工具版本升级导致行为变化。

第五，涉及数据删除、认证、支付等敏感操作时，不要给 Agent 太大权限。建议在沙箱目录里运行 Agent，用最小权限 token，并且把生成结果交给人工 review。严格禁止 Agent 直接操作生产环境。

第六，把执行日志保留下来。每次运行记录 Spec 的哈希、Skill 的版本、Agent 输出和测试结果。Agent 开发最大的问题之一是“不可复现”，有了日志才能定位和优化。

10. 总结与后续学习方向

Agentic SDD 框架解决的核心问题，是把 Agent 从“自由发挥的代码生成器”变成“按规范执行并验证的工程师”。Superpowers 在这里的作用，是把“能力”沉淀为“可组合的 Skill”，让 Agent 不重复造轮子，也让团队的工程经验得以积累。

如果你准备尝试，建议从一个小模块开始：写一份包含目标、接口、验收标准和“非目标”的 Spec，配置两三个 Skill，让 Agent 执行一轮并逐项验证。你会发现，真正让代码质量稳定的，不是模型有多强，而是任务边界和验证标准有多清晰。

后续可以继续研究 Openspec 的规范目录组织方式、Agent 可观测性、测试自动生成、以及 Agent 安全边界等主题。先把最小循环跑通，再逐步增加复杂度，会比一开始就搭一个“全家桶式”框架踏实得多。