# CLAUDE.md, AGENTS.md and Cursor rules, written from your code

https://gitmir.com/claude-md · updated 2026-10-07

The file your coding agent reads before every task decides what it knows about your product. What each file is, what belongs in it, why hand-written ones fall behind the code — and how to get the product part written from the product itself.

## In short

CLAUDE.md is the project instruction file Claude Code loads at the start of every session. AGENTS.md is the open, plain-Markdown equivalent read by Codex, Cursor, GitHub Copilot's coding agent, Gemini CLI and many other agents, and Cursor also reads its own project rules in .cursor/rules. Each is only as current as its last edit. GitMir writes the product part of these files — areas, customer paths, status flows, rules and records — from a model of your code that is updated on every push, and names the commit it was written on; agents that connect over MCP can skip the file and ask the live model instead.

## One idea, four file names

| File | Read by | Where it lives | Worth knowing |
| --- | --- | --- | --- |
| CLAUDE.md | Claude Code | ./CLAUDE.md or ./.claude/CLAUDE.md in the repository; ~/.claude/CLAUDE.md for your own rules | Loaded at the start of every session; files in parent folders are read too, and @path imports another file |
| AGENTS.md | Codex, Cursor, GitHub Copilot coding agent, Gemini CLI, Windsurf, Aider, Jules, Devin, Amp and more | Repository root, and inside sub-folders | Plain Markdown with no frontmatter; the file nearest to the code being edited wins |
| .cursor/rules/*.mdc | Cursor | .cursor/rules in the repository | Frontmatter decides when a rule applies — always, by file pattern or on request; the single .cursorrules file is the older form |
| .github/copilot-instructions.md | GitHub Copilot | .github in the repository | Repository-wide instructions for Copilot |

Using more than one agent? Keep one source. A common pattern is AGENTS.md as the source and a one-line CLAUDE.md that imports it with @AGENTS.md.

## What belongs in an agent rules file

- **Commands** — How to build, test and lint, with the exact flags. The agent runs what it reads.
- **Conventions that differ from the defaults** — Naming, structure and libraries the agent would not guess. Leave out what any model already does.
- **Where things live** — The areas of the product and the folders that implement them, so the agent starts in the right place.
- **The rules the product enforces** — What must hold — limits, permissions, which status can follow which — and what a change must never break. This is the part that is usually missing.
- **Boundaries** — Files and areas the agent must not touch, and when to stop and ask a person.
- **Short and current** — Every stale line is an instruction to do the wrong thing. A short file that is true beats a long one that was.

## The file describes the product on the day it was written

A rules file is a snapshot. Three hotfixes later the agent follows last quarter's product, and nothing tells it so — the file looks exactly as authoritative as the day it was written.

Nobody owns updating it. The person who changes a rule is fixing a bug, not editing CLAUDE.md, and the next agent session starts from the old rule.

And the rule a change breaks usually sits in another area. A short file names the conventions; it rarely names how a rule in billing restricts a screen in settings — which is the connection that turns a clean-looking diff into a broken customer path.

## A rules file written from a real product

The first lines of the file GitMir wrote for Supabase Studio from its published model — 173 lines in all. The rest lists customer paths, status flows, rules and records, then the tools to call before changing anything.

Supabase Studio · written by GitMir:

```
# Product model for agents

Supabase Studio

_Written by GitMir from the product model (2026-08-29). GitMir rewrites this file after every push — do not edit it by hand, and do not trust a copy older than your branch._

## What this product is made of

- **Database** — Managing the Postgres database itself: schemas, tables, functions, triggers, indexes, roles, extensions, publications, replication and backups.
- **Project Settings** — Project-level configuration: general settings, compute and disk add-ons, API keys, JWT signing keys, infrastructure and read replicas, log drains and webhooks.
- **Project** — A single Supabase project — the database and its services — and every tool the dashboard offers for working on it.
- **Project Integrations** — Postgres-side integrations installed into a project: cron jobs, queues, vault, foreign-data wrappers, GraphQL and the integrations marketplace.
- **Authentication** — Configuring the project's Auth service: end users, sign-in providers, email templates, MFA, sessions, rate limits, hooks and RLS policies.
- **Storage** — Buckets and their contents — file, analytics and vector buckets — plus storage access policies, S3 credentials and storage settings.
- **Table Editor** — The spreadsheet-style editor for table rows and schema: creating and altering tables, columns and foreign keys, and editing data in the grid.
- **Billing & Subscription** — Plan and subscription changes, payment methods, billing address and tax IDs, invoices and credits for the organization.
```

- [Open the Supabase model and its Connect AI tab](https://gitmir.com/models/supabase)

## Keep the product part current without editing it

- **Written from the model** — For a connected repository, GitMir writes the file for Claude Code (CLAUDE.md), Cursor (.cursor/rules/gitmir.mdc) or Codex and others (AGENTS.md) from the model each time you open it, and names the commit. https://gitmir.com/products/intelligence
- **Or ask the live model** — One MCP server in Claude Code, Cursor, VS Code or Codex: the agent asks the product before it edits, and each change is checked against it before it is committed. https://gitmir.com/products/vibe
- **See it first** — Eight open-source products are modelled in public. Open one and look at the file GitMir writes for it — no account. https://gitmir.com/models

## Questions

### What is the difference between CLAUDE.md and AGENTS.md?

CLAUDE.md is read by Claude Code. AGENTS.md is an open format read by Codex, Cursor, GitHub Copilot's coding agent, Gemini CLI and many other agents. The content can be the same; many teams keep AGENTS.md as the source and import it from CLAUDE.md with @AGENTS.md.

### Where do Cursor rules live?

In .cursor/rules as .mdc files, each with frontmatter that says when it applies. The single .cursorrules file at the repository root is the older form. Cursor also reads AGENTS.md.

### What should go in CLAUDE.md?

The commands to build and test, conventions that differ from the defaults, where each part of the product lives, the rules the product enforces, and the boundaries the agent must not cross. Keep it short and current: a stale line is an instruction to do the wrong thing.

### How do I keep CLAUDE.md up to date?

Do not write the product part by hand. GitMir writes it from a model of your code that is updated on every push, so the file you take after a push describes the product after that push; or connect the agent over MCP and it asks the live model instead of reading a snapshot.

### Can GitMir generate AGENTS.md or CLAUDE.md from my repository?

Yes. Connect the repository, and its Connect MCP tab in your GitMir account gives the file for Claude Code, Cursor or Codex with the product's areas, customer paths, status flows, rules and records — written from the model each time you open it.

### Do I still need a rules file if my agent connects over MCP?

Keep commands and conventions in the file. The knowledge of the product is better asked live: a file is a snapshot, and the model is current to the latest push.

## Read next

- [An MCP server for your codebase](https://gitmir.com/mcp-server)
- [Context engineering for coding agents](https://gitmir.com/context-engineering)
- [GitMir vs Claude Code](https://gitmir.com/compare/claude-code)
- [GitMir vs Cursor](https://gitmir.com/compare/cursor)
- [What MCP means for engineering teams](https://gitmir.com/blog/what-is-mcp-for-engineering-teams)