Coding agents rebuild everything because they can't find existing code.
Our coding agent kept rebuilding the same authentication flow. Three different sessions, three different OAuth implementations, all solving the same problem we'd already solved.
The issue wasn't the agent's memory or intelligence. It was context discovery.
When a coding agent lands in your codebase, it sees files but doesn't understand the architecture. It reads package.json and README.md but has no idea how authentication actually works, where the API clients live, or what the deployment process looks like.
So it rebuilds everything from scratch.
The fix is simple: create context files that your agent reads first, every time.
Here's what we built:
AGENTS.md — The master index
# Agent Context Files ## Read These First - AUTH.md — How authentication works - DEPLOY.md — Deployment process and environments - API.md — External services and rate limits - ARCH.md — System architecture and data flow ## Key Patterns - Use existing auth middleware in /lib/auth - All API calls go through /lib/clients - Tests require Docker compose up - Deploy via GitHub Actions only
AUTH.md — Authentication implementation
# Authentication ## How It Works - OAuth 2.0 via Google and GitHub - JWT tokens stored in httpOnly cookies - Middleware in /lib/auth/middleware.js ## Adding New Providers 1. Add config to /config/oauth.js 2. Create handler in /lib/auth/providers/ 3. Update middleware to recognize new provider ## Don't Rebuild - The OAuth flow works - The token validation works - Just add new providers to existing system
API.md — External service context
# External APIs ## Rate Limits - Stripe: 100/sec (we're nowhere near this) - SendGrid: 600/min (watch this one) - GitHub: 5000/hour (resets at :00) ## Client Usage - All clients in /lib/clients/ - Auto-retry with exponential backoff - Errors logged to /logs/api-errors.log ## Adding New APIs - Copy /lib/clients/stripe.js as template - Add rate limit config - Add error handling
DEPLOY.md — Deployment guardrails
# Deployment ## Process 1. PR to main triggers staging deploy 2. Manual approval required for production 3. Rollback via GitHub Actions "Rollback" workflow ## Never Deploy Directly - No manual server access - No database migrations without review - No environment variable changes without ops approval ## Emergency Contacts - On-call rotation in PagerDuty - #incidents Slack channel
Now when our coding agent starts a session, the first thing it does is read AGENTS.md, then the relevant context files. Instead of reverse-engineering our OAuth flow, it extends the existing one. Instead of guessing about rate limits, it uses the documented clients.
Pro tip: Put these files in your repository root and reference them in your agent's system prompt. "Always read AGENTS.md first to understand the codebase context."
The result: our agent stopped rebuilding wheels and started shipping features. Context files are documentation that agents actually read.