Introduction

When your codebase has accumulated unused code, duplicated logic, stale abstractions, large files, or legacy patterns that make every change more expensive than it should be, you should consider reducing the engineering debt with a refactor. Refactoring is about improving the shape of the existing system without turning it into a stack migration.

Codex is useful here because it can first map the messy area, then land the cleanup in small reviewable passes: deleting unused paths, untangling large modules, collapsing duplicate paths, modernizing old framework patterns, and tightening validation around each pass.

The goal is to improve the current codebase in place:

1. Remove unused code, stale helpers, old flags, and compatibility shims that are no longer needed.
2. Shrink noisy modules by extracting helpers, splitting components, or moving side effects to clearer boundaries.
3. Replace legacy patterns with the repo’s current conventions: newer framework primitives, clearer types, simpler state flow, or standard library utilities.
4. Keep public behavior stable while making the next change cheaper.

How to use

1. Ask Codex to map the area before editing: noisy modules, duplicated logic, unused code, tests, public contracts, and any old patterns that the repo has outgrown.
2. Pick one cleanup theme at a time: remove unused code, simplify control flow, modernize an outdated pattern, or split a large file into smaller owned pieces.
3. Before Codex patches files, have it state the current behavior, the structural improvement it wants to make, and the smallest check that should prove behavior stayed stable.
4. Review and run the smallest useful check after each pass instead of batching the whole cleanup into one diff.
5. Keep stack changes, dependency migrations, and architecture moves as separate tasks unless they’re required to finish the cleanup.

Leverage ExecPlans

The code modernization cookbook introduces ExecPlans: documents that let Codex keep an overview of the cleanup, spell out the intended end state, and log validation after each pass. They’re useful when the refactor spans more than one module or takes more than one session. Use them to record deletions, pattern updates, contracts that had to stay stable, and what’s still deferred.

Use skills for repeatable patterns

Skills are useful when the same cleanup rules repeat across repos, services, or teams. Use framework-specific skills when available, add security and CI skills around risky cleanups, and create a team skill when you have a proven checklist for unused-code removal, module extraction, or legacy-pattern modernization. If you end up doing the same modernization pass across more than one codebase, Codex can help turn the first successful pass into a reusable skill.