多仓库 Agent 开发:统一规范与能力沉淀方案
代码主要由 agent 开发时,仓库越来越多、项目越来越大,怎样让 agent 遵循统一规范、持续积累经验,并让新会话自动继承这些能力。
落地分享:
AiInfra 知识库建设分享
(含 agent-kit 接入教学与 AiInfraKB 工作流讲解视频)
1. 一句话结论
核心是把规范和经验当成代码来管理。
所有规范和经验放在一个有版本号的知识仓库里,作为唯一来源。用同步工具生成各家 agent(Cursor、Claude Code、Codex 等)能读的格式。只有少量内容常驻上下文,其余等任务需要时再加载。能用机器检查的规则尽量写成 lint、hook 或 CI,不只写在文档里。每次任务结束都有一个“复盘 → 提炼 → 审核 → 合入”的流程,新会话靠读这个仓库自动继承能力。
2. 规模变大后的典型问题
在多仓库、多 agent 工具并用的环境里,下面这几个问题几乎一定会出现,而且项目越大越严重:
- 规则串到别的仓库:某个业务仓库的强约束(例如“先写测试,等人 review 后才能写实现”“用户可见改动必须更新手册”)被配置成了全局规则。agent 在其他仓库干活时也被它约束,而这些规则本来和那个仓库无关。
-
同一类技能散在多处:
~/.claude/skills、~/.codex/skills、~/.agents/skills、~/.cursor/skills、各仓库的.claude/skills各存一份。没有唯一来源,就会互相冲突、过期、重复。 -
已经有好的做法,但没推广:
- TensorRT-LLM 里
CLAUDE.md只有一行@AGENTS.md,一份内容同时给多种工具用。 - 有的仓库要求“实验结论要回写到技能的 field notes 里,按症状索引”,这是一个闭环的学习机制。
- 把开发指南放在代码旁边(例如
ATTENTION_DEVELOPER_GUIDE.md),并要求修改相关代码前必须先读。
- TensorRT-LLM 里
3. 总体架构:三层知识,一个来源
flowchart LR KR["知识仓库 agent-kit
唯一来源 · 有版本号
standards/ 组织级规范
profiles/ 技术栈规范包
skills/ 可复用技能
evals/ 技能回归测试"] KR -- "agentkit sync
钉住版本" --> R["各业务仓库
AGENTS.md 索引 · 按路径生效的 rules
仓库专属 skills · *_GUIDE.md"] KR -- sync --> U["用户全局
~/.cursor ~/.claude ~/.codex"] R --> T["任务层
plan · 会话记录 · 复盘"] U --> T T -- "经验候选" --> IN["inbox/
待整理的经验"] IN -- "审核 PR 合入" --> KR
| 层级 | 放什么 | 怎么加载 | 谁维护 |
|---|---|---|---|
| 组织层 | 通用工程规范、提交流程、安全红线、通用技能(调试、性能分析、代码评审) | 极少部分常驻,大部分按需加载 | 平台或架构小组 |
| 技术栈层(profile) | Python / C++ / CUDA / 前端各自的约定 | 仓库声明自己用哪些 profile 才会同步过去 | 各领域负责人 |
| 仓库层 | 架构说明、模块开发指南、仓库专属技能、常见坑 | 按 glob 匹配路径生效,或靠技能描述触发 | 仓库 owner |
| 任务层 | 计划、过程记录、复盘结果 | 当次会话使用 | agent 自动产生 |
关键原则:分层隔离。仓库专属的规则不允许出现在全局层。上面说的规则串到其他仓库的问题,就是因为违反了这一条。
4. 机制 1:分发(让每个会话自动拿到统一规范)
知识仓库的目录结构
agent-kit/
agent-kit/
standards/ # 组织级规范,每条都写明 why + BAD/GOOD 示例
profiles/
python.yaml # 引用哪些规则和技能
cuda-kernel.yaml
skills/<name>/SKILL.md # frontmatter 带 description、owner、last_verified
adapters/ # 生成各工具格式:Cursor .mdc / CLAUDE.md / AGENTS.md / Codex
evals/<skill>/ # 技能的回归任务
inbox/ # 新经验先落在这里,等审核
CHANGELOG.md
每个仓库只加一个声明文件
.agentkit.toml
version = "1.8.0" profiles = ["python", "cuda-kernel"] extra_skills = ["perf-analysis"]
-
同步方式:运行
agentkit sync,按声明生成.cursor/rules/、.claude/skills/、AGENTS.md里的通用段落,然后提交进仓库。不论用 Cursor、Claude Code 还是 Codex 打开,看到的内容都一样。生成的文件头部标明# generated by agentkit — do not edit。 -
CI 漂移检查:在 CI 里跑
agentkit sync --check,发现手工改了生成文件或版本落后就报警,升级走 PR。 - 用户全局目录也由同一个工具同步,不再手工往多个 skills 目录里各拷一份。
5. 机制 2:渐进式加载(项目再大也不爆上下文)
上下文窗口是稀缺资源,规范越多越要控制常驻的部分。
- 常驻部分要小:每个仓库常驻的内容(AGENTS.md 加上始终生效的规则)设一个 token 预算,例如 ≤ 2k tokens,CI 统计,超了就失败。AGENTS.md 只当索引,写清楚“做 X 之前先读 Y”。
- 规则按路径生效:例如
globs: kernels/**/*.cu的规则只在改这些文件时加载。 - 技能靠描述触发:技能的 description 写成“什么情况下用”,正文、脚本、参考资料等触发后才读。
- 开发指南放在代码旁:复杂模块放一份
*_DEVELOPER_GUIDE.md,在 AGENTS.md 里写“改动xxx/之前必须先读”。
6. 机制 3:规范靠机器强制,而不是靠 agent 自觉
文档里的规则 agent 会遗忘、会误读,机器检查不会。按可靠性从高到低排:
| 手段 | 适用场景 |
|---|---|
| CI 门禁(lint、类型检查、架构依赖检查、API 稳定性测试) | 可以静态判定的规则 |
| pre-commit 和 agent hooks(编辑后自动格式化,拦截危险命令) | 每次改动都要执行的规则 |
| 独立的评审 agent(按一份规范清单评审 diff) | 需要语义判断的规则 |
| rules 和 skills 文本 | 方法论、取舍、背景知识 |
升级梯度:一条规则如果在文本层面反复被违反,就把它往上推一层,最终变成自动检查。
7. 能力沉淀闭环(新会话自动继承)
flowchart LR loop1["任务完成"] --> loop2["复盘 hook
自动提示复盘"] loop2 --> loop3["经验候选
写入 inbox"] loop3 --> loop4["定期整理 agent
去重、归类、找冲突"] loop4 --> loop5{"人工审核 PR"} loop5 -->|通过| loop6["按晋升梯度落地"] loop6 --> loop7["版本发布"] loop7 --> loop8["agentkit sync
同步到各仓库"] loop8 --> loop9["新会话自动加载"]
7.1 采集:靠流程自动触发,不靠 agent 想起来
用 agent 的 stop hook,在会话结束时要求输出一份结构化复盘:
inbox/2026-10-09-regspill.yaml
symptom: "kernel 寄存器溢出导致性能掉 30%" root_cause: "..." fix: "..." evidence: "ncu 数据 / 测试命令" scope: repo:xxx | profile:cuda-kernel | org confidence: measured | inferred
只记录“有证据、能复用”的经验。没有实测依据的推断要明确标注出来。
7.2 整理
用定时任务让一个整理 agent 每周处理 inbox:合并重复、找出和现有规范冲突的条目、给出晋升建议,提成 PR 等人审核。
7.3 晋升梯度:经验最终落在哪
单次观察 → field note(按症状索引,挂在对应技能下)
→ 出现 ≥3 次 / 跨仓库 → 写成技能正文的一节
→ 属于必须遵守的约束 → 写成 rule
→ 可以机器判定 → 写成 lint / hook / CI 检查
7.4 知识的生命周期
- 每条规则和技能都带
owner和last_verified字段,超过 N 个月没验证就标为过期,由整理 agent 提醒复核。 - 删除和废弃同样走 PR,避免知识只增不减。
- 每条规则必须带 BAD/GOOD 示例和 why,没有示例的规则 agent 很难用对。
8. 技能也要有测试
规范和技能本身也会出错、过期,所以给它们配回归测试:
evals/<skill>/下放 3 到 10 个“黄金任务”,包含输入、期望行为和检查脚本。- 修改技能或升级规范版本时,在 CI 里用固定模型重放这些任务,比较通过率、轮次和 token 消耗。
- 运营指标:每个任务的人工返工率、评审 agent 打回率、同类错误的复发次数、常驻上下文大小。复发次数下降,才说明沉淀真的生效了。
9. 单个任务的标准工作流
- 接需求:加载 AGENTS.md 索引和命中的 rules / skills。
- 探索:读相关的
*_GUIDE.md;先找已有的实现,避免重复造轮子。 - 计划:列出可以验证的验收标准;有风险就先问。
- 测试:先写复现或验收测试。是否需要人工确认由仓库自己的规则决定,不做成全局规则。
- 实现:小步提交;hooks 自动格式化和检查。
- 验证:本地跑门禁;独立的评审 agent 按规范清单审 diff。
- 合入:PR 模板里有“本次是否产生可沉淀的经验”一栏。
- 复盘:stop hook 产出经验候选,写入 inbox。
10. 落地路线
| 阶段 | 内容 | 验收 |
|---|---|---|
| 第 1–2 周 | 建 agent-kit 仓库,把散落在各处的 skills 和 rules 收拢、去重。修正规则串到别的仓库的问题。各仓库统一成 CLAUDE.md → @AGENTS.md 的写法 |
只剩一个来源;每个仓库只加载属于自己的规则 |
| 第 3–4 周 | 写 agentkit sync 和 adapters,加 .agentkit.toml,CI 加漂移检查和常驻 token 预算 |
新仓库接入 ≤ 10 分钟 |
| 第 2 个月 | 复盘 hook、inbox、整理 agent 定时跑、晋升梯度;把 field notes 机制推广到所有仓库 | 每周有经验 PR 合入 |
| 第 3 个月 | 给核心技能写 evals,加评审 agent,建指标看板 | 同类错误复发率开始下降 |
11. 几个取舍建议
- 不要一开始就追求完整:先把唯一来源和分层隔离做好,收益最大。复盘闭环第二步做,evals 最后做。
- 人工审核这一步不要省:让 agent 直接改知识库,很快会堆满低质量、互相矛盾的条目。整理可以交给 agent,合入必须由人决定。
- 合入要克制:每条新规则都会占所有 agent 的上下文,宁可少而准。