Every now and then I join a project where "everything works, but nobody dares to touch it." Deployment is done by hand from memory, the architecture grew historically, knowledge lives in people's heads, hiring happens by accident. That's normal: this is what almost any project looks like when it grows faster than it matures.
You don't bring order to a project like that in one heroic push. What works is different: split the chaos into tracks, take small steps within each track, and make every step pay off immediately. Below is my complete plan — what to do, in what order, and why. Each track will get its own deep-dive article; this is the map.
How to use this plan
- Snapshot first, then light, then changes. Don't fix anything until you can see what's going on.
- Tracks run in parallel, at different speeds — push the one that hurts right now.
- A step must fit into a week. If it doesn't, it's not a step, it's a project; keep cutting.
- Every touch leaves a trace: touched a service — bring it closer to the standard; figured out a piece of the system — write it down.
Track 0. State snapshot
One week, fix nothing — only look and write down.
⬜ Service map: what exists, where it lives, who deploys it and how
⬜ The "scary places" list — things people describe as "better not touch it"
⬜ Who knows what: which knowledge has a single carrier
⬜ Top 5 risks — one page, in plain human language
💬 The main artifact of this stage is not a document but a picture in your head. The document is a way to verify it: show it to the team, let them correct you.
📖 Full article: the state snapshot — your first week on a new project.
Track 1. Observability — turn on the lights
⬜ Centralized, structured logs
⬜ HTTP and database metrics
⬜ 3–5 alerts for the things that actually wake you up at night
⬜ A request_id passed through every service
💬 This track goes first because it makes every other track cheaper: any change is visible, any incident takes minutes to investigate instead of "going by gut feeling."
📖 Full article: how developers can monitor production — and why it matters.
Track 2. Infrastructure and deployment
⬜ CI/CD on the most frequently deployed service
⬜ Configuration in git, not on servers
⬜ A reference service template: structure, Dockerfile, healthcheck, pipeline
⬜ Rule: new services only from the template; old ones catch up as you touch them
💬 The goal of this track is for deployment to stop being an event and stop being one person's knowledge. The success marker: a Friday deploy scares no one.
📖 Full article: infrastructure and deployment — order by iteration.
Track 3. Architecture
⬜ Draw the system "as is" — honestly, without prettifying
⬜ Find the boundaries: what is genuinely a separate service and what got glued together by accident
⬜ Start a decision log — short records, half a page: what was decided and why
⬜ Tech debt — an explicit list with a price tag: what it blocks, what it slows down, what a fix costs
💬 The most common mistake is to start by rewriting. Start by writing down: half of the "architecture problems" dissolve once the system is described as it actually is.
📖 Full article: architecture — write it down before rewriting.
Track 4. People
⬜ Bus factor from the Track 0 map: wherever knowledge lives in one head — pair people up or document first
⬜ Onboarding: working environment within a day, first production task within a week
⬜ Hiring: write the job post from the project's real tasks, not from a list of technologies
⬜ Explicit ownership: every service has a name next to it
💬 Order among people matters more than order in code: code with a bus factor of 1 is not an asset, it's a hostage. And the other way around — a team where knowledge flows freely can fix any code.
📖 Full article: people — bus factor, expectations and day one.
Track 5. Processes
⬜ Planning that survives a week: a short cycle, a visible backlog
⬜ A release rhythm — predictable, boring, documented
⬜ Incidents: blameless reviews with one action item each
⬜ Meetings — audit them: each one either produces decisions or dies
💬 Processes come last not because they don't matter, but because without light (Track 1) and hands on the wheel (Track 2) any process is theater.
How to tell the order has arrived
Not by pretty dashboards. By how the team feels:
- deploying is not scary,
- a new person is useful in their first week,
- an incident is a procedure, not a panic,
- the question "why is it like this here?" has a written answer.
You'll never reach perfection — and you don't need to. It's enough that every week feels a little calmer than the last one.
This is the map of the series: links in the tracks will come alive as articles are published. Want a specific track covered sooner — tell me, the queue is flexible.
Originally published at mind.mansur.expert.
Top comments (0)