Communitygithub.com

tzwkb/disk-cleanup

에이전트 스킬 — Windows 디스크 정리 및 공간 분석 툴킷.

disk-cleanup란 무엇인가요?

이 스킬은 Windows 시스템에서 디스크 공간을 분석하고 안전하게 정리할 수 있는 포괄적인 툴킷입니다. 에이전트가 사용자에게 위험 요소를 명확히 전달하고 확인을 받은 후에만 삭제를 수행하는 '스캔은 공격적으로, 삭제는 보수적으로' 원칙을 따릅니다. '교통 신호등' 위험 모델(🟢 안전, 🟡 사용자 확인 필요, 🔴 금지)을 통해 임시 파일, 브라우저 캐시, Python pip 캐시, WinSxS 구성 요소 등 다양한 유형의 데이터를 안전하게 정리할 수 있습니다. 또한 WeChat, QQ, WPS와 같은 중국 소프트웨어의 특수 경로 문제를 처리하고, 계층적 스캐닝 스크립트를 통해 대용량 폴더를 빠르게 찾아내며, ProgramData 분석, 대규모 애플리케이션 제거, 사용자 디렉터리 마이그레이션까지 지원합니다. Claude Code, Cursor, Codex 등 모든 AI 에이전트 플랫폼에서 사용할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add tzwkb/disk-cleanup

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Disk Cleanup Master — Windows 디스크 정리 마스터

핵심 원칙 (위반 불가)

  1. 스캔은 공격적으로, 삭제는 보수적으로
    • 스캔 단계: 과감하게 전체를 탐색하고 철저히 조사하며, 많이 보고해도 괜찮음
    • 삭제 단계: 모든 작업은 사용자에게 구체적인 내용, 크기, 위험을 보여주고 명확한 확인을 받은 후에만 실행
  2. 교통 신호등 보안 모델
    • 🟢 초록불 (안전하게 삭제 가능): Temp, 브라우저 캐시, pip cache, __pycache__, 오래된 설치 패키지 잔여물, 앱이 명시한 Cache/Log, WinSxS 이전 구성 요소
    • 🟡 노란불 (사용자 확인 필요): 게임 저장 파일, WeChat/QQ 기록, WPS 클라우드 파일, 다운로드 폴더의 개인 파일, ProgramData의 앱 전역 데이터
    • 🔴 빨간불 (임의 삭제 금지): Windows 시스템 디렉터리, Program Files, 사용자가 사용 중인 프로젝트 파일, 백업되지 않은 데이터
  3. 중국 소프트웨어 특수 처리
    • 텐센트 계열(WeChat/QQ/WeCom), NetEase 계열, WPS, Baidu 계열은 일반적으로 경로가 하드코딩되어 있어 Windows Known Folders API를 따르지 않음
    • 해당 폴더를 직접 잘라내기/이름 변경해서는 안 되며, 반드시 소프트웨어 설정에서 경로를 변경해야 함
    • 자세한 내용은 references/chinese-app-special-cases.md 참조

표준 작업 흐름

Step 1: 전체 스캔 (공격적)

  • Get-PSDrive를 사용하여 각 드라이브의 공간 개요 확인
  • scripts/tree_size_scanner.py를 사용한 계층적 드릴다운 스캔 — 루트 디렉터리부터 시작하여 크기별로 정렬, 가장 큰 폴더를 단계별로 깊이 들어가 공간 소모 원인을 빠르게 찾음
  • AppData, Documents, ProgramData 등 주요 영역을 대상으로 지정 스캔
  • 목표: 5분 이내에 디스크 점유 맵 제공

계층적 드릴다운 스캔 전략:

# C 드라이브 전체 보기 (500MB 이상 폴더 표시, 4단계 깊이)
python scripts/tree_size_scanner.py "C:\\" 500 4

# D/E 드라이브 빠르게 큰 폴더 찾기
python scripts/tree_size_scanner.py "D:\\" 5000 3
  • 먼저 루트 디렉터리를 스캔하여 가장 큰 폴더 몇 개를 찾음
  • 그런 다음 가장 큰 폴더에 대해 별도로 심층 스캔 수행
  • 시스템 디렉터리(Windows, Program Files)는 자동으로 건너뛰어 오작동 방지

특정 애플리케이션/게임 검색 (플랫폼 설치가 아닌 경우):

# 키워드로 폴더 이름 검색 (6단계 깊이, 크기 계산 안 함, 초고속)
python scripts/find_folders_by_keyword.py "D:\\" "Call of Duty|COD|Modern Warfare"

Step 2: 분류 및 위험 평가

  • 스캔 결과를 🟢🟡🔴로 분류
  • 노란불 항목에 구체적인 위험 표시 (예: "WeChat Backup 33 GB, 삭제 시 휴대폰 변경 후 복구 불가")
  • 빨간불 항목은 직접 제외하며 어떤 작업도 수행하지 않음

Step 3: 사용자에게 보고서 제시

  • 표 형식으로 표시: 영역, 크기, 위험 수준, 권장 작업
  • 사용자가 선택하거나 "무엇을 삭제할지" 명확히 응답하도록 함
  • 사용자의 항목별 확인 없이 일괄 삭제를 실행하는 것은 금지

Step 4: 정리 실행

  • 초록불 항목: 직접 실행 가능하나, 실행 후 결과를 보고해야 함
  • 노란불 항목: 사용자가 한 항목씩 확인하면 한 항목씩 실행
  • 실행 전에 우선 --dry-run 또는 미리보기 모드 사용

Step 5: 검증

  • 정리 후 디스크 공간 재확인
  • 마이그레이션 작업(예: Documents 마이그레이션)에 대해 쓰기 테스트를 수행하여 경로 정확성 검증

C 드라이브 특별 정리 가이드

시스템 수준 안전 정리 (초록불)

# 임시 파일
$env:TEMP                    # 사용자 임시 파일
C:\Windows\Temp              # 시스템 임시 파일
C:\Windows\SoftwareDistribution\Download  # Windows Update 캐시

# 브라우저 캐시
$env:LOCALAPPDATA\Microsoft\Edge\User Data\Default\Cache
$env:LOCALAPPDATA\Google\Chrome\User Data\Default\Cache

# 휴지통
C:\$Recycle.Bin

# 최대 절전 모드 파일 (사용자가 최대 절전 모드를 사용하지 않는 경우)
# powercfg /hibernate off

WinSxS 구성 요소 저장소 정리 (고가치 초록불)

WinSxS (C:\Windows\WinSxS)는 Windows 시스템 구성 요소 저장소로, 업데이트할 때마다 롤백을 위해 이전 버전을 보관합니다. 장기간 누적되면 10-20 GB까지 도달할 수 있습니다.

회수 가능한 공간 분석:

dism /Online /Cleanup-Image /AnalyzeComponentStore

정리 실행 (안전, 권장):

dism /Online /Cleanup-Image /StartComponentCleanup
  • 정리 후에는 설치된 Windows 업데이트를 제거할 수 없음 (실제 영향은 매우 적음)
  • 일반적으로 수백 MB ~ 수 GB 회수 가능
  • 소요 시간 3-10분, 백그라운드에서 실행 가능

더 공격적인 정리 (주의):

dism /Online /Cleanup-Image /StartComponentCleanup /ResetBase
  • 더 많은 공간을 확보하지만, 모든 업데이트를 완전히 롤백할 수 없게 됨
  • 디스크가 매우 부족한 경우에만 고려

Python 전역 환경 정리

  • pip list --format=freeze로 총 패키지 수 확인
  • pip list --not-required로 사용자가 직접 설치한 최상위 패키지 찾기 (보통 총 패키지 수보다 훨씬 적음)
  • pip check로 종속성 충돌 확인
  • pip cache purge로 pip 다운로드 캐시 정리
  • site-packages에서 ~로 시작하는 손상된 설치 잔여물 정리
  • 모든 __pycache__ 폴더 정리: Get-ChildItem -Path $sitePackages -Recurse -Directory -Filter "__pycache__" | Remove-Item -Recurse -Force
  • 참고: 종속성 충돌을 수정할 때 상호 배타적인 패키지가 발생할 수 있음(예: pyjwt 버전이 두 패키지에서 서로 다른 범위를 요구), 사용자가 어느 것을 유지할지 결정해야 함

AppData 지정 스캔

AppData는 C 드라이브의 숨겨진 대용량 영역으로, 일반적으로 다음과 같이 나뉩니다:

  • Local: 프로그램 캐시, 런타임 데이터 (정리 가능한 공간이 큼)
  • Roaming: 사용자 구성, 채팅 기록 (신중히 처리)
  • LocalLow: 낮은 권한의 앱 데이터 (보통 크지 않음)

일반적인 큰 항목:

  • Local\Netease\CloudMusic\Cache — NetEase Cloud Music 캐시 (삭제 가능)
  • Roaming\Kingsoft\office6\backup — WPS 충돌 백업 (삭제 가능)
  • Roaming\Tencent — WeChat PC 버전 데이터 (노란불, reference 참조)

ProgramData 지정 스캔

ProgramData는 간과하기 쉬운 C 드라이브의 대용량 영역으로, 애플리케이션의 전역 데이터, 설치 캐시 및 장치 드라이버 구성을 보관합니다.

분류 전략:

카테고리일반적인 경로위험예시
장치 드라이버 데이터NVIDIA, NVIDIA Corporation, LGHUB, ASUS🔴 건드리지 않음삭제 시 장치에 이상이 생길 수 있음
앱 전역 데이터Tencent, anaconda3, 0install.net🟡 확인 후 삭제해당 앱을 사용하지 않을 때 삭제 가능
설치 캐시Package Cache, Microsoft\VisualStudio🟡 주의삭제 시 프로그램을 제거/복구하지 못할 수 있음
시스템 데이터Microsoft\Windows Defender, Microsoft\Search🔴 건드리지 않음시스템 핵심 구성 요소

스캔 명령어:

# 스크립트를 사용하여 스캔하는 것이 좋음 (단일 명령어 시간 초과 방지)
python scripts/scan_programdata.py

일반적인 정리 가능 항목:

  • anaconda3 — 다른 Python 환경으로 전환했다면 제거 가능 (보통 3-8 GB)
  • 0install.net — Zero Install 패키지 관리자 데이터, 사용하지 않을 때 삭제 가능 (보통 수백 MB)
  • Tencent\QQPCMgr — QQ PC 매니저 데이터 (사용하지 않으면 삭제 가능)
  • Tencent\WeType — WeChat 입력기 데이터 (사용하지 않으면 삭제 가능)

대규모 애플리케이션 제거 절차 (노란불 → 초록불)

ProgramData나 Program Files에서 발견된 대규모 애플리케이션 잔여물의 경우 폴더를 직접 삭제하지 말고 정식 제거 절차를 따라야 합니다:

  1. 레지스트리에서 제거 프로그램 찾기

    Get-ItemProperty "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*" |
      Where-Object { $_.DisplayName -match "Anaconda" }
    
  2. 자동 제거 (NSIS 설치 프로그램)

    & "C:\ProgramData\anaconda3\Uninstall-Anaconda3.exe" /S
    
    • 참고: /S 실행 후 즉시 반환될 수 있으며, 제거 완료를 기다리지 않음
    • 폴더가 사라졌는지 폴링하여 확인해야 함:
    while (Test-Path "C:\ProgramData\anaconda3") { Start-Sleep -Seconds 10 }
    
  3. 잔여물 정리

    • 잔여 폴더 확인 및 삭제
    • PATH 환경 변수 확인:
    [Environment]::GetEnvironmentVariable("Path", "User") -split ";" | Select-String "anaconda"
    [Environment]::GetEnvironmentVariable("Path", "Machine") -split ";" | Select-String "anaconda"
    
  4. 고집스러운 폴더 삭제의 최후의 수단: Robocopy Empty Trick Remove-Item -Force와 takeown + icacls도 실패할 때:

    $empty = "C:\temp_empty_$(Get-Random)"
    New-Item -ItemType Directory -Path $empty -Force | Out-Null
    robocopy $empty "C:\ProgramData\0install.net" /MIR /R:1 /W:1 /NP /NFL /NDL
    Remove-Item $empty -Force
    Remove-Item "C:\ProgramData\0install.net" -Force
    
    • 원리: 빈 폴더로 대상을 미러링하여 강제로 내용을 비움
    • 경고: robocopy /MIR은 대상을 완전히 비우므로 방향이 절대 반대가 되어서는 안 됨!

사용자 디렉터리 마이그레이션

Windows 표준 폴더 (Documents / Desktop / Downloads / Pictures / Videos)

  • 올바른 방법: 폴더 우클릭 → 속성 → 위치 → 이동
  • 이것은 시스템 수준의 리디렉션으로, 프로그램이 API를 통해 경로를 가져올 때 자동으로 새 위치를 가리킴
  • 마이그레이션 후 이전 폴더가 잠겨 삭제되지 않으면 재부팅 후 처리

타사 애플리케이션 데이터

  • 잘못된 방법: AppData나 Documents의 애플리케이션 폴더를 새 드라이브로 직접 잘라내기
  • 올바른 방법: 각 소프트웨어 설정에서 "파일 관리/저장 위치"를 수정하여 소프트웨어가 스스로 마이그레이션하도록 함
  • 예외: Steam 게임 라이브러리는 Steam 설정에서 라이브러리 폴더를 추가/마이그레이션할 수 있음

게임 라이브러리 분석

Steam

  • 라이브러리 폴더: steamapps\common\ (게임 본체)
  • 미완료 다운로드: steamapps\downloading\ (안전하게 삭제 가능)
  • 창작마당: steamapps\workshop\ (구독 취소 후 수동 정리 가능)
  • 게임 제거는 Steam 클라이언트를 통해야 하며, 폴더를 직접 삭제하지 말 것

WeGame

  • 플랫폼 데이터: WEGAME\
  • 게임 데이터: WeGameApps\rail_apps\
  • 일반적인 대용량 게임: LOL (~40-50 GB), Valorant (~30 GB)

일반적인 함정과 경험

  1. robocopy /MIR 위험

    • /MIR은 미러 동기화와 같아 대상의 추가 파일을 삭제하므로 방향을 잘못 사용하면 데이터가 비워짐
    • 대규모 디렉터리 작업은 시간 초과될 수 있지만, robocopy 프로세스는 백그라운드에서 계속 실행되어 후속 I/O가 중단될 수 있음
    • 처리: 작업 후 잔여 프로세스 확인 Get-Process robocopy, 필요 시 강제 종료
  2. Robocopy Empty Trick (고집스러운 폴더 삭제)

    • 파일이 잠겨 있거나, 권한이 부족하거나, takeown도 실패할 때 빈 폴더 + /MIR로 대상을 강제로 비울 수 있음
    • 필수: 먼저 독립적인 빈 폴더를 소스로 생성하고, 대상 경로가 올바른지 확인한 후 실행
    • 절대 시스템 디렉터리(예: C:\Windows)를 대상으로 사용하지 말 것
  3. 스캔 출력 오염

    • 단일 셸 명령어에서 여러 Get-ChildItem | Format-Table을 병렬로 실행하면 출력 스트림이 혼동될 수 있음 (예: NVIDIA Corporation 결과에 Tencent 폴더가 섞임)
    • 처리: 한 번에 하나의 디렉터리만 스캔하거나 Python 스크립트로 통합 출력
  4. NSIS 제거 프로그램 비동기 동작

    • /S 매개변수와 함께 실행되는 자동 제거 프로그램이 실행 후 즉시 반환되어 완료될 때까지 차단되지 않을 수 있음
    • 처리: 실행 후 설치 디렉터리가 사라졌는지 폴링하거나 프로세스 목록 확인
  5. 파일 잠금

    • WeChat, WPS, QQ 등 상주 백그라운드 소프트웨어는 자체 데이터 파일을 잠가 폴더 이름 변경/삭제가 불가능하게 함
    • 처리: 먼저 해당 프로세스(데몬 프로세스 포함)를 종료한 후 작업 수행
  6. 유니코드 파일 이름

    • Windows 중국어 파일 이름은 PowerShell/Python에서 인코딩 오류를 일으키기 쉬움
    • 처리: Python 스크립트에서 .encode('ascii', 'replace').decode('ascii')를 사용하여 안전하게 출력
  7. Measure-Object -Sum 시간 초과

    • 수십만 개의 파일이 포함된 디렉터리(예: WeChat 캐시, 게임 리소스)에서 Get-ChildItem -Recurse와 Measure-Object를 함께 사용하면 시간 초과될 수 있음
    • 처리: robocopy $path \NULL /L /S /NJH /NJS /BYTES를 사용하여 통계를 내거나 스캔 깊이 제한
  8. 대규모 디렉터리 검색의 궁극적 전략 (계층 + 키워드)

    • Get-ChildItem -Recurse와 robocopy /L /S는 Steam 게임 라이브러리나 전체 디스크 스캔 시 시간 초과될 수 있음
    • 처리:
      1. 거름: os.scandir를 사용하여 루트 디렉터리 아래 5GB 이상의 폴더만 스캔, 즉시 완료
      2. 드릴다운: tree_size_scanner.py로 큰 폴더를 단계별로 깊이 들어감
      3. 지정 검색: find_folders_by_keyword.py로 깊이가 제한된(≤6단계) 디렉터리 이름 키워드 일치, 크기 계산 없음, 시간 초과 방지
      4. 위 세 단계로도 찾을 수 없는 경우에만 전체 디스크 재귀 고려

스크립트 도구 목록

  • scripts/tree_size_scanner.py <path> [min_mb] [max_depth] — 계층적 드릴다운 스캔, 루트 디렉터리에서 가장 큰 폴더를 단계별로 깊이 들어가 디스크 점유 맵 생성
  • scripts/scan_large_folders.py <path> — 지정된 경로 아래의 큰 폴더를 빠르게 스캔 (깊이 제한으로 시간 초과 방지)
  • scripts/scan_programdata.py — C:\ProgramData를 지정 스캔, 보안 수준별로 큰 폴더 분류 출력
  • scripts/find_folders_by_keyword.py <path> <pattern> — 키워드로 폴더 이름 심층 검색 (6단계 깊이, 크기 계산 안 함, 초고속)
  • scripts/find_zombie_packages.py — 전역 pip 환경 분석, 최상위 패키지 및 종속성 충돌 나열
  • scripts/cleanup_temp.ps1 [-WhatIf] — Temp, 브라우저 캐시, pip cache, WinSxS 안전 정리 (미리보기 모드 지원)
  • scripts/robocopy_wipe.py <target> — robocopy empty trick을 사용하여 고집스러운 폴더 삭제 (경로 보안 검사 포함)

출력 템플릿

사용자에게 보고할 때 다음 표 템플릿을 사용하세요:

영역크기위험권장 사항
......🟢/🟡/🔴...

정리 후 보고:

드라이브 문자정리 전 사용 가능정리 후 사용 가능확보된 공간
............

관련 스킬