sportbox-reutte-2026-01-30-v1/skills/SYSTEM_SKILLS.md

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.

---

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

// 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

.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.