MAKING · 제작기
kk-flow.com 제작기: 보여 주는 사이트에서 읽히는 사이트로
8월 26일 원페이지 포트폴리오로 시작한 kk-flow.com이 작업 노트 사이트가 되기까지. 구글이 본문 대신 카드 한 줄을 읽어 가던 문제, 영어로 색인되던 홈, 빠진 canonical, 그리고 프레임워크 없이 파이썬 스크립트 하나로 글·그림·검색을 만드는 지금의 구조를 커밋 기록으로 돌아봤습니다.
지금 읽고 계신 이 사이트, kk-flow.com의 제작기입니다. 다른 제작기가 KKflow의 서비스와 게임을 다뤘다면, 이번에는 그것들을 모아 보여 주는 집 자체를 돌아봅니다. 저장소의 운영 브랜치에는 2026년 8월 26일부터 10월 8일까지 커밋이 65개 있고, 거의 전부 Claude Code가 작성자로 남아 있습니다. 이 글도 같은 방식으로, 커밋 기록과 저장소의 문서를 근거로 썼습니다.
8월 26일: 시안 여섯 장, 하루 만의 원페이지
첫 커밋은 8월 26일 오전 10시 59분(한국 시각)의 "KKflow 메인 홈페이지 기획 + 로고 + 원페이지 시안"입니다. 브랜드와 디자인 시스템, 페이지 구조, 프로젝트 목록, 로드맵을 담은 기획 문서(docs/PLANNING.md), 흐르는 K 모양의 로고, 그리고 "딥워터"라는 이름의 어두운 원페이지 시안이 한꺼번에 들어갔습니다.
50여 분 뒤에는 시안이 다섯 장 더 생겼습니다. 매거진, 브루탈, 터미널, 오로라, 스위스. 저장소의 designs/ 폴더에 지금도 남아 있습니다. 다시 35분 뒤 커밋 제목이 "딥워터 디자인 확정 및 홈페이지 마무리"입니다. 처음 시안이 그대로 채택된 셈입니다. 왜 딥워터를 골랐는지는 기록에 없습니다. 같은 날 오후에는 라이트 모드 기기에서 흰 배경 버전이 보이던 것을 없애고, 어디서나 같은 어두운 화면이 보이도록 테마를 하나로 고정했습니다.
그날 저녁까지 프로젝트 카드의 링크를 실제 서비스 주소로 바꾸고, 링크를 공유할 때 보이는 미리보기 이미지를 넣고, 아직 공개하지 않은 프로젝트 몇 개는 목록에서 숨겼습니다. 하루 만에 "1인 스튜디오의 프로젝트 목록"이라는 첫 모습이 완성됐습니다.
8월 27일: 상세 페이지와 영어
이튿날 아침에는 영어 버전이 생겼습니다. 헤더의 버튼으로 한국어와 영어를 바꾸고, 첫 방문이면 브라우저 언어를 보고 한국어가 아니면 영어로 보여 주는 방식이었습니다. 버튼이 줄바꿈되는 문제를 고치고, 버튼을 지구본 아이콘 메뉴로 바꾸는 데까지 21분이 걸렸습니다.
저녁에는 "콘텐츠·SEO 대규모 확장"이라는 커밋이 들어갔습니다. 프로젝트마다 소개·주요 기능·자주 묻는 질문이 있는 상세 페이지 8종(p/*.html), 업데이트 기록을 보여 주는 "흐름 일지", 이용약관과 404 페이지, 사이트맵과 robots.txt까지입니다. 이튿날에는 로고에 세로 조합을 더했는데, 커밋 제목에 이유가 적혀 있습니다. 가로로 늘어놓으면 K 마크와 "KKflow"가 이어져 "KKK처럼 읽히는 문제" 때문이었습니다.
9월 4일: 구글이 본 것은 빈 페이지였다
이 사이트에서 가장 많이 배운 커밋은 9월 4일의 "크롤러가 보는 콘텐츠 문제 해결"입니다. 구글 검색 결과에서 kk-flow.com의 설명이 바이브데일리 카드의 영어 문장으로 나오고, 페이지 전체가 영어로 색인되고 있었습니다. 커밋은 원인을 두 가지로 적었습니다.
- 본문이 자바스크립트로만 만들어졌다. 프로젝트 카드 8개, 흐름 일지, 소개 문단이 전부 스크립트로 그려졌기 때문에, 처음 받는 HTML에는 제목만 있었습니다. 검색 로봇이 스크립트를 실행하기 전에 보면 알맹이가 없는 페이지입니다.
- 첫 방문 언어를 브라우저 언어로 정했다. 구글의 검색 로봇은 영어 환경으로 들어오기 때문에, 영어 버전을 수집했습니다. 한국 사람을 위한 사이트가 한국어 검색에 걸리지 않는 상태였습니다.
해결은 카드·일지·소개를 한국어 HTML로 미리 그려 두는 것이었습니다. 커밋에 적힌 숫자로, 자바스크립트 없이 보이는 본문이 "사실상 0자에서 4,320자"가 됐습니다. 기본 언어는 한국어로 고정하고, 영어는 지구본 메뉴에서 고르게 했습니다. 커밋은 한 줄을 더 남겼습니다. "크롤러와 사용자에게 같은 내용을 보여주므로 클로킹에 해당하지 않는다." 검색 로봇에게만 다른 내용을 보여 주는 것은 검색엔진이 금지하는 일이라, 그렇지 않다는 점을 확인해 둔 것입니다.
9월 7일에는 사소하지만 눈에 띄는 문제가 고쳐졌습니다. 로고 글꼴(Hahmlet)이 f와 l을 한 글자로 합치는 합자를 기본으로 적용해서, "KKflow"의 "fl"이 붙어 보였습니다. 헤더가 있는 12개 페이지 전부와 이미지에 합자를 끄는 설정을 넣고, 글꼴 없이도 깨지지 않도록 글자를 도형으로 바꾼 벡터 로고 4종을 만들었습니다.
9월 10~15일: 검색 결과에 보이는 모습 다듬기
9월 10일 커밋은 또 다른 검색 결과 문제를 적었습니다. 구글이 kk-flow.com을 "KKflow" 한 단어 제목에 스택 타워 카드 문장을 붙여 보여 주고 있었습니다. 사이트가 블록 쌓기 게임 페이지처럼 읽히고, 이름이 같은 음원과도 섞였다고 합니다. 페이지 제목을 "KKflow — 게임·서비스·도구를 만드는 1인 프로덕트 스튜디오"로 바꾸고, 요약 문장에 실제 프로젝트 이름을 넣고, 구조화 데이터에 KKflow를 하나의 단체로 알아보게 하는 정보를 더했습니다.
9월 13일에는 배포된 서비스 8개를 전부 직접 열어 사이트 설명과 대조했습니다. 그 사이 "3D 검투사 대전"이던 게임이 웨이브 생존 게임 "최후의 파도"로 바뀌어 있었는데, 사이트는 여전히 옛 설명을 달고 있었습니다(이 게임의 사정은 최후의 파도 제작기에 있습니다). 이름과 설명, 상세 페이지를 실물에 맞추고, 얇았던 상세 페이지 네 곳에 "이렇게 만들었어요"와 자주 묻는 질문을 더했습니다. 상세 페이지 본문 합계가 6,483자에서 8,911자로 늘었다고 적혀 있습니다.
9월 15일에는 서치 콘솔이 9월 6일에 보고한 색인 제외 사유를 고쳤습니다. "사용자가 선택한 표준이 없는 중복 페이지." 상세 페이지와 약관에는 정식 주소(canonical)가 다 있는데, 정작 홈에만 빠져 있었습니다. 홈은 kk-flow.com, kk-flow.com/, /index.html 같은 여러 주소로 닿을 수 있어서 구글이 정본을 고르지 못한 것입니다. 404 페이지는 "색인하지 마라"와 "정식 주소는 이것"을 동시에 선언하고 있어서, 모순되는 쪽을 지웠습니다.
10월: 작업 노트가 중심이 되다
10월 2일, 프로젝트 소개만 있던 사이트에 블로그와 독립된 소개·문의 페이지가 생겼습니다. 첫 묶음은 가이드와 제작 노트 7편, 같은 날 오후 제작기 3편이 더해졌습니다. 이튿날의 커밋은 방향을 한 문장으로 적었습니다. "사이트의 중심을 프로젝트 소개에서 작업 노트로 옮긴다." 홈 첫 화면 바로 아래에 최신 노트가 오고, 글은 버그 도감·제작기·월간 노트·데이터 네 시리즈로 나뉘었습니다.
이 무렵부터 일하는 방식도 정해졌습니다. 정해진 시각마다 Claude Code가 KKflow 저장소들의 커밋 기록을 읽고 글 한 편을 써서 작업 브랜치에 올리면, 운영자가 읽고 승인한 글만 실제 사이트에 나갑니다. 사이트 기능도 하루에 하나씩 같은 방식으로 붙습니다. 운영 규칙은 저장소의 docs/BLOG.md와 docs/FEATURES.md에 적혀 있고, 그 안에는 "기록에 없는 동기·감정은 지어내지 않는다", "방문자 수·수익은 쓰지 않는다" 같은 원칙이 들어 있습니다. 이 글에 "기록에 없습니다"가 여러 번 나오는 이유이기도 합니다.
지금의 구조: 프레임워크 없는 생성기
kk-flow.com은 지금도 정적 HTML 사이트입니다. 빌드 도구나 프레임워크 없이, 저장소의 tools/notes/에 있는 파이썬 스크립트가 HTML을 만들어 냅니다. 글 한 편은 postsN.py 파일 하나에 담긴 파이썬 사전이고, build.py를 실행하면 글 페이지, 작업 노트 목록, 홈의 최신 노트 블록, RSS 피드, 검색용 목록이 한 번에 다시 만들어집니다. 생성기 핵심 파일 세 개(build.py, tpl.py, figs.py)를 합치면 1,700줄 남짓입니다.
10월 4일부터는 하루에 하나씩 기능이 붙었습니다.
- RSS 피드(10/4)와 글 목차·읽는 시간(10/5)
- 설명 그림(10/5~) — 글 속 그림은 이미지 파일이 아니라 파이썬으로 그리는 인라인 SVG입니다. 지금 44개가 있고, 제작기에는 날짜별 커밋 막대그래프가 자동으로 들어갑니다. 바로 위의 그래프도 그렇게 만들었습니다.
- 공유 카드 이미지(10/5) — 글마다 1200×630 미리보기 이미지를, 브라우저 자동화 도구(Playwright)로 페이지를 그려 찍어 냅니다. 지금 34장입니다.
- 관련 글 추천(10/6) — 같은 프로젝트 글에 2점, 같은 시리즈에 1점을 주어 글 아래에 세 편을 고릅니다.
- 작업 노트 검색(10/7) — 빌드할 때 제목·요약·태그를 담은 작은 JSON을 만들고, 목록 페이지에서 브라우저가 직접 찾습니다. 서버도, 검색어 기록도 없습니다.
- 다음 절기 안내(10/8) — 24절기 시각표 페이지가 지금 시각을 기준으로 다음 절기까지 남은 날을 계산합니다.
정적 사이트를 고집한 이유를 적은 문서는 없지만, 규칙 문서에는 "정적 사이트를 유지한다. 빌드 도구·프레임워크·외부 의존성을 들이지 않는다"가 원칙으로 적혀 있습니다. 덕분에 9월 4일의 교훈, 즉 "검색 로봇은 HTML에 있는 것만 본다"는 문제가 구조적으로 다시 생길 수 없습니다. 모든 본문이 처음부터 HTML에 들어 있으니까요.
돌아보며
kk-flow.com의 기록에서 반복되는 주제는 "사람이 보는 것과 검색 로봇이 보는 것이 같은가"입니다. 자바스크립트로만 그린 본문, 브라우저 언어로 정한 첫 화면, 빠진 정식 주소, 한 단어짜리 제목. 사람의 눈에는 멀쩡했지만 검색 로봇의 눈에는 다른 사이트였습니다. 그리고 한 달 뒤에는 "무엇을 보여 줄 것인가"라는 질문으로 넘어갔습니다. 프로젝트 목록만으로는 읽을 것이 거의 없었고, 그래서 만들며 겪은 것을 기록하는 작업 노트가 사이트의 중심이 됐습니다.
작업 노트를 처음 읽으신다면 버그 도감 #1이나 사주 플로우 제작기부터 시작해 보셔도 좋습니다. 사이트를 만든 사람과 원칙은 소개 페이지에 있습니다.