From a0566250b210499b4c5677f5ac2eedbd71d51a1b Mon Sep 17 00:00:00 2001 From: Ricky Date: Fri, 23 Jan 2026 20:16:06 -0500 Subject: [PATCH] [repo] init claude config (#35617) ## Overview Adds a claude setup that works with the nested /compiler setup. The constraints are: - when working in the root repo, don't use the compiler configs (easy) - when working in the compiler/ don't use the parent contigs (hard) The first one is easy: there's a claude.md and .claude directory in /compiler that is only loaded when you start a session from /compuler. The second one is hard, because if you start a session from /compiler, the parent claude files and skills are loaded. I was able to deny the permissions to the parent skills in settings.json, but the descriptions are still loaded into context and I don't think that's avoidable. To keep the parent claude file out of context, I created a hook hack: I moved all the non-compiler claude file context to instructions.md and added a SessionStart hook to cat the file into context if the cwd isn't the /compiler. Works well, but won't show it as part of the `/context` slash command. ## Skills I also added a number of skills specific to the React repo: | Skill | Description | |-------|-------------| | `/extract-errors` | `yarn extract-errors` | | `/feature-flags` | how feature flags work and `@gate` | | `/fix` | linc and prettier | | `/flags` | `yarn flags` | | `/flow` | `yarn flow ` | | `/test` | `yarn test-*` | | `/verify` | `run all the lints/tests/flow to verify` | ### Example: Flow | before | after | |-----|-----| | flow-before | flow-after | ### Example: Tests | before | after | |-----|-----| | test-before | test-after | --- .claude/instructions.md | 46 +++++++++++++++ .claude/settings.json | 44 ++++++++++++++ .claude/skills/extract-errors/SKILL.md | 12 ++++ .claude/skills/feature-flags/SKILL.md | 79 ++++++++++++++++++++++++++ .claude/skills/fix/SKILL.md | 17 ++++++ .claude/skills/flags/SKILL.md | 39 +++++++++++++ .claude/skills/flow/SKILL.md | 30 ++++++++++ .claude/skills/test/SKILL.md | 46 +++++++++++++++ .claude/skills/verify/SKILL.md | 24 ++++++++ CLAUDE.md | 8 +++ compiler/.claude/settings.json | 11 +++- 11 files changed, 354 insertions(+), 2 deletions(-) create mode 100644 .claude/instructions.md create mode 100644 .claude/settings.json create mode 100644 .claude/skills/extract-errors/SKILL.md create mode 100644 .claude/skills/feature-flags/SKILL.md create mode 100644 .claude/skills/fix/SKILL.md create mode 100644 .claude/skills/flags/SKILL.md create mode 100644 .claude/skills/flow/SKILL.md create mode 100644 .claude/skills/test/SKILL.md create mode 100644 .claude/skills/verify/SKILL.md create mode 100644 CLAUDE.md diff --git a/.claude/instructions.md b/.claude/instructions.md new file mode 100644 index 0000000000..39573f6c44 --- /dev/null +++ b/.claude/instructions.md @@ -0,0 +1,46 @@ +# React + +**Scope**: All code EXCEPT `/compiler/` (compiler has its own instructions). + +## Project Structure + +| Directory | Purpose | +|-----------|---------| +| `/packages/` | Publishable packages (react, react-dom, scheduler, etc.) | +| `/scripts/` | Build, test, and development scripts | +| `/fixtures/` | Test applications for manual testing | +| `/compiler/` | React Compiler (separate sub-project) | + +## Key Packages + +| Package | Purpose | +|---------|---------| +| `react` | Core React library | +| `react-dom` | DOM renderer | +| `react-reconciler` | Core reconciliation algorithm | +| `scheduler` | Cooperative scheduling | +| `react-server-dom-*` | Server Components | +| `react-devtools-*` | Developer Tools | +| `react-refresh` | Fast Refresh runtime | + +## Requirements + +- **Node**: Must be installed. Stop and prompt user if missing. +- **Package Manager**: Use `yarn` only. + +## Verification + +**IMPORTANT**: Use `/verify` to validate all changes before committing. + +## Commands + +| Command | Purpose | +|----------|----------------------| +| `/fix` | Lint and format code | +| `/test` | Run tests | +| `/flow` | Type check with Flow | +| `/flags` | Check feature flags | + +## Building + +Builds are handled by CI. Do not run locally unless instructed. diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000000..f12f21abf4 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,44 @@ +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "type": "command", + "command": "if [[ \"$PWD\" != */compiler* ]]; then cat .claude/instructions.md 2>/dev/null || true; fi" + } + ] + } + ] + }, + "permissions": { + "allow": [ + "Skill(extract-errors)", + "Skill(feature-flags)", + "Skill(fix)", + "Skill(flags)", + "Skill(flow)", + "Skill(test)", + "Skill(verify)", + "Bash(yarn test:*)", + "Bash(yarn test-www:*)", + "Bash(yarn test-classic:*)", + "Bash(yarn test-stable:*)", + "Bash(yarn linc:*)", + "Bash(yarn lint:*)", + "Bash(yarn flow:*)", + "Bash(yarn prettier:*)", + "Bash(yarn build:*)", + "Bash(yarn extract-errors:*)", + "Bash(yarn flags:*)" + ], + "deny": [ + "Bash(yarn download-build:*)", + "Bash(yarn download-build-for-head:*)", + "Bash(npm:*)", + "Bash(pnpm:*)", + "Bash(bun:*)", + "Bash(npx:*)" + ] + } +} diff --git a/.claude/skills/extract-errors/SKILL.md b/.claude/skills/extract-errors/SKILL.md new file mode 100644 index 0000000000..08bb1830eb --- /dev/null +++ b/.claude/skills/extract-errors/SKILL.md @@ -0,0 +1,12 @@ +--- +name: extract-errors +description: Use when adding new error messages to React, or seeing "unknown error code" warnings. +--- + +# Extract Error Codes + +## Instructions + +1. Run `yarn extract-errors` +2. Report if any new errors need codes assigned +3. Check if error codes are up to date diff --git a/.claude/skills/feature-flags/SKILL.md b/.claude/skills/feature-flags/SKILL.md new file mode 100644 index 0000000000..8e3281a1af --- /dev/null +++ b/.claude/skills/feature-flags/SKILL.md @@ -0,0 +1,79 @@ +--- +name: feature-flags +description: Use when feature flag tests fail, flags need updating, understanding @gate pragmas, debugging channel-specific test failures, or adding new flags to React. +--- + +# React Feature Flags + +## Flag Files + +| File | Purpose | +|------|---------| +| `packages/shared/ReactFeatureFlags.js` | Default flags (canary), `__EXPERIMENTAL__` overrides | +| `packages/shared/forks/ReactFeatureFlags.www.js` | www channel, `__VARIANT__` overrides | +| `packages/shared/forks/ReactFeatureFlags.native-fb.js` | React Native, `__VARIANT__` overrides | +| `packages/shared/forks/ReactFeatureFlags.test-renderer.js` | Test renderer | + +## Gating Tests + +### `@gate` pragma (test-level) + +Use when the feature is completely unavailable without the flag: + +```javascript +// @gate enableViewTransition +it('supports view transitions', () => { + // This test only runs when enableViewTransition is true + // and is SKIPPED (not failed) when false +}); +``` + +### `gate()` inline (assertion-level) + +Use when the feature exists but behavior differs based on flag: + +```javascript +it('renders component', async () => { + await act(() => root.render()); + + if (gate(flags => flags.enableNewBehavior)) { + expect(container.textContent).toBe('new output'); + } else { + expect(container.textContent).toBe('legacy output'); + } +}); +``` + +## Adding a New Flag + +1. Add to `ReactFeatureFlags.js` with default value +2. Add to each fork file (`*.www.js`, `*.native-fb.js`, etc.) +3. If it should vary in www/RN, set to `__VARIANT__` in the fork file +4. Gate tests with `@gate flagName` or inline `gate()` + +## Checking Flag States + +Use `/flags` to view states across channels. See the `flags` skill for full command options. + +## `__VARIANT__` Flags (GKs) + +Flags set to `__VARIANT__` simulate gatekeepers - tested twice (true and false): + +```bash +/test www # __VARIANT__ = true +/test www variant false # __VARIANT__ = false +``` + +## Debugging Channel-Specific Failures + +1. Run `/flags --diff ` to compare values +2. Check `@gate` conditions - test may be gated to specific channels +3. Run `/test ` to isolate the failure +4. Verify flag exists in all fork files if newly added + +## Common Mistakes + +- **Forgetting both variants** - Always test `www` AND `www variant false` for `__VARIANT__` flags +- **Using @gate for behavior differences** - Use inline `gate()` if both paths should run +- **Missing fork files** - New flags must be added to ALL fork files, not just the main one +- **Wrong gate syntax** - It's `gate(flags => flags.name)`, not `gate('name')` diff --git a/.claude/skills/fix/SKILL.md b/.claude/skills/fix/SKILL.md new file mode 100644 index 0000000000..9335409af1 --- /dev/null +++ b/.claude/skills/fix/SKILL.md @@ -0,0 +1,17 @@ +--- +name: fix +description: Use when you have lint errors, formatting issues, or before committing code to ensure it passes CI. +--- + +# Fix Lint and Formatting + +## Instructions + +1. Run `yarn prettier` to fix formatting +2. Run `yarn linc` to check for remaining lint issues +3. Report any remaining manual fixes needed + +## Common Mistakes + +- **Running prettier on wrong files** - `yarn prettier` only formats changed files +- **Ignoring linc errors** - These will fail CI, fix them before committing diff --git a/.claude/skills/flags/SKILL.md b/.claude/skills/flags/SKILL.md new file mode 100644 index 0000000000..a9ddc331ea --- /dev/null +++ b/.claude/skills/flags/SKILL.md @@ -0,0 +1,39 @@ +--- +name: flags +description: Use when you need to check feature flag states, compare channels, or debug why a feature behaves differently across release channels. +--- + +# Feature Flags + +Arguments: +- $ARGUMENTS: Optional flags + +## Options + +| Option | Purpose | +|--------|---------| +| (none) | Show all flags across all channels | +| `--diff ` | Compare flags between channels | +| `--cleanup` | Show flags grouped by cleanup status | +| `--csv` | Output in CSV format | + +## Channels + +- `www`, `www-modern` - Meta internal +- `canary`, `next`, `experimental` - OSS channels +- `rn`, `rn-fb`, `rn-next` - React Native + +## Legend + +โœ… enabled, โŒ disabled, ๐Ÿงช `__VARIANT__`, ๐Ÿ“Š profiling-only + +## Instructions + +1. Run `yarn flags $ARGUMENTS` +2. Explain the output to the user +3. For --diff, highlight meaningful differences + +## Common Mistakes + +- **Forgetting `__VARIANT__` flags** - These are tested both ways in www; check both variants +- **Comparing wrong channels** - Use `--diff` to see exact differences diff --git a/.claude/skills/flow/SKILL.md b/.claude/skills/flow/SKILL.md new file mode 100644 index 0000000000..5ef34a2012 --- /dev/null +++ b/.claude/skills/flow/SKILL.md @@ -0,0 +1,30 @@ +--- +name: flow +description: Use when you need to run Flow type checking, or when seeing Flow type errors in React code. +--- + +# Flow Type Checking + +Arguments: +- $ARGUMENTS: Renderer to check (default: dom-node) + +## Renderers + +| Renderer | When to Use | +|----------|-------------| +| `dom-node` | Default, recommended for most changes | +| `dom-browser` | Browser-specific DOM code | +| `native` | React Native | +| `fabric` | React Native Fabric | + +## Instructions + +1. Run `yarn flow $ARGUMENTS` (use `dom-node` if no argument) +2. Report type errors with file locations +3. For comprehensive checking (slow), use `yarn flow-ci` + +## Common Mistakes + +- **Running without a renderer** - Always specify or use default `dom-node` +- **Ignoring suppressions** - Check if `$FlowFixMe` comments are masking real issues +- **Missing type imports** - Ensure types are imported from the correct package diff --git a/.claude/skills/test/SKILL.md b/.claude/skills/test/SKILL.md new file mode 100644 index 0000000000..e150ad7e54 --- /dev/null +++ b/.claude/skills/test/SKILL.md @@ -0,0 +1,46 @@ +--- +name: test +description: Use when you need to run tests for React core. Supports source, www, stable, and experimental channels. +--- + +Run tests for the React codebase. + +Arguments: +- $ARGUMENTS: Channel, flags, and test pattern + +Usage Examples: +- `/test ReactFiberHooks` - Run with source channel (default) +- `/test experimental ReactFiberHooks` - Run with experimental channel +- `/test www ReactFiberHooks` - Run with www-modern channel +- `/test www variant false ReactFiberHooks` - Test __VARIANT__=false +- `/test stable ReactFiberHooks` - Run with stable channel +- `/test classic ReactFiberHooks` - Run with www-classic channel +- `/test watch ReactFiberHooks` - Run in watch mode (TDD) + +Release Channels: +- `(default)` - Source/canary channel, uses ReactFeatureFlags.js defaults +- `experimental` - Source/experimental channel with __EXPERIMENTAL__ flags = true +- `www` - www-modern channel with __VARIANT__ flags = true +- `www variant false` - www channel with __VARIANT__ flags = false +- `stable` - What ships to npm +- `classic` - Legacy www-classic (rarely needed) + +Instructions: +1. Parse channel from arguments (default: source) +2. Map to yarn command: + - (default) โ†’ `yarn test --silent --no-watchman ` + - experimental โ†’ `yarn test -r=experimental --silent --no-watchman ` + - stable โ†’ `yarn test-stable --silent --no-watchman ` + - classic โ†’ `yarn test-classic --silent --no-watchman ` + - www โ†’ `yarn test-www --silent --no-watchman ` + - www variant false โ†’ `yarn test-www --variant=false --silent --no-watchman ` +3. Report test results and any failures + +Hard Rules: +1. **Use --silent to see failures** - This limits the test output to only failures. +2. **Use --no-watchman** - This is a common failure in sandboxing. + +Common Mistakes: +- **Running without a pattern** - Runs ALL tests, very slow. Always specify a pattern. +- **Forgetting both www variants** - Test `www` AND `www variant false` for `__VARIANT__` flags. +- **Test skipped unexpectedly** - Check for `@gate` pragma; see `feature-flags` skill. diff --git a/.claude/skills/verify/SKILL.md b/.claude/skills/verify/SKILL.md new file mode 100644 index 0000000000..daed015e28 --- /dev/null +++ b/.claude/skills/verify/SKILL.md @@ -0,0 +1,24 @@ +--- +name: verify +description: Use when you want to validate changes before committing, or when you need to check all React contribution requirements. +--- + +# Verification + +Run all verification steps. + +Arguments: +- $ARGUMENTS: Test pattern for the test step + +## Instructions + +Run these first in sequence: +1. Run `yarn prettier` - format code (stop if fails) +2. Run `yarn linc` - lint changed files (stop if fails) + +Then run these with subagents in parallel: +1. Use `/flow` to type check (stop if fails) +2. Use `/test` to test changes in source (stop if fails) +3. Use `/test www` to test changes in www (stop if fails) + +If all pass, show success summary. On failure, stop immediately and report the issue with suggested fixes. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..81f9b42172 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,8 @@ +# React + +React is a JavaScript library for building user interfaces. + +## Monorepo Overview + +- **React**: All files outside `/compiler/` +- **React Compiler**: `/compiler/` directory (has its own instructions) diff --git a/compiler/.claude/settings.json b/compiler/.claude/settings.json index 9b961f1c17..6f27a36ce3 100644 --- a/compiler/.claude/settings.json +++ b/compiler/.claude/settings.json @@ -5,7 +5,14 @@ "Bash(yarn snap:build)", "Bash(node scripts/enable-feature-flag.js:*)" ], - "deny": [], - "ask": [] + "deny": [ + "Skill(extract-errors)", + "Skill(feature-flags)", + "Skill(fix)", + "Skill(flags)", + "Skill(flow)", + "Skill(test)", + "Skill(verify)" + ] } }