Maschinen lesen mit.
Dokumentation hat zwei Leserschaften. Diese Website ist mein Selbstversuch, für Menschen und Maschinen aus derselben Quelle zu schreiben.
Diese Website hat zwei Leserschaften. Die eine sind Menschen, die etwas über mich, meine Projekte und meine Überzeugungen erfahren wollen. Die andere sind Maschinen: Coding-Agenten und AI-Assistenten, die Seiten, Regeln und Zusammenhänge tatsächlich auswerten und nicht nur indexieren. Deshalb ist die Seite nicht nur für den Browser gebaut.
Zwei Oberflächen, eine Quelle
Für Maschinen pflegt diese Seite zwei ergänzende Dateien. Die llms.txt ist eine Konvention, die einer Website eine kurze, maschinenlesbare Zusammenfassung mitgibt; meine llms.txt wird automatisch aus denselben Inhalten generiert, die Menschen auf den Seiten lesen. Die AGENTS.md im Repository erklärt Coding-Agenten die Regeln des Projekts: dass die llms.txt niemals Unveröffentlichtes zeigen darf, dass externe Links in einem neuen Tab öffnen und wo die Regeln der genutzten Framework-Version zu finden sind. Ein Teil dieser Datei schreibt sogar das Framework selbst – sie erneuert sich bei jedem Dev-Start.
Entscheidend ist: Es gibt keine zweite Wahrheit. Menschen lesen Seiten, Maschinen lesen Struktur. Beides stammt aus denselben Quelldateien.
Schreiben für Maschinen schärft das Schreiben für Menschen
Der größte Effekt des Experiments ist ein Nebeneffekt. Wenn ein Agent meine Struktur missverstehen kann, versteht sie wahrscheinlich auch ein Mensch ohne Vorwissen nicht. Eine Zusammenfassung, die in einen Satz passt, zwingt mich, den Kern zu finden. Stabile Adressen, klare Namen und eindeutige Regeln helfen beiden Leserschaften gleichzeitig.
Umgekehrt gilt: Was nur für Maschinen verständlich ist, wird auf Dauer auch für Menschen unverständlich. Suchmaschinen-Optimierung hat das vor Jahren vorgemacht, als Seiten für Crawler geschrieben wurden und Menschen den Rest aushalten durften. Deshalb generiere ich die Maschinenfassung aus den echten Inhalten – nicht umgekehrt.
Prinzipien
Aus dem Selbstversuch sind für mich ein paar Prinzipien entstanden:
- Eine Quelle, zwei Lesarten: Die Maschinenfassung wird aus den Inhalten generiert, die Menschen lesen – nie parallel gepflegt.
- Struktur vor Stil: Stabile Adressen, kurze Zusammenfassungen und eindeutige Namen tragen mehr als jede Gestaltung.
- Regeln gehören ins Repository: Eine AGENTS.md ersetzt mündliche Übergaben und Wissen, das nur in Köpfen existiert.
- Missverständnisse sind Tests: Wo ein Agent falsch lesen kann, liegt meist die Unklarheit – nicht beim Leser.
Maschinen lesen mit. Gutes Schreiben wird dadurch nicht einfacher – es wird wichtiger.