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

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

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

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)

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)

// 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

# 매 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

# 매 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)

# .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

draft = claude.refactor(code)
critique = claude.review(draft, focus="correctness, edge cases")
final = claude.apply(critique)

8) Verification matrix

# 매 매 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
• 응용: 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