Das Umbrella - Artifacture

Wenn du mit einem Assistenten arbeitest, verbringst du einen erheblichen Teil der Zeit damit, ihm zu erklären, wie dieses Projekt funktioniert. Welche Datenbank. Warum damals gegen das andere Verfahren entschieden wurde. Wo etwas hingehört. Beim nächsten Mal erklärst du es wieder.

Das Umbrella ist der Ort, an dem diese Erklärungen stehen, statt jedes Mal neu zu entstehen.

Was darin liegt

Es ist ein eigenes Git-Repository — nicht dein Code-Repository, sondern eine Klammer darum:

mein-projekt/
  CLAUDE.md      Projektanweisungen: was gilt hier, was ist zu lesen
  ADR/           Architekturentscheidungen, einzeln und begründet
  Docs/          Kontext, Entscheidungshistorie, alles Erklärende
  src/           deine Repositories, jedes mit eigener Git-Historie

src/ ist der entscheidende Teil: Dort liegt dein eigentlicher Code, und er bleibt dort, wo er hingehört. Jedes Repository behält seine eigene Historie, seine eigenen Branches, seine eigene Berechtigung. Das Umbrella verfolgt sie nicht mit — es steht daneben und beschreibt sie.

Warum getrennt vom Code

Zwei Gründe, und beide sind praktisch.

Der Kontext wird nicht verwässert. Ein Assistent, der eine Aufgabe bearbeitet, liest Code. Läge die gesamte Projektdokumentation zwischen diesem Code, läse er sie mit — bei jeder Aufgabe, vollständig, unabhängig davon, ob sie zur Sache gehört. Getrennt aufbewahrt lässt sich gezielt zuführen, was gerade gebraucht wird.

Die Dokumentation wird erzwungen. Sie liegt nicht als guter Vorsatz in einem Wiki, das niemand pflegt, sondern an dem Ort, an dem gearbeitet wird. Was nicht im Umbrella steht, existiert für die Arbeit nicht — das ist unbequem und genau deshalb wirksam.

Was Architekturentscheidungen darin tun

Eine Architekturentscheidung hält fest, wie in diesem Projekt etwas gelöst wird und warum. Nicht als Empfehlung, sondern als Vorgabe.

Der Nutzen liegt nicht in der Dokumentation. Er liegt darin, dass sie den Lösungsraum verkleinert.

Ein Sprachmodell kann in aller Regel programmieren. Was es schwer macht, ist die Zahl der Wege, die von einer Anforderung zu einer Umsetzung führen — und wie viele davon in diesem konkreten Projekt falsch sind, obwohl sie für sich genommen richtig wären. Festgeschriebene Entscheidungen schneiden diese Wege ab, bevor jemand sie einschlägt. Das Modell füllt aus; es entscheidet nicht mehr, wie gebaut wird.

Deshalb sind die Entscheidungen bindend und nicht beratend. Eine Vorgabe, die umgangen werden darf, schränkt nichts ein.

Warum eine Übernahme dann Minuten dauert

Der übliche Weg, ein fremdes Projekt zu übernehmen: Code lesen, bis man versteht, warum er so aussieht. Das dauert Wochen und geht oft schief, weil die Begründung nirgends steht — sie war im Kopf von jemandem, der nicht mehr da ist.

Mit einem Umbrella liest man die Entscheidungen, die Projektanweisungen und die Vorgeschichte der Items. Der Code ist dann das Erwartbare, nicht das Rätsel.

Das gilt für einen neuen Kollegen genauso wie für uns, wenn du feststeckst.

Wie es entsteht

Du legst es nicht von Hand an. Nach dem Setup führst du einmal den Bootstrap aus, und der macht die Genese:

Er legt die Struktur an — CLAUDE.md, ADR/, Docs/, src/.
Er stellt dir strukturelle Fragen. Braucht das eine Datenbank? Melden sich Nutzer an? Gibt es mehrere Mandanten? Es geht nie um deine Produktidee, immer nur um den Rahmen.
Aus den Antworten entstehen die ersten Architekturentscheidungen, aus fertigen Vorlagen statt aus freier Formulierung.
Und es entstehen die ersten Items auf deinem Board — nach einer festen Zuordnung, nicht nach Einschätzung des Modells.

Liegt in src/ schon etwas, erkennt der Bootstrap das und leitet die Entscheidungen aus dem ab, was bereits gebaut ist, statt sie zu erfragen. Der Weg ist derselbe, ob dein Projekt neu ist oder seit drei Jahren läuft.

Was es kostet

Jedes Projekt braucht ein Umbrella, auch ein kleines. Das ist ein zusätzliches Repository und ein zusätzlicher Schritt am Anfang.

Für ein Wochenendprojekt ist das spürbarer Aufwand. Für etwas, an dem du länger als ein paar Wochen arbeitest, ist es der Punkt, an dem sich der Rest rechnet.

Wie du es anlegst → Erste Schritte
Wie Items es durchlaufen → Workflow und Zustand