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:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user