Batch Refactoring a Monorepo With Claude Code

A monorepo refactor becomes easier to manage when each automated run has a narrow target and a clear acceptance test. Claude Code’s non-interactive mode lets you turn that pattern into a repeatable workflow: supply a task, let the agent edit files, capture its result, and validate the patch before moving on.

This walkthrough uses a TypeScript migration: replacing direct calls to a deprecated request helper with an existing shared client. The same approach works for import migrations, configuration updates, and repetitive API changes.

01 · 1. Define the migration before launching an agent

Start with a written contract. Identify the deprecated helper, the replacement import, the argument mapping, and the behavior that must stay consistent. Include one representative before-and-after example, especially if error handling or return types differ.

Save those instructions in a tracked file such as refactor-request.md. Define acceptance criteria: no deprecated calls in migrated files, passing package checks, and no unrelated formatting changes. Tell the agent to report ambiguous cases instead of guessing. A precise contract makes results easier to compare across batches.

02 · 2. Create a clean worktree and package manifest

Create a dedicated branch and worktree with git worktree add ../request-migration -b refactor/request-client. Install dependencies using the repository’s normal locked installation procedure, then run the relevant baseline checks. Record existing failures so they do not become confused with migration regressions.

Search for the old helper with rg -l 'legacyRequest' packages. Review the matches and create an explicit package list. Begin with one small package that exercises typical usage. Keep shared libraries and their consumers in dependency order when the migration changes an interface.

03 · 3. Connect Claude Code through Quanta

For sustained batch work, Quanta provides pay-as-you-go API access from one balance and works with Claude Code, Codex, Gemini CLI, and applications using an OpenAI SDK. Its API base address is https://api.quantarelay.com. Open a Quanta account, create an API key, and follow its Claude Code configuration instructions for the required credentials and endpoint settings.

Keep credentials in the environment or an approved secret store. Select a supported model, such as Claude Sonnet 5.5, using the model identifier documented by Quanta. Run a small connectivity check before starting the migration.

04 · 4. Run one bounded non-interactive edit

From the worktree root, create an output directory outside the checkout. Then launch a pilot run with a command shaped like this:

claude -p "Read refactor-request.md. Apply the migration only within packages/catalog. Report changed files, unresolved cases, and checks still needed." --allowedTools "Read,Glob,Grep,Edit" --max-turns 12 --output-format json > ../catalog-refactor.json

The -p flag runs the supplied prompt without opening an interactive session. The tool allowlist permits the listed operations without approval prompts; this example authorizes reading and editing but leaves shell-based validation to the surrounding workflow. The turn limit bounds the run, and JSON output gives automation a structured result to inspect.

A directory instruction is not a filesystem security boundary. Review every changed path. For stronger isolation, run the agent in a sandbox that exposes only the required checkout and credentials.

05 · 5. Validate the patch before expanding the batch

Inspect git diff --stat and the full diff. Run the package’s actual lint, type-check, and test commands, followed by checks for affected consumers. Search again for the deprecated helper and examine any remaining matches.

Check the process exit status and the structured result for errors or an exhausted turn limit. A completed agent response does not establish correctness. If validation fails, provide the concrete diagnostics in a bounded repair run, then repeat the relevant checks.

06 · 6. Repeat serially and measure actual consumption

Once the pilot passes, commit the reviewed patch and repeat the same procedure for each package in the manifest. Keep a record of the package, commit, result file, validation outcome, and any deferred cases. Stop the sequence when a batch fails so later edits do not obscure the cause.

Use Quanta’s usage records to track actual consumption. Calls are metered on real tokens, with cache writes and cache reads priced separately. Compare those categories when estimating the remaining work; repeated instructions alone do not guarantee a cache hit. Finish with repository-wide checks and a final review of the combined migration.