AGENTS.md — Vignette 프로젝트 작업 지침

Vignette = AI 심리상담 시뮬레이션 훈련 플랫폼 (한신대 산학협력). 모노레포: apps/api(FastAPI/Python), apps/web(React 19/Vite/Playwright), docs, infra, scripts.

📚 문서 맵 — 작업 전 해당 가이드를 먼저 읽어라

목적	문서
저장소 개요·빠른 시작	`README.md`
로컬 서버 띄우기·테스트	`docs/guides/local-development.md`
시스템 아키텍처·데이터 흐름	`docs/guides/architecture.md`
테스트·검증 실행	`docs/guides/testing.md`
원천문서·갭 로드맵	`docs/guides/source-docs-and-gaps.md`
SSOT 상태판	`docs/dev_dashboard.html`
백로그	`docs/ops/backlog-2026-06-26.md`
서연 아바타 핸드오프	`docs/ops/handoff-avatar-seoyeon-2026-06-27.md`

작업 결과로 동작/구조가 바뀌면 해당 가이드와 SSOT 대시보드를 함께 갱신한다.

⚠️ 0. 무조건 OS를 먼저 파악하고 시작한다 (최우선·필수)

어떤 작업이든 명령을 실행하기 전에 OS와 셸을 먼저 확정하라. 이걸 건너뛰면 경로/인코딩/도구 차이로 시간을 크게 낭비한다(실제로 그랬다).

작업 시작 시 반드시 확인할 것:

OS / 셸: 이 저장소의 주 개발 환경은 Windows 11 + PowerShell이다. POSIX를 가정하지 마라. Bash 도구도 쓸 수 있으나 셸마다 문법이 다르다.
경로 규칙: Windows 절대경로(D:\..., C:\...). 한글·공백 포함 경로가 흔하다 (예: OneDrive 문서\카카오톡 받은 파일). -LiteralPath로 다루고, 외부 도구에 넘기기 전에 ASCII 이름으로 로컬 복사해 인코딩/공백 문제를 차단하라.
PowerShell 판(5.1) 주의: 인라인 if(){}else{}를 식으로 못 쓴다(삼항 없음). 네이티브 exe stderr를 2>&1로 합치지 마라(ErrorRecord로 감싸짐). 기본 출력 인코딩은 UTF-16 — 다른 도구가 읽을 파일은 -Encoding utf8.
외부 CLI는 실제로 블로킹되는지 확인: GUI 런처(soffice.exe 등)는 즉시 detach되어 Start-Process -Wait가 변환을 안 기다린다. 실제 작업 프로세스 (soffice.bin)를 직접 호출하라. 좀비 프로세스가 락을 잡으면 정리부터 한다.
도구 가용성 먼저 탐지: 변환/처리 전에 LibreOffice·pandoc·python 라이브러리· Playwright 브라우저 등 무엇이 설치돼 있는지 먼저 확인하고 경로를 잡아라.

한 줄 요약: "먼저 OS·셸·경로·도구를 확정한 뒤 실행한다." 추정 금지.

1. 운영 원칙

가짜 증거로 DONE 표기 금지. 실증/외부 의존/소유자 결정이 필요한 항목은 docs/ops/backlog-*.md에 분류해 추적한다(B1 코스메틱 · B2 환경제약 · B3 소유자결정 · B4 외부거버넌스).
docs/dev_dashboard.html이 SSOT(단일 진실 공급원)다. 상태·검증 증거·결정 필요·로드맵의 권위 기준이며, 새 발견·작업 결과·상태 변경은 별도 문서로만 남기지 말고 대시보드에 반영/동기화한다. 백로그(docs/ops/backlog-*.md)는 대시보드와 일치시킨다(어긋나면 대시보드 기준).
소유자(윤찬) 단독 결정 사안을 임의로 정하지 않는다(월권 금지).

2. 검증 기준 (프론트 변경 시)

cd apps/web && npm run typecheck
레이아웃 변경은 e2e/layout-visual-gate.spec.ts(7/7) + 레이아웃 포커스 E2E + e2e/session-layout.spec.ts(8/8) 무회귀. E2E는 web+api(+DB) 스택이 떠 있어야 한다.

3. 커뮤니케이션

모든 대화·주석·커밋 메시지는 한글.
git 커밋 메시지에 Co-Authored-By / Codex 관련 문구 추가 금지.

4. 이미지 생성(gpt-image-2 = imagegen2) · Live2D식 아바타

"이미지 생성해/만들어/그려줘" 요청 → ~/.Codex/skills/codex-image 스킬이 아래 래퍼를 자동 사용.

4.1 gpt-image-2 호출 (반드시 래퍼)

bash ~/.codex/imagegen-headless/codex_imagegen.sh \
  --out <경로.png> [--size WxH] [--quality low|medium|high|auto] \
  [-i <참조이미지> ...] [--all] "<프롬프트>"

인증: ChatGPT 구독 OAuth(~/.codex/auth.json의 auth_mode=="chatgpt"). API 키 사용 금지(과금).
codex 0.140+는 생성 이미지를 세션 rollout JSONL에 base64로 인라인 반환 → 래퍼의 extract_imagegen.py 추출만 결정적. stdout의 "저장 경로"는 환각(직접 codex exec 금지).
프롬프트는 stdin 파이프로(인자 전달 시 멈춤). 변주 생성 시 base를 -i 참조로 넘겨 아이덴티티·프레이밍 고정.
투명배경 미지원 → 단색 평면 배경으로 생성 후 누끼. 한글 텍스트 렌더 가능(stdin 파이프라 인코딩 문제 없음).

4.2 누끼(컷아웃)

object-separation 스킬(BiRefNet): ~/.venvs/object-separation/Scripts/python.exe ~/.agents/skills/object-separation/scripts/separate_object.py <in> <out> --model birefnet-general
알파 정제(잔류 헤이즈 제거): 임계치 <35→0, >205→255 + 페더(docs/avatar-art/seoyeon/publish.py 참조).

4.3 Live2D식 아바타(파츠 분리 리깅)

아바타는 기본 SVG 파라미터 리그 또는 래스터 파츠 분리 리깅(apps/web/src/components/avatar/RasterBust.tsx)으로 렌더. 후자는 persona.rasterArtSet 지정 시 활성.

레이어(각각 독립 opacity/교체 → 표정 중에도 깜빡임·입술싱크가 따로 움직임): base(neutral 전신) + upperface-<표정>(눈썹+눈) + eyelid-closed(깜빡임, 표정 무관) + mouth-<표정> + mouth-open(립싱크).
파이프라인(재현 스크립트는 docs/avatar-art/seoyeon/):
1. codex_imagegen.sh로 base + 표정 변주(sad/tired/anxious/warm/startled/eyes-closed/speaking) 생성. 변주는 base를 -i 참조로, 동일 평면 배경.
2. BiRefNet 누끼 → publish.py(표준 캔버스 900×1125 정규화 + 알파 정제)로 apps/web/public/avatar/<artSet>/ 게시.
3. make-parts.py로 특징 영역(upperface/eyelid/mouth) 크롭+페더 파츠를 parts/ 생성(영역 상수 튜너 블럭).
연결: persona.ts의 AvatarPersona.rasterArtSet / Session.tsx의 PERSONA_AVATAR_LOOKS[<code>].rasterArtSet / RasterBust.tsx(28표정→클러스터 매핑 포함).
dev 미리보기(인증 없음): /dev/avatar-preview(AvatarPreview.tsx). 스크린샷: node apps/web/scripts/avatar-shot.mjs(BASE_URL 환경변수로 포트 지정).
실제 Live2D Cubism(.moc3)은 편집기 저작이 필요해 자동화 불가 → 위 레이어 합성이 실용적 대안.

4.4 진행 중인 아바타 작업 핸드오프

서연(P1) 아바타 작업은 별도 세션에서 진행. 현재 상태·남은 작업(Image #2=짧은 보브 기준 재생성 등)은 docs/ops/handoff-avatar-seoyeon-2026-06-27.md 참조.

7.2 KiB Raw Blame History Unescape Escape