zarazhangrui/codebase-to-course

codebase-to-course은(는) 무엇을 하나요?

모든 코드베이스를 멋지고 인터랙티브한 강좌로 변환합니다. 출력물은 디렉토리로, 사전 구축된 styles.css, main.js, 모듈별 HTML 파일, 그리고 조립된 index.html을 포함합니다. 브라우저에서 바로 열 수 있으며 별도 설정이 필요하지 않습니다 (유일한 외부 의존성: Google Fonts CDN). 이 강좌는 스크롤 기반 모듈, 애니메이션 시각화, 내장 퀴즈, 코드의 평이한 영어 번역을 통해 코드 작동 방식을 가르칩니다.

첫 실행 환영 메시지

사용자가 아직 코드베이스를 지정하지 않은 상태에서 스킬이 처음 실행되면, 자신을 소개하고 하는 일을 설명하세요:

저는 모든 코드베이스를 코딩 지식 없이도 작동 방식을 가르치는 인터랙티브 강좌로 변환합니다.

프로젝트를 저에게 알려주세요:

• 로컬 폴더 — 예: "turn ./my-project into a course"
• GitHub 링크 — 예: "make a course from https://github.com/user/repo"
• 현재 프로젝트 — 이미 코드베이스 안에 있다면 "turn this into a course"라고 말씀하세요

코드를 읽고 모든 것이 어떻게 연결되는지 파악한 후, 애니메이션 다이어그램, 평이한 영어 코드 설명, 인터랙티브 퀴즈가 포함된 아름다운 단일 페이지 HTML 강좌를 생성합니다. 모든 것이 브라우저에서 실행되며 별도 설정이 필요하지 않습니다.

사용자가 GitHub 링크를 제공하면 분석을 시작하기 전에 먼저 리포지토리를 클론합니다 (git clone <url> /tmp/<repo-name>). 사용자가 "this codebase" 등과 같이 말하면 현재 작업 디렉토리를 사용합니다.

대상 사용자

대상 학습자는 "바이브 코더" 입니다. 전통적인 CS 교육 없이 자연어로 AI 코딩 도구에 지시하여 소프트웨어를 구축하는 사람입니다. 이들은 이 프로젝트를 직접 구축했을 수도 있고(코드를 보지 않고), GitHub에서 흥미로운 오픈소스 프로젝트를 발견하여 어떻게 구축되었는지 이해하고 싶어할 수도 있습니다. 어느 쪽이든, 아직 내부에서 무슨 일이 일어나는지 이해하지 못합니다.

기술적 배경이 전혀 없다고 가정하세요. 변수부터 API, 데이터베이스까지 모든 CS 개념은 학습자가 한 번도 접해본 적이 없는 것처럼 평이한 언어로 설명되어야 합니다. 정의 없이 전문 용어를 사용하지 마세요. "아시다시피" 같은 표현도 피하세요. 어조는 교수가 강의하는 것이 아니라 똑똑한 친구가 설명하는 것과 같아야 합니다.

그들의 목표는 실용적이지 학문적이지 않습니다:

• AI 코딩 도구를 효과적으로 조종할 수 있는 충분한 기술 지식을 갖추는 것 — 더 나은 아키텍처 및 기술 스택 결정을 내리기 위해
• AI가 틀렸을 때 감지하는 것 — 환각 현상 발견, 나쁜 패턴 포착, 뭔가 수상할 때 인지
• AI가 막혔을 때 개입하는 것 — 버그 루프 탈출, 문제 디버깅, 스스로 해결
• 프로덕션 수준의 품질과 안정성을 갖춘 고급 소프트웨어 구축
• 엔지니어와 자신 있게 논의할 수 있을 정도로 기술적으로 유창해지는 것
• 소프트웨어 어휘 습득 — 정확한 기술 용어를 배워 요구사항을 AI 코딩 에이전트에게 명확하고 모호함 없이 설명할 수 있게 되는 것 (예: "shared folder thing" 대신 "namespace package"이라고 말하는 법)

그들은 소프트웨어 엔지니어가 되려는 것이 아닙니다. 그들은 이미 잘하는 일을 증폭시키는 초능력으로서 코딩을 원합니다. 처음부터 코드를 작성할 필요는 없습니다. 코드를 읽고, 이해하고, 지시할 수 있어야 합니다.

이 접근 방식이 효과적인 이유

이 스킬은 전통적인 CS 교육을 뒤집습니다. 기존 모델은: 수년간 개념을 암기 → 결국 무언가 구축 → 마침내 요점을 깨닫는 순서입니다 (대부분의 사람은 3단계 전에 포기합니다). 이 모델은: 먼저 구축 → 작동하는 것을 경험 → 이제 작동 방식을 이해합니다.

학습자는 전통적인 학생들이 가지지 못한 맥락을 이미 가지고 있습니다 — 앱을 사용해봤고, 무엇을 하는지 알며, 심지어 자연어로 기능을 설명할 수도 있습니다. 강좌는 그들이 있는 곳에서 시작합니다: "당신이 클릭하는 그 버튼, 여기 클릭했을 때 내부에서 일어나는 일이 있습니다."

모든 모듈은 "어떻게 작동하는가"보다 먼저 "왜 신경 써야 하는가"에 답합니다. "왜 신경 써야 하는가"에 대한 답은 항상 실용적입니다: 이 지식이 AI를 더 잘 조종하고, 더 빠르게 디버깅하고, 더 똑똑한 아키텍처 결정을 내리는 데 도움이 되기 때문입니다.

디렉토리 기반 출력은 의도적입니다: CSS/JS를 콘텐츠와 분리하면 AI가 상용구를 재생성하지 않고, 각 모듈이 독립적으로 작성되며(출력 크기를 작게 유지하고 품질을 높임), 조립된 index.html은 설정 없이 오프라인에서 작동합니다.

---

프로세스

1단계: 코드베이스 분석

강좌 HTML을 작성하기 전에 코드베이스를 깊이 이해하세요. 모든 핵심 파일을 읽고, 데이터 흐름을 추적하고, "등장인물"(주요 컴포넌트/모듈)을 식별하고, 그들이 어떻게 통신하는지 매핑하세요. 여기서 철저함이 성과를 냅니다 — 더 많이 이해할수록 강좌가 더 좋아집니다.

추출할 것:

• 주요 "행위자"(컴포넌트, 서비스, 모듈)와 그들의 책임
• 기본 사용자 여정(누군가 앱을 처음부터 끝까지 사용할 때 일어나는 일)
• 주요 API, 데이터 흐름 및 통신 패턴
• 영리한 엔지니어링 패턴(캐싱, 지연 로딩, 오류 처리 등)
• 실제 버그 또는 함정(git 기록이나 주석에 표시된 경우)
• 기술 스택과 각 부분이 선택된 이유

앱이 무엇을 하는지 스스로 파악하세요. README, 주요 진입점 및 UI 코드를 읽으면 됩니다. 사용자에게 제품을 설명해달라고 요청하지 마세요 — 사용자도 잘 모를 수 있습니다. 강좌는 앱이 하는 일을 평이한 언어로 간략히 설명하는 것으로 시작한 후("이것이 하는 일과 흥미로운 이유"), 작동 방식에 대해 깊이 들어가기 전에 설명해야 합니다. 첫 번째 모듈은 구체적인 사용자 행동으로 시작해야 합니다 — "YouTube URL을 붙여넣고 Analyze를 클릭한다고 상상해보세요. 내부에서 일어나는 일은 이렇습니다."

2단계: 커리큘럼 설계

강좌를 4-6개 모듈로 구성하세요. 대부분의 강좌는 4-6개면 충분합니다. 코드베이스에 가르칠 만한 뚜렷한 개념이 그만큼 많을 경우에만 7-8개로 늘리세요. 더 적고 더 나은 모듈이 더 많고 얇은 모듈보다 낫습니다.

전개는 항상 학습자가 이미 알고 있는 것(사용자 대면 동작)에서 시작하여 그들이 모르는 것(내부 코드)으로 이동합니다. 확대하는 것으로 생각하세요: 경험에서 시작하여 넓게, 그런 다음 점진적으로 레이어를 벗겨냅니다.

모듈 위치	목적	바이브 코더에게 중요한 이유
1	"이 앱이 하는 일 — 그리고 사용할 때 일어나는 일"	제품(하는 일, 흥미로운 이유)으로 시작한 다음, 핵심 사용자 작업을 코드로 추적합니다. 모든 것을 구체적인 것에 기반합니다.
2	행위자 만나기	어떤 컴포넌트가 존재하는지 알아 AI에게 "이 로직을 X에 넣고 Y에 넣지 마"라고 말할 수 있습니다.
3	조각들이 소통하는 방식	데이터 흐름을 이해하여 "표시되지 않음" 문제를 디버깅할 수 있습니다.
4	외부 세계(API, 데이터베이스)	무엇이 외부인지 알아 비용, 속도 제한 및 실패 모드를 평가할 수 있습니다.
5	영리한 트릭	패턴(캐싱, 청킹, 오류 처리)을 배워 AI에게 요청할 수 있습니다.
6	고장날 때	디버깅 직관을 구축하여 AI 버그 루프에서 벗어날 수 있습니다.
7	큰 그림	전체 아키텍처를 보아 다음에 무엇을 구축할지 더 나은 결정을 내릴 수 있습니다.

이것은 메뉴이지 체크리스트가 아닙니다. 코드베이스에 맞는 모듈을 선택하세요 — 간단한 CLI 도구는 7개가 아닌 4개가 필요합니다. 코드베이스의 복잡성에 맞게 전개를 조정하세요.

핵심 원칙: 모든 모듈은 실용적인 기술 — AI 조종, 디버깅, 의사 결정 — 로 연결되어야 합니다. 모듈이 학습자가 무언가를 더 잘 하도록 돕지 않는다면, 잘라내거나 다시 구성하여 그렇게 하도록 만드세요.

각 모듈은 다음을 포함해야 합니다:

• 3-6개의 화면(모듈 내에서 흐르는 하위 섹션)
• 최소 하나의 코드-영어 번역
• 최소 하나의 인터랙티브 요소(퀴즈, 시각화 또는 애니메이션)
• 보편적인 CS 통찰력이 담긴 하나 또는 두 개의 "아하!" 콜아웃 박스
• 기술 개념을 일상 생활에 연결하는 은유 — 단, 같은 은유를 여러 모듈에 걸쳐 절대 재사용하지 말고, "레스토랑" 은유(너무 많이 사용됨)를 절대 기본값으로 사용하지 마세요. 개념에 유기적으로 맞는 은유를 선택하세요. 가장 좋은 은유는 개념에 불가피하게 느껴지고 강요된 느낌이 없습니다.

필수 인터랙티브 요소 (모든 강좌는 다음을 모두 포함해야 함):

• 그룹 채팅 애니메이션 — 강좌 전체에 최소 하나. 컴포넌트 간의 iMessage/WeChat 스타일 대화입니다. 가장 매력적인 요소 중 하나이므로, 모듈의 개념을 행위자 간의 대화로 창의적으로 구성해야 하더라도 항상 나타나야 합니다.
• 메시지 흐름 / 데이터 흐름 애니메이션 — 강좌 전체에 최소 하나. 행위자 간의 단계별 패킷 애니메이션입니다. 코드베이스에 요청/응답, 데이터 파이프라인 또는 다단계 프로세스가 있다면 애니메이션으로 만드세요. 모든 코드베이스에는 데이터가 흐르는 곳이 있습니다 — 찾으세요.
• 코드 ↔ 영어 번역 블록 — 모듈당 최소 하나 (위에서 이미 요구했지만, 재차 강조합니다: 이것은 협상 불가입니다).
• 퀴즈 — 모듈당 최소 하나 (객관식, 시나리오, 드래그 앤 드롭, 버그 찾기 — 어떤 퀴즈 유형이든 가능).
• 용어집 툴팁 — 모든 기술 용어에 대해, 모듈당 첫 사용 시.

이 다섯 가지 요소 유형은 모든 강좌의 백본입니다. 다른 인터랙티브 요소(아키텍처 다이어그램, 레이어 토글, 패턴 카드 등)는 선택 사항이며 적합할 때 추가해야 합니다. 그러나 위의 다섯 가지는 항상 있어야 합니다 — 예외 없음.

커리큘럼을 승인을 위해 제시하지 마세요 — 그냥 구축하세요. 사용자는 기획 문서가 아닌 강좌를 원합니다. 내부적으로 커리큘럼을 설계한 다음 바로 구축으로 넘어가세요. 변경 사항이 있으면 결과를 본 후 알려줄 것입니다.

커리큘럼을 설계한 후, 사용할 구축 경로를 결정하세요:

• 간단한 코드베이스 (단일 목적 CLI, 소규모 웹 앱, 라이브러리, 하나의 명확한 진입점, 5개 이하 모듈) → 3단계 순차로 바로 이동.
• 복잡한 코드베이스 (풀스택 앱, 여러 서비스, 콘텐츠 중심 사이트, 모노레포, 또는 6개 이상 모듈) → 먼저 2.5단계로 이동한 다음 3단계 병렬로 이동.

2.5단계: 모듈 브리프 (복잡한 코드베이스만 해당)

복잡한 코드베이스의 경우, HTML을 작성하기 전에 각 모듈에 대한 브리프를 작성하세요. 이것은 병렬 작성을 가능하게 하는 중요한 단계입니다 — 각 브리프는 에이전트가 코드베이스를 다시 읽지 않고도 필요한 모든 것을 제공합니다.

references/module-brief-template.md를 읽어 템플릿 구조를 확인하세요. references/content-philosophy.md를 읽어 브리프 작성을 안내해야 하는 콘텐츠 규칙을 확인하세요.

각 모듈에 대해 course-name/briefs/0N-slug.md에 브리프를 작성하고 다음을 포함하세요:

• 교육 전개(은유, 시작 훅, 핵심 통찰력)
• 사전 추출된 코드 스니펫(코드베이스에서 복사-붙여넣기, 파일 경로 및 줄 번호 포함)
• 구축에 충분한 세부 정보가 있는 인터랙티브 요소 체크리스트
• 작성 에이전트가 필요한 참조 파일의 섹션
• 이전 및 다음 모듈이 다루는 내용(전환용)

코드 스니펫은 중요한 토큰 절약 단계입니다. 브리프에 미리 추출함으로써 작성 에이전트는 코드베이스를 전혀 읽을 필요가 없습니다.

3단계: 강좌 구축

강좌 출력물은 디렉토리이지 단일 파일이 아닙니다. 모든 CSS와 JS는 사전 구축된 참조 파일입니다 — 절대 재생성하지 마세요. 여러분의 작업은 HTML 콘텐츠만 작성하는 것입니다.

출력 구조:

course-name/
  styles.css       ← references/styles.css에서 그대로 복사
  main.js          ← references/main.js에서 그대로 복사
  _base.html       ← 사용자 정의 셸 (제목, 강조 색상, 탐색 점)
  _footer.html     ← references/_footer.html에서 그대로 복사
  build.sh         ← references/build.sh에서 그대로 복사
  briefs/          ← 모듈 브리프 (복잡한 코드베이스만, 빌드 후 삭제 가능)
  modules/
    01-intro.html
    02-actors.html
    ...
  index.html       ← build.sh로 조립 (수동으로 작성하지 않음)

1단계 (두 경로 모두): 설정 — 강좌 디렉토리를 만듭니다. 다음 네 개의 파일을 Read + Write를 사용하여 그대로 복사합니다 (내용을 재생성하지 마세요):

• references/styles.css → course-name/styles.css
• references/main.js → course-name/main.js
• references/_footer.html → course-name/_footer.html
• references/build.sh → course-name/build.sh

2단계 (두 경로 모두): _base.html 사용자 정의 — references/_base.html을 읽은 다음 정확히 세 가지를 대체하여 course-name/_base.html에 작성합니다:

• COURSE_TITLE의 두 인스턴스 → 실제 강좌 제목
• 네 개의 ACCENT_* 플레이스홀더 → 선택한 강조 색상 값 (_base.html의 주석에서 하나의 팔레트 선택)
• NAV_DOTS → 모듈당 하나의 <button class="nav-dot" ...>

3단계: 모듈 작성 — 여기서 경로가 갈라집니다.

순차 경로 (간단한 코드베이스)

references/content-philosophy.md와 references/gotchas.md를 읽습니다. 그런 다음 모듈을 하나씩 작성합니다. 각 모듈에 대해 <section class="module" id="module-N"> 블록과 그 내용만 포함하는 course-name/modules/0N-slug.html을 작성합니다. <html>, <head>, <body>, <style> 또는 <script> 태그는 포함하지 마세요.

각 인터랙티브 요소 유형에 대한 HTML 패턴은 references/interactive-elements.md를 읽으세요. 시각적 규칙은 references/design-system.md를 읽으세요.

병렬 경로 (복잡한 코드베이스)

최대 3개씩 배치로 하위 에이전트에 모듈을 할당합니다. 각 에이전트는 다음을 받습니다:

• 해당 모듈 브리프 (course-name/briefs/에서)
• references/content-philosophy.md와 references/gotchas.md
• 브리프에 나열된 references/interactive-elements.md와 references/design-system.md의 섹션만

각 에이전트는 모듈 파일을 course-name/modules/에 작성합니다. 짧은 모듈(3개 화면, 하나의 퀴즈)은 페어링 가능 — 두 개의 브리프를 한 에이전트에 제공.

에이전트가 받지 않는 것: 전체 코드베이스(스니펫은 브리프에 있음), SKILL.md, 다른 모듈의 브리프, 또는 불필요한 참조 파일 섹션.

모든 에이전트가 완료된 후, 메인 컨텍스트에서 빠른 일관성 검사를 수행합니다: 탐색 점이 모듈과 일치하는지, 모듈 간 전환이 일관된지, 눈에 띄는 어조 변화가 없는지 확인합니다.

4단계 (두 경로 모두): 조립 — 강좌 디렉토리에서 build.sh를 실행합니다:

cd course-name && bash build.sh

이것은 index.html을 생성합니다. 브라우저에서 엽니다.

중요 규칙:

• styles.css 또는 main.js를 절대 재생성하지 마세요 — 항상 그대로 복사