为什么多文件编辑重要
改一个接口名，可能涉及 controller、service、DTO、测试、前端调用 5+ 个文件。手动改容易漏，Claude Code 一次搞定。
实战：重命名一个 API
> 把 getUserList 改名为 fetchUsers，所有引用的地方都改掉
Claude Code 的执行步骤：
- 用 Grep 搜索所有包含
getUserList的文件 - 分析每处引用的上下文（是函数定义、import、还是调用）
- 逐个文件用 Edit 工具替换
- 检查 import 路径、类型定义是否需要联动调整
- 展示所有修改的 diff，等你确认
你可以按 y 逐个确认，也可以切换到 auto-accept 模式（Shift+Tab 两次）一次性应用。
实战：批量加错误处理
> 检查 src/services/ 下所有 fetch 调用，没有 try-catch 的都加上，
> 错误统一用 toast.error() 提示用户
这类跨文件的模式化修改是 Claude Code 的强项。它能识别每个 fetch 调用的上下文，根据已有的错误处理模式生成一致的代码。
手动做要半小时的事情，Claude Code 通常 2 分钟搞定。
实战：类型重构
TypeScript 项目中类型变更是最头疼的多文件修改之一：
> User 类型里的 name 字段拆成 firstName 和 lastName，
> 所有用到 user.name 的地方都改成 `${user.firstName} ${user.lastName}`
Claude Code 会处理：
- 类型定义文件（
types.ts） - API 响应解析（
services/user.ts） - 组件 props 传递（
components/UserCard.tsx） - 测试文件里的 mock 数据（
__tests__/user.test.ts）
实战：React 组件改名（5 文件联动）
这是最典型的 React 多文件重构场景：把 UserCard 组件改名为 MemberCard。看起来简单，但涉及的文件比你想象的多：
src/components/UserCard.tsx— 组件文件本身（含 interface 名）src/components/index.ts— barrel export（重命名后 export 路径变了）src/pages/Dashboard.tsx— 引用处 1src/pages/Profile.tsx— 引用处 2src/__tests__/UserCard.test.tsx— 测试文件（文件名 + 内部引用都要改）
给 Claude Code 一句话：
> 把 UserCard 组件改名为 MemberCard，文件也一起重命名，所有 import 和测试都联动改
Claude Code 实际执行的每步 diff：
① 组件文件 → 重命名 + 内部 interface
// src/components/UserCard.tsx → src/components/MemberCard.tsx
-interface UserCardProps {
+interface MemberCardProps {
user: User
onEdit?: () => void
}
-export function UserCard({ user, onEdit }: UserCardProps) {
+export function MemberCard({ user, onEdit }: MemberCardProps) {
return (
- <div data-testid="user-card" className={styles.userCard}>
+ <div data-testid="member-card" className={styles.memberCard}>
...
</div>
)
}
② barrel export
// src/components/index.ts
-export { UserCard } from './UserCard'
+export { MemberCard } from './MemberCard'
export { Avatar } from './Avatar'
export { Badge } from './Badge'
③ 调用方（Dashboard + Profile）
// src/pages/Dashboard.tsx
-import { UserCard } from '@/components'
+import { MemberCard } from '@/components'
-<UserCard user={currentUser} onEdit={handleEdit} />
+<MemberCard user={currentUser} onEdit={handleEdit} />
④ 测试文件 → 文件名 + 内部引用 + testid
// src/__tests__/UserCard.test.tsx → src/__tests__/MemberCard.test.tsx
-import { UserCard } from '@/components'
+import { MemberCard } from '@/components'
describe('MemberCard', () => {
it('renders user info', () => {
- render(<UserCard user={mockUser} />)
+ render(<MemberCard user={mockUser} />)
- expect(screen.getByTestId('user-card')).toBeVisible()
+ expect(screen.getByTestId('member-card')).toBeVisible()
})
})
注意最后一行：data-testid 的值也被识别出来需要改。这不是简单的字符串 find-replace，Claude Code 理解了组件和测试之间的语义绑定关系，知道 "user-card" 这个 testid 属于这个组件，需要一起重命名。
改完之后在 terminal 跑：
npx tsc --noEmit && npx vitest run
5 个文件，0 TypeScript 编译错误，测试全绿。手动改大概要 10-15 分钟，而且几乎肯定会漏掉 testid 这种细节；Claude Code 大概 90 秒，不漏。
用 @ 快速引用文件
在提问时用 @ 引用文件，Claude Code 直接读取内容，不用你手动打开：
> @src/types/user.ts 和 @src/services/api.ts 之间的类型定义有没有不一致的地方？
引用目录也行：
> @src/components 这个目录里有没有没用到的组件？
用 CLAUDE.md 控制编辑行为
在项目根目录放一个 CLAUDE.md，写上你团队的编码规范：
# CLAUDE.md
- 错误处理统一用 try-catch + toast.error()
- API 调用统一放 services/ 目录
- React 组件用 TypeScript + CSS Modules
- 测试用 Vitest + React Testing Library
- import 排序: 第三方库 > 内部模块 > 相对路径
Claude Code 每次启动都会读这个文件，在做多文件编辑时自动遵守这些规范。团队成员把 CLAUDE.md 提交到 git 里，所有人共享同一套规则。
控制修改范围
有时候你只想改一部分文件，可以明确指定范围：
> 只改 src/api/ 目录下的文件，把所有 axios 调用换成 fetch
> 不要动测试文件
Claude Code 会严格遵守你给的范围限制。如果操作涉及范围外的文件（比如 import 需要调整），它会告诉你而不是直接改。
也可以反过来，排除特定目录：
> 全局把 moment.js 换成 dayjs，但 src/legacy/ 目录先别动
这种精细化控制在大型 monorepo 里特别有用——你可以逐模块推进重构，而不是一次改动几百个文件让 PR review 成噩梦。