Add tech stack and version policy section to vertical slice spec

Pin Node 24 LTS (Krypton) as runtime. Document latest-stable-major
policy for dependencies with initial pin candidates as of 2026-04-24,
and .nvmrc-based version synchronization for dev/CI.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-04-24 19:15:32 +00:00
parent bbbe292fc6
commit e22194bf39

View File

@@ -462,12 +462,57 @@ Slice는 온보딩 위자드를 제공하지 않는다.
---
## 7. 오픈 이슈 / 차기 spec으로 이관
## 7. 기술 스택과 버전 정책
### 7.1 버전 정책
- **Node.js:** 최신 LTS 고정. 구현 시작 시점 기준 **v24.x (Krypton, Latest LTS)**.
- **라이브러리·프레임워크:** 각 의존성의 최신 안정(stable) 메이저를 기본값으로 사용. 의도적 구버전 고정이 필요한 경우(보안 이슈, 알려진 regression 등) 이 문서 하단 §7.3 이슈 로그에 사유 기록.
- **pre-release·RC 금지:** alpha/beta/rc 태그 의존성은 허용하지 않는다. 단, Electron 내부 Chromium/Node 조합에 한해서는 Electron이 번들한 버전을 그대로 사용한다(별도 pin 불가).
- **버전 고정 방법:** `package.json`은 `^` 프리픽스 없이 정확한 버전으로 pin(`"electron": "41.3.0"` 형태). 업그레이드는 PR 단위 명시적 작업으로만 수행.
- **Node 버전 동기화:** 저장소 루트에 `.nvmrc`(예: `24.15.0`) 파일을 둔다. CI·로컬 개발자 모두 `nvm use`로 동일 버전 사용.
### 7.2 초기 pin 후보 (구현 시작 시점에 최신값 재확인)
| 역할 | 패키지 | 메이저 | 비고 |
|------|--------|--------|------|
| 런타임 | Node.js | 24 LTS | `.nvmrc`로 minor까지 고정 |
| 데스크톱 셸 | `electron` | 41 | Chromium + Node 번들 |
| UI | `react`, `react-dom` | 19 | Concurrent features 사용 자유 |
| 언어 | `typescript` | 6 | `strict: true` |
| 상태 관리 | `zustand` | 5 | |
| DB | `better-sqlite3` | 12 | 동기 드라이버 |
| 스키마 검증 | `zod` | 4 | AI 응답 파싱 |
| 단위/통합 테스트 | `vitest` | 4 | |
| E2E | `@playwright/test` | 1.59 | Electron support 포함 |
| HTTP mock (테스트) | `undici` | 8 | |
| 패키징 | `electron-builder` 또는 `electron-forge` | 미정 | §8 오픈 이슈 |
> 실제 `npm install` 시점에 `npm view <pkg> version`으로 최신값을 다시 확인하여 `package.json`에 기록한다. 위 표의 메이저 번호는 2026-04-24 기준 참고값이며, 구현 착수일에 더 높은 stable 메이저가 있으면 그것을 채택한다.
### 7.3 업그레이드 관리
- 의존성 업그레이드는 **메이저 단위로 일괄**이 아닌 **패키지 단위 독립 PR**로 수행한다.
- Electron 메이저 업그레이드는 Chromium·Node 동반 상승을 수반하므로 별도 smoke 체크리스트 재수행을 강제한다.
- `npm outdated`를 월 1회 리뷰하며, 보안 경고(`npm audit`)는 발견 즉시 처리.
### 7.4 개발 환경 전제
- Windows 개발 머신에 **nvm-windows** 또는 **Volta**로 Node 24 LTS 설치. macOS/Linux는 **nvm** 사용.
- 저장소 최초 체크아웃 흐름:
1. `nvm install` → `.nvmrc` 기반 설치·활성화.
2. `npm ci` → 락파일에 고정된 정확한 트리 복원.
3. 구현 착수 시점의 실제 버전이 §7.2 표와 어긋나면 이 문서를 PR로 갱신한다.
---
## 8. 오픈 이슈 / 차기 spec으로 이관
- **단축키 충돌 시 변경 UI**: 설정 화면이 slice에 없으므로 FAQ/환경 변수로 임시 대응. 후속 spec에서 정식 설정 UI로 해결.
- **AI 결과 수동 재처리 버튼**: dogfood 중 프롬프트 튜닝 편의가 필요하면 개발자 전용 debug 메뉴로 먼저 도입 검토.
- **Gemma 4 모델 가용성**: 설계 시점(2026-04) 공식 체크포인트 상태를 별도 확인. 미출시면 `gemma3:9b` 등 동세대 대체 모델로 임시 운용하고 스펙을 업데이트.
- **Electron 패키징 옵션 결정**: `electron-builder` vs `electron-forge`. Slice 바이너리는 dev 빌드로 충분하므로 후속 배포 spec에서 결정.
- **Node 24 LTS → 이후 LTS 전환**: Node 24 Maintenance 진입 시점(로드맵상 2027년대)에 다음 짝수 메이저로 이관. 시점 도래 시 별도 spec.
---