describug.dev

두 가지가 겹쳐서 만들었습니다.

하나. 친구가 로컬 LLM을 만지며 남긴 기록을 웹페이지로 만들어 보여줬습니다. 보자마자 재밌겠다는 생각이 들었습니다.

둘. 변리사들이 AI를 주제로 이야기할 단톡방이 하나 있으면 좋겠다 싶었습니다. 방을 만들려니 내놓을 게 있어야 했고, 제가 만든 것 중 여러 변리사에게 두루 쓸모가 있겠다 싶은 것은 docx2patent였습니다.

둘을 합치면 답이 하나였습니다. 여태 만든 앱과 업무 도구를 한군데 모아두고, 만들고 고친 과정을 같이 기록하는 페이지. 그게 이 사이트입니다.

아래는 그 만드는 과정에서 알게 된 것들입니다. 개발을 해본 적 없는 분이 비슷한 걸 만들어 보려 할 때 참고가 되도록 적었습니다. 저도 넉 달 전에는 아무것도 몰랐습니다.

「스택」이 뭔가

개발 이야기에 스택(stack) 이라는 말이 자주 나옵니다. 쌓아 올린 더미라는 뜻인데, 실제로는 이 사이트를 만드는 데 쓴 재료 목록입니다. 요리로 치면 레시피 맨 위의 재료 칸입니다.

재료가 여러 개인 이유는, 웹사이트 하나가 서로 다른 일 네 가지로 나뉘기 때문입니다.

하는 일	여기서 쓴 것
화면을 그린다	Next.js · React · Tailwind · TypeScript
글을 담아둔다	마크다운 파일 (데이터베이스 없음)
인터넷에 띄운다	Vercel
주소를 붙이고 큰 파일을 둔다	Cloudflare

하나씩 풀겠습니다.

화면을 그리는 쪽

React는 화면을 조각으로 나눠 만들게 해주는 도구입니다. 글 목록의 한 줄, 위쪽 메뉴, 아래 꼬리말을 각각 부품으로 만들어 두고 가져다 씁니다. 이 사이트는 그런 부품이 열다섯 개쯤 됩니다.

Next.js는 그 React를 실제 웹사이트로 만들어 주는 틀입니다. 주소를 나누고(/application, /description), 각 주소마다 어떤 화면을 보여줄지 정합니다. 여기서는 한 가지를 더 합니다 — 미리 다 그려둡니다.

이게 중요합니다. 보통 웹사이트는 누가 접속할 때마다 서버가 화면을 그려서 보냅니다. 이 사이트는 글을 고칠 때 딱 한 번 그려두고, 그다음부터는 그려놓은 걸 그대로 보냅니다. 서버가 할 일이 없으니 빠르고, 고장 날 자리도 없고, 돈도 거의 안 듭니다.

Tailwind는 꾸미는 도구입니다. 색·여백·글자 크기를 정하는 규칙을 따로 파일에 적는 대신 화면 만드는 자리에 바로 적습니다. 따로 적으면 나중에 어느 규칙이 어디에 걸리는지 못 찾게 되는데, 그 문제가 없어집니다.

TypeScript는 실수를 미리 잡아주는 장치입니다. 「날짜가 들어갈 자리에 숫자를 넣었다」 같은 걸 띄우기 전에 알려줍니다. 안 써도 되지만, 혼자 만들면 봐줄 사람이 없어서 넣었습니다.

글을 담는 쪽 — 데이터베이스가 없습니다

보통 이런 사이트에는 데이터베이스가 붙습니다. 글을 보관하는 창고인데, 글을 쓰려면 관리자 화면에 로그인해서 입력하고 저장을 눌러야 합니다.

여기엔 그게 없습니다. 글은 전부 content/ 폴더 안의 파일입니다. 파일 하나가 글 하나입니다. 파일 맨 위에 제목·날짜·태그를 적어두면 (이 부분을 프론트매터라고 부릅니다) 목록·정렬·태그가 알아서 따라옵니다.

글은 마크다운으로 씁니다. **굵게** 라고 적으면 굵게 나오는 식의, 메모장에서도 읽히는 단순한 표기법입니다. 그걸 웹페이지용으로 바꿔주는 부품이 marked, 맨 위 제목·날짜를 읽어내는 부품이 gray-matter입니다. 둘 다 남이 만들어 둔 걸 가져다 썼습니다.

글이 전부 제 컴퓨터에 텍스트 파일로 있으니, 이 사이트가 없어져도 글은 남습니다.

인터넷에 띄우는 쪽 — Vercel이 하는 일

만든 걸 제 컴퓨터에서만 보면 사이트가 아닙니다. 남의 컴퓨터에서도 열리게 하려면 항상 켜져 있는 컴퓨터에 올려둬야 합니다. 그 컴퓨터를 빌려주는 곳이 Vercel입니다.

하는 일은 셋입니다.

1. 받아온다 — 제가 글을 고쳐 GitHub에 올리면 Vercel이 그걸 알아서 가져갑니다
2. 만든다 — 가져간 걸로 사이트를 통째로 새로 그립니다 (앞서 말한 「미리 그려두기」)
3. 띄운다 — 그려진 걸 전 세계에 뿌립니다

제가 하는 건 글 파일을 저장하고 올리는 것뿐입니다. 1~3분 뒤에 사이트가 바뀌어 있습니다. 버튼을 누르거나 파일을 옮기는 절차가 없습니다.

개인이 이 정도로 쓰는 건 무료 범위입니다.

주소와 큰 파일 — Cloudflare가 하는 일

Cloudflare에서는 두 가지를 씁니다.

첫째, 도메인. describug.dev라는 주소를 여기서 샀습니다. 도메인은 사는 게 아니라 빌리는 것이라 해마다 값을 냅니다. Cloudflare를 고른 건 원가에 가깝게 팔기 때문입니다 — 첫해만 싸게 주고 갱신할 때 값을 올리는 곳이 많습니다.

산 다음에는 **「이 주소로 오면 Vercel로 보내라」**고 한 줄 적어둡니다. 이 안내판 역할을 DNS라고 부릅니다. 주소와 서버를 이어주는 자리입니다.

둘째, R2 — 큰 파일 창고. docx2patent처럼 실행파일을 나눠주는 도구가 있는데, 그 파일이 운영체제당 70MB쯤 됩니다. 코드 저장소에 넣을 수 있는 크기가 아닙니다.

그래서 파일만 따로 R2라는 창고에 올려두고(dl.describug.dev), 사이트에는 링크만 겁니다. 주소를 latest로 고정해 뒀기 때문에 새 버전을 내도 이 사이트는 손댈 일이 없습니다 — 창고의 파일만 덮어쓰면 됩니다. 버전 번호와 파일 크기도 같이 올라가는 작은 파일에서 읽어옵니다.

왜 .dev 인가

.dev는 개발자용으로 만들어진 도메인 꼬리표입니다. .com이나 .kr 자리에 오는 것이고, 구글이 운영합니다.

고른 이유는 단순합니다. 참고한 친구 페이지가 .dev였고, 값을 알아보니 첫해 값과 갱신 값이 같았습니다 — 연 $12.20으로 고정입니다. 같은 화면에서 .org는 첫해 $8.50에 갱신 $11.20이었습니다. 도메인은 한 번 사면 계속 갱신하는 것이라, 첫해가 싼 것보다 값이 안 뛰는 쪽이 낫습니다.

특이한 점도 하나 있습니다. .dev는 HTTPS가 강제됩니다. 자물쇠 없는 http://로는 아예 열리지 않습니다. 보통 도메인은 「보안 연결을 붙일 수도 있고 안 붙일 수도 있는」 것인데 이건 선택지가 없습니다. 안전한 쪽으로 못 박혀 있는 셈입니다.

다만 이 강제 조항에는 대가가 있습니다. DNS를 잘못 걸면 인증서가 안 나오고, 그러면 사이트가 통째로 안 열립니다. 보통 도메인이면 자물쇠만 빠진 채로라도 열리는데, .dev에는 그 여지가 없습니다.

화면에 명세서 문법을 입혔습니다

읽는 사람이 변리사라는 걸 정해두고 시작했습니다. 그러면 화면을 어떻게 짤지가 상당 부분 따라 정해집니다 — 읽는 사람이 이미 아는 문법을 쓰면 되니까요. 그래서 이 사이트는 명세서처럼 생겼습니다.

자리	무엇을 가져왔나
항목 이름	만든 것 = Application(출원, 그리고 앱) · 기록 = Description(발명의 설명) · 읽은 것 = Background(발명의 배경이 되는 기술)
만든 것 번호	26-01 — 출원번호꼴. 만든 순서대로 붙고 한 번 붙으면 안 바꿉니다
목록 표 머리	App no. / Title & Abstract / Drawings — 서지사항 표 머리 자리
화면 캡처	「도면」 칸에 둡니다. 누르면 그 자리에서 크게 봅니다
기록 번호	[0001] — 단락번호. 가장 오래된 글이 [0001]입니다
글 위 요약	SUMMARY 아래 과제·수단 두 줄
본문 표제	DETAILED DESCRIPTION — 요약과 본문을 가르는 자리
없는 페이지	404를 [0404]로 찍습니다. 단락번호꼴로
글 끝 표시	[b] — 대괄호는 단락번호에서, 초록 b는 이름 꼬리에서

말장난으로 시작했는데 실제로 일을 합니다. 번호가 붙어 있으니 「26-04 말인데」로 집어 말할 수 있고, 표 머리가 있으니 목록이 무엇을 보여주는지 따로 설명할 필요가 없습니다.

다만 끝까지 밀어붙이지는 않았습니다. 사이트 구조 전체를 명세서 목차에 맞추는 안을 검토했다가 하지 않기로 했습니다 — 자세한 건 비유를 어디서 멈출까에 적었습니다.

규약을 빌드에 물렸습니다

여기가 이 사이트에서 제일 쓸모 있었던 장치라, 풀어서 적습니다.

빌드(build) 는 글 파일들을 실제 웹페이지로 바꾸는 작업입니다. Vercel이 글을 받을 때마다 자동으로 돌리는, 앞서 말한 「만든다」 단계입니다.

글을 쓸 때 지켜야 하는 규칙이 몇 개 있습니다. 날짜를 어떤 형식으로 적을지, 파일 이름을 어떻게 지을지 같은 것들입니다. 처음엔 그걸 문서에 적어뒀습니다. 그리고 안 지켜졌습니다. 읽지 않는 순간 조용히 어긋나는데, 어긋난 걸 아무도 알려주지 않는다는 게 진짜 문제였습니다.

그래서 검사기를 만들어 빌드 앞에 세워뒀습니다. 규칙을 어긴 글이 있으면 빌드가 멈추고, 어느 파일의 무엇이 틀렸는지 말해줍니다. 멈췄으니 사이트에 반영도 안 됩니다.

맞춤법 검사기를 「경고만 띄우는 것」이 아니라 **「저장 버튼 앞에 세워둔 것」**에 가깝습니다.

무엇을 잡느냐면, 전부 제가 실제로 저지른 것들입니다.

• 파일 이름에 한글이 섞였는가 — 이게 제일 고약했습니다. 제 컴퓨터에서는 멀쩡히 보이고 빌드도 통과하는데, 띄우고 나면 그 글만 404가 납니다
• 날짜를 따옴표로 감쌌는가 — 안 감싸면 형식이 깨져 빌드가 실패합니다
• 없는 항목을 가리키고 있는가 — 눌러도 아무 데도 안 가는 링크가 생깁니다
• 코드를 안 여는 도구에 저장소 링크가 붙어 있는가 — 눌리면 404입니다

규칙은 문서가 아니라 실행되는 자리에 둬야 지켜집니다. 이 사이트에서 배운 것 중 가장 값어치 있는 게 이거였습니다.

코드는 닫고 글은 엽니다

여기 올린 도구 대부분은 사건 명세서나 가족 데이터를 다뤄서 코드를 공개할 수 없습니다.

그래서 「코드 공개」와 「글 공개」를 처음부터 갈라뒀습니다. 글마다 공개 여부를 따로 적게 해서, 저장소를 닫아둔 채로도 무엇을 왜 만들었고 어떻게 동작하는지는 쓸 수 있게 했습니다.

읽는 사람에게 값어치 있는 쪽도 대개 코드가 아니라 그쪽이었습니다.

따라 만들어 보시려면

순서는 이렇게 잡으시면 됩니다.

1. 글부터 씁니다. 사이트 모양보다 쓸 게 있는지가 먼저입니다. 저는 만든 것 열다섯 개가 이미 있었고, 그게 없었으면 만들 이유도 없었습니다
2. 틀을 고릅니다. 글이 목적이면 데이터베이스 없이 파일로 가는 쪽을 권합니다. 관리자 화면을 만들 일도, 그게 고장 날 일도 없습니다
3. 먼저 띄웁니다. 다 만들고 띄우려 하면 안 띄웁니다. 허술해도 주소가 생기면 그때부터 고치게 됩니다
4. 도메인은 나중에 붙여도 됩니다. Vercel이 주는 임시 주소로 한동안 굴러갑니다
5. 규칙이 생기면 그때 검사기를 만듭니다. 처음부터 만들 필요는 없습니다. 같은 실수를 두 번 하면 그때가 만들 때입니다

드는 돈은 도메인 값뿐입니다. 해마다 만 원대에서 갱신되고, 띄우는 것(Vercel)과 파일 창고(R2)는 개인이 쓰는 정도면 무료 범위 안입니다.

공개하지 않는 것

저장소는 비공개입니다. 처음에는 공개로 뒀다가 하루 만에 닫았습니다.

사이트에 안 나가는 것들이 저장소에는 있습니다. 글 원본, 아직 안 올린 초안, 그리고 이 사이트를 어떻게 쓸지 적어둔 지침 파일이 있습니다. 그 지침에 사내 시스템 이름과 소속에 관한 서술을 적어 올렸는데, 저장소가 공개라 그대로 읽히고 있었습니다. 닫고, 고유명사를 지웠습니다.

사이트에 무엇이 나가느냐와 저장소에 무엇이 있느냐는 다른 문제였습니다. 공개할 이유를 따져보니 딱히 없기도 했습니다 — 읽는 분들께 값어치 있는 쪽은 대개 코드가 아니라 무엇을 왜 만들었는가이고, 그건 이미 이 사이트에 나와 있습니다.