作为记录系统的仓库知识

将代码仓库作为事实记录系统（System of Record）

试想一下，你雇佣了一位优秀的初级开发人员。第一天上班，你就在他们的桌上扔了一本厚达 1,000 页的说明手册，里面记录了公司有史以来所有的架构决策、执行计划和编码准则。然后你要求他们在写下一行代码之前就背下这些内容。结果会怎样？他们会感到不知所措、困惑，并且很可能会错误地运用这些规则。在构建 AI Harness（AI 护栏/开发辅助框架）时，我们在自主智能体（autonomous agents）上经常犯同样的错误。

在本章中，我们将学习如何转变思维方式。与其将所有的上下文信息塞进智能体的系统提示词（system prompt）中，不如将你的项目仓库变成唯一的“事实来源”（single source of truth）。通过这种方式，智能体可以像查看地图一样浏览代码库，在需要时精准获取所需信息。

“厚手册”的陷阱

当开发者刚开始构建长程智能体（long-running agents）时，本能反应是提供尽可能多的上下文。他们会编写庞大的系统提示词，详述每一个 API 接口、数据库模式（schema）和设计模式。然而，这种做法会带来严重的副作用：

• 注意力衰减（Attention Degradation）：即使拥有海量的上下文窗口（如 10w+ token），大模型（LLM）也会遭遇“中间丢失”（lost in the middle）综合征。它们可能会遗忘或产生幻觉，误读埋藏在巨型提示词深处的指令。
• 成本与延迟：在每一次 API 调用中发送海量提示词会剧烈增加 token 成本，并拖慢智能体的响应速度。
• 上下文过时（Stale Context）：如果智能体修改了系统，静态的系统提示词会迅速过时。此时，AI 就如同在使用一张鬼影地图。

渐进式披露原则（Principle of Progressive Disclosure）

为了解决这个问题，我们依赖一种名为**渐进式披露（Progressive Disclosure）**的 UX 设计理念。在软件界面中，渐进式披露通过跨多个屏幕排列信息和操作，以减少用户的认知过载。对于 AI 智能体而言，这意味着我们只给 AI 提供一张高层级的地图，以及在任务需要时查找具体细节的工具。

我们不再说“这是整个数据库模式”，而是说“你正在参与一个项目。数据库模式位于 /docs/schemas 目录中。在编写数据库查询之前，请先阅读相关文件。”代码仓库本身就成了运营中动态的“活大脑”。

为智能体发现构建仓库结构

为了使渐进式披露发挥作用，你的代码仓库必须具备高度的组织性、可预测性和模块化。它应当包含专门的文件，用于概述设计文档、执行计划和核心架构理念。让我们看看一个针对 Harness 优化的代码仓库结构是怎样的：

my-agent-project/
├── .harness/
│   ├── core_beliefs.md       # 不可妥协的规则（例如：“始终使用 async/await”）
│   ├── execution_plan.md     # 当前冲刺（sprint），已完成事项与下一步计划
│   └── agent_journal.md      # 用于智能体记录笔记供未来参考的“草稿本”
├── docs/
│   ├── architecture_index.md # “地图”：指向具体的架构文档
│   ├── auth_flow.md          # 关于认证流程的详细说明
│   └── database_schema.md    # 关于数据库的详细说明
├── src/
│   └── ...                   # 应用程序代码
└── README.md                 # 入口文件

让我们拆解这些核心组件：

• 核心架构理念（Core Architectural Beliefs）：一个精简且高度浓缩的文件，用于执行你的“开发者品味”。它规定了代码库中不可逾越的规则。
• 执行计划（Execution Plans）：该文件用于追踪项目状态。当新的智能体任务开始时，它会读取此文件以了解“我们目前进展如何？”以及“紧接着的下一步是什么？”
• 设计文档（Design Documents）：模块化文件（如 auth_flow.md），包含深度的技术背景。智能体仅在当前任务明确涉及该系统时才会读取它们。

像看地图一样导航代码库

为了让智能体将仓库视为“事实记录系统”，它需要导航工具和入口点。你必须为智能体提供文件读取和目录列表功能（例如通过 Harness 中的专用工具）。此时，系统提示词就变成了一个轻量级的路由器。

以下是在此架构下，一个高效、轻量级智能体提示词的示例：

// 示例：轻量级系统提示词
你是一位自主软件工程师。
你的主要事实来源是本地代码仓库。

指令：
1. 首先阅读 README.md 和 .harness/execution_plan.md 以了解你当前的目标。
2. 在修改任何系统之前，请在 /docs 文件夹中查找其相关文档。
3. 不要猜测模式或 API。使用你的 `search_repo` 和 `read_file` 工具来调查代码库的当前状态。
4. 完成任务后，更新 .harness/execution_plan.md 以反映你的进度。

方案对比

让我们总结一下传统方案与 AI Harness 工程方案的区别：

维度	重量级系统提示词（传统）	仓库作为事实记录系统（Harness）
上下文位置	堆砌在 LLM 系统提示词中	存储在代码库的模块化文件中
上下文大小	庞大，接近 token 上限	极小的初始提示词，按需获取上下文
幻觉风险	高（容易在中间迷失）	低（在行动前即刻读取特定文件）
状态管理	依赖 LLM 会话记忆	直接保存到磁盘（例如 execution_plan.md）
可扩展性	随着项目增长而失效	随代码库无限扩展

通过将逻辑、状态和规则从 LLM 的瞬时记忆中移出，存入冷冰冰且稳定的文件系统中，你便创造了一个环境，让智能体可以在数天、数周甚至数月的时间里可靠地运行，而不会迷失方向。