How to plan for the senior architect leaving from day one

The brief that changes how you build

I was brought in as Solutions Architect on a fixed three-and-a-half month engagement. The team was around nine developers, predominantly junior, including several bootcamp graduates. After I left, the in-house team would own the platform.

That single fact changes everything about how you work.

If your remit were open-ended, you could build the architecture in front of the team, lead from the front, and trust that you would still be there to course-correct when drift set in. On a fixed engagement with a junior-heavy team, that approach has a predictable failure mode. The senior builds something coherent. The senior leaves. The team drifts off it within a quarter, because nobody internalised the reasoning behind the shape of the thing.

So the job is different. The job is to leave behind a team that can reason about the architecture without you. The architecture itself is secondary. The team's ability to extend it correctly is the deliverable.

I want to write down what I actually did, what worked, and what I would change if I were starting again on Monday morning.

The planning frame: the "after I am gone" filter

From day one, every meaningful decision passed through a single question. Will this still be true in three months, and will the team know why?

That filter does a lot of work. It rules out clever solutions that depend on the architect being around to defend them. It rules out implicit conventions that live only in the senior's head. It pushes you towards patterns that survive contact with people who were not in the room when the decision was made.

It also reframes what a "good" decision looks like. A good decision on an open-ended engagement might be the one with the best technical trade-offs. A good decision on a fixed engagement with a junior-heavy team is the one with the best technical trade-offs that the team can also reproduce, defend, and extend after the senior has gone.

Sometimes those are the same decision. Often they are not. When they diverge, the second one wins.

Mechanism 1: copyable patterns over clever ones

Juniors copy what they see. This is not a criticism. It is how people learn a new codebase. They find a piece of code that looks similar to the thing they have been asked to build, and they pattern-match.

If the patterns in the codebase are clever, the copies will be wrong. The copy will hit a case the original did not anticipate, or will miss a subtle invariant the original quietly relied on, and the result will be a near-miss that compiles and ships and slowly accumulates bugs.

If the patterns are simple, repetitive, and consistent, the copies will be right. The new feature will look like the existing features because the existing features all look like each other. The cost is some verbosity. The benefit is that the team can extend the system without holding the entire mental model of the architect in their heads.

Concretely, that meant I picked the boring choice more often than I would have on a different team. Repeated structure across handlers rather than a clever base class that abstracted three lines of duplication. An explicit mapping step rather than convention-based magic. The code looks more verbose. It is also legible to someone who joined six weeks ago.

Mechanism 2: decisions made in front of the team, trade-offs verbalised

Architectural decisions are an opportunity to teach what an architectural decision looks like. The mistake is to walk into the team meeting with the conclusion already formed and present it.

What the team needs is the worked example. The alternatives you considered. The ones you rejected, and specifically why. The constraints that ruled out the obvious answer. The reason you accepted the trade-off you did rather than a different one.

A junior who has only ever seen finished positions does not learn to argue. They learn to defer. A junior who has watched five worked examples of "I considered A, B and C, I went with B, here is what I gave up to do that" learns the shape of the argument. Six months later, they can run that argument themselves.

The cost is that decisions take longer to communicate. The benefit is that the team starts making smaller decisions in the same shape without being asked to.

Mechanism 3: a written patterns document

Code review transfers intent to the people on a given pull request. It does not transfer intent to anyone else. A patterns document does.

I wrote one. I wish I had written it earlier in the engagement. By the time I sat down to write it, I had already explained the same patterns six or seven times in code review, in standups, in ad hoc Slack threads. The document codified what I had been saying. It was useful. It would have been more useful in week two than in week eight.

A patterns document does not need to be long. It needs to be specific. "Here is how we structure a command handler. Here is why. Here is what to do when you hit case X, which we have hit twice already." Examples beat principles. A junior can copy an example. A junior cannot copy a principle without a worked example showing what the principle means in practice.

If I were starting again, the patterns document would exist as a stub on day three, with the first two patterns written out in full, and would grow each week as new patterns earned their place.

Mechanism 4: code review as the day-to-day teaching channel

Code review is where most of the actual transfer happens. It is high-frequency, specific, written, and tied to real code the reviewer has just produced. It is the most efficient teaching channel you have.

The temptation, on a fixed engagement with deadlines, is to do code review fast. Approve, request the obvious changes, move on. That mode ships features. It does not build a team.

Slow, written, question-driven code review is the opposite. Ask why a thing was done a particular way before saying it should be done differently. Often the developer has a reason you had not considered, and you learn something. Often they do not, and the question itself prompts them to work out the answer, which sticks far better than being told.

Be specific. "This works, but it diverges from the pattern in handler X. Either bring it in line, or tell me why this case warrants a new pattern, in which case let us write it down." Either outcome is good. The team either reinforces the existing pattern or consciously creates a new one with the reasoning attached.

Mechanism 5: handover documentation as a deliverable

The default treatment of handover documentation is as a polish step at the end of the engagement. A week-thirteen task. A README expansion done in the last fortnight when the build is winding down.

That is the wrong frame. By week thirteen the senior is tired, the build is being shipped, and the documentation gets the energy that is left over, which is not much. More importantly, week-thirteen documentation reflects a week-thirteen view of the system. It glosses over the decisions that felt obvious by then but were live debates in week three.

Treat handover documentation as a week-one deliverable. Architecture decisions, written down as they are made, with the reasoning attached and the sensitivities flagged. "We chose X. We chose it because of A and B. If A stops being true, revisit this." That last sentence is the load-bearing one. The team after you needs to know which decisions are robust to changing conditions and which are not.

I did this in part on the engagement. I would do it more deliberately next time, with a standing slot each week to write up the architectural decisions made that week before they faded into background assumption.

A concrete payoff

The engagement ran into mid-flight disruption. A senior teammate from the partner organisation left. A junior went off sick for an extended period. There was a late infrastructure pivot.

In a different shape of engagement, any one of those would have been disruptive enough to require a stop-and-replan. In this one, the consolidation work was straightforward. Orphaned pull requests were reconciled against patterns the team already understood. Work picked up by other developers slotted into a structure they recognised, because the structure was the same everywhere. The infrastructure pivot reshaped some of the wiring, but the application-level patterns survived it intact.

That continuity through disruption was not luck. It was a function of the patterns being copyable and consistent enough that any developer on the team could pick up any other developer's work without a long ramp.

The longer-term payoff arrived after I left. The in-house team continued to extend the architecture against the same patterns. No rewrite of what had been shipped. The patterns survived my departure, which was the actual brief.

What I would do differently

Three things, in order of impact.

Start the patterns document in week one as a living stub, and grow it weekly. The cost in week one is small. The cost of not having it in week eight is large.

Start coaching the team on AI-assisted development from week one rather than treating it as a separate workstream. The juniors were going to use AI tooling regardless. Better to set the conventions for how it gets used inside the patterns the codebase already enforces.

Treat the handover document as a week-one deliverable that grows in place, not a week-thirteen polish step. By week thirteen you do not have the energy or the perspective to write it well. The version that grows alongside the build is better, because it captures the reasoning at the moment the reasoning was live.

Closing

The load-bearing thing a senior leaves behind on a fixed engagement is not the architecture. It is the team's ability to reason about the architecture after the senior has gone.

Plan for that from day one, or the work walks out of the door with you.

If you are scoping a fixed engagement on a junior-heavy team and want to talk through how to set it up so the patterns survive the handover, I am happy to have a conversation.