How to Take Over a Magento Project Without Breaking It
You're inheriting someone else's decisions. That doesn't make them your fault — yet.
Taking over as tech lead on a Magento project is never a blank slate. There's a codebase built without you, a team with established habits, a product roadmap that predates your arrival, and a business expecting you to hit the ground running while also understanding the context. These instructions contradict each other.
I've been the incoming tech lead on projects ranging from €2M B2C stores to €100M+ enterprise platforms — and I've also been the person handing over to the next lead. Both perspectives inform what follows. The teams that set up new tech leads for failure do so by expecting both simultaneously. The teams that succeed give the new lead a structured first 90 days: observe first, diagnose second, change third. In that order, without shortcuts.
Every Magento project has three layers of reality. The first is what the documentation says (if it exists). The second is what the previous tech lead believed was true. The third is what's actually running in production.
These three rarely align perfectly. The documentation describes version 1 of a module that's now on version 4. The previous lead believed the ERP integration was clean, but it has two undocumented workarounds added six months ago by a developer who has since left. What's running in production has configuration that doesn't match staging.
Your job in the first two weeks is not to fix any of this. It's to map it accurately. The urge to start fixing immediately is a trap — every change you make in the first two weeks is a change you don't fully understand, in a system you haven't mapped, with implications you haven't assessed.
The audit has five areas. Work through each systematically before drawing conclusions.
Codebase audit: Run PHPStan or a similar static analysis tool against the codebase. Not to act on the results immediately, but to understand the baseline quality. Look at the custom module list — how many are there, how complex are they, which ones haven't been touched in a year? Git log patterns are informative: which files change most frequently? High-churn files in core areas are a signal.
Integration audit: Map every external system the Magento instance talks to. ERP, PIM, OMS, shipping, payment, marketing automation. For each: what's the integration pattern (sync/async, observer/queue/API), who owns it on both sides, what's the failure mode, and when was it last reviewed?
Infrastructure audit: Where is the code running? Who can deploy? What's the CI/CD pipeline? What environments exist and how closely do they mirror production? When was the last performance test run?
Team audit: Talk to each developer individually. What do they work on? What are the parts of the system they avoid? What do they think is the biggest technical risk? What would they change if they could? This is the most valuable data source you have.
Business audit: What is the roadmap for the next six months? Which features are committed? What's the Magento version upgrade plan? What is the actual business asking for and what is the team currently delivering?
After the audit, you should have a clear map of the system's risks. Month 1 is about establishing the processes that make those risks visible and manageable — not about fixing them yet.
Code review ownership. If there isn't a code review process, establish one. If there is one, join every review for the first month. You're not slowing the team down — you're learning the system and establishing your technical presence. The team should know that you understand what they're building before you start making decisions about how it's built.
Deployment observability. Get access to production monitoring. If there isn't one, set up New Relic, Blackfire, or a basic Magento log aggregation. You need to see what production actually looks like when it's under load. Staging is not a reliable proxy.
Write the first ADR. Pick the most significant architecture decision that wasn't documented and write an Architecture Decision Record for it. This establishes the habit and signals to the team that you value documented reasoning, not just working code.
Don't reorganize the team yet. You don't know enough. Even if the structure looks wrong, wait until you have three months of context before proposing changes to who does what.
By month 2 you have enough context to make changes with confidence. The question is which changes to prioritize.
Prioritize changes that reduce risk over changes that improve quality. A critical integration that has no error handling is a higher priority than a module that's architecturally messy but functionally stable. Fix what fails; refactor what's ugly.
Introduce one process change at a time. If you establish code review standards, a performance gate, and a documentation requirement simultaneously, the team experiences the overhead without understanding the value of each. Sequence them.
The change to make early: establish a clear distinction between "technical debt we're carrying intentionally" and "technical debt we accumulated by accident." The intentional kind has a documented reason and a plan. The accidental kind is a risk. Making this distinction visible is one of the most valuable things a new tech lead can do.
The conversation to have in month 2: Sit with the business stakeholder and map what they need against what the technical state of the system can actually deliver. Most year-2 problems come from the business expecting a system that can move faster than the codebase actually allows. Making this gap explicit — professionally, with evidence — is a tech lead responsibility, not a developer responsibility.
By day 90 you should have: a documented map of the system's major risk areas, at least one significant technical risk mitigated, a code review process that the team is following, and a credible picture of what the system needs over the next six months.
You should also know who on the team is the strongest technical contributor, who needs development support, and who is at risk of leaving. People problems on engineering teams are often technical lead problems in disguise — the team's morale is related to the technical quality of what they're being asked to build.
What you should not have done by day 90: a large-scale refactor, a rewrite of anything significant, or a major process overhaul across multiple areas simultaneously. These changes require more than 90 days of context to execute well.
These guides come from 22+ years and 50+ Magento projects. If your team is facing one of these challenges, I can help — through a focused platform audit, technical leadership engagement, or hands-on development.
Start a Conversation All Guides