이 교본은 루비얀카 방법론의 한 갈래다. 방법론은 궁극적으로 하네스·에이전트·스킬은 물론 프로젝트의 뼈대 세우기(스캐폴딩)와 라이브러리 구성까지 포괄하는 독자적인 개발 방법론을 향해 준비되고 있고, 이 교본은 그중 “기계를 결박하는 층위”를 먼저 꺼내 놓은 것이다. 한 사람이 굴리는 아홉 개의 작업장(프로젝트)을 전부 실측한 뒤에 썼다. 독자는 지금까지 채팅으로만 AI에게 일을 시켜 본 사람 — 그리고 “다 됐습니다”라는 말에 한 번이라도 데어 본 사람이다.
§ 00 · 채팅으로만 시킬 때 벌어지는 일
장면은 익숙하다. 채팅창에 지시를 적는다. “이 버튼 위치를 고쳐줘.” 잠시 뒤 기계가 답한다. “수정을 완료했습니다.” 화면을 열어 본다. 버튼은 그대로다. 따져 물으면 기계는 사과하고, 또 “완료했습니다”라고 말하고, 버튼은 또 그대로다. 지시는 무시되고, 보고는 거짓이 되고, 저녁이 사라진다.
이 반복의 뿌리는 기계의 성격이 아니라 구조다. 채팅으로 준 지시는 그 대화가 끝나는 순간 증발한다. 다음 세션의 기계는 어제의 약속을 모른다. “완료라고 말하기 전에 꼭 확인해”라는 다짐도, 그 대화 안에서만 유효한 1회용 각서다. 약속이 반복되지 않으니 위반도 반복된다. 그리고 검사를 강제하는 장치가 없으니, 기계는 검사 없이 완료를 선언한다.
해법의 방향은 하나다. 지시를 채팅이 아니라 파일에 적는다. 검사를 부탁이 아니라 스크립트로 만든다. 통과 여부를 기계의 말이 아니라 실행 결과 숫자(exit code)로 판정한다. 이 세 가지를 저장소 안에 상설로 박아 두는 일 — 그것이 이 교본이 다루는 하네스 엔지니어링의 전부다.
이것이 취미가의 결벽이 아니라 업계의 결론이라는 증거가 있다. 한 코딩 벤치마크에서 어느 팀이 모델을 한 글자도 바꾸지 않고 주변 장치만 바꿔 점수를 52.8에서 66.5로, 순위를 30위에서 5위로 끌어올렸다. 같은 두뇌, 다른 마구. 성과를 결정한 것은 모델이 아니라 하네스였다.
§ 01 · 아홉 개의 작업장
이 교본은 이론서가 아니라 실측 보고서다. 한 사람이 굴려 온 아홉 개 안팎의 작업장 — 세 개의 저장소로 이루어진 결제 서비스, 가계부, 매칭 서비스, 게임, 이미지 공방, 쇼핑몰, 내부 운영 도구 몇, 그리고 이 사이트 — 의 하네스를 폴더 단위로 전부 열어 세어 보고 썼다. 이 글에서 작업장들은 전부 익명이다. 중요한 것은 이름이 아니라 반복되는 패턴이니까.
크기는 극단적으로 다르다. 가장 큰 작업장은 일꾼(에이전트) 정의가 열 개, 절차서(스킬)가 스물여섯 개, 검증 스크립트가 여든한 개, 그중 센서만 쉰일곱 개다. 가장 작은 작업장은 훅 하나가 전부다. 그리고 어느 작업장은 “일꾼 0개”를 실수가 아니라 결정으로 문서에 박아 두었다. 하네스는 클수록 좋은 것이 아니라, 작업장의 위험 크기에 맞을수록 좋은 것이다.
크기가 달라도 부품은 반복된다. “완료를 선언하기 전에 실측하라”는 절차서가 거의 모든 작업장에 이식되어 있고, 세션의 기억을 지키는 훅 묶음이 거의 같은 모양으로 복제되어 있고, 스크립트 머리마다 “어느 작업장에서 가져왔다”는 출처가 적혀 있다. 표준 부품이 이미 존재한다는 뜻이다. 이 교본은 그 부품들의 조립 설명서다.
§ 02 · 읽는 법
순서대로 읽으면 된다. 01편은 용어 사전이다 — 하네스, 에이전트, 스킬이 무엇인지 이름부터 정리한다. 02편은 그것을 손으로 만드는 법이다 — 파일 다섯 개로 최소 하네스를 세운다. 03편은 같은 일을 클로드에게 시켜서 만드는 법이다. 04편은 이 교본의 심장인 센서와 게이트 — 거짓 완료 보고를 구조로 막는 장치들이다. 05편은 모델 배치 — 왜 모든 일에 최고급 모델을 쓰면 안 되는지를 다룬다.
전제는 하나뿐이다. 코드를 잘 몰라도 좋다. 폴더를 만들고, 텍스트 파일에 글을 쓸 수 있으면 시작할 수 있다. 실제로 하네스의 부품 대부분은 코드가 아니라 문서다 — 규칙을 적은 문서, 역할을 적은 문서, 절차를 적은 문서. 코드가 필요한 자리는 03편의 방법으로 기계에게 시키면 된다.
한 줄로 요약하고 시작한다. 이 교본의 목표는 기계를 신뢰하는 것이 아니다. 신뢰 없이도 일이 돌아가게 만드는 것이다. 신뢰는 사람 사이의 미덕이고, 기계에게 필요한 것은 증거다.
Read this note at sass.studio.