VS Code 리팩터링 실전 가이드: F2 이름 변경부터 Code Actions까지

VS Code 실무 활용 시리즈

VS Code 리팩터링으로
코드를 안전하게 바꾸는 법

이름 변경부터 함수 추출, Quick Fix, 변경 미리보기까지 초보자도 따라 하는 Code Actions 실전 가이드

코드에서 변수 이름을 일일이 찾아 바꾸거나, 긴 로직을 복사해 새 함수로 옮기고 있나요? VS Code의 리팩터링과 Code Actions를 사용하면 언어 서비스가 코드 구조를 이해한 상태에서 관련 참조를 함께 수정하고, 적용 전 변경 범위도 확인할 수 있습니다.

목차

1. 리팩터링과 Code Actions 이해하기
2. 핵심 단축키 한눈에 보기
3. 안전하게 적용하는 기본 순서
4. 실전 예제 1: 프로젝트 전체 이름 변경
5. 실전 예제 2: 중복 로직을 함수로 추출
6. Quick Fix로 작은 오류 정리하기
7. Refactor Preview로 변경 검토하기
8. 저장할 때 import 자동 정리하기
9. 주의점과 문제 해결
10. 15분 연습 과제

한 줄 요약 리팩터링은 프로그램의 실행 결과는 유지하면서 코드 구조와 이름을 개선하는 작업입니다. VS Code는 JavaScript·TypeScript 리팩터링을 기본 제공하며, 다른 언어는 해당 언어 서비스 또는 확장이 기능을 제공합니다. VS Code 리팩터링 공식 문서

1. 리팩터링과 Code Actions 이해하기

VS Code에서는 전구 아이콘으로 표시되는 Code Actions 안에 Quick Fix와 리팩터링이 함께 나타납니다. 두 기능은 비슷해 보이지만 목적이 다릅니다.

종류	주요 목적	대표 사례
Quick Fix	현재 오류·경고를 빠르게 수정	누락된 import 추가, 오타 교정, 사용하지 않는 import 제거
Refactor	동작을 유지하며 코드 구조 개선	함수 추출, 상수 추출, 심볼 이름 변경
Source Action	파일이나 프로젝트 단위 정리	import 정리, 가능한 수정 일괄 적용

표시되는 항목은 현재 선택 영역, 파일 언어, 설치된 확장, 프로젝트 설정에 따라 달라집니다. TypeScript·JavaScript의 대표 기능은 TypeScript 리팩터링 공식 문서에서 확인할 수 있습니다.

2. 핵심 단축키 한눈에 보기

기능	Windows	macOS	사용 시점
Rename Symbol	F2	F2	변수·함수·클래스 이름을 참조와 함께 변경
Quick Fix	Ctrl + .	⌘ + .	오류·경고의 수정안과 사용 가능한 Code Action 확인
Refactor	Ctrl + Shift + R	⌃ + ⇧ + R	Quick Fix를 제외하고 리팩터링 목록만 열기
변경 미리보기	Ctrl + Enter	⌘ + Enter	선택한 리팩터링을 바로 적용하지 않고 diff로 검토
Organize Imports	Shift + Alt + O	⇧ + ⌥ + O	TypeScript·JavaScript import 정리

기본 단축키는 운영체제와 키보드 배열, 사용자 설정에 따라 충돌하거나 달라질 수 있습니다. 공식 기본 단축키 목록과 단축키 설정 공식 문서에서 현재 값을 확인할 수 있습니다.

3. 안전하게 적용하는 기본 순서

1. 작업 전 상태를 저장합니다. Git을 사용한다면 변경 파일이 무엇인지 먼저 확인합니다.
2. 대상을 정확히 선택합니다. 이름 변경은 심볼 위에 커서를 두고, 함수 추출은 옮길 코드 블록을 드래그합니다.
3. Code Action을 엽니다. 목적에 따라 Rename Symbol, Quick Fix 또는 Refactor를 실행합니다.
4. 적용 범위를 확인합니다. 여러 파일이 바뀐다면 미리보기를 열어 예상하지 못한 변경이 없는지 봅니다.
5. 테스트와 타입 검사를 실행합니다. 자동 리팩터링도 런타임 동작까지 보장하지는 않습니다.

처음에는 작은 변경부터 이름 변경 한 번, 함수 추출 한 번처럼 작업을 작게 나누면 문제가 생겨도 Git diff에서 원인을 찾기 쉽습니다.

4. 실전 예제 1: 프로젝트 전체 이름 변경

여러 파일에서 사용하는 userName을 의미가 더 분명한 customerName으로 바꿔 보겠습니다. 단순 찾기·바꾸기와 달리 Rename Symbol은 언어 서비스가 같은 심볼로 판단한 참조를 수정합니다.

// customer.ts
export const userName = "Jin";

// greeting.ts
import { userName } from "./customer";
console.log(`Hello, ${userName}`);

1. userName 위에 커서를 둡니다.
2. Windows와 macOS 모두 F2를 누릅니다.
3. customerName을 입력합니다.
4. 바로 적용하려면 Enter를 누릅니다. 먼저 검토하려면 Windows는 Ctrl+Enter, macOS는 ⌘+Enter를 눌러 미리보기를 엽니다.
5. 두 파일의 선언·import·사용 위치가 모두 바뀌는지 확인합니다.

// customer.ts
export const customerName = "Jin";

// greeting.ts
import { customerName } from "./customer";
console.log(`Hello, ${customerName}`);

VS Code 공식 문서는 일부 언어에서 Rename Symbol이 파일을 넘어 참조를 변경할 수 있다고 설명합니다. Rename Symbol 공식 안내

5. 실전 예제 2: 중복 로직을 함수로 추출

주문 금액 계산식이 여러 곳에 반복된다면 선택 영역을 함수로 추출해 이름 있는 로직으로 만들 수 있습니다.

function printOrder(price: number, quantity: number) {
  const total = price * quantity;
  const discount = total >= 100000 ? total * 0.1 : 0;
  console.log(total - discount);
}

1. const total부터 discount 계산까지 선택합니다.
2. Windows는 Ctrl+Shift+R, macOS는 ⌃+⇧+R을 누릅니다.
3. Extract to function 또는 언어 서비스가 제안하는 유사 항목을 선택합니다.
4. 새 함수 이름을 calculateDiscountedTotal로 입력합니다.
5. 매개변수와 반환값이 의도대로 만들어졌는지 확인합니다.

function calculateDiscountedTotal(price: number, quantity: number) {
  const total = price * quantity;
  const discount = total >= 100000 ? total * 0.1 : 0;
  return total - discount;
}

function printOrder(price: number, quantity: number) {
  console.log(calculateDiscountedTotal(price, quantity));
}

선택한 표현식은 상수로, 여러 문장은 메서드나 함수로 추출할 수 있습니다. 실제 선택지는 언어 서비스와 코드 문맥에 따라 달라집니다. Extract Method·Extract Variable 공식 설명

6. Quick Fix로 작은 오류 정리하기

TypeScript 파일에 사용하지 않는 import가 남아 있다고 가정해 보겠습니다.

import { readFile, writeFile } from "node:fs/promises";

async function saveReport(path: string, content: string) {
  await writeFile(path, content);
}

1. 경고 밑줄이 표시된 readFile이 있는 줄에 커서를 둡니다.
2. Windows는 Ctrl+., macOS는 ⌘+.를 누릅니다.
3. Remove unused declaration처럼 현재 언어 서비스가 제안하는 수정안을 선택합니다.
4. 수정 후 import와 타입 오류가 정상인지 확인합니다.

알아두기 Quick Fix는 현재 커서가 오류에 정확히 있지 않아도 같은 줄에서 가장 가까운 수정안을 열 수 있습니다. 이 동작은 editor.codeActionWidget.includeNearbyQuickFixes가 기본 활성화된 방식입니다. VS Code 1.84 공식 릴리스 노트

7. Refactor Preview로 변경 검토하기

리팩터링 메뉴에서 항목을 선택하기 전에 해당 항목 위에 포커스를 둔 뒤, Windows는 Ctrl+Enter, macOS는 ⌘+Enter를 누르면 Refactor Preview를 열 수 있습니다.

• 파일별 diff를 열어 실제 변경 내용을 확인할 수 있습니다.
• 원하지 않는 변경 항목을 선택 해제해 일부만 적용할 수 있습니다.
• Accept로 적용하거나 Discard로 취소할 수 있습니다.

VS Code 1.87에서는 리팩터링 미리보기가 여러 파일의 변경을 한눈에 보는 multi diff editor로 개선됐고, 1.88에서 이름 변경과 Code Actions의 미리보기 키가 Windows Ctrl+Enter, macOS ⌘+Enter로 통일됐습니다. 1.87 릴리스 노트 · 1.88 릴리스 노트

8. 저장할 때 import 자동 정리하기

JavaScript·TypeScript 프로젝트에서 저장할 때 import를 자동 정리하려면 사용자 또는 워크스페이스의 settings.json에 다음을 추가합니다.

{
  "editor.codeActionsOnSave": {
    "source.organizeImports": "explicit"
  }
}

값	동작	추천 상황
explicit	사용자가 명시적으로 저장할 때 실행	처음 자동화를 도입할 때
always	명시적 저장과 포커스·창 변경 Auto Save에서도 실행	팀 규칙과 결과가 충분히 검증된 프로젝트
never	저장 시 실행하지 않음	자동 정리를 원하지 않을 때

공식 문서는 이전의 불리언 값보다 explicit·always·never 사용을 안내합니다. VS Code 1.91에서는 현재 워크스페이스와 활성 확장을 바탕으로 설정 가능한 Code Action 목록의 IntelliSense도 개선됐습니다. Code Actions on Save 공식 문서 · VS Code 1.91 릴리스 노트

9. 주의점과 문제 해결

• 항목이 보이지 않을 때: 파일의 언어 모드가 맞는지, 해당 언어 확장이 활성화됐는지, 프로젝트가 정상 인식됐는지 확인합니다.
• 텍스트 찾기·바꾸기와 구분: Rename Symbol은 언어 서비스가 이해한 심볼을 대상으로 합니다. 문자열·주석·동적 참조는 별도로 확인해야 합니다.
• 공개 API 변경 주의: 저장소 밖의 다른 서비스나 패키지 사용자가 참조하는 이름은 자동으로 수정되지 않습니다.
• 생성 코드 주의: 자동 생성 파일은 직접 리팩터링하기보다 원본 스키마나 생성 설정을 바꾸는 편이 안전합니다.
• 자동 저장 범위 확인: always는 창이나 포커스가 바뀌는 Auto Save에서도 실행될 수 있으므로 팀과 먼저 합의하세요.
• 적용 후 검증: 타입 검사, 린트, 단위 테스트와 Git diff 확인을 리팩터링 완료 조건으로 삼으세요.

단축키가 다르게 동작한다면 Keyboard Shortcuts 편집기에서 명령 이름을 검색하고 충돌 여부를 확인하세요. 확장이 같은 키를 가로채거나 키보드 배열에 따라 표시가 달라질 수 있습니다. 단축키 충돌 확인 공식 안내

10. 15분 연습 과제

1. 3분: 작은 TypeScript 또는 JavaScript 프로젝트에서 한 변수를 F2로 이름 변경하고, 두 파일 이상의 참조가 함께 바뀌는지 확인합니다.
2. 4분: 계산식 한 줄을 선택해 Extract to constant를 실행합니다.
3. 4분: 세 줄 이상의 로직을 선택해 함수로 추출하고 매개변수·반환값을 확인합니다.
4. 2분: 사용하지 않는 import를 만든 뒤 Windows Ctrl+. 또는 macOS ⌘+.로 정리합니다.
5. 2분: Git diff를 열어 예상한 파일과 줄만 바뀌었는지 검토하고 테스트를 실행합니다.

완료 기준 단축키를 외우는 것보다, 대상 선택 → Code Action → 미리보기 → 테스트 → diff 확인 순서를 습관화했다면 이번 연습의 목적을 달성한 것입니다.

공식 자료

• Refactoring
• Refactoring TypeScript
• Default keyboard shortcuts reference
• VS Code 1.84 Release Notes
• VS Code 1.87 Release Notes
• VS Code 1.88 Release Notes
• VS Code 1.91 Release Notes

공식 문서와 공식 릴리스 노트를 2026년 7월 22일 기준으로 확인해 작성했습니다.