Mini-Coding-Agent: 코딩 에이전트의 핵심만 남긴, 가장 읽기 쉬운 로컬 에이전트 구현

AI 코딩 에이전트가 넘쳐나는 시대다. 그런데 막상 “에이전트가 내부적으로 어떻게 돌아가는가?”를 이해하려고 코드를 열어보면, 프레임워크 계층과 추상화가 너무 두꺼워 금방 길을 잃는다. mini-coding-agent는 그 반대편에 서 있다. 기능을 과시하기보다, 코딩 에이전트의 뼈대를 눈으로 따라갈 수 있게 만든다. 저장소 설명 그대로 이 프로젝트는 “코딩 에이전트의 핵심 구성요소를 설명하기 위한 최소한의 읽기 쉬운 구현”을 목표로 한다. (GitHub)

무엇보다 흥미로운 지점은 이 프로젝트가 “새로운 에이전트 프레임워크”를 내세우지 않는다는 점이다. 대신 로컬 모델 서버인 Ollama를 백엔드로 붙이고, 단일 Python 파일 중심으로 에이전트 루프를 구현해 둔다. 설치 요구사항도 Python 3.10+, Ollama, 그리고 로컬에 내려받은 모델 정도로 단순하다. 런타임 의존성은 사실상 표준 라이브러리 중심이고, CLI 엔트리포인트도 제공한다. (GitHub)

 

GitHub - rasbt/mini-coding-agent: Minimal and readable coding agent harness implementation in Python to explain the core compone

 

프로젝트 소개

mini-coding-agent는 Sebastian Raschka가 만든 로컬 코딩 에이전트 학습용 프로젝트다. 저장소에는 핵심 구현 파일 mini_coding_agent.py, CLI 엔트리포인트 mini-coding-agent, 사용 예시 문서 EXAMPLE.md, 그리고 테스트 디렉터리가 함께 들어 있다. 이 프로젝트는 거대한 멀티에이전트 시스템이 아니라, “코드 저장소를 읽고, 모델에게 도구 사용을 시키고, 세션을 저장하고, 필요하면 제한된 하위 에이전트에게 조사 작업을 넘기는” 최소 루프를 보여준다. (GitHub)

이 프로젝트가 해결하려는 문제는 분명하다. 오늘날 많은 AI 코딩 도구는 사용하기는 쉽지만 내부 구조를 이해하기는 어렵다. 반대로 이 저장소는 코딩 에이전트를 구성하는 실전적 부품을 여섯 가지 블록으로 나눠 드러낸다. 저장소 README와 Raschka의 설명 글은 그 여섯 블록을 다음처럼 정리한다. 실시간 저장소 컨텍스트, 프롬프트 구조와 재사용, 구조화된 도구와 권한, 컨텍스트 축소, 세션 메모리, 제한된 위임이다. (GitHub)

왜 이 프로젝트가 등장했을까

코딩 에이전트는 겉으로 보기에는 단순하다. “모델에게 코드 고치라고 시키면 되는 것 아닌가?”라는 생각이 든다. 하지만 실제로는 그렇지 않다. 모델이 현재 어떤 저장소를 보고 있는지, 어떤 파일을 읽었는지, 어떤 수정이 이미 일어났는지, 어떤 행동은 허용되고 어떤 행동은 승인받아야 하는지까지 관리해야 한다. 이 저장소는 그런 문제를 감추지 않고, 오히려 가장 노출된 형태로 보여준다. README는 이 구현이 워크스페이스 스냅샷 수집, 안정적인 프롬프트 구성, 구조화된 도구, 위험한 도구에 대한 승인 처리, 대화 기록과 메모리 저장, 그리고 제한된 delegation을 포함한다고 설명한다. (GitHub)

즉, 이 프로젝트는 “성능 좋은 에이전트 제품”보다 “코딩 에이전트 설계 교과서”에 더 가깝다. LangChain, LangGraph, OpenAI SDK, 여러 툴 서버를 얹은 복잡한 시스템을 먼저 배우기 전에, 에이전트가 왜 상태 관리와 도구 제어를 필요로 하는지 이해하게 해주는 중간 단계라고 보는 편이 정확하다. (Sebastian Raschka's Magazine)

핵심 기능

1. 저장소를 먼저 이해하는 워크스페이스 컨텍스트

에이전트는 질문을 받자마자 무작정 추론하지 않는다. WorkspaceContext.build()는 현재 작업 디렉터리 기준으로 Git 루트, 브랜치, 기본 브랜치, Git 상태, 최근 커밋, 그리고 AGENTS.md, README.md, pyproject.toml, package.json 같은 프로젝트 문서를 모아 컨텍스트를 만든다. 즉, 모델이 바로 코드를 “생각”하기 전에 저장소의 사실 관계를 먼저 확보한다. (GitHub)

이 설계는 실전에서도 중요하다. 좋은 코딩 에이전트는 똑똑한 모델보다 먼저 “내가 어디서 일하고 있는가”를 알아야 한다. 브랜치가 무엇인지, README가 무엇을 말하는지, 패키지 메타데이터가 무엇인지 모른 채 파일만 읽게 하면 수정 품질이 급격히 떨어진다.

2. 프롬프트를 고정 영역과 가변 영역으로 분리

이 프로젝트에서 인상적인 부분 중 하나는 프롬프트 구성이다. build_prefix()는 도구 목록, 응답 규칙, 출력 형식 예시, 워크스페이스 정보 같은 비교적 안정적인 내용을 미리 조립한다. 이후 prompt()는 여기에 세션 메모리, 압축된 대화 이력, 현재 사용자 요청만 덧붙인다. Raschka는 이를 프롬프트 모양과 캐시 재사용의 관점에서 설명한다. (GitHub)

이 접근은 아주 실용적이다. 에이전트는 한 번의 답변으로 끝나지 않고 여러 차례 모델 호출을 반복한다. 매번 프롬프트 전체를 뒤섞기보다, 변하지 않는 부분과 변하는 부분을 나누면 추론 안정성과 비용 관리 양쪽에 도움이 된다.

3. 자유 형식 행동이 아니라 구조화된 도구 호출

build_tools()를 보면 이 에이전트가 지원하는 기본 도구는 list_files, read_file, search, run_shell, write_file, patch_file이고, 조건에 따라 delegate가 추가된다. 각 도구는 스키마, 위험 여부, 설명, 실행 함수가 함께 정의된다. (GitHub)

특히 중요한 건 모델이 마음대로 행동하지 못하게 만든다는 점이다. 시스템 프롬프트는 모델에게 정확히 하나의 <tool>...</tool> 또는 <final>...</final>만 반환하라고 요구한다. JSON 형식 도구 호출과 XML 스타일 파일 쓰기 형식도 예시로 강제한다. 파싱이 실패하면 재시도 메시지를 돌려보내고, 입력 검증에 실패하면 에러를 반환한다. (GitHub)

이건 에이전트 설계에서 굉장히 중요한 철학이다. 모델은 “행동을 상상”하는 존재가 아니라 “제한된 인터페이스를 통해 행동하는 존재”가 되어야 한다. 이 저장소는 그 원칙을 아주 노골적으로 보여준다.

4. 위험한 행동에는 승인 게이트를 둔다

run_shell, write_file, patch_file 같은 도구는 risky로 표시된다. 승인 정책은 ask, auto, never 세 가지이며, 기본값은 ask다. README와 CLI 설명은 auto가 임의 명령 실행과 파일 쓰기를 자동 허용하므로 신뢰된 프롬프트와 저장소에서만 써야 한다고 분명히 적어 둔다. 실제 구현에서도 approve()가 정책에 따라 승인 여부를 결정한다. (GitHub)

이 한 가지 설계만으로도 이 저장소가 단순 데모를 넘어선다는 걸 알 수 있다. 실제 코딩 에이전트에서 가장 위험한 부분은 “모델이 셸을 실행할 수 있는가”와 “파일을 수정할 수 있는가”다. 이 프로젝트는 최소 구현이지만, 최소한의 안전장치는 절대 빼지 않는다.

5. 세션 기록과 작은 working memory를 분리

SessionStore는 세션을 JSON 파일로 저장하고, 최신 세션을 불러오거나 특정 세션을 resume할 수 있게 한다. 세션은 .mini-coding-agent/sessions/ 아래에 저장된다. record()는 대화와 도구 실행 결과를 저장하고, note_tool()은 최근 읽거나 수정한 파일과 간단한 노트를 별도 메모리로 축약한다. README도 transcript와 working memory를 함께 유지해 세션 재개 시 중요한 상태를 보존한다고 설명한다. (GitHub)

이 구조가 좋은 이유는 명확하다. 전체 기록은 복구와 감사에 필요하고, working memory는 다음 턴의 효율적인 추론에 필요하다. 둘을 하나로 섞으면 프롬프트가 금방 비대해진다.

6. 하위 에이전트 위임도 넣었지만, 철저히 제한한다

이 저장소의 가장 재미있는 기능은 delegate다. 다만 “마음대로 하위 에이전트를 생성하는 멀티에이전트 시스템”은 아니다. 현재 깊이가 최대 깊이보다 작을 때만 활성화되며, child agent는 approval_policy="never"와 read_only=True로 생성된다. 즉, 하위 에이전트는 조사만 하고 위험한 실행은 하지 못한다. (GitHub)

이건 굉장히 좋은 설계 감각이다. 위임은 성능 향상 도구이기도 하지만, 통제가 없으면 복잡성 폭탄이 된다. 이 저장소는 위임을 허용하되 범위를 좁게 묶는다. “보조 조사자” 정도의 역할만 주는 셈이다.

프로젝트 아키텍처 분석

아래 다이어그램은 이 저장소의 실제 구조를 개발자 관점에서 재구성한 것이다.

이 아키텍처의 핵심은 MiniAgent.ask() 루프다. 사용자 요청을 기록한 뒤, 모델 호출 → 응답 파싱 → 도구 실행 → 기록 저장을 반복하고, 모델이 <final>을 반환하면 종료한다. 도중에 malformed 응답이 나오면 retry 경로로 다시 유도하고, 도구 반복 호출도 감지한다. 또한 최대 스텝 수와 최대 시도 수를 두어 루프가 무한정 돌지 않게 막는다. (GitHub)

여기서 눈여겨볼 점은 단순한 while-loop 안에 코딩 에이전트의 본질이 거의 다 들어 있다는 것이다. 별도의 복잡한 orchestration 레이어 없이도, 에이전트는 다음 여섯 가지를 반드시 가진다.

• 현재 작업 공간에 대한 사실
• 도구 집합
• 도구 사용 규칙
• 상태 축약 방식
• 지속되는 세션 저장소
• 행동 범위를 제어하는 안전장치

이 저장소는 그 여섯 가지를 하나의 파일 안에 모아 두었기 때문에 학습 재료로 가치가 높다. (GitHub)

코드로 보면 더 잘 보이는 포인트

예를 들어 이 프로젝트의 도구 정의 방식은 매우 직관적이다.

tools = {
    "read_file": {
        "schema": {"path": "str", "start": "int=1", "end": "int=200"},
        "risky": False,
        "run": self.tool_read_file,
    },
    "run_shell": {
        "schema": {"command": "str", "timeout": "int=20"},
        "risky": True,
        "run": self.tool_run_shell,
    },
}

이 방식의 장점은 세 가지다. 첫째, 모델에게 보여줄 설명과 런타임 검증 로직의 간격이 짧다. 둘째, 위험 여부가 실행 단위에 붙어 있어 승인 로직을 일관되게 적용할 수 있다. 셋째, 새 도구를 추가해도 에이전트 전체 구조를 뜯어고칠 필요가 없다. 이 저장소의 실제 build_tools()도 정확히 이 패턴을 따른다. (GitHub)

프롬프트도 비슷하다. 이 프로젝트는 “현재 요청만” 모델에 보내지 않는다.

prompt = f"""
{stable_prefix}

{memory_text}

Transcript:
{history_text}

Current user request:
{user_message}
"""

이 구조는 초보자가 에이전트를 만들 때 자주 놓치는 부분을 정확히 짚는다. 에이전트는 질문응답 챗봇이 아니라, 누적된 작업 상태를 가진 프로그램이다. 그러니 memory와 transcript가 빠지면 같은 파일을 반복해서 읽거나, 방금 수정한 내용을 잊어버리게 된다. 실제 구현도 이 순서를 그대로 사용한다. (GitHub)

실제 사용 흐름은 어떻게 되나

README와 예제 문서는 새 Python 저장소를 만든 뒤, 에이전트를 특정 작업 디렉터리에 붙여 binary_search.py를 구현하고, 다시 수정하고, pytest 테스트를 추가한 뒤, 테스트를 실행하고, 실패를 수정하는 흐름을 보여준다. 실행 예시는 uv run mini-coding-agent --cwd ./tmp/binary-search-repo --model "qwen3.5:4b"처럼 매우 단순하다. (GitHub)

개발자 관점에서 이 흐름이 좋은 이유는 “코딩 에이전트가 실제로 하는 일”을 과장 없이 보여주기 때문이다.

1. 저장소 구조를 파악한다.
2. 필요한 파일을 읽는다.
3. 새 파일을 쓰거나 기존 파일을 수정한다.
4. 테스트를 실행한다.
5. 결과를 보고 다시 수정한다.

이 다섯 단계는 오늘날 상용 코딩 에이전트도 결국 반복하는 패턴이다. 차이는 UI와 통합 범위, 그리고 모델 품질일 뿐이다.

이 프로젝트를 언제 쓰면 좋을까

이 저장소는 다음과 같은 경우에 특히 좋다.

코딩 에이전트를 처음부터 이해하고 싶을 때

에이전트 프레임워크를 배우기 전에, 에이전트의 최소 실행 루프를 이해하고 싶다면 아주 좋은 출발점이다. 특히 “도구 호출 포맷”, “세션 저장”, “권한 제어”, “컨텍스트 압축”이 왜 필요한지 실제 코드로 볼 수 있다. (GitHub)

로컬 전용 실험 환경이 필요할 때

이 프로젝트는 Ollama의 /api/generate 엔드포인트를 사용하며, 기본 모델도 qwen3.5:4b로 설정되어 있다. 즉, 클라우드 API 없이 로컬 환경에서 작게 실험하기 좋다. 민감한 코드베이스를 외부 SaaS로 보내기 어렵다면, 구조 학습용 또는 내부 PoC용으로 꽤 적절하다. (GitHub)

사내 에이전트 하네스를 직접 만들고 싶을 때

실제로 팀에서 코딩 에이전트를 만들려는 경우, 이 저장소를 “완제품”으로 쓰기보다는 설계 참고서로 보는 편이 맞다. 예를 들어 다음 같은 확장을 생각할 수 있다.

class CompanyAgent(MiniAgent):
    def build_tools(self):
        tools = super().build_tools()
        tools["run_tests"] = {
            "schema": {"target": "str='all'"},
            "risky": True,
            "description": "Run company-standard test pipeline",
            "run": self.tool_run_tests,
        }
        return tools

이런 식으로 사내 테스트 파이프라인, 코드 포맷터, 린터, 보안 스캐너, PR 요약기 같은 도구를 추가하면 교육용 저장소가 바로 내부 개발 도구의 골격이 된다. 이 프로젝트의 도구 중심 구조는 그런 확장에 적합하다. (GitHub)

이 프로젝트의 장점과 한계

장점은 명확하다. 읽기 쉽고, 구조가 직선적이며, 코딩 에이전트의 핵심 아이디어를 추상화 없이 보여준다. 세션 저장, 승인 게이트, 반복 호출 방지, 경로 탈출 방지, read-only delegation 같은 안전한 기본기도 갖췄다. 특히 path()와 관련 로직은 워크스페이스 바깥 경로로 빠져나가는 것을 막는다. (GitHub)

반면 한계도 분명하다. 모델 백엔드는 현재 Ollama 중심이고, 도구 생태계도 작다. 병렬 실행, 계획 수립 전용 단계, 장기 메모리 검색, 코드 인덱싱, AST 기반 패치, PR 생성, 원격 실행 같은 고급 기능은 없다. README 역시 이 프로젝트를 최소 로컬 에이전트 루프로 소개하며, 교육적 목적이 강하다는 점을 숨기지 않는다. (GitHub)

그래서 이 프로젝트는 “Claude Code 대체품”으로 보기보다, “Claude Code 같은 도구가 어떤 원리로 움직이는지 이해하기 위한 투명한 해부도”로 보는 편이 정확하다.

직접 실행해보는 최소 예시

git clone https://github.com/rasbt/mini-coding-agent.git
cd mini-coding-agent

ollama serve
ollama pull qwen3.5:4b

uv run mini-coding-agent --approval ask

특정 저장소를 대상으로 붙이고 싶다면 이렇게 쓸 수 있다.

uv run mini-coding-agent \
  --cwd /path/to/your-repo \
  --model qwen3.5:4b \
  --approval ask

그리고 프롬프트는 아주 구체적으로 주는 편이 좋다.

src/parser.py를 읽고, parse_config 함수의 예외 처리 누락을 수정해줘.
수정 후 tests/test_parser.py에 pytest 테스트도 추가해줘.
필요하면 테스트를 실행해도 돼.

이 프로젝트의 설계상, 에이전트는 먼저 파일을 읽고, 필요한 경우 수정 도구를 호출하고, 승인 정책이 허용되면 테스트를 실행하는 흐름으로 움직인다. EXAMPLE 문서도 같은 패턴을 따라간다. (GitHub)

마무리

mini-coding-agent의 진짜 가치는 “작다”는 데 있지 않다. “작은데도 코딩 에이전트의 핵심을 거의 빠뜨리지 않았다”는 데 있다. 저장소 컨텍스트, 프롬프트 구조, 구조화된 도구, 안전한 승인, 세션 메모리, 제한된 위임. 이 여섯 가지는 앞으로 어떤 에이전트 프레임워크를 보더라도 계속 다시 만나게 될 개념들이다. (GitHub)

복잡한 에이전트 플랫폼을 도입하기 전에, 혹은 사내 코딩 에이전트를 설계하기 전에, 이 저장소를 먼저 읽어보면 좋다. “에이전트란 결국 상태를 가진 도구 실행 루프다”라는 사실이 아주 선명하게 보이기 때문이다. 그리고 그 관점을 얻고 나면, 다른 모든 에이전트 프레임워크도 훨씬 쉽게 읽힌다. (Sebastian Raschka's Magazine)