shareAI-lab/learn-claude-code

Learn Claude Code – LLM 에이전트 하네스 구축을 위한 실습 과정

무엇인가요 – Anthropic의 Claude와 같은 대규모 언어 모델(LLM)이 자율적인 코딩 보조자로 작동할 수 있도록 해주는 하네스(주변 코드)를 작성하는 단계별 튜토리얼입니다. 이 리포지토리는 모델을 훈련하지 않습니다. 대신, 사전 훈련된 LLM이 실제 개발 환경에서 안전하고 효과적으로 작동하기 위해 도구, 권한, 컨텍스트 관리, 오케스트레이션을 제공하는 방법을 가르칩니다.

왜 중요한가요 – 현대의 "AI 에이전트"는 훈련된 모델과 모델을 세계(파일 시스템, 쉘, 브라우저, API 등)에 연결하는 런타임의 조합입니다. 대부분의 공개 프로젝트는 모델 자체에 초점을 맞추며, 하네스는 뒷받침되는 요소로 간주됩니다. 이 리포지토리는 반대로 하네스를 핵심 엔지니어링 문제로 다루며, 각 구성 요소를 실제로 구현하는 방법을 명확히 보여줍니다.

작동 방식 – 핵심 루프는 간단한 REPL입니다:

while True:
    response = client.messages.create(model=MODEL, system=SYSTEM,
                                      messages=messages, tools=TOOLS)
    messages.append({"role": "assistant", "content": response.content})
    tool_calls = [b for b in response.content if b.type == "tool_use"]
    if not tool_calls:
        break                     # 모델이 종료를 결정함
    results = []
    for call in tool_calls:
        out = TOOL_HANDLERS[call.name](**call.input)
        results.append({"type": "tool_result",
                        "tool_use_id": call.id,
                        "content": out})
    messages.append({"role": "user", "content": results})

모델이 도구를 호출할 시점을 결정하고, 하네스는 도구를 실행한 후 결과를 다시 피드백합니다. 이 리포지토리는 이 루프를 17단계의 점진적 수업으로 확장하여 각 수업마다 구체적인 하네스 기능을 추가합니다:

수업	추가된 기능	배우는 내용
s01	기본 에이전트 루프 + Bash 도구	최소한의 작동하는 에이전트
s02	도구 등록 및 디스패치	임의의 도구 추가
s03	권한 시스템	안전한 실행, 승인
s04	훅 시스템	확장 가능한 도구 전/후 로직
s05	Todo-Write (계획)	모델 주도의 작업 계획
s06	서브에이전트 격리	서브태스크용 별도의 메시지 컨텍스트
s07	스킬 로딩	필요 시 지식 주입
s08	컨텍스트 압축	토큰 창을 제한 내에 유지
s09	메모리 서브시스템	세션 간 지속적인 지식
s10	디스크 기반 작업 그래프	구조화되고 재시작 가능한 작업 목록
s11	백그라운드 작업	블로킹되지 않는 장시간 실행 명령
s12	크론 스케줄러	시간 기반 자동화
s13	에이전트 팀	다중 에이전트 협업, 작업 할당
s14	MCP 플러그인	외부 기능을 도구로 플러그인
s15	통합 하네스	이전 모든 메커니즘을 하나의 루프에 통합
s16	워크플로 런타임	저장 및 재시작 가능한 오케스트레이션 스크립트
s17	목표 루프	독립된 평가자가 에이전트가 종료해야 할 시점을 결정

각 수업은 작동 가능한 작은 code.py와 디자인 설명, 구현 방법, 흐름 시각화를 제공하는 README(영어, 중국어, 일본어)를 포함합니다.

누가 사용해야 할까요 –

• 하네스 엔지니어 : 이미 LLM API에 접근할 수 있으며, 에이전트를 구축하기 위한 프로덕션 수준의 패턴을 원하는 사람.
• 개발자 : Claude(또는 호환 가능한 LLM)를 파일 읽기/쓰기, 쉘 명령 실행, 웹 탐색, 사용자 정의 API 호출이 가능한 코딩 보조자로 만들고 싶은 사람.
• 연구자 : "모델 + 환경" 패러다임의 깔끔한 참조 구현을 찾는 사람.

이 리포지토리에서 얻을 수 있는 것

• 자신의 프로젝트에 복사할 수 있는 완전하고 모듈화된 코드베이스.
• 명확한 책임 분리: 도구, 권한, 훅, 메모리, 작업 스케줄링, 다중 에이전트 프로토콜은 모두 독립된 모듈.
• 에이전시는 모델에서 비롯되며, 기교적인 프롬프트 체이닝에 의존하지 않는 철학으로, 부서지기 쉬운 "루베 골드버그"식 에이전트 해킹을 피할 수 있습니다.

결론 – Learn Claude Code 는 새로운 LLM이 아니라, Claude를 참조 모델로 삼아 어떤 LLM 기반 에이전트의 차량(하네스)을 구축하는 실용적인 교육 과정입니다. 17개 수업을 마치면 완전한 자율 코딩 보조자를 구축하거나, 데이터 분석, 웹 자동화, 로봇 공학 등 다른 분야에 패턴을 적용할 수 있게 됩니다.

---

빠른 시작 체크리스트

1. Anthropic Claude API 키를 획득 (또는 도구 사용을 지원하는 다른 LLM에 클라이언트를 적응).
2. git clone https://github.com/shareAI-lab/learn-claude-code.git
3. 최소한의 종속성 설치 (일반적으로 anthropic과 표준 라이브러리만 필요).
4. python s01_agent_loop/code.py 를 실행하여 가장 간단한 루프를 실행해 보세요.
5. s02_… 에서 s17_… 폴더를 차례로 진행하며, 각각에서 다음 메커니즘을 추가하세요.

---

위의 모든 세부 정보는 리포지토리의 README에서 직접 가져온 것이며, 추가 기능은 추측되지 않았습니다.