How to make AI follow your project's rules: CLAUDE.md and Cursor
CLAUDE.md, Cursor project rules and AGENTS.md explained, with a short example you can adapt
You told the AI to use your design system. Next session, it builds a new button from scratch. You said never to touch the payments folder, and there it is in the diff. AI coding tools do not remember your project between sessions; each session starts fresh. The fix is a rules file: a short document in your project that the tool reads every time it starts work.
What a rules file is
A rules file is plain text, usually Markdown, that lives in your repository next to the code. The tool loads it into its context at the start of a session, so your conventions are in place before the first request. Because it sits in the repository, it is versioned with Git and shared with everyone who works on the project, human or AI.
It is guidance, not a lock. Anthropic's documentation says Claude treats CLAUDE.md as context rather than enforced configuration. If something must never happen, back the rule with a hard control as well, such as a hook, a permission setting or a protected branch.
CLAUDE.md for Claude Code
Claude Code reads CLAUDE.md files at the start of every session. The main locations, according to the official memory documentation, are:
./CLAUDE.mdor./.claude/CLAUDE.mdin the project, shared with the team through Git.~/.claude/CLAUDE.mdin your home folder, for personal preferences across all your projects.CLAUDE.local.mdin the project root, for private notes on one project; add it to.gitignore.
Run /init inside Claude Code and it drafts a CLAUDE.md from what it finds in your code, including build and test commands. A CLAUDE.md can pull in other files with @path/to/file, and rules that apply only to part of the code can go in .claude/rules/. Anthropic suggests keeping each CLAUDE.md under about 200 lines, because longer files use more context and are followed less consistently.
Project rules in Cursor
Cursor keeps project rules in a .cursor/rules folder, one rule per .mdc file, as described in Cursor's rules documentation. Each file starts with a short header with a description, optional globs for file patterns, and alwaysApply. Those fields decide whether a rule always applies, applies when the agent judges it relevant, applies to matching files, or is used only when you mention it. Cursor also has user rules in its settings for preferences that follow you across projects. The older single .cursorrules file in the project root is a legacy format; Cursor recommends project rules instead.
AGENTS.md, the shared option
AGENTS.md is an open format: a plain Markdown file in the project root that works as a README for coding agents. It is a real, widely adopted convention. Its site lists compatible tools including OpenAI Codex, Google's Jules and Gemini CLI, GitHub Copilot's coding agent, Cursor, Windsurf and Zed, and says the format is now stewarded by the Agentic AI Foundation under the Linux Foundation.
Cursor reads AGENTS.md in the root and in subfolders. Recent versions of Claude Code read AGENTS.md when the project has no CLAUDE.md; when both exist, Claude Code reads CLAUDE.md. If your team uses several tools, keep the content in AGENTS.md and add a line such as @AGENTS.md to CLAUDE.md to import it. One source of truth beats two files that slowly drift apart.
What to put in it
- Stack: framework, language, database, hosting, and the versions that matter.
- Commands: how to install, run, test, lint and build. These save the AI from guessing.
- Folder layout: where pages, components, server code and database migrations live.
- Conventions: naming, styling approach, error handling, and which shared components to reuse.
- Never-do list: files and folders not to touch, packages not to add, commands not to run.
- Security rules: no secrets in code, validate input on the server, check permissions on every data access, and keep database access rules switched on.
Leave out what the tool can see for itself, such as a full file listing or code it can read directly. Write each rule as a short, specific instruction. "Use the Button component in components/ui" works better than "keep the UI consistent".
A short example
Here is a compact rules file for a small Next.js app with a hosted Postgres database. It works as a CLAUDE.md or an AGENTS.md:
# Project: bookings appStack: Next.js (App Router), TypeScript, Postgres, deployed on VercelRun: npm run dev | Test: npm test | Lint: npm run lintLayout: app/ routes, components/ui shared UI, lib/ server helpers, db/migrations SQLConventions: reuse components/ui; never import server code into client componentsNever: edit a migration that has already run; add a package without askingSecurity: secrets only in environment variables; check the signed-in user in every server actionBefore finishing: run lint and tests, then list the files you changed
Eight lines, and each one changes behaviour. That is the target.
Keep it short and current
A rules file that describes last month's project is worse than none, because the AI follows it confidently. Treat it like code: update it in the same commit as the change that made it out of date. When you correct the AI for the same mistake twice, add a line. Every few weeks, read it from top to bottom and delete what no longer applies. If the file keeps growing, some of it probably belongs somewhere else.
Where skills fit
Rules hold the facts that apply to every task. Skills hold know-how that only some tasks need. In Anthropic's Agent Skills model, a skill is a folder with a SKILL.md file of instructions, plus optional reference files. Only the skill's short description is loaded up front; the full instructions load when a task calls for them, or when you invoke the skill by name. Anthropic's advice is to turn a section of CLAUDE.md into a skill once it has grown from a fact into a procedure.
A practical split: your rules file says "we deploy on Vercel and run tests before every commit", and a skill holds the step-by-step release checklist. Claude Code skills follow the open Agent Skills standard. Our guide to skills for Next.js and Supabase apps shows examples for a common stack.
Your next step
Open your project, run /init in Claude Code or create AGENTS.md by hand, and cut it down to the lines that matter. If you are starting from zero, follow your first app with Claude Code first, then browse the skills catalogue for packaged know-how that fits your stack.