http://www.gurubee.net 꿈꾸는 개발자, DBA 커뮤니티 구루비 ko 2026-04-11 14:03:36 Copyright ©gurubee.net All Rights Reserved. Since 2001.07.09 https://www.gurubee.net/article/90157 https://www.gurubee.net/article/90157 2026-03-16 16:54:30 원문: [The Anatomy of an Agent Harness (2026.3.10)](https://blog.langchain.com/the-anatomy-of-an-agent-harness/) LangChain의 Vivek Trivedy가 작성한 이 글은 **Agent = Model + Harness** 라는 공식에서 출발하여, 모델이 아닌 모든 것—즉 하네스(Harness)—의 구성 요소와 설계 원리를 체계적으로 정리합니다. 핵심 전제는 명확합니다. 모델은 지능을 담고 있고, 하네스는 그 지능을 쓸모 있게 만드는 시스템입니다. --- ## 하네스의 정의 - 하네스는 모델 자체가 아닌 모든 코드, 설정, 실행 로직을 포괄합니다. - 구체적으로는 시스템 프롬프트, 도구(Tools/MCP) 및 그 설명, 번들 인프라(파일시스템, 샌드박스, 브라우저), 오케스트레이션 로직(서브에이전트 스포닝, 핸드오프, 모델 라우팅), 훅/미들웨어(컴팩션, 컨티뉴에이션, 린트 체크) 등이 해당합니다. - 이 정의가 유용한 이유는, 모델 지능을 중심에 두고 **그 주변 시스템을 설계하는 사고방식**을 강제하기 때문입니다. --- ## 왜 하네스가 필요한가: 모델의 한계에서 출발 LLM은 기본적으로 텍스트·이미지·오디오·비디오를 입력받아 텍스트를 출력할 뿐입니다. 모델 단독으로는 할 수 없는 것들이 하네스의 존재 이유가 됩니다. - 상호작용 간 지속 상태 유지 불가 - 코드 실행 불가 - 실시간 지식 접근 불가 - 작업 완료를 위한 환경 설정 및 패키지 설치 불가 가장 기본적인 예시로, "채팅" UX를 만들려면 모델을 while 루프로 감싸 이전 메시지를 추적하고 새 메시지를 append해야 합니다. 이것 자체가 이미 하네스입니다. 글의 전체 구조는 **"원하는 에이전트 행동 → 그것을 실현하는 하네스 설계"** 라는 패턴을 반복하며 각 컴포넌트를 도출합니다. --- ## 파일시스템: 지속 저장소이자 컨텍스트 관리의 기반 모델은 컨텍스트 윈도우 안의 지식만 직접 다룰 수 있으므로, 하네스는 **파일시스템 추상화와 fs-ops 도구**를 제공합니다. 파일시스템이 가장 근본적인 하네스 프리미티브인 이유: - 에이전트에게 데이터, 코드, 문서를 읽고 쓸 수 있는 작업 공간을 제공합니다. - 중간 산출물을 저장하고, 단일 세션을 넘어서는 상태를 유지할 수 있습니다. 모든 것을 컨텍스트에 올려놓을 필요 없이 점진적으로 작업을 오프로드합니다. - **자연스러운 협업 표면**이 됩니다. 여러 에이전트와 인간이 공유 파일을 통해 조율하는 Agent Teams 같은 아키텍처가 이를 활용합니다. Git을 더하면 버저닝이 가능해져 작업 추적, 오류 롤백, 실험 브랜치 등이 열립니다. --- ## Bash + 코드 실행: 범용 도구 - 오늘날 에이전트의 주요 실행 패턴은 [ReAct 루프](https://docs.langchain.com/oss/python/langchain/agents)입니다. 모델이 추론하고, 도구를 호출하고, 결과를 관찰하고, 반복합니다. - 그러나 모든 가능한 행동에 대해 사전 정의된 도구를 만드는 건 비현실적입니다. 대신 **bash 도구를 탑재**하면 모델이 코드를 작성·실행하여 스스로 문제를 해결할 수 있습니다. - 사실상 **모델에게 컴퓨터를 주는 것**에 가깝습니다. 고정된 도구 세트에 구속되지 않고, 모델이 코드로 자체 도구를 즉석에서 설계합니다. - 하네스에 다른 도구도 탑재하지만, 코드 실행이 자율적 문제 해결의 기본 전략이 되었습니다. --- ## 샌드박스: 안전한 실행 환경과 검증 도구 - 에이전트가 생성한 코드를 로컬에서 실행하면 위험하고, 단일 로컬 환경은 대규모 에이전트 워크로드로 확장되지 않습니다. - **샌드박스**는 코드를 안전하고 격리된 환경에서 실행합니다. 필요에 따라 환경을 생성·확장·폐기할 수 있습니다. - 보안 강화를 위해 하네스는 커맨드 허용 목록, 네트워크 격리 등을 적용할 수 있습니다. - 좋은 환경에는 좋은 기본 도구가 따라옵니다. 언어 런타임, 패키지, git/테스트 CLI, [브라우저](https://github.com/vercel-labs/agent-browser) 등을 사전 설치하는 것이 하네스의 역할입니다. - 브라우저, 로그, 스크린샷, 테스트 러너 같은 도구는 에이전트가 **자기 검증 루프**를 만들 수 있게 합니다. 코드 작성 → 테스트 실행 → 로그 확인 → 오류 수정의 사이클입니다. --- ## 메모리와 검색: 지속적 학습 - 모델은 가중치와 현재 컨텍스트 이외의 지식이 없습니다. 가중치를 수정할 수 없으므로 지식을 추가하는 유일한 방법은 **컨텍스트 주입**입니다. - 파일시스템이 다시 핵심 프리미티브가 됩니다. 하네스는 [AGENTS.md](http://agents.md/) 같은 메모리 파일 표준을 지원하고, 에이전트 시작 시 컨텍스트에 주입합니다. 에이전트가 이 파일을 수정하면 다음 세션에 반영됩니다. - 이것은 일종의 [지속적 학습](https://www.ibm.com/think/topics/continual-learning) 형태입니다. - 지식 컷오프 문제에 대해서는 Web Search, [Context7](https://context7.com/) 같은 MCP 도구로 최신 정보에 접근합니다. --- ## 컨텍스트 부패(Context Rot) 대응 [컨텍스트 부패](https://research.trychroma.com/context-rot)란 컨텍스트 윈도우가 채워질수록 모델의 추론·작업 완수 능력이 저하되는 현상입니다. 오늘날의 하네스는 사실상 **좋은 컨텍스트 엔지니어링의 전달 메커니즘**입니다. - **Compaction**: 컨텍스트 윈도우가 한계에 근접하면, 기존 컨텍스트를 지능적으로 오프로드·요약하여 에이전트가 계속 작업할 수 있게 합니다. - **Tool Call Offloading**: 대용량 도구 출력이 컨텍스트를 어지럽히는 문제에 대응합니다. 임계값 이상의 도구 출력은 head/tail 토큰만 남기고 전체 출력을 파일시스템에 저장합니다. - **Skills (Progressive Disclosure)**: 에이전트 시작 시 너무 많은 도구/MCP 서버가 컨텍스트에 로드되면 성능이 저하됩니다. Skills는 필요한 시점에 점진적으로 도구 정보를 공개하는 하네스 수준의 프리미티브입니다. --- ## 장기 자율 실행 자율적 소프트웨어 생성이 코딩 에이전트의 최종 목표이지만, 현재 모델은 조기 중단, 복잡한 문제 분해 실패, 다수의 컨텍스트 윈도우에 걸친 비일관성 문제를 겪습니다. 앞서 다룬 하네스 프리미티브들이 여기서 복합적으로 작용합니다. - **파일시스템 + Git**: 에이전트가 장기 작업 중 수백만 토큰을 생성하더라도 파일시스템이 작업을 지속적으로 포착합니다. Git은 새 에이전트가 프로젝트 히스토리를 빠르게 파악할 수 있게 하고, 다수 에이전트가 공유 원장처럼 파일시스템을 활용해 협업합니다. - **[Ralph Loop](https://ghuntley.com/loop/)**: 모델이 종료를 시도하면 훅이 이를 가로채고, 깨끗한 컨텍스트 윈도우에 원래 프롬프트를 재주입하여 작업을 계속하도록 강제하는 하네스 패턴입니다. 각 반복은 신선한 컨텍스트로 시작하되 파일시스템에서 이전 상태를 읽습니다. - **계획과 자기 검증**: 하네스는 좋은 프롬프팅과 파일시스템 내 계획 파일 사용법 리마인더 주입을 통해 계획을 지원합니다. 각 단계 완료 후 훅이 사전 정의된 테스트 스위트를 실행하고, 실패 시 오류 메시지와 함께 모델에 루프백합니다. --- ## 하네스의 미래 ### 모델 훈련과 하네스 설계의 결합 - Claude Code, Codex 같은 현재 에이전트 제품은 모델과 하네스를 함께 놓고 포스트 트레이닝합니다. 모델이 파일시스템 조작, bash 실행, 계획, 서브에이전트 병렬화 등에 능숙해지도록 합니다. - 이 과정이 피드백 루프를 만듭니다. 유용한 프리미티브가 발견되면 하네스에 추가되고, 다음 세대 모델 훈련에 활용됩니다. - 다만 부작용도 있습니다. 도구 로직을 변경하면 모델 성능이 떨어지는 **오버피팅** 현상이 나타납니다. [Codex-5.3 프롬프팅 가이드](https://developers.openai.com/cookbook/examples/gpt-5/codex_prompting_guide/#apply_patch)의 apply_patch 도구 사례가 대표적입니다. - 그렇다고 모델이 포스트 트레이닝된 하네스가 항상 최적인 것은 아닙니다. [Terminal Bench 2.0 리더보드](https://www.tbench.ai/leaderboard/terminal-bench/2.0)에서 Opus 4.6은 Claude Code보다 다른 하네스에서 훨씬 높은 점수를 기록합니다. LangChain 팀은 하네스만 변경하여 코딩 에이전트 순위를 Top 30에서 Top 5로 끌어올린 사례를 보여준 바 있습니다. ### 하네스 엔지니어링의 방향 - 모델이 더 강해지면 현재 하네스에 있는 기능 일부(계획, 자기 검증, 장기 일관성 등)가 모델에 흡수될 것입니다. - 그러나 프롬프트 엔지니어링이 여전히 가치 있듯, 하네스 엔지니어링도 유효할 것입니다. 하네스는 모델 결함을 보완하는 것만이 아니라, 모델 지능 주위에 시스템을 구성하여 효율을 높이는 역할을 하기 때문입니다. - LangChain에서 하네스 빌딩 라이브러리 [deepagents](https://docs.langchain.com/oss/python/deepagents/overview)를 통해 탐구 중인 문제들: - 공유 코드베이스에서 수백 개의 에이전트를 병렬 오케스트레이션하는 것 - 에이전트가 자신의 트레이스를 분석해 하네스 수준 실패 모드를 식별·수정하는 것 - 사전 설정이 아닌, 주어진 작업에 맞는 도구와 컨텍스트를 just-in-time으로 동적 조립하는 하네스 --- > 모델은 지능을 담고, 하네스는 그 지능이 작동하는 시스템입니다.]]> https://www.gurubee.net/article/90156 https://www.gurubee.net/article/90156 2026-03-13 16:09:50 **파일 정리 도구가 아니라 지식 연결 도구입니다** 폴더보다 **링크가 중요합니다.** --- 💡 원하시면 제가 추가로 아래도 설명해 드릴게요 1️⃣ **Obsidian 고수들이 쓰는 Vault 구조 (Second Brain 시스템)** 2️⃣ **개발자에게 최고의 Obsidian 플러그인 15개** 3️⃣ **Obsidian + AI (Claude / ChatGPT) 지식 자동 생성 방법** 4️⃣ **Obsidian을 10배 잘 쓰는 Zettelkasten 실전 예시** 이건 Obsidian을 쓰는 사람들도 **90%가 모르는 방법들입니다.**]]> https://www.gurubee.net/article/90155 https://www.gurubee.net/article/90155 2026-03-12 16:38:39 --ai claude` 이렇게 하면 해당 프로젝트의 .claude/commands/ 에 아래 커맨드들이 생성됩니다 - /speckit.constitution - 프로젝트 거버넌스 정의 - /speckit.specify - 스펙 문서 작성 - /speckit.plan - 구현 계획 생성 - /speckit.tasks - 태스크 분해 - /speckit.implement - 개발 실행 - /speckit.clarify - 스펙 검 ### superpowers - [https://github.com/obra/superpowers](https://github.com/obra/superpowers)]]>