🤖 레슨

하네스 — AI가 일하는 작업장 짓기

하네스는 AI를 둘러싼 '작업 환경 전체'를 뜻해요. 고정 규칙(hook·skill)은 바닥, 그때그때 짜는 워크플로우는 천장.

① 오늘의 미션

가게의 규칙과, 가게의 큰 공사

'우리동네 반찬가게'를 운영하다 보면 두 종류의 일이 있어요. 하나는 매번 반드시 지켜야 하는 것 — "유통기한 지난 반찬은 절대 안 올린다." 다른 하나는 그때그때 크게 벌어지는 일 — "추석 명절 특가 페이지를 통째로 새로 짠다."

이 코스의 마지막인 오늘, 이 둘을 한 건물로 합쳐봅니다. 늘 지켜야 할 규칙은 정적 장치(바닥)로, 큰 작업의 지휘는 동적 워크플로우(천장)로 — 이게 에이전트 시대의 구조물, 하네스(harness)예요.

설명을 따라 진행하면, 여기서 직접 쳐보게 돼요 👇

~/my-shop

$ _

📚 「하네스 — AI가 일하는 작업장 짓기」 레슨 내용 전체 텍스트로 훑어보기

가게의 규칙과, 가게의 큰 공사

지금까지 배운 도구들을 한 건물에 올려볼게요.

하네스 = 바닥 + 천장

🟫 바닥(정적 방어층) — 항상 켜져 있어요. hook·rule(CLAUDE.md)·skill. 작업이 무엇이든 늘 깔려 있는 안전판. 한 번 깔면 매번 자동으로 작동.
🟦 천장(동적 워크플로우) — 큰 작업이 들어올 때마다 런타임에 새로 짜요. "이번 추석 페이지는 기획→디자인→상품등록→점검 순서로" 같은 지휘.

바닥은 한 번 깔고 잊는 것, 천장은 필요할 때마다 세우는 것. 이 둘이 한 구조에 있어야 가게가 안전하면서도 크게 자라요.

'유통기한 지난 반찬은 절대 페이지에 안 올린다' — 이 규칙은 하네스의 어디에 두어야 할까요?

맞아요. 매번 지켜야 하는 건 바닥이에요. 큰 작업마다 일일이 지시하면(천장) 언젠가 빠뜨려요. 한 번 정적 장치로 깔면 작업이 무엇이든 늘 작동합니다.

같은 가게를 떠받치지만 성격이 정반대예요. 둘을 비교해보세요.

🟫 바닥 — 정적 방어층: hook · rule · skill
· 항상 켜짐 — 작업과 무관하게 늘 작동
· 한 번 설치 → 매번 자동
· 역할: 실패를 막는다 (안전·일관성)
· 예: "유통기한 지난 반찬 등록 차단" hook

🟦 천장 — 동적 워크플로우: 그때그때 짜는 오케스트레이션
· 작업마다 새로 — 런타임에 작성
· 상황 보고 길을 정함
· 역할: 큰 일을 지휘한다 (규모·유연)
· 예: "추석 특가 페이지 통째로 만들기" 워크플로우

먼저 바닥부터. 우리 가게 폴더에 깔린 정적 장치들을 열어봐요. hook 코스에서 만든 그 등록부예요.

cat .claude/settings.json — 바닥에 깔린 hook을 들여다봐요

cat CLAUDE.md — 늘 켜진 규칙(rule)도 확인

이 둘이 바닥이에요. 내가 무슨 작업을 시키든 이 장치들은 늘 깔려 작동해요. 다음은 그 위에 세울 천장이에요.

바닥(PreToolUse hook)이 깔린 상태에서, Claude에게 유통기한이 지난 '시금치무침'을 페이지에 올려줘라고 시키면 어떻게 될까요?

맞아요. 바닥이 막아줘요. 내가 실수로 시켜도, AI가 무심코 따르려 해도, PreToolUse 장치가 '직전'에 차단합니다. 실패모드를 글이 아니라 장치로 막는다 — 이게 하네스 사상의 핵심이에요.

이제 천장. 작은 명령이 아니라 큰 작업을 통째로 맡겨봐요. Dynamic Workflows 레슨에서 본 것처럼, Claude가 상황을 보고 스스로 순서를 짭니다.

이번 추석 명절 특가 페이지를 통째로 만들어줘. 기획부터 상품 등록, 점검까지 알아서 진행해줘

— 큰 작업을 통째로 지휘 맡겨요

보이시죠? Claude가 고정 순서가 아니라 이 작업에 맞는 순서를 그 자리에서 짰어요(천장). 그리고 ③등록 단계에서 바닥의 hook이 그대로 작동했죠 — 천장이 새로 서도 바닥은 늘 깔려 있어요.

하네스의 이중 구조를 한 문장으로. 빈칸에 들어갈 말은?

정답은 정적(static). 정적 바닥 + 동적 천장, 이 두 글자가 하네스의 전부예요. 바닥은 변하지 않고 늘 작동, 천장은 작업마다 변하며 새로 선다.

둘이 한 건물에서 같이 도는 걸 눈으로 봐요. 큰 작업을 맡기되, 일부러 규칙을 어기는 실수를 섞어 시켜볼게요.

특가 페이지에 반찬 6종 올려줘. 그 중 '오래된 멸치볶음'도 같이 넣어줘 — 규칙 위반이 섞인 큰 작업을 맡겨요

ls pages/chuseok/ — 결과 페이지 목록을 확인

천장(동적 워크플로우)은 6종을 척척 진행했지만, 바닥(hook)은 딱 하나, 규칙 위반만 정확히 막았어요. 큰일은 유연하게, 지켜야 할 선은 단단하게 — 한 건물에서 동시에.

새 가게에 하네스를 세운다면, 어떤 순서로 갈까요? (바닥부터 천장으로)

맞아요. 바닥을 먼저 깔고 천장을 올립니다. 안전판 없이 큰 작업부터 벌이면, 실수 하나가 그대로 사고가 돼요. 막을 것을 먼저 막고, 그 위에서 크게 일한다.

그런데 왜 굳이 바닥을 깔까요? AI에게 큰 작업을 맡길 때 자주 나는 실패가 있기 때문이에요. 대표 3종.

에이전트의 3대 실패모드

· 부분 완료(agentic laziness) — "다 했어요" 했지만 6종 중 4종만 올림. 끝까지 안 함.
· 자기 편향 — 자기가 짠 길이 맞다고 우기며 더 나은 방법을 외면.
· 목표 이탈 — 처음 시킨 '추석 페이지'에서 슬슬 벗어나 엉뚱한 걸 만듦.

이 셋은 부탁(글)으로는 잘 안 막혀요. 그래서 바닥이 필요해요 — "6종 다 올라왔는지 점검하는 hook", "최종 결과가 목표와 맞는지 검사하는 Stop hook"처럼 장치로 막는 거죠.

AI가 '부분 완료'(6종 중 4종만 올리고 끝냄)를 자주 한다면, 하네스에서 어떻게 막는 게 가장 단단할까요?

맞아요. 글로 부탁하면 AI는 또 잊어요(확률적). 완료를 검사하는 hook은 매번 반드시 도는 코드(결정적)라 부분 완료를 빠짐없이 잡아냅니다. 실패모드는 의지가 아니라 장치로 막는다 — 하네스의 결론이에요.

한 건물로

에이전트 시대의 구조물은 바닥 + 천장이에요. 매번 지켜야 할 것은 정적 장치(hook·rule·skill)로 바닥에, 큰 작업의 지휘는 동적 워크플로우로 천장에. hook 코스와 Dynamic Workflows가 오늘 한 건물로 합쳐졌어요. 이게 하네스(harness)입니다.

다음 레슨 예고 — 하네스 엔지니어링

그런데 이상한 일이 하나 있어요. 옆 동네 반찬가게도 똑같은 AI를 쓰는데, 왜 우리 가게만 사고 없이 척척 돌아갈까요? 비밀은 모델이 아니라 이 건물을 설계하는 솜씨에 있어요. 다음 레슨에서 그 설계 기술 — 하네스 엔지니어링을 배웁니다. 🛠️