28 스타짜리 신생 코스가 트렌딩 24위에 진입한 이유. OpenAI "Harness Engineering" 블로그와 Anthropic "Effective Harnesses for Long-Running Agents"를 종합해 만든 12강 + 6 프로젝트 커리큘럼. 핵심 주장: 모델이 강해도 환경이 엉터리면 끝까지 못 간다. 같은 Opus 4.5에 "2D 레트로 게임 에디터 만들어"를 시켰을 때, harness 없으면 20분 $9에 안 돌아가는 결과, harness 있으면 6시간 $200에 진짜 플레이되는 게임을 만든다. 모델은 그대로다 — harness만 바뀌었다. 13개 언어로 번역된 한국어 자료도 있다.
"프롬프트 잘 쓰는 법"이 아니라 "AI 에이전트가 살아 일하는 환경을 짓는 법"을 가르치는 수업.
대부분의 "AI 코딩" 콘텐츠는 두 갈래다. ① 프롬프트 잘 쓰기 — "이런 식으로 시키면 결과가 좋아진다", ② 에이전트 내부 구조 — "ReAct, Tool-use, Agent loop, MCP가 어떻게 작동하는가". learn-harness-engineering은 완전히 다른 세 번째 갈래를 판다.
이 코스의 주장은 명료하다. Codex·Claude Code 같은 코딩 에이전트는 모델 자체보다 "에이전트를 둘러싼 작업 환경"이 결과를 더 크게 좌우한다. 같은 모델이 어떤 레포에서는 5분 만에 멋대로 망쳐 놓고, 옆 레포에서는 6시간 동안 차분히 한 기능씩 끝낸다. 차이는 모델이 아니라 그 레포 안에 깔린 "harness"다.
F1 드라이버를 떠올려 보자. 같은 드라이버를 평범한 도로용 세단에 태우면 사고만 친다. 그 드라이버에게 필요한 건 더 좋은 운전 실력이 아니라 — F1 머신, 피트 크루, 무전 시스템, 코스 가드레일이다. 모델은 드라이버, harness는 차+크루+가드레일. 코스에서는 "드라이버를 어떻게 키우나"가 아니라 "어떤 머신·크루·가드레일을 짜야 드라이버가 끝까지 완주하나"를 가르친다.
2025년 4분기~2026년 1분기 사이, OpenAI("Harness engineering: leveraging Codex in an agent-first world")와 Anthropic("Effective harnesses for long-running agents" 2025-11, "Harness design for long-running application development" 2026-03) 두 곳이 같은 메시지의 엔지니어링 블로그를 냈다. Cursor, LangChain, Thoughtworks(Martin Fowler) 도 곧이어 자신들의 harness 글을 올렸다. 업계가 "모델은 충분히 똑똑하다, 문제는 환경"으로 합의한 것이다. 그 합의를 가장 빨리 정리해 코스로 만든 게 이 레포다.
28 스타짜리 신생 레포가 1만 스타 이상의 거대 프로젝트들과 어깨 나란히 한 이유.
Trendshift는 GitHub Trending과 달리 절대 스타 수가 아니라 24시간/주 단위의 멘션·스타 증가율을 본다. 28 스타지만 그게 며칠 사이에 모인 거라면 1만 스타 레포보다 더 위에 뜬다. Anthropic·OpenAI 공식 블로그가 동시에 화제가 된 직후 등장했고, 트위터·해커뉴스에서 "이 두 글을 코스로 정리해 둔 레포"로 입소문이 났다.
강의(L01~L12)는 개념을, 프로젝트(P01~P06)는 같은 Electron 지식 베이스 앱을 6단계에 걸쳐 점점 더 진짜 harness 위로 옮긴다. 매 프로젝트의 결과물이 다음 프로젝트의 시작점이 된다. "읽기만 해도 되는 책"이 아니라 "매 챕터마다 같은 앱이 더 잘 작동하도록 코드를 짜는 코스"다.
12강을 다 안 읽어도 README의 "Quick Start" 한 섹션만 보고 AGENTS.md + init.sh + feature_list.json + claude-progress.md 4개를 내 레포에 떨궈도 효과가 즉시 보인다. 이 "오늘 당장 써먹을 수 있는 최소 구성" 미끼가 트래픽 진입점이 된다.
대부분의 신생 영문 코스가 못 따라가는 게 i18n인데, 이 레포는 처음부터 한국어·중국어(간/번)·일본어·스페인어·프랑스어·러시아어·독일어·아랍어·베트남어·우즈벡어·튀르키예어까지 번역본을 깔고 시작했다. 한국·중국·일본 개발자 트위터에서 빠르게 공유된 이유.
| 비교 대상 | 주력 | 이 레포의 차이 |
|---|---|---|
obra/superpowers | Claude Code 스킬 모음 | "바로 쓸 스킬" vs "왜·어떻게 환경을 짜야 하나"의 이론+실습 |
hesreallyhim/awesome-claude-code | 큐레이션 링크 리스트 | 리스트가 아니라 12강짜리 강의식 커리큘럼 |
shareAI-lab/learn-claude-code | Claude Code 자체 사용법 | "클로드 코드 쓰는 법"이 아니라 "어떤 코딩 에이전트에서도 통하는 환경 설계 원리" |
| OpenAI / Anthropic 공식 블로그 | 1편짜리 사례 글 | 흩어진 사례들을 12강 + Electron 캡스톤으로 묶음 |
강의 L02가 정의하는 5개 부품. 이게 코스 전체의 어휘이자 측정 단위다.
코스 전체에서 가장 중요한 한 장이 L02다. 여기서 정의한 5개 서브시스템을 가지고 나머지 11강과 6 프로젝트가 돌아간다.
"무엇을, 어떤 순서로, 시작 전 무엇을 읽어야 하는지"를 알려주는 파일들. 핵심 원칙은 한 거대한 파일이 아니라, 에이전트가 필요할 때 골라 읽을 수 있는 작은 파일들의 트리로 쪼개는 것. L04가 이 원칙을 다룬다.
이번 세션에서 무엇이 됐고, 무엇이 안 됐고, 다음에 뭘 해야 하는지를 디스크에 적어 두는 파일들. 컨텍스트 윈도우는 휘발성이지만 디스크는 영속적이다. 다음 세션의 첫 줄이 "이 파일들을 다시 읽어라"가 되는 순간, 에이전트가 며칠 전 작업을 이어 받는다. L05·L06이 이 부분.
"내가 다 했어요"라는 에이전트의 말을 그대로 믿지 않는 장치. 테스트·린트·타입체크·스모크 실행이 통과해야만 "끝났다"고 인정. L09는 "에이전트가 너무 일찍 끝났다고 선언하는" 문제를 다룬다.
학생이 "공부 다 했어요"라고 말한다고 부모가 그대로 믿어 주지 않는다. 모의고사 점수를 봐야 한다. 모델도 똑같다 — "구현 끝났다"는 자기 평가는 자신감일 뿐, 정답이 아니다. 통과한 테스트만이 증거다.
에이전트가 한 번에 한 기능만 잡게 가두는 장치. feature_list.json에 "지금 작업 가능한 기능"을 못박아 두면, 에이전트가 갑자기 옆 폴더까지 리팩토링하거나 3개를 반쯤 하다 도망가는 걸 막을 수 있다. L07·L08이 이 부분.
세션 시작 시 init.sh로 환경을 점검하고, 끝날 때는 clean-state-checklist로 정리한 다음, 다음 세션이 이어받을 수 있게 핸드오프 노트를 남기고 git commit. "세션은 자유분방한 작업이 아니라, 정해진 라이프사이클을 따른다"가 L12의 메시지.
12강을 다 듣지 않아도, 이 4개 파일을 내 레포에 떨구는 것만으로 세션 안정성이 즉시 올라간다.
이 레포의 명령 규칙·금지 사항·세션 시작 시 해야 할 것·끝낼 때 해야 할 것을 적은 파일. 단, 100KB짜리 위키가 되어선 안 된다. "이 파일은 지도다, 자세한 건 docs/ 아래에서 골라 읽어라" 식으로 점진적 공개를 의도해야 한다.
의존성 설치(INSTALL_CMD) → 검증(VERIFY_CMD) → 시작(START_CMD)을 차례로 돌린다. 검증이 깨져 있으면 "환경이 망가져 있으니 작업하지 마라"를 에이전트가 즉시 알게 된다. L06이 "초기화가 별도 단계여야 하는 이유"를 다룬다.
각 기능에 status(todo/in_progress/done), verification(어떻게 검증할지), evidence(검증 통과 증거)를 박아둔다. 에이전트는 이 파일을 보고 딱 하나의 미완료 기능을 골라 작업한다. "이번 한 시간 동안 너는 이 1개만 한다, 끝나면 status를 done으로 바꿔라"가 가능해진다.
매 세션 끝에 "오늘 뭘 했고, 무엇이 검증됐고, 무엇이 깨져 있는지"를 적는다. 다음 세션이 시작할 때 가장 먼저 이 파일을 읽으면, 며칠 전의 작업을 정확히 이어 받는다. 컨텍스트 윈도우가 비어도 디스크는 안 빈다가 핵심.
강의는 "왜 모델이 실패하나?" 질문 12개를, 프로젝트는 같은 Electron 앱을 6단계로 진화시킨다.
| 강의 | 핵심 질문 | 핵심 아이디어 |
|---|---|---|
| L01 | 왜 강한 모델이 진짜 작업에선 실패하나? | 벤치마크와 진짜 엔지니어링 사이의 능력 갭 |
| L02 | "Harness"는 도대체 뭔가? | 5개 서브시스템 — 명령·상태·검증·범위·라이프사이클 |
| L03 | 왜 레포가 유일한 진실의 원천이어야 하나? | 에이전트가 볼 수 없는 건 존재하지 않는다 |
| L04 | 왜 하나의 거대한 명령 파일은 실패하나? | 점진적 공개 — 백과사전이 아니라 지도 |
| L05 | 왜 긴 작업에서 연속성이 끊기나? | 진행 상황을 디스크에 영속화하라 |
| L06 | 왜 초기화가 별도 단계여야 하나? | 작업 전 환경 헬스 체크 |
| L07 | 왜 에이전트는 넘치게 하고 모자라게 끝내나? | 한 번에 한 기능 + 명시적 "끝의 정의" |
| L08 | 왜 feature list가 하니스의 원시 구성요소인가? | 기계가 읽는 범위 경계 — 에이전트가 무시 못함 |
| L09 | 왜 에이전트는 너무 일찍 "끝!"이라 하나? | 검증 갭 — 자신감 ≠ 정확함 |
| L10 | 왜 E2E 테스트가 결과를 바꾸나? | 전체 파이프라인 통과만이 진짜 검증 |
| L11 | 왜 관측성이 harness 안에 있어야 하나? | 못 본 것은 못 고친다 |
| L12 | 왜 모든 세션은 깨끗한 상태로 끝나야 하나? | 다음 세션의 성공은 이번 세션의 정리에 달려 있다 |
| 프로젝트 | 하는 일 | 도입 메커니즘 |
|---|---|---|
| P01 | 같은 작업을 프롬프트만 vs 규칙 우선, 둘 다 돌려보고 비교 | 최소 하니스 (AGENTS.md + init.sh + feature_list.json) |
| P02 | 에이전트가 읽을 수 있게 레포 재구조화 | agent-readable workspace + 영속 상태 파일 |
| P03 | 에이전트가 이전 세션 이어받게 만들기 | progress 로그 + 세션 핸드오프 |
| P04 | 에이전트가 넘치거나 모자라지 않게 막기 | 런타임 피드백 + 범위 통제 + 증분 인덱싱 |
| P05 | 에이전트가 자기 작업을 스스로 검증하게 만들기 | self-verification + grounded Q&A + 증거 기반 완료 |
| P06 | 밑바닥부터 완전한 harness 짓기 (캡스톤) | 풀 하니스 + 관측성 + 어블레이션 스터디 |
핵심 미덕은 P(N+1)의 시작점이 P(N)의 결과물이라는 것. 그래서 같은 앱이 1개의 문서도 없던 P01에서 풀 하니스가 깔린 P06까지 점진적으로 진화한다.
왜 굳이 Electron 데스크탑 앱을 캡스톤으로 골랐는가.
왜 굳이 Electron? 코스가 의도적으로 고른 이유는 "실제 제품 같은 복잡성"이다. 메인 프로세스 / 렌더러 프로세스 분리, IPC, 파일 시스템 권한, 패키징 빌드 등 — 단일 파일 스크립트로는 안 잡히는 복잡한 다층 구조를 가진 앱. 이 정도 복잡도가 있어야 "harness 있을 때 / 없을 때" 차이가 진짜로 드러난다.
각 프로젝트 폴더는 starter/(작업 시작 시점의 코드)와 solution/(완료 시점의 코드)을 모두 가진다. 진도가 막히면 solution을 보면 되고, 다음 프로젝트는 이 solution을 시작점으로 받는다. "내 진도가 코스 의도와 어긋났는지"를 매 단계 자가 진단할 수 있다.
코스 사이트 + 캡스톤 앱이 어떤 기술로 짜였는지.
| 레이어 | 기술 | 역할 |
|---|---|---|
| SSG 엔진 | VitePress | Vite + Vue 기반 정적 사이트 생성기. docs/ 안의 마크다운을 페이지로 뽑는다 |
| 호스팅 | GitHub Pages | walkinglabs.github.io/learn-harness-engineering/ |
| i18n | VitePress locales | docs/en/, docs/zh/, docs/ko/ ... 13개 디렉토리 |
| PDF 빌드 | npm 스크립트 + Actions | npm run pdf:build → artifacts/pdfs/ → Releases 자동 업로드 |
| 스크린샷 | screenshots:readme | README 미리보기 이미지 자동 재생성 |
| 레이어 | 기술 | 왜 이 조합인가 |
|---|---|---|
| 데스크탑 셸 | Electron | Mac·Windows·Linux 멀티플랫폼 + 파일시스템 접근 + 로컬 LLM 가능 |
| UI | React + TypeScript | 현대 프론트엔드 표준 — 학생이 이미 알 가능성 높음 |
| 빌드 | Vite (추정) | VitePress와 같은 생태계, 핫리로드 빠름 |
| 인덱싱 | 로컬 임베딩 + RAG (프로젝트별) | P04에서 증분 인덱싱이 등장 |
| Q&A | 로컬 목(mock) 키워드 매칭 (shared 기준) | 공통 스타터에는 mock Q&A; P04~P05에서 학생이 실제 LLM API로 교체하는 것이 학습 목표 |
| 파일 | 포맷 | 역할 |
|---|---|---|
AGENTS.md / CLAUDE.md | Markdown | 에이전트의 운영 매뉴얼 |
init.sh | Shell (Bash) | install + verify + start, 1회용 부팅 스크립트 |
feature_list.json | JSON | 기계 가독 작업 범위, status/verification/evidence |
claude-progress.md | Markdown | 세션 간 핸드오프 일기 |
session-handoff.md | Markdown | 축약형 세션 종료 노트 — 다음 세션 첫 줄에 읽힘 |
clean-state-checklist.md | Markdown | 세션 끝나기 전 체크박스 리스트 (커밋 안전한가?) |
evaluator-rubric.md | Markdown | 에이전트 작업물 채점 루브릭 |
주목할 점: harness 자체는 새 프로그래밍 언어도, 새 라이브러리도 아니다. 그냥 잘 정의된 약속의 마크다운/JSON/셸 스크립트 묶음이다. 이 단순함이 의도된 것 — 어떤 코딩 에이전트(Claude Code, Codex, Cursor, Aider, Roo Code…)에서도 그대로 동작한다.
레포를 클론하면 만나는 파일들이 각각 무슨 역할인지.
이 레포의 루트에 CLAUDE.md가 있다. 즉 "harness 코스를 짜는 작업 자체도 harness로 운영된다". 이건 "스스로 짜는 컴파일러"처럼 일종의 자기 적용(self-application). 메인테이너 본인이 자기가 가르치는 방법으로 자기 코스를 만들었다는 신호 — 신뢰도 있는 코스의 흔한 마크.
이 레포를 한 번 훑으면 인범님이 얻게 되는 구체적인 역량들.
AGENTS.md / CLAUDE.md를 점진적 공개로 설계하는 패턴init.sh로 세션 시작 헬스 체크 자동화feature_list.json으로 에이전트의 범위 폭주를 막는 기법claude-progress.md로 며칠 단위 작업의 연속성 확보.github/workflows/release-course-pdfs.yml 참고)한성크린텍 업무 자동화 스크립트든 작업일보 앱이든, 손에 잡히는 레포 한 곳을 정해서 AGENTS.md + init.sh + feature_list.json + claude-progress.md 4개를 1시간 만에 깔아 보고, 다음 주 1주일 동안 Claude Code 세션을 그 위에서 돌려본다. 1주일 후 "수정 횟수"가 얼마나 줄었는지를 직접 측정해 본다.
코스를 따라가려면 무엇이 필요한가.
| 항목 | 요구 | 비고 |
|---|---|---|
| OS | macOS / Linux / Windows | Electron이 동작하는 모든 OS |
| Node.js | 최신 LTS (v20+ 권장) | VitePress + Electron 빌드용 |
| npm | 10+ | npm install 시점에 확인 |
| 코딩 에이전트 | Claude Code · Codex · 유사 IDE/CLI 중 최소 하나 | 파일 편집 + 명령 실행 + 멀티스텝 작업 가능해야 |
| LLM API | OpenAI · Anthropic · Gemini 중 하나의 API 키 | 캡스톤 Q&A 동작용 |
| 디스크 | ~2GB | node_modules + Electron 바이너리 |
| RAM | 8GB+ 권장 | VitePress dev + Electron + IDE 동시 사용 |
| 네트워크 | 안정적인 인터넷 | npm 설치 + LLM API 호출 |
비싼 GPU도, 로컬 LLM도 필요 없다 — 코스의 초점은 "모델 자체"가 아니라 "모델 주변 환경"이기 때문이다. 노트북 한 대면 끝까지 갈 수 있다.
코스 자체와 별개로 인범님이 손에 잡힐 만한 과제 5개.
현재 다루고 있는 작은 레포 하나에 docs/en/resources/templates/AGENTS.md 템플릿을 복사해 떨궈본다. 거기 적힌 INSTALL_CMD·VERIFY_CMD·START_CMD 세 자리만 내 프로젝트에 맞게 바꾼다. 그날 저녁 Claude Code 세션이 어떻게 달라지는지 관찰. 한 줄 평을 메모리에 남기기.
smart-work-report-20251226 같은 진짜 일하는 앱에 feature_list.json을 짜본다. "WIR_JOINTS 조회 탭", "FMCS 엑셀 생성", "출역 동기화" 등을 항목으로 분해하고 각각의 verification(어떻게 됐다고 판단할지)을 적는다. 이 작업 자체가 "내 프로젝트의 정의를 다시 보는 일"이 된다.
projects/project-01-baseline-vs-minimal-harness/starter/를 클론해서 같은 기능을 두 번 짠다 — 첫 번째는 그냥 프롬프트로, 두 번째는 4파일 하니스를 깔고. 끝난 후 각각 ① 사람이 손댄 횟수, ② 테스트 통과 비율, ③ 소요 시간을 표로 비교한다. 이 차이를 본 사람과 안 본 사람은 다른 멘탈 모델을 가진다.
P03을 따라 "세션 1에서 절반 짜다 일부러 중단 → 세션 2에서 무에서 이어 받기"를 성공시킨다. 그 다음 P05를 따라 에이전트가 자기 결과물을 verification 기록 없이는 "끝났다" 못 외치게 막는 패턴을 구현한다. harness 작동의 두 번째 단계 — 단순한 4파일을 넘어서 "에이전트 행동을 강제하는 구조"로 진입.
daily-report나 sup-bom-sync처럼 인범님이 매주 돌리는 스킬 중 하나를 골라, 코스의 6 프로젝트 패턴을 그대로 자기 자신에게 적용한다. P01(비교) → P02(워크스페이스) → P03(연속성) → P04(범위) → P05(자가검증) → P06(관측성)을 한 단계씩. 다 끝나면 이 스킬은 사람이 한 번 시작 명령 내리면 다음 주까지 알아서 돌아간다.
이 코스를 끝낸 후 인범님이 자연스럽게 갈 만한 다음 단계.
skills/harness-creator/ 스킬을 내 다른 프로젝트에 깔아 보기코스 안에서 반복적으로 나오는 용어들 — 한 번에 정리.
npm run docs:dev로 핫리로드 개발 모드, npm run docs:build로 정적 사이트 빌드.코스 전체를 한 문장으로 압축하면.
코스를 다 듣지 않아도, README의 Quick Start에 적힌 4파일(AGENTS.md·init.sh·feature_list.json·claude-progress.md)을 진짜 일하는 레포 한 군데에 떨궈 보면 메시지가 손에 잡힌다. 이게 코스 전체의 "MVP 증명"이고, 그래서 28 스타짜리 신생 레포가 트렌딩 24위에 진입했다.
5min-ai-news나 smart-work-report-20251226 같은 거.docs/en/resources/templates/에서 4개 템플릿 다운로드 → 내 레포 루트에 복사 → INSTALL_CMD·VERIFY_CMD·START_CMD 자리만 내 프로젝트에 맞게 변경. 끝.P02로 진입.코스 본체 + 코스가 인용하는 원본 블로그들.