编辑文档 - antd v6 把 Agent Skill 做成了一等公民：6 个 Skill + 1 份 AGENTS.md + 1 份 CLAUDE.md 完整拆解

标题

工具栏

点击或拖拽上传图片

支持 PNG, JPG, GIF, WebP 格式

内容 (Markdown 格式)

---

这段时间我一直在跟 antd v6 的更新。v6.4.4（2026-06-12 发布）是目前的稳定版，距离 v6.4.0 这个 6.x 第一个大版本刚过去一个月。原本我以为重点会放在 React 19、设计 Token、CSS-in-JS 重构这些「看得见」的事情上，结果拉仓库看 master 分支的时候，被一个细节钉在屏幕前了：

`AGENTS.md`、`CLAUDE.md`、`.agents/skills/`、`.claude/skills`、`.cursor/skills`——这些**给 AI Agent 用的工程资产**，被 antd 团队做成了和 84 个 React 组件并列的一等公民。

我反复看了三遍 6 个 Skill 的 SKILL.md 之后，把这次的「升级」重新理解了一遍：v6.4.4 表面上是 React 组件库升大版本，**底层是在给 AI Agent 写一套完整的项目级 SOP**。

## 一、先说数据：v6.4.4 这次到底改了什么

先摆可查证的数据，全部来自 GitHub API 实时查询（北京时间 2026-06-22）：

| 项目 | 数据 |
|------|------|
| 最新稳定版 | **v6.4.4**（2026-06-12 发布） |
| 6.x 第一个大版本 | v6.4.0（2026-05-14 发布） |
| Stars | 98,422 |
| Forks | 54,623 |
| Watchers | 255 |
| 默认分支 | master |
| 协议 | MIT |
| 主语言 | TypeScript |
| 归档状态 | **未归档**（重要——很多公司项目用 antd，必须确认） |
| 开放 issues | 1,333 |
| React 兼容性 | `react >= 18.0.0`（不锁 React 19，向下兼容 18） |

v6 之后涉及 React 19 的 PR 有 42 个——说明 v6 时代已经在为 React 19 准备。但我今天不展开讲 React 19，而是讲 v6 真正升级的部分：**给 Agent 用的工程资产**。

## 二、被我盯上的两个文件：AGENTS.md 和 CLAUDE.md

打开 antd 仓库根目录，你会看到两个非常显眼的文件：

- `AGENTS.md`（4.7KB）
- `CLAUDE.md`（283 行 / 约 11KB）

**注意一个彩蛋**：`AGENTS.md` 在 master 分支**不是独立文件**，是个软链接——

```bash
$ ls -la AGENTS.md
lrwxrwxrwx  AGENTS.md -> CLAUDE.md
```

也就是说，**AGENTS.md 实际指向 CLAUDE.md**。这是 antd 团队对当前 Agent 生态命名混乱的一种折中：Claude Code 看 `CLAUDE.md`，其他通用 Agent 框架看 `AGENTS.md`，内容完全一致。

`CLAUDE.md` 顶端第一行就写明身份：

> 本文件为 AI 编程助手提供项目上下文和开发规范。

我把它通读了三遍，按章节归类大致 4 大块：

| 章节 | 内容 | 行数占比 |
|------|------|----------|
| 项目信息 | antd 是 84+ 组件的 React 库，CSS-in-JS，支持 Design Token / 暗色 / RTL / SSR / 150+ 语言 | 约 15% |
| 通用编码规范 | 数据类型判断用 `components/_util/is.ts` 的现成方法 | 约 10% |
| 文档 / Demo / Test / PR / Changelog 规范 | 5 大类**显式编码规则** | 约 50% |
| 编码行为准则 | 「不要假设、不要隐藏困惑、呈现权衡」「简洁优先」「精准改动」「目标驱动执行」4 条 | 约 25% |

最后那个「编码行为准则」章节，是我觉得最有价值的一块——后面单独说。

## 三、`.agents/skills/`：6 个 Skill 撑起 antd 仓库级 Agent 工作流

antd 仓库根目录下有三个看似重复的目录：

```
.claude/      → 软链接到 skills
.cursor/      → 软链接到 skills
.agents/skills/  ← 实际真目录
```

`.agents/skills/` 里**有 6 个 Skill**，每个都是 SKILL.md 单文件结构：

| Skill | 行数 | 文件大小 | 一句话职责 |
|-------|------|---------|-----------|
| `changelog-collect` | **490** | 15.4 KB | 收集两个版本之间的 PR、整理 changelog 草稿 |
| `create-pr` | **346** | 10.7 KB | 按仓库模板创建 PR，标题英文 / 内容按用户语言 |
| `issue-reply` | **291** | 10.0 KB | 帮维护者回复 issue，区分 Bug / Feature Request、用好 label |
| `version-release` | **206** | 6.6 KB | 版本发布流程 |
| `commit-msg` | **188** | 5.8 KB | 规范化 commit message |
| `test-review` | **181** | 5.3 KB | 测试代码 review |

**6 个 SKILL.md 加起来 52.6 KB，1,702 行**。

### 3.1 重点看 changelog-collect：490 行写了什么

这是 6 个里最长的一个，我读完之后理解了 antd 团队的 changelog 流水线：

- **阶段一**：用 `gh CLI` 收集两个版本/分支之间的 PR
- **阶段二**：按 emoji 分类（🐞 / 💄 / 🆕 / 🔥 / ⌨️ / 🗑 / 🛠 等 13 类）
- **阶段三**：处理「用户无感知的改动」（内部重构、纯测试更新、工具链优化直接过滤）
- **阶段四**：同步更新 `CHANGELOG.zh-CN.md` 和 `CHANGELOG.en-US.md` 两份文件
- **阶段五**：每条加贡献者链接

注意 changelog 句式有硬性约定（来自 CLAUDE.md）：

| 语言 | 格式 | 示例 |
|------|------|------|
| 中文 | `Emoji 动词 组件名 描述` | `🐞 修复 Button 在暗色主题下 \`color\` 的问题。` |
| 英文 | `Emoji 动词 组件名 描述` | `🐞 Fix Button reversed \`hover\` colors in dark theme.` |

**动词在前**，组件名必含（不加反引号），属性名加反引号，中英文之间留一个空格。

这套规范不是给人类记的，是**给 AI Agent 写的**——让 Agent 帮你整理 changelog 时有据可依。

### 3.2 create-pr 里的一个细节：「先确认再创建」

`create-pr/SKILL.md` 第 18 行明确写道：

> 真正执行 `gh pr create` 之前，必须先把 `base`、`title`、`body` 给用户确认，确认后才能创建 PR。

这条规则我反复看了两遍——它解决的是**「AI 直接 push 改动」这个 Agent 时代最危险的操作**。antd 这种 98k Star 的项目，AI 误创建 PR 是灾难级的，所以把「先确认」写进 Skill 的硬约束里。

Skill 文档还提到 PR 标题必须英文、PR body 按用户语言选模板（中英两套），以及 7 类 PR 改动类型（🆕 / 🐞 / 📝 / 📽️ / 💄 / 🤖 / 📦 / ⚡️ / 🌐）的 emoji 映射。

### 3.3 issue-reply：开篇第一句定调

`issue-reply/SKILL.md` 开头第一句非常有意思：

> 开源项目的用户和维护者之间并不是甲方和乙方的关系，issue 也不是客服。处理 issue 时抱着『一起合作来解决问题』的心态。

下面紧跟硬规则：仅对**状态为 open + 没有人维护者回复过**的 issue 做首次回复。这条规则我自己在社区也用——AI 不会去碰已经有人接的 issue，避免重复打扰维护者。

Skill 还内置了对 `dosubot` 自动回复的处理逻辑（GitHub 官方机器人），以及 label 分类建议。

### 3.4 其他 3 个 Skill 一句话带过

- `version-release`：版本发布轮值机制，引用了 antd 内部的 wiki 流程文档
- `commit-msg`：commit message 规范（Angular Convention），含 emoji 前缀
- `test-review`：测试代码 review 清单，覆盖覆盖率、断言质量、边界场景

**踩坑发现**：6 个 Skill **只用了 SKILL.md 单文件结构**，没有用 `references/`、`scripts/`、`assets/` 这种多文件子目录组织。`create-pr` 里引用的 `.github/PULL_REQUEST_TEMPLATE_CN.md` 模板也只是远程引用，不在 Skill 包内打包。

## 四、最让我意外的一节：「编码行为准则」

`CLAUDE.md` 最后一节，**283 行里压轴的 4 条核心原则**：

### 1. 先思考再编码

> 「不要假设。不要隐藏困惑。呈现权衡。」

实现之前必须明确陈述假设；存在多种理解时逐一列出；不明白的地方**停下来指出困惑再提问**。

### 2. 简洁优先

> 「用最少的代码解决问题。不做臆测性编码。」

- 不实现超出需求的特性
- 不为仅使用一次的代码做抽象
- 不添加未经要求的「灵活性」
- 如果你写了 200 行但 50 行就够了，那就重写

> 问问自己：「资深工程师会觉得这过于复杂吗？」如果是，就简化。

### 3. 精准改动

> 「只改必须改的。只清理自己制造的遗留。」

- 不要「改善」相邻的代码、注释或格式
- 不要重构没有问题的代码
- 即使你习惯不同写法，也要与现有风格保持一致

> 检验标准：「每一行改动都应该能追溯到用户的请求。」

### 4. 目标驱动执行

> 「定义成功标准。循环验证直到通过。」

- 「添加校验」→ 为无效输入编写测试，然后使其通过
- 「修复 Bug」→ 编写复现测试，然后使其通过
- 「重构 X」→ 确保重构前后测试都通过

对于多步骤任务，简要列出计划：

```
1. [步骤] → 验证：[检查方式]
2. [步骤] → 验证：[检查方式]
```

**这 4 条不是 antd 原创**，是面向 LLM 编码的通用准则。但 antd 是**第一个把这套准则写进自己仓库 CLAUDE.md 的顶级 React 库**——而这套准则恰恰是 2025-2026 Agent 编码圈最被低估的规范。

我之前跟很多人聊过，为什么同样用 Claude Code 写代码，有人能稳定输出 production-grade 代码，有人输出的代码 review 一遍要重写 80%——差距不在 prompt，而在**有没有这套「给 AI 立规矩」的项目资产**。

## 五、这意味着什么：开源项目的「第 85 个工程资产」

我之前把 antd 仓库的工程资产粗略分过类：

| 资产类型 | 数量级 | 例子 |
|---------|--------|------|
| 组件代码 | 84+ 组件 | `components/button/` |
| 主题系统 | 1 套 | `components/theme/` |
| 国际化文案 | 150+ 语言 | `components/locale/` |
| 测试套件 | 几千个 case | `**/__tests__/` |
| 文档站 | 几百个 md | `docs/` |
| **给 AI Agent 的资产** | **6 + 1 + 1 = 8 份** | **`.agents/skills/` + `AGENTS.md` + `CLAUDE.md`** |

**6 + 1 + 1** 是这次最值得记录的 antd 工程资产清单：

- **6 个 Skill**：changelog-collect / commit-msg / create-pr / issue-reply / test-review / version-release
- **1 份 AGENTS.md**（软链到 CLAUDE.md）
- **1 份 CLAUDE.md**（283 行项目级规范）

我之前帮几个团队做技术咨询时反复提一件事：**Agent Skill 应该是仓库的一等公民，而不是藏在某个 PR description 或者团队 Wiki 里的草稿**。antd 用 v6 这个时间点，把这件事示范了出来。

## 六、踩坑记录：我从这次研究里学到的 3 件事

### 踩坑 1：AGENTS.md 不一定独立存在

我第一次 `cat AGENTS.md` 出来的是 4.7KB 的 CLAUDE.md 内容，本以为 antd 写了两份；用 `ls -la` 才发现是软链。**写文章 / 写工具前，先看文件类型**，软链 / 硬链 / 独立文件三种情况对 Agent 行为的影响完全不同。

### 踩坑 2：Skill 不是越多越好

我数了一下，6 个 Skill 都在 antd 仓库的**真实发布流程**里被用上——changelog-collect 用于每次发版，issue-reply 用于日常 triage，create-pr 用于每个 PR。**Skill 数量与价值不是线性关系**，是阶跃关系；6 个但每个都用得上，比 30 个但 25 个是死代码好得多。

### 踩坑 3：CLAUDE.md 一定要有可执行的硬规则

我之前看很多项目 CLAUDE.md 写得「端正但空」（比如「请遵循最佳实践」「保持代码简洁」），这种文档对 Agent 几乎没用——Agent 不知道什么叫「最佳实践」。

antd 的写法值得抄：

- ❌ 软规则：「请写好 commit message」
- ✅ 硬规则：「commit message 必须用 Angular Convention + emoji 前缀，参考 `.agents/skills/commit-msg/SKILL.md`」

**能引用的就引用，能给链接的就给链接**。这是 CLAUDE.md 从「摆设」变成「约束」的关键。

## 七、我的选型建议

如果你也在维护一个开源项目，或者在企业内部做「AI 编码资产化」的事，这次 antd v6 的实践给你 3 条直接可抄的建议：

| 你在做的事 | 建议照 antd 抄什么 |
|-----------|------------------|
| 第一次给项目加 Agent 资产 | 优先写 `CLAUDE.md`（一份就够），不要同时铺开 5 个 Skill |
| 项目有 1k+ Stars 或 100+ 贡献者 | 至少加 3 个 Skill：`create-pr` / `commit-msg` / `issue-reply`（按使用频率排） |
| 团队希望 AI 写出的代码 review 率 ≤ 30% | 把「编码行为准则」4 条抄进 CLAUDE.md 末节 |
| 跨 Agent 工具兼容（Claude Code / Cursor / 通用 Agent） | 用 `.agents/skills/` 真目录 + `.claude/`、`.cursor/` 软链，三处全打通 |

最后一条：v6.4.4 当前还在快速迭代（v6.4.3 → v6.4.4 间隔 25 天），4 周内大概率还有 v6.4.5、v6.5.0。建议**现在就 git pull 一份 antd master 看看这 8 份资产**，比下次升级时临时翻文档强。

---

## 写在最后

antd v6.4.4 表面是 React 组件库升大版本，**底层是把 Agent Skill 做成了和 84 个组件并列的一等公民**——6 个 SKILL.md 加 1 份 AGENTS.md 加 1 份 CLAUDE.md，1,702 行字。

这套资产不会帮你多写一个 Button 组件，但会**让 AI 帮你写 Button 组件时少踩 80% 的坑**。这就是 v6 真正的护城河。

**你团队有没有给项目配 CLAUDE.md 或 Agent Skill？配了几个？评论区聊聊。**

摘要

标签多个标签用逗号分隔

分类