在除錯線索模糊之處加入一個 Logger

這個使用案例適用於只知道「發生了某件事」的 Mac 應用程式流程；這項線索太過模糊，無法單靠程式碼審查來除錯。請 Codex 針對一項行為加入少量資訊密度高的統一記錄、執行應用程式並觸發該行為，再透過主控台或 log stream 驗證預期事件是否已觸發。

在該迴圈中使用 Build macOS Apps 外掛程式。其 macOS 遙測技能有意保持輕量：使用 Apple 的 Logger、選擇清楚的 subsystem/category 配對、記錄操作邊界與狀態轉換、避免敏感酬載，並在本機建置/執行後驗證事件，而不是直接假設記錄機制已正確串接。

遙測為何有助於智慧體式工程

良好的記錄可在每次修補後，為 Codex 提供可重複執行的回饋迴圈。你不必手動檢查每個視窗、選單操作或同步轉換；智慧體可以執行應用程式、操作流程、檢查篩選後的記錄，再根據證據決定下一項程式碼變更。

這對以下三種智慧體工作迴圈尤其有用：

• 免手動操作的除錯迴圈： Codex 為可疑流程加入記錄機制、啟動應用程式、點按側邊欄或觸發指令、讀取產生的記錄序列、修補狀態更新路徑，然後重新執行相同流程，直到記錄與 UI 行為一致。
• 應用程式工作階段收集迴圈： Codex 為應用程式啟動、視窗開啟、側邊欄選取、匯入開始、匯入完成及匯入失敗各加入一個事件，接著執行本機工作階段並摘要產生的時間軸，讓遺漏或順序錯亂的轉換一目了然。
• 人工操作的擷取迴圈： Codex 啟動已啟用記錄功能的應用程式，在你手動操作棘手流程時持續執行精準篩選的記錄串流，之後再檢查擷取的工作階段，並根據該追蹤記錄提出下一項修補建議。

讓記錄機制保持精簡且易於篩選

請 Codex 為每個功能範圍各使用一個 logger，不要為每次狀態異動都新增一行永久記錄。使用 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 記錄雜訊較多的本機狀態細節；後者可能會在任務完成前移除或降低層級。只有在測量一段持續時間時才加入 signpost，請勿預設加入。

要求 Codex 從記錄證明事件已觸發

重點不只是加入 Logger 呼叫。請 Codex 執行應用程式、觸發已加入記錄機制的流程，並提供所使用的確切主控台篩選條件或 log stream 述詞，以及一至兩行具代表性的記錄。

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

如果預期事件未出現，請 Codex 將記錄點移至更接近疑似控制路徑的位置、重新執行相同流程，並持續反覆處理，直到記錄能解釋發生了什麼事。如果任務演變為當機或回溯追蹤分析，請改用此外掛程式的建置/執行除錯工作流程，並讓遙測繼續聚焦於操作邊界。

儲存工作階段追蹤檔，供 Codex 下一輪使用

對於較長或偶爾才發生的錯誤，請 Codex 將精準篩選的記錄串流儲存到小型本機追蹤檔、摘要時間軸，並將該產出檔保留在工作區中。這樣後續執行 Codex 時，不必憑記憶重現整個工作階段，就能檢視同一份證據。若你想讓一次智慧體執行負責收集追蹤記錄，再由另一次執行比較修補前後的行為，這可讓多輪除錯更容易。

當工作階段的一部分需要由使用者操作時，這個做法也很實用。請 Codex 啟動應用程式並進入便於記錄的除錯迴圈、開始經篩選的擷取作業、等待你手動重現問題，並在你完成後讀取已儲存的追蹤檔。

實用提示

一次只為一項功能加入記錄機制

先從一項側邊欄、視窗、指令或同步流程著手，讓記錄序列保持容易檢查。如果該流程變得可靠，Codex 就能將相同模式擴展到相鄰流程。

將隱私權納入提示詞

請 Codex 說明記錄的每個識別碼，並避免將機密資訊、個人資料或原始內容寫入統一記錄。少量的事件詞彙通常就足以進行本機除錯。

在最終摘要中保留範例輸出

幾行具代表性的記錄，比只說「已加入遙測」更能讓人信任這項變更。請 Codex 納入篩選述詞與簡短的操作時間軸，讓下一次智慧體執行可重複使用相同的驗證迴圈。