上下文工程即架构：650个文件之后的实践

我的CLAUDE.md最初只有50行。六个月后，它已经演变成一个横跨七层的650文件分布式架构。这一演变揭示了一个事实：上下文工程不是”文件更多的提示词工程”，而是一种面向特殊基底的软件架构——在这个基底上，记忆随着每个token的消耗而衰减。

上下文不是配置文件。它是决定AI代理能思考什么、记住什么、遗忘什么的架构基底。所有其他设计决策都从属于上下文。以下是六个月的Claude Code生产级上下文工程实践：架构设计、失败教训，以及最终存活下来的系统。

摘要

Böckeler在martinfowler.com上发表的上下文工程文章（2026）¹和Miessler的清晰思维框架²推进了这一讨论，但两者都低估了生产环境的实际需求。上下文工程要求设计这样一个系统：正确的指令在正确的时机到达代理，而错误的指令永远不会被加载。我的系统使用了9条规则、40个技能、19个代理、84个钩子和14个配置文件，分布在七层层级结构中。架构的精髓不在于文件本身，而在于哪些文件在何时加载，以及哪些内容被排除在外。

---

上下文不是一个文件

每周都会出现的”如何编写CLAUDE.md”教程文章忽略了关键问题。编写一个好的CLAUDE.md是必要的但不充分的，正如编写好的代码对于构建好的系统来说是必要但不充分的一样。架构是决定组件如何交互的结构。在代理系统中，上下文就是这个结构。

我的第一个CLAUDE.md是一个单体文件：200行内容涵盖了编码标准、项目结构、偏好设置、纠错规则、设计哲学、凭据管理和活跃项目状态。它工作了一个月。然后三个问题同时出现：

1. 文件增长超过300行后开始自相矛盾（规则A说”保持简洁”，规则B说”添加完善的错误处理”）
2. 项目A的上下文泄漏到了项目B（iOS专用规则污染了Web开发会话）
3. 代理花费token阅读与当前任务无关的指令

这些症状指向的是架构问题，而非文档问题：耦合、作用域泄漏和资源浪费。驱动软件架构决策的正是这些相同的力量。³

---

七层架构

经过六个月的重构，我的上下文系统最终稳定为七层层级结构。每一层都有明确的职责，并在特定时机加载：

层级	内容	加载时机	数量
1. 核心层	CLAUDE.md：设计哲学、活跃项目、纠错规则	每次会话启动	1个文件，205行
2. 规则层	领域特定约束（API设计、安全、测试、Git）	每次会话启动	9个文件
3. 技能层	可复用的知识模块，包含流程和示例	按需加载（手动调用或由钩子自动激活）	40个目录
4. 代理层	专用审查器/生成器规范	按需加载（通过Task工具）	19个文件
5. 钩子层	在生命周期事件中自动注入上下文	事件驱动（会话启动、提交前、工具调用后）	84个脚本
6. 配置层	数值参数（阈值、预算、限制）	被钩子和技能引用	14个JSON文件
7. 状态层	实时追踪（代理血统、置信度校准、成本）	被钩子引用	36个文件

关键洞察在于层级分离。规则在每次会话加载，因为它们具有普遍适用性。技能按需加载，因为它们是领域特定的。钩子在事件触发时执行，因为时机至关重要。如果在会话启动时加载全部650个文件，上下文窗口会在代理读到第一条用户消息之前就已耗尽。⁴

---

塑造架构的三次失败

失败1：单体式CLAUDE.md

我最初的CLAUDE.md包含了iOS规则、Web规则、API设计模式、Git规范、凭据管理和设计哲学原则——全部放在一个文件中。代理在每次会话都会读取全部内容，即使当前是一个永远不会涉及SwiftUI的Web项目。

代价： 无关上下文每次会话消耗约4,000个token。50次会话累计总共200,000个token花费在代理从未使用的指令上。

解决方案： 将领域特定内容提取到rules/文件中。rules/security.md每次会话加载（安全规则适用于所有场景）。rules/ios-security.md仅在会话涉及iOS项目时加载。上下文窗口管理一文记录了驱动这一决策的token经济学。

失败2：过时的技能

我创建了一个fastapi技能，其中的示例基于FastAPI 0.109。三个月后，项目已升级到使用不同模式的FastAPI 0.115。该技能悄无声息地传授着过时的惯例。代理生成的代码虽然可以运行，但与当前代码库的模式不一致。

代价： 一次45分钟的调试会话，追踪为什么一个新端点使用了与所有其他端点不同的依赖注入模式。这个模式来自过时的技能，而非代码库本身。

解决方案： 技能引用带版本号的文档，并包含”最后验证日期”。更重要的是，质量循环要求生成的代码匹配现有代码库模式——这是一种元认知检查，无论技能内容如何，都能捕捉到技能过时导致的偏差。

失败3：不同层级的规则冲突

CLAUDE.md说”优先选择简单方案”。一个技能说”添加完善的错误处理，包括重试逻辑和熔断器”。两者单独来看都是合理的。放在一起，它们产生了不一致的输出（有时极简，有时过度工程化），取决于代理在某一轮对话中更侧重哪条指令。

代价： 输出质量不可预测。同类型的任务在不同会话中产生不同的质量水平，使系统变得不可靠。

解决方案： 建立清晰的优先级层级。CLAUDE.md设定原则（”优先简洁”）。规则设定约束（”验证所有用户输入”）。技能设定流程（”以下是构建FastAPI端点的方法”）。当它们冲突时，更具体的层级胜出：技能的流程在其覆盖的特定任务上覆盖原则的指导。这种解析方式与编程语言处理作用域的方式一致：局部覆盖全局。⁵

---

上下文预算作为架构约束

上下文窗口并非无限。Claude的200K token上下文窗口⁶听起来很大，直到你衡量了什么在消耗它：

消耗来源	典型token数	占窗口百分比
系统提示 + CLAUDE.md + 规则	8,000-12,000	4-6%
对话历史	20,000-80,000	10-40%
文件读取（每个文件）	5,000-20,000	2.5-10%
工具输出（每次调用）	1,000-10,000	0.5-5%
技能/代理上下文（按需加载）	3,000-15,000	1.5-7.5%

Token消耗数据来自我在2025年8月至2026年2月间追踪的50次Claude Code会话。⁷ 一次90分钟的高强度会话仅通过正常的文件读取和工具交互就能耗尽整个窗口。上下文预算迫使我们做出架构权衡：

始终加载核心设计哲学、活跃纠错规则和安全规则。这三者成本低廉（占预算的4-6%），且具有普遍适用性。

按需加载技能、代理规范和参考文档。每项消耗窗口的5-15%，且仅适用于单一领域。仅在相关时加载，可以为实际工作保留预算。

永不加载过时的交接文档、弃用的配置或历史状态。每个过时文件都消耗预算却不改善输出。复利工程模式要求定期修剪不再值得其token成本的上下文。

上下文预算管理与数据库索引、缓存策略和传统软件中的内存管理所面临的权衡如出一辙。⁸ 约束条件不同（token而非字节），但架构原则完全一致。

---

多代理系统中的上下文传播

当主代理通过Task工具生成子代理时，选择传播哪些上下文决定了所有其他设计决策。我的多代理协商系统使用10个研究代理。每个代理需要足够的上下文来独立评估，但共享过多上下文会导致群体智能一文中记录的收敛问题：共享过多上下文的代理会产生相同的结论。

传播规则：

上下文类型	是否传播？	原因
核心设计哲学	是	保持代理间一致性
领域规则	是	共享质量标准
任务特定指令	是	实际工作内容
对话历史	否	独立性需要隔离
其他代理的发现	否（直到综合阶段）	防止过早收敛
技能流程	选择性传播	仅传播与代理角色相关的技能

Ralph架构解决了一个相关问题：跨时间（迭代）的上下文传播，而非跨代理（并行进程）的传播。两者共享同一原则：传播约束和原则，隔离实现细节。

---

衡量上下文质量

Token数量是一个代理指标。衡量上下文质量的真正标准是：代理是否在第一次尝试就产生正确的输出？

在追踪50次会话后，我识别出三个质量信号：

首次成功率。 代理的第一次响应不需要纠正的频率有多高？使用单体CLAUDE.md时，这个比率大约是60%。采用七层架构后，它上升到大约80%。改善来自移除无关上下文（减少干扰）和添加领域特定技能（增加相关知识）。⁹

纠正类型。 当代理确实需要纠正时，错误是事实性的（错误的API、错误的模式）还是判断性的（错误的方法、错误的优先级）？事实性错误表明缺少上下文。判断性错误表明上下文存在冲突或歧义。追踪纠正类型可以揭示哪一层需要改进。

任务完成时的上下文压力。 任务完成时还剩余多少上下文预算？如果任务完成不到一半时窗口已经使用了90%，说明上下文架构加载了过多无关内容。我的钩子系统包含一个上下文压力监控器，当使用率超过70%时会发出警告。

---

分布式架构模式

七层系统中没有任何东西是AI代理独有的。它镜像了成熟的软件模式：

软件模式	上下文等价物
环境变量	核心CLAUDE.md（始终加载，全局生效）
配置文件	规则（启动时加载，领域特定）
库/模块	技能（按需加载，自包含）
微服务	代理（隔离运行，通过协议通信）
事件处理器	钩子（由生命周期事件触发）
数据库	状态文件（持久化，可查询）
API契约	配置模式（共享数值参数）

这种类比并非隐喻。相同的力量（耦合、内聚、作用域、生命周期）驱动着相同的架构决策。¹⁰ 上下文工程就是面向一种特殊基底的软件工程——在这个基底上，”记忆”是一种稀缺的、可衰减的资源，而非一种丰富的、持久的资源。¹¹

---

核心要点

面向构建代理系统的工程师：

• 像设计软件架构一样设计上下文，而非像写文档。 什么在何时加载、什么覆盖什么、什么传播给子代理——这些决定了代理行为，远比任何单条指令更重要。请运用与代码相同的关注点分离原则。

• 按生命周期分离层级。 通用规则每次会话加载。领域特定知识按需加载。会话级状态保持临时性。将不同生命周期混合在一个文件中会产生软件架构存在的意义所在——解耦问题。

面向扩展AI工作流的团队：

• 将上下文窗口视为预算。 系统提示、文件读取和工具输出消耗着200K token的窗口。每条持久化指令都在与工作记忆竞争。衡量您加载的内容，修剪不值得其token成本的部分。

• 传播规则决定多代理质量。 子代理需要共享原则以保持一致性，需要隔离状态以保持独立性。传播过多上下文导致收敛。传播过少导致不连贯。

---

本文建立在上下文窗口管理（token经济学）和Ralph系统（文件系统记忆）的基础之上。Claude Code钩子系统实现了自动化层。关于代理协调模式，请参阅多代理协商和从群体智能到代理。

---