codebase-as-system-of-record

Codebase as system of record — the operating principle that all knowledge influencing agent behavior must live in versioned, repo-local artifacts. Knowledge stored in Google Docs, chat threads, meeting recordings, or people’s heads is invisible to an agent at runtime; per 2026-04-27-harness-engineering-codex-agent-first, the OpenAI codex team’s central rule is anything not in the repo doesn’t exist for the agent.

This page records the content side of agent-legibility: legibility means agents can read the system; system-of-record means there’s something in the system to read.

The problem statement

那次让团队在架构模式上达成一致的 Slack 讨论？如果智能体无法发现它，那么它就会像迟了三个月入职的新员工一样，对其一无所知。

(That Slack discussion where the team aligned on an architectural pattern? If the agent can’t find it, the agent is in the same position as a new hire who joined three months late: it knows nothing about it.)

— 2026-04-27-harness-engineering-codex-agent-first

The implication runs further than onboarding: a new hire can ask. An agent can only see what’s in context. So the bar for “in the repo” has to be higher than what a human-only team would write down.

Concrete shape — the OpenAI Codex layout

2026-04-27-harness-engineering-codex-agent-first‘s repo-as-records layout (paraphrased from its docs/ tree):

AGENTS.md                          # ~100 lines, table of contents only ([[claude-md]])
ARCHITECTURE.md                    # top-level domain + package map
docs/
├── design-docs/                   # decisions, validated state, core beliefs
│   ├── index.md
│   ├── core-beliefs.md
│   └── ...
├── exec-plans/                    # first-class artifact: in-flight planning
│   ├── active/
│   ├── completed/
│   └── tech-debt-tracker.md
├── generated/                     # auto-generated context
│   └── db-schema.md
├── product-specs/                 # one per product surface
│   ├── index.md
│   ├── new-user-onboarding.md
│   └── ...
├── references/                    # llms.txt-style copies of dependency docs
│   ├── design-system-reference-llms.txt
│   ├── nixpacks-llms.txt
│   ├── uv-llms.txt
│   └── ...
├── DESIGN.md
├── FRONTEND.md
├── PLANS.md
├── PRODUCT_SENSE.md
├── QUALITY_SCORE.md
├── RELIABILITY.md
└── SECURITY.md

Three things are worth noting:

1. exec-plans/ are first-class. Active plans, completed plans, and known tech debt are all version-controlled and indexed. The agent can navigate from “what are we working on” to “what was tried before” to “what’s known broken” without external context.
2. references/ ships LLM-friendly copies of dependency docs in-tree. When the agent needs to know how uv, nixpacks, or the design system works, it doesn’t fetch — it reads a file. Same instinct as filesystem-as-context-interface (context-engineering).
3. QUALITY_SCORE.md tracks gaps. Each product area / architectural layer has a score that drifts as code drifts. This is what the cleanup loop on entropy-and-garbage-collection reads from.

Progressive disclosure

The complement of “everything in the repo” is “not all of it in context at once”. AGENTS.md is intentionally short and acts as a map — when the agent needs deeper detail, it follows the map to the relevant docs/ file.

This avoids the failure mode named in 2026-04-27-harness-engineering-codex-agent-first for the “one big AGENTS.md” approach (see claude-md):

• Context is scarce — a giant instruction file crowds out task content and code.
• Too much guidance becomes ineffective — when everything is “important”, nothing is.
• It rots — manual upkeep can’t keep pace.
• It’s mechanically unverifiable — a single blob doesn’t fit coverage / freshness / ownership / cross-link checks.

Mechanical enforcement

2026-04-27-harness-engineering-codex-agent-first reports two enforcement layers:

• Linters and CI jobs verify that the knowledge base is up-to-date, cross-linked, and structurally well-formed — same shape as the verifier-loop for code, applied to docs.
• A scheduled “doc-gardening” agent scans for docs that no longer reflect actual code behavior and opens repair PRs. This is the dual of entropy-and-garbage-collection‘s code-side cleanup loop.

Without these, the system collapses: the repo accumulates docs faster than humans can prune them, and the agent starts pattern-matching against rotted material.

Relation to other concepts

• claude-md / AGENTS.md is the table-of-contents artifact at the top of this layout — the contract file the agent loads on every run; this page is the body it points into.
• agent-legibility is the upstream principle: legibility is why the system-of-record matters.
• context-engineering is the constraint: the system-of-record must be progressively-loaded, not always-resident.
• entropy-and-garbage-collection is the maintenance regime: docs and code both rot; both need a cleanup loop.
• long-running-agents‘s feature-list.json / claude-progress.txt patterns are the same idea applied at task-state level: the file is the source of truth, not the conversation.

Onboarding analogy

The framing the post repeatedly returns to: the agent is a new hire who never gets to ask questions and starts fresh every session. Onboarding investments that human teams under-invest in (architecture docs, decision logs, “why we don’t use X”) become first-order for agentic teams. The wiki this page lives in is itself an instance of the same instinct.