mandu-debug
에러 진단+수정. 빌드실패/하얀화면/Island안됨/API에러/CSS깨짐 시 자동 호출
SKILL.mddocs/archive/skills/package-v0/mandu-debug/SKILL.md
GitHubMandu Debug
Mandu 프로젝트의 에러를 진단하고 수정하는 8카테고리 트리아지 시스템. 증상 → 수집 → 진단 → 수정 → 검증 순서로 진행합니다.
Triage: 8 Error Categories
| Category | Symptoms | First Check |
|---|---|---|
| Build | bun run build fails, TS errors |
bunx mandu guard arch --ci |
| White Screen | Page loads but blank | Browser console, SSR output |
| Island | Component not interactive | "use client", import path |
| API | 4xx/5xx from endpoints | Route file, Mandu.filling() chain |
| CSS | Styles missing/broken | app/globals.css, Tailwind config |
| Guard | Architecture violations | bunx mandu guard arch |
| HMR | Changes not reflecting | Dev server restart, port conflict |
| Hydration | Mismatch warnings | Server vs client render diff |
Parallel Collection Phase
문제 발생 시 동시에 수집할 정보:
# 1. Guard check (아키텍처 위반 여부)
bunx mandu guard arch --ci
# 2. TypeScript check
bunx tsc --noEmit
# 3. Dev server logs
# 이미 실행 중이면 터미널 출력 확인
# 4. Browser console
# 개발자 도구에서 에러 메시지 확인
MCP 도구로 수집:
mandu_brain_diagnose({ symptoms: "white screen on /dashboard" })
Fix Patterns by Category
Build Failure
bunx tsc --noEmit- TypeScript 에러 위치 확인- Import 경로 확인 (특히
@mandujs/corevs@mandujs/core/client) bun install- 의존성 누락 확인
White Screen
app/layout.tsx에<html>/<head>/<body>태그가 있는지 확인 -> 있으면 제거page.tsx에서 default export 확인- SSR 에러: 서버 로그에서 렌더링 에러 확인
Island Not Working
"use client"디렉티브 확인 (파일 최상단)- Import:
@mandujs/core/client(NOT@mandujs/core) .island.tsx또는.client.tsx파일 확장자 확인island()API로 감싸져 있는지 확인
API Error
route.ts(NOTroute.tsx) 확인Mandu.filling()체인으로 default export 확인ctx.body()await 누락 확인.guard()반환값 확인 (void = 계속, Response = 차단)
CSS Missing
app/globals.css존재 확인- Tailwind v4 import 확인:
@import "tailwindcss" - 프로덕션:
cssPath옵션이 서버에 전달되는지 확인
Guard Violation
bunx mandu guard arch실행- Layer 위반: import 방향 확인 (상위 → 하위만 허용)
mandu.config.ts의 preset 확인
HMR Not Working
- Dev server 재시작:
Ctrl+C→bun run dev - 포트 충돌:
lsof -i :3333또는 다른 포트 사용 .mandu/캐시 삭제:rm -rf .mandu/generated
Hydration Mismatch
- 서버/클라이언트 렌더링 차이 확인
Date.now(),Math.random()등 비결정적 값 제거useHydrated()훅으로 클라이언트 전용 코드 분기
Verification
수정 후 반드시 검증:
bunx mandu guard arch --ci # 아키텍처 검증
bunx tsc --noEmit # 타입 검증
bun run dev # 런타임 검증
MCP Tools for Debugging
| Tool | Purpose |
|---|---|
mandu_brain_diagnose |
증상 기반 자동 진단 |
mandu_guard |
아키텍처 규칙 검사 |
mandu_guard_heal |
위반 자동 수정 |
mandu_runtime_check |
런타임 상태 점검 |
See also
mandu-mcp-verify— 진단 시작점 (fast path:ate.auto_pipeline+guard_check+doctor병렬), drill-down 규칙mandu-mcp-orient— 세션 진입 직후 상태 파악으로 문제 배경 확보