Mantine 仓库开发规范：从质量门禁到提交约定的完整协作指南（AGENTS.md 解析）-编程实验室

Mantine 仓库开发规范：从质量门禁到提交约定的完整协作指南（AGENTS.md 解析）

【免费下载链接】mantineA fully featured React components library项目地址: https://gitcode.com/GitHub_Trending/ma/mantine

导读

AGENTS.md 是 Mantine 组件库（一个基于 React 的全功能组件库 Monorepo）为代码贡献者与 AI Agent 编写的开发协作指南，明确了"收尾前必跑的质量门禁命令""代码注释规范""测试注意事项"与"提交信息约定"四类规则。阅读本文后，你将掌握在 Mantine 仓库中修改代码、验证改动、编写测试与提交 commit 的完整标准流程，并能理解每条规则背后的工程依据（如 jest 配置、渲染工具实现与 MDX 渲染管线）。

一、收尾质量门禁：Finalizing Your Work

AGENTS.md 要求在任何工作收尾前依次运行一组校验命令，确保改动不会破坏类型、代码风格、构建产物与测试。以下命令均可在仓库根目录直接执行：

# 每次收尾前必跑 npm run typecheck npx oxlint -c oxlint.config.mjs path/to/changed/files npm run format:write:files path/to/changed/files npm run build # 运行与改动路径相关的测试 npm run jest @mantine/charts npm run jest path/to/changed/file.test.ts # 仅当改动涉及样式或 CSS 文件时运行 npm run stylelint # 仅当改动过任何 package.json 的依赖时运行 npm run syncpack

上述命令在 package.json 中均有对应脚本定义，下面逐一说明其真实作用与适用范围：

npm run typecheck：执行tsc --noEmit后依次对apps/mantine.dev与apps/help.mantine.dev两个文档站点做类型检查，覆盖全部包与文档应用。
npx oxlint：仓库使用基于 Oxc 的高性能 lint 工具，默认配置读取 oxlint.config.mjs（由oxc-config-mantine预设扩展而来，并忽略mjs/cjs/js/d.ts/d.mts类型文件）。根目录还提供了npm run oxlint，一次性扫描packages、两个 docs app 的src与scripts；按文档建议，增量开发时只需对改动文件执行。
npm run format:write:files：基于oxfmt（底层是 Oxc formatter），接收改动文件路径参数进行格式化，配置见 oxfmt.config.mjs。全量校验/格式化则分别对应npm run format:test与npm run format:write。
npm run build：执行 scripts/build 构建所有包，用于验证改动可被正常产出。
npm run jest：即jest，配置见 jest.config.ts——使用jest-environment-jsdom环境、esbuild-jest转译 TSX、testMatch匹配**/*.test.ts(x)等文件，并将@mantine/*、@mantine-tests/*映射到对应包的src目录、把 CSS 映射为identity-obj-proxy。可以按包名（如@mantine/charts）或按单文件路径运行，便于做最小范围的快速回归。
npm run stylelint：对**/*.css做样式规范检查并带缓存，仅在改动 CSS 时有必要。
npm run syncpack：对prod,dev两类依赖执行syncpack lint，保证 Monorepo 各包依赖版本声明的一致性，仅在改动过任何package.json后需要运行。

在命令全部通过后，AGENTS.md 还建议检查codexCLI 是否可用（command -v codex），若存在则运行/codex-code-review对未暂存改动做一次自动化代码审查并应用修复。补充一点，CLAUDE.md 中对命令的执行节奏给出了更细的分层建议：oxlint与format:write:files可在每个编辑周期后运行（耗时秒级）；而typecheck（约 30s）与build（约 5–20s）只在推送或交付前整体跑一次即可，多个 commit 的改动可以合并到最后一次 typecheck + build 中统一验证，jest每个包约 2s，可以高频执行。

二、代码注释规范（Code Style）

AGENTS.md 对注释的使用给出三条明确约束：

不要在实现代码中加内联注释：除非被明确要求，描述逻辑或实现细节的内联注释应避免——代码库更偏好"自文档化"的干净实现。
始终保留文档注释：接口、类型与函数参数上的 JSDoc 风格注释（/** */）必须保留，它们是公开 API 的一部分。
类型定义与公开 API 需要维持其文档注释，不能因为清理代码而删除。

从源码结构看，这一规范与 Mantine 大量依赖类型推导、并通过文档注释驱动 API 文档生成的工程方式一致：仓库内置 scripts/docgen 负责从源码抽取类型与注释生成文档数据（对应根目录npm run docs:docgen），因此保留类型上的文档注释不仅是可读性要求，也直接影响文档站点的 Props 表、样式 API 表的正确性。对贡献者而言，新增或修改组件 Props、Hook 参数时，为它们补充/** */注释属于隐性义务。

三、文档（MDX）写作的工程约束

AGENTS.md 配套的 CLAUDE.md 进一步明确了编写文档 MDX 时必须遵守的一条硬约束，值得在此展开：

Markdown 表格语法在文档中不可用。两个文档站点apps/mantine.dev与apps/help.mantine.dev的 MDX 渲染管线未引入remark-gfm，因此管道符表格会被当作普通文本原样渲染在页面上。正确做法是使用<DataTable />组件——它在每个apps/mantine.dev的 MDX 文件中无需导入即可使用，其实现位于 MdxDataTable.tsx，底层基于@mantine/core的 Table 组件，支持head与data两个 props：

<DataTable head={['Prop', 'Components']} data={[ ['valueFormat', '`DateInput`, `DateTimePicker`'], ['weekdayFormat', '`Calendar`, `DatePicker`'], ]} />

该组件还会对包含var(--mantine-scale)的单元格值做缩放值转换处理。如果不想使用表格组件，写成普通列表也是被接受的替代方案。这一约束对任何为 Mantine 贡献文档（包括编写新的.mdx指南页）的开发者都至关重要。

四、测试注意事项：三个易踩的坑

AGENTS.md 与 CLAUDE.md 记录了测试环节最容易出问题的三类场景，均能通过仓库内源码得到印证：

1. 回归测试必须验证"确实会失败"。对覆盖异步、时序或生命周期行为的测试，建议临时回退修复代码、确认测试确实变红，再恢复修复，确认测试由红转绿。这能防止测试因"错误的理由"而静默通过（例如永远通过的空断言或时序巧合）。对于简单的直接断言场景，则无需此流程，属于纯开销。

2.rerender在树结构不一致时会整体卸载重挂。@mantine-tests/core的render()实现见 render.tsx：render会把ui包进一个 Fragment 再交给 testing-library，并自动包裹MantineProvider（env="test"）；但rerender(ui)不会包 Fragment。因此如果传入的树结构形状与之前不同（比如改变 Provider 的层级），React 会判定树类型不同而卸载并重新挂载子树，导致测试实际验证的是"全新挂载"，而非预期的属性更新。正确写法是给rerender的参数也包上<>...</>：

const { rerender } = render(<Provider adapter={a}>...</Provider>); rerender(<><Provider adapter={b}>...</Provider></>);

3. Jest 环境下StrictMode不会双重调用 effect。依赖StrictMode双挂载行为来复现 double-mount 缺陷的测试，在 jest 环境中无论 bug 是否存在都会通过，无法作为有效的回归保障，需要改用其他手段（如显式的挂载/卸载序列）来构造复现场景。

五、提交约定（Commit Conventions）

Mantine 是一个 Monorepo（workspaces 定义于 package.json，覆盖packages/**/*与apps/*），清晰的提交信息对维护 git 历史至关重要。所有提交被分为三类：

package commits—— 与某个具体包相关的改动；
docs commits—— 与文档相关的改动；
core commits—— 仅与仓库工具链相关、不归属任何包的改动。

提交信息由三部分组成，格式为：

[area] Optional title: Message

官方示例：

[core] Fix documentation deployment script—— 仓库脚本改动，与文档或任何包无关；
[mantine.dev] Update report issues link—— 文档站点相关改动；
[@mantine/core] Button: Add theme focus styles——@mantine/core包中 Button 组件的改动；
[@mantine/hooks] use-list-state: Add remove handler——@mantine/hooks包中use-list-statehook 的改动。

这套约定与仓库的自动化发布流程（如scripts/release、scripts/publish及 scripts/publish/decide-publish.ts 等）紧密配合：通过解析提交信息中的包名与范围，可以判断某次发布应当包含哪些包的改动，因此遵循格式不是形式主义，而是发布流水线正常运转的前提。对于提交者，只需对照"改动属于包 / 文档 / 工具链"三选一，并把具体位置与内容浓缩进[area]与标题即可。

结语

AGENTS.md 表面上是给 Agent 和贡献者的一份操作清单，实质是 Mantine 工程文化的最小浓缩：用秒级可跑的 lint/format 守住日常质量，用低频的 typecheck/build 守住交付底线，用注释规范与 MDX 表格约束保护文档生成管线，再用三段式提交信息串联 Monorepo 的发布自动化。无论是人工提交 PR 还是借助 AI Agent 协作开发，遵循这套规则都是让改动顺利进入 Mantine 组件库的最短路径。

【免费下载链接】mantineA fully featured React components library项目地址: https://gitcode.com/GitHub_Trending/ma/mantine

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考