How to Migrate From Claude Code to Augment Code Without Losing Context (2026)

Every CLAUDE.md file, unchanged. Augment's rules documentation lists the files Auggie loads "in the following order of precedence":

1. Custom rules file (via --rules flag), 2. CLAUDE.md, 3. AGENTS.md, 4. Workspace guidelines (.augment-guidelines), 5. Workspace rules folder (<workspace_root>/.augment/rules/), 6. User rules folder (~/.augment/rules/)

Two things stand out. CLAUDE.md ranks above AGENTS.md, which is the reverse of the ordering several other agents use. And both foreign filenames rank above Augment's native rules directory, with the user-level directory last.

Nested CLAUDE.md files transfer, and keep their scoping. Claude Code discovers CLAUDE.md files down the tree and states that "all discovered files are concatenated into context rather than overriding each other," ordered "from the filesystem root down to your working directory," so "instructions closer to where you launched Claude are read last."

Augment does something structurally similar but triggered differently. Its documentation describes hierarchical rules this way: "When you work on a file, Augment looks for AGENTS.md and CLAUDE.md in the file's directory," then "walks up the directory tree, checking each parent directory for these files," and "all discovered rules are included in the context for that work session." The search "stops at the workspace root." Rules are also "cached per conversation session to avoid duplicate inclusion."

So a monorepo with src/frontend/CLAUDE.md and src/backend/CLAUDE.md behaves roughly as you expect. When work happens in src/frontend/, that file and its parents load; the backend file does not.

Imports do not transfer. Claude Code supports @path imports inside CLAUDE.md, with a documented subtlety: "Import parsing skips Markdown code spans and fenced code blocks," so a backtick-wrapped @README stays literal. Augment's rules documentation describes plain Markdown files with optional YAML frontmatter and does not document an import syntax. Any @path line in a migrated CLAUDE.md should be treated as text — flatten the imported content into the file before you rely on it.

One rule type has no CLI destination. Augment's workspace rules take a type field with two documented values, always_apply and agent_requested, and the IDE extensions expose a third. The CLI page is explicit about the gap:

"Manual rules are not supported in the CLI. Rules with type: manual in <workspace_root>/.augment/rules/ are skipped by the CLI — there is no @-mention mechanism to attach them on demand."

The IDE-side page repeats it: Manual is "IDE only — attached on demand via @ mention; skipped by the CLI." If your team runs both surfaces, a manual rule is live in the editor and absent in the terminal.

User-level rules lose their frontmatter. Augment documents that "user rules in ~/.augment/rules/ are always treated as always_apply and do not support other frontmatter types." Anything you put in your home directory is on in every session of every project, regardless of what its frontmatter says.

Auto memory does not transfer. Claude Code has two persistence systems, and its docs describe them as complementary: CLAUDE.md files you write, and auto memory — "notes Claude writes itself based on your corrections and preferences" — stored per project under ~/.claude/projects/<project>/memory/ and injected "every session (first 200 lines or 25KB)." Augment has a memory system too, but a different one: Cosmos Experts store "scoped knowledge in the shared virtual filesystem (VFS)," an Expert's memory "belongs to its team," and there are two documented models, simple and noisy. Neither reads the other's files. We covered the Cosmos side separately in steering what Augment's Experts remember; this guide is about the instruction layer, which is a different mechanism with a different lifecycle.

Step 1: Decide whether CLAUDE.md stays authoritative, and commit to the answer

You have two coherent options, and the failure mode is picking neither.

Option A: keep CLAUDE.md. It ranks second, it works, and it keeps the repository readable by Claude Code for anyone who has not switched. The cost is that Augment's native features — per-rule type frontmatter, per-rule files you can review independently — stay unavailable, because a single CLAUDE.md has no frontmatter and no file boundaries.

Option B: convert to .augment/rules/. You get one file per rule, each with its own type, which is the closest thing either tool has to conditional loading. The cost is the one nobody sees coming, and it is worth its own paragraph.

Augment's hierarchical discovery covers exactly two filenames. Its documentation states: "Only AGENTS.md and CLAUDE.md files are discovered hierarchically," and immediately after: "Files in .augment/rules/ are only loaded from the workspace root, not from subdirectories."

So converting to Augment's own format costs you directory scoping. Your src/frontend/CLAUDE.md was loading only when work happened in the frontend. The same content moved into .augment/rules/frontend.md loads from the workspace root, for everything. The vendor's native format is, on this one axis, the least scopable of the three it supports.

The practical answer for most teams is a split: keep nested CLAUDE.md files where directory scoping is doing real work, and use .augment/rules/ only for repository-wide rules that need a type other than always-on. Do not convert a nested file just to make the tree tidy.

Whichever you pick, verify rather than assume. Claude Code's own consistency note is a good reason to check: "if two rules contradict each other, Claude may pick one arbitrarily." Two rule trees loading at once is exactly how you get contradictions you did not write, and the resolution mechanism is not something you can inspect. We walked through auditing that situation on the Claude Code side in reconciling conflicting CLAUDE.md layers.

Step 2: Re-declare your conditional rules, and check the character budget

Claude Code's mechanism for conditional loading is .claude/rules/ with paths frontmatter, plus its own note that rules without paths "are loaded at launch with the same priority as .claude/CLAUDE.md." Augment's mechanism is the type field.

Map them deliberately. A path-scoped Claude Code rule becomes either a nested CLAUDE.md in the directory it applies to — preserving the scoping — or an agent_requested rule whose description states when it applies. Augment's guidance favours the latter when you can write a good description: "Use agent_requested over always_apply if you want to optimize context usage. For these rules, the agent will determine the rule is relevant to your current task." Note that description is required for agent_requested and does all the selection work.

Then check the budgets, because Augment publishes hard limits and Claude Code publishes a recommendation. Claude Code advises you "target under 200 lines per CLAUDE.md file" — guidance, not a cap. Augment's limitations section is a cap, with a documented behaviour on overflow:

"User Guidelines are currently limited to a maximum of 24,576 characters. Workspace Guidelines + Rules are limited to a maximum of 49,512 characters. If we exceed these limits, the user will be notified in app and be applied in order of (manual rules, always + auto rules, .augment-guidelines)."

Read the order in that last clause. When you are over budget, manual rules are applied first and .augment-guidelines last. A team that has been treating .augment-guidelines as the canonical file is treating the lowest-priority item under pressure as canonical.

One more IDE-specific detail if part of your team uses the extensions rather than the CLI: "Guidelines defined in VSCode will not propagate to JetBrains IDEs and vice versa." User Guidelines are stored in local IDE storage, so they are neither shared nor version-controlled. Anything that matters to more than one person belongs in the repository.

Both tools rank files. Neither stores the reason a rule exists.

That is the gap that makes this migration risky in a way the file moves are not. When you decide that a nested CLAUDE.md becomes an agent_requested rule, you also decide what its description says — and the description determines whether the rule ever loads again. If the original constraint was "the payments module must not use the shared retry helper, because it double-charges on a specific failure path," the rule survives the move but the reason does not, and the next person who reads a terse rule with no justification deletes it.

MemoryLake holds the justifications: the ruling, what was tried, why it was rejected, and when. It sits outside both instruction systems, so precedence changes and format conversions cannot reorder it. Get started here.

Step 1: Create an API key

Create a workspace for the repository and generate an API key. Scope it to the repository rather than to Claude Code or Augment, since the point is that it outlives both.

Step 2: Upload your first memories

Walk your CLAUDE.md tree before converting anything and record why each non-obvious rule is there. Add the corrections you have been giving Claude Code repeatedly — those are the same corrections its auto memory has been accumulating locally, and they do not travel. Then add the decisions made during the migration itself: which files you kept, which you converted, and what you deliberately left behind.

Step 3: Connect your AI & agents

Connect Auggie, and keep Claude Code connected during the transition. Both read the same set, so a rule you have not ported yet still has its reasoning available to whichever agent someone happens to be using.

The "it already works" trap stops costing you a month. You know on day one that CLAUDE.md ranks second, so you make the keep-or-convert decision deliberately instead of discovering later that your new .augment/rules/ files have been sitting underneath a file you forgot about.

Conversions stop losing scoping by accident. Once you know that only AGENTS.md and CLAUDE.md are discovered hierarchically, "move everything into the native format" stops looking like an obvious cleanup.

Overflow stops being invisible. Augment's caps come with a documented application order, so a team near 49,512 characters knows which category degrades first rather than guessing why a rule stopped applying.

And the split-surface problem gets a name. A manual rule that works in VS Code and is skipped in the CLI is not a bug you will find by reading your rule files; it is documented behaviour you either design around or get surprised by.

Inventory before you convert. List every CLAUDE.md, AGENTS.md, .augment-guidelines, and .augment/rules/ file in the repository and write down which ones you expect to load. Then test one deliberately odd rule from each and see which actually applies. This is the fastest way to catch the case we described in why agents ignore your instruction files.

Keep nested files nested. Directory scoping is free in the two foreign formats and unavailable in the native one. That is an unusual incentive, and it favours leaving your tree alone.

Write description fields as trigger conditions. For agent_requested rules the description is the entire activation mechanism. "React component development patterns and best practices" — Augment's own example — is better than a summary of the rule's contents.

Treat ~/.augment/rules/ as always-on and nothing else. Frontmatter there is ignored, so anything you put in your home directory applies to every project you open. Reserve it for genuine personal preferences.

Do not rely on Augment's auto-import to find everything. It "will look for markdown files, e.g., files ending with *.md or *.mdx," which is helpful and not the same as a manifest. If a rule matters, put it somewhere the precedence list names.

Remember that neither tool enforces. Claude Code says it plainly — "Claude treats them as context, not enforced configuration," and recommends a PreToolUse hook "to block an action regardless of what Claude decides." Rules describe intent. Enforcement is a different layer, and that is true on both sides of this migration. The house-conventions version of this problem is covered in making Claude stick to your conventions.

The surprise in this migration is not that something breaks. It is that nothing does, for a while. CLAUDE.md is second on Augment's precedence list, so your instruction layer keeps working and the tool's native format sits unused underneath it.

The two decisions worth making on purpose: whether CLAUDE.md stays authoritative, and whether any nested file gets flattened into .augment/rules/ — because that directory loads only from the workspace root. Get those right and this is one of the cheapest agent migrations available. Get them wrong and you will spend weeks debugging rules that were never loading, in a tool that had been reading your old files the whole time.