# 만두(Mandu) 프레임워크 상세 평가 및 제언

## 1. 총평: "AI 시대의 새로운 개발 OS"

Mandu는 단순한 웹 프레임워크(Web Framework)를 넘어, **"AI 에이전트와의 협업을 전제로 한 개발 운영체제(OS)"**라는 명확한 정체성을 가지고 있습니다.

기존 프레임워크(Next.js, Remix 등)가 "사람이 작성하기 편한" 것에 초점을 맞췄다면, Mandu는 **"사람이 설계(`app/` 구조)하고 AI가 구현(Slot Filling)하되, 아키텍처가 무너지지 않도록(Guard) 하는 것"**에 집중하고 있습니다. 이는 현재 LLM 기반 개발 트렌드에서 가장 시급한 문제인 "문맥 오염"과 "아키텍처 부패"를 정면으로 해결하려는 시도이며, 매우 시의적절하고 혁신적인 접근입니다.

특히 `app/ (FS Routes) -> Manifest (캐시) -> Slot -> Guard`로 이어지는 단방향 파이프라인은 AI가 코드를 작성할 때 발생할 수 있는 환각이나 실수로부터 전체 시스템을 보호하는 강력한 방화벽 역할을 합니다.

---

## 2. 핵심 강점 (Pros)

### 🛡️ 아키텍처 보존 (Architecture Preservation)
- **강제성**: 단순 린트(Lint) 수준이 아니라, 파일 시스템 레벨에서 `Spec`과 `Generated` 코드의 수정을 막고 `Slot`만 열어두는 방식은 AI의 "창의적 파괴"를 효과적으로 차단합니다.
- **복구 가능성**: `Generated` 코드는 언제든 재생성 가능(Disposable)하므로, 코드가 꼬였을 때 "처음부터 다시"가 아닌 "생성 다시"로 해결할 수 있습니다.

### 🤖 에이전트 친화적 설계 (Agent-Native)
- **명확한 경계**: AI에게 "이 파일을 고쳐줘"가 아니라 "**이 슬롯(Slot)만 채워줘**"라고 명령할 수 있어, AI의 컨텍스트 윈도우 효율이 높아지고 작업 정확도가 상승합니다.
- **MCP 내장**: 프레임워크 자체가 MCP 서버를 내장하여 에이전트가 CLI를 통하지 않고 직접 함수 호출(Tool Call)로 라우트를 추가하거나 스펙을 변경할 수 있다는 점은 매우 선진적입니다.

### ⚡ 현대적인 기술 스택 및 성능
- **Bun & Island Hydration**: Bun의 빠른 런타임과 필요한 부분만 하이드레이션하는 Island 아키텍처는 성능과 DX(개발자 경험)를 모두 잡으려는 시도입니다.
- **Fluent API**: `Mandu.filling().get().post()` 형태의 체이닝 API는 가독성이 좋고 타입 추론(TypeScript)에 유리합니다.

---

## 3. 우려사항 및 약점 (Cons)

### ⚠️ 학습 곡선과 용어의 장벽
- `Spec`, `Slot`, `Filling`, `Guard`, `Island` 등 Mandu 고유의 개념을 익혀야 합니다. "그냥 라우트 파일 만들면 끝"인 프레임워크(Next.js App Router 등)에 비해 초기 진입 장벽이 있을 수 있습니다.

### 🧩 유연성 vs 강제성
- 프레임워크가 정한 틀(Spec)을 벗어난 예외적인 구현(예: 커스텀 서버 로직, 복잡한 미들웨어 파이프라인 등)이 필요할 때, `Slot` 시스템이 이를 수용할 수 있을지 미지수입니다. "탈출구(Escape Hatch)"가 부족하면 숙련된 개발자는 답답함을 느낄 수 있습니다.

### 🔌 생태계 부족
- 인증(Auth), 데이터베이스 ORM, 배포 등 주변 생태계가 Next.js 등에 비해 부족할 수밖에 없습니다. 주요 라이브러리(Prisma, Drizzle, Passport 등)와의 통합 레시피나 전용 어댑터가 필수적입니다.

---

## 4. 구체적인 개선 제언 (Roadmap Suggestions)

### 🚀 1. Contract-First 개발의 전면 도입 (우선순위: 높음)
현재 `Mandu.contract()`가 존재하지만, 이를 더 강화해야 합니다.
- **제안**: `spec/contracts/` 단계에서 입출력 스키마(Zod)를 먼저 정의하면, AI가 `Slot`을 작성할 때 **타입이 완벽하게 정의된 상태**에서 로직만 채우도록 강제할 수 있습니다.
- **효과**: AI의 가장 큰 강점인 "타입 맞추기"를 극대화하여 런타임 에러를 획기적으로 줄일 수 있습니다.

### 🧪 2. "Slot Test" 자동 생성 (우선순위: 높음)
테스트 작성을 AI에게 맡기는 것을 넘어, 프레임워크 차원에서 강제해야 합니다.
- **제안**: `users.slot.ts` 생성 시 `users.test.slot.ts` (또는 `users.spec.ts`)를 쌍으로 생성하고, `Mandu.test()` 유틸리티를 제공하여 슬롯 로직만 독립적으로 테스트할 수 있게 지원해야 합니다.
- **효과**: "구현 → 테스트 → 가드 통과"의 루프를 에이전트가 스스로 돌 수 있게 됩니다.

### 🔌 3. "만두소(Filling)" 레시피/마켓플레이스
자주 쓰는 로직을 패턴화해야 합니다.
- **제안**: 인증(JWT/Session), 기본 CRUD, 파일 업로드 등 자주 쓰이는 로직을 "공식 Filling 레시피"로 제공하여 에이전트가 "인증 레시피 적용해줘"라고 하면 바로 코드가 생성되도록 합니다.

### 🔍 4. 디버깅 매핑 강화 (Source Map for Slots)
런타임 에러 발생 시 `Generated` 코드가 아닌 `Slot`의 위치를 정확히 찍어주는 것이 중요합니다.
- **제안**: 현재 구현된 에러 분류기(`ErrorClassifier`)를 고도화하여, 스택 트레이스에서 `generated` 경로를 숨기고 `slot` 파일 경로로 변환해 보여주는 기능을 IDE 확장에서 지원하면 좋습니다.

---

## 5. 결론

Mandu는 **"AI와 함께 코딩하는 미래"를 가장 정확하게 예측하고 준비한 프레임워크**입니다. 단순히 코드를 빨리 짜는 것이 아니라, **"지속 가능한 소프트웨어"**를 만들기 위한 제약 조건을 시스템화했다는 점에서 높은 점수를 줄 수 있습니다.

현재 초기 버전(v0.x)임에도 불구하고 핵심 코어(`filling`, `guard`, `mcp`)의 완성도가 높습니다. 생태계와 문서화, 그리고 "Contract-First" 기능만 보강된다면, AI 에이전트 기반 개발 조직에서 **표준 OS**로 자리 잡을 잠재력이 충분합니다.
