altair823-org/inkling
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 18 Wiki Activity

docs(spec): F1~F6 dogfood 피드백 로드맵 v0.2.1 설계

Browse Source 
8개 항목 순차 작업 (F6-L1 → F5 → F6-L3 → F1 → F2 → F3+F4-E →
F6-L2 → F4-C·F) + 데이터 안전 우선 + 머지+테스트 게이트 + 단일
v0.2.1 cut 후 dogfood 재설치 + 1주 soak. F4-A·D 는 측정 후
별 brainstorm 으로 deferred. 항목별 mini-brainstorm 에서
decision-pending 답변하는 라이프사이클.

본 spec 은 순서·범위·게이트만 정의, 항목 내부 설계는 per-item.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
altair823
2026-04-26 01:42:46 +09:00
parent 2e709652fe
commit 6d3df0273e
1 changed files with 229 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

229
docs/superpowers/specs/2026-04-26-feedback-roadmap-design.md Normal file
View File

@@ -0,0 +1,229 @@
# Dogfood 피드백 로드맵 (F1~F6 → v0.2.1) 설계
**작성일:** 2026-04-26
**저자:** 김태현 (dlsrks0734@gmail.com)
**문서 성격:** v0.2.0 dogfood 와 병렬로 진행되는 F1~F6 항목 8개의 순차 작업 로드맵. 본 문서는 **순서·범위·게이트** 만 정의하며, 각 항목 내부 설계는 항목별 mini-brainstorm + writing-plans 단계에서 결정.
**선행 문서:**
- `docs/superpowers/specs/2026-04-25-dogfood-feedback.md` (F1~F6 raw/drafting 수집)
- `docs/superpowers/specs/2026-04-24-inkling-vertical-slice-design.md` (slice v0.4 본문, §1·§5·§7)
- `docs/superpowers/strategy/strategy.md` (심리학 전략, F3·F4-E 동반 갱신 대상)
- `docs/superpowers/strategy/dogfood-strategy.md` (dogfood 운영안)
---
## 1. 결정 요약
| 결정 | 값 | 근거 |
|------|-----|------|
| 우선순위 기준 | **데이터 안전 우선** | dogfood 진행 중 손실 위험 즉시 차단. F6 의 raw 발견이 시기적으로 가장 무거운 신호. |
| 항목당 게이트 | **머지 + 테스트 통과** (typecheck + 52+ 단위 + e2e smoke) | 빠른 회전. 새 빌드는 누적 후 한 번에 cut. |
| 시작 항목 | **F6-L1 로컬 스냅샷** | 안전 우선 + 작은 범위 + 독립 (외부 dep 0). |
| 순서 | **데이터 라이프사이클 → 기능 → 카피 → 무거운 sync → cue 강화** (Option X) | 백업·export·import 안전망 완성 후 schema 변경 (F1) 진입. e2e 흔드는 카피 변경은 늦게 배치. |
| 다음 빌드 | **v0.2.1** (8개 모두 머지 후 단일 cut) | slice §7 strict-pin 컨벤션의 patch 증분. |
| F4-A·D | **deferred** — v0.2.1 dogfood soak 후 측정 데이터 기반 별도 brainstorm | 측정 인프라가 cut 시점부터 활성. 사전 결정 위험 회피. |
| Decision-pending 처리 | **항목별 mini-brainstorm** | 본 문서는 순서만, 항목 내부는 per-item. |
---
## 2. 순차 작업 순서
```
v0.2.0 ────────[ dogfood 동결, 병렬 진행 ]────────
│
개발 트랙 (main 직접 머지): │
① F6-L1 로컬 스냅샷 [작음, 안전 즉시] │
② F5 Export [중, 의존성 잠금해제] │
③ F6-L3 Import [작음, F5 직후] │
④ F1 Due Date [큼, migration v2] │
⑤ F2 태그 클릭 [작음, 독립] │
⑥ F3+F4-E 카피·strategy 정리 [중, e2e 영향] │
⑦ F6-L2 Git sync [가장 큼] │
⑧ F4-C·F cue 강화 [작음] │
│
┌──────────┘
▼
v0.2.1 cut (단일)
│
▼
dogfood 재설치 + ≥ 1주 soak
│
▼
F4-A·D (측정 후 별 brainstorm)
```
### 2.1 순서 결정 근거 (요약)
1. **F6-L1 (1번)** — 안전 우선. SQLite `db.backup()` 만 사용, 외부 dep 0, 다른 항목 무영향.
2. **F5 (2번)** — F4-H5 측정 + F6-L3 import + F6-L2 git sync 의 dependency. 잠금해제 효율 1위.
3. **F6-L3 (3번)** — F5 의 역방향. 형식 동일, ImportService 만 추가. 데이터 라이프사이클 3종 세트 완성.
4. **F1 (4번)** — schema migration v2 가 백업·export·import 인프라 위에서 진행되어 회수 가능. migration 결함 시 v0.2.0 백업으로 복원 가능.
5. **F2 (5번)** — 작은 renderer 변경. F1 schema 변경과 충돌 없음.
6. **F3+F4-E (6번)** — strategy.md §1·§3·§7 의 "기억 구출" 어휘 결정 + e2e smoke 단언 변경 + Zeigarnik priming 카피. 한 PR 으로 묶음. e2e 흔드는 위치를 늦게 배치하여 다른 항목 머지 흐름 보호.
7. **F6-L2 (7번)** — git CLI 의존성 + safeStorage + 동기화 worker. 가장 무거움. F5/F6-L1/F6-L3 인프라 안정 후.
8. **F4-C·F (8번)** — 트레이 뱃지 + 정체성 카피. F3 카피 톤 결정 후 톤 통일. 가벼움.
---
## 3. 항목당 범위 (In/Out)
각 항목의 PR 범위 라인. 세부 결정 (decision-pending) 은 항목 시작 시 mini-brainstorm 에서.
| # | 항목 | In (이 PR 범위) | Out (다음 항목 또는 후속) |
|---|------|----------------|--------------------------|
| 1 | **F6-L1** 로컬 스냅샷 | `BackupService` + `db.backup()` 래핑 + GFS 로테이션 (일 14·주 4·월 6) + 트레이 메뉴 "지금 백업" + 종료 hook (`before-quit`) + `.last-snapshot` 마커 + 단위 테스트 (로테이션) | 외부 디렉터리 백업, 암호화, 미디어 포함, 자동 복원 |
| 2 | **F5** Export | `ExportService` + frontmatter 마크다운 (one-file-per-note) + `index.jsonl` + `manifest.json` + `README.md` 동봉 + 미디어 평탄화 복사 + 트레이 메뉴 "내보내기..." + 폴더 선택 다이얼로그 + 단위 테스트 (frontmatter 합성, 슬러그) | 증분 export, CLI 플래그, watch-mode, CSV/JSON 형식 |
| 3 | **F6-L3** Import | `ImportService` + 충돌 미리보기 다이얼로그 (n 신규, m 변경, k 충돌) + 트레이 메뉴 "백업에서 복원..." + 단위 테스트 (id 충돌 정책) | git remote 통한 import, 충돌 자동해결, 마이그레이션 자동 |
| 4 | **F1** Due Date | migration v2 (`due_date TEXT`, `due_date_edited_by_user INTEGER`) + 규칙 파서 (정규식 + KST 변환) + zod 스키마 확장 + AI 프롬프트 `{{TODAY_KST}}` + NoteCard 라벨 슬롯 + EditableField 재사용 + 골든 픽스처 50건 | 음력·시각 단위·반복 일정, 만료 처리 정책, 별도 due 뷰 |
| 5 | **F2** 태그 클릭 | NoteCard 칩 onClick 변경 (필터) + ✕ 아이콘 추가 + 5초 undo 토스트 + zustand `tagFilter` + Inbox 헤더 필터 칩 | 다중 태그 필터, rename/merge, 자동완성 |
| 6 | **F3+F4-E** 카피 정리 | NotificationService 회전 카피 #3 교체 + 트레이 라벨 2개 + 빈 상태 + QC 힌트 + `package.json description` + e2e smoke 단언 동기화 + slice §5.5 카피 테이블 + strategy.md §1·§3·§7 어휘 갱신 + Zeigarnik priming 카피 1줄 | 회전 카피 4종 전면 재작성, onboarding, 다국어 |
| 7 | **F6-L2** Git sync | `SyncService` (BackgroundSyncWorker) + `GitClient` (CLI 래퍼) + `CredentialStore` (safeStorage 래퍼) + Settings 창 신설 (remote URL · token · 주기 · 미디어 포함 · 충돌 정책) + 5분 debounce + 종료 시 push + 충돌 다이얼로그 (3-way 선택) + 트레이 상태 표시 | 자동 conflict resolution, 다중 활성 디바이스 sync, LFS, 암호화 |
| 8 | **F4-C·F** cue 강화 | 트레이 아이콘 동적 갱신 (오늘 캡처 0/N 색·뱃지) + `repo.countToday()` + Inbox 헤더 정체성 카운터 + 카피 1줄 ("오늘 N번 비웠습니다") | F4-A 잠금 hook, F4-D 랜덤 알림 (deferred) |
### 3.1 공통 게이트 (모든 항목)
각 항목 머지 전 필수:
- `npm run typecheck` 통과 (현재 0 에러)
- `npm test` 통과 (현재 52/52, 항목 신규 단위 추가)
- `npm run test:e2e` 통과 (현재 1/1)
- 항목 신규 단위 테스트 ≥ 1개 (TDD)
- main 머지 + dogfood-feedback.md 상태 🚀 promoted + 별 spec 분기
---
## 4. 항목당 작업 흐름
```
[항목 N 시작]
│
├─ mini-brainstorm ← 본 항목의 decision-pending 답변
│ - F<N>-spec 의 "결정 대기" 슬롯 채움
│ - dogfood-feedback.md 의 상태 🌱 → 🔬 → 📝 전이
│
├─ writing-plans ← TDD 구현 계획
│ - test-driven-development 스킬 사용
│ - 한 항목 = 한 plan
│
├─ 구현 (executing-plans 또는 직접)
│ - 브랜치: feat/F<N>-<short-slug> (예: feat/F1-due-date)
│ - 게이트 통과 후 main 머지
│ - 단일 PR 또는 main 직접 push (작은 항목 한정)
│
├─ dogfood-feedback.md 갱신
│ - 상태 → 🚀 promoted
│ - 별 spec 분기 → docs/superpowers/specs/2026-MM-DD-<topic>.md
│ - 본 문서엔 1줄 요약 + 링크만 남김
│
└─ 다음 항목 시작
```
### 4.1 Cross-cutting 정책
| 영역 | 정책 |
|------|------|
| **버전 관리** | 8개 모두 머지될 때까지 `package.json` `0.2.0` 유지. v0.2.1 cut 은 8번 후 단일. |
| **브랜치 전략** | `feat/F<N>-<slug>` 단명. main 머지 후 삭제. 작은 항목 (F6-L1, F2, F4-C·F) 은 main 직접 push 도 허용 (sandbox 정책 따름). |
| **테스트 추가 정책** | 항목당 최소 단위 1개. e2e smoke 영향 시 단언 동기화. integration (Ollama) 은 AI 호출 영향 시만. |
| **Slice invariant 위반 시** | 본 로드맵 결과로 invariant 변경 — slice spec §7 도 PR 안에 동봉 수정. |
| **F4-A·D deferred** | v0.2.1 dogfood soak (≥ 1주) 후 측정 데이터 보고 별도 brainstorm 진입. 본 로드맵 범위 외. |
| **dogfood-feedback.md 라이프사이클** | 항목 promoted 시 본 문서엔 1줄 + 링크. raw/drafting 항목은 그대로 누적. |
| **신규 dependency** | slice §7 strict-pin 그대로. 신규 dep 도입 시 PR 안에 §7.2 갱신 동봉. F6-L2 의 git CLI 는 시스템 의존이라 README 사전 요구 추가. |
| **로깅 정책** | slice §1.1 invariant 4 (raw_text/title/summary/intent 미기록) 유지. F5/F6 export·sync 로그도 노트 본문 미기록, ID·길이·해시 prefix 만. |
| **Strategy.md 동반 갱신** | F3+F4-E 항목 (6번) 에서만. 다른 항목은 strategy.md 미수정. |
---
## 5. v0.2.1 Cut 단계
8번 항목 머지 후:
```
[v0.2.0 dogfood 환경에서]
1. 트레이 → "지금 백업" 1회 클릭 ← F6-L1 첫 실증, 백업 1회 보장
2. 트레이 → "내보내기..." 1회 ← F5 첫 실증, 외부 백업 이중화
3. Inkling 종료 (트레이 → 종료) ← 설치 충돌 회피
[빌드 머신에서]
4. package.json version: 0.2.0 → 0.2.1
5. CHANGELOG.md (신설) 또는 git tag 메시지에 누적
* 결정 대기: CHANGELOG.md 신설 vs git tag 메시지 ─ 8번 항목 직전 mini-brainstorm 에서 결정
6. npm run dist
7. dist/Inkling Setup 0.2.1.exe 검증
[dogfood 머신에서]
8. Setup 0.2.1.exe 실행 → 같은 폴더에 설치 (위치 변경 시 side-by-side 위험)
9. 첫 실행 → migration v2 자동 적용 (F1 due_date 컬럼 추가)
10. 트레이 → "백업에서 복원..." 메뉴 존재 확인 (F6-L3 회로 통)
11. ≥ 1주 soak 시작
```
### 5.1 업그레이드 안전망
| 위험 | 완화 |
|------|------|
| migration v2 결함으로 DB 손상 | **2가지 복원 경로 보유**: (a) 단계 1 의 F6-L1 백업은 v0.2.0 schema 라 복원하려면 v0.2.0 인스톨러 재설치 후 백업 파일 교체 → 다시 v0.2.1 업그레이드 (migration 재시도 또는 fix 적용된 v0.2.2 대기). (b) 단계 2 의 F5 export 는 schema-agnostic 마크다운이라 v0.2.1 의 F6-L3 import 로 직접 복원 가능. (b) 가 더 빠른 회복 경로. |
| 설치 위치 변경 → side-by-side 잔존 | 설치 마법사에서 같은 폴더 선택 (기본값) |
| 앱 실행 중 설치 실패 | 단계 3 에서 종료 |
| 자동시작 토글 상태 손실 | `HKCU\...\Run` + `.autostart-init` 보존됨 (data dir 손대지 않음) |
| electron-updater 미설정 | 본 로드맵 범위 외. 사용자가 수동 다운로드 (gitea release 호스팅 후속 검토) |
---
## 6. 측정
### 6.1 로드맵 측정
| 메트릭 | 임계값 | 측정 방법 |
|--------|--------|----------|
| 항목 평균 PR 사이즈 | < 800 lines diff | git log 통계 |
| 항목 평균 머지 간격 | < 5일 | git log 시간차 |
| 회귀 테스트 추가 | 항목당 ≥ 1개 단위 테스트 | tests/unit 카운트 |
| dogfood-feedback.md 상태 전이 | 8/8 모두 🚀 promoted | grep |
| v0.2.1 cut 후 1주차 데이터 손실 | 0회 | 본인 라벨링 |
| typecheck/test 회귀 | 0회 (모든 항목 통과) | CI · 로컬 |
### 6.2 silent invariant 후보
본 로드맵 결과로 slice §1.3 종료 조건에 다음을 추가 권장:
> **"데이터 손실 0회"** — F6-L1 출시 후 모든 dogfood 사이클에 대해 데이터 손실 사건 0회. 발생 시 즉시 silent invariant 위반으로 간주.
이 추가는 F6-L1 항목 머지 시 slice spec §1.3 동봉 수정.
---
## 7. 본 로드맵의 종료 조건
**모두 만족해야 종결**:
1. F1·F2·F3+F4-E·F5·F6-L1·F6-L3·F6-L2·F4-C·F 8개 항목 모두 main 머지
2. 8개 모두 dogfood-feedback.md 에서 🚀 promoted 상태 + 별 spec 파일 분기
3. `package.json description`, README, slice spec §5.5 카피 테이블, strategy.md §1·§3·§7 동봉 갱신 완료
4. v0.2.1 cut → dogfood 머신 재설치 → migration v2 적용 확인 → 첫 실행 정상 + 트레이 메뉴 6개 항목 (지금 백업·내보내기·복원·자동시작·구출·종료, 카피 변경 반영) 동작 확인
5. ≥ 1주 dogfood soak 완료 (데이터 손실 0회 확인)
5 가 끝나면 본 로드맵 종결, F4-A·D 별 brainstorm 진입.
---
## 8. 미결정 항목 (각 항목 시작 시 답변)
본 로드맵은 순서만 정의했고, 각 F-spec 의 결정 대기 슬롯은 항목 시작 시 mini-brainstorm 에서 답함. 본 문서는 그 결정들을 미리 잠그지 않음.
특히 **다음 결정들은 빨리 마주치게 됨**:
- F5: 포맷 1차안 확정 (one-file-per-note + frontmatter + index.jsonl 트리플 가정), 미디어 포함 기본값, embedding_text 합성 규칙
- F6-L1: 백업 위치 (profileDir 안 vs 별 디렉터리 vs 사용자 지정 외부)
- F1: false positive 처리, due 만료 시 시각 표시 정책, 라벨 슬롯 위치
- F3+F4-E: strategy.md §1·§3·§7 동반 갱신 범위, 단일 동사 통일 vs 표면별 분배
- F6-L2: 첫 설정 UX 부담 vs opt-in, repo 분리 (`-data` 별 repo)
- 모든 항목: CHANGELOG.md 신설 vs git tag 메시지 (8번 항목 직전 mini-brainstorm)
---
## 9. 변경 이력
| 일자 | 변경 |
|------|------|
| 2026-04-26 | 초안 — F1~F6 의 8개 항목 순차 로드맵, 데이터 안전 우선 (Option A), 머지+테스트 게이트 (Option A), 데이터 라이프사이클 우선 순서 (Option X), v0.2.1 단일 cut |