Was ich tue

Ich leite den Orchestrator beim Erstellen neuer Funktionen (kein Ändern bestehender) mit vorheriger Analyse von Wiederverwendung, Konfiguration und Kompatibilität. Im Gegensatz zu Refactorings gibt es hier keinen vorherigen Code, der erhalten werden muss: Das Design beginnt mit den Benutzeranforderungen.

Wann dieser Skill verwendet werden soll (anstelle von refactor-protocol):

Der Benutzer fordert einen Endpunkt, Service, Job, Handler, ein Ereignis oder eine Konfiguration an, die es NICHT gibt
Die Aufgabe ist reine Erstellung, keine Änderung des bestehenden Verhaltens
Das Ergebnis fügt dem Repository Dateien hinzu, ändert aber nicht die Signatur vorhandener Dateien

Wann dieser Skill NICHT verwendet werden soll (stattdessen refactor-protocol verwenden):

Ändern der Signatur eines bestehenden Dienstes
Ändern des Verhaltens eines vorhandenen Endpunkts
Umbenennen, Extrahieren oder Verschieben von Code

PHASE 0 — Strukturvalidierung (immer zuerst)

Skill project-structure laden und vollständige Validierung ausführen
Host-Typ erkennen: FUNCTIONS | WEBAPP | NUGET_LIBRARY
Je nach Ergebnis handeln:

Status	Aktion
`HARD_BLOCK`	Anhalten. Benutzer informieren.
`NUGET_LIBRARY`	Das Erstellen eines HTTP-Endpunkts ist unerwartet. Fragen: „Möchten Sie eine öffentliche Operation zur Bibliothek hinzufügen oder gibt es tatsächlich einen Host, den ich nicht erkannt habe?“
`PREGUNTA`	Fragen klären, bevor fortgefahren wird
`OK` / `WARNING`	Mit PHASE 1 fortfahren

PHASE 1 — Anforderungserfassung

Der Orchestrator leitet so viel wie möglich aus der Benutzerbeschreibung ($ARGUMENTS) ab und fragt nur nach Dingen, die nicht klar sind. Stellen Sie keine Fragen, deren Antwort bereits in der Beschreibung enthalten ist.

1.1 Name, Zweck und Art der Funktion

HTTP-Endpunkt (Function/Controller): [VERB] /pfad — Beschreibung
Domain-Service: Name des Dienstes und Verantwortung
Job/Event-Handler: Trigger + Aktion
Konfigurationsoption: Name der Option und ihr Zweck

1.2 Klassifizierung READ vs. MUTATION

Bestimmen, ob die Funktion den Zustand ändert oder nur lesend ist. Dies beeinflusst:

Wo die Response-DTOs platziert werden
Ob eine Transaktion / Idempotenz erforderlich ist
Welche Tests benötigt werden

Typ	Merkmale	Auswirkung
READ-ONLY	GET, gibt vorhandene Daten zurück, schreibt nicht	Flüchtige DTOs, minimale Tests
MUTATION	POST/PUT/DELETE, schreibt oder ändert Zustand	Erfolgs- und Fehlertests erforderlich

1.3 Erfassung der erwarteten Ein-/Ausgabe

Request: Struktur des Bodys oder der Query-Parameter
Response: Struktur des Response-Bodys, Statuscodes
Fehler: Welche Fehler auf welche Statuscodes abgebildet werden müssen

PHASE 1.5 — Wiederverwendungsanalyse (KRITISCH, nicht überspringen)

Ziel: Erkennen, ob die Funktion teilweise oder vollständig bereits existiert, bevor etwas erstellt wird.

Schritte

Vorhandene Dienste in *.Impl/ mit @explore anhand der Domäne der Funktion suchen
Kandidatenmethoden suchen, die 80 %+ des erforderlichen Verhaltens abdecken:
- Gibt es eine Methode, die die benötigten Daten bereits mit einem trivialen Filter zurückgibt?
- Gibt es eine Methode, die überladen werden könnte, um den Fall hinzuzufügen?
Ähnliche Endpunkte in *.API/ mit derselben Request/Response-Form suchen

Entscheidungsbaum

Gibt es eine Methode, die 100 % des Falls abdeckt?
└── JA → KEINE neue Methode erstellen. Nur erstellen:
        · Endpunkt (Function/Controller) in *.API/
        · Exklusives Request/Response-DTO in *.API/
        · Test der Response-Form

Gibt es eine fast ideale Methode (Filter, Paginierung, Sortierung)?
├── JA → erwägen:
│   ├── Optionalen Parameter zur vorhandenen Methode hinzufügen (mit Standardwert)
│   ├── Überladung mit spezifischerer Signatur erstellen
│   └── Erweiterungsmethode erstellen, die die vorhandene umschließt
└── NEIN → mit der Erstellung einer neuen Methode fortfahren

Gibt es einen verwandten, aber anderen Dienst (z. B. ähnliche Verantwortung)?
├── JA → Benutzer fragen: „Erweitere ich [CSXxxService] oder erstelle ich einen neuen [CSYyyService]?“
└── NEIN → neuen Dienst erstellen

Erwartete Ausgabe dieser Phase

Eine dieser drei Entscheidungen, dem Benutzer vor dem Fortfahren präsentiert:

Reine Wiederverwendung: Die Funktion wird als Wrapper einer vorhandenen Methode implementiert
Erweiterung: Überladung/Methode zu einem vorhandenen Dienst hinzufügen
Neuerstellung: Neuer Dienst und neue Methoden (begründen, warum keine Wiederverwendung möglich ist)

PHASE 1.6 — Konfigurationsanalyse (NEU)

Ziel: Erkennen, ob die Funktion konfigurierbare Parameter benötigt und, falls ja, wo diese definiert werden sollen.

Schlüsselfragen

Hat die Funktion angemessene Standardwerte ohne externe Konfiguration?
Gibt es Schwellwerte, Paginierung, Timeouts oder Flags, die pro Umgebung konfigurierbar sein sollten?
Wird eine Verbindung zu einem externen System mit URL/Schlüssel/Geheimnis hergestellt?
Werden Feature-Flags für eine schrittweise Einführung benötigt?

Entscheidungsbaum

Erfordert die Funktion eine Konfiguration?
├── NEIN → Kein IXxxOptions erstellen, AddCustomConfiguration nicht anfassen
└── JA → Fortfahren

Welche Art von Konfiguration?
├── Verbindungszeichenfolge oder Geheimnis
│   └── IConfiguration mit Namen in appsettings.json verwenden (von AddCustomConfiguration verwaltet)
├── Einfacher Wert (Schwellwert, Timeout, Flag)
│   └── IXxxOptions in *.Impl/ erstellen (Interface) + zu AddCustomConfiguration<T>("schlüssel") hinzufügen
└── Werteliste (erlaubte Ursprünge, Zuordnungen)
    └── IXxxOptions mit Eigenschaft vom Typ IEnumerable<T> erstellen

Projektkonvention

Das Projekt verwendet AddCustomConfiguration<IXxxOptions>("config-section") in IoCExtensions.cs (Zeilen 43–45 des aktuellen Projekts). Die Interfaces leben in *.Impl/ und werden von *.Impl/Services/ referenziert.

Erwartete Ausgabe

Wenn die Funktion eine Konfiguration erfordert, dem Benutzer präsentieren:

Name des Interfaces (z. B. IPendingPaymentOptions)
Eigenschaften mit ihren Typen und Standardwerten
Abschnitt in appsettings.json (z. B. "RAMBLA.PendingPayment")
Änderung von IoCExtensions.AddCSLevelBooking()

Wenn NICHT erforderlich, dies explizit im Plan angeben.

PHASE 1.7 — Auswirkungsanalyse auf die öffentliche API

Ziel: Vermeiden, bestehende Verbraucher zu beeinträchtigen.

Wenn die Funktion eine vorhandene Methode wiederverwendet

Bleibt die Methode mit derselben Signatur? → keine Auswirkungen
Wird ein optionaler Parameter hinzugefügt? → überprüfen, dass keine Aufrufstelle beschädigt wird
Wird eine Überladung hinzugefügt? → überprüfen, dass der Compiler eindeutig auflöst
Wird umbenannt? → alle Aufrufstellen mit grep suchen und migrieren

Wenn die Funktion einen neuen Dienst hinzufügt

Wird der Dienst in DI registriert? → Registrierung in IoCExtensions sicherstellen
Hat ein vorhandener Dienst eine potenzielle zirkuläre Abhängigkeit? → überprüfen

Wenn die Funktion einen neuen Endpunkt hinzufügt

Kollidiert die Route mit einer vorhandenen Route? → überprüfen
Ist die HTTP-Methode konsistent mit REST? (GET für Lesen, POST für Mutation)

PHASE 1.8 — PREFLIGHT von Regressionstests (obligatorisch)

Ziel: Bevor neuer Code generiert oder vorhandener geändert wird, überprüfen, dass die Komponenten, die berührt werden (auch nur am Rande), eine Testabdeckung haben. Wenn nicht, diese erstellen und vor Beginn der Implementierung ausführen.

Schritte

Randoberfläche identifizieren: Basierend auf PHASE 1.5 (Wiederverwendung vs. Erweiterung vs. Neu), auflisten:
- Vorhandene Dienste, deren Methoden erweitert oder überladen werden
- Vorhandene Schnittstellen, die geändert werden
- Vorhandene Endpunkte, die von Routing/DI betroffen sein können
- Alle vorhandenen Dateien, die bearbeitet werden (nicht erstellt)
Für jede vorhandene Komponente, die berührt wird:
- Tests in src/*.Test*/** suchen, die sie üben
- Wenn Abdeckung vorhanden → OK, fortfahren
- Wenn keine Abdeckung vorhanden → HARD BLOCK:
  - @refactor-worker-tests aufrufen, um Charakterisierungstests\n des aktuellen Verhaltens zu erstellen
  - @refactor-verifier aufrufen, um zu bestätigen, dass sie grün sind
  - Separater Commit:
```
test(charakterisierung): Charakterisierungstests für <Klassen> hinzufügen
```
Wenn die Funktion zu 100 % neu ist (keine vorhandenen Dateien berührt):
- Keine Regressionsoberfläche → PREFLIGHT überspringen
- Aber die Tests für die neue Funktion werden in PHASE 4 erstellt und müssen in PHASE 5 bestehen

Abschlusskriterium (PHASE 5)

Um die Funktion als korrekt zu betrachten, muss @refactor-verifier bestätigen, dass bestehen:

Neue Tests der Funktion (Dienst + Endpunkt)
Vorhandene Tests der tangentialen Komponenten (Regression)

Wenn einer fehlschlägt, kann die Funktion nicht abgeschlossen werden.

PHASE 2 — Entscheidungsbaum: Was und wo erstellen

Die Entscheidung aus PHASE 1.5 (Wiederverwendung / Erweiterung / Neu) plus PHASE 1.6 (Konfiguration) anwenden.

Für READ-ONLY-Endpunkt mit Wiederverwendung

*.API/
  + {Name}Function.cs       — Neue Function/Controller
  + {Name}Request.cs        — nur für die Präsentation
  + {Name}Response.cs       — nur für die Präsentation
*.Test*/
  + {Name}FunctionTests.cs  — Test der Response-Form (KEINE Logik)

Für MUTATION-Endpunkt mit neuem Dienst

*.Contracts/
  + ICS{Name}Service.cs     — Dienstschnittstelle
  + {Name}Request.cs        — wenn Request gemeinsam genutzt
  + {Name}Response.cs       — wenn Response gemeinsam genutzt
*.Impl/
  + CS{Name}Service.cs      — Implementierung
  + I{Name}Options.cs       — NUR wenn PHASE 1.6 Konfiguration erkannt hat
*.API/
  + {Name}Function.cs       — Function/Controller
  + {Name}Request.cs        — nur für diese Funktion (wenn nicht in Contracts)
  + {Name}Response.cs       — nur für diese Funktion (wenn nicht in Contracts)
*.Test*/
  + CS{Name}ServiceTests.cs — Happy Path + mindestens ein Fehler

Für Erweiterung eines vorhandenen Dienstes

*.Contracts/
  ~ ICS{Name}Service.cs     — Methodensignatur hinzufügen (oder Überladung erstellen)
*.Impl/
  ~ CS{Name}Service.cs      — Neue Methode/Überladung implementieren
*.API/
  + {Name}Function.cs       — Neue Function/Controller
  + {Name}Request.cs        — wenn nur für diese Funktion
  + {Name}Response.cs       — wenn nur für diese Funktion
*.Test*/
  + (o ~) Dienst-Tests      — Fall für die neue Methode hinzufügen

PHASE 3 — Erstellungsplan

Bevor Worker aufgerufen werden, präsentiert der Orchestrator diesen Plan dem Benutzer und wartet auf explizite Bestätigung:

[ERSTELLUNGSPLAN] Funktion: <Name> — <Kurzbeschreibung>
Host: <FUNCTIONS | WEBAPP>
Klassifizierung: <READ-ONLY | MUTATION>
Strategie: <WIEDERVERWENDUNG | ERWEITERUNG | NEU>

Wiederverwendungsanalyse (PHASE 1.5):
  · Kandidatendienst: <ICSXxxService> oder "keiner"
  · Kandidatenmethode: <XxxService.YyyMethod> oder "keine"
  · Entscheidung: <WIEDERVERWENDUNG | ERWEITERUNG | NEU>

Konfigurationsanalyse (PHASE 1.6):
  · Benötigt Konfiguration: <JA | NEIN>
  · Wenn ja: <IXxxOptions + appsettings-Abschnitt>

Auswirkung auf öffentliche API (PHASE 1.7):
  · Betroffene Aufrufstellen: <Liste> oder "keine"
  · Breaking Change: <JA | NEIN>

Zu erstellende Artefakte:

  *.Contracts/ ([N] Dateien):
    + ICS{Name}Service.cs    — Neue Schnittstelle (oder: Methode zu IXxx hinzufügen)
    + {Name}Request.cs       — wenn gemeinsam genutzter Typ
    + {Name}Response.cs      — wenn gemeinsam genutzter Typ

  *.Impl/ ([N] Dateien):
    + CS{Name}Service.cs     — Dienstimplementierung
    + I{Name}Options.cs      — NUR wenn Konfiguration erforderlich (PHASE 1.6)

  *.API/ ([N] Dateien):
    + {Name}Function.cs      — Azure Function (oder: {Name}Controller.cs)
    + {Name}Request.cs       — wenn nur für diese Funktion
    + {Name}Response.cs      — wenn nur für diese Funktion

  *.Test*/ ([N] Dateien):
    + CS{Name}ServiceTests.cs — Dienst-Tests (Happy Path + Fehler)
    + {Name}FunctionTests.cs  — Endpunkt-Tests (falls zutreffend)

Änderungen an vorhandenen Dateien:
  ~ src/.../IoCExtensions.cs   — Dienst und Optionen registrieren (falls zutreffend)

Ausführungsreihenfolge: Contracts → Impl → Presentation → Tests

Fortfahren?

Ohne explizite Zustimmung des Benutzers keine Worker aufrufen.

PHASE 4 — Ausführung

Reihenfolge der Worker

@refactor-worker-contracts — nur wenn es neue Typen oder Signaturen in *.Contracts/ gibt
@refactor-worker-impl — immer wenn es Code in *.Impl/ gibt
@refactor-worker-presentation — immer wenn es einen Endpunkt gibt
@refactor-worker-tests — immer am Ende

Hinweis: @refactor-worker-crosscutting wird NICHT aufgerufen, es sei denn, die Funktion legt einen neuen Service Gateway offen. Dies ist bei der Erstellung selten der Fall; es tritt normalerweise bei Refactorings auf.

Anweisungen an jeden Worker

In den Prompt aufnehmen:

Den vollständigen Plan (PHASE 3)
Die Projektmuster: Vor dem Erstellen eine ähnliche Datei lesen
Die genaue Liste der Dateien mit ihrem erwarteten Inhalt
Wenn PHASE 1.6 Konfiguration erkannt hat: den Pfad von IXxxOptions und den Konfigurationsabschnitt

PHASE 5 — Überprüfung und Commit

@refactor-verifier aufrufen

Wenn BESTANDEN → Commit mit folgendem Format vorschlagen:

feat(<bereich>): <kurzname>-Funktion hinzufügen

- ICS{Name}Service-Schnittstelle und CS{Name}Service-Implementierung hinzugefügt
- {VERB} /{pfad} Function/Controller hinzugefügt
- {Name}Request/{Name}Response-Verträge hinzugefügt
- I{Name}Options für neue Konfiguration hinzugefügt (falls zutreffend)
- Unit-Tests für CS{Name}Service hinzugefügt

Wenn FEHLGESCHLAGEN → fehlgeschlagene Ebene identifizieren, Worker erneut aufrufen, erneut überprüfen

Muster pro Host

FUNCTIONS — Azure Functions Isolated Worker

Vor dem Erstellen der Function eine vorhandene HTTP-Function lesen und ihren Stil kopieren. Typisches Beispiel:

public class {Name}Function
{
    private readonly I{Name}Service _{feld};

    public {Name}Function(I{Name}Service {feld}) => _{feld} = {feld};

    [Function("{Name}Function")]
    public async Task<HttpResponseData> RunAsync(
        [HttpTrigger(AuthorizationLevel.Function, "post", Route = "{pfad}")] HttpRequestData req)
    {
        var request = await req.ReadFromJsonAsync<{Name}Request>();
        var result = await _{feld}.ExecuteAsync(request);
        var response = req.CreateResponse(HttpStatusCode.OK);
        await response.WriteAsJsonAsync(result);
        return response;
    }
}

Vor dem Erstellen überprüfen:

AuthorizationLevel.Function oder A...

[Fortsetzung des Originals, sofern vorhanden]

In Ihrer bevorzugten KI fragen

Dokumentation

Was ich tue

PHASE 0 — Strukturvalidierung (immer zuerst)

PHASE 1 — Anforderungserfassung

1.1 Name, Zweck und Art der Funktion

1.2 Klassifizierung READ vs. MUTATION

1.3 Erfassung der erwarteten Ein-/Ausgabe

PHASE 1.5 — Wiederverwendungsanalyse (KRITISCH, nicht überspringen)

Schritte

Entscheidungsbaum

Erwartete Ausgabe dieser Phase

PHASE 1.6 — Konfigurationsanalyse (NEU)

Schlüsselfragen

Entscheidungsbaum

Projektkonvention

Erwartete Ausgabe

PHASE 1.7 — Auswirkungsanalyse auf die öffentliche API

Wenn die Funktion eine vorhandene Methode wiederverwendet

Wenn die Funktion einen neuen Dienst hinzufügt

Wenn die Funktion einen neuen Endpunkt hinzufügt

PHASE 1.8 — PREFLIGHT von Regressionstests (obligatorisch)

Schritte

Abschlusskriterium (PHASE 5)

PHASE 2 — Entscheidungsbaum: Was und wo erstellen

Für READ-ONLY-Endpunkt mit Wiederverwendung

Für MUTATION-Endpunkt mit neuem Dienst

Für Erweiterung eines vorhandenen Dienstes

PHASE 3 — Erstellungsplan

PHASE 4 — Ausführung

Reihenfolge der Worker

Anweisungen an jeden Worker

PHASE 5 — Überprüfung und Commit

Muster pro Host

FUNCTIONS — Azure Functions Isolated Worker

Verwandte Skills

affaan-m/uspto-database

affaan-m/scholar-evaluation

affaan-m/literature-review

affaan-m/everything-claude-code

forrestchang/andrej-karpathy-skills

langgenius/backend-code-review