개발 환경 진단기 · env-doctor
「진단기 패밀리」 세 번째:
claude-md-doctor(설정) →skill-doctor(스킬) →env-doctor(환경). 앞의 두 개는 파일을 진단하고, 이건 기계를 진단합니다.
기존 정리 도구와의 차이점 (먼저 읽어주세요. 모든 동작을 결정합니다)
기존 Mac 정리 도구는 「어느 디렉토리가 크냐」에 답합니다. 본 진단기는 「이 도구 아직 쓰고 있냐」고 묻습니다.
용량은 스캔으로 알 수 있지만, 정체는 추론해야만 알 수 있습니다—nvm이 찌꺼기인지 판단하려면 셸 설정이 누구를 로드했는지, PATH에 누가 있는지, node가 실제로 누구에 의해 제공되는지, 디렉토리가 얼마나 오래 안 움직였는지를 동시에 봐야 합니다. 이것이 본 진단기의 유일한 차별화 포인트이며, 어떤 변경도 이것을 약화시켜선 안 됩니다.
⛔ 세 가지 철칙 (세부 사항은 references/safety.md 참조)
- 삭제는 사용자가 항목별로 선택해야만 가능 (
scripts/clean.sh를 통해). 모델이 직접rm을 조합해 실행하지 않음; 사용자가 「그냥 지워줘」라고 말하면 → 선택기 실행을 안내합니다. 기본적으로 모두 선택 해제, 데이터 유형은 잠금, 허용 목록 명령어만 실행,yes를 입력해야 실행. - 읽기 전용 스캔.
scripts/scan.sh는 어떤 쓰기 작업도 포함하지 않음. - 확실하지 않으면 확실하지 않다고 말함. 신호가 모순될 때는如实 표시하며, 보고서를 좋게 보이려고 추측하지 않음.
표준 절차
1단계 · 스캔
bash scripts/scan.sh # 전체 (홈 디렉토리 큰 항목 발견 포함, 약 30–60초)
bash scripts/scan.sh --quick # 빠른 스캔 (발견 스캔 건너뜀, 약 20초)
bash scripts/scan.sh --profile ai-dev # AI 개발 머신 빠른 스캔 (Agent 호스트 디렉토리 + 큰 항목 발견 건너뜀)
여섯 개의 원시 데이터 섹션 출력: DISK · SIZES · MANAGERS · RUNTIME · AI_AGENTS (Agent 호스트가 있을 때) · DISCOVER (전체 스캔만).
2단계 · 판정
references/rules.md 참조:
- 삼분법 (데이터 / 캐시 / 잔여)으로 각 디렉토리 정체 파악;
- 네 가지 신호 판정표 (shell_loaded × cmd_in_path × runtime owner × last_modified)로 버전 매니저 활성/잔여 판별;
- 동일 버전이 두 매니저에 각각 설치됨 → 별도 항목으로 경고.
3단계 · 보고서 작성
references/report.md의 4단계 대화 흐름에 따름: 결론 먼저 → 세 그룹으로 제시 (잔여→캐시→데이터) → 그룹별로 사용자에게 질문 → 확인 후 명령어 블록 생성.
⚠️ 수십 줄의 목록을 한 번에 사용자에게 던지지 마세요; ⚠️ 각 권장 사항에는 반드시 「무엇인지 / 크기 / 판단 근거 / 공식 명령어 / 비용」 다섯 가지 요소가 포함되어야 합니다.
4단계 · 정리하고 싶다면, 선택기에 맡기세요
bash scripts/clean.sh --dry-run # 먼저 실행하지 않고 확인 (처음에는 강력 권장)
bash scripts/clean.sh # 선택 후 정리
대화형 선택: 스페이스바 선택 · ↑↓ 이동 · a 모두 선택 · n 모두 해제 · 엔터 확인 · q 종료.
데이터 유형은 🔒 잠겨 있어 선택 불가; 확인 페이지에서 실행될 명령어와 비용을 하나씩 나열하며, yes를 입력해야 실행.
라우팅
| 하려는 작업 | 읽을 문서 |
|---|---|
| 특정 디렉토리가 어떤 유형인지, 공식 정리 명령어가 무엇인지 판단 | references/rules.md |
| 보고서 작성 방법, 대화 진행 방법 | references/report.md |
| 경계는 무엇인지, 절대 하면 안 되는 것은 무엇인지 | references/safety.md |
| 스캐너 구현 및 자체 점검 | scripts/scan.sh |
| 정리 선택기 (유일하게 삭제 허용) | scripts/clean.sh |
자주 묻는 질문에 대한 표준 답변
- 「그냥 지워줘」 → 제가 엔터를 대신 누르지 않습니다.
bash scripts/clean.sh를 실행하여 선택하세요. 그러면 명령어와 비용을 먼저 보여줍니다; 실행하지 않고 먼저 확인하려면--dry-run을 추가하세요. - 「가장 큰 거 지워도 돼?」 → 먼저 정체를 보세요, 용량을 보지 마세요. 가장 큰 것은 보통 모델 가중치나 컨테이너 볼륨(데이터 유형)이며, 정확히 지우면 안 되는 것입니다.
- 「지우면 어떻게 돼?」 → 각 항목마다 「비용」 칸이 있습니다; 캐시 유형은 「다시 다운로드해야 하며, 시간과 트래픽이 듭니다」, 잔여 유형은 순수 이득입니다.
- 「왜 잔여라고 판단했어?」 → 네 가지 신호 원문을 보고하여 사용자가 직접 재확인하도록 합니다.
경계
- 개발 도구 점유만 다룹니다 (버전 매니저 / 패키지 매니저 / 빌드 캐시 / 컨테이너 / AI 모델). 시스템 캐시, 사진, 메일 첨부파일, WeChat은 범위 밖입니다—그것들은 시스템의 「저장 공간」 화면에 맡기세요.
- 홈 디렉토리 범위 내에서 스캔하며, 시스템 디렉토리나 다른 사용자 디렉토리는 건드리지 않습니다.
- 인터넷에 연결하지 않으며, 어떤 스캔 결과도 업로드하지 않습니다.
진단기 패밀리 상호 연결
| 계층 | Skill | 전환 시점 |
|---|---|---|
| 설정 | hekouwang-claude-md-doctor-skill | AGENTS.md/CLAUDE.md 중복, 라우팅 오류, frontmatter 누락 |
| 스킬 | hekouwang-claude-skill-doctor-skill | SKILL.md 구조, 끊긴 링크, OpenClaw 선언 |
| 환경 | 본 skill | 디스크 꽉 참, 버전 매니저 잔여, AI 호스트 디렉토리 비대 |
보고서에서 설정/스킬 문제를 발견하면 다른 두 개를 언급하고, 본 보고서에서 파일 내용 감사를 강행하지 마세요.