Bottleneck Lens

Bottleneck Lens (Bottleneck Linse)

Finde den Engpass. Beweise die Verbesserung.

Halte die Erhebung lokal; lade standardmäßig keine Quellen, Traces oder Berichte hoch. Die portablen Anweisungen und gebündelten Skripte erfordern keinen bestimmten Agentenanbieter. Löse gebündelte Pfade relativ zu dieser SKILL.md auf. Die CLI erfordert Python 3.10+; Zieladapter unterstützen Python 3.10+ und Node.js 22+. Node unterstützt Benchmark-/CPU-Modi; Python unterstützt auch Speicherzuordnungsprofiling (allocation profiling).

Workload entdecken und vereinbaren

Lies Projektanweisungen, Manifeste, Lockfiles, Einstiegspunkte und vorhandene Leistungs-/Korrektheitstests, ohne Projektmodule zu importieren oder Setup-Hooks auszuführen. Identifiziere Sprache, Framework, Interpreter, Abhängigkeiten und die tatsächlich langsame Operation. Wähle den Python- oder Node-Adapter und die vorhandene Projektlaufzeit aus. Erkläre für eine andere Sprache die Collector-Grenzen und schlage einen geeigneten Profiler vor, anstatt so zu tun, als ob die gebündelten Adapter dies unterstützen würden.

Wähle einen repräsentativen, abgegrenzten Workload mit einem stabilen Datensatz, Seed, Nebenläufigkeit (Concurrency), Cache-Richtlinie und erwarteter Ausgabe. Bevorzuge einen vertrauenswürdigen vorhandenen Benchmark oder einen kleinen geprüften Treiber, der das Ergebnis zusichert. Auch Test-Colllection- und Anwendungsimporte führen Code aus. Wenn kein ausführbarer Workload verfügbar ist, liefere Hypothesen und einen Erhebungsplan; erfinde niemals Messungen.

Bevor du ein unbekanntes Repository ausführst, zeige den genauen Interpreter, das Arbeitsverzeichnis, den Befehl und die Argumente, die Anzahl der Aufrufe, das Timeout, die Ausgabepfade und mögliche Datenbank-/Netzwerk-/Dateiauswirkungen an. Hole dir für diesen konkreten Workload die Autorisierung ein, sofern diese nicht bereits durch das Gespräch abgedeckt ist. Die Erlaubnis zur Inspektion oder Profilerstellung ist nicht die Erlaubnis, Anwendungscode zu ändern. Frage vor Änderungen, es sei denn, der Benutzer hat die Optimierung bereits autorisiert. Frage nicht erneut nach einem unveränderten, bereits genehmigten Umfang. Das Installieren von Abhängigkeiten, das Anhängen an Prozesse und der Zugriff auf die Produktion erfordern ihre eigene entsprechende Autorisierung.

Der Collector führt Code mit den Berechtigungen des Benutzers aus: Unterprozess-Trennung und Timeouts sind keine Sicherheitssandbox. Verwende bei Bedarf Fixtures oder eine Testdatenbank. Gib niemals Anmeldeinformationen in Workload-IDs oder Befehlszeilenargumenten weiter; Argumente und Pfade werden lokal aufgezeichnet. Berichte können interne Pfade offenlegen. Führe keine unbekannten Befehle nur aus, um herauszufinden, was sie tun.

Daten sammeln

Lies references/measurement.md für Befehle, Metrikdefinitionen, statistische Entscheidungen und Exit-Codes. Das gemeinsame Format Version 2 ist in references/measurement.schema.json definiert. Führe den gebündelten Collector nur für den autorisierten Workload aus. Erhebe alte oder Ad-hoc-Artefakte erneut, anstatt ihre fehlenden Metrikgrenzen zu erraten.

• Sammle zuerst einen nicht instrumentierten Benchmark. Speichere alle Stichproben, Umgebungsmetadaten, Workload-Identität und Code-Revision. Jede Stichprobe verwendet einen neuen Prozess. Ein verworfener Warmup ist ebenfalls ein neuer Prozess; er wärmt keinen Anwendungszustand in späteren Prozessen auf.
• Sammle CPU-Profile und, für Python, Speicherzuordnungsprofile in separaten Aufrufen. Ihre Zeitmessungen sind diagnostisch und können nicht durch Benchmark-Zeitmessungen ersetzt werden. Der Node-CPU-Modus behält ein V8-Profil und Ereignisschleifen-Diagnosen bei; Stichprobentreffer sind keine Aufrufzahlen und das V8-Profil enthält den Collector-Start. Die Standard-Benchmark- und Speicherzuordnungserhebung führt den Workload jeweils achtmal aus (ein Warmup, sieben aufgezeichnete Durchläufe); ein CPU-Profil fügt einen Aufruf ohne Warmup hinzu. Gib diese Zählungen in den genehmigten Plan ein.
• Bewahre die Baseline vor der Bearbeitung auf. Verwende neue Ausgabenamen: Die Skripte weigern sich, Artefakte zu überschreiben. Wähle ein dauerhaftes Ergebnisverzeichnis und behalte jedes JSON mit seinem benachbarten Artefaktverzeichnis. Zeichne die Datensatzidentität, --input-Datei-Hashes, Seed, Revision, relevante --source-Dateien und die Cache-Richtlinie auf. Der aufgezeichnete Seed seedet keinen Anwendungscode; automatische Metadaten können den tatsächlichen Cache-Zustand oder nicht spezifizierte Eingaben nicht feststellen.
• Verwende, wo sinnvoll, --expected-stdout mit einer unabhängig geprüften bekannten Antwort. Jeder Aufruf, einschließlich Warmups, wird überprüft. Ohne diesen Orakel bleibt die automatische Korrektheitsbewertung aus; führe separate Projekttests aus und berichte darüber. Eine enge Ausgabegleichheit deckt nicht jede Anwendungsinvariante ab.
• Bevorzuge einen endlichen Treiber für eine Python-API oder einen Worker. Das gebündelte Tool ist kein HTTP-Lastgenerator, Live-Prozess-Sampler, Thread-weiter CPU-Profiler oder Prozessbaum-Monitor. Es misst nicht direkt I/O-Bytes, Abfragezahlen, Anfrage-Perzentile oder Durchsatz. Wähle bei Bedarf zusätzliche Instrumentierung mit dem Benutzer und zeichne deren Umfang/Overhead auf.

Diagnostizieren und Vorschlagen

Zitiere für jeden Befund das Artefakt, die Funktion/Datei/Zeile, die Aufrufanzahl oder Zuordnungsgröße und die relevante Selbst-/kumulative Zeit. Unterscheide beobachtete Tatsache, Hypothese und vorgeschlagene Änderung. Kumulative Zeiten überschneiden sich über den Aufrufbaum hinweg; addiere sie niemals zu einem Prozentsatz der Gesamtzeit. Eine hohe kumulative Zeit identifiziert einen teuren Pfad, nicht unbedingt die umzuschreibende Funktion.

Eine CPU-Zeit unterhalb der Wanduhrzeit kann auf Warten hindeuten, beweist aber keine Festplatten-, Datenbank- oder Netzwerkkausalität. Ein wiederholter Funktionsaufruf ist kein Beweis für N+1-Abfragen: Ermittle Abfragezahlen/-spannen und überprüfe die Schleife. Speicherzuordnungs-Snapshots beschreiben Live-Zuordnungen zum Snapshot-Zeitpunkt, nicht alle transienten Zuordnungen oder ein Leck. Bestätige vermutete Lecks durch wiederholte Workloads und Retention-Nachweise. Gib Unbekanntes explizit an.

Priorisiere Änderungen nach gemessenem Beitrag, wahrscheinlichem Nutzen, Implementierungskosten, Korrektheitsrisiko und Ressourcenabwägungen. Beschreibe Cache-Invalidierung, Reihenfolge, Transaktions-, Nebenläufigkeits- und Speichereffekte, wo relevant. Versprich keine prozentuale Verbesserung, bevor sie gemessen ist.

Optimieren und Verifizieren innerhalb der Autorisierung

Nimm die kleinste autorisierte Änderung vor und bewahre nicht zusammenhängende Arbeiten. Führe relevante Korrektheitstests durch und vergleiche Ausgaben/Invarianten mit dem gleichen Fixture. Ein erfolgreicher Prozess-Exit allein ist keine Korrektheitsverifizierung.

Wiederhole den gleichen Benchmark und die betroffenen Profile mit der gleichen Umgebung, dem gleichen Workload, Seed, Cache-Richtlinie, Durchlaufanzahl und Timeout. rerun führt den aktuellen Code mit der aufgezeichneten Anfrage aus und überprüft Eingabe-Hashes; es stellt keine historische Revision wieder her. Vergleiche nicht instrumentierte Zeitmessungen mit nicht instrumentierten Zeitmessungen und gleichartige Speichermetriken. Das gemeinsame JSON macht verschiedene Prozess-/Thread-Bereiche oder Laufzeit-Zeitintervalle nicht austauschbar. Wenn sich eine Abhängigkeit / ein Interpreter / ein Workload ändert, melde dies als separates Experiment, anstatt die Inkompatibilitätsprüfungen zu umgehen.

Verwende den gebündelten Vergleichsbefehl, um deskriptive Median-/Mittelwertänderungen, konfigurierte praktische Schwellenwerte und unabhängige Stichproben-Permutationsnachweise für Mittelwertunterschiede (Holm-korrigiert über verglichene Metriken) zu trennen. Wähle Schwellenwerte vor dem Betrachten der Ergebnisse; der Standardwert von 5 % ist nicht universell aussagekräftig. Bereichsüberlappung ist kein Signifikanztest. Der Test nimmt unabhängige, austauschbare Stichproben an; überprüfe die Variabilität und wiederhole oder verschränke A/B-Messungen, wenn Drift diese Annahme ungültig machen könnte. Nicht schlüssige Ergebnisse begründen keine Gleichwertigkeit.

Der Status verified_improvement (verifizierte Verbesserung) ist auf den gemessenen Workload und passende bestandene Ausgabe-Orakel beschränkt, erfordert eine unterstützte praktische primäre Metrikverbesserung und wird durch unterstützte praktische Regressionen in anderen verglichenen Metriken blockiert. Fehlgeschlagene Ausgabeprüfungen beenden mit Exit-Code 3 und blockieren die Verifizierung, selbst wenn die Ausführung schneller ist. --fail-on-regression lässt unterstützte praktische Regressionen mit Exit-Code 1 beenden; ein Exit-Code 0 für einen nicht schlüssigen Vergleich bescheinigt keine Verbesserung. Bewerbe kein nicht bewertetes oder fehlgeschlagenes Ergebnis in der Erzählung. Führe repräsentative benachbarte Workloads aus, falls vorhanden und autorisiert. Beanspruche Regressionsabdeckung nur für getestete Szenarien. Höre auf, Experimente auszuweiten, wenn die vereinbarte Frage beantwortet ist, ein Durchlauf fehlschlägt, Autorisierungsgrenzen erreicht sind oder vergleichbare Messungen nicht erhalten werden können.

Ergebnis liefern

Verwende die Sprache des Benutzers. Jede Sammlung/jeder Vergleich erzeugt einen Markdown-Bericht und JSON; füge eine Agenteninterpretation in der Sprache des Benutzers hinzu, während die rohen Beweise erhalten bleiben. Führe mit dem an, was gefunden wurde, seinen Beweisen und dem nächsten Experiment, dann füge hinzu:

• Umfang, Befehl, Umgebung/Revisionen, Eingaben, Wiederholungsanzahl und Messgrenzen.
• Befunde mit Beweisen und Vertrauen; trenne ungemessene Vorschläge.
• Vorgenommene oder vorgeschlagene Änderungen, Abwägungen und Korrektheitsprüfungen mit Befehlen/Ergebnissen.
• Vorher-/Nachher-Mediane und Mittelwerte, Min/Max, Stichprobenanzahl und Änderungsprozentsätze für jede vergleichbare Metrik. Tests und praktische Entscheidungen verwenden Mittelwerte; Medianänderungen sind deskriptiv. Füge Einheiten und Prozess-/Thread-/Startgrenzen hinzu. Positive Änderung bedeutet höhere Werte; negative bedeutet niedrigere. Markiere Null-Baselines als undefiniert.
• Status: gemessene Baseline, nicht schlüssig, beobachtete Verbesserung / Regression oder verifizierte Verbesserung. Reserve verifizierte Verbesserung für vergleichbare Wiederholungsmessungen plus bestandene Korrektheitsprüfungen. Ein Geschwindigkeitsgewinn bei erhöhtem Speicher ist ein Abwägung, kein uneingeschränkter Erfolg.
• Ungetestete Pfade, nicht verfügbare Metriken, Rauschen, nächste Aktion und den konkreten aufgezeichneten Rerun-Befehl. Kennzeichne die bekannten Antwort-Demonstrationen des gebündelten scripts/demo.py klar und verwende ihre Zahlen niemals als Anwendungsergebnisse.

Markdown/JSON-Dateien sind die portable Baseline; ein Agent kann mit seinen verfügbaren Präsentationswerkzeugen ein Diagramm hinzufügen. Verlasse dich nicht auf ein gehostetes Dashboard, einen externen KI-Endpunkt, einen proprietären Connector oder ein optionales Diagrammwerkzeug, um diesen Workflow abzuschließen.