하네스도 결국 파일과 스크립트다 — 그러니 그 제작을 클로드에게 시킬 수 있다. 단, 순서가 있다. 실측시키고, 제안받고, 승인하고, 그다음에 만들게 한다. 바로 쓸 수 있는 주문 예문과 함께.
§ 00 · 하네스도 코드다
02편의 파일 다섯 개를 손으로 만들 필요는 없다. 하네스의 부품은 결국 텍스트 파일과 셸 스크립트고, 그것을 만드는 일이야말로 기계가 잘하는 일이다. 실측한 작업장들의 하네스도 대부분 그렇게 만들어졌다 — 사람이 방향을 정하고, 기계가 파일을 짓고, 사람이 검수했다.
단, 순서가 생명이다. 다짜고짜 “하네스 만들어줘”라고 하면 기계는 어딘가에서 본 그럴듯한 틀을 상상으로 지어낸다. 뇌피셜 하네스는 뇌피셜 코드보다 위험하다 — 코드의 버그는 그 기능 하나를 망가뜨리지만, 규칙의 버그는 앞으로의 모든 세션을 오도한다. 정량 근거도 있다. 기계가 통째로 자동 생성한 규칙서는 성능을 되레 3% 낮췄다는 측정이 있다 — “코드를 깔끔하게 유지하세요” 같은 일반론만 담겨, 자리만 차지하고 신호는 없기 때문이다. 좋은 규칙은 이 저장소의 실패 경험에서 뽑아낸 것뿐이다. 그래서 순서는 반드시 이렇다. 먼저 실측시킨다(이 저장소에 무엇이 있는지). 다음 제안받는다(파일은 아직 만들지 말고 표로). 사람이 승인한다. 그다음에야 만들게 한다.
이 순서는 이 교본 자체의 제작 과정이기도 하다 — 아홉 작업장을 먼저 실측시키고, 그 보고를 근거로 쓰게 했다. 실측 없는 주장을 금지하는 규율은 하네스를 만드는 일에도 똑같이 적용된다. 아니, 거기에 가장 먼저 적용되어야 한다.
§ 01 · 주문 예문
첫 구축. “이 저장소의 구조와 위험 지점을 실측해라. 그 근거로 ① 헌법 문서(CLAUDE.md) 60줄 초안 ② 에이전트 로스터 — 역할·쥐여줄 도구·뺄 도구·모델 등급 — 를 제안해라. 파일은 아직 만들지 말고 표로만 보여라.” 핵심은 마지막 문장이다. 제안과 실행을 분리하면 검수할 자리가 생긴다.
검증 게이트. “완료 선언 전에 타입 검사·테스트·빌드를 강제하는 스킬을 만들고, 푸시 직전에 같은 3단을 돌려 실패 시 차단하는 git 훅을 만들어라. 만든 뒤 일부러 타입 에러를 하나 넣어서, 훅이 실제로 푸시를 거부하는지 실측해 그 출력을 보여라.” 방금 만든 안전장치를 그 자리에서 시험 격발까지 시키는 것 — 여러 작업장에서 “만들어졌지만 한 번도 발동한 적 없는 장치”가 발견된 뒤 생긴 규율이다.
이식. “저 프로젝트의 완료 검증 스킬을 이 저장소 사정에 맞게 이식해라. 파일 머리 주석에 원본 출처와 무엇을 바꿨는지를 남겨라.” 실측한 작업장들의 스크립트 머리마다 실제로 이런 출처 표기가 있다 — 검증된 부품의 계보가 이어지는 방식이다.
그리고 모든 주문의 공통 꼬리표. “만들었다고 보고하지 말고, 동작을 실측한 출력을 붙여라.” 이 한 문장이 주문의 절반이다.
§ 02 · 승인은 넘기지 않는다
하네스 제작을 위임해도, 위임하면 안 되는 것이 하나 남는다. 승인이다. 실측한 가장 큰 작업장은 이것을 구조로 박아 두었다 — 기계가 하네스 폴더를 직접 고치려 들면 훅이 차단하고 전담 일꾼에게 위임을 강제하며, 규칙 문서의 갱신은 제안서 폴더를 거쳐 사용자 승인 없이는 반영되지 않는다. 우리를 짓는 것은 짐승이어도 된다. 우리의 열쇠는 사람이 쥔다.
초보자를 위한 검수법은 거창하지 않다. 만들어진 파일을 직접 연다. 처음부터 끝까지 읽는다. 이해되지 않는 줄이 있으면 그 줄을 붙여 넣고 묻는다 — “이 줄이 무슨 일을 하나. 이 줄이 없으면 무슨 일이 벌어지나.” 대답이 석연치 않으면 지우게 한다. 읽고 이해한 규칙만이 네 규칙이다. 이해하지 못한 규칙은 기계의 규칙이고, 그것은 하네스가 아니라 장식이다.
분량에도 승인이 필요하다. 기계에게 시키면 하네스는 쉽게 비대해진다 — 일꾼 열 명, 스킬 서른 개를 하루에 뽑아내는 것쯤 일도 아니니까. 실측의 교훈은 반대 방향을 가리킨다. 작게 시작해서, 사고가 날 때마다 하나씩 늘려라. 04편에서 보겠지만, 좋은 하네스의 부품들은 대부분 실제 사고의 흉터다. 흉터 없이 자란 하네스는 몸에 맞지 않는다.
§ 03 · 크기는 위험에 맞춘다 — 부재도 설계다
아홉 작업장의 하네스 크기는 위험의 크기를 따라간다. 돈이 오가는 결제 서비스 작업장은 센서만 쉰일곱 개 — 결제 멱등성, 환불 원자성, 비밀 누출까지 전부 계기가 붙어 있다. 반면 정적인 홍보 사이트 작업장은 “파일 수정 직후 타입 검사” 훅 하나가 하네스의 전부다. 둘 다 옳다. 하네스의 비용은 실재한다 — 검문이 많을수록 커밋 한 번이 느려진다. 위험이 작은 곳의 과잉 하네스는 안전이 아니라 마찰이다.
가장 인상적인 실측은 어느 내부 도구 작업장의 문서 한 줄이다 — “에이전트 0개, 훅 0개. 의도적 제거. 사용자 결정.” 부품이 없는 것과, 없기로 결정하고 그 사실을 적어 둔 것은 완전히 다르다. 후자는 다음 세션의 기계가 “왜 여긴 에이전트가 없지? 만들어야겠다”라고 오판하는 것까지 막는다. 부재를 문서화하는 것 — 그것도 하네스다.
그러니 시작 크기는 이렇게 정하라. 이 저장소가 망가뜨릴 수 있는 가장 비싼 것이 무엇인가. 돈인가, 평판인가, 저녁 시간인가. 그 답의 크기만큼만 만들고, 나머지는 사고가 청구서를 들고 올 때 증축하라.
Read this note at sass.studio.