YAML-Manifeste: Wie AI-Teams strukturiert und sicher zusammenarbeiten

AI-Entwicklerteams stehen vor einer zentralen Herausforderung: Wie lassen sich Verantwortlichkeiten, Autonomie und Arbeitsabläufe so definieren, dass alle Beteiligten – menschlich wie maschinell – nachvollziehbare Grenzen und Freiheiten haben? Traditionelle Ansätze verlagern diese Fragen oft in versteckte Prompts, produktinterne Einstellungen oder informelle Absprachen. Das führt zu Unsicherheiten, insbesondere wenn Teams skalieren oder Tools wechseln.

Doch es gibt einen besseren Weg: explizite Teamdefinitionen durch YAML-Manifeste. Das Projekt NexFlow zeigt, wie solche Manifestdateien nicht nur technische Details abbilden, sondern auch als Grundlage für Code Reviews, Sicherheitsprüfungen und automatisierte Validierungen dienen können. Der Schlüssel liegt nicht in YAML selbst – sondern darin, dass diese Dateien versionierbar, prüfbar und in Repositories integrierbar sind.

Mehr als nur Konfiguration: Teamstrukturen sichtbar machen

Ein NexFlow-Team wird durch eine Sammlung von YAML-Dateien beschrieben, die gemeinsam Projekt und Team abbilden. Jede dieser Dateien folgt einem klaren Schema mit drei Kernelementen:

• specVersion: Gibt die Version der Spezifikation an, um Kompatibilität zu gewährleisten.
• kind: Definiert den Typ des Manifests (z. B. AgentSet für ein Team von Entwicklern).
• metadata: Verknüpft das Manifest mit einem Projekt und enthält zusätzliche Metadaten wie Projektname oder Verantwortliche.

Ein typisches NexFlow-Team umfasst folgende Dateien, die jeweils spezifische Aspekte klären:

• `project.yaml`: Identität des Projekts, Hauptverantwortliche, Policies und Verweis auf weitere Manifest-Dateien.
• `agents.yaml`: Rollen, Fähigkeiten, Berechtigungen und Zugriffsrechte aller menschlichen und maschinellen Teammitglieder.
• `workflow.yaml`: Arbeitsabläufe, Abhängigkeiten, Genehmigungspunkte und Ereignisse.
• `tasks.yaml`: Aufgaben, Verantwortliche, Abhängigkeiten und Akzeptanzkriterien.
• `permissions.yaml` und `capabilities.yaml`: Klare Trennung zwischen möglichen Aktionen und deren Freigabe.
• `memory.yaml` und `context.yaml`: Regeln für Datenzugriff, Speicherung und Klassifizierung.

Diese Struktur mag auf den ersten Blick überladen wirken. Doch der eigentliche Zweck ist nicht Komplexität – sondern Transparenz. Statt implizite Absprachen in Prompts zu verstecken, werden alle relevanten Fragen explizit beantwortet.

Minimalbeispiel: Ein Team aus Mensch und KI-Agent

Im Ordner examples/minimal-team demonstriert NexFlow ein vereinfachtes Team: ein menschlicher Maintainer und ein KI-Agent, der Dokumentationsänderungen vorbereitet. Die Team-Policy ist bewusst konservativ formuliert:

specVersion: "0.1"
kind: AgentSet
metadata:
  project: minimal-team
defaultAutonomy: ask_before_changes
policies:
  requireReview: true
  secretHandling: "Raw secrets are never stored in manifests."
  networkAccess: Disabled unless a task explicitly requests approval.
  destructiveActions: Human approval required.

Der KI-Agent mit der ID docs-agent hat folgende explizite Eigenschaften:

• Rolle: technical_writer (Dokumentationsspezialist).
• Berechtigungen: Kann Repository-Inhalte lesen, Dokumentation ändern und Kontext abrufen – jedoch nur nach Genehmigung.
• Autonomie: Darf Änderungen nur vorbereiten, nicht selbstständig umsetzen (autonomyLevel: ask_before_changes).

Diese Definition ist weit aussagekräftiger als ein vages Versprechen wie „der Agent ist intelligent und hilft bei Dokumentationen“. Stattdessen sind die Grenzen der Autonomie klar sichtbar. Der Agent darf lesen, analysieren und Vorschläge machen – aber nicht eigenmächtig handeln. Diese Klarheit reduziert Fehlerquellen und schafft Vertrauen.

Fähigkeiten vs. Berechtigungen: Warum die Trennung entscheidend ist

Ein häufiger Fehler in AI-Entwicklungsteams besteht darin, technische Möglichkeiten mit tatsächlichen Rechten zu verwechseln. NexFlow löst dieses Problem durch eine strikte Trennung:

1. `capabilities.yaml` definiert, welche Aktionen technisch möglich sind – z. B. das Ändern von Dokumentationsdateien (modify_documentation). Jede Fähigkeit erhält eine Risikobewertung (z. B. medium) und eine Kategorie (z. B. repository).

1. `permissions.yaml` entscheidet, wer diese Fähigkeit nutzen darf. Hier wird festgelegt, ob eine Aktion automatisch erlaubt ist, eine Genehmigung erfordert oder komplett verboten ist.

Ein Beispiel aus der Praxis:

id: modify_documentation
description: "Modify documentation files."
risk: medium
category: repository
requiresApprovalByDefault: true
auditRecommended: true

Umgesetzt wird die Berechtigung für den docs-agent so:

id: docs_write_with_review
description: "Docs agent may draft documentation changes after review."
subjects:
  - docs-agent
capabilities:
  - read_repository
  - read_context
  - modify_documentation
effect: approval_required
approvalGate: human_review
conditions:
  - "Documentation changes only."

Diese Trennung stellt sicher, dass technische Machbarkeit nicht mit Rechten verwechselt wird. Selbst wenn ein Agent technisch die Fähigkeit besitzt, ein Repository zu ändern, muss er für diese Aktion explizit eine Genehmigung einholen – und zwar nur für dokumentationsbezogene Änderungen.

Praxistauglich: Ein Blick auf ein vollständiges Softwareteam

Der Ordner examples/software-team zeigt, wie NexFlow in einem realistischen Szenario aussieht: ein Mini-Entwicklungsteam mit mehreren menschlichen Entwicklern, einem Code-Reviewer-Agenten und einem Dokumentations-Agenten. Die Workflows sind komplexer, aber die Prinzipien bleiben gleich:

• Arbeitsabläufe sind in workflow.yaml definiert, inklusive Abhängigkeiten zwischen Aufgaben.
• Genehmigungspunkte sind explizit aufgeführt – z. B. dass größere Codeänderungen eine menschliche Review erfordern.
• Kontextquellen (wie Code-Repositories oder Ticket-Systeme) werden in context.yaml deklariert, mit klaren Regeln für Lese- und Schreibzugriff.

Ein zentraler Vorteil dieses Ansatzes ist die Wiederverwendbarkeit. Die Manifestdateien können in verschiedenen Projekten eingesetzt werden, ohne dass Teams bei Null anfangen müssen. Gleichzeitig ermöglichen sie es, Policies zentral zu pflegen – etwa für Compliance-Anforderungen oder Sicherheitsstandards.

Fazit: YAML-Manifeste als Grundlage für vertrauenswürdige AI-Teams

Die Entwicklung von AI-Agenten ist längst keine Frage reiner Technologie mehr – sondern eine der Struktur und Verantwortung. NexFlow zeigt, wie YAML-Manifeste diese Verantwortung sichtbar und prüfbar machen können. Durch klare Trennung von Fähigkeiten, Berechtigungen und Arbeitsabläufen wird verhindert, dass implizite Absprachen zu Sicherheitsrisiken führen.

Für Teams, die AI-Entwicklung ernst nehmen, bieten diese Manifestdateien eine solide Basis: Sie sind versionierbar, durch Code Reviews prüfbar und lassen sich automatisiert validieren. Der nächste Schritt könnte sein, diese Ansätze in etablierte CI/CD-Pipelines zu integrieren – um AI-Agenten nicht nur zu bauen, sondern auch sicher zu betreiben.

Die Frage ist nicht mehr, ob AI-Agenten in Entwicklerteams sinnvoll sind – sondern wie sie strukturiert und kontrolliert eingesetzt werden. NexFlow liefert dafür ein vielversprechendes Framework.