首页 / AI Native / Agent 工程体系

多仓库 Agent 开发:统一规范与能力沉淀方案

代码主要由 agent 开发时,仓库越来越多、项目越来越大,怎样让 agent 遵循统一规范、持续积累经验,并让新会话自动继承这些能力。

落地分享: AiInfra 知识库建设分享 (含 agent-kit 接入教学与 AiInfraKB 工作流讲解视频)

1. 一句话结论

核心是把规范和经验当成代码来管理。

所有规范和经验放在一个有版本号的知识仓库里,作为唯一来源。用同步工具生成各家 agent(Cursor、Claude Code、Codex 等)能读的格式。只有少量内容常驻上下文,其余等任务需要时再加载。能用机器检查的规则尽量写成 lint、hook 或 CI,不只写在文档里。每次任务结束都有一个“复盘 → 提炼 → 审核 → 合入”的流程,新会话靠读这个仓库自动继承能力。

2. 规模变大后的典型问题

在多仓库、多 agent 工具并用的环境里,下面这几个问题几乎一定会出现,而且项目越大越严重:

  1. 规则串到别的仓库:某个业务仓库的强约束(例如“先写测试,等人 review 后才能写实现”“用户可见改动必须更新手册”)被配置成了全局规则。agent 在其他仓库干活时也被它约束,而这些规则本来和那个仓库无关。
  2. 同一类技能散在多处:~/.claude/skills、~/.codex/skills、~/.agents/skills、~/.cursor/skills、各仓库的 .claude/skills 各存一份。没有唯一来源,就会互相冲突、过期、重复。
  3. 已经有好的做法,但没推广:
    • TensorRT-LLM 里 CLAUDE.md 只有一行 @AGENTS.md,一份内容同时给多种工具用。
    • 有的仓库要求“实验结论要回写到技能的 field notes 里,按症状索引”,这是一个闭环的学习机制。
    • 把开发指南放在代码旁边(例如 ATTENTION_DEVELOPER_GUIDE.md),并要求修改相关代码前必须先读。
    这三个就是下面方案的雏形,只是往往只有个别仓库在用。

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"]

5. 机制 2:渐进式加载(项目再大也不爆上下文)

上下文窗口是稀缺资源,规范越多越要控制常驻的部分。

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 知识的生命周期

8. 技能也要有测试

规范和技能本身也会出错、过期,所以给它们配回归测试:

9. 单个任务的标准工作流

  1. 接需求:加载 AGENTS.md 索引和命中的 rules / skills。
  2. 探索:读相关的 *_GUIDE.md;先找已有的实现,避免重复造轮子。
  3. 计划:列出可以验证的验收标准;有风险就先问。
  4. 测试:先写复现或验收测试。是否需要人工确认由仓库自己的规则决定,不做成全局规则。
  5. 实现:小步提交;hooks 自动格式化和检查。
  6. 验证:本地跑门禁;独立的评审 agent 按规范清单审 diff。
  7. 合入:PR 模板里有“本次是否产生可沉淀的经验”一栏。
  8. 复盘: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. 几个取舍建议