react-expert

React 专家研究技能

概述

此技能通过搜索权威来源（测试、源代码、PR、问题），而非依赖大模型的训练知识，对任何 React API 或概念进行全面的文档研究。

**怀疑原则：** 必须对自己的知识保持怀疑。Claude 的训练数据中经常包含过时或错误的 React 模式。应将源材料视为唯一权威。如果研究结果与你原有的理解相矛盾，请明确指出这一差异。

警示信号——如果发现自己在想以下内容，请立即停止：

• “我知道这个 API 会做 X” → 先找到源代码证据
• “常见模式是 Y” → 在测试文件中验证
• 生成示例代码 → 必须提供源文件引用

调用

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

来源（优先级顺序）

1. React 仓库测试 - 对实际行为最具权威性
2. React 源代码 - 警告、错误、实现细节
3. Git 历史记录 - 附带上下文的提交消息
4. GitHub PR 和评论 - 设计依据（通过 gh CLI）
5. GitHub 问题 - 疑问与困惑（react/react + reactjs/react.dev）
6. React 工作组 - 较新 API 的设计讨论
7. Flow 类型 - 类型签名的事实来源
8. TypeScript 类型 - 注意与 Flow 的差异
9. 当前 react.dev 文档 - 基线参考（不视为完整）

不进行网络搜索 - 不使用 Stack Overflow、博客文章或网络搜索。允许通过 gh CLI 使用 GitHub API。

工作流

步骤 1：设置 React 仓库

首先，确保本地可用 React 仓库：

# Check if React repo exists, clone or update
if [ -d ".claude/react" ]; then
  cd .claude/react && git pull origin main
else
  git clone --depth=100 https://github.com/react/react.git .claude/react
fi

获取研究文档所需的当前提交哈希：

cd .claude/react && git rev-parse --short HEAD

步骤 2：并行分派 6 个研究 Agent

使用 Task 工具并行启动以下 Agent。每个 Agent 都会收到怀疑原则提示：

“你正在研究 React 的 <TOPIC>。重要：不要依赖你对这个 API 的既有知识。你的训练数据可能包含过时或错误的模式。只能报告你在源文件中找到的内容。如果研究结果与常见认知相矛盾，请明确指出这一差异。”

Agent	subagent_type	重点	说明
test-explorer	Explore	测试文件中的用法模式	在 .claude/react/packages/*/src/__tests__/ 中搜索提及该主题的测试文件。提取实际用法示例，并附上文件路径和行号。
source-explorer	Explore	源代码中的警告/错误	在 .claude/react/packages/*/src/ 中搜索提及该主题的 console.error、console.warn 和错误消息。记录触发条件。
git-historian	Explore	提交消息	在 .claude/react 中运行 git log --all --grep="<topic>" --oneline -50。阅读完整提交消息以了解上下文。
pr-researcher	Explore	引入或修改 API 的 PR	运行 gh pr list -R react/react --search "<topic>" --state all --limit 20。阅读关键 PR 的说明和评论。
issue-hunter	Explore	体现困惑的问题	在 react/react 和 reactjs/react.dev 两个仓库中搜索问题。查找常见问题和误解。
types-inspector	Explore	Flow + TypeScript 签名	在 .claude/react/packages/*/src/*.js 中查找 Flow 类型（查找 @flow 注释）。在 .claude/react/packages/*/index.d.ts 中查找 TS 类型。注意其中的差异。

步骤 3：Agent 提示词

启动 Agent 时使用以下确切提示词：

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:
## Test File: <path>
### Test: "<test description>"
```javascript
<exact code from test>

行为： <测试断言的内容>

#### source-explorer

你正在研究 React 的 。

重要：不要依赖你对该 API 的先验知识。只报告你在源文件中找到的内容。

你的任务：查找 的警告、错误和实现细节。

1. 搜索 .claude/react/packages/*/src/，查找：
   • 提及 的 console.error
   • 提及 的 console.warn
   • 提及 的错误消息
   • 主要实现文件
2. 对于每条警告或错误，记录：
   • 完整的消息文本
   • 触发条件
   • 源文件和行号

请按以下格式输出：

警告与错误

消息	触发条件	来源
"<完整消息>"	<条件>	<文件:行号>

实现说明

<源代码中的关键细节>

#### git-historian

你正在研究 React 的 。

重要：不要依赖你的先验知识。只报告你在 git 历史中找到的内容。

你的任务：查找解释 设计决策的提交消息。

1. 运行：cd .claude/react && git log --all --grep="" --oneline -50
2. 对于重要提交，阅读完整消息：git show --stat
3. 查找：
   • API 的首次引入
   • Bug 修复（揭示边缘情况）
   • 行为变更
   • 弃用通知

请按以下格式输出：

关键提交

<短哈希> - <主题>

日期： <日期> 背景： <做出此更改的原因> 影响： <行为发生的变化>

#### pr-researcher

你正在研究 React 的 。

重要：不要依赖你的先验知识。只报告你在 PR 中找到的内容。

你的任务：查找引入或修改 的 PR。

1. 运行：gh pr list -R react/react --search "" --state all --limit 20 --json number,title,url
2. 查看有希望的 PR 的详情：gh pr view -R react/react
3. 查找：
   • 原始 RFC/动机
   • 评论中的设计讨论
   • 考虑过的替代方案
   • 破坏性变更

请按以下格式输出：

关键 PR

PR #：<标题>

URL： 摘要： <引入或更改的内容> 设计依据： <采用这种方案的原因> 讨论要点： <评论中的关键内容>

#### issue-hunter

你正在研究 React 的 。

重要：不要依赖你的先验知识。只报告你在 issue 中找到的内容。

你的任务：查找揭示用户对 常见困惑的 issue。

1. 搜索 react/react：gh issue list -R react/react --search "" --state all --limit 20 --json number,title,url
2. 搜索 reactjs/react.dev：gh issue list -R reactjs/react.dev --search "" --state all --limit 20 --json number,title,url
3. 对于每个 issue，明确：
   • 用户困惑的内容
   • 问题的解决方式
   • 揭示的注意事项（如有）

请按以下格式输出：

常见困惑

Issue #：<标题>

仓库： <react/react 或 reactjs/react.dev> 困惑： <他们误解的内容> 解决方案： <正确的理解> 注意事项： <如适用>

#### types-inspector

你正在研究 React 的 。

重要：不要依赖你的先验知识。只报告你在类型定义中找到的内容。

你的任务：查找并比较 的 Flow 和 TypeScript 类型签名。

1. Flow 类型（事实来源）：搜索 .claude/react/packages//src/.js 中与 相关的 @flow 注解
2. TypeScript 类型：搜索 .claude/react/packages/*/index.d.ts 和 @types/react
3. 比较并指出差异

请按以下格式输出：

Flow 类型（事实来源）

文件： <路径>

<exact type definition>

TypeScript 类型

文件： <路径>

<exact type definition>

差异

<Flow 和 TS 定义之间的任何差异>

### Step 4: Synthesize Results

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.

### Step 5: Save Output

Write the final document to `.claude/research/<topic>.md`

Replace spaces in topic with hyphens (e.g., "suspense boundaries" → "suspense-boundaries.md")

## Output Document Template

```markdown
# React Research: <topic>

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

## Summary

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

## API Signature

### Flow Types (Source of Truth)

[From types-inspector agent]

### TypeScript Types

[From types-inspector agent]

### Discrepancies

[Any differences between Flow and TS]

## Usage Examples

### From Tests

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

### From PRs/Issues

[Real-world patterns from discussions]

## Caveats & Gotchas

[Each with source link]

- **<gotcha>** - Source: <link>

## Warnings & Errors

| Message | Trigger Condition | Source File |
|---------|------------------|-------------|
[From source-explorer agent]

## Common Confusion

[From issue-hunter agent]

## Design Decisions

[From git-historian and pr-researcher agents]

## Source Links

### Commits
- <hash>: <description>

### Pull Requests
- PR #<number>: <title> - <url>

### Issues
- Issue #<number>: <title> - <url>

应避免的常见错误

1. 轻信既有知识 - 即使你“知道”有关 API 的信息，也要找到源证据
2. 生成示例代码 - 每个代码示例都必须来自实际源文件
3. 跳过 Agent - 必须运行全部 6 个 Agent；每个 Agent 都会提供独特视角
4. 不附来源就总结 - 每项陈述都需要文件:行号或 PR/issue 引用
5. 使用网页搜索 - 不要使用 Stack Overflow、博客文章或社交媒体

验证清单

完成研究文档前：

• React 仓库位于 .claude/react，且已知提交哈希
• 全部 6 个 Agent 均已并行启动
• 每个代码示例都有源文件引用
• 警告/错误表包含来源位置
• 所有陈述均有源证据支持
• 已记录 Flow/TS 类型之间的差异
• 来源链接部分完整