Das Agentur-Übergabe-Problem: Wie man eine Codebase übergibt, ohne 3 Monate zu verlieren

Das schmutzige Geheimnis der Agentur-Entwicklung: Die meisten Projekte enden mit einer ZIP-Datei, einer Slack-Nachricht „meldet euch, wenn ihr Fragen habt" und dann Stille.

Das neue In-House-Team des Kunden öffnet die Codebase. Sie sehen 200 Dateien. Keine Dokumentation. Keine Erklärung, warum Dinge so strukturiert sind, wie sie sind. Sie verbringen die nächsten drei Monate damit, zu verstehen, was sie geerbt haben, bevor sie ein einziges Feature shippen können.

Wir waren auf beiden Seiten. Nach zu vielen schmerzhaften Erfahrungen haben wir einen Übergabeprozess entwickelt, der tatsächlich funktioniert.

Warum Übergaben scheitern

Das Problem ist nicht, dass Agenturen schlechten Code schreiben. Das Problem ist, dass Code ohne Kontext unbrauchbar ist.

Unsere Übergabe-Checkliste

Wir behandeln die Übergabe als Deliverable — nicht als Nachgedanken. Sie beginnt am ersten Tag, nicht am letzten.

1. Architecture Decision Records (ADRs)

Jede signifikante Entscheidung bekommt ein kurzes Dokument, das das Was, Warum und die betrachteten Alternativen erklärt. Diese leben im Repo.

<!-- docs/decisions/003-polling-statt-websockets.md -->

# ADR 003: Polling statt WebSockets für Echtzeit-Updates

## Status
Akzeptiert

## Kontext
Das Bestellsystem braucht nahezu Echtzeit-Updates für den Bestellstatus.
WebSockets würden echte Echtzeit bieten, aber erhebliche Komplexität hinzufügen.

## Entscheidung
HTTP Polling mit SWR (stale-while-revalidate) in 3-Sekunden-Intervallen.

## Begründung
- Bestellstatus-Änderungen sind selten (alle paar Minuten)
- 3-Sekunden-Polling bietet „gute genug" Echtzeit
- Keine zusätzliche Infrastruktur nötig
- Funktioniert zuverlässig auf instabilen Mobilverbindungen

## Konsequenzen
- Leicht höhere Serverlast (gemessen: ~2 % CPU-Anstieg)
- Maximale 3-Sekunden-Verzögerung für Status-Updates

Wir schreiben typischerweise 5–10 ADRs pro MVP. Sie brauchen 10 Minuten pro Stück. Sie sparen Wochen an Raterei.

2. Das README, das tatsächlich hilft

# Projektname

## Quick Start
1. Repo klonen
2. `.env.example` nach `.env` kopieren und Werte eintragen
3. `docker compose up` ausführen
4. http://localhost:3000 öffnen
5. Testdaten: `npm run db:seed`

## Architektur-Überblick
- **Frontend:** Next.js 15, React 19, Tailwind CSS v4
- **Backend:** Next.js API Routes + Prisma ORM
- **Datenbank:** PostgreSQL 16
- **Auth:** better-auth (session-basiert)

## Umgebungsvariablen
| Variable | Erforderlich | Beschreibung |
|---|---|---|
| DATABASE_URL | Ja | PostgreSQL Connection String |
| AUTH_SECRET | Ja | Zufälliger 32-Zeichen-String |
| STRIPE_SECRET_KEY | Ja | Stripe API Key (Test-Modus für Dev) |

## Bekannte Issues / Tech Debt
- [ ] `lib/utils.ts` muss in domänenspezifische Utilities aufgeteilt werden
- [ ] E-Mail-Templates sind hardcodiertes HTML
- [ ] Kein Rate Limiting auf öffentlichen API-Endpoints

3. Aufgezeichnete Walkthrough-Videos

Wir nehmen zwei Videos vor jeder Übergabe auf:

Video 1: Architektur-Walkthrough (30 Min) Screen-Share durch Codebase-Struktur, Datenfluss und wichtige Design-Entscheidungen.

Video 2: Deployment & Operations (15 Min) Wie man deployed, wie man rollbackt, wo man Logs findet, wie man häufige Probleme löst.

Wir nutzen Loom. Die Videos leben in einem geteilten Ordner, verlinkt vom README.

4. Docker-First lokale Entwicklung

Wenn ein neuer Entwickler das Projekt nicht innerhalb von 30 Minuten nach dem Klonen lokal zum Laufen bringen kann, ist die Übergabe gescheitert.

# docker-compose.yml — alles läuft lokal
services:
  app:
    build: .
    ports: ["3000:3000"]
    volumes: ["./:/app", "/app/node_modules"]
    env_file: .env
    depends_on: [db]

  db:
    image: postgres:16
    environment:
      POSTGRES_DB: myapp
      POSTGRES_PASSWORD: localdev
    ports: ["5432:5432"]

Ein Befehl. Alles funktioniert.

5. Test Suites als lebende Dokumentation

Tests sind nicht nur zum Bug-Fangen — sie sind Dokumentation, die nicht veralten kann:

describe("Bestellpreise", () => {
  it("wendet 10 % Mengenrabatt für Bestellungen über 50 Artikel an", async () => {
    const order = createOrder({ items: 60, pricePerItem: 10 });
    expect(order.total).toBe(540); // 600 - 10 % = 540
  });

  it("stapelt Mengenrabatt nicht mit Promo-Codes", async () => {
    const order = createOrder({
      items: 60,
      pricePerItem: 10,
      promoCode: "SAVE20",
    });
    expect(order.total).toBe(480); // Promo-Code gewinnt
  });
});

Ein neuer Entwickler liest diese Tests und versteht sofort die Business-Logik. Keine Dokumentation nötig.

6. Das Knowledge-Transfer-Meeting

Der letzte Schritt ist ein strukturiertes 2-Stunden-Meeting mit dem Team des Kunden:

1. Architektur-Überblick (30 Min) — System durchgehen, Fragen beantworten
2. Day-in-the-Life-Demo (30 Min) — gemeinsam ein einfaches Feature hinzufügen
3. Operations-Runbook (30 Min) — Deployment, Monitoring, Incident Response
4. Offene Fragen (30 Min)

Wir zeichnen dieses Meeting auf. Es wird das am meisten referenzierte Artefakt im ersten Monat nach der Übergabe.

Was das kostet

Unser Übergabeprozess fügt etwa 2–3 Tage zu einem 4-Wochen-MVP-Engagement hinzu. Das sind ungefähr 5–8 % des Projektbudgets.

Was es spart: 2–3 Monate, in denen das In-House-Team des Kunden mit der Codebase kämpft. Bei internen Entwicklerkosten ist das 5–10x die Kosten einer ordentlichen Übergabe.

Das Fazit

Unser Job ist nicht erledigt, wenn wir deployen. Er ist erledigt, wenn euer Team den Code ohne uns warten kann.

Dokumentiert während ihr baut. Nehmt die Walkthroughs auf. Containerisiert das Setup. Schreibt die Tests. Übergebt eine Codebase, mit der jemand tatsächlich arbeiten kann.

Das beste Kompliment, das wir je von einem Kunden bekommen haben: „Euer Team war weg, und wir haben es nicht einmal bemerkt."

Wir bauen MVPs, die von Tag eins für die Übergabe designt sind. Erfahre mehr über unseren MVP-Entwicklungsprozess.

Quellen

• Scope Creep als Top-Herausforderung für 59 % der MSPs — Moovila Report