Codebase takeover playbook

A playbook for the day you inherit a codebase. The code may come from a departed developer, an agency, an AI app builder or a company you plan to buy. It starts with triage in a fixed order, so access, secrets and backups come before any change to the code.

Then it pins today's behaviour with tests, decides between rewriting and refactoring, and moves an app off an AI builder one route at a time. Later chapters cover major framework and runtime upgrades and a register for technical debt. The last chapter turns a technical due diligence into rules, so a signed report can cite each finding by its rule ID.

Make no change before the first chapter is done. Most damage in a takeover comes from a fix made before anyone knew what the code did.

Chapters

1. Triage

   Before the first change to inherited code, take the accounts, rotate the secrets, prove a restore, get it running and measure where it starts.

   • Required 3
   • Recommended 4

2. Characterization tests

   Before changing inherited code, record what it does today in tests. Keep known bugs pinned until their own fix, and cut seams to reach hard code.

   • Recommended 3

3. Rewrite or refactor

   Improve inherited code in small shipped steps. Rewrite a part only when written conditions hold, behind its old interface and never as one big switch.

   • Recommended 3
   • Avoid 1

4. Leaving an AI builder

   Move an app off an AI builder one route at a time. Give each table one writer, compare answers, keep passwords and switch off the old app on a date.

   • Required 1
   • Recommended 4

5. Major upgrades

   Keep one list of support end dates and act before them. Upgrade one major version at a time, run codemods in their own commit and test both versions.

   • Required 1
   • Recommended 2
   • Optional 1

6. Technical debt

   Keep debt in a register in the repository, ranked by its monthly cost. Spend a set share of each cycle on it and record every shortcut when you take it.

   • Recommended 3

7. Due diligence

   Check a product before you buy or invest in it. Build it yourself, scan its history, test its access rules, and tie each finding to a rule ID and evidence.

   • Required 3
   • Recommended 10

All 39 rules on one page

This is a lot to check. An Expert can check it for you.

Related playbooks

• Apps built with AI builders

  In the AI-assisted development playbook. Most inherited apps today come from an AI builder. Close its usual holes before the move starts.

• Output comparison

  In the Testing playbook. Prove that a refactor changed nothing by comparing the whole output before and after.

• Dead code

  In the Clean code and architecture playbook. A takeover finds code, flags and packages nobody uses. Delete them in small steps.

• Access and accounts

  In the Adversarial testing playbook. Test who can reach which records before you trust inherited permission code.