Repository必须是AI agent的"唯一真相来源"，巨型指令文件为何失效

Repository必须是AI agent的"唯一真相来源"，巨型指令文件为何失效 | 前端进阶之旅

Full translation

完整中文译文

首先，理解术语

在进入主题之前，先介绍3个读者必须掌握的术语：

System of Record（单一真相来源）：具有最高决策权威的单一数据源，对 agent 来说就是 repository

Knowledge Visibility Gap（知识可见性缺口）："不在 repo 中"的项目知识比例，缺口越大 agent 出错越频繁

Lost in the Middle：LLM 在处理长文本"中间"部分的信息时，效果往往比开头和结尾差的现象

打个比方：repository 是 agent 赖以导航的"地图"，如果地图是空的，agent 就只能靠猜，猜错了就变成 bug

问题：知识散落四处

团队架构决策分散在 Confluence、Slack、Jira 以及几位资深工程师的脑子里

对人类来说，这还算勉强能应付——你可以问同事、搜索聊天记录、翻文档，实在不行还能去茶水间堵人

但对 AI agent 来说，不在 repository 里的数据就是不存在

Agent 只能看到3样东西

Agent 的数据来源只有3条：system prompt + task description、repository 内的文件内容、以及 tool 的执行结果

Slack 历史记录、Jira 工单、Confluence 页面，还有你上周五下午和同事讨论的那些决策——agent 全部看不见。它"没法问人"、"没法搜索聊天记录"，它的工作世界就是 repository 本身

OpenAI 说得很直白：不在 repo 里的数据，对 agent 来说就不存在，这就是"repo as spec"原则——repository 是具有最高权威的规格文档 [1]

测试你的地图够不够好：Fresh Session Test

打开一个全新的 agent session，只提供 repository 内容，然后看它能否回答这5个问题：

5 个 Fresh Session Test 问题

如果回答不了，说明地图有空白，空白的地方 agent 就得靠猜，猜错了变成 bug，猜得多又浪费 context，而且每个新 session 都要从头再猜一遍

绘制好地图的原则（4条）

知识要放在代码旁边，API authentication 规则应该放在 API 代码旁边，而不是埋在某个大文档里，每个 module 目录放简短的 doc

使用标准入口文件，AGENTS.md 是 agent 的"首页"，50-100 行足够，必须回答3个问题："这个项目是什么"、"怎么运行"、"怎么验证"

少而精，每条知识必须有明确的使用场景，如果删掉某条规则不会影响 agent 的决策，那这条规则就不该存在

跟着代码一起更新，把知识更新和代码变更绑定在一起，doc 放在 module 目录里，改代码时自然能看到 doc

好用的 repo 结构示例

project/
├── AGENTS.md              # 入口：概览、运行命令、硬性约束
├── src/
│   ├── api/
│   │   ├── ARCHITECTURE.md  # API 层架构决策
│   │   └── ...
│   ├── db/
│   │   ├── CONSTRAINTS.md   # 数据库操作硬性约束
│   │   └── ...
├── PROGRESS.md             # 当前进度：已完成、进行中、阻塞
└── Makefile                # 标准化命令：setup、test、lint、check

为什么单文件巨无霸会失效

你开始认真对待 harness，创建了 AGENTS.md 然后把所有规则都塞进去，1个月后文件膨胀到300行，2个月450行，3个月600行——然后你发现 agent 反而变差了：

简单的 bug 却因为读无关的 deploy 指令而烧掉大量 context

藏在第300行的重要 security 约束被忽略

3条互相冲突的 style 规则让 agent 每次都随机选

这就是"巨无霸文件"的陷阱——每条规则看起来都有用，全塞进去，但要找特定规则就得翻遍整个文件

解决方案：按主题分拆文件

原则：常用的放手边，不常用的放远处，永远用不到的别背着

入口文件 AGENTS.md 保持在50-200行，只包含：project overview（1-2句话）、first-run 命令、hard constraints（不超过15条），以及 topic documents 的链接

# AGENTS.md

## Project Overview
Python 3.11 FastAPI backend, PostgreSQL 15 database.

## Quick Start
- Install: `make setup`
- Test: `make test`

## Hard Constraints
- All APIs must use OAuth 2.0 authentication
- All database queries must use SQLAlchemy 2.0 syntax

## Topic Docs
- API Design Patterns (`docs/api-patterns.md`), Required when adding endpoints
- Database Rules (`docs/database-rules.md`), Required when modifying DB

每个 topic document 50-150行，按主题组织在 docs/ 下，agent 只在需要时才读——就像收纳盒：内衣一个盒子、洗漱用品一个盒子、充电器一个盒子，找东西不用把整个行李箱倒出来

真实案例：45% → 72% 全靠分拆文件

某 SaaS 团队的 AGENTS.md 从50行膨胀到600行，agent 开始变差：简单 bug 因读无关的 deploy 指令而烧掉 context、"所有 query 必须 parameterized"的安全规则埋在第300行频繁被忽略、3条互相冲突的 style 规则 [3]

团队做 refactoring：AGENTS.md 砍到80行，新建3个 topic docs，把 historical notes 移成 test case 或直接删掉

结果：成功率从45% → 72%，security 规则遵守率从60% → 95%——因为规则从文件中间移到了入口文件顶部，不再"Lost in the Middle"

我认为这两条经验是整个 harness engineering 的"根基"：(1) 知识必须放在 repo 里，因为 agent 看不见别处；(2) 指令文件必须短小、按主题分拆，因为巨无霸文件会让 agent 迷路

如果你只能做到两件事——把 AGENTS.md 缩短 + 把知识下移到 repo 里——你会立刻看到差异，无需换模型

你的 AGENTS.md 现在有多少行？你团队的重要知识，有多少百分比放在 repo 里？评论区聊聊吧

[1] OpenAI. "Harness Engineering: leveraging Codex in an agent-first world". 2026. https://openai.com/index/harness-engineering/

[2] Liu et al. "Lost in the Middle: How Language Models Use Long Contexts". 2023. https://arxiv.org/abs/2307.03172

[3] Learn Harness Engineering, Lecture 03-04. 2026. https://github.com/walkinglabs/learn-harness-engineering