use-cases/refactor-your-codebase.md Codex Docs, 2026-05-02 00:48 UTC → 2026-05-05 23:00 UTC

1# Refactor your codebase | Codex use cases1---

2 2name: Refactor your codebase

3Codex use cases3tagline: Remove dead code and modernize legacy patterns without changing behavior.

4 4summary: Use Codex to remove dead code, untangle large files, collapse

5![](/assets/OpenAI-black-wordmark.svg)5 duplicated logic, and modernize stale patterns in small reviewable passes.

6 6skills:

7![Codex](/assets/OAI_Codex-Lockup_Fallback_Black.svg)7 - token: $security-best-practices

8 8 url: https://github.com/openai/skills/tree/main/skills/.curated/security-best-practices

9Codex use case9 description: Review security-sensitive cleanup, dependency changes, auth flows,

10 10 and exposed surfaces before merging a modernization pass.

11# Refactor your codebase11 - token: $skill-creator

12 12 url: https://github.com/openai/skills/tree/main/skills/.system/skill-creator

13Remove dead code and modernize legacy patterns without changing behavior.13 description: Turn a proven modernization pattern, review checklist, or parity

14 14 workflow into a reusable repo or team skill.

15Difficulty **Advanced**15bestFor:

16 16 - Codebases with dead code, oversized modules, duplicated logic, or stale

17Time horizon **1h**17 abstractions that make routine edits expensive.

18 18 - Teams that need to modernize code in place without turning the work into a

19Use Codex to remove dead code, untangle large files, collapse duplicated logic, and modernize stale patterns in small reviewable passes.19 framework or stack migration.

20 20starterPrompt:

21## Best for21 title: Modernize in Small Passes

22 22 body: >-

23- Codebases with dead code, oversized modules, duplicated logic, or stale abstractions that make routine edits expensive.23 Modernize and refactor this codebase.

24- Teams that need to modernize code in place without turning the work into a framework or stack migration.

25 

26# Contents

27 

28[← All use cases](https://developers.openai.com/codex/use-cases)

29 

30Copy page [Export as PDF](https://developers.openai.com/codex/use-cases/refactor-your-codebase/?export=pdf)

31 

32Use Codex to remove dead code, untangle large files, collapse duplicated logic, and modernize stale patterns in small reviewable passes.

33 

34Advanced

35 

361h

37 

38Related links

39 

40[Modernizing your Codebase with Codex](https://developers.openai.com/cookbook/examples/codex/code_modernization)

41 24 

42## Best for

43 25 

44- Codebases with dead code, oversized modules, duplicated logic, or stale abstractions that make routine edits expensive.26 Requirements:

45- Teams that need to modernize code in place without turning the work into a framework or stack migration.

46 27 

47## Skills & Plugins28 - Preserve behavior unless I explicitly ask for a functional change.

48 29 

49- [Security Best Practices](https://github.com/openai/skills/tree/main/skills/.curated/security-best-practices)30 - Start by identifying dead code, duplicated paths, oversized modules, stale

31 abstractions, and legacy patterns that are slowing changes down.

50 32 

51 Review security-sensitive cleanup, dependency changes, auth flows, and exposed surfaces before merging a modernization pass.33 - For each proposed pass, name the current behavior, the structural

52- [Skill Creator](https://github.com/openai/skills/tree/main/skills/.system/skill-creator)34 improvement, and the validation check that should prove behavior stayed

35 stable.

53 36 

54 Turn a proven modernization pattern, review checklist, or parity workflow into a reusable repo or team skill.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.

55 40 

56| Skill | Why use it |41 - Keep public APIs stable unless a change is required by the refactor.

57| --- | --- |

58| [Security Best Practices](https://github.com/openai/skills/tree/main/skills/.curated/security-best-practices) | Review security-sensitive cleanup, dependency changes, auth flows, and exposed surfaces before merging a modernization pass. |

59| [Skill Creator](https://github.com/openai/skills/tree/main/skills/.system/skill-creator) | Turn a proven modernization pattern, review checklist, or parity workflow into a reusable repo or team skill. |

60 42 

61## Starter prompt43 - Call out any framework migration, dependency upgrade, API change, or

44 architecture move that should be split into a separate migration task.

62 45 

63 Modernize and refactor this codebase.46 - If the work is broad, propose the docs, specs, and parity checks we should

64 Requirements:47 create before implementation.

65 - Preserve behavior unless I explicitly ask for a functional change.

66- Start by identifying dead code, duplicated paths, oversized modules, stale abstractions, and legacy patterns that are slowing changes down.

67- For each proposed pass, name the current behavior, the structural improvement, and the validation check that should prove behavior stayed stable.

68- Break the work into small reviewable refactor passes such as deleting dead code, simplifying control flow, extracting helpers, or replacing outdated patterns with the repo's current conventions.

69 - Keep public APIs stable unless a change is required by the refactor.

70- Call out any framework migration, dependency upgrade, API change, or architecture move that should be split into a separate migration task.

71- If the work is broad, propose the docs, specs, and parity checks we should create before implementation.

72 Propose a plan to do this.

73 48 

74[Open in the Codex app](codex://new?prompt=Modernize+and+refactor+this+codebase.%0A%0ARequirements%3A%0A-+Preserve+behavior+unless+I+explicitly+ask+for+a+functional+change.%0A-+Start+by+identifying+dead+code%2C+duplicated+paths%2C+oversized+modules%2C+stale+abstractions%2C+and+legacy+patterns+that+are+slowing+changes+down.%0A-+For+each+proposed+pass%2C+name+the+current+behavior%2C+the+structural+improvement%2C+and+the+validation+check+that+should+prove+behavior+stayed+stable.%0A-+Break+the+work+into+small+reviewable+refactor+passes+such+as+deleting+dead+code%2C+simplifying+control+flow%2C+extracting+helpers%2C+or+replacing+outdated+patterns+with+the+repo%27s+current+conventions.%0A-+Keep+public+APIs+stable+unless+a+change+is+required+by+the+refactor.%0A-+Call+out+any+framework+migration%2C+dependency+upgrade%2C+API+change%2C+or+architecture+move+that+should+be+split+into+a+separate+migration+task.%0A-+If+the+work+is+broad%2C+propose+the+docs%2C+specs%2C+and+parity+checks+we+should+create+before+implementation.%0A%0APropose+a+plan+to+do+this. "Open in the Codex app")

75 49 

76 Modernize and refactor this codebase.

77 Requirements:

78 - Preserve behavior unless I explicitly ask for a functional change.

79- Start by identifying dead code, duplicated paths, oversized modules, stale abstractions, and legacy patterns that are slowing changes down.

80- For each proposed pass, name the current behavior, the structural improvement, and the validation check that should prove behavior stayed stable.

81- Break the work into small reviewable refactor passes such as deleting dead code, simplifying control flow, extracting helpers, or replacing outdated patterns with the repo's current conventions.

82 - Keep public APIs stable unless a change is required by the refactor.

83- Call out any framework migration, dependency upgrade, API change, or architecture move that should be split into a separate migration task.

84- If the work is broad, propose the docs, specs, and parity checks we should create before implementation.

85 Propose a plan to do this.50 Propose a plan to do this.

51relatedLinks:

52 - label: Modernizing your Codebase with Codex

53 url: /cookbook/examples/codex/code_modernization

54---

86 55 

87## Introduction56## Introduction

88 57 

117 86 

118[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.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.

119If 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.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.

120 

121## Related use cases

122 

123[![](/images/codex/codex-wallpaper-2.webp)

124 

125### Create a CLI Codex can use

126 

127Ask Codex to create a composable CLI it can run from any folder, combine with repo scripts...

128 

129Engineering Code](https://developers.openai.com/codex/use-cases/agent-friendly-clis)[![](/images/codex/codex-wallpaper-1.webp)

130 

131### Create browser-based games

132 

133Use Codex to turn a game brief into first a well-defined plan, and then a real browser-based...

134 

135Engineering Code](https://developers.openai.com/codex/use-cases/browser-games)[![](/images/codex/codex-wallpaper-2.webp)

136 

137### Run code migrations

138 

139Use Codex to map a legacy system to a new stack, land the move in milestones, and validate...

140 

141Engineering Code](https://developers.openai.com/codex/use-cases/code-migrations)