Turn Your Cursor Rules Into One Root AGENTS.md

Many of the reporter's repositories still contain Cursor rules in various forms, such as a dusty .cursorrules file at the root, or a collection of .mdc files under .cursor/rules/. Some rules are even typed directly in the UI and never exported. While Cursor handles these rules well, the reporter finds it annoying that the same repository also requires a root file like AGENTS.md or CLAUDE.md. These files do not appear automatically and often end up with multiple versions that differ slightly.

The reporter's solution to this issue is a simple workflow. First, gather the existing information from the repositories. This includes the text in .cursorrules if available, the useful bits from .cursor/rules/*.mdc, and any build/test/do not edit notes you would share with a new hire. It is essential to copy paths and commands exactly, as they should remain unchanged under the matching heading. If a converter rewrites these into vaguer English, discard that output.

Next, organize the gathered information into the same headings every time. The reporter uses eight sections for this process, which includes project overview, coding conventions, architecture constraints, do/don't guidelines, file and folder scope, PR and commit expectations, testing, and any other relevant information. If no information is available for a particular section, leave it as "Not specified."

Then, combine the content into a single source of truth file, depending on the tool that will open the repository. The reporter suggests using AGENTS.md for a common shared root brief, CLAUDE.md for when that is the house standard, and a shorter version for a one-off local brief. This way, there is only one source of truth for what the team has said, and the format can be flipped depending on the runner.

Finally, commit the root file so that a fresh clone receives the same brief. Keep UI-only or Cursor-only tips under .cursor/rules/, as other tools do not need Cursor UI preferences. The reporter provides a raw paste example and a sorted root file as examples of how the content should be structured. This approach ensures that the root file is short enough to skim, with do/don't guidelines in bullet form, test and lint commands copy-pasteable, and path globs matching the real tree structure.

Finally, the reporter reminds teammates that the root file should be checked in, short, and kept current, while Cursor-only details should remain under .cursor/rules/.