하네스 엔지니어링과 멀티 에이전트팀 개념

AI 에이전트가 실제 업무에서 신뢰할 수 있게 동작하려면 "무엇을 시킬지"보다 "어떤 틀 안에서 움직이게 할지"가 더 중요해진다. 1장에서 AI 에이전트의 필요성을 살펴보았다. 이 장에서는 하네스 엔지니어링이라는 관점과, 하나의 에이전트가 아니라 여러 에이전트가 팀으로 협업하는 멀티 에이전트팀의 기본 구조를 살펴본다.

출처: Claude Code 공식 문서 — Subagents, ai-workspace-standards 저장소, Faros AI — Harness Engineering, Anthropic — Building Effective Agents

에이전트란 무엇인가

이 장에서 본격적으로 하네스 엔지니어링을 다루기 전에, "에이전트"가 정확히 무엇인지 짚고 넘어가자. AI 에이전트는 단순한 챗봇과 구별되는 목적이 부여된 AI 시스템이다.

챗봇은 "질문에 답하는" 것이 전부다. 사용자가 프롬프트를 입력하면 응답을 생성하고, 대화가 끝나면 아무것도 남지 않는다. 반면 에이전트는 세 가지 차이가 있다.

• 목적 지속성: 에이전트는 "역할"로 정의된 목적을 가진다. 대화가 길어져도 자기 역할(리서처, 검토자, 작성자 등)을 잃지 않고 일관되게 행동한다.
• 도구 사용: 에이전트는 텍스트 생성뿐 아니라 파일을 읽고, 코드를 검색하고, 명령을 실행할 수 있다. 4장에서 이 도구를 tools 필드로 제어하는 방법을 실습한다.
• 자율적 행동: 에이전트는 단일 프롬프트에 대한 단일 응답이 아니라, 목적을 달성하기 위해 여러 단계를 자율적으로 수행할 수 있다. 조건 분기, 오류 재시도, 결과 검증까지 스스로 판단한다.

Prompt → Context → Harness — 여기까지 오게 된 흐름

하네스 엔지니어링은 어느 날 갑자기 등장한 개념이 아니라, AI를 다루는 방식이 세 단계를 거치며 쌓아 올린 결과다. 각 단계는 이전 단계를 대체한 것이 아니라, "이전 단계만으로는 부족하다"는 걸 드러내며 그 위에 새로운 층을 얹었다.

세 단계를 요리에 비유하면 이해가 빠르다. 프롬프트 엔지니어링은 "주방장에게 어떤 말로 주문을 넣을 것인가"이고, 컨텍스트 엔지니어링은 "주방장 손에 어떤 재료와 레시피를 쥐여 줄 것인가"이며, 하네스 엔지니어링은 "이 주방이 매번 같은 맛을 내도록 검수 절차·도구·위생 규칙까지 갖춘 시스템을 만드는 것"이다. 아무리 말을 잘하고 재료가 좋아도, 주방 시스템 자체가 엉성하면 결과는 매번 들쭉날쭉하다.

1단계 — 프롬프트 엔지니어링 (2022~2024년)

초기 관심은 순전히 언어에 있었다. 같은 요청이라도 어떻게 표현하느냐에 따라 결과 품질이 크게 달라진다는 사실이 알려지면서, "더 나은 프롬프트를 쓰는 법"이 핵심 기술로 취급됐다. 이 시기의 AI는 정교한 자동완성에 가까웠고, 사람이 매 단계 방향을 잡아 줘야 했다.

예를 들어 "코드 리뷰해줘"라고만 요청하면 모델이 무엇을 기준으로 봐야 할지 몰라 두루뭉술한 답을 내놓지만, "이 함수의 엣지 케이스 처리, 네이밍 일관성, 성능 문제를 각각 짚어서 리뷰해줘"처럼 구체적으로 지시하면 결과가 확 달라진다. 이런 "말을 어떻게 다듬을 것인가"에 대한 노하우가 이 시기의 전부였다.

2단계 — 컨텍스트 엔지니어링 (2024~2025년)

모델 성능이 좋아지면서 병목은 "표현"에서 "정보 공급"으로 옮겨갔다. 관련 파일, 프로젝트 규칙, 아키텍처 제약처럼 모델의 컨텍스트 창에 무엇을 채워 넣을지 큐레이션하는 일이 중요해졌고, RAG나 MCP 같은 도구가 이 과정을 체계화했다. Anthropic은 2025년 9월 이를 "추론 과정에서 최적의 토큰 집합을 큐레이션하고 유지하는 기술"이라고 공식 정의했다.

아무리 좋은 프롬프트를 써도, 모델이 우리 프로젝트의 코딩 컨벤션이나 기존 함수 구조를 모르면 엉뚱한 스타일의 코드를 내놓는다. 컨텍스트 엔지니어링은 "이 요청과 관련된 파일 몇 개, 프로젝트 규칙 문서, 과거 대화 요약"처럼 모델이 실제로 필요로 하는 정보만 골라 컨텍스트 창에 채워 넣는 기술이다. 정보가 너무 적으면 헛다리를 짚고, 너무 많으면 정작 중요한 내용이 노이즈에 묻힌다.

3단계 — 하네스 엔지니어링 (2026년)

2026년 현재 지배적인 패러다임이다. 모델 자체는 원재료에 가까운 지능을 담고 있을 뿐이고, 그 지능을 실제로 신뢰할 수 있는 자율적 행동으로 바꿔주는 것이 하네스다. 도구 오케스트레이션, 검증 루프, 컨텍스트·메모리 관리, 가드레일, 관측성(observability). 이 다섯 층이 갖춰졌을 때 비로소 에이전트가 "일을 맡길 만한" 수준이 된다. "에이전트 자체는 어렵지 않다. 어려운 건 하네스다"라는 말이 이 시기를 요약한다.

같은 프롬프트, 같은 컨텍스트를 줘도 매번 다른 품질의 결과가 나온다면 실무에 쓸 수 없다. 하네스 엔지니어링은 "이 결과를 자동으로 검증할 방법이 있는가", "위험한 작업(파일 삭제, 결제 실행 등)은 사람 승인 없이 못 하게 막았는가", "실패했을 때 무엇이 잘못됐는지 로그로 추적할 수 있는가" 같은, 모델의 대답 자체가 아니라 그 대답을 둘러싼 시스템을 설계하는 일이다.

하네스 아키텍처 전체도

하네스 엔지니어링은 모델과 사용자 사이에 놓이는 5층 구조로 생각할 수 있다. 아래 다이어그램은 이 핸드북 전체를 관통하는 아키텍처를 한눈에 보여준다 — 각 장이 이 5층 중 어느 계층을 다루는지는 다음 절에서 연결한다.

하네스 엔지니어링이란

프롬프트 엔지니어링이 "모델에게 어떤 말을 건넬 것인가"에 집중한다면, 하네스 엔지니어링은 한 걸음 물러나 "모델이 어떤 도구·규칙·검증 장치를 통해 일하게 할 것인가"를 설계하는 일이다. 여기서 하네스(harness)는 승마에서 말에게 씌우는 마구에서 온 표현으로, AI가 마음대로 아무 방향으로나 달리지 않고 정해진 절차·도구·권한 범위 안에서 예측 가능하게 움직이도록 잡아 주는 틀을 뜻한다.

실제로 이 틀은 몇 가지 구체적인 장치로 나타난다. 에이전트가 호출할 수 있는 도구의 목록과 각 도구의 위험도에 따른 승인 정책, 특정 이벤트(파일 저장 직후, 작업 완료 시점 등)에 자동으로 실행되는 훅(hook), 반복되는 작업 절차를 표준화해 재사용하는 스킬(skill), 그리고 이 모든 것을 조합해 여러 에이전트를 정해진 순서·조건으로 실행시키는 오케스트레이션 스크립트가 그것이다. 이런 장치들이 쌓이면, 같은 요청을 몇 번을 반복해도 결과의 품질과 형식이 흔들리지 않는 "재현 가능한 AI 워크플로"가 만들어진다.

구체적인 예를 들어보자. "파일을 삭제해줘"라는 요청이 들어왔을 때, 하네스가 없는 AI는 곧바로 삭제를 실행할 수도 있다. 하네스가 있는 AI는 다르다. 삭제는 "위험한 도구"로 분류돼 있어 실행 전 사용자 승인을 요구하는 정책이 걸려 있고, 삭제가 끝나면 그 사실이 로그에 남고, 실수로 잘못된 파일을 지웠을 때 되돌릴 방법(git으로 커밋 전 상태 확인 등)까지 절차화돼 있다. 모델의 판단력은 똑같은데, 그 판단력을 둘러싼 "안전장치"가 있고 없고의 차이가 결과의 신뢰도를 가른다.

단일 에이전트의 한계

하나의 에이전트에게 모든 역할을 맡기면 초기에는 편리하지만, 작업이 커질수록 세 가지 문제가 뚜렷해진다. 첫째, 컨텍스트 과부하다. 설계 검토, 코드 작성, 테스트, 문서화를 한 세션 안에서 순서대로 처리하다 보면 앞선 단계의 세부 사항이 뒤로 갈수록 희미해지고, 결과의 일관성이 떨어진다. 둘째, 역할 충돌이다. 코드를 작성한 에이전트가 자기 코드를 스스로 검토하면 놓치는 결함이 많아진다. 작성자와 검토자가 같은 사람이면 생기는 것과 똑같은 문제다. 셋째, 병렬성의 부재다. 서로 독립적인 하위 작업(예: 여러 파일의 리팩터링, 여러 관점의 코드 리뷰)도 단일 에이전트는 순서대로 처리할 수밖에 없어 시간이 선형으로 늘어난다.

회사 조직에 비유하면 이해하기 쉽다. 신입사원 한 명에게 기획·개발·테스트·문서화를 전부 맡기면, 처음엔 소통 비용이 없어 빠른 듯 보이지만 작업량이 늘수록 그 사람의 머릿속(컨텍스트)이 뒤죽박죽되고, 자기가 짠 코드의 허점을 자기가 못 보고 지나치며(역할 충돌), 서로 관련 없는 일 세 가지를 동시에 처리할 수 없어(병렬성 부재) 병목이 된다. 실무에서 기획자·개발자·QA를 나누는 이유와 똑같은 이유로, AI 작업도 여러 에이전트로 나눈다.

멀티 에이전트팀은 이 세 가지를 구조적으로 해결한다. 역할별로 컨텍스트를 분리해 각 에이전트가 자기 역할에 집중하게 하고, 작성자와 검증자를 분리해 독립적인 시각을 확보하며, 서로 의존하지 않는 작업은 동시에 실행해 시간을 단축한다.

멀티 에이전트팀의 구성요소

멀티 에이전트팀은 크게 세 가지 요소로 이루어진다.

오케스트레이터(Orchestrator)

전체 작업을 단계로 나누고, 각 단계에 맞는 스페셜리스트 에이전트를 호출하며, 사용자와의 확인이 필요한 지점(게이트)에서 진행을 멈추는 역할이다. 흔히 "PM 에이전트"로 불리며, 스스로 코드를 작성하지 않고 조율에 집중한다.

비유하면 프로젝트 매니저(PM)와 같다. PM은 직접 코드를 짜지 않지만 "이 작업은 백엔드 개발자에게, 이 작업은 QA에게" 배분하고, 중요한 결정 앞에서는 "이대로 진행해도 될까요?"라고 팀장(사용자)에게 확인받은 뒤 다음 단계로 넘어간다. 오케스트레이터도 똑같이 행동한다. 예를 들어 "새 기능을 추가해줘"라는 요청을 받으면, 오케스트레이터는 스스로 "1) 설계 검토 → 2) 구현 → 3) 테스트 → 4) 문서화" 순서로 쪼갠 뒤 각 단계를 담당 에이전트에게 넘긴다.

스페셜리스트(Specialist)

설계, 구현, 테스트, 보안 검토처럼 좁고 명확한 책임을 가진 에이전트다. 각 스페셜리스트는 자신이 받은 입력과 산출해야 할 출력이 분명하게 정의돼 있어, 오케스트레이터가 "무엇을 맡길 수 있는 에이전트인지" 쉽게 판단할 수 있다.

예를 들어 test-runner 스페셜리스트는 "테스트를 실행하고 실패한 항목을 보고한다"는 책임만 가진다. 코드를 새로 작성하거나 아키텍처를 바꾸는 일은 그의 책임이 아니다. 이렇게 책임을 좁게 잘라 두면, 오케스트레이터 입장에서는 "테스트가 필요하면 test-runner를 부르면 된다"는 판단이 즉각 선고, 스페셜리스트 입장에서는 자기 역할에만 집중해 더 정확한 결과를 낼 수 있다.

핸드오프 계약(Handoff Contract)

에이전트 사이에 작업을 넘길 때 주고받는 정보의 형식이다. 자연어로만 넘기면 다음 에이전트가 맥락을 다시 추측해야 하지만, 구조화된 입력(예: JSON)으로 "이 작업의 목적·범위·이전 단계 산출물"을 명시하면 다음 에이전트가 바로 작업에 들어갈 수 있다.

택배 인수인계를 떠올리면 된다. "이거 저기 갖다 줘"라고만 하면 받는 사람이 주소·수량·주의사항을 다시 물어봐야 하지만, 송장(운송장 번호·수령인·수량·특이사항이 적힌 문서)을 같이 넘기면 받는 사람이 바로 배송을 시작할 수 있다. 핸드오프 계약은 에이전트 사이의 "송장"이다. writer가 reviewer에게 "이 파일을, 이런 기준으로, 이 형식으로 검토해줘"라고 명시적으로 넘기면 reviewer는 다시 물어볼 필요 없이 바로 시작한다.

실제로는 다음과 같은 구조화된 문서로 넘긴다.

{
  "task": "코드 리뷰",
  "agent": "reviewer",
  "scope": {
    "target_file": "src/api/handler.ts",
    "change_description": "인증 미들웨어 추가 — JWT 토큰 검증 로직"
  },
  "deliverables": {
    "from": "code-writer",
    "files": ["src/api/handler.ts", "src/auth/verify.ts"],
    "commit_hash": "a3f7c21"
  },
  "review_criteria": [
    "보안: 토큰 만료 처리가 있는가",
    "오류 처리: 잘못된 토큰에 대한 401 응답이 있는가",
    "테스트: 관련 테스트가 추가되었는가"
  ],
  "output_format": {
    "type": "structured_comment",
    "fields": ["pass_fail", "findings", "suggestions"]
  },
  "failure_conditions": [
    "target_file이 존재하지 않으면 즉시 보고",
    "보안 기준 미충족 시 block으로 표시"
  ]
}

이 예시에서 task, scope, review_criteria가 "무엇을 검토할지"를 정하고, output_format이 "결과를 어떤 형식으로 줄지"를 정한다. failure_conditions은 검토 대상 자체에 문제가 있을 때의 처리 방식이다. 이처럼 핸드오프 계약은 목적·범위·기준·형식·예외 처리를 명시적으로 정의해 다음 에이전트가 다시 물어볼 필요 없이 바로 작업에 들어갈 수 있게 한다.

서브에이전트란 무엇인가

앞서 말한 스페셜리스트는 개념이고, 서브에이전트(subagent)는 그 개념을 실제 도구 안에서 구현하는 메커니즘이다. 서브에이전트는 메인 세션과 독립된 컨텍스트 창을 가진 보조 에이전트로, 자신에게 맡겨진 좁은 작업만 처리한 뒤 그 결과를 요약해 메인 세션으로 돌려준다. 메인 세션의 대화 기록에는 서브에이전트가 주고받은 세부 과정이 쌓이지 않고 최종 요약만 남기 때문에, §2에서 지적한 "컨텍스트 과부하" 문제를 구조적으로 완화한다.

사전 정의 vs 동적 생성 vs 역할 컨텍스트

서브에이전트를 다루는 방식은 도구마다 다르다. Claude Code/App은 사전 정의 방식을 쓴다. .claude/agents/ 아래에 이름.md 파일을 두고, YAML frontmatter로 name(호출 시 참조하는 식별자), description(언제 이 서브에이전트를 쓸지), tools(허용할 도구 목록으로 권한을 최소화), model(어떤 모델로 실행할지)을 명시한다. 메인 세션은 이 정의를 Agent(Task) 툴로 subagent_type="이름" 호출해 스폰한다.

반면 Antigravity는 동적 생성에 가깝다. 사전에 파일을 만들어 두지 않고, 오케스트레이터에게 목표를 자연어로 주면 그 순간 필요한 역할을 즉석에서 구성해 처리한다. "reviewer라는 서브에이전트를 호출했다"기보다는, 에이전트가 작업에 맞는 역할을 그때그때 만들어 쓰는 쪽에 가깝다. 두 접근 모두 결과적으로는 "좁은 책임의 작업을 격리된 컨텍스트에서 처리한다"는 같은 목표를 달성하지만, 사전 정의는 재사용성과 권한 통제가 강하고 동적 생성은 유연성이 강하다는 차이가 있다.

Codex는 역할 컨텍스트 순차 전환 방식을 쓴다. 별도의 서브에이전트 정의 파일이나 동적 스폰 없이, PM이 AGENTS.md·CODEX.md의 역할 정의를 컨텍스트로 읽고 한 단계가 끝날 때마다 다음 역할로 전환하며 작업한다. 병렬로 여러 서브에이전트가 존재하는 것이 아니라 한 세션 안에서 역할이 순차적으로 갈아입는 방식이라, 격리된 컨텍스트라기보다 "한 세션 안의 역할 전환"에 가깝다. 도구별 확장 기능 의존도가 가장 낮다는 것이 강점이다(4장 §1-C).

언제 서브에이전트를 쓰는가

모든 작업을 서브에이전트로 쪼갤 필요는 없다. 경계가 분명하고(무엇을 받아 무엇을 내놓는지 명확) 반복적이거나 병렬화가 가능한 작업. 코드 리뷰, 테스트 실행, 문서 검토 같은 것이 좋은 후보다. 반대로 메인 세션과 계속 맥락을 주고받아야 하는 탐색적 작업은 서브에이전트로 분리하면 오히려 핸드오프 비용만 늘어난다.

오케스트레이션 패턴

Anthropic이 2024년 12월 "Building Effective Agents"에서 정리한 다섯 가지 워크플로 패턴이 실무에서 가장 널리 쓰인다. 프롬프트 체이닝(파이프라인), 라우팅, 병렬화(팬아웃·투표), 오케스트레이터-워커, 평가자-최적화(검증-후-적용)다. 다섯 패턴은 서로 대체 관계가 아니라, "작업 사이에 의존 관계가 있는가", "미리 하위 작업을 예측할 수 있는가", "검증이 필요한가"에 따라 골라 쓰거나 조합하는 도구 상자다.

• 프롬프트 체이닝 / 파이프라인(Prompt Chaining). 한 작업을 순서가 정해진 여러 단계로 쪼개고, 각 단계 사이에 검증 게이트를 둔다. 여러 항목을 동시에 흘려보내면 항목 간에는 서로 기다리지 않는 파이프라인이 된다. 항목 A가 3단계에 있는 동안 항목 B는 아직 1단계에 있을 수 있어 전체 처리량이 늘어난다.
  예: 공장의 조립 라인과 같다. 제품 A가 도색 단계를 지나는 동안 제품 B는 이미 조립 단계에 있다. 문서 3개를 "초안 작성 → 검토 → 교정" 3단계로 처리한다면, 문서 1이 검토 단계로 넘어가자마자 문서 2가 초안 작성을 시작할 수 있다.
• 라우팅(Routing). 들어온 요청을 먼저 분류한 뒤, 그 성격에 맞는 전문 에이전트나 모델로 갈라 보낸다. 5장에서 다루는 모델 티어링이 대표적인 예다. 쉬운 질문은 저비용 모델(haiku)로, 어렵고 드문 질문은 고성능 모델(opus)로 보내 비용과 품질의 균형을 맞춘다.
  예: 고객 문의가 들어오면 먼저 "단순 FAQ인가, 복잡한 기술 문의인가"를 분류하는 에이전트가 판단하고, 전자는 정형화된 응답 에이전트로, 후자는 더 깊이 조사할 수 있는 에이전트로 넘긴다.
• 병렬화(Parallelization). 두 갈래로 나뉜다. 섹셔닝(팬아웃)은 서로 독립적인 여러 하위 작업(예: 4가지 관점의 코드 리뷰)을 동시에 여러 에이전트에게 맡기고 결과를 한데 모은다. 소요 시간은 가장 느린 하나의 작업 시간에 수렴한다. 투표(Voting)는 반대로 같은 작업을 여러 에이전트에게 독립적으로 반복시킨 뒤 다수결이나 합의로 하나의 답을 고른다.
  섹셔닝 예: "이 코드를 성능·보안·가독성·테스트 커버리지 네 관점에서 동시에 리뷰해줘." 투표 예: 같은 버그 원인 분석을 세 에이전트에게 각각 독립적으로 시킨 뒤, 두 곳 이상이 같은 원인을 지목하면 그 결론을 채택한다. 한 에이전트의 착각을 다수결로 걸러낸다.
• 오케스트레이터-워커(Orchestrator-Workers). §3에서 설명한 팀 구조 자체가 이 패턴이다. 중앙의 오케스트레이터가 작업을 어떻게 쪼갤지 미리 정해 두지 않고, 입력을 보고 그때그때 동적으로 결정해 워커(스페셜리스트)에게 위임하고 결과를 종합한다. 하위 작업을 미리 예측할 수 없는 복잡한 작업(여러 파일에 걸친 코드 변경, 여러 출처를 종합해야 하는 리서치)에 특히 적합하다. §4b에서 다루는 "동적 팀 구성"이 바로 이 패턴의 다른 이름이다.
• 평가자-최적화 / 검증-후-적용(Evaluator-Optimizer). 한 에이전트가 초안을 만들면, 독립된 다른 에이전트(또는 여러 에이전트의 합의)가 그 초안을 반박·검증한 뒤에만 실제 반영한다. 그럴듯하지만 틀린 결과가 그대로 통과되는 것을 막는 장치다.
  예: 코드를 수정하기 전에 "이 수정이 정말 안전한가?"를 독립된 에이전트가 반박 관점에서 재검토하고, 문제가 없다고 판단될 때만 실제로 파일을 수정한다. 초안을 쓴 사람이 자기 글을 스스로 교정 보면 놓치는 오류를, 다른 사람이 검토하면 잡아내는 것과 같은 원리다. 다만 평가자 자신이 좋은 결과와 나쁜 결과를 구분하지 못하면 이 루프가 공회전할 수 있다는 한계도 있다.

실패했을 때 — 재시도·롤백·에스컬레이션

세 패턴 모두 "정상적으로 끝났을 때"를 전제로 설명했지만, 실무에서는 서브에이전트가 잘못된 결과를 내거나 아예 실패로 끝나는 일이 생긴다. 검증-후-적용은 "실행 전에 걸러내는" 장치인 반면, 이미 실행된 뒤에 문제를 발견했을 때 무엇을 할지는 별개의 문제다. 대표적으로 세 가지 대응이 있다.

• 재시도(Retry). 일시적 오류(네트워크 타임아웃, 도구 호출 실패 등)라면 같은 작업을 다시 시도한다. 다만 같은 프롬프트로 무한정 재시도하면 같은 실수를 반복할 뿐이므로, 보통 재시도 횟수에 상한을 둔다.
• 롤백(Rollback). 잘못된 결과가 이미 파일이나 저장소에 반영됐다면, 변경 이전 상태로 되돌린다. 3장에서 다룬 "쓰기 단계는 git으로 되돌릴 수 있는 범위"라는 원칙이 여기서 실제로 힘을 발휘한다. 커밋 단위로 작업이 쪼개져 있어야 롤백도 정확한 지점으로 되돌릴 수 있다.
• 에스컬레이션(Escalation). 재시도해도 반복 실패하거나, 애초에 오케스트레이터가 판단하기 애매한 상황이라면 사람에게 넘긴다. "3번 실패하면 자동 재시도를 멈추고 사람에게 보고한다" 같은 상한선을 미리 정해 두지 않으면, 실패한 작업을 계속 재시도하며 시간과 비용만 소모하는 상황이 생긴다.

동적 팀 구성과 다양한 워크플로우

지금까지 오케스트레이터·스페셜리스트·핸드오프·오케스트레이션 패턴을 각각 따로 설명했지만, 하네스 엔지니어링이 실제로 강력한 이유는 이 요소들이 고정된 하나의 조합으로 굳어 있지 않다는 데 있다. 재래식 자동화 스크립트는 "A 다음 B, 항상 B 다음 C"처럼 순서와 참여자가 코드에 하드코딩돼 있지만, 하네스로 짜인 멀티 에이전트팀은 오케스트레이터가 매 요청마다 "이번엔 누가 필요하고 어떤 순서로 움직일지"를 그때그때 다시 판단한다.

팀 구성은 고정돼 있지 않다

같은 팀이라도 요청의 성격에 따라 실제로 호출되는 스페셜리스트의 수와 조합이 달라진다. "오탈자만 고쳐줘"라는 간단한 요청에는 오케스트레이터가 reviewer 하나만 부르고 끝내지만, "새 기능을 설계부터 배포까지 진행해줘"라는 요청에는 architect·code-writer·test-runner·security-monitor·docs-writer까지 순서대로(또는 일부는 동시에) 소집한다. 팀 명단 자체(어떤 서브에이전트를 정의해 뒀는가)는 미리 고정돼 있어도, 그중 누가 실제로 이번 작업에 투입되는지는 매번 새로 결정된다. 마치 축구팀이 22명 전체 스쿼드는 고정이어도 이번 경기 선발 11명은 상대와 전술에 따라 매번 다르게 짜는 것과 같다.

이 유연성은 §3b에서 다룬 서브에이전트의 세 구현 방식과도 맞닿아 있다. 사전 정의 방식(Claude Code/App)에서도 "정의된 서브에이전트 중 무엇을 이번에 호출할지"는 오케스트레이터가 매번 동적으로 고르고, 동적 생성 방식(Antigravity)에서는 한 발 더 나아가 서브에이전트의 존재 자체가 그 순간 필요에 맞춰 즉석에서 만들어진다. 역할 컨텍스트 전환 방식(Codex)에서도 PM이 매 단계 필요한 역할을 골라 수행한다. 세 경우 모두 "팀 구성은 작업이 결정한다"는 원칙은 같다.

같은 하네스 위에서 다양한 워크플로우를 구현할 수 있다

하네스 엔지니어링이 정해 두는 것은 "오케스트레이터가 있고, 스페셜리스트를 부르고, 핸드오프로 정보를 넘긴다"는 뼈대뿐이다. 그 뼈대 위에 몇 단계짜리 파이프라인을 몇 명으로 구성할지는 도메인마다 완전히 다르게 설계할 수 있다. 5장에서 다룰 ai-workspace-standards의 variant들이 이를 실증한다. 같은 하네스 원리로 만들어졌는데도 co-develop은 PM·Architect·Designer·Code Writer·Test Runner·Security Monitor가 참여하는 6단계 거버넌스 파이프라인이고, co-design은 5단계 반복 워크플로우, co-deck은 11단계 워크플로우로 완전히 다른 모양을 하고 있다. 하나의 "정답 워크플로우"를 강요하지 않고, 도메인이 요구하는 단계 수·참여자·검증 강도에 맞춰 워크플로우 자체를 새로 설계할 수 있다는 것이 하네스 엔지니어링의 핵심 장점이다.

이는 §4의 다섯 오케스트레이션 패턴(프롬프트 체이닝·라우팅·병렬화·오케스트레이터-워커·평가자-최적화)이 서로 배타적이지 않고 한 워크플로우 안에서 자유롭게 조합될 수 있다는 뜻이기도 하다. 예를 들어 코드 리뷰 워크플로우는 먼저 라우팅으로 변경 규모가 작은지 큰지 분류하고, 큰 변경이면 오케스트레이터-워커가 영향받는 파일들을 동적으로 나눠 각각 팬아웃으로 네 관점을 동시에 검토한 뒤, 그 결과를 순서대로 파이프라인 처리하며 문서화하고, 마지막에는 평가자-최적화(검증-후-적용)로 실제 반영 여부를 결정하는 식으로 다섯 패턴을 한 흐름 안에 섞어 쓸 수 있다.

도구를 넘나드는 하네스 — AGENTS.md

지금까지 설명한 오케스트레이터·스페셜리스트·핸드오프는 특정 도구에 종속된 개념이 아니다. 문제는 그동안 도구마다 이 하네스를 설정하는 방식이 제각각이었다는 점이다. Claude Code는 CLAUDE.md를, Cursor는 .cursorrules를, GitHub Copilot은 .github/copilot-instructions.md를 읽는 식이어서, 여러 도구를 함께 쓰는 팀은 같은 내용을 파일마다 중복해서 유지해야 했다.

같은 내용(예: "테스트는 항상 npm test로 실행하고, src/legacy/ 폴더는 절대 수정하지 마라")을 팀원이 쓰는 도구 수만큼(CLAUDE.md, .cursorrules, copilot-instructions.md...) 복사해 두면, 규칙이 바뀔 때마다 파일을 전부 찾아 고쳐야 하고 하나라도 빠뜨리면 그 도구를 쓰는 사람만 다른 규칙으로 일하게 된다. 여러 나라 말로 같은 계약서를 따로따로 번역해 보관하다가, 한쪽만 조항을 고치는 바람에 버전이 어긋나는 것과 같은 문제다.

AGENTS.md는 이 문제를 풀기 위해 2025년 8월 OpenAI 주도로 Google·Cursor·Factory 등이 참여해 만든 개방형 표준이고, 2025년 12월 리눅스 재단 산하 Agentic AI Foundation에 기증됐다. 저장소 루트에 AGENTS.md 하나만 두면 Codex, Claude Code(가져오기 방식), GitHub Copilot, Cursor, Google Jules, Antigravity 계열을 포함해 30개가 넘는 도구가 세션 시작 시 이를 읽어 빌드·테스트 명령, 코드 스타일, 손대면 안 되는 영역 같은 공통 규칙을 공유한다.

이 핸드북이 계속 강조하는 "네 도구 모두 지원"이라는 원칙도 결국 같은 문제의식에서 나온다. 팀이 Claude Desktop App을 쓰든 Antigravity 데스크톱(Desktop)을 쓰든, 저장소 루트의 공유 규칙(AGENTS.md)과 도구별 세부 설정(CLAUDE.md, GEMINI.md 등)을 나눠 두면 도구를 바꾸거나 섞어 써도 하네스 자체는 흔들리지 않는다. 5장에서 살펴볼 ai-workspace-standards 저장소는 이 원칙을 실제로 구현한 사례다. 루트의 AGENTS.md 파일이 워크스페이스 전체 에이전트의 정본 목록(SSOT) 역할을 하고, .agents/ 폴더가 .claude/·.gemini/와 나란히 도구-불가지론적(engine-agnostic) 커맨드·스킬을 담는다.

다음 장으로 넘어가기 전에, 이 팀에게 실제로 도구를 쥐여 줄 때 지켜야 할 안전장치부터 짚어야 한다. 3장은 서브에이전트에게 무엇을 허용하고 무엇을 막을지, 사람이 반드시 확인해야 하는 지점은 어디인지를 다룬다. 그 뒤 4장에서 이 개념들을 실제로 Claude Desktop App/Antigravity 데스크톱(Desktop)을 중심으로 만들어 보면서(Claude Code·Antigravity CLI 절차도 함께), 오케스트레이터·스페셜리스트·핸드오프가 도구마다 어떻게 표현되는지 확인한다.