Yd Blueprint

---
name: yd-blueprint
description: 프로젝트의 구조·기록 흐름·구현 현황·남은 작업을 JSONL 데이터로 적고 bun+Vite+React 청사진 화면(localhost:5173/blueprint/)으로 띄운다. 청사진·구조도·구현 현황표를 만들거나 고칠 때, 프론트·백엔드 경계를 도면으로 그릴 때, 청사진의 근거 코드 경로가 낡았는지 검사할 때 사용한다. 빌드·의존성은 yd-frontend-build, 컴포넌트는 yd-react-expert, 타입 경계는 yd-typescript, UI 토큰은 yd-doksam-ui, 에이전트 지침 AGENTS.yaml 은 yd-agents-yaml 이 맡고 이 스킬은 맡지 않는다.
---

# yd-blueprint

## 역할

프로젝트의 구조·기록 흐름·구현 현황·남은 작업을 **JSONL 데이터**로 적고, **Vite + React** 화면으로 띄운다(패키지 매니저는 bun·pnpm·npm 아무거나). 화면은 `localhost:5173/blueprint/` 하나다. 데이터와 화면을 나눠 두면 에이전트가 HTML 을 문자열로 고치지 않고 줄 단위로 고치며, 검사기가 낡은 경로를 잡는다.

## 언제 쓰나

- 청사진·구조도·구현 현황표를 새로 만들 때 — 첫 인스턴스는 infra 레포의 감지 화면 청사진이다. 옛 정적 청사진 HTML 은 지우지 않고 같은 폴더의 `backup/blueprint/` 로 옮겨 보관했다
- 구성요소·경로·상태가 바뀌어 기존 청사진을 고칠 때
- 프론트(브라우저)·중계·백엔드의 읽기·영상·쓰기 경계를 한 장에 그려야 할 때
- 청사진이 코드와 어긋났는지(없는 경로, 오래된 기준일) 확인할 때

## 만들기

1. **조사** — 청사진에 적을 사실은 코드·설정·배포 상태에서 직접 확인한다. 기존 문서의 문장을 그대로 옮기지 않는다. 확인한 날이 `asOf` 다.
2. **뼈대** — `scripts/new-blueprint.sh [--root <기준 폴더>] [--dir frontend] [--pm bun|pnpm|npm]`. 기본은 git 루트의 `frontend/`. 이미 비어 있지 않은 폴더는 덮어쓰지 않으므로, 기존 프론트가 있으면 `--dir frontend/blueprint` 처럼 비켜 만든다. 하위 프로젝트에 두려면 `--root <하위 프로젝트 폴더>` 처럼 준다. git 저장소 밖이면 `--root` 가 꼭 필요하다.
3. **데이터** — `data/*.jsonl` 에 줄마다 JSON 한 개를 적는다(아래 스키마). 파일명 순서가 표시 순서다. 샘플 줄은 지운다.
4. **띄우기** — `cd <폴더> && bun run dev`(pnpm·npm 이면 `pnpm run dev`·`npm run dev`). 기본 포트 5173 의 `/blueprint/` 가 열린다. 포트가 차 있으면 vite 가 다음 포트를 잡으니 **vite 가 출력한 주소**를 쓴다. 자동 열기는 `BROWSER=none`.
5. **검사** — `check` 스크립트(예: `bun run check`). 스키마·참조·**근거 경로 존재**를 본다. `build` 는 타입체크 후 `dist/` 를 만든다.

**뼈대는 어느 패키지 매니저로 깔아도 수정 없이 같다.** `package.json` 의 스크립트는 특정 매니저나 런타임을 부르지 않는다(`bun run`·`bunx`·`node 파일` 금지). `check` 는 `sh scripts/check.sh` 가 bun 이 있으면 bun, 없으면 node(22.6 이상)로 같은 `check.mjs` 를 돌린다. `--pm` 을 주지 않으면 PATH 에서 bun → pnpm → npm 순으로 처음 찾은 것을 쓴다. bun 을 앞세우는 이유는 설치가 가장 빠르고, pnpm 은 패키지를 받기 어려운 환경이 있기 때문이다(2026-10-05 사용자 지시). 락파일은 설치한 매니저가 만든 하나만 커밋한다. 매니저가 하나도 없으면 `brew install oven-sh/bun/bun`.

## 데이터 스키마

| kind | 필수 필드 | 선택 필드 | 쓰임 |
|---|---|---|---|
| `meta` (정확히 1개) | `title` `asOf`(YYYY-MM-DD) | `eyebrow` `summary` `badges` `links` | 제목·기준일. `links` 는 `[{label, href}]` 로 위쪽 목차 오른쪽에 붙는 이동 링크(운영 화면으로 돌아가기 등) |
| `lane` | `id` `title` | | 도면의 열. 파일 순서 = 왼쪽→오른쪽 |
| `node` | `id` `lane` `row` `title` `state` `summary` | `lines` `paths` `next` `gap` | 도면 상자. `(lane,row)` 칸은 하나뿐 |
| `edge` | `from` `to` | `label` `type`(`flow`·`write`) | 화살표. 쓰기 경로는 `write` |
| `flow` | `title` `body` | | 기록이 만들어지는 순서 카드 |
| `feature` | `name` `state` `now` `remaining` | | 구현 현황 표의 행 |
| `gap` | `id` `priority`(P0~P2) `title` `state` `now` `todo` `done` | `paths` | 남은 작업 |
| `doc` | `id` `title` `paragraphs` | | 접이식 운영 규칙·명세 |

`state` 는 `done`(구현) · `partial`(부분) · `missing`(미구현). 모르는 필드는 검사기가 거절한다.

## 작성 규칙

- **`paths` 는 저장소 루트 기준 전체 경로**다. 검사기가 `git rev-parse --show-toplevel` 기준으로 존재를 확인한다. `detector/a.py · b.py` 같은 줄임 표기는 쓰지 않는다.
- **실시간 상태처럼 쓰지 않는다.** 청사진은 설계와 구현 현황이다. 연결 여부·최신 수치는 운영 화면으로 안내한다.
- **상태는 근거로 나눈다.** 동작을 확인했으면 `done`, 일부만이거나 현장 검증이 남았으면 `partial`, 아직 없으면 `missing`. 돌려 본 적 없는 것을 `done` 으로 두지 않는다.
- **도면 글자는 짧게.** SVG 는 자동 줄바꿈이 없다. `title` 은 한글 15자, `lines` 는 줄당 17자 안팎이고 넘으면 검사기가 경고한다. 긴 설명은 `summary` 에 둔다.
- **열을 건너뛰는 선은 사이 상자를 지난다.** 가급적 인접한 열끼리 잇고, 아니면 행을 비켜 둔다.
- 프론트·백엔드 경계를 보일 때는 열을 `프론트(브라우저) / 중계 / 백엔드` 로 나누고 읽기·영상·쓰기 화살표를 따로 긋는다.
- 기준일은 사실을 다시 확인한 날로 올린다. 60일이 지나면 검사기가 경고한다.

## 배포

`build` 의 `dist/` 는 `base=/blueprint/` 로 만들어져 정적 서버의 `/blueprint/` 아래에 그대로 올리면 된다. nginx 가 허용한 경로만 통과시키는 곳이면 `vite.config.ts` 의 `build` 에 `assetsDir: ""` 와 고정 파일명(`main.js`·`style.css`)을 주고 그 경로를 허용 목록에 넣는다. 설정을 먼저 적용한 뒤 파일을 올린다(첫 인스턴스가 이 방식). 이 스킬은 배포를 하지 않는다. 운영 서버에 올리는 일은 그 서버의 규칙(사전 허가)을 따른다.

## 완료 조건

- `check` 가 `[OK]` 이고 경고를 읽어 처리했다(기준일, 상자 폭)
- `typecheck` 가 통과한다
- 띄운 화면에서 도면의 상자를 눌러 상세·근거 경로·관련 작업 링크가 맞게 나온다
- 데이터의 사실을 코드·설정과 대조했고 `asOf` 를 그 날짜로 올렸다

## 하지 않는 것

- 청사진 안에 실시간 지표를 넣지 않는다
- 빌드·의존성 설정 일반(yd-frontend-build), 컴포넌트 설계(yd-react-expert), 타입 경계(yd-typescript), UI 토큰(yd-doksam-ui), 에이전트 지침 파일(yd-agents-yaml)은 맡지 않는다
- 운영 서버 배포와 커밋·푸시는 이 스킬이 하지 않는다(`yd-git-ship` 절차를 따른다)
- 기존 폴더를 덮어쓰지 않는다

## Learned warnings

- (2026-10-05) 정적 청사진(`blueprint/index.html`, 약 45KB 한 줄)을 고칠 때 문자열 치환으로 해야 했고, 섹션 하나를 넣는 데도 도면·표·목차 세 군데를 따로 맞췄다. 데이터를 JSONL 로 빼면 줄 하나가 곧 변경 단위가 된다.
- (2026-10-05) 옛 청사진의 G-04 "대상" 칸에 `index.html` 이 적혀 있었지만 `detector/` 에는 그 파일이 없었다. 사람이 쓴 경로는 낡는다. 그래서 `paths` 는 검사기가 존재를 확인한다.
- (2026-10-05) 같은 URL 에 해시만 바꿔 다시 열면 브라우저가 새로고침하지 않아 낡은 DOM 을 보게 된다. 청사진을 고친 뒤 확인할 때는 다른 주소를 거쳐 다시 열거나 새로고침한다.
- (2026-10-05) vite 기본 host(`localhost`)는 `[::1]` 에 묶인다. `127.0.0.1:5173` 의 다른 vite(감지 화면 개발 서버)와 포트가 안 겹쳐 둘이 함께 떴고, `localhost:5173/blueprint/` 와 `127.0.0.1:5173/blueprint/` 가 서로 다른 서버로 갔다. 템플릿은 `server.host: "127.0.0.1"` 로 고정해 충돌하면 다음 포트로 간다. 주소는 vite 출력을 읽는다.
- (2026-10-05) bun 만 깔린 환경(PATH 에 node 없음)에서 `bun run` 스크립트 안의 `node 파일.mjs` 호출이 끝나지 않고 멈췄다. 같은 환경에서 `vite`·`tsc` 같은 node_modules/.bin 실행 파일은 정상이었다. 그래서 스크립트에서 `node` 를 직접 부르지 않고 `sh scripts/check.sh` 가 `command -v bun` 으로 런타임을 고른다.
- (2026-10-05) 같은 뼈대를 bun 1.4.2·pnpm 11.9.0·npm 11.19.0 으로 설치해 타입체크·검사·빌드·띄우기가 모두 통과함을 확인했다. 설치는 캐시가 따뜻할 때 bun 0.16초, pnpm 1.5초, npm 5.5초였다.
- (2026-10-05) 첫 인스턴스 청사진을 옛 정적 HTML 에서 옮기며 같은 열 안에서 도는 화살표(확인 API → 저장 이력)는 가운데 세로선이 상자 뒤를 지나 읽을 수 없었다. 선은 빼고 상자 `summary` 에 글로 적었다. 열을 건너뛰는 선도 사이 행을 비워야 상자를 안 지난다.
- (2026-10-05) 열이 4개인 도면은 상세 패널을 옆에 두면 도면이 절반 폭으로 줄어 글자가 작아지고 오른쪽이 잘렸다. 템플릿은 열이 3개를 넘으면 상세를 도면 아래로 내린다.
- (2026-10-05) `pnpm run check -- --repo-root <dir>` 는 `--` 를 지우지 않고 스크립트에 그대로 넘긴다(npm·bun 은 지운다). 검사기는 옵션을 위치가 아니라 이름으로 찾아 둘 다 받는다.