Electron 템플릿을 만든 뒤 가장 먼저 한 일은 화면을 예쁘게 만드는 일이 아니었다. 어떤 기능을 만들지, 어디까지를 MVP로 볼지, 보안 때문에 절대 허용하지 않을 것은 무엇인지 문서로 먼저 고정했다.
문서가 먼저였던 이유
Dock은 로컬 파일과 외부 검색 결과를 함께 다룬다. 이 조합에서는 ‘일단 UI부터 만들고 보안은 나중에’가 위험하다. Renderer에서 파일 시스템에 직접 접근하게 되거나, 검색 결과 HTML을 그대로 보여 주거나, 임의 IPC를 열어 두는 식의 편의가 나중에는 고치기 어려운 구조가 될 수 있다.
그래서 프로젝트의 기준 문서를 다음 순서로 만들었다.
| 분류 | 정의 및 핵심 내용 |
|---|---|
| PRODUCT RULE | 바꿀 수 없는 제품·구조·보안 원칙 |
| MVP 정의 | 대상 사용자와 필수 여정 |
| 아키텍처 기준 | Main / Preload / Renderer 책임 |
| 보안 기준 | Electron 보안 하한선 |
| 테스트 전략 | 무엇을 어떤 테스트로 검증할지 |
| 워크플로 | Phase와 종료 조건 |
| 현재 상태 기록 | 실제로 어디까지 왔는지 |
이 문서들은 ‘계획서’만이 아니다. 코드와 문서가 다를 때 무엇을 우선할지, 어떤 변경에 ADR 승인이 필요한지, 완료를 어떤 증거로 판단할지를 정한 작업 규칙이다.
제품을 작게 정의했다
처음부터 AI, 클라우드 동기화, 협업, 플러그인까지 넣으면 Dock이 무엇을 잘하는지 검증하기 어려워진다. MVP는 아래 두 가치를 모두 증명하는 범위로 제한했다.
로컬 Markdown을 안전하게 열고·편집하고·저장한다.
앱 안에서 링크와 이미지를 검색해 Markdown에 삽입한다.이 정의에서 중요한 단어는 ‘로컬’과 ‘사용자가 선택한다’다. 문서는 일반 .md 파일로 남고, 검색 결과는 자동 삽입하지 않으며, 외부 URL도 사용자 행동 없이 열지 않는다.
Electron은 세 개의 책임으로 나눈다
Dock의 앱 내부는 아래처럼 나눈다.
| 레이어 (Layer) | 책임 및 역할 (Responsibility) |
|---|---|
| Main | 창·파일·네트워크·IPC handler |
| Preload | Renderer에 공개할 좁은 API bridge |
| Renderer | React UI·편집기·미리보기·사용자 상호작용 |
| Shared | IPC 계약·직렬화 타입·runtime schema |
Renderer는 Node.js나 Electron을 직접 import하지 않는다. 대신 window.dock처럼 필요한 기능만 가진 API를 Preload에서 제공하고, 권한이 필요한 실제 작업은 Main에서 검증한 뒤 수행한다.
Renderer → window.dock → Preload → validated IPC → Main이 경계는 코드가 길어지게 하려는 규칙이 아니다. 악성 Markdown이나 조작된 화면이 임의 파일 접근·shell 실행·네트워크 요청으로 이어지지 않게 만드는 최소한의 방어선이다.
완료의 기준도 먼저 정했다
‘창이 열렸다’는 시작 신호이지 완료 증거가 아니다. Foundation 단계부터 아래처럼 검증 기준을 둔다.
- 타입 검사, lint, 포맷 검사
- Electron 개발 실행과 패키징
- 순수 로직 단위 테스트
- React 컴포넌트 테스트
- Preload/IPC 계약 테스트
- Electron E2E와 패키징 산출물 smoke test
테스트를 통과시키기 위해 sandbox, contextIsolation, Electron fuse를 약화하지 않는 것도 명시했다. 보안 옵션을 낮춘 테스트 성공은 성공이 아니라 기준 위반이다.
이번 단계에서 얻은 것
F0의 산출물은 기능 화면이 아니라 의사결정의 기준점이다. 이후 저장소 구조를 옮길 때도, React를 추가할 때도, 미래에 검색 공급자를 붙일 때도 ‘왜 이 구조인가’와 ‘무엇을 아직 하지 않는가’를 확인할 수 있게 됐다.
다음 글에서는 이 기준을 적용해 Electron 템플릿을 루트에서 apps/desktop으로 옮기고 npm workspace를 검증한 과정을 다룬다.
참고
