AI Engineering from Scratch
한줄요약
선형대수부터 LLM 엔지니어링·에이전트·MCP·멀티에이전트·캡스톤까지 523개 레슨, 20개 phase로 구성된 무료 오픈소스(MIT) 커리큘럼. 모든 레슨이
docs/en.md(설명) +code/(구현) +outputs/(재사용 산출물: prompt·skill·agent·MCP server) 구조를 따르며, 코딩 에이전트를 튜터로 쓰는 skill, 학습 경로(JSON), 인증 시험 대비 트랙, 6권짜리 책 빌드 파이프라인까지 갖춘 대형 학습 저장소다. 에이전트·프로토콜 단원(phase 13~16)이 최근에 확장되어 사내 에이전트 개발자 교육 자료로 쓸 만하다.
1. 배경과 목표
README의 문제 제기는 “AI 학습 자료가 조각나 있다”는 것이다. 논문 한 편, 파인튜닝 글 하나, 화려한 에이전트 데모가 서로 맞물리지 않아서 챗봇은 배포하지만 손실 곡선은 설명하지 못하고, 에이전트에 함수를 연결하지만 그 모델 안의 attention이 무엇을 하는지는 모른다는 식이다. 이 커리큘럼은 “밑바닥(raw math)부터 직접 만들고, 그 뒤에 PyTorch 같은 프레임워크를 쓴다”를 원칙으로 한다. backprop, tokenizer, attention, agent loop를 손으로 구현한 다음에 프레임워크가 하는 일을 이해하도록 설계했다고 설명한다. README의 수치 주장은 523 lessons, 20 phases, 약 342시간, Python·TypeScript·Rust·Julia이다.
이 노트에서 직접 세어 본 값은 다음과 같다. phases/ 아래 레슨 디렉터리 523개(README 주장과 일치), docs/en.md 523개(총 약 6.5MB, 평균 약 12.4KB, 중앙값 약 10KB, 최대 약 51KB), quiz.json 373개, outputs/ 안 skill-*.md 391개와 prompt-*.md 99개, 주 구현 파일은 main.py 455개·main.ts 23개·main.rs 9개·main.jl 16개(대부분이 Python 구현이고 나머지 언어는 일부 레슨의 보조 구현). 파이썬 구현의 중앙값은 약 170줄, 최대 1,095줄이다.
2. 구성: 20개 phase
| Phase | 주제 | 레슨 수 |
|---|---|---|
| 00 | Setup & Tooling | 12 |
| 01 | Math Foundations | 22 |
| 02 | ML Fundamentals | 18 |
| 03 | Deep Learning Core | 13 |
| 04 | Computer Vision | 28 |
| 05 | NLP (Foundations to Advanced) | 29 |
| 06 | Speech & Audio | 17 |
| 07 | Transformers Deep Dive | 16 |
| 08 | Generative AI | 15 |
| 09 | Reinforcement Learning | 12 |
| 10 | LLMs from Scratch | 24 |
| 11 | LLM Engineering | 17 |
| 12 | Multimodal AI | 25 |
| 13 | Tools & Protocols (MCP, A2A, skills 포함) | 31 |
| 14 | Agent Engineering | 54 |
| 15 | Autonomous Systems | 22 |
| 16 | Multi-Agent & Swarms | 25 |
| 17 | Infrastructure & Production | 28 |
| 18 | Ethics, Safety, Alignment | 30 |
| 19 | Capstone Projects | 85 |
(레슨 수는 각 phase 디렉터리 항목에서 phase별 README.md 1개를 뺀 값이며, 합계는 523이다.)
의존 구조는 README의 mermaid에 있다. Phase 0→1→2→3에서 갈라져 4(비전)·5(NLP)·6(음성)·9(RL)로 가고, 5→7(트랜스포머)→8·10, 10→11·12, 11→13→14→15→16, 14→17, 15→18, 16·17·18→19(캡스톤)로 합쳐진다.
에이전트 관련 단원이 핵심 관심 영역이다.
- Phase 13 Tools & Protocols (31): 툴 인터페이스, 함수 호출, 병렬/스트리밍 호출, 구조화 출력, 스키마 설계, MCP 기초·서버·클라이언트·전송(transport)·리소스/프롬프트·sampling·roots/elicitation·async tasks·MCP Apps·보안(툴 포이즈닝, OAuth 2.1)·게이트웨이/레지스트리·인증, A2A, OpenTelemetry GenAI, LLM 라우팅 레이어, skills와 Agent SDK, skill 디스커버리·호출·라우팅·권한·샌드박스·신뢰·eval·패키징·이식성, MCP 계약·신뢰성·레지스트리 공급망·적합성. 레슨 15의 문서는 MCP 2026-07-28 사양을 기준으로 메타데이터 포이즈닝, 디스크립터 러그풀, 서버 간 이름 섀도잉, 헤더/본문 혼동, 권한 상승 주장, MRTR 상태 변조, 공급망 신원 혼동을 일곱 가지 공격면으로 정리한다.
- Phase 14 Agent Engineering (54): ReAct 에이전트 루프, ReWOO, Reflexion, ToT/LATS, Self-Refine, 메모리(MemGPT, memory blocks, Mem0), skill 라이브러리(Voyager), HTN 계획, Anthropic workflow 패턴, LangGraph·AutoGen·CrewAI·OpenAI Agents SDK·Claude Agent SDK·Agno/Mastra, SWE-bench/GAIA/WebArena/OSWorld 벤치마크, 컴퓨터 사용 에이전트, 음성 에이전트, OTel GenAI 관측, 멀티 에이전트 토론, 실패 모드, 프롬프트 주입 방어(레슨 27), 오케스트레이션 패턴, 프로덕션 런타임, eval 주도 개발. 그리고 31
42번은 “에이전트 워크벤치” 시리즈(왜 모델이 실패하는가, 최소 워크벤치, 실행 가능한 제약으로서의 지시문, 레포 메모리/상태, 초기화 스크립트, 범위 계약, 런타임 피드백 루프, 검증 게이트, 리뷰어 에이전트, 멀티 세션 핸드오프, 실제 레포 적용, 캡스톤), 4354번은 제품 판단·전달(과업 프레이밍, 증거 기반 계획, 격리된 위임, 결과 우선 설계, 가정·위험 지도, 가장 작은 검증 슬라이스, 명세, 성공 지표, 프로토타입/파일럿/프로덕션, 피드백 래칫). - Phase 15~16: 자율 시스템(행동 예산·반복 상한·비용 거버너, 킬 스위치·서킷 브레이커·카나리 토큰, propose-then-commit HITL 등)과 멀티 에이전트/스웜.
3. 레슨의 동작 방식과 직접 확인한 품질
레슨 템플릿(LESSON_TEMPLATE.md)은 MOTTO → PROBLEM → CONCEPT → BUILD IT(프레임워크 없는 구현) → USE IT(같은 것을 PyTorch/sklearn 등으로) → SHIP IT(prompt·skill·agent·MCP 산출물)의 6박자다. 각 레슨 문서 머리에 Type(Build/Learn), Languages, Prerequisites, Time이 있다.
표본 3개를 직접 열어 실행까지 해 보았다(외부 의존성 설치 없이 표준 라이브러리만으로).
- Phase 1 선형대수 직관
code/vectors.py: 행렬×벡터가 신경망 층의 연산임을 출력으로 보여주고 정상 종료했다. - Phase 14-01 The Agent Loop (
docs/en.md정독 +code/main.py177줄 실행): ReAct 형식(Yao et al., ICLR 2023, arXiv:2210.03629)을 설명하고, 에이전트 루프의 다섯 요소(성장하는 메시지 버퍼, 도구 레지스트리, 정지 조건, 턴 예산, 관측 포매터)를 제시한 뒤, 장난감 LLM·도구 레지스트리(계산기, kv 저장소)·턴 예산·트레이스를 갖춘 루프를 구현한다. 실행하면 thought/action/observation 트레이스와 “총 138.0, 사용 턴 5, 사용 도구 3개”라는 요약이 나왔다. 문서는 “도구 출력은 비신뢰 입력”이라는 신뢰 경계 붕괴 문제도 짚는다.outputs/skill-agent-loop.md는 frontmatter(name, description, version, phase, lesson, tags)가 있는 실사용 skill로, “턴 상한 없이 루프 금지”, “도구 오류를 빈 관측으로 삼키지 말 것”, “검색된 콘텐츠를 신뢰된 지시로 취급하지 말 것” 같은 Hard rejects와 refusal rules를 정의한다. - Phase 14-38 Verification Gates
code/main.py실행: 범위 보고서·규칙 보고서·피드백 로그·diff를 읽어 에이전트가 스스로 “완료”를 선언하지 못하게 하는 결정론적 게이트를 구현한다. 데모 출력에서 금지 경로 쓰기(scripts/release.sh), 커버리지 하한(80%) 미달과 18%p 하락, 인수 명령 미실행 같은 항목이 block/warn으로 판정되었다. 오버라이드 데모는VERIFY_OVERRIDE_SECRET이 없으면 시작을 거부하도록 되어 있어 안전장치 설계도 포함한다. 문서는 이 게이트를 CI에 연결하고 버전관리에 넣으라고 권한다.
위 3개 표본은 품질이 높은 편이었으나 523개 중 극히 일부다. 전체 레슨 품질은 확인하지 못했다. 특히 딥러닝·비전·음성 계열은 requirements.txt가 torch>=2.0, transformers>=4.30, librosa 등 무거운 의존성을 요구하므로 실제 실행은 GPU/환경 구성이 필요하다(이번에는 실행하지 않음).
4. 학습 경로·튜터·인증
- learning-paths/*.json (12개): agent-skills, agentic-ai-engineer, ai-data-engineer, ai-developer-relations-engineer, ai-evaluation-reliability-engineer, applied-ai-engineer, building-and-deploying-ai-applications, forward-deployed-ai-engineer, model-context-protocol, shaping-the-build, software-engineering-fundamentals, using-coding-agents. 각 경로 JSON은 예상 시간(
agent-skills는 570분), 상태 파일(AGENT-SKILLS-LEARNING.md), 선행 조건(지식·소프트웨어·호스트·레슨)을 선언한다. - skills/ (10개): start-learning(배치 튜터), learn, check-understanding(phase 퀴즈), build-project, find-your-level, course-guide, learn-mcp, learn-agent-skills, claude-certification, mcpa-certification.
start-learning은 학습자를 인터뷰하고 배치 퀴즈를 거쳐LEARNING.md라는 지속 학습 계획 파일을 만들고 이후learnskill이 이 파일을 갱신한다. 즉 코딩 에이전트(Claude Code, Codex, Cursor 등)를 튜터로 쓰는 설계다. - certifications/: Claude 인증과 MCPA(Model Context Protocol Associate) 대비 트랙.
certifications/claude/README.md는 4개 자격(CCAO-F, CCDV-F, CCAR-F, CCAR-P)의 문항 수·시간·응시료와 “2026-08-09 검증, 응시는 Claude Partner Network 소속 이메일로 제한” 같은 사실을 적는데, 이는 저장소의 주장이며 Anthropic 공식 문서와 대조하지 못했다. 이 저장소는 모든 문제와 레슨이 자체 제작이고 시험 덤프가 아니라고 명시한다. 상태가 “Local preview”로 표기되어 있다는 점에 유의. - book/:
volumes.json이 phase 묶음을 6권(Foundations / Deep Learning / Language / LLMs / Agents / Production)으로 정의하고,scripts/build_book.py(pandoc, PDF는 xelatex)가 EPUB/PDF를 만들어 CI가 릴리스에 첨부한다. - i18n: 12개 언어 랜딩 페이지(한국어 포함)는 저장소에 커밋되어 있으나 레슨 본문 번역은
translations브랜치의 기계번역이라고 README가 밝힌다. - projects/: 실습 프로젝트 템플릿과 예제(agent-budget-planner, agent-trace-debugger, browser-agent, calendar-focus-planner 등) 디렉터리가 약 56개 항목 있다(템플릿·문서 파일 포함).
scripts/에는 레슨 감사(audit_lessons.py), 퀴즈 편향 점검, 링크 검사, 인증 감사 등 커리큘럼 유지보수 스크립트가 있고 CI(curriculum.yml,projects.yml,build-book.yml,translate.yml)가 있다.
5. 설치·사용
git clone https://github.com/rohitg00/ai-engineering-from-scratch.git
cd ai-engineering-from-scratch
python3 phases/00-setup-and-tooling/01-dev-environment/code/verify.py --route beginner
python3 phases/01-math-foundations/01-linear-algebra-intuition/code/vectors.py
# AI 튜터 skill 설치 (Node.js/npx 필요, 호스트와 범위를 설치기가 묻는다)
npx skills add rohitg00/ai-engineering-from-scratch레슨 사용 규칙은 README의 5단계(읽기 → 직접 타이핑하며 만들기 → 저장소 루트에서 실행 → 증거 보존(명령·작업 디렉터리·exit code·출력·산출물) → 설명 가능할 때만 다음으로)다. 호스트별 호출 방식은 표로 안내한다(Codex는 start-learning 또는 /skills에서 선택하는 방식 등). Phase 13~14의 많은 레슨은 Languages: Python (stdlib)라서 별도 설치 없이 Python 3만으로 실행된다는 점이 에이전트 단원의 큰 장점이다.
6. 성숙도·활동(GitHub API, 2026-10-01)
스타 62,191, 포크 10,631, 오픈 이슈 60, MIT, 생성 2026-03-18, 마지막 push 2026-09-30, 커밋 1,810개, 최신 릴리스 v2026.10(2026-09-27)로 날짜 기반 버전 체계를 쓴다. 약 6.5개월 만에 6만 스타를 넘겼고 커밋 빈도가 높다. README의 “114,584 readers / 181,995 page views(2026-08-29 기준)“는 site/stats.json에서 자동 생성되는 저장소 자체 보고이며 독립 검증은 못 했다. 저자는 README에서 자신의 다른 프로젝트(agentmemory)를 홍보하고 스폰서 배너(SerpApi)를 게시한다.
7. 비교
| 대상 | 차이 |
|---|---|
| fast.ai, CS231n/CS224n 같은 강의 | 학술/동영상 중심. 이 저장소는 에이전트·MCP·skills까지 폭이 넓고 에이전트 튜터와 산출물 자동 재사용을 전제로 한다. 내용 깊이는 직접 비교하지 않음 |
| Karpathy류 “from scratch” 코드 | 개별 주제의 깊은 구현. 이 저장소는 범위가 넓은 대신 레슨당 평균 약 170줄의 짧은 구현 |
| mengto-skills, agent-skills | skill 컬렉션(도구). 이쪽은 skill이 어떻게 만들어지는지 가르치는 학습 자료이며 산출물로 skill을 내놓는다 |
| claude-code-best-practice | Claude Code 사용법 레퍼런스. 이쪽은 에이전트 자체를 밑바닥부터 이해하는 교육과정 |
| Anthropic/OpenAI 공식 문서 | 사양과 제품 기준. 이 저장소는 요약·재해석이므로 최신 사양은 공식 문서로 재확인해야 함 |
8. 장단점·한계
장점: 범위가 매우 넓고, 에이전트·MCP·skills에 대한 현실적인 위험(툴 포이즈닝, 프롬프트 주입, 공급망, 과잉 권한)을 다루며, 레슨마다 실행 가능한 코드와 증거 기반 학습 규칙이 있고, 도구(튜터 skill, 학습 경로)가 잘 갖춰졌다. Phase 13·14의 표준 라이브러리 구현은 부담 없이 시험해 볼 수 있다.
한계: (1) 523개를 모두 검증하지 못했고 스타 수가 품질을 보증하지 않는다. (2) 속도가 빠른 영역(MCP 2026-07-28 사양, Claude 인증 정보 등)은 시간이 지나면 내용이 낡을 수 있다. (3) 레슨 번역은 기계번역이다. (4) 대부분이 장난감 규모 구현이라 프로덕션 품질의 코드는 아니다(저자 의도). (5) 분량이 방대해 사내 교육으로 쓰려면 발췌가 필요하다. (6) 총 342시간이라는 시간 추정은 저자의 값이다. (7) 학습자 진행 상태가 저장소 내 파일(LEARNING.md 등)에 쓰이므로 포크/개인 저장소 분리가 필요하다.
9. 보안·라이선스·운영 리스크
MIT 라이선스라 사내 교육 자료로 재배포·수정이 가능하다(저작권 고지 유지). 위험은 교육용 코드를 실행하는 데 있다. 레슨 코드는 외부 패키지(torch, transformers 등)를 설치하고 일부는 모델·데이터셋을 내려받으며, npx skills add는 에이전트의 skill 디렉터리에 외부 지시문을 설치한다. 사내 PC에서는 가상환경/격리된 작업 공간에서 실행하고, 설치할 skill의 내용을 먼저 읽는 편이 안전하다. 튜터 skill이 에이전트에게 명령 실행·파일 쓰기를 시키는 구조이므로 권한 모드를 보수적으로 설정해야 한다. API 키가 필요한 레슨이 있을 수 있으므로 키는 환경변수로만 주입하고 노트북·로그에 남기지 않도록 안내해야 한다.
관련 노트
mengto-skills · sanglard-agent-md · gepa · agency-agents · agent-skills · claude-code-best-practice · actguard · ag-ui-docs
출처
- https://github.com/rohitg00/ai-engineering-from-scratch (README, AGENTS.md, LESSON_TEMPLATE.md, phases/ 구조 집계, phases/14-agent-engineering/01·27·38, phases/13-tools-and-protocols/15·26, learning-paths/agent-skills.json, certifications/README.md·claude/README.md, skills/start-learning/SKILL.md, book/README.md·volumes.json, requirements.txt; 로컬 클론 및 표본 3건 실행 2026-10-01)
- GitHub API
repos/rohitg00/ai-engineering-from-scratch및 releases/latest, commits (2026-10-01)