빠른 시작#

TL;DR — Mandu 설치 (binary 또는 npm) → mandu create my-app → cd my-app && bun run dev → http://localhost:3333. 5분, 명령 3줄.

왜 Mandu#

다른 풀스택 프레임워크는 사람이 한 줄씩 짜는 것 을 전제로 만들어졌어요. Mandu 는 처음부터 AI 에이전트가 코드를 쏟아낸다 는 가정으로 설계됐습니다 — Guard 가 런타임 경계 강제, contract 한 파일이 타입·검증·OpenAPI 를 파생, MCP 100+ 도구가 에이전트와 직접 대화. 그래서 5분이면 충분합니다.

설치#

설치 경로 두 가지. 상황에 맞는 것을 고르세요.

경로 A · Standalone 바이너리 (사전 요구사항 없음, ~132 MB)#

Bun 이 바이너리에 포함되어 따로 설치할 게 없습니다.

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/konamgil/mandu/main/install.sh | sh

# Windows (PowerShell)
iwr https://raw.githubusercontent.com/konamgil/mandu/main/install.ps1 -useb | iex

mandu --version 으로 확인. "command not found" 면 셸을 재시작해 PATH (~/.mandu/bin, Windows 는 %LOCALAPPDATA%\Mandu\bin) 가 잡히도록 합니다.

경로 B · npm / Bun 패키지 (~5 MB, Bun 필요)#

다운로드는 작지만 Bun 이 미리 설치돼 있어야 합니다.

bun --version
# 1.3.12 이상이어야 합니다
bun install -g @mandujs/cli

Bun 이 없으면 bun.sh/docs/installation 에서 설치하세요. Node.js 는 지원하지 않습니다 — Mandu 의 라우터·번들러·테스트 러너 모두 Bun API 에 묶여있습니다.

프로젝트 스캐폴드#

mandu create my-app
cd my-app

스캐폴더가 두 가지 묻습니다:

• Template — minimal / starter / agent-ready. 처음이면 starter.
• MCP agents — Claude Code · Claude Desktop · Gemini CLI 사전 구성 여부. 나중에 mandu mcp add 로 추가.

dev 서버 실행#

bun run dev
# standalone 바이너리만 있으면: `mandu dev`

http://localhost:3333 에서 만두 캐릭터가 인사하면 성공.

🤖 에이전트 프롬프트#

Bootstrap a new Mandu project. Walk me through:

1. Install Mandu — prefer the standalone binary:
   - Unix:    curl -fsSL https://raw.githubusercontent.com/konamgil/mandu/main/install.sh | sh
   - Windows: iwr https://raw.githubusercontent.com/konamgil/mandu/main/install.ps1 -useb | iex
   (Or `bun install -g @mandujs/cli` if Bun is already installed.)

2. `mandu create my-app` (template: `starter`).
3. `cd my-app && bun run dev`.
4. Open http://localhost:3333 and confirm the welcome page renders.

Diagnose using these invariants:
- routes live at app/**/page.tsx (.tsx only)
- .island.tsx with `use client` is required for hydration
- dev port is 3333
- the npm path requires Bun >= 1.3.12 (the binary embeds Bun)

Once dev is running, show me the project tree
(app/, src/client, src/server, src/shared, spec/, content/, mandu.config.ts).

Claude Code · Cursor · OpenAI Codex · GitHub Copilot · Gemini CLI 등 어떤 AI 에이전트에 붙여 넣어도 그대로 동작합니다. ai-hint 와 invariants 가 frontmatter 에 있어 에이전트가 자동으로 끌어다 씁니다.

무엇이 만들어졌나요#

스캐폴드 직후 트리:

my-app/
├── app/
│   ├── page.tsx          # "/" 라우트
│   ├── layout.tsx        # body 래퍼 (html/head 는 Mandu 자동 생성)
│   └── api/              # 파일 시스템 API 라우트
├── src/
│   ├── client/           # UI 코드 (FSD: shared/entities/features/widgets)
│   ├── server/           # 서버 코드 (domain/application/infra)
│   └── shared/           # 양쪽이 공유하는 contract 와 타입
├── spec/                 # 스펙 (contract, decision, sketch)
├── content/              # MDX 컨텐츠 레이어
└── mandu.config.ts       # 프레임워크 설정

놓치면 안 되는 5가지#

• Bun ≥ 1.3.12 — npm 경로 사용 시 (바이너리는 Bun 포함, 사전 요구 없음).
• 라우트 = app/**/page.tsx 만 인식. .jsx, index.tsx, .mdx 는 무시.
• .island.tsx 만 hydrate. 일반 .tsx 는 서버 전용.
• 포트 3333 고정 — mandu.config.ts 의 server.port 로 변경.
• Guard 가 런타임에 경계 강제 — features 가 entities 의 internal 을 import 하면 dev 콘솔에서 즉시 거부.

다음 읽을거리#

• project-structure — 폴더가 왜 이렇게 나뉘었나
• first-route — 두 번째 라우트 추가하기
• recipes/create-api.ko — API 엔드포인트 만들기 (다음 단계)
• architect/guard.ko — Guard 가 무엇을 막는가