Project Conversion Playbook

You point Claude Code at a three-year-old Next.js repo and ask it to add a feature. It invents a state management library you removed last quarter, puts the API route in the wrong directory, and writes tests in a framework you don’t use. The code isn’t bad — it just has no idea how your project works. The fix isn’t a better prompt; it’s giving the agent the context a new hire would get on day one.

This playbook converts an existing project into one that Cursor, Claude Code, and Codex can work in productively, using a single source of truth that all three read.

What You’ll Walk Away With

• A real CLAUDE.md / AGENTS.md generated from your repo, not a blank template
• Cursor .mdc rules scoped to the parts of the codebase they apply to
• Copy-paste prompts to audit a legacy codebase and produce a phased conversion plan
• A CI job that keeps your context files current using a real agent CLI — no fictional npm tools
• A clear view of how each tool consumes context, so you don’t maintain three drifting copies

The Single Source of Truth

The mistake teams make is hand-writing three separate context files. Instead, write the conventions once and let each tool’s entry file point at the same content. All three tools read a root-level Markdown file:

Tool	Reads	Notes
Claude Code	CLAUDE.md	Project root; subdirectory CLAUDE.md files override for that path
Codex	AGENTS.md	Same idea, open AGENTS.md standard
Cursor	.cursor/rules/*.mdc	Scoped rule files with frontmatter; also reads AGENTS.md

Keep them in sync, don't fork them

The lowest-maintenance setup: make CLAUDE.md the canonical file, and make AGENTS.md a one-line pointer (See CLAUDE.md for project conventions.) or a symlink. Put Cursor-specific, path-scoped guidance in .cursor/rules/ and keep it short by referencing files rather than pasting their contents.

Start by Generating Context, Not Writing It

Don’t open a blank CLAUDE.md. Have the agent read the repo and draft it — you’ll edit far less than you’d write. This is identical across all three tools; run the prompt in whichever one you have open.

Copy-paste prompt: generate CLAUDE.md from the repo

Read this repository — package.json, the directory layout, the CI config, and a sample of source files — and generate a CLAUDE.md for the project root. Include: the actual tech stack with versions from package.json (do not guess), the real directory conventions you observe (where routes, components, and business logic live), the exact dev/test/build commands from the scripts, and any non-obvious patterns you can infer (state management, error handling, auth). Mark anything you’re unsure about with TODO: confirm instead of guessing. Keep it under 150 lines.

Review the draft against reality, delete the TODO: confirm lines you can answer, and commit it. A grounded 120-line file beats a 400-line template full of [YOUR_FRAMEWORK].

Here’s the shape of a good result for a real Next.js app — concrete, not a fill-in-the-blanks form:

# Acme Storefront

Next.js 16 e-commerce app. App Router, RSC by default.

## Stack
- Next.js 16.2 (App Router), React 19, TypeScript 5.6 (strict)
- Tailwind CSS 4, Prisma 6 + PostgreSQL 16, Stripe, Auth.js v5

## Conventions
- Server Components by default; add `'use client'` only for interactivity
- Route handlers live in `app/api/`, one folder per resource
- Shared UI in `components/ui/`, feature components beside their route
- Data access goes through `lib/db/` — never call Prisma from a component
- Money is stored and computed in integer cents, never floats

## Commands
- Dev: `npm run dev` | Test: `npm test` (Vitest) | Migrate: `npx prisma migrate dev`

## Watch out
- The legacy `/pages/checkout` route is being migrated to App Router — don't extend it

How Each Tool Consumes It

The conversion workflow diverges by tool once the context file exists. Here’s what to set up in each.

Cursor

Cursor reads .cursor/rules/*.mdc. Use .mdc (Markdown with frontmatter) so you can scope rules to paths and control when they apply — .md also works but gives you no scoping.

.cursor/rules/
  general.mdc        # alwaysApply: true — core standards
  api.mdc            # globs: app/api/** — backend rules
  components.mdc     # globs: components/** — UI rules

A scoped rule with real frontmatter:

---
description: API route conventions
globs: app/api/**
alwaysApply: false
---

- Validate request bodies with Zod schemas from `lib/schemas/`
- Wrap handlers in `withErrorHandler` from `lib/api/errors.ts`
- Return `NextResponse.json` with explicit status codes
- Never expose Prisma errors to the client

Reference files instead of pasting them (@lib/api/errors.ts) so rules don’t go stale when the code changes.

Claude Code

Claude Code reads CLAUDE.md from the root and merges any subdirectory CLAUDE.md files for work in that path. Bootstrap it with the /init slash command inside the REPL, which scans the repo and drafts the file for you:

> /init

Then refine it with the generation prompt above. For a monorepo, add a focused CLAUDE.md in each package — for example packages/api/CLAUDE.md describing only that service — and keep the root file high-level. Claude Code automatically picks up the nearest file for the code it’s editing.

Codex

Codex reads AGENTS.md. If you’ve already written CLAUDE.md, don’t duplicate it — point Codex at it:

AGENTS.md

See CLAUDE.md for project conventions, stack, and commands.

## Codex-specific
- Run `npm run lint && npm test` before declaring a task done
- For parallel Cloud tasks, scope each task to one package

Like Claude Code, Codex supports nested AGENTS.md files, so a package-level file overrides the root for work in that directory.

Converting a Legacy Codebase

For an older project with thin documentation, drive the conversion with two prompts: one to map what exists, one to plan the work.

1. Map the codebase. Let the agent build the picture you’d otherwise reconstruct by hand.

   Copy-paste prompt: audit a legacy codebase

   Audit this codebase and produce a report with five sections: (1) Architecture — the real module boundaries and data flow, not the aspirational ones; (2) Stack — frameworks and versions, flagging any that are EOL or a major version behind; (3) Anti-patterns and risks — concrete files with code smells, missing input validation, or N+1 query patterns, cited by path; (4) Test coverage gaps — which critical paths have no tests; (5) A prioritized list of what to fix first, ordered by risk × effort. Be specific and cite file paths. Do not suggest a rewrite.

2. Turn the audit into a phased plan. Convert findings into work you can actually schedule.

   Copy-paste prompt: produce a phased migration plan

   Using the audit above, write a three-phase conversion plan as a checklist. Phase 1: documentation and context files (CLAUDE.md, scoped Cursor rules) — one task per area. Phase 2: characterization tests around the highest-risk untested paths you identified, so refactors are safe. Phase 3: the refactors themselves, smallest-blast-radius first, each as an independent task I can hand to a separate agent. For every task, note the files touched and how I’ll verify it’s done.

3. Execute incrementally. Work module by module, keeping backward compatibility. Land the context files first (Phase 1) so every subsequent task benefits from them, then characterization tests, then refactors. Fan the independent Phase 3 tasks out across Codex Cloud tasks or Claude Code sub-agents and review the diffs as they arrive.

Keeping Context Current in CI

A CLAUDE.md that’s six months stale is worse than none — it actively misleads the agent. Automate a refresh in CI using a real agent CLI, not a fictional npx tool. Claude Code runs headless with -p; Codex runs non-interactively with codex exec.

.github/workflows/refresh-context.yml

name: Refresh project context
on:
  schedule:
    - cron: '0 6 * * 1' # Monday mornings
  workflow_dispatch:

jobs:
  update-claude-md:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Update CLAUDE.md from the current codebase
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "Review CLAUDE.md against the current repo. Update the \
            stack versions, commands, and directory conventions only where \
            they no longer match reality. Output the corrected file." \
            --output-format text > CLAUDE.md

      - name: Open a PR if anything changed
        uses: peter-evans/create-pull-request@v6
        with:
          commit-message: 'docs: refresh CLAUDE.md from codebase'
          title: 'docs: refresh project context'
          branch: chore/refresh-context

Don't auto-commit agent output to main

Generate the update on a branch and open a PR, as above — never push agent-written docs straight to main. A human glance catches the occasional confident-but-wrong edit, and the diff makes drift visible. The same pattern works with codex exec "..." if your CI authenticates with Codex instead.

When This Breaks

The agent ignores your CLAUDE.md

Most often the file is too long or buried in narrative. Agents weight concise, imperative rules over prose. Cut it under ~150 lines, lead with hard constraints (“never call Prisma from a component”), and delete anything the agent could infer from the code itself. If a specific rule keeps getting violated, move it into a scoped Cursor .mdc with a matching globs so it loads exactly when relevant.

Rules conflict across tools

When CLAUDE.md, AGENTS.md, and .cursor/rules disagree, each tool follows its own file and you get three behaviors. This is the symptom of forking instead of syncing. Collapse to one canonical file and make the others reference it. Run git grep for the same rule phrased differently in multiple files and reconcile.

Docs went stale after a big refactor

If you renamed directories or swapped a library and the agent starts suggesting the old structure, your context file is lying to it. Trigger the CI refresh job manually (workflow_dispatch) or re-run the generation prompt, then review the PR. Treat context files like code: they belong in the same commit as the change they describe.

Conversion Checklist

Minimum viable AI-ready project

• ☐ Canonical CLAUDE.md (or AGENTS.md) generated from the repo and reviewed
• ☐ Secondary entry files point at the canonical one — not forked copies
• ☐ .cursor/rules/*.mdc for path-scoped standards (API, components, tests)
• ☐ Highest-risk untested paths have characterization tests before any refactor
• ☐ CI refresh job opens a PR, never auto-commits to main
• ☐ Context files updated in the same PR as structural changes

What’s Next

• Between Codex, Cursor, and Claude Code — run all three from one set of conventions
• Workflow Transformation — reshape delegation and review loops
• Team Migration Strategies — roll the conversion out across a team
• Migration Strategy Center — the full map of migration playbooks

The goal isn’t a perfect document. It’s a foundation that makes the agent behave like someone who already knows your codebase.