workbench를 콘텐츠만 남기고 Astro로 다시 구성했습니다

요약#

workbench를 Astro로 이전하는 과정에서, 그동안 미뤄두었던 검색 기능과 전체 구조를 다시 바라보게 되었습니다.

기존 구현이나 스타일은 이어받지 않았고, Markdown으로 남아 있던 콘텐츠만을 기준으로 구조를 새로 구성했습니다. 이번 작업은 기능 개선보다는, 구현을 내려놓은 상태에서도 작업이 어디까지 진행될 수 있는지를 확인해보는 선택에 가까웠습니다.

이 글은 그 판단과, 최소한의 개입으로 진행된 작업 흐름을 기록한 것입니다.

배경#

Cloudflare Pages에서 blog와 workbench를 운영하고 있습니다.

정적 사이트로 운영하다 보니, 글의 수가 늘어날수록 이전에 작성한 내용을 다시 찾는 일이 점점 불편해졌습니다. 아주 초반부터 느꼈던 문제라기보다는, 어느 정도 콘텐츠가 쌓인 이후에야 체감하게 된 변화에 가깝습니다.

workbench에는 한때 검색 기능이 있었습니다. 당시에는 mustache 템플릿을 사용하지 않았고, JavaScript 함수 안에서 문자열 리터럴과 조건문을 직접 조합해 HTML을 만들어내는 방식이었습니다. 그 스크립트 안에 검색 로직이 포함되어 있었고, 실제로도 사용하고 있었습니다.

이후 스크립트를 다시 작성하면서 페이지를 여러 영역으로 나누고 템플릿화하는 작업을 진행했습니다. 구조를 단순하게 가져가는 과정에서 검색 기능은 함께 빠졌습니다. 기능 구현 자체의 어려움보다는, 템플릿 구조 안에서 검색 인덱스와 UI를 함께 관리해야 한다는 부담이 더 크게 느껴졌기 때문입니다. 당시에는 제목과 목록만으로도 당장은 문제가 없다고 판단했고, 검색은 제외된 상태로 유지되었습니다.

workbench를 Astro로 옮기며 다시 본 검색 문제#

이번 작업의 출발점은 workbench 재구성이었습니다.

기존 mustache 기반 구조에서는 스타일 수정이나 기능을 하나씩 추가할 때마다 관리 부담이 커졌고, 구조를 한 번 정리할 필요가 있었습니다. 이 과정에서 Astro를 선택했고, 구현은 OpenAI Codex에게 맡겼습니다.

Astro로 이전하면서, 이전 구조에서는 계속 미뤄두었던 검색 기능을 다시 검토하게 되었습니다.

이번에는 기준을 단순하게 잡았습니다. 검색 인덱스는 빌드 타임에 생성하고, 런타임에서는 정적 JSON을 읽어 필터링하는 방식으로 구성했습니다. 검색 품질을 높이기보다는, 기능이 존재하는 상태를 우선했습니다.

구현은 최소한의 정보만 포함하는 형태로 시작했습니다. 제목, 요약, 태그, URL을 기준으로 인덱스를 생성했고, 입력값에 따라 클라이언트에서 목록을 필터링하도록 구성했습니다.

완성도 높은 검색은 아니지만, 기록을 다시 찾는 데 필요한 수준의 기능은 제공하고 있습니다.

단순한 리팩터링이 아니었던 이유#

이번 작업은 기존 구현을 정리하거나 개선하는 리팩터링과는 성격이 달랐습니다.

리팩터링이라면 기존 구조를 이해한 상태에서 불필요한 부분을 덜어내거나, 유지보수를 고려해 점진적으로 수정하는 방식을 택했을 것입니다.

하지만 이번에는 그 방식을 선택하지 않았습니다.

기존 mustache 기반 템플릿은 분석하거나 다듬지 않았고, 구조를 이해한 뒤 단계적으로 고치는 과정도 거치지 않았습니다.

기존 구현은 참고 대상으로 두지 않았고, Markdown으로 작성된 콘텐츠만 남긴 채 구현 전체를 교체했습니다.

또한 구현 과정에서 사람이 직접 코드를 작성하거나 세부 동작을 하나씩 확인하는 방식도 사용하지 않았습니다.

무엇이 필요한지는 사람이 정했고, 그 외의 구현 과정은 Codex에게 맡겼습니다.

이 점에서 이번 작업은 기존 코드를 정리한 리팩터링이라기보다는, 구현을 유지해야 한다는 전제 자체를 내려놓은 선택에 가깝습니다.

템플릿을 제거하고 스타일을 다시 작성했습니다#

Astro로 이전하면서 기존 템플릿을 그대로 유지할 필요는 없었습니다.

템플릿 중심 구조에서는 스타일이 누적되기 쉬웠고, 페이지 단위로 구조를 나누는 것도 점점 불편해졌습니다. 작은 수정이라도 여러 파일을 함께 건드려야 하는 경우가 잦았고, 구조를 단순하게 유지하기가 어려워졌습니다.

그래서 기존 템플릿과 스타일은 유지하지 않았습니다. 레이아웃부터 다시 작성했고, 시각적인 요소를 늘리기보다는 구조를 단순하게 가져가는 쪽을 선택했습니다.

불필요한 장식은 제거했고, 각 페이지와 글로 이동하는 경로가 바로 드러나도록 구성했습니다. 목록은 많이 보여주기보다, 필요한 정보를 빠르게 찾을 수 있도록 정리했습니다.

이 과정에서 체감한 가장 큰 장점은 작업 피드백 루프가 눈에 띄게 짧아졌다는 점이었습니다.

기존 mustache 커스텀 템플릿 구조에서는 글이든 테마든 무언가를 수정한 뒤 결과를 확인하려면 매번 build & serve를 실행해야 했습니다. 구조가 단순하지 않다 보니, 작은 변경에도 확인 비용이 상대적으로 컸습니다.

Astro로 옮긴 이후에는 npm run dev만으로 바로 미리보기가 가능해졌습니다. Markdown 수정, 스타일 조정, 레이아웃 변경을 한 흐름 안에서 바로 확인할 수 있었고, 수정과 확인 사이의 간격이 거의 느껴지지 않을 정도로 줄었습니다.

이 변화는 기능 추가나 성능 개선처럼 눈에 보이는 결과는 아니지만, workbench를 다시 만질 수 있는 상태로 되돌려 놓는 데에는 결정적인 차이로 작용했습니다.

홈 페이지를 추가했습니다#

이번 작업과 함께 www.hyqrocodryx.kr 전용 홈 페이지를 추가했습니다.

이 페이지는 소개용 페이지라기보다, 각 프로젝트로 진입하기 위한 관문 역할로 구성했습니다.

구성은 다음과 같습니다.

Explore

Blog
workbench
GitHub

Recent Blog (최신 글 5개)
Recent workbench (최신 글 5개)
About / Tech Stack

Explore 섹션은 최상단에 배치했습니다. 이 페이지에서 오래 머무르기보다, 바로 각 공간으로 이동하는 구조를 선택했습니다.

GitHub README 내용을 홈으로 옮겼습니다#

홈 페이지 하단에는 About과 Tech Stack을 배치했습니다.

구성은 GitHub README에 정리해 두었던 내용을 기준으로 삼아 홈 페이지에 배치했습니다.

개인 소개를 새로 작성하기보다는, 각 프로젝트가 어떤 성격의 공간인지 드러내는 데 필요한 정보만 남겼습니다.

결과#

이번 작업을 통해 workbench에는 검색 기능이 다시 포함되었고, 전체적인 스타일과 구조도 이전보다 단순한 형태로 정리되었습니다. 또한 www 홈을 중심으로 blog, workbench, GitHub으로 이어지는 진입 경로가 분명해졌으며, 각 프로젝트의 최신 상태를 한눈에 확인할 수 있는 구조가 갖춰졌습니다.

마무리#

이번 workbench 재구성의 핵심은, 구현을 직접 관리하지 않은 상태에서 어디까지 정리할 수 있는지를 확인해보는 데 있었습니다. 기존 코드는 모두 폐기했고, 무엇을 만들 것인지에 대한 조건과 방향만 정한 뒤 실제 구현은 Codex에게 맡겼습니다.

그 결과 workbench는 Astro 기반으로 다시 구성되었고, 검색과 태그처럼 기록을 다시 찾는 데 필요한 최소한의 기능이 포함된 상태로 돌아왔습니다. 구현 세부를 하나씩 점검하거나 다듬지 않았음에도, 콘텐츠를 중심으로 한 구조는 충분히 동작 가능한 형태로 정리되었습니다.

특히 체감이 컸던 변화는 작업 환경이었습니다. 기존 mustache 커스텀 템플릿 구조에서는 글이나 스타일을 수정한 뒤 결과를 확인하기까지의 비용이 컸지만, 이제는 npm run dev로 바로 미리보기가 가능해졌습니다. 구현을 이해하거나 기억해두지 않아도, 수정과 확인이 자연스럽게 이어지는 흐름이 만들어졌다는 점이 이전과 가장 크게 달라진 부분입니다.

이 작업은 기능을 개선하거나 구조를 고도화하려는 시도라기보다는, 구현 부담을 내려놓았을 때 workbench가 어떤 상태로 재구성되는지를 관찰한 기록에 가깝습니다. 완성도를 높였다고 말하기보다는, 다시 만질 수 있고 다시 쓸 수 있는 상태로 되돌려 놓았다는 점에서 의미를 갖는 작업으로 남습니다.