Back to Details

react-expert

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

React Expert Research Skill

React 专家研究技能

Overview

概述

This skill produces exhaustive documentation research on any React API or concept by searching authoritative sources (tests, source code, PRs, issues) rather than relying on LLM training knowledge.
<CRITICAL> **Skepticism Mandate:** You must be skeptical of your own knowledge. Claude is often trained on outdated or incorrect React patterns. Treat source material as the sole authority. If findings contradict your prior understanding, explicitly flag this discrepancy.
Red Flags - STOP if you catch yourself thinking:
  • "I know this API does X" → Find source evidence first
  • "Common pattern is Y" → Verify in test files
  • Generating example code → Must have source file reference
</CRITICAL>
该技能通过搜索权威来源（测试、源代码、PR、问题）而非依赖大语言模型的训练知识，生成关于任意React API或概念的详尽文档研究。
<CRITICAL> **怀疑原则：** 你必须对自己的知识持怀疑态度。Claude的训练数据中常包含过时或错误的React模式。将原始资料视为唯一权威。如果发现的内容与你之前的理解相矛盾，需明确标记这种差异。
警示信号 - 如果你有以下想法请立即停止：
  • "我知道这个API的作用是X" → 先找到原始证据
  • "常见模式是Y" → 在测试文件中验证
  • 生成示例代码 → 必须附带原始文件引用
</CRITICAL>

Invocation

调用方式

/react-expert useTransition
/react-expert suspense boundaries
/react-expert startTransition
/react-expert useTransition
/react-expert suspense boundaries
/react-expert startTransition

Sources (Priority Order)

来源（优先级顺序）

  1. React Repo Tests - Most authoritative for actual behavior
  2. React Source Code - Warnings, errors, implementation details
  3. Git History - Commit messages with context
  4. GitHub PRs & Comments - Design rationale (via 
    gh
    CLI)
  5. GitHub Issues - Confusion/questions (facebook/react + reactjs/react.dev)
  6. React Working Group - Design discussions for newer APIs
  7. Flow Types - Source of truth for type signatures
  8. TypeScript Types - Note discrepancies with Flow
  9. Current react.dev docs - Baseline (not trusted as complete)
No web search - No Stack Overflow, blog posts, or web searches. GitHub API via 
gh
CLI is allowed.
  1. React 仓库测试 - 最能体现实际行为的权威来源
  2. React 源代码 - 警告、错误、实现细节
  3. Git 历史 - 带有上下文的提交信息
  4. GitHub PR 与评论 - 设计原理（通过
    gh
    CLI获取）
  5. GitHub 问题 - 困惑与疑问（来自facebook/react + reactjs/react.dev）
  6. React 工作组 - 新API的设计讨论
  7. Flow 类型 - 类型签名的权威来源
  8. TypeScript 类型 - 注意与Flow的差异
  9. 当前 react.dev 文档 - 基础参考（不视为完整权威）
禁止网页搜索 - 不得使用Stack Overflow、博客文章或网页搜索。允许通过
gh
CLI调用GitHub API。

Workflow

工作流程

Step 1: Setup React Repo

步骤1：搭建React仓库

First, ensure the React repo is available locally:
bash
undefined
首先确保本地已有React仓库：
bash
undefined

Check if React repo exists, clone or update

检查React仓库是否存在，存在则拉取更新，不存在则克隆

if [ -d ".claude/react" ]; then cd .claude/react && git pull origin main else git clone --depth=100 https://github.com/facebook/react.git .claude/react fi

Get the current commit hash for the research document:
```bash
cd .claude/react && git rev-parse --short HEAD
if [ -d ".claude/react" ]; then cd .claude/react && git pull origin main else git clone --depth=100 https://github.com/facebook/react.git .claude/react fi

获取研究文档对应的当前提交哈希：
```bash
cd .claude/react && git rev-parse --short HEAD

Step 2: Dispatch 6 Parallel Research Agents

步骤2：启动6个并行研究Agent

Spawn these agents IN PARALLEL using the Task tool. Each agent receives the skepticism preamble:
"You are researching React's 
<TOPIC>
. CRITICAL: Do NOT rely on your prior knowledge about this API. Your training may contain outdated or incorrect patterns. Only report what you find in the source files. If your findings contradict common understanding, explicitly highlight this discrepancy."
Agentsubagent_typeFocusInstructions
test-explorerExploreTest files for usage patternsSearch 
.claude/react/packages/*/src/__tests__/
for test files mentioning the topic. Extract actual usage examples WITH file paths and line numbers.
source-explorerExploreWarnings/errors in sourceSearch 
.claude/react/packages/*/src/
for console.error, console.warn, and error messages mentioning the topic. Document trigger conditions.
git-historianExploreCommit messagesRun 
git log --all --grep="<topic>" --oneline -50
in 
.claude/react
. Read full commit messages for context.
pr-researcherExplorePRs introducing/modifying APIRun 
gh pr list -R facebook/react --search "<topic>" --state all --limit 20
. Read key PR descriptions and comments.
issue-hunterExploreIssues showing confusionSearch issues in both 
facebook/react
and 
reactjs/react.dev
repos. Look for common questions and misunderstandings.
types-inspectorExploreFlow + TypeScript signaturesFind Flow types in 
.claude/react/packages/*/src/*.js
(look for 
@flow
annotations). Find TS types in 
.claude/react/packages/*/index.d.ts
. Note discrepancies.
使用任务工具并行启动以下Agent，每个Agent都会收到怀疑原则的前置说明：
"你正在研究React的
<TOPIC>
。重要提示：请勿依赖你关于该API的已有知识。你的训练数据可能包含过时或错误的模式。仅报告你在原始文件中发现的内容。如果发现的内容与普遍理解相矛盾，请明确强调这种差异。"
Agent子Agent类型研究重点说明
test-explorer探索类测试文件中的使用模式搜索
.claude/react/packages/*/src/__tests__/
中提及研究主题的测试文件。提取实际使用示例，并附带文件路径和行号。
source-explorer探索类源代码中的警告/错误搜索
.claude/react/packages/*/src/
中提及研究主题的console.error、console.warn和错误信息。记录触发条件。
git-historian探索类提交信息在
.claude/react
中运行
git log --all --grep="<topic>" --oneline -50
。阅读完整提交信息以获取上下文。
pr-researcher探索类引入/修改API的PR运行
gh pr list -R facebook/react --search "<topic>" --state all --limit 20
。阅读关键PR的描述和评论。
issue-hunter探索类体现用户困惑的问题搜索
facebook/react
和
reactjs/react.dev
仓库的问题。寻找常见疑问和误解。
types-inspector探索类Flow + TypeScript签名在
.claude/react/packages/*/src/*.js
中查找带有
@flow
注解的Flow类型。在
.claude/react/packages/*/index.d.ts
中查找TS类型。记录两者的差异。

Step 3: Agent Prompts

步骤3：Agent提示词

Use these exact prompts when spawning agents:
启动Agent时请使用以下精确提示词：

test-explorer

test-explorer

You are researching React's <TOPIC>.

CRITICAL: Do NOT rely on your prior knowledge about this API. Your training may contain outdated or incorrect patterns. Only report what you find in the source files.

Your task: Find test files in .claude/react that demonstrate <TOPIC> usage.

1. Search for test files: Glob for `**/__tests__/**/*<topic>*` and `**/__tests__/**/*.js` then grep for <topic>
2. For each relevant test file, extract:
   - The test description (describe/it blocks)
   - The actual usage code
   - Any assertions about behavior
   - Edge cases being tested
3. Report findings with exact file paths and line numbers

Format your output as:
You are researching React's <TOPIC>.

CRITICAL: Do NOT rely on your prior knowledge about this API. Your training may contain outdated or incorrect patterns. Only report what you find in the source files.

Your task: Find test files in .claude/react that demonstrate <TOPIC> usage.

1. Search for test files: Glob for `**/__tests__/**/*<topic>*` and `**/__tests__/**/*.js` then grep for <topic>
2. For each relevant test file, extract:
   - The test description (describe/it blocks)
   - The actual usage code
   - Any assertions about behavior
   - Edge cases being tested
3. Report findings with exact file paths and line numbers

Format your output as:

Test File: <path>

Test File: <path>

Test: "<test description>"

Test: "<test description>"

javascript
<exact code from test>
Behavior: <what the test asserts>
undefined
javascript
<exact code from test>
Behavior: <what the test asserts>
undefined

source-explorer

source-explorer

You are researching React's <TOPIC>.

CRITICAL: Do NOT rely on your prior knowledge about this API. Only report what you find in the source files.

Your task: Find warnings, errors, and implementation details for <TOPIC>.

1. Search .claude/react/packages/*/src/ for:
   - console.error mentions of <topic>
   - console.warn mentions of <topic>
   - Error messages mentioning <topic>
   - The main implementation file
2. For each warning/error, document:
   - The exact message text
   - The condition that triggers it
   - The source file and line number

Format your output as:
You are researching React's <TOPIC>.

CRITICAL: Do NOT rely on your prior knowledge about this API. Only report what you find in the source files.

Your task: Find warnings, errors, and implementation details for <TOPIC>.

1. Search .claude/react/packages/*/src/ for:
   - console.error mentions of <topic>
   - console.warn mentions of <topic>
   - Error messages mentioning <topic>
   - The main implementation file
2. For each warning/error, document:
   - The exact message text
   - The condition that triggers it
   - The source file and line number

Format your output as:

Warnings & Errors

Warnings & Errors

MessageTrigger ConditionSource
"<exact message>"<condition>file:line
MessageTrigger ConditionSource
"<exact message>"<condition>file:line

Implementation Notes

Implementation Notes

<key details from source code> ```
<key details from source code> ```

git-historian

git-historian

You are researching React's <TOPIC>.

CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in git history.

Your task: Find commit messages that explain <TOPIC> design decisions.

1. Run: cd .claude/react && git log --all --grep="<topic>" --oneline -50
2. For significant commits, read full message: git show <hash> --stat
3. Look for:
   - Initial introduction of the API
   - Bug fixes (reveal edge cases)
   - Behavior changes
   - Deprecation notices

Format your output as:
You are researching React's <TOPIC>.

CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in git history.

Your task: Find commit messages that explain <TOPIC> design decisions.

1. Run: cd .claude/react && git log --all --grep="<topic>" --oneline -50
2. For significant commits, read full message: git show <hash> --stat
3. Look for:
   - Initial introduction of the API
   - Bug fixes (reveal edge cases)
   - Behavior changes
   - Deprecation notices

Format your output as:

Key Commits

Key Commits

<short hash> - <subject>

<short hash> - <subject>

Date: <date> Context: <why this change was made> Impact: <what behavior changed>
undefined
Date: <date> Context: <why this change was made> Impact: <what behavior changed>
undefined

pr-researcher

pr-researcher

You are researching React's <TOPIC>.

CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in PRs.

Your task: Find PRs that introduced or modified <TOPIC>.

1. Run: gh pr list -R facebook/react --search "<topic>" --state all --limit 20 --json number,title,url
2. For promising PRs, read details: gh pr view <number> -R facebook/react
3. Look for:
   - The original RFC/motivation
   - Design discussions in comments
   - Alternative approaches considered
   - Breaking changes

Format your output as:
You are researching React's <TOPIC>.

CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in PRs.

Your task: Find PRs that introduced or modified <TOPIC>.

1. Run: gh pr list -R facebook/react --search "<topic>" --state all --limit 20 --json number,title,url
2. For promising PRs, read details: gh pr view <number> -R facebook/react
3. Look for:
   - The original RFC/motivation
   - Design discussions in comments
   - Alternative approaches considered
   - Breaking changes

Format your output as:

Key PRs

Key PRs

PR #<number>: <title>

PR #<number>: <title>

URL: <url> Summary: <what it introduced/changed> Design Rationale: <why this approach> Discussion Highlights: <key points from comments>
undefined
URL: <url> Summary: <what it introduced/changed> Design Rationale: <why this approach> Discussion Highlights: <key points from comments>
undefined

issue-hunter

issue-hunter

You are researching React's <TOPIC>.

CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in issues.

Your task: Find issues that reveal common confusion about <TOPIC>.

1. Search facebook/react: gh issue list -R facebook/react --search "<topic>" --state all --limit 20 --json number,title,url
2. Search reactjs/react.dev: gh issue list -R reactjs/react.dev --search "<topic>" --state all --limit 20 --json number,title,url
3. For each issue, identify:
   - What the user was confused about
   - What the resolution was
   - Any gotchas revealed

Format your output as:
You are researching React's <TOPIC>.

CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in issues.

Your task: Find issues that reveal common confusion about <TOPIC>.

1. Search facebook/react: gh issue list -R facebook/react --search "<topic>" --state all --limit 20 --json number,title,url
2. Search reactjs/react.dev: gh issue list -R reactjs/react.dev --search "<topic>" --state all --limit 20 --json number,title,url
3. For each issue, identify:
   - What the user was confused about
   - What the resolution was
   - Any gotchas revealed

Format your output as:

Common Confusion

Common Confusion

Issue #<number>: <title>

Issue #<number>: <title>

Repo: <facebook/react or reactjs/react.dev> Confusion: <what they misunderstood> Resolution: <correct understanding> Gotcha: <if applicable>
undefined
Repo: <facebook/react or reactjs/react.dev> Confusion: <what they misunderstood> Resolution: <correct understanding> Gotcha: <if applicable>
undefined

types-inspector

types-inspector

You are researching React's <TOPIC>.

CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in type definitions.

Your task: Find and compare Flow and TypeScript type signatures for <TOPIC>.

1. Flow types (source of truth): Search .claude/react/packages/*/src/*.js for @flow annotations related to <topic>
2. TypeScript types: Search .claude/react/packages/*/index.d.ts and @types/react
3. Compare and note any discrepancies

Format your output as:
You are researching React's <TOPIC>.

CRITICAL: Do NOT rely on your prior knowledge. Only report what you find in type definitions.

Your task: Find and compare Flow and TypeScript type signatures for <TOPIC>.

1. Flow types (source of truth): Search .claude/react/packages/*/src/*.js for @flow annotations related to <topic>
2. TypeScript types: Search .claude/react/packages/*/index.d.ts and @types/react
3. Compare and note any discrepancies

Format your output as:

Flow Types (Source of Truth)

Flow Types (Source of Truth)

File: <path>
flow
<exact type definition>
File: <path>
flow
<exact type definition>

TypeScript Types

TypeScript Types

File: <path>
typescript
<exact type definition>
File: <path>
typescript
<exact type definition>

Discrepancies

Discrepancies

<any differences between Flow and TS definitions> ```
<any differences between Flow and TS definitions> ```

Step 4: Synthesize Results

步骤4：综合结果

After all agents complete, combine their findings into a single research document.
DO NOT add information from your own knowledge. Only include what agents found in sources.
所有Agent完成任务后，将它们的发现整合为一份研究文档。
请勿添加任何来自你自身知识的信息。 仅包含Agent在原始来源中发现的内容。

Step 5: Save Output

步骤5：保存输出

Write the final document to 
.claude/research/<topic>.md
Replace spaces in topic with hyphens (e.g., "suspense boundaries" → "suspense-boundaries.md")
将最终文档写入
.claude/research/<topic>.md
将主题中的空格替换为连字符（例如："suspense boundaries" → "suspense-boundaries.md"）

Output Document Template

输出文档模板

markdown
undefined
markdown
undefined

React Research: <topic>

React Research: <topic>

Generated by /react-expert on YYYY-MM-DD Sources: React repo (commit <hash>), N PRs, M issues
Generated by /react-expert on YYYY-MM-DD Sources: React repo (commit <hash>), N PRs, M issues

Summary

Summary

[Brief summary based SOLELY on source findings, not prior knowledge]
[Brief summary based SOLELY on source findings, not prior knowledge]

API Signature

API Signature

Flow Types (Source of Truth)

Flow Types (Source of Truth)

[From types-inspector agent]
[From types-inspector agent]

TypeScript Types

TypeScript Types

[From types-inspector agent]
[From types-inspector agent]

Discrepancies

Discrepancies

[Any differences between Flow and TS]
[Any differences between Flow and TS]

Usage Examples

Usage Examples

From Tests

From Tests

[From test-explorer agent - with file:line references]
[From test-explorer agent - with file:line references]

From PRs/Issues

From PRs/Issues

[Real-world patterns from discussions]
[Real-world patterns from discussions]

Caveats & Gotchas

Caveats & Gotchas

[Each with source link]
  • <gotcha> - Source: <link>
[Each with source link]
  • <gotcha> - Source: <link>

Warnings & Errors

Warnings & Errors

MessageTrigger ConditionSource File
[From source-explorer agent]
MessageTrigger ConditionSource File
[From source-explorer agent]

Common Confusion

Common Confusion

[From issue-hunter agent]
[From issue-hunter agent]

Design Decisions

Design Decisions

[From git-historian and pr-researcher agents]
[From git-historian and pr-researcher agents]

Source Links

Source Links

Commits

Commits

  • <hash>: <description>
  • <hash>: <description>

Pull Requests

Pull Requests

  • PR #<number>: <title> - <url>
  • PR #<number>: <title> - <url>

Issues

Issues

  • Issue #<number>: <title> - <url>
undefined
  • Issue #<number>: <title> - <url>
undefined

Common Mistakes to Avoid

需避免的常见错误

  1. Trusting prior knowledge - If you "know" something about the API, find the source evidence anyway
  2. Generating example code - Every code example must come from an actual source file
  3. Skipping agents - All 6 agents must run; each provides unique perspective
  4. Summarizing without sources - Every claim needs a file:line or PR/issue reference
  5. Using web search - No Stack Overflow, no blog posts, no social media
  1. 依赖已有知识 - 如果你“了解”某个API的信息，一定要找到原始证据
  2. 生成无来源的示例代码 - 每段代码示例都必须来自实际的原始文件
  3. 跳过Agent - 必须运行全部6个Agent；每个Agent都能提供独特视角
  4. 无来源的总结 - 每个结论都需要附带文件行号或PR/问题引用
  5. 使用网页搜索 - 禁止使用Stack Overflow、博客文章或社交媒体内容

Verification Checklist

验证清单

Before finalizing the research document:
  • React repo is at 
    .claude/react
    with known commit hash
  • All 6 agents were spawned in parallel
  • Every code example has a source file reference
  • Warnings/errors table has source locations
  • No claims made without source evidence
  • Discrepancies between Flow/TS types documented
  • Source links section is complete
在最终确定研究文档前，请检查：
  • React仓库位于
    .claude/react
    ，且提交哈希已知
  • 已并行启动全部6个Agent
  • 每段代码示例都有原始文件引用
  • 警告/错误表格包含来源位置
  • 所有结论都有原始证据支持
  • Flow/TS类型之间的差异已记录
  • 来源链接部分完整