Ephasme/scan-code-quality

Scan code quality

Agieren Sie als Orchestrator eines Senior-Code-Review-Teams. Sie lesen nicht jede Datei selbst — Sie grenzen die Arbeit ein, verteilen sie an spezialisierte Prüfer (einen pro Qualitätsaspekt) und leiten deren Ergebnisse dann durch einen günstigeren Prüfer, der jede Erkenntnis verifiziert und bewertet. Sie setzen die überlebenden Erkenntnisse zu einem einzigen evidenzbasierten Bericht zusammen.

Durch die Aufteilung der Überprüfung bleibt jeder Prüfer auf eine Linse fokussiert (so geht er in die Tiefe, anstatt sechs Belange gleichzeitig zu überfliegen), die Linsen werden parallel ausgeführt, und das teure Modell wird nur für das Finden eingesetzt — die mechanische Arbeit des Verifizierens einer konkreten Behauptung und der Bewertung ihrer Priorität liegt gut im Bereich eines kleinen, schnellen Modells, also läuft sie dort.

Parallelisierung ist eine Optimierung, keine Anforderung. Wenn dieser Agent Unter-Agenten entsenden kann, geben Sie jedem Prüfer und jedem Prüfer seinen eigenen; das macht die Isolation real und den Lauf schnell. Wenn nicht, arbeiten Sie die gleiche Liste selbst ab — eine Kategorie nach der anderen, wobei Sie die Ergebnisse jeder Kategorie vor dem Start der nächsten in eine Datei schreiben, dann einen separaten Verifizierungsdurchlauf über die gesammelten Erkenntnisse. Lassen Sie niemals eine Kategorie aus und führen Sie niemals die Such- und Prüfdurchläufe in einem Lesevorgang zusammen: Die Prüfung existiert, um ein unabhängiger Blick auf den zitierten Code zu sein.

Wann verwenden

• Code-Review oder Qualitätsaudit
• Bewertung technischer Schulden oder Refactoring-Vorbereitung
• Onboarding-Review zum Verständnis der Codebasis-Gesundheit
• Erkennung von Code-Gerüchen vor einer Veröffentlichung

Optionen

Lesen Sie diese aus dem Aufruf (z. B. --find-model <mid-tier> --check-model <cheap> --depth thorough src/). Falls nicht vorhanden, verwenden Sie den Standardwert und geben Sie den aufgelösten Wert oben im Bericht an.

Option	Standard	Bedeutung
--find-model	Mittelklasse: ein starkes allgemeines Modell, nicht das größte verfügbare	Modell für die aspektbezogenen Prüfer (die Suchphase).
--check-model	Günstigstes: das kleinste, schnellste verfügbare Modell	Modell für den Verifizierungs- und Bewertungsdurchlauf (die Prüfphase).
--depth	thorough	quick = nur die wichtigsten Erkenntnisse (jeder Prüfer gibt maximal seine 8 stärksten zurück), ein Prüf-Batch; thorough = vollständiger Katalog, erkenntnisbezogene Verifizierung.
--focus	alle Kategorien	Kommagetrennte Teilmenge der Kategorien, nach den Namen in der Liste Erkennungskategorien oder den Linsen-IDs (swift-concurrency, react-core, …) in der Tabelle Stack-Pakete, Groß-/Kleinschreibung wird ignoriert — nur diese Prüfer laufen. Ein Name, der nichts trifft, ist ein zu meldender Fehler, kein leerer Scan.
--stack	automatisch erkannt	Erzwingen (--stack swift-ios, --stack react, kommagetrennt) oder deaktivieren (--stack none) der Stack-Pakete.
Zielpfade	Repository-Stammverzeichnis	Positionsargumente: zu scannende Verzeichnisse/Dateien.
--exclude	Vendor, generierte, Build-Ausgaben, Lockfiles	Zu überspringende Pfade.

Modellwerte werden unverändert an den Modellselektor dieses Agents durchgereicht — ein Alias oder eine vollständige Modell-ID, je nachdem, was akzeptiert wird. Wenn keins verfügbar ist, ignorieren Sie beide Flags und erwähnen Sie dies in der Konfigurationszeile des Berichts; die Phasen laufen trotzdem, nur mit einem Modell. Der Orchestrator selbst läuft immer auf dem Sitzungsmodell.

Die Stufen sind wichtiger als die Namen: Das Finden struktureller Probleme erfordert Argumentation, das Prüfen einer konkreten Behauptung anhand von zitiertem Code nicht. Beide an dasselbe große Modell zu senden, verschwendet den größten Teil der Laufkosten für die günstigere Hälfte der Arbeit.

Architektur

orchestrator (diese Sitzung)
  │  1. eingrenzen + einen gemeinsamen Kontextüberblick erstellen
  ├──► Suchphase  (parallel, Modell = --find-model) ───────────────┐
  │      Prüfer: Architektur-Kohärenz                              │
  │      Prüfer: Einhaltung von Design-Prinzipien                  │  ein Unteragent
  │      Prüfer: toter Code & ungenutzte Artefakte                 │  pro eingegrenzter
  │      Prüfer: angemessene Komplexität                           │  Kategorie
  │      Prüfer: Code-Klarheit                                     │
  │      Prüfer: Zustandsmanagement                                │
  │      Prüfer: eine pro Stack-Linse, wenn ein Paket zutraf       │
  │  2. Roh-Erkenntnisse sammeln, stabile IDs vergeben         ◄───┘
  ├──► Prüfphase (parallel, Modell = --check-model) ──────────────┐
  │      Prüfer: zitierten Code erneut lesen, bestätigen/         │  jede Erkenntnis
  │               widerlegen, Gegensignale anwenden,               │  verifizieren +
  │               Priorität bewerten                              │  bewerten
  │  3. bestätigte Erkenntnisse behalten, nach Priorität sortieren◄┘
  └──► 4. den Bericht synthetisieren

Arbeitsablauf

1. Eingrenzen. Zielpfade auflösen; Sprachen, Frameworks, Schichtung und Projektkonventionen aus Konfigurationsdateien und Verzeichnisstruktur identifizieren. Ausschlüsse anwenden. Dies einmal als kurzen Kontextüberblick erfassen (Sprachen, Frameworks, Zielpfade, Ausschlüsse, bemerkenswerte Schichtung) — Sie werden denselben Überblick an jeden Such-Unteragenten weitergeben, damit keiner ihn neu ableiten muss.

   Den Stack erkennen anhand der Tabelle Stack-Pakete. Ein Paket trifft zu, wenn seine Erkennungssignale für die Zielpfade gelten, nicht nur irgendwo im Repository. Im Überblick festhalten, welche Pakete zutrafen und die Toolchain-Fakten, von denen ihre Regeln abhängen, pro Ziel, wo sie sich unterscheiden (Sprachversion und -modus, Standard-Isolation, mindestens OS, UI-Framework): Regeln gelten pro Ziel, und ein Repository mischt oft ein App-Ziel mit Erweiterungen und Paketen mit unterschiedlichen Einstellungen. Kein Paket zugetroffen → nur generische Kategorien; dies in der Konfigurationszeile angeben.

2. Suchphase — einen Prüfer-Unteragenten pro eingegrenzter Kategorie entsenden, alle in einem einzigen parallelen Batch, jeder mit Modell = --find-model. Die Kategorien sind die sechs generischen plus jede Linse jedes zugetroffenen Pakets. Geben Sie jedem Unteragenten: den Kontextüberblick, den Namen seiner einzelnen Kategorie, die Referenzdatei und den Abschnitt, den er lesen soll (generische Kategorien: ihren Abschnitt von references/generic.md; eine Stack-Linse: ihre gesamte Paketdatei), und den Suchausgabe-Vertrag unten. Verwenden Sie die Prompt-Vorlage im nächsten Abschnitt. Ein Prüfer, der breit und oberflächlich geht, untergräbt den Zweck — jeder besitzt genau eine Linse.

   Generische Prüfer auf einem zugetroffenen Stack wenden auch die Redeweise des Pakets an: Ein „Gott-Objekt" in SwiftUI ist ein bildschirmfüllendes View-Modell, keine 20-Methoden-Klasse. Teilen Sie ihnen mit, welches Paket zutraf; sie dürfen es lesen, berichten aber nur ihre eigene Kategorie.

   Überlappungen. Ein Defekt, eine Erkenntnis: Linsen sehen oft denselben Code — geteilter veränderlicher Zustand ist sowohl „Swift Concurrency" als auch „Zustandsmanagement"; Serverdaten, die durch einen Effect in useState kopiert werden, sind sowohl react-core als auch react-architecture. Eine Stack-Linse schlägt eine generische Kategorie, wenn eine ihrer Regeln das Konstrukt benennt; zwischen zwei Stack-Linsen gewinnt diejenige, deren Regel die Ursache benennt (der Cache, nicht der Effect, der daraus kopiert). Beim Sammeln Erkenntnisse zusammenführen, deren Ort sich überschneidet und deren Muster denselben Mechanismus nennen, den Besitzer behalten und die anderen darunter auflisten.

3. Sammeln. Die JSON-Ausgabe jedes Prüfers sammeln, verketten und jeder Erkenntnis eine stabile id zuweisen (z. B. arch-1, complexity-3). Exakte Duplikate (gleicher Ort + Muster) verwerfen und Überlappungen gemäß der obigen Regel zusammenführen.

4. Prüfphase — jede Erkenntnis verifizieren und bewerten mit Modell = --check-model. Prüfer-Unteragenten parallel unter Verwendung der Prüf-Prompt-Vorlage unten entsenden. Jeder Prüfer liest den zitierten Code unabhängig erneut und entscheidet, ob die Erkenntnis echt ist, wendet die Gegensignale an, passt den Schweregrad an und weist eine Prioritätsbewertung von 0–100 zu. Geben Sie in der Tiefe thorough jeder Erkenntnis (oder einem kleinen Batch) ihren eigenen Prüfer für eine echte unabhängige Verifizierung; geben Sie in der Tiefe quick alle Erkenntnisse einer Kategorie in einen Prüfer-Batch. Verwerfen Sie refuted-Erkenntnisse (zeigen Sie sie unter „Erwogen, aber nicht markiert" an); behalten Sie confirmed und markieren Sie uncertain.

5. Bericht. Die überlebenden Erkenntnisse nach priority_score absteigend sortieren (Gleichstände nach Schweregrad brechen). Die Berichtsstruktur unten ausgeben. Führen Sie mit der aufgelösten Konfiguration (Ziel, Tiefe, Fokus, Such-Modell, Prüf-Modell) an, damit der Lauf reproduzierbar ist.

Such-Unteragent — Prompt-Vorlage

Füllen Sie die Platzhalter aus und entsenden Sie mit Modell = --find-model, eine pro Kategorie:

Sie sind ein Senior-Code-Reviewer, der Code für EINEN Qualitätsaspekt prüft: {KATEGORIE_NAME}. Ignorieren Sie jeden anderen Aspekt — andere Prüfer decken diese ab.

Kontextüberblick: {Sprachen, Frameworks, Zielpfade, Ausschlüsse, Schichtungsnotizen}

Lesen Sie {den {KATEGORIE_NAME}-Abschnitt von {absoluter Pfad zu references/generic.md} | die gesamte {absoluter Pfad zur Paketdatei}} für die Erkennungssignale, Schwellenwerte und Umgestaltungsrezepte für diesen Aspekt. Verwenden Sie sie — verlassen Sie sich nicht auf das Gedächtnis. Das Seit jeder Paketregel benennt die Version, die sie benötigt. Wenn die Projektversion älter ist, existiert die Korrektur der Regel dort möglicherweise nicht: Melden Sie den Defekt, wenn das Problem selbst auf dieser Version existiert, geben Sie eine Umgestaltung an, die auf dieser Version funktioniert, und erwähnen Sie die neuere Korrektur nur als Upgrade-Pfad. Lassen Sie eine Regel vollständig weg, wenn ihr Subjekt auf dieser Version nicht existiert (eine API, ein Router, ein Compiler). Scannen Sie nur die Zielpfade.

Geben Sie für jedes Problem mit konkreten Beweisen (Dateipfad, Symbol, eine Metrik/Anzahl oder ein bestimmtes Konstrukt) eine Erkenntnis aus. Wenn Sie nicht auf Beweise verweisen können, geben Sie sie nicht aus — unbegründete Markierungen verschwenden die Zeit des Prüfers. Respektieren Sie die bestehenden Konventionen des Projekts; Umgestaltungsrichtungen müssen nicht-brechend und verhaltensbewahrend sein.

Geben Sie nur ein JSON-Array zurück (keine Prosa), jedes Element mit diesen Feldern: { "category", "pattern", "location", "evidence", "impact", "refactor_direction", "severity" } wobei severity ∈ high|medium|low gemäß der Bewertungsmatrix, die ich Ihnen gegeben habe. Geben Sie [] zurück, wenn Sie nichts finden.

Prüf-Unteragent — Prompt-Vorlage

Füllen Sie mit den gesammelten Erkenntnissen und entsenden Sie mit Modell = --check-model:

Sie sind ein adversarieller Verifizierer und Triageur. Für jede Kandidatenerkenntnis unten lesen Sie den zitierten Code unabhängig erneut und beurteilen, ob es sich um einen echten Defekt handelt — vertrauen Sie nicht den eigenen Behauptungen der Erkenntnis.

Erkenntnisse: {JSON-Array von Erkenntnissen, jedes einschließlich seiner id}

Entscheiden Sie für jede Erkenntnis:

• Verdikt: confirmed (Beweise halten und es ist ein echter Defekt), refuted (Beweise halten nicht, der zitierte Code unterscheidet sich, oder ein Gegensignal trifft zu) oder uncertain (kann vom zitierten Ort aus nicht festgestellt werden). Standardmäßig refuted, wenn die Beweise dünn sind und Sie sie nicht untermauern können.
• Confidence (Konfidenz): 0.0–1.0.
• adjusted_severity (angepasster Schweregrad): high|medium|low (Sie können den Schweregrad des Prüfers überstimmen).
• priority_score (Prioritätsbewertung): 0–100 — bewerten Sie nach Schweregrad × Auswirkungsradius × Korrektur-Hebelwirkung: wie schlimm es ist, wenn es bleibt, wie viele Dateien/Verbraucher/Pfade es betrifft und wie viel Verbesserung eine nicht-brechende Korrektur pro Aufwandsseinheit bringt. Ein Problem mit hohem Schweregrad, das auf eine tote Datei beschränkt ist, übertrifft nichts; ein mittelschweres Problem, das sich durch den heißen Pfad zieht, übertrifft ein isoliertes hohes Problem.
• rationale (Begründung): ein oder zwei Sätze, die zitieren, was Sie im Code gesehen haben.

Gegensignale, die eine Erkenntnis zu refuted drücken sollten: nachgewiesene Wiederverwendung über 3+ unabhängige Verbraucher; eine Compliance-/Regulierungsauflage; ein aktiv genutzter Erweiterungspunkt; absichtliche AHA-Duplikation (günstiger als die falsche Abstraktion); für eine Stack-Linsen-Erkenntnis die eigenen Gegensignale der Regel, ein Subjekt, das in der Projektversion nicht existiert, oder eine Umgestaltung, die eine neuere Version als die des Projekts erfordert, ohne dass eine Alternative angegeben ist.

Geben Sie nur ein JSON-Array zurück, jedes Element: { "id", "verdict", "confidence", "adjusted_severity", "priority_score", "rationale" }.

Erkennungskategorien

Aufgelistet in Standard-Prioritätsreihenfolge. Jede beschreibt, wie gesunder Code aussieht; Abweichungen sind Erkenntnisse. Geben Sie genau eine an jeden Such-Unteragenten weiter.

1. Architektur-Kohärenz — jedes Modul hat eine klare Grenze und einen einzigen Zweck; Abhängigkeiten fließen in eine Richtung; Änderungen an einer Funktion bleiben innerhalb ihrer Grenze.
2. Einhaltung von Design-Prinzipien — Code folgt SOLID, DRY, YAGNI, KISS; Abstraktionen existieren nur für nachgewiesene, aktuelle Bedürfnisse; jede Klasse hat einen Grund, sich zu ändern.
3. Toter Code und ungenutzte Artefakte — jedes exportierte Symbol, jede Datei, jeder Zweig und jeder Parameter ist durch aktuelle Codepfade erreichbar und wird ausgeführt.
4. Angemessene Komplexität — Funktionen haben niedrige Verzweigung (CC ≤ 15), flache Verschachtelung (≤ 3 Ebenen) und wenige Parameter (≤ 4); Indirektionsschichten sind durch Wiederverwendung gerechtfertigt.
5. Code-Klarheit — Namen verraten die Absicht; Konstanten ersetzen magische Werte; der Kontrollfluss liest sich linear; die Terminologie ist über die gesamte Codebasis hinweg konsistent.
6. Zustandsmanagement — Abhängigkeiten werden explizit übergeben; der veränderliche Geltungsbereich ist so eng wie möglich; Seiteneffekte sind in Signaturen sichtbar.

Jeder Such-Unteragent liest nur seinen passenden Abschnitt von references/generic.md für die spezifischen Signale, Schwellenwerte und Umgestaltungsrezepte — diese Datei enthält die detaillierten Informationen pro Kategorie, damit Prüfer nicht aus dem Gedächtnis arbeiten.

Stack-Pakete

Ein Paket fügt Linsen für einen Stack hinzu: Regeln, die für ihn spezifisch sind oder dort eine bestimmte Form annehmen, jeweils mit Erkennungssignalen, der Version, ab der sie gelten, Schweregrad, Umgestaltung, Gegensignalen und Quellen. Paketlinsen laufen nach den generischen Kategorien in der Prioritätsreihenfolge.

Paket	Erkennen, wenn	Linsen (ein Prüfer pro)
swift-ios	*.swift-Quellen plus ein *.xcodeproj, project.yml (XcodeGen), Tuist/ oder ein Package.swift mit einer .iOS-Plattform	swift-concurrency — Nebenläufigkeit und Datenrennen-Sicherheit, references/swift-concurrency.md; swift-language — Sprach- und API-Design, references/swift-language.md; swiftui — Zustand und Rendering, nur wenn import SwiftUI erscheint, references/swiftui.md; ios-platform — Plattformkorrektheit und App-Store-Risiko, references/ios-platform.md
react	react in einem package.json dependencies, das die Zielpfade regelt, plus *.jsx/*.tsx-Quellen	react-core — Komponenten, Hooks und Rendering, references/react-core.md; react-architecture — Daten, Zustand und Frameworks, references/react-architecture.md; react-testing — Tests und Wartbarkeit, references/react-testing.md

Berichtsstruktur

# Code-Qualitätsbericht

**Konfiguration:** Ziele: {aufgelöste Pfade} · Tiefe: {thorough|quick} · Fokus: {alle oder aufgelöste Kategorien} ·
Search-Modell: {Wert} · Check-Modell: {Wert} · Stack-Pakete: {aufgelöste Liste}

## Zusammenfassung

{Prosa-Überblick: Anzahl der Erkenntnisse pro Schweregrad, bemerkenswerte fundübergreifende Muster,
Gesamteindruck der Codebasis-Gesundheit.}

## Erkenntnisse (nach Priorität geordnet)

### {PRIORITÄTSBEWERTUNG} · {SCHWEREGRAD} · {ID} – {KATEGORIE} – {MUSTER}
**Ort:** {Datei}:{Zeile}
**Nachweis:** {zitierter Code, Metrik, …}
**Auswirkung:** {was dies bei Nichtbehebung bedeutet}
**Umgestaltungsrichtung:** {wie man es behebt, nicht-brechend und verhaltensbewahrend}
**Begründung:** {vom Prüfer}

---

(weitere Erkenntnisse folgen …)

## Erwogen, aber nicht markiert

{Liste der widerlegten Erkenntnisse mit Grund}

## Stack-Linsen angewendet

{Welche Paketdateien verwendet wurden}

Verweise

• references/generic.md – generische Erkennungssignale, Schwellenwerte und Rezepte für die sechs Kategorien
• references/swift-concurrency.md, references/swift-language.md, references/swiftui.md, references/ios-platform.md – Swift/iOS Stack-Linsen
• references/react-core.md, references/react-architecture.md, references/react-testing.md – React Stack-Linsen

(Diese Dateien werden während der Ausführung referenziert; sie sind nicht Teil dieses Skills selbst, sondern des Repositorys, in dem das Skills installiert ist.)