v1.22.0

New

• HTML 문서 스킬 비교 배치 기준, 렌더 측정, 상태 캡션: 실제 산출물(File Search 쿼리 재작성 4축) 피드백 반영. (1) 코드·검색어·요청 본문을 좌우로 나란히 두면 칸 폭이 절반이 되어 양쪽 모두 가로 스크롤되던 문제. eli5 근거 카드(.evs)는 2열 자동 배치가 기본값이었다. 네 스킬(/eli5, /explain-diff, /micro-world, /visual-doc) 공유 디자인 규칙에 "비교는 행으로 쌓고, 좌우는 렌더된 페이지에서 어느 쪽도 가로로 넘치지 않을 때만"을 금지가 아닌 판단 기준으로 추가. eli5 .evs 기본값을 한 열로 바꾸고 짧은 카드끼리는 .evs.pair. eli5 SKILL.md의 "Two states side by side"를 같은 파일의 Static first와 맞게 "두 행"으로 수정. (2) 판단을 글자 수 추정이 아니라 렌더 측정으로: 네 스킬 폴더에 같은 measure.html을 두고, 페이지 사본에 붙여 --dump-dom으로 data-sbs(2열 grid 안 가로 넘침)와 data-fit(그림 라벨의 viewBox 이탈·상자 경계 걸침·라벨 겹침, 렌더된 글꼴로 측정)을 읽는다. 브라우저가 있으면 측정이 글자 폭 표보다 우선한다. 글자 폭 표 값도 Chrome 실측과 대조해 .dg-l 공백·구두점을 4 → 5px로 수정. (3) 상태 비교 그림에 행 캡션이 없던 문제. figure labels (SHARED 블록(eli5·visual-doc·explain-diff)에 선택 클래스 .dg-pill·.dg-cap 상태 캡션(행 위 머리줄)과 .dg-q 주인공 문자열을 추가. 캡션 글은 비교의 종류에 따른 추천 문구로 둔다: 이미 끝난 변경은 BEFORE/AFTER, 제안·예정인 변경은 AS-IS/TO-BE, 시간에 따른 변화가 아닌 비교는 행마다 참인 것을 주제의 말로 (금지 목록 없음). 색은 상태에 맞춘다(깨지는 쪽만 빨강). 새 규칙만 읽은 별도 에이전트로 eli5·visual-doc 예시를 생성해 두 테마 렌더와 측정을 확인했고, 그 과정에서 캡션 위치 모호함, 측정 스크립트의 배지 오탐과 transform 미반영, .dg-q의 fill이 .dg-em 파랑을 덮는 문제를 찾아 수정. 네 스킬의 allowed-tools에 측정과 렌더에 쓰는 Bash(google-chrome *), Bash(chromium *), Bash(cat *)를 추가 (eli5 Step 5의 Chrome 대체 명령도 이 목록에 없어 엄격한 호스트에서는 막혀 있었다). eli5 Step 5 다크 확인 플래그를 렌더 명령과 같은 --force-dark-mode로 통일. 배경과 근거: docs/decisions/2026-07-visual-doc.md (개정 2026-10-23)
• /eli5 묶음 배지·배지 수 기준·근거 카드 rail — 실제 산출물(Vector Store 라우팅 API 설계안) 피드백 반영. (1) 해설 하나가 같은 모양의 상자 여럿(store 5개, 무관 결과 3개)을 말하는데 배지가 첫 상자에만 붙어 상자 하나를 가리키는 것처럼 읽히던 문제: 상자들을 점선 묶음 테두리(.dg-grp, bad 빨강)로 묶고 배지 하나를 묶음 모서리에 두며, 해설은 묶음을 수와 함께 부른다(store 5개). (2) 거의 모든 상자에 배지가 붙어 강조가 아니라 색인이 되던 문제: 배지는 해설이 라벨로 말할 수 없는 사실을 보탤 때만 붙이고, 모든 상자에 붙으면 한 동작을 설명하는 해설을 합치며, 그림이 세로 목록 그 자체면 배지 없이 행 제목으로 시작하는 .notes.plain을 쓴다. (3) 근거 카드에서 꼬리표(1~50)가 잘린 것처럼 보이던 문제: 원인은 줄마다 예약한 배지 자리(.g 20px + 간격 8px)와 꼬리표를 오른쪽 끝으로 미는 margin-left:auto였다. 파일 형태의 배지를 줄 안이 아니라 카드 왼쪽 테두리 위의 .rail(줄 index --i로 위치 계산, 스크롤 본문 밖)로 옮겨 코드가 28px 넓어지고 가로 스크롤에도 배지가 제자리에 남으며, 꼬리표는 글자 바로 뒤에 붙는다. 테이블 형태(.tbl .col)는 배지 자리 .g를 유지. 배경과 근거: docs/decisions/2026-08-eli5.md (개정 2026-10-13)
• /eli5 근거 카드·번호 배지·해설 목록 — 실제 산출물 피드백 반영. (1) 해설이 .say 문단 하나에 코드 칩과 함께 줄글로 이어져 그림의 어느 부분을 말하는지 독자가 찾아야 했고, (2) 설정 파일에 그 줄이 없다는 사실이나 테이블의 컬럼 구성처럼 그림이 보여줄 수 없는 내용을 상자 안 글자(prod·onprem YAML 미설정)로 밀어 넣어 상자가 비좁아지던 문제. 그림의 상자 모서리와 해설 항목에 같은 번호 배지(.dg-m/.m, 파랑·bad 빨강·dim 회색)를 붙이고, 해설을 "배지 + 대상 이름 + 1~2문장" 목록(.notes)과 그래서 결론 한 줄(.say .lab)로 나눴다. 확인하지 못한 사실은 확인 못 한 것 줄로 분리해 [추정]이 문장 안에 숨지 않게 했다. 그림이 말할 수 없는 사실(파일에 없는 줄, 테이블 컬럼, 요청에 없는 필드)에 한해 그림과 해설 사이에 근거 카드(.ev)를 둔다: 파일은 원문 줄 그대로(공유 코드 블록의 sx-* 구문 강조, YAML도 키·숫자·불리언 색), 있어야 하는데 없는 줄은 점선 유령 줄(.ln.ghost + 이 줄이 없음), 테이블은 PK·FK와 타입이 있는 ERD 카드 두 장(.erd), 쓰이는 컬럼만 강조. 모든 줄이 배지 자리(.g)를 예약해 배지가 원문 들여쓰기를 밀지 않는다. 상자 부제는 한 줄(필수 사실 하나 또는 예시 하나, 둘을 섞지 않음)로 제한. 근거 카드는 선택이며 두 번째 시안에서 모든 비트에 코드 블록을 넣고 좌우 2열로 배치했을 때 번잡하다는 피드백을 받아 세로 한 줄 구조로 확정. Step 5에 playwright가 없을 때 Chrome 바이너리로 렌더하는 명령과 "긴 캡처를 잘라서 전부 본다" 절차 추가(첫 발행본의 코드 줄 간격 2배 버그를 렌더 없이 놓친 데서). 수정된 스킬로 job_indexing.mode(automatic·manual) 설명 페이지를 실제 생성해 두 테마 렌더를 확인하는 과정에서 숫자 카드 값(.num .v)이 1개의 숫자와 단위 사이에서 줄바꿈되는 문제를 발견해 word-break:keep-all을 추가. 배경과 근거: docs/decisions/2026-08-eli5.md (개정 2026-10-10)

Fixed

• AGENTS.md 브랜치 테스트 레시피가 플러그인 루트를 ~/.claude로 고정하고 "가장 최근 수정된 cache가 활성"이라고 가정하던 문제. CLAUDE_CONFIG_DIR가 다른 환경(~/.claude-upstage)에서 엉뚱한 트리에 복사해 구버전 스킬로 테스트할 뻔했고, 실제 활성 경로는 mtime 순서가 아니라 installed_plugins.json의 installPath와 스킬 실행 시 찍히는 Base directory였다. 레시피를 ${CLAUDE_CONFIG_DIR:-$HOME/.claude} + installPath 우선으로 바꾸고, cp -r skills/가 대상 디렉토리가 있을 때 skills/skills/로 중첩 복사되던 것을 skills/.로 수정. 같은 세션에서 이미 호출한 스킬은 본문이 메모리에 남아 복사 뒤 /reload-plugins 없이는 구버전이 다시 쓰인다는 점도 명시. PR #80 자체 리뷰에서 추가 수정: 3·5단계가 1단계의 셸 변수($CACHE)에 기대고 있어 별도 Bash 호출에서는 빈 경로로 루트 /skills/에 복사할 수 있었고, 같은 셸이어도 방금 복사한 경로와 비교해 "새 cache" 감지가 되지 않던 문제를 단계마다 변수를 다시 계산하고 탐색 실패 시 중단하도록 수정. 브랜치 테스트 절과 main push 후 동기화 절의 cache 정리 명령도 ~/.claude 고정 + mtime 최신 1개 보존(installPath 디렉토리를 지울 수 있음)에서 installed_plugins.json의 installPath만 남기는 루프로 교체. 정리 직후 다른 세션이 로드 중인 cache도 지울 수 있음을 발견: Claude Code는 로드한 cache 디렉토리에 .in_use/{pid} 마커를 남기므로, installPath 외에도 살아 있는 pid 마커가 있는 디렉토리는 건너뛰도록 두 절의 정리 명령을 다시 수정
• /eli5 SKILL.md의 Code blocks 항목이 이 페이지에서는 .codeblock을 근거 카드 대신 쓸 수 있다고 읽히던 모순(근거 카드 절은 .ev + 배지 자리 .g를 요구)을 "이 페이지에 독립 .codeblock은 없고 sx-*·들여쓰기·생략 줄 규칙만 재사용"으로 정리하고 frame.html의 남은 .say + .codeblock 선택자 삭제. Step 4 primitive 목록에 .notes·.lab·.m/.dg-m·.ev 추가, 조작 그림의 실시간 해설은 그래서 줄 하나를 다시 쓰며 aria-labelledby도 그 줄을 가리키도록 명시, 근거 카드의 생략 줄도 배지 자리를 유지하는 마크업 추가