feat(agenten): Vorlage in vier Bausteine, Anbindungsanleitung, Tooltips (#75)
VORLAGE ZERLEGT
docs/AGENT_PROMPT_TEMPLATE.md war ein Block von 300 Zeilen, den jedes Projekt
vollstaendig einkopierte - auch die, in denen der MCP-Adapter laeuft und die
Werkzeuge ihre Beschreibung selbst mitbringen. Jetzt vier Bausteine:
A Grundhaltung, gilt immer. Vier Regeln, kurz.
B Mit MCP-Adapter: die Reihenfolge, die in keiner Werkzeugbeschreibung
steht - erst nachsehen, dann uebernehmen, dann arbeiten.
C Ohne MCP: der REST-Weg, vollstaendig. Nur wo kein Adapter laeuft.
D Auf der Test-VM.
Ein Projekt mit Adapter traegt damit eine halbe Seite statt zweihundert Zeilen,
die das Modell nie liest und die auseinanderlaufen, sobald sich die
Schnittstelle aendert. Loest #75 (vormals C4).
NEU: docs/AGENTEN_ANBINDEN.md
Was einmalig je Projekt zu tun ist - fuer den Menschen, nicht fuer den Agenten:
Werkbank-Token, Adapter, welche Bausteine, Roadmap-Uebernahme, Test-VM. Dazu
zwei Abschnitte, die sonst gefehlt haetten:
- Was NICHT an die anderen Projekte geht: Testinstanz und tests/e2e gehoeren
zum Deploymentcenter und werden nicht je Projekt nachgebaut. Uebernehmen
laesst sich die Haltung dahinter - Befund bekommt Item UND Testfall,
bekannte Befunde blockieren nicht, fehlende Voraussetzung heisst
uebersprungen und nicht rot.
- Vier Pruefragen an den Agenten nach der Einrichtung. Antwortet er auf
"was steht als Naechstes an" mit dem Inhalt einer Markdown-Datei, fehlt
Baustein A oder der Adapter laeuft nicht.
WEBUI
Die Spaltenkoepfe der Bereichsuebersicht waren Zeichen ohne Erklaerung - wer
die Legende nicht gelesen hat, und das ist der Normalfall, riet was 🧊 heisst.
Jetzt title= samt Fragezeichen-Zeiger und gepunkteter Linie, damit ueberhaupt
erkennbar ist, dass da etwas zu holen ist. Auch Rang, Item, Ziel, Wer und Doku
in der Vorhabenliste, und der Fortschritt mit dem Hinweis, warum
Zurueckgestelltes und Verworfenes nicht in den Nenner zaehlt.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Deploymentcenter Bot
co-authored by
Claude Opus 5
Claude Opus 5
parent
c9bad697e5
commit
93aabfece3
@@ -0,0 +1,193 @@
|
||||
# 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 unter **Token-Verwaltung**:
|
||||
|
||||
| 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.
|
||||
Reference in New Issue
Block a user