docs(okayjing): add Jing Studio contract pipeline posts

apps/web/content/okayJing/architecture/jing-factory-hermes-redesign.mdx

@@ -0,0 +1,133 @@
+---
+title: "Jing Factory를 Hermes 시대에 다시 만든다면 — 공장보다 상태 흐름이 먼저다"
+date: 2026-05-24
+tags:
+  - okayJing
+  - JingFactory
+  - Hermes
+  - Ouroboros
+  - workflow
+description: OpenClaw-era Jing Factory와 jing-bridge 실험에서 남길 개념을 고르고, Hermes 단일 체계 안에서 다시 설계한다면 어떤 흐름이 자연스러운지 정리합니다.
+---
+
+<Subtitle level={2}>
+  0. Jing Factory는 아이디어를 제품으로 바꾸려던 실험이었다
+</Subtitle>
+
+<Paragraph>
+  Jing Factory는 이름 그대로 공장에 가까운 발상이었습니다. 진규가 아이디어를
+  던지면, 시스템이 질문하고, 요구사항을 정리하고, 실행 계획을 만들고, 리뷰를
+  거쳐 MVP 흐름까지 이어갑니다. 단순히 코드를 잘 짜는 agent가 아니라, 아이디어가
+  작업 단위로 내려오는 과정을 만들고 싶었던 것입니다.
+</Paragraph>
+
+<Paragraph>
+  과거 jing-bridge 데모에는 이 흐름이 화면으로도 남아 있었습니다. idea intake,
+  clarification report, execution plan, notjing plan review, batch approval 같은
+  slice가 있었습니다. 그 자체로 완성된 제품이라기보다는, 오케이징이 제품 기획과
+  구현 사이를 어떻게 연결할 수 있는지 보는 실험이었습니다.
+</Paragraph>
+
+---
+
+<Subtitle level={2}>1. 예전 구조를 그대로 되살리면 안 되는 이유</Subtitle>
+
+<Paragraph>
+  예전 Jing Factory는 OpenClaw-era의 냄새가 강했습니다. queue 파일, 별도 worker,
+  `.openclaw` 경로, bridge app이 전제였습니다. 당시에는 그게 자연스러웠습니다.
+  채팅과 작업 상태를 분리하고 싶었고, 파일 기반 queue는 durable state를 주는
+  좋은 방식처럼 보였습니다.
+</Paragraph>
+
+<Paragraph>
+  그런데 지금은 기본 구조가 달라졌습니다. Hermes 자체에 session, ticket, skill,
+  cron, memory, tool이 있습니다. 같은 문제를 다시 queue app으로 풀면 중복이
+  됩니다. 그래서 Jing Factory를 다시 만든다면 예전 구현을 복원하기보다, 남길
+  개념을 골라야 합니다.
+</Paragraph>
+
+| 예전 요소               | 지금 남길 것                             |
+| ----------------------- | ---------------------------------------- |
+| 파일 queue              | ticket에 남는 durable state              |
+| bridge screen           | 필요한 경우 나중에 UI로 시각화           |
+| batch approval          | 위험한 변경 전 승인 단계                 |
+| notjing review          | final gate / plan review 루틴            |
+| execution plan artifact | ticket comment/report 또는 별도 artifact |
+
+---
+
+<Subtitle level={2}>2. Hermes 시대의 기본 흐름</Subtitle>
+
+<Paragraph>
+  지금 구조에 맞게 다시 짠다면 시작점은 sessions Forum입니다. 진규가 아이디어를
+  던지고, 오케이징이 대화로 모호성을 줄입니다. 실제 작업이 될 만큼 구체화되면
+  그때 티켓을 엽니다.
+</Paragraph>
+
+```text
+sessions에서 아이디어 시작
+→ 오케이징이 질문하고 범위 수렴
+→ hermes-ticket 생성
+→ 필요하면 Ouroboros CLI 또는 planning skill로 PRD/plan 생성
+→ 산출물을 ticket에 저장
+→ Hermes가 구현
+→ notjing-final-gate 또는 plan review
+→ 진규 승인 후 다음 batch
+```
+
+<Paragraph>
+  이 흐름에서 중요한 건 공장 UI가 아닙니다. 상태가 어디에 남는지입니다.
+  아이디어는 sessions에 남고, 작업은 ticket에 남고, 계획은 ticket report나
+  artifact로 남고, 승인 여부도 ticket에 남습니다. 나중에 UI를 붙이더라도 이 상태
+  흐름이 먼저입니다.
+</Paragraph>
+
+---
+
+<Subtitle level={2}>3. 실제 Ouroboros CLI는 여기에 붙는 게 자연스럽다</Subtitle>
+
+<Paragraph>
+  일반 작업은 `ouroboros-planning` skill로 충분합니다. 하지만 Jing Factory처럼
+  제품 아이디어를 다루는 흐름에서는 실제 Ouroboros CLI가 어울릴 수 있습니다.
+  요구사항 인터뷰, PRD 생성, workflow 상태 관리가 필요하기 때문입니다.
+</Paragraph>
+
+<Paragraph>
+  다만 CLI를 붙인다고 해서 별도 인격을 늘리는 건 아닙니다. 오케이징이 필요할 때
+  Ouroboros CLI를 도구로 호출하고, 산출물을 티켓에 붙이는 구조여야 합니다. 실행
+  주체는 여전히 오케이징입니다.
+</Paragraph>
+
+---
+
+<Subtitle level={2}>4. UI는 마지막에 붙이는 게 맞다</Subtitle>
+
+<Paragraph>
+  예전 jing-bridge는 화면이 먼저 보였기 때문에 공장처럼 느껴졌습니다. 하지만
+  지금 다시 만든다면 UI는 마지막입니다. 먼저 상태 흐름이 안정적이어야 합니다.
+  어떤 단계가 ticket으로 남고, 어떤 단계가 승인으로 막히고, 어떤 산출물이 구현
+  입력이 되는지부터 정해야 합니다.
+</Paragraph>
+
+<Paragraph>
+  UI는 그 다음입니다. 필요하면 SEOJing 안에 운영 문서로 남기거나, Jing Studio
+  같은 별도 화면으로 시각화할 수 있습니다. 하지만 UI가 없어도 작업이 흘러가야
+  합니다. 공장의 핵심은 화면이 아니라 conveyor belt입니다.
+</Paragraph>
+
+---
+
+<Subtitle level={2}>5. 정리</Subtitle>
+
+<Paragraph>
+  Jing Factory를 Hermes 시대에 다시 만든다면, 예전 queue 구조를 그대로 되살리지
+  않는 쪽이 맞습니다. 지금은 오케이징에게 이미 sessions, tickets, skills,
+  memory가 있습니다. 그 위에서 아이디어 → 계획 → 구현 → 리뷰 → 승인 흐름을 얹는
+  게 자연스럽습니다.
+</Paragraph>
+
+<Paragraph>
+  결론은 단순합니다. 공장보다 상태 흐름이 먼저입니다. 상태가 안정적으로 남으면
+  UI는 나중에 붙일 수 있습니다. 반대로 상태가 없으면 아무리 그럴듯한 공장 화면도
+  다시 채팅 로그가 됩니다.
+</Paragraph>

apps/web/content/okayJing/architecture/jing-studio-contract-pipeline.mdx

@@ -0,0 +1,230 @@
+---
+title: "Jing Studio는 목업 생성기가 아니다 — 계약을 먼저 남기는 징팩토리"
+date: 2026-05-29
+tags:
+  - okayJing
+  - JingFactory
+  - JingStudio
+  - Hermes
+  - architecture
+  - MSW
+description: Jing Factory를 아이디어에서 프로토타입까지 밀어붙이는 흐름으로 다시 보면서, 화면보다 요구사항·DTO·API 계약·MSW mock API를 먼저 남기도록 Jing Studio skill을 바꾼 이유를 정리합니다.
+---
+
+<Subtitle level={2}>0. 처음엔 프로토타입을 뽑는 이야기처럼 보였다</Subtitle>
+
+<Paragraph>
+  Jing Factory를 다시 이야기할 때 처음 떠올린 건 단순했습니다. 진규가 아이디어를
+  던지면 오케이징이 화면을 만들고, mock data를 채우고, 실제로 눌러볼 수 있는
+  프로토타입까지 만들어주는 흐름입니다. 말만 들으면 꽤 괜찮습니다. 아이디어가
+  머릿속에만 있는 것보다, 브라우저에서 만져볼 수 있는 편이 훨씬 빠르기
+  때문입니다.
+</Paragraph>
+
+<Paragraph>
+  그런데 막상 이걸 작업 흐름으로 고정하려고 보니, 그냥 목업 화면을 빨리 만드는
+  것만으로는 부족했습니다. 화면은 나올 수 있습니다. 하지만 그 화면이 나중에
+  백엔드와 어떻게 연결될지, 어떤 request와 response가 필요한지, 어떤 데이터가
+  서버 책임이고 어떤 데이터가 프론트의 view model인지가 남지 않으면 같은 문제가
+  반복됩니다.
+</Paragraph>
+
+<Paragraph>
+  겉으로는 "프로토타입 생성" 문제였지만, 실제로는 "계약을 언제 남길 것인가"의
+  문제에 가까웠습니다.
+</Paragraph>
+
+---
+
+<Subtitle level={2}>
+  1. mock data가 대충 들어가면 나중에 API가 흔들린다
+</Subtitle>
+
+<Paragraph>
+  프론트 작업에서 mock data는 자주 가볍게 취급됩니다. 아직 API가 없으니 일단
+  화면에 필요한 필드를 아무렇게나 만들고, 컴포넌트가 예쁘게 보이면 넘어갑니다.
+  짧은 데모에서는 이 방식도 잘 돌아갑니다. 잠깐은.
+</Paragraph>
+
+<Paragraph>
+  문제는 실제 연동 시점에 옵니다. 프론트는 `title`, `scoreLabel`,
+  `isHighlighted` 같은 값을 기대하는데, 백엔드는 `name`, `matchScore`,
+  `priority` 같은 DTO를 내려줍니다. 어떤 값은 서버가 계산해야 할 것처럼 보이고,
+  어떤 값은 프론트에서 포맷팅하면 되는 값처럼 보입니다. 이 기준이 없으면 API
+  wrapper, mapper, component가 한꺼번에 흔들립니다.
+</Paragraph>
+
+```text
+대충 만든 mock data
+→ 화면은 빨리 나옴
+→ API 계약은 남지 않음
+→ 실제 백엔드 연동 때 필드명과 책임이 어긋남
+→ mapper/API wrapper/component를 다시 정리함
+```
+
+<Paragraph>
+  그래서 이번 Jing Studio 변경에서는 mock data를 단순 fixture가 아니라 계약의
+  초안으로 보기로 했습니다. 더미 데이터를 만들기 전에 요구사항, 도메인 모델,
+  DTO, API contract를 먼저 지나가게 만든 이유가 여기에 있습니다.
+</Paragraph>
+
+---
+
+<Subtitle level={2}>2. MSW는 더미 서버가 아니라 계약 시뮬레이터다</Subtitle>
+
+<Paragraph>
+  이번 변경에서 가장 중요한 기준은 MSW의 위치였습니다. MSW를 "백엔드 없을 때
+  쓰는 가짜 응답" 정도로 보면 이 흐름의 가치가 작아집니다. Jing Studio에서는
+  MSW를 API 계약 시뮬레이터로 봅니다.
+</Paragraph>
+
+```text
+screen data needs
+  → domain model
+  → request/response DTOs
+  → mock data fixtures
+  → MSW handlers
+  → API client functions
+  → view-model mappers
+  → UI blocks/screens
+```
+
+<Paragraph>
+  프론트는 처음부터 실제 API를 호출하듯 API client를 호출합니다. 다만 응답을
+  실제 서버가 아니라 MSW handler가 돌려줄 뿐입니다. 이렇게 하면 나중에 백엔드가
+  생겼을 때 바꿔야 하는 지점이 줄어듭니다. UI는 그대로 두고, MSW를 끄고, 같은
+  API client가 실제 base URL을 바라보게 만들 수 있습니다.
+</Paragraph>
+
+<Paragraph>
+  중요한 건 handler가 화면 전용 값을 대충 반환하지 않는 것입니다. request DTO,
+  response DTO, status code, validation error, empty/error/auth state를 같이
+  설계해야 합니다. 그래야 MSW가 단순 mock이 아니라 백엔드와 이야기할 수 있는
+  계약 초안이 됩니다.
+</Paragraph>
+
+---
+
+<Subtitle level={2}>3. 그래서 산출물이 늘어났다</Subtitle>
+
+<Paragraph>
+  기존 Jing Studio skill은 아이디어를 product brief, reference map, screen
+  inventory, DESIGN.md, block kit, Figma layout, implementation brief로 넘기는
+  흐름이었습니다. 이 흐름은 화면과 디자인을 잡는 데는 괜찮았습니다. 하지만
+  백엔드와 이어지는 계약은 약했습니다.
+</Paragraph>
+
+<Paragraph>그래서 이번에 run directory의 기본 산출물을 늘렸습니다.</Paragraph>
+
+```text
+runs/<slug>/
+  product-brief.md
+  requirements.md
+  reference-map.json
+  domain-model.md
+  screen-inventory.json
+  dto-spec.ts
+  api-contract.md
+  mock-data-plan.md
+  msw-handlers-plan.md
+  DESIGN.md
+  block-kit.json
+  figma-layout-brief.md
+  figma-placement.json
+  figma-layer-map.json
+  layout-brief.json
+  implementation-brief.md
+  backend-requirements.md
+```
+
+<Paragraph>
+  목록만 보면 문서가 너무 많아 보일 수 있습니다. 그런데 역할을 나누면 그렇게
+  과한 구조는 아닙니다. `requirements.md`는 무엇을 만들지 정리하고,
+  `domain-model.md`는 어떤 명사가 있는지 잡고, `dto-spec.ts`는 API 입출력을
+  고정합니다. `api-contract.md`는 endpoint와 status code를 남기고,
+  `mock-data-plan.md`와 `msw-handlers-plan.md`는 프론트가 실제 API처럼 작업할 수
+  있게 만듭니다. 마지막으로 `backend-requirements.md`가 백엔드 구현자에게 넘길
+  요구사항을 정리합니다.
+</Paragraph>
+
+---
+
+<Subtitle level={2}>4. 화면 모델과 서버 DTO를 분리해야 한다</Subtitle>
+
+<Paragraph>
+  이번 변경에서 따로 박아둔 기준이 있습니다. UI-only view model을 backend DTO로
+  착각하지 않는 것입니다. 화면에는 종종 서버가 알 필요 없는 값이 필요합니다.
+  예를 들어 `scoreLabel`, `subtitle`, `badgeTone`, `groupTitle` 같은 값은 화면
+  표현에 가깝습니다.
+</Paragraph>
+
+<Paragraph>
+  반대로 서버 DTO는 서버가 책임지는 사실을 내려줘야 합니다. 추천 점수라면
+  `matchScore`, 추천 이유라면 `matchReasons`, 식별자라면 `clubId`처럼 원본에
+  가까운 값이 좋습니다. 이 둘을 섞으면 나중에 백엔드가 UI 표현을 끌어안거나,
+  프론트가 서버 책임을 임의로 흉내 내게 됩니다.
+</Paragraph>
+
+```text
+API Response DTO
+  → 서버가 책임지는 사실
+
+Frontend ViewModel
+  → 화면 표현, 라벨, 포맷팅, grouping, derived flag
+
+Mapper
+  → DTO를 ViewModel로 바꾸는 경계
+```
+
+<Paragraph>
+  이 경계가 있어야 백엔드 요구사항 분석도 선명해집니다. "이 필드는 서버가
+  계산해야 하는가?" "프론트에서 포맷팅하면 되는가?" "DB에 저장되는 값인가,
+  요청마다 계산되는 값인가?" 같은 질문이 자연스럽게 나옵니다.
+</Paragraph>
+
+---
+
+<Subtitle level={2}>5. Figma보다 먼저 계약이 있어야 한다</Subtitle>
+
+<Paragraph>
+  Jing Studio에는 여전히 Figma MCP 흐름이 있습니다. 오케이징이 회색 블록을
+  만들고, 진규가 위치와 크기를 조정하고, 다시 layer tree를 읽어 implementation
+  brief로 바꾸는 흐름입니다. 이건 유효합니다. 다만 Figma가 요구사항의 출처가
+  되면 안 됩니다.
+</Paragraph>
+
+<Paragraph>
+  Figma는 배치 협상 화면입니다. 요구사항은 `requirements.md`에, 데이터는
+  `domain-model.md`에, API 계약은 `api-contract.md`에 있어야 합니다. Figma에서
+  어떤 카드가 오른쪽에 놓였다고 해서 서버 DTO가 바뀌면 안 됩니다. 반대로 API
+  계약이 바뀌었다면 그 이유가 문서에 남아야 합니다.
+</Paragraph>
+
+<Paragraph>
+  그래서 이번 변경의 핵심은 UI 자동화보다 artifact pipeline에 가깝습니다. 화면은
+  만들 수 있습니다. 하지만 화면보다 먼저 남아야 하는 것은 계약입니다.
+</Paragraph>
+
+---
+
+<Subtitle level={2}>6. 정리</Subtitle>
+
+<Paragraph>
+  이번 변경으로 Jing Studio는 "아이디어를 목업으로 바꾸는 도구"에서 조금 더
+  나아갔습니다. 이제 목표는 아이디어를 요구사항, DTO, API contract, MSW mock
+  API, backend requirements까지 연결하는 것입니다.
+</Paragraph>
+
+<Paragraph>
+  이게 잘 되면 진규가 아이디어를 던졌을 때 결과물은 단순 화면이 아닙니다.
+  프론트는 바로 만져볼 수 있는 프로토타입을 얻고, 백엔드는 어떤 API와 DTO를
+  만들어야 하는지 초안을 얻습니다. 그리고 오케이징은 다음 세션에서도 같은
+  artifact를 읽고 이어갈 수 있습니다.
+</Paragraph>
+
+<Paragraph>
+  결론은 단순합니다. Jing Factory에서 mock data는 장식이 아닙니다. mock data는
+  계약을 검증하는 재료입니다. MSW는 그 계약을 실제 호출처럼 굴려보는 장치입니다.
+  그래서 Jing Studio는 목업 생성기가 아니라, 제품 계약을 먼저 남기는
+  파이프라인이어야 합니다.
+</Paragraph>