AI coding assistants like Cursor, Copilot, and Claude Code are powerful, but they often guess wrong about your project's conventions. They might use tabs when you use spaces, or break your architectural patterns. The fix is a project rules file — a simple text file that tells the AI how to behave. This tutorial walks you through creating an AGENTS.md file, the de facto standard used by many AI coding tools today.

What is AGENTS.md?

AGENTS.md is a markdown file placed in your repository root (or subdirectories) that contains instructions for AI coding agents. Tools like Cursor, Claude Code, and Codex automatically read it to understand your project's context, style, and preferred workflows. It's like a README, but for the AI instead of humans.

Why AGENTS.md? Instead of pasting the same context into every chat, you write it once. The AI reads it automatically, saving you time and improving consistency.

Step 1: Add a Project Overview

Start with a short description of what the project does and its architecture. This helps the AI understand the big picture before touching code.

# AGENTS.md

## Project Overview

This is a FastAPI-based REST API for inventory management. It uses SQLAlchemy with PostgreSQL and is deployed to AWS Lambda. The codebase follows a layered architecture: routes → services → repositories.

Step 2: Define Code Style and Conventions

Be explicit about formatting, naming, and patterns. Use bullet points for easy scanning.

## Code Style

- Use 4 spaces for indentation, not tabs
- Use double quotes for strings, single quotes for chars
- Name variables in snake_case, classes in PascalCase
- Keep functions small — max 30 lines
- Prefer list comprehensions over map/filter
- Write type hints for all function signatures

Don't overdo it. Only include rules that are non-obvious or that the AI has gotten wrong before. Too many rules dilute the important ones.

Step 3: Describe Architecture & Key Patterns

If your project uses a specific design pattern, explain it so new code fits in. Example: say that all database access must go through the repository layer, never directly from routes.

## Architecture & Patterns

- Routes call service objects, never repositories directly
- Services handle business logic and transactions
- Repositories wrap SQLAlchemy queries, return models
- Use dependency injection for services and repositories
- Never use raw SQL unless absolutely necessary

## Error Handling

- Raise HTTPException with a message and status code
- Use custom exceptions for domain errors
- Catch exceptions only where you can recover

Step 4: Add Common Tasks and Workflows

List repeated tasks like adding a new endpoint, running tests, or creating a migration. The AI will follow these steps when asked to do similar work.

## Common Tasks

### Adding a New Endpoint

1. Create a route in app/routes/ with validation schemas
2. Add a service method in app/services/
3. Implement repository method if needed
4. Register route in app/main.py
5. Write tests in tests/
6. Run `pytest` to verify

## Build & Test Commands

- Run tests: `pytest`
- Run linter: `ruff check .`
- Run formatting: `black .`

Warning: AI agents may not automatically run these commands unless you explicitly ask. To make the rules more binding, phrase them as direct instructions: "Before submitting code, always run pytest and fix failures."

Step 5: Keep Rules Concise and Actionable

Use short, imperative sentences. Avoid vague wording like "write clean code" — define what clean means for your project. Aim for 20–50 lines total. If it gets longer, consider splitting by directory.

Step 6: Test and Iterate

Open your AI tool, make a small change, and see if the output follows the rules. If not, adjust. For example, if the AI still uses single quotes, add: "Quotes: always double quotes, even in imports."

Success! Once your rules are working, new contributors and AI agents will produce consistent, on-style code without you having to repeat yourself. Revisit the file monthly as your project evolves.

Beyond AGENTS.md

Some tools support additional files. Cursor uses .cursor/rules and Copilot uses .github/copilot-instructions.md. You can start with AGENTS.md and add tool-specific files later for finer control.

# Example tool-specific rules structure

AGENTS.md
.cursor/rules/backend.mdc
.github/copilot-instructions.md

Start with a simple AGENTS.md today. You'll see a noticeable improvement in how AI generation aligns with your codebase — and you'll spend far less time fixing AI-generated mistakes.