Update agent guidance, move to AGENTS.md (#57944)

Summary:
Pull Request resolved: https://github.com/react/react-native/pull/57944

The V1 of our `CLAUDE.md` was mostly contributor boilerplate. Revise this towards a plan overview of the repo — giving the agent immediate context on working in the codebase (and reducing exploratory file reads).

Also moves `CLAUDE.md` to `AGENTS.md`, for interop with non-Claude harnesses — `CLAUDE.md` is now a pointer to this source.

New contents:

- Repo structure
- Common commands
- Gotchas
- Contributing guidelines

This remains intentionally high level rather than exhaustive, to keep the context window lean. We can move towards nested `AGENTS.md` files over time.

**Notes**

- `CONTRIBUTING.md` is unchanged — already a short pointer to reactnative.dev. (Possible candidate for later deletion.)

Changelog: [Internal]

Reviewed By: Abbondanzo

Differential Revision: D115564651

fbshipit-source-id: 8e237cd1ab6189632bf59b2bd865c5f06fef8bcc
This commit is contained in:
Alex Hunt authored and meta-codesync[bot] committed 2026-08-13 07:20:06 -07:00
1 parent 9c770f5718
commit 2e4e8303ea
2 files changed
+54 -24

No files matched your search

+53
View File
@@ -0,0 +1,53 @@
# React Native
A framework for building native applications using React.
This file provides guidance for coding agents working in this repository.
## Repo structure
React Native is a monorepo: the `react-native` package, the packages published alongside it, and the apps and tooling used to develop them.
| Path | Contents |
| --- | --- |
| `packages/react-native/Libraries` | JavaScript source (Flow) — the legacy location, with code gradually moving to `src/private` |
| `packages/react-native/src/private` | JavaScript source (Flow) |
| `packages/react-native/ReactCommon` | Shared C++ — Fabric renderer, TurboModules, JSI, Yoga, `jsinspector-modern` |
| `packages/react-native/ReactAndroid` | Android runtime (Kotlin, Java, JNI) |
| `packages/react-native/{React,ReactApple}` | Apple runtime (Objective-C++, Swift) |
| `packages/rn-tester` | RNTester — test app showcasing each core component and API, plus a `Playground` scratch surface |
| `packages/*` | Other published packages — Metro config, Codegen, ESLint config, dev-middleware, React Native DevTools frontend |
| `private/*` | Unpublished — the `helloworld` sample app, the `react-native-fantom` test runner |
| `scripts/*` | Repository tooling — build, test, release, and CI scripts |
Architecture notes live in `__docs__` directories beside the code they describe, indexed by [`__docs__/README.md`](__docs__/README.md). Treat them as reference for the subsystem you are working in, not as required reading.
## Common commands
Run these from the repository root:
| Command | Purpose |
| --- | --- |
| `yarn test <path>` | Jest unit tests, found in `__tests__` directories |
| `yarn fantom <path>` | [Fantom](private/react-native-fantom/__docs__/README.md) integration tests, named `*-itest.js` |
| `yarn lint` | ESLint |
| `yarn format` | Prettier and clang-format |
| `yarn flow-check` | Flow |
| `yarn start`, `yarn android` | Metro, and RNTester on Android. See [RNTester](packages/rn-tester/README.md) for iOS |
Native builds use Gradle on Android, and CocoaPods or Swift Package Manager on iOS. See [Building from source](https://reactnative.dev/contributing/how-to-build-from-source).
## Gotchas
- JavaScript sources are typed with Flow, and the public API is exported from `packages/react-native/index.js`. TypeScript types are generated from those sources, and `packages/react-native/ReactNativeApi.d.ts` is a committed snapshot of that API — run `yarn build-types` to regenerate both whenever the public API changes.
- The public native API is snapshotted as well: C++ under `scripts/cxx-api` (`yarn cxx-api-build`), and Android in `packages/react-native/ReactAndroid/api/ReactAndroid.api`. CI validates both.
- Native modules and components are declared by JavaScript specs (`Native*.js`, `*NativeComponent.js`), from which their native counterparts are generated. Do not hand-edit generated code.
- `CHANGELOG.md` is compiled at release time. Changelog entries belong in the pull request description.
## Contributing guidelines
- Keep each change focused — no unrelated refactors, formatting, or dependency updates.
- Complete the pull request template — the motivation and the user-visible effect, and a [changelog entry](https://reactnative.dev/contributing/changelogs-in-pull-requests) with its category and type tags.
- In the test plan, give the exact commands you ran and their results, plus screenshots or a video for user-interface changes.
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full process, including how to report bugs.
+1 -24
View File
@@ -1,24 +1 @@
# Contributing to React Native
This file provides guidance for coding agents contributing to React Native.
These requirements apply to every contribution, regardless of how it was
created.
## Contributor guidelines
- Read [Contributing to React Native](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md) before making changes.
- Keep changes focused on the requested issue. Do not include unrelated refactors, formatting changes, or dependency updates.
- Explain the motivation and user-visible effect of the change in the pull request summary.
- Add or update tests for every behavior change. For user-facing changes, update an existing RNTester example or add a focused example when applicable.
- Run the most relevant tests and linters. In the test plan, include the exact commands and results, plus screenshots or videos for user-interface changes.
- Add a changelog entry using the format documented in [Changelogs in Pull Requests](https://reactnative.dev/contributing/changelogs-in-pull-requests). Use the pull request template's category and type tags.
- Do not open a pull request or issue on someone's behalf unless they have explicitly asked you to do so.
## Issue guidelines
- Use the [issue chooser](https://github.com/react/react-native/issues/new/choose) and select the template that matches the problem. Blank issues are not accepted.
- Search the [existing issues](https://github.com/react/react-native/issues) before filing a new one.
- Verify bugs against a currently supported React Native release and provide the React Native version, affected platforms, clear reproduction steps, environment information, and relevant logs.
- Every bug report must include a public reproducer. Prefer an `RNTesterPlayground.js` change, an [Expo Snack](https://snack.expo.dev/) for a focused UI problem, or a project created from the [React Native reproducer template](https://github.com/react-native-community/reproducer-react-native). See [How to Report a Bug](https://reactnative.dev/contributing/how-to-report-a-bug) for details.
- Report Expo, Metro, documentation, and third-party library problems to their respective repositories. Use the support resources linked by the issue chooser for questions and help.
- Discuss feature requests and API proposals in [Discussions and Proposals](https://github.com/react-native-community/discussions-and-proposals) instead of filing a bug report.
@AGENTS.md