Deploymentcenter BotandClaude Opus 5
8274a6c0ac
Der Unterschied zwischen "ich habe es behoben" und "der Fix eines anderen traegt" ist das Rueckgrat des Pruefverfahrens aus 2.6.1. Er stand bisher nur in der Anleitung - im Datenbestand und in den Rechten kam beides gleich an. RECHTE bugtracker:manage war ein einziger Schreib-Scope: Wer eine Nachpruefung bestaetigen durfte, durfte auch resolve, update, bulk_update und die Roadmap umschreiben. Fuer einen Pruefstand ist das zu viel - und wer einen Fix schreibt und ihn selbst abnimmt, prueft gegen die Erwartung, die er beim Schreiben hatte. bugtracker:verify deckt jetzt ab, was ein Pruefer braucht: next, claim, release, comment, confirm, report. Nicht mehr. manage schliesst es ein (IMPLIED_SCOPES), vorhandene Token verlieren nichts. "status" bleibt bewusst bei manage. Darueber liesse sich sonst jeder Zustand setzen, auch "resolved" - der Umweg um genau diese Trennung. DATENBESTAND Eine bestaetigte Nachpruefung war nicht von "jemand hat das Item zugemacht" zu unterscheiden: dc-testkit confirm setzte status=closed und schrieb den Rest in einen Kommentar. Damit war die eine Frage, fuer die das Verfahren gebaut ist, nicht beantwortbar - wurde dieses Item je gegen ein ausgeliefertes Paket geprueft? Ein Kommentartext laesst sich nicht zaehlen und nicht filtern. Migration 017 legt verified_at, verified_in_build und verified_by an. Kein eigener Status daneben: Ein bestaetigtes Item IST geschlossen, die Bestaetigung ist eine Eigenschaft dieses Abschlusses. Ein zweiter Wert waere dieselbe Falle, die 016 beim is_roadmap-Flag vermieden hat. verified_in_build steht neben resolved_in_build, weil beide verschiedene Fragen beantworten und auseinandergehen koennen - genau das ist der interessante Fall. Das eine ist die Behauptung des Behebenden, das andere die Beobachtung des Pruefenden. confirm laesst sich nur auf Items anwenden, die jemand als behoben ausgegeben hat (resolved, awaiting_verification, in_verification, fix_insufficient). Ein offenes Item zu "bestaetigen" waere ein Schliessen mit schmueckendem Beiwort - und stuende hinterher als geprueft in einer Statistik, die genau das misst. Antwort: 409 not_verifiable. MCP dc_confirm. Der Adapter hatte dc_next_task und dc_resolve, aber keinen Weg, eine Nachpruefung abzuschliessen; dc_comment kennt nur action_taken, keinen Status. Ein Pruefagent ueber MCP konnte einen Auftrag uebernehmen und dann nichts damit anfangen. 16 Werkzeuge statt 15. TESTKIT dc-testkit confirm nutzt die Aktion und schickt die gepruefte Fassung als Feld. Antwortet der Server mit 404, faellt es auf den alten Weg zurueck und sagt, dass die Fassung dann nur im Kommentar landet. Drei neue e2e-Faelle: dass confirm die gepruefte Fassung festhaelt, dass es nur dort geht, wo es etwas zu bestaetigen gibt, und dass ein verify-Token kommentieren, aber nicht beheben darf. 147 bestanden, 0 uebersprungen. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
264 lines
10 KiB
Markdown
264 lines
10 KiB
Markdown
# Ein Projekt und seinen Agenten anbinden
|
||
|
||
**Für dich, nicht für den Agenten.** Diese Datei beschreibt, was einmalig je
|
||
Projekt zu tun ist, damit ein Coding-Agent Bugtracker, Roadmap, MCP-Adapter und
|
||
die Testwege sinnvoll benutzt.
|
||
|
||
Der Agent selbst bekommt Textbausteine aus
|
||
[AGENT_PROMPT_TEMPLATE.md](AGENT_PROMPT_TEMPLATE.md) — nicht diese Datei.
|
||
|
||
Reihenfolge einhalten. Jeder Schritt setzt den vorigen voraus.
|
||
|
||
---
|
||
|
||
## Was ein Agent am Ende können soll
|
||
|
||
Damit klar ist, worauf die Schritte hinauslaufen — der Ablauf einer Sitzung:
|
||
|
||
| | Der Agent tut | Womit |
|
||
|---|---|---|
|
||
| 1 | Nachsehen, was ansteht und wer schon dransitzt | `dc_roadmap` |
|
||
| 2 | Ein Item exklusiv übernehmen | `dc_next_task` |
|
||
| 3 | Prüfen, ob es ein Prüfauftrag ist statt einer Fehlerbehebung | Status am Item |
|
||
| 4 | Arbeiten, Fortschritt festhalten | `dc_comment` |
|
||
| 5 | Was ihm nebenbei auffällt, dort melden, wo die Ursache liegt | `dc_report` |
|
||
| 6 | Abschließen oder zurückgeben | `dc_resolve` / `dc_release` |
|
||
| 7 | Ein neues Vorhaben einplanen | `dc_report` + `dc_roadmap_set` |
|
||
|
||
Was er **nicht** tun soll: eine `TODO.md` anlegen, Status in eine Markdown-Datei
|
||
schreiben, ein verworfenes Vorhaben erneut vorschlagen, ohne die Begründung
|
||
gelesen zu haben.
|
||
|
||
---
|
||
|
||
## 1. Werkbank-Token anlegen
|
||
|
||
**Erst nachsehen, ob es schon eines gibt.** Für ein angebundenes Projekt steht
|
||
es in der `.mcp.json` des Repos, unter `env.DC_TOKEN` — dort braucht der
|
||
MCP-Adapter es ohnehin. Ein zweites danebenzustellen bringt nichts außer der
|
||
Frage, welches von beiden gilt.
|
||
|
||
Im WebUI: **Token-Verwaltung → ➕ Token erstellen**.
|
||
|
||
Die Ansicht hieß bis 2.7.0 „Master-Token erstellen" — deshalb war das
|
||
Werkbank-Token dort nicht zu finden. Es entsteht an derselben Stelle, nur mit
|
||
anderem Identitätstyp.
|
||
|
||
| Feld | Wert |
|
||
|---|---|
|
||
| Typ (`owner_type`) | `dev_agent` |
|
||
| Projekt | das Projekt — **nicht leer** |
|
||
| Scopes | `bugtracker:manage`, `supervisor:read`, `watchdog:read` |
|
||
|
||
`supervisor:manage` nur, wenn der Agent Befunde auch abhaken soll.
|
||
`license:dev` und `updateservice:read` nur für die Test-VM (Schritt 5).
|
||
|
||
**Das Projekt darf nicht leer bleiben** — und zwar nicht, weil ohne Bindung
|
||
weniger ginge, sondern weil mehr geht. Der Server leitet aus ihr das
|
||
Heimatprojekt ab. Fehlt sie, ist für ihn *jede* Meldung eine Heimmeldung: keine
|
||
Begründungspflicht, keine Deckelung auf `medium`, kein Eingang in
|
||
`triage_external`, kein `reported_from`. Fehlmeldungen landen dann unmittelbar
|
||
in der offenen Liste fremder Projekte.
|
||
|
||
Kein hypothetischer Fall: Genau so ein Token lag bis zum 31.08.2026 auf der
|
||
Test-VM, `dev_agent` und ohne Projekt. Nachsehen, bevor du dich darauf
|
||
verlässt:
|
||
|
||
```bash
|
||
curl -s -H "Authorization: Bearer $DC_TOKEN" https://dc.mhdf.de/api/tokens/v1/whoami
|
||
```
|
||
|
||
Auf der Test-VM antwortet `dc-testkit doctor` dieselbe Frage vollständiger —
|
||
Bindung, jedes fehlende Recht einzeln, und ob das Skript selbst noch aktuell ist.
|
||
|
||
**Je Projekt ein eigenes Token.** Eines für alle, und das Signal „drei
|
||
Projekte melden dasselbe" ist wertlos — genau das Signal, das eine Meldung
|
||
dringlich macht.
|
||
|
||
**Kein Master-Token an einen Agenten.** Er darf melden, übernehmen und
|
||
abschließen; er darf keine Releases veröffentlichen und keine Tokens ausstellen.
|
||
|
||
---
|
||
|
||
## 2. MCP-Adapter einrichten
|
||
|
||
Der Adapter ist eine Datei ohne Abhängigkeiten. Kein `npm install`.
|
||
|
||
**Claude Code** — `.mcp.json` im Projektverzeichnis:
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"deploymentcenter": {
|
||
"command": "node",
|
||
"args": ["J:/Softwareprojekte/Deploymentcenter/mcp/deploymentcenter-mcp.mjs"],
|
||
"env": { "DC_TOKEN": "dc_..." }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**Claude Desktop** — `%APPDATA%\Claude\claude_desktop_config.json`, absoluter
|
||
Pfad, `DC_PROJECT` setzen, danach Desktop **vollständig** beenden und neu
|
||
starten. Einzelheiten in [../mcp/README.md](../mcp/README.md).
|
||
|
||
Prüfen, ohne Claude zu starten:
|
||
|
||
```bash
|
||
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | node mcp/deploymentcenter-mcp.mjs
|
||
```
|
||
|
||
Erwartet: 16 Werkzeuge (seit 2.8.0, mit `dc_confirm`). Kommt nichts, liegt es am
|
||
Pfad oder daran, dass `node` nicht im PATH steht.
|
||
|
||
---
|
||
|
||
## 3. Die Bausteine in die Projektdatei
|
||
|
||
In `CLAUDE.md` bzw. `AGENTS.md` des Projekts, aus
|
||
[AGENT_PROMPT_TEMPLATE.md](AGENT_PROMPT_TEMPLATE.md):
|
||
|
||
| Lage | Bausteine |
|
||
|---|---|
|
||
| Mit `.mcp.json` | **A** + **B** |
|
||
| Test-VM, Agent entwickelt und testet | **A** + **D** |
|
||
| Test-VM, Agent **prüft nur** | **A** + **E** |
|
||
| Ohne MCP | **A** + **C** |
|
||
|
||
**Nicht alles einkopieren.** Wo der Adapter läuft, tragen die Werkzeuge ihre
|
||
Beschreibung selbst; Baustein C wären zweihundert Zeilen, die das Modell nie
|
||
liest und die auseinanderlaufen, sobald sich die Schnittstelle ändert.
|
||
|
||
Danach einmal `dc_link_project` aufrufen — dann ist zentral beantwortbar,
|
||
welche Projekte von einem SDK-Fehler betroffen sind.
|
||
|
||
---
|
||
|
||
## 4. Die Roadmap des Projekts übernehmen
|
||
|
||
Nur, wenn es eine `ROADMAP.md`, `TODO.md` oder eine Sammlung von
|
||
Planungsdokumenten gibt. Verfahren in
|
||
[ROADMAP_MIGRATION.md](ROADMAP_MIGRATION.md), sechs Schritte.
|
||
|
||
Für Dateien im Format dieses Projekts nimmt
|
||
[../scripts/roadmap_import.py](../scripts/roadmap_import.py) die Arbeit ab:
|
||
|
||
```bash
|
||
python scripts/roadmap_import.py --lesen
|
||
```
|
||
|
||
**Immer zuerst.** Dabei fällt auf, was die Datei falsch behauptet. Bei der
|
||
Übernahme des Deploymentcenters selbst kam heraus: drei Einträge längst
|
||
erledigt, eine Kennung doppelt vergeben, ein Themenbereich nicht angelegt, und
|
||
eine erfundene Beispiel-Itemnummer im Fließtext, die ein echtes Item in einem
|
||
anderen Projekt traf.
|
||
|
||
Danach `--uebernehmen` mit `DC_TOKEN`, Datei umbauen, `--check`.
|
||
|
||
---
|
||
|
||
## 5. Nur wenn der Agent auf der Test-VM arbeitet
|
||
|
||
Zusätzlich `license:dev` und `updateservice:read` am Token, Ablage unter
|
||
`~/.config/dc-testkit/`, Baustein **D** statt **B**. Siehe
|
||
[TESTUMGEBUNG.md](TESTUMGEBUNG.md) §4.2.
|
||
|
||
**Kein Kundenlizenzschlüssel auf die VM.** Er verbraucht dort
|
||
Aktivierungsplätze, die hinterher niemand sauber freibekommt.
|
||
|
||
### Wenn der Agent nur prüfen soll
|
||
|
||
Dann Baustein **E** statt **D**, und vier Dinge stehen vorher fest, nicht erst
|
||
wenn er sie braucht:
|
||
|
||
| | |
|
||
|---|---|
|
||
| SSH-Alias und Schlüssel | `testvm-<projekt>` / `~/.ssh/testvm_<projekt>` |
|
||
| Testkit-Konfiguration | `~/.config/dc-testkit/<projekt>`, Pfad **im Prompt** |
|
||
| Werkbank-Token | die `.mcp.json` des Projekts muss **auf der VM** liegen; `DC_PROJECT_DIR` zeigt darauf. Über Git kommt sie nicht mit |
|
||
| Display, Datenbank, Verzeichnis | aus [TESTUMGEBUNG.md](TESTUMGEBUNG.md) §7 — vorher nachsehen, ob die Liste stimmt |
|
||
| Node.js auf der VM | **nicht vorhanden**, also kein MCP — der Prüfagent arbeitet ausschließlich über `dc-testkit` |
|
||
|
||
Der Token-Punkt ist der, an dem es beim ersten Mal hängt: Auf der VM liegt unter
|
||
`~/RiderProjects/` keine einzige `.mcp.json`. Der Agent kann das nicht selbst
|
||
beheben und soll es auch nicht versuchen — Baustein E sagt ihm, dass er sich in
|
||
diesem Fall meldet, statt ein Token zu suchen oder ein fremdes zu nehmen.
|
||
|
||
Die Rollengrenze steht in [TESTUMGEBUNG.md](TESTUMGEBUNG.md) §4.8. Seit 2.8.0
|
||
trägt sie ein Recht: **`bugtracker:verify` statt `bugtracker:manage`** erlaubt
|
||
übernehmen, kommentieren, bestätigen und melden — aber kein `resolve`, kein
|
||
`status`, kein `bulk_update` und kein Schreiben an der Roadmap.
|
||
|
||
Das Recht verhindert den Aufruf, nicht die Absicht: Ein Agent kann trotzdem
|
||
anfangen, den Fehler selbst zu suchen und zu beheben, statt ihn zu melden.
|
||
Baustein E sagt ihm, dass er das nicht tut — er darf deshalb nicht gekürzt
|
||
werden.
|
||
|
||
---
|
||
|
||
## Was NICHT an die anderen Projekte geht
|
||
|
||
Die Testinstanz `dc-dev.mhdf.de` und `tests/e2e` gehören zum Deploymentcenter
|
||
und werden **nicht** je Projekt nachgebaut. Sie prüfen den Server; die anderen
|
||
Projekte sind dessen Kunden, nicht seine Betreiber. `testctl.php` kann Tabellen
|
||
löschen und liegt bewusst nur auf einer Instanz.
|
||
|
||
Was sich dagegen **lohnt zu übernehmen**, ist die Haltung dahinter — sie kostet
|
||
kein eigenes Testtor:
|
||
|
||
- **Ein gefundener Fehler bekommt zweierlei:** ein Item im Bugtracker und einen
|
||
Testfall, der ihn festhält.
|
||
- **Bekannte, noch offene Befunde blockieren nicht.** Der Testfall läuft mit
|
||
und ist als bekannt vermerkt — mit Item-Nummer. Ein Eintrag ohne Item ist
|
||
eine Ausrede, kein Befund. Vorbild:
|
||
[../tests/e2e/bekannte_befunde.json](../tests/e2e/bekannte_befunde.json).
|
||
- **Fehlende Voraussetzung heißt übersprungen, nicht rot.** Der Unterschied
|
||
zwischen „kaputt" und „nicht prüfbar" muss im Bericht sichtbar bleiben — und
|
||
am Rückgabewert: Ein Lauf, der mehr überspringt als prüft, ist kein
|
||
bestandener Lauf.
|
||
|
||
Wer für sein Projekt eine eigene Strecke baut, meldet Fehler des
|
||
Deploymentcenters weiterhin dorthin — mit `evidence`.
|
||
|
||
---
|
||
|
||
## Prüfen, ob es sitzt
|
||
|
||
Nach der Einrichtung diese vier Fragen an den Agenten stellen. Sie decken
|
||
genau die Stellen ab, an denen es erfahrungsgemäß hakt:
|
||
|
||
| Frage | Erwartete Reaktion |
|
||
|---|---|
|
||
| „Was steht als Nächstes an?" | ruft `dc_roadmap` auf, liest keine Datei |
|
||
| „Fang mit dem obersten an." | ruft **zuerst** `dc_next_task`, dann erst Code |
|
||
| „Lass uns X bauen" (etwas aus Abschnitt H) | sucht die Begründung und widerspricht, statt loszulegen |
|
||
| „Mir ist ein Fehler im SDK aufgefallen" | meldet unter `deploymentcenter` mit `evidence`, nicht im eigenen Projekt |
|
||
|
||
Antwortet er auf die erste Frage mit dem Inhalt einer Markdown-Datei, fehlt
|
||
Baustein A oder der Adapter läuft nicht.
|
||
|
||
**Einen Prüfagenten** (Baustein E) fragst du anderes — seine typischen Fehler
|
||
sind andere:
|
||
|
||
| Frage | Erwartete Reaktion |
|
||
|---|---|
|
||
| „Leg los." | ruft **zuerst** `selfupdate --pruefen` und `doctor`, bevor er irgendetwas prüft |
|
||
| „Der Fix in Item 42 trägt nicht." | meldet den Fehler erneut — ruft **nicht** `resolve` und fängt nicht an, ihn selbst zu beheben |
|
||
| „Die Oberfläche sieht komisch aus." | startet sein **eigenes** Display, nicht `:0` und nicht `xvfb-run -a` |
|
||
| „Melde das." | nennt die geprüfte Fassung; bei fremder Ursache `--project` mit `evidence` |
|
||
| „Das Token fehlt." | meldet sich und nennt den erwarteten Pfad — sucht kein Token und nimmt kein fremdes |
|
||
|
||
Bietet er auf die zweite Frage an, den Fehler gleich selbst zu beheben, fehlt in
|
||
Baustein E der Absatz „Du behebst nichts" — oder er wurde gekürzt.
|
||
|
||
---
|
||
|
||
## Reihenfolge über alle Projekte
|
||
|
||
1. `deploymentcenter` — bereits erledigt, das Verfahren ist einmal durchlaufen
|
||
2. Ein zweites Projekt vollständig, mit allen fünf Schritten
|
||
3. Die übrigen erst danach
|
||
|
||
Schritt 2 ist der eigentliche Test der Anleitung. Was dabei hakt, gehört als
|
||
Meldung unter `deploymentcenter` — die Anleitung ist Teil des Produkts.
|