企业官网建设流程全解析

最近不少朋友在群里问我同一个问题：AI 编程助手写代码这么猛，为什么一落到自己团队项目里就开始“胡来”？函数写得没问题，但目录乱放、import 顺序全凭心情、commit message 写得像密码、数据库查询也敢裸奔——代码能跑，可一看就不像“自己人”写的。

这事的根子不在于 Agent 不会写代码，而在于它不知道你们团队是怎么定义“好代码”的。通用模型训练的时候见过海量开源仓库，但没读过你们内部的规范文档。你光在 prompt 里加一句“按团队规范来”也没用，它根本不知道规范长什么样。所以我这段时间一直在做一件事：把项目里所有零散的约定，整理成一套 Agent 能读、能执行、能自检的 Skills，让“会写代码的 Agent”变成“会按你们规范干活的同事”。

这篇文章是我自己踩完坑之后的一份完整记录，包含 Skills 适配的思路、目录怎么组织、SKILL.md 怎么写、脚本怎么把规范变成硬检查，以及适配过程中常见的 5 个坑。适合正在用 Claude Code、Codex、Cursor 做实际项目，又被“代码风格不统一”和“规范落地难”折磨过的团队和个人。

1. 为什么 Agent 写代码总“失控”：先搞懂适配要解决什么问题

1.1 通用 Agent 的“三不知”

很多人第一次用 AI 编程助手写业务代码，感受都是“惊艳三分钟，然后开始血压升高”。惊艳的是它确实理解需求、能写完整模块；血压升高的是它写出来的代码，在你自己的项目里怎么看怎么别扭。

我总结了一下，通用 Agent 进到真实项目里至少有“三不知”：第一，不知道项目背景，它不知道你这是个微服务还是一个单体老项目，不知道历史包袱在哪里；第二，不知道潜规则，比如团队约定新页面必须放在src/pages下，组件文件统一用PascalCase命名，这些规则通常不在任何文档里，而是散落在老同事的脑子里；第三，不知道质量标准，它知道 Python 有 PEP8，但不一定知道你团队在 ESLint 之上还叠了一层 import 排序规则和禁止any的红线。

这三件事，恰恰是“能不能在团队里跑起来”的关键。

有人会说，那我每次在 prompt 里写清楚不就行了？我试过，效果很一般。一是 prompt 长度有限，把规范全贴进去不现实；二是每次开新会话都得重新讲一遍，讲多了自己都烦；三是人的表达和 Agent 的理解之间有损耗，你说“组织好代码结构”，它能给你列出十个“结构”的重构方案，但没有一个符合你们项目的现状。临时叮嘱只能救急，解决不了长期问题。

1.2 Skills 像什么：给新同事的入职手册

后来我换了个思路：不再试图靠“每句话都说清楚”来约束 Agent，而是把规范沉淀成一个它随时能查阅、能调用的资产。这就是 Skills 在做的事。

你可以把 Skills 理解成给新同事准备的入职手册。一个新同事入职，光会写代码是不够的，他还得知道你们的小组用什么分支策略、提交信息按什么格式写、代码评审重点看什么、哪些库是禁用的。这些东西你不可能在入职第一天全部用嘴讲完，更不可能靠他“悟”。但如果你递给他一本写得很好的手册，他遇到问题翻一翻，很快就能上手。

Skills 就是给 Agent 的“入职手册 + 工具包”。它的形态通常是一个带SKILL.md描述文件的目录，里面可以再放校验脚本、模板、参考代码。Agent 在遇到匹配任务的时候会自动加载这个描述文件，然后照着手册里定义的流程去干活。和 prompt 最大的区别在于，prompt 是一次性、即兴的口头交代，Skills 是可复用、可版本管理、可挂在项目仓库里的长期资产。

我自己的体会是：一旦把规范转成 Skills，你对 Agent 的信任感会明显不一样。因为它不再是“碰运气式地偶尔遵守规范”，而是每次开工前先读一遍手册，干完活还能自己跑一遍检查。这种稳定感，才是团队愿意长期用 Agent 的前提。

2. 适配前先盘点：项目里到底有哪些“隐性规范”值得做成 Skills

2.1 四类高频规范，优先级最高

做全项目 Skills 适配之前，我建议先别急着写文件，而是花半天时间盘点自己项目里到底有哪些规范。我做过几个不同技术栈的项目之后，发现绝大多数团队真正高频、强约束的规范，其实集中在四类。

为什么优先做这四类？因为它们有三个共同点：高频出现，几乎每天都会触发；规则明确，可以写成确定性的“如果……那么……”；可以脚本化检查，能够做成自动化校验的一部分。与之相对，那些低频的、需要业务判断的规则，比如“这个订单状态机应该怎么设计”“这个缓存失效策略合不合理”，就不太适合塞进 Skills，更适合留在设计文档里。

按这个标准筛一遍，你会发现真正值得做成 Skills 的规范可能只有十几条，而不是整个 Wiki。别贪多，先把最痛的地方解决。

2.2 别把整个 Wiki 塞进 Skills

我第一次做 Skills 的时候犯过一个典型错误：觉得既然是“知识资产”，那就把团队 Wiki 里所有相关的页面都复制进去，越全越好。结果反馈非常糟糕——Agent 加载这个技能之后思考变慢了，输出也更啰嗦，甚至在检查代码的时候反复引用一些已经过时的架构说明。

后来我才想明白：Skills 不是知识库，它是“操作手册”。知识库是给 Agent 按需检索的，操作手册是让它照着执行的。你把一本几千行的 Wiki 塞进操作手册，Agent 反而不知道哪条规则是当前必须遵守的。

我现在判断一个规范适不适合做成 Skills，只看两个标准。第一，一段规则能不能在一分钟内读完并转化为行动？如果读一段规则要花五分钟，说明它拆得不够小，得拆开。第二，能不能用脚本自动校验？如果一个规则“线性可分”，比如命名规范、目录位置、import 顺序，那就尽量做成脚本，让 Agent 在生成代码后自己跑检测。如果规则机械判断不了，比如“这里是否应该加缓存”，那就不要写进技能，让它去问人。

这里分享一个很实用的原则：简单判断交给 Agent，机械校验交给脚本。规范的最终闭环是“自动化”，而不是“靠 Agent 自觉”。否则换个模型、换次对话，效果就打回原形。

3. 实操手记：将“会写代码的 Agent”改造成“按规范干活的同事”

3.1 目录放哪里、怎么命名、怎么触发

前人把路已经蹚得差不多了，现在主流 AI 编程助手对“技能”类目录的约定基本趋同，只是在细节上有差异。以我熟悉的 Claude Code 为例，个人级技能放在~/.claude/skills/<skill-name>/，项目级技能放在项目根目录下的.claude/skills/<skill-name>/；Codex 习惯用AGENTS.md写全局规则，Cursor 用.cursor/rules。好消息是，越来越多的工具开始支持跨格式读取，所以只要一个目录下有SKILL.md，很多场景都能通用。

我的建议是：个人习惯放用户目录，团队规范放项目目录。因为项目级技能跟着仓库走，新同事 clone 下来就自带规范，不用再做任何环境配置。你可能会问，规范散在每个项目里岂不是很乱？我在 3.4 节会讲用一个中心仓库统一维护的办法。

关于命名，最佳实践是“动词 + 对象”，让人一眼看清楚这个技能是干什么的。比如check-frontend-standards、review-db-migration、write-conventional-commit，都比frontend、db、commit这种模糊命名好得多。更重要的是SKILL.md头部的description和when_to_use字段，这两个字段决定了 Agent 什么时候会自动加载它——如果写不清楚，技能就是“存在但永远不生效”。

3.2 写 SKILL.md：不写“认真对待”，要写“什么不能做、应该怎么做”

我见过不少团队写的技能描述文件，内容通篇是“请认真遵循团队规范”“确保代码高质量”，看了等于没看。Agent 需要的是可执行的步骤，不是态度。我以一个前端工程规范检查技能为例，给你看看一份能落地的SKILL.md长什么样：

--- name: frontend-standards-check description: 检查前端代码是否违反团队工程规范。适用于新增/修改页面、组件、路由，以及用户要求“按规范生成”或“码上评审”时。 when_to_use: 新增组件、页面，提交代码评审前，或用户主动要求检查规范时。 version: 1.2.0 --- # 前端工程规范检查 ## 工作流程 1. 定位所有本次改动的 JS/TS/Vue/JSX/TSX 文件； 2. 检查项目根目录是否存在 `package.json` 和 `eslint.config.js`，据此判断规则链路； 3. 对每个改动文件逐项检查以下规则： - 组件文件命名必须为 `PascalCase.vue` 或 `PascalCase.tsx`，禁止使用 `index.vue` 以外的短横线命名； - 页面文件统一放在 `src/pages` 下，禁止放入 `src/components`； - `import` 顺序必须为：Node 内置模块 -> 外部依赖 -> 项目内部 `@/` 别名 -> 相对路径； - 组件内禁止直接调用 `fetch`，统一走 `src/utils/request` 封装； 4. 输出检查报告，内容包含：违规文件路径、违规类型、修改建议； 5. 修复后建议运行 `npm run lint` 确保无新告警。

这份文件的价值在于，每一步都是 Agent 可以直接执行的。你注意一下第 3 条，我写的不是“注意 import 顺序”，而是写清楚了顺序的四个分组，并且给出了判定标准。Agent 不需要猜，它只需要拿着每一行代码去对照规则。

还有一个经验是：正文尽量用检查清单，不要用叙事长文。清单格式方便 Agent 逐条执行，也方便你后期维护。每一条规则都尽量配一个“好的写法”和“坏的写法”，示例比形容词更可靠。如果某条规则比较复杂，比如“路由权限怎么配置”，不要写在 SKILL.md 里，把它链接到 docs 文档，让 Agent 有需要时点进去看。

3.3 用脚本把规范变成“硬检查”

文案规则写得再好，也不能保证 Agent 每次都严格遵守，因为它本质上还是概率模型。所以我的方案是：把能机械判断的规则全部写成脚本，放进 Skills 目录，让 Agent 在干完活之后自己跑一遍脚本，有问题自己改。这比靠“提示词约束”要可靠得多。

举个例子，我写过一个检查 import 顺序的 Node 脚本，核心逻辑非常简单：

/** * 简单 import 顺序检查脚本 * 规则：外部依赖(1) -> @/ 别名(2) -> 相对路径(3) */ const fs = require('fs'); const path = require('path'); function checkFile(filePath) { const content = fs.readFileSync(filePath, 'utf8'); const lines = content.split('\n').filter((l) => l.trim().startsWith('import ') ); let lastGroup = 0; const errors = []; for (const line of lines) { const src = line.match(/from\s+['"]([^'"]+)['"]/)?.[1] || ''; let group; if (src.startsWith('@/')) { group = 2; } else if (src.startsWith('.')) { group = 3; } else { group = 1; } if (group < lastGroup) { errors.push(`import 顺序错误: ${line.trim()} （期望分组 >= ${lastGroup}，实际分组 ${group}）`); } lastGroup = group; } return errors; } const files = process.argv.slice(2); let allErrors = []; for (const f of files) { allErrors = allErrors.concat(checkFile(f)); } if (allErrors.length > 0) { console.error(allErrors.join('\n')); process.exit(1); } console.log('✓ import 顺序检查通过');

这个脚本没用什么花哨的语法，但在实际工作流里非常好用。我把它放在~/.claude/skills/frontend-standards-check/scripts/check-import-order.js，然后在SKILL.md的末尾加了一段“工具说明”，告诉 Agent 检查完代码之后运行下面这条命令：

node .claude/skills/frontend-standards-check/scripts/check-import-order.js <改动的文件路径>

这样 Agent 就不再是“凭感觉遵守规范”，而是有了一个机械性的验收环节。跑不过就改，改到通过为止。这个“自我纠错”的循环一旦跑起来，它产出的代码在格式层面和团队老手写的几乎没什么区别。

同样的思路还可以覆盖很多场景：检查组件是否放在正确目录、检查是否包含明文密钥、检查 commit message 格式、检查是否误提交了console.log。每一条可以机械判断的规则，都值得写成一个小脚本。注意脚本的输出要清晰，最好就是“文件名 + 问题行 + 期望行为”，这样 Agent 拿着输出就能直接修。

3.4 把 Skills 接入日常工作流的三种姿势

Skills 做出来不是摆着看的，要真正发挥价值，得接入团队现有的工作流。我目前用得最顺的三个场景，可以给你参考。

第一个场景是提交信息规范化。以前我们团队提交代码，commit message 风格全靠个人发挥，有人写fix bug，有人写更新了登录逻辑，等要出 changelog 的时候就是一场灾难。现在我把 Conventional Commits 规范做成了一个技能，让 Agent 自己读git diff，然后按规范生成提交信息。它会先看改动涉及什么类型、有没有破坏性变更、影响范围是什么，然后输出符合规范的提交信息，我用工具一确认就提交，Revise 的时间几乎为零。

第二个场景是 Code Review 辅助。Review 是高度消耗精力的活，但如果提醒太泛，Agent 容易变成一个“无情的告警器”。我把团队最关心的五类红线做成一个 review 技能，明确告诉它“只看这五类问题，不要掉进代码风格细节里”，重点看安全敏感信息、数据库操作、权限校验、异常处理和性能隐患。这样它快速扫完改动后给我一份精炼的审查意见，我再在上面做业务判断，效率提升非常大。

第三个场景是新项目初始化。我们在用脚手架创建新项目的时候，经常漏掉一些基础配置：目录结构建了但不完整，pre-commit 钩子忘了装，Lint 规则没有引入。我索性把这个初始化过程也做成了技能，Agent 在初始化完成后会自动检查目录结构、依赖配置、hooks 是否注册，缺什么补什么。这相当于把“新项目体检”变成了标准动作，而不是靠某个人的记忆力。

4. 适配过程中的 5 个坑与排查方法

4.1 坑一：规范写得像公司制度，Agent 完全无感

症状是：你辛辛苦苦写了一份技能，但 Agent 的行为没有任何变化，该乱放目录还是乱放。我排查这类问题，第一步永远是看它到底有没有在正确时机加载技能。很多工具可以查看当前会话加载了哪些技能，比如输入对应的查看命令或直接检查日志。如果没有加载，多半是description或when_to_use写得不够精准，Agent 不知道“这个任务和这个技能有关系”。

另一个常见原因是，正文写得像公司制度而不是操作手册。你写“请保持代码整洁”，Agent 只会一脸茫然。我修复这类问题的办法是：把每一条规则改成“如果看到 X，就改成 Y”的句式，并且附带正反例。比如，“如果看到const a: any = ...，改为显式定义类型；示例：不要写let data: any，改为interface Data { id: string; name: string }”。只有这种颗粒度，Agent 才知道你要什么。

4.2 坑二：技能越塞越大，Agent 反而变笨

做适配最忌讳“大而全”。我见过有人把一个团队的完整开发规范做成了一个 800 行的技能文件，最后 Agent 每次执行任务都要加载几千 token，思考速度明显变慢，而且经常在规则之间“精神内耗”，明明是一个很简单的修改任务，它会花很长时间去逐条对规范。

这个问题我建议这么解决：把技能按触发场景拆小。目录结构上做分层，比如.claude/skills/frontend/只服务前端文件，.claude/skills/database/只在有 SQL 或 migration 文件改动时触发。如果一段规范超过一屏（大约 80 行），就先拆出来单独做成一个小技能。拆完之后你会发现，Agent 加载的是经过裁剪的、贴合当前任务的规则，响应质量和速度都会有明显改善。

4.3 坑三：技能更新了，Agent 还在用旧规范

这个坑特别隐蔽。团队规范不是一成不变的，比如这个月决定把路由模式从 history 改成 hash，或者升级了组件库之后要统一换新的导入路径。你更新了 SKILL.md，但 Agent 的新会话可能还在用缓存的定义，或者上一次会话的上下文覆盖面太广，导致它记得旧规则，用了新会话也没太注意。

我的做法很简单：第一，在SKILL.md的 frontmatter 里加一个version字段，每次更新规范就 bump 版本号，这样至少能追溯；第二，重要规范变更后，我会重新开一个新会话再让 Agent 干活，避免它在旧会话里带着错误的上下文继续执行；第三，如果发现 Agent 明显在用旧行为，我会检查工具是否有缓存目录，清理掉之后再试。另外，我维护了一个skills:sync脚本，能把主仓库里更新过的技能文件自动同步到各个项目目录，避免出现“一个项目是旧规范，另一个项目是新规范”的混乱。

4.4 坑四：换了工具，技能不能直接用

这个坑在团队协作里尤其明显。团队里有人用 Claude Code，有人用 Codex，有人用 Cursor。我在 Claude Code 里写好的一套技能，换到其他工具上，经常因为目录约定不一致或格式字段不兼容就失效了。如果每个工具维护一份规范，那维护成本会指数级上升，最后必然导致规范不一致。

我现在的做法是：在一个中心仓库里维护规范源文件，然后写一个构建脚本，自动生成各个工具需要的格式，包括.claude/skills/、.cursor/rules/、AGENTS.md等。这样团队只需要维护一套规范源，代码生成一次，所有工具都能吃到最新内容。虽然各家格式还不完全统一，但基础的 markdown + 脚本形式已经足够通用，社区也在朝开放格式的方向走，这个投入是值得的。

4.5 坑五：把技能验证当最终保障，评审被架空了

最后一个坑，也是我在团队里反复强调的：技能和脚本能挡住低级问题，但挡不住业务问题。import 顺序、commit message、敏感信息扫描，这些是“硬规则”，适合自动化；但一个 SQL 查询有没有走对索引、一个并发场景有没有考虑竞态条件、一个交互设计是否真的符合用户预期，这些是“软判断”，必须靠人。

我踩过一次教训：刚开始推 Skills 的时候，大家太依赖自动检查的结果，看到“✓ 检查通过”就直接合代码，结果跑出几个性能问题。后来我在技能的结尾加了一条兜底规则：如果发现需求本身存在歧义，或者改动会涉及到你无法判断的业务风险，先停下来问，不要自己编一个方案继续做。这一条在实践里极有价值，它让 Agent 在关键时刻愿意“暴露无知”，而不是硬着头皮把错误方案推进下去。

最后分享一点我自己的经验

做完全项目 Skills 适配之后，我最大的变化是：不再把 Agent 当“会写代码的工具”，而是当“刚开始带的新人”。新人刚来的时候，你给他一本入职手册，他干活你会有安全感；但手册写得不清楚，他出了问题你也不能全怪他。Skills 适配的本质，就是把规范整理成人能读、机器能执行的语言。

如果你也想在自己的项目里试，我的建议是从最小闭环开始：挑一个最让你头疼的规范，比如 commit message 或者页面目录，做成一个脚本 + 一份 SKILL.md，跑一个周期，看效果再决定要不要扩大范围。不要一上来就搞大而全的“工程规范全家桶”，那样维护压力会立刻盖过收益。规范这件事，永远是先把响应速度做起来，再慢慢完善深度。