From 85fdc3ec99807cf1e2fe2178b056cbfa492093d3 Mon Sep 17 00:00:00 2001 From: Alex Hunt Date: Thu, 13 Aug 2026 07:13:40 -0700 Subject: [PATCH] Update agent guidance, move to AGENTS.md (#57944) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- AGENTS.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 25 +------------------------ 2 files changed, 54 insertions(+), 24 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000000..d6d28d6f501 --- /dev/null +++ b/AGENTS.md @@ -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 ` | Jest unit tests, found in `__tests__` directories | +| `yarn fantom ` | [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. diff --git a/CLAUDE.md b/CLAUDE.md index 1b7bc701d07..43c994c2d36 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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