AI 研发工程化：规范、知识库与企业级选型

企业级代码仓库维护（含存量）· Spec 驱动 · Skill 库 · 代码知识图谱 · 经验演化 · evomap 解剖 · 企业落地选型

名词速查

首次阅读可跳过本表，直接看「场景问题」，遇到生词再回查。

本篇是工程化与可观测这一组名词的归属页。这一组词回答的是"怎么把 AI 写代码这件事变成可管的工程"——对应到你熟悉的东西就是：需求评审、SOP、代码索引、经验沉淀、APM、平台化。

篇幅较长，按 spec 拆两张表。

本篇自有名词

本篇引用的其他上下文名词

场景问题

从「AI 写代码」到「AI 做工程」之间的三个断层

Demo 里让模型写个函数很爽，但一放进真实工程就崩，断层集中在三处：

1. 意图漂移：需求只存在于聊天记录里，易失、不可评审。改了模型/换个 agent，上下文全丢，产出不可复现。
2. 流程不可复现：同一个人今天让 agent 先写测试、明天忘了，质量全看当次 prompt 心情，团队无法沉淀「我们就该这么做」。
3. 代码理解靠 grep：agent 面对百万行存量代码，只能反复 grep + read，既慢又不准，回答不了「改这个函数会炸哪些地方」这种结构性问题。

对应地，业界这两年沉淀出四个不同抽象层次的工程化实践——它们不是竞品，是可以叠起来用的一条栈：

实现方案

一、OpenSpec —— 规格驱动（Spec-Driven Development）

• 出处：Fission-AI，github.com/Fission-AI/OpenSpec。纯文件 + CLI，不需要 API key / MCP，本项目 openspec/ 目录用的就是它。
• 核心思想：不做「技术沙箱」约束，而是 用产物约束（constraint by artifact）——agent 必须先产出并对齐 spec，再照着 spec 执行。

变更生命周期（三段）：

目录结构与 delta 机制（关键设计）：

openspec/
├── specs/                 # 项目「真理源」——当前系统应该是什么样
│   └── <capability>/
├── changes/
│   └── <feature-name>/    # 一次变更，只存「相对增量 delta」
│       ├── proposal.md    # 为什么改
│       ├── design.md      # 技术方案
│       ├── tasks.md       # 实现清单（agent 逐条勾）
│       └── specs/         # 本次变更对真理源的 delta
└── changes/archive/
    └── 2026-07-13-<name>/ # 归档：delta 已 sync 进 specs

• 每次变更只写 delta（增量），不重写全量 spec；archive 时才把 delta 折叠进 specs/ 真理源，sync 可在不归档的情况下先同步。
• 这让 spec 始终是「活文档」：可追溯每次改了什么、为什么改，且能重新喂给任意 agent 复现。
• 对应本项目可用的 skill：openspec-propose / apply-change / archive-change / sync-specs（及 opsx:* 变体），1:1 映射上面三段。

二、Superpowers —— 方法论即 Skill 库

• 出处：Jesse Vincent（obra）/ Prime Radiant，github.com/obra/superpowers，通过插件市场安装（Claude Code / Cursor / Copilot CLI 等）。
• 定位：一整套「先想清楚再动手」的软件开发方法论，落在一组可组合的 skill 上。

强制的 7 段流水线：

① 头脑风暴(校验想法) → ② git worktree(隔离分支) → ③ 计划(拆成 2~5 分钟粒度任务)
→ ④ 实现(子 agent 审查) → ⑤ TDD(强制 RED-GREEN-REFACTOR) → ⑥ 代码评审(对齐 spec) → ⑦ 收尾合并

Skill 的实现机制（理解后面 evomap 对比的关键，也是 Anthropic Agent Skills 官方规范）：

• 每个 skill = 一个带 YAML frontmatter 的 SKILL.md + 可选脚本/资源目录：

---
name: brainstorming
description: 在动手前把模糊想法收敛成可执行方案；当用户说"我想做…"但需求不清时触发
---
# Brainstorming
（正文：步骤、检查清单、示例……命中后才加载）

• 渐进式披露三层（progressive disclosure）——这是 skill 能规模化而不撑爆上下文的核心：
  1. name + description 常驻系统提示，供模型判断「这个 skill 何时该用」；
  2. 命中后才加载 SKILL.md 正文；
  3. 需要时再加载 reference.md 等附件（因此可捆绑的上下文「近乎无限」）。
• 脚本作为工具执行：确定性强的部分写成脚本让 Claude 执行（而非读进上下文），保证可靠性与省 token。
• 组合 + 子 agent：高阶 skill 调用低阶 skill，用子 agent 委派离散步骤（如「让一个子 agent 专门做代码评审」）。

三、CodeGraph —— tree-sitter 代码知识图谱

• 出处：与本项目 codegraph_* 工具签名最吻合的是 colbymchenry/codegraph（工具名、.codegraph/codegraph.db、"只暴露 explore 保持 MCP 精简" 的设计都对得上）。
• 要解决的问题：让 agent 回答 grep 回答不了的结构性问题——「谁调用了 X」「改 Z 会炸哪些地方」。

四步流水线：

• 解析：tree-sitter 支持 30+ 语言，用语言特定 query 抽出节点（symbol）和边（edge）。
• 存储：本地 SQLite + FTS5 全文索引，符号查找亚毫秒级，完全离线无外部 API。
• 引用解析：把 调用→定义、导入→源、继承链连起来（还能识别 web 路由等框架模式）——这是纯文本 grep 做不到的。
• 自动同步：OS 原生文件监听 + 防抖（_500ms2s）增量重建，索引始终跟得上代码。

四、evomap / Evolver 深度解剖 —— 它到底是什么

打个比方：它想做的事，相当于给团队建一个自动生长的故障复盘库——每次踩坑后不用人写 wiki，系统自己把"这次为什么炸、下次怎么避"提炼成一条可检索的经验，下回遇到相似场景自动带出来。类比失效边界：人写的复盘过了审，语义明确、责任清楚；自动演化出的经验没有人审这一关——它可能沉淀下一条错误的教训，然后持续复用（错误固化），而且越用越"确信"。所以这类系统的成立条件不是"能不能自动提炼"，而是能不能审计、能不能回滚、能不能让一条经验失效。

这是本篇要重点"解剖 + 揭秘"的对象。先给一句最容易被营销话术掩盖的本质判断：

• 出处：EVOMAP PTE. LTD.（新加坡，© 2026）；开源引擎 Evolver（@evomap/evolver，github.com/EvoMap/evolver，早期 MIT→现 GPL-3.0）。背后论文 arXiv:2604.15097。
• 要解决的真问题：手改 prompt、堆 skill 文档，是稀疏、不稳定、无法审计、无法跨 agent 继承的经验载体。改了个 prompt 变好了，说不清好在哪、也没法安全回滚、更没法传给别的 agent。

数据模型：Gene / Capsule / EvolutionEvent（生物学包装下的朴素三件套）

剥掉生物学话术，就是"经验的三张表"：

再套一个 GDI（Genetic Desirability Index） 给资产排序：内在质量 35% + 使用指标 30% + 社交信号 20% + 新鲜度 15%——说白了就是个带权重的推荐排序分。

一个进化周期到底干了什么（4 步，全是确定性动作）

逐步拆解：

1. 扫日志：读 memory/ 里的运行历史，提取错误模式、成功率等 signals（这步就是日志分析）。
2. 选模板：Selector 从本地 .evolver/gep/genes.json / capsules.json 里匹配最合适的经验资产，输出可审计的选择决策 JSON。
3. 拼提示词：按 GEP 协议组装出一段严格约束的提示词，打到 stdout 就退出——独立模式下到此为止，什么都没改。
4. 记账：把这次 intent/mutation/outcome 追加进 events.jsonl 审计日志。

三条真正扎实的工程约束（这才是它值得学的地方）

营销词很虚，但底层几个约束确实是好工程：

• git 强依赖：必须在 git 仓运行，用 git 做回滚、算 blast radius、solidify 固化。非 git 目录直接报错退出——把"经验变更"纳入版本控制，这个直觉很对。
• validation 命令白名单（isValidationCommandAllowed）：Gene 的校验命令只允许 node/npm/npx 开头，禁止反引号/$(...)命令替换、禁止 ; & | > < shell 操作符、单命令 180s 超时、限定仓库根目录为工作目录——防任意命令执行，安全模型是认真做的。
• 稳定性优先熔断：近期错误率高时强制进入 repair 模式、暂停 innovate；单进程锁防 fork 炸弹；外部资产（A2A 拉来的 Gene）进隔离候选区，提升前必须人工 --validated 审查。

与宿主运行时的关系（"进化"发生在哪）

关键：所谓"自我进化"从来不是引擎自己动手，而是引擎产出指令、宿主/人执行、git 兜底回滚——它是"进化的编排者与账本"，不是"进化的执行者"。

EvoMap Hub 与 A2A：把经验做成网络（争议最大的一层）

• 可选连 EvoMap Hub，通过 A2A（agent-to-agent，HTTP+JSON）协议跨 agent 发布/拉取/继承 Gene——口号 "one agent learns, a million inherit"。
• 配套 skill2gep：把任意 Skill 蒸馏成 Gene/Capsule——即它把 Skill 当输入原料（所以下文说 Skill 是 Gene 的低阶形态）。
• 但 Hub 层堆了一大套重机制：Credits 代币经济、AI Council 自治治理（投票/否决）、Arena 竞技评分、Swarm 多 agent 协作、DID 身份 + reputation……这些离"帮企业维护代码仓库"已经很远，更像一个 to-C 的 agent 社交/激励网络。

为什么这么做

Skill 与 evomap 的本质区别

先给结论：二者不在同一抽象层，且 evomap 被明确定位成对 Skill 范式的「替代/超越」来打。

• Skill = 静态能力说明书：人写好的 markdown + 脚本，描述「遇到这类任务按这个流程做」。文档导向、靠人维护、用了也不会变。
• evomap = 演化式经验资产：从运行经验里自动提炼、可自我改进、可跨 agent 网络继承。

一句话记法：Skill 是「写死的招式」，Gene 是「打完架自己会长本事、还能传给别的 agent 的肌肉记忆」；而 Skill 是 Gene 的低阶形态。

⭐ 核心：企业级存量代码仓库怎么维护

企业最大的资产（也是最大的负债）是百万行存量代码。「让 AI 维护存量」和「让 AI 写新代码」是两个难度量级——新代码 agent 从零生成即可，存量代码 agent 首先得"读懂"它，尤其读懂"改一处会牵连哪些地方"。这一节把它拆成"三步走 + 三索引 + 选型 + 反模式"。

存量维护的三步闭环：定位 → 影响面 → 安全改

打个比方：这一整节就是你改存量时早已在做的依赖分析与影响面评估——动一个函数签名前，先用 IDE 的"查找所有引用"把调用方捞全，再判断哪些调用点会跟着炸，最后才动手并补测试。AI 的处境和你完全一样，区别只在于它没有 IDE，默认只能 grep。类比失效边界：IDE 的引用查找是编译器级精确的，查出来就是全部；这里的图谱是预先解析出来的静态快照——代码一改就过期，反射、动态分发、配置驱动的调用它建不出边。所以影响面清单只能提示风险，不能证明没有风险：图上干净不等于改了不炸，动态行为仍要靠测试与日志佐证。

真实场景：接到一个"给下单接口加个风控校验"的需求，面对百万行陌生代码，AI（和人）都要走这三步：

• ① 定位：模糊需求（"哪段做鉴权"）走语义向量；已知符号名走 SCIP 精确跳转。
• ② 影响面分析（最关键）：改一个函数/字段前，用 CodeGraph 的 callers/impact 逆向查出所有调用方、继承链、跨文件引用——这是纯 grep 永远做不到的，也是"AI 敢不敢改存量"的分水岭。
• ③ 安全改动：在影响面清单约束下改，配合 Skill 的 TDD 流水线补测试、CI 回归。
• ④ 沉淀：把"为什么这么改"写进 ADR / 经验库，下次同类改动直接复用。

三种互补索引（code 版 GraphRAG）

让 agent 真正「懂」存量，靠三种互补索引，实战里混合用：

三者各管一段，缺一不可：向量解决"从自然语言找到代码"（入口模糊），SCIP 解决"精确定位定义/引用"（点对点），结构图谱解决"这个改动的爆炸半径"（面）。只有结构图谱能回答影响面——所以它是存量维护的主干，另两者是辅助。

落地流程（推荐组合）：

选型决策：

• 中小仓 / 单语言 / 要快：直接上 CodeGraph（tree-sitter + SQLite，零基建、离线、亚毫秒）。本项目就是这个档位。
• 大型多仓 / 多语言 / 要精确跨仓跳转：Sourcegraph + SCIP/LSIF，编译期精确引用是它的护城河。
• 需求模糊、要"找一段做 X 的代码"：加语义向量层（code embedding，如 CodeBERT/嵌入模型 + Chroma/pgvector），但务必用结构图谱校准幻觉。
• 反模式：只做「全代码丢进向量库做 RAG」——代码的价值在结构关系（调用/依赖），纯向量丢掉了边，agent 会「看得懂片段、算不清影响面」。结构图谱是主干，向量是补充。

代码图谱能做什么：从 CodeGraph 到 Graphify

上面讲的三种索引里，结构图谱是存量维护的主干。它到底能做什么？以开源工具 Graphify（YC S26，tree-sitter + 知识图谱，非向量）为例，结构图谱的能力边界一目了然：

Graphify 相比 CodeGraph 的进阶：

• 零 LLM 依赖：代码解析纯 tree-sitter（确定性、离线、零 token 成本），只有 docs/PDF/images 的语义 pass 才调模型——代码图谱不需要 LLM，这是确定性的胜利。
• 边置信度：每条边带 EXTRACTED/INFERRED 标签，agent 可以区分"源码里写死的"和"推断出来的"——这对存量维护至关重要：改 EXTRACTED 边影响面确定，改 INFERRED 边需要人工确认。
• 社区发现自动切子系统：不用人手画边界，Leiden 算法自动发现模块聚类——对应到影响面分析，改一个 God node 波及多个社区 = 高风险改动。
• Benchmark：LOCOMO recall@10 = 0.497（mem0 仅 0.048），LongMemEval QA accuracy = 76%，graph build LLM credits = 0。

选型谱系更新：

CodeGraph 实战：从"找入口"到"查子图"的范式转变

上面讲的是结构图谱能做什么，现在来看实际怎么用。核心命题来自一个工程现实：

代码 Agent 真正卡住的地方，往往不是模型不会写代码，而是它不知道该先看哪里。

传统 Agent 面对陌生仓库的链路是：列目录 → 搜关键词 → 打开几个文件 → 猜入口点 → 发现不对 → 重复一轮。这个过程的根本问题是把结构性问题降级成了文本命中问题——"登录请求怎么写入数据库"需要的是路由→handler→service→repository→ORM 的关系链，不是 20 个包含 login 的文件。

CodeGraph 的四层建图链路：

Agent 工具选择表（给模型明确规则，否则它会退回 grep）：

核心原则：先结构，后细节——先用图查询锁定入口和链路，再按需读具体文件。这个顺序能显著减少 Agent 的无效探索（实测：~16% 成本节约、58% 工具调用减少、22% 速度提升）。

Resolution 层——代码图谱的真正难点：

AST 能告诉你"这里有个函数调用"，但很多工程语义不写在普通调用里。Resolution 层负责补全这些框架约定关系：

索引保鲜——不要让 Agent 信过期的图：

CodeGraph 用 FileWatcher + debounce + 增量同步解决这个问题。同步完成前，MCP 工具返回结果时带上 stale 提示，告诉 Agent 哪些文件刚改过、相关结论可能过期。这个设计比"假装图永远正确"更诚实——Agent 可以继续信任未变更文件的结构结论；对刚保存的文件，直接读取源码更稳。

MCP 接入的工程要点：

• 共享后台进程：Cursor、Claude Desktop、脚本工具连接同一个 codegraph serve --mcp 进程，避免每个客户端重复索引。
• Skill 固化分析流程：把"检查索引状态 → 必要时初始化 → 调用 context → 按结果补查 callers/impact → 固定结构输出"封成 Skill，让非代码专家也能问结构问题，Agent 也不容易一上来就全文搜索。

CodeGraph 的局限（不能盲信的边界）：

可复用组件的方法与选型

「可复用组件」在 AI 研发里有一条从轻到重的谱系，选型看确定性和复用边界：

选型心法：

• 确定性动作 → 写成 Tool/脚本，别让模型「每次重想」（既贵又不稳）。
• 判断 + 流程 → 写成 Skill，用渐进式披露，description 写清「何时触发」。
• 要跨系统/跨模型复用 → 包成 MCP Server，一次实现处处接（本项目的 CodeGraph、ruflo 都是 MCP）。
• 需要独立上下文的子任务 → 拆成 Subagent，避免污染主上下文。
• 反复踩同一个坑 → 沉淀成经验资产（记忆库/Gene），让下次自动规避。
• 黄金法则：能用确定性代码解决的，绝不留给模型即兴发挥；能沉淀成组件的，绝不散落在 prompt 里。

企业级工程规范全景：AI 只是新增的一环

打个比方：这一节讲的就是你 CI 里那一长串卡点——lint → 单测 → 覆盖率门槛 → 依赖扫描 → 人工 review → 灰度发布。AI 产出没有专属通道，它和人写的代码排同一条队、过同一道闸。类比失效边界：这套门禁是为人的失误设计的——人会写错边界条件、会漏加锁，但不会凭空发明一个不存在的第三方库。AI 会：它引入的依赖包名看着合理却根本不存在，而 SCA 查不到（库里没这个包就无从比对）。更麻烦的是第 7 维——门禁拦得住代码，拦不住"团队对系统的共享理解在悄悄流失"，而那部分摩擦正是 AI 消除掉的。

前面几节聚焦"AI 相关"的工程化，但企业级仓库的规范是一整套在 AI 之前就存在、AI 之后必须适配的护栏体系。把它们拉齐成一张清单——这也是"AI 生成的代码凭什么敢合进主干"的答案：因为它和人写的代码走同一套门禁。

1. 编码规范与静态门禁（左移的第一道闸）

心法：把"人评审时会说的话"尽量固化成机器可执行的 lint/类型规则——AI 生成量大，纯人肉 review 顶不住，必须让机器先过一遍。

2. 分支策略与提交规范

• 分支模型：trunk-based（主干开发 + 短命特性分支 + feature flag，CI/CD 友好，主流推荐）vs git-flow（多长期分支，适合有明确发版周期的传统交付）。AI 生成的改动尤其适合 trunk-based——小步、频繁、快速合并，避免长命分支累积巨型 diff 难评审。
• Conventional Commits：feat: / fix: / docs: / refactor: 规范化提交信息 → 自动生成 CHANGELOG、自动推导语义化版本。让 AI 也按这个格式写 commit。
• CODEOWNERS：按目录指定负责人，PR 自动请求对应 owner 评审——AI 改到谁的地盘，谁必须 review，责任不因 AI 生成而消失。

3. 测试与质量门（AI 代码合入的硬闸）

4. 安全与供应链规范（AI 时代放大的风险面）

AI 会"自信地"引入有漏洞的依赖、写出注入风险的代码、甚至幻觉出不存在的包名（被攻击者抢注 = "slopsquatting"投毒）。必须补齐：

运行时命令守卫（agent 的最后一道安全网）

上面都是静态安全门（代码合入前），但 agent 在运行时执行的命令同样需要护栏——AI 偶尔会跑出 git reset --hard、rm -rf ./src、DROP TABLE users 这类不可逆的灾难命令。开源工具 dcg（Destructive Command Guard，Rust + SIMD，亚毫秒级）专门解决这个问题：

5. 文档与知识规范（把"为什么"沉淀下来）

• ADR（Architecture Decision Record）：每个重要技术决策记一条"背景→选项→决定→后果"，让半年后（或接手的 agent）知道为什么这么设计。这正是 OpenSpec 的 spec 和存量知识库里"人+agent 沉淀文档"那一层。
• README/贡献指南/CLAUDE.md：人看的贡献规范 + 给 agent 看的仓库约定（本项目的 CLAUDE.md 就把"结构问题用 CodeGraph、字面文本才用 grep"这类纪律写进去，让每个进来的 agent 自动遵守）。
• API/接口文档即代码：OpenAPI/protobuf 作真理源，文档从代码生成，杜绝文档漂移。

6. 发布与运维规范

• 语义化版本（SemVer） + 自动化 release（由 Conventional Commits 推导版本、生成 CHANGELOG）。
• 灰度发布 + 快速回滚：金丝雀/蓝绿，异常自动回滚——AI 改动上线尤其要有"一键退回"的底气。
• 全链路可观测 + 审计（见下文可观测三面）：AI 参与的每一步都要能追溯、能定责。

7. 协调与共识规范（AI 消除的摩擦，恰恰是团队理解的载体）

前面六维都是技术护栏，但企业级软件项目真正的瓶颈从来不是"个人写代码的速度"，而是团队对系统的共享理解能不能保持一致。Armin Ronacher 在 The Tower Keeps Rising 里用巴别塔做了一个精妙的类比：

They use it [brick] for a civilizational project: let us build us a city and a tower, whose top may reach unto heaven. … the people is one, and they have all one language, and now nothing will be restrained from them.

巴别塔的力量不在于砖头，在于协调——共享语言让个体工作能组合成无人独建的东西。上帝没有没收砖头或制砖技术，而是夺走了他们理解彼此的能力，工程随即停滞。

AI 时代的巴别塔困境：agent 消除了开发间的摩擦——以前改别人的存储层要读他的代码、问他问题、跟依赖方协调，这个过程慢，但慢里有一部分不是浪费，而是"你的理解变成我的、双方确认系统仍按共识运作"的过程。现在每个人都能让 agent 在自己不理解的角落做局部改动，改动合理、测试通过、解释按需生成，但没有人需要和彼此交流，也没有人被迫学习那部分曾经被迫学习的共享模型。

摩擦被消除后，必须人为补上"共识同步机制"：

落地实践：

• 强制架构决策对齐：涉及跨模块/跨团队接口改动，即使 agent 能一键完成，也必须走 OpenSpec spec 评审——不是为了拦改动，是为了让共识在改动落地前同步。
• 定期"系统漫步"（System Walkthrough）：团队定期一起走一遍系统架构（CodeGraph 可视化图就是好材料），确认每个人脑子里的模型仍然对齐——agent 不会替你做这件事，因为 agent 不需要理解整个系统也能改局部。
• PR 描述不只是给 reviewer 看的：写 PR 描述的过程本身是"强迫改动者用共享语言表达改动意图"——如果写不清楚，说明改动者自己也没真理解，这正是曾经会被摩擦暴露的盲区。
• Guardrails 不是效率敌人：dcg 拦 git reset --hard、CodeGraph 圈影响面、契约测试守接口——这些护栏人为重建了被 agent 消除的摩擦，而那部分摩擦是共识的载体。

为什么别的选择不行

🔍 揭秘：evomap 在生产环境到底有没有实际价值

这是最该冷静回答的问题。结论先行——把它拆成三层看，价值从高到低急剧衰减：

① 范式层：真价值，值得学。 它踩中的问题是真的——skill/prompt 靠人手写、不自我改进、经验无法跨 agent 沉淀。「把 agent 经验做成版本化、可审计、可回滚、可继承的资产」是确定性方向。"经验编译成紧凑表示而非长文档"在信息论上也站得住（文档是稀疏、不稳定的控制信号）。git 当审计/回滚底座的工程直觉扎实。这一层无论你用不用它的产品，思路都该吸收。

② 引擎层：有限价值，看清它只是个 prompt 编排器。 Evolver 本身不神奇——扫日志、选模板、拼提示词、记账，外加一套还算认真的 validation 白名单和稳定性熔断。它的实际产出是"更结构化的提示词 + 一本经验账本"，不是"自动变强的代码"。 单机或小团队内，如果你本来就在手动攒 prompt 经验，用它做个规范化账本边际有用；但别指望它"自己把系统进化好"——真正的改动还是宿主/人做，它只是把经验组织得更规整。

③ 网络层：企业红线，生产不能碰。 Hub/A2A/Credits/AI Council/Swarm 这一整套，对企业是纯负债：

企业级落地：为什么不能直接接公共网络

evomap 式「连公共 Hub、一个学百万继承」在 to-C 玩得转，在企业里是红线。企业级形态应该是自建「经验资产层」，而非接入外部网络：

各方案不适用场景（避免误用）

• OpenSpec 不适合：一次性脚本、探索性 spike——写 spec 的开销 > 收益。它是给「要维护、要多人协作、要复现」的正式变更用的。
• 纯语义向量做代码库不适合：结构性问题（影响面分析）——丢了调用边，必炸。
• evomap 自动演化不适合：强合规/高风险域（金融交易、医疗）——「自我改进」和「可审计冻结」天然冲突。
• Skill 堆太多不适合：description 写不清「何时触发」时，模型会选错 skill，反而不如不加。

沉淀结论

企业级 AI 研发平台参考架构

┌─ 意图层  OpenSpec 式 spec 驱动     需求→proposal/specs/design/tasks，评审左移
├─ 方法层  私有 Skill 库             团队标准流程，渐进式披露 + 权限/worktree 隔离
├─ 理解层  CodeGraph + 向量 + SCIP   存量代码三索引混合，MCP 统一暴露
└─ 经验层  自研经验资产（非公共网络）  从 CI/PR/事故沉淀，人工闸门 + git 回滚 + 度量闭环
                    ↑ 全链路 Trace（OpenTelemetry）串起可观测与审计

• 今天就能进企业：OpenSpec / Superpowers-Skill / CodeGraph（成熟、开源、可私有化）。
• 蓝图先学后建：evomap 提供的「经验演化层」思想值得研究，但企业应自研而非依赖它的网络。

基建全景视野：控制面 / 数据面 / 可观测面

上面那张四层栈是「用什么」，真正做平台还要回答「底座有哪些」。借用云原生的分面思路，AI 研发基建可拆成三个面——这是评估自研平台成熟度的骨架：

Agent 平台化的组织与度量

上面那张三面表是技术视角的全景。但一个真实问题是：三面不是一次建成的，而且建到什么程度算够，取决于组织规模而非技术理想。这一节补两件工程之外的事——什么时候该从工具走向平台，以及AI 产出怎么被算清楚。

三级台阶与各自的进入判据

三条注意：

• 不要跳级。没经过②直接建③，会建出一个没人用的平台——因为你还不知道该固化哪些流程。
• 判据是"痛点出现"而非"规模达到"。20 人团队若各自独立项目、无共享代码，停在②完全合理。
• ③ 的成立前提是有人专职维护。兼职维护的平台会在第一次模型 API 变更时腐化，然后所有人绕过它——比没有平台更糟，因为它还在消耗信任。

AI 产出的三个可算度量

「AI 提效 30%」这类数字在多数团队是拍的。三个能真正算出来的口径：

三个一起看才有意义：单看采纳率会激励"生成能被合并的琐碎代码"；采纳率 + 返工率能识别"合了但一直在改"；再加事故归因才能回答"这些改动有没有在生产上咬人"。

与游戏研发周期的接口

本篇讲的是代码侧的工程化——它对应游戏研发周期里「内容生产阶段的程序侧」这一格。同一套四层栈（意图/方法/理解/经验）在其他阶段并不适用：QA 阶段要的是可复现的断言体系、上线运营要的是持续观察与崩溃恢复、在线反外挂根本不该用 LLM。

完整的阶段划分、每阶段引入的新问题，以及后台侧四个扎穿点（AI 巡检 / 自动化测试 / 反外挂 / 客服 Agent），见 AI 与游戏研发周期。那篇的判据可以直接借来用在这里：上任何一个 AI 研发工具前，先问「它的正确与否有没有可标注的人工基线」——代码侧的基线恰好最清晰（测试过不过、PR 合不合），这也是研发工程化比内容生产更容易见效的结构性原因。

未来可观测方向（值得关注）

AI 可观测和传统 APM 有两处根本不同，决定了它是一个正在成形的新品类：

1. 作用域从「请求级」变「轨迹级」：传统 APM 一个 span 对应一次请求；agent 是多步轨迹（plan→tool→observe→reflect），要观测的是整条 trajectory + session，还有子 agent、工具调用、记忆读写的父子关系。
2. 判定从「确定性」变「概率性」：接口对错是二值的；LLM 输出「对不对」要靠 eval（离线回归 + 在线 LLM-as-judge），所以 eval 与 observability 正在合并成一个东西——这已是标配而非差异点。

打个比方：AI 工程的可复现与可观测，就是你做可复现构建 + 发布单那一套——上线时记清 commit sha、依赖锁文件、镜像 digest、配置版本，半年后照同一份清单重建，产物应该对得上（对应 prompt 版本、模型 ID、数据集哈希、随机种子、评测集）；OpenTelemetry GenAI 语义约定就是行业统一的那张"发布单模板"，把 invoke_agent / execute_tool / chat / search_memory 各摊成一列。类比失效边界：可复现构建之所以成立，是因为你能把每一项依赖钉死——lock 文件锁版本、镜像锁 digest，锁住了就不会变；而 AI 系统里基座模型与 API 会静默升级（供应商改权重、改路由、换 tokenizer），这一项你根本拿不到 digest、也锁不住，同一份 prompt 半年后返回可能完全不同、评测分悄然漂移。所以这里的"可复现"只能做到可比对、不可锁定：除了版本化模型精确版本号、温度/种子、system prompt、评测集快照、embedding 模型，还必须定期用固定 Golden Set 回归——靠持续测量去发现环境变了，而不是靠锁去阻止它变。

① OpenTelemetry GenAI 语义约定（最该追的标准）

这是当前唯一在往「跨框架统一标准」走的努力，OTel 已把它拆到独立仓库 open-telemetry/semantic-conventions-genai：

• span 操作类型：chat / embeddings / execute_tool / invoke_agent / plan / create_memory / search_memory…（覆盖 agent、工具、记忆）。
• 关键属性：gen_ai.provider.name（原 gen_ai.system）、gen_ai.request.model/.temperature、gen_ai.usage.input_tokens/.output_tokens/.cache_read.input_tokens/.reasoning.output_tokens、gen_ai.tool.name/.call.arguments/.result。
• 指标：TTFT(gen_ai.server.time_to_first_token)、逐 token 时延、invoke_agent.duration、execute_tool.duration。
• 已有 MCP 约定（mcp.md）：instrument tools/call、client/server span 与 session 指标。

② Agent 专属可观测维度

③ 工具生态（按开源/OTel 原生/是否 eval+obs 一体）

选型心法：要私有化/省钱 → Langfuse 或 Phoenix（开源+OTel 原生）；已重度用 Datadog → 直接开 LLM Observability 模块；深绑 LangChain → LangSmith。避免自研全套——这个赛道成熟度已够高。

④ 2026 前沿（watch，尚未落定）

1. 「Agent observability」成独立品类 —— OTel 已发布专门的 agent 可观测约定（对齐 Google AI-agent 白皮书），目标是 CrewAI/AutoGen/LangGraph 通用。追踪它从 Development → stable 的进度，是这块最重要的信号。
2. eval 驱动 / 闭环自愈 —— 遥测直接反哺 agent 改进（自动检测→诊断→修复重复出现的 trace 问题）。这与前面 evomap 的「经验演化层」是同一件事的两个入口：可观测面产出的失败轨迹，正是经验层要沉淀的原料。（注：营销超前于成熟实践，谨慎。）
3. MCP 可观测 —— tools/call 级埋点已有早期约定，随 MCP 生态铺开会快速演进。
4. 多 agent 与记忆/上下文可观测 —— 多 agent 协调、记忆读写的可观测仍是公认未解的缺口，属于「值得盯、还没方案」。

技术选型 / 面试问答清单

规范化实践

• Q：OpenSpec 靠什么约束 agent？ A：不是技术沙箱，是「产物约束」——必须先产出可评审的 proposal/specs/design/tasks 并对齐，再照 tasks 逐条执行；delta 归档时折叠进真理源 spec，评审左移。
• Q：Skill 为什么能规模化不撑爆上下文？ A：渐进式披露三层——name+description 常驻判断何时用、命中才加载正文、需要才加载附件；确定性部分写成脚本让模型执行而非读入。
• Q：CodeGraph 比 grep 强在哪？ A：它是 tree-sitter 全 AST 解析出的符号+边的图谱，能答「谁调谁、改了炸哪」这类结构问题；grep 只能匹配字面文本。

Skill vs evomap

• Q：Skill 和 evomap 本质区别？ A：Skill 是人写的静态说明书（文档导向、不自我改进）；evomap 是 agent 从运行经验自动演化的经验基因（可自我改进、可跨 agent 网络继承），且用 skill2gep 把 Skill 当输入蒸馏成 Gene。
• Q：evomap/evolver 本质是什么？ A：是提示词生成器 + 经验资产版本化账本，不是能自己改代码的 AI。一个周期只做四件确定性动作：扫 memory 日志→从本地 GEP 库选 Gene/Capsule 模板→拼出受协议约束的提示词打到 stdout→追加 EvolutionEvent 审计；改不改代码由宿主运行时或人决定，git 兜底回滚。数据模型 Gene（策略模板）/Capsule（验证过的具体修复含 diff）/EvolutionEvent（审计日志）就是"经验的三张表"。
• Q：evomap 值得上生产吗？ A：分三层——范式层（经验→可审计资产→可继承）真价值值得学并自建；引擎层（prompt 编排器 + git 审计）单机/小团队有限有用但别神化；网络层（Hub/A2A/Credits/Council）是企业红线（数据主权/审计定责/错误经验放大/许可证与锁定风险）生产禁用。结论：学范式、自建经验资产层、坚决不接公共网络。

存量代码 & 组件复用

• Q：百万行存量代码怎么让 agent 读懂/维护？ A：三步闭环——定位（向量找模糊意图/SCIP 精确跳转）→ 影响面分析（CodeGraph callers/impact 查爆炸半径，这步最关键）→ 安全改动（TDD+CI 回归）→ 沉淀 ADR。索引用三种混合：结构图谱（主干）+ 精确引用 + 语义向量；纯向量丢结构边是反模式。
• Q：可复用组件怎么选型？ A：按确定性和复用边界分层——确定性动作→Tool/脚本、判断流程→Skill、跨系统→MCP Server、独立子任务→Subagent、跨任务经验→记忆/Gene；能用确定性代码解决的绝不留给模型即兴。

企业级工程规范

• Q：AI 生成的代码凭什么敢合进主干？ A：因为它和人写的代码走同一套、甚至更严的门禁——formatter/lint/类型检查左移拦风格与幻觉类型错误、单测+diff 覆盖率门、SAST/SCA/密钥扫描、CODEOWNERS 强制对应 owner 评审、CI 回归覆盖 CodeGraph 圈定的影响面。AI 代码能绕过门禁直接合入不是效率是定时炸弹。
• Q：AI 时代工程规范有哪些新增/放大的风险点？ A：① 幻觉包名被投毒（slopsquatting）→ lockfile + 私有 registry 白名单 + 依赖存在性校验；② AI 复制带漏洞的训练样本 → SAST 走更严的门；③ 生成量大人肉 review 顶不住 → 尽量把评审意见固化成机器可执行的 lint/类型规则；④ 每步 AI 动作要能追溯定责 → 全链路 Trace + 审计。
• Q：企业级工程规范全景有哪几段？ A：开发期（lint/format/静态分析/分支策略）→ 提交评审期（Conventional Commits/CODEOWNERS/pre-commit）→ CI 门禁（测试+覆盖率/SAST/SCA/可复现构建）→ 发布运维期（SemVer/灰度回滚/可观测审计），事故复盘 ADR 回流开发期形成闭环。第 7 维是协调与共识——AI 消除了开发间摩擦，而那些摩擦恰恰是共享理解的载体。
• Q：结构图谱（CodeGraph/Graphify）到底能做什么？ A：跨文件边解析（calls/imports/inherits）、最短路径查询（A→B 经几跳）、God node 检测（系统瓶颈）、社区发现（Leiden 自动切子系统）、边置信度标注（EXTRACTED 源码显式 vs INFERRED 推断）。这些全是 grep 和向量原理上做不到的——grep 只匹配字面文本，向量丢结构边。Graphify 进一步做到零 LLM 依赖（纯 tree-sitter）+ 边置信度，LOCOMO recall@10 = 0.497 远超 mem0 的 0.048。
• Q：agent 运行时安全怎么管？ A：静态安全门（SAST/SCA/密钥扫描）管代码合入前，运行时命令守卫（dcg）管命令执行前——dcg 用 50+ 安全 pack 拦截 git reset --hard/rm -rf/DROP TABLE 等不可逆命令，支持 agent 信任等级（不同 agent 配不同策略）、heredoc 内嵌脚本扫描、上下文感知（不拦 grep "rm -rf" 只拦 rm -rf /）。企业级安全 = 左移静态门 + 运行时守卫 + 审计追溯三层。
• Q：AI 消除摩擦后团队共识怎么维持？ A：Armin Ronacher 的巴别塔类比——agent 让每个人都能在自己不理解的角落做局部改动，测试通过、解释按需生成，但没人需要交流，共享理解悄然坍塌而工程仍能继续（塔不倒只是升高）。替代机制：CodeGraph 影响面分析 + ADR 强制记录"为什么" + OpenSpec spec 评审同步共识 + 定期"系统漫步"对齐架构模型 + 保留人审不替代决策。护栏不是效率敌人，是人为重建被 agent 消除的摩擦——而那部分摩擦是共识的载体。

基建与可观测

• Q：AI 研发基建有哪几个面？ A：控制面（spec/skill/MCP 注册 + 护栏 + 租户隔离，管规则）、数据面（模型网关 + 知识库 + 经验库 + 语义缓存，管知识与执行）、可观测面（trace/eval/成本/审计，管度量与反馈），CI/CD 横切串成闭环；只建数据面就上线是 Demo 能跑生产就崩的根因。
• Q：AI 可观测和传统 APM 有什么不同？ A：作用域从请求级变轨迹级（观测整条 plan→act→reflect + session、子 agent、工具调用、记忆读写）；判定从确定性变概率性，靠 eval（离线回归 + 在线 LLM-as-judge），所以 eval 与 observability 正合并。
• Q：AI 可观测最该追的标准？ A：OpenTelemetry GenAI 语义约定（gen_ai.*，含 invoke_agent/execute_tool/mcp span、TTFT/token 指标），已拆到独立仓库但仍是 Development（命名改过 gen_ai.system→gen_ai.provider.name）；现在就该按它埋点、接开源后端（Langfuse/Phoenix），闭环自愈是下一阶段。

记忆口诀

• 四层栈：意图层 OpenSpec（spec 固化需求）/ 方法层 Skill（流程固化+渐进披露）/ 理解层 CodeGraph（结构图谱）/ 经验层 evomap（经验演化）
• 三索引：结构图谱（主干·影响面）/ 精确引用 SCIP（点对点跳转）/ 语义向量（模糊意图·有幻觉）
• 三基建面：控制面（规则编排）/ 数据面（知识执行）/ 可观测面（度量反馈）·CI/CD 横切串闭环
• 五道红线：私有化 / 审计回滚 / 人工闸门 / 权限隔离 / 度量闭环——evomap 学范式、自建资产层、不接公共网络

内容来源

综合整理自各项目官方仓库/站点（2026-07 核实；生态更新快，请以官方为准）：

• OpenSpec — github.com/Fission-AI/OpenSpec · openspec.dev
• Superpowers — github.com/obra/superpowers（Jesse Vincent / Prime Radiant）
• Anthropic Agent Skills — 官方工程博客《Equipping agents for the real world with Agent Skills》
• CodeGraph — colbymchenry/codegraph（与本项目 codegraph_* 工具签名吻合）；实战分析参考 CodeGraph 代码图谱实战（2026-06，含四层建图链路/工具选择表/Resolution框架语义补全/索引保鲜/MCP接入工程要点）
• evomap / Evolver — github.com/EvoMap/evolver · evomap.ai · arXiv:2604.15097 · EvoMap/skill2gep（★ benchmark 与 star 数为项目方自述，未独立复核）
• Sourcegraph / SCIP / LSIF、LlamaIndex 等选型信息来自各自官方文档
• Graphify — github.com/Graphify-Labs/graphify（YC S26，tree-sitter 知识图谱，benchmark 见 BENCHMARKS.md）
• dcg (Destructive Command Guard) — github.com/Dicklesworthstone/destructive_command_guard（Rust + SIMD，50+ 安全 pack）
• Armin Ronacher — The Tower Keeps Rising（2026-07-13，AI 时代的巴别塔类比）

自测：合上资料能说清楚吗？

1. 「AI 会写代码」和「AI 能做工程」之间隔着哪几层规范化？分别解决什么断层？

2. 让 agent 读懂百万行存量代码靠三种索引混合，各管哪一段？为什么「全代码丢向量库做 RAG」是反模式？

3. 对比 Skill 与 evomap 的 Gene：二者在抽象层次、维护方式、是否自我改进上有何本质区别？关系是什么？

4. evomap/Evolver 在生产环境到底有没有价值？请分层判断。

5. 「AI 生成的代码凭什么敢合进主干」？企业级安全为什么是三层防线？