← making 메인으로

이 사이트가 어떻게 만들어졌는지의 솔직한 회고

메인 페이지 (index.html) 와 강사용 메뉴얼 (for-instructors.html) 은 비교적 깔끔합니다. 그건 결과물입니다. 결과물에 닿기까지의 과정은 그렇게 깔끔하지 않았습니다. 이 문서는 그 과정 자체의 기록입니다 — 어떤 대화가 사이트의 방향을 바꿨는지, 어디에서 시간을 잃었는지, 무엇을 다시 만들었는지.

1.시작

2026-04-28 12:26, /Users/jungyu/Desktop/study/spring/ 는 빈 디렉토리였습니다. 첫 명령어는 /init 이었습니다. 그 시점에 사이트의 모양은 정해진 것이 거의 없었습니다 — 코스명도, Part 구성도, 어떤 마무리 산출물로 끝낼지도. 정해진 것은 두 가지뿐이었습니다: estcamp.site 의 AWS 과정에서 검증된 사이트 템플릿을 차용한다는 것, 그리고 자료/ 디렉토리에 8 개의 docx 학습 가이드가 있다는 것.

처음 5 시간 (12:26 ~ 17:36) 동안 56 차시 × 4 종 자료 = 224 개의 학습 페이지가 만들어졌습니다. 이후 며칠에 걸쳐 보강이 더해졌습니다 — 슬라이드 분할, 코드 표준화, 협업 차시 신설, 영구 에이전트 등록. 현재 저장소는 약 1.4 MB / 240+ 파일입니다. 누적으로 약 1,400,000 토큰, 비용 예시* 로 환산하면 약 USD 38 (5만원 안팎) 을 썼습니다.

2.토큰 사용량 — 단계별

Claude Opus 4.7 (1M 컨텍스트) 한 모델로 단계적으로 누적 생산했습니다. 각 단계의 입력 + 출력 합계 추정치입니다. 6 차 이후로는 /compact 가 2~3 회 발생해 정확한 누적은 추정값입니다.

가장 비용 효율적이었던 단계는 2 차 양산입니다 (파일당 약 1,100 토큰 — 같은 템플릿을 다른 데이터로 채우는 일이라 토큰 단가가 매우 낮음). 가장 토큰을 많이 쓴 단계는 4 차 시각화 시스템 도입과 7 차 코드 표준화 입니다 (둘 다 100 개 단위 파일을 동시에 만지는 작업).

* 비용 예시 — 가정: Anthropic 공식 단가 기준 추정값. 입력 $15 / 1M tok, 출력 $75 / 1M tok (Claude Opus 4 표준 단가), 입출력 비율 80 : 20 가정 → 유효 평균 약 $27 / 1M tok. prompt cache 적중·1M 컨텍스트 프리미엄·배치 할인은 미반영. 실제 청구액은 사용 패턴(캐시 적중률·재작성 빈도·세션 길이)에 따라 ±50% 수준에서 달라질 수 있습니다. 한 마디로: "이 정도 규모의 사이트를 한 명이 만든다면 커피 몇 잔 값 ~ 한 끼 식사값 사이" 라는 감을 잡기 위한 숫자입니다.

3.실제 대화 — 방향을 바꾼 한마디들

이 사이트의 형태를 결정한 것은 토큰 양이 아니라 사용자의 짧은 한마디 몇 개였습니다. 아래는 그중 사이트의 골격 자체를 바꾼 6 개의 인용입니다. 표기 그대로 옮깁니다.

1) 비전공자라는 단어가 학생 화면에 박혀 있던 시점

"방향이 잘못되어있어 ... 비전공자라는 대상은 화면에 드러나면 안될 개념이지" — 본격 생산 1차 직후

이 한 줄로 컨벤션 대수정이 발생했습니다. 「비전공자」라는 단어가 학생용 어떤 화면에도 노출되지 않게 한다는 원칙이 처음 박혔고, 동시에 코스명·hero 부제·footer·Part tagline·핸드아웃 표지에서 이 단어가 모두 제거됐습니다. 이미 만들어진 50+ 파일을 재방문해야 했습니다.

2) 비유가 제목·라벨로 등장하던 시점

"가르키는 비유는 단순 과정상의 비유가 되어야 할뿐 그게 제목으로 등장하면 맞지 않아" — 같은 메시지의 후반부

비유는 본문 안의 보조 설명에서만 사용한다는 원칙이 굳어졌습니다. 「카페 비유로 시작」 같은 카드 제목, 「손님과 가게」 같은 Part tagline, 「카페 비유로 설명할 수 있다」 같은 학습 목표가 모두 제거됐습니다. 파일명도 의미 기반으로 개명 (예: web-network-cafe.html → web-client-server.html).

3) 차시 번호가 학생에게 보이던 시점

"차시에 연연하게 하지 않도록 숫자로 표현하기보단 기호로" — TOC 협상 후반

네 글자 기호 체계 (◇ ▣ ◆ ★) 가 도입됐습니다. 학생 화면에 「23/64 차시」 같은 카운트다운이 절대 노출되지 않게. 마일스톤은 추가로 버전 뱃지 (v0 ~ v∞) 를 붙입니다. 이 결정은 이후 모든 카드·헤더·핸드아웃 표지에 일괄 적용됐습니다.

4) 처음 어렵게 만든다는 발상

"처음 어렵게 ... CRUD 와 REST API 그럴것처럼" — 교수법 협상 단계

이터레이션 패턴 (v0 → v∞) 이 도입됐습니다. 같은 화면을 의도적으로 어렵게 한 번 만들고, 새 도구로 다시 만들면서 그 도구가 왜 좋은지 학생이 직접 체감하게 합니다. 동시에 모든 차시는 「이전 버전의 불편 → 새 도구 → 적용 → Before/After」 4 단계 구조를 따르도록 박혔습니다.

5) 양산 직후의 한마디

"내용들이 빈약한데?" — 2차 양산 검수 직후

Python 생성기로 224 파일을 양산한 직후의 평가입니다. 이 한 줄로 가장 중요한 마일스톤·전환점 9 개 (v0.5, v1, v3, v4, v6, v8, v9, v∞, db-setup-checklist) 의 슬라이드를 350~450 줄 / 18~22 슬라이드로 다시 작성하는 3 차 보강이 시작됐습니다. 양산이 빠르다는 것과 양산이 충실하다는 것은 다른 문제였습니다.

6) 슬라이드가 페이지를 넘어가던 시점

"슬라이드가 페이지를 넘어가는 형태들이 발견돼" — 6차 보강 직전

reveal.js 의 한 슬라이드가 720 px 안에 들어가지 않고 잘리던 문제. 이 한 줄로 scripts/check-overflow.js 와 layout-verifier 영구 에이전트가 만들어졌습니다. 첫 스캔에서 FAIL 46 / WARN 37. 4 Part 병렬 분담으로 모두 분할해 FAIL 0 까지 내렸습니다. 분할 후 슬라이드 수가 약 +50 개 늘었습니다.

4.삽질·실수 — 솔직한 기록

메뉴얼은 깔끔하게 정리됐지만 실제로는 다음과 같은 사고들이 있었습니다. 모두 사용자의 지적 또는 자체 검수에서 발견된 것입니다.

5.좋았던 결정

반대로 일찍 박아둬서 끝까지 흔들리지 않았던 결정들도 있습니다.

• 4 단계 구조의 강제 — 「불편 → 도구 → 적용 → Before/After」 가 모든 차시에 박혀 있어, 양산 단계에서도 톤이 흐트러지지 않았습니다. Python 생성기 자체가 4 단계 슬롯을 가지고 있어 빈 슬롯이 있으면 생성이 안 됐습니다.
• 데이터 흐름 컨벤션 3 종 — 흐름도 슬라이드 (마지막 직전 고정) / 미니맵 (examples·labs 첫 페이지) / Checkpoint (labs 모든 Step 마지막). 이 세 가지가 디버깅 사고를 「의식하지 않아도 따라가게」 만드는 장치입니다. 한 번 표준을 박아두니 차시가 늘어나도 학생이 길을 잃지 않습니다.
• 점진적 빌드업 — 완성형 코드를 한 번에 보여주지 않고, v2 → v10 까지 ALTER TABLE / 리팩토링 단계로 진화시킨 것. 학생이 「왜 이 컬럼이 추가됐는지」를 자기 손으로 겪게 됩니다.
• 영구 에이전트 6종 등록 — content-author / visual-designer / convention-auditor / flow-verifier / documentation-curator / layout-verifier 가 .claude/agents/ 에 영구 등록되어 다음 세션에서도 자동으로 호출 가능합니다. 한 차시 신설 시 이 6 개가 협업 체인으로 검증·보강합니다.
• 인포그래픽 vs 사진의 분리 원칙 — 비유 도입 (.new-tool·.pain-point) 에는 실사진, 추상 구조 (Controller-Service-Mapper, MVC 6 계층, DI 효과) 에는 SVG 인포그래픽. 두 자료의 역할이 섞이지 않아 슬라이드의 시각 부담이 일정하게 유지됐습니다.

6.만약 다시 만든다면

같은 사이트를 다시 만든다면 다음 네 가지를 처음부터 박을 것입니다. 모두 「뒤늦게 도입해 100+ 파일을 다시 만져야 했던」 항목들입니다.

1. 「비전공자」 노출 금지 규칙을 처음부터 — 코스명·hero·Part tagline·footer·핸드아웃 표지 등 학생 노출 자리를 미리 목록화하고, 그 자리에서 이 단어가 등장하지 않게.
2. Layout Verifier 를 처음부터 — 슬라이드 첫 한 장을 만들 때부터 scripts/check-overflow.js 같은 휴리스틱 검증기를 끼워두기. 사후 분할은 누적 손실이 큽니다.
3. CODE-STANDARD.md 를 처음부터 — 패키지명·테이블명·필드명을 첫 차시 작성 전에 결정. 본 프로젝트는 7 차에 도입해 108 개 파일을 다시 통일해야 했습니다.
4. 두 에이전트 동시 동작 금지 — 진행 중인 에이전트에 메시지 전달이 불가능한 동안에는 한 번에 한 차시씩만 처리. 새 에이전트를 띄우는 건 충돌 위험이 큽니다.

반대로 비유 사용 원칙·이터레이션 패턴·기호 체계는 일찍 박혔고, 끝까지 흔들리지 않은 부분입니다. 이 세 가지가 사이트의 톤을 만들었다고 봐도 됩니다.

7.마무리

메뉴얼은 깔끔합니다. 실제는 이만큼 더러웠습니다. 「비전공자」 라는 단어를 학생 화면에서 모두 빼는 데 한참 걸렸고, 비유를 제목 자리에서 끌어내리는 데도 한참 걸렸습니다. 양산은 빨랐지만 양산이 충실한 것은 아니었습니다. 슬라이드는 페이지를 넘쳤고, 두 에이전트는 한 번 부딪혔습니다.

이 기록을 따로 남기는 이유는, 강사용 메뉴얼 만 보면 이 사이트가 처음부터 정돈된 채 만들어진 것처럼 읽히기 때문입니다. 그렇지 않습니다. 위의 시행착오가 모두 있어서 지금 모양이 됐습니다. 다른 강사가 비슷한 사이트를 만들 때 같은 자리에서 다시 막히지 않게, 어디에서 시간을 잃었는지를 그대로 남깁니다.