msd-core/docs/ko-KR/how-to/work-in-parallel-with-workstreams.md

워크스트림으로 여러 영역을 병렬로 작업하는 방법

목표: 백엔드 API, 프론트엔드 대시보드, 인프라 등 서로 다른 마일스톤 영역에서 한 영역의 계획 상태가 다른 영역으로 유입되지 않도록 동시 작업을 수행합니다.

사전 조건: 활성화된 MSD Core 프로젝트(.planning/ROADMAP.md 존재). 없는 경우 먼저 /msd-new-project를 실행하세요.

---

워크스트림이란

워크스트림은 단일 코드베이스 내의 독립된 계획 컨텍스트입니다. 각 워크스트림은 독립적인 STATE.md, ROADMAP.md, REQUIREMENTS.md, phases/ 디렉터리를 포함하는 .planning/workstreams/<name>/ 서브트리를 가집니다. 코드베이스 자체(소스 코드, git 히스토리, 브랜치)는 모든 워크스트림이 공유합니다.

.planning/
├── PROJECT.md          ← 공유
├── config.json         ← 공유
├── codebase/           ← 공유
└── workstreams/
    ├── backend-api/
    │   ├── STATE.md
    │   ├── ROADMAP.md
    │   ├── REQUIREMENTS.md
    │   └── phases/
    └── frontend-dash/
        ├── STATE.md
        ├── ROADMAP.md
        ├── REQUIREMENTS.md
        └── phases/

워크스트림이 활성화되면 모든 MSD 명령인 /msd-progress, /msd-discuss-phase, /msd-plan-phase, /msd-execute-phase가 해당 워크스트림의 디렉터리에서 읽고 씁니다. 워크스트림을 전환하면 소스 트리를 건드리지 않고 모든 명령이 다른 서브트리로 리디렉션됩니다.

---

워크스트림 생성

/msd-workstreams create backend-api

MSD는 .planning/workstreams/backend-api/ 아래에 워크스트림 디렉터리를 생성하고 기본 STATE.md와 ROADMAP.md를 시드합니다. 워크스트림은 자동으로 활성화되지 않으며 명시적으로 전환해야 합니다.

---

워크스트림 목록 보기

/msd-workstreams list

모든 워크스트림과 현재 세션에서 활성화된 워크스트림을 표시합니다.

---

워크스트림으로 전환

/msd-workstreams switch backend-api

이 시점부터 모든 MSD 워크플로 명령은 backend-api 컨텍스트에서 동작합니다. 전환은 세션 범위로 적용됩니다. 같은 저장소에서 여러 Claude Code 터미널이 열려 있는 경우, 각 세션은 서로 간섭 없이 서로 다른 활성 워크스트림을 유지할 수 있습니다.

전환 후 일반 페이즈 워크플로를 진행합니다:

/msd-discuss-phase 1
/msd-plan-phase 1
/msd-execute-phase 1
/msd-verify-work 1

다른 영역에서 작업하려면 두 번째 터미널에서 워크스트림을 전환합니다:

/msd-workstreams switch frontend-dash
/msd-discuss-phase 1
/msd-plan-phase 1

---

모든 워크스트림의 진행 상황 확인

/msd-workstreams progress

워크스트림 간 전환 없이 모든 워크스트림의 페이즈 상태, 현재 위치, 미완료 작업을 포함한 교차 워크스트림 요약을 출력합니다.

단일 워크스트림의 상세 상태 확인:

/msd-workstreams status backend-api

---

워크스트림에서 작업 재개

컨텍스트 초기화나 새 세션 이후 위치를 복원합니다:

/msd-workstreams resume backend-api

이 명령은 워크스트림을 활성화하고 마지막으로 알려진 위치를 복원합니다. 전환 후 /msd-resume-work를 실행하는 것과 동일합니다.

---

완료된 워크스트림 보관

워크스트림의 마일스톤 작업이 완료되면:

/msd-workstreams complete backend-api

MSD는 워크스트림을 보관 상태로 표시하고 활성 목록에서 제거합니다. 계획 아티팩트는 감사 목적으로 .planning/workstreams/backend-api/에 보존됩니다.

---

세션 컨텍스트 전환 없이 특정 워크스트림에 명령 실행

세션의 활성 컨텍스트를 변경하지 않고 특정 워크스트림에 대해 하나의 명령을 실행해야 하는 경우 --ws 플래그를 사용합니다:

/msd-progress --ws frontend-dash
/msd-plan-phase 2 --ws backend-api

--ws는 해석 우선순위에서 가장 높은 우선권을 가지며 세션 범위의 포인터를 변경하지 않습니다.

---

워크스트림과 워크스페이스 중 선택 기준

워크스트림을 선택할 때:

• 모든 작업이 동일한 저장소에 있고 같은 git 히스토리를 공유할 때
• 서로의 STATE.md를 덮어쓰지 않고 서로 다른 관심 영역(API, UI, 인프라)을 동시에 계획하거나 논의하고자 할 때
• 워크스트림 생성 시 브랜치를 별도로 만들 필요가 없을 때(각 워크스트림의 실행 내에서 일반적으로 브랜칭 가능)
• 전체 git 워크트리 생성 오버헤드가 필요한 격리에 비해 과하다고 느껴질 때

워크스페이스를 선택할 때:

• 여러 저장소(예: hr-ui와 ZeymoAPI)에서 작업할 때
• 기능별로 별도의 git 워크트리 또는 클론이 필요할 때 — 완전히 독립된 브랜치, 잠금 파일, 빌드 아티팩트
• 메인 저장소의 .planning/ 하위 디렉터리가 아닌 완전히 별도의 .planning/ 루트로 /msd-new-project를 독립적으로 실행하고자 할 때

---

관련 문서

• 워크스페이스로 작업 격리
• 페이즈 루프
• 명령 참조
• 문서 인덱스