diff --git a/AGENTS.md b/AGENTS.md index c9f4513..17f4cf9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -74,17 +74,31 @@ These apply at every autonomy level and must not be weakened for convenience: Follow `docs/PLANNING.md`: decide → narrow → validate → specify. -Current next priorities (do not invent a full stack first): +PoC execution (real participant recruiting for PoC #1/#3, Q3 interviews) is +currently on hold — that data collection is deferred, not cancelled. In the +meantime, work has moved into Phase 1 app-build groundwork that doesn't +depend on PoC results (see `docs/roadmap.md` Phase 1 §2 for which workstreams +those are). -1. PoC #1 — on-device tone realism -2. PoC #3 — impersonation / trust acceptance (badge, veto UX) -3. Clickable prototype (badge + veto) -4. Small user interviews -5. Meeting review to promote Q1~Q7 from 제안 → 확정 +The tech stack for Phase 1 is decided — see `docs/tech-design.md` §8 +(Android native/Kotlin, Python/FastAPI backend, PostgreSQL, WebSocket relay, +Room+SQLCipher on-device). Do not re-litigate or invent a different stack; +build within this one unless a decision-log-style update changes it. -Do not invent frameworks, folder layouts, or CI conventions until real code -exists. When code work starts, prefer Android-first changes aligned with -`docs/tech-design.md` and keep L0~L2 + safety invariants intact. +### Phase 1 앱 빌드 작업 규칙 + +- Before starting any Phase 1 app-build task, check `docs/roadmap.md`'s + "Phase 1 상세 작업 분해" checklist for what's already done and what's next. +- Follow the "권장 착수 순서" there — don't skip ahead in the numbered order + without a reason, and note the reason in the checklist if you do. +- When a task is finished, check it off in that same checklist. When you + discover a new sub-task, add it there rather than tracking it elsewhere. +- Items under Phase 1 §3 ("PoC 결과가 있어야 정할 수 있는 것") stay unresolved + until real PoC data comes in — don't guess a default to unblock yourself; + leave a placeholder and move on to other checklist items instead. + +Do not invent frameworks, folder layouts, or CI conventions beyond what +`docs/tech-design.md` §8 and `docs/roadmap.md` already specify. ## Documentation conventions diff --git a/CLAUDE.md b/CLAUDE.md index b91be9a..c17c295 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,8 @@ Follow the project instructions in [@AGENTS.md](./AGENTS.md). Quick context: -- This repo is planning docs only (no app code yet). +- This repo started as planning docs only; Phase 1 app-build has now begun. + Check `docs/roadmap.md` Phase 1 checklist before starting app-build work. - Working product name: **분신** (tentative). - Source of working decisions: `docs/decision-log.md` (status: 제안). - v1 scope: self-app closed beta, L0~L2, 읽씹 종결 + 단톡 따라잡기, Android first. diff --git a/docs/roadmap.md b/docs/roadmap.md index 6936a68..af54a6c 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -21,65 +21,66 @@ **PoC 결과와 무관한 기반 작업은 병행 착수**하고, **PoC 결과가 있어야 정할 수 있는 세부 값**은 자리만 비워두고 나중에 채우는 방식으로 진행한다. 아래 §3이 그 경계선이다. +이 체크리스트가 Phase 1 작업의 단일 기준이다 — 작업을 시작하기 전에 여기서 다음 항목을 확인하고, +끝나면 체크하고, 새로 발견한 하위 작업은 해당 항목 밑에 추가한다 (`AGENTS.md` "Phase 1 앱 빌드 +작업 규칙" 참고). + #### 1. 착수 전 확정 필요 (기술 스택) -- 클라이언트: Android 네이티브(Kotlin) vs 크로스플랫폼 — 미정 -- 백엔드 언어/프레임워크, 데이터베이스 — 미정 -- 메시지 릴레이 방식 (자체 서버 WebSocket vs 관리형 서비스) — 미정 -- 온디바이스 저장소/암호화 방식 — 미정 -- Gemini API 프로덕션 키·쿼터 관리 — 미정 (`poc/tone-corpus/`는 PoC용 키만 다룸) +- [x] 기술 스택 결정 — `tech-design.md` §8 (Android 네이티브/Kotlin, 백엔드 Python/FastAPI, + PostgreSQL, WebSocket 릴레이, Room+SQLCipher, Gemini 키 분리) #### 2. 워크스트림별 작업 **2.1 백엔드 인프라** (PoC 결과 무관 — 지금 착수 가능) -- 계정/인증 (초대 코드 기반 가입) -- 메시지 릴레이 서버 (송수신, 멀티 디바이스 동기화) -- DB 스키마: users, contacts, conversations, messages, twin_settings, escalation_logs, whitelist_rules -- 푸시 알림 서비스 연동 +- [ ] 계정/인증 (초대 코드 기반 가입) +- [ ] 메시지 릴레이 서버 (송수신, 멀티 디바이스 동기화) +- [ ] DB 스키마: users, contacts, conversations, messages, twin_settings, escalation_logs, whitelist_rules +- [ ] 푸시 알림 서비스 연동 **2.2 AI 파이프라인 프로덕션화** (PoC 스크립트 → 서비스로 승격) -- `poc/tone-corpus/generate_draft.py`·`escalation_filter.py`·`retrieve_style.py`를 백엔드 API로 이식 -- 자율성 엔진(L0~L2) 오케스트레이션: 에스컬레이션 게이트 → 검색 → 초안 생성 → 승인/자동발송 분기 +- [ ] `poc/tone-corpus/generate_draft.py`·`escalation_filter.py`·`retrieve_style.py`를 백엔드 API로 이식 +- [ ] 자율성 엔진(L0~L2) 오케스트레이션: 에스컬레이션 게이트 → 검색 → 초안 생성 → 승인/자동발송 분기 (`tech-design.md` §3 흐름 그대로) -- 온디바이스 말투 이력 저장 + 서버 최소 전송 원칙 구현 -- 사후 알림 + 되돌리기 로그 스키마/API +- [ ] 온디바이스 말투 이력 저장 + 서버 최소 전송 원칙 구현 +- [ ] 사후 알림 + 되돌리기 로그 스키마/API **2.3 안드로이드 클라이언트** -- 기본 채팅 UI (대화 목록, 대화방) — 무관, 착수 가능 -- 온보딩 플로우(5분 온보딩) 뼈대 — 무관, 착수 가능. 말투 학습 UX 디테일만 PoC#1 결과로 조정 -- 분신 뱃지·실시간 본인확인·거부권 UX — 클릭 프로토타입 디자인 그대로 구현 가능 -- 자율성 설정 화면(L0~L2, 화이트리스트, 상대별 예외) — 무관, 착수 가능 -- 에스컬레이션 배너·사후알림·되돌리기 UI — 무관, 착수 가능 +- [ ] 기본 채팅 UI (대화 목록, 대화방) — 무관, 착수 가능 +- [ ] 온보딩 플로우(5분 온보딩) 뼈대 — 무관, 착수 가능. 말투 학습 UX 디테일만 PoC#1 결과로 조정 +- [ ] 분신 뱃지·실시간 본인확인·거부권 UX — 클릭 프로토타입 디자인 그대로 구현 가능 +- [ ] 자율성 설정 화면(L0~L2, 화이트리스트, 상대별 예외) — 무관, 착수 가능 +- [ ] 에스컬레이션 배너·사후알림·되돌리기 UI — 무관, 착수 가능 **2.4 안전장치 통합** (전 구간 필수, 타협 불가) -- 에스컬레이션 하드게이트가 클라이언트·서버 전 구간에서 우회 불가하게 설계 -- 데이터 프라이버시: 온디바이스 암호화, 삭제 플로우, 데이터 흐름 대시보드 +- [ ] 에스컬레이션 하드게이트가 클라이언트·서버 전 구간에서 우회 불가하게 설계 +- [ ] 데이터 프라이버시: 온디바이스 암호화, 삭제 플로우, 데이터 흐름 대시보드 **2.5 QA/테스트** -- `escalation_filter.py`의 자체 테스트를 정식 테스트 스위트로 승격, `generate_draft`·`retrieve_style`도 동일하게 -- 자율성 플로우(L0→L1→L2) 통합 테스트 -- 온보딩·채팅·설정 수동 QA +- [ ] `escalation_filter.py`의 자체 테스트를 정식 테스트 스위트로 승격, `generate_draft`·`retrieve_style`도 동일하게 +- [ ] 자율성 플로우(L0→L1→L2) 통합 테스트 +- [ ] 온보딩·채팅·설정 수동 QA **2.6 베타 배포 준비** -- 초대 기반 베타 가입 플로우 -- `vision.md` 성공 지표(자연스러움·거부율·안전선 위반) 계측용 분석/피드백 수집 -- 모니터링 대시보드 (에스컬레이션 트리거율, 생성 지연시간, 오류율) +- [ ] 초대 기반 베타 가입 플로우 +- [ ] `vision.md` 성공 지표(자연스러움·거부율·안전선 위반) 계측용 분석/피드백 수집 +- [ ] 모니터링 대시보드 (에스컬레이션 트리거율, 생성 지연시간, 오류율) #### 3. PoC 결과가 있어야 정할 수 있는 것 (병행 불가, 값만 비워둠) -- 자율성 기본값(L1 vs L2 어디서 시작할지) — Q3 인터뷰 필요 -- 화이트리스트 기본 주제 목록 — 실사용 데이터 필요 -- 신뢰 UX 문구/노출 위치 최종 확정 — PoC#3 결과 필요 -- 실제 베타 오픈 시점 — `vision.md` 게이트 통과 필요 +- [ ] 자율성 기본값(L1 vs L2 어디서 시작할지) — Q3 인터뷰 필요 +- [ ] 화이트리스트 기본 주제 목록 — 실사용 데이터 필요 +- [ ] 신뢰 UX 문구/노출 위치 최종 확정 — PoC#3 결과 필요 +- [ ] 실제 베타 오픈 시점 — `vision.md` 게이트 통과 필요 -#### 4. 권장 착수 순서 +#### 4. 권장 착수 순서 (진행 상황) -1. §1 기술 스택 결정 (회의 필요) -2. 2.1 백엔드 기본 인프라 + 2.3 채팅 UI 뼈대 (병행) -3. 2.2 AI 파이프라인 프로덕션화 (PoC 스크립트 재사용) -4. 2.3 나머지 UX(온보딩·설정·뱃지) -5. 2.4/2.5 안전장치·QA -6. PoC 결과 반영 → §3 확정 → 2.6 베타 오픈 +1. [x] §1 기술 스택 결정 +2. [ ] 2.1 백엔드 기본 인프라 + 2.3 채팅 UI 뼈대 (병행) — **다음 작업** +3. [ ] 2.2 AI 파이프라인 프로덕션화 (PoC 스크립트 재사용) +4. [ ] 2.3 나머지 UX(온보딩·설정·뱃지) +5. [ ] 2.4/2.5 안전장치·QA +6. [ ] PoC 결과 반영 → §3 확정 → 2.6 베타 오픈 1~5는 PoC 실제 실행(A트랙)과 병행 가능 — PoC가 늦어져도 인프라 작업은 막히지 않는다. 다만 §3 항목과 최종 베타 오픈은 PoC 결과 없이 확정하지 않는다. diff --git a/docs/tech-design.md b/docs/tech-design.md index 265404b..2e1673a 100644 --- a/docs/tech-design.md +++ b/docs/tech-design.md @@ -103,3 +103,20 @@ v1에서는 커스텀 모델을 새로 학습하지 않는다. 대신 **검색 파싱 로직을 유지보수해야 해서, 아직 검증 안 된 v1 핵심 가설과 리스크가 섞인다. - 분신 간 프로토콜(L4) — 네트워크 효과가 필요해 사용자 기반이 있어야 의미 있음. - 서버 측 전체 대화 분석/추천 — 온디바이스 우선 원칙과 상충. + +## 8. 기술 스택 결정 (Phase 1) + +`roadmap.md` Phase 1 §1의 "착수 전 확정 필요" 항목에 대한 결정. PoC 데이터와 무관하게 지금 +확정할 수 있는 것들이라 여기서 정리한다 — 자율성 기본값 같은 PoC 의존 값은 여전히 미정으로 남는다. + +| 항목 | 결정 | 근거 | +|---|---|---| +| 클라이언트 | Android 네이티브 (Kotlin, Jetpack Compose) | Q7이 이미 안드로이드 우선을 확정함. 크로스플랫폼은 v2 OS 레이어(알림 접근 권한 API)에서 결국 네이티브가 필요해지므로, 처음부터 네이티브로 시작하면 나중에 다시 만들 일이 없음 | +| 백엔드 | Python (FastAPI) | `poc/tone-corpus/`의 AI 파이프라인(generate_draft·escalation_filter·retrieve_style)이 이미 Python — 언어를 바꾸면 그대로 재사용 못 하고 다시 짜야 함. 클로즈드 베타 규모에서 성능은 병목이 아님 | +| 메시지 릴레이 | FastAPI WebSocket | 자체 서버로 충분한 규모(소규모 지인 네트워크 베타). Kafka·관리형 pub-sub 같은 건 지금 시점에 과한 인프라 | +| 데이터베이스 | PostgreSQL | users/contacts/conversations/messages/escalation_logs/whitelist_rules 관계형 스키마에 적합, 운영 경험 풍부 | +| 온디바이스 저장소 | Android Room (SQLite) + SQLCipher 암호화 | 말투 이력·설정을 기기 내 암호화 저장한다는 §2/§5 원칙을 그대로 구현 | +| Gemini API 키 관리 | 프로덕션 키는 서버 환경변수/시크릿 매니저로, PoC 키와 분리 | `poc/tone-corpus/.env`는 PoC 전용 — 프로덕션 트래픽과 쿼터를 섞지 않음 | + +이 표 밖의 결정(자율성 기본값, 화이트리스트 기본 주제, 신뢰 UX 문구)은 `roadmap.md` Phase 1 §3에 +남아있는 PoC 의존 항목이다 — 여기서 같이 정하지 않는다.