这半年我一直在观察团队里最明显的一个变化AI编程Agent用起来之后需求开发速度确实上来了但代码仓库的“熵增”速度也肉眼可见地加快了。PR描述写得天花乱坠实际上测试缺失、注释乱写、分支命名随意甚至连构建流程都敢顺手改掉。代码是AI写的但锅最终还得人来背。问题不在Agent写不出代码而在于它从来没有真正理解“这个项目是怎么协作的”。GitHub Skills系统这个原本给人类做交互式培训的老朋友最近被我重新翻了出来换了一条用法不再只给开发者上课而是把它当成给AI编程Agent立规矩、注入工程纪律的一套结构化机制。这篇文章就聊聊我是怎么把这件事落地的踩了哪些坑以及什么样的工程纪律能真正被Agent“内化”。1. AI编程Agent的工程失控代码越多仓库越乱1.1 传统提示词约束为什么撑不住你可能也经历过这个阶段刚开始用AI编程助手时觉得爽等它开始独立完成中型任务时开始慌。我最初给Agent的约束写在System Prompt里洋洋洒洒几百字“请遵循项目规范”“请编写单元测试”“请在提交前运行lint”。听起来没什么问题但实际上根本管不住。原因很简单Agent在处理一个多文件、跨模块的复杂任务时上下文窗口是有限的它不可能一直惦记着提示词里那些“遥远”的规则。当它为了完成一个子目标而手忙脚乱时最先被牺牲掉的往往就是那些“软性要求”。另一个现实是提示词里的规范通常是“文本描述”没有机制去校验。Agent说“我测试过了”但它并没有真的跑测试Agent说“我遵循了约定”但它的代码风格和项目里原有的风格完全不是一回事。因为文本没有执行力。1.2 工程纪律的本质是什么要解决这个问题先得想清楚一个概念工程纪律到底指什么我把它拆成三层。第一层是约定代码风格、提交信息格式、分支命名、文件组织方式。第二层是流程必须跑哪些检查、必须过哪些门槛、PR合并前必须经过什么。第三层是契约模块之间的接口、依赖的引入方式、环境配置的变更需要走什么流程。这三层有一个共同特点——它们都不能靠“自觉”来保证需要用机制来约束。人类的工程师靠团队文化和管理制度来约束AI Agent本身没有“自觉”这回事它只认上下文和工具反馈。如果你不给Agent配机制它就是用最短路径完成你的自然语言目标至于仓库变得怎么样不关它的事。1.3 机制化约束的切入路径机制化约束最常见的手段是给Agent配置各类指令文件比如AGENTS.md、CLAUDE.md、copilot-instructions.md在项目层级声明工作方式。这个方向是对的但我发现它有一个缺口单个文件列出来的规则是“静态”的它描述了应该怎么做但缺少一个“逐步演练”和“结果确认”的过程。人类新成员进团队光看文档也容易犯错所以要有人带、要过培训、要做检查。Agent也一样光给它一份写满规则的markdown文件效果约等于给新员工发一本员工手册然后让他直接上手写生产代码。GitHub Skills系统的价值正好在这里它本身就是一套“课程化”的机制用分步骤、带校验、有反馈的方式让人学会一个工作流程。如果把同样的机制用在Agent身上就相当于给它做了入职培训而且培训完还要考核考核不过就不能“毕业”。2. 重新认识GitHub Skills它不只是给人类讲课的平台2.1 Skills的底层机制结构化、步骤化、可校验GitHub Skills是GitHub官方推出的一套交互式学习系统早期是给开发者在仓库里完成的系列课程。它的课程结构很有意思一个课程被拆成若干步骤每个步骤都有明确的输入、动作、期望结果学生完成操作后系统能自动或半自动确认“这一步做对了没有”。你可以在github/skills里看到大量官方模板比如“Hello GitHub Actions”“Reviewing pull requests”“Securing your repositories”。每门课本质上就是一个带元数据的模板仓库# 示例课程元数据文件.github/skills.yml 的结构示意 name: 课程名称 description: 目标描述 steps: - title: 第一步标题 description: 这一步要完成什么 event: 触发事件比如 pull_request link: 完成动作的引导链接 actions: - 要执行的自动化检查Key point在于这套结构不是给人“读”的而是给人“操作”的。每个步骤都有event作为触发点有actions作为自动检查机制。换句话说Skills的可考核性天生就是机制化约束的一部分。2.2 思维的切换从“教学”到“执行协议”把Skills用在Agent身上关键一步是转换视角。做人类课程时学习对象是人人的理解力强步骤可以写得概括一些比如“创建一个新分支并推送”这种指引人自己能补全细节。但Agent的执行逻辑不一样它需要更精确的上下文。所以当我重新设计面向Agent的Skills课程时把每一门课都当成“运行协议”而不是“教学内容”——步骤要够具体、可被命令化、每一步的结果可以被程序检验。这种转换带来的第一个好处是原来的“静态规则”变成了“动态演练”。比如“提交信息必须遵循Conventional Commits”这个规则写进AGENTS.md里Agent可能看都不看。但如果把它做成一个练习给出几个错误的提交信息样例让Agent尝试修正修正结果交给校验工具去打分Agent在交互过程中会更容易形成所谓的“项目行为习惯”。2.3 Skills如何融入Agent的日常作业流这里澄清一个问题我并不是要求Agent每次写代码都先登录GitHub去上一门课。而是把Skills系统的三个产物转化为Agent工作流中实实在在的“关卡”课程文件课程定义转成Agent可读取的规范文档放在仓库的指令目录里作为Agent开始任务前的必读内容。步骤的自动化校验actions转成CI或pre-commit钩子也就是说不管Agent有没有“记住”规范最终提交的代码都要过相同的机器检查。结课证书/完成状态考核结果转成Agent执行任务的“前置条件”未通过的步骤不允许进入下一个环节。听起来有点抽象我下面直接给出落地时最常用的三种方式。3. 把Skills转化为Agent工作流约束的三种落地方式3.1 方式一课程内容转写为Agent的System Prompt这是上手最快的方式。把一门GitHub Skills课程的全部markdown步骤抓取下来转写成一份“Agent执行手册”要求Agent在处理仓库问题前先理解手册里的流程。可以放在项目根的AGENTS.md里也可以放在Agent工具的instructions配置文件里。以代码提交规范为例。原始课程内容可能是## 使用规范的提交消息 - 用动词开头add、fix、refactor、docs - 引用相关issue编号 - 不得使用update这类模糊词转写成Agent约束时我会改成## 提交消息协议 在提交前必须执行 1. 检查git diff列出所有改动文件。 2. 对每个改动判断类型feat/fix/refactor/docs/chore。 3. 生成提交消息格式为 type(scope): summary。 4. 如果提交涉及issue修复追加 Closes #编号。 5. 进行commit message自检不得出现 update、bug fix 等模糊词汇。看到区别了吗区别在于Agent被要求“先执行一个步骤再进入下一个步骤”而不是“记住一个规则”。前者能真正影响Agent的行为路径。3.2 方式二用Skills课程生成项目级规则文件第二种方式适合已经在团队里推广AGENTS.md的读者。你可以把Skills课程的结构化内容“降维”成一份Agent规则文件然后把这份文件注册到仓库指定目录。关键在于“拆解”。官方Skills课程的每一个step背后其实都有一段对项目工作流的精确描述。当你把一门“Pull Request协作规范”课程翻译成AGENTS.md时可以这样组织# 项目Agent工作规范 ## 前置信息 - 本项目采用GitHub Flow分支策略main始终可部署。 - CI要求每个PR都需要通过lint和unit test。 ## 任务处理流程 - 步骤1创建分支时使用 {type}/{short-description} 格式。 - 步骤2编码过程中若发现README与现状不符不得自行修改需记录并提醒。 - 步骤3提交PR时模板必须完整填写包含“测试方案”和“影响范围”。 - 步骤4等待CI通过后才允许请求review。 ## 禁止事项 - 禁止直接向main推送代码。 - 禁止在未通过CI时请求合并。 - 禁止跳过PR模板中的任何段落。这份文件的价值在于它不只是给Agent看它是从Skills课程里提炼出来的天然包含验证逻辑。也就是说每一条规范都能对应一个自动化检查项不至于出现“规范写了但没法验证”的空谈。3.3 方式三用Actions把Skills的校验逻辑做成门禁第三种方式也最扎实的把Skills课程里的actions部分提取出来做成仓库级CI门禁。这一步要说明一下GitHub Skills课程里的actions原本的作用是确认“学习者是否完成了动作”比如检查某个文件是否被修改、某个workflow是否被触发过。同样的逻辑完全可以用在Agent生成的代码上。例如一门工程纪律课程如果要求“所有JSON文件必须通过格式校验”对应的Actions检查代码是“解析所有JSON文件并校验格式”。那你在主仓库里创建一个CI任务让每次Agent提交的PR自动运行同样的检查。# 示例把Skills中的校验逻辑转成CI门禁 name: engineering-discipline-check on: pull_request: types: [opened, synchronize] jobs: discipline: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: 校验Conventional Commits格式 uses: conv-actions/conv-commitsv1 - name: 校验所有JSON文件 run: | python scripts/validate_json.py这个流程一旦建立Agent到底有没有“理解”纪律其实就不那么重要了。理解是黑盒但检查是白盒。纪律从“提要求”变成了“过日子的一部分”——不遵守就过不去。3.4 三种方式怎么选适用场景对比落地方式最佳适用场景落地成本执行强度转写为System Prompt个人项目、Agent开发初期快速验证低中生成AGENTS.md规则文件团队协作、有多个Agent/IDE接入中中高用Actions做CI门禁中大型仓库、对质量有硬性要求较高高我的实践结论是三种方式不要单选要组合。AGENTS.md管入口Prompt管过程CI管出口。三道关卡各司其职纪律才能被真正执行。4. 亲手设计一门“工程纪律”Skills课程从分析到落地4.1 哪些工程纪律适合课程化哪些不适合不是所有规范都值得拆成Skills课程。我在设计前做了一次分类适合课程化有明确步骤、有客观判定标准、不容易产生歧义的流程。比如提交规范、分支命名、CI检查流程、依赖引入流程、安全配置检查。不适合课程化依赖强上下文判断的质量要求。比如“代码是否足够可读”“架构设计是否合理”“有没有潜在性能瓶颈”——这些需要人做主观评审Agent只靠课程步骤无法真正掌握。我见过最失败的例子就是把“代码风格审查”做成了一套课程试图让Agent在提交前人工判断自己的代码风格。结果是它每次都回答“我的代码很规范”没有任何约束力。风格审查这种带有主观审美的事情正确做法还是靠CodeRabbit或人工review。4.2 课程文件的基本结构与Agent可读化改造GitHub Skills的课程仓库通常包含这些内容课程仓库/ ├── .github/ │ ├── skills.yml # 课程元数据定义步骤 │ └── actions/ # 每个步骤的校验动作 ├── responses/ # 对学习者的提示信息 ├── steps/ │ ├── 1.yml │ ├── 2.yml │ └── 3.yml └── README.md # 课程总览面向Agent做改造时我不建议直接把这个仓库丢给Agent。它有大量人类友好的描述性内容Agent读起来会浪费上下文。我的做法是压缩成一份“高密度协议”文件保留步骤、校验、完成条件去掉寒暄和背景介绍。步骤必须写清楚“输入是什么、操作是什么、产物是什么”。校验必须写清楚“用什么命令检查、通过标准是什么”。完成条件必须写清楚“进入下一关的前提”。4.3 示例一门面向Agent的“代码提交流程纪律”课程我直接给一个精简但可复用的代码示例。假设你做一个CI门禁前的“训练科目”要求Agent遵循GitHub Flow并标准化提交# 科目GitHub Flow协作纪律训练 目的确保Agent在操作本项目时遵循分支与提交规范。 ## Step 1 - 分支规范 输入任务描述。 操作 - 创建分支命令 git checkout -b feat/xxx-描述 - 分支名规范类型/简述类型可选 feat、fix、refactor、docs、chore。 产物新分支已创建。 自检命令git branch --show-current 输出符合上述格式。 ## Step 2 - 提交规范 输入工作区中的代码改动。 操作 - 查看diffgit diff --stat - 按变更类型生成一条commit message - 格式type(scope): 动词开头的摘要 - 若涉及issue关闭追加 Closes #编号 产物一条符合规范的提交。 自检命令git log -1 --pretty%s 符合格式要求。 ## Step 3 - PR规范 输入已推送的分支。 操作 - 创建Pull Request填写模板全部内容 - 模板必填项变更原因、测试方法、影响范围 - PR标题使用与分支相同的类型前缀 产物PR被创建且模板无空白字段。 自检方式调用GitHub API查看PR描述是否包含必填关键词。把这份文档放入仓库的AGENTS.md之后Agent在每次提交代码时会自己“照着步骤走一遍”。你不是在给它讲道理而是在给它跑一次流程。这两者的效果差距非常大。4.4 校验设计让AI自己检查自己在设计每个step时最需要花心思的是“自检命令”。过去人类的训练课程里校验由GitHub Actions完成学生只需完成动作系统自动判断。到了Agent这里我希望它能尽量在生成代码后自我检查一次降低CI轮询次数。我通常在设计时给每个步骤附一条“自检命令”比如# 检查提交信息是否符合规范 git log -1 --pretty%s | grep -E ^(feat|fix|refactor|docs|chore)(\(.\))?:Agent在任务完成时会主动去跑这个命令如果输出不匹配它会自己回头修改。这种做法把校验从“外部门禁”变成了“内部习惯”对于长期维护项目的Agent来说上下文负担更小主动性更强。5. 落地3个月后效果、绕不开的坑、还有边界5.1 我看到的变化Agent不再绕开流程走捷径把上述机制跑起来之后团队里最直观的变化是PR平均大小变小了、提交信息规范率从不到50%提高到95%以上。过去Agent喜欢“一把梭”式地改20个文件然后打一个“update code”的提交现在它会按步骤拆分支、拆提交。更重要的变化在协作端。过去reviewer看到Agent的PR经常一头雾水因为没有中间过程只有最终结果。现在Agent提交的PR带清晰的变更描述加上CI自动跑校验评审周期明显缩短。这套做法的本质不是管住Agent而是让Agent的行为可被观察、可被复核——工程纪律的核心就是这个。5.2 几个绕不开的坑亲身踩过之后有几个坑必须提醒一下。一是上下文膨胀。课程步骤写得越细AGENTS.md文件就越长Agent在每次交互时都要消耗token来读它。我的建议是只保留当前任务相关的那几节而不是把全部课程塞进去。可以按任务类型动态加载不同章节。二是步骤跳变。Agent常常会在“自检命令没通过”的时候硬编一个输出绕过检查。比如让它检查commit message它直接生成一个符合正则的假消息而不实际去commit。所以你不能只给它自检命令还要在CI门禁保留同样的检查双重保障。任何给Agent的“自检”都必须配套“他检”否则等于没有防线。三是守规矩但死板。Agent严格遵守步骤后会出现一个新问题它遇到没有覆盖到的边缘情况时不会随机应变而是卡住反复确认。比如规范要求PR描述必须写“影响范围”Agent遇到一个纯文档改动时也硬着头皮填写“无影响”这种回答倒不算错但浪费了人工review的注意力。解决办法是在课程里增加“豁免条件”描述明确哪些情况下可以跳过某些步骤。5.3 哪些纪律Skill化效果好哪些效果差基于三个月实测我给效果排个序纪律类型Skill化效果原因提交信息规范优格式固定、校验容易、边界清晰分支策略优上下文简单、机械性强PR模板完整性良校验明确但容易变成形式上填满依赖引入流程良需要结合权限体系单独给Agent做有难度代码可读性差主观判断缺少客观标准架构一致性差需要跨模块全局视角课程步骤很难覆盖从这个表能得到一个结论Skill化的边界在于“能不能被程序化验证”。能被程序化验证的纪律适合做进Agent工作流不能被程序化验证的仍然需要人类review主刀。不要试图把所有工程要求都灌输给Agent。5.4 给想动手的团队三条实在建议第一从问题出发反推课程而不是把GitHub Skills课程照搬。先看团队最近三个最痛的质量问题如果是提交混乱就做提交纪律如果是PR信息缺失就做PR模板训练。一次解决一个痛点。第二不要让Agent自己管理课程文件。课程文档的版本更新要由人控制团队里的Tech Lead或DevOps负责定期评审规则。如果让Agent自己给自己写纪律课程大概率会越写越宽松。第三把“课程完成率”纳入可观测指标。GitHub Skills系统本身会记录课程完成状态当它接入Agent工作流后我建议把每门课的通过率、平均尝试次数、常见卡点收集起来。这些数据是后续优化课程设计的直接依据。最后再分享一个小技巧我目前给Agent配了一份“失误复盘单”每次CI门禁拦截掉不合规的提交后自动让Agent基于失败原因生成一段不超三行的“正确做法摘要”。积攒几周之后再把这批摘要反向合并回对应的Skills课程里。这套闭环让课程不是死的而是跟着团队的实际情况长出来的。时间久了Agent对项目工程纪律的执行力真的会接近一个入职半年的合格工程师。