U-MAKER 시작하기

핵심 개념부터 전체 명령어, 실전 시나리오까지 단계별로 안내합니다.
전체 레퍼런스는 README를 참고하세요.

대상 초보자 ~ 중급

Version 3.4.4

Skills 13

Agents 7

01. U-MAKER란?

7개의 AI 에이전트와 3-Layer 파이프라인으로 소프트웨어 개발의 전 과정(기획 → 설계 → 구현 → 검증 → 배포)을 자동화하는 Claude Code 플러그인입니다.

	기존 방식	U-MAKER 방식
문서	코드 먼저, 문서는 나중에	문서 먼저, 코드는 문서 기반 생성 Docs-First
기존 프로젝트	문서 없이 코드만 존재	`/u-reverse`로 코드에서 SSoT 역공학
데이터 분석	200페이지 RFP를 한 번에 → loss	3-Layer chunk 분석 → 손실 없음
요구사항 추적	스프레드시트 수동 관리	4-Tier ID(USR→FR→US→FT) 자동 추적
설계 변경	SRS 수정 시 수동 갱신	Auto-Cascade 자동 전파
품질	개발 후 수동 QA	Phase Gate 자동 검증
AI 판단	블랙박스	Assumptions Log로 기록 + 리뷰

02. 핵심 개념 5가지

1 SSoT (Single Source of Truth)

모든 결정이 .u-maker/ 아래 문서에 기록됩니다. .md(사람용) + .json(기계용) 2종이 항상 함께 생성됩니다.

2 3-Layer 파이프라인

data/dropzone/(Raw) → data/digest/(Structured JSON) → docs/(Deliverables)
data/dropzone/에 파일을 넣으면 Plan 실행 시 자동 분석합니다.

3 PDCA 5-Phase

Plan → Design → Dev → Check → Ship → 다음 Iteration. 각 전환 시 Gate 검증.

4 4-Tier ID 체계

USR(사용자) → FR(기능 요구사항) → US(유저 스토리) → FT(Feature = 구현 단위). 전 구간 추적.

5 Assumptions Log

AI가 정보 부족 시 추정한 내용을 기록. /u-assume approve/reject로 리뷰.

PDCA 5-Phase (Plan, Design, Dev, Check, Ship): 각 Gate(기본 5, 최대 11 criteria)를 통과해야 다음 Phase로 진행.

03. AI 팀 구성 (7 Agents)

7-Agent Architecture: PM Agent가 전체를 조율하며, 6개 전문 에이전트(plan, design, dev, qa, gatekeeper, report)에 작업 분배

04. 설치

설치 (모든 OS 공통)

claude plugin add upleat-ax/u-maker-plugin

        Update: claude plugin add upleat-ax/u-maker-plugin (동일 명령으로 최신 버전 재설치)

        설치/업데이트 후 반드시 Claude Code를 재시작해주세요.

05. Forward Engineering (새 프로젝트)

Step 1 — 초기화

/u-init my-saas — .u-maker/ 구조 생성

Step 2 — 자료 수집

.u-maker/data/dropzone/에 RFP, 회의록, AS-IS 자료 드롭

Step 3 — 기획 (Plan Phase)

/u-plan --app myapp — SRS + IA 생성

Step 4 — 설계 (Design Phase)

/u-design --app myapp — ERD + API + Screens + Design System

Step 5 — 와이어프레임

/u-wireframe --app myapp --all — screens.json 기반 HTML 와이어프레임 (6-Section: Header, Stage, Component Spec, 2-col Diagrams, Overlay UI, Legend) + ERD, Sequence, Screen Flow

Step 6 — 구현 (Dev Phase)

/u-dev --app myapp — FE + BE 코드 생성

Step 7 — 검증 (Check Phase)

/u-check --app myapp — TC 설계 + 테스트 실행

Step 8 — HTML 산출물 생성

/u-output --app myapp — SSoT 문서를 독립 실행형 HTML로 변환. --diagram svg|mermaid|all로 다이어그램 모드 선택 (svg 모드는 free-form SVG로 생성, Mermaid 스타일 아님)

Step 9 — 배포 (Ship Phase)

/u-ship --app myapp — 최종 검증 + iteration log + 회고

        자동 실행: /u-loop --app myapp를 사용하면 Plan→Design→Dev→Check→Ship 전체를 gatekeeper 검증과 함께 자동으로 실행합니다.
      

        선행조건 자동 캐스케이드: 선행 Phase 문서가 없으면 자동으로 호출됩니다.

        /u-dev 실행 시 Design 문서 없으면 → /u-design 자동 호출 → Plan 문서 없으면 → /u-plan 자동 호출.

        즉, /u-dev 하나로 Plan → Design → Dev 전체가 자동 실행될 수 있습니다.

        스코어카드 필수 출력: 모든 Phase 검증 시 Gatekeeper가 N개 검증 (기본 5, 최대 11) 스코어카드를 화면에 출력합니다. PASS/FAIL 상태, 점수, 발견사항을 한눈에 확인할 수 있으며, FAIL 시 개선 항목이 심각도 순으로 표시됩니다.
      

06. Reverse Engineering (기존 프로젝트)

이미 코드가 있지만 SSoT 문서가 없는 프로젝트를 위한 워크플로우.

# 1. 프로젝트 초기화
/u-init my-existing-app

# 2. 소스 코드 → SSoT 역공학
/u-reverse --app my-app              # Code → Design (ERD, API, Screens, DS) → Plan (SRS, IA) 전체 역생성
/u-reverse --app my-app --db prisma/  # DB 스키마 경로 수동 지정
/u-reverse --app my-app --loop [N]  # Gatekeeper 검증 포함 (N 기본값 5)

# 3. 역공학 결과 검증 + 보완
/u-sync [app]                       # 문서 간 정합성 검증
/u-doc [app] srs --edit             # SRS에 비즈니스 의도 보완

07. Interaction Mode

Auto default

/u-plan [app] — 플래그 없으면 auto. 빠르게 진행, 판단은 Assumptions Log에 기록.

Interactive -i

/u-plan [app] -i — 분기점에서 질문. 중요 설계 결정이 있을 때.

Step --step

/u-plan [app] --step — 매 단계 확인. 학습 목적이나 품질 확인 시.

08. 역할별 활용

기획자 (PM)

/u-ingest [app] — 자료 분석
/u-plan [app] -i — Plan interactive
/u-add [app] fr "..." — FR 추가
/u-status [app] — 상태 확인
/u-discuss brainstorm "UX" — 토론

디자이너 (UX)

/u-design [app] — Design 전체
/u-design [app] --only screens — Screen만
/u-discuss workshop "메인 IA" — 워크숍
/u-sync [app] — 일관성 검증

개발자 (Dev)

/u-dev [app] — FE + BE 코드 생성
/u-dev [app] --only fe — Frontend만
/u-reverse [app] — 역공학
/u-git-pr — PR 자동 생성

QA (테스터)

/u-qa [app] — TC + 테스트 + 리포트
/u-coverage [app] — 커버리지 확인
/u-trace [app] FR-015 — 추적 체인

09. 명령어 치트시트 (13 Skills)

Command	설명	Options
/u-plan	Plan Phase — SRS + IA 생성	`--app {name}`, `[--loop [N]]`
/u-design	Design Phase — ERD + API + Screens + Design System	`--app {name}`, `[--loop [N]]`
/u-dev	Dev Phase — FE + BE 코드 생성	`--app {name}`, `[--loop [N]]`
/u-check alias: /u-qa	Check Phase — TC 설계 + 테스트 실행	`--app {name}`, `[--loop [N]]`
/u-output NEW	SSoT 문서 → 독립 실행형 HTML 생성 (도메인 분할 지원). svg 모드 = free-form SVG (Mermaid 스타일 아님)	`--app {name}`, `--doc {docType}`, `--diagram {svg\|mermaid\|all}`, `--force`
/u-reverse	기존 코드 → SSoT 역생성 (Code → Design → Plan)	`--app {name}`, `--src {path}`, `--db {path}`, `--api {path}`, `--pages {path}`, `--loop [N]` (기본 5)
/u-engine	내부 엔진 스킬 (분석, 문서, 검증 등)	—
/u-loop	무인 PDCA 자동 실행 루프. Plan→Design→Dev→Check→Ship을 gatekeeper 검증과 함께 실행	`--app {name}`, `--from {phase}`, `--to {phase}`, `--dry-run`, `--max-retries {n}`
/u-wireframe	screens.json 기반 HTML 와이어프레임 생성 (6-Section 템플릿: Header, Stage, Component Spec, 2-col Diagrams, Overlay UI, Legend) + ERD, Sequence Diagram, Screen Flow	`--app {name}`, `--screen {SCR-ID}`, `--all`
/u-discuss	구조화된 토론 세션 (brainstorm/review/decision/workshop/retro)	타입 + 주제
/u-git-pr	PR/MR 자동 생성	—
/u-init	프로젝트 초기화 — .u-maker/ 구조 생성	`{project-name}`
/u-meeting-report	회의록 기반 구조화 리포트 생성	—

10. /u-discuss 토론 세션

타입	용도	예시
brainstorm	아이디어 발산	`/u-discuss brainstorm "결제 UX"`
review	산출물 검토	`/u-discuss review`
decision	기술/비즈니스 의사결정	`/u-discuss decision "DB 선택"`
workshop	다단계 작업	`/u-discuss workshop "메인 화면"`
retro	Iteration 회고	`/u-discuss retro`

        Micro-commands:
        @planner / @builder / @gatekeeper / @all — 에이전트 질문
/idea [text] — 아이디어 태깅
/decide [text] — 결정사항 기록
/concern [text] — 우려/리스크 기록
/action [who] [text] — 액션 아이템
/wrap — 세션 종료 + SSoT 적재

      

11. 실전 시나리오

Scenario 1: 새 프로젝트 처음부터 끝까지

/u-plan --app myapp → /u-design --app myapp → /u-wireframe --app myapp --all → /u-dev --app myapp → /u-check --app myapp
또는 /u-loop --app myapp으로 전체 자동 실행

Scenario 2: 기존 프로젝트에 SSoT 도입

/u-init → /u-reverse → /u-sync → /u-doc srs --edit → /u-qa

Scenario 3: 요구사항 변경

/u-add fr "비밀번호 재설정" → /u-update srs --cascade → /u-status (impact flags 확인)

Scenario 4: PR 생성

/u-git-pr — uncommitted changes 자동 커밋 + push + 구조화 PR 생성

Scenario 5: Phase Gate 미통과

/u-gate → FAILED → /u-plan --only ia → /u-plan --only roadmap → /u-gate (재검증)

Scenario 6: 무인 자동 실행

/u-loop --app myapp — Plan→Design→Dev→Check→Ship 전체 파이프라인 자동 실행. --from design --to check으로 범위 지정 가능

Scenario 7: 멀티 앱 프로젝트

/u-plan common → /u-plan [app] → /u-plan admin → /u-design [app],admin -i → /u-sync all

12. 폴더 구조

# .u-maker/ 프로젝트 구조
.u-maker/
├── u-maker.config.json         # 전역 설정
├── data/
│   ├── dropzone/                    # 파일 드롭존
│   ├── digest/                      # 분석 결과
│   │   └── _index.json
│   └── links.json                   # 의존성 그래프
├── docs/{app}/
│   ├── plan/                        # SRS + IA
│   ├── design/                      # ERD + API + Screens + Design System
│   └── check/                       # Test Cases + Test Results
├── output/{app}/
│   ├── index.html
│   ├── plan/
│   ├── design/
│   │   └── wireframes/              # SCR-*.html 와이어프레임
│   └── check/
├── reports/
└── .state/
    └── loop-state.json              # 루프 실행 상태

13. FAQ

Q
명령어가 인식되지 않아요
Claude Code를 재시작해보세요.
Q
어떤 명령어를 써야 할지 모르겠어요
자연어로 말하세요. 또는 /u-ask로 물어보세요.
Q
기존 프로젝트에 적용하려면?
/u-init → /u-reverse로 코드에서 SSoT를 역공학하세요.
Q
문서 언어를 바꾸고 싶어요
u-maker.config.json의 language.documents를 "en", "ja", "zh" 등으로 변경.
Q
기본 테마를 dark로 시작하고 싶어요
u-maker.config.json에 "theme": "dark". 허용값: light | dark.
Q
auto 모드에서 자꾸 interactive로 전환돼요
maxAssumptions 초과. /u-assume로 리뷰하세요.
Q
PR을 빠르게 만들고 싶어요
/u-git-pr — uncommitted changes 자동 커밋 + push + PR body 자동 작성.

다음 단계: 전체 아키텍처와 엔진 스킬 상세는 README.ko.html을 참고하세요.
/u-ask로 궁금한 점을 자유롭게 질문하고, /u-status로 프로젝트 상태를 확인하세요.