Claude Code and Xcode: Setup, Changes, and Build Checks

Claude Code is a terminal tool, not an Xcode extension. You run it in a terminal window alongside Xcode and review its edits in the editor or through a build before accepting them. The workflow is straightforward: give Claude Code the project context, ask it to make a focused change, verify the result compiles and the tests pass, and record what you learned.

Xcode projects have specific requirements that Claude Code needs to know about: target names, Swift version, dependency management setup, and which files are generated. Tools like fenbs keep those requirements and the decisions behind them in a shared record that every Claude Code session can read.

How do you run Claude Code with an Xcode project?

Open a terminal in the same directory as your .xcodeproj or .xcworkspace file. Run claude there. Claude Code will see the project files and can read, edit, and create source files in the directory. Xcode does not need to be closed; the two tools can run side by side.

Keep Xcode's "Automatically refresh" setting enabled so that file changes from Claude Code appear in the editor without a manual reload. If you add or remove files through Claude Code, refresh the project navigator in Xcode to pick up the changes.

How do you give Claude Code project context?

Place a CLAUDE.md at the project root. Include the key facts Claude Code needs to work effectively on your specific project:

• The minimum iOS and macOS deployment targets.
• The Swift version and any language features in use.
• The dependency manager and how to resolve packages (Swift Package Manager, CocoaPods, Carthage).
• How to build from the command line — the scheme name, destination, and any required environment variables.
• Files or directories that are generated and should not be edited directly.
• Naming conventions and code style rules the project follows.

Standing decisions — "always use async/await rather than completion handlers," "do not add new CocoaPods dependencies without approval" — belong in fenbs Decisions and rules rather than CLAUDE.md, so they are visible to connected sessions without re-reading the entire project file.

Review the CLAUDE.md whenever you make a significant structural change to the project, such as adding a new target or switching dependency managers. Confirm it still accurately describes the build commands and constraints so future sessions do not inherit outdated instructions.

How do you verify edits through Xcode builds?

After Claude Code edits a Swift file, build the project from the command line before reviewing the change in Xcode. A build error surfaces immediately rather than after you have moved on to the next task.

xcodebuild -scheme YourScheme -destination "platform=iOS Simulator,name=iPhone 15" build

Adjust the scheme and destination to match your project. If your project uses a workspace rather than a project file, use the -workspace flag instead of -project. For the first run, ask Claude Code to echo the correct build command for your setup, then save it in CLAUDE.md so all future sessions use it.

How do you run unit tests from the command line?

Use xcodebuild test with the test target and a simulator destination. This lets Claude Code run the tests itself and see the pass or fail result, rather than requiring you to switch to Xcode and run them manually.

xcodebuild test -scheme YourScheme -destination "platform=iOS Simulator,name=iPhone 15"

Give Claude Code a rule in CLAUDE.md or the task description: always run the tests after making a change and report whether they passed. A test run that Claude Code skips leaves you with less confidence in the edit.

What decisions and lessons should you record?

Xcode projects accumulate project-specific knowledge that is easy to lose between sessions. When a debugging session surfaces why an approach does not work in Swift or on a specific iOS version, that knowledge is worth recording as a lesson so the next session does not repeat the investigation.

Architecture choices made during a Claude Code session — "use the repository pattern for network calls in this project," "store user preferences in UserDefaults for now" — are decisions that a future assistant needs to know. Recording them in fenbs means they persist across machines and sessions.

How to do this with fenbs

1. Create a free account and add the Xcode project with its deployment targets, dependencies, and build command.
2. Connect Claude Code to fenbs from Integrations. Place a CLAUDE.md at the project root with build instructions and the command to check for new context at session start.
3. Ask Claude Code to read the project context before making any changes. Confirm it can state the deployment target, the build command, and the current task correctly.
4. After each significant debugging session, record what was learned as a fenbs lesson. Link it to the relevant task so future sessions see it before tackling the same area.
5. Before stopping, save task progress and Where we left off to fenbs. Include which tests passed, which failed, and what the next step is.

fenbs does not interface with Xcode or read .xcodeproj files. It holds the record of what the project needs and what sessions have learned. For understanding how Claude Code handles parallel working copies when you need to test a change without touching the main project, the Claude Code worktrees guide covers that setup.