第 14 章 · RAG 与检索增强提示

本章目标：理解"仓库即规格（repo IS the spec）"原则，掌握 AGENTS.md 作为目录页的设计方法，学会用 init.sh 建立标准化的启动流程。

12.1 Repo IS the Spec

OpenAI 在 harness engineering 文章里提出了一个核心原则：repo IS the spec（仓库即规格）。

这句话的含义是：agent 能看见的只有仓库里的文件。任何不存在于仓库中的信息，对 agent 而言等于不存在。你脑子里的架构约定、Slack 里三个月前讨论的决策、Figma 设计稿上的交互细节——如果没写进仓库，agent 就不知道。

这与 Anthropic 的"state persistence"理念不谋而合：所有 agent 需要的上下文都应该在仓库中以结构化文件的形式存在，而不是靠对话历史或口头传达。

两个公司关注点不同，说的是同一件事：工程基础设施的所有必要信息必须居住在仓库里。

12.2 AGENTS.md：目录页而非百科全书

承接上一章，AGENTS.md 的定位是目录页——告诉 agent "项目是什么、怎么用、哪里找更多信息"，而不是把所有知识都塞进去。

一份完整的 AGENTS.md 结构

markdown

<!-- project-root/AGENTS.md -->
# AGENTS.md — Working with this repository

## What this project is
A FastAPI-based task management API with PostgreSQL backend.
Built for the Python Engineering team.

## Tech Stack
- Python 3.12 · FastAPI 0.141 · SQLAlchemy 2.0 (async)
- PostgreSQL 16 · Redis 7 (caching) · Celery 5 (background tasks)
- Testing: pytest + httpx TestClient
- Linting: ruff + mypy --strict

## First Run
```bash
make dev-up      # starts postgres + redis via docker-compose
uv sync
uv run pytest tests/ -q   # smoke test

Hard Constraints

All API routes must be under /api/v2/...
No synchronous database calls — use async with session()
All new endpoints require OpenAPI schema + request model

Verification Commands

Tests: pytest tests/ -x
Types: mypy src/ --strict
Lint: ruff check src/
Full: make check

Architecture

See your project's architecture documentation

API Spec

See your project's API specification


### 关键设计原则

1. **不超过 100 行**：太长会被 agent 当作"背景噪音"，关键信息被淹没。超出就拆。
2. **硬约束写在正文里**：不可协商的规则（技术栈版本、命名规范、鉴权方式）直接写在 AGENTS.md。
3. **详细文档放 docs/**：架构决策、API 规范、数据库 ER 图——这些 agent 只在需要时才会读，不要塞进 AGENTS.md。
4. **验证命令必须可执行**：每条命令都能直接复制粘贴到终端运行，不是文字描述。

## 12.3 init.sh：独立的初始化阶段

第 10 章提到过五大失败模式之一："环境不全"。agent 打开一个仓库，花 10 分钟排查环境、装依赖、建数据库——这些时间本应用于真正的工作。

**初始化阶段的独立价值**：把环境探索成本从任务本身剥离出来，让每次会话开始时环境已经是确定可用的状态。

`init.sh` 的职责：

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

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

INSTALL_CMD=(uv sync)
VERIFY_CMD=(pytest tests/ -q)
START_CMD=(uv run fastapi dev src/main.py)

echo "==> Working directory: $PWD"
echo "==> Syncing dependencies"
"${INSTALL_CMD[@]}"

echo "==> Running baseline verification"
"${VERIFY_CMD[@]}"

echo "==> Startup command"
printf '    %q\n' "${START_CMD[@]}"

if [ "${RUN_START_COMMAND:-0}" = "1" ]; then
    echo "==> Starting the app"
    exec "${START_CMD[@]}"
fi
echo "Set RUN_START_COMMAND=1 to launch the app directly."

init.sh 的工作流设计

agent 每次启动时应该按照固定顺序执行：

bash

# 1. 确认工作目录
pwd

# 2. 读取上次会话的进度记录
cat PROGRESS.md   # 或 claude-progress.md

# 3. 读取功能列表，选择最高优先级的未完成项
cat feature_list.json | jq '.features[] | select(.status == "in_progress")'

# 4. 查看最近提交，了解当前代码状态
git log --oneline -5

# 5. 运行 init.sh 确保环境可用
./init.sh

# 6. 运行冒烟测试确认基线通过
pytest tests/smoke/ -q

基线失败的处理原则

如果 init.sh 或冒烟测试失败，先修复基线，再做新功能。不要在已破裂的基线上叠加新工作——这只会让问题更深。

12.4 AGENTS.md 与 init.sh 的协同

AGENTS.md 和 init.sh 是互补关系：

维度	AGENTS.md	init.sh
角色	静态说明书	动态启动脚本
谁来读	agent 读（每次会话开始）	agent 执行（每次会话开始）
内容	技术栈、约束、验证命令	依赖安装、基线验证、服务启动
生命周期	变更频率低（架构稳定后）	几乎不变（复制即用）

典型协作流程：

text

agent 启动
    ↓
读 AGENTS.md（获取项目全貌 + 硬约束）
    ↓
读 PROGRESS.md（获取上次会话断点）
    ↓
读 feature_list.json（选择当前任务）
    ↓
运行 ./init.sh（确保环境干净可用）
    ↓
开始工作

这个流程保证了每次会话都在相同的环境起点上开始，不会因为某次手动干预改变了环境状态而导致后续会话行为不一致。

12.5 常见陷阱

陷阱一：AGENTS.md 写成博客

写 500 行项目介绍、历史背景、团队故事……agent 不需要知道你的项目为什么诞生，它只需要知道"怎么在这里工作"。精简到 100 行以内。

陷阱二：验证命令写在 AGENTS.md 里但从未运行过

如果你写的 make check 在你的机器上跑不通，agent 也跑不通。AGENTS.md 里的每一条命令都应该在你自己的机器上实际验证过。

陷阱三：init.sh 假设环境已经配好

uv sync 失败、docker-compose 启动不了、数据库连不上——这些都是 init.sh 应该处理的边界情况，不是 agent 该花时间排查的问题。

陷阱四：PROGRESS.md 从不更新

写了 PROGRESS.md 但不更新，等于没写。每次会话结束前必须更新进度记录，下次会话才有意义。

本章小结

repo IS the spec：agent 只能看见仓库里的文件，不在仓库里的信息对它等于不存在
AGENTS.md 是目录页（~100 行），详细内容放 docs/ 按需读取
AGENTS.md 四要素：项目概述 / 技术栈与版本 / 硬约束 / 验证命令
init.sh 把环境初始化成本从任务本身剥离，保证每次会话从相同起点开始
init.sh 执行顺序：pwd → 读进度 → 选 feature → 查 git log → 跑 init.sh → 跑冒烟测试
AGENTS.md（静态说明）与 init.sh（动态执行）协同工作，构成最小可运行的 harness 基线

🧪 随堂测验

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

1. "repo IS the spec"的核心含义是什么？

2. 关于 AGENTS.md 的长度控制，以下哪项是正确的做法？

3. init.sh 的基线验证失败时，正确的处理原则是？

4. AGENTS.md 与 init.sh 的关系最准确的描述是？

🛠️ 动手实践

在你的项目根目录创建一份 AGENTS.md（不超过 100 行），包含四要素，并确保每条验证命令在你本地实际运行通过。
编写 init.sh，实现：安装依赖 → 运行基线测试 → 可选启动服务三个阶段，用 set -euo pipefail 保证错误可控。
创建 PROGRESS.md，模拟一个"上次会话遗留的中断状态"，让下一次启动的 agent 能从中断点无缝续接。

完成后进入下一章：对抗攻击与防御。

第 14 章 · RAG 与检索增强提示 ​

12.1 Repo IS the Spec ​

12.2 AGENTS.md：目录页而非百科全书 ​

一份完整的 AGENTS.md 结构 ​

Hard Constraints ​

Verification Commands ​

Architecture ​

API Spec ​

init.sh 的工作流设计 ​

12.4 AGENTS.md 与 init.sh 的协同 ​

12.5 常见陷阱 ​

本章小结 ​