한빛미디어

▶ 이전 글: 에이전트가 무너지는 네 가지 패턴 | 하네스 엔지니어링의 등장 배경

앞선 편에서는 에이전트의 성패를 가르는 것이 모델이 아니라 모델을 둘러싼 환경, 즉 하네스라는 점을 확인했습니다. 이제 하네스가 실제로 무엇으로 이루어지는지 들여다보려고 합니다. 하네스를 이루는 일곱 가지 구성요소를 핵심 요소 4가지와 전술 요소 3가지로 나누어 살펴보고, 도구가 기본으로 제공하는 이너 하네스와 사용자가 직접 설계해야 하는 아우터 하네스를 구분한 뒤, 아우터 하네스를 만드는 스펙 주도 개발(SDD)과 피해야 할 안티 패턴까지 알아보겠습니다.

하네스를 이루는 7가지 구성요소

하네스는 총 7가지 구성요소로 나눌 수 있습니다. 실행 환경의 기반을 이루는 핵심 요소 4가지와, 그 위에서 운영의 안정성과 효율을 높이는 전술 요소 3가지입니다. 이 요소들은 하네스를 점검하기 위한 프레임으로, 실제 시스템에서는 업무 특성, 모델 능력, 사용 도구에 따라 일부 요소를 생략하거나 하나의 기능으로 통합할 수 있습니다.

핵심 요소 4가지는 에이전트가 실행되는 시점에 직접 영향을 미칩니다.

네 요소는 서로 독립적으로 동작하지 않고 하나의 작업 흐름 안에서 연결되어 움직입니다. 사용자가 "지난주 회의록 5개를 정리해주세요"라고 요청하면 시스템 프롬프트는 역할과 출력 형식을 정의하고, 도구는 실제로 파일을 읽고, 메모리는 회사 약어나 이전 작업 상태 같은 배경 정보를 제공하며, 필요하다면 서브 에이전트가 작업을 나누어 처리합니다. 네 요소 가운데 하나라도 부족하거나 불명확하면 전체 흐름이 어긋날 수 있습니다.

전술 요소 3가지는 핵심 구조가 갖춰져 있을 때 의미가 있는 보조 장치입니다.

훅은 도구 호출 과정의 특정 지점에 미리 정한 동작을 삽입하는 기능입니다. 모델 출력과 관계없이 정해진 시점에 정해진 코드가 항상 같은 방식으로 실행되어 결과를 검사하거나 후처리합니다. 가장 자주 사용되는 지점은 두 곳입니다.

• PreToolUse Hook: 도구 호출 직전에 실행합니다. 사용자 승인, 비공개 정보 검출, 비용 한도 점검처럼 위험한 동작을 사전 차단합니다.
• PostToolUse Hook: 도구 호출 직후에 실행합니다. 결과 검증, lint·type 확인, 단위 테스트처럼 작업 후 검증을 담당합니다.

이 구조에서 자주 등장하는 가드레일과 피드백 루프는 모두 훅을 활용한 방식입니다. 행동 전에 차단하면 가드레일, 행동 후 결과를 검사해 다시 시도하게 만들면 피드백 루프입니다. 훅은 항상 같은 방식으로 동작하므로 yes/no 검증, 파일 변환, 비용 제한, 자동 테스트처럼 일관성이 중요한 작업에 적합합니다. 반대로 어떤 액션 아이템을 고를지, 어떤 문체로 작성할지처럼 모델의 판단이 필요한 부분까지 훅으로 고정하면 결과가 지나치게 경직됩니다.

스킬은 회의록 정리, 이메일 초안 작성, 계약서 검토처럼 특정 작업을 안정적으로 수행하는 데 필요한 지침, 예시, 참조 자료를 하나로 묶어둔 지식 모듈입니다. 중심에는 SKILL.md 파일이 있고, 필요에 따라 references/, examples/ 같은 폴더를 함께 둡니다. 모든 작업 노하우를 하나의 시스템 프롬프트에 넣는 대신 작업마다 스킬을 만들어두면, 모델은 현재 작업에 필요한 정보만 선택적으로 읽을 수 있습니다.

스펙은 무엇을 만들고 어떻게 검증할지 미리 정의한 설계 문서입니다. 시스템 프롬프트, 훅, 스킬이 에이전트가 실행되는 과정에서 사용된다면, 스펙은 그보다 앞선 설계 단계에서 작성된다는 점이 다릅니다. 구현이 끝난 뒤 스펙을 작성하면 스펙이 코드에 끌려다니게 되고, 도구가 바뀌면 처음부터 다시 정리해야 합니다. 스펙은 코드의 결과가 아니라 기준이어야 합니다. 

좋은 스펙은 보통 ①outcomes(무엇을 만들 것인가), ②scope boundaries(어디까지 다룰 것인가), ③constraints(어떤 제약 안에서 동작할 것인가), ④prior decisions(이미 결정된 사항), ⑤task breakdown(작업을 어떻게 나눌 것인가), ⑥verification criteria(어떤 기준으로 합격 여부를 판단할 것인가)의 여섯 가지로 구성됩니다.

이너 하네스와 아우터 하네스

일곱 가지 구성요소 가운데 몇 가지는 도구 회사가 이미 제공하지만, 어떤 부분은 사용자가 직접 설계해야 합니다. 이 구분으로 이너 하네스(Inner Harness)와 아우터 하네스(Outer Harness)의 역할을 이해할 수 있습니다.

클로드 코드(Claude Code)를 예로 들면 Read·Write·Bash 같은 기본 도구, MCP 기반 외부 연결, 사용자 승인 워크플로, 컨텍스트 자동 압축, 토큰 추적, 오류 처리가 기본 제공됩니다. Task 도구로 컨텍스트를 분리한 서브 에이전트 실행과 작업 성격에 따른 모델 자동 선택도 지원됩니다. 이처럼 도구 안에 기본적으로 포함되어, 사용자가 별도로 구현하지 않아도 바로 활용할 수 있는 기능을 이너 하네스라고 합니다.

그렇다면 이너 하네스가 발전할수록 사용자가 직접 만드는 아우터 하네스의 역할은 줄어들까요? 그렇지 않습니다. 도구 회사가 대신 만들어줄 수 없는 영역이 분명히 존재하기 때문입니다.

같은 도구나 모델을 쓰더라도 조직의 문서 형식, 작업 절차, 평가 기준을 환경에 정의해둔 팀과 그렇지 않은 팀의 결과 품질은 다를 수밖에 없습니다. 이너 하네스는 누구나 비슷하게 쓰지만 아우터 하네스는 각자의 환경에 맞게 직접 설계해야 하므로, 결국 경쟁력은 아우터 하네스에서 나옵니다.

아우터 하네스 만들기: 스펙 주도 개발과 안티 패턴

아우터 하네스를 만드는 대표적인 방법이 스펙 주도 개발(Spec-Driven Development, SDD)입니다. SDD는 2025년 말을 지나며 AI 에이전트 개발에서 사실상 표준으로 자리 잡았으며, 핵심은 다음 두 가지입니다.

• 코드가 아니라 스펙(명세)을 기준으로 합니다.
• 사람은 스펙을 작성하고, 도구는 그 스펙을 바탕으로 코드를 생성합니다.

사용자가 마크다운으로 스펙을 작성하면 에이전트가 이를 코드와 실행 환경으로 구현하고, 운영 결과를 다시 스펙에 반영합니다. 이 아이디어는 깃허브의 Spec Kit, AWS의 Kiro IDE, 앤트로픽의 CLAUDE.md, 오픈AI 코덱스 등이 함께 만든 AGENTS.md, 커서의 .cursor/rules/*.mdc처럼 여러 도구에서 비슷한 형태로 등장했습니다.

SDD가 해결하려는 문제는 크게 두 가지입니다. 첫째는 개발 의도가 코드 속에 묻히는 문제입니다. 코드가 기준이 되면 시간이 지날수록 원래 의도가 코드 속에 묻히지만, SDD는 스펙을 짧고 분리된 마크다운으로 유지해 전체 의도를 한눈에 파악할 수 있게 합니다. 둘째는 특정 도구에 의존하는 문제입니다. 스펙은 도구와 분리되어 있으므로 다른 도구에서도 활용할 수 있고, 사용자의 자산이 특정 도구에 묶이지 않습니다.

따라서 한 도구에서 작성한 스펙 파일(specs/*.md)은 다른 도구에서도 활용할 수 있습니다. 다만 도구마다 진입점 파일과 적용 방식이 조금씩 다르므로, 다른 도구에서 사용할 때는 그 차이만 이해해두면 됩니다.

미첼 하시모토(Mitchell Hashimoto)의 AGENTS.md는 SDD가 실제로 축적되는 모습을 보여주는 사례입니다. 그는 에이전트가 실수할 때마다 프로젝트 루트의 AGENTS.md에 다음과 같은 규칙을 추가했습니다.

• 테스트가 실패하더라도 테스트를 삭제하지 말 것
• 새로운 의존성은 별도 PR로 추가할 것
• any 타입을 추가하지 말고, 모르면 사용자에게 질문할 것

각 규칙은 단순해 보이지만 실제 작업에서 발생한 실패를 바탕으로 만들어졌습니다. 이런 규칙이 쌓일수록 같은 유형의 오류가 반복될 가능성은 줄어듭니다. 결국 AGENTS.md는 해당 프로젝트에서 에이전트가 따라야 할 운영 원칙을 담은 아우터 하네스가 됩니다.

아우터 하네스를 만들 때 가장 흔한 함정은 처음부터 완성된 시스템을 한 번에 만들려는 것입니다. 좋은 아우터 하네스는 거대한 설계에서 시작하지 않습니다. 작은 규칙 한 줄에서 출발해 운영 과정에서 조금씩 발전합니다. 아우터 하네스를 만드는 과정을 방해하는 흔한 실수는 다음과 같습니다.

이 문제들의 해결 방향은 같습니다. 작게 시작하고, 실제 실패에서 배우고, 특정 도구에 묶이지 않는 형태로 유지하는 것입니다. 그러면 처음에는 커서로 시작했다가 몇 달 뒤 클로드 코드로 옮겨도, 그동안 만든 시스템 프롬프트나 검증 기준, 스킬, 실패 회피 규칙 등이 대부분 그대로 따라갑니다. 도구는 바뀌어도 사용자가 만든 환경은 누적되는 것입니다.

아우터 하네스는 한 번에 완성되지 않습니다. 시스템 프롬프트 한 줄로 시작해 출력 형식 규칙, 훅 정책, 스킬, 검증 기준이 하나씩 쌓이다 보면 어느 순간 처음과는 전혀 다른 수준의 실행 환경이 만들어집니다. 그 사이 모델은 계속 바뀌지만, 환경을 직접 만든 사람은 쌓아둔 환경 위에 새 모델만 교체하면 됩니다. 결국 시간이 지날수록 차이를 만드는 것은 특정 모델을 사용했다는 사실이 아닙니다. 실제 업무에서 얻은 경험을 규칙, 지식, 절차와 검증 기준으로 얼마나 잘 축적했는지가 더 중요합니다.

위 컨텐츠는 서지영 저자의
『하네스 엔지니어링, 클로드 코드로 내 일을 대신하는 AI 에이전트 만들기』를 재구성하여 작성되었습니다.