개념이 흐리면 지시도 흐려진다. 하네스·에이전트·스킬 — 이 세 단어와, 그 곁에 붙는 훅·센서·게이트·메모리·정본까지. 아홉 작업장에서 실제로 쓰이는 의미 그대로 정의한다.
§ 00 · 하네스 — 기계에 채우는 마구(馬具)
하네스(harness)는 원래 말에 채우는 마구다. 말의 힘을 죽이는 물건이 아니라, 그 힘을 마차에 연결해 방향을 갖게 만드는 물건. AI 하네스도 같다 — 모델의 능력 주위에 두르는 규칙·권한·검증·기록의 틀이다. 루비얀카 시리즈에서 이미 한 번 쓴 등식을 다시 꺼낸다. 에이전트 = 모델 + 하네스. 모델은 빌려 쓰는 두뇌라 내가 바꿀 수 없지만, 하네스는 전부 내 손안에 있다.
이 말을 만든 개발자의 정의는 뜻밖에 소박하다 — 기계가 실수를 저지를 때마다, 같은 실수를 두 번 다시 저지르지 못하게 하는 장치를 그때그때 하나씩 짓는 일. 그 장치들은 네 갈래로 정리된다. 할 수 있는 일을 줄이고(제한), 해야 할 일을 알려주고(정보), 제대로 했는지 확인하고(검증), 틀렸을 때 바로잡는다(교정). 이 교본의 모든 부품은 이 네 기둥 중 어딘가에 속한다.
실체는 소박하다. 저장소 안의 폴더 하나와 문서 몇 개. 관례상 루트에 헌법 문서(CLAUDE.md — 매 세션 자동으로 읽히는 규칙서) 하나, 그리고 숨김 폴더(.claude/) 아래에 일꾼 정의(agents/), 절차서(skills/), 자동 실행 스크립트(scripts/), 배선표(settings.json)가 들어간다. 전부 텍스트 파일이다. 열어서 읽을 수 있고, 고칠 수 있고, 지울 수 있다.
왜 하필 파일인가. 채팅 지시는 세션이 끝나면 증발하지만 파일은 남기 때문이다. 헌법 문서는 새 세션이 열릴 때마다 자동으로 기계의 눈앞에 놓인다. 같은 규칙이 백 번의 세션에 백 번 반복된다 — 사람이 백 번 타이핑하지 않고도. 하네스 엔지니어링의 첫 원리는 그래서 이렇게 요약된다. 한 번만 말하고 싶은 것은, 말하지 말고 적어라.
§ 01 · 에이전트 — 역할과 권한을 쪼갠 일꾼
에이전트는 특정 역할을 맡는 별도의 일꾼이다. 실체는 역시 파일 — 마크다운 문서 하나가 일꾼 하나다. 파일 머리(frontmatter)에 네 가지를 적는다. 이름(name), 언제 이 일꾼을 부르는지(description), 이 일꾼에게 쥐여줄 도구 목록(tools), 이 일꾼이 쓸 모델(model). 본문에는 역할과 금지사항을 적는다.
감이 안 오면 사고 실험 하나. 아이폰 앱, 안드로이드 앱, 웹, 서버 — 네 갈래로 이루어진 서비스를 채팅 창구 하나로 전부 진행시킨다고 치자. 장담하는데 기계는 셋 중 하나를 한다. 작업을 까먹거나, 엉뚱한 곳을 고치거나, 허위 보고를 하거나. 기계에게는 유능한 비서인 척하려는 성격이 바닥에 깔려 있다 — 일을 실패했다고 처음부터 자백하면 무능한 비서가 되므로, 거짓말하기를 택하는 것이다. 그래서 사람의 조직이 하는 그대로 한다. 노점상과 1인 기업을 빼면, 어느 회사도 한 사람에게 모든 일을 맡기지 않는다. 직원을 뽑고, 분업을 시키고, 검사는 다른 부서에 준다. 에이전트를 만든다는 것은 그 채용이다.
넷 중 가장 중요한 칸은 도구 목록이다. 도구 목록이 곧 권한이기 때문이다. 실측한 작업장들에서 가장 아름다운 설계가 여기 있었다 — 검증 전담 일꾼에게서 수정 도구(Edit·Write)를 아예 빼 버린 것. 읽기와 실행만 가능한 검사관은 “몰래 고쳐 놓고 통과시켰다고 보고하는” 부정을 저지르고 싶어도 저지를 수 없다. 규칙으로 금지하는 것이 아니라 구조로 불가능하게 만드는 것. 이 교본 전체를 관통하는 원칙이다.
구성의 전형도 실측에서 반복된다. 기획자(명세만 쓰고 코드 금지), 구현자(승인된 명세가 있을 때만 작업), 검증자(코드 수정 금지, 보고만), 그리고 도메인 수호자(시각 정본 지킴이, 비용 회계사 같은). 핵심은 머릿수가 아니라 분리다 — 계획하는 손, 만드는 손, 검사하는 손이 서로 다른 파일, 다른 권한으로 떨어져 있다는 것.
§ 02 · 스킬 — 절차를 파일로 고정한 것
스킬은 반복되는 절차를 문서로 고정한 것이다. 폴더 하나에 SKILL.md 파일 하나 — 머리에 이름과 “언제 발동하는가”를 적고, 본문에 단계별 절차와 금지사항을 적는다. 에이전트가 “누가 하느냐”라면 스킬은 “어떤 순서로 하느냐”다.
회사 비유를 이어가자. 채용이 에이전트라면, 스킬은 그 회사의 업무 수칙집이다. 신입이 들어와도 보고서 품질이 유지되는 회사는 사람이 아니라 절차서가 일하는 회사다. 실제 발동 장면은 이렇다 — 기계가 “다 했습니다”라고 치는 순간, 바로 그 말버릇이 방아쇠가 되어 절차서가 끼어든다. 빌드는 돌렸는가. 출력은 붙였는가. 어제 결과를 오늘 증거로 쓰지 않았는가. 세 칸을 채우기 전에는 완료라는 단어를 마칠 수 없다. 스킬의 본질은 이 성격 교정이다 — 기계는 완료라고 답하도록 길들여져 있고, 말버릇 자체는 고칠 수 없으니, 말버릇이 나오는 길목에 검문을 세운다.
“그 정도는 알아서 하지 않나”라는 생각이 들면 조종석을 떠올려라. 비행시간 2만 시간의 기장도 이륙 전에는 점검표를 소리 내어 읽는다. 점검표는 조종사의 숙련을 의심해서 있는 게 아니라, 숙련조차 빠뜨리는 날이 있음을 알아서 있는 것이다. 스킬도 같다 — 그리고 이 절차서 한 부의 실체는 열 줄짜리 텍스트 파일이다. 이름 한 줄, 방아쇠 어구 몇 개(“다 했습니다”, “전부 통과”), 그리고 체크 세 줄. 그게 전부다.
아홉 작업장에서 가장 자주 이식된 스킬 네 가지가 사실상의 표준이다. 하나, 완료 선언 게이트 — “다 했습니다”라고 말하기 직전에 발동해 실측 증거를 요구한다. 둘, 체계적 디버깅 — 버그 앞에서 추측 수정을 금지하고 재현·격리·가설검증 순서를 강제한다. 셋, 조율 판단 — 이 일을 직접 할지 일꾼에게 위임할지를 기준표로 가른다. 넷, 도메인 검사 — 그 작업장 고유의 화면·정책·정합을 재는 절차다.
그리고 실제 작업장들을 열어 보면 수칙집에는 담당 부서가 적혀 있다. 완료 선언 게이트의 표지에는 “담당: 검수관”, 배포 절차서의 표지에는 “담당: 인프라 일꾼” — 아무나 집어 드는 공용 수칙도 있지만, 대부분의 절차서는 그 절차를 맡은 일꾼의 책상에 놓인다. 에이전트가 채용이고 스킬이 절차서라면, 좋은 하네스는 절차서마다 주인이 정해진 회사다.
§ 03 · 나머지 부품들 — 훅·센서·게이트·메모리·정본
훅(hook)은 정해진 순간마다 자동으로 도는 스크립트다. 세션이 열릴 때, 사용자가 프롬프트를 보낼 때, 기계가 파일을 고친 직후, 세션이 닫힐 때 — 이런 순간들에 배선해 둔 스크립트가 사람 손 없이 실행된다. 실측된 훅의 절대다수는 차단하지 않는다. 경고문을 화면에 흘려 넣을 뿐이다. 세게 무는 것은 다음 두 부품의 몫이다.
센서(sensor)는 상태를 재는 계기다. 타입 검사·테스트·빌드를 실제로 돌리고, 결과를 말이 아니라 숫자 — 종료 코드(exit code) 0이면 통과, 아니면 실패 — 로 내놓는다. 게이트(gate)는 그 숫자로 길을 막는 검문소다. 대표가 git 훅 — 커밋 직전, 푸시 직전에 센서를 돌려 실패하면 커밋 자체가 거부된다. 기계가 아무리 “문제없습니다”라고 말해도 게이트는 문장을 읽지 않는다. 숫자만 읽는다.
메모리는 세션 사이의 기억이다. 세션이 끝날 때 오늘 한 일과 결정을 파일로 적어 두면, 다음 세션이 그 파일을 읽고 이어받는다. 정본(canon)은 “한 사실은 한 곳에만 적는다”는 규칙이다 — 같은 사실이 세 문서에 적히면 반드시 서로 어긋나기 시작하고(실측으로 확인된 부패다), 어긋난 문서는 기계를 오도한다. 각 부품을 실제로 만드는 법은 02편과 04편에서 다룬다.
§ 04 · 왜 전부 한꺼번에 로드되지 않는가
오해 하나를 바로잡고 이 사전을 닫는다. 일을 시키는 순간 에이전트 전원과 스킬 전부가 기계의 머릿속에 로드된다 — 그렇게 상상하기 쉽지만, 그렇지 않고, 그래서도 안 된다. 평소 기계 앞에 놓이는 것은 목록뿐이다. 일꾼들의 이름과 한 줄 설명, 절차서들의 이름과 한 줄 설명. 본문 전체는 그 일꾼을 실제로 소환하는 순간, 그 절차서가 실제로 발동하는 순간에만 펼쳐진다. 서재를 떠올리면 된다 — 책은 서가에 꽂혀 있고, 책상 위에는 지금 읽는 한 권만 올라온다.
왜 그래야 하는가. 첫째, 주의력 때문이다. 기계가 한 번에 소화하는 지시의 양에는 한계가 있다 — 규칙이 열 개면 대부분 지키지만, 백 개면 무엇이 중요한지 판단하지 못한다는 것은 이미 측정된 사실이다. 배포 절차서, 디버깅 수칙, 시각 검사 목록이 지금 하는 번역 작업과 무관하게 전부 펼쳐져 있으면, 그 더미가 정작 중요한 한 줄을 묻어버린다. 책상 위의 책이 많을수록 지금 읽는 문장에 가는 눈은 흐려진다.
둘째, 비용 때문이다. 기계 앞에 놓이는 글자는 전부 요금이 매겨진다 — 매번, 다시. 세션의 턴마다 쓰지도 않을 절차서 서른 부를 통째로 다시 올리는 것은, 회의 때마다 전 직원의 업무 매뉴얼을 전부 복사해 나눠주는 회사와 같다. 셋째, 격리 때문이다. 일꾼이 자료를 뒤지며 만든 수만 줄의 중간 출력은 그 일꾼의 책상에서 끝나고, 본진 대화에는 요약 한 장만 돌아온다. 전부가 한 책상을 쓰면 이 방화벽이 사라진다.
실무 함의는 두 가지다. 하나 — 목록에 남는 “한 줄 설명”이 사실상 호출 버튼이다. 기계는 그 한 줄만 보고 부를지 말지를 정하므로, 설명은 “유용한 도우미” 같은 덕담이 아니라 “완료 선언을 검증할 때, 코드는 안 고치고 판정만”처럼 발동 조건이 읽히게 써야 한다. 둘 — 반드시 발동해야 하는 절차(완료 선언 게이트 같은)는 기계의 판단에만 맡기지 마라. 목록에서 골라 읽는 구조는 안 고를 자유도 준다는 뜻이므로, 놓치면 안 되는 절차에는 04편의 방아쇠 — 말버릇을 낚아채는 훅 — 를 따로 단다.
Read this note at sass.studio.