트러블슈팅
스킬 체인이 기대대로 흘러가지 않을 때 읽는 페이지입니다. 증상 → 원인 후보 → 다음 액션 순서로 정리했습니다.
Note시스템 레이어(앱·로그인·플러그인 설치·MCP)의 트러블슈팅은 Cowork 트러블슈팅을, 시스템 한도는 제약과 한도를 함께 보세요. 본 페이지는 체인 단계의 실패 진단에 집중합니다.
- 체인 실패를 스킬 단위 / 체인 단위 / 산출물 단위로 분리해 진단할 수 있다
- 재시도 시 프롬프트를 어떻게 보강해야 할지 판단할 수 있다
- 롤백 시점을 판단해 되돌아갈 체크포인트를 지정할 수 있다
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개씩 차단 — 가능한 원인이 여러 개라면 가장 흔한 것부터 하나씩 차단합니다. 한 번에 두 곳을 바꾸면 무엇이 고쳤는지 알 수 없습니다.
- 원인 후보: 트리거 키워드 부재 · 플러그인 미설치 · 다른 스킬과 경쟁
- 다음 액션: 요청문에 스킬 이름을 명시 (예: “사업계획서 써줘 —
strategy-planner사용”)
- 원인 후보: 도메인 스킬 응답이 너무 짧아 체인 연결 트리거가 약함
- 다음 액션: “방금 결과를 DOCX로 만들어줘"라고 후속 요청
- 원인 후보: 체인 마지막이 파일 생성에서 종료
- 다음 액션: “이 문서 AI 슬롭 검수해줘"라고 이어서 요청
- 원인 후보: 세션 경로가 260자 초과
- 다음 액션: 짧은 경로(
C:\docs\)로 파일 복사 후 열기
- 원인 후보: 도메인 스킬 출력에 마크다운 표가 너무 큼
- 다음 액션: 표를 분할 요청하거나 PPTX로 전환
- 원인 후보: 시스템에
Pretendard·한글 명조 미설치 - 다음 액션: 폰트 설치 또는 기본 폰트로 재생성 요청
- 원인 후보:
GEMINI_API_KEY미설정 - 다음 액션:
moai-media/CONNECTORS.md참고해.moai/credentials.env에 등록
- 원인 후보: 세션 컨텍스트 상한 도달
- 다음 액션: 프로젝트·메모리로 이전, 단계 분할 재시도
- 원인 후보: 포맷 스킬을 두 번 호출 (예: DOCX → DOCX 재생성)
- 다음 액션: 체인 재설계, 원본을 기준으로 한 번만 포맷 변환
- 원인 후보:
ai-slop-reviewer가 도메인 전문 용어를 일반어로 치환 - 다음 액션: 검수 전 “의학·법률·금융 용어는 보존"이라고 명시
Note되돌리기 원칙: 체인 중간에 원본 프롬프트와 직전 산출물을 세션 내 북마크로 저장해두면 문제 시 해당 지점으로 복귀해 재시도할 수 있습니다.
Note
- Q. 방금 체인이 중단된 지점을 스킬 이름으로 말할 수 있나요? (쉬움·이해)
- Q. 증상 10선 중 본인이 겪은 것과 가장 가까운 것은? 원인 후보를 하나씩 차단했나요? (중간·적용)
- Q. 체인을 처음부터 재실행하지 않고 마지막 실패 단계부터 이어가려면 어떻게 프롬프트를 써야 할까요? (어려움·창조)
- 스킬 체이닝 가이드 — 체인 설계 3원칙 복습