Deploymentcenter BotandClaude Opus 5
eeda6c911e
Aufgefallen bei der Frage, wo man ein Werkbank-Token anlegt. Drei Befunde an derselben Stelle: 1. DIE SUPERVISOR-RECHTE FEHLTEN IM FORMULAR TokenManager::KNOWN_SCOPES kennt supervisor:read, :manage und :report seit 2.6.0 - die Ankreuzliste bot sie nie an. Ein Werkbank-Token liess sich ueber die Oberflaeche also gar nicht so ausstellen, wie die Anleitung es verlangt: dc_findings, dc_finding_summary und dc_metrics im MCP-Adapter waeren mit "unauthorized" gescheitert, und der Grund waere nirgends zu sehen gewesen. 2. "ALLE RECHTE" WAR DIE VORGABE Wer ein Agenten-Token anlegte und den Haken uebersah, gab damit alles heraus - Releases veroeffentlichen und Tokens ausstellen inbegriffen. Die gefaehrlichste Auswahl gehoert nicht in die Vorgabe. Vorangekreuzt ist jetzt "Bugtracker verwalten", also der dokumentierte Normalfall; der Vollzugriff traegt eine Warnung und muss ausdruecklich gewaehlt werden. 3. DIE ANSICHT HIESS "MASTER-TOKEN ERSTELLEN" Deshalb fand niemand das Werkbank-Token: Es entsteht an genau dieser Stelle, nur mit anderem Identitaetstyp. Der Name der Ansicht versprach etwas anderes, als sie kann - und widersprach der eigenen Regel "kein Master-Token an einen Agenten". Heisst jetzt "Token erstellen", mit einem Hinweiskasten fuer den Agentenfall. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
198 lines
7.0 KiB
Markdown
198 lines
7.0 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
|
||
|
||
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).
|
||
|
||
**Je Projekt ein eigenes Token.** Aus der Projektbindung leitet der Server
|
||
`reported_from` ab. Ein Token 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: 15 Werkzeuge. 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 | **A** + **D** |
|
||
| 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.
|
||
|
||
---
|
||
|
||
## 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.
|
||
|
||
---
|
||
|
||
## 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.
|