iOS AI Instructions File: CLAUDE.md and AGENTS.md Templates

Q: Where does the Copilot instructions file go?

In .github/copilot-instructions.md in your repository. Rules that apply only to some files go under .github/instructions/, with file names ending in .instructions.md and the paths set with applyTo.

An AI instructions file stops assistants from using wrong iOS APIs or touching signing. Claude Code reads CLAUDE.md, all support AGENTS.md. 4 templates.

An AI instructions file is a file in your repository that AI coding assistants read at the start of every conversation. Write it well and the AI stops using APIs your iOS version doesn’t have, adding dependencies on its own or touching your certificates. Claude Code reads CLAUDE.md, GitHub Copilot reads .github/copilot-instructions.md, Cursor reads .mdc rules under .cursor/rules/, and all three support the shared AGENTS.md. This article gives a comparison table and a way to share one file across tools, then four templates you can copy for SwiftUI, UIKit + CocoaPods, Flutter and React Native / Expo.

For the full workflow with an AI assistant in an iOS project (describing the change, reviewing code, building, testing on a device), see AI iOS app development in VS Code with Copilot and Claude Code. This article covers only the instructions file.

Which instructions file does each AI tool read?

The table follows each tool’s official documentation as of October 2026.

Tool	Project instructions file	Path-scoped rules	Reads AGENTS.md
Claude Code	`CLAUDE.md` or `.claude/CLAUDE.md` in the root, plus a personal `CLAUDE.local.md`	`.claude/rules/*.md`, scoped with `paths`	When the repository has no CLAUDE.md. You can also import it with `@AGENTS.md` in CLAUDE.md
GitHub Copilot	`.github/copilot-instructions.md`	`.github/instructions/*.instructions.md`, scoped with `applyTo`	Yes. In VS Code it’s controlled by `chat.useAgentsMdFile`
Cursor	`.cursor/rules/*.mdc`	Same folder, scoped with `globs`	Yes, in the root and in subfolders

A few details.

Claude Code is documented in How Claude remembers your project. Run /context in a session and look under Memory files to see which files were loaded. /init generates a draft you can edit.
Copilot is documented in the GitHub docs and the VS Code docs. With chat.useClaudeMdFile turned on in VS Code, Copilot reads CLAUDE.md too.
Cursor is documented in Rules. Files in .cursor/rules need the .mdc extension and frontmatter. Plain .md files without frontmatter are ignored.

One source for all three tools

When people on your team use different tools, write the content once in AGENTS.md at the root and have the other files only reference it, so you never end up with contradicting instructions.

Copilot and Cursor read AGENTS.md directly. You don’t need another file.
Claude Code reads AGENTS.md directly when the repository has no CLAUDE.md. If you also need Claude-specific content, create a CLAUDE.md that imports it on the first line.

1@AGENTS.md
2
3(Add Claude Code-specific notes below, or leave this empty)

For Cursor only, with the rule always applied, write .cursor/rules/ios.mdc like this.

1---
2description: iOS project conventions
3alwaysApply: true
4---
5
6(Body as in the templates below)

What belongs in an AI instructions file?

Only write facts the AI can’t see. The minimum iOS version, which dependencies are allowed, which files are generated and how to check the build are hard to infer from code. Skip things the AI already does, like “write in Swift” or “use meaningful variable names”.
Keep it short. Claude Code recommends under 200 lines per file, Cursor recommends rules under 500 lines, and the VS Code docs recommend one sentence per rule. The longer the file, the more likely the AI misses a rule.
Make rules checkable. A rule that can be checked with a command or a specific name works best. “After changes, run this command and only finish when there are no errors” is far more useful than “keep code quality high”.
Give the reason. “New fields must be optional, because existing data is already stored on users’ phones” helps the AI get similar cases right better than just “use optionals”.
Update it with the project. When you raise the minimum iOS version or change dependencies, update the instructions file in the same commit. Outdated rules are worse than none.

An instructions file is only guidance, and the AI won’t always follow it. For things that must stay off limits, such as certificates, also exclude them with each tool’s own ignore or permission settings.

Template 1: what does a SwiftUI app’s instructions file look like?

For new Xcode projects that manage dependencies with Swift packages. Replace the project name, versions and folders with your own. To find the minimum iOS version, right-click the target in the KXBuild view, choose KXBuild: Edit Target Settings, and read iOS Deployment Target on the General page.

 1# MyApp
 2
 3## Project
 4- iOS app, SwiftUI, Swift 5, minimum iOS 16.0. Wrap APIs that need iOS 17 or later (@Observable, SwiftData and so on) in if #available, or use the iOS 16 equivalent.
 5- One app target, MyApp, in MyApp.xcodeproj.
 6
 7## Dependencies
 8- Swift packages only. Current packages are Alamofire and Kingfisher. Don't add CocoaPods.
 9- Ask me before adding any new dependency. Don't add one yourself.
10
11## Layout
12- MyApp/Views: UI. MyApp/Models: data types. MyApp/Services: networking and storage.
13- Data models are already stored on users' phones. New fields must be optional or have a default value, or decoding old data fails.
14
15## Checks
16- After changing code, run kxbuild build .\MyApp.xcodeproj -D CODE_SIGNING_ALLOWED=NO from the repository root. If there are errors, keep fixing until it passes.
17- A passing build doesn't mean the feature works. Tell me which interactions to verify on the phone.
18
19## Off limits
20- Don't read or modify the keychain/ folder or any .p12, .mobileprovision or password.properties file.
21- When you use the camera, photo library, location, microphone or other protected resources, remind me to add the Info.plist usage description (such as INFOPLIST_KEY_NSCameraUsageDescription) and suggest a one-sentence description for users.

Template 2: legacy UIKit + CocoaPods project

For older projects with mixed Objective-C and Swift that manage dependencies with a Podfile. The most common mistakes in these projects are the build target and the bridging header, so spell them out.

 1# LegacyApp
 2
 3## Project
 4- iOS app, UIKit, mixed Objective-C and Swift, minimum iOS 13.0.
 5- Dependencies use CocoaPods. Build LegacyApp.xcworkspace, not the .xcodeproj.
 6- Add Objective-C headers that Swift needs to LegacyApp/LegacyApp-Bridging-Header.h.
 7- UI uses storyboards and xibs. Don't convert them to SwiftUI. Write new screens in UIKit code.
 8
 9## Dependencies
10- Podfile libraries are pinned in Podfile.lock. Don't run pod update.
11- Don't add libraries to the Podfile. If one is really needed, ask me first and prefer a Swift package.
12- The Pods/ folder is generated. Don't modify files in it.
13
14## Layout
15- LegacyApp/Classes/Modules: screens grouped by feature, one folder per module.
16- LegacyApp/Classes/Common: shared utilities. Search for usages before changing anything here.
17
18## Checks
19- After changing the Podfile, run pod install in the folder that contains it.
20- After changing code, run kxbuild build .\LegacyApp.xcworkspace -D CODE_SIGNING_ALLOWED=NO. If there are errors, keep fixing until it passes.
21
22## Off limits
23- Don't read or modify the keychain/ folder or any .p12, .mobileprovision or password.properties file.
24- Don't change signing settings in project.pbxproj (CODE_SIGN_*, PROVISIONING_PROFILE_*, DEVELOPMENT_TEAM).
25- When you use a new privacy-protected resource, remind me to add the matching UsageDescription key and user-facing text to LegacyApp/Info.plist.

If you plan to move the project from CocoaPods to Swift packages, keep the Dependencies section in sync with the current state during the migration. See migrate CocoaPods to SPM.

Template 3: Flutter

Most of a Flutter project is Dart, so checks use Flutter’s own commands. When native code under the ios folder changes, also build the iOS side with KXBuild. Before the first build on a computer, run kxbuild doctor . once in the project root.

 1# my_flutter_app
 2
 3## Project
 4- Flutter app. Dart code is in lib/, iOS native code is in ios/Runner/ (Swift).
 5- Minimum iOS 13.0. Don't use plugins or APIs on the Dart side that only work on Android.
 6
 7## Dependencies
 8- Add dependencies with flutter pub add. Don't edit pubspec.lock by hand. Ask me before adding a plugin and confirm it supports iOS.
 9- Don't modify generated files under ios/Flutter/ or GeneratedPluginRegistrant.
10
11## Layout
12- lib/screens: screens. lib/widgets: reusable widgets. lib/services: networking and storage.
13- State management uses provider. Don't add other state management libraries.
14
15## Checks
16- After changing Dart code, run flutter analyze and flutter test. Only finish when there are no errors.
17- When you change native code under ios/, also run kxbuild build .\ios\Runner.xcworkspace -D CODE_SIGNING_ALLOWED=NO.
18
19## Off limits
20- Don't read or modify the keychain/ folder or any .p12, .mobileprovision or password.properties file.
21- When you add a plugin that uses the camera, photo library, location or microphone, remind me to add the UsageDescription keys its docs require, with user-facing text, to ios/Runner/Info.plist.

Template 4: React Native / Expo

React Native and Expo share one template. Delete the lines that don’t apply to your project. If your Expo project’s ios folder is generated, tell the AI clearly not to edit it.

 1# rnhello
 2
 3## Project
 4- React Native app, TypeScript. Code is in src/, the iOS native project is in ios/.
 5- Minimum iOS 15.1, as set by platform in ios/Podfile.
 6- (Expo) The ios/ folder is generated by prebuild. Don't edit it directly. Change native configuration in app.json and put usage descriptions in expo.ios.infoPlist.
 7
 8## Dependencies
 9- Use npm as the package manager, not yarn or pnpm. Don't delete package-lock.json.
10- (Expo) Add dependencies with npx expo install so versions match the current SDK.
11- Ask me before adding a library with native code. After adding one, run pod install in ios/.
12
13## Layout
14- src/screens: screens. src/components: components. src/api: API requests.
15- Navigation uses React Navigation. Don't add other navigation libraries.
16
17## Checks
18- After changing code, run npx tsc --noEmit and npm test. Only finish when there are no errors.
19- When you change native code under ios/, also run kxbuild build .\ios\rnhello.xcworkspace -D CODE_SIGNING_ALLOWED=NO.
20
21## Off limits
22- Don't read or modify the keychain/ folder or any .p12, .mobileprovision or password.properties file.
23- Don't put API keys in code. Read them from .env, and don't commit .env.
24- When you use the camera, photo library, location or microphone, remind me to add the Info.plist UsageDescription keys (in app.json for Expo) with user-facing text.

For the key names and how to word the usage descriptions mentioned in all four templates, see Info.plist usage descriptions for every permission.

How do you check that the AI reads it?

Put the file where the table above says, and commit it with the code so teammates get it when they pull.
Start a new conversation and ask the AI “What’s the minimum iOS version for this project, and how should you check your changes?” A correct answer means it read the file. In Claude Code you can also confirm with /context.
When the AI keeps making the same mistake, add a checkable rule to the instructions file instead of repeating the reminder in every conversation.

For other kxbuild build options, such as choosing a scheme or target, see the kxbuild command reference, and add them to the build check in your AI instructions file when needed.

FAQ

Do I need both CLAUDE.md and AGENTS.md?

No. Write the content in AGENTS.md, which Copilot and Cursor both read. Claude Code reads AGENTS.md directly when there’s no CLAUDE.md, and if you need a CLAUDE.md, a single @AGENTS.md line in it imports the content.

Where does the Copilot instructions file go?

In .github/copilot-instructions.md in your repository. Rules that apply only to some files go under .github/instructions/, with file names ending in .instructions.md and the paths set with applyTo.

Why aren’t my Cursor rules applied?

Check the extension and the top of the file first. Rules in .cursor/rules/ must be .mdc files with frontmatter, and alwaysApply: true makes them apply every time. Plain .md files without frontmatter are ignored. If you’d rather not maintain .mdc files, put the content in AGENTS.md at the root.

How long should an instructions file be?

As short as possible. A few dozen lines is usually enough. Claude Code recommends under 200 lines and Cursor under 500. Split anything longer into separate path-scoped rule files.

The AI still used a newer API despite the instructions file. What now?

Make the rule specific. List the APIs it must not use and the minimum version, and require it to run the build check after every change. When the build reports is only available in iOS xx or newer, the AI can fix the code from the error.