커맨드 팔레트 21부: VS Code Task 목록에 설명을 붙여 비슷한 명령 구분하기

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

Task 목록 설명으로 비슷한 명령 구분하기

detail을 사용해 이름이 비슷한 Task에 목적과 결과 파일을 한 줄로 덧붙이고, 실행 전에 올바른 항목을 골랐는지 확인합니다.

이번 편의 핵심

Tasks: Run Task 목록에서 개발용과 운영용 Task의 보조 설명을 확인한 뒤 운영용만 실행해 output-production.txt의 정확한 값을 검증합니다.

detail은 선택을 돕는 설명입니다. 실행 명령, 권한, 환경 구분을 대신하지 않으므로 실제 label과 args도 함께 검토해야 합니다.

목차

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

1. 시작하기 전에

난이도: 초급. 빈 폴더에서 JSON 파일 하나와 결과 텍스트 파일 하나를 만듭니다. 기본 환경은 Windows 11, VS Code Stable 1.134.0, Windows PowerShell 5.1 계열입니다.

준비할 것

• 직접 만든 빈 실습 폴더 — File > Open Folder...로 열어야 Workspace Task를 사용할 수 있습니다.
• VS Code Stable — PowerShell에서 code --version을 실행해 버전을 확인합니다. 이 글의 공식 소스와 로컬 검증 기준은 2026-08-20 Stable 1.134.0입니다.
• Windows PowerShell — powershell.exe -NoProfile -Command "$PSVersionTable.PSVersion.ToString()"이 종료 코드 0으로 끝나는지 확인합니다.
• 기존 .vscode/tasks.json 보호 — 이미 있으면 덮어쓰지 말고 새 빈 폴더를 사용하거나 먼저 복사본을 만듭니다.

실행 전 Human Gate 예제 Task는 현재 Workspace에 output-development.txt 또는 output-production.txt를 씁니다. 두 파일과 .vscode/tasks.json이 없는 빈 폴더인지 확인한 뒤 진행합니다. 중단 조건: 폴더의 출처를 모르거나 같은 이름의 파일이 이미 있거나 명령을 이해하지 못하면 실행하지 않습니다. Rollback: 새로 만든 실습 파일만 제거하고, 기존 파일은 건드리지 않습니다.

2. 알아둘 핵심 개념

label과 detail

FACT. label은 Task를 UI에서 식별하는 이름입니다. detail은 선택적 String 설명이며 Stable 1.134.0 스키마는 이를 Run Task Quick Pick에 표시되는 설명으로 정의합니다. 두 Task의 label은 서로 다르게 유지해야 참조와 실행 기록을 혼동하기 쉽지 않습니다.

task.quickOpen.detail

FACT. 이 설정은 Task Quick Pick에서 설명을 표시할지 제어하는 Boolean이며 기본값은 true입니다. 이 글은 User 또는 Workspace 설정에서 값이 true이거나 기본값인 상태를 전제로 합니다.

설명은 안전장치가 아닙니다

RECOMMENDATION. 설명은 사람이 고르는 순간의 실수를 줄이는 메모입니다. 명령을 바꾸거나 운영 실행을 차단하지 않습니다. 실제 작업에서는 권한, 승인 흐름, 별도 환경과 같은 통제를 함께 사용합니다.

관찰 가능한 완료 상태

EXAMPLE. Run Task 목록에서 두 항목 아래의 개발용·운영용 설명을 확인하고 운영용 Task만 선택합니다. 실행 뒤 output-production.txt가 정확히 ENVIRONMENT=PRODUCTION을 담고, 개발용 파일은 없으면 완료입니다.

3. 순서대로 진행하기

각 단계의 정상 결과를 확인한 뒤 다음으로 이동합니다. <실습폴더>는 직접 만든 빈 폴더의 실제 경로로 바꿉니다.

1. 빈 실습 폴더를 Workspace로 열기

목적 예제 결과를 기존 프로젝트와 분리합니다.

1. File > Open Folder...에서 <실습폴더>를 엽니다. Workspace Trust 안내가 나오면 본인이 만든 빈 폴더인지 확인한 뒤에만 신뢰합니다.

입력 위치 VS Code File 메뉴와 폴더 선택 창

<실습폴더>
└─ 아직 파일 없음

정상 결과 Explorer 최상단에 실습 폴더 하나가 표시됩니다.

확인 Terminal > New Terminal에서 Get-Location을 실행하고 마지막 경로가 <실습폴더>인지 확인합니다.

실패 신호 단일 파일만 열렸거나 Terminal 경로가 다른 프로젝트입니다.

Recovery File > Close Folder로 닫고 새 빈 폴더를 열어 S01에 재합류합니다.

2. 보호 대상 파일이 없는지 확인하기

목적 기존 설정과 결과 파일의 덮어쓰기를 막습니다.

1. Integrated Terminal에서 아래 읽기 전용 명령을 실행합니다.

입력 위치 Integrated Terminal · Shell: PowerShell · 실행 위치: <실습폴더>

@(
  '.\.vscode\tasks.json',
  '.\output-development.txt',
  '.\output-production.txt'
) | ForEach-Object { "$_=$((Test-Path -LiteralPath $_))" }

정상 결과 세 경로가 모두 False입니다.

확인 출력 세 줄을 원문과 비교합니다.

실패 신호 하나라도 True이거나 접근 오류가 납니다.

Recovery 기존 파일을 삭제하지 말고 새 빈 폴더를 만들어 S01부터 다시 진행합니다.

3. Task 설명 표시 설정 확인하기

목적 작성한 detail이 선택 목록에서 보이는 전제 조건을 확인합니다.

1. Ctrl+,로 Settings를 열고 검색란에 @id:task.quickOpen.detail을 입력합니다. Task: Quick Open Detail이 켜져 있거나 기본값인지 확인합니다.

입력 위치 Settings UI · User 또는 Workspace 범위

Key: task.quickOpen.detail
Type: Boolean
Expected: true (default)

정상 결과 설정이 켜져 있고 Workspace 범위에서 false로 덮어쓰지 않았습니다.

확인 설정 항목의 기어 메뉴에서 적용 범위를 확인합니다.

실패 신호 값이 false이거나 다른 범위에서 덮어쓴 표시가 보입니다.

Recovery 설명 표시가 목표인 실습이므로 사용자가 직접 값을 true로 바꾸고 S03에 재합류합니다. 팀 정책으로 잠겼다면 값을 변경하지 말고 이 실습을 중단합니다.

4. 설명이 다른 두 Task 작성하기

목적 이름이 비슷한 개발용·운영용 실행 항목에 판단 근거를 추가합니다.

1. Explorer에서 .vscode 폴더와 그 안의 tasks.json을 새로 만들고 아래 전체 내용을 저장합니다.

입력 위치 <실습폴더>\.vscode\tasks.json

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Demo: build development",
      "detail": "개발 확인용 · output-development.txt 생성",
      "type": "process",
      "command": "powershell.exe",
      "args": [
        "-NoLogo",
        "-NoProfile",
        "-Command",
        "Set-Content -LiteralPath 'output-development.txt' -Value 'ENVIRONMENT=DEVELOPMENT' -NoNewline; Write-Output 'ENVIRONMENT=DEVELOPMENT'"
      ],
      "options": { "cwd": "${workspaceFolder}" },
      "problemMatcher": []
    },
    {
      "label": "Demo: build production",
      "detail": "운영 확인용 · output-production.txt 생성",
      "type": "process",
      "command": "powershell.exe",
      "args": [
        "-NoLogo",
        "-NoProfile",
        "-Command",
        "Set-Content -LiteralPath 'output-production.txt' -Value 'ENVIRONMENT=PRODUCTION' -NoNewline; Write-Output 'ENVIRONMENT=PRODUCTION'"
      ],
      "options": { "cwd": "${workspaceFolder}" },
      "problemMatcher": []
    }
  ]
}

정상 결과 VS Code가 JSON 오류 표시 없이 저장합니다.

확인 두 label과 두 detail이 서로 다르고, detail 값이 따옴표로 감싼 String인지 확인합니다.

실패 신호 빨간 물결선, Incorrect type, 쉼표 오류, 저장되지 않음 표시가 남습니다.

Human Gate 두 명령이 현재 폴더의 지정 파일 하나씩만 쓰는지 읽고 승인합니다. Recovery: 명령을 실행하지 말고 JSON만 S04 원문과 비교해 수정합니다.

5. JSON 자료형과 파일 부재 검증하기

목적 실행 전에 두 설명이 String이고 결과 파일이 아직 없음을 독립적으로 확인합니다.

1. 새 PowerShell Terminal에서 아래 읽기 전용 검증을 실행합니다.

입력 위치 Integrated Terminal · Shell: PowerShell · 실행 위치: <실습폴더>

$config = Get-Content -Raw -LiteralPath '.\.vscode\tasks.json' | ConvertFrom-Json
$details = @($config.tasks.detail)
[pscustomobject]@{
  TaskCount = @($config.tasks).Count
  DetailTypes = (($details | ForEach-Object { $_.GetType().Name }) -join ',')
  UniqueDetails = @($details | Sort-Object -Unique).Count
  OutputsAbsent = -not (Test-Path '.\output-development.txt') -and
                  -not (Test-Path '.\output-production.txt')
}

정상 결과 TaskCount=2, DetailTypes=String,String, UniqueDetails=2, OutputsAbsent=True입니다.

확인 네 값이 모두 정확한지 확인합니다.

실패 신호 JSON 파싱 오류, String 이외의 자료형, 중복 설명, 기존 결과 파일이 나타납니다.

Recovery 기존 결과 파일은 삭제하지 않습니다. JSON만 S04와 비교해 고치거나 새 빈 폴더로 돌아가 S01부터 재합류합니다.

6. Run Task 목록에서 설명 비교하기

목적 실행 전에 항목의 목적과 결과 파일을 읽어 구분합니다.

1. Ctrl+Shift+P를 누르고 Tasks: Run Task를 실행합니다. 두 Task를 찾되 아직 선택하지 않습니다.

입력 위치 Command Palette와 Run Task Quick Pick

Demo: build development
  개발 확인용 · output-development.txt 생성

Demo: build production
  운영 확인용 · output-production.txt 생성

정상 결과 각 label 아래에 서로 다른 detail이 보입니다.

확인 운영용 항목의 설명에 output-production.txt가 적혀 있는지 읽고 Esc로 한 번 닫습니다.

실패 신호 설명이 없거나, 설명이 같은 줄로 섞이거나, 두 Task 중 하나가 없습니다.

Recovery S03 설정, S04의 detail 위치와 String 자료형, 저장 상태를 차례로 확인한 뒤 S06으로 재합류합니다. 다른 Task 목록에서는 표시가 다를 수 있으므로 반드시 Tasks: Run Task를 사용합니다.

7. 운영용 Task만 선택해 실행하기

목적 설명을 근거로 목표 항목을 선택하고 실제 결과를 만듭니다.

1. S05의 OutputsAbsent=True와 S04 명령을 다시 확인하는 Human Gate를 통과합니다.
2. Tasks: Run Task에서 Demo: build production을 선택합니다.

입력 위치 Run Task Quick Pick

선택 label: Demo: build production
확인 detail: 운영 확인용 · output-production.txt 생성

정상 결과 Terminal에 ENVIRONMENT=PRODUCTION이 한 줄 출력되고 Task가 종료 코드 0으로 끝납니다.

확인 실행 직전 선택한 label과 detail을 다시 읽고, 실행 후 Terminal 출력 원문을 보존합니다.

실패 신호 DEVELOPMENT가 출력되거나, 오류 원문이 나오거나, Task가 계속 실행 중입니다.

Recovery 오류 원문과 종료 코드를 지우지 않습니다. 원인은 UNKNOWN으로 두고 S04의 선택 항목·명령과 비교합니다. 잘못된 Task를 실행했다면 결과 파일을 임의로 덮어쓰지 말고 새 빈 폴더에서 S01부터 다시 합류합니다.

8. 결과를 독립 검증하고 정리하기

목적 운영 파일의 내용과 개발 파일 부재를 UI와 분리해 확인합니다.

1. Integrated Terminal에서 아래 검증을 실행합니다.

입력 위치 Integrated Terminal · Shell: PowerShell · 실행 위치: <실습폴더>

$production = if (Test-Path '.\output-production.txt') {
  Get-Content -Raw -LiteralPath '.\output-production.txt'
} else { '<MISSING>' }
[pscustomobject]@{
  Production = $production
  DevelopmentAbsent = -not (Test-Path '.\output-development.txt')
  Complete = ($production -eq 'ENVIRONMENT=PRODUCTION') -and
             -not (Test-Path '.\output-development.txt')
}

정상 결과 Production=ENVIRONMENT=PRODUCTION, DevelopmentAbsent=True, Complete=True입니다.

확인 세 값과 S07 Terminal 원문을 함께 비교합니다.

실패 신호 파일 누락, 값 불일치, 개발 파일 존재, Complete=False입니다.

Rollback 실습이 끝난 뒤 본인이 S04에서 새로 만든 .vscode\tasks.json과 결과 파일만 제거할 수 있습니다. 기존 파일이 섞였거나 경로가 확실하지 않으면 삭제하지 않고 폴더를 닫습니다. 정리 후 다시 검증하려면 새 빈 폴더에서 S01에 재합류합니다.

4. 완료 확인하기

• Run Task Quick Pick에서 개발용·운영용 두 label과 서로 다른 두 detail을 확인했다.
• 운영용 항목의 설명을 읽고 Demo: build production만 실행했다.
• Terminal 출력과 output-production.txt가 정확히 ENVIRONMENT=PRODUCTION이다.
• output-development.txt는 없고 S08의 Complete가 True다.

네 항목이 모두 맞아야 완료입니다. Quick Pick 설명 표시 자체는 VS Code UI에서 확인하고, 결과 내용은 PowerShell로 독립 검증합니다.

5. 문제가 생겼다면

detail이 보이지 않습니다

S03에서 task.quickOpen.detail이 true인지, S04에서 detail이 각 Task 객체 안의 String인지 확인합니다. 저장 후 Tasks: Run Task를 다시 엽니다. 설정 정책으로 잠겨 있으면 변경하지 말고 표시 검증을 UNCONFIRMED으로 남깁니다.

두 Task가 목록에 없습니다

단일 파일이 아니라 폴더를 열었는지, .vscode/tasks.json 경로와 JSON 저장 상태를 확인합니다. Tasks: Run Task를 다시 실행합니다.

잘못된 Task를 실행했습니다

Terminal 출력과 생성된 파일을 지우거나 덮어쓰지 말고 증거로 보존합니다. S04의 label·detail·args를 비교한 뒤 기존 파일이 없는 새 폴더에서 다시 시작합니다.

JSON 파싱 오류가 납니다

오류 원문과 줄 번호를 보존합니다. 괄호, 쉼표, 따옴표를 S04 원문과 비교하고 S05를 다시 실행해 네 값이 모두 정상일 때만 S06으로 재합류합니다.

원인은 확인하지 못했습니다

원인을 추측하지 말고 UNKNOWN으로 기록합니다. VS Code 버전, Workspace 경로, 설정 범위, 오류 원문, 종료 코드를 보존한 뒤 빈 폴더에서 최소 예제로 재현합니다.

6. 핵심 정리와 공식 자료

• detail은 Task 선택 목록에 목적을 덧붙이는 선택적 String입니다.
• task.quickOpen.detail은 Boolean이고 기본값은 true입니다.
• 설명은 선택 보조 수단이며 실행 명령이나 권한 통제를 대신하지 않습니다.
• 완료는 설명 확인, 운영용 선택, 정확한 파일 값, 개발 파일 부재로 검증합니다.

Source

• FACT · 기준 시점 2026-08-20 · 접근 가능: VS Code Stable Update API — Windows x64 User Stable 1.134.0과 commit 110a328ea54b42367b803ec53ee0bf52ef26b419.
• FACT/PROCEDURE · 현재 문서 · 접근 가능: Integrate with External Tools via Tasks — Workspace Task 위치, label·type·command 의미, IntelliSense 확인 방법.
• FACT_SCHEMA · Stable 고정 소스 · 접근 가능: tasks.json schema source — detail String과 Run Task Quick Pick 설명.
• FACT_SETTING · Stable 고정 소스 · 접근 가능: Task settings contribution source — task.quickOpen.detail Boolean, 기본값 true.
• FACT_HISTORY · 적용 범위 참고 · 접근 가능: VS Code 1.40 Release Notes — detail의 tasks.json 지원과 Quick Pick 표시 설정 도입.

다음 편 예고

커맨드 팔레트 22부 — 최근 실행 Task 기록 수 조절하기. task.quickOpen.history의 Number 범위 0..30을 확인하고, Run Task Quick Pick의 최근 항목 수를 바꾼 뒤 표시 결과를 검증합니다.