MFR 동기화

원격과 로컬을 연결하기

MFR 문서를 원격 저장소와 양방향 동기화하고, Organization 계층 간 정책을 전파하는 시나리오. 사용자의 환경에 따라 Standalone(로컬 전용)부터 Full Service(클라우드)까지 단계적으로 활용할 수 있습니다.

사용자 티어

HanSpec은 동기화 수준에 따라 세 가지 사용 방식을 지원합니다.

티어	이름	MFR 관리	뷰어	동기화
Tier 1	Standalone	로컬 파일 only	hanspec-viewer (로컬 서버)	Git only
Tier 2	Sync	로컬 + HanSpec 서비스	로컬 뷰어 + 웹 대시보드	양방향 (로컬 ↔ 서비스)
Tier 3	Full Service	HanSpec 서비스 (클라우드)	웹 대시보드	실시간 (Organization 전파 포함)

Tier 1: Standalone — 로컬에서만 사용하기

HanSpec 서비스에 연동하지 않고, 스킬/CLI만 다운받아서 로컬에서 MFR 구조를 관리하는 방식입니다.

HanSpec의 UIA 스킬을 다운로드하여 MFR 구조 생성
로컬 파일 시스템에서 md 파일로 관리
Git으로만 버전 관리
hanspec-viewer로 브라우저에서 MFR 조회

# 설치 없이 바로 실행
npx hanspec-viewer

# 또는 프로젝트 의존성으로 설치
pnpm add -D hanspec-viewer
pnpm hanspec-viewer

# 정적 HTML 빌드 (GitHub Pages 배포용)
npx hanspec-viewer build --out ./hanspec-docs

Standalone Viewer 제공 기능:

MFR 트리 뷰

Module → Feature → Requirement 계층 탐색

상태 대시보드

confirmed / draft / undecided 비율 표시

_pages 뷰

페이지 관점 탐색 + 와이어프레임 렌더링

_changes 타임라인

변경 내역 시간순 표시

교차 참조 그래프

공통정책 → 모듈 영향도 시각화

검색 & 파일 감시

키워드 검색 + 파일 변경 시 자동 갱신

Tier 2 & 3: 원격 동기화 & Full Service

Tier 2부터는 HanSpec 서비스와 연동하여 팀 협업, Organization 정책 전파 등을 활용합니다.

언제 사용하나?

(Tier 1) 로컬에서 MFR을 브라우저로 조회하고 싶을 때
(Tier 2) 팀원들과 MFR 스펙을 공유하고 협업할 때
(Tier 2) 원격 저장소(GitHub 등)에서 최신 스펙을 가져올 때
(Tier 2) 로컬에서 수정한 스펙을 원격으로 반영할 때
(Tier 3) 상위 Organization의 정책을 하위 프로젝트에 적용할 때

흐름도

원격 ↔ 로컬 동기화

┌──────────────┐          ┌──────────────┐
│  원격 저장소   │          │   로컬 MFR    │
│  (GitHub 등)  │          │  디렉터리     │
│              │          │              │
│  MFR 문서     │──Pull──→│  MFR 문서     │
│  _pages      │          │  _pages      │
│  _changes    │←─Push───│  _changes    │
│              │          │              │
└──────────────┘          └──────────────┘
       │                         │
       └────── 충돌 감지 ──────────┘
                  │
                  ▼
           수동 해결 또는
           자동 병합 전략

Organization 정책 전파

┌──────────────────────────────┐
│  상위 Organization            │
│  (회사 레벨)                   │
│                              │
│  공통정책:                     │
│  - 인증: OAuth2 필수           │
│  - 로깅: 구조화 로그 필수       │
│  - 보안: OWASP Top 10 준수     │
│                              │
└──────────┬───────────────────┘
           │ 정책 전파
     ┌─────┴─────┐
     ▼           ▼
┌─────────┐ ┌─────────┐
│ 프로젝트A │ │ 프로젝트B │
│ 중고차앱  │ │ 학원관리  │
│         │ │         │
│ 공통정책: │ │ 공통정책: │
│ (상속됨) │ │ (상속됨) │
│ +커스텀  │ │ +커스텀  │
└─────────┘ └─────────┘

구체적 예시: 중고차 거래 앱

시나리오 1: 원격에서 Pull

팀원 A가 원격 저장소에 새 Requirement를 추가한 상황:

# 원격에 추가된 내용
Module: 거래
  Feature: 구매 신청
    Requirement: 구매 의향서 작성     [draft]
    Requirement: 에스크로 결제 연동   [draft]  ← 신규

# Pull 후 로컬에 반영
vehicle/trade/purchase/
├── REQ-purchase-form.md
└── REQ-escrow-payment.md    ← 새로 동기화됨

시나리오 2: 로컬에서 Push

로컬에서 Requirement 상태를 변경한 후 원격에 반영:

# 로컬 변경
REQ-photo-upload.md
  status: draft → confirmed   ← 로컬에서 변경

# Push 후 원격에 반영
→ 원격 저장소에도 confirmed 상태로 갱신
→ _changes에 변경 내역 기록

시나리오 3: Organization 정책 전파

회사 레벨에서 보안 정책 추가:

# 상위 Organization 정책
공통정책:
  Feature: 보안
    Requirement: 개인정보 암호화 필수 [confirmed]  ← 신규 정책

# 하위 프로젝트(중고차 앱)에 전파
Module: 공통정책
  Feature: 보안                           ← 자동 추가
    Requirement: 개인정보 암호화 필수       ← 상속됨 (수정 불가)
    Requirement: 차량 소유자 정보 마스킹    ← 프로젝트 커스텀 추가 가능

동기화 전략

상황	전략	설명
충돌 없음	자동 병합	변경 사항을 자동으로 합침
같은 파일 수정	충돌 표시	사용자가 수동으로 해결
상위 정책 변경	강제 전파	하위에서 override 불가 (상속)
하위 커스텀 추가	허용	상위 정책 + 추가 항목 가능

디렉터리/파일 구조

{mfr_root}/
├── .hanspec/
│   ├── sync.config.md          # 동기화 설정
│   │   - remote: github.com/org/project
│   │   - strategy: auto-merge
│   └── org-policy.md           # 상속받은 Organization 정책
├── vehicle/
├── trade/
└── common-policy/
    └── security/               # Organization에서 전파된 정책
        ├── 00_feature.md       # [inherited] 태그
        └── REQ-encryption.md   # [inherited, locked] 수정 불가