Claude Code 重构工作流完全指南：从小步重构到大规模改造的 AI 协作之道

> 分析 src/legacy/ 目录的代码质量：
> 1. 有多少文件超过 300 行？函数平均复杂度如何？
> 2. 有多少 any 类型？测试覆盖率大概多少？
> ��我一个"重构 vs 重写"的建议。

# 先看覆盖率
> 跑一下测试覆盖率，重点看我要重构的 components/Navigation.tsx
 
# 覆盖率不够就先补
> Navigation.tsx 覆盖率只有 40%，帮我补充测试：
> - 桌面端导航链接渲染
> - 移动端 hamburger 菜单开关
> - 活跃链接高亮
> - Escape 键关闭菜单

# 方式一：普通分支
git checkout -b refactor/navigation-split
 
# 方式二：worktree 隔离（推荐）
git worktree add ../my-blog-refactor -b refactor/navigation-split

## 重构规范
- 每次只做一种类型的重构（不要同时重命名 + 拆分 + 改类型）
- 每步重构后必须通过所有现有测试
- 不改变公共 API 的行为签名
- 提取的工具函数：camelCase，放 lib/；组件：PascalCase，放 components/
- Commit: refactor: 结构调整 / refactor!: 有 breaking change

> 看一下 lib/posts.ts 的 getPostsByLocale 函数，
> 它现在做了太多事（读文件、解析 frontmatter、排序、分页）。
> 帮我把每个职责提取成独立函数，保持原函数作为编排层。

// Before: 一个 80 行的大函数
export function getPostsByLocale(locale: Locale, page?: number) {
  // 读取文件... 解析 frontmatter... 过滤排序... 分页... 生成元数据...
}
 
// After: 职责清晰的小函数 + 编排层
function readMdxFiles(locale: Locale): string[] { /* ... */ }
function parseFrontmatter(content: string): PostMeta { /* ... */ }
function sortByDate(posts: PostMeta[]): PostMeta[] { /* ... */ }
function paginate<T>(items: T[], page: number, perPage: number): PaginatedResult<T> { /* ... */ }
 
export function getPostsByLocale(locale: Locale, page: number = 1) {
  const files = readMdxFiles(locale)
  const posts = files.map(parseFrontmatter)
  const sorted = sortByDate(posts)
  return paginate(sorted, page, 10)
}

> lib/utils.ts 已经 500 多行了，里面有日期、字符串、URL、数组四类函数。
> 帮我拆成 lib/date.ts、lib/string.ts、lib/url.ts、lib/array.ts。
> 保留 lib/utils.ts 作为统一导出入口（re-export），更新所有 import。

> Navigation.tsx 现在 350 行，包含桌面导航、移动端菜单、主题切换。
> 帮我拆分成：
> - NavBar.tsx：外层容器 + 桌面端链接
> - MobileMenu.tsx：移动端 hamburger 菜单（含动画）
> - NavLink.tsx：单个导航链接（含 active 状态）
> 要求：用 props 传递数据，保持现有 aria 属性和键盘导航。

# 变量/函数重命名
> 把 lib/posts.ts 里的 getAllPosts 重命名为 getPostsByLocale。
> 更新所有引用（import、调用、测试、类型定义），列出所有被修改的文件。
 
# 文件重命名
> 把 components/Nav.tsx 重命名为 components/Navigation.tsx，更新所有 import。

# Step 1: 分析影响范围（先不改）
> 我想把 PostMeta 类型重命名为 PostFrontmatter。
> 先不要改，只告诉我这个类型在哪些文件中被使用，预计修改多少个文件。
 
# Step 2: 确认后执行
> 确认修改，每个文件改完后跑一次类型检查。
 
# Step 3: 验证
> 跑一下 tsc --noEmit 和 npm test，确认没有遗漏。

> 搜索项目中所有 any 类型，按分类统计（参数、返回值、变量、as any），
> 给每个 any 建议具体的替代类型。

// ❌ Before
function processData(data: any): any {
  const result: any = {}
  data.items.forEach((item: any) => { result[item.id] = item.value })
  return result
}
 
// ✅ After
interface DataItem { id: string; value: number }
interface DataInput { items: DataItem[] }
type ProcessedData = Record<string, number>
 
function processData(data: DataInput): ProcessedData {
  const result: ProcessedData = {}
  data.items.forEach((item) => { result[item.id] = item.value })
  return result
}

> 把 Notification 类型从普通 union 重构为 discriminated union，
> 按 type 字段区分，每种通知类型只包含它需要的字段。

// ❌ Before: 所有字段都是可选的
type Notification = {
  type: string; title: string; message?: string; progress?: number; error?: Error
}
 
// ✅ After: 每种类型精确定义
type Notification =
  | { type: 'info'; title: string; message: string }
  | { type: 'success'; title: string; message: string }
  | { type: 'progress'; title: string; progress: number }
  | { type: 'error'; title: string; error: Error }
 
// 类型收窄自动生效
function renderNotification(n: Notification) {
  switch (n.type) {
    case 'progress': return <ProgressBar value={n.progress} />  // TS 知道 progress 存在
    case 'error': return <ErrorMessage error={n.error} />       // TS 知道 error 存在
  }
}

// ❌ Before: 三个几乎一样的函数
async function fetchUsers(): Promise<ApiResponse<User[]>> {
  const res = await fetch('/api/users')
  if (!res.ok) throw new ApiError(res.status)
  return res.json()
}
// fetchPosts, fetchComments 也是一样的模式...
 
// ✅ After: 一个泛型函数
async function fetchResource<T>(endpoint: string): Promise<ApiResponse<T>> {
  const res = await fetch(`/api/${endpoint}`)
  if (!res.ok) throw new ApiError(res.status)
  return res.json()
}
 
const users = await fetchResource<User[]>('users')  // 类型安全

> getPostsByLocale 的返回值结构要改：
> 旧：{ posts: Post[], total: number }
> 新：{ data: Post[], meta: { total, page, perPage } }
> 帮我：创建新实现 V2，写 adapter 让旧函数调用新实现，加 @deprecated 标记。

// 新实现
function getPostsByLocaleV2(locale: Locale, options: QueryOptions): PaginatedResult<Post> {
  return { data: posts, meta: { total, page: options.page, perPage: options.perPage } }
}
 
// Adapter：旧接口 → 新实现
/** @deprecated 请使用 getPostsByLocaleV2，此函数将在 v3.0 移除 */
function getPostsByLocale(locale: Locale, page?: number) {
  const result = getPostsByLocaleV2(locale, { page: page ?? 1, perPage: 10 })
  return { posts: result.data, total: result.meta.total }
}

/**
 * @deprecated 自 v2.5.0 起废弃，将在 v3.0.0 移除。
 * 请使用 `formatDateTime(new Date('2026-03-21'), { style: 'short' })` 替代。
 */
function formatDate(date: string): string {
  if (process.env.NODE_ENV === 'development') {
    console.warn('[DEPRECATED] formatDate() → 请使用 formatDateTime()')
  }
  return formatDateTime(new Date(date), { style: 'short' })
}

# Step 1: 分析（Plan Mode）
> /plan 我要把状态管理从 Redux 迁移到 Zustand。
> 分析有多少 slice、多少组件用了 useSelector/useDispatch、有没有 middleware。
> 给我一个分步迁移计划。
 
# Step 2: 按模块逐个迁移
> 先迁移 userSlice：创建 Zustand store → 更新组件 → 跑测试 → 提交
 
# Step 3: 重复直到完成
> 继续迁移 postSlice...

# 终端 1: 重构用户模块
claude "把 stores/userSlice.ts 从 Redux 迁移到 Zustand，更新所有相关组件和测试"
 
# 终端 2: 重构文章模块
claude "把 stores/postSlice.ts 从 Redux 迁移到 Zustand，更新所有相关组件和测试"
 
# 终端 3: 重构评论模块
claude "把 stores/commentSlice.ts 从 Redux 迁移到 Zustand，更新所有相关组件和测试"

git worktree add ../blog-refactor-redux -b refactor/redux-to-zustand
cd ../blog-refactor-redux && claude  # 在隔离工作区中重构

# Redux → Zustand 迁移进度
 
| 模块 | 状态 | 组件数 | 测试 | 备注 |
|------|------|--------|------|------|
| userSlice | ✅ 已验证 | 8 | 通过 | - |
| postSlice | 🔄 进行中 | 12 | - | 有 middleware |
| commentSlice | ⬜ 待开始 | 5 | - | - |
| authSlice | ⬜ 待开始 | 6 | - | 依赖 userSlice |
| uiSlice | ⬜ 待开始 | 15 | - | 最多组件 |

# 重构前：确保测试通过
> 跑一下 Navigation 组件的所有测试，确认当前是绿的。
 
# 重构中：每步验证
> 我刚把 MobileMenu 提取成独立组件了，跑一下测试。
 
# 重构后：补充新测试
> 重构完成，帮我补充 NavBar、MobileMenu、NavLink 的独立测试。

describe('Navigation refactoring', () => {
  it('should render identically after refactoring', () => {
    const { container } = render(<Navigation locale="zh" pathname="/zh/blog" />)
    expect(container).toMatchSnapshot()
  })
})

git stash push -m "refactor attempt 1"   # 小改动：stash
git checkout main && git branch -D refactor/xxx  # 大改动：删分支重来
git reset --soft HEAD~3                   # 逐 commit 回退，保留改动

> 重构完成了，帮我跑一遍验证清单：tsc --noEmit → npm test → npm run lint → npm run build
> 每步结果告诉我，有问题就停下来。

## 命名规范
- 文件：组件 PascalCase / 工具函数 camelCase / 测试 同名.test
- 变量：组件 PascalCase / 函数 camelCase / 常量 UPPER_SNAKE_CASE
- 类型：PascalCase / 泛型 T, TData / Hook useCamelCase
- 布尔：is/has/should 前缀（isOpen, hasError）

## 文件组织
- 组件拆分后放同名目录：components/navigation/NavBar.tsx
- 每个组件目录必须有 index.ts 统一导出
- 共享类型放 types.ts，私有类型就近定义
- 文件大小限制：组件 250 行 / 工具函数 200 行 / 类型 150 行
- Import 顺序：React 内置 → 第三方 → 内部模块 → 相对路径 → 类型

## 重构 Commit
- refactor: 不改变行为的结构调整
- refactor!: 有 breaking change（需要 BREAKING CHANGE footer）
- 每个独立重构步骤一个 commit，不混合"提取"和"重命名"
- Message 格式：refactor(scope): 简短描述 + 详细说明为什么重构

# 重构规范
 
## 原则
- 小步重构，每步可验证
- 不改变公共 API 的外部行为
- 每步重构后必须通过所有测试
- 重构和功能修改不混在同一个 commit
 
## 流程
1. 确认测试覆盖率 ≥ 70%
2. 创建重构分支
3. 每步重构后跑 tsc + test
4. 用 /review 检查改动
5. 按步骤提交（每步一个 commit）
 
## 禁止事项
- 不要在重构 commit 中加新功能
- 不要删除测试（可以移动或重命名）
- 不要改变公共函数的签名（除非是 refactor!）
- 不要一次性重构超过 10 个文件（拆成多个 PR）

// components/Navigation.tsx — 350 行的单文件组件
'use client'
import { usePathname } from 'next/navigation'
import { useTranslations } from 'next-intl'
import { useState, useEffect, useRef } from 'react'
 
export default function Navigation({ locale }: { locale: Locale }) {
  const [isMenuOpen, setIsMenuOpen] = useState(false)
  // Escape 键关闭菜单 (20 行)
  // 点击外部关闭菜单 (15 行)
  // 自动聚焦第一个链接 (10 行)
  // 渲染桌面导航 (40 行)
  // 渲染移动端 hamburger (20 行)
  // 渲染移动端菜单面板 (60 行)
  // 渲染主题切换 + 语言切换 (30 行)
  return <nav>{/* 350 行的 JSX */}</nav>
}

> 分析 components/Navigation.tsx，我想拆分成更小的组件。
> 当前有哪些职责混在一起？建议拆成哪几个？Props 接口？状态放哪层？
> 先不要改代码。

> 在拆分前，帮我写测试覆盖当前行为：渲染所有链接、aria-current、hamburger 开关、Escape 关闭。

describe('Navigation', () => {
  it('renders all nav links', () => {
    render(<Navigation locale="zh" />)
    expect(screen.getByText('home')).toBeInTheDocument()
    expect(screen.getByText('blog')).toBeInTheDocument()
  })
 
  it('marks current page link as active', () => {
    render(<Navigation locale="zh" />)
    expect(screen.getByText('blog').closest('a')).toHaveAttribute('aria-current', 'page')
  })
 
  it('toggles mobile menu', () => {
    render(<Navigation locale="zh" />)
    fireEvent.click(screen.getByRole('button', { name: /openMenu/i }))
    expect(screen.getByRole('navigation')).toHaveClass('menu-open')
    fireEvent.keyDown(document, { key: 'Escape' })
    expect(screen.getByRole('navigation')).not.toHaveClass('menu-open')
  })
})

> 从 Navigation.tsx 中提取 NavLink 组件到 components/navigation/NavLink.tsx。
> Props: { href, label, isActive }，包含 active 样式和 aria-current。
> 在 Navigation.tsx 中使用新组件，跑测试确认。

// components/navigation/NavLink.tsx
import { Link } from '@/i18n/navigation'
 
interface NavLinkProps { href: string; label: string; isActive: boolean }
 
export default function NavLink({ href, label, isActive }: NavLinkProps) {
  return (
    <Link
      href={href}
      className={`nav-link ${isActive ? 'nav-link-active' : ''}`}
      aria-current={isActive ? 'page' : undefined}
    >
      {label}
    </Link>
  )
}

> 提交：refactor(navigation): extract NavLink into separate component

> 从 Navigation.tsx 中提取 MobileMenu 组件：
> Props: { items, isOpen, onToggle, onClose, pathname }
> 包含 Escape 关闭、自动聚焦的 useEffect，使用 NavLink 渲染链接。
> 保持所有 aria 属性和键盘导航。

// components/navigation/MobileMenu.tsx
'use client'
import { useEffect, useRef } from 'react'
import { useTranslations } from 'next-intl'
import NavLink from './NavLink'
import type { NavItem } from './types'
 
interface MobileMenuProps {
  items: NavItem[]; isOpen: boolean
  onToggle: () => void; onClose: () => void; pathname: string
}
 
export default function MobileMenu({ items, isOpen, onToggle, onClose, pathname }: MobileMenuProps) {
  const t = useTranslations('a11y')
  const firstLinkRef = useRef<HTMLAnchorElement>(null)
 
  // Escape 键关闭
  useEffect(() => {
    if (!isOpen) return
    const handler = (e: KeyboardEvent) => { if (e.key === 'Escape') onClose() }
    document.addEventListener('keydown', handler)
    return () => document.removeEventListener('keydown', handler)
  }, [isOpen, onClose])
 
  // 自动聚焦
  useEffect(() => { if (isOpen) firstLinkRef.current?.focus() }, [isOpen])
 
  return (
    <div className="md:hidden">
      <button onClick={onToggle} aria-label={isOpen ? t('closeMenu') : t('openMenu')}
        aria-expanded={isOpen} type="button">{/* hamburger icon */}</button>
      {isOpen && (
        <div className="mobile-menu" role="menu">
          {items.map((item) => (
            <NavLink key={item.href} href={item.href} label={item.label}
              isActive={pathname.includes(item.href)} />
          ))}
        </div>
      )}
    </div>
  )
}

> 最后一步：整理成干净的 NavBar，创建 index.ts 和 types.ts，更新所有 import。

// components/navigation/types.ts
export interface NavItem { href: string; label: string }
 
// components/navigation/NavBar.tsx — 整理后的主组件（~90 行）
'use client'
import { usePathname } from 'next/navigation'
import { useTranslations } from 'next-intl'
import { useState, useCallback } from 'react'
import NavLink from './NavLink'
import MobileMenu from './MobileMenu'
import ThemeToggle from '../ThemeToggle'
 
export default function NavBar({ locale }: { locale: Locale }) {
  const t = useTranslations('nav')
  const pathname = usePathname()
  const [isMenuOpen, setIsMenuOpen] = useState(false)
  const navItems: NavItem[] = [
    { href: '/', label: t('home') }, { href: '/blog', label: t('blog') },
    { href: '/projects', label: t('projects') }, { href: '/about', label: t('about') },
  ]
  const isActive = (href: string) =>
    href === '/' ? pathname === `/${locale}` : pathname.startsWith(`/${locale}${href}`)
 
  return (
    <nav className={`navbar ${isMenuOpen ? 'menu-open' : ''}`}>
      <div className="hidden md:flex items-center gap-6">
        {navItems.map(item => (
          <NavLink key={item.href} href={item.href} label={item.label} isActive={isActive(item.href)} />
        ))}
      </div>
      <MobileMenu items={navItems} isOpen={isMenuOpen}
        onToggle={useCallback(() => setIsMenuOpen(p => !p), [])}
        onClose={useCallback(() => setIsMenuOpen(false), [])} pathname={pathname} />
      <div className="flex items-center gap-2"><ThemeToggle /></div>
    </nav>
  )
}
 
// components/navigation/index.ts
export { default as Navigation } from './NavBar'
export { default as NavLink } from './NavLink'
export { default as MobileMenu } from './MobileMenu'

> 给拆分后的组件补充独立测试：NavLink、MobileMenu、NavBar 集成测试。

describe('NavLink', () => {
  it('applies active styles when isActive', () => {
    render(<NavLink href="/blog" label="Blog" isActive={true} />)
    expect(screen.getByText('Blog').closest('a')).toHaveAttribute('aria-current', 'page')
  })
})
 
describe('MobileMenu', () => {
  it('calls onClose when Escape is pressed', () => {
    const onClose = vi.fn()
    render(<MobileMenu items={[{ href: '/', label: 'Home' }]}
      isOpen={true} onToggle={vi.fn()} onClose={onClose} pathname="/zh" />)
    fireEvent.keyDown(document, { key: 'Escape' })
    expect(onClose).toHaveBeenCalled()
  })
})

> 跑完整验证：tsc --noEmit → npm test → npm run lint → npm run build
 
# ✓ tsc --noEmit — 零错误
# ✓ npm test — 24 tests passed（原 17 + 新增 7）
# ✓ npm run lint — 零警告
# ✓ npm run build — 构建成功

git log --oneline -5
# a1b2c3d refactor(navigation): add unit tests for NavLink and MobileMenu
# d4e5f6g refactor(navigation): reorganize NavBar as orchestration component
# h7i8j9k refactor(navigation): extract MobileMenu into separate component
# l0m1n2o refactor(navigation): extract NavLink into separate component
# p3q4r5s test(navigation): add baseline tests before refactoring