Taking over a project from another team
Taking over a project is not "understanding the code". It is recovering knowledge nobody wrote down and making the system predictable before anyone asks you for a feature. Here is a sequence that works.
Step 0: credentials, all of them
Before opening an editor, collect the full list: repository, image registry, server, database, DNS, domain, mail provider, payment gateway, analytics, file storage, CI. Every one of them must sit on your account or the client’s — not on the personal address of someone who has left.
This is the dullest step and the most common reason things stop a month later: the domain renews from a former contractor’s card, and on expiry day the site disappears.
Step 1: run it locally, from scratch, from the instructions
The goal is not "it works on my machine" but a reproducible run: a fresh clone, documented environment variables, one command. Everything you had to do by hand to get it up is exactly what is missing from the documentation. Write it down while you still remember.
If it cannot be run locally at all, that is risk number one in the report. A project that exists only in production can be neither changed safely nor restored after an incident.
Step 2: an audit the client can read
A technical audit for a client is not a list of code review comments. It is a list of risks with consequences and rough costs. Sort it into three groups:
- Can stop the business. No backups. Secrets in the repository. A certificate with no auto-renewal. A dependency that is no longer maintained.
- Slows down every change. No tests. No local run. The same logic in three places. No migrations, the schema edited by hand.
- Cosmetic. Code style, naming, folder structure.
Leave the third group alone for the first few months. Refactoring for beauty in unfamiliar code is the fastest way to break something you do not understand yet.
The first job of a new team is not to improve the code but to make the system predictable. Beauty comes later.
Step 3: stabilisation
The order is almost always the same:
- Backups on a schedule, with a restore test. Restore the database into a test environment and confirm the data is there.
- Monitoring and alerts. Until you can see outages, you learn about them from the client — the most expensive channel there is.
- Secrets out of the code and into the environment. Rotate them while you are at it: anything that sat in a repository should be considered compromised.
- CI with lint, types and a build. Even without tests this catches half the accidental breakage.
- Tests for the one scenario that matters. A single end-to-end test on checkout or on the enquiry form beats a hundred unit tests on helpers.
Step 4: the first feature
Pick something small but end to end: from the form to the database and back. It reveals the true state of every layer better than a week of reading code, and it gives the client something visible while you do the invisible stabilisation work.
How to talk to the client
Two mistakes, both expensive. The first is saying "this is all bad, it needs a rewrite". It is almost never true and it always sounds like an attempt to sell a bigger contract. The second is quietly firefighting and showing zero progress in the first month.
What works: a report with the three risk groups, an estimate per item and a proposed order. The client makes a decision instead of receiving a verdict. Then a short "done this, left that" every two weeks.
- Collect credentials before opening the editor
- A reproducible local run matters more than reading the code
- An audit is risks with consequences and costs, not style comments
- Cosmetic refactoring in unfamiliar code waits for months
For a mid-sized project, three days to two weeks, depending on whether it can be run locally. The multiplier is not the amount of code but the number of undocumented manual steps.
When the cost of a single change exceeds the cost of building it again, and you can see that across several tasks in a row. Before that it is a guess, not a conclusion.
