Ein geklontes Projekt liegt unter ~/Documents/application-platform/<organisations-slug>/<projekt-slug>/ mit einem Ordner pro Repository; Symlinks auf local-configuration legen AGENTS.md, CLAUDE.md, .cursor, .claude, .codex und .vscode daneben. Öffne im Editor den Projektordner statt eines einzelnen Repositories; im Remote-Workspace ist das Layout identisch.
Anwendungen starten
Jede Anwendung startet im Root ihres Repositories mit demselben Befehl:
ap run-local
Ein Backend startet Docker-Dienste und Dev-Server, eine App Flutter Web oder den Dev-Server ihres Stacks, eine Homepage Hugo oder Astro, jeweils mit den Env-Dateien und auf festen Ports (ap ports). Bei Flutter gibst du Ziel und Gerät an, etwa ap run-local chrome; --env dev lädt die Dev-Konfiguration statt der lokalen, und der Start-Button der Plattform-Extension führt denselben Befehl aus, siehe Anwendungen starten.
Runtimes über asdf
Die Runtime-Versionen stehen pro Repository in .tool-versions; asdf verwaltet sie auf macOS und Linux, auf Windows FVM, NVM und HVM. ap bootstrap installiert sie ohne Start der Anwendung, ap doctor zeigt fehlende Werkzeuge. Installiere Runtimes nicht global am Projekt vorbei, sonst baut deine Maschine anders als die Pipeline.
Generierte und eigene Dateien
Die Plattform schreibt env/*.generated.env und .gitlab-ci.yml und überschreibt sie bei Änderungen am Projekt; deine Werte kommen in env/*.custom.env, danach startest du ap run-local neu. Ein Pre-Commit-Hook (ap git pre-commit check) aus Setup-App und clone blockiert Commits an den generierten Dateien; die Dateien im Einzelnen und gitops-configuration für Dev und Prod stehen unter Umgebungsvariablen. Passwörter, Tokens und Schlüssel verwaltet die Plattform verschlüsselt; sie gehören nicht in *.custom.env, Commits, Logs oder Chat-Antworten.
Uploads im Backend
Persistente Datei-Uploads speichert ein Backend lokal unter ./upload und im Container unter /app/upload, wohin der Server ./backend-uploads mountet; Multer, FastAPI-Upload-Handler oder Laravel Storage zeigen dorthin und nicht auf user-uploads oder /app/uploads. Dockerfiles legen den Ordner mit RUN mkdir -p upload an.
AGENTS.md als Vertrag
Die AGENTS.md aus local-configuration fasst diese Regeln zusammen und verlangt, im passenden App-Repository statt in local-configuration zu arbeiten; alle Agenten lesen sie automatisch. Eigene Regeln ergänzst du dort (Eigene Regeln für KI-Agenten); was die Pipeline nach dem Push macht, steht unter Git-Workflow und Deployment.