Best Practices: Bootstrap-Prompt – Gunther Popp – Softwarearchitekt & AI‑Driven Development Experte

Ein guter Bootstrap-Prompt versorgt AI-Coding-Agenten mit genau dem Kontext, den sie für eine Aufgabe brauchen. Was gehört hinein, was nicht und wie wird er gestaltet?

Einleitung

Ein professioneller AI-Driven-Development-Prozess erfordert mehr als nur die Auswahl eines AI-Coding-Tools. Es braucht Steuerungsinstrumente, um die Zusammenarbeit zwischen Mensch und Maschine zu strukturieren und konsistente Ergebnisse zu erzielen. Eines der wichtigsten dieser Instrumente ist der Bootstrap-Prompt.

AI-Coding-Agenten sind sessionbasiert, d. h., sie starten mit einem leeren Kontext und bauen diesen erst im Laufe der Session auf. Der Bootstrap-Prompt ist eine Anweisung, die zu Beginn jeder Session ausgeführt wird, um den Agenten mit dem nötigen Projektkontext auszustatten. Ohne Bootstrap-Prompt muss der Agent auf eigene Faust herausfinden, welche Architektur, Konventionen, Dokumentation und Regeln in diesem Projekt gelten. Selbst wenn das klappen sollte, ist es zumindest sehr ineffizient und teuer. Zudem besteht die Gefahr, dass sich Inkonsistenzen in die erstellten Artefakte einschleichen, weil der Agent wichtige Informationen nicht gefunden oder falsch interpretiert hat.

Bootstrapping ist nicht nur das einmalige Formulieren eines Prompts, sondern Context Engineering, also das systematische Bereitstellen von relevantem Kontext als Bestandteil des Entwicklungsprozesses.

Ausprägungen von Bootstrap-Prompts

Ein Bootstrap-Prompt ist eine klassische Best Practice, kein konkretes Dateiformat oder ein bestimmtes Template, das immer 1:1 übernommen werden muss. Es gibt verschiedene Möglichkeiten, wie ein Bootstrap-Prompt in den Entwicklungsprozess integriert werden kann, aber letztlich läuft es immer auf die folgenden beiden Varianten hinaus:

Always-on Instructions (AoI): Projektweite oder sogar global gültige Regeln, die automatisch geladen werden, z. B. AGENTS.md, CLAUDE.md oder .github/copilot-instructions.md. Sie sind möglichst knapp gehalten und enthalten wirklich nur die wichtigsten Regeln, die für alle Sessions entweder global oder im Projekt gelten.
Session-Bootstrap: Ein manuell geladener Prompt zu Beginn einer neuen Session. Er setzt die Always-on Instructions voraus und ergänzt den spezifischen Kontext für die jeweilige Session abhängig von der anstehenden Aufgabe (z. B. Implementierung oder Code-Review).

AoI-Prompts

Die populärsten Alternativen für Always-on Instructions sind:

AGENTS.md: Der wichtigste offene Standard für AoI-Prompts. Hinter AGENTS.md steht die Agentic AI Foundation unter dem Dach der Linux Foundation, also eine herstellerübergreifende, neutrale Organisation. Unterstützt wird der Standard u. a. von Codex, Cursor und GitHub Copilot, aber interessanterweise nicht von Claude Code (siehe unten). Codex berücksichtigt beispielsweise eine globale ~/.codex/AGENTS.md-Datei und einzelne AGENTS.md-Dateien in der Projektstruktur (vom Root bis hinein in die einzelnen Verzeichnisse). Zusätzlich können Entwickler:innen eigene Regeln in einer AGENTS.override.md-Datei definieren, die dann typischerweise in .gitignore aufgenommen wird. Alle gefundenen Dateien werden “von oben nach unten” hintereinander gehängt und als Startpunkt für den Kontext der Session verwendet. Auf der offiziellen Webseite https://agents.md findet ihr zahlreiche Beispiele für die Gestaltung von AGENTS.md-Dateien.
CLAUDE.md: Wie ich oben schon erwähnt habe, setzt Claude Code mit CLAUDE.md auf eine “eigene” AoI-Variante. Ähnlich wie bei AGENTS.md kann man einen globalen AoI-Prompt definieren (~/.claude/CLAUDE.md) oder spezifische Prompts in der Projektstruktur anlegen. Daneben existiert CLAUDE.local.md als lokale Override-Variante. Wer wie ich mit mehreren AI-Coding-Tools arbeitet, sollte die eigentlichen AoI-Prompts über AGENTS.md-Dateien definieren und dann in CLAUDE.md per @AGENTS.md-Import einbinden.

Es gibt noch weitere Varianten wie beispielsweise die Copilot Instructions oder Claude Code Rules, auf die ich hier im Detail aber nicht eingehen möchte. Meines Erachtens sind AGENTS.md und CLAUDE.md für die meisten Anwendungsfälle als AoI-Prompts ausreichend. Für alle aufgabenspezifischen Regeln sind dann Session-Bootstrap-Prompts die bessere Wahl.

Session-Bootstrap-Prompts

Ein guter Session-Bootstrap-Prompt beantwortet fünf Fragen:

Was ist der Projektkontext? Der Agent muss wissen, womit er es zu tun hat. Gute Quellen sind in der Regel READMEs, Architektur-Doku, semantisches Datenmodell und die wichtigsten Projektdateien.
Welche Regeln gelten immer? Hier geht es um die Einschränkung des Handlungsspielraums (z. B. “Keine Refactorings ohne Rückfrage, keine Änderungen außerhalb des Workspaces”), Einhaltung der Architektur, Coding-Konventionen, Test-Anforderungen, Dokumentationssprache und Umgang mit bestehenden Patterns.
Welche Kommandos prüfen das Ergebnis? Build, Tests, Linting, Typecheck, Formatierung und ggf. projektspezifische Smoke-Tests.
Wie soll der Agent mit Unsicherheit umgehen? Hier gebe ich z. B. vor, dass Agenten im Zweifel nachfragen statt raten, Annahmen explizit benennen und widersprüchliche Dokumentation bzw. Spezifikationen mit mir diskutieren.
Wie funktioniert der Entwicklungsprozess? Agenten müssen den AI-Driven Development Prozess verstehen, bevor sie ihn ausführen können. Also beispielsweise: Ausgangspunkt ist immer eine Feature-Datei, daraus entsteht ein Implementierungsplan als Markdown-Datei, der Plan muss genehmigt werden, bevor mit der Implementierung begonnen wird. Und das Ergebnis der Implementierung wird als separate Markdown-Datei dokumentiert und kann damit in die nächste Iteration einbezogen werden.

Die konkrete Verwendung eines Session-Bootstrap-Prompts ist denkbar einfach: Er wird entweder per Copy-Paste in das Chat-Fenster eingefügt oder man bittet den Agenten, den Bootstrap-Prompt aus der Prompt-Datei zu laden. Es geht sicher auch “fancier” mit einem Custom Command oder Skill, ich bin bis jetzt mit der KISS-Variante aber ganz gut gefahren.

Ich habe zwei Beispiele für Session-Bootstrap-Prompts erstellt, die ihr euch gerne anschauen könnt: Ein Bootstrap-Prompt zur Implementierung von Features in einem Java-Projekt mit Maven und ein Bootstrap-Prompt für Code-Reviews.

Was gehört nicht in den Session-Bootstrap-Prompt?

Die größte Gefahr bei der Gestaltung von Session-Bootstrap-Prompts ist, dass sie zu umfangreich und unübersichtlich werden. Es ist wichtig, den Bootstrap auf die wirklich relevanten Informationen zu beschränken. Hier sind einige Dinge, die nicht in den Session-Bootstrap-Prompt gehören:

Bootstrap und Aufgabe trennen: Der Bootstrap baut Kontext auf. Die konkrete Implementierungsaufgabe kommt danach, einfach direkt im Chat-Fenster.
Keine Secrets: Tokens, API Keys, Passwörter und interne Zugangsdaten gehören nicht in Prompts.
Keine Wiederholung der Always-on Instructions: Wenn eine Regel bereits in AGENTS.md oder CLAUDE.md steht, sollte der Bootstrap sie nicht kopieren. Er sollte nur ergänzen, was für diese Session oder diesen Arbeitsmodus zusätzlich gilt.
Keine Wiederholung der Projektdokumentation: Architekturdokumentation, semantisches Datenmodell, Codierrichtlinien, Spezifikationen, … dürfen nicht in den Bootstrap kopiert werden. Stattdessen sollte der Bootstrap den Agenten anweisen, die relevanten Dokumente zu lesen und die wichtigsten Informationen daraus zu extrahieren.
Keine Regeln, die besser technisch erzwungen werden: Formatierung, Linting, Typecheck, etc. sollten durch Tools abgesichert werden. Der Bootstrap verweist auf diese Kommandos, ersetzt sie aber nicht.

Fazit

Der Bootstrap-Prompt ist aus meiner Sicht kein optionales Extra, sondern ein zentrales Artefakt im professionellen AI-Driven Development. Er stellt sicher, dass Agenten den Projektkontext verstehen, bevor sie mit der Arbeit beginnen. Die in einen gut gepflegten Bootstrap-Prompt investierte Zeit zahlt sich durch konsistentere Ergebnisse und weniger Korrekturen aus.

Ich empfehle, einen sehr sparsamen AoI-Prompt zu erstellen und die meisten Regeln und Kontextinformationen in Session-Bootstrap-Prompts zu packen, die dann je nach Arbeitsmodus (Implementierung, Code-Review, Refactoring, …) angepasst werden können. Persönlich verzichte ich auch weitgehend auf den Einsatz von hierarchischen AoI-Prompts (z. B. AGENTS.md in mehreren Verzeichnissen), da das die Übersicht erschwert und die Gefahr von Inkonsistenzen erhöht.

Neben dem Bootstrap-Prompt gibt es ein weiteres wichtiges Steuerungsinstrument im AI-Driven Development: den Implementierungsplan, der die Ausführung in kontrollierte, überprüfbare Aufgaben zerlegt. Aber dazu mehr im nächsten Beitrag.