learn-claude-code 딥다이브
— "에이전트가 아니라 하니스를 만들어라"는 20단계 코스

1프로젝트 한줄 요약

"Claude Code 같은 코딩 에이전트가 내부에서 어떻게 동작하는지를, 파이썬 코드 20단계로 한 메커니즘씩 직접 만들어보며 배우는 교과서"입니다. 완성된 도구를 쓰는 법이 아니라 그 도구를 어떻게 짜는가를 가르칩니다. 각 단계는 독립 실행되는 code.py 하나 + 3개 언어(영/중/일) README + 다이어그램으로 이뤄져 있습니다.

이 레포의 정체성은 코드보다 관점에 있습니다. "에이전트를 만든다"는 말은 사실 둘 중 하나라는 것 — ①모델을 학습시키거나(앤트로픽·딥마인드가 하는 일), ②하니스를 짠다(우리 대부분이 하는 일). 이 레포는 ②, 즉 "모델에게 손·눈·작업공간을 쥐여주는 골격 코드"를 만드는 법을 가르칩니다.

2왜 주목받는가

① "에이전트 = 모델 + 하니스"라는 명쾌한 프레이밍

요즘 "AI 에이전트"라는 말은 노코드 워크플로우 빌더·프롬프트 체인 같은 것에 남발됩니다. 이 레포는 그걸 정면으로 "if-else와 노드 그래프로 LLM 호출을 엮은 건 에이전트가 아니라 루브 골드버그 장치"라고 비판하며, "지능은 학습되는 것이지 코딩되는 게 아니다"라는 선명한 테제를 세웁니다. 이 관점 정리만으로도 많은 개발자가 "아하"를 얻습니다.

② "한 단계에 한 메커니즘"이라는 완벽한 학습 곡선

137줄짜리 s01에서 시작해 단계마다 정확히 하나의 메커니즘(권한→훅→할일목록→서브에이전트→압축→기억→…)을 더합니다. 매 단계 표어(motto)가 붙어 있어 "이번 장에서 뭘 배우는지"가 한 줄로 잡힙니다. 난이도가 계단처럼 완만하게 올라가 중도 포기가 적습니다.

③ "진짜 돌아가는 최소 코드"라서 읽힌다

상용 에이전트 소스는 너무 커서 입문자가 길을 잃습니다. 이 레포는 의존성 3개, 단계당 수백 줄로 실제로 실행되는 가장 작은 버전을 보여줍니다. "프로덕션 디테일(완전한 훅 버스·OAuth·MCP 트랜스포트)은 일부러 단순화했다"고 범위를 명시해, 핵심에만 집중하게 합니다.

④ 멀티 프로바이더 + 다국어 + 웹 강의

Anthropic뿐 아니라 MiniMax·GLM·Kimi·DeepSeek 등 Anthropic 호환 API를 ANTHROPIC_BASE_URL 한 줄로 갈아끼울 수 있습니다. README는 영·중·일 3개 언어, 별도 Next.js 강의 사이트까지 갖춰 접근성이 높습니다.

기존 학습 방식과의 비교

3기술 스택 전체 지도

이 레포는 두 부분으로 나뉩니다. ① 핵심 교육 코드는 의존성 단 3개의 순수 파이썬이고, ② 웹 강의 사이트는 별도의 Next.js 앱입니다. 학습의 본체는 ①이고, ②는 그걸 브라우저로 보기 좋게 만든 포장입니다.

핵심 교육 코드 (Python)

멀티 프로바이더 지원 (Anthropic 호환 API)

웹 강의 사이트 (web/, 레거시 12강 트랙)

4아키텍처 심화 분석

전부의 시작 — 변하지 않는 에이전트 루프

20단계 내내 절대 바뀌지 않는 단 하나의 코드입니다. 이걸 손에 익히면 나머지는 전부 이 루프 바깥에 붙는 장식입니다.

# s01 — 코딩 에이전트의 전부
def agent_loop(messages):
    while True:
        response = client.messages.create(
            model=MODEL, system=SYSTEM,
            messages=messages, tools=TOOLS)
        messages.append({"role":"assistant","content":response.content})

        # 모델이 도구를 안 부르면 끝
        if response.stop_reason != "tool_use":
            return

        # 도구 호출을 실제로 실행해 결과를 모음
        results = []
        for block in response.content:
            if block.type == "tool_use":
                output = TOOL_HANDLERS[block.name](**block.input)
                results.append({"type":"tool_result",
                    "tool_use_id":block.id, "content":output})

        # 결과를 되돌려주고 루프 계속
        messages.append({"role":"user","content":results})

설계 패턴 ① — "루프는 건드리지 말고 디스패치 맵만 키운다"

s02의 표어가 "도구를 추가한다 = 핸들러 하나를 추가한다"입니다. 도구가 1개에서 여러 개로 늘어도 루프 코드는 그대로고, TOOL_HANDLERS라는 이름→함수 딕셔너리(디스패치 맵)에 항목만 등록합니다. read·write·edit·bash·glob·grep이 전부 이렇게 붙습니다. "개방-폐쇄 원칙"의 교과서적 사례입니다.

설계 패턴 ② — "루프를 다시 쓰지 말고 루프 둘레에 훅을 건다"

s04의 표어 "Hook around the loop, never rewrite the loop". 도구 실행 전/후에 끼어드는 확장점(훅)을 두어, 권한 검사·로깅·정책 적용 같은 걸 핵심 루프를 수정하지 않고 덧붙입니다. 권한(s03)·훅(s04)이 바로 이 "둘레에 거는" 계층입니다.

설계 패턴 ③ — "경계를 먼저, 자유는 그다음"

s03 권한의 표어 "Set boundaries first, then grant freedom". 도구를 실행하기 전에 "이건 그냥 실행 / 이건 차단 / 이건 사용자 승인 필요"를 분류합니다. s01의 가장 단순한 버전조차 rm -rf /·sudo·shutdown 같은 위험 명령을 블랙리스트로 막는 것에서 출발합니다.

설계 패턴 ④ — "컨텍스트는 늘 가득 찬다. 비우는 법을 마련하라"

대화가 길어지면 토큰 한도에 부딪힙니다. s08(컨텍스트 압축)·s09(기억)은 오래된 히스토리를 요약·선별·통합해 자리를 비웁니다. 이 덕분에 "사실상 무한 세션"이 가능해집니다. 서브에이전트(s06)도 곁가지 작업을 격리된 컨텍스트에서 돌려 결과만 가져오므로, 메인 대화가 잡음으로 오염되지 않습니다.

20단계가 쌓는 메커니즘 전체 지도

5디렉토리 구조 해부

6학습 포인트

에이전트 아키텍처 — "루프는 모델 것, 메커니즘은 하니스 것"

배울 것: 코딩 에이전트의 본질이 tool_use 루프 하나라는 깨달음. 그리고 그 위에 권한·훅·기억·협업을 루프를 수정하지 않고 얹는 법. 이 분리 감각은 어떤 도메인의 에이전트를 짜든 그대로 적용됩니다.

도구 디자인 — atomic·composable·잘 설명된

배울 것: 도구는 작고(atomic), 조합 가능하고(composable), 설명(description)이 명확해야 모델이 잘 씁니다. input_schema를 어떻게 쓰느냐가 모델의 도구 사용 정확도를 좌우한다는 감각을 s02에서 얻습니다.

컨텍스트 엔지니어링 — 압축·기억·서브에이전트

배울 것: LLM의 진짜 병목은 컨텍스트 윈도우입니다. s08(압축)·s09(선별/추출/통합 3단 기억)·s06(서브에이전트 격리)은 "긴 작업에서 어떻게 깨끗한 기억을 유지하는가"라는, 실무에서 가장 중요한 기술을 다룹니다.

권한·보안 — 경계를 코드로

배울 것: 위험 명령 차단(블랙리스트)에서 시작해, "허용/차단/승인필요" 3분류, 도구 실행 전 검사(훅)까지. 자율 에이전트에게 손을 쥐여줄 때 어디까지 자유를 주고 어디서 멈출지를 코드로 표현하는 법을 배웁니다.

멀티 에이전트 협업 — 메일박스·프로토콜·자기조직화

배울 것: s15~s18의 비동기 메일박스(JSONL), 고정 요청-응답 프로토콜, "게시판에서 일을 직접 집는" 자율 분업, 워크트리로 디렉터리를 격리한 병렬 실행. 여러 에이전트를 충돌 없이 굴리는 패턴의 최소 구현입니다.

MCP·스킬 로딩 — 능력의 동적 확장

배울 것: s07(스킬을 미리 다 싣지 않고 필요할 때 펼치기)과 s19(MCP로 외부 도구를 같은 도구 풀에 꽂기)는 "에이전트의 능력을 어떻게 무한 확장하는가"를 보여줍니다. 토큰을 아끼는 on-demand 로딩이 핵심.

7시스템 요구사항

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

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

1주차 — 코어 루프와 도구

s01~s04를 정독·실행합니다. 목표: 루프를 손으로 다시 쓸 수 있을 만큼 외우고, 도구를 디스패치 맵에 등록하는 패턴과 권한/훅을 "루프 둘레에 거는" 감각을 체득. Anthropic Messages API의 tool_use/tool_result 구조도 함께 익히세요.

2주차 — 복잡한 일과 컨텍스트

s05(계획)·s06(서브에이전트)·s08(압축)·s09(기억)을 봅니다. 목표: 컨텍스트 엔지니어링의 핵심 — 언제 무엇을 기억하고, 무엇을 격리하고, 무엇을 압축하는가 — 을 이해하고 내 에이전트에 하나라도 이식하기.

3주차 — 긴 작업과 멀티 에이전트

s11(에러 복구)·s12(태스크 그래프)·s13(백그라운드)·s14(크론)과 s15~s18(팀·프로토콜·자율·워크트리)을 봅니다. 목표: 파일 기반 태스크 영속과 비동기 협업의 최소 구조를 파악. 동시성(threading)·격리(worktree) 개념도 함께.

4주차 — 확장과 종합

s07(스킬 로딩)·s19(MCP)·s20(종합)을 봅니다. 목표: on-demand 능력 확장과 MCP 연결을 이해하고, s20에서 "모든 메커니즘이 하나의 루프로 어떻게 다시 합쳐지는지" 전체 그림을 완성. 여기까지 오면 자기만의 도메인 하니스를 설계할 수 있습니다.

10핵심 키워드 사전

11참고 링크