在 iOS 模擬器裡復現和修 Bug

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
iOS 模擬器	simulator	在 Mac 上模擬 iOS 裝置的環境。
復現	reproduce	穩定重現 bug 才能可靠修復。
迴歸驗證	regression check	確認修復沒引入新問題。

不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你在 iOS 模擬器裡規劃復現並修復一個 bug 的任務。

你是 iOS 模擬器 bug 修復規劃顧問，幫我把一個 bug 的復現和修復拆成可靠的步驟。

【角色】
你熟悉在 iOS 模擬器裡復現和修 bug 的流程，知道先穩定復現再定位、修復後要回歸驗證。

【輸入】
- bug 的現象和觸發條件：___
- 涉及的介面 / 模組：___
- 是否能穩定復現：___
- 我的 iOS 開發經驗：___

【工作流程】
1. 先在模擬器裡穩定復現 bug
2. 讓 Codex 據復現路徑定位根因
3. 給最小修改方案
4. 修復後做迴歸驗證

【輸出規範】
▌一、穩定復現的步驟
▌二、根因定位思路
▌三、最小修複方案
▌四、迴歸驗證方法

【硬約束】
- 先穩定復現再修，不憑猜改
- 最小改動，不順手重構
- 修復後必須迴歸驗證
- 改動在模擬器實際驗證
- 不確定的 API 標註需查官方文件
- 修復方案先在模擬器跑通驗證，確認 bug 真的沒了再提交，別隻憑程式碼看著對就收工

用 Codex 調 iOS bug，最好讓它擁有完整 simulator loop：選擇 app target，啟動 Simulator，檢查目前螢幕，執行復現路徑，收集 logs 和 screenshots，需要時看 stack trace，修改程式碼，再跑同一路徑驗證修復。

iOS 除錯先要證據，再改程式碼。讓 Codex 記錄 simulator、scheme、復現步驟、截圖、記錄或 stack trace，否則修復很難 review。

官方頁面：https://developers.openai.com/codex/use-cases/ios-simulator-bug-debugging

適合什麼任務

場景	Codex 應該做什麼
bug 只在特定 tap、scroll、form entry 後出現	用 Simulator 真實執行復現路徑
crash、hang、broken navigation 需要證據	收集 logs、screenshots、view hierarchy、LLDB backtrace
團隊希望 Codex 跑完整 reproduce-fix-verify loop	自己復現、定位、修復，再重新驗證

使用的能力

能力	用法	連結
`build-ios-apps`	用 iOS debugger agent 透過 XcodeBuildMCP build、launch、inspect、drive Simulator，並收集 logs、screenshots、stack traces	https://github.com/openai/plugins/tree/main/plugins/build-ios-apps

相關官方說明：

Build iOS Apps plugin：https://github.com/openai/plugins/tree/main/plugins/build-ios-apps
Model Context Protocol：https://developers.openai.com/codex/mcp
Agent skills：https://developers.openai.com/codex/skills

起始提示詞

請使用 Build iOS Apps plugin 和 XcodeBuildMCP，直接在 Simulator 中復現這個 bug，診斷 root cause，並實現一個小修復。

Bug report：
[描述 expected behavior、actual bug，以及任何已知 screen 或 account setup。]

約束：
- 先檢查 project、scheme 和 simulator 是否已經選定。如果沒有，請發現正確的 Xcode project 或 workspace，選擇 app scheme，選擇 simulator，並在本 session 後續複用這套 setup。
- 在 Simulator 中 build 並 launch app；開始互動前，先用 UI snapshot 或 screenshot 確認正確 screen 可見。
- 自己在 simulator 裡透過 tapping、typing、scrolling 和 swiping 執行準確復現路徑。優先使用 accessibility labels 或 IDs，不要依賴 raw coordinates；layout 變化後，下一步操作前重新讀取 UI hierarchy。
- 除錯時捕獲證據：visual state 用 screenshots，failure 附近用 simulator logs；如果像 crash 或 hang，再收集 LLDB stack frames 或 variables。
- 如果 simulator 尚未 boot，請 boot 一個，並告訴我選擇了哪個 device 和 OS。如果需要 credentials 或特殊 fixture，暫停並只詢問這個缺失輸入。
- 做能解決 bug 的最小程式碼改動，然後重新執行 simulator flow，並準確說明你如何驗證修復。

交付：
- Codex 執行的 reproduction steps
- 解釋 bug 的關鍵 screenshots、logs 或 stack details
- code fix 以及它為什麼有效
- 最終驗證使用的 simulator 和 scheme

這個 prompt 要求 Codex 先復現和收集證據，再改程式碼。不要讓它跳過 simulator evidence 直接猜修復。

需要	推薦預設值	原因
Simulator automation	XcodeBuildMCP	覆蓋 simulator setup、build/launch、UI snapshots、taps、typing、gestures、screenshots、log capture、debugger attachment
Agent workflow	Build iOS Apps plugin	iOS debugger agent 提供 simulator-first loop，用於復現 bug、收集證據、驗證修復
App observability	`Logger`、`OSLog`、LLDB、Simulator screenshots	Codex 可以用 logs 和 debugger state 解釋問題，並儲存修復前後的 UI evidence

給 Codex 完整 Simulator Loop

這個用例最適合讓 Codex 按完整鏈路工作：

發現 Xcode project 或 workspace。
選擇 app scheme。
選擇或啟動 simulator。
build、install、launch app。
讀取 UI accessibility hierarchy。
按復現步驟 tap、type、scroll、swipe。
收集 screenshots、simulator logs、LLDB stack frames。
修改最小程式碼。
重新執行同一路徑驗證。

如果 Codex 還沒選定 project、scheme 和 simulator，先讓它 discover，並在後續 session 複用這個 setup。

XcodeBuildMCP 能做什麼

實用 capability groups：

Project and simulator discovery：檢查 app target 和 simulator，發現 Xcode project/workspace，列舉 schemes，找到或啟動 simulator。
Build and launch control：build active app target，安裝並啟動 simulator build，需要時 relaunch with log capture，解析 app bundle id。
UI inspection and interaction：讀取 accessibility hierarchy，截圖，tap controls，type fields，scroll lists，執行 edge swipes 或其他 gestures。
Logs and debugger state：stream simulator logs，attach LLDB，set breakpoints，檢查 stack frames 和 local variables，執行 debugger commands。

關鍵習慣：tap 前先 inspect view tree。優先用 accessibility labels 或 IDs，不要猜 raw screen coordinates。