하네스 엔지니어링 다양한 레퍼런스 공부하고 적용해보기

한 달 전에 하네스 엔지니어링에 대한 글을 썼습니다. 교사인 제가 7개 프로젝트에서 AI에게 작업 환경을 깔아 온 이야기였습니다. 여섯 개의 축(구조·맥락·계획·실행·검증·개선)에 열다섯 가지 사례를 묶었고, "좋은 하네스는 점점 단순해진다"는 문장으로 마무리했습니다.

한 달이 지났습니다. 그 사이에 몇 가지가 바뀌었습니다. 전역 하네스에 새 원칙이 추가됐고, 플러그인 여럿이 정리됐고, 이전에는 수동이던 몇몇 절차가 훅으로 자동화됐습니다. 학생들에게 하네스 엔지니어링을 가르치는 수업도 준비하게 됐습니다. 그 과정에서 안드레 카파시의 CLAUDE.md 원문을 한 줄씩 뜯어보았고, 이호연 님(Team Attention)의 발표 자료와 WalkingLabs의 커리큘럼도 함께 살펴보았습니다.

이 글은 그 결과물입니다. 1편이 "내 사례 모음"이었다면, 이번 글은 여러 소스를 합쳐 하나의 레퍼런스로 엮어 본 것입니다. 하네스 엔지니어링을 처음 접하는 분에게는 입문서로, 1편을 읽으신 분에게는 후속편으로 읽히기를 바랍니다.

1. 왜 하네스 엔지니어링인가

1.1. 세 단계의 진화

AI를 잘 쓰는 기술은 세 단계로 진화해 왔습니다.

1단계는 프롬프트 엔지니어링입니다. "이렇게 말해 봐"라는 식으로 질문을 잘 다듬는 기술입니다. 2단계는 컨텍스트 엔지니어링입니다. "이런 배경지식도 같이 줄게"라는 식으로 맥락을 풍부하게 하는 기술입니다. 3단계가 하네스 엔지니어링입니다. "환경 자체를 만들어 줄 테니, 너는 그 안에서 일해"라는 식으로 작업 환경을 통째로 설계하는 기술입니다.

왜 환경까지 가야 하는가. 프롬프트는 이제 AI가 AI한테 시키는 게 더 잘 됩니다. 컨텍스트도 자동 축적이 잘 되는 영역입니다. 그러면 사람이 마지막까지 챙겨야 하는 영역은 어디인가. 폴더 구조, 규칙 문서, 검증 게이트, 도구 배치, 핸드오프 절차. 이런 것들을 사람이 정해 줘야 합니다. 이게 하네스입니다.

1.2. 2026년, 세 가지가 겹쳤다

왜 하필 2026년인가. 세 가지가 동시에 수렴했습니다.

첫째, AI 모델이 상향 평준화됐습니다. Claude·GPT·Gemini 같은 주요 모델들의 벤치마크 점수가 빠르게 좁혀졌고, 더는 "어떤 모델을 쓰느냐"가 결정적인 차이를 만들지 못하는 시기가 왔습니다. 무엇이 차이를 만드는가. 모델을 둘러싼 시스템, 즉 하네스입니다. LangChain은 같은 모델을 쓰면서 하네스만 개선해 TerminalBench 점수를 52.8%에서 66.5%로 올렸습니다. 30위 밖에서 Top 5 안으로 들어왔습니다.

둘째, AI 에이전트가 데모를 벗어나 실무로 들어왔습니다. 짧은 작업은 잘하지만 긴 작업에서 궤도를 이탈하고, 자기가 만든 결과를 평가시키면 항상 잘했다고 답하고, 같은 실수를 반복하며 무한 루프에 빠지는 문제가 본격적으로 드러났습니다. 프롬프트 한 줄로는 해결되지 않습니다. 구조적 해결책, 즉 하네스가 필요해졌습니다.

셋째, 이름이 붙었습니다. 2026년 2월, Mitchell Hashimoto가 "Harness Engineering"이라는 이름을 블로그에 정리했습니다. 핵심 철학은 분명합니다. 에이전트가 실수할 때마다 "다음에 잘하라"고 말하지 말고, 그 실수가 구조적으로 재발하지 않도록 시스템을 엔지니어링하라.

1.3. 기업이 증명한 하네스의 힘

이호연 님(Team Attention)의 발표 자료에서 인상적이었던 사례 네 가지를 옮겨 봅니다.

기업	결과	핵심 교훈
LangChain	30위→Top 5, +14%p	같은 모델, 하네스만 변경. 셀프 검증 루프 + 컨텍스트 자동 수집 + 둠 루프 탐지.
OpenAI	100만 줄, 인간 코드 0줄	엔지니어 3~7명이 5개월 동안 한 일은 코딩이 아니라 하네스 설계. 5가지 교훈 중 "더 좋은 모델 써라"는 없었습니다.
Anthropic	$9 실패 vs $200 성공	싱글 에이전트 20분/$9은 실패. 3에이전트 하네스 6시간/$200은 완전 동작. 간소화 버전 $124로도 품질 유지.
Stripe	1,000 PR/주, 완전 무인	전문화된 소형 에이전트 다수. 매 스텝 검증 게이트 + 정밀 컨텍스트 관리.

모델 교체로 5% 개선하는 것보다, 하네스 설계로 15% 개선하는 것이 현실적이다.

1.4. 정의의 넓이

이호연 님의 발표에서 한 가지 중요한 구분이 있었습니다.

좁은 의미의 하네스는 CLAUDE.md에 DOs/DON'Ts를 적고 Hook으로 차단하는 것, Skill + Agent를 조합해 특정 작업을 효율적으로 수행하는 것입니다. 넓은 의미의 하네스는 특정 스킬이나 에이전트 조합이 아니라, AI 에이전트의 작업 환경 자체를 설계하는 것입니다. 맥락, 제한, 흐름, 검증. 이 모든 것을 포괄하는 개념입니다.

Anthropic의 표현을 빌리면 이렇습니다. "하네스의 모든 구성요소는 모델이 혼자서는 못 하는 것에 대한 가정을 담고 있다."

이 글에서 다루려는 하네스도 넓은 의미입니다. 가드레일 하나가 아니라, 작업 환경 전체를 설계하는 관점입니다.

2. 카파시 CLAUDE.md 원문 살펴보기

안드레 카파시(Andrej Karpathy, 전 테슬라 AI 디렉터이자 OpenAI 창립 멤버)가 2026년 1월에 X(구 트위터)에서 자기 코딩 방식의 전환을 이야기했습니다. 80% 수동 코딩에서 80% 에이전트 기반 코딩으로 바뀌었다는 내용이었습니다. 그가 에이전트를 쓰면서 자주 겪는 네 가지 실패 패턴을 관찰했고, 포레스트 챙(Forrest Chang)이 그 관찰을 CLAUDE.md 형식으로 변환했습니다. 이 파일이 GitHub에서 28일 연속 #1 트렌딩을 기록하고, 22만 개가 넘는 스타를 받았습니다.

원문은 65줄에 불과합니다. 단순함이 작동의 조건이라는 카파시 자신의 말을 증명하는 분량입니다. 네 가지 원칙을 하나씩 살펴보겠습니다.

원칙 1: Think Before Coding — 가정하지 말고, 혼란을 숨기지 말고, 트레이드오프를 드러내라

Before implementing:

State your assumptions explicitly. If uncertain, ask.

If multiple interpretations exist, present them — don't pick silently.

If a simpler approach exists, say so. Push back when warranted.

If something is unclear, stop. Name what's confusing. Ask.

AI에게 "해줘"라고 시키면 AI는 가정을 세우고 조용히 시작합니다. 그 가정이 맞으면 운이 좋은 거고, 틀리면 다 만든 뒤에야 "이게 아닌데..."가 됩니다. 카파시의 첫 번째 원칙은 이걸 뒤집습니다. 가정하지 말고 물어봐라. 여러 해석이 가능하면 조용히 하나를 고르지 말고 전부 보여줘라.

6축 매핑: 계획(Planning). "해줘"가 아니라 "물어봐"의 원칙입니다.

DoRm 적용. 전역 CLAUDE.md의 의사결정 규칙에 "애매한 요구사항 → 반드시 질문 (가정하지 말 것)"이 명시되어 있습니다. 한 달 전에는 이 규칙만 있었는데, 지금은 여기에 OMC deep-interview 스킬이 더해졌습니다. 플랜 모드에 진입하면 훅이 자동으로 deep-interview를 안내합니다. AI가 사람에게 소크라테스식 질문을 던지며 모호함을 줄여 나가는 절차가 자동화된 셈입니다.

이호연 님 연결. 발표에서 이 원칙을 "나에게 질문하게 하기"로 풀었습니다. AskUserQuestion을 통해 AI가 자동으로 모호한 점을 물어보게 만드는 커스텀 Plan 스킬(/specify, /deep-interview)이 이 원칙의 도구화입니다.

원칙 2: Simplicity First — 최소 코드, 추측 없음

No features beyond what was asked.

No abstractions for single-use code.

No "flexibility" or "configurability" that wasn't requested.

If you write 200 lines and it could be 50, rewrite it.

AI는 친절합니다. "더 좋게 해드릴게요"라며 요청하지 않은 기능을 추가하고, 한 번밖에 안 쓸 코드에 추상화를 씌우고, 유연성을 위해 설정 옵션을 늘립니다. 카파시는 이걸 전부 금지합니다. 요청한 것만, 최소한으로.

6축 매핑: 구조(Scaffolding) + 개선(Compound).

DoRm 적용. 전역 CLAUDE.md의 작업 원칙 첫 줄이 "요청한 것만 구현 (과잉 엔지니어링 금지)"입니다. 개인용 살핌에서는 docs/plan.md에 v1 범위를 명시적으로 잠가 두고, v2 후보는 현재 세션에서 구현하지 않도록 했습니다(1편 참조). 그리고 한 달 사이에 이 원칙이 플러그인 정리로도 이어졌습니다. superpowers 플러그인이 비활성화되고, claude-mem도 꺼졌습니다. 쓰지 않는 것을 치운 것입니다. 좋은 하네스는 점점 단순해진다는 1편의 결론이 한 달 뒤에 실제로 일어났습니다.

카파시 LLM Wiki 연결. 카파시가 굳이 마크다운 폴더 하나라는 가장 단순한 형태를 고른 이유. 단순함이 미덕이 아니라 단순함이 작동의 조건이기 때문입니다.

원칙 3: Surgical Changes — 내가 만진 것만 바꾸고, 옆에 있는 건 건드리지 마라

Don't "improve" adjacent code, comments, or formatting.

Don't refactor things that aren't broken.

Match existing style, even if you'd do it differently.

Remove imports/variables that YOUR changes made unused.

AI는 코드를 읽으면서 "이것도 고치면 좋겠다"는 충동을 자주 느낍니다. 옆에 있는 코드의 포맷을 정리하고, 사용되지 않는 변수를 삭제하고, 더 나은 패턴으로 리팩토링합니다. 카파시는 이 모든 부수적 변경을 금지합니다. 내가 만진 것만 바꿔라. 깨지지 않은 것은 건드리지 마라.

6축 매핑: 검증(Verification).

DoRm 적용. 프로젝트 CLAUDE.md에 "이번 세션에서 직접 수정한 파일만 커밋"이라는 규칙이 있습니다. git add .이나 git add -A는 절대 금지입니다. 북곽원에서는 한 단계 더 나아가, src/components/design/ 폴더의 Edit/Write를 PreToolUse 훅으로 아예 차단합니다. Variant에서 만든 디자인 원본에 AI가 손을 대지 못하게 물리적으로 막아 둔 것입니다. AI의 "더 좋게 만들어 드리겠습니다" 충동을 문서가 아니라 인프라로 차단한 사례입니다.

원칙 4: Goal-Driven Execution — 성공 기준을 정하고, 검증될 때까지 반복

Transform tasks into verifiable goals:

"Add validation" → "Write tests for invalid inputs, then make them pass"

"Fix the bug" → "Write a test that reproduces it, then make it pass"

For multi-step tasks, state a brief plan:

[Step] → verify: [check]

[Step] → verify: [check]

이 원칙이 네 가지 중 가장 실천적입니다. 모호한 지시를 검증 가능한 목표로 바꿔라. "검증 추가"가 아니라 "잘못된 입력에 대한 테스트를 작성하고, 그 테스트를 통과시켜라". 다단계 작업에서는 각 단계마다 검증 항목을 붙여라.

6축 매핑: 검증(Verification) + 실행(Orchestration).

DoRm 적용. 한 달 전에는 이 원칙이 암묵적으로만 작동했습니다. 지금은 전역 CLAUDE.md에 검증 가능성 원칙 (Karpathy)이라는 별도 섹션이 있습니다.

- 출력만 보고 "성공"이라 하지 말 것 — exit code/결과를 직접 확인한 후 보고
- LLM은 *지정 가능한 것*이 아니라 *검증 가능한 것*을 자동화한다

OMC verify 스킬은 이 원칙을 순차적 검증 체계(기존 테스트 → 타입체크/빌드 → 직접 명령 검증 → UI 레이아웃 무결성 → 수동 검증)로 체계화한 것입니다. 앵그리매스의 Phase 게이트(15단계 마일스톤, 각 단계에 인수 조건과 테스트 케이스)도 같은 결입니다.

2026년 5월 추가: "AI는 눈이 없다" — UI 검증의 맹점. 포켓몬 도감 사이트를 만들면서 이 원칙의 한계를 하나 더 발견했습니다. AI가 카드 플립 기능을 구현했고, Playwright로 스크린샷을 찍어 "잘 보입니다"라고 보고했습니다. 그런데 실제로는 이브이의 분기 진화 체인(샤미드/쥬피썬더/부스터)이 카드 밖으로 109px 넘쳐서 이웃 카드와 겹치고 있었습니다. AI는 스크린샷의 픽셀을 해석할 수 없으므로, 눈으로 봐야 보이는 오버플로우·겹침·잘림 문제를 원천적으로 발견할 수 없습니다.

해결책은 프로그래밍적 검증입니다. Playwright의 browser_evaluate로 모든 요소의 scrollWidth > clientWidth, scrollHeight > clientHeight, getBoundingClientRect() 교차 여부를 수치로 측정하는 스크립트(~/.claude/scripts/ui-overflow-check.js)를 만들어 OMC verify 스킬에 "UI layout integrity" 단계로 통합했습니다. 스크린샷 촬영 시 자동으로 리마인드하는 PostToolUse 훅도 추가했습니다. 실수를 발견할 때마다 "다음에 잘해"라고 말하는 대신, 그 실수가 구조적으로 재발하지 않도록 하네스를 바꾼 사례입니다.

이호연 님 연결. 발표에서 이 원칙을 "Ralph Loop"로 풀었습니다. 완료 기준을 정하고, 충족할 때까지 AI가 알아서 반복하는 패턴입니다. 재미있는 점은, DoRm에서는 이 Ralph Loop 개념이 독립 플러그인에서 OMC autopilot 파이프라인의 일부로 흡수됐다는 것입니다. 개별 기능이 더 큰 파이프라인으로 통합되며 단순해지는 사례입니다.

카파시 4원칙 → 6축 매핑표

카파시 원칙	주요 6축	DoRm 실전	이호연 TRY IT
Think Before Coding	계획	deep-interview, 의사결정 규칙	/specify, /clarify
Simplicity First	구조+개선	plan.md 스코프 락, 플러그인 정리	/check-harness
Surgical Changes	검증	커밋 규칙, design-protection 훅	worktree 격리
Goal-Driven Execution	검증+실행	verify L0~L7, autopilot	/qa, autoresearch

카파시의 원문에는 이런 문장이 있습니다.

These guidelines are working if: fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

65줄짜리 문서가 작동하고 있는지를 판단하는 기준도 세 가지뿐입니다. diff에 불필요한 변경이 줄었는가. 과잉 구현으로 인한 재작업이 줄었는가. 실수 후가 아니라 구현 전에 질문이 나오는가. 이 세 가지가 곧 좋은 하네스의 작동 증거입니다.

3. 6축 프레임워크 — 종합 정리

하네스의 여섯 개 축은 이호연 님의 발표와 DoRm 블로그 1편에서 동일하게 사용하는 프레임워크입니다. 순환 구조를 이룹니다.

[구조] → [맥락] → [계획]
  ↑                  ↓
[개선] ← [검증] ← [실행]

이 장에서는 각 축마다 이론(이호연/카파시/WalkingLabs)과 실전(DoRm)을 통합하고, 1편 이후 한 달간의 진화를 짚습니다. 1편의 15개 사례를 여기서 다시 나열하지는 않습니다. 해당 사례는 1편을 참고해 주세요.

3.1. 구조(Scaffolding) — 한 번 깔면 계속 효력이 있는 것

구조는 하네스의 토대입니다. 폴더를 어떻게 나누고, 도구를 어디에 배치하고, 경계를 어떻게 설정하는가.

이론. 이호연 님은 세 가지를 강조합니다. 첫째, 모노레포로 묶어 AI가 전체 맥락을 파악하게 한다. 둘째, 역할별 폴더링(src/, docs/, tests/, .dev/, .claude/)으로 AI가 어디에 뭘 넣을지 바로 알게 한다. 셋째, 사람의 문서(docs/)와 AI의 문서(.dev/)를 분리한다. 사람이 관리를 멈추면 AI도 엉뚱한 맥락으로 일하기 때문입니다. WalkingLabs의 강의 04는 이 축에서 특히 중요한 경고를 줍니다. 거대한 명령 파일(AGENTS.md가 600줄)은 오히려 성능을 떨어뜨립니다. 이유가 네 가지입니다. 첫째, 컨텍스트 예산을 1020K 토큰씩 잠식합니다. 둘째, LLM은 긴 텍스트의 중간 정보를 양 끝보다 훨씬 덜 활용합니다(Lost in the Middle 효과). 셋째, 하드 제약과 선호 사항이 동등하게 취급되어 우선순위가 모호해집니다. 넷째, "추가는 공짜"라는 심리로 파일이 끝없이 비대해집니다. 해법은 명령 분산 아키텍처입니다. 진입 파일(50200줄)에는 개요와 하드 제약 최대 15개만 두고, 나머지는 주제별 문서(api-patterns.md, testing-standards.md 등)로 분리해 필요할 때만 로드합니다. 한 SaaS 팀은 이 리팩터링으로 동일 작업 성공률을 45%에서 72%로, 보안 제약 준수율을 60%에서 95%로 올렸습니다.

DoRm 사례. 살핌의 CLAUDE.md는 약 50KB입니다. 처음에는 매 세션 통째로 읽게 했는데, 컨텍스트가 빠르게 차고 95%가 잡음이 되었습니다. 지금은 첫 부분에 상황별 라우팅 표를 두고("보고서 작성 → docs/reports/ 참고, DB 분석 → docs/database/ 참고") 필요한 문서만 동적으로 로드합니다. 북곽원은 정반대로 갔습니다. CLAUDE.md는 24줄, 규칙은 전부 .claude/rules/로 분산했습니다. 입구를 짧게 만들고 글로브 패턴으로 자동 매칭되게 한 것입니다. 앵그리매스는 Phaser 4 공식 문서가 자주 바뀌어서, v4.0.0 태그 docs를 .claude/skills/phaser-v4/에 스냅샷으로 고정해 버렸습니다. 라이브러리 버전 드리프트를 인프라로 차단한 사례입니다.

설정 파일 상속 구조. 이호연 님의 발표에서 가장 유용했던 다이어그램입니다.

~/.claude/CLAUDE.md          [User — 모든 프로젝트 공통]
│
└── my-app/
    ├── CLAUDE.md            [Project — 이 프로젝트 전용]
    ├── .claude/
    │   └── rules/           [상황별 규칙, glob 패턴으로 조건부 로드]
    └── src/auth/
        └── CLAUDE.md        [Folder — 이 폴더 작업 시에만]

하위가 상위를 오버라이드합니다. User에 "camelCase 사용"이라고 적어 두어도, Project에 "snake_case 사용"이라고 적으면 이 프로젝트에서는 snake_case가 적용됩니다.

도구 배치. 2차시에서 배운 5가지 도구(Skill, Hook, Agent, MCP, Plugin)가 이 축에 속합니다. 한 번 배치해 두면 모든 세션에서 같은 도구가 손에 잡힙니다.

3.2. 맥락(Context) — AI가 무엇을 알고 일하는가

이론. Progressive Disclosure — "한꺼번에 다 주면 AI도 헷갈린다." 필요한 것만 필요할 때 보여주는 원칙입니다. SKILL.md 안에 "코드 작성 시 → references/code-style.md 참고, 테스트 시 → references/testing-guide.md 참고"라는 안내문을 넣으면 AI가 상황에 따라 필요한 문서만 읽습니다. 세션 맥락 관리도 중요합니다. 이호연 님의 기준은 "20~30% 차면 새로 시작". /compact로 오래된 대화를 압축하거나, /clear로 완전 초기화하거나, handoff로 맥락을 파일에 저장한 뒤 새 세션에서 이어받습니다. WalkingLabs의 강의 03은 "저장소가 단일 진실 원천(System of Record)"이어야 한다고 강조합니다. 핵심 테스트는 "콜드 스타트 테스트"입니다. 새 세션이 저장소만으로 다섯 가지 질문에 답할 수 있는가? (1) 시스템의 목적, (2) 구성, (3) 실행 방법, (4) 검증 방법, (5) 현재 진행 상황. 답할 수 없다면 맥락이 Slack이나 사람의 머릿속에 갇혀 있는 것입니다. 강의 05는 PROGRESS.md로 장시간 작업의 연속성을 유지하라고 안내합니다. 30분을 넘기면 에이전트 실패율이 급상승하기 때문입니다.

DoRm 사례. 주도는 30개 넘는 모듈(출결, 외박, 상벌점, 방과후 등)이 6개 역할의 권한과 얽혀 있습니다. 코드와 문서가 어긋나면 누구도 알아채지 못하는데, CLAUDE.md에 메뉴와 리뷰 문서의 1:1 매핑 표를 두어 "코드를 만지기 전에 문서를 만진다"는 운영 원칙을 굳혔습니다. 살핌에서는 수학 교사인 제가 P.F.(proof, 증명 시작)/Q.E.D.(증명 완료)라는 수학 용어를 세션 핸드오프 트리거로 썼습니다. 긴 작업을 인위적으로 자르고, 자른 자리마다 Serena 메모리에 표식을 남깁니다. 앵그리매스에서는 수학식을 게임 메커닉으로 바꾸는 6계층 변환 스택(f_user → T_debuff → originWorld → hLocal → kLocal → dir)과 AI가 흔히 빠지는 함정 10가지를 src/math/CLAUDE.md에 전부 적어 두었습니다. 실패 사례를 미리 박제해 두면 AI는 같은 실수를 반복하지 않습니다.

진화. 1편 이후 가장 체감이 큰 변화입니다. session-start.sh 훅이 매 세션 시작 시 vault/wiki/index.md 전체를 자동 주입합니다. 별도로 파일을 읽지 않아도 DoRm vault의 전체 지식 인덱스가 컨텍스트에 올라옵니다. Obsidian MCP도 등록되어 wiki 페이지를 개별적으로 읽고 편집할 수 있게 됐습니다. 맥락 제공이 수동에서 자동으로 넘어간 것입니다.

3.3. 계획(Planning) — 뭘 할지 먼저 정하는가

이론. 이호연 님은 "해줘"의 함정을 명쾌하게 정리했습니다. "이거 만들어줘" → AI가 알아서 만듦 → "아닌데..." → 다시 → 시간만 날림. 해법은 "같이 계획부터 세우자"입니다. AI에게 질문을 시키는 것("이해한 것을 미러링하고, 모호한 점을 질문해서 명확하게 해줘")이 핵심입니다. 사람은 자기 머릿속의 전제를 프롬프트에 다 담지 못합니다. AI가 질문해야 빠진 맥락이 드러납니다.

DoRm 사례. 담임 업무 자동화에는 슬래시 커맨드 대신 한국어 트리거가 있습니다. "ㅎㅇ"이면 인박스 확인(GOE 폴더 스캔 → 분류 → Slack 정리 제안), "ㅋㅋ"이면 학생 참여 콘텐츠 제안, "RAG"이면 자료 검색. 명령어를 외울 필요 없이, 카카오톡에 답장 보내듯 치는 동작이 9단계 자동 워크플로우의 진입점이 됩니다. 개인용 살핌에서는 docs/plan.md에 v1 범위를 잠가 두고, v2 후보는 현재 세션에서 구현 금지로 했습니다. AI의 "더 좋게 해드릴게요" 친절을 차단하는 장치입니다. 앵그리매스는 Phase 0~14까지 15단계 마일스톤이 있고, 각 Phase마다 인수 조건과 테스트 케이스가 문서에 박혀 있습니다. lint/typecheck/테스트 중 하나라도 실패하면 Phase가 닫히지 않습니다.

진화. 이 축에서 가장 큰 변화가 있었습니다. plan-mode-omc.sh라는 PreToolUse 훅이 추가됐습니다. Plan Mode에 진입하면 이 훅이 자동으로 OMC 플래닝 파이프라인을 안내합니다.

# ~/.claude/hooks/plan-mode-omc.sh
[OMC Plan Mode Pipeline]
1. 요구사항 모호 → deep-interview로 정제
2. 플랜 수립 → plan --consensus
   - analyst → architect → critic → 합의 루프 (최대 5회)
3. 합의 완료 → ExitPlanMode → autopilot Phase 1부터 실행
4. 검증: verify L0~L7 전부 통과 필수

analyst(요구사항 분석), architect(기술적 타당성), critic(허점 검증) 세 관점이 합의할 때까지 최대 5라운드를 돕니다. 한 달 전에는 "플랜을 어떻게 세울지"를 사람이 매번 정했습니다. 지금은 훅이 그 절차를 강제합니다. 하네스가 하네스를 만드는 자기재귀 구조입니다. 전역 CLAUDE.md에는 플랜 모드 합의 원칙도 추가됐습니다. "합의가 완전히 끝나기 전 plan 확정 금지." 이 원칙이 다른 어떤 지시보다 우선합니다.

3.4. 실행(Orchestration) — 어떻게 시키는가

이론. 세 가지 패턴이 있습니다. 혼자(Single) — 90%의 일상 작업. 부하 파견(Subagent) — 병렬/전문화, 위임 후 종합. 팀(Team Mode) — 에이전트 간 직접 소통, 다관점 협업. 이호연 님은 "90%는 단일/서브에이전트로 충분하고, 팀 모드는 ~7x 토큰 비용"이라고 정리합니다. Ralph Loop("될 때까지 반복")와 카파시의 autoresearch("사람은 방향만, AI가 밤새 실험")도 이 축의 패턴입니다. WalkingLabs의 강의 09는 "조기완료방지"를 깊이 다룹니다. 에이전트는 체계적으로 자기 작업을 과대평가합니다(신뢰도 보정 편향). "완료했다"고 보고하지만 실제로는 미완료인 경우가 빈번합니다. 특히 단위 테스트가 통과하면 끝이라고 착각하는 "단위 테스트 함정"이 위험합니다. 모킹된 의존성이 통합 실패를 은폐하기 때문입니다. 해법은 3계층 출구 검증입니다. 1계층(구문/정적 분석) → 2계층(런타임 행동 — 코드가 실행되어야 함) → 3계층(시스템 수준 E2E 확인). 핵심 원칙: "완료란 체계적 실행 테스트를 통해 외부에서 검증된 것을 의미한다."

DoRm 사례. 담임 업무 자동화는 훅에 많이 의존합니다. SessionStart 훅이 매일 첫 세션에서 어제 일정을 제거하고 Slack pin을 교체합니다. PostToolUse 훅이 일정 파일 수정 직후 학생 전체에게 업데이트 DM을 발송합니다. 한 번의 행위(파일 수정)가 자동으로 Slack pin 교체 + DM 발송으로 확산됩니다. NEIS 추정분할점수 계산기는 git 태그 한 번이면 윈도/맥/리눅스 설치 파일이 동시에 만들어지고 웹도 갱신됩니다. 전역 /loop 스킬은 체크리스트 기반 구현-테스트-수정 루프를 자율 실행합니다. AI가 개발 서버에 접속해 스크린샷을 찍으며 검증하고, 실패하면 Codex에 위임하고, 모든 항목 통과까지 사람 손 없이 돕니다.

진화와 반성. 솔직히 고백하면, 1편을 쓸 때 에이전트 오케스트레이션을 제대로 활용하지 못하고 있었습니다. 서브에이전트를 쓰긴 했지만, 대부분 한 번에 하나를 보내고 결과를 기다리는 직렬 방식이었습니다. 그런데 oh-my-claudecode를 본격적으로 쓰면서 에이전트 병렬 실행의 위력을 체감했습니다.

핵심은 메인 컨텍스트 보호입니다. 긴 작업에서 가장 무서운 건 컨텍스트 오염입니다. 탐색, 분석, 검색을 메인 세션에서 직접 하면 컨텍스트가 빠르게 차고, 정작 중요한 판단을 할 때 이전 맥락을 놓칩니다. 서브에이전트에게 위임하면 그 작업의 결과만 요약으로 돌아옵니다. 메인 AI는 조정과 통합에만 집중합니다.

실제로 이 글을 쓰는 과정에서도 3개의 탐색 에이전트를 병렬로 보냈습니다. 하나는 기존 수업 자료를 읽고, 하나는 DoRm 하네스 현재 상태를 분석하고, 하나는 외부 참고자료를 웹서치했습니다. 세 에이전트가 동시에 돌아가는 동안 메인 세션의 컨텍스트는 깨끗하게 유지됐습니다. 결과가 돌아오면 메인 AI가 종합하고 판단합니다.

oh-my-claudecode의 autopilot이 이 패턴을 체계화합니다.

Phase 0: analyst(Opus)가 요구사항 분석 → architect(Opus)가 설계
Phase 1: plan --consensus → analyst/architect/critic 3인이 합의할 때까지 루프
Phase 2: 독립 작업을 병렬 에이전트로 분배 (Haiku=단순, Sonnet=표준, Opus=복잡)
Phase 3: QA 사이클 (빌드→린트→테스트→수정, 최대 5회)
Phase 4: 병렬 검증 — architect(완성도) + security-reviewer(취약점) + code-reviewer(품질)
Phase 5: 정리 및 보고

각 Phase의 에이전트는 독립된 컨텍스트에서 작업합니다. Phase 4에서 세 명의 리뷰어가 동시에 같은 코드를 다른 관점으로 봅니다. 한 리뷰어의 분석이 다른 리뷰어의 판단을 오염시키지 않습니다. 이게 Anthropic이 말한 "Generator와 Evaluator 분리"의 실질적 구현입니다.

기본 실행 경로가 이 autopilot으로 정착했습니다. Ralph는 이호연 님의 발표에서 "Claude Code 공식 Plugin"으로 소개됐지만, DoRm에서는 standalone ralph를 사용하지 않고 autopilot 파이프라인 안에서 같은 기능이 작동합니다. 멀티 AI 라우팅도 정비됐습니다. Claude 서브에이전트는 Agent(model:sonnet|opus), Codex는 /codex:rescue, Gemini는 gemini-run.sh CLI로 호출합니다. 작업의 성격에 따라 적합한 모델을 골라 보내는 것이 핵심이고, routing-table.json이 이 라우팅을 문서화합니다.

3.5. 검증(Verification) — 결과물을 어떻게 믿을 것인가

이론. 이호연 님은 네 가지 원칙을 제시합니다.

기준이 있어야 검증이 가능하다. 작업 전에 "뭘 만들고 어떻게 검증할지" 합의. "잘 되게"가 아니라 "테스트 통과 + 빌드 성공".
컨텍스트를 나누고, 관점을 분리한다. Anthropic의 핵심 레버. "자기 작업을 평가하면 quality가 mediocre해도 자신있게 칭찬한다." 만든 AI(Generator)와 확인하는 AI(Evaluator)를 분리하는 것이 가장 강력합니다.
모델도 나누고, 역할도 나눈다. Codex로 코드 리뷰, Gemini로 문서 리뷰, Opus로 아키텍처 판단. 한 모델의 맹점을 다른 모델이 잡습니다.
에이전트에게 눈을 달아준다. Browser Agent로 실제 화면을 보고 검증. Computer Use로 네이티브 앱도 제어. 검증 범위를 코드에서 화면까지 확장합니다.

WalkingLabs의 강의 10은 "E2E 테스트만이 진정한 검증"이라고 단언합니다. 단위 테스트가 잡지 못하는 결함이 네 가지입니다. 인터페이스 불일치(상대 경로 vs 절대 경로), 상태 전파 오류(계층 간 캐시 불일치), 리소스 수명 주기 문제(파일 핸들 미해제), 환경 의존성(테스트 환경 ≠ 실제 환경). Electron 파일 내보내기 사례에서 5개 결함 모두 E2E로 감지됐지만 단위 테스트는 0개를 잡았습니다. 흥미로운 점은 E2E 테스트가 단순히 결함을 찾는 것을 넘어 에이전트의 코딩 행동 자체를 변화시킨다는 것입니다. 컴포넌트 상호작용을 설계 단계에서 고려하고, 예외 처리를 미리 대비하게 됩니다.

DoRm 사례. 가장 비중을 두고 있는 축입니다. 주도에서는 iOS Safari ITP 문제를 세 계층(운영 문서 + 코드 패턴 + TypeScript 타입 체크)으로 동시에 검증합니다. 한 계층이 뚫려도 다음이 잡습니다. Supabase의 1000행 제한은 코드 작성 단계에서 .select() 호출 위에 예상 행 수 주석을 강제해 차단합니다. 살핌에서는 hookify로 디자인 토큰(Cozy Garden 팔레트)을 자동 강제하고, /peem-role 스킬이 명세서와 RLS 정책의 일치를 자동 대조합니다. 담임 업무에서는 Slack 게시 직전에 AskUserQuestion 설문이 끼어들어, 타이핑 없이 클릭만으로 10초짜리 검수가 됩니다. 50명에게 잘못된 메시지가 퍼지는 사고를 막는 최소 비용 게이트입니다. 보안성검토-하/중/상은 등급별로 검증 강도를 조절하는 글로벌 스킬입니다. "중" 등급에서는 Gemini(공격면 스캔) + Codex(보안 도구) + Sonnet(패턴 매칭) + Opus(교차 검증)가 협업합니다. 북깍스토어에서 이걸 적용해 한 번에 17건의 취약점을 찾았습니다. 만든 AI와 평가하는 AI를 다른 모델·다른 컨텍스트로 분리한 것입니다. 북곽원에서는 PreToolUse 훅이 src/components/design/ 폴더의 Edit/Write를 아예 차단합니다. Variant 디자인 원본에 AI가 손을 대지 못하게 물리적으로 막은 것입니다.

진화. 전역 CLAUDE.md에 검증 가능성 원칙 (Karpathy) 섹션이 별도로 생겼습니다.

- 출력만 보고 "성공"이라 하지 말 것 — exit code/결과를 직접 확인한 후 보고
- LLM은 *지정 가능한 것*이 아니라 *검증 가능한 것*을 자동화한다

OMC verify 스킬은 7레벨(L0 빌드 ~ L7 보안) 체계로 검증을 구조화합니다. autopilot 파이프라인의 Phase 4가 이 검증을 자동 실행합니다.

3.6. 개선(Compound) — 어떻게 계속 나아지는가

이론. 이호연 님의 핵심 공식. 작업 → 관측(세션+사용 패턴) → 패턴 발견 → Skill 또는 Rule → 더 나은 작업. 구체적으로: 3번 반복한 작업 → Skill로 자동화. 3번 틀린 패턴 → Rule 또는 CLAUDE.md에 규칙 추가. 안 쓰는 건 치운다. 모델이 좋아지면 하네스를 재평가한다. 자가 진단의 좋은 신호는 "같은 말을 두 번 하지 않는다", "불필요한 것이 줄어든다", "실수가 규칙이 된다". 나쁜 신호는 "검수에 시간이 더 걸린다", "스킬이 많은데 잘 안 쓴다". WalkingLabs의 강의 11은 "관측 가능성(Observability)이 하네스 안에 있어야 한다"고 강조합니다. 런타임 추적과 디버깅이 가능해야 무엇이 실패했고 왜인지 알 수 있고, 알아야 개선할 수 있습니다. 강의 12는 "매 세션이 깨끗한 상태를 남겨야 한다"고 마무리합니다. PROGRESS.md를 업데이트하고 상태를 정리해야 다음 세션이 오염 없이 시작됩니다. 이 두 강의가 DoRm의 stop-session-protocol.sh(세션 종료 시 구조화된 회고 자동 강제)와 정확히 같은 결을 갖습니다.

DoRm 사례. 주도에는 tasks/ 디렉토리가 있습니다. 매 버그마다 문제→근인→솔루션→검증 4단 구조로 한 파일이 추가됩니다. 비슷한 버그가 다시 나오면 이 폴더를 검색합니다. 북곽원에서는 PostToolUse 훅이 git push main 후 changelog 갱신을 자동 리마인드합니다. 깜빡할 자유 자체가 사라집니다. 앵그리매스의 Decision Log는 현재 D-001부터 D-095까지 95건이 누적되어 있습니다. 모든 코드 변경에 의사결정 사유를 기록하는데, PreToolUse 훅이 src/ 수정 시 docs/decisions.md 동시 수정을 강제합니다. 95건이 쌓이니 재발 패턴이 보이기 시작했습니다. "D-023과 D-067에서도 비슷한 결정이 있었구나"라는 인식이 다음 결정을 더 빠르게 만듭니다.

진화. 이 축에서 진화가 가장 많았습니다.

stop-session-protocol.sh 훅이 세션 종료 시 구조화된 회고를 자동 강제합니다. 작업 요약, 재작업 여부, 사용 모델, 성공/실패 판정, routing-table 자가 점검까지 포함됩니다. 이전에는 Q.E.D. 트리거를 사람이 입력해야 했는데, 이제는 세션이 끝나면 자동으로 회고 절차가 시작됩니다.
tasks/lessons.md → CLAUDE.md 승격 루프가 명문화됐습니다. 세션 중 생기는 교훈은 먼저 tasks/lessons.md에 기록하고, 반복 발생하거나 전역 불변식으로 판단될 때만 CLAUDE.md에 승격합니다.
스킬 우선 원칙이 전역 규칙으로 추가됐습니다. "작업 전 관련 스킬이 있는지 확인 → 있으면 호출." 이미 있는 스킬을 활용하지 않는 것 자체가 위반입니다.
플러그인 정리. superpowers OFF, claude-mem OFF. oh-my-claudecode 하나가 핵심이 됐습니다. 1편에서 "글로벌 스킬 12→5 압축"을 언급했는데, 플러그인도 같은 흐름입니다.

Anthropic의 표현이 이 축을 잘 요약합니다. "하네스의 공간은 모델이 좋아져도 줄어들지 않는다. 이동할 뿐이다."

3.7. 한 달간의 변화 기록 — 무엇이 바뀌고 무엇이 사라졌나

1편을 쓴 뒤 한 달간 전역 하네스에 일어난 변화를 한 곳에 정리합니다. 좋은 하네스는 점점 단순해진다는 원칙이 실제로 작동하고 있는지 확인하는 기록이기도 합니다.

추가된 것:

plan-mode-omc.sh 훅: Plan Mode 진입 시 OMC 플래닝 파이프라인을 자동 강제. 이전에는 "어떤 방식으로 플랜을 세울지"를 사람이 매번 결정했습니다. 플래닝 절차를 깜빡하거나 건너뛰는 일이 잦아서, 훅으로 강제한 것입니다.
검증 가능성 원칙 섹션: 카파시의 "Goal-Driven Execution"을 전역 규칙으로 격상. 이전에는 "확인 잘 해"라는 암묵적 기대만 있었는데, "출력만 보고 성공이라 하지 말 것"이라는 명시적 문장이 필요했습니다. AI가 "완료했습니다"라고 보고하고 실제로는 에러가 있는 일이 반복됐기 때문입니다.
스킬 우선 원칙 섹션: 이미 만들어 둔 스킬을 활용하지 않고 맨바닥부터 시작하는 일이 잦아서 추가. "바퀴를 다시 발명하지 마라"의 하네스 버전입니다.
stop-session-protocol.sh 정교화: 세션 종료 시 AskUserQuestion으로 구조화된 회고를 자동 실행. 이전의 Q.E.D.는 사람이 트리거를 입력해야 했는데, 세션이 끝나면 자동으로 시작됩니다.

사라진 것 (비활성화):

superpowers 플러그인: 비활성화. oh-my-claudecode가 brainstorming, verification, TDD, code review 등 superpowers의 핵심 기능을 대체했습니다. 두 플러그인이 비슷한 스킬을 제공하면서 충돌과 컨텍스트 낭비가 생겼기 때문입니다. 하나를 고르고 나머지를 끈 것입니다.
claude-mem 플러그인: 비활성화. 모든 프로젝트에서 자동으로 Read/Bash를 수집하는 방식이 토큰을 많이 먹었습니다. DoRm에 등록된 프로젝트만 local opt-in으로 기억하는 방식으로 전환했는데, 실질적으로 Serena 메모리와 vault 시스템이 같은 역할을 더 가볍게 수행하고 있어 꺼 두었습니다.
Ralph standalone 플러그인: 이호연 님 발표에서 "Claude Code 공식 Plugin"으로 소개됐지만, DoRm에서는 미사용. oh-my-claudecode:ralph 스킬이 같은 기능을 제공하고, 기본 실행 경로는 autopilot으로 통합됐습니다. "될 때까지 반복"이라는 개념 자체가 사라진 건 아니고, 더 큰 파이프라인(autopilot Phase 0~5)의 일부로 흡수된 것입니다.

바뀐 것:

글로벌 스킬 12→5개 압축 (1편 시점) → 플러그인도 정리 (현재 활성 6개: hookify, frontend-design, codex, rust-analyzer-lsp, wiki-skills, oh-my-claudecode)
P.F./Q.E.D. 수동 트리거 → session-start.sh (자동 맥락 주입) + stop-session-protocol.sh (자동 회고)
Plan Mode 수동 선택 → plan-mode-omc.sh 훅이 OMC 파이프라인 자동 강제

이 변화들의 공통 방향이 있습니다. 수동→자동, 분산→통합, 많은→적은. 한 달 전보다 도구 수는 줄었지만 자동화 수준은 올라갔습니다. 이게 "좋은 하네스는 점점 단순해진다"의 실체라고 생각합니다. 단순해진다는 건 기능이 줄어든다는 뜻이 아니라, 같은 기능을 더 적은 부품으로 돌린다는 뜻입니다.

4. 도구 생태계 — 하네스를 만드는 도구들

하네스를 직접 설계할 수도 있지만, 이미 잘 만들어진 도구를 활용하면 시작이 훨씬 쉽습니다.

4.1. oh-my-claudecode — 하네스의 하네스

DoRm에서 현재 핵심 플러그인으로 쓰고 있습니다. 19개 전문 에이전트와 36개 스킬을 제공합니다. 설치는 npx oh-my-claudecode@latest install 한 줄입니다.

이 플러그인이 재미있는 이유는, 그 자체가 하네스 엔지니어링의 산물이라는 점입니다. 6축 프레임워크의 각 축에 전문 에이전트를 배치한 구조입니다.

카테고리	주요 스킬	하네스 축	하는 일
계획	plan, deep-interview, analyst	Planning	소크라테스식 인터뷰로 요구사항 정제, 3인 합의 플래닝
실행	autopilot, ralph, team, ultrawork	Orchestration	병렬 에이전트 분배, 자율 실행, 팀 협업
검증	verify, critic, code-reviewer, security-reviewer	Verification	7레벨 검증, 코드/보안/아키텍처 병렬 리뷰
분석	tracer, debugger, architect	Context	근본 원인 추적, 경쟁 가설 검증, 설계 자문
개선	self-improve, learner, skillify	Compound	세션에서 패턴 추출, 스킬 자동 생성

왜 이게 효과적인가. 사람이 직접 "이 작업은 Sonnet에게 시키고, 저 작업은 Opus에게 시키자"를 매번 결정하면 인지 부하가 큽니다. oh-my-claudecode는 이 라우팅을 자동화합니다. /autopilot을 호출하면 단순 작업은 Haiku, 표준 작업은 Sonnet, 복잡한 판단은 Opus가 자동 분배됩니다. 사람은 "뭘 만들지"만 정하면 "어떻게 분배할지"는 하네스가 결정합니다.

메인 컨텍스트 보호의 실제. 이 글을 쓰면서 겪은 사례입니다. 블로그 글, PPT, 셀프진단 마크다운, walkinglabs HTML 저장까지 4개 산출물을 동시에 만들어야 했습니다. 독립적인 작업(walkinglabs 저장, 셀프진단 작성)은 백그라운드 에이전트로 보내고, 메인 세션에서는 사용자와의 인터뷰와 블로그 카피 리뷰에 집중했습니다. 만약 이 모든 작업을 한 세션에서 직렬로 했다면, 컨텍스트가 빠르게 차서 앞선 맥락을 놓쳤을 것입니다. 에이전트 분리는 AI의 "기억력"을 보호하는 인프라입니다.

4.2. 기타 활성 플러그인

hookify: 대화 중 발견된 규칙 위반을 훅으로 자동 생성합니다.
codex: GPT 기반 코드 리뷰/디버깅. 멀티모델 교차검증에 활용합니다.
wiki-skills: 카파시 LLM Wiki 패턴의 구현체. wiki-ingest/query/audit/lint.
frontend-design: UI/UX 디자인 품질 보증.

4.3. 이호연 님 추천 도구

발표에서 각 축마다 "TRY IT" 코너로 추천한 도구들입니다.

/scaffold: 프로젝트 초기 구성 자동 생성 (team-attention/harness 플러그인)
/check-harness: 현재 하네스 상태를 체크리스트로 진단
/specify: 인터뷰 → 요구사항 → 플랜 자동화
/qa: Browser Agent/Computer Use 기반 QA 자동화
/agent-orchestrate: 최적 오케스트레이션 패턴 자동 선택

4.4. 시작하기

이호연 님의 마무리 슬라이드에 공감합니다.

이미 잘 만들어진 도구부터 써보기.
내 현재 상태를 진단하기. 본인이 이해 가능한 형태로 하네스를 쓰는 것이 중요합니다.
개선하고 점검하기를 반복. 한꺼번에 다 바꾸려 하지 말 것. 불편한 지점만 하나씩.

⚠ 조심할 점: 하네스를 설계할 때 너무 옥죄려고 하지 말 것. 자유도를 높게 주고, 안 되는 것만 제한하기. 생각보다 에이전트는 예측 가능하게 잘 움직인다.

5. 교육 현장에서의 하네스 엔지니어링

비개발자가 하네스를 구축한 1년

이 글을 쓰면서, 그리고 학생들에게 가르칠 수업을 준비하면서, 한 가지 생각이 선명해졌습니다.

하네스 엔지니어링은 코딩 기술이 아닙니다. 작업 환경을 설계하는 기술입니다. 그렇다면 이 기술은 개발자만의 것이 아닙니다. 교사가, 학생이, 비개발자가 자기 작업에 맞게 AI의 환경을 깔아 줄 수 있습니다. 저는 개발자가 아닌 교사입니다. 그런데도 7개 프로젝트에서 15가지 이상의 하네스를 깔아 왔습니다. 비결이 있는 게 아니라, 매주 AI가 넘어지는 자리에 기둥을 하나씩 박았을 뿐입니다.

1편에서 이렇게 적었습니다. "하네스 엔지니어링은 100명이 있으면 100가지 모양이 나오는 영역입니다." 수학 교사인 저에게는 P.F./Q.E.D.가 자연스럽고, 담임 업무에서는 ㅎㅇ/ㅋㅋ가 자연스럽습니다. 학생들에게도 마찬가지입니다. 정답이 하나인 영역이 아닙니다. 자기에게 맞는 환경을 자기가 만들어 가는 것입니다.

학생들에게 가르치며 발견한 것

방과후 수업에서 바이브코딩을 가르치며 몇 가지를 발견했습니다.

첫째, 학생들은 "해줘"에서 시작합니다. 그리고 그게 자연스럽습니다. 처음부터 Plan Mode를 쓰라고 하면 오히려 흥미를 잃습니다. "해줘"로 시작해서, AI가 엉뚱한 결과를 내면, 그때 "다음에는 이렇게 시켜보자"가 나옵니다. 실패가 학습의 연료입니다. 하네스 엔지니어링도 마찬가지입니다. 처음부터 완벽한 시스템을 설계하려 들지 않는 게 핵심입니다.

둘째, 용어를 배우는 것과 쓸 줄 아는 것은 다릅니다. 2차시에서 Skill, Hook, Plugin, MCP, CLI의 개념을 가르쳤습니다. 학생들은 용어를 알게 됐지만, "그래서 이걸 언제 쓰는 건데?"가 남아 있습니다. 하네스 엔지니어링이라는 프레임워크가 그 다리 역할을 합니다. "AI가 같은 실수를 반복하면 → 그게 Rule이 되고", "위험한 명령을 자동으로 막고 싶으면 → 그게 Hook이 되고". 도구를 배우는 게 아니라, 문제를 만나고, 그 문제에 맞는 도구를 고르는 과정입니다.

셋째, 하네스를 강제하면 안 됩니다. 이호연 님도 같은 말을 했습니다. "옥죄려 하지 말 것. 자유도를 높게 주고, 안 되는 것만 제한하기." 학생마다 만드는 프로젝트가 다르고, 편한 방식이 다릅니다. 누군가에게는 CLAUDE.md 한 파일이면 충분하고, 누군가에게는 Hook 3개가 먼저 필요합니다.

수업에서는 세 가지 사례로 보여줬다

이론만으로는 "그래서 하네스가 뭔데?"가 남습니다. 그래서 수업에서는 제가 실제로 쓰는 하네스를 세 가지 유형으로 나눠 보여줬습니다.

한 번 적어두기. 매번 설명하기 귀찮은 규칙(한국어로 답하기, 위험한 명령은 먼저 물어보기 등)을 전역 CLAUDE.md에 한 번만 적어 두면, 무슨 작업을 하든 자동으로 먼저 읽힙니다. 3장의 맥락·계획·검증·개선 축에서 다룬 전역 설정이 여기에 해당합니다.
잘 만든 걸 가져다 쓰기. 직접 만들지 않아도 됩니다. 남이 공개해 둔 하네스를 통째로 설치해서 씁니다. 4장의 oh-my-claudecode가 그 예입니다.
실수에서 배우기. AI가 놓친 걸 발견하면, 그 자리에서 다시는 안 틀리게 장치를 붙입니다. 3장 5절의 "AI는 눈이 없다" 사례가 그것입니다.

세 유형의 공통점은 하나입니다. **'부탁'이 아니라 '자동'**이라는 것. 한 번 세팅하면 매번 부탁하지 않아도 알아서 지켜집니다. 학생들은 이렇게 나눠 보니 흩어져 있던 도구(Skill·Hook·Rule)를 "언제 쓰는 것인지" 빠르게 잡았습니다.

셀프진단 마크다운 — harness-selfcheck.md

수업에서는 harness-selfcheck.md라는 마크다운 파일을 학생들에게 나눠 줄 계획입니다. 이 파일을 Claude Code에 던지면, AI가 6축 체크리스트로 현재 하네스를 진단하고, 학생이 선택한 영역부터 함께 만들어 나갑니다.

진단은 6축마다 이런 질문으로 시작합니다.

축	진단 질문	잘 되고 있다면
구조	AI가 파일을 어디에 놓을지 바로 아는가?	묻지 않고 맞는 곳에 놓는다
맥락	CLAUDE.md에 기술 스택이 적혀 있는가?	같은 말을 두 번 하지 않는다
계획	"해줘"만 하고 있는가?	AI가 먼저 질문한다
실행	반복 작업을 자동화했는가?	사람은 시작과 확인만 한다
검증	위험한 명령에 안전장치가 있는가?	차단 장치가 작동한다
개선	AI의 실수를 규칙으로 만들었는가?	하네스가 점점 단순해진다

각 질문에 "아니오"가 나오는 축, 그곳이 지금 기둥을 박을 자리입니다.

핵심 설계 원칙이 세 가지입니다.

방향 비강제. "이렇게 해라"가 아니라 "이런 질문을 해볼까?" 방식. 학생이 자기 프로젝트와 스타일에 맞게 선택합니다.
점진적 구축. 빈 CLAUDE.md 하나에서 시작해, AI가 틀릴 때마다 규칙을 한 줄씩 더합니다. 구체적인 순서는 아래 6주 로드맵으로 정리했습니다.
즉시 작동. 진단만 하고 끝나지 않습니다. 진단 결과를 바탕으로 바로 CLAUDE.md, Hook, Skill, Rule을 함께 만듭니다.

6주 로드맵 — 어디서부터 시작할까

진단이 끝나면 한꺼번에 다 바꾸려 들지 말고, 한 주에 하나씩만 더합니다. 수업에서 학생들에게 권한 순서는 이렇습니다.

1주차. 빈 CLAUDE.md 하나 만들기 — 프로젝트 이름과 기술 스택만 적습니다.
2주차. AI가 틀린 것 한 줄 추가하기 — 예: "TODO·임시 코드 금지".
3주차. 세 번 틀린 패턴 → .claude/rules/에 Rule 파일로 분리.
4주차. 세 번 반복한 작업 → .claude/skills/에 Skill로 만들기.
5주차. 위험한 명령 → .claude/hooks/에 Hook으로 차단.
6주차. 안 쓰는 것 정리 — 좋은 하네스는 점점 단순해집니다.

한 주에 기둥 하나면 충분합니다.

6. 마무리 — 좋은 하네스의 세 가지 조건

여러 소스를 종합하면 좋은 하네스의 조건이 세 가지로 수렴합니다.

1. 점점 단순해진다. 이호연 님의 표현입니다. "복잡해지고 있다면 뭔가 잘못된 것." 1편에서 글로벌 스킬 12→5 압축을 보고했는데, 한 달 뒤에 플러그인 정리(superpowers OFF, claude-mem OFF)가 이어졌습니다. 좋은 하네스는 모델이 좋아질수록 불필요한 가드레일을 치우고, 정말 필요한 것만 남깁니다.

2. 검증 가능한 것을 자동화한다. 카파시의 원칙입니다. "LLM은 지정 가능한 것이 아니라 검증 가능한 것을 자동화한다." "잘 해"가 아니라 "이 기준을 충족해". 출력만 보고 "성공"이라 하지 말고, exit code와 결과를 직접 확인한 후 보고하라.

3. 실수가 구조적으로 재발하지 않는다. Hashimoto의 철학입니다. "에이전트가 실수하는 모습을 발견할 때마다, 그 실수를 다시 하지 않도록 시간을 들여 시스템을 손본다." 그리고 그 손본 흔적 한 줄 한 줄이 쌓여 결국 거의 모든 잘못된 행동이 사라진다. "다음에 잘 해"가 아니라 시스템을 바꾸는 것입니다.

1편의 마지막 문장을 다시 쓰겠습니다.

AI가 코드를 쓰는 시대에, 사람의 역할은 "잘 짜기"에서 "잘 일하는 환경을 만들기"로 바뀌고 있습니다. 어디서부터 시작해야 할지 모르겠다면, 빈 마크다운 파일 하나를 만드시기를 추천드립니다. 거기에 매일 한 줄씩, AI가 빠뜨리던 것을 적으세요. 한 달이 지나면 그 파일이 첫 번째 하네스가 되어 있을 것입니다. 넘어지는 자리에만 기둥을 박으세요. 그게 결국 가장 빠른 길입니다.

이 글에서 언급한 하네스 엔지니어링 셀프진단 마크다운(Claude Code에 던지면 6축 진단 + 하네스 구축을 함께 해주는 문서)과 수업에서 활용하는 PPT 자료는 인스타그램 @dorm_edu 또는 오픈카톡을 통해 공유받으실 수 있습니다.