HenryNdubuaku/maths-cs-ai-compendium 딥다이브
— 수학·CS·AI를 밑바닥부터 손으로 쓴 267,000단어짜리 오픈 교과서

1프로젝트 한 줄 요약

HenryNdubuaku/maths-cs-ai-compendium는 "호기심 많은 실무자를 위한, 관습을 깬 오픈 교과서(an open, unconventional textbook)"를 표방한다. 저자 Henry Ndubuaku가 README에 못 박은 목표는 분명하다 — "시험·면접을 겨우 통과하려는 게 아니라, 원리를 진짜로 이해하게 만든다". 그래서 위키처럼 정의만 나열하지 않고, 직관 → 수식 → 코드 → 직접 풀 과제의 순서로 개념 하나하나를 손으로 풀어 준다.

이 저장소에는 사연이 있다. 저자가 몇 년에 걸쳐 채운 학습 노트를, 2025년 친구들이 DeepMind·OpenAI·Nvidia 면접 준비에 썼고 실제로 합격했다는 것. 저자 본인은 이 내용을 밑천 삼아 Y Combinator에 들어갔다고 적혀 있다. 즉 이 교과서는 "AI 리서치 엔지니어로 취업"이라는 실전 목표에 맞춰 다듬어진, 현장에서 검증된 노트라는 서사를 갖고 있다.

2왜 지금 주목받는가

AI 학습 자료는 넘쳐 나는데 이 저장소가 왜 트렌딩에 올랐을까. 세 가지가 겹쳤다 — ① "이 노트로 DeepMind·OpenAI에 합격했다"는 서사의 흡인력, ② 순수 수학부터 GPU 커널·추론 서빙까지 흩어진 주제를 한 저장소에 밑바닥부터 모은 희소성, ③ MCP 서버와 llms.txt를 얹어 AI 코딩 에이전트가 교과서를 직접 읽게 한 요즘 감각이다.

주목 포인트 1 — "합격 서사"라는 강력한 동기

README의 Background 절은 짧지만 셌다. "내 노트로 친구들이 최상위 AI 랩 면접을 뚫었다"는 한 줄이, 수많은 취업 준비생에게 "그럼 나도 이걸로?"라는 동기를 심는다. 여기에 서문(Foreword)은 크바쉬체프(Kvashchev)의 문제풀이 훈련 실험, "느린 처리자"였던 다윈, 로젠탈 실험 같은 이야기로 "머리는 훈련으로 자란다"는 성장 마인드셋을 깔아, 단순 자료집이 아니라 "학습법까지 코칭하는 책"이라는 인상을 준다.

주목 포인트 2 — 흩어진 걸 한곳에, 그것도 밑바닥부터

보통 이 정도 범위는 여러 강의·교재·블로그로 쪼개져 있다. 선형대수는 이 강의, CUDA는 저 문서, 추론 최적화는 또 다른 논문… 이 저장소는 그 전부를 한 사람의 목소리로 이어 붙였다. 특히 대부분의 ML 학습자가 건너뛰는 시스템 계층(SIMD/GPU, 추론 서빙, ML 시스템 설계)까지 포함한 게 드물다. "모델을 만들 줄 아는 사람"을 넘어 "모델을 빠르게 굴릴 줄 아는 사람"까지 겨냥한다.

주목 포인트 3 — 교과서를 "AI가 읽게" 만들었다

요즘 저장소답게, 이 책은 사람만을 독자로 두지 않는다. mcp/ 폴더의 MCP 서버는 list_topics·read_section·search·recommend·get_examples 5개 도구를 노출해, AI 코딩 에이전트가 "어텐션 관련 절을 찾아 예제 코드를 뽑아 줘" 같은 요청을 처리하게 한다. 사이트 루트의 llms.txt는 전체 목차를 기계가 읽기 좋은 형태로 제공한다. "사람이 공부하는 책 + AI가 참조하는 지식베이스"라는 두 얼굴이 화제성을 키웠다.

3기술 스택 전체 지도

이 저장소의 스택은 앱이 아니라 책을 쓰고·펴내고·AI에게 먹이는 파이프라인이다. 따라서 "백엔드/프론트엔드"가 아니라 ① 콘텐츠(무엇으로 쓰는가), ② 퍼블리싱(어떻게 웹으로 펴내는가), ③ AI 접근(어떻게 에이전트가 읽는가)의 세 축으로 봐야 한다.

① 콘텐츠 계층 — Markdown + LaTeX + 손그림 SVG + JAX 코드

② 퍼블리싱 계층 — MkDocs Material + GitHub Pages 자동 배포

원문은 마크다운이지만, 독자는 예쁜 웹사이트로 읽는다. mkdocs.yml이 MkDocs의 Material 테마로 사이트를 조립하고(다크모드·소셜 카드·MathJax 로딩 javascripts/mathjax.js 포함), .github/workflows/deploy-docs.yml이 커밋이 올라올 때마다 GitHub Pages로 자동 배포한다. 즉 저자는 마크다운만 쓰면 되고, 사이트 빌드·배포는 CI가 알아서 한다.

③ AI 접근 계층 — TypeScript MCP 서버 + llms.txt

4아키텍처 심화 분석

이 저장소엔 서버도 런타임도 없다. 그래서 "아키텍처"는 지식이 어떤 순서로 쌓이도록 설계됐는가, 그리고 그 지식을 MCP 서버가 어떻게 꺼내 주는가로 요약된다. 이 둘을 뜯어보자.

핵심 설계 1 — 4층으로 쌓는 커리큘럼(순수수학 → ML → 도메인 → 시스템)

20개 챕터는 무작위 나열이 아니라 아래층이 위층의 전제가 되는 4개 층으로 설계됐다. 벡터·행렬 없이는 머신러닝을, 머신러닝 없이는 트랜스포머를, 그리고 그 모델을 실제로 굴리려면 GPU·추론 시스템을 알아야 한다는 흐름이 순서에 녹아 있다.

이 구조의 묘미는 위로 갈수록 추상이 아니라 구체로 간다는 점이다. 보통 커리큘럼은 응용에서 시작해 이론으로 파고들지만, 여기선 반대로 이론(수학)에서 시작해 하드웨어(GPU 커널)로 내려간다. "왜 되는가"를 먼저 세우고 "어떻게 빠르게 굴리는가"로 끝맺는다.

핵심 설계 2 — 모든 절이 따르는 4단 골격(직관→수식→코드→과제)

105개 파일이 거의 같은 리듬을 탄다. 개념을 비유로 감 잡게 하고 → 수식으로 정밀화하고 → JAX/NumPy 코드로 구현해 보이고 → 마지막에 직접 풀 코딩 과제로 닫는다. 실제로 105개 중 84개 파일이 끝에 과제 섹션을 달고 있다.

과제 헤딩이 챕터 성격에 따라 갈린다는 점이 세심하다 — 일반 챕터는 use CoLab or notebook, 자료구조 챕터는 NeetCode 문제, GPU 챕터는 compile with nvcc, C++ 챕터는 g++ 또는 riscv64 크로스컴파일러로처럼 그 장에서 실제로 쓰는 도구로 손을 움직이게 유도한다.

핵심 설계 3 — MCP 서버가 교과서를 도구로 노출(그리고 지금 고장 난 이유)

MCP 서버는 마크다운 더미를 5개 도구로 감싼다. 그중 recommend는 사용자의 키워드를 llms.txt의 절 설명과 대조해 점수를 매기고, get_examples는 지정한 언어·챕터의 펜스드 코드 블록만 뽑아 준다. 그런데 하루 전 커밋이 문제를 냈다.

# mcp 서버는 디렉토리명을 이 정규식으로 파싱한다
const CHAPTER_RE = /^chapter (\d{2}): (.+)$/;   # ← 콜론(:) 기대

# 하지만 어제 커밋(9e3c096)이 윈도우 호환을 위해 폴더명을 바꿨다
#   전:  "chapter 01: vectors"     (콜론)
#   후:  "chapter 01 - vectors"    (대시)   ← 디스크의 실제 폴더

→ 정규식이 대시 폴더명과 안 맞음 → getChapters() 가 빈 배열 반환
→ list_topics·read_section·search·recommend·get_examples 전부 무력화
#  mkdocs.yml 내비 · llms.txt 도 아직 콜론 형식 → 사이트 링크도 404 위험

5디렉토리 구조 해부

구조는 "책"답게 직관적이다. 챕터마다 폴더 하나, 그 안에 번호 매긴 절 마크다운이 들어 있고, 모든 도해는 images/에 모여 있다. 여기에 퍼블리싱 설정(mkdocs.yml)과 AI 접근(mcp/, llms.txt)이 루트에 얹힌다.

규모를 숫자로 보면 — 마크다운 105개·총 29,604줄·약 267,000단어, SVG 263개(+로고 png 1개), 챕터 폴더 20개. 분량은 고르지 않다. 가장 두꺼운 곳은 16장 SIMD·GPU(3,722줄/8파일), 다음이 09장 오디오·음성(3,250줄), 14장 자료구조·알고리즘(2,695줄/6파일), 07장 전산언어학(2,119줄) 순이다. 반대로 01장 벡터(623줄)·02장 행렬(816줄)은 얇다.

6학습 포인트

먼저 전체 지도를 보자. 18개(+2개 예고) 챕터를 저자의 한 줄 요약과 함께 4개 그룹으로 묶으면 이렇다.

배울 것 1 — "언어가 되는 수학"을 제대로 깐다

많은 학습자가 딥러닝을 먼저 만지고 수학을 나중에 때운다. 이 책은 반대로 벡터·행렬·미적분·확률·정보이론을 앞에 단단히 깐다. SVD가 왜 차원 축소·추천의 뼈대인지, 크로스엔트로피가 왜 정보이론에서 나오는지 같은 "당연히 아는 척했지만 실은 애매했던" 연결을 메운다. 뒤의 모든 AI 챕터가 이 5개 장의 언어로 쓰여 있어, 여기가 흔들리면 위층이 무너진다.

배울 것 2 — 현대 AI의 전 영역을 한 목소리로

NLP·비전·음성·멀티모달·로보틱스·그래프를 따로따로가 아니라 하나의 서술로 관통한다. 트랜스포머가 어떻게 언어에서 비전(ViT)·멀티모달(CLIP/VLM)·로보틱스(VLA)로 번져 갔는지, 확산모델이 이미지에서 어떻게 오디오·비디오로 확장됐는지를 이어서 읽을 수 있다. 파편적으로 알던 최신 기법들이 하나의 지도 위에 배치되는 경험이다.

배울 것 3 — ML 학습자가 늘 건너뛰는 "시스템 계층"

이 책의 진짜 차별점은 여기 있다. 대부분의 AI 교재는 모델을 짜는 데서 멈추지만, 여기선 그 모델을 하드웨어에서 어떻게 빠르게 굴리는가까지 내려간다 — SIMD 인트린식과 CUDA 커널, Triton/Pallas, GPTQ·AWQ·BitNet 양자화, Flash·Ring 어텐션, vLLM의 PagedAttention, 투기적 디코딩. "리서치 엔지니어" 채용에서 실제로 갈리는, 모델과 실리콘 사이의 그 층을 정면으로 다룬다.

배울 것 4 — 콘텐츠가 아니라 "공부하는 법"까지

README의 How To Study Better 절은 저자가 실제로 쓴 2단계 학습법을 준다. 1단계(누적 읽기)는 수업 후 그날 노트를 자기 전 다시 읽고, 다음 학습 땐 처음부터 되짚은 뒤 부족한 부분을 채우는 방식(뇌가 패턴을 잇게 둔다). 2단계(그림자 읽기)는 시험 전, 소제목만 보고 책을 덮은 채 기억으로 설명을 써 보고 틀린 곳만 다시 읽는 것 — 저자는 이를 "마스킹 언어모델과 비슷하다"고 표현한다. 그리고 마지막은 언제나 코드로 구현이다.

7시스템 · 실행 요구사항

이 저장소는 "쓰임새"에 따라 준비물이 셋으로 갈린다 — ① 읽기만(가장 쉬움), ② 코드 과제 실행(파이썬~GPU), ③ MCP로 AI에 연결(Node + 버그 수정).

MCP를 Claude Code에 붙이는 개념 흐름(버그 수정 포함)

# 1) 클론
git clone https://github.com/HenryNdubuaku/maths-cs-ai-compendium.git
cd maths-cs-ai-compendium

# 2) (지금은 필수) 정규식을 대시 폴더명에 맞게 수정
#    mcp/ 안의 CHAPTER_RE 를 콜론(:) → 대시( - ) 로
const CHAPTER_RE = /^chapter (\d{2}) - (.+)$/;   # 콜론을 대시로

# 3) MCP 서버 실행(예시) — 교과서 루트를 알려 준다
COMPENDIUM_ROOT=$(pwd) npx tsx mcp/server.ts
#    이후 Claude Code/Cursor의 MCP 설정에 이 서버를 등록하면
#    list_topics·search·get_examples 같은 도구를 대화 중 호출 가능

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

저장소 · 제작자
· GitHub: github.com/HenryNdubuaku/maths-cs-ai-compendium (Markdown/MkDocs · 챕터 20개(18 완성+2 예고) · Apache-2.0)
· 온라인으로 읽기: README 상단의 "Read online"(GitHub Pages) 링크 — 수식·도해가 렌더된 사이트
· 저자: Henry Ndubuaku (Y Combinator 창업자 · 온디바이스 추론 스타트업 Cactus — 16·17장에 실제 사례로 등장)
· 최신 커밋: 9e3c096 (2026-07-16, "윈도우 호환 위해 챕터 폴더명 콜론→대시 개명")

추천 시작 지점(클론/사이트)
· chapter 01 - vectors/ — 수학 토대의 출발점(얇아서 부담 적음)
· chapter 06 - machine learning/ — ML 코어, 경사하강·역전파
· chapter 07 - computational linguistics/ — 트랜스포머·어텐션(현대 AI의 중심축)
· chapter 17 - ai inference/ — 추론 최적화(리서치 엔지니어 차별 포인트)

배경 지식 · 원전
· MkDocs / Material for MkDocs(퍼블리싱) · Model Context Protocol(MCP 서버)
· JAX 공식 문서(코드 주력) · NeetCode(14장 알고리즘 문제)
· vLLM · PagedAttention 논문(17장 추론 서빙의 원전)