meeting-stt-dev

Imported from geongyu09/meeting-stt (.claude/skills/meeting-stt-dev/SKILL.md). Install upstream with npx skills add geongyu09/meeting-stt --skill meeting-stt-dev. Copyright stays with the author.

meeting-stt 개발 방향성

클로바 노트/젠스파크 회의록과 유사한 기능을 서버 없이 데스크탑 앱 하나로 구현한다. 근거 문서는 plan.md(2026-08 기준 조사 자료). 이 스킬은 그 문서에서 결정된 사항과 작업 규칙만 추려낸 것이며, 배경 설명이 필요하면 plan.md의 해당 섹션을 읽는다.

0. 문서 우선 원칙 (SSOT)

이 스킬 문서(SKILL.md + references/*.md)가 프로젝트의 단일 진실 공급원(SSOT)이고, 코드는 그 부산물이다. 코드와 문서가 다르면 문서가 옳다고 보고 코드를 문서에 맞춘다. 문서를 고쳐야 할 이유가 생겼다면 코드보다 문서를 먼저 고친다.

• 기술 결정(1절)·파이프라인(2절)·로드맵(3절)·구조 규칙(4절)과 어긋나는 구현·리팩터링·라이브러리 추가·모델 변경은 문서를 먼저 수정하고 사용자에게 변경 내용을 알린 뒤 코드를 작성한다. "일단 코드 먼저, 문서는 나중에"는 금지.
• 작업 중 문서에 없는 결정을 내려야 하면(예: 새 IPC 채널 규약, 스키마 컬럼 추가, 상수 값 선택) 코드를 쓰기 전에 해당 references/*.md에 결정과 근거를 추가한다. 사소한 구현 세부는 코드에 두되, 다른 코드가 의존하게 되는 계약은 문서에 둔다.
• Phase 완료·진입 등 상태 변화는 3절의 "현재 위치"와 references/roadmap.md 체크리스트를 갱신해 기록한다.
• 문서에 오래된 내용(예: 마이그레이션 전 도구 이름)이 발견되면 즉시 문서를 고친다. 낡은 문서는 잘못된 SSOT다.

1. 확정된 기술 결정 (변경 시 사용자 확인 필수)

2. 처리 파이프라인 (불변)

[마이크 녹음 (AudioWorklet, 16kHz mono)]
  → [WAV 확정]
  → [음량 정규화 (RMS 게인, 순수 TS)]
  → [VAD 무음 제거]
  → [whisper-cli → JSON 세그먼트(+단어 타임스탬프)]   ┐ 코어 수에 따라
  → [sherpa-onnx diarization → 화자 구간]              ┘ 병렬/순차 분기
  → [병합: 군소 화자 흡수 → 타임스탬프 겹침 최대 화자 배정 → 동일 화자 연속 발화 문단화]
  → [SQLite INSERT, status='done']
  → [(설정) 원본 WAV 삭제]
  → [홈 리스트 / 디테일 페이지: 조회·인라인 수정·화자 이름 지정·복사]

무거운 작업(spawn, 파일 IO, DB)은 전부 main 프로세스(또는 utilityProcess) 에서 수행하고, renderer는 IPC로 요청·진행률 수신만 한다. 렌더러 내 추론(transformers.js/WebGPU)은 하지 않는다.

3. 단계별 로드맵 — 순서를 건너뛰지 않는다

상세 체크리스트(완료 기준 포함)는 references/roadmap.md.

1. Phase 1 파이프라인 검증 (스크립트) — 앱 UI를 만들기 전에 apps/desktop/scripts/에서 tsx로 whisper-cli → sherpa-onnx → 병합을 실제 한국어 회의 WAV로 돌려 품질·속도를 확인하고 모델 크기/양자화/cluster_threshold를 튜닝한다. 여기서 만든 병합 로직은 이후 src/main/pipeline/으로 그대로 옮긴다.
2. Phase 2 앱 골격 — 녹음 → WAV → 파이프라인 → SQLite → 홈/디테일 관통.
3. Phase 3 편집·복사·화자 관리 — 인라인 편집, 화자 이름, 전체/부분 복사, 진행률.
4. Phase 4 배포 품질 — 온보딩 모델 다운로드, 코드 사이닝/notarization, electron-updater, 저사양 폴백.
5. Phase 5 확장 — 로컬 LLM 요약(llama.cpp), 시스템 오디오 캡처.

현재 위치: Phase 1~4 종료, Phase 5-1(로컬 요약) 종료 (2026-09-18). Phase 2·3·4와 5-1의 완료 기준이 2026-09-18 사용자 수동 확인을 모두 통과했다. 진행 중인 작업은 Phase 5-3(녹음 위젯 패널) 이다 — 사용자 요청으로 5-2보다 먼저 착수했고, 5-1처럼 순서를 건너뛴 예외다. 그 뒤 작업 후보는 Phase 5-2(시스템 오디오 캡처) 와 미착수로 남은 배포·품질 항목(다음 릴리스의 업데이트용 zip, 회의별 용어 사전, 저사양 요약 폴백 모델)이다. Phase 1은 합성 픽스처에 이어 실제 한국어 발표·Q&A 녹음(71분, 음성 메모 m4a → 16kHz WAV) 으로 재측정까지 마쳤고, 그 결과 음량 정규화 단계 추가·cluster-threshold 0.8·군소 화자 흡수를 확정했다(docs/phase1-results.md). Phase 2의 run.ts가 이 세 가지를 반영했고, 녹음 → 파이프라인 → SQLite → 홈/디테일 관통이 붙었다. Phase 3(편집·복사·화자 관리·설정)과 Phase 4(온보딩 모델 다운로드, 서명·업데이터 설정, CI, 단일 인스턴스)도 코드가 붙었고, 세 Phase의 완료 기준(실제 녹음·실제 회의록·빈 userData로 온보딩)을 모두 통과했다. Phase 5-1(로컬 LLM 요약)은 사용자 지시로 Phase 3·4보다 먼저 착수했다 — 로드맵 순서를 건너뛴 예외이므로 여기 기록해 둔다. 5-1에 남은 항목(회의별 용어 사전, 저사양 폴백 모델)은 완료 기준이 아니라 후속 과제다 (references/roadmap.md). Phase 4 배포 결정(모델 레지스트리·온보딩·바이너리·서명·업데이트·CI)은 references/distribution.md에 있다. Phase 5-2(시스템 오디오 캡처)는 아직 시작하지 않았다. Phase 5-3(녹음 위젯 패널) 은 2026-09-18에 문서를 먼저 확정했다. 녹음 제어가 메인 창 밖으로 나가면서 오디오 그래프 소유자·참석자 수의 단일 출처·창 참조 관리가 함께 바뀌므로, 체크리스트의 "계약 변경"을 먼저 끝내고 구현한다. Phase 5-4(LLM 회의록 교정) 는 2026-09-24 사용자 요청으로 검증 단계만 마쳤다 — 발화를 LLM이 다시 쓰는 방식은 폐기하고, 용어 사전 + 발음 유사도 후보 + LLM O/X 판정으로 수정 제안을 만드는 방식을 채택했다 (docs/phase5-refine-results.md). 앱 통합은 사용자 확인 뒤 착수한다. 작업 시작 시 git log/디렉터리 상태로 현재 Phase를 먼저 재확인한다.

4. 코드 구조와 규칙

워크스페이스 경계·패키지 형태·스크립트 규약은 references/monorepo.md, 데스크탑 앱 내부의 디렉터리 배치·IPC 규약·프로세스 경계는 references/architecture.md, 배포(모델 다운로드·바이너리·서명·업데이트·CI)는 references/distribution.md를 따른다. 코드 컨벤션·renderer React 레이어(추상화 레벨·콜로케이션·세그먼트·훅 위치)·IPC/API 작성·테스트 배치 규칙은 .claude/rules/*.md에 있으며, 해당 경로의 파일을 만들거나 수정할 때 자동으로 적용된다. 핵심 규칙:

• 워크스페이스 경계: 두 앱이 같은 값·같은 알고리즘을 써야 하면 packages/core(순수 로직)나 packages/models(모델 카탈로그)에 올리고, 런타임 API(fs, electron, AudioContext, 워커, spawn)를 만지는 코드는 앱에 남긴다. 아래 src/… 경로는 모두 apps/desktop/ 기준이다 (references/monorepo.md).
• 프로세스 경계: src/main(Node) / src/preload(contextBridge) / src/renderer(브라우저) / src/shared(순수 TS 타입·유틸, 런타임 의존 없음). 병합 알고리즘·포맷터 같은 순수 로직은 src/shared 또는 src/main/pipeline에 두고 pnpm test(vitest)로 단위 테스트한다.
• IPC: 채널 이름과 payload 타입은 src/shared/ipc.ts에 단일 정의. 요청-응답은 ipcMain.handle/ipcRenderer.invoke, 진행률 등 push는 webContents.send. preload는 window.api에 타입이 붙은 함수만 노출하고 ipcRenderer를 직접 노출하지 않는다.
• 외부 바이너리: resources/bin/<platform>-<arch>/ 에 두고 asarUnpack 대상으로 유지. 실행 전 존재·실행권한 확인, stdout JSON 파싱 실패/비정상 종료는 status='error'로 기록하고 사용자에게 안내한다.
• 데이터: 화자 이름은 utterances에 쓰지 않고 speakers(meeting_id, label) → display_name 매핑으로 관리한다(한 번 바꾸면 전체 반영). 모든 시간 값은 초(sec, REAL), 생성 시각은 epoch ms.
• 한국어 우선: 기본 언어 ko, UI 문구·문서·커밋 메시지는 한국어. 코드 식별자는 영어.
• pnpm 주의: pnpm 10은 의존성의 install/postinstall 스크립트를 기본 차단한다. 네이티브 애드온·바이너리 다운로드 패키지(electron, esbuild, electron-winstaller, better-sqlite3)는 워크스페이스 루트 package.json의 pnpm.onlyBuiltDependencies에 등록해야 한다 (앱 package.json에 적으면 무시된다). 새 네이티브 의존성을 추가하면 이 목록도 갱신한다. .npmrc의 node-linker=hoisted는 electron-builder 패키징을 위한 설정이므로 지우지 않는다. package.json scripts 내부 호출은 pnpm run <script>로 통일한다.
• 범위 절제: plan.md에 없는 기능(클라우드 동기화, 실시간 스트리밍 STT, 계정 등)은 제안만 하고 구현하지 않는다.

5. 알려진 함정 (구현 전 확인)

전체 목록은 references/pitfalls.md. 자주 걸리는 것:

• Whisper는 무음에서 환각 텍스트를 만든다 → VAD 없이 추론 금지.
• 음량이 작은 녹음(원거리 마이크)에서는 Whisper가 수십 초 구간을 한두 단어로 뭉갠다 → STT 전에 RMS 정규화 필수.
• 임계값 군집(cluster-threshold)은 긴 녹음에서 화자가 무한정 늘어나고 같은 사람도 여러 클러스터로 갈라진다 → 참석자 수를 받아 num-clusters로 돌리는 것이 기본. 임계값 경로는 폴백이며 군소 화자 흡수로도 못 막는다.
• Whisper 세그먼트 안에서 화자가 바뀔 수 있다 → 단어 단위 타임스탬프로 배정 후 재문장화.
• 장시간 녹음 PCM을 메모리에 전부 들고 있지 않는다 → 청크 단위 디스크 append.
• 저사양 CPU에서 STT+화자분리 병렬 실행은 오히려 느리다 → os.cpus().length 기준 분기.
• 바이너리에 코어 수만큼 스레드를 주면 효율 코어까지 잡아 느려지고 팬만 돈다 → 성능 코어 수 기준으로, GPU가 일하는 whisper·llama는 그보다 더 낮게.
• 성능 코어 수로 돌려도 긴 회의의 화자 분리는 몇 분간 코어를 전부 쓴다 → 소음이 싫은 사용자는 '조용히 처리' 설정으로 속도를 내준다. GPU를 쓴다고 발열이 없는 게 아니다(CPU·GPU가 방열판 하나를 공유).
• macOS 마이크 권한: NSMicrophoneUsageDescription(electron-builder.yml, 한국어 문구로 교체) + systemPreferences.askForMediaAccess('microphone').
• 동봉 바이너리도 macOS notarization 시 함께 서명해야 한다.

6. 작업 시작 시 절차

1. 이 스킬과 필요한 references/*.md를 읽는다. 결정 사항과 어긋나는 요청이면 plan.md 근거를 들어 한 번 확인하고, 사용자가 재확인하면 그대로 진행한다.
2. 현재 Phase와 완료 기준을 references/roadmap.md에서 확인하고, 해당 Phase 항목만 구현한다.
3. 순수 로직은 pnpm test로 검증, 앱 동작은 pnpm dev로 확인한 뒤 결과를 있는 그대로 보고한다.
4. 새로운 기술 결정(모델 변경, 라이브러리 추가, 규약 변경 등)이 생기면 코드를 쓰기 전에 이 SKILL.md의 결정 표나 해당 references/*.md를 먼저 갱신한다(0절). 문서 갱신 → 사용자 확인 → 코드 순서를 지킨다.