企业官网建设流程全解析

• 前端
• 开发工具

导读

antd-admin 是一个面向 AI 辅助开发的「AI-friendly enterprise front-end best practices」仓库，它通过.cursor/rules/目录下的规则文件约束 AI Agent 与人类开发者的编码行为。其中 english-only-comments.md 是唯一一条alwaysApply: true的全局规则：所有源码注释必须使用英文。本文以该规则文件为骨架，结合仓库内真实源码与同目录其他规则文件，完整讲解这条规范的适用范围、写法示例、底层机制（frontmatter 字段、globs、alwaysApply）以及它在项目中的实际落地形态，帮助你在自己的前端工程里复刻一套「AI 可读、人机一致」的注释治理方案。

一、规则文件的位置与身份

这条规范位于仓库根目录的.cursor/rules/english-only-comments.md。.cursor/rules/是 Cursor 编辑器（及同类 Agent 工具链）约定俗成的规则目录，antd-admin 在仓库中维护了多个规则文件：

其中英文注释规则之所以特殊，在于它的alwaysApply: true—— 这意味着规则不依赖文件路径匹配，任何一次代码编辑都会被自动附加上这条约束，是项目注释风格的「宪法级」底线。

二、规则文件的完整结构与 frontmatter

原文件全文结构如下（正文仅 18 行，但语义密度很高）：

--- description: All code comments must be written in English alwaysApply: true --- # English-only comments - Write **all** new and updated comments in **English**: `//`, `/* */`, `///`, JSDoc, inline `<!-- -->` in templates, and similar. - **Do not** add or keep Chinese (or other non-English) text in comments when editing files. - User-facing copy (UI strings, i18n keys, docs meant for end users) is **not** covered by this rule—only **source comments**.

frontmatter 字段语义

• description：一句话描述规则意图（All code comments must be written in English），在 Agent 工具链中用于规则检索与匹配，写作时应保持简短、动词开头、可被语义搜索命中。
• alwaysApply: true：声明该规则无条件生效。与之对比，同目录的with-lingui-*.mdc规则使用globs字段限定匹配文件（如apps/with-lingui/src/api/**/*.ts），且alwaysApply: false，只有编辑匹配文件时才加载。从源码结构可以推断，antd-admin 有意把「注释语言」这种跨模块的通用约束与「业务模块专属约束」分层管理：全局规则放通用底线，模块规则放具体操作清单。

三、规则的三条核心条款

3.1 所有新增与更新的注释必须用英文

规则覆盖了常见注释语法形态的全部类型：

• 行注释//
• 块注释/* */
• 文档注释///
• JSDoc（如/** ... */）
• 模板内联注释<!-- -->（如 JSX / HTML）

值得强调的是「new and updated」——它同时约束新写的注释和修改既有代码时触碰到的注释。也就是说，哪怕只是顺路改一行代码，也不允许把附近的注释顺手改写成中文。

3.2 不得添加或保留非英语注释

条款二（Do not add or keep Chinese (or other non-English) text in comments）比条款一更严格：不仅禁止新引入，也禁止在编辑文件时保留历史遗留的非英文注释。这意味着这是一条「净化式」规则——如果你接手一个混有中文注释的文件，按此规则应在编辑时一并清理为英文。

3.3 边界：用户可见文案不受约束

条款三划定了规则的适用范围边界：

• 受约束：源码注释（source comments）
• 不受约束：UI 字符串、i18n 键值、面向终端用户的文档

这条边界非常关键。antd-admin 是一个多语言意识很强的项目——仓库同时维护apps/basic（单语言）与apps/with-lingui（集成 Lingui 国际化，含 locales/en/messages.po 与 locales/zh/messages.po）两套模板。UI 文案（如用户可见的「No data」「登录」）本就需要按语言环境呈现，显然不能强行英文化；规则只对「开发者读的注释」提出语言要求，避免了与国际化设计冲突。

四、规则附带的代码示例解读

4.1 TypeScript 注释示例

// BAD — non-English comment // Initialiser le cache (example: any non-English language) // GOOD // Initialize the cache from the last session snapshot.

反例刻意选用法语来强调「任何非英语语言都不行」，而不仅仅是中文。正例则展示了一个高质量英文注释应该有的样子：主语（the cache）+ 动作（initialize）+ 来源（from the last session snapshot），信息完整、无需读者猜上下文。

4.2 TSX / JSX 模板注释示例

// BAD {/* Chargement… */} // GOOD {/* Loading spinner */}

这个示例补充了 JSX 内联注释场景：反例是法语「加载中…」且带有省略号，正例「Loading spinner」更精确——它告诉读者这个位置渲染的是「加载中的 spinner 组件」，而不是模糊的状态描述。这也暗示了英文注释的最佳实践：描述组件/逻辑是什么，而非翻译界面文案。

五、仓库源码中的真实落地证据

英文注释规范并非纸上谈兵，antd-admin 的核心源码是高度一致的英文注释样板，可以直接作为团队的「注释风格范文」：

5.1 JSDoc 描述组件职责

DataTableEmpty.tsx 用一行 JSDoc 概括组件定位：

/** * Table empty state: icon in soft tile + bold title + secondary description (dashboard-style). */ export function DataTableEmpty(): ReactElement { ... }

5.2 JSDoc 描述共享 Token 构建器

tokenBuilders.ts 对工具函数的职责、目的都做了英文注释，例如：

/** * Common theme token builders * Reduces duplication between light and dark theme definitions */

以及 buildTableTokens 的「Calculate table row selected color based on theme algorithm」，用动词开头的祈使句描述函数行为。

5.3 用注释解释「为什么这么做」

英文注释尤其适合承载决策理由（rationale）。useResourceCRUD.ts 中：

/** @deprecated Prefer `ResourceCRUDResult` — alias kept for plan wording compatibility */ export type CrudResult<...> = ResourceCRUDResult<...>;

这条@deprecatedJSDoc 解释了类型别名保留的原因（为兼容方案文档措辞），而 createHandler.ts 中的注释则解释了实现意图：

/** Parse `data` with Zod before wrapping — catches mock ↔ contract drift early. */

这些注释都在回答「为什么这样写」，这正是英文注释规范想推动的注释质量方向——不是翻译代码，而是补充代码之外的信息。

六、这条规则在项目中的角色与机制

6.1 与模块级规则的分工

从前文规则表可以看到，antd-admin 的规则体系是「一条全局底线 + 若干模块细则」：

• 全局层：english-only-comments.md（alwaysApply: true）约束一切编辑的注释语言；
• 模块层：with-lingui-*.mdc规则通过globs绑定具体目录，且采用「薄规则」设计——正文只指向.github/instructions/下的唯一细则来源（如apps/with-lingui/.github/instructions/api.instructions.md），避免在规则文件里重复维护长文档。

从源码结构看，apps/basic/AGENTS.md 也印证了这套分层：仓库使用 scoped AI instruction files（frontend.instructions.md、testing.instructions.md、api.instructions.md、refactor.instructions.md）分别约束 UI、测试、API 与重构工作。语言规范属于跨切面（cross-cutting）关注点，因此放在全局规则而非模块细则里，任何 Agent 在处理任何文件时都会被注入。

6.2 对 AI Agent 与 LLM 的实际意义

antd-admin 自我定位为「AI-friendly」工程，英文注释是其中关键一环：

• 注释可被检索：统一的英文注释让代码语义可以被自然语言搜索、被 LLM 在补全和重构时稳定理解；
• 减少语言混杂噪音：中英混杂注释会干扰 token 上下文与检索质量，统一语言降低了 Agent 误读概率；
• 边界清晰：明确「注释必须英文、UI 文案可多语言」的界限，避免 Agent 在 i18n 文件里错误地「英文化」用户可见文案，破坏 Lingui 的语言包机制。

七、在自己的工程中落地这套规范

参考 antd-admin 的做法，落地英文注释规范只需四步：

1. 建立规则文件：在仓库根目录创建.cursor/rules/english-only-comments.md，frontmatter 写入description与alwaysApply: true；
2. 明确边界条款：务必保留「User-facing copy 不受约束」的边界说明，避免与 i18n 体系冲突；
3. 提供正反例：像原文件一样分别给出 TS 与 TSX 的 BAD/GOOD 对照，让规则可被机械执行；
4. 用 CI / 代码评审兜底：规则文件约束的是 AI 助手与编辑器行为，仍建议配合代码评审对历史遗留的非英文注释做渐进式清理。

八、小结

english-only-comments.md 以 18 行正文定义了一条高杠杆的工程规范：注释语言统一、边界明确、示例具体，并通过alwaysApply: true保证全局生效。它既约束人类开发者，也约束接入仓库的 AI Agent，与with-lingui-*.mdc模块规则、.github/instructions/细则文件共同构成 antd-admin 的「AI 友好」协作底座。仓库内 tokenBuilders.ts、useResourceCRUD.ts、createHandler.ts、DataTableEmpty.tsx 等文件的英文注释，即为这套规范最直观的范本。

• 前端
• 开发工具