gahusb
1a03b71779
- docs/spec.md: 정식 spec (브랜드·시장·기술 스택·일정·Day 0 검증 결과) - docs/v0-plan.md: W1~W4 13 task 구현 plan (TDD + manual test 절차) - docs/brainstorming-raw.md: 2026-05-23 brainstorming 원본 - CLAUDE.md: 하네스 운영 규약 (컨텍스트 3단·agentic 7 구성요소·박재오 Why 정합도) - README.md: 입구 + v0 상태 표 - .gitattributes: Windows ↔ macOS LF 통일 + pbxproj 바이너리 처리 - src/, modules/ 폴더 구조 (.gitkeep) 박재오 + AI agent 협업 표준 정립. 7월 착수 → 5/24 앞당김. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
260 lines
13 KiB
Markdown
260 lines
13 KiB
Markdown
# 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-설계-운영-원칙]]
|