Designing a Safe Handoff Between Two Development Teams

A product with a heavy dependency on a CMS for content and platform structure — onboarding flows, forms, workflows — built in a monorepo by a small internal team, with parts of the backend owned by an external team inside the client's own tech ecosystem. Around 2024, the client started building its own IT and development department and wanted to progressively take over maintenance of the product.

Documenting the system and handing it off was not enough. A new team with little context on the product needed to start contributing directly to the repository while our team kept shipping features at the same pace. Both teams needed to work in parallel without turning every change into a coordination problem.

I worked with the engineering director on a risk-classification system using a traffic-light model, over the same board and the same repository. Green issues were small, low-risk changes: the new team implemented and merged them without a formal review from our side. Yellow issues needed more context or carried more impact: the new team implemented them, but one of our developers reviewed, and the PR had to include a short explanation of the change and its expected impact. Red issues could compromise the platform's integrity or needed deep architectural knowledge: those went straight to our team. The point was not to keep the new team away from the code. It was to let them touch it safely.

We created a maintenance branch that lived alongside the main development flow. Maintenance changes followed their own integration and validation pipeline while feature work continued on its own path, with automatic branch syncs to cut down on manual coordination. This mattered because the product depended heavily on structured data and configuration managed from the CMS: adding or removing a field, changing a form, editing a workflow, or updating a content model could have consequences that went well beyond the change itself. With multiple teams touching the same product, we needed to minimize the moments where someone had to ask what changed, where, and what else it could break.

I built development infrastructure around Docker and GitLab CI/CD: every time a branch was created, the pipeline spun up an isolated environment with a frontend instance, a backend instance, and a database seeded from a copy of the dev environment. Instead of asking QA to reproduce a scenario locally, we handed them a preview environment directly: a developer worked on a branch, deployed it to their own environment, and QA validated the full flow against representative data without touching the shared environment. Once the work was no longer needed, the environment was discarded without affecting the rest of the team. Conceptually, it is the same approach later popularized by preview deployments on platforms like Vercel, applied to an architecture spanning frontend, backend, and database.

The handoff became a progressive transition instead of an abrupt jump: the new team started contributing directly to the monorepo and taking on maintenance, while our team kept shipping features and only stepped in on the highest-risk architectural changes. We did not solve this with more meetings or by routing every change through our team. Change classification, progressive ownership, branch syncing, automated CI/CD, and isolated preview environments let two teams contribute to the same product without constantly getting in each other's way while ownership was changing hands.