---
title: "트러블슈팅"
weight: 150
description: "스킬 체인 실패를 증상별로 진단·재시도·롤백하는 방법."
geekdocBreadcrumb: true
tags: [cookbook, troubleshooting]
---
> 스킬 체인이 기대대로 흘러가지 않을 때 읽는 페이지입니다. 증상 → 원인 후보 → 다음 액션 순서로 정리했습니다.

{{< hint type="note" >}}
시스템 레이어(앱·로그인·플러그인 설치·MCP)의 트러블슈팅은 [Cowork 트러블슈팅](../../cowork/troubleshooting/)을, 시스템 한도는 [제약과 한도](../../cowork/constraints/)를 함께 보세요. 본 페이지는 **체인 단계의 실패 진단**에 집중합니다.
{{< /hint >}}

## 학습 목표

- 체인 실패를 **스킬 단위 / 체인 단위 / 산출물 단위**로 분리해 진단할 수 있다
- 재시도 시 프롬프트를 어떻게 보강해야 할지 판단할 수 있다
- 롤백 시점을 판단해 되돌아갈 체크포인트를 지정할 수 있다

## 선수 지식

- [스킬 체이닝 가이드](../skill-chaining/)
- [FAQ — 스킬·플러그인 호출](../../cowork/faq/)

## 진단 3단계

```mermaid
flowchart TD
    Start["체인 실패"] --> Q1{"어느 단계에서<br/>멈췄는가?"}
    Q1 -- "스킬 미호출" --> A1["호출 누락"]
    Q1 -- "중간 결과만" --> A2["중간 중단"]
    Q1 -- "파일 생성됨" --> Q2{"어떤 증상인가?"}
    Q2 -- "내용 부정확" --> A3["산출물 불일치"]
    Q2 -- "파일 안 열림" --> A4["형식 깨짐"]
    Q2 -- "AI 어투 남음" --> A5["검수 누락"]

    A1 --> R["원인 후보 1개씩 차단"]
    A2 --> R
    A3 --> R
    A4 --> R
    A5 --> R

    style Start fill:#f5dcd7,stroke:#c44a3a,color:#09110f
    style R fill:#e6f0ef,stroke:#144a46,color:#09110f
```

1. **어느 단계에서 멈췄는가** — 체인이 완결되지 않았다면 마지막으로 응답을 남긴 스킬이 무엇인지 먼저 특정합니다. 도메인 스킬이었는지, 포맷 스킬이었는지, `ai-slop-reviewer` 직전이었는지에 따라 대응이 다릅니다.
2. **어떤 증상인가**
   - **호출 누락** — 스킬이 아예 트리거되지 않음
   - **중간 중단** — 중간 단계에서 멈추고 결과 반환
   - **산출물 불일치** — 파일은 생성됐으나 내용이 부정확
   - **형식 깨짐** — DOCX/PPTX가 열리지 않거나 레이아웃이 어긋남
   - **AI 어투 잔존** — 검수 단계 누락
3. **원인을 가정하고 1개씩 차단** — 가능한 원인이 여러 개라면 **가장 흔한 것부터** 하나씩 차단합니다. 한 번에 두 곳을 바꾸면 무엇이 고쳤는지 알 수 없습니다.

## 증상별 패턴 10선

### 1. 스킬 트리거 실패

- **원인 후보**: 트리거 키워드 부재 · 플러그인 미설치 · 다른 스킬과 경쟁
- **다음 액션**: 요청문에 스킬 이름을 명시 (예: "사업계획서 써줘 — `strategy-planner` 사용")

### 2. 포맷 스킬로 인계 안 됨

- **원인 후보**: 도메인 스킬 응답이 너무 짧아 체인 연결 트리거가 약함
- **다음 액션**: "방금 결과를 DOCX로 만들어줘"라고 후속 요청

### 3. `ai-slop-reviewer` 누락

- **원인 후보**: 체인 마지막이 파일 생성에서 종료
- **다음 액션**: "이 문서 AI 슬롭 검수해줘"라고 이어서 요청

### 4. Windows MAX_PATH

- **원인 후보**: 세션 경로가 260자 초과
- **다음 액션**: 짧은 경로(`C:\docs\`)로 파일 복사 후 열기

### 5. DOCX 표 레이아웃 깨짐

- **원인 후보**: 도메인 스킬 출력에 마크다운 표가 너무 큼
- **다음 액션**: 표를 분할 요청하거나 PPTX로 전환

### 6. PPTX 글꼴 누락

- **원인 후보**: 시스템에 `Pretendard`·한글 명조 미설치
- **다음 액션**: 폰트 설치 또는 기본 폰트로 재생성 요청

### 7. 이미지 생성 API 키 없음

- **원인 후보**: `GEMINI_API_KEY` 미설정
- **다음 액션**: `moai-media/CONNECTORS.md` 참고해 `.moai/credentials.env`에 등록

### 8. 긴 작업 중단

- **원인 후보**: 세션 컨텍스트 상한 도달
- **다음 액션**: 프로젝트·메모리로 이전, 단계 분할 재시도

### 9. 체인이 무한 루프

- **원인 후보**: 포맷 스킬을 두 번 호출 (예: DOCX → DOCX 재생성)
- **다음 액션**: 체인 재설계, 원본을 기준으로 한 번만 포맷 변환

### 10. 검수 후 내용이 오히려 어색

- **원인 후보**: `ai-slop-reviewer`가 도메인 전문 용어를 일반어로 치환
- **다음 액션**: 검수 전 "의학·법률·금융 용어는 보존"이라고 명시

## 롤백 가이드

{{< hint type="note" >}}
**되돌리기 원칙**: 체인 중간에 원본 프롬프트와 직전 산출물을 **세션 내 북마크**로 저장해두면 문제 시 해당 지점으로 복귀해 재시도할 수 있습니다.
{{< /hint >}}

## 자가 점검

{{< hint type="note" >}}
- Q. 방금 체인이 중단된 지점을 스킬 이름으로 말할 수 있나요? (쉬움·이해)
- Q. 증상 10선 중 본인이 겪은 것과 가장 가까운 것은? 원인 후보를 하나씩 차단했나요? (중간·적용)
- Q. 체인을 처음부터 재실행하지 않고 마지막 실패 단계부터 이어가려면 어떻게 프롬프트를 써야 할까요? (어려움·창조)
{{< /hint >}}

## 다음 단계

- [스킬 체이닝 가이드](../skill-chaining/) — 체인 설계 3원칙 복습

---

### Sources

- [modu-ai/cowork-plugins — Issues](https://github.com/modu-ai/cowork-plugins/issues)
- [Anthropic 지원센터](https://support.claude.com)
