市面上에서 돌아다니는 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 루프다.
동작 원리 (구조)
네 단계 루프다.
- system prompt가 도구 목록을 정의한다
- 사용자 메시지를 큐에 넣는다
- Claude API를 호출한다
- 응답의
tool_use블록을 파싱해서 로컬에서 bash 또는 python을 subprocess로 실행한다 - 결과를 messages에 다시 넣는다
- 모델이 더 이상 도구를 호출하지 않을 때까지 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 루프를 끝까지 읽겠다는 각오는 있어야 한다.
참고:
- shareAI-lab/learn-claude-code GitHub 저장소
- 현재 star 수: 74,754 (글 작성 시점 기준)