Storybook docs-review 技能文档策略解析：五种工作模式、六类文档类型与干预阈值

在 Storybook 开源仓库中，官方文档（/docs 目录下的 MDX 页面）的撰写、审查与重构被沉淀为一个名为 docs-review 的 Agent 技能，而其中 references/docs-strategy.md 是该技能的核心策略文件，定义了文档审查的五大工作模式（Mode）、六种文档类型（Doc Type）以及“以最小有效干预改善读者体验”的干预阈值。读完本文，你将掌握一套可直接落地的文档工程方法论：如何为任意文档页面判定工作模式、识别主文档类型与次级章节、诊断页面是否“过载”，并据此选择从维护到重写的正确干预层级——同时了解该策略在仓库中如何与质量维度评估、反模式诊断、风格规范和自动化校验脚本（yarn docs:check）协同运作。

技能定位：docs-strategy.md 在 docs-review 中的角色

docs-review 技能只作用于 /docs 目录下的文档文件与 docs/_snippets/ 中文档拥有的代码片段文件，明确不适用于代码、配置文件或 /docs 之外的 README（见 .agents/skills/docs-review/SKILL.md 的 Scope 一节）。

该技能使用四个参考文件，按固定顺序、按需加载：

文件	职责	加载时机
docs-principles.md	北极星目标、质量维度、双读者要求	始终加载，最先阅读
docs-strategy.md	模式、文档类型、干预阈值、页面形态指导	始终加载，其次阅读
docs-antipatterns.md	诊断模式与修正动作	诊断薄弱或令人困惑的草稿时
storybook-style.md	编辑风格、MDX 组件、frontmatter、格式与校验规则	maintenance 模式下，或编辑模式的最后一遍

其中存在明确的职责边界（Ownership Rules）：策略类参考文件不负责格式或组件规则；storybook-style.md 不负责文档类型识别或干预逻辑；SKILL.md 本身只负责工作流与交接。本文聚焦的策略文件正是中间那个“Always — read second”的核心。

五种工作模式：先选模式，再动手

策略文件的第一原则是“在做任何实质性工作之前先选定模式”。五种模式各自的适用场景与产出如下（完整继承自原文档）：

模式	适用场景	产出
maintenance	页面结构完好，只需编辑性、合规性或格式修复	清理风格、组件、frontmatter 与格式，并运行校验
improve	页面可用，但表述可以更清晰、组织更好、示例更佳	在保持页面身份的前提下强化框架、顺序、解释与示例，并运行校验
rewrite	局部修改无法救活——页面的形态、框架或范围从根本上错误	实质性替换页面。保留仍有效的内容，丢弃或重构其余部分，并运行校验
author	需要创建新页面，或从笔记、简报中完成草稿	以合适的文档类型为指导从头撰写，并运行校验
strategy	用户要的是规划而非修改——页面职责分析、大纲、拆分/合并建议	返回一份规划产物：受众、页面职责、主文档类型、推荐大纲、拆分/合并建议、保留清单。不运行格式或校验

模式选择规则

原文档给出了四条决策规则，构成一套完整的请求消歧逻辑：

• 用户明确命名了模式（例如 "rewrite this"）→ 直接采用该模式；
• 用户只说 "review this doc" 而未给细节 → 采用混合行为（hybrid behavior）：面向 strategy 请求或明显薄弱的草稿，采用“批评优先”（critique-first）；面向常规清理或改进请求，采用“改进优先”（improve-first）；
• 请求含糊（如 "improve this doc"、"make this better"）→ 默认 improve；
• 诊断发现页面结构性薄弱 → 从 improve 升级到 rewrite——当页面形态本身是问题时，不要停留在句子级修改。

这四条规则与 SKILL.md 中的工作流第 1 步完全对应：请求模式映射表中 "Review this doc"（未指明具体）被标注为 hybrid，且明确 “当含糊时，默认 improve，而不是 maintenance”。

六种文档类型：先给页面定型，再谈质量

策略文件要求每个页面有且只有一个主文档类型，且必须在编辑之前选定。页面可以同时包含次级章节（secondary sections）——即带有独立标题、且内容遵循另一文档类型形态的章节，这是正常且被预期的。主类型决定页面整体形态与评估标准，每个次级章节则按它自身类型的标准评估。

六种文档类型及其“页面职责（Page Job）”与“形态（Shape）”：

文档类型	页面职责	形态
concept	帮助读者理解某物是什么、为何重要	定义 → 心智模型 → 与其他概念的关系 → 何时使用
task	帮助读者完成一个具体目标	目标陈述 → 前提条件 → 有序步骤 → 预期结果 → 故障排查
reference	帮助读者查询具体细节（选项、API、配置）	简短引言 → 结构化条目（名称、类型、默认值、描述）→ 有益处的示例
troubleshooting	帮助读者诊断并修复问题	症状 → 原因 → 修复 → 验证
migration	帮助读者从一个版本或方案迁移到另一个	变更了什么 → 为什么 → 逐步迁移路径 → 破坏性变更 → 验证
decision guide	帮助读者在选项间做选择	决策背景 → 带权衡的选项 → 推荐 → 日后如何切换

Overview 页面的映射

/docs 中的 Overview 页面（如章节落地页）不获得特殊类型，而是走两条默认规则：

• 默认为 concept——大多数 overview 解释某功能区域是什么、各部分如何关联；
• 当页面以对比为主时（例如选择 builder 或 renderer），使用 decision guide。

常见的次级章节组合

策略文件用一张表列出了高频、且有惯例形态的“主类型 + 次级章节”组合，这也是判断“组合合理”与“页面过载”的分界线：

主类型	常见次级章节	示例
task	reference——结尾处的 API 选项或配置表	以配置选项表收尾的 “Configure visual tests” 任务页
task	troubleshooting——流程之后的常见错误	以 "Common issues" 条目收尾的 "Set up Storybook" 任务页
concept	task——让概念落地的简短操作	包含简短 "Add a decorator" 流程的 "Decorators" 概念页
concept	reference——相关 API 面的汇总表格	以注解类型表收尾的 "Controls" 概念页
migration	troubleshooting——迁移期间的已知问题	以 "If you see error X" 修复条目收尾的迁移指南
decision guide	reference——选项对比表	带详细功能对比表的 "Choose a builder" 页面

次级章节被视为“结构良好”需要同时满足三条标准：

1. 有自己清晰的标题，标示内容形态的切换（如 "API reference"、"Troubleshooting"、"Quick start"）；
2. 遵循其文档类型所期望的形态（例如 reference 章节用结构化条目而非散文）；
3. 支撑主页面职责，而不是引入无关话题。

拆分与升级规则

当诊断发现页面过载——同时承担多个职责且没有清晰的主类型——应切换到 strategy 模式，或在打磨之前建议拆分页面。注意两点边界：

不构成过载：带有结构良好的次级章节的页面不算过载。任务页结尾附一张 reference 表、概念页附一段简短流程，都是正常的。

真正的过载有四个信号（原文档的 rough signals）：

• 页面没有清晰的主文档类型——两种或多种类型以大致相等的权重争夺主导地位；
• 页面在一个标题下覆盖多个互不相关的功能；
• 某次级章节已膨胀到可以独立成页（粗略判据：超过主内容长度的一半）；
• 概念性散文与步骤式指令贯穿全页交织，而非分离到各自独立的章节。

干预阈值：选择“最小有效干预”

策略文件的结尾给出决策收束——使用能够实质提升读者有用性的最小干预：

• 无结构问题、仅有轻微风格问题 → maintenance
• 结构尚可，但框架、顺序或示例薄弱 → improve
• 结构对该页面的职责而言是错误的 → rewrite
• 页面不存在 → author
• 用户要的是建议而非修改 → strategy

这条阈值表与 SKILL.md 工作流第 4 步一致，并配有一条硬性规则：当草稿结构性薄弱时，不要停留在句子级修改——应重排、拆分、替换示例或重写页面形态。同时有一条拆分/升级规则：当主导职责不清晰、或页面服务多个互不相关的职责时，先切换到 strategy 模式或建议拆分，再谈打磨；而结构良好的次级章节不构成拆分理由。

配套机制：从诊断到校验的完整闭环

要理解这份策略文件的实际运行方式，需要看它如何嵌入 SKILL.md 定义的七步工作流（第 1–4 步为诊断，第 5–7 步为行动）：

1. 确定请求产出：把用户请求映射到模式（含 hybrid 行为与默认 improve）；
2. 确定主文档类型：依据 docs-strategy.md 的类型表分类页面，并识别次级章节；
3. 诊断草稿：按 docs-principles.md 的七个质量维度依序评估——意图清晰度、受众匹配、信息形态、概念清晰度、任务可用性、示例质量、经济性。对次级章节，第 3、5 维度按其自身类型评估，其余维度全页适用。出现结构性弱点时再加载 docs-antipatterns.md 比对模式；
4. 选择干预层级：套用本文第三节的阈值表；
5. 改进或规划：按模式执行；strategy 模式返回的规划产物包含受众、页面职责、主文档类型、推荐大纲、拆分/合并建议、保留清单六项，且不编辑文件、不运行校验；
6. 应用 Storybook 风格：加载 storybook-style.md 作为最终一遍，且永远在结构/编辑工作之后进行；
7. 校验：仅编辑模式运行 yarn fmt:write 与 yarn docs:check，修复后再跑一次确认；strategy 模式或未改动文件时不运行校验。

质量维度与策略文件互为表里：docs-principles.md 明确维度按“从最结构到最表面”排序——先修列表顶部，再打磨底部，且北极星目标是降低读者的 time-to-understanding（理解耗时）或 time-to-success（成功耗时）。它还提出了双读者要求：文档必须同时服务两类读者——扫描答案与步骤的前端开发者，以及为 AI 辅助工作流解析结构化信息的 LLM 与检索系统；写作“为人优先，结构为两者服务”。这正是本文开头所述“容易被搜索引擎、Agent 和 LLM 理解与检索”的方法论来源。

反模式文件 docs-antipatterns.md 则为第 3 步诊断提供了 10 个具体模式，每个都含“问题 → 如何识别 → 如何修复”三段式，包括：背景先行开头、混合文档类型不分离、边缘案例先于默认路径、技术有效但示例如摆设（foo/bar 占位名）、关键术语定义过晚、只列能力不帮读者决策、被埋没的操作结果、因“格式整洁”而保留糟糕结构、过度解释基础却低估 Storybook 特有行为、以及在需要重写时只做文字收紧。其中第 8 条与第 10 条正是策略文件中“升级规则”的具象化：格式整洁不是保留无效页面形态的理由，文字收紧不能替代结构诊断。

自动化校验：策略落地的最后防线

storybook-style.md 中标注 [auto] 的规则（如正文禁用 H1、不跳级标题、Callout 必须带 variant、<CodeSnippets path> 必须指向 docs/_snippets/ 中存在的文件等）由 yarn docs:check 检查，其实现位于 scripts/docs/check-docs.ts，测试用例见 scripts/docs/tests/check-docs.test.ts。从源码结构看，该校验至少覆盖四类检查：相对链接断链检测（含锚点 slug 校验，并豁免指向其他 release 分支的跨版本链接）、<CodeSnippets path="..." /> 指向缺失片段的检测、废弃 <If> 用法的检测，以及 Callout variant 的检测——这与 docs/_snippets/ 下数百个按 功能-场景.md 命名的片段文件（如 button-story.md、main-config-typical.md）共同构成了文档示例的单一事实来源。

值得注意的分层设计：策略文件管“页面该长什么样”（结构决策），风格文件管“句子与组件该怎么写”（表达规范），校验脚本管“规则是否被违反”（机器可查项）。三者各司其职、互不越界，正是 Ownership Rules 在仓库层面的体现。

实践清单：对一页文档套用这套策略

结合原文档内容，可将整套策略收敛为如下可复用流程：

1. 先选模式：请求是否明确命名了模式？含糊则 improve；只要规划则 strategy（并跳过一切格式化与校验）；
2. 再定主类型：从 concept / task / reference / troubleshooting / migration / decision guide 中选一个；overview 页面默认 concept，对比型用 decision guide；
3. 识别次级章节：检查每个带独立标题的章节是否符合其类型形态；对照“常见次级章节组合”表确认组合是否属于惯例形态；
4. 诊断过载：命中四个过载信号中的任何一个，先转 strategy 或建议拆分，不做打磨；
5. 按阈值定干预：结构错 → rewrite；框架/顺序/示例弱 → improve；仅风格问题 → maintenance；页面不存在 → author；
6. 结构先行，风格殿后：结构性改动完成后再套用 storybook-style.md；
7. 最后校验：编辑模式下运行 yarn fmt:write 与 yarn docs:check，修复至通过。

这套“模式 → 类型 → 阈值”的三段式决策，加上质量维度、反模式清单与自动化校验的支撑，使 Storybook 的文档质量不依赖个体作者的审美，而成为一条可被 Agent 复现、可被脚本验证的工程流水线——这也是它作为 AI 时代文档工程实践样本的价值所在。