{"slug": "turn-your-cursor-rules-into-one-root-agents-md", "title": "Turn Your Cursor Rules Into One Root AGENTS.md", "summary": "A developer described a workflow for consolidating Cursor rules — legacy `.cursorrules` files and `.cursor/rules/*.mdc` files — into a single short root `AGENTS.md` (or `CLAUDE.md`) brief, sorting existing rule text into eight fixed sections rather than rewriting it. The approach preserves exact paths and commands like `pnpm test` and `app/api/**`, marks unwritten sections as \"Not specified,\" and recommends browser-local conversion tools that avoid uploading content or paraphrasing it with a model.", "body_md": "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.\n\nThat 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.\n\nI got tired of the drift. Here is the boring workflow I use now.\n\nNot an essay. Not a second README. Something an editor (or a teammate) can skim in under a minute:\n\nCursor rules often already say most of that. They just say it in long paragraphs, with “always” and “never” buried mid-sentence. Sorting beats rewriting.\n\nWhat stuck for me:\n\n| Path | Role | \n|---|---|\n| `/AGENTS.md` | Short shared brief at the root | \n| `/.cursor/rules/*.mdc` | Cursor-only detail | \n| `/CLAUDE.md` | Only if that is the team standard | \n| `/docs/` (optional) | Longer notes; link from the short root file | \n\nKeep 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.\n\nPull the text you trust today:\n\n`.cursorrules` if you still have the old single file`.cursor/rules/*.mdc`\nPaste 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.\n\nI use eight sections so I am not inventing a new outline per repo:\n\nIf 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.\n\nSame content, different filename depending on who opens the repo:\n\n`AGENTS.md` — common shared root brief\n`CLAUDE.md` — when that is the house standard\nThe point is one source of truth for *what* you said. Flip the format when the runner changes. Do not maintain three hand-edited forks.\n\nCheck 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.\n\nRaw paste:\n\n```\nThis is a Next.js App Router app. Prefer server components.\nNever edit /prisma/migrations by hand.\nRun pnpm test and pnpm lint before PR.\nDo not commit .env.\nAPI routes live under app/api.\n```\n\nSorted root file:\n\n```\n# AGENTS.md\n\n## Project overview\nNext.js App Router application.\n\n## Coding conventions\nPrefer server components.\n\n## Architecture constraints\nAPI routes live under `app/api`.\n\n## Do\n- Run `pnpm test` and `pnpm lint` before opening a PR.\n\n## Don't\n- Do not edit `/prisma/migrations` by hand.\n- Do not commit `.env`.\n\n## File and folder scope\n- `app/api/**` — API routes\n\n## PR and commit expectations\nNot specified.\n\n## Testing\n- `pnpm test`\n- `pnpm lint`\n```\n\nNothing clever happened. The lines landed under headings. That alone stops a lot of guesswork.\n\nRules 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.\n\nWhen 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.\n\n`.cursor/rules/`\nYou 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.\n\nIf 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.", "url": "https://wpnews.pro/news/turn-your-cursor-rules-into-one-root-agents-md", "canonical_source": "https://dev.to/lianzhaofu/turn-your-cursor-rules-into-one-root-agentsmd-10ni", "published_at": "2026-11-10 01:11:55+00:00", "updated_at": "2026-11-10 01:21:40.753945+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-agents", "agent-protocols"], "entities": ["Cursor", "rules2md", "Next.js", "Prisma"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/turn-your-cursor-rules-into-one-root-agents-md", "markdown": "https://wpnews.pro/news/turn-your-cursor-rules-into-one-root-agents-md.md", "text": "https://wpnews.pro/news/turn-your-cursor-rules-into-one-root-agents-md.txt", "jsonld": "https://wpnews.pro/news/turn-your-cursor-rules-into-one-root-agents-md.jsonld"}}