Apps bauen, für Agenten

Wie ein Agent eine Laze-App baut, die Personen gern nutzen: Designregeln, das Kit, Pins und Teilen, Trunk-Pushes und die Prüfung der eigenen Arbeit.

Diese Seite ist für einen KI-Agenten geschrieben, der eine Laze-App bauen oder ändern soll. Lies sie vor deinem ersten laze app create. Personen beurteilen eine App in den ersten fünf Sekunden: Sie muss fertig aussehen, dort sein, wo sie gewünscht wurde, und du musst sie selbst prüfen, bevor du sagst, dass sie bereit ist.

Der Ablauf#

1. Erstelle sie in der Unterhaltung, in der sie angefragt wurde:

   laze app create "Insights" --channel <channel>

   Die App startet leer, mit einem Ordner, der dir gehört: Baue sie von Grund auf, beginnend mit index.html, dann laze app push. --channel heftet die App als Tab dieser Unterhaltung an. Alle darin und ihre Agenten können sie öffnen und daran weiterarbeiten (Bearbeiter). Benenne die App mit Worten, die Personen lesen, nicht mit einem Slug.

   Verknüpfe das Plattform-Kit und den Client von deiner Seite:

   <link rel="stylesheet" href="/_laze/theme.css" />
   <link rel="stylesheet" href="/_laze/kit.css" />
   <script src="/_laze/laze.js"></script>

   Folien, ein Deck oder ein Vortrag sind die eine Ausnahme: Sie starten mit --template slides, der einzigen Vorlage. Ihre Dateien sind die erste Live-Version der App und du kannst sie ändern. Jede Folie ist eine Datei in slides/, in slides/deck.json der Reihe nach aufgeführt; das README.md der Vorlage erklärt, wie du Folien hinzufügst, neu sortierst und gestaltest. Das Deck hat eine Folienleiste, Tastaturnavigation, Vollbild-Präsentation sowie Schaltflächen für Export PDF und Export HTML. Baue das also nicht noch einmal. Über MCP macht create_app mit template: "slides" dasselbe, und write_app_files ändert jeweils eine Folie.

   Die Folienvorlage ist nur für ein neues Deck gedacht. Wenn eine Person Dateien sendet, die bereits eine Seite oder ein Deck sind (ein HTML-Export, eine ZIP-Datei mit index.html, eine statische Website), stelle sie unverändert bereit: Erstelle die App ohne --template, entpacke die Dateien in ihren Ordner mit index.html ganz oben, kopiere jedes Skript hinein, das sie aus einem CDN lädt, und pushe. „Verschiebe sie hierher“ oder „leg das hier ab“ mit einem Anhang bedeutet genau das: Mach es, frag nicht, was es bedeutet.

2. Eine App, die bereits existiert, kommt in eine Unterhaltung mit einem angehefteten Tab, nicht in eine Nachricht mit einem Link:

   laze app pin <app> --channel <channel>

   Mit --role editor können Mitglieder Daten ändern, aber nicht den Code. Mit --view-only können sie nur schauen. laze app pins <channel> listet die Tabs auf. Hefte nie wieder eine App an, die eine Person gelöst hat.

3. Forme die Daten in laze.app.json: eine Sammlung pro Art von Sache, mit typisierten Feldern und ein paar Startdatensätzen. Daten liegen in Datensätzen, nie im Code der Seite. Eine Seite, die ihre Zahlen, Zeilen oder Texte fest im Code hat, ist falsch: Wenn sich die Daten ändern, muss sich die App ohne Push ändern.

4. Ändere die Seite und sieh sie dir dann lokal an, bevor sie live geht (siehe Prüfe deine eigene Arbeit).

5. Pushe:

   laze app push -m "Added the pipeline board" --seed

   Jeder Push ist sofort die Live-App. Es gibt keine Entwürfe, Branches oder Pull Requests: Apps sind trunk-basiert. Schreibe die Nachricht als einfachen Satz darüber, was sich für Personen geändert hat. --seed füllt nur Sammlungen, die noch keine Datensätze haben.

6. Zurück, wenn ein Push falsch war: laze app versions, dann laze app revert <version> -m "<why>". Das ist eine neue Live-Version; kein Datensatz geht verloren. Die Git-Historie in einer App ist nur dafür da.

Wer sie öffnen kann#

Eine neue App ist eingeschränkt. Eine App, die in einer Unterhaltung angeheftet ist, lässt sich für alle dort öffnen. Ein angehefteter Tab ist also meist alles, was eine Team-App zum Teilen braucht. Teile eine App nicht nur mit der Person, die gefragt hat, wenn sie in einem Channel danach gefragt hat: Hefte sie dort an. Erweitere den Zugriff mit laze app access visibility internal|public nur, wenn du darum gebeten wirst; der Befehl sagt, wann ein Admin genehmigen muss. laze app members zeigt, wer sie jetzt öffnen kann. Prüfe das, bevor du Personen sagst, dass die App bereit ist.

Designregeln#

Beginne mit dem Thema der App, nicht mit einem Layout. Frag dich, wie jemand, dem das Thema wichtig ist, es auf ein Whiteboard zeichnen würde, und baue das: Ein Bedrohungsmodell ist eine Angriffskarte, eine Roadmap ist eine Zeitleiste, ein Budget ist ein Geldfluss, ein Prozess ist ein Diagramm. Eine Seite aus Kennzahlen-Kacheln und Aufzählungen liest sich wie ein Bericht, und genau diese App solltest du vermeiden.

Sei sehr visuell: Nutze Motion Graphics und Abläufe, wo es geht, und führe die Leute Schritt für Schritt, bis sie alles verstanden haben. Schreib nie Textwände: Wo du Worte brauchst, nimm einfache, kurze Sätze. Eine App ist dafür da, dass Menschen etwas verstehen, nicht für deinen eigenen Brain-Dump.

Das Laze-Kit kommt von der Plattform (/_laze/theme.css, /_laze/kit.css, /_laze/laze.js). Es ist ein Werkzeugkasten, kein Layout zum Ausfüllen: Nimm seine Tokens und die Steuerelemente, die du brauchst, und lege dein eigenes CSS in deiner eigenen Datei darüber. Kopiere das Kit nie in die App.

• Visuell zuerst. Mache das Bild des Themas zur App selbst: Inline-SVG, Canvas, eine Karte, eine Zeitleiste, ein Diagramm, etwas, das Personen anklicken und erkunden. Gib ihr einen eigenen Look, mit deinem eigenen Layout und Bewegung auf den Tokens des Kits.
• Eine Aufgabe pro Bildschirm. Der erste Bildschirm beantwortet die Frage, für die es die App gibt. Lege eine zweite Aufgabe auf einen Tab (lz-tabs), nicht unter die erste.
• Die richtige Form. Verwende eine Tabelle (lz-table) oder ein Board (lz-board), wenn Personen Zeilen überfliegen oder verschieben, eine Kennzahlen-Kachel (lz-stats, lz-stat-value), wenn eine Zahl der Kern ist, ein Diagramm (lz-chart) für Zahlen über die Zeit und nummerierte Schritte (lz-steps) für eine kurze Abfolge. Text mit mehr als drei Zeilen gehört in ein Dokument, nicht in eine App.
• Echte Daten. Zeige die Datensätze, die Personen wichtig sind, mit ihren echten Namen und Daten. Kein „Lorem“, „Item 1“ oder Platzhalterdiagramme. Jede Aussage auf der Seite kommt aus einem Datensatz oder einem Link.
• Schriftgrößen. Ein Seitentitel (lz-title), eine Zeile darunter (lz-lede), Abschnittstitel (lz-h2 oder lz-card-title), Fließtext. Füge keine weiteren Größen hinzu.
• Abstände. Verwende die Klassen für Seite (lz-page), Karte (lz-card lz-card-body) und Raster (lz-grid, lz-row); sie halten den Rhythmus von 12 bis 20 px. Staple keine Karten in Karten.
• Beide Themes. Farben kommen nur aus Tokens (var(--color-fg), var(--color-bg-surface), var(--color-primary), var(--color-border) und den lz-badge-*-Tönen). Eine Hex-Farbe zerstört den Dark Mode.
• Schmale Breite. Apps öffnen in einem Seitenpanel von etwa 380 px Breite. Gib Tabellenzellen data-label, damit Zeilen umbrechen, und halte Überschriften auf einer Zeile.
• Leer- und Fehlerzustände. Eine leere Liste sagt, was erscheinen wird und wie die erste Sache hinzugefügt wird. Ein fehlgeschlagener Aufruf zeigt Laze.fail(error), nie eine leere Seite.
• Status als Badges. Zeige Zustände mit lz-badge und einem Ton (-success, -warning, -danger, -info, -primary), nicht mit farbigem Text.
• Formulare bleiben aus dem Weg. Lege „Neues Element“ hinter eine Schaltfläche; die Liste ist der Hauptinhalt.

Kit-Referenz#

Skripte laden nur vom eigenen Ursprung der App: Ein CDN <script> wird abgelehnt. Kopiere also eine Bibliothek, die du brauchst, in den App-Ordner. Wenn du ein claude.ai-Artefakt oder eine andere React-Seite portierst, kompiliere ihr JSX, bevor du pushst (zum Beispiel npx esbuild app.jsx --bundle --minify --outfile=app.js), und verknüpfe die gebaute Datei. Babel im Browser funktioniert auch, lädt aber bei jedem Öffnen Megabytes.

Im Seitenskript listet, erstellt, aktualisiert und entfernt Laze.records("<collection>") Datensätze, Laze.subscribe lädt bei Änderungen neu, Laze.h baut Elemente und Laze.mount zeichnet sie.

Tastenkürzel#

Laze gibt seine eigenen Tastenkürzel aus deiner App an Laze weiter, außer deine App verarbeitet sie. So können Personen Cmd+K (Ctrl+K unter Windows und Linux) drücken, um eine App zu verlassen, ohne zuerst aus ihr herausklicken zu müssen. Weitergegeben werden Cmd+K, Cmd+[ und Cmd+], Cmd+1 bis Cmd+9, Cmd+Shift+A, Cmd+Shift+T, Cmd+Shift+M, Cmd+Shift+D, Cmd+. und Cmd+/ sowie Alt+Up und Alt+Down außerhalb von Textfeldern. Jede andere Taste bleibt in deiner App.

Wenn du eines davon für deine App behalten willst, verarbeite die Taste und rufe event.preventDefault() auf; Laze lässt sie dann in Ruhe:

document.addEventListener("keydown", (event) => {
  if ((event.metaKey || event.ctrlKey) && event.key === "k") {
    event.preventDefault();
    openSearch();
  }
});

Prüfe deine eigene Arbeit#

Sieh dir jede Änderung an, bevor du sie pushst:

laze app serve --port 4173

Das stellt deinen Ordner unter http://127.0.0.1:4173/ mit dem Plattform-Kit und den Datensätzen der Live-App bereit, schreibgeschützt. Es braucht eine Live-Version. Führe also zuerst einmal laze app push aus. Öffne es mit deinem Browser-Tool und mache Screenshots in beiden Themes und in Panelbreite, zum Beispiel:

npx -y playwright install chromium   # once
npx -y playwright screenshot --viewport-size=1100,800 http://127.0.0.1:4173/ light.png
npx -y playwright screenshot --viewport-size=1100,800 "http://127.0.0.1:4173/?theme=dark" dark.png
npx -y playwright screenshot --viewport-size=390,800 http://127.0.0.1:4173/ narrow.png

Sieh dir jedes Bild an. Behebe Text, der überläuft, Spalten, die nicht passen, Farben, die im Dark Mode verschwinden, und alles, was noch „demo“ sagt.

Bevor du die App postest:

• Sie ist dort angeheftet, wo sie angefragt wurde, und laze app members listet die Personen auf, die sie öffnen können sollen.
• Der erste Bildschirm beantwortet die Anfrage ohne Scrollen.
• Screenshots in hell, dunkel und 390 px sehen fertig aus.
• Deine Nachricht nennt den Namen der App und sagt in einer Zeile, was sie tut. Der Tab in der Unterhaltung ist der Link.

Frag, wenn du unsicher bist#

Stelle der Person eine kurze Frage, statt das Falsche zu bauen. Warte nicht auf ein „Los“ für Schritte, um die sie bereits gebeten hat: Wenn sie in diesem Channel nach einer App gefragt hat, erstelle sie dort, hefte sie an und sag Bescheid.