| name | xcode-agentic |
| description | Agentic coding workflows for Xcode projects (Xcode 26.3+/27): building, testing, and running apps from the CLI (xcodebuild, xcrun, devicectl, simctl), connecting agents to Xcode via MCP (xcrun mcpbridge), Device Hub device management, self-validation loops (build → test → preview → simulator), Xcode skill/AGENTS.md integration, and SDK 27 migration gates. Use when an agent needs to build, test, run, profile, or verify an Xcode project, or when configuring Xcode for agent access.
|
| allowed-tools | ["Read","Glob","Grep","Bash"] |
Xcode Agentic Coding
How a coding agent should drive an Xcode project end-to-end. Grounded in the
Xcode 26.3–27 agentic tooling (WWDC26: sessions "What's new in Xcode",
"Xcode, agents, and you", "Get the most out of Device Hub").
Core Principle: Self-Validation Loop
Never report a change as done on compilation alone. Validate in increasing
fidelity, stopping at the first failure:
- Build the affected scheme
- Test — run the relevant test plan/suite (Swift Testing or XCTest)
- Preview/Playground — for UI changes, verify previews still render
- Simulator/Device run — install, launch, exercise the changed flow
(see
device-interaction skill for UI verification)
- Localization/accessibility — if strings or UI changed, confirm String
Catalogs updated and accessibility labels intact
CLI Toolbox
Discover before assuming
xcodebuild -list
xcodebuild -showdestinations -scheme <S>
xcrun simctl list devices available
xcrun devicectl list devices
Build and test
xcodebuild -scheme <S> -destination 'platform=iOS Simulator,name=<device>' build
xcodebuild -scheme <S> -destination '<dest>' test
xcodebuild -scheme <S> -destination '<dest>' test -only-testing:<Target>/<Suite>
- Prefer
-quiet for less noise; on failure re-run without it and read the
first error, not the last.
xcodebuild vs SwiftPM CLI — default to xcodebuild
Prefer xcodebuild whenever an Apple platform is the target. It is the
only CLI that builds for simulator/device destinations, honors schemes, test
plans, signing, and asset catalogs, and emits .xcresult bundles. Beware:
swift test runs on the host macOS only — it silently skips
iOS/watchOS/tvOS/visionOS-specific behavior, availability paths, and UI
frameworks. Test a package on the platform it ships on:
xcodebuild -scheme <Package> -destination 'platform=iOS Simulator,name=<device>' test
Reserve swift build / swift test for pure, host-platform SwiftPM packages
(no platform-conditional code), where they give a faster inner loop and Linux
parity.
Run on simulator / device
xcrun simctl boot "<device>" && xcrun simctl install booted <App.app> && xcrun simctl launch booted <bundle-id>
xcrun devicectl device install app --device <id> <App.app>
Profile / trace
xcrun xctrace record --template 'Time Profiler' --launch <App.app>
Xcode ↔ Agent Integration (Xcode 26.3+/27)
- MCP bridge: Xcode exposes its tools over MCP via
xcrun mcpbridge
(build/test, diagnostics, Swift REPL, preview rendering, doc search;
Xcode 27 sessions additionally announced debugger state,
scheme/destination switching, and build-setting/entitlement/Info.plist
inspection — verify against your Xcode's release notes). Requires enabling
Settings → Intelligence → Allow external agents to use Xcode tools.
Note: running xcrun mcpbridge with no arguments starts the stdio MCP
server (and fails if Xcode isn't running) — wire it into an MCP client
config rather than invoking it interactively.
- Project instructions: Xcode picks up
AGENTS.md at the repo root
automatically (Claude Code reads CLAUDE.md; keep one canonical file and
import it from the other).
- Skills: Xcode 27 reads Agent Skills (this SKILL.md format) from
~/Library/Developer/Xcode/CodingAssistant/<agent-config>/skills/, and
ships Apple-authored skills for SwiftUI adoption, UIKit modernization, and
security-settings auditing (mirrored in this harness as
swiftui-whats-new-27, uikit-app-modernization,
audit-xcode-security-settings).
- Plans: Xcode's plan mode produces editable Markdown plans — when working
alongside it, write plans as Markdown artifacts the user can edit.
SDK 27 Migration Gates (check before upgrading)
| Gate | Consequence | Skill |
|---|
| UIScene lifecycle is mandatory when building with the iOS 27 SDK — apps without a scene manifest won't launch (TN3187) | Blocker | uikit-app-modernization |
| Liquid Glass opt-out removed in Xcode 27 (per WWDC26 guidance; confirm in release notes) | Visual regression risk | apple-platforms |
@State becomes a macro (back-deployed) — some previously-compiling code errors | Compile errors with misleading "obvious" fixes | swiftui-whats-new-27 (state-macro reference) |
UIScreen.main, UIWindow(frame:), legacy app-delegate callbacks deprecated | Warnings → future removal | uikit-app-modernization |
Swift Testing gains issue severity, Test.cancel, flaky-test repetition, improved XCTest interop (announced WWDC26) | Opportunity, not blocker | test-modernizer |
Enhanced Security entitlement (com.apple.security.hardened-process), -fbounds-safety | Hardening opportunity | audit-xcode-security-settings, c-bounds-safety |
Concurrent Sessions & Simulator Resources
Multiple agent sessions on one Mac can race to boot simulator clones
(each ~1 GB RAM plus CoreSim XPC processes). Exhaustion produces a
distinctive signature: clones die with Mach error -308 (server died) and
tests "fail" as phantom 0.000s aborts that look like real bugs but are
infrastructure exhaustion — the failures are not in your code.
- If the machine may run concurrent agent sessions, serialize
xcodebuild build/test behind a machine-wide lock (e.g., a wrapper taking an
exclusive fcntl/flock lock on a fixed /tmp lockfile before invoking
xcodebuild). The bottleneck is shared CoreSim infrastructure, so the lock
must be OS-global, not per-repo.
- Under resource pressure, also pass
-parallel-testing-enabled NO
(optionally -maximum-parallel-testing-workers 1).
- On phantom 0.000s failures: check for the -308 signature and other running
sessions before debugging the tests themselves.
Guardrails
- Discover schemes/destinations before building — never guess names.
- One failing gate at a time: fix the first compiler/test error, rebuild,
repeat. Don't batch speculative fixes.
- Don't modify signing, provisioning, or CI lanes unless the task requires it.
- Long builds: run in background and continue useful work; never poll in a
sleep loop.
- Version facts here describe Xcode 26.3–27; verify against
xcodebuild -version and release notes when behavior seems off.
Related Skills
| Need | Skill |
|---|
| UI verification on simulator/device | device-interaction |
| Security build settings audit | audit-xcode-security-settings |
| XCTest → Swift Testing migration | test-modernizer |
| UIKit scene/lifecycle modernization | uikit-app-modernization |
| SwiftUI SDK 27 changes | swiftui-whats-new-27 |
