Agent-native Architektur — Markdown + Frontmatter als Objektmodell

Agent-native Architektur

Kern-Idee

In klassischer Software gibt es eine strikte Trennung: Daten sind passiv (Tabellen warten darauf, gelesen zu werden), Code ist aktiv (Methoden fuehren Logik aus). Agent-native Systeme verwischen das. Ein CLAUDE.md ist Daten (Text) UND aktiv (wird beim Betreten des Ordners wirksam und veraendert Agent-Verhalten). Ein Markdown-File mit Frontmatter ist Datensatz UND Instruktion zugleich.

Folge: Die Abstraktionsebene verschiebt sich, aber die fundamentalen Konzepte bleiben.

Mapping OOP → Agent-native

OOP-Konzept	Klassisch	Agent-native Entsprechung
Daten	Datenbank (Tables, Rows)	Markdown-Files + YAML-Frontmatter
Prozedur / Methode	sum(x, y)	Skill summiere x und y (SKILL.md)
Objekt	Customer Klasse mit Feldern + Methoden	Ordner kunden/koehnemann/ mit .md-Files + CONTEXT.md + Skills
Kapselung	private / public Modifier	visibility: internal im Frontmatter, _internal/ Prefix
Vererbung	class B extends A	Parent CLAUDE.md + lokale CONTEXT.md die Context erweitert / ueberschreibt
Polymorphie	Methode verhaelt sich je nach Typ anders	Skill reagiert je nach Ordner-Kontext / Frontmatter unterschiedlich
Interface / Contract	abstrakte Methodensignatur	contract.md in Pipeline-Stages — lies X, mach Y, schreib Z
Modul / Namespace	import foo from bar	Ordner-Struktur + Wiki-Links
Event / Callback	onClick, subscribe()	Behavior Rules in CLAUDE.md (“Wenn User X sagt → tu Y”)

Skills sind Methoden in natuerlicher Sprache auf einem Folder-”Objekt”.

Was Datenbanken weiterhin unersetzlich macht

Agent-File-Systeme funktionieren auf menschlichem Tempo: Hunderte Eintraege, wenige parallele Schreiber, Sinn-Kontext wichtig. Wo sie versagen:

• ACID / Transaktionen — Zahlungen, doppelte Buchungen, Konsistenz ueber mehrere Entitaeten
• Nebenlaeufigkeit — 1000 User schreiben gleichzeitig, Locks, Isolation
• Structured Queries — “alle Kunden mit Revenue > 10k in Branche X sortiert nach Last-Touch” in 50ms
• Millionen-Scale — Logs, Analytics, Event-Streams. grep arbeitet nicht mit 10 Mio Files
• Strenge Schemas — wenn ein Wert einen festen Typ + Constraint braucht, nicht “meist ein Datum”

Faustregel:

• < 1000 Eintraege + wenige parallele Schreiber + Semantik-reich → Markdown reicht, ist besser weil lesbar + Agent-navigierbar
• Hohe Schreibfrequenz / strikte Struktur / komplexe Aggregationen → Datenbank

Die interessante Verschmelzung

Zwei Konsequenzen aus dem “Daten traegen Instruktionen”-Muster:

1. Self-describing Objects. Ein customer-profile.md mit Frontmatter type: customer-profile, status: active ist nicht nur “ein Textfile”. Der Agent weiss aus dem Frontmatter was er damit tun darf und welche Regeln gelten.
2. Living Documentation. Dokumentation und Verhalten sind dasselbe Artefakt. Wenn sich CLAUDE.md aendert, aendert sich das Systemverhalten. Keine Drift zwischen “was die Doku sagt” und “was der Code tut” — es gibt nur ein Ding.

Praktische Konsequenzen fuer agent-agentur

1. Wiki = Datenschicht. Kundenprofile, Wissen, Branchen leben als .md. Jede Datei hat Frontmatter mit type, status, visibility. Das Frontmatter ist das Schema-light.
2. Skills = Prozeduren. Wiederverwendbare Ablaeufe (Tages-Planung, Email-Scan, Kunden-Briefing) leben in skills/ mit SKILL.md. Ein Skill ist eine Methode die auf dem Vault-Objekt arbeitet.
3. Pipelines = Zustandsautomaten. Mehrstufige Prozesse (Post erstellen, Onboarding) sind Pipelines mit Stages, jede Stage hat contract.md. Das ist ein State-Machine-Pattern in Markdown.
4. CLAUDE.md + CONTEXT.md = Klassen-Definition. CLAUDE.md im Root ist die Basisklasse. Jeder Unterordner ueberschreibt Teilverhalten via CONTEXT.md. Bei Konflikt gewinnt die tiefere Ebene (lokaler Scope).
5. Datenbank kommt spaeter. Sobald wir Analytics machen (Performance-Tracking ueber Zeit, Kohortenvergleich, Reporting ueber viele Kunden) brauchen wir eine DB. Bis dahin reicht Markdown + Dataview-Queries fuer Uebersichten.

Was das nicht ist

• Kein Argument gegen Datenbanken. Agent-native Systeme ersetzen keine DB fuer Production-Workloads. Sie sind eine andere Abstraktionsebene fuer andere Probleme.
• Keine Ausrede fuer schlechte Struktur. Dass Frontmatter “schema-light” ist, heisst nicht “schreib irgendwas rein”. conventions.md ist hier das Schema-Kontrakt — ohne Konventionen wird das Vault schnell ein Daten-Sumpf.
• Kein Ersatz fuer echte Code-Logik. Wo Agenten-Prompts unzuverlaessig werden (numerische Praezision, Echtzeit-Anforderungen, Security-kritisches), bleibt echter Code die richtige Wahl. Der Runner-Layer (siehe runner-architektur.md) ist genau dafuer da.

Related

• CLAUDE.md — Basisklasse des Vaults
• conventions.md — Schema-Kontrakt fuer Files + Ordner
• zugriffsmodell.md — wie Kunden-Sichtbarkeit mit visibility: und _internal/ greift
• runner-architektur.md — LLM-Agnostik-Layer, wo echter Code hingehoert
• _index.md — Inventar aller Decision Records