Why AGENTS.md?

Without AGENTS.md, every AI interaction starts from zero:

You: "Add a new API endpoint"
AI:  *Uses CommonJS, creates a callback-based Express route,
      puts business logic in the route handler*
You: "No, we use ESM, async/await, and services..."

With AGENTS.md, the AI already knows your conventions:

You: "Add a new API endpoint"
AI:  *Creates ESM module, uses async/await, puts logic in
      a service, follows your naming conventions*

AGENTS.md is a one-time investment that saves time on every future interaction.

The Structure

A comprehensive AGENTS.md has five sections:

# AGENTS.md

## 1. Project Overview
What this project is, what it does, tech stack.

## 2. Architecture
How the code is organized, key patterns.

## 3. Code Style
Formatting, naming, conventions, language features.

## 4. Common Tasks
Step-by-step guides for frequent operations.

## 5. Pitfalls
Things the AI (and new developers) commonly get wrong.

Place it in the root of your project. AI tools like Claude Code, OpenCode, and Cursor automatically detect and read it.

Writing the Project Overview

Start with context the AI can't infer from code alone:

## Project Overview
Multi-tenant SaaS analytics platform.
- **Backend:** Node.js 20, Express, ESM modules, MongoDB
- **Frontend:** React 18, Mantine UI, Vite
- **Auth:** JWT tokens, bcrypt password hashing
- **Deployment:** Docker container, single image serves API + static frontend
- **Testing:** Jest for backend, Vitest for frontend
- **API Style:** RESTful, OpenAI-compatible gateway endpoints

Key details to include:

• Business domain (SaaS, e-commerce, healthcare, etc.)
• Why certain technologies were chosen
• Major integrations (Stripe, AWS, etc.)
• Target audience (internal tool, public API, consumer app)

Defining Code Conventions

This is where AGENTS.md pays for itself:

## Code Style

### JavaScript/Node.js
- ESM modules only (`import/export`, never `require`)
- `async/await` everywhere — no callbacks, no raw `.then()`
- `const` by default, `let` only when reassignment is needed
- All functions: JSDoc with `@param` and `@returns`
- Error handling: throw `AppError` instances, never plain strings

### Naming
- Files: kebab-case (`user-service.js`, not `UserService.js`)
- Variables/functions: camelCase
- Constants: UPPER_SNAKE_CASE
- Database models: PascalCase (`Tenant`, `RequestLog`)

### API Routes
- Always return `{ data }` on success
- Always return `{ error: "message" }` on failure
- Use appropriate HTTP status codes (201 for create, 204 for delete)
- Validate all input with express-validator

### Frontend
- Functional components only — no class components
- Custom hooks in `/hooks` directory
- Shared components in `/components`
- Page-level components in `/pages`

Documenting Common Tasks

Give the AI step-by-step playbooks:

## Common Tasks

### Adding a New API Route
1. Create `server/routes/admin/myroute.js`
2. Export a router with GET/POST/PUT/DELETE handlers
3. Import and mount in `server/index.js` with RBAC middleware:
   - `adminOrMaint` for write operations
   - `anyUser` for read-only endpoints
4. Add input validation using sanitize helpers
5. Create or update the corresponding service in `server/services/`

### Adding a New Database Model
1. Create `server/models/MyModel.js` with Mongoose schema
2. Add indexes for frequently queried fields
3. Include `timestamps: true` in schema options
4. Export both the model and the schema

### Running Tests
- Backend: `npm run test:server`
- Frontend: `npm run test:frontend`
- All: `npm test`
- Coverage: `npm run test:coverage` (minimum 80%)

Listing Pitfalls

Prevent the AI from making mistakes you've seen before:

## Pitfalls — Things That Commonly Go Wrong

### DON'T
- Don't use `process.env` directly — always go through `config.js`
- Don't put business logic in route handlers — use services
- Don't use `var` — ever
- Don't commit `.env` files
- Don't use `any` type in TypeScript without a comment explaining why
- Don't use synchronous file operations in request handlers
- Don't trust user input — always sanitize with `sanitize.js`

### WATCH OUT FOR
- MongoDB injection: always use parameterized queries
- Context window: when editing large files, read the file first
- Import paths: use `.js` extension in ESM imports
- Port conflicts: dev server runs on 3000, frontend on 5173

Pro tip: Every time the AI makes a mistake, add it to the pitfalls section. Your AGENTS.md becomes a living document that gets smarter over time.

Agent Self-Improvement

Here's the advanced technique: let the AI improve its own instructions.

After a coding session, ask:

Review the changes we just made. Were there any conventions
or patterns you had to discover by reading the code that
should have been documented in AGENTS.md?

Update AGENTS.md with any missing conventions.

The AI will:

1. Analyze what it learned during the session
2. Identify patterns it had to infer rather than read
3. Add those patterns to AGENTS.md
4. Future sessions will be more efficient

The virtuous cycle:

Use AI → AI discovers patterns → Update AGENTS.md →
AI reads AGENTS.md → AI follows patterns → Better code →
AI discovers more patterns → ...

This is one of the most powerful techniques in AI-assisted development.

---quiz question: What is the primary purpose of AGENTS.md? options:

• { text: "To document the API for end users", correct: false }
• { text: "To define project conventions so AI coding agents follow your code style automatically", correct: true }
• { text: "To configure deployment pipelines", correct: false } feedback: AGENTS.md teaches AI coding tools your project's conventions — code style, architecture patterns, common tasks, and pitfalls — so they produce code that fits your project naturally, without you repeating instructions every time.

---quiz question: What is "agent self-improvement" in the context of AGENTS.md? options:

• { text: "The AI automatically updates its own model weights", correct: false }
• { text: "Asking the AI to identify undocumented patterns and update AGENTS.md", correct: true }
• { text: "Reinstalling the AI agent to get the latest version", correct: false } feedback: After a coding session, you can ask the AI to review what patterns it had to discover on its own and add them to AGENTS.md. This creates a virtuous cycle where each session makes the next one more efficient.

---quiz question: Why should you include a "Pitfalls" section in AGENTS.md? options:

• { text: "To make the file longer and more impressive", correct: false }
• { text: "To prevent the AI from making mistakes you've already encountered", correct: true }
• { text: "To document bugs in the AI tool itself", correct: false } feedback: The pitfalls section captures common mistakes so the AI avoids them proactively. Every time the AI makes an error, adding it to the pitfalls section prevents it from recurring in future sessions.