Claude Code项目越写越乱？这套清理流程能救你

你有没有遇到过这种情况：用Claude Code开发了一段时间后，打开项目目录一看，里面堆了三四十个文件，有些是你自己写的，有些是Claude生成的，还有一些你根本不知道是干嘛用的。

一位网友发帖说："你那22万行代码的代码库可能是一团臃肿的乱麻。建议是把重构和删除死代码作为你工作流程的常规部分。"虽然说的是一个更大的项目，但这个原则适用于任何规模。Claude生成代码很快。它也会生成你不需要的代码。

用Claude Code开发就是这样的。它写代码确实快，但不会管你的项目是不是已经有一个同样的功能了。举个例子：Claude可能在这周创建了一个格式化日期的工具函数，下周又创建了另一个也格式化日期的函数，放到了不同的文件里。两个都能用，但谁也不调用谁。你的项目里就这样悄悄多了两个干同一件事的函数。

把这个模式放大到整个项目，你就会得到一堆重复的辅助函数、孤立的组件、压根没用到过的导入、以及调试时创建但事后忘了删的文件。

Claude没有眼睛，也不记得它上周创建了什么。每次新对话都是从头开始。它读取你的文件，构建你这次要的东西，却不记得三次对话前已经在某处写过一个完全够用的formatDate函数。

这篇文章就是教你做清理的。跟着步骤走完，你的项目会变得精简有序，Claude干活也能快不少。

寻找死代码

死代码是指项目中存在但从未实际运行的代码。未使用的导入、未被调用的函数、未被任何页面渲染的组件、未被任何文件引用的文件。

Claude 可以帮你找到它们。开启一个新的对话（为此任务清理上下文），然后说：

bash 复制代码

 扫描整个代码库，识别死代码。检查：每个文件中的未使用导入、未被任何文件引用的导出函数、未被任何页面或布局渲染的组件、未被任何文件引用的文件。列出每个实例，包括文件路径和行号。

Claude 会系统地读取每个文件，追踪导入关系图，并报告未使用的部分。在一个经过多次会话构建的典型项目中，我发现有 10-15% 的死代码。对于项目来说，大概是 3-5 个文件或函数。

在删除任何内容之前，先审查列表。有时 Claude 会误将代码识别为死代码，而实际上它被动态使用（通过变量导入、在配置文件中引用，或作为未出现在导入语句中的服务器操作）。对于 Claude 标记的每个项目，问自己："这是通过 Claude 无法追踪的机制使用的吗？"如果不确定，可以问 Claude："formatDate 是否在静态导入分析可能遗漏的地方被使用？检查服务器操作、动态导入和配置文件。"

确认死代码后，告诉 Claude："删除所有已确认的死代码。移除未使用的导入。删除孤立文件。"然后运行测试以验证没有破坏任何功能。如果测试通过，清理就是安全的。

合并重复代码

死代码是显而易见的浪费。重复代码则是隐蔽的浪费。它虽然能正常工作，但会让项目变得更大、更难维护。更重要的是，它会让 Claude 在每个任务中读取更多文件，从而消耗更多 token。

告诉 Claude："查找在不同文件中实现相同功能的函数、工具或组件。按功能分组。对每组，推荐保留哪个版本、删除哪个版本。"

在 Claude 构建的项目中常见的重复代码：

多个 API 客户端包装器。 Claude 可能在一个文件中创建了 fetchTasks 函数，在另一个文件中创建了 getTasks 函数。两者都访问数据库，返回相同的数据。一个是在早期创建的，另一个是在Claude忘记第一个时创建的。

冲突的类型定义。 TypeScript 项目会积累重复的类型定义。Claude 在一个文件中创建了 Task 类型，在另一个文件中创建了相同的 TaskType。两者描述相同的数据结构，且彼此不互相导入。

冗余的工具函数。字符串格式化函数、日期解析函数、验证辅助函数。Claude 在需要时创建它们，而不检查是否已存在。

对于每组重复代码，选择更好的版本（通常是更完整的那个），删除其他版本，并更新所有导入。告诉 Claude："将这些重复的工具合并到 src/lib/utils.ts 的单个文件中。更新整个代码库中的所有导入。"

合并后，再次运行测试。如果通过，你就减少了文件数量，并使未来的每个 Claude 会话更高效，因为需要读取的文件更少了。

重复代码的真实成本

这里有一个具体例子说明重复代码如何浪费 token。假设你在 src/utils/dates.ts 中有 formatDate，在 src/components/TaskCard.tsx 中有 formatTimestamp。它们功能相同，只是名称略有不同。

当你要求 Claude"更改整个应用中日期的显示方式"时，未经清理的情况是这样的：Claude 读取两个文件，找到两个日期格式化函数。它不知道哪个是标准版本，于是同时更新两者。如果它们签名略有不同，Claude 可能会引入不一致。而且你为 Claude 读取和修改两个文件支付了费用，而实际上一个文件就足够了。

经过清理后：只有一个 formatDate 在 src/lib/utils.ts 中。Claude 读取一个文件，进行一次更改，更新会传播到所有地方，因为所有内容都从同一来源导入。token 成本减半，不一致的可能性为零。

在一个月的日常开发中，这累积起来。与典型的 Claude 生成冗余项目相比，一个没有重复代码的干净项目大约能节省 20-30% 的 token 使用量。这还不包括其他的优化。节省效果是叠加的。

组织文件结构

Claude 对文件组织没有强烈偏好。它会根据你的项目结构，把文件放在它认为合适的位置。久而久之，这会导致一个扁平文件夹里堆满二十个文件，而不是按逻辑分组形成嵌套结构。

查看你的 src 目录。所有文件是否都在一个文件夹里？组件、工具函数、类型定义和服务器操作是否混在一起？

以下是我在 Next.js 项目中使用的结构：

bash 复制代码

 src/
├── app/                 （页面、布局、路由）
├── components/          （UI 组件）
│   ├── ui/              （通用组件：Button、Input、Card）
│   └── tasks/           （功能特定组件：TaskList、TaskForm、TaskCard）
├── lib/                 （工具函数、辅助方法、共享逻辑）
├── types/               （TypeScript 类型定义）
└── actions/             （服务器操作）

告诉 Claude："将项目文件重新组织成这个结构。把组件移到相应的子文件夹。把工具函数移到 lib/。把类型定义移到 types/。更新所有导入路径。不要更改任何功能。"

Claude 会移动文件并更新项目中所有导入语句。运行你的测试。如果测试通过，你的项目现在就是按用途组织，而不是按创建日期排列了。

为什么组织对 Claude Code 很重要？因为 Claude 读取文件的方式。当你让 Claude"在任务卡片上添加一个按钮"时，它需要找到任务卡片组件。在包含二十个文件的扁平结构中，Claude 可能要读取五个文件才能找到正确的那个。而在有组织的结构中，它会直接进入 src/components/tasks/TaskCard.tsx。读取的文件越少 = 消耗的 token 越少 = 响应速度越快。

用新结构更新你的 CLAUDE.md 文件，这样未来的对话就不会打乱你的组织：

文件结构

bash 复制代码

 src/
├── app/                 （仅包含页面和布局）
├── components/
│   ├── ui/              （通用可复用组件）
│   └── tasks/           （任务特定组件）
├── lib/                 （工具函数和共享逻辑）
├── types/               （TypeScript 类型定义）
└── actions/             （用于数据库操作的服务器操作）

精简组件臃肿

Claude 有时会构建比实际需要更大的组件。一个任务卡片组件可能同时处理渲染、状态切换、删除、编辑和动画，全部塞在一个 200 行的文件里。这本身没错，但成本很高。每次 Claude 因任何原因读取该文件时，它都要读取全部 200 行。

告诉 Claude："检查项目中的每个组件。如果任何组件超过 100 行，建议如何将其拆分为更小、更专注的组件。并实施拆分。"

这个目标并非随意设定，而是出于实用考虑。更小的组件意味着 Claude 每项任务读取的内容更少。如果你让 Claude"更改状态徽章的颜色"，它只需读取 StatusBadge 组件，而不必读取包含它的整个 TaskCard。

拆分后，你的组件数量会增加，但文件大小会减小。最终效果：Claude 工作更快，因为它只读取所需内容，忽略其余部分。

何时不拆分

并非所有大文件都需要拆分。有些文件之所以大，是因为它们实现的功能本身就比较复杂。你的主页面组件可能负责协调任务获取、筛选、排序和渲染，有 150 行，这完全没问题。把它拆成四个 40 行的组件，可能会增加比节省更多的复杂性，因为现在 Claude 需要读取四个文件并理解它们之间的关系，而不是一次读取一个文件并理解所有内容。

规则是：当组件执行多个不相关的操作时（渲染 + API 调用 + 状态管理 + 动画），就拆分。当组件执行一个自然内聚的复杂操作时，就不要拆分。

问 Claude："对于每个超过 100 行的组件，告诉我：这个组件是在做多个不相关的事情（建议拆分），还是做一件复杂的事情（保持原样）？"Claude 在这方面的判断通常不错，因为它能分析代码结构并识别不同的关注点。

重构模式 Claude Code 擅长处理

在我们清理代码的同时，有一些重构模式是 Claude 能够可靠执行并提升代码库质量的。

提取常量。魔法数字和硬编码字符串散落在代码各处。告诉 Claude："找出所有魔法数字和硬编码字符串。将它们提取为命名常量，放在每个文件顶部或共享常量文件中。"好处是：当你需要将任务标题最大长度从 200 字符改为 300 字符时，只需修改一个常量，而不用在五个文件中逐一查找。

类型推断清理。 Claude 有时会在 TypeScript 能推断类型的地方添加显式类型注解，有时又会遗漏能提高可读性的注解。告诉 Claude："审查类型注解。移除 TypeScript 能推断的冗余注解。为当前依赖隐式 any 的函数签名添加显式注解。"

导入整理。经过多个阶段的编写，你的导入语句可能已经一团糟。有些文件从同一目录导入了五次，每行一个。有些存在未使用的导入，而 TypeScript 并未将其标记为错误。告诉 Claude："整理每个文件中的导入。按以下分组：先外部包，再本地导入，最后相对导入。移除所有未使用的导入。尽可能使用项目的路径别名。"

这三项重构各需约五分钟，能让代码库明显更整洁。它们都不改变功能，因此破坏代码的风险几乎为零。

CLAUDE.md 审计

你的 CLAUDE.md 文件在多个阶段中不断增长。审查它。移除过时的内容（关于已重构功能的规则、已移动文件的引用）。添加缺失的内容（新的文件结构、已建立的模式）。

整洁的 CLAUDE.md 就像整洁的桌面。它从第一条消息起就设定了正确的上下文。杂乱的 CLAUDE.md 包含矛盾的规则或已删除文件的引用，会混淆 Claude 并浪费令牌处理无关上下文。

告诉 Claude："审查 CLAUDE.md 文件。移除不再适用于当前代码库的任何规则或引用。添加我们已建立的架构模式。保持简洁。"

以下是经过一段时间开发后，一个成熟的 CLAUDE.md 示例：

bash 复制代码

 # 项目
个人任务管理应用。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 和认证的服务器操作

## 设计
遵循 design-system.md。所有样式通过 Tailwind 实现。

## 规则
- 新功能在合并前需要测试
- 每周运行 npm audit
- 架构投入最大精力，功能投入中等，编辑投入最低

注意其中没有的内容：冗长的解释、重复的描述、过时的引用。每一行都物有所值。30 行以内的 CLAUDE.md 几乎总是优于 60 行以上的。

规模与性能曲线

这里有个没人提及的问题：随着项目规模增大，Claude Code 会变慢。这不是因为 Claude 的技术限制，而是由于文件读取和上下文窗口的工作方式。

10 个文件时，Claude 能在几秒内读取整个项目。上下文窗口有足够空间容纳所有内容。响应快速且准确，因为 Claude 能把握全局。

50 个文件时，Claude 会选择性读取。它挑选认为相关的文件。有时选错，需要第二次尝试。响应仍然不错，但偶尔会遗漏 Claude 未读取文件中的上下文。

200 个文件时，Claude 会策略性读取。它严重依赖文件名、目录结构和你的 CLAUDE.md 来导航。如果结构清晰，Claude 能快速找到所需内容。如果结构混乱，Claude 会读取十个文件才能找到目标，而你为这十个文件都付出了代价。

500 个以上文件时，Claude 需要 LSP、强大的 CLAUDE.md 和清晰的结构才能有效工作。缺少这些，每个任务都会从昂贵的探索阶段开始，Claude 会逐个读取文件试图定位。

项目目前大约有 30-40 个文件。这正处于清理工作影响最大的黄金阶段。从 40 个文件减少到 30 个，意味着 Claude 可能需要扫描的文件减少了 25%。而在 200 个文件时，同样的减少量（190 到 180）仅占 5%。趁早清理，趁影响比例还大。

这也是为什么的".claudeignore"文件如此重要。如果你的项目有40个TypeScript文件和500个node_modules文件，.claudeignore比其他任何优化都更有效。这不仅仅是关于token数量，而是关乎Claude能否聚焦于真正重要的内容。

何时重构 vs. 何时重写

有时清理会暴露出更深层的问题：项目的架构与已构建的功能不匹配，数据库模式向三个不同方向扩展，组件层级关系颠倒（父组件获取本应由子组件拥有的数据）。

此时你面临选择：重构架构（代价高、风险大），或者吸取教训启动新项目（代价不同但更干净）。

对于项目来说，答案始终是重构。这是一个小型项目，架构问题可控，并且你有测试来捕捉回归错误。

对于更大的项目（读完本文后的下一个项目），以下是决策框架：

重构条件： - 整体架构合理但细节混乱 - 需要修改的代码少于30% - 你有覆盖关键路径的测试 - Claude能在2-3次对话中完成重构

重写条件： - 基础数据模型错误（错误的数据库表、错误的关系） - 需要修改的代码超过50% - 没有测试，无法验证重构是否破坏功能 - 项目积累了太多死代码，重构比重建更困难

八个月里我重写了两个项目。两次重写所花时间都比重构要少，因为我用第一次尝试中学到的经验，以干净的架构重新构建。代码更好了，CLAUDE.md更完善了，文件结构从一开始就是正确的。

不要把重写视为失败，而是当作第二稿。作家经常扔掉第一稿，开发者也应该如此。

衡量影响

在清理前后，衡量Claude的性能表现：

开始一次对话，要求Claude："为每个任务卡片添加'最后修改'时间戳。"记录所需时间以及Claude读取的文件数量。

然后在清理后，用新的对话执行相同任务。差异应该很明显：读取的文件更少、响应更快、token使用量更低。

如果你在设置了LSP，那么LSP+有序结构+无死代码的综合效果非常显著。Claude能在毫秒级找到所需内容，只读取相关文件并生成修改。让初学者感到沮丧的"Claude反应慢"体验，几乎完全是项目臃肿的症状，而非工具本身的限制。

月度清理例行程序

不要等到项目达到22万行代码才清理。养成每月习惯：

运行死代码分析（5分钟）
检查重复工具函数（5分钟）
审查文件结构（5分钟）
更新 CLAUDE.md（5分钟）
运行 npm audit 进行安全审计（，2分钟）
运行完整测试套件（1分钟）

每月23分钟。回报是：一个保持快速、整洁且成本低廉的项目。这正是用 Claude Code 构建一个项目的人与构建十个项目的人之间的区别。构建十个项目的人有清理流程，而构建一个项目的人则留下一团22万行的混乱。

把这个流程记到日历里。每月第一个星期一。"Claude Code 清理：无效代码、重复内容、结构、CLAUDE.md、审计、测试。"如果你跳过一次，就会忘记。如果你跳过三次，技术债务会累积到让清理变成一个大项目，而不是一项20分钟的小事。我在第二个 Claude Code 项目上吃了这个苦头------连续两个月跳过清理，结果花了一整个下午来理顺那些已经分化的重复工具函数。

回顾：Claude 没有眼睛。Claude 没有记忆。它看不到你的用户界面，也记不住你的文件结构。你需要通过提供截图和整洁有序的项目来弥补这两点。这两个变通方法能让 Claude Code 感觉像一位资深开发者，而不是一个困惑的实习生。

构建步骤

清理并整理你的项目代码库。

运行无效代码分析：让 Claude 查找未使用的导入、未调用的函数和孤立文件
审查并确认无效代码列表，然后删除确认的项目
运行重复代码分析：查找不同文件中功能相同的函数
将重复内容整合到共享工具文件中
将文件结构重新组织到逻辑文件夹中（components/ui、components/tasks、lib、types、actions）
重新组织后更新所有导入路径
用新的文件结构和当前项目规则更新 CLAUDE.md
运行完整测试套件以验证没有东西损坏

检查点：清理后测试通过。项目文件数量比之前更少。文件结构遵循清晰的组织模式。CLAUDE.md 反映了项目的当前状态。

交付物：一个精简有序的代码库，附带可每月重复的维护流程。Claude Code 在后续每个任务上的响应速度更快，因为需要阅读的噪音更少。

你的应用运行正常、外观良好、运行成本降低一半、具备高级功能、通过安全审计，并且现在整洁有序。Claude 在此代码库上响应任务的速度比清理前快了一倍。这种改进将延续到你从今往后执行的每一个任务中。

构建阶段还剩一件事：让它赚钱。你已经花了40小时来构建、打磨、优化、增强、保护和清理一个应用。在接下来的6小时里，你将给它加上价格标签和一扇前门。，它将不再只是一个项目，而是开始成为一个产品。