Claude Code /checkup 설명: 깔끔한 컨텍스트, 설정 수정, 에이전트 안전성 향상

소개

Claude Code에 더 강력해진 내장 설정 점검 기능이 추가되었습니다. Anthropic은 버전 2.1.205에서 기존 /doctor 워크플로를 확장하여 구성 문제를 진단하고 해결을 도울 수 있도록 했습니다. /checkup은 동일한 세션 내 워크플로의 별칭으로 사용할 수 있습니다.

이 변경 사항은 단일 슬래시 명령어로 실행되기 때문에 작아 보일 수 있습니다. 실제로는 장기 실행되는 Claude Code 환경에서 흔히 발생하는 문제를 해결합니다: 사용하지 않는 스킬, 오래된 Model Context Protocol 서버, 과도하게 큰 명령어 파일, 느린 후크, 오래된 설치, 반복적인 권한 프롬프트 등이 점차 환경을 이해하기 어렵게 만듭니다.

목표는 단순히 문제가 있다고 보고하는 것만이 아닙니다. 업데이트된 점검 기능은 설정을 검사하고, 제안된 변경 사항을 설명하며, 적용하기 전에 승인을 요청할 수 있습니다.

/checkup

표준 명령어도 사용할 수 있습니다:

/doctor

원클릭 설정 점검

Claude Code 2.1.205 변경 로그에 따르면, /doctor는 이제 문제를 진단하고 수정할 수 있는 완전한 설정 점검 기능이며, /checkup은 그 별칭입니다.

이는 별도의 터미널 명령어와 다릅니다:

claude doctor

터미널 명령어는 대화형 세션을 시작하지 않고 읽기 전용의 설치 및 설정 진단 정보를 출력합니다. 반면 세션 내 /doctor 또는 /checkup 워크플로는 수정 사항을 제안하고 Claude가 사용 가능한 도구를 통해 정리를 조정할 수 있도록 하여 더 나아갈 수 있습니다.

Claude Code 제작자 Boris Cherny는 점검 기능이 처리하도록 설계된 여러 작업을 설명했습니다:

1. 사용하지 않는 스킬, MCP 서버 및 플러그인 정리
2. 로컬 CLAUDE.md 명령어와 체크인된 프로젝트 명령어 중복 제거
3. 과도하게 큰 루트 CLAUDE.md를 중첩 파일과 재사용 가능한 스킬로 분할
4. 느린 후크 식별 및 비활성화
5. Claude Code를 최신 버전으로 업데이트
6. 적절한 경우 기본적으로 자동 모드 활성화
7. 자주 거부되는 읽기 전용 명령어 사전 승인
8. 환경을 느리게 하거나 덜 안정적으로 만드는 기타 설정 문제 감지

명령어는 변경 사항을 적용하기 전에 확인을 요청합니다.

점검 기능이 실제로 검토하는 내용

1. 사용하지 않는 스킬, MCP 서버 및 플러그인

Claude Code는 스킬, 플러그인, 후크 및 MCP 서버로 확장할 수 있습니다. 이러한 통합은 유용하지만, 성숙한 환경에서는 더 이상 필요하지 않은 구성 요소가 축적되는 경우가 많습니다.

관련 없는 점검

오래된 이슈 트래커를 위해 MCP 서버가 추가되었을 수 있습니다. 팀에서 더 이상 사용하지 않는 워크플로우를 위해 스킬이 생성되었을 수 있습니다. 명령어가 대체되었음에도 플러그인이 계속 활성화되어 있을 수 있습니다.

점검을 통해 이러한 사용하지 않는 구성 요소를 발견하고 이를 제거하거나 비활성화하도록 제안할 수 있습니다.

이것이 중요한 이유는 도구와 명령어가 현재 작업에 적극적으로 도움이 되지 않더라도 주의력과 맥락을 소모할 수 있기 때문입니다. 관련 없는 통합이 적을수록 권한 모델을 감사하기도 더 쉬워집니다.

2. 중복되거나 과도하게 큰 CLAUDE.md 명령어

CLAUDE.md 파일은 Claude Code에 지속적인 명령어를 제공합니다. 여기에는 빌드 명령어, 코딩 규칙, 아키텍처 참고 사항, 테스트 요구 사항 및 프로젝트별 규칙이 포함될 수 있습니다.

이러한 파일은 세션 컨텍스트에 로드됩니다. Anthropic은 각 파일을 간결하게 유지하고 중첩된 명령어 파일을 오래되었거나 충돌하는 규칙이 있는지 정기적으로 검토할 것을 권장합니다.

시간이 지남에 따라 프로젝트에서 몇 가지 일반적인 문제가 발생할 수 있습니다:

• 로컬 파일과 체크인된 파일에 동일한 규칙이 나타납니다.
• 코드베이스가 변경된 후에도 이전 명령어가 남아 있습니다.
• 루트 파일이 관련 없는 절차의 긴 모음으로 커집니다.
• 팀 전체 규칙과 디렉터리별 규칙이 혼합됩니다.
• 상세한 워크플로우가 주문형 스킬로 더 잘 작동함에도 CLAUDE.md에 저장됩니다.

점검을 통해 로컬 및 프로젝트 명령어를 비교하고 중복을 식별하며 더 집중된 구조를 제안할 수 있습니다.

실용적인 레이아웃은 다음과 같을 수 있습니다:

project/
├── CLAUDE.md
├── .claude/
│   ├── rules/
│   │   ├── frontend.md
│   │   ├── backend.md
│   │   └── testing.md
│   └── skills/
│       └── release/
│           └── SKILL.md
└── packages/
    └── api/
        └── CLAUDE.md

루트 파일에는 전체 저장소에 필요한 규칙만 포함될 수 있습니다. 더 구체적인 명령어는 Claude가 관련 디렉터리 내에서 작업할 때 로드되고, 재사용 가능한 절차는 호출될 때 로드되는 스킬이 될 수 있습니다.

3. 느리거나 중복된 훅

훅은 Claude Code 라이프사이클의 특정 지점에서 실행되는 결정론적 작업입니다. 파일 형식 지정, 명령어 검증, 정책 시행, 알림 전송 또는 Claude Code를 내부 시스템과 통합할 수 있습니다.

훅은 그 가치가 비용을 정당화할 때만 유용합니다. 모든 도구 호출에 2~3초를 추가하는 스크립트는 긴 세션 동안 큰 지연을 만들 수 있습니다.

점검을 통해 다음 상태의 훅을 식별하는 데 도움이 될 수 있습니다:

• 지속적으로 느린 경우
• 의도한 것보다 더 자주 트리거되는 경우
• 다른 검증 단계를 중복하는 경우
• 더 이상 존재하지 않는 스크립트를 참조하는 경우
• 사용자가 무시하는 법을 배운 오류를 생성하는 경우
• 더 이상 활성 워크플로우에 연결되지 않은 경우

불필요한 훅을 비활성화하면 속도만 향상되는 것이 아닙니다. 또한 잡음을 줄여 중요한 실패를 더 쉽게 알아차릴 수 있습니다.

4. 설치 및 업데이트 문제

손상된 런처, 오래된 설치 또는 부분 업데이트는 혼란스러운 동작을 만들 수 있습니다. 설정 점검을 통해 설치 상태를 검사하고 Claude Code 업데이트를 권장할 수 있습니다.

설치된 버전을 수동으로 확인하려면 다음을 사용하세요:

claude --version

정확한 업데이트 방법은 Claude Code가 설치된 방식에 따라 다릅니다.

관리형 엔터프라이즈 배포에서는 의도적으로 특정 버전을 고정할 수 있으므로, 사용자는 단순히 새로운 릴리스가 존재한다는 이유로 조직 정책을 무시해서는 안 됩니다.

5. 반복적인 읽기 전용 권한 요청

Claude Code는 위험이 낮은 검사와 환경을 변경하는 작업을 분리하는 권한 시스템을 사용합니다.

Anthropic의 보안 문서에 따르면, ls, cat, git status와 같은 명령어를 포함한 내장된 읽기 전용 명령어 세트는 프롬프트 없이 실행될 수 있습니다. 파일을 편집하거나 잠재적으로 Bash 작업을 수정하거나 추가 시스템에 액세스하는 명령어는 승인이 필요할 수 있습니다.

사용자가 무해한 읽기 전용 명령어를 반복적으로 거부하거나 수동으로 승인하는 경우, 체크업은 더 명확한 권한 규칙을 제안할 수 있습니다. 목표는 광범위한 쓰기 액세스를 허용하지 않으면서 프롬프트 피로를 줄이는 것입니다.

좋은 권한 규칙은 좁은 범위여야 합니다. 특정 읽기 전용 패턴을 승인하는 것은 전체 셸이나 도구 카테고리를 허용하는 것보다 안전합니다.

컨텍스트 유지가 중요한 이유

AI 코딩 에이전트는 여러 종류의 정보를 하나의 작업 컨텍스트에 맞춰야 합니다:

• 현재 대화.
• 관련 소스 파일.
• 도구 결과 및 명령어 출력.
• CLAUDE.md 지침.
• 스킬 설명.
• MCP 도구 정의.
• 계획, 작업 상태 및 중간 결과.

컨텍스트 창은 유한합니다. 관련 없는 설정 정보가 많으면 실제 문제를 위한 공간이 줄어들 수 있습니다.

이는 설치된 모든 스킬이나 MCP 서버가 자동으로 완전히 로드된다는 것을 의미하지 않습니다. Claude Code는 주문형 스킬 본문 및 도구 검색과 같은 메커니즘을 사용하여 컨텍스트 사용을 제어합니다. 그럼에도 불구하고 불필요한 구성은 추가적인 복잡성을 만들고 오래된 지침이나 통합이 세션에 영향을 미칠 가능성을 높입니다.

따라서 건강한 설정은 소프트웨어 프로젝트와 동일한 유형의 유지 관리가 필요합니다:

1. 더 이상 사용되지 않는 것을 제거하세요.
2. 글로벌 지침을 간결하게 유지하세요.
3. 특수 절차를 범위가 지정된 파일이나 스킬로 이동하세요.
4. 통합 및 권한을 감사하세요.
5. 후크의 비용을 측정하세요.
6. 주요 프로젝트 변경 후 설정을 재검토하세요.

진단에서 정리 지원으로

초기 진단 도구는 종종 오류를 나열한 후 중단되었습니다. 사용자는 여전히 모든 경고를 이해하고, 관련 파일을 찾고, 수정 방법을 결정하고, 수동으로 적용해야 했습니다.

업데이트된 세션 내 체크업은 더 에이전트적인 패턴을 따릅니다:

1. 현재 환경을 검사합니다.
2. 특정 문제를 식별합니다.
3. 정리의 이점을 추정합니다.
4. 제안된 변경 사항을 제시합니다.
5. 사용자가 전체 정리, 선택된 수정 또는 보고서 전용 옵션을 선택하도록 합니다.
6. 승인된 변경 사항만 적용합니다.
7. 검토를 위해 파일 수정 사항을 표시합니다.

이로 인해 워크플로우는 수동적인 오류 보고보다는 대화형 유지 관리 도우미에 더 가까워집니다.

승인 단계는 중요합니다. 도구는 승인 없이 변경을 수행해서는 안 됩니다.

단순히 설정이 비효율적이라고 판단했다는 이유만으로 프로젝트 스킬을 조용히 제거하거나, 명령어 파일을 다시 작성하거나, 권한 동작을 변경해서는 안 됩니다.

자율 명령어 관련 안전성 개선

동일한 릴리스에는 Claude Code가 더 자율적으로 작동할 때의 위험을 줄이기 위한 변경 사항도 포함되었습니다.

세션 로그에서 조작된 승인 방지

이제 백그라운드 작업 알림에는 사람의 입력이 없었을 때 이를 명시적으로 표시합니다. 이는 대화 기록 내의 텍스트가 실제 사용자 승인으로 오인되는 것을 방지하기 위한 것입니다.

에이전트에게 있어 "기록에 승인과 유사한 텍스트가 포함되어 있다"는 것과 "사용자가 인터페이스를 통해 실제로 이 작업을 승인했다"는 것은 근본적으로 다릅니다. 보안에 민감한 결정은 신뢰할 수 있는 승인 채널이 필요합니다.

위험한 rm -rf 명령어에 대한 추가 확인

변경 로그에는 자동 모드의 개선 사항도 포함되어 있습니다. Claude Code는 경로에 컨텍스트에서 확인할 수 없는 변수가 포함된 rm -rf를 실행하기 전에 확인을 요청합니다.

위험한 예시는 다음과 같습니다.

rm -rf "$TARGET_DIR/"

TARGET_DIR이 비어 있거나 잘못 확장되면 결과는 스크립트 작성자가 의도한 것과 크게 달라질 수 있습니다.

여기서 얻어야 할 올바른 교훈은 확인 프롬프트 하나로 파괴적인 셸 명령어가 안전해진다는 것이 아닙니다. 사용자는 여전히 확인된 경로를 검사하고, 가능하면 샌드박스 또는 일회용 환경을 사용하고, 백업을 유지하며, 프로덕션 시스템에서 광범위한 삭제 명령어를 피해야 합니다.

자율성에는 경계가 필요합니다

이번 릴리스는 상충되는 것처럼 보일 수 있는 두 가지 목표를 결합합니다.

• 일상적인 읽기 전용 작업에 대한 불필요한 중단을 줄입니다.
• 불확실하거나 파괴적인 작업에 대해 더 강력한 확인을 추가합니다.

이러한 목표는 함께 작동합니다. 유용한 에이전트는 명확하게 정의된 안전 영역 내에서 빠르게 움직이고, 돌이킬 수 없는 결과를 초래하는 경계에 가까워지면 속도를 늦춰야 합니다.

/doctor, /checkup, claude doctor

비슷한 이름 때문에 혼동될 수 있습니다.

명령어	실행 위치	주요 목적	수정 제안 또는 적용 가능 여부
/doctor	Claude Code 세션 내부	전체 설정 점검	예
/checkup	Claude Code 세션 내부	/doctor의 별칭	예
claude doctor	터미널, 세션 열지 않음	읽기 전용 설치 및 설정 진단	아니요

Claude가 현재 설정을 검사하고 정리하도록 하려는 대부분의 사용자에게는 /doctor 또는 /checkup이 적합한 명령어입니다.

스크립트, 지원 확인, 또는 세션 외부에서의 빠른 설치 진단에는 claude doctor가 더 적합합니다.

/checkup을 안전하게 실행하는 방법

1단계: 현재 저장소 상태 확인

도구가 구성 파일을 수정하도록 허용하기 전에 중요한 작업이 커밋 또는 백업되었는지 확인하십시오.

git status

커밋되지 않은 파일을 검토하고, 코드 변경과 구성 정리를 혼합하지 않도록 하십시오.

2단계: 의도한 프로젝트에서 Claude Code 시작

cd /path/to/project
claude

올바른 저장소에서 점검을 실행하는 것이 중요합니다. 프로젝트 명령어, 훅, 플러그인 및 MCP 설정이 범위 지정되어 있을 수 있기 때문입니다.

3단계: 점검 실행

/checkup

변경 사항을 수락하기 전에 보고서를 읽으십시오.

4단계: 범위 선택

Claude가 제안하는 내용에 따라

finds에서 인터페이스는 다음과 같은 옵션을 제공할 수 있습니다:

• 권장 정리 항목 적용
• 개별 카테고리 선택
• 현재 설정 유지 및 보고서 생성
• 결정 전 권장 사항 논의

저장소에 커스텀 내부 도구 또는 공유 팀 설정이 있는 경우 선택적 정리를 선호하세요.

5단계: Diff 검토하기

설정 파일이 변경된 후 다음 내용을 확인하세요:

git diff

특히 다음 항목에 주의하세요:

• CLAUDE.md 및 CLAUDE.local.md
• .claude/ 디렉토리 내 파일
• Hook 정의
• 플러그인 설정
• MCP 구성
• 권한 규칙
• 생성된 모든 스킬

6단계: 일반 워크플로우 테스트하기

일상적인 작업을 대표하는 태스크를 실행하세요. 필요한 도구가 여전히 작동하는지, 관련 지침이 정상적으로 로드되는지, Hook이 중요한 규칙을 계속 적용하는지, 권한 프롬프트가 예상대로 동작하는지 확인하세요.

7단계: 정리 항목을 별도로 커밋하기

공유 프로젝트 설정이 변경된 경우 집중된 커밋을 사용하면 팀원들이 독립적으로 검토하고 되돌릴 수 있습니다.

git add CLAUDE.md .claude/
git commit -m "chore: Claude Code 설정 정리"

실제로 변경된 파일에 맞게 경로를 조정하세요.

자동 정리를 즉시 수락하지 말아야 하는 경우

다음 상황에서는 검토 없이 모든 권장 사항을 승인하지 마세요:

• 저장소가 조직 관리 설정을 사용하는 경우
• MCP 서버가 비즈니스 크리티컬 통합을 제공하는 경우
• Hook이 보안 또는 규정 준수 정책을 적용하는 경우
• CLAUDE.md에 의도적으로 이식성을 위한 중복 내용이 포함된 경우
• 프로젝트가 테스트된 버전의 Claude Code에 고정된 경우
• 여러 팀이 동일한 플러그인 또는 명령어 계층 구조에 의존하는 경우
• 정리가 권한 동작 변경을 제안하는 경우
• 작업 트리에 관련 없는 커밋되지 않은 변경 사항이 있는 경우

이러한 경우 먼저 점검을 감사 보고서로 활용하세요. 팀의 일반적인 검토 프로세스를 통해 변경 사항을 논의하거나 적용하세요.

FAQ

Claude Code /checkup 명령어란 무엇인가요?

/checkup은 Claude Code 2.1.205에 도입된 확장된 세션 내 /doctor 워크플로우의 별칭입니다. 설정 문제를 감사하고 구성, 컨텍스트, 통합, Hook, 설치 상태 및 관련 문제에 대한 수정 사항을 제안할 수 있습니다.

/checkup과 /doctor는 다른가요?

현재 Claude Code 버전에서 /checkup은 /doctor의 별칭입니다. 대화형 Claude Code 세션 내에서 동일한 전체 설정 점검을 실행합니다.

claude doctor와 /doctor는 동일한가요?

아니요. claude doctor는 터미널에서 실행되며 세션을 열지 않고 읽기 전용 설치 및 설정 진단을 출력합니다. 슬래시 명령어는 승인을 요청한 후 수정 사항을 조정할 수 있습니다.

/checkup이 자동으로 스킬이나 MCP 서버를 삭제할 수 있나요?

워크플로우는 사용되지 않는 컴포넌트를 식별하고 정리를 제안할 수 있지만, 변경을 수행하기 전에 승인을 요청하도록 설계되었습니다. 특히 공유되거나 관리되는 프로젝트에서는 각 제안된 제거를 검토해야 합니다.

큰 CLAUDE.md가 Claude Code에 영향을 주는 이유는 무엇인가요?

CLAUDE.md 지침은 세션 컨텍스트에 포함되므로 길거나 중복된 파일은 활성 작업에 사용될 수 있는 공간을 소모합니다. Anthropic은 대규모 프로젝트에 대해 간결한 지침과 범위가 지정된 파일을 권장합니다.

모든 프로시저를 CLAUDE.md에서 이동해야 하나요?

아니요. 안정적인

프로젝트 팩트, 코딩 규칙, 필수 명령어는 CLAUDE.md에 포함되어야 합니다. 길고 재사용 가능한 절차는 필요할 때만 전체 내용이 로드되므로 스킬(skills)에 적합한 경우가 많습니다.

/checkup을 사용하면 자동 모드가 완전히 안전해지나요?

아니요. 기본값을 개선하고 보호 장치를 추가할 수는 있지만, 명령과 권한을 검토하는 책임은 여전히 사용자에게 있습니다. 파괴적인 작업, 외부 쓰기, 프로덕션 접근, 자격 증명 처리는 여전히 신중한 제어가 필요합니다.

설정(checkup)은 얼마나 자주 실행해야 하나요?

필요한 일정은 없습니다. 주요 구성 변경 후, Claude Code가 느리거나 일관성이 떨어질 때, 여러 통합을 추가한 후, 또는 정기적인 프로젝트 유지보수 검토의 일부로 실행하는 것이 유용합니다.

관련 도구

• Claude Code: Anthropic의 터미널, IDE, 데스크톱 및 웹용 에이전트 코딩 도구입니다.
• Claude Code Skills: Claude Code를 확장하는 재사용 가능한 온디맨드 절차를 생성합니다.
• Claude Code의 Model Context Protocol: Claude Code를 외부 도구, API, 데이터베이스 및 서비스에 연결합니다.
• Claude Code Hooks: 에이전트 수명 주기의 정의된 지점에서 결정론적 자동화를 실행합니다.
• Claude Code Plugins: 스킬, 에이전트, 훅 및 MCP 통합을 패키징하고 배포합니다.
• Claude Agent SDK: Claude Code에서 사용하는 것과 동일한 핵심 도구와 에이전트 루프로 프로그래밍 가능한 에이전트를 구축합니다.

관련 링크

• Claude Code 변경 로그: 버전 2.1.205 설정 검사(setup-checkup) 변경 사항을 포함한 공식 릴리스 내역입니다.
• Claude Code 명령어 참조: 내장 슬래시 명령어 및 번들 스킬에 대한 참조입니다.
• Claude Code CLI 참조: 터미널 명령 및 CLI 플래그에 대한 공식 참조입니다.
• Claude가 프로젝트를 기억하는 방법: CLAUDE.md 파일 구성 및 유지 관리에 대한 지침입니다.
• Claude Code 보안: 권한 동작, 샌드박싱, 승인 제어 및 안전 지침입니다.
• Claude Code 설정: 구성 범위, 관리 설정, 플러그인, MCP 정책 및 파일 시스템 제어입니다.
• Claude Code 문제 해결: 공식 진단 및 복구 지침입니다.
• 훅으로 작업 자동화: 수명 주기 훅 생성 및 감사에 대한 실용적인 지침입니다.

요약

Claude Code 2.1.205는 /doctor를 더 광범위한 설정 유지보수 워크플로우로 전환하고 /checkup을 별칭으로 추가합니다. 이 명령어는 사용되지 않는 확장 기능, 중복된 지침, 과도하게 큰 CLAUDE.md 파일, 느린 훅, 설치 문제를 검사할 수 있습니다.

및 반복적인 권한 부여 동작.

업데이트에서 가장 유용한 점은 유지보수를 단일 명령어 뒤에 숨기는 것이 아니라, 워크플로가 제안된 변경 사항을 설명하고 환경을 수정하기 전에 사용자를 계속 참여시킬 수 있다는 점입니다.

이번 릴리스는 에이전트 도구에 중요한 패턴을 강화합니다. 일상적인 읽기 전용 작업은 장애물을 최소화해야 하며, 불확실하거나 파괴적인 작업에는 더 강력한 보호 장치가 적용되어야 한다는 것입니다.

더 건강한 Claude Code 설정은 가장 많은 스킬, 훅, 통합을 가진 것이 아니라, 로드된 모든 구성 요소가 명확한 목적을 가지고 강력한 모든 작업에 적절한 경계가 있는 것입니다.