# 코딩 에이전트의 구성 요소 > Clean Markdown view of GeekNews topic #28232. Use the original source for factual precision when an external source URL is present. ## Metadata - GeekNews HTML: [https://news.hada.io/topic?id=28232](https://news.hada.io/topic?id=28232) - GeekNews Markdown: [https://news.hada.io/topic/28232.md](https://news.hada.io/topic/28232.md) - Type: GN+ - Author: [neo](https://news.hada.io/@neo) - Published: 2026-04-06T03:33:23+09:00 - Updated: 2026-04-06T03:33:23+09:00 - Original source: [magazine.sebastianraschka.com](https://magazine.sebastianraschka.com/p/components-of-a-coding-agent) - Points: 32 - Comments: 1 ## Summary ML 분야의 베스트셀러 저자 **Sebastian Raschka**가 코딩 에이전트의 내부 구조를 체계적으로 분해한 글입니다. LLM은 엔진, 추론 모델은 강화된 엔진, 하네스는 그 엔진을 제어하는 시스템이라는 비유가 깔끔하고요. 리포 컨텍스트, 프롬프트 캐시, 도구 접근, 세션 메모리, 서브에이전트 위임까지 **여섯 가지 구성 요소**로 나눠 설명합니다. 하네스가 대체 뭘 하는 건지 구체적으로 알고 싶은 분에게 좋은 입문 글입니다. ## Topic Body - **코딩 에이전트**는 LLM을 중심으로 코드 작성, 실행, 피드백을 반복 수행하는 **제어 루프와 소프트웨어 하니스**로 구성된 시스템 - **에이전트 하니스**는 컨텍스트 관리, 도구 접근, 프롬프트 구성, 상태 제어를 담당하며, 코딩 작업에 특화된 **코딩 하니스**는 리포지토리·테스트·에러 점검을 관리 - 코딩 에이전트는 **실시간 리포 컨텍스트, 프롬프트 캐시, 도구 접근, 컨텍스트 관리, 세션 메모리, 하위 에이전트 위임**의 여섯 구성 요소로 작동 - 하니스 설계 품질에 따라 동일한 LLM이라도 **성능과 사용자 경험이 크게 달라지며**, 잘 설계된 하니스는 지속적이고 맥락 인식적인 개발 환경을 제공 - Mini Coding Agent는 이러한 구조를 **순수 Python으로 구현한 최소 예시**로, OpenClaw와는 코딩 특화 여부와 운영 범위에서 차이를 보임 --- ### 코딩 에이전트의 구성 요소 - **코딩 에이전트**는 LLM을 중심으로 한 제어 루프와 이를 감싸는 **소프트웨어 하니스(harness)** 로 구성된 시스템으로, 코드 작성·수정·실행·피드백을 반복 수행하는 구조 - **LLM**은 기본적인 다음 토큰 예측 모델이며, **추론 모델(reasoning model)** 은 중간 추론과 검증을 더 많이 수행하도록 훈련된 LLM - **에이전트**는 목표 달성을 위해 모델 호출, 도구 사용, 상태 갱신, 종료 판단 등을 반복 수행하는 제어 루프 - **에이전트 하니스(agent harness)** 는 이러한 루프를 감싸는 소프트웨어 구조로, **컨텍스트 관리**, **도구 접근**, **프롬프트 구성**, **상태 제어** 등을 담당 - **코딩 하니스(coding harness)** 는 코드 작업에 특화된 형태로, 리포지토리 컨텍스트, 코드 실행, 테스트, 에러 점검 등을 관리 ### LLM, 추론 모델, 에이전트의 관계 - LLM은 **엔진**, 추론 모델은 **강화된 엔진**, 에이전트 하니스는 **이 엔진을 제어하는 시스템**으로 비유 가능 - LLM과 추론 모델은 단독으로도 코딩 작업을 수행할 수 있으나, 실제 개발 환경에서는 **리포 탐색, 함수 검색, 테스트 실행, 에러 분석** 등 복합적 맥락 관리가 필요 - **코딩 하니스**는 모델의 성능을 극대화하며, 단순 채팅형 인터페이스보다 훨씬 강력한 코딩 경험을 제공 ### 코딩 하니스의 역할 - 모델을 감싸는 **소프트웨어 계층**으로, 프롬프트 조립, 도구 노출, 파일 상태 추적, 명령 실행, 권한 관리, 캐시, 메모리 저장 등을 수행 - 동일한 LLM이라도 하니스 설계에 따라 **성능과 사용자 경험이 크게 달라짐** - 예를 들어, GLM-5 같은 오픈웨이트 모델도 Codex나 Claude Code 수준의 하니스에 통합되면 유사한 성능을 낼 수 있음 - OpenAI는 GPT-5.3과 GPT-5.3-Codex처럼 **하니스별 후처리 모델**을 별도로 유지한 사례 존재 ### 코딩 에이전트의 6가지 핵심 구성 요소 - ## 1. 실시간 리포지토리 컨텍스트 (Live Repo Context) - 에이전트는 현재 **Git 리포 상태, 브랜치, 문서, 테스트 명령어** 등을 인식해야 함 - “테스트 수정” 같은 지시는 리포 구조와 문맥에 따라 달라지므로, **작업 전 리포 요약 정보를 수집** - 이를 통해 매번 제로 상태에서 시작하지 않고, **안정된 작업 기반(stable facts)** 확보 - ## 2. 프롬프트 구조와 캐시 재사용 (Prompt Shape and Cache Reuse) - 리포 요약, 도구 설명, 일반 지침 등은 자주 변하지 않으므로 **“안정된 프롬프트 프리픽스(stable prompt prefix)”** 로 캐시 - 매 요청마다 전체 프롬프트를 새로 조립하지 않고, **변경된 부분만 업데이트** - 반복 세션에서 **계산 낭비를 줄이고 응답 일관성 유지** - ## 3. 도구 접근과 사용 (Tool Access and Use) - 모델이 단순히 명령을 제안하는 대신, **하니스가 정의한 도구 세트**를 통해 실제 명령 실행 가능 - 각 도구는 **명확한 입력·출력 형식과 경계**를 가지며, 실행 전 **유효성 검사 및 승인 절차** 수행 - 예: “알려진 도구인가?”, “인자 유효한가?”, “작업 경로가 워크스페이스 내인가?” 등의 검증 - 이를 통해 **보안성과 신뢰성 향상**, 모델의 자유도는 줄지만 **실용성 증가** - ## 4. 컨텍스트 팽창 최소화 (Minimizing Context Bloat) - 긴 세션에서 반복된 파일 읽기, 로그, 도구 출력 등으로 **프롬프트 길이 초과 문제 발생** - 하니스는 두 가지 전략으로 이를 관리 - **클리핑(clipping)**: 긴 텍스트, 로그, 메모를 일정 길이로 축약 - **요약(summarization)**: 오래된 대화 이력을 압축 요약 - 최근 이벤트는 상세히 유지하고, 오래된 정보는 **중복 제거 및 압축** - 결과적으로 모델 품질보다 **컨텍스트 품질이 실제 성능에 더 큰 영향** - ## 5. 구조화된 세션 메모리 (Structured Session Memory) - 에이전트는 상태를 **작업 메모리(working memory)** 와 **전체 대화 기록(full transcript)** 으로 분리 - 전체 기록은 모든 요청·응답·도구 출력을 포함하며 **세션 재개 가능** - 작업 메모리는 현재 중요한 정보(현재 작업, 주요 파일, 최근 노트 등)를 **요약 저장** - **압축된 대화 기록(compact transcript)** 은 모델 프롬프트 재구성용, 작업 메모리는 **작업 지속성 유지용** - ## 6. 하위 에이전트 위임 (Delegation With Bounded Subagents) - 메인 에이전트가 **보조 작업을 병렬 처리**하기 위해 **하위 에이전트(subagent)** 를 생성 - 예: 특정 심볼 정의 위치, 설정 파일 내용, 테스트 실패 원인 등을 별도 하위 작업으로 분리 - 하위 에이전트는 **필요한 컨텍스트만 상속**받고, **읽기 전용·재귀 깊이 제한** 등으로 제약 - Claude Code와 Codex 모두 하위 에이전트를 지원하며, **작업 범위와 컨텍스트 깊이로 경계 설정** ### 구성 요소 요약 - 여섯 구성 요소는 상호 밀접하게 연결되어 있으며, **하니스 설계 품질이 모델 활용 효율을 결정** - 잘 설계된 코딩 하니스는 단순한 LLM 채팅보다 훨씬 **맥락 인식적이고 지속적인 개발 지원 환경** 제공 - Mini Coding Agent(https://github.com/rasbt/mini-coding-agent)는 이러한 구조를 **순수 Python으로 구현한 최소 예시** ### OpenClaw와의 비교 - **OpenClaw**는 코딩 전용 도우미라기보다 **일반 에이전트 플랫폼**에 가까움 - 공통점: - 워크스페이스 내 **프롬프트·지침 파일(AGENTS.md, TOOLS.md 등)** 사용 - **JSONL 세션 파일**, **대화 압축**, **세션 관리** 기능 포함 - **보조 세션 및 하위 에이전트 생성** 가능 - 차이점: - 코딩 에이전트는 **리포 탐색·코드 편집·로컬 도구 실행**에 최적화 - OpenClaw는 **다중 채널·워크스페이스 간 장기 에이전트 운영**에 중점 ### 부록: 신간 안내 - *Build A Reasoning Model (From Scratch)* 집필 완료, 현재 **초기 접근판(Early Access)** 공개 중 - 출판사는 여름 출간을 목표로 레이아웃 작업 진행 - 책은 **LLM의 추론 메커니즘을 직접 구현하며 이해하는 접근법** 중심으로 구성됨 ## Comments ### Comment 54708 - Author: neo - Created: 2026-04-06T03:33:23+09:00 - Points: 1 ###### [Hacker News 의견들](https://news.ycombinator.com/item?id=47638810) - 긴 **context**는 여전히 비싸고 불필요한 정보가 많으면 노이즈가 생김 그래서 나는 대화형 코딩 대신 **spec 기반 생성**이 더 낫다고 생각함 내가 만든 [Ossature](https://github.com/ossature/ossature)는 반대 접근임. 먼저 동작을 설명하는 spec을 작성하면, 코드 생성 전에 누락이나 모순을 감리하고, 각 작업이 어떤 spec 섹션과 파일을 참조하는지 명시한 build plan TOML을 생성함 LLM은 필요한 부분만 보고, 대화 이력 누적이 없음. 모든 프롬프트와 응답은 디스크에 저장되어 **추적성**이 자동으로 확보됨 최근에는 이 방식으로 [CHIP-8 에뮬레이터](https://github.com/beshrkayali/chomp8)를 완전히 spec만으로 만들었고, [예제 프로젝트들](https://github.com/ossature/ossature-examples)도 있음 - 요즘 코딩 에이전트에는 **중앙 진실 소스**가 없다는 생각을 자주 함 예전엔 팀이 무엇을 만들고 있는지 모두가 알고 있었지만, 지금은 에이전트가 매번 새로 시작함 그래서 나는 chat → spec → code 흐름이 미래라고 봄. spec → code 단계는 인간 개입 없이 돌아가야 함 명세가 불명확하면 인간에게 명확히 물어보고, 그걸 기반으로 코드 생성해야 함 지금은 불명확한 요청이 반복되며 인간도 왜 그런지 배우지 못함. “memory”나 agent 파일은 임시방편에 불과함 - 나도 비슷한 걸 만들고 있음. 아직 공개 전이지만 **spec 중심 워크플로우 엔진**임 대화 대신 코드와 spec의 투영된 context를 LLM에 제공하고, 단계별로 context를 다르게 구성함 누적 context로 인한 **drift**를 막고, LLM이 아닌 내 코드가 워크플로우를 제어함 TOML을 단계 간 전달 artifact로 쓰는 아이디어가 흥미로워서 참고해볼 예정임 - 나도 같은 생각임. Agent A는 오직 spec만 수정하고, Agent B는 spec만 보고 빌드함 사용자는 Agent A가 만든 **diff**를 검토하면 되고, 반복적 코드 검증에서 벗어남 핵심은 **의도(intent)** 를 항상 보존하는 것임. 명세와 맥락을 그대로 저장해야 함 비용은 2~3배 들겠지만 장기적으로는 효율이 더 높아질 것 같음 - chat 기반 워크플로우는 피로하고 정보 손실이 많음 spec 기반 접근이 훨씬 낫다고 생각함. 사람이 개입하는 방식이 궁금함 — spec과 audit 편집을 병행하는지, 코드 생성 성공률은 어떤지, 기존 코드에도 적용할 계획이 있는지 궁금함 - 나도 **Claude Code + Cucumber** 조합으로 spec부터 시작해 코드 반복 개선을 시도함 Ossature는 그 접근과 어떻게 다른지 궁금함 - 단순한 **state machine**과 bash 접근만으로 LLM의 잠재력을 끌어낸 게 놀라움 - 그래서 나는 **격리된 코딩 에이전트**를 직접 만들고 있음 요즘 에이전트 생태계는 과도한 기능과 나쁜 결정으로 가득함 10년 전만 해도 이런 도구엔 책임감이 필요하다고 했는데, 지금은 공포와 과대광고가 뒤섞인 혼란스러운 시기임 - 결국 핵심은 **prompt/context 엔지니어링**임 모델은 지식을 이미 갖고 있지만, 이를 실질적 행동으로 이끌려면 context 설계가 중요함 사용자 요청을 숙련 개발자의 단계로 번역하고 필요한 도구를 연결하는 방식이 유망함 오픈소스 모델도 잘 최적화된 에이전트와 약간의 튜닝으로 충분히 경쟁 가능하다고 봄 - **Claude Code 유출본**을 보면, 그 구조는 단순하지 않음 복잡한 하네스가 필요하지만, 그 덕분에 LLM이 도구로서 **결정론적**으로 작동함 - 많은 CLI 에이전트들이 단순히 bash 접근만으로는 부족하다고 생각해, **JavaScript TUI**에 온갖 기능을 억지로 넣고 있음 - bash 대신 **Python**을 쓰는 게 더 유용했음 파이프라인 대신 자유롭게 원하는 로직을 구성할 수 있음 - 예제가 간결하고 명확함 코딩 에이전트를 쓰지 않지만, 이 글은 **코딩 에이전트의 본질**을 이해하는 데 도움 됨 단 1k LOC짜리 유용한 코드도 500k LOC의 혼란으로 바뀔 수 있다는 점을 잘 보여줌 - 이미 많은 사람들이 **GLM-5** 같은 오픈 모델을 Claude Code나 Codex CLI에 연결해 사용 중임 [GLM 공식 문서](https://docs.z.ai/devpack/tool/claude)에서도 이를 권장함 - Opus 수준은 아니지만, **GLM과 Qwen3.5-plus** 조합이 개인 프로젝트에서는 충분히 훌륭함 - 글이 인상적이었음. 나는 이메일 기반 **비코딩 에이전트**를 만들었는데 원리는 비슷함 각 이메일 루프마다 context를 새로 시작해 **context 누적 문제**를 자연스럽게 해결함 초기 프롬프트에 넣을 context와 툴로 분리할 context의 균형이 중요함 캐싱과 토큰 비용도 고려해야 함 자세한 내용은 [내 블로그 글](https://www.healthsharetech.com/blog/building-alice-an-empow...)에 정리했음 - “harness”라는 단어가 마음에 들지 않음. 더 나은 표현이 없을까 생각함 - “test harness”나 “fuzzing harness”처럼 프로그램을 관리하는 **shim** 의미로 자주 쓰임 - 아이러니하게도 요즘 모든 게 “app”이 되었는데, 정작 LLM 실행용 앱은 “app”이라 부르지 않음 - 결국 “harness”는 **scaffolding**의 멋진 표현일 뿐임 - 그렇다면 대안 단어를 제안해보라는 반응도 있었음 - **tool output truncation**이 context 부풀림을 줄이는 데 매우 효과적임 나는 SQLite 기반으로 context를 조립하고, 필요 시 메시지 ID로 잘린 툴 호출을 복원함 관련 실험은 [문서](https://github.com/hsaliak/std_slop/blob/main/docs/CONTEXT_M...)에 정리했음 - Claude Code를 다른 모델로 돌리는 건 흔한 일임 [예시 문서](https://docs.z.ai/scenario-example/develop-tools/claude)에도 나와 있음 하지만 내 경험상 Anthropic 모델 수준에는 미치지 못함 - 프로젝트에 따라 **MiMo V2 Pro** 같은 저가 모델로도 70~80%는 가능하지만, **Sonnet**이 훨씬 뛰어난 경우도 있음 Opus는 비용 대비 가치가 있는 경우가 5% 정도뿐임 나는 **OpenCode**가 Claude Code보다 훨씬 낫다고 느껴 OpenRouter API 크레딧을 구매함 OpenCode는 커스텀 명령과 간단한 agent 정의만으로도 충분히 강력함 AGENTS.md, ROADMAP.md 등으로 워크플로우를 정의하면 대부분의 프로젝트에 충분함 복잡한 하네스보다는 **유연한 구조**가 최신 모델 변화에 더 잘 대응한다고 생각함 - Anthropic 모델이 더 나은 이유가 단순히 모델 품질 때문인지, 아니면 **하네스 최적화** 때문인지 궁금함 - 코딩 에이전트의 발전은 모델 자체보다 **주변 구조(scaffolding)** 개선에서 더 많이 옴 도구, 리포지토리 context, 간단한 상태 기계가 갖춰지면 병목은 **context 품질**로 이동함 - 글이 강렬했음. 나도 코딩 에이전트를 **엔진/자동차 비유**로 설명하곤 함 기본 구성 요소를 실험해보고 싶다면 [OpenHands software-agent-sdk](https://github.com/OpenHands/software-agent-sdk)를 참고할 만함