Thema: Teil 5. Ersteinrichtung des Projekts
Schwierigkeitsgrad: Mittel
Geschätzte Lernzeit: 1,5–2 Stunden
Voraussetzungen: Grundlegendes Verständnis von dbt und Modellschichten (staging, intermediate, marts)
Vertrautheit mit dem Konzept eines KI-Agenten als Entwicklungsteilnehmer
Verständnis der Prinzipien der Versionsverwaltung (Git) und der Arbeit mit einem Repository
Erfahrung mit relationalen Datenspeichern und SQL
Verständnis dessen, was eine Modellspezifikation und ein Mart-Vertrag ist
Lernziele: Erklären, warum die Ersteinrichtung des Projekts in Datenprojekten wichtiger ist als in normalen Anwendungen
Eine minimale Verzeichnisstruktur des Projekts gemäß dem Kursstandard erstellen
Fünf kurze Verhaltensregeln für den Agenten in AGENTS.md formulieren
Die Verantwortungsbereiche von AGENTS.md und specs/tech-stack.md unterscheiden
Eine Projekt-Roadmap nach Artefakten und Prüffakten erstellen
Eine Qwen-Abfrage für ein Audit des Projektgerüsts ohne Dateiänderungen formulieren
Die Projekteinrichtung mit dem Kriterium „nach /clear versteht ein neuer Agent das Projekt ohne Nacherzählen des Chats“ überprüfen
Übersicht: Das Kapitel beschreibt die minimale, aber verpflichtende Ersteinrichtung eines Datenprojekts, in dem ein KI-Agent und ein Mensch als Paar arbeiten. Ziel der Einrichtung ist es, das Gedächtnis von Entscheidungen aus dem Chat in die Repository-Dateien zu verlagern: Mission, Technologie-Stack, Roadmap, Modellspezifikationen, Validierungsnotizen und Reviewer-Berichte. Das Kapitel erläutert, warum die Verzeichnisse specs/, models/ und tests/ benötigt werden, was genau in AGENTS.md geschrieben werden sollte, warum eine Roadmap nach Schichten schlecht ist und welche Abfrage verwendet werden sollte, um den Agenten mit einem Audit des Gerüsts zu beauftragen. Nach dem Kapitel sollten im Repository AGENTS.md, specs/mission.md, specs/tech-stack.md, specs/roadmap.md, Verzeichnisse für Modellspezifikationen, Validierungsnotizen und Reviewer-Berichte sowie ein dbt-Projektgerüst vorhanden sein. Das Kapitel vermittelt das Hauptprinzip: In der Einrichtungsphase werden keine fertigen Artefakte erstellt, sondern „Orte“, an denen diese Artefakte landen werden. Die Einrichtung ist nicht abgeschlossen, wenn die Ordner erstellt sind, sondern wenn sie beginnen, Entscheidungen festzuhalten.
Schlüsselkonzepte: Projektgedächtnis vs. Chat-Gedächtnis: Das Projektgedächtnis ist die Ordnerstruktur und die Dateien (mission.md, tech-stack.md, roadmap.md, Modellspezifikationen, Validierungsnotizen, Reviewer-Berichte). Das Chat-Gedächtnis ist der Inhalt des Dialogs mit dem Agenten, der beim ersten /clear verschwindet. Vor dem Zurücksetzen des Kontexts scheint das Chat-Gedächtnis bequem zu sein, aber für die nächste Person und den nächsten Reviewer ist es nutzlos. Die Ersteinrichtung ist nötig, damit Entscheidungen in Dateien leben und nicht im Dialogfenster.
Minimale Verzeichnisstruktur: Standardlayout des Repositorys: specs/ (mit den Dateien mission.md, tech-stack.md, roadmap.md und den Unterverzeichnissen models/, validation/, reviewer-reports/), models/ (mit den Unterverzeichnissen staging/, intermediate/, marts/), tests/, AGENTS.md, dbt_project.yml, profiles.yml. In der Einrichtungsphase werden keine produktionsreifen Artefakte benötigt, sondern „Orte“, an denen Entscheidungen landen werden. Wenn es beispielsweise den Ordner specs/validation/ nicht gibt, bleiben Prüffakten mit hoher Wahrscheinlichkeit im Chat oder in der PR-Beschreibung.
Agents.md als Verhaltensdatei: Dies ist eine kurze Datei, die das Verhalten des Agenten vor Änderungen festlegt: was gelesen werden soll (Mission, Tech-Stack, Roadmap, benötigte Spezifikationen), was nicht zu tun ist (keine direkten PII offenlegen, grain, SLA und Vertragsfelder nicht ohne Bestätigung ändern), welche Prüfungen auszuführen sind (dbt build), wie zu berichten ist (mit Prüffakten, nicht mit Versprechen). AGENTS.md ist keine Enzyklopädie, sondern eine Liste von Verhaltensregeln. Je kürzer die Regeln, desto höher die Wahrscheinlichkeit, dass Agent und Mensch sie nutzen.
Trennung von agents.md und specs: AGENTS.md beschreibt, wie sich der Agent verhalten soll. specs/mission.md beschreibt, wofür das Projekt gemacht wird. specs/tech-stack.md beschreibt, welcher Stack erlaubt ist und warum. specs/roadmap.md beschreibt, welche Artefakte erscheinen sollen. specs/models/ enthält Modellverträge. specs/validation/ enthält Validierungsnotizen. specs/reviewer-reports/ enthält Reviewer-Berichte. Produktversprechen, Vertragsfelder und Abnahmefakten gehören in specs/, nicht in AGENTS.md.
Roadmap nach Artefakten: In einem Datenprojekt führt man eine Roadmap besser nach Beweisen als nach Schichten. Ein Beispiel für eine schlechte Formulierung ist „marts/customer_360.sql wurde geschrieben“. Ein Beispiel für eine gute Formulierung ist „Mart Customer 360 wurde vom Reviewer geprüft“. So sieht man, dass „Modell geschrieben“ nicht gleich „Produkt fertig“ bedeutet. Ein konkretes Beispiel aus dem Kapitel: 1) raw/staging sind reproduzierbar; 2) Vertrag Customer 360 ist genehmigt; 3) Mart Customer 360 ist geprüft; 4) Risiko-, Kredit- und Einwilligungs-Marts wurden vom Reviewer geprüft; 5) Release-Beweise für die praktische Prüfung sind fertig.
Schichten von Bedeutung, Prüfung und Review: Die Ordner specs/models/, specs/validation/ und specs/reviewer-reports/ signalisieren dem Agenten, dass Bedeutung, Prüfung und Review getrennte Schichten sind und nicht ein Nachwort zum SQL. Wenn diese Ordner fehlen, entsteht die Quelle der Wahrheit dort, wo es für den Agenten bequemer ist: im Kommentar, in der Befehlsausgabe, im Antworttext. Das später wiederherzustellen ist sehr schwierig.
Container für Entscheidungen: In der Einrichtungsphase müssen Container für Entscheidungen geschaffen werden, nicht die Entscheidungen selbst getroffen werden. Die Aufgabe besteht darin, im Voraus zu vereinbaren, wo Mission, Stack, Roadmap, Spezifikationen, Validierungsnotizen und Berichte abgelegt werden. Der Inhalt dieser Ordner wird später in den nächsten Kapiteln des Kurses festgelegt.
Qwen-Abfrage für ein Einrichtungs-Audit: Eine Abfrage, die den Agenten beauftragt, die aktuelle Projektstruktur zu lesen, das Vorhandensein von Orten für Mission, Tech-Stack, Roadmap, Modellspezifikationen, Prüffakten, dbt-Modelle und Reviewer-Berichte zu prüfen und eine Liste von Einrichtungslücken ohne Dateiänderungen zu erstellen. Nach der Liste der Lücken kann man den Agenten bitten, nur die fehlenden Verzeichnisse und leeren Vorlagen anzulegen. SQL schreiben zu lassen ist in dieser Phase nicht erlaubt.
Kriterium für die Einrichtungsbereitschaft: Eine gute Einrichtung ermöglicht einen einfachen Test: Nach dem Leeren des Kontexts muss ein neuer Agent verstehen, wo sich die Mission befindet, welcher Stack erlaubt ist, welche Marts gebaut werden und wie die Bereitschaft nachgewiesen wird. Wenn zur Fortsetzung der Arbeit der Chat nacherzählt werden muss, ist das Projekt noch nicht eingerichtet. Die Einrichtung ist nicht abgeschlossen, wenn die Ordner erstellt sind, sondern wenn sie beginnen, Entscheidungen festzuhalten.
Typischer Einrichtungsfehler: Den Agenten sofort zu bitten, „baue ein Lakehouse zusammen“ – das ist eine zu breite Anfrage. In der Einrichtungsphase müssen Container für Entscheidungen geschaffen werden, nicht die Entscheidungen selbst getroffen werden. Eine solche Anfrage führt den Agenten in eine Diskussion über Stack, Formate und Orchestratoren im Chat, und im Repository erscheint keine einzige Struktureinheit.
Übungsaufgaben: Name: Erstellung des minimalen Projektgerüsts
Problem: Erstellen Sie in einem leeren Repository die folgende Verzeichnisstruktur: specs/ (mit den Unterverzeichnissen models/, validation/, reviewer-reports/), models/ (mit den Unterverzeichnissen staging/, intermediate/, marts/), tests/. Fügen Sie leere Vorlagendateien hinzu: specs/mission.md, specs/tech-stack.md, specs/roadmap.md, AGENTS.md, dbt_project.yml, profiles.yml. Beschreiben Sie, welche Befehle Sie verwenden und in welcher Reihenfolge, und erläutern Sie, warum die Reihenfolge der Verzeichniserstellung für die weitere Arbeit mit dem Agenten wichtig ist.
Lösung: Schritt 1. Erstellen Sie die Stammverzeichnisse mit einem Befehl: mkdir -p specs/models specs/validation specs/reviewer-reports models/staging models/intermediate models/marts tests. Das Flag -p ist nötig, um verschachtelte Verzeichnisse mit einem Befehl zu erstellen. Schritt 2. Erstellen Sie leere Vorlagendateien: touch specs/mission.md specs/tech-stack.md specs/roadmap.md AGENTS.md dbt_project.yml profiles.yml. Schritt 3. Fixieren Sie die Struktur in Git: git init && git add . && git commit -m 'scaffold: minimale Projektstruktur'. Schritt 4. Erklären Sie die Reihenfolge: specs/ ist der Vertrag, models/ ist die Implementierung, tests/ ist die Prüfung. specs/ vor models/ zu erstellen, fixiert die Priorität der Bedeutung gegenüber dem Code. Wenn zuerst models/ erstellt wird, beginnt der Agent SQL zu schreiben, bevor Orte für Mission und Spezifikationen vorhanden sind, und die Quelle der Wahrheit wandert in Kommentare und Chat-Antworten.
Komplexität: intermediate
Name: AGENTS.md nach minimaler Vorlage schreiben
Problem: Füllen Sie AGENTS.md mit fünf Regeln aus dem Kapitel. Formulieren Sie sie eindeutig und kurz: 1) was der Agent vor der Änderung von dbt-Modellen lesen soll; 2) was nicht offengelegt werden darf; 3) was nicht ohne Bestätigung geändert werden darf; 4) welcher Befehl ausgeführt werden soll; 5) wie zu berichten ist. Erläutern Sie, warum jede Regel kurz sein sollte und warum AGENTS.md ein schlechter Ort für die Beschreibung von Marts ist.
Lösung: Schritt 1. Erste Regel – vorbereitendes Lesen: „Lies vor der Änderung von dbt-Modellen die Mission, den Tech-Stack, die Roadmap und die benötigten Modellspezifikationen“. Schritt 2. Zweite Regel – PII-Beschränkung: „Lege keine direkten PII-Felder in marts offen“. Schritt 3. Dritte Regel – Verbot stiller Vertragsänderungen: „Ändere grain, SLA oder Vertragsfelder nicht ohne Bestätigung“. Schritt 4. Vierte Regel – verpflichtende Prüfung: „Führe dbt build aus, wenn dbt verfügbar ist“. Schritt 5. Fünfte Regel – Berichtsformat: „Berichte mit Prüffakten, nicht mit Versprechen“. Schritt 6. Erläuterung: Die Regeln müssen kurz sein, weil eine lange AGENTS.md zu einer Enzyklopädie wird, die niemand liest – weder Mensch noch Agent. Die Beschreibung von Marts gehört in specs/models/, nicht in AGENTS.md, weil es Produktwissen ist und kein Agentenverhalten.
Komplexität: intermediate
Name: Audit des Gerüsts durch eine Qwen-Abfrage
Problem: Formulieren Sie eine Abfrage an den KI-Agenten, die: 1) die aktuelle Projektstruktur lesen soll; 2) das Vorhandensein von Orten für Mission, Tech-Stack, Roadmap, Modellspezifikationen, Prüffakten, dbt-Modelle und Reviewer-Berichte prüfen soll; 3) eine Liste von Einrichtungslücken ohne Dateiänderungen erstellen soll. Formulieren Sie dann eine zweite Abfrage, die auf Basis der Lückenliste nur die fehlenden Verzeichnisse und leeren Vorlagen erstellt, ohne SQL zu schreiben und ohne den Inhalt der Spezifikationen auszufüllen.
Lösung: Schritt 1. Erste Abfrage (nur Lesen): „Lies die aktuelle Projektstruktur. Prüfe, ob es Orte für Mission, Tech-Stack, Roadmap, Modellspezifikationen, Prüffakten, dbt-Modelle und Reviewer-Berichte gibt. Erstelle eine Liste von Einrichtungslücken. Ändere keine Dateien“. Schritt 2. Zweite Abfrage (nur Container): „Erstelle auf Basis der Lückenliste nur die fehlenden Verzeichnisse und leeren Vorlagen. Schreibe kein SQL, fülle den Inhalt der Spezifikationen nicht aus“. Schritt 3. Erläuterung: Die erste Abfrage ist von Mutationen getrennt, sodass der Agent bestehende Dateien nicht versehentlich überschreiben kann und das Team eine saubere Lückenliste sieht. Die zweite Abfrage beschränkt sich auf die Erstellung leerer Container, sodass der Agent nicht vorzeitig in das Schreiben von Modellen und die Stack-Diskussion abdriftet. Das ist das Prinzip „Container für Entscheidungen, nicht die Entscheidungen selbst“.
Komplexität: intermediate
Name: Erstellung einer Roadmap nach Artefakten
Problem: Erstellen Sie für ein fiktives Bank-Datenprojekt „Customer 360“ eine Roadmap mit fünf Punkten. Jeder Punkt sollte ein Artefakt oder Prüffakt benennen, nicht eine Schicht. Erläutern Sie, warum die Formulierung „Modell marts/customer_360.sql wurde geschrieben“ schlecht ist und „Mart Customer 360 wurde vom Reviewer geprüft“ gut ist. Fügen Sie jedem Punkt den erwarteten Beweis hinzu (wo er abgelegt wird).
Lösung: Schritt 1. Punkt 1: „raw/staging sind reproduzierbar“ – der Beweis liegt in specs/validation/ (Bericht über einen reproduzierbaren Lauf) und in tests/ (bestandene dbt build-Tests). Schritt 2. Punkt 2: „Vertrag Customer 360 ist genehmigt“ – der Beweis liegt in specs/models/customer_360.md mit Unterschrift des Mart-Owners. Schritt 3. Punkt 3: „Mart Customer 360 ist geprüft“ – der Beweis liegt in specs/validation/customer_360.md (Bericht über die Prüfung von Feldern, grain und SLA). Schritt 4. Punkt 4: „Risiko-, Kredit- und Einwilligungs-Marts wurden vom Reviewer geprüft“ – der Beweis liegt in specs/reviewer-reports/. Schritt 5. Punkt 5: „Release-Beweise für die praktische Prüfung sind fertig“ – dies ist ein Sammelpunkt, der auf alle vorherigen Ordner verweist. Schritt 6. Erläuterung: Die Formulierung „Modell wurde geschrieben“ beschreibt eine Handlung, nicht ein Ergebnis; die Formulierung „wurde vom Reviewer geprüft“ beschreibt einen Beweis. Eine Roadmap nach Artefakten zeigt sofort, welche Beweise noch fehlen und wo sie abgelegt werden sollen.
Komplexität: intermediate
Name: Trennung der Bereiche von AGENTS.md und specs
Problem: Ihnen werden vier Aussagen gegeben: 1) „PostgreSQL ist eine erlaubte Speicherschicht, weil sie bereits in der Bank verwendet wird“; 2) „Der Agent darf dbt build nicht ohne Lesen von mission.md ausführen“; 3) „Customer 360 enthält die Felder customer_id, full_name, birth_date, risk_score“; 4) „Jeder PR zu einem Mart muss von einem Reviewer-Bericht begleitet werden“. Verteilen Sie sie auf die richtigen Dateien im Repository und erläutern Sie, warum AGENTS.md ein schlechter Ort für Aussage 1 und ein guter für Aussage 2 ist.
Lösung: Schritt 1. Aussage 1 („PostgreSQL ist erlaubt, weil es in der Bank verwendet wird“) gehört in specs/tech-stack.md – dies ist die Beschreibung des erlaubten Stacks und die Begründung der Wahl, nicht das Verhalten des Agenten. Schritt 2. Aussage 2 („der Agent darf dbt build nicht ohne Lesen von mission.md ausführen“) gehört in AGENTS.md – dies ist eine Verhaltensregel des Agenten vor einer Aktion. Schritt 3. Aussage 3 („Customer 360 enthält die Felder…“) gehört in specs/models/customer_360.md – dies ist der Vertrag eines bestimmten Modells, keine Verhaltensregel. Schritt 4. Aussage 4 („jeder PR muss von einem Reviewer-Bericht begleitet werden“) gehört als Verhaltensregel für den Agenten in AGENTS.md und als Prozessanforderung in specs/roadmap.md. Schritt 5. Erläuterung: AGENTS.md ist ein schlechter Ort für Aussage 1, weil sie den Stack beschreibt, nicht das Verhalten; eine Vermischung erzeugt eine aufgeblähte AGENTS.md, die der Agent aufhört zu lesen. AGENTS.md ist ein guter Ort für Aussage 2, weil es eine Regel „vor einer Aktion lesen“ ist, also Verhalten.
Komplexität: advanced
Fallstudien: Name: Bank Customer 360: Wie der Chat eine vergessene PII-Einschränkung „verschluckt“ hat
Szenario: Ein Team aus drei Analysten und einem KI-Agenten baute den Mart Customer 360 für die Risikoabteilung einer Bank. Zu Projektbeginn einigte sich das Team im Chat darauf, dass das Feld email nicht ohne Maskierung in marts ausgegeben werden darf und dass das grain des Marts „ein Kunde – eine Zeile pro Stichtag“ ist. Die Vereinbarungen blieben im Dialogfenster. Zwei Wochen später kam ein neuer Analyst ins Repository und verband einen frischen Kontext mit dem Agenten.
Aufgabe: Nach dem Befehl /clear fand der Agent im Projekt keine Erwähnungen der E-Mail-Maskierung und des Mart-grain. Er generierte einen Mart, in dem email im Klartext ausgegeben wurde und das grain sich zu „eine Zeile pro Kunden-Transaktion“ verwässerte – weil das für die aktuelle Anfrage der Risikoabteilung bequemer war. SQL bestand alle dbt build-Tests und lieferte ein grünes Ergebnis, verletzte aber Vereinbarungen, die nur im Chat lebten. Die Risikoabteilung erhielt einen Mart mit PII und falschem grain, was jegliche Aggregate sinnlos machte.
Lösung: Das Team stoppte das Release, stellte die Chat-Historie manuell wieder her und fixierte zwei neue Ordner im Repository: specs/models/customer_360.md mit grain, SLA, Feldliste und explizitem Verbot von Klartext-Email sowie specs/validation/ für Validierungsnotizen. In AGENTS.md wurden zwei Regeln hinzugefügt: „Lege keine direkten PII-Felder in marts offen“ und „Ändere grain, SLA oder Vertragsfelder nicht ohne Bestätigung“. In specs/tech-stack.md wurde festgehalten, dass PII-Maskierung ein verpflichtender Schritt der Pipeline und nicht optional ist. Die Roadmap wurde nach Artefakten umgeschrieben: „Vertrag genehmigt → Mart geprüft → Mart vom Reviewer freigegeben“.
Ergebnis: Innerhalb einer Woche wurde der Mart neu geschrieben: email wurde nur in maskierter Form ausgegeben, das grain wurde auf „ein Kunde – eine Zeile pro Stichtag“ wiederhergestellt. Ein neuer Analyst, der erstmals zum Projekt stieß, konnte die Arbeit ohne Nacherzählen des Chats fortsetzen: Er las specs/models/customer_360.md und sah sofort die Einschränkungen. Grünes dbt build war kein Zeichen mehr für Bereitschaft – Bereitschaft wurde nun durch den Inhalt von specs/validation/ und specs/reviewer-reports/ nachgewiesen.
Gewonnene Erkenntnisse: Vereinbarungen, die im Chat bleiben, verschwinden beim ersten /clear und sind für eine neue Person unsichtbar
Grünes dbt build ist nicht gleich Produktbereitschaft – Spezifikationen und Prüffakten sind nötig
AGENTS.md sollte eine kurze Liste von Verhaltensregeln sein, keine Kopie der Spezifikationen
Eine Roadmap nach Artefakten zeigt sofort, welche Beweise noch nicht gesammelt sind
Die Ordner specs/models/, specs/validation/ und specs/reviewer-reports/ müssen vor dem ersten SQL-Modell existieren
Verwandte Konzepte: Projektgedächtnis vs. Chat-Gedächtnis
Trennung von AGENTS.md und specs
Schichten von Bedeutung, Prüfung und Review
Roadmap nach Artefakten
Kriterium für die Einrichtungsbereitschaft
Name: E-Commerce-Analyse: Der Versuch, „sofort ein Lakehouse zu bauen“
Szenario: Der Manager eines E-Commerce-Projekts bat den KI-Agenten, „ein Lakehouse für Verkaufsanalysen zu bauen“. Das Projekt hatte weder mission.md noch tech-stack.md noch specs/. Das Repository enthielt nur eine leere README und einen data/-Ordner mit rohen Auszügen.
Aufgabe: Der Agent begann damit, zwischen Spark, ClickHouse, BigQuery und Snowflake zu wählen, diskutierte Datenmodelle, Dateiformate und Orchestratoren direkt im Chat. Nach einer Stunde war der Dialog auf Hunderte von Nachrichten angewachsen, aber im Repository war außer der README keine einzige Struktureinheit aufgetaucht. Als ein zweiter Analyst kam, konnte er nicht verstehen, welche Entscheidungen bereits getroffen waren, weil sie über den Chat verstreut waren. Jedes /clear löschte den Kontext, und die Arbeit musste von vorn begonnen werden.
Lösung: Der Manager stoppte den Dialog und begann mit der Projekteinrichtung nach den Regeln des Kapitels. Er erstellte specs/mission.md („Verkaufsanalyse E-Commerce, Fokus auf Wiederholungskäufe“), specs/tech-stack.md („ClickHouse als Speicher, dbt als Transformationsschicht, Airflow als Orchestrator“), specs/roadmap.md nach Artefakten und AGENTS.md mit fünf kurzen Verhaltensregeln. Danach wurde dem Agenten eine Qwen-Abfrage für ein Audit des Gerüsts gesendet: „Lies die aktuelle Projektstruktur. Prüfe, ob es Orte für Mission, Tech-Stack, Roadmap, Modellspezifikationen, Prüffakten, dbt-Modelle und Reviewer-Berichte gibt. Erstelle eine Liste von Einrichtungslücken. Ändere keine Dateien“. Auf Basis der Lückenliste wurde der Agent beauftragt, nur die fehlenden Verzeichnisse und leeren Vorlagen zu erstellen, ohne SQL zu schreiben.
Ergebnis: Nach 30 Minuten war das Gerüst fertig, und der zweite Analyst kam bereits nach der Einrichtung ins Projekt. Er las mission.md, tech-stack.md und roadmap.md in 10 Minuten und verstand sofort, was gemacht wird und warum. Danach ging das Team zu den Modellspezifikationen über und erst danach zu SQL. Die Onboarding-Zeit für ein neues Teammitglied verkürzte sich von mehreren Tagen auf eine Stunde. Ein neuer Agent nach /clear verstand das Projekt ebenfalls ohne Nacherzählen des Chats, was das Kriterium für die Einrichtungsbereitschaft bestätigte.
Gewonnene Erkenntnisse: Eine zu breite Anfrage an den Agenten („baue ein Lakehouse“) führt zu einem Dialog ohne Artefakte im Repository
Die Projekteinrichtung bedeutet, Container für Entscheidungen zu schaffen, nicht die Entscheidungen selbst zu treffen
Eine Qwen-Abfrage mit Änderungsverbot eignet sich gut für ein Audit des Gerüsts
Eine Roadmap nach Artefakten hilft, nicht in „Schichten um der Schichten willen“ zu verfallen
Eine kurze AGENTS.md funktioniert besser als eine lange Anleitung
Verwandte Konzepte: Container für Entscheidungen
Qwen-Abfrage für ein Einrichtungs-Audit
Minimale Verzeichnisstruktur
Roadmap nach Artefakten
Typischer Einrichtungsfehler
Name: Marketplace: AGENTS.md als Enzyklopädie und zerbrochenes Onboarding
Szenario: Ein Analyst eines Marketplace schrieb AGENTS.md auf 12 Seiten: Dort landeten Anleitungen zur Arbeit mit dbt, Beschreibungen aller Marts, Sicherheitsanforderungen, Datenschemata und sogar SQL-Stücke. Die Datei wurde regelmäßig aktualisiert, aber niemand las sie vollständig – weder Mensch noch Agent.
Aufgabe: Als ein neuer Agent ins Projekt kam, ignorierte er die lange AGENTS.md und stützte sich auf seinen eigenen „gesunden Menschenverstand“. Insbesondere begann er, das grain des Bestell-Marts ohne Bestätigung zu ändern, weil die Regel zum Verbot der grain-Änderung zwischen den Schemabeschreibungen und SQL-Beispielen unterging. Der Reviewer bemerkte das Problem erst, nachdem der Mart in Produktion ging und den Umsatzbericht brach. Die Prüffakten waren dabei über PR-Kommentare und den Chat verstreut, sodass der Gedankengang des Agenten nicht rekonstruierbar war.
Lösung: Das Team schrieb AGENTS.md nach den Regeln des Kapitels um: Es ließ fünf kurze Verhaltensregeln übrig (was zu lesen ist, was nicht offengelegt werden darf, was nicht ohne Bestätigung geändert werden darf, welcher Befehl auszuführen ist, wie zu berichten ist). Alle Produktbeschreibungen, Mart-Beschreibungen, Vertragsfelder und Abnahmefakten wurden in specs/ verschoben: in specs/mission.md, specs/tech-stack.md, specs/roadmap.md, specs/models/ und specs/validation/. Der Ordner specs/reviewer-reports/ wurde neu angelegt, und der Reviewer erhielt die Anweisung, Berichte dorthin zu schreiben, nicht in den Chat. Die Roadmap wurde nach Artefakten umgeschrieben mit explizitem Verweis auf specs/validation/ als Speicher der Beweise.
Ergebnis: Innerhalb eines Monats sank die Anzahl der Vertragsverletzungen (Änderung des grain, PII-Leaks, SLA-Änderungen ohne Bestätigung) fast auf null. Der neue Agent begann, die kurzen Regeln von AGENTS.md zu befolgen und für Details auf specs/ zuzugreifen. Die Review-Zeit pro PR verkürzte sich, weil die Prüffakten in specs/validation/ lagen und nicht über Chat und Kommentare verstreut waren. Das Team konnte erstmals das Kriterium für die Einrichtungsbereitschaft prüfen: Ein neuer Agent nach /clear verstand das Projekt ohne Nacherzählen des Chats.
Gewonnene Erkenntnisse: Eine lange AGENTS.md wird zur Enzyklopädie, die niemand liest
Verhaltensregeln und Produktbeschreibungen müssen in verschiedenen Dateien leben
Prüffakten gehören in specs/validation/, nicht in PR-Kommentare
Eine kurze AGENTS.md erhöht die Wahrscheinlichkeit, dass Agent und Mensch sie nutzen
Der Reviewer-Bericht ist ein eigenständiges Artefakt (specs/reviewer-reports/), keine Chat-Nachricht
Verwandte Konzepte: AGENTS.md als Verhaltensdatei
Trennung von AGENTS.md und specs
Schichten von Bedeutung, Prüfung und Review
Roadmap nach Artefakten
Projektgedächtnis vs. Chat-Gedächtnis
Lerntipps: Versuchen Sie nicht, specs/ sofort mit Inhalt zu füllen – in der Einrichtungsphase werden nur leere Container und Überschriften benötigt
Fragen Sie sich vor jeder Änderung im Projekt: „Wenn ich jetzt /clear mache, versteht ein neuer Agent, wo er diese Entscheidung findet?“ Wenn die Antwort „nein“ lautet, muss die Entscheidung in einer Datei leben, nicht im Chat
Halten Sie AGENTS.md kurz: Lieber fünf kurze Regeln als zwölf Seiten Anleitungen
Erstellen Sie die Roadmap nach Artefakten und Prüffakten, nicht nach „Schichten um der Schichten willen“
Verwenden Sie die Qwen-Abfrage aus dem Kapitel als Vorlage für das Audit des Gerüsts: erste Abfrage – nur Lesen, zweite – nur Erstellung leerer Verzeichnisse
Trennen Sie das Verhalten des Agenten (AGENTS.md) von der Produktbeschreibung (specs/); eine Vermischung erzeugt aufgeblähte Dateien, die niemand liest
Prüfen Sie das Kriterium für die Einrichtungsbereitschaft: Ein neuer Agent nach /clear muss Mission, Stack, Marts und die Art, Bereitschaft nachzuweisen, ohne Nacherzählen des Chats verstehen
Führen Sie die Einrichtung vor dem ersten SQL-Modell durch; sonst entsteht die Quelle der Wahrheit in Kommentaren und Antworttexten des Agenten und ist schwer wiederherzustellen
Vermeiden Sie breite Anfragen wie „baue ein Lakehouse“ – in der Einrichtungsphase werden Container für Entscheidungen benötigt, nicht die Entscheidungen selbst
Fixieren Sie jede wesentliche Entscheidung sofort nach der Entscheidung in specs/, nicht „wenn Zeit ist“
Zusätzliche Ressourcen: Dbt documentation — project structure: https://docs.getdbt.com/docs/build/projects — offizieller Leitfaden zur Struktur eines dbt-Projekts, zu den Dateien dbt_project.yml und profiles.yml
Dbt labs — model contracts: https://docs.getdbt.com/docs/collaborate/govern/model-contracts — Beschreibung von Modellverträgen, Fixierung von grain und Feldbestand
Anthropic — claude documentation: https://docs.anthropic.com — Empfehlungen zur Formulierung von Verhaltensregeln für KI-Agenten
Conventional commits: https://www.conventionalcommits.org — Standard für die Gestaltung von Commits, nützlich zur Fixierung von Gerüst-Einrichtungsschritten
Markdown guide: https://www.markdownguide.org — Nachschlagewerk für die Auszeichnungssprache für mission.md, tech-stack.md, roadmap.md und AGENTS.md
Git book — recording changes to the repository: https://git-scm.com/book — Grundlagen der Arbeit mit Git, die zur Fixierung des Gerüsts und seiner Versionierung nötig sind
Zusammenfassung: Das Kapitel „Teil 5. Ersteinrichtung des Projekts“ lehrt, das Gedächtnis von Entscheidungen aus dem Chat in die Repository-Dateien zu verlagern. Das minimale Gerüst umfasst specs/ (mission.md, tech-stack.md, roadmap.md und die Unterverzeichnisse models/, validation/, reviewer-reports/), models/ (staging, intermediate, marts), tests/, AGENTS.md, dbt_project.yml und profiles.yml. AGENTS.md legt kurze Verhaltensregeln fest: was vor einer Änderung zu lesen ist, was nicht offengelegt werden darf, was nicht ohne Bestätigung geändert werden darf, welcher Befehl auszuführen ist und wie mit Prüffakten zu berichten ist. Die Spezifikationen für Mission, Stack, Roadmap, Modellverträge und Abnahmefakten leben in specs/, nicht in AGENTS.md. Die Roadmap führt man besser nach Artefakten und Prüffakten, damit sichtbar wird, dass „Modell geschrieben“ nicht gleich „Produkt fertig“ bedeutet. Für das Audit des Gerüsts wird eine Qwen-Abfrage mit Änderungsverbot verwendet; nach der Lückenliste wird der Agent beauftragt, nur die fehlenden Verzeichnisse und leeren Vorlagen zu erstellen, ohne SQL zu schreiben. Ein typischer Fehler ist eine zu breite Anfrage wie „baue ein Lakehouse“, die den Agenten in eine Stack-Diskussion im Chat führt, ohne dass im Repository eine Struktureinheit erscheint. Die Einrichtung ist abgeschlossen, wenn nach /clear ein neuer Agent Mission, Stack, Marts und die Art, Bereitschaft nachzuweisen, ohne Nacherzählen des Chats versteht: Die Ordner beginnen, Entscheidungen festzuhalten.