PyTorch 官方把 docstring 规范打包成 Skill，Claude 直接按 SOP 写文档

PyTorch 自己怎么写 docstring？这套官方 Skill 直接喂给 Claude 当 SOP

如果你给 PyTorch 项目提过 PR，大概率被 reviewer 揪过 docstring 不规范——Sphinx 引用写错了、shape 没写 LaTeX、Args 顺序不对、有个 tensor 参数漏了 (Tensor, optional) 标注。手动改一遍下来，一个 PR 能磨两小时。

现在 PyTorch 官方把这套「合格 docstring 长啥样」直接打包成一个 Claude Skill，挂在了 pytorch/pytorch 仓库的 .claude/skills/docstring/ 目录下，跟着 Claude Code 一起跑。

它解决什么问题

让 Claude 自动按 PyTorch 项目的规范来写 docstring——raw string、Sphinx/reST 格式、函数签名第一行、math directive 表达 tensor shape、:class: :func: :meth: 交叉引用、Examples:: 块、.warning:: .. note:: 提示框……全部套好。

以前要么靠 reviewer 一个个挑，要么靠 copilot 自由发挥（写出来经常格式不达标）。有了它，Claude 写的第一稿就能过 lint。

核心约束一览

• 必须用 r""" — 因为 PyTorch docstring 里全是 LaTeX 反斜杠，普通字符串会触发转义灾难
• 第一行是函数签名 — 含 positional、keyword-only 参数（* 分隔）、默认值、返回类型，且不结尾句号
• Args 段 — 参数名小写、(Type) 或 (Type, optional) 标注、可选参数尾加 Default: value、双反引号包 inline code、续行缩进 2 空格
• shape 必须用 LaTeX — (text{minibatch} , text{in_channels} , iH , iW) 这种，没有图省事的写法
• Examples 必须有 — Examples:: 后接 >>> prompt，必要时贴上实际输出

这套约束看着繁琐，但就是 PyTorch 几千个公开 API 保持视觉一致的根本——torch.nn.functional 全靠这套规范才能让文档站看着不杂乱。

实战效果

实测在写 gumbel_softmax 这种含 math 公式 + warning + example + 外部论文链接的复杂函数时，Claude 直接吐出来的 docstring 已经能直接复制进 torch/_tensor_docs.py，省掉 reviewer 两轮返工。

对于日常给 PyTorch 写自定义 layer、给自家项目仿 PyTorch 风格写文档的团队，这套 Skill 就是现成的 SOP，不用每次口述规范。

GitHub 仓库直接看 .claude/skills/docstring/SKILL.md，配合 Claude Code 加载就能用：

GitHub： https://github.com/pytorch/pytorch/tree/main/.claude/skills/docstring

顺手给个实用 tip：把 SKILL.md 复制一份改改参数名、默认值、shape 维度，就能给自家框架做一套「风格统一的 docstring SOP」——不用每次给新人发 wiki。

GitHub: https://github.com/pytorch/pytorch/tree/main/.claude/skills/docstring