# 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 이후 사용)
```bash
# 의존성 설치
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/<feature>/ios/)
1. `<Feature>Module.swift` — 실제 로직 (Vision Framework 호출)
2. `<Feature>Module.m` — Objective-C 매크로 (RCT_EXTERN_MODULE)
3. `src/features/<feature>/index.ts` — NativeModules.<Feature>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-설계-운영-원칙]]