The Founder's Guide to Agency Handoffs

EUR 42,000. That's what one client spent to rebuild a project that an agency delivered with a Slack message saying "code's in the repo, let us know if you have questions."

They had questions. The agency was already on the next project. The in-house developer they hired spent 6 weeks trying to understand the codebase before giving up. The rewrite cost more than the original build.

We've seen this pattern four times in the last year. The handoff isn't a formality. It's the difference between a product that lives and a product that dies the moment the agency walks away.

Key Takeaways > - A proper handoff takes 1-2 weeks of dedicated work. If your agency isn't budgeting for it, the handoff will be bad. > - Our handoff template includes 7 documents. We'll share the exact structure below. > - The biggest handoff failure isn't missing docs. It's undocumented decisions.

Why Handoffs Fail

The handoff fails before the project ends. It fails when the agency treats documentation as a last-minute chore instead of a deliverable.

Here's the timeline of a bad handoff:

1. Agency builds the product over 4-6 months 2. In the final week, a junior developer writes a README 3. The README says "run npm install, then npm run dev" 4. The client gets a repo link and a Zoom call 5. 3 months later, the client's new developer can't deploy to production because the deployment process was never documented

And here's what's really lost: not the how, but the why. Why did the agency choose PostgreSQL over MongoDB? Why is the auth flow structured this way? Why does the payment webhook handler have a 30-second timeout? These decisions are invisible in code. They live in Slack threads that the client doesn't have access to.

What a Good Handoff Actually Includes

We deliver 7 documents with every project. Not because we love writing docs. Because we've been the developers inheriting codebases, and we know what we needed but didn't have.

1. Architecture Overview

A single document that explains how the system works at a high level. Not code-level detail. System-level: what services exist, how they communicate, what databases they use, where they're deployed.

This document should be readable by a product manager, not just a developer. If a non-technical founder can't understand the architecture overview, it's too detailed.

What we include: - System diagram (boxes and arrows, not UML) - List of services and their responsibilities - Data flow for the 3-5 most important user actions - Third-party services and why they were chosen

2. Environment and Deployment Guide

This is the document that saves the most money. A developer who can't deploy the app is a developer burning the client's money.

What we include: - Every environment variable, what it does, and where to get the value - Step-by-step deployment process for staging and production - CI/CD pipeline explanation - Domain and DNS configuration - SSL certificate management - Monitoring and alerting setup

We test this document by having someone who didn't build the project follow it. If they can deploy to production using only the document, it's done. If they have to ask a question, we update the document.

3. Database Schema and Data Model

ERD diagrams and table descriptions. Every table, every relationship, every index.

What we include: - Entity relationship diagram - Table-by-table descriptions (what it stores, why it exists) - Important queries and their performance characteristics - Migration history and how to run migrations - Backup and restore procedures

4. API Documentation

Every endpoint, every request format, every response format. We generate this automatically from the code but manually review it for accuracy.

What we include: - Complete endpoint list with methods, paths, and descriptions - Request and response examples for every endpoint - Authentication and authorization rules - Rate limiting details - Error codes and their meanings

5. Decision Log

This is the document no one writes and everyone needs. A chronological list of every significant technical decision and why it was made.

What we include: - Decision: What we decided - Context: What was the situation when we decided - Alternatives: What other options we considered - Rationale: Why we chose this option - Consequences: What this decision makes easier and harder

Example entry: "We chose Resend over SendGrid for transactional email because Resend's API is simpler and our volume doesn't justify SendGrid's advanced features. If email volume exceeds 50k/month, reconsider SendGrid for its analytics."

This document is worth more than all the other documents combined. A developer who understands why decisions were made can extend the system. A developer who only knows what was built will break it.

6. Third-Party Service Inventory

Every external service the product depends on: who owns the account, what plan it's on, when it renews, what happens if it goes down.

What we include: - Service name, purpose, and URL - Account owner and login method - Current plan and monthly cost - API keys (location, not values) - What breaks if this service goes down - Alternatives if migration is needed

7. Runbook

Operational procedures for common scenarios. What to do when things break.

What we include: - How to restart each service - How to roll back a deployment - How to investigate common errors - How to scale up if traffic spikes - Who to contact for each third-party service

The Contrarian Take: The Best Handoff Documentation Is Written During Development, Not After

Most agencies write docs at the end. We write them during development. Not because we're disciplined. Because docs written after the fact are wrong.

After 6 months of development, no one remembers why they made the decision in week 3. They reconstruct a rationale that sounds reasonable but isn't what actually happened. The decision log becomes fiction.

We update the decision log in real-time. Every significant decision gets an entry within 24 hours. The architecture overview is a living document updated each sprint. The deployment guide is written the first time we deploy, not the last.

This adds maybe 10% to the development effort. It saves the client 200% in transition costs.

How to Evaluate Your Agency's Handoff Before the Project Starts

Don't wait until the project is done to discover the handoff is bad. Ask these questions during the sales process.

"Can I see a sample handoff from a past project?" If they can't show you one, they don't have a standard process. You'll get whatever the developer feels like writing on the last day.

"Is the handoff included in the project scope and timeline?" If the answer is "we include documentation," push harder. How many days are allocated? What documents are included? If they can't answer specifically, documentation isn't part of their process.

"Who writes the documentation?" If it's the same developers who write the code, good. If it's a technical writer who wasn't involved in development, the docs will be accurate but shallow. They'll describe what the code does but not why.

"How do you handle the knowledge transfer meeting?" A handoff isn't just documents. It's a structured walkthrough with the person who will maintain the code. We do a 2-day transfer session: day one is architecture and deployment, day two is codebase walkthrough and Q&A.

What Founders Get Wrong About Handoffs

"We'll figure it out from the code." No, you won't. Code tells you what the system does. It doesn't tell you why it does it that way, what alternatives were considered, or what assumptions are baked in. Self-documenting code is a myth for any system beyond trivial complexity.

"We'll hire the agency for maintenance." Maybe. But what happens when the agency raises their rates? Or gets acquired? Or loses the developers who built your product? Dependency on the original agency is a business risk. A good handoff eliminates that dependency.

"Documentation goes stale anyway." True. But stale documentation is still better than no documentation. A deployment guide from 6 months ago is 80% accurate. No deployment guide is 0% useful. The decision log never goes stale because decisions don't change retroactively.

Our Handoff Process: Step by Step

Here's exactly what happens in the last 2 weeks of every RalphNex project.

Week 1: Documentation finalization - Complete all 7 documents - Internal review by the developer who didn't write the document - Client review of architecture overview and decision log

Week 2: Knowledge transfer - Day 1: Architecture walkthrough (2-3 hours) - Day 2: Codebase walkthrough (2-3 hours) - Day 3: Deployment and operations walkthrough (1-2 hours) - Day 4-5: Client's developer works independently while our team is available for questions

Post-handoff: 30 days of support Every project includes 30 days of support after handoff. The client's team can ask questions, report issues, and request clarification on any documentation. This is included in the project price.

After 30 days, we're done. The client owns everything: code, documentation, accounts, and knowledge. They don't need us anymore. That's the goal.

Frequently Asked Questions

How long should an agency handoff take?

Plan for 1-2 weeks of dedicated handoff work. The documentation finalization takes 3-5 days. The knowledge transfer sessions take 2-3 days. Then allow 1-2 weeks of overlap where the new team works independently but can ask questions. Anything less than a week is a red flag.

What if our agency already delivered without proper documentation?

Hire a senior developer to spend 2-4 weeks reverse-engineering the codebase and writing the documentation that should have been delivered. It costs EUR 5k-15k, but it's cheaper than discovering gaps during an emergency. We've done this for 4 inherited codebases, and every client wished they'd demanded proper docs from the start.

Should we require code ownership from day one?

Yes. The code should live in your repository from the first commit. Not the agency's repo. Not a shared account. Your GitHub organization, your access controls, your ownership. If the agency pushes back on this, that's a warning sign about their handoff intentions.

What format should documentation be in?

Markdown files in the repository, alongside the code. Not Notion, not Google Docs, not Confluence. When the docs live with the code, they're versioned with the code. A developer cloning the repo gets everything they need. External documentation platforms create a dependency on yet another service.

*Planning a project and want to see our handoff template? Book a 30-minute call and we'll walk you through exactly what you'll receive. Or see our services to understand what's included in every engagement.*