Skip to content
Recipes Ecosystem Source Code Docs

Large Codebase Refactor

Refactor a core service class safely across a large codebase. OpenCode navigates your import graph, updates types, and verifies nothing breaks.

When to use this recipe

  • You need to rename or move a widely-used class, function, or module.
  • The change spans many files and manual edits are error-prone.
  • You want each step committed so you can roll back easily.

Prerequisites

  • OpenCode installed and configured with a capable LLM provider.
  • A clean working tree (commit or stash current changes).
  • A test suite or build command to verify results.

Steps

  1. Start from a clean base

    Commit your current work so OpenCode operates on a known state.

    git status
git add -A && git commit -m "wip: before refactor"

  2. Describe the refactor goal

    Tell OpenCode exactly what to rename and the desired end state.

    Rename the OldService class to NewService across the whole project. Update all imports, type references, and usages. Do not change any public behavior.

  3. Let OpenCode map the impact

    OpenCode reads the import graph and lists every affected file before editing, so you can confirm the blast radius.

  4. Review and apply edits

    Walk through the proposed changes. Ask OpenCode to group edits into logical commits:

    git commit -m "refactor: rename OldService to NewService"

  5. Verify

    Run your build and tests. If anything fails, ask OpenCode to fix the specific error.

    npm run build && npm test

Key prompt

Find every reference to OldService, including imports, type annotations, and string usages. Rename them all to NewService. Show me the file list first, then apply in grouped commits.

Common pitfalls

  • Partial renames: If you stop mid-way, leftover references will break the build. Always let OpenCode finish, then verify.
  • String references: Dynamic references (e.g. container.get('OldService')) may need manual attention — point OpenCode at them explicitly.
  • Generated files: Add build output to .gitignore so it isn’t edited by mistake.

Next up