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

**Melde in dem Projekt, in dem die Ursache liegt — nicht in dem, in dem du
gerade arbeitest.** Ein Fehler im SDK, im `update-agent`, in der Lizenzprüfung
oder im Bugtracker gehört unter `deploymentcenter`, auch wenn er dir bei der
Arbeit an etwas anderem aufgefallen ist. Legst du ihn im eigenen Projekt ab,
liest ihn niemand, der ihn beheben könnte.

### In ein fremdes Projekt melden
Dabei gelten drei Regeln, die beim eigenen Projekt nicht greifen:

1. **`evidence` ist Pflicht**, mindestens 40 Zeichen — sonst `400
   missing_evidence`. Beantworte darin: *Was wurde beobachtet, und warum liegt
   die Ursache dort und nicht bei mir?* Der Grund für die Hürde: Du kannst
   selten sicher unterscheiden, ob das fremde Projekt kaputt ist oder ob du es
   falsch benutzt.
2. **Der Schweregrad wird auf `medium` gedeckelt.** `high` und `critical`
   vergibt die empfangende Seite — nur sie weiß, wer sonst noch betroffen ist.
   Was dringlich ist, schreibst du in die Begründung.
3. **Die Meldung landet in `triage_external`, nicht in `open`.** Such sie
   also nicht in der offenen Liste des fremden Projekts.

`reported_from` wird aus deinem Token abgeleitet und **nie** aus dem Body
übernommen — du kannst dich nicht als jemand anderes ausgeben. Meldet ein
zweites Projekt dieselbe Sache, entsteht kein neues Item; es wird als weiterer
Betroffener geführt (`affects`).

Voraussetzung ist ein **Werkbank-Token** (`owner_type: dev_agent`). Ein
Laufzeit-Token darf nicht projektübergreifend melden — es steckt in der
ausgelieferten Anwendung und ist extrahierbar.

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

Prüfaufträge erkennen

Kommt ein Item mit Status in_verification aus ?action=next, ist die Frage nicht „behebe das", sondern „trägt der Fix?". Der Fehler gilt als behoben; in resolved_in_build steht, in welcher Fassung. Gegen diese Fassung testen, dann eines von beidem:

• trägt → ?action=status mit {"status": "closed"} und einer Notiz, was geprüft wurde
• trägt nicht → den Fehler ganz normal erneut melden. Das Item wechselt von selbst auf fix_insufficient und liegt wieder in der Arbeitsschlange — es entsteht kein neues Item

Wer den Status übersieht, behebt einen bereits behobenen Fehler ein zweites Mal.

Schicke bei jeder Meldung build_version mit. Daran entscheidet der Server, ob dein Befund eine Regression ist, ein unzureichender Fix, oder ob du schlicht eine ältere Fassung prüfst als die, in der der Fix steckt. Ohne die Angabe fällt die Entscheidung im Zweifel auf den ungünstigsten Ausgang.

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"}

Die Roadmap des Projekts

Vor der Arbeit aufrufen, nicht nachher. Der Planungsstand steht im Deploymentcenter, nicht in einer Markdown-Datei:

GET /api/bugtracker/v1/roadmap.php?action=list&status=aktiv

Mit MCP-Adapter: dc_roadmap. Die Antwort beantwortet zwei Fragen, die man sich sonst falsch beantwortet: Was ist als Nächstes dran? und arbeitet schon jemand daran?

Eine ROADMAP.md im Projektverzeichnis zeigt nur eine erzeugte Kopie zwischen <!-- dc:roadmap … -->-Markern. Sie darf älter sein als der echte Stand. Was zwischen den Markern steht, niemals von Hand ändern — der nächste Lauf überschreibt es.

Ein Vorhaben auf die Roadmap heben heißt: ihm einen Themenbereich geben.

dc_roadmap_set(id: 142, epic: "A", roadmap_rank: 10, target_build: "1.5.0",
               doc_anchor: "ROADMAP.md#142-titel")

Zurückstellen nur mit Auslöser — woran erkennt man, dass „später" jetzt ist? Ohne diese Angabe wird der Aufruf abgelehnt, und das ist Absicht: Ein zurückgestelltes Vorhaben ohne Anlass ist ein vergessenes.

dc_roadmap_set(id: 147, status: "deferred",
               defer_trigger: "sobald strukturierte Logauszüge hereinkommen")

Steht etwas auf rejected oder deferred, lies erst die Begründung, die doc_anchor nennt, bevor du es erneut vorschlägst. Ein neuer Vorschlag braucht ein Argument, das dort noch nicht steht.

Was nur in einer Datei steht, ist keine eingeplante Arbeit. Die Arbeitsschlange ist ?action=next; was dort nicht auftaucht, macht niemand. Ein Punkt, der etwas werden soll, muss ein Item sein.

Erstmalige Übernahme einer vorhandenen Roadmap-Datei: Deploymentcenter/docs/ROADMAP_MIGRATION.md.

Auf der Linux-Testumgebung

Arbeitest du auf der geteilten Test-VM, benutze dc-testkit statt eigener curl-Aufrufe — es holt den DEV-Lizenzschlüssel, prüft Auslieferung und Update und meldet, was scheitert:

dc-testkit doctor      # Werkzeuge, Netz, Token, Projekt
dc-testkit license     # befristeten DEV-Schlüssel holen (wiederholbar)
dc-testkit run         # ausliefern, prüfen, aktualisieren; meldet Fehlschläge
dc-testkit projects    # welche Slugs gibt es?
dc-testkit report --type bug --title "…" --desc "…"
dc-testkit next        # auch Prüfaufträge; der Hinweis dazu steht in der Ausgabe
dc-testkit confirm <id> "was geprüft wurde"

Was dir an der Testumgebung selbst auffällt — ein fehlendes Werkzeug, eine Konvention, die nicht trägt, eine Stelle in der Anleitung, die nicht stimmt — gehört ebenfalls gemeldet, unter deploymentcenter. Die Testumgebung ist kein eigenes Projekt; Skript und Anleitung liegen in dessen Repo:

dc-testkit report --project deploymentcenter --type feature --severity wishlist \
  --title "…" --desc "…" --evidence "…"

Nimm nie einen Kundenlizenzschlüssel auf die Test-VM. Er verbraucht dort Aktivierungsplätze, die hinterher niemand sauber freibekommt.

Anleitung: Deploymentcenter/docs/TESTUMGEBUNG.md, Fremdmeldungen in §4.6.

Release melden

Beim Veröffentlichen werden Items mit passendem resolved_in_build fortgeschrieben: noch offene werden abgeschlossen, bereits als gelöst markierte gehen auf awaiting_verification — der Fix ist jetzt ausgeliefert und damit erstmals prüfbar. Sie tauchen danach als Prüfauftrag in ?action=next auf.

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.

Planungsstand: GET .../bugtracker/v1/roadmap.php?action=list&status=aktiv —
was als Nächstes dran ist und wer schon dransitzt. Eine ROADMAP.md im Repo
zeigt nur eine erzeugte Kopie; zwischen den dc:roadmap-Markern nichts von Hand
ändern.

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