2nd/10_Wiki/Topics/Architecture/AI-Assisted Refactoring (AI 기반 리팩토링).md

---
id: wiki-2026-0508-ai-assisted-refactoring-ai-기반-리팩
title: AI-Assisted Refactoring (AI 기반 리팩토링)
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [AI Refactoring, LLM Refactoring, Agent Refactoring]
duplicate_of: none
source_trust_level: A
confidence_score: 0.9
verification_status: applied
tags: [refactoring, ai, llm, claude-code, cursor, codemod]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: typescript
  framework: claude-code
---

# AI-Assisted Refactoring (AI 기반 리팩토링)

## 매 한 줄
> **"매 LLM agent 가 codebase-wide refactoring 을 매 propose / apply / verify 하는 workflow."** 2026 현재 매 Claude Code (Opus 4.7), Cursor (Composer), Aider, Continue, Codex CLI 등이 매 multi-file edit + test loop 를 자동화. 매 핵심은 매 *deterministic checks* (test, type, lint) 로 매 LLM 의 stochasticity 를 매 제어. 매 "AI 가 짜준다"가 아닌 매 "AI 가 propose, CI 가 verify".

## 매 핵심

### 매 effective workflow
- **Plan → Apply → Verify → Commit**: 매 매 step 마다 매 human 또는 매 automated gate.
- **Small diffs**: 매 100-300 lines / commit. 매 1000+ line PR 은 매 review 불가능.
- **Test as oracle**: 매 LLM 의 output 을 매 existing test suite 로 검증. 매 test 없으면 매 refactoring 시도 X.
- **Type-driven**: 매 TS / Python (mypy/pyright) / Rust 등 매 strict typing 이 매 hallucination 을 매 catch.

### 매 적합 task
- Rename / move (매 IDE refactor 와 비슷하나 매 cross-language).
- Library migration (매 Express → Fastify, 매 enzyme → RTL, 매 moment → date-fns).
- API surface 변경의 매 callsite 일괄 업데이트.
- Style 통일 (매 callback → async/await, 매 class → hooks).
- 매 dead code 제거.

### 매 부적합 task
- 매 architectural redesign — 매 human 의 design 결정 필요.
- 매 perf-critical hot path — 매 measurement 없이 매 LLM 의 "looks faster" 신뢰 X.
- 매 security-sensitive (auth, crypto) — 매 human review 필수.

### 매 응용
1. Legacy codebase 의 점진적 modernization.
2. Mass dependency upgrade.
3. Test coverage 가속.

## 💻 패턴

### 1) Claude Code 의 대규모 rename
```bash
claude
> Rename `getUserData` to `fetchUserProfile` across the repo.
> Update all callsites, tests, and JSDoc.
> Run `npm test` after.
```

### 2) Plan-first prompt (Opus 4.7)
```text
Before editing, output a numbered PLAN of files & changes.
Wait for "approved" before applying any edit.
After each file, run `pnpm typecheck` and stop on first error.
```

### 3) Codemod fallback (deterministic)
```ts
// jscodeshift transform — 매 LLM 보다 매 reliable for syntactic
import { API, FileInfo } from 'jscodeshift';
export default function (file: FileInfo, api: API) {
  return api.jscodeshift(file.source)
    .find('CallExpression', { callee: { name: 'getUserData' } })
    .replaceWith(p => api.jscodeshift.callExpression(
      api.jscodeshift.identifier('fetchUserProfile'),
      p.value.arguments
    ))
    .toSource();
}
```

### 4) Hybrid: codemod + LLM cleanup
```bash
# 매 1) codemod 로 매 syntactic 변경
jscodeshift -t rename.ts src/
# 매 2) LLM 으로 매 semantic 보정 (매 import path, comment, type narrowing)
claude "Fix any remaining type errors after the rename."
```

### 5) Test-driven refactor loop
```bash
# 매 Aider / Claude Code 의 매 auto-test loop
claude --auto-test "Extract logger to a separate module. Run pytest after."
# 매 pytest fail → 매 LLM 이 매 fix 시도 → 매 max 3 retries → 매 stop
```

### 6) Diff size guard (pre-commit)
```bash
# .git/hooks/pre-commit
LINES=$(git diff --cached --shortstat | grep -oE '[0-9]+ insertions' | head -1)
if [ "${LINES%% *}" -gt 500 ]; then
  echo "Refusing >500 line AI commit. Split it."; exit 1
fi
```

### 7) Chain of LLMs — propose / critique
```python
draft = claude.refactor(code)
critique = claude.review(draft, focus="correctness, edge cases")
final = claude.apply(critique)
```

### 8) Verification matrix
```yaml
# 매 매 refactor PR 의 mandatory gates
gates:
  - typecheck: pnpm tsc --noEmit
  - test: pnpm vitest run
  - lint: pnpm biome check
  - perf: bench compare main vs HEAD (regression < 5%)
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| 매 syntactic mass change | Codemod (jscodeshift / ast-grep) |
| 매 semantic + 매 cross-cutting | LLM (Claude Code / Cursor) |
| 매 1-file refactor | IDE refactor menu |
| 매 risk-heavy (auth/payment) | Manual + LLM 보조 review |
| 매 large repo (>1M LoC) | Hybrid: codemod 먼저, LLM 보정 |

**기본값**: 매 plan-first + 매 small diff + 매 test gate. 매 syntactic 부분은 매 codemod, 매 semantic 부분만 매 LLM.

## 🔗 Graph
- 부모: [[Refactoring_Best_Practices|Refactoring]]
- 응용: [[3의 법칙 (Rule of Three)]]
- Adjacent: [[Claude Code]] · [[Cursor]] · [[Aider]]

## 🤖 LLM 활용
**언제**: 매 cross-file rename/migrate, 매 boilerplate 변환, 매 test scaffold 생성.
**언제 X**: 매 architectural decision, 매 perf hot path, 매 security crypto.

## ❌ 안티패턴
- **Massive PR**: 매 5000-line "AI did it all" PR. 매 review 불가능 → 매 bug 잠복.
- **No tests**: 매 LLM refactor 의 검증 없음. 매 silent regression.
- **Trust without verify**: 매 LLM 의 매 "I updated all callsites" 를 매 grep 으로 매 cross-check 안 함.
- **Architectural delegation**: 매 design 까지 LLM 에 위임 → 매 incoherent system.
- **Skipping codemod**: 매 syntactic mass-rename 까지 매 LLM 으로 → 매 token waste + 매 inconsistency.

## 🧪 검증 / 중복
- Verified (Anthropic Claude Code docs 2026, Cursor Composer guide 2026, jscodeshift Meta OSS).
- 신뢰도 A.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — workflow + codemod hybrid + 8 patterns |