The Revenue AI Report

Claude Code for agentic refactors and migrations (L3)

Use Anthropic\'s Claude Code CLI as a teammate that can read your whole repo, propose multi-file refactors, run tests, and open PRs. Goes beyond autocomplete: you give it a goal, it iterates on the codebase like a junior engineer with a coffee IV.

WORKFLOW1Install Claude Code + sco…ed repo accessClaude Code2Pick a real migration as …he first jobClaude Code3Add CLAUDE.md to every re…oGitHub4Weekly "agent debt" clean…p ritualManual
4 steps, in order, with the tool that owns each one.
Adoption ladderSix levels from Starter to Rebuilt. This item sits at level 3.L1 StarterOne tool, no workflow changeL2 AssistedAI drafts, humans approveL3 IntegratedWired into CRM and SlackL4 OrchestratedMulti-step, owned, measuredL5 AutonomousAgent runs, human auditsL6 RebuiltThe process itself changes
This playbook belongs at L3 Integrated. Running it above your level is how pilots stall.
Measures of success# of migrations completed/quarter; engineer-hours saved per migration; PR-from-AI acceptance ratePROVE IT WORKED# of migrations completed/quarterengineer-hours saved per migrationPR-from-AI acceptance rate

The steps

  1. 01

    Install Claude Code + scoped repo access

    Tool: Claude Code

    Install the Claude Code CLI (npm i -g @anthropic-ai/claude-code). Authenticate with an Anthropic API key tied to a business account (NOT personal). Run inside a worktree, NOT main, so a runaway agent can't nuke your active branch. Owner: senior engineer. Time: 30 minutes. Pitfall: running with --no-confirm in main branch, you will get a 47-file commit you don't understand. DoD: every operator can launch claude-code, see it list the repo, and exit cleanly.

  2. 02

    Pick a real migration as the first job

    Tool: Claude Code

    Don't demo on a toy. Pick a real chore: "Migrate all class components to function components", "Replace moment.js with date-fns across the repo", "Add error boundaries to every route". Give Claude Code a clear goal, the relevant tests, and authority to read CLAUDE.md (a repo doc explaining conventions). Owner: senior engineer pairs with the agent. Time estimate: 1,3 hours for what would take 2 days manually. Pitfall: giving a vague goal ("refactor the auth module"), you'll get unfocused PRs. Be specific. DoD: first PR opened by Claude Code, reviewed and merged with <10 human edits.

  3. 03

    Add CLAUDE.md to every repo

    Tool: GitHub

    Create CLAUDE.md in repo root: stack, build commands, how to run tests, where data lives, what to never touch, code-review checklist. Claude Code reads this automatically and dramatically increases first-pass PR quality. Owner: tech lead per repo. DoD: every actively maintained repo has CLAUDE.md, last-updated date <60 days.

  4. 04

    Weekly "agent debt" cleanup ritual

    Tool: Manual

    Every Friday, the team picks 2,4 ticket-shaped chores from the backlog (typo fixes, deprecation warnings, test coverage gaps, small refactors) and hands them to Claude Code. The agent opens PRs over the weekend; humans review Monday. Owner: tech lead. Pitfall: handing it product features, agents are great at well-scoped chores, mediocre at ambiguous product work. Use it where it shines. DoD: "agent-authored" PR label exists in GitHub, and at least 5 merge per week.

Tools in this playbook

Next playbooks

Unfamiliar terms are defined in the AI and Revenue Dictionary. Related frameworks live in the framework library.

Share this playbook

Posting to Instagram or TikTok? Copy the link, it carries the title, summary and share image.

Arrives weekly by email. Free. Unsubscribe anytime. By subscribing you agree to our Privacy policy and Terms. We never sell or share the list.