[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 <variant>` | | `/test` | `yarn test-*` | | `/verify` | `run all the lints/tests/flow to verify` | ### Example: Flow | before | after | |-----|-----| | <img width="1076" height="442" alt="flow-before" src="https://github.com/user-attachments/assets/73eec143-d0af-4771-b501-c9dc29cc09ac" /> | <img width="1076" height="273" alt="flow-after" src="https://github.com/user-attachments/assets/292d33af-1d98-4252-9c08-744b33e88b86" /> | ### Example: Tests | before | after | |-----|-----| | <img width="1048" height="607" alt="test-before" src="https://github.com/user-attachments/assets/aa558ccf-2cee-4d22-b1f1-e4221c5a59dd" /> | <img width="1075" height="359" alt="test-after" src="https://github.com/user-attachments/assets/eb795392-6f46-403f-b9bb-8851ed790165" /> |
Ricky committed
Jan 23, 2026 at 20:16 UTC
a0566250b210499b4c5677f5ac2eedbd71d51a1b
11 files changed
+354
-2
.claude/instructions.md
new
+46
@@ -0,0 +1,46 @@
1
+# React
2
+
3
+**Scope**: All code EXCEPT `/compiler/` (compiler has its own instructions).
4
+
5
+## Project Structure
6
+
7
+| Directory | Purpose |
8
+|-----------|---------|
9
+| `/packages/` | Publishable packages (react, react-dom, scheduler, etc.) |
10
+| `/scripts/` | Build, test, and development scripts |
11
+| `/fixtures/` | Test applications for manual testing |
12
+| `/compiler/` | React Compiler (separate sub-project) |
13
+
14
+## Key Packages
15
+
16
+| Package | Purpose |
17
+|---------|---------|
18
+| `react` | Core React library |
19
+| `react-dom` | DOM renderer |
20
+| `react-reconciler` | Core reconciliation algorithm |
21
+| `scheduler` | Cooperative scheduling |
22
+| `react-server-dom-*` | Server Components |
23
+| `react-devtools-*` | Developer Tools |
24
+| `react-refresh` | Fast Refresh runtime |
25
+
26
+## Requirements
27
+
28
+- **Node**: Must be installed. Stop and prompt user if missing.
29
+- **Package Manager**: Use `yarn` only.
30
+
31
+## Verification
32
+
33
+**IMPORTANT**: Use `/verify` to validate all changes before committing.
34
+
35
+## Commands
36
+
37
+| Command | Purpose |
38
+|----------|----------------------|
39
+| `/fix` | Lint and format code |
40
+| `/test` | Run tests |
41
+| `/flow` | Type check with Flow |
42
+| `/flags` | Check feature flags |
43
+
44
+## Building
45
+
46
+Builds are handled by CI. Do not run locally unless instructed.
.claude/settings.json
new
+44
@@ -0,0 +1,44 @@
1
+{
2
+ "hooks": {
3
+ "SessionStart": [
4
+ {
5
+ "hooks": [
6
+ {
7
+ "type": "command",
8
+ "command": "if [[ \"$PWD\" != */compiler* ]]; then cat .claude/instructions.md 2>/dev/null || true; fi"
9
+ }
10
+ ]
11
+ }
12
+ ]
13
+ },
14
+ "permissions": {
15
+ "allow": [
16
+ "Skill(extract-errors)",
17
+ "Skill(feature-flags)",
18
+ "Skill(fix)",
19
+ "Skill(flags)",
20
+ "Skill(flow)",
21
+ "Skill(test)",
22
+ "Skill(verify)",
23
+ "Bash(yarn test:*)",
24
+ "Bash(yarn test-www:*)",
25
+ "Bash(yarn test-classic:*)",
26
+ "Bash(yarn test-stable:*)",
27
+ "Bash(yarn linc:*)",
28
+ "Bash(yarn lint:*)",
29
+ "Bash(yarn flow:*)",
30
+ "Bash(yarn prettier:*)",
31
+ "Bash(yarn build:*)",
32
+ "Bash(yarn extract-errors:*)",
33
+ "Bash(yarn flags:*)"
34
+ ],
35
+ "deny": [
36
+ "Bash(yarn download-build:*)",
37
+ "Bash(yarn download-build-for-head:*)",
38
+ "Bash(npm:*)",
39
+ "Bash(pnpm:*)",
40
+ "Bash(bun:*)",
41
+ "Bash(npx:*)"
42
+ ]
43
+ }
44
+}
.claude/skills/extract-errors/SKILL.md
new
+12
@@ -0,0 +1,12 @@
1
+---
2
+name: extract-errors
3
+description: Use when adding new error messages to React, or seeing "unknown error code" warnings.
4
+---
5
+
6
+# Extract Error Codes
7
+
8
+## Instructions
9
+
10
+1. Run `yarn extract-errors`
11
+2. Report if any new errors need codes assigned
12
+3. Check if error codes are up to date
.claude/skills/feature-flags/SKILL.md
new
+79
@@ -0,0 +1,79 @@
1
+---
2
+name: feature-flags
3
+description: Use when feature flag tests fail, flags need updating, understanding @gate pragmas, debugging channel-specific test failures, or adding new flags to React.
4
+---
5
+
6
+# React Feature Flags
7
+
8
+## Flag Files
9
+
10
+| File | Purpose |
11
+|------|---------|
12
+| `packages/shared/ReactFeatureFlags.js` | Default flags (canary), `__EXPERIMENTAL__` overrides |
13
+| `packages/shared/forks/ReactFeatureFlags.www.js` | www channel, `__VARIANT__` overrides |
14
+| `packages/shared/forks/ReactFeatureFlags.native-fb.js` | React Native, `__VARIANT__` overrides |
15
+| `packages/shared/forks/ReactFeatureFlags.test-renderer.js` | Test renderer |
16
+
17
+## Gating Tests
18
+
19
+### `@gate` pragma (test-level)
20
+
21
+Use when the feature is completely unavailable without the flag:
22
+
23
+```javascript
24
+// @gate enableViewTransition
25
+it('supports view transitions', () => {
26
+ // This test only runs when enableViewTransition is true
27
+ // and is SKIPPED (not failed) when false
28
+});
29
+```
30
+
31
+### `gate()` inline (assertion-level)
32
+
33
+Use when the feature exists but behavior differs based on flag:
34
+
35
+```javascript
36
+it('renders component', async () => {
37
+ await act(() => root.render(<App />));
38
+
39
+ if (gate(flags => flags.enableNewBehavior)) {
40
+ expect(container.textContent).toBe('new output');
41
+ } else {
42
+ expect(container.textContent).toBe('legacy output');
43
+ }
44
+});
45
+```
46
+
47
+## Adding a New Flag
48
+
49
+1. Add to `ReactFeatureFlags.js` with default value
50
+2. Add to each fork file (`*.www.js`, `*.native-fb.js`, etc.)
51
+3. If it should vary in www/RN, set to `__VARIANT__` in the fork file
52
+4. Gate tests with `@gate flagName` or inline `gate()`
53
+
54
+## Checking Flag States
55
+
56
+Use `/flags` to view states across channels. See the `flags` skill for full command options.
57
+
58
+## `__VARIANT__` Flags (GKs)
59
+
60
+Flags set to `__VARIANT__` simulate gatekeepers - tested twice (true and false):
61
+
62
+```bash
63
+/test www <pattern> # __VARIANT__ = true
64
+/test www variant false <pattern> # __VARIANT__ = false
65
+```
66
+
67
+## Debugging Channel-Specific Failures
68
+
69
+1. Run `/flags --diff <channel1> <channel2>` to compare values
70
+2. Check `@gate` conditions - test may be gated to specific channels
71
+3. Run `/test <channel> <pattern>` to isolate the failure
72
+4. Verify flag exists in all fork files if newly added
73
+
74
+## Common Mistakes
75
+
76
+- **Forgetting both variants** - Always test `www` AND `www variant false` for `__VARIANT__` flags
77
+- **Using @gate for behavior differences** - Use inline `gate()` if both paths should run
78
+- **Missing fork files** - New flags must be added to ALL fork files, not just the main one
79
+- **Wrong gate syntax** - It's `gate(flags => flags.name)`, not `gate('name')`
.claude/skills/fix/SKILL.md
new
+17
@@ -0,0 +1,17 @@
1
+---
2
+name: fix
3
+description: Use when you have lint errors, formatting issues, or before committing code to ensure it passes CI.
4
+---
5
+
6
+# Fix Lint and Formatting
7
+
8
+## Instructions
9
+
10
+1. Run `yarn prettier` to fix formatting
11
+2. Run `yarn linc` to check for remaining lint issues
12
+3. Report any remaining manual fixes needed
13
+
14
+## Common Mistakes
15
+
16
+- **Running prettier on wrong files** - `yarn prettier` only formats changed files
17
+- **Ignoring linc errors** - These will fail CI, fix them before committing
.claude/skills/flags/SKILL.md
new
+39
@@ -0,0 +1,39 @@
1
+---
2
+name: flags
3
+description: Use when you need to check feature flag states, compare channels, or debug why a feature behaves differently across release channels.
4
+---
5
+
6
+# Feature Flags
7
+
8
+Arguments:
9
+- $ARGUMENTS: Optional flags
10
+
11
+## Options
12
+
13
+| Option | Purpose |
14
+|--------|---------|
15
+| (none) | Show all flags across all channels |
16
+| `--diff <ch1> <ch2>` | Compare flags between channels |
17
+| `--cleanup` | Show flags grouped by cleanup status |
18
+| `--csv` | Output in CSV format |
19
+
20
+## Channels
21
+
22
+- `www`, `www-modern` - Meta internal
23
+- `canary`, `next`, `experimental` - OSS channels
24
+- `rn`, `rn-fb`, `rn-next` - React Native
25
+
26
+## Legend
27
+
28
+✅ enabled, ❌ disabled, 🧪 `__VARIANT__`, 📊 profiling-only
29
+
30
+## Instructions
31
+
32
+1. Run `yarn flags $ARGUMENTS`
33
+2. Explain the output to the user
34
+3. For --diff, highlight meaningful differences
35
+
36
+## Common Mistakes
37
+
38
+- **Forgetting `__VARIANT__` flags** - These are tested both ways in www; check both variants
39
+- **Comparing wrong channels** - Use `--diff` to see exact differences
.claude/skills/flow/SKILL.md
new
+30
@@ -0,0 +1,30 @@
1
+---
2
+name: flow
3
+description: Use when you need to run Flow type checking, or when seeing Flow type errors in React code.
4
+---
5
+
6
+# Flow Type Checking
7
+
8
+Arguments:
9
+- $ARGUMENTS: Renderer to check (default: dom-node)
10
+
11
+## Renderers
12
+
13
+| Renderer | When to Use |
14
+|----------|-------------|
15
+| `dom-node` | Default, recommended for most changes |
16
+| `dom-browser` | Browser-specific DOM code |
17
+| `native` | React Native |
18
+| `fabric` | React Native Fabric |
19
+
20
+## Instructions
21
+
22
+1. Run `yarn flow $ARGUMENTS` (use `dom-node` if no argument)
23
+2. Report type errors with file locations
24
+3. For comprehensive checking (slow), use `yarn flow-ci`
25
+
26
+## Common Mistakes
27
+
28
+- **Running without a renderer** - Always specify or use default `dom-node`
29
+- **Ignoring suppressions** - Check if `$FlowFixMe` comments are masking real issues
30
+- **Missing type imports** - Ensure types are imported from the correct package
.claude/skills/test/SKILL.md
new
+46
@@ -0,0 +1,46 @@
1
+---
2
+name: test
3
+description: Use when you need to run tests for React core. Supports source, www, stable, and experimental channels.
4
+---
5
+
6
+Run tests for the React codebase.
7
+
8
+Arguments:
9
+- $ARGUMENTS: Channel, flags, and test pattern
10
+
11
+Usage Examples:
12
+- `/test ReactFiberHooks` - Run with source channel (default)
13
+- `/test experimental ReactFiberHooks` - Run with experimental channel
14
+- `/test www ReactFiberHooks` - Run with www-modern channel
15
+- `/test www variant false ReactFiberHooks` - Test __VARIANT__=false
16
+- `/test stable ReactFiberHooks` - Run with stable channel
17
+- `/test classic ReactFiberHooks` - Run with www-classic channel
18
+- `/test watch ReactFiberHooks` - Run in watch mode (TDD)
19
+
20
+Release Channels:
21
+- `(default)` - Source/canary channel, uses ReactFeatureFlags.js defaults
22
+- `experimental` - Source/experimental channel with __EXPERIMENTAL__ flags = true
23
+- `www` - www-modern channel with __VARIANT__ flags = true
24
+- `www variant false` - www channel with __VARIANT__ flags = false
25
+- `stable` - What ships to npm
26
+- `classic` - Legacy www-classic (rarely needed)
27
+
28
+Instructions:
29
+1. Parse channel from arguments (default: source)
30
+2. Map to yarn command:
31
+ - (default) → `yarn test --silent --no-watchman <pattern>`
32
+ - experimental → `yarn test -r=experimental --silent --no-watchman <pattern>`
33
+ - stable → `yarn test-stable --silent --no-watchman <pattern>`
34
+ - classic → `yarn test-classic --silent --no-watchman <pattern>`
35
+ - www → `yarn test-www --silent --no-watchman <pattern>`
36
+ - www variant false → `yarn test-www --variant=false --silent --no-watchman <pattern>`
37
+3. Report test results and any failures
38
+
39
+Hard Rules:
40
+1. **Use --silent to see failures** - This limits the test output to only failures.
41
+2. **Use --no-watchman** - This is a common failure in sandboxing.
42
+
43
+Common Mistakes:
44
+- **Running without a pattern** - Runs ALL tests, very slow. Always specify a pattern.
45
+- **Forgetting both www variants** - Test `www` AND `www variant false` for `__VARIANT__` flags.
46
+- **Test skipped unexpectedly** - Check for `@gate` pragma; see `feature-flags` skill.
.claude/skills/verify/SKILL.md
new
+24
@@ -0,0 +1,24 @@
1
+---
2
+name: verify
3
+description: Use when you want to validate changes before committing, or when you need to check all React contribution requirements.
4
+---
5
+
6
+# Verification
7
+
8
+Run all verification steps.
9
+
10
+Arguments:
11
+- $ARGUMENTS: Test pattern for the test step
12
+
13
+## Instructions
14
+
15
+Run these first in sequence:
16
+1. Run `yarn prettier` - format code (stop if fails)
17
+2. Run `yarn linc` - lint changed files (stop if fails)
18
+
19
+Then run these with subagents in parallel:
20
+1. Use `/flow` to type check (stop if fails)
21
+2. Use `/test` to test changes in source (stop if fails)
22
+3. Use `/test www` to test changes in www (stop if fails)
23
+
24
+If all pass, show success summary. On failure, stop immediately and report the issue with suggested fixes.
CLAUDE.md
new
+8
@@ -0,0 +1,8 @@
1
+# React
2
+
3
+React is a JavaScript library for building user interfaces.
4
+
5
+## Monorepo Overview
6
+
7
+- **React**: All files outside `/compiler/`
8
+- **React Compiler**: `/compiler/` directory (has its own instructions)
compiler/.claude/settings.json
+9
-2
@@ -5,7 +5,14 @@
5
"Bash(yarn snap:build)",
6
"Bash(node scripts/enable-feature-flag.js:*)"
7
],
8
- "deny": [],
9
- "ask": []
8
+ "deny": [
9
+ "Skill(extract-errors)",
10
+ "Skill(feature-flags)",
11
+ "Skill(fix)",
12
+ "Skill(flags)",
13
+ "Skill(flow)",
14
+ "Skill(test)",
15
+ "Skill(verify)"
16
+ ]
17
}
18
}