LLM·임베딩 모델명 문서 드리프트 정정

[i3months]

배경 — 디자인·TTS·AI 모델 축 감사

이번 라운드에서 확인한 것들. 코드는 전부 깨끗했다:

검사	결과
하드코딩 hex 색상	DesignSystem 스와치 문서 외 0건
sage-* 오용 (항상-어두운-표면 전용 규약)	4곳 모두 정당 (웹캠 오버레이·GitHub 버튼·면접관 아바타·푸터)
text-primary 오용 (고정 흰 표면 전용)	1곳뿐이고 bg-white 위 — 규약대로
존재하지 않는 색 토큰 (#189 의 조용한 no-op 함정)	사용된 스케일 토큰 19종 전수 대조 — 0건
모델 배치 vs 설계 (Pro=품질 / Flash=저지연)	체인 9개 전부 일치 — Pro: 질문풀·분석·PDF vision·패널·합성·직무적합 / Flash: 꼬리질문·첫인상·인성·코칭
TTS 폴백 체인	gateway→gemini→openai→mock, 각 폴백마다 경고 로그
TTS 합성 실패	FAILED 콜백 발행 → 질문은 텍스트로 정상 진행 (오디오는 enhancement)
TTS 산출 포맷 vs Core 세그먼트 프록시 화이트리스트	wav/mp3/ogg/m4a — 전 공급자 출력 커버
TTS 재생 훅	로드 지연·자동재생 차단 폴백 처리됨

남은 결함은 문서 드리프트 하나다 — #220(PII 마스킹 서술)과 같은 부류.

문제

같은 설정이 네 곳에서 세 가지 값으로 적혀 있다.

위치	Pro	Flash
settings.py (실제) · .env.example · environment.md 카탈로그	gemini-3.1-pro-preview	gemini-3.1-flash-lite
ai/CLAUDE.md §6.2 표	(일치)	gemini-3.1-flash-lite-preview "후보"
ai/CLAUDE.md §9 예시 · environment.md 코드 예시	gemini-3.1-pro	gemini-3.1-flash

§9 예시는 임베딩도 낡았다: text-embedding-004 / 768차원. 실제는 gemini-embedding-001 / 1536차원이고 pgvector 컬럼이 vector(1536) 이라, 예시를 그대로 따라 하면 차원 불일치로 upsert 가 깨진다. 단순 이름 차이가 아니라 따라 하면 사고가 나는 예시였다.

수정

전부 실제 기본값으로 정렬. 추가로 §6.2 에 운영 주의를 명시했다:

Pro 기본값이 -preview 별칭이다. 게이트웨이가 preview 별칭을 은퇴시키면 Pro 를 쓰는 경로(질문 풀·분석·피드백)가 한꺼번에 죽는다. 복구는 .env 의 LLM_PRO_MODEL 한 줄 — 재배포·코드 수정 불필요.

장애 때 "어디를 고치면 되는지"가 문서에 있어야 새벽에 코드를 뒤지지 않는다.