vitamin-analyzer

# Vitamin Analyzer — 보충제 분석 Skill > **"지금 먹는 비타민, 정말 나한테 맞는 걸까?"** > 부족한 건 없는지, 뭘 중복으로 먹고 있지는 않은지, 상한선을 넘긴 성분은 없는지 — 내 비타민 포트폴리오를 근거 기반으로 점검하고 최적의 조합을 찾아가는 **탐색 여정**을 돕는 Claude Skill. 프로필(선택)과 복용 제품(텍스트/라벨 사진/제품명)을 받아 UL 초과·RDA 미달·중복·상호작용을 평가하고, **국내·해외에서 구할 수 있는 대체 제품**을 가격·근거와 함께 제시합니다. 식약처 건강기능식품 Open API(선택) 연동 시 국내 제품은 제품명만으로 정부 공식 DB에서 정확히 식별합니다. --- ## 1. When to use this skill 본 스킬은 다음 중 하나 이상의 입력이 감지될 때 활성화됩니다: - 보충제 제품명 (한/영) — 예: "센트룸 실버 여성용", "NutriCalm LiverRelax" - 성분 리스트 텍스트 — 예: "비타민 D 1000IU, 칼슘 500mg, 마그네슘 200mg" - **성분표 사진 (Supplement Facts 패널)** — 이미지 업로드 - **복수 제품 조합** — 2개 이상 제품을 한 번에 분석 (스택 최적화) - 선택적 프로필 — 성별/나이/증상/임신·수유/복용 약물 **활성화하지 않는 경우**: - 영유아(<12세) 또는 반려동물 대상 → §6 거부 프로토콜 - 처방약 복용량 조정 요청 → "의사·약사 상담 권고"로 응답 - 식품 영양 분석 (보충제 외) → 본 스킬 범위 밖 --- ## 2. 사용 프로필 수집 (PRD — 선택 입력) 스킬 시작 시 사용자에게 **선택적으로** 프로필을 질문합니다. **모든 필드는 의무가 아닙니다.** ### 2-1. 질문 템플릿 (한국어) ``` 보충제 분석을 시작하겠습니다. 더 정확한 분석을 위해 프로필을 입력해 주세요. (모두 선택입니다 — 건너뛰어도 됩니다) 1. **성별**: 여성 / 남성 / 기타·미입력 2. **나이** (또는 신체나이): 예) 35 3. **현재 증상/목표**: 예) 피로, 수면의 질, 면역, 관절, 특별 없음 4. **임신·수유 여부**: 해당 / 해당 없음 5. **복용 중인 처방약**: 예) 레보티록신, 와파린, 없음 6. **기저질환** (선택): 예) 갑상선, 고혈압, 없음 입력하지 않은 항목은 "일반 성인" 기본값으로 진행합니다. 이어서 분석할 제품을 알려주세요: - 제품명 (예: "센트룸 실버") - 성분표 사진 업로드 - 성분 리스트 직접 입력 (예: "비타민 D 1000IU, ...") - **여러 제품을 한번에 분석하려면 모두 나열하거나 사진을 여러 장 올려주세요** ``` ### 2-1-A. 제품 완전성 재확인 루프 사용자가 제품 목록을 제시한 **직후**, 아래 확인 질문을 **반드시** 실행 (생략 금지): ``` 확인: 현재 매일 드시는 보충제는 아래 N개가 **전부**인가요? - [제품1] - [제품2] - [제품3] 혹시 아래 중 빠진 게 있다면 지금 추가해 주세요: - 오메가3·피쉬오일 - 비타민D (단독 제품, 종합비타민에 포함된 것 외) - 프로바이오틱스·유산균 - 마그네슘·칼슘·철분 (단독) - 루테인·아스타잔틴 등 눈 보조제 - 콜라겐·히알루론산 - 츄어블·젤리 형태 보충제 (잊기 쉬움) - 주 1-2회만 복용하는 제품 "이게 전부" 또는 추가 제품을 알려주시면 분석 진행합니다. ``` **규칙**: - 이 루프를 **거치지 않고 Phase 2로 진입하지 말 것** - 사용자가 "전부"라고 확인한 후에만 분석 시작 - 분석 중간에 사용자가 "아, 이것도 먹어" 하고 추가하면 Phase 1로 복귀하여 처음부터 재산출 - 사유: 초판 테스트에서 사용자가 철분을 "먹는다"고 했으나 실제로는 안 먹었고, 오메가3는 중간에 추가되는 등 목록 부정확이 빈번 ### 2-2. 질문 템플릿 (`--en` 영어 옵션) ``` Starting the supplement analysis. For more accurate results, please share your profile (all fields are optional — you can skip). 1. **Gender**: female / male / other / skip 2. **Age** (or biological age): e.g., 35 3. **Current symptoms/goals**: e.g., fatigue, sleep, immunity, joint, none 4. **Pregnancy/breastfeeding**: yes / no 5. **Prescription medications**: e.g., levothyroxine, warfarin, none 6. **Underlying conditions** (optional): e.g., thyroid, hypertension, none Unspecified fields default to "general adult". Then, provide the supplement(s) to analyze: - Product name - Upload a photo of the Supplement Facts panel - Type the ingredient list directly - **For multi-product stack analysis, list all or upload multiple photos** ``` ### 2-3. 프로필 처리 규칙 - **영유아(<12세) 또는 반려동물** 감지 시 → 즉시 §6 거부 프로토콜 - **임신·수유** 응답 "해당" → 리포트 최상단에 `references/disclaimer.md` §3-1 배너 강제 삽입 - **처방약** 비어있지 않음 → §3-3 배너 삽입, 각 보충제-약물 쌍에 대해 `references/interaction-patterns.md` 매칭 - 모든 필드 미입력 → `profile_assumption: "일반 성인 (19-50세, 여성 기준)"` 플래그 --- ## 3. 파이프라인 (Phase 0-A ~ 6) ``` Phase 0-A: API 연결 체크 (매 세션 최초 1회 — 가장 먼저 실행) ├─ KFDA 환경변수 존재 → 즉시 Phase 0 진입 ├─ user-data/kfda-skip.json (foreign_only) 존재 → 즉시 Phase 0 진입 └─ 둘 다 없음 → API 안내 화면 출력 → 사용자 선택 (A/B/C) A. 지금 연동 → 발급 가이드 단계별 출력 → 키 입력 대기 → ~/.env 설정 안내 → Phase 0 B. 이번만 건너뛰기 → 저장 없음 (다음 세션 재안내) → Phase 0 (KFDA 미연동 배너 포함) C. 영구 건너뛰기 → user-data/kfda-skip.json 생성 → Phase 0 (배너 없음) Phase 0: 프로필 결정 └─ prompts/detect-profile.md → profile_id 확정 └─ user-data/profiles/{id}.json 로드 or 신규 생성 Phase 0.5: 인텐트 라우팅 └─ prompts/detect-intent.md → mode 분류 ├─ quick_check → Phase 1·3만 축약 실행 → 1~2 문단 답변 ├─ quick_replace → Phase 1·5만 축약 실행 → 대체후보 표 └─ full_analysis → Phase 1~6 전체 실행 (아래) ↓ Phase 1: 입력 수신 + 이미지 판독 + 제품 DB 조회 ├─ 라벨 사진 (최우선) ├─ user-data/products/ DB 재사용 (365일 이내) ├─ 텍스트 입력 → 직접 파싱 ├─ 이미지 → prompts/parse-image.md → JSON └─ 제품명만 → Fallback Chain (§4-1-3) ↓ Phase 2: 정규화 └─ prompts/analyze-ingredient.md §2 → canonical_name 매핑 └─ prompts/analyze-ingredient.md §3 → 단위 표준화 (IU→mcg 등) ↓ Phase 3: 스택 합산 + RDA/UL + 중복 + deficiency_gap[] └─ prompts/analyze-ingredient.md §4 / §5 / §6 / §4.5 (부족) ↓ Phase 4: 상호작용 + 근거 URL 조회 └─ prompts/analyze-ingredient.md §7 / §8 ↓ Phase 5: 대체제품 조회 (국내 5 + 해외 3, 흡수율 반영) └─ references/search-templates.md §10-2 + bioavailability-table.md └─ 쿠팡/네이버 = 가격만 / iHerb = 가격+리뷰 ↓ Phase 6: 리포트 생성 + 자동 저장 (프로필별 디렉토리) └─ prompts/report-template.md + references/disclaimer.md §1/§2 └─ user-data/stacks/{profile_id}_latest.json (원본 백업) └─ user-data/reports/{profile_id}/YYYY-MM-DD_HHMM_analysis.md └─ user-data/reports/{profile_id}/latest.md (symlink) ``` **모드별 실행 범위**: | 모드 | Phase 0-A | Phase 0 | 0.5 | 1 | 2 | 3 | 4 | 5 | 6 | 리포트 저장 | |------|----------|---------|-----|---|---|---|---|---|---|------------| | quick_check | ✅ 필수 | ✅ | ✅ | 축약 | ✅ | 선택 항목만 | 선택 항목만 | ❌ | 축약 | ❌ | | quick_replace | ✅ 필수 | ✅ | ✅ | 1제품만 | ✅ | 해당 성분만 | ❌ | ✅ | 축약 | 선택 | | full_analysis | ✅ 필수 | ✅ | ✅ | 전체 | ✅ | 전체 | ✅ | ✅ | 전체 | ✅ | --- ## 4. Phase별 상세 ### Phase 0-A — API 연결 체크 (매 세션 최초 1회) **모든 모드에서 가장 먼저 실행.** Phase 0보다 선행. #### 판단 순서 ``` 1. KFDA_HTFS_KEY + KFDA_FOODSAFETY_KEY 환경변수 존재? → YES: 즉시 Phase 0 진입 (이 Phase 종료) 2. user-data/kfda-skip.json 존재 + reason == "foreign_only"? → YES: 즉시 Phase 0 진입 (이 Phase 종료) 3. 둘 다 아니면: 아래 안내 화면 출력 → 선택 대기 ``` #### 안내 화면 (출력 템플릿) ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ⚠️ 식약처 API 미연동 — 한국 제품 정확도 제한 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 이 스킬은 식약처 Open API 연동을 기본으로 설계됐습니다. API 없이도 동작하지만, 한국 제품(비맥스·아로나민·센트룸 등)의 성분·함량 정확도가 크게 낮아집니다. 항목 | API 없음 | API 있음 ─────────────────|──────────────────|───────────────── 한국 제품 성분 | ★★☆☆☆ (웹 검색) | ★★★★★ (식약처 공식 DB) 성분 함량 정확도 | 낮음 | 높음 의약품/건기식 구분 | 어려움 | 자동 구분 선택해 주세요: A. 지금 연동하기 (API 키 발급, 약 5분 — 승인까지 최대 2시간) B. 이번만 건너뛰기 (다음 세션에 다시 안내) C. 계속 건너뛰기 (외국 보충제만 분석) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` #### 선택별 처리 **A — 지금 연동:** 아래 가이드를 순서대로 출력하고, 키 입력을 기다린 후 Phase 0 진입. ``` [식약처 API 연동 가이드] Step 1. 건강기능식품 API 키 발급 (KFDA_FOODSAFETY_KEY) 1) https://openapi.foodsafetykorea.go.kr 회원가입 2) C003 / I0030 / I2710 각각 활용신청 3) 발급된 키 복사 Step 2. 의약품 API 키 발급 (KFDA_HTFS_KEY) 1) https://data.go.kr 회원가입 2) "식품의약품안전처_의약품개요정보" 검색 → 활용신청 3) Encoding 탭의 URL-encoded 키 복사 (%2F·%2B 포함) ⚠️ 승인까지 최대 2시간 소요. 승인 후 아래 입력. Step 3. 환경변수 등록 (~/.env 또는 claude_desktop_config.json) KFDA_FOODSAFETY_KEY=발급받은_키 KFDA_HTFS_KEY=발급받은_키 키를 받으셨으면 "등록 완료"라고 입력해 주세요. (지금 당장 발급이 어려우면 'B'를 입력하면 이번만 건너뜁니다) ``` 사용자가 "등록 완료" 입력 시 → Phase 0 진입 (환경변수는 재시작 후 적용됨을 안내). **B — 이번만 건너뛰기:** - `user-data/kfda-skip.json` **저장하지 않음** (다음 세션 재안내 보장) - Phase 0 진입. 리포트 상단에 KFDA 미연동 배너 1회 삽입. **C — 영구 건너뛰기 (외국 제품 전용):** - `user-data/kfda-skip.json` 생성: ```json { "reason": "foreign_only", "skipped_at": "YYYY-MM-DD" } ``` - Phase 0 진입. 이후 세션에서 이 Phase 재실행 안 함. #### 규칙 - 이 Phase는 **세션 내 1회만** 실행 (같은 세션에서 두 번째 쿼리부터는 스킵) - 사용자가 먼저 보충제 정보를 입력해도 **이 Phase를 먼저 처리한 뒤** 분석 시작 - "나중에", "무시", "괜찮아" 같은 우회 표현 → B 선택으로 처리 (저장 없음) --- ### Phase 0 — 프로필 결정 모든 사용자 발화에 대해 **가장 먼저** 실행. 분석 대상 프로필을 확정. 1. `user-data/profiles/_index.json` 읽기 (없으면 빈 인덱스 생성) 2. `prompts/detect-profile.md` 프롬프트로 발화 분류 → `decision` 수신 3. `decision` 별 처리: | decision | 처리 | |----------|------| | `match` | `profiles/{id}.json` + `stacks/{id}_latest.json` 로드, "지난번 OO 드시던 '{display_name}' 맞으신가요?" 1회 확인 (세션 내 2분 이내 재참조는 생략) | | `default` | `default_profile_id` 사용. 첫 방문이면 `display_name`을 사용자에게 질문 후 신규 생성 | | `needs_new_profile` | 프로필명 질문 → slug 변환 → `_index.json` 추가 + `{id}.json` 신규 (demographics는 Phase 1에서) | | `ambiguous` | 후보 목록 제시, 사용자 선택 후 재진입 | | `reject_scope` | 영유아·반려동물 거부 문구 출력 후 종료 (§6 거부 프로토콜과 동일) | **프라이버시 원칙**: profile JSON은 로컬에만 저장. WebSearch 쿼리에는 비식별 정보만 사용 (예: 연령대·성별·일반 증상 키워드). **스키마**: `references/user-data-schema.md` 참조. --- ### Phase 0.5 — 인텐트 라우팅 Phase 0 직후 실행. 사용자 발화의 깊이에 맞는 모드를 선택. 1. `prompts/detect-intent.md` 프롬프트 실행 → `mode`, `target`, `suggestion_message` 수신 2. 모드별 분기: | mode | 다음 단계 | |------|----------| | `quick_check` | Phase 1·3 축약 진입. `target.ingredient_ids`만 RDA/UL 조회. 답변 말미에 `suggestion_message` 1문장 | | `quick_replace` | Phase 1·5 축약 진입. `target.product_keys[0]`의 핵심 성분 중심 대체후보 5+3. `suggestion_message`로 풀 분석 제안 | | `full_analysis` | 기존 Phase 1~6 전체 실행. `suggestion_message` = null | **핵심 원칙 (CLAUDE.md §2-1 + L10 교훈)**: - 풀 분석을 **강제 유도하지 않음**. 제안만. - 모호할 때 라이트 모드 편향 (`quick_check` 우선) - 풀 분석 직후 10분 이내 같은 프로필 질문은 `escalation_allowed: false` → 제안 생략 --- ### Phase 1 — 입력 수신 #### 4-1-1. 텍스트 입력 사용자가 성분 리스트를 텍스트로 입력하면 그대로 `ingredients[]` 배열로 변환: ``` "비타민 D 1000IU, 칼슘 500mg, 마그네슘 200mg" → [{ raw_name: "비타민 D", amount: 1000, unit: "IU" }, ...] ``` #### 4-1-2. 이미지 입력 - `prompts/parse-image.md` 프롬프트로 Claude native vision 호출 - JSON 출력 수신 → `overall_confidence` 확인 - `medium`/`low` 또는 `partial` → §4-1-2-a 재확인 플로우 ##### 4-1-2-a. 재확인 플로우 `requires_user_confirmation: true` 시: ``` 성분표 이미지 일부를 명확하게 판독하지 못했습니다. 불명확한 항목: [unclear_fields 리스트] 전체 신뢰도: [overall_confidence] 다음 중 선택해 주세요: 1. 더 선명한 사진을 다시 업로드 (정면, 밝은 조명 권장) 2. 성분을 직접 텍스트로 입력 3. 현재 판독된 부분만으로 분석 진행 (일부 성분 누락 가능, 권장 X) ``` #### 4-1-3. 제품명만 입력 — Fallback Chain v3.1 (KFDA 건기식 + 의약품 통합 + 함량 스크래핑) **핵심 원칙 (2026-04-18 v3.1 — nedrug 상세 스크래핑 통합)**: - 한국 제품 → **식약처 Open API가 1차 근거** (건기식 C003 → 의약품 허가정보 순차 조회) - 건기식 0건 ≠ "모른다". **자동으로 의약품 API 폴백** (OTC 종합비타민이 건기식이 아닌 의약품인 경우 많음 — 비맥스·아로나민·센트룸 등) - **의약품은 Open API만으로 함량 확보 불가** (허가정보 API는 성분명만 제공). ITEM_SEQ 확보 후 **nedrug 상세 페이지 "원료약품 및 분량" 테이블을 필수 파싱** → 진짜 함량(mg/IU/µg)·규격(KP/USP/EP/별규)·환산값(으로서 X mg) 확보 - 라벨 사진 업로드 시 → OCR + 적절한 API 교차검증 (**라벨 값이 ground truth**) - 해외 제품은 식약처 미등록 → Perplexity/공식몰/iHerb 체인으로 폴백 - 전체 규칙: `references/kfda-htfs-api.md` (건기식), `references/kfda-drug-api.md` (의약품 API + §9 nedrug 스크래핑) ``` Step A: 사용자 라벨 사진 요청 (항상 1순위 질문) - "라벨 사진 있으면 훨씬 정확해요. 있으시면 올려주세요." - 사진 제공 시 → prompts/parse-image.md로 JSON 추출 + 라벨의 "의약품/건강기능식품" 표기 감지 → Step B-KFDA로 교차검증 → Step X - 없으면 Step B로 Step B: user-data/ DB 재사용 - 건기식: user-data/products/{key}.json - 의약품: user-data/drugs/{item_seq}.json - verified_at 365일 이내 + confidence ≥ medium이면 재사용 - DB hit 시 → Step X로 (네트워크 호출 0건) Step C: ★ 식약처 C003 API (건강기능식품 1차 근거) - 조건: env KFDA_FOODSAFETY_KEY 설정됨 - 엔드포인트: GET http://openapi.foodsafetykorea.go.kr/api/{KEY}/C003/json/1/10/PRDLST_NM={제품명} - 결과 처리 (kfda-htfs-api.md §4-4): * 1건 → 확정 → prompts/parse-kfda-response.md → Step X * 2~5건 → 리스트 제시 + 사용자 선택 * 6건+ → 좁히기 질문 (제조사 → 제형 → 함량 → 구매시기 순) * 0건 → ★ Step C2로 (건기식 미등록 = 의약품 가능성) Step C2-a: ★ 식약처 의약품 Open API (일반의약품/전문의약품 폴백) [v3 신규, v3.1 재구성] - 조건: env KFDA_HTFS_KEY 설정됨 (또는 KFDA_DRUG_KEY) - 엔드포인트 순차: