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:

  1. Project overview
  2. Coding conventions
  3. Architecture constraints
  4. Do
  5. Don’t
  6. File and folder scope
  7. PR and commit expectations
  8. 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.