Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
Refactor terminology in lectures to enhance clarity and consistency
Okan Selamidd630eabb7eb
diff --git a/README-AR.md b/README-AR.mddeleted file mode 100644index 9ccae56..0000000--- a/README-AR.md+++ /dev/null@@ -1,582 +0,0 @@-<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>- <a href="./README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?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- نمط الحزام- ===========-- أنت --> تعطي مهمة --> الوكيل يقرأ ملفات الحزام --> الوكيل ينفذ- |- الحزام يحكم كل خطوة:- |- +--> التعليمات: ماذا يفعل، بأي ترتيب- +--> النطاق: ميزة واحدة في كل مرة، بلا تجاوز- +--> الحالة: سجل التقدم، قائمة الميزات، سجل git- +--> التحقق: اختبارات، تنسيق، فحص أنواع، تشغيل تجريبي- +--> دورة الحياة: تهيئة في البداية، حالة نظيفة في النهاية- |- v- الوكيل يتوقف فقط عندما- يجتاز التحقق-```-------## ما تعنيه هندسة الحزام فعلياً--هندسة الحزام تدور حول بناء بيئة عمل كاملة حول النموذج حتى ينتج نتائج موثوقة. الأمر لا يتعلق بكتابة موجهات أفضل. بل يتعلق بتصميم النظام الذي يعمل النموذج داخله.--يتكون الحزام من خمس أنظمة فرعية:--```text- ┌─────────────────────────────────────────────────────────────────┐- │ الحزام │- │ │- │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │- │ │ التعليمات │ │ الحالة │ │ التحقق │ │- │ │ │ │ │ │ │ │- │ │ AGENTS.md │ │ progress.md │ │ اختبارات + تنسيق │ │- │ │ CLAUDE.md │ │ feature_list │ │ فحص أنواع │ │- │ │ feature_list │ │ سجل git │ │ تشغيل تجريبي │ │- │ │ docs/ │ │ تسليم جلسة │ │ خط أنابيب شامل │ │- │ └──────────────┘ └──────────────┘ └──────────────────────┘ │- │ │- │ ┌──────────────┐ ┌──────────────────────────────────────┐ │- │ │ النطاق │ │ دورة حياة الجلسة │ │- │ │ │ │ │ │- │ │ ميزة واحدة │ │ init.sh في البداية │ │- │ │ في كل مرة │ │ قائمة حالة نظيفة في النهاية │ │- │ │ تعريف │ │ ملاحظة تسليم للجلسة التالية │ │- │ │ الإتمام │ │ التزام فقط عندما يكون آمناً للاستئناف │ │- │ └──────────────┘ └──────────────────────────────────────┘ │- │ │- └─────────────────────────────────────────────────────────────────┘-- النموذج يقرر أي كود يكتبه.- الحزام يحكم متى وأين وكيف يكتبه.- الحزام لا يجعل النموذج أذكى.- بل يجعل مخرجات النموذج موثوقة.-```--لكل نظام فرعي وظيفة واحدة:--- **التعليمات** — تخبر الوكيل بما يجب فعله، بأي ترتيب، وما يجب قراءته قبل البدء. ليس ملفاً ضخماً واحداً؛ بل هيكل إفصاح تدريجي يتنقل فيه الوكيل حسب الحاجة.-- **الحالة** — تتبع ما تم إنجازه، ما قيد التنفيذ، وما هو التالي. محفوظة على القرص حتى تلتقط الجلسة التالية من حيث توقفت الجلسة السابقة تماماً.-- **التحقق** — مجموعة اختبارات ناجحة فقط تُحسب كدليل. لا يمكن للوكيل إعلان النصر بدون دليل قابل للتشغيل.-- **النطاق** — تقييد الوكيل بميزة واحدة في كل مرة. لا تجاوز. لا إنهاء نصف ثلاثة أشياء. لا إعادة كتابة قائمة الميزات لإخفاء العمل غير المنجز.-- **دورة حياة الجلسة** — التهيئة في البداية. التنظيف في النهاية. ترك مسار إعادة تشغيل نظيف للجلسة التالية.-------## لماذا توجد هذه الدورة--السؤال ليس "هل يمكن للنماذج كتابة الكود؟" يمكنها ذلك. السؤال هو: **هل يمكنها إكمال مهام هندسية حقيقية بشكل موثوق داخل مستودعات حقيقية، عبر جلسات متعددة، بدون إشراف بشري مستمر؟**--حالياً، الإجابة هي: ليس بدون حزام.--```text- بدون حزام مع حزام- ========= ======-- الجلسة 1: الوكيل يكتب كوداً الجلسة 1: الوكيل يقرأ التعليمات- الوكيل يكسر الاختبارات الوكيل يشغّل init.sh- الوكيل يقول "تم" الوكيل يعمل على ميزة واحدة- أنت تصلحه يدوياً الوكيل يتحقق قبل أن يدّعي الإتمام- الوكيل يحدّث سجل التقدم- الجلسة 2: الوكيل يبدأ من الصفر الوكيل يلتزم حالة نظيفة- الوكيل ليس لديه ذاكرة- لما حدث سابقاً الجلسة 2: الوكيل يقرأ سجل التقدم- الوكيل يعيد العمل الوكيل يكمل من حيث توقف بالضبط- أو يقوم بشيء آخر تماماً الوكيل يواصل الميزة غير المكتملة- أنت تصلحه مرة أخرى أنت تراجع، لا تنقذ-- النتيجة: أنت تقضي وقتاً أطول النتيجة: الوكيل يقوم بالعمل،- في الإصلاح مما لو كنت وأنت تتحقق من النتيجة- فعلت ذلك بنفسك-```--الأسئلة التي تهتم بها هذه الدورة فعلياً:--- أي تصاميم حزام تحسّن معدلات إكمال المهام؟-- أي تصاميم تقلل إعادة العمل والإكمالات غير الصحيحة؟-- أي آليات تحافظ على تقدم المهام طويلة التشغيل بشكل ثابت؟-- أي هياكل تحافظ على قابلية صيانة النظام بعد عمليات تشغيل وكيل متعددة؟-------## المنهج الدراسي والتوثيق--للحصول على مواد الدورة الكاملة، يرجى زيارة **[موقع التوثيق](https://walkinglabs.github.io/learn-harness-engineering/)**.--ينقسم المنهج إلى ثلاثة أجزاء:--1. **المحاضرات**: 12 وحدة مفاهيمية تشرح النظرية وراء هندسة الحزام.-2. **المشاريع**: 6 مشاريع عملية حيث تبني مساحة عمل وكيلية من الصفر.-3. **مكتبة الموارد**: قوالب جاهزة للنسخ (`AGENTS.md`، `feature_list.json`، `init.sh`، إلخ) لاستخدامها في مستودعاتك الخاصة اليوم.-------## ابدأ بسرعة: حسّن وكيلك اليوم--لا تحتاج إلى قراءة جميع المحاضرات الـ 12 قبل أن تبدأ في الحصول على قيمة. إذا كنت تستخدم بالفعل وكيل برمجة في مشروع حقيقي، إليك كيفية تحسينه الآن.--الفكرة بسيطة: بدلاً من مجرد كتابة الموجهات، أعطِ وكيلك مجموعة من الملفات المنظمة التي تحدد ما يجب فعله، ما تم إنجازه، وكيفية التحقق من العمل. هذه الملفات تعيش داخل مستودعك، لذا تبدأ كل جلسة من نفس الحالة.--```text- الجذر الرئيسي لمشروعك- ├── 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- ┌─────────────────────────────────────────────────────┐- │ تطبيق سطح مكتب لقاعدة المعرفة │- │ │- │ ┌──────────────┐ ┌──────────────────────────────┐│- │ │ قائمة المستندات│ │ لوحة الأسئلة والأجوبة ││- │ │ │ │ ││- │ │ doc-001.md │ │ س: ما هي هندسة الحزام؟ ││- │ │ doc-002.md │ │ ج: البيئة المبنية ││- │ │ doc-003.md │ │ حول نموذج وكيل... ││- │ │ ... │ │ [استشهاد: doc-002.md] ││- │ └──────────────┘ └──────────────────────────────┘│- │ │- │ ┌─────────────────────────────────────────────────┐│- │ │ شريط الحالة: 42 مستند | 38 مفهرس | آخر مزامنة 3د ││- │ └─────────────────────────────────────────────────┘│- └─────────────────────────────────────────────────────┘-- الميزات الأساسية:- ├── استيراد المستندات المحلية- ├── إدارة مكتبة المستندات- ├── معالجة وفهرسة المستندات- ├── تشغيل أسئلة وأجوبة مدعومة بالذكاء الاصطناعي على المحتوى المستورد- └── إرجاع إجابات مبنية على أدلة مع استشهادات-```--تم اختيار هذا المشروع لأنه يجمع بين قيمة عملية قوية، تعقيد كافٍ في المنتج الحقيقي، وبيئة جيدة لمراقبة تحسينات الحزام قبل وبعد.--كل ملف بدء/حل لمشروع في الدورة هو نسخة كاملة من تطبيق Electron في تلك المرحلة التطورية. ملف بدء P(N+1) مشتق من حل P(N) — التطبيق يتطور مع نمو مهاراتك في الحزام.-------## مسار التعلم--الدورة مصممة لتُنفذ بالترتيب. كل مرحلة تبني على سابقتها.--```text- المرحلة 1: شاهد المشكلة المرحلة 2: هيكل المستودع- ======================= ========================-- L01 النماذج القوية ≠ تنفيذ L03 المستودع كمصدر- موثوق وحيد للحقيقة- L02 ماذا يعني الحزام فعلياً- L04 قسّم التعليمات عبر- | ملفات، لا ملف ضخم واحد- v- P01 بالموجهات فقط مقابل |- القواعد أولاً v- P02 مساحة عمل قابلة للقراءة- بواسطة الوكيل--- المرحلة 3: ربط الجلسات المرحلة 4: التغذية الراجعة والنطاق- ========================== ==================================-- L05 أبقِ السياق حياً L07 ارسم حدود مهام واضحة- عبر الجلسات- L08 قوائم الميزات كعناصر- L06 التهيئة قبل كل أساسية للحزام- جلسة وكيل- |- | v- v P04 تغذية راجعة وقت التشغيل- P03 استمرارية متعددة الجلسات لتصحيح سلوك الوكيل--- المرحلة 5: التحقق المرحلة 6: اجمع كل شيء- ===================== ========================-- L09 أوقف الوكلاء عن L11 اجعل بيئة تشغيل الوكيل- إعلان النصر مبكراً قابلة للملاحظة-- L10 تشغيل خط أنابيب كامل = L12 تسليم نظيف في نهاية- تحقق حقيقي كل جلسة-- | |- v v- P05 الوكيل يتحقق من عمله بنفسه P06 ابنِ حزاماً كاملاً- (مشروع التخرج)-```--كل مرحلة تستغرق حوالي أسبوع إذا كنت تعمل بدوام جزئي. إذا كنت تريد السرعة، يمكن إنجاز المراحل 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- تطور المشاريع- =============-- P01 بالموجهات فقط مقابل القواعد أولاً أنت ترى المشكلة- |- v- P02 مساحة عمل قابلة للقراءة بواسطة الوكيل أنت تعيد هيكلة المستودع- |- v- P03 استمرارية متعددة الجلسات أنت تربط الجلسات- |- v- P04 تغذية راجعة وقت التشغيل والنطاق أنت تضيف حلقات التغذية الراجعة- |- v- P05 التحقق الذاتي أنت تجعل الوكيل يتحقق من نفسه- |- v- P06 حزام كامل (مشروع التخرج) أنت تبني النظام الكامل-- حل كل مشروع يصبح بداية المشروع التالي.- التطبيق يتطور. مهاراتك في الحزام تنمو معه.-```--### مكتبة الموارد--- [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- دورة حياة جلسة الوكيل- =====================-- ┌──────────────────────────────────────────────────────────────────┐- │ البداية │- │ │- │ 1. الوكيل يقرأ AGENTS.md / CLAUDE.md │- │ 2. الوكيل يشغّل init.sh (تثبيت، تحقق، فحص صحي) │- │ 3. الوكيل يقرأ claude-progress.md (ما حدث في المرة السابقة) │- │ 4. الوكيل يقرأ feature_list.json (ما تم إنجازه، ما هو التالي) │- │ 5. الوكيل يفحص سجل git (التغييرات الأخيرة) │- │ │- │ الاختيار │- │ │- │ 6. الوكيل يختار ميزة واحدة غير مكتملة بالضبط │- │ 7. الوكيل يعمل على تلك الميزة فقط │- │ │- │ التنفيذ │- │ │- │ 8. الوكيل ينفّذ الميزة │- │ 9. الوكيل يشغّل التحقق (اختبارات، تنسيق، فحص أنواع) │- │ 10. إذا فشل التحقق: إصلاح وإعادة التشغيل │- │ 11. إذا نجح التحقق: تسجيل الدليل │- │ │- │ الختام │- │ │- │ 12. الوكيل يحدّث claude-progress.md │- │ 13. الوكيل يحدّث feature_list.json │- │ 14. الوكيل يسجّل ما زال معطلاً أو غير مُتحقق منه │- │ 15. الوكيل يلتزم (فقط عندما يكون آمناً للاستئناف) │- │ 16. الوكيل يترك مسار إعادة تشغيل نظيف للجلسة التالية │- │ │- └──────────────────────────────────────────────────────────────────┘-- الحزام يحكم كل انتقال في دورة الحياة هذه.- النموذج يقرر أي كود يكتبه في كل خطوة.- بدون الحزام، الخطوة 9 تصبح "الوكيل يقول يبدو جيداً."- مع الحزام، الخطوة 9 هي "الاختبارات تجتاز، التنسيق نظيف، الأنواع صحيحة."-```-------## لمن هذه الدورة--هذه الدورة موجهة لـ:--- المهندسين الذين يستخدمون بالفعل وكلاء البرمجة ويرغبون في تحسين الاستقرار والجودة-- الباحثين أو البناة الذين يريدون فهماً منهجياً لتصميم الحزام-- قادة التكنولوجيا الذين يحتاجون لفهم كيف يؤثر تصميم البيئة على أداء الوكيل--هذه الدورة ليست لـ:--- الأشخاص الذين يبحثون عن مقدمة للذكاء الاصطناعي بدون كود-- الأشخاص الذين يهتمون فقط بالموجهات ولا يخططون لبناء تطبيقات حقيقية-- المتعلمين غير المستعدين للسماح للوكلاء بالعمل داخل مستودعات حقيقية-------## المتطلبات--هذه دورة حيث تقوم بتشغيل وكلاء البرمجة فعلياً.--تحتاج إلى واحد على الأقل من هذه الأدوات:--- 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.mddeleted file mode 100644index 1448628..0000000--- a/README-CN.md+++ /dev/null@@ -1,579 +0,0 @@-<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>- <a href="./README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?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-到底是什么意思)-- [快速开始:今天就改善你的代理](#快速开始今天就改善你的代理)-- [毕业项目:一个真实的应用](#毕业项目一个真实的应用)-- [学习路径](#学习路径)-- [课程大纲](#课程大纲)-- [技能](#技能)-- [其他课程](#其他课程)-------## 视觉预览--### 课程主页-> 全面的课程大纲和核心理念介绍,为你提供清晰的学习起点。----### 沉浸式讲座-> 深入剖析真实痛点,配合动手项目(如项目 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 上也报告了同样的事情:在一个良好 Harness 的仓库中,同一个模型从"不可靠"变成了"可靠"。这不是边际提升——这是质变。--**这门课程教你如何构建那个环境。**--```text- HARNESS 模式- =============-- 你 --> 给出任务 --> 代理读取 harness 文件 --> 代理执行- |- harness 管控每一个步骤:- |- +--> 指令:做什么,按什么顺序- +--> 范围:一次一个功能,不越界- +--> 状态:进度日志、功能列表、git 历史- +--> 验证:测试、lint、类型检查、冒烟测试- +--> 生命周期:开始时初始化,结束时清理状态- |- v- 代理只在验证通过时- 才会停止-```-------## Harness Engineering 到底是什么意思--Harness Engineering 是围绕模型构建一个完整的工作环境,使其产生可靠的结果。它不是关于写更好的提示词。它是关于设计模型运行其中的系统。--一个 Harness 有五个子系统:--```text- ┌─────────────────────────────────────────────────────────────────┐- │ HARNESS 系统 │- │ │- │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │- │ │ 指令 │ │ 状态 │ │ 验证 │ │- │ │ │ │ │ │ │ │- │ │ AGENTS.md │ │ progress.md │ │ 测试 + lint │ │- │ │ CLAUDE.md │ │ feature_list │ │ 类型检查 │ │- │ │ feature_list │ │ git log │ │ 冒烟测试 │ │- │ │ docs/ │ │ 会话交接 │ │ 端到端流水线 │ │- │ └──────────────┘ └──────────────┘ └──────────────────────┘ │- │ │- │ ┌──────────────┐ ┌──────────────────────────────────────┐ │- │ │ 范围 │ │ 会话生命周期 │ │- │ │ │ │ │ │- │ │ 一次一个功能 │ │ 开始时运行 init.sh │ │- │ │ 明确完成的 │ │ 结束时执行清理检查清单 │ │- │ │ 定义 │ │ 为下一次会话留下交接说明 │ │- │ │ │ │ 只在安全可恢复时才提交 │ │- │ └──────────────┘ └──────────────────────────────────────┘ │- │ │- └─────────────────────────────────────────────────────────────────┘-- 模型决定写什么代码。- HARNESS 管控何时、何地以及如何写。- Harness 不会让模型更聪明。- 它让模型的输出更可靠。-```--每个子系统各司其职:--- **指令**——告诉代理做什么、按什么顺序、开始前读什么。不是一个巨大的文件,而是一个渐进式披露结构,代理按需导航。-- **状态**——追踪已完成的工作、正在进行的工作和下一步。持久化到磁盘,使下一次会话可以准确地从上次离开的地方继续。-- **验证**——只有通过的测试套件才算数。代理不能在没有可运行证据的情况下宣布完成。-- **范围**——将代理限制在一次只做一个功能。不越界。不同时做三个半成品。不重写功能列表来掩盖未完成的工作。-- **会话生命周期**——开始时初始化。结束时清理。为下一次会话留下干净的重启路径。-------## 为什么会有这门课程--问题不是"模型能不能写代码?"它们能。问题是:**它们能否在没有持续人工监督的情况下,在真实的仓库中、跨多个会话、可靠地完成真正的工程任务?**--目前,答案是:没有 Harness 就不行。--```text- 没有 HARNESS 有 HARNESS- ============== ===========-- 会话 1:代理写代码 会话 1:代理读取指令- 代理破坏了测试 代理运行 init.sh- 代理说"完成了" 代理只做一个功能- 你手动修复 代理在声明完成前先验证- 代理更新进度日志- 会话 2:代理从零开始 代理提交干净的状态- 代理不记得之前- 发生了什么 会话 2:代理读取进度日志- 代理重做已完成的工作 代理准确从上次离开处继续- 或者做完全不同的事情 代理继续未完成的功能- 你再次修复 你是审查者,不是救援者-- 结果:你花的时间比 结果:代理完成工作,- 自己做还多 你验证结果-```--这门课程真正关心的问题:--- 哪些 Harness 设计能提高任务完成率?-- 哪些设计能减少返工和错误完成?-- 哪些机制能让长时间运行的任务稳步推进?-- 哪些结构能让系统在多次代理运行后仍然可维护?-------## 课程内容与文档--完整的课程材料,请访问**[文档网站](https://walkinglabs.github.io/learn-harness-engineering/)**。--课程分为三个部分:--1. **讲座**:12 个概念单元,讲解 Harness Engineering 背后的理论。-2. **项目**:6 个动手项目,你将从零构建一个代理工作空间。-3. **资源库**:可直接使用的模板(`AGENTS.md`、`feature_list.json`、`init.sh` 等),今天就能用在你自己的仓库中。-------## 快速开始:今天就改善你的代理--你不需要先读完所有 12 个讲座才能开始获得价值。如果你已经在真实项目中使用编程代理,以下是如何立刻改善它。--思路很简单:与其只写提示词,不如给你的代理一组结构化文件,定义做什么、已做了什么、以及如何验证工作。这些文件存在于你的仓库中,所以每次会话都从相同的状态开始。--```text- 你的项目根目录- ├── 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- ┌─────────────────────────────────────────────────────┐- │ 知识库桌面应用 │- │ │- │ ┌──────────────┐ ┌──────────────────────────────┐│- │ │ 文档列表 │ │ 问答面板 ││- │ │ │ │ ││- │ │ doc-001.md │ │ 问:什么是 Harness Eng? ││- │ │ doc-002.md │ │ 答:围绕代理模型构建的 ││- │ │ doc-003.md │ │ 环境... ││- │ │ ... │ │ [引用: doc-002.md] ││- │ └──────────────┘ └──────────────────────────────┘│- │ │- │ ┌─────────────────────────────────────────────────┐│- │ │ 状态栏:42 篇文档 | 38 篇已索引 | 上次同步 3 分钟前 ││- │ └─────────────────────────────────────────────────┘│- └─────────────────────────────────────────────────────┘-- 核心功能:- ├── 导入本地文档- ├── 管理文档库- ├── 处理和索引文档- ├── 基于导入内容运行 AI 驱动的问答- └── 返回带引用的有据答案-```--选择这个项目是因为它兼具实用价值、足够的真实产品复杂度,以及一个适合观察 Harness 改进前后对比的良好场景。--每个课程项目的 starter/solution 都是此 Electron 应用在相应进化阶段的完整副本。P(N+1) 的 starter 派生自 P(N) 的 solution——随着你的 Harness 技能增长,应用也在进化。-------## 学习路径--课程按顺序设计。每个阶段建立在前一个之上。--```text- 阶段 1:看到问题 阶段 2:结构化仓库- ======================= ==========================-- L01 强模型 ≠ 可靠执行 L03 仓库作为唯一的- 真实来源- L02 Harness 到底意味着什么- L04 将指令分散到多个文件,- 而不是一个巨大文件- |- v |- P01 仅提示词 vs. v- 规则优先对比- P02 代理可读的工作空间--- 阶段 3:连接会话 阶段 4:反馈与范围- ========================== =========================-- L05 让上下文跨会话保持活跃 L07 划清任务边界-- L06 每次代理会话前初始化 L08 功能列表作为 Harness- 基本单元- | |- v v- P03 多会话连续性 P04 运行时反馈- 纠正代理行为--- 阶段 5:验证 阶段 6:整合一切- ===================== ============================-- L09 阻止代理过早 L11 让代理的运行时- 宣布完成 可观测-- L10 完整流水线运行 = L12 每次会话结束时- 真正的验证 干净交接- | |- v v- P05 代理验证自己的工作 P06 构建完整的 Harness- (毕业项目)-```--如果你是业余时间学习,每个阶段大约需要一周。如果你想加快速度,阶段 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- 项目演进- =================-- P01 仅提示词 vs. 规则优先 你看到问题- |- v- P02 代理可读工作空间 你重构仓库- |- v- P03 多会话连续性 你连接会话- |- v- P04 运行时反馈与范围 你添加反馈循环- |- v- P05 自验证 你让代理检查自己- |- v- P06 完整 Harness(毕业项目) 你构建完整系统-- 每个项目的 solution 成为下一个项目的 starter。- 应用在演进。你的 Harness 技能随之增长。-```--### 资源库--- [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- 代理会话生命周期- ======================-- ┌──────────────────────────────────────────────────────────────────┐- │ 启动 │- │ │- │ 1. 代理读取 AGENTS.md / CLAUDE.md │- │ 2. 代理运行 init.sh(安装、验证、健康检查) │- │ 3. 代理读取 claude-progress.md(上次发生了什么) │- │ 4. 代理读取 feature_list.json(哪些完成,哪些待做) │- │ 5. 代理检查 git log(最近的变更) │- │ │- │ 选择 │- │ │- │ 6. 代理精确选择一个未完成的功能 │- │ 7. 代理只做那个功能 │- │ │- │ 执行 │- │ │- │ 8. 代理实现功能 │- │ 9. 代理运行验证(测试、lint、类型检查) │- │ 10. 如果验证失败:修复并重新运行 │- │ 11. 如果验证通过:记录证据 │- │ │- │ 收尾 │- │ │- │ 12. 代理更新 claude-progress.md │- │ 13. 代理更新 feature_list.json │- │ 14. 代理记录仍然有问题或未验证的内容 │- │ 15. 代理提交(仅在安全可恢复时) │- │ 16. 代理为下一次会话留下干净的重启路径 │- │ │- └──────────────────────────────────────────────────────────────────┘-- Harness 管控这个生命周期中的每一次转换。- 模型决定每一步写什么代码。- 没有 Harness,第 9 步变成"代理说看起来没问题"。- 有了 Harness,第 9 步是"测试通过,lint 干净,类型检查通过"。-```-------## 适合谁--本课程适合:--- 已经在使用编程代理、希望获得更好稳定性和质量的工程师-- 希望系统理解 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、桌面应用或本地优先工具的经验-- 有测试、日志或软件架构方面的背景-- 之前接触过 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**:一个开源的动手课程,从基础强化学习概念到 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/README-DE.md b/README-DE.mddeleted file mode 100644index 9472b97..0000000--- a/README-DE.md+++ /dev/null@@ -1,581 +0,0 @@-<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>- <a href="./README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?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- DAS HARNESS-MUSTER- ==================-- Sie --> Aufgabe geben --> Agent liest Harness-Dateien --> Agent führt aus- |- Harness steuert jeden Schritt:- |- +--> Anweisungen: was zu tun ist, in welcher Reihenfolge- +--> Umfang: ein Feature nach dem anderen, keine Übergriffe- +--> Zustand: Fortschrittslog, Feature-Liste, Git-Verlauf- +--> Verifizierung: Tests, Lint, Typprüfung, Smoke-Runs- +--> Lebenszyklus: Initialisierung am Start, sauberer Zustand am Ende- |- v- Agent stoppt nur, wenn- Verifizierung bestanden ist-```-------## 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- ┌─────────────────────────────────────────────────────────────────┐- │ DAS HARNESS │- │ │- │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │- │ │ Anweisungen │ │ Zustand │ │ Verifizierung │ │- │ │ │ │ │ │ │ │- │ │ AGENTS.md │ │ progress.md │ │ Tests + Lint │ │- │ │ CLAUDE.md │ │ feature_list │ │ Typprüfung │ │- │ │ feature_list │ │ git log │ │ Smoke-Runs │ │- │ │ docs/ │ │ Session-Übg. │ │ E2E-Pipeline │ │- │ └──────────────┘ └──────────────┘ └──────────────────────┘ │- │ │- │ ┌──────────────┐ ┌──────────────────────────────────────┐ │- │ │ Umfang │ │ Session-Lebenszyklus │ │- │ │ │ │ │ │- │ │ ein Feature │ │ init.sh am Start │ │- │ │ nach dem and.│ │ Clean-State-Checkliste am Ende │ │- │ │ Definition │ │ Übergabenotiz für nächste Session │ │- │ │ von Fertig │ │ Commit nur wenn sicher fortsetzbar │ │- │ └──────────────┘ └──────────────────────────────────────┘ │- │ │- └─────────────────────────────────────────────────────────────────┘-- Das MODELL entscheidet, welcher Code geschrieben wird.- Das HARNESS steuert, wann, wo und wie es geschrieben wird.- Das Harness macht das Modell nicht schlauer.- Es macht die Ausgabe des Modells zuverlässig.-```--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- OHNE HARNESS MIT HARNESS- =========== ===========-- Session 1: Agent schreibt Code Session 1: Agent liest Anweisungen- Agent zerstört Tests Agent führt init.sh aus- Agent sagt "fertig" Agent arbeitet an einem Feature- Sie reparieren manuell Agent verifiziert vor Fertig-Meldung- Agent aktualisiert Fortschrittslog- Session 2: Agent startet neu Agent committet sauberen Zustand- Agent hat keine Erinnerung- an vorherige Session Session 2: Agent liest Fortschrittslog- Agent macht Arbeit neu Agent setzt genau dort fort- oder macht etwas ganz anderes Agent bearbeitet das unfertige Feature- Sie reparieren wieder Sie überprüfen, statt zu retten-- Ergebnis: Sie verbringen mehr Zeit Ergebnis: Agent erledigt die Arbeit,- mit Aufräumen, als wenn Sie verifizieren das Ergebnis- Sie es selbst gemacht hätten-```--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- IHR PROJEKT-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- ┌─────────────────────────────────────────────────────┐- │ Wissensdatenbank-Desktop-App │- │ │- │ ┌──────────────┐ ┌──────────────────────────────┐│- │ │ Dokumenten- │ │ F&A-Panel ││- │ │ liste │ │ ││- │ │ doc-001.md │ │ F: Was ist Harness Eng.? ││- │ │ doc-002.md │ │ A: Die Umgebung, die um ││- │ │ doc-003.md │ │ ein Agentenmodell... ││- │ │ ... │ │ [Zitat: doc-002.md] ││- │ └──────────────┘ └──────────────────────────────┘│- │ │- │ ┌─────────────────────────────────────────────────┐│- │ │ Statusleiste: 42 Doks | 38 indiziert | letzte Sync 3m ││- │ └─────────────────────────────────────────────────┘│- └─────────────────────────────────────────────────────┘-- Kernfunktionen:- ├── Lokale Dokumente importieren- ├── Eine Dokumentenbibliothek verwalten- ├── Dokumente verarbeiten und indizieren- ├── KI-gestützte F&A über importierte Inhalte ausführen- └── Fundierte Antworten mit Quellnachweisen liefern-```--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: DAS PROBLEM ERKENNEN Phase 2: DAS REPO STRUKTURIEREN- ============================== ===============================-- L01 Starke Modelle ≠ zuverlässige L03 Repository als einzige- Ausführung Wahrheitsquelle- L02 Was ein Harness wirklich bedeutet- L04 Anweisungen auf mehrere- | Dateien aufteilen, nicht eine riesige- v- P01 Nur-Prompt vs. |- regelbasierter Vergleich v- P02 Agentenlesbarer Arbeitsbereich--- Phase 3: SESSIONS VERBINDEN Phase 4: FEEDBACK & UMFANG- =========================== =========================-- L05 Kontext über Sessions hinweg L07 Klare Aufgabengrenzen ziehen- lebendig halten- L08 Feature-Listen als Harness-- L06 Vor jeder Agenten-Session Primitive- initialisieren- |- | v- v P04 Laufzeit-Feedback zur- P03 Multi-Session-Kontinuität Korrektur des Agentenverhaltens--- Phase 5: VERIFIZIERUNG Phase 6: ALLES ZUSAMMENFÜHREN- ======================= ==============================-- L09 Agenten davon abhalten, L11 Laufzeit des Agenten- zu früh Erfolg zu melden beobachtbar machen-- L10 Vollständiger Pipeline-Lauf = L12 Saubere Übergabe am Ende- echte Verifizierung jeder Session-- | |- v v- P05 Agent verifiziert seine P06 Ein vollständiges Harness- eigene Arbeit aufbauen (Abschlussprojekt)-```--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- PROJEKTENTWICKLUNG- ==================-- P01 Nur-Prompt vs. regelbasiert Sie erkennen das Problem- |- v- P02 Agentenlesbarer Arbeitsbereich Sie restrukturieren das Repo- |- v- P03 Multi-Session-Kontinuität Sie verbinden Sessions- |- v- P04 Laufzeit-Feedback & Umfang Sie fügen Feedback-Schleifen hinzu- |- v- P05 Selbstverifizierung Sie lassen den Agenten sich selbst prüfen- |- v- P06 Vollständiges Harness (Abschluss) Sie bauen das Gesamtsystem-- Die Lösung jedes Projekts wird zum Starter des nächsten Projekts.- Die App entwickelt sich weiter. Ihre Harness-Fähigkeiten wachsen mit.-```--### 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- AGENTEN-SESSION-LEBENSZYKLUS- ============================-- ┌──────────────────────────────────────────────────────────────────┐- │ START │- │ │- │ 1. Agent liest AGENTS.md / CLAUDE.md │- │ 2. Agent führt init.sh aus (Installieren, Verifizieren, Check) │- │ 3. Agent liest claude-progress.md (was letztes Mal passierte) │- │ 4. Agent liest feature_list.json (was erledigt, was als Nächstes)│- │ 5. Agent prüft git log (letzte Änderungen) │- │ │- │ AUSWAHL │- │ │- │ 6. Agent wählt genau EIN unfertiges Feature aus │- │ 7. Agent arbeitet nur an diesem Feature │- │ │- │ AUSFÜHRUNG │- │ │- │ 8. Agent implementiert das Feature │- │ 9. Agent führt Verifizierung aus (Tests, Lint, Typprüfung) │- │ 10. Wenn Verifizierung fehlschlägt: korrigieren und neu ausf. │- │ 11. Wenn Verifizierung bestanden: Beweise dokumentieren │- │ │- │ ABSCHLUSS │- │ │- │ 12. Agent aktualisiert claude-progress.md │- │ 13. Agent aktualisiert feature_list.json │- │ 14. Agent dokumentiert, was noch kaputt oder unverifiziert ist │- │ 15. Agent committet (nur wenn sicher fortsetzbar) │- │ 16. Agent hinterlässt sauberen Neustartpfad für nächste Session│- │ │- └──────────────────────────────────────────────────────────────────┘-- Das Harness steuert jeden Übergang in diesem Lebenszyklus.- Das Modell entscheidet, welcher Code bei jedem Schritt geschrieben wird.- Ohne Harness wird Schritt 9 zu „Agent sagt, es sieht gut aus."- Mit Harness ist Schritt 9: „Tests bestanden, Lint sauber, Typen geprüft."-```-------## 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.mddeleted file mode 100644index 9a93e8f..0000000--- a/README-ES.md+++ /dev/null@@ -1,586 +0,0 @@-<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>- <a href="./README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?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- EL PATRÓN DEL HARNESS- =====================-- Tú --> das tarea --> Agente lee archivos del harness --> Agente ejecuta- |- el harness gobierna cada paso:- |- +--> Instrucciones: qué hacer, en qué orden- +--> Alcance: una funcionalidad a la vez, sin excederse- +--> Estado: registro de progreso, lista de funcionalidades, historial git- +--> Verificación: tests, lint, verificación de tipos, pruebas de humo- +--> Ciclo de vida: inicio al arrancar, estado limpio al finalizar- |- v- El agente se detiene solo cuando- la verificación pasa-```-------## 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- ┌─────────────────────────────────────────────────────────────────┐- │ EL HARNESS │- │ │- │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │- │ │ Instrucciones │ │ Estado │ │ Verificación │ │- │ │ │ │ │ │ │ │- │ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │- │ │ CLAUDE.md │ │ feature_list │ │ verif. de tipos │ │- │ │ feature_list │ │ git log │ │ pruebas de humo │ │- │ │ docs/ │ │ handoff ses. │ │ pipeline e2e │ │- │ └──────────────┘ └──────────────┘ └──────────────────────┘ │- │ │- │ ┌──────────────┐ ┌──────────────────────────────────────┐ │- │ │ Alcance │ │ Ciclo de Vida de Sesión │ │- │ │ │ │ │ │- │ │ una func. │ │ init.sh al inicio │ │- │ │ a la vez │ │ checklist de estado limpio al final │ │- │ │ definición │ │ nota de entrega para sig. sesión │ │- │ │ de hecho │ │ commit solo cuando es seguro reanudar│ │- │ └──────────────┘ └──────────────────────────────────────┘ │- │ │- └─────────────────────────────────────────────────────────────────┘-- El MODELO decide qué código escribir.- El HARNESS gobierna cuándo, dónde y cómo lo escribe.- El harness no hace al modelo más inteligente.- Hace que la salida del modelo sea fiable.-```--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- SIN HARNESS CON HARNESS- =========== ===========-- Sesión 1: agente escribe código Sesión 1: agente lee instrucciones- agente rompe tests agente ejecuta init.sh- agente dice "listo" agente trabaja en una funcionalidad- tú lo arreglas manualmente agente verifica antes de decir "listo"- agente actualiza registro de progreso- Sesión 2: agente empieza de cero agente hace commit de estado limpio- agente no tiene memoria- de lo que pasó antes Sesión 2: agente lee registro de progreso- agente rehace el trabajo agente continúa exactamente donde lo dejó- o hace algo totalmente distinto agente sigue con la funcionalidad pendiente- tú lo arreglas otra vez tú revisas, no rescatas-- Resultado: pasas más tiempo Resultado: el agente hace el trabajo,- arreglando que si lo tú verificas el resultado- hubieras hecho tú mismo-```--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- RAÍZ DE TU PROYECTO- ├── AGENTS.md <-- el manual de operación del agente- ├── CLAUDE.md <-- (alternativa, si usas Claude Code)- ├── init.sh <-- ejecuta install + verify + start- ├── feature_list.json <-- qué funcionalidades existen, cuáles están listas- ├── claude-progress.md <-- qué pasó en cada sesión- └── src/ <-- tu código real-```--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- ┌─────────────────────────────────────────────────────┐- │ App de Escritorio Base de Conocimiento │- │ │- │ ┌──────────────┐ ┌──────────────────────────────┐│- │ │ Lista de │ │ Panel de Preguntas y ││- │ │ Documentos │ │ Respuestas ││- │ │ │ │ ││- │ │ doc-001.md │ │ P: Qué es harness eng? ││- │ │ doc-002.md │ │ R: El entorno construido ││- │ │ doc-003.md │ │ alrededor de un agente...││- │ │ ... │ │ [cita: doc-002.md] ││- │ └──────────────┘ └──────────────────────────────┘│- │ │- │ ┌─────────────────────────────────────────────────┐│- │ │ Barra de estado: 42 docs | 38 indexados | últ. 3m│- │ └─────────────────────────────────────────────────┘│- └─────────────────────────────────────────────────────┘-- Funcionalidades principales:- ├── Importar documentos locales- ├── Gestionar una biblioteca de documentos- ├── Procesar e indexar documentos- ├── Ejecutar P&R con IA sobre el contenido importado- └── Devolver respuestas fundamentadas con citas-```--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- Fase 1: VER EL PROBLEMA Fase 2: ESTRUCTURAR EL REPO- ========================= ==========================-- L01 Modelos potentes ≠ ejecución L03 Repositorio como única- fiable fuente de verdad- L02 Qué significa realmente harness- L04 Dividir instrucciones en- | archivos, no un archivo gigante- v- P01 Solo prompts vs. |- comparación con reglas primero v- P02 Espacio de trabajo legible- por el agente--- Fase 3: CONECTAR SESIONES Fase 4: RETROALIMENTACIÓN Y ALCANCE- ========================== ====================================-- L05 Mantener el contexto vivo L07 Dibujar límites claros de tarea- entre sesiones- L08 Listas de funcionalidades como- L06 Inicializar antes de cada primitivas del harness- sesión del agente- |- | v- v P04 Retroalimentación en tiempo de- P03 Continuidad multi-sesión ejecución para corregir el agente--- Fase 5: VERIFICACIÓN Fase 6: PONERLO TODO JUNTO- ===================== ============================-- L09 Evitar que los agentes L11 Hacer observable el runtime- declaren victoria pronto del agente-- L10 Ejecución completa del L12 Entrega limpia al final de- pipeline = verificación real cada sesión-- | |- v v- P05 El agente verifica su P06 Construir un harness completo- propio trabajo (proyecto final)-```--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- EVOLUCIÓN DEL PROYECTO- ======================-- P01 Solo prompts vs. reglas primero Tú ves el problema- |- v- P02 Espacio de trabajo legible Tú reestructuras el repo- por el agente- |- v- P03 Continuidad multi-sesión Tú conectas las sesiones- |- v- P04 Retroalimentación y alcance Tú agregas ciclos de- en tiempo de ejecución retroalimentación- |- v- P05 Auto-verificación Tú haces que el agente- se verifique a sí mismo- |- v- P06 Harness completo (proyecto final) Tú construyes el sistema completo-- La solución de cada proyecto se convierte en el starter del siguiente.- La app evoluciona. Tus habilidades de harness crecen con ella.-```--### 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- CICLO DE VIDA DE LA SESIÓN DEL AGENTE- =====================================-- ┌──────────────────────────────────────────────────────────────────┐- │ INICIO │- │ │- │ 1. Agente lee AGENTS.md / CLAUDE.md │- │ 2. Agente ejecuta init.sh (install, verify, health check) │- │ 3. Agente lee claude-progress.md (qué pasó la última vez) │- │ 4. Agente lee feature_list.json (qué está listo, qué sigue) │- │ 5. Agente revisa git log (cambios recientes) │- │ │- │ SELECCIONAR │- │ │- │ 6. Agente elige exactamente UNA funcionalidad pendiente │- │ 7. Agente trabaja solo en esa funcionalidad │- │ │- │ EJECUTAR │- │ │- │ 8. Agente implementa la funcionalidad │- │ 9. Agente ejecuta verificación (tests, lint, verif. de tipos) │- │ 10. Si la verificación falla: corregir y volver a ejecutar │- │ 11. Si la verificación pasa: registrar evidencia │- │ │- │ CERRAR │- │ │- │ 12. Agente actualiza claude-progress.md │- │ 13. Agente actualiza feature_list.json │- │ 14. Agente registra qué sigue roto o sin verificar │- │ 15. Agente hace commit (solo cuando es seguro reanudar) │- │ 16. Agente deja una ruta de reinicio limpia para la sig. sesión│- │ │- └──────────────────────────────────────────────────────────────────┘-- El harness gobierna cada transición en este ciclo de vida.- El modelo decide qué código escribir en cada paso.- Sin el harness, el paso 9 se convierte en "el agente dice que se ve bien."- Con el harness, el paso 9 es "los tests pasan, el lint está limpio, los tipos verifican."-```-------## 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.mddeleted file mode 100644index f6440ff..0000000--- a/README-FR.md+++ /dev/null@@ -1,580 +0,0 @@-<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>- <a href="./README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?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- LE MODÈLE HARNESS- =================-- Vous --> donnez une tâche --> L'agent lit les fichiers harness --> L'agent exécute- |- Le harness gouverne chaque étape :- |- +--> Instructions : quoi faire, dans quel ordre- +--> Portée : une fonctionnalité à la fois, pas de surcharge- +--> État : journal de progression, liste de fonctionnalités, historique git- +--> Vérification : tests, lint, vérification de types, essais de fumée- +--> Cycle de vie : initialisation au démarrage, état propre à la fin- |- v- L'agent s'arrête uniquement quand- la vérification réussit-```-------## 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- ┌─────────────────────────────────────────────────────────────────┐- │ LE HARNESS │- │ │- │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │- │ │ Instructions │ │ État │ │ Vérification │ │- │ │ │ │ │ │ │ │- │ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │- │ │ CLAUDE.md │ │ feature_list │ │ vérif. de types │ │- │ │ feature_list │ │ git log │ │ essais de fumée │ │- │ │ docs/ │ │ transfert │ │ pipeline e2e │ │- │ └──────────────┘ └──────────────┘ └──────────────────────┘ │- │ │- │ ┌──────────────┐ ┌──────────────────────────────────────┐ │- │ │ Portée │ │ Cycle de vie de session │ │- │ │ │ │ │ │- │ │ une seule │ │ init.sh au démarrage │ │- │ │ fonctionnalité│ │ liste de contrôle état propre à fin │ │- │ │ définition │ │ note de transfert pour prochaine │ │- │ │ de « terminé »│ │ commit uniquement si reprise sûre │ │- │ └──────────────┘ └──────────────────────────────────────┘ │- │ │- └─────────────────────────────────────────────────────────────────┘-- Le MODÈLE décide quel code écrire.- Le HARNESS gouverne quand, où et comment il l'écrit.- Le harness ne rend pas le modèle plus intelligent.- Il rend la sortie du modèle fiable.-```--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- SANS HARNESS AVEC HARNESS- =========== ============-- Session 1 : l'agent écrit du code Session 1 : l'agent lit les instructions- l'agent casse les tests l'agent exécute init.sh- l'agent dit « terminé » l'agent travaille sur une fonctionnalité- vous corrigez manuellement l'agent vérifie avant de déclarer « terminé »- l'agent met à jour le journal de progression- Session 2 : l'agent repart de zéro l'agent commit un état propre- l'agent n'a aucun souvenir- de ce qui s'est passé avant Session 2 : l'agent lit le journal de progression- l'agent refait le travail l'agent reprend exactement là où il s'est arrêté- ou fait autre chose totalement l'agent continue la fonctionnalité inachevée- vous corrigez encore vous révisez, vous ne sauvez pas-- Résultat : vous passez plus de temps Résultat : l'agent fait le travail,- à nettoyer qu si vous vous vérifiez le résultat- l'aviez fait vous-même-```--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- RACINE DE VOTRE PROJET- ├── AGENTS.md <-- le manuel de fonctionnement de l'agent- ├── CLAUDE.md <-- (alternative, si vous utilisez Claude Code)- ├── init.sh <-- exécute installation + vérification + démarrage- ├── feature_list.json <-- quelles fonctionnalités existent, lesquelles sont terminées- ├── claude-progress.md <-- ce qui s'est passé à chaque session- └── src/ <-- votre code réel-```--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- ┌─────────────────────────────────────────────────────┐- │ Application Bureau de Base de Connaissances │- │ │- │ ┌──────────────┐ ┌──────────────────────────────┐│- │ │ Liste de │ │ Panneau Q&R ││- │ │ documents │ │ ││- │ │ doc-001.md │ │ Q : Qu'est-ce que le harness││- │ │ doc-002.md │ │ R : L'environnement construit││- │ │ doc-003.md │ │ autour d'un modèle d'agent││- │ │ ... │ │ [citation : doc-002.md] ││- │ └──────────────┘ └──────────────────────────────┘│- │ │- │ ┌─────────────────────────────────────────────────┐│- │ │ Barre d'état : 42 docs | 38 indexés | sync 3m ││- │ └─────────────────────────────────────────────────┘│- └─────────────────────────────────────────────────────┘-- Fonctionnalités principales :- ├── Importer des documents locaux- ├── Gérer une bibliothèque de documents- ├── Traiter et indexer des documents- ├── Exécuter des Q&R alimentées par l'IA sur le contenu importé- └── Retourner des réponses fondées avec des 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 : VOIR LE PROBLÈME Phase 2 : STRUCTURER LE DÉPÔT- =========================== =============================-- L01 Des modèles performants ≠ L03 Le dépôt comme unique- une exécution fiable source de vérité- L02 Ce que signifie réellement- un harness L04 Répartir les instructions entre- plusieurs fichiers, pas un seul fichier géant- |- v |- P01 Comparaison prompts seuls v- vs. règles d'abord P02 Espace de travail lisible par l'agent--- Phase 3 : CONNECTER LES SESSIONS Phase 4 : RETOUR & PORTÉE- ================================= =========================-- L05 Maintenir le contexte L07 Définir des limites de tâches claires- entre les sessions- L08 Les listes de fonctionnalités comme- L06 Initialiser avant chaque primitives du harness- session d'agent- |- | v- v P04 Retour d'exécution pour- P03 Continuité multi-sessions corriger le comportement de l'agent--- Phase 5 : VÉRIFICATION Phase 6 : TOUT ASSEMBLER- ====================== ========================-- L09 Empêcher les agents de L11 Rendre l'exécution de l'agent- déclarer victoire trop tôt observable-- L10 Une exécution complète du L12 Transfert propre à la fin de- pipeline = vraie vérification chaque session-- | |- v v- P05 L'agent vérifie son propre travail P06 Construire un harness complet- (projet final)-```--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- ÉVOLUTION DES PROJETS- =====================-- P01 Prompts seuls vs. règles d'abord Vous voyez le problème- |- v- P02 Espace de travail lisible Vous restructurez le dépôt- par l'agent- |- v- P03 Continuité multi-sessions Vous connectez les sessions- |- v- P04 Retour d'exécution & portée Vous ajoutez des boucles de retour- |- v- P05 Auto-vérification Vous faites en sorte que l'agent se vérifie- |- v- P06 Harness complet (projet final) Vous construisez le système complet-- La solution de chaque projet devient le starter du projet suivant.- L'application évolue. Vos compétences en harness grandissent avec elle.-```--### 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- CYCLE DE VIE DE LA SESSION DE L'AGENT- ======================================-- ┌──────────────────────────────────────────────────────────────────┐- │ DÉMARRAGE │- │ │- │ 1. L'agent lit AGENTS.md / CLAUDE.md │- │ 2. L'agent exécute init.sh (installation, vérif., contrôle) │- │ 3. L'agent lit claude-progress.md (ce qui s'est passé) │- │ 4. L'agent lit feature_list.json (terminé, à faire) │- │ 5. L'agent vérifie git log (changements récents) │- │ │- │ SÉLECTION │- │ │- │ 6. L'agent choisit exactement UNE fonctionnalité inachevée │- │ 7. L'agent travaille uniquement sur cette fonctionnalité │- │ │- │ EXÉCUTION │- │ │- │ 8. L'agent implémente la fonctionnalité │- │ 9. L'agent exécute la vérification (tests, lint, types) │- │ 10. Si la vérification échoue : corriger et relancer │- │ 11. Si la vérification réussit : enregistrer la preuve │- │ │- │ CLÔTURE │- │ │- │ 12. L'agent met à jour claude-progress.md │- │ 13. L'agent met à jour feature_list.json │- │ 14. L'agent enregistre ce qui reste cassé ou non vérifié │- │ 15. L'agent commit (uniquement si la reprise est sûre) │- │ 16. L'agent laisse un chemin de redémarrage propre │- │ │- └──────────────────────────────────────────────────────────────────┘-- Le harness gouverne chaque transition dans ce cycle de vie.- Le modèle décide quel code écrire à chaque étape.- Sans le harness, l'étape 9 devient « l'agent dit que ça a l'air correct ».- Avec le harness, l'étape 9 est « les tests passent, le lint est propre, les types sont valides ».-```-------## À 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.mddeleted file mode 100644index 5e3440b..0000000--- a/README-JA.md+++ /dev/null@@ -1,581 +0,0 @@-<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>- <a href="./README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?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- ハーネスパターン- ================-- あなた --> タスクを与える --> エージェントがハーネスファイルを読む --> エージェントが実行- |- ハーネスが全ステップを管理:- |- +--> 指示:何を、どの順序で行うか- +--> スコープ:一度に一つの機能、過剰な範囲拡大なし- +--> 状態:進捗ログ、機能リスト、git履歴- +--> 検証:テスト、lint、型チェック、スモーク実行- +--> ライフサイクル:開始時に初期化、終了時にクリーンな状態- |- v- エージェントは検証が- 通過した時のみ停止-```-------## Harness Engineering が本当に意味すること--Harness Engineering は、モデルの周囲に完全な作業環境を構築し、信頼性の高い結果を生成させることです。より良いプロンプトを書くことではありません。モデルが内部で動作するシステムを設計することです。--ハーネスには5つのサブシステムがあります:--```text- ┌─────────────────────────────────────────────────────────────────┐- │ ハーネス │- │ │- │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │- │ │ 指示 │ │ 状態 │ │ 検証 │ │- │ │ │ │ │ │ │ │- │ │ AGENTS.md │ │ progress.md │ │ テスト + lint │ │- │ │ CLAUDE.md │ │ feature_list │ │ 型チェック │ │- │ │ feature_list │ │ git log │ │ スモーク実行 │ │- │ │ docs/ │ │ セションハンドオフ│ │ e2eパイプライン │ │- │ └──────────────┘ └──────────────┘ └──────────────────────┘ │- │ │- │ ┌──────────────┐ ┌──────────────────────────────────────┐ │- │ │ スコープ │ │ セッションライフサイクル │ │- │ │ │ │ │ │- │ │ 一度に │ │ 開始時にinit.shを実行 │ │- │ │ 一つの機能 │ │ 終了時にクリーン状態チェックリスト │ │- │ │ 完了の定義 │ │ 次セッションへのハンドオフノート │ │- │ │ │ │ 再開安全な場合のみコミット │ │- │ └──────────────┘ └──────────────────────────────────────┘ │- │ │- └─────────────────────────────────────────────────────────────────┘-- モデルは書くコードを決定する。- ハーネスはいつ、どこで、どう書くかを管理する。- ハーネスはモデルを賢くするわけではない。- モデルの出力を信頼性のあるものにする。-```--各サブシステムには一つの役割があります:--- **Instructions** — エージェントに何を、どの順序で、開始前に何を読むべきかを伝えます。一つの巨大なファイルではなく、エージェントが必要に応じてナビゲートする段階的開示構造です。-- **State** — 何が完了し、何が進行中で、何が次かを追跡します。ディスクに永続化され、次のセッションは前回の続きから正確に再開できます。-- **Verification** — 合格したテストスイートのみが証拠として認められます。エージェントは実行可能な証拠なしに完了を宣言できません。-- **Scope** — エージェントを一度に一つの機能に制約します。過剰な範囲拡大なし。3つのことを中途半端に終わらせることなし。未完了の作業を隠すために機能リストを書き換えることなし。-- **Session Lifecycle** — 開始時に初期化。終了時にクリーンアップ。次のセッションのためのクリーンな再起動パスを残します。-------## なぜこのコースが存在するのか--問題は「モデルはコードを書けるか?」ではありません。書けます。問題は:**実際のリポジトリ内で、複数のセッションにわたり、常に人間の監視なしに、実際のエンジニアリングタスクを確実に完了できるか?** ということです。--現時点での答えは:ハーネスなしでは無理です。--```text- ハーネスなし ハーネスあり- ========== ==========-- セッション1: エージェントがコードを書く セッション1: エージェントが指示を読む- エージェントがテストを壊す エージェントがinit.shを実行- エージェントが「完了」と言う エージェントが一つの機能に取り組む- あなたが手動で修正 エージェントが完了宣言前に検証- エージェントが進捗ログを更新- セッション2: エージェントがゼロから開始 エージェントがクリーンな状態でコミット- エージェントは前回の記憶がない- セッション2: エージェントが進捗ログを読む- エージェントが同じ作業をやり直す エージェントが前回の続きから正確に再開- または全く別のことをする エージェントが未完了の機能を継続- あなたがまた修正 あなたは確認する、修正するのではない-- 結果: 自分でやるよりも 結果: エージェントが作業を行い、- 修正に多くの時間を費やす あなたは結果を検証する-```--このコースが本当に重視している問い:--- どのハーネス設計がタスク完了率を向上させるか?-- どの設計が手戻りや誤った完了を減らすか?-- どのメカニズムが長時間実行タスクを着実に進行させるか?-- どの構造が複数回のエージェント実行後もシステムを保守可能に保つか?-------## コースカリキュラムとドキュメント--完全なコース資料については、**[ドキュメントウェブサイト](https://walkinglabs.github.io/learn-harness-engineering/)** をご覧ください。--カリキュラムは3つの部分に分かれています:--1. **レクチャー**:Harness Engineering の背景理論を説明する12の概念ユニット。-2. **プロジェクト**:ゼロからエージェントワークスペースを構築する6つのハンズオンプロジェクト。-3. **リソースライブラリ**:自分のリポジトリで今日すぐ使えるコピー用テンプレート(`AGENTS.md`、`feature_list.json`、`init.sh` など)。-------## クイックスタート:今日からエージェントを改善する--価値を得るために12のレクチャーをすべて読む必要はありません。すでに実際のプロジェクトでコーディングエージェントを使用している場合、今すぐ改善する方法は以下の通りです。--アイデアはシンプルです:プロンプトを書く代わりに、何をすべきか、何が完了しているか、作業をどう検証するかを定義する構造化ファイルのセットをエージェントに与えます。これらのファイルはリポジトリ内に存在するため、すべてのセッションが同じ状態から始まります。--```text- あなたのプロジェクトルート- ├── 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- ┌─────────────────────────────────────────────────────┐- │ ナレッジベースデスクトップアプリ │- │ │- │ ┌──────────────┐ ┌──────────────────────────────┐│- │ │ ドキュメント │ │ Q&Aパネル ││- │ │ リスト │ │ ││- │ │ doc-001.md │ │ Q: ハーネスエンジニアリング ││- │ │ doc-002.md │ │ とは何か? ││- │ │ doc-003.md │ │ A: エージェントモデルの ││- │ │ ... │ │ 周囲に構築された環境... ││- │ │ │ │ [引用元: doc-002.md] ││- │ └──────────────┘ └──────────────────────────────┘│- │ │- │ ┌─────────────────────────────────────────────────┐│- │ │ ステータスバー: 42文書 | 38件インデックス済 | 最終同期 3分前││- │ └─────────────────────────────────────────────────┘│- └─────────────────────────────────────────────────────┘-- コア機能:- ├── ローカルドキュメントのインポート- ├── ドキュメントライブラリの管理- ├── ドキュメントの処理とインデックス作成- ├── インポートしたコンテンツに対するAI搭載Q&Aの実行- └── 引用付きの根拠ある回答の返却-```--このプロジェクトが選ばれたのは、実用的な価値、十分な現実世界の製品複雑さ、ハーネス改善の前後を観察するのに適した設定を組み合わせているからです。--各コースプロジェクトのスターター/ソリューションは、その進化段階におけるこの Electron アプリの完全なコピーです。P(N+1) のスターターは P(N) のソリューションから派生します — アプリはあなたのハーネスキルの成長とともに進化します。-------## 学習パス--このコースは順番に進めるように設計されています。各フェーズは前のフェーズの上に構築されます。--```text- フェーズ1: 問題を見る フェーズ2: リポジトリを構造化- ================================= =================================-- L01 強力なモデル ≠ 確実な実行 L03 リポジトリを唯一の- 信頼できる情報源にする- L02 ハーネスが実際に意味するもの- L04 指示を複数ファイルに分割、- | 一つの巨大ファイルにしない- v- P01 プロンプトのみ vs. |- ルール優先の比較 v- P02 エージェント可読ワークスペース--- フェーズ3: セッションを接続 フェーズ4: フィードバックとスコープ- ================================= ====================================-- L05 セッション間で L07 明確なタスク境界を引く- コンテキストを維持- L08 機能リストをハーネスの- L06 毎回のエージェント プリミティブとして使う- セッション前に初期化- |- | v- v P04 エージェントの動作を修正する- P03 マルチセッション連続性 ランタイムフィードバック--- フェーズ5: 検証 フェーズ6: すべてを統合- ===================== ============================-- L09 エージェントが早すぎる L11 エージェントのランタイムを- 完了宣言をするのを防ぐ 観測可能にする-- L10 フルパイプライン実行 = L12 全セッションの終了時に- 本当の検証 クリーンなハンドオフ-- | |- v v- P05 エージェントが自分の作業を検証 P06 完全なハーネスを構築- (カプロジェクト)-```--パートタイムで進める場合、各フェーズは約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- プロジェクトの進化- ==================-- P01 プロンプトのみ vs. ルール優先 問題を目撃する- |- v- P02 エージェント可読ワークスペース リポジトリを再構築する- |- v- P03 マルチセッション連続性 セッションを接続する- |- v- P04 ランタイムフィードバックとスコープ フィードバックループを追加する- |- v- P05 自己検証 エージェントに自己チェックさせる- |- v- P06 完全なハーネス(カプロジェクト) 完全なシステムを構築する-- 各プロジェクトのソリューションが次のプロジェクトのスターターになる。- アプリは進化する。あなたのハーネスキルも共に成長する。-```--### リソースライブラリ--- [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- エージェントセッションライフサイクル- ====================================-- ┌──────────────────────────────────────────────────────────────────┐- │ 開始 │- │ │- │ 1. エージェントがAGENTS.md / CLAUDE.mdを読む │- │ 2. エージェントがinit.shを実行(インストール、検証、ヘルスチェック)│- │ 3. エージェントがclaude-progress.mdを読む(前回の内容) │- │ 4. エージェントがfeature_list.jsonを読む(完了済み、次の作業) │- │ 5. エージェントがgit logを確認(最近の変更) │- │ │- │ 選択 │- │ │- │ 6. エージェントは未完了の機能を正確に1つだけ選択 │- │ 7. エージェントはその機能のみに取り組む │- │ │- │ 実行 │- │ │- │ 8. エージェントが機能を実装する │- │ 9. エージェントが検証を実行(テスト、lint、型チェック) │- │ 10. 検証失敗時:修正して再実行 │- │ 11. 検証通過時:証拠を記録 │- │ │- │ 仕上げ │- │ │- │ 12. エージェントがclaude-progress.mdを更新 │- │ 13. エージェントがfeature_list.jsonを更新 │- │ 14. エージェントがまだ壊れている、または未検証の項目を記録 │- │ 15. エージェントがコミット(再開安全な場合のみ) │- │ 16. エージェントが次セッション用のクリーンな再起動パスを残す │- │ │- └──────────────────────────────────────────────────────────────────┘-- ハーネスはこのライフサイクルの全移行を管理する。- モデルは各ステップで書くコードを決定する。- ハーネスなしでは、ステップ9は「エージェントが大丈夫そうだと言う」になる。- ハーネスありでは、ステップ9は「テスト通過、lintクリーン、型チェックOK」になる。-```-------## 対象者--このコースは以下の方を対象としています:--- コーディングエージェントをすでに使用しており、安定性と品質を向上させたいエンジニア-- ハーネス設計の体系的な理解を求める研究者やビルダー-- 環境設計がエージェントのパフォーマンスにどう影響するかを理解する必要があるテックリード--このコースは以下の方を対象としていません:--- ゼロコードの 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.mddeleted file mode 100644index e592fbb..0000000--- a/README-KO.md+++ /dev/null@@ -1,579 +0,0 @@-<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>- <a href="./README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?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의-진정한-의미)-- [빠른 시작: 오늘 바로 에이전트 개선하기](#빠른-시작-오늘-바로-에이전트-개선하기)-- [캡스톤 프로젝트: 실제 앱](#캡스톤-프로젝트-실제-앱)-- [학습 경로](#학습-경로)-- [강의 개요](#강의-개요)-- [스킬](#스킬)-- [다른 강좌](#다른-강좌)-------## ✨ 시각적 미리보기--### 🏠 강좌 홈페이지-> 포괄적인 강좌 개요와 핵심 철학에 대한 소개로, 시작하기 위한 명확한 경로를 제공합니다.----### 📖 몰입형 강의-> 실제 문제점에 대한 심층 분석과 실습 프로젝트(예: 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에 게시할 수 있습니다.-------## 모델은 똑똑하고, 하니스가 안정성을 만듭니다--대부분의 사람들이 어려운 방식으로 깨닫는 뼈아픈 사실이 있습니다: **세계에서 가장 강력한 모델이라도 주변에 적절한 환경을 구축하지 않으면 실제 엔지니어링 작업에서 여전히 실패합니다.**--직접 겪어보셨을 것입니다. 여러분의 저장소에서 Claude나 GPT에 작업을 맡깁니다. 처음에는 잘 진행됩니다 — 파일을 읽고, 코드를 작성하고, 생산적으로 보입니다. 그러다 무언가 잘못됩니다. 단계를 건너뜁니다. 테스트를 망가뜨립니다. "완료"라고 말하지만 실제로는 아무것도 작동하지 않습니다. 직접 했더라면 더 빨랐을 작업을 수정하는 데 더 많은 시간을 쓰게 됩니다.--이것은 모델의 문제가 아닙니다. 하니스의 문제입니다.--증거는 명확합니다. Anthropic은 통제된 실험을 진행했습니다: 동일한 모델(Opus 4.5), 동일한 프롬프트("2D 레트로 게임 에디터 구축"). 하니스 없이는 20분 만에 $9를 소비하고 작동하지 않는 결과물을 만들었습니다. 전체 하니스(플래너 + 제너레이터 + 평가자)를 갖추면 6시간 동안 $200를 소비하고 실제로 플레이할 수 있는 게임을 구축했습니다. 모델은 변하지 않았습니다. 하니스가 달랐습니다.--OpenAI도 Codex에서 동일한 결과를 보고했습니다: 잘 구축된 하니스가 있는 저장소에서는 동일한 모델이 "불안정"에서 "안정적"으로 변합니다. 미미한 개선이 아닌 질적인 전환입니다.--**이 강좌는 그 환경을 구축하는 방법을 가르칩니다.**--```text- 하니스 패턴- ==========-- 사용자 --> 작업 전달 --> 에이전트가 하니스 파일 읽음 --> 에이전트 실행- |- 하니스가 모든 단계를 제어:- |- +--> 지시 사항: 무엇을, 어떤 순서로 할 것인가- +--> 범위: 한 번에 하나의 기능, 과도한 작업 금지- +--> 상태: 진행 로그, 기능 목록, git 기록- +--> 검증: 테스트, 린트, 타입 검사, 스모크 실행- +--> 수명 주기: 시작 시 초기화, 종료 시 깔끔한 상태- |- v- 에이전트는 검증을 통과한 경우에만- 실행을 중지합니다-```-------## Harness Engineering의 진정한 의미--Harness engineering은 모델 주변에 안정적인 결과를 생성하는 완전한 작업 환경을 구축하는 것입니다. 더 나은 프롬프트를 작성하는 것이 아닙니다. 모델이 작동하는 시스템 자체를 설계하는 것입니다.--하니스에는 다섯 가지 하위 시스템이 있습니다:--```text- ┌─────────────────────────────────────────────────────────────────┐- │ 하니스 │- │ │- │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │- │ │ 지시 사항 │ │ 상태 │ │ 검증 │ │- │ │ │ │ │ │ │ │- │ │ AGENTS.md │ │ progress.md │ │ 테스트 + 린트 │ │- │ │ CLAUDE.md │ │ 기능 목록 │ │ 타입 검사 │ │- │ │ 기능 목록 │ │ git log │ │ 스모크 실행 │ │- │ │ docs/ │ │ 세션 인계 │ │ e2e 파이프라인 │ │- │ └──────────────┘ └──────────────┘ └──────────────────────┘ │- │ │- │ ┌──────────────┐ ┌──────────────────────────────────────┐ │- │ │ 범위 │ │ 세션 수명 주기 │ │- │ │ │ │ │ │- │ │ 한 번에 │ │ 시작 시 init.sh 실행 │ │- │ │ 하나의 기능 │ │ 종료 시 깔끔한 상태 체크리스트 │ │- │ │ 완료 정의 │ │ 다음 세션을 위한 인계 노트 │ │- │ │ │ │ 안전하게 재개 가능할 때만 커밋 │ │- │ └──────────────┘ └──────────────────────────────────────┘ │- │ │- └─────────────────────────────────────────────────────────────────┘-- 모델은 어떤 코드를 작성할지 결정합니다.- 하니스는 언제, 어디서, 어떻게 작성할지 제어합니다.- 하니스는 모델을 더 똑똑하게 만들지 않습니다.- 모델의 출력을 안정적으로 만듭니다.-```--각 하위 시스템은 하나의 역할을 담당합니다:--- **지시 사항(Instructions)** — 에이전트에게 무엇을, 어떤 순서로, 시작하기 전에 무엇을 읽어야 하는지 알려줍니다. 거대한 단일 파일이 아닌, 에이전트가 필요에 따라 탐색하는 점진적 공개 구조입니다.-- **상태(State)** — 완료된 작업, 진행 중인 작업, 다음 작업을 추적합니다. 디스크에 영속화되어 다음 세션이 정확히 이전 세션이 중단된 지점에서 이어집니다.-- **검증(Verification)** — 통과하는 테스트 스위트만 증거로 인정됩니다. 에이전트는 실행 가능한 증명 없이 완료를 선언할 수 없습니다.-- **범위(Scope)** — 에이전트를 한 번에 하나의 기능으로 제한합니다. 과도한 작업 금지. 세 가지를 반쯤 완성하는 것 금지. 미완료 작업을 숨기기 위해 기능 목록을 재작성하는 것 금지.-- **세션 수명 주기(Session Lifecycle)** — 시작할 때 초기화. 끝날 때 정리. 다음 세션을 위한 깔끔한 재시작 경로를 남깁니다.-------## 이 강좌가 존재하는 이유--질문은 "모델이 코드를 작성할 수 있는가?"가 아닙니다. 작성할 수 있습니다. 진짜 질문은: **실제 저장소 내에서 여러 세션에 걸쳐 지속적인 인간 감독 없이 실제 엔지니어링 작업을 안정적으로 완료할 수 있는가?**입니다.--현재 답은: 하니스 없이는 불가능합니다.--```text- 하니스 없음 하니스 있음- ========= ========-- 세션 1: 에이전트가 코드를 작성 세션 1: 에이전트가 지시 사항을 읽음- 에이전트가 테스트를 망가뜨림 에이전트가 init.sh를 실행- 에이전트가 "완료"라고 선언 에이전트가 하나의 기능에 집중- 사용자가 직접 수정 에이전트가 완료 선언 전 검증- 에이전트가 진행 로그를 업데이트- 세션 2: 에이전트가 처음부터 시작 에이전트가 깔끔한 상태로 커밋- 에이전트에게 이전 기록 없음- 에이전트가 작업을 다시 시작 세션 2: 에이전트가 진행 로그를 읽음- 또는 전혀 다른 작업을 수행 에이전트가 정확히 중단한 지점부터 이어서 작업- 사용자가 또다시 수정 에이전트가 미완료 기능을 계속 진행- 사용자는 검토만, 구조 작업은 불필요-- 결과: 직접 했더라면 더 빨랐을 결과: 에이전트가 작업을 수행하고,- 작업을 수정하는 데 더 많은 사용자가 결과를 검증- 시간을 소비-```--이 강좌가 실제로 다루는 질문들:--- 어떤 하니스 설계가 작업 완료율을 향상시키는가?-- 어떤 설계가 재작업 및 잘못된 완료를 줄이는가?-- 어떤 메커니즘이 장기 실행 작업을 꾸준히 진행되게 유지하는가?-- 어떤 구조가 여러 에이전트 실행 후에도 시스템을 유지보수 가능하게 만드는가?-------## 강의 과정 및 문서--전체 강의 자료는 **[문서 웹사이트](https://walkinglabs.github.io/learn-harness-engineering/)**를 방문하세요.--과정은 세 부분으로 나뉩니다:--1. **강의(Lectures)**: Harness engineering 이론을 설명하는 12개의 개념적 단원.-2. **프로젝트(Projects)**: 처음부터 에이전트 작업 공간을 구축하는 6개의 실습 프로젝트.-3. **리소스 라이브러리**: 여러분의 저장소에 오늘 바로 사용할 수 있는 복사 가능 템플릿(`AGENTS.md`, `feature_list.json`, `init.sh` 등).-------## 빠른 시작: 오늘 바로 에이전트 개선하기--12개의 강의를 모두 읽고 나서 가치를 얻기 시작할 필요가 없습니다. 이미 실제 프로젝트에서 코딩 에이전트를 사용하고 있다면, 지금 당장 개선하는 방법은 다음과 같습니다.--핵심 아이디어는 간단합니다: 프롬프트만 작성하는 대신, 무엇을 해야 하는지, 무엇이 완료되었는지, 작업을 어떻게 검증할지 정의하는 구조화된 파일 세트를 에이전트에 제공하세요. 이 파일들은 저장소 내에 있으므로 모든 세션이 동일한 상태에서 시작합니다.--```text- 프로젝트 루트 디렉토리- ├── AGENTS.md <-- 에이전트의 운영 매뉴얼- ├── CLAUDE.md <-- (대체, Claude Code 사용 시)- ├── init.sh <-- 설치 + 검증 + 시작 실행- ├── feature_list.json <-- 어떤 기능이 있는지, 무엇이 완료되었는지- ├── claude-progress.md <-- 각 세션에서 무슨 일이 있었는지- └── src/ <-- 실제 코드-```--[리소스 라이브러리](https://walkinglabs.github.io/learn-harness-engineering/en/resources/)에서 스타터 템플릿을 가져와 프로젝트에 넣으세요. 그게 전부입니다. 네 개의 파일만으로 프롬프트만 사용할 때보다 에이전트 세션이 훨씬 더 안정적일 것입니다.-------## 캡스톤 프로젝트: 실제 앱--6개의 강좌 프로젝트는 모두 동일한 제품을 중심으로 전개됩니다: **Electron 기반 개인 지식 베이스 데스크톱 앱**.--```text- ┌─────────────────────────────────────────────────────┐- │ 지식 베이스 데스크톱 앱 │- │ │- │ ┌──────────────┐ ┌──────────────────────────────┐│- │ │ 문서 목록 │ │ Q&A 패널 ││- │ │ │ │ ││- │ │ doc-001.md │ │ 질문: 하니스 엔지니어링이란? ││- │ │ doc-002.md │ │ 답변: 에이전트 모델 주변에 ││- │ │ doc-003.md │ │ 구축된 환경... ││- │ │ ... │ │ [출처: doc-002.md] ││- │ └──────────────┘ └──────────────────────────────┘│- │ │- │ ┌─────────────────────────────────────────────────┐│- │ │ 상태 표시줄: 42개 문서 | 38개 인덱싱 | 마지막 동기화 3분 전 ││- │ └─────────────────────────────────────────────────┘│- └─────────────────────────────────────────────────────┘-- 핵심 기능:- ├── 로컬 문서 가져오기- ├── 문서 라이브러리 관리- ├── 문서 처리 및 인덱싱- ├── 가져온 콘텐츠에 대한 AI 기반 Q&A 실행- └── 출처가 포함된 근거 기반 답변 반환-```--이 프로젝트는 강력한 실용적 가치, 충분한 실제 제품 복잡성, 그리고 하니스 개선 전후를 관찰하기 좋은 환경을 결합하고 있어 선택되었습니다.--각 강좌 프로젝트의 스타터/솔루션은 해당 진화 단계의 Electron 앱 전체 사본입니다. P(N+1)의 스타터는 P(N)의 솔루션에서 파생됩니다 — 앱은 여러분의 하니스 기술이 성장함에 따라 함께 진화합니다.-------## 학습 경로--이 강좌는 순서대로 진행하도록 설계되었습니다. 각 단계는 이전 단계를 기반으로 구축됩니다.--```text- 1단계: 문제 인식 2단계: 저장소 구조화- ================ ================-- L01 강력한 모델 ≠ 안정적 실행 L03 저장소를 단일 진실 공급원으로- L02 하니스가 실제로 의미하는 것- L04 거대한 단일 파일 대신- | 여러 파일로 지시 사항 분할- v- P01 프롬프트만 vs. |- 규칙 우선 비교 v- P02 에이전트 판독 가능 작업 공간--- 3단계: 세션 연결 4단계: 피드백 및 범위- ================ ==================-- L05 세션 간 컨텍스트 유지 L07 명확한 작업 경계 설정- L06 모든 에이전트 세션 전- 초기화 L08 기능 목록을 하니스 프리미티브로-- |- | v- v P04 에이전트 동작 교정을 위한- P03 다중 세션 연속성 런타임 피드백--- 5단계: 검증 6단계: 모든 것을 종합- ========== ==================-- L09 에이전트가 너무 일찍 L11 에이전트의 런타임을- 완료를 선언하지 못하게 방지 관측 가능하게 만들기-- L10 전체 파이프라인 실행 = L12 모든 세션 종료 시- 진정한 검증 깔끔한 인계-- | |- v v- P05 에이전트가 자체 검증 P06 완전한 하니스 구축- (캡스톤 프로젝트)-```--파트타임으로 진행하면 각 단계는 약 1주일이 소요됩니다. 더 빠르게 진행하고 싶다면 1~3단계는 긴 주말에 완료할 수 있습니다.-------## 강의 개요--### 강의 — 각각 하나의 핵심 질문에 답하는 12개의 개념적 단원--*각 강의의 전체 내용은 [문서 웹사이트](https://walkinglabs.github.io/learn-harness-engineering/)에서 읽을 수 있습니다.*--| 세션 | 질문 | 핵심 아이디어 |-|---------|----------|-----------|-| [L01](../../docs/lectures/lecture-01-why-capable-agents-still-fail/index.md) | 왜 강력한 모델도 실제 작업에서 여전히 실패하는가? | 벤치마크와 실제 엔지니어링 사이의 역량 격차 |-| [L02](../../docs/lectures/lecture-02-what-a-harness-actually-is/index.md) | "하니스"는 실제로 무엇을 의미하는가? | 다섯 가지 하위 시스템: 지시 사항, 상태, 검증, 범위, 수명 주기 |-| [L03](../../docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | 왜 저장소가 단일 진실 공급원이어야 하는가? | 에이전트가 볼 수 없다면 존재하지 않는 것과 같다 |-| [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) | 동일한 작업을 두 번 실행: 프롬프트만 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- 프로젝트 발전 과정- ==================-- P01 프롬프트만 vs. 규칙 우선 문제를 직접 확인합니다- |- v- P02 에이전트 판독 가능 작업 공간 저장소를 재구성합니다- |- v- P03 다중 세션 연속성 세션을 연결합니다- |- v- P04 런타임 피드백 및 범위 피드백 루프를 추가합니다- |- v- P05 자체 검증 에이전트가 스스로 검증하게 만듭니다- |- v- P06 완전한 하니스 (캡스톤) 전체 시스템을 구축합니다-- 각 프로젝트의 솔루션이 다음 프로젝트의 스타터가 됩니다.- 앱이 발전합니다. 여러분의 하니스 기술도 함께 성장합니다.-```--### 리소스 라이브러리--- [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- 에이전트 세션 수명 주기- ======================-- ┌──────────────────────────────────────────────────────────────────┐- │ 시작 │- │ │- │ 1. 에이전트가 AGENTS.md / CLAUDE.md를 읽음 │- │ 2. 에이전트가 init.sh를 실행 (설치, 검증, 상태 확인) │- │ 3. 에이전트가 claude-progress.md를 읽음 (이전 세션 기록) │- │ 4. 에이전트가 feature_list.json을 읽음 (완료된 항목, 다음 항목) │- │ 5. 에이전트가 git log를 확인 (최근 변경 사항) │- │ │- │ 선택 │- │ │- │ 6. 에이전트가 정확히 하나의 미완료 기능을 선택 │- │ 7. 에이전트가 해당 기능에만 작업 │- │ │- │ 실행 │- │ │- │ 8. 에이전트가 기능을 구현 │- │ 9. 에이전트가 검증을 실행 (테스트, 린트, 타입 검사) │- │ 10. 검증 실패 시: 수정 후 재실행 │- │ 11. 검증 통과 시: 증거를 기록 │- │ │- │ 마무리 │- │ │- │ 12. 에이전트가 claude-progress.md를 업데이트 │- │ 13. 에이전트가 feature_list.json을 업데이트 │- │ 14. 에이전트가 여전히 망가져 있거나 미검증된 항목을 기록 │- │ 15. 에이전트가 커밋 (안전하게 재개 가능할 때만) │- │ 16. 에이전트가 다음 세션을 위한 깔끔한 재시작 경로를 남김 │- │ │- └──────────────────────────────────────────────────────────────────┘-- 하니스가 이 수명 주기의 모든 전환을 제어합니다.- 모델은 각 단계에서 어떤 코드를 작성할지 결정합니다.- 하니스가 없으면 9단계는 "에이전트가 괜찮아 보인다고 말함"이 됩니다.- 하니스가 있으면 9단계는 "테스트 통과, 린트 깔끔함, 타입 검사 통과"가 됩니다.-```-------## 이 강좌의 대상--이 강좌는 다음 분들을 위한 것입니다:--- 이미 코딩 에이전트를 사용 중이며 더 나은 안정성과 품질을 원하는 엔지니어-- 하니스 설계에 대한 체계적인 이해를 원하는 연구자 또는 빌더-- 환경 설계가 에이전트 성능에 미치는 영향을 이해해야 하는 기술 리더--이 강좌는 다음 분들에게 적합하지 않습니다:--- 코드 없는 AI 입문을 찾는 분-- 프롬프트에만 관심이 있고 실제 구현을 계획하지 않는 분-- 에이전트가 실제 저장소 내에서 작업하도록 할 준비가 되지 않은 학습자-------## 요구 사항--이 강좌는 실제로 코딩 에이전트를 실행하는 강좌입니다.--다음 도구 중 최소 하나가 필요합니다:--- Claude Code-- Codex-- 파일 편집, 명령 실행, 다단계 작업을 지원하는 다른 IDE 또는 CLI 코딩 에이전트--이 강좌는 다음이 가능하다고 가정합니다:--- 로컬 저장소 열기-- 에이전트가 파일을 편집하도록 허용-- 에이전트가 명령을 실행하도록 허용-- 출력을 검사하고 작업을 재실행--해당 도구가 없는 경우에도 강좌 내용을 읽을 수 있지만, 의도된 대로 프로젝트를 완료할 수는 없습니다.-------## 로컬 미리보기--이 저장소는 문서 뷰어로 VitePress를 사용합니다.--```sh-npm install-npm run docs:dev # 핫 리로드가 포함된 개발 서버-npm run docs:build # 프로덕션 빌드-npm run docs:preview # 빌드된 사이트 미리보기-```--그런 다음 브라우저에서 VitePress가 출력하는 로컬 URL을 여세요.-------## 사전 요구 사항--필수:--- 터미널, git, 로컬 개발 환경에 대한 친숙도-- 최소 하나의 일반적인 애플리케이션 스택에서 코드 읽기 및 쓰기 능력-- 기본적인 소프트웨어 디버깅 경험 (로그, 테스트, 런타임 동작 읽기)-- 구현 중심의 강좌 작업에 투자할 충분한 시간--도움이 되지만 필수는 아님:--- Electron, 데스크톱 앱 또는 로컬 우선 도구에 대한 경험-- 테스팅, 로깅 또는 소프트웨어 아키텍처에 대한 배경지식-- Codex, Claude Code 또는 유사한 코딩 에이전트에 대한 사전 경험-------## 핵심 참고 자료--주요 자료:--- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)-- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)-- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)-- [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**: 기본 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-RU.md b/README-RU.mddeleted file mode 100644index 52c0176..0000000--- a/README-RU.md+++ /dev/null@@ -1,595 +0,0 @@-<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>- <a href="./README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?style=flat-square"></a>-</p>--# Learn Harness Engineering--> **Проектный курс о построении окружений, управлении состоянием, верификации и механизмах контроля, которые делают KI-Coding-агентов надёжными.**--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)--> **Быстрый старт?** Skill [`skills/harness-creator/`](../../skills/) поможет вам за считанные минуты создать готовое к продакшену harness (AGENTS.md, feature-списки, init.sh, верификационные workflow) для вашего собственного проекта.-------## Содержание--- [Визуальная подборка](#визуальная-подборка)-- [Модель умна, harness делает её надёжной](#модель-умна-harness-делает-её-надёжной)-- [Быстрый старт: улучшите своего агента уже сегодня](#быстрый-старт-улучшите-своего-агента-уже-сегодня)-- [Итоговый проект: настоящее приложение](#итоговый-проект-настоящее-приложение)-- [Путь обучения](#путь-обучения)-- [Учебная программа](#учебная-программа)-- [Skills](#skills)-- [Другие курсы](#другие-курсы)-------## Визуальная подборка--### Главная страница курса-> Обзор курса и введение в ключевые философии, формирующие чёткий путь для старта.----### Иммерсивные лекции-> Глубокое погружение в реальные проблемы и практические проекты (например, Проект 01) для иммерсивного обучения.----### Библиотека шаблонов-> Шаблоны и эталонные конфигурации, созданные для решения распространённых проблем при разработке многоходовых KI-агентов, таких как потеря контекста и преждевременное завершение задач.----## PDF-учебники курса--Репозиторий теперь содержит pipeline для генерации PDF-версий учебных материалов.--- Запустите `npm run pdf:build`, чтобы сгенерировать PDF на английском и китайском языках локально.-- Готовые файлы помещаются в `artifacts/pdfs/`.-- Запустите `npm run screenshots:readme`, если хотите обновить скриншоты для README.-- GitHub Actions workflow [`release-course-pdfs.yml`](../../.github/workflows/release-course-pdfs.yml) может создать PDF и опубликовать их в GitHub Releases.-------## Модель умна, harness делает её надёжной--Существует суровая правда, которую большинство людей познаёт на собственном опыте: **самая мощная модель в мире всё равно провалит реальную инженерную задачу, если вы не построите для неё подходящее окружение.**--Вы, вероятно, сталкивались с этим сами. Вы даёте Claude или GPT задачу в своём репозитории. Всё начинается хорошо — агент читает файлы, пишет код, выглядит продуктивно. Затем что-то идёт не так. Он пропускает шаг. Ломает тест. Говорит «готово", но на самом деле ничего не работает. Вы тратите больше времени на исправление, чем если бы сделали всё сами.--Это не проблема модели. Это проблема harness.--Доказательства однозначны. Anthropic провёл контролируемый эксперимент: та же модель (Opus 4.5), тот же промпт («постройте 2D-ретро-игровой редактор"). Без harness агент потратил 9 $ за 20 минут и создал что-то неработающее. С полным harness (планировщик + генератор + оценщик) он потратил 200 $ за 6 часов и создал игру, в которую можно реально играть. Модель не изменилась. Изменился harness.--OpenAI сообщает то же самое с Codex: в хорошо подготовленном репозитории та же модель переходит от «ненадёжной" к «надёжной". Не маргинальное улучшение — качественный скачок.--**Этот курс научит вас, как построить такое окружение.**--```text- ПАТТЕРН HARNESS- ================-- Вы --> даёте задачу --> Агент читает файлы harness --> Агент выполняет- |- harness управляет каждым шагом:- |- +--> Инструкции: что делать, в каком порядке- +--> Область: одна фича за раз, без превышения- +--> Состояние: лог прогресса, список фич, история git- +--> Верификация: тесты, линт, проверка типов, smoke-запуски- +--> Жизненный инициализация при старте, чистое- цикл: состояние в конце- |- v- Агент останавливается- только когда верификация пройдена-```-------## Что на самом деле означает Harness Engineering--Harness Engineering — это построение полноценной рабочей среды вокруг модели, чтобы она давала надёжные результаты. Речь не о том, чтобы писать лучшие промпты. Речь о проектировании системы, в которой модель работает.--Harness состоит из пяти подсистем:--```text- ┌─────────────────────────────────────────────────────────────────┐- │ HARNESS │- │ │- │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │- │ │ Инструкции │ │ Состояние │ │ Верификация │ │- │ │ │ │ │ │ │ │- │ │ AGENTS.md │ │ progress.md │ │ тесты + линт │ │- │ │ CLAUDE.md │ │ feature_list │ │ проверка типов │ │- │ │ feature_list │ │ git log │ │ smoke-запуски │ │- │ │ docs/ │ │ передача │ │ e2e pipeline │ │- │ │ │ │ сессии │ │ │ │- │ └──────────────┘ └──────────────┘ └──────────────────────┘ │- │ │- │ ┌──────────────┐ ┌──────────────────────────────────────┐ │- │ │ Область │ │ Жизненный цикл сессии │ │- │ │ │ │ │ │- │ │ одна фича │ │ init.sh при старте │ │- │ │ за раз │ │ чек-лист чистого состояния в конце │ │- │ │ определение │ │ заметка-передача для след. сессии │ │- │ │ «готово» │ │ коммит только когда безопасно │ │- │ │ │ │ для возобновления │ │- │ └──────────────┘ └──────────────────────────────────────┘ │- │ │- └─────────────────────────────────────────────────────────────────┘-- МОДЕЛЬ решает, какой код писать.- HARNESS управляет тем, когда, где и как она его пишет.- Harness не делает модель умнее.- Он делает вывод модели надёжным.-```--Каждая подсистема выполняет свою задачу:--- **Instructions** — указывают агенту, что делать, в каком порядке и что прочитать перед началом. Не один гигантский файл, а структура прогрессивного раскрытия, по которой агент навигирует по мере необходимости.-- **State** — отслеживает, что сделано, что в работе и что предстоит дальше. Сохраняется на диске, чтобы следующая сессия продолжала точно с того места, где остановилась предыдущая.-- **Verification** — только существующий набор тестов считается доказательством. Агент не может сообщить об успехе без исполняемого подтверждения.-- **Scope** — ограничивает агента одной фичей за раз. Никаких превышений полномочий. Никакого полуготового завершения трёх вещей. Никакой переписки feature-списка, чтобы скрыть незавершённую работу.-- **Session Lifecycle** — инициализация в начале. Очистка в конце. Оставление чистого пути перезапуска для следующей сессии.-------## Почему существует этот курс--Вопрос не в том, «могут ли модели писать код?" Могут. Вопрос в том: **могут ли они надёжно выполнять реальные инженерные задачи в реальных репозиториях на протяжении нескольких сессий без постоянного человеческого контроля?**--На данный момент ответ: нет без harness.--```text- БЕЗ HARNESS С HARNESS- ========== =========-- Сессия 1: агент пишет код Сессия 1: агент читает инструкции- агент ломает тесты агент запускает init.sh- агент говорит «готово» агент работает над одной фичей- вы исправляете вручную агент верифицирует перед тем- как сообщить о готовности- агент обновляет лог прогресса-- Сессия 2: агент начинает с чистого агент фиксирует чистое состояние- листа- у агента нет памяти Сессия 2: агент читает лог прогресса- о том, что было раньше агент продолжает точно с того места- агент переделывает работу где остановился- или делает что-то совсем другое агент продолжает незавершённую фичу- вы исправляете снова вы проверяете, а не спасаете-- Результат: вы тратите больше Результат: агент делает работу,- времени на исправления, вы проверяете результат- чем если бы сделали сами-```--Вопросы, которые действительно волнуют этот курс:--- Какие дизайны harness повышают процент завершения задач?-- Какие дизайны сокращают переделки и ложные завершения?-- Какие механизмы поддерживают продвижение длительных задач?-- Какие структуры сохраняют поддерживаемость системы после множества запусков агента?-------## Учебная программа и документация--Полные материалы курса доступны на **[сайте документации](https://walkinglabs.github.io/learn-harness-engineering/)**.--Программа разделена на три части:--1. **Лекции**: 12 концептуальных блоков, объясняющих теорию Harness Engineering.-2. **Проекты**: 6 практических проектов, в которых вы строите агентскую рабочую среду с нуля.-3. **Библиотека шаблонов**: готовые к копированию шаблоны (`AGENTS.md`, `feature_list.json`, `init.sh` и др.), которые вы можете использовать в своих репозиториях уже сегодня.-------## Быстрый старт: улучшите своего агента уже сегодня--Вам не нужно читать все 12 лекций, чтобы получить пользу. Если вы уже используете coding-агента в реальном проекте, вы можете улучшить его прямо сейчас.--Идея проста: вместо того чтобы писать только промпты, дайте своему агенту набор структурированных файлов, определяющих, что нужно сделать, что уже сделано и как проверить результат. Эти файлы находятся в вашем репозитории, поэтому каждая сессия стартует из одного и того же состояния.--```text- КОРНЕВАЯ ПАПКА ВАШЕГО ПРОЕКТА- ├── AGENTS.md <-- операционное руководство агента- ├── CLAUDE.md <-- (альтернатива, если вы используете Claude Code)- ├── init.sh <-- выполняет установку + верификацию + запуск- ├── feature_list.json <-- какие фичи существуют, какие выполнены- ├── claude-progress.md <-- что произошло в каждой сессии- └── src/ <-- ваш фактический код-```--Скачайте стартовые шаблоны из [библиотеки шаблонов](https://walkinglabs.github.io/learn-harness-engineering/ru/resources/) и добавьте их в свой проект. Вот и всё. Четыре файла — и ваши агентские сессии уже станут значительно стабильнее, чем с одними промптами.-------## Итоговый проект: настоящее приложение--Все шесть проектов курса вращаются вокруг одного продукта: **десктопного приложения для персонального управления знаниями на базе Electron.**--```text- ┌─────────────────────────────────────────────────────┐- │ Десктоп-приложение «База знаний» │- │ │- │ ┌──────────────┐ ┌──────────────────────────────┐│- │ │ Список │ │ Панель вопросов ││- │ │ документов │ │ и ответов ││- │ │ │ │ ││- │ │ doc-001.md │ │ В: Что такое harness eng? ││- │ │ doc-002.md │ │ О: Окружение, построенное ││- │ │ doc-003.md │ │ вокруг агентной модели...││- │ │ ... │ │ [источник: doc-002.md] ││- │ └──────────────┘ └──────────────────────────────┘│- │ │- │ ┌─────────────────────────────────────────────────┐│- │ │ Строка состояния: 42 док. | 38 индекс. | синхр. ││- │ │ 3 мин. назад ││- │ └─────────────────────────────────────────────────┘│- └─────────────────────────────────────────────────────┘-- Основные возможности:- ├── Импорт локальных документов- ├── Управление библиотекой документов- ├── Обработка и индексирование документов- ├── AI-вопросы и ответы по импортированному контенту- └── Обоснованные ответы с источниками-```--Этот проект выбран потому, что он сочетает высокую практическую пользу, достаточную реальную продуктовую сложность и хороший сценарий для наблюдения улучшений harness (до/после).--Каждый курсовой проект (starter/solution) — это полная копия этого Electron-приложения на соответствующей стадии развития. Starter для P(N+1) получается из solution для P(N) — приложение эволюционирует вместе с ростом ваших навыков harness.-------## Путь обучения--Курс рассчитан на последовательное прохождение. Каждая фаза строится на предыдущей.--```text- Фаза 1: УВИДЕТЬ ПРОБЛЕМУ Фаза 2: СТРУКТУРИРОВАТЬ РЕПОЗИТОРИЙ- ========================== ===================================-- L01 Сильные модели ≠ надёжное L03 Репозиторий как единственный- выполнение источник истины- L02 Что на самом деле означает- harness L04 Разнести инструкции по файлам,- а не один гигантский файл- |- v |- P01 Только промпт vs. v- подход на основе правил P02 Агентно-читаемое рабочее- пространство--- Фаза 3: СВЯЗАТЬ СЕССИИ Фаза 4: ОБРАТНАЯ СВЯЗЬ И ОБЛАСТЬ- ========================= ================================-- L05 Сохранять контекст живым L07 Чёткие границы задач- между сессиями- L08 Списки фич как примитивы- L06 Инициализация перед каждой harness- сессией агента- |- | v- v P04 Runtime-обратная связь- P03 Мультисессионная связность для корректировки поведения--- Фаза 5: ВЕРИФИКАЦИЯ Фаза 6: СОБРАТЬ ВСЁ ВМЕСТЕ- =================== ==========================-- L09 Остановить агентов от L11 Сделать runtime агента- преждевременного объявления наблюдаемым- победы- L12 Чистая передача в конце- L10 Полный прогон pipeline = каждой сессии- настоящая верификация-- | |- v v- P05 Агент верифицирует P06 Построить полный harness- собственную работу (итоговый проект)-```--Каждая фаза занимает примерно неделю при обучении параллельно с основной работой. Если двигаться быстрее, фазы 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"? | Пять подсистем: Instructions, State, Verification, Scope, Lifecycle |-| [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) | Почему feature-списки — это примитивы harness? | Машинно-читаемые границы scope, которые агент не может проигнорировать |-| [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) | Почему end-to-end-тестирование меняет результаты? | Только полный прогон pipeline считается настоящей верификацией |-| [L11](../../docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Почему observability должна быть внутри 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) | Не дать агенту сделать слишком много или слишком мало | Runtime-обратная связь + контроль scope + инкрементальное индексирование |-| [P05](../../docs/projects/project-05-grounded-qa-verification/index.md) | Заставить агента верифицировать собственную работу | Самоверификация + обоснованный Q&A + завершение на основе свидетельств |-| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | Построить полный harness с нуля (итоговый проект) | Полный harness: все механизмы + observability + абляционное исследование |--```text- ЭВОЛЮЦИЯ ПРОЕКТОВ- =================-- P01 Только промпт vs. подход Вы видите проблему- на основе правил- |- v- P02 Агентно-читаемое рабочее Вы реструктурируете репозиторий- пространство- |- v- P03 Мультисессионная связность Вы связываете сессии- |- v- P04 Runtime-обратная связь и Вы добавляете циклы обратной- область связи- |- v- P05 Самоверификация Вы заставляете агента проверять- самого себя- |- v- P06 Полный harness (итоговый) Вы строите полную систему-- Solution каждого проекта становится starter'ом следующего.- Приложение эволюционирует. Ваши навыки harness растут вместе с ним.-```--### Библиотека шаблонов--- [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- ЖИЗНЕННЫЙ ЦИКЛ СЕССИИ АГЕНТА- =============================-- ┌──────────────────────────────────────────────────────────────────┐- │ СТАРТ │- │ │- │ 1. Агент читает AGENTS.md / CLAUDE.md │- │ 2. Агент запускает init.sh (установка, верификация, проверка) │- │ 3. Агент читает claude-progress.md (что было в прошлый раз) │- │ 4. Агент читает feature_list.json (что готово, что дальше) │- │ 5. Агент проверяет git log (недавние изменения) │- │ │- │ ВЫБОР │- │ │- │ 6. Агент выбирает ровно ОДНУ незавершённую фичу │- │ 7. Агент работает только над этой фичей │- │ │- │ ВЫПОЛНЕНИЕ │- │ │- │ 8. Агент реализует фичу │- │ 9. Агент запускает верификацию (тесты, линт, проверка типов) │- │ 10. Если верификация не прошла: исправить и запустить снова │- │ 11. Если верификация прошла: зафиксировать результат │- │ │- │ ЗАВЕРШЕНИЕ │- │ │- │ 12. Агент обновляет claude-progress.md │- │ 13. Агент обновляет feature_list.json │- │ 14. Агент записывает, что всё ещё сломано или не верифицировано│- │ 15. Агент делает коммит (только когда безопасно возобновлять) │- │ 16. Агент оставляет чистый путь перезапуска для след. сессии │- │ │- └──────────────────────────────────────────────────────────────────┘-- Harness управляет каждым переходом в этом жизненном цикле.- Модель решает, какой код писать на каждом шаге.- Без harness шаг 9 превращается в «агент говорит, что всё выглядит нормально».- С harness шаг 9 — это «тесты пройдены, линт чист, типы в порядке».-```-------## Для кого этот курс--Этот курс предназначен для:--- Разработчиков, уже использующих coding-агентов и желающих большей стабильности и качества-- Исследователей и разработчиков, стремящихся получить систематическое понимание дизайна harness-- Технических лидеров, желающих понять, как дизайн окружения влияет на производительность агентов--Этот курс НЕ предназначен для:--- Тех, кто ищет введение в KI без программирования-- Тех, кому интересны только промпты без планов реальной реализации-- Обучающихся, не готовых доверить агентам работу в реальных репозиториях-------## Необходимые инструменты--Это курс, в котором вы реально запускаете coding-агентов.--Вам понадобится как минимум один из следующих инструментов:--- Claude Code-- Codex-- Другой IDE- или CLI-coding-агент с поддержкой редактирования файлов, выполнения команд и многошаговых задач--Курс предполагает, что вы умеете:--- Открыть локальный репозиторий-- Разрешить агенту редактировать файлы-- Разрешить агенту выполнять команды-- Проверять вывод и перезапускать задачи--Если у вас нет такого инструмента, вы сможете читать материалы курса, но не сможете выполнить проекты так, как задумано.-------## Локальный предпросмотр--Этот репозиторий использует VitePress в качестве системы документации.--```sh-npm install-npm run docs:dev # Dev-сервер с горячей перезагрузкой-npm run docs:build # Продакшен-сборка-npm run docs:preview # Предпросмотр собранного сайта-```--Затем откройте локальный URL, который выведет VitePress, в вашем браузере.-------## Предварительные знания--Обязательные:--- Знакомство с терминалом, Git и локальными средами разработки-- Умение читать и писать код хотя бы на одном распространённом стеке-- Базовый опыт отладки ПО (чтение логов, тестов и анализ runtime-поведения)-- Достаточно времени для выполнения практических заданий курса--Полезные, но не обязательные:--- Опыт работы с Electron, десктопными приложениями или local-first-инструментами-- Основы в области тестирования, логирования или программной архитектуры-- Предыдущий опыт работы с Codex, Claude Code или аналогичными coding-агентами-------## Основные источники--Первичные:--- [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/ # Переиспользуемые skills для KI-агентов-│ └── harness-creator/ # Skill для Harness Engineering-├── package.json # VitePress + инструменты разработки-└── CLAUDE.md # Инструкции Claude Code для этого репозитория-```-------## Организация курса--- Каждая лекция сфокусирована на одном вопросе-- Курс включает 6 проектов-- Каждый проект требует, чтобы агент выполнял реальную работу-- Каждый проект сравнивает результаты слабого и сильного harness-- Важен измеримый результат, а не количество написанных документов-------## Skills--Этот репозиторий также содержит переиспользуемые skills для KI-агентов, которые можно установить прямо в вашу IDE или агентское рабочее пространство.--- [**harness-creator**](../../skills/harness-creator/): Skill, помогающий за считанные минуты создать готовое к продакшену harness для вашего собственного проекта.-------## Другие курсы--Наша команда также создала другие курсы! Ознакомьтесь с ними:--[](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-TR.md b/README-TR.mddeleted file mode 100644index 370ea48..0000000--- a/README-TR.md+++ /dev/null@@ -1,590 +0,0 @@-<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-ZH.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>- <a href="./README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?style=flat-square"></a>-</p>--<h1 align="center">Learn Harness Engineering</h1>--<p align="center"><strong>Yapay zeka kod yazma ajanlarının güvenilir biçimde çalışmasını sağlayan ortamı, durum yönetimini, doğrulamayı ve kontrol mekanizmalarını kurmaya odaklanan, proje tabanlı bir kurs.</strong></p>--<p align="center">- <img src="https://img.shields.io/badge/Lectures-12-blue?style=flat-square" alt="12 Ders">- <img src="https://img.shields.io/badge/Projects-6-green?style=flat-square" alt="6 Proje">- <img src="https://img.shields.io/badge/Languages-13-yellow?style=flat-square" alt="13 Dil">- <img src="https://img.shields.io/badge/License-MIT-lightgrey?style=flat-square" alt="MIT Lisansı">-</p>--> **Globe icon** Bu kurs **13 dilde** mevcuttur: English, 简体中文, 繁體中文, 日本語, 한국어, Español, Français, Русский, Deutsch, العربية, Tiếng Việt, Oʻzbekcha, Türkçe. Dilinizi yukarıdaki rozetlerden seçin.--Learn Harness Engineering, yapay zeka kod yazma ajanlarının mühendisliğine adanmış bir kurstur. Sektördeki en gelişmiş Harness Engineering teorilerini ve uygulamalarını derinlemesine inceleyip sentezledik. Temel referanslarımız:--- [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)--> **Hızlı başlangıç mı?** [`skills/harness-creator/`](./skills/) skill'i, kendi projeniz için üretim kalitesinde bir harness (AGENTS.md, özellik listeleri, init.sh, doğrulama iş akışları) iskeletini dakikalar içinde oluşturmanıza yardımcı olabilir.-------## İçindekiler--- [✨ Görsel önizleme](#-görsel-önizleme)-- [Harness engineering aslında ne demek](#harness-engineering-aslında-ne-demek)-- [Hızlı başlangıç: Ajanınızı bugün geliştirin](#hızlı-başlangıç-ajanınızı-bugün-geliştirin)-- [Bitirme projesi: Gerçek bir uygulama](#bitirme-projesi-gerçek-bir-uygulama)-- [Öğrenme yolu](#öğrenme-yolu)-- [Müfredat](#müfredat)-- [Skills](#skills)-- [Diğer kurslar](#diğer-kurslar)-------## ✨ Görsel önizleme--### 🏠 Kurs ana sayfası-> Başlamak için net bir yol sunan kapsamlı bir kurs özeti ve temel felsefelere giriş.----### 📖 Sürükleyici dersler-> Sürükleyici bir öğrenme deneyimi için gerçek dünya sorunlarına ve uygulamalı projelere (Proje 01 gibi) derinlemesine inişler.----### 🗂️ Kullanıma hazır Kaynak Kütüphanesi-> Çok adımlı yapay zeka ajanı geliştirmedeki bağlam kaybı ve görevin erken tamamlandığının ilan edilmesi gibi yaygın tuzakları çözmek için tasarlanmış şablonlar ve referans yapılandırmalar.----## PDF Ders Kitapları--Depo artık kurs içeriği için bir PDF üretim hattı içermektedir.--- Şu anda yapılandırılmış PDF ders kitaplarını yerel olarak oluşturmak için `npm run pdf:build` komutunu çalıştırın.-- Çıktı dosyaları `artifacts/pdfs/` dizinine yazılır.-- README önizleme görsellerini yenilemek istiyorsanız `npm run screenshots:readme` komutunu çalıştırın.-- [`release-course-pdfs.yml`](./.github/workflows/release-course-pdfs.yml) GitHub Actions iş akışı PDF'leri oluşturup GitHub Releases'a yayınlayabilir.-------## Model akıllıdır, harness onu güvenilir kılar--Çoğu insanın zor yoldan öğrendiği acı bir gerçek var: **Dünyanın en güçlü modeli bile, etrafına uygun bir ortam kurmazsanız gerçek mühendislik görevlerinde başarısız olacaktır.**--Muhtemelen bunu kendiniz de yaşamışsınızdır. Claude veya GPT'ye deponuzda bir görev verirsiniz. İyi başlar — dosyaları okur, kod yazar, üretken görünür. Sonra bir şeyler ters gider. Bir adımı atlar. Bir testi bozar. "Tamamlandı" der ama hiçbir şey gerçekten çalışmaz. Kendiniz yapsanız harcayacağınızdan daha fazla zamanı temizlik yaparak harcarsınız.--Bu bir model sorunu değildir. Bir harness sorunudur.--Kanıtlar açık. Anthropic kontrollü bir deney yürüttü: aynı model (Opus 4.5), aynı prompt ("bir 2D retro oyun editörü oluştur"). Harness olmadan 20 dakikada 9 $ harcadı ve çalışmayan bir şey üretti. Tam bir harness ile (planlayıcı + üretici + değerlendirici) 6 saatte 200 $ harcadı ve gerçekten oynayabileceğiniz bir oyun yaptı. Model değişmedi. Harness değişti.--OpenAI Codex ile aynı şeyi bildirdi: iyi harness'lanmış bir depoda aynı model "güvenilmez"den "güvenilir"e geçer. Marjinal bir iyileşme değil — niteliksel bir sıçrama.--**Bu kurs size o ortamı nasıl kuracağınızı öğretir.**--```text- HARNESS DESENİ- ==============-- Siz --> görev verirsiniz --> Ajan harness dosyalarını okur --> Ajan yürütür- |- harness her adımı yönetir:- |- +--> Talimatlar: ne yapılacak, hangi sırada- +--> Kapsam: bir seferde tek özellik, sınırı aşma yok- +--> Durum: ilerleme günlüğü, özellik listesi, git geçmişi- +--> Doğrulama: testler, lint, tip kontrolü, smoke koşuları- +--> Yaşam döngüsü: başta init, sonda temiz durum- |- v- Ajan yalnızca doğrulama- başarılı olduğunda durur-```-------## Harness engineering aslında ne demek--Harness engineering, modelin güvenilir sonuçlar üretmesi için etrafına eksiksiz bir çalışma ortamı kurmakla ilgilidir. Daha iyi prompt yazmakla ilgili değildir. Modelin içinde çalıştığı sistemi tasarlamakla ilgilidir.--Bir harness'ın beş alt sistemi vardır:--```text- ┌─────────────────────────────────────────────────────────────────┐- │ HARNESS │- │ │- │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │- │ │ Talimatlar │ │ Durum │ │ Doğrulama │ │- │ │ │ │ │ │ │ │- │ │ AGENTS.md │ │ progress.md │ │ testler + lint │ │- │ │ CLAUDE.md │ │ feature_list │ │ tip kontrolü │ │- │ │ feature_list │ │ git log │ │ smoke koşuları │ │- │ │ docs/ │ │ oturum devri │ │ e2e hattı │ │- │ └──────────────┘ └──────────────┘ └──────────────────────┘ │- │ │- │ ┌──────────────┐ ┌──────────────────────────────────────┐ │- │ │ Kapsam │ │ Oturum yaşam döngüsü │ │- │ │ │ │ │ │- │ │ bir seferde │ │ başta init.sh │ │- │ │ tek özellik │ │ sonda temiz-durum listesi │ │- │ │ bitti │ │ sonraki oturum için devir notu │ │- │ │ tanımı │ │ yalnızca sürdürmek güvenli ise commit│ │- │ └──────────────┘ └──────────────────────────────────────┘ │- │ │- └─────────────────────────────────────────────────────────────────┘-- MODEL hangi kodun yazılacağına karar verir.- HARNESS ne zaman, nerede ve nasıl yazıldığını yönetir.- Harness modeli daha akıllı yapmaz.- Modelin çıktısını güvenilir yapar.-```--Her alt sistemin bir görevi vardır:--- **Talimatlar (Instructions)** — Ajana ne yapacağını, hangi sırada yapacağını ve başlamadan önce ne okuyacağını söyler. Tek bir dev dosya değil; ajanın ihtiyaca göre gezdiği aşamalı bir açılım yapısı.-- **Durum (State)** — Yapılanı, devam edeni ve sıradakini takip eder. Diske kalıcı olarak yazılır, böylece sonraki oturum tam olarak öncekinin bıraktığı yerden devam eder.-- **Doğrulama (Verification)** — Yalnızca geçen bir test paketi kanıt sayılır. Ajan, çalıştırılabilir kanıt olmadan zafer ilan edemez.-- **Kapsam (Scope)** — Ajanı bir seferde tek bir özelliğe sınırlar. Sınırı aşma yok. Üç şeyi yarım bırakma yok. Yarım kalan işi gizlemek için özellik listesini yeniden yazma yok.-- **Oturum yaşam döngüsü (Session Lifecycle)** — Başta başlat. Sonda temizle. Sonraki oturum için temiz bir yeniden başlatma yolu bırak.-------## Bu kurs neden var--Soru "modeller kod yazabilir mi?" değil. Yazabilirler. Soru şu: **Gerçek depolarda, birden fazla oturum boyunca, sürekli insan denetimi olmadan gerçek mühendislik görevlerini güvenilir biçimde tamamlayabilirler mi?**--Şu an için cevap: bir harness olmadan, hayır.--```text- HARNESS OLMADAN HARNESS İLE- =============== ===========-- Oturum 1: ajan kod yazar Oturum 1: ajan talimatları okur- ajan testleri bozar ajan init.sh çalıştırır- ajan "tamam" der ajan tek bir özellik üzerinde çalışır- siz elle düzeltirsiniz ajan "tamam" demeden önce doğrular- ajan ilerleme günlüğünü günceller- Oturum 2: ajan sıfırdan başlar ajan temiz durumu commit'ler- ajanın daha önce ne- olduğuna dair belleği yok Oturum 2: ajan ilerleme günlüğünü okur- ajan işi tekrar yapar ajan tam bıraktığı yerden devam eder- ya da tamamen başka bir şey yapar ajan yarım kalan özelliği sürdürür- siz yine düzeltirsiniz siz inceler, kurtarmazsınız-- Sonuç: kendiniz yapsanız harcayacağınızdan Sonuç: ajan işi yapar,- daha fazla zamanı temizlik siz sonucu doğrularsınız- yaparak harcarsınız-```--Bu kursun gerçekten önemsediği sorular:--- Hangi harness tasarımları görev tamamlama oranlarını artırır?-- Hangi tasarımlar yeniden yapım ve hatalı tamamlamaları azaltır?-- Hangi mekanizmalar uzun süren görevlerin istikrarlı ilerlemesini sağlar?-- Hangi yapılar sistemi birden fazla ajan koşusundan sonra bakım yapılabilir tutar?-------## Kurs Müfredatı ve Dokümantasyon--Tüm kurs materyalleri için lütfen **[Dokümantasyon Sitesi](https://walkinglabs.github.io/learn-harness-engineering/)**'ni ziyaret edin.--Müfredat üç bölüme ayrılmıştır:--1. **Dersler**: Harness engineering'in arkasındaki teoriyi açıklayan 12 kavramsal birim.-2. **Projeler**: Ajansal bir çalışma alanını sıfırdan inşa ettiğiniz 6 uygulamalı proje.-3. **Kaynak Kütüphanesi**: Kendi depolarınızda bugün kullanabileceğiniz kopya-yapıştır şablonlar (`AGENTS.md`, `feature_list.json`, `init.sh` vb.).-------## Hızlı başlangıç: Ajanınızı bugün geliştirin--Değer elde etmeye başlamadan önce 12 dersin tamamını okumanıza gerek yok. Gerçek bir projede zaten bir kod yazma ajanı kullanıyorsanız, onu şu anda nasıl iyileştirebileceğiniz aşağıda.--Fikir basit: yalnızca prompt yazmak yerine, ajanınıza ne yapacağını, ne yapıldığını ve işin nasıl doğrulanacağını tanımlayan bir dizi yapılandırılmış dosya verin. Bu dosyalar deponuzun içinde yaşar, böylece her oturum aynı durumdan başlar.--```text- PROJENİZİN KÖK DİZİNİ- ├── AGENTS.md <-- ajanın çalıştırma kılavuzu- ├── CLAUDE.md <-- (Claude Code kullanıyorsanız alternatif)- ├── init.sh <-- install + verify + start çalıştırır- ├── feature_list.json <-- hangi özellikler var, hangileri bitti- ├── claude-progress.md <-- her oturumda ne oldu- └── src/ <-- gerçek kodunuz-```--Başlangıç şablonlarını [Kaynak Kütüphanesi](https://walkinglabs.github.io/learn-harness-engineering/en/resources/)'nden alıp projenize bırakın. Hepsi bu. Dört dosya ve ajan oturumlarınız yalnızca prompt'larla çalıştırmaya kıyasla zaten belirgin şekilde daha kararlı olacak.-------## Bitirme projesi: Gerçek bir uygulama--Altı kurs projesinin tamamı aynı ürün etrafında döner: **Electron tabanlı kişisel bir bilgi tabanı masaüstü uygulaması**.--```text- ┌─────────────────────────────────────────────────────┐- │ Bilgi Tabanı Masaüstü Uygulaması │- │ │- │ ┌──────────────┐ ┌──────────────────────────────┐│- │ │ Belge Listesi│ │ Soru-Cevap Paneli ││- │ │ │ │ ││- │ │ doc-001.md │ │ S: Harness eng. nedir? ││- │ │ doc-002.md │ │ C: Bir ajan modelinin ││- │ │ doc-003.md │ │ etrafında kurulan... ││- │ │ ... │ │ [kaynak: doc-002.md] ││- │ └──────────────┘ └──────────────────────────────┘│- │ │- │ ┌─────────────────────────────────────────────────┐│- │ │ Durum Çubuğu: 42 belge | 38 indekslendi | son sync 3d ││- │ └─────────────────────────────────────────────────┘│- └─────────────────────────────────────────────────────┘-- Temel özellikler:- ├── Yerel belgeleri içe aktarma- ├── Bir belge kütüphanesi yönetme- ├── Belgeleri işleme ve dizinleme- ├── İçe aktarılan içerik üzerinde yapay zeka destekli Soru-Cevap çalıştırma- └── Kaynak gösterimleri ile dayanaklı yanıtlar döndürme-```--Bu proje, güçlü pratik değer, yeterli gerçek dünya ürün karmaşıklığı ve harness iyileştirmelerinin öncesi/sonrası gözlemlemek için iyi bir ortamı bir araya getirdiği için seçildi.--Her kurs projesinin starter/solution'ı, bu Electron uygulamasının o evrimsel aşamadaki eksiksiz bir kopyasıdır. P(N+1)'in starter'ı P(N)'in solution'ından türetilir — uygulama, harness yetenekleriniz geliştikçe evrilir.-------## Öğrenme yolu--Kurs sırayla yapılacak şekilde tasarlanmıştır. Her aşama bir öncekinin üzerine inşa edilir.--```text- Aşama 1: PROBLEMİ GÖR Aşama 2: DEPOYU YAPILANDIR- ===================== ===========================-- L01 Güçlü modeller ≠ güvenilir L03 Tek kayıt sistemi- yürütme olarak depo- L02 Harness aslında ne demek- L04 Talimatları tek bir dev dosya- | yerine birden fazla dosyaya böl- v- P01 Yalnızca prompt vs. |- önce kurallar karşılaştırması v- P02 Ajanın okuyabildiği çalışma alanı--- Aşama 3: OTURUMLARI BAĞLA Aşama 4: GERİ BİLDİRİM VE KAPSAM- ========================== =================================-- L05 Bağlamı oturumlar L07 Net görev sınırları çiz- arasında canlı tut- L08 Özellik listeleri harness- L06 Her ajan oturumundan yapı taşı olarak- önce başlat- |- | v- v P04 Ajan davranışını düzeltmek için- P03 Çok oturumlu süreklilik runtime geri bildirimi--- Aşama 5: DOĞRULAMA Aşama 6: HEPSİNİ BİR ARAYA GETİR- ================== ================================-- L09 Ajanların zaferi çok L11 Ajanın runtime'ını- erken ilan etmesini engelle gözlemlenebilir kıl-- L10 Tam hat koşusu = L12 Her oturumun sonunda- gerçek doğrulama temiz devir-- | |- v v- P05 Ajan kendi işini doğrular P06 Eksiksiz bir harness kur- (bitirme projesi)-```--Yarı zamanlı ilerliyorsanız her aşama yaklaşık bir hafta sürer. Daha hızlı gitmek istiyorsanız 1-3. aşamalar uzun bir hafta sonunda tamamlanabilir.-------## Müfredat--### Dersler — her biri tek bir temel soruya yanıt veren 12 kavramsal birim--*Her dersin tam metnini [Dokümantasyon Sitesi](https://walkinglabs.github.io/learn-harness-engineering/)'nde okuyun.*--| Oturum | Soru | Temel Fikir |-|---------|------|-------------|-| [L01](./docs/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Güçlü modeller gerçek görevlerde neden hâlâ başarısız olur? | Benchmark'lar ile gerçek mühendislik arasındaki yetenek boşluğu |-| [L02](./docs/lectures/lecture-02-what-a-harness-actually-is/index.md) | "Harness" aslında ne demek? | Beş alt sistem: talimatlar, durum, doğrulama, kapsam, yaşam döngüsü |-| [L03](./docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Depo neden tek kayıt sistemi olmalı? | Ajan göremiyorsa, o şey yok demektir |-| [L04](./docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Tek bir dev talimat dosyası neden yetmez? | Aşamalı açılım: bir harita verin, ansiklopedi değil |-| [L05](./docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Uzun süren görevler neden sürekliliği kaybeder? | İlerlemeyi diske yaz; kaldığın yerden devam et |-| [L06](./docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Başlatma neden kendine ait bir aşama olmalı? | Ajan işe başlamadan önce ortamın sağlıklı olduğunu doğrula |-| [L07](./docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Ajanlar neden sınırı aşar ve yarım bırakır? | Bir seferde tek özellik; bittinin açık tanımı |-| [L08](./docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Özellik listeleri neden harness'ın temel yapı taşı? | Ajanın görmezden gelemeyeceği, makine okur kapsam sınırları |-| [L09](./docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Ajanlar neden zaferi çok erken ilan eder? | Doğrulama boşlukları: güven ≠ doğruluk |-| [L10](./docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Uçtan uca test sonuçları neden değiştirir? | Yalnızca tam hat koşusu gerçek doğrulama sayılır |-| [L11](./docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Gözlemlenebilirlik neden harness'ın içinde olmalı? | Ajanın ne yaptığını göremiyorsanız, bozduğunu da düzeltemezsiniz |-| [L12](./docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Her oturum neden temiz bir durumla bitmeli? | Sonraki oturumun başarısı bu oturumun temizliğine bağlıdır |--### Projeler — ders yöntemlerini aynı Electron uygulamasına uygulayan 6 uygulamalı proje--| Proje | Ne yaparsınız | Harness Mekanizması |-|---------|---------------|----------------------|-| [P01](./docs/projects/project-01-baseline-vs-minimal-harness/index.md) | Aynı görevi iki kez çalıştırın: yalnızca prompt vs. önce kurallar | Minimal harness: AGENTS.md + init.sh + feature_list.json |-| [P02](./docs/projects/project-02-agent-readable-workspace/index.md) | Depoyu ajanın okuyabileceği şekilde yeniden yapılandırın | Ajanın okuyabildiği çalışma alanı + kalıcı durum dosyaları |-| [P03](./docs/projects/project-03-multi-session-continuity/index.md) | Ajanın kaldığı yerden devam etmesini sağlayın | İlerleme günlüğü + oturum devri + çok oturumlu süreklilik |-| [P04](./docs/projects/project-04-incremental-indexing/index.md) | Ajanın çok fazla ya da çok az iş yapmasını engelleyin | Runtime geri bildirimi + kapsam kontrolü + artımlı dizinleme |-| [P05](./docs/projects/project-05-grounded-qa-verification/index.md) | Ajanın kendi işini doğrulamasını sağlayın | Öz-doğrulama + dayanaklı Soru-Cevap + kanıta dayalı tamamlama |-| [P06](./docs/projects/project-06-runtime-observability-and-debugging/index.md) | Eksiksiz bir harness'ı sıfırdan kurun (bitirme projesi) | Tam harness: tüm mekanizmalar + gözlemlenebilirlik + ablasyon çalışması |--```text- PROJE EVRİMİ- ============-- P01 Yalnızca prompt vs. önce kurallar Sorunu görürsünüz- |- v- P02 Ajanın okuyabildiği çalışma alanı Depoyu yeniden yapılandırırsınız- |- v- P03 Çok oturumlu süreklilik Oturumları birbirine bağlarsınız- |- v- P04 Runtime geri bildirimi ve kapsam Geri bildirim döngüleri eklersiniz- |- v- P05 Öz-doğrulama Ajanın kendini denetlemesini sağlarsınız- |- v- P06 Eksiksiz harness (bitirme) Tam sistemi inşa edersiniz-- Her projenin solution'ı bir sonraki projenin starter'ı olur.- Uygulama evrilir. Harness yetenekleriniz onunla birlikte büyür.-```--### Kaynak Kütüphanesi--- [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-------## Ajan oturumunun yaşam döngüsü--Bu kursun temel fikirlerinden biri: **ajanın oturumu serbest takılma değil, yapılandırılmış bir yaşam döngüsünü izlemelidir.** İşte bunun nasıl göründüğü:--```text- AJAN OTURUMU YAŞAM DÖNGÜSÜ- ==========================-- ┌──────────────────────────────────────────────────────────────────┐- │ BAŞLAT │- │ │- │ 1. Ajan AGENTS.md / CLAUDE.md okur │- │ 2. Ajan init.sh çalıştırır (install, verify, health check) │- │ 3. Ajan claude-progress.md okur (geçen sefer ne oldu) │- │ 4. Ajan feature_list.json okur (ne bitti, sırada ne var) │- │ 5. Ajan git log kontrol eder (son değişiklikler) │- │ │- │ SEÇ │- │ │- │ 6. Ajan tam olarak BİR yarım kalmış özellik seçer │- │ 7. Ajan yalnızca o özellik üzerinde çalışır │- │ │- │ YÜRÜT │- │ │- │ 8. Ajan özelliği uygular │- │ 9. Ajan doğrulamayı çalıştırır (testler, lint, tip kontrolü) │- │ 10. Doğrulama başarısızsa: düzelt ve yeniden çalıştır │- │ 11. Doğrulama başarılıysa: kanıtı kayıt altına al │- │ │- │ KAPATIŞ │- │ │- │ 12. Ajan claude-progress.md günceller │- │ 13. Ajan feature_list.json günceller │- │ 14. Ajan hâlâ bozuk ya da doğrulanmamış olanı kaydeder │- │ 15. Ajan commit yapar (yalnızca sürdürmesi güvenli olduğunda) │- │ 16. Ajan sonraki oturum için temiz bir başlama yolu bırakır │- │ │- └──────────────────────────────────────────────────────────────────┘-- Harness bu yaşam döngüsündeki her geçişi yönetir.- Model her adımda hangi kodun yazılacağına karar verir.- Harness olmadan 9. adım "ajan iyi görünüyor diyor" olur.- Harness ile 9. adım "testler geçiyor, lint temiz, tipler kontrol edildi" olur.-```-------## Bu kurs kimler içindir--Bu kurs şunlar için:--- Daha fazla kararlılık ve kalite isteyen, halihazırda kod yazma ajanı kullanan mühendisler-- Harness tasarımını sistematik biçimde anlamak isteyen araştırmacılar veya geliştiriciler-- Ortam tasarımının ajan performansını nasıl etkilediğini anlaması gereken tech lead'ler--Bu kurs şunlar için değil:--- Kod yazmadan bir yapay zeka girişi arayanlar-- Yalnızca prompt'larla ilgilenen ve gerçek uygulamalar geliştirmeyi planlamayanlar-- Ajanların gerçek depolarda çalışmasına izin vermeye hazır olmayan öğrenenler-------## Gereksinimler--Bu, gerçekten kod yazma ajanları çalıştıracağınız bir kurstur.--Şu araçlardan en az birine ihtiyacınız var:--- Claude Code-- Codex-- Dosya düzenleme, komut yürütme ve çok adımlı görevleri destekleyen başka bir IDE veya CLI kod yazma ajanı--Kurs şunları yapabildiğinizi varsayar:--- Yerel bir depo açabilmek-- Ajanın dosyaları düzenlemesine izin vermek-- Ajanın komut çalıştırmasına izin vermek-- Çıktıyı incelemek ve görevleri yeniden çalıştırmak--Bu tür bir aracınız yoksa kurs içeriğini yine de okuyabilirsiniz ama projeleri tasarlandığı gibi tamamlayamazsınız.-------## Yerel önizleme--Bu depo, dokümantasyon görüntüleyici olarak VitePress kullanır.--```sh-npm install-npm run docs:dev # Hot reload ile dev sunucusu-npm run docs:build # Üretim build'i-npm run docs:preview # Build edilmiş siteyi önizle-```--Ardından VitePress'in çıktıladığı yerel URL'yi tarayıcınızda açın.-------## Ön koşullar--Gerekli:--- Terminal, git ve yerel geliştirme ortamlarına aşinalık-- En az bir yaygın uygulama stack'inde kod okuma ve yazma becerisi-- Temel yazılım hata ayıklama deneyimi (log, test ve runtime davranışını okuma)-- Uygulama odaklı kurs çalışmasına ayırabilecek kadar zaman--Yardımcı olur ama gerekli değildir:--- Electron, masaüstü uygulamalar veya local-first araçlarla deneyim-- Test, log veya yazılım mimarisi geçmişi-- Codex, Claude Code veya benzeri kod yazma ajanlarıyla önceki deneyim-------## Temel Referanslar--Birincil:--- [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)--Tam katmanlı referans listesini [`docs/en/resources/reference/`](./docs/en/resources/reference/index.md) içinde bulabilirsiniz.-------## Depo Yapısı--```text-learn-harness-engineering/-├── docs/ # VitePress dokümantasyon sitesi-│ ├── lectures/ # 12 ders (index.md + code/ örnekleri)-│ │ ├── lecture-01-*/-│ │ ├── lecture-02-*/-│ │ └── ... (toplam 12)-│ ├── projects/ # 6 proje açıklaması-│ │ ├── project-01-*/-│ │ └── ... (toplam 6)-│ └── resources/ # Çok dilli şablonlar ve referanslar-│ ├── en/ # İngilizce şablonlar, kontrol listeleri, rehberler-│ ├── zh/ # Çince şablonlar, kontrol listeleri, rehberler-│ ├── ru/ # Rusça şablonlar, kontrol listeleri, rehberler-│ └── vi/ # Vietnamca şablonlar, kontrol listeleri, rehberler-├── projects/-│ ├── shared/ # Ortak Electron + TypeScript + React temeli-│ └── project-NN/ # Proje bazlı starter/ ve solution/ dizinleri-├── skills/ # Yeniden kullanılabilir yapay zeka ajan skill'leri-│ └── harness-creator/ # Harness engineering skill'i-├── package.json # VitePress + dev araçları-└── CLAUDE.md # Bu depo için Claude Code talimatları-```-------## Kurs nasıl organize edilmiş--- Her ders tek bir soruya odaklanır-- Kurs 6 proje içerir-- Her proje ajanın gerçek iş yapmasını gerektirir-- Her proje zayıf vs. güçlü harness sonuçlarını karşılaştırır-- Önemli olan, kaç doküman yazıldığı değil, ölçülen farktır-------## Skills--Bu depo ayrıca IDE'nize veya ajan çalışma alanınıza doğrudan kurabileceğiniz yeniden kullanılabilir yapay zeka ajan skill'leri de içerir.--- [**harness-creator**](./skills/harness-creator/): Kendi projeniz için dakikalar içinde üretim kalitesinde bir harness iskeletini oluşturmanıza yardımcı olan bir skill.-------## Diğer kurslar--Ekibimiz başka kurslar da hazırladı! Göz atın:--[](https://github.com/walkinglabs/hands-on-modern-rl)--**Hands-on Modern RL**: Temel RL kavramlarından LLM hizalamasına, RLVR'ye ve ileri ajansal sistemlere uzanan boşluğu kapatan, açık kaynaklı, uygulamalı bir müfredat.-------## Yıldız Geçmişi--[](https://www.star-history.com/#walkinglabs/learn-harness-engineering&type=date&legend=top-left)-------## Teşekkürler--Bu kurs, [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code)'dan ilham aldı ve fikirler ödünç aldı — tek bir döngüden izole özerk yürütmeye, bir ajanı sıfırdan inşa etmeye yönelik aşamalı bir rehber.diff --git a/README-UZ.md b/README-UZ.mddeleted file mode 100644index ee6826d..0000000--- a/README-UZ.md+++ /dev/null@@ -1,582 +0,0 @@-<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>- <a href="./README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?style=flat-square"></a>-</p>--# Learn Harness Engineering--> **Muhitlar, holat boshqaruvi, tekshiruv va nazorat mexanizmlarini qurishga bagʻishlangan, KI kod yozuvchi agentlarini ishonchli qiladigan loyihaga asoslangan kurs.**--Learn Harness Engineering — KI kod yozuvchi agentlarini ishlab chiqishga bagʻishlangan kurs. Biz sanoatdagi Harness Engineering sohasining eng ilgʻor nazariya va amaliyotlarini chuqur oʻrganib, sintez qildik. Asosiy manbalarimiz:--- [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)--> **Tezkor boshlash?** [`skills/harness-creator/`](../../skills/) skillʼi sizga oʻz loyihangiz uchun daqiqalar ichida ishlab chiqarish darajasidagi harness (AGENTS.md, funksiya roʻyxatlari, init.sh, tekshiruv oqimlari) yaratishga yordam beradi.-------## Mundarija--- [Vizual oldindan koʻrish](#vizual-oldindan-ko%C5%A1ish)-- [Harness Engineering nima degani](#harness-engineering-nima-degani)-- [Tezkor boshlash: Agentingizni bugunoq yaxshilang](#tezkor-boshlash-agentingizni-bugunoq-yaxshilang)-- [Yakuniy loyiha: Haqiqiy ilova](#yakuniy-loyiha-haqiqiy-ilova)-- [Oʻqish yoʻli](#o%C5%9Eqish-yo%C5%A7li)-- [Oʻquv dasturi](#o%C5%9Equv-dasturi)-- [Skillʼlar](#skilllar)-- [Boshqa kurslar](#boshqa-kurslar)-------## Vizual oldindan koʻrish--### Kurs bosh sahifasi-> Kursning toʻliq umumiy koʻrinishi va aniq boshlash yoʻlini taʼminlovchi asosiy falsafalarga kirish.----### Choʻmilishli maʼruzalar-> Haqiqiy muammolar va amaliy loyihalar (masalan, 01-loyiha) boʻyicha chuqur tahlillar, choʻmilishli oʻqish tajribasi uchun.----### Andozalar kutubxonasi-> Koʻp burqli KI agentlarini ishlab chiqishda uchraydigan umumiy muammolarni, masalan kontekst yoʻqotilishi va muddatidan oldin vazifani tugatishni hal qilish uchun moʻljallangan andozalar va moslashtirilgan konfiguratsiyalar.----## PDF kurs kitoblari--Repozitoriyada endi kurs materiallari uchun PDF yaratish pipelineʼi mavjud.--- Ingliz va xitoy PDFʼlarini mahalliy tarzda yaratish uchun `npm run pdf:build` buyrugʻini bajaring.-- Natija fayllari `artifacts/pdfs/` papkasiga yoziladi.-- README oldindan koʻrish rasmlarini yangilash uchun `npm run screenshots:readme` buyrugʻini bajaring.-- [`release-course-pdfs.yml`](../../.github/workflows/release-course-pdfs.yml) GitHub Actions workflowʼi PDFʼlarni yaratib, GitHub Releasesʼga chiqarishi mumkin.-------## Model aqlli, harness uni ishonchli qiladi--Aksariyat odamlar ogʻir yoʻl bilan oʻrganadigan bitta qatʼiy haqiqat bor: **Dunyodagi eng kuchli model haqiqiy muhandislik vazifalarida, agar siz unga mos muhit yaratmasangiz, baribir muvaffaqiyatsiz boʻladi.**--Siz buni ehtimol oʻzingiz ham boshdan kechirgansiz. Claude yoki GPTʼga oʻz repozitoriyoringizda vazifa bersangiz. U yaxshi boshlanadi — fayllarni oʻqiydi, kod yozadi, samarali koʻrinadi. Keyin nimadir notoʻgʻri ketadi. Bir qadamni oʻtkazib yuboradi. Testni buzadi. "Tayyor" deydi, lekin hech narsa haqiqatan ishlamaydi. Oʻzingiz qilgandan koʻra koʻproq vaqtni tuzatishga sarflaysiz.--Bu model muammosi emas. Bu harness muammosi.--Dalillar aniq. Anthropic nazorat qilingan tajriba oʻtkazdi: bir xil model (Opus 4.5), bir xil soʻrov ("2D retro oʻyin muharriri yarating"). Harnessʼsiz u 20 daqiqada 9 $ sarfladi va ishlamaydigan narsa yaratdi. Toʻliq harness bilan (rejalashtiruvchi + generator + baholovchi) u 6 soatda 200 $ sarfladi va haqiqatan oʻynash mumkin boʻlgan oʻyin yaratdi. Model oʻzgarmadi. Harness oʻzgardi.--OpenAI Codex bilan xuddi shu haqida xabar berdi: yaxshi harnesslangan repozitoriyada bir xil model "ishonchsiz"dan "ishonchli"ga oʻtadi. Bu marginal yaxshilanish emas — sifat sakrashi.--**Ushbu kurs sizga shu muhitni qanday qurishni oʻrgatadi.**--```text- HARNESS NAMUNASI- ================-- Siz --> vazifa berasiz --> Agent harness fayllarini oʻqiydi --> Agent bajaradi- |- harness har bir qadamni boshqaradi:- |- +--> Koʻrsatmalar: nima qilish, qanday tartibda- +--> Doira: bir vaqtda bitta funksiya, haddan oshmaslik- +--> Holat: taraqqiyot jurnali, funksiya roʻyxati, git tarixi- +--> Tekshiruv: testlar, lint, tur-tekshirish, sinov ishga tushirish- +--> Hayot sikli: boshida ishga tushirish, oxirida toza holat- |- v- Agent faqat tekshiruv- oʻtganda toʻxtaydi-```-------## Harness Engineering nima degani--Harness Engineering — model atrofida toʻliq ish muhiti qurishdir, shunda u ishonchli natijalar beradi. Bu yaxshi promptʼlar yozish haqida emas. Bu model ishlaydigan tizimni loyihalash haqida.--Harnessʼning beshta quyi tizimi bor:--```text- ┌─────────────────────────────────────────────────────────────────┐- │ HARNESS │- │ │- │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │- │ │ Koʻrsatmalar │ │ Holat │ │ Tekshiruv │ │- │ │ │ │ │ │ │ │- │ │ AGENTS.md │ │ progress.md │ │ testlar + lint │ │- │ │ CLAUDE.md │ │ feature_list │ │ tur-tekshirish │ │- │ │ feature_list │ │ git log │ │ sinov ishga tushirish│ │- │ │ docs/ │ │ sessiya uzat │ │ e2e pipeline │ │- │ └──────────────┘ └──────────────┘ └──────────────────────┘ │- │ │- │ ┌──────────────┐ ┌──────────────────────────────────────┐ │- │ │ Doira │ │ Sessiya hayot sikli │ │- │ │ │ │ │ │- │ │ bir vaqtda │ │ boshida init.sh │ │- │ │ bitta funksiya│ │ oxirida toza-holat tekshiruv roʻyxati│ │- │ │ "tugadi" │ │ keyingi sessiya uchun uzatish yozuvi │ │- │ │ taʼrifi │ │ faqat xavfsiz davom ettirishda commit│ │- │ └──────────────┘ └──────────────────────────────────────┘ │- │ │- └─────────────────────────────────────────────────────────────────┘-- MODEL qanday kod yozishni hal qiladi.- HARNESS qachon, qayerda va qanday yozishni boshqaradi.- Harness modelni aqlliroq qilmaydi.- U model natijasini ishonchli qiladi.-```--Har bir quyi tizimning oʻz vazifasi bor:--- **Koʻrsatmalar (Instructions)** — Agentga nima qilish kerak, qanday tartibda va boshlashdan oldin nima oʻqish kerakligini aytish. Bu bitta ulkan fayl emas; agent ehtiyojiga qarab navigatsiya qiladigan progressiv ochilish strukturasi.-- **Holat (State)** — Nima qilingan, nima bajarilayotgan va keyin nima turib qolganini kuzatish. Diskda saqlanadi, shunda keyingi sessiya aynan oldingi toʻxtagan joydan davom etadi.-- **Tekshiruv (Verification)** — Faqat mavjud test toʻplami dalil sifatida hisoblanadi. Agent bajariluvchi dalilsiz muvaffaqiyat haqida xabar bera olmaydi.-- **Doira (Scope)** — Agentni bir vaqtning oʻzida faqat bitta funksiyaga cheklash. Haddan oshmaslik. Uchta narsani yarim-yorti tugatmaslik. Tugallanmagan ishni yashirish uchun funksiya roʻyxatini qayta yozmaslik.-- **Sessiya hayot sikli (Session Lifecycle)** — Boshida ishga tushirish. Oxirida tozalash. Keyingi sessiya uchun toza qayta boshlash yoʻlini qoldirish.-------## Bu kurs nega mavjud--Savol "Model lar kod yozoladimi?" emas. Yozoladi. Haqiqiy savol: **Ular haqiqiy repozitoriyalarda, bir nechta sessiyalar davomida, doimiy inson nazoratisiz haqiqiy muhandislik vazifalarini ishonchli bajara oladimi?**--Hozircha javob: harnessʼsiz — yoʻq.--```text- HARNESSʼSIZ HARNESS BILAN- ============ ============-- 1-sessiya: agent kod yozadi 1-sessiya: agent koʻrsatmalarni oʻqiydi- agent testlarni buzadi agent init.sh ni ishga tushiradi- agent "tugadi" deydi agent bitta funksiya ustida ishlaydi- siz qoʻlbola tuzatasiz agent "tugadi" deyishdan oldin tekshiradi- agent taraqqiyot jurnalini yangilaydi- 2-sessiya: agent yangidan boshlaydi agent toza holatni commit qiladi- agentning xotirasi yoʻq- oldin nima boʻlganini 2-sessiya: agent taraqqiyot jurnalini oʻqiydi- agent ishni qayta qiladi agent aynan toʻxtagan joydan davom etadi- yoki butunlay boshqa narsa qiladi agent tugallanmagan funksiyani davom ettiradi- siz yana tuzatasiz siz koʻrib chiqasiz, qutqarmaysiz-- Natija: siz oʻzingiz qilganingizdan Natija: agent ishni bajaradi,- koʻra koʻproq vaqtni siz natijani tekshirasiz- tuzatishga sarflaysiz-```--Bu kursni qiziqtiradigan haqiqiy savollar:--- Qanday harness dizaynlari vazifani bajash koʻrsatkichlarini yaxshilaydi?-- Qanday dizaynlar qayta ish va notoʻgʻri tugashlarni kamaytiradi?-- Qanday mexanizmlar uzoq davom etuvchi vazifalarni barqaror oldinga surib turadi?-- Qanday strukturalar tizimni bir nechta agent ishga tushirgandan keyin ham saqlab turiladigan qiladi?-------## Kurs oʻquv dasturi va hujjatlari--Toʻliq kurs materiallarini **[hujjatlar saytida](https://walkinglabs.github.io/learn-harness-engineering/)** topishingiz mumkin.--Oʻquv dasturi uch qismdan iborat:--1. **Maʼruzalar**: Harness Engineering ortidagi nazariyani tushuntiruvchi 12 konseptual blok.-2. **Loyihalar**: Agent asosidagi ish muhitini noldan quradigan 6 ta amaliy loyiha.-3. **Andozalar kutubxonasi**: Bugunoq oʻz repozitoriyalaringizda ishlatish uchun nusxalashga tayyor andozalar (`AGENTS.md`, `feature_list.json`, `init.sh` va h.k.).-------## Tezkor boshlash: Agentingizni bugunoq yaxshilang--Foyda olish uchun 12 ta maʼruzani ham oʻqish shart emas. Agar siz allaqachon haqiqiy loyihada kod yozuvchi agentdan foydalansangiz, uni hoziryoq yaxshilashingiz mumkin.--Gʻoya oddiy: faqat promptʼlar yozish oʻrniga, agentingizga nima qilish kerak, nima allaqachon qilingan va ish qanday tekshirilishini belgilovchi strukturaviy fayllar toʻplamini bering. Bu fayllar repozitoriyangizda joylashgan, shunda har bir sessiya bir xil holatdan boshlanadi.--```text- LOYIHANGIZNING ILDIZ PAPKASI- ├── AGENTS.md <-- agentning ish qoʻllanmasi- ├── CLAUDE.md <-- (Claude Code ishlatganingizda alternativa)- ├── init.sh <-- oʻrnatish + tekshirish + ishga tushirishni bajaradi- ├── feature_list.json <-- qanday funksiyalar mavjud, qaysilari tugallangan- ├── claude-progress.md <-- har bir sessiyada nima boʻlgani- └── src/ <-- sizning haqiqiy kodingiz-```--Boshlangʻich andozalarni [andozalar kutubxonasidan](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) yuklab oling va loyihangizga qoʻshing. Shu. Toʻrtta fayl, va agent sessiyalaringiz allaqachon faqat promptʼlarga qaraganda ancha barqaror boʻladi.-------## Yakuniy loyiha: Haqiqiy ilova--Oltita kurs loyihasi bir xil mahsulot atrofida qurilgan: **Electron asosidagi shaxsiy bilim bazasi uchun desktop ilova**.--```text- ┌─────────────────────────────────────────────────────┐- │ Bilim bazasi desktop ilovasi │- │ │- │ ┌──────────────┐ ┌──────────────────────────────┐│- │ │ Hujjatlar │ │ S&S paneli ││- │ │ roʻyxati │ │ ││- │ │ │ │ S: Harness eng nima? ││- │ │ doc-001.md │ │ J: Agent modeli atrofida ││- │ │ doc-002.md │ │ qurilgan muhit... ││- │ │ doc-003.md │ │ [manba: doc-002.md] ││- │ │ ... │ │ ││- │ └──────────────┘ └──────────────────────────────┘│- │ │- │ ┌─────────────────────────────────────────────────┐│- │ │ Holat paneli: 42 hujjat | 38 indekslangan | soʻnggi sinxronizatsiya 3d ││- │ └─────────────────────────────────────────────────┘│- └─────────────────────────────────────────────────────┘-- Asosiy funksiyalar:- ├── Mahalliy hujjatlarni import qilish- ├── Hujjatlar kutubxonasini boshqarish- ├── Hujjatlarni qayta ishlash va indekslash- ├── Import qilingan kontent ustida KI asosidagi S&S oʻtkazish- └── Manbalar bilan asoslangan javoblarni qaytarish-```--Bu loyiha shuning uchun tanlanganki, u yuqori amaliy foyda, yetarli haqiqiy mahsulot murakkabligi va harness yaxshilanishlarini kuzatish uchun yaxshi stsenariyani oʻzida birlashtiradi.--Har bir kurs loyihasi (boshlangʻich/yechim) ushbu Electron ilovasining mos rivojlanish bosqichidagi toʻliq nusxasidir. P(N+1) boshlangʻichi P(N) yechimidan hosil qilinadi — ilova rivojlanadi, harness koʻnikmalaringiz esa oʻsadi.-------## Oʻqish yoʻli--Kurs xronologik tartibda bajarish uchun moʻljallangan. Har bir bosqich oldingisiga asoslanadi.--```text- 1-bosqich: MUAMMONI KOʻRISH 2-bosqich: REPONI TUZISH- =========================== ========================-- L01 Kuchli modellar ≠ ishonchli L03 Repo yagona haqiqat- bajarish manbai sifatida- L02 Harness nima degani haqiqatan- L04 Koʻrsatmalarni bitta ulkan- | faylga emas, bir nechta faylga boʻlish- v- P01 Faqat prompt vs. |- qoidalarga asoslangan solishtirish v- P02 Agent oʻqiy oladigan ish muhiti--- 3-bosqich: SESSIYALARNI BOGʻLASH 4-bosqich: FIKR-MULOHAZA VA DOIRA- ================================ ================================-- L05 Kontekstni sessiyalar L07 Aniq vazifa chegaralarini chizish- orasida saqlash- L08 Funksiya roʻyxatlari harness- L06 Har bir agent sessiyasidan primitivlari sifatida- oldin ishga tushirish- |- | v- v P04 Agent xatti-harakatini- P03 Koʻp sessiyali uzluksizlik tuzatish uchun runtime fikr-mulohaza--- 5-bosqich: TEKSHIRUV 6-bosqich: HAMMASINI BIRGA JAMQILISH- =================== ===================================-- L09 Agentlarga erta L11 Agent runtime'ini- muvaffaqiyat haqida xabar kuzatiladigan qilish- berishiga toʻsqinlik qilish- L12 Har bir sessiya oxirida- L10 Toʻliq pipeline ishga toza uzatish- tushirish = haqiqiy tekshiruv- |- | v- v P06 Toʻliq harness qurish- P05 Agent oʻz ishini mustaqil tekshiradi (yakuniy loyiha)-```--Agar parallel oʻqisangiz, har bir bosqich taxminan bir hafta davom etadi. Agar tezroq borishni xohlasangiz, 1–3 bosqichlarni bitta uzun dam olish kunlarida tugatishingiz mumkin.-------## Oʻquv dasturi--### Maʼruzalar — har biri muhim savolga javob beruvchi 12 ta konseptual blok--*Har bir maʼruza matnini toʻliq oʻqish uchun [hujjatlar sayti](https://walkinglabs.github.io/learn-harness-engineering/)ga murojaat qiling.*--| Sessiya | Savol | Asosiy gʻoya |-|---------|-------|--------------|-| [L01](../../docs/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Kuchli modellar nega haqiqiy vazifalarda muvaffaqiyatsiz boʻladi? | Benchmarkʼlar va haqiqiy muhandislik oʻrtasidagi farq |-| [L02](../../docs/lectures/lecture-02-what-a-harness-actually-is/index.md) | "Harness" nima degani? | Besh quyi tizim: Koʻrsatmalar, Holat, Tekshiruv, Doira, Hayot sikli |-| [L03](../../docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Nega repozitoriy yagona haqiqat manbai boʻlishi kerak? | Agar agent koʻrolmasa, u mavjud emas |-| [L04](../../docs/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Nega bitta ulkan koʻrsatma fayli muvaffaqiyatsiz boʻladi? | Progressiv ochilish: xarita berish, ensiklopediya emas |-| [L05](../../docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Nega uzoq davom etuvchi vazifalar uzluksizlikni yoʻqotadi? | Taraqqiyotni diskda saqlash; toʻxtagan joydan davom ettirish |-| [L06](../../docs/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Nega ishga tushirish alohida bosqichga muhtoj? | Agent ishni boshlashdan oldin muhit ishlashini tekshirish |-| [L07](../../docs/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Nega agentlar haddan oshadi va yarim-yorti tugatadi? | Bir vaqtda bitta funksiya; "Tugadi" ning aniq taʼrifi |-| [L08](../../docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Nega funksiya roʻyxatlari harness primitivlari hisoblanadi? | Agent eʼtiborsiz qoldirolmaydigan, mashina oʻqiyoladigan doira chegaralari |-| [L09](../../docs/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Nega agentlar juda erta muvaffaqiyat haqida xabar beradi? | Tekshiruv boʻshliqlari: ishonch = toʻgʻrilik emas |-| [L10](../../docs/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Nega uchdan-uchgacha testlash natijalarni oʻzgartiradi? | Faqat toʻliq pipeline ishga tushirish haqiqiy tekshiruv hisoblanadi |-| [L11](../../docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Nega kuzatuvchanlik harness ichida boʻlishi kerak? | Agent nima qilganini koʻrolmasangiz, u buzgan narsani tuzata olmaysiz |-| [L12](../../docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Nega har bir sessiya toiza holat qoldirishi kerak? | Keyingi sessiyaning muvaffaqiyati shu sessiyaning tozalanishiga bogʻliq |--### Loyihalar — maʼruza usullarini bir xil Electron ilovasiga qoʻllaydigan 6 ta amaliy loyiha--| Loyiha | Nima qilasiz | Harness mexanizmi |-|---------|--------------|-------------------|-| [P01](../../docs/projects/project-01-baseline-vs-minimal-harness/index.md) | Bir xil vazifani ikki marta bajarish: faqat prompt vs. qoidalarga asoslangan | Minimal harness: AGENTS.md + init.sh + feature_list.json |-| [P02](../../docs/projects/project-02-agent-readable-workspace/index.md) | Repoʼni agent oʻqiy oladigan qayta tuzish | Agent oʻqiy oladigan ish muhiti + doimiy holat fayllari |-| [P03](../../docs/projects/project-03-multi-session-continuity/index.md) | Agentni toʻxtagan joyidan davom ettirish | Taraqqiyot jurnali + sessiya uzatish + koʻp sessiyali uzluksizlik |-| [P04](../../docs/projects/project-04-incremental-indexing/index.md) | Agentning koʻp yoki oz ishlashining oldini olish | Runtime fikr-mulohaza + doira nazorati + inkremental indekslash |-| [P05](../../docs/projects/project-05-grounded-qa-verification/index.md) | Agentni oʻz ishini tekshirishga majburlash | Oʻz-oʻzini tekshirish + asoslangan S&S + dalillarga asoslangan tugatish |-| [P06](../../docs/projects/project-06-runtime-observability-and-debugging/index.md) | Toʻliq harnessʼni noldan qurish (yakuniy loyiha) | Toʻliq harness: barcha mexanizmlar + kuzatuvchanlik + ablyatsiya tadqiqoti |--```text- LOYIHA RIVOJLANISHI- ===================-- P01 Faqat prompt vs. qoidalarga asoslangan Siz muammoni koʻrasiz- |- v- P02 Agent oʻqiy oladigan ish muhiti Siz repolarni qayta tuzasiz- |- v- P03 Koʻp sessiyali uzluksizlik Siz sessiyalarni bogʻlaysiz- |- v- P04 Runtime fikr-mulohaza va doira Siz fikr-mulohaza halqalarini qoʻshasiz- |- v- P05 Oʻz-oʻzini tekshirish Siz agentni oʻz-oʻzini tekshirishga majburlaysiz- |- v- P06 Toʻliq harness (yakuniy loyiha) Siz toʻliq tizimni qurasiz-- Har bir loyihaning yechimi keyingi loyihaning boshlangʻichiga aylanadi.- Ilova rivojlanadi. Harness koʻnikmalaringiz unga qarab oʻsadi.-```--### Andozalar kutubxonasi--- [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-------## Agent sessiyasi hayot sikli--Ushbu kursning asosiy gʻoyalaridan biri: **Agent sessiyasi tuzilgan hayot sikliga amal qilishi kerak, emas xohlagancha ishlashiga.** Bu quyidagicha koʻrinadi:--```text- AGENT SESSIYA HAYOT SIKLI- =========================-- ┌──────────────────────────────────────────────────────────────────┐- │ BOSHLASH │- │ │- │ 1. Agent AGENTS.md / CLAUDE.md faylini oʻqiydi │- │ 2. Agent init.sh ni ishga tushiradi (oʻrnatish, tekshirish, sogʻliqni nazorat)│- │ 3. Agent claude-progress.md ni oʻqiydi (oxirgi safar nima boʻldi)│- │ 4. Agent feature_list.json ni oʻqiydi (nima tugadi, keyin nima)│- │ 5. Agent git log ni tekshiradi (soʻnggi oʻzgarishlar) │- │ │- │ TANLASH │- │ │- │ 6. Agent aynan BITTA tugallanmagan funksiyani tanlaydi │- │ 7. Agent faqat shu funksiya ustida ishlaydi │- │ │- │ BAJARISH │- │ │- │ 8. Agent funksiyani amalga oshiradi │- │ 9. Agent tekshiruvni ishga tushiradi (testlar, lint, tur-tekshirish)│- │ 10. Agar tekshiruv oʻtmasa: tuzatish va qayta ishga tushirish │- │ 11. Agar tekshiruv oʻtsa: dalilni qayd etish │- │ │- │ YAKUNLASH │- │ │- │ 12. Agent claude-progress.md ni yangilaydi │- │ 13. Agent feature_list.json ni yangilaydi │- │ 14. Agent hali buzilgan yoki tekshirilmagan narsalarni qayd etadi│- │ 15. Agent commit qiladi (faqat xavfsiz davom ettirishda) │- │ 16. Agent keyingi sessiya uchun toza qayta boshlash yoʻlini qoldiradi│- │ │- └──────────────────────────────────────────────────────────────────┘-- Harness ushbu hayot siklidagi har bir oʻtishni boshqaradi.- Model har bir qadamda qanday kod yozishni hal qiladi.- Harnessʼsiz 9-qadam "agent yaxshi koʻrinadi deydi" ga aylanadi.- Harness bilan 9-qadam "testlar oʻtdi, lint toza, turlar tekshirildi" boʻladi.-```-------## Bu kurs kim uchun?--Bu kurs quyidagilar uchun moʻljallangan:--- Kod yozuvchi agentlardan foydalanayotgan va koʻproq barqarorlik va sifat xohlaydigan dasturchilar-- Harness dizayni boʻyicha tizimli tushunchaga ega boʻlishni xohlaydigan tadqiqotchilar yoki dasturchilar-- Muhit dizayni agent ish faoliyatiga qanday taʼsir qilishini tushunmoqchi boʻlgan texnik yetakchilar--Bu kurs quyidagilar uchun moʻljallanmagan:--- Dasturlashsiz KI kirishini qidirayotganlar-- Faqat promptʼlar bilan qiziqqan va haqiqiy amalga oshirishni rejalashtirmaydiganlar-- Agentlarni haqiqiy repozitoriyalarda ishlashga tayyor boʻlmagan oʻquvchilar-------## Talablar--Bu siz haqiqatan kod yozuvchi agentlarni ishga tushiradigan kurs.--Kamida quyidagi vositalardan biriga muhtojsiz:--- Claude Code-- Codex-- Fayl tahrirlash, buyruqlarni bajarish va koʻp bosqichli vazifalarni qoʻllab-quvvatlovchi boshqa IDE yoki CLI kod yozuvchi agent--Kurs quyidagilarni talab qiladi:--- Mahalliy repozitoriyni ochish-- Agentga fayllarni tahrirlashga ruxsat berish-- Agentga buyruqlar bajarishga ruxsat berish-- Natijalarni tekshirish va vazifalarni qayta boshlash--Agar sizda bunday vosita boʻlmasa, kurs materiallarini oʻqiy olasiz, lekin loyihalarni rejalashtirilganidek bajara olmaysiz.-------## Mahalliy oldindan koʻrish--Ushbu repozitoriy hujjatlar koʻrish vositasi sifatida VitePressʼdan foydalanadi.--```sh-npm install-npm run docs:dev # Hot reload bilan dev-server-npm run docs:build # Ishlab chiqarish buildʼi-npm run docs:preview # Yaratilgan saytni oldindan koʻrish-```--Keyin VitePress koʻrsatadigan mahalliy URLʼni brauzeringizda oching.-------## Oldindan bilim--Talab qilinadi:--- Terminal, Git va mahalliy rivojlanish muhitlari bilan tanishlik-- Kamida bitta keng tarqalgan ilova stackʼida kodni oʻqish va yozish qobiliyati-- Asosiy dasturiy xatolarni tuzatish tajribasi (logʼlarni oʻqish, testlar va runtime xatti-harakati)-- Amalga oshirishga yoʻnaltirilgan kurs ishi uchun yetarli vaqt--Yordam beradi, lekin majburiy emas:--- Electron, desktop ilovalar yoki local-first vositalar bilan tajriba-- Testlash, logʼlash yoki dasturiy taʼminot arxitekturasi sohasida tajriba-- Codex, Claude Code yoki shunga oʻxshash kod yozuvchi agentlar bilan oldingi tajriba-------## Asosiy manbalar--Birlamchi:--- [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)--Toʻliq qatlamli manbalar roʻyxatini [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md) da topishingiz mumkin.-------## Repozitoriy strukturasi--```text-learn-harness-engineering/-├── docs/ # VitePress hujjatlar sayti-│ ├── lectures/ # 12 ta maʼruza (index.md + code/ misollar)-│ │ ├── lecture-01-*/-│ │ ├── lecture-02-*/-│ │ └── ... (jami 12 ta)-│ ├── projects/ # 6 ta loyiha tavsifi-│ │ ├── project-01-*/-│ │ └── ... (jami 6 ta)-│ └── resources/ # Koʻp tilli andozalar va maʼlumotnomalar-│ ├── en/ # Ingliz andozalari, tekshiruv roʻyxatlari, qoʻllanmalar-│ ├── zh/ # Xitoy andozalari, tekshiruv roʻyxatlari, qoʻllanmalar-│ ├── ru/ # Rus andozalari, tekshiruv roʻyxatlari, qoʻllanmalar-│ └── vi/ # Vetnam andozalari, tekshiruv roʻyxatlari, qoʻllanmalar-├── projects/-│ ├── shared/ # Umumiy Electron + TypeScript + React asos-│ └── project-NN/ # Loyihaga oid starter/ va solution/ papkalari-├── skills/ # Qayta ishlatiladigan KI agent skillʼlari-│ └── harness-creator/ # Harness Engineering skillʼi-├── package.json # VitePress + dev vositalari-└── CLAUDE.md # Ushbu repo uchun Claude Code koʻrsatmalari-```-------## Kurs qanday tuzilgan--- Har bir maʼruza bitta savolga qaratilgan-- Kurs 6 ta loyihani oʻz ichiga oladi-- Har bir loyiha agentdan haqiqiy ish bajarishni talab qiladi-- Har bir loyiha kuchsiz vs. kuchli harness natijalarini solishtiradi-- Muhim boʻlgan narsa — oʻlchangan farq, nechta hujjat yozilgani emas-------## Skillʼlar--Ushbu repozitoriy, shuningdek, toʻgʻridan-toʻgʻri IDE yoki agent ish muhitiga oʻrnatishingiz mumkin boʻlgan qayta ishlatiladigan KI agent skillʼlarini oʻz ichiga oladi.--- [**harness-creator**](../../skills/harness-creator/): Oʻz loyihangiz uchun daqiqalar ichida ishlab chiqarish darajasidagi harness yaratishga yordam beradigan skill.-------## Boshqa kurslar--Bizning jamoamiz yana boshqa kurslar ham yaratdi! Ularni koʻrib chiqing:--[](https://github.com/walkinglabs/hands-on-modern-rl)--**Hands-on Modern RL**: Asosiy RL konsepsiyalaridan LLM alignment, RLVR va ilgʻor agent tizimlarigacha boʻlgan masofani bridjlash uchun ochiq manbali amaliy oʻquv dasturi.-------## Yulduzlar tarixi--[](https://www.star-history.com/#walkinglabs/learn-harness-engineering&type=date&legend=top-left)-------## Minnatdorchilik--Ushbu kurs [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) dan ilhomlangan va undan gʻoyalar olgan — agentni bitta sikldan izolyatsiya qilingan avtonom bajarishgacha noldan qurish boʻyicha progressiv qoʻllanma.diff --git a/README-VI.md b/README-VI.mddeleted file mode 100644index 3f927c6..0000000--- a/README-VI.md+++ /dev/null@@ -1,585 +0,0 @@-<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>- <a href="./README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?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- MÔ HÌNH HARNESS- ===============-- Bạn --> giao tác vụ --> Agent đọc tệp harness --> Agent thực thi- |- harness điều phối mọi bước:- |- +--> Hướng dẫn: làm gì, theo thứ tự nào- +--> Phạm vi: một tính năng mỗi lần, không vượt quá- +--> Trạng thái: nhật ký tiến trình, danh sách tính năng, lịch sử git- +--> Kiểm chứng: bài kiểm tra, lint, kiểm tra kiểu, chạy thử- +--> Vòng đời: khởi tạo lúc bắt đầu, trạng thái sạch lúc kết thúc- |- v- Agent chỉ dừng khi- kiểm chứng đạt yêu cầu-```-------## 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- ┌─────────────────────────────────────────────────────────────────┐- │ HARNESS │- │ │- │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │- │ │ Hướng dẫn │ │ Trạng thái │ │ Kiểm chứng │ │- │ │ │ │ │ │ │ │- │ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │- │ │ CLAUDE.md │ │ feature_list │ │ kiểm tra kiểu │ │- │ │ feature_list │ │ git log │ │ chạy thử │ │- │ │ docs/ │ │ bàn giao phiên│ │ pipeline e2e │ │- │ └──────────────┘ └──────────────┘ └──────────────────────┘ │- │ │- │ ┌──────────────┐ ┌──────────────────────────────────────┐ │- │ │ Phạm vi │ │ Vòng đời phiên │ │- │ │ │ │ │ │- │ │ một tính │ │ init.sh lúc bắt đầu │ │- │ │ năng mỗi lần │ │ danh sách kiểm tra sạch lúc kết thúc │ │- │ │ định nghĩa │ │ ghi chú bàn giao cho phiên tiếp │ │- │ │ "hoàn thành" │ │ commit chỉ khi an toàn để tiếp tục │ │- │ └──────────────┘ └──────────────────────────────────────┘ │- │ │- └─────────────────────────────────────────────────────────────────┘-- MÔ HÌNH quyết định viết code gì.- HARNESS điều phối khi nào, ở đâu và viết như thế nào.- Harness không làm mô hình thông minh hơn.- Nó làm đầu ra của mô hình đáng tin cậy hơn.-```--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- KHÔNG CÓ HARNESS CÓ HARNESS- ================ ==========-- Phiên 1: agent viết code Phiên 1: agent đọc hướng dẫn- agent làm hỏng bài kiểm tra agent chạy init.sh- agent nói "xong rồi" agent làm một tính năng- bạn tự sửa thủ công agent kiểm chứng trước khi nói xong- agent cập nhật nhật ký tiến trình- Phiên 2: agent bắt đầu lại từ đầu agent commit trạng thái sạch- agent không nhớ- những gì đã xảy ra trước đó Phiên 2: agent đọc nhật ký tiến trình- agent làm lại từ đầu agent tiếp tục chính xác nơi đã dừng- hoặc làm hoàn toàn việc khác agent tiếp tục tính năng chưa xong- bạn lại phải sửa lại bạn đánh giá, không phải cứu vãn-- Kết quả: bạn dành nhiều thời gian Kết quả: agent làm công việc,- dọn dẹp hơn là nếu bạn bạn kiểm chứng kết quả- tự làm lấy-```--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- THƯ MỤC GỐC DỰ ÁN CỦA BẠN- ├── AGENTS.md <-- sổ tay vận hành của agent- ├── CLAUDE.md <-- (thay thế, nếu dùng Claude Code)- ├── init.sh <-- chạy cài đặt + xác minh + khởi động- ├── feature_list.json <-- tính năng nào tồn tại, cái nào đã xong- ├── claude-progress.md <-- những gì đã xảy ra trong mỗi phiên- └── src/ <-- code thực tế của bạn-```--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- ┌─────────────────────────────────────────────────────┐- │ Ứng dụng Desktop Cơ sở Tri thức │- │ │- │ ┌──────────────┐ ┌──────────────────────────────┐│- │ │ Danh sách tài │ │ Bảng Hỏi-Đáp ││- │ │ liệu │ │ ││- │ │ doc-001.md │ │ H: Harness engineering là gì?││- │ │ doc-002.md │ │ Đ: Môi trường được xây dựng ││- │ │ doc-003.md │ │ quanh một mô hình agent...││- │ │ ... │ │ [trích dẫn: doc-002.md] ││- │ └──────────────┘ └──────────────────────────────┘│- │ │- │ ┌─────────────────────────────────────────────────┐│- │ │ Thanh trạng thái: 42 tài liệu | 38 đã lập chỉ │││- │ │ mục | đồng bộ lần cuối 3p │││- │ └─────────────────────────────────────────────────┘│- └─────────────────────────────────────────────────────┘-- Tính năng cốt lõi:- ├── Nhập tài liệu cục bộ- ├── Quản lý thư viện tài liệu- ├── Xử lý và lập chỉ mục tài liệu- ├── Chạy Hỏi-Đáp AI trên nội dung đã nhập- └── Trả lời có căn cứ kèm trích dẫn-```--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- Giai đoạn 1: NHÌN VẤN ĐỀ Giai đoạn 2: TỔ CHỨC KHO MÃ- ========================= ===========================-- L01 Mô hình mạnh ≠ thực thi L03 Kho mã là nguồn- đáng tin cậy chân lý duy nhất- L02 Harness thực sự nghĩa là gì- L04 Chia hướng dẫn thành nhiều- | tệp, không phải một tệp khổng lồ- v- P01 Chỉ dùng prompt vs. |- ưu tiên quy tắc v- P02 Không gian làm việc agent đọc được--- Giai đoạn 3: KẾT NỐI CÁC PHIÊN Giai đoạn 4: PHẢN HỒI & PHẠM VI- ============================== ================================-- L05 Giữ ngữ cảnh sống L07 Vẽ ranh giới tác vụ rõ ràng- qua các phiên- L08 Danh sách tính năng như- L06 Khởi tạo trước mọi nguyên thủy harness- phiên agent- |- | v- v P04 Phản hồi thời gian chạy- P03 Tính liên tục đa phiên sửa hành vi agent--- Giai đoạn 5: KIỂM CHỨNG Giai đoạn 6: TỔNG HỢP TẤT CẢ- ========================= =============================-- L09 Ngăn agent tuyên bố L11 Làm thời gian chạy của- hoàn thành quá sớm agent có thể quan sát-- L10 Chạy toàn bộ pipeline = L12 Bàn giao sạch ở cuối- kiểm chứng thực sự mọi phiên-- | |- v v- P05 Agent tự kiểm chứng P06 Xây dựng harness hoàn chỉnh- (dự án tổng kết)-```--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- SỰ PHÁT TRIỂN DỰ ÁN- ===================-- P01 Chỉ dùng prompt vs. ưu tiên Bạn nhìn thấy vấn đề- quy tắc- |- v- P02 Không gian làm việc Bạn tái cấu trúc kho mã- agent đọc được- |- v- P03 Tính liên tục đa phiên Bạn kết nối các phiên- |- v- P04 Phản hồi & phạm vi Bạn thêm các vòng phản hồi- thời gian chạy- |- v- P05 Tự kiểm chứng Bạn khiến agent tự kiểm tra- |- v- P06 Harness hoàn chỉnh (tổng kết) Bạn xây dựng hệ thống đầy đủ-- Solution của mỗi dự án trở thành starter của dự án tiếp theo.- Ứng dụng phát triển. Kỹ năng harness của bạn lớn lên cùng nó.-```--### 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- VÒNG ĐỜI PHIÊN AGENT- ====================-- ┌──────────────────────────────────────────────────────────────────┐- │ BẮT ĐẦU │- │ │- │ 1. Agent đọc AGENTS.md / CLAUDE.md │- │ 2. Agent chạy init.sh (cài đặt, xác minh, kiểm tra sức khỏe) │- │ 3. Agent đọc claude-progress.md (đã xảy ra gì lần trước) │- │ 4. Agent đọc feature_list.json (cái gì xong, cái gì tiếp) │- │ 5. Agent kiểm tra git log (thay đổi gần đây) │- │ │- │ CHỌN TÁC VỤ │- │ │- │ 6. Agent chọn chính xác MỘT tính năng chưa hoàn thành │- │ 7. Agent chỉ làm việc trên tính năng đó │- │ │- │ THỰC THI │- │ │- │ 8. Agent triển khai tính năng │- │ 9. Agent chạy kiểm chứng (bài kiểm tra, lint, kiểm tra kiểu) │- │ 10. Nếu kiểm chứng thất bại: sửa và chạy lại │- │ 11. Nếu kiểm chứng đạt: ghi nhận bằng chứng │- │ │- │ KẾT THÚC │- │ │- │ 12. Agent cập nhật claude-progress.md │- │ 13. Agent cập nhật feature_list.json │- │ 14. Agent ghi lại những gì vẫn còn lỗi hoặc chưa kiểm chứng │- │ 15. Agent commit (chỉ khi an toàn để tiếp tục) │- │ 16. Agent để lại đường khởi động lại sạch cho phiên tiếp │- │ │- └──────────────────────────────────────────────────────────────────┘-- Harness điều phối mọi chuyển đổi trong vòng đời này.- Mô hình quyết định viết code gì ở mỗi bước.- Không có harness, bước 9 trở thành "agent nói trông ổn rồi."- Có harness, bước 9 là "bài kiểm tra đạt, lint sạch, kiểu đúng."-```-------## 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.mddeleted file mode 100644index 5a9adc9..0000000--- a/README-ZH-TW.md+++ /dev/null@@ -1,575 +0,0 @@-<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>- <a href="./README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?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- HARNESS 模式- ============-- 你 --> 給定任務 --> 代理讀取 harness 檔案 --> 代理執行- |- harness 管控每個步驟:- |- +--> 指令:該做什麼,以什麼順序- +--> 範圍:一次一個功能,不過度延伸- +--> 狀態:進度日誌、功能列表、git 歷史- +--> 驗證:測試、lint、型別檢查、冒煙測試- +--> 生命週期:開始時初始化,結束時乾淨狀態- |- v- 代理只在驗證通過時- 才會停止-```-------## Harness Engineering 的真正含義--Harness Engineering 是關於在模型周圍建構一個完整的工作環境,使其產生可靠的結果。它不是關於寫更好的提示。它是關於設計模型運作所在的系統。--一個 harness 有五個子系統:--```text- ┌─────────────────────────────────────────────────────────────────┐- │ HARNESS 系統 │- │ │- │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │- │ │ 指令 │ │ 狀態 │ │ 驗證 │ │- │ │ │ │ │ │ │ │- │ │ AGENTS.md │ │ progress.md │ │ 測試 + lint │ │- │ │ CLAUDE.md │ │ feature_list │ │ 型別檢查 │ │- │ │ feature_list │ │ git log │ │ 冒煙測試 │ │- │ │ docs/ │ │ 工作階段交接 │ │ 端到端流程 │ │- │ └──────────────┘ └──────────────┘ └──────────────────────┘ │- │ │- │ ┌──────────────┐ ┌──────────────────────────────────────┐ │- │ │ 範圍 │ │ 工作階段生命週期 │ │- │ │ │ │ │ │- │ │ 一次一個功能 │ │ 開始時執行 init.sh │ │- │ │ 明確的完成 │ │ 結束時使用乾淨狀態檢查清單 │ │- │ │ 定義 │ │ 為下一個工作階段留下交接筆記 │ │- │ │ │ │ 只在可安全恢復時才提交 │ │- │ └──────────────┘ └──────────────────────────────────────┘ │- │ │- └─────────────────────────────────────────────────────────────────┘-- 模型決定要寫什麼程式碼。- HARNESS 管控何時、在哪裡、以及如何撰寫。- Harness 不會讓模型變得更聰明。- 它讓模型的輸出變得可靠。-```--每個子系統各有其職責:--- **Instructions(指令)** — 告訴代理該做什麼、以什麼順序、以及在開始前該閱讀什麼。不是一個巨大的檔案;而是一個漸進揭露的結構,讓代理按需導航。-- **State(狀態)** — 追蹤已完成的事項、正在進行的事項、以及接下來該做的事。持久化到磁碟,讓下一個工作階段可以精確地從上一個階段停止的地方接續。-- **Verification(驗證)** — 只有通過的測試套件才算數。代理不能在沒有可執行證據的情況下宣告勝利。-- **Scope(範圍)** — 將代理限制在每次只做一個功能。不過度延伸。不三件事做一半。不改寫功能列表來隱藏未完成的工作。-- **Session Lifecycle(工作階段生命週期)** — 開始時初始化。結束時清理。為下一個工作階段留下乾淨的重啟路徑。-------## 為什麼會有這門課程--問題不是「模型能不能寫程式?」它們能。問題是:**它們能不能在真實的儲存庫中,跨越多個工作階段,在沒有持續人工監督的情況下,可靠地完成真實的工程任務?**--目前的答案是:沒有 harness 就不行。--```text- 沒有 HARNESS 有 HARNESS- ============== ============-- 工作階段 1:代理撰寫程式碼 工作階段 1:代理讀取指令- 代理破壞了測試 代理執行 init.sh- 代理說「完成了」 代理只做一個功能- 你手動修復 代理在宣告完成前先驗證- 代理更新進度日誌- 工作階段 2:代理從頭開始 代理提交乾淨狀態- 代理沒有記憶- 不知道之前發生了什麼 工作階段 2:代理讀取進度日誌- 代理重做工作 代理精確地從上次停止處接續- 或者做完全不同的事情 代理繼續未完成的功能- 你再次修復 你是審查,不是搶救-- 結果:你花在清理的時間 結果:代理做工作,- 比自己動手做還多 你驗證結果-```--這門課程真正關心的問題:--- 哪些 harness 設計能提升任務完成率?-- 哪些設計能減少返工與錯誤完成?-- 哪些機制能讓長時間執行的任務穩定推進?-- 哪些結構能讓系統在多次代理執行後仍保持可維護性?-------## 課程內容與文件--完整的課程資料,請造訪**[文件網站](https://walkinglabs.github.io/learn-harness-engineering/)**。--課程分為三個部分:--1. **講座**:12 個概念單元,解釋 harness engineering 背後的理論。-2. **專案**:6 個動手專案,讓你從零建構一個代理工作空間。-3. **資源庫**:可直接複製使用的模板(`AGENTS.md`、`feature_list.json`、`init.sh` 等),今天就能在你的儲存庫中使用。-------## 快速入門:今天就改善你的代理--你不需要讀完所有 12 堂講座才能開始受益。如果你已經在真實專案中使用程式設計代理,以下是如何立刻改善它的方法。--概念很簡單:與其只寫提示,不如給你的代理一組結構化的檔案,定義該做什麼、已經做了什麼、以及如何驗證工作。這些檔案存在你的儲存庫中,所以每個工作階段都從相同的狀態開始。--```text- 你的專案根目錄- ├── 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- ┌─────────────────────────────────────────────────────┐- │ 知識庫桌面應用程式 │- │ │- │ ┌──────────────┐ ┌──────────────────────────────┐│- │ │ 文件列表 │ │ 問答面板 ││- │ │ │ │ ││- │ │ doc-001.md │ │ 問:什麼是 harness 工程? ││- │ │ doc-002.md │ │ 答:圍繞代理模型建構的 ││- │ │ doc-003.md │ │ 環境...... ││- │ │ ... │ │ [引用來源:doc-002.md] ││- │ └──────────────┘ └──────────────────────────────┘│- │ │- │ ┌─────────────────────────────────────────────────┐│- │ │ 狀態列:42 篇文件 | 38 篇已索引 | 上次同步 3 分鐘前││- │ └─────────────────────────────────────────────────┘│- └─────────────────────────────────────────────────────┘-- 核心功能:- ├── 匯入本地文件- ├── 管理文件庫- ├── 處理和索引文件- ├── 對匯入內容執行 AI 問答- └── 回傳有依據的答案與引用來源-```--選擇這個專案是因為它結合了強大的實用價值、足夠的真實產品複雜度,以及觀察 harness 改善前後差異的良好場景。--每個課程專案的 starter/solution 是這個 Electron 應用程式在那個演化階段的完整副本。P(N+1) 的 starter 衍生自 P(N) 的 solution——隨著你的 harness 技能成長,應用程式也在演化。-------## 學習路徑--課程設計為按順序進行。每個階段建立在前一個階段之上。--```text- 階段 1:看見問題 階段 2:建構儲存庫結構- =================== ========================-- L01 強大的模型 ≠ 可靠的執行 L03 儲存庫作為唯一真實來源- L02 Harness 到底是什麼意思- L04 將指令分散到多個檔案,- | 而非一個巨大檔案- v- P01 僅提示 vs. 規則優先比較 |- v- P02 代理可讀的工作空間--- 階段 3:連接工作階段 階段 4:回饋與範圍- ======================= ==================-- L05 跨工作階段保持上下文 L07 劃清任務邊界- L06 每次代理工作階段前初始化 L08 功能列表作為 harness- 基本元素- |- v P04 執行時回饋修正- P03 多工作階段連續性 代理行為--- 階段 5:驗證 階段 6:整合所有內容- ================= ========================-- L09 阻止代理過早宣告勝利 L11 讓代理的執行時行為- 可觀測- L10 完整流程執行 = L12 每個工作階段結束時- 真正的驗證 乾淨的交接-- | |- v v- P05 代理驗證自己的工作 P06 建構完整的 harness- (畢業專案)-```--如果你是兼職學習,每個階段大約需要一週。如果你想加快速度,階段 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- 專案演進- ========-- P01 僅提示 vs. 規則優先 你看見問題- |- v- P02 代理可讀的工作空間 你重構儲存庫- |- v- P03 多工作階段連續性 你連接工作階段- |- v- P04 執行時回饋與範圍控制 你加入回饋迴圈- |- v- P05 自我驗證 你讓代理檢查自己- |- v- P06 完整 harness(畢業專案) 你建構完整系統-- 每個專案的 solution 成為下一個專案的 starter。- 應用程式在演化。你的 harness 技能也隨之成長。-```--### 資源庫--- [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- 代理工作階段生命週期- ===================-- ┌──────────────────────────────────────────────────────────────────┐- │ 開始 │- │ │- │ 1. 代理讀取 AGENTS.md / CLAUDE.md │- │ 2. 代理執行 init.sh(安裝、驗證、健康檢查) │- │ 3. 代理讀取 claude-progress.md(上次發生了什麼事) │- │ 4. 代理讀取 feature_list.json(什麼已完成,什麼是下一步) │- │ 5. 代理檢查 git log(最近的變更) │- │ │- │ 選擇 │- │ │- │ 6. 代理精確挑選一個未完成的功能 │- │ 7. 代理只做那個功能 │- │ │- │ 執行 │- │ │- │ 8. 代理實作該功能 │- │ 9. 代理執行驗證(測試、lint、型別檢查) │- │ 10. 如果驗證失敗:修復並重新執行 │- │ 11. 如果驗證通過:記錄證據 │- │ │- │ 收尾 │- │ │- │ 12. 代理更新 claude-progress.md │- │ 13. 代理更新 feature_list.json │- │ 14. 代理記錄仍然損壞或未驗證的部分 │- │ 15. 代理提交(只在可安全恢復時) │- │ 16. 代理為下一個工作階段留下乾淨的重啟路徑 │- │ │- └──────────────────────────────────────────────────────────────────┘-- Harness 管控這個生命週期中的每個轉換。- 模型決定在每個步驟寫什麼程式碼。- 沒有 harness 時,步驟 9 變成「代理說看起來沒問題」。- 有了 harness 時,步驟 9 是「測試通過、lint 乾淨、型別檢查通過」。-```-------## 適合什麼人--這門課程適合:--- 已在使用程式設計代理並希望獲得更好穩定性與品質的工程師-- 希望系統性理解 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-readme/README.md b/docs-readme/README.mdnew file mode 100644index 0000000..d3b2c35--- /dev/null+++ b/docs-readme/README.md@@ -0,0 +1,20 @@+# README Translations++The main project README stays at the repository root:++- [English](../README.md)++Translated README files live in this directory:++- [简体中文](zh-CN/README.md)+- [繁體中文](zh-TW/README.md)+- [日本語](ja-JP/README.md)+- [한국어](ko-KR/README.md)+- [Español](es-ES/README.md)+- [Français](fr-FR/README.md)+- [Русский](ru-RU/README.md)+- [Deutsch](de-DE/README.md)+- [العربية](ar-SA/README.md)+- [Tiếng Việt](vi-VN/README.md)+- [Oʻzbekcha](uz-UZ/README.md)+- [Türkçe](tr-TR/README.md)diff --git a/docs/ar/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/ar/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex cdf7640..f0a6188 100644--- a/docs/ar/lectures/lecture-01-why-capable-agents-still-fail/index.md+++ b/docs/ar/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -17,9 +17,9 @@أجرت Anthropic تجربة مضبوطة. المطالبة نفسها ("ابنِ صانع ألعاب ريترو ثنائية الأبعاد")، والنموذج نفسه (Opus 4.5). التشغيل الأول: عارٍ بلا دعم - 20 دقيقة، 9 دولارات، والميزات الأساسية للعبة لم تعمل إطلاقًا. التشغيل الثاني: Harness كامل (مخطط + مولد + مقيم في بنية من ثلاثة وكلاء) - 6 ساعات، 200 دولار، وأصبحت اللعبة قابلة للعب.-لم يغيروا النموذج. بقي Opus 4.5 هو Opus 4.5. ما تغيّر هو السرج.+لم يغيروا النموذج. بقي Opus 4.5 هو Opus 4.5. ما تغيّر هو العدة الكاملة للفرس.-مقال OpenAI لعام 2025 عن هندسة الـ Harness يقولها بوضوح: ينتقل Codex في مستودع مجهز جيدًا بالـ Harness من "غير موثوق" إلى "موثوق". لاحظ الصياغة - ليست "أفضل قليلًا"، بل انتقال نوعي. مثل حصان أصيل: يمكنك ركوبه بلا سرج، لكنك لن تذهب بعيدًا، ولن تتحرك بسرعة، والسقوط لن يكون مفاجأة. الـ Harness هو ذلك السرج - **كل ما في البنية الهندسية خارج أوزان النموذج.**+مقال OpenAI لعام 2025 عن هندسة الـ Harness يقولها بوضوح: ينتقل Codex في مستودع مجهز جيدًا بالـ Harness من "غير موثوق" إلى "موثوق". لاحظ الصياغة - ليست "أفضل قليلًا"، بل انتقال نوعي. مثل حصان أصيل: يمكنك ركوبه بلا عدة مناسبة، لكنك لن تذهب بعيدًا، ولن تتحرك بسرعة، والسقوط لن يكون مفاجأة. الـ Harness هو تلك العدة الكاملة - **كل ما في البنية الهندسية خارج أوزان النموذج.**## أين تتعطل الوكلاء فعليًا@@ -40,7 +40,7 @@مع هذه السيناريوهات في الذهن، لم تعد هذه المفاهيم مجرد مصطلحات:- **Capability Gap**: الفجوة الكبيرة بين أداء النموذج على المعايير القياسية وأدائه في المهام الحقيقية. معدل نجاح 50-60% على SWE-bench Verified يعني أن قرابة نصف القضايا الحقيقية لا تُحل.-- **Harness**: كل ما هو خارج النموذج - التعليمات، الأدوات، البيئة، إدارة الحالة، وتغذية التحقق الراجعة. إن لم يكن من أوزان النموذج فهو جزء من الـ Harness. هذا هو "السرج" الذي نتحدث عنه.+- **Harness**: كل ما هو خارج النموذج - التعليمات، الأدوات، البيئة، إدارة الحالة، وتغذية التحقق الراجعة. إن لم يكن من أوزان النموذج فهو جزء من الـ Harness. هذه هي "العدة الكاملة" التي نتحدث عنها.- **Harness-Induced Failure**: لدى النموذج قدرة كافية، لكن بيئة التنفيذ فيها عيوب بنيوية. تجربة Anthropic المضبوطة أثبتت ذلك بالفعل.- **Verification Gap**: الفجوة بين ثقة الوكيل في مخرجاته والصحة الفعلية. يقول الوكيل "انتهيت" وهو لم ينتهِ - وهذا هو نمط الفشل الأكثر شيوعًا.- **Diagnostic Loop**: نفّذ، لاحظ الفشل، انسبه إلى طبقة Harness محددة، أصلح تلك الطبقة، ثم نفّذ مرة أخرى. هذه هي المنهجية الأساسية لهندسة الـ Harness.@@ -52,7 +52,7 @@خطوات عملية:-**انسب كل فشل إلى طبقة محددة.** لا تقل فقط "النموذج سيئ". اسأل: هل كانت المهمة غير واضحة؟ هل كان السياق غير كافٍ؟ هل لم تكن هناك وسائل تحقق؟ اربط كل فشل بإحدى طبقات الفشل الخمس: مواصفة المهمة، تزويد السياق، بيئة التنفيذ، تغذية التحقق الراجعة، وإدارة الحالة. ابنِ هذه العادة، وستجد أن عبارة "النموذج ليس جيدًا بما يكفي" تظهر أقل فأقل في سجلاتك.+**انسب كل فشل إلى طبقة محددة.** لا تقل فقط "النموذج سيئ". اسأل: هل كانت المهمة غير واضحة؟ هل كان السياق غير كافٍ؟ هل لم تكن هناك وسائل تحقق؟ اربط كل فشل بإحدى طبقات الفشل الخمس: مواصفة المهمة، تزويد السياق، بيئة التنفيذ، تغذية التحقق الراجعة، وإدارة الحالة. هذه طبقات تشخيص عملية، وليست المصطلحات الستة في المسرد أعلاه. ابنِ هذه العادة، وستجد أن عبارة "النموذج ليس جيدًا بما يكفي" تظهر أقل فأقل في سجلاتك.**اكتب Definition of Done صريحة لكل مهمة.** لا تقل "أضف ميزة بحث". قل:```@@ -94,7 +94,7 @@ Completion criteria:## الخلاصات الأساسية-- قدرة النموذج وموثوقية التنفيذ شيئان مختلفان. حتى الحصان الأصيل يحتاج إلى سرج جيد.+- قدرة النموذج وموثوقية التنفيذ شيئان مختلفان. حتى الحصان الأصيل يحتاج إلى عدة جيدة.- عندما تفشل الأمور، افحص الـ Harness أولًا ثم النموذج. تبديل النماذج هو الخيار الأغلى - وغالبًا ليست المشكلة في النموذج أصلًا.- كل فشل إشارة: لدى الـ Harness عيب بنيوي. اعثر عليه وأصلحه.- خمس طبقات دفاع: مواصفة المهمة، تزويد السياق، بيئة التنفيذ، تغذية التحقق الراجعة، وإدارة الحالة. افحصها بشكل منهجي، كما يستبعد الطبيب الأسباب الأكثر شيوعًا أولًا.diff --git a/docs/ar/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/ar/lectures/lecture-02-what-a-harness-actually-is/index.mdindex 7996183..cb85336 100644--- a/docs/ar/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/ar/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -33,7 +33,7 @@- **المستودع هو المصدر الوحيد للحقيقة**: أي شيء لا يستطيع الوكيل رؤيته، لجميع الأغراض العملية، غير موجود. تتعامل OpenAI مع المستودع بصفته "سجل النظام" — يجب أن يعيش فيه كل السياق الضروري، من خلال ملفات منظمة وتنظيم واضح للأدلة.- **أعطِ خريطة، لا دليلًا**: تجربة OpenAI — يجب أن يكون `AGENTS.md` صفحة فهرس، لا موسوعة. حوالي 100 سطر كافية. إذا لم تكف، قسّمها إلى دليل `docs/` ودع الوكيل يقرأ عند الحاجة.- **قيّد، لا تُدارة بالتفصيل**: harness الجيد يستخدم قواعد قابلة للتنفيذ لتقييد الوكيل، بدلاً من تعداد التعليمات واحدة تلو الأخرى. تقول OpenAI "فرض الثوابت، لا تُدارة التنفيذ"؛ ووجدت Anthropic أن الوكلاء يمدحون عملهم بثقة، والحل هو فصل "من يقوم بالعمل" عن "من يتحقق من العمل."-- **أزل المكونات واحدًا تلو الآخر**: لقياس قيمة كل مكون من مكونات harness، أزلها واحدًا تلو الآخر وانظر أي إزالة تسبب أكبر انخفاض في الأداء. استخدمت Anthropic هذه الطريقة ووجدت أنه مع قوة النماذج، تتوقف بعض المكونات عن كونها حرجة — لكن جديدة تظهر دائمًا.+- **أزل المكونات واحدًا تلو الآخر**: لقياس المساهمة الحدية لكل مكون من مكونات harness، أزلها واحدًا تلو الآخر وانظر أي إزالة تسبب أكبر انخفاض في الأداء. استخدمت Anthropic هذه الطريقة ووجدت أنه مع قوة النماذج، تتوقف بعض المكونات عن كونها حرجة — لكن جديدة تظهر دائمًا.## نموذج harness ذو الأنظمة الفرعية الخمسة@@ -68,7 +68,7 @@ Verification commands:غياب أي نظام فرعي يشبه غياب منطقة وظيفية في المطبخ — لا يزال بإمكانك الطبخ، لكن الأمر دائمًا محرج.-**تشخيص جودة harness**: استخدم "التحكم المتساوي للنموذج." أبقِ النموذج ثابتًا، وأزل الأنظمة الفرعية واحدًا تلو الآخر، وقِس أي إزالة تسبب أكبر انخفاض في الأداء. هذا هو عنق الزجاجة الخاص بك — ركّز جهدك هناك. مثل البحث عن عنق الزجاجة في المطبخ: خذ رف الوصفات وانظر كم يصبح الأمر أبطأ، أطفئ الموقد وانظر التأثير.+**قياس قيمة مكونات harness**: استخدم "التحكم المتساوي للنموذج." أبقِ النموذج ثابتًا، وأزل الأنظمة الفرعية واحدًا تلو الآخر، وقِس أي إزالة تسبب أكبر انخفاض في الأداء. أكبر انخفاض يحدد المكون صاحب أعلى مساهمة حدية في تلك المهمة، وليس بالضرورة عنق الزجاجة. لتحديد عنق الزجاجة الحقيقي، اجمع هذه التجربة مع سجلات الفشل ونسب الأسباب: مهمة غير واضحة، سياق غير كافٍ، بيئة غير قابلة لإعادة الإنتاج، غياب تغذية التحقق الراجعة، أو انقطاع إدارة الحالة.## قصة فريق حقيقية@@ -89,7 +89,7 @@ Verification commands:- Harness = تعليمات + أدوات + بيئة + حالة + تغذية راجعة. خمسة أنظمة فرعية، مثل المناطق الوظيفية الخمس للمطبخ — جميعها أساسية.- إذا لم تكن أوزان النموذج، فهي harness. إن harness الخاص بك يحدد مقدار ما يتحقق من قدرات النموذج.- من بين الأنظمة الفرعية الخمسة، عادةً ما يكون نظام التغذية الراجعة هو الأقل استثمارًا والأعلى عائدًا. اجعل أوامر التحقق صحيحة أولاً — نافذة فحص الجودة هي الترقية الأكثر جدوى بالاستثمار.-- استخدم "التحكم المتساوي للنموذج" لقياس المساهمة الحدية لكل نظام فرعي — لا تعتمد على الحدس.+- استخدم "التحكم المتساوي للنموذج" لقياس المساهمة الحدية لكل نظام فرعي؛ واستخدم سجلات الفشل ونسب الأسباب لتحديد عنق الزجاجة الحقيقي.- harness يتآكل مثل الكود. راجع بانتظام، وسدد ديون harness كما تسدد الديون التقنية.## قراءات إضافيةdiff --git a/docs/de/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/de/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex e0b04da..574863f 100644--- a/docs/de/lectures/lecture-01-why-capable-agents-still-fail/index.md+++ b/docs/de/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -17,9 +17,9 @@ Hinter diesen Zahlen steckt aber eine kontraintuitive Wahrheit.Anthropic führte ein kontrolliertes Experiment durch. Gleicher Prompt ("baue einen 2D-Retro-Game-Maker"), gleiches Modell (Opus 4.5). Erster Lauf: nackt, ohne Unterstützung - 20 Minuten, 9 Dollar, die Kernfunktionen des Spiels funktionierten überhaupt nicht. Zweiter Lauf: vollständiger Harness (Planner + Generator + Evaluator als Drei-Agenten-Architektur) - 6 Stunden, 200 Dollar, das Spiel war spielbar.-Sie änderten nicht das Modell. Opus 4.5 blieb Opus 4.5. Was sich änderte, war der Sattel.+Sie änderten nicht das Modell. Opus 4.5 blieb Opus 4.5. Was sich änderte, war das Zaumzeug.-OpenAIs Artikel zu Harness Engineering aus dem Jahr 2025 formuliert es direkt: Codex wechselt in einem gut geharnessten Repository von "unzuverlässig" zu "zuverlässig". Achte auf die Wortwahl - nicht "ein bisschen besser", sondern ein qualitativer Sprung. Wie bei einem Vollblutpferd: Du kannst ohne Sattel reiten, aber du kommst nicht weit, nicht schnell, und ein Sturz ist keine Überraschung. Der Harness ist dieser Sattel - **alles in der Engineering-Infrastruktur außerhalb der Modellgewichte.**+OpenAIs Artikel zu Harness Engineering aus dem Jahr 2025 formuliert es direkt: Codex wechselt in einem gut geharnessten Repository von "unzuverlässig" zu "zuverlässig". Achte auf die Wortwahl - nicht "ein bisschen besser", sondern ein qualitativer Sprung. Wie bei einem Vollblutpferd: Du kannst ohne passendes Zaumzeug reiten, aber du kommst nicht weit, nicht schnell, und ein Sturz ist keine Überraschung. Der Harness ist dieses gesamte Zaumzeug - **alles in der Engineering-Infrastruktur außerhalb der Modellgewichte.**## Wo Agenten tatsächlich stecken bleiben@@ -40,7 +40,7 @@ Lange Aufgaben über mehrere Sitzungen sind noch schlimmer: Alle Erkenntnisse auMit diesen Szenarien im Hinterkopf sind die folgenden Begriffe kein bloßer Jargon mehr:- **Capability Gap**: Die große Lücke zwischen Modellleistung auf Benchmarks und Leistung bei realen Aufgaben. Eine Erfolgsrate von 50-60% auf SWE-bench Verified bedeutet, dass fast die Hälfte realer Issues nicht gelöst wird.-- **Harness**: Alles außerhalb des Modells - Anweisungen, Tools, Umgebung, Zustandsverwaltung, Verifikationsfeedback. Wenn es keine Modellgewichte sind, gehört es zum Harness. Das ist der "Sattel", von dem wir gesprochen haben.+- **Harness**: Alles außerhalb des Modells - Anweisungen, Tools, Umgebung, Zustandsverwaltung, Verifikationsfeedback. Wenn es keine Modellgewichte sind, gehört es zum Harness. Das ist das "Zaumzeug", von dem wir gesprochen haben.- **Harness-Induced Failure**: Das Modell hat grundsätzlich genug Fähigkeit, aber die Ausführungsumgebung hat strukturelle Defekte. Anthropics kontrolliertes Experiment hat genau das gezeigt.- **Verification Gap**: Die Lücke zwischen dem Vertrauen des Agenten in sein Ergebnis und der tatsächlichen Korrektheit. Der Agent sagt "ich bin fertig", obwohl er nicht fertig ist - der häufigste Fehlermodus.- **Diagnostic Loop**: Ausführen, Fehler beobachten, einer bestimmten Harness-Schicht zuordnen, diese Schicht reparieren, erneut ausführen. Das ist die Kernmethodik von Harness Engineering.@@ -52,7 +52,7 @@ Kernprinzip: **Wenn etwas scheitert, tausche nicht zuerst das Modell aus - prüfKonkrete Schritte:-**Ordne jeden Fehler einer bestimmten Schicht zu.** Sag nicht nur "das Modell taugt nichts". Frage: War die Aufgabe unklar? War der Kontext unzureichend? Gab es keine Verifikationsmethode? Ordne jeden Fehler einer der fünf Fehlerschichten zu: Aufgabenspezifikation, Kontextbereitstellung, Ausführungsumgebung, Verifikationsfeedback, Zustandsverwaltung. Wenn du diese Gewohnheit aufbaust, wirst du "das Modell ist nicht gut genug" immer seltener in deinen Logs sehen.+**Ordne jeden Fehler einer bestimmten Schicht zu.** Sag nicht nur "das Modell taugt nichts". Frage: War die Aufgabe unklar? War der Kontext unzureichend? Gab es keine Verifikationsmethode? Ordne jeden Fehler einer der fünf Fehlerschichten zu: Aufgabenspezifikation, Kontextbereitstellung, Ausführungsumgebung, Verifikationsfeedback, Zustandsverwaltung. Das sind praktische Diagnoseschichten, nicht die sechs Glossarbegriffe oben. Wenn du diese Gewohnheit aufbaust, wirst du "das Modell ist nicht gut genug" immer seltener in deinen Logs sehen.**Schreibe für jede Aufgabe eine explizite Definition of Done.** Sag nicht "füge eine Suchfunktion hinzu". Sag:```@@ -94,7 +94,7 @@ Sie änderten nicht das Modell. Sie änderten den Harness.## Wichtigste Erkenntnisse-- Modellfähigkeit und Ausführungszuverlässigkeit sind verschiedene Dinge. Auch ein Vollblut braucht einen guten Sattel.+- Modellfähigkeit und Ausführungszuverlässigkeit sind verschiedene Dinge. Auch ein Vollblut braucht gutes Zaumzeug.- Wenn etwas scheitert, prüfe zuerst den Harness und dann das Modell. Modelle zu wechseln ist die teuerste Option - und oft ist es nicht einmal ein Modellproblem.- Jeder Fehler ist ein Signal: Dein Harness hat einen strukturellen Defekt. Finde ihn und behebe ihn.- Fünf Verteidigungsschichten: Aufgabenspezifikation, Kontextbereitstellung, Ausführungsumgebung, Verifikationsfeedback, Zustandsverwaltung. Prüfe sie systematisch, wie ein Arzt die häufigsten Ursachen zuerst ausschließt.diff --git a/docs/de/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/de/lectures/lecture-02-what-a-harness-actually-is/index.mdindex 6487c57..8f089f6 100644--- a/docs/de/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/de/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -33,7 +33,7 @@ Betrachten Sie einige Tools, die Sie bereits kennen:- **Das Repo ist die einzige Quelle der Wahrheit**: Alles, was der Agent nicht sehen kann, existiert für alle praktischen Zwecke nicht. OpenAI behandelt das Repo als „system of record" — der gesamte notwendige Kontext muss dort leben, durch strukturierte Dateien und klare Verzeichnisorganisation.- **Eine Karte geben, kein Handbuch**: OpenAIs Erfahrung — `AGENTS.md` sollte eine Übersichtsseite sein, keine Enzyklopädie. Etwa 100 Zeilen reichen aus. Wenn es nicht passt, teilen Sie es in das `docs/`-Verzeichnis auf und lassen Sie den Agenten bei Bedarf lesen.- **Einschränken, nicht mikroverwalten**: Ein gutes harness verwendet ausführbare Regeln, um den Agenten einzuschränken, anstatt Anweisungen einzeln aufzuzählen. OpenAI sagt „enforce invariants, don't micromanage implementation"; Anthropic hat festgestellt, dass Agenten ihre eigene Arbeit zuversichtlich loben, und die Lösung darin besteht, „die Person, die die Arbeit erledigt" von „der Person, die die Arbeit prüft" zu trennen.-- **Komponenten einzeln entfernen**: Um den Wert jeder harness-Komponente zu quantifizieren, entfernen Sie sie einzeln und prüfen Sie, welche Entfernung den größten Leistungsabfall verursacht. Anthropic hat diese Methode angewandt und festgestellt, dass mit stärker werdenden Modellen einige Komponenten aufhören, kritisch zu sein — aber neue tauchen immer auf.+- **Komponenten einzeln entfernen**: Um den Grenzbeitrag jeder harness-Komponente zu quantifizieren, entfernen Sie sie einzeln und prüfen Sie, welche Entfernung den größten Leistungsabfall verursacht. Anthropic hat diese Methode angewandt und festgestellt, dass mit stärker werdenden Modellen einige Komponenten aufhören, kritisch zu sein — aber neue tauchen immer auf.## Das Fünf-Subsystem-harness-Modell@@ -68,7 +68,7 @@ Verification commands:Wenn ein Subsystem fehlt, ist das wie ein fehlender Funktionsbereich in der Küche — Sie können immer noch kochen, aber es ist immer umständlich.-**harness-Qualität diagnostizieren**: Verwenden Sie „isometrische Modellkontrolle". Halten Sie das Modell fest, entfernen Sie Subsysteme einzeln, messen Sie, welche Entfernung den größten Leistungsabfall verursacht. Das ist Ihr Engpass — konzentrieren Sie Ihre Mühe darauf. Wie bei der Suche nach dem Engpass in einer Küche: Nehmen Sie das Rezeptregal weg und sehen Sie, wie viel langsamer alles wird, schalten Sie den Herd ab und beobachten Sie die Auswirkungen.+**Wert von harness-Komponenten quantifizieren**: Verwenden Sie „isometrische Modellkontrolle". Halten Sie das Modell fest, entfernen Sie Subsysteme einzeln und messen Sie, welche Entfernung den größten Leistungsabfall verursacht. Der größte Abfall zeigt die Komponente mit dem höchsten Grenzbeitrag in dieser Aufgabe, nicht automatisch den Engpass. Um den Engpass zu finden, kombinieren Sie das Experiment mit Fehlerprotokollen und Attribution: unklare Aufgabe, zu wenig Kontext, nicht reproduzierbare Umgebung, fehlendes Verifikationsfeedback oder gebrochene Zustandsverwaltung.## Die wahre Geschichte eines Teams@@ -89,7 +89,7 @@ Vier Iterationen, das Modell hat sich gar nicht geändert, die Erfolgsquote stie- Harness = Instructions + Tools + Environment + State + Feedback. Fünf Subsysteme, wie die fünf Funktionsbereiche einer Küche — alle unverzichtbar.- Wenn es keine Modellgewichte sind, ist es harness. Ihr harness bestimmt, wie viel der Modelfähigkeiten realisiert wird.- Unter den fünf Subsystemen hat das Feedback-Subsystem normalerweise die geringste Investition und die höchste Rendite. Bringen Sie zuerst Ihre Verifizierungsbefehle in Ordnung — das Qualitätskontrollfenster ist das lohnendste Upgrade.-- Verwenden Sie „isometrische Modellkontrolle", um den Grenznutzen jedes Subsystems zu quantifizieren — gehen Sie nicht nach Bauchgefühl.+- Verwenden Sie „isometrische Modellkontrolle", um den Grenzbeitrag jedes Subsystems zu quantifizieren; nutzen Sie Fehlerprotokolle und Attribution, um den echten Engpass zu finden.- Harness verrottet wie Code. Überprüfen Sie regelmäßig und tilgen Sie harness-Schulden wie Sie technische Schulden tilgen.## Weiterführende Literaturdiff --git a/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex 5646231..81719cf 100644--- a/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md+++ b/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -17,9 +17,9 @@ But behind these numbers lies a counterintuitive truth.Anthropic ran a controlled experiment. Same prompt ("build a 2D retro game maker"), same model (Opus 4.5). First run: bare, no support — 20 minutes, $9, the game's core features didn't work at all. Second run: full harness (planner + generator + evaluator three-agent architecture) — 6 hours, $200, the game was playable.-They didn't change the model. Opus 4.5 was still Opus 4.5. What changed was the saddle.+They didn't change the model. Opus 4.5 was still Opus 4.5. What changed was the tack.-OpenAI's 2025 harness engineering article puts it plainly: Codex in a well-harnessed repository goes from "unreliable" to "reliable." Note their wording — not "a bit better," but a qualitative shift. Like a thoroughbred: you can ride it without a saddle, but you won't go far, won't go fast, and falling off is no surprise. The harness is that saddle — **everything in the engineering infrastructure outside the model weights.**+OpenAI's 2025 harness engineering article puts it plainly: Codex in a well-harnessed repository goes from "unreliable" to "reliable." Note their wording — not "a bit better," but a qualitative shift. Like a thoroughbred: you can ride it without proper tack, but you won't go far, won't go fast, and falling off is no surprise. The harness is that full set of tack — **everything in the engineering infrastructure outside the model weights.**## Where Agents Actually Get Stuck@@ -40,7 +40,7 @@ Long tasks spanning sessions are even worse — all discoveries from the previouWith these scenarios in mind, these concepts are no longer just jargon:- **Capability Gap**: The huge gulf between model performance on benchmarks and performance on real tasks. A 50-60% pass rate on SWE-bench Verified means nearly half of real issues can't be resolved.-- **Harness**: Everything outside the model — instructions, tools, environment, state management, verification feedback. If it's not model weights, it's harness. What we've been calling the "saddle."+- **Harness**: Everything outside the model — instructions, tools, environment, state management, verification feedback. If it's not model weights, it's harness. What we've been calling the "tack."- **Harness-Induced Failure**: The model has enough capability, but the execution environment has structural defects. Anthropic's controlled experiment already proved this.- **Verification Gap**: The gap between the agent's confidence in its output and actual correctness. The agent says "I'm done" when it's not done — this is the most common failure mode.- **Diagnostic Loop**: Execute, observe failure, attribute to a specific harness layer, fix that layer, re-execute. This is the core methodology of harness engineering.@@ -52,7 +52,7 @@ Core principle: **When things fail, don't swap the model first — check the harConcrete steps:-**Attribute every failure to a specific layer.** Don't just say "the model sucks." Ask: was the task unclear? Was context insufficient? Were there no verification methods? Map each failure to one of the five failure layers (task specification, context provision, execution environment, verification feedback, state management). Build this habit, and you'll find "the model isn't good enough" appearing less and less in your logs.+**Attribute every failure to a specific layer.** Don't just say "the model sucks." Ask: was the task unclear? Was context insufficient? Were there no verification methods? Map each failure to one of the five failure layers: task specification, context provision, execution environment, verification feedback, and state management. These are the practical diagnostic layers, not the six glossary terms above. Build this habit, and you'll find "the model isn't good enough" appearing less and less in your logs.**Write an explicit Definition of Done for every task.** Don't say "add a search feature." Say:```@@ -94,7 +94,7 @@ They didn't change the model. They changed the harness.## Key Takeaways-- Model capability and execution reliability are different things. A thoroughbred still needs a good saddle.+- Model capability and execution reliability are different things. A thoroughbred still needs good tack.- When things fail, check the harness first, then the model. Swapping models is the most expensive option — and often it's not even a model problem.- Every failure is a signal: your harness has a structural defect. Find it, fix it.- Five defense layers: task specification, context provision, execution environment, verification feedback, state management. Check them systematically, like a doctor ruling out the most common causes first.diff --git a/docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/en/lectures/lecture-02-what-a-harness-actually-is/index.mdindex bbeaebf..7567324 100644--- a/docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -33,7 +33,7 @@ Look at some tools you already know:- **The repo is the single source of truth**: Anything the agent can't see, for all practical purposes, doesn't exist. OpenAI treats the repo as the "system of record" — all necessary context must live there, through structured files and clear directory organization.- **Give a map, not a manual**: OpenAI's experience — `AGENTS.md` should be a directory page, not an encyclopedia. Around 100 lines is enough. If it doesn't fit, split it into the `docs/` directory and let the agent read on demand.- **Constrain, don't micromanage**: A good harness uses executable rules to constrain the agent, rather than enumerating instructions one by one. OpenAI says "enforce invariants, don't micromanage implementation"; Anthropic found that agents confidently praise their own work, and the solution is to separate "the person who does the work" from "the person who checks the work."-- **Remove components one at a time**: To quantify the value of each harness component, remove them one at a time and see which removal causes the biggest performance drop. Anthropic used this method and found that as models get stronger, some components stop being critical — but new ones always emerge.+- **Remove components one at a time**: To quantify each harness component's marginal contribution, remove them one at a time and see which removal causes the biggest performance drop. Anthropic used this method and found that as models get stronger, some components stop being critical — but new ones always emerge.## The Five-Subsystem Harness Model@@ -68,7 +68,7 @@ Verification commands:Missing any subsystem is like missing a functional area in the kitchen — you can still cook, but it's always awkward.-**Diagnosing harness quality**: Use "isometric model control." Keep the model fixed, remove subsystems one at a time, measure which removal causes the biggest performance drop. That's your bottleneck — focus your effort there. Like finding the bottleneck in a kitchen: take away the recipe shelf and see how much slower things get, shut off the stove and see the impact.+**Quantifying harness component value**: Use "isometric model control." Keep the model fixed, remove subsystems one at a time, and measure which removal causes the biggest performance drop. The largest drop identifies the component with the highest marginal contribution in that task, not automatically the bottleneck. To locate the bottleneck, combine this experiment with failure logs and attribution: unclear task, insufficient context, unreproducible environment, missing verification feedback, or broken state management.## A Team's Real Story@@ -89,7 +89,7 @@ Four iterations, the model didn't change at all, success rate went from 20% to n- Harness = Instructions + Tools + Environment + State + Feedback. Five subsystems, like a kitchen's five functional areas — all essential.- If it's not model weights, it's harness. Your harness determines how much model capability gets realized.- Among the five subsystems, the feedback subsystem usually has the lowest investment and highest return. Get your verification commands right first — the quality check window is the most worthwhile upgrade.-- Use "isometric model control" to quantify each subsystem's marginal contribution — don't go by gut feeling.+- Use "isometric model control" to quantify each subsystem's marginal contribution — don't go by gut feeling; use failure logs and attribution to locate the real bottleneck.- Harness rots like code does. Audit regularly, pay down harness debt like you pay down technical debt.## Further Readingdiff --git a/docs/es/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/es/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex 9620608..54e32a9 100644--- a/docs/es/lectures/lecture-01-why-capable-agents-still-fail/index.md+++ b/docs/es/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -17,9 +17,9 @@ Pero detrás de estos números hay una verdad contraintuitiva.Anthropic realizó un experimento controlado. Mismo prompt ("construye un creador de juegos retro 2D"), mismo modelo (Opus 4.5). Primera ejecución: sin apoyo, sin harness — 20 minutos, 9 dólares, las funciones centrales del juego no funcionaban. Segunda ejecución: harness completo, con arquitectura de tres agentes planner + generator + evaluator — 6 horas, 200 dólares, el juego era jugable.-No cambiaron el modelo. Opus 4.5 seguía siendo Opus 4.5. Lo que cambió fue la silla de montar.+No cambiaron el modelo. Opus 4.5 seguía siendo Opus 4.5. Lo que cambió fue el equipo de monta.-El artículo de OpenAI sobre harness engineering lo dice con claridad: Codex en un repositorio bien harnessed pasa de "poco fiable" a "fiable". Fíjate en el lenguaje: no es "un poco mejor", sino un cambio cualitativo. Como un caballo pura sangre: puedes montarlo sin silla, pero no llegarás lejos, no irás rápido y caerte no será una sorpresa. El harness es esa silla: **todo lo que existe en la infraestructura de ingeniería fuera de los pesos del modelo.**+El artículo de OpenAI sobre harness engineering lo dice con claridad: Codex en un repositorio bien harnessed pasa de "poco fiable" a "fiable". Fíjate en el lenguaje: no es "un poco mejor", sino un cambio cualitativo. Como un caballo pura sangre: puedes montarlo sin equipo de monta adecuado, pero no llegarás lejos, no irás rápido y caerte no será una sorpresa. El harness es ese conjunto completo de equipo: **todo lo que existe en la infraestructura de ingeniería fuera de los pesos del modelo.**## Dónde se atascan realmente los agentes@@ -40,7 +40,7 @@ Las tareas largas que cruzan sesiones son aún peores: los descubrimientos de laCon estos escenarios en mente, estos conceptos ya no son jerga:- **Brecha de capacidad**: la distancia enorme entre el rendimiento del modelo en benchmarks y su rendimiento en tareas reales. Un 50-60% en SWE-bench Verified significa que casi la mitad de los issues reales no se resuelven.-- **Harness**: todo lo que está fuera del modelo: instrucciones, herramientas, entorno, gestión de estado y feedback de verificación. Si no son pesos del modelo, es harness. Es la "silla de montar" de la que hablamos.+- **Harness**: todo lo que está fuera del modelo: instrucciones, herramientas, entorno, gestión de estado y feedback de verificación. Si no son pesos del modelo, es harness. Es el "equipo de monta" del que hablamos.- **Fallo inducido por harness**: el modelo tiene capacidad suficiente, pero el entorno de ejecución tiene defectos estructurales. El experimento controlado de Anthropic ya lo demostró.- **Brecha de verificación**: la diferencia entre la confianza del agente en su salida y la corrección real. El agente dice "terminé" cuando no terminó. Es el modo de fallo más común.- **Bucle diagnóstico**: ejecutar, observar el fallo, atribuirlo a una capa concreta del harness, corregir esa capa y volver a ejecutar. Es la metodología central del harness engineering.@@ -52,7 +52,7 @@ Principio central: **cuando algo falla, no cambies primero el modelo; revisa elPasos concretos:-**Atribuye cada fallo a una capa específica.** No digas simplemente "el modelo es malo". Pregunta: ¿la tarea era poco clara?, ¿faltaba contexto?, ¿no había métodos de verificación? Mapea cada fallo a una de las cinco capas: especificación de tarea, provisión de contexto, entorno de ejecución, feedback de verificación y gestión de estado. Si construyes este hábito, verás cada vez menos "el modelo no es suficiente" en tus registros.+**Atribuye cada fallo a una capa específica.** No digas simplemente "el modelo es malo". Pregunta: ¿la tarea era poco clara?, ¿faltaba contexto?, ¿no había métodos de verificación? Mapea cada fallo a una de las cinco capas: especificación de tarea, provisión de contexto, entorno de ejecución, feedback de verificación y gestión de estado. Estas son capas diagnósticas prácticas, no los seis términos del glosario anterior. Si construyes este hábito, verás cada vez menos "el modelo no es suficiente" en tus registros.**Escribe una Definition of Done explícita para cada tarea.** No digas "añade búsqueda". Di:```@@ -94,7 +94,7 @@ No cambiaron el modelo. Cambiaron el harness.## Ideas clave-- Capacidad del modelo y fiabilidad de ejecución son cosas distintas. Un pura sangre también necesita buena silla.+- Capacidad del modelo y fiabilidad de ejecución son cosas distintas. Un pura sangre también necesita buen equipo de monta.- Cuando algo falla, revisa primero el harness y luego el modelo. Cambiar de modelo es la opción más cara, y muchas veces ni siquiera es un problema del modelo.- Cada fallo es una señal: tu harness tiene un defecto estructural. Encuéntralo y arréglalo.- Cinco capas defensivas: especificación de tarea, provisión de contexto, entorno de ejecución, feedback de verificación y gestión de estado. Revísalas de forma sistemática.diff --git a/docs/es/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/es/lectures/lecture-02-what-a-harness-actually-is/index.mdindex 0fb03c0..6ccff10 100644--- a/docs/es/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/es/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -33,7 +33,7 @@ Mira algunas herramientas que ya conoces:- **El repositorio es la única fuente de verdad**: Cualquier cosa que el agente no pueda ver, para todos los efectos prácticos, no existe. OpenAI trata el repositorio como el "sistema de registro" — todo el contexto necesario debe vivir ahí, a través de archivos estructurados y una organización clara de directorios.- **Da un mapa, no un manual**: La experiencia de OpenAI — `AGENTS.md` debería ser una página de directorio, no una enciclopedia. Alrededor de 100 líneas es suficiente. Si no cabe, divídelo en el directorio `docs/` y deja que el agente lea bajo demanda.- **Restringe, no microgestiones**: Un buen harness usa reglas ejecutables para restringir al agente, en lugar de enumerar instrucciones una por una. OpenAI dice "haz cumplir invariantes, no microgestiones la implementación"; Anthropic descubrió que los agentes elogian confiadamente su propio trabajo, y la solución es separar "la persona que hace el trabajo" de "la persona que revisa el trabajo."-- **Elimina componentes uno a la vez**: Para cuantificar el valor de cada componente del harness, elimínalos uno a la vez y observa cuál eliminación causa la mayor caída de rendimiento. Anthropic usó este método y descubrió que a medida que los modelos se vuelven más fuertes, algunos componentes dejan de ser críticos — pero siempre surgen nuevos.+- **Elimina componentes uno a la vez**: Para cuantificar la contribución marginal de cada componente del harness, elimínalos uno a la vez y observa cuál eliminación causa la mayor caída de rendimiento. Anthropic usó este método y descubrió que a medida que los modelos se vuelven más fuertes, algunos componentes dejan de ser críticos — pero siempre surgen nuevos.## El modelo de harness de cinco subsistemas@@ -68,7 +68,7 @@ Verification commands:Que falte cualquier subsistema es como que falte un área funcional en la cocina — todavía puedes cocinar, pero siempre será incómodo.-**Diagnosticando la calidad del harness**: Usa "control isométrico del modelo." Mantén el modelo fijo, elimina subsistemas uno a la vez, mide cuál eliminación causa la mayor caída de rendimiento. Ese es tu cuello de botella — enfoca tu esfuerzo ahí. Como encontrar el cuello de botella en una cocina: quita la estantería de recetas y mira cuánto más lento se vuelve todo, apaga la estufa y mira el impacto.+**Cuantificar el valor de los componentes del harness**: Usa "control isométrico del modelo." Mantén el modelo fijo, elimina subsistemas uno a la vez y mide cuál eliminación causa la mayor caída de rendimiento. La mayor caída identifica el componente con mayor contribución marginal en esa tarea, no automáticamente el cuello de botella. Para localizar el cuello de botella, combina el experimento con registros de fallos y atribución: tarea poco clara, contexto insuficiente, entorno no reproducible, falta de feedback de verificación o gestión de estado rota.## La historia real de un equipo@@ -89,7 +89,7 @@ Cuatro iteraciones, el modelo no cambió en absoluto, la tasa de éxito pasó de- Harness = Instrucciones + Herramientas + Entorno + Estado + Retroalimentación. Cinco subsistemas, como las cinco áreas funcionales de una cocina — todos esenciales.- Si no son pesos del modelo, es harness. Tu harness determina cuánta capacidad del modelo se realiza.- Entre los cinco subsistemas, el subsistema de retroalimentación suele tener la menor inversión y el mayor retorno. Configura bien tus comandos de verificación primero — la ventana de control de calidad es la mejora más valiosa.-- Usa "control isométrico del modelo" para cuantificar la contribución marginal de cada subsistema — no te guíes por la intuición.+- Usa "control isométrico del modelo" para cuantificar la contribución marginal de cada subsistema; usa registros de fallos y atribución para localizar el cuello de botella real.- El harness se degrada como el código. Audita regularmente, paga la deuda de harness como pagas la deuda técnica.## Lecturas adicionalesdiff --git a/docs/fr/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/fr/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex f894405..45bde6a 100644--- a/docs/fr/lectures/lecture-01-why-capable-agents-still-fail/index.md+++ b/docs/fr/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -17,9 +17,9 @@ Derrière ces chiffres se cache pourtant une vérité contre-intuitive.Anthropic a mené une expérience contrôlée. Même prompt (« construire un éditeur de jeux rétro 2D »), même modèle (Opus 4.5). Premier essai : nu, sans support — 20 minutes, 9 dollars, les fonctionnalités centrales ne fonctionnent pas. Deuxième essai : harness complet (architecture planner + generator + evaluator) — 6 heures, 200 dollars, le jeu est jouable.-Ils n'ont pas changé de modèle. Opus 4.5 restait Opus 4.5. Ce qui a changé, c'est la selle.+Ils n'ont pas changé de modèle. Opus 4.5 restait Opus 4.5. Ce qui a changé, c'est le harnachement.-L'article d'OpenAI sur le harness engineering le formule simplement : Codex dans un dépôt bien harnessed passe de « peu fiable » à « fiable ». Pas « un peu mieux », mais un changement qualitatif. Comme un pur-sang : vous pouvez le monter sans selle, mais vous n'irez ni loin ni vite, et tomber n'a rien d'étonnant. Le harness est cette selle : **tout ce qui, dans l'infrastructure d'ingénierie, se trouve hors des poids du modèle.**+L'article d'OpenAI sur le harness engineering le formule simplement : Codex dans un dépôt bien harnessed passe de « peu fiable » à « fiable ». Pas « un peu mieux », mais un changement qualitatif. Comme un pur-sang : vous pouvez le monter sans harnachement adapté, mais vous n'irez ni loin ni vite, et tomber n'a rien d'étonnant. Le harness est cet ensemble de harnachement : **tout ce qui, dans l'infrastructure d'ingénierie, se trouve hors des poids du modèle.**## Où les agents se bloquent vraiment@@ -48,7 +48,7 @@ Les tâches longues sur plusieurs sessions sont encore pires : les découvertesPrincipe central : **quand ça échoue, ne changez pas d'abord de modèle — vérifiez le harness.** Si le même modèle réussit sur des tâches similaires bien structurées, supposez un problème de harness. Comme une voiture en panne : on vérifie d'abord l'essence avant d'accuser le moteur.-**Attribuer chaque échec à une couche précise.** Ne dites pas « le modèle est nul ». Demandez : la tâche était-elle floue ? Le contexte insuffisant ? La vérification absente ? Reliez chaque échec à une des cinq couches : spécification, contexte, environnement, feedback de vérification, état.+**Attribuer chaque échec à une couche précise.** Ne dites pas « le modèle est nul ». Demandez : la tâche était-elle floue ? Le contexte insuffisant ? La vérification absente ? Reliez chaque échec à une des cinq couches : spécification, contexte, environnement, feedback de vérification, état. Ce sont des couches de diagnostic pratiques, pas les six termes du glossaire ci-dessus.**Écrire une Definition of Done explicite.**```diff --git a/docs/fr/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/fr/lectures/lecture-02-what-a-harness-actually-is/index.mdindex d62f5a5..3feee4f 100644--- a/docs/fr/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/fr/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -33,7 +33,7 @@ Regardez quelques outils que vous connaissez déjà :- **Le repo est l'unique source de vérité** : Tout ce que l'agent ne peut pas voir, en pratique, n'existe pas. OpenAI traite le repo comme le « système de référence » — tout le contexte nécessaire doit y vivre, via des fichiers structurés et une organisation claire des répertoires.- **Donnez un plan, pas un manuel** : L'expérience d'OpenAI — `AGENTS.md` devrait être une page de sommaire, pas une encyclopédie. Une centaine de lignes suffit. Si ça ne tient pas, découpez-le dans le répertoire `docs/` et laissez l'agent lire à la demande.- **Contraindre, pas micromanager** : Un bon harness utilise des règles exécutables pour contraindre l'agent, plutôt que d'énumérer les instructions une par une. OpenAI dit « imposez des invariants, ne micromanagez pas l'implémentation » ; Anthropic a constaté que les agents font l'éloge de leur propre travail en toute confiance, et la solution est de séparer « celui qui fait le travail » de « celui qui vérifie le travail ».-- **Retirer les composants un par un** : Pour quantifier la valeur de chaque composant du harness, retirez-les un par un et observez quel retrait provoque la plus forte baisse de performance. Anthropic a utilisé cette méthode et a découvert qu'à mesure que les modèles deviennent plus puissants, certains composants cessent d'être critiques — mais de nouveaux apparaissent toujours.+- **Retirer les composants un par un** : Pour quantifier la contribution marginale de chaque composant du harness, retirez-les un par un et observez quel retrait provoque la plus forte baisse de performance. Anthropic a utilisé cette méthode et a découvert qu'à mesure que les modèles deviennent plus puissants, certains composants cessent d'être critiques — mais de nouveaux apparaissent toujours.## Le modèle de harness à cinq sous-systèmes@@ -68,7 +68,7 @@ Verification commands:L'absence d'un sous-système est comme l'absence d'une zone fonctionnelle dans la cuisine — vous pouvez toujours cuisiner, mais c'est toujours laborieux.-**Diagnostiquer la qualité du harness** : Utilisez le « contrôle isométrique du modèle ». Gardez le modèle fixe, retirez les sous-systèmes un par un, mesurez quel retrait provoque la plus forte baisse de performance. C'est votre goulot d'étranglement — concentrez vos efforts là-dessus. Comme trouver le goulot d'étranglement dans une cuisine : retirez l'étagère à recettes et voyez combien les choses ralentissent, coupez la cuisinière et observez l'impact.+**Quantifier la valeur des composants du harness** : Utilisez le « contrôle isométrique du modèle ». Gardez le modèle fixe, retirez les sous-systèmes un par un et mesurez quel retrait provoque la plus forte baisse de performance. La plus forte baisse indique le composant à plus forte contribution marginale dans cette tâche, pas automatiquement le goulot d'étranglement. Pour localiser le vrai goulot, combinez cette expérience avec des journaux d'échec et une attribution : tâche floue, contexte insuffisant, environnement non reproductible, feedback de vérification manquant ou gestion d'état rompue.## L'histoire vraie d'une équipe@@ -89,7 +89,7 @@ Quatre itérations, le modèle n'a pas du tout changé, le taux de réussite est- Harness = Instructions + Outils + Environnement + État + Retour. Cinq sous-systèmes, comme les cinq zones fonctionnelles d'une cuisine — tous essentiels.- Si ce ne sont pas les poids du modèle, c'est du harness. Votre harness détermine quelle part de la capacité du modèle est réellement exploitée.- Parmi les cinq sous-systèmes, le sous-système de retour offre généralement l'investissement le plus faible et le rendement le plus élevé. Configurez d'abord vos commandes de vérification — la fenêtre de contrôle qualité est l'amélioration la plus rentable.-- Utilisez le « contrôle isométrique du modèle » pour quantifier la contribution marginale de chaque sous-système — ne vous fiez pas à votre intuition.+- Utilisez le « contrôle isométrique du modèle » pour quantifier la contribution marginale de chaque sous-système ; utilisez les journaux d'échec et l'attribution pour localiser le vrai goulot d'étranglement.- Le harness se dégrade comme le code. Auditez régulièrement, remboursez la dette de harness comme vous remboursez la dette technique.## Pour aller plus loindiff --git a/docs/ja/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/ja/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex 6d07bb7..8081d44 100644--- a/docs/ja/lectures/lecture-01-why-capable-agents-still-fail/index.md+++ b/docs/ja/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -17,9 +17,9 @@Anthropic は制御実験を行いました。同じプロンプト(「2D レトロゲームメーカーを作る」)、同じモデル(Opus 4.5)。1 回目は bare、支援なし。20 分、9 ドル、ゲームの中核機能はまったく動きませんでした。2 回目は完全な harness(planner + generator + evaluator の 3 エージェント構成)。6 時間、200 ドル、ゲームはプレイ可能でした。-モデルは変えていません。Opus 4.5 は同じ Opus 4.5 です。変わったのは鞍です。+モデルは変えていません。Opus 4.5 は同じ Opus 4.5 です。変わったのは馬具です。-OpenAI の harness engineering 記事ははっきり言っています。よく harness されたリポジトリでは、Codex は「不可靠」から「可靠」へ変わる。表現に注目してください。「少し良くなる」ではなく、質的な変化です。サラブレッドのようなものです。鞍なしでも乗れますが、遠くへは行けず、速くも走れず、落ちても不思議ではありません。harness はその鞍です。つまり、**モデル重みの外側にあるエンジニアリング基盤のすべて**です。+OpenAI の harness engineering 記事ははっきり言っています。よく harness されたリポジトリでは、Codex は「不可靠」から「可靠」へ変わる。表現に注目してください。「少し良くなる」ではなく、質的な変化です。サラブレッドのようなものです。馬具なしでも乗れますが、うまく制御できず、遠くへは行けず、落ちても不思議ではありません。harness はその一式の馬具です。つまり、**モデル重みの外側にあるエンジニアリング基盤のすべて**です。## エージェントは実際どこで詰まるのか@@ -40,7 +40,7 @@ OpenAI の harness engineering 記事ははっきり言っています。よくこうした状況を踏まえると、次の概念は単なる流行語ではありません。- **能力ギャップ**: ベンチマーク上のモデル性能と実タスクでの性能の大きな差。SWE-bench Verified で 50-60% ということは、実 issue のほぼ半分は解けないということです。-- **Harness**: モデルの外側にあるすべて。指示、ツール、環境、状態管理、検証フィードバック。モデル重みでなければ harness です。この講義で言う「鞍」です。+- **Harness**: モデルの外側にあるすべて。指示、ツール、環境、状態管理、検証フィードバック。モデル重みでなければ harness です。この講義で言う「馬具」です。- **Harness 起因の失敗**: モデルには能力があるのに、実行環境に構造的欠陥があるため失敗すること。Anthropic の制御実験がこれを示しています。- **検証ギャップ**: エージェントの出力への自信と実際の正しさの差。エージェントが「完了」と言うが完了していない。最も多い失敗モードです。- **診断ループ**: 実行し、失敗を観察し、特定の harness 層に原因を割り当て、その層を修正し、再実行する。harness engineering の中核手法です。@@ -52,7 +52,7 @@ OpenAI の harness engineering 記事ははっきり言っています。よく具体的には次のように進めます。-**すべての失敗を特定の層に帰属させる。** 「モデルがだめ」と言わないでください。タスクが曖昧だったのか。コンテキスト不足だったのか。検証手段がなかったのか。各失敗を 5 つの層(タスク仕様、コンテキスト提供、実行環境、検証フィードバック、状態管理)に対応づけます。この習慣がつくと、「モデルが足りない」はログにだんだん出なくなります。+**すべての失敗を特定の層に帰属させる。** 「モデルがだめ」と言わないでください。タスクが曖昧だったのか。コンテキスト不足だったのか。検証手段がなかったのか。各失敗を 5 つの防御層(タスク仕様、コンテキスト提供、実行環境、検証フィードバック、状態管理)に対応づけます。これは実践的な診断レイヤーであり、上の 6 つの用語とは別の分類です。この習慣がつくと、「モデルが足りない」はログにだんだん出なくなります。**すべてのタスクに明示的な Definition of Done を書く。** 「検索機能を追加して」ではなく、こう書きます。```@@ -94,7 +94,7 @@ OpenAI は 2025 年に強烈な実験を行いました。空の git リポジ## 重要なポイント-- モデル能力と実行信頼性は別物です。サラブレッドにも良い鞍が必要です。+- モデル能力と実行信頼性は別物です。サラブレッドにも良い馬具が必要です。- 失敗したら、まず harness を確認し、その後でモデルを疑います。モデル交換は最も高価な選択肢で、多くの場合はモデル問題ですらありません。- すべての失敗は信号です。harness に構造的欠陥があります。見つけて直してください。- 5 つの防御層: タスク仕様、コンテキスト提供、実行環境、検証フィードバック、状態管理。医師が一般的な原因から除外するように、体系的に確認します。diff --git a/docs/ja/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/ja/lectures/lecture-02-what-a-harness-actually-is/index.mdindex aaca938..4239dd0 100644--- a/docs/ja/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/ja/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -33,7 +33,7 @@ OpenAI は核心となる原則を「リポジトリこそが仕様である」- **リポジトリが唯一の信頼できる情報源**: エージェントが見られないものは、実質的に存在しません。OpenAI はリポジトリを「system of record」として扱います — 必要なコンテキストはすべてそこに存在し、構造化されたファイルと明確なディレクトリ構成を通じて提供される必要があります。- **マニュアルではなく地図を与える**: OpenAI の経験 — `AGENTS.md` は百科事典ではなく目次ページであるべきです。100行程度で十分です。収まらない場合は `docs/` ディレクトリに分割し、エージェントが必要に応じて読み込むようにします。- **細かく管理するのではなく制約を与える**: 良い harness は、実行可能なルールを使ってエージェントを制約し、指示を一つ一つ列挙するのではありません。OpenAI は「不変条件を強制し、実装を細かく管理しない」と述べています。Anthropic は、エージェントが自信満々に自分の仕事を賞賛することを発見し、解決策は「仕事をする人」と「仕事をチェックする人」を分離することだとしています。-- **コンポーネントを一つずつ削除する**: 各 harness コンポーネントの価値を定量化するには、一つずつ削除し、どの削除が最大のパフォーマンス低下を引き起こすかを確認します。Anthropic はこの手法を用い、モデルが強力になるにつれて一部のコンポーネントは重要でなくなるが、常に新しいコンポーネントが必要になることを発見しました。+- **コンポーネントを一つずつ削除する**: 各 harness コンポーネントの限界貢献を定量化するには、一つずつ削除し、どの削除が最大のパフォーマンス低下を引き起こすかを確認します。Anthropic はこの手法を用い、モデルが強力になるにつれて一部のコンポーネントは重要でなくなるが、常に新しいコンポーネントが必要になることを発見しました。## 5サブシステム harness モデル@@ -68,7 +68,7 @@ Verification commands:どれか一つのサブシステムが欠けていると、キッチンの機能領域が欠けているのと同じです — 料理はできますが、常に不便です。-**harness の品質診断**: 「等尺性モデル制御」を使用します。モデルを固定し、サブシステムを一つずつ削除し、どの削除が最大のパフォーマンス低下を引き起こすかを測定します。そこがボトルネックです — 努力をそこに集中させます。キッチンのボトルネックを見つけるように、レシピ棚を取り外してどれくらい遅くなるかを確認し、コンロを止めて影響を見ます。+**harness コンポーネントの価値を定量化する方法**: 「等尺性モデル制御」を使用します。モデルを固定し、サブシステムを一つずつ削除し、どの削除が最大のパフォーマンス低下を引き起こすかを測定します。最大の低下は、そのタスクで限界貢献が最も大きいコンポーネントを示しますが、それだけでボトルネックを証明するわけではありません。ボトルネックを見つけるには、失敗ログと原因帰属も組み合わせます。タスクが曖昧だったのか、コンテキスト不足だったのか、環境が再現不能だったのか、検証フィードバックが欠けていたのか、状態管理が途切れていたのかを確認します。## あるチームの実話@@ -89,7 +89,7 @@ Verification commands:- Harness = 指示 + ツール + 環境 + 状態 + フィードバック。5つのサブシステムは、キッチンの5つの機能領域のように — すべて不可欠です。- モデルの重みパラメータでないものは、すべて harness です。あなたの harness がモデルの能力をどれだけ発揮させるかを決定します。- 5つのサブシステムの中で、フィードバックサブシステムは通常、最も投資が少なく最もリターンが大きいです。まず検証コマンドを正しく設定しましょう — 品質チェック窓口は最も価値のあるアップグレードです。-- 「等尺性モデル制御」を使って各サブシステムの限界貢献を定量化しましょう — 感覚に頼ってはいけません。+- 「等尺性モデル制御」を使って各サブシステムの限界貢献を定量化しましょう。感覚に頼らず、失敗ログと原因帰属で本当のボトルネックを見つけます。- Harness はコードと同じように腐敗します。定期的に監査し、技術的負債を返済するように harness の負債も返済しましょう。## 参考資料diff --git a/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex 7bed969..d630550 100644--- a/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/index.md+++ b/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -21,9 +21,9 @@ Anthropic이 통제 실험을 진행했습니다. 동일한 프롬프트("2D 레하네스(harness)란 AI 코딩 에이전트가 안정적으로 동작하도록 환경·상태(state)·검증(verification)·제어를 묶어서 제공하는 외골격(스캐폴딩) 시스템입니다. 모델 가중치 외부에 있는 모든 엔지니어링 인프라가 하네스에 해당합니다.-모델은 바꾸지 않았습니다. Opus 4.5는 여전히 Opus 4.5였죠. 바뀐 것은 안장(saddle)이었습니다.+모델은 바꾸지 않았습니다. Opus 4.5는 여전히 Opus 4.5였죠. 바뀐 것은 마구(tack)였습니다.-OpenAI의 2025년 하네스 엔지니어링 글은 명확하게 밝힙니다: 잘 갖춰진 저장소(repository)에서의 Codex는 "불안정"에서 "안정"으로 질적 전환을 이룬다고. 표현에 주목하세요 — "조금 나아진"이 아니라 질적 변화입니다. 마치 경주마처럼: 안장 없이도 탈 수 있지만, 멀리 갈 수 없고, 빠르게 달릴 수 없으며, 낙마도 놀랍지 않습니다. 하네스는 그 안장입니다 — **모델 가중치 외부의 엔지니어링 인프라 전체입니다.**+OpenAI의 2025년 하네스 엔지니어링 글은 명확하게 밝힙니다: 잘 갖춰진 저장소(repository)에서의 Codex는 "불안정"에서 "안정"으로 질적 전환을 이룬다고. 표현에 주목하세요 — "조금 나아진"이 아니라 질적 변화입니다. 마치 경주마처럼: 적절한 마구 없이도 탈 수 있지만, 멀리 갈 수 없고, 빠르게 달릴 수 없으며, 낙마도 놀랍지 않습니다. 하네스는 그 전체 마구입니다 — **모델 가중치 외부의 엔지니어링 인프라 전체입니다.**## 에이전트가 실제로 막히는 지점@@ -44,7 +44,7 @@ OpenAI의 2025년 하네스 엔지니어링 글은 명확하게 밝힙니다:이 시나리오들을 염두에 두면 다음 개념들이 단순한 전문 용어 이상으로 다가옵니다.- **역량 격차(Capability Gap)**: 벤치마크 성능과 실제 작업 성능 사이의 큰 간극. SWE-bench Verified에서 50-60%의 통과율은 실제 이슈의 거의 절반이 해결되지 않는다는 의미입니다.-- **하네스(Harness)**: 모델 외부의 모든 것 — 지시사항, 도구, 환경, 상태(state) 관리, 검증(verification) 피드백. 모델 가중치가 아니라면 모두 하네스입니다. 우리가 "안장"이라고 부른 것입니다.+- **하네스(Harness)**: 모델 외부의 모든 것 — 지시사항, 도구, 환경, 상태(state) 관리, 검증(verification) 피드백. 모델 가중치가 아니라면 모두 하네스입니다. 우리가 "마구"라고 부른 것입니다.- **하네스 유발 실패(Harness-Induced Failure)**: 모델은 충분한 역량을 갖췄지만 실행 환경에 구조적 결함이 있는 경우. Anthropic의 통제 실험이 이를 이미 증명했습니다.- **검증 격차(Verification Gap)**: 에이전트가 자신의 산출물(deliverable)에 대해 갖는 자신감과 실제 정확성 사이의 간극. 에이전트가 "완료했다"고 말하지만 완료하지 않은 상태 — 이것이 가장 흔한 실패 유형입니다.- **진단 루프(Diagnostic Loop)**: 실행 → 실패 관찰 → 특정 하네스 레이어에 귀속 → 해당 레이어 수정 → 재실행. 이것이 하네스 엔지니어링의 핵심 방법론입니다.@@ -56,7 +56,7 @@ OpenAI의 2025년 하네스 엔지니어링 글은 명확하게 밝힙니다:구체적인 단계:-**모든 실패를 특정 레이어에 귀속시키십시오.** "모델이 별로야"라고만 하지 마십시오. 물어보십시오: 작업이 불명확했는가? 컨텍스트(context)가 불충분했는가? 검증 방법이 없었는가? 각 실패를 다섯 가지 실패 레이어(작업 명세, 컨텍스트 제공, 실행 환경, 검증 피드백, 상태 관리) 중 하나에 매핑하십시오. 이 습관을 들이면 로그에서 "모델이 부족해"라는 말이 점점 사라집니다.+**모든 실패를 특정 레이어에 귀속시키십시오.** "모델이 별로야"라고만 하지 마십시오. 물어보십시오: 작업이 불명확했는가? 컨텍스트(context)가 불충분했는가? 검증 방법이 없었는가? 각 실패를 다섯 가지 실패 레이어(작업 명세, 컨텍스트 제공, 실행 환경, 검증 피드백, 상태 관리) 중 하나에 매핑하십시오. 이것은 실무 진단 레이어이지, 위의 여섯 가지 용어와 같은 분류가 아닙니다. 이 습관을 들이면 로그에서 "모델이 부족해"라는 말이 점점 사라집니다.**모든 작업에 명시적인 완료 기준을 작성하십시오.** "검색 기능을 추가해"라고 하지 마십시오. 이렇게 하십시오:```@@ -98,7 +98,7 @@ OpenAI는 2025년에 공격적인 실험을 진행했습니다: Codex를 사용## 핵심 정리-- 모델 역량과 실행 신뢰성은 별개입니다. 경주마도 좋은 안장이 필요합니다.+- 모델 역량과 실행 신뢰성은 별개입니다. 경주마도 좋은 마구가 필요합니다.- 실패 시 먼저 하네스를 점검하고, 그 다음 모델을 확인하십시오. 모델 교체는 가장 비싼 선택지입니다 — 그리고 대부분 모델 문제가 아닙니다.- 모든 실패는 신호입니다: 하네스에 구조적 결함이 있습니다. 찾아서 고치십시오.- 다섯 가지 방어 레이어: 작업 명세, 컨텍스트 제공, 실행 환경, 검증 피드백, 상태 관리. 의사가 가장 흔한 원인부터 먼저 배제하듯이 체계적으로 점검하십시오.diff --git a/docs/ko/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/ko/lectures/lecture-02-what-a-harness-actually-is/index.mdindex c1bd542..09c26ee 100644--- a/docs/ko/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/ko/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -33,7 +33,7 @@ OpenAI는 핵심 원칙을 "저장소(repo)가 명세(spec)다"로 정의합니- **저장소는 단일 진실 원천(SoR)이다**: 에이전트가 볼 수 없는 것은 실질적으로 존재하지 않습니다. OpenAI는 저장소를 "시스템 오브 레코드(SoR, system of record)"로 취급합니다 — 모든 필요한 컨텍스트는 구조화된 파일과 명확한 디렉터리 구성을 통해 저장소에 있어야 합니다.- **지도를 줘라, 매뉴얼이 아니라**: OpenAI의 경험 — `AGENTS.md`는 백과사전이 아니라 디렉터리 페이지여야 합니다. 100줄 정도가 적당합니다. 맞지 않으면 `docs/` 디렉터리로 분리하여 에이전트가 필요할 때 읽도록 하십시오.- **제약하되, 마이크로매니지하지 마라**: 좋은 하네스는 실행 가능한 규칙으로 에이전트를 제약하지, 지시를 하나하나 열거하지 않습니다. OpenAI는 "불변성을 강제하되, 구현을 마이크로매니지하지 말라"고 말합니다. Anthropic은 에이전트가 자신의 작업을 자신만만하게 칭찬한다는 것을 발견했으며, 해결책은 "일하는 사람"과 "확인하는 사람"을 분리하는 것입니다.-- **컴포넌트를 하나씩 제거하라**: 각 하네스 컴포넌트의 가치를 정량화하려면 하나씩 제거하고 어떤 제거가 가장 큰 성능 저하를 유발하는지 확인하십시오. Anthropic은 이 방법을 사용했으며, 모델이 강해질수록 일부 컴포넌트는 더 이상 핵심적이지 않지만 새로운 컴포넌트가 항상 등장한다는 것을 발견했습니다.+- **컴포넌트를 하나씩 제거하라**: 각 하네스 컴포넌트의 한계 기여도를 정량화하려면 하나씩 제거하고 어떤 제거가 가장 큰 성능 저하를 유발하는지 확인하십시오. Anthropic은 이 방법을 사용했으며, 모델이 강해질수록 일부 컴포넌트는 더 이상 핵심적이지 않지만 새로운 컴포넌트가 항상 등장한다는 것을 발견했습니다.## 5개 하위 시스템 하네스 모델@@ -68,7 +68,7 @@ flowchart LR하위 시스템 하나라도 빠지면 주방의 기능 구역 하나가 없는 것과 같습니다 — 요리는 할 수 있지만 항상 불편합니다.-**하네스 품질 진단**: "등압 모델 제어(isometric model control)"를 사용하십시오. 모델을 고정하고 하위 시스템을 하나씩 제거하면서 어떤 제거가 가장 큰 성능 저하를 유발하는지 측정하십시오. 그것이 병목 — 거기에 집중하십시오. 주방에서 병목을 찾는 것처럼: 레시피 선반을 없애고 얼마나 느려지는지 보고, 가스레인지를 끄고 영향을 확인하십시오.+**하네스 컴포넌트 가치 정량화**: "등압 모델 제어(isometric model control)"를 사용하십시오. 모델을 고정하고 하위 시스템을 하나씩 제거하면서 어떤 제거가 가장 큰 성능 저하를 유발하는지 측정하십시오. 가장 큰 하락은 해당 작업에서 한계 기여도가 가장 큰 컴포넌트를 보여주지만, 그것만으로 병목을 증명하지는 않습니다. 병목을 찾으려면 실패 기록과 귀인을 함께 보십시오. 작업이 불명확했는지, 컨텍스트가 부족했는지, 환경이 재현 불가능했는지, 검증 피드백이 없었는지, 상태 관리가 끊겼는지를 확인해야 합니다.## 한 팀의 실제 이야기@@ -89,7 +89,7 @@ flowchart LR- 하네스 = 지시 + 도구 + 환경 + 상태(state) + 피드백. 다섯 가지 하위 시스템, 주방의 다섯 가지 기능 구역처럼 — 모두 필수입니다.- 모델 가중치가 아니라면 모두 하네스입니다. 하네스가 모델 역량이 얼마나 발휘되는지를 결정합니다.- 다섯 가지 하위 시스템 중 피드백 하위 시스템이 일반적으로 가장 낮은 투자로 가장 높은 수익을 냅니다. 검증 명령어를 먼저 맞추십시오 — 품질 확인 창이 가장 가치 있는 업그레이드입니다.-- "등압 모델 제어"를 사용하여 각 하위 시스템의 한계 기여도를 정량화하십시오 — 직감에 의존하지 마십시오.+- "등압 모델 제어"를 사용하여 각 하위 시스템의 한계 기여도를 정량화하십시오. 직감에 의존하지 말고, 실패 기록과 귀인으로 실제 병목을 찾으십시오.- 하네스는 코드처럼 부패합니다. 정기적으로 감사하고 기술 부채를 갚듯 하네스 부채를 갚으십시오.## 더 읽을거리diff --git a/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex b53a947..da3fcf4 100644--- a/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/index.md+++ b/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -17,9 +17,9 @@Anthropic провели контролируемый эксперимент. Один и тот же промпт («собери 2D ретро-конструктор игр»), одна и та же модель (Opus 4.5). Первый прогон: голая среда без поддержки — 20 минут, $9, ключевые механики игры просто не работают. Второй прогон: полный harness (архитектура из трёх агентов: planner + generator + evaluator) — 6 часов, $200, в игру можно играть.-Модель не меняли. Opus 4.5 оставался Opus 4.5. Изменилось седло.+Модель не меняли. Opus 4.5 оставался Opus 4.5. Изменилась упряжь.-Статья OpenAI 2025 года про harness engineering говорит прямо: Codex в репозитории с хорошим harness переходит из «ненадёжного» в «надёжный». Обратите внимание на формулировку — не «чуть лучше», а качественный сдвиг. Как с породистой лошадью: ездить можно и без седла, но далеко не уедете, быстро не разгонитесь, и упасть — не сюрприз. Harness и есть это седло — **всё в инженерной инфраструктуре, что находится за пределами весов модели.**+Статья OpenAI 2025 года про harness engineering говорит прямо: Codex в репозитории с хорошим harness переходит из «ненадёжного» в «надёжный». Обратите внимание на формулировку — не «чуть лучше», а качественный сдвиг. Как с породистой лошадью: ездить можно и без подходящей упряжи, но далеко не уедете, быстро не разгонитесь, и упасть — не сюрприз. Harness и есть вся эта упряжь — **всё в инженерной инфраструктуре, что находится за пределами весов модели.**## Где на самом деле застревают агенты@@ -40,7 +40,7 @@ Anthropic провели контролируемый эксперимент. ОКогда вы видите эти сценарии вживую, термины перестают быть просто жаргоном:- **Capability Gap**: огромная пропасть между производительностью модели на бенчмарках и на реальных задачах. 50–60% pass rate на SWE-bench Verified означает, что почти половина реальных issue не решается.-- **Harness**: всё за пределами модели — инструкции, инструменты, среда, управление состоянием, верификационная обратная связь. Если это не веса модели — это harness. То самое «седло».+- **Harness**: всё за пределами модели — инструкции, инструменты, среда, управление состоянием, верификационная обратная связь. Если это не веса модели — это harness. Та самая «упряжь».- **Harness-Induced Failure**: у модели достаточно способностей, но в среде исполнения есть структурные дефекты. Контролируемый эксперимент Anthropic это уже доказал.- **Verification Gap**: разрыв между уверенностью агента в своей работе и реальной корректностью. Агент говорит «я закончил», когда не закончил — самый частый паттерн провала.- **Diagnostic Loop**: выполнить, увидеть провал, отнести его к конкретному слою harness, починить этот слой, выполнить снова. Это ядро методологии harness engineering.@@ -52,7 +52,7 @@ Anthropic провели контролируемый эксперимент. ОКонкретные шаги:-**Привязывайте каждый провал к конкретному слою.** Не ограничивайтесь «модель тупит». Спросите: задача была размыта? Контекста не хватало? Не было способов верификации? Сопоставьте каждый провал с одним из пяти защитных слоёв (спецификация задачи, предоставление контекста, среда исполнения, верификационная обратная связь, управление состоянием). Выработайте эту привычку — и в ваших логах «модель недостаточно хороша» будет всплывать всё реже.+**Привязывайте каждый провал к конкретному слою.** Не ограничивайтесь «модель тупит». Спросите: задача была размыта? Контекста не хватало? Не было способов верификации? Сопоставьте каждый провал с одним из пяти защитных слоёв: спецификация задачи, предоставление контекста, среда исполнения, верификационная обратная связь, управление состоянием. Это практические диагностические слои, а не шесть терминов из глоссария выше. Выработайте эту привычку — и в ваших логах «модель недостаточно хороша» будет всплывать всё реже.**Пишите явный Definition of Done для каждой задачи.** Не «добавь поиск». А:```@@ -94,7 +94,7 @@ Anthropic провели контролируемый эксперимент. О## Главное-- Способности модели и надёжность исполнения — разные вещи. Породистой лошади всё равно нужно хорошее седло.+- Способности модели и надёжность исполнения — разные вещи. Породистой лошади всё равно нужна хорошая упряжь.- Когда что-то ломается, сначала проверьте harness, потом модель. Менять модель — самый дорогой вариант, и часто это вообще не проблема модели.- Каждый провал — сигнал: в вашем harness структурный дефект. Найдите, почините.- Пять защитных слоёв: спецификация задачи, предоставление контекста, среда исполнения, верификационная обратная связь, управление состоянием. Проверяйте систематически, как врач сначала отметает самые частые причины.diff --git a/docs/ru/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/ru/lectures/lecture-02-what-a-harness-actually-is/index.mdindex 3fd909a..e449a45 100644--- a/docs/ru/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/ru/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -33,7 +33,7 @@ OpenAI формулируют главный принцип так: «the repo I- **Репозиторий — единственный источник истины**: то, чего агент не видит, для всех практических целей не существует. OpenAI рассматривают репо как «system of record» — весь необходимый контекст должен жить там, через структурированные файлы и понятную организацию каталогов.- **Дайте карту, а не учебник**: опыт OpenAI — `AGENTS.md` должен быть оглавлением, а не энциклопедией. Около 100 строк — достаточно. Если не помещается, выносите в каталог `docs/` и пусть агент читает по необходимости.- **Ограничивайте, а не микроменеджите**: хороший harness ограничивает агента исполняемыми правилами, а не перечисляет инструкции одну за другой. OpenAI говорят «enforce invariants, don't micromanage implementation»; Anthropic обнаружили, что агенты уверенно хвалят свою же работу, и решение — разделить «того, кто делает» и «того, кто проверяет».-- **Удаляйте компоненты по одному**: чтобы измерить ценность каждого компонента harness, удаляйте их по одному и смотрите, какое удаление сильнее всего просаживает производительность. Anthropic именно так и делали — и обнаружили, что по мере усиления моделей некоторые компоненты перестают быть критичными, но всегда появляются новые.+- **Удаляйте компоненты по одному**: чтобы измерить предельный вклад каждого компонента harness, удаляйте их по одному и смотрите, какое удаление сильнее всего просаживает производительность. Anthropic именно так и делали — и обнаружили, что по мере усиления моделей некоторые компоненты перестают быть критичными, но всегда появляются новые.## Модель harness из пяти подсистем@@ -68,7 +68,7 @@ flowchart LRОтсутствие любой подсистемы — как отсутствие функциональной зоны на кухне: готовить можно, но всегда будет неудобно.-**Диагностика качества harness**: используйте «изометрический контроль модели». Зафиксируйте модель, удаляйте подсистемы по одной, измеряйте, какое удаление сильнее всего просаживает производительность. Это и есть бутылочное горлышко — туда направляйте усилия. Как в поиске бутылочного горлышка на кухне: уберите полку с рецептами и посмотрите, насколько всё замедлится; выключите плиту и оцените эффект.+**Оценка ценности компонентов harness**: используйте «изометрический контроль модели». Зафиксируйте модель, удаляйте подсистемы по одной и измеряйте, какое удаление сильнее всего просаживает производительность. Самая большая просадка показывает компонент с наибольшим предельным вкладом в этой задаче, а не автоматически бутылочное горлышко. Чтобы найти настоящее бутылочное горлышко, совместите эксперимент с журналами сбоев и атрибуцией: размытая задача, нехватка контекста, невоспроизводимая среда, отсутствие верификационной обратной связи или сломанное управление состоянием.## Реальная история одной команды@@ -89,7 +89,7 @@ flowchart LR- Harness = инструкции + инструменты + среда + состояние + обратная связь. Пять подсистем, как пять функциональных зон кухни — все обязательны.- Если это не веса модели — это harness. Ваш harness определяет, какая часть способностей модели реализуется.- Среди пяти подсистем у подсистемы обратной связи обычно самый низкий вход и самый высокий возврат. Сначала наладьте команды верификации — окно контроля качества стоит апгрейдить в первую очередь.-- Используйте «изометрический контроль модели», чтобы количественно оценить вклад каждой подсистемы — не на глазок.+- Используйте «изометрический контроль модели», чтобы количественно оценить предельный вклад каждой подсистемы; используйте журналы сбоев и атрибуцию, чтобы найти настоящее бутылочное горлышко.- Harness гниёт так же, как код. Ревизуйте регулярно, гасите harness-долг как технический долг.## Дальнейшее чтениеdiff --git a/docs/tr/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/tr/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex 57abb9c..f284a7b 100644--- a/docs/tr/lectures/lecture-01-why-capable-agents-still-fail/index.md+++ b/docs/tr/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -17,9 +17,9 @@ Ama bu sayıların ardında sezgilere ters bir gerçek yatıyor.Anthropic kontrollü bir deney yaptı. Aynı prompt ("2B retro oyun yapımcısı geliştir"), aynı model (Opus 4.5). İlk koşu: çıplak, hiçbir destek yok — 20 dakika, 9 dolar, oyunun temel özellikleri hiç çalışmadı. İkinci koşu: tam harness (planlayıcı + üretici + değerlendirici üç-ajan mimarisi) — 6 saat, 200 dolar, oyun oynanabilir hâle geldi.-Modeli değiştirmediler. Opus 4.5 yine Opus 4.5'ti. Değişen şey eyerdi.+Modeli değiştirmediler. Opus 4.5 yine Opus 4.5'ti. Değişen şey koşum takımıydı.-OpenAI'nin 2025 harness mühendisliği makalesi bunu açıkça söylüyor: iyi bir harness'a sahip bir depoda Codex "güvenilmez"den "güvenilir"e geçiyor. İfadeye dikkat edin — "biraz daha iyi" değil, niteliksel bir sıçrama. Tıpkı safkan bir at gibi: eyersiz binebilirsiniz ama uzağa gidemezsiniz, hızlı gidemezsiniz, düşmek de sürpriz olmaz. Harness işte o eyerdir — **model ağırlıkları dışındaki tüm mühendislik altyapısı.**+OpenAI'nin 2025 harness mühendisliği makalesi bunu açıkça söylüyor: iyi bir harness'a sahip bir depoda Codex "güvenilmez"den "güvenilir"e geçiyor. İfadeye dikkat edin — "biraz daha iyi" değil, niteliksel bir sıçrama. Tıpkı safkan bir at gibi: doğru koşum takımı olmadan binebilirsiniz ama uzağa gidemezsiniz, hızlı gidemezsiniz, düşmek de sürpriz olmaz. Harness işte o tam koşum takımıdır — **model ağırlıkları dışındaki tüm mühendislik altyapısı.**## Ajanlar gerçekte nerede takılıyor@@ -40,7 +40,7 @@ Birden fazla oturuma yayılan uzun görevler daha da kötüdür — önceki oturBu senaryolar göz önünde bulundurulduğunda bu kavramlar artık sadece jargon değil:- **Yetenek farkı (Capability Gap)**: Modelin benchmark performansı ile gerçek görev performansı arasındaki büyük uçurum. SWE-bench Verified üzerindeki %50-60 başarı oranı, gerçek sorunların neredeyse yarısının çözülemediği anlamına gelir.-- **Harness**: Modelin dışındaki her şey — talimatlar, araçlar, ortam, durum yönetimi, doğrulama geri bildirimi. Eğer model ağırlığı değilse, harness'tır. "Eyer" diye andığımız şey.+- **Harness**: Modelin dışındaki her şey — talimatlar, araçlar, ortam, durum yönetimi, doğrulama geri bildirimi. Eğer model ağırlığı değilse, harness'tır. "Koşum takımı" diye andığımız şey.- **Harness kaynaklı başarısızlık (Harness-Induced Failure)**: Modelin yeterli yeteneği vardır ama yürütme ortamı yapısal kusurlara sahiptir. Anthropic'in kontrollü deneyi bunu zaten kanıtladı.- **Doğrulama farkı (Verification Gap)**: Ajanın çıktısına olan güveni ile gerçek doğruluk arasındaki fark. Ajan iş bitmemişken "bitirdim" diyor — bu en yaygın başarısızlık modu.- **Tanılayıcı döngü (Diagnostic Loop)**: Yürüt, başarısızlığı gözlemle, belirli bir harness katmanına ata, o katmanı düzelt, yeniden yürüt. Bu, harness mühendisliğinin temel metodolojisidir.@@ -52,7 +52,7 @@ Temel ilke: **Bir şey ters gittiğinde önce modeli değiştirmeyin — harnessSomut adımlar:-**Her başarısızlığı belirli bir katmana atfedin.** Sadece "model berbat" demeyin. Sorun: Görev belirsiz miydi? Bağlam yetersiz miydi? Doğrulama yöntemleri yok muydu? Her başarısızlığı beş başarısızlık katmanından birine eşleyin (görev belirleme, bağlam sağlama, yürütme ortamı, doğrulama geri bildirimi, durum yönetimi). Bu alışkanlığı kazanın ve "model yeterince iyi değil" ifadesinin günlüklerinizde gittikçe azaldığını göreceksiniz.+**Her başarısızlığı belirli bir katmana atfedin.** Sadece "model berbat" demeyin. Sorun: Görev belirsiz miydi? Bağlam yetersiz miydi? Doğrulama yöntemleri yok muydu? Her başarısızlığı beş başarısızlık katmanından birine eşleyin: görev belirleme, bağlam sağlama, yürütme ortamı, doğrulama geri bildirimi ve durum yönetimi. Bunlar pratik tanı katmanlarıdır, yukarıdaki altı sözlük terimi değildir. Bu alışkanlığı kazanın ve "model yeterince iyi değil" ifadesinin günlüklerinizde gittikçe azaldığını göreceksiniz.**Her görev için açık bir Bitirme Tanımı yazın.** "Bir arama özelliği ekle" demeyin. Şunu söyleyin:```@@ -94,7 +94,7 @@ Modeli değiştirmediler. Harness'ı değiştirdiler.## Önemli çıkarımlar-- Model yeteneği ve yürütme güvenilirliği farklı şeylerdir. Safkan bir at hâlâ iyi bir eyere ihtiyaç duyar.+- Model yeteneği ve yürütme güvenilirliği farklı şeylerdir. Safkan bir at hâlâ iyi bir koşum takımına ihtiyaç duyar.- Bir şey ters gittiğinde önce harness'ı kontrol edin, sonra modeli. Model değiştirmek en pahalı seçenektir — ve çoğu zaman model sorunu bile değildir.- Her başarısızlık bir sinyaldir: harness'ınızın yapısal bir kusuru var. Onu bulun, düzeltin.- Beş savunma katmanı: görev belirleme, bağlam sağlama, yürütme ortamı, doğrulama geri bildirimi, durum yönetimi. Bir doktorun en yaygın nedenleri önce eleyerek yaptığı gibi sistematik olarak kontrol edin.diff --git a/docs/tr/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/tr/lectures/lecture-02-what-a-harness-actually-is/index.mdindex 542e8d7..2bc6e96 100644--- a/docs/tr/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/tr/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -33,7 +33,7 @@ Zaten bildiğiniz bazı araçlara bakın:- **Depo tek doğruluk kaynağıdır**: Ajanın göremediği her şey, pratik olarak yoktur. OpenAI depoyu "kayıt sistemi" olarak ele alır — gerekli tüm bağlam yapılandırılmış dosyalar ve net dizin organizasyonu aracılığıyla orada yaşamalıdır.- **Manuel değil, harita verin**: OpenAI'nin tecrübesi — `AGENTS.md` bir ansiklopedi değil, bir içerik sayfası olmalıdır. Yaklaşık 100 satır yeterlidir. Sığmıyorsa `docs/` dizinine bölün ve ajanın talep üzerine okumasına izin verin.- **Kısıtlayın, mikromanaje etmeyin**: İyi bir harness ajanı tek tek talimatları saymak yerine yürütülebilir kurallarla kısıtlar. OpenAI "değişmezleri zorla, uygulamayı mikromanaje etme" diyor; Anthropic ajanların kendi işlerini güvenle övdüğünü buldu ve çözüm "işi yapan kişi" ile "işi kontrol eden kişiyi" ayırmak.-- **Bileşenleri tek tek kaldırın**: Her harness bileşeninin değerini ölçmek için bunları tek tek kaldırın ve hangisinin kaldırılmasının en büyük performans düşüşüne neden olduğunu görün. Anthropic bu yöntemi kullandı ve modeller güçlendikçe bazı bileşenlerin artık kritik olmaktan çıktığını buldu — ancak her zaman yenileri ortaya çıkıyor.+- **Bileşenleri tek tek kaldırın**: Her harness bileşeninin marjinal katkısını ölçmek için bunları tek tek kaldırın ve hangisinin kaldırılmasının en büyük performans düşüşüne neden olduğunu görün. Anthropic bu yöntemi kullandı ve modeller güçlendikçe bazı bileşenlerin artık kritik olmaktan çıktığını buldu — ancak her zaman yenileri ortaya çıkıyor.## Beş alt sistemli harness modeli@@ -68,7 +68,7 @@ Doğrulama komutları:Herhangi bir alt sistemin eksikliği mutfakta bir işlevsel alanın eksikliği gibidir — yine de yemek yapabilirsiniz, ama her zaman zahmetlidir.-**Harness kalitesini tanılama**: "Eşit modelli kontrol" kullanın. Modeli sabit tutun, alt sistemleri tek tek kaldırın, hangisinin kaldırılmasının en büyük performans düşüşüne neden olduğunu ölçün. Bu sizin darboğazınızdır — çabanızı oraya odaklayın. Bir mutfakta darboğazı bulmak gibi: tarif rafını alın ve ne kadar yavaşladığını görün, ocağı kapatın ve etkiyi görün.+**Harness bileşen değerini ölçme**: "Eşit modelli kontrol" kullanın. Modeli sabit tutun, alt sistemleri tek tek kaldırın ve hangisinin kaldırılmasının en büyük performans düşüşüne neden olduğunu ölçün. En büyük düşüş, o görevde marjinal katkısı en yüksek olan bileşeni belirler — otomatik olarak darboğazı belirlemez. Darboğazı tespit etmek için bu deneyi başarısızlık günlükleri ve atıflarla birleştirin: belirsiz görev, yetersiz bağlam, yeniden üretilemeyen ortam, eksik doğrulama geri bildirimi veya bozuk durum yönetimi.## Bir takımın gerçek hikâyesi@@ -89,7 +89,7 @@ Dört iterasyon, model hiç değişmedi, başarı oranı %20'den neredeyse %100'- Harness = Talimatlar + Araçlar + Ortam + Durum + Geri Bildirim. Beş alt sistem, bir mutfağın beş işlevsel alanı gibi — hepsi zorunlu.- Eğer model ağırlığı değilse, harness'tır. Harness'ınız model yeteneğinin ne kadarının kullanıldığını belirler.- Beş alt sistem arasında geri bildirim alt sistemi genellikle en düşük yatırım ve en yüksek getiriye sahiptir. Önce doğrulama komutlarınızı doğru ayarlayın — kalite kontrol penceresi en değerli yükseltmedir.-- Her alt sistemin marjinal katkısını ölçmek için "eşit modelli kontrol" kullanın — sezgiyle gitmeyin.+- Her alt sistemin marjinal katkısını ölçmek için "eşit modelli kontrol" kullanın — sezgiyle gitmeyin; gerçek darboğazı bulmak için başarısızlık günlüklerini ve atıflarını kullanın.- Harness da kod gibi çürür. Düzenli denetim yapın, teknik borç gibi harness borcunu da ödeyin.## Daha fazla okumadiff --git a/docs/uz/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/uz/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex 5a201dc..ba5d957 100644--- a/docs/uz/lectures/lecture-01-why-capable-agents-still-fail/index.md+++ b/docs/uz/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -17,9 +17,9 @@ Ammo bu raqamlar ortida intuitsiyaga zid bir haqiqat yashiringan.Anthropic nazorat ostida tajriba oʻtkazdi. Bir xil prompt (“2D retro oʻyinlar yaratish dasturini qur”), bir xil model (Opus 4.5). Birinchi sinov — hech qanday qoʻshimcha vositasiz: 20 daqiqa, 9 dollar; oʻyinning asosiy funksiyalari umuman ishlamadi. Ikkinchi sinov — toʻliq harness bilan (planner + generator + evaluator — uch agentli arxitektura): 6 soat, 200 dollar; oʻyin oʻynaladigan holatda chiqdi.-Ular modelni oʻzgartirmadi. Opus 4.5 hamon Opus 4.5 edi. Oʻzgargan narsa — egar.+Ular modelni oʻzgartirmadi. Opus 4.5 hamon Opus 4.5 edi. Oʻzgargan narsa — ot anjomlari.-OpenAIʼning 2025-yilgi harness engineering maqolasi buni ochiq aytadi: yaxshi tuzilgan harnessʼga ega repozitoriyadagi Codex “ishonchsiz”dan “ishonchli”ga oʻtadi. Eʼtibor bering — “biroz yaxshi” emas, sifat jihatidan tubdan boshqacha. Bu xuddi zotli otga oʻxshaydi: egarsiz minib boʻladi, lekin uzoqqa bormaysiz, tez ham yura olmaysiz, yiqilishingiz esa hech kimni ajablantirmaydi. Harness — aynan oʻsha egar; **model ogʻirliklaridan tashqaridagi barcha muhandislik infratuzilmasi.**+OpenAIʼning 2025-yilgi harness engineering maqolasi buni ochiq aytadi: yaxshi tuzilgan harnessʼga ega repozitoriyadagi Codex “ishonchsiz”dan “ishonchli”ga oʻtadi. Eʼtibor bering — “biroz yaxshi” emas, sifat jihatidan tubdan boshqacha. Bu xuddi zotli otga oʻxshaydi: mos ot anjomlarisiz minib boʻladi, lekin uzoqqa bormaysiz, tez ham yura olmaysiz, yiqilishingiz esa hech kimni ajablantirmaydi. Harness — aynan oʻsha toʻliq ot anjomlari; **model ogʻirliklaridan tashqaridagi barcha muhandislik infratuzilmasi.**## Agentlar aslida qayerda tiqilib qoladi@@ -40,7 +40,7 @@ Bir necha sessiyaga choʻzilgan uzun vazifalar yana ham yomonroq — oldingi sesBu ssenariylarni nazarda tutsak, quyidagi atamalar endi shunchaki jargon emas — har biri aniq muvaffaqiyatsizlik turini nomlaydi:- **Capability Gap (Imkoniyatlar tafovuti)**: Modelning benchmark natijalari va haqiqiy vazifalarda koʻrsatadigan natijalari oʻrtasidagi katta tafovut. SWE-bench Verifiedʼda 50–60% muvaffaqiyat darajasi haqiqiy muammolarning deyarli yarmi hal qilinmasligini bildiradi.-- **Harness**: Modeldan tashqaridagi hamma narsa — yoʻriqnomalar, vositalar, muhit, holat boshqaruvi, tekshiruv qayta aloqasi. Agar bu model ogʻirliklari boʻlmasa — bu harness. Biz “egar” deb atayotgan narsamiz.+- **Harness**: Modeldan tashqaridagi hamma narsa — yoʻriqnomalar, vositalar, muhit, holat boshqaruvi, tekshiruv qayta aloqasi. Agar bu model ogʻirliklari boʻlmasa — bu harness. Biz “ot anjomlari” deb atayotgan narsamiz.- **Harness-Induced Failure (Harness keltirib chiqargan muvaffaqiyatsizlik)**: Modelda yetarli imkoniyat mavjud, ammo bajarilish muhitida strukturaviy nuqsonlar bor. Anthropicʼning nazoratli tajribasi buni allaqachon isbotladi.- **Verification Gap (Tekshiruv tafovuti)**: Agentning oʻz natijasiga ishonchi va haqiqiy toʻgʻrilik oʻrtasidagi farq. Agent “men tugatdim” deydi, aslida tugatmagan — bu eng keng tarqalgan muvaffaqiyatsizlik turi.- **Diagnostic Loop (Diagnostik sikl)**: Bajarish, muvaffaqiyatsizlikni kuzatish, uni maʼlum bir harness qatlamiga bogʻlash, oʻsha qatlamni tuzatish, qaytadan bajarish. Bu — harness muhandisligining asosiy metodikasi.@@ -52,7 +52,7 @@ Asosiy tamoyil: **Yiqilish boʻlganda, modelni almashtirishga shoshilmang — haAniq qadamlar:-**Har bir muvaffaqiyatsizlikni aniq qatlamga bogʻlang.** Shunchaki “model yomon” demang. Oʻzingizdan soʻrang: vazifa noaniqmidi? Kontekst yetarli emasmidi? Tekshiruv usullari yoʻqmidi? Har bir muvaffaqiyatsizlikni beshta muvaffaqiyatsizlik qatlamlaridan biriga (vazifa spetsifikatsiyasi, kontekst taʼminoti, bajarilish muhiti, tekshiruv qayta aloqasi, holat boshqaruvi) bogʻlang. Shu odatni shakllantirsangiz, “model yetarli emas” iborasi loglaringizda kamayib boradi.+**Har bir muvaffaqiyatsizlikni aniq qatlamga bogʻlang.** Shunchaki “model yomon” demang. Oʻzingizdan soʻrang: vazifa noaniqmidi? Kontekst yetarli emasmidi? Tekshiruv usullari yoʻqmidi? Har bir muvaffaqiyatsizlikni beshta himoya qatlamidan biriga bogʻlang: vazifa spetsifikatsiyasi, kontekst taʼminoti, bajarilish muhiti, tekshiruv qayta aloqasi, holat boshqaruvi. Bular amaliy diagnostika qatlamlari, yuqoridagi oltita glossariy atamasi emas. Shu odatni shakllantirsangiz, “model yetarli emas” iborasi loglaringizda kamayib boradi.**Har bir vazifa uchun aniq Definition of Done (bajarilganlik mezonlari) yozing.** “Qidiruv funksiyasini qoʻsh” demang. Mana shunday yozing:@@ -95,7 +95,7 @@ Ular modelni oʻzgartirmadi. Ular harnessʼni oʻzgartirdi.## Asosiy xulosalar-- Modelning imkoniyati va bajarilishning ishonchliligi — bular boshqa-boshqa narsalar. Zotli ot ham yaxshi egarni talab qiladi.+- Modelning imkoniyati va bajarilishning ishonchliligi — bular boshqa-boshqa narsalar. Zotli ot ham yaxshi ot anjomlarini talab qiladi.- Yiqilish boʻlganda — avval harnessʼni, keyin modelni tekshiring. Modelni almashtirish — eng qimmat variant — va koʻpincha bu model muammosi ham emas.- Har bir muvaffaqiyatsizlik — signal: harnessʼingizda strukturaviy nuqson bor. Toping, tuzating.- Beshta himoya qatlami: vazifa spetsifikatsiyasi, kontekst taʼminoti, bajarilish muhiti, tekshiruv qayta aloqasi, holat boshqaruvi. Doktor eng keng tarqalgan sabablarni avval inkor qilganidek, ularni tizimli tekshiring.diff --git a/docs/uz/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/uz/lectures/lecture-02-what-a-harness-actually-is/index.mdindex d3b085a..2ec0a8a 100644--- a/docs/uz/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/uz/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -33,7 +33,7 @@ Oʻzingiz bilgan baʼzi vositalarga eʼtibor qarating:- **Repo — bu yagona haqiqat manbai (system of record)**: Agent koʻra olmaydigan har qanday narsa, amalda mavjud emas deb hisoblanadi. OpenAI repoʼni “yagona haqiqat manbai” (system of record) sifatida qabul qiladi — barcha zarur kontekst tizimlashtirilgan fayllar va tushunarli katalog strukturasi orqali shu yerda yashashi kerak.- **Qoʻllanma emas, xarita bering**: OpenAI tajribasidan — `AGENTS.md` ensiklopediya emas, balki katalog sahifasi boʻlishi kerak. Taxminan 100 qator yetarli. Agar sigʻmasa, uni `docs/` katalogiga ajrating va kerak boʻlganda agent oʻqishiga imkon bering.- **Cheklang, mikromenejment qilmang**: Yaxshi harness yoʻriqnomalarni birma-bir sanab oʻtish oʻrniga, agentʼni cheklash uchun bajariladigan qoidalardan (executable rules) foydalanadi. OpenAI “implementatsiyani mikromenejment qilmang, oʻzgarmas qoidalarni (invariants) taʼminlang” deydi; Anthropic shuni aniqladiki, agentlar oʻz ishlarini ishonch bilan maqtashadi va buning yechimi “ishni bajaradigan odam” bilan “ishni tekshiradigan odam”ni alohida ajratishdir.-- **Komponentlarni birma-bir olib tashlang**: Har bir harness komponentining qadrini oʻlchash uchun, ularni birma-bir olib tashlang va qaysi birining olib tashlanishi unumdorlikning eng katta pasayishiga olib kelishini koʻring. Anthropic bu usuldan foydalandi va shuni aniqladiki, modelʼlar kuchayib borgan sari baʼzi komponentlar oʻzining oʻta muhimligini yoʻqotadi — lekin doim yangilari paydo boʻladi.+- **Komponentlarni birma-bir olib tashlang**: Har bir harness komponentining chegaraviy hissasini oʻlchash uchun, ularni birma-bir olib tashlang va qaysi birining olib tashlanishi unumdorlikning eng katta pasayishiga olib kelishini koʻring. Anthropic bu usuldan foydalandi va shuni aniqladiki, modelʼlar kuchayib borgan sari baʼzi komponentlar oʻzining oʻta muhimligini yoʻqotadi — lekin doim yangilari paydo boʻladi.## Beshta quyi tizimli Harness modeli@@ -68,7 +68,7 @@ Tekshiruv buyruqlari:Qandaydir bir quyi tizimning yoʻqligi, xuddi oshxonada qaysidir funksional hududning yoʻqligiga oʻxshaydi — siz hali ham ovqat pishirishingiz mumkin, lekin bu doim noqulay boʻladi.-**Harness sifatini tashxis qilish**: **Izometrik model boshqaruvi** (modelni oʻzgarmas saqlab, harness komponentlarini birma-bir olib tashlab tekshirish usuli)dan foydalaning. Modelni oʻzgarishsiz qoldiring, quyi tizimlarni birma-bir olib tashlang, qaysi birining olib tashlanishi unumdorlikning eng katta pasayishiga olib kelishini oʻlchang. Bu sizning toʻsiq nuqtangiz (bottleneck) — asosiy eʼtiboringizni shu yerga qarating. Xuddi oshxonadagi toʻsiqni topishga oʻxshaydi: retseptlar javonini olib tashlang va ishlar qanchalik sekinlashishini koʻring, plitani oʻchiring va uning taʼsirini kuzating.+**Harness komponentlari qiymatini oʻlchash**: **Izometrik model boshqaruvi** (modelni oʻzgarmas saqlab, harness komponentlarini birma-bir olib tashlab tekshirish usuli)dan foydalaning. Modelni oʻzgarishsiz qoldiring, quyi tizimlarni birma-bir olib tashlang va qaysi birining olib tashlanishi unumdorlikning eng katta pasayishiga olib kelishini oʻlchang. Eng katta pasayish shu vazifada chegaraviy hissasi eng yuqori komponentni koʻrsatadi, lekin bu avtomatik ravishda toʻsiq nuqtasi degani emas. Haqiqiy toʻsiqni topish uchun tajribani muvaffaqiyatsizlik jurnallari va sababga bogʻlash bilan birlashtiring: vazifa noaniqmi, kontekst yetishmayaptimi, muhit qayta tiklanmayaptimi, tekshiruv qayta aloqasi yoʻqmi yoki holat boshqaruvi uzilganmi.## Jamoaning hayotiy misoli@@ -89,7 +89,7 @@ Toʻrtta iteratsiya, model umuman oʻzgarmadi, muvaffaqiyat koʻrsatkichi 20% da- Harness = Yoʻriqnomalar + Vositalar + Muhit + Holat + Qayta aloqa. Beshta quyi tizim, xuddi oshxonaning beshta funksional hududiga oʻxshab — barchasi zarur.- Agar bu model ogʻirliklari boʻlmasa, bu harness. Sizning harnessʼingiz model imkoniyatlarining qanchalik roʻyobga chiqishini belgilaydi.- Beshta quyi tizim ichida qayta aloqa quyi tizimi odatda eng kam xarajat va eng yuqori daromadga (ROI) ega. Avval tekshiruv buyruqlaringizni toʻgʻri sozlang — sifat nazorati oynasi eng munosib yangilanishdir.-- Har bir quyi tizimning hissasini oʻlchash uchun **izometrik model boshqaruvi**dan foydalaning — ichki sezgiga suyanmang.+- Har bir quyi tizimning chegaraviy hissasini oʻlchash uchun **izometrik model boshqaruvi**dan foydalaning; haqiqiy toʻsiqni topish uchun muvaffaqiyatsizlik jurnallari va sababga bogʻlashdan foydalaning.- Harness xuddi kod kabi eskiradi. Uni muntazam tekshirib turing, texnik qarzni toʻlaganingiz kabi harness qarzini ham toʻlab boring.## Qoʻshimcha oʻqish uchundiff --git a/docs/vi/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/vi/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex c2651f5..51e8009 100644--- a/docs/vi/lectures/lecture-01-why-capable-agents-still-fail/index.md+++ b/docs/vi/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -17,9 +17,9 @@ Nhưng đằng sau những con số này ẩn chứa một sự thật phản trAnthropic đã thực hiện một thí nghiệm có kiểm soát. Cùng một prompt ("xây dựng một trình tạo trò chơi retro 2D"), cùng một mô hình (Opus 4.5). Lần chạy đầu tiên: trần trụi, không có hỗ trợ — 20 phút, $9, các tính năng cốt lõi của trò chơi hoàn toàn không hoạt động. Lần chạy thứ hai: harness đầy đủ (kiến trúc ba agent: planner + generator + evaluator) — 6 giờ, $200, trò chơi có thể chơi được.-Họ không thay đổi mô hình. Opus 4.5 vẫn là Opus 4.5. Những gì thay đổi là cái yên ngựa.+Họ không thay đổi mô hình. Opus 4.5 vẫn là Opus 4.5. Những gì thay đổi là bộ yên cương.-Bài viết về harness engineering năm 2025 của OpenAI nói thẳng: Codex trong một kho lưu trữ được trang bị harness tốt đi từ "không đáng tin cậy" đến "đáng tin cậy." Lưu ý cách diễn đạt của họ — không phải "tốt hơn một chút," mà là một sự thay đổi về chất. Giống như một con ngựa thuần chủng: bạn có thể cưỡi nó không có yên, nhưng bạn sẽ không đi xa, không nhanh, và việc ngã ngựa không có gì là ngạc nhiên. Harness là cái yên ngựa đó — **tất cả mọi thứ trong cơ sở hạ tầng kỹ thuật bên ngoài trọng số mô hình.**+Bài viết về harness engineering năm 2025 của OpenAI nói thẳng: Codex trong một kho lưu trữ được trang bị harness tốt đi từ "không đáng tin cậy" đến "đáng tin cậy." Lưu ý cách diễn đạt của họ — không phải "tốt hơn một chút," mà là một sự thay đổi về chất. Giống như một con ngựa thuần chủng: bạn có thể cưỡi nó không có bộ yên cương phù hợp, nhưng bạn sẽ không đi xa, không nhanh, và việc ngã ngựa không có gì là ngạc nhiên. Harness là cả bộ yên cương đó — **tất cả mọi thứ trong cơ sở hạ tầng kỹ thuật bên ngoài trọng số mô hình.**## Agent Thực sự Bị Kẹt Ở Đâu@@ -40,7 +40,7 @@ Các tác vụ dài trải dài qua nhiều phiên còn tệ hơn — tất cảVới những tình huống này, các khái niệm sau không còn chỉ là thuật ngữ nữa:- **Khoảng cách Năng lực (Capability Gap)**: Khoảng cách lớn giữa hiệu suất mô hình trên các điểm chuẩn và hiệu suất trên các tác vụ thực tế. Tỷ lệ vượt qua 50-60% trên SWE-bench Verified có nghĩa là gần một nửa số vấn đề thực tế không thể được giải quyết.-- **Harness**: Mọi thứ bên ngoài mô hình — hướng dẫn, công cụ, môi trường, quản lý trạng thái, phản hồi xác minh. Nếu không phải trọng số mô hình, thì đó là harness. Đó là cái chúng ta gọi là "yên ngựa."+- **Harness**: Mọi thứ bên ngoài mô hình — hướng dẫn, công cụ, môi trường, quản lý trạng thái, phản hồi xác minh. Nếu không phải trọng số mô hình, thì đó là harness. Đó là cái chúng ta gọi là "bộ yên cương."- **Lỗi Do Harness (Harness-Induced Failure)**: Mô hình có đủ năng lực, nhưng môi trường thực thi có khiếm khuyết cấu trúc. Thí nghiệm có kiểm soát của Anthropic đã chứng minh điều này.- **Khoảng cách Xác minh (Verification Gap)**: Khoảng cách giữa sự tự tin của agent vào kết quả của nó và tính đúng đắn thực tế. Agent nói "tôi đã xong" khi chưa xong — đây là chế độ lỗi phổ biến nhất.- **Vòng lặp Chẩn đoán (Diagnostic Loop)**: Thực thi, quan sát lỗi, quy cho một lớp harness cụ thể, sửa lớp đó, thực thi lại. Đây là phương pháp luận cốt lõi của harness engineering.@@ -52,7 +52,7 @@ Nguyên tắc cốt lõi: **Khi sự cố xảy ra, đừng đổi mô hình trCác bước cụ thể:-**Quy mọi lỗi cho một lớp cụ thể.** Đừng chỉ nói "mô hình không tốt." Hãy hỏi: tác vụ có mơ hồ không? Ngữ cảnh có không đủ không? Không có phương pháp xác minh không? Ánh xạ mỗi lỗi vào một trong năm lớp phòng thủ (đặc tả tác vụ, cung cấp ngữ cảnh, môi trường thực thi, phản hồi xác minh, quản lý trạng thái). Xây dựng thói quen này, và bạn sẽ thấy "mô hình không đủ tốt" xuất hiện ngày càng ít hơn trong nhật ký của bạn.+**Quy mọi lỗi cho một lớp cụ thể.** Đừng chỉ nói "mô hình không tốt." Hãy hỏi: tác vụ có mơ hồ không? Ngữ cảnh có không đủ không? Không có phương pháp xác minh không? Ánh xạ mỗi lỗi vào một trong năm lớp phòng thủ: đặc tả tác vụ, cung cấp ngữ cảnh, môi trường thực thi, phản hồi xác minh, quản lý trạng thái. Đây là các lớp chẩn đoán thực hành, không phải sáu thuật ngữ trong phần thuật ngữ phía trên. Xây dựng thói quen này, và bạn sẽ thấy "mô hình không đủ tốt" xuất hiện ngày càng ít hơn trong nhật ký của bạn.**Viết Định nghĩa Hoàn thành rõ ràng cho mỗi tác vụ.** Đừng nói "thêm tính năng tìm kiếm." Hãy nói:```@@ -94,7 +94,7 @@ Họ không thay đổi mô hình. Họ thay đổi harness.## Những Điểm chính cần Nhớ-- Năng lực mô hình và độ tin cậy thực thi là hai điều khác nhau. Một con ngựa thuần chủng vẫn cần một cái yên tốt.+- Năng lực mô hình và độ tin cậy thực thi là hai điều khác nhau. Một con ngựa thuần chủng vẫn cần bộ yên cương tốt.- Khi sự cố xảy ra, kiểm tra harness trước, rồi mới đến mô hình. Đổi mô hình là lựa chọn tốn kém nhất — và thường thậm chí không phải là vấn đề mô hình.- Mỗi lỗi là một tín hiệu: harness của bạn có khiếm khuyết cấu trúc. Tìm nó, sửa nó.- Năm lớp phòng thủ: đặc tả tác vụ, cung cấp ngữ cảnh, môi trường thực thi, phản hồi xác minh, quản lý trạng thái. Kiểm tra chúng có hệ thống, như bác sĩ loại trừ các nguyên nhân phổ biến nhất trước.diff --git a/docs/vi/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/vi/lectures/lecture-02-what-a-harness-actually-is/index.mdindex b6f4dd6..3630c06 100644--- a/docs/vi/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/vi/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -33,7 +33,7 @@ Nhìn vào một số công cụ bạn đã biết:- **Repo là nguồn sự thật duy nhất**: Bất cứ thứ gì agent không thể nhìn thấy, theo mọi nghĩa thực tế, không tồn tại. OpenAI coi repo là "hệ thống ghi chép" — tất cả ngữ cảnh cần thiết phải sống ở đó, qua các tệp có cấu trúc và tổ chức thư mục rõ ràng.- **Đưa bản đồ, không phải cẩm nang**: Kinh nghiệm của OpenAI — `AGENTS.md` nên là một trang thư mục, không phải bách khoa toàn thư. Khoảng 100 dòng là đủ. Nếu không vừa, chia vào thư mục `docs/` và để agent đọc theo yêu cầu.- **Ràng buộc, không vi quản lý**: Một harness tốt sử dụng các quy tắc có thể thực thi để ràng buộc agent, thay vì liệt kê hướng dẫn từng cái một. OpenAI nói "thực thi các bất biến, không vi quản lý triển khai"; Anthropic phát hiện rằng các agent tự tin khen ngợi công việc của chính mình, và giải pháp là tách "người làm việc" khỏi "người kiểm tra công việc."-- **Xóa từng thành phần một**: Để định lượng giá trị của từng thành phần harness, hãy xóa chúng từng cái một và xem cái nào bị xóa gây ra giảm hiệu suất lớn nhất. Anthropic đã sử dụng phương pháp này và phát hiện ra rằng khi các mô hình trở nên mạnh hơn, một số thành phần không còn quan trọng — nhưng các thành phần mới luôn xuất hiện.+- **Xóa từng thành phần một**: Để định lượng đóng góp biên của từng thành phần harness, hãy xóa chúng từng cái một và xem cái nào bị xóa gây ra giảm hiệu suất lớn nhất. Anthropic đã sử dụng phương pháp này và phát hiện ra rằng khi các mô hình trở nên mạnh hơn, một số thành phần không còn quan trọng — nhưng các thành phần mới luôn xuất hiện.## Mô hình Harness Năm Hệ thống Phụ@@ -68,7 +68,7 @@ Lệnh xác minh:Thiếu bất kỳ hệ thống phụ nào cũng giống như thiếu một khu vực chức năng trong nhà bếp — bạn vẫn có thể nấu ăn, nhưng luôn gượng gạo.-**Chẩn đoán chất lượng harness**: Sử dụng "kiểm soát mô hình đẳng áp." Giữ nguyên mô hình, xóa từng hệ thống phụ một, đo xem cái nào bị xóa gây ra giảm hiệu suất lớn nhất. Đó là điểm nghẽn cổ chai của bạn — tập trung nỗ lực ở đó. Giống như tìm điểm nghẽn cổ chai trong nhà bếp: lấy kệ công thức đi và xem mọi thứ chậm lại bao nhiêu, tắt bếp và xem tác động.+**Định lượng giá trị thành phần harness**: Sử dụng "kiểm soát mô hình đẳng áp." Giữ nguyên mô hình, xóa từng hệ thống phụ một và đo xem cái nào bị xóa gây ra giảm hiệu suất lớn nhất. Mức giảm lớn nhất cho biết thành phần có đóng góp biên cao nhất trong tác vụ đó, không tự động là điểm nghẽn cổ chai. Để xác định điểm nghẽn thật, hãy kết hợp thí nghiệm với nhật ký lỗi và quy kết nguyên nhân: tác vụ mơ hồ, thiếu ngữ cảnh, môi trường không tái lập được, thiếu phản hồi xác minh, hoặc quản lý trạng thái bị đứt gãy.## Câu chuyện Thực tế của Một Nhóm@@ -89,7 +89,7 @@ Bốn lần lặp, mô hình hoàn toàn không thay đổi, tỷ lệ thành c- Harness = Hướng dẫn + Công cụ + Môi trường + Trạng thái + Phản hồi. Năm hệ thống phụ, như năm khu vực chức năng của nhà bếp — tất cả đều cần thiết.- Nếu không phải trọng số mô hình, thì đó là harness. Harness của bạn xác định mức độ năng lực mô hình được hiện thực hóa bao nhiêu.- Trong số năm hệ thống phụ, hệ thống phụ phản hồi thường có đầu tư thấp nhất và lợi nhuận cao nhất. Đặt đúng các lệnh xác minh trước — cửa sổ kiểm tra chất lượng là bản nâng cấp đáng giá nhất.-- Sử dụng "kiểm soát mô hình đẳng áp" để định lượng đóng góp biên của mỗi hệ thống phụ — đừng dựa vào trực giác.+- Sử dụng "kiểm soát mô hình đẳng áp" để định lượng đóng góp biên của mỗi hệ thống phụ; dùng nhật ký lỗi và quy kết nguyên nhân để xác định điểm nghẽn thật.- Harness mục nát như mã nguồn. Kiểm tra thường xuyên, trả nợ harness như bạn trả nợ kỹ thuật.## Đọc thêmdiff --git a/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex 14e87d8..32e8cc6 100644--- a/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/index.md+++ b/docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -17,9 +17,9 @@Anthropic 做過一個對照實驗。同一個 prompt("做一個 2D 復古遊戲編輯器"),同一個模型(Opus 4.5)。第一次讓它裸跑——20 分鐘,花了 $9,遊戲核心功能根本跑不起來。第二次給它配上完整的 harness(planner + generator + evaluator 三 agent 架構)——6 小時,花了 $200,遊戲可以正常遊玩。-模型沒換。Opus 4.5 還是那個 Opus 4.5。換的是馬鞍。+模型沒換。Opus 4.5 還是那個 Opus 4.5。換的是馬具。-OpenAI 在 2025 年發佈的 harness engineering 文章裡說得更直白:Codex 在一個 harness 搭得好的倉庫裡,表現能從"不可靠"變成"可靠"。注意他們的用詞——不是"好了一點",是質變。就像一匹千裡馬,沒馬鞍你也能騎,但騎不了多遠、跑不了多快、摔下來也不稀奇。harness 就是那個馬鞍——**模型權重之外的一切工程基礎設施**。+OpenAI 在 2025 年發佈的 harness engineering 文章裡說得更直白:Codex 在一個 harness 搭得好的倉庫裡,表現能從"不可靠"變成"可靠"。注意他們的用詞——不是"好了一點",是質變。就像一匹千裡馬,沒馬具你也能騎,但控不穩、走不遠、摔下來也不稀奇。harness 就是那整套馬具——**模型權重之外的一切工程基礎設施**。## agent 到底卡在哪@@ -40,7 +40,7 @@ OpenAI 在 2025 年發佈的 harness engineering 文章裡說得更直白:Code理解了上面的場景,這些概念就不再是一堆術語了:- **能力鴻溝(Capability Gap)**:模型在基準測試上的表現和真實任務上的表現之間的巨大落差。SWE-bench Verified 上 50-60% 的通過率意味著近一半的真實 issue 解不了。-- **Harness**:模型之外的一切——指令、工具、環境、狀態管理、驗證反饋。不是模型權重的部分,全是 harness。也就是我們說的"馬鞍"。+- **Harness**:模型之外的一切——指令、工具、環境、狀態管理、驗證反饋。不是模型權重的部分,全是 harness。也就是我們說的"馬具"。- **Harness 誘導失敗**:模型本身能力足夠,但因為執行環境有結構性缺陷而失敗。Anthropic 的對照實驗已經證明了這一點。- **驗證缺口**:agent 對自己輸出的信心評估和實際正確性之間的偏差。agent 說"我做完了"但實際沒做完——這是最常見的失敗模式。- **診斷循環**:執行 → 觀察失敗 → 定位到 harness 的哪一層出了問題 → 修補那一層 → 重新執行。這是 harness 工程的核心方法論。@@ -52,7 +52,7 @@ OpenAI 在 2025 年發佈的 harness engineering 文章裡說得更直白:Code具體怎麼做:-**每次失敗都歸因到具體層。** 不要籠統地說"模型不行",而是問:是任務沒說清楚?是上下文不夠?是沒有驗證手段?把每次失敗歸到五層防禦(任務規範、上下文供給、執行環境、驗證反饋、狀態管理)中的某一層。養成這個習慣,你會發現"模型不行"這個結論在你的日誌裡出現得越來越少。+**每次失敗都歸因到具體層。** 不要籠統地說"模型不行",而是問:是任務沒說清楚?是上下文不夠?是沒有驗證手段?把每次失敗歸到五層防禦:任務規範、上下文供給、執行環境、驗證反饋、狀態管理。這裡說的是實操診斷用的五層防禦,不是上面那組六個術語。養成這個習慣,你會發現"模型不行"這個結論在你的日誌裡出現得越來越少。**給每個任務寫顯式的完成定義。** 不要說"加個搜索功能",要說:```@@ -94,7 +94,7 @@ OpenAI 在 2025 年做了一個激進的實驗:用 Codex 從一個空的 git## 帶走什麼-- 模型能力和執行可靠性是兩回事。千裡馬也得配上好馬鞍。+- 模型能力和執行可靠性是兩回事。千裡馬也得配上好馬具。- 失敗的時候先看 harness,再看模型。換模型是成本最高的選擇——而且很多時候根本不是模型的問題。- 每次失敗都是一個信號:你的 harness 有結構性缺陷。把它找出來、修掉。- 五層防禦:任務規範、上下文供給、執行環境、驗證反饋、狀態管理。逐層排查,就像醫生看病先檢查最常見的病因。diff --git a/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/index.mdindex 6e90e95..0d6c8bc 100644--- a/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -33,7 +33,7 @@ OpenAI 在他們的 harness engineering 文章裡把 harness 的核心原則表- **倉庫是唯一事實來源**:agent 看不到的東西,對它來說就不存在。OpenAI 把倉庫當作"記錄系統"——所有必要的上下文都必須在倉庫裡,通過結構化的檔案和清晰的目錄組織來呈現。- **給地圖,不給說明書**:OpenAI 的經驗——`AGENTS.md` 應該是目錄頁,不是百科全書。100 行左右就夠了,放不下就拆分到 `docs/` 目錄裡,讓 agent 按需去讀。- **約束而非微操**:好的 harness 用可執行的規則來約束 agent,而不是在指令裡逐條叮囑。OpenAI 說"執行不變量,不要微管實現";Anthropic 發現 agent 會自信地誇讚自己的工作,解決方案是把"幹活的人"和"檢查的人"分開。-- **逐個組件拆除法**:想量化 harness 各組件的價值,就逐個移除,看哪個移除後性能下降最多。Anthropic 用這個方法發現:隨著模型變強,某些組件不再關鍵,但總會有新的關鍵組件出現。+- **逐個組件拆除法**:想量化 harness 各組件的邊際貢獻,就逐個移除,看哪個移除後性能下降最多。它能告訴你哪些組件當前最有價值,也能暴露哪些組件暫時貢獻不明顯。Anthropic 用這個方法發現:隨著模型變強,某些組件不再關鍵,但總會有新的關鍵組件出現。## Harness 五子系統模型@@ -68,7 +68,7 @@ flowchart LR五個子系統缺一個,就像廚房裡少了一個功能區——菜還是能做,但總是彆扭。-**診斷 harness 質量的方法**:用"等模型對照實驗"。保持模型不變,逐個移除五個子系統,看哪個子系統缺失時性能下降最多。那個就是你的瓶頸——集中精力加強它。就像找廚房的瓶頸一樣:把菜譜架拿走看看出菜速度降多少,把灶臺關掉看看影響多大。+**量化 harness 組件價值的方法**:用"等模型對照實驗"。保持模型不變,逐個移除五個子系統,看哪個子系統缺失時性能下降最多。下降最多的組件,說明它在當前任務裡邊際貢獻最大,應該優先保護和加強;幾乎沒有影響的組件,則可能是冗餘、設計失效,或還沒有被任務充分觸發。它不能單獨證明"瓶頸在哪裡"。真正定位瓶頸,還要結合失敗記錄和歸因:任務沒說清楚、上下文不足、環境不可復現、驗證反饋缺失,還是狀態管理斷裂。## 一個團隊的真實經歷@@ -89,7 +89,7 @@ flowchart LR- Harness = 指令 + 工具 + 環境 + 狀態 + 反饋。五個子系統,就像廚房的五個功能區,缺一不可。- 不是模型權重的部分全是 harness。你的 harness 決定了模型能力能被髮揮多少。- 五個子系統中,反饋子系統通常是投入最少、回報最高的。先把驗證命令寫清楚——出菜檢查口是最值得先裝的。-- 用"等模型對照實驗"量化各子系統的邊際貢獻,別憑感覺。+- 用"等模型對照實驗"量化各子系統的邊際貢獻,別憑感覺;用失敗記錄和歸因定位真正的瓶頸。- Harness 和代碼一樣會腐化。定期審計,像還技術債一樣還 harness 債。## 延伸閱讀diff --git a/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex fe81b88..2a2d3dd 100644--- a/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md+++ b/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md@@ -17,9 +17,9 @@Anthropic 做过一个对照实验。同一个 prompt("做一个 2D 复古游戏编辑器"),同一个模型(Opus 4.5)。第一次让它裸跑——20 分钟,花了 $9,游戏核心功能根本跑不起来。第二次给它配上完整的 harness(planner + generator + evaluator 三 agent 架构)——6 小时,花了 $200,游戏可以正常游玩。-模型没换。Opus 4.5 还是那个 Opus 4.5。换的是马鞍。+模型没换。Opus 4.5 还是那个 Opus 4.5。换的是马具。-OpenAI 在 2025 年发布的 harness engineering 文章里说得更直白:Codex 在一个 harness 搭得好的仓库里,表现能从"不可靠"变成"可靠"。注意他们的用词——不是"好了一点",是质变。就像一匹千里马,没马鞍你也能骑,但骑不了多远、跑不了多快、摔下来也不稀奇。harness 就是那个马鞍——**模型权重之外的一切工程基础设施**。+OpenAI 在 2025 年发布的 harness engineering 文章里说得更直白:Codex 在一个 harness 搭得好的仓库里,表现能从"不可靠"变成"可靠"。注意他们的用词——不是"好了一点",是质变。就像一匹千里马,没马具你也能骑,但控不稳、走不远、摔下来也不稀奇。harness 就是那整套马具——**模型权重之外的一切工程基础设施**。## agent 到底卡在哪@@ -40,7 +40,7 @@ OpenAI 在 2025 年发布的 harness engineering 文章里说得更直白:Code理解了上面的场景,这些概念就不再是一堆术语了:- **能力鸿沟(Capability Gap)**:模型在基准测试上的表现和真实任务上的表现之间的巨大落差。SWE-bench Verified 上 50-60% 的通过率意味着近一半的真实 issue 解不了。-- **Harness**:模型之外的一切——指令、工具、环境、状态管理、验证反馈。不是模型权重的部分,全是 harness。也就是我们说的"马鞍"。+- **Harness**:模型之外的一切——指令、工具、环境、状态管理、验证反馈。不是模型权重的部分,全是 harness。也就是我们说的"马具"。- **Harness 诱导失败**:模型本身能力足够,但因为执行环境有结构性缺陷而失败。Anthropic 的对照实验已经证明了这一点。- **验证缺口**:agent 对自己输出的信心评估和实际正确性之间的偏差。agent 说"我做完了"但实际没做完——这是最常见的失败模式。- **诊断循环**:执行 → 观察失败 → 定位到 harness 的哪一层出了问题 → 修补那一层 → 重新执行。这是 harness 工程的核心方法论。@@ -52,7 +52,7 @@ OpenAI 在 2025 年发布的 harness engineering 文章里说得更直白:Code具体怎么做:-**每次失败都归因到具体层。** 不要笼统地说"模型不行",而是问:是任务没说清楚?是上下文不够?是没有验证手段?把每次失败归到五层防御(任务规范、上下文供给、执行环境、验证反馈、状态管理)中的某一层。养成这个习惯,你会发现"模型不行"这个结论在你的日志里出现得越来越少。+**每次失败都归因到具体层。** 不要笼统地说"模型不行",而是问:是任务没说清楚?是上下文不够?是没有验证手段?把每次失败归到五层防御:任务规范、上下文供给、执行环境、验证反馈、状态管理。这里说的是实操诊断用的五层防御,不是上面那组六个术语。养成这个习惯,你会发现"模型不行"这个结论在你的日志里出现得越来越少。**给每个任务写显式的完成定义。** 不要说"加个搜索功能",要说:```@@ -94,7 +94,7 @@ OpenAI 在 2025 年做了一个激进的实验:用 Codex 从一个空的 git## 带走什么-- 模型能力和执行可靠性是两回事。千里马也得配上好马鞍。+- 模型能力和执行可靠性是两回事。千里马也得配上好马具。- 失败的时候先看 harness,再看模型。换模型是成本最高的选择——而且很多时候根本不是模型的问题。- 每次失败都是一个信号:你的 harness 有结构性缺陷。把它找出来、修掉。- 五层防御:任务规范、上下文供给、执行环境、验证反馈、状态管理。逐层排查,就像医生看病先检查最常见的病因。diff --git a/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.mdindex 12c7f11..de9c528 100644--- a/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -33,7 +33,7 @@ OpenAI 在他们的 harness engineering 文章里把 harness 的核心原则表- **仓库是唯一事实来源**:agent 看不到的东西,对它来说就不存在。OpenAI 把仓库当作"记录系统"——所有必要的上下文都必须在仓库里,通过结构化的文件和清晰的目录组织来呈现。- **给地图,不给说明书**:OpenAI 的经验——`AGENTS.md` 应该是目录页,不是百科全书。100 行左右就够了,放不下就拆分到 `docs/` 目录里,让 agent 按需去读。- **约束而非微操**:好的 harness 用可执行的规则来约束 agent,而不是在指令里逐条叮嘱。OpenAI 说"执行不变量,不要微管实现";Anthropic 发现 agent 会自信地夸赞自己的工作,解决方案是把"干活的人"和"检查的人"分开。-- **逐个组件拆除法**:想量化 harness 各组件的价值,就逐个移除,看哪个移除后性能下降最多。Anthropic 用这个方法发现:随着模型变强,某些组件不再关键,但总会有新的关键组件出现。+- **逐个组件拆除法**:想量化 harness 各组件的边际贡献,就逐个移除,看哪个移除后性能下降最多。它能告诉你哪些组件当前最有价值,也能暴露哪些组件暂时贡献不明显。Anthropic 用这个方法发现:随着模型变强,某些组件不再关键,但总会有新的关键组件出现。## Harness 五子系统模型@@ -68,7 +68,7 @@ flowchart LR五个子系统缺一个,就像厨房里少了一个功能区——菜还是能做,但总是别扭。-**诊断 harness 质量的方法**:用"等模型对照实验"。保持模型不变,逐个移除五个子系统,看哪个子系统缺失时性能下降最多。那个就是你的瓶颈——集中精力加强它。就像找厨房的瓶颈一样:把菜谱架拿走看看出菜速度降多少,把灶台关掉看看影响多大。+**量化 harness 组件价值的方法**:用"等模型对照实验"。保持模型不变,逐个移除五个子系统,看哪个子系统缺失时性能下降最多。下降最多的组件,说明它在当前任务里边际贡献最大,应该优先保护和加强;几乎没有影响的组件,则可能是冗余、设计失效,或还没有被任务充分触发。它不能单独证明"瓶颈在哪里"。真正定位瓶颈,还要结合失败记录和归因:任务没说清楚、上下文不足、环境不可复现、验证反馈缺失,还是状态管理断裂。## 一个团队的真实经历@@ -89,7 +89,7 @@ flowchart LR- Harness = 指令 + 工具 + 环境 + 状态 + 反馈。五个子系统,就像厨房的五个功能区,缺一不可。- 不是模型权重的部分全是 harness。你的 harness 决定了模型能力能被发挥多少。- 五个子系统中,反馈子系统通常是投入最少、回报最高的。先把验证命令写清楚——出菜检查口是最值得先装的。-- 用"等模型对照实验"量化各子系统的边际贡献,别凭感觉。+- 用"等模型对照实验"量化各子系统的边际贡献,别凭感觉;用失败记录和归因定位真正的瓶颈。- Harness 和代码一样会腐化。定期审计,像还技术债一样还 harness 债。## 延伸阅读