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.
Not an essay. Not a second README. Something an editor (or a teammate) can skim in under a minute:
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.
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.
Pull the text you trust today:
.cursorrules if you still have the old single file.cursor/rules/*.mdc
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.
I use eight sections so I am not inventing a new outline per repo:
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.
Same content, different filename depending on who opens the repo:
AGENTS.md — common shared root brief
CLAUDE.md — when that is the house standard
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.
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.
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:
## 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.
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 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.
.cursor/rules/
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.