Learn Claude Code: Bash 하나로 시작하는 Claude Code 스타일 AI 에이전트 학습 프로젝트

GitHub - shareAI-lab/learn-claude-code: Bash is all you need - A nano Claude Code–like agent, built from 0 to 1

---

프로젝트 소개

이 저장소를 한 문장으로 설명하면 이렇습니다.

“Claude Code 스타일의 에이전트를 가장 단순한 루프에서 시작해, 점진적으로 실제적인 메커니즘까지 확장해 보는 학습용 레퍼런스 구현.” 

구성도 꽤 명확합니다.
agents/에는 s01부터 s12까지의 Python 레퍼런스 구현과 s_full.py 캡스톤 예제가 들어 있고, docs/{en,zh,ja}에는 설명 문서, web/에는 Next.js 기반의 인터랙티브 학습 플랫폼, skills/에는 s05에서 사용하는 스킬 파일이 들어 있습니다. 또한 requirements.txt를 보면 Python 의존성은 놀랄 만큼 작아서 anthropic과 python-dotenv 정도만 필요합니다. 이 점도 의도적입니다. 복잡한 의존성을 걷어내고 “에이전트의 본질이 무엇인지” 보이게 하려는 설계라고 볼 수 있습니다.

---

왜 이 프로젝트가 등장했을까

AI 에이전트를 설명하는 많은 자료는 둘 중 하나로 흐르기 쉽습니다.

첫째, 너무 추상적입니다.
“에이전트는 계획하고, 툴을 쓰고, 메모리를 관리한다” 같은 설명은 많지만, 실제 코드에서 어떤 루프가 돌고 어떤 시점에 툴 결과를 다시 모델에 넣는지가 빠져 있는 경우가 많습니다. 

둘째, 너무 거대합니다.
실무용 프레임워크나 상용 에이전트는 권한 정책, 이벤트 버스, 복수 프로세스, 원격 런타임, UI, 세션 관리까지 한 번에 얹혀 있어 초중급 개발자가 핵심 패턴을 분리해서 보기 어렵습니다. 이 저장소는 그래서 **“한 번에 하나씩만 추가한다”**는 방식으로 설계되었습니다. README에 따르면 12개의 progressive sessions가 있고, 각 세션은 “한 가지 메커니즘”과 “한 가지 모토”를 추가합니다. 

이 방식이 좋은 이유는 개발자가 에이전트를 기능 목록이 아니라 축적되는 설계 원리로 이해하게 만들어 주기 때문입니다. 예를 들어 s01에서 루프를 이해하고, s02에서 툴 디스패치를 붙이고, s03에서 계획을 넣고, s04에서 서브에이전트를 분리하고, 이후에 컨텍스트 압축과 작업 영속성, 팀 협업, 격리 실행으로 확장됩니다. 즉, “에이전트는 원래 복잡한 시스템”이 아니라 **“작은 반복 구조 위에 층층이 기능이 올라간 결과물”**이라는 걸 코드로 체감하게 해 줍니다. 

---

핵심 아이디어: 에이전트의 본질은 결국 루프다

이 프로젝트의 가장 중요한 메시지는 README에 거의 그대로 드러납니다.
사용자 메시지를 받고, LLM을 호출하고, 응답이 tool_use라면 툴을 실행하고, 그 결과를 다시 메시지에 넣어 LLM에게 돌려주는 것. 이 반복이 바로 최소 에이전트 패턴입니다. 

README와 s01_agent_loop.py를 바탕으로 보면 구조는 사실상 아래와 같습니다. 

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})

이 코드는 단순하지만, 오늘날 많은 AI 코딩 에이전트의 공통 뼈대를 거의 그대로 보여 줍니다.
에이전트는 무언가 신비한 존재라기보다, 모델이 툴 호출을 제안하면 실행하고, 그 결과를 다시 모델에게 먹이는 제어 루프라고 이해하면 됩니다. 이 저장소가 좋은 이유는 이 패턴을 숨기지 않는다는 점입니다. 

---

핵심 기능

1) 최소 Agent Loop

s01은 가장 기본적인 루프만 보여 줍니다. bash 하나를 툴로 두고, 모델이 셸 명령을 요청하면 실행한 뒤 결과를 되돌립니다. s01_agent_loop.py를 보면 시스템 프롬프트도 매우 간단하고, 위험 명령 일부를 문자열 수준에서 차단하며, subprocess.run으로 셸 명령을 수행합니다. 즉, “에이전트”의 최소 구현이 사실상 LLM + tool schema + while loop라는 점을 아주 직설적으로 보여 줍니다. 

개발자 관점에서 중요한 포인트는 두 가지입니다.
하나는 에이전트의 핵심 제어 흐름이 프레임워크 종속적이지 않다는 것, 다른 하나는 첫 단계부터 “툴 사용 결과를 다시 모델에 주입해야 한다”는 피드백 루프를 이해하게 만든다는 점입니다.

2) 툴 확장: 기능 추가는 핸들러 추가다

s02의 모토는 “Adding a tool means adding one handler”입니다. README 설명대로 루프 자체는 바꾸지 않고, 새로운 툴을 디스패치 맵에 등록하는 방식으로 확장합니다. 이건 실무적으로도 중요합니다. 에이전트를 설계할 때 복잡한 orchestration보다 먼저 생각해야 할 것은 루프는 고정하고, 툴만 조립 가능하게 만드는 인터페이스입니다. 

s_full.py 상단을 보면 실제로 bash, read, write, edit, TodoWrite, task 관련 툴, background 작업, 팀 통신 툴 등이 전부 하나의 툴 디스패치 구조 아래 통합됩니다. 이 구조는 “에이전트의 두뇌는 모델, 손발은 툴”이라는 설계를 잘 보여 줍니다. 

3) 계획(Planning)과 Todo 관리

s03의 모토는 “An agent without a plan drifts”입니다. README 설명에서는 먼저 해야 할 일을 나열하고, 그 뒤 실행하도록 만들면 완료율이 올라간다고 말합니다. s_full.py의 TodoManager 구현을 보면 항목 수 제한, 상태 검증, 동시에 하나만 in_progress 허용 같은 간단하지만 실용적인 규칙이 들어 있습니다. 

이 부분은 실제 개발자 도구를 만들 때 꽤 중요합니다.
LLM은 곧잘 “다음에 뭘 해야 하는지”를 잊거나 한 번에 너무 많은 일을 벌이기 쉽습니다. Todo 계층을 두면 모델이 해야 할 일을 외부 상태로 드러내게 되고, 그 자체가 작업 추적 가능성(observability) 과 실행 안정성을 높이는 장치가 됩니다. 

4) 서브에이전트와 깨끗한 컨텍스트

s04는 큰 작업을 작은 작업으로 쪼개고, 각 하위 작업에 독립적인 messages[]를 주는 구조를 소개합니다. README는 이것을 “each subtask gets a clean context”라고 설명합니다. s_full.py의 run_subagent도 별도의 메시지 배열과 제한된 툴 집합을 사용하는 형태입니다.

이 설계의 장점은 메인 대화가 오염되지 않는다는 점입니다.
탐색용 서브에이전트, 수정용 서브에이전트, 파일 분석용 서브에이전트를 분리하면, 주 에이전트는 결과 요약만 받으면 됩니다. 결국 이건 멀티에이전트 이전 단계에서 먼저 필요한 컨텍스트 격리 패턴입니다. 

5) Skills: 지식은 필요할 때만 불러온다

s05의 모토는 “Load knowledge when you need it, not upfront”입니다. README에 따르면 스킬은 시스템 프롬프트에 미리 전부 넣는 것이 아니라, 필요할 때 tool_result 형태로 주입합니다. s_full.py의 SkillLoader도 skills/ 디렉터리 아래 SKILL.md를 읽어 메타데이터와 본문을 로드하는 구조입니다. 

이건 토큰 효율 측면에서도 좋고, 구조적으로도 좋습니다.
모델에게 모든 지식을 항상 들고 있게 하는 대신, 작업 맥락에 따라 필요한 스킬만 주면 됩니다. 요즘 말하는 RAG, tool-based retrieval, context injection 같은 패턴을 아주 단순한 형태로 체험할 수 있는 셈입니다. 

6) 컨텍스트 압축

s06은 길어지는 세션을 다룹니다. README는 3-layer compression strategy를 언급하고, s_full.py에는 microcompact와 auto_compact가 구현되어 있습니다. 전자는 오래된 툴 결과를 정리하고, 후자는 대화 전체를 transcript로 저장한 뒤 요약본으로 교체하는 방식입니다. 

여기서 중요한 점은 “컨텍스트가 꽉 차면 끝”이 아니라는 겁니다.
실제 에이전트 시스템은 결국 메모리를 무한히 가질 수 없기 때문에, 무엇을 버리고 무엇을 남길지를 아키텍처 문제로 다뤄야 합니다. 이 저장소는 그 문제를 거창한 메모리 시스템 없이도 이해할 수 있게 해 줍니다.

7) 태스크 영속화와 백그라운드 작업

s07은 파일 기반 CRUD와 의존성 그래프를 통한 태스크 보드를 다루고, s08은 daemon thread 기반의 백그라운드 실행과 완료 알림 큐를 다룹니다. README 설명만 봐도 이 저장소가 단순한 REPL 데모를 넘어, 장기 작업을 다루는 런타임의 기본기까지 건드리고 있다는 걸 알 수 있습니다. 

s12 코드 일부를 보면 태스크 정보가 .tasks/task_12.json 같은 파일로 유지되고, 워크트리 인덱스는 .worktrees/index.json으로 관리됩니다. 즉 상태를 메모리에만 두지 않고 파일로 내리면서, 작업과 실행 공간을 연결합니다. 

8) 에이전트 팀과 프로토콜, 자율 할당, 워크트리 격리

s09~s12는 이 프로젝트의 후반부 하이라이트입니다. README에 따르면 팀원 에이전트, JSONL 메일박스, 요청-응답 패턴, idle cycle 기반 auto-claim, 그리고 각 작업을 별도 디렉터리/워크트리에서 수행하는 격리 구조까지 이어집니다.

s12_worktree_task_isolation.py는 이를 매우 상징적으로 보여 줍니다. 태스크는 control plane, worktree는 execution plane이라고 설명하고, 핵심 통찰을 “Isolate by directory, coordinate by task ID”라고 정리합니다. 이건 실전에서도 그대로 통하는 패턴입니다. 서로 다른 작업이 같은 파일 시스템 공간을 공유하면 충돌이 생기기 쉽기 때문에, 작업 단위 격리는 멀티에이전트 또는 병렬 코딩 환경에서 매우 중요한 주제입니다. 

---

프로젝트 구조

이 저장소를 개발자 시점에서 다시 구조화하면 아래처럼 볼 수 있습니다.

이 다이어그램이 보여 주는 핵심은, 에이전트의 중심은 여전히 Agent Loop이고, 나머지는 모두 그 위에 붙는 계층이라는 점입니다. Planning, Skills, Compression, Tasks, Team, Worktree는 각각 독립 기능처럼 보이지만, 결국은 루프 주변에 붙는 운영 장치들입니다. 이 관점으로 보면 복잡한 에이전트도 훨씬 이해하기 쉬워집니다. 

README의 실제 디렉터리 구조를 바탕으로 보면 저장소는 대략 아래처럼 이해할 수 있습니다. 

learn-claude-code/
├─ agents/                  # s01 ~ s12, s_full 레퍼런스 구현
├─ docs/{en,zh,ja}/         # 세션별 문서
├─ web/                     # Next.js 기반 인터랙티브 학습 플랫폼
├─ skills/                  # s05용 SKILL.md
├─ .github/workflows/ci.yml # 타입체크 + 빌드 CI
├─ requirements.txt
└─ .env.example

---

실행 방법

이 저장소는 시작도 간단합니다. README 기준으로 아래 순서로 바로 실행할 수 있습니다. 

git clone https://github.com/shareAI-lab/learn-claude-code
cd learn-claude-code
pip install -r requirements.txt
cp .env.example .env

그다음 .env에 ANTHROPIC_API_KEY를 넣고, 첫 번째 세션 또는 마지막 세션을 실행하면 됩니다. README는 시작점으로 s01_agent_loop.py, 전체 진행의 끝점으로 s12_worktree_task_isolation.py, 그리고 모든 메커니즘을 합친 예제로 s_full.py를 제시합니다. 

python agents/s01_agent_loop.py
python agents/s12_worktree_task_isolation.py
python agents/s_full.py

웹 기반 학습 플랫폼도 따로 제공됩니다. README에 따르면 web/ 폴더에서 npm install && npm run dev로 실행하며, 인터랙티브 시각화와 step-through 다이어그램, 소스 뷰어, 문서를 제공합니다. 

cd web
npm install
npm run dev

---

코드로 보는 설계 포인트

1) 가장 작은 도구: Bash

s01은 결국 Bash 하나로 시작합니다.
툴 정의도 단순해서 command 문자열 하나를 입력으로 받고, 핸들러는 subprocess.run으로 실행합니다. 위험 명령은 일부 차단하지만, 구조적으로는 매우 순수한 형태입니다. 이 설계는 “에이전트 = 코드 편집기 내장 초거대 시스템”이라는 인상을 깨 줍니다. 사실 시작은 명령 실행기 하나여도 충분합니다. 

TOOLS = [{
    "name": "bash",
    "description": "Run a shell command.",
    "input_schema": {
        "type": "object",
        "properties": {"command": {"type": "string"}},
        "required": ["command"],
    },
}]

2) 작업은 파일로 남긴다

s12에서 태스크는 JSON 파일이고, 워크트리 인덱스도 JSON 파일입니다.
즉, 상태 관리 DB 없이도 에이전트 런타임의 핵심 상태를 파일 시스템 위에 모델링할 수 있음을 보여 줍니다. 학습용 프로젝트로서는 매우 좋은 선택입니다. 눈으로 바로 확인할 수 있고, 디버깅도 쉽기 때문입니다. 

예를 들면 README와 s12 설명을 바탕으로 이런 형태를 상상할 수 있습니다. 

{
  "id": 12,
  "subject": "Implement auth refactor",
  "status": "in_progress",
  "worktree": "auth-refactor"
}

이 구조는 나중에 SQLite, Redis, Postgres, 이벤트 소싱 등으로 확장해도 기본 개념이 그대로 유지됩니다. 그래서 학습 가치가 높습니다. 

---

이 프로젝트의 장점

가장 큰 장점은 설명 방식이 아키텍처 친화적이라는 점입니다.
세션별 모토가 명확하고, 한 세션마다 하나의 메커니즘만 추가되기 때문에 “왜 이 기능이 필요한지”가 이해됩니다. README도 문제, 해결, ASCII 다이어그램, 최소 코드 중심의 문서 구성을 강조합니다.

두 번째 장점은 작은 구현으로 큰 개념을 배울 수 있다는 점입니다.
의존성이 매우 적고, Python 스크립트 형태라 읽기 쉽습니다. 거대한 프레임워크를 파고드는 대신, 직접 코드 파일을 열어 에이전트 루프와 상태 변화를 따라갈 수 있습니다.

세 번째 장점은 실전 감각이 생각보다 강하다는 점입니다.
교육용 프로젝트이지만 컨텍스트 압축, 백그라운드 작업, 팀 프로토콜, 작업 보드, 워크트리 격리 같은 주제는 실제 제품 개발에서도 바로 중요해지는 문제들입니다. 따라서 이 저장소는 단순 입문서를 넘어, 에이전트 런타임 설계 입문서에 가깝습니다. 

---

아쉬운 점과 주의할 점

물론 이 저장소를 그대로 production 설계로 받아들이면 안 됩니다. README는 분명히 이 프로젝트가 몇 가지 production 메커니즘을 의도적으로 생략한다고 말합니다. 정교한 권한 관리, 전체 이벤트 버스, 세션 라이프사이클 제어, 완전한 MCP 런타임 등의 부재는 학습용 단순화를 위한 선택입니다. 

또한 s01_agent_loop.py의 명령 차단은 문자열 기반의 최소 보호에 가깝습니다. 실전 샌드박싱, 리소스 제한, 파일 접근 제어, 감사 로그, 정책 엔진 같은 것은 별도 설계가 필요합니다. 그러니 이 프로젝트는 원리 학습용 기준점으로 보는 것이 가장 적절합니다. 

---

어떤 개발자에게 추천할까

이 프로젝트는 특히 아래 개발자에게 잘 맞습니다.

• Claude Code, Cursor, Copilot Agents 같은 도구를 쓰고 있지만 내부 구조가 궁금한 개발자
• LLM 에이전트 프레임워크를 “사용”하는 수준에서 벗어나 “설계”해 보고 싶은 개발자
• 멀티에이전트, 툴 호출, 컨텍스트 관리, 작업 격리의 감각을 코드로 익히고 싶은 개발자 

반대로, 바로 실전 배포 가능한 풀스택 에이전트 플랫폼을 찾는다면 이 저장소는 목적이 다릅니다. README도 이를 학습용 0→1 프로젝트로 규정합니다. 

---

마무리

learn-claude-code의 진짜 가치는 “Claude Code 비슷한 걸 만든다”에 있지 않습니다.
더 중요한 가치는 AI 코딩 에이전트를 이루는 본질적인 계층을 순서대로 해부해 준다는 데 있습니다. 최소 루프에서 출발해, 툴, 계획, 서브에이전트, 스킬 주입, 컨텍스트 압축, 태스크 영속화, 팀 협업, 워크트리 격리까지 올라가는 흐름은 에이전트 아키텍처를 공부하는 데 매우 좋은 학습 경로입니다. 

개인적으로는 이 저장소를 “에이전트 프레임워크”보다 **“에이전트 구조를 읽는 교과서”**로 보는 편이 더 정확하다고 생각합니다.
요즘 AI 에이전트가 너무 마법처럼 포장될 때가 많은데, 이 프로젝트는 오히려 반대로 말합니다.

모델이 있고, 툴이 있고, 결과를 다시 넣는 루프가 있다.
그 위에 필요한 운영 메커니즘을 조금씩 올리면 된다. 

.