lapie_app/CLAUDE.md

Lapie — 하네스 엔지니어링 운영 규약

본 파일은 Lapie 워크스페이스에서 Claude Code (또는 다른 AI agent)와 협업할 때의 하네스(harness) 운영 규약이다. agent의 컨텍스트 입력·실행 권한·검증 조건을 명시한다. 출처: Karpathy "Software 3.0 / Agentic Engineering" (2026-05-13 박재오 위키 AI-Agent-설계-운영-원칙 정식화) + superpowers 스킬 표준.

---

0. 프로젝트 정체성 (한 줄)

Lapie (라피) = 정면 전신 사진의 신체 영역에 실시간 카메라로 옷을 대보는 iOS 앱. 박재오 D-3 Why "내가 부딪힌 불편함을 누군가 다시 부딪히지 않도록 푸는 것"의 외면 분기 첫 증거. 메인 흐름 '결'(내면 자기자각)과 동등 라인.

• 정식 spec: docs/spec.md
• v0 plan (W1~W4 13 task): docs/v0-plan.md
• 브레인스토밍 원본: docs/brainstorming-raw.md
• 박재오 위키 메타: [[사업-Lapie-피팅앱]] (Obsidian Vault)

---

1. 작업 지시 표준 — 컨텍스트 3단 템플릿

박재오 ↔ AI agent의 모든 작업 위임은 다음 3단 조건으로 해석·실행한다. 명시되지 않으면 agent가 추론하되, 모호하면 시작 전에 묻는다.

• [완료 조건] 이 작업이 끝났다고 말할 수 있는 객관적 기준. (예: "테스트 3개 PASS + npx tsc 무에러 + git commit 1건")
• [금지 조건] 절대 하지 말 것 / 건드리지 말 것. (예: "기존 src/features/segmentation/ 수정 금지", "Skia 셰이더에 새 uniform 추가 금지", "사용자 결정 보류 항목 임의 실행 금지")
• [검증 조건] 결과를 어떻게 검증하는가. (예: "npx jest src/features/autoScale 결과 캡쳐", "iOS 실기기 시각 검증 스크린샷", "verification-before-completion 스킬 적용")

agent가 다른 sub-agent에게 위임할 때도 같은 3단으로 지시한다.

본 3단은 박재오 메인 위키 CLAUDE.md(Obsidian Vault)에서 정식화. Lapie는 그 인스턴스.

---

2. agentic engineering 7 구성요소 (Lapie 매핑)

Karpathy의 7 구성요소를 본 워크스페이스에 매핑한다.

#	구성요소	Lapie 적용
1	스펙	docs/spec.md + docs/v0-plan.md가 단일 진실 소스. 코드 작성 전 반드시 plan task 번호를 명시.
2	계획 검토	신규 기능 추가 전 plan 또는 spec에 한 줄 이상 반영. plan에 없는 작업은 spec 변경 이력에 우선 한 줄 추가.
3	diff 리뷰	모든 commit은 박재오가 직접 또는 superpowers:requesting-code-review 스킬로 리뷰. agent autopilot 금지.
4	테스트	순수 함수(autoScale·maskSplit·photoValidation 등)는 TDD 강제. UI·카메라·합성은 manual test 절차 명시(docs/v0-plan.md 각 task 참고).
5	권한 제한	agent는 docs/·src/·modules/ 외부 디렉토리 수정 금지. git commit/push는 박재오 확인 후. CocoaPods·npm install은 의존성 추가 명시 후.
6	실패 감지	실기기 manual test 실패 시 즉시 task 중단 + plan에 한 줄 보고. "should work" 표현 금지.
7	롤백	각 task는 단일 commit 권장. 실패 시 git revert <sha> 또는 git reset --hard HEAD~1 (push 전에 한정). push 후엔 새 commit으로 수정.

---

3. 폴더 구조

lapie/
├ CLAUDE.md              # 본 파일 — 하네스 운영 규약
├ README.md              # 입구 + 빠른 시작
├ .gitignore
├ docs/                  # 기획·설계 단일 진실 소스
│  ├ spec.md             # 정식 spec (브랜드·시장·기술·일정)
│  ├ v0-plan.md          # W1~W4 13 task 구현 plan
│  └ brainstorming-raw.md # 2026-05-23 brainstorming 원본 보관
├ src/                   # React Native + TypeScript 코드
│  ├ screens/            # 화면 단위 (Onboarding·PhotoCapture·MaskPreview·LiveFitting·Capture)
│  ├ features/           # 도메인 로직 (각 폴더는 단일 책임)
│  │  ├ segmentation/    # Selfie Segmentation 브릿지 + TS 래퍼
│  │  ├ pose/            # Pose Detection 브릿지 + TS 래퍼
│  │  ├ maskSplit/       # 상/하/전신 3 마스크 영역 분할 (Pose keypoint 기반)
│  │  ├ composite/       # Skia 셰이더 합성
│  │  ├ autoScale/       # 자동 스케일 추정 (하이브리드, v0 차별화 포인트)
│  │  └ photoValidation/ # 정면사진 자세 검증
│  ├ store/              # Zustand 전역 상태 (최소화)
│  ├ navigation/         # 화면 전환
│  └ types/              # 공유 타입 정의
├ modules/               # 네이티브 브릿지 (iOS Swift, Android Kotlin)
│  ├ segmentation/ios/   # SegmentationModule.swift + .m
│  └ pose/ios/           # PoseModule.swift + .m
├ ios/                   # Expo prebuild 생성 (W1 Task 1)
├ android/               # Expo prebuild 생성 (v1)
├ app.json               # Expo config (W1 Task 1)
├ package.json           # W1 Task 1
└ tsconfig.json          # W1 Task 1

원칙:

• src/features/<domain>/ 폴더는 단일 책임만 갖는다. 다른 feature 폴더 import는 최소화. 공통 타입은 src/types/로.
• modules/<feature>/ios/ 네이티브 코드는 해당 feature 폴더와 동일 이름으로 매칭.
• docs/는 사람용 단일 진실 소스. src/는 코드 진실 소스. 둘 다 commit.

---

4. 기술 스택 + 빌드 명령어

스택 (v0 확정)

• 프레임워크: React Native 0.76+ / Expo 52+ (bare workflow) / TypeScript
• 카메라: react-native-vision-camera v4 (Frame Processor)
• 세그멘테이션: iOS Vision (VNGeneratePersonSegmentationRequest) / Android: MediaPipe Selfie Segmentation (v1)
• Pose: iOS Vision (VNDetectHumanBodyPoseRequest) / Android: ML Kit Pose (v1)
• 합성: @shopify/react-native-skia v1 (셰이더)
• 제스처: react-native-gesture-handler (핀치·드래그)
• 상태: zustand
• 이미지 픽커: expo-image-picker
• 저장/공유: expo-media-library + React Native Share API
• 빌드: EAS Build (Windows 환경 보완)
• 테스트: Jest + ts-jest (순수 함수만)

빌드 명령어 (W1 Task 1 이후 사용)

# 의존성 설치
npm install

# 네이티브 prebuild (Mac/EAS)
npx expo prebuild --platform ios

# iOS 실기기 빌드 (Mac 필요)
npx expo run:ios --device

# EAS 클라우드 빌드 (Windows 가능)
eas build --platform ios --profile development

# 테스트 (순수 함수)
npx jest

# 특정 모듈만
npx jest src/features/autoScale

# TypeScript 체크
npx tsc --noEmit

Windows 환경 제약

• 박재오 메인 환경 = Windows → iOS 네이티브 빌드 직접 불가
• Pre-Task 0.2(docs/v0-plan.md)에서 결정: (a) Mac mini 구매 / (b) EAS Build 클라우드 / (c) Flutter 재검토
• agent는 Windows에서 작업 시 npx expo run:ios 명령어 호출 금지 → 코드 작성 + Jest 테스트만, 빌드는 EAS 또는 Mac에서.

---

5. 코드 컨벤션

TypeScript

• strict: true 유지 (tsconfig.json)
• 모든 함수는 명시적 반환 타입 (특히 export 함수)
• any 금지. 모르겠으면 unknown 후 타입가드.
• 타입 정의는 인터페이스 우선, 합집합/리터럴은 타입 별칭.

React Native

• 함수형 컴포넌트 + hook만. class 금지.
• StyleSheet는 컴포넌트 파일 하단에 인라인 (CSS-in-JS 라이브러리 도입 X for v0).
• 화면 컴포넌트는 props로 콜백만 받고 내부에서 store 직접 구독.

도메인 로직 (features/)

• 각 feature는 순수 함수 우선. 부수효과(네이티브 호출·파일 IO)는 별도 모듈로 분리.
• 예: calculateScale.ts(순수, TDD 가능) / detectClothBounds.ts(네이티브 호출, manual test).

TDD 적용 범위

• ✅ TDD 강제: features/autoScale/calculateScale.ts, features/maskSplit/splitMask.ts, features/photoValidation/validatePose.ts
• 🟡 TDD 선택: store/, navigation/
• ❌ TDD 비적용: UI 화면, 카메라 합성, 네이티브 브릿지 (manual test로 대체)
• TDD 사이클: 실패 테스트 작성 → 실행 PASS X 확인 → 최소 구현 → 실행 PASS 확인 → commit
• superpowers:test-driven-development 스킬 적용

네이밍

• 컴포넌트: PascalCase (LiveFittingScreen)
• 함수·변수: camelCase (calculateScale, photoUri)
• 타입: PascalCase (PoseResult, ValidationResult)
• 상수: UPPER_SNAKE_CASE (MIN_SCALE, MAX_SCALE)
• 파일: camelCase.ts 또는 PascalCase.tsx (컴포넌트만)

---

6. 네이티브 모듈 가이드

iOS Swift 브릿지 패턴 (modules//ios/)

1. <Feature>Module.swift — 실제 로직 (Vision Framework 호출)
2. <Feature>Module.m — Objective-C 매크로 (RCT_EXTERN_MODULE)
3. src/features/<feature>/index.ts — NativeModules.Module 래핑 + 타입 정의
4. src/features/<feature>/__tests__/<feature>.test.ts — NativeModules mock + TS 래퍼 검증

자세한 예시는 docs/v0-plan.md Task 3·4 참고.

Vision Framework 호출 시 주의

• 좌표계 변환: Vision은 좌하단 원점·normalized (0~1), UIKit은 좌상단 원점·픽셀 → 변환 필요
• 신뢰도 임계 (confidence > 0.3 또는 > 0.5) 항상 적용
• PixelBuffer → PNG 변환 시 메모리 해제 주의 (Swift ARC 자동이지만 큰 이미지 누적 주의)
• 이미지 로드는 URL(string:) → Data → UIImage → CGImage 4단

권한 (app.json)

• NSCameraUsageDescription
• NSPhotoLibraryUsageDescription
• NSPhotoLibraryAddUsageDescription

---

7. 작업 시작/종료 체크리스트 (agent용)

작업 시작 전

• docs/spec.md 최신 결정사항 확인
• docs/v0-plan.md에서 작업할 task 번호·Files·Steps 확인
• 컨텍스트 3단(완료/금지/검증) 명시 (사용자 요청 없으면 agent 추론 후 확인)
• superpowers 스킬 평가 (brainstorming / writing-plans / executing-plans / TDD / verification 등)
• 현재 git 브랜치·작업 트리 상태 확인 (git status)

작업 종료 시

• 컨텍스트 3단 중 [검증 조건] 실제 실행 (예: npx jest src/features/<x> 결과 캡쳐)
• superpowers:verification-before-completion 가이드 적용 (evidence before claims)
• commit message는 conventional commits 형식: feat:, fix:, chore:, docs:, test:, refactor:
• commit 직전 박재오 확인 — agent autopilot push 금지
• docs/v0-plan.md의 해당 task step에 ✅ 체크 (또는 박재오에게 체크 요청)

git 룰

• --no-verify 금지 (사용자 명시 X 한)
• git reset --hard 또는 git push --force는 박재오 확인 후만
• 새 commit은 항상 만들기 (amend 금지, 사용자 명시 시만 amend)
• 브랜치 전략: main + feature 브랜치 (W1, W2, W3, W4 별도 브랜치도 가능)

---

8. 위키 시스템 연동 (박재오 Obsidian Vault)

단일 진실 소스 관계

• 워크스페이스 lapie/docs/ = 정식 spec / plan / brainstorming 원본
• 위키 [[사업-Lapie-피팅앱]] = 박재오 메타 인덱스 (workspace/lapie/ 포인터 역할)
• 의사결정 / 변경 이력 / 작업 로그는 양쪽에 한 줄씩

동기화 룰

• Lapie 관련 큰 결정(spec 변경·기술 스택 변경·일정 변경)은:
  1. docs/spec.md 변경 이력에 한 줄
  2. 박재오 위키 [[사업-Lapie-피팅앱]] 변경 이력에 한 줄
  3. 박재오 위키 wiki/log/YYYY-MM.md에 한 줄
• 코드·세부 구현·테스트 결과는 워크스페이스 내부에서만 (위키에 안 옮김)

Day 0 검증 결과 (2026-05-23 완료)

• 브랜드: Lapie 확정 (Wittu·Mirree·Geola 비교 후)
• 인스타: @lapie_app 선점 완료
• 도메인: lapie.kr + lapie.io 등록 (7월 착수 직전 박재오 직접)
• 상표: Class 9·42만 출원, Class 14·25 회피 (변리사 정식 조사 후)

---

9. 박재오 정합성 검증대

신규 결정이 D-3 Why와 정합한지 항상 확인. 비정합 시 보류 + 박재오 확인.

Why 요소	Lapie 적용
"내가 부딪힌 불편함"	박재오 본인 옷 구매 시 "어울릴까?" 고민 직접 경험
"다시 부딪히지 않도록"	동일 불편함을 가진 타인에게 도구로 제공
적용 영역 '결' (외면 분기)	외면(체형·스타일)을 명료히 자각하기 어려움
발견 4 "함께"	지인 공유 부가기능 = 발견 4의 시각화
발견 3 "증명"	친구·SNS에 "어울린다" 증명받는 욕구

→ 본 검증대 통과 안 하는 기능은 v0에서 제외. v1·v2 추가 기능도 동일 적용.

---

10. 메타 정보

• 생성일: 2026-05-24
• 박재오 위키: [[사업-Lapie-피팅앱]] (사업-Lapie-피팅앱-v0-plan는 본 워크스페이스로 이동)
• 작성 도구: Claude Code + superpowers 스킬 5종
• 최초 brainstorming: 2026-05-23 (superpowers:brainstorming → writing-plans → dispatching-parallel-agents → verification-before-completion)
• 본 CLAUDE.md 패턴 출처: Karpathy Software 3.0 + 박재오 위키 AI-Agent-설계-운영-원칙