Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design
Codex

Anwendungsfall für Codex

Telemetrie für eine Mac-App ergänzen

Protokolliere mit Codex und Logger, was eine Funktion deiner Mac-App tut. Starte die App und prüfe im macOS-Systemprotokoll, ob die erwartete Aktion ausgeführt wurde.

Schwierigkeitsgrad Advanced
Zeithorizont 30m

Erfasse mit Codex und dem Plugin „Build macOS Apps“ einige aussagekräftige Logger-Ereignisse für Fenster, Seitenleisten, Befehle oder die Synchronisierung. Starte dann die App und prüfe in der Konsole oder mit log stream, ob die erwarteten Aktionen ausgeführt wurden.

Besonders geeignet für

  • Funktionen in Mac-Apps, bei denen Codex einzelne Schritte zuverlässig nachvollziehen muss, etwa das Öffnen eines Fensters, eine geänderte Auswahl in der Seitenleiste, einen Menübefehl, eine Aktion in der Menüleiste, einen wichtigen Schritt bei der Synchronisierung oder den Wechsel zu einem alternativen Ablauf
  • Debugging mit Codex, wenn der Agent den Code korrigieren, die App erneut starten und anhand der Protokolle entscheiden soll, was als Nächstes zu beheben ist
  • Lokale App-Sitzungen, bei denen du Bedienaktionen und Ereignisse im Lebenszyklus der App kompakt protokollieren und ihre Reihenfolge über mehrere Durchläufe hinweg vergleichen möchtest

Inhalt

    ← Alle Anwendungsfälle

    Telemetrie für eine Mac-App ergänzen

    Protokolliere mit Codex und Logger, was eine Funktion deiner Mac-App tut. Starte die App und prüfe im macOS-Systemprotokoll, ob die erwartete Aktion ausgeführt wurde.

    Erfasse mit Codex und dem Plugin „Build macOS Apps“ einige aussagekräftige Logger-Ereignisse für Fenster, Seitenleisten, Befehle oder die Synchronisierung. Starte dann die App und prüfe in der Konsole oder mit log stream, ob die erwarteten Aktionen ausgeführt wurden.

    Advanced
    30m

    Erfasse mit Codex und dem Plugin „Build macOS Apps“ einige aussagekräftige Logger-Ereignisse für Fenster, Seitenleisten, Befehle oder die Synchronisierung. Starte dann die App und prüfe in der Konsole oder mit log stream, ob die erwarteten Aktionen ausgeführt wurden.

    Advanced
    30m

    Besonders geeignet für

    • Funktionen in Mac-Apps, bei denen Codex einzelne Schritte zuverlässig nachvollziehen muss, etwa das Öffnen eines Fensters, eine geänderte Auswahl in der Seitenleiste, einen Menübefehl, eine Aktion in der Menüleiste, einen wichtigen Schritt bei der Synchronisierung oder den Wechsel zu einem alternativen Ablauf
    • Debugging mit Codex, wenn der Agent den Code korrigieren, die App erneut starten und anhand der Protokolle entscheiden soll, was als Nächstes zu beheben ist
    • Lokale App-Sitzungen, bei denen du Bedienaktionen und Ereignisse im Lebenszyklus der App kompakt protokollieren und ihre Reihenfolge über mehrere Durchläufe hinweg vergleichen möchtest

    Skills und Plug-ins

    • Nutze die Skills für macOS-Telemetrie und für das Kompilieren und Starten der App. Ergänze damit die strukturierte Protokollierung mit `OSLog`, starte die App und teste den Ablauf in der Benutzeroberfläche. Prüfe die erfassten Ereignisse in der Konsole oder mit `log stream`.
    Skill Nutzen
    Build macOS Apps Nutze die Skills für macOS-Telemetrie und für das Kompilieren und Starten der App. Ergänze damit die strukturierte Protokollierung mit `OSLog`, starte die App und teste den Ablauf in der Benutzeroberfläche. Prüfe die erfassten Ereignisse in der Konsole oder mit `log stream`.

    Prompt für den Einstieg

    Use the Build macOS Apps plugin to add lightweight unified logging around [name one Mac feature or action flow], then run the app and verify from logs that those events fire in the expected order. Constraints: - Prefer `Logger` from `OSLog`, not `print`, and create a clear subsystem/category pair for this feature so the logs are easy to filter. - Log one concise line for each important action boundary or state transition: for example window opened, sidebar selection changed, menu command invoked, sync started, sync finished, or fallback path taken. - Keep permanent `info` logs stable and high signal. Use `debug` only for noisy local details, and remove or demote temporary instrumentation before finishing. - Do not log secrets, auth tokens, personal data, or raw document contents. If an identifier must be logged, choose the safest privacy annotation and explain why. - Build and run the app, exercise the feature path yourself, and verify the events with Console or a focused `log stream` predicate. - If the flow is long, intermittent, or easier to reproduce by hand, save the filtered log stream to a small local session trace file, let me manually exercise the app if needed, then read that file back and summarize the event timeline. - If an expected event does not appear, move the log closer to the suspected control path, rerun the flow, and continue until the logs explain what happened. Deliver: - the new logger setup and the exact events you added - the Console filter or `log stream` predicate you used - a short before/after summary of what the logs now make observable - the saved trace file and timeline summary if this became a longer capture session - one or two representative log lines that prove the flow is instrumented correctly
    Use the Build macOS Apps plugin to add lightweight unified logging around [name one Mac feature or action flow], then run the app and verify from logs that those events fire in the expected order. Constraints: - Prefer `Logger` from `OSLog`, not `print`, and create a clear subsystem/category pair for this feature so the logs are easy to filter. - Log one concise line for each important action boundary or state transition: for example window opened, sidebar selection changed, menu command invoked, sync started, sync finished, or fallback path taken. - Keep permanent `info` logs stable and high signal. Use `debug` only for noisy local details, and remove or demote temporary instrumentation before finishing. - Do not log secrets, auth tokens, personal data, or raw document contents. If an identifier must be logged, choose the safest privacy annotation and explain why. - Build and run the app, exercise the feature path yourself, and verify the events with Console or a focused `log stream` predicate. - If the flow is long, intermittent, or easier to reproduce by hand, save the filtered log stream to a small local session trace file, let me manually exercise the app if needed, then read that file back and summarize the event timeline. - If an expected event does not appear, move the log closer to the suspected control path, rerun the flow, and continue until the logs explain what happened. Deliver: - the new logger setup and the exact events you added - the Console filter or `log stream` predicate you used - a short before/after summary of what the logs now make observable - the saved trace file and timeline summary if this became a longer capture session - one or two representative log lines that prove the flow is instrumented correctly

    Setze einen Logger dort ein, wo die Fehlersuche stockt

    Wenn du bei einem Ablauf in einer Mac-App nur weißt, dass „irgendetwas passiert ist“, kommst du oft nicht weiter, indem du allein den Code prüfst. Bitte Codex, für einen bestimmten Ablauf einige aussagekräftige Einträge im zentralen Protokoll von macOS zu ergänzen. Lass Codex dann die App starten, den Ablauf auslösen und in der App „Konsole“ oder mit log stream prüfen, ob die erwarteten Ereignisse eingetreten sind.

    Verwende dafür das Plugin „Build macOS Apps“. Der zugehörige Skill für macOS-Telemetrie beschränkt sich bewusst auf das Wesentliche. Verwende Apples Logger, wähle eine eindeutige Kombination aus Subsystem und Kategorie und protokolliere Beginn und Ende von Aktionen sowie Zustandswechsel. Lass sensible Nutzdaten aus. Erstelle und starte die App lokal und prüfe, ob das Ereignis im Protokoll erscheint. So siehst du, ob die Instrumentierung tatsächlich funktioniert.

    Warum Telemetrie bei der Entwicklung mit Agenten hilft

    Mit aussagekräftigen Logs kann Codex nach jedem Patch denselben Ablauf überprüfen. Der Agent kann die App starten, den Ablauf durchspielen, die gefilterten Logs auswerten und anhand der Ergebnisse entscheiden, was er als Nächstes am Code ändert. So musst du nicht jedes Fenster, jede Menüaktion oder jeden Zustandswechsel bei der Synchronisierung selbst prüfen.

    Das ist besonders bei drei Arbeitsweisen hilfreich:

    • Selbstständige Fehlersuche: Codex ergänzt Logs für einen auffälligen Ablauf, startet die App, klickt in die Seitenleiste oder löst einen Befehl aus. Anhand der protokollierten Ereignisfolge korrigiert Codex den Code, der den Zustand aktualisiert. Anschließend wiederholt Codex denselben Ablauf, bis die Logs mit dem Verhalten der Benutzeroberfläche übereinstimmen.
    • Aufzeichnung einer App-Sitzung: Codex ergänzt je ein Ereignis für den App-Start, das Öffnen eines Fensters, die Auswahl in der Seitenleiste sowie für den Beginn, den erfolgreichen Abschluss und das Scheitern eines Imports. Dann führt Codex eine lokale Sitzung durch und fasst die Ereignisse chronologisch zusammen. So fällt auf, wenn Zustandswechsel fehlen oder in der falschen Reihenfolge erfolgen.
    • Aufzeichnung während der manuellen Fehlersuche: Codex startet die App mit aktivierter Protokollierung und lässt einen gefilterten Logstream mitlaufen, während du einen kniffligen Ablauf von Hand durchspielst. Anschließend wertet Codex die Aufzeichnung aus und schlägt auf dieser Grundlage den nächsten Patch vor.

    Beschränke die Instrumentierung auf wenige, gut filterbare Einträge

    Bitte Codex, pro Funktionsbereich einen Logger einzurichten. Nicht jede Zustandsänderung braucht einen dauerhaften Logeintrag. Mit Kategorien wie Windowing, Commands, MenuBar, Sidebar, Sync oder Import kannst du die Logs bei der nächsten Fehlersuche gezielt filtern.

    import SwiftUI
    
    struct SidebarItem { let id: String }
    @MainActor private var selection: String?
    import OSLog
    
    private let logger = Logger(
      subsystem: Bundle.main.bundleIdentifier ?? "SampleApp",
      category: "Sidebar"
    )
    
    @MainActor
    func selectItem(_ item: SidebarItem) {
      logger.info("Selected sidebar item: \(item.id, privacy: .public)")
      selection = item.id
    }

    Verwende info für knappe Meldungen zu Aktionen und Lebenszyklusereignissen, die auch später noch nützlich sind. Nutze debug für ausführlichere Angaben zum lokalen Zustand, die du vor Abschluss der Aufgabe entfernen oder auf eine niedrigere Protokollstufe setzen kannst. Ergänze Signposts nur, wenn du die Dauer eines Vorgangs misst.

    Lass Codex das Ereignis anhand der Logs nachweisen

    Mit den Logger-Aufrufen allein ist die Prüfung noch nicht abgeschlossen. Bitte Codex, die App zu starten und den instrumentierten Ablauf auszulösen. Lass dir den genauen Filter aus der App „Konsole“ oder das verwendete Prädikat für log stream zusammen mit ein oder zwei typischen Logzeilen zeigen.

    log stream --style compact --predicate 'subsystem == "com.example.app" && category == "Sidebar"'

    Fehlt ein erwartetes Ereignis, bitte Codex, den Logaufruf näher an den vermuteten Ausführungspfad zu verschieben und denselben Ablauf erneut durchzuspielen. Lass Codex das wiederholen, bis die Logs zeigen, was passiert ist. Wenn du einen Absturz oder einen Backtrace untersuchen musst, wechsle zum Debugging-Workflow des Plugins für das Erstellen und Ausführen der App. Beschränke die Telemetrie dabei auf Beginn und Ende der Aktionen.

    Speichere die Sitzungsaufzeichnung für einen späteren Codex-Durchlauf

    Bei langwierigen oder sporadischen Fehlern kannst du Codex bitten, einen gefilterten Logstream in einer kleinen lokalen Trace-Datei zu speichern, den zeitlichen Ablauf zusammenzufassen und die Datei im Workspace zu belassen. So kann Codex später dieselben Ereignisse untersuchen, ohne die gesamte Sitzung aus dem Gedächtnis nachstellen zu müssen. Das erleichtert die Fehlersuche über mehrere Durchläufe hinweg. In einem Durchlauf kann der Agent die Ereignisse aufzeichnen und in einem weiteren das Verhalten vor und nach einem Patch vergleichen.

    Das funktioniert auch, wenn du einen Teil der Sitzung selbst steuern musst. Bitte Codex, die App zum Debuggen mit aktivierter Protokollierung zu starten und eine gefilterte Aufzeichnung zu beginnen. Codex soll warten, während du das Problem von Hand reproduzierst, und anschließend die gespeicherte Trace-Datei auswerten.

    Praktische Tipps

    Instrumentiere jeweils nur eine Funktion

    Beginne mit einem einzelnen Ablauf, etwa der Auswahl in einer Seitenleiste, dem Öffnen eines Fensters, einem Befehl oder einem Synchronisierungsvorgang. So bleibt die Ereignisfolge überschaubar. Sobald dieser Ablauf zuverlässig funktioniert, kann Codex nach demselben Muster weitere, verwandte Abläufe instrumentieren.

    Berücksichtige den Datenschutz im Prompt

    Bitte Codex, jede protokollierte Kennung zu erläutern und weder Geheimnisse noch personenbezogene Daten oder unverarbeitete Inhalte in das zentrale Protokoll zu schreiben. Für die lokale Fehlersuche genügen meist wenige Ereignistypen.

    Nimm Beispielausgaben in die abschließende Zusammenfassung auf

    Anhand typischer Logzeilen lässt sich die Änderung besser nachvollziehen als anhand der Aussage „Telemetrie wurde hinzugefügt“. Bitte Codex, das Filterprädikat anzugeben und die Aktionen kurz in zeitlicher Reihenfolge aufzulisten. So kann der Agent die Prüfung beim nächsten Durchlauf wiederholen.

    Tech-Stack

    Was du brauchst

    Protokollierung in der App

    Standardoptionen

    Logger aus OSLog

    Warum du es brauchst

    Mit der strukturierten Protokollierung von macOS kann Codex gezielt die Ereignisse herausfiltern, die für den getesteten Ablauf relevant sind. So kommt der Code ohne eine Vielzahl von print-Anweisungen aus.

    Was du brauchst

    Arbeitsablauf des Agenten

    Warum du es brauchst

    Die Skills des Plugins für Telemetrie und für das Kompilieren und Starten der App sind aufeinander abgestimmt. Damit kannst du einen Ablauf instrumentieren, die App starten, die Protokolle prüfen und die Erfassung auf die aussagekräftigen Ereignisse eingrenzen.

    Was du brauchst

    Überprüfung zur Laufzeit

    Standardoptionen

    Console.app und log stream --predicate ...

    Warum du es brauchst

    Gibt der Agent den verwendeten Protokollfilter zusammen mit einer Beispielausgabe weiter, kannst du die Prüfung bei späteren Durchläufen wiederholen und sehen, ob die neue Instrumentierung die erwarteten Ereignisse erfasst.

    Was du brauchst Standardoptionen Warum du es brauchst
    Protokollierung in der App Logger aus OSLog Mit der strukturierten Protokollierung von macOS kann Codex gezielt die Ereignisse herausfiltern, die für den getesteten Ablauf relevant sind. So kommt der Code ohne eine Vielzahl von print -Anweisungen aus.
    Arbeitsablauf des Agenten Plugin „Build macOS Apps“ Die Skills des Plugins für Telemetrie und für das Kompilieren und Starten der App sind aufeinander abgestimmt. Damit kannst du einen Ablauf instrumentieren, die App starten, die Protokolle prüfen und die Erfassung auf die aussagekräftigen Ereignisse eingrenzen.
    Überprüfung zur Laufzeit Console.app und log stream --predicate ... Gibt der Agent den verwendeten Protokollfilter zusammen mit einer Beispielausgabe weiter, kannst du die Prüfung bei späteren Durchläufen wiederholen und sehen, ob die neue Instrumentierung die erwarteten Ereignisse erfasst.

    Verwandte Anwendungsfälle