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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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/apiTrae 的 Base URL 也填同一个但路径可能略有不同下面配置章节会详细写。3. 可复制配置AGENTS.md、OpenSpec 与双工具接入片段这一节是全文的核心我会把三个配置文件完整写出来你直接复制改改就能用。先装 OpenSpec再配 AGENTS.md最后分别配 Claude Code 和 Trae。3.1 安装 OpenSpec 并初始化项目全局安装命令如下注意包名是fission-ai/openspecnpm install -g fission-ai/openspeclatest 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.md3.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 → 模型服务 → 添加自定义模型。填写如下配置项值服务商OpenAI 兼容Base URLhttps://taotoken.net/api/v1API Key你的TaoToken Key模型 IDclaude-sonnet-4-20250514最大 Token200000注意 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-inittrue 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-annotationClaude Code 会按照提案里的步骤逐条执行。这里有个关键点它每改一个文件你都要用git diff看一眼。我翻车那次就是没看 diff直接让它批量改结果改错了三个文件。正确的做法是分步应用。你可以在提案里把步骤拆细比如新增配置类是一步添加注解是另一步这样 AI 每次只改一个文件你验证起来也容易。4.3 验证成功结果改完后跑测试mvn test -DtestUserModuleTest如果全部通过再启动应用验证mvn spring-boot:run -Dspring.profiles.activeannotation启动成功后用 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.activexml两个 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/v1Trae 需要/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 里。配好后跑一个小的重构任务试试比如把一个工具类的方法从静态改成实例方法验证整个流程能跑通。跑通了再上大任务别一上来就动核心模块。