코칭 엔진 기술 아키텍처 해부도
전 모듈을 코드 단위로 시각화

엔진은 토대 위 3단으로 짓습니다 — ① 결정론이 2축 음식 네트워크·영양 신호로 후보(시나리오·추천 풀)를 깔고, ② 🧠 두뇌(Sonnet, ?brain 카나리아)가 시나리오를 고르고 음식 추천을 검수하고, ③ ✍️ 손(Haiku)이 작문합니다. "계획·판단은 코드와 두뇌가, 글만 손이" 원칙 위에 섭니다.

엔진은 스스로 깨지 않습니다. Vercel Cron이 매일 새벽 깨우면, Supabase에서 식사 기록을 읽고, 필요할 때만 Claude에게 글을 맡긴 뒤, 결과를 다시 Supabase에 넣어 둡니다. 부모는 아침에 이미 만들어진 편지를 읽기만 합니다.

★ 핵심 설계 = 비동기 사전 생성. 부모가 앱을 여는 순간 LLM을 호출하지 않습니다 — 새벽에 미리 만들어 둔 편지를 read만 합니다(온디맨드 API는 폴백). 그래서 아침 화면은 즉시 뜨고, LLM 비용·지연은 새벽 배치에 격리됩니다.

위에서 아래로: 깨어남(진입점) → 지휘(오케스트레이션) → 전략(주간)·전술(일간) → 🧠 두뇌 선택·검수 → 사실·추천 → 데이터·영양 토대 → 검증 하네스 → 지원. 칩 하나가 모듈 하나입니다(파일명 병기).

엔진은 v2(LLM 작문) 기반 위에 LLM 두뇌를 얹은 2파이프 구조입니다. ① 결정론이 토대(2축 네트워크·영양 신호)로 '오늘 쓸 수 있는 것'(시나리오·추천 식재료 풀)을 후보로 깔고 → ② 🧠 두뇌(Sonnet)가 그중 하나를 고르고 음식 추천을 켤지 끌지 검수(편지는 안 씀)하고 → ③ ✍️ 손(Haiku)이 영양 평가·어제 식단·음식 추천을 엮어 작문합니다. 두뇌가 꺼지거나(?brain 미설정·실패) 후보가 없으면 결정론 산출로 폴백 — 발행은 언제나 보장됩니다.

★ 왜 두뇌인가 — 결정론만으로는 "오늘 진짜 문제가 음식이 아니라 환경인데도 음식 추천을 우겨넣는" 판단 오류를 못 막습니다. 그래서 두뇌가 useFood로 음식 추천 본문을 통째로 켜거나 끄고, 환경이 핵심인 날엔 음식을 뺍니다. 두뇌는 고르고 검수만, 글은 손이 — 생성자(손)와 판단자(두뇌)를 분리해, 비싼 머리(Sonnet)는 하루 1콜·주 1콜만 쓰고 작문은 싼 손(Haiku)이 맡습니다. 상태기계·영양·사실·간식·추천·괴식 매트릭스·검증 하네스는 전부 결정론 순수 함수(LLM 0콜)라 테스트·리플레이가 쉽습니다. (과거 v3 블록 조립·하이브리드 Letter B 비교는 플래그 뒤 도먼트로만 잔존 — 전 자녀 라이브 경로는 위 2파이프.)

새벽 코칭 크론이 한 번 깨어나 한 자녀의 편지·질문을 짓기까지. 레인(누가)·종류(무엇을)·갈래(공통/결정론/두뇌·손)로 색을 입혔습니다. 7개 국면으로 묶었습니다.

엔진은 "오늘 어떤 각도로 코칭할지"를 확률이 아니라 상태 전이·트리거로 결정합니다. ⓐ 시나리오 선택(현재 라이브·selectScenario+두뇌)과 ⓒ 한 주의 가르치는 결(주간 아크)은 라이브, ⓑ 유닛 생애주기(decideDailyV3)는 v3 도먼트입니다.

ⓐ 일간 전개 결정기 — decideDailyV3 + advanceProgress

전이 조건(코드 그대로): 전진=합격 연속이 holdWeeks 충족(step+1) · 심화=최근 신호 있고 진전 중 · 피벗=정체(무신호 6일+ & 충분히 코칭) 또는 절뚝거림(약신호로 정체 판정엔 안 걸리나 사다리 0진전)이고 주당 피벗 캡(1회) 미소진 · 유지=최종단 후 유지 주, 또는 정체+피벗 불가 → 강등 · maintain 3연속이면 deepen으로 강제 재개(위안만 반복 차단). 우선순위 1순위는 재발 신규(mastered→relapsed) 유닛 재개.

교육용 블록 언어(Scratch)처럼, 엔진의 두 핵심 로직을 색깔 블록으로 풀었습니다. 주황=제어(만약~), 파랑=동작, 초록=판정, 보라=나만의 블록(모듈), 노랑=시작(언제), 빨강=저장.

모든 것의 원천은 부모가 찍은 끼니 기록 하나. 그것이 여러 처리기를 거쳐 편지·질문·진도·요약 네 개의 저장소로 흩어집니다. 사각=데이터 저장소, 둥근=처리기.

★ 방향성 — 진단·사실은 항상 왼쪽(데이터)→오른쪽(편지)으로만 흐릅니다. 편지(LLM 산출)가 사실을 거꾸로 만들지 못하게, 모든 숫자·라벨은 처리기(코드)가 확정하고 작문기는 인용만 합니다. 이 단방향성이 환각 차단의 뼈대입니다.

children가 허브이고 모든 코칭 테이블이 child_id로 매답니다. 부모는 coach_letters·daily_questions만 읽고, 엔진 내부 상태(weekly_plans·curriculum_progress)는 RLS로 비노출(서버만 접근)입니다.

유닛 하나가 "편식 해결의 한 과목"입니다. 각 유닛은 레버(어떤 지렛대)·최소 주차·2단 사다리(과제)·졸업 기준·관측 질문을 코드로 선언합니다(선언이 곧 명세). 색=레버.

★ 코어 8 → 확장 4 — pressure-off → hunger-rhythm → table-stage → exposure-savings → fullness-respect → parent-model → no-bargain → table-talk가 기초 순서(W1~W3 가능), 나머지 4종(감각·다리·자율성·연계)은 신호 발동 시 선택됩니다. 주간 사령부가 신호 강도(trigger 점수)로 후보를 올리고, 포트폴리오 2~3개로 묶어 한 주의 goals를 정합니다. 이 12 유닛은 학부모용 실라버스(coaching-syllabus.html)와 1:1로 정합 — 엔진이 실제로 가르치는 것만 적었습니다.

현재 라이브 작문은 ✍️ 손(composeLetter, Haiku)이 LLM으로 직접 쓰고, 결정론 금지어 → 어휘 유사도 → 의미 검증자(별도 LLM 1콜) 3종 가드로 사후 검열·재생성합니다(§4·§11 방어 가드). "글맛은 LLM, 안전은 코드 가드" 원칙입니다.

★ 폐기된 접근 — 한때 "글을 쓰지 않고 검수된 블록을 집합 차감으로 조립(LLM 0콜)"하는 v3 경로를 실험했습니다(반복을 구조적으로 차단하려는 의도). 하지만 조립식은 따뜻함·다양성·구체성을 잃어(아린 A/B 실증에서 LLM 작문에 완패) 폐기했습니다. 관련 코드(assembleLetter·letterBlocks·decideDailyV3)는 카나리아 플래그 뒤 도먼트로만 남아 있고 전 자녀 라이브에선 가동되지 않습니다. 다양성은 조립이 아니라 두뇌의 시나리오 회전 + 추천 풀 일일 회전 + 유사도 가드로 확보합니다.

새벽 코칭 크론이 모든 것의 지휘자입니다. 아래로 갈수록 순수해집니다 — 잎(leaf) 모듈(영양·그래프·날짜)은 DB·LLM·시계를 모르는 순수 함수라 테스트·리플레이가 쉽습니다.

★ 의존 방향이 단방향(상위→하위)이고 잎이 순수해서, 전체 파이프라인(결정론 후보 → 두뇌 선택·검수 → 손 작문)을 실제 DB·LLM 없이 인메모리로 14일 돌려볼 수 있습니다. "라이브에 내보내기 전에 미래를 시뮬레이션한다"가 가능한 이유.

가드 하나하나가 실제 사고의 흉터입니다. 5겹 방어로 묶었습니다 — 결정론(정규식) → 의미(LLM 검증자) → 구조(집합 차감) → 운영(시간·영속) → 안전(아동 보호). 프롬프트로 호소해선 못 막은 것을 코드 가드 + 리플레이로 잡았습니다.

⏱ 사고 연대기 — 가드가 자란 자리

엔진의 강건함은 설계가 아니라 사고 → 진단 → 가드 → 리플레이 박제의 반복에서 왔습니다.

모듈별 규모와 LLM 모델 사용처. 결정론 토대(LLM 0콜) 위에서 손(Haiku)·두뇌·주간 닻(Sonnet)만 모델을 씁니다.

모듈 규모(LOC) — 상위

LLM 모델 사용 지도 — "비싼 머리는 두 곳만"

이 문서는 2026-06-14 코드 기준 실재하는 것만 그렸습니다. 추측·로드맵은 배제했습니다.

★ 관련 정본 문서 — 무엇을·언제(시나리오·간식) · 어떻게 정하고 만드나(plan 엔진) · 일·주·월 케이던스(주간 케이던스) · 학부모용(실라버스) · 피치용(엔진 다이어그램). 이 문서는 그 모두를 코드 단위로 합친 기술 해부도입니다.

추천의 질문은 하나입니다: "이 음식·식재료가 정말 같이 먹는 조합인가?" 엔진은 이걸 의견이 아니라 실제 식단 데이터의 공통출현으로 판정합니다. 단일 카운트는 흔한 식재료(밥·달걀)를 우연히 '강함'으로 둔갑시키므로, 우리는 서로 다른 두 데이터에서 각자 lift(우연 보정)로 등급화하고, 둘 다 받쳐줄 때만 추천에 씁니다. 그래서 떡+달걀처럼 LLM은 "괜찮다" 했지만 두 축 모두 약신호인 조합이 자동으로 차단됩니다.

두 증거축 — 무엇이 다른가

★ 두 축은 다른 것을 본다 — 레시피축은 '한 그릇 안에 섞이는가', 식판축은 '같은 상에 같이 오르는가'. 둘 다 lift로 우연을 빼지만, 식판축은 메뉴명에 안 적히는 숨은 채소(잡채·볶음 속 당근)와 '같이 차려짐'이라는 부모 직관을 보강합니다.

세 번째 관계, bridge(사촌). 대체 사촌(명태↔대구, 고구마↔단호박)은 같은 레시피·식판에 거의 함께 안 나오므로 동시출현으로는 안 잡힙니다. 그래서 맛·식감·색이 닮은 고신뢰 수기 시드 175쌍(전부 verified:true·동일 식품군 근접)으로 따로 둡니다. 푸드체이닝 'chain' 추천(잘 먹는 것 → 닮은 새 음식)은 verifiedCousinsOf로 이것만 씁니다.

병합 규칙 — upgrade-only(신뢰는 올리기만)

식판축을 레시피축 그래프에 합칠 때 강등은 금지합니다. 메뉴명에 안 적힌 채소 누락이 '안 어울림'을 뜻하진 않기 때문 — 빠진 근거는 약점 증거가 아닙니다. 그래서 식판 strong 쌍은 ① 기존 엣지면 등급을 승급만(37쌍), ② 그래프에 없으면 새 pair 엣지로 추가(106쌍, src:'tray'·basis="같은 끼니 식단 N회").

추천 게이트 — 조합이 통과하는 경로 — comboMatrix.scoreCombo

최종적으로 '잘 먹는 음식 + 결핍 식재료' 조합을 띄울 때, 4단 폴백을 위에서부터 따집니다. 핵심은 borderline LLM 점수(2)는 실제 레시피 동시출현(cells)이 ≥8일 때만 인정한다는 게이트 — 떡+달걀(score 2·cells 4)을 여기서 한 번 더 거릅니다.

통과 임계는 기본 2(isComboOk) — score 1(미역국+당근·떡+달걀)은 막고 2·3만 통과. 약신호 차단 임계 PAIR_MIN_STRENGTH=2는 그래프(strongPairsOf)와 매트릭스(CELLS_MIN=8) 양쪽에서 통일됩니다 — 모든 소비자(coachRecos·coachMaterials·comboMatrix·comboGuard)가 같은 헬퍼로 일원화.

사례 추적 — 왜 '떡+달걀'이 차단되나(두 축 모두 약신호)

★ 핵심 — LLM 한 사람의 "괜찮을 것 같다"는 판단(score 2)이 아니라 실제로 같이 먹는 데이터가 최종 결정권을 갖습니다. 떡+달걀은 레시피에서도(lift 0.72) 식판에서도(strong 미달) 약신호라, 두 축의 교차 검증으로 자동 탈락합니다.

★ 설계 한 줄 — 추천은 "이 음식 좋아요"라는 의견이 아니라, 두 데이터(레시피·식판)에서 우연을 뺀 뒤에도 함께 등장하는가라는 증거 질문입니다. 등급화·upgrade-only 병합·교차 게이트·작문 가드가 한 줄로 꿰여, 부모가 보는 문장 속 곁들임은 모두 실제 식단으로 검증된 것만 남습니다.