트러블슈팅

스킬 체인이 기대대로 흘러가지 않을 때 읽는 페이지입니다. 증상 → 원인 후보 → 다음 액션 순서로 정리했습니다.

Note
시스템 레이어(앱·로그인·플러그인 설치·MCP)의 트러블슈팅은 Cowork 트러블슈팅을, 시스템 한도는 제약과 한도를 함께 보세요. 본 페이지는 체인 단계의 실패 진단에 집중합니다.

학습 목표

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

선수 지식

진단 3단계

진단 3단계: 왜 이 순서로 진단하는가

체인(여러 스킬이 차례로 이어받아 실행되는 작업 연결선)이 기대대로 흘러가지 않으면 당황하기 쉽지만, 진단에는 정해진 순서가 있습니다. 병원 진료에 비유하면 이해하기 쉽습니다. 환자가 아프다고 오면 의사는 먼저 “어디가 아파?“라고 증상을 듣습니다. 그다음 이 증상에 보통 어떤 병이 의심되는지 원인 후보 몇 가지를 떠올립니다. 마지막으로 가장 가능성이 높은 병부터 하나씩 검사하고 처방하며 차단(원인을 하나씩 제거해가며 확인하는 일)해 나갑니다.

이때 한 번에 두 약을 같이 먹으면 나중에 나았을 때 어느 약 덕분인지 알 수 없듯, 원인도 한 번에 하나만 바꿔야 “이게 문제였구나"를 확실히 알 수 있습니다. 두 곳을 동시에 고치면 결과가 좋아졌을 때도 어느 수정이 효과를 냈는지, 혹은 한쪽 수정이 다른 쪽 수정을 덮어썼는지 분간할 수 없습니다. 그래서 진단은 항상 ① 어느 단계에서 멈췄는가 → ② 어떤 증상인가 → ③ 가장 흔한 원인부터 하나씩 차단 순서로 진행합니다.

flowchart TD
    Start["체인 실패"] --> Q1{"어느 단계에서
멈췄는가?"}
    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

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

증상별 패턴 10선

증상 10선: 체인이 끊기는 세 지점

10개 증상은 서로 달라 보이지만, 대부분 체인의 세 지점 중 한 곳에서 멈춘 모습입니다. 공장 컨베이어 벨트에 비유하면 이해가 쉽습니다. 요청이 들어오면 재료 손질(도메인 스킬, 분야 전문 지식을 담은 스킬) → 포장(포맷 스킬, DOCX·PPTX·XLSX 같은 문서 형식을 만드는 스킬) → 품질 검사(ai-slop-reviewer, AI 특유의 기계적 어투를 솎아내는 검수 스킬) 순으로 벨트가 굴러갑니다.

초보자가 가장 자주 겪는 세 가지는 모두 이 벨트가 멈추는 순간입니다. 트리거 실패는 첫 작업자가 작업 지시서를 못 받아 벨트 자체가 안 도는 것이고, 포맷 인계 실패는 손질만 끝나고 포장 담당에게 물건이 안 넘어간 것이며, ai-slop-reviewer 누락은 검사 담당이 자리를 비껴 불량품이 그대로 출하된 것입니다. 아래 일러스트는 정상 흐름(위쪽)과 세 가지 끊김 지점(아래쪽)을 시간 순서대로 보여줍니다.

sequenceDiagram
    participant U as 사용자
    participant D as 도메인 스킬
    participant F as 포맷 스킬
    participant Q as ai-slop-reviewer

    Note over U,Q: 정상 흐름
    U->>D: 자연어 요청
    D-->>F: 손질된 원고
    F-->>Q: 생성된 파일
    Q-->>U: 검수 완료 산출물

    Note over U,Q: 끊김 지점 3종

    Note over U,D: ① 트리거 실패
    U->>D: ❌ 스킬 미호출 (벨트 정지)

    Note over D,F: ② 포맷 인계 실패
    D-->>D: ⚠️ 다음 스킬로 안 넘어감

    Note over F,Q: ③ 검수 누락
    F-->>U: ❌ 검수 통과 안 한 채 반환

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가 도메인 전문 용어를 일반어로 치환
다음 액션: 검수 전 “의학·법률·금융 용어는 보존"이라고 명시

롤백 가이드

롤백: 언제, 어디까지 되돌릴까

롤백(rollback)은 문제가 생겼을 때 이전 상태로 되돌리는 일입니다. 비개발자에게는 낯선 단어지만, 요리 중 실수했을 때를 떠올리면 쉽습니다. 국이 너무 짜졌다고 해서 애초 밥을 안 하던 시점까지 완전히 되돌아갈 필요는 없습니다. 국 간만 다시 맞추는 지점에서 다시 시작하면 됩니다. 체인도 마찬가지로, 처음부터 다시 시작하는 게 아니라 마지막으로 잘 돌아간 단계부터 이어가는 것이 핵심입니다.

이때 중요한 습관이 체크포인트(북마크) 만들기입니다. 요리할 때 “여기까지는 잘 됐다"는 순간마다 맛을 보고 살짝 덜어두듯, 체인이 진행되는 동안 원본 프롬프트와 직전 산출물을 세션 안에 저장해두는 것입니다. 그러면 나중에 문제가 생겨도 처음부터 재료를 다시 썰 필요 없이 그 저장 지점부터 이어 요리할 수 있습니다. 실패한 단계 하나만 다시 하면 되므로 시간과 토큰(컴퓨터가 한 번에 읽는 텍스트 분량의 단위)을 크게 아껴줍니다.

flowchart LR
    Start["요청 입력"] --> CP1["체크포인트 1
도메인 완료"]
    CP1 --> CP2["체크포인트 2
포맷 완료"]
    CP2 --> Fail["❌ 검수 실패"]

    Fail --> Decide{"어디로
되돌릴까?"}
    Decide -- "처음부터" --> Start
    Decide -- "체크포인트 2" --> CP2
    CP2 -. 다시 시도 .-> Fail2["검수 재실행"]

    style CP1 fill:#e6f0ef,stroke:#144a46,color:#09110f
    style CP2 fill:#e6f0ef,stroke:#144a46,color:#09110f
    style Fail fill:#f5dcd7,stroke:#c44a3a,color:#09110f

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

자가 점검

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

다음 단계

스킬 체이닝 가이드 — 체인 설계 3원칙 복습