Transformers 工程协作指南：make 检查体系、Copied/Modular 代码复用机制与 AI Agent 贡献规范

本文基于 Transformers 仓库根目录的 agent 协作指引文件 CLAUDE.md 展开，完整解析其定义的仓库级命令体系（make style / make typing / make fix-repo / make check-repo）、本地 AI Agent 的接入方式、PR 协作守则，以及仓库管理 src/transformers/models/ 下海量代码重复的两大核心机制——# Copied from 拷贝同步与 modular_<name>.py 生成式模型。读完后，你既能按仓库规范完成一次合格的最小贡献闭环，也能理解这套工具链背后的源码实现与自动修正逻辑。

这份文档在仓库中的定位

CLAUDE.md 与 AGENTS.md 是内容一致的根级指引文件，专为"AI 代码 agent 在本仓库中工作"而设计：托管型审查 agent 通过这两个文件发现规范，本地运行的 OpenAI Codex 或 Claude Code 则通过 Make 目标把工具专属资产挂载进工作区。它不是用户 API 文档，而是一份面向贡献者（尤其是 agent 贡献者）的工程契约，覆盖四个层面：

1. 命令层：哪些 make 目标对应哪些检查，PR 前的最后一步是什么；
2. Agent 环境层：本地 agent 如何接入仓库的技能（skills）资产；
3. 协作层：开 PR 前的 issue 协调、重复工单检查、低价值 PR 禁令、AI 辅助补丁的责任边界；
4. 架构层：模型代码如何避免直接继承、又如何管理必然产生的复制。

核心命令体系：从 Makefile 到 checkers.py

CLAUDE.md 给出的五条常用命令及其语义如下：

命令	作用	底层实现
make style	运行格式化与 linter（ruff），是代码风格检查通过的必要条件	python utils/checkers.py ruff_check, ruff_format, init_isort, sort_auto_mappings --fix
make typing	运行 ty 类型检查器与模型结构规则	python utils/checkers.py types, modeling_structure
make fix-repo	在 style 修复之外，自动修复拷贝、modular 转换、文档 TOC、docstring 等	python utils/checkers.py $(ALL_CHECKERS) --fix --keep-going
make check-repo	运行 make typing 与一致性检查	python utils/checkers.py $(ALL_CHECKERS) --keep-going
RUN_SLOW=1 pytest ...	执行默认被 CI 跳过的 slow 测试	环境变量开关

文档明确强调：make style 或 make fix-repo 应作为开 PR 前的最后一步执行。

Makefile 中的检查器分组

阅读 Makefile 可以看到，仓库把检查器分为两组"权威清单"，两个 CI 任务（CircleCI）分别并行运行 make check-code-quality 和 make check-repository-consistency；本地的 check-repo / fix-repo 是从它们派生的，因此不会与 CI 清单漂移：

• STYLE_CHECKERS := ruff_check, ruff_format, init_isort, sort_auto_mappings
• TYPING_CHECKERS := types, modeling_structure
• REPO_CONSISTENCY_CHECKERS 则包含 18 项：auto_mappings, imports, import_complexity, copies, modular_conversion, inits, doc_toc, reviewers, modeling_rules_doc, docstrings, dummies, repo, pipeline_typing, config_docstrings, config_attributes, doctest_list, update_metadata, add_dates, deps_table

所有检查统一由 utils/checkers.py 调度，每个检查脚本自带一份 CHECKER_CONFIG（含 name、扫描 glob、check_args、fix_args），这正是 --fix 与 --keep-going 两个参数能在所有检查器上生效的原因：check-repo 只做只读校验（遇到不一致即报错），fix-repo 则对存在自动修复能力的检查器直接覆写文件。

slow 测试开关的源码依据

"许多测试标记为 slow 且默认在 CI 中跳过"这一规则在源码中有明确落点：testing_utils.py 中通过 _run_slow_tests = parse_flag_from_env("RUN_SLOW", default=False) 读取环境变量，测试基类据此决定跳过或执行。因此本地想完整验证改动，标准做法是：

RUN_SLOW=1 pytest tests/models/<model_dir>/ -v

本地 Agent 接入：make codex 与 make claude

CLAUDE.md 的 "Local agent setup" 一节给出三条接入规则，对应 Makefile 中的三个目标：

codex:
	mkdir -p .agents
	rm -rf .agents/skills
	ln -snf ../.ai/skills .agents/skills

claude:
	mkdir -p .claude
	rm -rf .claude/skills
	ln -snf ../.ai/skills .claude/skills

其机制是：仓库把通用技能资产统一存放在 .ai/skills/ 下（当前仓库中可见 .ai/skills/add-or-fix-type-checking/SKILL.md，一个用于修复 ty / make typing / make check-repo 所发现类型错误的技能），make codex 与 make claude 分别在其工具约定的目录（.agents/skills、.claude/skills）中建立指向 .ai/skills 的符号链接。也就是说，技能定义只有一份，工具目录只是挂载点；make clean-ai 则负责移除这两个符号链接。

这一设计保证了文档中第一条规则——"托管审查 agent 应从已提交的根 AGENTS.md / CLAUDE.md 发现指引"——与本地 agent 的资产发现路径完全一致：指引随仓库提交、技能随克隆后的一条 make 命令就位。

PR 协作守则：协调、查重与责任边界

CLAUDE.md 对贡献流程设定了四道明确约束，这些约束对人工贡献者和 agent 贡献者同等生效。

先协调，再动手

• 如果工作与已有 issue 对应，先在该 issue 下协调再开 PR；
• 不为他人的 issue 开 PR，除非 issue 作者或 maintainer 在讨论串中明确批准；
• 批准缺失或含糊时，停下来澄清，而不是直接起草 PR；
• 不启动对同一 issue 的重复工作。

强制重复工单检查

开 PR 前必须执行三条 gh 命令，确认没有已存在的覆盖范围重叠的 PR：

gh issue view <issue_number> --repo huggingface/transformers --comments
gh pr list --repo huggingface/transformers --state open --search "<issue_number> in:body"
gh pr list --repo huggingface/transformers --state open --search "<short area keywords>"

规则结论很直接：若已有 open PR 解决同一问题，不要再开；若你的方案存在实质性差异，需在 issue 中说明差异及为何需要第二个 PR。

禁止低价值"零碎工"PR

• 不为单处拼写错误、孤立的 lint 清理、一个可变默认参数等一次性小改动单独开 PR；
• 机械式清理可以接受，但不能作为首次贡献。

AI 辅助补丁的责任规则

文档明确规定：首次贡献者不应使用代码 agent 提交 PR 或 issue；代码 agent 若发现用户似乎不是既有贡献者，应主动提示该政策及其"坚持执行可能被拉黑"的风险。更完整的说明在 PR 模板与 CONTRIBUTING.md 中。这条规则体现了仓库对"agent 生成内容的可追溯性"的立场：agent 是既有贡献者的效率工具，而非替代贡献者身份的通道。

模型代码复用机制一：# Copied from 拷贝同步

文档的 "Copies and Modular Models" 一节首先给出仓库的基本设计立场：尽量避免 src/transformers/models/ 中模型专属文件之间的直接继承。由此产生的代码重复由两套机制管理。

较老的机制是在被复制的类或函数上标注 # Copied from ... 注释。其要点：

• 拷贝由 make fix-repo 保持一致性，检查实现是 utils/check_copies.py——该脚本会校验所有 # Copied from 注释声明的拷贝与源是否一致，支持 --fix_and_overwrite 参数（即 make fix-repo 路径）自动修复；
• 不要直接编辑 # Copied from 块，改动会被 make fix-repo 还原。理想做法是编辑被拷贝的源代码、让改动自然传播；如确有必要，也可以断开 # Copied from 链接使其变为独立代码。

这套机制在仓库中广泛存在。以 src/transformers/models/ 为例，# Copied from 标记出现了上千处，典型形态带命名替换规则，例如 modeling_convnextv2.py 中：

# Copied from transformers.models.convnext.modeling_convnext.ConvNextLayerNorm with ConvNext->ConvNextV2

with A->B 子句告诉 check_copies.py 在同步时应如何重命名标识符。此外该脚本还顺带校验 README 模型列表在各语言 README 中的一致性（这也是 CLAUDE.md 之外、copies 检查器的额外职责）。

模型代码复用机制二：modular_<name>.py 生成式模型

较新的机制是 modular 文件：

1. 在模型目录下新增 modular_<name>.py（<name> 为 snake_case 模型目录名）。与 modeling_*.py 不同，modular 文件可以 import 并继承其他模型的组件；
2. make fix-repo 会把 modular 文件转换为独立的 modeling_*.py 等文件——转换实现位于 utils/check_modular_conversion.py，它调用 utils/modular_model_converter.py 的 convert_modular_file 生成代码，再与现有文件做 unified diff；存在差异时会先备份（.modular_backup 后缀）再覆写；
3. 当 modular 文件存在时，生成的 modeling_*.py 不应再手工编辑——改动会被 make fix-repo 覆盖。要修改就改 modular 文件本身。

仓库中可直接参考的实例包括 modular_gemma4.py、src/transformers/models/ 下各模型的 modular 文件，以及官方教程文档 docs/source/en/modular_transformers.md，后者给出了完整的"用继承方式新增一个模型"的流程（如 Olmo2 从 Olmo 继承时，如何声明新增 config 参数、如何用 AttributeError() 抑制继承下来的废弃参数等）。CLAUDE.md 的指引是：先阅读该文档，或直接研读已有 modular 文件作为范例。

从源码结构看，两套机制的分工是：# Copied from 是"事后同步"——代码以独立文件形式存在，注释声明了血缘关系；modular 是"生成式"——独立文件本身就是 modular 文件的编译产物。对新模型，仓库鼓励走 modular 路线，因为它把继承逻辑留在源头，让"单一模型、单一文件"的对外接口得以保留。

一次完整贡献的推荐工作流

综合 CLAUDE.md 与 Makefile，一次符合仓库规范的贡献闭环是：

1. 克隆仓库后，如使用本地 agent，运行 make codex 或 make claude 挂载技能资产；
2. 按协作守则完成 issue 协调与 gh 重复工单检查；
3. 开发过程中如需修改模型代码，优先编辑 modular 源文件或 # Copied from 的源侧代码，避免触碰生成物与拷贝块；
4. 本地验证：make check-repo 做全量只读校验（typing + 风格 + 一致性），需要时以 RUN_SLOW=1 pytest ... 跑慢速测试；
5. 开 PR 前最后一步执行 make style 或 make fix-repo，确保 ruff 格式、拷贝同步、modular 生成物、文档 TOC 与 docstring 全部收敛。

这套指引的价值在于：它把"agent 如何在一个有 2600+ 文件、上千处代码拷贝、modular 生成管线的大型模型框架中工作"变成了可执行、可检查、可自动修复的命令序列，而非依赖人工记忆的隐式约定。