I work with AI coding agents every day. Cursor, Claude Code, sometimes both in the same project. And the thing that used to slow me down the most wasn't writing code. It was re-orienting the agent at the start of every session.
"Here's the folder structure." "We use Provider for state." "Don't put new screens in the root of lib." "Android alarm testing needs a real device."
Over and over. Every session.
So I built a fix. I call it /document-project, and the prompt file is here if you want to skip straight to it: https://gist.github.com/razamit/b28d7d8b0acaf995969673df47333d58
What it actually is
It's a markdown prompt file I keep in my projects. When I type the command in Cursor or Claude Code, the agent reads the file, walks the entire repo, and produces or updates two things:
AGENTS.md at the root — a machine-oriented map with build commands, tech stack, layout, conventions, and known footguns
Folder-level README.md files — short, only where they add navigation value
The file tells the agent exactly what to write, what to skip, and how to format it. It prioritizes accurate and short over comprehensive and stale.
A real example
Here's what AGENTS.md looks like after running on my StickyTasks Flutter app:
## One-line purpose
Cross-platform Flutter task app with sticky reminders, local
notifications, recurring tasks, optional daily recap, ads + Pro IAP.
## Tech stack
| Area | Stack |
|-------|------------------------------------------|
| App | Flutter, Dart SDK ^3.9.0 |
| State | provider |
| DB | Hive + hive_flutter |
| Notif | flutter_local_notifications, timezone |
## Layout map
| Path | Role |
|-------------------|-----------------------------------------------|
| lib/ | screens, widgets, viewmodels, controllers... |
| android/ | Kotlin native, alarms, manifest |
| functions/ | Firebase callable sendFeedback |
## Known footguns
- Android alarms: test on real device, not emulator
- Hive model changes: run build_runner after
- Firebase feedback: needs RESEND_API_KEY configured
No walls of text. No dependency dumps. Just what an agent needs to orient fast.
The key design decisions in the prompt
AGENTS.md comes first. Many tools treat it as the machine-oriented entry point.
Folder READMEs only where they pay off — top-level areas, confusing names, shared entry points. Not everywhere.
Don't paste dependency lists or full directory trees. Summarize and point to files.
Update, don't append. If structure changed, remove outdated sections instead of adding contradictions.
How to set it up
Download the file from the Gist and drop it in your project.
Cursor: place it in .cursor/ named document-project.md
Claude Code: place it in .claude/commands/ named document-project.md
Then just type /document-project in the chat. That's it.
When I run it
I run it on a break. Literally: type the command, go make coffee, come back and the whole repo is documented and up to date.
The next session, the agent starts oriented. It puts new features in the right layer. It knows what build_runner is for. It doesn't ask me to re-explain the architecture.
The bigger principle
AI agents don't have memory. That's not going to change soon. So the question is: how do you give them the context they need without spending 10 minutes typing it every single time?
Good documentation written for machines, not humans, is the answer. Short, scannable, honest about footguns. AGENTS.md is that format.
If you're using Cursor or Claude Code on any project longer than a weekend, this is worth setting up.
Prompt file: https://gist.github.com/razamit/b28d7d8b0acaf995969673df47333d58
I'm Amit Raz, a Software Architect and AI consultant. I build AI-powered products and help teams integrate AI into their workflows. Check out my work at rzailabs.com
Top comments (0)