Skip to content
Winter Sale from $619, until 31st December 2026 Book now
Agentic coding tools & comparisons iOS + Android

CLAUDE.md and AGENTS.md for Mobile Projects: A Structure You Can Copy

A memory file tells a coding agent what it cannot infer from the code: how to build and test, which conventions win, and which files affect signing, privacy or store review. For mobile repositories, keep it short, put commands first, list protected files explicitly, and maintain one shared AGENTS.md that Claude Code imports from CLAUDE.md – so every tool follows the same release rules.

8 min read

Key takeaways

  • Claude Code reads CLAUDE.md, Codex reads AGENTS.md, and most other agents have their own file – one shared source avoids drift.
  • Order matters: what the app is, commands, definition of done, conventions, platform rules, protected files, release notes.
  • Store-relevant files – entitlements, privacy manifest, manifest permissions, signing, version numbers – belong on an explicit "ask first" list.
  • Leave out secrets, style rules a formatter enforces and anything you would not want an attacker to edit.
  • Treat the file like code: review changes, test it with questions and update it after every rejection.

Which agent reads which file

Every coding agent starts a session by loading project instructions. The file names differ:

ToolInstruction fileGood to know
Claude CodeCLAUDE.md in the repository, in subfolders and in your home folderCan import other files with @path; subfolder files load when the agent works there
OpenAI CodexAGENTS.md globally in ~/.codex, at the root and in subfoldersThe file closest to the working directory takes precedence
Gemini CLIGEMINI.mdThe context file name can be configured, for example to AGENTS.md
GitHub Copilot.github/copilot-instructions.mdCheck the current docs for AGENTS.md support
CursorProject rules in .cursor/rulesRules can target file patterns

AGENTS.md is the closest thing to a common standard: an open, tool-agnostic format now stewarded by the Agentic AI Foundation under the Linux Foundation. If your team uses more than one agent, make it the source of truth.

A structure that works for app repositories

Agents read the whole file, but they weigh what comes first and what is concrete. This order has worked well for mobile repositories:

  1. About the app – two or three sentences: platforms, frameworks, where things live.
  2. Commands – build, test, lint and run, copy-paste ready.
  3. Definition of done – what must be true before the agent reports success.
  4. Conventions – only where you deviate from platform defaults.
  5. Platform rules – iOS and Android specifics.
  6. Protected files and actions – the "ask first" list.
  7. Release notes for agents – store rules that affect code.

Here is the template for a repository with a native iOS app and a native Android app:

# AGENTS.md

## About this app
Habit tracker. iOS app in ios/ (SwiftUI), Android app in android/ (Jetpack Compose).
Both use the REST API described in api/openapi.yaml. Shared business rules: docs/rules.md.

## Commands
- iOS build (in ios/):     xcodebuild -scheme Habits -destination 'platform=iOS Simulator,name=iPhone 17' build -quiet
- iOS tests (in ios/):     xcodebuild -scheme Habits -destination 'platform=iOS Simulator,name=iPhone 17' test -quiet
- Android build (android/): ./gradlew --console=plain assembleDebug
- Android tests (android/): ./gradlew --console=plain testDebugUnitTest lintDebug

## Done means
- Build and tests pass for every platform you changed. If you could not run them, say so.
- A rule from docs/rules.md behaves the same on both platforms.
- New user-facing text exists in English and German.

## Conventions (only deviations from platform defaults)
- Networking: URLSession on iOS, Ktor client on Android. No other HTTP libraries.
- Feature flags are read only through RemoteFlags.swift and RemoteFlags.kt.

## Ask before changing
- Signing: team settings, provisioning, android/keystore.properties, any certificate or keystore
- Store-relevant: Info.plist usage texts, PrivacyInfo.xcprivacy, *.entitlements,
  AndroidManifest.xml permissions, minSdk, targetSdk, bundle ID, applicationId
- Purchases: StoreKit and Play Billing code in */purchases/

## Release notes for agents
- CI sets version and build numbers. Never change them.
- Any flow that creates an account needs an in-app way to delete it.
- A new SDK means new privacy answers: list the data it collects in the PR.

Talk to an AI Code Engineer about shipping your app to the App Store and Google Play.

In a free call we look at what you built, tell you honestly what stands between it and an approved release – and whether you need us at all.

The platform rules agents do not guess

Generic agent instructions cover code style. Mobile repositories need rules that come from Apple and Google, because the agent cannot see App Store Connect or the Play Console. Pick the ones that apply to your app:

iOS block

  • Deployment target and the APIs to use in new code (for example NavigationStack and @Observable for iOS 17+).
  • A simulator name that exists on every Mac and in CI, and that uploads need Xcode 26 with the iOS 26 SDK.
  • "Every new SDK needs privacy manifest entries" – missing required-reason declarations cause ITMS-91053 warnings at upload, see our guide to ITMS-91053.
  • Third-party login implies Sign in with Apple as an option; digital goods use In-App Purchase.

Android block

  • Dependencies only through the version catalog; Compose versions from the BOM.
  • targetSdk is a policy decision: Google Play requires Android 16 (API level 36) for new apps and updates.
  • New permissions and SDKs change the Data safety form; digital goods use Google Play Billing.
  • Account deletion needs an in-app path and a web link where users can request deletion.

For framework-specific examples, see Claude Code for SwiftUI, Codex for Android and Claude Code for Expo.

One source of truth for several agents

Keep the shared rules in AGENTS.md and make CLAUDE.md a thin file that imports it and adds Claude-specific notes:

@AGENTS.md

## Claude Code only
- Use plan mode for any change that touches both ios/ and android/.
- Before finishing iOS work, ask the ios-reviewer subagent to check the diff.

The import keeps one file as the single source and leaves room for features other tools do not have. Recent Claude Code versions can also read AGENTS.md on their own when no CLAUDE.md exists – check the memory documentation for your version – but the import works either way. For Gemini CLI, set the context file name to AGENTS.md; for Cursor and Copilot, a short rules file that points to AGENTS.md avoids duplicating content.

In a repository with two apps, add nested files for the details: ios/AGENTS.md with Xcode specifics and android/AGENTS.md with Gradle specifics. The root file stays short, and each agent gets the platform detail exactly when it works in that folder.

What to leave out

  • Secrets. No API keys, passwords, keystore credentials or tokens – the file is committed, read by every tool and pasted into model context.
  • What tools already enforce. Indentation, import order and naming belong in SwiftLint, ktlint, ESLint or the formatter. Tell the agent to run them instead.
  • Copies of documentation. Link to docs/ files rather than pasting them in; the agent can open them when needed.
  • Wishes. "Write clean, maintainable code" changes nothing. "ViewModels never import UI frameworks" does.
  • Contradictions. When two rules conflict, the agent picks one at random. Read the whole file before adding to it.

A practical length test: if the file no longer fits on two screens, move platform detail into nested files and long explanations into linked docs.

Keep it alive: review, test, update after every rejection

Memory files go stale like any other code. Three habits keep them useful:

  • Review changes like code. Put the files under CODEOWNERS and review edits – including edits an agent proposes. A memory file is also an attack surface: an injected instruction there would apply to every future session. Our article on the security risks of agentic coding explains why.
  • Test it with questions. Start a fresh session and ask: "How do I run the Android tests? Which files must you not change? What do you do when you add an SDK?" Wrong answers show where the file is unclear.
  • Learn from rejections. When App Review or Google Play reject a build, add the rule that would have prevented it. Over time the file becomes your team's release memory.

Our AI Code Engineers set up memory files, permissions and review routines in hands-on Claude Code and Codex workshops, remote or on-site, in English or German.

Memory file checklist for mobile repositories

  • One shared AGENTS.md; CLAUDE.md and other tool files point to it.
  • Build, test and lint commands for every platform are copy-paste ready.
  • The definition of done says what to report when a build could not run.
  • Conventions only list deviations from platform defaults.
  • iOS and Android blocks cover the store rules that affect code.
  • Signing, privacy, permission and version files are on the ask-first list.
  • No secrets, no duplicated linter rules, no contradictions.
  • Changes go through code review, and rejections lead to new rules.

Frequently asked questions

Should CLAUDE.md and AGENTS.md be committed to git?

Yes. Shared rules only work if everyone's agent reads the same file. Personal preferences belong in your user-level file, for example ~/.claude/CLAUDE.md or ~/.codex/AGENTS.md.

How long should a memory file be?

As short as possible while still answering the questions an agent would otherwise guess. Most mobile repositories need a root file of one or two screens plus nested files for platform details.

Does a memory file affect App Store or Google Play review?

Not directly – reviewers never see it. But it prevents the code changes that cause rejections: missing permission texts, undeclared SDKs, broken account deletion, changed identifiers.

Can you write our memory files with us?

Yes. Book a free call and an AI Code Engineer looks at your repository. In a workshop we write the memory file, permissions and review routine together with your team.

Free, 15 minutes, no obligation

Get your app from agent output to approved release.

Our AI Code Engineers take apps built with Claude Code, Codex, Cursor, Lovable, Base44 and co. through signing, CI/CD, store listings and review – in your own developer accounts.

AI tools, store policies and requirements change quickly – always check the current documentation of the tools and stores you use. This article is independent advice and not affiliated with or endorsed by Apple, Google, Anthropic, OpenAI or any other company or product mentioned; all trademarks belong to their owners.

Ready to ship?

Talk to an AI Code Engineer – free, 15 minutes, in English or German.

Book a call for free

Chat and hotline are open 24/7. Answers from our senior AI Code Engineers (real humans) usually take closer to 72 hours than 1 hour.