Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
docs: add root-level READMEs for all languages + translate VitePress sidebar
sanbuphy827d42dd303d
diff --git a/README-AR.md b/README-AR.mdnew file mode 100644index 0000000..3992990--- /dev/null+++ b/README-AR.md@@ -0,0 +1,580 @@+<p align="center">+ <a href="./README.md"><img alt="English" src="https://img.shields.io/badge/EN-English-blue?style=flat-square"></a>+ <a href="./README-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/ZH-简体中文-red?style=flat-square"></a>+ <a href="./README-ZH-TW.md"><img alt="繁體中文" src="https://img.shields.io/badge/ZH--TW-繁體中文-orange?style=flat-square"></a>+ <a href="./README-JA.md"><img alt="日本語" src="https://img.shields.io/badge/JA-日本語-green?style=flat-square"></a>+ <a href="./README-KO.md"><img alt="한국어" src="https://img.shields.io/badge/KO-한국어-blueviolet?style=flat-square"></a>+ <a href="./README-ES.md"><img alt="Español" src="https://img.shields.io/badge/ES-Español-yellow?style=flat-square"></a>+ <a href="./README-FR.md"><img alt="Français" src="https://img.shields.io/badge/FR-Français-007EC6?style=flat-square"></a>+ <a href="./README-RU.md"><img alt="Русский" src="https://img.shields.io/badge/RU-Русский-informational?style=flat-square"></a>+ <a href="./README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/DE-Deutsch-2EA043?style=flat-square"></a>+ <a href="./README-AR.md"><img alt="العربية" src="https://img.shields.io/badge/AR-العربية-success?style=flat-square"></a>+ <a href="./README-VI.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/VI-Tiếng_Việt-cc6699?style=flat-square"></a>+ <a href="./README-UZ.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>+</p>++# تعلّم هندسة الحزام (Learn Harness Engineering)++> **دورة تعليمية قائمة على المشاريع حول بناء البيئة وإدارة الحالة وآليات التحقق والتحكم التي تجعل وكلاء البرمجة بالذكاء الاصطناعي يعملون بشكل موثوق.**++تعلّم هندسة الحزام (Learn 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/) يمكن أن تساعدك في إنشاء حزام بمستوى الإنتاج (AGENTS.md، قوائم الميزات، init.sh، سير عمل التحقق) لمشروعك الخاص في دقائق.++---++## جدول المحتويات++- [✨ معاينة بصرية](#-معاينة-بصرية)+- [ما تعنيه هندسة الحزام فعلياً](#ما-تعنيه-هندسة-الحزام-فعليا)+- [ابدأ بسرعة: حسّن وكيلك اليوم](#ابدأ-بسرعة-حسّن-وكيلك-اليوم)+- [مشروع التخرج: تطبيق حقيقي](#مشروع-التخرج-تطبيق-حقيقي)+- [مسار التعلم](#مسار-التعلم)+- [المنهج الدراسي](#المنهج-الدراسي)+- [المهارات](#المهارات)+- [دورات أخرى](#دورات-أخرى)++---++## ✨ معاينة بصرية++### 🏠 الصفحة الرئيسية للدورة+> مخطط شامل للدورة ومقدمة للفلسفات الأساسية، توفر مساراً واضحاً للبدء.++++### 📖 محاضرات تفاعلية+> غوص عميق في نقاط الألم الواقعية ومشاريع عملية (مثل المشروع 01) لتجربة تعليمية تفاعلية.++++### 🗂️ مكتبة موارد جاهزة للاستخدام+> قوالب وتكوينات مرجعية مصممة لحل المشكلات الشائعة في تطوير وكلاء الذكاء الاصطناعي متعددة الأدوار، مثل فقدان السياق والإنهاء المبكر للمهام.++++## كتيبات الدورة بصيغة PDF++يحتوي هذا المستودع الآن على خط أنابيب لبناء كتيبات الدورة بصيغة PDF.++- شغّل `npm run pdf:build` لتوليد ملفات PDF باللغتين الإنجليزية والصينية محلياً.+- تُكتب ملفات المخرجات إلى `artifacts/pdfs/`.+- شغّل `npm run screenshots:readme` إذا كنت تريد تحديث صور معاينة README.+- سير عمل GitHub Actions [`release-course-pdfs.yml`](../../.github/workflows/release-course-pdfs.yml) يمكنه بناء ملفات PDF ونشرها على GitHub Releases.++---++## النموذج ذكي، الحزام يجعله موثوقاً++هناك حقيقة قاسية يتعلمها معظم الناس بالطريقة الصعبة: **أقوى نموذج في العالم سيفشل في مهام الهندسة الحقيقية إذا لم تبني بيئة مناسبة حوله.**++ربما رأيت هذا بنفسك. تعطي Claude أو GPT مهمة في مستودعك. يبدأ بشكل جيد — يقرأ الملفات، يكتب الكود، يبدو منتجاً. ثم يحدث خطأ ما. يتخطى خطوة. يكسر اختباراً. يقول "تم" لكن لا شيء يعمل فعلياً. تقضي وقتاً أطول في الإصلاح مما لو كنت فعلت ذلك بنفسك.++هذه ليست مشكلة نموذج. إنها مشكلة حزام.++الدليل واضح. أجرت Anthropic تجربة محكومة: نفس النموذج (Opus 4.5)، نفس الموجه ("بناء محرر ألعاب ريترو ثنائي الأبعاد"). بدون حزام، أنفق 9 دولارات في 20 دقيقة وأنتج شيئاً لا يعمل. مع حزام كامل (مخطط + مولّد + مقيّم)، أنفق 200 دولار في 6 ساعات وبنى لعبة يمكنك اللعب بها فعلياً. النموذج لم يتغير. الحزام هو الذي تغيّر.++أبلغت 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+```++---++## ما تعنيه هندسة الحزام فعلياً++هندسة الحزام تدور حول بناء بيئة عمل كاملة حول النموذج حتى ينتج نتائج موثوقة. الأمر لا يتعلق بكتابة موجهات أفضل. بل يتعلق بتصميم النظام الذي يعمل النموذج داخله.++يتكون الحزام من خمس أنظمة فرعية:++```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.+```++لكل نظام فرعي وظيفة واحدة:++- **التعليمات** — تخبر الوكيل بما يجب فعله، بأي ترتيب، وما يجب قراءته قبل البدء. ليس ملفاً ضخماً واحداً؛ بل هيكل إفصاح تدريجي يتنقل فيه الوكيل حسب الحاجة.+- **الحالة** — تتبع ما تم إنجازه، ما قيد التنفيذ، وما هو التالي. محفوظة على القرص حتى تلتقط الجلسة التالية من حيث توقفت الجلسة السابقة تماماً.+- **التحقق** — مجموعة اختبارات ناجحة فقط تُحسب كدليل. لا يمكن للوكيل إعلان النصر بدون دليل قابل للتشغيل.+- **النطاق** — تقييد الوكيل بميزة واحدة في كل مرة. لا تجاوز. لا إنهاء نصف ثلاثة أشياء. لا إعادة كتابة قائمة الميزات لإخفاء العمل غير المنجز.+- **دورة حياة الجلسة** — التهيئة في البداية. التنظيف في النهاية. ترك مسار إعادة تشغيل نظيف للجلسة التالية.++---++## لماذا توجد هذه الدورة++السؤال ليس "هل يمكن للنماذج كتابة الكود؟" يمكنها ذلك. السؤال هو: **هل يمكنها إكمال مهام هندسية حقيقية بشكل موثوق داخل مستودعات حقيقية، عبر جلسات متعددة، بدون إشراف بشري مستمر؟**++حالياً، الإجابة هي: ليس بدون حزام.++```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. **المحاضرات**: 12 وحدة مفاهيمية تشرح النظرية وراء هندسة الحزام.+2. **المشاريع**: 6 مشاريع عملية حيث تبني مساحة عمل وكيلية من الصفر.+3. **مكتبة الموارد**: قوالب جاهزة للنسخ (`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/) وأضفها إلى مشروعك. هذا كل شيء. أربعة ملفات، وستكون جلسات وكيلك أكثر استقراراً بشكل ملحوظ مقارنة بالاعتماد على الموجهات وحدها.++---++## مشروع التخرج: تطبيق حقيقي++جميع مشاريع الدورة الستة تدور حول نفس المنتج: **تطبيق سطح مكتب لقاعدة المعرفة الشخصية مبني على Electron**.++```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-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) | لماذا يجب أن يكون المستودع هو المصدر الوحيد للحقيقة؟ | إذا لم يستطع الوكيل رؤيته، فهو غير موجود |+| [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) | لماذا تفقد المهام طويلة التشغيل الاستمرارية؟ | احفظ التقدم على القرص؛ التقط من حيث توقفت |+| [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) | لماذا تنتمي قابلية الملاحظة داخل الحزام؟ | إذا لم تستطع رؤية ما فعله الوكيل، لا يمكنك إصلاح ما أفسده |+| [L12](../../docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | لماذا يجب أن تترك كل جلسة حالة نظيفة؟ | نجاح الجلسة التالية يعتمد على تنظيف هذه الجلسة |++### المشاريع — 6 مشاريع عملية تطبق طرق المحاضرات على نفس تطبيق Electron++| المشروع | ماذا تفعل | آلية الحزام |+|---------|-----------|-------------|+| [P01](../../docs/projects/project-01-baseline-vs-minimal-harness/index.md) | شغّل نفس المهمة مرتين: بالموجهات فقط مقابل القواعد أولاً | حزام أدنى: 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) | اجعل الوكيل يلتقط من حيث توقف | سجل التقدم + تسليم الجلسة + استمرارية متعددة الجلسات |+| [P04](../../docs/projects/project-04-incremental-indexing/index.md) | أوقف الوكيل عن القيام بالكثير جداً أو القليل جداً | ملاحظات وقت التشغيل + التحكم في النطاق + الفهرسة التدريجية |+| [P05](../../docs/projects/project-05-grounded-qa-verification/index.md) | اجعل الوكيل يتحقق من عمله بنفسه | التحقق الذاتي + أسئلة وأجوبة مبنية على أدلة + إكمال قائم على الأدلة |+| [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.+```++### مكتبة الموارد++- [English](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) — templates, checklists, and method references+- [简体中文](https://walkinglabs.github.io/learn-harness-engineering/zh/resources/) — 中文模板、清单和方法参考+- [繁體中文](https://walkinglabs.github.io/learn-harness-engineering/zh-TW/resources/) — 繁體中文範本、清單和方法參考+- [日本語](https://walkinglabs.github.io/learn-harness-engineering/ja/resources/) — テンプレート、チェックリスト、方法リファレンス+- [한국어](https://walkinglabs.github.io/learn-harness-engineering/ko/resources/) — 템플릿, 체크리스트, 방법 참고 자료+- [Español](https://walkinglabs.github.io/learn-harness-engineering/es/resources/) — plantillas, listas de verificación y referencias+- [Français](https://walkinglabs.github.io/learn-harness-engineering/fr/resources/) — modèles, listes de contrôle et références+- [Русский](https://walkinglabs.github.io/learn-harness-engineering/ru/resources/) — шаблоны, чек-листы и справочники+- [Deutsch](https://walkinglabs.github.io/learn-harness-engineering/de/resources/) — Vorlagen, Checklisten und Referenzen+- [العربية](https://walkinglabs.github.io/learn-harness-engineering/ar/resources/) — قوالب، قوائم تحقق ومراجع+- [Tiếng Việt](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+- [Oʻzbekcha](https://walkinglabs.github.io/learn-harness-engineering/uz/resources/) — andozalar, tekshiruv roʻyxatlari va maʼlumotnomalar++---++## دورة حياة جلسة الوكيل++إحدى الأفكار الأساسية في هذه الدورة: **يجب أن تتبع جلسة الوكيل دورة حياة منظمة، وليست عشوائية.** إليك كيف تبدو:++```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."+```++---++## لمن هذه الدورة++هذه الدورة موجهة لـ:++- المهندسين الذين يستخدمون بالفعل وكلاء البرمجة ويرغبون في تحسين الاستقرار والجودة+- الباحثين أو البناة الذين يريدون فهماً منهجياً لتصميم الحزام+- قادة التكنولوجيا الذين يحتاجون لفهم كيف يؤثر تصميم البيئة على أداء الوكيل++هذه الدورة ليست لـ:++- الأشخاص الذين يبحثون عن مقدمة للذكاء الاصطناعي بدون كود+- الأشخاص الذين يهتمون فقط بالموجهات ولا يخططون لبناء تطبيقات حقيقية+- المتعلمين غير المستعدين للسماح للوكلاء بالعمل داخل مستودعات حقيقية++---++## المتطلبات++هذه دورة حيث تقوم بتشغيل وكلاء البرمجة فعلياً.++تحتاج إلى واحد على الأقل من هذه الأدوات:++- Claude Code+- Codex+- وكيل برمجة IDE أو سطر أوامر آخر يدعم تعديل الملفات وتنفيذ الأوامر والمهام متعددة الخطوات++تفترض الدورة أنك تستطيع:++- فتح مستودع محلي+- السماح للوكيل بتعديل الملفات+- السماح للوكيل بتشغيل الأوامر+- فحص المخرجات وإعادة تشغيل المهام++إذا لم تكن لديك هذه الأداة، لا يزال بإمكانك قراءة محتوى الدورة، لكن لن تتمكن من إكمال المشاريع كما هو مقصود.++---++## المعاينة المحلية++يستخدم هذا المستودع VitePress كعارض للتوثيق.++```sh+npm install+npm run docs:dev # Dev server with hot reload+npm run docs:build # Production build+npm run docs:preview # Preview built site+```++ثم افتح URL المحلي الذي يُخرجه VitePress في متصفحك.++---++## المتطلبات المسبقة++المطلوب:++- الإلمام بسطر الأوامر و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)+- [OpenAI: Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/)+- [Anthropic: Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)+- [LangChain: Improving Deep Agents with harness engineering](https://www.langchain.com/blog/improving-deep-agents-with-harness-engineering)+- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)+- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)++راجع قائمة المراجع الطبقية الكاملة في [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md).++---++## هيكل المستودع++```text+learn-harness-engineering/+├── docs/ # VitePress documentation site+│ ├── lectures/ # 12 lectures (index.md + code/ examples)+│ │ ├── lecture-01-*/+│ │ ├── lecture-02-*/+│ │ └── ... (12 total)+│ ├── projects/ # 6 project descriptions+│ │ ├── project-01-*/+│ │ └── ... (6 total)+│ └── resources/ # Multilingual templates & references+│ ├── en/ # English templates, checklists, guides+│ ├── zh/ # Chinese templates, checklists, guides+│ ├── ru/ # Russian templates, checklists, guides+│ └── vi/ # Vietnamese templates, checklists, guides+├── projects/+│ ├── shared/ # Shared Electron + TypeScript + React foundation+│ └── project-NN/ # Per-project starter/ and solution/ directories+├── skills/ # Reusable AI agent skills+│ └── harness-creator/ # Harness engineering skill+├── package.json # VitePress + dev tooling+└── CLAUDE.md # Claude Code instructions for this repo+```++---++## كيف تم تنظيم الدورة++- كل محاضرة تركز على سؤال واحد+- الدورة تتضمن 6 مشاريع+- كل مشروع يتطلب من الوكيل القيام بعمل حقيقي+- كل مشروع يقارن نتائج الحزام الضعيف بالقوي+- ما يهم هو الفرق المقاس، وليس عدد الوثائق المكتوبة++---++## المهارات++يحتوي هذا المستودع أيضاً على مهارات وكلاء ذكاء اصطناعي قابلة لإعادة الاستخدام والتي يمكنك تثبيتها مباشرة في IDE أو مساحة عمل وكيلك.++- [**harness-creator**](../../skills/harness-creator/): مهارة تساعدك في إنشاء حزام بمستوى الإنتاج لمشروعك الخاص في دقائق.++---++## دورات أخرى++فريقنا أنشأ دورات أخرى أيضاً! اطلع عليها:++[](https://github.com/walkinglabs/hands-on-modern-rl)++**Hands-on Modern RL**: منهج عملي مفتوح المصدر يسد الفجوة من مفاهيم التعلم المعزز الأساسية إلى محاذاة نماذج اللغة الكبيرة (LLM) وRLVR والأنظمة الوكيلية المتقدمة.++---++## تاريخ النجوم++[](https://www.star-history.com/#walkinglabs/learn-harness-engineering&type=date&legend=top-left)++---++## شكر وتقدير++هذه الدورة مستوحاة وتستمد أفكاراً من [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) — دليل تدريجي لبناء وكيل من الصفر، من حلقة واحدة إلى تنفيذ مستقل معزول.diff --git a/README-CN.md b/README-CN.mdindex 480a7f6..df7d672 100644--- a/README-CN.md+++ b/README-CN.md@@ -1,16 +1,16 @@<p align="center"><a href="./README.md"><img alt="English" src="https://img.shields.io/badge/EN-English-blue?style=flat-square"></a>- <img alt="简体中文" src="https://img.shields.io/badge/ZH-简体中文-red?style=flat-square">- <a href="./docs-readme/zh-TW/README.md"><img alt="繁體中文" src="https://img.shields.io/badge/ZH--TW-繁體中文-orange?style=flat-square"></a>- <a href="./docs-readme/ja-JP/README.md"><img alt="日本語" src="https://img.shields.io/badge/JA-日本語-green?style=flat-square"></a>- <a href="./docs-readme/ko-KR/README.md"><img alt="한국어" src="https://img.shields.io/badge/KO-한국어-blueviolet?style=flat-square"></a>- <a href="./docs-readme/es-ES/README.md"><img alt="Español" src="https://img.shields.io/badge/ES-Español-yellow?style=flat-square"></a>- <a href="./docs-readme/fr-FR/README.md"><img alt="Français" src="https://img.shields.io/badge/FR-Français-007EC6?style=flat-square"></a>- <a href="https://walkinglabs.github.io/learn-harness-engineering/ru/"><img alt="Русский" src="https://img.shields.io/badge/RU-Русский-informational?style=flat-square"></a>- <a href="./docs-readme/de-DE/README.md"><img alt="Deutsch" src="https://img.shields.io/badge/DE-Deutsch-2EA043?style=flat-square"></a>- <a href="./docs-readme/ar-SA/README.md"><img alt="العربية" src="https://img.shields.io/badge/AR-العربية-success?style=flat-square"></a>- <a href="./docs-readme/vi-VN/README.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/VI-Tiếng_Việt-cc6699?style=flat-square"></a>- <a href="https://walkinglabs.github.io/learn-harness-engineering/uz/"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>+ <a href="./README-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/ZH-简体中文-red?style=flat-square"></a>+ <a href="./README-ZH-TW.md"><img alt="繁體中文" src="https://img.shields.io/badge/ZH--TW-繁體中文-orange?style=flat-square"></a>+ <a href="./README-JA.md"><img alt="日本語" src="https://img.shields.io/badge/JA-日本語-green?style=flat-square"></a>+ <a href="./README-KO.md"><img alt="한국어" src="https://img.shields.io/badge/KO-한국어-blueviolet?style=flat-square"></a>+ <a href="./README-ES.md"><img alt="Español" src="https://img.shields.io/badge/ES-Español-yellow?style=flat-square"></a>+ <a href="./README-FR.md"><img alt="Français" src="https://img.shields.io/badge/FR-Français-007EC6?style=flat-square"></a>+ <a href="./README-RU.md"><img alt="Русский" src="https://img.shields.io/badge/RU-Русский-informational?style=flat-square"></a>+ <a href="./README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/DE-Deutsch-2EA043?style=flat-square"></a>+ <a href="./README-AR.md"><img alt="العربية" src="https://img.shields.io/badge/AR-العربية-success?style=flat-square"></a>+ <a href="./README-VI.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/VI-Tiếng_Việt-cc6699?style=flat-square"></a>+ <a href="./README-UZ.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a></p># Learn Harness Engineeringdiff --git a/README-DE.md b/README-DE.mdnew file mode 100644index 0000000..74b818f--- /dev/null+++ b/README-DE.md@@ -0,0 +1,580 @@+<p align="center">+ <a href="./README.md"><img alt="English" src="https://img.shields.io/badge/EN-English-blue?style=flat-square"></a>+ <a href="./README-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/ZH-简体中文-red?style=flat-square"></a>+ <a href="./README-ZH-TW.md"><img alt="繁體中文" src="https://img.shields.io/badge/ZH--TW-繁體中文-orange?style=flat-square"></a>+ <a href="./README-JA.md"><img alt="日本語" src="https://img.shields.io/badge/JA-日本語-green?style=flat-square"></a>+ <a href="./README-KO.md"><img alt="한국어" src="https://img.shields.io/badge/KO-한국어-blueviolet?style=flat-square"></a>+ <a href="./README-ES.md"><img alt="Español" src="https://img.shields.io/badge/ES-Español-yellow?style=flat-square"></a>+ <a href="./README-FR.md"><img alt="Français" src="https://img.shields.io/badge/FR-Français-007EC6?style=flat-square"></a>+ <a href="./README-RU.md"><img alt="Русский" src="https://img.shields.io/badge/RU-Русский-informational?style=flat-square"></a>+ <a href="./README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/DE-Deutsch-2EA043?style=flat-square"></a>+ <a href="./README-AR.md"><img alt="العربية" src="https://img.shields.io/badge/AR-العربية-success?style=flat-square"></a>+ <a href="./README-VI.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/VI-Tiếng_Việt-cc6699?style=flat-square"></a>+ <a href="./README-UZ.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>+</p>++# Learn Harness Engineering++> **Ein projektbasierter Kurs über den Aufbau von Umgebungen, Zustandsverwaltung, Verifizierung und Kontrollmechanismen, die KI-Coding-Agenten zuverlässig machen.**++Learn Harness Engineering ist ein Kurs, der sich der Entwicklung von KI-Coding-Agenten widmet. Wir haben die fortschrittlichsten Theorien und Praktiken des Harness Engineering in der Branche eingehend studiert und zusammengefasst. Unsere Kernreferenzen umfassen:++- [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)++> **Schneller Einstieg?** Der Skill [`skills/harness-creator/`](../../skills/) kann Ihnen helfen, in Minuten ein produktionsreifes Harness (AGENTS.md, Feature-Listen, init.sh, Verifizierungs-Workflows) für Ihr eigenes Projekt zu erstellen.++---++## Inhaltsverzeichnis++- [Visuelle Vorschau](#visuelle-vorschau)+- [Was Harness Engineering wirklich bedeutet](#was-harness-engineering-wirklich-bedeutet)+- [Schnellstart: Verbessern Sie Ihren Agenten noch heute](#schnellstart-verbessern-sie-ihren-agenten-noch-heute)+- [Abschlussprojekt: Eine echte App](#abschlussprojekt-eine-echte-app)+- [Lernpfad](#lernpfad)+- [Lehrplan](#lehrplan)+- [Skills](#skills)+- [Weitere Kurse](#weitere-kurse)++---++## Visuelle Vorschau++### Kurs-Startseite+> Ein umfassender Kursüberblick und eine Einführung in die Kernphilosophien, die einen klaren Einstiegspfad bieten.++++### Immersive Vorlesungen+> Tiefe Einblicke in reale Problemstellungen und praktische Projekte (wie Projekt 01) für ein immersives Lernerlebnis.++++### Vorlagen-Bibliothek+> Vorlagen und Referenzkonfigurationen, die entwickelt wurden, um häufige Fallstricke bei der Entwicklung von Multi-Turn-KI-Agenten zu lösen, wie Kontextverlust und vorzeitiger Aufgabenabschluss.++++## PDF-Kursbücher++Das Repository enthält nun eine PDF-Build-Pipeline für die Kursinhalte.++- Führen Sie `npm run pdf:build` aus, um englische und chinesische PDFs lokal zu generieren.+- Die Ausgabedateien werden in `artifacts/pdfs/` geschrieben.+- Führen Sie `npm run screenshots:readme` aus, wenn Sie die README-Vorschaubilder aktualisieren möchten.+- Der GitHub Actions-Workflow [`release-course-pdfs.yml`](../../.github/workflows/release-course-pdfs.yml) kann die PDFs erstellen und auf GitHub Releases veröffentlichen.++---++## Das Modell ist klug, das Harness macht es zuverlässig++Es gibt eine harte Wahrheit, die die meisten Menschen auf die harte Tour lernen: **Das stärkste Modell der Welt wird bei echten Engineering-Aufgaben dennoch scheitern, wenn Sie keine geeignete Umgebung dafür aufbauen.**++Sie haben das wahrscheinlich selbst erlebt. Sie geben Claude oder GPT eine Aufgabe in Ihrem Repo. Es beginnt gut — liest Dateien, schreibt Code, sieht produktiv aus. Dann geht etwas schief. Es überspringt einen Schritt. Es zerstört einen Test. Es sagt „fertig", aber nichts funktioniert tatsächlich. Sie verbringen mehr Zeit mit der Behebung, als wenn Sie es selbst gemacht hätten.++Das ist kein Modellproblem. Es ist ein Harness-Problem.++Die Beweise sind eindeutig. Anthropic führte ein kontrolliertes Experiment durch: gleiches Modell (Opus 4.5), gleicher Prompt („baue einen 2D-Retro-Spieleditor"). Ohne Harness gab es 9 $ in 20 Minuten aus und produzierte etwas, das nicht funktionierte. Mit einem vollständigen Harness (Planer + Generator + Evaluierer) gab es 200 $ in 6 Stunden aus und baute ein Spiel, das man tatsächlich spielen konnte. Das Modell hat sich nicht geändert. Das Harness schon.++OpenAI berichtete dasselbe mit Codex: in einem gut geharnischten Repository wechselt dasselbe Modell von „unzuverlässig" zu „zuverlässig". Keine marginale Verbesserung — ein qualitativer Sprung.++**Dieser Kurs bringt Ihnen bei, wie Sie diese Umgebung aufbauen.**++```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+```++---++## Was Harness Engineering wirklich bedeutet++Harness Engineering handelt davon, eine vollständige Arbeitsumgebung um das Modell herum aufzubauen, damit es zuverlässige Ergebnisse liefert. Es geht nicht darum, bessere Prompts zu schreiben. Es geht darum, das System zu entwerfen, in dem das Modell arbeitet.++Ein Harness hat fünf Subsysteme:++```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.+```++Jedes Subsystem hat eine Aufgabe:++- **Instructions** — Dem Agenten sagen, was zu tun ist, in welcher Reihenfolge und was er lesen soll, bevor er beginnt. Nicht eine riesige Datei; eine progressive Enthüllungsstruktur, die der Agent nach Bedarf navigiert.+- **State** — Verfolgen, was erledigt wurde, was in Bearbeitung ist und was als Nächstes ansteht. Auf der Festplatte gespeichert, damit die nächste Session genau dort ansetzt, wo die letzte aufgehört hat.+- **Verification** — Nur eine bestehende Testsuite gilt als Nachweis. Der Agent kann keinen Erfolg melden ohne ausführbaren Beweis.+- **Scope** — Den Agenten auf ein Feature gleichzeitig beschränken. Keine Übergriffe. Kein halbfertiges Abschließen von drei Dingen. Kein Umschreiben der Feature-Liste, um unfertige Arbeit zu verbergen.+- **Session Lifecycle** — Initialisierung am Anfang. Aufräumen am Ende. Einen sauberen Neustartpfad für die nächste Sitzung hinterlassen.++---++## Warum dieser Kurs existiert++Die Frage ist nicht „Können Modelle Code schreiben?" Sie können. Die Frage ist: **Können sie zuverlässig echte Engineering-Aufgaben in echten Repositories über mehrere Sessions hinweg absolvieren, ohne ständige menschliche Überwachung?**++Im Moment lautet die Antwort: nicht ohne ein Harness.++```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+```++Die Fragen, die dieser Kurs wirklich interessieren:++- Welche Harness-Designs verbessern die Aufgabenabschlussraten?+- Welche Designs reduzieren Nacharbeit und falsche Abschlüsse?+- Welche Mechanismen halten langlaufende Aufgaben stetig voran?+- Welche Strukturen halten das System nach mehreren Agenten-Läufen wartbar?++---++## Kurscurriculum & Dokumentation++Die vollständigen Kursmaterialien finden Sie auf der **[Dokumentations-Website](https://walkinglabs.github.io/learn-harness-engineering/)**.++Das Curriculum ist in drei Teile gegliedert:++1. **Vorlesungen**: 12 konzeptionelle Einheiten, die die Theorie hinter dem Harness Engineering erklären.+2. **Projekte**: 6 praktische Projekte, bei denen Sie einen agentenbasierten Arbeitsbereich von Grund auf neu aufbauen.+3. **Vorlagen-Bibliothek**: Kopierfertige Vorlagen (`AGENTS.md`, `feature_list.json`, `init.sh` usw.), die Sie noch heute in Ihren eigenen Repositories verwenden können.++---++## Schnellstart: Verbessern Sie Ihren Agenten noch heute++Sie müssen nicht alle 12 Vorlesungen lesen, bevor Sie einen Nutzen ziehen. Wenn Sie bereits einen Coding-Agenten in einem echten Projekt einsetzen, können Sie ihn jetzt sofort verbessern.++Die Idee ist einfach: Anstatt nur Prompts zu schreiben, geben Sie Ihrem Agenten einen Satz strukturierter Dateien, die definieren, was zu tun ist, was bereits erledigt ist und wie die Arbeit verifiziert wird. Diese Dateien befinden sich in Ihrem Repo, sodass jede Session vom gleichen Zustand ausgeht.++```text+ YOUR PROJECT ROOT+ ├── AGENTS.md <-- das Betriebshandbuch des Agenten+ ├── CLAUDE.md <-- (Alternative, wenn Sie Claude Code verwenden)+ ├── init.sh <-- führt install + verify + start aus+ ├── feature_list.json <-- welche Features existieren, welche erledigt sind+ ├── claude-progress.md <-- was in jeder Session passiert ist+ └── src/ <-- Ihr tatsächlicher Code+```++Laden Sie sich die Starter-Vorlagen aus der [Vorlagen-Bibliothek](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) herunter und fügen Sie sie in Ihr Projekt ein. Das war's. Vier Dateien, und Ihre Agenten-Sessions werden bereits deutlich stabiler sein als mit Prompts allein.++---++## Abschlussprojekt: Eine echte App++Alle sechs Kursprojekte drehen sich um dasselbe Produkt: **eine Electron-basierte Desktop-App für persönliches Wissensmanagement**.++```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+```++Dieses Projekt wurde gewählt, weil es hohen praktischen Nutzen, ausreichende reale Produktkomplexität und ein gutes Szenario für die Beobachtung von Harness-Verbesserungen (Vorher/Nachher) verbindet.++Jedes Kursprojekt (Starter/Lösung) ist eine vollständige Kopie dieser Electron-App im jeweiligen Entwicklungsstadium. Der Starter von P(N+1) wird aus der Lösung von P(N) abgeleitet — die App entwickelt sich weiter, während Ihre Harness-Fähigkeiten wachsen.++---++## Lernpfad++Der Kurs ist für die chronologische Abarbeitung konzipiert. Jede Phase baut auf der vorherigen auf.++```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)+```++Jede Phase dauert etwa eine Woche, wenn Sie nebenbei lernen. Wenn Sie schneller vorgehen möchten, können die Phasen 1–3 an einem langen Wochenende absolviert werden.++---++## Lehrplan++### Vorlesungen — 12 konzeptionelle Einheiten, die jeweils eine Kernfrage beantworten++*Lesen Sie den vollständigen Text jeder Vorlesung auf der [Dokumentations-Website](https://walkinglabs.github.io/learn-harness-engineering/).*++| Session | Frage | Kernidee |+|---------|-------|----------|+| [L01](../../docs/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Warum scheitern starke Modelle dennoch bei echten Aufgaben? | Die Lücke zwischen Benchmarks und echtem Engineering |+| [L02](../../docs/lectures/lecture-02-what-a-harness-actually-is/index.md) | Was bedeutet „Harness" eigentlich? | Fünf Subsysteme: Instructions, State, Verification, Scope, Lifecycle |+| [L03](../../docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Warum muss das Repo die einzige Quelle der Wahrheit sein? | Wenn der Agent es nicht sehen kann, existiert es nicht |+| [L04](../../docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Warum scheitert eine einzige riesige Instruktionsdatei? | Progressive Enthüllung: eine Karte geben, keine Enzyklopädie |+| [L05](../../docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Warum verlieren langlaufende Aufgaben ihre Kontinuität? | Fortschritt auf der Festplatte speichern; dort fortfahren, wo man aufgehört hat |+| [L06](../../docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Warum braucht die Initialisierung eine eigene Phase? | Die Umgebung auf Funktionsfähigkeit prüfen, bevor der Agent mit der Arbeit beginnt |+| [L07](../../docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Warum greifen Agenten über und schließen unvollständig ab? | Ein Feature gleichzeitig; explizite Definition von „Fertig" |+| [L08](../../docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Warum sind Feature-Listen Harness-Primitiven? | Maschinenlesbare Scope-Grenzen, die der Agent nicht ignorieren kann |+| [L09](../../docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Warum melden Agenten zu früh den Erfolg? | Verifizierungslücken: Vertrauen ≠ Korrektheit |+| [L10](../../docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Warum ändert End-to-End-Testing die Ergebnisse? | Nur ein vollständiger Pipeline-Lauf gilt als echte Verifizierung |+| [L11](../../docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Warum gehört Observability in das Harness? | Wenn Sie nicht sehen können, was der Agent getan hat, können Sie nicht reparieren, was er zerstört hat |+| [L12](../../docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Warum muss jede Session einen sauberen Zustand hinterlassen? | Der Erfolg der nächsten Session hängt vom Aufräumen dieser Session ab |++### Projekte — 6 praktische Projekte, die Vorlesungsmethoden auf dieselbe Electron-App anwenden++| Projekt | Was Sie tun | Harness-Mechanismus |+|---------|-------------|---------------------|+| [P01](../../docs/projects/project-01-baseline-vs-minimal-harness/index.md) | Dieselbe Aufgabe zweimal ausführen: nur Prompt vs. regelnbasiert | Minimales Harness: AGENTS.md + init.sh + feature_list.json |+| [P02](../../docs/projects/project-02-agent-readable-workspace/index.md) | Das Repo umstrukturieren, damit der Agent es lesen kann | Agentenlesbarer Arbeitsbereich + persistente Zustandsdateien |+| [P03](../../docs/projects/project-03-multi-session-continuity/index.md) | Den Agenten dort fortfahren lassen, wo er aufgehört hat | Fortschrittsprotokoll + Session-Übergabe + Multi-Session-Kontinuität |+| [P04](../../docs/projects/project-04-incremental-indexing/index.md) | Den Agenten davon abhalten, zu viel oder zu wenig zu tun | Laufzeit-Feedback + Scope-Kontrolle + inkrementelle Indizierung |+| [P05](../../docs/projects/project-05-grounded-qa-verification/index.md) | Den Agenten seine eigene Arbeit verifizieren lassen | Selbstverifizierung + fundierte Q&A + evidenzbasierter Abschluss |+| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | Ein vollständiges Harness von Grund auf neu aufbauen (Abschlussprojekt) | Vollständiges Harness: alle Mechanismen + Observability + Ablationsstudie |++```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.+```++### Vorlagen-Bibliothek++- [English](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) — templates, checklists, and method references+- [简体中文](https://walkinglabs.github.io/learn-harness-engineering/zh/resources/) — 中文模板、清单和方法参考+- [繁體中文](https://walkinglabs.github.io/learn-harness-engineering/zh-TW/resources/) — 繁體中文範本、清單和方法參考+- [日本語](https://walkinglabs.github.io/learn-harness-engineering/ja/resources/) — テンプレート、チェックリスト、方法リファレンス+- [한국어](https://walkinglabs.github.io/learn-harness-engineering/ko/resources/) — 템플릿, 체크리스트, 방법 참고 자료+- [Español](https://walkinglabs.github.io/learn-harness-engineering/es/resources/) — plantillas, listas de verificación y referencias+- [Français](https://walkinglabs.github.io/learn-harness-engineering/fr/resources/) — modèles, listes de contrôle et références+- [Русский](https://walkinglabs.github.io/learn-harness-engineering/ru/resources/) — шаблоны, чек-листы и справочники+- [Deutsch](https://walkinglabs.github.io/learn-harness-engineering/de/resources/) — Vorlagen, Checklisten und Referenzen+- [العربية](https://walkinglabs.github.io/learn-harness-engineering/ar/resources/) — قوالب، قوائم تحقق ومراجع+- [Tiếng Việt](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+- [Oʻzbekcha](https://walkinglabs.github.io/learn-harness-engineering/uz/resources/) — andozalar, tekshiruv roʻyxatlari va maʼlumotnomalar++---++## Der Lebenszyklus einer Agenten-Session++Eine der Kernideen dieses Kurses: **Die Session eines Agenten sollte einem strukturierten Lebenszyklus folgen, keinem Freifür-alle.** So sieht das aus:++```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."+```++---++## Für wen ist dieser Kurs?++Dieser Kurs richtet sich an:++- Entwickler, die bereits Coding-Agenten verwenden und mehr Stabilität und Qualität möchten+- Forscher oder Entwickler, die ein systematisches Verständnis des Harness-Designs erwerben möchten+- Tech-Leads, die verstehen möchten, wie Umgebungsdesign die Agentenleistung beeinflusst++Dieser Kurs richtet sich nicht an:++- Personen, die eine Einführung in KI ohne Programmierung suchen+- Personen, die sich nur für Prompts interessieren und keine echten Implementierungen planen+- Lernende, die nicht bereit sind, Agenten in echten Repositories arbeiten zu lassen++---++## Voraussetzungen++Dies ist ein Kurs, in dem Sie tatsächlich Coding-Agenten ausführen.++Sie benötigen mindestens eines dieser Werkzeuge:++- Claude Code+- Codex+- Einen anderen IDE- oder CLI-Coding-Agenten, der Dateibearbeitung, Befehlsausführung und mehrstufige Aufgaben unterstützt++Der Kurs setzt voraus, dass Sie:++- Ein lokales Repository öffnen können+- Dem Agenten erlauben können, Dateien zu bearbeiten+- Dem Agenten erlauben können, Befehle auszuführen+- Ausgaben überprüfen und Aufgaben neu starten können++Wenn Sie über kein solches Werkzeug verfügen, können Sie die Kursinhalte dennoch lesen, aber Sie werden die Projekte nicht wie vorgesehen abschließen können.++---++## Lokale Vorschau++Dieses Repository verwendet VitePress als Dokumentationsbetrachter.++```sh+npm install+npm run docs:dev # Dev-Server mit Hot Reload+npm run docs:build # Produktions-Build+npm run docs:preview # Vorschau der erstellten Seite+```++Öffnen Sie dann die lokale URL, die VitePress ausgibt, in Ihrem Browser.++---++## Vorkenntnisse++Erforderlich:++- Vertrautheit mit dem Terminal, Git und lokalen Entwicklungsumgebungen+- Fähigkeit, Code in mindestens einem gängigen Anwendungsstack zu lesen und zu schreiben+- Grundlegende Software-Debugging-Erfahrung (Lesen von Logs, Tests und Laufzeitverhalten)+- Ausreichend Zeit für implementationsfokussierte Kursarbeit++Hilfreich, aber nicht erforderlich:++- Erfahrung mit Electron, Desktop-Apps oder Local-First-Tools+- Hintergrund in Testing, Logging oder Softwarearchitektur+- Frühere Erfahrung mit Codex, Claude Code oder ähnlichen Coding-Agenten++---++## Kernreferenzen++Primär:++- [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)+- [OpenAI: Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/)+- [Anthropic: Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)+- [LangChain: Improving Deep Agents with harness engineering](https://www.langchain.com/blog/improving-deep-agents-with-harness-engineering)+- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)+- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)++Die vollständige geschichtete Referenzliste finden Sie in [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md).++---++## Repository-Struktur++```text+learn-harness-engineering/+├── docs/ # VitePress-Dokumentationsseite+│ ├── lectures/ # 12 Vorlesungen (index.md + code/ Beispiele)+│ │ ├── lecture-01-*/+│ │ ├── lecture-02-*/+│ │ └── ... (insgesamt 12)+│ ├── projects/ # 6 Projektbeschreibungen+│ │ ├── project-01-*/+│ │ └── ... (insgesamt 6)+│ └── resources/ # Mehrsprachige Vorlagen & Referenzen+│ ├── en/ # Englische Vorlagen, Checklisten, Leitfäden+│ ├── zh/ # Chinesische Vorlagen, Checklisten, Leitfäden+│ ├── ru/ # Russische Vorlagen, Checklisten, Leitfäden+│ └── vi/ # Vietnamesische Vorlagen, Checklisten, Leitfäden+├── projects/+│ ├── shared/ # Gemeinsame Electron + TypeScript + React-Basis+│ └── project-NN/ # Projektbezogene starter/ und solution/ Verzeichnisse+├── skills/ # Wiederverwendbare KI-Agenten-Skills+│ └── harness-creator/ # Harness Engineering Skill+├── package.json # VitePress + Dev-Werkzeuge+└── CLAUDE.md # Claude Code-Anweisungen für dieses Repo+```++---++## Wie der Kurs organisiert ist++- Jede Vorlesung konzentriert sich auf eine Frage+- Der Kurs umfasst 6 Projekte+- Jedes Projekt erfordert, dass der Agent echte Arbeit leistet+- Jedes Projekt vergleicht schwache vs. starke Harness-Ergebnisse+- Was zählt, ist der gemessene Unterschied, nicht wie viele Dokumente geschrieben wurden++---++## Skills++Dieses Repository enthält auch wiederverwendbare KI-Agenten-Skills, die Sie direkt in Ihre IDE oder Ihren Agenten-Arbeitsbereich installieren können.++- [**harness-creator**](../../skills/harness-creator/): Ein Skill, der Ihnen hilft, in Minuten ein produktionsreifes Harness für Ihr eigenes Projekt zu erstellen.++---++## Weitere Kurse++Unser Team hat auch weitere Kurse erstellt! Schauen Sie sich diese an:++[](https://github.com/walkinglabs/hands-on-modern-rl)++**Hands-on Modern RL**: Ein Open-Source-Praxiscurriculum, das die Lücke von grundlegenden RL-Konzepten zu LLM-Alignment, RLVR und fortschrittlichen agentischen Systemen überbrückt.++---++## Star-History++[](https://www.star-history.com/#walkinglabs/learn-harness-engineering&type=date&legend=top-left)++---++## Danksagungen++Dieser Kurs wurde inspiriert von und bezieht Ideen aus [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) — einem fortschreitenden Leitfaden zum Aufbau eines Agenten von Grund auf, von einem einzelnen Loop bis zur isolierten autonomen Ausführung.diff --git a/README-ES.md b/README-ES.mdnew file mode 100644index 0000000..fa5e8f4--- /dev/null+++ b/README-ES.md@@ -0,0 +1,580 @@+<p align="center">+ <a href="./README.md"><img alt="English" src="https://img.shields.io/badge/EN-English-blue?style=flat-square"></a>+ <a href="./README-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/ZH-简体中文-red?style=flat-square"></a>+ <a href="./README-ZH-TW.md"><img alt="繁體中文" src="https://img.shields.io/badge/ZH--TW-繁體中文-orange?style=flat-square"></a>+ <a href="./README-JA.md"><img alt="日本語" src="https://img.shields.io/badge/JA-日本語-green?style=flat-square"></a>+ <a href="./README-KO.md"><img alt="한국어" src="https://img.shields.io/badge/KO-한국어-blueviolet?style=flat-square"></a>+ <a href="./README-ES.md"><img alt="Español" src="https://img.shields.io/badge/ES-Español-yellow?style=flat-square"></a>+ <a href="./README-FR.md"><img alt="Français" src="https://img.shields.io/badge/FR-Français-007EC6?style=flat-square"></a>+ <a href="./README-RU.md"><img alt="Русский" src="https://img.shields.io/badge/RU-Русский-informational?style=flat-square"></a>+ <a href="./README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/DE-Deutsch-2EA043?style=flat-square"></a>+ <a href="./README-AR.md"><img alt="العربية" src="https://img.shields.io/badge/AR-العربية-success?style=flat-square"></a>+ <a href="./README-VI.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/VI-Tiếng_Việt-cc6699?style=flat-square"></a>+ <a href="./README-UZ.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>+</p>++# Learn Harness Engineering++> **Un curso basado en proyectos sobre cómo construir el entorno, la gestión de estado, la verificación y los mecanismos de control que hacen que los agentes de codificación de IA funcionen de forma fiable.**++Learn Harness Engineering es un curso dedicado a la ingeniería de agentes de codificación de IA. Hemos estudiado y sintetizado en profundidad las teorías y prácticas más avanzadas de Harness Engineering en la industria. Nuestras referencias principales incluyen:++- [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)++> **Inicio rápido?** La skill [`skills/harness-creator/`](../../skills/) puede ayudarte a generar un harness de nivel productivo (AGENTS.md, listas de funcionalidades, init.sh, flujos de verificación) para tu propio proyecto en cuestión de minutos.++---++## Tabla de Contenidos++- [Vista Previa Visual](#vista-previa-visual)+- [Lo que realmente significa Harness Engineering](#lo-que-realmente-significa-harness-engineering)+- [Inicio Rápido: Mejora tu agente hoy mismo](#inicio-rápido-mejora-tu-agente-hoy-mismo)+- [Proyecto Final: Una aplicación real](#proyecto-final-una-aplicación-real)+- [Ruta de Aprendizaje](#ruta-de-aprendizaje)+- [Programa de Estudios](#programa-de-estudios)+- [Skills](#skills)+- [Otros Cursos](#otros-cursos)++---++## Vista Previa Visual++### Pagina de Inicio del Curso+> Un esquema completo del curso e introducción a las filosofías centrales, que proporciona una ruta clara para comenzar.++++### Clases Inmersivas+> Análisis profundo de problemas reales y proyectos prácticos (como el Proyecto 01) para una experiencia de aprendizaje inmersiva.++++### Biblioteca de Recursos Listos para Usar+> Plantillas y configuraciones de referencia diseñadas para resolver problemas comunes en el desarrollo de agentes de IA de múltiples turnos, como la pérdida de contexto y la finalización prematura de tareas.++++## Libros de Curso en PDF++El repositorio ahora incluye un pipeline de construcción en PDF para el contenido del curso.++- Ejecuta `npm run pdf:build` para generar los PDFs en inglés y chino localmente.+- Los archivos de salida se escriben en `artifacts/pdfs/`.+- Ejecuta `npm run screenshots:readme` si deseas actualizar las imágenes de vista previa del README.+- El workflow de GitHub Actions [`release-course-pdfs.yml`](../../.github/workflows/release-course-pdfs.yml) puede construir los PDFs y publicarlos en GitHub Releases.++---++## El modelo es inteligente, el harness lo hace fiable++Hay una verdad difícil que la mayoría de las personas aprenden por las malas: **el modelo más potente del mundo seguirá fallando en tareas de ingeniería reales si no construyes un entorno adecuado a su alrededor.**++Probablemente ya lo hayas visto. Le das una tarea a Claude o GPT en tu repositorio. Comienza bien: lee archivos, escribe código, parece productivo. Luego algo sale mal. Omite un paso. Rompe un test. Dice "listo" pero nada funciona realmente. Pasas más tiempo arreglando las cosas que si lo hubieras hecho tú mismo.++Esto no es un problema del modelo. Es un problema del harness.++La evidencia es clara. Anthropic realizó un experimento controlado: mismo modelo (Opus 4.5), mismo prompt ("construye un editor de juegos retro 2D"). Sin un harness, gastó $9 en 20 minutos y produjo algo que no funcionaba. Con un harness completo (planificador + generador + evaluador), gastó $200 en 6 horas y construyó un juego que realmente se podía jugar. El modelo no cambió. El harness sí.++OpenAI reportó lo mismo con Codex: en un repositorio bien equipado con un harness, el mismo modelo pasa de "poco fiable" a "fiable". No una mejora marginal, sino un cambio cualitativo.++**Este curso te enseña cómo construir ese entorno.**++```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+```++---++## Lo que realmente significa Harness Engineering++Harness Engineering se trata de construir un entorno de trabajo completo alrededor del modelo para que produzca resultados fiables. No se trata de escribir mejores prompts. Se trata de diseñar el sistema dentro del cual opera el modelo.++Un harness tiene cinco subsistemas:++```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.+```++Cada subsistema tiene una única responsabilidad:++- **Instructions** — Le dicen al agente qué hacer, en qué orden y qué leer antes de comenzar. No un archivo gigante; una estructura de divulgación progresiva que el agente navega según lo necesite.+- **State** — Rastrea qué se ha hecho, qué está en progreso y qué sigue. Se persiste en disco para que la siguiente sesión continúe exactamente donde la anterior se quedó.+- **Verification** — Solo un conjunto de tests que pasan cuenta como evidencia. El agente no puede declarar victoria sin pruebas ejecutables.+- **Scope** — Limita al agente a una funcionalidad a la vez. Sin excederse. Sin dejar tres cosas a medias. Sin reescribir la lista de funcionalidades para ocultar trabajo inacabado.+- **Session Lifecycle** — Inicializar al inicio. Limpiar al final. Dejar una ruta de reinicio limpia para la siguiente sesión.++---++## Por qué existe este curso++La pregunta no es "pueden los modelos escribir código?" Pueden. La pregunta es: **pueden completar de forma fiable tareas de ingeniería reales dentro de repositorios reales, a lo largo de múltiples sesiones, sin supervisión humana constante?**++En este momento, la respuesta es: no sin un harness.++```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+```++Las preguntas que realmente importan en este curso:++- Qué diseños de harness mejoran las tasas de completitud de tareas?+- Qué diseños reducen el retrabajo y las completaciones incorrectas?+- Qué mecanismos mantienen las tareas de larga duración progresando de manera constante?+- Qué estructuras mantienen el sistema mantenible después de múltiples ejecuciones del agente?++---++## Plan de Estudios y Documentación del Curso++Para ver todos los materiales del curso, visita el **[Sitio de Documentación](https://walkinglabs.github.io/learn-harness-engineering/)**.++El plan de estudios se divide en tres partes:++1. **Clases**: 12 unidades conceptuales que explican la teoría detrás de Harness Engineering.+2. **Proyectos**: 6 proyectos prácticos donde construyes un espacio de trabajo para agentes desde cero.+3. **Biblioteca de Recursos**: Plantillas listas para copiar (`AGENTS.md`, `feature_list.json`, `init.sh`, etc.) para usar en tus propios repositorios hoy mismo.++---++## Inicio Rápido: Mejora tu agente hoy mismo++No necesitas leer las 12 clases antes de empezar a obtener valor. Si ya estás usando un agente de codificación en un proyecto real, aquí tienes cómo mejorarlo ahora mismo.++La idea es simple: en lugar de solo escribir prompts, dale a tu agente un conjunto de archivos estructurados que definan qué hacer, qué se ha hecho y cómo verificar el trabajo. Estos archivos viven dentro de tu repositorio, así que cada sesión comienza desde el mismo estado.++```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+```++Obtén las plantillas iniciales de la [Biblioteca de Recursos](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) y colócalas en tu proyecto. Eso es todo. Cuatro archivos, y tus sesiones de agente ya serán significativamente más estables que ejecutándolas solo con prompts.++---++## Proyecto Final: Una aplicación real++Los seis proyectos del curso giran en torno al mismo producto: **una aplicación de escritorio de base de conocimiento personal basada en Electron**.++```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+```++Este proyecto fue elegido porque combina un fuerte valor práctico, suficiente complejidad de producto del mundo real y un buen entorno para observar mejoras antes y después del harness.++El starter/solution de cada proyecto del curso es una copia completa de esta aplicación Electron en esa etapa evolutiva. El starter de P(N+1) se deriva de la solution de P(N) — la aplicación evoluciona a medida que crecen tus habilidades de harness.++---++## Ruta de Aprendizaje++El curso está diseñado para realizarse en orden. Cada fase se construye sobre la anterior.++```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)+```++Cada fase toma aproximadamente una semana si lo haces a tiempo parcial. Si quieres ir más rápido, las fases 1-3 se pueden completar en un fin de semana largo.++---++## Programa de Estudios++### Clases — 12 unidades conceptuales, cada una respondiendo una pregunta central++*Lee el texto completo de cada clase en el [Sitio de Documentación](https://walkinglabs.github.io/learn-harness-engineering/).*++| Sesión | Pregunta | Idea Central |+|---------|----------|--------------|+| [L01](../../docs/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Por qué los modelos potentes siguen fallando en tareas reales? | La brecha de capacidad entre benchmarks e ingeniería real |+| [L02](../../docs/lectures/lecture-02-what-a-harness-actually-is/index.md) | Qué significa realmente "harness"? | Cinco subsistemas: instrucciones, estado, verificación, alcance, ciclo de vida |+| [L03](../../docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Por qué el repositorio debe ser la única fuente de verdad? | Si el agente no puede verlo, no existe |+| [L04](../../docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Por qué falla un único archivo de instrucciones gigante? | Divulgación progresiva: da un mapa, no una enciclopedia |+| [L05](../../docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Por qué las tareas de larga duración pierden continuidad? | Persistir el progreso en disco; continuar donde lo dejaste |+| [L06](../../docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Por qué la inicialización necesita su propia fase? | Verificar que el entorno está saludable antes de que el agente comience a trabajar |+| [L07](../../docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Por qué los agentes se exceden y no terminan? | Una funcionalidad a la vez; definición explícita de "hecho" |+| [L08](../../docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Por qué las listas de funcionalidades son primitivas del harness? | Límites de alcance legibles por máquina que el agente no puede ignorar |+| [L09](../../docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Por qué los agentes declaran victoria demasiado pronto? | Brechas de verificación: confianza ≠ corrección |+| [L10](../../docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Por qué las pruebas de extremo a extremo cambian los resultados? | Solo una ejecución completa del pipeline cuenta como verificación real |+| [L11](../../docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Por qué la observabilidad pertenece dentro del harness? | Si no puedes ver lo que el agente hizo, no puedes arreglar lo que rompió |+| [L12](../../docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Por qué cada sesión debe dejar un estado limpio? | El éxito de la siguiente sesión depende de la limpieza de esta sesión |++### Proyectos — 6 proyectos prácticos aplicando los métodos de las clases a la misma aplicación Electron++| Proyecto | Lo que haces | Mecanismo del Harness |+|----------|--------------|----------------------|+| [P01](../../docs/projects/project-01-baseline-vs-minimal-harness/index.md) | Ejecutar la misma tarea dos veces: solo con prompts vs. con reglas primero | Harness mínimo: AGENTS.md + init.sh + feature_list.json |+| [P02](../../docs/projects/project-02-agent-readable-workspace/index.md) | Reestructurar el repositorio para que el agente pueda leerlo | Espacio de trabajo legible por el agente + archivos de estado persistentes |+| [P03](../../docs/projects/project-03-multi-session-continuity/index.md) | Hacer que el agente continúe desde donde se quedó | Registro de progreso + transferencia de sesión + continuidad multi-sesión |+| [P04](../../docs/projects/project-04-incremental-indexing/index.md) | Evitar que el agente haga demasiado o muy poco | Retroalimentación en tiempo de ejecución + control de alcance + indexación incremental |+| [P05](../../docs/projects/project-05-grounded-qa-verification/index.md) | Hacer que el agente verifique su propio trabajo | Auto-verificación + Q&A fundamentado + completación basada en evidencia |+| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | Construir un harness completo desde cero (proyecto final) | Harness completo: todos los mecanismos + observabilidad + estudio de ablación |++```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.+```++### Biblioteca de Recursos++- [English](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) — templates, checklists, and method references+- [简体中文](https://walkinglabs.github.io/learn-harness-engineering/zh/resources/) — 中文模板、清单和方法参考+- [繁體中文](https://walkinglabs.github.io/learn-harness-engineering/zh-TW/resources/) — 繁體中文範本、清單和方法參考+- [日本語](https://walkinglabs.github.io/learn-harness-engineering/ja/resources/) — テンプレート、チェックリスト、方法リファレンス+- [한국어](https://walkinglabs.github.io/learn-harness-engineering/ko/resources/) — 템플릿, 체크리스트, 방법 참고 자료+- [Español](https://walkinglabs.github.io/learn-harness-engineering/es/resources/) — plantillas, listas de verificación y referencias+- [Français](https://walkinglabs.github.io/learn-harness-engineering/fr/resources/) — modèles, listes de contrôle et références+- [Русский](https://walkinglabs.github.io/learn-harness-engineering/ru/resources/) — шаблоны, чек-листы и справочники+- [Deutsch](https://walkinglabs.github.io/learn-harness-engineering/de/resources/) — Vorlagen, Checklisten und Referenzen+- [العربية](https://walkinglabs.github.io/learn-harness-engineering/ar/resources/) — قوالب، قوائم تحقق ومراجع+- [Tiếng Việt](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+- [Oʻzbekcha](https://walkinglabs.github.io/learn-harness-engineering/uz/resources/) — andozalar, tekshiruv roʻyxatlari va maʼlumotnomalar++---++## El Ciclo de Vida de la Sesión del Agente++Una de las ideas centrales de este curso: **la sesión del agente debe seguir un ciclo de vida estructurado, no un libre intercambio.** Así es como se ve:++```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."+```++---++## Para quién es este curso++Este curso es para:++- Ingenieros que ya usan agentes de codificación y desean mayor estabilidad y calidad+- Investigadores o constructores que quieren una comprensión sistemática del diseño de harnesses+- Líderes técnicos que necesitan entender cómo el diseño del entorno afecta el rendimiento del agente++Este curso NO es para:++- Personas que buscan una introducción a la IA sin código+- Personas que solo se interesan por los prompts y no planean construir implementaciones reales+- Estudiantes que no están preparados para dejar que los agentes trabajen dentro de repositorios reales++---++## Requisitos++Este es un curso donde realmente ejecutas agentes de codificación.++Necesitas al menos una de estas herramientas:++- Claude Code+- Codex+- Otro agente de codificación de IDE o CLI que soporte edición de archivos, ejecución de comandos y tareas de múltiples pasos++El curso asume que puedes:++- Abrir un repositorio local+- Permitir que el agente edite archivos+- Permitir que el agente ejecute comandos+- Inspeccionar la salida y volver a ejecutar tareas++Si no tienes una de estas herramientas, aún puedes leer el contenido del curso, pero no podrás completar los proyectos según lo previsto.++---++## Vista Previa Local++Este repositorio usa VitePress como visor de documentación.++```sh+npm install+npm run docs:dev # Servidor de desarrollo con recarga en caliente+npm run docs:build # Build de producción+npm run docs:preview # Vista previa del sitio construido+```++Luego abre la URL local que VitePress muestra en tu navegador.++---++## Prerrequisitos++Requerido:++- Familiaridad con la terminal, git y entornos de desarrollo local+- Capacidad de leer y escribir código en al menos un stack de aplicaciones común+- Experiencia básica en depuración de software (lectura de logs, tests y comportamiento en tiempo de ejecución)+- Suficiente tiempo para dedicar a un curso enfocado en la implementación++Útil pero no requerido:++- Experiencia con Electron, aplicaciones de escritorio o herramientas local-first+- Experiencia en testing, logging o arquitectura de software+- Exposición previa a Codex, Claude Code o agentes de codificación similares++---++## Referencias Principales++Primarias:++- [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)+- [OpenAI: Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/)+- [Anthropic: Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)+- [LangChain: Improving Deep Agents with harness engineering](https://www.langchain.com/blog/improving-deep-agents-with-harness-engineering)+- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)+- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)++Consulta la lista completa de referencias en capas en [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md).++---++## Estructura del Repositorio++```text+learn-harness-engineering/+├── docs/ # Sitio de documentación VitePress+│ ├── lectures/ # 12 clases (index.md + ejemplos en code/)+│ │ ├── lecture-01-*/+│ │ ├── lecture-02-*/+│ │ └── ... (12 en total)+│ ├── projects/ # 6 descripciones de proyectos+│ │ ├── project-01-*/+│ │ └── ... (6 en total)+│ └── resources/ # Plantillas y referencias multilingües+│ ├── en/ # Plantillas, checklists y guías en inglés+│ ├── zh/ # Plantillas, checklists y guías en chino+│ ├── ru/ # Plantillas, checklists y guías en ruso+│ └── vi/ # Plantillas, checklists y guías en vietnamita+├── projects/+│ ├── shared/ # Fundación compartida de Electron + TypeScript + React+│ └── project-NN/ # Directorios starter/ y solution/ por proyecto+├── skills/ # Skills reutilizables para agentes de IA+│ └── harness-creator/ # Skill de Harness Engineering+├── package.json # VitePress + herramientas de desarrollo+└── CLAUDE.md # Instrucciones de Claude Code para este repositorio+```++---++## Cómo está organizado el curso++- Cada clase se enfoca en una pregunta+- El curso incluye 6 proyectos+- Cada proyecto requiere que el agente haga trabajo real+- Cada proyecto compara resultados con harness débil vs. fuerte+- Lo que importa es la diferencia medida, no cuánta documentación se escribió++---++## Skills++Este repositorio también incluye skills reutilizables para agentes de IA que puedes instalar directamente en tu IDE o espacio de trabajo del agente.++- [**harness-creator**](../../skills/harness-creator/): Un skill que te ayuda a generar un harness de nivel productivo para tu propio proyecto en cuestión de minutos.++---++## Otros Cursos++Nuestro equipo también ha creado otros cursos! Échales un vistazo:++[](https://github.com/walkinglabs/hands-on-modern-rl)++**Hands-on Modern RL**: Un plan de estudios práctico y de código abierto que cierra la brecha entre los conceptos básicos de RL y la alineación de LLMs, RLVR y sistemas Agentic avanzados.++---++## Historial de Estrellas++[](https://www.star-history.com/#walkinglabs/learn-harness-engineering&type=date&legend=top-left)++---++## Agradecimientos++Este curso fue inspirado por y toma ideas de [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) — una guía progresiva para construir un agente desde cero, desde un simple bucle hasta la ejecución autónoma aislada.diff --git a/README-FR.md b/README-FR.mdnew file mode 100644index 0000000..81db7a6--- /dev/null+++ b/README-FR.md@@ -0,0 +1,578 @@+<p align="center">+ <a href="./README.md"><img alt="English" src="https://img.shields.io/badge/EN-English-blue?style=flat-square"></a>+ <a href="./README-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/ZH-简体中文-red?style=flat-square"></a>+ <a href="./README-ZH-TW.md"><img alt="繁體中文" src="https://img.shields.io/badge/ZH--TW-繁體中文-orange?style=flat-square"></a>+ <a href="./README-JA.md"><img alt="日本語" src="https://img.shields.io/badge/JA-日本語-green?style=flat-square"></a>+ <a href="./README-KO.md"><img alt="한국어" src="https://img.shields.io/badge/KO-한국어-blueviolet?style=flat-square"></a>+ <a href="./README-ES.md"><img alt="Español" src="https://img.shields.io/badge/ES-Español-yellow?style=flat-square"></a>+ <a href="./README-FR.md"><img alt="Français" src="https://img.shields.io/badge/FR-Français-007EC6?style=flat-square"></a>+ <a href="./README-RU.md"><img alt="Русский" src="https://img.shields.io/badge/RU-Русский-informational?style=flat-square"></a>+ <a href="./README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/DE-Deutsch-2EA043?style=flat-square"></a>+ <a href="./README-AR.md"><img alt="العربية" src="https://img.shields.io/badge/AR-العربية-success?style=flat-square"></a>+ <a href="./README-VI.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/VI-Tiếng_Việt-cc6699?style=flat-square"></a>+ <a href="./README-UZ.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>+</p>++# Learn Harness Engineering++> **Un cours basé sur des projets consacré à la construction de l'environnement, de la gestion d'état, de la vérification et des mécanismes de contrôle qui permettent aux agents de codage IA de fonctionner de manière fiable.**++Learn Harness Engineering est un cours dédié à l'ingénierie des agents de codage IA. Nous avons étudié et synthétisé en profondeur les théories et pratiques les plus avancées en matière de Harness Engineering dans l'industrie. Nos références principales incluent :++- [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)++> **Démarrage rapide ?** Le skill [`skills/harness-creator/`](../../skills/) peut vous aider à générer un harness de niveau production (AGENTS.md, listes de fonctionnalités, init.sh, flux de vérification) pour votre propre projet en quelques minutes.++---++## Table des Matières++- [Aperçu Visuel](#aperçu-visuel)+- [Ce que signifie réellement Harness Engineering](#ce-que-signifie-réellement-harness-engineering)+- [Démarrage Rapide : Améliorez votre agent dès aujourd'hui](#démarrage-rapide--améliorez-votre-agent-dès-aujourdhui)+- [Projet Final : Une véritable application](#projet-final--une-véritable-application)+- [Parcours d'Apprentissage](#parcours-dapprentissage)+- [Programme d'Études](#programme-détudes)+- [Skills](#skills)+- [Autres Cours](#autres-cours)++---++## Aperçu Visuel++### Page d'Accueil du Cours+> Un plan de cours complet et une introduction aux philosophies fondamentales, offrant un chemin clair pour commencer.++++### Cours Immersifs+> Des plongées approfondies dans les problèmes concrets et des projets pratiques (comme le Projet 01) pour une expérience d'apprentissage immersive.++++### Bibliothèque de Ressources Prête à l'Emploi+> Des modèles et des configurations de référence conçus pour résoudre les problèmes courants dans le développement d'agents IA multi-tours, tels que la perte de contexte et l'achèvement prématuré des tâches.++++## Livres de Cours en PDF++Le dépôt inclut désormais un pipeline de génération de PDF pour le contenu du cours.++- Exécutez `npm run pdf:build` pour générer les PDF en anglais et en chinois localement.+- Les fichiers de sortie sont écrits dans `artifacts/pdfs/`.+- Exécutez `npm run screenshots:readme` si vous souhaitez mettre à jour les images d'aperçu du README.+- Le workflow GitHub Actions [`release-course-pdfs.yml`](../../.github/workflows/release-course-pdfs.yml) peut construire les PDF et les publier sur les Releases GitHub.++---++## Le modèle est intelligent, le harness le rend fiable++Il y a une dure vérité que la plupart des gens apprennent à leurs dépens : **le modèle le plus puissant au monde échouera toujours sur de vraies tâches d'ingénierie si vous ne construisez pas un environnement approprié autour de lui.**++Vous l'avez probablement constaté vous-même. Vous donnez une tâche à Claude ou GPT dans votre dépôt. Cela commence bien -- il lit des fichiers, écrit du code, semble productif. Puis quelque chose tourne mal. Il saute une étape. Il casse un test. Il dit « terminé » mais rien ne fonctionne vraiment. Vous passez plus de temps à corriger qu si vous l'aviez fait vous-même.++Ce n'est pas un problème de modèle. C'est un problème de harness.++Les preuves sont claires. Anthropic a mené une expérience contrôlée : même modèle (Opus 4.5), même prompt (« construis un éditeur de jeux rétro 2D »). Sans harness, il a dépensé 9 $ en 20 minutes et a produit quelque chose qui ne fonctionnait pas. Avec un harness complet (planificateur + générateur + évaluateur), il a dépensé 200 $ en 6 heures et a construit un jeu auquel on pouvait réellement jouer. Le modèle n'a pas changé. Le harness, oui.++OpenAI a rapporté la même chose avec Codex : dans un dépôt bien équipé d'un harness, le même modèle passe de « peu fiable » à « fiable ». Pas une amélioration marginale -- un changement qualitatif.++**Ce cours vous apprend à construire cet environnement.**++```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+```++---++## Ce que signifie réellement Harness Engineering++Le Harness Engineering consiste à construire un environnement de travail complet autour du modèle pour qu'il produise des résultats fiables. Il ne s'agit pas d'écrire de meilleurs prompts. Il s'agit de concevoir le système dans lequel le modèle opère.++Un harness comporte cinq sous-systèmes :++```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.+```++Chaque sous-système a une seule responsabilité :++- **Instructions** -- Indiquent à l'agent ce qu'il doit faire, dans quel ordre, et ce qu'il doit lire avant de commencer. Pas un fichier gigantesque ; une structure à divulgation progressive que l'agent navigue selon ses besoins.+- **State** -- Suivi de ce qui a été fait, de ce qui est en cours et de ce qui reste à faire. Les données sont persistées sur disque pour que la prochaine session reprenne exactement là où la précédente s'est arrêtée.+- **Verification** -- Seul un jeu de tests qui passe constitue une preuve. L'agent ne peut pas déclarer victoire sans une preuve exécutable.+- **Scope** -- Limite l'agent à une seule fonctionnalité à la fois. Pas de surcharge. Pas de trois choses à moitié terminées. Pas de réécriture de la liste de fonctionnalités pour masquer le travail inachevé.+- **Session Lifecycle** -- Initialisation au démarrage. Nettoyage à la fin. Laisser un chemin de redémarrage propre pour la prochaine session.++---++## Pourquoi ce cours existe++La question n'est pas « les modèles peuvent-ils écrire du code ? » Ils le peuvent. La question est : **peuvent-ils accomplir de manière fiable de vraies tâches d'ingénierie dans de vrais dépôts, sur plusieurs sessions, sans supervision humaine constante ?**++Pour l'instant, la réponse est : pas sans un harness.++```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+```++Les questions auxquelles ce cours s'intéresse réellement :++- Quels modèles de harness améliorent les taux d'achèvement des tâches ?+- Quels modèles réduisent le retravail et les achèvements incorrects ?+- Quels mécanismes maintiennent une progression régulière des tâches de longue durée ?+- Quelles structures gardent le système maintenable après plusieurs exécutions de l'agent ?++---++## Programme d'Études et Documentation++Pour l'ensemble des matériaux du cours, veuillez visiter le **[Site de Documentation](https://walkinglabs.github.io/learn-harness-engineering/)**.++Le programme est divisé en trois parties :++1. **Cours magistraux** : 12 unités conceptuelles expliquant la théorie derrière le Harness Engineering.+2. **Projets** : 6 projets pratiques où vous construisez un espace de travail agentique à partir de zéro.+3. **Bibliothèque de Ressources** : Des modèles prêts à copier (`AGENTS.md`, `feature_list.json`, `init.sh`, etc.) à utiliser dans vos propres dépôts dès aujourd'hui.++---++## Démarrage Rapide : Améliorez votre agent dès aujourd'hui++Vous n'avez pas besoin de lire les 12 cours avant de commencer à en tirer profit. Si vous utilisez déjà un agent de codage sur un vrai projet, voici comment l'améliorer dès maintenant.++L'idée est simple : au lieu de simplement écrire des prompts, donnez à votre agent un ensemble de fichiers structurés qui définissent ce qu'il faut faire, ce qui a été fait et comment vérifier le travail. Ces fichiers résident dans votre dépôt, donc chaque session démarre depuis le même état.++```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+```++Récupérez les modèles de démarrage depuis la [Bibliothèque de Ressources](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) et déposez-les dans votre projet. C'est tout. Quatre fichiers, et vos sessions d'agent seront déjà nettement plus stables qu'avec des prompts seuls.++---++## Projet Final : Une véritable application++Les six projets du cours gravitent autour du même produit : **une application de bureau de base de connaissances personnelle basée sur Electron**.++```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+```++Ce projet a été choisi car il combine une forte valeur pratique, une complexité produit suffisante pour le monde réel et un bon cadre pour observer les améliorations avant/après harness.++Le starter/solution de chaque projet du cours est une copie complète de cette application Electron à ce stade d'évolution. Le starter de P(N+1) est dérivé de la solution de P(N) -- l'application évolue au fur et à mesure que vos compétences en harness se développent.++---++## Parcours d'Apprentissage++Le cours est conçu pour être suivi dans l'ordre. Chaque phase s'appuie sur la précédente.++```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)+```++Chaque phase prend environ une semaine si vous suivez le cours à temps partiel. Si vous souhaitez aller plus vite, les phases 1 à 3 peuvent être effectuées en un long week-end.++---++## Programme d'Études++### Cours magistraux -- 12 unités conceptuelles, chacune répondant à une question fondamentale++*Lisez le texte complet de chaque cours sur le [Site de Documentation](https://walkinglabs.github.io/learn-harness-engineering/).*++| Session | Question | Idée Centrale |+|---------|----------|---------------|+| [L01](../../docs/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Pourquoi les modèles performants échouent-ils encore sur des tâches réelles ? | L'écart de capacité entre les benchmarks et l'ingénierie réelle |+| [L02](../../docs/lectures/lecture-02-what-a-harness-actually-is/index.md) | Que signifie réellement « harness » ? | Cinq sous-systèmes : instructions, état, vérification, portée, cycle de vie |+| [L03](../../docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Pourquoi le dépôt doit-il être l'unique source de vérité ? | Si l'agent ne peut pas le voir, ça n'existe pas |+| [L04](../../docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Pourquoi un seul fichier d'instructions géant échoue-t-il ? | Divulgation progressive : donnez une carte, pas une encyclopédie |+| [L05](../../docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Pourquoi les tâches de longue durée perdent-elles leur continuité ? | Persister le progrès sur disque ; reprendre là où vous vous êtes arrêté |+| [L06](../../docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Pourquoi l'initialisation nécessite-t-elle sa propre phase ? | Vérifier que l'environnement est sain avant que l'agent ne commence à travailler |+| [L07](../../docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Pourquoi les agents vont-ils trop loin et n'en font-ils pas assez ? | Une seule fonctionnalité à la fois ; définition explicite de « terminé » |+| [L08](../../docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Pourquoi les listes de fonctionnalités sont-elles des primitives du harness ? | Des limites de portée lisibles par machine que l'agent ne peut pas ignorer |+| [L09](../../docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Pourquoi les agents déclarent-ils victoire trop tôt ? | Lacunes de vérification : confiance ≠ correction |+| [L10](../../docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Pourquoi les tests de bout en bout changent-ils les résultats ? | Seule une exécution complète du pipeline compte comme véritable vérification |+| [L11](../../docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Pourquoi l'observabilité appartient-elle au harness ? | Si vous ne pouvez pas voir ce que l'agent a fait, vous ne pouvez pas corriger ce qu'il a cassé |+| [L12](../../docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Pourquoi chaque session doit-elle laisser un état propre ? | Le succès de la prochaine session dépend du nettoyage de celle-ci |++### Projets -- 6 projets pratiques appliquant les méthodes des cours à la même application Electron++| Projet | Ce que vous faites | Mécanisme du Harness |+|--------|--------------------|----------------------|+| [P01](../../docs/projects/project-01-baseline-vs-minimal-harness/index.md) | Exécuter la même tâche deux fois : avec prompts seuls vs. avec règles d'abord | Harness minimal : AGENTS.md + init.sh + feature_list.json |+| [P02](../../docs/projects/project-02-agent-readable-workspace/index.md) | Restructurer le dépôt pour que l'agent puisse le lire | Espace de travail lisible par l'agent + fichiers d'état persistants |+| [P03](../../docs/projects/project-03-multi-session-continuity/index.md) | Faire en sorte que l'agent reprenne là où il s'est arrêté | Journal de progression + transfert de session + continuité multi-sessions |+| [P04](../../docs/projects/project-04-incremental-indexing/index.md) | Empêcher l'agent d'en faire trop ou pas assez | Retour d'exécution + contrôle de portée + indexation incrémentale |+| [P05](../../docs/projects/project-05-grounded-qa-verification/index.md) | Faire en sorte que l'agent vérifie son propre travail | Auto-vérification + Q&A fondé + achèvement basé sur les preuves |+| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | Construire un harness complet à partir de zéro (projet final) | Harness complet : tous les mécanismes + observabilité + étude d'ablation |++```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.+```++### Bibliothèque de Ressources++- [English](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) — templates, checklists, and method references+- [简体中文](https://walkinglabs.github.io/learn-harness-engineering/zh/resources/) — 中文模板、清单和方法参考+- [繁體中文](https://walkinglabs.github.io/learn-harness-engineering/zh-TW/resources/) — 繁體中文範本、清單和方法參考+- [日本語](https://walkinglabs.github.io/learn-harness-engineering/ja/resources/) — テンプレート、チェックリスト、方法リファレンス+- [한국어](https://walkinglabs.github.io/learn-harness-engineering/ko/resources/) — 템플릿, 체크리스트, 방법 참고 자료+- [Español](https://walkinglabs.github.io/learn-harness-engineering/es/resources/) — plantillas, listas de verificación y referencias+- [Français](https://walkinglabs.github.io/learn-harness-engineering/fr/resources/) — modèles, listes de contrôle et références+- [Русский](https://walkinglabs.github.io/learn-harness-engineering/ru/resources/) — шаблоны, чек-листы и справочники+- [Deutsch](https://walkinglabs.github.io/learn-harness-engineering/de/resources/) — Vorlagen, Checklisten und Referenzen+- [العربية](https://walkinglabs.github.io/learn-harness-engineering/ar/resources/) — قوالب، قوائم تحقق ومراجع+- [Tiếng Việt](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+- [Oʻzbekcha](https://walkinglabs.github.io/learn-harness-engineering/uz/resources/) — andozalar, tekshiruv roʻyxatlari va maʼlumotnomalar++---++## Le Cycle de Vie de la Session de l'Agent++L'une des idées centrales de ce cours : **la session de l'agent doit suivre un cycle de vie structuré, pas être laissée au hasard.** Voici à quoi cela ressemble :++```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."+```++---++## À qui ce cours s'adresse++Ce cours est destiné :++- Aux ingénieurs utilisant déjà des agents de codage et souhaitant une meilleure stabilité et qualité+- Aux chercheurs ou constructeurs souhaitant une compréhension systématique de la conception de harness+- Aux responsables techniques qui doivent comprendre comment la conception de l'environnement affecte les performances de l'agent++Ce cours n'est PAS destiné :++- Aux personnes cherchant une introduction à l'IA sans code+- Aux personnes qui ne s'intéressent qu'aux prompts et ne prévoient pas de construire de véritables implémentations+- Aux apprenants non préparés à laisser des agents travailler dans de vrais dépôts++---++## Prérequis++Il faut au moins l'un de ces outils :++- Claude Code+- Codex+- Un autre agent de codage IDE ou CLI prenant en charge l'édition de fichiers, l'exécution de commandes et les tâches multi-étapes++Le cours suppose que vous êtes capable de :++- Ouvrir un dépôt local+- Autoriser l'agent à modifier des fichiers+- Autoriser l'agent à exécuter des commandes+- Inspecter les résultats et réexécuter les tâches++Si vous ne disposez pas d'un tel outil, vous pouvez toujours lire le contenu du cours, mais vous ne pourrez pas réaliser les projets comme prévu.++---++## Aperçu Local++Ce dépôt utilise VitePress comme visualiseur de documentation.++```sh+npm install+npm run docs:dev # Serveur de développement avec rechargement à chaud+npm run docs:build # Build de production+npm run docs:preview # Aperçu du site construit+```++Ouvrez ensuite l'URL locale affichée par VitePress dans votre navigateur.++---++## Prérequis Techniques++Requis :++- Familiarité avec le terminal, git et les environnements de développement local+- Capacité à lire et écrire du code dans au moins une pile applicative courante+- Expérience de base en débogage logiciel (lecture de logs, tests et comportement à l'exécution)+- Assez de temps à consacrer à un cours axé sur l'implémentation++Utile mais non requis :++- Expérience avec Electron, les applications de bureau ou les outils local-first+- Formation en tests, logging ou architecture logicielle+- Exposition préalable à Codex, Claude Code ou à des agents de codage similaires++---++## Références Principales++Primaires :++- [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)+- [OpenAI : Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/)+- [Anthropic : Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)+- [LangChain : Improving Deep Agents with harness engineering](https://www.langchain.com/blog/improving-deep-agents-with-harness-engineering)+- [Thoughtworks / Martin Fowler : Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)+- [Cursor : Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)++Consultez la liste complète de références en couches dans [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md).++---++## Structure du Dépôt++```text+learn-harness-engineering/+├── docs/ # Site de documentation VitePress+│ ├── lectures/ # 12 cours (index.md + exemples dans code/)+│ │ ├── lecture-01-*/+│ │ ├── lecture-02-*/+│ │ └── ... (12 au total)+│ ├── projects/ # 6 descriptions de projets+│ │ ├── project-01-*/+│ │ └── ... (6 au total)+│ └── resources/ # Modèles et références multilingues+│ ├── en/ # Modèles, listes de contrôle et guides en anglais+│ ├── zh/ # Modèles, listes de contrôle et guides en chinois+│ ├── ru/ # Modèles, listes de contrôle et guides en russe+│ └── vi/ # Modèles, listes de contrôle et guides en vietnamien+├── projects/+│ ├── shared/ # Fondation partagée Electron + TypeScript + React+│ └── project-NN/ # Répertoires starter/ et solution/ par projet+├── skills/ # Skills réutilisables pour agents IA+│ └── harness-creator/ # Skill de Harness Engineering+├── package.json # VitePress + outils de développement+└── CLAUDE.md # Instructions Claude Code pour ce dépôt+```++---++## Comment le cours est organisé++- Chaque cours se concentre sur une seule question+- Le cours comprend 6 projets+- Chaque projet nécessite que l'agent effectue un véritable travail+- Chaque projet compare les résultats avec un harness faible vs. un harness robuste+- Ce qui compte, c'est la différence mesurée, pas la quantité de documentation rédigée++---++## Skills++Ce dépôt inclut également des skills réutilisables pour agents IA que vous pouvez installer directement dans votre IDE ou espace de travail agentique.++- [**harness-creator**](../../skills/harness-creator/) : Un skill qui vous aide à générer un harness de niveau production pour votre propre projet en quelques minutes.++---++## Autres Cours++Notre équipe a également créé d'autres cours ! Découvrez-les :++[](https://github.com/walkinglabs/hands-on-modern-rl)++**Hands-on Modern RL** : Un programme pratique et open source qui comble le fossé entre les concepts de base de l'apprentissage par renforcement et l'alignement des LLM, le RLVR et les systèmes agentiques avancés.++---++## Historique des Étoiles++[](https://www.star-history.com/#walkinglabs/learn-harness-engineering&type=date&legend=top-left)++---++## Remerciements++Ce cours a été inspiré par et puise ses idées dans [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) -- un guide progressif pour construire un agent à partir de zéro, d'une simple boucle à l'exécution autonome isolée.diff --git a/README-JA.md b/README-JA.mdnew file mode 100644index 0000000..3ae645d--- /dev/null+++ b/README-JA.md@@ -0,0 +1,580 @@+<p align="center">+ <a href="./README.md"><img alt="English" src="https://img.shields.io/badge/EN-English-blue?style=flat-square"></a>+ <a href="./README-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/ZH-简体中文-red?style=flat-square"></a>+ <a href="./README-ZH-TW.md"><img alt="繁體中文" src="https://img.shields.io/badge/ZH--TW-繁體中文-orange?style=flat-square"></a>+ <a href="./README-JA.md"><img alt="日本語" src="https://img.shields.io/badge/JA-日本語-green?style=flat-square"></a>+ <a href="./README-KO.md"><img alt="한국어" src="https://img.shields.io/badge/KO-한국어-blueviolet?style=flat-square"></a>+ <a href="./README-ES.md"><img alt="Español" src="https://img.shields.io/badge/ES-Español-yellow?style=flat-square"></a>+ <a href="./README-FR.md"><img alt="Français" src="https://img.shields.io/badge/FR-Français-007EC6?style=flat-square"></a>+ <a href="./README-RU.md"><img alt="Русский" src="https://img.shields.io/badge/RU-Русский-informational?style=flat-square"></a>+ <a href="./README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/DE-Deutsch-2EA043?style=flat-square"></a>+ <a href="./README-AR.md"><img alt="العربية" src="https://img.shields.io/badge/AR-العربية-success?style=flat-square"></a>+ <a href="./README-VI.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/VI-Tiếng_Việt-cc6699?style=flat-square"></a>+ <a href="./README-UZ.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>+</p>++# Learn Harness Engineering++> **AIコーディングエージェントを確実に動作させるための環境、状態管理、検証、制御メカニズムを構築するプロジェクトベースのコース。**++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/) スキルを使えば、自分のプロジェクト向けに本格的なハーネス(AGENTS.md、機能リスト、init.sh、検証ワークフロー)を数分でスキャフォールドできます。++---++## 目次++- [✨ ビジュアルプレビュー](#-ビジュアルプレビュー)+- [Harness Engineering が本当に意味すること](#harness-engineering-が本当に意味すること)+- [クイックスタート:今日からエージェントを改善する](#クイックスタート今日からエージェントを改善する)+- [カプロジェクト:実際のアプリケーション](#カプロジェクト実際のアプリケーション)+- [学習パス](#学習パス)+- [シラバス](#シラバス)+- [スキル](#スキル)+- [その他のコース](#その他のコース)++---++## ✨ ビジュアルプレビュー++### 🏠 コースホームページ+> 包括的なコース概要とコア思想の紹介により、明確なスタートパスを提供します。++++### 📖 没入型レクチャー+> 実際の課題とハンズオンプロジェクト(プロジェクト01など)の深い解説により、没入型の学習体験を提供します。++++### 🗂️ すぐに使えるリソースライブラリ+> マルチターンAIエージェント開発における一般的な落とし穴(コンテキストの損失やタスクの早期完了など)を解決するために設計されたテンプレートと参照設定。++++## 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 にリポジトリでタスクを与えます。最初はうまくいきます — ファイルを読み、コードを書き、生産的に見えます。しかし、どこかで問題が発生します。ステップを飛ばします。テストを壊します。「完了」と言いますが、実際には何も動いていません。自分でやった以上に修正に時間を費やすことになります。++これはモデルの問題ではありません。ハーネスの問題です。++証拠は明確です。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 が本当に意味すること++Harness Engineering は、モデルの周囲に完全な作業環境を構築し、信頼性の高い結果を生成させることです。より良いプロンプトを書くことではありません。モデルが内部で動作するシステムを設計することです。++ハーネスには5つのサブシステムがあります:++```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** — エージェントに何を、どの順序で、開始前に何を読むべきかを伝えます。一つの巨大なファイルではなく、エージェントが必要に応じてナビゲートする段階的開示構造です。+- **State** — 何が完了し、何が進行中で、何が次かを追跡します。ディスクに永続化され、次のセッションは前回の続きから正確に再開できます。+- **Verification** — 合格したテストスイートのみが証拠として認められます。エージェントは実行可能な証拠なしに完了を宣言できません。+- **Scope** — エージェントを一度に一つの機能に制約します。過剰な範囲拡大なし。3つのことを中途半端に終わらせることなし。未完了の作業を隠すために機能リストを書き換えることなし。+- **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/)** をご覧ください。++カリキュラムは3つの部分に分かれています:++1. **レクチャー**:Harness Engineering の背景理論を説明する12の概念ユニット。+2. **プロジェクト**:ゼロからエージェントワークスペースを構築する6つのハンズオンプロジェクト。+3. **リソースライブラリ**:自分のリポジトリで今日すぐ使えるコピー用テンプレート(`AGENTS.md`、`feature_list.json`、`init.sh` など)。++---++## クイックスタート:今日からエージェントを改善する++価値を得るために12のレクチャーをすべて読む必要はありません。すでに実際のプロジェクトでコーディングエージェントを使用している場合、今すぐ改善する方法は以下の通りです。++アイデアはシンプルです:プロンプトを書く代わりに、何をすべきか、何が完了しているか、作業をどう検証するかを定義する構造化ファイルのセットをエージェントに与えます。これらのファイルはリポジトリ内に存在するため、すべてのセッションが同じ状態から始まります。++```text+ YOUR PROJECT ROOT+ ├── AGENTS.md <-- エージェントの操作マニュアル+ ├── CLAUDE.md <-- (代替、Claude Code を使用する場合)+ ├── init.sh <-- install + verify + start を実行+ ├── feature_list.json <-- 存在する機能、完了している機能+ ├── claude-progress.md <-- 各セッションで何が起きたか+ └── src/ <-- 実際のコード+```++[リソースライブラリ](https://walkinglabs.github.io/learn-harness-engineering/en/resources/)からスターターテンプレートを取得し、プロジェクトに配置してください。たったこれだけです。4つのファイルで、プロンプトだけで実行するよりもエージェントセッションが大幅に安定します。++---++## カプロジェクト:実際のアプリケーション++6つのコースプロジェクトはすべて同じ製品を中心に展開しています:**Electron ベースの個人ナレッジベースデスクトップアプリ**です。++```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) | 「ハーネス」とは実際何を意味するのか? | 5つのサブシステム:インストラクション、状態、検証、スコープ、ライフサイクル |+| [L03](../../docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | なぜリポジトリが唯一の信頼できる情報源でなければならないのか? | エージェントが見られないものは存在しない |+| [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) | なぜ長時間実行タスクは連続性を失うのか? | 進捗をディスクに永続化し、前回の続きから再開する |+| [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) | なぜオブザーバビリティはハーネス内にあるべきなのか? | エージェントが何をしたか見えなければ、何を壊したか修正できない |+| [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) | 同じタスクを2回実行:プロンプトのみ 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) | エージェントが前回の続きから再開できるようにする | 進捗ログ + セションハンドオフ + マルチセッション連続性 |+| [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.+```++### リソースライブラリ++- [English](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) — templates, checklists, and method references+- [简体中文](https://walkinglabs.github.io/learn-harness-engineering/zh/resources/) — 中文模板、清单和方法参考+- [繁體中文](https://walkinglabs.github.io/learn-harness-engineering/zh-TW/resources/) — 繁體中文範本、清單和方法參考+- [日本語](https://walkinglabs.github.io/learn-harness-engineering/ja/resources/) — テンプレート、チェックリスト、方法リファレンス+- [한국어](https://walkinglabs.github.io/learn-harness-engineering/ko/resources/) — 템플릿, 체크리스트, 방법 참고 자료+- [Español](https://walkinglabs.github.io/learn-harness-engineering/es/resources/) — plantillas, listas de verificación y referencias+- [Français](https://walkinglabs.github.io/learn-harness-engineering/fr/resources/) — modèles, listes de contrôle et références+- [Русский](https://walkinglabs.github.io/learn-harness-engineering/ru/resources/) — шаблоны, чек-листы и справочники+- [Deutsch](https://walkinglabs.github.io/learn-harness-engineering/de/resources/) — Vorlagen, Checklisten und Referenzen+- [العربية](https://walkinglabs.github.io/learn-harness-engineering/ar/resources/) — قوالب، قوائم تحقق ومراجع+- [Tiếng Việt](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+- [Oʻzbekcha](https://walkinglabs.github.io/learn-harness-engineering/uz/resources/) — andozalar, tekshiruv roʻyxatlari va maʼlumotnomalar++---++## エージェントセッションライフサイクル++このコースのコアアイデアの一つ:**エージェントのセッションは自由放任ではなく、構造化されたライフサイクルに従うべきです。** どのようなものか:++```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 入門を求める方+- プロンプトにしか関心がなく、実際の実装を構築する予定のない方+- エージェントを実際のリポジトリ内で動かす準備ができていない学習者++---++## 必要なツール++このコースでは実際にコーディングエージェントを動かします。++以下のツールのうち少なくとも1つが必要です:++- Claude Code+- Codex+- ファイル編集、コマンド実行、マルチステップタスクをサポートする他の IDE または CLI コーディングエージェント++このコースでは以下ができることを前提としています:++- ローカルリポジトリを開く+- エージェントにファイルの編集を許可する+- エージェントにコマンドの実行を許可する+- 出力を確認し、タスクを再実行する++このようなツールがない場合でも、コースコンテンツを読むことはできますが、プロジェクトを意図通りに完了することはできません。++---++## ローカルプレビュー++このリポジトリは VitePress をドキュメントビューアとして使用しています。++```sh+npm install+npm run docs:dev # ホットリロード付き開発サーバー+npm run docs:build # プロダクションビルド+npm run docs:preview # ビルド済みサイトのプレビュー+```++その後、VitePress が出力するローカル URL をブラウザで開いてください。++---++## 前提条件++必須:++- ターミナル、git、ローカル開発環境に慣れていること+- 少なくとも1つの一般的なアプリケーションスタックでコードの読み書きができること+- 基本的なソフトウェアデバッグ経験(ログ、テスト、ランタイム動作の読み取り)+- 実装重視のコースワークに十分な時間を投入できること++あれば役立つが必須ではない:++- 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)+- [OpenAI: Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/)+- [Anthropic: Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)+- [LangChain: Improving Deep Agents with harness engineering](https://www.langchain.com/blog/improving-deep-agents-with-harness-engineering)+- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)+- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)++完全な階層別参考文献リストは [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md) をご覧ください。++---++## リポジトリ構造++```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/ # Harness Engineering スキル+├── package.json # VitePress + 開発ツール+└── CLAUDE.md # このリポジトリの Claude Code 指示+```++---++## コースの構成++- 各レクチャーは一つの問いに焦点を当てる+- コースには6つのプロジェクトが含まれる+- すべてのプロジェクトでエージェントが実際の作業を行う+- すべてのプロジェクトで弱いハーネスと強いハーネスの結果を比較する+- 重要なのは測定された差であり、書かれたドキュメントの数ではない++---++## スキル++このリポジトリには、IDE やエージェントワークスペースに直接インストールできる再利用可能な AI エージェントスキルも含まれています。++- [**harness-creator**](../../skills/harness-creator/): 自分のプロジェクト向けに本格的なハーネスを数分でスキャフォールドするスキル。++---++## その他のコース++私たちのチームは他のコースも作成しています!ぜひご覧ください:++[](https://github.com/walkinglabs/hands-on-modern-rl)++**Hands-on Modern RL**:基本的な強化学習の概念から LLM アライメント、RLVR、高度なエージェントシステムまでをつなぐ、オープンソースのハンズオンカリキュラム。++---++## スター履歴++[](https://www.star-history.com/#walkinglabs/learn-harness-engineering&type=date&legend=top-left)++---++## 謝辞++このコースは [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) にインスピレーションを受け、アイデアを得ています — 単一のループから独立した自律実行まで、ゼロからエージェントを構築する段階的ガイド。diff --git a/README-KO.md b/README-KO.mdindex 1a5105f..53da38d 100644--- a/README-KO.md+++ b/README-KO.md@@ -1,16 +1,16 @@<p align="center"><a href="./README.md"><img alt="English" src="https://img.shields.io/badge/EN-English-blue?style=flat-square"></a><a href="./README-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/ZH-简体中文-red?style=flat-square"></a>- <a href="./docs-readme/zh-TW/README.md"><img alt="繁體中文" src="https://img.shields.io/badge/ZH--TW-繁體中文-orange?style=flat-square"></a>- <a href="./docs-readme/ja-JP/README.md"><img alt="日本語" src="https://img.shields.io/badge/JA-日本語-green?style=flat-square"></a>- <img alt="한국어" src="https://img.shields.io/badge/KO-한국어-blueviolet?style=flat-square">- <a href="./docs-readme/es-ES/README.md"><img alt="Español" src="https://img.shields.io/badge/ES-Español-yellow?style=flat-square"></a>- <a href="./docs-readme/fr-FR/README.md"><img alt="Français" src="https://img.shields.io/badge/FR-Français-007EC6?style=flat-square"></a>- <a href="https://walkinglabs.github.io/learn-harness-engineering/ru/"><img alt="Русский" src="https://img.shields.io/badge/RU-Русский-informational?style=flat-square"></a>- <a href="./docs-readme/de-DE/README.md"><img alt="Deutsch" src="https://img.shields.io/badge/DE-Deutsch-2EA043?style=flat-square"></a>- <a href="./docs-readme/ar-SA/README.md"><img alt="العربية" src="https://img.shields.io/badge/AR-العربية-success?style=flat-square"></a>- <a href="./docs-readme/vi-VN/README.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/VI-Tiếng_Việt-cc6699?style=flat-square"></a>- <a href="https://walkinglabs.github.io/learn-harness-engineering/uz/"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>+ <a href="./README-ZH-TW.md"><img alt="繁體中文" src="https://img.shields.io/badge/ZH--TW-繁體中文-orange?style=flat-square"></a>+ <a href="./README-JA.md"><img alt="日本語" src="https://img.shields.io/badge/JA-日本語-green?style=flat-square"></a>+ <a href="./README-KO.md"><img alt="한국어" src="https://img.shields.io/badge/KO-한국어-blueviolet?style=flat-square"></a>+ <a href="./README-ES.md"><img alt="Español" src="https://img.shields.io/badge/ES-Español-yellow?style=flat-square"></a>+ <a href="./README-FR.md"><img alt="Français" src="https://img.shields.io/badge/FR-Français-007EC6?style=flat-square"></a>+ <a href="./README-RU.md"><img alt="Русский" src="https://img.shields.io/badge/RU-Русский-informational?style=flat-square"></a>+ <a href="./README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/DE-Deutsch-2EA043?style=flat-square"></a>+ <a href="./README-AR.md"><img alt="العربية" src="https://img.shields.io/badge/AR-العربية-success?style=flat-square"></a>+ <a href="./README-VI.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/VI-Tiếng_Việt-cc6699?style=flat-square"></a>+ <a href="./README-UZ.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a></p># Learn Harness Engineeringdiff --git a/README-VI.md b/README-VI.mdnew file mode 100644index 0000000..e869e3a--- /dev/null+++ b/README-VI.md@@ -0,0 +1,580 @@+<p align="center">+ <a href="./README.md"><img alt="English" src="https://img.shields.io/badge/EN-English-blue?style=flat-square"></a>+ <a href="./README-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/ZH-简体中文-red?style=flat-square"></a>+ <a href="./README-ZH-TW.md"><img alt="繁體中文" src="https://img.shields.io/badge/ZH--TW-繁體中文-orange?style=flat-square"></a>+ <a href="./README-JA.md"><img alt="日本語" src="https://img.shields.io/badge/JA-日本語-green?style=flat-square"></a>+ <a href="./README-KO.md"><img alt="한국어" src="https://img.shields.io/badge/KO-한국어-blueviolet?style=flat-square"></a>+ <a href="./README-ES.md"><img alt="Español" src="https://img.shields.io/badge/ES-Español-yellow?style=flat-square"></a>+ <a href="./README-FR.md"><img alt="Français" src="https://img.shields.io/badge/FR-Français-007EC6?style=flat-square"></a>+ <a href="./README-RU.md"><img alt="Русский" src="https://img.shields.io/badge/RU-Русский-informational?style=flat-square"></a>+ <a href="./README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/DE-Deutsch-2EA043?style=flat-square"></a>+ <a href="./README-AR.md"><img alt="العربية" src="https://img.shields.io/badge/AR-العربية-success?style=flat-square"></a>+ <a href="./README-VI.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/VI-Tiếng_Việt-cc6699?style=flat-square"></a>+ <a href="./README-UZ.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>+</p>++# Learn Harness Engineering++> **Khóa học dựa trên dự án về xây dựng môi trường, quản lý trạng thái, cơ chế kiểm chứng và điều khiển giúp các agent viết code AI hoạt động đáng tin cậy.**++Learn Harness Engineering là một khóa học dành riêng cho kỹ thuật liên quan đến các agent viết code AI. Chúng tôi đã nghiên cứu sâu và tổng hợp các lý thuyết và thực tiễn Harness Engineering tiên tiến nhất trong ngành. Các tài liệu tham khảo cốt lõi của chúng tôi bao gồm:++- [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)++> **Bắt đầu nhanh?** Skill [`skills/harness-creator/`](../../skills/) có thể giúp bạn tạo nhanh một harness cấp sản xuất (AGENTS.md, feature lists, init.sh, quy trình kiểm chứng) cho dự án của riêng bạn chỉ trong vài phút.++---++## Mục lục++- [Xem trước trực quan](#xem-trước-trực-quan)+- [Harness Engineering thực sự có nghĩa là gì](#harness-engineering-thực-sự-có-nghĩa-là-gì)+- [Bắt đầu nhanh: Cải thiện Agent của bạn ngay hôm nay](#bắt-đầu-nhanh-cải-thiện-agent-của-bạn-ngay-hôm-nay)+- [Dự án tổng kết: Một ứng dụng thực tế](#dự-án-tổng-kết-một-ứng-dụng-thực-tế)+- [Lộ trình học tập](#lộ-trình-học-tập)+- [Giáo trình](#giáo-trình)+- [Skills](#skills)+- [Các khóa học khác](#các-khóa-học-khác)++---++## Xem trước trực quan++### Trang chủ khóa học+> Tổng quan khóa học toàn diện và giới thiệu về các triết lý cốt lõi, cung cấp lộ trình rõ ràng để bắt đầu.++++### Bài giảng nhập môn+> Đi sâu vào các vấn đề thực tế và dự án thực hành (như Dự án 01) mang đến trải nghiệm học tập nhập môn.++++### Thư viện tài nguyên sẵn sàng sử dụng+> Các mẫu và cấu hình tham khảo được thiết kế để giải quyết các vấn đề phổ biến trong phát triển agent AI nhiều lượt, chẳng hạn như mất ngữ cảnh và hoàn thành tác vụ quá sớm.++++## Sách giáo trình PDF++Kho lưu trữ hiện đã bao gồm quy trình xây dựng PDF cho nội dung khóa học.++- Chạy `npm run pdf:build` để tạo PDF tiếng Anh và tiếng Trung tại máy cục bộ.+- Các tệp đầu ra được ghi vào `artifacts/pdfs/`.+- Chạy `npm run screenshots:readme` nếu bạn muốn làm mới hình ảnh xem trước README.+- GitHub Actions workflow [`release-course-pdfs.yml`](../../.github/workflows/release-course-pdfs.yml) có thể xây dựng PDF và xuất bản chúng lên GitHub Releases.++---++## Mô hình thì thông minh, Harness giúp nó đáng tin cậy++Có một sự thật khắc nghiệt mà hầu hết mọi người đều học theo cách khó khăn nhất: **mô hình mạnh nhất thế giới vẫn sẽ thất bại trên các tác vụ kỹ thuật thực tế nếu bạn không xây dựng một môi trường phù hợp xung quanh nó.**++Bạn có thể đã tự thấy điều này. Bạn giao một tác vụ cho Claude hoặc GPT trong kho mã của mình. Nó bắt đầu tốt — đọc tệp, viết code, trông có vẻ hiệu quả. Sau đó có điều gì đó sai. Nó bỏ qua một bước. Nó làm hỏng một bài kiểm tra. Nó nói "xong" nhưng thực tế không có gì hoạt động. Bạn dành nhiều thời gian hơn để dọn dẹp so với việc tự làm.++Đây không phải là vấn đề của mô hình. Đây là vấn đề của harness.++Bằng chứng là rõ ràng. Anthropic đã thực hiện một thí nghiệm đối chứng: cùng mô hình (Opus 4.5), cùng prompt ("xây dựng trình soạn thảo game retro 2D"). Không có harness, nó tiêu tốn 9 đô la trong 20 phút và tạo ra thứ gì đó không hoạt động. Với harness đầy đủ (planner + generator + evaluator), nó tiêu tốn 200 đô la trong 6 giờ và xây dựng một game mà bạn có thể thực sự chơi được. Mô hình không thay đổi. Harness đã thay đổi.++OpenAI cũng báo cáo điều tương tự với Codex: trong một kho mã được harness tốt, cùng mô hình chuyển từ "không đáng tin cậy" sang "đáng tin cậy." Không phải là cải thiện nhỏ — mà là sự chuyển đổi về chất.++**Khóa học này dạy bạn cách xây dựng môi trường đó.**++```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 thực sự có nghĩa là gì++Harness engineering là về việc xây dựng một môi trường làm việc hoàn chỉnh xung quanh mô hình để nó tạo ra kết quả đáng tin cậy. Nó không phải là về việc viết prompt tốt hơn. Nó là về việc thiết kế hệ thống mà mô hình hoạt động bên trong.++Một harness có năm hệ thống con:++```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.+```++Mỗi hệ thống con có một nhiệm vụ duy nhất:++- **Instructions** — Cho agent biết phải làm gì, theo thứ tự nào, và phải đọc gì trước khi bắt đầu. Không phải một tệp khổng lồ duy nhất; mà là cấu trúc tiết lộ dần mà agent điều hướng theo nhu cầu.+- **State** — Theo dõi những gì đã làm, những gì đang tiến hành, và những gì tiếp theo. Được lưu trữ trên đĩa để phiên tiếp theo tiếp tục chính xác nơi phiên trước đã dừng.+- **Verification** — Chỉ một bộ bài kiểm tra đạt mới được tính là bằng chứng. Agent không thể tuyên bố hoàn thành mà không có bằng chứng có thể chạy được.+- **Scope** — Giới hạn agent ở một tính năng tại một thời điểm. Không vượt quá phạm vi. Không hoàn thành một nửa ba việc. Không viết lại danh sách tính năng để che giấu công việc chưa hoàn thành.+- **Session Lifecycle** — Khởi tạo ở đầu. Dọn dẹp ở cuối. Để lại đường dẫn khởi động lại sạch cho phiên tiếp theo.++---++## Tại sao khóa học này tồn tại++Câu hỏi không phải là "mô hình có thể viết code không?" Chúng có thể. Câu hỏi là: **chúng có thể hoàn thành đáng tin cậy các tác vụ kỹ thuật thực tế bên trong các kho mã thực tế, qua nhiều phiên, mà không cần giám sát liên tục từ con người không?**++Hiện tại, câu trả lời là: không thể nếu không có harness.++```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+```++Những câu hỏi mà khóa học này thực sự quan tâm:++- Những thiết kế harness nào cải thiện tỷ lệ hoàn thành tác vụ?+- Những thiết kế nào giảm thiểu việc làm lại và hoàn thành không chính xác?+- Những cơ chế nào giữ cho các tác vụ chạy dài tiến triển ổn định?+- Những cấu trúc nào giữ cho hệ thống có thể bảo trì sau nhiều lần chạy agent?++---++## Giáo trình & Tài liệu khóa học++Để xem đầy đủ tài liệu khóa học, vui lòng truy cập **[Trang web Tài liệu](https://walkinglabs.github.io/learn-harness-engineering/)**.++Giáo trình được chia thành ba phần:++1. **Bài giảng**: 12 đơn vị khái niệm giải thích lý thuyết đằng sau harness engineering.+2. **Dự án**: 6 dự án thực hành nơi bạn xây dựng một không gian làm việc agentic từ đầu.+3. **Thư viện tài nguyên**: Các mẫu sẵn sàng sử dụng (`AGENTS.md`, `feature_list.json`, `init.sh`, v.v.) để sử dụng trong kho mã của riêng bạn ngay hôm nay.++---++## Bắt đầu nhanh: Cải thiện Agent của bạn ngay hôm nay++Bạn không cần phải đọc cả 12 bài giảng trước khi bắt đầu nhận được giá trị. Nếu bạn đang sử dụng một agent viết code trên một dự án thực tế, đây là cách cải thiện nó ngay bây giờ.++Ý tưởng rất đơn giản: thay vì chỉ viết prompt, hãy cho agent của bạn một bộ tệp có cấu trúc xác định phải làm gì, những gì đã làm, và cách kiểm chứng công việc. Các tệp này nằm trong kho mã của bạn, vì vậy mỗi phiên bắt đầu từ cùng một trạng thái.++```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+```++Lấy các mẫu khởi đầu từ [Thư viện tài nguyên](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) và đưa chúng vào dự án của bạn. Đó là tất cả. Bốn tệp, và các phiên agent của bạn sẽ đã ổn định hơn đáng kể so với việc chỉ chạy trên prompt.++---++## Dự án tổng kết: Một ứng dụng thực tế++Tất cả sáu dự án khóa học đều xoay quanh cùng một sản phẩm: **một ứng dụng desktop cơ sở tri thức cá nhân dựa trên Electron**.++```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+```++Dự án này được chọn vì nó kết hợp giá trị thực tế cao, đủ độ phức tạp sản phẩm thực tế, và môi trường tốt để quan sát sự cải thiện harness trước/sau.++Mỗi starter/solution của dự án khóa học là một bản sao hoàn chỉnh của ứng dụng Electron ở giai đoạn tiến hóa đó. Starter của P(N+1) được tạo từ solution của P(N) — ứng dụng tiến hóa khi kỹ năng harness của bạn phát triển.++---++## Lộ trình học tập++Khóa học được thiết kế để hoàn thành theo thứ tự. Mỗi giai đoạn xây dựng dựa trên giai đoạn trước.++```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)+```++Mỗi giai đoạn mất khoảng một tuần nếu bạn học bán thời gian. Nếu bạn muốn đi nhanh hơn, các giai đoạn 1-3 có thể hoàn thành trong một cuối tuần dài.++---++## Giáo trình++### Bài giảng — 12 đơn vị khái niệm, mỗi đơn vị trả lời một câu hỏi cốt lõi++*Đọc toàn bộ văn bản cho mỗi bài giảng trên [Trang web Tài liệu](https://walkinglabs.github.io/learn-harness-engineering/).*++| Phiên | Câu hỏi | Ý tưởng cốt lõi |+|-------|---------|------------------|+| [L01](../../docs/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Tại sao các mô hình mạnh vẫn thất bại trên tác vụ thực tế? | Khoảng cách năng lực giữa benchmark và kỹ thuật thực tế |+| [L02](../../docs/lectures/lecture-02-what-a-harness-actually-is/index.md) | "Harness" thực sự có nghĩa là gì? | Năm hệ thống con: instructions, state, verification, scope, lifecycle |+| [L03](../../docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Tại sao kho mã phải là nguồn chân lý duy nhất? | Nếu agent không thể thấy nó, nó không tồn tại |+| [L04](../../docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Tại sao một tệp hướng dẫn khổng lồ lại thất bại? | Tiết lộ dần: cho một bản đồ, không phải một bộ bách khoa toàn thư |+| [L05](../../docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Tại sao các tác vụ chạy dài mất tính liên tục? | Lưu trữ tiến trình vào đĩa; tiếp tục từ nơi bạn đã dừng |+| [L06](../../docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Tại sao khởi tạo cần một giai đoạn riêng? | Xác minh môi trường khỏe mạnh trước khi agent bắt đầu làm việc |+| [L07](../../docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Tại sao agent lại vượt quá phạm vi và không hoàn thành? | Một tính năng tại một thời điểm; định nghĩa rõ ràng về "hoàn thành" |+| [L08](../../docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Tại sao danh sách tính năng là nguyên thủy của harness? | Ranh giới phạm vi có thể đọc bởi máy mà agent không thể bỏ qua |+| [L09](../../docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Tại sao agent tuyên bố hoàn thành quá sớm? | Khoảng trống kiểm chứng: sự tự tin ≠ sự chính xác |+| [L10](../../docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Tại sao kiểm thử đầu-cuối lại thay đổi kết quả? | Chỉ một lần chạy toàn bộ pipeline mới được tính là kiểm chứng thực sự |+| [L11](../../docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Tại sao khả năng quan sát thuộc về bên trong harness? | Nếu bạn không thể thấy agent đã làm gì, bạn không thể sửa những gì nó đã làm hỏng |+| [L12](../../docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Tại sao mỗi phiên phải để lại trạng thái sạch? | Sự thành công của phiên tiếp theo phụ thuộc vào việc dọn dẹp của phiên này |++### Dự án — 6 dự án thực hành áp dụng phương pháp bài giảng vào cùng ứng dụng Electron++| Dự án | Những gì bạn làm | Cơ chế Harness |+|-------|-------------------|----------------|+| [P01](../../docs/projects/project-01-baseline-vs-minimal-harness/index.md) | Chạy cùng tác vụ hai lần: chỉ dùng prompt vs. ưu tiên quy tắc | Harness tối thiểu: AGENTS.md + init.sh + feature_list.json |+| [P02](../../docs/projects/project-02-agent-readable-workspace/index.md) | Tái cấu trúc kho mã để agent có thể đọc được | Không gian làm việc agent có thể đọc + các tệp trạng thái liên tục |+| [P03](../../docs/projects/project-03-multi-session-continuity/index.md) | Khiến agent tiếp tục từ nơi nó đã dừng | Nhật ký tiến trình + bàn giao phiên + tính liên tục đa phiên |+| [P04](../../docs/projects/project-04-incremental-indexing/index.md) | Ngăn agent làm quá nhiều hoặc quá ít | Phản hồi thời gian chạy + kiểm soát phạm vi + lập chỉ mục gia tăng |+| [P05](../../docs/projects/project-05-grounded-qa-verification/index.md) | Khiến agent tự kiểm chứng công việc của mình | Tự kiểm chứng + Q&A có căn cứ + hoàn thành dựa trên bằng chứng |+| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | Xây dựng một harness hoàn chỉnh từ đầu (tổng kết) | Harness đầy đủ: tất cả cơ chế + khả năng quan sát + nghiên cứu ablation |++```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.+```++### Thư viện tài nguyên++- [English](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) — templates, checklists, and method references+- [简体中文](https://walkinglabs.github.io/learn-harness-engineering/zh/resources/) — 中文模板、清单和方法参考+- [繁體中文](https://walkinglabs.github.io/learn-harness-engineering/zh-TW/resources/) — 繁體中文範本、清單和方法參考+- [日本語](https://walkinglabs.github.io/learn-harness-engineering/ja/resources/) — テンプレート、チェックリスト、方法リファレンス+- [한국어](https://walkinglabs.github.io/learn-harness-engineering/ko/resources/) — 템플릿, 체크리스트, 방법 참고 자료+- [Español](https://walkinglabs.github.io/learn-harness-engineering/es/resources/) — plantillas, listas de verificación y referencias+- [Français](https://walkinglabs.github.io/learn-harness-engineering/fr/resources/) — modèles, listes de contrôle et références+- [Русский](https://walkinglabs.github.io/learn-harness-engineering/ru/resources/) — шаблоны, чек-листы и справочники+- [Deutsch](https://walkinglabs.github.io/learn-harness-engineering/de/resources/) — Vorlagen, Checklisten und Referenzen+- [العربية](https://walkinglabs.github.io/learn-harness-engineering/ar/resources/) — قوالب، قوائم تحقق ومراجع+- [Tiếng Việt](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+- [Oʻzbekcha](https://walkinglabs.github.io/learn-harness-engineering/uz/resources/) — andozalar, tekshiruv roʻyxatlari va maʼlumotnomalar++---++## Vòng đời phiên Agent++Một trong những ý tưởng cốt lõi trong khóa học này: **phiên của agent nên tuân theo một vòng đời có cấu trúc, không phải tự do không kiểm soát.** Đây là cách nó trông như thế này:++```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."+```++---++## Khóa học này dành cho ai++Khóa học này dành cho:++- Các kỹ sư đang sử dụng agent viết code và muốn sự ổn định và chất lượng tốt hơn+- Các nhà nghiên cứu hoặc nhà xây dựng muốn hiểu biết hệ thống về thiết kế harness+- Các trưởng nhóm kỹ thuật cần hiểu cách thiết kế môi trường ảnh hưởng đến hiệu suất agent++Khóa học này không dành cho:++- Những người tìm kiếm một giới thiệu AI không cần viết code+- Những người chỉ quan tâm đến prompt và không có kế hoạch xây dựng các triển khai thực tế+- Những người học không sẵn sàng để các agent làm việc bên trong các kho mã thực tế++---++## Yêu cầu++Đây là một khóa học mà bạn thực sự chạy các agent viết code.++Bạn cần ít nhất một trong các công cụ sau:++- Claude Code+- Codex+- Một agent viết code IDE hoặc CLI khác hỗ trợ chỉnh sửa tệp, thực thi lệnh và tác vụ nhiều bước++Khóa học giả định rằng bạn có thể:++- Mở một kho mã cục bộ+- Cho phép agent chỉnh sửa tệp+- Cho phép agent chạy lệnh+- Kiểm tra đầu ra và chạy lại tác vụ++Nếu bạn không có công cụ như vậy, bạn vẫn có thể đọc nội dung khóa học, nhưng bạn sẽ không thể hoàn thành các dự án như dự kiến.++---++## Xem trước cục bộ++Kho lưu trữ này sử dụng VitePress làm trình xem tài liệu.++```sh+npm install+npm run docs:dev # Dev server với tải lại nóng+npm run docs:build # Build sản xuất+npm run docs:preview # Xem trước trang đã build+```++Sau đó mở URL cục bộ mà VitePress hiển thị trong trình duyệt của bạn.++---++## Điều kiện tiên quyết++Bắt buộc:++- Quen thuộc với terminal, git và môi trường phát triển cục bộ+- Khả năng đọc và viết code trong ít nhất một ngăn xếp ứng dụng phổ biến+- Kinh nghiệm gỡ lỗi phần mềm cơ bản (đọc log, kiểm thử và hành vi thời gian chạy)+- Đủ thời gian để cam kết với khóa học tập trung vào triển khai++Có ích nhưng không bắt buộc:++- Kinh nghiệm với Electron, ứng dụng desktop hoặc công cụ local-first+- Nền tảng về kiểm thử, logging hoặc kiến trúc phần mềm+- Đã tiếp xúc với Codex, Claude Code hoặc các agent viết code tương tự++---++## Tài liệu tham khảo cốt lõi++Chính:++- [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)+- [OpenAI: Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/)+- [Anthropic: Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)+- [LangChain: Improving Deep Agents with harness engineering](https://www.langchain.com/blog/improving-deep-agents-with-harness-engineering)+- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)+- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)++Xem danh sách tài liệu tham khảo phân tầng đầy đủ tại [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md).++---++## Cấu trúc kho lưu trữ++```text+learn-harness-engineering/+├── docs/ # VitePress documentation site+│ ├── lectures/ # 12 lectures (index.md + code/ examples)+│ │ ├── lecture-01-*/+│ │ ├── lecture-02-*/+│ │ └── ... (12 total)+│ ├── projects/ # 6 project descriptions+│ │ ├── project-01-*/+│ │ └── ... (6 total)+│ └── resources/ # Multilingual templates & references+│ ├── en/ # English templates, checklists, guides+│ ├── zh/ # Chinese templates, checklists, guides+│ ├── ru/ # Russian templates, checklists, guides+│ └── vi/ # Vietnamese templates, checklists, guides+├── projects/+│ ├── shared/ # Shared Electron + TypeScript + React foundation+│ └── project-NN/ # Per-project starter/ and solution/ directories+├── skills/ # Reusable AI agent skills+│ └── harness-creator/ # Harness engineering skill+├── package.json # VitePress + dev tooling+└── CLAUDE.md # Claude Code instructions for this repo+```++---++## Khóa học được tổ chức như thế nào++- Mỗi bài giảng tập trung vào một câu hỏi+- Khóa học bao gồm 6 dự án+- Mọi dự án đều yêu cầu agent thực hiện công việc thực tế+- Mọi dự án đều so sánh kết quả harness yếu vs. mạnh+- Điều quan trọng là sự khác biệt được đo lường, không phải số lượng tài liệu đã viết++---++## Skills++Kho lưu trữ này cũng bao gồm các skill agent AI có thể tái sử dụng mà bạn có thể cài đặt trực tiếp vào IDE hoặc không gian làm việc agent của mình.++- [**harness-creator**](../../skills/harness-creator/): Một skill giúp bạn tạo nhanh một harness cấp sản xuất cho dự án của riêng bạn chỉ trong vài phút.++---++## Các khóa học khác++Đội ngũ của chúng tôi cũng đã tạo các khóa học khác! Hãy xem:++[](https://github.com/walkinglabs/hands-on-modern-rl)++**Hands-on Modern RL**: Một giáo trình thực hành mã nguồn mở kết nối khoảng cách từ các khái niệm RL cơ bản đến LLM alignment, RLVR và các hệ thống Agentic nâng cao.++---++## Lịch sử Star++[](https://www.star-history.com/#walkinglabs/learn-harness-engineering&type=date&legend=top-left)++---++## Lời cảm ơn++Khóa học này được truyền cảm hứng và rút ra ý tưởng từ [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) — một hướng dẫn tiệm tiến về việc xây dựng một agent từ đầu, từ một vòng lặp đơn giản đến thực thi tự chủ cô lập.diff --git a/README-ZH-TW.md b/README-ZH-TW.mdnew file mode 100644index 0000000..53f644c--- /dev/null+++ b/README-ZH-TW.md@@ -0,0 +1,580 @@+<p align="center">+ <a href="./README.md"><img alt="English" src="https://img.shields.io/badge/EN-English-blue?style=flat-square"></a>+ <a href="./README-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/ZH-简体中文-red?style=flat-square"></a>+ <a href="./README-ZH-TW.md"><img alt="繁體中文" src="https://img.shields.io/badge/ZH--TW-繁體中文-orange?style=flat-square"></a>+ <a href="./README-JA.md"><img alt="日本語" src="https://img.shields.io/badge/JA-日本語-green?style=flat-square"></a>+ <a href="./README-KO.md"><img alt="한국어" src="https://img.shields.io/badge/KO-한국어-blueviolet?style=flat-square"></a>+ <a href="./README-ES.md"><img alt="Español" src="https://img.shields.io/badge/ES-Español-yellow?style=flat-square"></a>+ <a href="./README-FR.md"><img alt="Français" src="https://img.shields.io/badge/FR-Français-007EC6?style=flat-square"></a>+ <a href="./README-RU.md"><img alt="Русский" src="https://img.shields.io/badge/RU-Русский-informational?style=flat-square"></a>+ <a href="./README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/DE-Deutsch-2EA043?style=flat-square"></a>+ <a href="./README-AR.md"><img alt="العربية" src="https://img.shields.io/badge/AR-العربية-success?style=flat-square"></a>+ <a href="./README-VI.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/VI-Tiếng_Việt-cc6699?style=flat-square"></a>+ <a href="./README-UZ.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>+</p>++# Learn Harness Engineering++> **一門專案導向的課程,教你建構讓 AI 程式設計代理可靠運作的環境、狀態管理、驗證與控制機制。**++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/) 技能可以在幾分鐘內為你自己的專案搭建一套生產級的 harness(AGENTS.md、功能列表、init.sh、驗證流程)。++---++## 目錄++- [✨ 視覺預覽](#-視覺預覽)+- [Harness Engineering 的真正含義](#harness-engineering-的真正含義)+- [快速入門:今天就改善你的代理](#快速入門今天就改善你的代理)+- [畢業專案:一個真實的應用程式](#畢業專案一個真實的應用程式)+- [學習路徑](#學習路徑)+- [課程大綱](#課程大綱)+- [技能](#技能)+- [其他課程](#其他課程)++---++## ✨ 視覺預覽++### 🏠 課程首頁+> 完整的課程大綱與核心理念介紹,提供清晰的上手路徑。++++### 📖 沉浸式講座+> 深入探討實際痛點與動手專案(如 Project 01),帶來沉浸式的學習體驗。++++### 🗂️ 即用的資源庫+> 專為解決多輪 AI 代理開發中常見陷阱(如上下文遺失、過早宣告任務完成)而設計的模板與參考配置。++++## 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。++---++## 模型很聰明,Harness 讓它可靠++大多數人都是慘痛教訓後才明白一個殘酷的事實:**世界上最強大的模型,如果你不在它周圍建構適當的環境,它在真實工程任務上仍然會失敗。**++你可能自己也見過這種情況。你讓 Claude 或 GPT 在你的儲存庫中執行一項任務。它一開始表現不錯——讀取檔案、撰寫程式碼,看起來很有效率。然後出了問題。它跳過了一個步驟。它破壞了一個測試。它說「完成了」,但實際上什麼都不能用。你最後花的時間比自己動手做還多。++這不是模型的問題。這是 harness 的問題。++證據很明確。Anthropic 進行了一項對照實驗:相同的模型(Opus 4.5)、相同的提示(「建構一個 2D 復古遊戲編輯器」)。沒有 harness 的情況下,它在 20 分鐘內花了 9 美元,產出的東西無法運作。有了完整的 harness(規劃器 + 生成器 + 評估器),它在 6 小時內花了 200 美元,建構出一個你真的可以玩的遊戲。模型沒有變。變的是 harness。++OpenAI 也報告了 Codex 的相同結果:在一個 well-harnessed 的儲存庫中,相同的模型從「不可靠」變成「可靠」。這不是邊際改善——這是質的飛躍。++**這門課程教你如何建構那個環境。**++```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 的真正含義++Harness Engineering 是關於在模型周圍建構一個完整的工作環境,使其產生可靠的結果。它不是關於寫更好的提示。它是關於設計模型運作所在的系統。++一個 harness 有五個子系統:++```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(指令)** — 告訴代理該做什麼、以什麼順序、以及在開始前該閱讀什麼。不是一個巨大的檔案;而是一個漸進揭露的結構,讓代理按需導航。+- **State(狀態)** — 追蹤已完成的事項、正在進行的事項、以及接下來該做的事。持久化到磁碟,讓下一個工作階段可以精確地從上一個階段停止的地方接續。+- **Verification(驗證)** — 只有通過的測試套件才算數。代理不能在沒有可執行證據的情況下宣告勝利。+- **Scope(範圍)** — 將代理限制在每次只做一個功能。不過度延伸。不三件事做一半。不改寫功能列表來隱藏未完成的工作。+- **Session Lifecycle(工作階段生命週期)** — 開始時初始化。結束時清理。為下一個工作階段留下乾淨的重啟路徑。++---++## 為什麼會有這門課程++問題不是「模型能不能寫程式?」它們能。問題是:**它們能不能在真實的儲存庫中,跨越多個工作階段,在沒有持續人工監督的情況下,可靠地完成真實的工程任務?**++目前的答案是:沒有 harness 就不行。++```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+```++這門課程真正關心的問題:++- 哪些 harness 設計能提升任務完成率?+- 哪些設計能減少返工與錯誤完成?+- 哪些機制能讓長時間執行的任務穩定推進?+- 哪些結構能讓系統在多次代理執行後仍保持可維護性?++---++## 課程內容與文件++完整的課程資料,請造訪**[文件網站](https://walkinglabs.github.io/learn-harness-engineering/)**。++課程分為三個部分:++1. **講座**:12 個概念單元,解釋 harness engineering 背後的理論。+2. **專案**:6 個動手專案,讓你從零建構一個代理工作空間。+3. **資源庫**:可直接複製使用的模板(`AGENTS.md`、`feature_list.json`、`init.sh` 等),今天就能在你的儲存庫中使用。++---++## 快速入門:今天就改善你的代理++你不需要讀完所有 12 堂講座才能開始受益。如果你已經在真實專案中使用程式設計代理,以下是如何立刻改善它的方法。++概念很簡單:與其只寫提示,不如給你的代理一組結構化的檔案,定義該做什麼、已經做了什麼、以及如何驗證工作。這些檔案存在你的儲存庫中,所以每個工作階段都從相同的狀態開始。++```text+ YOUR PROJECT ROOT+ ├── AGENTS.md <-- 代理的操作手冊+ ├── CLAUDE.md <-- (替代方案,如果使用 Claude Code)+ ├── init.sh <-- 執行安裝 + 驗證 + 啟動+ ├── feature_list.json <-- 哪些功能存在,哪些已完成+ ├── claude-progress.md <-- 每個工作階段發生了什麼事+ └── src/ <-- 你實際的程式碼+```++從[資源庫](https://walkinglabs.github.io/learn-harness-engineering/en/resources/)取得入門模板,放入你的專案。就是這樣。四個檔案,你的代理工作階段就會比僅靠提示穩定得多。++---++## 畢業專案:一個真實的應用程式++所有六個課程專案都圍繞著同一個產品:**一個基於 Electron 的個人知識庫桌面應用程式**。++```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+```++選擇這個專案是因為它結合了強大的實用價值、足夠的真實產品複雜度,以及觀察 harness 改善前後差異的良好場景。++每個課程專案的 starter/solution 是這個 Electron 應用程式在那個演化階段的完整副本。P(N+1) 的 starter 衍生自 P(N) 的 solution——隨著你的 harness 技能成長,應用程式也在演化。++---++## 學習路徑++課程設計為按順序進行。每個階段建立在前一個階段之上。++```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-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) | 「harness」到底是什麼意思? | 五個子系統:指令、狀態、驗證、範圍、生命週期 |+| [L03](../../docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | 為什麼儲存庫必須是唯一的真實來源? | 如果代理看不到它,它就不存在 |+| [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) | 為什麼長時間執行的任務會失去連續性? | 將進度持久化到磁碟;從你停止的地方接續 |+| [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) | 為什麼功能列表是 harness 的基本元素? | 機器可讀的範圍邊界,代理無法忽略 |+| [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) | 為什麼可觀測性應該屬於 harness 內部? | 如果你看不到代理做了什麼,你就無法修復它破壞的東西 |+| [L12](../../docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | 為什麼每個工作階段都必須留下乾淨的狀態? | 下一個工作階段的成功取決於這個工作階段的清理 |++### 專案 — 6 個動手專案,將講座方法應用於同一個 Electron 應用程式++| 專案 | 你要做什麼 | Harness 機制 |+|---------|------------|-------------------|+| [P01](../../docs/projects/project-01-baseline-vs-minimal-harness/index.md) | 將同一任務執行兩次:僅提示 vs. 規則優先 | 最小 harness: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) | 讓代理從上次停止的地方接續 | 進度日誌 + 工作階段交接 + 多工作階段連續性 |+| [P04](../../docs/projects/project-04-incremental-indexing/index.md) | 阻止代理做得太多或太少 | 執行時回饋 + 範圍控制 + 增量索引 |+| [P05](../../docs/projects/project-05-grounded-qa-verification/index.md) | 讓代理驗證自己的工作 | 自我驗證 + 有依據的問答 + 基於證據的完成 |+| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | 從零建構一個完整的 harness(畢業專案) | 完整 harness:所有機制 + 可觀測性 + 消融實驗 |++```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.+```++### 資源庫++- [English](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) — templates, checklists, and method references+- [简体中文](https://walkinglabs.github.io/learn-harness-engineering/zh/resources/) — 中文模板、清单和方法参考+- [繁體中文](https://walkinglabs.github.io/learn-harness-engineering/zh-TW/resources/) — 繁體中文範本、清單和方法參考+- [日本語](https://walkinglabs.github.io/learn-harness-engineering/ja/resources/) — テンプレート、チェックリスト、方法リファレンス+- [한국어](https://walkinglabs.github.io/learn-harness-engineering/ko/resources/) — 템플릿, 체크리스트, 방법 참고 자료+- [Español](https://walkinglabs.github.io/learn-harness-engineering/es/resources/) — plantillas, listas de verificación y referencias+- [Français](https://walkinglabs.github.io/learn-harness-engineering/fr/resources/) — modèles, listes de contrôle et références+- [Русский](https://walkinglabs.github.io/learn-harness-engineering/ru/resources/) — шаблоны, чек-листы и справочники+- [Deutsch](https://walkinglabs.github.io/learn-harness-engineering/de/resources/) — Vorlagen, Checklisten und Referenzen+- [العربية](https://walkinglabs.github.io/learn-harness-engineering/ar/resources/) — قوالب، قوائم تحقق ومراجع+- [Tiếng Việt](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+- [Oʻzbekcha](https://walkinglabs.github.io/learn-harness-engineering/uz/resources/) — andozalar, tekshiruv roʻyxatlari va maʼlumotnomalar++---++## 代理工作階段生命週期++這門課程的核心理念之一:**代理的工作階段應該遵循結構化的生命週期,而不是隨意進行。** 以下是它的樣貌:++```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."+```++---++## 適合什麼人++這門課程適合:++- 已在使用程式設計代理並希望獲得更好穩定性與品質的工程師+- 希望系統性理解 harness 設計的研究者或建構者+- 需要了解環境設計如何影響代理效能的技術主管++這門課程不適合:++- 尋求零程式碼 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、桌面應用程式或 local-first 工具的經驗+- 有測試、日誌或軟體架構的背景+- 曾接觸過 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)+- [OpenAI: Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/)+- [Anthropic: Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)+- [LangChain: Improving Deep Agents with harness engineering](https://www.langchain.com/blog/improving-deep-agents-with-harness-engineering)+- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)+- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)++完整的分層參考列表請見 [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md)。++---++## 儲存庫結構++```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/ # Harness Engineering 技能+├── package.json # VitePress + 開發工具+└── CLAUDE.md # 本儲存庫的 Claude Code 指令+```++---++## 課程組織方式++- 每堂講座專注於一個問題+- 課程包含 6 個專案+- 每個專案都要求代理做真實的工作+- 每個專案都比較弱 harness 與強 harness 的結果+- 重要的是可量測的差異,而不是寫了多少文件++---++## 技能++本儲存庫還包含可重用的 AI 代理技能,你可以直接安裝到你的 IDE 或代理工作空間。++- [**harness-creator**](../../skills/harness-creator/):一個幫助你在幾分鐘內為自己的專案搭建生產級 harness 的技能。++---++## 其他課程++我們的團隊還製作了其他課程!歡迎查看:++[](https://github.com/walkinglabs/hands-on-modern-rl)++**Hands-on Modern RL**:一個開源的實作課程,從基礎 RL 概念銜接到 LLM 對齊、RLVR 和進階 Agentic 系統。++---++## Star 歷史++[](https://www.star-history.com/#walkinglabs/learn-harness-engineering&type=date&legend=top-left)++---++## 致謝++本課程的靈感來源和部分理念取自 [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) —— 一份從零建構代理的漸進式指南,從單一迴圈到隔離的自主執行。diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mtsindex da221fe..0b98e5e 100644--- a/docs/.vitepress/config.mts+++ b/docs/.vitepress/config.mts@@ -228,10 +228,239 @@ const koSkillItems = [{ text: "스킬 개요", link: "/ko/skills/" }];+const jaLectureItems = [+ { text: "ようこそ", link: "/ja/" },+ { text: "強いモデルは信頼できる実行を意味しない", link: "/ja/lectures/lecture-01-why-capable-agents-still-fail/" },+ { text: "Harness とは何か", link: "/ja/lectures/lecture-02-what-a-harness-actually-is/" },+ { text: "リポジトリを唯一の信頼できる情報源にする", link: "/ja/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/" },+ { text: "指示を複数ファイルに分割する", link: "/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/" },+ { text: "セッションをまたいでコンテキストを保つ", link: "/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/" },+ { text: "すべてのエージェントセッション前に初期化する", link: "/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/" },+ { text: "エージェントのタスク境界を明確にする", link: "/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/" },+ { text: "機能リストでエージェントの作業を制約する", link: "/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/" },+ { text: "エージェントの早すぎる完了宣言を防ぐ", link: "/ja/lectures/lecture-09-why-agents-declare-victory-too-early/" },+ { text: "End-to-End テストだけが本当の検証である", link: "/ja/lectures/lecture-10-why-end-to-end-testing-changes-results/" },+ { text: "エージェントのランタイムを観測可能にする", link: "/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/" },+ { text: "すべてのセッションをきれいな引き継ぎで終える", link: "/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" }+];++const jaProjectItems = [+ { text: "ようこそ", link: "/ja/projects/" },+ { text: "プロンプトのみ vs ルール優先", link: "/ja/projects/project-01-baseline-vs-minimal-harness/" },+ { text: "プロジェクトを読みやすくし、中断地点から再開する", link: "/ja/projects/project-02-agent-readable-workspace/" },+ { text: "セッション再起動後もエージェントが作業を続ける", link: "/ja/projects/project-03-multi-session-continuity/" },+ { text: "ランタイムフィードバックでエージェントの挙動を修正する", link: "/ja/projects/project-04-incremental-indexing/" },+ { text: "エージェントに自分の作業を検証させる", link: "/ja/projects/project-05-grounded-qa-verification/" },+ { text: "完全なエージェント harness を構築する(総合課題)", link: "/ja/projects/project-06-runtime-observability-and-debugging/" }+];++const jaResourceItems = [+ { text: "概要", link: "/ja/resources/" },+ { text: "テンプレート", link: "/ja/resources/templates/" },+ { text: "リファレンス", link: "/ja/resources/reference/" },+ { text: "高度なパック", link: "/ja/resources/openai-advanced/" }+];++const jaSkillItems = [+ { text: "スキル概要", link: "/ja/skills/" }+];++const esLectureItems = [+ { text: "Bienvenido", link: "/es/" },+ { text: "Los modelos fuertes no significan ejecución fiable", link: "/es/lectures/lecture-01-why-capable-agents-still-fail/" },+ { text: "Qué significa realmente harness", link: "/es/lectures/lecture-02-what-a-harness-actually-is/" },+ { text: "Convierte el repositorio en la fuente única de verdad", link: "/es/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/" },+ { text: "Divide las instrucciones entre archivos", link: "/es/lectures/lecture-04-why-one-giant-instruction-file-fails/" },+ { text: "Mantén vivo el contexto entre sesiones", link: "/es/lectures/lecture-05-why-long-running-tasks-lose-continuity/" },+ { text: "Inicializa antes de cada sesión del agente", link: "/es/lectures/lecture-06-why-initialization-needs-its-own-phase/" },+ { text: "Define límites claros para las tareas del agente", link: "/es/lectures/lecture-07-why-agents-overreach-and-under-finish/" },+ { text: "Usa listas de funciones para limitar al agente", link: "/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/" },+ { text: "Evita que los agentes declaren victoria demasiado pronto", link: "/es/lectures/lecture-09-why-agents-declare-victory-too-early/" },+ { text: "Solo las pruebas end-to-end son verificación real", link: "/es/lectures/lecture-10-why-end-to-end-testing-changes-results/" },+ { text: "Haz observable el runtime del agente", link: "/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/" },+ { text: "Deja un handoff limpio al final de cada sesión", link: "/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" }+];++const esProjectItems = [+ { text: "Bienvenido", link: "/es/projects/" },+ { text: "Solo prompt vs reglas primero", link: "/es/projects/project-01-baseline-vs-minimal-harness/" },+ { text: "Haz el proyecto legible y retoma el trabajo", link: "/es/projects/project-02-agent-readable-workspace/" },+ { text: "Mantén al agente trabajando tras reiniciar sesiones", link: "/es/projects/project-03-multi-session-continuity/" },+ { text: "Usa feedback de runtime para corregir el comportamiento", link: "/es/projects/project-04-incremental-indexing/" },+ { text: "Haz que el agente verifique su propio trabajo", link: "/es/projects/project-05-grounded-qa-verification/" },+ { text: "Construye un harness completo (capstone)", link: "/es/projects/project-06-runtime-observability-and-debugging/" }+];++const esResourceItems = [+ { text: "Resumen", link: "/es/resources/" },+ { text: "Plantillas", link: "/es/resources/templates/" },+ { text: "Referencia", link: "/es/resources/reference/" },+ { text: "Paquete avanzado", link: "/es/resources/openai-advanced/" }+];++const esSkillItems = [+ { text: "Resumen de Skills", link: "/es/skills/" }+];++const frLectureItems = [+ { text: "Bienvenue", link: "/fr/" },+ { text: "Les modèles forts ne garantissent pas une exécution fiable", link: "/fr/lectures/lecture-01-why-capable-agents-still-fail/" },+ { text: "Ce que signifie vraiment harness", link: "/fr/lectures/lecture-02-what-a-harness-actually-is/" },+ { text: "Faire du dépôt la source unique de vérité", link: "/fr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/" },+ { text: "Répartir les instructions entre fichiers", link: "/fr/lectures/lecture-04-why-one-giant-instruction-file-fails/" },+ { text: "Garder le contexte vivant entre les sessions", link: "/fr/lectures/lecture-05-why-long-running-tasks-lose-continuity/" },+ { text: "Initialiser avant chaque session d'agent", link: "/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/" },+ { text: "Définir des limites de tâche claires", link: "/fr/lectures/lecture-07-why-agents-overreach-and-under-finish/" },+ { text: "Utiliser les listes de fonctionnalités pour contraindre l'agent", link: "/fr/lectures/lecture-08-why-feature-lists-are-harness-primitives/" },+ { text: "Empêcher les agents de déclarer victoire trop tôt", link: "/fr/lectures/lecture-09-why-agents-declare-victory-too-early/" },+ { text: "Seul le test end-to-end est une vraie vérification", link: "/fr/lectures/lecture-10-why-end-to-end-testing-changes-results/" },+ { text: "Rendre le runtime de l'agent observable", link: "/fr/lectures/lecture-11-why-observability-belongs-inside-the-harness/" },+ { text: "Laisser un handoff propre à la fin de chaque session", link: "/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" }+];++const frProjectItems = [+ { text: "Bienvenue", link: "/fr/projects/" },+ { text: "Prompt seul vs règles d'abord", link: "/fr/projects/project-01-baseline-vs-minimal-harness/" },+ { text: "Rendre le projet lisible et reprendre", link: "/fr/projects/project-02-agent-readable-workspace/" },+ { text: "Garder l'agent au travail après les redémarrages", link: "/fr/projects/project-03-multi-session-continuity/" },+ { text: "Utiliser le feedback runtime pour corriger le comportement", link: "/fr/projects/project-04-incremental-indexing/" },+ { text: "Faire vérifier son propre travail par l'agent", link: "/fr/projects/project-05-grounded-qa-verification/" },+ { text: "Construire un harness complet (capstone)", link: "/fr/projects/project-06-runtime-observability-and-debugging/" }+];++const frResourceItems = [+ { text: "Aperçu", link: "/fr/resources/" },+ { text: "Modèles", link: "/fr/resources/templates/" },+ { text: "Référence", link: "/fr/resources/reference/" },+ { text: "Pack avancé", link: "/fr/resources/openai-advanced/" }+];++const frSkillItems = [+ { text: "Aperçu des Skills", link: "/fr/skills/" }+];++const deLectureItems = [+ { text: "Willkommen", link: "/de/" },+ { text: "Starke Modelle bedeuten keine zuverlässige Ausführung", link: "/de/lectures/lecture-01-why-capable-agents-still-fail/" },+ { text: "Was harness wirklich bedeutet", link: "/de/lectures/lecture-02-what-a-harness-actually-is/" },+ { text: "Das Repository zur einzigen Quelle der Wahrheit machen", link: "/de/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/" },+ { text: "Anweisungen auf Dateien verteilen", link: "/de/lectures/lecture-04-why-one-giant-instruction-file-fails/" },+ { text: "Kontext über Sessions hinweg erhalten", link: "/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/" },+ { text: "Vor jeder Agenten-Session initialisieren", link: "/de/lectures/lecture-06-why-initialization-needs-its-own-phase/" },+ { text: "Klare Aufgabengrenzen für Agenten ziehen", link: "/de/lectures/lecture-07-why-agents-overreach-and-under-finish/" },+ { text: "Feature-Listen nutzen, um Agentenarbeit zu begrenzen", link: "/de/lectures/lecture-08-why-feature-lists-are-harness-primitives/" },+ { text: "Verhindern, dass Agenten zu früh Erfolg melden", link: "/de/lectures/lecture-09-why-agents-declare-victory-too-early/" },+ { text: "Nur End-to-End-Tests sind echte Verifikation", link: "/de/lectures/lecture-10-why-end-to-end-testing-changes-results/" },+ { text: "Die Runtime des Agenten beobachtbar machen", link: "/de/lectures/lecture-11-why-observability-belongs-inside-the-harness/" },+ { text: "Sauberes Handoff am Ende jeder Session", link: "/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" }+];++const deProjectItems = [+ { text: "Willkommen", link: "/de/projects/" },+ { text: "Nur Prompt vs Regeln zuerst", link: "/de/projects/project-01-baseline-vs-minimal-harness/" },+ { text: "Das Projekt lesbar machen und weiterarbeiten", link: "/de/projects/project-02-agent-readable-workspace/" },+ { text: "Den Agenten über Session-Neustarts hinweg weiterarbeiten lassen", link: "/de/projects/project-03-multi-session-continuity/" },+ { text: "Runtime-Feedback nutzen, um Agentenverhalten zu korrigieren", link: "/de/projects/project-04-incremental-indexing/" },+ { text: "Den Agenten seine eigene Arbeit verifizieren lassen", link: "/de/projects/project-05-grounded-qa-verification/" },+ { text: "Einen vollständigen Agenten-harness bauen (Capstone)", link: "/de/projects/project-06-runtime-observability-and-debugging/" }+];++const deResourceItems = [+ { text: "Übersicht", link: "/de/resources/" },+ { text: "Vorlagen", link: "/de/resources/templates/" },+ { text: "Referenz", link: "/de/resources/reference/" },+ { text: "Erweitertes Paket", link: "/de/resources/openai-advanced/" }+];++const deSkillItems = [+ { text: "Skills Übersicht", link: "/de/skills/" }+];++const arLectureItems = [+ { text: "مرحبًا", link: "/ar/" },+ { text: "النماذج القوية لا تعني تنفيذًا موثوقًا", link: "/ar/lectures/lecture-01-why-capable-agents-still-fail/" },+ { text: "ما معنى harness فعليًا", link: "/ar/lectures/lecture-02-what-a-harness-actually-is/" },+ { text: "اجعل المستودع مصدر الحقيقة الوحيد", link: "/ar/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/" },+ { text: "قسّم التعليمات عبر ملفات", link: "/ar/lectures/lecture-04-why-one-giant-instruction-file-fails/" },+ { text: "حافظ على السياق عبر الجلسات", link: "/ar/lectures/lecture-05-why-long-running-tasks-lose-continuity/" },+ { text: "هيئ قبل كل جلسة وكيل", link: "/ar/lectures/lecture-06-why-initialization-needs-its-own-phase/" },+ { text: "ارسم حدود مهمة واضحة للوكلاء", link: "/ar/lectures/lecture-07-why-agents-overreach-and-under-finish/" },+ { text: "استخدم قوائم الميزات لتقييد الوكيل", link: "/ar/lectures/lecture-08-why-feature-lists-are-harness-primitives/" },+ { text: "منع الوكلاء من إعلان النجاح مبكرًا", link: "/ar/lectures/lecture-09-why-agents-declare-victory-too-early/" },+ { text: "الاختبار end-to-end هو التحقق الحقيقي", link: "/ar/lectures/lecture-10-why-end-to-end-testing-changes-results/" },+ { text: "اجعل runtime الوكيل قابلًا للملاحظة", link: "/ar/lectures/lecture-11-why-observability-belongs-inside-the-harness/" },+ { text: "اترك handoff نظيفًا في نهاية كل جلسة", link: "/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" }+];++const arProjectItems = [+ { text: "مرحبًا", link: "/ar/projects/" },+ { text: "Prompt فقط مقابل القواعد أولًا", link: "/ar/projects/project-01-baseline-vs-minimal-harness/" },+ { text: "اجعل المشروع قابلًا للقراءة واستأنف", link: "/ar/projects/project-02-agent-readable-workspace/" },+ { text: "أبقِ الوكيل يعمل بعد إعادة تشغيل الجلسات", link: "/ar/projects/project-03-multi-session-continuity/" },+ { text: "استخدم feedback في runtime لتصحيح سلوك الوكيل", link: "/ar/projects/project-04-incremental-indexing/" },+ { text: "اجعل الوكيل يتحقق من عمله", link: "/ar/projects/project-05-grounded-qa-verification/" },+ { text: "ابنِ harness كاملًا للوكيل (Capstone)", link: "/ar/projects/project-06-runtime-observability-and-debugging/" }+];++const arResourceItems = [+ { text: "نظرة عامة", link: "/ar/resources/" },+ { text: "قوالب", link: "/ar/resources/templates/" },+ { text: "مرجع", link: "/ar/resources/reference/" },+ { text: "حزمة متقدمة", link: "/ar/resources/openai-advanced/" }+];++const arSkillItems = [+ { text: "نظرة عامة على المهارات", link: "/ar/skills/" }+];++const zhTWLectureItems = [+ { text: "歡迎", link: "/zh-TW/" },+ { text: "模型能力強,不等於執行可靠", link: "/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/" },+ { text: "Harness 到底是什麼", link: "/zh-TW/lectures/lecture-02-what-a-harness-actually-is/" },+ { text: "讓代碼倉庫成為唯一的事實來源", link: "/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/" },+ { text: "把指令拆分到不同檔案裡", link: "/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/" },+ { text: "讓跨會話的任務保持上下文連續", link: "/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/" },+ { text: "讓 agent 每次工作前先初始化", link: "/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/" },+ { text: "給 agent 劃清每次任務的邊界", link: "/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/" },+ { text: "用功能清單約束 agent 該做什麼", link: "/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/" },+ { text: "防止 agent 提前宣告完成", link: "/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/" },+ { text: "跑通完整流程才算真正驗證", link: "/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/" },+ { text: "讓 agent 的運行過程可觀測", link: "/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/" },+ { text: "每次會話結束前都做好交接", link: "/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" }+];++const zhTWProjectItems = [+ { text: "歡迎", link: "/zh-TW/projects/" },+ { text: "提示詞驅動 vs 規則驅動", link: "/zh-TW/projects/project-01-baseline-vs-minimal-harness/" },+ { text: "讓 agent 看懂項目、接住上次的工作", link: "/zh-TW/projects/project-02-agent-readable-workspace/" },+ { text: "讓 agent 關掉再打開還能接著幹", link: "/zh-TW/projects/project-03-multi-session-continuity/" },+ { text: "用運行反饋修正 agent 的行為", link: "/zh-TW/projects/project-04-incremental-indexing/" },+ { text: "讓 agent 自己檢查自己做的對不對", link: "/zh-TW/projects/project-05-grounded-qa-verification/" },+ { text: "搭建一套完整的 agent 工作環境", link: "/zh-TW/projects/project-06-runtime-observability-and-debugging/" }+];++const zhTWResourceItems = [+ { text: "資料庫總覽", link: "/zh-TW/resources/" },+ { text: "繁體中文範本", link: "/zh-TW/resources/templates/" },+ { text: "繁體中文參考", link: "/zh-TW/resources/reference/" },+ { text: "進階資源包", link: "/zh-TW/resources/openai-advanced/" }+];++const zhTWSkillItems = [+ { text: "技能總覽", link: "/zh-TW/skills/" }+];++const jaSourceItems = { lectures: jaLectureItems, projects: jaProjectItems, resources: jaResourceItems, skills: jaSkillItems };+const esSourceItems = { lectures: esLectureItems, projects: esProjectItems, resources: esResourceItems, skills: esSkillItems };+const frSourceItems = { lectures: frLectureItems, projects: frProjectItems, resources: frResourceItems, skills: frSkillItems };+const deSourceItems = { lectures: deLectureItems, projects: deProjectItems, resources: deResourceItems, skills: deSkillItems };+const arSourceItems = { lectures: arLectureItems, projects: arProjectItems, resources: arResourceItems, skills: arSkillItems };+const zhTWSourceItems = { lectures: zhTWLectureItems, projects: zhTWProjectItems, resources: zhTWResourceItems, skills: zhTWSkillItems };+const relinkItems = (items: Array<{ text: string; link: string }>, locale: string) =>items.map((item) => ({...item,- link: item.link.replace(/^\/(en|zh|vi|ko|uz|ru)\//, `/${locale}/`)+ link: item.link.replace(/^\/(en|zh|vi|ko|uz|ru|ja|es|fr|de|ar|zh-TW)\//, `/${locale}/`)}));const createLocaleTheme = (@@ -426,7 +655,7 @@ export default withMermaid(label: "繁體中文",lang: "zh-TW",link: "/zh-TW/",- themeConfig: createLocaleTheme("zh-TW", zhSourceItems, {+ themeConfig: createLocaleTheme("zh-TW", zhTWSourceItems, {lectures: "講義",projects: "專案",resources: "資源庫",@@ -447,7 +676,7 @@ export default withMermaid(label: "日本語",lang: "ja-JP",link: "/ja/",- themeConfig: createLocaleTheme("ja", enSourceItems, {+ themeConfig: createLocaleTheme("ja", jaSourceItems, {lectures: "講義",projects: "プロジェクト",resources: "リソース",@@ -469,7 +698,7 @@ export default withMermaid(label: "Español",lang: "es-ES",link: "/es/",- themeConfig: createLocaleTheme("es", enSourceItems, {+ themeConfig: createLocaleTheme("es", esSourceItems, {lectures: "Lecciones",projects: "Proyectos",resources: "Biblioteca",@@ -491,7 +720,7 @@ export default withMermaid(label: "Français",lang: "fr-FR",link: "/fr/",- themeConfig: createLocaleTheme("fr", enSourceItems, {+ themeConfig: createLocaleTheme("fr", frSourceItems, {lectures: "Cours",projects: "Projets",resources: "Bibliothèque",@@ -513,7 +742,7 @@ export default withMermaid(label: "Deutsch",lang: "de-DE",link: "/de/",- themeConfig: createLocaleTheme("de", enSourceItems, {+ themeConfig: createLocaleTheme("de", deSourceItems, {lectures: "Lektionen",projects: "Projekte",resources: "Bibliothek",@@ -535,7 +764,7 @@ export default withMermaid(label: "العربية",lang: "ar-SA",link: "/ar/",- themeConfig: createLocaleTheme("ar", enSourceItems, {+ themeConfig: createLocaleTheme("ar", arSourceItems, {lectures: "المحاضرات",projects: "المشاريع",resources: "المكتبة",