U-MAKER Plugin v4.0.0-alpha.22 (PBGD)

2. TL;DR

세 가지 방식으로 U-MAKER를 활용할 수 있습니다.

Forward Engineering (정방향)

원시 자료 투입 → Plan → Build → Gatekeeping → Deploy까지 자동 실행

Reverse Engineering (역방향)

기존 코드베이스에서 SSoT 설계 문서를 역생성

Figma 소스 분석

Figma URL을 전달하면 페이지/컴포넌트/variants/에셋/코멘트/시맨틱을 자동 추출

Natural Language (자연어)

슬래시 커맨드 없이 자연어로 요청하면 PM 에이전트가 자동 라우팅

3. 아키텍처 개요

U-MAKER는 10개 AI 에이전트가 PBGD 4-phase 파이프라인을 수행하며, 28개 스킬(별칭 3개 포함)을 통해 각 단계를 제어합니다. PM 에이전트가 모든 요청을 라우팅하고 Gatekeeper가 품질을 검증합니다.

4. PBGD 4-Phase 프로세스

U-MAKER는 v3.x PDCA 5-phase를 축약한 4-phase PBGD 파이프라인을 사용합니다. Plan → Build(Design ↔ Dev 오케스트레이션) → Gatekeeping(문서 점수 + 런타임 QA) → Deploy. 마이그레이션은 CHANGELOG.md 참조.

5. 데이터 파이프라인

U-MAKER의 데이터 흐름은 4단계 파이프라인으로 구성됩니다. 원시 자료가 정제, 분석을 거쳐 SSoT 문서와 HTML 산출물로 변환됩니다.

6. 10개 Agents

각 에이전트는 PBGD 4-phase 중 특정 역할을 전담합니다. PM이 모든 커맨드를 라우팅하고, 나머지 에이전트가 Phase별 작업을 수행합니다.

7. 28개 Commands (Skills)

모든 커맨드는 /u-{name} 형태로 호출됩니다. Plan(7) + Build(3) + Gatekeeping(1+2 aliases) + Deploy(1) + Tools(5) + Output/Report(5) + Control(3) + Setup alias(1) = 28개.

공통 옵션

Plan Phase Skills (6 + 1 umbrella)

Build Phase Skills (3)

Gatekeeping Phase Skills (1 + 2 aliases)

Deploy Phase Skills (1)

External-tool Skills (3) — u-tools-* 네임스페이스

외부 프로그램/서비스 래퍼. phase skill은 MCP/CLI를 직접 호출하지 않고 이 스킬들을 경유해야 합니다.

Rule Packs — 외부 표준 룰 연동

코드·디자인 산출물 품질을 강제하는 외부 권위 룰 팩. 관련 스킬에서 자동 로드됩니다.

Output / Report Skills (5)

Control Flow / Utility Skills (3)

8. Gate Criteria (11개)

모든 Phase 산출물은 Gatekeeper 기준으로 검증됩니다. 각 항목은 0~100점으로 채점되고 평균 95점 이상(configurable)이어야 다음 Phase로 진행합니다.

스코어카드 출력 (필수)

모든 Phase 검증 시 전체 스코어카드가 반드시 화면에 표시됩니다. 생략이나 축약 없이 매번 전체 결과를 출력합니다.

+-----+----------------------+-------+--------+---------------+
|  GATEKEEPER REPORT -- Plan Phase (myapp)                  |
+-----+----------------------+-------+--------+---------------+
|  #  | Criteria             | Score | Status | Findings      |
+-----+----------------------+-------+--------+---------------+
|  01 | Completeness         |   98  |   PASS | --            |
|  02 | Accuracy             |   95  |   PASS | --            |
|  03 | Consistency          |   97  |   PASS | --            |
|  04 | Traceability         |   88  |   FAIL | FR-030 orphan |
|  05 | TOC Quality          |   96  |   PASS | --            |
|  06 | Composition          |   95  |   PASS | --            |
|  07 | Visual               |   99  |   PASS | --            |
|  08 | Diagram              |   93  |   FAIL | SVG mismatch  |
|  09 | Mermaid              |   90  |   FAIL | syntax L:45   |
|  10 | JSON Sync            |  100  |   PASS | --            |
|  11 | Cross-Ref            |   96  |   PASS | --            |
+-----+----------------------+-------+--------+---------------+
| AVG |                      | 95.2  | PASS   |               |
+-----+----------------------+-------+--------+---------------+
  Attempt: 1/3 · Threshold: 95 · Result: PASS -> advance to Design

9. .u-maker/ 폴더 구조

프로젝트 루트에 생성되는 .u-maker/ 디렉토리 구조입니다. /u-prepare (별칭 /u-init) 또는 최초 /u-plan 실행 시 자동 생성됩니다.

.u-maker/
├── u-maker.config.json          # 프로젝트 설정 (v4.0)
├── data/
│   ├── dropzone/                # 원시 입력 파일 (RFP, 회의록, Figma URL 등)
│   ├── digest/                  # 정제된 분석 JSON
│   │   ├── _classified/         # 12개 카테고리 분류 결과
│   │   ├── figma/               # u-agent-figma가 생성 (source.pipeline 태깅)
│   │   └── _index.json          # 해시 인덱스 (변경 감지)
│   ├── deploy/                  # Deploy manifest (sourceHashes, artifacts)
│   └── _links.json              # 글로벌 의존성 그래프
├── docs/
│   └── {app}/
│       ├── _index.json          # 문서 상태 인덱스
│       ├── plan/                # SRS + IA (.md + .json) + wireframes/
│       ├── design/              # ERD + API + Screens + Design System
│       ├── dev/                 # code.md + spec-sync-report.md
│       └── gatekeeping/         # testcases.md + test-results.md (v3.x의 check/ 에서 리네임)
├── output/
│   └── {app}/
│       ├── index.html           # 산출물 내비게이션 인덱스
│       ├── plan/                # Plan HTML (srs.html, ia.html)
│       ├── design/              # Design HTML (erd, api, screens, ds)
│       │   └── wireframes/      # 화면별 와이어프레임 HTML
│       ├── gatekeeping/         # Gatekeeping HTML (testcases, results)
│       └── deploy/              # Deploy runbook, release-notes, CI/CD 아티팩트
├── reports/
│   └── {YYYY-MM-DD}/            # Daily/Weekly Report HTML
│       ├── daily-report.html
│       └── weekly-report.html
├── discussions/                 # 토론 세션 기록
└── .state/
    ├── loop-state.json          # 런타임 상태 (현재 Phase, Loop 카운트)
    └── deploy-stale.json        # SSoT drift 감지 (on-deploy-state.js hook)

10. 시나리오 가이드

일반적인 사용 시나리오별 커맨드 흐름을 안내합니다.

A. Forward Engineering (신규 프로젝트)

원시 기획 자료로부터 전체 PBGD 산출물을 처음부터 생성하는 시나리오입니다.

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

이미 구현된 코드베이스에서 설계 문서를 역생성하는 시나리오입니다.

B'. Figma 소스 분석

Figma URL이 포함되어 있으면 u-agent-figma가 자동 호출됩니다.

C. Daily Operations (일상 운영)

일상적인 개발 업무에서 활용하는 보조 커맨드들입니다.

D. 리포트 생성

프로젝트 현황 및 회의 기록을 리포트로 생성하는 시나리오입니다.

11. 설치 및 사전 요구사항

사전 요구사항

설치 방법

초기화

12. 트러블슈팅

자주 발생하는 문제와 해결 방법입니다.

13. 라이선스