The decision to change tools takes about ten minutes. You read something, you try the new one on a side project, you like how it plans before it edits, and that is that. The first real session on your actual project is where you find out how much of the project was living inside the old tool rather than in the repository.
Switching AI coding assistants mid-project fails in a specific way. The code is fine, the tests still pass, nothing is broken. But the new assistant proposes the caching layer you rejected in August, asks which package manager you use, and rewrites a file that has a comment at the top saying not to. You spend the first day re-explaining things you already explained, except you explained them to software that no longer has them.
The fix is not a better prompt. It is to treat the move as a migration with two halves, and to notice that only one of those halves was ever portable.
Mistake: copying the instruction file and calling it done
The usual first move when you change AI coding tool mid-project is to rename or duplicate the instruction file. CLAUDE.md becomes AGENTS.md, or the contents get pasted into the new tool's rules panel, and the migration is declared finished.
That handles the smallest part of the problem. Instruction files hold rules: run this command before committing, never edit generated files, use named exports. Rules travel well because they are short, explicit and tool-agnostic. If that file was the only context your project had, the copy genuinely is the whole migration, and you should take the hint: most of what the old assistant knew was in the conversation, not in the repository.
What does not travel is everything the old tool accumulated through use. Your prompt habits, the slash commands you wrote, the way you had learned to phrase a refactor request so it stayed inside one directory, the mental model of which files it would wander into if you were not watching. That knowledge is real and it is now worthless. Accept the loss instead of trying to reconstruct it in a tool with a different shape.
Switching AI coding assistants is a sorting problem first
Before you write anything for the new tool, sort what you have into two columns. The split matters because only one column deserves effort.
| Tool-specific | Project-specific |
|---|---|
| Slash commands, custom modes, saved prompts | Stack, versions, package manager |
| Rules file location and format | Test, build and deploy commands |
| Which model you picked for which task | Decisions and the reasoning behind them |
| Indexing and ignore settings for that tool | Approaches you tried and dropped |
| Your phrasing habits | Open threads and known traps |
The left column is sunk cost. Rebuild the two or three commands you actually used and let the rest go.
The right column is the migration. It is also the column that answers the question people really mean when they ask about ai assistant memory portability: nothing about an assistant's memory is portable, but project facts written as files are portable by definition. A decisions.md that says why you chose SQLite over Postgres for the desktop build reads identically to Claude Code, Codex and Cursor, because it is just text in your repository. If you have been splitting rules from facts already, as in splitting CLAUDE.md from project memory, the sorting is mostly done and the switch costs you an hour.
The part that was never written down
Here is where a claude code to cursor switch, or any move in either direction, quietly hurts. Over weeks of sessions you corrected the assistant dozens of times in chat. You told it the staging database resets overnight. You told it the retry loop in the sync worker looks wrong on purpose. You told it three separate times to stop reaching for a new dependency when the standard library covers it.
None of those corrections are in a file. They worked because the thread was long and the context held. When the tool changes, every correction you made conversationally reverts to its default.
So before you start the new tool, spend twenty minutes writing down what you have been repeating out loud. A practical way to find it: open the last few sessions you kept and look for the places where you said "no" or "actually". Those are the undocumented constraints. Each one becomes a line in project memory or, if it is a hard rule, a line in the instruction file.
project/
CLAUDE.md # rules the assistant must follow
.prjcontext/
memory/
decisions.md # choice, reason, consequence, status
rejected.md # tried X, dropped it because Y
open-threads.md # what is half-finished right now
Plain files and folders are enough. The point is that the content stops depending on which assistant is reading it.
Rewrite the instructions, keep the decisions
The second common mistake is to rewrite the instruction file for the new tool and, while rewriting, compress the reasoning out of it. "Use SQLite" survives. "Use SQLite because users run this without a server, so no JSON columns and keep queries portable" gets trimmed for length. Two months later the new assistant suggests a JSON column and nothing in the repository argues back.
Keep rules terse in the instruction file and keep reasons in memory, where length is not a problem. If you are now running both files because the new tool reads a different one, CLAUDE.md vs AGENTS.md covers whether to maintain one or two without them drifting apart. And if the switch is additive rather than a replacement, the setup in running multiple assistants over one codebase is closer to what you want.
A first session that starts from the project's state
Do not open the new assistant on the feature you were mid-way through. Spend one short session establishing the baseline.
- Point it at the instruction file and the memory folder explicitly, by path. Do not assume it discovered them.
- Ask it to summarise the project back to you in ten lines: stack, conventions, current state, open questions.
- Correct the summary. Every correction you make here is a gap in your files, not a gap in the assistant. Fix the file, not just the chat.
- Give it one bounded task you already know the right answer to. A small refactor in a directory you know well tells you more than a feature.
- Watch for the rejected approach. If it proposes something you dropped weeks ago,
rejected.mdis missing a line. - Note what you had to explain by hand. That list is your week-one backlog of writing.
Step two is the one people skip and the one that earns the session. A summary you have to correct in four places is a map of exactly what did not migrate.
Keep the old assistant for one more session
Counterintuitively, the best use of the tool you are leaving is one final session where you ask it to write the handoff. It still has the long thread. Ask it for the decisions made in this project, the things you told it not to do, and what is currently unfinished.
Treat the output as a draft, not a record. Assistants summarising their own history will state things with more confidence than the conversation supports, which is why a draft of project memory needs human review before it lands. Read it line by line, delete what you do not recognise, and keep what you had forgotten you knew. Then close the tool.
When you migrate from one AI assistant to another with that file in hand, the new tool is reading a project, not guessing at one. The same files are what make handing the project to a teammate on a different assistant survivable.
We built PrjLab because this context is the part git repositories tend not to carry: instructions, decisions and the sessions worth keeping, pushed with prj push as versioned files that sit beside the code and come back with prj clone on any machine, regardless of which assistant you are using this month. If you want to see the layout before committing to it, the getting-started guide walks through a first push.
