前端开发工具【免费下载链接】antd-adminAI-friendly enterprise front-end best practices项目地址https://gitcode.com/gh_mirrors/an/antd-admin点击查看免费下载导读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覆盖范围english-only-comments.mdtrue全局所有被编辑的文件with-lingui-add-resource.mdcfalseapps/with-lingui下 API / mocks / routes / e2e 文件with-lingui-api.mdcfalseapps/with-lingui/src/api、utils/http.ts、mocks 相关文件with-lingui-frontend.mdcfalseapps/with-lingui/src/**/*.{ts,tsx,css}with-lingui-refactor.mdc、with-lingui-testing.mdcfalse对应重构与测试场景其中英文注释规则之所以特殊在于它的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.mdalwaysApply: true约束一切编辑的注释语言模块层with-lingui-*.mdc规则通过globs绑定具体目录且采用「薄规则」设计——正文只指向.github/instructions/下的唯一细则来源如apps/with-lingui/.github/instructions/api.instructions.md避免在规则文件里重复维护长文档。从源码结构看apps/basic/AGENTS.md 也印证了这套分层仓库使用 scoped AI instruction filesfrontend.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 的做法落地英文注释规范只需四步建立规则文件在仓库根目录创建.cursor/rules/english-only-comments.mdfrontmatter 写入description与alwaysApply: true明确边界条款务必保留「User-facing copy 不受约束」的边界说明避免与 i18n 体系冲突提供正反例像原文件一样分别给出 TS 与 TSX 的 BAD/GOOD 对照让规则可被机械执行用 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 等文件的英文注释即为这套规范最直观的范本。赞分享前端开发工具【免费下载链接】antd-adminAI-friendly enterprise front-end best practices项目地址https://gitcode.com/gh_mirrors/an/antd-admin点击查看免费下载相关推荐ESLint no-warning-comments 规则详解用注释规范拦截 TODO、FIXME 与 XXXESLint no warning comments 规则详解用注释规范拦截 TODO、FIXME 与 XXX 本篇技术指南以 ESLint 内置规则 no开发工具Lint静态分析代码质量NES.css代码规范注释规范NES.css代码规范注释规范 在NES.css项目中注释规范是保证代码可读性和可维护性的重要组成部分。良好的注释能够帮助开发者快速理解代码功能、设计思路和前端UI组件ESLint 注释大小写规范指南深入解析 capitalized-comments 规则ESLint 注释大小写规范指南深入解析 capitalized comments 规则 注释是开发者之间传递信息的重要载体而注释首字母是否大写、是否遵循统开发工具Lint静态分析代码质量上一篇ReActor AI换脸技术终极指南3分钟快速部署与实战技巧下一篇YOLOv8 Aimbot深度解析AI瞄准革命与FPS游戏实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考