Stop Fixing AI Code Manually – AGENTS.md Is the Setup You Actually Need
If you have been working with AI coding assistants for a while, you know the drill. You ask for a feature, the AI generates something close but not quite right, and you spend the next twenty minutes correcting directory placements, styling approaches, and naming conventions that somehow never survived the conversation.
The problem is not the AI capability. It is context. Without a shared reference for your project rules, every session starts from scratch and ends in corrections.
AGENTS.md is the fix. It is a project specification file written for AI coding assistants, the same way .eslintrc handles linting rules or tsconfig.json tells TypeScript how to behave.
The Analogy That Makes It Click
- .eslintrc tells ESLint single quotes or double quotes
- .prettierrc tells Prettier how to format
- tsconfig.json tells TypeScript how to type-check
- AGENTS.md tells AI where components live, what styling approach to use, which files are off-limits
Without it, you are working with an AI that is highly capable but completely unaware of your team conventions. With it, the AI plays by your rules from the first message.
A Template You Can Copy in 5 Minutes
Drop this in your project root, replace the bracketed sections, and you are set.
# AGENTS.md
## Tech Stack
- Framework: [Vue 3 / React / Next.js] + TypeScript
- Package manager: [yarn / pnpm / npm]
- Styling: [Less / Sass / Tailwind CSS] + CSS Modules
- UI library: [Element Plus / Ant Design / Material UI] v[version]
## Project Structure
src/
components/ # Shared components (PascalCase)
views/ # Page components
composables/ # Composables (Vue 3) / hooks/ (React)
api/ # API layer (Vue 3) / services/ (React)
stores/ # State management
utils/ # Utility functions
types/ # TypeScript definitions
constants/ # Constants
## Coding Style
**TypeScript**
- Use defineProps<Interface>() for Props
- Component naming: PascalCase, filename index.vue
- Never use the `any` type
- Never use Options API (Vue)
**Styling**
- Never use inline styles
- Never hardcode color values
## Build Commands
[yarn dev] # Start dev server
[yarn build] # Production build
[yarn lint] # Format code
## Never Rules
- Never modify framework-generated directories
- Never modify dist/ build output
- Never use `any` type in components
- Never use inline styles
- Never put long operations in render paths
- Never omit `key` in v-for loops
- Never hardcode sensitive information
- Never modify lock files
- Never use Options API
## Commit Format
Format: type(scope): description
Types: feat / fix / docs / style / refactor / test / chore
FAQ
Q: Where does AGENTS.md go?
Project root, alongside package.json and tsconfig.json. AI coding assistants automatically scan the root for this file.
Q: Should I commit it to Git?
Yes. It is a shared team specification. Add AGENTS.local.md (personal preferences) to .gitignore.
Q: How long should it be?
- Minimum viable: 30 lines (tech stack + structure + 3 Never rules)
- Recommended: 60-100 lines
- Do not exceed: 200 lines
Q: Which AI tools work with it?
Verified: Cursor, Claude, GitHub Copilot, Windsurf.
Q: How do I add this to an existing project?
Create AGENTS.md in the project root, copy the template, fill in your specifics, and commit. No code changes, no new dependencies.
Q: Vue 3 specific tips?
- Use views/, composables/, api/, stores/, types/ directories
- Enforce Composition API with <script setup>
- Add “Never use Options API” to Never Rules
- Use Pinia over Vuex for state management
The Bottom Line
AGENTS.md will not make your AI coding assistant smarter. But it will make it more predictable, which in practice means less time correcting and more time shipping.
If you have been manually fixing AI output on every task, the real fix is not more patience. It is adding this one file to your project root.
