개발 기록 2026-10-28 오후: CLAUDE.md와 Vitest 검수 규칙, 메인 목록 페이지 나누기, MSA 대화 음성·릴 영상

오후 17시 13분부터 17시 39분까지 짧은 시간 동안 두 갈래로 작업했다. 하나는 SvelteKit 블로그(my-blog)를 다듬는 일이고, 다른 하나는 ElevenLabs로 대화 음성을 만들어 인스타그램 릴 영상까지 이어 본 실험이다.

다른 도구에서 만든 스킬을 Claude Code에서 쓸 수 있는지

Antigravity 쪽에 만들어 둔 문서 스킬을 Claude Code에서도 쓸 수 있는지부터 물었다. 답은 "형식은 같다"였다. 둘 다 SKILL.md 형식을 쓰기 때문에 폴더를 ~/.claude/skills/에 연결하면 바로 쓸 수 있다.

다만 홈 폴더를 뒤져 보니 말한 문서 스킬이 어떤 것인지 특정하지 못했다.

Antigravity가 실제로 읽는 폴더에는 Cloudflare 관련 스킬 13개만 있었다.
~/.agent/skills/skills에는 공개 모음집으로 보이는 스킬 648개가 있었다. 그중 docx-official, pptx-official 같은 문서 스킬은 Claude 쪽에 이미 document-skills:docx, pptx, xlsx, pdf로 같은 기능이 있다.
한글 문서 스킬(hwpx-master, md-to-hwpx 등)도 목록에 있었는데, 이후 처리 결과는 기록에 없다.

CLAUDE.md로 토큰 낭비 줄이기

블로그 폴더에서 Claude Code를 열 때마다 코드를 처음부터 다시 훑느라 토큰을 쓰는 게 아까워서 /init으로 CLAUDE.md를 만들었다. 이 파일은 폴더를 열면 자동으로 읽힌다.

들어간 내용은 다음과 같다.

명령어: dev, check, build, db:push, 그리고 배포용 vercel deploy --prod --yes.
읽지 말 것 목록: static/reports/(46MB), reports.json, local.db, .svelte-kit/, REVIEW.md, 루트 SKILL.md. 토큰을 아끼는 데 가장 효과가 큰 부분이다.
구조와 규칙:
- DB는 로컬 SQLite와 Turso를 자동으로 전환한다. 컬럼을 추가하면 schema.ts와 db.ts를 함께 고쳐야 한다.
- 관리자 기능마다 isAdmin 확인을 직접 넣어야 한다.
- 공개 페이지는 CDN에 1시간 캐시된다.

파일 하나만 봐서는 알 수 없는 규칙 위주로 적는 게 핵심이다.

Vitest로 검수(checker) 규칙 만들기

코드를 고칠 때마다 실패를 줄이려고 테스트 프레임워크를 붙이고, 그게 통과해야 검수가 끝난 것으로 치는 규칙을 넣었다. 처음 만들 당시에는 테스트 러너와 린터가 없어서 npm run check가 유일한 검증 수단이었다.

테스트 도구: Vitest 3.2.7. 설정은 vite.config.ts 안에 넣어서 별도 설정 파일이 없다.
명령어: package.json에 두 개를 추가했다.
- test: 테스트만 돌린다.
- verify: 타입 검사 → 테스트 → 빌드를 순서대로 돌리고, 하나라도 실패하면 바로 멈춘다.
첫 테스트 14개 (3개 파일):
- posts.test.ts: 예약 발행 글의 공개 여부, KST 변환
- markdown.test.ts: <script>와 javascript: 링크 차단, 목차 생성, 읽기 시간 계산
- auth.test.ts: 한글 슬러그 생성, 잘못된 관리자 토큰 거부

npm run verify

처음 돌렸을 때 결과는 다음과 같았다. 종료 코드 0, 타입 에러 0개, 테스트 14개 모두 통과, 빌드 성공. 이 규칙은 CLAUDE.md에도 적어 두었다.

메인 목록 페이지 나누기 (PC는 번호, 모바일은 더보기)

메인 화면 글 목록이 페이지 나누기 없이 한 번에 다 나와서 너무 길었다. 한 페이지에 10개씩 보이도록 나누고, 화면 크기에 따라 다르게 동작하게 했다.

PC (폭 760px 초과): 목록 아래에 이전 1 2 3 다음이 나오고, 지금 보는 페이지 번호를 진하게 표시한다. 주소는 /, /?page=2, /?page=3 식이다.
모바일 (760px 이하): 더보기 10 / 23 버튼이 나온다. 누르면 스크롤 위치는 그대로 두고 다음 10개를 아래에 붙인다. 주소가 /?from=1&page=2처럼 바뀌어서, 새로고침하거나 뒤로 가도 보던 글이 남아 있다.
잘못된 주소: ?page=abc, ?page=99처럼 없는 페이지가 들어오면 가장 가까운 정상 페이지를 보여 준다.

page/from 주소 규칙 하나로 PC 번호 이동과 모바일 더보기를 함께 처리했다. 로컬 DB(글 23개)에서 verify를 통과했고, 페이지도 의도대로 나왔다.

배포

배포 후 운영 주소에서 직접 확인했다.

/: 글 10개, 페이지 번호 1, 2, 3, 더보기 링크 있음
?page=2: 2페이지 글 10개
?from=1&page=2: 1·2페이지 글 20개가 이어서 나옴

처음 배포 명령은 "status": "error"를 돌려줬다. 원인은 확인하지 못했고, 바로 다시 실행하니 READY 상태로 올라갔다. 위 확인 결과는 두 번째 배포 기준이다.

ElevenLabs로 MSA 대화 음성 만들기

Claude Code에서 ElevenLabs를 쓸 수 있는지 물었다. 전용 MCP는 없지만 스킬을 거쳐 API를 직접 부르는 방식으로 쓸 수 있었다.

환경변수에 API 키가 이미 설정되어 있었다.
media-use 스킬의 audio/tts가 ElevenLabs TTS를 기본으로 쓴다. 모델은 eleven_multilingual_v2라 한국어도 된다.
hyperframes, remotion-markup, video-editing 스킬에서 ElevenLabs 내레이션을 영상에 붙일 수 있다.

그래서 "마이크로서비스 아키텍처"를 주제로 대화 스크립트를 쓰고 음성 파일까지 만들어 보았다. 진행자 지수와 아키텍트 민호가 MSA 정의, 모놀리식과의 차이, 장단점, 도입하기 좋은 조직을 이야기하는 2인 대화로, 길이는 약 1분 59초다.

script.md: 대본
gen.py: 대사 한 줄마다 ElevenLabs(eleven_multilingual_v2)를 호출하고, 0.4초 쉰 뒤 ffmpeg로 이어 붙인다.
msa-dialogue.mp3: 결과 음성

음성으로 인스타그램 릴 만들기

만든 음성을 바탕으로 /ig-reel을 구성했다. 이미지는 Codex CLI로 만들고, 음성과 장면 연결은 HyperFrames와 Remotion 스킬을 쓰게 했다.

결과는 45초짜리 세로 릴(1080x1920)이다. HyperFrames check를 통과했고, 렌더한 영상에서 프레임을 뽑아 보니 장면 전환 때 생기던 검은 프레임도 없어졌다.

첫 3초 훅은 후보를 점수로 비교해서 골랐다.

85.6  STRONG  "MSA부터 깔지 마. 왜 쪼개는지부터 답해."
48.6  WEAK    "작은 팀이면 MSA 필요 없어."
45.0  WEAK    "쪼갤수록 빨라진다? 아니, 느려져."

첫 장면(0~~3.3초)은 모놀리스가 깨지는 이미지에 "MSA부터 깔지 마" 카드를 얹었고, 다음 장면(3.3~~12.9초)은 모든 기능이 한 덩어리로 들어 있는 거대한 빌딩 이미지다.

블로그 글 올리기와 자동화 스케줄러

작업이 끝난 뒤 두 편을 블로그에 올렸다.

오늘 작업 정리: CLAUDE.md, Vitest 검수 규칙, 메인 목록 페이지 나누기
오늘 보낸 프롬프트를 오전·오후로 나눠 시간순으로 정리한 글

이 두 가지를 매번 손으로 시키는 대신, 오전·오후 작업이 끝나면 정리 글과 프롬프트 기록을 자동으로 올리는 스케줄러를 만들어 달라고 했다. 이번 오후 구간으로 파이프라인 전체를 한 번 시험하는 단계(비공개 초안으로 저장)까지 진행했다.

남은 것

테스트 도입과 페이지 나누기 변경을 아직 커밋하지 않았다.
운영 사이트를 브라우저로 PC·모바일 화면에서 직접 열어 보지는 않았다.
첫 배포가 "status": "error"를 낸 원인은 확인하지 못했다.
Antigravity 쪽 한글 문서 스킬을 Claude Code에 연결했는지는 기록에 없다.
자동화 스케줄러 시험 실행 결과와 등록 여부는 아직 기록에 없다.