文章同步發表在我的個人 Blog

Swift 第一天：讓 Claude Code 接上 Xcode，跑出第一個畫面

Swift 第一天，目標是把 Day 7 整理的規範接起來。

先講結果：Xcode 設定、專案建立、規範檔都已完成，App 可以在模擬器上執行。這篇記錄每一個步驟如何執行，以及有卡關的地方。

1. Xcode 裝好了，卻叫不動

Xcode 已經在 /Applications 裡，版本是 26.6。可是在終端機裡叫它，會出現這個錯誤：

xcode-select: error: tool 'xcodebuild' requires Xcode, but active developer
directory '/Library/Developer/CommandLineTools' is a command line tools instance

原因是系統還指向以前裝的 Command Line Tools，不是完整的 Xcode，授權也還沒同意。要做三件事：

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer  # use full Xcode
sudo xcodebuild -license accept                                         # accept license
sudo xcodebuild -runFirstLaunch                                         # install components

這裡踩到一個小坑：在 Claude Code 裡用 ! 開頭直接跑這些指令，會出現 sudo: a terminal is required to read the password。! 模式沒辦法輸入密碼，要打開終端機自己貼。

跑完之後 xcodebuild -version 顯示 Xcode 26.6，就是切換成功了。

2. 建立專案

專案用 Xcode 的畫面建一次：File → New → Project → iOS → App。

建立好之後的結構，對照 Laravel 大概是這樣：

有兩個地方要注意：

• 新增檔案不用改專案設定檔：新版 Xcode 的專案是直接同步資料夾裡的檔案，AI 新增一個 .swift 檔，不用去改 Teammate.xcodeproj 裡的設定。以前每新增一個檔案都要改這個設定檔，改動一多就容易衝突
• 最低支援的 iOS 版本預設是 26.5：也就是最新版。家人的手機如果不是最新版，App 會裝不起來，這個要在裝到手機之前調整

3. 讓 Claude Code 接上 Xcode

Xcode 26.3 開始，Apple 在 Xcode 裡內建了 MCP，讓外面的 AI Agent 可以使用 Xcode 的工具，例如看編譯錯誤、查文件、看 Preview。

要先在 Xcode 裡打開：Settings → Intelligence → Model Context Protocol → Allow external agents to use Xcode tools。

同一頁上面還有一排 Agents，列著 Claude Agent、Codex、Gemini，旁邊有「Get」按鈕。這些是 Xcode 內建的 AI Agent，要在 Xcode 裡面用的。我用的是外面這個 Claude Code，所以不需要安裝。

Claude Code 這邊，比照 Apple 官方文件加上這個 MCP：

claude mcp add --transport stdio --scope local xcode -- xcrun mcpbridge

連接後遇到兩個狀況：

• Xcode 需要開著：這個 MCP 是橋接到正在執行的 Xcode，Xcode 關著的話直接失敗，錯誤訊息是 no running Xcode processes found
• 剛打開 Xcode 時會逾時：claude mcp get xcode 一開始顯示「Connected · tools fetch failed」，等 Xcode 開一陣子再測，就變成正常的「Connected」

工具清單裡有「build 並產生 Preview 截圖」這類工具，實際好不好用，等開始寫功能再看。目前驗證還是以 xcodebuild 為主，MCP 當輔助，因為 xcodebuild 的結果比較容易留下紀錄。

4. 規範檔長什麼樣子

先在 repo 裡初始化 Spectra，同時產生 Claude Code 和 Codex 用的 skill：

spectra init --tools claude,codex

接著把 Day 7 整理的東西寫進四份檔案：

CLAUDE.md 只有匯入加上幾行 Claude Code 專屬的說明，規則本身都在 AGENTS.md，這樣 Codex 和 Claude Code 讀到的是同一套。

openspec/config.yaml 裡的規則，之後每次用 Spectra 開規格都會自動套用，例如：

rules:
  specs:
    - Scenario 寫成可以觀察的行為，不寫實作方式
    - 會存資料的功能，要有「App 關掉重新打開，資料還存在」的情境
  tasks:
    - 每個 task 列出預期會修改的檔案
    - 「怎麼測試」跟「驗收條件」分開寫

另外補了 .gitignore，Xcode 的個人設定（xcuserdata/）和 build 產物不進 git。

5. 卡在模擬器

專案打開後，Xcode 右上角顯示「iOS 26.5 Not Installed」。這是 iOS 26.5 的平台和模擬器，要另外下載，我用指令下載：

xcodebuild -downloadPlatform iOS -architectureVariant arm64

總共 8.52 GB，從凌晨 00:50 下載到 04:23，花了三個半小時。

我想說不裝模擬器，至少先編譯看看有沒有錯，結果連編譯都不行：

error: iOS 26.5 is not installed. Please download and install the platform
from Xcode > Settings > Components.

Xcode 26 把 iOS 平台跟模擬器綁在一起，沒裝的話，不只不能跑模擬器，連 build 都跑不了。測試、Preview、Day 7 訂的驗收流程，全部都要等它下載完。

6. 第一次 build 和測試

模擬器裝好之後，照 AGENTS.md 裡寫的指令跑：

xcodebuild -project Teammate.xcodeproj -scheme Teammate \
  -destination 'platform=iOS Simulator,name=iPhone 17' build        # 9 seconds
xcodebuild -project Teammate.xcodeproj -scheme Teammate \
  -destination 'platform=iOS Simulator,name=iPhone 17' \
  -only-testing:TeammateTests test                                   # about 2 minutes

Xcode 範本的畫面只有一個空白清單，所以我另外請 Claude Code 做了一個「今天的交接」待辦畫面當 prototype：用假資料、可以打勾，還不會存資料。這是還在試、之後不一定會留下來的畫面，所以沒有開 Spectra 規格。

有一個地方值得注意：那 1 個通過的測試，是 Xcode 範本附的空測試，裡面一行檢查都沒有，也照樣顯示通過。所以「測試有跑、全部通過」還不夠，之後每個功能的測試，都要真的檢查到行為。

明天

Day 9 要決定 App 第一版做哪些功能：投票頁收集到的痛點，各自對應 App 的哪個功能、這次先做哪些、哪些先不做，順便把 plan.md 的功能清單正式整理好。