feat: agenten-prompt-standard definieren + az-pruefer perfektionieren

- README: neue Sektion 'Agenten-Prompt-Standard' (Prompt-Skelett,
  Trigger-Description mit Beispielfragen in den ersten 80 Zeichen,
  Output-Vertrags-Pflicht fuer Subagents mit Belegen + Offenen Punkten,
  Sprachregel, 10k-Zeichen-Grenze, external/-Lieferweg) als weiche
  Regel (LLM-geprueft via az-pruefer, kein Guard)
- agents/az-pruefer.md: neu nach eigenem Standard — prueft Guard-Regeln
  + Prompt-Standard getrennt, eigener Output-Vertrag, Trigger-Description
- tests/fixtures/agents/demo/: schlechter Agent (guard-gueltig, 3
  Standard-Verstoesse) als Pruefgut; Demo-Lauf meldete exakt die 3
  Verstoesse

Closes beads: az-agent-defaults-74g
This commit is contained in:
m3ta-chiron
2026-09-20 19:59:16 +02:00
parent 8b492ee197
commit 8b5ab67bda
4 changed files with 164 additions and 19 deletions
+84 -2
View File
@@ -215,6 +215,83 @@ ab — auch in Kommentaren), Platzhalter in anderer Syntax als `${VAULT:…}`.
---
## Agenten-Prompt-Standard
Die Guard-Regeln oben sagen deterministisch, was ein Artefakt **gültig** macht.
Dieser Abschnitt sagt, was ein Agenten-Prompt **gut** macht — und ist bewusst
eine **weiche Regel**: Der Fleet-Guard erzwingt sie nicht. Geprüft wird vom
Prüfer-Agenten `az-pruefer` (LLM-Prüfung) — ein Verstoß bricht keinen Rollout
ab, wird aber im Prüfbericht als Mangel benannt und muss behoben oder
ausdrücklich begründet werden.
### Prompt-Skelett
Jeder Agenten-Body folgt diesem Skelett (Reihenfolge einhalten; Überschriften
dürfen sinngemäß abweichen):
```markdown
<Rollen-Eröffnung: wer du bist, wer dich ruft>
## Arbeitsweise
1. **<Schritt>** — <Anweisung mit erkennbarem Abschlusskriterium>.
## Ausgabeformat
<Output-Vertrag — für Subagents Pflicht, siehe unten>
## Grenzen
- <Was der Agent nie tut; Auth, Fleet-Verwaltung, Eskalation>
```
- **Arbeitsweise:** nummerierte Schritte, jeder mit erkennbarem
Abschlusskriterium. Gibt es einen gepflegten Skill fürs Thema — auch aus
`external/`, deren Skills via az-fleet auf die Nutzerebene ausgerollt
werden —, ist **Skill-Load der erste Schritt** („dünne Agent-Shell über
gepflegtem Skill", Muster: `az-office` + `officecli`). Inline-Wissen, das
der Skill bereits trägt, bleibt draußen.
- **Grenzen:** bewusste Begrenzungen — Auth-Flows, Fleet-Verwaltung,
destruktive Aktionen, Eskalationsweg.
### Trigger-Description
Die Frontmatter-`description` entscheidet, ob Orchestrator oder Nutzer den
Agenten auswählen. Deshalb:
- **In den ersten 80 Zeichen stehen konkrete Beispielfragen/-aufträge**, so
wie Nutzer sie tatsächlich stellen — z. B. „Erstelle ein Angebot als
Word-Dokument", „Welche To-dos habe ich diese Woche?".
- Danach Kurzform der Fähigkeiten; Rolle/Zugehörigkeit ans Ende.
Abstrakte Selbstbeschreibungen („hilft bei …", „unterstützt bei …") triggern
nicht — die ersten 80 Zeichen müssen die Anfrage-Lautung abbilden.
### Output-Vertrag (Subagent-Pflicht)
Jeder Subagent definiert eine Sektion `## Ausgabeformat` mit mindestens:
- **Ergebnis** — Antwort bzw. Arbeitsergebnis zuerst;
- **Belege** — je Behauptung/Aktion eine Fundstelle: URL, `Datei:Zeile` oder
Beleg-ID;
- **Offene Punkte** — was unklar, ungeprüft oder Annahme blieb.
Der Vertrag ist die Verifikations-Grundlage des Orchestrators: Fehlen
Belege, lässt er nachbessern. Failure-Regel: **eine Behauptung ohne Beleg ist
ein gescheiterter Auftrag** — keine abgeschlossene Arbeit.
### Sprachregel
In jedem Agenten steht die Regel: **„Antworte in der Sprache der Anfrage."**
Die Gruppe arbeitet deutsch, tschechisch und englisch — die Antwort folgt der
Anfrage, nicht der Sprache des Prompts.
### Größen-Grenze
Agenten-Prompts bleiben unter **10.000 Zeichen**. Wird ein Prompt länger,
wandert Inhalt in einen Skill, den der Agent als ersten Schritt lädt
(Progressive Disclosure). Dünner Prompt über gepflegtem Skill schlägt fetten
Inline-Prompt.
---
## Trennung Content / Mechanismus
| Zuständigkeit | Repo |
@@ -249,7 +326,7 @@ Konvention: je Artefakt-Typ ein Unterordner, darin `valid/`- und
tests/fixtures/
├── skills/valid/… skills/invalid/…
├── commands/valid/… commands/invalid/…
├── agents/valid/… agents/invalid/…
├── agents/valid/… agents/invalid/… agents/demo/…
└── mcp/valid/… mcp/invalid/…
```
@@ -257,12 +334,17 @@ tests/fixtures/
ausgeliefert** — nichts daraus in die Typ-Verzeichnisse schieben; umgekehrt
sind echte Artefakte dort fehl am Platz.
Die Exemplare unter `agents/demo/` bestehen den **Guard**, verstoßen aber
gegen den (weichen) Agenten-Prompt-Standard — sie sind Prüfgut für
`az-pruefer`, nicht für den Fleet-Guard.
---
## Beitrags-Kurzanleitung
1. Richtiges Verzeichnis anhand der Tabelle oben wählen.
2. Artefakt gemäß Guard-Regeln des Typs anlegen (Minimalbeispiel als Vorlage).
2. Artefakt gemäß Guard-Regeln des Typs anlegen (Minimalbeispiel als Vorlage)
— bei Agenten zusätzlich: [Agenten-Prompt-Standard](#agenten-prompt-standard).
3. Prüfen: erfüllt das Artefakt **alle** Pflichtpunkte der Checkliste seines Typs?
Wenn unsicher — die Checklisten sind vollständig; es braucht kein
Architektur-Wissen.