第 3 章 · 仓库即记录系统与初始化

本章目标：理解为什么仓库必须是单一事实来源，掌握 AGENTS.md 的正确定位，学会设计 init.sh 启动脚本。

3.1 知识可见性缺口

你们团队的架构决策分散在 Confluence、Slack、Jira 和几位 senior 工程师的头脑中。对人类来说这勉强能工作——你可以问同事、搜索聊天记录、翻文档，实在不行还能在茶水间堵住人。但对 AI 智能体来说，不在仓库里的信息等于不存在。

这不是夸张。智能体只有三个输入源：系统提示和任务描述、仓库中的文件内容、工具执行输出。你的 Slack 历史、Jira 工单、Confluence 页面、周五下午和同事敲定的架构决策——智能体都看不到。它不能"去问问别人"或"搜索聊天记录"。它的整个世界就是仓库本身。

所以真正的问题是：你要给它一张足够好的地图吗？

3.2 地图上应该有什么

OpenAI 在 harness 工程文章中直言：不在仓库里的信息，对智能体来说不存在。 他们称之为"仓库即规范"原则——仓库本身是最权威的规格文档。

Anthropic 的长运行智能体文档呼应类似观点：持久化状态是长任务连续性的必要条件，跨会话知识可恢复性直接决定任务成功率。而且这种状态必须存在于仓库中——因为那是智能体唯一稳定、可靠访问的存储。

你可能觉得："我们团队小，知识都在每个人脑子里，这样也挺好。"没错——对人类而言。但如果你想用智能体，必须接受一个事实：智能体不能问人。 它需要知道的一切必须写下来，放在它能找到的地方。

这不是"多写文档"的问题——是"把决策信息放在正确位置"的问题。一份放在 src/api/ 目录下的 50 行 ARCHITECTURE.md，比 Confluence 里 500 页无人维护的设计文档有用得多。** proximity（邻近性）比长度更重要**，因为信息只有在你需要它的瞬间就在手边，才是真正有用的。

3.3 知识可见性测试

怎么测试你的地图够不够好？做一个"新会话测试"：打开一个全新智能体会话，只给它仓库内容，看它能否回答五个基本问题：

text

Q1: 这是什么系统？     → AGENTS.md / README
Q2: 结构如何组织？     → ARCHITECTURE.md / module docs
Q3: 怎么运行？         → Makefile / init.sh / package scripts
Q4: 怎么验证？         → Test, lint, check commands
Q5: 现在进行到哪？     → PROGRESS.md / feature list / git history

如果都能答 → 新会话可以直接开始工作，无需问人
如果答不出 → 地图有空白，智能体必须猜

地图空白的地方，智能体只能猜——错误猜测变成 bug，过度猜测浪费上下文。而且每个新会话都要重新猜一遍。猜错的代价总是远高于一开始就把地图画好。

3.4 AGENTS.md 的正确定位

AGENTS.md 不是百科全书，是目录页。它应该告诉智能体：

项目是什么（一两句话）
技术栈和版本（Python 3.11, FastAPI 0.100, ...)
首次运行命令（./init.sh）
不可协商的硬约束（禁止事项、必须遵循的规范）
详细文档在哪（指向 docs/ 或 ARCHITECTURE.md）

示例：

markdown

# AGENTS.md

## 项目
用户偏好管理系统，FastAPI + PostgreSQL + Redis，~15K 行代码。

## 技术栈
- Python 3.11+, FastAPI 0.100+, SQLAlchemy 2.0 (async)
- PostgreSQL 15, Redis 7
- pytest, mypy --strict, ruff

## 首次运行
```bash
./init.sh

硬约束

所有 API 端点必须经过 OAuth 2.0 认证
禁止使用 SQLAlchemy 1.x 语法
新增代码必须通过 pytest 和 mypy
禁止直接修改生产数据库，必须先写 migration

详细文档

架构: docs/ARCHITECTURE.md
API 规范: docs/API.md
部署: docs/DEPLOYMENT.md


## 3.5 init.sh：标准化启动流程

`init.sh` 是让智能体"打卡上班"的标准流程：

```bash
#!/usr/bin/env bash
set -euo pipefail

ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
cd "$ROOT_DIR"

echo "==> 工作目录: $PWD"
echo "==> 同步依赖..."
pip install -e ".[dev]"

echo "==> 基线验证..."
pytest tests/ -x --tb=short
mypy src/ --strict
ruff check src/

echo "==> 启动命令"
printf '    %q\n' "uvicorn src.main:app --reload"

if [ "${RUN_START_COMMAND:-0}" = "1" ]; then
    exec "${START_CMD[@]}"
fi

echo "设置 RUN_START_COMMAND=1 以直接启动应用。"

关键设计：

set -euo pipefail：任何错误立即中止
基线验证：确保仓库处于可工作状态
可选启动：默认不启动服务，让智能体决定是否启动

3.6 初始化阶段的价值

为什么初始化需要独立阶段？因为：

环境一致性：确保所有智能体会话从相同基线开始
快速失败：如果基线验证失败，立即修复而不是在错误基础上堆叠新功能
上下文节省：智能体不需要每次重新探索环境配置

OpenAI 的实验证明：五个工程师五个月后用 Codex 从空仓库构建出约 100 万行代码。早期进展缓慢——Codex 不是不够好，只是缺少足够的工具和结构来驱动高层目标。他们逐渐找到模式：把大目标拆成小模块——设计、编码、审查、测试——让智能体一个个组装，然后用这些模块组合更复杂的任务。

3.7 本章小结

仓库是智能体的唯一可靠信息源；不在仓库里的信息等于不存在
做"新会话测试"：新智能体能否不靠人类回答五个基本问题
AGENTS.md 是目录页不是百科全书，约 100 行
init.sh 标准化启动流程，确保环境一致性和快速失败
邻近性比长度重要：50 行近在手边的文档 > 500 页远程文档

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. "新会话测试"的目的是什么？

2. AGENTS.md 的理想定位是？

3. init.sh 中 set -euo pipefail 的作用是什么？

4. 邻近性原则在 harness 工程中的含义是？

🛠️ 动手实践

找一个开源项目，运行"新会话测试"：让一个全新智能体会话只读仓库，看它能否回答 Q1-Q5。
为一个新项目创建 AGENTS.md + init.sh 组合，确保新会话无需询问人类即可开始工作。
测试邻近性原则：把关键决策放在靠近代码的位置（如 src/api/ARCHITECTURE.md），对比放在项目根目录的效果。

下一章：长任务连续性管理

第 3 章 · 仓库即记录系统与初始化 ​

3.1 知识可见性缺口 ​

3.2 地图上应该有什么 ​

3.3 知识可见性测试 ​

3.4 AGENTS.md 的正确定位 ​

硬约束 ​

详细文档 ​

3.6 初始化阶段的价值 ​

3.7 本章小结 ​