企业官网建设流程全解析

1. 从“superpowers”说起：这套方法论到底想解决什么问题

第一次看到“superpowers”这个词，是在一个开发者社群里有人贴了一张截图，里面是一套围绕 Claude Code 和 Codex CLI 构建的 agentic skills framework。当时我的第一反应是：又是一个包装概念的东西。但仔细看完它的结构之后，我改变了看法——它其实在试图回答一个很实际的问题：当 AI 编程助手从“补全代码”进化到“自主执行任务”之后，我们该怎么组织这些能力，才能让它们真正稳定地干活？

这个问题的背景是这样的：Claude Code 和 Codex CLI 这类工具已经不只是聊天窗口了，它们能读写文件、执行终端命令、调用外部 API、甚至自己规划多步操作。但大多数人用它们的方式还停留在“问一句答一句”的阶段，没有形成一套可复用的工作流。superpowers 这套框架的核心主张就是：把 AI 编程助手当成一个需要被“编排”的团队成员，而不是一个更聪明的搜索引擎。

它适合谁来参考？我梳理了一下，大概三类人最需要：第一类是已经在用 Claude Code 或 Codex CLI，但感觉效率没有质变的开发者；第二类是团队里负责制定 AI 辅助开发规范的技术负责人；第三类是对 agentic skills 这个概念感兴趣、想自己搭一套类似体系的人。不管你用的是哪个工具，这套思路都有可迁移的地方。

接下来我会从设计思路、核心细节、实操过程、常见问题几个维度，把这套框架拆开讲清楚。不是照搬文档，而是结合我自己在 Ubuntu 和 macOS 上配置 Claude Code、在 VS Code 里调试 Codex CLI 的实际经验，把那些文档里不会写的坑和技巧一并交代。

2. 整体设计思路：为什么是“技能框架”而不是“提示词集合”

2.1 从提示词工程到技能编排的范式转变

大多数人接触 AI 编程助手的第一步，是学怎么写提示词。但提示词工程有一个根本性的局限：它是无状态的。你每次对话都要重新交代背景、重新设定角色、重新说明约束条件。对于一次性的小任务这没问题，但对于一个需要持续几小时甚至几天的开发任务，这种模式就崩溃了。

superpowers 的设计出发点就是解决这个“状态丢失”的问题。它的做法是把常用的开发能力抽象成一个个“技能”（skill），每个技能包含：触发条件、执行步骤、所需工具、输出格式、异常处理。这听起来很像传统软件工程里的“函数”或者“微服务”，只不过执行者从代码变成了 AI agent。

我举个例子你就明白了。假设你要让 AI 帮你重构一个模块。在纯提示词模式下，你得写：“你是一个资深 Python 开发者，请帮我重构以下代码，要求保持接口不变，提升可读性，添加类型注解……”然后 AI 给你一版，你发现它改了接口，你得重新强调。但在技能框架下，“重构”这个技能本身就内置了“接口不变”的约束，AI 在执行时会自动检查这个条件，不需要你每次重复。

注意：技能框架不是要取代提示词，而是把提示词里那些反复出现的约束和步骤固化下来。你仍然需要为每个技能写清晰的描述，只是这个描述只需要写一次。

2.2 为什么选择 Claude Code 和 Codex CLI 作为主要载体

市面上能执行终端命令的 AI 工具不少，但 superpowers 这类框架通常优先适配 Claude Code 和 Codex CLI，原因有几个。第一是这两个工具都提供了相对完整的“工具调用”接口，AI 不仅能生成文本，还能实际执行 shell 命令、读写文件、调用外部程序。第二是它们都有“项目级上下文”的概念，能读取项目里的配置文件，这为技能的定义和加载提供了天然容器。

第三点可能更重要：这两个工具的设计哲学都偏向“可组合”。Claude Code 支持通过配置文件定义自定义命令，Codex CLI 支持通过命令行参数切换模型和行为模式。这种可组合性让技能框架能够以插件的形式接入，而不需要修改工具本身的源码。

我在 Ubuntu 上配置 Claude Code 的时候，特意观察了它的配置文件加载顺序。它会先读全局配置，再读项目级配置，最后读当前目录的配置。这个层级结构正好可以用来组织技能：全局放通用技能，项目级放项目特定技能，当前目录放临时技能。这种设计不是巧合，而是工具作者有意为之的扩展点。

2.3 技能框架的四个核心抽象

拆开来看，superpowers 这类框架通常包含四个核心抽象，理解这四个东西，你就理解了整套体系。

第一个是Skill（技能）。这是最基本的单元，定义了一个具体的开发动作，比如“写单元测试”“生成 API 文档”“执行数据库迁移”。每个技能有明确的输入和输出，以及执行过程中需要遵循的约束。

第二个是Workflow（工作流）。工作流把多个技能串联起来，形成一个完整的开发流程。比如“新功能开发”工作流可能包含：需求分析 → 接口设计 → 代码实现 → 测试编写 → 文档更新。工作流定义了技能之间的依赖关系和执行顺序。

第三个是Context（上下文）。这是技能执行时的环境信息，包括当前项目结构、代码风格、依赖版本、环境变量等。上下文的质量直接决定了技能执行的效果。

第四个是Guardrail（护栏）。这是安全机制，确保 AI 在执行技能时不会做出危险操作，比如删除生产数据库、提交敏感信息、修改不该修改的文件。护栏通常以规则的形式定义，在技能执行前和执行中进行检查。

这四个抽象组合起来，就形成了一套可复用、可组合、可审计的 AI 辅助开发体系。我个人的体会是，刚开始只需要定义三五个核心技能，就能感受到效率的明显提升。随着技能库的积累，整个开发流程会越来越顺畅。

3. 核心细节解析：技能定义、加载与执行的完整链路

3.1 技能定义文件的格式与关键字段

技能定义通常是一个 Markdown 文件，放在项目根目录的.skills/文件夹下，或者放在全局配置目录里。文件名就是技能名，比如write-unit-test.md。文件内容分为两部分：YAML frontmatter 和正文。

YAML frontmatter 定义技能的元信息，关键字段包括：

• name：技能的唯一标识，建议用 kebab-case，比如write-unit-test。
• description：一句话描述这个技能做什么，会显示在技能列表里。
• triggers：触发条件，可以是关键词列表，也可以是自然语言描述。当用户的请求匹配到这些条件时，AI 会自动加载这个技能。
• tools：这个技能需要使用的工具列表，比如read_file、write_file、run_command。
• guardrails：这个技能特有的护栏规则，比如“不允许修改package.json”。

正文部分则是技能的具体执行步骤，用自然语言描述，但结构要清晰。我通常会用有序列表来写步骤，每一步都说明“做什么”和“为什么”。比如：

--- name: write-unit-test description: 为指定函数生成单元测试 triggers: - 写测试 - 生成单元测试 - unit test tools: - read_file - write_file - run_command guardrails: - 不允许修改被测函数的实现 - 测试文件必须放在 tests/ 目录下 --- 1. 读取目标函数的源码，理解其输入、输出和边界条件。 2. 检查项目中是否已有测试框架，优先使用已有的框架。 3. 根据函数的参数类型和返回值，设计至少三个测试用例：正常情况、边界情况、异常情况。 4. 生成测试代码，确保测试文件命名符合项目规范。 5. 运行测试，确认全部通过。如果失败，分析原因并修正测试代码。

这个格式的好处是，AI 在加载技能后，能清楚地知道自己的任务边界和约束条件，不需要你每次重复交代。

3.2 技能加载机制：什么时候加载、加载哪些

技能加载有两种模式：自动加载和手动加载。自动加载依赖triggers字段，当你的请求里包含触发词时，AI 会自动把对应的技能加载到当前上下文。手动加载则是通过命令显式调用，比如在 Claude Code 里输入/skill write-unit-test。

自动加载的优点是省事，缺点是可能加载了不需要的技能，占用上下文窗口。我的经验是，把最常用的三五个技能设为自动加载，其他的用手动。另外，triggers的关键词要选得精准一些，不要用太泛的词。比如“测试”这个词太泛，可能在你只是想讨论测试策略时也被触发。用“写测试”“生成测试”这种更具体的短语会好很多。

还有一个细节：技能加载是有优先级的。项目级技能会覆盖全局技能，当前目录技能会覆盖项目级技能。这个机制可以用来做项目特定的定制。比如全局的write-unit-test技能用的是 pytest，但某个项目用的是 unittest，你可以在项目级目录里放一个同名技能，覆盖全局的。

提示：如果你发现某个技能总是被意外触发，检查一下它的triggers是不是太宽泛了。我踩过这个坑，后来把触发词从“文档”改成“生成 API 文档”就解决了。

3.3 上下文注入：让 AI 知道“现在是什么情况”

技能执行的效果，很大程度上取决于上下文的质量。superpowers 框架通常会在技能执行前，自动注入以下几类上下文：

• 项目结构：当前目录的文件树，让 AI 知道项目里有哪些文件、怎么组织的。
• 代码风格：从已有的代码文件里提取的命名规范、缩进风格、注释习惯等。
• 依赖信息：从package.json、requirements.txt、go.mod等文件里读取的依赖列表和版本。
• 环境变量：当前 shell 的环境变量，但会过滤掉敏感信息。
• Git 状态：当前分支、最近提交、未提交的修改。

这些上下文不是一股脑全塞进去的，而是根据技能的需要选择性注入。比如“写单元测试”技能需要项目结构和依赖信息，但不需要 Git 状态。这种选择性注入既节省了上下文窗口，也减少了干扰。

我实测下来，上下文注入的质量对技能执行效果影响极大。有一次我在一个没有requirements.txt的项目里执行“写单元测试”技能，AI 因为不知道用了什么测试框架，生成了一堆 pytest 代码，但项目实际用的是 unittest。后来我在技能定义里加了一条“如果找不到依赖文件，先询问用户使用什么测试框架”，问题就解决了。

3.4 护栏机制：怎么防止 AI “好心办坏事”

护栏是技能框架里最容易被忽视、但最重要的部分。AI 在执行任务时，有时候会“过度热情”，比如你让它修一个 bug，它顺手把整个文件重写了；你让它加一个日志，它把日志级别改成了 DEBUG 并且提交了。

护栏机制通过规则来约束 AI 的行为。规则可以分几个层级：

• 全局护栏：适用于所有技能，比如“不允许执行rm -rf”“不允许修改.env文件”“不允许直接 push 到 main 分支”。
• 技能级护栏：特定技能的约束，比如“写单元测试”技能不允许修改被测函数的实现。
• 运行时护栏：在技能执行过程中动态检查，比如“如果修改的文件超过 5 个，暂停并请求确认”。

护栏的实现方式通常是在技能执行前和执行中插入检查点。执行前检查是静态的，看 AI 的计划里有没有违规操作。执行中检查是动态的，每执行一步就检查一次。如果发现违规，AI 会暂停并请求用户确认。

我自己的做法是，全局护栏尽量严格，技能级护栏根据实际情况调整。比如在个人项目里，我可以允许 AI 直接修改文件；但在团队项目里，我会要求所有修改都先展示 diff，确认后再写入。

4. 实操过程：从零搭建一套可用的技能框架

4.1 环境准备：Claude Code 与 Codex CLI 的安装与配置

在开始搭建技能框架之前，你需要先确保 Claude Code 或 Codex CLI 能正常工作。我分别在 Ubuntu 和 macOS 上装过这两个工具，流程大同小异，但有几个坑值得提前说。

Claude Code 的安装，官方推荐的方式是通过 npm 全局安装。在 Ubuntu 上，你需要先确保 Node.js 版本不低于 18。我建议用 nvm 来管理 Node 版本，这样切换起来方便。安装命令是：

npm install -g @anthropic-ai/claude-code

安装完成后，第一次运行claude会引导你完成登录和初始化配置。如果你在 VS Code 里使用，还需要安装 Claude Code 的 VS Code 插件，然后在设置里配置好路径。

Codex CLI 的安装，同样是通过 npm：

npm install -g @openai/codex

这里有一个常见的坑：在国内网络环境下，npm 安装可能会很慢甚至超时。我的解决办法是配置 npm 的镜像源，或者用pnpm代替npm，速度会快很多。另外，Codex CLI 对 Node 版本也有要求，建议用 LTS 版本。

安装完成后，你可以通过codex --version和claude --version来验证是否安装成功。如果遇到权限问题，在 Linux 上可能需要用sudo，但我不建议全局用sudo装 npm 包，更好的做法是配置 npm 的全局目录到用户目录下。

注意：如果你在 VS Code 里同时使用 Claude Code 和 Codex CLI，建议给它们配置不同的快捷键，避免冲突。我一开始没注意，结果按快捷键总是唤起错误的工具。

4.2 技能目录结构设计与初始化

环境准备好之后，下一步是设计技能目录的结构。我推荐的结构是这样的：

project-root/ ├── .skills/ │ ├── global/ │ │ ├── write-unit-test.md │ │ ├── generate-api-doc.md │ │ └── refactor-code.md │ ├── project/ │ │ ├── deploy-staging.md │ │ └── run-migration.md │ └── local/ │ └── debug-current-issue.md ├── .claude/ │ └── config.json └── .codex/ └── config.json

global/放通用技能，project/放项目特定技能，local/放临时技能（这个目录应该加到.gitignore里）。.claude/和.codex/分别是两个工具的配置文件目录。

初始化的时候，我建议先从三个技能开始：一个代码生成类（比如“写单元测试”），一个代码分析类（比如“解释这段代码”），一个流程类（比如“提交前检查”）。这三个技能覆盖了日常开发中最常见的场景，能让你快速感受到技能框架的价值。

4.3 编写第一个技能：以“写单元测试”为例

我们来完整走一遍编写技能的过程。假设你要为一个 Python 项目写一个“写单元测试”技能。

第一步，确定技能的边界。这个技能只负责生成测试代码，不负责修改被测代码，不负责运行测试（运行测试是另一个技能）。边界清晰了，护栏就好写了。

第二步，写 YAML frontmatter。triggers我设了三个：“写测试”“生成单元测试”“unit test”。tools需要read_file、write_file、run_command。guardrails设了两条：不允许修改被测函数，测试文件必须放在tests/目录下。

第三步，写执行步骤。我把它分成五步：读源码、检查测试框架、设计用例、生成代码、运行验证。每一步都写清楚“做什么”和“为什么”。

第四步，测试技能。我找了一个简单的函数，输入“写测试”，看 AI 是否自动加载了这个技能，执行结果是否符合预期。第一次测试时，AI 把测试文件放在了项目根目录，而不是tests/目录下。我检查了技能定义，发现护栏里写了“测试文件必须放在 tests/ 目录下”，但 AI 没有遵守。后来我在执行步骤里也加了一条“测试文件路径为 tests/test_<函数名>.py”，问题就解决了。

这个经历告诉我，护栏和执行步骤要互相配合。护栏是“不允许做什么”，执行步骤是“应该怎么做”。两者都写清楚，AI 的执行才会稳定。

4.4 技能组合与工作流编排

单个技能用起来之后，下一步是把它们组合成工作流。工作流的定义方式和技能类似，也是 Markdown 文件，但内容是指定技能的执行顺序和条件。

比如一个“新功能开发”工作流：

--- name: new-feature description: 从需求到测试的完整开发流程 skills: - analyze-requirement - design-interface - implement-code - write-unit-test - update-doc --- 1. 执行 analyze-requirement 技能，理解需求并输出需求摘要。 2. 执行 design-interface 技能，设计接口并输出接口定义。 3. 执行 implement-code 技能，根据接口定义实现代码。 4. 执行 write-unit-test 技能，为新增代码生成测试。 5. 执行 update-doc 技能，更新相关文档。 6. 所有步骤完成后，输出变更摘要，等待用户确认。

工作流的价值在于，它把多个技能的执行顺序和依赖关系固化下来，你只需要说“开始新功能开发”，AI 就会按顺序执行所有技能。这比手动一个个调用技能效率高得多。

我实测下来，工作流最适合那些步骤固定、重复性高的开发任务。比如“修 bug”工作流、“发布新版本”工作流、“代码审查”工作流。对于探索性的任务，比如“调研某个技术方案”，工作流反而会限制 AI 的灵活性，这时候用单个技能或者纯对话更合适。

5. 常见问题与排查技巧实录

5.1 技能不触发或触发错误怎么办

这是最常见的问题。症状是：你输入了触发词，但 AI 没有加载对应的技能，或者加载了错误的技能。

排查思路分三步。第一步，检查triggers字段是否包含了你输入的关键词。注意大小写和单复数，有些框架对大小写敏感。第二步，检查技能文件的路径是否正确。技能必须放在框架能扫描到的目录下，通常是.skills/及其子目录。第三步，检查是否有同名技能覆盖。项目级技能会覆盖全局技能，如果你在项目级目录里放了一个同名但内容不同的技能，全局技能就不会生效。

我遇到过一次比较隐蔽的情况：技能文件里 YAML frontmatter 的格式有误，导致整个文件被跳过。YAML 对缩进和冒号后面的空格很敏感，建议用编辑器插件做语法检查。

5.2 技能执行结果不符合预期的调试方法

技能触发了，但执行结果不对。比如“写单元测试”技能生成的测试代码跑不起来，或者“重构代码”技能把接口改了。

调试方法是从后往前查。先看输出结果哪里不对，然后看执行步骤里哪一步可能导致这个结果，最后看上下文注入是否充分。大多数情况下，问题出在上下文不足或者执行步骤描述不够具体。

我自己的经验是，在技能定义里加一个“自检”步骤。比如“写单元测试”技能的最后一步是“运行测试，确认全部通过”。如果测试失败，AI 会分析原因并修正。这个自检步骤能拦截大部分低级错误。

另外，技能的描述要尽量具体，避免模糊词汇。比如“生成高质量的代码”这种描述，AI 不知道什么叫“高质量”。改成“生成符合 PEP 8 规范、包含类型注解、函数长度不超过 50 行的代码”，AI 就知道该怎么做了。

5.3 上下文窗口不足的优化策略

技能框架用久了，技能库会越来越大，上下文窗口不够用是迟早的事。症状是 AI 开始“忘记”之前的指令，或者执行到一半突然中断。

优化策略有几个。第一，把不常用的技能从自动加载改为手动加载。第二，精简技能定义，去掉冗余的描述和示例。第三，把大段的上下文信息（比如完整的项目结构）改成摘要形式。第四，使用框架提供的“上下文压缩”功能，如果支持的话。

我自己的做法是，每个技能的定义控制在 500 字以内，执行步骤不超过 7 步。超过这个规模，就考虑拆分成多个技能。另外，定期清理不再使用的技能，保持技能库的精简。

5.4 常见问题速查表

提示：这张表建议放在项目 README 里，团队新成员遇到问题时可以先自查，减少沟通成本。

5.5 几个我踩过的坑和对应的技巧

第一个坑：技能定义里的tools字段写得太少。我以为 AI 会自动使用所有可用工具，但实际上框架只会加载tools里列出的工具。有一次“写单元测试”技能需要运行测试，但我忘了在tools里加run_command，结果 AI 生成完测试代码就停了，没有运行验证。

第二个坑：护栏规则写得太模糊。我写过一条“不允许修改重要文件”，结果 AI 不知道哪些文件算“重要”，还是修改了config.py。后来改成“不允许修改config.py、settings.py、.env”，问题就解决了。

第三个坑：技能之间的依赖关系没有显式声明。工作流里如果技能 B 依赖技能 A 的输出，但你没有在技能 B 的定义里说明这一点，AI 可能会在技能 A 还没完成时就执行技能 B。解决办法是在工作流定义里明确指定执行顺序，并且在技能 B 的上下文注入里包含技能 A 的输出。

第四个坑：没有版本控制。技能定义也是代码，应该纳入 Git 管理。我一开始把技能文件放在.gitignore里，结果换电脑后所有技能都没了。后来把.skills/global/和.skills/project/纳入版本控制，.skills/local/保持忽略，这样就既能共享又能保留个人定制。

6. 技能框架的扩展方向与个人实践体会

6.1 从个人使用到团队协作的演进路径

一个人用技能框架和团队用，完全是两回事。个人使用时，你可以随意修改技能定义，不需要考虑兼容性。但团队使用时，技能定义就变成了“接口”，需要版本管理和变更评审。

我的建议是分三步走。第一步，个人先跑通一套技能，积累经验。第二步，把验证有效的技能提取出来，放到团队共享仓库里，加上版本号和变更日志。第三步，建立技能评审机制，任何技能定义的修改都需要至少一个人 review。

团队协作还有一个特殊问题：不同成员的开发环境可能不同。比如有人用 macOS，有人用 Ubuntu，有人用 Windows。技能定义里如果包含平台特定的命令，就会出问题。解决办法是在技能定义里用条件判断，或者把平台特定的部分抽成单独的技能。

6.2 技能库的维护与迭代节奏

技能库不是建好就完了，需要持续维护。我的做法是每个月做一次技能库回顾，检查哪些技能经常用、哪些从来没用过、哪些需要更新。经常用的技能，考虑优化执行步骤；从来没用过的技能，考虑删除；需要更新的技能，根据最近的踩坑经验补充护栏或调整步骤。

迭代节奏上，我建议小步快跑。不要一次性写一个完美的技能，而是先写一个能用的版本，然后在实际使用中不断调整。我自己的“写单元测试”技能改了七八版，才达到比较稳定的状态。每一版都是因为遇到了新的问题，比如测试框架识别错误、测试文件命名不规范、边界用例覆盖不全等。

6.3 我个人在实际操作中的几点体会

用了几个月下来，我最大的体会是：技能框架的价值不在于“让 AI 更聪明”，而在于“让 AI 更稳定”。AI 本身的能力已经很强了，但它有时候会“发挥不稳定”。技能框架通过固化流程和约束，把 AI 的输出稳定在一个可预期的范围内。这对于需要重复执行的任务来说，价值巨大。

第二个体会是：不要追求大而全的技能库。我一开始兴致勃勃地写了二十多个技能，结果常用的就五六个。技能太多反而会增加上下文负担，降低执行效率。现在我保持技能库在十个以内，每个都经过实际验证。

第三个体会是：护栏比技能本身更重要。一个没有护栏的技能，就像一辆没有刹车的车，跑得越快越危险。我现在的做法是，每写一个新技能，先想清楚“这个技能绝对不能做什么”，把护栏写好，再写执行步骤。

最后分享一个小技巧：如果你用的是 Claude Code，可以在项目根目录放一个CLAUDE.md文件，里面写项目的整体约定和常用命令。这个文件会在每次对话开始时自动加载，相当于一个“全局上下文”。把技能框架的说明也放进去，AI 就能更好地理解你的工作方式。Codex CLI 也有类似的机制，通常是AGENTS.md或.codex/instructions.md。这个文件不用写太长，几百字就够了，关键是信息密度要高。