The Repo Is the Spec

June 5, 2026

The single most important principle in agentic engineering: all context must live in the repository.

The Problem

Imagine dropping a new engineer into a project at 3AM. They need to know what the project does, how to run tests, where to put new code, and what conventions to follow.

If the answer to any of these is "ask Bob," you fail. If the answer is "read CLAUDE.md in the repo," you win.

What the Repo Should Contain

repo/
+-- CLAUDE.md or AGENTS.md    # Agent instructions (the most important file)
+-- init.sh                   # Environment setup script
+-- feature_list.json         # Tracked features with evidence
+-- Makefile                  # Common commands (test, build, lint)
+-- tests/                    # Expected outcomes as evidence
+-- skills/                   # Reusable skill definitions
+-- .mcp.json                 # MCP server configuration

Why This Matters for Agents

An agent can only see what you put in front of it. A well-structured repo eliminates tribal knowledge because the agent discovers everything from files. It makes onboarding instant because a new agent reads the same files as the old one. It creates audit trails because every instruction is version-controlled. And it enables multi-agent teams because all agents read from the same source of truth.

The Rule

If an agent needs to know something to do its job, that information must be in a file in the repo. Not in your head. Not in Slack. Not in a README that nobody reads. In a file, checked into version control, readable by any agent at any time.

---

From Module 1 of the Agentic Engineering Course. The full module covers the agent loop, tool calling, and decision frameworks.