Use case · All use cases

How to write an AGENTS.md file (beginner template and example)

Short answer: an AGENTS.md file is a plain Markdown file in the top folder of your project that tells AI coding agents how to behave. For beginners, five or six short rules are enough: explain in plain English, make one change at a time, ask before deleting anything, never put secrets in code, and stop after two failed fixes.

Why a beginner needs one

Without rules, AI coding tools tend to make big, sweeping changes you can't follow. A short rules file nudges them to work in small, reviewable steps. It is not magic: tools may still ignore a rule sometimes, so keep reviewing what changes.

A simple agents.md template

Copy this into a file named AGENTS.md in your project's top folder and fill in the brackets:

# Project rules for AI helpers

## About this project
- What it is: [ONE SENTENCE ABOUT YOUR APP]
- Who I am: a beginner. Explain things in plain English.

## How to work
- Make one small change at a time, then stop and tell me what changed.
- Ask before deleting files or installing new packages.
- Never put API keys or passwords in code. Use a .env file listed in .gitignore.
- If a fix fails twice, stop and explain the problem instead of trying again.

Where it works

Cursor, OpenAI Codex and GitHub Copilot's agent read AGENTS.md. Claude Code reads CLAUDE.md, so create a CLAUDE.md whose first line is @AGENTS.md. For tools like Lovable, Bolt or Replit, paste the same rules into the project's custom instructions. More detail: AGENTS.md for beginners.

AGENTS.md vs CLAUDE.md

Same idea, different file name. Keep your rules in AGENTS.md and point CLAUDE.md at it, so you only maintain one file.

Free and paid help

• Free: the 5-prompt Kit.
• $12 Starter Pack: includes a fuller beginner AGENTS.md template plus a prompt that helps your AI write one for your specific project.