TL;DR
- 혼자 쓰는 플래너를 단일 HTML 페이지에서 SvelteKit 앱으로 AI와 함께 옮겼다.
- 첫 이주가 끝났을 때 옛 페이지와 비교해 보니 빠진 기능이 9개, 동작이 바뀐 기능이 9개였다.
- 옛 코드에서 동작 목록을 뽑고, 그 목록을 spec-kit 스펙으로 바꾼 뒤 스펙대로 다시 개발했다.
- UI는 달라졌지만 동작은 그대로 남았고, 그 확인이 끝난 다음에야 옛 코드를 지웠다.
AI로 앱을 다시 만들면 왜 기능이 빠질까?
AI에게 "옛 페이지를 새 프레임워크로 옮겨 줘"라고 하면 눈에 보이는 화면은 잘 옮기지만, 화면에 드러나지 않는 작은 동작은 빠뜨린다. 그 동작이 코드 어딘가에만 있고, 사람도 AI도 목록으로 갖고 있지 않기 때문이다.
내 플래너는 src/js 아래 23개 파일로 된 단일 HTML 페이지였다. 이걸 SvelteKit + TypeScript + Supabase 앱으로 다시 만들었다. 탭 다섯 개(오늘·일정·할 일·기록·브레인)가 다 떴고 테스트도 통과했다. 그런데 며칠 쓰다 보니 손에 익은 것들이 없었다.
- 일정에서 날을 누르면 대화창이 뜨고 ← → 키로 전날·다음 날로 넘어갔는데, 새 앱에서는 달력 아래 패널로 바뀌었고 키가 먹지 않았다.
- 마지막으로 본 탭을 기억해서 다음에 그 탭으로 열어 주던 동작이 없었다.
- 문제를 해결했다고 적으면 예전 로그의
다음에 이어서:줄을후속(완료 M/D):로 바꿔 주던 동작이 없었다. - 방금 넣은 항목 목록, 영역 숨기기, 브레인 그래프 노드 더블클릭으로 고정 풀기도 빠져 있었다.
하나하나는 작다. 하지만 매일 쓰는 도구에서는 이런 작은 동작이 손에 익은 사용감을 만든다. 새 앱에서 빠졌다는 것도 써 보기 전에는 몰랐다.
빠진 기능은 어떻게 찾았나?
옛 코드에서 "이 앱이 하는 일"을 탭별 표로 뽑아서 찾았다. 표의 열은 네 개다.
| 동작 | 옛 위치 | 새 앱 위치 | 상태 |
|---|---|---|---|
| 날을 누르면 대화창, ← → 키로 전날·다음 날 | 06 openDay |
달력 아래 패널, 화살표 링크(키 없음) | ⚠️ |
| 영역 숨기기 + "숨긴 영역" 다시 보이기 | 09 setAreaHidden |
없음 | ❌ |
| 최근 추가한 것 목록(어디에 넣었는지·이유) | 05 addLog |
토스트로만 | ❌ |
상태는 ✅ 옮김, ⚠️ 바뀜, ❌ 빠짐, — 일부러 뺌 네 가지로 나눴다. AI에게 옛 파일을 하나씩 읽혀 동작을 적게 하고, 새 앱에서 같은 동작이 어디 있는지 찾게 했다. 이 파일(BEHAVIORS.md)을 처음 만든 날 ❌가 9개, ⚠️가 9개 나왔다.
여기서 중요한 건 "옛 위치" 열이다. 함수 이름까지 적어 두니 "정말 옛 앱에 있었나?"를 코드로 바로 확인할 수 있었다. 기억에 기대지 않아도 됐다.
동작 목록을 어떻게 스펙으로 바꿨나?
동작 목록을 그대로 spec-kit의 기준선 스펙으로 옮겼다. spec-kit은 GitHub이 공개한 스펙 주도 개발(Spec-Driven Development, SDD) 도구로, specify → plan → tasks → implement 순서로 스펙에서 코드까지 내려간다.
옛 코드 (src/js 23개 파일)
│ AI가 읽고 동작을 뽑음
▼
BEHAVIORS.md (탭별 동작 · 옛 위치 · 새 위치 · ✅⚠️❌)
│ 탭별로 묶음
▼
specs/001-common … 006-brain (사용자 이야기 · FR · 남은 일)
│ ❌·⚠️ 줄만 모아 새 스펙
▼
specs/010-restore-old-features (FR-001 ~ FR-006)
│ /speckit-plan → tasks → implement
▼
새 앱에 되살림 → 옛 코드 삭제
먼저 원칙 5개를 constitution.md에 적었다. "나 혼자 쓴다", "데이터를 잃지 않는다" 같은 것들이다. 그다음 탭마다 기준선 스펙(001~006)을 만들었다. 각 스펙에는 사용자 이야기와 기능 요구사항(Functional Requirement, FR), 그리고 아직 남은 일로 ❌·⚠️ 줄이 들어갔다.
되살릴 기능은 따로 스펙 하나(010-restore-old-features)로 묶었다. 입력은 내가 한 말 한 줄이었다. "옛 페이지와 달라진 것들이 많은 듯. 특히 일정에서 일정 클릭하면 모달 형식으로 떴었는데." 여기에 기준선 스펙의 ❌·⚠️ 줄을 붙이니 FR이 6개 나왔다.
- FR-001: 일정 날 →
<dialog>창, ← → 키, 바깥·✕·Esc로 닫기 - FR-002: 이 기기에서 마지막으로 본 탭 기억
- FR-003: 해결 등록 뒤 최근 14일 로그의
다음에 이어서:를후속(완료 M/D):로 바꾸고 되돌리기 - FR-004: 방금 넣은 것 목록(최대 30개, 5개 보이기)
- FR-005: 영역 숨기기·보이기(서버 설정에 저장)
- FR-006: 일일 요약 폴더 링크, 브레인 더블클릭 고정 풀기, 끊긴 링크 더 보기
이 스펙으로 구현한 커밋 하나가 24개 파일, 401줄 추가였다. 그 커밋을 배포한 뒤 같은 날 옛 페이지 코드를 지웠다.
UI가 달라져도 동작이 같다는 건 어떻게 확인했나?
화면이 아니라 동작 목록으로 확인했다. 새 앱은 Tailwind로 다시 그려서 색도 배치도 옛 페이지와 다르다. 그래서 스크린샷 비교는 쓸 수 없었다. 대신 "날을 누르면 창이 뜨고 ← → 키가 먹는가"처럼 동작 단위로 ✅를 채웠다.
지금 BEHAVIORS.md에는 ✅가 86줄이고, 남은 것은 ❌ 1줄(테마 고르기)과 ⚠️ 2줄이다. 남은 줄도 "왜 바뀌었는지"가 적혀 있어서, 일부러 다르게 둔 것인지 빠뜨린 것인지 헷갈리지 않는다.
이 파일은 이주가 끝난 뒤에도 쓴다. 프로젝트 규칙에 "동작을 더하거나 바꾸거나 빼면 같은 커밋에서 그 줄을 고친다"를 넣었다. AI가 다음 기능을 만들 때도 이 목록과 스펙을 먼저 읽으니, 있던 동작을 모르고 지우는 일이 줄어든다.
검토한 대안
1안: AI에게 "옛 페이지 그대로 옮겨 줘"라고 맡기기 (버림)
처음 이주가 사실상 이 방식이었다. 탭과 큰 기능은 다 옮겨졌지만 작은 동작 9개가 빠지고 9개가 바뀌었다. 무엇이 빠졌는지 AI도 나도 몰랐다는 게 문제였다.
2안: 화면을 나란히 놓고 비교하기 (버림)
새 앱은 UI를 일부러 바꿨기 때문에 화면 비교로는 같은 동작인지 판단할 수 없었다. 키보드 단축키나 "마지막 탭 기억"처럼 화면에 안 보이는 동작은 애초에 비교 대상이 되지 않는다.
3안: 옛 코드에서 동작 목록과 스펙을 뽑고 그 스펙으로 다시 개발하기 (선택)
동작마다 옛 위치를 적으니 빠진 것을 코드로 증명할 수 있었고, 스펙으로 바꾸니 AI에게 "이걸 만들어"를 정확히 줄 수 있었다. 옛 코드를 지워도 된다는 판단도 이 목록으로 내렸다.
결과 / 회고
처음 ❌였던 9줄 중 지금 남은 것은 1줄(테마)이고, 이 줄은 다음 할 일 후보가 됐다. 옛 코드는 지웠지만 그 코드가 하던 일은 BEHAVIORS.md와 스펙에 남았다.
이번에 확실히 느낀 건 AI를 제대로 다루는 방법은 결국 스펙이라는 것이다. AI는 시킨 것은 잘 만든다. 문제는 시키지 않은 것, 내가 말로 꺼내지 못한 것이다. 옛 코드에서 스펙을 뽑는 과정은 "내가 이 앱에 기대하던 것"을 말로 꺼내는 과정이었다.
앞서 스펙 주도 개발(SDD)이 개발자의 다음 일이 될까에서는 새 기능을 만들 때 SDD를 썼고, 스펙 주도 개발(SDD)은 워터폴의 귀환일까에서는 스펙을 계속 고치는 고리를 이야기했다. 이번에는 이주에도 같은 방식이 통했다. 새로 만들 때도, 옮길 때도 스펙이 기준이 된다. 앞으로 AI와 하는 개발은 스펙 주도 개발이 메인이 될 거라는 생각이 든다.