메뉴
에러 진단+수정. 빌드실패/하얀화면/Island안됨/API에러/CSS깨짐 시 자동 호출
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
Canonical Mandu agent workflow. Use first in Mandu projects before direct source edits so Codex, Claude Code, Gemini CLI, and other agents follow the same context -> plan -> apply -> verify -> repair loop.
React composition patterns for Mandu applications. Use when designing Island components, managing shared state, or building reusable component APIs. Triggers on compound components, context providers, boolean props, or component architecture tasks.
Production deployment patterns for Mandu applications
File-system based routing for Mandu. Use when creating pages, API routes, layouts, or dynamic routes. Triggers on tasks involving app/ folder, page.tsx, route.ts, layout.tsx, [id], [...slug], or URL patterns.
Architecture guard system for Mandu. Use when checking layer dependencies, enforcing architecture rules, or validating file locations. Triggers on tasks involving architecture, layers, dependencies, or guard commands.
Island Hydration pattern for Mandu. Use when creating interactive components, client-side state, or partial hydration. Triggers on tasks involving "use client", client.tsx, useState, useEffect, Island, or hydration.
| name | mandu-debug |
| description | 에러 진단+수정. 빌드실패/하얀화면/Island안됨/API에러/CSS깨짐 시 자동 호출 |
Mandu 프로젝트의 에러를 진단하고 수정하는 8카테고리 트리아지 시스템. 증상 → 수집 → 진단 → 수정 → 검증 순서로 진행합니다.
| 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 |
문제 발생 시 동시에 수집할 정보:
# 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" })
bunx tsc --noEmit - TypeScript 에러 위치 확인@mandujs/core vs @mandujs/core/client)bun install - 의존성 누락 확인app/layout.tsx에 <html>/<head>/<body> 태그가 있는지 확인 -> 있으면 제거page.tsx에서 default export 확인"use client" 디렉티브 확인 (파일 최상단)@mandujs/core/client (NOT @mandujs/core).island.tsx 또는 .client.tsx 파일 확장자 확인island() API로 감싸져 있는지 확인route.ts (NOT route.tsx) 확인Mandu.filling() 체인으로 default export 확인ctx.body() await 누락 확인.guard() 반환값 확인 (void = 계속, Response = 차단)app/globals.css 존재 확인@import "tailwindcss"cssPath 옵션이 서버에 전달되는지 확인bunx mandu guard arch 실행mandu.config.ts의 preset 확인Ctrl+C → bun run devlsof -i :3333 또는 다른 포트 사용.mandu/ 캐시 삭제: rm -rf .mandu/generatedDate.now(), Math.random() 등 비결정적 값 제거useHydrated() 훅으로 클라이언트 전용 코드 분기수정 후 반드시 검증:
bunx mandu guard arch --ci # 아키텍처 검증
bunx tsc --noEmit # 타입 검증
bun run dev # 런타임 검증
| Tool | Purpose |
|---|---|
mandu_brain_diagnose | 증상 기반 자동 진단 |
mandu_guard | 아키텍처 규칙 검사 |
mandu_guard_heal | 위반 자동 수정 |
mandu_runtime_check | 런타임 상태 점검 |
mandu-mcp-verify — 진단 시작점 (fast path: ate.auto_pipeline + guard_check + doctor 병렬), drill-down 규칙mandu-mcp-orient — 세션 진입 직후 상태 파악으로 문제 배경 확보