Chapter 3 · Repo-as-Record System and Initialization

Chapter goals: Understand why the repo must be the single source of truth, master the correct positioning of AGENTS.md, and learn to design init.sh startup scripts.

3.1 The Knowledge Visibility Gap

Your team's architecture decisions are scattered across Confluence, Slack, Jira, and the heads of a few senior engineers. This barely works for humans — you can ask colleagues, search chat history, flip through docs, and if all else fails you can still corner someone at the coffee machine. But for an AI agent, information not in the repo is non-existent.

This is not an exaggeration. An agent has only three input sources: system prompts and task descriptions, file contents in the repo, and tool execution outputs. Your Slack history, Jira tickets, Confluence pages, architecture decisions made with a colleague on a Friday afternoon — the agent can't see any of this. It can't "go ask someone" or "search chat history." Its entire world is the repo itself.

So the real question is: are you giving it a map good enough to navigate by?

3.2 What Should Be on the Map

OpenAI states directly in their harness engineering article: information not in the repo does not exist for the agent. They call this the "repo IS the spec" principle — the repo itself is the most authoritative spec document.

Anthropic's long-running agent docs echo a similar point: persistent state is a necessary condition for long-task continuity, and cross-session knowledge recoverability directly determines task success rates. And this state must exist in the repo — because that's the only storage the agent has stable, reliable access to.

You might think: "Our team is small, everyone knows everything in their heads, this is fine." Sure — for humans. But if you want to use agents, you must accept one fact: agents can't ask people. Everything they need to know must be written down and placed where they can find it.

This isn't about "writing more docs" — it's about "putting decision information in the right place." A 50-line ARCHITECTURE.md file sitting in src/api/ is far more useful than 500 pages of unmaintained design docs on Confluence. Proximity matters more than length — information is only truly useful when it's right at your fingertips at the moment you need it.

3.3 The Knowledge Visibility Test

How do you test whether your map is good enough? Run a "new session test": open a brand-new agent session, give it only the repo contents, and see if it can answer five basic questions:

Q1: What is this system?        → AGENTS.md / README
Q2: How is it structured?       → ARCHITECTURE.md / module docs
Q3: How do I run it?            → Makefile / init.sh / package scripts
Q4: How do I verify it?         → Test, lint, check commands
Q5: Where are we right now?     → PROGRESS.md / feature list / git history

If all answered → a new session can start working immediately without asking humans
If not answered → the map has gaps, the agent must guess

Wherever the map has gaps, the agent guesses — wrong guesses become bugs, over-guessing wastes context. And the agent has to re-guess every single new session. The cost of guessing wrong is always far higher than drawing the map correctly upfront.

3.4 The Correct Positioning of AGENTS.md

AGENTS.md is not an encyclopedia — it's a table of contents. It should tell the agent:

1. What the project is (one or two sentences)
2. Tech stack and versions (Python 3.11, FastAPI 0.100, ...)
3. First-run command (./init.sh)
4. Non-negotiable hard constraints (things to avoid, specs to follow)
5. Where the detailed docs are (pointing to docs/ or ARCHITECTURE.md)

Example:

# AGENTS.md

## Project
User preference management system, FastAPI + PostgreSQL + Redis, ~15K lines.

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

## First Run
```bash
./init.sh

Hard Constraints

• All API endpoints must go through OAuth 2.0 authentication
• SQLAlchemy 1.x syntax is forbidden
• New code must pass pytest and mypy
• Never modify the production database directly; write a migration first

Detailed Docs

• Architecture: docs/ARCHITECTURE.md
• API spec: docs/API.md
• Deployment: docs/DEPLOYMENT.md

## 3.5 init.sh: Standardized Startup Flow

`init.sh` is the standard "clock in"流程 for an agent:

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

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

echo "==> Working directory: $PWD"
echo "==> Syncing dependencies..."
pip install -e ".[dev]"

echo "==> Baseline verification..."
pytest tests/ -x --tb=short
mypy src/ --strict
ruff check src/

echo "==> Startup command"
printf '    %q\n' "uvicorn src.main:app --reload"

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

echo "Set RUN_START_COMMAND=1 to launch the app directly."

Key design points:

• set -euo pipefail: abort immediately on any error
• Baseline verification: ensure the repo is in a working state
• Optional startup: don't start services by default, let the agent decide

3.6 The Value of the Initialization Phase

Why does initialization need its own phase? Because:

1. Environment consistency: ensure all agent sessions start from the same baseline
2. Fail fast: if baseline verification fails, fix it immediately instead of stacking new features on top of a broken base
3. Context savings: the agent doesn't need to re-explore environment config every time

OpenAI's experiment proved this: five engineers used Codex to build approximately 1 million lines of code from an empty repo over five months. Progress was slow at first — Codex wasn't bad enough, it just lacked sufficient tools and structure to drive high-level goals. They gradually found the pattern: break big goals into small modules — design, code, review, test — let the agent assemble them one by one, then compose those modules into more complex tasks.

3.7 Chapter Summary

• The repo is the agent's only reliable information source; information not in the repo is non-existent
• Run the "new session test": can a new agent answer the five basic questions without human help, using only repo contents?
• AGENTS.md is a table of contents, not an encyclopedia — about 100 lines
• init.sh standardizes the startup flow, ensuring environment consistency and fast failure
• Proximity matters more than length: a 50-line doc right at hand > a 500-page doc far away

🧪 随堂测验

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

1. What is the purpose of the "new session test"?

2. What is the ideal positioning of AGENTS.md?

3. What is the purpose of `set -euo pipefail` in init.sh?

4. What does the proximity principle mean in harness engineering?

🛠️ Hands-on Practice

1. Pick an open-source project and run the "new session test": let a fresh agent session read only the repo and see if it can answer Q1–Q5.
2. Create an AGENTS.md + init.sh combo for a new project, ensuring a new session can start working without asking a human.
3. Test the proximity principle: place key decisions near the relevant code (e.g. src/api/ARCHITECTURE.md) and compare with placing them at the project root.

Next chapter: Long-Task Continuity Management