Cursor
一次看似普通的样式修复，曾把一个前端项目的配置目录、生成产物和测试快照一起交给了代理。代理很快给出“可用”的页面，却顺手改写了锁文件、删掉了两条边界测试，并把本地 .env 的变量名放进了聊天上下文。CI 没有立即失败，因为缓存命中了旧产物；直到另一位开发者拉取分支，才发现问题并不在 CSS，而在一次没有被限制的上下文选择、命令执行和补丁接收。
Cursor 的价值不在于让编辑器多一个对话框，而在于把补全、检索、聊天、文件修改和终端动作放进同一条开发链路。也正因为它靠近工作区，错误的索引、含混的规则或过宽的终端权限会把一个局部请求放大成仓库级变更。下面的做法把代理当作可以产出候选补丁的协作者：它可以搜索、建议和执行受控命令，但每一个写入、测试结论和合并决定都必须能回到文件差异与可重复命令。
先让安装结果可验证
从 Cursor 下载页 选择与操作系统和 CPU 架构匹配的桌面安装包。官方桌面应用覆盖 macOS、Windows 与 Linux；桌面程序与 Cursor Agent CLI 是两个入口，不能因为桌面应用已经安装就假定终端里一定存在 cursor 或 cursor-agent。企业网络、代理或终端防护软件可能拦截安装器或扩展下载，因此不要把“安装窗口已经出现”当成成功信号。打开应用后，用命令面板运行 Cursor: Start Onboarding 可以重新完成快捷键、主题和终端偏好的初始化；这是官方安装文档给出的回到引导流程的入口。
先在一个没有业务数据的练习仓库中确认编辑器、Shell 与 Git 都指向预期对象。Windows 用户尤其要检查系统级安装与用户级安装没有同时留下两个版本；Linux 用户要确认发行版包、AppImage 或团队软件仓库只保留一种权威来源。多个可执行文件并存时，终端里看到的 cursor 可能不是你刚打开的桌面程序。
# 在练习仓库根目录执行；每项都应指向同一个实验工作区
cursor --version
git rev-parse --show-toplevel
git status --short
Get-Command cursor -All | Select-Object Source, Version预期证据是版本命令能返回、Git 根目录是当前练习仓库、状态为空或只有你明知的实验文件。若 cursor 找不到，不要通过复制未知目录到 PATH 解决；回到 Cursor 的安装与 Shell Command 设置，或者从安装器修复。若 git rev-parse 给出错误，先打开正确文件夹再启动 Agent，避免代理把上一级目录误认为工作区。
首次登录使用个人账号还是团队受管账号，会直接影响可用模型、团队策略和账单归属。登录前先向管理员确认座席已经分配、允许的身份提供方、是否强制隐私模式，以及成员离开团队时的回收路径。不要共享浏览器会话、编辑器配置目录或团队账号；共享账号会让补丁、用量和审查记录失去归属。
首次打开外部仓库时，还要把“信任仓库内容”和“信任编辑器扩展”拆成两次判断。不要因为 Cursor 基于 VS Code 就推断当前客户端必然启用了 Workspace Trust；先在团队批准的客户端镜像中检查 security.workspace.trust.enabled，需要这一层保护时将它显式设为 true。随后先以 Restricted Mode 阅读 .vscode/settings.json、任务、调试配置、包管理脚本和工作区推荐扩展，再决定是否授予信任。即使启用了 Workspace Trust，它也主要限制恶意文件夹触发的执行，不能阻止恶意扩展绕过限制。
{
"security.workspace.trust.enabled": true
}扩展是与编辑器进程同等级的供应链入口。Cursor 的 安全说明 还提示，其扩展市场下载链路不能照搬 VS Code 的签名验证假设。团队不要把个人 VS Code 配置和全部扩展一键导入受管开发机；应维护允许的 publisher、扩展 ID、批准版本和用途，检查扩展是否会启动语言服务器、执行工作区二进制、读取终端或访问网络。正向检查是在无业务数据的仓库中只安装批准清单里的扩展，并确认 Restricted Mode 下 Agent、任务和终端没有被意外放开；反向检查是打开带有陌生推荐扩展和任务配置的仓库，预期保持受限、拒绝安装并由管理员复核。仅看到扩展名称、下载量或“兼容 VS Code”都不能作为信任证据。
用一条小事故建立代理工作节奏
代理最容易越界的时刻，往往不是面对复杂重构，而是面对一句“顺便把相关问题都修掉”。把请求拆成观察、候选补丁、验证三个可见阶段，能让对话历史和 Git 差异保持对应。先要求只读分析，再让它针对一个文件组提出改动，最后由开发者批准测试命令并检查差异。
在 Chat 或 Agent 中，文件、文件夹、代码符号、Git 变更和文档都可以作为上下文被引用。官方的 上下文引用说明 列出了 @Files、@Folders、@Code、@Git、@Docs 与 lint 错误等入口。它们不是“资料越多越好”的开关：上下文越大，模型越可能抓住无关旧实现，成本与泄露面也随之增加。
一个安全的提示可以写成下面这样。它把操作对象、禁止动作和成功证据说清楚，但仍由开发者选择命令与补丁是否接受。
先只分析 src/auth/session.ts 与 tests/session.test.ts，不写文件也不执行命令。
说明现有刷新逻辑为何会重复发送请求，并给出最小修复方案。
修改时不要触碰依赖清单、锁文件、环境变量文件和发布配置。
完成后列出需要由我批准运行的测试命令，以及每个命令证明什么。随后再明确交付单位：只修改指定实现和同一行为的测试；不要把“优化”理解为格式化全仓、升级依赖或删除未理解的断言。若代理提议扩大影响面，先回到只读阶段，用 @Git 检查最近相关提交，或者让它解释每个新增文件为何必要。Chat 的回答不是代码审查结论；它只是形成假设和补丁的接口。
索引先排除秘密与噪声
Cursor 的代码库索引用于让模型在仓库内找到相关代码。官方隐私说明指出，索引会将代码分块上传以计算嵌入，服务端保留嵌入以及哈希、混淆路径等元数据，明文代码不作为持久索引保存；查询命中后，客户端仍会读取对应代码片段并将其用于请求。这不等于任何文件都适合进入索引。密钥、导出的客户数据、抓包、构建产物、二进制大文件和本地缓存既会污染检索，也会制造不必要的数据暴露。
把忽略规则作为仓库配置审查，而不是个人编辑器偏好。Cursor 官方将 .cursorignore 描述为阻止文件被发送和进入 AI 请求的尽力保护，并同时使用 .gitignore 过滤索引；因此它是减少暴露面的工程控制，不是访问控制或保密承诺。.gitignore 服务于版本控制，.cursorignore 服务于 AI 上下文，两者常有重合却不能互相替代：某些可提交但不应给模型的安全说明、脱敏样本或大体积报告，应单独写入 .cursorignore，真正的秘密仍应从工作区移走并由文件权限或秘密管理器控制。
# .cursorignore：只保留可由团队公开审查的上下文
.env
.env.*
!.env.example
**/*secret*
**/*credential*
**/*.pem
**/*.key
data/export/
tmp/
coverage/
dist/
node_modules/
*.sqlite
*.pcap这份规则故意保留 .env.example，前提是它只含变量名和无效示例值。不要用 *.env 这样的通配符误伤团队需要审查的模板，也不要因为文件已被 Git 忽略就假设它不存在于聊天上下文。修改后关闭并重新打开相关工作区，尝试在 Chat 中用 @ 搜索一条应排除的文件名；预期结果是它不会出现在可选上下文中。若仍可选，停止继续投喂文件，检查规则位置、拼写和是否打开了另一个目录层级。
索引失败也有价值。大仓库初次索引很慢时，不要把整个 monorepo 反复切换为完整文件夹内容。先排除构建目录与 vendored 依赖，再按当前服务目录添加 @Folders，让代理在需要时读取具体文件。官方文件夹说明还提示“完整文件夹内容”会显著增加输入 token；对长上下文模型，这既是费用信号，也是审查难度信号。
索引“完成”也不保证上下文正确。重命名后的旧文件、未保存的编辑器缓冲、分支切换留下的生成物、重复的接口定义和过期快照，都可能让模型把相似代码当作权威实现。发生这种现象时，回答通常带有可识别的症状：代理引用了已删除的函数名，建议修改与当前测试无关的目录，或者解释的调用链与 git grep 找到的实现不一致。不要用更大的文件夹引用压住这个错误；先把问题缩到一个符号和一条失败测试，要求它给出引用文件与行号，再用本地搜索核对。
# 用本地证据校验代理声称的符号与调用位置
rg -n "refreshSession|authorizeRequest" src tests
git status --short
git diff --name-only
# 分支切换或生成行为后，确认没有残留旧产物干扰当前任务
git clean -fdn预期是搜索结果与代理解释中的文件一致，工作树只包含当前任务允许的变更。若 rg 找不到代理提到的符号，或者 git diff --name-only 出现无关目录，先终止该轮会话并开启一个只带目标文件的新会话。需要向团队报告时，记录使用的脱敏提示、允许的文件列表、错误引用和本地搜索结果即可；不要转发含有源码、密钥或完整聊天内容的截图。这样留下的失败证据既能帮助修正规则，也不会把一次排障变成新的数据暴露。
把规则写进仓库，而不是聊天记忆
重复强调“不要修改锁文件”“测试必须先跑”会耗尽对话，也无法被评审。Cursor 的 Rules 文档 将 Project Rules 放在 .cursor/rules，以 MDC 文件保存并纳入版本控制；它们可按 glob 自动附着、由 Agent 自行请求，或手动引用。旧的 .cursorrules 仍可识别，但官方已标为遗留形式，新的项目应迁移到 Project Rules。
规则应像可执行的团队约定一样短而具体。全局规则适合稳定的仓库不变量；路径规则适合前端、服务端或迁移脚本等不同责任区。不要把架构文档、历史决策和完整 API 手册塞进一个永远附着的规则，它会稀释每次任务真正需要的约束。
---
description: TypeScript 服务层的修改与验证约束
globs: src/**/*.ts
alwaysApply: false
---
- 先读取同目录测试与类型定义，再提出修改。
- 不得修改 package.json、锁文件、.env 或部署配置，除非用户明确点名。
- 新分支必须保持 API 兼容；如需破坏性改动，先只输出影响分析。
- 修改后优先运行 npm test -- --runInBand；失败时保留失败输出并解释。
- 所有生成的日志、临时文件和测试数据必须在任务结束前删除。把上例保存为 .cursor/rules/service-layer.mdc 后，使用一个 src/**/*.ts 的小任务检验它。正向实验是让代理在一个函数中补上空值分支并更新同文件测试；预期是候选 diff 只触及源文件和测试。反向实验是要求“顺便升级依赖并修复所有 lint”；预期的安全行为是它先指出规则限制并等待更明确授权，而不是写入包管理文件。若反向实验仍产生越界 diff，撤销实验分支，检查规则是否被正确附着，必要时改为 alwaysApply: true 的短规则，而不是用更长的自然语言补丁覆盖原规则。
用户规则适合语言、答复风格等个人偏好，不应承载仓库安全策略。官方文档还说明 Rules 只会作用于 Agent 与 Inline Edit，并不会自动约束所有补全行为；这意味着 Tab 补全插入的敏感片段、错误 API 或不合规范代码仍要经过相同的 diff 与测试门禁。
Agent、Chat 与终端应保留批准点
在 Chat 中提问、在 Inline Edit 修改选区、在 Agent 中跨文件执行任务，风险并不相同。Inline Edit 的理想用途是局部重命名、补齐条件和文档修订；Agent 更适合需要搜索、跨文件协调和受控测试的任务。每次从 Chat 切到 Agent 前，先在提示里写清可修改的目录、不可读取的目录、可运行命令和停止信号。
终端动作尤其需要分层。读取版本、运行单测、格式化单个文件通常可逐条批准；安装依赖、迁移数据库、访问网络、清理缓存、写入 Git 历史和发布命令应当单独确认。Cursor CLI 的 Agent 使用说明 表示交互式命令在运行前要求批准；--print 会进入没有逐条人工确认的非交互链路。非交互写入还受权限配置和 --force 约束，但这不等于有人会在危险动作发生前替你踩刹车。把它直接接入能访问生产凭据的 CI 或共享工作站，依然会移除关键人工批准点。
# 先看代理将要处理的范围，再由开发者决定是否允许后续动作
cursor-agent "只阅读并总结 tests/auth 下失败原因，不写文件、不运行命令"
# 不把下面的模式用于持有真实密钥、可推送主分支或可访问生产网络的环境
cursor-agent -p "分析 git diff --check 的输出，只给文本建议" --output-format text
# 所有实际修改后都回到 Git 可见证据
git diff --check
git diff -- src/auth/session.ts tests/session.test.ts打开正确目录并启用 Workspace Trust，只处理“是否允许这个文件夹触发编辑器能力”的第一道门，不能替代代理权限，也不能证明已安装扩展可信。Cursor CLI 的 Permissions 文档 支持在用户级 ~/.cursor/cli-config.json 或项目级 .cursor/cli.json 配置 Shell(...)、Read(...)、Write(...)，且 deny 优先于 allow。项目级配置应进入代码审查，但不要在其中保存凭据。下面的最小配置允许读取源代码、写入一个认证模块和运行测试，同时拒绝读取环境文件、删除文件及执行 Git；注意 Shell(git) 会放行所有 Git 子命令，不能把它当成只读授权。
{
"permissions": {
"allow": [
"Read(src/**/*.ts)",
"Read(tests/**/*.ts)",
"Write(src/auth/**)",
"Write(tests/auth/**)",
"Shell(npm)"
],
"deny": [
"Read(.env*)",
"Read(**/*.key)",
"Shell(rm)",
"Shell(git)"
]
}
}正向实验是在无秘密的练习仓库运行只读分析和单测，预期能读取指定源码并执行 npm；反向实验是要求读取 .env 或运行 git push，预期得到权限拒绝且工作树没有新增变化。若反向实验仍成功，先停止非交互任务，核对配置文件实际加载位置、当前工作目录和调用参数，再检查是否使用了覆盖限制的 --force；不要靠提示词里的“请勿读取”掩盖权限配置失效。
看到“运行测试”也要问它将在什么目录、用什么参数、会写哪些缓存。一个常见失败是代理在错误工作区执行 npm test，把上级仓库的缓存与配置带入结论。处理方式不是重复执行，而是先执行 git rev-parse --show-toplevel、检查 pwd 与工作区根目录，再重新运行最小测试。另一个常见失败是测试命令通过却没有覆盖修改路径；这时要读断言和覆盖率报告，而不能把绿色输出当作正确性证明。
还要把“命令失败”区分为环境失败和代码失败。依赖下载超时、公司代理拒绝连接、端口已被本机服务占用、测试数据库没有启动，都会让 Agent 获得一段失败输出；它可能据此改业务代码，结果既没有修网络，也引入了无关补丁。要求它先报告命令、退出码、工作目录、关键错误行和它准备验证的假设。只有证据指向当前改动时才允许编辑实现；如果证据指向基础设施，就停止编码并把问题交回对应的本地环境、凭据或网络配置。这样的暂停不是降低效率，而是避免一次临时故障把无辜的业务逻辑改坏。
隐私模式、团队控制与远程代理
Cursor 的 Privacy & Security 文档 将数据选项放在 Cursor Settings > General > Privacy Mode，并区分 Share Data、Privacy Mode with Storage 与 Privacy Mode。团队不能把“没有用于训练”“不持久保存明文索引”和“请求不离开本机”混成一件事：官方说明即使使用自带 API key，请求仍经过 Cursor 后端完成最终提示组装。启用前要记录谁有权改变模式、团队是否强制设置、哪些仓库禁止索引、各功能保存什么以及日志和用量数据由谁查看。隐私模式改变保存和训练相关处理，并不替代工作区访问控制、代码审查或密钥管理；本地已经可读的文件仍可能被代理选择、终端输出或外部工具带入任务。
将项目拆成三类数据会更容易执行：可进入普通开发上下文的源代码；只能在脱敏后进入上下文的样例与日志；永远不进入 AI 上下文的凭据、个人数据、客户导出和生产配置。第三类先由 .cursorignore 拦住，再通过文件权限、密钥管理器与 CI 注入阻断。不要把真实 token 放进规则、提示词、命令历史或 MCP 配置；示例统一使用 <access-token> 与 example.com。
MCP 扩展了代理能读取和调用的系统。Cursor 官方 MCP 文档说明项目级配置可放在 .cursor/mcp.json，全局配置可放在用户目录；工具默认需要批准，也可以被开启为自动运行。团队应把 MCP 看作新增权限面，而不是一段聊天插件配置：登记工具 owner、访问的系统、认证方式、可写动作、网络出口和停用方式。低风险读取工具可以在练习仓库验证；能删数据、发消息、创建资源或读取工单系统的工具必须从最小权限账号开始，并保留批准记录。
远程 Background Agent 的风险更高。官方说明它在隔离环境中克隆仓库、可以访问互联网并自动运行终端命令；这与前台逐条批准的模型不同。不要把带有生产网络、广泛 GitHub 写权限或长期凭据的仓库直接交给远程代理。创建短命分支、给 GitHub App 最小仓库权限、提供无效测试凭据，并在任务结束后撤销连接或权限，才能把远程迭代限制在可回收的范围内。
用正反实验检查上下文和补丁
AI 工具接入项目的第一个验证不应是“让它生成一个新模块”，而是证明它能在受限输入下做出小而正确的改动。创建临时分支、放一段没有秘密的测试代码、只允许改动两个文件。正向实验验证规则与索引能帮助它定位真实行为；反向实验验证忽略、权限和审查能阻止它跨过边界。
git switch -c experiment/cursor-small-fix
git status --short
# 让 Agent 只处理两个明确文件；由开发者在界面内批准写入与测试
git diff --name-only
npm test -- --runInBand tests/session.test.ts
git diff --check
git diff --stat正向实验的预期证据有三项：测试先失败并能指出与目标分支有关的断言；接受补丁后同一测试通过；git diff --name-only 仅出现被授权的源文件和测试。失败证据也应被保留：若代理开始读取 .env、生成 package-lock.json 或要求执行网络下载，立即拒绝该动作，记录命令与文件名，使用 git restore --source=HEAD -- <file> 仅恢复这次实验产生的已跟踪文件，再重新缩小上下文。
反向实验可以故意提示“扫描整个仓库并自动修复所有问题”。一个成熟配置的预期并不是完成更多修改，而是规则、忽略和人工批准共同限制影响面。若它提出无法证实的“全部修好”，要求它给出每个变更对应的测试名称、差异位置和未覆盖风险。代理无法替代浏览器兼容测试、性能压测、数据迁移验证或安全评审，它只能让这些检查更早进入工作流。
Diff、测试与审查形成闭环
把接受代理补丁视为代码评审，而不是“接受建议”。先检查文件列表和空白错误，再逐段确认业务语义，最后运行最窄的测试。小任务仍然要看删除的代码：代理可能删除看起来冗余的错误分支、指标埋点或权限判断，而单测恰好没有覆盖它。
# 先获得机器可读的基本差异，再读业务上下文
git diff --check
git diff --name-status
git diff -- src/auth/session.ts tests/session.test.ts
# 最小测试通过后，再按项目约定扩大验证
npm test -- --runInBand tests/session.test.ts
npm run lint -- --max-warnings=0
git status --short审查时至少问四个问题：它读取的输入是否被校验；异常是否保留原有语义；新增依赖或命令是否扩大供应链和网络权限；测试是否覆盖了新分支而非只覆盖旧路径。涉及认证、权限、加密、SQL、模板渲染、命令执行或反序列化时，必须再由熟悉该领域的人审阅。可让 Cursor 帮忙列出威胁假设和测试缺口，但不要接受“没有安全问题”这类没有证据链的判断。
将补丁提交到独立分支后，仍应以常规 PR、受保护分支、CI 与人工复核作为合并门。团队可以记录哪些变更来自补全、Inline Edit 或 Agent，用于观察返工率和测试失败模式；记录不应用来跳过审查，也不应成为对个人的产出排名。
清理、回滚与事故隔离
代理实验结束后，最容易被遗漏的是聊天上下文、临时分支、未跟踪生成物、后台进程和临时凭据。先确认哪些文件是实验生成，再选择精确删除或恢复；不要在不理解状态时运行全局清理命令。特别是在 monorepo 或共享工作区，git clean -fd 可能删除另一项正在进行的未跟踪工作。
# 只撤销本次实验中明确的已跟踪文件
git restore --source=HEAD -- src/auth/session.ts tests/session.test.ts
# 先预演未跟踪文件清理；确认列表后才移除
git clean -fdn
# 结束实验分支前确保当前不在该分支
git switch main
git branch -D experiment/cursor-small-fix若代理已执行高风险命令，先断开网络或撤销可疑凭据，再保留终端输出、diff、命令历史和受影响文件清单。接着用已知良好的提交恢复代码，并对可能泄露的 token 进行轮换；仅撤销 Git 提交并不能让已经发出的凭据重新安全。对于远程代理，还应撤销 GitHub App 的仓库授权、删除临时分支和检查是否留下了自动创建的 PR、Issue 或构建资源。
用量、座席与长期治理
模型、上下文大小、请求限额和团队能力会变化，团队不应把某个价格数字、单一模型名称或试用额度写进工程规范。采购或续费前，应由管理员在 Cursor 的团队控制台和官方计划页面核对座席状态、可用能力、隐私强制、单用户用量限制、结算方式与导出能力。技术负责人则关心另一组指标：接受的补丁是否降低返工，测试失败是否更早暴露，是否出现不必要的大上下文、过宽权限或未审查的自动命令。
每个团队至少要有人维护以下事实：哪些仓库允许 Cursor；哪些目录必须忽略；规则由谁审核；MCP 与远程代理有什么权限；隐私模式是否被强制；离职、转岗或外包结束时如何移除成员、撤销 GitHub 连接并回收设备登录。规则文件、忽略文件和小型验证脚本可以进入仓库并像代码一样评审；个人规则、个人会话和本机终端历史不应成为团队唯一知识库。
当团队决定退出或更换工具时，先导出必要的团队审计与用量信息，关闭远程代理和 MCP 连接，撤销团队座席与单点登录映射，删除本机残留凭据，并保留与工具无关的项目规则副本。这样，代码质量门、测试命令和审查标准仍然属于项目，而不是被锁在某个编辑器里。