131 lines
3.4 KiB
Markdown
131 lines
3.4 KiB
Markdown
# components/agents/ - Agent Specs (Markdown)
|
|
|
|
Dieser Ordner enthaelt die menschenlesbaren Agent-Spezifikationen.
|
|
Jede Datei ist gleichzeitig Produktdoku und kuratierte Prompt-Quelle.
|
|
|
|
---
|
|
|
|
## Dual Model (verbindlich)
|
|
|
|
Die Agent-Runtime basiert auf zwei Quellen:
|
|
|
|
1. **Struktur in TypeScript**
|
|
- `lib/agent-definitions.ts`
|
|
- `lib/agent-run-contract.ts`
|
|
2. **Kuratierte Prompt-Segmente in Markdown**
|
|
- `components/agents/*.md`
|
|
- kompiliert via `scripts/compile-agent-docs.ts`
|
|
- konsumiert aus `lib/generated/agent-doc-segments.ts`
|
|
|
|
Wichtig:
|
|
- `convex/agents.ts` liest **kein** Raw-Markdown zur Laufzeit.
|
|
- Nur markierte `AGENT_PROMPT_SEGMENT`-Bloecke wirken prompt-relevant.
|
|
- Unmarkierter Text ist Doku fuer Menschen.
|
|
|
|
---
|
|
|
|
## Dateikonvention pro Agent
|
|
|
|
Dateiname muss dem Agent-Id-Muster folgen, z. B.:
|
|
- `campaign-distributor.md` fur `campaign-distributor`
|
|
|
|
Die Zuordnung passiert ueber `docs.markdownPath` in `lib/agent-definitions.ts`.
|
|
|
|
---
|
|
|
|
## Frontmatter (Pflicht)
|
|
|
|
Jede Agent-Datei startet mit Frontmatter:
|
|
|
|
```md
|
|
---
|
|
name: Campaign Distributor
|
|
description: ...
|
|
tools: WebFetch, WebSearch, Read, Write, Edit
|
|
color: yellow
|
|
emoji: lemon
|
|
vibe: ...
|
|
---
|
|
```
|
|
|
|
Hinweise:
|
|
- `emoji` soll als ASCII-Token gepflegt werden (z. B. `lemon`), nicht als Unicode-Zeichen.
|
|
- Frontmatter ist Referenz fuer Doku und muss mit der TS-Definition konsistent bleiben.
|
|
|
|
---
|
|
|
|
## Prompt Segment Marker (Pflicht)
|
|
|
|
Aktuell required keys:
|
|
- `role`
|
|
- `style-rules`
|
|
- `decision-framework`
|
|
- `channel-notes`
|
|
|
|
Marker-Format:
|
|
|
|
```md
|
|
<!-- AGENT_PROMPT_SEGMENT:role:start -->
|
|
Segment text
|
|
<!-- AGENT_PROMPT_SEGMENT:role:end -->
|
|
```
|
|
|
|
Regeln:
|
|
- Pro required key genau **ein** start- und **ein** end-marker.
|
|
- Kein leerer Segment-Inhalt.
|
|
- Marker-Namen muessen exakt passen.
|
|
- Segment-Reihenfolge in der Generierung folgt `AGENT_PROMPT_SEGMENT_KEYS`.
|
|
|
|
Optional zusaetzliche Segmenttypen sind erlaubt, muessen aber erst im Compiler/
|
|
Runtime-Prompting verankert werden, bevor sie Wirkung haben.
|
|
|
|
---
|
|
|
|
## Schreibregeln fuer Segmente
|
|
|
|
- Schreibe handlungsorientiert und spezifisch.
|
|
- Keine versteckte Denkspur (kein chain-of-thought).
|
|
- Keine erfundenen Produktfakten, Statistiken oder Deadlines.
|
|
- Kanalregeln konkret, aber nicht auf fragile Einzelformate ueber-engineeren.
|
|
- Immer auf strukturierten Runtime-Output ausrichten (`artifactType`, `sections`, `metadata`, `qualityChecks`, `previewText`, `body`).
|
|
|
|
---
|
|
|
|
## Nach jeder Aenderung
|
|
|
|
1. Prompt-Segmente kompilieren:
|
|
|
|
```bash
|
|
npx tsx scripts/compile-agent-docs.ts
|
|
```
|
|
|
|
2. Relevante Tests laufen lassen:
|
|
|
|
```bash
|
|
npm run test -- tests/lib/agent-doc-segments.test.ts tests/lib/agent-prompting.test.ts
|
|
```
|
|
|
|
3. Bei Struktur-Aenderungen zusaetzlich:
|
|
|
|
```bash
|
|
npm run test -- tests/lib/agent-definitions.test.ts tests/lib/agent-run-contract.test.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Wann andere Dateien mitziehen
|
|
|
|
- `lib/agent-definitions.ts` anpassen, wenn sich Inputs, Kanaele, Regeln, Blueprints oder Parameter aendern.
|
|
- `lib/agent-prompting.ts` anpassen, wenn neue Segmenttypen wirklich in Prompts einfliessen sollen.
|
|
- `scripts/compile-agent-docs.ts` anpassen, wenn required segment keys geaendert werden.
|
|
- `messages/de.json` / `messages/en.json` anpassen, wenn neue UI-Labels sichtbar werden.
|
|
|
|
---
|
|
|
|
## Anti-Patterns
|
|
|
|
- Komplettes monolithisches Prompt-Dokument ohne Marker-Struktur.
|
|
- Raw-Markdown als Runtime-Input ohne Compile-Step.
|
|
- Agent-Output nur als Freitext ohne strukturierte Deliverables.
|
|
- Segment-Inhalte, die den TS-Contracts widersprechen.
|