When I first got sucked into “vibe coding,” the appeal was irresistible: talk to an AI, get working code, iterate by telling it “fix this, change that,” and watch things come together. The problem was: very quickly, the AI would drift. It would forget naming conventions, reimplement things already in your codebase, introduce inconsistent formatting, or ignore tests. Every new prompt felt like onboarding a fresh engineer from scratch.
That’s when I discovered AGENTS.md. It’s a simple Markdown file your project carries, telling AI agents: these are your rules, conventions, and tools for this project. Think of it as a “readme for machines.” Over time, a small but growing community adopted it (OpenAI, Factory, Cursor, others) as a way to unify how agents understand projects.
In my early projects, I had separate “prompt templates,” “cursor.rules,” “claude.md,” “copilot-instructions.md,” etc. It became a mess, especially when I switched tools. Moving everything into one canonical AGENTS.md, layering context properly, and structuring it for minimal but sufficient coverage was a revelation. It immediately raised the quality of agent outputs and reduced drift.
Here I’ll walk you through how I do a simple vibe coding project — let’s say a little web tool using JavaScript + Node, minimal complexity — and how I build a clean, sensible AGENTS.md that helps agents stay consistent and productive.
What is AGENTS.md, and why it matters
Before diving into examples, I’ll summarize what AGENTS.md is, how agents use it, and what benefits it gives.
- AGENTS.md is just a Markdown file (with any headings you like) that describes how an AI coding agent should operate in your project: build steps, style rules, domain vocabulary, caveats, etc.
- It complements — not replaces — your normal
README.md. The README is for human readers: usage, architecture overviews, how to run, etc. AGENTS.md is for agents. - Agents look up the nearest AGENTS.md file relative to where they’re editing; nested AGENTS.md files are allowed (for subdirectories or modules) so context is scoped.
- Using a single unified file avoids duplication across agent systems (Cursor, Claude, Gemini, etc.). Many projects already support reading from AGENTS.md.
- A well-written AGENTS.md reduces prompt drift, cuts down repetitive instructions, and helps keep generated code aligned with project conventions.
One recent empirical study of Claude.md files (an equivalent manifest for Claude-based agent systems) examined 253 manifests and found that most are shallow (one top heading, a few subsections) and heavy on commands, architecture, and operational notes. That suggests real users keep them concise and focused.
In short: AGENTS.md is your tool to teach the AI your project’s “tribal knowledge”, so it doesn’t need to relearn everything per prompt.
Overall structure strategy
Here’s how I like to structure an AGENTS.md for a small vibe coding project. (You can adapt or omit sections depending on your project.)
- Project overview / purpose
- Core commands (setup, run, test)
- Architecture sketch / module breakdown
- Conventions & patterns (naming, formatting, folder structure)
- Domain vocabulary / business rules
- Git / PR style / commit conventions
- Tips, gotchas, edge cases, constraints
- Security / secrets handling
- Optional: testing / quality rules, CI info
I aim for enough detail to reduce “stupid mistakes,” but not so much that it overwhelms the agent or conflicts with prompts.
Later, when you start a subdirectory with special logic (say, backend/ or ui/), you can add a nested AGENTS.md there with overrides specific to that part.
Example: Simple Vibe Coding Project — “Notes App”
Let me walk you through how I’d build an AGENTS.md for a very simple notes app — backend with Node/Express, frontend minimal React, storing JSON or a light database.
Sample AGENTS.md
Below is a draft. I’ll then explain each section and what I expect an agent to do with it.
# NotesApp
A simple notes-taking app: frontend (React) + backend (Node/Express).
Focus: features like create, list, edit, delete notes; export JSON; search notes by keyword.
## Core Commands
- `npm install` — install dependencies
- `npm run dev` — start frontend + backend in dev mode
- `npm run build` — build production frontend
- `npm run test` — run all tests
- `npm run lint` — run lint checks
- `npm run format` — run code formatter (prettier/eslint)
## Architecture Overview
- `backend/` — Express API, routes, controllers, services, data store (JSON file or SQLite)
- `frontend/` — React components + pages under `src/`
- Shared types: `shared/` folder for common types/interfaces
- API: `/api/notes` endpoints: GET, POST, PUT, DELETE
- State: frontend uses simple React context or useState; minimal global state
## Conventions & Patterns
- Use `camelCase` for variables and properties
- File naming: `PascalCase` for component files, lower-kebab-case for utility files
- Prefer functional React components; use hooks, no class components
- Always include types/interfaces (TypeScript)
- Format code using Prettier with `.prettierrc` (see project)
- ESLint rules enforced; import order: external → internal → relative
- For error handling, use `try/catch` + central error middleware
## Domain & Vocabulary
- Note = { id, title, body, createdAt, updatedAt }
- “Archive” means notes that are hidden but not deleted
- “Tag” is optional string label on a note
- “Full-text search”: simple keyword filter in title/body
## Git & PR Style
- Branches: `feature/`, `bugfix/`, `hotfix/`
- Commit messages: `<scope>: <verb> <what>` (e.g. `notes: add delete endpoint`)
- Before PR: run `lint`, `test`, `format`
- PR title matches commit message style; include summary + related issue if applicable
## Tips, Gotchas & Constraints
- Do not modify `shared/` types without updating both backend & frontend
- Avoid large dependencies; stick to lightweight libs
- Do not commit `.env` or secret keys
- When adding endpoints, ensure you write matching types/interfaces
- For production build, double-check environment variables are present
## Security & Secrets
- Secrets stored in `.env` (excluded from Git)
- Do not log sensitive info (e.g. raw request body) in production
- Validate user input (title, body) for length and type
- Escape strings or sanitize input if embedding HTML
That is the “source of truth” I expect the agent to use when generating or modifying code.
How an agent uses this AGENTS.md
- On each prompt, the agent reads
Core Commandsto know what commands to call (e.g. run tests, start dev). - When creating new files or endpoints, it follows
Conventions & Patterns(camelCase, file naming, formatting). - It refers to
Architecture Overviewto know where to place a new module or which folder it belongs in. - Domain vocabulary (Note, Archive, Tag) ensures that the agent uses your domain names consistently, not inventing synonyms or conflicting terms.
- Git & PR style helps the agent construct commit messages or even stage changes in a way you expect.
- Tips & constraints warn the agent what not to do (e.g. don’t alter
shared/types carelessly). - Security section guards against footguns (e.g. not writing secrets in code, validating input).
If later I decide to expand the project (e.g. add authentication, tagging, search index), I update the AGENTS.md rather than having to instruct agents in each prompt.
Why this setup helps in vibe coding
Without AGENTS.md, every prompt has to re-explain your stack, naming conventions, folder structure, domain, etc. With it, the agent starts from baseline context. That saves tokens and avoids repetitive mistakes.
Over multiple edits, agents tend to drift (style inconsistencies, misnaming, contradictory patterns). The AGENTS.md is a fixed anchor the agent can re-refer to. You can even instruct “Before applying changes, reread AGENTS.md and align with the rules.”
Rather than re-stating “In this project we use camelCase, functional components, Prettier, TypeScript, no semicolons,” your prompt can be concise. The agent “knows” the rules from AGENTS.md.
As project grows, you can add nested AGENTS.md for submodules (e.g. backend/AGENTS.md) to offer more fine-grained rules without cluttering the root file.
Writing a decent AGENTS.md forces you to clarify your conventions, architectural decisions, and domain language explicitly rather than leaving them implicit.
Tips & pitfalls from my experience
It takes some time and a lot of practice to get your Agents to do what you want them to do, even with a dedicated file that tries to keep them in check. Here are some of my personal experiences and advice to help you avoid wasting time like I did.
- Keep AGENTS.md concise. Don’t overload it with everything. Only include things you’d actually want the agent to reference frequently.
- Test by prompting mistakes. Intentionally ask the agent to violate a rule and see if it corrects itself based on AGENTS.md. Refine phrasing accordingly.
- Version it. As your conventions evolve, update AGENTS.md. The agent can even propose AGENTS.md edits if asked.
- Use decision logs. In communities doing vibe coding, folks often maintain a
decision-log.mdwhere each change is annotated with why; that becomes extra context in prompts. - Watch for context limits. If your codebase is large, agents may not see the entire AGENTS.md plus your full code. Keep crucial rules early in the file.
- Avoid contradictions in AGENTS.md. If two lines conflict (e.g. “always use semicolons” vs “omit semicolons”), the agent will be confused.
- Use nested AGENTS.md when needed. For example,
backend/AGENTS.mdcan override or add rules specific to API layer. - Be explicit about domain terms. If your domain has special names or meanings, define them in AGENTS.md so the agent doesn’t invent weird synonyms or misinterpret.
When my project grows (many modules, complex business logic, microservices), I modify the approach:
- Split AGENTS.md into core + plugin style: root file covers global conventions, nested files cover module-specific rules.
- Add a “dependencies and external services” section (e.g. which APIs, databases, network constraints).
- Include performance or architecture constraints (e.g. caching, rate limits, concurrency).
- Offer scaffolding templates or snippet references inside AGENTS.md (e.g. “when creating a new route, use this skeleton”).
At all times, though, I treat AGENTS.md as a living file — update it when the project changes, keep it minimal but sufficient, and rely on it as the stable context anchor for agents.
Final thoughts
If I were doing a new simple vibe coding project today, I’d start by drafting a minimal AGENTS.md based on the template above. I’d iteratively test prompts, catch where the agent messes up, and refine rules bit by bit. Over a few sprints, that AGENTS.md becomes your project’s “agent brain” — letting you focus on features, not re-teaching the AI every time.
Maybe the most important thing is to really acknowledge that even cutting edge tools/models (like Codex and Claude) are quite “stupid” and eventually lose track of what they are doing. But from my own experience, creating instructions with the Agents file does improve results by a lot!
Do you have any additional tips that I didn’t cover in this post? Let me know in the comments.
