在大型代码库中，找到目标比修改它更难。Claude Code 提供四层搜索策略，从精确匹配到语义理解逐层递进。

搜索分层策略

CLAUDE.md 作为代码库地图

在大型项目中，CLAUDE.md 不仅是配置文件——它是代码库地图。 在其中描述项目的目录结构、核心模块职责和模块间依赖关系，Claude 就能跳过漫长的探索阶段，直接定位目标。

# CLAUDE.md — 大型项目的架构速写

## Architecture
src/core/        — 核心业务逻辑（纯函数，无副作用）
src/adapters/    — 外部服务适配层（DB、API、MQ）
src/handlers/    — HTTP/gRPC 请求处理
src/shared/      — 跨模块共享类型和工具函数

## Key Patterns
- 所有数据库操作必须通过 src/adapters/db/ 中的 Repository
- Handler 不直接导入 core，通过 src/services/ 中转
- 共享类型定义在 src/shared/types/，禁止循环引用

重命名一个被 200 个文件引用的函数——Claude Code 的 Edit 工具和 Bash 脚本协同完成这种精密的跨文件手术。

重构工作流

实战：跨文件重命名

场景：将 getUserData 重命名为 fetchUserProfile，该函数被 87 个文件引用。

# Step 1 — 定位范围：有多少文件受影响？
$ grep -rn "getUserData" src/ --include="*.ts" | wc -l
143   # 143 处引用，分布在 87 个文件中

$ grep -rl "getUserData" src/ --include="*.ts" | wc -l
87    # 确认 87 个文件

# Step 2 — 分类：定义处 vs 引用处
$ grep -rn "export.*getUserData\|function getUserData" src/
src/services/user.ts:42: export async function getUserData(id: string)
src/services/user.ts:89: export function getUserData.cached(...)

对 Claude 下达精确指令：

# 给 Claude 的 Prompt
把 getUserData 重命名为 fetchUserProfile。
规则：
1. 先修改 src/services/user.ts 中的定义和导出
2. 然后修改所有 import 语句
3. 最后修改所有调用处
4. 每修改一个文件后用 grep 确认该文件无残留
5. 全部完成后运行 npm run typecheck 确认零错误

三种重构模式

从 JavaScript 到 TypeScript、从 REST 到 gRPC、从 Class 组件到 Hooks——大规模迁移需要分阶段执行，用 Worktree 隔离风险。

迁移策略对比

实战：JS → TypeScript 增量迁移

# Phase 1 — 基础设施（在 Worktree 中隔离）
$ claude --worktree ts-migration

# 在隔离环境中初始化 TypeScript 配置
claude> 为这个 JS 项目添加 TypeScript 支持：
        1. 创建 tsconfig.json，设置 allowJs: true
        2. 安装 typescript 和 @types/node
        3. 先不转换任何文件，确保 tsc --noEmit 通过

# Phase 2 — 类型定义
claude> 在 src/types/ 下创建共享类型定义文件：
        - User, Product, Order 等核心实体类型
        - API 请求和响应的类型
        从现有代码的 JSDoc 和运行时形状推断类型

# Phase 3 — 逐模块转换
claude> 把 src/utils/ 下所有 .js 文件转换为 .ts：
        - 添加类型注解
        - 保持导出签名不变
        - 每转换一个文件后运行 tsc --noEmit 确认
        - 如果有循环依赖，报告但不修改

Worktree 隔离机制

把一个 3000 行的 utils.ts 拆成六个聚焦模块、把单体应用拆分为分层架构——这类手术需要 Plan 模式先规划，再精确执行。

Plan 模式：先规划再动手

对于架构级变更，永远先进入 Plan 模式（Shift+Tab 两次）。 让 Claude 分析代码库结构、识别模块边界、发现隐藏的依赖关系，然后输出一份可审核的执行计划—— 你审批后再执行。

# 典型的架构重组 Prompt
claude> 分析 src/utils.ts（3200 行），提出拆分方案：
        1. 识别内聚的函数组（按用途分类）
        2. 分析函数间的调用关系（哪些必须同组）
        3. 输出拆分方案：每个新模块的文件名、包含的函数、预计行数
        4. 列出所有需要更新 import 的文件
        先给我方案，不要执行

模块拆分流程

// utils/index.ts — Barrel export 保持向后兼容
export * from './string-utils';
export * from './date-utils';
export * from './validation';
export * from './http-helpers';
export * from './crypto';
export * from './file-io';

// 所有原有的 import { xxx } from './utils' 无需修改

当一个任务太大、太复杂，一个上下文窗口装不下时——把它拆成子任务，分发给专业的 Agent 并行执行。

Agent 类型

并行 Agent 编排

Claude Code 可以在一次回复中同时分发多个 Agent。 配合 isolation: "worktree"，每个 Agent 在独立的 Git Worktree 中工作，彼此不会产生文件冲突。

上下文保护策略

1. 在大型代码库中，搜索分层策略的四个层次是什么？各自的适用场景？
2. 使用 Edit 工具进行跨文件重命名时，replace_all: true 参数的作用是什么？有什么限制？
3. 增量迁移和 Strangler 模式的核心区别是什么？各自在什么场景下优先选择？
4. Worktree 隔离解决了 Agent 并行执行中的什么问题？无 Worktree 的 Agent 会有什么风险？
5. 为什么架构重组应该先进入 Plan 模式？直接让 Claude 执行拆分会有什么潜在问题？