shareAI-lab/learn-claude-code

코드를 작성하기 전에 한 가지 분명히 해야 할 점이 있습니다.

에이전시 (Agency) — 인지하고, 추론하며, 행동하는 능력 — 는 외부 코드 오케스트레이션 (orchestration)이 아니라 모델 학습 (model training)에서 비롯됩니다. 하지만 실제로 작동하는 에이전트 제품에는 모델과 하네스 (harness)가 모두 필요합니다. 모델은 운전자이고, 하네스는 차량입니다. 이 저장소(repository)는 차량을 구축하는 방법을 가르칩니다.

모든 에이전트의 핵심에는 신경망 (neural network) — 트랜스포머 (Transformer), RNN, 학습된 함수 (trained function) — 이 있으며, 이는 인지, 추론, 행동의 시퀀스에 대한 수십억 번의 경사 하강법 업데이트 (gradient updates)를 통해 형성됩니다. 에이전시 (Agency)는 주변 코드에 의해 부여된 것이 아닙니다. 그것은 학습 과정 중에 습득된 것입니다.

인간은 그 원형적인 증거입니다. 수백만 년의 진화적 압력에 의해 정교해진 생물학적 신경망 (biological neural network)은 감각을 통해 세상을 인지하고, 뇌를 통해 추론하며, 신체를 통해 행동합니다. DeepMind, OpenAI, 또는 Anthropic이 "에이전트 (agent)"라고 말할 때, 그들은 모두 동일한 핵심을 의미합니다: 학습을 통해 행동하는 법을 배운 모델, 그리고 그 모델이 특정 환경에서 작동할 수 있게 해주는 인프라스트럭처 (infrastructure).

역사적 기록은 명확합니다:

• 2013 -- DeepMind DQN이 Atari를 플레이하다. 오직 가공되지 않은 픽셀 (raw pixels)과 게임 점수만을 입력받는 단일 신경망 (neural network)이 7개의 Atari 2600 게임을 학습했습니다. 이는 이전의 알고리즘들을 능가했으며, 그중 3개 게임에서는 인간 전문가를 이겼습니다. 2015년에는 전문 테스터 수준으로 49개의 게임까지 확장되었으며, Nature지에 발표되었습니다. 게임별로 특화된 규칙은 없었습니다. 하나의 모델이 경험으로부터 학습했습니다. -
  2019 -- OpenAI Five가 Dota 2를 정복하다. 5개의 신경망이 10개월 동안 자신들과의 대결을 통해 45,000년 분량의 Dota 2 경기를 수행했으며, 이후 라이브 경기에서 TI8 세계 챔피언인 OG를 2-0으로 격파했습니다. 공개 경기장에서 이 AI는 42,729번의 게임 중 99.4%를 승리했습니다. 짜여진 전략 (scripted strategies)은 없었습니다. 모델들은 셀프 플레이 (self-play)를 통해 팀워크를 학습했습니다. -
  2019 -- DeepMind AlphaStar가 StarCraft II를 마스터하다. AlphaStar는 비공개 경기에서 프로 선수를 10-1로 이겼으며, 이후 유럽 서버에서 상위 0.15%인 그랜드마스터 (Grandmaster) 등급에 도달했습니다. 이는 체스나 바둑 (Go)을 훨씬 능가하는 조합론적 행동 공간 (combinatorial action space)을 가진 불완전 정보 (incomplete-information) 실시간 게임입니다. -
  2019 -- Tencent Jueyu가 Honor of Kings를 지배하다. Tencent AI Lab의

모든 이정표는 동일한 사실을 가리킵니다. 에이전시 (Agency) -- 인지하고, 추론하며, 행동하는 능력 -- 은 코딩되는 것이 아니라 학습되는 것입니다. 하지만 모든 에이전트에게도 작동할 환경이 필요합니다. Atari 에뮬레이터, Dota 2 클라이언트, StarCraft II 엔진, IDE 및 터미널과 같은 환경 말입니다. 모델은 지능을 제공하고, 환경은 행동 공간 (Action Space)을 제공합니다. 이들이 결합하여 완전한 에이전트를 형성합니다.

"에이전트 (Agent)"라는 단어는 프롬프트 배관 (Prompt-plumbing) 산업 전체에 의해 하이재킹되었습니다.

드래그 앤 드롭 워크플로우 빌더, 노코드 (No-code) "AI 에이전트" 플랫폼, 프롬프트 체인 오케스트레이션 (Prompt-chain orchestration) 라이브러리들. 이들은 단 하나의 망상, 즉 LLM API 호출을 if-else 분기, 노드 그래프, 하드코딩된 라우팅 로직과 함께 엮는 것이 "에이전트를 구축하는 것"이라는 망상을 공유하고 있습니다.

그렇지 않습니다. 이들이 만들어내는 것은 루브 골드버그 장치 (Rube Goldberg machines) -- 즉, LLM을 미화된 텍스트 완성 노드로 끼워 넣은, 과하게 설계되고 취약하며 절차적인 규칙 파이프라인일 뿐입니다. 그것은 에이전트가 아닙니다. 그것은 거창한 허세를 부리는 쉘 스크립트 (Shell script)에 불과합니다.

절차적 로직 -- 방대한 규칙 트리, 노드 그래프, 체인형 프롬프트 폭포 (Chained prompt waterfalls) -- 을 쌓아 올리고, 충분한 글루 코드 (Glue code)가 자발적으로 자율적인 행동을 만들어내기를 기도하는 방식으로 지능을 무력으로 얻어낼 수는 없습니다. 그렇게 되지 않습니다. 에이전시를 엔지니어링을 통해 존재하게 만들 수는 없습니다. 에이전시는 코딩되는 것이 아니라 학습되는 것입니다.

누군가 "나는 에이전트를 구축하고 있다"라고 말할 때, 그것은 오직 다음 두 가지 중 하나만을 의미할 수 있습니다.

1. 모델 학습 (Training a model). 강화학습 (Reinforcement Learning), 미세 조정 (Fine-tuning), RLHF 또는 다른 경사 하강법 기반 (Gradient-based) 방법을 통해 가중치를 조정하는 것입니다. 대상 도메인에서의 인지, 추론, 행동의 실제 세계 시퀀스인 궤적 데이터 (Trajectory data)를 수집하고, 이를 사용하여 모델의 행동을 형성하는 것입니다. 이것이 DeepMind, OpenAI, Tencent AI Lab, 그리고 Anthropic이 하는 일입니다.

2. 하네스 (Harness) 구축. 모델에 운영 환경을 제공하는 코드를 작성하는 것입니다. 이것이 우리 대부분이 하는 일이며, 이 저장소 (Repository)의 핵심입니다.

하네스는 에이전트가 특정 도메인에서 작동하는 데 필요한 모든 것입니다:

Harness = 도구 (Tools) + 지식 (Knowledge) + 관찰 (Observation) + 행동 인터페이스 (Action Interfaces) + 권한 (Permissions)
도구 (Tools): 파일 I/O, 셸 (shell), 네트워크 (network), 데이터베이스 (database), 브라우저 (browser)
지식 (Knowledge): 제품 문서 (product docs), 도메인 참조 (domain references), API 명세 (API specs), 스타일 가이드 (style guides)
...

모델이 결정합니다. 하네스 (Harness)가 실행합니다. 모델이 추론합니다. 하네스가 컨텍스트 (Context)를 제공합니다. 모델이 운전자라면, 하네스는 차량입니다.

이 저장소 (Repository)는 여러분에게 그 차량을 만드는 법을 가르칩니다. 코딩을 위한 차량입니다. 하지만 이 디자인 패턴 (Design patterns)은 어떤 도메인에도 일반화될 수 있습니다.

만약 여러분이 이 저장소를 읽고 있다면, 여러분은 아마도 하네스 엔지니어 (Harness engineer)일 것입니다. 이 직무가 실제로 포함하는 내용은 다음과 같습니다:

도구 구현 (Implement tools). 에이전트에게 손을 부여하십시오. 파일 읽기/쓰기, 셸 실행 (shell execution), API 호출 (API calls), 브라우저 제어 (browser control), 데이터베이스 쿼리 (database queries). 각 도구는 에이전트가 자신의 환경에서 취할 수 있는 하나의 행동입니다. 도구를 원자적 (atomic)이고, 조합 가능하며 (composable), 명확하게 설명되도록 설계하십시오. -
지식 큐레이션 (Curate knowledge). 에이전트에게 도메인 전문 지식을 부여하십시오. 제품 문서 (Product documentation), 아키텍처 결정 기록 (architecture decision records), 스타일 가이드 (style guides), 컴플라이언스 요구사항 (compliance requirements). 미리 로드하지 말고, 필요할 때 (on demand) 로드하십시오. -
컨텍스트 관리 (Manage context). 에이전트에게 깨끗한 메모리를 부여하십시오. 서브 에이전트 격리 (Subagent isolation)는 노이즈 누출 (noise leakage)을 방지합니다. 컨텍스트 압축 (Context compaction)은 과거 기록이 현재를 압도하는 것을 방지합니다. 태스크 시스템 (Task systems)은 목표가 단일 대화를 넘어 지속되도록 합니다. -
권한 제어 (Control permissions). 에이전트에게 경계 (Boundaries)를 부여하십시오. 파일 접근을 샌드박스 (Sandbox)화 하십시오. 파괴적인 작업에는 승인을 요구하십시오. 에이전트와 외부 시스템 간의 신뢰 경계 (Trust boundaries)를 강제하십시오. -
궤적 데이터 수집 (Collect trajectory data). 에이전트가 여러분의 하네스에서 실행하는 모든 행동 시퀀스 (action sequence)는 학습 신호 (training signal)입니다. 실제 배포 궤적 (deployment trajectories)은 차세대 에이전트 모델을 미세 조정 (fine-tuning)하기 위한 원재료입니다.

여러분은 지능을 작성하는 것이 아닙니다. 여러분은 지능이 거주하는 세계를 구축하는 것입니다. 그 세계의 품질이 지능이 자신을 얼마나 효과적으로 표현할 수 있는지를 직접적으로 결정합니다.

하네스를 잘 구축하십시오. 나머지는 모델이 할 것입니다.

Claude Code가 우리가 본 것 중 가장 우아하고 가장 완전한 에이전트 하네스 (agent harness) 구현체이기 때문입니다. 어떤 영리한 트릭 때문이 아니라, 그것이 하지 않는 일들 때문입니다. 그것은 에이전트가 되려고 하지 않습니다. 경직된 워크플로우 (workflows)를 강요하지 않습니다. 모델의 자체적인 판단을 대신하여 수작업으로 만든 결정 트리 (decision trees)를 끼워 넣지 않습니다. 그것은 모델에게 도구 (tools), 지식 (knowledge), 컨텍스트 관리 (context management), 그리고 권한 경계 (permission boundaries)를 제공한 뒤, 그 길을 비켜줍니다.

Claude Code를 그 본질로 분해해 보면 다음과 같습니다:

Claude Code = 하나의 에이전트 루프 (agent loop)
+ 도구 (tools) (bash, read, write, edit, glob, grep, browser...)
+ 온디맨드 기술 로딩 (on-demand skill loading)
...

그게 전부입니다. 에이전트 자체는 무엇인가요? 바로 Claude입니다. 하나의 모델이죠. Anthropic이 인간의 추론과 코드의 전체 범위를 통해 학습시킨 모델입니다. 하네스가 Claude를 똑똑하게 만든 것이 아닙니다. Claude는 이미 똑똑했습니다. 하네스는 Claude에게 손과 눈, 그리고 작업 공간을 제공했을 뿐입니다.

여기서 얻어야 할 교훈은 "Claude Code를 복사하라"가 아닙니다. 교훈은 다음과 같습니다: 최고의 에이전트 제품은 자신의 역할이 지능 (intelligence)이 아니라 하네스 (harness)임을 이해하는 엔지니어들로부터 나온다.

에이전트 패턴 (THE AGENT PATTERN)
=============================
사용자 (User) --> 메시지 배열 (messages[]) --> LLM --> 응답 (response)
...

def agent_loop(messages):
while True:
response = client.messages.create(
...

모든 레슨은 이 루프 위에 하나의 하네스 메커니즘을 층층이 쌓아 올립니다. 루프 자체는 절대 변하지 않습니다. 루프는 에이전트의 것입니다. 메커니즘은 하네스의 것입니다.

루프는 불변입니다. 도구, 지식, 그리고 권한은 변합니다. 에이전트 (Agent) = 모델 (LLM) + 일반화된 운영 환경 (Harness)입니다.

이 저장소는 현재 두 가지 튜토리얼 트랙을 포함하고 있습니다:

현재 트랙: root-level
루트 레벨의 s01-s20 폴더들이 새로운 정식 버전 (canonical version)입니다. s01_* ... s20_* 각 장에는 전체 서사가 담긴 README, 번역, 실행 가능한 code.py, 그리고 필요한 경우 다이어그램이 포함되어 있습니다.

레거시 전환 트랙 (Legacy transition track):
이들은 여전히 이전의 12개 레슨 버전을 유지하고 있습니다. 새로운 20개 레슨 트랙이 안착될 때까지 기존 독자, 오래된 링크, 그리고 웹 플랫폼을 위해 임시로 유지됩니다. docs/, agents/

, 그리고 현재의 web/ 앱

지금 시작하는 경우라면, 루트 레벨의 s01_agent_loop/부터 s20_comprehensive/까지의 챕터를 읽으십시오. 만약 오래된 링크를 따라오고 있거나 현재의 웹 앱 (web app)을 사용 중이라면, 기존의 12개 레슨 트랙 (legacy 12-lesson track)을 읽고 있을 가능성이 높습니다. 기존 트랙과 현재 트랙의 챕터 번호가 항상 일치하는 것은 아니므로, 트랙 간에 챕터 번호를 혼용하지 않도록 주의하십시오.

기존 12개 레슨 트랙	현재 20개 레슨 트랙	주제
old s01	new s01	에이전트 루프 (Agent Loop)
...

이 리포지토리 (repository)는 0에서 1로 나아가는 하네스 엔지니어링 (harness engineering) 학습 프로젝트입니다. 즉, 에이전트 모델 (agent model) 주변의 작동 환경을 구축하는 방법을 가르칩니다. 학습 경로를 명확하게 유지하기 위해, 일부 프로덕션 메커니즘 (production mechanisms)은 의도적으로 단순화하거나 생략되었습니다:

• PreToolUse, SessionStart/End, ConfigChange와 같은 전체 이벤트 / 훅 버스 (event / hook bus) 동작. 교육용 코드는 필요한 경우에만 최소한의 라이프사이클 이벤트 (lifecycle events)를 사용합니다.
• 규칙 기반의 권한 거버넌스 (permission governance) 및 전체 신뢰 워크플로우 (trust workflows).
• 재개/포크 (resume/fork)와 같은 세션 라이프사이클 제어, 그리고 더 완전한 워크트리 (worktree) 라이프사이클 처리.
• 전송 (transport), OAuth, 리소스 구독 (resource subscription), 폴링 (polling)과 같은 전체 MCP 런타임 (runtime) 세부 사항.

이 리포지토리에 포함된 JSONL 메일박스 프로토콜 (mailbox protocol)은 교육용 구현이며, 특정 프로덕션 내부 구현에 대한 주장이 아닙니다.

각 레슨은 하나의 하네스 메커니즘 (harness mechanism)을 추가합니다. 각 메커니즘에는 모토 (motto)가 있습니다.

s01 "하나의 루프와 Bash만 있으면 충분합니다" — 하나의 도구 + 하나의 루프 = 하나의 에이전트

s02 "도구를 추가한다는 것은 하나의 핸들러 (handler)를 추가하는 것을 의미합니다" — 루프는 건드리지 않습니다; 새로운 도구는 디스패치 맵 (dispatch map)에 등록됩니다.

s03 "경계를 먼저 설정한 다음 자유를 부여하십시오" — 무엇이 실행될 수 있는지, 무엇이 중단되어야 하는지, 무엇이 승인을 필요로 하는지 확인합니다.

s04 "루프 주변에 훅 (hook)을 거십시오, 루프를 다시 작성하지 마십시오" — 메인 루프를 변경하지 않고 확장 지점 (extension points)을 추가합니다.

s05 "계획이 없는 에이전트는 표류합니다" — 시작하기 전에 단계를 나열하십시오; 완료율이 두 배로 높아집니다.

s06 "큰 작업은 작게 나누고, 각 서브태스크 (subtask)는 깨끗한 컨텍스트 (context)를 가집니다" — 서브 에이전트 (subagents)가 부수적인 작업을 수행하고 결과만을 가져옵니다.

s07 "지식을 미리 로드하지 말고, 필요할 때 로드하라" — 기술 목록을 먼저 나열하고, 필요할 때만 확장합니다.

s08 "컨텍스트는 항상 가득 찬다 — 공간을 확보할 방법을 마련하라" — 다층 압축 전략 (multi-layer compaction strategies)을 통해 무한한 세션을 확보할 수 있습니다.

s09 "중요한 것은 기억하고, 중요하지 않은 것은 잊어라" — 세 가지 서브시스템: 선택 (selection), 추출 (extraction), 통합 (consolidation).

s10 "프롬프트는 하드코딩하는 것이 아니라, 런타임 (runtime)에 조립된다" — 섹션 기반 연결 (section-based concatenation), 필요 시 로드.

s11 "오류는 끝이 아니라, 재시도 (retry)의 시작이다" — 실패 시 재시도하거나, 공간을 확보하거나, 다른 경로를 택하십시오.

s12 "큰 목표는 작고 순서가 있는 작업으로 나뉘며, 디스크에 저장된다" — 멀티 에이전트 협업 (multi-agent coordination)의 기초가 되는 파일 기반 작업 그래프 (file-backed task graph).

s13 "느린 작업은 백그라운드로 보내고, 에이전트는 계속 생각한다" — 백그라운드 스레드 (background threads)가 명령을 실행하며, 완료 시 알림 (notifications)이 주입됩니다.

s14 "사람의 개입 없이, 일정에 따라 실행한다" — 시간에 따라 작업을 자동으로 트리거 (trigger) 합니다.

s15 "한 명의 에이전트가 감당하기에 너무 크다면 — 팀원에게 위임하라" — 지속적인 팀원 (persistent teammates) + 비동기 메일박스 (async mailboxes).

s16 "팀원들에게는 공유된 통신 규칙이 필요하다" — 협업을 위해 고정된 요청-응답 (request-reply) 형식을 사용합니다.

s17 "팀원들이 직접 보드를 확인하고 작업을 가져간다" — 리더가 하나씩 할당하는 것이 아니라, 스스로 조직화 (self-organizing) 합니다.

s18 "각자는 자신의 디렉토리에서 작업하며, 서로 간섭하지 않는다" — 작업 (tasks)은 목표를 소유하고, 워크트리 (worktrees)는 디렉토리를 소유하며, ID로 결합됩니다.

s19 "역량이 부족한가? MCP를 통해 더 많이 연결하라" — 외부 도구를 동일한 도구 풀 (tool pool)에 연결합니다.

s20 "많은 메커니즘, 하나의 루프" — 이전의 모든 메커니즘은 하나의 완전한 하네스 (harness)로 돌아옵니다.

핵심 라인: 행동(act) → 복잡한 작업 처리(handle complex work) → 기억 및 복구(remember and recover) → 장기 작업 실행(run long tasks) → 협업(collaborate) → 확장 및 조립(extend and assemble).

flowchart TD
%% Card styles
classDef stage1 fill:#E3F2FD,stroke:#1976D2,stroke-width:2px,color:#0D47A1,rx:12,ry:12,text-align:left
...

장 (Chapter)	주제 (Topic)	핵심 개념 (Key Concepts)
s01	에이전트 루프 (Agent Loop)	messages / while True / stop_reason
...	...	...
각 장은 하나의 폴더입니다. 폴더를 열면 다음을 찾을 수 있습니다: