[TIL] Dock 개발 여정 (25) - 중간 QA

JARVIS Dock

20개가 넘는 개발 포스팅을 작성해오면서 텍스트와 Mermaid로 워크 플로우만 공유했지, 실제 어떤 제품을 개발하고 있는지 공유한 사항은 없었다.

• 어떤걸 만들고 있고
• 어떤 기능들이 어떻게 구현되어있는지
• 실제 화면은 어떻게 구성되어있는지

포스팅에 공유하고 개선되어가는 과정도 함께 공유하고자 한다.

JARVIS Dock Github Repository

중간 QA를 하면서 당연히 예외 상황에 대한 처리도 중요하지만, "실제 업무 상황에서 쓰인다면?" 이라는 전제를 깔았다.
해당 전제를 깔게 되면서 테스트를 진행하다보니 예외 상황에 대한 처리보다 성능적인 개선도 함께 포함 되어야 한다는걸 뼈저리게 느꼈다.

기능과 실사용 그 사이

Dock의 Workspace Explorer, 문서 충돌 보호, Markdown Preview, 이미지 삽입, Research View를 구현한 뒤 한 가지 질문이 남았다.

“지금까지 구현한 기능들이 예외 상황에서 정상적으로 동작하는가?”

단위 테스트와 Electron E2E가 통과했다는 의미의 동작과, 실제 사용자가 앱을 처음 열고 파일을 만들고 지우고 외부에서 수정하는 과정에서 불편 없이 사용할 수 있다는 의미의 동작은 같지 않다.

이번에는 C:\Users\user\Downloads\Dock를 실제 document workspace로 선택하고, 개발 중 만든 기능을 준비 단계부터 packaged 앱까지 순서대로 확인했다. 기준 commit은 다음과 같다.

Dock Repository: JARVIS Dock Github

검증 환경은 Windows 10 x64. 결과는 전체 PARTIAL이다. 대부분의 기능은 정상적으로 동작했지만, Explorer 생성 흐름과 새 문서 입력 검증, 이미지 삽입 위치 처리처럼 실제 사용성에 직접 영향을 주는 문제가 확인됐다.

이번 QA에서 지킨 원칙

이번 검증은 “버튼이 화면에 보이는가”만 확인하는 테스트가 아니었다. 사용자의 작업이 실제 파일에 반영되는지, 외부 변경으로 작업을 잃지 않는지, 실패했을 때 다음 행동을 알 수 있는지까지 확인했다.

결과 표기는 원래 체크리스트와 동일하게 사용했다.

• P: PASS
• F: FAIL
• B: BLOCKED
• N/A: 테스트 환경 또는 조건 없음

총 143개 항목의 결과는 다음과 같다.

판정	개수	의미
PASS	125	기대 결과와 일치
FAIL	6	실제 오류 또는 기대 결과와 불일치
BLOCKED	6	선행 실패 때문에 진행 불가
N/A	6	macOS·Linux 환경 부재

중요한 점은 PASS 개수가 많다는 사실보다, 실패한 항목이 어떤 사용자 흐름을 막고 있는지다.

0. 준비 단계

테스트 폴더를 백업 또는 복사본으로 준비하고 저장소 최신 상태를 확인했다. npm run dev로 최신 Dock을 실행했으며, 기존 Research View와 문서 탭을 닫은 상태에서 테스트를 시작했다.

상태	확인 항목
P	테스트 폴더 백업 또는 복사본 준비
P	저장소 최신 상태 확인
P	npm run dev로 최신 Dock 실행
P	기존 Research View와 문서 탭 닫기
P	테스트 시작 시각 기록: 2026-08-30 21:46

출발 조건은 정상적이었다. 이후 결과는 특정 이전 화면이나 남아 있던 문서 상태에 의존하지 않는다.

1. 폴더 선택과 초기 Explorer

폴더 선택으로 C:\Users\user\Downloads\Dock 선택하고 실제 디렉터리와 Dock의 Explorer 트리를 비교했다.

상태	확인 항목	실제 결과
P	폴더 선택으로 테스트 폴더 선택	정상
P	실제 폴더 구조와 Dock Explorer 목록 일치	정상
P	파일 아이콘과 폴더 아이콘 표시	정상
P	폴더 펼침·접힘 아이콘이 문자 기호가 아닌 아이콘으로 표시	정상
P	폴더 접기 후 Editor가 확장	정상
P	폴더 펼치기 후 Explorer·Editor·Preview가 겹치지 않음	정상
F	작은 창 크기에서도 가로 overflow 없음	가로 overflow는 없었지만 Document Workspace에 스크롤 발생

마지막 항목은 해석이 필요하다. 원래 체크 항목은 가로 overflow를 확인하는 내용이므로 그 조건만 보면 문제가 없었다. 하지만 사용자가 작은 창에서 문서를 작성할 때 Document Workspace에 예상하지 못한 스크롤이 생기는 것은 별도의 UX 문제다.

따라서 이 항목은 순수한 CSS overflow 결함이라기보다 작은 창에서 최소 크기와 내부 스크롤 정책이 명확하지 않다는 레이아웃 문제로 분류했다.

검토 방향은 세 가지다.

• 앱의 최소 창 크기를 정하고 그 이하에서는 창 확대를 안내한다.
• 전체 레이아웃의 스크롤과 Document Workspace 내부 스크롤을 분리한다.
• 작은 창 전용으로 Explorer 헤더·목록·Editor 영역의 높이 배분을 조정한다.

2. Dock 외부 파일·폴더 동기화

이번 단계의 목적은 Windows 파일 탐색기에서 파일과 폴더를 바꿨을 때 Dock이 재실행 없이 실제 디렉터리 상태를 따라오는지 확인하는 것이었다.

상태	확인 항목	실제 결과
P	external.md 생성 후 Dock Explorer에 자동 표시	정상
P	external.md를 Dock에서 열기	정상
P	파일 내용을 정상적으로 읽기	정상
P	external.md를 renamed.md로 변경	정상
P	기존 이름이 Dock에서 사라짐	정상
P	새 이름이 Dock에 표시됨	정상
P	renamed.md 삭제 후 Dock에서 자동 제거	정상
F	notes 폴더 생성 후 Dock에 자동 표시	테스트 메모상 Dock 내부 + 폴더 버튼 무반응
B	notes/nested.md 생성 후 중첩 항목 표시	폴더 생성 실패로 진행 불가
B	notes 폴더 삭제 후 폴더와 내부 파일이 모두 제거	폴더 생성 실패로 진행 불가
P	Dock 재실행 없이 모든 변경이 반영	파일 변경 흐름에서는 정상

여기서 테스트 절차의 구분이 중요하다. 이 섹션은 Windows 파일 탐색기에서 notes 폴더를 만들어 native watcher가 감지하는 흐름이어야 한다. 그러나 Dock 내부의 [+ 폴더], [+ 파일] 버튼을 클릭했을 때 아무런 상호작용이 없었다.

따라서 다음 두 가지를 분리해서 봐야 한다.

1. 외부 파일 생성·이름 변경·삭제 동기화는 실제로 통과했다.
2. 외부 폴더 생성 동기화는 절차가 정확히 수행되지 않아 아직 검증하지 못했다.

이 문제를 수정한 뒤에는 Windows 파일 탐색기에서 notes를 직접 생성하고, Dock에서 중첩 파일 표시와 폴더 삭제까지 다시 확인해야 한다.

3. Explorer 내부 CRUD

이번 QA에서 가장 큰 기능 결함이 발견된 구간이다. 이름 변경과 삭제는 동작했지만, Explorer 상단과 컨텍스트 메뉴의 새 파일·새 폴더 생성 흐름이 동작하지 않았다.

파일·폴더 생성

상태	확인 항목	실제 결과
F	Explorer의 + 파일로 new.md 생성	버튼 클릭 후 무반응
B	생성된 파일이 자동으로 Editor에서 열림	파일 생성 실패로 진행 불가
F	Explorer의 + 폴더로 drafts 생성	버튼 클릭 후 무반응
B	drafts 안에 draft.md 생성	폴더 생성 실패로 진행 불가

이름 변경

상태	확인 항목	실제 결과
P	파일 더블클릭 시 행 내부 입력창 표시	정상
P	새 이름 입력 후 Enter로 저장	정상
P	실제 파일 이름 변경	정상
P	Escape로 이름 변경 취소	정상
P	폴더 이름도 inline 방식으로 변경	정상

컨텍스트 메뉴

상태	확인 항목	실제 결과
P	파일에서 마우스 오른쪽 클릭 시 메뉴 표시	정상
P	폴더에서 마우스 오른쪽 클릭 시 메뉴 표시	정상
F	새 파일 실행	실행 후 무반응
F	새 폴더 실행	실행 후 무반응
P	이름 변경 실행	정상
P	삭제 실행	정상

오류·삭제

상태	확인 항목	실제 결과
B	동일한 이름의 파일 생성 시 오류 표시	파일 생성 진입 실패로 확인 불가
B	동일한 이름의 폴더 생성 시 오류 표시	폴더 생성 진입 실패로 확인 불가
P	잘못된 이름 입력 시 오류 표시	정상
P	이름 변경 실패 시 입력 내용 유지	정상
P	삭제 취소 시 실제 항목 유지	정상
P	삭제 확인 시 실제 항목 삭제	정상
P	폴더 삭제 시 내부 항목도 삭제	정상

이름 변경 자체는 작동했지만, 중복 이름 오류 메시지의 위치와 여백이 어색했다. 더 중요한 문제는 오류가 이름 변경 종료 후에도 계속 남아 있다는 점이다. 오류는 작업 단위의 상태로 관리하고, 이름 변경이 취소되거나 정상적으로 종료되면 해당 오류를 제거해야 한다.

별도의 [새 문서 생성] 흐름은 다음과 같이 확인됐다.

• 현재 존재하는 폴더 이름을 새 문서 경로로 입력하면 정상적으로 생성된다.
• 중복 이름을 입력해도 오류 메시지가 표시되지 않는다.
• 존재하지 않는 경로를 입력하면 생성되지 않지만 사용자에게 아무런 안내가 없다.

즉, Explorer의 생성 버튼 무반응과 새 문서 생성 폼의 입력 검증 부족은 서로 다른 문제다. 전자는 이벤트 연결 또는 UI 진입 흐름을 먼저 복구해야 하고, 후자는 Main의 오류를 Renderer가 사용자 메시지로 매핑해야 한다.

4. 저장된 문서의 외부 변경

저장된 guide.md를 열고 Windows 파일 탐색기에서 내용을 변경하거나 삭제했다.

상태	확인 항목
P	저장된 guide.md 열기
P	Editor가 저장 상태인지 확인
P	Windows 파일 탐색기에서 guide.md 내용 변경
P	Dock Editor에 외부 내용 자동 반영
P	변경된 파일의 Explorer 상태 정상
P	저장된 문서를 외부에서 삭제
P	Dock에서 문서가 자동으로 닫힘

저장된 문서는 외부 변경을 그대로 반영해도 사용자의 미저장 작업을 잃을 위험이 없기 때문에 자동 동기화가 가능하다. 이 흐름은 기대대로 동작했다.

5. 미저장 문서의 외부 변경 충돌

문서 내용을 수정한 뒤 저장하지 않고 외부 파일을 바꿔 충돌 상태를 만들었다.

충돌 감지와 보호

상태	확인 항목
P	guide.md 열기
P	Editor 내용 변경
P	저장하지 않은 상태에서 외부 파일 내용 변경
P	충돌 안내 표시
P	Editor의 미저장 내용 유지
P	외부 내용으로 자동 덮어쓰기되지 않음
P	외부 변경 불러오기 버튼 표시
P	내 작업으로 저장 버튼 표시
P	문서 닫기 버튼 표시

외부 변경 불러오기

상태	확인 항목
P	외부 변경 불러오기 클릭
P	외부 내용이 Editor에 표시
P	충돌 안내 제거
P	저장 상태 정상화

내 작업으로 저장

상태	확인 항목
P	Editor 내용 재수정
P	외부 파일을 다시 변경해 충돌 발생
P	내 작업으로 저장 클릭
P	실제 파일 내용이 Editor 내용과 일치
P	저장 상태가 저장됨으로 변경

문서 닫기

상태	확인 항목
P	미저장 변경 후 외부 변경 발생
P	문서 닫기 클릭
P	문서 탭과 Editor에서 문서 제거
P	충돌 안내 제거

핵심 보호 규칙은 지켜졌다. Dock은 미저장 내용을 외부 파일 내용으로 자동 덮어쓰지 않았고, 사용자가 선택한 뒤에만 외부 내용을 불러오거나 자신의 작업을 저장했다.

다만 외부 변경 내용을 불러왔습니다. 메시지는 문서 전환을 해야 사라졌다. 성공 메시지는 일정 시간 후 자동 제거하거나, 동일 작업이 종료되는 즉시 제거하는 편이 자연스럽다.

6. 미저장 문서 외부 삭제·이름 변경

문서를 편집한 상태에서 외부에서 삭제하거나 이름을 변경해 복구 흐름을 확인했다.

삭제 후 복구 저장

상태	확인 항목
P	guide.md 열기
P	내용을 수정하고 저장하지 않음
P	파일 탐색기에서 guide.md 삭제
P	충돌 안내 표시
P	미저장 내용 유지
P	내 작업으로 저장 클릭
P	원래 경로에 guide.md 재생성
P	파일 내용이 미저장 Editor 내용과 일치

외부 이름 변경

상태	확인 항목
P	새 테스트 문서 열기
P	내용을 수정하고 저장하지 않음
P	파일 탐색기에서 문서 이름 변경
P	충돌 안내 표시
P	미저장 내용 유지
P	문서 닫기 또는 내 작업으로 저장 동작 확인

외부에서 파일이 사라져도 미저장 작업을 버리지 않고 원래 경로에 다시 저장할 수 있었다. 별도 개선 의견으로 Ctrl + S 저장 단축키가 남았다. 현재 저장 버튼을 직접 누르는 흐름은 정상이나, 문서 편집기의 기본 기대 동작을 만족하려면 단축키를 제공하는 편이 좋다.

7. Editor·Preview 회귀

긴 Markdown 문서와 이전에 문제가 발생했던 표·인용문·Mermaid 문서를 사용해 Editor와 Preview의 회귀 여부를 확인했다.

상태	확인 항목
P	긴 Markdown 문서에서 Editor 자체 스크롤 동작
P	Preview 자체 스크롤 동작
P	Editor와 Preview가 서로 겹치지 않음
P	Markdown 표가 정상 렌더링
P	인용문 >의 간격과 디자인 확인
P	코드 하이라이트 표시
P	Mermaid 다이어그램 표시
P	긴 Mermaid 다이어그램이 Preview 영역 밖으로 튀어나오지 않음
P	문서 탭과 Editor 헤더 사이 여백 확인
P	창 크기 변경 후 레이아웃 유지

기능 회귀는 없었다. 다만 창 크기를 변경하는 동안 일부 렉이 관찰됐다. Preview가 Markdown을 다시 파싱하고 코드 하이라이트와 Mermaid를 다시 렌더링하는 과정에서 리소스가 발생하는 것으로 추정된다.

이 관찰은 단순한 CSS 문제로 단정하지 않는다. 다음 최적화 Job에서 렌더링 시간, Preview 재계산 횟수, Mermaid 재생성 횟수, Main과 Renderer 메모리를 측정해 원인을 분리해야 한다.

8. 이미지 기능 회귀

이미지 검색, 다운로드, 로컬 저장, Markdown 삽입, Preview, 클립보드, 원본 삭제 흐름을 확인했다.

상태	확인 항목
P	/image 실행
P	검색 결과 카드에 썸네일 표시
P	이미지 출처·라이선스 표시
P	이미지 선택 후 assets/에 원본 저장
P	Markdown 이미지 문법 삽입
P	Preview에서 이미지 렌더링
P	캡처 이미지를 클립보드에 복사
P	Editor에 붙여넣기
P	클립보드 이미지가 assets/에 저장
P	클립보드 이미지 Preview 렌더링
P	본문 이미지 참조 삭제 후 저장
P	원본 삭제 확인창 표시
P	삭제 취소 시 원본 유지
P	삭제 확인 시 원본 삭제

기본 흐름은 통과했지만 결과를 그대로 PASS로 확정하기 어려운 조건이 하나 있다.

Editor에 커서를 둔 상태로 이미지 검색을 실행하면 이미지가 정상적으로 다운로드되고 Markdown도 삽입된다. 그러나 커서가 없는 상태에서 검색하면 assets/에 원본만 저장되고 Markdown 참조는 삽입되지 않는다.

이 상태는 사용자에게 “이미지를 넣었다”는 인상을 주지만 실제 문서에서는 이미지를 참조하지 않는다. 결과 파일만 남는 고아 asset이 생길 수 있으므로 PARTIAL PASS로 재분류하는 것이 정확하다.

다음 중 하나를 제품 규칙으로 정해야 한다.

• 마지막 Editor selection을 복원해 그 위치에 삽입한다.
• 커서가 없으면 다운로드 전에 삽입 위치를 안내한다.
• 커서가 없으면 다운로드를 실행하지 않고 Editor 포커스를 요청한다.

개인적으로는 마지막 selection 보존을 우선 검토할 만하다. 검색 창이나 Research View를 여는 순간 Editor의 selection이 사라지는 것은 자연스러운 UI 동작이기 때문에, 검색을 시작할 때 selection을 기억해 두고 다운로드 성공 후 복원하는 방식이 사용자의 기대와 가장 잘 맞는다.

이미지 검색 provider를 Wikimedia Commons 외로 확장하는 의견도 있었지만, 이는 현재 결함 수정과 분리된 별도 provider 검토 과제다.

9. Research View

Google 검색은 반복 요청에서 Sorry 차단이 발생할 수 있으므로 한 세션에서 최소한으로 확인했다. User-Agent 변경이나 사용자 Chrome 프로필 복제는 적용하지 않았다.

상태	확인 항목
P	/link 실행
P	Research View 표시
P	상단바에 현재 URL 표시
P	새로고침 버튼 표시
P	중지 버튼 표시
P	닫기 버튼 표시
P	상단바와 WebView 사이 여백·구분선 표시
P	Research View가 Editor를 덮지 않음
P	검색 결과 카드 표시 여부 기록
P	카드 클릭 시 현재 Editor 커서 위치에 링크 삽입
P	카드가 없을 때 현재 페이지 링크 삽입
P	Sorry 페이지에서도 fallback 동작
P	새 창·새 탭 링크가 Research 탭으로 추가
P	명령 팔레트가 Research View 아래로 깔리지 않음

검색 결과 기록은 다음과 같다.

검색어: python
표시된 URL: https://www.google.com/search?q=python
카드 표시 여부: Y
Sorry 표시 여부: Y
fallback 동작: Y

여기서 Sorry가 표시됐다는 사실과 Dock의 Research View 동작이 통과했다는 사실은 동시에 성립할 수 있다. Google이 차단 응답을 보냈지만, Dock은 Research View를 표시했고 현재 페이지 링크 fallback도 수행했다. 따라서 앱의 fallback·레이아웃·삽입 경계는 PASS지만, Google 검색 결과의 안정적인 제공은 여전히 외부 환경에 종속된 제한 사항이다.

처음 실행하는 별도 머신에서도 동일한 현상이 발생하는지 추가 확인할 필요가 있다. 다만 User-Agent 위조나 실제 Chrome 프로필·쿠키 복제로 차단을 우회하는 방식은 현재 보안·제품 결정상 적용하지 않는다.

10. Packaged 앱 최종 확인

개발 서버가 아닌 packaged 실행 파일을 사용해 최종 동작을 확인했다.

상태	확인 항목
P	npm run test:smoke 통과
P	npm run make 통과
P	apps/desktop/out/Dock-win32-x64/Dock.exe 실행
P	Dock 창 표시
P	Explorer 아이콘·트리 표시
P	Editor·Preview 레이아웃 정상
P	Research View 표시 시 다른 UI를 덮지 않음
P	충돌 안내 UI 표시
P	창 크기 변경 후 레이아웃 유지
P	앱 정상 종료

Windows packaged 앱에서는 개발 환경에서만 발생하는 동작 차이를 발견하지 못했다.

11. 플랫폼별 확인

상태	확인 항목	결과
P	Windows GUI 확인	완료
N/A	macOS GUI 확인	테스트 환경 없음
N/A	macOS native folder dialog 확인	테스트 환경 없음
N/A	macOS fs.watch 외부 변경 확인	테스트 환경 없음
N/A	Linux GUI 확인	테스트 환경 없음
N/A	Linux native folder dialog 확인	테스트 환경 없음
N/A	Linux fs.watch 외부 변경 확인	테스트 환경 없음

N/A는 실패가 아니라 미검증이다. 그러나 릴리스 후보를 선언하려면 지원 플랫폼의 실제 GUI 동작과 native folder dialog, 파일 변경 감시를 별도로 확인해야 한다.

무엇이 실제 결함이고, 무엇이 다음 개선인가

QA 메모를 모두 기능 결함으로 취급하면 우선순위가 흐려진다. 이번 결과는 다음처럼 나누는 것이 정확하다.

즉시 수정해야 하는 결함

1. Explorer + 파일, + 폴더 버튼 무반응
2. 컨텍스트 메뉴의 새 파일, 새 폴더 무반응
3. 새 문서 생성 시 중복 이름·존재하지 않는 경로에 대한 오류 안내 부재
4. Editor selection이 없을 때 이미지가 파일만 저장되고 Markdown에는 삽입되지 않는 문제

기능은 통과했지만 UX 개선이 필요한 항목

1. 작은 창에서 Document Workspace에 발생하는 스크롤 정책
2. 이름 변경 오류 메시지의 위치·여백과 종료 후 잔존
3. 외부 변경 불러오기 성공 메시지의 제거 시점
4. Ctrl + S 저장 단축키
5. 이미지 검색 카드 UI와 provider 확장성

환경 또는 외부 서비스에 의존하는 항목

1. Google Sorry 응답의 재현성과 첫 실행 머신 확인
2. macOS GUI와 native folder dialog
3. Linux GUI와 native folder dialog

별도 Job으로 분리한 항목

창 크기 변경 중 렉과 대용량 저장소 선택 시 메모리 급증은 “느낌이 조금 느리다” 수준으로 넘길 문제가 아니다. 현재 구조에서는 다음 작업이 동시에 일어날 수 있다.

• 전체 document workspace 재귀 탐색
• Markdown 파일 목록 조회
• Explorer entry 목록 조회
• 디렉터리별 native fs.watch 등록
• 전체 Explorer 트리 렌더링
• Preview Markdown 파싱과 Mermaid·코드 하이라이트 재계산

특히 node_modules, out처럼 수만 개 파일과 하위 디렉터리를 가진 저장소를 선택하면 탐색 대상, watcher, React 노드가 한꺼번에 늘어난다. 그래서 QA가 끝난 뒤 Job: Dock 앱 최적화로 분리했다.

수정 순서

수정은 다음 순서가 적절하다.

1단계: Explorer 생성 흐름 복구

먼저 상단의 + 파일, + 폴더와 컨텍스트 메뉴의 새 파일, 새 폴더가 동일한 생성 함수를 호출하는지 확인한다. 버튼 이벤트가 연결됐는지, 생성 대상 경로가 현재 선택된 디렉터리로 전달되는지, 생성 성공 후 목록 갱신과 Editor 자동 열기가 이어지는지 분리해서 검증한다.

2단계: 오류 반환과 사용자 메시지 정리

새 문서 생성과 Explorer 생성에서 다음 결과를 명확한 메시지로 보여줘야 한다.

• 중복 파일·폴더
• 존재하지 않는 부모 경로
• 잘못된 이름
• 권한 부족
• 저장 또는 목록 갱신 실패

오류 메시지는 Main의 실제 실패 이유를 그대로 노출하지 않고, 사용자 행동으로 번역해야 한다. 이름 변경이 종료되면 이전 이름 변경 오류도 제거해야 한다.

3단계: 이미지 삽입 위치 보존

이미지 검색을 시작하는 시점에 Editor의 selection과 문서 경로를 보존한다. 검색과 다운로드가 성공한 뒤에도 문서가 같은 상태인지 확인하고, 안전한 경우에만 기존 selection에 Markdown을 삽입한다. 삽입할 위치가 사라졌다면 파일만 남기지 말고 사용자에게 명확히 알려야 한다.

4단계: 회귀 QA

수정 후에는 실패한 항목만 보는 것이 아니라 다음을 다시 확인해야 한다.

• Explorer 내부 생성과 컨텍스트 메뉴
• 외부 폴더 생성·중첩 파일·삭제 동기화
• 새 문서 오류 검증
• 이미지 검색과 커서 위치 삽입
• 기존 문서 충돌 보호
• Packaged 앱 실행

이 회귀가 끝난 뒤에야 수동 QA Exit Gate를 다시 판정할 수 있다.

다음 Job: Dock 앱 최적화

성능 최적화는 QA 결과에 대한 즉흥적인 setTimeout이나 무조건적인 .gitignore 적용으로 시작하지 않는다. 먼저 현재 구현의 비용을 측정해야 한다.

착수 시 확인할 기준은 다음과 같다.

• 초기 workspace 선택부터 첫 Explorer 표시까지의 시간
• 재귀 탐색 파일·디렉터리 수
• 등록된 watcher 수
• Main과 Renderer의 메모리 사용량
• Preview 재계산 횟수와 Mermaid 재생성 횟수
• 창 크기 변경 중 UI 응답성

그 다음 아래 정책을 결정한다.

• .git, node_modules, out, .vite, dist, build, coverage, test-results, playwright-report, .cache 같은 기본 제외 디렉터리
• .gitignore를 탐색 힌트로 사용할지 여부
• .gitignore에 포함됐더라도 사용자가 봐야 하는 docs/ 같은 문서 폴더의 가시성
• ! negation과 중첩 .gitignore를 어느 수준까지 지원할지

.gitignore는 곧 “Dock에서 숨길 파일 목록”이 아니다. Git 저장소에서 추적하지 않는다는 의미와 사용자가 문서 앱에서 열람하지 않아야 한다는 의미는 다르다. 예를 들어 이 저장소의 docs/는 Git 기준에서는 ignore 대상이지만 Dock에서는 사용자가 반드시 확인해야 하는 문서 workspace가 될 수 있다.

구현 후보는 하나만 선택할 필요가 없다.

• 한 번의 탐색 결과를 Markdown 목록과 Explorer가 함께 사용하도록 중복 스캔 제거
• 폴더를 펼칠 때만 자식 항목을 조회하는 지연 로딩
• 변경된 디렉터리만 갱신하는 증분 탐색
• 모든 디렉터리에 watcher를 두지 않고 감시 범위를 줄이는 방식
• Preview가 실제로 변경됐을 때만 파싱·렌더링하는 방식

이 Job의 완료 조건은 “메모리가 줄었다”가 아니다. 최적화 전후 측정값으로 원인을 설명하고, Downloads/Dock의 일반 문서 흐름을 훼손하지 않으며, 대용량 workspace에서도 초기 화면과 Explorer가 응답하는지 회귀 테스트로 확인하는 것이다.

마무리

이번 QA를 통해 Dock은 핵심 문서 편집 흐름과 외부 파일 변경 보호를 안정적으로 수행한다는 것을 확인했다. 동시에 실제 사용성은 자동 테스트의 녹색 결과만으로 완성되지 않는다는 것도 확인했다.

특히 다음 세 가지가 이번 QA의 핵심 결과다.

1. Explorer 생성 버튼은 화면에 존재하는 것과 실제로 사용할 수 있는 것이 달랐다.
2. 이미지 검색은 다운로드 성공과 문서 삽입 성공을 같은 결과로 취급하면 안 된다.
3. 대용량 workspace와 Preview 렌더링 비용은 기능 QA 이후 별도 성능 작업으로 다뤄야 한다.

현재 Dock은 릴리스 완료가 아니라, 실패 항목을 수정하고 회귀 검증을 다시 진행해야 하는 상태다. QA는 끝났지만 Exit Gate는 아직 열려 있다. 다음 목표는 기능을 더 추가하는 것이 아니라, 이번에 실제로 드러난 결함을 닫고 사용자가 실패 상황에서도 다음 행동을 알 수 있게 만드는 것이다.