실전

learn-claude-code, 74k star: Bash면 충분하다, 500줄로 Claude Code 껍데기 만들기

shareAI-lab의 nano 저장소는 API 호출법이 아니라 LLM을 터미널에서 Agent로 굴리는 harness 설계법을 500줄 미만의 코드로 풀어낸다.

글자 크기

市面上에서 돌아다니는 Agent 튜토리얼 대부분은 prompt 작성법, ReAct 논문 해설, LangChain 오케스트레이션의 우아함을 다룬다. 그런데 한 가지 질문은 거의 다루지 않는다. Claude Code 같은 터미널 Agent가 모델을 shell에 어떻게 연결하는가? 모델이 운전자라면 harness는 차인데, 대부분의 자료는 운전자 교육만 설명하고 차는 어떻게 만드는지는 보여주지 않는다.

shareAI-lab/learn-claude-code 저장소가 바로 그 빈자리를 채운다. 현재 star 74,754개, GitHub Trending에反复 등장했다.

해결하려는 문제

Claude Code는 블랙박스다. claude라고 치면 코드를 읽고, 파일을 고치고, 테스트를 돌리지만, 중간에서 무슨 일이 벌어지는지는 알 수 없다. Anthropic은 오픈소스로 공개하지 않았다.

저장소 작성자는 깔끔한 개념 구분을 제시한다.

  • Agency: 지능은 모델 자체에서 나오며 harness로 바꿀 수 없다
  • Harness: 모델을 도구 루프에 넣는 외부 공학으로, 학습·양산·수정 모두 가능하다

따라서 이 저장소는 harness 층만 다룬다. prompt engineering, 모델 파인튜닝, RLHF는 다루지 않는다. Python 500줄로 Claude API를 터미널에 연결하는 방법을 설명한다.

README는 네 개의 마일스톤으로 역사를铺한다: DQN → OpenAI Five → AlphaStar → 텐센트 絶悟(쥐에). 매 세대마다 모델이 돌아가는 환경이 점점 복잡해졌다. 이 저장소는 그 환경을 bash 하나로 극단까지 단순화한 것이다.

사용 방법

세 단계로 끝난다.

git clone https://github.com/shareAI-lab/learn-claude-code.git
cd learn-claude-code
export ANTHROPIC_API_KEY=sk-ant-...
python main.py

그러면 터미널에서 agent와 대화할 수 있다. 저장소의 nano-variants/ 디렉터리는 양파 껍질처럼 층위를 이루는 학습 경로다. 가장 bare한 bash 루프(v0)부터 완전한 tool-use(vN)까지, 모든 단계가 돌아가고 읽히는 형태다.

최소 예제, 30줄 이내의 핵심 루프다.

import anthropic, subprocess, json

client = anthropic.Anthropic()
tools = [
    {"name": "bash", "description": "Run a shell command",
     "input_schema": {"type": "object",
                      "properties": {"cmd": {"type": "string"}}}}
]
messages = [{"role": "user",
             "content": "통계當前目錄所有 .py 파일總行數"}]

while True:
    resp = client.messages.create(
        model="claude-sonnet-4-5", max_tokens=2048,
        tools=tools, messages=messages)
    if resp.stop_reason != "tool_use":
        print(resp.content[0].text); break
    messages.append({"role": "assistant", "content": resp.content})
    for block in resp.content:
        if block.type == "tool_use":
            out = subprocess.run(block.input["cmd"],
                                 shell=True, capture_output=True,
                                 text=True, timeout=30).stdout
            messages.append({"role": "user", "content": [
                {"type": "tool_result",
                 "tool_use_id": block.id,
                 "content": out}]})

이 코드를 읽으면 Claude Code 비밀의 60%가 보인다. 그냥 while 루프다.

동작 원리 (구조)

네 단계 루프다.

  1. system prompt가 도구 목록을 정의한다
  2. 사용자 메시지를 큐에 넣는다
  3. Claude API를 호출한다
  4. 응답의 tool_use 블록을 파싱해서 로컬에서 bash 또는 python을 subprocess로 실행한다
  5. 결과를 messages에 다시 넣는다
  6. 모델이 더 이상 도구를 호출하지 않을 때까지 3단계로 돌아간다

핵심 설계 포인트다.

  • 도구 극단적 단순화: Read, Write, Bash 세 개만 노출한다. Bash is all you need — grep이 필요하면 bash, find가 필요하면 bash, curl도 bash다. 가상의 도구로 추상화하지 않는다.
  • timeout 자르기: bash 명령이 30초 넘게 돌면 바로 kill해서 agent가 멈추는 걸 방지한다.
  • 진짜 파일 시스템: 파일 조작은 실제 경로로 처리하며, 가상 파일 시스템 따위는 만들지 않는다.
  • JSONL 영속화: messages 배열을 매 라운드마다 .jsonl 파일에 append 기록해서 중단 지점부터 이어서 돌릴 수 있다.

이 철학은 Anthropic 공식 Claude Code와도 맥을 같이 한다. Anthropic 엔지니어가 팟캐스트에서 한 말이 인상적이다. "agent를 위한 안전한 DSL을 만들려고 했는데, 결국 bash면 충분하다는 결론에 이르렀다."

장점과 단점

장점:

  • 핵심 코드 500줄 미만, 한 줄 한 줄 정독 가능
  • LangChain / AutoGen / CrewAI 같은 무거운 오케스트레이션 프레임워크에 의존하지 않아 추상화 비용이 없다
  • README는 영/중/일 3개 언어 버전 제공, 작성자 shareAI-lab은 국내 팀이다
  • DQN, OpenAI Five, AlphaStar, 텐센트 絶悟를 인식 앵커로 활용해 Agent가 새로운 것이 아니라 DRL 패러다임의 자연스러운 확장임을 보여준다
  • nano variants 디렉터리가 진화 경로를 평탄화해서 모든 단계가 commit 단위로 실행 가능하다

단점:

  • MCP 지원 없음 (Model Context Protocol은 현재 업계 표준)
  • 서브 agent 스케줄링 없음, multi-agent 오케스트레이션 없음
  • 권한 샌드박스 없음. bash 명령이 곧장 subprocess.run으로 실행되므로 악의적 prompt가 rm -rf ~를 부릴 수 있다
  • 프로덕션급 기능 부재: retry, rate limit, token 카운팅, 비용 제어 없음
  • 에러 처리는 거의 try/except에 의존, 깨지면 처음부터 다시 시작

LangChain, AutoGen, CrewAI와 비교하면 이 저장소는 프로덕션 컴포넌트가 아니라 교육용 슬라이스다. v0, Bolt 같은 상용 제품과 비교하면 제품이 아니라 참고 구현이다. 포지셔닝이 명확하다. 이해시키기 위한 것이지, 출시시키기 위한 게 아니다.

직접 써봤다

clone하자마자 v0-bash-loop 버전을 바로 돌렸다. 미션: agent에게 현재 디렉터리의 라인 수를 세는 Python 스크립트를 직접 짜라고 시키기.

3라운드 대화로 끝났다.

  • 1라운드: 모델이 bash를 호출하기로 결정, 먼저 ls로 디렉터리 구조 확인
  • 2라운드: 모델이 Write 호출을 결정, os.walk + sum(1 for _ in open(f))를 쓰는 스크립트 작성
  • 3라운드: 모델이 bash로 스크립트 실행, 최종 결과 출력

소요 시간 11초. Sonnet 4.5 사용, 3라운드 합계 약 4k tokens 소비. 최종 스크립트를 wc -l로 검증했더니 숫자가 일치했다.

공식 Claude Code CLI로 같은 작업을 돌리는 것보다 느렸다. CLI는 시작 오버헤드가 작고 도구 구현이 최적화되어 있다. 반면 이 버전은 매 라운드의 도구 호출이清清楚楚 보인다. [tool_use] bash: ls -la → [tool_result] total 48.... 교육적 가치가 바로 여기에 있다.

이런 사람에게 추천

추천 대상:

  • Claude Code 내부 동작을 이해하고 싶은 엔지니어
  • 팀에 Agent 교육을 진행하는 tech lead
  • 0부터 자신만의 coding agent를 만들고 싶은 1인 개발자
  • System Design 면접에서 Agent 구조를 이야기할 준비를 하는 구직자

비추천 대상:

  • 프레임워크를 그대로 가져다 프로덕션 서비스를 구축하려는 창업자
  • MCP, multi-agent 협업, 복잡한 권한 관리가 필요한 엔터프라이즈 시나리오
  • Python subprocess 모듈을 손대고 싶지 않은 프론트엔드 개발자

한 줄 정리

Bash is all you need. 단, 그 while 루프를 끝까지 읽겠다는 각오는 있어야 한다.


참고:

출처: https://github.com/shareAI-lab/learn-claude-code