Cursor to Codex CLI: Migrating Rules to AGENTS.md

Recently, I said goodbye to Cursor after two years of heavy usage, and I'm now migrating all my coding workflows to the Codex CLI.

One of the biggest challenges in this transition was migrating all my Cursor Rules to work with Codex CLI (basically converting them into nested markdown files called AGENTS.md).

If you already get the "why" and just want the "how," jump straight to the solution.

Still not sure why any of this matters? Keep reading.

Why AI Agent Documentation Matters

Whenever I talk about writing helpful docs for AI agents, the most common reactions I get are somewhere along the lines of:

"Why do we even need to do all of this?"
"Let's just YOLO it."
"I tried it and didn't find any benefit."
"When is it actually worth all this effort?"

I've detailed my reasoning in a previous post that went mildly viral on Hacker News, but I'll summarize the core idea here with a newer (and I think better) analogy.

Imagine you're exploring gnarly unexplored terrain. If you're just doing short walks, quick iterations, exploring, mapping something out once and then forgetting about it, it doesn't make sense to clear out the terrain and lay down railway tracks for your little expedition. You'll just grab your bag and go.

But the moment you know you want to move across this terrain repeatedly and efficiently, it starts making sense to clear the terrain and lay down railway tracks. Yes, there's upfront work, but once you do it, you'll eventually see the payoff. You'll be able to move much more cargo at much higher velocity and throughput on things you do frequently.

In the AI coding world: if you're just writing short scripts and throwing them away or writing a proof of concept, setting up elaborate documentation for AI agents doesn't make much sense.

But once you start building something serious, a codebase you'll work on for weeks and months, maybe you're past the MVP stage and building a company (like me), it will start making sense. You will very likely be building multiple features using the same API patterns, the same ways of exposing backends and frontends, the same interface approaches, that's when laying down these "railway tracks" becomes incredibly valuable.

These railway tracks take different forms for AI agents:

Structured codebase with consistent patterns
Automated tooling (linters, type checkers, tests)
Documentation that teaches agents how your project works

For today's post, we're focusing on number three. This is basically documenting the knowledge you'd give a new developer so they can effectively work on your project. Different coding tools call this differently: Claude has claude.md, Cursor has Cursor Rules, and now we're broadly converging on something called AGENTS.md, which is an open standard.

Much of my coding over the last two years has been done through Cursor, so I've invested heavily in number three with Cursor Rules. In retrospect, this was the single greatest investment I've made while coding.

I'd classify myself as a bad to average programmer on my own. But with this approach, I become something like a very good programming manager for AI agents. It's been working so well that I have confidence to ship code to clients and I've been able to build a company.

When I started migrating away from Cursor to Codex CLI (here's why, but in short, cost), my Cursor Rules investment was one of the main sticky factors keeping me there. Every repository I work with has at least six to ten custom rules that define exactly how my agents should behave.

The challenge was keeping all my Cursor rules when switching to Codex CLI. Obviously I automated it. Let me walk you through how that works.

The Solution: AGENTS.md Migration

A Note Before You Start I wrote the script to cover the migration patterns I run into most often. I highly recommend reading How the Script Works to understand the decisions baked into it—this will help you tweak the script for your own repository's quirks. But if you're feeling YOLO, you can jump straight to running the migration.

How the Migration Script Works

In case you don't know the context, Cursor Rules are markdown files with YAML frontmatter. The YAML frontmatter does a bunch of stuff—you can give instructions to auto-attach using descriptions, or you can give glob patterns (like src/components/**/*.tsx) and it'll automatically attach when working with those files. They can be nested in folders and automatically attach when relevant files are referenced.

AGENTS.md is similar, but you don't get all the fancy auto-attachment features. It's a very simple markdown file that can also be nested in folders, and agents automatically look into the folder when they're working on files in that directory.

Our goal is to convert from Cursor Rules to AGENTS.md. My migration script handles this in three main scenarios:

1. Simple Case: Consolidation This is for the straightforward cases where rules are consolidated into a single AGENTS.md file.

First, if you have a single global rule in your root .cursor/rules folder, it gets converted directly into a root AGENTS.md file.

# Before: Single Global Rule
.cursor/rules/
└── global.mdc

# After
AGENTS.md # Contains content from global.mdc

Second, for subdirectory rules, the script merges all rules inside a specific .cursor/rules folder (like src/api/) into a single AGENTS.md file in that same directory.

# Before: Subdirectory Rules
project/
└── src/
    ├── components/
    │   └── .cursor/rules/
    │       └── react-patterns.mdc
    └── api/
        └── .cursor/rules/
            ├── auth.mdc
            └── validation.mdc

# After
project/
└── src/
    ├── components/
    │   └── AGENTS.md  # Content from react-patterns.mdc
    └── api/
        └── AGENTS.md  # Merged content from auth.mdc + validation.mdc

2. Complex Case: Indexing Multiple Global Rules But what if you have multiple rules in the root .cursor/rules folder?

One way could be to consolidate them all into one massive root AGENTS.md. I don't recommend this for two reasons:

It bloats the context provided to the AI in every interaction.
It encourages stuffing unrelated rules into one file, making it hard to maintain.

Instead, the script treats each root-level rule as a separate piece of documentation. It converts each one into its own markdown file under docs/rules/ and creates a clean, simple root AGENTS.md that acts as a hyperlinked index.

Here's an example of that scenario:

# Before
.cursor/rules/
├── contributing.mdc
├── pr-reviews.mdc
└── style-guide.mdc

# After
├── AGENTS.md
└── docs/
    └── rules/
        ├── contributing.md
        ├── pr-reviews.md
        └── style-guide.md

The new root AGENTS.md would look something like this, acting as a set of pointers:

# Agent Rules

Here are the main guidelines for working on this project:

- [Contributing Guidelines](./docs/rules/contributing.md)
- [Pull Request Reviews](./docs/rules/pr-reviews.md)
- [Project Style Guide](./docs/rules/style-guide.md)

The migration script handles all of these scenarios automatically, stripping YAML frontmatter and putting the content in the right place.

Running the Migration

Grab generate_agents_from_cursor.py from my gist: generate_agents_from_cursor.py.
Drop the file in the repository whose .cursor/rules you want to convert (putting it at the root is easiest).
From that repository directory, run python generate_agents_from_cursor.py.
Review the generated AGENTS.md files before committing.
The script leaves your .cursor/rules as is. Keep them until you’re satisfied with the new setup, then delete them manually if you like.