Codebase to Course (Claude Skill) — 설치 & 라이브 데모

왜 쓰나요

핵심 기능

단일 파일 HTML 출력 — 빌드 파이프라인 없음
README가 아닌 실제 코드에서 생성된 아키텍처 개요
모듈별 '이것이 왜 존재하는가 + 어떻게 작동하는가' 섹션
실제 진입점을 따르는 요청 흐름 안내
줄별 설명이 있는 주석 달린 코드 블록
비엔지니어(PM, 디자이너, 신규 입사자)를 위해 설계됨

라이브 데모

실제 사용 모습

준비됨

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "codebase-to-course-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/zarazhangrui/codebase-to-course",
        "~/.claude/skills/codebase-to-course"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "codebase-to-course-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/zarazhangrui/codebase-to-course",
        "~/.claude/skills/codebase-to-course"
      ],
      "_inferred": true
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "codebase-to-course-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/zarazhangrui/codebase-to-course",
        "~/.claude/skills/codebase-to-course"
      ],
      "_inferred": true
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "codebase-to-course-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/zarazhangrui/codebase-to-course",
        "~/.claude/skills/codebase-to-course"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "codebase-to-course-skill",
      "command": "git",
      "args": [
        "clone",
        "https://github.com/zarazhangrui/codebase-to-course",
        "~/.claude/skills/codebase-to-course"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "codebase-to-course-skill": {
      "command": {
        "path": "git",
        "args": [
          "clone",
          "https://github.com/zarazhangrui/codebase-to-course",
          "~/.claude/skills/codebase-to-course"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add codebase-to-course-skill -- git clone https://github.com/zarazhangrui/codebase-to-course ~/.claude/skills/codebase-to-course

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: Codebase to Course

신규 입사자를 위한 자기 주도 온보딩 코스 생성

👤 엔지니어링 매니저 / 테크 리드 ⏱ ~45 min beginner

언제 쓸까: 입사 제안 수락 후 금요일: '코드를 읽으세요' 대신 실제 온보딩 결과물이 필요할 때.

사전 조건

스킬 설치됨 — git clone https://github.com/zarazhangrui/codebase-to-course ~/.claude/skills/codebase-to-course
레포지토리 체크아웃됨 — 표준 git clone

흐름

레포지토리 스캔

codebase-to-course: ./our-app를 스캔하세요. 작성하기 전에 먼저 제안된 코스 구조 — 섹션 목록 — 를 출력하세요.✓ 복사됨

→ 구체적인 목차: 아키텍처, 모듈, 요청 흐름
코스 생성

좋아 보입니다. 전체 HTML을 /onboarding/course.html에 생성하세요. 대상 청중: React + Node는 알지만 우리 도메인은 모르는 신규 풀스택 입사자.✓ 복사됨

→ HTML 파일 생성됨; 브라우저에서 열림
정확성 확인

스팟 체크: '인증 흐름' 안내가 src/auth/에 실제로 있는 내용과 일치하나요? 실제 코드를 인용하세요.✓ 복사됨

→ 안내가 실제 파일 경로와 현재 코드를 인용

결과: 팀에 2주 동안의 설명을 절약하는 실제 온보딩 결과물

함정

코스가 너무 길어서 실제로 읽기 어려움 — 최대 섹션 수 지정; 완성도보다 품질
코드 발췌가 오래됨 — 주요 리팩토링 후 재생성; 스킬이 빠름

함께 쓰기: filesystem · git-mcp-idosal

비기술적 PM에게 복잡한 기능 설명

👤 테크 리드 ⏱ ~20 min beginner

언제 쓸까: PM이 '왜 이게 3스프린트나 걸리나요'를 계속 물어볼 때 — 구체적인 결과물이 필요할 때.

흐름

기능으로 범위 제한

codebase-to-course: src/payments/로 범위 제한. 청중: 엔지니어링 배경이 없는 PM. 다이어그램 + 비유 위주, 코드는 최소.✓ 복사됨

→ 코스가 고수준; 코드 블록 최소

결과: PM이 멘탈 모델을 가지고 자리를 떠남

함정

비유가 지나치게 단순화 — 스팟 체크; 스킬은 압력을 받으면 정확성을 선호

오픈 소스 프로젝트를 위한 '작동 방식' 페이지 생성

👤 OSS 메인테이너 ⏱ ~30 min intermediate

언제 쓸까: README에 기능은 있지만 아키텍처 설명이 없을 때.

흐름

문서 페이지로 생성

codebase-to-course: main 브랜치를 스캔하세요. 문서 사이트를 위한 ARCHITECTURE.html을 출력하세요. 대상: 프로젝트를 평가하는 숙련된 개발자.✓ 복사됨

→ 출력이 사려 깊은 기여자 가이드처럼 읽힘

결과: 평가자와 기여자를 위한 더 나은 개발자 경험

함정

코스가 잘못 브랜딩됨 (일반적으로 보임) — 프롬프트에 프로젝트 이름 + 스타일 힌트 전달

조합

다른 MCP와 조합해 10배 효율

codebase-to-course-skill + filesystem

로컬 레포지토리를 읽고 코스 작성

codebase-to-course: ./our-app 스캔, /onboarding/course.html 작성.✓ 복사됨

codebase-to-course-skill + git-mcp-idosal

클론하지 않고 외부 레포지토리 코스화

owner/repo에 GitMCP 사용. 그 위에 codebase-to-course 적용.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출
scan_repo	path	항상 먼저
propose_toc	scan_result, audience	스캔 후, 생성 전
generate_course	scan_result, toc, target_html_path	최종 단계
scope_to_subdir	subdir_path	대형 모노레포 또는 기능 포커스

비용 및 제한

운영 비용

API 쿼터: 해당 없음
호출당 토큰: 상당함 — 스킬이 전체 레포지토리를 읽음 (일반적으로 10k–50k 토큰)
금액: 무료; 모델 토큰 적용
팁: 모노레포에는 scope_to_subdir 사용; 한 번에 전체 코스화 금지

보안

권한, 시크릿, 파급범위

최소 스코프: filesystem-read filesystem-write

자격 증명 저장: 없음

데이터 외부 송신: 없음 — 순수 로컬 읽기/쓰기

생성된 코스에 코드 발췌가 포함될 수 있음; 레포지토리에 시크릿이 있으면 외부 공유 전 검토

문제 해결

자주 발생하는 오류와 해결

코스가 너무 일반적 / 실제 코드를 참조하지 않음

프롬프트를 더 구체적으로; file:line 인용 요청

레포지토리가 너무 커서 컨텍스트 부족

scope_to_subdir 사용; 모듈별 코스를 만들고 링크

HTML 서식 손상됨

스킬에 출력 유효성 검사 요청; 필요시 재생성

대안

Codebase to Course 다른 것과 비교

대안	언제 쓰나	단점/장점
Repomix + 수동 프롬프트	코드베이스를 Claude에 제공하는 방법을 완전히 제어하고 싶을 때	더 많은 설정; 의견 있는 출력 형식 없음
DocsGPT / Mintlify	호스팅된 문서를 원할 때	완전히 다른 제품; 단일 파일 HTML 아님
absolutely-skilled / autodoc	자동 생성된 API 문서를 원할 때	API 참조 ≠ 튜토리얼

Codebase to Course