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, structure (Hallen/Rahmen/Fachwerke), furniture oder generic
  • promptDetail: normalerweise progressive

Die Antwort enthält die Design-Session, einen kompakten Prompt-Kern, Browserfähigkeiten und das empfohlene nächste Tool. Bei einer direkten MCP-Verbindung ist dieses Tool zunächst confbuild_get_prompt_sections: Der Client lädt das verpflichtende Profil und danach nur passende Pakete wie geometry, systems oder assembly. Erst anschließend folgt er nextProjectTool.

1a. Sheet-Topologie planen

Vor Erzeugen, Klonen oder Begin-Edit ruft der Client confbuild_plan_sheet_topology auf. single-sheet ist nur für ein wirklich unteilbares Bauteil vorgesehen. Maschinen, Gebäude, Produkte, Möbel und Tragwerke mit eigenständig montierten, wiederverwendbaren, wiederholten oder gemeinsam bewegten Einheiten verwenden composite: Main Part bleibt das erste Orchestrierungs-Sheet, die Child-Sheets heißen nach ihrer Funktion und besitzen lokale Geometrie, Montagebezug und eigene Inputs. Wiederholte Baugruppen werden einmal modelliert und mehrfach über exakte SHEET: <Name>-Zeilen instanziiert. Beim Anlegen erzeugt der Server alle geplanten benannten Subsheets sofort mit.

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.

2a. Browser verbinden

Direkt nach Session-/Prompt-Setup ruft der Client confbuild_prepare_browser auf. Bei einem neuen Entwurf beweist der Aufruf mit der Design-Session zunächst irgendeinen angemeldeten confBuild-Tab oder öffnet vor der Projekterzeugung das Dashboard. Für ein aufgelöstes, erzeugtes oder geklontes Ziel führt der Client reuse, reload, navigate oder open-new mit seiner Chrome-/Browsersteuerung aus und wiederholt den Aufruf, bis connected: true die exakte Projekt-, Konfigurations- und Revisionsverbindung bestätigt. Ein anderer Projekt- oder Konfigurations-Tab sowie ein veralteter Tab mit ungespeicherten Änderungen bleiben erhalten; ohne offenen confBuild-Tab wird ein neuer Tab geöffnet. Der Server blockiert Erzeugen, Klonen, Begin-Edit, Commit und Restore ohne den passenden Nachweis; nach Erzeugen/Klonen sowie jedem Commit oder Snapshot-Restore wird die exakte Prüfung wiederholt.

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;
  • Übereinstimmung mit dem Topologieplan: Main Part zuerst, alle geplanten Children erreichbar, keine Zyklen/Orphans und vollständige Parent→Child-Parameterspalten;
  • 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_publish_checkpoint beziehungsweise confbuild_commit_edit speichert anschließend Workbook und Projekt-scriptcode 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 erfolgreiche Durchgang verlangt zusätzlich einen vollständigen Pre-Commit-Rollback-Snapshot; schlägt dessen Erstellung fehl, bleibt das gespeicherte Projekt unverändert. Mit confbuild_list_project_snapshots, confbuild_diff_revisions und confbuild_restore_project_snapshot lässt sich eine Verschlechterung einschließlich Quellcode zurückverfolgen und zurücknehmen — der Restore sichert zuerst den Vorzustand und ist dadurch selbst rückgängig machbar.

6. Renderjob starten und abholen

Nach erneuter Browser-Bestätigung startet und wartet confbuild_render_and_wait bevorzugt in einem Aufruf; alternativ startet confbuild_render_project asynchron und der Client fragt confbuild_get_render_result mit waitMs ab. Der Browser-Tab rendert standardmäßig, ohne automatischen Server-Fallback. Nur wenn der Nutzer ausdrücklich Server-Rendering verlangt, setzt der Client rendererMode: server-headless zusammen mit serverRenderingExplicitlyRequested: true; die Browser-Verbindung bleibt trotzdem Pflicht. Das Ergebnis enthält bis zu sieben geordnete, beschriftete PNG-Bilder (Ansichten default, right, front, left, back, top, bottom) plus Browser- und Szenendiagnosen, Geometrie-Audit und iterationDelta. Bei Composite-Projekten müssen subsheetCount beziehungsweise subprojectCount mindestens alle geplanten Instanzen nachweisen.

Bei mehrteiligen Modellen gibt das Ergebnis als nächsten Schritt confbuild_inspect_outputs mit exakten Output-IDs zurück. Der Client prüft dessen vier Bilder — transparenter Kontext, Isolation, automatischer Mittelschnitt und X-Ray — vor Diagnose oder Reparatur und wiederholt denselben Satz nach einer Änderung.

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 zeigt danach jedes zurückgegebene Bild in Reihenfolge in Codex/Claude an. Für jede Ansicht gibt er konkretes Feedback. Meldet presentation.omittedImageCount ausgelassene Bilder, holt er sie vor Diagnose oder Abschluss nach. 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, ein noch laufender finaler Render, ein verletzter Topologieplan oder fehlende Nested-Scene-Diagnostik verhindern den Abschluss als complete.

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 hält der Client über confbuild_prepare_browser das exakte Projekt im normalen angemeldeten Browser verbunden. Beachten Sie:

  • Der passende confBuild-Projekt-Tab übernimmt standardmäßig Remote-Renderjobs und lädt private PNGs hoch.
  • Dashboard, anderes Projekt, gleiche/veraltete Revision und „kein Tab“ werden durch die sichere Handoff-Matrix automatisch unterschieden.
  • 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 das standardmäßige promptDetail: progressive und laden Sie nur benötigte Wissenspakete; essential ist der monolithische Kompatibilitätsmodus.
  • 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