▲

Claude Code를 200줄의 코드로 구현하는 방법

 (mihaileric.com)
4P by GN⁺ 1일전 | ★ favorite | 댓글 1개
  • AI 코딩 어시스턴트의 핵심 구조는 복잡한 마법이 아니라 약 200줄의 단순한 Python 코드로 구성됨
  • 시스템은 LLM과의 대화 루프를 기반으로 하며, LLM이 도구 호출을 요청하면 로컬 코드가 이를 실행하고 결과를 다시 전달함
  • 필요한 기본 도구는 파일 읽기(read) , 파일 목록(list) , 파일 편집(edit) 의 세 가지로, 이를 통해 프로젝트 탐색과 코드 수정이 가능함
  • LLM은 도구의 시그니처와 설명(docstring) 을 기반으로 어떤 도구를 언제 호출할지 스스로 결정함
  • 이 구조는 Claude Code 같은 상용 제품의 핵심과 동일하며, 단순한 구조로도 강력한 코딩 에이전트 구현이 가능함

코딩 에이전트의 기본 개념

  • 코딩 에이전트는 LLM과의 대화 기반 시스템으로, 사용자의 명령을 받아 도구 호출을 통해 실제 파일 작업을 수행
    • 사용자는 “hello world 함수를 포함한 새 파일 생성”과 같은 요청을 입력
    • LLM은 필요한 도구 호출을 JSON 형식으로 응답
    • 프로그램이 해당 도구를 실행하고 결과를 다시 LLM에 전달
  • LLM은 파일 시스템에 직접 접근하지 않고, 요청만 수행하며 실제 작업은 로컬 코드가 처리

필요한 세 가지 도구

  • read_file: 지정된 파일의 전체 내용을 읽어 반환
  • list_files: 디렉터리 내 파일과 폴더 목록을 반환
  • edit_file: 기존 문자열을 새 문자열로 교체하거나, old_str이 비어 있으면 새 파일을 생성
    • 교체할 문자열이 없을 경우 “old_str not found”를 반환
  • 이 세 가지 도구만으로도 파일 생성, 수정, 탐색이 가능

도구 등록 및 LLM 통합

  • 모든 도구는 TOOL_REGISTRY에 이름과 함수로 등록되어 LLM이 호출 가능
  • 각 도구의 docstring과 시그니처를 추출해 LLM에게 전달
  • 시스템 프롬프트는 LLM에게 “사용 가능한 도구 목록”과 “호출 형식”을 명확히 알려줌
    • 도구 호출은 'tool: TOOL_NAME({JSON_ARGS})' 형식으로 제한
    • 도구 실행 결과는 tool_result(...) 형태로 LLM에 전달

도구 호출 파싱 및 LLM 응답 처리

  • LLM의 응답에서 tool:로 시작하는 줄을 찾아 도구 이름과 인자(JSON) 를 추출
  • 각 도구를 실행한 후 결과를 JSON으로 직렬화해 대화 기록에 추가
  • execute_llm_call 함수는 LLM API를 호출하고 응답 텍스트를 반환
  • run_coding_agent_loop는 사용자 입력을 받아 LLM과의 대화 루프를 유지
    • 내부 루프는 LLM이 더 이상 도구 호출을 요청하지 않을 때까지 반복

실행 예시와 확장 가능성

  • 예시 대화:
    • “hello.py 파일을 만들고 hello world를 구현해줘” → edit_file 호출로 새 파일 생성
    • “hello.py에 두 수를 곱하는 함수 추가” → read_file 후 edit_file 호출
  • 약 200줄의 코드로 완전한 코딩 어시스턴트 구현 가능
  • 상용 제품은 여기에 에러 처리, 스트리밍 응답, 컨텍스트 관리, 추가 도구, 승인 절차 등을 더함
  • 핵심 구조는 동일하며, LLM이 결정하고 코드가 실행하는 단순한 루프로 구성됨

실습 및 확장

  • 전체 소스는 약 200줄이며, 다른 LLM 제공자 교체나 도구 추가로 확장 가능
  • 간단한 구조로도 강력한 AI 코딩 에이전트 프로토타입을 직접 구현 가능
▲
GN⁺ 1일전  [-]
Hacker News 의견들

  • 내가 추가하고 싶은 건 planning임
    효과적인 도구 사용의 핵심은 이들이 동적 TODO 리스트 위에서 작동한다는 걸 깨닫는 순간임
    Plan 모드는 그 리스트가 어떻게 시드되고, 각 항목이 언제 실행되는지를 부트스트랩하는 역할을 함
    사용자 상호작용은 그 리스트를 재정렬하는 방식으로 작동함
    지난달에 Claude Code가 CTF 문제를 얼마나 잘 푸는지 실험했는데, TodoList 도구와 planning을 끄면 성능이 1~2단계 떨어졌음
    관련 영상은 Breaking Bots: Cheating at Blue Team CTFs with AI Speed Runs 참고
    흥미로운 건, 많은 사람들이 “plan 모드를 쓸까 말까”에만 집중하지만 TODO 리스트는 항상 활성 상태라는 점임
    또, “스마트한 컨텍스트 관리”를 단순 TODO 항목으로 치부하는 글들을 보면 웃기기도 함
    직접 구현하려다 생산 환경에서 망가지는 평가 결과 때문에 1년을 날리는 경우도 많음

    • Claude Code의 시스템 프롬프트를 추출한 gist를 보면 TODO 반복(iteration)에 대한 세부 내용이 많음
      이걸 단순히 reasoning 토큰으로 추가할 수도 있지만, 실제로는 명시적 단일 키 저장 도구로 구현하는 게 훨씬 예측 가능하고 효과적임
      언어 구조를 저장하는 다른 툴 아이디어에도 이런 단순한 접근이 통할 수 있을 것 같음
    • CLI 에이전트용으로 “working memory” 파일을 유지하는 방식이 매우 잘 작동했음
      Codex를 테스트하면서 명세를 10분 정도 정리해 변경 리스트로 나누고, 그걸 파일로 저장하게 한 뒤 매 변경 후 계획을 검토·수정하도록 지시함
      이렇게 하면 LLM이 짧은 목표 중심 작업에 집중하면서도 지속적인 프롬프트 입력이 필요 없어짐
      사실상 서브에이전트를 두는 것과 비슷한 효과를 냄
    • 나도 프롬프트 끝에 “이 작업을 위해 매우 세분화된 todo 리스트를 사용하라”고 자주 추가함
      마지막 todo로 “전체 작업을 다시 검토하고 linter 등으로 품질을 확인하라”고 지시하기도 함
    • TODO 리스트는 종종 컨텍스트의 HEAD에 재삽입되어 LLM이 과거와 다음 단계를 인식하도록 함
      컨텍스트 압축 시에는 세션의 간결한 표현으로도 쓰임
    • 연말쯤 되면 “How to Code Claude Code in 200 Million Lines of Code” 같은 농담이 나올지도 모름

  • 코딩 에이전트의 핵심은 사실 단순한 루프와 도구 호출 구조임
    하지만 “The Emperor Has No Clothes: How to Code Claude Code in 200 Lines of Code” 같은 글을 쓸 거라면 Thorsten Ball의 How to Build an Agent를 꼭 참고해야 함
    그 글이 “에이전트의 본질은 단순하다”는 아이디어를 처음 제시했음
    물론 실제로는 TODO나 다양한 스캐폴딩이 필요하고, Claude Code 자체도 복잡한 설정과 플러그인, UI 기능이 많음
    그래도 최소 루프만 있으면 스스로 기능을 확장하도록 부트스트랩할 수도 있음
    내부 동작을 보고 싶다면 claude-trace로 LLM과 도구 호출 간의 상호작용을 추적할 수 있음

    • 나는 Claude Code와 Codex의 로컬 트랜스크립트를 분석하면서 내부 구조를 살펴봤음
      단순한 루프 외에도 uuid 스레딩, 메시지 큐 처리, 파일 변경 스냅샷, 서브에이전트 사이드체인 등 복잡한 요소가 많음
      그래서 “200줄”은 개념적으로는 맞지만 실제 프로덕션 수준은 훨씬 복잡함
      Codex는 아직 큐잉 기능이 없지만 여전히 강력함
      나는 Contextify라는 macOS 앱을 만들어 Claude Code와 Codex의 CLI 트랜스크립트를 실시간으로 모니터링하고, Total Recall 기능으로 대화 이력을 질의할 수 있게 함
    • 코드 편집이 가장 중요한 부분임
      Claude 모델은 자체 str replace 도구 스키마로 훈련되어 있음
      전체 파일을 다시 쓰는 건 비효율적이므로 부분 수정이 핵심임
    • “같은 글이 재게시된 줄 알았다”는 반응도 있었음
    • “그 단순한 코어 루프를 직접 보여줄 수 있냐”는 요청도 있었음

  • 실제로는 더 많은 요소가 있음
    예를 들어 에이전트가 early stopping을 일으켜 작업을 끝내버리는 경우가 있음
    최신 reasoning 모델로도 해결되지 않음
    Claude Code는 TODO를 매 프롬프트에 주입해 남은 작업을 상기시키는 방식으로 해결함
    HolmesGPT의 공개 저장소에 다양한 실험 벤치마크가 있음

    • “왜 early stop이 발생하냐”는 질문이 나왔음

  • “LLM에게 도구 목록과 호출 형식만 알려주면 된다”는 개념이 처음엔 충격이었음
    LLM이 단순히 텍스트를 생성하는데 어떻게 도구를 호출하나 싶었지만, 그게 전부라는 걸 깨달았을 때 마법 같았음

  • 휴일 동안 Opus로 Prolog DSL 기반 코딩 에이전트를 만들어봤는데 (200줄은 넘었음)
    놀랍게도 거의 바로 잘 작동했음
    최신 세대 모델은 에이전트 하네스의 중요성이 줄어든 단계에 도달한 듯함
    관련 실험은 이 글 참고

  • 1년 전엔 이 글이 꽤 정확했지만, 지금은 하네스가 훨씬 발전해서 단순 루프 모델로는 Claude Code의 실제 동작을 설명하기 어렵음

    • 물론 현대 하네스가 더 많은 기능을 갖췄지만, 기본 개념은 여전히 유효함
      단순한 에이전트도 같은 모델을 쓰면 성능 차이가 크지 않음
      마치 “직접 DB 만들기” 튜토리얼이 기본 B-tree를 보여주는 것과 비슷함
    • tbench.ai 리더보드에 따르면 복잡성이 성능을 약간 높이긴 하지만, “Terminus”처럼 단순 루프 기반도 충분히 강력함
    • “이 글은 2025년 1월에 게시된 것”이라는 언급도 있었음
    • 실제로는 최근 1년간의 발전이 프롬프트와 도구 설계의 단순화에 집중되어 있음
      Subagent나 MCP, Skills는 중간 수준이고, 컨텍스트 최적화는 장기 실행에만 유의미함
    • codex-cli 저장소를 활용하면 더 나은 모델 분석이 가능함

  • 나는 기업용 에이전트 루프를 직접 구축해 월 10억 토큰 이상을 처리하고 있음
    단순 루프가 핵심이긴 하지만, 실제 환경에서는 수많은 세부 요소가 복잡성을 폭발적으로 키움
    예를 들어 사용자가 도중에 메시지를 보내면 루프를 어떻게 처리할지, Slack 같은 웹훅 입력을 어떻게 동기화할지,
    승인·가드레일·비동기 Task 처리 등 고려할 게 많음
    이런 경험을 블로그로 정리해볼까 생각 중임

  • 참고할 만한 글로 You Should Write An Agent와 How To Build An Agent가 있음

  • 우리 SWE-bench 팀은 100줄짜리 오픈소스 에이전트를 공개했음
    mini-swe-agent인데, 학계와 업계 모두에서 인기가 많음
    에이전트 세계를 배우기에 좋은 출발점임

  • 2023년에 “LangChain을 100줄로 재구현하기”라는 글이 있었는데
    그 글을 보고 실제로 구현해 여러 프로젝트에 활용했음

    • “벌써 3년 전이라니”라는 반응이 나왔음
답변달기