msd-core/docs/ko-KR/how-to/recover-and-troubleshoot.md

복구 및 문제 해결 방법

목표: 조건부 레시피 구조를 사용하여 컨텍스트 손실과 손상된 상태부터 설치 실패와 권한 오류까지 일반적인 문제를 식별하고 수정합니다.

사전 조건: MSD Core가 설치되어 있어야 합니다. 설치 문제의 경우 런타임에 설치를 참조하세요.

---

컨텍스트 및 세션 문제

현재 위치를 파악하지 못한 경우

/msd-progress

모든 상태 파일을 읽고 현재 위치와 다음 할 일을 정확히 알려줍니다.

올바른 다음 단계로 자동 진행하려면:

/msd-progress --next

새 세션을 시작하고 컨텍스트를 복원해야 하는 경우

/msd-resume-work

마지막 핸드오프의 전체 세션 컨텍스트(현재 페이즈, 계획 결정, 작업이 중단된 위치)를 복원합니다.

긴 세션 중 품질이 저하되는 경우

주요 명령 사이에 컨텍스트 창을 초기화합니다:

/clear

그다음 상태를 복원합니다:

/msd-resume-work

MSD는 새로운 컨텍스트를 중심으로 설계되었습니다. 모든 서브에이전트는 이미 깨끗한 200k 창을 받습니다. 메인 세션은 시간이 지남에 따라 저하됩니다 — 초기화하고 재개하는 것이 올바른 해결책이며 계속 밀어붙이는 것이 아닙니다.

중단 전에 컨텍스트를 저장하고 싶은 경우

/msd-pause-work

현재 위치가 있는 .planning/HANDOFF.json을 생성합니다. 세션 후 요약도 .planning/reports/에 작성하려면 --report를 추가합니다:

/msd-pause-work --report

---

계획 무결성 문제

.planning/ 무결성이 불확실한 경우

/msd-health

오류, 경고, 정보 메모에 걸쳐 상태를 보고합니다:

상태	의미
HEALTHY	모든 예상 아티팩트가 존재하고 올바른 형식
DEGRADED	처리해야 하지만 작업을 계속할 수 있는 경고
BROKEN	실행을 차단하는 심각한 오류

일반적인 자동 복구 가능한 문제(오류 E004, E005; 경고 W003, W008):

/msd-health --repair

누락된 STATE.md를 재생성하고, 손상된 config.json을 기본값으로 재설정하며, 누락된 구성 키를 추가합니다. PROJECT.md나 ROADMAP.md를 덮어쓰지 않습니다.

STATE.md가 존재하지 않는 페이즈를 참조하는 경우

이것은 경고 W002를 생성합니다. 상태 CLI를 사용하여 진단하고 복구합니다:

node "$HOME/.claude/msd-core/bin/msd-tools.cjs" state validate

쓰기 없이 동기화가 변경할 내용 미리 보기:

node "$HOME/.claude/msd-core/bin/msd-tools.cjs" state sync --verify

동기화 적용:

node "$HOME/.claude/msd-core/bin/msd-tools.cjs" state sync

이 명령들은 디스크의 실제 프로젝트 상태에서 STATE.md를 재구성합니다. 수동 STATE.md 편집을 대체합니다.

"Project already initialised"가 표시되는 경우

.planning/PROJECT.md가 이미 있습니다. /msd-new-project는 안전 확인입니다. 정말로 처음부터 다시 시작하고 싶다면 먼저 .planning/ 디렉터리를 삭제합니다:

rm -rf .planning/

그다음 /msd-new-project를 다시 실행합니다.

컨텍스트 창 사용률이 높은 경우

/msd-health --context

컨텍스트 창 사용률 가드를 프로브합니다. 60%에서 경고, 70%에서 위험. 경고 임계값을 초과한 경우 다음 주요 명령을 시작하기 전에 /clear를 실행한 후 /msd-resume-work를 실행합니다.

---

실행 문제

실행자가 Bash 명령에서 "Permission denied"를 받는 경우

MSD의 msd-executor 서브에이전트는 쓰기 가능한 Bash 접근이 필요합니다. ~/.claude/settings.json의 permissions.allow 아래에 필요한 패턴을 추가합니다. 최소한:

"Bash(git add:*)",
"Bash(git commit:*)",
"Bash(git merge:*)",
"Bash(git checkout:*)"

스택별 패턴(Rails, Python, Node, Rust)은 docs/USER-GUIDE.md의 "Executor Subagent Gets Permission denied" 섹션의 전체 표를 참조하세요.

프로젝트별 대안: 프로젝트 루트의 .claude/settings.local.json에 동일한 블록을 추가합니다.

실행이 실패하거나 스텁을 생성하는 경우

플랜이 너무 야심찬지 확인합니다. 플랜에는 최대 두세 개의 작업이 있어야 합니다. 작업이 너무 크면 단일 컨텍스트 창이 안정적으로 생성할 수 있는 것을 초과합니다. 더 작은 범위로 페이즈를 다시 계획합니다:

/msd-plan-phase 1

무엇이 잘못되었는지에 대한 체계적인 진단은 실패한 실행 디버그를 참조하세요.

병렬 실행이 빌드 잠금 오류 또는 사전 커밋 훅 실패를 일으키는 경우

이것은 여러 에이전트가 동시에 빌드 도구를 트리거하여 발생합니다. MSD는 v1.26 이후 이를 자동으로 처리합니다. 오래된 버전이거나 여전히 경합이 보이면 병렬 실행을 비활성화합니다:

/msd-settings

parallelization.enabled를 false로 설정합니다.

서브에이전트가 실패한 것처럼 보이지만 커밋이 만들어진 경우

무언가가 고장났다고 결론 내리기 전에 git 로그를 확인합니다:

git log --oneline -10

알려진 Claude Code 분류 버그로 인해 작업이 성공했는데도 실패를 보고할 수 있습니다. MSD의 오케스트레이터는 실제 출력을 점검하지만 불일치가 보이면 커밋이 실제 근거입니다.

---

플랜 및 페이즈 문제

플랜이 의도와 맞지 않거나 잘못 정렬된 경우

계획 전에 /msd-discuss-phase N을 실행합니다. 대부분의 플랜 품질 문제는 CONTEXT.md가 방지했을 가정에서 발생합니다:

/msd-discuss-phase 1

전체 세션을 시작하지 않고 MSD가 현재 어떤 가정을 하는지 보려면:

/msd-discuss-phase 3 --assumptions

실행 후 무언가를 변경해야 하는 경우

/msd-execute-phase를 다시 실행하지 마세요. 대상이 되는 수정에는 /msd-quick을 사용합니다:

/msd-quick "Fix the login button not responding on mobile Safari"

또는 /msd-verify-work N을 사용하여 UAT를 통해 체계적으로 문제를 식별하고 수정합니다.

명령이 "Spawning…"에서 멈춘 것처럼 보이는 경우

기다리세요. MSD 서브에이전트는 별도의 컨텍스트 창에서 실행됩니다. 진행 중일 때는 상위 세션에서 보이지 않습니다. 스폰 라인의 활성 상태 메모가 이것이 예상된 동작임을 확인합니다. 연구 및 계획 에이전트는 일상적으로 1~5분이 걸립니다. 검증 에이전트는 대규모 페이즈에서 더 오래 걸릴 수 있습니다.

세션을 중단하지 마세요. 종료하면 진행 중인 서브에이전트 작업이 버려집니다.

10분 이상 지난 경우 Claude Code 사이드바에서 에이전트 작업이 여전히 활성으로 표시되는지 확인합니다.

---

워크플로 상태 문제

워크플로가 손상되거나 상태가 일관성이 없어 보이는 경우

/msd-forensics

또는 설명과 함께:

/msd-forensics "Phase 3 execution stalled after wave 1"

/msd-forensics는 사후 분석 조사를 실행합니다: git 히스토리 이상 감지, 아티팩트 무결성, STATE.md 일관성, 커밋되지 않은 작업, 고아 워크트리. .planning/forensics/에 보고서를 작성하고 권장 복구 단계를 제시합니다. 읽기 전용이며 프로젝트 파일을 절대 수정하지 않습니다.

페이즈 또는 플랜을 롤백해야 하는 경우

/msd-undo --phase 03          # 페이즈 3의 모든 커밋 롤백
/msd-undo --plan 03-02        # 페이즈 3의 플랜 02 커밋 롤백
/msd-undo --last 5            # 가장 최근 MSD 커밋 5개에서 대화식으로 선택

/msd-undo는 되돌리기 전에 종속 페이즈를 확인하고 항상 확인 게이트를 표시합니다.

---

설치 및 업데이트 문제

설치 후 MSD가 인식되지 않는 경우

런타임을 재시작합니다. MSD는 런타임의 명령 디렉터리(예: ~/.claude/commands/msd/)에 슬래시 명령을 설치합니다. 대부분의 런타임은 시작 시에만 새 명령을 발견합니다.

문제가 지속되면 설치를 확인합니다:

npx @golem15/msd-core@latest --claude --local

런타임별 설치 경로와 문제 해결은 런타임에 설치를 참조하세요.

업데이트가 로컬 변경 사항을 덮어쓴 경우

v1.17 이후 인스톨러는 로컬에서 수정된 파일을 msd-local-patches/에 백업합니다. 변경 사항을 재적용합니다:

/msd-update --reapply

npm을 통한 업데이트가 불가능한 경우

npm 중단이나 네트워크 제한으로 npx @golem15/msd-core가 실패하는 경우 npm 접근 없이도 작동하는 단계별 수동 업데이트 절차는 docs/manual-update.md를 참조하세요.

일상적인 업데이트는 MSD 업데이트를 참조하세요.

---

비용 문제

모델 비용이 너무 높은 경우

예산 프로필로 전환합니다:

/msd-config --profile budget

도메인이 익숙한 경우 설정에서 연구 및 플랜 체크 에이전트를 비활성화합니다:

/msd-settings

활성화된 MCP 서버도 감사합니다. 활성화된 모든 MCP 서버는 모든 턴에 도구 스키마를 주입합니다. 브라우저 및 플랫폼별 도구는 각각 20k+ 토큰이 소요될 수 있습니다. 현재 페이즈에 필요하지 않은 것은 .claude/settings.json에서 비활성화합니다:

{
  "disabledMcpjsonServers": ["playwright", "mac-tools"]
}

---

복구 빠른 참조

문제	해결책
컨텍스트 손실 또는 새 세션	/msd-resume-work 또는 /msd-progress
다음 단계를 모름	/msd-progress --next
페이즈가 잘못됨	/msd-undo --phase NN, 그다음 다시 계획
무언가 고장남	/msd-debug "description" (수정 없이 분석만 하려면 --diagnose 추가)
STATE.md 동기화 오류	state validate 후 state sync
.planning/ 무결성 불확실	/msd-health, 그다음 /msd-health --repair
워크플로 상태 손상	/msd-forensics
빠른 대상 수정	/msd-quick
플랜이 비전과 맞지 않음	/msd-discuss-phase N 후 다시 계획
비용이 높아짐	/msd-config --profile budget 및 /msd-settings에서 에이전트 끄기
업데이트가 로컬 변경 사항 손상	/msd-update --reapply
세션 요약 원함	/msd-pause-work --report
병렬 실행 빌드 오류	MSD 업데이트 또는 parallelization.enabled: false 설정

---

관련 문서

• 실패한 실행 디버그
• 런타임에 설치
• 명령 참조
• 문서 인덱스