커맨드 팔레트 10부: VS Code Task 중복 실행을 instanceLimit로 제한하기

VS CODE 초보자 시리즈 · 커맨드 팔레트 10부

같은 Task의 중복 실행을 안전하게 제한하기

runOptions.instanceLimit와 instancePolicy로 동시에 실행할 수 있는 Task 수와 제한 도달 시 동작을 정하고, 두 번째 실행의 결과를 눈으로 확인합니다.

이번 편의 핵심

30초 동안 실행되는 연습 Task에 동시 실행 한도를 1로 지정합니다. warn 정책에서는 두 번째 실행이 시작되지 않고, terminateOldest 정책에서는 기존 실행이 종료된 뒤 새 실행이 시작되면 완료입니다.

개발 서버나 파일 감시 Task를 실수로 여러 번 실행하면 포트 충돌, 중복 로그, 불필요한 CPU 사용이 생길 수 있습니다. VS Code의 실행 정책을 정해 두면 두 번째 실행을 어떻게 처리할지 Task 자체에 기록할 수 있습니다.

목차

1. 시작하기 전에
2. 알아둘 핵심 개념
3. 순서대로 진행하기
4. 완료 확인하기
5. 문제가 생겼다면
6. 핵심 정리와 공식 자료

1. 시작하기 전에

난이도는 초급입니다. JSON 파일 한 개를 만들고 같은 Task를 빠르게 두 번 실행할 수 있으면 됩니다. 확장 설치, 관리자 권한, 인터넷 전송은 필요하지 않습니다.

준비할 것

• Windows 11과 VS Code Stable 1.132.0 — 확인: 도움말 > 정보에서 버전을 확인합니다.
• PowerShell — 확인: 통합 Terminal에서 $PSVersionTable.PSVersion을 실행해 버전 값이 표시되는지 봅니다.
• 비어 있는 연습 폴더 — 확인: 기존 프로젝트가 아닌 새 폴더인지 주소 표시줄에서 확인합니다.

적용 환경 한국어 초보자 · Windows 11 · VS Code Stable 1.132.0 · Windows PowerShell · Workspace Folder

안전하게 시작하기 이 실습 Task는 파일·네트워크·권한을 변경하지 않고 30초 동안 대기하지만, terminateOldest는 실행 중인 Task 프로세스를 종료합니다. 실제 빌드·서버 Task에 바로 적용하지 말고 새 연습 폴더에서 먼저 확인하세요. 기존 .vscode/tasks.json이 보이면 덮어쓰지 말고 중단한 뒤 다른 빈 폴더를 사용합니다. 보호 대상: 기존 프로젝트의 Task 구성과 실행 중인 프로세스. 중단 조건: 연습 폴더가 아니거나, 알 수 없는 Task가 이미 실행 중이거나, 저장 전 변경 내용을 구분할 수 없을 때.

2. 알아둘 핵심 개념

runOptions.instanceLimit

한 Task가 동시에 가질 수 있는 실행 인스턴스 수입니다. 자료형은 정수이며 Task 범위의 runOptions 안에 씁니다. 공식 문서의 기본값은 1입니다. 이번 실습도 1로 고정해 두 번째 실행이 제한에 닿도록 만듭니다.

runOptions.instancePolicy

이미 instanceLimit에 도달했을 때 다음 실행 요청을 처리하는 문자열 값입니다. 기본값 prompt는 종료할 인스턴스를 사용자가 고르게 하고, silent는 알림 없이 새 실행을 막고, warn은 경고를 보여 주며 새 실행을 막습니다. terminateNewest는 실행 중인 인스턴스 중 가장 최근 것을, terminateOldest는 가장 오래된 것을 종료한 뒤 새 실행을 처리합니다.

인스턴스와 Terminal은 같은 개념이 아닙니다

인스턴스는 Task의 실행 단위이고 Terminal은 출력을 보여 주는 화면입니다. presentation.panel은 Terminal 재사용 방식을 정하지만, 동시에 몇 개의 Task를 허용할지는 runOptions가 정합니다.

권장 시작점 초보자는 차단 사실이 보이는 warn으로 먼저 확인하세요. 자동 교체가 필요하고 기존 실행을 안전하게 끝내도 된다는 근거가 있을 때만 terminateOldest를 고려합니다. silent는 실행되지 않은 이유를 놓치기 쉬워 첫 설정으로는 권하지 않습니다.

3. 순서대로 진행하기

각 단계의 정상 결과를 확인한 뒤 다음 단계로 이동합니다.

1. 빈 연습 폴더 열기

목적 기존 프로젝트의 Task를 건드리지 않는 독립된 실습 공간을 만듭니다.

1. 파일 탐색기에서 C:\Users\<USER>\Documents\vscode-task-instance-lab 폴더를 만든 뒤, VS Code에서 파일 > 폴더 열기로 엽니다. <USER>는 Windows 사용자 폴더 이름으로 바꿉니다.

입력 위치 Windows 파일 탐색기와 VS Code의 파일 > 폴더 열기

C:\Users\<USER>\Documents\vscode-task-instance-lab

정상 결과 탐색기 루트에 vscode-task-instance-lab만 보이고 파일은 없습니다.

확인 VS Code 창 제목과 탐색기 루트 이름이 연습 폴더와 같은지 확인합니다.

실패 신호 기존 소스 파일이나 .vscode 폴더가 이미 보입니다.

주의 기존 폴더라면 아무 파일도 만들지 말고 창을 닫습니다. 되돌리기: 새 이름의 빈 폴더를 만든 뒤 STEP-01부터 다시 시작합니다.

2. warn 정책 Task 만들기

목적 한 번에 하나만 실행하고, 두 번째 요청은 경고와 함께 막는 기준 구성을 만듭니다.

1. 탐색기에서 .vscode 폴더와 그 안의 tasks.json 파일을 만든 뒤 아래 JSON 전체를 저장합니다.

입력 위치 연습 Workspace의 .vscode/tasks.json

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Instance policy lab",
      "type": "process",
      "command": "powershell.exe",
      "args": [
        "-NoProfile",
        "-Command",
        "$stamp = Get-Date -Format HH:mm:ss.fff; Write-Output ('START-' + $stamp + '-PID-' + $PID); Start-Sleep -Seconds 30; Write-Output ('END-' + $stamp + '-PID-' + $PID)"
      ],
      "runOptions": {
        "instanceLimit": 1,
        "instancePolicy": "warn"
      },
      "presentation": {
        "reveal": "always",
        "panel": "new"
      },
      "problemMatcher": []
    }
  ]
}

정상 결과 편집기에서 빨간 물결 밑줄이 없고 instanceLimit에는 숫자 1, instancePolicy에는 문자열 "warn"이 보입니다.

확인 Ctrl+S로 저장하고 문제 패널에 JSON 오류가 없는지 확인합니다.

실패 신호 Property expected, Incorrect type처럼 JSON 오류가 표시됩니다.

주의 이 명령은 Workspace에서 Windows PowerShell 프로세스를 30초간 실행합니다. 파일·네트워크 변경은 없습니다. 되돌리기: 오류가 있으면 실행하지 말고 위 예제와 쉼표·따옴표·중괄호를 비교해 수정한 뒤 STEP-02 확인으로 돌아갑니다.

3. 첫 번째 인스턴스 실행하기

목적 한도에 포함될 실행 중 인스턴스 하나를 만듭니다.

1. Ctrl+Shift+P를 누르고 Tasks: Run Task를 실행한 뒤 Instance policy lab을 선택합니다.

입력 위치 Command Palette와 Integrated Terminal

START-<시각>-PID-<프로세스ID>

정상 결과 Terminal에 START-로 시작하는 한 줄이 나타나고, 약 30초 동안 Task가 실행 중입니다.

확인 END- 줄이 나오기 전에 바로 STEP-04로 이동합니다.

실패 신호 Task를 찾을 수 없거나 시작하자마자 오류와 함께 종료됩니다.

주의 출력의 시각과 PID는 실행마다 달라지는 플레이스홀더입니다. 되돌리기: 오류 원문을 복사해 보존하고 STEP-02의 파일 경로와 JSON을 확인한 뒤 STEP-03을 다시 실행합니다.

4. 두 번째 실행이 warn으로 막히는지 확인하기

목적 동시 실행 한도 1에 도달했을 때 두 번째 인스턴스가 시작되지 않는지 관찰합니다.

1. 첫 Task의 30초가 끝나기 전에 Command Palette에서 Tasks: Run Task를 다시 실행하고 같은 Instance policy lab을 선택합니다.

입력 위치 Command Palette, 알림 영역, Integrated Terminal

예상 관찰: 새 START 줄 0개
정책: instanceLimit = 1, instancePolicy = warn

정상 결과 제한 도달을 알리는 경고가 표시되고 새 인스턴스는 시작되지 않습니다. 첫 Terminal에는 두 번째 START- 줄이 생기지 않습니다.

확인 첫 번째 START- 뒤에 새 START-가 없는지 보고, 첫 실행이 끝나면 같은 PID의 END-가 나타나는지 확인합니다.

실패 신호 서로 다른 PID의 START- 줄이 두 개 보이거나, 두 번째 실행 전에 첫 Task가 이미 끝났습니다.

주의 알림 문구는 VS Code 표시 언어와 버전에 따라 다를 수 있으므로 정확한 문장보다 “새 START가 생기지 않음”을 기준으로 판정합니다. 되돌리기: 첫 실행이 끝났다면 STEP-03부터 다시 시작하고 5초 안에 두 번째 실행을 요청합니다.

5. 정책을 terminateOldest로 바꾸기

목적 제한에 도달했을 때 기존 실행을 새 실행으로 교체하는 정책을 비교합니다.

1. 실행 중인 Task가 없는지 확인한 뒤 .vscode/tasks.json에서 "warn"만 "terminateOldest"로 바꾸고 저장합니다.

입력 위치 .vscode/tasks.json의 runOptions.instancePolicy

"runOptions": {
  "instanceLimit": 1,
  "instancePolicy": "terminateOldest"
}

정상 결과 instanceLimit는 1로 유지되고 정책 문자열만 terminateOldest로 바뀝니다.

확인 저장 후 문제 패널에 JSON 오류가 없고 편집기 검색 결과에 instancePolicy가 한 번만 있는지 확인합니다.

실패 신호 첫 Task가 아직 실행 중이거나 다른 키까지 함께 바뀌었습니다.

주의 다음 단계의 두 번째 실행은 기존 PowerShell Task를 의도적으로 종료합니다. 실제 서버나 배포 Task에는 종료 안전성을 별도로 검토해야 합니다. Human Gate: 현재 실행 중인 것이 이 연습 Task뿐임을 확인한 뒤 진행합니다. 되돌리기: 진행하지 않으려면 값을 "warn"으로 복원하고 저장합니다.

6. 가장 오래된 실행이 교체되는지 확인하기

목적 terminateOldest의 실제 교체 결과를 서로 다른 PID로 확인합니다.

1. STEP-03과 같은 방법으로 Task를 한 번 실행하고, 첫 START-...-PID-<첫PID>가 보이면 5초 안에 같은 Task를 다시 실행합니다.

입력 위치 Command Palette와 Integrated Terminal

START-<시각1>-PID-<첫PID>
START-<시각2>-PID-<둘째PID>
END-<시각2>-PID-<둘째PID>

정상 결과 둘째 PID의 새 인스턴스가 시작되고 가장 오래된 첫 인스턴스는 30초를 채우기 전에 종료됩니다. 따라서 첫 PID의 정상 END-는 없고, 기다리면 둘째 PID의 END-가 나타납니다.

확인 두 START-의 PID가 다르고, 정상 완료한 END-의 PID가 둘째 PID와 같은지 확인합니다.

실패 신호 새 START가 없거나 첫 PID와 둘째 PID가 같거나, 두 실행이 모두 30초 동안 동시에 유지됩니다.

주의 Task 종료 과정의 추가 상태 문구는 환경에 따라 달라질 수 있습니다. PID와 START/END 조합을 우선 Evidence로 사용합니다. 되돌리기: Terminal의 휴지통이나 Tasks: Terminate Task로 연습 Task를 종료하고, 정책을 "warn"으로 되돌린 뒤 STEP-05 확인 지점에 재합류합니다.

7. 안전한 기본 상태로 복구하기

목적 자동 종료 정책을 남겨 두지 않고 실습을 끝냅니다.

1. 모든 연습 Task가 끝난 것을 확인한 뒤 instancePolicy를 "warn"으로 되돌려 저장합니다.

입력 위치 .vscode/tasks.json

"instancePolicy": "warn"

정상 결과 다음 중복 실행은 기존 프로세스를 자동 종료하지 않고 경고와 함께 차단됩니다.

확인 파일에서 "warn"을 확인하고 실행 중인 Task가 0개인지 확인합니다.

실패 신호 Terminal 탭에 실행 중 표시가 남아 있거나 파일이 저장되지 않았습니다.

주의 연습 폴더 삭제는 필수가 아닙니다. 되돌리기: 삭제하려면 폴더 경로가 정확한 연습 폴더인지 다시 확인하고 필요한 Evidence를 복사한 다음 Windows 휴지통으로 이동합니다.

4. 완료 확인하기

입력 화면과 독립된 Terminal 출력으로 결과를 교차 확인합니다.

• warn 시험에서 첫 실행 중 두 번째 요청을 해도 새 START- 줄이 생기지 않습니다.
• terminateOldest 시험에서 서로 다른 두 PID의 START-가 보이고, 첫 PID의 정상 END- 없이 둘째 PID만 완료됩니다.
• 최종 tasks.json은 instanceLimit: 1, instancePolicy: "warn"이며 JSON 오류가 없습니다.
• 실행 중인 연습 Task가 없고 파일·네트워크·권한 변경이 발생하지 않았습니다.

완료 기준 동시 실행 한도 1에서 warn은 두 번째 실행을 막고, terminateOldest는 기존 실행을 새 실행으로 교체한다는 차이를 PID와 START/END 출력으로 설명하고 재현할 수 있습니다.

5. 문제가 생겼다면

Task 목록에 Instance policy lab이 없습니다

먼저 확인 단일 파일이 아니라 폴더를 열었는지, 경로가 정확히 .vscode/tasks.json인지, 저장했는지 확인합니다.

복구 JSON 오류 원문을 보존하고 STEP-02 예제와 괄호·쉼표·따옴표를 비교합니다. 원인을 확인하지 못하면 새 빈 폴더에서 예제를 다시 만듭니다.

재합류 STEP-02

두 번째 실행이 제한되지 않습니다

먼저 확인 첫 Task가 아직 30초 대기 중인지, instanceLimit가 숫자 1인지, 두 번 모두 같은 label의 Task를 선택했는지 확인합니다.

복구 실행 중 Task를 모두 종료하고 저장된 JSON을 확인한 다음 STEP-03부터 5초 안에 두 번 실행합니다.

재합류 STEP-03

terminateOldest에서 첫 Task의 END도 보입니다

먼저 확인 두 번째 실행 요청 전에 첫 30초가 끝났는지, 출력의 PID가 서로 다른지 확인합니다.

복구 Terminal의 기존 출력을 지우지 말고 Evidence를 보존한 뒤, 새 시도는 첫 START 후 5초 안에 실행합니다. 원인이 불명확하면 UNKNOWN으로 기록하고 warn으로 복원합니다.

재합류 STEP-05

정책 값을 저장했는데 빨간 밑줄이 생깁니다

먼저 확인 runOptions 안에 썼는지, 대소문자가 정확한지, 값이 공식 목록의 문자열인지 확인합니다.

복구 "instancePolicy": "warn"으로 복원해 오류가 사라지는지 확인합니다. 계속되면 오류 원문과 VS Code 버전을 보존하고 진행을 중단합니다.

재합류 STEP-02

핵심 판단 원인을 확인하지 못하면 상태와 오류 원문을 보존하고 임의로 다른 정책 이름을 만들지 않습니다. 모든 Recovery 뒤에는 4장의 완료 기준을 다시 확인합니다.

6. 핵심 정리와 공식 자료

• instanceLimit는 동시에 허용할 Task 인스턴스 수이며 기본값은 1입니다.
• instancePolicy는 제한 도달 후의 처리 방식이며 기본값은 prompt입니다.
• 처음에는 차단 사실이 보이는 warn으로 검증하고, 종료 안전성이 확인된 Task에만 terminateOldest 같은 자동 종료 정책을 사용합니다.
• 정책 검증은 알림 문구보다 새 인스턴스의 START, PID, END처럼 관찰 가능한 결과를 기준으로 합니다.

공식 자료

아래 자료는 2026-08-09 Asia/Seoul에 접근했습니다. Stable API와 Release Notes는 당시 최신 버전과 도입 시점을, Tasks 문서는 현재 동작과 값 목록을 설명합니다. UI 문구는 표시 언어와 후속 버전에 따라 달라질 수 있습니다.

• VS Code Stable Releases API · Microsoft
• Visual Studio Code 1.132 Release Notes · Microsoft
• Tasks: Run behavior · Microsoft
• Visual Studio Code 1.101: Instance policy · Microsoft

다음 편 예고 커맨드 팔레트 11부 — 마지막 Task 재실행에서 입력값 평가 시점 고정하기. runOptions.reevaluateOnRerun과 Tasks: Rerun Last Task로 이전 입력값 재사용과 재평가를 비교합니다.