1. 老代码重构为什么会翻车：从一次真实事故说起

我接手过一个八年前的单体项目，Spring Boot 1.x 加 JSP，数据库里还有一堆没人敢动的存储过程。需求很简单：把用户模块拆出来，顺手把接口从 XML 配置改成注解。听起来是标准的重构任务，我当时的想法也很朴素——让 AI 帮我读代码、出方案、改文件，效率至少翻三倍。

结果第一天就翻车了。Claude Code 读完项目后，直接给我生成了一份"重构方案"，把三个核心 Service 合并成一个，理由是"职责重叠"。我扫了一眼觉得有道理，点了应用。半小时后本地启动报错，BeanCreationException连环炸，原因是它没意识到那两个 Service 被 AOP 切面按类名硬编码拦截了。更麻烦的是，Trae 那边我同时开着另一个会话在改前端调用，两边对同一个 DTO 的理解不一致，一个改了字段名，一个还在用旧字段，联调直接对不上。

这次事故让我意识到两个问题。第一，AI 读代码的能力很强，但它不知道"这个类不能动"这种隐性约束，除非你明确告诉它。第二，多个 AI 工具各自为战，上下文不共享，改出来的东西必然打架。后来我用了两周时间重新梳理流程，核心思路是：用 OpenSpec 把重构任务拆成有规范的变更提案，用 AGENTS.md 把项目约束固化下来，再用 TaoToken 统一 Key 把 Claude Code 和 Trae 接到同一条 API 通道上，保证两边看到的是同一套模型、同一套规范。

这篇文章就是那次复盘。我会把可复制的 AGENTS.md 配置、OpenSpec 任务拆分模板、以及翻车后的回滚验证清单都写出来。如果你手里也有那种"年没人敢碰"的老代码，这套流程能帮你少走至少一周弯路。

先说清楚适用人群：你至少用过一次 Claude Code 或 Trae，知道什么是 API Key，能在终端里跑 npm 命令。不需要你懂 OpenSpec，我会从初始化讲起。核心检索词就三个——OpenSpec 规范注入、Claude Code 接入、Trae 项目规则配置，这三个搞定了，剩下的都是顺水推舟。

2. TaoToken 统一 Key 接入 Claude Code 与 Trae 的前置准备

在讲配置之前，得先解决一个现实问题：Claude Code 和 Trae 默认走的是各自的官方通道，你要么分别管理两套 Key，要么就得找个统一入口。我试过手动同步两边的环境变量，结果是每次换 Key 都要改两个地方，还容易漏。后来换成 TaoToken 统一 Key，一个 Key 同时给两个工具用，省事很多。

TaoToken 在这里的角色是 API 通道聚合，它提供兼容 Anthropic 和 OpenAI 格式的接口。Claude Code 走的是 Anthropic 协议，Trae 走的是 OpenAI 兼容协议，TaoToken 两边都支持，所以你只需要在官网注册一次，拿到一个 Key，然后分别填到两个工具的配置里就行。官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，注册流程不复杂，邮箱加密码，两分钟搞定。

拿到 Key 之后，你需要确认两件事。第一，你的项目目录结构。OpenSpec 初始化会往项目根目录写文件，所以你得先cd到项目根目录再执行初始化。第二，确认 Node.js 版本。OpenSpec 要求 Node 18 以上，我用的是 20.11.0，跑起来没问题。你可以用node -v检查一下，如果低于 18，先升级。

关于模型选择，TaoToken 支持 Claude 系列和 GPT 系列。Claude Code 建议用 claude-sonnet-4-20250514 或更新的版本，代码理解能力强，长上下文不容易丢信息。Trae 那边如果你主要做前端改造，用 claude-sonnet-4-20250514 也行，如果偏后端逻辑，gpt-4o 也可以。我实测下来，重构场景下 Claude 系列对老代码的兼容性判断更准，尤其是涉及反射和动态代理的代码。

还有一个前置动作容易被忽略：把项目的.gitignore检查一遍。OpenSpec 会生成openspec/目录，这个目录建议提交到 Git，因为它是团队共享的规范载体。但.claude/目录下的本地配置不要提交，里面可能有你的 Key 信息。你可以在.gitignore里加一行.claude/settings.local.json，避免 Key 泄露。

最后提醒一点：TaoToken 的 API 地址是 https://taotoken.net/api ，注意不要加 UTM 参数，直接填这个地址就行。Claude Code 的 Base URL 填https://taotoken.net/api，Trae 的 Base URL 也填同一个，但路径可能略有不同，下面配置章节会详细写。

3. 可复制配置：AGENTS.md、OpenSpec 与双工具接入片段

这一节是全文的核心，我会把三个配置文件完整写出来，你直接复制改改就能用。先装 OpenSpec，再配 AGENTS.md，最后分别配 Claude Code 和 Trae。

3.1 安装 OpenSpec 并初始化项目

全局安装命令如下，注意包名是@fission-ai/openspec：

npm install -g @fission-ai/openspec@latest cd /path/to/your-project openspec init

初始化时会提示你选择 AI 工具。如果你用 Claude Code，直接选 Claude Code，它会生成.claude/commands/openspec/目录和AGENTS.md。如果你用 Trae，选Other Tools，它会生成openspec/目录和根目录的AGENT.md。我两个都用，所以初始化了两次，分别放在两个分支上，最后手动合并了配置。

初始化完成后，目录结构大概是这样：

项目根目录/ ├── .claude/ │ ├── commands/openspec/ │ │ ├── apply.md │ │ ├── archive.md │ │ └── proposal.md │ ├── AGENTS.md │ └── CLAUDE.md ├── openspec/ │ ├── AGENTS.md │ ├── project.md │ ├── specs/ │ └── changes/ └── AGENT.md

3.2 AGENTS.md 配置片段（项目约束固化）

这个文件是 AI 每次对话的"第一课"，我把它改成了适合老代码重构的版本。核心是把"不能动的东西"写清楚：

# 项目 AI 协作规范 ## 重构红线（绝对禁止） - 禁止修改 `com.legacy.aop` 包下任何类，这些类被 XML 硬编码拦截 - 禁止重命名 `UserDTO` 的 `userId` 和 `userName` 字段，前端有硬编码引用 - 禁止删除 `LegacyUserService` 的 `queryByCondition` 方法，存储过程依赖它 - 禁止改动 `application-context.xml` 中的 bean id ## 重构允许范围 - 可以新增注解配置，但必须保留 XML 配置作为 fallback - 可以拆分 Service，但必须保留原类作为门面（Facade） - 可以改方法内部实现，但方法签名不能变 ## OpenSpec 触发规则 当请求包含"提案""变更""重构方案""规范"等关键词时， 必须先读取 `@/openspec/AGENTS.md` 再执行。 ## 业务知识索引 - 用户模块业务逻辑：`docs/user-module.md` - 数据库表关系：`docs/db-schema.md` - 历史踩坑记录：`docs/pitfalls.md`

这个文件放在项目根目录，Claude Code 会自动读取。Trae 新版本也支持读取AGENT.md，老版本需要手动粘贴到项目规则里。

3.3 Claude Code 接入 TaoToken 配置

Claude Code 的配置在~/.claude/settings.json或项目级.claude/settings.local.json。我建议用项目级配置，避免影响其他项目：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "你的TaoToken Key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" }, "permissions": { "allow": ["Read", "Write", "Bash(npm run *)", "Bash(git diff *)"] } }

注意ANTHROPIC_BASE_URL填https://taotoken.net/api，不要加尾部斜杠。Key 从 TaoToken 控制台的 API Keys 页面获取，地址是 https://taotoken.net/api-keys 。配好后重启 Claude Code，用/status命令确认连接状态。

3.4 Trae 接入 TaoToken 配置

Trae 的配置在设置里的"模型服务"部分。如果你用的是 Trae 国内版，路径是：设置 → AI → 模型服务 → 添加自定义模型。填写如下：

注意 Trae 的 Base URL 要加/v1后缀，这是 OpenAI 兼容协议的要求。Claude Code 不需要加，因为走的是 Anthropic 原生协议。这个差异我踩过坑，一开始两边填一样的地址，Trae 一直报 404。

配好后在 Trae 里新建对话，输入"读取 AGENT.md 并总结项目约束"，如果能正确读出内容，说明配置成功。

3.5 OpenSpec 任务拆分模板

这是我在翻车后总结的模板，放在openspec/changes/目录下，每个重构任务一个文件：

# 变更提案：用户模块接口注解化 ## 背景 当前用户模块使用 XML 配置，维护成本高，需要逐步迁移到注解配置。 ## 影响范围 - 涉及类：UserController、UserService、UserServiceImpl - 涉及配置：application-context.xml 中的 user 相关 bean - 前端影响：无（接口签名不变） ## 约束条件 - 必须保留 XML 配置作为 fallback，通过 profile 切换 - 禁止修改 UserDTO 字段名 - 禁止删除 LegacyUserService ## 实施步骤 1. 新增注解配置类 UserAnnotationConfig 2. 在 UserServiceImpl 上添加 @Service 注解 3. 保留 XML 中的 bean 定义，设置 lazy-init=true 4. 编写对比测试，验证两种配置行为一致 5. 切换 profile 验证，确认无回归 ## 回滚方案 - 删除 UserAnnotationConfig - 恢复 XML 配置的 lazy-init 设置 - 重新部署验证 ## 验证清单 - [ ] 单元测试通过率 100% - [ ] 集成测试用户模块全部通过 - [ ] 手动验证登录、查询、更新三个接口 - [ ] 检查日志无 BeanCreationException

这个模板的关键是"约束条件"和"回滚方案"两节。翻车那次就是因为没写约束，AI 自由发挥把 AOP 切面搞崩了。

4. 验证请求与成功结果：从提案到应用的完整流程

配置写完了，得验证能不能跑通。我用一个真实的重构任务来演示：把用户查询接口从 XML 配置改成注解配置，同时保证不破坏现有功能。

4.1 发起变更提案

在 Claude Code 里输入：

/openspec:proposal 用户模块接口注解化

Claude Code 会读取openspec/AGENTS.md，然后根据规范生成一份提案草稿。我实测下来，它会自动填充背景、影响范围、实施步骤，但"约束条件"和"回滚方案"需要你手动补充，因为 AI 不知道你的隐性约束。这就是为什么 AGENTS.md 里要写清楚红线。

生成后，用openspec validate校验提案格式：

openspec validate user-module-annotation

如果输出Validation passed，说明格式没问题。如果报错，通常是缺少必填字段，按提示补上就行。

4.2 应用变更

提案批准后，在 Claude Code 里输入：

/openspec:apply user-module-annotation

Claude Code 会按照提案里的步骤逐条执行。这里有个关键点：它每改一个文件，你都要用git diff看一眼。我翻车那次就是没看 diff，直接让它批量改，结果改错了三个文件。

正确的做法是分步应用。你可以在提案里把步骤拆细，比如"新增配置类"是一步，"添加注解"是另一步，这样 AI 每次只改一个文件，你验证起来也容易。

4.3 验证成功结果

改完后，跑测试：

mvn test -Dtest=UserModuleTest

如果全部通过，再启动应用验证：

mvn spring-boot:run -Dspring.profiles.active=annotation

启动成功后，用 curl 测三个接口：

curl -X POST http://localhost:8080/api/user/query \ -H "Content-Type: application/json" \ -d '{"userId": "123"}'

返回{"userId":"123","userName":"test"}就说明注解配置生效了。然后切换到 XML profile 再测一遍，确认 fallback 也能用：

mvn spring-boot:run -Dspring.profiles.active=xml

两个 profile 都通过，才算真正成功。

4.4 Trae 侧的同步验证

Claude Code 改完后端，Trae 那边要同步验证前端调用。在 Trae 里输入：

读取 openspec/changes/user-module-annotation.md， 检查前端调用是否与后端接口签名一致

Trae 会读取提案文件，然后扫描前端代码里的 API 调用。如果发现字段名不一致，它会提示你。我实测下来，Trae 对 TypeScript 类型定义的检查比较准，但对 JavaScript 里的动态调用容易漏，所以关键接口还是手动核对一遍。

4.5 归档变更

验证通过后，归档提案：

openspec archive user-module-annotation

归档后，提案会移到openspec/changes/archive/目录，同时更新openspec/specs/里的规范。这样下次 AI 读规范时，就知道用户模块已经注解化了。

5. 本篇常见错误排查：401、local proxy failed 与 OAuth 报错

这一节列的都是我实际踩过的报错，按出现频率排序。

5.1 401 Unauthorized

这是最常见的错误，原因通常是 Key 填错或 Base URL 不对。先检查 Claude Code 的配置：

cat .claude/settings.local.json | grep ANTHROPIC

确认ANTHROPIC_API_KEY是完整的 Key，没有多余空格。然后确认ANTHROPIC_BASE_URL是https://taotoken.net/api，不是https://taotoken.net/api/v1。Claude Code 走 Anthropic 协议，不需要/v1。

Trae 那边如果报 401，检查 Base URL 是不是https://taotoken.net/api/v1，Trae 需要/v1。这个差异我强调过，但每次配新工具还是会搞混。

5.2 local proxy failed

这个报错通常出现在 Claude Code 启动时，原因是环境变量冲突。如果你之前配过其他代理工具，HTTP_PROXY或HTTPS_PROXY可能还在。检查一下：

env | grep -i proxy

如果有输出，用unset HTTP_PROXY HTTPS_PROXY清掉，然后重启 Claude Code。注意不要用export设成空字符串，那样还是会走代理逻辑，必须unset。

5.3 reading choices 报错

这个报错出现在 Trae 里，通常是模型返回格式不对。原因是 Trae 期望 OpenAI 格式的响应，但 TaoToken 返回的是 Anthropic 格式。解决办法是确认 Trae 的模型服务选的是"OpenAI 兼容"，而不是"Anthropic"。如果你选错了协议，TaoToken 会按 Anthropic 格式返回，Trae 解析不了。

5.4 OAuth 相关报错

Claude Code 如果报 OAuth 错误，说明它在尝试走官方登录流程，而不是用 API Key。检查settings.json里有没有oauth相关配置，有的话删掉。然后确认ANTHROPIC_API_KEY已经设置，Claude Code 会优先用 API Key，不走 OAuth。

5.5 OpenSpec 规范不触发

AI 不读openspec/AGENTS.md，通常是触发词没命中。OpenSpec 的触发机制是关键词匹配，你的请求里要有"提案""变更""规范"这些词。如果不想每次都说触发词，可以在AGENTS.md里加一条规则：

## 强制触发 任何涉及代码修改的请求，都必须先读取 openspec/AGENTS.md。

这样 AI 每次改代码前都会读规范，不用你手动触发。

5.6 回滚验证清单

如果改完发现有问题，按这个清单回滚：

# 1. 查看当前变更 git status # 2. 回滚所有未提交的修改 git checkout -- . # 3. 如果已经提交，回滚到上一个 commit git reset --hard HEAD~1 # 4. 删除 OpenSpec 提案 rm -rf openspec/changes/user-module-annotation # 5. 重启应用验证 mvn spring-boot:run

回滚后，用openspec list确认提案已删除，然后重新发起提案，这次把约束条件写得更细。

6. 长期编码与 Agent 场景：把 TaoToken 用成团队标配

单次重构跑通后，下一步是把它变成团队的标准流程。我现在的做法是：每个新项目初始化时，先跑一遍 OpenSpec init，然后把 AGENTS.md 模板复制进去，再配好 TaoToken 的 Key。新同学入职，照着文档配一遍，半小时就能上手。

对于长期编码场景，TaoToken 的 Coding Plan 比按量付费更划算。如果你每天都要用 Claude Code 改代码，建议开 Coding Plan，地址是 https://taotoken.net/coding-plan 。它按周期计费，不限制 Token 用量，适合高频使用。

Agent 场景下，比如让 AI 自动跑测试、自动提交代码，你需要把权限配好。Claude Code 的permissions.allow里可以加Bash(mvn test *)和Bash(git commit *)，但不要加Bash(rm *)，避免误删。我一般只给读和测试权限，写操作还是手动确认。

最后说一个实用技巧：把 OpenSpec 的提案模板和 AGENTS.md 模板放在一个 Git 仓库里，团队共享。每次新项目直接 clone 过来，改改约束条件就能用。这样规范不会散落在各人电脑上，AI 读到的永远是团队最新版本。

如果你还没配 TaoToken，先去官网拿 Key，然后按第 3 节的配置片段填到 Claude Code 和 Trae 里。配好后跑一个小的重构任务试试，比如把一个工具类的方法从静态改成实例方法，验证整个流程能跑通。跑通了再上大任务，别一上来就动核心模块。