Agent Engineering on ICE-ICE-BEAR-BLOG

Claude Code 스킬 컬렉션 폭발 — 같은 날 5개 레포가 말해주는 것

Sun, 10 May 2026 00:00:00 +0900

개요

2026-05-10 하루에 Claude Code 스킬·에이전트 컬렉션 레포 5개가 같은 시기에 회자됐다. 어떤 건 Karpathy 본인의 자율 연구 에이전트, 어떤 건 Matt Pocock의 실전 엔지니어링 스킬, 어떤 건 SuperClaude 같은 풀스택 프레임워크다. 우연이 아니다. 스킬(skill)이 에이전트 엔지니어링의 1차 프리미티브로 굳어지고 있다는 신호다.

graph TD
 Pattern["skills 패턴"] --> K["karpathy/autoresearch <br/> 80K stars"]
 Pattern --> F["forrestchang/andrej-karpathy-skills <br/> 123K stars"]
 Pattern --> A["hesreallyhim/awesome-claude-code <br/> 43K stars"]
 Pattern --> S["SuperClaude_Framework <br/> 22K stars"]
 Pattern --> M["mattpocock/skills <br/> 69K stars"]

 K --> Primitive["program.md = 스킬"]
 F --> Primitive
 M --> Primitive
 S --> Primitive
 A --> Curation["awesome-list 큐레이션"]

왜 스킬이 모이는가

스킬은 Anthropic이 2025년 가을 공식화한 패턴이다. 형식은 단순하다 — 폴더 하나, SKILL.md 파일 하나, 필요하면 보조 스크립트. Claude Code는 사용자의 작업 맥락을 보고 어떤 스킬을 발동할지 스스로 정한다.

이 단순함이 폭발의 원인이다.

버전 관리 가능 — 그냥 텍스트 파일. git diff로 리뷰하고, PR 받을 수 있다.
합성 가능 — 한 스킬이 다른 스킬을 호출할 수 있다. /grill-me → /to-prd → /to-issues → /tdd 가 자연스러운 파이프라인이 된다.
모델 중립적인 정신 — Claude Code가 1차 무대지만, 형식 자체는 마크다운이라 다른 에이전트로 옮기기 쉽다. 실제로 SuperGemini와 SuperQwen 포크가 이미 존재한다.
공유 가능 — 한 레포를 /plugin marketplace add로 통째로 가져올 수 있다.

이 5개 레포는 그 패턴이 결정화되는 과정에서 나온 5개의 단면이다.

1. karpathy/autoresearch — 스킬이 곧 연구 에이전트의 program.md

karpathy/autoresearch는 80,223 stars. 2026-03-06 생성, “AI agents running research on single-GPU nanochat training automatically”.

아이디어는 단순하다. AI 에이전트에게 작지만 진짜 LLM 학습 셋업을 주고 밤새 자율적으로 실험하게 한다. 코드 수정 → 5분 학습 → 결과 비교 → 채택 또는 폐기 → 반복. 아침에 일어나면 실험 로그와 (운 좋으면) 더 나은 모델이 있다.

핵심은 파일 구조다.

prepare.py — 상수, 데이터 준비 (수정 금지)
train.py — 모델/옵티마이저/학습 루프 (에이전트가 수정)
program.md — 에이전트 지시사항 (사람이 수정)

Karpathy 본인이 README에 명시한다.

The program.md file is essentially a super lightweight “skill”.

이게 핵심이다. Karpathy는 “스킬"이라는 용어를 채택했다. nanochat 학습 코드 위에 자율 연구 오케스트레이션을 얹은 1만 줄짜리 프레임워크가 아니라, 마크다운 한 장이다. 사람은 program.md를 진화시키고, 에이전트는 train.py를 진화시킨다. 메타 진화 루프 두 개가 분리돼 있다.

이 패턴이 영향력 있는 이유 — Karpathy는 학습 셋업에서 가장 안 빌릴 사람이다. 그가 마크다운 한 장으로 끝낸다면, 다른 사람들은 더더욱 단순화할 명분이 생긴다.

2. forrestchang/andrej-karpathy-skills — 스킬을 통한 행동 교정

forrestchang/andrej-karpathy-skills는 123,691 stars. “A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy’s observations on LLM coding pitfalls.”

Karpathy가 X에 적은 LLM 코딩 함정 관찰에서 네 가지 원칙을 뽑아냈다.

원칙	해결하는 문제
Think Before Coding	잘못된 가정, 숨겨진 혼란, 트레이드오프 누락
Simplicity First	과잉설계, 부풀린 추상화
Surgical Changes	무관한 코드 건드림, 건드려선 안 될 곳 수정
Goal-Driven Execution	검증 가능한 성공 기준으로 루프

설치는 두 가지 — /plugin marketplace add forrestchang/andrej-karpathy-skills로 Claude Code 플러그인으로 박거나, CLAUDE.md에 curl로 append한다. 같은 룰셋이 Cursor용 .cursor/rules/karpathy-guidelines.mdc로도 커밋돼 있다.

핵심 인용:

“LLMs are exceptionally good at looping until they meet specific goals… Don’t tell it what to do, give it success criteria and watch it go.” — Karpathy

이건 스킬을 모델 행동을 교정하는 룰셋으로 쓰는 사례다. 능력을 추가하는 게 아니라 결함을 빼는 스킬.

3. mattpocock/skills — Skills For Real Engineers

mattpocock/skills는 69,128 stars, MIT. “Skills for Real Engineers. Straight from my .claude directory.” 2026-05-10에 마지막 푸시.

이 레포는 명백히 GSD·BMAD·Spec-Kit 같은 풀프로세스 프레임워크의 반대편에 선다. README가 못박는다.

Approaches like GSD, BMAD, and Spec-Kit try to help by owning the process. But while doing so, they take away your control and make bugs in the process hard to resolve.

These skills are designed to be small, easy to adapt, and composable. They work with any model.

Matt이 정의한 4대 실패 모드와 각각의 스킬:

실패 모드	스킬
#1 The Agent Didn’t Do What I Want	`/grill-me`, `/grill-with-docs`
#2 The Agent Is Way Too Verbose	`CONTEXT.md` 공유 언어 (grill-with-docs 안에 빌트인)
#3 The Code Doesn’t Work	`/tdd`, `/diagnose`
#4 We Built A Ball Of Mud	`/to-prd`, `/zoom-out`, `/improve-codebase-architecture`

설치는 skills.sh 인스톨러로:

npx skills@latest add mattpocock/skills

설치하면 /setup-matt-pocock-skills가 이슈 트래커(GitHub / Linear / 로컬 파일), 트리아지 레이블 어휘, 도큐먼트 저장 경로를 셋업한다. 그 뒤로 to-issues, to-prd, triage, diagnose, tdd, improve-codebase-architecture, zoom-out이 일관된 컨벤션으로 연결된다.

Pocock이 인용하는 책들 — Pragmatic Programmer, Domain-Driven Design, Extreme Programming Explained, A Philosophy of Software Design — 가 자체로 신호다. 스킬은 새로운 패러다임이 아니라 30년 된 소프트웨어 공학 원칙의 LLM 인터페이스라는 입장.

4. SuperClaude_Framework — 스킬 위의 메타프로그래밍 레이어

SuperClaude-Org/SuperClaude_Framework는 22,726 stars, MIT, superclaude.netlify.app. 2025-06-22 생성.

스킬 미니멀리즘의 반대 극단에 있다.

메트릭	수
Slash Commands	30
Specialized AI Agents	20
Behavioral Modes	7
MCP Servers	8

자칭 “meta-programming configuration framework that transforms Claude Code into a structured development platform through behavioral instruction injection and component orchestration.”

설치는 PyPI:

pipx install superclaude
superclaude install

대표 명령어 — /sc:research (Tavily MCP 연동 딥 리서치), /sc:brainstorm, /sc:implement, /sc:test, /sc:pm. 선택적으로 Serena (코드 이해 2-3배 가속), Sequential (토큰 30-50% 절감), Tavily, Context7 MCP 서버를 airis-mcp-gateway로 묶어 띄울 수 있다.

v5.0에는 TypeScript 플러그인 시스템이 예고돼 있다(이슈 #419). 그러면 설치가 /plugin marketplace add SuperClaude-Org/superclaude-plugin-marketplace로 단순화된다.

SuperClaude의 의의 — 스킬이 충분히 안정적이라 그 위에 메타프레임워크를 얹어도 무너지지 않는다는 것. 그리고 같은 형식을 Gemini와 Qwen에도 옮겼다는 것 — 스킬 정신의 모델 중립성을 실증한다.

5. hesreallyhim/awesome-claude-code — 큐레이션 레이어

hesreallyhim/awesome-claude-code는 43,273 stars. 2025-04-19 생성으로, 이 묶음에서 가장 오래됐다. “A curated list of awesome skills, hooks, slash-commands, agent orchestrators, applications, and plugins for Claude Code by Anthropic.”

awesome-list 컨벤션을 따른다. 토픽 태그가 흥미롭다 — agentic-coding, agent-skills, ai-workflow-optimization, coding-agents. README 자체는 *“the previous Table of Contents was no longer fit for purpose”*라며 재정비 중이지만, 그 사실 자체가 메시지다 — Claude Code 생태계가 awesome-list 한 장으로 정리될 수준을 넘어섰다.

이 레포가 5개 묶음에 들어가는 이유는 단순하다. 다른 4개가 *“새로운 스킬을 제공”*한다면, 이 레포는 *“어디에 가야 스킬을 찾을 수 있는지”*를 푼다. 큐레이션 자체가 메타-스킬이다.

인사이트

1. 스킬은 합의된 프리미티브가 됐다. 같은 시기에 5개의 다른 사람이 다른 각도에서 같은 단어를 쓰고 있다 — Karpathy의 program.md도, Matt Pocock의 SKILL.md도, SuperClaude의 슬래시 명령도, 모두 “스킬"로 자기를 설명한다. 이전 세대 용어(“프롬프트 템플릿”, “에이전트 룰”, “시스템 메시지”)는 단일 단어로 합쳐졌다.

2. 풀프로세스 프레임워크 vs. 마이크로스킬의 분기. SuperClaude(30개 명령)와 Matt Pocock(작고 합성 가능)이 같은 날 노출된 건 우연이지만 의미심장하다. *“프로세스를 소유하는 프레임워크”*와 “각자 골라 끼는 마이크로스킬” 둘 다 살아남는다. Pocock이 GSD/BMAD/Spec-Kit를 명시적으로 반대편에 세우는 게 흥미롭다.

3. 스킬은 능력 추가가 아니라 결함 제거 도구로도 쓴다. Forrest Chang의 Karpathy 가이드라인은 새 기능을 주지 않는다. 모델이 “안 했으면 하는 행동"을 막는다. Anthropic이 Constitutional AI에서 모델 정렬에 했던 일을 사용자가 자기 워크플로에 한다.

4. 스킬은 모델 중립성의 베이스다 — Claude Code는 1차 무대일 뿐. SuperClaude가 SuperGemini와 SuperQwen 포크를 유지하고, Forrest Chang이 Cursor용 .mdc 파일을 같은 레포에 커밋하고, Matt Pocock이 *“They work with any model”*을 README 셀링 포인트로 적는다. 형식이 표준화되면 IDE/모델 락인이 약해진다.

5. program.md 패턴이 학습 코드까지 침투했다. Karpathy autoresearch에서 사람이 만지는 파일과 에이전트가 만지는 파일이 명시적으로 분리됐다. 이 분리가 일반화되면 모든 자동화 코드베이스가 human.md + agent-modifiable/ 구조로 갈 가능성이 있다.

6. 다음에 올 것 — 스킬 마켓플레이스, 스킬 SDK, 스킬 평가. /plugin marketplace가 이미 있고, SuperClaude가 Smithery에 등록돼 있고, skills.sh가 별도 인스톨러로 등장했다. 다음은 스킬 품질 평가(어떤 스킬이 실제로 모델 출력을 개선하나)와 스킬 SDK(스킬을 코드처럼 빌드/테스트)다.

7. 큐레이션 자체가 스킬이 된다. awesome-claude-code가 43K stars를 받은 건 *“어디서 시작할지 모르겠다”*는 신호다. 스킬 수가 한 사람이 다 못 읽을 만큼 늘었다는 뜻이고, 메타 레이어가 필요하다는 뜻이다.

참고

소스 레포 5개

karpathy/autoresearch — 단일 GPU nanochat 자율 연구 에이전트. program.md를 “lightweight skill"이라고 명시.
forrestchang/andrej-karpathy-skills — Karpathy의 LLM 코딩 함정 관찰에서 추출한 4대 원칙 CLAUDE.md.
mattpocock/skills — 실전 엔지니어링용 소형 합성 가능 스킬 모음. GSD/BMAD/Spec-Kit 반대편.
SuperClaude-Org/SuperClaude_Framework — 30개 슬래시 명령 + 20개 에이전트 + 8개 MCP 서버 메타프레임워크.
hesreallyhim/awesome-claude-code — Claude Code 리소스 awesome-list.

배경

Anthropic: Introducing Skills — 스킬 포맷 공식화.
Claude Code 공식 문서: Plugins — /plugin marketplace 시스템.
Karpathy의 LLM 코딩 함정 트윗 — Forrest Chang 가이드라인의 원전.

에이전트 학습, 코스로 갈까 카탈로그로 갈까: Microsoft AI Agents for Beginners vs. Awesome LLM Apps

Sun, 10 May 2026 00:00:00 +0900

개요

같은 시기에 회자된 두 학습 자료가 흥미로운 대조를 이룬다. 한쪽은 Microsoft의 ai-agents-for-beginners — 12+개 레슨으로 짜인 정식 커리큘럼이고, 다른 한쪽은 Shubham Saboo의 awesome-llm-apps — 클론해서 바로 돌릴 수 있는 100+개 예제 카탈로그다. 둘 다 별 6만/10만 개를 넘긴 거대 레포지만 접근 방식은 정반대다.

flowchart LR
 Learner["에이전트 입문자"]
 Curriculum["ai-agents-for-beginners <br/> 12+ 레슨 코스"]
 Catalog["awesome-llm-apps <br/> 100+ 템플릿 뷔페"]
 Goal1["개념 → 코드 → 프로덕션"]
 Goal2["내 유즈케이스에 가까운 것 포크"]
 Gap["빠진 것: eval, observability, cost"]

 Learner --> Curriculum
 Learner --> Catalog
 Curriculum --> Goal1
 Catalog --> Goal2
 Goal1 --> Gap
 Goal2 --> Gap

두 레포의 정체성

Microsoft AI Agents for Beginners — 코스 형태

microsoft/ai-agents-for-beginners는 GitHub 별 61k에 도달한 공식 학습 코스다. MIT 라이선스, Jupyter Notebook 기반, 2024년 11월부터 시작해 Microsoft Agent Framework와 Azure AI Foundry Agent Service V2를 축으로 빌드한다. 레슨 트리는 다음과 같다.

01 Intro to AI Agents and Agent Use Cases — 에이전트 정의와 유즈케이스
02 Exploring Agentic Frameworks — 프레임워크 비교
03 Agentic Design Patterns — UX 원칙(Space/Time/Core)
04 Tool Use Design Pattern
05 Agentic RAG
06 Building Trustworthy AI Agents
07 Planning Design Pattern
08 Multi-Agent Design Pattern
09 Metacognition Design Pattern
10 AI Agents in Production — observability + evaluation
11 Agentic Protocols (MCP, A2A, NLWeb)
12 Context Engineering for AI Agents
13 Managing Agentic Memory
14~18 Microsoft Agent Framework, Browser-Use 기반 Computer Use Agents, Securing AI Agents 등

각 레슨은 텍스트 + 짧은 동영상 + Jupyter 노트북 코드 샘플로 구성되어 있다. 또한 co-op-translator로 50+개 언어로 자동 번역되어 Korean 트랜슬레이션도 제공된다(번역 누락이 신경 쓰이면 sparse checkout으로 영어판만 받을 수도 있다).

Awesome LLM Apps — 카탈로그 형태

반대편의 Shubhamsaboo/awesome-llm-apps는 별 109k의 거대한 템플릿 모음집이다. Apache-2.0 라이선스이고 README 첫 줄부터 “100+ AI Agent & RAG apps you can actually run — clone, customize, ship"이라고 못 박는다. 본인 표현에 따르면 “큐레이션이 아니라 손으로 직접 빌드한 템플릿 카탈로그"이고 13개 카테고리로 분류되어 있다.

🌱 Starter AI Agents — API 키 하나로 도는 단일 파일 에이전트
🚀 Advanced AI Agents — 메모리/툴/멀티스텝 reasoning
🤝 Multi-agent Teams — CrewAI 기반 서비스 에이전시 등
🗣️ Voice AI Agents — 실시간 음성 인터페이스
♾️ MCP AI Agents — Model Context Protocol 통합
📀 RAG Tutorials — Agentic RAG, Corrective RAG, Vision RAG 등 21+개
🧩 Awesome Agent Skills — Claude Code/ADK용 스킬 파일 19개
🔧 LLM 파인튜닝 (Gemma 3, Llama 3.2)
🧑‍🏫 Google ADK Crash Course & OpenAI Agents SDK Crash Course

각 템플릿은 자체 README + requirements.txt + 보통 streamlit run으로 끝나는 실행 명령으로 구성된다. 30초 안에 첫 에이전트를 돌리는 게 목표라고 명시되어 있다.

같은 주제, 다른 깊이 — 레슨 03 vs 카탈로그 03

같은 “에이전트 설계 원칙"을 어떻게 다루는지 비교하면 두 자료의 성격이 드러난다.

차원	MS 03-agentic-design-patterns	Awesome LLM Apps Starter
출발점	“Connecting not collapsing”, “Embrace uncertainty” 같은 UX 원칙	AI Travel Agent 같은 실행 가능한 코드
설명 길이	수천 단어, 다이어그램, Travel Agent 케이스 스터디	짧은 README + 실행 가이드
도출 방식	원칙 → 가이드라인(Transparency/Control/Consistency) → 적용	동작하는 코드 → 직접 만져보며 이해
다음 행동	다음 레슨(04 Tool Use)으로 진행	다른 30개 템플릿으로 분기

전자는 “왜 이렇게 설계해야 하는가"를 가르치고, 후자는 “이미 누가 이렇게 설계했으니 포크해서 고쳐 써라"고 말한다. 둘 다 정답이지만 학습자의 상황이 다르다.

누구에게 무엇이 맞는가

코스가 맞는 학습자

에이전트가 처음이고 기본기를 잡아야 하는 사람 — UX 원칙, 디자인 패턴, 멀티에이전트, 메모리, 컨텍스트 엔지니어링까지 체계적으로 다룬다
회사에서 Azure를 쓰고 있는 팀 — Azure AI Foundry + Microsoft Agent Framework 라인업이 그대로 매핑된다
번역본이 필요한 비영어권 학습자 — 한국어, 일본어, 중국어 등 50+개 언어 자동 번역
CIO 보고용 슬라이드가 필요한 사람 — “MCP, A2A, NLWeb 프로토콜 비교"처럼 깔끔한 챕터 구조가 그대로 자료가 된다

카탈로그가 맞는 학습자

이미 LLM 호출은 할 줄 알고 패턴을 빠르게 훑고 싶은 엔지니어 — RAG 21종을 비교해보고 자기 케이스에 가까운 것을 고를 수 있다
유즈케이스가 명확한 사람 — “내 도메인이 보험/투자/리서치/음성"이라면 Insurance Claim Live Agent, AI VC Due Diligence 같은 직접적인 출발점이 있다
사이드 프로젝트 영감이 필요한 사람 — AI 3D Pygame Agent, AI Meme Generator처럼 가볍게 시작할 거리가 많다
MCP/CrewAI/ADK 같은 특정 스택 예제를 빨리 보고 싶은 사람

대략 코스는 “지도가 필요한 사람"용, 카탈로그는 “재료가 필요한 사람"용이다. 실제로 두 자료를 같이 쓰면 가장 강력하다 — MS 코스의 05 Agentic RAG 챕터를 읽은 다음 awesome-llm-apps의 Agentic RAG with Reasoning을 클론해서 돌려보면, 이론과 코드가 한 번에 잡힌다.

입문 자료가 공통으로 놓치는 것

두 자료를 비교해 봐도 — 그리고 시장에 있는 다른 “agent 101” 자료를 봐도 — 입문 콘텐츠가 시스템적으로 약한 영역이 보인다.

1. Evaluation을 충분히 안 다룬다. MS 코스는 Lesson 10 - AI Agents in Production에서 trace/span, offline/online eval, RAGAS, LLM Guard를 언급하긴 하는데 그게 1개 레슨이고 코스 끝부분이다. awesome-llm-apps에는 RAG Failure Diagnostics Clinic 같은 게 있지만 평가는 카테고리가 아니다. 그러나 현장에서는 “에이전트를 빌드하는 시간"보다 “왜 회귀했는지 파악하는 시간"이 훨씬 길다.

2. Observability를 비싼 옵션처럼 다룬다. OpenTelemetry, Langfuse, Microsoft Foundry 같은 도구가 언급되긴 하지만 “프로덕션 단계의 무거운 도구"로 그려진다. 실제로는 첫 멀티스텝 에이전트 코드를 짤 때부터 trace를 켜놔야 디버깅이 가능하다. trace 없이 멀티에이전트 시스템을 디버깅하는 건 print 없이 멀티스레드 코드 디버깅하는 것과 비슷하다.

3. 비용 시뮬레이션이 없다. awesome-llm-apps의 Toonify Token Optimization이나 Headroom Context Optimization 같은 시도가 있지만, 멀티에이전트 한 번 돌리면 토큰을 5~50배 쓸 수 있다는 감각이 입문자에게는 전혀 전달되지 않는다. 첫 레슨에서 “이 데모를 100번 돌리면 얼마"인지 계산기를 줘야 한다.

4. Failure mode 카탈로그가 없다. “이게 동작합니다"는 보여주는데 “이렇게 망가집니다"는 거의 없다. 프롬프트 인젝션, 무한 툴 호출, 메모리 누수, 잘못된 RAG 결과를 곧이곧대로 믿는 에이전트 같은 패턴은 실제 운영하면 매주 만난다. 현장 한 줄 평으로는 “에이전트 빌드는 쉽고, 망가지는 패턴을 외우는 게 본업"이라는 얘기가 가장 정확하다.

인사이트

에이전트 학습 시장은 지난 1년 사이 “프레임워크 비교"에서 “교육과정"으로 한 단계 올라갔다. MS의 코스가 12+개 레슨으로 디자인 패턴과 프로토콜까지 다룬다는 것 자체가 시장 성숙도의 지표다. 동시에 awesome-llm-apps의 100+ 템플릿이 ADK, OpenAI Agents SDK, CrewAI, MCP를 모두 커버하면서도 일관되게 streamlit run 한 줄로 도는 것은 “에이전트 빌드 비용"이 충분히 떨어졌다는 신호다. 입문자가 두 자료를 같이 쓰면 “원리는 코스에서, 첫 동작은 카탈로그에서"라는 깔끔한 학습 루프가 만들어진다. 하지만 두 자료 모두 — 그리고 사실상 시장 전체가 — 평가/관측/비용/실패 패턴에는 여전히 인색하다. 이 갭이 다음 1년의 콘텐츠 기회다. “AI Agents Eval for Beginners”, “Agent Observability for Beginners” 같은 코스가 나올 때 시장은 또 한 단계 성숙할 것이다.

참고

Microsoft 코스

Awesome LLM Apps

평가와 관측 도구

Claude Code OS — Claude Code를 운영체제로 박은 부팅 가능한 LiveUSB

Sat, 09 May 2026 00:00:00 +0900

개요

Hostingglobal-Tech/claude-code-os는 2026-05-01에 생성된 MIT 라이선스 프로젝트로, 약 85 stars를 가진 부팅 가능한 LiveUSB 배포판이다. 한 줄로 요약하면 *“USB를 꽂으면 1분 안에 Claude Code와 OpenAI Codex CLI가 한 창 두 탭으로 동시에 뜨는 Linux Mint 기반 OS”*다. 흥미로운 건 “Claude Code OS” 라는 작명이 단순한 마케팅 비유가 아니라는 점이다. 이 프로젝트는 진짜로 Linux Mint 21.3 XFCE 위에 Claude Code를 userspace 그 자체로 박아놓았다. AI 에이전트가 한 명의 사용자로서 OS와 함께 부팅된다.

graph TD
 Kernel["Linux 커널 (Mint 21.3 XFCE base)"] --> Userland["Userspace = AI 에이전트들"]
 Userland --> Tab1["좌측 탭: Claude Code <br/> @anthropic-ai/claude-code"]
 Userland --> Tab2["우측 탭: Codex CLI <br/> @openai/codex"]
 Userland --> Browser["Firefox (OAuth용)"]

 Persistence["cco-persistence.dat <br/> ext4 3.5 GB on USB"] --> Userland
 Persistence -. "Wi-Fi 비번 / OAuth / 작업 파일" .-> Tab1
 Persistence -. "API 키 / 작업 파일" .-> Tab2

 Boot["Ventoy 부트로더"] --> Kernel
 Boot --> Persistence

왜 만들었나 — AI 앞에 끼인 OS 설치 의식

저자가 README 첫 페이지에 박은 문제 제기는 단순하다.

AI 와 한 번 대화하려고 Windows 깔고 → 드라이버 잡고 → 브라우저 깔고 → 검색. 또는 Linux 깔고 → Node 깔고 → 명령어 입력 → 로그인. 너무 복잡합니다. AI 가 결국 우리가 쓰는 도구인데, 왜 그 앞에 복잡한 단계를 끼워둘까. 그래서 OS 자체를 AI 로 만들었습니다.

이 관점이 흥미롭다. agentmemory나 agent-skills 같은 도구들이 “에이전트의 컨텍스트/스킬을 OS 처럼 다루자” 라는 비유를 썼다면, claude-code-os는 비유를 떼고 진짜 OS 부팅 시퀀스의 init 단계에 에이전트를 끼워넣는다. lightdm autologin → xfce4-terminal 자동 실행 → Claude Code + Codex CLI auto-start. 사용자가 보는 첫 화면은 데스크톱이 아니라 두 AI 프롬프트다.

무엇이 들어있나 (v2.0.5 기준)

v2.0.5 릴리즈의 구성:

컴포넌트	무엇	비고
Base	Linux Mint 21.3 XFCE (Ubuntu 22.04 LTS jammy)	안정 LTS
AI 좌측 탭	`@anthropic-ai/claude-code`	npm 전역 설치
AI 우측 탭	`@openai/codex`	npm 전역 설치
런타임	Node.js 20 LTS	NodeSource 저장소
브라우저	Firefox	OAuth 로그인용
한글 입력	ibus + ibus-hangul	`Shift+Space` / `한/영` 토글
폰트	Noto Sans CJK KR + D2Coding	가독성
로케일	ko_KR.UTF-8 + Asia/Seoul	KST 시간
자동 로그인	lightdm `autologin-user=cco`	NOPASSWD sudo
영속성	Ventoy `casper-rw` (3.5 GB)	USB에 모든 상태 저장

전체 ISO는 약 3.4 GB. 두 조각으로 쪼개 올라가있다 (aicode-os-v2.0.5.iso.part1 1.99 GB + part2 1.65 GB). 합치는 명령은 한 줄.

cat aicode-os-v2.0.5.iso.part1 aicode-os-v2.0.5.iso.part2 > aicode-os-v2.0.5.iso

부팅 시퀀스 — Claude Code가 init이다

build-mint.sh (약 18 KB의 단일 셸 스크립트)가 ISO를 만든다. 핵심은 chroot 안에서 다음을 박는 것.

apt로 ibus, ibus-hangul, fonts-noto-cjk, language-pack-ko, xfce4-terminal 설치
ko_KR.UTF-8 locale + Asia/Seoul timezone
Node.js 20 LTS + npm install -g @anthropic-ai/claude-code @openai/codex
Naver D2Coding 폰트 wget 다운로드
cco 사용자 생성 (sudo NOPASSWD)
lightdm autologin-user=cco 설정
aicode-startup-claude + aicode-startup-codex 시작 스크립트를 /usr/local/bin에 박음
XFCE autostart에 xfce4-terminal --maximize --tab 등록 → 한 창 두 탭

aicode-startup-claude는 claude --dangerously-skip-permissions를 띄운다. 권한 묻기를 통째로 끄고 root로 풀 네트워크 권한을 준다는 뜻이다. 이게 “OS를 AI로 만들었다” 라는 카피의 진짜 의미다 — AI가 사용자 권한이 아니라 시스템 권한으로 작동한다.

Persistence — USB 안에 모든 상태를 박아두기

이 프로젝트의 두 번째 핵심은 Ventoy의 persistence 기능을 활용한 휴대성이다. cco-persistence.dat라는 3.5 GB ext4 이미지 파일을 USB에 두면 다음이 USB 안에만 저장된다.

Wi-Fi SSID + 비번
Claude OAuth 토큰
OpenAI API 키 (혹은 ChatGPT 세션)
작업한 파일 / git clone한 리포 / npm 캐시
ibus 설정, 키보드 단축키 커스터마이즈

호스트 PC의 디스크는 건드리지 않는다. USB를 빼면 그 컴퓨터에는 흔적이 0이다. 같은 USB를 다른 PC에 꽂으면 환경 전체가 그대로 따라온다. 카페 노트북, 회의실 PC, 호텔 데스크탑 어디든.

ventoy.json에 박는 설정이 간결하다.

{
 "control": [
 { "VTOY_DEFAULT_MENU_MODE": "0" },
 { "VTOY_MENU_TIMEOUT": "3" },
 { "VTOY_DEFAULT_IMAGE": "/aicode-os-v2.0.5.iso" }
 ],
 "persistence": [
 {
 "image": "/aicode-os-v2.0.5.iso",
 "backend": "/cco-persistence.dat",
 "autosel": 1
 }
 ]
}

보안 모델 — 호스트 안전, USB 위험

README의 보안 섹션이 흥미롭다. 위험을 정확히 분리해서 설명한다.

영역	안전 / 위험	이유
호스트 PC 디스크	안전	LiveUSB는 USB 안에서만 작동, 호스트 파일시스템 미접근
USB 내부 작업물	위험	AI가 root로 실행, 시킨 대로 다 함
네트워크 outbound	위험	풀 네트워크 권한, 외부로 데이터 빠질 수 있음
분실 시	위험	OAuth 토큰 / API 키가 dat에 평문 저장, 원격 wipe 없음

claude --dangerously-skip-permissions가 의도된 디자인이다. 샌드박스가 아니라 “이건 격리된 USB라 호스트는 안전하니, AI한테 root 쥐어주는 트레이드오프” 가 핵심 가정이다. 이 가정이 무너지는 지점은 USB 분실과 outbound 네트워크 두 군데다. 저자는 분실 시 claude.ai 콘솔과 OpenAI 콘솔에서 직접 토큰 revoke하라고 명시한다.

버전 히스토리 — Alpine에서 Mint로의 항해

CHANGELOG.en.md를 보면 이 프로젝트의 진화가 한눈에 보인다.

graph LR
 V1["v1.0.0 <br/> Alpine + console only"] --> V106["v1.0.6 <br/> X11 + Firefox 추가"]
 V106 --> V120["v1.0.20 <br/> Wi-Fi GUI iwgtk"]
 V120 --> V134["v1.0.34 <br/> Ventoy auto-boot"]
 V134 --> V200["v2.0.0 <br/> Mint 베이스 전환"]
 V200 --> V204["v2.0.4 <br/> Codex CLI 통합"]
 V204 --> V205["v2.0.5 <br/> 한 창 두 탭"]

v1.0.0 (2026-05-01) — Alpine Linux 3.20 기반, 콘솔 전용, root autologin, claude-code만
v1.0.6 — X11 + fluxbox + Firefox로 데스크톱화
v1.0.20 — Wi-Fi GUI iwgtk + iwd, RTL8821CE 호환
v1.0.34 (2026-05-05) — Ventoy 자동 부트, chrony 시간 동기화 (1970 epoch 문제 해결)
v2.0.0~v2.0.4 — Alpine → Linux Mint 21.3 전환, Codex CLI 추가, AICODE-OS 브랜드 전환
v2.0.5 (2026-05-09) — 두 별도 창 → 한 창 두 탭으로 통합 (1366×768 화면 호환성)

v1.x → v2.x의 베이스 OS 전환이 흥미롭다. 처음에는 “가장 가벼운 Alpine 기반” 으로 시작했지만, X11 / 한글 입력기 / 와이파이 드라이버 등 데스크톱 의존성이 쌓이자 “검증된 Ubuntu 기반 Mint” 로 갈아탔다. 미니멀리즘 vs 호환성 트레이드오프의 흔한 곡선이다.

Claude Code “배포판” 생태계 안에서의 위치

claude-code-os를 보면서 떠올릴 만한 인접 프로젝트들이 있다. 다들 Claude Code를 커널처럼 다루고 그 위에 자기 색을 입히는 시도다.

graph TD
 CC["Claude Code 커널 <br/> @anthropic-ai/claude-code"]

 CC --> Distro1["claude-code-os <br/> 부팅 가능한 LiveUSB"]
 CC --> Distro2["SuperClaude_Framework <br/> 페르소나/명령 프레임워크"]
 CC --> Distro3["awesome-claude-code <br/> 큐레이션"]
 CC --> Distro4["agent-skills <br/> 워크플로 강제 스킬"]

 Distro1 -. "OS 레벨" .-> Layer1["하드웨어 + Linux"]
 Distro2 -. "설정 레벨" .-> Layer2["슬래시 명령 + 페르소나"]
 Distro3 -. "발견 레벨" .-> Layer3["링크 모음"]
 Distro4 -. "행동 레벨" .-> Layer4["Markdown 스킬 번들"]

SuperClaude-Org/SuperClaude_Framework (약 22,700 stars) — “specialized commands, cognitive personas, and development methodologies” 를 박아주는 설정 프레임워크. Claude Code 설치 후 그 위에 슬래시 명령과 페르소나를 부여한다. 같은 운영체제(Claude Code) 위에 도는 “X윈도우 같은” 사용자 환경이다.
hesreallyhim/awesome-claude-code — Awesome 시리즈 큐레이션. 무엇이 있는지 알려주는 “색인”.
anthropics/skills (agent-skills) — Anthropic 본가가 푼 “시니어 엔지니어의 워크플로 강제 스킬” 묶음. Codex CLI에 같은 패턴을 이식한 codex-r 같은 파생도 나왔다.
rohitg00/agentmemory — Claude Code 포함 16개 에이전트와 MCP로 공유되는 영속 메모리.

claude-code-os가 다른 것들과 구분되는 지점은 추상화 레벨이다. SuperClaude가 “같은 OS 위에서 다른 셸 환경” 이라면, claude-code-os는 “OS 자체를 바꾼다.” Linux 배포판 전쟁이 같은 커널 위에 다른 패키지 매니저와 데스크톱을 얹는 식으로 분화했듯, Claude Code 배포판 의 분화도 비슷한 결로 가고 있다.

누가 쓰면 좋은가

이 프로젝트가 노리는 페르소나는 분명해 보인다.

시나리오	적합도	이유
발표/시연 — 누구 컴퓨터에서든 AI 데모	높음	USB 꽂고 1분, 호스트 PC 안전
가벼운 노트북에 부담 없이 코딩	중간	persistence dat가 3.5 GB 한도
비전공자 친구에게 “AI 만져봐” 권유	높음	OS 설치 진입장벽 0
기존 dev 환경의 메인 도구로	낮음	git config / SSH key / dotfile 등은 별도 동기화 필요
보안 민감한 작업	낮음	AI가 root로 풀 권한, 토큰이 USB에 평문 저장

발표 데모 / 강의실 / 비전공자 온보딩에 가장 잘 어울린다. dotfile-heavy한 개인 워크스테이션 대체로는 무리.

흥미로운 디자인 디테일

한 창 두 탭으로 통합 (v2.0.5) — v2.0.4까지는 두 별도 창을 좌표 지정으로 띄웠는데, Samsung NT900X3A 같은 1366×768 화면에서 Codex 창이 화면 밖으로 잘렸다. v2.0.5는 xfce4-terminal --maximize --tab 한 줄로 모든 화면 크기에서 안전.
graceful 종료 — claude / codex 가 끝나면 exec bash로 셸이 살아있어 재시작 가능. 빈 창에서 다시 claude 치면 그대로 부활.
stale autostart 자동 정리 — aicode-startup-dual이 옛 v2.0.0~v2.0.4의 ~/.config/autostart/*.desktop을 자동으로 rm한다. persistence USB를 v2.0.x 사이에 업그레이드해도 깨지지 않게.
chrony 박은 이유 — Alpine 시절 v1.0.34부터 박힌 시간 동기화. 1970 epoch에서 시작하면 SSL/OAuth 핸드셰이크가 cert 만료로 실패한다. LiveUSB는 RTC 못 믿어서 부팅 직후 NTP 동기화 필수.
D2Coding 폰트를 Naver GitHub release에서 직접 wget — Ubuntu repo에 없어서. 고정 버전 (VER1.3.2-20180524)을 박았다.

한계와 미해결

persistence dat 크기 고정 — 처음 만든 3.5 GB에서 자동 확장 안 됨. 한도 도달 시 더 큰 dat 새로 만들어 교체해야 함.
FAT32 USB는 부적합 — 단일 파일 4 GB 한도 때문에 8 GB dat 만들어도 USB에 복사 안 됨. exFAT 권장 (Ventoy 1.0.96+ 기본).
호스트 PC의 데이터에 접근하려면 추가 마운트 필요 — “흔적 0” 의 이면. 호스트 디스크의 코드를 작업하려면 수동 마운트해야 함.
root + 풀 네트워크 AI의 책임 — “AI가 시키는 명령은 그대로 실행되니, 모르는 명령이나 외부 코드를 무분별하게 실행하지 마세요” 라고 README가 명시. 사용자 신중함이 보안 모델의 일부.

결론 — “OS 자체를 AI로” 라는 카피의 진심

claude-code-os는 흔히 보는 “Claude Code 위에 얹는 설정 프레임워크” 가 아니다. 부팅 init부터 AI를 끼워넣는 LiveCD 배포판이다. SuperClaude가 “같은 OS 위 다른 셸” 이라면, 이건 “커널부터 바꿨다.” 이 분화는 흥미롭다 — 초기 Linux 배포판 전쟁이 같은 커널 위에 데비안/레드햇/아치 각자 색을 입히며 진행됐듯, Claude Code 배포판 들도 같은 npm 패키지 위에 OS-level, framework-level, skill-level로 각자 추상화 층을 쌓고 있다.

이 프로젝트가 다음으로 풀면 흥미로운 문제는 샌드박스 vs 호스트 통합의 트레이드오프다. “호스트 디스크 안전 + AI root” 라는 현재 모델은 데모/온보딩에 완벽하지만, 일상 개발의 메인 환경으로 쓰려면 호스트 dotfile / SSH key / git config가 자연스럽게 따라와야 한다. 부팅 가능한 USB가 “내 dev 환경 전체” 가 되려면 그 다리가 필요하다.

참고

claude-code-os 자체

Hostingglobal-Tech/claude-code-os — 본 리포
v2.0.5 Release — ISO 두 조각 + persistence dat
CHANGELOG.en.md — Alpine → Mint 베이스 전환 히스토리
build-mint.sh — 빌드 스크립트 본체

의존 도구

Ventoy — multi-ISO 부팅 USB 도구
Ventoy persistence plugin — casper-rw 백엔드
Linux Mint 21.3 XFCE — 베이스 OS
@anthropic-ai/claude-code · @openai/codex — 두 AI 코더
Naver D2Coding 폰트

인접 Claude Code 생태계

SuperClaude-Org/SuperClaude_Framework — 페르소나 / 슬래시 명령 프레임워크
anthropics/skills — Anthropic 본가 agent-skills
rohitg00/agentmemory — MCP 기반 영속 메모리
thedalbee/codex-r — Claude Code 세션을 Codex로 import하는 스킬
Model Context Protocol

Agent Engineering on ICE-ICE-BEAR-BLOG

Claude Code 스킬 컬렉션 폭발 — 같은 날 5개 레포가 말해주는 것

개요

왜 스킬이 모이는가

1. karpathy/autoresearch — 스킬이 곧 연구 에이전트의 program.md

2. forrestchang/andrej-karpathy-skills — 스킬을 통한 행동 교정

3. mattpocock/skills — Skills For Real Engineers

4. SuperClaude_Framework — 스킬 위의 메타프로그래밍 레이어

5. hesreallyhim/awesome-claude-code — 큐레이션 레이어

인사이트

참고

에이전트 학습, 코스로 갈까 카탈로그로 갈까: Microsoft AI Agents for Beginners vs. Awesome LLM Apps

개요

두 레포의 정체성

Microsoft AI Agents for Beginners — 코스 형태

Awesome LLM Apps — 카탈로그 형태

같은 주제, 다른 깊이 — 레슨 03 vs 카탈로그 03

누구에게 무엇이 맞는가

코스가 맞는 학습자

카탈로그가 맞는 학습자

입문 자료가 공통으로 놓치는 것

인사이트

참고

Microsoft 코스

Awesome LLM Apps

평가와 관측 도구

관련 프로토콜과 프레임워크

Claude Code OS — Claude Code를 운영체제로 박은 부팅 가능한 LiveUSB

개요

왜 만들었나 — AI 앞에 끼인 OS 설치 의식

무엇이 들어있나 (v2.0.5 기준)

부팅 시퀀스 — Claude Code가 init이다

Persistence — USB 안에 모든 상태를 박아두기

보안 모델 — 호스트 안전, USB 위험

버전 히스토리 — Alpine에서 Mint로의 항해

Claude Code “배포판” 생태계 안에서의 위치

누가 쓰면 좋은가

흥미로운 디자인 디테일

한계와 미해결

결론 — “OS 자체를 AI로” 라는 카피의 진심

참고

claude-code-os 자체

의존 도구

인접 Claude Code 생태계