← 返回列表

xray -- Codified Context: Infrastructure for AI Agents in a Complex Codebase

Codified Context: Infrastructure for AI Agents in a Complex Codebase
Aristidis Vasilopoulos
Independent
2026-02-24
#paper #xray #AI-agents #context-engineering #developer-tools

挠痒

AI agents 在复杂代码库中缺少结构化的上下文基础设施——没有持久化的项目规约、领域知识和架构约束，agent 每次会话都是白纸状态，导致幻觉、违反项目惯例、重复犯错。论文在一个 108K 行 C# 分布式实时多人模拟项目上，用 283 sessions / 70 天的实践数据验证了三层上下文体系。

翻译

一句话

Before: agent 每次会话靠提问或猜测项目惯例。After: 三层上下文体系（T1 宪法级 / T2 专家级 / T3 冷知识库）让 agent 行为一致，且 prompt 开销仅 4.3%。

核心机制

              Human Prompt
                   |
                   v
            +-------------+
            |   SESSION    |
            |              |
            | T1 Constit. <== ALWAYS (660 ln, rules+triggers)
            |      |       |
            |  trigger     |
            |      |       |
            | T2 Agents   <== PER-TASK (19 specialists, 65% domain knowledge)
            |      |       |
            |  MCP query   |
            |      |       |
            | T3 Cold KB  <== ON-DEMAND (34 specs, 1478 calls/218 sessions)
            |              |
            +------+-------+
                   |
                   v
                Result

核喻：公司新员工入职。 T1 是员工手册——所有人必读的公司宪法（代码规范、安全红线、触发词），660 行，每次会话自动加载，O(1)。T2 是老师傅带教——19 个专家 agent，按任务类型触发，承载 65% 的领域知识（"这个模块的数据流怎么走""网络同步用什么模式"）。T3 是资料室——34 份技术文档，通过 MCP 按需检索，70 天里被调用 1478 次。新人（agent）不用每次从零摸索，公司知识已经铺好了路。

关键概念

上下文工程 vs 提示工程： 提示工程关注单次对话怎么措辞。上下文工程关注跨会话的知识基础设施——哪些知识永远在场（T1），哪些按需加载（T2/T3），怎么组织让 agent 行为稳定。类比：提示工程是写好一封邮件，上下文工程是建好整个邮件系统。

Napkin Sketch

Agent_Consistency = f(T1_hot, T2_specialist, T3_cold)

T1: ~660 lines, always-on    → O(1) 加载
T2: 19 agents, per-task      → O(trigger_match)
T3: 34 docs, on-demand       → O(MCP_retrieval)

Knowledge : Code = 26K : 108K = 24.2%
Meta overhead = 4.3% of prompts

一句话核心位移：从"agent 靠猜"到"agent 有基础设施"，知识代码比 24.2% 是这个位移的量化锚点。

洞见

哦，原来……上下文不是 prompt 的附属品，而是跟代码同等地位的基础设施——"知识代码比 24.2%"说明你的 AI 系统有四分之一是用来让 agent 理解系统的。

提示工程的主流思路是"怎么写好这次 prompt"，隐含假设是知识存在 LLM 权重里，prompt 只是激活它。这篇论文颠覆了这个假设：复杂领域知识（架构约束、项目惯例、领域术语）根本没在 LLM 权重里，必须显式编码成持久化基础设施。之所以没人把它当"基础设施"对待，是因为传统软件工程里没有这个概念——代码是代码，文档是文档，没有"让机器理解代码库的专用知识层"这种东西。

这个洞见的实际意义是：上下文工程是软件工程的新子领域，跟数据库设计、API 设计一样需要专业投入。知识代码比 24.2% 是行业首个量化基准，说明这不是可选项而是必要投资——省掉它，agent 的行为就是随机的。

博导审稿

有意思的实践报告——单项目 N=1，但 283 sessions、70 天的纵深数据让它不是玩具。知识代码比 24.2% 和 prompt 开销 4.3% 是有用的工程基准，给后来者一个参照系。不过缺泛化验证：一个 C# 游戏项目的数字能不能迁移到 Python 微服务或 Rust 编译器？三层划分的边界（什么该 T1 什么该 T2）也缺原则性指导。判决：weak accept——有趣的实践报告，不是研究贡献，但数据扎实、框架清晰。

接线

迁移：论文的三层触发机制（T1 always-on → T2 per-task trigger → T3 on-demand MCP）可以作为 PAI skill 体系的优化蓝图——当前 CLAUDE.md 承担了太多 T2 级别的内容，可以按照"触发频率 × 领域专精度"矩阵，把高频通用知识留 T1，把领域专精知识迁移到 T2 specialist agents，把低频冷知识推到 OpenViking T3。论文给出了 4.3% prompt 开销这个目标基准。

反转：我一直认为 PAI 的 CLAUDE.md 越全越好——越多背景 agent 越懂我。这篇论文揭示了这个直觉的代价：always-on 的 T1 内容每次都消耗 token，把不该在 T1 的内容塞进去是在为所有会话持续付出不必要的成本。"宪法应该精简"不是哲学立场，是工程效率问题——660 行的 T1 比 2000 行的 T1 更好，因为剩下的内容在 T2/T3 按需触发时才花钱。

💬 评论