제대로된 하네스 엔지니어링— AI 100x 생산성을 만드는 5가지 핵심 개념

Steve Yegge가 한 말이 있어요. "AI 코딩 에이전트를 제대로 쓰는 사람은 Cursor와 챗으로 일하는 엔지니어보다 10배에서 100배 더 생산적이고, 2005년 구글러보다는 약 1000배 더 생산적이다."

처음 들으면 과장 같지만, 이걸 직접 경험한 YC CEO 개리 탄(Garry Tan)이 정면으로 답합니다. 2배 쓰는 사람과 100배 쓰는 사람은 같은 모델을 쓰고 있다는 거예요. 차이는 모델이 아니라 모델을 감싸는 아키텍처에 있습니다. 그리고 그 아키텍처는 인덱스 카드 한 장에 다 들어갑니다.

핵심 슬로건은 이거예요. Thin Harness, Fat Skills (얇은 하네스, 두꺼운 스킬).

ALT

얇은 하네스, 뚱뚱한 기술

이 글에서는 개리 탄이 제시한 5가지 핵심 정의를 하나씩 정리하고, 지피터스 멤버분들이 지금 쓰고 계신 Claude Code 스킬 시스템에 어떻게 적용할 수 있는지 짚어봅니다. 한국에서 이미 "하네스 엔지니어링"이라는 키워드가 패스트캠퍼스 강의로까지 나올 정도로 핫한데, 이 글은 거기서 한 단계 더 들어갑니다.

이 글을 읽으면

내가 만든 Claude Code 스킬을 얇은 하네스 + 두꺼운 스킬 구조로 재설계하는 5가지 기준을 얻을 수 있어요. 그리고 왜 이 구조여야 모델이 바뀔 때마다 시스템 전체가 자동으로 좋아지는지 이해할 수 있습니다.

1. 왜 모델이 아니라 하네스인가 — 사건 두 개

먼저 사실 두 개부터 짚고 갑니다.

첫째, 2026년 3월 31일, Anthropic이 실수로 Claude Code 전체 소스코드를 npm 레지스트리에 올렸어요. 51만 2,000줄. 개리 탄이 이걸 직접 읽고 확인한 결론은 단순합니다.

"비밀은 모델이 아니다. 모델을 감싸는 그것(=하네스)이다."

둘째, Anthropic 직원들이 일관되게 말하는 게 있어요. 라이브 레포 컨텍스트, 프롬프트 캐싱, 목적별 도구, 컨텍스트 군살 제거, 구조화된 세션 메모리, 병렬 서브에이전트. 이 중 어떤 것도 모델 자체를 똑똑하게 만들지 않습니다. 전부 모델에게 올바른 컨텍스트를 올바른 시점에 주는 장치예요.

이 장치 묶음이 하네스(harness)입니다. 한국에서 흔히 "하네스 엔지니어링"이라고 부르는 게 바로 이 영역이에요.

그리고 진짜 중요한 질문은 이거예요. 하네스 안에 무엇을 넣고, 무엇을 빼느냐. 답에는 구체적인 모양이 있고, 그 모양 이름이 Thin Harness, Fat Skills입니다.

병목은 절대 모델의 지능이 아니에요. 모델은 이미 추론하고 종합하고 코드를 쓸 줄 압니다. 모델이 실패하는 이유는 여러분의 데이터를 이해하지 못해서예요. 스키마, 사내 컨벤션, 문제의 고유한 모양. 이걸 채워주는 5가지 정의를 봅니다.

2. 정의 ① 스킬 파일 — 마크다운으로 쓰는 함수

스킬 파일은 모델에게 어떤 작업을 어떻게 하는지 가르치는 재사용 가능한 마크다운 문서입니다. 무엇을 할지(WHAT)는 사용자가 결정하고, 어떻게 할지(HOW)는 스킬이 결정해요.

여기서 사람들이 자주 놓치는 핵심이 있습니다. 스킬 파일은 함수 호출처럼 동작합니다. 파라미터를 받아요. 같은 절차에 다른 인자를 넘기면 전혀 다른 능력이 나옵니다.

예를 들어 /investigate라는 스킬이 있다고 해봐요. 7단계 워크플로우를 내장합니다 — 데이터셋 범위 정하기, 타임라인 만들기, 모든 문서 다이어리제이션, 종합, 양쪽 입장 논쟁, 출처 인용. 파라미터는 3개: TARGET, QUESTION, DATASET.

같은 스킬, 같은 7단계, 같은 마크다운 파일. 스킬은 판단의 절차를 기술하고, 호출은 세계를 공급합니다.

이건 프롬프트 엔지니어링이 아니에요. 마크다운을 프로그래밍 언어로, 인간 판단을 런타임으로 쓰는 소프트웨어 설계입니다.

3. 정의 ② 하네스 — 모델을 돌리는 얇은 프로그램

하네스는 LLM을 돌리는 프로그램입니다. 4가지만 합니다.

1. 모델을 루프로 돌린다

2. 파일을 읽고 쓴다

3. 컨텍스트를 관리한다

4. 안전성을 강제한다

끝. 이게 "Thin"입니다.

반대 패턴(=망가지는 패턴)은 두꺼운 하네스에 얇은 스킬이에요. 한 번쯤 보셨을 겁니다.

• 도구 정의 40개 이상이 컨텍스트 윈도우의 절반을 잡아먹는 구조

• 한 번 호출에 2~5초씩 걸리는 god-tool MCP

• REST API 엔드포인트마다 도구 하나로 만든 래퍼

토큰 3배, 지연 3배, 실패율 3배. 받침대(=하네스)에 살이 너무 많이 붙으면 그 안에 들어갈 콘텐츠(=스킬)가 들어설 자리가 없어집니다.

원하는 건 빠르고 좁은 목적별 도구예요. 브라우저 작업 하나에 100ms 걸리는 Playwright CLI 같은 거요. Chrome MCP가 스크린샷-찾기-클릭-기다리기-읽기에 15초 걸린다면, Playwright CLI는 75배 빠릅니다.

4. 정의 ③ 리졸버 — 컨텍스트의 라우팅 테이블

리졸버(Resolver)는 컨텍스트를 위한 라우팅 테이블입니다. "X 유형의 작업이 들어오면 Y 문서를 먼저 로드해라"라는 규칙이에요.

스킬은 모델에게 어떻게를 알려주고, 리졸버는 무엇을, 언제 로드할지 알려줍니다. 차이가 큽니다.

예를 들어 개발자가 프롬프트를 수정합니다. 리졸버 없이는 그냥 푸시해요. 리졸버가 있으면 모델이 먼저 docs/EVALS.md를 읽고, 거기 적힌 규칙을 따릅니다. "평가 스위트 돌려라, 점수 비교해라, 정확도 2% 이상 떨어지면 롤백하고 조사해라." 개발자는 평가 스위트가 있는지도 몰랐어요. 리졸버가 올바른 시점에 올바른 컨텍스트를 로드해줬기 때문에 사고를 막은 거죠.

Claude Code에는 사실 리졸버가 이미 내장돼 있어요. 모든 스킬에 description 필드가 있고, 모델이 사용자 의도를 이 description과 매칭해서 자동으로 스킬을 고릅니다. 여러분이 /ship이 있다는 사실을 외울 필요가 없어요. description이 곧 리졸버입니다.

여기서 개리 탄이 한 고백이 인상적이에요. 본인의 CLAUDE.md가 한때 2만 줄이었답니다. 모든 자잘한 규칙, 패턴, 교훈을 다 적어 넣었던 거죠. 결과는? 모델의 어텐션이 망가졌어요. Claude Code가 직접 "줄이라"고 말해줬을 정도예요.

해결은 약 200줄로 줄이는 것이었습니다. 본문은 다 빼고, 문서 포인터만 남깁니다. 필요한 시점에 리졸버가 적절한 문서를 로드해요. 2만 줄의 지식이 컨텍스트 윈도우를 오염시키지 않으면서 필요할 때마다 접근 가능한 구조가 됩니다.

지피터스 멤버분들이 만드신 CLAUDE.md가 1,000줄을 넘어가신다면, 본문을 다른 마크다운 파일로 빼고 포인터만 남기는 리팩토링을 한번 해보시는 걸 추천드려요.

5. 정의 ④ 잠재 vs 결정론 — 가장 흔한 설계 실수

여기가 에이전트 설계에서 가장 자주 틀리는 지점입니다.

시스템의 모든 단계는 둘 중 하나예요. 그리고 둘을 헷갈리는 게 가장 흔한 실수입니다.

LLM에게 만찬 테이블에 8명을 앉혀달라고 하면, 성격과 사회적 역학을 고려해서 잘 배치합니다. 그런데 800명을 앉혀달라고 하면? 그럴듯해 보이지만 완전히 틀린 좌석표를 환각합니다. 이건 결정론 문제(=조합 최적화)를 잠재 공간에 던진 결과예요.

규칙은 단순해요.

• 판단이 필요한 일 → 잠재 공간(LLM)

• 반복 가능성이 필요한 일 → 결정론 코드(SQL, 알고리즘)

가장 망가진 시스템은 잘못된 일을 잘못된 쪽에 둡니다. 가장 좋은 시스템은 이 경계에 대해 무자비할 정도로 명확합니다.

지피터스에서 자주 보는 안티패턴 중 하나가 "AI한테 엑셀 시트에 있는 1,000개 셀을 처리해달라고 시키는" 겁니다. 그건 LLM의 일이 아니에요. LLM이 변환 규칙을 만들고, 결정론 코드가 1,000개 셀을 처리해야 합니다.

Photo by Amsterdam City Archives on Unsplash

6. 정의 ⑤ 다이어리제이션 — 진짜 지식 작업을 가능하게 만드는 단계

Diarization(다이어리제이션)은 AI를 진짜 지식 작업에 쓸모 있게 만드는 단계입니다.

정의는 이래요. 모델이 한 주제에 대한 모든 자료를 읽고, 구조화된 프로파일을 한 페이지로 써냅니다. 수십~수백 개 문서에서 추출한 판단을 한 장에 압축한 결과물이에요.

SQL 쿼리로는 이게 안 나옵니다. RAG 파이프라인으로도 안 나옵니다. 모델이 실제로 읽고, 모순을 머리에 담고, 무엇이 언제 바뀌었는지 알아채고, 구조화된 인텔리전스로 종합해야 해요.

데이터베이스 룩업과 분석가의 브리프 사이의 차이입니다.

다이어리제이션이 빛나는 실전 사례 — YC Startup School

원문에 나온 사례가 이걸 가장 잘 보여줍니다. 6,000명 창업자를 매칭하는 시스템이에요. 각 창업자에게는 신청서, 설문 답변, 1:1 어드바이저 채팅 트랜스크립트, 그리고 X 게시물·GitHub 커밋·Claude Code 트랜스크립트 같은 공개 신호가 있어요.

다이어리제이션 출력 예시:

창업자: Maria Santos
회사: Contrail (contrail.dev)
말한 것: "AI 에이전트를 위한 Datadog"
실제 만들고 있는 것: 커밋의 80%가 빌링 모듈.
  관측 도구로 위장한 FinOps 도구를 만들고 있음.

"말한 것 vs 실제 만들고 있는 것"이라는 갭은 GitHub 커밋 히스토리, 신청서, 어드바이저 트랜스크립트를 동시에 머리에 담고 읽어야 잡힙니다. 임베딩 유사도 검색으로는 못 잡아요. 키워드 필터로도 못 잡아요. 모델이 전체 프로파일을 읽고 판단해야 합니다.

7. 5가지 정의를 합치면 나오는 3층 아키텍처

5가지 개념을 합치면 단순한 3층 아키텍처가 나옵니다.

┌─────────────────────────────────┐
│  Fat Skills (마크다운 절차)         │  ← 90%의 가치가 여기
│  - 판단, 프로세스, 도메인 지식       │
└─────────────────────────────────┘
           ↑ 호출
┌─────────────────────────────────┐
│  Thin CLI Harness (≈ 200줄 코드) │
│  - JSON in, text out             │
│  - 기본 read-only                 │
└─────────────────────────────────┘
           ↑ 실행
┌─────────────────────────────────┐
│  Application (결정론적 토대)        │
│  - QueryDB, Search, Timeline     │
└─────────────────────────────────┘

원칙은 방향성이에요.

• 지능은 위로 — 스킬에 밀어 올린다

• 실행은 아래로 — 결정론적 도구에 밀어 내린다

• 하네스는 얇게 — 가운데는 얇게 유지한다

이렇게 하면 모델이 업데이트될 때마다 모든 스킬이 자동으로 좋아지고, 결정론 레이어는 완벽하게 안정적으로 남습니다.

8. 학습하는 시스템 — Enrich → Match → Improve 루프

5가지 정의가 실전에서 어떻게 결합되는지 보여주는 가장 강력한 패턴이 YC Startup School 6,000명 매칭 시스템입니다.

Step 1. 인리치먼트 (Enrichment)

/enrich-founder 스킬이 모든 소스를 끌어와 다이어리제이션을 돌립니다. 결정론 레이어가 SQL 룩업, GitHub 통계, 데모 URL 브라우저 테스트, 소셜 신호 풀, CrustData 쿼리를 처리합니다. 크론으로 매일 밤 6,000개 프로파일이 자동 갱신돼요.

Step 2. 매칭 (Matching) — 같은 스킬, 다른 인자

같은 매칭 스킬을 3가지 방식으로 호출합니다. 정의 ①(스킬은 함수)이 빛나는 지점이에요.

그리고 모델이 클러스터링 알고리즘으로는 절대 못 할 판단을 내려요. "Kim은 'developer tools'로 신청했지만 1:1 트랜스크립트를 보면 SOC2 컴플라이언스 자동화를 만들고 있다. FinTech/RegTech로 옮겨라."

이 Kim 재분류는 임베딩으로 절대 안 잡힙니다. 모델이 전체 프로파일을 읽어야 가능해요.

Step 3. 학습 루프 (Improve)

이게 진짜 핵심이에요. 행사 끝나고 /improve 스킬이 NPS 설문을 읽고, "OK"라고 답한 어정쩡한 응답들을 다이어리제이션합니다. 나쁜 거 말고 — 거의 작동했지만 안 된 부분이요. 그리고 패턴을 추출해서 새 규칙을 매칭 스킬에 직접 써넣습니다.

참석자가 "AI 인프라"라고 말했지만
스타트업 코드의 80%+가 빌링 모듈이면:
  → AI 인프라가 아니라 FinTech로 분류

이 규칙이 스킬 파일 안에 그대로 적혀요. 다음 행사 때부터 자동 적용됩니다. 스킬이 스스로를 다시 씁니다.

7월 행사: "OK" 평점 12%. 다음 행사: 4%. 코드를 누가 다시 짠 게 아니에요. 스킬 파일이 "OK"의 진짜 의미를 학습한 결과입니다.

9. 한 번 묻는 일은 자동화 — 일회성 작업 금지 원칙

개리 탄이 자기 OpenClaw에 내린 지시가 큰 반향을 얻었어요. 한국 멤버분들에게도 이게 가장 실용적인 부분입니다.

너는 일회성 작업을 할 권한이 없다. 내가 시킨 일이 다시 일어날 종류의 일이라면 다음을 해야 한다:

1. 처음에는 3~10개 항목에 대해 수동으로 한다

2. 결과를 나에게 보여준다

3. 내가 승인하면 → 스킬 파일로 코드화한다

4. 자동 실행이어야 하면 → 크론에 올린다

테스트: 내가 같은 걸 두 번 시켜야 한다면, 너는 실패한 것이다.

여러분이 쓰는 모든 스킬은 시스템에 대한 영구 업그레이드예요. 절대 퇴화하지 않고, 잊지 않고, 새벽 3시에도 잠든 동안 돌아갑니다. 그리고 다음 모델이 나오면 모든 스킬이 즉시 더 좋아져요. 잠재 단계의 판단력은 모델 따라 향상되고, 결정론 단계는 완벽하게 안정적으로 남기 때문입니다.

이게 Yegge가 말한 100x의 정체입니다. 더 똑똑한 모델이 아니라 — Fat Skills, Thin Harness, 그리고 모든 걸 코드화하는 규율.

원문: Garry Tan, "Thin Harness, Fat Skills"