What a CLAUDE.md File Actually Does
A CLAUDE.md file is a plain markdown file at the root of your project that Claude Code reads automatically at the start of every session in that folder. It is not a prompt you paste in, it is standing project memory. For an Expo app, that means your stack, your navigation pattern, your file structure, and any app-specific gotchas load into context before you type a single instruction, so you stop re-explaining the same conventions every time you open a new session.
This works the same whether you are typing in a terminal or using the Claude Code desktop app. You do not need to know any CLI flags to benefit from it. Open your Expo project's folder in Claude Code and the file gets read the same way either way. If the project has no CLAUDE.md yet, running the /init command inside it will scan your existing code and draft a starting one for you to edit, which is faster than writing it from a blank page.
Why an Expo App Drifts Without One
Without a CLAUDE.md, Claude Code treats every fresh session like a brand-new project and falls back on generic React defaults that do not match how an Expo app actually works. That shows up as web-style routing suggestions instead of your Expo Router file-based routes, a navigation pattern that ignores the library you already installed, or a screen rebuilt in a different style than the one sitting three files away.
I have watched Claude Code rebuild a screen I already had, in a completely different pattern, because a new session had no memory of the first one. That is not a Claude Code failure, it is a missing-context problem, and a CLAUDE.md file is the fix. It costs you five minutes once and saves you from correcting the same drift for the rest of the build.
The Sections I Put in Every Expo CLAUDE.md
Every Expo project I start gets the same handful of sections in its CLAUDE.md, filled in with that project's real specifics. This is the version that actually earns its keep, not a generic checklist copied between apps.
- Stack: Expo SDK version, Expo Router, TypeScript or JavaScript, package manager. Claude Code should never have to guess which router or language you are on.
- Commands: the exact commands you run, such as npx expo start, eas build --platform ios --profile development, and eas submit --platform ios. Paste the real ones from your project, not placeholders.
- Navigation: where screens live in the file-based route tree and any nested layouts, so a new screen goes in the right folder the first time.
- Styling: the approach you actually use, whether that is StyleSheet, a utility library, or a design system, so suggestions match the rest of the app instead of introducing a second styling pattern.
- State and data: what you use for state and how the app talks to your API, so Claude Code reuses your existing data layer instead of writing a parallel one.
- Platform gotchas already fixed: iOS versus Android differences you have already solved, like safe area handling or a permission prompt sequence, so they do not get reintroduced.
- Do-not-touch list: files where a wrong edit is expensive to unwind, such as your EAS build profiles in eas.json or plugin config in app.json.
Where It Goes and How Claude Code Finds It
CLAUDE.md lives at the root of your Expo project, in the same folder as your package.json and app.json. Claude Code loads it automatically when you open that folder, no flag or setting required. If you are starting fresh, write it before your first real build session. If you are already mid-project, run /init and Claude Code will read your existing code and draft a first pass for you to correct rather than trust blindly.
Keep It Updated as the App Grows
A CLAUDE.md file is not a one-time setup task, it is a working document. The moment I have to correct the same wrong assumption more than once in a session, that correction goes straight into the file so I never have to type it again. An Expo app that started as three screens and grew into thirty needs a CLAUDE.md that grew with it, not the three-screen version from week one.
This is the same discipline behind the 90-day build-and-ship path I teach in App Store Launch Club: the systems you set up early, whether that is a CLAUDE.md file or your [EAS build profiles](/blog/eas-build-guide-for-expo-apps), are what keep the app coherent as it grows instead of turning into a pile of one-off fixes.
What to Leave Out
Keep API keys, tokens, and any real secrets out of CLAUDE.md. It is a plain text file that commonly gets committed to git alongside the rest of your project, so anything sensitive belongs in your environment variables, not in project memory that could end up in your repository's history.
Also resist pasting in large chunks of code or trying to document every file in the app. The useful version is a working set of decisions and conventions, short enough that you would actually reread it, not a second copy of your codebase in prose form.
If you are still setting up the build machine itself, start with [how to ship your first app in 7 days with Claude Code](/blog/ship-your-first-app-in-7-days-with-claude-code) and add the CLAUDE.md file as part of day one, not as an afterthought once the drift has already started. App Store Launch Club members get the exact CLAUDE.md template I start every Expo build from, alongside the 69 copy-paste build prompts. Join at applaunchclub.co for $9 a month.
Short, practical drops on app ideas, validating fast, store listings, and passing app review. No spam, unsubscribe anytime.
Frequently asked questions
What is a CLAUDE.md file?
CLAUDE.md is a plain markdown file at the root of a project that Claude Code reads automatically at the start of every session in that folder. It holds standing project memory, such as your stack, conventions, and build commands, so you do not have to re-explain them every time you start a new session.
Does Claude Code read CLAUDE.md automatically, or do I have to load it myself?
Automatically. As long as the file sits at the root of the project folder you have open, Claude Code reads it at the start of the session with no flag, setting, or extra step needed.
Do I need the terminal to use CLAUDE.md, or does the Claude Code desktop app read it too?
The desktop app reads it the same way the terminal does. CLAUDE.md is a project-level file, not a terminal-specific feature, so opening the project folder in either version of Claude Code gets you the same automatic project memory.
Should I commit CLAUDE.md to git for my Expo app?
Yes, for the parts that describe your stack, commands, and conventions. Just keep secrets and API keys out of it entirely, since it is a plain text file that typically lives in your repository alongside the rest of the project.
Can Claude Code generate a CLAUDE.md automatically for an existing Expo project?
Yes. Running the /init command inside an existing project has Claude Code scan your real code and draft a starting CLAUDE.md from it. Treat that draft as a first pass to edit, since it can describe what your code does today but cannot know your actual build commands or the mistakes you have already fixed.
Where can I get a real CLAUDE.md example built for an Expo app and Claude Code build pipeline?
App Store Launch Club shares the exact CLAUDE.md template used to start every Expo build in the course, alongside the 69 copy-paste build prompts and the full 90-day path from first build to a live App Store and Google Play listing. Join at applaunchclub.co for $9 a month.
Last reviewed by David on August 25, 2026
