Four markdown files that stop your coding agent from rediscovering your codebase every session

Our coding agent was spending 20 minutes every session just figuring out what our codebase does. Not reading the code — that's fine. But rediscovering our architecture, our conventions, our deployment process, our testing patterns. Every. Single. Time.

The fix wasn't a bigger context window or a smarter model. It was four markdown files that live in our repo root:

ARCHITECTURE.md    # System design, data flow, key decisions
CONVENTIONS.md     # Code style, naming, file organization
DEPLOYMENT.md      # How to build, test, deploy, rollback
TROUBLESHOoting.md # Common issues and their solutions

These aren't documentation for humans. They're context primers for agents. Each file is under 500 words, written specifically to answer the questions agents ask most.

ARCHITECTURE.md maps the system at 30,000 feet. What talks to what, where data lives, what each service does. No implementation details — just the mental model.

CONVENTIONS.md captures the patterns that aren't obvious from reading code. "API routes go in /routes, tests mirror the src structure, database migrations are irreversible." The stuff that takes humans weeks to absorb.

DEPLOYMENT.md is the runbook. How to start the dev environment, run tests, deploy to staging, check if something worked. Step by step, no assumptions.

TROUBLESHOOTING.md is the debug cheat sheet. "If the tests fail with X error, check Y. If the deployment hangs, restart Z service." All the tribal knowledge that prevents 45-minute debugging sessions.

Pro tip: Update these files when you catch your agent making the same mistake twice. They're living documents, not set-it-and-forget-it artifacts.

The result? Our agent now jumps straight into productive work instead of spending the first 20 minutes playing detective. It knows our patterns, understands our constraints, and debugs issues instead of rediscovering them.

Four files. Maybe 1,500 words total. Saved us hours every week and made our agent feel like it actually knows our codebase.

The best part: these files help human developers too. New team members read them on day one. Contractors use them to get up to speed. They're documentation that actually gets used because they solve real problems.