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/Hook/组件的默认类型）、“learn”（概念/指南）、“blog”（公告）
目标文件	对于更新：在 src/content/ 中查找现有文件。对于新建：根据文档类型确定路径

如果意图不明确，请先让用户澄清再继续。

步骤 2：研究（并行 Agent）

并行启动以下 Agent：

Agent 1：React 专家研究

使用 Task Agent（subagent_type: general-purpose）调用 /react-expert <topic>。该 Agent 将研究 React 源代码、测试、PR、问题和类型签名。

提示词：

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.

Agent 2：现有文档审查

使用 Task Agent（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.

Agent 3：用例研究

使用具备网络搜索能力的 Task Agent（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：综合并制定撰写计划

所有研究 Agent 完成后，制定撰写计划，其中包括：

1. 页面类型（根据 docs-writer-reference 决策树，或 learn/blog 类型）
2. 新建或更新文件的文件路径
3. 大纲，其中的章节标题应与相应模板一致
4. 每个章节的内容说明，根据研究结果整理：
   • API 签名和参数（来自 react-expert 类型）
   • 用法示例（来自 react-expert 测试和用例研究）
   • 注意事项和陷阱（来自 react-expert 警告、错误和问题）
   • 相关页面的交叉引用（来自文档审查）
5. 所需的导航变更（侧边栏 JSON 更新）

向用户展示此计划，并在继续之前征求确认。

步骤 4：撰写文档

分派 Task Agent（subagent_type: general-purpose）来撰写文档。

Agent 提示词必须包含：

1. 步骤 3 中的完整撰写计划
2. 调用相应技能的指示：
   • 参考页面使用 /docs-writer-reference
   • learn 页面使用 /docs-writer-learn
   • 博客文章使用 /docs-writer-blog
3. 调用 /docs-components 以了解 MDX 组件模式的指示
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。该命令会分派并行审核 Agent，检查：

• 结构合规性（docs-writer-*）
• 语气和风格（docs-voice）
• 组件用法（docs-components）
• Sandpack 模式（docs-sandpack）

步骤 6：修复问题

如果审核发现问题：

1. 向用户展示审核清单
2. 修复已发现的问题
3. 对修复后的文件重新运行 /review-docs
4. 重复以上步骤，直到审核通过

重要规则

• 撰写前务必先研究。 切勿仅凭大模型知识撰写文档。
• 撰写前务必与用户确认计划。
• 撰写后务必使用 /review-docs 进行审核。
• 遵循现有模式。 阅读相邻文档，以匹配其风格和详略程度。
• 更新导航。 新页面需要添加侧边栏条目。