michaelschiemer/backups/docs-backup-20250731125004/ai/GUIDELINES-FÜR-AI-ASSISTANT.md

# Guidelines für KI-Assistenten

## Übersicht

Diese Guidelines helfen dir, dem KI-Assistenten, konsistenten, modernen und qualitativ hochwertigen PHP-Code zu generieren, der den Projektstandards entspricht.

## Verwendung in PhpStorm

Diese Guidelines können in PhpStorm so eingerichtet werden, dass sie automatisch vom KI-Assistenten verwendet werden:

1. Gehe zu **Settings/Preferences** → **Tools** → **AI Assistant** → **Custom Instructions**
2. Aktiviere **Use custom instructions**
3. Füge im Textfeld den Inhalt dieser Datei ein oder verwende einen relativen Pfad zu dieser Datei
4. Optional: Aktiviere **Apply project-specific instructions** für projektspezifische Einstellungen

Alternativ kann die Datei `.idea/aiAssistant.xml` angepasst werden, um diese Guidelines als Standardeinstellung für das Projekt zu verwenden.

## Kernprinzipien

### Abhängigkeitsvermeidung

- **Keine externen Abhängigkeiten** außer den explizit freigegebenen
- Eigene Implementierungen gegenüber externen Bibliotheken bevorzugen
- Bei Bedarf nach externen Funktionen zuerst prüfen, ob eine eigene Implementierung möglich ist
- Erlaubte Abhängigkeiten sind auf die vorhandenen Composer-Pakete beschränkt

## Architekturprinzipien

Bei der Codeanalyse und -generierung sind folgende Architekturprinzipien zu beachten:

1. **Modularer Aufbau**: Das Projekt ist in Module unter `/src/Framework/` organisiert
2. **Service-orientierte Architektur**: Funktionalitäten als unabhängige Services implementieren
3. **Dependency Injection**: Abhängigkeiten werden per Constructor Injection bereitgestellt
4. **Event-basierte Kommunikation**: Module kommunizieren über den EventDispatcher
5. **Selbstständigkeit**: Module sollten möglichst unabhängig von externen Bibliotheken sein

## Coding-Standards

### Klassen

- **IMMER `final` verwenden**, außer bei zwingenden Gründen für Vererbung
- **KEINE abstrakten Klassen** verwenden - stattdessen Interfaces und Kompositionen
- Klassen und Properties wenn möglich als `readonly` deklarieren
- Bevorzuge Interfaces für Vertragsgestaltung zwischen Komponenten

```php
// RICHTIG
final readonly class AnalyticsService implements AnalyticsInterface
{
    // ...
}

// FALSCH
abstract class BaseAnalytics
{
    // ...
}
```

### Properties und Methoden

- Private `readonly` Properties mit Typisierung
- Return-Types immer angeben
- Parameter-Types immer angeben
- Union Types und Nullable Types nutzen

```php
// RICHTIG
private readonly LoggerInterface $logger;

public function process(?int $id): Result|null
{
    // ...
}

// FALSCH
public $logger;

public function process($id)
{
    // ...
}
```

### Moderne PHP-Features

Nutze aktiv die neuesten PHP-Features:

- Constructor Property Promotion
- Match Expressions statt Switch
- Named Arguments
- Enums statt Konstanten
- Nullsafe Operator (`?->`) wo sinnvoll
- Typed Properties

## Klassenaufbau

Folgende Reihenfolge für Klassenelemente:

1. Konstanten
2. Properties
3. Constructor
4. Öffentliche Methoden
5. Private/Protected Methoden

## Service-Initialisierung

Services werden durch Initializer-Klassen registriert:

```php
#[Initializer]
final readonly class ServiceInitializer
{
    public function __construct(
        private Configuration $config,
        private DependencyInterface $dependency
    ) {}

    public function __invoke(Container $container): ServiceInterface
    {
        return new Service(
            $this->config->get('service'),
            $this->dependency
        );
    }
}
```

## Fehlerbehandlung

- Spezifische Exception-Klassen werfen
- Early Return Pattern bevorzugen
- Defensive Programmierung mit Validierung

## Testing

Bei Test-Vorschlägen Pest-Framework nutzen:

```php
test('method does something correctly', function () {
    // Arrangement
    $service = new Service($dependency);

    // Action
    $result = $service->method();

    // Assertion
    expect($result)->toBe('expected');
});
```

## Dokumentation

- PHPDoc für alle öffentlichen Methoden
- Kurze, präzise Beschreibungen
- Parameter und Return-Types in PHPDoc

## Zu vermeidende Praktiken

- Globale Zustände und statische Methoden
- Tiefe Vererbungshierarchien
- Lange, komplexe Methoden
- Magische Methoden (`__call`, etc.) ohne triftigen Grund
- Unnötige Abstraktionen

## Bei Codeanalyse und -vorschlägen

1. **Aktuellen Stil beibehalten**: Bei Vorschlägen den vorhandenen Codierungsstil beibehalten
2. **Standards berücksichtigen**: Auf Einhaltung der hier definierten Guidelines achten
3. **Modernisierung vorschlagen**: Auf Möglichkeiten zur Modernisierung hinweisen
4. **Begründen**: Bei Empfehlungen die Gründe erläutern
5. **Vollständigkeit**: Vollständige Lösungen anbieten, nicht nur Fragmente

Diese Guidelines sind als lebendiges Dokument zu betrachten, das mit der Evolution des Projekts und von PHP weiterentwickelt wird.