Thirty Days in the Dark: A Field Manual for the Codebase Nobody Will Miss When You Leave

There's a particular moment, usually around 4pm on your second day, when it lands. The client calls it 'the system'. Not the invoicing system, not the booking platform — just the system, definite article, as if there's no other. The bloke who wrote it left in 2019 and, according to the office manager, 'went back to Portugal'. There is no documentation. There is a single staging environment that's been down since March. And you're now the person responsible for it.

Welcome to brownfield development. It's where most of the actual software in the British economy lives, and almost none of it gets written about because greenfield tutorials make better conference talks. So let's do the unglamorous thing and talk about what you actually do in your first thirty days.

Week One: Be an Archaeologist, Not a Builder

The instinct is to start fixing things. Resist it. You don't yet know which of the weird behaviours are bugs and which are load-bearing accidents that the client's entire order pipeline depends on.

Instead, spend the first week mapping. Not refactoring — mapping. Get the thing running locally, even if it takes two days of wrestling with a PHP version that's no longer in any package repository. Every hour of that wrestling is knowledge: you're learning exactly how fragile the setup is, and you'll want that later.

Then trace the critical paths. What happens when a customer places an order? When an invoice is generated? Follow the code by hand, write down what you find, and — this is the important bit — start the documentation you wish you'd been handed. A plain markdown file in the repo, a diagram on a whiteboard photographed and shoved in a docs/ folder. It doesn't need to be good. It needs to exist, because right now the only documentation is in the head of a person who left four years ago.

Week Two: Build the Safety Net Before You Touch Anything

Here's the uncomfortable truth about most legacy codebases we've audited over the years: the tests, where they exist at all, cover the easy bits. The gnarly business logic — the VAT rounding rules, the bespoke courier integration, the thing that emails a specific person in Warrington when stock drops below ten — is all untested, because the original author tested it by looking at it very hard.

You cannot safely change untested code. So before you change anything, you write tests against the current behaviour, bugs and all. This is characterization testing, and it feels wrong the first time you do it, because you're enshrining behaviour you know is incorrect. That's fine. The test isn't a statement of what should happen; it's a tripwire that tells you when you've accidentally changed something.

Start with the paths that would cost the client money if they broke. Get those pinned down first, even crudely. A scrappy test suite covering the happy path of the top five workflows is worth more than an elegant architecture diagram at this stage.

And while you're at it: sort out backups. Actually restore one. A backup you've never restored is a rumour, not a backup.

Week Three: Manage the Human Side

Somewhere around week three, someone at the client will ask the question: "While you're in there, could we just... rebuild it properly?"

Do not take the bait. The rewrite conversation, triggered casually in week three, is how projects die. You don't know enough yet to say whether a rewrite is sensible, and neither do they. What you can say honestly is: "Let's spend another few weeks understanding what we've got, then I'll give you a proper view on it." That's not stalling — it's genuinely the only defensible position.

What you should push for in week three is small, visible wins. The cron job that fails every Tuesday and spams someone's inbox. The deployment process that involves a laptop and a prayer. Fixing the annoying things around the system buys you credibility and buys the client patience, which you will need.

Week Four: Write Down What You Know

By now you've got a mental map, a nascent test suite, and a client who's stopped assuming you're going to break everything. Time to consolidate.

Your thirty-day checklist, roughly:

• Running locally — with setup instructions written down for the next person
• Critical paths traced and documented — even as rough notes
• Characterization tests on the money-touching workflows
• Backups verified by an actual restore
• A risk list — the three things most likely to fall over, shared with the client in plain English
• A recommendation — improve in place, wrap and replace incrementally, or (rarely) rebuild. With evidence.

That last point matters. After thirty days you'll have a genuine opinion, grounded in what the code actually does rather than what it looks like from the outside. Sometimes the answer is that the ugly code is fine and the real risk is the server in a cupboard in Sheffield. Sometimes it's genuinely time to start planning an exit. Either way, you'll be saying it with data.

The Long Game

Brownfield work gets a bad reputation, but it's some of the most valuable engineering you'll ever do — and, increasingly, some of the most hireable. Every business in the country is sitting on a system like this, held together by one person's knowledge and a hosting bill nobody's read carefully.

The developers who thrive in that world aren't the ones who know the shiniest framework. They're the ones who can walk into a dark room, find the light switch, and leave better notes than they found. Thirty days is enough to make a start.