소개
화장품 상품 분석을 위한 에이전트 개발. (그 중 크림을 할 예정입니다.)
바이브코딩을 위한 문서를 작성할 것입니다. 이 사례글은 매 주 순차적으로 업로드할 예정입니다.
진행 방법
이전에 정리되지 않았던 문서들의 chatgpt로 목차를 작성하고 문서를 작성합니다.
먼저 이전에 정리되지 않고 있었던 문서들 13개를 넣었습니다. 그리고 제가 작성한 지침을 넣고 진행했습니다.
프롬프트는
"프로젝트 파일을 1번부터 순서대로 읽고 하나의 문서로 정리해주세요. 누락된 것 없이 꼼꼼히 정리해야됩니다. 목차를 먼저 구성해주고, 거기에 맞춰서 하나씩 채워주세요. 먼저 목차부터 정리해주세요. 그러고서 순서대로 정리 요청하겠습니다."
작성했으며, 거기에 목차를 아래와 같이 정리해줬습니다. 그리고 목차에 따라 내용을 채웠습니다.
BeautyPulse AI 통합 마스터 문서 목차(안)
0. 문서 메타
0.1 문서 목적(SSOT/단일 진실 원천)과 독자
0.2 적용 범위(P0/P0+/P1)와 비범위(Non-goals)
0.3 버전/변경 이력(업데이트 로그)
0.4 용어/약어(OliveYoung, 화해, MODS, RAG, Receipts 등)
1. 프로젝트 한눈에 보기
1.1 프로젝트 한 줄 요약
1.2 해결하려는 문제(“화장품 상품 개발자를 위한 컨설팅 AI”)
1.3 핵심 목표와 산출물(6쪽 리포트, 지표, 근거/출처, 검색)
1.4 핵심 원칙(재현성, 근거(Evidence/Receipts) 연결, SSOT)
2. 결정사항 타임라인(파일 1→N 순서)
2.1 초기 설계(P0 로드맵/9단계)
2.2 ERD/스키마 확정 과정(14개 테이블)
2.3 수집 전략 변화(“올영 720 → 화해 100 매칭 → TOP50”)
2.4 로더/드라이버/인덱스 등 운영 표준 확정 과정
2.5 현재 “확정 상태(What’s done / What’s next)”
3. 데이터 소스 & 수집 전략
3.1 대상 채널(올리브영 중심 + 화해 보조)
3.2 Phase 1: 올리브영 리스트 수집(목록 HTML/이미지/CSV)
3.3 Phase 2: 화해 랭킹 매칭 전략(RapidFuzz 임계값)
3.4 Phase 3: TOP50 선정 규칙(A그룹/B그룹)
3.5 Phase 4: TOP50 상세 수집(상세/리뷰/전성분)
3.6 Phase 5: DB 적재 + 임베딩/인덱스
3.7 크롤링 운영 정책(딜레이/체크포인트/재시도/robots)
4. 데이터 표준화/정규화 규칙(품질 기준)
4.1 공통 필드 규칙
4.2 브랜드 정규화
4.3 제품/리뷰/성분 키 설계(유니크 키, 중복 제거 기준)
4.4 리뷰 해시(review_hash) 생성 규칙과 중복 처리
4.5 전성분 파싱 “최종 규칙”(본품 크림만, 주석/따옴표/괄호 처리 등)
4.6 인코딩/CSV 규약(utf-8-sig 등)과 예외 처리
5. 폴더 구조 & 데이터 아 티팩트(파일/경로 SSOT)
5.1 레포 구조
5.2 data/raw 스냅샷 규칙(HTML/이미지 저장 규칙)
5.3 data/processed 산출물 목록(필수/선택)
5.4 data/reference(brand_mapping, 한글→INCI 맵 등)
5.5 data/state 체크포인트(중단 복구 기준)
6. 데이터베이스 설계(ERD/DDL/제약/인덱스)
6.1 DB 선택 이유(PostgreSQL 17 + pgvector + pg_trgm)
6.2 테이블 개요
6.3 Evidence/Receipts 무결성(“정확히 1개의 FK만”)
6.4 인덱스 전략(GIN trigram, IVFFlat/HNSW, 조인 인덱스)
6.5 성능/튜닝 포인트(ivfflat.probes 등)
6.6 스키마 적용 순서(001→002→003)와 멱등성
7. 적재(Loader) 파이프라인
7.1 적재 순서
7.2 로더 입력 파일(자동 탐지 규약)
7.3 UPSERT 정책(리뷰 유니크 키/충돌 정책)
7.4 검증 쿼리 템플릿(건수/NULL/특정 goodsNo 조회 등)
7.5 재현 가능한 “삭제→설치→적재→검증” 절차
8. 임베딩 & 검색(RAG)
8.1 임베딩 대상 테이블/컬럼 범위
8.2 임베딩 모델/차원(text-embedding-3-small, 1536D)
8.3 백필(backfill) 전략(배치/재시도/추적)
8.4 하이브리드 검색(Trigram + Vector + RRF) 개념/구현 포인트
8.5 검색 검증(KNN, trigram 테스트)
9. MODS 4개 에이전트(REV/ING/RTL/REG)
9.1 에이전트 목표와 출력(결과 타입/상태 병합)
9.2 각 노드 역할/입력/출력
RTL: 가격/랭크/리뷰수
REV: 불만 TOP3 + 대표 스니펫
ING: INCI/EWG/Dirty List
REG: 규제 문서 1줄(없으면 해당 없음)
9.3 LLM 사용 범위(REV/REG만 선택적) & 폴백(규칙 기반)
9.4 구조화 출력(JSON Schema) vs 공용 타입(Pydantic SSOT)
9.5 Receipts 저장 규칙(DB evidence + state.receipts)
10. LangGraph 오케스트레이터(병렬→JOIN→집계)
10.1 그래프 구조(병렬 실행, 상태 병합, 게이트)
10.2 체크포인팅(중단 복구)
10.3 오류/폴백/부분 성공 처리 전략
10.4 추적(선택): LangSmith 설정과 운영 방식
11. 6쪽 리포트 생성(HTML/PDF)
11.1 리포트 구성(요약/스냅샷/리뷰/성분·규제/기회맵/권고안)
11.2 Receipts 팝오버(“모든 수치·문장에 출처”) UI 규칙
11.3 report_meta / report_product_map 설계 의도
11.4 렌더링 파이프라인(템플릿 → HTML → PDF 옵션)
12. FastAPI/API 설계
12.1 엔드포인트
12.2 요청/응답 스키마(보고서 생성/조회)
12.3 헬스체크/운영 점검 포인트
13. 운영 표준(로깅/환경변수/설정)
13.1 .env 규약(PG 표준 변수 vs DATABASE_URL)
13.2 로깅 정책(스크립트별 로그, 롤링)
13.3 트레이싱(LangSmith 프로젝트/배치 분리 전략)
13.4 보안/레이트리밋(스텁/확장 포인트)
14. 재현 가능한 실행 가이드(복붙용)
14.1 최초 1회 준비(의존성, PYTHONPATH 등)
14.2 DB 컨테이너 구성/기동
14.3 DDL 적용
14.4 수집 → 매칭 → TOP50 → 상세 수집
14.5 적재 → 임베딩 → 인덱스
14.6 최종 검증 체크리스트
15. 트러블슈팅(빈출 이슈 & 즉시 해결)
15.1 CSV 경로 문제(“0개 유니크 브랜드” 등)
15.2 Windows 인코딩/드라이버/HBA/인증 문제
15.3 ON CONFLICT 키 불일치/중복 리뷰 이슈
15.4 PYTHONPATH/import 오류
15.5 LangSmith 추적이 안 잡힐 때
16. 로드맵(확장/P1+)
16.1 채널 확장(Sephora 등)
16.2 규제 코퍼스/근거(Evidence) 데이터 확장
16.3 검색 품질/평가(Eval)
16.4 CI/테스트/성능 벤치
17. 부록
17.1 파일/스크립트 목록(프로젝트 파일 1~N 원본 인덱스)
17.2 CSV 스키마 표(파일별 컬럼 정의)
17.3 SQL/검증 쿼리 모음
17.4 용어집/규칙 요약(한 페이지)
결과와 배운 점
이제 작성한 문서를 기반으로 작업 단계를 정의하고 작업을 진행할 예정입니다.
