挙動を追いにくい箇所への Logger の追加

Mac アプリで「何かが起きた」ことは分かっても、コードレビューだけでは何が起きたのか特定できない場合があります。そんなときは Codex に、調べたい挙動を一つ選び、判断の手がかりになるイベントをいくつか統合ログに記録するよう依頼します。続けてアプリを起動し、その挙動を引き起こす操作を行い、コンソールまたは log stream で想定どおりのイベントが発生したか確認してもらいます。

この一連の作業には Build macOS Apps プラグインを使います。プラグインの macOS テレメトリスキルは、計測に必要な作業を最小限に絞っています。Apple の Logger を使い、対象が分かりやすいサブシステムとカテゴリの組み合わせを選びます。操作の開始・終了と状態遷移を記録し、機密性の高いデータはログに含めません。計測コードが正しく動くと決めつけず、ローカルでアプリをビルドして実行し、イベントを確認します。

エージェントを使った開発でテレメトリが役立つ理由

適切なログがあれば、Codex はパッチを適用するたびに同じ手順で結果を検証できます。ウィンドウやメニュー操作、同期状態の変化を一つずつ人の目で確認してもらう代わりに、エージェントがアプリを起動して対象の操作を試し、ログを絞り込んで確認します。その結果をもとに、コードのどこを次に変更するか判断できます。

特に役立つのは、次の 3 つの進め方です。

• デバッグの自動化： Codex が問題の疑われる処理にログを追加し、アプリを起動してサイドバーをクリックするか、コマンドを実行します。出力されたログを順に読み、状態を更新する処理を修正します。ログの内容と UI の挙動が一致するまで、同じ操作を繰り返します。
• アプリのセッション記録： Codex がアプリの起動、ウィンドウの表示、サイドバーでの選択、インポートの開始、完了、失敗にそれぞれイベントを一つ追加します。ローカルでアプリを実行して結果を時系列でまとめると、抜けている状態遷移や順序のずれが分かります。
• 手動操作の記録： Codex がログを有効にしてアプリを起動します。再現の難しい操作をユーザーが手動で行う間、Codex は対象を絞ったログストリームを記録し続けます。操作が終わったらセッションの記録を調べ、そのトレースをもとに次の修正案を提示します。

計測箇所の限定とログの絞り込み

状態が変わるたびにログを出力するコードを恒久的に組み込むのではなく、機能ごとにロガーを一つ用意するよう Codex に依頼します。Windowing、Commands、MenuBar、Sidebar、Sync、Import のように機能別のカテゴリを使うと、次にデバッグするときにログを絞り込みやすくなります。

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
}

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 に依頼します。手動で問題を再現する間は待機してもらい、操作が終わったら、保存したトレースファイルを読み取ってもらいます。

実践のヒント

機能を一つずつ計測

ログを順に追いやすくするため、まずは一つのサイドバー、ウィンドウ、コマンド、または同期処理に対象を絞ります。その処理が安定して動くようになったら、Codex は関連する処理にも同じ方法を適用できます。

プロンプトへのプライバシー要件の明記

ログに記録する識別子について一つずつ説明し、秘密情報、個人データ、コンテンツの生データを統合ログに書き込まないよう Codex に依頼します。ローカルでのデバッグには、通常、少数のイベント種別で十分です。

最終報告への出力例の掲載

「テレメトリを追加しました」という報告だけよりも、実際に出力されたログの例があれば、変更が意図どおりに動いたかを確かめやすくなります。次回のエージェント実行でも同じ手順で検証できるよう、絞り込みに使った述語と、実行した操作を時系列で簡潔にまとめたものを報告に含めるよう Codex に依頼します。