← Back to library

Set up layered context files before an agent-led migration

Karthik Subramanian, an engineering manager, took on a large migration alone with Claude Code: four legacy repositories folded into two, a switch from MySQL to Postgres, upgraded frameworks and new authentication. Preparation was the key. CLAUDE.md files sat at workspace, domain and repository level, memory files turned each correction into a standing rule, and both databases were connected read-only.

  • OutcomeLet a single engineer drive a multi-repo modernization by giving the agent the same onboarding a new team would get.
  • SetupAn afternoon+
  • LevelAdvanced
  • CreditKarthik Subramanian
View original
Works with
Claude Code

Published Oct 23, 2026Updated Oct 23, 2026AI dry run on sample input: passed Oct 23, 2026Source verified Oct 23, 2026

When should you use it?

  • You face a large multi-repo migration with a small team
  • The agent keeps re-learning your architecture each session
  • You can grant read-only access to real systems

Not for: Quick one-repo changes; Organizations that cannot allow source and database access

What do you need, and what do you get?

You need

  • Repos to migrate and a reference implementation
  • Read-only database connections
  • Upstream API documentation

You get

  • Hierarchical context files
  • A growing set of feedback rules
  • A migration plan built on full context

How does it work, step by step?

  1. Write the top layerDescribe all repos, stack, cross-service architecture and shared commands.
  2. Add domain and repo layersCapture service catalogs, glossary, auth design and per-repo conventions.
  3. Turn corrections into rulesSave each correction, such as never amending commits, as a lasting memory.
  4. Load the full context for planningGive source, read-only databases, a reference migration and live API docs.
  5. Plan before codingGenerate and review the migration plan before any change is made.

The prompt

Our own prompt, inspired by Karthik Subramanian and written to work in Claude Code. Values in lime are placeholders.

Prompt0 variables
Before we start the migration, create CLAUDE.md files at three levels: workspace (all repos, stack, architecture, shared commands), domain (service catalog, glossary, auth design) and each repo (conventions, structure, testing, local setup). Ask me questions where you are unsure. Whenever I correct you, save the correction as a rule in memory. Use the database connections read-only. Produce a migration plan for my review; do not change code yet.

Inspired by Karthik Subramanian: The Setup Is the Strategy: How I Orchestrated a Product Migration with Claude Code. The prompt above is written by playbooks.bot in our own words; nothing from the original is quoted.

What can go wrong?

  • Skipping the foundation layer leaves the agent guessing about architecture.
  • Memory rules accumulate; review them so stale ones do not mislead later work.

Our take

Karthik Subramanian's write-up is a good example of context engineering done properly for a job that would normally need a team. Layering instruction files at workspace, domain and repository level means the agent gets broad conventions everywhere and specific rules only where they apply, which keeps each session focused. The feedback memory is the part most teams miss. Every correction becomes a permanent rule, so a mistake made once does not reappear in the next repository or the next week. Giving the agent full source access plus read-only connections to both databases during planning is the right balance: it can inspect real schemas and data shapes, but cannot change anything while it is still forming its view. Have a person read the generated migration plan line by line before execution, especially data type mappings between MySQL and PostgreSQL, where silent changes to dates, text encoding or numeric precision hide. Run the migrated system against copies of production data and compare row counts and key reports before switching users over.

Where the time goes back: The agent stops rediscovering the codebase every session, so effort goes into the migration itself.

FAQ

Why does management experience help?
The author says clear context, specific delegation and rigorous review are the same skills that make the agent effective.
Which part matters most?
He calls the context files the single highest-leverage setup step.

Source and credit

Inspired by Karthik Subramanian. We describe the idea in our own words, link to the original, and wrote the prompt ourselves; nothing is quoted.

Inspired by
The Setup Is the Strategy: How I Orchestrated a Product Migration with Claude Code
Creator
Karthik Subramanian
Published on
DEV Community (dev.to)
Original date
Apr 16, 2026
License
Not openly licensed (the poster keeps all rights), so we quote nothing and link to the original
Originally for
Claude Code
AI dry run
Oct 23, 2026: passed. Dry-run tested by our AI test agent on sample input. PASS: Gates held on desk check; no live sends or purchases.
AI dry run on sample data; not run with live connected accounts. The playbooks.bot test agent filled the prompt with synthetic inputs, produced the output and checked it against the page's stated outputs and guardrails.
Verified
Oct 23, 2026: source link resolves to the original, the credited creator published it, our excerpt or prompt matches it, and the license allows our use.

Are you the creator? Claim or correct this page.

More in Operations & Admin

All 203 Operations & Admin playbooks →

Related playbooks

Operations & AdminWorkflow✓ AI dry run

Add a merge check for every way coding agents break code

Keep a running list of the specific ways coding agents have damaged your repository, from hollow tests and invented fake responses to deleted files and silenced type errors, and turn each one into an automated gate that blocks the merge, so the same mistake cannot slip through review twice.

Credit: u/alexmarquardt on r/ClaudeCode

An afternoon+
Operations & AdminWorkflow✓ AI dry run

Ask Reddit's experience before you pick a library

Let your coding agent search Reddit for long-term user reports on a library, an error message or a competitor before you commit to a choice.

Credit: u/karanb192 on r/ClaudeCode

Minutes
Operations & AdminWorkflow✓ AI dry run

Run parallel coding agents for days on one large build

Keep many coding agent sessions making autonomous progress on one big codebase by investing in tests, logs and task locks instead of supervision.

Credit: Nicholas Carlini (Anthropic)

An afternoon+