---
number: 120
lang: de
title: "Zentrale Doku: Der Link-Back ist das Wichtige"
date: 2026-08-24
stability: evergreen
review_by: 2029-08-24
author: "Stefan Wendel"
coauthor: "Claude Opus 5.5"
coauthor_id: claude-opus-5-5
---
# Zentrale Doku: Der Link-Back ist das Wichtige

**Ein Runbook, auf das kein Repo zeigt, existiert praktisch nicht.**

2026-08-24 · Stefan Wendel · Claude Opus 5.5

---

<figure class="cartoon">
  <img src="/cartoons/0120-de-v1.svg" width="520" height="420" alt="Tiefer Wald: Hänsel und Gretel stehen verloren zwischen den Bäumen. Daneben liegt ein ordentlicher Haufen Brotkrumen mit einem kleinen Schild." />
  <figcaption>„Keine Sorge. Ich hab die Krümel alle an einem zentralen Ort abgelegt.“</figcaption>
</figure>

Kurz zum Setup: Wir arbeiten mit fünf Arbeits-Repos, in denen der Code liegt, und einem Doku-Repo mit Spezifikationen, Prototypen und Runbooks.

Im Doku-Repo lagen neun gute Runbooks: Prod-Promotion, Rollback, Credential-Rotation, Incident-Response. Verweise darauf aus den fünf Arbeits-Repos: **null**.

Aufgefallen ist es, als ein Agent eine Version nach Produktion bringen sollte. Er hat es richtig gemacht, aber die ganze Prozedur aus den GitHub-Workflows *rekonstruiert*. Das Runbook, das genau das beschreibt, hat er nie gesehen.

Das ist der Punkt aus [#0101 Shift Into](/101), und er ist so wichtig, dass er hier noch einmal steht: **Doku wird Teil des Codes.** Doku, auf die der Code nicht zeigt, gibt es für einen Agenten nicht.

Der Agent hatte nicht das falsche Werkzeug. Ihm fehlte der Zeiger. Die `CLAUDE.md` eines Repos ist das einzige Dokument, das ein Agent garantiert liest, bevor er handelt. Zwei Zeilen dort reichen: „Betriebsprozeduren stehen in `<doku-repo>/runbooks/`. Vor einem Prod-Eingriff dort nachsehen.“

Was sonst noch hilft:

- **Im Katalog die Spalte „wann greife ich danach“**, formuliert als Symptom. Um zwei Uhr nachts kennst Du Dein Problem, nicht den Namen der Lösung.
- **„Zuletzt verifiziert“ an jedem Runbook.** Wer es benutzt, stempelt es.
- **Der Alarm verlinkt das Runbook**, das ihn behebt.

Messen kostet eine Minute: `grep` nach dem Doku-Verzeichnis in allen `CLAUDE.md`. Steht da null, ist Deine Doku unsichtbar.

## Alternativ: Ein Agent-Skill für das Runbook

Für genau solche Abläufe gibt es eine zweite Antwort: Das Runbook wird ein Skill. Ein Skill beschreibt dem Agenten Schritt für Schritt, wie er eine wiederkehrende Aufgabe erledigt, und der Agent lädt ihn selbst, sobald die Aufgabe dazu passt. Aus „Prod-Promotion nachlesen“ wird „Prod-Promotion ausführen“.

Der Haken ist derselbe: Der Skill muss dort liegen, wo der Agent ihn findet, im Repo oder in seiner Umgebung. Wie sich Skill, MCP und API voneinander abgrenzen, steht in [#0107 MCP, API oder Skill?](/107).

**Die Lesson:** Wer Doku zentral ablegt, setzt im selben Commit den Link zurück in jedes Repo.

## Changelog

**2026-10-13** — Setup der Repos, Verweis auf #0101 und Abschnitt zum Skill ergänzt. ([#25](https://github.com/wecloudsio/weclouds-blog/pull/25))

**2026-10-12** — Cartoon ergänzt. ([#20](https://github.com/wecloudsio/weclouds-blog/pull/20))