mini-coding-agent는 Sebastian Raschka가 코딩 에이전트(coding agent)의 핵심 구성 요소를 명확하게 설명하기 위해 작성한 최소 구현체다. GitHub: rasbt/mini-coding-agent. Ollama 백엔드 기반으로 로컬에서 동작하며, 실제 프로덕션 에이전트를 이해하려는 개발자를 위한 학습 자료로 설계됐다.
등장 배경
Claude Code, Cursor, Codex 같은 AI 코딩 에이전트가 빠르게 보급되면서 “내부에서 무슨 일이 일어나는가”에 대한 관심이 높아졌다. mini-coding-agent는 에이전트 루프의 핵심 메커니즘을 표준 라이브러리만으로 간결하게 구현해, 복잡한 프레임워크 없이 에이전트 작동 원리를 파악할 수 있도록 한다.
6가지 핵심 구성 요소
| # | 컴포넌트 | 설명 |
|---|---|---|
| 1 | 라이브 레포 컨텍스트 | 에이전트 시작 시 레포 레이아웃, 지시사항, git 상태 등을 수집 |
| 2 | 프롬프트 구조 및 캐시 재사용 | 정적 prefix와 변경되는 요청·트랜스크립트·메모리를 분리해 반복 호출 효율화 |
| 3 | 구조화된 도구, 검증, 권한 | 이름이 있는 도구(named tools)로 작동, 입력 검증 및 위험 작업 승인 게이트 |
| 4 | 컨텍스트 축소 및 출력 관리 | 긴 출력 클리핑, 중복 읽기 제거, 오래된 트랜스크립트 압축 |
| 5 | 트랜스크립트, 메모리, 재시작 | 전체 내구성 트랜스크립트 + 워킹 메모리로 세션 재개 지원 |
| 6 | 위임 및 제한된 서브에이전트 | 스코프가 정해진 서브태스크를 헬퍼 에이전트에 위임 |
설치 및 사용법
# 의존성: Python 3.10+, Ollama, (선택) uv
git clone https://github.com/rasbt/mini-coding-agent.git
cd mini-coding-agent
# Ollama 서버 시작 및 모델 다운로드
ollama serve
ollama pull qwen3.5:4b # 기본 모델
# uv로 실행
uv run mini-coding-agent
# 또는 직접 실행
python mini_coding_agent.py승인 모드(approval modes)
| 모드 | 동작 |
|---|---|
--approval ask | 위험 작업 전 사용자 승인 요청 (기본값, 권장) |
--approval auto | 위험 작업 자동 허용 (신뢰하는 환경에서만) |
--approval never | 위험 작업 항상 거부 |
누가 쓰면 좋은가
- 에이전트 개발자: 프로덕션 에이전트 설계 전 기본 패턴 이해
- AI/ML 연구자: 에이전트 루프 메커니즘을 최소 코드로 학습
- 교육 목적: 커스텀 코딩 에이전트 harness 구현 실습
라이선스 및 관련 문서
- GitHub: rasbt/mini-coding-agent
- 상세 튜토리얼: Components of a Coding Agent
- 관련 토픽: claude-agent-sdk, agent-skills, gstack, pi-autoresearch