← making 메인으로

강사용 메뉴얼 — 이 사이트를 어떻게 만들었나

이 페이지는 본인 강의용으로 비슷한 사이트를 직접 만들어보려는 강사를 위한 작업 기록입니다. 광고가 아니라 작업 순서입니다. Claude Code 라는 CLI 와 몇 개의 마크다운 파일을 사용했고, 아래 6단계로 진행했습니다.

①Claude Code CLI 설치

터미널에서 다음 한 줄을 실행합니다. Node.js 18 이상이 필요합니다.

npm install -g @anthropic-ai/claude-code

설치 후 작업할 디렉토리로 이동해서 claude 명령으로 시작합니다. 첫 실행 때 브라우저로 로그인 창이 한 번 뜹니다.

$ mkdir my-course
$ cd my-course
$ claude

②시작용 MD 파일 받기

Claude Code 는 프로젝트 루트의 CLAUDE.md 와 .claude/agents/*.md 를 자동으로 읽습니다. 이 파일들이 「어떤 톤·구조·금기 사항」으로 작업할지 결정하므로, 비어 있으면 Claude 가 멋대로 「상품화된 광고 페이지」 같은 걸 만들어버립니다.

이 사이트에서 사용한 시작용 파일을 그대로 받아서 본인 주제로 수정하세요. 이 저장소는 public 입니다 — 강사 누구나 GitHub 에서 클론해 본인 강의 사이트를 만들 수 있도록 준비됐습니다.

받는 방법은 5 가지 — 모두 같은 파일을 받아오는 다른 경로일 뿐입니다. 본인 환경과 의도에 맞는 탭을 골라 그 명령만 따라하세요. 강의 사이트로 발전시킬 거면 E (권장) 또는 C 가 자연스럽습니다 — 자기 GitHub 계정에 자기 repo 가 생기므로 받은 그대로 push 해서 본인 강의 사이트로 키울 수 있습니다.

git clone https://github.com/<본인>/<새-repo-이름>.git
cd <새-repo-이름>

git clone https://github.com/<본인>/course-template.git
cd course-template

git clone https://github.com/icom009/course-template.git
cd course-template

git clone --depth 1 https://github.com/icom009/course-template.git
cd course-template

받은 다음 (5 가지 모두 공통) — 받은 그 폴더 안에 들어가서 (예: cd course-template) 다음 세 줄을 차례로 실행하세요. 각 줄이 뭘 하는지는 아래 설명을 참고하세요.

# 1. 본인 강의용 폴더를 새로 만들기
mkdir ~/<자기강의명>

# 2. starter 안의 내용물을 (숨김 파일까지) 그 폴더로 복사하기
cp -r starter/. ~/<자기강의명>/

# 3. 새로 만들어진 폴더로 이동해서 작업 시작
cd ~/<자기강의명>

복사된 그 자리에 이미 6 개 에이전트가 박혀 있습니다. claude 한 번 실행하고 "커리큘럼 짜줘" 한 마디면 시작됩니다.

③agent 환경 구축

받은 파일을 다음 구조로 프로젝트 루트에 둡니다.

my-course/
├── CLAUDE.md
├── CODE-STANDARD.md
├── scripts/
│   └── check-overflow.js
└── .claude/
    └── agents/
        ├── content-author.md
        ├── visual-designer.md
        ├── convention-auditor.md
        ├── flow-verifier.md
        ├── documentation-curator.md
        └── layout-verifier.md

.claude/ 폴더는 점(.) 으로 시작하므로 ls 에서 안 보일 수 있습니다. ls -a 로 확인하세요. 파일을 둔 다음 claude 명령으로 다시 들어가면 자동으로 인식합니다. 이후 「커리큘럼 짜줘」 라고 하면 content-author 에이전트가 호출됩니다.

각 에이전트의 역할은 파일 상단 frontmatter 에 적혀 있습니다. 본인 도메인에 맞춰 수정하세요 — 예를 들어 「Spring 기초 과정」 부분을 「JavaScript 기초」 로 바꾸는 식입니다.

④주제·테마 정하기 (Claude 와 대화)

여기가 이 메뉴얼에서 가장 중요한 단계입니다. 「커리큘럼 짜줘」 라고 한 번에 던지지 말고, 티키타카로 좁혀가야 학생이 풀 수 있는 산출물에 도달합니다. 처음부터 완벽한 프롬프트를 쓰려고 하지 말고, 그냥 평소 말하듯이 시작하세요.

실제로 다른 강사가 JavaScript 기초 강의를 만들 때의 대화를 그대로 옮긴 것입니다.

위에서 본 것처럼, 좋은 결과는 「한 번에 받는 것」 이 아니라 「강사가 자기 학생을 알기 때문에 좁혀가는 것」 입니다. Claude 는 일반론을 줄 뿐이고, 「3주차에 다 떨어져나갔어」 같은 정보를 넣어주는 게 강사의 몫입니다.

이 단계의 산출물은 다음 한 줄입니다 — 한 줄로 정리되지 않으면 아직 5단계로 넘어가면 안 됩니다.

4주 / 입문 / 마무리 산출물 = 숫자 맞히기 게임 (v0→v3)
이벤트는 onclick 만, addEventListener 는 후속 과정으로 분리

⑤범위 정하기 (Part 분할 / 진화 지도)

4단계의 한 줄 정리를 Claude 에 다시 던지면, 받아둔 content-author 에이전트가 표를 그려줍니다. 이 표는 본인이 검토해서 직접 줄이거나 늘려야 합니다.

예시 — 위 JavaScript 강의의 진화 지도:

이 단계에서 자주 하는 실수는 v 단계를 너무 잘게 쪼개는 것 입니다. v 가 늘어날수록 「이번 시간 우리가 어디로 진화하는가」 의 변화 폭이 작아져서 학생이 「지난 시간이랑 똑같은데?」 라고 느낍니다. 한 v 안에서는 눈에 띄는 변화 — 화면이 달라지거나 새 입력이 추가되거나 — 가 일어나야 합니다.

Part 분할은 CLAUDE.md 의 Part 약어 표 에 기록합니다. 본인 강의에 맞춰 약어와 색상을 바꾸세요. 이 표가 곧 index.html 의 카드 색상이 됩니다.

⑥코드·이미지 정리

CODE-STANDARD.md 작성

4·5단계에서 정한 「마무리 산출물」 의 도메인 모델을 한 번 정해두지 않으면, Claude 가 슬라이드마다 다른 변수명·다른 클래스명을 쓰게 됩니다. 받은 CODE-STANDARD.md 를 본인 강의에 맞춰 수정합니다.

# CODE-STANDARD.md 예시 (JavaScript 강의)

## 도메인
- 게임 객체 변수명은 `game`
- 답 변수명은 `answer` (`target`, `secret` 금지)
- 사용자 입력 변수명은 `guess`

## 표기
- 셸 입력: `$ ` 접두사
- 콘솔 출력: 접두사 없음
- 함수명: camelCase

인포그래픽·이미지

슬라이드 안의 빈 블록은 누락이 아닙니다 — 슬라이드 템플릿(starter/slides/template.html) 안에 보이는 <div data-infographic="..."> 빈 블록은 본문 작성 단계에서는 의도적으로 비워 둔 자리입니다. content-author 가 본문을 채운 뒤 visual-designer 에이전트 가 이 자리를 인포그래픽 SVG 또는 실사 이미지로 자동으로 채워 넣습니다 (js/infographics.js 에 등록). "내용이 빠졌나?" 싶은 칸이 보이면 거의 다 이 자리표시입니다.

슬라이드와 예제에 들어갈 다이어그램은 가능하면 HTML/CSS 로 그리는 텍스트 다이어그램 으로 처리하는 게 안전합니다 — 외부 이미지를 쓰면 라이선스·해상도·다크모드 호환을 매번 확인해야 합니다.

그래도 외부 이미지가 필요하면 다음 출처가 비교적 안전합니다.

이 사이트에서는 외부 이미지를 거의 쓰지 않았고, 대부분 .flow-diagram / .box 같은 텍스트 다이어그램으로 처리했습니다.