getrvp.com — 이 사이트를 만든 순서, 시안에서 개편까지

① 개요

이 글은 순서를 적는다. 같은 것을 만들려는 사람이 어디서 무엇이 필요한지 알 수 있게. 겪은 일은 순서 안에 들어 있고, 사고는 따로 모았다.

---

② 기획 — 왜, 무엇을

3월에 「합리적가치프롬프트」라는 도구를 만들었다. AI에게 붙여 넣는 문장 묶음이다. 그리고 그것을 설명하는 책과, 그 도구가 왜 필요한지를 보여주는 사례 200편이 생겼다. 노션과 워드 파일에 흩어져 있었다. 남에게 보여줄 곳이 없었다.

그래서 사이트를 만들기로 했다. 처음 정한 성격은 「개인 홍보 사이트이자 실험실」. 책과 팩을 두는 서재이고, 동시에 AI로 무엇이 되는지 시험하는 곳. 홍보용이라기보다 기록이 있는 곳이 필요했다.

만드는 방식은 처음부터 정했다. 나는 코드를 모른다. 대화용 AI가 설계하고, 코딩 AI가 만들고, 나는 결정하고 확인한다. 이 분업이 뒤의 모든 단계를 정했다.

---

③ 구성 — 구조와 기능

명령어(홈)   조립기 · AI 리터러시 검사 · 카드 · 원전 · 본서 · 사례 DB(방패 100 ↔ 칼 100)
검증         팩을 조립기로 쓴 세션 기록 19편
실행         AI에게 일을 맡기는 순서 5편
결과         만든 것 — 이 구역
소개 · 공지 · 검색

기술은 단순하게 유지했다. 정적 사이트 — 서버가 없고, 사용자 데이터를 받지 않고, 폼이 없다. 빌드하면 HTML 파일 265개가 나오고 그것을 그대로 내놓는다. 검색도 빌드 때 색인을 만들어 두는 방식이라 서버가 필요 없다.

이 선택이 비용을 0으로 만들고, 관리할 것을 줄이고, 뚫릴 곳을 없앤다. 대신 할 수 없는 것이 생긴다 — 댓글, 로그인, 응답 수집. 그것을 하지 않기로 했다. 결과 구역에 동작하는 시연 대신 화면 캡처만 넣는 이유도 이 규칙이다.

콘텐츠는 두 종류로 산다. 사례 200편처럼 오래된 것은 데이터 파일(자바스크립트 객체)에, 검증·실행·결과처럼 새로 쓰는 글은 마크다운 파일에. 마크다운 쪽은 파일 하나가 글 하나다. 이 글도 그렇다.

---

④ 프롬프트 → 바이브코딩 — 여섯 단계

1. 시안 — 코드 전에 HTML 8장

코드부터 시작하지 않았다. 대화용 AI에게 화면 시안을 HTML로 그리게 했다. 홈, 소개, 창작교실, 클리닉, 작업실, 공지, DB. 8장. 화면을 눈으로 보고 결을 정했다 — 여백이 넓은 서재의 결. 로고 마크 「‖」, 구분자 「—」.

시안이 끝나자 AI에게 인수인계서를 쓰게 했다. 「다음 대화창의 AI가 재설명 없이 바로 코드 작업을 시작할 수 있게」. 이때는 몰랐지만 이것이 이 사이트의 첫 번째 규칙 파일이었다. 대화는 사라지고 파일은 남는다.

2. 코드 — Astro로 옮기기

시안 8장을 Astro 페이지로 옮겼다. 한 번에 한 페이지씩. 이때 AI가 특정 단어 하나를 말버릇처럼 썼는데, 그 단어는 나중에 사이트 전체에서 걷어 내야 했다. AI가 한 번 굳힌 말버릇은 파일 전체에 퍼진다.

가장 큰 일은 사례 200편이었다. 워드 파일 두 개(방패 100 · 칼 100)를 AI가 파싱해서 데이터 파일 하나로 만들었다. 397KB. 이 파일이 나중에 「단일 진실」 사건의 주인공이 된다.

3. 배포 — 5월

순서는 이랬다.

Git 설치 확인 → GitHub 저장소 생성 → 파일 115개 push
→ Cloudflare에 저장소 연결 → 첫 빌드 → 실패

첫 빌드가 실패했다. 파일 하나에서 내보내기(export) 한 줄이 빠져 있었다. 로컬에서는 됐는데 서버에서는 안 됐다. 로컬은 관대하고 서버는 엄격하다는 것을 이때 알았다. 한 줄 추가하고 다시 push. 통과. 파일 501개가 생성됐다.

도메인은 프로젝트 이름 그대로 getrvp.com. 5년 등록. 등록에는 실명이 필요한데 외부에는 공개되지 않게 설정된다는 것을 확인하고 진행했다. 도메인 연결, www 연결, HTTPS 자동. 그날부터 이 주소가 살아 있다.

4. 정비와 CI — 6~7월

올리고 한 달 뒤 AI에게 사이트를 평가시켰다. 「웹디자인을 전혀 모르는 상태로 바이브코딩으로 만든 첫 웹사이트다. 개인 사이트로 나쁘지 않은가.」 AI는 점수를 매겼고 약점 다섯을 짚었다. 점수는 근거로 삼지 않는다 — AI가 매긴 점수가 무엇을 뜻하는지는 이 사이트의 검증 구역이 따로 다루는 주제다. 약점 다섯은 유용했다. 로딩 속도, 접근성, 시각 자산, 첫 화면, 다음 행동의 안내.

그리고 그 대화에서 질문 하나가 나왔다. 「AI가 내 상황을 다 알고 모든 계획을 짰는데, 왜 더 나은 방법을 미리 제시하지 않았을까.」 AI의 대꾸는 정직했다 — AI는 시킨 것을 하지, 시키지 않은 위험을 말하지 않는다. 그것이 실행 구역이 생긴 이유이고, 이 사이트가 「사람의 규약」을 「기계의 검증」으로 바꿔 간 이유다.

6월 정비.

저장소 정리       백업 zip 18개 삭제 · 중복 파일 제거
주소 통일         www → non-www 하나로. 정규 URL(캐노니컬) 전 페이지 통일
사이트맵          손으로 만들던 것 → 빌드 때 자동 생성. 페이지를 더해도 손댈 일 없음
구조화 데이터     검색엔진이 읽는 JSON-LD(사이트·저자·책·글·경로)
폰트              안 쓰는 굵기 제거 · 가짜 볼드 교정
보안 헤더 · 404 페이지

7월 정비는 다른 종류였다. 타입 검사(typecheck)를 실행했더니 오류가 83개였다. 화면은 멀쩡했다. 오류는 「지금은 되지만 다음에 고칠 때 깨질 것」의 목록이다. 83개를 0으로 만들었다. 테스트 15개를 만들었다. 그리고 CI를 추가했다 — GitHub에 push할 때마다 GitHub의 컴퓨터가 타입 검사·테스트·빌드를 자동으로 실행하고, 하나라도 실패하면 빨간 표시를 남긴다.

CI 설정 파일 맨 위에 이렇게 적혀 있다.

「사람의 규약」을 「기계의 검증」으로. 사람이 잊어도 기계는 잊지 않는다.

이 문장이 실행 4호가 됐다.

5. 단일 진실 — 7월 13일

사례 200편의 데이터 파일 이야기다. 원본은 워드 파일이었고, 사이트의 데이터 파일은 거기서 만들어졌다. 그 뒤 사실 정정을 데이터 파일에 직접 했다. 그러면 워드 원본은 낡은 것이 된다.

문제는 AI가 그것을 모른다는 것이다. 어느 날 AI가 「워드에서 다시 생성하면 깔끔하다」고 제안할 수 있고, 그러면 정정이 전부 되돌아간다. 실제로 그 직전까지 갔다. 그래서 문서 한 장으로 못 박았다 — 데이터 파일이 유일한 원본이다. 재생성하지 않는다. 수정은 파일에 직접 하고 커밋 메시지에 사례 번호를 적는다.

이것이 「두 개의 진실을 만들지 않는다」는 규칙의 시작이다. 같은 내용이 두 곳에 있으면 언젠가 어긋나고, 어긋나면 어느 쪽이 맞는지 판정하는 일이 새로 생긴다. 이 규칙은 뒤의 개편에서 라이선스 표기가 일곱 곳에서 어긋난 사고를 잡는 데도 쓰였다.

6. 개편 — 8~9월

8월 말, 구조를 바꿨다. 창작교실·클리닉·작업실을 내리고 검증·실행·결과·확장 네 구역을 세웠다. 명령어(도구·책·사례)는 그대로.

바꾸는 방식이 이 사이트답다.

명세 먼저          무엇을 왜 바꾸는지 문서 한 편. 소유자만 고친다
한 칸씩 교체       메뉴 배열을 통째로 바꾸지 않는다. 배포 1 · 2 · 3으로 나눠 한 칸씩
빈 진열장 금지     글 0편인 구역은 켜지 않는다. 파일 이름 앞에 「_」를 붙여 빌드에서 뺀다
옛 주소 보존       내린 페이지의 주소는 새 구역으로 자동 이동(301)
결정 기록          바꿀 때마다 「왜」를 파일로. 60여 편

이 구역(결과)이 배포 3이다. 이 글이 올라간 것이 그 배포가 켜진 순간이다.

---

⑤ 배포·관리 — 지금 굴러가는 방식

git pull → 수정 → 3패스 자가검증 → 작은 단위 커밋 → 보고 → (소유자) push
→ CI 검사 → Cloudflare 자동 빌드(약 100초) → getrvp.com 반영

3패스 자가검증은 AI가 소유자에게 올리기 전에 하는 세 가지 확인이다. 요구사항과 대조했는가 / 빌드·타입검사·테스트가 실제로 통과했는가 / 렌더된 HTML을 열어 봤고 다른 페이지가 안 깨졌는가. 세 가지가 다른 오류를 잡는다.

push는 항상 소유자가 한다. AI는 커밋까지만. 배포는 되돌리기 어려운 일이고, 되돌리기 어려운 일은 사람이 한다. 이것이 규약 파일의 첫 원칙 — 「객관적으로 증명 가능한 것은 자율로, 판단이 필요한 것은 소유자에게」.

규약 파일 한 장이 프로젝트 뿌리에 있고 세션마다 자동으로 읽힌다. 목표, 자율/호출 분기선, 행동 규칙, 매 작업 후 확인 목록, 그리고 교훈 로그. 교훈 로그는 사고가 날 때마다 한 줄씩 는다.

사고 — 교훈 로그에서

규칙은 사고에서 나왔다. 몇 개만.

• 홈이 덮어써졌다. AI가 전달한 파일 이름이 index.astro였다. 폴더 정보가 없는 이름. 실행 구역 랜딩이 될 파일이 홈 파일 위에 놓였고 본문 1,014줄이 사라졌다. 커밋 전이라 되돌렸다. 교훈 — 전달 파일은 이름에 폴더가 없다. 착수 전에 파일 요약값(md5)과 줄 수를 대조한다.
• 미완성 표시가 공개 직전까지 갔다. 글 안에 미완성 표시(괄호 안에 「확인」이라고 적어 둔 것)를 남겨 뒀는데 타입 검사·테스트·빌드가 전부 통과했다. 기계는 그 글자를 오류로 보지 않는다. 교훈 — 병합 전에 그 문자열을 검색해 0건인지 사람이 확인한다.
• 되돌리기 명령이 삭제 명령이었다. 커밋 안 한 수정본이 있을 때 git reset --hard는 안전망이 아니라 삭제다. 교훈 — 커밋 전의 안전망은 변경분을 파일로 저장해 두는 것이다.
• 한 단어를 바꿨는데 파일 전체가 바뀌었다. 줄끝 문자(CRLF) 문제. 어떤 편집 명령은 줄끝을 전부 바꿔 버린다. 교훈 — 편집 후 변경 통계가 예상 줄 수와 다르면 줄끝이 바뀐 것이다.

이 목록이 AI에게 매 세션 읽힌다. 같은 사고는 두 번 안 난다. 다른 사고는 난다.

검사 기준선

npm run check    0 errors · 0 warnings
npm test         110 passed
npm run build    265 pages

이 숫자가 기준선이다. 작업 뒤에 이 숫자가 예상과 다르면 무언가가 잘못된 것이다. 예상은 작업 전에 적는다. 「페이지가 +5 될 것」처럼. 맞으면 통과, 다르면 멈춤.

---

⑥ 결과물

지금 읽고 있는 것이 결과물이다. getrvp.com — 페이지 265, 도구 세 개(조립기 · 리터러시 검사 · 카드), 문서 네 축(원전 · 본서 · 방패 · 칼), 검증 19편, 실행 5편, 그리고 이 글.

5월의 첫 화면은 남아 있지 않다. 홈은 세 번 바뀌었고 메뉴는 두 번 바뀌었다. 남은 것은 저장소의 커밋 기록과 결정 기록 60여 편이다. 그것이 이 사이트가 「완성품 진열」이 아니라 「진행 중인 작업장」인 이유다. 이 구역의 다음 글들은 그 작업장에서 만든 다른 것들이다.

---

이 글의 범위

• 여섯 단계는 이 사이트에서 일어난 순서다. 다른 사이트는 다른 순서일 것이다. 남는 것은 「무엇이 어디서 필요했나」뿐이다
• 사고는 전부 커밋 전에 잡히거나 원상 복구됐다. 사이트에 실제로 올라간 사고는 미완성 표시 한 건뿐이고 그것도 공개 전에 잡혔다
• 도구 이름은 실제로 쓴 것이다. Astro가 최선이어서가 아니라 정적 사이트를 만들기 쉬워서 골랐다
• 이 글이 말하는 「규약」「3패스」「CI」의 자세한 방법은 실행 구역에 있다. 여기서는 그것이 어느 단계에서 왜 생겼는지만 적었다