The previous agency has signed off. The handover was a zip file, a shared password document and a forty-minute call. Now your team is looking at a repository nobody fully understands, production keeps throwing errors, and the original estimate bears no relation to what is left to do.
That is what inheriting a failing codebase looks like in practice. The pressure to start fixing things immediately is understandable, and it is usually the first mistake.
The Right Approach
Treat an inherited codebase as an unknown system. Secure access, assess before making changes, stabilise production and rebuild missing knowledge before deciding whether to fix, refactor, replace parts or rebuild. A rewrite on day one is rarely an evidence-based decision.
What Makes an Inherited Codebase So Hard to Work With?
The code may still run perfectly well in production. That does not mean it is safe to change.
An inherited codebase is difficult because the knowledge that made it workable left with the previous team. What remains is code, infrastructure and a set of assumptions nobody wrote down.
| Problem | What it may indicate | Business impact |
|---|---|---|
| Undocumented code | Knowledge sat with one or two people | Slow onboarding, cautious and expensive changes |
| Technical debt | Shortcuts were taken under deadline pressure | Slower releases, unpredictable estimates |
| Outdated dependencies | Updates were skipped to avoid breakage | Security exposure, harder upgrades later |
| Missing or thin tests | Changes were verified by hand, if at all | Regressions reach users |
| Unclear architecture | The design grew without a plan | Every change feels risky |
| Fragile integrations | Third-party and API links were patched, not built to last | Intermittent failures nobody can explain |
| Deployment problems | Releases rely on manual steps or one person’s memory | Delayed releases, stressful rollbacks |
| Security gaps | Never assessed against current standards | Data exposure, loss of stakeholder confidence |
A typical version: the payment integration works only because a former developer’s personal API key is still sitting in the configuration. Nobody knows until the key is revoked and checkout stops.
The cost shows up in developer time. Chainguard’s 2026 Engineering Reality Report, a survey of 1,200 engineers and senior technology leaders, found that 79% of engineers see code maintenance as a major drain on their time. An inherited codebase tends to sit at the sharp end of that pattern, because the team maintaining it also has to learn it.
Taking Over From Another Development Team: Secure Access First
A software project takeover is as much about access and ownership as code. Before you assess anything, confirm that you can reach everything the system depends on.
A responsible engineering handover covers:
-
- Repository ownership and source-code access, including all branches
- Hosting and cloud infrastructure, with ownership of the accounts
- Domains, DNS and certificates, which are often registered to a person rather than a company
- Credentials and secrets for every environment
- CI/CD pipelines and environments
- Database access and backup arrangements
- APIs and third-party integrations, including who owns each account
- Documentation, backlog and known bugs
- Deployment history and any recent incidents
- Outstanding scope and agreed-but-unbuilt features
- Known technical debt and the reasons behind it
Check the contract as well. Ownership of code, accounts and intellectual property should be unambiguous, and our guide to protecting IP when working with a development agency covers what to confirm.
Keep the tone professional. Changing software development teams is rarely a story of one party failing. Most handovers lose context because nobody was asked to preserve it.
What to Do in the First Week
Access alone is not enough. The first week is about making the project safe to examine, not about fixing it.
-
- Rotate credentials and revoke the previous team’s access once your own access is confirmed
- Take verified backups of the database and configuration before anyone touches anything
- Build and run the application locally and in a staging environment. If it cannot be built from the repository alone, that is your first finding
- List known production incidents and who is affected by each
- Pause non-essential releases, so the system stays still while you learn it
- Identify key-person dependencies: who knew what, and whether they can still be reached
- Set up basic error tracking and monitoring, so failures surface before users report them
Just as important is what to leave alone. Do not upgrade the framework, bump major dependencies or start refactoring in week one. Each change makes it harder to tell whether a problem was inherited or introduced.
How to Assess an Inherited Codebase
Do this before anyone writes a line of new code. A codebase assessment is not a judgement on the previous team. It is how you replace assumptions with evidence.
The first mistake is treating the codebase as if the new team already understands it. The assessment exists to close that gap.
| Area | What to check | Why it matters |
|---|---|---|
| Repository and history | Ownership, branching, commit patterns, how recently code changed | Shows who touched what and where the risk sits |
| Architecture | Structure, boundaries, coupling, fit with current needs | Tells you if the design can carry the roadmap |
| Dependencies | Versions, end-of-life packages, known vulnerabilities | Finds security and upgrade risk early |
| Security | Authentication, access control, data handling, secrets | Exposure rarely announces itself |
| Tests | Coverage, reliability, what is untested | Determines how safely you can change things |
| CI/CD and deployment | Build stability, manual steps, rollback process | Predictable releases come before new features |
| Infrastructure and data | Hosting, environments, database dependencies, backups | Hidden dependencies cause the worst surprises |
| Integrations | API and third-party dependencies, error handling | Fragile links break without warning |
| Documentation | What exists, what is wrong, what is missing | Sets the scale of knowledge recovery |
| Production issues | Logs, incidents, recurring bugs | Shows what is actually failing for users |
| Business scope | What was agreed, what is built, what remains | Resets the estimate against reality |
For example, if the repository shows the deployment script was last edited fourteen months ago by someone no longer on the project, test the release process before you trust it.
Dependencies deserve particular attention. In its 2025 Top 10, OWASP replaced “Vulnerable and Outdated Components” with a broader category, A03:2025 Software Supply Chain Failures, which covers weaknesses in third-party libraries, build systems and delivery pipelines. An inherited project is where this exposure hides, because nobody knows exactly what the dependencies are or who can push a change through the pipeline.
A source code review should be structured, not a read-through. Practices like early code reviews help surface performance problems before they reach production, and a DevOps maturity assessment shows how safe your deployment process really is.
What should the assessment tell you?
Six plain questions:
-
- What works?
- What is broken?
- What is risky?
- What can be salvaged?
- What needs fixing?
- What should be replaced?
What a good assessment should hand you
A discussion is not a deliverable. Whoever does the work, you should come away with:
-
- An architecture map showing components, data flows and external dependencies
- A dependency and vulnerability report, ranked by severity
- A risk register covering security, deployment, data and key-person dependencies
- A prioritised stabilisation backlog, not a flat list of bugs
- A recommendation on fix, refactor, replace or rebuild, with the reasoning shown
- A revised estimate based on what was found, not on the original plan
How long this takes depends on size. A small, contained application is usually a matter of weeks; a multi-year platform with many integrations takes longer. Be wary of anyone who quotes a fixed duration before seeing the code.
Stabilise Before You Modernise
Short answer: Stabilising an inherited codebase means making it predictable enough to change safely. Fix what threatens production, security and releases first. Modernisation comes after.
For an inherited project the order is: Secure access → Assess → Stabilise → Decide → Improve.
The temptation is to jump to the end. Resist it. Rewriting everything, introducing a new framework, rebuilding the architecture or adding features on an unstable base usually stacks new problems on old ones.
Stabilisation typically includes:
-
- critical bug remediation and production fixes
- deployment reliability and CI/CD improvements
- security remediation and dependency updates
- regression tests around the most important behaviour
- fixing the worst performance issues
The goal is not a perfect system. It is a system that behaves the same way tomorrow as it did today.
What If There Is No Documentation?
You can still start. A new team does not need perfect documentation before work begins, because the system itself is the best record of what it does.
Missing architecture diagrams, deployment notes and business rules are common in an inherited project. Knowledge can be rebuilt through:
-
- Repository analysis, including commit history and who changed what
- Application walkthroughs, using the product as a user would
- Logs and deployment history, which show what actually happens in production
- Code review of the riskiest modules first
- Stakeholder interviews with the people who use and sponsor the system
- Characterisation tests, which capture current behaviour before you change it
- Living system documentation, written as you learn rather than saved for later
If the previous team is reachable, ask for a knowledge-transfer session. Even an hour of “why is this like that?” can save weeks.
Should You Refactor or Rebuild an Inherited Codebase?
A rewrite should be an evidence-based decision, not a reaction to frustration. Weigh architecture, technical debt, code quality, test coverage, business logic, integrations, data, security, cost, timeline and risk.
| What the assessment finds | Likely route | Reason |
|---|---|---|
| Isolated defects, sound structure | Fix | Lowest cost and risk |
| Sound architecture, risky or messy code | Refactor | Improves maintainability without changing behaviour |
| Ageing stack, working business logic | Incremental modernisation | Keeps the system live while it improves |
| A few modules unfit for purpose | Selective replacement | Rebuilds only what is genuinely broken |
| Architecture cannot support requirements, or fixing costs more than starting again | Full rebuild | The foundation, not the code, is the problem |
For example, a reporting module with tangled logic but a sound data model is a refactor candidate. A payments module built on an unsupported library is a replacement candidate. Neither justifies rebuilding the whole product.
Most inherited projects land in the middle rows. A full rebuild is the exception, and it carries its own risks: lost business logic, data migration and a long stretch with no visible progress.
Technical debt remediation works best when it is incremental and protected by tests. The cost of technical debt explains why leaving it alone is rarely free.
When Does an Inherited Codebase Need Rescue?
Most inherited projects can be stabilised by the team that now owns them. If the assessment shows fixes that keep failing, a release process nobody trusts and no one who understands the architecture, a structured recovery engagement may be faster than going it alone. Our guide to software rescue services explains what that involves, and our advice on choosing a software development partner covers how to pick one.
Taking the Next Step
Inheriting a failing codebase is recoverable. The projects that recover are the ones where someone measured the situation honestly before changing it.
Secure access first, assess second, stabilise third, then decide between fixing, refactoring, replacing parts or rebuilding on the evidence.
FAQs On Inheriting A Failing Codebase
Should I start fixing bugs straight away when inheriting a failing codebase?
No. Confirm access, take backups and assess the system first. Fixing before you understand it risks breaking behaviour nobody documented, and it muddies the evidence. Only urgent production faults justify an immediate fix, and even those should be made small, tested and recorded.
How do you assess an inherited codebase?
Review the repository history, architecture, dependencies, security, tests, deployment pipeline, infrastructure and integrations, then compare what exists with the agreed scope. A good assessment answers what works, what is broken, what is risky and what can be salvaged before any code changes.
What if an inherited codebase has no documentation?
Rebuild knowledge from the system itself: repository history, application walkthroughs, logs, deployment records and stakeholder interviews. Write tests around critical behaviour to capture business rules, and document as you learn. You need enough understanding to change things safely, not perfect documentation.
How long does it take to stabilise an inherited project?
It depends on size and severity. A small, contained application is usually a matter of weeks; a large platform with many integrations takes longer. Assessment and stabilisation are separate phases, so get a firm estimate for stabilisation only after the assessment shows what you are dealing with.
Should I refactor or rebuild an inherited codebase?
Neither by default. Refactor when the architecture is sound but the code is risky to change, replace specific modules that are unfit, and rebuild only when evidence shows the foundation cannot support the product. Let the assessment drive the decision, not frustration with the current state.
What does a codebase audit include?
A codebase audit reviews code quality, architecture, dependencies and vulnerabilities, test coverage, CI/CD, infrastructure, database and API dependencies, documentation and open defects. It should end with a prioritised risk list and a recommendation, not just a score, so the next steps are clear.
How do you manage technical debt in an inherited project?
List the debt by business risk, not by how untidy the code looks. Fix what threatens production, security or delivery speed first, and leave harmless untidiness alone. Refactor incrementally alongside feature work, protected by tests, rather than pausing delivery for one large clean-up.
What should I do in the first week after inheriting a codebase?
Confirm access to the repository, hosting, databases and third-party accounts, then rotate credentials and take backups. Get the application running locally and in staging, list known production incidents, and pause non-essential releases until the assessment is complete.
