▲

코딩 에이전트의 구성 요소

 (magazine.sebastianraschka.com)
8P by GN⁺ 11시간전 | ★ favorite | 댓글 1개
  • 코딩 에이전트는 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의 추론 메커니즘을 직접 구현하며 이해하는 접근법 중심으로 구성됨

함께 보면 좋은 글 β

▲
GN⁺ 11시간전  [-]
Hacker News 의견들

  • 긴 context는 여전히 비싸고 불필요한 정보가 많으면 노이즈가 생김
    그래서 나는 대화형 코딩 대신 spec 기반 생성이 더 낫다고 생각함
    내가 만든 Ossature는 반대 접근임. 먼저 동작을 설명하는 spec을 작성하면, 코드 생성 전에 누락이나 모순을 감리하고, 각 작업이 어떤 spec 섹션과 파일을 참조하는지 명시한 build plan TOML을 생성함
    LLM은 필요한 부분만 보고, 대화 이력 누적이 없음. 모든 프롬프트와 응답은 디스크에 저장되어 추적성이 자동으로 확보됨
    최근에는 이 방식으로 CHIP-8 에뮬레이터를 완전히 spec만으로 만들었고, 예제 프로젝트들도 있음

    • 요즘 코딩 에이전트에는 중앙 진실 소스가 없다는 생각을 자주 함
      예전엔 팀이 무엇을 만들고 있는지 모두가 알고 있었지만, 지금은 에이전트가 매번 새로 시작함
      그래서 나는 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 공식 문서에서도 이를 권장함

    • Opus 수준은 아니지만, GLM과 Qwen3.5-plus 조합이 개인 프로젝트에서는 충분히 훌륭함

  • 글이 인상적이었음. 나는 이메일 기반 비코딩 에이전트를 만들었는데 원리는 비슷함
    각 이메일 루프마다 context를 새로 시작해 context 누적 문제를 자연스럽게 해결함
    초기 프롬프트에 넣을 context와 툴로 분리할 context의 균형이 중요함
    캐싱과 토큰 비용도 고려해야 함
    자세한 내용은 내 블로그 글에 정리했음

  • “harness”라는 단어가 마음에 들지 않음. 더 나은 표현이 없을까 생각함

    • “test harness”나 “fuzzing harness”처럼 프로그램을 관리하는 shim 의미로 자주 쓰임
    • 아이러니하게도 요즘 모든 게 “app”이 되었는데, 정작 LLM 실행용 앱은 “app”이라 부르지 않음
    • 결국 “harness”는 scaffolding의 멋진 표현일 뿐임
    • 그렇다면 대안 단어를 제안해보라는 반응도 있었음

  • tool output truncation이 context 부풀림을 줄이는 데 매우 효과적임
    나는 SQLite 기반으로 context를 조립하고, 필요 시 메시지 ID로 잘린 툴 호출을 복원함
    관련 실험은 문서에 정리했음

  • Claude Code를 다른 모델로 돌리는 건 흔한 일임
    예시 문서에도 나와 있음
    하지만 내 경험상 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를 참고할 만함

답변달기