How to do a code handover
The handover checklist that saves you from "just one more question" emails for the next 3 months.
What a code handover includes
A code handover transfers ownership of a codebase from one developer (or team) to another. This happens when freelancers finish projects, employees leave, or teams reorganize.
A complete handover includes:
- Access to the repository, hosting, and third-party services - Documentation of the architecture and system design - Setup instructions for the development environment - A walkthrough of key features and how they work - Known issues, technical debt, and pending work - Contact information for follow-up questions
Prepare access and credentials
Before writing any documentation, make sure the receiving party has access to everything:
- Repository (GitHub/GitLab/Bitbucket): add them as a collaborator or transfer ownership. - Hosting (Vercel, AWS, Heroku): invite them to the project or transfer the account. - Third-party services (Stripe, Supabase, SendGrid): transfer ownership or create new accounts under their control. - Domain registrar: transfer the domain or update DNS contacts. - Environment variables: share all secrets securely (use a password manager, not email).
Missing access is the number one cause of post-handover emergency calls.
Document the architecture
The receiving developer needs a mental model of the system before they read code. Provide:
- A high-level architecture diagram showing major components and how they communicate. - A list of all technologies with versions. - The database schema and key relationships between entities. - How authentication works. - Where business logic lives (which files/modules handle the core features).
This is where automated tools save hours. CodeDashboard generates architecture diagrams, tech stack reports, and component summaries from the repository. Run an analysis and include the dashboard link in your handover package.
Write setup instructions
Test your setup instructions by following them on a clean machine (or asking someone else to). Instructions that work on your laptop but fail on theirs are worse than no instructions.
Include:
- System prerequisites (Node.js version, Python version, Docker, etc.) - Clone and install commands - Environment variable template with descriptions for each variable - Database setup (migrations, seed data) - How to run the development server - How to run tests - How to deploy
CodeDashboard's "How to Run" section auto-detects setup steps from the repository. It catches package managers, scripts, and environment variable files.
Walk through key flows
Pick the 3-5 most important user flows and walk through them. For each flow, explain:
- What the user does (e.g., "creates an account") - Which files handle the request (route, controller, service, model) - What happens in the database - What third-party services are involved - Edge cases and error handling
A recorded screen share (Loom, Zoom recording) can supplement written docs here. Some things are faster to show than describe.
List known issues and technical debt
Be honest about the state of the codebase. The receiving developer will find the issues anyway. Listing them upfront saves time and builds trust.
Include:
- Known bugs (with reproduction steps if possible) - Technical debt you intended to address but did not - Workarounds and hacks (explain why they exist) - Performance issues or scalability concerns - Pending dependency updates
This list prevents the new developer from investigating known problems. It also gives them a starting point for improvement work.
Schedule follow-up availability
Even with perfect documentation, questions will come up. Agree on a follow-up period upfront.
A typical arrangement: 2-4 weeks of email availability for questions after the handover, with an option to schedule a paid follow-up call for complex issues.
Set expectations: how quickly you will respond, which channels to use (email, Slack, scheduled calls), and when the support period ends. This prevents indefinite "just one more question" requests.
Key takeaways
- 1Transfer all access and credentials before documentation.
- 2Include architecture diagrams, setup instructions, and key flow walkthroughs.
- 3Auto-generate the structural documentation with CodeDashboard to save hours.
- 4Be honest about technical debt and known issues.
- 5Agree on a follow-up availability window (2-4 weeks) upfront.
Related guides
How to understand a GitHub repo
A step-by-step process for making sense of any codebase you have never seen before.
What is codebase documentation?
The types of documentation every codebase needs, and how to create them without burning out.
How to onboard developers faster
The difference between "figure it out" and "here is everything you need" is about 3 weeks of productivity.
Try CodeDashboard free for 7 days
Paste a GitHub URL and get a full visual dashboard in under 2 minutes. No credit card required for free accounts.