企业官网建设流程全解析

1. 从“superpowers”说起：这套技能框架到底在解决什么问题

第一次看到“superpowers”这个词，很多人会以为是某个超级英雄题材的游戏或者插件合集。但如果你最近在折腾 Claude Code、Codex CLI 这类终端里的 AI 编程助手，大概率已经在各种社区里刷到过它。简单来说，superpowers 是一套面向 AI 编程代理的技能框架（agentic skills framework），也是一套围绕它建立起来的软件开发方法论。它要解决的核心痛点非常具体：AI 编程助手本身很聪明，但每次对话都是“失忆”的，你不告诉它你的项目规范、代码风格、目录结构、测试习惯，它就会按自己的默认套路来，写出来的东西能跑，但跟你的工程体系格格不入。

superpowers 的思路是把这些“你希望 AI 一直记住并且一直遵守的东西”抽出来，做成一个个可复用的技能模块，然后在 Claude Code、Codex CLI 这类工具里按需加载。你可以把它理解成给 AI 助手装了一套“职业培训手册加操作规范”：什么场景该调用什么技能、写代码前先看哪些约束、提交前跑哪些检查，全都固化下来。它不是一个具体的库，也不是某个语言的 SDK，而是一层方法论加配置体系，落在你的项目目录里，跟着代码一起走。

这套东西适合谁？三类人最值得花时间研究。第一类是已经在用 Claude Code 或 Codex CLI 做日常开发，但总觉得 AI 输出“差那么点意思”的工程师；第二类是想把 AI 编程引入团队、但苦于无法统一输出质量的 Tech Lead；第三类是刚接触 agentic 工具、想找一套现成规范照着抄的新手。它不要求你会写复杂的提示词工程，也不要求你懂模型微调，核心工作就是整理你的工程知识，然后按框架约定组织起来。

我自己的体会是，superpowers 真正的价值不在于“让 AI 变强”，而在于“让 AI 变稳”。模型能力是外部变量，你控制不了；但技能框架是你自己的资产，写一次就能反复用，换模型、换工具、换项目都能迁移。下面我会从设计思路、核心细节、实操落地、问题排查几个层面，把我在实际项目里踩过的路完整讲一遍。

2. 整体设计与思路拆解：为什么是“技能”而不是“提示词”

2.1 技能框架和普通提示词的本质区别

很多人第一反应是：这不就是写一段 system prompt 吗？我直接把规范塞进对话开头不就行了。短期看确实能凑合，但一旦项目变大、场景变多，问题就暴露了。普通提示词是“一次性”的，它跟着某一次对话走，对话结束就没了；而 superpowers 里的技能是“持久化”的，它以文件形式存在项目里，可以被版本控制、被复用、被组合。这是第一个本质区别：提示词是会话级的，技能是项目级的。

第二个区别在于组织方式。一段长提示词是线性的，所有规则堆在一起，AI 读的时候没有优先级，容易顾此失彼。而技能框架是模块化的，每个技能负责一个明确的领域，比如“代码风格”“测试规范”“提交信息格式”“依赖管理”。AI 在具体任务里只加载相关技能，注意力更集中，输出质量自然更稳定。这就像你给新员工培训，不会把公司所有制度一次性念完，而是按岗位、按场景分批给资料。

第三个区别是可验证性。技能文件是纯文本，你可以 review、可以 diff、可以写测试去校验它有没有被正确引用。提示词藏在对话历史里，改了什么、什么时候改的，根本追溯不了。对于团队协作来说，这一点是决定性的。

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

superpowers 之所以和 Claude Code、Codex CLI 绑定得这么紧，是因为这两类工具都支持在项目目录里读取本地文件作为上下文。Claude Code 有 CLAUDE.md 这类约定文件，Codex CLI 也有自己的配置读取机制，它们都允许你把项目级的指令放在仓库里，而不是每次手动粘贴。这就给技能框架提供了落地的土壤。

选这两个工具还有一层现实考虑：它们都是终端优先的，工作流天然贴近真实开发。你在终端里敲命令、跑测试、看 diff，AI 助手就在同一个环境里，能直接读文件、执行命令、看输出。技能框架里的很多规则，比如“改完代码必须跑 lint”“提交前检查测试覆盖”，在这种环境下是可以被真正执行的，而不是停留在纸面上。相比之下，纯聊天窗口里的 AI 助手，你让它“记得跑测试”，它只能口头答应，实际做不做全看运气。

提示：如果你还没装 Claude Code 或 Codex CLI，建议先把基础工具跑通，再上技能框架。工具本身没跑顺，框架只会放大混乱。

2.3 框架的分层结构：从“总纲”到“具体技能”

我在实际项目里把 superpowers 的组织分成三层。最上面是总纲层，通常是一个入口文件，比如 CLAUDE.md 或者项目根目录的说明文件，里面写清楚这个项目是干什么的、技术栈是什么、有哪些全局约束。这一层不涉及具体操作，只给 AI 建立“世界观”。

中间是技能层，每个技能一个文件或一个目录，比如skills/code-style.md、skills/testing.md、skills/git-workflow.md。每个技能内部结构尽量统一：先说明这个技能解决什么问题，再列出具体规则，最后给正反例。统一结构的好处是 AI 读起来有预期，你维护起来也方便。

最下面是场景层，也就是把技能和具体任务绑定。比如“新增一个 API 接口”这个场景，需要加载 code-style、testing、api-convention 三个技能；“修一个 bug”这个场景，需要加载 debugging、testing 两个技能。场景层可以是一个简单的映射表，也可以是一段说明文字，告诉 AI 在什么情况下该看哪些技能。

这种分层的好处是解耦。技能本身不关心什么时候被用，场景只负责编排，总纲只负责定调。任何一层要改，都不会牵一发动全身。我见过有人把所有规则塞进一个巨大文件，结果改一行要通读全文，维护成本极高，最后就没人愿意改了。

3. 核心细节解析与实操要点：技能文件到底怎么写

3.1 一个合格技能文件的四段式结构

写技能文件最容易犯的错是写成“愿望清单”——“代码要整洁”“命名要规范”“测试要覆盖”。这种话 AI 看了等于没看，因为它不知道你的“整洁”和“规范”具体指什么。我总结下来，一个能真正生效的技能文件应该包含四段：适用场景、硬性规则、正例、反例。

适用场景放在最前面，用一两句话说明这个技能在什么时候生效。比如“当你需要新增或修改任何 Python 文件时，遵循以下规则”。这句话的作用是给 AI 一个触发条件，避免它在无关任务里乱套规则。

硬性规则是核心，必须具体到可执行。不要说“函数要短”，要说“单个函数不超过 40 行，超过就拆分”。不要说“命名要清晰”，要说“变量用 snake_case，类用 PascalCase，常量全大写”。规则越具体，AI 执行越稳定。我一般会把规则控制在 5 到 10 条，太多 AI 记不住，太少覆盖不全。

正例和反例各给一到两个代码片段。正例展示“这样做是对的”，反例展示“这样做是错的，因为……”。反例特别重要，因为 AI 对“不要做什么”的理解往往比“要做什么”更模糊，给它一个具体的错误样本，它能更快对齐你的预期。

3.2 规则的具体化程度：一个对比案例

我拿“错误处理”这个技能举例，展示一下模糊规则和具体规则的区别。

模糊版本是这样的：代码要有良好的错误处理，不要吞掉异常，要给出有意义的错误信息。这段话读起来没毛病，但 AI 拿到之后基本会自由发挥，有人写 try-catch 包一切，有人直接抛原始异常，风格完全不统一。

具体版本我会这么写：所有外部调用（网络、文件、数据库）必须包裹 try-catch；catch 块里必须记录日志，日志包含操作名和关键参数；禁止使用裸的except: pass；对外抛出的异常必须是项目自定义的AppError子类，并附带 error code。这样 AI 就知道边界在哪，输出会稳定得多。

再进一步，我会在正例里给一段标准写法，在反例里给一段“吞异常”的写法并标注问题所在。实测下来，加了正反例之后，AI 在错误处理上的输出一致性提升非常明显，基本不需要我再手动改。

3.3 技能之间的依赖和引用怎么处理

项目大了之后，技能之间会有依赖。比如 testing 技能可能依赖 code-style 技能里定义的命名规范，git-workflow 技能可能依赖 testing 技能里定义的测试命令。如果每个技能都自包含，会有大量重复；如果互相引用，又容易形成循环。

我的做法是设一个基础技能层，把最通用的规则放进去，比如命名规范、目录结构、日志格式。其他技能可以引用基础层，但基础层不引用任何其他技能。引用方式很简单，在技能文件里写一句“本技能继承 base-convention 的命名规则”，不需要复杂的机制。AI 读到这句话会自己去加载基础技能，效果和显式 import 差不多。

注意：引用层级不要超过两层。基础层到具体技能一层就够了，再深下去 AI 容易迷路，维护的人也容易搞混。

3.4 技能文件的存放位置和命名约定

存放位置直接影响 AI 能不能找到。Claude Code 默认会读项目根目录的 CLAUDE.md，所以我会在 CLAUDE.md 里写清楚技能目录在哪，比如“所有技能文件位于.ai/skills/目录下”。Codex CLI 类似，需要在它的配置里指定读取路径。

命名上我建议用“领域-动作”的格式，比如code-style.md、test-writing.md、git-commit.md。不要用中文文件名，虽然技术上可行，但在不同系统间同步容易出编码问题。也不要用太泛的名字，比如rules.md、misc.md，时间一长你自己都忘了里面写的什么。

目录结构我一般是这样：

.ai/ skills/ base-convention.md code-style.md testing.md git-workflow.md api-convention.md scenarios/ new-feature.md bug-fix.md refactor.md

.ai目录放在项目根目录，跟.github、.vscode平级，语义清晰，也不会污染源码目录。

4. 实操过程与核心环节实现：从零搭起一套可用的技能框架

4.1 环境准备：Claude Code 与 Codex CLI 的基础配置

在动手写技能之前，先把工具跑通。Claude Code 的安装方式根据系统不同有差异，Ubuntu 下一般是通过包管理器或者官方提供的安装脚本，Windows 下建议用 WSL 环境，避免路径和权限的坑。安装完之后，在项目根目录运行一次，确认它能正常读取文件、执行命令。如果遇到“unable to locate the codex cli binary or required runtime components”这类提示，通常是运行环境没装全，检查一下 Node 运行时和相关依赖是否到位。

Codex CLI 的安装类似，Windows 下同样推荐 WSL。装完之后用codex --version确认版本，然后在项目里跑一个简单任务，比如“读一下 README 并总结”，看它能不能正常访问文件。这一步不要跳过，工具本身有问题，后面技能框架写得再好也白搭。

VSCode 里配置 Claude Code 的话，主要是确保终端环境和插件环境一致，避免出现“终端里能用、插件里报错”的情况。我一般会先在终端里把所有流程跑通，再考虑插件集成。

4.2 第一步：写总纲文件，给 AI 建立项目世界观

总纲文件是整个框架的入口，我通常放在项目根目录，命名成CLAUDE.md或者AGENTS.md。内容不需要长，但要把关键信息说清楚。我的模板大概是这样：

# 项目总纲 ## 项目简介 这是一个基于 Python 的后端服务，负责订单处理，对外提供 REST API。 ## 技术栈 - 语言：Python 3.11 - 框架：FastAPI - 数据库：PostgreSQL - 测试：pytest ## 全局约束 - 所有代码必须通过 ruff 检查 - 提交前必须跑通 pytest - 技能文件位于 .ai/skills/ 目录 - 场景文件位于 .ai/scenarios/ 目录 ## 工作流程 1. 接到任务先读相关场景文件 2. 按场景加载对应技能 3. 改完代码跑 lint 和测试 4. 提交信息遵循 git-workflow 技能

这个文件的作用是让 AI 一进项目就知道“我在哪、我要遵守什么”。实测下来，有了总纲之后，AI 在后续对话里跑偏的概率明显降低。

4.3 第二步：抽取你的第一条技能，从代码风格开始

第一条技能建议从代码风格入手，因为它最通用、最容易验证。我以 Python 项目为例，写一个code-style.md：

# 代码风格技能 ## 适用场景 新增或修改任何 Python 文件时生效。 ## 硬性规则 1. 缩进用 4 空格，禁止 Tab 2. 行宽不超过 100 字符 3. 函数名和变量名用 snake_case 4. 类名用 PascalCase 5. 常量全大写，单词间下划线分隔 6. 单个函数不超过 40 行 7. 导入顺序：标准库、第三方库、本地模块，三组之间空一行 8. 禁止使用通配符导入（from x import *） ## 正例 ```python import os from typing import Optional from fastapi import FastAPI from app.models import Order MAX_RETRY_COUNT = 3 def calculate_total_price(order: Order) -> float: ...

反例

from app.models import * # 禁止通配符导入 def CalcTotal(Order): # 命名不符合规范 ...

写完这条技能后，在总纲里引用它，然后跑一个真实任务测试。比如让 AI 新增一个函数，看它是否遵守了命名和行宽规则。如果没遵守，说明规则写得还不够具体，回去补细节。 ### 4.4 第三步：建立场景映射，让技能按需加载 技能写好了，接下来要解决“什么时候用哪个技能”的问题。我在 `.ai/scenarios/` 下建几个常见场景文件。以“新增功能”为例： ```markdown # 场景：新增功能 ## 触发条件 用户要求新增一个 API 接口、一个业务函数或一个模块。 ## 加载技能 1. code-style（必选） 2. testing（必选） 3. api-convention（如果涉及 API） ## 执行步骤 1. 先读现有代码，理解项目结构 2. 按 code-style 写实现 3. 按 testing 写单元测试 4. 跑 lint 和测试 5. 按 git-workflow 提交

场景文件不需要复杂，关键是让 AI 知道“这个任务该看哪些资料、按什么顺序做”。我一般会建四到五个场景：新增功能、修 bug、重构、写文档、依赖升级。覆盖日常开发八成以上的情况。

4.5 第四步：参数与规则的量化，让约束可执行

很多规则之所以失效，是因为没有量化。我在实操里会把能数字化的全部数字化。比如测试覆盖率，不写“要有足够测试”，写“核心模块覆盖率不低于 80%，工具模块不低于 60%”。比如提交信息，不写“写清楚”，写“格式为 type(scope): description，type 限定为 feat/fix/refactor/docs/test/chore”。

量化的好处是可验证。AI 写完代码，你可以让它自己对照规则检查一遍，不符合就改。我甚至会在技能里加一段“自检清单”，让 AI 在提交前逐条核对。实测下来，加了自检清单之后，返工率下降很明显。

提示：量化规则不要一次定太死，先定一个宽松版本，跑一段时间再收紧。一上来就要求 90% 覆盖率，AI 和你都会崩溃。

4.6 第五步：把技能框架纳入版本控制

技能文件是项目资产，必须进 Git。我会把.ai/目录完整提交，并且在 PR 模板里加一条“如果修改了技能文件，请说明原因”。这样技能框架的演进就有迹可循，新人入职也能通过读技能文件快速理解项目规范。

另外，技能文件的修改建议单独提交，不要和业务代码混在一起。混在一起的话，review 的人容易忽略技能变更，时间一长就没人知道规则什么时候改的、为什么改。

5. 常见问题与排查技巧实录：我踩过的那些坑

5.1 技能写了但 AI 不遵守，怎么排查

这是最常见的问题。排查思路分三步。第一步，确认技能文件真的被加载了。可以在对话里直接问 AI“你现在加载了哪些技能文件”，看它的回答是否包含你写的文件。如果没加载，检查总纲里的路径配置对不对，文件名有没有拼错。

第二步，确认规则是否具体。如果 AI 加载了但没遵守，大概率是规则太模糊。把规则改写成可执行的形式，加上正反例，再测一次。我遇到过“日志要详细”这种规则，AI 完全自由发挥，改成“日志必须包含 request_id、user_id、操作名三个字段”之后，立刻就稳定了。

第三步，确认规则之间没有冲突。如果两个技能对同一件事有不同要求，AI 会随机选一个。比如 code-style 说函数不超过 40 行，另一个技能说复杂逻辑可以放宽到 60 行，AI 就懵了。解决办法是设一个优先级，或者在总纲里明确“冲突时以 code-style 为准”。

5.2 技能文件越写越多，怎么控制规模

我一开始也犯过这个错，什么都想写进技能，最后搞了二十多个文件，AI 加载慢，我自己也维护不动。后来我定了一个原则：只写那些“AI 默认做不对、且反复出现”的规则。一次性的事情不写，AI 本来就能做对的事情不写，只写那些你每次都要手动纠正的点。

按这个原则筛下来，真正必要的技能通常不超过八个。剩下的可以合并或者删掉。技能框架的价值在于精，不在于多。

5.3 换模型或换工具之后，技能框架还能用吗

能用，但要做适配。技能文件本身是纯文本，跟模型无关，换模型不影响。但不同工具读取技能的方式不一样，Claude Code 读 CLAUDE.md，Codex CLI 有自己的配置入口，换工具的时候需要在总纲里调整路径说明。

我的做法是把技能内容本身和工具配置分离。技能文件放在.ai/skills/，工具相关的配置放在各自的入口文件里，入口文件只负责“告诉工具去哪读技能”。这样换工具的时候，只需要改入口文件，技能内容一行都不用动。

5.4 常见问题速查表

5.5 几个容易被忽略的细节

第一个细节是技能文件的编码。统一用 UTF-8，不要用系统默认编码，否则在不同机器上可能乱码。第二个细节是换行符，Windows 和 Linux 混用的时候容易出问题，建议在项目里配.gitattributes统一成 LF。第三个细节是技能文件的更新频率，我一般一个月 review 一次，把过时的规则删掉，把新踩的坑补进去。

还有一个坑是“技能膨胀”。有人觉得技能越多越专业，其实相反。技能多了之后，AI 的注意力被分散，反而容易漏掉关键规则。我现在的做法是每个技能不超过 10 条规则，超过就拆成两个技能，但总数控制在八个以内。

注意：技能框架不是写完就完事的，它需要跟着项目一起演进。项目变了，技能不变，框架就会变成负担。

6. 技能框架的扩展玩法：从个人到团队

6.1 个人项目里的轻量用法

如果你只是自己写点小项目，不需要搞太复杂。一个总纲文件加两三个技能就够了。我自己的 side project 就只有一个CLAUDE.md，里面写了技术栈、代码风格、测试要求三块，跑起来完全够用。关键是养成习惯：每次发现 AI 犯同样的错，就把它补进技能文件，而不是每次手动纠正。

这种“边用边补”的方式，比一开始就设计一套完美框架要实际得多。框架是长出来的，不是设计出来的。

6.2 团队协作里的技能治理

团队用的话，技能文件就成了协作规范的一部分。我建议指定一个人负责维护，其他人提 PR 修改。修改的时候要写清楚“为什么改”，因为技能规则背后往往有具体的踩坑经历，不写清楚的话，后人容易误删。

另外，团队里最好定期同步一次技能变更，比如在周会上花五分钟过一下这周改了什么规则。不然规则悄悄变了，大家的 AI 输出风格也跟着变，但没人知道为什么。

6.3 技能框架和 CI 的结合

技能框架里的很多规则，其实可以在 CI 里强制执行。比如代码风格用 ruff 检查，测试覆盖率用 pytest-cov 检查，提交信息用 commitlint 检查。这样 AI 写的东西在提交前就被机器卡一道，比靠 AI 自觉要可靠得多。

我的做法是技能文件里写规则，CI 里配对应的检查工具，两边保持一致。AI 在本地跑的时候按技能规则来，提交到 CI 再被机器验一遍。双保险下来，输出质量非常稳定。

6.4 后续可以扩展的方向

技能框架跑顺之后，可以往几个方向扩展。一是把技能和具体工具链绑定，比如技能里直接写“用 ruff 格式化”“用 pytest 跑测试”，让 AI 直接调用命令。二是做技能模板库，把通用技能抽出来，新项目直接复制。三是把技能和代码审查结合，让 AI 在 review 的时候按技能规则逐条检查。

这些扩展都不需要改框架本身，只是在现有结构上加东西。这也是分层设计的好处：核心稳定，外围灵活。

我个人在实际操作中的体会是，superpowers 这类技能框架最大的价值，是把你脑子里那些“默认的工程常识”显性化。以前这些常识只存在于老员工的习惯里，新人来了靠口口相传；现在它们变成了文件，AI 能读，新人能看，团队能 review。这件事本身比“让 AI 写代码更快”要有意义得多。最后再分享一个小技巧：每次 AI 输出让你不满意的时候，别急着改代码，先想想“这条规则我写进技能了吗”。写进去了，下次就不会再犯；没写，那就补上。坚持一个月，你会发现需要手动纠正的次数越来越少。