# eve-software-factory-template einrichten — Anleitung für deinen Coding-Agenten

> **So benutzt du diese Datei:** Leg sie in dein Projektverzeichnis und sag
> deinem Agenten: *„Halte dich an eve-software-factory-template-einrichten.md."* Das funktioniert mit Claude
> Code, Codex, Cursor, Cline und allem anderen, was Dateien lesen kann.
> Wenn dein Agent von selbst eine bestimmte Datei liest, kannst du sie auch
> in `AGENTS.md` umbenennen oder den Inhalt in deine `CLAUDE.md` kopieren.

**Projekt:** [github.com/vercel-labs/eve-software-factory-template](https://github.com/vercel-labs/eve-software-factory-template) · **Stand:** 2026-08-20 · Zusammengestellt von
[localdev.ai](https://localdev.ai/)

---

## Ziel

Ein lokaler Foreman-TUI-Entwicklungsserver läuft mit `pnpm dev` und ist bereit, Aufgaben durch die vier Stationen zu verarbeiten.

## Voraussetzungen

- Node.js und pnpm installiert
- Ein Vercel-Konto mit bereits deploytem Foreman-Projekt (für `vercel link` und `vercel env pull`)
- Vercel CLI global installiert
- Das deployte Projekt hat gültige `FACTORY_REPO` und `FACTORY_LABEL` Umgebungsvariablen
- GitHub App mit Zugriff auf `FACTORY_REPO` ist installiert (sonst schlägt Deploy fehl)

## Das fragst du mich, bevor du anfängst

- Hast du bereits ein Foreman-Projekt auf Vercel deployt? (Ohne deploytes Projekt kann `vercel link` nichts verlinken.)
- Ist die Vercel CLI installiert? Falls nein: `npm i -g vercel` oder `pnpm add -g vercel` ausführen – okay?
- Hast du ein `FACTORY_REPO` im Format `owner/repo`, auf das die GitHub App Zugriff hat?
- Wo liegt das Repository? Das Material nennt `vercel link`, nicht `git clone`. Hast du das Template bereits lokal oder musst du es erst beschaffen?

## Einrichtung

### 1. Mit Vercel-Projekt verlinken

```bash
vercel link
```

**Prüfen:** `.vercel/project.json` wurde erstellt oder existiert bereits

> ⚠️ Erfordert interaktive Auswahl des Vercel-Projekts; ohne deploytes Projekt gibt es nichts zum Verlinken. Der Nutzer muss die Auswahl bestätigen.

### 2. Umgebungsvariablen ziehen

```bash
vercel env pull
```

**Prüfen:** `.env`-Datei wurde erstellt oder aktualisiert und enthält `FACTORY_REPO` und `FACTORY_LABEL`

> ⚠️ Dies sendet Daten an Vercel und erfordert gültige Vercel-Login-Session. Ohne deploytes Projekt mit gesetzten Variablen ist die Datei leer oder unvollständig.

### 3. Abhängigkeiten installieren

```bash
pnpm install
```

**Prüfen:** `node_modules`-Verzeichnis existiert und `pnpm-lock.yaml` ist konsistent

> ⚠️ Das Material nennt nur `pnpm dev`, nicht explizit `pnpm install`. Prüfe, ob `package.json` existiert und `pnpm` installiert ist.

### 4. Entwicklungsserver starten

```bash
pnpm dev
```

**Prüfen:** Prozess läuft und TUI ist interaktiv (Ausgabe zeigt Foreman/Stationen-Status oder Prompt für Aufgabeneingabe)

> ⚠️ Lokale Runs sind 'untrusted' – Änderungen an GitHub warten auf Bestätigung in der TUI. Kein automatisches Pushen ohne Zustimmung.


## Erster Test

Gib in der laufenden TUI eine Aufgabe ein, um die vier Stationen zu testen.

```python
users report the password reset email arrives twice, fix it
```

## Wenn es klemmt

| Symptom | Ursache | Lösung |
|---|---|---|
| `vercel link` findet kein Projekt | Noch kein Foreman-Projekt auf Vercel deployt | Zuerst über 'Deploy with Vercel'-Button oder `vercel --prod` deployen; `FACTORY_REPO` und GitHub App-Zugriff müssen vorher konfiguriert sein |
| `vercel env pull` liefert leere `.env` | Im deployten Projekt sind Umgebungsvariablen nicht gesetzt | Im Vercel-Dashboard unter Project Settings → Environment Variables `FACTORY_REPO` (Format: owner/repo) und `FACTORY_LABEL` (default: factory) setzen, dann erneut `vercel env pull` |
| Deploy schlägt fehl mit 'Cannot clone repository' | GitHub App hat keinen Zugriff auf `FACTORY_REPO` | In GitHub → Settings → GitHub Apps → Vercel-App Repository-Zugriff prüfen und `FACTORY_REPO` explizit hinzufügen |
| `pnpm dev` startet nicht oder wirft Fehler | Fehlende Abhängigkeiten oder falsche Node-Version | `pnpm install` wiederholen, Node-Version prüfen (Material nennt keine spezifische Version), `package.json` engines field checken |
| TUI reagiert nicht auf Aufgabeneingabe | Umgebungsvariablen fehlen oder API-Schlüssel ungültig | `.env` auf `FACTORY_REPO`, `FACTORY_LABEL` und Connector-Variablen (GITHUB_CONNECTOR, LINEAR_CONNECTOR) prüfen; bei Unsicherheit Nutzer fragen |

## Grenzen — das kann das Projekt nicht

- Kein Standalone-Deployment aus dem Template; erfordert vorheriges Vercel-Deploy
- Keine automatischen GitHub-Pushes im lokalen Modus – Änderungen warten auf manuelle Bestätigung in der TUI
- Linear-Integration und GitHub-Connector erfordern externe Dienste und entsprechende Konten
- Vercel Blob Store wird für Factory Memory genutzt – ohne Deploy keine persistente Speicherung
- Keine Information über Hardware-Anforderungen oder Kosten für Vercel-Nutzung im Material enthalten

## Regeln für dich als Agent

- Niemals Annahmen über API-Schlüssel, Connector-Werte oder Repository-Namen treffen – bei Unsicherheit den Nutzer fragen
- Keine `sudo`-Befehle oder systemweiten Installationen ohne explizite Zustimmung
- Vor jedem Schritt prüfen, ob die erwartete Datei oder das Verzeichnis existiert
- Bei `vercel`-Befehlen immer den Nutzer bestätigen lassen, da diese mit seinem Konto interagieren
- Keine Deployment-Versuche auf Vercel starten – das Template ist für lokale Entwicklung via TUI gedacht
- Wenn `.env`-Variablen fehlen, nicht raten, sondern auf `vercel env pull` oder manuelle Konfiguration verweisen

---

### Wichtig

Diese Datei wurde aus der Liesmich-Datei des Projekts vom 2026-08-20
zusammengestellt und ist keine offizielle Dokumentation. Sie ersetzt nicht den
Blick in das Repository — wenn ein Befehl hier nicht funktioniert, gilt
[die Quelle](https://github.com/vercel-labs/eve-software-factory-template), nicht diese Datei.

*Erklärvideos und Merkblätter zu Werkzeugen wie diesem:
[localdev.ai](https://localdev.ai/m/) — ohne Anmeldung.*
