Building Better Context for AI Coding Assistants
Yesterday was one of those days where the meta-work feels more important than the feature work. I spent the afternoon adding AGENTS.md files across our active repos โ minte-blog-worker, flo-social-worker, and atlas-skills. On the surface, it looks like documentation debt. In reality, it's infrastructure for how AI agents collaborate with our codebase.
The Problem: Context Switching Kills Productivity
When you're working with AI coding assistants (Claude Code, Codex CLI, or our own DevFlo agent), the quality of output depends entirely on context. Every time an agent starts a new session, it needs to rebuild understanding of:
- Project structure โ Where do things live?
- Tech stack โ What tools are we using?
- Conventions โ How do we name things? What patterns do we follow?
- Gotchas โ What are the common issues?
- Commands โ How do we test, build, deploy?
Without explicit documentation, the agent spends 3-5 messages asking clarifying questions. Or worse โ it guesses wrong and suggests changes that break conventions.
The Solution: AGENTS.md as First-Class Documentation
We already have README.md for humans. Why not AGENTS.md for AI?
Here's the structure we landed on:
1. Project Overview
## Project Overview
This is a Cloudflare Worker that publishes blog posts to R2 storage.
It provides:
- Admin UI for creating/editing posts
- JSON API for post retrieval
- Public-facing blog reader
Short, declarative, no fluff. The agent now knows what this repo does in 10 seconds.
2. Architecture
ASCII diagrams work surprisingly well:
Browser
โ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Cloudflare Worker โ
โ - Admin routes (/admin/*) โ
โ - Public routes (/) โ
โ - R2 bucket (minte-blog-prod) โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Agents parse this better than prose. It's visual, hierarchical, and unambiguous.
3. Key Files
A table mapping files to their purpose:
| File | Purpose |
|---|---|
src/index.ts |
Main Hono app, route mounting |
src/routes/api.ts |
JSON API endpoints |
src/routes/admin.ts |
Admin UI handlers |
Now when the agent needs to add a new API endpoint, it knows exactly where to look.
4. Common Tasks
Step-by-step workflows for frequent operations:
### Adding a New Blog Post
1. Create JSON file with slug, title, content
2. Upload to R2 bucket via admin UI
3. Test retrieval: `curl https://blog.minte.dev/api/posts/{slug}`
4. Deploy: `npm run deploy`
This eliminates back-and-forth. The agent has a checklist.
5. Testing
## Commands
npm test # Run tests (vitest)
npm run deploy # Build and deploy to Cloudflare
npm run dev # Vite dev server
Copy-paste ready. No ambiguity.
Real-World Impact
After adding AGENTS.md to minte-blog-worker, I tested it with a fresh Claude Code session:
Before AGENTS.md:
- 5 messages to understand project structure
- 2 incorrect suggestions (wrong file paths)
- 10 minutes to first useful output
After AGENTS.md:
- 1 message: "Add a new API endpoint for listing posts by tag"
- Correct implementation on first try
- 2 minutes to working code
5x productivity boost from 30 minutes of documentation work.
What Belongs in AGENTS.md vs README.md?
README.md is for humans who want to understand and use the project:
- Installation instructions
- Usage examples
- Contribution guidelines
- License
AGENTS.md is for AI agents who need to modify the codebase:
- Architecture decisions
- File organization
- Development workflows
- Common patterns and gotchas
Think of README.md as the manual. AGENTS.md is the field guide.
Patterns Worth Stealing
1. Environment Variables Table
| Variable | Purpose | Example |
|---|---|---|
ANTHROPIC_API_KEY |
Claude API access | sk-ant-... |
R2_BUCKET |
Blog storage | minte-blog-prod |
Agents need to know what secrets exist. This table makes it explicit.
2. Deployment Patterns
### Cloudflare Workers
- Use `wrangler deploy` for production
- Service bindings for worker-to-worker calls
- Secrets via `wrangler secret put`
Describe how we deploy, not just the commands.
3. Common Issues
### Windows + Cloudflare workerd
Use GitHub Actions (Linux runners) โ workerd doesn't build reliably on Windows.
Capture the gotchas before they bite.
The Meta-Lesson: Infrastructure for AI Collaboration
Adding AGENTS.md isn't just documentation โ it's infrastructure. When you're building in public with AI agents as collaborators, you need machine-readable context.
Think about it:
- Humans read README.md once, then remember
- AI agents forget everything between sessions
We need documentation optimized for zero-shot understanding. AGENTS.md is that layer.
What's Next
- Automated validation โ CI check that fails if AGENTS.md is missing
- Agent-specific sections โ "For Claude Code:" vs "For Codex CLI:"
- Version tracking โ Link AGENTS.md to specific commit SHAs
- Cross-repo discovery โ Index all AGENTS.md files for quick lookup
The Bigger Picture
We're building in an era where AI agents are first-class collaborators. That means rethinking our tooling:
- Documentation โ Machine-readable context (
AGENTS.md) - Testing โ AI-verifiable correctness (deterministic outputs)
- Architecture โ Modular, composable, understandable by models
Yesterday's work (adding AGENTS.md to 3 repos) wasn't feature work. It was platform work. The kind of work that compounds.
Every future agent session benefits. Every onboarding gets faster. Every context switch gets cheaper.
That's the game: Build infrastructure that makes AI collaboration effortless.
Technical Details
Repos updated:
Commits:
726e486โ Add AGENTS.md to minte-blog-workeraa46648โ Add AGENTS.md to flo-social-workerab1199bโ Add AGENTS.md to atlas-skills
Lines added: ~300 lines of documentation across 3 repos
Time investment: 30 minutes
Expected ROI: 5-10 hours saved over next month
Building in public with AI agents as teammates. This is the way.