Deploymentcenter/docs/AGENT_PROMPT_TEMPLATE.md

# Agent-Prompt-Vorlage

Diesen Abschnitt in `CLAUDE.md`, `AGENTS.md` oder `.cursorrules` des jeweiligen
Projekts einfügen.

---

```markdown
## Zentraler Bugtracker — Deployment Center

Erfasse unbehandelte Fehler, geplante Verbesserungen und Ideen im zentralen
Deployment Center. Basis-URL: `https://dc.mhdf.de`

### Zugang
Token steht in der Umgebungsvariable `DC_TOKEN`.
Header: `Authorization: Bearer $DC_TOKEN`

Die vollständige Schnittstellenbeschreibung liegt maschinenlesbar unter
`GET /api/openapi.json`, das Handbuch unter `/docs/`.

### Projekt bestimmen
`GET /api/bugtracker/v1/projects` liefert alle Slugs.
Bekannt: `deploymentcenter`, `myapp`, `polytrader`, `predictalytics`.
Fällt dir ein Fehler im Deployment Center selbst auf, melde ihn unter
`deploymentcenter`.

### Etwas melden
`POST /api/bugtracker/v1/report`

```json
{
  "project_slug": "myapp",
  "type": "bug",
  "title": "Kurze, aussagekräftige Zusammenfassung",
  "description": "Unter welchen Bedingungen tritt es auf?",
  "error_message": "Exakte Fehlermeldung",
  "stack_trace": "Vollständiger Stacktrace",
  "severity": "high",
  "environment": "production",
  "build_version": "v1.4.2",
  "repo_url": "https://git.example.com/me/myapp.git",
  "git_branch": "main",
  "commit_sha": "a21536f",
  "file_path": "src/Core/UserAuthService.cs",
  "line_no": 42,
  "client_ref": "eindeutige-id-dieses-laufs"
}
```

**Setze immer `client_ref`** — ein wiederholter Aufruf mit demselben Wert legt
kein Duplikat an. Gib nach Möglichkeit `file_path` und `line_no` an; das spart
dem nächsten Agenten das Parsen des Stacktrace.

Schweregrade: `idea` (Gedanke für später), `wishlist` (Backlog),
`low`, `medium`, `high`, `critical`.

### Laufzeitfehler automatisch melden
Für den globalen Exception-Handler einer Anwendung gibt es einen schlankeren
Eingang — Titel und Dringlichkeit leitet der Server ab:

`POST /api/errors/v1/report`

```json
{
  "project_slug": "myapp",
  "exception":    "PDOException",
  "message":      "Exakte Fehlermeldung",
  "stack_trace":  "...",
  "level":        "error",
  "build":        "v1.4.2",
  "environment":  "production",
  "file":         "src/Core/Service.php",
  "line":         42
}
```

`level`: `fatal` (Prozess beendet), `error` (Vorgang fehlgeschlagen, Programm
läuft weiter), `warning`.

Gleiche Fehler werden zu einer Gruppe zusammengefasst und hochgezählt;
veränderliche Anteile wie Schlüsselwerte, Adressen und Zeitstempel werden dabei
ausgeblendet. Kommt `"ignored": true` zurück, ist der Fehler als bekannt und
harmlos eingestuft — dann nicht weiter untersuchen, sondern nur zählen lassen.

### Arbeit übernehmen
Bevor du an einem Item arbeitest, übernimm es — sonst arbeiten zwei Agenten
parallel am selben Problem:

```
POST /api/bugtracker/v1/manage?action=next
Body: {"project_slug": "myapp", "limit": 1}
```

Antwortet der Server mit `409 already_claimed`, nimm das nächste Item.

### Fortschritt festhalten
```
POST /api/bugtracker/v1/manage?action=comment&id=<ID>
Body: {"comment": "Was du herausgefunden hast", "action_taken": "investigated"}
```

`action_taken`: `investigated`, `fix_proposed`, `pr_opened`, `needs_human`,
`blocked`.

### Abschließen
```
POST /api/bugtracker/v1/manage?action=resolve&id=<ID>
Body: {"resolved_in_build": "v1.4.3", "resolution_notes": "Was geändert wurde"}
```

Kommst du nicht weiter, gib das Item zurück statt es blockieren zu lassen:
```
POST /api/bugtracker/v1/manage?action=release&id=<ID>
Body: {"note": "Grund"}
```

### Release melden
Nach einem Release schließen sich Items mit passendem `resolved_in_build`
automatisch:
```
POST /api/updateservice/v1/publish
Body: {"product_slug": "myapp", "version": "1.4.3",
       "download_url": "...", "sha256_hash": "...", "git_commit": "..."}
```

### Fehlerbehandlung
Antworten haben die Form `{"status":"error","error":{"code":"…"}}`.
Reagiere auf `code`, nicht auf den Text:
- `401 unauthorized` — Token prüfen, nicht wiederholen
- `409 already_claimed` — nächstes Item nehmen
- `429 rate_limited` — Intervall verdoppeln, später erneut

### Halte fest, gegen welche Fassung du integriert hast

**Pflicht bei jeder Änderung an der Deploymentcenter-Anbindung.** Trage die
Fassung in dieser Datei ein, direkt hier:

```
Deploymentcenter-Anbindung: SDK 2.5.1, integriert am 2026-08-14
```

Der Wert steht in `DeploymentcenterSdk.Version`. Ohne ihn muss beim nächsten
Mal die gesamte Historie gelesen werden.

**Bevor du die Anbindung anfasst,** frag zuerst, was sich seitdem geändert hat:

```
GET /api/updateservice/v1/changelog?since=2.5.1
```

Die Antwort nennt nur die neueren Fassungen, dazu `action_items` (Punkte mit
Handlungsbedarf) und `breaking` (brechende Änderungen). Jeder Eintrag hat ein
Feld `action` mit dem, was konkret zu tun ist — steht dort `null`, ist nichts
zu tun.

Kommt `"count": 0` zurück, bist du auf Stand und musst gar nichts lesen.

Zum Nachschlagen für Menschen: `https://dc.mhdf.de/docs/changelog.php?since=2.5.1`

**Nach getaner Arbeit die Zeile oben auf die neue Fassung setzen.**
```

---

## Kurzfassung für knappe Prompt-Budgets

```markdown
Melde Fehler und Ideen an https://dc.mhdf.de/api/bugtracker/v1/report
(Header `Authorization: Bearer $DC_TOKEN`, JSON mit project_slug, type, title,
description, error_message, stack_trace, severity, file_path, line_no,
client_ref). Vor der Arbeit an einem Item: POST .../manage?action=next zum
Übernehmen. Danach ?action=resolve mit resolved_in_build.

Deploymentcenter-Anbindung: SDK 2.5.1
Bevor du sie anfasst: GET /api/updateservice/v1/changelog?since=2.5.1 —
zeigt nur, was seitdem dazukam. Danach die Zeile hochsetzen.

Vollständige Beschreibung: https://dc.mhdf.de/api/openapi.json
```