Deploymentcenter/docs/AGENT_PROMPT_TEMPLATE.md

Agent-Prompt-Vorlage

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

---

## 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

{
  "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.0, 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.0

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.0

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.0
Bevor du sie anfasst: GET /api/updateservice/v1/changelog?since=2.5.0 —
zeigt nur, was seitdem dazukam. Danach die Zeile hochsetzen.

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