wbroom

如何使用 Cursor 项目规则：.cursor/rules、规则类型与第一条 Agent 约束

在 .cursor/rules 用 .mdc 约束 Agent 改动范围，让 diff 更贴近团队习惯。

用 Cursor Agent 改一个组件，它顺手把无关文件的缩进、import 顺序也「统一」了，Review 时 diff 噪音比功能还多。项目规则（Project Rules）写在仓库里的 .cursor/rules/，用带 YAML 前言的 .mdc 文件告诉 Agent：哪些目录能改、测试怎么跑、什么风格算合格。官方说明见 Cursor 文档中的 Rules / Project rules。

搜索 Cursor 项目规则 .cursor/rules 规则类型 Agent 编辑 的人，通常要完成：弄清规则类型（始终应用 / 按文件 / 按需）、在仓库里加第一条可验证的规则，并让下一次 Agent 改动更贴近团队习惯。以下步骤以 Cursor 文档为准，不依赖第三方插件。

建 .cursor/rules写第一条 .mdc用 Agent 小任务验证

适合谁

01

多人共用一个 monorepo

前端、后端、脚本目录并存，希望 Agent 不要动 backend/public 或生成物。

02

已有 lint/format 但 Agent 仍「自创风格」

ESLint/Prettier 管保存时格式，Agent 批量改文件时仍需要文字层面的约束（测试命令、最小 diff 原则）。

03

刚把 Copilot 换成 Cursor Agent

把 README 里口头约定落成可版本化的规则，新人 clone 即生效。

规则放在哪、长什么样

项目级规则目录为 .cursor/rules/，每个规则一个 .mdc 文件：顶部 YAML frontmatter + Markdown 正文。可提交到 Git，与 AGENTS.md 等文档互补 — 本指南以 .cursor/rules 为主。

类型（界面常见名称）frontmatter 要点何时生效
Always Apply / 始终应用alwaysApply: true每次 Agent / Chat 会话都会带上
Apply to Specific Filesglobs: **/*.vue 等编辑或讨论匹配路径时
Apply Intelligently / Agent 按需description: 写清用途模型根据描述判断是否引用
Apply Manually无 always、无 globs在规则列表里手动 @ 或启用

写第一条项目规则（推荐：最小 diff）

  1. 1

    创建目录

    在仓库根执行 mkdir -p .cursor/rules。若已有该目录，先 git status 看清现有规则，避免重复主题。

  2. 2

    新建 .mdc 文件

    例如 .cursor/rules/agent-minimal-diff.mdc。frontmatter 里 alwaysApply: true 适合「全仓库通用、且很短」的约束；若规则只针对 Vue 组件，改用 globs: frontend-app/**/*.vue 并设 alwaysApply: false。

  3. 3

    正文写可执行句子

    用 bullet 写清：只改任务相关文件、改前先说明计划、跑哪条测试命令（如 npm run test -- --run）、禁止改哪些路径。单条规则宜控制在几十行内，一条规则一个主题。

  4. 4

    提交并开 PR

    git add .cursor/rules 与团队一起 review — 规则与代码一样会长期影响 Agent 行为。

  5. 5

    用 Agent 做验收

    在 Cursor 打开该仓库，给 Agent 一个小任务（例如「只给 X 组件加 loading 态」），看 diff 是否仍越界修改；若否，收紧 globs 或补充禁止路径。

---
description: Keep Agent edits scoped and minimal
alwaysApply: true
---

# Agent edit scope

- Change only files required for the user request.
- Do not reformat unrelated files or reorder imports repo-wide.
- Before editing, list planned files in the chat.
- After edits, run `npm run test -- --run` when tests exist.
- Never edit `backend/public/` or lockfiles unless asked.

和 User Rules、Skills 怎么分工

User Rules（用户规则）
存在 Cursor 账号/应用设置里，跨项目生效 — 适合个人偏好，不适合写死本仓库路径。
Project Rules（.cursor/rules）
跟仓库走，CI/同事 clone 后一致 — 适合 monorepo 路径、测试命令、发布流程。
Skills / 文档
长流程或外部工具步骤可放 skill；日常编码约束仍优先短规则，避免一次塞入整本手册。

规则不是越多越好：两条清晰的 alwaysApply + 若干按 glob 的专项规则，通常比一篇超长 README 更能让 Agent 稳定。

和队友对齐规则时，可在 wbroom 首页 开浏览器房间共享屏幕 — 见 创建与加入房间。终端/Git 习惯可参考本站 lazygit 指南 与 Zed 上手。

还想核对的问题

规则不生效怎么办？

确认用 Cursor 打开的是仓库根目录、.mdc 在 .cursor/rules/ 且 frontmatter 合法。在 Settings → Rules 查看项目规则是否列出；改完后重开 workspace 或新开 Agent 会话再试。

alwaysApply 和 globs 能同时用吗？

以文档为准：通常 alwaysApply: true 表示全局；文件专项规则用 globs 且保持正文简短。避免同一主题写两份重复规则。

可以用 .md 而不是 .mdc 吗？

项目规则标准格式是带 frontmatter 的 .mdc。旧版 .cursorrules 若仍存在，建议迁移到 .cursor/rules 以便分文件管理。

规则里能写密钥吗？

不要。只写命令名与路径模式；API 密钥继续用环境变量或密钥管理器，且勿提交 .env。

开始一场会议