배경 · 문제

• Claude Skills(SKILL.md 기반 작업별 지침 모음)는 유용하지만, 지금 어떤 스킬이 켜져 있는지 보려면 매번 ~/.claude/skills 폴더를 직접 열어 확인해야 했다. 한눈에 보고 스위치처럼 켜고 끌 도구가 없어 직접 만들었다.

접근

• 워크스페이스·전역 스킬을 사이드 패널에 목록(Tree View)으로 보여주고, 파일을 직접 고치지 않고 클릭 한 번으로 켜고 끄게 했다.
• 스킬 설명(frontmatter의 name/description)을 목록에 마우스를 올리면 바로 보이게 하고, 파일이 추가·삭제되면 화면에 실시간 반영했다.
• 파일 변경 감지를 처음엔 기본 기능(fs.watch)으로 했는데 리눅스에서 하위 폴더를 못 잡고 저장을 놓치는 문제가 있어, 더 안정적인 라이브러리(chokidar)로 바꾸고 짧은 시간에 몰려 오는 변경은 하나로 묶었다(150ms 디바운스).
• 스킬 상태를 '프로젝트별'과 '전역'으로 나눠 저장해, 한 프로젝트 설정이 다른 프로젝트로 새지 않게 했다.
• 켜기/끄기를 각각 별도 명령으로 나눠, 빠르게 연타해도 상태가 꼬이지 않게 했다.
• 남이 만든 SKILL.md 내용을 신뢰하지 않도록 설정(isTrusted = false)해, 의도치 않은 명령 실행을 막았다.

결과

• 실제로 불편했던 문제를 직접 도구로 만들어 확장 마켓(Open VSX)에 publisher(parksubeom.claude-skills-panel)로 정식 배포했다.

배경 · 문제

• Claude Code는 대화 세션이 바뀌면 지난번에 배운 것·실수·의사결정을 기억하지 못해, 매번 같은 맥락을 다시 설명해야 했다("매일 새로 출근하는 알바생" 같은 문제).

접근

• 세션이 끝나면 자동으로 대화를 분석해 '배운 것'(knowledge.md)과 '실수·함정'(gotchas.md)을 파일로 쌓고, 11가지 종류로 분류했다.
• 대화의 한글 비율을 보고 한국어/영어를 자동으로 골라 기록하고, 결과는 그냥 텍스트(markdown)라 직접 고치거나 지울 수 있게 했다(지운 항목은 다음 세션에 다시 안 나옴).
• 비용을 줄이려 여러 단계로 걸렀다: 공짜 규칙으로 먼저 거르고 → 값싼 모델로 "기록할 가치가 있나?"만 한 번 묻고 → 중복 제거 순. 그 결과 세션의 약 90%가 비싼 분석 전에 걸러져, 비싼 호출이 약 1/10로 줄었다.
• 개인정보 보호를 위해 중간 서버 없이 내 컴퓨터에서 바로 API로 보내고, 대화 원문은 저장하지 않았다(중복 확인용 짧은 해시만 저장).
• 다른 라이브러리 없이 50KB로 만들어 코드를 통째로 확인할 수 있고, 설정만 지우면 언제든 끌 수 있다.

결과

• 대부분 세션은 거의 0원, 실제 분석까지 간 세션만 약 0.1달러 수준으로 비용을 눌렀다. npm에 배포.

배경 · 문제

• 프로젝트마다 폴더 구조·컴포넌트 작성법·테스트·커밋 방식이 제각각이 되고, AI 코딩 도구에도 매번 같은 규칙을 다시 알려줘야 했다. 그래서 작업 규칙과 그 규칙대로 일해 주는 Claude Code 스킬을 한 묶음으로 만들어, 명령어 한 줄로 어떤 프로젝트에나 깔리게 했다.

접근

• npx bumpist-code init 한 줄이면 규칙·스킬·문서가 프로젝트 .claude/에 복사되고 CLAUDE.md까지 자동 연결된다.
• package.json을 보고 어떤 프레임워크(Vue/React/Next.js)인지 자동으로 알아내 맞는 규칙을 고른다.
• 작업 종류에 맞는 14개 스킬(계획 세우기·기능 추가·API 타입 생성·테스트 작성·PR 준비 등)을 제공한다.
• 접근성 기준(WCAG AA)과 폴더 구조 설계 방식(Feature-Sliced Design)을 기본으로 넣었다.
• 원본에 계속 연결되는 방식이 아니라 '복사해서 넣는' 방식이라, 받은 시점의 버전이 그대로 고정된다.
• 버전 규칙(semver)으로 배포해 프로젝트마다 다른 버전을 따로 쓸 수 있고, 어떤 버전을 받았는지 기록해 둔다.

결과

• npm에 배포하고, 실제 서비스 MVP(re-pin)을 이걸로 시작해 Next.js 트랙까지 검증했다.

학생·교사·발표자가 동일한 인터랙티브 캔버스를 공유하되, 각 역할은 서로 다른 실행 컨텍스트(메인 앱 vs CDN 임베드)에서 동작한다.

배경 · 문제

• 학생·발표자 화면은 CDN 번들로 shadow DOM 안에 임베드되는데, 교사 뷰어만 메인 앱에서 캔버스를 직접 렌더했다. 하나의 캔버스가 서로 다른 두 렌더링 경로를 타면서 교구 동작·좌표계·재생 결과가 화면마다 어긋났다.
• 학생 풀이를 교사가 다시 볼 때 재생이 중간 과정 없이 최종 상태로 즉시 스냅되어, 풀이 과정을 따라 보며 지도하는 핵심 시나리오가 성립하지 못했다.

접근

• 렌더링 경로 통일 — 교사 뷰어를 메인 앱 직접 렌더에서 CDN 임베드로 이관해 세 역할을 같은 렌더링 파이프라인으로 모았다. 한 번에 전환하는 리스크를 줄이려 feature flag로 감싸 6단계로 점진 적용했다.
• 크로스번들 통신 브릿지 — CDN 번들은 독립된 Pinia 스토어와 shadow DOM을 써서 메인 앱과 상태를 직접 공유할 수 없다. window 커스텀 이벤트로 두 컨텍스트를 연결하고, 리스너 등록 시점에 올바른 Pinia 인스턴스를 캡처해 잘못된 스토어에 상태가 기록되는 버그를 차단했다.
• 히스토리 재생 엔진 — 학생의 조작을 스트림으로 기록해 두고 교사 뷰어에서 재구성해 재생했다. 일반 객체는 이동 경로 구간을 보간(tween)해 부드럽게, 3D 교구는 카메라 상태를 보간해 궤적을 살렸다.
• 재생 충실도 개선 — 한 프레임에 몰아 그려 스냅되던 재생을 조작 타임스탬프에 비례해 배속(0.5~2배) 구간에 분산 렌더하도록 바꿨다. 최종 상태로 갔다가 시작점으로 되돌아오던 아티팩트를 제거하고, 히스토리에 누락돼 재생 시 사라지던 교구 16종의 조작도 기록되게 했다.

결과

• 학생·교사·발표자 세 역할의 렌더링 경로를 하나로 통합해 재생 결과·좌표 일관성을 확보.
• 재생을 정적 스냅에서 배속 연동 트레이스 애니메이션으로 전환(주사위 재생 약 11s → 4.9s @0.5×).
• 회귀 방지 테스트 20개를 함께 작성, 64개 파일·3,700여 줄 변경을 회귀 없이 반영.

① 슬라이드 이동 성능 — 2.8초 → 0.3초 (약 9배)

• 상황: 슬라이드를 넘길 때마다 현재 화면을 통째로 이미지로 저장하느라 전환이 ~2.8초 블로킹
• 어떻게: 화면 전체를 한 번에 저장하던 방식을 버리고 화면 구성요소(수식·필기·3D)를 따로 합성 + "실제로 편집했을 때만" 저장하도록 변경
• 왜: 병목이 화질(해상도)이 아니라 "화면 전환 직전에 저장이 끝나길 기다리는" 구조였기 때문 — 저장을 전환과 분리하면 대기 자체가 사라짐
• 효과: 전환 ~2.8초 → ~0.3초, 보기만 할 땐 기존 썸네일 유지

② WebGL 렌더 부하 — 51 → 13fps (약 4배)

• 상황: 3D 교구가 화면이 그대로여도 매 순간 다시 그려져, 여러 개가 겹치면 프레임 드롭
• 어떻게: "상태가 바뀔 때만 다시 그리기"로 전환, 카메라를 움직이는 동안만 잠깐 연속 렌더 후 정지
• 왜: 아무것도 안 바뀐 순간에도 계속 그리는 게 낭비 — 유휴 시 0프레임이면 성능 저하 없이 필요할 때만 렌더
• 효과: 51 → 13fps, 유휴 상태 오버헤드 0

③ 발표 중 학생 화면이 하얗게 꺼짐 — 임시책 대신 근본 해결

• 상황: 브라우저가 동시에 띄우는 3D 화면 수 한계(16개)를 발표자·학생 두 창이 나눠 쓰다 교구 9종×2창=18개로 초과 → 학생 화면 꺼짐
• 어떻게: 응답 대기시간을 늘려 버티는 임시책 대신, 여러 교구가 3D 화면 하나를 공유하도록 근본 수정(창당 9개 → 1개, 즉시 되돌릴 스위치 포함)
• 왜: 대기시간을 늘려도 16개 한계는 그대로라 결국 재발 — 한도 자체를 넘지 않아야 근본 해결
• 효과: 3D 화면 18개 → 2개, 백지·강제종료 해소

④ 3D 교구 소멸 버그 — 일괄 수정 대신 정밀 수정

• 상황: 한 버그를 잡으려 공통 로직에 일괄 수정(중복 제거)을 넣으려던 상황
• 어떻게: 일괄 수정을 폐기하고 문제가 확인된 특정 경로만 정밀 수정
• 왜: 배포 전 여러 각도로 검증하니 그 일괄 수정이 드래그·회전·되돌리기 등 190여 곳에서 교구를 전부 사라지게 함 — 한 증상 잡으려다 더 큰 붕괴를 부르면 비용 > 이득
• 효과: 광범위한 붕괴를 배포 전 차단하고 원래 증상만 안전하게 해결

⑤ 렌더 실패 — 위험한 근본 수정 대신 안전장치 먼저

• 상황: 특정 상황에서 3D 교구가 아무 오류 없이 화면에서 사라짐(그릴 대상이 비어 조용히 실패)
• 어떻게: 원인(중복 초기화)을 통째로 고치는 대신 "비어 버린 화면을 그 자리에서 되살리는" 작은 가드를 먼저 적용, 근본 수정은 별도 작업으로 분리
• 왜: 근본 수정은 초기화·되돌리기·슬라이드 전환 전반을 건드려 검증 범위가 넓고 위험 — 가드는 화면 복구 지점만 건드려 위험이 국소적
• 효과: 증상 즉시 해소 + 전체 테스트 무회귀 통과, 근본은 위험을 분리해 관리

⑥ 판단 근거 — 눈대중 대신 계측

• 상황: 원격 화면은 전송 지연 탓에 성능 체감이 실제와 왜곡됨
• 어떻게: 처리 시간·프레임 주기·3D 화면 사용량을 코드로 직접 계측하고 켜고 끄며 A/B로 비교
• 왜: 체감이 아니라 숫자로 봐야 원인·효과가 확정됨 — 처음 세운 원인 가설(누적 문제)이 계측으로 반증되며 진짜 원인(두 창의 GPU 공유)을 특정
• 효과: 특정 조작 시 화면 멈춤 16회 → 1회를 수치로 확인 후 배포

배경 · 문제

• 수강생이 제출한 과제(PR) 링크가 Re-open·리포지토리 포맷 변경·계정 ID 불일치 등으로 자주 바뀌어, LMS에서 제출 이력이 누락·휘발됐다. 단순 문자열 매칭으로는 정합성을 보장할 수 없어, GitHub API 기반 자동 수집 파이프라인과 실패에 강한 매칭 로직이 필요했다.

접근

• 4-Layer Fallback 매칭 알고리즘 (핵심) — 한 단계가 실패하면 다음 단계로 순차 복구하는 결함 허용 알고리즘을 직접 설계했다: ① URL 표준화(www 제거·트레일링 슬래시 통일) ② 실명과 GitHub ID가 다른 약 5% 케이스를 매핑 테이블로 강제 연결 ③ 과제명(Chapter) 키워드로 유저의 이벤트 히스토리를 역추적해 오기입 링크 복구 ④ Fork·원본 리포지토리의 PR 번호를 대조해 유실분 추적.
• 관측 가능성(Observability) — 매칭 로직이 복잡해질수록 실패 원인 파악이 어려워지는(블랙박스) 문제를, 매칭 실행마다 성공/실패 원인과 매칭 경로를 분석한 디버깅 리포트(matching-debug.md)를 자동 생성해 해결. 원인 파악을 수십 분 → 즉시로 단축.
• 게이미피케이션·인터랙티브 UI — 단순 점수제를 폐지하고 완료율과 베스트 프랙티스(BP)를 복합 평가하는 6단계 등급 시스템(ranking.utils.ts)으로 재설계. 프로필 카드에 CSS 3D Transform(perspective·rotateY) 기반 flip 애니메이션을 적용하고 will-change로 렌더링을 최적화, 커스텀 cubic-bezier 이징으로 모션을 다듬음. 등급에 따라 그라데이션·글래스모피즘·SVG 뱃지가 자동으로 바뀌는 동적 스타일링 시스템 구축.
• SSR Hydration Mismatch 해결 — 배포 서버(UTC)와 클라이언트(KST)의 타임존 차이로 날짜가 달라져 hydration 에러가 발생. 런타임 진입점에서 타임존을 서울로 고정하고, UTC 기준 포맷팅 + 클라이언트 전용 훅 초기값 통일로 서버/클라이언트 렌더 결과를 일치시킴.

결과

• 매칭 정확도 초기 실패율 40% → 95% 이상, 단순 URL 매칭으로 못 찾던 40% 이상의 누락 데이터 복구.
• 수동 개입이 필요한 케이스를 전체의 5% 미만으로 축소, 데이터 유실률 0% 달성.