시나리오 스튜디오

시나리오와 동작 규칙을 앱 안에서 직접 관리하고, 규칙 사이의 관계를 명시하고, 명세가 덜 여문 곳을 자동으로 찾아내는 도구다. AI 에이전트가 MCP 로 붙어 명세를 함께 만든다.

엑셀 시트를 원본에서 내려놓고 앱을 원본으로 삼는 것이 목표다.

---

필요한 것

	버전	확인
Node.js	22 이상	node -v
pnpm	10 이상	pnpm -v

pnpm 이 없으면 corepack enable pnpm 으로 켠다. DB 는 SQLite 파일이라 따로 설치할 게 없다.

5분 안에 띄우기

git clone https://github.com/JayStevency/open-scenario-studio.git
cd open-scenario-studio

pnpm install
pnpm db:migrate       # data/scenario-studio.db 를 만든다
pnpm db:seed:sample   # 예제 데이터를 넣는다 (규칙 28건)
pnpm dev              # 웹과 API 를 함께 띄운다

브라우저에서 http://localhost:5173 을 연다. 규칙 28건이 표로 뜨면 성공이다.

pnpm dev 는 두 프로세스를 함께 띄운다.

• 웹 http://localhost:5173
• API http://localhost:3000

화면 다섯 개

탭	하는 일
BR 시트	규칙을 표로 놓고 셀을 바로 고친다. 검색·필터, 추가·복제·삭제
관계도 편집	시나리오를 노드로 그린다. 끌어 옮기면 위치가 저장되고, 이으면 관계가 생긴다
CAP · DEV 편성	규칙을 칩으로 끌어 기능 그룹에 배정한다. 여기서 나눈 단위가 개발 작업 단위가 된다
시나리오 상세	규칙 사이의 관계를 만들고 해제한다. 변경 이력과 메모를 함께 본다
검사	명세가 덜 여문 곳 8종을 찾는다. 데이터를 고치면 즉시 다시 센다

헤더의 엑셀 내보내기 로 전체를 시트별로 나눠 받는다.

내 데이터 넣기

예제 대신 자기 데이터를 쓰려면 TSV 여섯 개를 design/data/ 에 넣고 시드한다.

mkdir -p design/data
cp /어딘가/*.tsv design/data/
pnpm db:seed

파일 이름과 열 구성은 samples/README.md 를 따른다. 탭 구분, UTF-8 BOM 이라 엑셀에서 바로 열린다.

design/data/ 는 저장소에 올리지 않는다 — 프로젝트마다 다른 내용이기 때문이다. 없어도 빌드와 테스트는 통과한다.

에이전트 붙이기

에이전트는 명세를 읽는 쪽이 아니라 만드는 쪽이다. 규칙 문장을 다듬고, 규칙 사이의 관계를 찾아내고, 기능 그룹 편성을 제안한다.

claude mcp add scenario-studio -- pnpm --filter @oss/mcp start
pnpm mcp:smoke    # 도구가 DB 에 제대로 붙는지 점검

도구는 여덟 개다. 읽기는 get_project · get_rule · list_rule_links · check_integrity, 쓰기는 update_rule · assign_rule_to_capability · create_rule_link · delete_rule_link.

쓰기는 모두 건 단위이고 version 을 요구한다. 사람이 화면에서 같은 데이터를 고치고 있으면 거절하고 다시 읽게 한다. 에이전트가 고친 것은 이력에 따로 표시되고, 잘못 고쳤으면 시나리오 상세의 이력에서 되돌릴 수 있다.

명령

명령	하는 일
pnpm dev	웹 + API 함께
pnpm dev:web / pnpm dev:api	하나만
pnpm db:migrate	DB 파일 생성과 스키마 적용
pnpm db:seed / pnpm db:seed:sample	내 데이터 / 예제 데이터
pnpm db:reset	DB 를 비우고 다시 만든다
pnpm mcp:smoke	MCP 도구 점검
pnpm test	테스트
pnpm typecheck	타입 검사
pnpm build	프로덕션 빌드
pnpm check:fix	포맷·린트 자동 수정

막혔을 때

브라우저가 연결하지 못한다 — 5173 이나 3000 을 다른 프로그램이 쓰고 있는지 본다. lsof -nP -iTCP:5173 -sTCP:LISTEN

화면이 비어 있다 — 데이터를 안 넣었다. pnpm db:seed:sample

DATABASE_URL 관련 오류 — 기본값은 저장소 안 data/scenario-studio.db 다. 다른 위치를 쓰려면 apps/api/env.example 을 apps/api/.env 로 복사한다.

스키마를 고친 뒤 타입이 안 맞는다 — pnpm --filter @oss/api db:generate

구성

packages/domain   공용 도메인 — 타입, TSV 파서, 무결성 검사, 정합성 검사
apps/api          Fastify 5 · tRPC 11 · Prisma 7 · SQLite
apps/mcp          MCP 서버 — 에이전트가 붙는 통로
apps/web          Vite 7 · React 19 · TanStack Table/Query · React Flow · dnd-kit
samples/          예제 데이터
design/           요구사항 명세와 동작 프로토타입

요구사항은 design/REQUIREMENTS.md, 설계 판단의 근거는 CLAUDE.md 에 있다.

아직 없는 것

• 사용자 인증 — 지금은 x-user-id 헤더로 신원을 흉내 낸다
• 유형·담당 주체 선택 목록의 관리자 설정 — 지금은 데이터에 쓰인 값을 모아 쓴다
• 시나리오 자체의 추가·삭제
• 엑셀 가져오기 — 앱이 원본이라는 전제라 범위 밖이다
• 되돌리기는 수정 전체와 규칙 간 관계의 생성·삭제까지다

드래그가 들어가는 두 화면(관계도 노드 이동, 편성 보드 칩 옮기기)은 브라우저에서 직접 확인해야 한다.

라이선스

MIT