Mini-Coding-Agent: AI 코딩 에이전트의 6가지 핵심 구성 요소를 설명하는 최소 구현체 (feat. Sebastian Raschka)

9bow · 4월 16, 2026, 9:30오후

Mini-Coding-Agent 프로젝트 소개

Claude Code, Cursor, Windsurf와 같은 AI 코딩 에이전트(coding agent)들이 어떻게 동작하는지 궁금했던 적이 있으신가요? 이 도구들은 단순히 LLM에게 코드를 물어보는 것을 넘어, 저장소 구조를 파악하고, 파일을 읽고 쓰며, 커맨드를 실행하고, 이전 작업 컨텍스트를 이어받는 복잡한 에이전트 루프(agent loop)를 구현합니다. Mini-Coding-Agent는 이러한 AI 코딩 에이전트의 핵심 구성 요소를 가능한 한 간결하고 읽기 쉬운 Python 코드로 구현한 교육용 프로젝트입니다.

이 프로젝트는 PyTorch 생태계의 ML 교육 자료 및 최근 여러 최신 LLM들의 구조를 시각화한 'LLM 아키텍처 갤러리' 프로젝트로 잘 알려진 Sebastian Raschka가 공개하였으며, 별도의 외부 Python 라이브러리 의존성 없이 표준 라이브러리만으로 동작하는 것이 특징입니다.

Mini-Coding-Agent 프로젝트의 의의는 "어떻게 만드는가"보다 "왜 이렇게 설계되었는가"를 이해하는 데 있습니다. 프로덕션 수준의 견고함보다 가독성(readability)을 우선시하여, AI 에이전트를 처음 접하는 개발자도 코드를 읽으면서 각 컴포넌트의 역할과 상호작용을 직관적으로 이해할 수 있습니다. Ollama를 모델 백엔드로 활용하기 때문에 OpenAI API 키 없이도 로컬에서 완전히 실행 가능하며, 기본 모델로는 qwen3.5:4b를 사용합니다. 현재 GitHub 저장소는 474개의 스타와 92개의 포크를 기록 중입니다.

Mini-Coding-Agent의 6가지 핵심 구성 요소

Mini-Coding-Agent의 가장 큰 교육적 가치는 AI 코딩 에이전트를 구성하는 6가지 핵심 아키텍처 패턴을 명확하게 분리하여 구현한 점입니다. Sebastian Raschka는 자신의 블로그에서 이 6가지 요소가 실제 코딩 에이전트들이 공통으로 채택하는 설계 원칙임을 설명합니다:

1. 라이브 저장소 컨텍스트(Live Repo Context): 에이전트 시작 시 작업 공간의 전체 레이아웃, git 상태, 설정 파일 등을 미리 수집하여 모델에게 현재 프로젝트의 사실(fact)을 제공합니다. 사람이 새 프로젝트를 받으면 먼저 폴더 구조를 파악하듯, 에이전트도 작업 전에 환경을 스캔합니다.

2. 프롬프트 형태와 캐시 재사용(Prompt Shape and Cache Reuse): 안정적인 시스템 프롬프트 프리픽스와 변화하는 요청/대화록 부분을 분리합니다. 이를 통해 LLM의 KV 캐시를 효율적으로 재사용하여 추론 비용과 시간을 절감할 수 있습니다.

3. 입력 검증이 있는 구조화된 도구(Structured Tools with Validation): 자유 형식의 액션 대신, 이름이 지정된 도구(named tool)에 대한 스키마 검증과 권한 게이트(approval gate)를 구현합니다. 모델은 <tool>읽기_파일(경로)</tool> 형식으로 도구를 호출하고, 에이전트는 이를 파싱하여 실행합니다.

4. 컨텍스트 축소(Context Reduction): 긴 도구 출력을 잘라내고, 반복적인 파일 읽기를 중복 제거하며, 오래된 대화록 항목을 압축합니다. 컨텍스트 창(context window)이 아무리 커도 불필요한 정보로 채워지면 에이전트 성능이 저하되기 때문에, 관련성 높은 정보를 유지하는 것이 중요합니다.

5. 대화록과 메모리 지속성(Transcripts and Memory Persistence): 전체 대화 이력을 담은 영구 대화록과 세션 재개를 위한 압축 작업 메모리를 함께 유지합니다. 세션이 종료되어도 --resume latest 옵션으로 이전 작업 맥락을 그대로 이어받을 수 있습니다.

6. 경계가 있는 위임(Bounded Delegation): 스코프가 제한된 서브태스크를 헬퍼 에이전트에게 위임합니다. 이때 부모 에이전트의 컨텍스트 제한이 상속되어, 헬퍼 에이전트가 과도한 자원을 사용하지 않도록 제어합니다.

Mini-Coding-Agent 설치 및 사용법

Python 3.10 이상과 Ollama 설치가 필요하며, 외부 Python 의존성이 없어 설치가 간단합니다:

# 저장소 클론
git clone https://github.com/rasbt/mini-coding-agent.git
cd mini-coding-agent

# Ollama 서버 시작 (별도 터미널)
ollama serve

# 기본 모델 다운로드
ollama pull qwen3.5:4b

# 에이전트 실행
uv run mini-coding-agent
# 또는: python mini_coding_agent.py

승인 모드(Approval Mode)

파일 삭제나 셸 명령 실행 같은 위험한 작업에 대한 권한 제어를 지원합니다:

# 기본값: 위험한 작업 전 확인 요청
uv run mini-coding-agent --approval ask

# 자동 승인 (신뢰할 수 있는 저장소에서만 사용)
uv run mini-coding-agent --approval auto

# 위험한 작업 자동 거부
uv run mini-coding-agent --approval never

세션 관리

# 최근 세션 재개
uv run mini-coding-agent --resume latest

# 특정 세션 재개
uv run mini-coding-agent --resume 20260401-144025-2dd0aa

주요 CLI 옵션

옵션	설명	기본값
`--cwd`	작업 디렉터리	`.`
`--model`	Ollama 모델 이름	`qwen3.5:4b`
`--max-steps`	턴당 모델/도구 실행 제한	`6`
`--max-new-tokens`	출력 길이 제한	`512`
`--temperature`	샘플링 무작위성	`0.2`

REPL 내에서는 /help, /memory, /session, /reset, /exit 등의 슬래시 명령어를 사용할 수 있습니다.

도구 호출 형식

에이전트는 모델 출력에서 다음 형식의 태그를 파싱하여 도구를 실행합니다:

<!-- 도구 호출 -->
<tool>read_file(path="src/main.py")</tool>

<!-- 최종 응답 -->
<final>작업이 완료되었습니다. main.py의 버그를 수정했습니다.</final>

지시 따르기(instruction-following) 능력이 좋은 모델일수록 이 형식을 더 일관되게 준수합니다.

라이선스

Mini-Coding-Agent 프로젝트는 Apache 2.0 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용하고 수정할 수 있습니다.

Mini-Coding-Agent에 대한 상세한 소개 블로그

mini-coding-agent 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~