Nach der Analyse von 2.500 Fällen auf GitHub: Wir haben die "Sechs Hauptregeln" für die Erstellung von AI-Agent-Spezifikationen zusammengefasst.

Das Divine Translation Bureau ist ein Übersetzungsteam von 36Kr, das sich auf Technologie, Business, Karriere und Lebensbereiche konzentriert und vor allem neue Technologien, neue Ansichten und neue Trends aus dem Ausland vorstellt.

Herausgeberhinweis: Hängen Sie nicht mehr lange Dokumente an Agenten! Die Beherrschung dieses Management-Frameworks für "digitale Praktikanten" ist der entscheidende Schlüssel, um KI von einem Spielzeug zu einer produktiven Kraft zu entwickeln.

Das Ziel ist es, eine klare Spezifikation zu schreiben, die die richtige Menge an Details enthält (einschließlich Struktur, Stil, Tests und Grenzen), um die KI zu leiten, ohne sie mit zu viel Informationen zu überlasten. Zerlegen Sie große Aufgaben in kleinere, anstatt alles in einen riesigen Prompt zu packen. Planen Sie zunächst im "Nur-Lesen-Modus" und führen Sie dann die Aufgabe aus und iterieren Sie kontinuierlich.

"Ich habe viele Tipps darüber gehört, wie man gute Spezifikationen für KI-Agenten schreibt, aber ich habe noch nie ein reifes Framework gefunden. Ich kann auch detaillierte Spezifikationen wie ein RFC (Request for Comments) schreiben, aber sobald der Kontext zu lang wird, beginnt das Modell 'zu streiken'."

Viele Entwickler teilen diese Frustration. Es funktioniert nicht, eine lange Spezifikation einfach an einen KI-Agenten zu werfen - die Einschränkungen des Kontextfensters und das "Aufmerksamkeitsbudget" des Modells werden zu Hindernissen. Der Schlüssel liegt in der Schreibung von "klugen" Spezifikationen: Diese Dokumente können den Agenten klar leiten, bleiben innerhalb der tatsächlichen Kontextkapazität und entwickeln sich synchron mit dem Projekt. Dieser Leitfaden fasst meine besten Praktiken bei der Arbeit mit Entwicklungsschnittstellen wie Claude Code und Gemini CLI zusammen und extrahiert ein Framework für die Schreibung von Spezifikationen, um Ihren KI-Agenten fokussiert und effizient zu halten.

Wir werden fünf Prinzipien für die Schreibung von guten KI-Agenten-Spezifikationen vorstellen, wobei jedes Prinzip mit einem fettgedruckten Punkt beginnt.

1. Beginnen Sie mit der übergeordneten Vision und lassen Sie die KI die Details ausarbeiten

Starten Sie das Projekt mit einer knappen Zusammenfassung und überlassen Sie die Details der KI.

Statt von Anfang an zu überdesignen, beginnen Sie mit einer klaren Zielstellung und einigen Kernanforderungen. Stellen Sie sich dies als eine "Produktbriefing" vor, auf der Grundlage derer der Agent detailliertere Spezifikationen erstellen kann. So können Sie die Stärken der KI bei der Ergänzung von Details nutzen und gleichzeitig die Kontrolle über die Gesamtrichtung behalten. Diese Methode funktioniert sehr gut, es sei denn, Sie haben von Anfang an sehr spezifische technische Anforderungen, die erfüllt werden müssen.

Das Prinzip dahinter ist: Agenten auf der Grundlage von Large Language Models (LLM) sind sehr gut darin, Details auszufüllen, wenn sie klare Zusammenfassungsanweisungen erhalten; aber sie benötigen ein klares Aufgabenziel, um nicht abzuschweifen. Indem Sie eine kurze Gliederung oder eine Zielbeschreibung geben und die KI auffordern, eine vollständige Spezifikation zu erstellen (z. B. `spec.md`), legen Sie für den Agenten einen dauerhaften Referenzstandard fest. Bei der Zusammenarbeit mit einem Agenten ist die Vorplanung besonders wichtig - Sie können zunächst den Plan iterieren und ihn dann an den Agenten geben, um den Code zu schreiben. Diese Spezifikation wird das erste gemeinsame Produkt, das Sie mit der KI erstellen.

Praktische Methode: Starten Sie eine neue Programmier-Sitzung und geben Sie den folgenden Prompt ein:

"Sie sind ein KI-Softwareingenieur. Bitte erstellen Sie eine detaillierte Spezifikation für [Projekt X], die das Ziel, die Funktionen, die Einschränkungen und einen Schritt-für-Schritt-Implementierungsplan umfasst."

Der initiale Prompt sollte auf hoher Ebene bleiben - z. B.: "Erstellen Sie eine Webanwendung, mit der Benutzer Aufgaben verfolgen können (To-Do-Liste). Die Anwendung muss Benutzerkonten, eine Datenbank und eine einfache Benutzeroberfläche haben."

Der Agent könnte eine strukturierte Spezifikationsvorlage zurückgeben, die Folgendes umfasst: Übersicht, Funktionsliste, Technologieempfehlungen, Datenmodell usw. Anschließend wird diese Spezifikation die "einzige Quelle der Wahrheit", auf die Sie und der Agent sich beziehen können. Das AI-Team von GitHub befürwortet stark die Spezifikations-getriebene Entwicklung (Spec-driven Development), bei der "die Spezifikation die gemeinsame Quelle der Wahrheit wird... ein lebendiges, ausführbares Produkt, das sich mit dem Projekt entwickelt". Bevor Sie irgendeinen Code schreiben, überprüfen und verbessern Sie unbedingt die von der KI generierte Spezifikation, um sicherzustellen, dass sie Ihrer Vision entspricht, und korrigieren Sie alle Halluzinationen oder abweichenden Details.

Verwenden Sie die "Plan-Mode" zur Erzwingung der Vorplanung: Tools wie Claude Code bieten eine "Plan-Mode", die den Agenten auf Leseoperationen beschränkt - er kann Ihre Codebasis analysieren und einen detaillierten Plan erstellen, aber er schreibt keinen Code, bevor Sie bereit sind. Dies ist ideal für die Planungsphase: Starten Sie in der Plan-Mode, beschreiben Sie, was Sie erstellen möchten, und lassen Sie den Agenten eine Spezifikation erstellen, während er die vorhandene Codebasis untersucht. Fordern Sie ihn auf, Fragen zu Ihrem Plan zu stellen, um Unklarheiten zu beseitigen. Lassen Sie ihn den Plan aus Sicht der Architektur, der besten Praktiken, der Sicherheitsrisiken und der Teststrategien bewerten. Das Ziel ist es, den Plan zu verfeinern, bis kein Raum für Missverständnisse bleibt. Erst dann verlassen Sie die Plan-Mode und lassen den Agenten mit der Ausführung beginnen. Dieser Workflow kann das häufige Problem vermeiden, "Code zu generieren, bevor die Spezifikation festgelegt ist".

Verwenden Sie die Spezifikation als Kontext: Sobald die Spezifikation genehmigt ist, speichern Sie sie (z. B. als `SPEC.md`) und geben Sie bei Bedarf die relevanten Abschnitte an den Agenten weiter. Viele Entwickler, die leistungsstarke Modelle verwenden, tun genau das - die Spezifikationsdatei bleibt über verschiedene Sitzungen hinweg bestehen und kann die KI bei der Wiederaufnahme des Projekts unterstützen. Dies verringert das Problem der "Vergesslichkeit", das bei zu langer Dialoghistorie oder beim Neustart des Agenten auftreten kann. Dies ist ähnlich wie die Verwendung von Produktanforderungsdokumenten (PRD) im Team: Es ist eine Referenz, die jeder (Mensch oder KI) einsehen kann, um den Überblick zu behalten. Wie ein Ingenieur beobachtet hat, neigen erfahrene Personen oft dazu, "zuerst die Dokumentation zu schreiben, und das Modell kann auf der Grundlage dieser Eingaben möglicherweise eine passende Implementierung erstellen". Diese Spezifikation ist genau dieses Dokument.

Bleiben Sie zielorientiert: Die Zusammenfassungsspezifikation eines KI-Agenten sollte sich eher auf "was" und "warum" konzentrieren, als auf die triviale Details von "wie" (zumindest am Anfang). Stellen Sie sich dies wie User Stories und Akzeptanzkriterien vor: Wer sind die Benutzer? Was brauchen sie? Was sind die Erfolgsbedingungen? (Z. B.: "Benutzer können Aufgaben hinzufügen, bearbeiten und abschließen; Daten werden dauerhaft gespeichert; die Anwendung reagiert schnell und sicher"). Dies ermöglicht es der KI, die detaillierte Spezifikation auf der Grundlage der Benutzeranforderungen und -ergebnisse zu erstellen, anstatt nur auf technische To-Do-Listen. Wie in der GitHub Spec Kit-Dokumentation steht, geben Sie eine Zusammenfassungsbeschreibung des zu erstellenden Inhalts und der Gründe dafür, damit der Programmier-Agent eine detaillierte Spezifikation erstellt, die sich auf die Benutzererfahrung und die Erfolgsbedingungen konzentriert. Wenn Sie von der Gesamtvision ausgehen, können Sie verhindern, dass der Agent im anschließenden Codierungsprozess "den Wald vor lauter Bäumen nicht sieht".

2. Bauen Sie die Spezifikation wie ein professionelles PRD (oder SRS) auf

Betrachten Sie Ihre KI-Spezifikation als ein strukturiertes Dokument (PRD) mit klaren Kapiteln, anstatt als eine Ansammlung von losen Notizen.

Viele Entwickler behandeln die Agenten-Spezifikation ähnlich wie traditionelle Produktanforderungsdokumente (PRD) oder Systementwurfsdokumente - umfassend, gut organisiert und einfach für eine "einfach verständige" KI zu analysieren. Diese formelle Methode gibt dem Agenten ein zu befolgendes Blueprint und reduziert die Unklarheiten.

Sechs Kernbereiche: Eine Analyse von über 2500 Agenten-Konfigurationsdateien durch GitHub hat ein klares Muster aufgezeigt: Die effektivsten Spezifikationen umfassen sechs Bereiche. Verwenden Sie dies als Prüfcheckliste für die Vollständigkeit:

1. Befehle: Stellen Sie die ausführbaren Befehle an den Anfang - nicht nur den Namen des Tools, sondern den vollständigen Befehl mit Parametern: `npm test`, `pytest -v`, `npm run build`. Der Agent wird diese Befehle häufig referenzieren.

2. Tests: Wie werden die Tests ausgeführt, welches Framework wird verwendet, wo werden die Testdateien gespeichert und welche Codeabdeckung wird erwartet.

3. Projektstruktur: Wo sich der Quellcode befindet, wo die Tests sind und wo die Dokumentation liegt. Geben Sie es klar an: "`src/` enthält den Anwendungsquellcode, `tests/` die Unittests, `docs/` die Dokumentation."

4. Code-Stil: Ein echter Codeausschnitt, der Ihren Stil zeigt, ist besser als drei Textbeschreibungen. Dies umfasst Benennungskonventionen, Formatierungsregeln und Beispiele für gute Ausgabe.

5. Git-Workflow: Branch-Namensgebung, Commit-Nachrichtenformat, PR-Anforderungen. Wenn Sie es klar schreiben, kann der Agent es befolgen.

6. Grenzen: Dinge, die der Agent absolut nicht berühren darf - Schlüssel, Verzeichnisse von Drittanbieter-Bibliotheken, Produktionsumgebungs-Konfigurationen, bestimmte Ordner. "Keine Schlüssel committen" ist die am häufigsten auftretende nützliche Einschränkung in der GitHub-Studie.

Definieren Sie Ihre Technologie-Stack: Sagen Sie "React 18 in Kombination mit TypeScript, Vite und Tailwind CSS", anstatt nur "React-Projekt". Enthalten Sie die Versionsnummern und die Kernabhängigkeiten. Vage Spezifikationen führen zu vagen Code.

Verwenden Sie ein einheitliches Format: Klarheit geht vor. Viele Entwickler verwenden in ihrer Spezifikation Markdown-Überschriften oder sogar XML-ähnliche Tags, um die Kapitel zu trennen, da KI-Modelle strukturierte Texte besser verarbeiten können als freien Prosa. Beispielsweise können Sie Ihre Spezifikation wie folgt aufbauen:

# Projekt-Spezifikation: Die Aufgaben-App meines Teams

 ## Ziel

 * Erstellen Sie eine Webanwendung für kleine Teams, um Aufgaben zu verwalten...

 ## Technologie-Stack

 * React 18+, TypeScript, Vite, Tailwind CSS

* Node.js/Express-Backend, PostgreSQL, Prisma ORM

 ## Befehle

 * Build: `npm run build` (kompiliert TypeScript, Ausgabe in dist/)

* Test: `npm test` (führt Jest aus, muss vor Commits bestanden werden)

* Lint: `npm run lint --fix` (behebt automatisch ESLint-Fehler)

 ## Projektstruktur

 * `src/` – Anwendungsquellcode

* `tests/` – Unittests und Integrationstests

* `docs/` – Dokumentation

 ## Grenzen

 * ✅ Immer: Führen Sie Tests vor Commits aus, befolgen Sie die Benennungskonventionen

* ⚠️ Fragen Sie zuerst: Änderungen am Datenbankschema, Hinzufügen von Abhängigkeiten

* 🚫 Nie: Committen von Geheimnissen, Bearbeiten von node_modules/, Ändern der CI-Konfiguration

Eine solche Organisation hilft Ihnen nicht nur, Ihre Gedanken zu ordnen, sondern auch der KI, schnell auf Informationen zuzugreifen. Die Ingenieure von Anthropic empfehlen, die Prompts in verschiedene Kapitel zu gliedern (z. B. ``, ``, ``, `` usw.), weil dies dem Modell starke Hinweise gibt, um die Informationen zu unterscheiden. Denken Sie daran, "Einfachheit bedeutet nicht Kürze" - wenn bestimmte Details wichtig sind, scheuen Sie sich nicht, in der Spezifikation ausführlich zu schreiben, solange Sie fokussiert bleiben.

Integrieren Sie die Spezifikation in Ihre Toolchain: Betrachten Sie die Spezifikation als ein "ausführbares Produkt", das an die Versionskontrolle und CI/CD gebunden ist. Das GitHub Spec Kit verwendet einen vierstufigen Schaltplan-Workflow, der die Spezifikation zum Kern des Engineering-Prozesses macht. Anstatt die Spezifikation nach der Erstellung einfach beiseite zu legen, lassen Sie sie die Implementierung, die Prüfchecklisten und die Aufgabenzerlegung steuern. Ihre Hauptaufgabe ist die Führung; der Programmier-Agent übernimmt den größten Teil der Schreibarbeit. Jede Stufe hat bestimmte Aufgaben, und Sie sollten erst in die nächste Stufe gehen, wenn die aktuelle Aufgabe vollständig validiert ist:

1. Spezifizieren (Specify): Sie geben eine Zusammenfassungsbeschreibung des zu erstellenden Inhalts und der Gründe dafür, und der Programmier-Agent erstellt eine detaillierte Spezifikation. Dies geht nicht um den Technologie-Stack oder das Anwendungsdesign, sondern um die Benutzerreise, die Erfahrung und die Definition von Erfolg. Wer wird es nutzen? Welches Problem löst es? Wie interagieren die Benutzer damit? Stellen Sie sich dies als das Zeichnen eines Blueprints für die Benutzererfahrung vor, die Sie schaffen möchten, und lassen Sie den Programmier-Agenten die Details ausfüllen. Dies wird zu einem dynamischen Produkt, das sich mit zunehmendem Verständnis weiterentwickelt.