Mandu Debug
SkillDev toolsError diagnosis + fixes. Automatically invoked on build failures, white screens, Islands not working, API errors, or broken CSS.
Available today. Use it from your connected AI after setup.
No other account needed.
Connect ahel once, and every AI you use reads what you have installed.
Then ask your AI: use the Mandu Debug skill
What this skill tells your AI
The instructions your AI receives, as published by konamgil/mandu in docs/archive/skills/package-v0/mandu-debug/SKILL.md and read by ahel’s review.
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— 세션 진입 직후 상태 파악으로 문제 배경 확보
Signals
- GitHub stars
- 46
- Forks
- 3
- Last commit
- Aug 2026
Advanced
- Catalog kind
- skill
- Gateway key
mandu-debug- Source
- github.com/konamgil/mandu