← Back to blog

    CLAUDE.md to AGENTS.md Migration Guide

    Most teams do not start with AGENTS.md. They start with Claude Code, write a CLAUDE.md, tune it through a few painful sessions, and eventually get something useful. Then the toolchain changes. Codex enters the repo. Cursor reads a different rule file. Copilot has its own instructions. The old CLAUDE.md is still valuable, but it is no longer enough.

    The migration from CLAUDE.md to AGENTS.md is not a search-and-replace. It is a source-of-truth decision. Some rules in CLAUDE.md are project rules and should move into AGENTS.md. Some are Claude Code mechanics and should stay in Claude-specific files. Some are long workflow procedures that should move into skills or docs. Some are stale and should be deleted.

    This guide is the path I use when a team started Claude-only and now needs a multi-tool setup without turning the repo into a split-brain harness.

    Step one: audit the existing CLAUDE.md

    Read the file before touching it. Do not copy it blindly.

    Make a simple table:

    Rule or section | Type | Keep, move, or delete

    Classify each section into one of four types.

    Project facts: what the repo is, stack, layout, commands, process, architecture, security rules. These usually move to AGENTS.md.

    Claude Code mechanics: hooks, slash commands, skills, MCP permissions, Claude-specific settings, how Claude loads global and project files. These usually stay in CLAUDE.md or .claude/.

    Workflow procedures: release process, handoff format, review checklist, incident drill. These often move to docs or skills, with AGENTS.md linking to them.

    Stale or generic material: deleted commands, old paths, "write clean code," copied chat history, outdated tool preferences. These should be removed.

    The audit is where you recover value. A messy CLAUDE.md is usually not all bad. It contains hard-won knowledge. But the knowledge is mixed with tool habits, old scars, and stale references. Migration is the chance to sort it.

    Step two: identify cross-agent rules

    Cross-agent rules are rules that should apply no matter which coding agent touches the repo.

    Examples:

    - Use npm. package-lock.json is canonical.
- Run npm run build before opening a PR.
- Do not edit generated dist/ output by hand.
- Never print secret values.
- Public API changes require docs and tests.
- Blog slugs are derived from markdown filenames.
- New dependencies require approval.

    These belong in AGENTS.md because they describe the project, not Claude Code. If Codex should follow the rule, it cannot live only in CLAUDE.md. If Cursor should follow the rule, it cannot live only in AGENTS.md unless Cursor is configured to read it or has a pointer.

    A useful test: replace "Claude" with "agent." If the sentence still makes sense and should constrain every tool, it is a cross-agent rule.

    Step three: separate Claude-specific rules

    Now collect the rules that only matter to Claude Code.

    Examples:

    - SessionStart hooks live in .claude/settings.json.
- Use /handoff when the user asks to wrap up a session.
- Project skills live under .claude/skills/.
- Claude Code MCP permissions are configured in settings.json.
- Hook output is injected as system-reminder messages.

    These do not belong in the shared AGENTS.md except maybe as a one-line reference. Codex does not need a paragraph about Claude Code hook semantics. Cursor does not need to know how a Claude skill frontmatter field triggers. Tool-specific detail belongs near the tool.

    This is where many migrations go wrong. Teams copy the whole CLAUDE.md into AGENTS.md, and now Codex is reading instructions about slash commands or hooks that do not exist in its harness. That is not harmless. It teaches the agent the wrong environment.

    Step four: create AGENTS.md as canonical

    Write AGENTS.md from the classified rules, not from the old file's structure.

    A strong first version:

    # AGENTS.md

## Project facts
One paragraph describing the product, stack, and repo layout.

## Commands
- Install: npm ci
- Build: npm run build
- Lint: npm run lint
- Test: npm test

## Working rules
- Branch from main and open a PR. No direct pushes to main.
- Use npm only. Do not add other lockfiles.
- Do not edit generated dist/ output by hand.
- Never print secret values. Refer to environment variable names only.

## Architecture and boundaries
- Route metadata lives in src/lib/seo.ts.
- Static route generation lives in scripts/generate-sitemap.ts.
- Blog content lives in src/content/blog/.

## References
- package.json is the source of truth for commands.
- docs/release.md covers release procedure.
- .github/workflows/ci.yml is the source of truth for CI.

    Do not preserve the old section order if it was bad. AGENTS.md should be optimized for the agent starting a session, not for the history of how the CLAUDE.md grew.

    Keep the file short. If a section needs more than a few bullets, either it is too vague or it belongs in a referenced document.

    Step five: replace CLAUDE.md with a thin pointer

    Once AGENTS.md is canonical, CLAUDE.md should stop being a parallel source of project truth. Make it an adapter.

    Example:

    # CLAUDE.md

AGENTS.md is the canonical project instruction file.
Read AGENTS.md before making changes.

## Claude Code-specific behavior
- Hooks are configured in .claude/settings.json.
- Workflow-specific instructions live in .claude/skills/.
- If AGENTS.md and this file conflict, AGENTS.md wins for project rules.
- This file only owns Claude Code harness behavior.

    This is intentionally boring. Boring is good. A thin pointer makes drift obvious. If someone adds a package-manager rule to CLAUDE.md, the review question is immediate: why is a project rule being added to the adapter instead of AGENTS.md?

    If the team is not ready to make AGENTS.md canonical, invert the pointer temporarily:

    # AGENTS.md

Generated from CLAUDE.md. Do not edit by hand.
Shared project rules follow.

    That can be a bridge, but it should be explicit. Silent dual ownership is the failure mode.

    Step six: verify each agent reads correctly

    Do not assume discovery works. Test it.

    For Codex, run a harmless prompt from the repo root:

    codex --ask-for-approval never "Summarize the project instructions you loaded."

    Expected: it mentions AGENTS.md, the project commands, and the working rules. If it does not, check the current directory, CODEX_HOME, override files, and whether the file is empty. Codex builds its instruction chain at session start, so restart the session after changing instruction files.

    For Claude Code, start a new session and ask it to summarize the active project guidance. Expected: it reads CLAUDE.md, follows the pointer, and treats AGENTS.md as canonical for project rules.

    For Cursor or Copilot, either configure them to read AGENTS.md where supported or add a thin adapter file that points at it:

    Project rules live in AGENTS.md. Treat that file as canonical.
Tool-specific instructions in this file only cover editor behavior.

    Verification matters because the repo can look correct while one tool still reads an old file. Harness bugs often look like model behavior until you check what instructions actually loaded.

    Step seven: catch contradictions

    After migration, search for duplicated nouns:

    package manager
test
build
lint
main
PR
secret
lockfile
generated

    If AGENTS.md says npm and CLAUDE.md says pnpm, decide which is true. If AGENTS.md says PR required and a Cursor rule says direct commits are allowed, decide which is true. Do not leave both and hope the agent infers your intent.

    Every intentional override should say it is intentional:

    - Use npm in this repo; overrides global pnpm preference because CI uses npm.

    That sentence does two jobs. It tells the agent which rule wins, and it tells the human reviewer why the contradiction exists.

    Step eight: move long procedures out of always-loaded files

    Migration is also the moment to shrink. A common CLAUDE.md contains a 70-line release procedure, a 50-line handoff format, and a 40-line review checklist. Those are useful. They do not belong in always-loaded AGENTS.md.

    Move them:

    docs/release.md
.claude/skills/handoff/SKILL.md
docs/review-checklist.md

    Then keep only pointers:

    - Release procedure: docs/release.md.
- Session handoff in Claude Code: use /handoff.
- Review checklist: docs/review-checklist.md.

    This keeps AGENTS.md small while preserving the knowledge. The agent can open the deeper file when the task requires it.

    A migration checklist

    Use this as the PR checklist:

    - [ ] Existing CLAUDE.md audited and classified.
- [ ] Cross-agent project rules moved to AGENTS.md.
- [ ] Claude-specific rules kept in CLAUDE.md or .claude/.
- [ ] Long workflow procedures moved to docs or skills.
- [ ] CLAUDE.md now points at AGENTS.md as canonical.
- [ ] Each agent was tested in a fresh session.
- [ ] Contradictions and stale references were removed or declared.
- [ ] CI, hooks, or review gates enforce the rules that matter.

    The final line is the one people skip. Prose is not enforcement. If a rule is important enough to block a release, put a check beneath it.

    What good looks like after migration

    After migration, a new contributor should know where to edit a project rule. A Codex session and a Claude Code session should agree on package manager, commands, branch policy, generated files, and security basics. Tool-specific files should be thin and obviously scoped. Long procedures should live where they can be maintained without bloating every session.

    That is the real outcome: not "we added AGENTS.md," but "we removed ambiguity from the harness." AgentLint fits at the end of the migration because it checks the new AGENTS.md and the remaining instruction files for vague rules, stale references, contradictions, and missing enforcement before the new structure starts drifting.

    Related posts

    Using CLAUDE.md and Cursor Rules Together

    AGENTS.md vs CLAUDE.md

    Codex CLI Best Practices