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

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

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

#[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:

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.