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 파일이 잘못된 위치에 있음.

BAD:  src/server/slots/user.slot.ts
FIX:  spec/slots/user.slot.ts

GENERATED_DIRECT_EDIT (error)

자동 생성된 파일을 직접 수정하면 안 됨.

BAD:  .mandu/generated/server/routes.ts 직접 편집
FIX:  소스 파일을 수정하고 regenerate

CONTRACT_MISSING (warning)

API route에 대응하는 contract가 없음.

Missing: src/shared/contracts/user.contract.ts
For:     app/api/users/route.ts
FIX:     contract 파일 생성

SLOT_NAMING (warning)

Slot 파일명이 규칙에 맞지 않음.

BAD:  spec/slots/userData.ts
FIX:  spec/slots/user-data.slot.ts

CLI Commands

# 전체 아키텍처 검사
bunx mandu guard arch

# 특정 프리셋으로 검사
bunx mandu guard arch --preset fsd

# CI 모드 (위반 시 exit 1)
bunx mandu guard arch --ci

# Watch 모드
bunx mandu guard arch --watch

# 단일 파일 검사
bunx mandu guard check-file src/client/features/auth.ts

Configuration

// mandu.config.ts
export default {
  guard: {
    preset: "mandu",
    rules: {
      LAYER_VIOLATION: "error",     // "error" | "warning" | "off"
      FORBIDDEN_IMPORT: "error",
      WRONG_SLOT_LOCATION: "warning",
      CONTRACT_MISSING: "off",
      GENERATED_DIRECT_EDIT: "error",
      SLOT_NAMING: "warning",
    }
  }
};

MCP Tools

Tool	Purpose
mandu_guard	Run architecture check
mandu_guard_heal	Auto-fix violations
mandu_negotiate	Analyze with preset awareness

See also

• mandu-mcp-verify — guard 위반 drill-down (guard_explain → guard_heal) 순서
• mandu-mcp-safe-change — 대규모 guard 수정은 snapshot + tx 안에서
• mandu-lint — 가드레일의 lint 축 (oxlint, 세팅, type-aware, 자동수정 안전 절차)