最近半年我一直在折腾一个叫AI-Infra-Auto-Driven-SKILLS的框架项目目前迭代到 v0.1.5。老读者可能记得我吐槽过 Codex 和 Claude Code 这类终端 AI 编程代理脑子不够使的问题——不是模型笨而是每次任务进来都像没头苍蝇要么跳过规划直接写代码要么无视项目已有的约定。v0.1.5 就是冲着这个痛点去的它是一套面向 Codex / Claude Code 的技能库加推理工作流负责把这个任务该按什么步骤想、该调用哪份技能文档、做完怎么验证这件事固定下来。如果你也在用 AI 写代码或者正在搭团队级的 Agent 工作流这篇内容可以直接当配置参考。本文会把这套框架的动机、目录结构、推理启动链路、双工具接入差异、实测踩坑全部摊开讲包括我踩过的上下文膨胀、双 Agent 行为不一致这类问题。下面按我实际迭代的顺序来写。1. 先说动机为什么我需要一套技能驱动的工作流1.1 裸奔的 Codex / Claude Code 有多不靠谱先说个场景。某次我给 Claude Code 丢了一个给登录模块加个验证码的需求它上来就改了三个文件等我 review 的时候发现验证码生成逻辑写在了前端组件里、后端接口没加限流、错误提示文案和现有风格完全不一致。代码能跑但质量一言难尽。这不是模型能力的问题是工作方式的问题。默认状态下这类代理会把回应对话当作第一目标而不是把项目当回事。它不会先去看你项目的架构文档不会主动遵守你代码仓库里的 lint 规则更不会在改完代码后跑一遍测试再向你汇报。你把所有约束写进 system prompt那上下文会被撑爆而且每次对话都要为这些常识付费。我试过在 CLAUDE.md 里写十几条规矩试过在 Codex 的 AGENTS.md 里堆注意事项效果都一般。原因很简单约束如果不和任务类型绑定就是一堆噪音。改个 CSS 的任务不需要加载安全评审规则重构核心模块的任务又必须走完整推理链路。一刀切的约束要么太松要么太紧。1.2 技能驱动到底是什么思路v0.1.5 的核心思路其实就一句话把项目知识和推理步骤拆成一个个小技能包按任务类型按需加载而不是一次性全塞给 Agent。打个比方。默认的 Agent 像一个刚入职的实习生你给他一份两百页的公司制度手册他翻了两页就厌了遇到实际问题还是按自己习惯来。而技能驱动的做法是给每个岗位配一张遇到 X 情况就打开 Y 手册的索引卡遇到问题先查索引卡再读对应手册的那几页。具体到 v0.1.5它做三件事技能仓库把项目经验、编码规范、领域知识拆成独立的 Markdown 规则文件每个技能包只解决一类问题推理框架定义一套标准的任务处理流程比如澄清需求 → 拆解任务 → 设计方案 → 执行变更 → 自测验证 → 复盘总结Agent 拿到新任务先走框架而不是自由发挥自动驱动层根据任务描述、当前目录、git 变更等信息自动决定加载哪些技能、按什么顺序执行哪些推理阶段。v0.1.5 是第 15 个小版本覆盖的技能包从最早的 8 个涨到了 32 个推理模板从 3 套变成了 6 套。下面我直接把当前版本的内部结构翻出来给你看。2. 目录级拆解一套技能包是怎么组织的2.1 skills 仓库的物理布局先看整体目录结构。v0.1.5 不再像早期版本那样把所有技能平铺在根目录而是按推理阶段分成了六个子目录ai-infra-auto-driven-skills/ ├── router/ │ └── task-router.yaml # 任务分类路由规则 ├── skills/ │ ├── analyze/ # 需求澄清、影响面分析 │ │ ├── requirement-clarify/ │ │ └── impact-analysis/ │ ├── plan/ # 技术方案、任务拆解 │ │ ├── tech-design/ │ │ └── todo-breakdown/ │ ├── implement/ # 编码规范、模块实现 │ │ ├── coding-style/ │ │ ├── api-standards/ │ │ └── error-handling/ │ ├── verify/ # 自测、lint、测试补充 │ │ ├── self-test-checklist/ │ │ └── lint-verify/ │ └── reflect/ # 变更总结、commit 规范 │ └── review-summary/ ├── templates/ # 推理阶段提示词模板 │ ├── stage-analyze.md │ ├── stage-plan.md │ ├── stage-implement.md │ ├── stage-verify.md │ └── stage-reflect.md ├── scripts/ │ ├── skill-detect.sh # 环境探测脚本 │ └── context-build.py # 生成 Agent 上下文包 └── versions/ └── v0.1.5.changelog.md这个布局的用意很直接按推理阶段分目录Agent 在某个阶段只需要读对应目录下的技能。比如进入 verify 阶段时它只会加载verify/下面的自测检查单和 lint 规则不会把 implement 阶段的编码风格又读一遍。2.2 每个技能包里的三样东西早期版本每个技能就是一份 Markdown结果发现文件一多就没法维护。v0.1.5 里每个技能包固定包含三件套skill-name/ ├── SKILL.md # 给 Agent 看的操作手册 ├── rules.yaml # 给驱动层看的加载规则 └── examples/ # 正反示例可选SKILL.md是核心但有个硬性要求前 100 个字必须说清楚这个技能解决什么问题、什么时候不用它。为什么因为 Agent 是靠语义匹配决定是否加载技能的开头写不清楚匹配阶段就容易把不相关的技能拉进来。rules.yaml是写给程序看的定义了触发条件。拿 api-standards 技能举个例子name: api-standards version: 2.3.0 triggers: - reg: (add|modify|create|update).*(api|endpoint|route|interface) - dir: server/controllers - dir: server/routes conditional: - if: frontend_code_changed backend_api_changed use: [api-contract-check] priority: 70这段规则的意思是当任务描述里出现新增/修改接口这类关键词或者改动范围落在 controllers / routes 目录就触发 api-standards 技能。priority用于多个技能同时匹配时决定加载顺序。2.3 版本与兼容性v0.1.5 的更新思路为什么单独搞一个versions/目录因为这半年我吃够了技能和项目不同步的苦头。技能包和代码仓库是两套生命周期的产物。代码仓库在快速迭代技能里的编码规范如果三个月不更新Agent 就会按过时的规矩干活产出直接被团队打回。v0.1.5 的做法是每个技能包独立维护版本号SKILL.md有修改就 bump 一版顶层项目保持统一的 v0.1.x 版本代表整个框架的对外 API 稳定程度每个版本发布时changelog里必须记录哪个技能改了、为什么改、对 Agent 行为有什么影响。这样做的直接好处是团队升级 v0.1.5 时能提前知道行为变化不至于出现昨天 Agent 还会写单测今天突然不写了这种灵异事件。3. 推理框架的启动链路从任务进来开始3.1 第一步任务分类与技能匹配路由Agent 拿到一个新任务时第一件事不是写代码而是跑路由。v0.1.5 里路由由两部分协作完成router/task-router.yaml负责粗分类scripts/context-build.py负责按分类结果组装上下文。路由规则长这样categories: - name: bugfix patterns: - fix|repair|broken|crash|bug stages: [analyze, plan, implement, verify, reflect] load_skills: [impact-analysis, coding-style, self-test-checklist] - name: feature patterns: - add|implement|support|new feature stages: [analyze, plan, implement, verify, reflect] load_skills: [requirement-clarify, tech-design, api-standards, self-test-checklist] - name: refactor patterns: - refactor|restructure|clean up|rename stages: [analyze, plan, implement, verify, reflect] load_skills: [impact-analysis, coding-style, lint-verify] - name: docs patterns: - documentation|readme|comment|doc stages: [plan, implement] load_skills: [docs-style]注意bugfix和feature的差异修复 Bug 不需要走完整的需求澄清但要加载影响面分析——因为你得先判断这个 Bug 会不会波及别的地方。文档任务则不需要 verify 阶段它本来就不跑测试。这一步的实际效果是一个修 Bug的任务进来时Agent 的上下文里只会有任务路由规则、impact-analysis 技能、coding-style 技能、self-test-checklist 技能、以及对应的阶段模板。比裸奔时省掉的无关指令至少六成。3.2 第二步推理模板的上下文注入路由决定走哪些阶段之后context-build.py会把templates/下的阶段模板注入到 Agent 的初始上下文里。每个阶段的模板都遵循同一个格式目标 → 输入 → 操作步骤 → 产出物 → 验收标准。以stage-plan.md为例## 阶段规划PLAN 目标基于分析结果输出可执行的变更方案。 输入 - 上一阶段的分析结论 - 当前仓库结构 - 相关技能包内容 操作步骤 1. 列出至少两个候选方案对比优缺点。 2. 选择方案时遵循仓库既有约定不要引入新模式。 3. 将任务拆成 5 到 15 个可独立验证的子任务。 4. 标注每个子任务的依赖关系。 产出物 - 一份包含子任务清单、变更文件列表、风险点的方案文档。 验收标准 - 每个子任务都能在 10 分钟内完成。 - 变更文件列表与后续实施阶段一致。 - 方案文档中不存在待定再说类模糊词汇。这里我最想强调的是验收标准这一格。早期模板只写步骤结果 Agent 老老实实走完了流程产出却是一堆没头没尾的半成品。后来在每步后面追加验收标准情况立刻变了——Agent 会自己对照标准检查产出不合格就返工而不是交差完事。3.3 第三步结果验证与人工回环推理链路到 reflect 阶段并没有结束v0.1.5 还加了一个人工回环机制Agent 完成变更后必须生成一份变更汇报但汇报不是终点而是触发人工 review 的起点。变更汇报模板里包含- 改了什么按文件列出变更点 - 为什么这么改对应哪个推理阶段、哪个技能约束 - 如何验证执行了哪些测试/lint结果如何 - 遗留风险哪些地方没把握需要人来看这套机制解决了一个实际问题让 Agent 的推理过程可审计。以前它改完代码你只能通过 diff 猜测它的思路现在它必须把为什么这么改写出来你 review 的时候一眼就能看出它有没有遵守技能规则卡在哪个环节。人工回环的粒度是可以调的。团队刚开始用的时候可以要求每个任务都走完 review运行两周后如果 Bug 修复类任务的通过率高就可以只抽查把精力留给 feature 类任务。4. 接入 Codex 与 Claude Code 的差异处理4.1 Codex 的命令与技能加载方式Codex 命令行工具对自定义指令的支持主要靠 AGENTS.md 和自定义命令。AGENTS.md 相当于项目级的长期记忆Agent 启动时会自动读取。自定义命令则放在配置文件目录下用户手动触发。v0.1.5 给 Codex 做的接入方案是把context-build.py生成的技能上下文包写到 AGENTS.md 对应位置但做了分层处理。AGENTS.md 里只放索引和路由规则技能全文通过层级引用按需加载。参考结构AGENTS.md ├── 项目通用信息简短 ├── SKILLS 索引每个技能一句话 触发条件 ├── 推理阶段约定五阶段流程简述 └── 验证规则测试与 lint 命令为什么不全量写进 AGENTS.md因为 Codex 的上下文窗口虽然不小但 AGENTS.md 被读入后一直占着位置。我实测过把 32 个技能全文塞进去后上下文里光技能说明就占了两万多 tokenAgent 回复速度肉眼可见地变慢而且容易在无关技能里挑着看等于回到了一刀切的老路。4.2 Claude Code 的 Skills 目录与插件机制Claude Code 的情况和 Codex 不太一样。它原生支持 Skills 目录机制.claude/skills/下的每个技能包有自己的SKILL.mdAgent 可以根据任务自动选择是否加载某个技能。这比把全部指令塞进 CLAUDE.md 要优雅得多。v0.1.5 对 Claude Code 的适配核心是把上面那套rules.yaml翻译成 Claude Code 的 Skills 元信息格式。一个标准的技能包在.claude/skills/里长这样.claude/skills/ ├── api-standards/ │ ├── SKILL.md │ ├── metadata.yaml │ └── examples/ └── self-test-checklist/ ├── SKILL.md ├── metadata.yaml └── examples/metadata.yaml里写了技能的描述和触发关键词Claude Code 会依据这段描述来决定何时加载技能。描述里必须写清什么情况下用和什么情况下别用否则 Agent 容易在无关任务里也把技能拉出来。4.3 一套技能两份配置的做法同时维护 Codex 和 Claude Code 两套配置听起来维护成本翻倍但 v0.1.5 的实际做法是源头只有一份其他全是生成的。具体流程在skills/目录里用统一格式维护技能内容SKILL.md rules.yaml运行scripts/context-build.py --target codex生成 Codex 的 AGENTS.md运行scripts/context-build.py --target claude生成.claude/skills/下的技能包。两份配置共享同一个内容源rules.yaml里的触发条件在生成时分别映射到两种机制。Codex 侧映射成 AGENTS.md 里的关键词索引Claude Code 侧映射成metadata.yaml里的 description。生成脚本我放在 CI 里跑每次技能内容有变更自动重新生成两份配置并提交到仓库。这样团队里用 Codex 的和用 Claude Code 的同事拿到的技能约束完全一致不会出现我用 Claude Code 改的接口格式和你用 Codex 改的对不上的尴尬。下表整理了 v0.1.5 在两种工具下的接入差异维度Codex 接入Claude Code 接入配置载体AGENTS.md 自定义命令.claude/skills/ 技能目录技能加载按索引语义匹配按 metadata 语义匹配阶段模板注入通过 AGENTS.md 索引引用通过 skills 目录轮询加载验证钩子自定义命令触发技能内嵌 checklist维护方式脚本生成脚本生成5. 实测三个月沉淀下来的坑5.1 上下文膨胀与技能文件太啰嗦v0.1.5 早期版本最大的败笔是技能文件写得像论文。比如 coding-style 技能我最初写了四千多字涵盖了命名、缩进、注释、异常处理、数据库访问……应有尽有。结果 Agent 加载这个技能后生成代码的风格确实符合规范但整个对话的上下文被占掉一大截后续修改时它反而记不住任务本身的需求了。后来我把每个技能的 SKILL.md 压到 300 到 800 字只保留规则 正反例 验收标准三块。缩进规则这种一句话能说清的绝不展开异常处理规范直接配一个好的写法/坏的写法对照示例示例比解释省 token 且效果好得多。压完以后上下文占用降了约四成任务完成质量反而提升了。这里有个反直觉的经验技能文件的核心价值不是教会 Agent 怎么做而是告诉它去哪查、查完怎么核对。细节留给人或者代码仓库里的既有模式去沉淀。5.2 双 Agent 行为差异导致的同一套技能两个结果这是最让我头疼的一个坑。同一套技能配置Codex 和 Claude Code 跑出来的结果经常不一样。Codex 倾向于严格遵守 AGENTS.md 里的步骤清单按部就班地走流程Claude Code 则更灵活经常跳过非强制的步骤直接跳到实现阶段。发现这个问题的方式很偶然——团队里两个同事用不同工具改同一个模块一个人交上来的代码带了详细的方案文档另一个人只改了代码没写方案。一查才发现Claude Code 把输出方案文档当成可选项跳过了。解决办法是在技能规则里增加强制级别字段requirements: - id: plan-doc action: mandatory check: 存在 plan/ 目录下的方案文档 - id: lint-pass action: mandatory check: lint 命令 exit code 0 - id: commit-prefix action: recommended note: 提交信息建议按约定前缀生成阶段模板时mandatory级别的条目会写到验收标准区块并明确标注缺少此项视为任务未完成recommended级别则写明在条件允许时执行未执行需在汇报中说明原因。加了这个区分之后双 Agent 的行为一致性明显提升。5.3 更新策略别让技能变成技术债技能库最隐蔽的成本不是创建而是维护。项目代码风格变了、依赖框架升级了、团队约定改了任何一个变化都可能导致技能内容过时。v0.1.5 里我踩过的具体坑是某个技能里写死了旧的 ORM 用法结果 Agent 每次改数据库相关代码都按旧规范来生成的代码直接编译不过。现在我的维护策略有三条每次技能使用后留反馈Agent 完成一个任务后在汇报里标注本次使用了哪些技能、哪些规则对结果无帮助。攒够反馈就删掉无用的规则每周做一次技能审计把技能内容里涉及 API 名、命令路径、目录结构的部分抽出来和当前仓库实际情况比对不一致的立即改技能变更走 PR 流程技能文件的修改不直接 push要像改代码一样经过 review。因为技能变更会同时影响 Codex 和 Claude Code 两份配置改错了等于让所有 Agent 同时犯错。这三条执行下来技能库从越用越脏变成了越用越精准。目前 v0.1.5 的 32 个技能里大约每个月会调整五六个但整体结构保持稳定。6. 适合谁不适合谁以及下一步想做的事先说结论这套 v0.1.5 的推理框架工作流最适合的是手里有一批模式固定、重复度高、修改频繁的代码任务的个人开发者或小团队。比如接口联调、Bug 修复、写测试、补文档这类任务技能驱动能明显减少你反复交代同样要求的次数。你的项目约定越清晰这套体系收益越大。不适合的场景我也踩过如果你主要用 Agent 做探索性的、一次性的研究任务或者代码仓库本身没什么约定可循技能库反而会变成束缚——Agent 花在匹配技能上的时间比实际干活还长性价比很低。另外如果团队里没人维护技能库那就不如别上这种重方案老老实实用 CLAUDE.md 写三条最硬的规矩更实际。v0.1.5 下一步我打算做两件事一是给context-build.py加一个技能使用统计输出跑完任务能自动记录每个技能被加载次数和引用次数帮我把没用的技能揪出来二是支持按项目目录做技能版本锁定让老项目继续用旧技能、新项目用新技能别让一次升级波及全部历史仓库。最后分享一个我自己的体会做这套东西最难的永远是克制。我一开始什么规范都想塞进去结果证明全是噪音。技能驱动真正的价值不是让 Agent 变聪明而是让你把项目里那些默认大家都知道的知识显性化——写进技能包的那一刻才是它们真正开始发挥作用的时候。 
长河君 · 2026/10/13 17:19:44 · 阅读 1.2k AI编程代理技能驱动工作流：v0.1.5框架实战解析
最近半年我一直在折腾一个叫AI-Infra-Auto-Driven-SKILLS的框架项目目前迭代到 v0.1.5。老读者可能记得我吐槽过 Codex 和 Claude Code 这类终端 AI 编程代理脑子不够使的问题——不是模型笨而是每次任务进来都像没头苍蝇要么跳过规划直接写代码要么无视项目已有的约定。v0.1.5 就是冲着这个痛点去的它是一套面向 Codex / Claude Code 的技能库加推理工作流负责把这个任务该按什么步骤想、该调用哪份技能文档、做完怎么验证这件事固定下来。如果你也在用 AI 写代码或者正在搭团队级的 Agent 工作流这篇内容可以直接当配置参考。本文会把这套框架的动机、目录结构、推理启动链路、双工具接入差异、实测踩坑全部摊开讲包括我踩过的上下文膨胀、双 Agent 行为不一致这类问题。下面按我实际迭代的顺序来写。1. 先说动机为什么我需要一套技能驱动的工作流1.1 裸奔的 Codex / Claude Code 有多不靠谱先说个场景。某次我给 Claude Code 丢了一个给登录模块加个验证码的需求它上来就改了三个文件等我 review 的时候发现验证码生成逻辑写在了前端组件里、后端接口没加限流、错误提示文案和现有风格完全不一致。代码能跑但质量一言难尽。这不是模型能力的问题是工作方式的问题。默认状态下这类代理会把回应对话当作第一目标而不是把项目当回事。它不会先去看你项目的架构文档不会主动遵守你代码仓库里的 lint 规则更不会在改完代码后跑一遍测试再向你汇报。你把所有约束写进 system prompt那上下文会被撑爆而且每次对话都要为这些常识付费。我试过在 CLAUDE.md 里写十几条规矩试过在 Codex 的 AGENTS.md 里堆注意事项效果都一般。原因很简单约束如果不和任务类型绑定就是一堆噪音。改个 CSS 的任务不需要加载安全评审规则重构核心模块的任务又必须走完整推理链路。一刀切的约束要么太松要么太紧。1.2 技能驱动到底是什么思路v0.1.5 的核心思路其实就一句话把项目知识和推理步骤拆成一个个小技能包按任务类型按需加载而不是一次性全塞给 Agent。打个比方。默认的 Agent 像一个刚入职的实习生你给他一份两百页的公司制度手册他翻了两页就厌了遇到实际问题还是按自己习惯来。而技能驱动的做法是给每个岗位配一张遇到 X 情况就打开 Y 手册的索引卡遇到问题先查索引卡再读对应手册的那几页。具体到 v0.1.5它做三件事技能仓库把项目经验、编码规范、领域知识拆成独立的 Markdown 规则文件每个技能包只解决一类问题推理框架定义一套标准的任务处理流程比如澄清需求 → 拆解任务 → 设计方案 → 执行变更 → 自测验证 → 复盘总结Agent 拿到新任务先走框架而不是自由发挥自动驱动层根据任务描述、当前目录、git 变更等信息自动决定加载哪些技能、按什么顺序执行哪些推理阶段。v0.1.5 是第 15 个小版本覆盖的技能包从最早的 8 个涨到了 32 个推理模板从 3 套变成了 6 套。下面我直接把当前版本的内部结构翻出来给你看。2. 目录级拆解一套技能包是怎么组织的2.1 skills 仓库的物理布局先看整体目录结构。v0.1.5 不再像早期版本那样把所有技能平铺在根目录而是按推理阶段分成了六个子目录ai-infra-auto-driven-skills/ ├── router/ │ └── task-router.yaml # 任务分类路由规则 ├── skills/ │ ├── analyze/ # 需求澄清、影响面分析 │ │ ├── requirement-clarify/ │ │ └── impact-analysis/ │ ├── plan/ # 技术方案、任务拆解 │ │ ├── tech-design/ │ │ └── todo-breakdown/ │ ├── implement/ # 编码规范、模块实现 │ │ ├── coding-style/ │ │ ├── api-standards/ │ │ └── error-handling/ │ ├── verify/ # 自测、lint、测试补充 │ │ ├── self-test-checklist/ │ │ └── lint-verify/ │ └── reflect/ # 变更总结、commit 规范 │ └── review-summary/ ├── templates/ # 推理阶段提示词模板 │ ├── stage-analyze.md │ ├── stage-plan.md │ ├── stage-implement.md │ ├── stage-verify.md │ └── stage-reflect.md ├── scripts/ │ ├── skill-detect.sh # 环境探测脚本 │ └── context-build.py # 生成 Agent 上下文包 └── versions/ └── v0.1.5.changelog.md这个布局的用意很直接按推理阶段分目录Agent 在某个阶段只需要读对应目录下的技能。比如进入 verify 阶段时它只会加载verify/下面的自测检查单和 lint 规则不会把 implement 阶段的编码风格又读一遍。2.2 每个技能包里的三样东西早期版本每个技能就是一份 Markdown结果发现文件一多就没法维护。v0.1.5 里每个技能包固定包含三件套skill-name/ ├── SKILL.md # 给 Agent 看的操作手册 ├── rules.yaml # 给驱动层看的加载规则 └── examples/ # 正反示例可选SKILL.md是核心但有个硬性要求前 100 个字必须说清楚这个技能解决什么问题、什么时候不用它。为什么因为 Agent 是靠语义匹配决定是否加载技能的开头写不清楚匹配阶段就容易把不相关的技能拉进来。rules.yaml是写给程序看的定义了触发条件。拿 api-standards 技能举个例子name: api-standards version: 2.3.0 triggers: - reg: (add|modify|create|update).*(api|endpoint|route|interface) - dir: server/controllers - dir: server/routes conditional: - if: frontend_code_changed backend_api_changed use: [api-contract-check] priority: 70这段规则的意思是当任务描述里出现新增/修改接口这类关键词或者改动范围落在 controllers / routes 目录就触发 api-standards 技能。priority用于多个技能同时匹配时决定加载顺序。2.3 版本与兼容性v0.1.5 的更新思路为什么单独搞一个versions/目录因为这半年我吃够了技能和项目不同步的苦头。技能包和代码仓库是两套生命周期的产物。代码仓库在快速迭代技能里的编码规范如果三个月不更新Agent 就会按过时的规矩干活产出直接被团队打回。v0.1.5 的做法是每个技能包独立维护版本号SKILL.md有修改就 bump 一版顶层项目保持统一的 v0.1.x 版本代表整个框架的对外 API 稳定程度每个版本发布时changelog里必须记录哪个技能改了、为什么改、对 Agent 行为有什么影响。这样做的直接好处是团队升级 v0.1.5 时能提前知道行为变化不至于出现昨天 Agent 还会写单测今天突然不写了这种灵异事件。3. 推理框架的启动链路从任务进来开始3.1 第一步任务分类与技能匹配路由Agent 拿到一个新任务时第一件事不是写代码而是跑路由。v0.1.5 里路由由两部分协作完成router/task-router.yaml负责粗分类scripts/context-build.py负责按分类结果组装上下文。路由规则长这样categories: - name: bugfix patterns: - fix|repair|broken|crash|bug stages: [analyze, plan, implement, verify, reflect] load_skills: [impact-analysis, coding-style, self-test-checklist] - name: feature patterns: - add|implement|support|new feature stages: [analyze, plan, implement, verify, reflect] load_skills: [requirement-clarify, tech-design, api-standards, self-test-checklist] - name: refactor patterns: - refactor|restructure|clean up|rename stages: [analyze, plan, implement, verify, reflect] load_skills: [impact-analysis, coding-style, lint-verify] - name: docs patterns: - documentation|readme|comment|doc stages: [plan, implement] load_skills: [docs-style]注意bugfix和feature的差异修复 Bug 不需要走完整的需求澄清但要加载影响面分析——因为你得先判断这个 Bug 会不会波及别的地方。文档任务则不需要 verify 阶段它本来就不跑测试。这一步的实际效果是一个修 Bug的任务进来时Agent 的上下文里只会有任务路由规则、impact-analysis 技能、coding-style 技能、self-test-checklist 技能、以及对应的阶段模板。比裸奔时省掉的无关指令至少六成。3.2 第二步推理模板的上下文注入路由决定走哪些阶段之后context-build.py会把templates/下的阶段模板注入到 Agent 的初始上下文里。每个阶段的模板都遵循同一个格式目标 → 输入 → 操作步骤 → 产出物 → 验收标准。以stage-plan.md为例## 阶段规划PLAN 目标基于分析结果输出可执行的变更方案。 输入 - 上一阶段的分析结论 - 当前仓库结构 - 相关技能包内容 操作步骤 1. 列出至少两个候选方案对比优缺点。 2. 选择方案时遵循仓库既有约定不要引入新模式。 3. 将任务拆成 5 到 15 个可独立验证的子任务。 4. 标注每个子任务的依赖关系。 产出物 - 一份包含子任务清单、变更文件列表、风险点的方案文档。 验收标准 - 每个子任务都能在 10 分钟内完成。 - 变更文件列表与后续实施阶段一致。 - 方案文档中不存在待定再说类模糊词汇。这里我最想强调的是验收标准这一格。早期模板只写步骤结果 Agent 老老实实走完了流程产出却是一堆没头没尾的半成品。后来在每步后面追加验收标准情况立刻变了——Agent 会自己对照标准检查产出不合格就返工而不是交差完事。3.3 第三步结果验证与人工回环推理链路到 reflect 阶段并没有结束v0.1.5 还加了一个人工回环机制Agent 完成变更后必须生成一份变更汇报但汇报不是终点而是触发人工 review 的起点。变更汇报模板里包含- 改了什么按文件列出变更点 - 为什么这么改对应哪个推理阶段、哪个技能约束 - 如何验证执行了哪些测试/lint结果如何 - 遗留风险哪些地方没把握需要人来看这套机制解决了一个实际问题让 Agent 的推理过程可审计。以前它改完代码你只能通过 diff 猜测它的思路现在它必须把为什么这么改写出来你 review 的时候一眼就能看出它有没有遵守技能规则卡在哪个环节。人工回环的粒度是可以调的。团队刚开始用的时候可以要求每个任务都走完 review运行两周后如果 Bug 修复类任务的通过率高就可以只抽查把精力留给 feature 类任务。4. 接入 Codex 与 Claude Code 的差异处理4.1 Codex 的命令与技能加载方式Codex 命令行工具对自定义指令的支持主要靠 AGENTS.md 和自定义命令。AGENTS.md 相当于项目级的长期记忆Agent 启动时会自动读取。自定义命令则放在配置文件目录下用户手动触发。v0.1.5 给 Codex 做的接入方案是把context-build.py生成的技能上下文包写到 AGENTS.md 对应位置但做了分层处理。AGENTS.md 里只放索引和路由规则技能全文通过层级引用按需加载。参考结构AGENTS.md ├── 项目通用信息简短 ├── SKILLS 索引每个技能一句话 触发条件 ├── 推理阶段约定五阶段流程简述 └── 验证规则测试与 lint 命令为什么不全量写进 AGENTS.md因为 Codex 的上下文窗口虽然不小但 AGENTS.md 被读入后一直占着位置。我实测过把 32 个技能全文塞进去后上下文里光技能说明就占了两万多 tokenAgent 回复速度肉眼可见地变慢而且容易在无关技能里挑着看等于回到了一刀切的老路。4.2 Claude Code 的 Skills 目录与插件机制Claude Code 的情况和 Codex 不太一样。它原生支持 Skills 目录机制.claude/skills/下的每个技能包有自己的SKILL.mdAgent 可以根据任务自动选择是否加载某个技能。这比把全部指令塞进 CLAUDE.md 要优雅得多。v0.1.5 对 Claude Code 的适配核心是把上面那套rules.yaml翻译成 Claude Code 的 Skills 元信息格式。一个标准的技能包在.claude/skills/里长这样.claude/skills/ ├── api-standards/ │ ├── SKILL.md │ ├── metadata.yaml │ └── examples/ └── self-test-checklist/ ├── SKILL.md ├── metadata.yaml └── examples/metadata.yaml里写了技能的描述和触发关键词Claude Code 会依据这段描述来决定何时加载技能。描述里必须写清什么情况下用和什么情况下别用否则 Agent 容易在无关任务里也把技能拉出来。4.3 一套技能两份配置的做法同时维护 Codex 和 Claude Code 两套配置听起来维护成本翻倍但 v0.1.5 的实际做法是源头只有一份其他全是生成的。具体流程在skills/目录里用统一格式维护技能内容SKILL.md rules.yaml运行scripts/context-build.py --target codex生成 Codex 的 AGENTS.md运行scripts/context-build.py --target claude生成.claude/skills/下的技能包。两份配置共享同一个内容源rules.yaml里的触发条件在生成时分别映射到两种机制。Codex 侧映射成 AGENTS.md 里的关键词索引Claude Code 侧映射成metadata.yaml里的 description。生成脚本我放在 CI 里跑每次技能内容有变更自动重新生成两份配置并提交到仓库。这样团队里用 Codex 的和用 Claude Code 的同事拿到的技能约束完全一致不会出现我用 Claude Code 改的接口格式和你用 Codex 改的对不上的尴尬。下表整理了 v0.1.5 在两种工具下的接入差异维度Codex 接入Claude Code 接入配置载体AGENTS.md 自定义命令.claude/skills/ 技能目录技能加载按索引语义匹配按 metadata 语义匹配阶段模板注入通过 AGENTS.md 索引引用通过 skills 目录轮询加载验证钩子自定义命令触发技能内嵌 checklist维护方式脚本生成脚本生成5. 实测三个月沉淀下来的坑5.1 上下文膨胀与技能文件太啰嗦v0.1.5 早期版本最大的败笔是技能文件写得像论文。比如 coding-style 技能我最初写了四千多字涵盖了命名、缩进、注释、异常处理、数据库访问……应有尽有。结果 Agent 加载这个技能后生成代码的风格确实符合规范但整个对话的上下文被占掉一大截后续修改时它反而记不住任务本身的需求了。后来我把每个技能的 SKILL.md 压到 300 到 800 字只保留规则 正反例 验收标准三块。缩进规则这种一句话能说清的绝不展开异常处理规范直接配一个好的写法/坏的写法对照示例示例比解释省 token 且效果好得多。压完以后上下文占用降了约四成任务完成质量反而提升了。这里有个反直觉的经验技能文件的核心价值不是教会 Agent 怎么做而是告诉它去哪查、查完怎么核对。细节留给人或者代码仓库里的既有模式去沉淀。5.2 双 Agent 行为差异导致的同一套技能两个结果这是最让我头疼的一个坑。同一套技能配置Codex 和 Claude Code 跑出来的结果经常不一样。Codex 倾向于严格遵守 AGENTS.md 里的步骤清单按部就班地走流程Claude Code 则更灵活经常跳过非强制的步骤直接跳到实现阶段。发现这个问题的方式很偶然——团队里两个同事用不同工具改同一个模块一个人交上来的代码带了详细的方案文档另一个人只改了代码没写方案。一查才发现Claude Code 把输出方案文档当成可选项跳过了。解决办法是在技能规则里增加强制级别字段requirements: - id: plan-doc action: mandatory check: 存在 plan/ 目录下的方案文档 - id: lint-pass action: mandatory check: lint 命令 exit code 0 - id: commit-prefix action: recommended note: 提交信息建议按约定前缀生成阶段模板时mandatory级别的条目会写到验收标准区块并明确标注缺少此项视为任务未完成recommended级别则写明在条件允许时执行未执行需在汇报中说明原因。加了这个区分之后双 Agent 的行为一致性明显提升。5.3 更新策略别让技能变成技术债技能库最隐蔽的成本不是创建而是维护。项目代码风格变了、依赖框架升级了、团队约定改了任何一个变化都可能导致技能内容过时。v0.1.5 里我踩过的具体坑是某个技能里写死了旧的 ORM 用法结果 Agent 每次改数据库相关代码都按旧规范来生成的代码直接编译不过。现在我的维护策略有三条每次技能使用后留反馈Agent 完成一个任务后在汇报里标注本次使用了哪些技能、哪些规则对结果无帮助。攒够反馈就删掉无用的规则每周做一次技能审计把技能内容里涉及 API 名、命令路径、目录结构的部分抽出来和当前仓库实际情况比对不一致的立即改技能变更走 PR 流程技能文件的修改不直接 push要像改代码一样经过 review。因为技能变更会同时影响 Codex 和 Claude Code 两份配置改错了等于让所有 Agent 同时犯错。这三条执行下来技能库从越用越脏变成了越用越精准。目前 v0.1.5 的 32 个技能里大约每个月会调整五六个但整体结构保持稳定。6. 适合谁不适合谁以及下一步想做的事先说结论这套 v0.1.5 的推理框架工作流最适合的是手里有一批模式固定、重复度高、修改频繁的代码任务的个人开发者或小团队。比如接口联调、Bug 修复、写测试、补文档这类任务技能驱动能明显减少你反复交代同样要求的次数。你的项目约定越清晰这套体系收益越大。不适合的场景我也踩过如果你主要用 Agent 做探索性的、一次性的研究任务或者代码仓库本身没什么约定可循技能库反而会变成束缚——Agent 花在匹配技能上的时间比实际干活还长性价比很低。另外如果团队里没人维护技能库那就不如别上这种重方案老老实实用 CLAUDE.md 写三条最硬的规矩更实际。v0.1.5 下一步我打算做两件事一是给context-build.py加一个技能使用统计输出跑完任务能自动记录每个技能被加载次数和引用次数帮我把没用的技能揪出来二是支持按项目目录做技能版本锁定让老项目继续用旧技能、新项目用新技能别让一次升级波及全部历史仓库。最后分享一个我自己的体会做这套东西最难的永远是克制。我一开始什么规范都想塞进去结果证明全是噪音。技能驱动真正的价值不是让 Agent 变聪明而是让你把项目里那些默认大家都知道的知识显性化——写进技能包的那一刻才是它们真正开始发挥作用的时候。