write

ドキュメントライター

React のドキュメント作成に向けた調査、執筆、レビューを統括します。

呼び出し

/write add optimisticKey              → creates new reference docs
/write update ViewTransition Activity → updates ViewTransition docs to cover Activity
/write transition learn docs          → creates new learn docs for transitions
/write blog post for React 20         → creates a new blog post

ワークフロー

digraph write_flow {
    rankdir=TB;
    "Parse intent" [shape=box];
    "Research (parallel)" [shape=box];
    "Synthesize plan" [shape=box];
    "Write docs" [shape=box];
    "Review docs" [shape=box];
    "Issues found?" [shape=diamond];
    "Done" [shape=doublecircle];

    "Parse intent" -> "Research (parallel)";
    "Research (parallel)" -> "Synthesize plan";
    "Synthesize plan" -> "Write docs";
    "Write docs" -> "Review docs";
    "Review docs" -> "Issues found?";
    "Issues found?" -> "Write docs" [label="yes - fix"];
    "Issues found?" -> "Done" [label="no"];
}

ステップ 1：意図の解析

ユーザーの指示から次の項目を判断します。

項目	判断方法
アクション	「add」「create」「new」＝新しいページ、「update」「edit」「with」＝既存ページの変更
トピック	React API または概念（例：optimisticKey、ViewTransition、transitions）
ドキュメントの種類	「reference」（API／フック／コンポーネントのデフォルト）、「learn」（概念／ガイド用）、「blog」（告知用）
対象ファイル	更新の場合：src/content/ 内の既存ファイルを探します。新規の場合：ドキュメントの種類からパスを決定します

意図が曖昧な場合は、先にユーザーに確認してください。

ステップ 2：調査（並列エージェント）

次のエージェントを並列で起動します。

エージェント 1：React エキスパートによる調査

Task エージェント（subagent_type: general-purpose）を使い、/react-expert <topic> を実行します。React のソースコード、テスト、PR、issue、型シグネチャを調査します。

プロンプト：

Invoke the /react-expert skill for <TOPIC>. Follow the skill's full workflow:
setup the React repo, dispatch all 6 research agents in parallel, synthesize
results, and save to .claude/research/<topic>.md. Return the full research document.

エージェント 2：既存ドキュメントの監査

Task エージェント（subagent_type: Explore）を使い、トピックに関する既存ドキュメントを探して読み込みます。

プロンプト：

Find all existing documentation related to <TOPIC> in this repo:
1. Search src/content/ for files mentioning <TOPIC>
2. Read any matching files fully
3. For updates: identify what sections exist and what's missing
4. For new pages: identify related pages to understand linking/cross-references
5. Check src/sidebarLearn.json and src/sidebarReference.json for navigation placement

Return: list of existing files with summaries, navigation structure, and gaps.

エージェント 3：ユースケースの調査

Task エージェント（subagent_type: general-purpose）とウェブ検索を使い、一般的なユースケースやパターンを探します。

プロンプト：

Search the web for common use cases and patterns for React's <TOPIC>.
Focus on:
1. Real-world usage patterns developers actually need
2. Common mistakes or confusion points
3. Migration patterns (if replacing an older API)
4. Framework integration patterns (Next.js, Remix, etc.)

Return a summary of the top 5-8 use cases with brief code sketches.
Do NOT search Stack Overflow. Focus on official docs, GitHub discussions,
and high-quality technical blogs.

ステップ 3：調査結果をまとめて執筆計画を作成

すべての調査エージェントが完了したら、次の内容を含む執筆計画を作成します。

1. ページの種類（docs-writer-reference の判定ツリー、または learn／blog の種類に基づく）
2. 新規または更新するファイルのファイルパス
3. 適切なテンプレートに沿ったセクション見出しを含むアウトライン
4. 調査結果に基づく各セクションの内容メモ：
   • API シグネチャとパラメーター（react-expert の型情報から）
   • 使用例（react-expert のテストとユースケース調査から）
   • 注意事項と落とし穴（react-expert の警告／エラー／issue から）
   • 関連ページへの相互参照（ドキュメント監査から）
5. 必要なナビゲーションの変更（サイドバーの JSON 更新）

この計画をユーザーに提示し、作業を進める前に確認を得てください。

ステップ 4：ドキュメントを執筆

Task エージェント（subagent_type: general-purpose）にドキュメントを執筆させます。

エージェントへのプロンプトには、必ず次の内容を含めてください。

1. ステップ 3 で作成した執筆計画の全文
2. 適切なスキルを実行する指示：
   • reference ページには /docs-writer-reference
   • learn ページには /docs-writer-learn
   • blog 投稿には /docs-writer-blog
3. MDX コンポーネントのパターンについて /docs-components を実行する指示
4. インタラクティブなコード例を追加する場合は /docs-sandpack を実行する指示
5. 調査ドキュメントの内容（全出力ではなく、主な調査結果）

プロンプトのテンプレート：

You are writing React documentation. Follow these steps:

1. Invoke /docs-writer-<TYPE> to load the page template and conventions
2. Invoke /docs-components to load MDX component patterns
3. Invoke /docs-sandpack if you need interactive code examples
4. Write the documentation following the plan below

PLAN:
<writing plan from Step 3>

RESEARCH FINDINGS:
<key findings from Step 2 agents>

Write the file to: <target file path>
Also update <sidebar JSON> if adding a new page.

ステップ 5：ドキュメントをレビュー

執筆したファイルに対して /review-docs を実行します。これにより、次の項目をチェックする並列レビューエージェントが起動します。

• 構成への準拠（docs-writer-*）
• 文体とスタイル（docs-voice）
• コンポーネントの使用方法（docs-components）
• Sandpack のパターン（docs-sandpack）

ステップ 6：問題を修正

レビューで問題が見つかった場合：

1. レビューチェックリストをユーザーに提示します
2. 指摘された問題を修正します
3. 修正したファイルに対して /review-docs を再実行します
4. 問題がなくなるまで繰り返します

重要なルール

• 執筆前に必ず調査してください。 LLM の知識だけを頼りにドキュメントを書いてはいけません。
• 執筆前に必ず計画をユーザーに確認してください。
• 執筆後は必ず /review-docs でレビューしてください。
• 既存のパターンに合わせてください。 隣接するドキュメントを読み、文体や詳しさをそろえてください。
• ナビゲーションを更新してください。 新しいページにはサイドバーの項目が必要です。