Turn Your Cursor Rules Into One Root AGENTS.md

Lian Zhaofu — Tue, 10 Nov 2026 01:11:55 +0000

Most of my repos still have Cursor rules in some form. Sometimes a dusty .cursorrules at the root. Sometimes a pile of .mdc files under .cursor/rules/. Sometimes rules I typed in the UI and never exported.

That is fine for Cursor. It is annoying when the same repo also needs a short brief at the root — AGENTS.md, or CLAUDE.md if that is what the team agreed on. Those files do not appear by magic from your Cursor rules. You either copy-paste by hand, or you end up with three slightly different versions that drift.

I got tired of the drift. Here is the boring workflow I use now.

What I actually want in the root file

Not an essay. Not a second README. Something an editor (or a teammate) can skim in under a minute:

what the project is
how we write code here
what not to touch
clear do / don’t lines
which folders matter
PR / commit habits
how to run tests (real commands)

Cursor rules often already say most of that. They just say it in long paragraphs, with “always” and “never” buried mid-sentence. Sorting beats rewriting.

A layout that does not fight Cursor

What stuck for me:

Path	Role
`/AGENTS.md`	Short shared brief at the root
`/.cursor/rules/*.mdc`	Cursor-only detail
`/CLAUDE.md`	Only if that is the team standard
`/docs/` (optional)	Longer notes; link from the short root file

Keep the root file short. Bullets and path globs over prose. If something needs two pages of architecture, put it in docs and link it. Do not dump a design doc into the one file everyone loads every time.

Step 1 — gather what is already true

Pull the text you trust today:

.cursorrules if you still have the old single file
the useful bits from .cursor/rules/*.mdc
the same build / test / “do not edit” notes you would tell a new hire

Paste paths and commands exactly. pnpm test, cargo clippy, app/api/** — those strings should survive under the matching heading. If a converter rewrites them into vaguer English, throw that output away.

Step 2 — sort into the same headings every time

I use eight sections so I am not inventing a new outline per repo:

Project overview
Coding conventions
Architecture constraints
Do
Don’t
File and folder scope
PR and commit expectations
Testing

If you never wrote anything about PRs, leave that section as “Not specified.” Empty honesty is better than inventing a commit style you do not follow.

Step 3 — one paste, pick the filename the tool expects

Same content, different filename depending on who opens the repo:

AGENTS.md — common shared root brief
CLAUDE.md — when that is the house standard
something shorter for a one-off local brief if you need it

The point is one source of truth for what you said. Flip the format when the runner changes. Do not maintain three hand-edited forks.

Step 4 — commit the root file; leave Cursor nuance local

Check in /AGENTS.md (or /CLAUDE.md) so a fresh clone gets the same brief. Keep UI-only or Cursor-only tips under .cursor/rules/. Other tools do not need your Cursor UI preferences.

Tiny example

Raw paste:

This is a Next.js App Router app. Prefer server components.
Never edit /prisma/migrations by hand.
Run pnpm test and pnpm lint before PR.
Do not commit .env.
API routes live under app/api.

Sorted root file:

# AGENTS.md

## Project overview
Next.js App Router application.

## Coding conventions
Prefer server components.

## Architecture constraints
API routes live under `app/api`.

## Do
- Run `pnpm test` and `pnpm lint` before opening a PR.

## Don't
- Do not edit `/prisma/migrations` by hand.
- Do not commit `.env`.

## File and folder scope
- `app/api/**` — API routes

## PR and commit expectations
Not specified.

## Testing
- `pnpm test`
- `pnpm lint`

Nothing clever happened. The lines landed under headings. That alone stops a lot of guesswork.

Privacy, briefly

Rules often name internal paths, products, and “never touch” folders. Prefer a sort that runs in the browser, does not upload the paste, and does not call a model to “improve” your wording. Structure is the job. Paraphrase is optional and usually unhelpful.

When I need the file tonight

When I already have Cursor rules and I just need the root file tonight, I paste into rules2md. It sorts into AGENTS.md (or switch to CLAUDE.md), keeps my wording, marks missing sections as not specified, and stays local in the browser — copy or download, no account. If you would rather hand-author from the section list above, that works too. The outline is the useful part.

Before you merge

Root file short enough to skim
Do / don’t are bullets
Test and lint commands are copy-pasteable
Path globs match the real tree
Missing sections say “not specified”
Cursor-only detail stays under .cursor/rules/
Teammates know which root file is canonical

You do not need louder prompts. You need one honest root brief that matches the rules you already keep for Cursor. Sort first. Paraphrase only if you choose to. Treat AGENTS.md / CLAUDE.md like README.md: checked in, short, and kept current.

If your team splits Cursor rules and root briefs differently, leave a comment — I am still tweaking this on side projects and happy to compare notes.

DEV Community: Lian Zhaofu