デバッグの手がかりが曖昧な箇所に Logger を 1 つ追加

このユースケースは、Mac アプリのフローで「何かが起きた」というだけでは情報が曖昧すぎて、コードレビューだけではデバッグできない場合を対象としています。Codex に、1 つの動作の要所へ重要な情報に絞った少数の統合ログを追加し、アプリを実行してその動作を発生させ、想定したイベントが発生したことをコンソールまたは log stream で確認するよう依頼します。

このループには、Build macOS Apps プラグイン を使います。その macOS テレメトリスキルは、意図的に軽量に設計されています。Apple の Logger を使い、明確なサブシステムとカテゴリの組み合わせを選び、アクションの区切りと状態遷移をログに記録し、機密性の高いデータは避けます。また、計測が正しく組み込まれていると思い込まず、ローカルでビルド／実行した後にイベントを検証します。

エージェント型エンジニアリングでテレメトリが役立つ理由

適切なログがあれば、Codex はパッチを適用するたびに再現可能なフィードバックループを回せます。すべてのウィンドウ、メニュー操作、同期遷移を手動で確認するよう求める代わりに、エージェントがアプリを実行してフローを操作し、絞り込んだログを調べ、証拠に基づいて次のコード変更を決定できます。

これは特に、次の 3 つのエージェント型ループで役立ちます：

• ハンズフリーのデバッグループ： Codex が問題の疑われるフローに計測を追加し、アプリを起動してサイドバーをクリックするかコマンドを実行し、出力されたログシーケンスを読み取ります。その後、状態更新の処理経路にパッチを適用し、ログと UI の動作が一致するまで同じフローを再実行します。
• アプリセッション収集ループ： Codex がアプリ起動、ウィンドウを開く操作、サイドバーの選択、インポート開始、インポート完了、インポート失敗のそれぞれにイベントを 1 件ずつ追加します。その後、ローカルセッションを実行して結果のタイムラインを要約するため、欠落した遷移や順序の誤った遷移が明確になります。
• 人が操作するキャプチャループ： Codex がログを有効にしてアプリを起動し、対象を絞ったログストリームを実行したまま、ユーザーが難しいフローを手動で操作できるようにします。その後、キャプチャしたセッションを調べ、そのトレースに基づいて次のパッチを提案します。

小規模で絞り込みやすい計測

状態変更ごとに恒久的なログを 1 行ずつ残すのではなく、機能領域ごとにロガーを 1 つ設けるよう Codex に依頼します。機能カテゴリを Windowing、Commands、MenuBar、Sidebar、Sync、Import などにすると、次回のデバッグでログを簡単に絞り込めます。

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
}

継続的に役立つ簡潔なアクションイベントとライフサイクルイベントには info を使い、タスク完了前に削除したりレベルを下げたりする可能性のある、ノイズの多いローカル状態の詳細には debug を使います。サインポストは時間区間を計測するときだけ追加し、デフォルトでは追加しないでください。

ログによるイベントの実証を Codex に依頼

価値があるのは、Logger の呼び出しを追加することだけではありません。Codex にアプリを実行して計測対象のフローを発生させ、使用した正確なコンソールフィルターまたは log stream の述語と、代表的なログ 1～2 行を提示するよう依頼します。

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

想定したイベントが表示されない場合は、疑わしい制御経路により近い位置へログ出力を移し、同じフローを再実行して、何が起きたかをログで説明できるまで反復するよう Codex に依頼します。タスクがクラッシュやバックトレースの分析に発展した場合は、プラグインのビルド／実行デバッグワークフローに切り替え、テレメトリの対象はアクションの区切りに絞ってください。

後続の Codex 実行に備えたセッショントレースの保存

時間がかかるバグや断続的なバグでは、対象を絞ったログストリームを小さなローカルトレースファイルに保存し、タイムラインを要約して、その成果物をワークスペースに残すよう Codex に依頼します。そうすれば、後続の Codex 実行では、記憶を頼りにセッション全体を再現することなく、同じ証拠を調べられます。あるエージェント実行でトレースを収集し、別の実行でパッチ適用前後の動作を比較したい場合に、複数回にわたるデバッグが容易になります。

これは、セッションの一部を人が操作する必要がある場合にも有効です。Codex に、ログを取得しやすいデバッグループでアプリを起動し、絞り込んだキャプチャを開始して、ユーザーが問題を手動で再現する間は待機し、操作が終わったら保存済みのトレースファイルを読み取るよう依頼します。

実践的なヒント

一度に 1 つの機能への計測

ログシーケンスを確認しやすく保つため、まずサイドバー、ウィンドウ、コマンド、同期経路のいずれか 1 つから始めます。その経路の信頼性が確保できたら、Codex は同じパターンを隣接するフローに展開できます。

プロンプトにプライバシー要件を明記

ログに記録するすべての識別子について説明し、シークレット、個人データ、未加工のコンテンツを統合ログに書き込まないよう Codex に依頼します。ローカルデバッグには通常、ごく少数のイベント種別だけで十分です。

最終要約に出力例を記載

「テレメトリを追加しました」という説明より、代表的なログ行がある方が変更をはるかに信頼しやすくなります。Codex にフィルター述語と簡潔なアクションタイムラインを含めるよう依頼すると、次回のエージェント実行で同じ検証ループを再利用できます。