Step-by-step guide · 10 steps · about a weekend

Vibe Coding Native Swift iOS Apps

Vibe coding means you describe the app you want in plain English, let an AI agent write the Swift, and steer by running it and reacting to what you see. This guide takes you from an empty Mac to your own app on TestFlight, whether that's a tracker, a utility, a journal or your own idea, without losing control of the code.

By the Tle Apps team · Last updated October 2026 for Xcode 26 and Swift 6

DescribeSay what you want, in one small chunk
GenerateThe agent writes and edits Swift files
RunBuild in the Simulator and see it live
ReactFeed back errors, screenshots and taste

Repeat the loop, and commit to git every time something works.

Before you start

What you need, how long it takes, and whether this guide is for you.

💻 What you need

A Mac that runs the current version of Xcode. Xcode only runs on macOS.
Xcode, free from the Mac App Store (about 10–15 GB with the iOS Simulator).
An AI agent. Most cost about $20/month. See the tool chooser.
A free Apple Account to run the app on your own iPhone.
Apple Developer Program, $99/year. Only needed for TestFlight and the App Store (steps 9–10). You can wait until the app works.

⏱️ How long it takes

Setup (steps 1–3)1–2 hours
Build a working app (4–8)6–10 hours
Test & ship (9–10)2–4 hours
Apple's TestFlight / App Review~1–2 days

Rough estimates for a small app with three features. Bigger ideas take longer.

🙋 Who it's for

Total beginners: you've never written Swift. Follow every step and open the Go deeper panels.
Developers new to iOS: skim the cards, copy the prompts and skip the panels.
Not covered: apps that need accounts, a server or payments. This guide builds an app that stores its data on the device.

Pick your app type

The steps are the same for any small iPhone app. Pick the kind you want to build, and the example prompts in every step change to match.

Keep a list of things and the details about each one. The example is a reading list.

Also works for: Reading list, recipe box, plant care, gift ideas

Book list with the author and a reading status for each book.
Add book sheet with a title, an author and a status picker.
Detail screen with notes and a star rating.
Saved on the device with SwiftData, so your books are still there after the app closes.
Dark Mode, Dynamic Type, a friendly empty state and an app icon.

Books

📘Project Hail MaryAndy Weir · Finished

📗The HobbitJ.R.R. Tolkien · Finished

📙DuneFrank Herbert · Reading

📕CirceMadeline Miller · Want to read

Illustration of the finished app

Harder for a first app: anything that needs accounts, a server, payments, real-time multiplayer or AR. Start with something that keeps its data on the device, ship it, then add more.

Choose your AI agent

Pick one and stick with it. The guide works with all four, and the habits matter more than the tool.

Tool	Best for	Cost	How it builds and runs
Claude Code Matches this guide	Following this guide exactly. Every prompt and `CLAUDE.md` works as written.	Claude subscription, from about $20/month	Runs in the Terminal next to Xcode. Runs `xcodebuild` itself, and can drive the Simulator with XcodeBuildMCP.
Xcode's built-in agent	Total beginners who want everything in one window.	Included in Xcode. Needs a ChatGPT or Claude account; free use is limited.	Works inside Xcode and builds with the same Run button you use. Fewer moving parts.
Codex	People who already pay for ChatGPT.	Included with ChatGPT Plus, about $20/month	Terminal or app. Reads `AGENTS.md` instead of `CLAUDE.md` and runs `xcodebuild` itself.
Cursor	Developers who like a VS Code-style editor.	Free tier; Pro about $20/month	Agent edits files and runs `xcodebuild` in its terminal. You still run and sign the app in Xcode.

Prices change often, so check each vendor's site. Using Codex or another tool? Wherever the guide says CLAUDE.md, use that tool's rules file (for example AGENTS.md).

The guide

Ten steps in three phases. Tick each one off as you go.

0/10 done

Install your vibe stack

Step 1 · Setup

Done

You need Apple's toolchain to build. You also need an AI agent that can read your project, edit files and run commands, not just a chat window you copy from.

Xcode from the Mac App Store. Open it once to install the iOS Simulator and accept the license.
An agent: Claude Code, Codex, Cursor or Xcode's built-in agent. Not sure? Use the tool chooser.
Git (xcode-select --install). It's your undo button when a session goes in the wrong direction.
Optional: XcodeBuildMCP lets the agent build, run and screenshot the Simulator by itself (set up in step 4).

Sanity-check prompt

Check my machine for iOS development: print the active Xcode version, list available iOS simulators, and confirm git is installed. Don't change anything.

Write a one-page vibe brief

Step 2 · Setup

Done

The vibe still needs a direction. Spend 10 minutes writing down what the app is for before the AI writes any code.

One sentence: who the app is for and the one job it does.
Three core features for v1. Everything else goes on a "later" list.
Screens: list each screen and what the user can do there.
Non-goals: no login, no backend, no ads, unless you really need them.
Not sure what to build? Pick an app type for a ready-made starting point.

Brief prompt

I want to build [a reading list app] for iPhone. Interview me with up to 8 short questions, then write a one-page brief: purpose, 3 v1 features, screen list, data I need to store, and explicit non-goals. Save it as BRIEF.md.

Create the project and a rules file

Step 3 · Setup

Done

Create the Xcode project yourself so the project file is correct. Then give the agent a short rules file that it reads before every session.

New project: iOS App, Interface: SwiftUI, Storage: SwiftData. Then git init and make the first commit.
Rules file (CLAUDE.md / AGENTS.md): Swift 6, @Observable instead of ObservableObject, SwiftData, and no third-party packages without asking.
Include the build command so the agent can compile and check its own work (see step 4).

Rules prompt

Read BRIEF.md and the Xcode project. Write a short CLAUDE.md with: project layout, coding conventions (Swift 6, SwiftUI, @Observable, SwiftData, async/await), the exact xcodebuild command to build for the iPhone simulator, and a rule to ask before adding dependencies.

Close the feedback loop

Step 4 · Build

Done

Vibe coding works best when the agent can see compiler errors on its own instead of waiting for you to paste them. Set this up before building any features.

Agent builds: it runs xcodebuild after every change and fixes errors before handing control back.
You run: keep Xcode open, press ⌘R, and use the app like a user would.
Previews: ask for #Preview blocks with sample data so you can check each screen without tapping through the app.

Loop prompt

Build the app for the iPhone simulator using the command in CLAUDE.md. If it fails, fix the errors and rebuild until it succeeds. Then summarize what you changed in 3 bullets.

Go deeper Build command, XcodeBuildMCP, good vs. bad results

The build command for your rules file

xcodebuild -scheme YourApp -destination 'platform=iOS Simulator,name=iPhone 17' build

Replace YourApp with your scheme name and iPhone 17 with a simulator you have. This command lists them:

xcrun simctl list devices available

If the name doesn't match exactly, the build fails before it starts.

✅ A good result

The output ends with ** BUILD SUCCEEDED **.
The agent summarizes what it changed in a few lines instead of dumping code.

❌ A bad result

** BUILD FAILED ** with error: lines. A good agent reads these, fixes them and rebuilds without you.
The agent says "it should work now" but never ran the build. Reply: "Run the build command and show me the result."

Optional: let the agent see the Simulator

XcodeBuildMCP lets the agent launch the app and take screenshots, so it can check its own UI work. In Claude Code you add it with the command below. For other agents, follow the setup in the XcodeBuildMCP README.

claude mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@latest

Verify prompt

Build and launch the app in the iPhone simulator, take a screenshot, and describe what you see. Tell me anything that looks broken.

Troubleshooting

Symptom	Likely cause	Fix
"Unable to find a destination"	The simulator name doesn't exist	Run `xcrun simctl list devices available` and update CLAUDE.md
Builds for the agent but not in Xcode	Different scheme or a stale build	Product › Clean Build Folder (`⇧⌘K`), then rebuild
Agent edits `.xcodeproj` and breaks it	Project files are fragile	Add to rules: "Never edit the .xcodeproj file. Tell me what to add in Xcode."

Build one feature at a time

Step 5 · Build

Done

Ask for one feature, check the result and commit it before asking for the next one. Small requests keep the agent accurate and make it easy to undo a bad change.

Data first: start with the SwiftData @Model types, then the screens that use them.
Plan, then code: for anything bigger than one file, ask for a plan first and approve it.
Commit when it runs: git commit after each working feature. Run git restore . when a change goes wrong.

Feature prompt

Add feature 1 from BRIEF.md: [add and list books]. First tell me which files you'll add or change and why. Wait for my OK, then implement it, build, and fix any errors.

Go deeper Feature sizing, a worked example, fresh sessions

Right-sized vs. too big

Too big	Right-sized
"Build the whole reading list app"	"Add the Book model with a title, an author and a status"
"Add ratings, search and sharing"	"Add a 1–5 star rating to the book detail screen"
"Make it look good"	"Give the list screen a large title and more spacing between rows"

If you can't describe the feature in one sentence, split it.

A worked example: "add and list books"

You send the Feature prompt.
The agent replies with a plan, something like: "I'll add Book.swift (SwiftData model), BookListView.swift (list screen) and AddBookView.swift (sheet), and edit App.swift to add the model container."
You check the plan. Does it touch only what it needs to? If it wants to add a package or rewrite existing files, say "Don't do that. Use only built-in frameworks."
You approve. The agent writes the code, builds and fixes errors.
You run the app, add a book, close and reopen the app, and check the book is still there.
It works, so commit:

Commit prompt

Commit all changes with a clear message describing this feature. Then tell me what's left in BRIEF.md.

When to start a fresh session

The agent starts forgetting rules or repeating mistakes.
You've finished a feature and are starting an unrelated one.
Responses have gotten slow or vague.

A fresh session costs you nothing, because BRIEF.md and CLAUDE.md hold the context. Start with: "Read BRIEF.md and CLAUDE.md, then tell me where we are."

Rule of thumb: if you've gone more than an hour without a commit, you're taking too big a step.

Design the UI with screenshots

Step 6 · Build

Done

UI is where vibe coding works best. Show the agent a screenshot instead of describing pixels, then refine with how you want it to feel.

Show, don't tell: paste a sketch, a Figma frame or a Simulator screenshot (⌘S) with the result you want.
React with taste: "too cramped", "make it feel like Apple Weather", "add a satisfying spring when I check it off".
Stay native: use standard SwiftUI controls, SF Symbols and system colors. This gives you Dark Mode and Dynamic Type for free.

UI prompt

Here's a screenshot of the current book list screen [attach]. Make it feel calmer and more premium: more breathing room, a large title, a book icon on each row, and a spring animation when a book is marked as finished. Keep it native SwiftUI.

Go deeper Before and after, design words, native building blocks

What the UI prompt changes

Before

Books

Project Hail Mary

The Hobbit

Dune

After

Books

📘Project Hail Mary

📗The Hobbit

📙Dune

Words that work well with agents

You mean	Say
"Too crowded"	"Add more padding and spacing between rows"
"Boring"	"Add a clear visual hierarchy: a bold title, secondary text in gray"
"Looks cheap"	"Use system materials, SF Symbols and a consistent corner radius"
"Feels stiff"	"Add a subtle spring animation and haptic feedback on tap"
"Like a real app"	"Follow Apple's Human Interface Guidelines for a list-based app"

Native building blocks to name in prompts

NavigationStack: moving between screens.
.sheet: adding or editing something, then dismissing.
List vs. ScrollView: use List for rows, ScrollView for custom layouts.
ContentUnavailableView: a friendly empty state.
.sensoryFeedback: haptics.
SF Symbols: thousands of built-in icons that match the system font.

Don't forget the empty state

Empty state prompt

When there are no books yet, show a ContentUnavailableView with an SF Symbol, a short friendly message and a button to add the first book.

Refine in rounds. Change one thing per prompt, such as spacing, then colors, then animation. Take a screenshot after each round. If you change everything at once, you can't tell which change helped.

Add persistence, settings and polish Optional

Step 7 · Build

Done

The features work, but it doesn't feel finished yet. This is where many beginners get stuck, so take it one item at a time.

Persistence: force-quit the app and reopen it. Everything you added or changed should still be there.
Settings: a simple screen for preferences such as units, a default sort order or a reminder time, saved with @AppStorage.
App icon: design it in Icon Composer or as a 1024×1024 image, and add it in Xcode.
Feel: haptics on key actions, an accent color, and Dark Mode and large text that both look right.

Polish prompt

Do a polish pass, one item at a time, building after each: add a Settings screen using @AppStorage, add .sensoryFeedback when a book is marked as finished, set an accent color in the asset catalog, and check every screen in Dark Mode and at the largest Dynamic Type size. List anything you couldn't fix.

Go deeper Polish checklist, data safety

Polish checklist

Check	How
Data survives a restart	Add data, force-quit from the app switcher, reopen.
Dark Mode	In the Simulator press `⇧⌘A`, or go to Settings › Developer › Dark Appearance.
Large text	In Xcode, open Environment Overrides in the debug bar and drag Dynamic Type to the largest size.
Empty states	Delete everything. Every screen should still say something helpful.
App icon and name	Check the Home Screen. The name under the icon should not be cut off.

Be careful with your data model

Once testers have real data, renaming or deleting a SwiftData property can make the app lose their data or crash on launch. Before changing a @Model, ask:

Data safety prompt

I want to change the Book model to [describe change]. Will existing users lose data? If so, explain the safest migration with SwiftData before writing any code.

Debug with full context

Step 8 · Build

Done

When something breaks, give the agent everything you have. When it keeps failing, stop it and go back to the last commit.

Paste the whole thing: the exact error, the crash log or console output, and the steps to reproduce it.
Ask for a diagnosis first: "explain the cause before changing code" catches guesses before they turn into rewrites.
Three strikes: if the third fix attempt fails, git restore, start a fresh session, and describe the problem from the beginning.

Debug prompt

The app crashes when I [delete the last book]. Console output: [paste]. Explain the root cause first, then make the smallest fix, rebuild, and tell me how to verify it.

Go deeper Finding errors and crash logs, diagnosis first

Where to find the error information

Build errors: the Issue Navigator in Xcode (⌘5), or the agent's own build output.
Runtime errors: the console at the bottom of the Xcode window while the app runs. Press ⇧⌘C if it's hidden.
Crash location: the line Xcode highlights in red, plus the last 20 lines of console output.

Copy the exact text. A paraphrase like "it crashes when I tap delete" gives the agent much less to work with.

Ask for a diagnosis before a fix. If the agent can't explain the cause clearly, it is guessing, and guesses tend to turn into rewrites.

Seeing a specific error? Check the common errors table below the guide.

Test, review and harden

Step 9 · Test & Ship

Done

Before you ship, have the agent act as a reviewer and write tests, then test the app on a real iPhone yourself.

Swift Testing: generate @Test cases for your models and logic, including edge cases like empty, huge and duplicate inputs.
Review pass: ask for a review of data loss risks, concurrency warnings and retain cycles.
Real device: run on your own iPhone with VoiceOver, large text and Dark Mode turned on.

Review prompt

Act as a senior iOS reviewer. Review the whole project for bugs, data loss risks, Swift 6 concurrency issues and accessibility gaps. List findings by severity, then write Swift Testing @Test cases for the model layer and run them.

Ship to TestFlight and the App Store

Step 10 · Test & Ship

Done

The agent can draft all the paperwork. Signing and submitting stay with you in Xcode and App Store Connect. You need the $99/year Apple Developer Program from here on.

Assets: a 1024×1024 app icon, a launch screen, and screenshots taken from the Simulator.
Metadata: name and subtitle (30 characters each), a 100-character keyword field, a description and a privacy policy.
Upload: choose Product › Archive, then Distribute to TestFlight. Get feedback from a few testers, then submit for review.

Launch prompt

Using BRIEF.md and the code, draft App Store metadata: name (≤30 chars), subtitle (≤30), keywords (≤100, comma-separated), a description, and what to declare in the App Privacy section based on the data the app actually stores.

Golden rules of vibe coding Swift

The habits that separate an app that ships from one that falls apart

Rule	Why it matters	Say this to the agent
Small steps	Small changes are easy to review and easy to undo. Large ones fail in ways that are hard to track down.	"Only do feature 2. Don't touch other files."
Modern Swift only	Models often fall back to older APIs they've seen more often in training data.	"Use @Observable and SwiftData, not ObservableObject or Core Data."
Let it compile	An agent that builds after each change fixes its own errors instead of handing you broken code.	"Build after every change and fix all errors."
Git is your undo	Rolling back to the last commit is faster than trying to fix a bad session.	"Commit with a clear message now that this works."
Read the diff	You don't need to write the code, but you're the one shipping it.	"Explain this change like I'm reviewing a pull request."

Prompt library

Every prompt in this guide in one place. Click one to jump to it, or copy them all into a note.

Troubleshooting

The errors beginners hit most, what they usually mean, and what to tell the agent.

What you see	What it usually means	What to do
`Fatal error: ... ModelContainer`	The SwiftData container isn't set up correctly	"Check that `.modelContainer(for:)` is applied and includes all my @Model types."
`Main actor-isolated ... cannot be called from nonisolated context`	A Swift 6 concurrency rule	"Fix this concurrency error properly. Don't silence it with `@unchecked Sendable`."
"Index out of range" after deleting	The code uses positions that changed	"Explain why the index is invalid. Use item IDs instead of array positions."
"No such module"	A package or target problem	"Don't add packages. Remove the import and use built-in frameworks."
Signing errors on a real device	Team or provisioning not set	Fix it in Xcode: Signing & Capabilities › select your Team. This isn't a job for the agent.
UI doesn't update after data changes	The view isn't observing the data	"Check my view reads data from @Query or an @Observable object."
Simulator won't launch or hangs	A stuck Simulator process	Quit the Simulator, then in Xcode choose Product › Clean Build Folder (`⇧⌘K`) and run again.

If the agent is looping (same fix, different words, same error)

Stop the agent.
Run git restore . to go back to your last good commit.
Open a fresh session.
Describe the problem from scratch, including what you already tried.

Common mistakes

Most failed vibe-coded apps go wrong in one of these ways.

Asking for the whole app in one prompt. You get a lot of code that almost works and is hard to fix.
Not committing. Without a recent commit, one bad session can cost you hours of work.
Skipping the brief. Without BRIEF.md, the agent fills the gaps with its own ideas.
One endless session. Long conversations drift. Start fresh after each feature.

Paraphrasing errors. Paste the exact message and console output.
Letting it add packages or edit the .xcodeproj file without asking.
Silencing warnings. Swift 6 concurrency warnings point at real bugs.
Testing only in the Simulator. Haptics, performance and the feel of the app only show up on a real iPhone.

FAQ

Do I need to know Swift?

No. You need to describe what you want clearly and read what the agent tells you. Ask it to explain any change you don't understand, and you will pick up Swift as you go.

Do I have to pay Apple $99 a year?

Only to ship. A free Apple Account is enough to run the app in the Simulator and on your own iPhone, though apps installed that way stop working after 7 days. You need the $99/year Apple Developer Program for TestFlight and the App Store.

Can I follow this guide on Windows or Linux?

No. Xcode only runs on macOS, and you need it to build, sign and upload iOS apps. Rented cloud Macs exist, but this guide assumes a Mac in front of you.

Which AI agent should I use?

Any agent that can edit files and run commands works. If you're unsure, use Claude Code, because every prompt in this guide works with it as written. The tool chooser above compares the options.

Will Apple reject an app built with AI?

Apple reviews the app, not how the code was written. Rejections come from the usual reasons: crashes, missing privacy details, or an app too thin to be useful (guideline 4.2, Minimum Functionality). Test it properly and give it a real purpose.

Can I make an Android version too?

Not with this guide. SwiftUI only runs on Apple platforms. The same loop works for Android with Kotlin and Jetpack Compose, but the tools and prompts are different.

What does the whole thing cost?

Xcode is free. Most agents cost about $20 a month, and some have limited free tiers. Add $99 a year for the Apple Developer Program when you are ready to ship.

What kinds of apps can I build with this guide?

Any app that keeps its data on the device: lists and collections, trackers, calculators and other utilities, flashcards and reference apps, timers, and journals. Apps that need accounts, a server, payments or real-time multiplayer are possible, but they are much harder for a first project.

What to build next

Each idea adds one new Apple framework. Use the same loop and the same small steps.

📊 ChartsPlot your data over time with Swift Charts.

🔔 RemindersSchedule local notifications with UserNotifications.

🧩 Home Screen widgetShow the most useful number or item at a glance with WidgetKit.

☁️ iCloud syncSync SwiftData across devices with CloudKit.

📸 PhotosAttach images to anything with PhotosPicker.

⏱️ Live ActivitiesShow live progress or a countdown on the Lock Screen.

Resources

Official documentation worth bookmarking. Paste a link into your prompt when the agent gets an API wrong.

SwiftUI documentationViews, navigation, animation
SwiftData documentationModels, queries, saving data
Swift TestingWriting @Test cases
Swift 6 migration guideUnderstanding concurrency errors
Human Interface GuidelinesHow native iOS apps should look and behave
SF SymbolsBrowse the built-in icon library
TestFlightBeta testing before release
App Store Review GuidelinesRead before you submit
Apple Developer ProgramEnrollment and the $99/year membership
XcodeBuildMCPLet your agent build and drive the Simulator

Your progress is saved in this browser. Swift, SwiftUI and Xcode are trademarks of Apple Inc.