# 为 Coding Agent 设计项目知识层：User Harness 里被低估的一块
好的 AI coding 依赖 User Harness；其中被低估的一块是项目知识层——用最小负载、Lazy Loading 式按需外联，以及有界分类，把代码仓库升级为可控的项目知识库。
Agent 答非所问、改错文件、烧了一堆 token 却仍在原地打转——很多人第一反应是「模型不够强」或「这个 Agent 不行」。更常见的瓶颈其实在别处：它看到的上下文又多又散。
好的 AI coding，不只靠模型与 Agent Runtime，更靠你为它搭的 User Harness。Harness 里有一块常被低估、却直接决定准确度与成本的部件——项目知识层：知识从哪来、怎么放、怎么取。
User Harness 与项目知识层
一句话：Agent = Model + Harness。产品内置了一部分 harness（系统提示、检索、编排）；用户还能建设 outer harness——规则、权限、技能、验证回路，以及本文要谈的知识供给方式。
在 Harness Engineering 的框架里，知识层主要属于 Guides（前馈）：在 Agent 动手之前，提高一次做对的概率。Context 维度回答的是「Agent 知道什么」；项目知识层回答的是更上游的问题——什么值得让它知道，以及以什么形态进入上下文。
本文不展开完整五维 Harness，只深挖这一块：如何把「仓库里的东西」设计成 Agent 用得起、用得准的知识面。
从代码仓库到项目知识库
过去工程师心目中的仓库，大致是：代码 + 一点 README。人读代码、人记约定、人在脑里补上下文。
AI coding 时代，仓库不再只是代码仓。除了源码，至少还有：
- 规格：SDD 下的 Spec 是真相源之一（见 Spec 作为真相源），但规格只是知识的一类，不是全部
- 决策与领域知识：为什么这样设计、边界在哪、哪些坑不能再踩
- 索引与指针：去哪里找更细的材料，而不是把材料全文塞进常驻上下文
关键转变是：仓库从「存放代码的地方」，变成 知识编排面——本地保留可控、轻量、高信号的资产；易变或外部的知识，用策略在需要时再加载。不是把一切搬进 repo，而是让 repo 成为 Agent 的导航图。
原则一：最小负载（Minimize Load）
第一条原则很朴素：尽量少往 Agent 的注意力预算里塞东西。
Anthropic 把 context engineering 说成：找到最小的高信号 token 集合，去最大化期望结果。反过来，什么都塞进 CLAUDE.md / AGENTS.md / docs/，看起来「知识很全」，实际是在制造噪声——成本上升，命中率下降，路径也更散。
可收缩的存法包括：
| 存什么 | 不存什么 |
|---|---|
| 索引、目录、一句话摘要 | 可随时再读的长文全文 |
| 稳定约定与硬约束 | 每周都在变的接口细节 |
| 指向深层材料的指针 | 「以防万一」的百科全书 |
落地形态上，轻量 Repo Wiki 比「文档大锅炖」更接近这个原则。Andrej Karpathy 的 LLM Wiki 思路是：对来源做 ingest，提炼成可交叉引用的 markdown 页面，由 Agent 维护簿记，人负责选题与提问。国内如 Qoder 的 Repo Wiki 也是先从代码侧抽取结构化知识，再持续修订——提炼，而不是 dump。
与 progressive disclosure 同一逻辑：常驻层只做身份与目录（如精简的 CLAUDE.md），任务相关细节用 Skills / 按路径规则再展开。参见 Claude Code Skills 九型。
原则二：按需外联 = Lazy Loading
程序员都懂 Lazy Loading：默认不加载，用到再加载。项目知识层应当同一心态。
不是所有知识都适合进仓、更不适合进「每次会话必读」层。易变数据、外部系统状态、大文档库、票据与监控——更适合通过工具在需要时拉取。仓内保存的是加载策略：去哪里取、何时取、取什么粒度；而不是把载荷提前摊开在上下文里。
这与 Anthropic 说的 just-in-time retrieval 一致：Agent 手里拿着轻量标识（路径、查询、链接），运行时再用工具把数据拉进上下文。对外部平台而言，MCP 就是这类契约——但切记「千万不要贪多」：MCP Server 堆满，等于给 Lazy Loading 配了一堆永远在抢注意力的目录项。
一张简单对照：
| Eager（反模式） | Lazy（推荐） | |
|---|---|---|
| 仓内 | 粘贴全量外部文档 | 存 MCP/命令与查询约定 |
| 会话开始 | 预加载「可能有用」的一切 | 只带索引与硬约束 |
| 任务进行中 | 上下文早已胀满 | 按需 read / 调工具 |
最小负载管「常驻多重」；Lazy Loading管「其余何时出现」。两者一起，才构成可收缩的知识供给。
原则三：分类有界（Bounded Taxonomy）
有了收缩与懒加载，还缺一件事：路径怎么切。知识库若没有边界，Agent 检索时会觉得「什么都像相关」——再小的单页也会在错误的目录树里迷路。
建议给分类语言三件套，并明确告诉 Agent（写进 wiki schema 或 AGENTS.md）：
- DDD bounded context——按领域边界分目录，避免「支付」与「通知」揉在同一锅概念里
- 本体意识——区分实体、概念、关系、决策；页面类型稳定后，交叉引用才有结构
- MECE——划分尽量相互独立、合起来较完整，减少重叠标签与孤儿页
Karpathy wiki 用 summary / entity / concept 等页面类型约束形状；Qoder Repo Wiki 用结构化文档覆盖架构与模块关系。你不必照搬某一产品，但需要可执行的分类契约：Agent 按契约归档与检索，比「自由发挥建 docs」可靠得多。
分类不是为了好看，是为了让检索路径收敛——这是知识层作为 Guide 真正生效的前提。
反模式与最小行动清单
| 反模式 | 更好的做法 |
|---|---|
巨型 CLAUDE.md / AGENTS.md | 常驻层当目录与硬约束，细节外置 |
无索引的 wiki / 万能 docs/ | 先定 taxonomy，再 ingest；定期 lint 断链与孤儿页 |
| MCP / 工具装到「可能有用」 | 少而准；描述写清触发条件 |
| 把 Spec、纪要、监控原文全进仓 | Spec 进真相源；其余指针 + Lazy Loading |
若只做四步：
- 先定知识分类（上下文边界 + 页面类型）
- 写出最小常驻层（身份、约束、索引）
- 其余改为指针或 MCP/工具策略
- 把「知识层 lint」当成 Harness 的一种 sensor：断链、重复、过期摘要要有人（或 Agent）定期扫
收束
Coding Agent 很重要，但更重要的是你为它建的 User Harness。Harness 里，项目知识层决定了 Agent「看见」的世界是清晰地图，还是杂物间。
把仓库从代码仓升级为项目知识库，靠的不是堆更多文档，而是三条可执行的原则：最小负载、Lazy Loading 式按需外联、有界分类。做好这三件事，知识才会变成 Guide，而不是噪音。
参考
- Birgitta Böckeler, Harness engineering for coding agent users, Martin Fowler, 2026
- Anthropic, Effective context engineering for AI agents
- Andrej Karpathy, LLM Wiki
- Qoder, Repo Wiki