Vedran BurojevicCaffeinated Code
Back to Blog
iOS Swift Xcode AI Automation Engineering Management

AGENTS.md for iOS: guardrails that stop AI from breaking your app

Treat AI as a powerful, unreliable teammate. An AGENTS.md file gives it constraints, workflows, and verification steps that keep your iOS codebase stable and your PRs reviewable.

• 5 min read •

AI can move fast, but it does not carry context the way a senior engineer does. It will happily:

  • edit files outside the feature you asked for
  • refactor a working subsystem because it looked “cleaner”
  • change build settings and break CI
  • ship risky changes without tests

If you want AI in your iOS workflow, you need guardrails.

An AGENTS.md file is a simple, versioned contract that tells any agent (human or AI) how to work in your repo. The goal is not to restrict productivity. The goal is to make the output predictable, reviewable, and safe.

What AGENTS.md should do

A good AGENTS.md does three things:

  1. Defines scope: where the agent is allowed to touch code.
  2. Defines process: how changes should be made and verified.
  3. Defines quality bars: what must be true before a PR is acceptable.

This works best when it is concrete and testable.

Start with the non negotiables

Most teams already have rules. They are just spread across tribal knowledge and Slack messages. Pull them into one place.

Examples that matter for iOS:

  • Do not change deployment targets without explicit approval.
  • Do not update third party dependencies unless requested.
  • Do not modify entitlements, capabilities, or Info.plist keys unless required for the task.
  • Never disable warnings or lints to make the build pass.

If your agent is allowed to do these things, it will. Make “no” the default.

Define the workflow: plan, change, verify

Agents do best with a tight loop.

A practical template:

  • Plan: 1 to 3 bullets, including files likely to change.
  • Execute: make minimal changes that satisfy the request.
  • Verify: run the exact checks you care about.

For iOS, verification needs to be explicit. “The app builds” is not a check, it is a wish.

Write down the commands the agent must run, for example:

  • xcodebuild for your canonical scheme and simulator
  • unit tests for a targeted set of modules
  • snapshot tests if relevant
  • SwiftFormat or SwiftLint if you use them

If the agent cannot run them (missing credentials, Apple account, and so on), require a clear statement of what was not verified.

Be explicit about Xcode projects and generated files

iOS repos often contain files that should not be edited directly.

Spell it out:

  • If you use XcodeGen or Tuist, do not edit the .xcodeproj.
  • If you generate API clients, do not edit generated sources.
  • If you rely on SwiftGen, do not manually change generated asset accessors.

If you do want agents to touch these, require them to change the source of truth and regenerate.

Constrain the blast radius

Most AI mistakes are not “wrong code”. They are “too much code”.

Put boundaries in writing:

  • Prefer small diffs.
  • Avoid repo wide refactors.
  • Do not reformat unrelated files.
  • Do not rename public APIs without a migration plan.

Also define where work should happen:

  • feature code: Sources/ or App/
  • tests: Tests/ and snapshots
  • scripts: scripts/

When the agent knows the layout and the rules, it stops guessing.

Define patterns to follow

Agents copy patterns. If you want consistent output, tell it what “good” looks like.

Examples:

  • Architecture: MVVM, TCA, or your internal pattern.
  • Dependency injection: how services are passed, where singletons are forbidden.
  • State management: where @MainActor is required, how background work is done.
  • Error handling: how errors are surfaced, logged, and tested.

If you have existing “golden” files, list them as references.

Require safety checks for risky areas

Some iOS changes are high leverage and high risk:

  • keychain and auth flows
  • StoreKit purchases and receipt handling
  • push notifications and APNs environment switches
  • background modes and task scheduling
  • privacy prompts and tracking

Your AGENTS.md should call these out and require extra verification. For example:

  • add or update tests
  • include a manual QA checklist
  • include screenshots or screen recordings for UI flows

Make the agent do the boring safety work.

A minimal AGENTS.md you can copy

Keep the file short. It should be easy to read and hard to misinterpret.

Here is a compact starting point:

  • Scope: change only files related to the request. No drive by refactors.
  • Project: do not edit .xcodeproj (generated). Use XcodeGen and regenerate.
  • Dependencies: do not update SPM or CocoaPods unless asked.
  • Verification: run xcodebuild for scheme App on a specific simulator and run unit tests for AppTests.
  • Output: explain what changed, why, and how it was verified.

Then iterate based on the mistakes you see.

The real payoff: stable collaboration

AGENTS.md is not an “AI file”. It is a collaboration file.

It makes onboarding faster, reviews cleaner, and CI failures rarer. AI just makes the need obvious because it will exploit every ambiguity.

Write the rules once. Save hours every week.