Verified against Claude Code · 2026-07-29
Plan a repo-wide pattern migration as a codemod, not five hundred manual edits
A large-scale transformation plan that defines the exact before-and-after pattern once, verifies it against a codemod tool on a sample before running it repo-wide, and stages rollout by directory — distinct from a single dependency's breaking-change migration, this is for a systemic pattern change across the whole codebase.
The prompt
Ready to copy — highlighted parts are example details you can swap.
You are planning a repo-wide transformation of one specific pattern into another, at a scale where manually editing every occurrence by hand is not a realistic or reliable option. This is a planning and tooling task first — do not begin editing individual files by hand until the codemod itself has been verified on a small sample. THE PATTERN, BEFORE AND AFTER Before: class components extending React.Component with a componentDidMount lifecycle method. After: functional components using useEffect with an empty dependency array for the equivalent mount-only behavior. ROUGHLY HOW MANY FILES THIS TOUCHES Roughly 60 to 70 component files, based on a quick grep for extends React.Component. CODEMOD TOOLING AVAILABLE jscodeshift, already used elsewhere in this monorepo for a prior migration. STAGING BOUNDARY FOR ROLLOUT Stage by top-level feature directory: components/checkout first as the smallest and most test-covered, then components/reports, then everything else. PROCESS 1. State the transformation rule with enough precision that it could be applied mechanically, not just described in prose — the exact syntactic shape being matched, and the exact shape it becomes, including how any variation in the original pattern, such as a different variable name or an extra prop, should be handled rather than assumed away. 2. Search the codebase for every occurrence matching the before-pattern, using Roughly 60 to 70 component files, based on a quick grep for extends React.Component. as a sanity check against what the search actually finds — if the real count is far off from the estimate, that is a signal the pattern definition in step one is either too broad or too narrow, and worth revisiting before writing the codemod itself. 3. Write the codemod using jscodeshift, already used elsewhere in this monorepo for a prior migration., and run it against a small, representative sample of five to ten files first, not the whole codebase — review the actual diff on that sample by hand before trusting the codemod at scale, since a codemod that is subtly wrong will be wrong identically and invisibly across every file it touches, which is a much larger blast radius than the same mistake made once by hand. 4. Once the sample diff is confirmed correct, run the codemod against Stage by top-level feature directory: components/checkout first as the smallest and most test-covered, then components/reports, then everything else.'s first stage only, not the entire estimated file set at once — commit that stage, run the test suite, and confirm nothing broke before proceeding to the next stage. 5. Name any occurrence the codemod could not handle automatically, and why — an edge case genuinely too irregular for the mechanical rule to cover, a file where the pattern appears inside a string or a comment rather than real code, or a case where the surrounding context changes what the correct transformation actually is. List these for manual handling rather than forcing the codemod to attempt them and silently producing a wrong result. CONSTRAINTS - Do not run the codemod against the full estimated file set before it has been verified on a sample and on at least one staged rollout boundary. - If the codemod tool itself cannot express part of the transformation rule, say so rather than writing a codemod that handles most of the pattern correctly and silently mishandles the rest. - Track progress with a running count of files transformed against the total, not a vague sense of 'mostly done.' OUTPUT The precise transformation rule, the codemod script, the sample-diff review result, the staged rollout plan, and the list of occurrences requiring manual handling.
Customize
Optional — swap in your own details for the highlighted parts above.
Why this works
A pattern that recurs across sixty or seventy files is a fundamentally different problem from the same pattern appearing in one file, because the actual risk shifts from getting one instance right to getting one rule right and then trusting it uniformly — a codemod that is subtly wrong is wrong identically across every file it touches, which sounds like consistency but is actually a much larger blast radius than a single hand-made mistake, since the same subtle error now needs to be found and re-fixed sixty or seventy times instead of once. Requiring the transformation rule to be stated precisely enough to apply mechanically, rather than described only in prose, forces the exact ambiguity a manual edit could quietly resolve case by case — such as what happens to a slightly different variable name or an extra prop — to be decided once, explicitly, before it gets baked into a tool that will apply that same decision everywhere without the chance to notice a particular instance deserved different handling. Checking the actual search result count against the rough estimate is a real sanity check with a specific failure mode it catches: an estimate wildly off from what the codebase search actually finds means the pattern definition itself is probably too broad, catching things that only superficially resemble the target, or too narrow, missing real occurrences written in a slightly different but equivalent form, and either error compounds silently if the codemod is trusted at the estimate's face value instead. Verifying on a small sample before running at scale, and staging the rollout by directory rather than attempting the whole estimated set in one pass, both exist because a codemod's failure mode is not a crash that stops execution, it is a plausible-looking but wrong transformation that a test suite might not catch if the tests themselves were not written to distinguish the old and new behavior precisely — reviewing five to ten files by hand catches what a codemod cannot self-report, and staging the rollout means a defect discovered at stage two is attributable to a small, known change set rather than lost somewhere inside a single sixty-file commit. Explicitly listing what the codemod could not handle, rather than letting it attempt every occurrence uniformly, matters because the alternative failure — a codemod that mishandles an edge case silently rather than skipping it — produces a file that looks migrated and runs cleanly right up until the specific behavior that edge case depended on breaks in a way nobody flagged as worth checking.
Verified against
Claude Code Sonnet 4.6 · 2026-07-29
Changelog
- 2026-07-29 — Initial publish, verified against Claude Code with jscodeshift-driven migration planning (Sonnet 4.6).
Building this for real?
This is a free starting point. If you'd rather have custom software built and running for your business, that's Scult's day job.
EXPLORE CUSTOM SOFTWARE
