# 개발 블로그 엔트리 문서 아카이브 기능을 대폭 개선했습니다. 그동안 문제가 되어온 것은 콘텐츠가 쌓일수록 메인 페이지 로딩이 느려지고, 사용자가 원하는 문서를 찾기 어렵다는 점이었는데요. 이번 업데이트에서는 **페이지네이션을 도입**해 한 번에 표시되는 문서 개수를 제한하고, **요약 필드를 추가**해 사용자가 클릭하지 않고도 문서의 내용을 미리 파악할 수 있도록 했습니다. 구현 과정에서 AI의 도움을 받아 페이지네이션 로직을 설계했는데, 데이터베이스 쿼리 최적화와 프론트엔드 UI 간의 동기화를 맞추는 부분이 까다로웠습니다. 결과적으로 9개 파일에 걸쳐 384줄을 추가하고 16줄을 정리하면서, 기존 기능을 유지하면서도 새로운 사용 경험을 제공할 수 있었습니다. 특히 흥미로운 점은 요약 필드가 단순한 텍스트 트림이 아니라, 동적으로 생성되는 스니펫이라는 것입니다. 문서의 중요도나 카테고리에 따라 표시되는 내용이 달라지므로, 사용자는 더 맥락에 맞는 정보를 빠르게 스캔할 수 있게 되었습니다. 다음 단계로는 검색 기능을 추가해 페이지네이션과 함께 시너지를 낼 계획입니다.
# 개발 블로그 엔트리 Documents 프로젝트에서 사용자 경험을 크게 개선하는 업데이트를 완료했습니다. 이번 작업은 71개 파일에 걸친 변경으로, 접근성(a11y) 개선, 검색 기능 강화, 그리고 네비게이션 시스템 재구성이 핵심입니다. 특히 이전/다음 페이지 네비게이션을 새롭게 구현하고 로딩 상태 표시를 추가하여 사용자들이 현재 상태를 명확히 파악할 수 있도록 했습니다. 또한 robots.txt를 추가함으로써 검색 엔진 최적화 기초도 마련했습니다. 디자인 측면에서는 FINDING-001, 002, 003 이슈를 통해 발견된 사용성 문제들을 체계적으로 해결했습니다. 터치 타겟 영역을 확대하여 모바일 환경에서의 정확성을 높였고, 필터 높이를 조정해 화면 공간을 더 효율적으로 활용했으며, 음소거된 색상 대비를 개선하여 시각적 가독성을 향상시켰습니다. 이러한 작은 변화들이 모여 전체적인 인터페이스 품질을 한 단계 끌어올렸습니다. 흥미로운 점은 이 프로젝트에서 AI 도구와의 협업을 통해 접근성 체크리스트를 자동으로 생성하고 검토하는 프로세스를 도입했다는 것입니다. 이를 통해 수동 점검에서 놓칠 수 있는 WCAG 기준 위반 사항들을 사전에 발견할 수 있었고, 결과적으로 모든 인터랙티브 요소가 키보드 네비게이션을 지원하고 스크린 리더와 호환되도록 보장했습니다. 작은 부분이지만 모든 사용자가 동등하게 접근할 수 있는 서비스를 만드는 데 한 발 더 가까워졌습니다.
# 개발 블로그 엔트리 Google 로그인 기능을 Documents 프로젝트에 통합했습니다. 사용자들이 기존 Google 계정으로 간편하게 가입하고 로그인할 수 있도록 구현했으며, 동시에 기존 계정과의 연동도 지원합니다. OAuth 2.0 기반의 Google 인증 흐름을 적용했고, 사용자 정보 매핑과 데이터베이스 연동 로직을 함께 구성했습니다. 총 5개 파일을 수정하며 약 214줄의 코드를 추가하고 155줄을 정리했습니다. 구현 과정에서 마주친 로그인 에러들을 추적하기 위해 에러 메시지를 더욱 상세하게 개선했습니다. 사용자가 마주칠 수 있는 여러 실패 시나리오(토큰 만료, 권한 부족, 네트워크 오류 등)를 구분하여 각각에 맞는 메시지를 제공하도록 했습니다. 이를 통해 프로덕션 환경에서 발생하는 문제들을 더 빠르게 진단할 수 있게 되었고, 사용자 경험도 함께 개선되었습니다. 이 과정에서 AI의 도움을 받아 OAuth 흐름 설계와 에러 케이스 분류를 더욱 체계적으로 진행할 수 있었습니다. 단순 구현을 넘어 안정성 높은 인증 시스템을 만드는 데 집중했고, 향후 다른 소셜 로그인 제공자 추가도 이러한 아키텍처 위에서 수월하게 진행할 수 있을 것 같습니다.
# 개발 블로그 엔트리 이번 업데이트에서는 문서 사이트의 레이아웃과 성능을 함께 개선했습니다. 가장 눈에 띄는 변화는 colophon 페이지를 매거진 에디토리얼 스타일로 재설계한 것입니다. 중앙 정렬된 레이아웃으로 편집 콘텐츠의 위계를 명확히 하면서도 세련된 느낌을 전달하려고 했습니다. 동시에 콘텐츠 영역을 792px에서 1000px로 확대해 더 많은 정보를 효율적으로 표시할 수 있게 했습니다. 기술적으로는 몇 가지 중요한 이슈를 해결했습니다. 콘텐츠 캐시 무효화 로직을 개선하고 불필요한 ISR(Incremental Static Regeneration) 타이머를 제거해 빌드 성능을 최적화했습니다. TOC iframe 리로드 문제, 콘텐츠 재검증, 카테고리 ID 이름 변경 등 3가지 버그도 동시에 처리했는데, 이 과정에서 캐시 레이어와 동적 콘텐츠 처리 사이의 복잡한 상호작용을 디버깅할 수 있었습니다. 이번 변경사항들은 함께 작업하면서 개선 사항을 정의하는 데 AI의 도움을 받았습니다. 특히 레이아웃 재설계와 성능 최적화 전략을 검토할 때 다양한 관점에서 피드백을 얻을 수 있었고, 이를 통해 더욱 사려 깊은 결정을 내릴 수 있었습니다. 총 7개 파일에서 289줄을 추가하고 130줄을 정리해 사이트의 기초를 더욱 견고하게 만들었습니다.
# 개발 블로그 엔트리 Documents 프로젝트에 큰 규모의 기능 개선과 안정성 개선 작업을 진행했습니다. 목차(TOC) 네비게이션 시스템을 완전히 재설계하여 iframe 리로드 문제를 해결하고 `scrollIntoView`를 활용한 부드러운 스크롤 경험을 제공했습니다. 특히 앵커 인터셉션 로직을 강화하여 resolved href의 프래그먼트도 확인하도록 개선해, 복잡한 라우팅 환경에서도 안정적으로 작동하도록 만들었습니다. 더불어 관리자 카테고리 매니저의 UX를 폭넓게 개선했고, 에디터 저장 기능과 카테고리 커스텀 ID 설정 등 여러 주요 버그들을 수정했습니다. TypeScript 타입 안정성 강화, 데이터베이스 쿼리 최적화(복합 인덱스 제거 및 JS 측 정렬로 변경)도 함께 진행하여 코드베이스의 견고성을 높였습니다. AI 어시스턴트의 도움을 받아 타입 캐스팅 이슈들을 효율적으로 식별하고 해결할 수 있었습니다. 16개 파일에 걸쳐 1800여 줄의 코드 추가와 함께 불필요한 부분들을 정리하면서, 사용자 경험과 개발자 경험 모두를 개선하는 균형잡힌 업데이트가 되었습니다. 특히 이번 작업을 통해 작은 버그 수정이 전체 사용성에 얼마나 큰 영향을 미치는지 다시 한 번 깨달을 수 있었습니다.
Documents 프로젝트를 GitHub Pages에서 Next.js와 Firebase 기반의 현대적인 스택으로 완전히 마이그레이션했습니다. 이번 작업의 핵심은 단순한 정적 사이트 호스팅을 넘어 동적 콘텐츠 관리와 성능 최적화를 동시에 달성하는 것이었습니다. 72개 파일의 변경을 통해 아카이브 페이지들을 Next.js의 ISR(Incremental Static Regeneration)로 전환했고, Firebase를 활용한 캐시 무효화 메커니즘을 구현해 콘텐츠 업데이트 시 자동으로 캐시를 갱신하도록 설정했습니다. 이를 통해 빌드 시간은 단축하면서도 항상 최신 콘텐츠를 사용자에게 제공할 수 있게 되었습니다. 기술적으로는 몇 가지 흥미로운 개선 사항들이 있습니다. 기존의 브라우저 기본 `confirm()` 대신 React 기반의 인라인 컨펌 UI로 교체해 사용자 경험을 개선했고, 관리자 CRUD 작업을 클라이언트 SDK에서 Server Actions로 마이그레이션해 보안을 강화했습니다. 또한 환경 변수의 뉘앙스로 인한 Firestore 경로 오류를 해결했고, 아카이브 콘텐츠 페이지를 풀스크린으로 렌더링하도록 수정했습니다. AI 어시스턴트의 도움을 받아 마이그레이션 중 여러 엣지 케이스를 식별하고 해결 방안을 검토했으며, 원본 사이트 레이아웃과의 일관성 유지도 함께 진행했습니다. 이제 Documents는 확장 가능하고 유지보수하기 쉬운 구조로 재편성되었습니다. ISR을 통한 캐싱 전략과 Server Actions 기반의 관리 시스템은 향후 더 많은 문서 추가와 실시간 업데이트 요구사항에도 쉽게 대응할 수 있는 토대를 마련했습니다.
# 개발 블로그 엔트리 이번 업데이트에서는 Documents 프로젝트에 FIA F1 2026 시즌 규정 문서의 한국어 번역본을 추가했습니다. 구체적으로 2026년 포뮬러 1 시리즈의 Section A(일반규정)을 한국어로 번역하여 데이터베이스에 통합했는데, 이는 국내 F1 팬들과 개발자들이 공식 규정에 더 쉽게 접근할 수 있도록 하는 것이 목표였습니다. 4개의 파일을 수정하며 705줄을 추가하고 52줄을 정리하는 과정을 거쳤으며, 문서 구조를 최적화하고 아카이브 목록을 재정렬했습니다. 작업 과정에서 주목할 점은 단순한 번역 추가를 넘어 전체 문서 체계의 일관성을 유지하는 데 집중했다는 것입니다. 새로운 F1 카테고리를 생성하고, 여러 차례에 걸쳐 아카이브 목록을 재정렬하며 문서의 메타데이터를 정확하게 관리했습니다. AI 도구를 활용하여 번역 검수 및 문서 포맷 정규화 과정을 효율화했으며, 이를 통해 데이터 일관성을 보장하면서도 작업 시간을 단축할 수 있었습니다. 이러한 작업은 단순해 보이지만 문서 관리 시스템에서 매우 중요한 부분입니다. 카테고리 추가, 순서 정렬, 메타데이터 업데이트 등 세부 사항들이 축적되면 사용자 경험을 크게 개선할 수 있기 때문입니다. 향후에는 이 패턴을 다른 국제 스포츠 규정 문서에도 적용하여 더욱 다양한 자료를 제공할 계획입니다.