React Expert Research Skill

概要

このスキルは、LLM の学習知識に頼らず、権威のあるソース(テスト、ソースコード、PR、Issue)を検索することにより、任意の React API またはコンセプトについて徹底的なドキュメント調査を実施します。

<CRITICAL> **懐疑的態度の強制:** 自分の知識に対して懐疑的である必要があります。Claude は古い、または誤った React パターンについて学習していることが多いです。ソース資料を唯一の権威として扱ってください。調査結果が以前の理解と矛盾する場合は、この矛盾を明示的にフラグしてください。

危険信号 - 次のように考えている場合は STOP してください:

• 「この API は X を実行するとわかっている」→ 最初にソース証拠を探す
• 「一般的なパターンは Y である」→ テストファイルで検証する
• サンプルコードを生成している → ソースファイルの参照が必須 </CRITICAL>

呼び出し

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

ソース(優先度順)

1. React Repo Tests - 実際の動作について最も信頼できる
2. React Source Code - 警告、エラー、実装の詳細
3. Git History - コンテキスト付きコミットメッセージ
4. GitHub PRs & Comments - 設計根拠(gh CLI 経由)
5. GitHub Issues - 混乱と質問(facebook/react + reactjs/react.dev)
6. React Working Group - 新しい API の設計議論
7. Flow Types - 型署名の真実のソース
8. TypeScript Types - Flow との矛盾に注意
9. 現在の react.dev ドキュメント - ベースライン(完全とは信頼できない)

Web 検索なし - Stack Overflow、ブログ記事、または Web 検索はありません。gh CLI を経由した GitHub API は許可されます。

ワークフロー

ステップ 1: React Repo をセットアップ

まず、React repo がローカルで利用可能であることを確認します:

# React repo が存在するか確認し、クローンまたは更新
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

調査ドキュメント用の現在のコミットハッシュを取得:

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

ステップ 2: 6 つの並列研究エージェントをディスパッチ

Task ツールを使用して、これらのエージェントを並列で起動します。各エージェントは懐疑的態度の前置きを受け取ります:

「あなたは React の <TOPIC> を調査しています。重要: この API についての事前知識に頼らないでください。あなたの学習には古い、または誤ったパターンが含まれている可能性があります。ソースファイルで見つけたもののみを報告してください。あなたの調査結果が一般的な理解と矛盾する場合は、この矛盾を明示的にハイライトしてください。」

エージェント	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 facebook/react --search "<topic>" --state all --limit 20 を実行します。主要な PR の説明とコメントを読みます。
issue-hunter	Explore	混乱を示す Issue	facebook/react と reactjs/react.dev の両方のリポジトリで Issue を検索します。一般的な質問と誤解を探します。
types-inspector	Explore	Flow + TypeScript シグネチャ	.claude/react/packages/*/src/*.js で Flow タイプを探します(@flow アノテーションを探します)。.claude/react/packages/*/index.d.ts で TS タイプを探します。矛盾を注記します。

ステップ 3: エージェントプロンプト

エージェントを起動するときに、これらの正確なプロンプトを使用します:

test-explorer

あなたは React の <TOPIC> を調査しています。

重要: この API についての事前知識に頼らないでください。あなたの学習には古い、または誤ったパターンが含まれている可能性があります。ソースファイルで見つけたもののみを報告してください。

あなたのタスク: .claude/react の <TOPIC> の使用例を示すテストファイルを探します。

1. テストファイルを検索: `**/__tests__/**/*<topic>*` と `**/__tests__/**/*.js` の glob 検索、その後 <topic> の grep を実行
2. 関連する各テストファイルについて、以下を抽出します:
   - テストの説明(describe/it ブロック)
   - 実際の使用コード
   - 動作に関するアサーション
   - テストされるエッジケース
3. 正確なファイルパスと行番号を含めて調査結果を報告します

出力形式:
## Test File: <path>
### Test: "<test description>"
```javascript
<exact code from test>

Behavior: <what the test asserts>

#### source-explorer

あなたは React の <TOPIC> を調査しています。

重要: この API についての事前知識に頼らないでください。ソースファイルで見つけたもののみを報告してください。

あなたのタスク: <TOPIC> の警告、エラー、実装の詳細を探します。

1. .claude/react/packages/*/src/ で以下を検索します:
   • <topic> に言及する console.error
   • <topic> に言及する console.warn
   • <topic> に言及するエラーメッセージ
   • メイン実装ファイル
2. 各警告/エラーについて、以下を文書化します:
   • 正確なメッセージテキスト
   • それをトリガーする条件
   • ソースファイルと行番号

出力形式:

Warnings & Errors

Message	Trigger Condition	Source
"<exact message>"	<condition>	file:line

Implementation Notes

<key details from source code> ```

git-historian

あなたは React の <TOPIC> を調査しています。

重要: 事前知識に頼らないでください。git history で見つけたもののみを報告してください。

あなたのタスク: <TOPIC> の設計決定を説明するコミットメッセージを探します。

1. 実行: cd .claude/react && git log --all --grep="<topic>" --oneline -50
2. 重要なコミットについて、完全なメッセージを読みます: git show <hash> --stat
3. 以下を探します:
   - API の初期導入
   - バグ修正(エッジケースを明かす)
   - 動作の変更
   - 非推奨通知

出力形式:
## Key Commits
### <short hash> - <subject>
**Date:** <date>
**Context:** <why this change was made>
**Impact:** <what behavior changed>

pr-researcher

あなたは React の <TOPIC> を調査しています。

重要: 事前知識に頼らないでください。PR で見つけたもののみを報告してください。

あなたのタスク: <TOPIC> を導入または変更した PR を探します。

1. 実行: gh pr list -R facebook/react --search "<topic>" --state all --limit 20 --json number,title,url
2. 有望な PR については、詳細を読みます: gh pr view <number> -R facebook/react
3. 以下を探します:
   - 元の RFC/動機
   - コメント内の設計議論
   - 検討された代替アプローチ
   - 破壊的変更

出力形式:
## Key PRs
### PR #<number>: <title>
**URL:** <url>
**Summary:** <what it introduced/changed>
**Design Rationale:** <why this approach>
**Discussion Highlights:** <key points from comments>

issue-hunter

あなたは React の <TOPIC> を調査しています。

重要: 事前知識に頼らないでください。Issue で見つけたもののみを報告してください。

あなたのタスク: <TOPIC> について一般的な混乱を明かす Issue を探します。

1. facebook/react を検索: gh issue list -R facebook/react --search "<topic>" --state all --limit 20 --json number,title,url
2. reactjs/react.dev を検索: gh issue list -R reactjs/react.dev --search "<topic>" --state all --limit 20 --json number,title,url
3. 各 Issue について、以下を特定します:
   - ユーザーが何について混乱していたか
   - 解決策は何だったか
   - 明かされたゴットチャ

出力形式:
## Common Confusion
### Issue #<number>: <title>
**Repo:** <facebook/react or reactjs/react.dev>
**Confusion:** <what they misunderstood>
**Resolution:** <correct understanding>
**Gotcha:** <if applicable>

types-inspector

あなたは React の <TOPIC> を調査しています。

重要: 事前知識に頼らないでください。型定義で見つけたもののみを報告してください。

あなたのタスク: <TOPIC> の Flow と TypeScript 型署名を探して比較します。

1. Flow タイプ(真実のソース): .claude/react/packages/*/src/*.js で <topic> に関連する @flow アノテーションを検索
2. TypeScript タイプ: .claude/react/packages/*/index.d.ts と @types/react を検索
3. 比較して矛盾を注記

出力形式:
## Flow Types (Source of Truth)
**File:** <path>
```flow
<exact type definition>

TypeScript Types

File: <path>

<exact type definition>

Discrepancies

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

ステップ 4: 結果を統合

すべてのエージェントが完了したら、その調査結果を単一の研究ドキュメントに結合します。

独自の知識から情報を追加しないでください。 エージェントがソースで見つけたものだけを含めてください。

ステップ 5: 出力を保存

最終ドキュメントを .claude/research/<topic>.md に書き込みます

トピック内のスペースをハイフンに置き換えます(例: 「suspense boundaries」→「suspense-boundaries.md」)

出力ドキュメントテンプレート

# React Research: <topic>

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

## Summary

[ソース調査結果のみに基づいた簡潔な概要。事前知識ではない]

## API Signature

### Flow Types (Source of Truth)

[types-inspector エージェントから]

### TypeScript Types

[types-inspector エージェントから]

### Discrepancies

[Flow と TS の間の違い]

## Usage Examples

### From Tests

[test-explorer エージェントから - file:line 参照付き]

### From PRs/Issues

[議論からの実世界パターン]

## Caveats & Gotchas

[それぞれソースリンク付き]

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

## Warnings & Errors

| Message | Trigger Condition | Source File |
|---------|------------------|-------------|
[source-explorer エージェントから]

## Common Confusion

[issue-hunter エージェントから]

## Design Decisions

[git-historian と pr-researcher エージェントから]

## Source Links

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

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

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

避けるべき一般的な誤り

1. 事前知識の信頼 - API について「知っている」場合でも、とにかくソース証拠を探す
2. サンプルコード生成 - すべてのコード例は実際のソースファイルから来る必要があります
3. エージェントをスキップ - すべての 6 つのエージェントを実行する必要があります。各々が独自の観点を提供します
4. ソースなしの要約 - すべての主張には file:line または PR/Issue 参照が必要です
5. Web 検索を使用 - Stack Overflow、ブログ記事、ソーシャルメディアはありません

検証チェックリスト

研究ドキュメントを最終化する前に:

• React repo は .claude/react にあり、既知のコミットハッシュがある
• 6 つのエージェントすべてが並列で起動された
• すべてのコード例にはソースファイル参照がある
• 警告/エラーテーブルにはソース位置がある
• ソース証拠なしに主張は作られていない
• Flow/TS タイプ間の矛盾が文書化されている
• ソースリンクセクションが完成している