Agent-First Repository Design

Patterns for structuring a repository so AI coding agents can do effective, autonomous work. Based on OpenAI's harness engineering approach: https://openai.com/index/harness-engineering/

The core insight: if the agent can't see it in the repo, it doesn't exist. Knowledge in Slack, Google Docs, or people's heads is invisible to agents. The repository must be the single source of truth.

The Knowledge Hierarchy

A well-structured agent-first repo follows a layered documentation architecture:

AGENTS.md                    ~100 lines — table of contents, dev commands
ARCHITECTURE.md              codemap with boundaries and invariants
docs/
├── design-docs/
│   ├── index.md             catalogue of all design docs with status