1. Claude Code 项目越写越乱的真实场景与清理目标用 Claude Code 写项目前两周是蜜月期第三周开始你会隐约觉得不对劲src目录里文件数量翻了一倍有些文件名看着眼熟但想不起来干嘛用的npm run build偶尔报一个「unused variable」警告你顺手删掉那行结果某个页面白屏了。这就是典型的 Claude Code 长期迭代后代码库膨胀——不是 Claude 写错了而是它每次对话都从零开始不记得上周已经写过formatDate于是又造了一个formatTimestamp。我先把问题拆清楚这样后面的清理流程你才知道每一步在解决什么。Claude Code 生成代码有三个特点速度快、局部正确、全局失忆。速度快意味着你一天能加五个功能局部正确意味着每个函数单看都没毛病全局失忆意味着它不会主动检查「这个功能是不是已经存在」。三者叠加项目里就会悄悄堆积四类垃圾第一类是死代码。未被任何文件引用的导出函数、未被任何页面渲染的组件、调试时创建但忘了删的临时文件、import进来却从没用过的模块。这类代码不运行但 Claude 每次读文件都要读它白烧 token。第二类是重复代码。两个功能相同的日期格式化函数、两套描述同一数据结构的 TypeScript 类型、两个都访问数据库但名字不同的 API 包装器。这类代码能跑但维护时你要改两处Claude 也可能只改一处留下不一致。第三类是结构混乱。所有文件平铺在一个文件夹里组件、工具函数、类型定义、服务器操作混在一起。Claude 找TaskCard组件时可能要读五个文件才定位到。第四类是 CLAUDE.md 腐化。项目初期写的规则还在但文件早就移动了、功能早就重构了CLAUDE.md 里还写着「所有工具函数放在 src/utils」而实际已经在 src/lib。Claude 读到矛盾指令行为就开始飘。这套清理流程的目标很明确把项目从「能跑但没人敢动」恢复到「结构清晰、Claude 干活快、你改代码不心虚」。适合谁适合用 Claude Code 或类似 AI 编码工具连续开发了两周以上、文件数超过 30 个、开始感觉每次对话 Claude 都要「探索」很久才动手的人。如果你项目才 10 个文件先别折腾等它长到 30 个再说——清理的收益和文件数成正比太早清理是浪费时间。清理不是一次性大扫除而是把它变成工作流的一部分。我建议每完成一个中等功能大概 3-5 次 Claude 对话就做一轮轻量清理每两周做一次完整清理。下面从 TaoToken 的前置配置讲起因为多轮清理验证需要稳定的 API 通道否则你清理到一半 key 限流了验证就断了。2. TaoToken 前置配置统一 Key 与 API 通道支撑多轮清理验证清理流程里有一个容易被忽略的环节验证。你删了死代码、合并了重复函数、重组了目录结构每一步之后都要跑测试、跑构建、让 Claude 重新读一遍项目确认没漏。这些操作会消耗大量 API 调用如果你用的是零散申请的 key很容易在第三轮清理时撞上限流验证做到一半卡住前面的清理成果没法确认。所以先把 API 通道统一。TaoToken 在这里的作用是提供一个稳定的 Base URL 和统一的 Key 管理让你在 Claude Code、Cline、Codex 这些工具之间切换时不用反复改配置。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置时别把查询串带进去。你需要准备三样东西我把它叫做「三件套」后面所有工具配置都围绕它展开Base URLhttps://taotoken.net/apiAPI Key在控制台创建形如sk-开头的一串字符Model ID根据你用的模型填比如claude-sonnet-4-5这类标识先创建 Key。打开 https://taotoken.net/console 登录后进入 API Keys 页面点创建复制生成的 key。这个 key 只显示一次建议直接存进密码管理器。如果你团队多人用给每人建一个独立 key方便排查是谁的调用出了问题。创建完 key建议先做一次最小验证确认通道是通的。用 curl 发一个最简单的请求curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 64, messages: [{role: user, content: 回复 OK 两个字母}] }如果返回 JSON 里content字段有内容说明 key 和通道都正常。如果返回 401检查 key 有没有复制完整、有没有多余空格如果返回 404检查 Base URL 是不是写成了带/v1的完整路径——不同工具对路径拼接方式不一样这个坑后面第 5 节会专门讲。接下来配置 Claude Code。Claude Code 读取环境变量或配置文件来定位 API 通道。最稳妥的方式是在项目根目录或用户目录下配置。如果你用 Claude Code 的 settings 文件路径通常是~/.claude/settings.json内容如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key, ANTHROPIC_MODEL: claude-sonnet-4-5 } }注意ANTHROPIC_BASE_URL只写到/api不要带/v1。Claude Code 内部会自己拼接/v1/messages你多写一层就变成/api/v1/v1/messages直接 404。这是最常见的配置错误我见过至少三个人卡在这里。如果你同时用 Cline 或别的编辑器插件它们的配置项名字不同但逻辑一样。Cline 在设置里找「API Provider」选 Anthropic 兼容模式然后填 Base URL、API Key、Model ID 三件套。Codex 的话看auth.json路径一般在~/.codex/auth.json把 base URL 和 key 填进去。配置完做一次连通性测试在 Claude Code 里发一句「读取当前目录的文件列表并告诉我项目大概是什么技术栈」。如果它能正常读文件并回答说明通道和工具都通了。这一步别跳过因为后面清理流程里 Claude 要反复读整个项目通道不稳会非常痛苦。最后提醒一点清理期间建议固定用一个模型。不同模型对「死代码判断」的准确率不一样你中途换模型Claude 对同一个函数的判断可能从「可删」变成「保留」验证结果就没法对比了。等清理完再换模型做日常开发。3. 可复制配置CLAUDE.md 清理规则与死代码扫描命令这一节是整套流程的核心给你可以直接复制粘贴的配置和命令。先讲 CLAUDE.md因为它是 Claude 每次对话的「项目说明书」清理规则写在这里Claude 才会在后续对话里自觉遵守。CLAUDE.md 放在项目根目录。清理相关的规则我建议单独成段不要和功能描述混在一起。下面这份是我在 Next.js 项目里实际用的你可以直接抄把文件结构部分改成你自己的# 项目 个人任务管理应用。Next.js 14、TypeScript、Tailwind CSS、Postgres通过 Prisma、NextAuth。 ## 架构 - 默认使用服务器组件仅交互部分使用客户端组件 - 所有数据库查询通过 Prisma禁止原始 SQL - 所有服务器操作放在 src/actions/ - 任务数据始终限定于已认证用户 ## 文件结构 - src/app/页面、布局、API 路由 - src/components/ui/通用可复用组件Button、Input、Card、Badge - src/components/tasks/任务专用组件TaskList、TaskForm、TaskCard、StatusBadge - src/lib/工具函数formatDate、validateInput、tokenUtils - src/types/TypeScript 类型定义 - src/actions/用于 CRUD 和认证的服务器操作 ## 清理规则 - 新增工具函数前先搜索 src/lib/ 是否已有同功能函数 - 新增类型定义前先搜索 src/types/ 是否已有同结构类型 - 组件超过 100 行时评估是否拆分为更小单元 - 每次功能合并前运行死代码扫描 - 禁止在 src/ 下创建临时调试文件调试完立即删除 ## 设计 遵循 design-system.md。所有样式通过 Tailwind 实现。 ## 规则 - 新功能在合并前需要测试 - 每周运行 npm audit - 架构投入最大精力功能投入中等编辑投入最低这份 CLAUDE.md 控制在 30 行以内。我试过写 60 行以上的版本Claude 反而会忽略部分规则因为上下文里规则太多它抓不住重点。精简比全面重要。写完 CLAUDE.md接下来是死代码扫描。Claude 可以帮你扫但你要给它明确的指令否则它会泛泛地说「有一些未使用的导入」而不给具体位置。开启一个新对话清理任务建议开新对话避免旧上下文干扰然后发这段扫描整个代码库识别死代码。检查以下四类 1. 每个文件中未被使用的 import 2. 未被任何文件引用的导出函数 3. 未被任何页面或布局渲染的组件 4. 未被任何文件引用的独立文件 对每个实例输出文件路径、行号、代码片段、判断依据。 不要直接删除先列清单。Claude 会逐个读文件、追踪导入关系图然后给你一份清单。典型项目里死代码占比 10% 到 15%30 个文件的项目大概能找出 3 到 5 处。拿到清单后不要急着删。Claude 会误判尤其是动态导入、配置文件里引用的字符串、服务器操作这些它追踪不到的用法。对每个标记项你可以追问一句formatDate 是否在静态导入分析可能遗漏的地方被使用 检查服务器操作、动态 import()、配置文件引用、字符串形式的模块路径。确认无误后再让它删删除所有已确认的死代码。移除未使用的 import。删除孤立文件。 删除后运行 npm run build 和 npm test报告结果。构建和测试通过这一轮死代码清理就算完成。如果构建失败让 Claude 读报错信息回滚对应删除。重复代码的扫描指令不一样重点是「按功能分组」查找在不同文件中实现相同功能的函数、工具或组件。 按功能分组每组输出 - 涉及的文件和函数名 - 功能描述 - 建议保留哪个版本、删除哪个版本、理由 不要直接合并先给分组清单。Claude 生成的项目里重复代码高发区有三个API 客户端包装器fetchTasks和getTasks干同一件事、TypeScript 类型定义Task和TaskType结构相同、工具函数多个日期格式化、字符串处理。看到分组清单后选更完整的那个版本保留让 Claude 合并将这些重复的工具合并到 src/lib/utils.ts 的单个文件中。 更新整个代码库的所有 import 路径。合并后运行测试。合并完再跑一次测试。通过的话你的文件数会减少Claude 后续每次对话要读的文件也少了。4. 验证请求与成功结果多轮清理后的项目状态确认清理做完不等于结束你得验证。验证分三层功能层、结构层、Claude 行为层。三层都过了才算真的清理成功。功能层验证最直接跑构建和测试npm run build npm test构建通过说明没有语法错误和类型错误测试通过说明功能没被破坏。如果项目没有测试至少跑一次npx tsc --noEmit做类型检查再手动点几个核心页面。我踩过的坑是删了一个「看起来没用」的函数构建也过了但那个函数是通过字符串动态调用的运行时才报错。所以构建通过只是第一关核心流程要手动走一遍。结构层验证看文件数和目录层级。清理前记录一下src下的文件总数清理后再数一次。一个健康的清理应该让文件数减少 15% 到 25%。如果没减少说明死代码和重复代码没找干净如果减少超过 40%你要警惕是不是误删了还在用的东西回头检查测试覆盖。目录结构方面清理后应该是按用途分组而不是按创建时间平铺。用这条命令看结构find src -type f -name *.ts -o -name *.tsx | sort输出应该呈现清晰的层级app/下是页面和布局components/ui/是通用组件components/tasks/是业务组件lib/是工具函数types/是类型actions/是服务器操作。如果还有一堆文件散在src/根目录说明结构重组没做彻底。Claude 行为层验证最容易被忽略但最能说明问题。开一个新对话发一个需要跨文件理解的任务比如在任务卡片上添加一个「标记完成」按钮点击后更新任务状态。观察 Claude 的反应。清理前它可能要读五六个文件才找到TaskCard组件中间还会问「你的任务组件在哪个目录」。清理后它应该直接定位到src/components/tasks/TaskCard.tsx读一两个相关文件就开始改。如果 Claude 还是到处翻文件说明你的 CLAUDE.md 文件结构部分没写清楚或者目录重组没做到位。再做一个 token 消耗对比。清理前后各做一次相同复杂度的任务看 API 用量。干净项目通常比冗余项目省 20% 到 30% 的 token。这个数字不是绝对值但趋势应该明显。如果你用 TaoToken 的控制台可以在 https://taotoken.net/console 看用量统计对比清理前后的单任务消耗。多轮清理的验证节奏是这样的第一轮清理死代码验证第二轮合并重复代码验证第三轮重组目录结构验证第四轮审计 CLAUDE.md验证。每轮之间隔一天让项目稳定一下。不要一天内做完四轮因为如果第三轮出了问题你分不清是第二轮还是第三轮引入的。验证通过的标准我总结成三条构建和测试全绿、文件数下降 15% 以上、Claude 定位文件不再需要探索。三条都满足这轮清理就成功了。有一条不满足回到对应环节重做。5. 本篇常见错误排查401、local proxy failed、reading choices 与 OAuth清理流程里报错集中在配置和验证两个环节。我把最常见的四类错误和排查方法列出来你对照着看。401 Unauthorized。这个最直接key 有问题。排查顺序先确认 key 复制完整没有首尾空格没有换行符。然后确认 key 没有过期或被禁用去 https://taotoken.net/api-keys 看状态。再确认请求头字段名对不对——Anthropic 兼容接口用x-api-key有些工具用Authorization: Bearer填错字段名也会 401。最后确认 Base URL 没写错https://taotoken.net/api后面不要手动加/v1。local proxy failed。这个报错通常出现在你本地开了某种转发工具或者工具配置里填了localhost地址。排查检查 Claude Code 或 Cline 的配置里 Base URL 是不是被改成了http://localhost:xxxx。如果是改回https://taotoken.net/api。另外检查环境变量HTTP_PROXY、HTTPS_PROXY有没有被设置成奇怪的地址有的话清掉。这个报错和网络环境有关但根因基本都是配置指向了本地地址。reading choices 相关报错。这个一般出现在响应解析阶段报错信息里带reading choices或类似字段。原因是工具按 OpenAI 格式解析响应但实际返回的是 Anthropic 格式或者反过来。排查确认你用的模型和接口格式匹配。Claude 系列走 Anthropic 格式响应里是content数组如果你在 Cline 里选了 OpenAI 兼容模式却填了 Claude 模型就会解析失败。解决方法是把 Provider 类型改成 Anthropic或者换成对应的模型 ID。OAuth 相关报错。如果你用 Claude Code 的登录流程而不是 API Key可能会遇到 OAuth 回调失败。排查确认你走的是 API Key 模式而不是 OAuth 模式。在 settings.json 里同时配了ANTHROPIC_API_KEY和 OAuth 相关字段时工具可能优先走 OAuth 然后失败。清掉 OAuth 相关配置只保留三件套。除了这四类还有一个高频问题是「配置改了但没生效」。原因是环境变量优先级shell 里 export 的变量会覆盖配置文件里的值。排查方法是打印当前生效的配置echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_API_KEY如果输出和你配置文件里写的不一样说明 shell 里有旧值。清掉 shell 里的 export或者重启终端。再给一个通用排查思路任何报错先看 HTTP 状态码。401 是认证问题404 是路径问题429 是限流500 是服务端问题。状态码定位了大方向再去查具体配置。别一上来就改代码配置问题占报错的八成以上。最后提醒清理过程中如果 Claude 突然开始胡言乱语或者重复输出先检查是不是上下文太长了。清理任务会让 Claude 读大量文件上下文容易爆。这时候开新对话把当前进度和 CLAUDE.md 重新贴进去继续做。6. 语义一致 CTA把清理变成习惯让 Claude Code 持续高效清理做完一轮项目会明显清爽但如果你不改工作习惯两周后它又会乱。所以最后讲怎么把清理变成常规动作。第一把死代码扫描写进你的功能合并流程。每次功能开发完、准备合并前让 Claude 跑一次扫描。指令可以固化成一个快捷 prompt存在你的笔记里用的时候直接贴。扫描发现的问题当场处理不要攒着——攒到 30 个问题再清理你会不想动手。第二CLAUDE.md 每两周审计一次。项目在变CLAUDE.md 也要跟着变。审计指令很简单审查 CLAUDE.md。移除不再适用于当前代码库的规则或引用。 添加我们最近建立的架构模式。保持 30 行以内。第三新增代码前先搜索。这条规则写进 CLAUDE.md 了但你要在对话里主动提醒 Claude。比如你要加一个日期处理功能先说一句「先搜索 src/lib/ 有没有现成的日期函数」再让它写。养成这个习惯重复代码的源头就堵住了。第四控制单次对话的范围。Claude Code 的上下文是有限的一次对话里塞太多任务它读的文件就多判断也容易飘。一个对话专注一个功能或一个清理任务做完就开新对话。这样每次 Claude 的上下文都干净定位文件也快。关于工具和通道如果你清理任务比较密集需要频繁调用 API 做验证可以考虑用 Coding Plan 这类长期方案避免每次验证都担心额度。入口在 https://taotoken.net/coding-plan 适合连续多天做重构的场景。如果只是偶尔验证一下模型输出用模型对话页面就够了https://taotoken.net/models 。接入文档在 https://taotoken.net/doc 里面有各工具的详细配置步骤遇到本文没覆盖的工具可以去查。清理这件事做一次是救火做成习惯才是真的解决问题。Claude Code 本身不会帮你维护项目整洁它只负责快速生成。整洁是你的责任而 CLAUDE.md 加定期扫描就是你把这份责任交给流程的方式。项目从 40 个文件降到 30 个Claude 每次对话少读四分之一文件这个收益会随着你继续开发不断累积。趁项目还没长到 200 个文件现在就开始清理。