# Turn Your Cursor Rules Into One Root AGENTS.md

> Source: <https://dev.to/lianzhaofu/turn-your-cursor-rules-into-one-root-agentsmd-10ni>
> Published: 2026-11-10 01:11:55+00:00

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:

```
# 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.

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](https://rules2md.com/). 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.