Your coding agent needs an AGENTS.md file (and 3 other context files)
Your coding agent nails the demo. Clean function, perfect tests, runs on the first try. Then you point it at your actual codebase and it falls apart.
The difference isn't the complexity — it's the invisible context. Your demo task was self-contained. Your production code lives in a web of undocumented assumptions, brittle infrastructure, and business logic that never made it into comments.
Here's how to bridge that gap with four files that turn your coding agent from a demo hero into a production workhorse.
1. AGENTS.md — Your codebase's field guide
This isn't documentation for humans. It's context for agents. Start with architecture decisions that aren't obvious from the code:
# Architecture Context - User auth flows through Firebase, but admin auth uses custom JWT - Payment processing: Stripe for subscriptions, PayPal for one-time - Database: Postgres for transactional, Redis for sessions/cache - File uploads go to S3, but PDFs get processed through Lambda first # Gotchas - Never modify user.email directly — use updateUserEmail() helper - API rate limits reset at midnight UTC, not user timezone - Test DB seeds with stale data on Fridays (known issue)
Add the non-obvious stuff: why certain patterns exist, what breaks when you change X, which services are flaky.
2. WORKFLOWS.md — How things actually get done
Your agent needs to know the development workflow, not just the code structure:
# Development Process - Feature branches from `develop`, not `main` - Run `npm run test:integration` before any DB schema changes - Staging deploys automatically, prod requires manual approval - Database migrations run in separate deploy step (never bundle) # Testing - Unit tests: `npm test` - Integration: `npm run test:integration` (requires Docker) - E2E: `npm run test:e2e` (slow, only run for major changes)
3. CONSTRAINTS.md — The boundaries and business rules
This is where you document the business logic that lives in people's heads:
# Business Rules - Free users: 3 projects max, 100MB storage - Paid users: unlimited projects, 10GB storage - Enterprise: custom limits in enterprise_limits table # Technical Constraints - API responses must be under 2MB (mobile app limitation) - Background jobs timeout after 30 minutes - File processing queue: max 50 concurrent jobs
4. EXAMPLES.md — Show, don't just tell
Give your agent concrete examples of common tasks done right:
# Adding a new API endpoint 1. Define route in routes/api.js 2. Create controller in controllers/ 3. Add validation schema in schemas/ 4. Write tests in tests/api/ 5. Update API docs in docs/api.md # Database changes 1. Create migration: `npm run migrate:create name` 2. Test migration up/down locally 3. Update models in models/ 4. Run integration tests
Pro tip: Start your agent prompts with "Review AGENTS.md, WORKFLOWS.md, and CONSTRAINTS.md before starting." Make context-checking a habit.
The magic happens when your agent stops guessing and starts knowing. It understands why the code is structured this way, follows your actual development process, and respects the business rules that matter.
Your demos work because they're simple. Your production code works when your agent has the context to navigate complexity.