Skip to content

Harness engineering beginner tutorial, from 0 to 1

feat(docs): add Korean (ko) locale with full translation

Teddy Leee492130d4b0d
diff --git a/README-CN.md b/README-CN.md
index df6462b..936a8d2 100644
--- a/README-CN.md
+++ b/README-CN.md
@@ -1,3 +1,5 @@
+[English](https://walkinglabs.github.io/learn-harness-engineering/en/) · [中文](https://walkinglabs.github.io/learn-harness-engineering/zh/) · [Русский](https://walkinglabs.github.io/learn-harness-engineering/ru/) · [Tiếng Việt](https://walkinglabs.github.io/learn-harness-engineering/vi/) · [한국어](https://walkinglabs.github.io/learn-harness-engineering/ko/)
+
# Learn Harness Engineering
> **这是一门项目制课程:系统学习如何通过环境、状态、验证与控制机制,让 AI 编程智能体(Coding Agents)更可靠地工作。**
diff --git a/README-KO.md b/README-KO.md
new file mode 100644
index 0000000..f18de4c
--- /dev/null
+++ b/README-KO.md
@@ -0,0 +1,522 @@
+[English](https://walkinglabs.github.io/learn-harness-engineering/en/) · [中文](https://walkinglabs.github.io/learn-harness-engineering/zh/) · [Русский](https://walkinglabs.github.io/learn-harness-engineering/ru/) · [Tiếng Việt](https://walkinglabs.github.io/learn-harness-engineering/vi/) · **한국어**
+
+# Learn Harness Engineering
+
+> **AI 코딩 에이전트(coding agent)가 안정적으로 동작하도록 환경, 상태 관리, 검증(verification), 제어 메커니즘을 구축하는 프로젝트 기반 강의입니다.**
+
+Learn Harness Engineering은 AI 코딩 에이전트 공학에 전념하는 강의입니다. 업계에서 가장 앞선 해네스 엔지니어링(Harness Engineering) 이론과 실천을 깊이 연구하여 종합했습니다. 핵심 참고 자료는 다음과 같습니다.
+
+- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
+- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
+- [Awesome Harness Engineering](https://github.com/walkinglabs/awesome-harness-engineering)
+
+> **빠르게 시작하려면?** [`skills/harness-creator/`](./skills/) 스킬(skill)을 사용하면 몇 분 만에 프로덕션 수준의 해네스(AGENTS.md, 기능 목록, init.sh, 검증 워크플로우)를 직접 프로젝트에 스캐폴딩(scaffold)할 수 있습니다.
+
+---
+
+## 시각적 미리보기
+
+### 강의 홈페이지
+> 핵심 철학을 소개하고 시작 경로를 명확히 제시하는 종합 강의 개요입니다.
+
+![강의 홈페이지 미리보기](./docs/public/screenshots/readme/en-home.png)
+
+### 몰입형 강의
+> 실제 문제 상황을 심층적으로 분석하고 실습 프로젝트(예: Project 01)를 통해 몰입 학습 경험을 제공합니다.
+
+![강의 미리보기](./docs/public/screenshots/readme/en-lecture-01.png)
+
+### 즉시 사용 가능한 리소스 라이브러리
+> 다중 턴 AI 에이전트 개발 시 흔히 발생하는 컨텍스트(context) 손실, 과도한 완료 선언 등의 문제를 해결하기 위해 설계된 템플릿과 참고 설정 모음입니다.
+
+![리소스 라이브러리 미리보기](./docs/public/screenshots/readme/en-resources.png)
+
+## PDF 강의 교재
+
+저장소에는 강의 콘텐츠를 위한 PDF 빌드 파이프라인이 포함되어 있습니다.
+
+- `npm run pdf:build` 명령으로 영어·중국어 PDF를 로컬에서 생성할 수 있습니다.
+- 출력 파일은 `artifacts/pdfs/`에 저장됩니다.
+- README 미리보기 이미지를 갱신하려면 `npm run screenshots:readme`를 실행하십시오.
+- GitHub Actions 워크플로우 [`release-course-pdfs.yml`](./.github/workflows/release-course-pdfs.yml)을 통해 PDF를 빌드하고 GitHub Releases에 게시할 수 있습니다.
+
+---
+
+## 모델은 스마트하고, 해네스가 안정성을 만든다
+
+대부분의 사람들이 직접 경험한 뒤에야 깨닫는 냉혹한 진실이 있습니다. **세상에서 가장 강력한 모델도 적절한 환경 없이는 실제 엔지니어링 작업에서 실패합니다.**
+
+아마 직접 겪어보셨을 것입니다. Claude나 GPT에게 저장소(repository)에서 작업을 맡깁니다. 처음에는 잘 진행됩니다 — 파일을 읽고, 코드를 작성하고, 생산적으로 보입니다. 그러다 뭔가 잘못됩니다. 단계를 건너뜁니다. 테스트를 망칩니다. "완료"라고 하지만 실제로는 아무것도 동작하지 않습니다. 직접 했더라면 더 빨랐을 시간을 수습에 써버립니다.
+
+이것은 모델 문제가 아닙니다. 해네스 문제입니다.
+
+증거는 명확합니다. Anthropic이 통제된 실험을 수행했습니다. 동일한 모델(Opus 4.5), 동일한 프롬프트("2D 레트로 게임 에디터 만들기"). 해네스 없이는 20분 동안 $9를 사용했으나 동작하지 않는 결과물이 나왔습니다. 완전한 해네스(플래너 + 생성기 + 평가기)를 사용했을 때는 6시간 동안 $200을 사용해 실제로 플레이할 수 있는 게임을 만들었습니다. 모델은 바뀌지 않았습니다. 해네스가 바뀌었습니다.
+
+OpenAI도 Codex로 동일한 사실을 보고했습니다. 잘 갖추어진 저장소에서는 동일한 모델이 "불안정"에서 "안정적"으로 전환됩니다. 미미한 개선이 아니라 질적 변화입니다.
+
+**이 강의는 그 환경을 구축하는 방법을 가르칩니다.**
+
+```text
+ THE HARNESS PATTERN
+ ====================
+
+ You --> give task --> Agent reads harness files --> Agent executes
+ |
+ harness governs every step:
+ |
+ +--> Instructions: what to do, in what order
+ +--> Scope: one feature at a time, no overreach
+ +--> State: progress log, feature list, git history
+ +--> Verification: tests, lint, type-check, smoke runs
+ +--> Lifecycle: init at start, clean state at end
+ |
+ v
+ Agent stops only when
+ verification passes
+```
+
+---
+
+## 해네스 엔지니어링이란 실제로 무엇인가
+
+해네스 엔지니어링(Harness Engineering)은 모델이 안정적인 결과를 낼 수 있도록 모델 주변에 완전한 작업 환경을 구축하는 것입니다. 더 나은 프롬프트를 작성하는 것이 아닙니다. 모델이 운영되는 시스템을 설계하는 것입니다.
+
+해네스에는 다섯 가지 하위 시스템이 있습니다.
+
+```text
+ ┌─────────────────────────────────────────────────────────────────┐
+ │ THE HARNESS │
+ │ │
+ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
+ │ │ Instructions │ │ State │ │ Verification │ │
+ │ │ │ │ │ │ │ │
+ │ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
+ │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
+ │ │ feature_list │ │ git log │ │ smoke runs │ │
+ │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ └──────────────┘ └──────────────┘ └──────────────────────┘ │
+ │ │
+ │ ┌──────────────┐ ┌──────────────────────────────────────┐ │
+ │ │ Scope │ │ Session Lifecycle │ │
+ │ │ │ │ │ │
+ │ │ one feature │ │ init.sh at start │ │
+ │ │ at a time │ │ clean-state checklist at end │ │
+ │ │ definition │ │ handoff note for next session │ │
+ │ │ of done │ │ commit only when safe to resume │ │
+ │ └──────────────┘ └──────────────────────────────────────┘ │
+ │ │
+ └─────────────────────────────────────────────────────────────────┘
+
+ The MODEL decides what code to write.
+ The HARNESS governs when, where, and how it writes it.
+ The harness doesn't make the model smarter.
+ It makes the model's output reliable.
+```
+
+각 하위 시스템에는 하나의 역할이 있습니다.
+
+- **지시사항(Instructions)** — 에이전트에게 무엇을 어떤 순서로 할지, 시작 전에 무엇을 읽어야 하는지 알려줍니다. 하나의 거대한 파일이 아니라, 에이전트가 필요할 때 탐색하는 점진적 공개(progressive disclosure) 구조입니다.
+- **상태(State)** — 완료된 것, 진행 중인 것, 다음 작업을 추적합니다. 디스크에 영속화(persist)되어 다음 세션이 이전 세션이 끝난 정확한 위치에서 이어받을 수 있습니다.
+- **검증(Verification)** — 통과하는 테스트 스위트만이 증거로 인정됩니다. 에이전트는 실행 가능한 증거 없이는 완료를 선언할 수 없습니다.
+- **범위(Scope)** — 에이전트를 한 번에 하나의 기능으로 제한합니다. 범위 초과(overreach) 없음. 세 가지를 반쯤 완성하는 일 없음. 미완성 작업을 숨기기 위해 기능 목록을 재작성하는 일 없음.
+- **세션 라이프사이클(Session Lifecycle)** — 시작 시 초기화합니다. 종료 시 정리합니다. 다음 세션을 위한 깨끗한 재시작 경로를 남깁니다.
+
+---
+
+## 이 강의가 존재하는 이유
+
+질문은 "모델이 코드를 작성할 수 있는가?"가 아닙니다. 모델은 쓸 수 있습니다. 질문은 이것입니다. **모델이 실제 저장소에서 여러 세션에 걸쳐 지속적인 인간 감독 없이 실제 엔지니어링 작업을 안정적으로 완수할 수 있는가?**
+
+현재 답은 이렇습니다. 해네스 없이는 그렇지 않습니다.
+
+```text
+ WITHOUT HARNESS WITH HARNESS
+ ============== ============
+
+ Session 1: agent writes code Session 1: agent reads instructions
+ agent breaks tests agent runs init.sh
+ agent says "done" agent works on one feature
+ you fix it manually agent verifies before claiming done
+ agent updates progress log
+ Session 2: agent starts fresh agent commits clean state
+ agent has no memory
+ of what happened before Session 2: agent reads progress log
+ agent re-does work agent picks up exactly where it left off
+ or does something else entirely agent continues the unfinished feature
+ you fix it again you review, not rescue
+
+ Result: you spend more time Result: agent does the work,
+ cleaning up than if you you verify the result
+ did it yourself
+```
+
+이 강의가 실제로 다루는 질문들:
+
+- 어떤 해네스 설계가 작업 완료율을 개선하는가?
+- 어떤 설계가 재작업과 잘못된 완료를 줄이는가?
+- 어떤 메커니즘이 장시간 작업을 꾸준히 진행시키는가?
+- 어떤 구조가 여러 번의 에이전트 실행 후에도 시스템을 유지 관리 가능하게 유지하는가?
+
+---
+
+## 강의 커리큘럼 및 문서
+
+전체 강의 자료는 **[문서 웹사이트](https://walkinglabs.github.io/learn-harness-engineering/)**에서 확인하십시오.
+
+커리큘럼은 세 부분으로 나뉩니다.
+
+1. **강의(Lectures)**: 해네스 엔지니어링의 이론을 설명하는 12개 개념 단원.
+2. **프로젝트(Projects)**: 처음부터 에이전트 워크스페이스를 구축하는 6개 실습 프로젝트.
+3. **리소스 라이브러리(Resource Library)**: 지금 바로 자신의 저장소에서 사용할 수 있는 복사 준비 완료 템플릿(`AGENTS.md`, `feature_list.json`, `init.sh` 등).
+
+---
+
+## 빠른 시작: 지금 당장 에이전트를 개선하기
+
+가치를 얻기 위해 12개 강의를 모두 읽을 필요는 없습니다. 이미 실제 프로젝트에서 코딩 에이전트를 사용하고 있다면, 지금 바로 개선하는 방법이 있습니다.
+
+아이디어는 간단합니다. 프롬프트만 작성하는 대신, 에이전트에게 무엇을 해야 하는지, 무엇이 완료되었는지, 작업을 어떻게 검증하는지를 정의하는 구조화된 파일 집합을 제공하십시오. 이 파일들은 저장소 내부에 위치하므로 모든 세션이 동일한 상태에서 시작합니다.
+
+```text
+ YOUR PROJECT ROOT
+ ├── AGENTS.md <-- the agent's operating manual
+ ├── CLAUDE.md <-- (alternative, if using Claude Code)
+ ├── init.sh <-- runs install + verify + start
+ ├── feature_list.json <-- what features exist, which are done
+ ├── claude-progress.md <-- what happened each session
+ └── src/ <-- your actual code
+```
+
+[리소스 라이브러리](https://walkinglabs.github.io/learn-harness-engineering/en/resources/)에서 시작 템플릿을 가져와 프로젝트에 추가하십시오. 네 개의 파일만으로도 에이전트 세션이 프롬프트만으로 실행하는 것보다 훨씬 안정적이 될 것입니다.
+
+---
+
+## 캡스톤 프로젝트: 실제 앱
+
+6개의 강의 프로젝트는 모두 동일한 제품을 중심으로 전개됩니다. **Electron 기반 개인 지식 베이스(knowledge base) 데스크탑 앱**입니다.
+
+```text
+ ┌─────────────────────────────────────────────────────┐
+ │ Knowledge Base Desktop App │
+ │ │
+ │ ┌──────────────┐ ┌──────────────────────────────┐│
+ │ │ Document List │ │ Q&A Panel ││
+ │ │ │ │ ││
+ │ │ doc-001.md │ │ Q: What is harness eng? ││
+ │ │ doc-002.md │ │ A: The environment built ││
+ │ │ doc-003.md │ │ around an agent model... ││
+ │ │ ... │ │ [citation: doc-002.md] ││
+ │ └──────────────┘ └──────────────────────────────┘│
+ │ │
+ │ ┌─────────────────────────────────────────────────┐│
+ │ │ Status Bar: 42 docs | 38 indexed | last sync 3m ││
+ │ └─────────────────────────────────────────────────┘│
+ └─────────────────────────────────────────────────────┘
+
+ Core features:
+ ├── Import local documents
+ ├── Manage a document library
+ ├── Process and index documents
+ ├── Run AI-powered Q&A over imported content
+ └── Return grounded answers with citations
+```
+
+이 프로젝트는 강력한 실용적 가치, 충분한 실제 제품 복잡성, 그리고 해네스 개선 전후를 관찰하기에 적합한 환경을 갖추고 있어 선택되었습니다.
+
+각 강의 프로젝트의 시작점/풀이는 해당 진화 단계의 이 Electron 앱의 완전한 복사본입니다. P(N+1)의 시작점은 P(N)의 풀이에서 파생됩니다 — 앱은 해네스 기술이 성장함에 따라 함께 진화합니다.
+
+---
+
+## 학습 경로
+
+강의는 순서대로 진행하도록 설계되었습니다. 각 단계는 이전 단계 위에 구축됩니다.
+
+```text
+ Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
+ ======================== ==========================
+
+ L01 Strong models != reliable L03 Repository as single
+ execution source of truth
+ L02 What harness actually means
+ L04 Split instructions across
+ | files, not one giant file
+ v
+ P01 Prompt-only vs. |
+ rules-first comparison v
+ P02 Agent-readable workspace
+
+
+ Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
+ ========================== =========================
+
+ L05 Keep context alive L07 Draw clear task boundaries
+ across sessions
+ L08 Feature lists as harness
+ L06 Initialize before every primitives
+ agent session
+ |
+ | v
+ v P04 Runtime feedback to
+ P03 Multi-session continuity correct agent behavior
+
+
+ Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
+ ===================== ============================
+
+ L09 Stop agents from L11 Make agent's runtime
+ declaring victory early observable
+
+ L10 Full-pipeline run = L12 Clean handoff at end of
+ real verification every session
+
+ | |
+ v v
+ P05 Agent verifies its own work P06 Build a complete harness
+ (capstone project)
+```
+
+파트타임으로 진행한다면 각 단계는 약 1주일이 걸립니다. 더 빠르게 진행하려면 1–3단계를 긴 주말 동안 완료할 수 있습니다.
+
+---
+
+## 실라버스
+
+### 강의 — 12개 개념 단원, 각각 하나의 핵심 질문에 답변
+
+*각 강의의 전체 텍스트는 [문서 웹사이트](https://walkinglabs.github.io/learn-harness-engineering/)에서 읽을 수 있습니다.*
+
+| 세션 | 질문 | 핵심 아이디어 |
+|------|------|--------------|
+| [L01](./docs/lectures/lecture-01-why-capable-agents-still-fail/index.md) | 강력한 모델이 실제 작업에서 왜 여전히 실패하는가? | 벤치마크와 실제 엔지니어링 사이의 역량 격차 |
+| [L02](./docs/lectures/lecture-02-what-a-harness-actually-is/index.md) | "해네스"는 실제로 무엇을 의미하는가? | 다섯 가지 하위 시스템: 지시사항, 상태, 검증, 범위, 라이프사이클 |
+| [L03](./docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | 왜 저장소가 단일 진실 원천(Single Source of Truth)이어야 하는가? | 에이전트가 볼 수 없으면 존재하지 않는다 |
+| [L04](./docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | 하나의 거대한 지시 파일이 왜 실패하는가? | 점진적 공개: 백과사전이 아닌 지도를 제공하라 |
+| [L05](./docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | 장시간 작업이 왜 연속성(continuity)을 잃는가? | 진행 상황을 디스크에 영속화하고, 중단된 곳에서 재개하라 |
+| [L06](./docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | 초기화가 왜 자체 단계가 필요한가? | 에이전트가 작업을 시작하기 전에 환경이 정상임을 검증하라 |
+| [L07](./docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | 에이전트가 왜 범위를 초과하고 미완성으로 끝나는가? | 한 번에 하나의 기능; 완료의 명시적 정의 |
+| [L08](./docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | 기능 목록이 왜 해네스의 기본 구성 요소인가? | 에이전트가 무시할 수 없는 기계 가독형 범위 경계 |
+| [L09](./docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | 에이전트가 왜 너무 일찍 완료를 선언하는가? | 검증 격차: 신뢰감 ≠ 정확성 |
+| [L10](./docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | 엔드-투-엔드 테스트가 왜 결과를 바꾸는가? | 전체 파이프라인 실행만이 실제 검증으로 인정된다 |
+| [L11](./docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | 가관측성(observability)이 왜 해네스 내부에 있어야 하는가? | 에이전트가 무엇을 했는지 볼 수 없으면 무엇이 잘못되었는지 고칠 수 없다 |
+| [L12](./docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | 왜 모든 세션이 깨끗한 상태를 남겨야 하는가? | 다음 세션의 성공은 이 세션의 정리에 달려 있다 |
+
+### 프로젝트 — 동일한 Electron 앱에 강의 방법을 적용하는 6개 실습 프로젝트
+
+| 프로젝트 | 수행 내용 | 해네스 메커니즘 |
+|---------|----------|----------------|
+| [P01](./docs/projects/project-01-baseline-vs-minimal-harness/index.md) | 동일한 작업을 두 번 실행: 프롬프트만 사용 vs. 규칙 우선 | 최소 해네스: AGENTS.md + init.sh + feature_list.json |
+| [P02](./docs/projects/project-02-agent-readable-workspace/index.md) | 에이전트가 읽을 수 있도록 저장소 재구성 | 에이전트 가독형 워크스페이스 + 영속 상태 파일 |
+| [P03](./docs/projects/project-03-multi-session-continuity/index.md) | 에이전트가 중단된 곳에서 이어받도록 만들기 | 진행 로그 + 세션 핸드오프(handoff) + 다중 세션 연속성 |
+| [P04](./docs/projects/project-04-incremental-indexing/index.md) | 에이전트가 너무 많거나 너무 적게 하지 않도록 막기 | 런타임 피드백 + 범위 제어 + 점진적 인덱싱 |
+| [P05](./docs/projects/project-05-grounded-qa-verification/index.md) | 에이전트가 자신의 작업을 검증하도록 만들기 | 자기 검증 + 근거 기반 Q&A + 증거 기반 완료 |
+| [P06](./docs/projects/project-06-runtime-observability-and-debugging/index.md) | 처음부터 완전한 해네스 구축 (캡스톤 프로젝트) | 완전한 해네스: 모든 메커니즘 + 가관측성 + 절제 연구 |
+
+```text
+ PROJECT EVOLUTION
+ =================
+
+ P01 Prompt-only vs. rules-first You see the problem
+ |
+ v
+ P02 Agent-readable workspace You restructure the repo
+ |
+ v
+ P03 Multi-session continuity You connect sessions
+ |
+ v
+ P04 Runtime feedback & scope You add feedback loops
+ |
+ v
+ P05 Self-verification You make the agent check itself
+ |
+ v
+ P06 Complete harness (capstone) You build the full system
+
+ Each project's solution becomes the next project's starter.
+ The app evolves. Your harness skills grow with it.
+```
+
+### 리소스 라이브러리
+
+- [한국어 리소스 라이브러리](https://walkinglabs.github.io/learn-harness-engineering/ko/resources/) — 템플릿, 체크리스트, 방법 참고 자료
+- [English Resource Library](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) — templates, checklists, and method references
+- [Chinese Resource Library](https://walkinglabs.github.io/learn-harness-engineering/zh/resources/) — 中文模板、清单和方法参考
+- [Russian Resource Library](https://walkinglabs.github.io/learn-harness-engineering/ru/resources/) — шаблоны, чек-листы и справочники
+- [Vietnamese Resource Library](https://walkinglabs.github.io/learn-harness-engineering/vi/resources/) — mẫu, danh sách kiểm tra và tài liệu tham khảo
+
+---
+
+## 에이전트 세션 라이프사이클
+
+이 강의의 핵심 아이디어 중 하나: **에이전트 세션은 자유로운 흐름이 아니라 구조화된 라이프사이클을 따라야 합니다.** 다음은 그 모습입니다.
+
+```text
+ AGENT SESSION LIFECYCLE
+ ======================
+
+ ┌──────────────────────────────────────────────────────────────────┐
+ │ START │
+ │ │
+ │ 1. Agent reads AGENTS.md / CLAUDE.md │
+ │ 2. Agent runs init.sh (install, verify, health check) │
+ │ 3. Agent reads claude-progress.md (what happened last time) │
+ │ 4. Agent reads feature_list.json (what's done, what's next) │
+ │ 5. Agent checks git log (recent changes) │
+ │ │
+ │ SELECT │
+ │ │
+ │ 6. Agent picks exactly ONE unfinished feature │
+ │ 7. Agent works only on that feature │
+ │ │
+ │ EXECUTE │
+ │ │
+ │ 8. Agent implements the feature │
+ │ 9. Agent runs verification (tests, lint, type-check) │
+ │ 10. If verification fails: fix and re-run │
+ │ 11. If verification passes: record evidence │
+ │ │
+ │ WRAP UP │
+ │ │
+ │ 12. Agent updates claude-progress.md │
+ │ 13. Agent updates feature_list.json │
+ │ 14. Agent records what's still broken or unverified │
+ │ 15. Agent commits (only when safe to resume) │
+ │ 16. Agent leaves clean restart path for next session │
+ │ │
+ └──────────────────────────────────────────────────────────────────┘
+
+ The harness governs every transition in this lifecycle.
+ The model decides what code to write at each step.
+ Without the harness, step 9 becomes "agent says it looks fine."
+ With the harness, step 9 is "tests pass, lint is clean, types check."
+```
+
+---
+
+## 대상 독자
+
+이 강의는 다음 분들을 위한 것입니다.
+
+- 더 나은 안정성과 품질을 원하는 코딩 에이전트 사용자
+- 해네스 설계에 대한 체계적인 이해를 원하는 연구자 또는 빌더
+- 환경 설계가 에이전트 성능에 미치는 영향을 이해해야 하는 기술 리드
+
+이 강의는 다음 분들을 위한 것이 아닙니다.
+
+- 코드 없는 AI 입문을 찾는 분
+- 프롬프트에만 관심이 있고 실제 구현을 구축할 계획이 없는 분
+- 에이전트가 실제 저장소에서 작업하도록 허용할 준비가 되어 있지 않은 학습자
+
+---
+
+## 요구 사항
+
+이 강의는 실제로 코딩 에이전트를 실행하는 강의입니다.
+
+다음 도구 중 최소 하나가 필요합니다.
+
+- Claude Code
+- Codex
+- 파일 편집, 명령 실행, 다단계 작업을 지원하는 다른 IDE 또는 CLI 코딩 에이전트
+
+강의는 다음이 가능하다고 가정합니다.
+
+- 로컬 저장소 열기
+- 에이전트가 파일을 편집하도록 허용
+- 에이전트가 명령을 실행하도록 허용
+- 출력을 검사하고 작업 재실행
+
+그러한 도구가 없어도 강의 콘텐츠를 읽을 수 있지만 의도한 대로 프로젝트를 완료할 수는 없습니다.
+
+---
+
+## 로컬 미리보기
+
+이 저장소는 VitePress를 문서 뷰어로 사용합니다.
+
+```sh
+npm install
+npm run docs:dev # 핫 리로드가 있는 개발 서버
+npm run docs:build # 프로덕션 빌드
+npm run docs:preview # 빌드된 사이트 미리보기
+```
+
+VitePress가 출력하는 로컬 URL을 브라우저에서 여십시오.
+
+---
+
+## 사전 요건
+
+필수:
+
+- 터미널, git, 로컬 개발 환경에 대한 친숙함
+- 일반적인 애플리케이션 스택에서 코드를 읽고 쓸 수 있는 능력
+- 기본적인 소프트웨어 디버깅 경험 (로그, 테스트, 런타임 동작 읽기)
+- 구현 중심 강의에 전념할 충분한 시간
+
+도움이 되지만 필수는 아님:
+
+- Electron, 데스크탑 앱, 또는 로컬 우선 도구 경험
+- 테스트, 로깅, 또는 소프트웨어 아키텍처 배경
+- Codex, Claude Code, 또는 유사한 코딩 에이전트에 대한 사전 노출
+
+---
+
+## 핵심 참고 자료
+
+주요:
+
+- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
+- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
+
+보충:
+
+- [LangChain: The Anatomy of an Agent Harness](https://blog.langchain.com/the-anatomy-of-an-agent-harness/)
+- [Thoughtworks: Harness Engineering](https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html)
+- [HumanLayer: Skill Issue: Harness Engineering for Coding Agents](https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents)
+
+---
+
+## 저장소 구조
+
+```text
+learn-harness-engineering/
+├── docs/ # VitePress 문서 사이트
+│ ├── lectures/ # 12개 강의 (index.md + code/ 예제)
+│ │ ├── lecture-01-*/
+│ │ ├── lecture-02-*/
+│ │ └── ... (총 12개)
+│ ├── projects/ # 6개 프로젝트 설명
+│ │ ├── project-01-*/
+│ │ └── ... (총 6개)
+│ └── resources/ # 다국어 템플릿 및 참고 자료
+│ ├── en/ # 영어 템플릿, 체크리스트, 가이드
+│ ├── zh/ # 중국어 템플릿, 체크리스트, 가이드
+│ ├── ru/ # 러시아어 템플릿, 체크리스트, 가이드
+│ └── vi/ # 베트남어 템플릿, 체크리스트, 가이드
+├── projects/
+│ ├── shared/ # 공유 Electron + TypeScript + React 기반
+│ └── project-NN/ # 프로젝트별 starter/ 및 solution/ 디렉터리
+├── skills/ # 재사용 가능한 AI 에이전트 스킬
+│ └── harness-creator/ # 해네스 엔지니어링 스킬
+├── package.json # VitePress + 개발 도구
+└── CLAUDE.md # 이 저장소에 대한 Claude Code 지시사항
+```
+
+---
+
+## 강의 구성 방식
+
+- 각 강의는 하나의 질문에 집중합니다
+- 강의는 6개의 프로젝트를 포함합니다
+- 모든 프로젝트는 에이전트가 실제 작업을 수행하도록 요구합니다
+- 모든 프로젝트는 약한 해네스 대 강한 해네스 결과를 비교합니다
+- 중요한 것은 작성된 문서의 양이 아니라 측정된 차이입니다
+
+---
+
+## 감사의 말
+
+이 강의는 [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code)에서 영감을 받았으며, 아이디어를 차용했습니다. 이 프로젝트는 단일 루프에서 격리된 자율 실행까지 처음부터 에이전트를 구축하기 위한 점진적 가이드입니다.
diff --git a/README.md b/README.md
index 41a0cd6..37accfa 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-[English](https://walkinglabs.github.io/learn-harness-engineering/en/) · [中文](https://walkinglabs.github.io/learn-harness-engineering/zh/) · [Русский](https://walkinglabs.github.io/learn-harness-engineering/ru/) · [Tiếng Việt](https://walkinglabs.github.io/learn-harness-engineering/vi/)
+[English](https://walkinglabs.github.io/learn-harness-engineering/en/) · [中文](https://walkinglabs.github.io/learn-harness-engineering/zh/) · [Русский](https://walkinglabs.github.io/learn-harness-engineering/ru/) · [Tiếng Việt](https://walkinglabs.github.io/learn-harness-engineering/vi/) · [한국어](https://walkinglabs.github.io/learn-harness-engineering/ko/)
# Learn Harness Engineering
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index d2fcdf6..898228e 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -154,6 +154,43 @@ const ruSkillItems = [
{ text: "Обзор скиллов", link: "/ru/skills/" }
];
+const koLectureItems = [
+ { text: "환영합니다", link: "/ko/" },
+ { text: "유능한 에이전트가 여전히 실패하는 이유", link: "/ko/lectures/lecture-01-why-capable-agents-still-fail/" },
+ { text: "해네스란 무엇인가", link: "/ko/lectures/lecture-02-what-a-harness-actually-is/" },
+ { text: "저장소가 시스템 오브 레코드(SoR)가 되어야 하는 이유", link: "/ko/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/" },
+ { text: "거대한 단일 지시 파일이 실패하는 이유", link: "/ko/lectures/lecture-04-why-one-giant-instruction-file-fails/" },
+ { text: "장기 작업이 연속성을 잃는 이유", link: "/ko/lectures/lecture-05-why-long-running-tasks-lose-continuity/" },
+ { text: "초기화가 별도 단계여야 하는 이유", link: "/ko/lectures/lecture-06-why-initialization-needs-its-own-phase/" },
+ { text: "에이전트가 과도하게 손대고 끝맺지 못하는 이유", link: "/ko/lectures/lecture-07-why-agents-overreach-and-under-finish/" },
+ { text: "기능 목록이 해네스의 기본 단위인 이유", link: "/ko/lectures/lecture-08-why-feature-lists-are-harness-primitives/" },
+ { text: "에이전트가 너무 일찍 완료를 선언하는 이유", link: "/ko/lectures/lecture-09-why-agents-declare-victory-too-early/" },
+ { text: "엔드투엔드 테스트가 결과를 바꾸는 이유", link: "/ko/lectures/lecture-10-why-end-to-end-testing-changes-results/" },
+ { text: "관측 가능성이 해네스 안에 있어야 하는 이유", link: "/ko/lectures/lecture-11-why-observability-belongs-inside-the-harness/" },
+ { text: "모든 세션이 클린 상태로 끝나야 하는 이유", link: "/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" }
+];
+
+const koProjectItems = [
+ { text: "환영합니다", link: "/ko/projects/" },
+ { text: "프롬프트 단독 vs 규칙 우선", link: "/ko/projects/project-01-baseline-vs-minimal-harness/" },
+ { text: "에이전트가 읽을 수 있는 작업 공간", link: "/ko/projects/project-02-agent-readable-workspace/" },
+ { text: "다중 세션 연속성", link: "/ko/projects/project-03-multi-session-continuity/" },
+ { text: "런타임 피드백과 범위 제어", link: "/ko/projects/project-04-incremental-indexing/" },
+ { text: "자기 검증과 역할 분리", link: "/ko/projects/project-05-grounded-qa-verification/" },
+ { text: "완성형 해네스(캡스톤)", link: "/ko/projects/project-06-runtime-observability-and-debugging/" }
+];
+
+const koResourceItems = [
+ { text: "리소스 모음 개요", link: "/ko/resources/" },
+ { text: "한국어 템플릿", link: "/ko/resources/templates/" },
+ { text: "한국어 레퍼런스", link: "/ko/resources/reference/" },
+ { text: "고급 리소스 팩", link: "/ko/resources/openai-advanced/" }
+];
+
+const koSkillItems = [
+ { text: "스킬 개요", link: "/ko/skills/" }
+];
+
export default withMermaid(
defineConfig({
base: docsBase,
@@ -294,6 +331,43 @@ export default withMermaid(
socialLinks: [{ icon: "github", link: githubRepoTreeLink }]
}
},
+ ko: {
+ label: "한국어",
+ lang: "ko",
+ link: "/ko/",
+ themeConfig: {
+ nav: [
+ { text: "강의", link: koLectureItems[1].link, activeMatch: '^/ko/(lectures/.*)?$' },
+ { text: "프로젝트", link: koProjectItems[0].link, activeMatch: '^/ko/projects/' },
+ { text: "리소스 모음", link: "/ko/resources/", activeMatch: '^/ko/resources/' },
+ { text: "스킬", link: "/ko/skills/", activeMatch: '^/ko/skills/' },
+ { text: "Try Harness ↗", link: "https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ko/resources/templates/index.md", target: "_blank", rel: "noopener noreferrer" }
+ ],
+ sidebar: {
+ '/ko/projects/': [{ text: "프로젝트", items: koProjectItems }],
+ '/ko/resources/': [{ text: "리소스 모음", items: koResourceItems }],
+ '/ko/skills/': [{ text: "스킬", items: koSkillItems }],
+ '/ko/': [{ text: "강의", items: koLectureItems }]
+ },
+ outline: {
+ level: [2, 3],
+ label: "이 페이지에서"
+ },
+ docFooter: {
+ prev: "이전",
+ next: "다음"
+ },
+ lastUpdated: {
+ text: "마지막 업데이트"
+ },
+ returnToTopLabel: "맨 위로",
+ sidebarMenuLabel: "메뉴",
+ darkModeSwitchLabel: "테마",
+ lightModeSwitchTitle: "라이트 모드로 전환",
+ darkModeSwitchTitle: "다크 모드로 전환",
+ socialLinks: [{ icon: "github", link: githubRepoTreeLink }]
+ }
+ },
ru: {
label: "Русский",
lang: "ru",
diff --git a/docs/index.md b/docs/index.md
index 8fca504..779e1c7 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -6,7 +6,12 @@ layout: page
if (typeof window !== 'undefined') {
const base = import.meta.env.BASE_URL || '/'
const lang = navigator.language || navigator.languages?.[0] || ''
- const target = `${base}${lang.startsWith('zh') ? 'zh/' : 'en/'}`
+ let locale = 'en/'
+ if (lang.startsWith('ko')) locale = 'ko/'
+ else if (lang.startsWith('zh')) locale = 'zh/'
+ else if (lang.startsWith('ru')) locale = 'ru/'
+ else if (lang.startsWith('vi')) locale = 'vi/'
+ const target = `${base}${locale}`
if (!window.location.pathname.replace(/\/$/, '').endsWith(target.replace(/\/$/, ''))) {
window.location.replace(target)
}
diff --git a/docs/ko/index.md b/docs/ko/index.md
new file mode 100644
index 0000000..482f41d
--- /dev/null
+++ b/docs/ko/index.md
@@ -0,0 +1,76 @@
+# Learn Harness Engineering에 오신 것을 환영합니다
+
+Learn Harness Engineering은 AI 코딩 에이전트(coding agent)의 엔지니어링에 집중하는 강의입니다. 우리는 업계에서 가장 앞선 해네스 엔지니어링(Harness Engineering) 이론과 실천을 깊이 학습하고 정리했습니다. 핵심 참고 자료는 다음과 같습니다.
+
+- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
+- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
+- [Awesome Harness Engineering](https://github.com/walkinglabs/awesome-harness-engineering)
+
+이 강의는 체계적인 환경 설계, 상태(state) 관리, 검증(verification), 제어(control) 시스템을 통해 Codex와 Claude Code 같은 에이전트형 코딩 도구를 실제로 신뢰할 수 있게 만드는 방법을 가르칩니다. 명시적인 규칙과 경계로 AI 코딩 보조 도구를 제약하여, 기능을 구현하고 버그를 수정하며 개발 작업을 자동화하도록 돕습니다.
+
+> 처음 보시는 용어가 많아도 괜찮습니다. 핵심 개념의 한국어·영어 대응표는 [용어집](./resources/reference/glossary.md)에 정리되어 있습니다.
+
+## 시작하기
+
+학습 경로를 선택해 시작하세요. 강의는 이론 강의, 실습 프로젝트, 즉시 사용 가능한 리소스 모음으로 구성됩니다.
+
+<div class="card-grid">
+ <a href="./lectures/lecture-01-why-capable-agents-still-fail/" class="card">
+ <h3>강의(Lectures)</h3>
+ <p>강력한 모델이 왜 여전히 실패하는지 이해하고, 효과적인 해네스의 이론을 배웁니다.</p>
+ </a>
+ <a href="./projects/" class="card">
+ <h3>프로젝트(Projects)</h3>
+ <p>믿을 수 있는 에이전트 환경을 처음부터 직접 만들어 보는 실습입니다.</p>
+ </a>
+ <a href="./resources/" class="card">
+ <h3>리소스 모음(Resource Library)</h3>
+ <p>여러분의 저장소에서 바로 쓸 수 있는 복사용 템플릿(AGENTS.md, feature_list.json 등)입니다.</p>
+ </a>
+</div>
+
+## 해네스의 핵심 메커니즘
+
+해네스(harness)는 모델을 "더 똑똑하게" 만드는 도구가 아닙니다. 대신, 모델을 위한 닫힌 루프(closed loop) **작업 시스템**을 만들어 줍니다. 핵심 흐름은 다음 다이어그램으로 이해할 수 있습니다.
+
+```mermaid
+graph TD
+ A["명확한 목표<br/>AGENTS.md"] --> B("초기화<br/>init.sh")
+ B --> C{"작업 실행<br/>AI Agent"}
+ C -->|문제 발생| D["런타임 피드백<br/>CLI / Logs"]
+ D -->|자동 수정| C
+ C -->|코드 완성| E{"검증과 QA<br/>Test suite"}
+ E -->|실패| D
+ E -->|통과| F["정리와 인계<br/>claude-progress.md"]
+
+ classDef primary fill:#D95C41,stroke:#C14E36,color:#fff,font-weight:bold;
+ classDef process fill:#F4F3EE,stroke:#D1D1D1,color:#1A1A1A;
+ classDef check fill:#EAE8E1,stroke:#B3B3B3,color:#1A1A1A;
+
+ class A,F primary;
+ class B,D process;
+ class C,E check;
+```
+
+## 이 강의에서 배우는 것
+
+본 강의를 완주하면 다음과 같은 핵심 개념을 다룰 수 있게 됩니다.
+
+<ul class="index-list">
+ <li><strong>에이전트 동작 제약</strong>: 명시적인 규칙과 경계로 에이전트의 행동 범위를 한정합니다.</li>
+ <li><strong>컨텍스트(context) 유지</strong>: 장시간·다중 세션 작업에서도 컨텍스트를 잃지 않도록 합니다.</li>
+ <li><strong>섣부른 완료 선언 방지</strong>: 에이전트가 너무 빨리 "끝났다"고 선언하지 못하게 합니다.</li>
+ <li><strong>작업 검증</strong>: 전체 파이프라인 테스트와 자기 점검(self-reflection)으로 결과물을 검증합니다.</li>
+ <li><strong>관측 가능성 확보</strong>: 런타임을 관측·디버깅 가능하게 만듭니다.</li>
+</ul>
+
+## 다음 단계
+
+핵심 개념이 익숙해졌다면, 다음 자료로 한 걸음 더 들어가 보세요.
+
+<ul class="index-list">
+ <li><a href="./lectures/lecture-01-why-capable-agents-still-fail/">강의 01: 유능한 에이전트가 여전히 실패하는 이유</a> — 해네스 엔지니어링의 이론적 출발점입니다.</li>
+ <li><a href="./projects/project-01-baseline-vs-minimal-harness/">프로젝트 01: 베이스라인(Baseline) vs 미니멀 해네스(Minimal Harness)</a> — 첫 실제 과제를 처음부터 진행해 봅니다.</li>
+ <li><a href="./resources/templates/">템플릿(Templates)</a> — 미니멀 해네스 팩(AGENTS.md, feature_list.json, claude-progress.md)을 자신의 프로젝트에 바로 적용해 보세요.</li>
+</ul>
diff --git a/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md b/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md
new file mode 100644
index 0000000..c7931e0
--- /dev/null
+++ b/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md
@@ -0,0 +1,9 @@
+# 실패 신호 체크리스트
+
+취약한 해네스(harness) 실행을 검토할 때 이 체크리스트를 활용하십시오.
+
+- 에이전트(agent)가 앱 시작 방법을 직접 물어보았는가, 아니면 잘못 추론했는가?
+- 의도한 제품과 일치하지 않는 디렉터리 또는 추상화를 만들었는가?
+- 완전한 워크플로 없이 눈에 보이는 UI 껍데기만 만든 뒤 멈췄는가?
+- 이후 실행이 이어 진행할 수 있도록 메모나 산출물(deliverable)을 남겼는가?
+- 새 세션이 5분 이내에 이전에 무슨 일이 있었는지 파악할 수 있는가?
diff --git a/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/code/index.md b/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/code/index.md
new file mode 100644
index 0000000..586dba8
--- /dev/null
+++ b/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/code/index.md
@@ -0,0 +1,7 @@
+# 강의 01 코드 예제
+
+이 폴더는 다음을 보여주는 소규모 예제에 사용됩니다.
+
+- 강력한 모델이 취약한 환경에서 실패하는 사례
+- 명세가 부족한 저장소(repository) 설정
+- 피드백 루프가 없는 상황
diff --git a/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md b/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md
new file mode 100644
index 0000000..75ac8fd
--- /dev/null
+++ b/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md
@@ -0,0 +1,18 @@
+# 명세가 부족한 작업 예시
+
+AI 질의응답 기능이 있는 데스크톱 지식 베이스 앱을 만드십시오.
+
+제약 조건:
+
+- 명시된 것 없음
+- 시작 명령어 없음
+- 폴더 구조 안내 없음
+- 데이터 모델 정의 없음
+- 명시적 완료 기준(Definition of Done) 없음
+
+이런 종류의 프롬프트에서 발생하는 전형적인 결과:
+
+- 에이전트(agent)가 구조를 임시방편으로 만들어냄
+- 앱이 컴파일되더라도 일관되게 시작되지 않을 수 있음
+- 사용 가능한 수집/조회 경로가 없는 상태에서 UI가 먼저 나타날 수 있음
+- 에이전트가 겉으로만 보이는 성공 후에 멈추는 경우가 많음
diff --git a/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/index.md
new file mode 100644
index 0000000..1a534ab
--- /dev/null
+++ b/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/index.md
@@ -0,0 +1,121 @@
+[中文版本 →](../../../zh/lectures/lecture-01-why-capable-agents-still-fail/)
+
+> 코드 예제: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-01-why-capable-agents-still-fail/code/)
+> 실습 프로젝트: [Project 01. Prompt-only vs. rules-first](./../../projects/project-01-baseline-vs-minimal-harness/index.md)
+
+# 강의 01. 강력한 모델도 실행 신뢰성을 보장하지 않는다
+
+AI 세계에 꽤 익숙하다고 자부합니다 — Claude Pro 구독, GPT-4o API 키, SWE-bench 리더보드 수치까지 외우고 있죠. 그러던 어느 날 드디어 실제 프로젝트를 AI 에이전트(agent)에게 맡겨봤습니다. 결과는? 기능 하나를 추가했더니 테스트가 깨지고, 버그 하나를 고쳤더니 두 개가 더 생기고, 20분 동안 열심히 실행하더니 당당하게 "완료"를 선언했는데 코드를 보면 요청한 것과 전혀 다른 내용입니다.
+
+에이전트(agent)란 자율적으로 작업을 수행하는 AI 소프트웨어 단위입니다. 코딩 에이전트(coding agent)는 이 중에서도 코드 작성·리팩터·테스트 등 개발 작업을 담당합니다.
+
+처음 든 생각은 이겁니다: "이 모델은 아직 부족해. 더 좋은 걸로 바꿔야겠어." 잠깐, 지갑을 꺼내기 전에 — 문제가 모델에 있지 않을 수도 있다는 점을 먼저 짚어봐야 합니다.
+
+숫자를 봅시다. 2025년 말 기준 SWE-bench Verified에서 가장 강력한 코딩 에이전트들은 대략 50-60%의 정확도를 기록합니다. 그것도 명확한 이슈 설명과 기존 테스트 케이스가 갖춰진 엄선된 작업 기준입니다. 막연한 요구사항, 테스트 없음, 암묵적 비즈니스 규칙이 여기저기 흩어진 실제 개발 환경으로 넘어오면 그 수치는 더 낮아집니다.
+
+그런데 이 수치들 뒤에는 직관에 반하는 진실이 있습니다.
+
+## 같은 말(馬), 다른 결과
+
+Anthropic이 통제 실험을 진행했습니다. 동일한 프롬프트("2D 레트로 게임 메이커를 만들어라"), 동일한 모델(Opus 4.5). 첫 번째 실행: 아무런 지원 없이 맨손 — 20분, 9달러, 게임의 핵심 기능은 전혀 작동하지 않았습니다. 두 번째 실행: 완전한 해네스(harness) 적용(플래너 + 제너레이터 + 이밸류에이터 3에이전트 아키텍처) — 6시간, 200달러, 게임을 실제로 플레이할 수 있었습니다.
+
+해네스(harness)란 AI 코딩 에이전트가 안정적으로 동작하도록 환경·상태(state)·검증(verification)·제어를 묶어서 제공하는 외골격(스캐폴딩) 시스템입니다. 모델 가중치 외부에 있는 모든 엔지니어링 인프라가 해네스에 해당합니다.
+
+모델은 바꾸지 않았습니다. Opus 4.5는 여전히 Opus 4.5였죠. 바뀐 것은 안장(saddle)이었습니다.
+
+OpenAI의 2025년 해네스 엔지니어링 글은 명확하게 밝힙니다: 잘 갖춰진 저장소(repository)에서의 Codex는 "불안정"에서 "안정"으로 질적 전환을 이룬다고. 표현에 주목하세요 — "조금 나아진"이 아니라 질적 변화입니다. 마치 경주마처럼: 안장 없이도 탈 수 있지만, 멀리 갈 수 없고, 빠르게 달릴 수 없으며, 낙마도 놀랍지 않습니다. 해네스는 그 안장입니다 — **모델 가중치 외부의 엔지니어링 인프라 전체입니다.**
+
+## 에이전트가 실제로 막히는 지점
+
+그렇다면 구체적으로 무엇이 잘못되는 걸까요?
+
+가장 흔한 원인: 작업을 명확하게 정의하지 않았습니다. "검색 기능을 추가해"라고 하면 에이전트의 이해는 여러분의 이해와 전혀 다릅니다 — 무엇을 검색? 전문 검색 아니면 구조화 검색? 페이지네이션은? 하이라이팅은? 명시하지 않았으니 에이전트는 추측합니다. 맞는 추측은 운이고, 틀린 추측은 처음부터 명확히 했을 때보다 고치는 비용이 더 듭니다. 레스토랑에 가서 주방장에게 "생선으로 주세요"라고 하는 것과 같습니다 — 조림이 나올지, 찜이 나올지, 전골이 나올지는 순전히 운에 달려 있습니다.
+
+명확히 지시했더라도, 프로젝트에는 에이전트가 모르는 암묵적 아키텍처 컨벤션이 있습니다. 팀에서는 SQLAlchemy 2.0 문법을 표준으로 쓰는데 에이전트는 기본적으로 1.x 코드를 작성합니다. 모든 API 엔드포인트는 OAuth 2.0 인증을 사용해야 하는데, 그 규칙은 여러분 머릿속과 석 달 전 슬랙 메시지에만 존재합니다. 에이전트는 이것을 볼 수 없습니다 — 따르기 싫어서가 아니라 그 규칙의 존재 자체를 모릅니다.
+
+환경도 함정입니다. 불완전한 개발 환경, 누락된 의존성, 잘못된 도구 버전. 에이전트는 실제 작업 대신 `pip install` 실패와 Node 버전 불일치를 처리하느라 귀중한 컨텍스트 윈도(context window)를 낭비합니다. 숙련된 목수를 고용했는데 망치도, 못도, 평평한 작업대도 제공하지 않은 것과 같습니다 — 아무리 실력이 좋아도 작업을 할 수 없습니다.
+
+더 흔한 문제: 검증(verification) 방법이 아예 없습니다. 테스트도 없고, 린트도 없고, 검증 명령어도 에이전트에게 전달되지 않습니다. 에이전트는 코드를 작성하고, 보고, 괜찮다고 판단하고, "완료"라고 선언합니다. 답안지 없이 숙제를 제출하도록 한 것과 같습니다 — 학생은 맞혔다고 생각하지만 채점하면 오류 투성이입니다. Anthropic은 흥미로운 현상도 관찰했습니다: 에이전트가 컨텍스트 부족을 감지하면 서둘러 마무리하고, 검증을 건너뛰고, 최선 대신 단순한 해결책을 선택합니다. 이를 "컨텍스트 불안(context anxiety)"이라 부릅니다 — 시험 시간이 거의 다 됐을 때 남은 객관식 문제를 무작위로 찍기 시작하는 것과 같은 현상입니다.
+
+세션에 걸친 장시간 작업은 더욱 나쁩니다 — 이전 세션에서 발견한 모든 것이 사라지고, 매 새 세션마다 프로젝트 구조를 다시 탐색하고 코드 구성을 다시 이해해야 합니다. 영속적인 상태(state)가 없는 에이전트는 30분을 초과하는 작업에서 실패율이 급격히 치솟습니다.
+
+## 핵심 용어
+
+이 시나리오들을 염두에 두면 다음 개념들이 단순한 전문 용어 이상으로 다가옵니다.
+
+- **역량 격차(Capability Gap)**: 벤치마크 성능과 실제 작업 성능 사이의 큰 간극. SWE-bench Verified에서 50-60%의 통과율은 실제 이슈의 거의 절반이 해결되지 않는다는 의미입니다.
+- **해네스(Harness)**: 모델 외부의 모든 것 — 지시사항, 도구, 환경, 상태(state) 관리, 검증(verification) 피드백. 모델 가중치가 아니라면 모두 해네스입니다. 우리가 "안장"이라고 부른 것입니다.
+- **해네스 유발 실패(Harness-Induced Failure)**: 모델은 충분한 역량을 갖췄지만 실행 환경에 구조적 결함이 있는 경우. Anthropic의 통제 실험이 이를 이미 증명했습니다.
+- **검증 격차(Verification Gap)**: 에이전트가 자신의 산출물(deliverable)에 대해 갖는 자신감과 실제 정확성 사이의 간극. 에이전트가 "완료했다"고 말하지만 완료하지 않은 상태 — 이것이 가장 흔한 실패 유형입니다.
+- **진단 루프(Diagnostic Loop)**: 실행 → 실패 관찰 → 특정 해네스 레이어에 귀속 → 해당 레이어 수정 → 재실행. 이것이 해네스 엔지니어링의 핵심 방법론입니다.
+- **완료 기준(Definition of Done)**: 기계 검증 가능한 조건들의 집합 — 테스트 통과, 린트 클린, 타입 검사 통과. 명시적인 완료 기준이 없으면 에이전트는 자체 기준을 만들어냅니다.
+
+## 실패하면 먼저 해네스를 점검하라
+
+핵심 원칙: **실패가 발생하면 먼저 모델을 교체하지 말고 해네스를 점검하십시오.** 같은 모델이 비슷하게 잘 구성된 작업에서 성공한다면, 해네스 문제라고 가정하십시오. 자동차가 고장났을 때처럼 — 바로 엔진을 의심하지 않습니다. 먼저 연료가 있는지 확인합니다.
+
+구체적인 단계:
+
+**모든 실패를 특정 레이어에 귀속시키십시오.** "모델이 별로야"라고만 하지 마십시오. 물어보십시오: 작업이 불명확했는가? 컨텍스트(context)가 불충분했는가? 검증 방법이 없었는가? 각 실패를 다섯 가지 실패 레이어(작업 명세, 컨텍스트 제공, 실행 환경, 검증 피드백, 상태 관리) 중 하나에 매핑하십시오. 이 습관을 들이면 로그에서 "모델이 부족해"라는 말이 점점 사라집니다.
+
+**모든 작업에 명시적인 완료 기준을 작성하십시오.** "검색 기능을 추가해"라고 하지 마십시오. 이렇게 하십시오:
+```
+완료 기준:
+- 새 엔드포인트 GET /api/search?q=xxx
+- 페이지네이션 지원, 기본 20개 항목
+- 결과에 하이라이트된 스니펫 포함
+- 모든 새 코드가 pytest 통과
+- 타입 검사 통과 (mypy --strict)
+```
+
+**AGENTS.md 파일을 만드십시오.** 저장소(repository) 루트에 배치하여 에이전트에게 프로젝트의 기술 스택, 아키텍처 컨벤션, 검증 명령어를 알려주십시오. 이것이 해네스 엔지니어링의 첫 번째 단계이자 투자 대비 효과가 가장 높은 단계입니다. AGENTS.md 파일 하나가 더 비싼 모델로 업그레이드하는 것보다 효과적일 수도 있습니다 — 농담이 아닙니다.
+
+**진단 루프를 구축하십시오.** 실패를 "모델이 또 멍청한 짓을 했네"로 취급하지 마십시오. 해네스에 결함이 있다는 신호로 취급하십시오. 매 실패마다 레이어를 찾아 수정하고, 같은 방식으로 다시 실패하지 않도록 하십시오. 몇 라운드를 거치면 해네스가 강화되고 에이전트 성능이 안정됩니다. 도로 보수처럼 — 모든 움푹 파인 곳을 메울수록 다음 구간이 더 매끄러워집니다.
+
+**개선 사항을 정량화하십시오.** 간단한 로그를 유지하십시오: 각 작업이 성공했는지 실패했는지, 그리고 어느 레이어가 실패를 야기했는지. 몇 라운드 후에는 어느 레이어가 병목인지 보이기 시작합니다 — 거기에 에너지를 집중하십시오.
+
+## 백만 줄 코드 실험
+
+OpenAI는 2025년에 공격적인 실험을 진행했습니다: Codex를 사용하여 빈 git 저장소에서 완전한 내부 제품을 구축하는 것. 5개월 후 저장소에는 약 100만 줄의 코드가 생성되었습니다 — 애플리케이션 로직, 인프라, 툴링, 문서, 내부 개발 도구 모두 에이전트가 생성했습니다. 세 명의 엔지니어가 Codex를 운영하며 약 1,500개의 PR을 열고 병합했습니다. 1인당 하루 평균 3.5개의 PR.
+
+핵심 제약: **인간은 코드를 직접 작성하지 않습니다.** 이것은 단순한 실험적 설정이 아니었습니다 — 엔지니어의 주요 업무가 더 이상 코드 작성이 아니라 환경 설계, 의도 표현, 피드백 루프 구축이 될 때 무엇이 달라지는지 파악하도록 강제하기 위한 설계였습니다.
+
+초기 진행은 예상보다 느렸습니다. Codex의 역량이 부족해서가 아니라 환경이 아직 충분히 갖춰지지 않았기 때문입니다 — 에이전트에게 고수준 목표를 진전시키는 데 필요한 도구, 추상화, 내부 구조가 부족했습니다. 엔지니어들의 작업은 이렇게 바뀌었습니다: 큰 목표를 작은 구성 요소(설계, 코드, 리뷰, 테스트)로 분해하고, 에이전트가 조합하도록 한 다음, 그 구성 요소들을 활용하여 더 복잡한 작업을 가능하게 하는 것. 무언가 실패했을 때 해결책은 거의 "더 열심히 해봐"가 아니었습니다 — "에이전트에게 어떤 역량이 부족하고, 어떻게 하면 이해 가능하고 실행 가능하게 만들 수 있는가?"였습니다.
+
+이 실험은 이 강의의 핵심 테제를 직접 증명합니다: **동일한 모델이 맨손 환경과 완전한 해네스 환경에서 근본적으로 다른 산출물을 만들어냅니다.** 모델은 변하지 않았습니다. 환경이 변했습니다.
+
+> 출처: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
+
+## 현실적인 예시
+
+한 팀이 중간 규모의 Python 웹 앱(FastAPI + PostgreSQL + Redis, 약 15,000줄)에 새 API 엔드포인트를 추가하기 위해 Claude Sonnet을 사용했습니다.
+
+처음에는 한 문장만 제공했습니다: "/api/v2/users 아래에 사용자 환경설정 엔드포인트를 추가해." 결과는? 에이전트가 컨텍스트(context) 윈도의 40%를 저장소 구조 탐색에 사용했고, 겉으로는 합리적으로 보이지만 프로젝트의 오류 처리 패턴을 따르지 않는 코드를 생성했으며, 구식 SQLAlchemy 문법을 사용했고, 엔드포인트에 런타임 오류가 있는 상태에서 완료를 선언했습니다. 다음 세션은 모든 탐색 작업을 처음부터 다시 해야 했습니다.
+
+이후 AGENTS.md(프로젝트 아키텍처 및 기술 스택 버전 설명), 명시적 검증 명령어(`pytest tests/api/v2/ && python -m mypy src/`), 아키텍처 결정 기록을 추가했습니다. 같은 모델이 독립적으로 세 번 실행한 모두에서 성공했고, 컨텍스트 효율도 약 60% 향상되었습니다.
+
+모델을 바꾸지 않았습니다. 해네스를 바꿨습니다.
+
+## 핵심 정리
+
+- 모델 역량과 실행 신뢰성은 별개입니다. 경주마도 좋은 안장이 필요합니다.
+- 실패 시 먼저 해네스를 점검하고, 그 다음 모델을 확인하십시오. 모델 교체는 가장 비싼 선택지입니다 — 그리고 대부분 모델 문제가 아닙니다.
+- 모든 실패는 신호입니다: 해네스에 구조적 결함이 있습니다. 찾아서 고치십시오.
+- 다섯 가지 방어 레이어: 작업 명세, 컨텍스트 제공, 실행 환경, 검증 피드백, 상태 관리. 의사가 가장 흔한 원인부터 먼저 배제하듯이 체계적으로 점검하십시오.
+- AGENTS.md 파일 하나가 더 비싼 모델로 업그레이드하는 것보다 효과적일 수 있습니다. 진심입니다.
+
+## 더 읽을거리
+
+- [OpenAI: Harness Engineering — Leveraging Codex in an Agent-First World](https://openai.com/index/harness-engineering/)
+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+- [HumanLayer: Skill Issue — Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)
+- [SWE-bench Leaderboard](https://www.swebench.com/)
+- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)
+
+## 연습 문제
+
+1. **비교 실험**: 잘 아는 코드베이스와 비사소한 수정 작업을 선택하십시오. 먼저 해네스 지원 없이 에이전트를 실행하고 실패를 기록하십시오. 그런 다음 명시적 검증 명령어가 포함된 AGENTS.md를 추가하고 같은 에이전트로 다시 실행하십시오. 결과를 비교하고, 각 실패를 다섯 가지 방어 레이어 중 하나에 귀속시키십시오.
+
+2. **검증 격차 측정**: 코딩 작업 5개를 선택하십시오. 각 작업 후 에이전트가 완료를 주장하는지 기록한 다음, 독립적인 테스트로 실제 정확성을 검증하십시오. 에이전트가 실제로는 완료하지 않았는데 완료했다고 주장하는 비율을 계산하십시오 — 그것이 여러분의 검증 격차입니다. 그런 다음 어떤 검증 명령어가 이 비율을 낮출 수 있는지 생각해보십시오.
+
+3. **진단 루프 실습**: 프로젝트에서 에이전트가 반복적으로 실패하는 작업을 찾으십시오. 한 번 실행하고 실패를 기록하십시오. 다섯 가지 레이어 중 하나에 귀속시키십시오. 그 레이어를 수정하십시오. 다시 실행하십시오. 3~5라운드를 반복하면서 매번 개선 사항을 기록하십시오.
diff --git a/docs/ko/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md b/docs/ko/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md
new file mode 100644
index 0000000..25aa460
--- /dev/null
+++ b/docs/ko/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md
@@ -0,0 +1,21 @@
+# 해네스 구성 요소 예시
+
+로컬 저장소(repository)에서 작업하는 코딩 에이전트(coding agent)의 경우:
+
+- 모델:
+ LLM 자체
+
+- 해네스(harness):
+ - 시스템 프롬프트
+ - AGENTS.md
+ - bash 도구
+ - 파일 읽기/쓰기 도구
+ - git 접근
+ - 로컬 파일 시스템
+ - 시작 스크립트
+ - 테스트 명령어
+ - 중지 훅(hook)
+ - 린트 검사
+ - 평가자 루프
+
+위의 해네스 요소 중 하나라도 변경하면 실효적인 에이전트가 바뀝니다.
diff --git a/docs/ko/lectures/lecture-02-what-a-harness-actually-is/code/index.md b/docs/ko/lectures/lecture-02-what-a-harness-actually-is/code/index.md
new file mode 100644
index 0000000..5d223bf
--- /dev/null
+++ b/docs/ko/lectures/lecture-02-what-a-harness-actually-is/code/index.md
@@ -0,0 +1,8 @@
+# 강의 02 코드 예제
+
+이 폴더는 다음을 구분하는 소규모 예제에 사용됩니다.
+
+- 모델 동작
+- 해네스(harness) 동작
+- 프롬프트만 사용하는 설정
+- 환경 기반 에이전트(agent) 설정
diff --git a/docs/ko/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/ko/lectures/lecture-02-what-a-harness-actually-is/index.md
new file mode 100644
index 0000000..4d530b2
--- /dev/null
+++ b/docs/ko/lectures/lecture-02-what-a-harness-actually-is/index.md
@@ -0,0 +1,109 @@
+[中文版本 →](../../../zh/lectures/lecture-02-what-a-harness-actually-is/)
+
+> 코드 예제: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-02-what-a-harness-actually-is/code/)
+> 실습 프로젝트: [Project 01. Prompt-only vs. rules-first](./../../projects/project-01-baseline-vs-minimal-harness/index.md)
+
+# 강의 02. 해네스란 실제로 무엇인가
+
+"해네스(harness)"라는 단어는 AI 코딩 에이전트 분야에서 자주 언급되지만, 솔직히 말하면 대부분의 사람들이 해네스라고 할 때 "프롬프트 파일"을 의미합니다. 그것은 해네스가 아닙니다. 재료만 있고 가스레인지도, 칼도, 레시피도, 플레이팅 워크플로도 없이 레스토랑을 여는 것과 같습니다. 그것은 레스토랑이 아닙니다. 냉장고입니다.
+
+이 강의에서는 정확하고 실행 가능한 해네스의 정의를 제시합니다. 학술적 추상이 아니라 오늘 바로 활용할 수 있는 프레임워크입니다: 해네스는 명확한 책임과 평가 기준을 가진 다섯 가지 하위 시스템으로 구성됩니다.
+
+## 비유로 시작하기
+
+문서도 없고, 코드에 주석도 없고, 테스트 실행 방법도 아무도 알려주지 않고, CI 설정은 어딘가에 묻혀 있는 프로젝트에 갑자기 투입된 신규 엔지니어를 상상해보십시오. 좋은 코드를 작성할 수 있을까요? 충분히 똑똑하고 인내심이 있다면 가능할 수도 있습니다. 하지만 "문제를 해결하는 것"보다 "이 프로젝트가 뭔지 파악하는 것"에 엄청난 시간을 쏟게 됩니다.
+
+AI 에이전트도 정확히 같은 상황에 놓입니다. 그리고 더 나쁩니다 — 여러분은 적어도 동료에게 물어볼 수 있습니다. 에이전트는 여러분이 앞에 놓아준 파일과 실행할 수 있는 명령어만 볼 수 있습니다. 누군가를 톡 치면서 "이 프로젝트가 어떤 버전의 ORM을 사용해요?"라고 물을 수 없습니다.
+
+OpenAI는 핵심 원칙을 "저장소(repo)가 명세(spec)다"로 정의합니다 — 필요한 모든 컨텍스트(context)는 저장소에 있어야 하며, 구조화된 지시 파일, 명시적 검증(verification) 명령어, 명확한 디렉터리 구성을 통해 전달되어야 합니다. Anthropic의 장기 실행 에이전트 문서는 상태(state) 지속성, 명시적 복구 경로, 구조화된 진행 추적을 강조합니다. 두 회사는 서로 다른 측면에 집중하지만 같은 말을 합니다: **모델 외부의 엔지니어링 인프라 전체가 모델의 역량이 실제로 얼마나 발휘되는지를 결정합니다.**
+
+이미 알고 있는 도구들을 살펴보십시오:
+
+**Claude Code**는 해네스 사고를 구현합니다. 저장소에서 `CLAUDE.md`를 읽고(레시피 선반), 셸 명령어를 실행할 수 있으며(칼 랙), 로컬 환경에서 실행되고(가스레인지), 세션 기록을 유지하며(준비 스테이션), 테스트를 실행하고 결과를 볼 수 있습니다(품질 확인 창). 하지만 테스트 실행 방법을 알려주지 않으면 품질 확인 창이 고장납니다 — 요리가 완전히 익었는지 아무도 알 수 없습니다.
+
+**Cursor**도 유사한 논리를 따릅니다. `.cursorrules` 파일이 레시피 선반이고, 터미널이 칼 랙이며, 프로젝트 구조와 린트 설정을 읽는 것이 가스레인지입니다. 하지만 Cursor의 상태 관리는 상대적으로 취약합니다 — IDE를 닫고 다시 열면 이전 컨텍스트가 사라집니다.
+
+**Codex**(OpenAI의 코딩 에이전트)는 git 워크트리(worktree)를 사용하여 각 작업의 런타임 환경을 격리하고, 로컬 관찰 가능성 스택(로그, 메트릭, 트레이스)과 결합하여 모든 변경 사항이 독립적인 환경에서 검증됩니다. `AGENTS.md`와 명확한 검증 명령어가 있는 저장소에서는 "맨손" 저장소보다 훨씬 뛰어난 성능을 발휘합니다.
+
+**AutoGPT**는 경고의 사례입니다 — 구조화된 상태 관리의 부재로 장시간 작업에서 컨텍스트가 축적되고, 정밀한 피드백 메커니즘의 부재로 에이전트가 루프에 빠집니다. 많은 사람들이 AutoGPT가 "작동하지 않는다"고 말하지만, 실제로는 AutoGPT의 해네스가 작동하지 않는 것입니다 — 고장난 가스레인지에 주방장을 배치하면 아무리 좋은 재료도 요리가 되지 않습니다.
+
+## 핵심 개념
+
+- **해네스(harness)란 무엇인가**: 모델 가중치 외부의 엔지니어링 인프라 전체. OpenAI는 엔지니어의 핵심 업무를 세 가지로 정리합니다: 환경 설계, 의도 표현, 피드백 루프 구축. Anthropic은 자사의 Claude Agent SDK를 "범용 에이전트 해네스"라고 부릅니다.
+- **저장소는 단일 진실 원천(SoR)이다**: 에이전트가 볼 수 없는 것은 실질적으로 존재하지 않습니다. OpenAI는 저장소를 "시스템 오브 레코드(SoR, system of record)"로 취급합니다 — 모든 필요한 컨텍스트는 구조화된 파일과 명확한 디렉터리 구성을 통해 저장소에 있어야 합니다.
+- **지도를 줘라, 매뉴얼이 아니라**: OpenAI의 경험 — `AGENTS.md`는 백과사전이 아니라 디렉터리 페이지여야 합니다. 100줄 정도가 적당합니다. 맞지 않으면 `docs/` 디렉터리로 분리하여 에이전트가 필요할 때 읽도록 하십시오.
+- **제약하되, 마이크로매니지하지 마라**: 좋은 해네스는 실행 가능한 규칙으로 에이전트를 제약하지, 지시를 하나하나 열거하지 않습니다. OpenAI는 "불변성을 강제하되, 구현을 마이크로매니지하지 말라"고 말합니다. Anthropic은 에이전트가 자신의 작업을 자신만만하게 칭찬한다는 것을 발견했으며, 해결책은 "일하는 사람"과 "확인하는 사람"을 분리하는 것입니다.
+- **컴포넌트를 하나씩 제거하라**: 각 해네스 컴포넌트의 가치를 정량화하려면 하나씩 제거하고 어떤 제거가 가장 큰 성능 저하를 유발하는지 확인하십시오. Anthropic은 이 방법을 사용했으며, 모델이 강해질수록 일부 컴포넌트는 더 이상 핵심적이지 않지만 새로운 컴포넌트가 항상 등장한다는 것을 발견했습니다.
+
+## 5개 하위 시스템 해네스 모델
+
+주방 비유로 돌아가봅시다. 완전한 주방에는 다섯 가지 기능 구역이 있고, 해네스에도 다섯 가지 하위 시스템이 있습니다:
+
+```mermaid
+flowchart LR
+ Rules["프로젝트 규칙<br/>AGENTS.md / CLAUDE.md"] --> Agent["AI 에이전트"]
+ State["진행 상황 및 git<br/>PROGRESS.md / 커밋"] --> Agent
+ Agent --> Tools["도구<br/>셸 / 파일 / 테스트"]
+ Tools --> Env["런타임<br/>의존성 / 서비스 / 버전"]
+ Env --> Checks["검사 결과<br/>테스트 / 린트 / 빌드"]
+ Checks --> Agent
+```
+
+**지시 하위 시스템(레시피 선반)**: `AGENTS.md`(또는 `CLAUDE.md`)를 만들어 다음을 포함하십시오: 프로젝트 개요와 목적(한 문장), 기술 스택과 버전(Python 3.11, FastAPI 0.100+, PostgreSQL 15), 첫 실행 명령어(`make setup`, `make test`), 협상 불가능한 HARD 제약("모든 API는 OAuth 2.0을 사용해야 함"), 더 자세한 문서 링크.
+
+**도구 하위 시스템(칼 랙)**: 에이전트가 충분한 도구 접근권을 갖도록 하십시오. "보안"을 위해 셸을 비활성화하지 마십시오 — 에이전트가 `pip install`조차 실행할 수 없다면 어떻게 작업하겠습니까? 하지만 모든 것을 열어두지도 마십시오 — 최소 권한 원칙을 따르십시오.
+
+**환경 하위 시스템(가스레인지)**: 환경 상태가 자기 서술적이도록 만드십시오. 의존성 잠금을 위해 `pyproject.toml` 또는 `package.json`을 사용하고, 런타임 버전을 위해 `.nvmrc` 또는 `.python-version`을, 재현성을 위해 Docker 또는 devcontainers를 사용하십시오.
+
+**상태(state) 하위 시스템(준비 스테이션)**: 장시간 작업에는 진행 추적이 필요합니다. 간단한 `PROGRESS.md` 파일을 사용하여 기록하십시오: 완료된 것, 진행 중인 것, 차단된 것. 매 세션 종료 전에 업데이트하고, 다음 세션 시작 시 읽으십시오.
+
+**피드백 하위 시스템(품질 확인 창)**: 이것이 투자 대비 효과가 가장 높은 하위 시스템입니다. `AGENTS.md`에 검증 명령어를 명시적으로 나열하십시오:
+```
+검증 명령어:
+- 테스트: pytest tests/ -x
+- 타입 검사: mypy src/ --strict
+- 린트: ruff check src/
+- 전체 검증: make check (위 모두 포함)
+```
+
+하위 시스템 하나라도 빠지면 주방의 기능 구역 하나가 없는 것과 같습니다 — 요리는 할 수 있지만 항상 불편합니다.
+
+**해네스 품질 진단**: "등압 모델 제어(isometric model control)"를 사용하십시오. 모델을 고정하고 하위 시스템을 하나씩 제거하면서 어떤 제거가 가장 큰 성능 저하를 유발하는지 측정하십시오. 그것이 병목 — 거기에 집중하십시오. 주방에서 병목을 찾는 것처럼: 레시피 선반을 없애고 얼마나 느려지는지 보고, 가스레인지를 끄고 영향을 확인하십시오.
+
+## 한 팀의 실제 이야기
+
+한 팀이 TypeScript + React 프론트엔드 앱(약 20,000줄)에 GPT-4o를 사용했습니다. 필수적으로 주방 장비를 하나씩 추가하는 4단계를 거쳤습니다:
+
+**1단계 — 빈 주방**: README에 기본 프로젝트 설명만 있음. 5번 실행 중 1번 성공(20%). 주요 실패: 잘못된 패키지 매니저 선택(npm vs yarn), 컴포넌트 명명 컨벤션 미준수, 테스트 실행 불가.
+
+**2단계 — 레시피 선반 설치**: 기술 스택 버전, 명명 컨벤션, 주요 아키텍처 결정이 담긴 `AGENTS.md` 추가. 성공률 60%로 상승. 남은 실패는 주로 환경 문제와 검증 누락.
+
+**3단계 — 품질 확인 창 개방**: `AGENTS.md`에 검증 명령어 나열: `yarn test && yarn lint && yarn build`. 성공률 80%로 상승.
+
+**4단계 — 준비 스테이션 준비**: 에이전트가 매 실행마다 완료된 작업과 미완료 작업을 기록하는 진행 파일 템플릿 도입. 성공률 80-100%로 안정화.
+
+4번의 반복, 모델은 전혀 바꾸지 않았고, 성공률은 20%에서 거의 100%로. 그것이 해네스 엔지니어링의 힘입니다. 더 비싼 재료를 구매한 것이 아닙니다 — 주방을 제대로 정리한 것입니다.
+
+## 핵심 정리
+
+- 해네스 = 지시 + 도구 + 환경 + 상태(state) + 피드백. 다섯 가지 하위 시스템, 주방의 다섯 가지 기능 구역처럼 — 모두 필수입니다.
+- 모델 가중치가 아니라면 모두 해네스입니다. 해네스가 모델 역량이 얼마나 발휘되는지를 결정합니다.
+- 다섯 가지 하위 시스템 중 피드백 하위 시스템이 일반적으로 가장 낮은 투자로 가장 높은 수익을 냅니다. 검증 명령어를 먼저 맞추십시오 — 품질 확인 창이 가장 가치 있는 업그레이드입니다.
+- "등압 모델 제어"를 사용하여 각 하위 시스템의 한계 기여도를 정량화하십시오 — 직감에 의존하지 마십시오.
+- 해네스는 코드처럼 부패합니다. 정기적으로 감사하고 기술 부채를 갚듯 해네스 부채를 갚으십시오.
+
+## 더 읽을거리
+
+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)
+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)
+- [SWE-agent: Agent-Computer Interfaces](https://github.com/princeton-nlp/SWE-agent)
+- [Thoughtworks: Harness Engineering on Technology Radar](https://www.thoughtworks.com/radar)
+
+## 연습 문제
+
+1. **5개 하위 시스템 해네스 감사**: AI 에이전트를 사용하는 프로젝트를 가져와 5개 하위 시스템 프레임워크를 사용하여 완전한 감사를 수행하십시오. 각 하위 시스템에 1-5점을 매기십시오. 점수가 가장 낮은 하위 시스템을 찾아 30분을 개선에 투자하고, 에이전트 성능의 변화를 관찰하십시오.
+
+2. **등압 모델 제어 실험**: 모델 하나와 도전적인 작업 하나를 선택하십시오. 지시(AGENTS.md 삭제), 피드백(검증 명령어 미제공), 상태(진행 파일 없음)를 순차적으로 제거하되 한 번에 하나씩만 제거하고 성능 저하를 측정하십시오. 결과를 기반으로 프로젝트에서 하위 시스템 중요도를 순위 매기십시오.
+
+3. **어포던스 분석**: 프로젝트에서 에이전트가 "하고 싶지만 할 수 없는" 시나리오(예: 매개변수화된 쿼리를 사용해야 하지만 프로젝트의 ORM 패턴을 모르는 경우)를 찾으십시오. 이것이 실행의 간극(Gulf of Execution, 방법을 모름)인지 아니면 평가의 간극(Gulf of Evaluation, 맞는지를 모름)인지 분석한 다음, 이를 해소할 해네스 개선 방안을 설계하십시오.
diff --git a/docs/ko/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md b/docs/ko/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md
new file mode 100644
index 0000000..8eafba5
--- /dev/null
+++ b/docs/ko/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md
@@ -0,0 +1,7 @@
+# 강의 03 코드 예제
+
+이 폴더는 다음 예제에 사용됩니다.
+
+- 에이전트(agent)가 읽을 수 있는 저장소(repository) 구조
+- 시스템 오브 레코드(SoR)로서의 문서
+- 잘못된 지식 배치 vs 올바른 지식 배치
diff --git a/docs/ko/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md b/docs/ko/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md
new file mode 100644
index 0000000..5e06ed2
--- /dev/null
+++ b/docs/ko/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md
@@ -0,0 +1,11 @@
+# 시스템 오브 레코드 체크리스트
+
+새 에이전트(agent)가 저장소(repository)만으로 다음을 발견할 수 있는가?
+
+- 어떤 제품을 만들고 있는가?
+- 앱이 사용자를 위해 무엇을 해야 하는가?
+- 코드베이스는 어떻게 구성되어 있는가?
+- 앱은 어떻게 시작하는가?
+- 상태는 어떻게 확인하는가?
+- 현재 어떤 작업이 진행 중인가?
+- 어떤 품질 기준이 중요한가?
diff --git a/docs/ko/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/ko/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
new file mode 100644
index 0000000..41957d2
--- /dev/null
+++ b/docs/ko/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
@@ -0,0 +1,137 @@
+[中文版本 →](../../../zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/)
+
+> 코드 예제: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/)
+> 실습 프로젝트: [Project 02. Agent-readable workspace](./../../projects/project-02-agent-readable-workspace/index.md)
+
+# 강의 03. 저장소를 단일 진실 원천으로 만들어라
+
+팀의 아키텍처 결정이 Confluence, Slack, Jira, 그리고 몇몇 시니어 엔지니어의 머릿속에 흩어져 있습니다. 사람에게는 이것이 겨우 통합니다 — 동료에게 물어보고, 채팅 기록을 검색하고, 문서를 뒤지면 됩니다. 도저히 안 되면 휴게실에서 누군가를 붙잡을 수도 있습니다. 하지만 AI 에이전트(agent)에게는, 저장소(repository)에 없는 정보는 단순히 존재하지 않습니다.
+
+이것은 과장이 아닙니다. 에이전트의 입력이 실제로 무엇인지 생각해보십시오: 시스템 프롬프트와 작업 설명, 저장소의 파일 내용, 그리고 도구 실행 결과. 그뿐입니다. 슬랙 기록, Jira 티켓, Confluence 페이지, 금요일 오후 동료와 커피 한 잔 하며 나눈 아키텍처 결정 — 에이전트는 이 중 어느 것도 볼 수 없습니다. "누군가에게 물어보거나" "채팅 기록을 검색"할 수 없습니다. 저장소 안에 갇힌 엔지니어입니다 — 외부에 있는 것은 아무것도 모릅니다.
+
+그렇다면 질문은 이것입니다: 이 엔지니어에게 좋은 지도를 줄 건가요?
+
+## 지도에 무엇이 있어야 하는가
+
+OpenAI는 이를 명확히 말합니다: **저장소에 없는 정보는 에이전트에게 존재하지 않습니다.** 그들은 이를 "저장소를 명세(spec)로" 원칙이라고 부릅니다 — 저장소 자체가 최고 권위의 명세 문서입니다.
+
+Anthropic의 장기 실행 에이전트 문서도 이를 반향합니다: 영속적인 상태(state)는 장기 작업 연속성의 필요 조건입니다. 세션 간 지식 복구 가능성이 작업 성공률을 직접 결정합니다. 그리고 이 상태는 저장소에 존재해야 합니다 — 에이전트가 가진 유일하게 안정적이고 접근 가능한 저장소이기 때문입니다.
+
+"우리 팀은 규모가 작아서 지식이 모두의 머릿속에 있는데 잘 돌아가고 있어"라고 생각할 수 있습니다. 사람에게는 그렇습니다. 하지만 에이전트를 사용한다면 이 사실을 받아들여야 합니다: 에이전트는 사람에게 물어볼 수 없습니다. 알아야 하는 모든 것은 적어서 찾을 수 있는 곳에 두어야 합니다.
+
+이것은 "더 많은 문서를 작성하는 것"에 관한 것이 아닙니다. "결정 정보를 올바른 장소에 두는 것"에 관한 것입니다. `src/api/` 디렉터리의 50줄짜리 `ARCHITECTURE.md`는 아무도 유지보수하지 않는 Confluence의 500페이지 설계 문서보다 만 배 유용합니다. 책상에 붙여 놓은 손으로 그린 사무실 지도와 파일 캐비닛에 잠겨 있는 아름다운 건축 청사진의 차이와 같습니다 — 전자는 필요할 때 바로 거기 있지만, 후자는 기술적으로 우수하더라도 현장에서는 쓸모가 없습니다.
+
+## 지식 가시성
+
+```mermaid
+flowchart LR
+ Slack["슬랙의 규칙"] --> Write["저장소 파일에 작성<br/>AGENTS.md / ARCHITECTURE.md / PROGRESS.md"]
+ Confluence["Confluence의 규칙"] --> Write
+ Heads["사람들 머릿속의 규칙"] --> Write
+ Jira["Jira 티켓의 규칙"] --> Write
+ Write --> Repo["저장소 파일"]
+ Repo --> Agent["새 에이전트 세션<br/>저장소를 직접 읽음"]
+ Warning["저장소에 없는 규칙은<br/>에이전트가 볼 수 없음"] --> Agent
+```
+
+지도가 충분히 좋은지 테스트하는 방법은? "콜드 스타트 테스트(cold-start test)"를 실행하십시오: 저장소 내용만을 사용하여 완전히 새로운 에이전트 세션을 열고, 다섯 가지 기본 질문에 답할 수 있는지 확인하십시오:
+
+```mermaid
+flowchart TB
+ Q1["이 시스템이 무엇인가?"] --> A1["AGENTS.md / README"]
+ Q2["어떻게 구성되어 있는가?"] --> A2["ARCHITECTURE.md / 모듈 문서"]
+ Q3["어떻게 실행하는가?"] --> A3["Makefile / init.sh / 패키지 스크립트"]
+ Q4["어떻게 검증하는가?"] --> A4["테스트, 린트, 검사 명령어"]
+ Q5["지금 어디에 있는가?"] --> A5["PROGRESS.md / 기능 목록 / git 기록"]
+
+ A1 --> Ready["새 세션이 사람에게 묻지 않고<br/>작업을 시작할 수 있음"]
+ A2 --> Ready
+ A3 --> Ready
+ A4 --> Ready
+ A5 --> Ready
+```
+
+답할 수 없다면 지도에 빈 곳이 있습니다. 지도에 빈 곳이 있으면 에이전트는 추측합니다 — 잘못된 추측은 버그가 되고, 과도한 추측은 컨텍스트(context)를 낭비합니다. 그리고 모든 새 세션에서 다시 추측합니다. 추측의 비용은 항상 처음부터 제대로 지도를 그리는 비용보다 높습니다.
+
+## 핵심 개념
+
+- **지식 가시성 격차(Knowledge Visibility Gap)**: 저장소에 없는 전체 프로젝트 지식의 비율. 격차가 클수록 에이전트의 실패율이 높습니다. 이 프로젝트에 대해 얼마나 많은 암묵적 지식이 머릿속에 있는지 헤아려보십시오. 그 중 얼마나 저장소에 들어갔는지 확인하십시오 — 그 차이가 여러분의 가시성 격차입니다.
+- **시스템 오브 레코드(SoR, System of Record)**: 프로젝트 결정, 아키텍처 제약, 실행 상태, 검증 기준에 대한 권위 있는 출처로서의 코드 저장소. 저장소가 최종 발언권을 가지며, 다른 어느 곳도 인정되지 않습니다. "도로 폐쇄"를 표시한 지도처럼 — 그 길로 가지 않습니다. 하지만 그 정보가 장씨의 머릿속에만 있다면 매번 장씨에게 물어봐야 합니다.
+- **콜드 스타트 테스트(Cold-Start Test)**: 위의 다섯 가지 질문. 몇 개나 답할 수 있는가가 지도가 얼마나 완전한가를 나타냅니다.
+- **발견 비용(Discovery Cost)**: 에이전트가 저장소에서 핵심 정보를 찾는 데 소비하는 컨텍스트 예산의 양. 정보가 숨어있을수록 발견 비용이 높아지고, 실제 작업에 남는 예산이 줄어듭니다. 중요한 정보를 열 개의 디렉터리 아래 README에 숨기는 것은 지하실 금고에 소화기를 잠그는 것과 같습니다 — 존재하지만 필요할 때 찾을 수 없습니다.
+- **지식 부패율(Knowledge Decay Rate)**: 단위 시간당 낡아지는 지식 항목의 비율. 문서가 코드와 동기화되지 않는 것이 가장 큰 적입니다 — 문서가 없는 것보다 더 나쁩니다.
+- **ACID 유추**: 데이터베이스 트랜잭션 원칙(원자성, 일관성, 격리성, 내구성)을 에이전트 상태 관리에 적용하는 것. 아래에서 자세히 설명합니다.
+
+## 좋은 지도를 그리는 방법
+
+**원칙 1: 지식은 코드 옆에 있어야 합니다.** API 엔드포인트 인증에 관한 규칙은 거대한 전역 문서 안에 묻혀 있는 것이 아니라 API 코드 옆에 있어야 합니다. 각 모듈 디렉터리에 해당 모듈의 책임, 인터페이스, 특별 제약을 설명하는 짧은 문서를 두십시오. 도서관 선반 레이블처럼 — 역사책을 원하면 "역사" 표시 선반으로 바로 갑니다. 전체 도서관을 뒤질 필요가 없습니다.
+
+**원칙 2: 표준화된 진입 파일을 사용하십시오.** `AGENTS.md`(또는 `CLAUDE.md`)는 에이전트의 "랜딩 페이지"입니다. 모든 정보를 담을 필요는 없지만 에이전트가 세 가지 질문에 빠르게 답할 수 있도록 해야 합니다: "이 프로젝트가 무엇인가", "어떻게 실행하는가", "어떻게 검증하는가". 50-100줄이면 충분합니다.
+
+**원칙 3: 최소하되 완전하게.** 모든 지식은 명확한 사용 사례가 있어야 합니다. 규칙을 제거해도 에이전트의 결정 품질에 영향을 주지 않는다면 그 규칙은 존재하지 않아야 합니다. 하지만 콜드 스타트 테스트의 모든 질문에는 답이 있어야 합니다. 이것은 섬세한 균형입니다 — 너무 많지도, 너무 적지도 않게, 딱 적당하게.
+
+**원칙 4: 코드와 함께 업데이트하십시오.** 지식 업데이트를 코드 변경에 바인딩하십시오. 가장 간단한 방법: 아키텍처 문서를 해당 모듈 디렉터리에 두십시오. 코드를 수정할 때 자연스럽게 문서를 보게 됩니다. 코드 변경 후 CI에서 문서 업데이트가 필요한지 확인하도록 알릴 수 있습니다.
+
+**구체적인 저장소 구조**:
+
+```
+project/
+├── AGENTS.md # 진입점: 프로젝트 개요, 실행 명령어, HARD 제약
+├── src/
+│ ├── api/
+│ │ ├── ARCHITECTURE.md # API 레이어 아키텍처 결정
+│ │ └── ...
+│ ├── db/
+│ │ ├── CONSTRAINTS.md # 데이터베이스 작업 HARD 제약
+│ │ └── ...
+│ └── ...
+├── PROGRESS.md # 현재 진행 상황: 완료, 진행 중, 차단됨
+└── Makefile # 표준화된 명령어: setup, test, lint, check
+```
+
+## ACID 원칙으로 에이전트 상태 관리하기
+
+이 유추는 데이터베이스 트랜잭션 관리에서 비롯됩니다 — 과도하게 복잡하게 만드는 것 같지만, 실제로는 매우 실용적인 프레임워크를 제공합니다:
+
+- **원자성(Atomicity)**: 각 "논리적 작업"(예: "새 엔드포인트 추가 및 테스트 업데이트")은 하나의 git 커밋을 받습니다. 중간에 실패하면 `git stash`로 롤백합니다. 전부 아니면 아무것도 — "반쯤 완료된" 상태는 없습니다.
+- **일관성(Consistency)**: "일관된 상태" 검증 조건을 정의하십시오 — 모든 테스트 통과, 린트 오류 없음. 에이전트는 각 작업 후 검증을 실행합니다. 일관성 없는 중간 상태는 커밋되지 않습니다. 은행 송금처럼 — 입금 없이 출금할 수 없습니다.
+- **격리성(Isolation)**: 여러 에이전트가 동시에 작업할 때 상태 파일이 경쟁 조건을 피하도록 설계하십시오. 간단한 방법: 각 에이전트가 자체 진행 파일을 사용하거나, 격리를 위해 git 브랜치를 사용하십시오. 두 명의 주방장이 같은 냄비를 동시에 간을 맞출 수 없습니다 — 짜게 되면 누가 책임을 지나요?
+- **내구성(Durability)**: 중요한 프로젝트 지식은 git으로 추적되는 파일에 있습니다. 임시 상태는 세션 메모리에 있어도 되지만, 세션 간 지식은 파일에 영속화해야 합니다. 머릿속에 있는 것은 인정되지 않습니다 — 종이에 있는 것만 인정됩니다.
+
+## 실제 변환 사례
+
+약 30개의 마이크로서비스로 구성된 이커머스 플랫폼을 유지보수하는 팀이 있었습니다. 아키텍처 결정(서비스 간 통신 프로토콜, 데이터 일관성 전략, API 버전 관리 규칙)이 다음에 흩어져 있었습니다: Confluence(부분적으로 낡음), Slack(검색하기 어려움), 몇몇 시니어 엔지니어의 머릿속(확장 불가), 산발적인 코드 주석(체계적이지 않음).
+
+AI 에이전트를 도입한 후 70%의 작업에 사람의 개입이 필요했습니다. 거의 모든 실패에는 에이전트가 "모두가 알지만 아무도 적지 않은" 암묵적 제약을 위반하는 것이 포함되었습니다. 아무도 "점심 주문은 단체 채팅에 올려야 해"라고 알려주지 않은 새 직원과 같습니다 — 잘못 추측하고, 혼나지만, 혼난 후에도 아무도 규칙을 알려주지 않습니다.
+
+팀은 변환을 실행했습니다:
+1. 저장소 루트에 `AGENTS.md`를 만들어 프로젝트 개요, 기술 스택 버전, 전역 HARD 제약 포함
+2. 각 마이크로서비스 디렉터리에 책임, 인터페이스, 의존성을 설명하는 `ARCHITECTURE.md` 추가
+3. 명시적인 "MUST/MUST NOT" 언어로 HARD 제약을 담은 중앙 집중식 `CONSTRAINTS.md` 생성
+4. 각 서비스 디렉터리에 현재 작업 상태를 추적하는 `PROGRESS.md` 추가
+
+변환 후: 같은 에이전트가 콜드 스타트에서 모든 주요 프로젝트 질문에 답할 수 있게 되었고, 작업 완료 품질이 크게 향상되었습니다.
+
+## 핵심 정리
+
+- 저장소에 없는 지식은 에이전트에게 존재하지 않습니다. 중요한 결정을 저장소에 두는 것이 가장 기본적인 해네스 투자입니다 — 길을 잃지 않도록 좋은 지도를 그리십시오.
+- "콜드 스타트 테스트"를 사용하여 저장소 품질을 평가하십시오: 새 세션이 저장소 내용만으로 다섯 가지 기본 질문에 답할 수 있는가?
+- 지식은 코드 가까이에, 최소하되 완전하게, 코드와 함께 업데이트되어야 합니다. 더 많은 문서를 작성하는 것이 아니라 정보를 올바른 장소에 두는 것입니다.
+- ACID 원칙을 에이전트 상태에 사용하십시오: 원자적 커밋, 일관성 검증, 동시성 격리, 중요 지식의 내구성.
+- 지식 부패가 가장 큰 적입니다. 코드와 동기화되지 않는 문서는 문서가 없는 것보다 더 위험합니다 — 에이전트를 맞는 방향이라고 생각하면서 잘못된 방향으로 보냅니다.
+
+## 더 읽을거리
+
+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)
+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+- [Infrastructure as Code — Martin Fowler](https://martinfowler.com/bliki/InfrastructureAsCode.html)
+- [ADR: Architecture Decision Records](https://adr.github.io/)
+- [The Twelve-Factor App](https://12factor.net/)
+
+## 연습 문제
+
+1. **콜드 스타트 테스트**: 프로젝트에서 완전히 새로운 에이전트 세션을 여십시오(구두 컨텍스트 없음, 저장소 내용만). 다섯 가지 질문을 하십시오: 이 시스템이 무엇인가? 어떻게 구성되어 있는가? 어떻게 실행하는가? 어떻게 검증하는가? 현재 진행 상황은? 답하지 못하는 것을 기록한 다음, 에이전트가 답할 수 있을 때까지 저장소를 개선하십시오.
+
+2. **지식 외재화 정량화**: 프로젝트의 개발 작업에 중요한 모든 결정과 제약을 나열하십시오. 각각을 저장소 내부 또는 외부로 표시하십시오. 지식 가시성 격차(저장소 외부 비율)를 계산하십시오. 이를 10% 미만으로 낮추는 계획을 세우십시오.
+
+3. **ACID 평가**: 이 강의의 ACID 유추를 사용하여 프로젝트의 상태 관리를 평가하십시오. 원자성 — 에이전트 작업을 깔끔하게 롤백할 수 있는가? 일관성 — "일관된 상태" 검증이 있는가? 격리성 — 동시 에이전트들이 서로 간섭하는가? 내구성 — 모든 세션 간 지식이 영속화되는가?
diff --git a/docs/ko/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md b/docs/ko/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md
new file mode 100644
index 0000000..5ba6bb6
--- /dev/null
+++ b/docs/ko/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md
@@ -0,0 +1,14 @@
+# AGENTS.md
+
+## 시작하기
+
+- `docs/ARCHITECTURE.md`를 읽으세요
+- `docs/PRODUCT.md`를 읽으세요
+- `npm run dev`로 앱을 시작하세요
+- 작업 완료로 표시하기 전에 `npm run check`를 실행하세요
+
+## 하드 규칙
+
+- `docs/ARCHITECTURE.md`를 읽지 않고 Electron main/preload/renderer 경계를 변경하지 마세요
+- 검증 없이 기능을 완료로 표시하지 마세요
+- 다음 세션을 위해 깨끗한 상태를 남기세요
diff --git a/docs/ko/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md b/docs/ko/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md
new file mode 100644
index 0000000..3c9afe4
--- /dev/null
+++ b/docs/ko/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md
@@ -0,0 +1,7 @@
+# 명령 파일 안티패턴
+
+- 저장소의 모든 지식을 하나의 파일에 넣기
+- 여러 곳에 동일한 규칙을 반복하기
+- 아무도 감사하지 않는 오래된 규칙을 유지하기
+- 거의 적용되지 않는 지나치게 구체적인 조건부 명령 작성하기
+- 긴 도구 설명서를 시작 컨텍스트에 포함하기
diff --git a/docs/ko/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md b/docs/ko/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md
new file mode 100644
index 0000000..1738dff
--- /dev/null
+++ b/docs/ko/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md
@@ -0,0 +1,7 @@
+# 강의 04 코드 예제
+
+이 폴더는 다음 예제들을 위해 사용합니다.
+
+- 단일 파일에 모든 내용을 담은 명령 파일
+- 짧은 진입점(entrypoint) 파일
+- 점진적 공개(progressive disclosure) 패턴
diff --git a/docs/ko/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/ko/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
new file mode 100644
index 0000000..3b621a6
--- /dev/null
+++ b/docs/ko/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
@@ -0,0 +1,132 @@
+[中文版本 →](../../../zh/lectures/lecture-04-why-one-giant-instruction-file-fails/)
+
+> 코드 예제: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/code/)
+> 실습 프로젝트: [Project 02. 에이전트가 읽을 수 있는 작업 공간](./../../projects/project-02-agent-readable-workspace/index.md)
+
+# 강의 04. 명령 파일을 여러 파일로 분산하라
+
+해네스 엔지니어링(harness engineering)에 진지하게 임하기 시작했습니다. `AGENTS.md`를 만들고, 떠오르는 모든 규칙과 제약과 교훈을 그 안에 빼곡히 담았습니다. 한 달이 지나자 파일이 300줄로 불었고, 두 달 뒤엔 450줄, 세 달 뒤엔 600줄이 됐습니다. 그런데 에이전트(agent) 성능이 오히려 나빠지고 있다는 것을 알게 됩니다. 간단한 버그 수정을 할 때도 에이전트가 불필요한 배포 명령을 처리하느라 컨텍스트(context)를 낭비하고, 300번째 줄에 묻혀 있는 중요한 보안 제약은 완전히 무시되며, 서로 모순된 코드 스타일 규칙 세 개를 매번 임의로 골라 따릅니다.
+
+이것이 "거대한 명령 파일" 함정입니다. 여행 가방을 과도하게 채우는 것과 같습니다. 모든 물건이 필요해 보여서 계속 욱여넣다 보면 지퍼가 터질 지경이 됩니다. 속옷 한 장을 찾으려면 가방 전체를 비워야 합니다. 가득 찬 가방을 들고 다니지만, 실제로 꺼내 쓰는 물건은 그 중 3분의 1도 안 됩니다.
+
+## 근본 원인: 악순환
+
+가장 흔한 악순환은 이렇게 진행됩니다. 에이전트가 실수를 하면, "이걸 막을 규칙을 추가하자"라는 생각에 AGENTS.md에 규칙을 넣습니다. 잠시 효과가 있습니다. 에이전트가 다른 실수를 하면, 또 규칙을 추가합니다. 이 과정을 반복하다 보면 파일은 걷잡을 수 없이 커집니다.
+
+이것은 여러분의 잘못이 아닙니다. "문제가 생기면 규칙을 추가한다"는 반응은 매우 자연스럽습니다. 외출할 때마다 "혹시 몰라서" 가방에 물건을 하나씩 더 챙기는 것과 같습니다. 하지만 누적 효과는 치명적입니다. 구체적으로 무엇이 잘못되는지 살펴보겠습니다.
+
+**컨텍스트 예산이 잠식됩니다.** 에이전트의 컨텍스트 윈도(context window)는 유한합니다. 에이전트에게 200K 토큰 윈도가 있다고 가정하면, 비대해진 명령 파일이 10~20K 토큰을 먹어치울 수 있습니다. 아직 여유가 있어 보이나요? 하지만 복잡한 작업은 수십 개의 소스 파일을 읽어야 하고, 도구 실행 결과도 컨텍스트를 차지하며, 대화 기록도 쌓입니다. 에이전트가 코드를 이해해야 할 때쯤이면 예산은 이미 빠듯합니다. "혹시 몰라서" 챙긴 물건들로 가득 찬 가방에 노트북을 넣을 자리가 없는 것과 같습니다.
+
+**중간에서 길을 잃습니다(Lost in the Middle).** "Lost in the Middle" 논문(Liu et al., 2023)은 LLM이 긴 텍스트의 중간에 있는 정보를 처음이나 끝에 있는 정보보다 훨씬 덜 효과적으로 활용한다는 것을 명확히 증명했습니다. AGENTS.md가 600줄이고 300번째 줄에 "모든 데이터베이스 쿼리는 매개변수화된 쿼리를 사용해야 한다"는 보안 하드 제약이 있다면, 그것은 중간에 묻혀 있어 에이전트가 거의 확실히 무시할 것입니다. 과도하게 채운 여행 가방 바닥의 선크림과 같습니다. 있다는 건 알지만 세 번을 뒤져도 못 찾아서 결국 새로 하나 삽니다.
+
+**우선순위 충돌이 발생합니다.** 파일은 협상 불가능한 하드 제약("절대 eval()을 사용하지 말 것"), 중요한 설계 지침("함수형 스타일을 선호할 것"), 그리고 특정 역사적 교훈("지난주에 WebSocket 메모리 누수를 고쳤으니 유사 패턴을 주의할 것")을 뒤섞어 놓습니다. 이 세 규칙의 중요도는 완전히 다르지만 파일 안에서는 동일하게 보입니다. 에이전트가 이를 구별할 신뢰할 만한 신호가 없습니다. 여행 가방 안에서 여권과 충전 케이블이 뒤엉켜 있는 것처럼, 어느 쪽이 더 긴급한지 알 수 없습니다.
+
+**유지보수 붕괴가 옵니다.** 큰 파일은 본질적으로 유지보수하기 어렵습니다. 오래된 명령은 좀처럼 삭제되지 않습니다. 삭제의 결과가 불확실하기 때문입니다("어쩌면 다른 규칙이 이것에 의존하고 있을지도?"). 반면 새 명령을 추가하는 것은 공짜처럼 느껴집니다. 결과적으로 파일은 오로지 커지기만 하고 줄어들지 않으며, 신호 대 잡음비(SNR)는 지속적으로 하락합니다. 이것은 소프트웨어의 기술 부채 축적과 정확히 같습니다.
+
+**모순이 쌓입니다.** 서로 다른 시점에 추가된 명령들이 서로 충돌하기 시작합니다. 한쪽은 "TypeScript strict 모드를 사용하라"고 하고, 다른 쪽은 "일부 레거시 파일은 any 타입을 허용한다"고 합니다. 에이전트는 매번 하나를 임의로 골라 따릅니다. 엄마가 "따뜻하게 입어라", 아빠가 "너무 두껍게 입지 마라"라고 하는 상황에서 문 앞에 서서 누구 말을 들어야 할지 모르는 것과 같습니다.
+
+## 핵심 개념
+
+- **명령 비대화(Instruction Bloat)**: 명령 파일이 컨텍스트 윈도의 10~15%를 초과하면 코드 읽기와 작업 추론에 쓸 예산을 잠식하기 시작합니다. 600줄짜리 `AGENTS.md`는 10,000~20,000 토큰을 소비할 수 있으며, 이는 에이전트가 시작하기도 전에 128K 윈도의 8~15%가 소진되는 것입니다.
+- **중간 손실 효과(Lost in the Middle Effect)**: Liu et al.의 2023년 연구는 LLM이 긴 텍스트의 중간 정보를 처음이나 끝 정보보다 훨씬 덜 효과적으로 활용한다는 것을 증명했습니다. 600줄 파일의 300번째 줄에 묻힌 중요한 제약은 사실상 무시될 가능성이 매우 높습니다.
+- **명령 신호 대 잡음비(SNR)**: 파일 안의 명령 중 현재 작업과 관련된 비율입니다. 버그 수정 중에 배포 명령 50줄을 읽어야 한다면, 그것은 낮은 SNR입니다.
+- **라우팅 파일(Routing File)**: 모든 것을 담는 것이 아니라 에이전트를 더 상세한 문서로 안내하는 것이 핵심 기능인 짧은 진입 파일. 50~200줄이면 충분합니다.
+- **점진적 공개(Progressive Disclosure)**: 먼저 개요 정보를 제공하고, 필요할 때 상세 정보를 제공합니다. 좋은 해네스 설계는 좋은 UI 설계와 같습니다. 모든 옵션을 한 번에 사용자에게 쏟아붓지 않습니다.
+- **우선순위 모호성(Priority Ambiguity)**: 모든 명령이 같은 형식과 위치에 나타나면, 에이전트는 협상 불가능한 하드 제약과 권장적인 소프트 가이드라인을 구별할 수 없습니다.
+
+## 명령 아키텍처
+
+```mermaid
+flowchart LR
+ Mono["600줄짜리 단일 AGENTS.md"] --> MonoLoad["간단한 버그 수정에도<br/>배포 규칙과 오래된 메모를 모두 읽어야 함"]
+ MonoLoad --> MonoRisk["중간에 묻힌 중요 규칙은<br/>쉽게 놓칠 수 있음"]
+
+ Router["짧은 AGENTS.md"] --> Topics["이 작업에 필요한 경우에만<br/>API / DB / 테스트 문서를 로드"]
+ Topics --> RoutedResult["코드 읽기와 검증에<br/>더 많은 컨텍스트가 남음"]
+```
+
+```mermaid
+flowchart TB
+ File["600줄짜리 명령 파일"] --> Top["상단 섹션<br/>빠른 시작 + 하드 제약"]
+ File --> Mid["중간 섹션<br/>300번째 줄의 중요한 보안 규칙"]
+ File --> Bot["하단 섹션<br/>파일 끝의 명시적 체크리스트"]
+ Top --> Seen["높은 회상 가능성"]
+ Bot --> Seen
+ Mid --> Missed["희석되거나 놓칠 가능성 높음"]
+```
+
+## 분산하는 방법
+
+핵심 원칙: 자주 필요한 정보는 손에 닿는 곳에, 가끔 필요한 정보는 치워두고, 결코 쓰지 않을 정보는 버립니다.
+
+진입 파일인 `AGENTS.md`는 50~200줄로 유지하며, 가장 자주 사용하는 항목만 담습니다. 프로젝트 개요(한두 문장), 첫 실행 명령(`make setup && make test`), 전역 하드 제약(협상 불가능한 규칙 최대 15개), 그리고 주제 문서 링크(한 줄 설명 + 적용 조건)입니다.
+
+```markdown
+# AGENTS.md
+
+## 프로젝트 개요
+Python 3.11 FastAPI 백엔드, PostgreSQL 15 데이터베이스.
+
+## 빠른 시작
+- 설치: `make setup`
+- 테스트: `make test`
+- 전체 검증: `make check`
+
+## 하드 제약
+- 모든 API는 OAuth 2.0 인증을 사용해야 함
+- 모든 데이터베이스 쿼리는 SQLAlchemy 2.0 문법을 사용해야 함
+- 모든 PR은 pytest + mypy --strict + ruff check를 통과해야 함
+
+## 주제 문서
+- [API 설계 패턴](docs/api-patterns.md) — 엔드포인트 추가 시 필독
+- [데이터베이스 규칙](docs/database-rules.md) — 데이터베이스 작업 수정 시 필독
+- [테스트 표준](docs/testing-standards.md) — 테스트 작성 시 참조
+```
+
+각 주제 문서는 50~150줄이며, `docs/` 디렉터리 또는 해당 모듈 옆에 주제별로 정리됩니다. 에이전트는 필요할 때만 읽습니다. 여행 가방 안의 패킹 큐브와 같습니다. 속옷은 한 큐브에, 세면도구는 다른 큐브에, 충전기는 세 번째 큐브에. 전체 가방을 비우지 않아도 원하는 것을 찾을 수 있습니다.
+
+일부 정보는 코드 안에 직접 배치하는 것이 더 낫습니다. 타입 정의, 인터페이스 주석, 설정 파일의 설명 등입니다. 에이전트는 코드를 읽을 때 자연스럽게 이것들을 보게 되므로, 명령 파일에 중복할 필요가 없습니다.
+
+모든 명령에는 출처("이 규칙은 왜 추가됐는가?"), 적용 조건("이 규칙은 언제 필요한가?"), 만료 조건("어떤 상황에서 이 규칙을 제거할 수 있는가?")이 있어야 합니다. 정기적으로 감사하고, 오래되거나 중복되거나 모순된 항목을 제거합니다. 코드 의존성을 관리하듯 명령을 관리하세요. 사용하지 않는 의존성은 삭제해야 합니다. 그렇지 않으면 시스템이 느려질 뿐입니다.
+
+명령이 반드시 진입 파일에 있어야 한다면, 맨 위나 맨 아래에 두세요. 절대 중간에 두지 마세요. "중간 손실" 효과는 LLM이 양 끝의 정보를 중간보다 훨씬 더 잘 활용한다는 것을 알려줍니다. 하지만 더 나은 접근법은 명령을 주제 문서로 옮겨 필요할 때만 로드하는 것입니다.
+
+OpenAI와 Anthropic 모두 분산 접근 방식을 암묵적으로 지지합니다. OpenAI는 진입 파일이 "짧고 라우팅 중심"이어야 한다고 말하고, Anthropic은 장기 실행 에이전트 제어 정보가 "간결하고 높은 우선순위"여야 한다고 말합니다. 둘 다 같은 말을 하고 있습니다. 모든 것을 하나의 파일에 구겨 넣지 말라는 것입니다. 여행 가방도 정리가 필요합니다. 무작정 욱여넣는 것이 아니라.
+
+## 실제 사례
+
+한 SaaS 팀의 `AGENTS.md`가 50줄에서 600줄로 불었습니다. 내용은 기술 스택 버전, 코딩 표준, 역사적 버그 수정 메모, API 사용 가이드, 배포 절차, 팀원들의 개인 선호도가 뒤섞여 있었습니다. 여행 가방이 터질 지경이었습니다.
+
+에이전트 성능이 눈에 띄게 저하되기 시작했습니다. 간단한 버그 수정 중에도 에이전트가 관련 없는 배포 명령을 처리하느라 많은 컨텍스트를 낭비했고, "모든 데이터베이스 쿼리는 매개변수화된 쿼리를 사용해야 한다"는 보안 제약이 300번째 줄에 묻혀 자주 무시됐으며, 서로 모순된 코드 스타일 규칙 세 개가 에이전트의 임의적인 행동을 유발했습니다.
+
+팀은 "여행 가방 재정리"를 실행했습니다.
+1. `AGENTS.md`를 80줄로 줄임: 프로젝트 개요, 실행 명령, 전역 하드 제약 15개만 남김
+2. 주제 문서 생성: `docs/api-patterns.md`(120줄), `docs/database-rules.md`(60줄), `docs/testing-standards.md`(80줄)
+3. 라우팅 파일에 주제 문서 링크 추가
+4. 역사적 메모는 테스트 케이스로 전환하거나 삭제
+
+리팩터링 후: 동일 작업 세트 성공률이 45%에서 72%로 올랐습니다. 보안 제약 준수율은 60%에서 95%로 상승했는데, 이는 파일 중간에서 라우팅 파일 상단으로 이동해 더 이상 "중간에서 길을 잃지" 않게 됐기 때문입니다.
+
+## 핵심 정리
+
+- "규칙 추가"는 단기 진통제이고 장기 독약입니다. 규칙을 추가하기 전에 먼저 물어보세요: 이게 주제 문서에 더 적합하지 않을까요? 가방에 물건을 계속 욱여넣지 마세요.
+- 진입 파일은 라우터이지 백과사전이 아닙니다. 50~200줄에 개요, 하드 제약, 링크만 담으세요.
+- "중간 손실" 효과를 활용하세요: 중요한 정보는 위나 아래에, 덜 중요한 정보는 주제 문서로 이동합니다.
+- 명령 비대화를 기술 부채처럼 관리하세요. 정기적인 감사, 모든 명령에 출처·적용 조건·만료 조건이 필요합니다.
+- 분산 후 SNR이 개선되고 에이전트는 관련 없는 명령을 처리하는 대신 실제 작업에 더 많은 컨텍스트 예산을 씁니다.
+
+## 더 읽어보기
+
+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)
+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+- [Lost in the Middle: How Language Models Use Long Contexts](https://arxiv.org/abs/2307.03172)
+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)
+- [Nielsen Norman Group: Progressive Disclosure](https://www.nngroup.com/articles/progressive-disclosure/)
+
+## 연습 문제
+
+1. **SNR 감사**: 현재 진입 명령 파일을 가져와 모든 명령 항목을 나열하세요. 흔한 작업 유형 5가지를 골라 각 명령이 해당 작업과 관련 있는지 표시하세요. 각 작업 유형별 SNR을 계산하세요. 대부분의 작업에서 잡음인 명령은 주제 문서로 이동해야 합니다.
+
+2. **점진적 공개 리팩터**: 300줄 이상의 명령 파일이 있다면 다음으로 분리하세요: (a) 100줄 미만의 라우팅 파일, (b) 3~5개의 주제 문서. 분리 전후에 동일한 작업 세트(최소 5개)를 실행하고 성공률을 비교하세요.
+
+3. **중간 손실 검증**: 긴 명령 파일에서 중요한 제약을 각각 맨 위, 중간, 맨 아래에 배치하고 동일한 작업 세트를 실행하세요(위치당 최소 5회). 준수율에 차이가 있는지 확인하세요. 위치 효과가 얼마나 강력한지 놀랄 수도 있습니다.
diff --git a/docs/ko/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md b/docs/ko/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md
new file mode 100644
index 0000000..1c8ab44
--- /dev/null
+++ b/docs/ko/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md
@@ -0,0 +1,6 @@
+# 연속성(continuity) 체크리스트
+
+- 새로운 에이전트가 5분 이내에 최근 작업을 파악할 수 있습니까?
+- 현재의 안정적인 시작 경로가 문서화되어 있습니까?
+- 미완료 작업이 명확히 식별되어 있습니까?
+- 이전 채팅 로그를 읽지 않고도 다음으로 가장 좋은 작업이 보입니까?
diff --git a/docs/ko/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md b/docs/ko/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md
new file mode 100644
index 0000000..59b9f9d
--- /dev/null
+++ b/docs/ko/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md
@@ -0,0 +1,7 @@
+# 강의 05 코드 예제
+
+이 폴더는 다음 예제들을 위해 사용합니다.
+
+- 멀티 세션 작업의 연속성이 끊긴 사례
+- 연속성 산출물(continuity artifacts)이 누락된 경우
+- 연속성 복구 패턴
diff --git a/docs/ko/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md b/docs/ko/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md
new file mode 100644
index 0000000..c6b3370
--- /dev/null
+++ b/docs/ko/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md
@@ -0,0 +1,17 @@
+# 세션 핸드오프(Session Handoff) 예제
+
+## 완료된 항목
+
+- 마크다운 가져오기 지원 추가
+- 렌더러에 기본 문서 목록 추가
+
+## 깨지거나 미검증된 항목
+
+- `.md` 가져오기는 성공하지만 큰 `.txt` 파일은 실패함
+- 앱은 시작되지만 상세 보기가 아직 연결되지 않음
+
+## 다음으로 가장 좋은 단계
+
+- `.txt` 가져오기 경로 수정
+- 가져오기 엔드투엔드 검증
+- 이후 문서 상세 패널 추가
diff --git a/docs/ko/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/ko/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
new file mode 100644
index 0000000..33a07ec
--- /dev/null
+++ b/docs/ko/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -0,0 +1,180 @@
+[中文版本 →](../../../zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/)
+
+> 코드 예제: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/)
+> 실습 프로젝트: [Project 03. 멀티 세션 연속성](./../../projects/project-03-multi-session-continuity/index.md)
+
+# 강의 05. 세션을 넘어 컨텍스트를 살아있게 유지하라
+
+Claude Code에게 완전한 기능을 구현하도록 요청합니다. 30분 동안 실행되며 대부분의 작업을 완료하지만 컨텍스트(context)가 거의 소진됩니다. 계속하기 위해 새 세션을 시작하면, 지난번에 어떤 결정이 내려졌는지, 왜 옵션 A가 아닌 옵션 B가 선택됐는지, 어떤 파일이 이미 수정됐는지, 테스트 상태가 어떤지를 기억하지 못한다는 것을 발견합니다. 프로젝트를 재탐색하는 데 15분을 쓰고, 이전 접근법과 일관성이 없을 수도 있습니다.
+
+매일 아침 일어나면 모든 것을 잊어버리는 장인을 상상해 보세요. 건설 현장 전체를 다시 파악해야 합니다. 어떤 벽이 반쯤 지어졌는지, 왜 파란 벽돌이 아닌 빨간 벽돌을 선택했는지, 배관 공사가 어디까지 진행됐는지를요. 더 나쁜 경우, 어제 이미 설치된 창문을 그것이 완료됐다는 것을 기억하지 못해서 뜯어낼 수도 있습니다.
+
+이것이 바로 장기 작업에서 AI 코딩 에이전트(agent)가 처한 딜레마입니다. 이 강의는 에이전트가 장기 작업 중에 "블랙아웃"되는 이유와, 구조화된 상태(state) 영속화가 에이전트를 신뢰할 수 있는 일일 일지를 갖춘 장인으로 만드는 방법을 설명합니다. 여전히 건망증이 있지만, 일지가 모든 것을 기억합니다.
+
+## 컨텍스트 윈도는 무한하지 않습니다
+
+컨텍스트 윈도는 유한합니다. 이것은 모델 업그레이드로 해결할 수 없는 문제입니다. 윈도 크기가 1M 토큰으로 커지더라도 복잡한 작업은 결국 소진될 것입니다. 에이전트는 단순히 코드를 생성하는 것이 아닙니다. 코드베이스를 이해하고, 자신의 결정 이력을 추적하고, 도구 출력을 처리하고, 대화 컨텍스트를 유지합니다. 이 모든 정보는 윈도 확장보다 빠르게 증가합니다.
+
+더 깊은 문제가 있습니다. 에이전트가 생성하는 정보가 균등하게 중요하지 않다는 것입니다. 중간 추론 단계에는 결정의 "왜"가 담겨 있습니다. 왜 옵션 A가 아닌 옵션 B를 선택했는지, 왜 이 라이브러리를 저 라이브러리 대신 사용했는지, 왜 특정 최적화를 건너뛰었는지를요. 최종 출력에는 "무엇"만 담겨 있습니다. 코드 자체입니다. 컴팩션(compaction) 전략은 보통 후자를 보존하지만 전자를 잃습니다. 다음 세션은 코드를 보지만 왜 그렇게 작성됐는지 알지 못하며, 의도적인 설계 결정을 "최적화"해 버릴 수도 있습니다.
+
+Anthropic은 자신들의 장기 실행 에이전트 연구에서 흥미로운 사실을 발견했습니다. 에이전트가 컨텍스트가 소진되고 있다고 느끼면 "조기 수렴" 행동을 보인다는 것입니다. 현재 작업을 서둘러 마무리하고, 검증 단계를 건너뛰거나, 최적의 해결책 대신 간단한 해결책을 선택합니다. 시험에서 시간이 얼마 남지 않았다는 것을 깨닫고 나머지 객관식 문제에 급하게 임의로 답을 채워넣는 것과 같습니다. Anthropic은 이를 "컨텍스트 불안(context anxiety)"이라고 부릅니다.
+
+## 세션 연속성(continuity) 흐름
+
+연속성 산출물(continuity artifacts)이 없으면 모든 새 세션은 재앙입니다.
+
+```mermaid
+flowchart LR
+ S1["세션 1<br/>기능이 절반 완성"] --> End1["컨텍스트 거의 소진<br/>세션 종료"]
+ End1 --> S2["세션 2 새로 시작"]
+ S2 --> Guess["폴더 재탐색, 테스트 재실행,<br/>코드가 왜 이렇게 작성됐는지 추측"]
+ Guess --> Drift["작업이 반복되고<br/>복구가 느림"]
+```
+
+연속성 산출물이 있으면 새 세션이 빠르게 이어받을 수 있습니다.
+
+```mermaid
+flowchart LR
+ Work["세션 1 작업"] --> Progress["PROGRESS.md<br/>완료 / 진행 중 / 다음 단계"]
+ Work --> Decisions["DECISIONS.md<br/>왜 이 접근법을 선택했는지"]
+ Work --> Verify["검증 메모<br/>어떤 테스트가 통과하고 실패하는지"]
+ Work --> Commit["Git 체크포인트<br/>정확한 저장소 상태"]
+
+ Progress --> Rebuild["세션 2 재구축"]
+ Decisions --> Rebuild
+ Verify --> Rebuild
+ Commit --> Rebuild
+
+ Rebuild --> Resume["새 세션이 빠르게 이어받음"]
+```
+
+## 핵심 개념
+
+- **컨텍스트 윈도는 유한합니다**: 어떤 윈도 크기가 주장되더라도(128K, 200K, 1M), 긴 작업은 결국 소진됩니다. 소진 후에는 컴팩션(정보 손실) 또는 리셋(새 세션)이 필요합니다. 둘 다 무언가를 잃습니다.
+- **연속성 산출물**: 새 세션이 이전 세션이 중단한 곳에서 명확하게 재개할 수 있도록 해주는 영속화된 상태 파일입니다. 기본 형태: 진행 로그 + 검증(verification) 기록 + 다음 행동. 그 장인의 일지입니다.
+- **재구축 비용(Rebuild cost)**: 새 세션이 실행 가능한 상태에 도달하는 데 필요한 시간. 좋은 해네스는 재구축 비용을 15분에서 3분으로 줄일 수 있습니다.
+- **드리프트(Drift)**: 에이전트의 이해와 코드 저장소(repository)의 실제 상태 사이의 간극. 모든 세션 경계는 드리프트를 유발하며, 통제하지 않으면 누적됩니다.
+- **컨텍스트 불안(Context anxiety)**: Anthropic이 관찰한 현상으로, 에이전트가 인식된 컨텍스트 한계에 접근하면 조기 수렴 행동을 보이며 정보 손실을 피하기 위해 작업을 일찍 마무리합니다. 비합리적인 자원 불안입니다.
+- **컴팩션 vs 리셋**: 컴팩션은 동일 세션 내에서 초기 대화를 요약합니다("무엇"은 유지하지만 "왜"를 잃을 수 있음). 리셋은 새 세션을 열어 영속화된 상태에서 재구축합니다(깔끔하지만 산출물 완전성에 의존함).
+
+## 연속성이 깨지면 어떤 일이 벌어지나
+
+이전 세션은 상당한 컨텍스트 예산을 사용해 세 가지 접근법을 분석하고 옵션 B를 선택했습니다. 이번 세션의 에이전트는 그 분석을 모르고 불완전한 정보를 바탕으로 다시 결정을 내릴 수 있습니다. 왜 빨간 벽돌이 선택됐는지 기억하지 못하는 건망증 장인이 오늘 파란 벽돌을 보고 더 예쁘다고 생각해 어제 쌓은 벽을 허물고 다시 짓는 것과 같습니다.
+
+더 나쁜 것은 중복 작업입니다. 에이전트가 특정 작업이 이미 완료됐는지 확인할 수 없어 다시 합니다. 또는 더 나쁜 경우, 절반만 하다가 기존 구현과의 충돌을 발견하고 다시 작업해야 합니다. 건설 현장에서 두 팀이 동시에 같은 벽을 지을 수 없습니다. 하지만 진행 기록이 없으면 새 팀은 누군가가 이미 그것을 하고 있다는 것을 알 수 없습니다.
+
+여러 세션에 걸쳐 구현 방향이 원래 요구사항에서 조용히 벗어났을 수도 있습니다. 각 새 세션은 프로젝트 목표에 대해 약간 다른 이해를 가집니다. 전화 전달 게임처럼, 열 명이 메시지를 전달한 후 "커피 한 잔 가져다 줘"가 "커피 머신을 사줘"가 될 수 있습니다.
+
+검증 격차도 있습니다. 이전 세션의 검증 결과(어떤 테스트가 통과하고, 실패하고, 왜 실패하는지)가 기록되지 않았습니다. 새 세션은 현재 상태를 이해하기 위해 모든 검증을 다시 실행해야 합니다. 매 세션마다 처음부터 진단하고, 매번 귀중한 컨텍스트를 낭비합니다.
+
+OpenAI와 Anthropic 모두 자신들의 문서에서 구조화된 상태 영속화를 강조합니다. OpenAI의 해네스 엔지니어링 기사는 저장소를 "운영 기록"으로 취급합니다. 모든 작업의 결과는 저장소에 추적 가능한 증거를 남겨야 합니다. Anthropic의 장기 실행 에이전트 문서는 "핸드오프(handoff) 파일"을 명시적으로 권장합니다. 현재 상태, 알려진 이슈, 다음 행동을 담은 구조화된 문서입니다.
+
+## 건망증 장인을 위한 일지
+
+핵심 접근법: **에이전트를 건망증이 있는 뛰어난 엔지니어처럼 취급하세요.** "퇴근" 전에 다음 "교대" 에이전트가 빠르게 이어받을 수 있도록 중요한 정보를 적어두어야 합니다.
+
+**도구 1: 진행 파일(PROGRESS.md).** 가장 기본적인 연속성 산출물, 일지의 핵심입니다.
+
+```markdown
+# 프로젝트 진행 상황
+
+## 현재 상태
+- 최신 커밋: abc1234 (feat: add user preferences endpoint)
+- 테스트 상태: 42/43 통과 (test_pagination_edge_case 실패)
+- 린트: 통과
+
+## 완료된 항목
+- [x] 사용자 모델 및 데이터베이스 마이그레이션
+- [x] 기본 CRUD 엔드포인트
+- [x] 인증 미들웨어 통합
+
+## 진행 중
+- [ ] 페이지네이션 기능 (90% - 엣지 케이스 테스트 실패 중)
+
+## 알려진 이슈
+- test_pagination_edge_case가 빈 결과 세트에서 500을 반환함
+- 삭제된 사용자가 목록에 표시돼야 하는지 확인 필요
+
+## 다음 단계
+1. 페이지네이션 엣지 케이스 버그 수정
+2. "삭제된 사용자 포함" 쿼리 매개변수 추가
+3. API 문서 업데이트
+```
+
+**도구 2: 결정 로그(DECISIONS.md).** 중요한 설계 결정과 이유를 기록합니다. 상세한 설계 문서가 필요하지 않습니다. "어떤 결정, 왜, 언제"만 있으면 됩니다. 일지의 메모입니다.
+
+```markdown
+# 설계 결정
+
+## 2024-01-15: 사용자 선호도 캐싱에 Redis 사용
+- 이유: 읽기 빈도 높음 (모든 API 호출), 데이터 크기 작음
+- 거부된 대안: PostgreSQL 구체화 뷰 (변경 빈도가 높아 유지보수 비용이 수지에 맞지 않음)
+- 제약: 캐시 TTL 5분, 쓰기 시 능동적 무효화
+```
+
+**도구 3: Git 커밋을 체크포인트로.** 각 원자적 작업 단위 완료 후 커밋합니다. 커밋 메시지는 무엇을 했고 왜 했는지를 설명해야 합니다. 이것은 무료로 자동으로 버전이 관리되는 상태 스냅샷입니다.
+
+**도구 4: init.sh 또는 해네스 초기화 흐름.** `AGENTS.md`에 "출근"과 "퇴근" 루틴을 명시합니다.
+
+```markdown
+## 세션 시작 시 (출근)
+1. PROGRESS.md를 읽어 현재 상태 파악
+2. DECISIONS.md를 읽어 중요 결정 파악
+3. make check를 실행해 저장소가 일관된 상태인지 확인
+4. PROGRESS.md의 "다음 단계" 섹션에서 이어서 진행
+
+## 세션 종료 전 (퇴근)
+1. PROGRESS.md 업데이트
+2. make check를 실행해 일관된 상태 확인
+3. 완료된 모든 작업 커밋
+```
+
+**혼합 전략**: 모든 작업에 컨텍스트 리셋이 필요하지 않습니다. 짧은 작업(30분 이하)은 한 세션 내에서 완료할 수 있습니다. 긴 작업(세션에 걸쳐 있는)은 연속성을 위해 진행 파일과 결정 로그를 사용해야 합니다. 결정 기준: 작업에 윈도의 60% 이상이 필요하다면 핸드오프(handoff) 준비를 시작하세요.
+
+### 컨텍스트 불안 깊이 보기
+
+Anthropic의 2026년 3월 연구는 컨텍스트 불안의 구체적인 발현을 추가로 밝혔습니다. Sonnet 4.5에서 컨텍스트가 윈도 한계에 접근하면 에이전트가 강한 "조기 수렴" 행동을 보입니다. 시험에서 시간이 거의 다 됐다는 것을 깨닫고 객관식 문제에 급하게 임의 답을 채워넣는 것과 같습니다.
+
+두 가지 전략으로 이에 대처합니다.
+
+**컴팩션**: 같은 세션 내에서 초기 대화를 요약합니다. 장점: 연속성을 유지하며 에이전트가 "무엇"을 볼 수 있습니다. 단점: "왜"는 요약에서 자주 사라집니다. 왜 옵션 B가 옵션 A 대신 선택됐는지, 왜 특정 최적화가 건너뛰어졌는지요. 더 결정적으로, 컴팩션은 컨텍스트 불안을 없애지 않습니다. 에이전트는 컨텍스트가 한때 컸다는 것을 알고, 심리적으로 여전히 종결을 서두르는 경향이 있습니다.
+
+**컨텍스트 리셋**: 컨텍스트를 완전히 지우고, 새 세션을 열고, 영속화된 산출물에서 재구축합니다. 장점: 깨끗한 정신 상태로 새 세션에는 "시간이 촉박하다"는 불안이 없습니다. 단점: 핸드오프 산출물의 완전성에 의존합니다. 일지에 중요한 정보가 빠져 있으면 새 세션이 잘못된 방향으로 시간을 낭비할 수 있습니다.
+
+Anthropic의 실제 데이터: Sonnet 4.5에서 컨텍스트 불안이 심각해서 컴팩션만으로는 충분하지 않으며, 컨텍스트 리셋이 해네스 설계의 중요한 구성 요소가 됩니다. 하지만 Opus 4.5에서는 이 행동이 크게 줄어들어 컴팩션으로 리셋에 의존하지 않고 컨텍스트를 관리할 수 있습니다. 이것이 의미하는 바: **해네스 설계는 대상 모델에 대한 구체적인 이해가 필요하며, 일률적인 템플릿이 아닙니다.**
+
+> 출처: [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
+
+## 실제 사례
+
+에이전트에게 사용자 인증이 있는 블로그 시스템 구현을 맡겼습니다. 기능 포인트 12개, 예상 5세션이 필요합니다.
+
+**일지 없는 기준선**: 세션 1에서 사용자 모델과 기본 라우트를 구현했습니다. 세션 2는 에이전트가 인증 미들웨어의 인터페이스 계약을 기억하지 못해 이전 설계 의도를 추론하는 데 약 15분을 썼습니다. 세션 3에서는 누적된 드리프트로 에이전트가 이미 완료된 기능을 다시 구현하기 시작했습니다. 세션 5에서는 저장소에 중복 코드가 많았지만 핵심 인증 기능은 여전히 엔드투엔드 테스트를 통과하지 못했습니다. 12개 기능 포인트 중 7개만 완료됐고, 3개는 숨겨진 정확성 문제가 있었습니다. 일지를 쓰지 않는 장인처럼, 5일째 건설 현장은 혼돈입니다. 어떤 벽은 두 번 지어졌고, 지어져야 했던 어떤 벽은 시작도 안 됐습니다.
+
+**일지 있는 경우**: 진행 파일, 결정 로그, 검증 기록, git 체크포인트를 사용했습니다. 각 세션 종료 시 상태 보고서가 자동으로 업데이트됐습니다. 세션 2의 재구축 비용이 약 3분으로 줄었습니다. 세션 5에서 12개 기능 포인트 모두 완료되고 검증됐습니다.
+
+정량적 비교: 재구축 시간이 약 78% 감소했고, 기능 완료율은 58%에서 100%로, 숨겨진 결함율은 43%에서 8%로 낮아졌습니다. 장인은 여전히 건망증이 있지만, 일지 덕분에 매일 어제가 멈춘 곳에서 시작합니다. 처음부터가 아니라.
+
+## 핵심 정리
+
+- 컨텍스트 윈도는 유한한 자원입니다. 긴 작업은 세션에 걸쳐 이어지고, 세션은 정보를 잃습니다. 매일 잊어버리는 장인처럼, 이것은 객관적인 현실입니다.
+- 해결책은 더 큰 윈도가 아닙니다. 더 나은 상태 영속화입니다. 진행 파일 + 결정 로그 + git 체크포인트로 건망증 장인에게 신뢰할 수 있는 일지를 제공하세요.
+- 에이전트를 건망증 있는 엔지니어처럼 취급하세요. "퇴근" 전에 무엇을 했는지, 왜 했는지, 다음은 무엇인지를 적어두세요.
+- 재구축 비용이 핵심 지표입니다. 좋은 해네스는 새 세션이 3분 이내에 실행 가능한 상태에 도달하도록 해야 합니다.
+- 혼합 전략: 짧은 작업은 세션 내에서, 긴 작업은 구조화된 산출물로 연속성을 유지합니다.
+
+## 더 읽어보기
+
+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)
+- [Lost in the Middle: How Language Models Use Long Contexts](https://arxiv.org/abs/2307.03172)
+- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)
+
+## 연습 문제
+
+1. **연속성 손실 측정**: 최소 3세션이 필요한 개발 작업을 고르세요. 연속성 산출물을 제공하지 않고, 각 세션 시작 시 에이전트가 "지난번에 무슨 일이 있었는지" 파악하는 데 얼마나 많은 컨텍스트를 소비하는지 기록하세요. 각 세션 후 진행 파일을 만들고 다음 세션이 그것에서 시작하게 하세요. 진행 파일 있을 때와 없을 때의 재구축 비용을 비교하세요.
+
+2. **핸드오프 템플릿 설계**: 네 개의 필드를 가진 최소 핸드오프(handoff) 템플릿을 설계하세요: 저장소 상태(커밋 해시), 실행 상태(테스트 통과율), 차단 항목, 다음 행동. 완전히 새로운 에이전트 세션이 오직 이 템플릿만을 사용해 프로젝트 상태를 복원하게 하세요. 복원 중 만난 모호함을 기록하고, 템플릿을 개선하세요.
+
+3. **혼합 전략 실험**: 5세션짜리 개발 작업에서 세 가지 전략을 비교하세요: (a) 항상 새 세션 시작 + 진행 파일, (b) 한 세션에서 최대한 많이 하기(컨텍스트 컴팩션), (c) 혼합 전략(짧은 작업은 세션 내, 긴 작업은 세션 간 + 진행 파일). 재구축 시간, 기능 완료율, 결정 일관성을 비교하세요.
diff --git a/docs/ko/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md b/docs/ko/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md
new file mode 100644
index 0000000..4af8347
--- /dev/null
+++ b/docs/ko/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md
@@ -0,0 +1,8 @@
+# 강의 06 코드 예제
+
+이 폴더는 다음 예제들을 위해 사용합니다.
+
+- 초기화(initializer) 출력물
+- init 스크립트
+- 진행 파일
+- 첫 실행 스캐폴딩
diff --git a/docs/ko/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md b/docs/ko/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md
new file mode 100644
index 0000000..b43c368
--- /dev/null
+++ b/docs/ko/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md
@@ -0,0 +1,7 @@
+# 초기화(Initializer) 출력 체크리스트
+
+- 표준 시작 명령이 있습니까?
+- 표준 검증 명령이 있습니까?
+- 첫 번째 진행 산출물이 있습니까?
+- 안정적인 첫 번째 커밋이 있습니까?
+- 이후 실행을 위한 가시적인 기능 표면이 있습니까?
diff --git a/docs/ko/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/ko/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
new file mode 100644
index 0000000..477f568
--- /dev/null
+++ b/docs/ko/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -0,0 +1,157 @@
+[中文版本 →](../../../zh/lectures/lecture-06-why-initialization-needs-its-own-phase/)
+
+> 코드 예제: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/code/)
+> 실습 프로젝트: [Project 03. 멀티 세션 연속성](./../../projects/project-03-multi-session-continuity/index.md)
+
+# 강의 06. 모든 에이전트 세션 전에 초기화하라
+
+새 에이전트(agent) 세션을 시작하고 "검색 기능을 추가해줘"라고 말합니다. 에이전트가 바로 코딩에 뛰어듭니다. 훌륭한 열정입니다. 20분 후 테스트 프레임워크가 제대로 설정되지 않았다는 것을 발견하고, 그것을 수정하는 데 10분을 더 씁니다. 그러다 데이터베이스 마이그레이션 스크립트 형식이 잘못됐다는 것을 알게 되어 또 수정합니다. 검색 기능은 결국 추가되지만, 전체 세션이 비효율적이었습니다. 대부분의 시간이 검색 기능을 작성하는 것이 아닌 "이 프로젝트가 어떻게 작동하는지 파악하기"에 사용됐습니다.
+
+더 나은 접근법은 이렇습니다. 에이전트가 작업을 시작하기 전에, 별도의 단계를 사용해 기본 환경을 준비하고, 검증 명령이 통과하도록 하고, 프로젝트 구조를 이해합니다. 집을 짓는 것과 같습니다. 기초를 붓고 동시에 벽을 세우지 않습니다. 그렇게 하면 기초가 굳기 전에 벽이 올라가고, 건물 전체를 허물고 다시 시작해야 합니다. 먼저 기초를 붓고, 굳힌 다음, 벽을 세웁니다. 깔끔하고 효율적입니다.
+
+이 강의는 초기화(initialization)가 구현과 혼합되지 않고 왜 별도의 단계여야 하는지 설명합니다.
+
+## 기초와 벽: 근본적으로 다른 두 가지 작업
+
+초기화와 구현은 완전히 다른 최적화 목표를 가집니다. 구현 단계는 검증된 기능의 수량과 품질을 극대화하는 것을 최적화합니다. 초기화(initialization) 단계는 이후 모든 구현의 신뢰성과 효율성을 극대화하는 것을 최적화합니다.
+
+초기화와 구현을 혼합하면 에이전트는 다중 목표 최적화 문제에 직면합니다. 동시에 인프라를 구축하고 기능 코드를 작성합니다. 명시적인 우선순위 설정 없이는 에이전트가 자연스럽게 코드 작성을 선호합니다(직접 보이는 출력이기 때문에). 인프라는 희생됩니다(그 가치는 이후 세션에서만 나타나기 때문에). 건설 팀에게 동시에 기초를 붓고 벽을 세우라고 하는 것과 같습니다. 팀은 벽이 보이고 보여줄 수 있으니 서두를 것입니다. 하지만 기초가 나쁜 집은 나중에 체계적인 문제를 가집니다.
+
+## 초기화 생명주기
+
+```mermaid
+flowchart TB
+ subgraph Wrong["혼합 세션 (잘못된 방식)"]
+ W1["즉시 기능 작업 시작"] --> W2["작업 중간에 환경·테스트 누락 발견"]
+ W2 --> W3["미검증 코드가 누적됨"]
+ W3 --> W4["다음 세션은 프로젝트 상태를 다시 발견해야 함"]
+ end
+
+ subgraph Right["전용 초기화 (올바른 방식)"]
+ R1["세션 1: 환경 실행 가능"] --> R2["예제 테스트 통과"]
+ R2 --> R3["부트스트랩 계약 + 작업 목록 작성"]
+ R3 --> R4["깨끗한 체크포인트 커밋"]
+ R4 --> R5["이후 세션은 검증된 작업에서 직접 시작"]
+ end
+```
+
+## 혼합했을 때 어떤 일이 벌어지나
+
+가장 직접적인 문제: 기초가 제대로 굳지 않습니다. 에이전트가 기능 코드에 80%의 노력을 쓰고 인프라 설정에 20%만 임시로 씁니다. 테스트 프레임워크가 설정됐지만 검증되지 않았고, 린트 규칙이 설정됐지만 너무 느슨하고, 진행 파일이 만들어지지 않았습니다. 이 결함은 첫 번째 세션에서 명확하지 않습니다(에이전트가 무엇을 했는지 여전히 기억하기 때문에). 하지만 두 번째 세션에서 표면화됩니다. 새 에이전트는 실행 방법, 테스트 방법, 상황이 어떤지를 알지 못합니다. 기초가 부실하면 건물이 흔들립니다.
+
+더 숨겨진 비용은 "미검증 누적"입니다. 테스트 프레임워크가 설정되기 전에 작성된 기능 코드는 검증 없는 코드입니다. 마침내 그 코드에 테스트를 추가하러 돌아갈 때, 처음부터 설계가 잘못됐다는 것을 발견할 수도 있습니다. 알았더라면 다르게 구현했을 것입니다. 젖은 콘크리트 위에 타일을 붙이는 것과 같습니다. 바닥이 평평하지 않다는 것을 발견하면 모든 타일을 들어내고 다시 해야 합니다.
+
+세션 예산도 낭비됩니다. 초기화 작업(환경 설정, 테스트 구성, 프로젝트 구조 이해)이 상당한 예산을 소비해 실제 기능 구현에 남는 것이 적습니다. 결과: 첫 번째 세션에서 기능의 절반만 완료되고, 두 번째 세션은 프로젝트를 다시 이해하는 것부터 시작해야 합니다. 기초에 예산을 썼지만 기초도 단단하지 않습니다. 어떤 목표도 달성하지 못합니다.
+
+가장 쉽게 간과하는 문제는 암묵적 가정의 지뢰밭입니다. 에이전트가 초기화 중에 내리는 결정들(어떤 테스트 프레임워크, 디렉터리 구성 방식, 의존성 관리)이 명시적으로 기록되지 않으면 이후 세션이 이러한 선택을 이해할 수 없습니다. 더 나쁜 경우, 이후 세션이 상충되는 선택을 할 수도 있습니다. 첫 번째 건설 팀이 콘크리트 기초를 사용했는데 두 번째 팀은 그것을 모르고 그 위에 나무 말뚝을 박습니다. 기초가 갈라집니다.
+
+Anthropic의 장기 실행 애플리케이션 개발 연구는 초기화와 구현을 분리할 것을 명시적으로 권장합니다. 그들의 실험 데이터: 전용 초기화 단계를 사용한 프로젝트는 멀티 세션 시나리오에서 혼합 접근법 대비 기능 완료율이 31% 높았습니다. 핵심 통찰은 초기화 단계에 투자한 시간이 이후 3~4세션에서 완전히 회수된다는 것입니다. 기초가 견고할수록 벽이 더 빨리 올라갑니다.
+
+OpenAI의 Codex 해네스 엔지니어링 가이드도 "저장소(repository)를 운영 기록으로" 원칙을 강조합니다. 첫 번째 실행에서 명확한 운영 구조를 확립하거나, 모든 새 세션이 프로젝트 컨벤션을 다시 추론해야 합니다.
+
+## 핵심 개념
+
+- **초기화 단계(Initialization Phase)**: 에이전트 생명주기의 첫 번째 단계로, 기능 구현이 없고 이후 모든 구현 단계의 전제 조건을 확립하는 것만 합니다. 출력은 코드가 아니라 인프라입니다.
+- **부트스트랩 계약(Bootstrap Contract)**: 새로운 에이전트 세션이 프로젝트를 명확하게 운영할 수 있는 조건입니다. 시작할 수 있고, 테스트할 수 있고, 진행 상황을 볼 수 있고, 다음 단계를 파악할 수 있어야 합니다. 네 가지 조건이 모두 필요합니다.
+- **콜드 스타트(Cold Start) vs 웜 스타트(Warm Start)**: 콜드 스타트는 에이전트가 프로젝트 구조를 추측해야 하는 빈 디렉터리에서 시작하는 것입니다. 웜 스타트는 인프라가 이미 갖춰진 템플릿이나 기존 프로젝트에서 시작하는 것입니다. 웜 스타트가 콜드 스타트보다 훨씬 우수합니다. 물과 전기가 들어오는 현장에서 작업을 시작하는 것과 황량한 땅에서 시작하는 것의 차이입니다.
+- **핸드오프 준비성(Handoff Readiness)**: 어느 순간이든 프로젝트가 새로운 에이전트가 인계받을 수 있는 상태인 것. 구두 설명이 필요 없고, 저장소 내용만으로 충분합니다.
+- **첫 번째 검증까지의 시간(Time to First Verification)**: 프로젝트 시작부터 첫 번째 기능 포인트가 검증을 통과할 때까지의 시간. 초기화 효율성을 측정하는 핵심 지표입니다.
+- **다운스트림 사용성(Downstream Usability)**: 초기화 품질을 측정하는 가장 좋은 방법. 암묵적 지식에 의존하지 않고 성공적으로 작업을 실행할 수 있는 이후 세션의 비율.
+
+## 초기화를 올바르게 하는 방법
+
+**초기화를 전용 단계로 취급하세요.** 첫 번째 세션은 초기화만 합니다. 비즈니스 기능 코드는 전혀 없습니다. 초기화가 생성하는 것:
+
+**1. 실행 가능한 환경.** 프로젝트가 시작되고, 의존성이 설치되고, 환경 문제가 없습니다. 기초를 부었고, 균열이 없습니다.
+
+**2. 검증 가능한 테스트 프레임워크.** 최소한 하나의 예제 테스트가 통과합니다. 이것은 테스트 프레임워크 자체가 제대로 설정됐다는 것을 증명합니다. 기초 위에 기둥을 세워 무게를 지탱할 수 있음을 증명하는 것과 같습니다.
+
+**3. 부트스트랩 계약 문서.** 이후 세션에 다음을 알려주는 명확한 문서:
+```markdown
+# 초기화 계약
+
+## 시작 명령
+- 의존성 설치: `make setup`
+- 개발 서버 시작: `make dev`
+- 테스트 실행: `make test`
+- 전체 검증: `make check`
+
+## 현재 상태
+- 모든 의존성 설치 및 잠금
+- 테스트 프레임워크 설정됨 (Vitest + React Testing Library)
+- 예제 테스트 통과 (1/1)
+- 린트 규칙 설정됨 (ESLint + Prettier)
+
+## 프로젝트 구조
+- src/ — 소스 코드
+- src/components/ — React 컴포넌트
+- src/api/ — API 클라이언트
+- tests/ — 테스트 파일
+```
+
+**4. 작업 분해.** 전체 프로젝트를 순서가 있는 작업 목록으로 분리하고, 각 작업에 명확한 인수 기준을 부여합니다.
+```markdown
+# 작업 분해
+
+## 작업 1: 사용자 인증 기본
+- JWT 인증 미들웨어 구현
+- 로그인/회원가입 엔드포인트 추가
+- 인수 기준: pytest tests/test_auth.py 모두 통과
+
+## 작업 2: 사용자 프로필 페이지
+- 사용자 프로필 CRUD 구현
+- 프로필 편집 폼 추가
+- 인수 기준: pytest tests/test_profile.py 모두 통과
+
+## 작업 3: 검색 기능
+- ...
+```
+
+**5. Git 커밋을 체크포인트로.** 초기화가 완료되면 깨끗한 체크포인트를 커밋합니다. 이후 모든 작업은 이 체크포인트에서 시작합니다.
+
+**웜 스타트 전략**: 빈 디렉터리에서 시작하지 마세요. 프로젝트 템플릿(create-react-app, fastapi-template 등)을 사용해 표준 디렉터리 구조, 의존성 설정, 테스트 프레임워크를 미리 설정하세요. 일반적인 초기화 단계를 템플릿에 굽고, 프로젝트별 초기화 작업만 남깁니다. 물과 전기가 들어오는 현장에서 작업을 시작하는 것과 같습니다. 황량한 땅에서 시작하는 것보다 만 배 낫습니다.
+
+**초기화 완료 기준**: "얼마나 많은 코드를 작성했는가"가 아니라, 부트스트랩 계약의 네 가지 조건이 충족됐는지 여부입니다. 시작할 수 있고, 테스트할 수 있고, 진행 상황을 볼 수 있고, 다음 단계를 파악할 수 있어야 합니다. 이 체크리스트로 초기화를 검증하세요:
+
+```markdown
+## 초기화 인수 체크리스트
+- [ ] `make setup`이 처음부터 성공함
+- [ ] `make test`에 최소한 하나의 통과하는 테스트가 있음
+- [ ] 새 에이전트 세션이 저장소 내용만으로 "실행 방법"과 "테스트 방법"을 답할 수 있음
+- [ ] 최소 3개의 작업이 있는 작업 분해 파일이 존재함
+- [ ] 모든 것이 git에 커밋됨
+```
+
+## 실제 사례
+
+React 프론트엔드 프로젝트에 대한 두 가지 초기화 접근법:
+
+**혼합 접근법 (기초를 부으면서 동시에 벽을 세우기)**: 에이전트가 세션 1에서 동시에 프로젝트 스캐폴딩을 만들고 첫 번째 기능을 구현했습니다. 세션 종료 시 저장소에는 실행 가능한 코드가 있었지만: 명시적인 시작/테스트 명령 문서가 없었고, 진행 추적 파일도 없었고, 작업 분해도 없었습니다. 세션 2는 프로젝트 구조, 테스트 프레임워크, 빌드 프로세스를 추론하는 데 약 20분을 썼습니다. 새 건설 팀이 현장에 도착해서 기초가 얼마나 됐는지, 배관 공사가 어디까지 됐는지 알지 못해 하나씩 구멍을 파가며 확인해야 하는 것과 같습니다.
+
+**전용 초기화 (기초 먼저)**: 세션 1에서 초기화만 했습니다. 템플릿에서 디렉터리 구조를 만들고, 테스트 프레임워크(Vitest + React Testing Library)를 설정하고, 하나의 예제 테스트를 작성하고 검증하고, 부트스트랩 계약 문서와 작업 분해 파일을 만들고, 초기 체크포인트를 커밋했습니다. 세션 2의 재구축 시간은 3분 미만이었고, 작업 목록에서 바로 작업을 시작했습니다. 팀이 도착해서 청사진을 한번 보고 어디서 이어받아야 하는지 정확히 아는 것과 같습니다.
+
+전체 프로젝트 주기 비교: 혼합 접근법의 총 재구축 시간(모든 세션 합산)은 전용 초기화 접근법보다 약 60% 더 많았습니다. 초기화에 쓴 추가 20분이 이후 세션에서 여러 배로 회수됐습니다. 견고한 기초가 벽을 더 빨리 올라가게 하는 것과 같습니다. 느린 것이 빠른 것입니다.
+
+## 핵심 정리
+
+- 초기화와 구현은 최적화 목표가 다릅니다. 섞으면 둘 다 끌어내립니다. 기초를 먼저 붓고, 그 다음 벽을 세우세요.
+- 초기화의 출력은 코드가 아닙니다. 인프라입니다: 실행 가능한 환경, 검증 가능한 테스트, 부트스트랩 계약, 작업 분해.
+- 부트스트랩 계약의 네 가지 조건으로 초기화를 검증하세요: 시작할 수 있고, 테스트할 수 있고, 진행 상황을 볼 수 있고, 다음 단계를 파악할 수 있어야 합니다.
+- 웜 스타트가 콜드 스타트보다 낫습니다. 프로젝트 템플릿을 사용해 표준화된 인프라를 미리 설정하세요.
+- 초기화에 투자한 시간은 이후 3~4세션에서 완전히 회수됩니다. 이것은 추가 비용이 아닙니다. 선행 투자입니다. 기초가 견고할수록 건물이 더 빨리 올라갑니다.
+
+## 더 읽어보기
+
+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)
+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)
+- [Infrastructure as Code — Martin Fowler](https://martinfowler.com/bliki/InfrastructureAsCode.html)
+- [SWE-agent: Agent-Computer Interfaces](https://github.com/princeton-nlp/SWE-agent)
+
+## 연습 문제
+
+1. **부트스트랩 계약 설계**: 개발 중인 프로젝트에 대한 완전한 부트스트랩 계약을 작성하세요. 그런 다음 완전히 새로운 에이전트 세션을 열고, 저장소 내용만 보여주고(구두 컨텍스트 없이), 프로젝트를 시작하고, 테스트를 실행하고, 현재 진행 상황을 이해하게 하세요. 마주치는 모든 문제를 기록하세요. 각각이 부트스트랩 계약의 누락된 조항에 해당합니다.
+
+2. **비교 실험**: 적당히 복잡한 새 프로젝트를 고르세요. 접근법 A: 에이전트가 초기화와 첫 번째 구현을 동시에 하게 합니다. 접근법 B: 한 세션을 전용 초기화에 쓰고, 세션 2에서 구현을 시작합니다. 4세션 후 비교: 첫 번째 검증까지의 시간, 재구축 비용, 기능 완료율.
+
+3. **초기화 인수 체크리스트**: 프로젝트를 위한 초기화 인수 체크리스트를 설계하세요. 새로운 에이전트 세션이 각 체크리스트 항목을 실행하고 어떤 것이 통과하고 실패하는지 기록하게 하세요. 실패하는 항목이 해네스를 강화해야 하는 부분입니다.
diff --git a/docs/ko/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md b/docs/ko/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md
new file mode 100644
index 0000000..dc98ec0
--- /dev/null
+++ b/docs/ko/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md
@@ -0,0 +1,8 @@
+# 강의 07 코드 예제
+
+이 폴더는 다음 예제들을 위한 공간입니다:
+
+- 원샷 실패(one-shot failures) 사례
+- 지나치게 큰 작업 프롬프트
+- 점진적 작업 형태 조정
+- 구조화된 기능 범위 표면(feature surface)
diff --git a/docs/ko/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md b/docs/ko/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md
new file mode 100644
index 0000000..59f8c7e
--- /dev/null
+++ b/docs/ko/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md
@@ -0,0 +1,6 @@
+# 다음 작업 템플릿
+
+- 현재 가장 높은 우선순위의 기능:
+- 이 기능이 다음에 오는 이유:
+- 통과로 간주되는 조건:
+- 이 단계에서 변경해서는 안 되는 것:
diff --git a/docs/ko/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md b/docs/ko/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md
new file mode 100644
index 0000000..1883be2
--- /dev/null
+++ b/docs/ko/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md
@@ -0,0 +1,17 @@
+# 범위 표면(Scope Surface) 예제
+
+작업:
+
+- Electron 지식 앱에 인덱싱 기능 추가
+
+나쁜 범위 형태:
+
+- "인덱싱 구현"
+
+더 나은 범위 형태:
+
+- 가져온 문서 파싱
+- 문서를 청크(chunk)로 분할
+- 청크 메타데이터 영속화
+- UI에서 인덱싱 상태 노출
+- 재인덱싱 액션 추가
diff --git a/docs/ko/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/ko/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
new file mode 100644
index 0000000..4f6e506
--- /dev/null
+++ b/docs/ko/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -0,0 +1,134 @@
+[中文版本 →](../../../zh/lectures/lecture-07-why-agents-overreach-and-under-finish/)
+
+> 코드 예제: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/code/)
+> 실습 프로젝트: [프로젝트 04. 런타임 피드백과 범위(scope) 제어](./../../projects/project-04-incremental-indexing/index.md)
+
+# 강의 07. 에이전트에게 명확한 작업 경계를 그어 주어야 합니다
+
+Claude Code에게 "이 프로젝트에 사용자 인증을 추가해 줘"라고 지시하면, 에이전트(agent)는 데이터베이스 스키마를 수정하고, 라우트를 작성하고, 프론트엔드 컴포넌트를 변경하고 — 그 김에 오류 처리 미들웨어까지 리팩터링하기 시작합니다. 두 시간 후 확인해 보면: 수정된 파일 12개, 새로운 코드 800줄, 그리고 단 하나의 기능도 엔드투엔드로 동작하지 않습니다.
+
+"한 번에 너무 많이 베어 물다" — 이 표현은 AI 에이전트에게 특히 잘 들어맞습니다. 에이전트는 "조금 더 해두자"는 충동을 타고납니다. 관련된 것들을 보면 그냥 처리해 버립니다. 마치 간장 한 병 사러 마트에 갔다가 카트 가득 채워 나오는 사람처럼요. 문제는, 사람이 너무 많이 사면 돈만 낭비하지만, 에이전트가 너무 많은 것을 동시에 하면 어느 것 하나도 제대로 마무리되지 않는다는 점입니다.
+
+Anthropic의 "장시간 실행 에이전트를 위한 효과적인 해네스(harness)" 엔지니어링 블로그는 명확하게 밝힙니다: 프롬프트가 지나치게 넓으면, 에이전트는 "한 가지를 먼저 끝내기"보다 "여러 가지를 동시에 시작"하는 경향이 있다고. OpenAI의 Codex 엔지니어링 실천 사례에서도 같은 현상이 관찰되었습니다 — 명시적인 범위 제어가 없는 작업은 완료율이 급락합니다. 이것은 모델의 문제가 아닙니다 — 해네스의 문제입니다. 경계를 그어주지 않은 것입니다.
+
+## 주의력은 유한한 자원입니다
+
+이것은 비유가 아니라 수학입니다. 에이전트의 컨텍스트(context) 용량을 C라 하고, k개의 작업을 동시에 활성화한다고 가정하면, 각 작업에는 평균 C/k의 추론 자원이 할당됩니다. C/k가 단일 작업을 완료하는 데 필요한 최소 임계값 아래로 떨어지면, 어느 것도 완성되지 않습니다. 위가 한 개인데 만두 열 개를 한꺼번에 욱여넣으면 다 소화되지 않고, 열 개 모두 체하게 됩니다.
+
+Claude Code의 실제 동작이 이를 잘 보여줍니다. "사용자 등록 기능을 추가해 줘"라고 요청하면 다음과 같이 진행될 수 있습니다:
+
+1. User 모델 생성
+2. 등록 라우트 작성
+3. 이메일 인증이 필요하다는 것을 알아채고 메일 서비스 추가
+4. 비밀번호 해싱이 필요하다는 것을 확인하고 bcrypt 도입
+5. 오류 처리가 일관성이 없다는 것을 발견하고 글로벌 오류 미들웨어 리팩터링
+6. 테스트 파일 구조가 지저분하다는 것을 보고 디렉터리 재구성
+
+여섯 단계 후, 하나도 완성되지 않았습니다. 엔드투엔드 검증(verification)은 없고, 미완성 코드 간의 복잡한 결합만 남으며, 다음에 이어받을 세션은 완전히 길을 잃습니다. 마치 여섯 가지 요리를 동시에 하는 사람처럼 — 모든 요리가 냄비 안에 있지만 접시에 담긴 것은 하나도 없습니다. 다 타버립니다.
+
+Anthropic의 실험 데이터가 이를 직접 뒷받침합니다: "작은 다음 단계" 전략(WIP=1에 해당)을 사용한 에이전트는 넓은 프롬프트를 사용한 에이전트보다 작업 완료율이 37% 높습니다. 더 흥미로운 점은, 에이전트가 생성한 코드 줄 수와 실제 기능 완료 수가 약한 음의 상관관계를 보인다는 것입니다 — 코드를 많이 작성할수록 완성된 기능은 적습니다. 데이터로 증명된 과욕(overreach)입니다.
+
+## WIP=1 워크플로우
+
+```mermaid
+flowchart LR
+ Queue["기능 대기열"] --> Pick["정확히 하나의 작업 선택"]
+ Pick --> Active["활성 항목 하나만 유지"]
+ Active --> Verify["엔드투엔드 검증 실행"]
+ Verify -->|통과| Commit["커밋하고 다음 작업 잠금 해제"]
+ Verify -->|실패| Active
+ Commit --> Queue
+```
+
+```mermaid
+flowchart TB
+ Budget["사용 가능한 추론 예산 = C"] --> One["WIP = 1<br/>작업당 C / 1"]
+ Budget --> Many["WIP = 5<br/>작업당 C / 5"]
+
+ One --> Finish["하나의 기능이 통과 상태에 도달"]
+ Many --> Partial["다섯 개의 부분 구현"]
+ Partial --> VCR["낮은 검증 완료율(VCR)<br/>다음 세션에서 높은 재작업 비율"]
+```
+
+## 핵심 개념
+
+- **과욕(Overreach)**: 에이전트가 단일 세션에서 최적보다 많은 작업을 활성화하는 것입니다. 정량화 가능합니다 — 5개 기능을 작업했지만 엔드투엔드를 통과한 것이 0개이면 과욕입니다.
+- **미완성(Under-finish)**: 활성화된 전체 작업 중 엔드투엔드 검증을 통과한 작업의 비율이 임계값 아래로 떨어지는 상태입니다. 코드는 작성했지만 테스트가 통과하지 않으면 미완성입니다.
+- **WIP 제한(Work-in-Progress Limit)**: 칸반(Kanban) 방법론에서 온 개념입니다. 핵심 아이디어: 동시에 진행 중인 작업 수를 제한합니다. 에이전트에게는 WIP=1이 가장 안전한 기본값입니다 — 하나를 끝낸 후 다음을 시작합니다. 뷔페처럼 — 접시를 쌓지 말고, 한 접시를 다 먹은 후 다음 접시를 가져오십시오. 칸반은 제조업에서 비롯된 작업 흐름 관리 방법론으로, 재공품(WIP) 제한을 통해 흐름 효율을 극대화하는 것이 핵심 원리입니다.
+- **완료 증거(Completion Evidence)**: 작업이 "진행 중"에서 "완료"로 이동하기 위해 만족해야 하는 검증 가능한 조건입니다. 이것 없이는 에이전트가 "코드가 멀쩡해 보인다"를 "동작이 테스트를 통과했다"로 대체합니다.
+- **범위 표면(Scope Surface)**: 각 노드가 작업 단위이고 엣지가 의존성인 DAG 구조입니다. 상태는 네 가지로 제한됩니다: not_started, active, blocked, passing.
+- **완료 압력(Completion Pressure)**: 해네스가 WIP 제한과 완료 증거 요구사항을 통해 가하는 제약력으로, 에이전트가 새 작업을 시작하기 전에 현재 작업을 마무리하도록 강제합니다.
+
+## 과욕과 미완성은 공생 관계입니다
+
+두 문제는 독립적이지 않습니다 — 서로를 증폭시킵니다. 과욕은 주의력을 희석시키고, 희석된 주의력은 미완성을 야기하며, 남겨진 반완성 코드는 시스템 복잡도를 높이고, 이는 다음 작업에서 더 큰 과욕을 불러옵니다. 악순환입니다.
+
+칸반 용어로: 리틀의 법칙(Little's Law)은 L = lambda * W임을 알려줍니다. 재공품(WIP) L이 너무 높으면(동시에 너무 많은 것을 하면), 각 작업의 리드 타임 W가 불가피하게 늘어납니다. 에이전트에게 이는 각 기능이 시작에서 검증된 완료까지 더 오래 걸리고 실패 확률이 커짐을 의미합니다.
+
+이것은 인간 세계에서도 오래된 문제입니다 — Steve McConnell은 『Rapid Development』에서 범위 크리프(scope creep)가 프로젝트 실패의 주요 원인이라고 기록했습니다. 하지만 사람은 적어도 "이 정도면 됐다"는 직관이 있습니다. 에이전트에게는 그것이 없습니다. 다음 아이디어를 생성하는 데 드는 추가 토큰 비용은 거의 0에 가깝습니다 — "여기도 고쳐볼게"라고 쓰는 것은 모델 입장에서 거의 부담이 없지만, 모든 추가 수정은 에이전트의 주의력을 희석시킵니다. 한 접시 추가 비용이 거의 0인 뷔페에서도 위장은 여전히 한 개뿐인 것과 같습니다.
+
+## 올바른 방법
+
+### 1. WIP=1 강제 적용
+
+가장 직접적이고 효과적인 방법입니다. 해네스에서 에이전트에게 명시적으로 지시하십시오: **어떤 시점에도 하나의 작업만 "active" 상태일 수 있습니다.** Claude Code의 CLAUDE.md 또는 Codex의 AGENTS.md에 다음과 같이 작성하십시오:
+
+```
+## 작업 규칙
+- 한 번에 하나의 기능만 작업합니다
+- 현재 기능이 엔드투엔드 검증을 통과한 후에만 다음 기능을 시작합니다
+- 기능 A를 구현하는 동안 기능 B도 "리팩터링"하지 않습니다
+```
+
+뷔페에서 먹는 것처럼 — 한 번에 한 접시, 다 먹은 후 다시 가져옵니다.
+
+### 2. 모든 작업에 명시적인 완료 증거 정의
+
+완료는 "코드가 작성됨"이 아니라 "동작 검증이 통과됨"입니다. 기능 목록(feature list)의 모든 항목에는 검증 명령이 필요합니다:
+
+```
+F01: 사용자 등록
+ 검증: curl -X POST /api/register -d '{"email":"[email protected]","password":"123456"}' | jq .status == 201
+ 상태: passing
+```
+
+### 3. 범위 표면 외부화
+
+기계 판독 가능한 파일(JSON 또는 Markdown)을 사용하여 모든 작업 상태를 기록하십시오. 새로운 세션은 이 파일을 읽고 즉시 알 수 있습니다: 어떤 작업이 활성 상태인가? 어떤 동작이 완료로 간주되는가? 어떤 검증이 통과했는가?
+
+### 4. 검증 완료율(VCR) 모니터링
+
+해네스는 VCR(Verified Completion Rate) = 검증된 작업 / 활성화된 작업을 지속적으로 추적해야 합니다. VCR < 1.0일 때 새 작업 활성화를 차단합니다.
+
+## 실제 사례
+
+8개의 기능을 가진 REST API 프로젝트, 두 가지 전략 비교:
+
+**뷔페 모드(제약 없음)**: 에이전트가 세션 1에서 5개의 기능을 동시에 활성화합니다. 12개 파일에 걸쳐 ~800줄을 생성합니다. 엔드투엔드 테스트 통과율: 20% — 사용자 등록만 작동합니다. 나머지 4개 기능: 데이터베이스 스키마는 생성되었지만 유효성 검사 로직이 없고, 라우트는 정의되었지만 잘못된 응답 형식을 반환합니다. 마치 여섯 가지 요리를 동시에 하다가 하나만 겨우 먹을 수 있는 것처럼. 세션 3 종료 시 8개 기능 중 3개만 완성됩니다.
+
+**단일 접시 모드(WIP=1)**: 에이전트가 세션 1에서 사용자 등록에만 집중합니다. 4개 파일에 ~200줄을 생성합니다. 엔드투엔드 테스트: 100% 통과. 검증된 클린 구현을 커밋합니다. 세션 4 종료 시 8개 기능 중 7개 완성(나머지 1개는 외부 의존성으로 차단됨).
+
+결과: 총 코드는 적지만(800 vs 1200줄) 더 효과적인 코드. 완료율: 87.5% vs 37.5%. 한 번에 한 입씩 먹으면, 실제로 더 많이 먹을 수 있습니다.
+
+## 핵심 요점
+
+- **WIP=1은 에이전트 해네스의 기본 안전 설정입니다** — 하나를 완료한 후 다음을 시작하십시오. 병렬화하려 하지 마십시오. 한 입에 살찔 수 없습니다.
+- **완료 증거는 실행 가능해야 합니다** — "코드가 멀쩡해 보인다"는 해당되지 않습니다. "curl이 201을 반환한다"가 해당됩니다.
+- **범위 표면은 파일로 외부화되어야 합니다** — 대화에서만 언급하는 것이 아니라, 저장소의 기계 판독 가능한 형식으로 기록되어야 합니다.
+- **과욕과 미완성은 공생 관계입니다** — 하나를 해결하면 다른 하나도 해결됩니다.
+- **"적게 하되 끝내는 것"이 항상 "많이 하되 반만 남기는 것"보다 낫습니다** — 에이전트의 코드 줄 수와 기능 완료율은 음의 상관관계를 보입니다. 품질이 항상 양을 이깁니다.
+
+## 더 읽을거리
+
+- [Effective harnesses for long-running agents - Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — Anthropic 엔지니어링 블로그, "작은 다음 단계" 전략에 대한 상세한 논의
+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — OpenAI의 해네스 엔지니어링에 대한 포괄적인 다룸
+- [Kanban: Successful Evolutionary Change - David Anderson](https://www.goodreads.com/book/show/1070822.Kanban) — WIP 제한에 관한 고전 자료
+- [Rapid Development - Steve McConnell](https://www.goodreads.com/book/show/125171.Rapid_Development) — 범위 크리프가 프로젝트 실패의 주요 원인이라는 실증적 데이터
+
+## 연습 문제
+
+1. **작업 원자화**: 넓은 요구사항(예: "사용자 관리 시스템 구현")을 골라 최소 5개의 원자적 작업 단위로 분해하십시오. 각 단위에 대해 다음을 명시하십시오: (a) 단일 동작 설명, (b) 실행 가능한 검증 명령, (c) 의존성. 분해가 WIP=1 제약을 만족하는지 확인하십시오.
+
+2. **비교 실험**: 동일한 프로젝트를 두 번 실행하십시오 — 한 번은 제약 없이, 한 번은 WIP=1을 강제 적용하여. 비교하십시오: 검증 완료율, 총 코드 줄 수, 유효 코드 비율.
+
+3. **완료 증거 감사**: 최근 에이전트 실행 결과를 검토하고, 각 코드 변경 사항을 "완료된 동작", "미완성 동작", "스캐폴딩"으로 분류하십시오. 각 미완성 동작에 누락된 검증 명령을 추가하십시오.
diff --git a/docs/ko/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md b/docs/ko/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md
new file mode 100644
index 0000000..c47a003
--- /dev/null
+++ b/docs/ko/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md
@@ -0,0 +1,8 @@
+# 강의 08 코드 예제
+
+이 폴더는 다음 예제들을 위한 공간입니다:
+
+- 패스 상태 게이팅(pass-state gating)
+- 엔드투엔드 검증(end-to-end verification)
+- 약한 완료 기준 vs 강한 완료 기준
+- 평가자 루프(evaluator-loop) 예제
diff --git a/docs/ko/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md b/docs/ko/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md
new file mode 100644
index 0000000..954f025
--- /dev/null
+++ b/docs/ko/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md
@@ -0,0 +1,8 @@
+# 패스 게이트 정책(Pass Gate Policy)
+
+기능이 `passes: false`에서 `passes: true`로 이동하려면 다음 조건을 모두 만족해야 합니다:
+
+- 예상된 워크플로우가 실행(exercise)되었을 것
+- 성공의 증거가 기록되었을 것
+- 테스트된 경로에 차단하는 오류가 없을 것
+- 구현이 앱을 손상되거나 모호한 상태로 두지 않을 것
diff --git a/docs/ko/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/ko/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
new file mode 100644
index 0000000..b2a67f7
--- /dev/null
+++ b/docs/ko/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -0,0 +1,137 @@
+[中文版本 →](../../../zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/)
+
+> 코드 예제: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/)
+> 실습 프로젝트: [프로젝트 04. 런타임 피드백과 범위 제어](./../../projects/project-04-incremental-indexing/index.md)
+
+# 강의 08. 기능 목록으로 에이전트의 행동을 제약하십시오
+
+에이전트에게 전자상거래 사이트를 구축하라고 요청합니다. 완성 후 에이전트는 "완료"라고 말합니다. 코드를 살펴보니 — 사용자 인증은 작동하지만 장바구니의 결제 버튼은 아무것도 하지 않고, 결제 흐름은 전혀 연결되어 있지 않습니다. 문제는: "완료"가 무엇을 의미하는지 전혀 알려주지 않았기 때문에, 에이전트는 자신만의 기준을 사용했습니다 — "코드를 많이 작성했고 꽤 완성된 것처럼 보인다."
+
+기능 목록(feature list)은 많은 사람들의 눈에 그저 메모처럼 보입니다 — 잊지 않으려고 적어두고 나서 옆으로 치워두는 것. 하지만 해네스(harness) 세계에서 기능 목록은 인간을 위한 메모가 아닙니다 — 전체 해네스의 근간(backbone)입니다. 스케줄러(scheduler)는 이것을 바탕으로 작업을 선택하고, 검증기(verifier)는 이것을 바탕으로 완료를 판단하며, 핸드오프(handoff) 보고기는 이것을 바탕으로 요약본을 생성합니다. 근간이 부러지면 온 몸이 마비됩니다.
+
+Anthropic과 OpenAI 모두 강조합니다: **산출물(artifact)은 외부화되어야 합니다.** 기능 상태는 구조화되지 않은 대화 텍스트가 아니라, 저장소의 기계 판독 가능한 파일에 존재해야 합니다.
+
+## 에이전트는 "완료"의 의미를 모릅니다
+
+Claude Code도 Codex도 "완료"가 무엇을 의미하는지 자동으로 알지 못합니다. "장바구니 기능을 추가해 줘"라고 하면, 모델의 해석은 "Cart 컴포넌트와 addToCart 메서드를 작성하는 것"일 수 있습니다. 하지만 당신이 의미한 것은 "사용자가 상품을 탐색하고, 장바구니에 추가하고, 결제를 완료할 수 있는 엔드투엔드 흐름"이었습니다. 이 이해의 간극은 기능 목록 없이는 지속됩니다. 에이전트는 자신만의 암묵적인 기준을 사용합니다 — 보통 "코드에 명백한 문법 오류가 없다"입니다. 당신이 필요한 것은 엔드투엔드 동작 검증입니다. 친구에게 과일을 사달라고 하면서 "과일 좀 사와"라고만 했는데 레몬을 가져오는 것처럼. 친구의 과일과 당신의 과일은 같은 과일이 아닙니다.
+
+다음과 같은 일반적인 진행 메모를 살펴보십시오:
+
+```
+사용자 인증 완료, 장바구니 거의 완료, 결제는 아직 필요
+```
+새로운 에이전트 세션이 이 메모에서 다음 질문들에 답할 수 있을까요? "거의 완료"가 무엇을 의미하는지? 장바구니가 통과한 테스트는 무엇인지? 결제를 막는 것이 무엇인지? 모든 답은 "아무도 모른다"입니다. 의사에게 "배가 아픈데, 요즘엔 괜찮아요"라고 하는 것과 같습니다 — 어떤 약을 처방할 수 있을까요?
+
+결과: 새 세션이 프로젝트 상태를 추론하는 데 20분을 소비하고, 이미 완료된 기능을 재구현할 수도 있습니다. Anthropic의 엔지니어링 데이터에 따르면 좋은 진행 기록은 세션 시작 진단 시간을 60-80% 줄입니다.
+
+## 기능 상태 기계
+
+```mermaid
+flowchart LR
+ Feature["하나의 기능 행"] --> Behavior["동작 설명<br/>예: POST /cart/items가 201 반환"]
+ Feature --> Check["검증 명령<br/>실행할 정확한 확인 방법"]
+ Feature --> State["상태<br/>not_started / active / blocked / passing"]
+
+ Behavior --> Complete["세 필드가 모두 있어야만<br/>기능 행이 사용 가능"]
+ Check --> Complete
+ State --> Complete
+```
+
+```mermaid
+flowchart LR
+ List["feature_list.json / features.md"] --> Scheduler["다음 not_started 항목 선택"]
+ Scheduler --> Agent["에이전트가 해당 항목 하나 작업"]
+ Agent --> Verifier["해당 항목의 검증 명령 실행"]
+ Verifier -->|통과| Passing["passing으로 표시하고<br/>증거 기록"]
+ Verifier -->|실패| Active["active 유지"]
+ Verifier -->|의존성 문제| Blocked["blocked로 표시"]
+ Passing --> Handoff["핸드오프 메모와<br/>현재 진행상황 업데이트"]
+ Active --> Agent
+```
+
+## 핵심 개념
+
+- **기능 목록은 해네스 프리미티브(primitive)입니다**: "선택적 계획 도구"가 아니라, 다른 모든 해네스 구성 요소가 의존하는 기반 데이터 구조입니다. 데이터베이스 테이블 구조처럼 — "기본 키는 건너뛰자"고 말할 수 없습니다. "프리미티브"란 시스템에서 더 이상 분해할 수 없는 기본 구성 요소를 의미하며, 다른 모든 추상화가 이 위에 구축됩니다.
+- **삼중 구조**: 각 기능 항목은 `(동작 설명, 검증 명령, 현재 상태)` 삼중 구조입니다. 어느 한 요소가 빠지면 항목이 불완전합니다.
+- **상태 기계 모델**: 각 기능 항목은 네 가지 상태를 가집니다 — `not_started`, `active`, `blocked`, `passing`. 상태 전환은 에이전트가 자유롭게 변경하는 것이 아니라 해네스가 제어합니다.
+- **패스 상태 게이팅(Pass-state gating)**: 기능이 `active`에서 `passing`으로 이동하는 유일한 방법은 검증 명령이 성공적으로 실행되는 것입니다. 이것은 되돌릴 수 없습니다 — 한 번 `passing`이 되면 되돌아갈 수 없습니다. 시험에 합격하면 합격한 것이고, 점수를 소급하여 변경할 수 없는 것처럼요.
+- **단일 진실 원천(Single source of truth)**: "무엇을 해야 하는가"에 관한 모든 정보는 하나의 기능 목록에서 파생되어야 합니다. 기능 목록과 대화 기록 간에 모순이 없어야 합니다.
+- **역압력(Back-pressure)**: 아직 통과하지 못한 기능의 수는 해네스가 에이전트에게 가하는 압력입니다. 압력이 0이면 = 프로젝트 완료.
+
+## 기능 목록이 "프리미티브"여야 하는 이유
+
+문서는 인간이 읽기 위한 것이고, 프리미티브는 시스템이 실행하기 위한 것입니다. 문서는 무시될 수 있지만, 프리미티브는 우회될 수 없습니다.
+
+데이터베이스 트리거 제약과 애플리케이션 레이어 검사를 생각해 보십시오: 전자는 데이터베이스 엔진이 강제하며, 어떤 SQL도 건너뛸 수 없습니다. 후자는 애플리케이션 코드의 정확성에 의존하며 우연히 우회될 수 있습니다. 해네스 프리미티브로서의 기능 목록은 구체적으로 네 가지 해네스 구성 요소를 담당합니다:
+
+1. **스케줄러(Scheduler)**: 상태를 읽고, 다음 `not_started` 기능을 선택합니다. 공장 생산 계획 시스템처럼요.
+2. **검증기(Verifier)**: 검증 명령을 실행하고, 상태 전환을 허용할지 결정합니다. 품질 검사처럼요.
+3. **핸드오프 보고기(Handoff reporter)**: 기능 목록에서 자동으로 세션 핸드오프 요약을 생성합니다. 자동 교대 근무 보고서처럼요.
+4. **진행 추적기(Progress tracker)**: 상태 분포를 집계하고, 프로젝트 건강 지표를 제공합니다. 대시보드처럼요.
+
+## 올바른 방법
+
+### 1. 최소한의 기능 목록 형식 정의
+
+복잡한 시스템이 필요하지 않습니다 — 구조화된 Markdown 또는 JSON 파일이면 충분합니다. 핵심은 모든 항목이 삼중 구조를 가져야 한다는 것입니다:
+
+```json
+{
+ "id": "F03",
+ "behavior": "POST /cart/items with {product_id, quantity} returns 201",
+ "verification": "curl -X POST http://localhost:3000/api/cart/items -H 'Content-Type: application/json' -d '{\"product_id\":1,\"quantity\":2}' | jq .status == 201",
+ "state": "passing",
+ "evidence": "commit abc123, test output log"
+}
+```
+
+### 2. 해네스가 상태 전환을 제어하도록 하기
+
+에이전트는 기능의 상태를 `passing`으로 직접 변경할 수 없습니다. 검증 요청만 제출할 수 있으며, 해네스가 검증 명령을 실행하고 전환을 허용할지 결정합니다. 이것이 "패스 상태 게이팅"입니다.
+
+### 3. CLAUDE.md에 규칙 작성
+
+```
+## 기능 목록 규칙
+- 기능 목록 파일: /docs/features.md
+- 한 번에 하나의 기능만 활성화
+- passing으로 표시하기 전에 검증 명령이 통과해야 함
+- 기능 목록 상태를 직접 수정하지 마십시오 — 검증 스크립트가 자동으로 업데이트합니다
+```
+
+### 4. 세분화 수준 조정
+
+각 기능 항목은 "하나의 세션 내에서 완료 가능"한 범위여야 합니다. 너무 넓으면 완료되지 않고, 너무 좁으면 관리 오버헤드가 늘어납니다. "사용자가 장바구니에 항목을 추가할 수 있다"는 적절한 세분화입니다. "장바구니 구현"은 너무 넓습니다. "Cart 모델에 name 필드 생성"은 너무 좁습니다. 스테이크 자르는 것처럼 — 통째로도 아니고, 간 고기도 아닌 적절한 한 입 크기.
+
+## 실제 사례
+
+10개의 기능을 가진 전자상거래 플랫폼. 두 가지 추적 방법 비교:
+
+**메모 모드**: 에이전트가 구조화되지 않은 메모를 사용합니다. 3개의 세션 후 메모는 "사용자 인증과 상품 목록은 완료, 장바구니는 거의 완료지만 버그 있음, 결제는 시작 안 됨"이 됩니다. 새 세션은 상태를 추론하는 데 20분이 필요하고, 결국 완료된 기능을 재구현합니다. 장보기 목록에 "우유, 빵, 그 물건"이라고 적혀 있으면 — 마트에서도 여전히 무엇을 사야 할지 모르는 것처럼.
+
+**근간 모드**: 모든 기능이 명확한 상태와 검증 명령을 가집니다. 새 세션은 기능 목록을 읽고 3분 만에 알 수 있습니다: F01-F05는 `passing`, F06은 `active`, F07-F10은 `not_started`. F06에서 직접 이어받고, 재작업 없이 진행합니다.
+
+정량화된 결과: 구조화된 기능 목록을 사용하는 프로젝트는 자유 형식 추적에 비해 기능 완료율이 45% 높으며, 중복 구현이 전혀 없습니다.
+
+## 핵심 요점
+
+- **기능 목록은 해네스의 근간입니다**, 인간을 위한 메모가 아닙니다. 스케줄러, 검증기, 핸드오프 보고기 모두 이에 의존합니다.
+- **모든 기능 항목은 삼중 구조를 가져야 합니다**: 동작 설명 + 검증 명령 + 현재 상태. 하나의 요소가 빠지면 불완전합니다 — 다리 하나 없는 세발 의자처럼.
+- **상태 전환은 해네스가 제어합니다** — 에이전트는 혼자서 상태를 변경할 수 없습니다. 검증 통과 = 유일한 업그레이드 경로.
+- **기능 목록은 프로젝트의 단일 진실 원천입니다** — "무엇을 해야 하는가"에 관한 모든 정보는 하나의 목록에서 파생됩니다.
+- **세분화 수준을 "하나의 세션 내에서 완료 가능"으로 조정하십시오.**
+
+## 더 읽을거리
+
+- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents) — 기능 목록을 에이전트 범위 제어를 위한 "핵심 데이터 구조"로 명시적으로 식별
+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — "산출물 외부화" 원칙 강조
+- [Design by Contract - Bertrand Meyer](https://www.goodreads.com/book/show/130439.Object_Oriented_Software_Construction) — 계약 설계 원칙, 기능 목록의 이론적 기반
+- [How Google Tests Software](https://www.goodreads.com/book/show/13563030-how-google-tests-software) — 테스트 피라미드와 동작 명세 엔지니어링 실천
+
+## 연습 문제
+
+1. **기능 목록 설계**: 최소한의 기능 목록 JSON 스키마를 정의하십시오. 포함 항목: id, 동작 설명, 검증 명령, 현재 상태, 증거 참조. 이를 사용하여 5개의 기능을 가진 실제 프로젝트를 설명하십시오.
+
+2. **검증 엄격성 비교**: 3개의 기능을 선택하고 "느슨한" 검증(예: "코드에 문법 오류가 없음")과 "엄격한" 검증(예: "엔드투엔드 테스트 통과") 모두를 설계하십시오. 각 방법에서의 위양성 비율을 비교하십시오.
+
+3. **단일 진실 원천 원칙 감사**: 기존 에이전트 프로젝트를 검토하고 기능 목록과 모순되는 범위 정보(대화 내 암묵적 요구사항, 코드의 TODO 댓글 등)를 찾아보십시오. 모든 정보를 기능 목록으로 통합하는 계획을 설계하십시오.
diff --git a/docs/ko/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md b/docs/ko/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md
new file mode 100644
index 0000000..68984e5
--- /dev/null
+++ b/docs/ko/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md
@@ -0,0 +1,6 @@
+# 클린 상태 체크리스트(Clean State Checklist)
+
+- 수동 수리 없이 앱이 시작됩니다
+- 현재 진행 상황이 기록되어 있습니다
+- 문서화되지 않은 반완성 가져오기(import) 또는 인덱싱 단계가 남아 있지 않습니다
+- 다음 에이전트(agent)가 표준 시작 및 검증(verification) 경로를 즉시 실행할 수 있습니다
diff --git a/docs/ko/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md b/docs/ko/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md
new file mode 100644
index 0000000..c48c926
--- /dev/null
+++ b/docs/ko/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md
@@ -0,0 +1,8 @@
+# 강의 09 코드 예제
+
+이 폴더는 다음 예제들을 위한 공간입니다:
+
+- 피드백으로서의 로그(logs as feedback)
+- 런타임 상태 가시성(runtime-state visibility)
+- 클린 상태(clean state) 확인
+- 복구(recovery) 예제
diff --git a/docs/ko/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/ko/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
new file mode 100644
index 0000000..b80d072
--- /dev/null
+++ b/docs/ko/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -0,0 +1,145 @@
+[中文版本 →](../../../zh/lectures/lecture-09-why-agents-declare-victory-too-early/)
+
+> 이 강의의 코드 예제: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/code/)
+> 실습 프로젝트: [프로젝트 05. 에이전트가 자신의 작업을 스스로 검증하게 하기](./../../projects/project-05-grounded-qa-verification/index.md)
+
+# 강의 9. 에이전트가 너무 일찍 완료를 선언하지 못하도록 방지하기
+
+에이전트에게 "비밀번호 재설정" 기능을 구현하라고 요청합니다. 에이전트는 데이터베이스 스키마를 수정하고, API 엔드포인트를 작성하고, 이메일 템플릿을 추가하고, 단위 테스트를 실행합니다(모두 통과). 그런 다음 자신 있게 "완료되었습니다"라고 알립니다. 실제로 실행해 보면 — 비밀번호 재설정 링크를 보낼 수 없고(이메일 서비스 설정 누락), 데이터베이스 마이그레이션이 중간에 실패하며(스키마 불일치), 엔드투엔드 흐름은 단 한 번도 실행되지 않았습니다.
+
+이 느낌이 낯설지 않을 것입니다 — 시험지를 가득 채우고 자신 있게 가장 먼저 제출했는데, 성적이 나왔을 때 낙제하는 경우와 같습니다. 시험지가 가득 찼다고 해서 답이 맞는 것은 아닙니다.
+
+이것은 단발성 사건이 아닙니다. 2017년 Guo et al.의 ICML 고전 논문이 증명했습니다: **현대 신경망은 체계적으로 과도한 자신감을 보입니다** — 모델이 보고하는 신뢰도는 실제 정확도보다 유의미하게 높습니다. AI 코딩 에이전트(agent)에게도 동일하게 적용됩니다: 에이전트는 완료되었다고 "느끼지만", 실제로는 아직 한참 멀었습니다. 여러분의 해네스(harness)는 에이전트의 "느낌"을 외부화된 실행 기반 검증(verification)으로 대체해야 합니다.
+
+## 미끄러운 경사면
+
+조기 완료 선언은 거의 항상 같은 패턴을 따릅니다: 코드가 괜찮아 보입니다 — 문법이 올바르고, 로직이 합리적으로 보이며, 정적 분석에서 명백한 오류가 없습니다. 하지만 해네스가 포괄적인 실행 검증을 강제하지 않기 때문에, 에이전트는 실제 실행을 건너뛰거나 부분적인 테스트만 수행합니다. 단위 테스트는 실행하지만 통합 테스트는 건너뜁니다. 테스트는 실행하지만 커버리지를 확인하지 않습니다. 결국 "코드가 멀쩡해 보인다"가 "기능이 완료되었다"의 증거로 사용됩니다. 그리고 시험지가 제출됩니다.
+
+정보는 모든 단계에서 손실됩니다. 작업 명세에서 코드 구현을 거쳐 런타임 동작에 이르기까지, 모든 변환은 편향을 유발할 수 있으며, 건너뛴 모든 검증은 정보 비대칭을 악화시킵니다.
+
+## 3단계 종료 검사
+
+```mermaid
+flowchart LR
+ Claim["에이전트: 완료됨"] --> L1["먼저 실행<br/>lint / typecheck"]
+ L1 --> L2["다음으로 실행<br/>테스트 및 시작 확인"]
+ L2 --> L3["마지막으로 실행<br/>완전한 사용자 흐름"]
+ L3 --> Done["세 가지 모두 통과해야 완료"]
+```
+
+```mermaid
+flowchart LR
+ A["코드가 작성됨<br/>단위 테스트 통과"] --> B["하지만 앱이 실제로 시작되지 않음<br/>전체 흐름이 실행된 적 없음"]
+ B --> C["설정, DB, 외부 서비스 문제가<br/>모두 숨겨져 있음"]
+ C --> D["그래서 에이전트가 너무 일찍 완료 선언"]
+```
+
+## 핵심 개념
+
+- **조기 완료 선언(Premature Completion Declaration)**: 에이전트가 작업이 완료되었다고 주장하지만, 아직 충족되지 않은 정확성 명세가 존재하는 상태입니다. 핵심 문제: 에이전트는 코드 수준의 로컬 신뢰도를 기반으로 판단하지만, 시스템 수준의 정확성은 전역적 검증을 필요로 합니다.
+- **신뢰도 보정 편향(Confidence Calibration Bias)**: 에이전트가 자체 보고한 완료 신뢰도와 실제 완료 품질 사이의 체계적인 간극입니다. 복잡한 다중 파일 작업의 경우 이 편향은 유의미하게 양(+)입니다 — 에이전트는 실제 성과보다 항상 더 자신 있어합니다. 시험 후 항상 점수를 과대 평가하는 학생처럼요.
+- **종료 기준(Termination Criteria)**: 해네스에서 정의된 명확하고 실행 가능한 판단 조건의 집합입니다. 에이전트는 완료를 선언하기 전에 모든 조건을 만족해야 합니다. "완료"가 주관적 판단에서 객관적 결정으로 바뀝니다.
+- **검증-유효성 검사 이중 게이트(Verification-Validation Dual Gate)**: 첫 번째 검증 레이어는 "코드가 명세된 동작을 올바르게 구현했는가"를 확인하고, 두 번째 유효성 검사 레이어는 "시스템 수준의 동작이 엔드투엔드 요구사항을 충족하는가"를 확인합니다. 완료로 간주되려면 두 가지 모두 통과해야 합니다.
+- **런타임 피드백 신호(Runtime Feedback Signals)**: 프로그램 실행에서 나오는 로그, 프로세스 상태, 상태 확인. 해네스가 완료 품질을 판단하기 위한 객관적 근거입니다.
+- **완료 우선순위 제약(Completion Priority Constraint)**: 먼저 기능적 정확성을 검증하고, 그다음 성능을 다루고, 마지막으로 스타일을 다룹니다. 핵심 기능이 검증되기 전까지 리팩터링은 금지입니다.
+
+## 단위 테스트 통과 != 작업 완료
+
+이것이 가장 흔한 함정이자 가장 위험한 것입니다. 에이전트가 코드를 작성하고, 단위 테스트를 실행하고, 모두 통과했으며, "완료"라고 했습니다. 하지만 단위 테스트의 설계 철학 — 테스트 대상을 격리하고 의존성을 모킹(mocking)하는 것 — 이 바로 단위 테스트가 컴포넌트 간 문제를 감지할 수 없게 하는 이유입니다:
+
+**인터페이스 불일치**: 렌더 프로세스가 preload 스크립트에 전달하는 파일 경로는 상대 경로이지만, preload 스크립트는 절대 경로를 기대합니다. 각각의 단위 테스트는 모두 모킹을 사용했고 통과했습니다. 문제는 엔드투엔드 테스트 중에만 발견됩니다. 밴드의 모든 음악가가 각자 연습할 때는 완벽하지만, 함께 연주할 때 음이 맞지 않는다는 것을 깨닫는 것처럼.
+
+**상태 전파 오류**: 데이터베이스 마이그레이션이 테이블 스키마를 변경했지만, ORM 캐싱 레이어는 여전히 이전 스키마의 캐시 항목을 보유하고 있습니다. 단위 테스트는 매번 새로운 모킹 환경을 제공하므로 이 교차 레이어 상태 불일치가 드러나지 않습니다.
+
+**환경 의존성**: 코드는 테스트 환경(모든 것이 모킹됨)에서는 올바르게 동작하지만, 설정 차이, 네트워크 지연, 또는 서비스 불가용성으로 인해 실제 환경에서 실패합니다. 연습실에서는 완벽하게 노래하지만, 무대에서는 음향 장비 문제에 직면하는 것처럼.
+
+### "그 김에 리팩터링"은 완료 판단에 독입니다
+
+Claude Code에는 흔한 행동 패턴이 있습니다: 핵심 기능이 검증을 통과하기 전에 코드를 리팩터링하고, 성능을 최적화하고, 스타일을 개선하기 시작합니다. Knuth의 인용문 "조기 최적화는 만악의 근원"은 에이전트 시나리오에서 새로운 의미를 가집니다 — 리팩터링은 검증된 코드와 미검증 코드 사이의 경계를 변경하여, 이전에 암묵적으로 올바랐던 코드 경로를 잠재적으로 깨뜨릴 수 있습니다. 수학 서술형 문제를 다 풀기 전에 객관식 답안을 더 예쁘게 옮겨 적는 것과 같습니다 — 시간 낭비일 뿐만 아니라 잘못 옮길 수도 있습니다.
+
+### 자기 평가의 체계적 편향
+
+Anthropic은 2026년 연구에서 더 깊은 실패 패턴을 발견했습니다: **에이전트에게 자신의 작업을 평가하도록 요청하면, 인간 관찰자가 품질이 명백히 기준에 미달한다고 볼 때조차 체계적으로 지나치게 긍정적인 평가를 제공합니다.** 학생에게 자신의 시험을 채점하도록 하는 것과 같습니다 — 그들은 항상 자신의 답안에 특히 관대할 것입니다.
+
+이 문제는 주관적인 작업(예: 디자인 미학)에서 특히 심각합니다 — "레이아웃이 정교한가"는 판단의 문제이며, 에이전트는 신뢰할 수 있게 긍정적으로 치우칩니다. 심지어 검증 가능한 결과가 있는 작업에서도 에이전트의 성과는 잘못된 판단에 의해 방해받을 수 있습니다.
+
+해결책은 에이전트를 "더 객관적으로" 만드는 것이 아닙니다 — 생성과 평가를 담당하는 동일한 모델은 본질적으로 자신에게 관대한 경향이 있습니다. **해결책은 "작업자"와 "검사자"를 분리하는 것입니다.** 학생이 자신의 시험을 채점해서는 안 되는 것처럼 — 독립적인 채점자가 필요합니다.
+
+"까다롭게" 튜닝된 독립적인 평가 에이전트는 생성 에이전트가 스스로를 평가하는 것보다 훨씬 효과적입니다. Anthropic의 실험 데이터:
+
+| 아키텍처 | 실행 시간 | 비용 | 핵심 기능 작동 여부 |
+|----------|-----------|------|---------------------|
+| 단일 에이전트(bare run) | 20분 | $9 | 아니오(게임 개체가 입력에 반응 없음) |
+| 세 에이전트(planner + generator + evaluator) | 6시간 | $200 | 예(게임이 완전히 플레이 가능) |
+
+이것은 정확히 같은 모델(Opus 4.5)에 정확히 같은 프롬프트("2D 레트로 게임 에디터 구축")입니다. 유일한 차이점은 해네스입니다 — "bare 실행"에서 "플래너가 요구사항 확장 → 생성기가 기능별 구현 → 평가기가 Playwright를 사용하여 실제 클릭 테스트 수행"으로 변경된 것입니다.
+
+> 출처: [Anthropic: 장시간 애플리케이션 개발을 위한 해네스 설계](https://www.anthropic.com/engineering/harness-design-long-running-apps)
+
+## 조기 제출을 방지하는 방법
+
+### 1. 종료 판단 외부화
+
+완료 판단은 에이전트 자신이 내려서는 안 됩니다. 해네스는 런타임 신호를 입력으로 사용하여 독립적으로 종료 유효성 검사를 실행해야 하며, 에이전트의 신뢰도를 사용해서는 안 됩니다. `CLAUDE.md`에 다음과 같이 명확하게 작성하십시오:
+
+```
+## 완료의 정의
+- 기능 완료 = 엔드투엔드 검증 통과, "코드가 작성됨"이 아님
+- 필요한 검증 레벨:
+ 1. 단위 테스트 통과
+ 2. 통합 테스트 통과
+ 3. 엔드투엔드 흐름 검증 통과
+- 레벨 1이 실패하면 레벨 2로 진행하지 않습니다
+- 레벨 2가 실패하면 레벨 3으로 진행하지 않습니다
+```
+
+### 2. 3단계 종료 유효성 검사 구축
+
+- **레이어 1: 문법 및 정적 분석**. 비용이 가장 낮고 정보가 가장 적지만, 반드시 통과해야 합니다. 이것이 최소한의 확인입니다 — 다른 것을 보기 전에 철자를 올바르게 써야 합니다.
+- **레이어 2: 런타임 동작 검증**. 테스트 실행, 앱 시작 확인, 핵심 경로 유효성 검사. 이것이 완료의 핵심 증거입니다. 작성하는 것만으로는 충분하지 않습니다. 실행되어야 합니다.
+- **레이어 3: 시스템 수준 확인**. 엔드투엔드 테스트, 통합 유효성 검사, 사용자 시나리오 시뮬레이션. 조기 선언에 대한 최후의 방어선입니다. 실행하는 것만으로는 충분하지 않습니다. 올바르게 실행되어야 합니다.
+
+### 3. 에이전트를 위한 좋은 "빨간 펜 수정" 설계
+
+OpenAI는 Codex 실천 과정에서 특히 효과적인 패턴을 소개했습니다: **에이전트에 대한 오류 메시지에는 수정 지침이 포함되어야 합니다**. 게으른 채점자처럼 큰 빨간 X만 그리지 말고, 좋은 선생님처럼 "여기를 이렇게 바꿔야 합니다"라고 여백에 써주십시오. `"테스트 실패"`를 사용하지 말고, `"테스트 실패: POST /api/reset-password가 500을 반환했습니다. 환경 변수에 이메일 서비스 설정이 있는지 확인하십시오. 템플릿 파일은 templates/reset-email.html에 있어야 합니다."`를 사용하십시오. 이러한 구체적이고 실행 가능한 피드백은 에이전트가 인간의 개입 없이 스스로 수정할 수 있게 해줍니다.
+
+### 4. 런타임 신호 수집
+
+효과적인 런타임 신호에는 다음이 포함됩니다:
+- 애플리케이션이 성공적으로 시작되어 준비 상태에 도달했는가?
+- 핵심 기능 경로가 런타임에 성공적으로 실행되었는가?
+- 데이터베이스 쓰기, 파일 작업 및 기타 부작용이 올바른가?
+- 임시 리소스가 정리되었는가?
+
+## 실제 사례
+
+**작업**: 사용자 비밀번호 재설정 기능 구현. 데이터베이스 작업, 이메일 전송, API 엔드포인트 수정이 포함됩니다.
+
+**조기 제출 경로**: 에이전트가 데이터베이스 스키마를 수정하고, API 엔드포인트를 작성하고, 이메일 템플릿을 추가하고, 단위 테스트를 실행하고(통과), 완료를 선언합니다. 시험지가 가득 찼습니다.
+
+**실제 감점 항목**: (1) 엔드투엔드 흐름 미테스트 — 재설정 링크의 실제 전송 및 검증이 확인된 적 없음. (2) 데이터베이스 마이그레이션이 부분 실행 후 실패하여 스키마 불일치 발생. (3) 대상 환경에서 이메일 서비스 설정 누락.
+
+**해네스 개입**: 종료 유효성 검사 강제 실행 — (1) 전체 앱을 시작하여 재설정 엔드포인트 접근성 확인; (2) 전체 재설정 흐름 실행; (3) 데이터베이스 상태 일관성 검증. 모든 결함이 세션 내에서 발견되어, 이후 수정 비용의 5-10배를 절약했습니다. 독립적인 채점자가 실제 문제를 발견했습니다.
+
+## 핵심 요점
+
+- **에이전트는 체계적으로 과도한 자신감을 보입니다** — 신뢰도 보정 편향은 객관적 현실입니다. 시험지를 가득 채운다고 답이 맞는 것은 아닙니다.
+- **완료 판단은 외부화되어야 합니다** — 해네스가 독립적으로 검증하며, 에이전트의 "느낌"을 신뢰하지 마십시오. 학생이 자신의 시험을 채점할 수 없습니다.
+- **3단계 유효성 검사가 모두 필수입니다** — 문법 통과, 동작 통과, 시스템 통과, 단계별로 진행합니다.
+- **오류 메시지는 좋은 선생님의 빨간 펜 수정과 같아야 합니다** — 에이전트가 스스로 수정할 수 있도록 구체적인 수정 단계를 포함하십시오.
+- **핵심 기능이 검증되기 전에는 리팩터링하지 마십시오** — 완료 우선순위 제약이 조기 최적화를 방지하는 핵심입니다.
+
+## 더 읽을거리
+
+- [On Calibration of Modern Neural Networks - Guo et al.](https://arxiv.org/abs/1706.04599) — 현대 심층 신경망이 체계적으로 과도한 자신감을 보임을 증명
+- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents) — 완료 판단에서 런타임 증거의 중요한 역할
+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — 조기 완료 선언이 에이전트의 주요 실패 모드 중 하나
+- [The Art of Software Testing - Myers](https://www.goodreads.com/book/show/137543.The_Art_of_Software_Testing) — 테스트 방법 계층 구조와 효과성에 관한 고전 참고서
+
+## 연습 문제
+
+1. **종료 유효성 검사 함수 설계**: 데이터베이스 마이그레이션과 API 수정이 포함된 작업에 대한 완전한 종료 유효성 검사를 설계하십시오. 필요한 런타임 신호와 각 신호의 통과/실패 기준을 나열하십시오. 실제 작업에 실행하고 어떤 숨겨진 문제가 발견되는지 기록하십시오.
+
+2. **보정 편향 측정**: 10가지 다른 유형의 코딩 작업을 선택하고, 에이전트의 자체 보고 완료 신뢰도와 실제 완료 품질을 기록하십시오. 편향 값을 계산하고 작업 복잡성과의 관계를 분석하십시오.
+
+3. **다층 방어 실험**: 동일한 작업 세트에 세 가지 구성을 실행하십시오 — (a) 정적 분석만, (b) 단위 테스트 추가, (c) 완전한 3단계 유효성 검사. 조기 완료 선언의 비율과 발견되지 않은 결함의 수를 비교하십시오.
diff --git a/docs/ko/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md b/docs/ko/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md
new file mode 100644
index 0000000..44adc63
--- /dev/null
+++ b/docs/ko/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md
@@ -0,0 +1,6 @@
+# Electron 아키텍처 규칙
+
+- 렌더러 코드는 파일시스템에 직접 접근할 수 없습니다.
+- 프리로드(preload)는 렌더러와 Electron 메인 간의 유일한 브릿지입니다.
+- 검색 및 인덱싱 로직은 UI 컴포넌트가 아닌 서비스 모듈에 있어야 합니다.
+- 로깅은 구조화되어야 하며 서비스 경계에서 방출되어야 합니다.
diff --git a/docs/ko/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md b/docs/ko/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md
new file mode 100644
index 0000000..5f3f44e
--- /dev/null
+++ b/docs/ko/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md
@@ -0,0 +1,8 @@
+# 강의 10 코드
+
+이 폴더는 다음 항목의 예제에 사용합니다.
+
+- 아키텍처 제약(architecture constraints)
+- 구조적 테스트(structural tests)
+- 불변성 검사(taste invariants)
+- 수정 지향 린트 메시지(remediation-oriented lint messages)
diff --git a/docs/ko/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md b/docs/ko/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md
new file mode 100644
index 0000000..9e6c7a0
--- /dev/null
+++ b/docs/ko/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md
@@ -0,0 +1,10 @@
+# 예제: 리뷰 피드백을 규칙으로 전환하기
+
+반복되는 리뷰 코멘트:
+
+> 렌더러에서 파일시스템 유틸리티를 직접 호출하지 마세요. 프리로드 브릿지를 사용하세요.
+
+승격된 해네스 규칙:
+
+- 렌더러 코드에서 `fs` 사용을 방지하는 린트 또는 임포트 규칙 추가
+- 프리로드 경계를 설명하는 수정 텍스트 추가
diff --git a/docs/ko/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/ko/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
new file mode 100644
index 0000000..b101fd6
--- /dev/null
+++ b/docs/ko/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -0,0 +1,158 @@
+[English Version →](../../../en/lectures/lecture-10-why-end-to-end-testing-changes-results/)
+
+> 이 강의의 코드 예제: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/code/)
+> 실습 프로젝트: [Project 05. 에이전트가 자신의 작업을 스스로 검증하게 하기](./../../projects/project-05-grounded-qa-verification/index.md)
+
+# 강의 10. 엔드투엔드 테스트(end-to-end testing)만이 진정한 검증이다
+
+에이전트에게 Electron 앱에 파일 내보내기 기능을 추가해 달라고 합니다. 에이전트는 렌더 프로세스 컴포넌트, 프리로드 스크립트, 서비스 계층 로직을 작성합니다. 각 컴포넌트에 대한 단위 테스트(unit test)는 완벽하게 통과합니다. 에이전트는 "완료됐습니다"라고 말합니다. 실제로 내보내기 버튼을 클릭하면—파일 경로 형식이 잘못되어 있고, 진행 표시줄이 업데이트되지 않으며, 대용량 파일 내보내기 시 메모리 누수가 발생합니다. 다섯 개의 컴포넌트 경계 결함이 있었는데, 단위 테스트는 하나도 잡아내지 못한 것입니다.
+
+마치 합창 리허설에서 각 성부가 개별적으로 연습할 때는 완벽하게 들리지만, 함께 노래하면 소프라노가 베이스보다 반 박자 빠르고, 반주는 주 선율보다 반음 낮은 것과 같습니다. 각 파트는 개별적으로는 "정확"하지만, 전체적으로는 엇나갑니다.
+
+Google의 테스팅 피라미드(Testing Pyramid)는 이렇게 말합니다. 대량의 단위 테스트가 기반이지만, 거기서 멈추면 컴포넌트 간 상호작용 문제를 체계적으로 놓치게 됩니다. AI 코딩 에이전트(coding agent)에게는 이 문제가 더욱 심각합니다—에이전트는 가장 빠른 테스트만 실행하고 완료를 선언하는 경향이 있기 때문입니다. **엔드투엔드 테스트만이 시스템 수준의 결함이 존재하지 않음을 증명할 수 있습니다.**
+
+## 단위 테스트의 맹점
+
+단위 테스트의 설계 철학은 격리(isolation)입니다—의존성을 모킹(mocking)하고 테스트 대상 단위에만 집중하는 것입니다. 이 철학이 단위 테스트를 빠르고 정밀하게 만들지만, 동시에 체계적인 맹점을 만들어 냅니다. 합창 리허설에서 각 성부가 헤드폰을 끼고 연습하는 것과 같습니다—자신에게는 괜찮게 들리지만, 함께 모였을 때야 비로소 문제가 드러납니다.
+
+**인터페이스 불일치**: 렌더 프로세스가 프리로드 스크립트에 전달하는 파일 경로는 상대 경로이지만, 프리로드 스크립트는 절대 경로를 기대합니다. 각각의 단위 테스트는 모두 모킹을 사용해 통과했습니다. 엔드투엔드 흐름이 실행될 때야 비로소 문제가 발견됩니다—마치 두 성부가 개별적으로 연습하면서 괜찮다고 느끼다가, 앙상블에서 한쪽은 4/4박자로, 다른 쪽은 3/4박자로 노래하고 있다는 것을 알게 되는 것처럼.
+
+**상태 전파 오류(State Propagation Errors)**: 데이터베이스 마이그레이션이 테이블 스키마를 변경했지만, ORM 캐싱 계층은 여전히 이전 스키마에 대한 캐시 항목을 보유하고 있습니다. 단위 테스트는 매번 완전히 새로운 모킹 환경을 제공하므로, 이러한 계층 간 상태 불일치를 드러내지 않습니다. 노래 가사를 바꿨는데 누군가가 아직도 이전 버전으로 노래하는 것과 같습니다.
+
+**리소스 수명 주기 문제**: 파일 핸들, 데이터베이스 연결, 네트워크 소켓의 획득 및 해제는 여러 컴포넌트에 걸쳐 있습니다. 단위 테스트는 각 테스트를 위해 독립적인 리소스를 생성하고 소멸시키므로, 리소스 경합이나 누수를 드러내지 못합니다. 리허설 중에 각 성부가 마이크를 번갈아 사용하지만, 무대에서 모두 함께 올라갔을 때 마이크가 부족한 것과 같습니다.
+
+**환경 의존성**: 코드는 테스트 환경(모든 것이 모킹된 곳)에서는 올바르게 동작하지만, 설정 차이, 네트워크 지연, 또는 서비스 불가용성으로 인해 실제 환경에서는 실패합니다. 리허설실에서는 완벽하게 노래했지만, 야외 페스티벌에서 오디오 피드백과 바람 간섭을 만나는 것과 같습니다.
+
+## 엔드투엔드 테스트는 결과만 바꾸는 것이 아니라 행동을 바꾼다
+
+많은 사람들이 깨닫지 못하는 것이 있습니다. 에이전트가 자신의 작업이 엔드투엔드 테스트를 받게 된다는 것을 알면, 코딩 행동이 바뀐다는 점입니다.
+
+1. **컴포넌트 상호작용 고려**: 코드를 작성하면서 "이 인터페이스가 업스트림과 어떻게 연결되는가"를 생각하게 됩니다. 단순히 하나의 함수에만 집중하지 않습니다. 마치 결국 함께 노래하게 될 것을 알기에, 연습 중에도 다른 성부에 귀를 기울이는 것처럼.
+2. **아키텍처 경계 준수**: 아키텍처 제약이 있는 시스템에서 엔드투엔드 테스트는 에이전트가 경계 규칙을 준수하도록 강제합니다. 악보에 "여기서 크레셴도(crescendo)"라고 표시된 것처럼, 따라야 합니다.
+3. **오류 경로 처리**: 엔드투엔드 테스트는 보통 실패 시나리오를 포함하므로, 에이전트가 예외 처리를 고려하게 만듭니다. 리허설 중에 "마이크가 갑자기 꺼지면 어떻게 할까"를 시뮬레이션하여, 실제 상황에서 어떻게 대처할지 알게 되는 것처럼.
+
+## 테스팅 피라미드와 리뷰 피드백 승격
+
+```mermaid
+flowchart TB
+ subgraph Unit["단위 테스트는 격리된 부분만 검사합니다"]
+ U1["렌더러 테스트"]
+ U2["프리로드 테스트"]
+ U3["서비스 테스트"]
+ end
+
+ subgraph E2E["E2E는 실제 시스템을 통과합니다"]
+ R["렌더러 버튼 클릭"] --> P["프리로드 브릿지"]
+ P --> S["서비스 계층"]
+ S --> F["파일 시스템 / OS"]
+ F --> Result["실제 내보낸 파일"]
+ end
+```
+
+```mermaid
+flowchart LR
+ Review["리뷰 피드백:<br/>렌더러에서 fs를 직접 import할 수 없음"] --> Rule["직접 fs import 검사 추가"]
+ Rule --> Message["오류 메시지에 에이전트에게<br/>파일 접근을 프리로드로 이동하라고 알림"]
+ Message --> Harness["이 검사를 해네스에 추가"]
+ Harness --> Stronger["다음에는 즉시 실패하게 됨"]
+```
+
+Codex 엔지니어링 실천에서 OpenAI는 강조합니다. **에이전트를 위해 작성된 오류 메시지에는 수정 지침이 포함되어야 합니다.** `"렌더러에서 직접 파일시스템 접근"`이라고만 쓰지 말고, `"렌더러에서 직접 파일시스템 접근. 모든 파일 작업은 프리로드 브릿지를 통해야 합니다. 이 호출을 preload/file-ops.ts로 이동하고 window.api를 통해 호출하세요."`라고 써야 합니다. 이것이 아키텍처 규칙을 자동 수정 루프로 만듭니다. 지휘자가 단순히 "그거 틀렸어"라고 말하지 않고, "여기서 반 박자 빠르게 나왔어, 알토 리듬을 들어봐, 32마디에서 들어와"라고 말하는 것처럼.
+
+## 핵심 개념
+
+- **컴포넌트 경계 결함(Component Boundary Defects)**: 컴포넌트 A와 B가 각자의 단위 테스트를 통과하지만, 상호작용이 잘못된 동작을 만들어냅니다. 이것이 엔드투엔드 테스트가 가장 잘 잡아내는 문제 유형입니다—개별적으로는 정확하지만 함께하면 엇나가는 합창 성부처럼.
+- **테스팅 적합성 기울기(Testing Adequacy Gradient)**: 단위 테스트가 잡는 결함 <= 통합 테스트가 잡는 결함 <= 엔드투엔드 테스트가 잡는 결함. 각 계층이 올라갈수록 탐지 능력이 증가합니다.
+- **아키텍처 경계 강제 규칙(Architectural Boundary Enforcement Rules)**: 아키텍처 문서의 규칙(예: "렌더 프로세스는 파일 시스템에 직접 접근할 수 없다")을 실행 가능한 자동화된 검사로 전환합니다. "문서에 적힌"에서 "CI에서 실행되는"으로.
+- **리뷰 피드백 승격(Review Feedback Promotion)**: 반복되는 코드 리뷰 코멘트를 자동화된 테스트로 전환합니다. 반복되는 문제가 발견될 때마다 규칙을 추가하면, 해네스(harness)가 자동으로 강화됩니다. 지휘자가 흔한 리허설 실수를 워밍업 연습으로 바꾸는 것처럼—다음에 같은 실수를 하면, 연습 자체가 지휘자가 한 마디 할 필요 없이 그것을 드러냅니다.
+- **에이전트 지향 오류 메시지(Agent-Oriented Error Messages)**: 실패 메시지는 단순히 "무엇이 잘못됐는지"를 명시해서는 안 되고, 에이전트에게 정확히 어떻게 수정하는지도 알려줘야 합니다. 이것이 테스트 실패를 자기 수정 피드백 루프로 만듭니다.
+
+## 어떻게 해야 하는가
+
+### 0. 아키텍처 경계를 먼저 정의하고, 그 다음에 E2E 테스트를 작성하라
+
+엔드투엔드 테스트의 전제 조건은 명확한 시스템 경계입니다. 아키텍처가 스파게티 더미라면, 엔드투엔드 테스트는 그저 "이 스파게티가 실행된다"는 것만 증명할 뿐, 설계 의도가 위반된 곳을 알려주지 않습니다. 성부 분리조차 안 된 합창단처럼—아무리 리허설을 해도 좋아지지 않습니다.
+
+OpenAI의 경험: **에이전트가 생성한 코드베이스에는 아키텍처 제약이 팀이 커질 때 고려할 것이 아니라, 1일차에 확립되어야 하는 초기 전제 조건이어야 합니다.** 이유는 간단합니다—에이전트는 저장소의 기존 패턴을 복사하는 경향이 있고, 그 패턴이 고르지 않거나 차선이어도 마찬가지입니다. 아키텍처 제약 없이는 에이전트가 매 세션마다 더 많은 편차를 도입합니다.
+
+OpenAI는 "계층화된 도메인 아키텍처(Layered Domain Architecture)"를 채택했습니다—각 비즈니스 도메인은 고정된 계층으로 구분됩니다: Types → Config → Repo → Service → Runtime → UI. 의존성은 엄격하게 앞으로만 흐르고, 도메인 간 관심사는 명시적인 Provider 인터페이스를 통해 들어옵니다. 다른 의존성은 금지되며 커스텀 린팅(linting)으로 기계적으로 강제됩니다.
+
+핵심 원칙: **불변성을 강제하되, 구현을 세세하게 관리하지 않는다.** 예를 들어, "데이터는 경계에서 파싱된다"고 요구하되, 어떤 라이브러리를 사용할지는 지시하지 않습니다. 오류 메시지에는 수정 지침이 포함되어야 합니다—단순히 "위반"이라고 말하는 것이 아니라, 에이전트에게 정확히 어떻게 변경해야 하는지 알려줘야 합니다.
+
+> 출처: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
+
+### 1. 해네스에 엔드투엔드 계층이 반드시 포함되어야 한다
+
+검증 흐름에서 명시적으로 만드세요. 컴포넌트 간 변경이 포함된 작업의 경우, 엔드투엔드 테스트 통과가 완료의 전제 조건입니다.
+
+```
+## 검증 계층 구조
+- 레벨 1: 단위 테스트 (반드시 통과)
+- 레벨 2: 통합 테스트 (반드시 통과)
+- 레벨 3: 엔드투엔드 테스트 (크로스 컴포넌트 변경 시 반드시 통과)
+- 필수 레벨 건너뛰기 = 완료 아님
+```
+
+### 2. 아키텍처 규칙을 실행 가능한 검사로 전환하라
+
+모든 아키텍처 제약에는 대응하는 테스트 또는 린트 규칙이 있어야 합니다.
+
+```bash
+# 렌더 프로세스가 Node.js API를 직접 호출하는지 검사
+grep -r "require('fs')" src/renderer/ && exit 1 || echo "OK: no direct fs access in renderer"
+```
+
+### 3. 에이전트 지향 오류 메시지를 설계하라
+
+실패 메시지에는 세 가지 요소가 포함되어야 합니다. 무엇이 잘못됐는지, 왜인지, 어떻게 수정하는지.
+
+```
+ERROR: Found direct import of 'fs' in src/renderer/App.tsx:12
+WHY: Renderer process has no access to Node.js APIs for security
+FIX: Move file operations to src/preload/file-ops.ts and call via window.api.readFile()
+```
+
+### 4. 리뷰 피드백 승격 프로세스를 수립하라
+
+코드 리뷰 중에 새로운 유형의 에이전트 오류가 발견될 때마다, 자동화된 검사로 전환하세요. 한 달 후에는 해네스가 한 달 전보다 크게 강화되어 있을 것입니다. 합창의 리허설 노트처럼—매 리허설에서 발견된 문제를 기록해두면, 다음 리허설 전에 확인할 수 있습니다. 시간이 지날수록 흔한 오류는 줄어들고, 음악은 더 조화로워집니다.
+
+## 실제 사례
+
+**작업**: Electron 앱에 파일 내보내기 기능 구현. 렌더 프로세스 UI, 프리로드 스크립트 파일시스템 프록시, 서비스 계층 데이터 변환이 포함됩니다.
+
+**각 성부 개별 연습 (단위 테스트 통과)**: 렌더 컴포넌트 테스트 (통과, 파일 작업 모킹), 프리로드 스크립트 테스트 (통과, 파일시스템 모킹), 서비스 계층 테스트 (통과, 데이터 소스 모킹). 에이전트는 완료를 선언합니다.
+
+**함께 노래하기 (엔드투엔드 테스트로 드러난 결함)**:
+
+| 결함 | 설명 | 단위 테스트 | E2E |
+|------|------|-----------|-----|
+| 인터페이스 불일치 | 파일 경로 형식 불일치 | 놓침 | 잡음 |
+| 상태 전파 | 내보내기 진행 상황이 IPC를 통해 UI로 전달되지 않음 | 놓침 | 잡음 |
+| 리소스 누수 | 대용량 파일 내보내기 핸들 미해제 | 놓침 | 잡음 |
+| 권한 문제 | 패키징된 환경에서 권한 차이 | 놓침 | 잡음 |
+| 오류 전파 | 서비스 계층 예외가 UI 계층까지 도달하지 않음 | 놓침 | 잡음 |
+
+5개의 결함 모두 엔드투엔드 테스트로 잡혔고, 단위 테스트는 하나도 잡지 못했습니다. 비용은 테스트 시간이 2초에서 15초로 늘어난 것뿐이었습니다—에이전트 워크플로에서는 완전히 수용 가능합니다. 각 파트가 개별적으로 아무리 잘 노래해도, 전체 앙상블 리허설을 이길 수는 없습니다.
+
+## 핵심 정리
+
+- **단위 테스트는 컴포넌트 경계 결함에 체계적으로 맹목적입니다**—격리 설계 자체가 상호작용 문제를 탐지하지 못하게 합니다. 모두가 정확하게 노래해도 합창이 엇나갈 수 있습니다.
+- **엔드투엔드 테스트는 결함을 탐지할 뿐만 아니라 에이전트의 코딩 행동을 바꿉니다**—통합과 경계에 더 집중하게 만듭니다.
+- **아키텍처 규칙은 실행 가능해야 합니다**—읽히기를 기다리는 문서에 쓰이는 것이 아니라, 모든 커밋에서 자동으로 검사되어야 합니다.
+- **오류 메시지는 에이전트를 위해 설계되어야 합니다**—"어떻게 수정하는지"에 대한 구체적인 단계를 포함해 자기 수정 루프를 형성해야 합니다.
+- **리뷰 피드백 승격이 해네스를 자동으로 강화합니다**—포착된 결함의 각 카테고리가 영구적인 방어선이 됩니다.
+
+## 더 읽을거리
+
+- [How Google Tests Software - Whittaker et al.](https://www.goodreads.com/book/show/13563030-how-google-tests-software) — 테스팅 피라미드 모델의 고전적 원천
+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — 아키텍처 제약의 자동화된 실행을 위한 엔지니어링 실천
+- [Chaos Engineering - Netflix (Basiri et al.)](https://ieeexplore.ieee.org/document/7466237) — 시스템 복원력 검증을 위한 능동적 장애 주입
+- [QuickCheck - Claessen & Hughes](https://www.cs.tufts.edu/~nr/cs257/archive/john-hughes/quick.pdf) — 예제 테스트와 형식 검증 사이에 위치한 속성 테스팅 방법론
+
+## 연습 문제
+
+1. **크로스 컴포넌트 결함 탐지**: 최소 세 개의 컴포넌트가 관련된 수정 작업을 선택하세요. 먼저 단위 테스트만 실행하고 결과를 기록한 다음, 엔드투엔드 테스트를 실행합니다. 추가로 발견된 각 결함이 어떤 유형의 계층 간 상호작용 문제에 해당하는지 분석하세요.
+
+2. **아키텍처 규칙 자동화**: 프로젝트에서 아키텍처 제약을 선택하고 실행 가능한 검사(에이전트 지향 오류 메시지 포함)로 전환하세요. 해네스에 통합하고 기준선 작업으로 효과를 검증하세요.
+
+3. **리뷰 피드백 승격**: 코드 리뷰 히스토리에서 반복되는 코멘트 유형을 찾아 5단계 프로세스를 사용해 자동화된 검사로 전환하세요. 승격 전후에 문제의 빈도를 비교하세요.
diff --git a/docs/ko/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md b/docs/ko/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md
new file mode 100644
index 0000000..d640fc5
--- /dev/null
+++ b/docs/ko/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md
@@ -0,0 +1,8 @@
+# 평가자 루브릭 예제
+
+각 차원에 대해 1-5 점수를 사용합니다.
+
+- 근거(Grounding): 답변이 가져온 출처에 명확하게 연결되어 있는가?
+- 인용 품질(Citation quality): 출처 참조가 눈에 보이고 구체적인가?
+- 기능성(Functionality): 사용자가 질의응답 흐름을 완료할 수 있는가?
+- 제품 일관성(Product coherence): 워크플로가 통합된 것처럼 느껴지는가?
diff --git a/docs/ko/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md b/docs/ko/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md
new file mode 100644
index 0000000..1df9270
--- /dev/null
+++ b/docs/ko/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md
@@ -0,0 +1,8 @@
+# 강의 11 코드
+
+이 폴더는 다음 항목의 예제에 사용합니다.
+
+- 계획자 출력(planner outputs)
+- 평가자 루브릭(evaluator rubrics)
+- 생성자/평가자 루프(generator/evaluator loops)
+- 단일 에이전트 대 다중 역할 비교(single-agent vs multi-role comparisons)
diff --git a/docs/ko/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md b/docs/ko/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md
new file mode 100644
index 0000000..49ba615
--- /dev/null
+++ b/docs/ko/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md
@@ -0,0 +1,12 @@
+# 스프린트 계약 예제
+
+스프린트 목표:
+
+- 근거 기반 Q&A 결과에 눈에 보이는 인용 추가
+
+완료 기준:
+
+- 사용자가 질문을 합니다
+- 앱이 답변을 반환합니다
+- 최소 하나의 인용이 표시됩니다
+- 인용을 클릭하면 문서 뷰에서 출처 위치가 열립니다
diff --git a/docs/ko/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/ko/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
new file mode 100644
index 0000000..c6f011d
--- /dev/null
+++ b/docs/ko/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -0,0 +1,154 @@
+[English Version →](../../../en/lectures/lecture-11-why-observability-belongs-inside-the-harness/)
+
+> 코드 예제: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/)
+> 실습 프로젝트: [Project 06. 완전한 해네스 (캡스톤)](./../../projects/project-06-runtime-observability-and-debugging/index.md)
+
+# 강의 11. 에이전트의 런타임을 관측 가능하게 만들어라
+
+## 이 강의가 해결하는 문제
+
+에이전트에게 기능을 구현하도록 요청합니다. 20분 동안 실행하고, 여러 파일을 수정한 다음, "완료됐지만 두 개의 테스트가 실패하고 있습니다"라고 알립니다. 왜 실패하는지 물으면 "잘 모르겠습니다, 타이밍 문제일 수 있습니다". 어떤 중요 경로를 변경했는지 물으면 "코드를 살펴보겠습니다..."
+
+이것은 에이전트의 능력 부족 문제가 아닙니다. 해네스가 충분한 관측 가능성(observability)을 제공하지 않는 것입니다. **관측 가능성 없이는 에이전트가 불확실성 속에서 결정을 내리고, 평가는 주관적 판단이 되며, 재시도는 맹목적인 방황이 됩니다.** OpenAI와 Anthropic 모두 신뢰성을 증거 문제로 정의합니다—해네스는 런타임 동작과 평가 신호를 다음 결정을 안내할 수 있는 형태로 노출해야 합니다.
+
+## 핵심 개념
+
+- **런타임 관측 가능성(Runtime observability)**: 로그, 트레이스(trace), 프로세스 이벤트, 상태 확인 등 시스템 수준의 신호입니다. "시스템이 무엇을 했는가"에 대해 답합니다. 분산 시스템의 요청 트레이싱과 유사하게, 에이전트의 각 동작을 컨텍스트와 함께 기록합니다.
+- **프로세스 관측 가능성(Process observability)**: 계획, 채점 루브릭(rubric), 인수 기준 등 해네스 결정 산출물에 대한 가시성입니다. "이 변경이 왜 수용되어야 하는가"에 대해 답합니다.
+- **태스크 트레이스(Task trace)**: 태스크 시작부터 완료까지의 완전한 결정 경로 기록입니다. 분산 시스템의 요청 트레이싱과 유사하게, 에이전트가 취하는 모든 단계가 컨텍스트와 함께 기록됩니다.
+- **스프린트 계약(Sprint contract)**: 코딩 시작 전에 협상되는 단기 합의입니다. 작업 범위, 검증 기준, 제외 사항을 명시합니다. 프로세스 관측 가능성을 위한 핵심 도구입니다.
+- **평가자 루브릭(Evaluator rubric)**: 품질 평가를 주관적 판단에서 증거 기반 구조화된 채점으로 변환합니다. 서로 다른 평가자가 동일한 출력에 대해 유사한 결과를 도출하게 합니다.
+- **계층화된 관측 가능성(Layered observability)**: 시스템 계층과 프로세스 계층의 관측 가능성을 동시에 설계하고 서로 강화하게 합니다. 런타임 신호는 동작을 설명하고, 프로세스 산출물은 의도를 설명합니다.
+
+## 계층화된 관측 가능성
+
+```mermaid
+flowchart LR
+ Contract["먼저 작업을 적어 두세요<br/>변경할 것 / 변경하지 않을 것 / 통과 기준"] --> Generator["생성기"]
+ Generator --> Signals["실행 중에 앱 로그, 트레이스,<br/>상태 확인을 수집합니다"]
+ Contract --> Review["결과를 항목별로 확인합니다<br/>동작 / 테스트 / 경계"]
+ Signals --> Review
+ Review --> Verdict["실패한 검사와<br/>수정 위치를 지목합니다"]
+ Verdict --> Generator
+```
+
+## 왜 이런 일이 발생하는가
+
+### 관측 가능성 부재의 실제 비용
+
+해네스에 관측 가능성이 없으면 네 가지 유형의 문제가 체계적으로 나타납니다.
+
+**"정확함"과 "정확해 보임"을 구별할 수 없다**: 코드 리뷰 중에 함수가 완벽하게 보입니다—올바른 구문, 탄탄한 로직. 그러나 런타임에서 엣지 케이스 처리 오류가 특정 입력에서 잘못된 결과를 만들어냅니다. 실제 실행 경로가 예상에서 벗어났다는 것은 런타임 트레이스만이 드러낼 수 있습니다.
+
+**평가가 신비주의가 된다**: 채점 루브릭과 인수 기준 없이는 평가자(사람 또는 에이전트)가 암묵적 가정에 의존합니다. 동일한 출력이 서로 다른 평가자로부터 완전히 다른 평가를 받을 수 있습니다. 품질 평가가 재현 불가능해집니다.
+
+**재시도가 맹목적인 추측이 된다**: 에이전트가 왜 실패했는지 모르면, 재시도 방향이 무작위입니다. 실제 실패 근본 원인을 무시하고 관련 없는 코드 경로를 고치면서 잘못된 방향으로 반복적으로 시도할 수 있습니다. 모든 맹목적 재시도는 토큰과 시간을 소비합니다.
+
+**세션 핸드오프(handoff) 정보 절벽**: 완료되지 않은 작업이 다음 세션으로 인계될 때, 관측 가능성 부재는 새 세션이 시스템 상태를 처음부터 진단해야 함을 의미합니다. Anthropic의 장시간 실행 에이전트 관찰에 따르면 이러한 중복 진단이 총 세션 시간의 30-50%를 소비할 수 있습니다.
+
+### 실제 Claude Code 시나리오
+
+"계획자-생성자-평가자(planner-generator-evaluator)" 세 가지 역할 워크플로를 사용하는 해네스가 "앱에 다크 모드 추가" 작업을 실행하는 것을 상상해 보세요.
+
+**관측 가능성 없이**: 계획자가 모호한 설명을 출력합니다. 생성자가 그 모호함을 바탕으로 다크 모드를 구현하지만, 계획자의 암묵적 기대와 맞지 않습니다. 평가자는 자신의 암묵적 기준을 바탕으로 거부하지만, 구체적으로 무엇이 잘못됐는지 명확히 말할 수 없습니다. 생성자는 모호한 거부 이유를 바탕으로 맹목적으로 재시도합니다. 사이클이 3-4번 반복되고, 약 45분이 소요되며, 겨우 수용 가능한 출력이 만들어집니다.
+
+**완전한 관측 가능성으로**: 계획자가 스프린트 계약을 출력합니다—수정할 컴포넌트, 각각의 검증 기준, 제외 사항(인쇄 스타일 처리 안 함)을 나열합니다. 생성자가 계약에 따라 구현합니다. 런타임 관측 가능성이 각 컴포넌트의 스타일 로딩 및 적용 프로세스를 기록합니다. 평가자가 채점 루브릭을 사용해 차원별로 평가하며, 구체적인 증거를 인용합니다. 한 번의 반복으로 고품질 결과가 나오고, 약 15분이 소요됩니다.
+
+3배의 효율성 차이. 유일한 변화는 관측 가능성입니다.
+
+### 에이전트가 이것을 스스로 해결할 수 없는 이유
+
+"에이전트가 자체 로그를 출력하면 안 되나요?"라고 생각할 수 있습니다. 문제는 다음과 같습니다.
+
+1. 에이전트는 자신이 모르는 것을 모릅니다—필요하다고 깨닫지 못하는 신호는 능동적으로 기록하지 않을 것입니다.
+2. 로그 형식이 일관되지 않습니다—서로 다른 세션이 서로 다른 로그 형식을 사용하면 체계적인 분석이 불가능합니다.
+3. 프로세스 관측 가능성은 로그로 해결할 수 없습니다—스프린트 계약과 채점 루브릭은 해네스 수준의 지원이 필요한 구조화된 산출물입니다.
+
+## 올바르게 하는 방법
+
+### 1. 런타임 신호 수집을 해네스에 구축하라
+
+에이전트가 자체 로그를 출력하는 것에 의존하지 마세요. 해네스가 자동으로 이러한 신호를 수집해야 합니다.
+
+- **애플리케이션 수명 주기**: 시작, 준비, 실행, 종료 단계 상태
+- **기능 경로 실행**: 진입점, 체크포인트, 종료를 포함한 중요 경로 실행 기록
+- **데이터 흐름**: 컴포넌트 간 데이터 흐름 기록
+- **리소스 활용**: 비정상적인 리소스 사용 패턴 (예: 지속적으로 증가하는 메모리)
+- **오류 및 예외**: 오류 메시지만이 아닌 전체 오류 컨텍스트
+
+### 2. 스프린트 계약을 구현하라
+
+각 작업 시작 전에, 생성자와 평가자(동일한 에이전트의 서로 다른 호출일 수 있음)가 계약을 협상합니다.
+
+```markdown
+# 스프린트 계약: 다크 모드 지원
+
+## 범위
+- 테마 전환 컴포넌트 수정
+- 전역 CSS 변수 업데이트
+- 다크 모드 테스트 추가
+
+## 검증 기준
+- 각 컴포넌트에 대한 시각적 회귀 테스트 통과
+- 주요 흐름 엔드투엔드 테스트 통과
+- 스타일되지 않은 콘텐츠의 플래시(FOUC) 없음
+
+## 제외 사항
+- 인쇄 스타일 처리 안 함
+- 써드파티 컴포넌트 다크 모드 처리 안 함
+```
+
+### 3. 평가자 루브릭을 수립하라
+
+"좋은가 아닌가"를 정량화 가능한 채점으로 전환합니다.
+
+```markdown
+# 채점 루브릭
+
+| 차원 | A | B | C | D |
+|------|---|---|---|---|
+| 코드 정확성 | 모든 테스트 통과 | 주요 흐름 통과 | 부분 통과 | 빌드 실패 |
+| 아키텍처 준수 | 완전 준수 | 사소한 편차 | 명백한 편차 | 심각한 위반 |
+| 테스트 커버리지 | 주요 + 엣지 케이스 | 주요 흐름만 | 스켈레톤만 | 테스트 없음 |
+```
+
+### 4. OpenTelemetry로 표준화하라
+
+각 해네스 세션에 대한 트레이스(trace)를, 각 작업에 대한 스팬(span)을, 각 검증 단계에 대한 하위 스팬을 생성하세요. 표준 속성을 사용해 주요 정보에 주석을 달 수 있습니다. 이렇게 하면 관측 가능성 데이터가 표준 툴체인(Jaeger, Zipkin)과 통합됩니다.
+
+## 실제 사례
+
+계획자-생성자-평가자 워크플로를 사용하는 해네스가 "다크 모드 지원 추가"를 실행합니다.
+
+**관측 불가능한 버전**: 3-4번의 맹목적 재시도, 45분, 겨우 수용 가능한 출력. 평가자는 "느낌이 좋지 않습니다"라고 하지만 구체적으로 무엇인지 말할 수 없습니다. 생성자는 잘못된 방향으로 상당한 시간을 낭비합니다.
+
+**완전히 관측 가능한 버전**:
+- 스프린트 계약이 범위, 기준, 제외 사항을 명확히 함
+- 런타임 트레이스가 각 컴포넌트의 스타일 로딩 프로세스를 기록
+- 채점 루브릭이 차원별 구조화된 평가를 제공
+- 한 번의 반복으로 고품질 결과, 15분
+
+3배 효율성 향상, 더 안정적인 품질, 재현 가능한 평가.
+
+## 핵심 정리
+
+- **관측 가능성은 해네스 아키텍처의 속성입니다**—나중에 추가되는 기능이 아니라, 설계 중에 고려되어야 하는 핵심 역량입니다.
+- **두 관측 가능성 계층이 모두 필수적입니다**—런타임 신호는 "무슨 일이 있었는가"를 설명하고, 프로세스 산출물은 "왜 그렇게 했는가"를 설명합니다.
+- **스프린트 계약은 사전 정렬(front-load alignment)을 수행합니다**—"생성자가 구축한 것을 평가자가 예측 가능한 이유로 즉시 거부하는" 상황을 방지합니다.
+- **채점 루브릭은 평가를 재현 가능하게 만듭니다**—서로 다른 평가자가 동일한 출력에 대해 유사한 점수를 부여합니다.
+- **관측 가능성 부재는 세션 시간의 30-50%를 중복 진단에 낭비합니다.**
+
+## 더 읽을거리
+
+- [Observability Engineering - Charity Majors](https://www.honeycomb.io/blog/observability-engineering-book) — 현대 관측 가능성 엔지니어링의 이론과 실천 프레임워크
+- [Dapper - Google (Sigelman et al.)](https://research.google/pubs/pub36356/) — 대규모 분산 트레이싱의 선구적 실천
+- [Harness Design - Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps) — 스프린트 계약과 평가자 루브릭 소개
+- [Site Reliability Engineering - Google](https://sre.google/sre-book/table-of-contents/) — 프로덕션 시스템에서 관측 가능성의 체계적 적용
+
+## 연습 문제
+
+1. **관측 가능성 격차 분석**: 현재 해네스에서 시스템 계층과 프로세스 계층의 관측 가능성을 감사합니다. 기존 신호로 구별할 수 없는 시스템 상태를 찾아 추가 사항을 제안하세요.
+
+2. **스프린트 계약 실습**: 실제 작업에 대한 스프린트 계약을 작성하세요. 에이전트가 계약에 따라 실행하도록 하고, 계약 유무에 따른 효율성과 품질을 비교하세요.
+
+3. **태스크 트레이스 구성**: 완전한 코딩 작업 동안 에이전트 작업의 모든 단계를 기록합니다. OpenTelemetry 시맨틱 컨벤션으로 주석을 달 수 있습니다. 트레이스에서 정보 병목을 분석합니다—어떤 단계가 결정을 위한 충분한 신호 지원이 부족한지 파악하세요.
diff --git a/docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md b/docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md
new file mode 100644
index 0000000..4cc9039
--- /dev/null
+++ b/docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md
@@ -0,0 +1,18 @@
+# 벤치마크 비교 템플릿
+
+해네스 A:
+
+- 완료율
+- 평균 재시도 횟수
+- 사람 리뷰 전에 발견된 버그
+
+해네스 B:
+
+- 완료율
+- 평균 재시도 횟수
+- 사람 리뷰 전에 발견된 버그
+
+해석:
+
+- 어떤 해네스가 결과를 바꿨는가?
+- 어떤 해네스가 결과를 얻는 비용을 바꿨는가?
diff --git a/docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md b/docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md
new file mode 100644
index 0000000..34dee5c
--- /dev/null
+++ b/docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md
@@ -0,0 +1,9 @@
+# 클린업 루프 예제
+
+반복적인 정리 작업:
+
+- 오래된 문서 스캔
+- 구조적 위반 스캔
+- 품질 등급 업데이트
+- 목표 지향 정리 PR 오픈
+- 정리 후 고정 벤치마크 슬라이스 재실행
diff --git a/docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md b/docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md
new file mode 100644
index 0000000..d934e87
--- /dev/null
+++ b/docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md
@@ -0,0 +1,8 @@
+# 강의 12 코드
+
+이 폴더는 다음 항목의 예제에 사용합니다.
+
+- 벤치마크 슬라이스(benchmark slices)
+- 정리 작업(cleanup tasks)
+- 엔트로피 감소 예제(entropy reduction examples)
+- 반복 가능한 해네스 실행(repeatable harness runs)
diff --git a/docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
new file mode 100644
index 0000000..b8e27e3
--- /dev/null
+++ b/docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -0,0 +1,186 @@
+[English Version →](../../../en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/)
+
+> 코드 예제: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/)
+> 실습 프로젝트: [Project 06. 완전한 해네스 (캡스톤)](./../../projects/project-06-runtime-observability-and-debugging/index.md)
+
+# 강의 12. 모든 세션은 클린 상태(clean state)로 끝나야 한다
+
+## 이 강의가 해결하는 문제
+
+에이전트가 오후 내내 실행되고, 20개의 파일을 수정하고, 코드를 커밋하고, 세션이 종료됩니다. 다음 에이전트 세션이 시작되고 즉시 발견합니다. 빌드가 깨져 있고, 테스트는 빨간 상태이며, 임시 디버그 파일이 곳곳에 있고, 기능 목록은 업데이트되지 않았으며, 진행 상황이 전혀 불분명합니다. 새 세션은 "지난 세션이 실제로 무엇을 했는가"를 파악하는 데 첫 30분을 씁니다.
+
+OpenAI와 Anthropic 모두 명확히 밝힙니다. **장기적 신뢰성은 단일 실행의 성공이 아니라 운영 규율에 달려 있습니다.** 세션 종료 시점의 상태 품질이 다음 세션의 효율성을 직접 결정합니다. Git 모범 사례처럼 생각하세요—모든 커밋은 원자적이고 컴파일 가능한 변경이어야 하며, 반쯤 완성된 코드 더미가 되어서는 안 됩니다.
+
+## 핵심 개념
+
+- **클린 상태(Clean state)**: 세션 종료 시 시스템이 다섯 가지 조건을 만족하는 것입니다—빌드 통과, 테스트 통과, 진행 상황 기록됨, 오래된 산출물 없음, 시작 경로 사용 가능. 하나라도 빠지면 세션이 "완료"된 것이 아닙니다.
+- **세션 무결성(Session integrity)**: 데이터베이스 트랜잭션과 유사합니다—완전히 커밋하고 클린 상태를 남기거나, 마지막 일관된 상태로 롤백합니다. 중간 지점은 없습니다.
+- **품질 문서(Quality document)**: 각 모듈의 품질 등급을 지속적으로 기록하는 활성 산출물입니다. 일회성 평가가 아니라, 코드베이스가 시간이 지남에 따라 강해지는지 약해지는지 보여주는 추적기입니다.
+- **클린업 루프(Cleanup loop)**: 코드베이스의 엔트로피(entropy)를 체계적으로 줄이기 위한 정기적인 유지보수 세션입니다. 긴급 수정이 아닌 일상적인 운영입니다.
+- **해네스 단순화(Harness simplification)**: 모델 역량이 향상됨에 따라, 더 이상 필요하지 않은 해네스 구성 요소를 주기적으로 제거합니다. 오늘 필수적인 제약이 세 달 후에는 불필요한 오버헤드가 될 수 있습니다.
+- **멱등 정리(Idempotent cleanup)**: 정리 작업이 몇 번 실행되든 동일한 결과를 생성합니다. 실패-재시도 시나리오에서도 정리가 안전하게 유지됨을 보장합니다.
+
+## 클린 상태의 다섯 가지 차원
+
+```mermaid
+flowchart LR
+ Work["기능 작업 완료"] --> Build{"빌드 통과?"}
+ Build -->|yes| Test{"테스트 통과?"}
+ Build -->|no| Fix["종료 전에 수정"]
+ Test -->|yes| Record["기능 목록 + 진행 상황 업데이트"]
+ Test -->|no| Fix
+ Record --> Cleanup["임시 산출물 / 디버그 코드 제거"]
+ Cleanup --> Startup{"표준 시작 경로 작동?"}
+ Startup -->|yes| Clean["클린 핸드오프"]
+ Startup -->|no| Fix
+ Fix --> Build
+```
+
+```mermaid
+flowchart LR
+ Dirty["세션이 종료됨<br/>빨간 테스트 / 임시 파일 / 진행 상황 미업데이트"] --> Diagnose["다음 세션이 먼저<br/>무슨 일이 있었는지 파악해야 함"]
+ Diagnose --> Fragile["새 작업이 지저분한 저장소에서 시작됨"]
+ Fragile --> More["더 많은 디버그 파일, 더 많은 깨진 검사,<br/>더 불분명한 진행 상황"]
+ More --> Dirty
+
+ Clean["세션이 종료됨<br/>초록 테스트 / 업데이트된 진행 상황 / 임시 파일 제거"] --> Fast["다음 세션이 즉시 코딩을 시작할 수 있음"]
+ Fast --> Stable["먼저 저장소를 구조할 필요 없음"]
+ Stable --> Clean
+```
+
+## 왜 이런 일이 발생하는가
+
+### 엔트로피 증가가 기본 상태이다
+
+소프트웨어 진화의 Lehman 법칙에 따르면 지속적으로 변경되는 시스템은 능동적으로 관리되지 않으면 복잡성이 불가피하게 증가합니다. 이것은 AI 코딩 에이전트에게 특히 사실입니다—매 세션마다 변경 사항을 도입하고, 종료 시 정리하지 않으면 기술 부채가 기하급수적으로 쌓입니다.
+
+실제 데이터가 이를 말해줍니다. 정리 전략 없이 12주간 에이전트로 개발된 프로젝트:
+
+- 1주차: 빌드 통과율 100%, 테스트 통과율 100%, 새 세션 시작 5분
+- 4주차: 빌드 95%, 테스트 92%, 시작 15분
+- 8주차: 빌드 82%, 테스트 78%, 시작 35분
+- 12주차: 빌드 68%, 테스트 61%, 시작 60분+
+
+정리 전략이 있는 동일한 프로젝트:
+
+- 1주차: 100%, 100%, 5분
+- 12주차: 97%, 95%, 9분
+
+12주 후: 빌드 통과율 29퍼센트포인트 차이, 새 세션 시작 시간 85% 차이. 이것은 이론이 아닙니다—관찰된 차이입니다.
+
+### 클린 상태의 다섯 가지 차원
+
+클린 상태는 단순히 "코드가 컴파일된다"는 것이 아닙니다. 함께 평가되는 다섯 가지 차원입니다.
+
+**빌드 차원**: 코드가 오류 없이 빌드되는가? 이것이 가장 기본입니다—다음 세션이 빌드 오류를 먼저 수정해야 하는 상황은 없어야 합니다.
+
+**테스트 차원**: 모든 테스트가 통과하는가? 세션 전에 존재했던 테스트도 포함해서입니다—세션은 기존 기능을 깨뜨리지 않을 책임이 있습니다. 그리고 "내 기계에서는 작동해"가 아니라 CI에서 검증되어야 합니다.
+
+**진행 상황 차원**: 현재 진행 상황이 기계가 읽을 수 있는 산출물에 기록되어 있는가? 통과 기준이 있는 완료된 하위 작업, 현재 상태가 있는 진행 중이지만 완료되지 않은 하위 작업, 아직 시작되지 않은 하위 작업. 좋은 진행 상황 기록은 세션 시작 진단 시간의 60-80%를 줄입니다.
+
+**산출물 차원**: 오래되거나 모호한 임시 산출물이 있는가? 디버그 로그, 임시 파일, 주석 처리된 코드, TODO 마커—이 모두가 다음 세션의 인지 부하를 높입니다.
+
+**시작 차원**: 표준 시작 경로를 사용할 수 있는가? 다음 세션이 수동 개입 없이 작업을 시작할 수 있는가? 환경 초기화, 코드베이스 로딩, 컨텍스트 획득, 작업 선택—이 경로들이 깨져서는 안 됩니다.
+
+### "나중에 정리"는 절대 정리하지 않는다는 의미다
+
+가장 흔한 정신적 함정은 "이번 세션에는 정리할 시간이 없으니 다음에 하겠다"입니다. 그러나 다음 에이전트 세션은 당신이 남겨 놓은 것을 모릅니다—코드 더미와 불확실한 상태를 봅니다. "이 코드의 어떤 부분이 의도적이고 어떤 부분이 임시적인가"를 추론하는 데 상당한 시간을 씁니다.
+
+더 나쁜 것은, 모든 세션에는 자체 작업 목표가 있습니다. 새 세션은 이전 세션의 혼란을 정리하는 것이 아니라 새 작업을 하러 왔습니다. 혼란을 무시하고 그 위에 새 작업을 시작하여, 혼란 위에 더 많은 혼란을 도입합니다. 이것이 엔트로피의 양의 피드백 루프입니다.
+
+## 올바르게 하는 방법
+
+### 1. 클린 상태를 완료 요건으로 정의하라
+
+해네스에서 명시적으로 정의하세요. **세션 완료 = 작업이 검증을 통과함 AND 클린 상태 검사를 통과함.** 둘 중 하나라도 빠지면 세션이 완료된 것이 아닙니다. CLAUDE.md에 작성하세요.
+
+```
+## 세션 종료 체크리스트
+- [ ] 빌드 통과 (npm run build)
+- [ ] 모든 테스트 통과 (npm test)
+- [ ] 기능 목록 업데이트됨
+- [ ] 디버그 코드 없음 (console.log, debugger, TODO)
+- [ ] 표준 시작 경로 사용 가능 (npm run dev)
+```
+
+### 2. 이중 모드 정리 전략을 결합하라
+
+두 가지 정리 모드를 결합합니다.
+
+**즉각적 정리 (모든 세션 종료 시)**: 세션 중에 생성된 임시 산출물을 정리하고, 기능 목록 상태를 업데이트하고, 빌드와 테스트가 통과하는지 확인합니다. 이것은 "참조 카운팅" 정리입니다.
+
+**주기적 정리 (주간)**: 전체 시스템 스캔—누적된 구조적 문제를 처리하고, 품질 문서를 업데이트하고, 드리프트를 탐지하기 위해 벤치마크 테스트를 실행합니다. 이것은 "추적" 정리입니다.
+
+### 3. 품질 문서를 유지하라
+
+품질 문서는 각 모듈을 지속적으로 채점하는 활성 산출물입니다.
+
+```markdown
+# 품질 문서
+
+## 사용자 인증 모듈 (품질: A)
+- 검증 통과: 예
+- 에이전트 이해 가능: 예
+- 테스트 안정성: 안정
+- 아키텍처 경계: 준수
+- 코드 컨벤션: 따름
+
+## 결제 모듈 (품질: C)
+- 검증 통과: 부분 (결제 콜백 미테스트)
+- 에이전트 이해 가능: 어려움 (로직이 3개 파일에 분산)
+- 테스트 안정성: 불안정 (2개의 불안정 테스트)
+- 아키텍처 경계: 위반 존재
+- 코드 컨벤션: 부분적으로 따름
+```
+
+새 세션은 이 문서를 읽고 어디에 우선순위를 둘지 즉시 알 수 있습니다. 가장 낮은 점수의 모듈을 먼저 수정합니다.
+
+### 4. 주기적으로 해네스를 단순화하라
+
+Anthropic의 중요한 통찰: **모든 해네스 구성 요소는 모델이 스스로 무언가를 안정적으로 할 수 없기 때문에 존재합니다. 그러나 모델이 향상됨에 따라 이러한 가정은 구식이 됩니다.** 세 달 전에 필수적인 제약이 오늘은 불필요한 오버헤드일 수 있습니다.
+
+권장 실천: 매달 하나의 해네스 구성 요소를 선택하고, 일시적으로 비활성화하고, 벤치마크 작업을 실행합니다. 결과가 저하되지 않으면 영구적으로 제거합니다. 저하되면 복원하거나 더 가벼운 대안으로 교체합니다.
+
+### 5. 정리 작업은 멱등적이어야 한다
+
+정리 스크립트는 반복 실행에도 안전해야 합니다.
+
+```bash
+# 멱등 정리 작업
+rm -f /tmp/debug-*.log # -f는 파일이 없을 때 오류 없음을 보장
+git checkout -- .env.local # 알려진 상태로 복원
+npm run test # 정리가 아무것도 깨뜨리지 않았는지 확인
+```
+
+## 실제 사례
+
+12주 동안 에이전트로 개발된 Electron 앱으로 두 가지 접근 방식을 비교합니다.
+
+**정리 전략 없이** (대조군): 12주차, 빌드 통과율 68%, 테스트 통과율 61%, 새 세션 시작 60분+, 오래된 산출물 103개.
+
+**정리 전략으로** (실험군): 모든 세션 종료 시 완전한 클린 상태 검사 + 주간 클린업 루프. 12주차, 빌드 통과율 97%, 테스트 통과율 95%, 새 세션 시작 9분, 오래된 산출물 11개.
+
+12주차에 실험군의 빌드 통과율은 29퍼센트포인트 높고, 테스트 통과율은 34포인트 높으며, 새 세션 시작 시간은 85% 낮습니다.
+
+## 핵심 정리
+
+- **클린 상태는 세션 완료의 필요 조건입니다**—선택적 정리 작업이 아니라, "완료의 정의"의 일부입니다.
+- **다섯 가지 차원 모두 필요합니다**—빌드, 테스트, 진행 상황, 산출물, 시작—각각 명시적으로 검사되어야 합니다.
+- **품질 문서는 코드베이스 건강을 추적 가능하게 만듭니다**—저하되고 있다는 것을 알아야만 수정할 수 있습니다.
+- **주기적으로 해네스를 단순화하세요**—모델 역량이 향상됨에 따라, 더 이상 필요 없는 제약을 제거하세요.
+- **"나중에 정리"는 절대 정리하지 않는다는 의미입니다**—엔트로피 증가가 기본 상태이며, 능동적인 정리만이 이를 막을 수 있습니다.
+
+## 더 읽을거리
+
+- [Clean Code - Robert C. Martin](https://www.goodreads.com/book/show/3735293-clean-code) — 코드 청결성의 체계적 원칙
+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — 핵심 해네스 설계 요건으로서의 재현성
+- [Effective Harnesses - Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — 장기적 신뢰성을 위한 클린 세션 종료의 중요한 역할
+- [Programs, Life Cycles, and Laws of Software Evolution - Lehman](https://ieeexplore.ieee.org/document/1702314) — 능동적 유지보수 없이는 시스템 복잡성이 불가피하게 증가함을 증명하는 소프트웨어 진화 법칙
+
+## 연습 문제
+
+1. **클린 상태 체크리스트**: 다섯 가지 차원을 모두 포함하는 코드베이스의 세션 종료 체크리스트를 설계하세요. 연속 5개 세션에 적용하고 차원별 위반 사항을 기록하세요.
+
+2. **벤치마크 비교**: 두 가지 해네스 변형(클린 상태 요건 있음/없음)으로 고정된 작업 세트를 사용하세요. 완료율, 재시도 횟수, 결함 탈출률을 비교하세요.
+
+3. **해네스 단순화 실습**: 하나의 해네스 구성 요소를 선택하고, 일시적으로 비활성화하고, 벤치마크 작업을 실행하세요. 있을 때와 없을 때의 결과를 비교하세요. 유지할지, 제거할지, 교체할지 결정하세요.
diff --git a/docs/ko/projects/index.md b/docs/ko/projects/index.md
new file mode 100644
index 0000000..7986c76
--- /dev/null
+++ b/docs/ko/projects/index.md
@@ -0,0 +1,24 @@
+# 프로젝트에 오신 것을 환영합니다
+
+이곳은 Learn Harness Engineering의 실습(hands-on) 섹션입니다. 강의를 읽는 것만으로는 충분하지 않습니다. 직접 환경을 구축하고, 서로 다른 규칙 아래에서 Codex, Claude Code 또는 다른 AI 에이전트(agent)가 어떻게 동작하는지 관찰해야 합니다.
+
+## 프로젝트 개요
+
+이 강의는 신뢰할 수 있는 에이전트 작업 환경을 처음부터 구축하는 방법을 가르치는, 단계적으로 심화되는 6개의 실습 프로젝트로 구성되어 있습니다.
+
+1. **프롬프트 단독 vs. 규칙 우선(Rules-First)**: 프롬프트만 사용하는 경우와 기초 해네스(harness)를 갖춘 경우의 에이전트 성능을 비교합니다.
+2. **에이전트 가독성 있는 작업 공간**: 저장소를 AI 친화적으로 구조화하는 방법과 핸드오프(handoff) 메커니즘을 확립하는 방법을 학습합니다.
+3. **멀티 세션 연속성(Multi-Session Continuity)**: 에이전트가 세션 간에 작업을 원활하게 재개할 수 있도록 상태(state) 파일과 초기화(initialization) 스크립트를 설계합니다.
+4. **런타임 피드백과 범위 제어**: 에이전트가 자신의 코드를 테스트하고 실행 중 오류를 수정할 수 있는 도구를 도입합니다.
+5. **자기 검증과 역할 분리**: 환각(hallucination)과 섣부른 완료 선언을 방지하기 위한 독립적인 리뷰 메커니즘을 구축합니다.
+6. **완전한 해네스(캡스톤)**: 관찰 가능하고(observable) 완성된 엔드-투-엔드 에이전트 작업 환경을 조립합니다.
+
+## 진행 방법
+
+각 프로젝트 폴더에는 일반적으로 다음이 포함됩니다.
+
+- `starter/`: 시작 작업 공간입니다.
+- `solution/`: 참조 구현체(막히면 참고하세요)입니다.
+- 배경 지식과 구체적인 목표를 설명하는 작업 지침입니다.
+
+`starter/` 디렉터리 안에서 원하는 AI 코딩 에이전트(예: Claude Code, Cursor, Trae)를 사용하여 작업을 완료하시기 바랍니다.
diff --git a/docs/ko/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/ko/projects/project-01-baseline-vs-minimal-harness/index.md
new file mode 100644
index 0000000..d730214
--- /dev/null
+++ b/docs/ko/projects/project-01-baseline-vs-minimal-harness/index.md
@@ -0,0 +1,27 @@
+[English Version →](../../../en/projects/project-01-baseline-vs-minimal-harness/)
+
+> 관련 강의: [강의 01. 강력한 모델이 곧 신뢰할 수 있는 실행을 의미하지는 않습니다](./../../lectures/lecture-01-why-capable-agents-still-fail/index.md) · [강의 02. 해네스가 실제로 의미하는 것](./../../lectures/lecture-02-what-a-harness-actually-is/index.md)
+> 템플릿 파일: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/resources/templates/)
+
+# 프로젝트 01. 프롬프트 단독 vs. 규칙 우선(Rules-First): 차이는 얼마나 클까
+
+## 해야 할 일
+
+최소한의 Electron 지식 베이스 앱 쉘(shell)을 구축합니다. 왼쪽에 문서 목록이 있고, 오른쪽에 Q&A 패널이 있으며, 로컬 데이터 디렉터리가 포함된 창입니다. 작업 자체는 복잡하지 않습니다. 복잡한 것은 에이전트(agent)가 이 작업을 완료하도록 만드는 방법입니다.
+
+두 번 실행합니다. 첫 번째: 프롬프트만 사용하고 사전 준비 없이 진행합니다. 두 번째: `AGENTS.md`, `init.sh`, `feature_list.json`을 저장소에 미리 배치한 상태로 진행합니다. 그런 다음 비교합니다.
+
+이 프로젝트의 핵심은 코드를 작성하는 것이 아닙니다. "규칙을 먼저 준비하는 데 15분을 쓰는 것"과 "에이전트를 그냥 실행시키는 것" 사이의 격차가 얼마나 큰지 파악하는 것입니다.
+
+에이전트에게 규칙(rule)과 초기화(initialization) 단서를 제공하면 작업 범위를 스스로 파악하고 불필요한 탐색을 줄일 수 있습니다. 이처럼 최소한의 해네스만으로도 에이전트의 출발점과 결과 품질이 크게 달라집니다.
+
+## 도구
+
+- Claude Code 또는 Codex (하나를 선택하여 두 번의 실행 모두 동일하게 사용)
+- Git (브랜치 관리 및 비교)
+- Node.js + Electron (프로젝트 스택)
+- 타이머 (각 실행의 소요 시간 기록)
+
+## 해네스 메커니즘
+
+최소 해네스(minimal harness): `AGENTS.md` + `init.sh` + `feature_list.json`
diff --git a/docs/ko/projects/project-02-agent-readable-workspace/index.md b/docs/ko/projects/project-02-agent-readable-workspace/index.md
new file mode 100644
index 0000000..489c76e
--- /dev/null
+++ b/docs/ko/projects/project-02-agent-readable-workspace/index.md
@@ -0,0 +1,24 @@
+[English Version →](../../../en/projects/project-02-agent-readable-workspace/)
+
+> 관련 강의: [강의 03. 저장소를 단일 진실 원천으로 만들기](./../../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) · [강의 04. 지침을 여러 파일로 분리하기](./../../lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)
+> 템플릿 파일: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/resources/templates/)
+
+# 프로젝트 02. 프로젝트를 읽기 쉽게 만들고 중단된 곳에서 재개하기
+
+## 해야 할 일
+
+새로운 에이전트(agent)가 프로젝트 구조를 빠르게 파악하고, 현재 진행 상황을 이해하며, 작업을 이어받을 수 있도록 저장소에 "가독성(readability)"을 추가합니다. 구체적으로는 문서 임포트(import), 문서 상세 보기, 로컬 퍼시스턴스(persistence)를 구현하며, 두 세션에 걸쳐 완성합니다.
+
+두 번 실행합니다. 첫 번째는 아무런 도움 없이, 두 번째는 `ARCHITECTURE.md`, `PRODUCT.md`, `session-handoff.md`를 저장소에 미리 배치한 상태로 진행합니다.
+
+에이전트는 컨텍스트 윈도(context window)가 초기화되면 이전 작업 흐름을 기억하지 못합니다. 세션 핸드오프(session handoff) 파일을 통해 이전 세션의 상태(state)를 영속화하면, 새 세션의 에이전트도 동일한 진행 지점에서 출발할 수 있습니다.
+
+## 도구
+
+- Claude Code 또는 Codex
+- Git
+- Node.js + Electron
+
+## 해네스 메커니즘
+
+에이전트 가독성 있는 작업 공간 + 영속 상태 파일(persistent state files)
diff --git a/docs/ko/projects/project-03-multi-session-continuity/index.md b/docs/ko/projects/project-03-multi-session-continuity/index.md
new file mode 100644
index 0000000..3f9bd86
--- /dev/null
+++ b/docs/ko/projects/project-03-multi-session-continuity/index.md
@@ -0,0 +1,24 @@
+[English Version →](../../../en/projects/project-03-multi-session-continuity/)
+
+> 관련 강의: [강의 05. 세션 간에 컨텍스트를 유지하기](./../../lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) · [강의 06. 모든 에이전트 세션 전에 초기화하기](./../../lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)
+> 템플릿 파일: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/resources/templates/)
+
+# 프로젝트 03. 세션 재시작 후에도 에이전트가 계속 작업하도록 만들기
+
+## 해야 할 일
+
+에이전트(agent)에 범위 제어(scope control)와 검증 게이트(verification gates)를 추가합니다. 문서 청킹(chunking), 메타데이터 추출, 인덱싱 진행 상태 표시, 인용 기반 Q&A 흐름을 구현합니다. `feature_list.json`을 사용하여 기능 상태를 추적합니다. 한 번에 하나의 기능만 처리하고, 검증 증거 없이는 "완료(pass)"로 표시할 수 없습니다.
+
+장시간 실행되는 작업은 컨텍스트(context) 초기화나 중단으로 인해 연속성(continuity)을 잃기 쉽습니다. 진행 로그(progress log)와 세션 핸드오프를 결합하면 에이전트가 이전에 완료한 항목을 재확인하지 않고 정확한 다음 단계에서 재개할 수 있습니다.
+
+두 번 실행합니다. 첫 번째는 제약 없이, 두 번째는 엄격한 적용 방식으로 진행합니다.
+
+## 도구
+
+- Claude Code 또는 Codex
+- Git
+- Node.js + Electron
+
+## 해네스 메커니즘
+
+진행 로그 + 세션 핸드오프 + 멀티 세션 연속성(multi-session continuity)
diff --git a/docs/ko/projects/project-04-incremental-indexing/index.md b/docs/ko/projects/project-04-incremental-indexing/index.md
new file mode 100644
index 0000000..3570258
--- /dev/null
+++ b/docs/ko/projects/project-04-incremental-indexing/index.md
@@ -0,0 +1,24 @@
+[English Version →](../../../en/projects/project-04-incremental-indexing/)
+
+> 관련 강의: [강의 07. 에이전트를 위한 명확한 작업 경계 설정하기](./../../lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) · [강의 08. 기능 목록을 사용하여 에이전트가 하는 일을 제한하기](./../../lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)
+> 템플릿 파일: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/resources/templates/)
+
+# 프로젝트 04. 런타임 피드백을 사용하여 에이전트 동작 수정하기
+
+## 해야 할 일
+
+런타임 관찰 가능성(runtime observability, 시작 로그, 임포트/인덱싱 로그, 오류 상태)을 추가하고, 레이어 간 위반(cross-layer violation)을 방지하기 위한 아키텍처 제약(architecture constraints)을 도입합니다. 에이전트가 수정할 수 있도록 런타임 버그를 심어 둡니다.
+
+에이전트는 로그(log)나 오류 출력이 없으면 내부 오류를 인식하기 어렵고, 존재하지 않는 기능도 "구현되었다"고 잘못 판단할 수 있습니다. 런타임 피드백 루프를 갖추면 에이전트가 실행 결과를 직접 관찰하고 동작을 즉시 수정할 수 있습니다.
+
+두 번 실행합니다. 첫 번째는 로그나 제약 없이, 두 번째는 적절한 도구와 규칙(rules)을 갖춘 상태로 진행합니다.
+
+## 도구
+
+- Claude Code 또는 Codex
+- Git
+- Node.js + Electron
+
+## 해네스 메커니즘
+
+런타임 피드백 + 범위 제어 + 증분 인덱싱(incremental indexing)
diff --git a/docs/ko/projects/project-05-grounded-qa-verification/index.md b/docs/ko/projects/project-05-grounded-qa-verification/index.md
new file mode 100644
index 0000000..4e1ccd5
--- /dev/null
+++ b/docs/ko/projects/project-05-grounded-qa-verification/index.md
@@ -0,0 +1,24 @@
+[English Version →](../../../en/projects/project-05-grounded-qa-verification/)
+
+> 관련 강의: [강의 09. 에이전트가 섣불리 완료를 선언하지 않도록 막기](./../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md) · [강의 10. 완전한 파이프라인 실행만이 진정한 검증으로 인정됩니다](./../../lectures/lecture-10-why-end-to-end-testing-changes-results/index.md)
+> 템플릿 파일: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/resources/templates/)
+
+# 프로젝트 05. 에이전트가 자신의 작업을 검증하도록 만들기
+
+## 해야 할 일
+
+역할 분리(role separation)를 구현합니다. 구현을 담당하는 생성자(generator), 검토를 담당하는 평가자(evaluator), 그리고 선택적으로 플래너(planner)를 만듭니다. 각 역할이 추가될 때마다 효과를 측정하기 위해 세 번 실행합니다.
+
+에이전트가 구현과 검증을 동시에 담당하면 자신의 오류를 스스로 발견하기 어렵습니다. 독립된 평가자 역할을 분리하면 환각(hallucination)과 섣부른 완료 선언을 방지하고, 근거 기반(grounded) Q&A의 정확도를 높일 수 있습니다.
+
+실질적인 기능 업그레이드(멀티턴 대화, 인용 패널 재설계, 또는 문서 필터링)를 선택하고 모든 실행에서 동일하게 유지합니다.
+
+## 도구
+
+- Claude Code 또는 Codex
+- Git
+- Node.js + Electron
+
+## 해네스 메커니즘
+
+자기 검증(self-verification) + 근거 기반 Q&A + 증거 기반 완료(evidence-based completion)
diff --git a/docs/ko/projects/project-06-runtime-observability-and-debugging/index.md b/docs/ko/projects/project-06-runtime-observability-and-debugging/index.md
new file mode 100644
index 0000000..42c71ca
--- /dev/null
+++ b/docs/ko/projects/project-06-runtime-observability-and-debugging/index.md
@@ -0,0 +1,27 @@
+[English Version →](../../../en/projects/project-06-runtime-observability-and-debugging/)
+
+> 관련 강의: [강의 11. 에이전트의 런타임을 관찰 가능하게 만들기](./../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) · [강의 12. 모든 세션의 끝에서 깔끔하게 핸드오프하기](./../../lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)
+> 템플릿 파일: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/resources/templates/)
+
+# 프로젝트 06. 완전한 에이전트 해네스 구축하기 (캡스톤)
+
+## 해야 할 일
+
+이 프로젝트는 캡스톤(capstone) 프로젝트입니다. 앞선 다섯 개의 프로젝트에서 학습한 모든 것을 조립하고, 전체 벤치마크(benchmark)를 실행한 다음, 품질이 유지 가능한지 확인하기 위해 정리 과정(cleanup pass)을 수행합니다.
+
+완전한 제품 슬라이스(product slice)를 포괄하는 고정된 멀티 기능 작업 세트를 사용합니다. 문서 임포트, 인덱싱, 인용 기반 Q&A, 런타임 관찰 가능성, 그리고 가독성 있고 재시작 가능한 저장소 상태가 포함됩니다. 먼저 약한 해네스 베이스라인으로 실행하고, 이어서 가장 강력한 해네스로 실행한 다음, 정리 후 재실행합니다. 마지막으로 해네스 절제 실험(harness ablation experiment)을 수행합니다. 구성 요소를 하나씩 제거하면서 실제로 어떤 요소가 중요한지 확인합니다.
+
+앞선 프로젝트들에서 개별적으로 효과를 확인한 메커니즘들이 함께 작동할 때 어떤 시너지를 만들어 내는지, 그리고 어떤 구성 요소를 제거했을 때 품질이 가장 크게 저하되는지 파악하는 것이 이 캡스톤의 핵심입니다.
+
+## 도구
+
+- Claude Code 또는 Codex
+- Git
+- Node.js + Electron
+- 품질 문서 템플릿(quality document template)
+- 평가자 루브릭(evaluator rubric)
+- 앞선 다섯 개의 프로젝트에서 축적된 모든 해네스 구성 요소
+
+## 해네스 메커니즘
+
+완전한 해네스: 모든 메커니즘 + 관찰 가능성 + 절제 연구(ablation study)
diff --git a/docs/ko/resources/index.md b/docs/ko/resources/index.md
new file mode 100644
index 0000000..e3642e0
--- /dev/null
+++ b/docs/ko/resources/index.md
@@ -0,0 +1,50 @@
+# 한국어 리소스 라이브러리 (Resource Library)
+
+이 폴더는 강의에서 소개한 메서드(method)를 실제 저장소에 바로 복사해 사용할 수 있는 템플릿(template)과 간결한 참고 자료로 구체화한 것입니다. 에이전트(agent)가 여러 세션에 걸쳐 일관성 있게 작동하려면 별도의 설정·상태·범위를 매번 재도출하는 대신, 이 자료들을 기반으로 삼아야 합니다.
+
+## 언제 사용하는가
+
+Codex, Claude Code 또는 다른 코딩 에이전트가 여러 세션에 걸쳐 작업할 때 시작점으로 활용하십시오.
+
+특히 다음 상황에서 유용합니다.
+
+- 작업이 여러 세션에 걸쳐 진행될 때
+- 기능(feature)이 많아 반쯤 완성된 채 방치되기 쉬울 때
+- 에이전트가 지나치게 일찍 완료를 선언하는 경향이 있을 때
+- 시작 단계를 매번 새로 발견해야 할 때
+
+## 시작하기
+
+최소 설정을 위해 먼저 다음 파일부터 시작하십시오.
+
+- 루트 지침: [`templates/AGENTS.md`](./templates/AGENTS.md) 또는 [`templates/CLAUDE.md`](./templates/CLAUDE.md)
+- 기능 상태: [`templates/feature_list.json`](./templates/feature_list.json)
+- 진행 로그: [`templates/claude-progress.md`](./templates/claude-progress.md)
+- 부트스트랩(bootstrap) 스크립트 참고: `docs/ko/resources/templates/init.sh`
+
+그다음 다음 파일을 추가하십시오.
+
+- 세션 핸드오프(session handoff): [`templates/session-handoff.md`](./templates/session-handoff.md)
+- 클린 상태(clean state) 체크리스트: [`templates/clean-state-checklist.md`](./templates/clean-state-checklist.md)
+- 평가자(evaluator) 루브릭(rubric): [`templates/evaluator-rubric.md`](./templates/evaluator-rubric.md)
+
+"Harness engineering" 포스트에 나오는 OpenAI 스타일의 완전한 저장소 구조를 원한다면 고급 팩을 사용하십시오.
+
+- [`openai-advanced/index.md`](./openai-advanced/index.md)
+
+## 라이브러리 구조
+
+- [`templates/`](./templates/index.md): 실제 저장소에 복사할 수 있는 템플릿
+- [`reference/`](./reference/index.md): 메서드 노트, 시작 흐름, 실패 유형 맵
+- [`openai-advanced/`](./openai-advanced/index.md): 고급 저장소 스켈레톤(skeleton), 시스템 오브 레코드(SoR) 문서, 에이전트 우선 거버넌스 템플릿
+
+## 권장 최소 팩
+
+- `AGENTS.md` 또는 `CLAUDE.md`
+- `feature_list.json`
+- `claude-progress.md`
+- `init.sh`
+
+이 네 파일만으로도 대부분의 에이전트 워크플로우를 눈에 띄게 안정화할 수 있습니다.
+
+저장소가 여러 도메인, 활성 계획(plan), 품질 점수, 안정성 정책을 갖춘 장기 시스템으로 발전하면, 최소 팩을 무리하게 늘리는 대신 [`openai-advanced/`](./openai-advanced/index.md) 팩으로 전환하십시오.
diff --git a/docs/ko/resources/openai-advanced/index.md b/docs/ko/resources/openai-advanced/index.md
new file mode 100644
index 0000000..d5e2fdd
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/index.md
@@ -0,0 +1,73 @@
+# OpenAI 고급 팩(Advanced Pack)
+
+이 폴더는 OpenAI의 "Harness engineering: leveraging Codex in an agent-first world" 문서에서 설명하는 보다 견고한 저장소(repository) 구조를 복사해서 바로 사용할 수 있는 스타터 파일로 패키징한 것입니다.
+
+기본적인 해네스(harness)가 더 이상 충분하지 않고 다음과 같은 것들이 필요할 때 이 팩을 사용하십시오.
+
+- 라우팅 스타일의 간결한 `AGENTS.md`
+- 저장소 내 지속형 시스템 오브 레코드(system-of-record) 문서
+- 활성 및 완료된 실행 계획(execution plan)
+- 명시적인 제품, 신뢰성(reliability), 보안(security), 프론트엔드 정책 파일
+- 제품 도메인과 아키텍처 계층별 품질 점수 관리
+- 에이전트(agent) 친화적 참고 자료 폴더
+- 아키텍처, 지식 포착(knowledge capture), 런타임 검증을 위한 표준 작업 절차(SOP)
+
+## 포함된 스타터 레이아웃
+
+[`repo-template/`](./repo-template/index.md) 아래에 있는 스타터 팩은 아래와 같은 구조를 반영합니다.
+
+```text
+AGENTS.md
+ARCHITECTURE.md
+docs/
+├── design-docs/
+│ ├── index.md
+│ └── core-beliefs.md
+├── exec-plans/
+│ ├── active/
+│ ├── completed/
+│ └── tech-debt-tracker.md
+├── generated/
+│ └── db-schema.md
+├── product-specs/
+│ ├── index.md
+│ └── new-user-onboarding.md
+├── references/
+│ ├── design-system-reference-llms.txt
+│ ├── nixpacks-llms.txt
+│ └── uv-llms.txt
+├── DESIGN.md
+├── FRONTEND.md
+├── PLANS.md
+├── PRODUCT_SENSE.md
+├── QUALITY_SCORE.md
+├── RELIABILITY.md
+└── SECURITY.md
+```
+
+## 도입 방법
+
+1. 저장소가 아직 작다면 최소 팩(minimal pack)부터 시작하십시오.
+2. 더 강한 구조가 필요해지면 [`repo-template/`](./repo-template/index.md)의 파일들을 자신의 저장소에 복사하십시오.
+3. `AGENTS.md`는 짧게 유지하십시오. 이 파일을 깊이 있는 문서들로의 라우터로 취급하되, 백과사전처럼 쓰지 마십시오.
+4. 품질·신뢰성·계획 문서는 별도의 정리 날을 따로 잡지 말고 일상적인 작업의 일부로 업데이트하십시오.
+5. 생성된 산출물(artifact)과 외부 참고 자료를 명시적으로 관리하여 에이전트가 채팅 기록에 의존하지 않고 찾을 수 있도록 하십시오.
+
+## SOP 라이브러리
+
+[`sops/`](./sops/index.md) 폴더는 원문 문서의 다이어그램을 단계별 운영 절차(표준 작업 절차, SOP)로 변환한 것입니다.
+
+- 계층형 도메인 아키텍처(layered domain architecture) 설정
+- 보이지 않는 지식을 저장소에 인코딩하기
+- 로컬 관측 가능성(observability) 스택과 피드백 루프(feedback loop) 워크플로우
+- UI 작업을 위한 Chrome DevTools 검증 루프(validation loop)
+
+## 설계 원칙
+
+- 짧은 진입점, 더 깊이 연결된 문서들
+- 시스템 오브 레코드로서의 저장소
+- 기계적 검사가 기억에 의존하는 규칙보다 낫다
+- 계획과 품질 이력은 코드 옆에 존재한다
+- 정리와 단순화는 일급(first-class) 책임이다
+
+이 팩은 의도적으로 견해가 담겨 있지만, 그럼에도 맹목적으로 복사하지 않고 자신의 프로젝트에 맞게 조정해서 사용해야 합니다.
diff --git a/docs/ko/resources/openai-advanced/repo-template/AGENTS.md b/docs/ko/resources/openai-advanced/repo-template/AGENTS.md
new file mode 100644
index 0000000..6f5dd02
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/repo-template/AGENTS.md
@@ -0,0 +1,55 @@
+# AGENTS.md
+
+이 저장소는 장기 실행 코딩 에이전트(coding agent) 작업에 최적화되어 있습니다. 이 파일은 짧게 유지하십시오. 이 파일을 시스템 오브 레코드(system-of-record) 문서들로의 라우팅 계층으로 사용하되, 거대한 지시 모음으로 만들지 마십시오.
+
+## 시작 워크플로우
+
+코드를 변경하기 전에:
+
+1. `pwd`로 저장소 루트를 확인한다.
+2. 현재 시스템 지도와 의존성 규칙을 파악하기 위해 `ARCHITECTURE.md`를 읽는다.
+3. 어떤 도메인 또는 계층이 가장 취약한지 확인하기 위해 `docs/QUALITY_SCORE.md`를 읽는다.
+4. `docs/PLANS.md`를 읽고, 현재 작업 중인 활성 실행 계획(active execution plan)을 연다.
+5. `docs/product-specs/`에서 관련 제품 명세(product spec)를 읽는다.
+6. 이 저장소의 표준 부트스트랩(bootstrap) 및 검증(verification) 경로를 실행한다.
+7. 기준 검증이 실패하면 범위를 추가하기 전에 기준을 먼저 복구한다.
+
+## 라우팅 지도
+
+- `ARCHITECTURE.md`: 도메인 지도, 계층 모델, 의존성 규칙
+- `docs/design-docs/index.md`: 설계 결정(design decision)과 핵심 신념
+- `docs/product-specs/index.md`: 현재 제품 동작과 인수 목표
+- `docs/PLANS.md`: 계획 라이프사이클과 실행 계획 정책
+- `docs/QUALITY_SCORE.md`: 제품 도메인 및 계층 건전성
+- `docs/RELIABILITY.md`: 런타임 신호, 벤치마크, 재시작 기대치
+- `docs/SECURITY.md`: 비밀(secret), 샌드박스, 데이터, 외부 행동 규칙
+- `docs/FRONTEND.md`: UI 제약, 디자인 시스템 규칙, 접근성(accessibility) 검사
+
+## 작업 계약
+
+- 한 번에 하나의 제한된 계획 또는 기능 슬라이스로 작업한다.
+- 코드 검사만으로 작업이 완료됐다고 표시하지 않는다. 실행 가능한 증거(evidence)가 필요하다.
+- 동작을 변경하면, 같은 세션 내에서 일치하는 제품·계획·신뢰성 문서를 업데이트한다.
+- 반복되는 리뷰 피드백이 있으면 채팅에서 재설명하는 대신 기계적인 규칙·검사·린터로 승격시킨다.
+- 생성된 자료는 `docs/generated/`에, 외부 참고 자료는 `docs/references/`에 보관한다.
+- 이 파일을 늘리는 것보다 작고 현재의 문서를 추가하는 것을 선호한다.
+
+## 완료 정의
+
+다음 모든 조건이 충족될 때만 변경이 완료된 것으로 간주한다.
+
+- 목표 동작이 구현되었다
+- 필요한 검증이 실제로 실행되었다
+- 증거가 관련 계획 또는 품질 문서에서 연결되어 있다
+- 영향받는 문서가 현재 상태를 유지한다
+- 저장소가 표준 시작 경로에서 깔끔하게 재시작될 수 있다
+
+## 세션 종료
+
+세션을 종료하기 전에:
+
+1. 활성 실행 계획을 업데이트한다.
+2. 도메인 또는 계층이 의미 있게 변경된 경우 `docs/QUALITY_SCORE.md`를 업데이트한다.
+3. 미뤄진 사항이 있으면 `docs/exec-plans/tech-debt-tracker.md`에 새 기술 부채(tech debt)를 기록한다.
+4. 완료된 계획은 적절한 시점에 `docs/exec-plans/completed/`로 이동한다.
+5. 명확한 다음 행동이 있는 재시작 가능한 상태로 저장소를 남긴다.
diff --git a/docs/ko/resources/openai-advanced/repo-template/ARCHITECTURE.md b/docs/ko/resources/openai-advanced/repo-template/ARCHITECTURE.md
new file mode 100644
index 0000000..0f45ea2
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/repo-template/ARCHITECTURE.md
@@ -0,0 +1,57 @@
+# ARCHITECTURE.md
+
+이 파일은 시스템의 최상위 지도입니다. 간결하게 유지하고 필요할 때 더 깊은 문서를 가리키도록 합니다.
+
+아키텍처 문서는 에이전트(agent)가 코드를 변경하기 전에 읽어야 할 시스템 지도 역할을 합니다. 도메인 경계, 계층 모델, 의존성 규칙을 한 곳에 명시함으로써 에이전트가 아드혹(ad-hoc) 아키텍처를 만들지 않도록 방지합니다.
+
+## 시스템 형태
+
+- 제품: `[제품명으로 교체]`
+- 주요 사용자 워크플로우: `[주요 워크플로우로 교체]`
+- 런타임 표면: `[desktop / web / cli / services / workers]`
+- 제품 동작의 진실 원천(source of truth): `docs/product-specs/`
+
+## 도메인 지도
+
+| 도메인 | 목적 | 주요 진입점 | 관련 명세 |
+|--------|------|------------|-----------|
+| `[domain-a]` | `[소유하는 것]` | `[모듈 / 라우트 / 명령어]` | `[명세 경로]` |
+| `[domain-b]` | `[소유하는 것]` | `[모듈 / 라우트 / 명령어]` | `[명세 경로]` |
+
+## 계층 모델
+
+에이전트가 즉흥적인 아키텍처를 발명하지 않도록 고정된 방향성 모델을 사용한다.
+
+`Types -> Config -> Repo -> Service -> Runtime -> UI`
+
+횡단 관심사(cross-cutting concern)는 계층을 직접 가로지르는 대신 명시적인 공급자(provider) 또는 어댑터(adapter) 경계를 통해 진입해야 합니다.
+
+## 의존성 하드 규칙
+
+- 하위 계층은 상위 계층에 의존해서는 안 된다.
+- UI는 런타임 또는 서비스 계약을 우회해서는 안 된다.
+- 데이터 접근은 저장소(repository) 또는 동등한 어댑터를 통해 진입해야 한다.
+- 공유 유틸리티는 범용으로 유지하며 도메인 로직을 축적해서는 안 된다.
+- 새로운 의존성은 일치하는 계획 또는 설계 문서에서 정당화되어야 한다.
+
+## 횡단 관심사 인터페이스
+
+| 관심사 | 승인된 경계 | 비고 |
+|--------|------------|------|
+| 로깅 및 트레이싱 | `[공급자 / 유틸리티 경로]` | `[구조화만 허용, 임의 콘솔 사용 금지]` |
+| 인증(Auth) | `[공급자 경로]` | `[토큰/세션 규칙]` |
+| 외부 API | `[클라이언트 또는 공급자 경로]` | `[속도 제한 / 재시도 지침]` |
+| 기능 플래그 | `[플래그 경계]` | `[소유권]` |
+
+## 현재 핫스팟
+
+- `[에이전트가 안전하게 변경하기 가장 어려운 영역]`
+- `[경계가 약하거나 테스트가 취약한 영역]`
+
+## 변경 체크리스트
+
+아키텍처 관련 코드를 수정할 때:
+
+1. 도메인 지도 또는 허용된 경계가 변경된 경우 이 파일을 업데이트한다.
+2. 근거가 변경된 경우 `docs/design-docs/`의 관련 설계 문서(design doc)를 업데이트한다.
+3. 규칙이 기계적으로 강제되어야 한다면 실행 가능한 검사를 추가하거나 업데이트한다.
diff --git a/docs/ko/resources/openai-advanced/repo-template/docs/DESIGN.md b/docs/ko/resources/openai-advanced/repo-template/docs/DESIGN.md
new file mode 100644
index 0000000..2eaa42c
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/repo-template/docs/DESIGN.md
@@ -0,0 +1,27 @@
+# DESIGN.md
+
+이 파일은 설계 진입점(design entrypoint)입니다. 간결하게 유지하고 `docs/design-docs/` 아래의 더 상세한 파일들로 라우팅하는 데 사용하십시오.
+
+## 목적
+
+단일 채팅, 스프린트, 또는 리뷰어의 기억을 넘어 지속되어야 할 내구적인 제품 및 시스템 설계 결정을 기록합니다.
+
+설계 문서(design doc)는 단순한 코드 주석이나 PR 설명과 달리, 결정이 내려진 이유와 맥락을 장기적으로 보존하여 미래의 에이전트(agent)와 인간이 동일한 실수를 반복하지 않도록 돕습니다.
+
+## 읽어야 할 때
+
+- 현재 설계 철학이 필요할 때
+- 새로운 패턴을 도입하려 할 때
+- 어떤 설계 결정이 확정되었고 어떤 것이 아직 열려 있는지 알아야 할 때
+
+## 규범적 설계 문서
+
+- `docs/design-docs/index.md`: 수락됨, 제안됨, 폐기됨 상태의 문서 색인
+- `docs/design-docs/core-beliefs.md`: 프로젝트 전반에 걸친 에이전트 우선(agent-first) 신념
+
+## 설계 규칙
+
+- 설계 문서는 작고 현재 상태를 유지한다.
+- 결정 영역당 하나의 문서를 선호한다.
+- 변경이 설계 문서에 의존할 때 계획과 명세에서 설계 문서를 연결한다.
+- 설계 규칙이 운영적으로 중요해지면 자동화된 검사로 승격하거나 `ARCHITECTURE.md`를 업데이트한다.
diff --git a/docs/ko/resources/openai-advanced/repo-template/docs/FRONTEND.md b/docs/ko/resources/openai-advanced/repo-template/docs/FRONTEND.md
new file mode 100644
index 0000000..f33b09f
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/repo-template/docs/FRONTEND.md
@@ -0,0 +1,25 @@
+# FRONTEND.md
+
+이 파일은 안정적인 프론트엔드 기대치를 정의하여 에이전트(agent)가 예측 불가능하게 UI 패턴을 발명하지 않도록 합니다.
+
+프론트엔드 정책 문서는 에이전트가 UI 작업 중 임의의 패턴을 선택하지 않도록, 디자인 시스템 규칙·접근성(accessibility) 기준·검증 방식을 미리 명시하는 역할을 합니다.
+
+## UI 원칙
+
+- 참신함보다 명료함을 우선시한다.
+- 상호작용 흐름을 발견하기 쉽고 재시작 가능하게 유지한다.
+- 일회성 변형보다 소수의 재사용 가능한 컴포넌트를 선호한다.
+- 접근성 검사는 마무리 작업이 아닌 일반적인 검증의 일부이다.
+
+## 가드레일(Guardrail)
+
+- 디자인 시스템 또는 컴포넌트 라이브러리를 `docs/references/`에 문서화한다.
+- 주요 사용자 대면 상태를 기록한다: 빈 상태, 로딩, 성공, 오류, 재시도.
+- 복사 문구, 키보드 동작, 시각적 계층 구조를 흐름 전반에 걸쳐 일관되게 유지한다.
+- UI 버그를 수정할 때 일치하는 유효성 검사 단계를 추가하거나 업데이트한다.
+
+## 검증 기대치
+
+- 중요한 사용자 여정에 대한 증거를 캡처한다.
+- 관련 계획에 브라우저 또는 런타임 유효성 검사(validation) 단계를 기록한다.
+- 시각적 회귀(regression)가 잦으면 스크린샷 또는 DOM 검사를 표준화한다.
diff --git a/docs/ko/resources/openai-advanced/repo-template/docs/PLANS.md b/docs/ko/resources/openai-advanced/repo-template/docs/PLANS.md
new file mode 100644
index 0000000..57ef988
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/repo-template/docs/PLANS.md
@@ -0,0 +1,36 @@
+# PLANS.md
+
+이 파일은 실행 계획(execution plan)이 어떻게 생성·업데이트·완료·보관되는지를 정의합니다.
+
+실행 계획은 단일 세션을 초과하는 작업, 여러 하위 시스템에 걸친 변경, 또는 공개된 결정 사항이 있는 작업을 구조화된 방식으로 추적합니다. 계획을 저장소에 영속화함으로써 에이전트(agent)가 이전 컨텍스트(context) 없이도 작업을 이어받을 수 있습니다.
+
+## 계획이 필요한 경우
+
+다음에 해당할 때 실행 계획을 생성한다.
+
+- 하나 이상의 세션에 걸치는 작업
+- 하나 이상의 하위 시스템을 변경하는 작업
+- 중요하지 않은 검증 또는 배포 위험이 있는 작업
+- 기록되어야 할 미결 결정이 있는 작업
+
+## 계획 위치
+
+- `docs/exec-plans/active/`: 현재 작업을 이끄는 계획
+- `docs/exec-plans/completed/`: 향후 에이전트 컨텍스트를 위해 보관된 완료 계획
+- `docs/exec-plans/tech-debt-tracker.md`: 미뤄진 작업과 후속 조치
+
+## 최소 계획 섹션
+
+- 목표(objective)
+- 범위 및 범위 외(scope and out-of-scope)
+- 검증 경로(verification path)
+- 위험 및 차단 요소(risks and blockers)
+- 진행 로그(progress log)
+- 미결 결정(open decisions)
+
+## 운영 규칙
+
+- 하나의 활성 계획에는 현재 진행 중인 단계가 명확하게 하나 있어야 한다.
+- 작업이 진행되면 계획을 업데이트한다. 정적 산문으로 취급하지 않는다.
+- 결정이 구현 방향을 변경하면 계획에 기록한다.
+- 완료된 계획은 에이전트가 이전 컨텍스트를 계속 발견할 수 있도록 `completed/`로 이동한다.
diff --git a/docs/ko/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md b/docs/ko/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md
new file mode 100644
index 0000000..8ad0e1b
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md
@@ -0,0 +1,26 @@
+# PRODUCT_SENSE.md
+
+이 파일은 에이전트(agent)가 코드만으로는 신뢰할 수 있게 추론할 수 없는 지속적인 제품 판단을 담습니다.
+
+제품 감각(product sense) 문서는 단순한 기능 명세(feature spec)를 넘어, 팀이 어떤 종류의 결정을 어떤 우선순위로 내려야 하는지에 관한 횡단 관심사(cross-cutting) 원칙을 에이전트에게 제공합니다.
+
+## 제품 핵심
+
+- 주요 사용자: `[교체]`
+- 해야 할 일(job to be done): `[교체]`
+- 제거할 주요 불편함: `[교체]`
+- 인수 품질 기준: `[교체]`
+
+## 제품 규칙
+
+- 기능 수보다 사용자에게 보이는 신뢰성(reliability)을 우선시한다.
+- 모호한 동작은 추측할 권한이 아닌 명세 공백(spec gap)으로 취급한다.
+- 구현이 사용자가 보거나 신뢰하는 것을 변경하면 일치하는 명세를 업데이트한다.
+- 구체적인 흐름에는 제품 명세(product spec)를 사용하고, 횡단적인 제품 우선순위에는 이 파일을 사용한다.
+
+## 금지 패턴
+
+- 숨겨진 파괴적 행동
+- 사용자 피드백 없는 무음(無音) 실패
+- 가시적 상태에 대한 불명확한 진실 원천
+- 한 문장으로 설명할 수 없는 기능
diff --git a/docs/ko/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md b/docs/ko/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md
new file mode 100644
index 0000000..48fb784
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md
@@ -0,0 +1,41 @@
+# QUALITY_SCORE.md
+
+이 문서는 저장소가 시간이 지남에 따라 강해지고 있는지, 아니면 약해지고 있는지를 추적합니다.
+
+품질 점수(quality score)는 단순한 테스트 커버리지를 넘어, 에이전트 가독성·경계 강제·안정성 측면에서 각 도메인과 계층의 건전성을 주기적으로 평가하는 도구입니다. 이를 통해 부채가 쌓이기 전에 조기에 발견할 수 있습니다.
+
+## 등급 척도
+
+- `A`: 검증됨, 가독성 높음, 안정적, 경계 강제됨
+- `B`: 사소한 공백이 있지만 작동함
+- `C`: 부분적으로 작동함, 주목할 만한 혼란 또는 불안정
+- `D`: 고장남, 안전하지 않음, 또는 구조적으로 불명확함
+
+## 제품 도메인
+
+| 도메인 | 등급 | 검증 | 에이전트 가독성 | 테스트 안정성 | 주요 공백 | 최종 업데이트 |
+|--------|------|------|--------------|------------|---------|------------|
+| `[domain-a]` | - | - | - | - | - | - |
+| `[domain-b]` | - | - | - | - | - | - |
+| `[domain-c]` | - | - | - | - | - | - |
+
+## 아키텍처 계층
+
+| 계층 | 등급 | 경계 강제 | 에이전트 가독성 | 주요 공백 | 최종 업데이트 |
+|------|------|----------|--------------|---------|------------|
+| Types | - | - | - | - | - |
+| Services | - | - | - | - | - |
+| Runtime | - | - | - | - | - |
+| UI | - | - | - | - | - |
+
+## 벤치마크 스냅샷
+
+| 날짜 | 해네스 변형 | 완료율 | 재시도 | 리뷰 전 결함 | 비고 |
+|------|------------|-------|-------|------------|------|
+| YYYY-MM-DD | `[baseline / improved / simplified]` | - | - | - | - |
+
+## 단순화 로그
+
+| 날짜 | 제거된 컴포넌트 | 결과 | 결정 |
+|------|--------------|------|------|
+| YYYY-MM-DD | `[컴포넌트]` | `[degraded / unchanged]` | `[restore / keep removed]` |
diff --git a/docs/ko/resources/openai-advanced/repo-template/docs/RELIABILITY.md b/docs/ko/resources/openai-advanced/repo-template/docs/RELIABILITY.md
new file mode 100644
index 0000000..fff0090
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/repo-template/docs/RELIABILITY.md
@@ -0,0 +1,34 @@
+# RELIABILITY.md
+
+이 파일은 시스템이 어떻게 건강하고 재시작 가능함을 증명하는지를 정의합니다.
+
+신뢰성(reliability) 문서는 에이전트(agent)가 기능 구현 후 시스템이 깨끗하게 재시작될 수 있는지, 그리고 런타임 실패가 진단 가능한지를 확인하는 데 필요한 경로와 신호를 제공합니다. 신뢰성을 가드레일로 정의함으로써 기능 추가 시 시스템 안정성이 묵시적으로 저하되는 것을 방지합니다.
+
+## 표준 경로
+
+- 부트스트랩(Bootstrap): `[명령어]`
+- 검증(Verification): `[명령어]`
+- 앱 또는 서비스 시작: `[명령어]`
+- 런타임 디버그 또는 검사: `[명령어]`
+
+## 필수 런타임 신호
+
+- 시작 및 중요 흐름에 대한 구조화된 로그
+- 주요 서비스에 대한 헬스 체크(health check)
+- 가능한 경우 느린 경로에 대한 트레이스 또는 타이밍 데이터
+- 복구 가능한 실패에 대한 사용자 가시적 오류 상태
+
+## 황금 여정(Golden Journey)
+
+- `[여정 1]`
+- `[여정 2]`
+- `[여정 3]`
+
+각 황금 여정에는 반복 가능한 검증 경로와 명확한 실패 신호가 있어야 합니다.
+
+## 신뢰성 규칙
+
+- 시스템이 이후에 깔끔하게 재시작될 수 없으면 어떤 기능도 완료된 것이 아니다.
+- 런타임 실패는 저장소 로컬 신호로 진단 가능해야 한다.
+- 반복되는 실패 모드가 나타나면 해당 모드에 대한 벤치마크 또는 가드레일을 추가한다.
+- 정리(cleanup)는 신뢰성의 일부이며 별도의 관심사가 아니다.
diff --git a/docs/ko/resources/openai-advanced/repo-template/docs/SECURITY.md b/docs/ko/resources/openai-advanced/repo-template/docs/SECURITY.md
new file mode 100644
index 0000000..2ba0e32
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/repo-template/docs/SECURITY.md
@@ -0,0 +1,29 @@
+# SECURITY.md
+
+이 파일은 에이전트(agent)가 추측해서는 안 되는 보안(security) 및 안전 규칙을 정의합니다.
+
+보안 정책을 저장소에 명시적으로 기록하면, 에이전트가 비밀 처리·외부 행동 승인·의존성 검토 등에서 임의의 선택을 하지 않고 정해진 경계 내에서 작동하게 됩니다.
+
+## 비밀(Secret) 및 자격 증명(Credential)
+
+- 소스 코드나 문서에 절대로 비밀을 하드코딩하지 않는다.
+- 승인된 비밀 로딩 경로를 여기에 문서화한다.
+- 토큰, API 키, 개인 데이터는 로그와 스크린샷에서 제거(redact)한다.
+
+## 신뢰할 수 없는 입력
+
+- 외부 콘텐츠는 검증될 때까지 신뢰할 수 없는 것으로 취급한다.
+- 허용된 가져오기(fetch) 또는 실행 경계를 여기에 기록한다.
+- 프롬프트 주입(prompt injection) 또는 명령어 주입(command injection) 위험이 있으면 가드레일(guardrail)을 문서화한다.
+
+## 외부 행동
+
+- 명시적 승인이 필요한 행동을 나열한다.
+- 에이전트가 기본적으로 실행해서는 안 되는 운영 또는 파괴적인 명령어를 기록한다.
+- 디버깅 및 검증을 위해 샌드박스 안전 워크플로우를 선호한다.
+
+## 의존성 및 리뷰 규칙
+
+- 새로운 의존성은 활성 계획에서 정당화가 필요하다.
+- 보안에 민감한 변경은 명시적인 검증 단계가 필요하다.
+- 반복되는 보안 리뷰 의견은 구전 지식이 아닌 검사로 전환해야 한다.
diff --git a/docs/ko/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md b/docs/ko/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md
new file mode 100644
index 0000000..18f0ad4
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md
@@ -0,0 +1,11 @@
+# 핵심 신념(Core Beliefs)
+
+이 문서는 프로젝트 전반에서 에이전트(agent)와 인간이 공유하는 에이전트 우선(agent-first) 운영 원칙을 정리한 것입니다. 개별 결정보다 상위에 있는 이 신념들은 모호한 상황에서 판단의 기준이 됩니다.
+
+- 저장소는 에이전트를 위한 시스템 오브 레코드(system-of-record)이다.
+- `AGENTS.md`는 라우터이지 백과사전이 아니다.
+- 검증 증거가 자신감보다 더 중요하다.
+- 많은 반쯤 완성된 작업보다 하나의 제한된 작업이 낫다.
+- 반복되는 사람의 피드백은 재사용 가능한 해네스(harness) 규칙이 되어야 한다.
+- 정리와 단순화는 출시의 일부이지 후처리가 아니다.
+- 에이전트가 저장소에서 사실을 발견할 수 없다면, 그 사실은 운영적으로 사용 불가능한 것으로 취급한다.
diff --git a/docs/ko/resources/openai-advanced/repo-template/docs/design-docs/index.md b/docs/ko/resources/openai-advanced/repo-template/docs/design-docs/index.md
new file mode 100644
index 0000000..749b491
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/repo-template/docs/design-docs/index.md
@@ -0,0 +1,23 @@
+# 설계 문서(Design Doc) 색인
+
+이 색인을 설계 이력의 발견 가능한 지도로 사용하십시오.
+
+설계 문서(design doc)는 단순한 구현 설명이 아니라 "왜 이 결정을 내렸는가"에 대한 근거를 담은 문서입니다. 상태(수락됨·제안됨·폐기됨)를 명시적으로 관리함으로써 에이전트(agent)가 유효한 결정과 낡은 결정을 구분할 수 있습니다.
+
+## 수락됨(Accepted)
+
+- `core-beliefs.md`: 에이전트 우선(agent-first) 운영 신념과 지속적인 프로젝트 규범
+
+## 제안됨(Proposed)
+
+- `[여기에 새 설계 문서 경로를 추가]`
+
+## 폐기됨(Deprecated)
+
+- `[대체 링크와 함께 오래되거나 대체된 설계 문서를 여기로 이동]`
+
+## 유지보수 규칙
+
+- 모든 설계 문서에는 소유자 또는 업데이트 트리거가 있어야 한다.
+- 오래된 문서는 폐기 처리하거나 삭제하되, 그냥 방치하지 않는다.
+- 활성 실행 계획(execution plan)을 그것이 의존하는 설계 문서에 연결한다.
diff --git a/docs/ko/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md b/docs/ko/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md
new file mode 100644
index 0000000..ec00d8c
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md
@@ -0,0 +1,11 @@
+# 활성 계획(Active Plans)
+
+이 폴더에 활성 실행 계획(active execution plan)을 마크다운 파일 형식으로 하나씩 보관하십시오.
+
+활성 계획이란 현재 진행 중인 작업을 이끄는 계획으로, 새 에이전트(agent) 세션이 저장소만으로도 작업을 재개할 수 있을 만큼 충분히 최신 상태를 유지해야 합니다.
+
+권장 파일명 패턴:
+
+- `YYYY-MM-DD-short-topic.md`
+
+각 활성 계획은 새로운 에이전트 세션이 저장소만으로 작업을 재개할 수 있을 만큼 충분히 최신 상태를 유지해야 합니다.
diff --git a/docs/ko/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md b/docs/ko/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md
new file mode 100644
index 0000000..12d7f1a
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md
@@ -0,0 +1,5 @@
+# 완료된 계획(Completed Plans)
+
+완료된 계획은 삭제하지 말고 이 폴더로 이동하십시오. 완료된 계획은 저장소 메모리 표면의 일부로, 이후 에이전트(agent) 실행 시 코드가 현재와 같은 형태가 된 이유를 이해하는 데 도움이 됩니다.
+
+완료된 계획을 보존함으로써 미래의 에이전트는 과거에 내린 결정의 맥락과 근거를 추적할 수 있으며, 동일한 문제에 대해 이미 검토된 접근 방식을 재탐색하는 낭비를 줄일 수 있습니다.
diff --git a/docs/ko/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md b/docs/ko/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md
new file mode 100644
index 0000000..111b05e
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md
@@ -0,0 +1,9 @@
+# 기술 부채 추적기(Tech Debt Tracker)
+
+실제로 존재하고, 인지되어 있으며, 의도적으로 미뤄진 기술 부채(tech debt)에 이 파일을 사용하십시오.
+
+기술 부채란 더 나은 방법이 있음을 알면서도 시간·리스크·우선순위 등의 이유로 의도적으로 선택한 차선책입니다. 이를 명시적으로 추적함으로써 에이전트(agent)와 팀 구성원이 어떤 영역이 개선이 필요한지, 그 이유는 무엇인지를 한눈에 파악할 수 있습니다.
+
+| 날짜 | 영역 | 부채 | 미룬 이유 | 위험 | 다음 트리거 |
+|------|------|------|----------|------|------------|
+| YYYY-MM-DD | `[area]` | `[debt]` | `[reason]` | `[risk]` | `[when to revisit]` |
diff --git a/docs/ko/resources/openai-advanced/repo-template/docs/generated/db-schema.md b/docs/ko/resources/openai-advanced/repo-template/docs/generated/db-schema.md
new file mode 100644
index 0000000..e59fe5e
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/repo-template/docs/generated/db-schema.md
@@ -0,0 +1,15 @@
+# 데이터베이스 스키마(Database Schema)
+
+이 폴더는 에이전트(agent)가 코드를 역공학(reverse-engineering)하지 않고도 검사할 수 있도록 생성(generated)되거나 파생된 산출물(artifact)을 보관하는 데 사용하십시오.
+
+생성된 산출물을 저장소에 명시적으로 보관하면, 에이전트가 원본 코드를 분석하지 않고도 현재 스키마나 파생 데이터를 즉시 참조할 수 있어 컨텍스트(context) 소비를 줄이고 분석 속도를 높입니다.
+
+## 출처
+
+- 생성 위치: `[명령어 또는 소스 경로]`
+- 마지막 갱신: `YYYY-MM-DD`
+
+## 비고
+
+- 생성된 섹션을 직접 수동으로 편집하지 마십시오.
+- 기반 스키마가 변경되면 이 파일을 재생성하십시오.
diff --git a/docs/ko/resources/openai-advanced/repo-template/docs/product-specs/index.md b/docs/ko/resources/openai-advanced/repo-template/docs/product-specs/index.md
new file mode 100644
index 0000000..d44ad94
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/repo-template/docs/product-specs/index.md
@@ -0,0 +1,15 @@
+# 제품 명세(Product Specs) 색인
+
+현재 사용자 대면 동작 명세에 이 폴더를 사용하십시오.
+
+제품 명세(product spec)는 기능의 사용자 가시적 동작과 인수 기준(acceptance criteria)을 정의합니다. 에이전트(agent)가 명세를 참조함으로써 구현이 제품 의도에서 벗어나는 것을 방지합니다.
+
+## 활성 명세
+
+- `new-user-onboarding.md`
+
+## 규칙
+
+- 명세는 사용자 가시적 동작과 인수 기준을 설명해야 한다.
+- 구현이 명세에서 벗어나면 같은 세션에서 둘 중 하나를 업데이트한다.
+- 새로운 에이전트가 제품 범위를 빠르게 파악할 수 있도록 이 색인을 최신 상태로 유지한다.
diff --git a/docs/ko/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md b/docs/ko/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md
new file mode 100644
index 0000000..648f9dc
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md
@@ -0,0 +1,28 @@
+# 신규 사용자 온보딩(New User Onboarding)
+
+## 목표
+
+신규 사용자가 처음 실행 시 어떤 경험을 해야 하는지를 설명합니다.
+
+온보딩(onboarding)은 새 사용자가 서비스를 처음 접할 때 거치는 진입 흐름입니다. 이 명세는 에이전트(agent)가 온보딩 흐름을 구현하거나 수정할 때 참조하는 단일 진실 원천(single source of truth)입니다.
+
+## 진입 조건
+
+- `[흐름이 시작되기 전 상태]`
+
+## 사용자 흐름
+
+1. `[첫 번째 단계]`
+2. `[두 번째 단계]`
+3. `[세 번째 단계]`
+
+## 인수 기준(Acceptance Criteria)
+
+- `[관찰 가능한 결과]`
+- `[관찰 가능한 결과]`
+- `[관찰 가능한 결과]`
+
+## 실패 상태
+
+- `[복구 가능한 오류와 사용자 피드백]`
+- `[차단된 상태와 대체 경로]`
diff --git a/docs/ko/resources/openai-advanced/repo-template/index.md b/docs/ko/resources/openai-advanced/repo-template/index.md
new file mode 100644
index 0000000..b351292
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/repo-template/index.md
@@ -0,0 +1,23 @@
+# 고급 저장소 템플릿(Advanced Repo Template)
+
+최소한의 해네스(harness)만으로는 부족하고, OpenAI 스타일의 에이전트 우선(agent-first) 문서 체계가 필요할 때 이 스타터를 실제 저장소에 복사하십시오.
+
+저장소 템플릿(repo template)이란 에이전트와 인간 모두가 프로젝트 컨텍스트를 빠르게 파악하고, 점진적으로 더 깊은 정보를 탐색할 수 있도록 구조화된 스타터 파일 모음입니다.
+
+## 복사 순서
+
+1. `AGENTS.md`와 `ARCHITECTURE.md`를 저장소 루트에 복사한다.
+2. 전체 `docs/` 트리를 복사한다.
+3. `docs/PRODUCT_SENSE.md`, `docs/QUALITY_SCORE.md`, `docs/RELIABILITY.md`를 가장 먼저 채운다.
+4. `docs/exec-plans/active/` 아래에 첫 번째 활성 계획(active plan)을 추가한다.
+5. 진입점 파일은 짧게 유지하고 세부 사항은 연결된 문서로 라우팅한다.
+
+## 이 템플릿이 최적화하는 것
+
+- 지속형 저장소 로컬 컨텍스트
+- 하나의 거대한 지시 파일 대신 점진적 공개(progressive disclosure)
+- 명시적인 계획 라이프사이클
+- 시간에 따른 품질 추적
+- 에이전트와 사람 모두 읽기 쉬운 경계
+
+여기 있는 모든 파일을 스타터로 취급하십시오. 실제로 사용하기 전에 플레이스홀더, 예시, 샘플 명령어를 실제 프로젝트 내용으로 교체하십시오.
diff --git a/docs/ko/resources/openai-advanced/sops/chrome-devtools-validation-loop.md b/docs/ko/resources/openai-advanced/sops/chrome-devtools-validation-loop.md
new file mode 100644
index 0000000..4231cb0
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/sops/chrome-devtools-validation-loop.md
@@ -0,0 +1,50 @@
+# SOP: Chrome DevTools 검증 루프(Validation Loop)
+
+UI 작업이 실제 런타임 상호작용에 의존하고, 코드 검사만으로는 부족하며 스크린샷·DOM 상태·콘솔 출력이 더 중요할 때 이 표준 작업 절차(SOP)를 사용하십시오.
+
+검증 루프(validation loop)란 특정 UI 여정(journey)이 깔끔하게 완료될 때까지 BEFORE/AFTER 상태를 반복적으로 비교하며 문제를 좁혀 나가는 디버그 사이클입니다.
+
+## 목표
+
+UI 유효성 검사(validation)를 에이전트(agent)가 여정이 깔끔해질 때까지 반복 실행할 수 있는 재현 가능한 상호작용 루프로 전환합니다.
+
+## 핵심 루프
+
+1. 대상 페이지 또는 앱 인스턴스를 선택한다.
+2. 오래된 콘솔 노이즈를 제거한다.
+3. BEFORE 상태를 캡처한다.
+4. UI 경로를 실행한다.
+5. 상호작용 중 런타임 이벤트를 관찰한다.
+6. AFTER 상태를 캡처한다.
+7. 수정 사항을 적용하고 필요하면 앱을 재시작한다.
+8. 여정이 깔끔해질 때까지 유효성 검사를 재실행한다.
+
+## 필요한 입력
+
+- 안정적인 시작 명령어
+- 재현 가능한 UI 여정
+- DOM, 콘솔, 또는 스크린샷을 스냅샷할 수 있는 수단
+- "깔끔함"의 기준이 되는 규칙
+
+## 실행 절차
+
+1. 활성 실행 계획(execution plan)에 대상 여정을 기록한다.
+2. 성공을 관찰 가능한 항목으로 정의한다: 텍스트 존재 여부, 버튼 활성화, 오류 제거, 콘솔 정상, 요청 성공.
+3. 상호작용 전 초기 상태를 스냅샷한다.
+4. 한 번에 정확히 하나의 경로만 실행한다.
+5. 런타임 이벤트, DOM 변화, 가시적 출력을 기록한다.
+6. 여정이 실패하면 가장 작은 책임 계층을 수정하고 재시작한다.
+7. 동일한 경로를 재실행하여 BEFORE/AFTER 증거를 비교한다.
+
+## 깔끔함 기준
+
+- 의도한 가시적 상태가 존재한다
+- 예기치 않은 오류가 없다
+- 콘솔 노이즈가 이해되거나 제거되었다
+- 동일한 경로를 재실행하면 동일한 결과가 나온다
+
+## 업데이트해야 할 저장소 산출물
+
+- 활성 실행 계획
+- `docs/RELIABILITY.md` — 해당 여정이 황금 경로(golden path)가 되는 경우
+- 가시적 동작이 변경된 경우 제품 명세(product spec)
diff --git a/docs/ko/resources/openai-advanced/sops/encode-knowledge-into-repo.md b/docs/ko/resources/openai-advanced/sops/encode-knowledge-into-repo.md
new file mode 100644
index 0000000..80ea175
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/sops/encode-knowledge-into-repo.md
@@ -0,0 +1,44 @@
+# SOP: 보이지 않는 지식을 저장소에 인코딩하기
+
+중요한 컨텍스트(context)가 여전히 Google Docs, 채팅 스레드, 티켓, 혹은 사람들의 머릿속에만 있을 때 이 표준 작업 절차(SOP)를 사용하십시오.
+
+에이전트(agent)에게 보이지 않는 지식이란 저장소 어디에도 기록되지 않아 새로운 세션에서는 발견할 수 없는 암묵지를 말합니다. 이를 저장소 로컬 파일로 옮기는 것이 시스템 오브 레코드(system-of-record)로서의 저장소 원칙의 핵심입니다.
+
+## 목표
+
+에이전트에게 보이지 않는 지식을 코드베이스에서 발견 가능하게 만들어, 새 세션이 이전 대화에 의존하지 않고 바로 작업할 수 있게 합니다.
+
+## 트리거 신호
+
+- 에이전트가 시스템 동작 방식을 계속 질문한다.
+- "우리가 Slack에서 결정했어요" 또는 "지난 주에 X가 말한 대로 해주세요"라는 말이 나온다.
+- 리뷰에서 저장소 내에 기록되지 않은 제품 또는 보안 규칙을 참조한다.
+- 새 세션이 이미 해결됐어야 할 탐색 작업을 반복한다.
+
+## 실행 절차
+
+1. 보이지 않는 지식 출처를 목록으로 작성한다: 문서, 채팅, 암묵적인 팀 규칙, 구두 결정.
+2. 각 출처에 대해 묻는다: 이것이 아키텍처, 제품 동작, 보안 정책, 신뢰성(reliability) 기대치, 계획 컨텍스트, 또는 참고 자료인가?
+3. 해당하는 저장소 산출물(artifact)에 인코딩한다:
+ - 아키텍처 -> `ARCHITECTURE.md`
+ - 제품 동작 -> `docs/product-specs/`
+ - 설계 근거 -> `docs/design-docs/`
+ - 실행 상태 -> `docs/exec-plans/`
+ - 반복적인 외부 참고 자료 -> `docs/references/`
+ - 품질 또는 신뢰성 기대치 -> `docs/QUALITY_SCORE.md` 또는 `docs/RELIABILITY.md`
+4. 모호한 서술을 운영 관점에서 유용한 표현으로 교체한다.
+5. 오래된 사본을 제거하거나 폐기(deprecate)하여 저장소가 하나의 발견 가능한 진실을 유지하도록 한다.
+
+## 올바른 인코딩 규칙
+
+- 문학적 완결성이 아닌 발견 가능성을 위해 작성한다.
+- 명확한 파일명을 가진 짧은 문서를 선호한다.
+- 관련 산출물들을 서로 연결한다.
+- 회의록이 아닌 지속적인 규칙을 저장한다.
+- 결정이 내려진 동일한 세션에서 저장소를 업데이트한다.
+
+## 완료 정의
+
+- 새로운 에이전트가 사람에게 묻지 않고 관련 규칙을 발견할 수 있다.
+- 동일한 사실이 여러 모순된 파일에 흩어져 있지 않다.
+- 새 산출물은 그것이 관장하는 코드 또는 워크플로우 가까이에 위치한다.
diff --git a/docs/ko/resources/openai-advanced/sops/index.md b/docs/ko/resources/openai-advanced/sops/index.md
new file mode 100644
index 0000000..abef97b
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/sops/index.md
@@ -0,0 +1,25 @@
+# OpenAI 고급 표준 작업 절차(SOP)
+
+이 표준 작업 절차(SOP, Standard Operating Procedure) 모음은 원문 문서의 운영 패턴을 직접 따르거나 응용할 수 있는 구체적인 실행 지침서(playbook)로 변환한 것입니다.
+
+SOP란 반복 가능한 작업을 일관되게 실행할 수 있도록 단계별로 정리한 절차 문서로, 팀의 암묵지를 명시적인 지식으로 전환하는 데 핵심 역할을 합니다.
+
+## 포함된 표준 작업 절차
+
+- [`layered-domain-architecture.md`](./layered-domain-architecture.md):
+ 명시적인 계층과 횡단 관심사(cross-cutting) 경계를 설정한다
+- [`encode-knowledge-into-repo.md`](./encode-knowledge-into-repo.md):
+ 채팅·문서·메모리에 있는 보이지 않는 지식을 저장소 로컬 파일로 옮긴다
+- [`observability-feedback-loop.md`](./observability-feedback-loop.md):
+ 에이전트에게 로그·메트릭·트레이스와 반복 가능한 디버그 루프를 제공한다
+- [`chrome-devtools-validation-loop.md`](./chrome-devtools-validation-loop.md):
+ 브라우저 자동화와 스냅샷을 활용하여 UI 동작을 깔끔해질 때까지 검증한다
+
+## 사용 방법
+
+1. 현재 병목 지점에 맞는 표준 작업 절차를 선택하십시오.
+2. 체크리스트를 사용하여 누락된 산출물이나 툴링을 갖추십시오.
+3. 결과로 나온 규칙들을 복사한 `repo-template/` 문서들에 인코딩하십시오.
+4. 반복되는 리뷰 의견은 검사·스크립트·가드레일(guardrail)로 전환하십시오.
+
+이 절차들을 맹목적으로 따르지 않아도 됩니다. 이것들은 해네스(harness)를 더 명료하고, 강제 가능하며, 반복 가능하게 만들기 위한 것입니다.
diff --git a/docs/ko/resources/openai-advanced/sops/layered-domain-architecture.md b/docs/ko/resources/openai-advanced/sops/layered-domain-architecture.md
new file mode 100644
index 0000000..553fede
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/sops/layered-domain-architecture.md
@@ -0,0 +1,49 @@
+# SOP: 계층형 도메인 아키텍처(Layered Domain Architecture)
+
+에이전트(agent)가 경계를 계속 위반하거나, 계층 간에 로직을 중복 작성하거나, 몇 번의 세션 후에 검토하기 어려운 코드를 생성할 때 이 표준 작업 절차(SOP)를 사용하십시오.
+
+계층형 아키텍처(layered architecture)란 코드베이스를 역할별 계층으로 분리하고, 각 계층 간의 의존성 방향을 명시적으로 정해 에이전트가 구조를 조용히 훼손하지 않고 빠르게 작업할 수 있게 하는 설계 원칙입니다.
+
+## 목표
+
+도메인 경계를 명시적으로 만들어 에이전트가 구조를 조용히 훼손하지 않고 빠르게 이동할 수 있도록 합니다.
+
+## 목표 모델
+
+비즈니스 도메인 내에서는 다음과 같은 방향성 흐름을 선호하십시오.
+
+`Types -> Config -> Repo -> Service -> Runtime -> UI`
+
+횡단 관심사(cross-cutting concern)는 명시적인 공급자(provider) 또는 어댑터(adapter)를 통해 진입해야 합니다. 공유 유틸리티는 도메인 외부에 위치하며, 도메인 로직을 축적해서는 안 됩니다.
+
+## 설정 체크리스트
+
+- `ARCHITECTURE.md`에 현재 도메인들을 정의한다.
+- `ARCHITECTURE.md`에 허용된 의존성 방향을 기록한다.
+- auth, 텔레메트리(telemetry), 외부 API 등 횡단 관심사 인터페이스를 기록한다.
+- 현재 가장 문제가 되는 경계 위반에 대한 짧은 노트를 하나 추가한다.
+- 린트, 테스트, 또는 스크립트로 기계적으로 강제할 항목을 결정한다.
+
+## 실행 절차
+
+1. 구현 스타일에 손을 대기 전에 코드베이스를 도메인으로 매핑한다.
+2. 각 도메인에 대해 허용된 계층 시퀀스를 확인한다.
+3. 모든 횡단 관심사를 식별하고 공급자 또는 어댑터를 통해 라우팅한다.
+4. 애매한 공유 로직을 소유 도메인으로 이동하거나 진정한 범용 유틸리티로 분리한다.
+5. 규칙을 `ARCHITECTURE.md`에 문서화한다.
+6. 가장 비용이 큰 위반 사항에 대해 하나의 실행 가능한 가드레일(guardrail)을 추가한다.
+7. 변경 후 품질 점수를 업데이트한다.
+
+## 완료 정의
+
+- 새로운 에이전트가 어떤 계층이 변경을 소유하는지 파악할 수 있다.
+- UI 코드가 더 이상 저장소나 외부 사이드 이펙트에 직접 접근하지 않는다.
+- 횡단 관심사는 명명된 진입점을 갖는다.
+- 적어도 하나의 중요한 경계가 기계적으로 강제된다.
+
+## 업데이트해야 할 저장소 산출물
+
+- `ARCHITECTURE.md`
+- `docs/QUALITY_SCORE.md`
+- `docs/design-docs/` — 근거가 변경된 경우
+- `docs/PLANS.md` 또는 활성 실행 계획(execution plan)
diff --git a/docs/ko/resources/openai-advanced/sops/observability-feedback-loop.md b/docs/ko/resources/openai-advanced/sops/observability-feedback-loop.md
new file mode 100644
index 0000000..7eaf889
--- /dev/null
+++ b/docs/ko/resources/openai-advanced/sops/observability-feedback-loop.md
@@ -0,0 +1,43 @@
+# SOP: 관측 가능성 피드백 루프(Observability Feedback Loop)
+
+디버깅이 느리거나, 에이전트(agent)가 증거 없이 성공을 주장하거나, 런타임 동작이 코드 자체보다 파악하기 어려울 때 이 표준 작업 절차(SOP)를 사용하십시오.
+
+관측 가능성(observability)이란 로그, 메트릭, 트레이스와 같은 런타임 신호를 통해 시스템 내부 상태를 외부에서 추론할 수 있는 능력을 말합니다. 피드백 루프(feedback loop)는 이러한 신호를 에이전트가 코드 검사뿐 아니라 실행 결과로부터 추론할 수 있도록 반복 가능하게 구성한 것입니다.
+
+## 목표
+
+에이전트에게 로컬 피드백 루프를 제공하여 로그, 메트릭, 트레이스, 실행 가능한 워크로드를 통해 코드 검사만이 아닌 실행 결과로부터 추론할 수 있게 합니다.
+
+## 최소 스택
+
+- 애플리케이션이 구조화된 로그를 내보낸다
+- 애플리케이션이 가능한 경우 메트릭과 트레이스를 내보낸다
+- 로컬 팬아웃(fan-out) 또는 수집 계층
+- 로그, 메트릭, 트레이스에 대한 쿼리 인터페이스
+- 각 변경 후 재실행할 수 있는 반복 가능한 워크로드 또는 사용자 여정
+
+## 실행 절차
+
+1. 가장 중요한 황금 런타임 여정(golden runtime journey)을 정의한다.
+2. 시작 및 핵심 경로에 구조화된 로그를 추가한다.
+3. 유용한 경우 지연 시간, 실패 횟수, 큐 깊이에 대한 메트릭을 추가한다.
+4. 느리거나 여러 단계로 구성된 흐름에 트레이스 또는 타이밍 마커를 추가한다.
+5. 로컬 개발 환경에서 신호를 쿼리 가능하게 만든다.
+6. 에이전트에게 재실행할 반복 가능한 워크로드 또는 시나리오를 하나 제공한다.
+7. 루프를 강제한다: 쿼리 -> 상관 분석 -> 추론 -> 구현 -> 재시작 -> 재실행 -> 검증.
+
+## 디버그 세션 체크리스트
+
+- 무엇이 실패했는가?
+- 어떤 신호가 실패를 증명하는가?
+- 어떤 계층이 실패를 소유하는가?
+- 수정 후 무엇이 변경되었는가?
+- 앱이 깔끔하게 재시작되었는가?
+- 재실행 후 동일한 워크로드가 통과했는가?
+
+## 완료 정의
+
+- 에이전트가 런타임 증거로부터 실패 모드를 설명할 수 있다.
+- 각 변경 후 동일한 워크로드를 재실행할 수 있다.
+- 재시작과 재실행이 일반적인 작업 루프의 일부이다.
+- 신뢰성(reliability) 신호가 `docs/RELIABILITY.md`에 문서화되어 있다.
diff --git a/docs/ko/resources/reference/coding-agent-startup-flow.md b/docs/ko/resources/reference/coding-agent-startup-flow.md
new file mode 100644
index 0000000..4330e29
--- /dev/null
+++ b/docs/ko/resources/reference/coding-agent-startup-flow.md
@@ -0,0 +1,33 @@
+# 코딩 에이전트 시작 흐름 (Coding Agent Startup Flow)
+
+초기화(initialization)가 완료된 후 모든 세션 시작 시 이 흐름을 사용하십시오. 이 고정된 순서를 따르면 에이전트(agent)가 상태를 재발견하는 데 시간을 낭비하지 않고 즉시 작업에 집중할 수 있습니다.
+
+## 고정된 시작 템플릿 (Fixed Startup Template)
+
+1. `pwd`를 실행하여 저장소 루트를 확인합니다.
+2. `claude-progress.md`를 읽습니다.
+3. `feature_list.json`을 읽습니다.
+4. `git log --oneline -5`로 최근 커밋(commit)을 검토합니다.
+5. `./init.sh`를 실행합니다.
+6. 기준선(baseline) 스모크(smoke) 또는 엔드-투-엔드(end-to-end) 경로를 실행합니다.
+7. 기준선이 손상된 경우 먼저 수정합니다.
+8. 가장 높은 우선순위의 미완성 기능을 선택합니다.
+9. 검증이 완료되거나 명시적으로 차단될 때까지 그 기능만 작업합니다.
+
+## 이 순서가 중요한 이유 (Why This Order Matters)
+
+- `pwd`는 잘못된 디렉터리에서 실수로 작업하는 것을 방지합니다.
+- 진행 및 기능 파일은 새 편집이 시작되기 전에 지속적인 상태(durable state)를 복구합니다.
+- 최근 커밋(commit)은 가장 최근에 변경된 것을 설명합니다.
+- `init.sh`는 메모리에 의존하는 대신 시작을 표준화합니다.
+- 기준선(baseline) 검증은 새 작업이 이를 숨기기 전에 손상된 시작 상태를 잡아냅니다.
+
+## 세션 종료 미러 (End-Of-Session Mirror)
+
+같은 세션은 다음으로 종료되어야 합니다.
+
+1. 진행 상태 기록
+2. 기능 상태 업데이트
+3. 필요 시 핸드오프(handoff) 작성
+4. 안전한 작업 커밋(commit)
+5. 클린(clean)한 재시작 경로 유지
diff --git a/docs/ko/resources/reference/glossary.md b/docs/ko/resources/reference/glossary.md
new file mode 100644
index 0000000..d83d91c
--- /dev/null
+++ b/docs/ko/resources/reference/glossary.md
@@ -0,0 +1,120 @@
+---
+title: 한국어 용어집 (Glossary)
+description: Learn Harness Engineering 한국어판 전반에서 사용되는 핵심 용어의 한·영 대응표와 정의입니다.
+---
+
+# 한국어 용어집 (Glossary)
+
+이 문서는 한국어판 전체에서 일관된 번역어를 보장하기 위한 단일 진실 원천(Single Source of Truth)입니다. 각 강의·프로젝트·리소스 문서에서 처음 등장하는 전문 용어는 본 용어집의 표기를 따릅니다.
+
+## 표기 규칙 (Convention)
+
+- **첫 등장 형식**: 본문에서 처음 나오는 전문 용어는 `한국어(English)` 형태로 병기합니다. 예: `해네스(harness)`, `에이전트(agent)`.
+- **두 번째 이후**: 한국어만 사용하되, 문맥상 모호하면 다시 영어를 병기할 수 있습니다.
+- **고유명사·도구명**: `Claude Code`, `Codex`, `VitePress`, `GitHub Actions` 등은 영어 그대로 둡니다.
+- **시스템 토큰**: `BLOCKING`, `HARD`, `[CP]`, `@plan-writer`, `Skill("...")` 등 코드·프롬프트에서 의미를 갖는 토큰은 번역하지 않습니다.
+- **명령어·파일 경로**: `npm run docs:build`, `docs/.vitepress/config.mts` 등은 영어로 유지합니다.
+
+## 핵심 개념 (Core Concepts)
+
+| English | 한국어 | 정의 |
+|---------|--------|------|
+| Harness | 해네스 | AI 코딩 에이전트가 안정적으로 동작하도록 환경·상태·검증·제어를 묶어서 제공하는 외골격(스캐폴딩) 시스템. 본 강의의 중심 개념. |
+| Harness Engineering | 해네스 엔지니어링 | 해네스를 설계·구축·유지보수하는 공학적 실천 분야. |
+| Agent | 에이전트 | 자율적으로 작업을 수행하는 AI 소프트웨어 단위. 본 강의에서는 주로 코딩 에이전트(coding agent)를 가리킵니다. |
+| Coding Agent | 코딩 에이전트 | 코드 작성·리팩터·테스트 등 개발 작업을 수행하는 AI 에이전트. |
+| State | 상태 | 에이전트가 다음 행동을 결정할 때 참조하는 영속 데이터(작업 진행 로그, 기능 목록, git 히스토리, 체크리스트 등). |
+| Context | 컨텍스트 | 에이전트가 한 번의 추론에 사용하는 입력 정보의 집합. 모델의 컨텍스트 윈도(context window)에 담긴 내용. |
+| Context Window | 컨텍스트 윈도 | LLM이 한 번에 처리할 수 있는 토큰의 최대 길이. |
+| Repository as System of Record | 시스템 오브 레코드(SoR)로서의 저장소 | 작업 결과·결정·근거를 모두 git 저장소에 영속화하여 신뢰의 단일 원천으로 삼는 원칙. |
+
+## 작업·산출물 (Work and Deliverables)
+
+| English | 한국어 | 정의 |
+|---------|--------|------|
+| Deliverable | 산출물 | 작업의 결과로 만들어지는 파일·문서·코드 등 검증 가능한 실체. |
+| Specification | 명세 | 작업의 입력·동작·출력을 명확히 정의한 문서. `spec`로 줄여 쓰기도 합니다. |
+| Plan | 계획 | 명세를 만족시키기 위한 단계별 작업 순서와 책임 배분 문서. |
+| TODO Checklist | TODO 체크리스트 | 계획을 실행 가능한 단위 작업으로 분해한 체크박스 목록. |
+| Commit | 커밋 | git에서 변경 사항을 영속화하는 단위. |
+| Branch | 브랜치 | 독립적인 작업 흐름을 유지하기 위한 git 분기. |
+| Worktree | 워크트리 | 같은 저장소에서 여러 작업 흐름을 동시에 진행하기 위한 별도 작업 디렉터리. |
+| Pull Request (PR) | 풀 리퀘스트(PR) | 한 브랜치의 변경 사항을 다른 브랜치로 병합 요청하는 GitHub의 협업 단위. |
+
+## 검증과 품질 (Verification and Quality)
+
+| English | 한국어 | 정의 |
+|---------|--------|------|
+| Verification | 검증 | 산출물이 명세를 만족하는지 객관적 증거로 확인하는 절차. |
+| Validation | 유효성 검사 | 입력값이 제약을 만족하는지 확인하는 절차. 검증보다 좁은 의미. |
+| Critique | 비평(크리틱) | 계획·설계·산출물의 약점을 사전에 발견하기 위한 적대적(adversarial) 검토. |
+| Review | 리뷰 | 코드·문서를 동료 또는 에이전트가 읽고 피드백을 남기는 절차. |
+| Test | 테스트 | 코드의 동작을 자동으로 확인하는 검증 수단(단위·통합·E2E 등). |
+| TDD (Test-Driven Development) | 테스트 주도 개발 | RED→GREEN→IMPROVE 순서로 테스트를 먼저 쓴 뒤 구현하는 방식. |
+| Acceptance Criteria | 인수 기준 | 작업이 완료되었다고 인정받기 위해 만족해야 할 객관적 조건. |
+| Quality Gate | 품질 게이트 | 다음 단계로 진행하기 전에 통과해야 하는 자동·수동 검사 묶음. |
+| Lint | 린트 | 정적 분석으로 스타일·잠재적 오류를 검출하는 도구(예: `ruff`, `eslint`). |
+| Type Check | 타입 검사 | 정적 타입 시스템으로 타입 오류를 사전에 감지하는 절차(예: `pyright`, `tsc --noEmit`). |
+
+## 해네스 구성 요소 (Harness Components)
+
+| English | 한국어 | 정의 |
+|---------|--------|------|
+| Skill | 스킬 | 특정 작업 흐름을 묘사한 재사용 가능한 프롬프트 모듈. 에이전트가 필요할 때 로드합니다. |
+| Hook | 훅 | 에이전트의 라이프사이클(예: 도구 호출 전/후, 세션 시작) 시점에 실행되는 사용자 정의 스크립트. |
+| Rule | 규칙 | 에이전트가 항상 따라야 하는 정책·제약을 모아 둔 마크다운 문서. |
+| Subagent / Agent (role) | 서브에이전트 / 역할 에이전트 | 메인 세션이 위임할 수 있는 전문 역할(예: `@api-implement`, `@code-review`). |
+| Orchestration | 오케스트레이션 | 여러 에이전트·도구·검사를 정해진 순서로 묶어 실행하는 상위 흐름 제어. |
+| Permission | 권한 | 에이전트가 특정 도구·파일·명령을 사용할 수 있는지 제어하는 설정. |
+| Preflight | 사전 점검(프리플라이트) | 본 작업을 시작하기 전에 환경·전제 조건이 갖춰졌는지 확인하는 단계. |
+| Guardrail | 가드레일 | 에이전트가 위험한 행동을 하지 못하도록 막는 정책·검증 장치. |
+| Telemetry | 텔레메트리 | 에이전트 실행 중에 수집하는 측정 지표(이벤트 로그·지연 시간·실패율 등). |
+
+## 실패와 복구 (Failure and Recovery)
+
+| English | 한국어 | 정의 |
+|---------|--------|------|
+| Fail-loud | 실패-크게(fail-loud) | 오류가 발생하면 즉시 눈에 띄게 알리는 정책. 침묵 실패의 반대. |
+| Silent Failure | 무음(無音) 실패 | 오류가 났는데 아무런 신호 없이 다음 단계로 진행되는 현상. |
+| Continuity | 연속성 | 장시간 작업 중에도 컨텍스트·상태가 유지되어 끊기지 않는 성질. |
+| Handoff | 핸드오프 | 한 세션 또는 한 에이전트에서 다음 세션·에이전트로 작업을 인계하는 행위. |
+| Session Handoff | 세션 핸드오프 | 컨텍스트가 잘릴 위험이 있을 때 다음 세션이 이어 받을 수 있도록 상태를 영속화하는 패턴. |
+| Checkpoint | 체크포인트 | 복구 가능한 진행 지점에서 상태를 영속화한 시점. |
+| Rollback | 롤백 | 특정 시점으로 상태를 되돌리는 행위. |
+
+## 초기화와 컨벤션 (Initialization and Conventions)
+
+| English | 한국어 | 정의 |
+|---------|--------|------|
+| Initialization | 초기화 | 새 프로젝트나 작업 환경에서 해네스를 설정하는 단계. |
+| Onboarding | 온보딩 | 새 구성원(사람 또는 에이전트)이 프로젝트 컨벤션을 학습·적용하도록 돕는 절차. |
+| Convention | 컨벤션 | 팀이 합의한 명명·구조·작업 방식의 표준. |
+| Bootstrap | 부트스트랩 | 빈 상태에서 동작 가능한 최소 환경을 갖추는 일. |
+| Scaffold | 스캐폴딩 | 작업 시작점이 될 디렉터리·파일 구조를 미리 생성해 주는 도구·패턴. |
+
+## 도구 및 생태계 (Tools and Ecosystem)
+
+| English | 한국어(또는 그대로) | 비고 |
+|---------|---------------------|------|
+| Claude Code | Claude Code | 그대로 사용. Anthropic의 코딩 에이전트 CLI. |
+| Codex | Codex | 그대로 사용. OpenAI의 코딩 에이전트 CLI. |
+| Cursor | Cursor | 그대로 사용. AI 코드 에디터. |
+| VitePress | VitePress | 그대로 사용. 마크다운 기반 정적 사이트 생성기. |
+| MCP (Model Context Protocol) | MCP(모델 컨텍스트 프로토콜) | 에이전트가 외부 도구·리소스를 발견·호출하기 위한 표준. |
+| LSP (Language Server Protocol) | LSP(언어 서버 프로토콜) | 에디터와 언어 도구가 코드 정보를 주고받는 표준. |
+| GitHub Actions | GitHub Actions | 그대로 사용. GitHub의 CI/CD 시스템. |
+| LangGraph | LangGraph | 그대로 사용. 상태 그래프 기반 에이전트 프레임워크. |
+
+## 보존 토큰 (Untranslated Tokens)
+
+다음 토큰은 한국어판 본문에서도 절대 번역하지 않고 영어 그대로 유지합니다.
+
+- 시스템 의미 토큰: `BLOCKING`, `HARD`, `[CP]`, `RED`, `GREEN`, `IMPROVE`, `DONE`, `RETRY`, `BLOCKED`
+- 에이전트 식별자: `@plan-writer`, `@code-review`, `@doc-writer`, `@ui-implement` 등 모든 `@agent-name`
+- 스킬 호출: `Skill("omb-doc")`, `Skill("omb-tdd")` 등 모든 `Skill("...")` 형태
+- 파일 경로·명령어: `docs/.vitepress/config.mts`, `npm run docs:build`, `git commit -m "..."` 등
+- frontmatter 키: `title`, `description`, `layout` 등 `---` 블록 내부의 영어 키 이름
+
+## 향후 갱신 (Maintenance)
+
+강의 번역 중 새 용어가 발견되면 본 문서에 즉시 추가하고, 후속 강의 번역 시 갱신본을 입력으로 사용합니다(계획 Task #16b 참조).
diff --git a/docs/ko/resources/reference/index.md b/docs/ko/resources/reference/index.md
new file mode 100644
index 0000000..40ed3f7
--- /dev/null
+++ b/docs/ko/resources/reference/index.md
@@ -0,0 +1,17 @@
+# 한국어 참고 자료 (Reference)
+
+이 노트들은 템플릿(template) 모음을 단순한 파일 더미가 아닌 실제로 작동하는 해네스(harness)로 사용하는 방법을 설명합니다. 각 문서는 특정 실패 유형(failure mode)을 다루며, 함께 읽으면 안정적인 장기 에이전트(agent) 작업 환경을 구축하는 전체 그림을 파악할 수 있습니다.
+
+## 참고 노트 (Reference Notes)
+
+- [`method-map.md`](./method-map.md): 장기 실행 중 자주 발생하는 실패 유형을 해당 문제를 가장 먼저 해결하는 산출물(artifact) 또는 정책(policy)에 매핑합니다.
+- [`initializer-agent-playbook.md`](./initializer-agent-playbook.md): 기능 작업이 시작되기 전에 초기화 에이전트가 남겨야 할 것들.
+- [`coding-agent-startup-flow.md`](./coding-agent-startup-flow.md): 이후 코딩 세션을 위한 고정된 세션 시작 흐름.
+- [`prompt-calibration.md`](./prompt-calibration.md): 루트 지침을 비대하고 취약하게 만들지 않으면서 날카롭게 유지하는 방법.
+
+## 권장 읽기 순서 (Suggested Reading Order)
+
+1. `method-map.md`
+2. `initializer-agent-playbook.md`
+3. `coding-agent-startup-flow.md`
+4. `prompt-calibration.md`
diff --git a/docs/ko/resources/reference/initializer-agent-playbook.md b/docs/ko/resources/reference/initializer-agent-playbook.md
new file mode 100644
index 0000000..4eb8423
--- /dev/null
+++ b/docs/ko/resources/reference/initializer-agent-playbook.md
@@ -0,0 +1,35 @@
+# 초기화 에이전트 플레이북 (Initializer Agent Playbook)
+
+저장소에서 첫 번째 본격적인 세션, 즉 점진적인 기능 작업이 시작되기 전에 이 플레이북(playbook)을 사용하십시오. 초기화(initialization)는 이후 모든 세션이 안정적으로 작동할 수 있는 기반을 마련하는 단계입니다.
+
+## 목표 (Goal)
+
+이후 세션이 시작 명령, 현재 상태, 작업 경계를 재도출하지 않고도 동작을 구현할 수 있도록 안정적인 운영 환경(operating surface)을 만드는 것입니다.
+
+## 필수 산출물 (Required Outputs)
+
+초기화 에이전트(agent)는 최소한 다음 산출물을 남겨야 합니다.
+
+- `AGENTS.md` 또는 `CLAUDE.md` 와 같은 루트 지침 파일
+- `feature_list.json` 과 같은 기계 가독 기능 목록
+- `claude-progress.md` 와 같은 지속적인 진행 산출물
+- `init.sh` 와 같은 표준 시작 헬퍼(helper)
+- 기준선(baseline) 스캐폴드(scaffold)를 캡처하는 초기 안전 커밋(commit)
+
+## 체크리스트 (Checklist)
+
+1. 표준 시작 경로를 정의합니다.
+2. 표준 검증(verification) 경로를 정의합니다.
+3. 진행 로그(progress log)를 생성하고 시작 상태를 기록합니다.
+4. 작업을 상태(status)가 있는 명시적인 기능으로 분해합니다.
+5. 첫 번째 클린(clean) 기준선 커밋(commit)을 생성합니다.
+
+## 성공 테스트 (Success Test)
+
+이전 채팅 컨텍스트(context) 없는 새 세션이 다음 질문에 답할 수 있어야 합니다.
+
+- 이 저장소가 무엇을 하는지
+- 어떻게 시작하는지
+- 어떻게 검증(verify)하는지
+- 무엇이 미완성인지
+- 다음으로 최선의 행동은 무엇인지
diff --git a/docs/ko/resources/reference/method-map.md b/docs/ko/resources/reference/method-map.md
new file mode 100644
index 0000000..952841a
--- /dev/null
+++ b/docs/ko/resources/reference/method-map.md
@@ -0,0 +1,16 @@
+# 메서드 맵 (Method Map)
+
+이 표는 장기 코딩 에이전트(agent) 작업에서 자주 발생하는 실패 유형(failure mode)을, 보통 가장 먼저 이를 해결하는 산출물(artifact) 또는 운영 규칙(operating rule)에 매핑합니다. 새로운 문제를 발견했을 때 전역 지침 파일에 더 많은 텍스트를 덧붙이는 대신, 해당 실패 유형에 직접 대응하는 최소한의 산출물을 추가하는 원칙을 따릅니다.
+
+| 실패 유형 (Failure mode) | 실제 현상 (What it looks like in practice) | 주요 수정 방법 (Primary fix) | 보조 산출물 (Supporting artifact) |
+| --- | --- | --- | --- |
+| 콜드 스타트 혼란 (Cold-start confusion) | 새 세션이 대부분의 시간을 설정 및 상태를 재발견하는 데 사용함 | 저장소를 시스템 오브 레코드(system of record)로 만들기 | `claude-progress.md` |
+| 범위 확산 (Scope sprawl) | 에이전트가 여러 기능을 시작하지만 어느 것도 깔끔하게 마무리하지 못함 | 활성 범위 제한 | `feature_list.json` |
+| 섣부른 완료 선언 (Premature completion) | 에이전트가 코드 편집 후, 실행 가능한 증거(runnable proof) 없이 완료를 주장함 | 완료를 증거에 연결 | `clean-state-checklist.md` |
+| 취약한 시작 (Fragile startup) | 모든 세션이 프로젝트를 부팅하는 방법을 다시 배움 | 설정 및 검증 표준화 | `init.sh` |
+| 약한 핸드오프(Weak handoff) | 다음 세션이 무엇이 검증되었고, 손상되었고, 다음에 무엇을 할지 알 수 없음 | 명시적인 핸드오프(handoff)로 종료 | `session-handoff.md` |
+| 주관적 리뷰 (Subjective review) | 리뷰 품질이 취향이나 기억에 의존함 | 고정된 카테고리로 산출물 점수화 | `evaluator-rubric.md` |
+
+## 운영 원칙 (Operating Principle)
+
+관찰된 실패 유형(failure mode)을 직접 해결하는 최소한의 산출물을 추가하십시오. 하나의 전역 지침 파일에 더 많은 텍스트를 덤핑(dumping)하여 모든 신뢰성 문제를 해결하려 하지 마십시오.
diff --git a/docs/ko/resources/reference/prompt-calibration.md b/docs/ko/resources/reference/prompt-calibration.md
new file mode 100644
index 0000000..32c7b1a
--- /dev/null
+++ b/docs/ko/resources/reference/prompt-calibration.md
@@ -0,0 +1,23 @@
+# 프롬프트 보정 (Prompt Calibration)
+
+루트 지침(root instructions)은 가능한 모든 행동을 나열하는 것이 아니라 운영 프레임(operating frame)을 정의해야 합니다. 파일이 지나치게 커지면 에이전트(agent)가 중요한 정보를 찾기 어려워지고, 유지보수도 까다로워집니다.
+
+## 루트 파일에 유지할 내용 (Keep In The Root File)
+
+- 저장소 목적과 범위
+- 시작 경로(startup path)
+- 검증(verification) 경로
+- 타협 불가 제약(non-negotiable constraints)
+- 필수 상태 산출물(required state artifacts)
+- 세션 종료 규칙
+
+## 루트 파일에서 이동할 내용 (Move Out Of The Root File)
+
+- 오래된 히스토리(history) 엣지 케이스(edge cases)
+- 주제별 구현 세부 사항
+- 코드 근처에 있어야 할 로컬 아키텍처(architecture) 노트
+- 하나의 서브시스템(subsystem)에만 적용되는 예시
+
+## 작업 규칙 (Working Rule)
+
+루트 파일은 새 세션이 빠르게 방향을 잡도록 도와야 합니다. 파일이 과거 모든 실패 사례를 덤핑(dumping)하는 장소가 되고 있다면, 세부 내용을 더 작은 문서로 분리하고 대신 링크를 사용하십시오.
diff --git a/docs/ko/resources/templates/AGENTS.md b/docs/ko/resources/templates/AGENTS.md
new file mode 100644
index 0000000..c353455
--- /dev/null
+++ b/docs/ko/resources/templates/AGENTS.md
@@ -0,0 +1,52 @@
+# AGENTS.md
+
+이 파일은 해네스(harness) 리소스 라이브러리에 포함된 샘플 템플릿입니다. 실제 프로젝트에 복사한 뒤 프로젝트 고유의 명령어와 경로로 수정하여 사용하십시오. 에이전트(agent)가 세션을 시작할 때 가장 먼저 읽는 파일로, 안정적인 장기 작업의 토대를 제공합니다.
+
+이 저장소는 장기 코딩 에이전트 작업을 위해 설계되었습니다. 목표는 코드 산출물(output)을 극대화하는 것이 아닙니다. 목표는 다음 세션이 추측 없이 계속할 수 있도록 저장소를 남겨 두는 것입니다.
+
+## 시작 워크플로우 (Startup Workflow)
+
+코드를 작성하기 전에:
+
+1. `pwd`로 작업 디렉터리를 확인합니다.
+2. `claude-progress.md`를 읽어 최신 검증(verified) 상태와 다음 단계를 확인합니다.
+3. `feature_list.json`을 읽어 가장 높은 우선순위의 미완성 기능을 선택합니다.
+4. `git log --oneline -5`로 최근 커밋(commit)을 검토합니다.
+5. `./init.sh`를 실행합니다.
+6. 새 작업을 시작하기 전에 필요한 스모크(smoke) 또는 엔드-투-엔드(end-to-end) 검증을 실행합니다.
+
+기준선(baseline) 검증이 이미 실패 중인 경우, 먼저 이를 수정하십시오. 망가진 시작 상태 위에 새 기능 작업을 쌓지 마십시오.
+
+## 작업 규칙 (Working Rules)
+
+- 한 번에 하나의 기능만 작업합니다.
+- 코드가 추가되었다고 기능을 완료로 표시하지 않습니다.
+- 차단(blocker)이 좁은 지원 수정을 강제하지 않는 한, 선택한 기능 범위 내에서 변경 사항을 유지합니다.
+- 구현 중에 검증 규칙을 조용히 변경하지 않습니다.
+- 채팅 요약보다 지속적인 저장소 산출물(durable repo artifacts)을 선호합니다.
+
+## 필수 산출물 (Required Artifacts)
+
+- `feature_list.json`: 기능 상태의 단일 진실 원천(single source of truth)
+- `claude-progress.md`: 세션 로그 및 현재 검증 상태
+- `init.sh`: 표준 시작 및 검증 경로
+- `session-handoff.md`: 대규모 세션을 위한 선택적 간결 핸드오프(handoff)
+
+## 완료 정의 (Definition Of Done)
+
+다음 조건이 모두 충족될 때만 기능이 완료됩니다.
+
+- 목표 동작이 구현됨
+- 필요한 검증이 실제로 실행됨
+- 증거(evidence)가 `feature_list.json` 또는 `claude-progress.md`에 기록됨
+- 저장소가 표준 시작 경로에서 재시작 가능한 상태를 유지함
+
+## 세션 종료 (End Of Session)
+
+세션을 종료하기 전에:
+
+1. `claude-progress.md`를 업데이트합니다.
+2. `feature_list.json`을 업데이트합니다.
+3. 미해결된 위험 또는 차단 항목을 기록합니다.
+4. 작업이 안전한 상태가 되면 설명적인 메시지로 커밋합니다.
+5. 다음 세션이 즉시 `./init.sh`를 실행할 수 있도록 저장소를 충분히 클린(clean)한 상태로 남겨 둡니다.
diff --git a/docs/ko/resources/templates/CLAUDE.md b/docs/ko/resources/templates/CLAUDE.md
new file mode 100644
index 0000000..c8abf0f
--- /dev/null
+++ b/docs/ko/resources/templates/CLAUDE.md
@@ -0,0 +1,45 @@
+# CLAUDE.md
+
+이 파일은 해네스(harness) 리소스 라이브러리에 포함된 샘플 템플릿입니다. 실제 프로젝트에 복사한 뒤 프로젝트 고유의 명령어와 경로로 수정하여 사용하십시오. `AGENTS.md`와 구조는 동일하며 Claude Code의 지침 스타일에 맞게 형식화된 버전입니다.
+
+여러분은 장기 구현 작업을 위해 설계된 저장소에서 작업하고 있습니다. 속도보다 신뢰성 있는 완료, 세션 간 연속성(continuity), 명시적인 검증(verification)을 우선하십시오.
+
+## 운영 루프 (Operating Loop)
+
+모든 세션 시작 시:
+
+1. `pwd`를 실행하여 예상된 저장소 루트에 있는지 확인합니다.
+2. `claude-progress.md`를 읽습니다.
+3. `feature_list.json`을 읽습니다.
+4. `git log --oneline -5`로 최근 커밋(commit)을 검토합니다.
+5. `./init.sh`를 실행합니다.
+6. 기준선(baseline) 스모크(smoke) 또는 엔드-투-엔드(end-to-end) 경로가 이미 손상되었는지 확인합니다.
+
+그런 다음 미완성 기능 하나를 정확히 선택하고, 검증이 완료되거나 차단되었다고 명시적으로 문서화할 때까지 그 기능만 작업하십시오.
+
+## 규칙 (Rules)
+
+- 한 번에 하나의 활성 기능만.
+- 실행 가능한 증거(evidence) 없이 완료를 주장하지 않습니다.
+- 미완성 작업을 숨기기 위해 기능 목록을 재작성하지 않습니다.
+- 작업이 완료된 것처럼 보이게 하기 위해 테스트를 제거하거나 약화시키지 않습니다.
+- 시스템 오브 레코드(system of record)로서 저장소 산출물(repository artifacts)을 사용합니다.
+
+## 필수 파일 (Required Files)
+
+- `feature_list.json`
+- `claude-progress.md`
+- `init.sh`
+- `session-handoff.md` — 간결한 핸드오프(handoff)가 유용할 때
+
+## 완료 게이트 (Completion Gate)
+
+필요한 검증이 성공하고 결과가 기록된 후에만 기능을 `passing`으로 이동할 수 있습니다.
+
+## 중단하기 전에 (Before You Stop)
+
+1. 진행 로그(progress log)를 업데이트합니다.
+2. 기능 상태(feature state)를 업데이트합니다.
+3. 여전히 손상되거나 미검증된 것을 기록합니다.
+4. 저장소가 재개 가능한 상태가 되면 커밋합니다.
+5. 다음 세션을 위한 클린(clean)한 재시작 경로를 남겨 둡니다.
diff --git a/docs/ko/resources/templates/claude-progress.md b/docs/ko/resources/templates/claude-progress.md
new file mode 100644
index 0000000..2b824bd
--- /dev/null
+++ b/docs/ko/resources/templates/claude-progress.md
@@ -0,0 +1,37 @@
+# 진행 로그 (Progress Log)
+
+에이전트(agent)가 세션마다 이 파일에 기록하고, 새 세션은 이 파일을 가장 먼저 읽어 현재 상태와 다음 단계를 파악합니다. 이 파일은 프로젝트의 단일 진실 원천(single source of truth)입니다.
+
+## 현재 검증된 상태 (Current Verified State)
+
+- Repository root:
+- Standard startup path:
+- Standard verification path:
+- Current highest-priority unfinished feature:
+- Current blocker:
+
+## 세션 로그 (Session Log)
+
+### Session 001
+
+- Date:
+- Goal:
+- Completed:
+- Verification run:
+- Evidence captured:
+- Commits:
+- Files or artifacts updated:
+- Known risk or unresolved issue:
+- Next best step:
+
+### Session 002
+
+- Date:
+- Goal:
+- Completed:
+- Verification run:
+- Evidence captured:
+- Commits:
+- Files or artifacts updated:
+- Known risk or unresolved issue:
+- Next best step:
diff --git a/docs/ko/resources/templates/clean-state-checklist.md b/docs/ko/resources/templates/clean-state-checklist.md
new file mode 100644
index 0000000..6eb52f3
--- /dev/null
+++ b/docs/ko/resources/templates/clean-state-checklist.md
@@ -0,0 +1,10 @@
+# 클린 상태 체크리스트 (Clean State Checklist)
+
+세션 종료 전에 이 체크리스트를 실행하여 다음 세션이 깨끗한 클린 상태(clean state)에서 시작할 수 있도록 저장소를 정돈하십시오. 에이전트(agent)도 세션 종료 루틴의 일부로 이 항목들을 점검해야 합니다.
+
+- [ ] 표준 시작 경로가 여전히 작동합니다.
+- [ ] 표준 검증(verification) 경로가 여전히 실행됩니다.
+- [ ] 현재 진행 상태가 진행 로그(progress log)에 기록되어 있습니다.
+- [ ] 기능 상태가 실제로 통과(passing)된 것과 미검증된 것을 반영합니다.
+- [ ] 미완성 단계가 문서화되지 않은 채 남아 있지 않습니다.
+- [ ] 다음 세션이 수동 수정 없이 계속할 수 있습니다.
diff --git a/docs/ko/resources/templates/evaluator-rubric.md b/docs/ko/resources/templates/evaluator-rubric.md
new file mode 100644
index 0000000..0ccbee1
--- /dev/null
+++ b/docs/ko/resources/templates/evaluator-rubric.md
@@ -0,0 +1,24 @@
+# 평가자 루브릭 (Evaluator Rubric)
+
+구현 후, 최종 수락 전에 이 루브릭(rubric)을 사용하십시오. 에이전트(agent)는 자기 평가에 약한 경향이 있으므로, 이 점수표(scorecard)를 반복적으로 보정(calibration)하여 인간의 판단과 일치하도록 만들어야 합니다.
+
+| 범주 (Category) | 질문 (Question) | 점수 (0-2) | 비고 (Notes) |
+| --- | --- | --- | --- |
+| 정확성 (Correctness) | 구현된 동작이 요청된 기능과 일치하는가? | | |
+| 검증 (Verification) | 필요한 검사가 증거(evidence)와 함께 실제로 실행되었는가? | | |
+| 범위 규율 (Scope discipline) | 세션이 선택된 기능 범위 내에 머물렀는가? | | |
+| 신뢰성 (Reliability) | 결과가 재시작 또는 재실행 후에도 수정 없이 유지되는가? | | |
+| 유지보수성 (Maintainability) | 코드와 문서가 다음 세션에서 충분히 이해 가능한가? | | |
+| 핸드오프 준비성 (Handoff readiness) | 새 세션이 저장소 산출물(repo artifacts)만으로 작업을 계속할 수 있는가? | | |
+
+## 판정 (Verdict)
+
+- Accept
+- Revise
+- Block
+
+## 필수 후속 조치 (Required Follow-Up)
+
+- Missing evidence:
+- Required fixes:
+- Next review trigger:
diff --git a/docs/ko/resources/templates/index.md b/docs/ko/resources/templates/index.md
new file mode 100644
index 0000000..6b1fefc
--- /dev/null
+++ b/docs/ko/resources/templates/index.md
@@ -0,0 +1,226 @@
+# 템플릿 가이드 (Template Guide)
+
+이 템플릿들은 여러분의 프로젝트에 바로 복사해 사용할 수 있도록 준비된 것입니다. 각 파일은 에이전트(agent) 워크플로우의 특정 목적을 위해 설계되었습니다. 프로젝트의 명령어, 경로, 기능 이름, 검증 단계에 맞게 내용을 수정하십시오.
+
+## 시작 방법
+
+먼저 프로젝트 루트에 다음 네 파일을 복사하십시오.
+
+1. `AGENTS.md` 또는 `CLAUDE.md`
+2. `init.sh`
+3. `claude-progress.md`
+4. `feature_list.json`
+
+프로젝트가 성장함에 따라 나머지 파일도 추가하십시오.
+
+---
+
+## AGENTS.md
+
+루트 지침 파일입니다. 에이전트가 세션을 시작할 때 가장 먼저 읽는 파일로, 코드를 작성하기 전에 해야 할 일, 작업 방식, 마무리 방법 등 운영 규칙을 정의합니다.
+
+**사용 방법:**
+
+- 프로젝트 루트 디렉터리에 복사하십시오.
+- 시작 워크플로우 단계를 실제 프로젝트 경로와 명령어로 교체하십시오.
+- 팀의 컨벤션(convention)에 맞게 작업 규칙을 조정하십시오.
+- "완료 정의(Definition of Done)" 섹션은 가장 중요한 부분이므로 반드시 유지하십시오.
+
+**에이전트에게 제공하는 역할:**
+
+- 작업 시작 전에 진행 상태와 기능(feature) 상태를 먼저 읽도록 지시합니다.
+- 한 번에 하나의 기능만 작업하도록 강제합니다.
+- 완료 표시 전에 증거(evidence)를 요구합니다.
+- 세션 종료 시 저장소를 클린 상태(clean state)로 마무리하는 방법을 정의합니다.
+
+Codex 또는 다른 에이전트에는 `AGENTS.md`를 사용하십시오. Claude Code와 함께 작업하는 경우 `CLAUDE.md`를 사용하십시오. 구조는 동일하며 Claude의 지침 스타일에 맞게 형식화된 것입니다.
+
+## init.sh
+
+시작 스크립트입니다. 의존성 설치, 검증(verification), 시작 명령 출력을 한 번에 실행합니다.
+
+**사용 방법:**
+
+- 프로젝트 루트에 복사하십시오.
+- 상단의 다음 세 변수를 편집하십시오.
+ - `INSTALL_CMD` — 의존성 설치 명령 (예: `npm install`, `pip install -r requirements.txt`)
+ - `VERIFY_CMD` — 기본 검증 명령 (예: `npm test`, `pytest`)
+ - `START_CMD` — 개발 서버 시작 명령 (예: `npm run dev`)
+- 실행 권한을 부여하십시오: `chmod +x init.sh`
+
+**동작:**
+
+1. 현재 디렉터리를 출력합니다(올바른 위치에서 실행되고 있는지 확인).
+2. 의존성을 설치합니다.
+3. 검증 명령을 실행합니다.
+4. 시작 명령을 출력합니다(`RUN_START_COMMAND=1`이 설정된 경우 직접 실행).
+
+검증이 실패하면 에이전트는 다른 작업을 시작하기 전에 기준선(baseline)을 먼저 수정해야 합니다.
+
+## claude-progress.md
+
+진행 로그(progress log)입니다. 모든 세션은 이 파일에 기록하고, 새 세션은 이 파일을 가장 먼저 읽습니다.
+
+**사용 방법:**
+
+- 프로젝트 루트에 복사하십시오.
+- "현재 검증된 상태(Current Verified State)" 섹션을 프로젝트 정보로 채우십시오.
+- 각 세션 후에 세션 레코드를 업데이트하십시오.
+
+**각 필드의 의미:**
+
+- **현재 검증된 상태(Current Verified State)** — 프로젝트의 현재 상태를 나타내는 단일 진실 원천
+ - `Repository root directory` — 프로젝트 위치
+ - `Standard startup path` — 프로젝트를 실행하는 명령
+ - `Standard verification path` — 테스트 실행 명령
+ - `Highest priority unfinished feature` — 다음 세션에서 작업할 항목
+ - `Current blocker` — 막혀 있는 항목
+- **세션 레코드(Session Record)** — 세션당 하나의 항목
+ - `Goal` — 계획한 작업
+ - `Completed` — 실제로 완료된 것
+ - `Verification run` — 실행된 테스트
+ - `Evidence recorded` — 기록된 증거
+ - `Commits` — 커밋된 내용
+ - `Known risks` — 손상될 수 있는 것
+ - `Next best action` — 다음 세션의 시작점
+
+## feature_list.json
+
+기능 추적기(feature tracker)입니다. 에이전트가 구현해야 할 모든 기능 목록과 상태(status), 검증 단계, 증거를 기계 가독 형식으로 관리합니다.
+
+**사용 방법:**
+
+- 프로젝트 루트에 복사하십시오.
+- 예시 기능을 실제 기능으로 교체하십시오.
+- 각 기능에는 다음이 필요합니다.
+ - `id` — 짧은 고유 식별자
+ - `priority` — 정수, 낮을수록 높은 우선순위
+ - `area` — 앱의 어떤 부분인지 (예: "chat", "import", "search")
+ - `title` — 짧은 설명
+ - `user_visible_behavior` — 기능이 작동할 때 사용자가 보게 될 것
+ - `status` — `not_started`, `in_progress`, `blocked`, `passing` 중 하나
+ - `verification` — 작동 여부를 확인하는 단계별 지침
+ - `evidence` — 검증 통과를 기록한 증거 (에이전트가 채움)
+ - `notes` — 추가 맥락
+
+**상태(status) 규칙:**
+
+- `not_started` — 아직 작업하지 않음
+- `in_progress` — 현재 작업 중인 기능 (한 번에 하나만)
+- `blocked` — 문서화된 문제로 진행 불가
+- `passing` — 검증 통과 및 증거 기록됨
+
+에이전트는 한 번에 하나의 기능만 `in_progress` 상태여야 합니다.
+
+## session-handoff.md
+
+세션 간 간결한 핸드오프(handoff) 노트입니다. 세션이 종료되고 다음 세션이 빠르게 이어 받길 원할 때 사용하십시오.
+
+**사용 방법:**
+
+- 프로젝트 루트에 복사하십시오.
+- 각 세션 종료 시 채우십시오(에이전트가 채울 수도 있음).
+
+**각 섹션이 다루는 내용:**
+
+- **현재 검증된 것(Currently verified)** — 작동이 확인된 것과 실행된 검증
+- **이번 세션의 변경 사항(Changes this session)** — 변경된 코드 또는 인프라
+- **손상되거나 미검증된 것(Still broken or unverified)** — 알려진 문제와 위험 영역
+- **다음으로 최선의 행동(Next best action)** — 다음 세션에서 할 일과 건드리지 말아야 할 것
+- **명령어(Commands)** — 시작, 검증, 디버그 명령 참고용
+
+이 파일은 소규모 세션에서는 선택 사항입니다. 세션이 길거나 프로젝트에 여러 활성 영역이 있을 때 중요해집니다.
+
+## clean-state-checklist.md
+
+각 세션 종료 전에 실행할 체크리스트입니다. 다음 세션이 클린 상태(clean state)로 시작할 수 있도록 저장소가 좋은 상태인지 확인합니다.
+
+**사용 방법:**
+
+- 프로젝트 루트에 복사하십시오.
+- 세션을 닫기 전에 확인하십시오.
+- 에이전트도 세션 종료 루틴의 일부로 이 항목들을 점검해야 합니다.
+
+**확인 항목:**
+
+- 표준 시작 경로가 여전히 작동하는지
+- 표준 검증 경로가 여전히 실행되는지
+- 진행 로그가 업데이트되었는지
+- 기능 목록이 실제 상태를 반영하는지 (허위 `passing` 항목 없음)
+- 미완성 작업이 기록되지 않은 채 남아 있지 않은지
+- 다음 세션이 수동 수정 없이 계속할 수 있는지
+
+## evaluator-rubric.md
+
+에이전트 산출물(output) 품질을 검토하기 위한 점수표(scorecard)입니다. 세션 후 또는 프로젝트 마일스톤(milestone)에서 작업이 기준을 충족하는지 평가할 때 사용하십시오.
+
+**사용 방법:**
+
+- 프로젝트 루트에 복사하십시오.
+- 세션(또는 일련의 세션) 후 여섯 가지 차원에서 에이전트의 작업을 점수화하십시오.
+- 각 차원은 0-2점으로 채점합니다.
+
+**여섯 가지 차원:**
+
+1. **정확성(Correctness)** — 구현이 목표 동작과 일치하는가?
+2. **검증(Verification)** — 필요한 검사가 증거와 함께 실제로 실행되었는가?
+3. **범위 규율(Scope discipline)** — 에이전트가 선택한 기능 범위 안에 머물렀는가?
+4. **신뢰성(Reliability)** — 결과가 재시작 또는 재실행 후에도 유지되는가?
+5. **유지보수성(Maintainability)** — 코드와 문서가 다음 세션에서 충분히 이해 가능한가?
+6. **핸드오프 준비성(Handoff readiness)** — 새 세션이 저장소 산출물만으로 계속할 수 있는가?
+
+**결론 옵션:**
+
+- Accept — 기준 충족
+- Revise — 수락 전 수정 필요
+- Block — 먼저 해결해야 할 근본적인 문제 있음
+
+**중요: 평가자(evaluator)는 보정(calibration)이 필요합니다.** 기본 설정에서 에이전트는 자기 평가를 잘 하지 못합니다. 문제를 발견하고도 스스로 승인하는 방향으로 논리를 전개하는 경향이 있습니다. 다음과 같이 반복적으로 조정해야 합니다.
+
+1. 완료된 스프린트(sprint)에 평가자(evaluator)를 실행합니다.
+2. 점수를 여러분 자신의 인간적 판단과 비교합니다.
+3. 차이가 있는 곳에서 루브릭(rubric)의 합격/불합격 기준을 더 구체화합니다.
+4. 다시 실행하여 정렬 상태를 확인합니다.
+5. 평가자가 인간 리뷰와 일관되게 일치할 때까지 반복합니다.
+
+3-5회의 보정(calibration) 라운드를 예상하십시오. 각 변경 사항을 기록하여 무엇이 정렬을 개선했는지 추적할 수 있도록 하십시오.
+
+## quality-document.md
+
+프로젝트의 각 제품 도메인(domain)과 아키텍처(architecture) 레이어(layer)를 등급화하는 품질 스냅샷(snapshot)입니다. 개별 세션 산출물이 아닌 코드베이스(codebase) 전체의 건전성을 시간에 따라 추적합니다.
+
+**사용 방법:**
+
+- 프로젝트 루트에 복사하십시오.
+- 세션 시작 전: 코드베이스에서 가장 약한 부분을 파악하기 위해 읽으십시오.
+- 세션 후: 변경된 사항에 따라 등급을 업데이트하십시오.
+- 시간이 지남에 따라: 스냅샷을 비교하여 어떤 해네스(harness) 변경이 실제로 코드베이스 건전성을 개선했는지 확인하십시오.
+
+**등급화 항목:**
+
+- **제품 도메인(Product domains)** (예: 문서 가져오기, Q&A 흐름, 색인화): 각 도메인은 검증 상태, 에이전트 가독성(agent legibility), 테스트 안정성, 주요 격차에 대한 등급(A-D)을 받습니다.
+- **아키텍처 레이어(Architectural layers)** (예: 메인 프로세스, preload, renderer, services): 각 레이어는 경계 적용(boundary enforcement)과 에이전트 가독성에 대한 등급을 받습니다.
+
+**중요성:**
+
+평가자 루브릭은 개별 에이전트 산출물을 점수화합니다. 품질 문서는 코드베이스 자체를 점수화합니다. 두 문서는 서로 다른 질문에 답합니다.
+
+- 평가자 루브릭(evaluator rubric): "에이전트가 이번 세션에서 좋은 작업을 했는가?"
+- 품질 문서(quality document): "프로젝트가 시간이 지남에 따라 강해지고 있는가, 약해지고 있는가?"
+
+**업데이트 시점:**
+
+- 각 중요한 세션 후
+- 벤치마크(benchmark) 비교 전
+- 정리 또는 단순화 작업 후
+- 새 에이전트 또는 모델을 프로젝트에 온보딩(onboarding)할 때
+
+**해네스 단순화 연계:**
+
+품질 문서는 해네스(harness) 단순화도 지원합니다. 모든 해네스 구성 요소는 모델이 할 수 없는 것에 대한 가정을 내포합니다. 모델이 발전함에 따라 이러한 가정은 낡아집니다. 구성 요소가 여전히 필요한지 확인하려면 다음을 수행하십시오.
+
+1. 품질 문서 스냅샷(snapshot)을 찍습니다.
+2. 해네스 구성 요소 하나를 제거합니다.
+3. 벤치마크 작업 집합을 실행합니다.
+4. 또 다른 스냅샷을 찍습니다.
+5. 비교합니다. 등급이 하락하지 않았다면 해당 구성 요소는 오버헤드(overhead)였습니다. 하락했다면 복원합니다.
diff --git a/docs/ko/resources/templates/quality-document.md b/docs/ko/resources/templates/quality-document.md
new file mode 100644
index 0000000..b1428b9
--- /dev/null
+++ b/docs/ko/resources/templates/quality-document.md
@@ -0,0 +1,45 @@
+# 품질 문서 (Quality Document)
+
+각 제품 도메인(product domain)과 아키텍처(architecture) 레이어(layer)에 대한 품질 스냅샷(snapshot)입니다. 에이전트(agent)와 사람 모두 이 문서를 사용하여 코드베이스(codebase)에서 강한 부분과 보완이 필요한 부분을 빠르게 파악할 수 있습니다.
+
+이 문서는 개별 세션 산출물이 아닌 프로젝트 전체의 건전성을 시간에 따라 추적한다는 점에서 평가자 루브릭(evaluator rubric)과 구분됩니다.
+
+**업데이트 주기:** 각 중요한 세션 후, 또는 새 작업 단계 시작 전.
+
+**등급 기준:**
+
+- **A**: 모든 검증(verification) 통과, 클린(clean) 아키텍처, 에이전트 가독성(agent-legible), 안정적인 테스트
+- **B**: 검증 통과, 대체로 클린, 가독성 또는 테스트 커버리지에 사소한 격차 있음
+- **C**: 부분적으로 작동, 알려진 격차, 일부 코드 영역이 에이전트가 이해하기 어려움
+- **D**: 작동하지 않거나, 주요 구조적 문제 있음
+
+---
+
+## 제품 도메인 (Product Domains)
+
+| 도메인 (Domain) | 등급 (Grade) | 검증 (Verification) | 에이전트 가독성 (Agent Legibility) | 테스트 안정성 (Test Stability) | 주요 격차 (Key Gaps) | 마지막 업데이트 (Last Updated) |
+|--------|-------|-------------|-----------------|---------------|----------|-------------|
+| Document Import | - | - | - | - | - | - |
+| Document Management | - | - | - | - | - | - |
+| Document Indexing | - | - | - | - | - | - |
+| Q&A Flow | - | - | - | - | - | - |
+| Grounded Answers | - | - | - | - | - | - |
+
+## 아키텍처 레이어 (Architectural Layers)
+
+| 레이어 (Layer) | 등급 (Grade) | 경계 적용 (Boundary Enforcement) | 에이전트 가독성 (Agent Legibility) | 주요 격차 (Key Gaps) | 마지막 업데이트 (Last Updated) |
+|-------|-------|---------------------|-----------------|----------|-------------|
+| Main Process | - | - | - | - | - |
+| Preload | - | - | - | - | - |
+| Renderer | - | - | - | - | - |
+| Services | - | - | - | - | - |
+
+## 변경 이력 (Change History)
+
+### YYYY-MM-DD
+
+- Changes:
+- Domains promoted:
+- Demoted:
+- New gaps identified:
+- Gaps closed:
diff --git a/docs/ko/resources/templates/session-handoff.md b/docs/ko/resources/templates/session-handoff.md
new file mode 100644
index 0000000..7b4678b
--- /dev/null
+++ b/docs/ko/resources/templates/session-handoff.md
@@ -0,0 +1,32 @@
+# 세션 핸드오프 (Session Handoff)
+
+세션이 종료되고 다음 세션이 빠르게 이어 받기 위한 간결한 핸드오프(handoff) 노트입니다. 에이전트(agent)가 세션 종료 시 이 파일을 채우도록 하거나, 사람이 직접 채울 수 있습니다. 세션이 길거나 프로젝트에 여러 활성 영역이 있을 때 특히 중요합니다.
+
+## 현재 검증된 것 (Verified Now)
+
+- What is currently working:
+- What verification actually ran:
+
+## 이번 세션의 변경 사항 (Changed This Session)
+
+- Code or behavior added:
+- Infrastructure or harness changes:
+
+## 손상되거나 미검증된 것 (Broken Or Unverified)
+
+- Known defect:
+- Unverified path:
+- Risk for the next session:
+
+## 다음으로 최선의 행동 (Next Best Step)
+
+- Highest-priority unfinished feature:
+- Why it is next:
+- What counts as passing:
+- What must not change during that step:
+
+## 명령어 (Commands)
+
+- Startup:
+- Verification:
+- Focused debug command:
diff --git a/docs/ko/skills/index.md b/docs/ko/skills/index.md
new file mode 100644
index 0000000..23c5fba
--- /dev/null
+++ b/docs/ko/skills/index.md
@@ -0,0 +1,49 @@
+# 스킬 (Skills)
+
+이 디렉터리에는 본 강의와 함께 제공되는 번들(bundled) AI 에이전트(agent) 스킬(skill)이 포함되어 있습니다. 스킬은 AI 코딩 에이전트(Claude Code, Codex, Cursor, Windsurf 등)가 특수한 작업을 수행하기 위해 로드(load)할 수 있는 자기 완결적 프롬프트 템플릿(template)입니다.
+
+## harness-creator
+
+AI 코딩 에이전트를 위한 프로덕션(production) 등급의 해네스 엔지니어링(harness engineering) 스킬입니다. 다섯 가지 핵심 해네스(harness) 서브시스템(subsystem)인 지침(instructions), 상태(state), 검증(verification), 범위(scope), 세션 라이프사이클(session lifecycle)을 생성·평가·개선하도록 돕습니다.
+
+### 기능 (What It Does)
+
+- **처음부터 해네스 생성** — AGENTS.md, 기능 목록(feature list), 검증(verification) 워크플로우
+- **기존 해네스 개선** — 다섯 가지 서브시스템 평가와 우선순위화된 개선 사항
+- **세션 연속성(continuity) 설계** — 메모리(memory) 영속화, 진행 추적, 핸드오프(handoff) 절차
+- **프로덕션 패턴 적용** — 메모리, 컨텍스트 엔지니어링(context engineering), 도구 안전성, 멀티 에이전트(multi-agent) 조율
+
+### 빠른 시작 (Quick Start)
+
+스킬 파일은 저장소의 [`skills/harness-creator/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/skills/harness-creator)에 위치합니다.
+
+Claude Code와 함께 사용하려면 `harness-creator/` 디렉터리를 프로젝트의 스킬 경로에 복사하거나, 에이전트가 SKILL.md 파일을 가리키도록 설정하십시오.
+
+### 참고 패턴 (Reference Patterns)
+
+이 스킬에는 6가지 심층 참고 문서가 포함됩니다.
+
+| 패턴 (Pattern) | 사용 시점 (When to Use) |
+|---------|-------------|
+| Memory Persistence | 에이전트가 세션 간에 기억을 잃을 때 |
+| Context Engineering | 컨텍스트 예산 관리, JIT 로딩 |
+| Tool Registry | 도구 안전성, 동시성 제어 |
+| Multi-Agent Coordination | 병렬화, 특수화 워크플로우 |
+| Lifecycle & Bootstrap | 훅(hook), 백그라운드 작업, 초기화(initialization) |
+| Gotchas | 15가지 비자명한 실패 유형과 수정 방법 |
+
+### 템플릿 (Templates)
+
+이 스킬에는 바로 사용할 수 있는 템플릿이 포함되어 있습니다.
+
+- `agents.md` — 작업 규칙이 있는 AGENTS.md 스캐폴드(scaffold)
+- `feature-list.json` — JSON Schema와 기능 목록 예시
+- `init.sh` — 표준 초기화(initialization) 스크립트
+- `progress.md` — 세션 진행 로그 템플릿
+
+### 이 스킬이 만들어진 방법 (How This Skill Was Built)
+
+`harness-creator`는 **skill-creator** 방법론을 사용하여 개발되었습니다. 이는 에이전트 스킬을 생성·테스트·반복하기 위한 Anthropic의 공식 메타 스킬입니다. skill-creator는 구조화된 워크플로우(draft → test → evaluate → iterate)를 내장된 평가 러너(eval runner), 채점기(grader), 벤치마크 뷰어(benchmark viewer)와 함께 제공합니다.
+
+- **skill-creator 소스**: [anthropics/skills — skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator)
+- **Claude Code 스킬 문서**: [anthropics/claude-code — plugin-dev/skills](https://github.com/anthropics/claude-code/tree/main/plugins/plugin-dev/skills)
diff --git a/projects/project-01/README-KO.md b/projects/project-01/README-KO.md
new file mode 100644
index 0000000..9e39953
--- /dev/null
+++ b/projects/project-01/README-KO.md
@@ -0,0 +1,46 @@
+[English](./README.md) · **한국어**
+
+# 프로젝트 01: 기준선 대 최소 해네스
+
+약한 해네스(harness)(프롬프트에만 의존)와 명시적 해네스(규칙 파일 + 검증(verification) 메커니즘)가 AI 코딩 에이전트의 작업 완료율에 미치는 영향을 비교합니다.
+
+이 프로젝트는 본 강의의 출발점입니다. 해네스의 유무에 따른 차이를 직접 눈으로 확인하는 것이 목적입니다. 동일한 작업을 두 가지 조건에서 실행하고 결과를 측정하십시오.
+
+## 디렉터리 설명
+
+| 디렉터리 | 의미 |
+|----------|------|
+| `starter/` | **시작점** — 모호한 `task-prompt.md` 하나만 있으며 AGENTS.md, feature_list.json이 없습니다. 에이전트에게 제공하는 "약한 해네스" 버전입니다. |
+| `solution/` | **참고 구현** — 동일한 앱 코드이지만 완전한 해네스 파일(AGENTS.md, feature_list.json, init.sh, claude-progress.md)을 갖추고 있습니다. "명시적 해네스" 버전입니다. |
+
+## 사용 방법
+
+```sh
+# 1. starter(약한 해네스)로 에이전트 작업을 한 번 실행
+cd starter
+npm install
+# task-prompt.md의 내용을 Claude Code / Codex에게 프롬프트로 제공
+# 에이전트가 창 시작, 문서 목록, 문답 패널, 데이터 디렉터리 완료를 시도하도록 함
+
+# 2. solution(명시적 해네스)으로 한 번 더 실행
+cd ../solution
+npm install
+# 에이전트가 AGENTS.md를 읽고 규칙에 따라 동일한 작업을 수행하도록 함
+
+# 3. 두 결과를 비교
+# - 작업이 완료되었는가?
+# - 몇 번이나 재시도가 필요했는가?
+# - 에이전트가 조기에 "완료"를 선언했는가?
+```
+
+## 이 프로젝트에서 다루는 기능
+
+- Electron 창 성공적으로 시작
+- UI에 문서 목록 영역 표시
+- UI에 문답 패널 표시
+- 앱이 로컬 데이터 디렉터리를 생성하고 사용
+
+## 관련 강의
+
+- [강의 01: 강력한 모델이 왜 여전히 실패하는가](../../docs/lectures/lecture-01-why-capable-agents-still-fail/index.md)
+- [강의 02: 해네스가 실제로 무엇인가](../../docs/lectures/lecture-02-what-a-harness-actually-is/index.md)
diff --git a/projects/project-02/README-KO.md b/projects/project-02/README-KO.md
new file mode 100644
index 0000000..774ee40
--- /dev/null
+++ b/projects/project-02/README-KO.md
@@ -0,0 +1,39 @@
+[English](./README.md) · **한국어**
+
+# 프로젝트 02: 에이전트 가독형 워크스페이스
+
+저장소(repository) 가독성과 명시적 연속성(continuity) 산출물이 어떻게 교차 세션 개발에서 컨텍스트(context) 손실을 줄이는지 시연합니다.
+
+에이전트가 새 세션을 시작할 때 가장 먼저 하는 일은 저장소를 읽는 것입니다. 저장소가 에이전트 친화적으로 구성되어 있지 않으면, 에이전트는 이전 세션에서 무슨 일이 있었는지 파악하는 데 많은 시간을 소비합니다. 이 프로젝트는 그 차이를 직접 측정합니다.
+
+## 디렉터리 설명
+
+| 디렉터리 | 의미 |
+|----------|------|
+| `starter/` | **시작점** — P1 풀이(solution) 기반 코드로, 문서 가져오기(import), 상세 보기, 영속성(persistence) 기능이 구현 대기 중입니다. 해네스가 약합니다. AGENTS.md가 단순하고 세션 핸드오프(session-handoff)가 없습니다. |
+| `solution/` | **참고 구현** — 모든 새 기능이 구현되어 있으며 완전한 워크스페이스 문서(ARCHITECTURE.md, PRODUCT.md, session-handoff.md)를 갖추고 있습니다. |
+
+## 사용 방법
+
+```sh
+# 완료하려면 최소 2개의 에이전트 세션이 필요합니다
+cd starter
+npm install
+# 세션 A: 문서 가져오기 및 상세 보기 구현
+# 세션 B: 영속성 구현 (에이전트가 컨텍스트를 빠르게 복원하는지 관찰)
+
+cd ../solution
+npm install
+# 완전한 해네스로 재실행하여 세션 복원 속도를 비교
+```
+
+## 이 프로젝트에서 다루는 기능
+
+- 문서 가져오기 흐름 (파일 선택기 + IPC 전송)
+- 문서 상세 보기 (메타데이터 + 내용 표시)
+- 기본 영속성 (가져온 문서가 재시작 후에도 유지)
+
+## 관련 강의
+
+- [강의 03: 저장소가 왜 단일 진실 원천이어야 하는가](../../docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md)
+- [강의 04: 왜 하나의 거대한 지시 파일이 실패하는가](../../docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)
diff --git a/projects/project-03/README-KO.md b/projects/project-03/README-KO.md
new file mode 100644
index 0000000..1366f18
--- /dev/null
+++ b/projects/project-03/README-KO.md
@@ -0,0 +1,38 @@
+[English](./README.md) · **한국어**
+
+# 프로젝트 03: 범위 제어와 근거 기반 검증
+
+명시적 범위(scope) 제어와 검증(verification) 게이트가 구현 정확도를 향상시키는지 평가합니다.
+
+에이전트는 여러 기능을 동시에 구현하려는 경향이 있습니다. 이를 범위 이탈(scope drift)이라고 합니다. 이 프로젝트는 "한 번에 하나의 기능" 전략을 명시적으로 적용했을 때 산출물 품질이 어떻게 달라지는지 측정합니다.
+
+## 디렉터리 설명
+
+| 디렉터리 | 의미 |
+|----------|------|
+| `starter/` | **시작점** — P2 풀이(solution) 기반으로, 문서 청킹(chunking), 메타데이터 추출, 인덱스 상태, 기본 문답 기능이 구현 대기 중입니다. 한 번에 하나의 기능 전략 제약이 없습니다. |
+| `solution/` | **참고 구현** — 모든 기능이 구현되어 있으며, AGENTS.md에 "한 번에 하나의 기능" 전략이 포함되어 있고, feature_list.json이 실패→통과 전환 과정과 검증 증거를 보여줍니다. |
+
+## 사용 방법
+
+```sh
+cd starter
+npm install
+# 에이전트가 여러 기능을 동시에 구현하려 하는지 관찰 (범위 이탈)
+
+cd ../solution
+npm install
+# 범위 제어를 적용하여 재실행, 기능 구현 정확도 비교
+```
+
+## 이 프로젝트에서 다루는 기능
+
+- 문서 청킹 (단락 인식, 약 500자)
+- 메타데이터 추출 (단어 수, 줄 수, 단락 수)
+- 인덱스 상태가 UI에 표시
+- 출처 인용(citation)이 포함된 기본 문답 흐름
+
+## 관련 강의
+
+- [강의 05: 세션 간 컨텍스트를 유지하는 방법](../../docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md)
+- [강의 06: 모든 에이전트 세션 전에 초기화가 필요한 이유](../../docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)
diff --git a/projects/project-04/README-KO.md b/projects/project-04/README-KO.md
new file mode 100644
index 0000000..7e65a25
--- /dev/null
+++ b/projects/project-04/README-KO.md
@@ -0,0 +1,40 @@
+[English](./README.md) · **한국어**
+
+# 프로젝트 04: 런타임 가관측성과 구조적 제어
+
+런타임 가관측성(observability)과 구조화된 경계 검사를 도입하면서, 심어진 런타임 결함을 디버깅합니다.
+
+가관측성이란 에이전트가 실행되는 동안 무슨 일이 일어나고 있는지 볼 수 있는 능력입니다. 구조화된 로그와 아키텍처 경계 검사가 없으면, 에이전트가 버그를 발견했을 때 문제를 진단하는 데 훨씬 더 많은 시간이 걸립니다. 이 프로젝트는 그 차이를 측정합니다.
+
+## 디렉터리 설명
+
+| 디렉터리 | 의미 |
+|----------|------|
+| `starter/` | **시작점** — P3 풀이(solution) 기반으로, 로그와 구조화된 경계 기능이 구현 대기 중입니다. `IndexingService`에 숨겨진 버그가 심어져 있습니다. 1000자를 초과하는 파일이 빈 청크(chunk)를 생성합니다. 아키텍처 검사 스크립트가 없습니다. |
+| `solution/` | **참고 구현** — 구조화된 로그 모듈, 아키텍처 경계 검사 스크립트, 심어진 버그가 수정되어 있습니다. |
+
+## 사용 방법
+
+```sh
+cd starter
+npm install
+# 1. 에이전트가 로그를 통해 버그를 찾을 수 있는지 관찰
+# 2. 큰 파일을 가져와서 청킹 결과가 비정상적인지 확인
+
+cd ../solution
+npm install
+# 비교: 구조화된 로그가 어떻게 문제 진단을 가속화하는가
+```
+
+## 이 프로젝트에서 다루는 기능
+
+- 시작 로그
+- 가져오기 및 인덱싱 로그
+- UI에서 보이는 문답 실패 경로
+- main / preload / renderer / services 레이어의 명시적 경계
+- 심어진 런타임 결함 디버깅
+
+## 관련 강의
+
+- [강의 07: 에이전트에게 명확한 작업 경계를 설정하는 방법](../../docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md)
+- [강의 08: 기능 목록으로 에이전트 행동을 제약하는 방법](../../docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)
diff --git a/projects/project-05/README-KO.md b/projects/project-05/README-KO.md
new file mode 100644
index 0000000..cfe1a19
--- /dev/null
+++ b/projects/project-05/README-KO.md
@@ -0,0 +1,41 @@
+[English](./README.md) · **한국어**
+
+# 프로젝트 05: 평가기 루프와 3역할 업그레이드
+
+역할 분리(단일 역할 / 생성기+평가기 / 계획기+생성기+평가기)가 구현 품질을 어떻게 변화시키는지 측정합니다.
+
+에이전트 시스템에서 역할 분리는 중요한 품질 향상 기법입니다. 한 에이전트가 작업을 수행하는 동시에 자신의 작업을 평가하는 것은 이해충돌을 일으킵니다. 별도의 평가기 역할을 도입하면 더 객관적인 품질 검증이 가능합니다. 이 프로젝트는 세 가지 구성 방식을 직접 비교합니다.
+
+## 디렉터리 설명
+
+| 디렉터리 | 의미 |
+|----------|------|
+| `starter/` | **시작점** — P4 풀이(solution) 기반으로, 다중 턴 문답 이력 기능이 구현 대기 중입니다. |
+| `solution/single-role/` | **변체 A** — 단일 에이전트가 모든 작업(계획 + 구현 + 자체 검토)을 수행합니다. 기본 품질. |
+| `solution/gen-eval/` | **변체 B** — 생성기(generator) + 평가기(evaluator) 패턴. 수정 증거가 있으며 더 높은 품질. |
+| `solution/plan-gen-eval/` | **변체 C** — 계획기(planner) + 생성기 + 평가기. 스프린트 계약(sprint contract)과 채점 기준(rubric)이 있는 최고 품질. |
+
+## 사용 방법
+
+```sh
+# 세 변체는 각자 독립적으로 실행
+cd solution/single-role && npm install # 단일 역할 모드
+cd solution/gen-eval && npm install # 생성+평가 모드
+cd solution/plan-gen-eval && npm install # 완전한 3역할 모드
+
+# 세 변체의 다음을 비교:
+# - 코드 품질 (evaluator-rubric.md 점수)
+# - 발견된 결함 수
+# - 필요한 재작업 정도
+```
+
+## 이 프로젝트에서 다루는 기능
+
+- 다중 턴 문답 이력 (대화형 UI)
+- 스프린트 계약(sprint contract)
+- 평가기 채점 기준(evaluator rubric) 조정
+
+## 관련 강의
+
+- [강의 09: 에이전트가 너무 일찍 완료를 선언하지 못하도록 막는 방법](../../docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md)
+- [강의 10: 전체 파이프라인 실행만이 진정한 검증인 이유](../../docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md)
diff --git a/projects/project-06/README-KO.md b/projects/project-06/README-KO.md
new file mode 100644
index 0000000..586770d
--- /dev/null
+++ b/projects/project-06/README-KO.md
@@ -0,0 +1,47 @@
+[English](./README.md) · **한국어**
+
+# 프로젝트 06: 런타임 가관측성과 디버깅 (캡스톤)
+
+강의 졸업 프로젝트: 완전한 해네스(harness)를 구축하고 벤치마크(benchmark) 테스트를 수행하며, 정리(cleanup) 루프를 실행하여 품질 유지 가능성을 검증합니다.
+
+이 프로젝트는 강의 전체를 종합하는 캡스톤(capstone)입니다. 이전 다섯 프로젝트에서 배운 모든 해네스 메커니즘을 하나의 완전한 시스템으로 통합합니다. 완성된 해네스는 미래의 에이전트 세션이 안정적으로 작업을 이어받을 수 있는 기반을 제공해야 합니다.
+
+## 디렉터리 설명
+
+| 디렉터리 | 의미 |
+|----------|------|
+| `starter/` | **시작점** — 완전한 제품 코드이지만 해네스가 의도적으로 약화되어 있습니다(기본 AGENTS.md만 있고, feature_list.json, session-handoff, clean-state-checklist가 없음). |
+| `solution/` | **참고 구현** — 최대 해네스: 모든 산출물 파일이 완비되어 있고, 품질 문서 점수가 높으며, 벤치마크 스크립트와 정리 스캐너가 포함되어 있습니다. |
+
+## 사용 방법
+
+```sh
+cd starter
+npm install
+# 약한 해네스로 벤치마크 스위트를 실행하고 결과를 기록
+
+cd ../solution
+npm install
+# 완전한 해네스로 동일한 벤치마크를 실행
+# 정리 루프 실행
+# quality-document.md의 점수 변화를 비교
+
+# 벤치마크 실행
+./scripts/benchmark.sh
+
+# 정리 스캔 실행
+./scripts/cleanup-scanner.sh
+```
+
+## 이 프로젝트에서 다루는 기능
+
+- 문서 가져오기
+- 인덱스 구축 또는 갱신
+- 인용이 포함된 문답
+- 런타임 피드백(feedback)
+- 읽기 가능하고 재시작 가능한 저장소 상태
+
+## 관련 강의
+
+- [강의 11: 에이전트의 런타임을 가관측하게 만드는 방법](../../docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md)
+- [강의 12: 모든 세션이 왜 깨끗한 상태를 남겨야 하는가](../../docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)
diff --git a/skills/README-CN.md b/skills/README-CN.md
index 48ed6a0..3a8c0c4 100644
--- a/skills/README-CN.md
+++ b/skills/README-CN.md
@@ -1,6 +1,6 @@
# Skills(技能集)
-[English](./README.md)
+[English](./README.md) · [한국어](./README-KO.md)
本目录包含 Learn Harness Engineering 项目的可复用 AI agent 技能。每个技能都是一个自包含的提示词模板,可被 AI 编程智能体(Claude Code、Codex、Cursor、Windsurf 等)加载以执行专业任务。
diff --git a/skills/README-KO.md b/skills/README-KO.md
new file mode 100644
index 0000000..ef3dfdc
--- /dev/null
+++ b/skills/README-KO.md
@@ -0,0 +1,71 @@
+[English](./README.md) · [中文版](./README-CN.md) · **한국어**
+
+# 스킬(Skills)
+
+이 디렉터리에는 Learn Harness Engineering 프로젝트를 위한 재사용 가능한 AI 에이전트(agent) 스킬(skill)이 포함되어 있습니다. 각 스킬은 AI 코딩 에이전트(Claude Code, Codex, Cursor, Windsurf 등)가 로드하여 특화된 작업을 수행할 수 있는 독립적인 프롬프트(prompt) 템플릿입니다.
+
+스킬은 에이전트가 복잡한 작업 흐름을 모듈화된 방식으로 처리할 수 있게 해주는 해네스(harness)의 핵심 구성 요소입니다. SKILL.md 파일을 진입점으로 하는 구조화된 형식을 따릅니다.
+
+## 사용 가능한 스킬
+
+### harness-creator
+
+AI 코딩 에이전트를 위한 프로덕션 해네스 엔지니어링 스킬입니다. 에이전트 해네스 파일(AGENTS.md, 기능 목록, 검증 워크플로우, 세션 연속성(session continuity) 메커니즘)을 생성하고 평가하며 개선하는 데 도움을 줍니다.
+
+- **5가지 참고 패턴**: 메모리 영속성(Memory Persistence), 컨텍스트 엔지니어링(Context Engineering), 도구 레지스트리(Tool Registry), 다중 에이전트 조율(Multi-Agent Coordination), 라이프사이클 및 부트스트랩(Lifecycle & Bootstrap)
+- **템플릿**: AGENTS.md, feature-list.json, init.sh, progress.md
+- **5개의 내장 평가(eval) 테스트 케이스**
+- **이중 언어**: 영어 + 中文
+
+전체 문서는 [harness-creator/README.md](harness-creator/README.md)를 참조하십시오.
+
+## harness-creator 구축 방법
+
+`harness-creator` 스킬은 **skill-creator** 방법론을 사용하여 개발되었습니다. skill-creator는 에이전트 스킬을 생성하고 테스트하고 반복하기 위한 Anthropic의 공식 메타 스킬입니다. skill-creator는 내장된 평가 실행기, 채점기, 벤치마크 뷰어를 갖춘 구조화된 워크플로우(초안 → 테스트 → 평가 → 반복)를 제공합니다.
+
+이처럼 스킬 자체를 스킬로 만드는 접근 방식은 해네스 엔지니어링의 재귀적 특성을 보여줍니다. 에이전트를 위한 도구를 에이전트가 검증하는 구조입니다.
+
+- **skill-creator 소스**: [anthropics/skills — skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator)
+- **Anthropic Claude Code 스킬 문서**: [anthropics/claude-code — plugin-dev/skills](https://github.com/anthropics/claude-code/tree/main/plugins/plugin-dev/skills)
+
+## 디렉터리 구조
+
+```
+skills/
+├── README.md # 영어 버전 (이 파일의 원본)
+├── README-CN.md # 중국어 버전
+├── README-KO.md # 한국어 버전 (이 파일)
+└── harness-creator/ # 해네스 엔지니어링 스킬
+ ├── SKILL.md # 주요 스킬 정의 (이중 언어)
+ ├── SKILL.md.en # 영어 전용 버전
+ ├── README.md # 상세 문서
+ ├── metadata.json # 스킬 메타데이터 및 트리거
+ ├── evals/ # 테스트 케이스
+ ├── templates/ # 스캐폴드(scaffold) 템플릿
+ └── references/ # 심층 패턴 문서
+```
+
+## 스킬 동작 방식
+
+각 스킬은 표준 구조를 따릅니다.
+
+1. **SKILL.md** — 진입점. YAML 프론트매터(frontmatter)(이름, 트리거를 위한 설명)와 에이전트를 위한 마크다운 지시사항이 포함됩니다.
+2. **references/** — 필요에 따라 컨텍스트로 로드되는 추가 문서.
+3. **templates/** — 스킬이 사용자를 위해 생성할 수 있는 시작 템플릿.
+
+스킬은 점진적 공개(progressive disclosure)를 사용합니다. 에이전트는 처음에 이름과 설명만 보고, 트리거되면 전체 SKILL.md 본문을 로드하며, 필요할 때만 번들된 리소스를 읽습니다.
+
+이 접근 방식은 컨텍스트 윈도(context window)를 효율적으로 사용하기 위한 것입니다. 에이전트가 항상 모든 정보를 가지고 시작하는 것이 아니라, 필요한 시점에 필요한 정보를 로드합니다.
+
+## 보안 감사
+
+이 디렉터리의 모든 파일은 보안 감사를 마쳤습니다.
+
+- 백도어, 숨겨진 URL, 인코딩된 페이로드 없음
+- 데이터 유출 또는 하드코딩된 자격 증명 없음
+- 명령 주입 취약점 없음
+- `init.sh`는 표준 npm 라이프사이클 명령만 실행
+
+## 라이선스
+
+MIT
diff --git a/skills/README.md b/skills/README.md
index 729ed5e..9b424c5 100644
--- a/skills/README.md
+++ b/skills/README.md
@@ -1,6 +1,6 @@
# Skills
-[中文版](./README-CN.md)
+[中文版](./README-CN.md) · [한국어](./README-KO.md)
This directory contains reusable AI agent skills for the Learn Harness Engineering project. Each skill is a self-contained prompt template that can be loaded by AI coding agents (Claude Code, Codex, Cursor, Windsurf, etc.) to perform specialized tasks.