하네스 스택 (The Harness Stack)

다섯 명의 개발자에게 "에이전트 하네스 (agent harness)"가 무엇인지 물어본다면, 당신은 다섯 가지의 서로 다른 답변을 듣게 될 것입니다. 어떤 이들은 모델을 의미합니다. 어떤 이들은 CLAUDE.md 파일을 의미합니다. 어떤 이들은 오케스트레이션 인프라 (orchestration infrastructure)를 의미합니다. 모두가 무언가 실질적인 것을 만들고 있습니다. 하지만 공유된 어휘가 없다면, 우리는 서로에게서 배울 수 없고, 시스템 전반에 걸쳐 추론할 수 없으며, 문제가 발생했을 때 그 문제가 어디에 있는지조차 합의할 수 없습니다.

이것이 현재 AI 에이전트 설정 (AI agent configuration)이 처한 상황입니다. _하네스 (harness)_라는 단어는 어디에나 있으며, 모든 것을 의미합니다. 이는 다시 말해, 유용할 만큼 정밀한 의미를 담고 있지 않다는 뜻이기도 합니다.

이것은 사소한 불편함이 아닙니다. 이토록 젊은 분야에서, 우리가 정착시키는 단어들은 우리가 구축하는 멘탈 모델 (mental models)을 형성합니다. 그리고 멘탈 모델은 우리가 다음에 무엇을 만들 것인지에 대한 생각을 결정합니다. 사물에 이름을 신중하게 붙이는 것은 집단적 인프라 (collective infrastructure)를 구축하는 행위입니다.

이 포스트는 하나의 분류 체계(taxonomy)를 제안합니다: 하네스 스택 (The Harness Stack). 각각 명확한 범위와 책임을 가진 다섯 가지의 개별적인 레벨입니다. 이것은 규정적인 것이 아닙니다. 다섯 가지를 모두 가질 필요도 없습니다. 이것은 이 분야가 나누어야 할 대화를 위한 시작점으로 제공되는 공유된 지도입니다.

다섯 가지 레벨

레벨 0: 모델 하네스 (Model Harness)

AI 코딩 도구 그 자체입니다. Claude Code, Cursor, Copilot, Pi 등 당신이 실행하고 있는 무엇이든 해당됩니다.

이것은 제품 레이어 (product layer)입니다: 도구가 출시될 때 포함하는 기능, 인터페이스, 그리고 내장된 동작들을 의미합니다. 당신은 레벨 0를 설정하는 것이 아니라, 선택하는 것입니다. 그리고 그 선택은 생각보다 중요합니다. 왜냐하면 그 위의 모든 것은 에이전트가 어떻게 작동해야 하는지, 어떤 컨텍스트 (context)를 보유할 수 있는지, 어떤 훅 (hooks)을 노출하는지에 대해 해당 도구가 가지는 가정 위에 구축되기 때문입니다.

여기서 길러야 할 가치 있는 규율은 느슨한 결합 (loose coupling)입니다. 당신의 상위 레벨 설정은 특정 도구를 위해 작성되어서는 안 됩니다. 그것은 오늘날 레벨 0가 충족하고 있는 도구의 _부류 (class)_를 위해 작성되어야 합니다. 모델을 교체하는 것이 마찰 없이 이루어지는 단계까지는 아직 도달하지 못했지만, 지금부터 그러한 이식성 (portability)을 목표로 설계하는 것은 복리로 돌아오는 투자입니다.

레벨 1: 에이전트 하네스 (Agent Harness)

도구가 단일 프로젝트가 아닌, 당신의 모든 작업 전반에 걸쳐 전역적으로(globally) 어떻게 구성되는지를 다룹니다.

이곳은 메모리(memory), 지속적인 선호도(persistent preferences), 사용자 수준 설정(user-level settings), 그리고 코드베이스에서 다른 코드베이스로 당신과 함께 이동하는 컨텍스트(context)가 존재하는 곳입니다. Claude Code에서는 이것이 전역 CLAUDE.md 파일입니다. claude.ai에서는 메모리 및 시스템 수준 지침(system-level instructions)입니다. 레벨 1은 매우 중요하지만 간과하기 쉬운 질문에 답합니다: 이 에이전트가 특정 프로젝트를 마주하기 전에 어떻게 행동하도록 구성되어 있는가?

레벨 0과 레벨 1의 구분은 무너지기 쉽지만 반드시 유지해야 할 만큼 중요합니다. 도구(tool)는 제공되는 그대로의 모습입니다. 에이전트(agent)는 당신이 그 도구를 통해 만들어낸 결과물입니다. 기본 동작(default behavior)과 의도적으로 형성된 동작(deliberately shaped behavior) 사이의 그 간극에 놀라울 정도의 레버리지(leverage)가 존재합니다. 당신이 선호하는 코딩 스타일, 장황함(verbosity)에 대한 허용치, 명명 규칙(naming conventions) 및 에러 처리(error handling) 방식 등을 이해하는 에이전트는 모든 프로젝트에 참여할 때 이미 부분적으로 방향이 잡힌(oriented) 상태로 도착합니다. 그 방향 설정이 바로 레벨 1입니다.

레벨 2: 프로젝트 하네스 (Project Harness)

에이전트가 작동하는 코드베이스 수준의 스캐폴딩(scaffolding)입니다.

현재 대부분의 개발자가 활발하게 구축하고 있는 단계이며, 툴링(tooling)이 가장 성숙한 단계이기도 합니다. 프로젝트 하네스에는 다음이 포함됩니다:

• 슬래시 명령어(Slash commands) 및 MCP 플러 plugins
• 훅 스크립트 (Hook scripts: PreToolUse, PostToolUse, Stop, Bash)
• 특정 모듈에 범위가 지정된(scoped) 하위 디렉토리 CLAUDE.md 파일들
• 특성 테스트(Characterization tests) 및 정적 분석(static analysis) 설정
• 기술(skills), 센서(sensors), 규칙(rules), 플라이휠(flywheels) 및 기타 "마크다운으로서의 코드(code as markdown)" 산출물들

레벨 2를 지형(terrain)이라고 생각하십시오. 이는 에이전트가 당신의 코드베이스를 이동하며 마주치는 것들을 형성합니다: 어떤 가드레일(guardrails)이 존재하는지, 어떤 패턴을 따라야 하는지, 어떤 도구를 어디서 사용할 수 있는지 등을 결정합니다. 잘 설계된 프로젝트 하네스는 단순히 에이전트를 제약하는 것에 그치지 않습니다. 올바른 경로를 가장 쉬운 경로로 만들어 줍니다. 이것이 최근 제가 주목하고 있는 계층입니다.

이 분야의 열린 질문들은 진정으로 흥미롭습니다. 하위 디렉터리 컨텍스트 (subdirectory context)가 노이즈가 되기 전까지 얼마나 세밀해야 할까요? 훅 (hook)이 지혜를 인코딩하는 시점은 언제이며, 두려움을 인코딩하는 시점은 언제일까요? 프로젝트 하네스 (project harness)가 경직되어, 6개월 전에는 타당했지만 지금은 방해가 될 뿐인 규칙 세트로 변하는 것을 어떻게 방지할 수 있을까요? 이것들은 숙련도에 관한 질문 (craft questions)이며, 우리는 이제 막 공유된 답변들을 개발하기 시작한 단계입니다.

레벨 3: 조직 하네스 (Organization Harness)

프로젝트 간 일관성 계층 (cross-project consistency layer). 그리고 스택에서 가장 미비하게 구축된 단계입니다.

레벨 2가 단일 프로젝트의 지형이라면, 레벨 3은 여러 지형을 동일한 에이전트가 읽을 수 있게 만드는 측량 (survey)입니다. 어떤 규모에서든 그 목적은 한 프로젝트에서 다른 프로젝트로 이동하는 에이전트가 기본 사항을 다시 배울 필요가 없도록 만드는 것입니다. 공유된 컨벤션 (Shared conventions). 공통된 도구 설정 (Common tool configurations). 어디서나 적용되어 어디에서도 다시 진술할 필요가 없는 정책들입니다.

레벨 3은 반드시 기업 규모여야 할 필요는 없습니다. 모노레포 (monorepo)에서는 루트 레벨의 CLAUDE.md와 공유된 린트 설정 (lint config) 그 이상도 이하도 아닐 수 있습니다. 더 큰 조직의 경우, 승인된 도구 레지스트리 (tool registries), 컴플라이언스 가드레일 (compliance guardrails), 그리고 거버넌스 정책 (governance policies)으로 확장됩니다. 하지만 여러 레포지토리를 사용하는 솔로 개발자이든, 수십 개의 제품 팀을 지원하는 플랫폼 팀이든 그 의도는 동일합니다.

현재의 솔직한 상태는 이렇습니다: 아직 의도적으로 레벨 3을 수행하는 사람은 거의 없습니다. 대부분의 팀은 우연히 이를 갖게 됩니다. 유기적으로 발생한 컨벤션, 누군가 추가하고 다른 사람들이 조용히 물려받은 루트 CLAUDE.md 같은 것 말입니다. 그것이 아무것도 아니라는 뜻은 아니지만, 설계 (design)라고 할 수는 없습니다.

이 계층을 위해 특화된 도구는 아직 실제로 존재하지 않습니다. 하지만 기본 요소 (primitives)들은 존재하며, 이는 개발자들이 이미 알고 있는 것들입니다. 버전 관리 (version-controlled)가 되는 공유 저장소 (shared repo)에는 조직 수준의 CLAUDE.md, 훅 템플릿 (hook templates), 린트 설정 (lint configs) 등을 담을 수 있습니다. 패키지 매니저 (Package managers)가 이를 배포할 수 있습니다. 오늘날 여러 개의 개별 저장소를 관리하는 팀에게 git submodules는 과소평가된 실용적인 옵션입니다. 조직의 설정을 각 프로젝트에 서브모듈로 가져오고, 중앙에서 이를 업데이트하면, 각 프로젝트가 자체 일정에 따라 변경 사항을 상속받도록 할 수 있습니다.

MCP servers 또한 고려할 만한 또 다른 우회 방법입니다. 내부 MCP 서버는 각 프로젝트가 설정을 직접 포함할 필요 없이, 연결된 모든 에이전트에게 조직 전체의 도구, 프롬프트 (prompts), 리소스 (resources)를 노출할 수 있습니다. 이는 서브모듈과는 다른 방식으로 배포 문제를 해결합니다. 하지만 더 어려운 문제들, 즉 조직 수준의 하네스 (harness)가 어떻게 '작성'되는지, 프로젝트 수준의 설정과의 충돌을 어떻게 해결하는지, 또는 드리프트 (drift)를 어떻게 감지하는지는 해결하지 못합니다. 데이터 (bytes)가 어디에 있든 이러한 공백은 남아 있습니다.

진정한 공백은 기술적인 것이 아니라 의미론적 (semantic)인 것입니다. 이는 바로 공유된 어휘 (shared vocabulary)가 메울 수 있는 종류의 공백입니다.

이것이 스택에서 가장 흥미로운 빈 계층입니다. 에이전트 워크플로우 (agentic workflows)가 성숙해지고 프로젝트가 늘어남에 따라, 불일치 (inconsistency)는 조용히 누적됩니다. Level 3에 조기에 투자하는 팀은 그 기여도를 명확히 측정하기는 어렵지만 결코 놓칠 수 없는 방식으로 배당금을 지급할 무언가를 구축하고 있는 것입니다.

Level 4: 오케스트레이터 하네스 (Orchestrator Harness)

에이전트들의 플릿 수준 (Fleet-level) 조정. 제품과 프레임워크가 패턴보다 더 빠르게 등장하고 있는 단계입니다.

Devin은 레벨 4 (Level 4) 시스템입니다. CrewAI, AutoGen, LangGraph, 그리고 swarm 프레임워크도 마찬가지입니다. 개별 에이전트를 더 큰 그래프 내의 노드(nodes)로 취급하여, 에이전트 간의 작업을 라우팅(routing)하고, 생명주기(lifecycles)를 관리하며, 출력물을 일관된 결과물로 구성하는 모든 인프라가 이에 해당합니다. 이것은 전통적인 의미의 설정(configuration)이 아닙니다. 이것은 코레오그래피 (choreography, 안무/조율)입니다. 이 단계의 하네스 (harness)는 에이전트가 어떻게 생각하는지를 형성하지 않습니다. 에이전트들이 서로 어떻게 관계를 맺는지를 형성합니다.

LangGraph는 이를 구체화합니다. 에이전트 노드(agent nodes)의 그래프, 에이전트 간의 조건부 라우팅 (conditional routing)을 나타내는 엣지 (edges), 그리고 작업이 진행됨에 따라 그래프를 통해 흐르는 상태 (state)를 정의합니다. 여기서 하네스는 그래프 그 자체이며, 어떤 에이전트가 어떤 조건에서 무엇을 처리할지, 그리고 무언가 실패했을 때 어떤 일이 일어날지에 대해 인코딩된 결정 사항들입니다. Devin은 구현 방식은 다를지라도 정신적으로는 유사하게 작동합니다. 작업이 시스템에 들어오면, 분해(decomposed)되고, 분산(distributed)되며, 다시 조립(reassembled)됩니다. 오케스트레이터 (orchestrator) 하네스는 바로 그 프로세스를 하나로 묶어주는 역할을 합니다.

레벨 4를 진정으로 어렵게 만드는 것은 도구 (tooling)가 아닙니다. LangGraph와 그 동료 도구들은 점점 더 유능해지고 있습니다. 아직 정립된 답이 없는 것은 바로 설계 (design) 질문들입니다. 에이전트 플릿 (fleet)이 당신이 의도하지 않은 일을 하고 있을 때, 어떻게 알 수 있을까요? 생성된 인스턴스 (instances)들 사이에서 인과 관계를 어떻게 추적할 수 있을까요? 하위 작업 (subtasks)으로 분해되어도 유지될 수 있도록 조직의 의도 (organizational intent)를 어떻게 인코딩할 수 있을까요? 실패하는 구성 요소 자체가 자체적인 하네스를 가진 에이전트일 때, 실패에 대해 어떻게 추론할 수 있을까요?

이것들은 사소한 질문들이 아닙니다. 레벨 4는 공유된 어휘 (shared vocabulary)의 부재가 가장 큰 비용을 초래하는 단계입니다. 시스템이 충분히 복잡하여 부정확한 언어가 부정확한 설계로 직결되기 때문입니다. 그리고 이 정도 규모에서의 부정확한 설계는 진단하기 어렵고 해결하는 데 비용이 많이 드는 방식으로 실패하게 됩니다.

제품은 분류 체계를 따르지 않는다

"하네스 (harness)\

Claude Code는 기본적으로 Level 0 도구이지만, Level 2 프리미티브 (primitives): 기술 (skills), 명령 (commands), .claude/ 디렉토리 구조 등을 함께 제공합니다. Cursor는 Level 0과 Level 2 사이에 걸쳐 있습니다. CrewAI와 AutoGen은 Level 1과 Level 4를 동시에 모호하게 만듭니다. 즉, 이들은 하나의 에이전트가 어떻게 실행되는지와 얼마나 많은 에이전트가 협력하는지를 정의합니다. LangChain은 Level 1, Level 2, 그리고 때로는 Level 4에 걸쳐 넓게 퍼져 있습니다. Devin은 다섯 단계 모두에 관여합니다.

이것이 바로 용어가 무너지는 이유입니다. 제품들이 거짓말을 하는 것이 아닙니다. 이들은 실제로 여러 계층에 걸쳐 있습니다. 해결책은 이들이 그렇지 않은 척하는 것이 아닙니다. 해결책은 우리가 제품에 대해 이야기할 때, 그 제품이 _어느 레벨(level)_에 닿아 있는지를 명시하는 것입니다.

디버깅 사다리 (A debugging ladder)

이 분류 체계는 무언가 잘못되었을 때 그 진가를 발휘합니다.

에이전트가 예상치 못한 방식으로 동작할 때, 본능적으로 가장 눈에 띄는 것, 대개 프롬프트 (prompt)나 설정 파일 (config file)을 건드리게 됩니다. 하지만 "이것은 어느 레벨의 문제인가?"라는 질문이 더 유용합니다:

• 도구 자체가 이 작업에서 성능을 제대로 내지 못하고 있는가? (L0)
• 전역 메모리 (global memory)나 에이전트 설정 (agent configuration)이 불완전하거나 모순되는가? (L1)
• 훅 (hook)이 잘못 설정되었거나, 하위 디렉토리의 CLAUDE.md에 중요한 컨텍스트 (context)가 누락되었는가? (L2)
• 에이전트가 일관성 없이 상속받고 있는 프로젝트 간의 충돌하는 컨벤션 (conventions)이 있는가? (L3)
• 오케스트레이션 (orchestration) 로직이 라우팅 (routing)을 잘못하거나 잘못된 스폰 (spawning)을 하고 있는가? (L4)

다섯 가지 질문. 다섯 가지 확인 지점. 이것은 단순한 디버깅 방법론이 아닙니다. 공유된 어휘가 가능하게 만드는 것입니다.

어텐션 맵 (The attention map)

이 분류 체계는 이 분야의 어텐션 맵 (attention map)을 가시화해 줍니다. 현재 대부분의 작업은 Level 0 (도구 전쟁), Level 2 (프로젝트 레벨 스캐폴딩의 폭발), 그리고 Level 4 (멀티 에이전트 프레임워크)에서 일어나고 있습니다. Level 1은 뒤따라가고 있습니다. Level 3은 비어 있습니다.

만약 다음번 흥미로운 작업이 어디에서 일어날지 찾고 있다면, 비어 있는 계층을 보십시오.

이것을 명명하는 것이 중요한 이유

우리는 집단적으로 급격한 축적의 시기에 놓여 있습니다. 패턴이 명명되는 속도보다 더 빠르게 나타나고 있습니다. 그 결과 지식은 국지적으로 머물게 됩니다. 즉, 개별 CLAUDE.md 파일에 묻혀 있거나, 문서화되지 않은 훅 스크립트(hook scripts), 팀 변경 시 살아남지 못하는 관습적인 규칙(tribal conventions)으로 남게 됩니다.

분류 체계(Taxonomies)는 평소에는 단순한 정리 작업처럼 느껴지지만, 어느 순간 갑자기 하중을 견뎌야 하는 지지 구조(load-bearing)가 됩니다. 하네스 스택 (The Harness Stack)의 목표는 빠르게 움직이는 분야에 격식(ceremony)을 더하는 것이 아닙니다. 이 분야에 논쟁할 수 있는 구체적인 대상을 제공하는 것입니다. "더 나은 하네스가 필요하다"라는 말은 오늘날 대답할 수 없는 질문입니다. 왜냐하면 다음 사람이 이를 원하는 대로 어떻게든 해석할 수 있기 때문입니다. 반면 "더 나은 레벨 3 (Level 3)가 필요하다"는 말은 실행에 옮길 수 있는 논쟁거리가 됩니다.

저는 이 이론을 느슨하게 유지하고 있습니다. 경계선은 진정으로 모호합니다. 글로벌 메모리 (global memory)가 프로젝트 특정 컨텍스트 (project-specific context)를 참조하기 시작하면 레벨 1 (Level 1)과 레벨 2 (Level 2)의 경계가 흐려집니다. 조직 정책 (org policies)이 에이전트 생성 동작 (agent spawning behavior)을 규제하기 시작하면 레벨 3 (Level 3)과 레벨 4 (Level 4)의 경계가 흐려집니다. 그것은 괜찮습니다. 분류 체계는 유용하기 위해 완벽할 필요는 없습니다. 공유될 필요가 있을 뿐입니다.

규칙은 이렇습니다. "하네스"라고 말할 때는 어느 레벨인지 말하십시오. 분류 체계는 어딘가 틀려 있을 것입니다. 이것은 첫 번째 시도입니다. 저는 엔지니어들이 서로 고개를 끄덕이며 다섯 가지 서로 다른 멘탈 모델 (mental models)을 가진 채 방을 나가는 것을 계속 지켜보는 것보다, 레벨 3 (Level 3)을 조직 계층 (Organization layer)이라고 불러야 할지 아니면 다른 무언가로 불러야 할지에 대해 논쟁하는 편을 택하겠습니다.

이것이 여러분이 구축하고 있는 방식과 일치합니까, 아니면 의미 있는 지점에서 어긋납니까? 저는 어느 레벨이 유지되고 어느 레벨에서 논쟁이 필요한지 궁금합니다. 만약 여러분이 이 분야에서 작업하고 있다면, 저는 제가 옳다는 것을 증명하기보다 대화를 나누고 싶습니다.