KI-Bereich: Sicherere Projektänderungen mit KI-Agenten

Dies ist eine 10-teilige Serie, die zeigt, wie Apidog das Apidog CLI, ein Befehlszeilentool für API-Tests und das API-Lifecycle-Management, entwickelt hat. Lesen Sie der Reihe nach oder springen Sie zu einem beliebigen Beitrag, der Sie interessiert:

Wenn ein Agent Projektressourcen modifiziert, sind Sicherheit und Überprüfbarkeit wichtig. AI Branch bietet eine isolierte Bearbeitungsumgebung – Änderungen gelangen erst nach menschlicher Bestätigung in den Zielbranch.

Die Sicherheitsherausforderung

Wenn KI-Agents an der API-Entwicklung und -Tests teilnehmen, können sie Projektressourcen über CLI-Befehle erstellen, aktualisieren und löschen.

Diese Macht birgt Risiken.

Wie lassen Sie Agents an realen Projekten arbeiten, ohne den Main-Branch zu gefährden?

AI Branch: Die Sicherheitsebene

AI Branch ist ein spezieller Sprint Branch-Typ, der speziell für externe KI- und CLI-Operationen entwickelt wurde.

Schlüsselkonzept:

Alle über Apidog CLI initiierten Bearbeitungsvorgänge werden standardmäßig als von KI / KI-Agents initiiert behandelt.

AI Branch stellt KI-Agents einen **isolierten Bearbeitungs-Branch** zur Verfügung. Änderungen verbleiben im AI Branch, bis ein Mensch sie überprüft und zusammenführt.

Agent nimmt Änderungen via CLI vor
        ↓
Änderungen werden im AI Branch gespeichert (isoliert)
        ↓
Benutzer überprüft Unterschiede
        ↓
Benutzer bestätigt den Ressourcenumfang
        ↓
In den Zielbranch zusammenführen (direkt oder Merge-Request)

Der Main-Branch bleibt unberührt, bis Sie zustimmen.

Warum AI Branch benötigt wird

Von KI initiierte Bearbeitungen können unvorhersehbar sein. Apidog CLI bietet eine breite Palette von Bearbeitungsmöglichkeiten – Endpunkte, Schemata, Testszenarien, Testsuiten und mehr.

AI Branch ist für diese risikoreicheren, von KI initiierten Bearbeitungsvorgänge konzipiert.

Es ermöglicht KI-Agents, **Projektressourcen innerhalb eines kontrollierten Bereichs zu bearbeiten**:

Was ist AI Branch?

AI Branch ist ein **spezieller Sprint Branch** mit spezifischen Eigenschaften:

Hauptmerkmale

Wie es funktioniert

Die normale Bearbeitung im Client durch Benutzer folgt weiterhin den Projektmitgliedsberechtigungen und Branch-Schutzregeln.

Anwendungsfälle

AI Branch ist geeignet, wenn KI an der Projektpflege teilnehmen muss, während die Branch-Isolation und menschliche Bestätigung erhalten bleiben.

Grundlegender Workflow

Ein typischer AI Branch Workflow:

┌─────────────────────────────────────────────────────────────────┐
│                     AI BRANCH WORKFLOW                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Schritt 1: AI Branch erstellen                                  │
│  ┌───────────────────────────────────────────┐                  │
│  │ apidog branch create --type ai             │                  │
│  │ --name "ai/20260312-from-main-feature"     │                  │
│  │ --from main                                │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  Schritt 2: Ressourcen importieren oder erstellen                │
│  ┌───────────────────────────────────────────┐                  │
│  │ apidog branch pick-to (bestehende importieren)    │                  │
│  │ ODER                                       │                  │
│  │ apidog endpoint create (neu erstellen)        │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  Schritt 3: KI modifiziert Ressourcen                            │
│  ┌───────────────────────────────────────────┐                  │
│  │ Agent verwendet CLI, um Endpunkte,       │                  │
│  │ Schemata, Testszenarien usw. zu aktualisieren.             │                  │
│  │ (--branch Parameter gibt AI Branch an)  │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  Schritt 4: Benutzer überprüft Unterschiede                      │
│  ┌───────────────────────────────────────────┐                  │
│  │ apidog merge-request preview              │                  │
│  │ ODER                                       │                  │
│  │ Im Apidog Client anzeigen                 │                  │
│  └───────────────────────────────────────────┘                  │
│                    ↓                                             │
│  Schritt 5: In den Zielbranch zusammenführen                     │
│  ┌───────────────────────────────────────────┐                  │
│  │ Direktes Zusammenführen (ungeschützter Branch)         │                  │
│  │ ODER                                       │                  │
│  │ Merge-Request (geschützter Branch)          │                  │
│  └───────────────────────────────────────────┘                  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Einen AI Branch erstellen

Verwenden Sie branch create --type ai:

apidog branch create \
  --project 123456 \
  --type ai \
  --name "ai/20260312-from-main-userRegister" \
  --from main

Benennungsempfehlung: ai/JJJJMMTT-von-sourceBranch-featureOderModul

Ressourcen in einem AI Branch bearbeiten

Wenn CLI Projektressourcen schreibt, verwenden Sie den `--branch`-Parameter, um in den AI Branch zu schreiben:

Empfohlener Workflow:

# 1. Schema abrufen
apidog cli-schema get endpoint-create

# 2. Vor dem Schreiben validieren
apidog cli-schema validate endpoint-create --file ./endpoint.json

# 3. In den AI Branch schreiben (nicht main)
apidog endpoint create \
  --project 123456 \
  --branch "ai/20260312-from-main-userRegister" \
  --file ./endpoint.json

Bestehende Ressourcen importieren

Um bestehende Ressourcen zu modifizieren, importieren Sie diese zuerst aus dem Quellbranch:

apidog branch pick-to \
  --project 123456 \
  --from main \
  --to "ai/20260312-from-main-userRegister" \
  --endpoint-ids 1001,1002

Dies stellt sicher, dass die KI mit der korrekten Basisversion arbeitet.

Änderungen vor dem Zusammenführen überprüfen

Vor dem Zusammenführen Unterschiede in der Vorschau anzeigen:

apidog merge-request preview \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main

Oder vollständigen Diff im Apidog Client anzeigen.

Einen AI Branch zusammenführen

Nach der Überprüfung Änderungen zusammenführen:

Direktes Zusammenführen (Ungeschützter Branch)

apidog branch merge \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main \
  --endpoint-ids 1001,1002

Merge-Request (Geschützter Branch)

apidog merge-request create \
  --project 123456 \
  --from "ai/20260312-from-main-userRegister" \
  --to main \
  --reviewer-ids 20001,20002 \
  --endpoint-ids 1001,1002

Wichtig: Zusammenführungsbefehle verarbeiten nur explizit angegebene Ressourcenlisten. Bestätigen Sie Abhängigkeiten (Verzeichnisse, Modelle, Antwortkomponenten, Tests) vor dem Zusammenführen.

Archivieren und Löschen

Nachdem Änderungen zusammengeführt oder nicht mehr benötigt werden:

# Archivieren
apidog branch archive "ai/20260312-from-main-userRegister" \
  --project 123456 --type ai

# Löschen (nach dem Archivieren)
apidog branch delete "ai/20260312-from-main-userRegister" \
  --project 123456 --type ai

Externe KI-Bearbeitungsberechtigungen

Standardmäßig schreibt CLI in den AI Branch. Dies hält von KI generierte Änderungen isoliert, bis der Benutzer sie bestätigt.

Um die direkte Bearbeitung des Main-Branches zu ermöglichen:

Project Settings → Feature Settings → AI Feature Settings → External AI Edit Permissions

Empfehlung: Behalten Sie die AI Branch Isolation aktiviert. Aktivieren Sie die direkte Bearbeitung nur, wenn Automatisierungs-Workflows dies eindeutig erfordern.

Best Practices

AI Branch im CLI + SKILL Workflow

AI Branch integriert sich natürlich in CLI + SKILL:

Jeder Schreibvorgang durchläuft AI Branch → menschliche Überprüfung → Zusammenführung.

Sicherheitszusammenfassung

Zusammen bilden diese Ebenen einen sichereren Kreislauf für Agenten-gesteuerte Projektänderungen.

Was kommt als Nächstes

Da AI Branch die Sicherheitsebene bietet, sind nun alle Teile vorhanden:

• MCP für die Tool-Verbindung (Teil 1)
• CLI + SKILL für die Workflow-Ausführung (Teile 2-5)
• Validierungsergebnisse (Teil 6)
• Praktische Workflows (Teil 7)
• CI/CD-Grundlage (Teil 8)
• AI Branch für Sicherheit (Teil 9)

Jetzt ist es Zeit für die Vision.

In Teil 10, Spec-First war gestern. Willkommen bei Skill-First., werden wir darlegen, wie sich die API-Entwicklung mit KI-Agents weiterentwickelt – und was Teams als Nächstes tun sollten.

Wichtige Erkenntnisse

• AI Branch bietet isolierte Bearbeitung für KI-/CLI-Operationen
• Änderungen wirken sich erst nach menschlicher Bestätigung auf den Main-Branch aus
• Erstellen mit branch create --type ai, Schreiben mit dem --branch-Parameter
• Bestehende Ressourcen mit branch pick-to vor der Bearbeitung importieren
• Vorschau mit merge-request preview, dann zusammenführen oder Merge-Request erstellen
• Direkte Bearbeitungsberechtigungen können den AI Branch umgehen – mit Vorsicht verwenden
• Best Practice: ein AI Branch pro Aufgabe, vor dem Schreiben validieren, vor dem Zusammenführen überprüfen

Laden Sie Apidog herunter, um APIs in einem einzigen Arbeitsbereich zu entwerfen, zu simulieren, zu testen und zu dokumentieren. Erfahren Sie mehr über das Apidog CLI für Befehlszeilen-API-Tests, CI-Automatisierung und KI-Agent-Workflows.