37 lines
1.7 KiB
Markdown
37 lines
1.7 KiB
Markdown
# The Repo Is the Spec
|
|
|
|
**May 26, 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.*
|