mandu-guard-guide
Guard 아키텍처 가이드. 위반 수정/프리셋 선택/레이어 규칙. guard violation 시 자동 호출
SKILL.mddocs/archive/skills/package-v0/mandu-guard-guide/SKILL.md
GitHubMandu 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, 자동수정 안전 절차)