215 lines
5.1 KiB
Markdown
215 lines
5.1 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.
|
|
|
|
---
|
|
|
|
## 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.
|