SOUL.md

In vielen Softwareprojekten liegen neben dem eigentlichen Programmcode ein paar erklärende Textdateien. Sie sind im Format Markdown geschrieben, also einfacher Text mit ein paar Zeichen für Überschriften und Listen. Die bekannteste heißt README und erklärt, wie man das Projekt installiert und benutzt. SOUL.md ist eine jüngere Ergänzung dazu und beantwortet eine andere Frage: warum es dieses Projekt überhaupt gibt. Dort steht, welchen Zweck es verfolgt, welche Grundsätze gelten, welcher Tonfall gewünscht ist und was ausdrücklich nicht gebaut werden soll. Der Name spielt darauf an, dass hier die „Seele“ des Projekts festgehalten wird und nicht seine Technik.

Warum Projekte plötzlich ihre Haltung aufschreiben

Der Anlass für solche Dateien sind Programmierassistenten auf KI-Basis. Solche Werkzeuge lesen ein Projekt ein und schreiben auf Zuruf neuen Code dazu. Sie sind sehr gut darin, Regeln zu befolgen, die irgendwo schriftlich stehen. Alles, was nur im Kopf des Teams existiert, ist für sie unsichtbar.

Genau da entsteht ein Problem. Ein Team weiß vielleicht seit Jahren, dass es keine nervigen Pop-ups einbaut und keine Nutzerdaten an Dritte weitergibt. Niemand hat das je notiert, weil es allen selbstverständlich schien. Eine KI kennt diese ungeschriebenen Regeln nicht und schlägt fröhlich ein Pop-up vor. SOUL.md macht solche stillschweigenden Grundsätze sichtbar und damit maschinenlesbar.

Ein zweiter Grund betrifft Menschen. Projekte wechseln Mitarbeiter, und Open-Source-Projekte bekommen ständig Beiträge von Fremden. Eine Datei, die den Zweck und die Grenzen in klaren Worten beschreibt, spart lange Diskussionen. Sie ist damit weniger eine KI-Erfindung als ein alter Wunsch, der durch KI dringend geworden ist.

Was in so einer Datei steht

Ein festes Format gibt es nicht, SOUL.md ist kein offizieller Standard. Üblich sind aber einige wiederkehrende Abschnitte. Am Anfang steht meist der Zweck in zwei oder drei Sätzen. Dann folgen Grundsätze, oft als Liste von Sätzen wie „Geschwindigkeit ist wichtiger als Funktionsfülle“.

Besonders nützlich ist der Abschnitt mit den Grenzen. Dort steht, was das Projekt bewusst nicht tut. Solche Negativregeln sind für eine KI wertvoller als schöne Absichtserklärungen, weil sie eindeutig prüfbar sind. Häufig kommt noch ein Abschnitt zum Tonfall dazu, etwa für Fehlermeldungen oder Texte in der Benutzeroberfläche.

Technisch passiert dabei nichts Magisches. Die Datei wird dem KI-Assistenten zusammen mit dem Code als Text mitgegeben. Er behandelt ihren Inhalt wie eine Anweisung des Nutzers. Genau deshalb gilt: je konkreter die Sätze, desto besser die Wirkung. Ein Satz wie „Wir lieben gute Qualität“ ändert praktisch nichts, ein Satz wie „Keine externen Werbe-Bibliotheken einbinden“ schon.

SOUL.md, AGENTS.md und der Rest der Dateifamilie

Wer auf Plattformen wie GitHub durch Projekte stöbert, trifft inzwischen auf eine ganze Reihe solcher Dateien. AGENTS.md und CLAUDE.md enthalten technische Anweisungen für KI-Assistenten, etwa welche Befehle zum Testen laufen müssen. CONTRIBUTING.md richtet sich an menschliche Mitwirkende. SOUL.md steht daneben und deckt die inhaltliche Ebene ab.

Man kann sich den Unterschied wie bei einem Praktikanten vorstellen. AGENTS.md ist die Liste der Arbeitsabläufe im Betrieb. SOUL.md ist das Gespräch darüber, worauf es der Firma ankommt und wo sie nicht mitmacht. Beides braucht man, aber es sind verschiedene Dinge.

In Tech-News taucht der Begriff meist im Zusammenhang mit sogenanntem Vibe Coding auf, also dem Programmieren, bei dem eine KI den Großteil des Codes schreibt. Ein verbreiteter Irrtum dabei ist, die Datei sei eine Sicherheitsmaßnahme. Das ist sie nicht: eine KI kann Anweisungen missverstehen oder übergehen, und niemand erzwingt die Einhaltung technisch. SOUL.md ist eine Orientierungshilfe, kein Schloss an der Tür.