从 Cursor 搬到 Claude Code

约 1184 字大约 4 分钟

2026-09-11

用了大半年 Cursor,最后是因为一个很具体的理由换掉的:我们的后端是个十几个模块的 Gradle 多模块工程,Cursor 的索引是 embedding 驱动的,跨模块找「同一个模式在别处是怎么写的」经常漏。Claude Code 笨一点,它直接把文件读进去,慢,但不漏。

搬过来花了两周,前三天基本都在填坑。

规则文件不是复制粘贴

Cursor 的规则放在 .cursor/rules/*.mdc,每个文件带 frontmatter:

---
description: "MyBatis Mapper 编写规范"
globs: "**/mapper/**/*.java"
alwaysApply: false
---

globs 决定这条规则只在动到匹配文件时才挂进上下文,alwaysApply: false 意味着平时它根本不在。而 CLAUDE.md 是纯 Markdown,没有 frontmatter,没有条件激活——进去的东西每次都在。

我以为这就是个格式转换,写了个脚本把 11 个 .mdc 的正文 cat 到一起塞进 CLAUDE.md。结果第一天就出事:我让它改一个 UserMapper.xml 里的 SQL,它顺手按前端那份规则把同目录下一个 .ts 文件的 import 重排了一遍,理由是「规则里写了 import 要按字母序」。那条规则原本 globs 限定在 web/src/**,拼进 CLAUDE.md 之后就变成了全局宪法。

正确的拆法是按目录放:

CLAUDE.md                     # 只放全局的:技术栈、构建命令、不可改的范围
web/CLAUDE.md                 # 前端规范
service-order/CLAUDE.md       # 这个模块的领域知识

Claude Code 会按路径层级加载,子目录的规则只在你动那个目录时生效——这是 globs 最接近的等价物。另外那句「你是一位资深 Java 架构师」可以删了,对 Claude Code 没什么用,白占 token。

覆盖顺序会咬人

~/.claude/agents/ 是用户级,.claude/agents/ 是项目级。同名的 subagent,项目级优先。我在个人目录里放了一个叫 reviewer 的 agent 用了半年,接手新项目后发现它行为完全变了——项目里也有一个同名的。排查这种问题的第一条命令是 claude mcp list 和 /context,先看清楚现在到底加载了什么,再猜。

hook 写错退出码等于没写

Claude Code 的 hook 靠退出码通信,这套语义和普通 shell 脚本的直觉不一样:

退出码	含义
`0`	成功,继续
`2`	阻塞,stderr 的内容会回灌给 Claude 让它改
其它	非阻塞错误,只显示给我看,Claude 完全无视

我最早写的格式化 hook 是 exit 1,跑了一个星期才发现 Claude 从来没收到过任何反馈——它压根不知道自己提交的代码没过 checkstyle。改成 exit 2 之后,它会自己读 stderr 然后把格式修掉。

#!/usr/bin/env bash
set -euo pipefail

changed=$(git diff --name-only --cached | grep -E '\.java$' || true)
[ -z "$changed" ] && exit 0

if ! ./gradlew spotlessCheck --quiet; then
  echo "spotless 未通过,请运行 ./gradlew spotlessApply" >&2
  exit 2
fi

set -euo pipefail 这行别省。少了 -o pipefail,管道中间一环失败整条命令照样返回 0,hook 一路绿灯,实际什么都没检查——跟我们在 GitLab CI 的部署脚本里栽过的是同一个跟头。

上下文窗口比标称的小

标称 200K,实际能用的没那么多。几个在偷偷吃 token 的地方:

自动压缩:窗口快满时会自动做一次总结压缩,这个过程本身要占掉相当一块预算;
MCP server:每个连着的 server 都会把工具定义塞进上下文,几个下来吃掉一两万 token 很正常。.mcp.json 里配了不用的,claude mcp remove <name> 删掉,别留着;
subagent:并行派十个 subagent 各读一遍代码,总 token 是顺序做的好几倍。换来的是速度,不是省钱,该不该用看任务值不值。

我的习惯是每次开工先 /context 看一眼水位,超过六成就 /clear 重开,把需要延续的东西写进 CLAUDE.md 而不是指望它记住。

值不值得搬

两个月下来,团队的 PR 从提交到合入的中位数从 4 天多降到 1.7 天,主要不是因为 AI 写得多快,而是那个跑在 CI 里的评审 agent 把「变量命名」「空指针」「忘了加事务」这类往返消耗掉了,人只需要看架构。

代价也实在:token 花销比用 Cursor 订阅制的时候明显高,月度波动还大。这笔账每个团队自己算。

真要总结一条:Cursor 是 IDE 里的一个功能,Claude Code 是命令行里的一个同事。前者你要教它用你的编辑器,后者你要教它用你的工程——写 CLAUDE.md 的时候当成在写新人入职文档,基本就对了。