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] [--deps-dir ~/.tmp]. 기본은 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/ 를 만든다.

스크래치·로컬 청사진은 의존성을 한 폴더에 모은다. --deps-dir ~/.tmp 를 주면 그 폴더의 node_modules 에 없는 패키지만 설치하고, 청사진 폴더에는 설치하지 않는다. 대상이 그 폴더 아래면 링크하지 않는다. Node 가 상위 폴더를 타고 올라가 찾기 때문이다. 밖이면 node_modules 심링크를 건다. 패키지는 버전 하나만 둘 수 있고 이미 있는 패키지는 버전이 달라도 건드리지 않는다. 락파일이 프로젝트에 남지 않으므로 커밋할 청사진에는 쓰지 않는다. vite 캐시는 템플릿이 프로젝트 폴더의 .vite 에 두므로 공유 node_modules 를 써도 섞이지 않는다.

뼈대는 어느 패키지 매니저로 깔아도 수정 없이 같다. 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.

데이터 스키마

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

작성 규칙

• 한눈에 들어오게 쓴다. 맨 위 수치 한 줄은 구성요소 상태 수와 남은 작업 수다. 데이터에서 자동으로 세고 0 은 적지 않는다. 글 칸은 문장 60자, 한 칸 120자를 넘기면 check 가 경고한다. 긴 설명은 문서로 보내고 경로만 남긴다.
• 배치는 둘 중 하나를 고른다. 계층이 위에서 아래로 쌓이는 구조(화면→서버→데이터)는 tiers, 호출 순서·쓰기 경로가 핵심이면 grid 다. tiers 는 화살표를 그리지 않는다. edge 를 쓰면 검사기가 거절하고, 띠 사이 연결은 lane.toNext 한 줄로 적는다. tiers 의 group 은 한 띠 안의 이웃 노드만 묶는다. 띠 하나에 노드가 6개를 넘으면 경고한다.
• tags 는 기술명만, lines 는 하는 일만 적는다. tags 는 3개까지, 각 18자 안이다. lines 와 합쳐 3줄을 넘기면 경고한다.
• 선은 두 가지로 읽힌다. 실선은 동작하는 흐름, 점선(boundary·group)은 경계나 미연결이다. 범례는 도면에 쓰인 종류만 보인다.
• AI 냄새를 내지 않는다. 이모지 아이콘, 한쪽 가장자리 색 띠, 그라디언트·그림자를 쓰지 않는다. 색 줄 달린 숫자 카드와 테두리 배지 나열도 쓰지 않는다. 상태는 상자 테두리 색과 테두리 없는 글자로만 보인다.
• 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 은 지운다). 검사기는 옵션을 위치가 아니라 이름으로 찾아 둘 다 받는다.
• (2026-10-11) 도면 상자 왼쪽의 상태 색 띠는 AI 생성물 티가 난다는 사용자 지적으로 뺐다. 상태는 테두리 색으로만 보인다. 구현은 기본 테두리, 부분·미구현만 색을 준다.
• (2026-10-11) codex·agy 와 두 차례 교차 검토해 AI 냄새를 걷어 냈다. 색 줄 달린 숫자 카드는 수치 한 줄로, 테두리 배지는 글자로 바꿨다. 띠 상자는 가는 구분선으로, 페이지 전체 격자는 도면 안 격자로 줄였다. 첫 상자를 미리 고르지 않는다(굵은 테두리가 상태 강조로 읽힌다).
• (2026-10-11) impeccable 검출기(detect <URL>)를 돌렸다. 종이 모드의 "부분" 노랑 글자가 흰 바탕에서 2.2:1 로 WCAG AA(4.5:1) 미달이었다. 상태 색은 테두리와 글자에 함께 쓰이므로 종이 토큰을 어둡게 잡는다. tiers 는 실제 폭에 맞춰 좁은 화면에서 한 줄에 카드 하나로 쌓는다.