480 lines
14 KiB
Markdown
480 lines
14 KiB
Markdown
# System Skills
|
||
|
||
Verbindliche Regeln für die KI-gestützte Website-Generierung im Agentur-Kontext.
|
||
|
||
---
|
||
|
||
## Scope
|
||
|
||
Diese Datei definiert den **harten Rahmen** für:
|
||
- Arbeitsweise und Workflow
|
||
- Code-Qualität und Repo-Konventionen
|
||
- Source of Truth für Design und Anforderungen
|
||
- Verbote und Pflichten
|
||
|
||
**Geltungsbereich:** Gilt global für jedes Projekt. CLIENT_OVERRIDES.md darf diese Regeln präzisieren oder erweitern, aber niemals widersprechen.
|
||
|
||
---
|
||
|
||
## Read Order
|
||
|
||
Die KI muss Dateien in folgender Reihenfolge lesen:
|
||
|
||
1. `skills/SYSTEM_SKILLS.md` (diese Datei)
|
||
2. `skills/UI_GUIDELINES.md`
|
||
3. `skills/DEFINITION_OF_DONE.md`
|
||
4. `skills/CLIENT_OVERRIDES.md` (falls vorhanden)
|
||
5. `spec/ProjectSpec.json`
|
||
6. `spec/design_tokens.json`
|
||
7. `theme/stylesheet.css` / `theme/globals.css`
|
||
|
||
Bei Konflikten gilt: **Globale Skills > Client Overrides**
|
||
|
||
---
|
||
|
||
## Non-Goals
|
||
|
||
Diese Datei definiert **NICHT**:
|
||
- Konkrete Design-Vorgaben (Farben, Layouts, Abstände)
|
||
- UI-Templates oder vorgefertigte Komponenten
|
||
- Visuelle Entscheidungen jeglicher Art
|
||
- Landingpage-Strukturen oder Section-Vorlagen
|
||
|
||
Design entsteht ausschließlich aus den Projekt-Specs, nicht aus diesen Skills.
|
||
|
||
---
|
||
|
||
## Parameter-Interpreter-Modus
|
||
|
||
Das System arbeitet mit **9 strukturierten Parameter-Kategorien (A–J)**. Diese Kategorien sind in `CLIENT_OVERRIDES.md` und `master_prompt.md` vollständig aufbereitet.
|
||
|
||
### Die 9 Kategorien
|
||
|
||
| Kat. | Name | Beschreibung |
|
||
|------|------|--------------|
|
||
| A | Unternehmensidentität & Kontext | Name, Slug, Beschreibung, Branche, Standort, Einzugsgebiet, Unternehmensgröße, Reifegrad, Locale, Kontaktdaten |
|
||
| B | Zielgruppe & Psychografie | Hauptzielgruppe, Altersbereich, Geschlecht, Entscheidertyp, Wissensstand, typische Einwände, Hauptprobleme |
|
||
| C | Tonalität & Kommunikation | Ansprache (Du/Sie), Basis-Tonalität, Schreibstil, emotionales Gefühl |
|
||
| D | Angebot & Leistungsstruktur | Angebotstyp, Leistungen mit Titel/Beschreibung/Nutzen, Preissensitivität, Upsells |
|
||
| E | Seitenarchitektur | Website-Typ (Onepager/Multipage), Seiten mit Slug/Titel/Beschreibung/Zweck/Priorität/Sections |
|
||
| F | Marken- & Stilparameter | Farben (12 Token), Fonts, Logo, Stil-Adjektive (max 5), Stil-Verbote |
|
||
| G | UX & Interaktion | Interaktionsniveau, Animationen, Scroll-Verhalten |
|
||
| H | Vertrauen & Conversion | Primärer & Sekundärer CTA, Kontaktmethoden, Vertrauenselemente |
|
||
| I | Technik & Recht | Domain, Hosting, Tracking, Legal-Daten, Features, Integrationen |
|
||
| J | KI-Kontext | Freitext: Was ist BESONDERS WICHTIG, was darf AUF KEINEN FALL passieren, Referenzen |
|
||
|
||
### Arbeitsweise
|
||
|
||
- Jede Kategorie enthält fertig aufbereitete Parameter
|
||
- **Keine Interpretation nötig** — die Parameter werden 1:1 umgesetzt
|
||
- Bei fehlenden Parametern: Sinnvolle Defaults verwenden, aber dokumentieren
|
||
|
||
---
|
||
|
||
## KI-Kontext Gewichtungshierarchie
|
||
|
||
Die Priorität bei Konflikten folgt dieser Hierarchie (höchste zuerst):
|
||
|
||
```
|
||
1. SYSTEM_SKILLS.md
|
||
2. UI_GUIDELINES.md
|
||
3. DEFINITION_OF_DONE.md
|
||
4. KI-KONTEXT (Kategorie J)
|
||
5. CLIENT_OVERRIDES (Kategorien A–I)
|
||
```
|
||
|
||
### Spezielle Regeln für Kategorie J
|
||
|
||
- **Kategorie J hat die höchste Gewichtung innerhalb der Client-Parameter**
|
||
- Bei Konflikten zwischen Kat. J und Kat. A–I: **Kat. J gewinnt**
|
||
- Bei Konflikten zwischen Kat. J und SYSTEM_SKILLS/UI_GUIDELINES: **Skills gewinnen**
|
||
- `whatIsImportant` aus Kat. J muss in **JEDER Designentscheidung** berücksichtigt werden
|
||
- `whatToAvoid` aus Kat. J sind **harte Verbote** — keine Ausnahmen
|
||
|
||
### Beispiel
|
||
|
||
Wenn Kat. J sagt "Keine Animationen" und Kat. G sagt "Interaktionsniveau: dynamisch", dann gilt: **Keine Animationen**.
|
||
|
||
---
|
||
|
||
## Seiten-Zweck-System
|
||
|
||
Jede Seite in Kat. E hat einen definierten `purpose` und eine `priority`.
|
||
|
||
### Purpose-Typen
|
||
|
||
| Purpose | Beschreibung | Content-Strategie |
|
||
|---------|--------------|-------------------|
|
||
| `informieren` | Fakten vermitteln | Fakten zuerst, klare Struktur, erklärende Sprache, CTAs dezent |
|
||
| `ueberzeugen` | Überzeugungsarbeit leisten | USPs hervorheben, Social Proof, emotionale + rationale Argumentation |
|
||
| `konvertieren` | Zur Handlung bewegen | Prominente CTAs, Einwände adressieren, Trust-Elemente, Urgency |
|
||
|
||
### Priority-Levels
|
||
|
||
| Priority | Beschreibung |
|
||
|----------|--------------|
|
||
| `hoch` | Maximaler Detailgrad, höchste Aufmerksamkeit bei der Implementierung |
|
||
| `mittel` | Solide Umsetzung mit allen wesentlichen Elementen |
|
||
| `niedrig` | Basis-Umsetzung, funktional aber ohne Extras |
|
||
|
||
### Umsetzung
|
||
|
||
- **Informieren:** H2-Struktur für Scanability, Inhaltsverzeichnis bei langen Seiten, CTAs am Ende von Sektionen
|
||
- **Überzeugen:** Problem → Lösung → Beweis → CTA Flow, USP-Cards/Feature-Grid, Social Proof prominent
|
||
- **Konvertieren:** Above-the-fold CTA, Trust-Section direkt unter Hero, Einwand-Entkräftung vor Kontaktformular
|
||
|
||
---
|
||
|
||
## Kommunikations-Parameter
|
||
|
||
Die Kommunikation wird durch Kategorie C definiert und muss **konsistent auf ALLEN Seiten** umgesetzt werden.
|
||
|
||
### Ansprache (address)
|
||
|
||
| Wert | Verwendung | Beispiel |
|
||
|------|------------|----------|
|
||
| `du` | Informelle Ansprache | "Schick uns eine Nachricht", "Dein Name" |
|
||
| `sie` | Formelle Ansprache | "Senden Sie uns eine Nachricht", "Ihr Name" |
|
||
|
||
**Pflicht:** Die gewählte Ansprache gilt für:
|
||
- Alle Fließtexte
|
||
- Alle Button-Labels
|
||
- Alle Formular-Labels und Placeholders
|
||
- Alle Microcopy-Elemente
|
||
- Alle CTAs
|
||
|
||
### Tonalität (baseTone)
|
||
|
||
| Wert | Beschreibung |
|
||
|------|--------------|
|
||
| `sachlich` | Neutral, faktenbasiert, nüchtern |
|
||
| `freundlich` | Warm, einladend, zugänglich |
|
||
| `beratend` | Kompetent, hilfsbereit, lösungsorientiert |
|
||
| `motivierend` | Energetisch, inspirierend, aktivierend |
|
||
| `exklusiv` | Premium, distinguiert, hochwertig |
|
||
|
||
### Schreibstil (writingStyle)
|
||
|
||
| Wert | Beschreibung |
|
||
|------|--------------|
|
||
| `kurz_praegnant` | Kurze Sätze, auf den Punkt, keine Füllwörter |
|
||
| `erklaerend` | Ausführlicher, didaktisch, schrittweise |
|
||
| `emotional` | Gefühlsbetont, storytelling, persönlich |
|
||
| `technisch` | Fachsprachlich, präzise, detailliert |
|
||
|
||
### Emotionales Gefühl (emotionalFeeling)
|
||
|
||
Beschreibt das gewünschte Gesamtgefühl der Website (z.B. "vertrauenswürdig und modern", "dynamisch und innovativ"). Muss sich im Gesamtdesign widerspiegeln.
|
||
|
||
---
|
||
|
||
## Vertrauens- & Conversion-Elemente
|
||
|
||
Kategorie H definiert, wie Vertrauen aufgebaut und Conversions erzielt werden.
|
||
|
||
### Vertrauenselemente (trustElements)
|
||
|
||
| Element | Implementierung |
|
||
|---------|-----------------|
|
||
| `bewertungen` | Google/Trustpilot-Widgets oder Zitat-Karten mit Sternebewertung |
|
||
| `zertifikate` | Logo-Leiste mit Zertifizierungen (TÜV, ISO, etc.) |
|
||
| `referenzen` | Kundenlogos oder Case-Study-Snippets |
|
||
| `community` | Mitglieder-Zahlen, Social-Media-Feeds, Follower-Counts |
|
||
|
||
### Kontaktmethoden (contactMethods)
|
||
|
||
| Methode | Implementierung |
|
||
|---------|-----------------|
|
||
| `formular` | Kontaktformular prominent auf Kontaktseite, ggf. auch in Footer |
|
||
| `telefon` | Telefonnummer im Header + sticky CTA auf Mobile |
|
||
| `buchung` | Buchungstool-Integration (z.B. Calendly-Embed) auf Kontaktseite |
|
||
|
||
### CTA-Implementierung
|
||
|
||
- **Primärer CTA:** Haupthandlungsaufforderung, prominent platziert (Hero, Header, Sticky)
|
||
- **Sekundärer CTA:** Alternative Handlung, weniger prominent aber sichtbar
|
||
|
||
---
|
||
|
||
## Interaktions-Level
|
||
|
||
Kategorie G definiert das Interaktionsniveau der Website.
|
||
|
||
### Level-Definitionen
|
||
|
||
| Level | Beschreibung | Regeln |
|
||
|-------|--------------|--------|
|
||
| `ruhig` | Maximale visuelle Ruhe | Keine Animationen, kein Parallax, statisches Layout, **framer-motion NICHT verwenden**, maximal 1 CTA pro Viewport |
|
||
| `moderat` | Ausgewogenes Layout | Dezente Fade-In Animationen, subtile Hover-Effekte, **framer-motion sparsam einsetzen**, IntersectionObserver-basierte Reveals |
|
||
| `dynamisch` | Lebendige Interaktion | Scroll-Animationen, Parallax erlaubt, Micro-Interactions, **framer-motion aktiv eingesetzt**, Sticky CTAs |
|
||
|
||
### Animations-Einstellung (animations)
|
||
|
||
| Wert | Beschreibung |
|
||
|------|--------------|
|
||
| `keine` | Absolut keine Animationen, auch keine Hover-Transitions |
|
||
| `dezent` | Nur subtile Transitions (opacity, transform), max. 300ms |
|
||
| `praesent` | Auffälligere Animationen, Scroll-triggered, Stagger-Effekte |
|
||
|
||
### Scroll-Verhalten (scrollBehavior)
|
||
|
||
| Wert | CSS-Umsetzung |
|
||
|------|---------------|
|
||
| `normal` | `scroll-behavior: auto` |
|
||
| `smooth` | `scroll-behavior: smooth` (auf `html` Element) |
|
||
|
||
---
|
||
|
||
## Integrationen
|
||
|
||
Kategorie I definiert technische Integrationen.
|
||
|
||
### Newsletter
|
||
|
||
Wenn `newsletter: true`:
|
||
- Newsletter-Signup-Formular im Footer
|
||
- Dedizierte Section auf der Startseite (optional)
|
||
- Platzhalter für Newsletter-Provider (Mailchimp, etc.)
|
||
|
||
### Buchungstool
|
||
|
||
Wenn `bookingTool` gesetzt:
|
||
- Als iframe/embed auf der Kontaktseite einbinden
|
||
- Platzhalter-Embed wenn kein konkreter Anbieter angegeben:
|
||
```html
|
||
<!-- TODO: Buchungstool-Integration hier einfügen -->
|
||
<div class="booking-placeholder">Buchungstool wird hier eingebunden</div>
|
||
```
|
||
|
||
### Externe Integrationen
|
||
|
||
Externe Integrationen als Platzhalter-Kommentare im Code markieren:
|
||
```typescript
|
||
// TODO: Integration ${name} - ${description}
|
||
```
|
||
|
||
---
|
||
|
||
## Impressum & Datenschutz
|
||
|
||
### Impressum
|
||
|
||
Legal-Daten kommen aus `spec.technical.legal.impressum` mit folgender Struktur:
|
||
|
||
```json
|
||
{
|
||
"companyName": "Firmenname GmbH",
|
||
"street": "Musterstraße 1",
|
||
"postalCode": "12345",
|
||
"city": "Musterstadt",
|
||
"country": "Deutschland",
|
||
"email": "info@example.com",
|
||
"phone": "+49 123 456789",
|
||
"vatId": "DE123456789",
|
||
"register": "HRB 12345, Amtsgericht Musterstadt"
|
||
}
|
||
```
|
||
|
||
**Pflicht:** Die KI generiert aus diesen Daten automatisch eine korrekte Impressum-Seite gemäß DACH-Recht.
|
||
|
||
### Datenschutz
|
||
|
||
Datenschutz-Seite enthält mindestens:
|
||
- Cookie-Hinweis
|
||
- Hosting-Info (aus `spec.technical.hosting`)
|
||
- Analytics-Angabe (aus `spec.technical.tracking`)
|
||
- Kontaktdaten des Verantwortlichen
|
||
- Hinweis auf Rechte der Betroffenen
|
||
|
||
---
|
||
|
||
## Research-Insights Nutzung
|
||
|
||
Die `llmResearch`-Daten im ProjectSpec enthalten wertvolle Insights.
|
||
|
||
### Verfügbare Research-Daten
|
||
|
||
| Feld | Verwendung |
|
||
|------|------------|
|
||
| `audienceAnalysis` | Bei Content-Erstellung für Kat. B berücksichtigen |
|
||
| `uxRecommendations` | Bei Layout-Entscheidungen berücksichtigen |
|
||
| `conversionStrategy` | Bei CTA-Platzierung und Funnel-Design berücksichtigen |
|
||
| `suggestedUSPs` | Auf Startseite und Überzeugungsseiten prominent platzieren |
|
||
|
||
### Umsetzung
|
||
|
||
- USPs aus `suggestedUSPs` als Feature-Cards oder Hero-Bullet-Points
|
||
- `conversionStrategy` bestimmt den Aufbau von Conversion-Seiten
|
||
- `uxRecommendations` fließen in Layout-Entscheidungen ein
|
||
|
||
---
|
||
|
||
## Source of Truth
|
||
|
||
Das Design und die Anforderungen einer Website basieren ausschließlich auf:
|
||
|
||
| Quelle | Inhalt |
|
||
|--------|--------|
|
||
| `spec/ProjectSpec.json` | Projektanforderungen, Ziele, Inhalte |
|
||
| `spec/design_tokens.json` | Farben, Typografie, Spacing-System |
|
||
| `theme/stylesheet.css` | Projektspezifische Styles |
|
||
| `theme/globals.css` | Globale CSS-Variablen und Resets |
|
||
|
||
**Regel:** Keine Design-Entscheidung ohne Grundlage in diesen Quellen.
|
||
|
||
---
|
||
|
||
## Verbote
|
||
|
||
### Absolut verboten:
|
||
- **KEINE** Templates oder vorgefertigten Layouts
|
||
- **KEINE** Copy-Paste-Strukturen aus anderen Projekten
|
||
- **KEINE** Boilerplate-Landingpages
|
||
- **KEINE** Standard-Hero/Feature/CTA-Sections ohne Spec-Grundlage
|
||
- **KEINE** eigenmächtigen Design-Entscheidungen
|
||
- **KEINE** hardcodierten Farben, Größen oder Abstände
|
||
- **KEINE** UI-Libraries (shadcn, MUI, Chakra, Radix, etc.)
|
||
- **KEINE** CSS-Frameworks außer Tailwind (falls im Projekt konfiguriert)
|
||
- **KEINE** inline Styles (außer dynamische Werte)
|
||
- **KEINE** `!important` (außer dokumentierte Ausnahmen)
|
||
- **KEINE** Secrets im Repository (nur .env, .env.local)
|
||
|
||
### Daten und Secrets:
|
||
- Sensible Daten gehören in `.env` / `.env.local`
|
||
- `.env*` Dateien sind in `.gitignore`
|
||
- API-Keys, Passwörter, Tokens niemals committen
|
||
|
||
---
|
||
|
||
## Arbeitsprozess
|
||
|
||
Jede Aufgabe folgt diesem Ablauf:
|
||
|
||
### 1. Lesen
|
||
- `/skills` vollständig lesen
|
||
- `/spec` vollständig lesen
|
||
- Bestehenden Code verstehen
|
||
|
||
### 2. Planen
|
||
- Anforderungen analysieren
|
||
- Struktur und Komponenten konzipieren
|
||
- Abhängigkeiten identifizieren
|
||
|
||
### 3. Implementieren
|
||
- Code schreiben
|
||
- Design-Tokens verwenden
|
||
- Keine eigenmächtigen Entscheidungen
|
||
|
||
### 4. Self-Check
|
||
- `npm run build` ausführen
|
||
- Gegen Definition of Done validieren
|
||
- Responsive und Accessibility prüfen
|
||
|
||
### 5. Dokumentieren
|
||
- Änderungen in `generation_log.json` maschinell festhalten
|
||
- Keine manuellen Einträge im Log
|
||
|
||
---
|
||
|
||
## Coding-Standards
|
||
|
||
### TypeScript
|
||
|
||
- **Strict Mode** ist Pflicht
|
||
- Keine `any` Types
|
||
- Explizite Typdefinitionen für Props und State
|
||
- Keine Type-Assertions ohne Notwendigkeit
|
||
- Strict null checks beachten
|
||
|
||
```typescript
|
||
// Korrekt
|
||
interface ComponentProps {
|
||
title: string;
|
||
items: ReadonlyArray<Item>;
|
||
onSelect?: (item: Item) => void;
|
||
}
|
||
|
||
// Falsch
|
||
const props: any = { ... }
|
||
```
|
||
|
||
### React / Next.js
|
||
|
||
- Funktionale Komponenten
|
||
- Server Components wo möglich
|
||
- Client Components nur wenn nötig (`"use client"`)
|
||
- Keine unnötigen `useEffect` / `useState`
|
||
- Keine Over-Abstraktionen
|
||
|
||
### CSS
|
||
|
||
- CSS-Variablen aus `globals.css` verwenden
|
||
- Tailwind für Utility-Klassen (falls konfiguriert)
|
||
- Eigene Klassen für wiederverwendbare Patterns
|
||
- Mobile-first Breakpoints
|
||
|
||
```css
|
||
.element {
|
||
color: var(--color-foreground);
|
||
padding: var(--spacing-md);
|
||
}
|
||
```
|
||
|
||
### Allgemein
|
||
|
||
- Lesbarkeit > Cleverness
|
||
- Keine unnötigen Abstraktionen
|
||
- Keine Over-Engineering
|
||
- Konsistente Namenskonventionen
|
||
- Keine auskommentierten Code-Blöcke
|
||
- Keine `console.log` im Production-Code
|
||
|
||
---
|
||
|
||
## Pflichten
|
||
|
||
### Performance
|
||
|
||
- Core Web Vitals optimieren
|
||
- Lazy Loading für Below-the-fold-Inhalte
|
||
- Kritisches CSS inline
|
||
- JavaScript-Bundle minimieren
|
||
- Fonts optimieren (`display: swap`)
|
||
- Bildformate: WebP/AVIF bevorzugen
|
||
- Keine unnötigen Dependencies
|
||
|
||
### SEO
|
||
|
||
- Semantisches HTML (`header`, `main`, `nav`, `article`, `section`, `footer`)
|
||
- Korrekte Heading-Hierarchie (`h1` > `h2` > `h3`)
|
||
- Meta-Tags (`title`, `description`)
|
||
- Open Graph Tags
|
||
- Alt-Texte für alle Bilder
|
||
- Strukturierte Daten wo sinnvoll
|
||
|
||
### Mobile-First
|
||
|
||
- Responsive Design ist Pflicht
|
||
- Touch-Targets mindestens 44x44px
|
||
- Keine horizontalen Scrollbars
|
||
- Lesbare Schriftgrößen ohne Zoom
|
||
|
||
---
|
||
|
||
## Logging
|
||
|
||
### generation_log.json
|
||
|
||
- Nur maschinell befüllen
|
||
- Keine manuellen Einträge
|
||
- Dokumentiert: was wurde generiert, wann, welche Dateien
|
||
- Dient der Nachvollziehbarkeit
|
||
|
||
---
|
||
|
||
## Zusammenfassung
|
||
|
||
> Jede Website ist einzigartig. Design kommt aus den Specs, nicht aus dem Bauch.
|
||
> Code ist sauber, typisiert und wartbar. Build muss laufen.
|
||
> Diese Regeln sind nicht verhandelbar.
|