10.1 理解文件上下文管理

# 模拟交易

print(f"Processing {method} payment for ${amount}")

return True

然后，你可以向 Claude 提供依赖文件的摘要，而不是整个源代码：

# 上下文摘要（用于 Claude 提示）

- user.py 定义了 User 类，包含字段：id, membership_level

- product.py 定义了 Product 类，包含 price, stock

- helpers.py 定义了 calculate_discount(price, membership_level)

然后向 Claude 提示：

"根据此上下文，审查 process_payment() 并就错误处理和可扩展性提出改进建议。"

Claude 将通过此摘要分析依赖关系，推断可能存在的问题，而无需每个模块的完整文本。

澄清表：上下文管理策略

有效地管理文件上下文，使 Claude 能够像阅读整个项目一样在大型代码库中进行推理——而绝不会超出 token 限制或失去精确性。掌握此过程的开发人员能够将 AI 编码辅助扩展到企业级项目，同时保持提示快速、高效且经济实惠。

随着我们继续前进，下一节将演示多文件协作技术，其中 Claude 可以在单个工作流程中跨多个模块审查、重构和同步更改——这是使用复杂、相互依赖系统的团队的关键能力。

10.2 总结和导航大型代码库

开发人员在处理大型项目时面临的最大挑战之一，就是简单地理解一切所在的位置——哪些文件定义了核心逻辑，哪些文件保存配置，哪些文件负责实用程序或测试。Claude Code 擅长通过摘要和上下文导航帮助开发人员理解此类复杂环境。通过智能地阅读和描述代码结构，Claude 使你能够即时获得对数千行代码的可见性，使入职、调试或重构变得无比轻松。

在本节中，我们将探讨如何使用 Claude Code 高效地总结代码库、生成清晰的概述以及跨模块导航而不会丢失上下文。你将看到实用的工作流程，将冗长、令人困惑的代码库转换为可以在几秒钟内进行推理的整齐摘要蓝图。

概念开发

Claude 的优势在于结构化摘要——将代码和文档转换为保留意图、逻辑和关系的自然语言摘要。对于大型项目，这有助于你快速回答关键问题：

• 每个文件的用途是什么？
• 函数和类如何连接？
• 依赖项或配置源自哪里？

Claude 通过迭代式上下文阅读来实现这一点。你可以一次向其输入一个目录或模块，提示其用通俗英语描述功能，而不是一次性加载整个项目。然后，这些摘要可以组合成系统的项目范围"地图"。

精心设计的摘要工作流可改善开发的每个阶段。在新开发人员入职时，他们可以使用 Claude 生成简洁的概述，而不是手动探索文件。在重构期间，你可以要求 Claude 跨多个模块追踪依赖关系以确保一致性。而在调试时，通过让 Claude 概述受影响组件周围的结构，你可以更快地隔离问题区域。

动手示例：使用 Claude 总结大型项目

假设你正在使用一个中等规模的 Python Web 应用程序，其结构如下：

project/

│

├── api/

│ ├── routes/

│ │ ├── users.py

│ │ └── payments.py

│ └── middleware/

│ └── auth.py

│

├── services/

│ ├── database.py

│ └── notifications.py

│

└── main.py

你可以使用 Claude 来总结它们的用途和关键内容，而不是手动打开每个文件。下面是一个实用的 Python 脚本，它读取目录中的所有 .py 文件并准备适合 Claude 提示的结构化摘要。

import os

def gather_code_snippets(root_dir, max_lines=30):

    """从每个文件收集短代码片段以进行摘要。"""

    code_summary = {}

    for root, _, files in os.walk(root_dir):

        for file in files:

            if file.endswith(".py"):

                path = os.path.join(root, file)

                with open(path, "r", encoding="utf-8") as f:

                    lines = f.readlines()

                    snippet = "".join(lines[:max_lines])

                    code_summary[path] = snippet

    return code_summary

def generate_summary_prompt(code_summary):

    """生成结构化提示以发送给 Claude。"""

    sections = []

    for path, snippet in code_summary.items():

        sections.append(f"File: {path}\n{snippet}\n\n---")

    return "\n".join(sections)

if __name__ == "__main__":

    project_root = "./project"

    code_data = gather_code_snippets(project_root)

    prompt = generate_summary_prompt(code_data)

    print("=== Claude Prompt ===\n")

    print(prompt)

这个脚本会从每个 .py 文件中收集开头几行（例如导入语句、文档字符串或类定义），并创建一个结构化的文本块。然后你可以将其粘贴到 Claude Code 中，配合一个简单的提示词，例如：

"总结每个文件的作用，并根据导入、类定义和函数名描述它们之间的交互方式。"

Claude 会生成一个清晰的层次化描述，例如：

总结：

• main.py 初始化 API 路由并启动 FastAPI 服务器。
• api/routes/users.py 处理用户账户的 CRUD 操作。
• api/routes/payments.py 实现支付逻辑并关联到通知模块。
• services/database.py 管理与 PostgreSQL 的连接和查询。
• middleware/auth.py 为受保护的路由添加基于 JWT 的身份验证。

从这里开始，你可以继续以交互式的方式进行导航：

"Claude，展示一下 payments.py 中哪些函数调用了 notifications.py，以及它们是如何通信的。"

Claude 会追踪函数级别的交互，从而以对话式的方式有效地导航项目。

说明表：常见的总结提示词

使用 Claude Code 对大型代码库进行总结和导航，将过去数小时的手动探索转变为数分钟的结构化推理。通过精心组织代码片段并使用有针对性的提示词，你无需无止境地滚动文件，就能获得系统的完整心智模型。

更重要的是，Claude 的总结超越了语法层面 —— 它保留了意图，帮助团队理解代码存在的原因，而不仅仅是它做了什么。这种能力在新员工入职、审计或重大重构期间尤其有价值。

在下一节中，我们将在此基础上探索多文件推理，其中 Claude 不仅会总结文件，还能同时主动编辑、同步和重构多个模块，同时在整个项目中保持逻辑一致性。

10.3 增量重构与文档编写

重构是软件工程中最有价值但也最耗时的方面之一。它涉及改进代码的结构和清晰度，而不改变其外部行为。然而，在大型项目中，全规模的重构可能变得令人难以承受 —— 它们有破坏功能、引入不一致或导致合并冲突的风险。这正是 Claude Code 增量重构能力真正发挥作用的地方。

Claude 擅长以小型、可控的步骤执行重构，使开发者能够在保持稳定性的同时实现代码库现代化。它不仅有助于重写函数、重命名变量和重组类，还能自动记录每次更改背后的推理。这种技术精确性与自我文档化的结合，创造了更干净、更易维护的代码，团队可以信任并随时间演进。

在本节中，我们将探讨如何使用 Claude Code 增量重构大型代码库，如何在这些更改过程中维护文档，以及如何确保每个重构都保留其功能。

概念阐述

使用 Claude Code 进行增量重构围绕三个原则构建：范围、验证和可追溯性。

1. 范围 — 始终在明确定义的边界内进行重构。与其要求 Claude "重构整个项目"，不如一次专注于一个模块、类或函数。当 Claude 获得简洁的上下文和明确的目标时（例如"为异步性能优化 DatabaseClient"），它的表现最佳。
2. 验证 — 每个重构都应立即进行测试或验证。Claude 可以生成甚至推理出验证修改后代码行为的测试，从而降低回归风险。
3. 可追溯性 — Claude 所做的每项更改都可以附带自动生成的文档 —— 文档字符串、提交信息或变更日志。这确保未来的开发者理解更改的原因，而不仅仅是更改了什么。

这些原则使 Claude Code 成为持续改进工作流程的理想伴侣，使代码能够优雅地演进，而不是通过大规模破坏性的重写来实现。

动手实践：使用 Claude 进行逐步重构

让我们从一个简单的例子开始 —— 一个处理用户身份验证的遗留类，但它混合了过多的职责。