128줄의 Python.

이것이 Claude Code나 Cursor와 같은 도구들을 구동하는 루프(loop), 즉 코딩 에이전트의 핵심 전체입니다. 저도 믿기지 않았기에, 직접 처음부터 하나를 만들어 보았습니다. 그런 다음 실패하는 테스트를 대상으로 지정했더니, 에이전트가 파일을 읽고, 테스트를 실행하고, 트레이스백(traceback)을 확인하고, 코드를 수정하고, 다시 실행했습니다. 모든 단계를 스스로 선택하면서 말이죠. 그 누구도 이를 하드코딩(hard-coded)하지 않았습니다.

이 프로젝트는 오픈 소스(MIT)이며, 여러분이 따라갈 수 있는 단계별 로드맵이 있습니다:

👉 github.com/osama96gh/coding-agent-from-scratch

기존 것을 읽는 대신 왜 직접 만드는가

저는 매일 코딩 에이전트를 사용합니다. AI 엔지니어로서, 저는 이것이 현재 LLM(대규모 언어 모델)의 폭발적인 활용 사례라고 생각합니다. 하지만 무언가를 사용하는 것과 그것을 이해하는 것은 별개의 문제입니다.

핵심을 배우기 위해 상용 에이전트의 소스 코드를 읽는 것은 함정입니다. 필수적인 로직이 프롬프트 캐싱(prompt caching), 재시도(retries), 텔레메트리(telemetry), 그리고 정교한 스캐폴딩(scaffolding) 아래에 묻혀 있기 때문입니다. 외장 부품 때문에 엔진을 볼 수 없는 것과 같습니다.

그래서 저는 오직 엔진만을 만들었습니다. 최적화는 없습니다. 오직 본질뿐입니다.

"어라, 이렇게 작다고?" 하는 숫자들

이 수치들은 제가 다시 확인해 볼 정도로 놀라웠습니다:

구성 요소	크기
전체 REPL + 에이전트 루프(agent loop) + 권한 게이트 (main.py)	128줄
...

마치 마법처럼 느껴지는 것들 — 에이전트가 자율적으로 파일을 읽고, 테스트를 실행하고, 실패를 수정하고, 다시 실행하는 것 — 은 약 100줄 정도의 오케스트레이션(orchestration)에서 나옵니다. 지능은 모델에 존재합니다. 여러분의 역할은 배관(plumbing) 작업입니다.

전체적인 트릭: 에이전트 루프 (agent loop)

스트리밍(streaming), 권한 게이트, 그리고 UI를 모두 걷어내면, 이 모든 것의 심장 박동은 다음과 같습니다:

conversation.append({"role": "user", "content": user_input})

while True:  # 모델이 도구(tools) 사용을 요청하는 것을 멈출 때까지 계속 진행
...

그게 전부입니다. 그것이 바로 에이전트입니다.

1. 평이한 영어로 요청을 입력합니다.
2. 대화 내용 + 도구(tools) 목록을 LLM에 보냅니다.
3. 모델은 텍스트 (사용자에게 말하기) 또는 도구 호출 (tool call) ("main.py 읽기", "pytest 실행") 중 하나로 응답합니다.
4. 도구 호출인 경우: 이를 실행하고, 결과를 대화에 추가한 뒤, 2단계로 다시 루프(loop)를 돌립니다.
5. 텍스트인 경우: 이를 보여주고, 사용자의 다음 차례를 기다립니다.

모델은 어떤 도구를 어떤 순서로 사용할지 결정하며, 루프는 모델이 요청을 멈출 때까지 계속 돌아갑니다.

에이전트는 그저 LLM, 루프, 그리고 몇 가지 도구일 뿐입니다. 이 저장소(repo)의 다른 모든 것들은 이 세 가지를 기반으로 한 개선 사항들입니다.

이것이 바로

• 시스템 프롬프트 (System prompt, 19줄). 아주 작지만, 이것이 조향 장치 역할을 합니다: "당신은 코딩 에이전트입니다. 추측하기보다 도구를 사용하는 것을 선호하며, 단계별로 작업하세요."
• 권한 게이트 (Permission gate). 위험한 작업(쓰기, 셸 명령)을 수행하기 전에 에이전트가 요청을 보냅니다. 이때 결정 과정은 단순히 도구 이름만 보는 것이 아니라 _인자 (arguments)_를 읽습니다. 따라서 git status는 묻지 않고 실행되지만, git push는 여전히 멈춰서 확인을 요청합니다. 이것이 어시스턴트와 rm -rf 룰렛의 차이입니다.
• 컨텍스트 관리 (Context management). LLM은 상태가 없습니다 (stateless). 매 턴마다 전체 대화 내용을 다시 전송해야 하며, 이는 비용이 빠르게 증가하는 원인이 됩니다. 해결책은 다음과 같습니다: 제공업체의 캐시된 접두사 (cached prefix)에 의존하고, 오래된 대화 내용은 직접 요약하는 것입니다.
• 플러그형 제공자 (Pluggable providers). 얇은 인터페이스 (thin interface)를 통해 OpenAI와 Gemini를 서로 교체할 수 있으며 (환경 변수 하나로 전환 가능), 제공자별 특화된 기능이 전체 로직에 섞이지 않도록 유지합니다.
• 스트리밍 + 사용량 보고 (Streaming + usage reporting). 토큰이 생성되는 것을 실시간으로 확인하고, 각 턴의 비용이 얼마인지 파악할 수 있습니다.

나를 놀라게 한 부분: 정말로 "진짜"처럼 느껴집니다

맨 위에서 보여준 테스트 실패 실행 사례요? 저는 그것을 스크립트로 짜지 않았습니다. 모델이 스스로 읽고, 실행하고, 진단하고, 수정하고, 다시 실행하기로 결정했습니다. 제가 매일 Claude Code에 비용을 지불하며 경험하는 것과 동일한 형태의 동작을, 단 한 번에 읽을 수 있는 약 128줄의 코드 안에서 구현해낸 것입니다.

"장난감"과 "실제" 사이의 간극은 과장된 홍보만큼 크지 않습니다. 캐싱, 재시도 (retries), 샌드박싱 (sandboxing), 수천 개의 예외 처리와 같은 프로덕션 수준의 다듬기 작업은 분명히 어렵고 정교한 엔지니어링의 영역입니다. 하지만 에이전트를 에이전트답게 만드는 _핵심 (core)_은 어떤 엔지니어라도 오후 한때면 충분히 도달할 수 있는 범위 안에 있습니다.

한 단계씩 직접 만들어 보세요

이 저장소(repo)는 **단계별 로드맵 (phased roadmap)**입니다. 각 단계는 독립적으로 실행되며 하나의 개념을 가르쳐주므로, 항상 작동하는 에이전트를 보유할 수 있습니다:

1. 기본 채팅 루프 (도구 없음)
2. 도구 인프라 + read_file
3. 읽기 전용 탐색 (list_files, grep)
4. 쓰기 도구 (edit_file, write_file)
5. 셸 도구 (run_bash) — 여기서부터 강력해지며 (동시에 위험해집니다)
6. 시스템 프롬프트 + UX 다듬기
7. 안전 및 권한
8. 긴 세션을 위한 컨텍스트 관리

osama96gh / coding-agent-from-scratch

에이전트 루프 (agent loops), 도구 호출 (tool calling), 코드 편집 (code editing), bash 실행 (bash execution), 권한 (permissions), 컨텍스트 관리 (context management), 그리고 OpenAI/Gemini 프로바이더 (providers)를 설명하기 위해 처음부터 구축한 교육용 Python 코딩 에이전트.

처음부터 코딩 에이전트 구축하기

학습용 프로젝트: 복잡한 AI 에이전트가 실제로 내부적으로 어떻게 구조화되어 있는지 이해하기 위해, 아무것도 없는 상태에서 단계별로 단순하지만 실제적인 코딩 에이전트 (작은 Claude Code / Cursor / Codex라고 생각하세요)를 구축합니다.

한 문장으로 요약된 멘탈 모델 (mental model): 에이전트는 단지 LLM, 루프 (loop), 그리고 몇 가지 도구 (tools)일 뿐입니다. 그 외의 모든 것은 정교화 과정입니다. (출처)

프로젝트 설명

이 저장소는 터미널 코딩 에이전트를 처음부터 구현한 교육용 Python 구현체입니다. 현대적인 AI 코딩 도구의 핵심 메커니즘을 보여줍니다: 모델 주도형 에이전트 루프 (model-driven agent loop), 도구 호출 (tool calling), 파일 탐색 (file exploration), 타겟팅된 코드 편집 (targeted code edits), 셸 명령 실행 (shell command execution), 권한 확인 (permission checks), 스트리밍 응답 (streaming responses), 사용량 보고 (usage reporting), 컨텍스트 압축 (context compaction), 그리고 플러그 가능한 OpenAI/Gemini 프로바이더 (pluggable OpenAI/Gemini providers).

이 프로젝트는 읽고, 수정하고, 배우기 위한 목적으로 만들어졌습니다. 이것은 프로덕션용 코딩 에이전트가 아니라, 프로덕션 코딩 에이전트가 내부적으로 어떻게 구조화되어 있는지 이해하기 위한 작은 참조 구현체 (reference implementation)입니다.

무엇인가

…

GitHub에서 보기

직접 구축하고, 망가뜨려 보고, 확장해 보세요 (새로운 도구, 웹 UI, 제3의 프로바이더 추가) — 그리고 결과가 어떤지 알려주세요. AI 도구가 마법처럼 느껴지는 것을 멈추는 가장 빠른 방법은 작은 것을 직접 만들어 보는 것입니다.