use-cases/refactor-your-codebase.md +88 −0 added
1---
2name: Refactor your codebase
3tagline: Remove dead code and modernize legacy patterns without changing behavior.
4summary: Use Codex to remove dead code, untangle large files, collapse
5 duplicated logic, and modernize stale patterns in small reviewable passes.
6skills:
7 - token: $security-best-practices
8 url: https://github.com/openai/skills/tree/main/skills/.curated/security-best-practices
9 description: Review security-sensitive cleanup, dependency changes, auth flows,
10 and exposed surfaces before merging a modernization pass.
11 - token: $skill-creator
12 url: https://github.com/openai/skills/tree/main/skills/.system/skill-creator
13 description: Turn a proven modernization pattern, review checklist, or parity
14 workflow into a reusable repo or team skill.
15bestFor:
16 - Codebases with dead code, oversized modules, duplicated logic, or stale
17 abstractions that make routine edits expensive.
18 - Teams that need to modernize code in place without turning the work into a
19 framework or stack migration.
20starterPrompt:
21 title: Modernize in Small Passes
22 body: >-
23 Modernize and refactor this codebase.
24
25
26 Requirements:
27
28 - Preserve behavior unless I explicitly ask for a functional change.
29
30 - Start by identifying dead code, duplicated paths, oversized modules, stale
31 abstractions, and legacy patterns that are slowing changes down.
32
33 - For each proposed pass, name the current behavior, the structural
34 improvement, and the validation check that should prove behavior stayed
35 stable.
36
37 - Break the work into small reviewable refactor passes such as deleting dead
38 code, simplifying control flow, extracting helpers, or replacing outdated
39 patterns with the repo's current conventions.
40
41 - Keep public APIs stable unless a change is required by the refactor.
42
43 - Call out any framework migration, dependency upgrade, API change, or
44 architecture move that should be split into a separate migration task.
45
46 - If the work is broad, propose the docs, specs, and parity checks we should
47 create before implementation.
48
49
50 Propose a plan to do this.
51relatedLinks:
52 - label: Modernizing your Codebase with Codex
53 url: /cookbook/examples/codex/code_modernization
54---
55
56## Introduction
57
58When 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.
59
60Codex 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.
61
62The goal is to improve the current codebase in place:
63
641. Remove unused code, stale helpers, old flags, and compatibility shims that are no longer needed.
652. Shrink noisy modules by extracting helpers, splitting components, or moving side effects to clearer boundaries.
663. Replace legacy patterns with the repo's current conventions: newer framework primitives, clearer types, simpler state flow, or standard library utilities.
674. Keep public behavior stable while making the next change cheaper.
68
69## How to use
70
711. 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.
722. 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.
733. 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.
744. Review and run the smallest useful check after each pass instead of batching the whole cleanup into one diff.
755. Keep stack changes, dependency migrations, and architecture moves as separate tasks unless they're required to finish the cleanup.
76
77You can use Plan mode to create a plan for the refactor before starting the
78 work.
79
80## Leverage ExecPlans
81
82The [code modernization cookbook](https://developers.openai.com/cookbook/examples/codex/code_modernization) introduces ExecPlans: documents that let Codex keep an overview of the cleanup, spell out the intended end state, and log validation after each pass.
83They'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.
84
85## Use skills for repeatable patterns
86
87[Skills](https://developers.openai.com/codex/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.
88If 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.