结论先行:全局配置要薄,流程知识要厚,事实记忆要外置。三者混在一个文件里,是 agent 配置最常见的反模式。

三层各自装什么

~/.zcode/AGENTS.md        ← 行为宪法:怎么干活(薄,常驻每个会话)
~/.zcode/skills/          ← 流程库:干某类活的步骤(厚,按需加载)
~/.zcode/cli/memories/    ← 记忆库:干过什么、结论是什么(外置,检索召回)

宪法层只放跨项目通用的工作方式与红线,几百 token 常驻。流程层放具体场景的执行步骤——代码评审 checklist、测试环境排障流程、造数操作手册——这些内容如果塞进全局,每轮对话都要付一遍 token 成本,而实际上十轮对话才用一次。记忆层放事实与结论:架构口径、踩坑根因、关键配置。

三层放错内容的症状各不相同。把流程塞进宪法层,症状是全局文件越写越长、会话启动成本逐月上涨;把项目事实塞进宪法层,症状是换一个仓库这些"常识"全变成噪声;把结论只写进对话不落记忆层,症状是三个月后同一个坑再踩一遍,还得从头排查。反模式的可怕之处在于每一种都"当时看起来挺合理"。

三层的输入来源也不同:宪法层的输入是复盘——每次被模型的某个行为刺到,先判断是不是通用问题,是才立规矩;skill 层的输入是重复——同一流程第三次手工执行才立项;记忆层的输入是结论——排查、决策、踩坑的收尾产物。来源分清楚,各层的增长节奏就健康:宪法层最慢、skill 层中等、记忆层随时,谁也不会突然膨胀挤压另外两层。

什么该放哪层:判断表

判断维度宪法层流程层(skill)记忆层
生效范围跨项目通用特定场景单项目事实
触发频率每轮都要管偶发场景整段用按需检索
内容性质约束与偏好步骤与决策树结论与口径
失效速度慢,季度审中,随平台升级快,随时更新
常驻成本每轮支付只付一行索引只付检索开销

拿不准时我用一道题裁决:这段内容十轮对话会用几次? 每轮都用,进宪法层;偶发用,进 skill;不主动用但检索时值钱,进记忆层。

量化依据

我调研过一套以精简著称的公开配置:35 个 skill 加起来才约 4400 token 常驻,靠的是每个 skill 只写索引、正文按需读。对比无差别把流程写满全局的方案,同样的知识量常驻成本差一个数量级。“薄全局 + 厚 skill"不是审美偏好,是 token 经济学的必然。

算一笔假设账更直观:一个千余字的排障流程写进全局,按每轮对话都带着它算,一天几十轮对话就是几万字级的重复携带;拆成 skill 后,常驻成本只剩一行"何时用我”,正文只在真正排障的那一两轮被读入。知识一点没少,租金刚好付在被使用的那部分上。

但薄索引不是免费的:skill 的头部索引本身也是常驻成本,库里每多一个条目,每次会话都多背一行。所以条目数要收敛——过时的 skill 直接删,同类的合并,索引行压到一句话。这套机制让常驻成本有上限,不随时间线性膨胀;放任条目增长的库,最后会把自己引以为傲的"薄"吃回去。

记忆层为什么必须外置

宪法管"应该怎么干",skill 管"这类活怎么干",记忆管"这里的事实是什么"。事实和约束有个本质区别:事实会过期,约束不会。项目口径改了、索引加了、配置挪了,记忆条目就失效;而"测试红着不许报完成"不会因为版本升级失效。两者放在一起管理,审查节奏完全对不上——所以记忆必须独立成层,条目带上时间与适用范围,允许被判定过时、被更新、被删除。

有人会问:为什么不在每次会话开头把记忆全量注入?短期能用,不可扩展。记忆条目按月增长,全量注入的成本跟着按月上涨,而且绝大多数条目和当前问题无关——为不到一成的命中率背全部条目的重量,正是这套架构要消灭的模式。检索召回的意义,就是把成本从"按存量收"改成"按命中收"。

skill 的索引和记忆的索引可以共用同一套哲学:一行钩子 + 按需展开正文。

# skill 索引行示例(SKILL.md 头部)
---
name: test-env-log-query
description: 测试环境服务日志检索
何时用我:需要查测试环境某服务日志、按关键字过滤报错时
---

分层的隐藏收益

三层各自独立演进:宪法季度审一次,skill 随项目长,记忆随时写。升级任何一层都不用重新审另外两层。如果把所有东西揉在一个大文件里,每次改动都要在脑子里全量回归一遍——改一行排障流程,得顺便确认没把红线改没;补一条项目事实,得确认没跟效率习惯打架。回归成本随文件变大超线性增长,最后变成没人敢动的化石文件。

还有一个隐性收益:三层是三种不同的文体。宪法写禁令与偏好,skill 写决策树,记忆写结论——混在一份文件里,文体会互相污染,宪法里出现操作步骤、skill 里出现团队八卦;分开后每种文体都能写到它最有效的形态。

第三层收益属于协作。多人共用同一套目录结构时,宪法层的改动走"提议—评审—生效"的流程,skill 和记忆可以各自维护自己的领域。分层等于给不同变更频率的内容配了不同的变更流程:高频内容走轻通道,低频内容走重通道,团队接手这套配置时,也不用从几百轮对话考古开始。

真实场景

我最早把测试环境排障的完整手册——日志路径、DB 连接方式、常见报错对照表——直接写进了全局宪法,一千多字。当时的想法是"这些内容天天用,常驻最省事"。两个月后发现两个问题:一是不排障的日子,这些内容纯属每轮白付的租金;二是手册越写越细,宪法层的红线反而被淹没,模型对"不装新依赖"这类禁令的遵守肉眼可见地变松——注意力是守恒的,流程细节挤占的正是约束的权重。拆分动作很简单:手册原样搬进 skill,宪法层只留一行指引。拆完的直观感受是上下文清爽了,排障质量没有下降——skill 正文按需读,该详细时照样详细。当时犹豫过要不要顺手把手册重写精简,最后决定先原样搬迁、验证分层有效后再优化内容,避免了两个变量混在一起。事后看,早拆比晚拆好,判断标准就是那道题:这段内容十轮对话用几次。还有个顺带收获:手册搬进 skill 后被迫补写了头部索引,“何时用我"逼着我把手册里隐含的适用边界写成明文——哪些场景该用、哪些不该用,写宪法的时候从没想过要交代。

检查清单

  • 全局宪法一个屏幕读完,不含具体场景的操作流程
  • 每段知识都有归属:宪法、skill 或记忆,没有第四种去处
  • skill 头部写清"何时用我”,索引行能独立触发正确召回
  • 记忆条目带时间与适用范围,可判定过时
  • 改任何一层,不需要回归审查另外两层
  • 用"十轮对话用几次"复检每一处放错位置的内容