Ajoutez un Logger là où le comportement de l’application est difficile à expliquer

Dans une application Mac, il arrive que l’on constate que « quelque chose s’est passé » sans qu’une revue de code suffise à expliquer quoi. Demandez à Codex de consigner quelques événements révélateurs dans les journaux unifiés pour un comportement précis, de lancer l’application, de déclencher ce comportement et de vérifier dans Console ou avec log stream que les événements attendus se sont produits.

Utilisez le plugin Build macOS Apps pour suivre cette démarche. Son skill de télémétrie macOS se limite volontairement à l’essentiel. Utilisez le Logger d’Apple, choisissez un sous-système et une catégorie aux noms explicites, puis consignez le début et la fin des actions ainsi que les changements d’état. Évitez de journaliser des données sensibles. Compilez et lancez l’application en local, puis vérifiez que l’événement apparaît pour vous assurer que l’instrumentation fonctionne.

Pourquoi la télémétrie facilite le développement avec des agents

Des journaux bien conçus permettent à Codex de répéter les mêmes vérifications après chaque correctif. Au lieu de vous demander de vérifier manuellement chaque fenêtre, chaque action de menu ou chaque changement d’état de la synchronisation, l’agent peut lancer l’application, reproduire le scénario, examiner les journaux filtrés et s’appuyer sur ses observations pour décider de la prochaine modification du code.

Cette démarche se prête particulièrement bien à trois scénarios :

• Débogage autonome : Codex instrumente le parcours qui semble poser problème, lance l’application, clique dans la barre latérale ou déclenche une commande, puis examine la suite des événements consignés. Il corrige le code qui met à jour l’état et répète le parcours jusqu’à ce que les journaux concordent avec le comportement de l’interface.
• Enregistrement d’une session : Codex ajoute un événement pour chacune des étapes à observer : lancement de l’application, ouverture d’une fenêtre, sélection dans la barre latérale, début, fin ou échec d’un import. Il exécute ensuite une session en local et en résume la chronologie pour faire ressortir les transitions manquantes ou survenues dans le désordre.
• Capture pendant vos manipulations : Codex lance l’application avec la journalisation activée et maintient un flux de journaux filtré pendant que vous reproduisez manuellement un scénario délicat. Il examine ensuite la session enregistrée et s’appuie sur la trace pour proposer le prochain correctif.

Limitez l’instrumentation et facilitez le filtrage

Demandez à Codex d’utiliser un seul enregistreur par domaine fonctionnel. Évitez de consigner systématiquement chaque modification d’état. Des catégories fonctionnelles telles que Windowing, Commands, MenuBar, Sidebar, Sync ou Import facilitent le filtrage des journaux lors de la prochaine séance de débogage.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import 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
}

Utilisez info pour consigner brièvement les actions et les événements du cycle de vie qui resteront utiles dans la durée. Réservez debug aux détails plus nombreux sur l’état local, que vous pourrez supprimer ou passer à un niveau de journalisation inférieur avant de terminer la tâche. Ajoutez des points de mesure (signposts) uniquement lorsque vous mesurez une durée.

Demandez à Codex de confirmer l’événement à partir des journaux

Allez au-delà de l’ajout d’appels à Logger. Demandez à Codex de lancer l’application, de reproduire le parcours instrumenté et de vous fournir le filtre exact utilisé dans Console ou le prédicat passé à log stream, ainsi qu’une ou deux lignes représentatives du journal.

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

Si un événement attendu n’apparaît pas, demandez à Codex de rapprocher l’appel de journalisation du chemin d’exécution suspecté, de reproduire le même parcours et de répéter l’opération jusqu’à ce que les journaux expliquent ce qui s’est passé. Si vous devez finalement analyser un plantage ou une trace de pile, passez au workflow de débogage du plugin qui compile et lance l’application, et limitez la télémétrie au début et à la fin des actions.

Enregistrez une trace de session pour une prochaine exécution de Codex

Pour les bugs qui demandent du temps à reproduire ou qui ne surviennent que par intermittence, demandez à Codex d’enregistrer un flux de journaux filtré dans un petit fichier de trace local, d’en résumer la chronologie et de laisser le fichier dans l’espace de travail. Lors d’une prochaine exécution, Codex pourra examiner les mêmes événements sans avoir à reconstituer toute la session de mémoire. Cela facilite le débogage en plusieurs étapes lorsqu’une première exécution de l’agent sert à recueillir une trace et qu’une autre sert à comparer le comportement avant et après un correctif.

Cette méthode convient aussi lorsque vous devez effectuer vous-même une partie des manipulations. Demandez à Codex de lancer l’application en mode débogage avec la journalisation activée, de démarrer une capture filtrée, d’attendre pendant que vous reproduisez le problème manuellement, puis de lire le fichier de trace enregistré une fois vos manipulations terminées.

Conseils pratiques

Instrumentez une seule fonctionnalité à la fois

Commencez par une seule barre latérale, une fenêtre, une commande ou un parcours de synchronisation pour que la suite des événements reste facile à examiner. Une fois ce parcours fiable, Codex peut appliquer la même méthode aux parcours associés.

Précisez les exigences de confidentialité dans le prompt

Demandez à Codex d’expliquer chaque identifiant consigné et d’éviter d’écrire des secrets, des données personnelles ou du contenu brut dans les journaux unifiés. Quelques types d’événements suffisent généralement pour le débogage local.

Incluez un extrait du journal dans le résumé final

Quelques lignes représentatives permettent de vérifier la modification bien plus facilement que la seule mention « la télémétrie a été ajoutée ». Demandez à Codex d’inclure le prédicat de filtrage et une brève chronologie des actions pour que l’agent puisse répéter la même vérification lors de sa prochaine exécution.