The Lore of the Codebase: Why Your Team's Weirdest Habits Might Be Load-Bearing

Every team I've ever worked on had a rulebook that nobody wrote. Not the confluence page with the branching strategy and the PR checklist — the other one. The one that lives in raised eyebrows and pointed coughs. The one you learn the hard way, usually at 5:40pm on a Thursday when you've just kicked off a migration and three people have materialised behind your chair like a jury.

We tend to treat these habits as quirks. Folklore. Slightly embarrassing tribal behaviour that a 'properly run' team would have grown out of. I've come to believe the opposite: most unwritten rules are compressed incident reports. Somebody paid for that knowledge, once, in a very memorable currency — and the rule is the receipt.

Where the Rules Actually Come From

Ask why you don't deploy on a Friday afternoon and the honest answer is usually 'because we don't'. Push a bit further and a story emerges. The Great Outage of 2019. The time the payment provider did a scheduled maintenance nobody had in the calendar. The release that went out clean at 4pm and detonated at 4:15, with half the team already on the M25.

That's the pattern worth noticing: the rule is the lesson, minus the context. Which is fine right up until the context matters again — a new provider, a new deployment pipeline, a team that's all-remote and no longer clustered around the same metaphorical campfire. A rule without its origin story can't be re-evaluated. It just gets obeyed, or quietly ignored, and either way you've lost something.

The Audit Nobody Schedules

Here's a practical exercise that costs one meeting and a decent pack of biscuits: get the team in a room (or a call) and write down every unwritten rule you can think of. Don't debate them yet. Don't fix them. Just capture them.

You'll get roughly three flavours:

• Genuinely load-bearing. 'We don't touch the VAT calculation logic without a second pair of eyes.' This is process that never got formalised. Promote it: make it an actual CODEOWNERS entry, a PR template note, a checklist item.
• Historical but harmless. 'Standup is at 10 because the old office car park flooded before 9:30.' Fine. Keep it, but now it's documented folklore rather than mystery.
• Fossilised nonsense. 'We always deploy from Steve's laptop.' This one should scare you. It's a single point of failure wearing a lanyard.

That third category is where the real work is. Anything that depends on one person's machine, one person's memory, or one person's willingness to be pinged on Teams is not a process — it's a countdown.

The Spreadsheet Problem

Every team has a Dave. Dave knows the reconciliation spreadsheet. Dave knows why the staging environment points at that weird IP. Dave knows which client invoices go through the legacy payment path. Dave has just accepted a role at a fintech in Manchester and his last day is in three weeks.

Documentation-as-Dave is the most common architectural pattern in British SMEs, and it's never in the architecture diagrams. The fix isn't a heroic documentation sprint nobody has time for — it's the boring version:

1. Ask Dave to narrate, not write. Pair with someone else, record the session, and let that person write the notes. People document other people's knowledge far more reliably than their own.
2. Target the blast radius. You don't need Dave's entire brain. You need the three things that would cause an incident if he vanished tomorrow. Start there.
3. Delete as you go. Half of undocumented knowledge is compensating for something that should be automated anyway. Every 'ask Dave' step is a candidate for a script, a runbook, or a proper config file.

Rules Should Have Retirement Dates

Once your rules are written down, give them the same lifecycle as your code. A rule that made sense when your monolith ran on a single box in a Slough data centre may be pure friction now that you're on Kubernetes. An unwritten rule can never be retired — it can only be forgotten, which is worse, because sometimes it gets forgotten by the wrong person at the wrong time.

Stick a review date on the list. Six months. Re-read it, keep what's earned its place, kill what hasn't. A short living document beats a beautiful one that's wrong.

Write It Down Before You Have To

There's a version of this article where I tell you a horror story about the dev who left and took the release process with them. You've probably already lived your own version of it — the frantic Slack archaeology, the 'does anyone know the SSH password for the old box', the dawning realisation that the answer was 'a bloke called Tom, 2018'.

Your team's weird rules are assets. Some are worth promoting into real process, some are worth keeping as culture, and some are time bombs. But you can't manage any of them while they're still invisible. Book the meeting. Bring the biscuits. Write the lore down.