mandu-guard-guide

Mandu Guard Guide

Mandu Guard 아키텍처 강제 시스템의 상세 가이드. 6개 프리셋, 위반 유형별 수정 방법, 레이어 규칙을 다룹니다.

가드레일 3축 (중요)

Mandu 의 품질 가드레일은 단일 도구가 아니라 3축 병렬:

축	무엇을 잡나	도구	이 skill
Guard	아키텍처 / 레이어 / import 규칙	mandu guard	여기 (지금)
Typecheck	타입 에러	tsgo / mandu check	mandu-mcp-verify
Lint	코드 품질 (any / unused / promise-leak 등)	oxlint	mandu-lint

세 축은 서로 겹치지 않고 상호보완. Guard 는 "B 레이어가 A 를 import 해도 되나?" 를 보고, lint 는 "이 함수 파라미터가 any 인가?" 를 보고, typecheck 는 "이 unknown 을 진짜로 string 으로 좁혔나?" 를 본다. 어느 하나를 꺼두면 다른 축이 잡지 못하는 구멍이 열림. mandu check 가 셋 모두를 한 번에 실행한다.

6 Presets

mandu (default)

FSD + Clean Architecture 하이브리드. 프론트엔드와 백엔드 모두 커버.

// mandu.config.ts
export default { guard: { preset: "mandu" } };

fsd (Feature-Sliced Design)

프론트엔드 전용. 7계층 레이어 구조.

app > pages > widgets > features > entities > shared

clean (Clean Architecture)

백엔드 전용. 의존성 역전 원칙.

api > application > domain > infra > core > shared

hexagonal (Ports & Adapters)

포트와 어댑터 패턴. domain이 중심, adapters가 외부 의존성 처리.

adapters > ports > application > domain

atomic (Atomic Design)

UI 컴포넌트 전용. atoms -> molecules -> organisms -> templates -> pages.

cqrs (Command Query Responsibility Segregation)

명령과 조회를 분리. command, query, event, dto 전용 구조.

Violation Types and Fixes

LAYER_VIOLATION (error)

상위 레이어가 하위 레이어를 import하는 것만 허용.

// BAD: shared가 features를 import (하위 -> 상위)
// src/shared/utils/helper.ts
import { useAuth } from "@/features/auth"; // VIOLATION

// FIX: 의존 방향 반전, 또는 shared에 인터페이스 정의
// src/shared/types/auth.ts
export interface AuthContext { userId: string; }

FORBIDDEN_IMPORT (error)

클라이언트 코드에서 서버 전용 모듈 import 금지.

// BAD: island에서 fs import
// app/editor.island.tsx
import fs from "fs"; // VIOLATION

// FIX: 서버 로직은 slot으로 분리
// spec/slots/editor.slot.ts
import fs from "fs"; // OK (server-only)

WRONG_SLOT_LOCATION (warning)

Slot 파일이 잘못된 위치에 있음.