Agentischer Projekt-Workflow

Das Ergebnis zuerst definieren

Ein guter Auftrag beschreibt nicht nur das Objekt, sondern auch die Kriterien, anhand derer der Client es später im Browser prüfen soll.

Ziel: Parametrische Portalfräsmaschine
Abmessungen: Arbeitsraum 800 × 500 × 180 mm
Muss enthalten: Grundrahmen, Portal, X/Y/Z-Achsen, Spindel, Energieketten
Parameter: Arbeitsbreite, Arbeitslänge, Portalhöhe
Qualität: Bauteile verbunden, plausible Maßstäbe, keine unbeabsichtigten Kollisionen
Ausgabe: Privates bearbeitbares Projekt und visuelle Prüfung aus vier Ansichten

Sie müssen dieses Format nicht exakt verwenden. Es hilft dem Client aber, Anforderungen, Annahmen und Abnahmekriterien auseinanderzuhalten.

Der verpflichtende Ablauf

1. Design-Session starten

Der Client ruft zuerst confbuild_start_design_session mit Ihrer vollständigen Anfrage auf. Optional übergibt er:

  • projectReference: Projekt-ID oder URL
  • client: codex, claude oder generic
  • profile: auto, building, machine, 3dprint oder generic
  • promptDetail: normalerweise essential

Die Antwort enthält die Design-Session, das passende Prompt-Bundle, Browserfähigkeiten und das empfohlene nächste Tool. Dieser Schritt ist wichtig, weil hier auch die aktuellen Master-Prompts des Prompt-Editors an den Client gelangen.

2. Ziel auswählen

Neues Projekt

confbuild_create_project legt ein privates Projekt im Konto des angemeldeten Nutzers an.

Eigenes Projekt

confbuild_begin_edit lädt ein eigenes privates Projekt direkt in eine Edit-Session.

Öffentliche Vorlage

confbuild_clone_project oder cloneReadOnly: true erstellt eine private bearbeitbare Kopie.

Nur untersuchen

confbuild_read_project liest Metadaten und ausgewählte Sheets ohne Änderung.

Neue Projekte und Klone sollten einen stabilen idempotencyKey erhalten. Wiederholt der Client denselben Aufruf nach einem Verbindungsfehler, entsteht dadurch kein Duplikat.

3. Arbeitsmappe lesen und planen

confbuild_begin_edit liefert eine vollständige, normalisierte Arbeitsmappe und die Basisrevision. Bei großen bestehenden Projekten kann der Client vorher mit confbuild_read_project nur relevante Sheet-Namen oder begrenzte Zeilen lesen.

Beim Weiterbearbeiten sollte der Client:

  • bestehende Output-IDs und funktionsfähige Formeln erhalten;
  • unveränderte Sheets nicht unnötig ersetzen;
  • Querverweise zwischen Main Part und Sub-Sheets prüfen;
  • ein vollständig zu ersetzendes Sheet vorab vollständig lesen.

4. Änderungen lokal anwenden

confbuild_apply_sheet_patch ändert zunächst nur die temporäre Arbeitskopie der Edit-Session. Im Remote-Modus ist diese Session UID-getrennt persistent, das eigentliche Projekt bleibt aber bis zum Commit unverändert. Unterstützt werden:

  • komplette Arbeitsmappe ersetzen;
  • Sheet hinzufügen oder ersetzen;
  • Sheet löschen, umbenennen oder ein-/ausblenden;
  • einzelne Zellen setzen;
  • Zeilen ersetzen, einfügen oder löschen.

Für ein neues Modell ist replace_workbook oft sinnvoll. Für die Weiterentwicklung eines bestehenden Projekts sind upsert_sheet, set_cells und lokalisierte Zeilenoperationen risikoärmer.

5. Validieren und speichern

Vor jedem Speichern ruft der Client confbuild_validate_edit auf. Fehler müssen behoben werden; Warnungen müssen bewusst bewertet werden. Geprüft werden unter anderem:

  • eindeutige Sheet-Namen und gültige 2D-Daten;
  • JSON-/Firestore-Serialisierbarkeit;
  • INPUTID- und OUTPUTID-Marker;
  • doppelte Output-IDs;
  • Engine-Fallen-Lint: nackte Zellreferenzen ohne =, Text in Zahlspalten, aufeinanderfolgende #-Header, Zellen jenseits des Headers;
  • VALUE-Zellen, die ein gespeicherter Konfigurationsstand überdeckt (VALUE_SHADOWED_BY_CONFIGMODEL);
  • Zeilen-, Zellen-, Output- und Payload-Größe.

confbuild_commit_edit speichert anschließend atomar. Hat der Nutzer dasselbe Projekt inzwischen im Browser geändert, wird ein REVISION_CONFLICT zurückgegeben. Der Client muss dann die aktuelle Version neu lesen und seine Änderungen bewusst darauf aufsetzen. Ein erzwungenes Überschreiben ist nicht vorgesehen. Jeder Commit sichert zusätzlich einen Pre-Commit-Rollback-Snapshot; mit confbuild_list_project_snapshots und confbuild_restore_project_snapshot lässt sich ein Commit zurücknehmen, der das Modell verschlechtert hat — der Restore ist selbst revisionsgeschützt und rückgängig machbar.

6. Renderjob starten und abholen

confbuild_render_project startet asynchron. Der Client fragt confbuild_get_render_result ab — bevorzugt mit waitMs als serverseitigem Long-Poll —, bis der Status completed lautet. Erst dann erhält er bis zu vier PNG-Bilder plus Browser- und Szenendiagnosen, einschließlich des näherungsweisen Geometrie-Audits und eines iterationDelta gegenüber dem vorherigen Render.

Ein Render ist nur für eine gespeicherte Revision möglich. Solange die Edit-Session ungespeicherte Änderungen enthält, lehnt der Server den Render ab.

7. Selbst prüfen und iterieren

Der MCP-Client liest zuerst die maschinelle Evidenz — Geometrie-Funde (Kollisionspaare, losgelöste Teile, Ausreißer) und das Iterations-Delta — und betrachtet dann jedes Bild und die Diagnosen. Typische Fragen sind:

  • Ist das gewünschte Objekt sofort erkennbar?
  • Stimmen Gesamtproportionen und Einheiten?
  • Sind Baugruppen räumlich verbunden?
  • Fehlen Bauteile, Öffnungen oder funktionale Details?
  • Gibt es offensichtlich schwebende, doppelte oder kollidierende Geometrie — und bestätigt das Geometrie-Audit das?
  • Hat der letzte Patch die Szene überhaupt verändert (iterationDelta), oder muss zuerst der Datenpfad repariert werden?
  • Melden Browser oder Editor Fehler beziehungsweise nicht aufgelöste Referenzen?

Falls nötig, beginnt erneut Patch → Validieren → Speichern → Rendern → Prüfen. Ein erfolgreicher Commit allein ist noch keine visuelle Abnahme.

8. Session sauber abschließen

Mit confbuild_finish_design_session schließt der Client die temporären Sessiondaten und meldet das strukturierte Ergebnis (completionState, iterationsUsed, behobene/verbleibende Defektkategorien) als inhaltsfreie Enums. Ungespeicherte Änderungen oder ein noch laufender finaler Render verhindern den Abschluss.

Der abschließende Bericht sollte enthalten:

  • bearbeitbarer Projektlink;
  • wichtigste Änderungen und Parameter;
  • Ergebnis der deterministischen Validierung;
  • Erkenntnisse aus allen Screenshots;
  • verbleibende Annahmen oder fachliche Grenzen.

Unterstützte Beispiele:

mcp-1234567890abcdef
https://app.confbuild.com/e/mcp-1234567890abcdef
https://app.confbuild.com/editor/mcp-1234567890abcdef
https://app.confbuild.com/p/public123/config-a
https://app.confbuild.com/lib/public123

Sie können dem Client einfach schreiben:

Bearbeite dieses Projekt weiter: https://app.confbuild.com/e/PROJEKT_ID
Ersetze nicht das gesamte Modell. Ändere nur das Dach, ergänze Dachüberstände
von 450 mm und prüfe, dass Fenster und Geschosse unverändert bleiben.

Die explizite Angabe, was nicht verändert werden darf, ist bei großen Projekten besonders hilfreich.

Parallel im Browser arbeiten

Für den gehosteten MCP öffnen Sie das Projekt parallel im normalen angemeldeten Browser. Beachten Sie:

  • Der passende confBuild-Projekt-Tab übernimmt Remote-Renderjobs und lädt private PNGs hoch.
  • Browser und MCP-OAuth müssen dasselbe confBuild-Konto verwenden.
  • Lokale headed-/headless-/attached-Modi sind nur für Entwickler und CI relevant.
  • Gleichzeitiges manuelles Speichern und MCP-Speichern kann einen Revisionskonflikt auslösen; das ist ein Schutzmechanismus.

Details stehen im Browser- und Screenshot-Loop.

Kosten und Kontext klein halten

  • Verwenden Sie promptDetail: essential, solange keine Spezialregel fehlt.
  • Lesen Sie bei großen Projekten nur relevante Sheets, aber nie unvollständig vor einem vollständigen Ersatz.
  • Nutzen Sie lokalisierte Patches statt kompletter Arbeitsmappen, wenn nur wenige Bereiche betroffen sind.
  • Fordern Sie zunächst Diagnosen ohne Bilder an, wenn nur der Renderstatus geprüft werden soll.
  • Beenden Sie fertige Sessions, damit keine unnötigen Kontextobjekte im Client verbleiben.

Der Server selbst ruft kein Modell auf. Token- oder Nutzungskosten entstehen nur im verwendeten MCP-Client sowie mögliche normale Infrastrukturkosten für confBuild/Firebase.

Nächster Schritt

Lesen Sie Prompts & KI-Grenze, um den automatischen Master-Prompt-Abruf zu verstehen, oder öffnen Sie die Tool- und Sheet-Referenz für genaue Operationen.

Zurück zur Dokumentation