하네스 엔지니어링 3 - 하위 집합

 

이미지 파일 (SVG : Scalable Vector Graphics)로 구성한 이미지를 캡쳐함

<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="1000" viewBox="0 0 1600 1000" fill="none">
  <defs>
    <linearGradient id="bg" x1="0" y1="0" x2="1600" y2="1000" gradientUnits="userSpaceOnUse">
      <stop stop-color="#F8FBFF"/>
      <stop offset="1" stop-color="#EEF4FF"/>
    </linearGradient>
    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
      <feDropShadow dx="0" dy="10" stdDeviation="18" flood-color="#B8C6E4" flood-opacity="0.28"/>
    </filter>
    <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="5" orient="auto">
      <path d="M0 0L10 5L0 10Z" fill="#61738F"/>
    </marker>
    <style>
      .title { font: 700 44px 'Apple SD Gothic Neo', 'Noto Sans KR', sans-serif; fill: #18243A; }
      .subtitle { font: 500 22px 'Apple SD Gothic Neo', 'Noto Sans KR', sans-serif; fill: #50617D; }
      .boxtitle { font: 700 28px 'Apple SD Gothic Neo', 'Noto Sans KR', sans-serif; fill: #18243A; }
      .boxbody { font: 500 22px 'Apple SD Gothic Neo', 'Noto Sans KR', sans-serif; fill: #42526C; }
      .coretitle { font: 700 40px 'Apple SD Gothic Neo', 'Noto Sans KR', sans-serif; fill: white; }
      .corebody { font: 500 24px 'Apple SD Gothic Neo', 'Noto Sans KR', sans-serif; fill: #EAF1FF; }
      .foot { font: 600 22px 'Apple SD Gothic Neo', 'Noto Sans KR', sans-serif; fill: #54657F; }
    </style>
  </defs>

  <rect width="1600" height="1000" fill="url(#bg)"/>

  <text x="800" y="88" text-anchor="middle" class="title">코딩 에이전트 하네스의 핵심 구성 요소</text>
  <text x="800" y="128" text-anchor="middle" class="subtitle">원문 이미지를 바탕으로, 이해하기 쉽게 한글로 재구성한 개념도</text>

  <rect x="570" y="310" width="460" height="320" rx="36" fill="#2B5CFF" filter="url(#shadow)"/>
  <text x="800" y="415" text-anchor="middle" class="coretitle">AI 모델</text>
  <text x="800" y="460" text-anchor="middle" class="corebody">추론과 생성의 중심</text>
  <text x="800" y="500" text-anchor="middle" class="corebody">하지만 혼자서는 부족함</text>
  <text x="800" y="560" text-anchor="middle" class="corebody">하네스가 있어야</text>
  <text x="800" y="600" text-anchor="middle" class="corebody">실제 업무를 안정적으로 수행</text>

  <rect x="110" y="180" width="410" height="210" rx="28" fill="#FFFFFF" stroke="#D9E4FF" stroke-width="2" filter="url(#shadow)"/>
  <text x="315" y="240" text-anchor="middle" class="boxtitle">1. 시스템 프롬프트</text>
  <text x="315" y="290" text-anchor="middle" class="boxbody">AGENTS.md, CLAUDE.md 같은</text>
  <text x="315" y="325" text-anchor="middle" class="boxbody">공통 규칙과 작업 원칙</text>
  <text x="315" y="360" text-anchor="middle" class="boxbody">“무엇을 우선하고 무엇을 피할지” 지정</text>

  <rect x="1080" y="180" width="410" height="210" rx="28" fill="#FFFFFF" stroke="#D9E4FF" stroke-width="2" filter="url(#shadow)"/>
  <text x="1285" y="240" text-anchor="middle" class="boxtitle">2. 도구 / MCP</text>
  <text x="1285" y="290" text-anchor="middle" class="boxbody">파일, 셸, 브라우저, DB, API 등</text>
  <text x="1285" y="325" text-anchor="middle" class="boxbody">모델이 바깥세상과 상호작용하는 수단</text>
  <text x="1285" y="360" text-anchor="middle" class="boxbody">“할 수 있는 일의 범위”를 확장</text>

  <rect x="110" y="640" width="410" height="210" rx="28" fill="#FFFFFF" stroke="#D9E4FF" stroke-width="2" filter="url(#shadow)"/>
  <text x="315" y="700" text-anchor="middle" class="boxtitle">3. 컨텍스트 관리</text>
  <text x="315" y="750" text-anchor="middle" class="boxbody">필요한 지식만 적시에 넣고</text>
  <text x="315" y="785" text-anchor="middle" class="boxbody">불필요한 정보는 줄이는 설계</text>
  <text x="315" y="820" text-anchor="middle" class="boxbody">“짧고 관련성 높은 작업 창” 유지</text>

  <rect x="1080" y="640" width="410" height="210" rx="28" fill="#FFFFFF" stroke="#D9E4FF" stroke-width="2" filter="url(#shadow)"/>
  <text x="1285" y="700" text-anchor="middle" class="boxtitle">4. 서브에이전트</text>
  <text x="1285" y="750" text-anchor="middle" class="boxbody">큰 문제를 작은 작업으로 나누고</text>
  <text x="1285" y="785" text-anchor="middle" class="boxbody">각 작업을 분리된 컨텍스트에서 처리</text>
  <text x="1285" y="820" text-anchor="middle" class="boxbody">“메인 에이전트의 집중력”을 보호</text>

  <path d="M520 350C560 360 590 380 620 410" stroke="#61738F" stroke-width="4" stroke-linecap="round" marker-end="url(#arrow)"/>
  <path d="M1080 350C1040 360 1010 380 980 410" stroke="#61738F" stroke-width="4" stroke-linecap="round" marker-end="url(#arrow)"/>
  <path d="M520 700C565 680 595 655 625 620" stroke="#61738F" stroke-width="4" stroke-linecap="round" marker-end="url(#arrow)"/>
  <path d="M1080 700C1035 680 1005 655 975 620" stroke="#61738F" stroke-width="4" stroke-linecap="round" marker-end="url(#arrow)"/>

  <rect x="260" y="900" width="1080" height="54" rx="18" fill="#E6EEFF"/>
  <text x="800" y="935" text-anchor="middle" class="foot">하네스 = 모델 주변의 실행 환경, 제약, 도구, 컨텍스트, 분업 구조를 설계하는 것</text>
</svg>

AI 모델

추론과 생성의 중심입니다. 다만 모델만으로는 파일 수정, 외부 도구 호출, 긴 작업 유지, 안전한 실행 통제가 어렵기 때문에 하네스가 필요합니다.

시스템 프롬프트

AGENTS.md(Open AI - GPT), CLAUDE.md 같은 공통 지침층입니다. 에이전트가 어떤 규칙을 따르고, 무엇을 우선하며, 무엇을 피해야 하는지 정합니다.

도구

쉘(Shell) : 텍스트 명령어 기반으로 파일시스템, 브라우저, API, DB 등을 다룰 수 있는 실행 수단입니다. 모델이 실제 시스템 환경과 상호작용하게 해 주는 인터페이스입니다.
스킬(Skill) : 특정 작업을 잘 수행하게 만드는 지침/절차 모듈, Codex의 skill은 Claude의 skill(Skill instruction module) 과 유사
MCP : Model Context Protocol : AI 에이전트가 파일, 데이터베이스, API, 브라우저 같은 외부 도구와 표준 방식으로 연결되도록 해주는 인터페이스 규약

 

컨텍스트 관리

필요한 정보만 적절한 시점에 넣고, 불필요한 정보는 줄이는 방식입니다.
핵심은 에이전트가 긴 문맥에 묻히지 않고, 현재 작업에 필요한 정보에 집중하게 만드는 것입니다.

AGENTS.md, CLAUDE.md는 정보를 찾기 위한 맵(목차)로 간략하게 구성하고, 에이전트가 필요에 따라 세부 정보를 찾아서 작업할 수 있도록 하는 것

서브에이전트

큰 작업을 작은 작업으로 나누어 별도 컨텍스트에서 처리하는 구조입니다. 메인 에이전트의 컨텍스트를 오염시키지 않고 조사, 분석, 구현 같은 하위 작업을 분리할 때 유용합니다. 
메인 에이전트가 하위 조사 작업을 별도 에이전트에게 맡김
Claude의 서브에이전트는 Codex의 spawned agent나 병렬 에이전트 실행 개념
* spawn [spɔːn]