Merge pull request #8 from teddylee777/feat/repository-lucky-sundae

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

Author: sanbuphy

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）更可靠地工作。**

README-KO.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
 

README.md

@@ -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",

docs/.vitepress/config.mts

@@ -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)
   }

docs/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>

docs/ko/index.md

@@ -0,0 +1,9 @@
+# 실패 신호 체크리스트
+
+취약한 하네스(harness) 실행을 검토할 때 이 체크리스트를 활용하십시오.
+
+- 에이전트(agent)가 앱 시작 방법을 직접 물어보았는가, 아니면 잘못 추론했는가?
+- 의도한 제품과 일치하지 않는 디렉터리 또는 추상화를 만들었는가?
+- 완전한 워크플로 없이 눈에 보이는 UI 껍데기만 만든 뒤 멈췄는가?
+- 이후 실행이 이어 진행할 수 있도록 메모나 산출물(deliverable)을 남겼는가?
+- 새 세션이 5분 이내에 이전에 무슨 일이 있었는지 파악할 수 있는가?

docs/ko/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md

@@ -0,0 +1,7 @@
+# 강의 01 코드 예제
+
+이 폴더는 다음을 보여주는 소규모 예제에 사용됩니다.
+
+- 강력한 모델이 취약한 환경에서 실패하는 사례
+- 명세가 부족한 저장소(repository) 설정
+- 피드백 루프가 없는 상황

docs/ko/lectures/lecture-01-why-capable-agents-still-fail/code/index.md

@@ -0,0 +1,18 @@
+# 명세가 부족한 작업 예시
+
+AI 질의응답 기능이 있는 데스크톱 지식 베이스 앱을 만드십시오.
+
+제약 조건:
+
+- 명시된 것 없음
+- 시작 명령어 없음
+- 폴더 구조 안내 없음
+- 데이터 모델 정의 없음
+- 명시적 완료 기준(Definition of Done) 없음
+
+이런 종류의 프롬프트에서 발생하는 전형적인 결과:
+
+- 에이전트(agent)가 구조를 임시방편으로 만들어냄
+- 앱이 컴파일되더라도 일관되게 시작되지 않을 수 있음
+- 사용 가능한 수집/조회 경로가 없는 상태에서 UI가 먼저 나타날 수 있음
+- 에이전트가 겉으로만 보이는 성공 후에 멈추는 경우가 많음