Claude-Code-Session-Handoff-Vorlage: Kontext für die nächste Person oder den nächsten Agenten sichern

Claude Code ist besonders nützlich, wenn eine Session sauber übergeben werden kann. Der typische Verlust entsteht nicht, weil Claude Code die Dateien nicht findet. Es findet sie, grenzt den Fehler ein, verwirft falsche Annahmen und schreibt vielleicht schon einen Teil der Lösung. Dann endet die Session mit “morgen weiter”, und die nächste Person rekonstruiert denselben Kontext.

In diesem Artikel bedeutet Handoff eine kurze Arbeitsübergabe für die nächste Person oder die nächste AI-Agent-Session. Es ist kein Tagebuch. Es ist ein operativer Hinweis mit Ziel, aktuellem Stand, relevanten Dateien, Prüfbelegen, offenen Risiken und dem nächsten Prompt für Claude Code.

Als offizielle Grundlage solltest du die aktuellen Claude-Code-Dokumente nutzen. How Claude Code works erklärt Agent-Loop, Projektzugriff, Git-Status, Sessions und Kontext. Memory erklärt CLAUDE.md und Projektanweisungen. CLI reference deckt die Kommandozeile ab. Intern passen CLAUDE.md best practices, verification receipt workflow und team handoff rules dazu.

Das richtige Modell

Einsteiger vermischen oft CLAUDE.md und Handoff-Notizen. CLAUDE.md ist für dauerhafte Projektregeln: Build-Befehle, Code-Standards, Architekturregeln, Review-Kriterien und empfindliche Pfade.

Eine Handoff-Notiz ist der temporäre Aufgabenstand. Sie beschreibt, was heute passiert ist: welche Hypothese falsch war, welche Dateien wichtig sind, was geprüft wurde, was noch ungeprüft ist und womit die nächste Session anfangen soll. Einfach gesagt: Kontext ist der Arbeitszusammenhang, ein verification receipt ist der Prüfbeleg, und ein harness ist der Arbeitsrahmen, der den Agenten in sinnvollen Grenzen hält.

flowchart LR
  A["Goal<br/>Welches Ergebnis zählt"] --> B["Current state<br/>Wo endete die Arbeit"]
  B --> C["Evidence<br/>Was wurde geprüft"]
  C --> D["Risk<br/>Was bleibt unsicher"]
  D --> E["Next prompt<br/>Was kommt zuerst"]

Diese Kette verhindert kalte Neustarts. Die nächste Person soll nicht den ganzen Chat lesen müssen, bevor sie einen sinnvollen Befehl ausführt.

Markdown-Vorlage zum Kopieren

# Claude Code session handoff

## Goal
- target outcome:
- explicitly out of scope:

## Current state
- branch:
- dirty files:
- related URL:
- what is known:

## What changed
- changed files:
- reason for change:
- important files not touched:

## Verification receipt
- commands run:
- result:
- manual checks:
- not checked:

## Risks and constraints
- fragile area:
- do not touch:
- requires approval:

## Next prompt
In the next session, compare git status with this handoff, then continue from the unchecked verification items.

Der wichtigste Eintrag ist not checked. Ein erfolgreicher lokaler Build beweist nicht, dass öffentliche URL, mobile Ansicht, CTA-Link, Analytics-Event oder Übersetzung korrekt sind. Offene Prüfungen ausdrücklich zu nennen, ist sicherer als ein unklarer Abschluss.

Strukturierte JSON-Zusammenfassung

Wenn dein Team Handoffs in GitHub Issues, Slack, Notion oder einem internen Dashboard sammelt, ist eine kleine JSON-Zusammenfassung neben Markdown praktisch.

{
  "slug": "claude-code-session-handoff-template",
  "goal": "Improve the published multilingual article group",
  "status": "draft updated, verification pending",
  "files": [
    "site/src/content/blog/claude-code-session-handoff-template.mdx",
    "site/src/content/blog-en/claude-code-session-handoff-template.mdx"
  ],
  "checksRun": ["frontmatter parse", "code fence scan"],
  "checksMissing": ["production URL check"],
  "nextAction": "Run targeted validation and review locale copy"
}

JSON ist gut für Tools, aber schlecht für Begründungen. Schreibe Entscheidungen und Hintergründe in Markdown. Lege maschinenlesbaren Status in JSON ab.

Ausführbares Node.js-Skript

Speichere den folgenden Code als scripts/write-handoff.mjs. Er verwendet nur eingebaute Node.js-Module, liest den Git-Status und schreibt eine datierte Markdown-Datei nach handoffs/.

import { execSync } from "node:child_process";
import { mkdirSync, writeFileSync } from "node:fs";
import { join } from "node:path";

function run(command) {
  try {
    return execSync(command, { encoding: "utf8" }).trim() || "(no output)";
  } catch (error) {
    return `ERROR: ${error.message}`;
  }
}

const date = new Date().toISOString().slice(0, 10);
const branch = run("git branch --show-current");
const status = run("git status --short");
const recentCommit = run("git log -1 --oneline");
const outDir = "handoffs";
const outFile = join(outDir, `${date}-session-handoff.md`);

mkdirSync(outDir, { recursive: true });

const body = `# Claude Code session handoff

## Goal
-

## Current state
- branch: ${branch}
- recent commit: ${recentCommit}
- dirty files:
\`\`\`text
${status}
\`\`\`

## What changed
-

## Verification receipt
- commands:
- result:
- missing:

## Risks and constraints
-

## Next prompt
Read this handoff, compare it with git status, and continue from the missing verification items.
`;

writeFileSync(outFile, body, "utf8");
console.log(`Wrote ${outFile}`);

Prüfe zuerst die Syntax, dann führe es aus:

node --check scripts/write-handoff.mjs
node scripts/write-handoff.mjs

Praktische Einsatzfälle

Erster Einsatzfall: mehrsprachige Content-Veröffentlichung. Wenn ein Slug Dateien für Japanisch, Englisch, Chinesisch, Koreanisch, Spanisch, Französisch, Deutsch, Portugiesisch, Hindi und Indonesisch hat, ist die Schwierigkeit nicht eine einzelne Datei. Schwierig ist zu wissen, welche Locale noch Textprüfung, Mojibake-Scan, Description-Länge, interne Links und CTAs zu /products/ oder /training/ braucht.

## Goal
- raise the 10-locale article group for slug claude-code-session-handoff-template to publish quality

## Current state
- Japanese canonical body updated
- English and Indonesian reviewed for natural tone
- zh, ko, and hi still need mojibake scan

## Verification receipt
- frontmatter parse: pass
- JSON code block parse: pass
- production URL: not checked

## Next prompt
Check the remaining locale files for mojibake, description length, and missing CTA links. Report only unresolved items.

Zweiter Einsatzfall: eine unterbrochene Fehlersuche. Wenn die echte Erkenntnis lautet “bei 390px läuft der CTA über, weil die Preiskarte eine feste min-width behält”, dann schreibe genau das. “CSS geprüft” zwingt die nächste Person zur Wiederholung.

Dritter Einsatzfall: riskantes Code-Review. Authentifizierung, Billing, Datenbankmigrationen und Berechtigungen brauchen eine Notiz dazu, welche Risiken geprüft wurden, welche Tests fehlen und wer vor dem Merge zustimmen muss.

Vierter Einsatzfall: parallele Arbeit mehrerer Personen oder Agenten. Wenn andere Worker andere Slugs oder Branches bearbeiten, muss der Handoff die erlaubten Dateien und die tabuisierten Dateien nennen.

Häufige Fehler

Fehler eins: Dateipfade ohne Begründung. site/src/pages/products.astro ist weniger hilfreich als “die min-width der Preiskarte erzeugt bei 390px Overflow”.

Fehler zwei: nur erfolgreiche Checks melden. npm run build kann bestehen, obwohl öffentliche URL, mobile Ansicht, Klicktracking, Formularfluss oder Übersetzung noch fehlerhaft sind.

Fehler drei: lange Gesprächszusammenfassungen schreiben. Wenn der nächste Schritt fehlt, ist die Notiz nur zusätzliche Lesezeit.

Fehler vier: private Daten einfügen. API Keys, Kundendaten, interne Preise und private Incident-Links gehören nicht in wiederverwendbare Handoffs.

CTA und Monetarisierung

Bei einem Content-Projekt wie ClaudeCodeLab gehört die Monetarisierungsstrecke zur Qualitätsprüfung. Wenn interne Links, kostenlose Ressourcen, Produktseiten oder Beratung fehlen, verliert der Leser den nächsten Schritt. Einzelne Leser starten mit der kostenlosen Checkliste. Wer Vorlagen und Checklisten braucht, nutzt products. Teams, die CLAUDE.md, Berechtigungen, Review Gates, verification receipts und Handoff-Rituale in einem echten Repository einführen wollen, sollten Claude Code training and consultation nutzen.

Der Ablauf kostet 30 Sekunden: Ziel, Stand, Belege, offene Prüfungen und nächster Prompt. In Masas Veröffentlichungsworkflow war der größte Gewinn, am nächsten Tag nicht mehr suchen zu müssen, wo die vorherige Session aufgehört hatte.