最近不少朋友在群里问我同一个问题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. 适配前先盘点项目里到底有哪些“隐性规范”值得做成 Skills2.1 四类高频规范优先级最高做全项目 Skills 适配之前我建议先别急着写文件而是花半天时间盘点自己项目里到底有哪些规范。我做过几个不同技术栈的项目之后发现绝大多数团队真正高频、强约束的规范其实集中在四类。规范类型包含内容典型示例工程约定代码风格、Lint 规则、目录结构、组件命名组件文件用 PascalCase页面放src/pages下架构约束分层方向、依赖关系、禁止循环引用业务逻辑禁止直接写在组件里禁止services反向依赖pages协作规范提交信息、分支命名、MR/PR 描述、Code Review 重点commit 使用 Conventional Commits分支名带需求单号安全红线敏感信息、日志脱敏、数据库操作、鉴权逻辑禁止明文 token禁止连表后不带索引条件禁止把console.log提交到主分支为什么优先做这四类因为它们有三个共同点高频出现几乎每天都会触发规则明确可以写成确定性的“如果……那么……”可以脚本化检查能够做成自动化校验的一部分。与之相对那些低频的、需要业务判断的规则比如“这个订单状态机应该怎么设计”“这个缓存失效策略合不合理”就不太适合塞进 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跑一个周期看效果再决定要不要扩大范围。不要一上来就搞大而全的“工程规范全家桶”那样维护压力会立刻盖过收益。规范这件事永远是先把响应速度做起来再慢慢完善深度。