Skip to content

Harness engineering beginner tutorial, from 0 to 1

docs: correct cited course data across 15 locales (#92)

Sanbu 散步a9342ff471f2
diff --git a/docs/.vitepress/anchor-map.json b/docs/.vitepress/anchor-map.json
index d26b921..84e08c9 100644
--- a/docs/.vitepress/anchor-map.json
+++ b/docs/.vitepress/anchor-map.json
@@ -1407,7 +1407,7 @@
"how-goal-grew-organically",
"there-s-more-than-one-kind-of-loop",
"don-t-confuse-goal-and-loop",
- "june-2026-three-people-lit-the-same-fuse-in-one-week",
+ "different-dates-the-same-direction",
"inside-the-loop-vs-outside-the-loop",
"core-concepts",
"the-six-primitives-of-a-loop",
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.md
index 552328c..3f739e4 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
@@ -9,13 +9,13 @@
غريزتك الأولى؟ "هذا النموذج ليس جيدًا بما يكفي. حان وقت الترقية." تمهل. قبل أن تمد يدك إلى محفظتك، فكّر في احتمال أن المشكلة ليست في النموذج أصلًا.
-لننظر إلى بعض الأرقام. بحلول أواخر عام 2025، كانت أقوى وكلاء البرمجة على SWE-bench Verified تحقق تقريبًا 50-60%. وهذا على مهام مختارة بعناية، مع أوصاف Issues واضحة وحالات اختبار موجودة. انقل الأمر إلى بيئة تطويرك اليومية - متطلبات غامضة، لا اختبارات جاهزة، وقواعد عمل ضمنية مبعثرة في كل مكان - وستنخفض هذه النسبة أكثر.
+لننظر إلى بعض الأرقام. في 29 سبتمبر 2025، أعلنت Anthropic أن Claude Sonnet 4.5 يحقق [77.2% على SWE-bench Verified](https://www.anthropic.com/news/claude-sonnet-4-5). وهذا على مهام مختارة بعناية، مع أوصاف Issues واضحة وحالات اختبار موجودة. انقل الأمر إلى بيئة تطويرك اليومية - متطلبات غامضة، لا اختبارات جاهزة، وقواعد عمل ضمنية مبعثرة في كل مكان - وستنخفض هذه النسبة أكثر.
لكن خلف هذه الأرقام توجد حقيقة غير بديهية.
## الحصان نفسه، مصائر مختلفة
-أجرت Anthropic تجربة مضبوطة. المطالبة نفسها ("ابنِ صانع ألعاب ريترو ثنائية الأبعاد")، والنموذج نفسه (Opus 4.5). التشغيل الأول: عارٍ بلا دعم - 20 دقيقة، 9 دولارات، والميزات الأساسية للعبة لم تعمل إطلاقًا. التشغيل الثاني: Harness كامل (مخطط + مولد + مقيم في بنية من ثلاثة وكلاء) - 6 ساعات، 200 دولار، وأصبحت اللعبة قابلة للعب.
+قارنت Anthropic المطالبة نفسها ("ابنِ صانع ألعاب ريترو ثنائية الأبعاد") والنموذج نفسه (Opus 4.5) في إعدادين مختلفين للـ Harness. التشغيل الأول: عارٍ بلا دعم - 20 دقيقة، 9 دولارات؛ فتح التطبيق، لكن الكيانات لم تستجب للمدخلات. التشغيل الثاني: Harness كامل (مخطط + مولد + مقيم في بنية من ثلاثة وكلاء) - 6 ساعات، 200 دولار؛ استطاع المؤلف تحريك كيان، لكن الفيزياء كانت خشنة وجدار أعاق التقدم. [عملت اللعبة الأساسية؛ لكن التطبيق لم يكتمل.](https://www.anthropic.com/engineering/harness-design-long-running-apps)
لم يغيروا النموذج. بقي Opus 4.5 هو Opus 4.5. ما تغيّر هو العدة الكاملة للفرس.
@@ -39,9 +39,9 @@
مع هذه السيناريوهات في الذهن، لم تعد هذه المفاهيم مجرد مصطلحات:
-- **Capability Gap**: الفجوة الكبيرة بين أداء النموذج على المعايير القياسية وأدائه في المهام الحقيقية. معدل نجاح 50-60% على SWE-bench Verified يعني أن قرابة نصف القضايا الحقيقية لا تُحل.
+- **Capability Gap**: الفجوة الكبيرة بين أداء النموذج على المعايير القياسية وأدائه في المهام الحقيقية. مهام المعايير تأتي مع أوصاف واضحة للقضايا واختبارات وبيئة جاهزة؛ أما المهام الحقيقية فغالبًا تتطلب منك توفيرها.
- **Harness**: كل ما هو خارج النموذج - التعليمات، الأدوات، البيئة، إدارة الحالة، وتغذية التحقق الراجعة. إن لم يكن من أوزان النموذج فهو جزء من الـ Harness. هذه هي "العدة الكاملة" التي نتحدث عنها.
-- **Harness-Induced Failure**: لدى النموذج قدرة كافية، لكن بيئة التنفيذ فيها عيوب بنيوية. تجربة Anthropic المضبوطة أثبتت ذلك بالفعل.
+- **Harness-Induced Failure**: لدى النموذج قدرة كافية، لكن بيئة التنفيذ فيها عيوب بنيوية. مقارنة اللعبة الريترو أعلاه مثال على ذلك.
- **Verification Gap**: الفجوة بين ثقة الوكيل في مخرجاته والصحة الفعلية. يقول الوكيل "انتهيت" وهو لم ينتهِ - وهذا هو نمط الفشل الأكثر شيوعًا.
- **Diagnostic Loop**: نفّذ، لاحظ الفشل، انسبه إلى طبقة Harness محددة، أصلح تلك الطبقة، ثم نفّذ مرة أخرى. هذه هي المنهجية الأساسية لهندسة الـ Harness.
- **Definition of Done**: مجموعة شروط قابلة للتحقق آليًا - الاختبارات تمر، الـ lint نظيف، وفحوصات الأنواع ناجحة. من دون Definition of Done صريحة، سيخترع الوكيل تعريفه الخاص.
@@ -72,7 +72,7 @@ Completion criteria:
## تجربة المليون سطر
-أجرت OpenAI في 2025 تجربة جريئة: استخدام Codex لبناء منتج داخلي كامل من مستودع Git فارغ. بعد خمسة أشهر، احتوى المستودع على نحو مليون سطر كود - منطق تطبيق، بنية تحتية، أدوات، توثيق، وأدوات تطوير داخلية - كلها مولدة بواسطة الوكلاء. قاد ثلاثة مهندسين Codex، وفتحوا ودمجوا نحو 1,500 Pull Request. بمعدل 3.5 Pull Request لكل شخص يوميًا.
+في أغسطس 2025، بدأ ثلاثة مهندسين في OpenAI تجربة جريئة: استخدام Codex لبناء منتج داخلي كامل انطلاقًا من مستودع Git فارغ. بعد خمسة أشهر، [احتوى المستودع على نحو مليون سطر كود](https://openai.com/index/harness-engineering/) - منطق تطبيق، بنية تحتية، أدوات، توثيق، وأدوات تطوير داخلية - كلها مولدة بواسطة الوكلاء. توسع الفريق لاحقًا إلى سبعة مهندسين، وعلى مدى الفترة دمج نحو 1,500 Pull Request بمعدل 3.5 لكل مهندس يوميًا.
القيد الأساسي: **البشر لا يكتبون الكود مباشرة أبدًا.** لم تكن هذه حيلة، بل صُممت لإجبار الفريق على فهم ما يتغير عندما لا تكون وظيفة المهندس الأساسية هي كتابة الكود، بل تصميم البيئات، وصياغة النية، وبناء حلقات التغذية الراجعة.
@@ -86,9 +86,9 @@ Completion criteria:
استخدم فريق Claude Sonnet لإضافة نقطة API جديدة إلى تطبيق ويب Python متوسط الحجم (FastAPI + PostgreSQL + Redis، نحو 15,000 سطر كود).
-في البداية أعطوه جملة واحدة فقط: "add user preferences endpoints under `/api/v2/users`." النتيجة؟ استهلك الوكيل 40% من نافذة السياق في استكشاف بنية المستودع، وأنتج كودًا يبدو معقولًا لكنه لا يتبع أنماط معالجة الأخطاء في المشروع، واستخدم صيغة SQLAlchemy قديمة، وأعلن الانتهاء رغم أن نقطة النهاية كانت تحتوي على أخطاء تشغيل. اضطرت الجلسة التالية إلى إعادة كل عمل الاكتشاف.
+في البداية أعطوه جملة واحدة فقط: "add user preferences endpoints under `/api/v2/users`." النتيجة؟ استهلك الوكيل جزءًا كبيرًا من الجلسة في استكشاف بنية المستودع، وأنتج كودًا يبدو معقولًا لكنه لا يتبع أنماط معالجة الأخطاء في المشروع، واستخدم صيغة SQLAlchemy قديمة، وأعلن الانتهاء رغم أن نقطة النهاية كانت تحتوي على أخطاء تشغيل. اضطرت الجلسة التالية إلى إعادة كل عمل الاكتشاف.
-لاحقًا أضافوا `AGENTS.md` (يصف معمارية المشروع وإصدارات مكدس التقنية)، وأوامر تحقق صريحة (`pytest tests/api/v2/ && python -m mypy src/`)، وسجلات قرارات معمارية. نجح النموذج نفسه في الجولات الثلاث المستقلة كلها، مع كفاءة سياق أفضل بنحو 60%.
+لاحقًا أضافوا `AGENTS.md` (يصف معمارية المشروع وإصدارات مكدس التقنية)، وأوامر تحقق صريحة (`pytest tests/api/v2/ && python -m mypy src/`)، وسجلات قرارات معمارية. ثم اتبع النموذج نفسه أعراف المشروع وتحقق من عمله بالأوامر التي يستطيع تشغيلها.
لم يغيروا النموذج. غيّروا الـ Harness.
diff --git a/docs/ar/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/ar/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
index 599d422..e353287 100644
--- a/docs/ar/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
+++ b/docs/ar/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -52,7 +52,7 @@ flowchart LR
- **نوافذ السياق محدودة**: مهما كان حجم النافذة المُعلن عنه (128K، 200K، 1M)، المهام الطويلة ستستنزفها في النهاية. بعد الاستنفاد، يلزم إما ضغط (فقدان معلومات) أو إعادة تعيين (جلسة جديدة). كلاهما يفقد شيئًا ما.
- **مخرجات الاستمرارية**: ملفات حالة محفوظة تتيح لجلسة جديدة استئناف ما توقف عنده الجلسة السابقة بدون لبس. الشكل الأساسي: سجل تقدم + سجل تحقق + إجراءات تالية. مذكرة ذلك الحرفي.
-- **تكلفة إعادة البناء**: الوقت الذي تحتاجه جلسة جديدة للوصول إلى حالة قابلة للتنفيذ. harness الجيد يمكن أن يضغط تكلفة إعادة البناء من 15 دقيقة إلى 3 دقائق.
+- **تكلفة إعادة البناء**: الوقت الذي تحتاجه جلسة جديدة للوصول إلى حالة قابلة للتنفيذ. الـ harness الجيد يترك التقدم ونتائج التحقق والخطوات التالية في ملفات، فتبدأ الجلسة الجديدة من حالة مكتوبة.
- **الانحراف**: الفجوة بين فهم الوكيل والحالة الفعلية لمستودع الكود. كل حد جلسة يُدخل انحرافًا؛ بدون تحكم، يتراكم.
- **قلق السياق**: ظاهرة رصدتها Anthropic — يُظهر الوكلاء سلوك التقارب المبكر عند اقترابهم من حدود السياق المتوقعة، منهين المهام مبكرًا لتجنب فقدان المعلومات. إنه قلق موارد غير عقلاني.
- **الضغط مقابل إعادة التعيين**: الضغط يُلخص السياق داخل نفس الجلسة (يحافظ على "الماذا"، قد يفقد "السبب")؛ إعادة التعيين تفتح جلسة جديدة تعيد البناء من المخرجات المحفوظة (نظيفة لكنها تعتمد على اكتمال المخرجات).
@@ -160,7 +160,7 @@ flowchart LR
- نوافذ السياق مورد محدود. المهام الطويلة ستمتد عبر جلسات، والجلسات ستفقد معلومات — مثل الحرفي الذي ينسى كل يوم، هذا واقع موضوعي.
- الحل ليس نوافذ أكبر — بل استمرارية حالة أفضل. ملفات التقدم + سجلات القرارات + نقاط فحص git — أعطِ الحرفي المصاب بفقدان الذاكرة مذكرة موثوقة.
- عامل الوكيل كمهندس مصاب بفقدان الذاكرة: قبل "انتهاء الدوام"، اكتب ما تم إنجازه، ولماذا، وما التالي.
-- تكلفة إعادة البناء هي المقياس الأساسي. harness الجيد يجب أن يوصل الجلسات الجديدة إلى حالة قابلة للتنفيذ خلال 3 دقائق.
+- تكلفة إعادة البناء هي المقياس الأساسي. الـ harness الجيد يترك التقدم ونتائج التحقق والخطوات التالية في ملفات، فتتعافى الجلسة الجديدة بسرعة.
- الاستراتيجية المختلطة: مهام قصيرة ضمن الجلسات، مهام طويلة مع مخرجات منظمة للاستمرارية.
## قراءات إضافية
diff --git a/docs/ar/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/ar/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
index 2394b6d..8286455 100644
--- a/docs/ar/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
+++ b/docs/ar/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -37,7 +37,7 @@ flowchart TB
## ماذا يحدث عند خلطهما
-المشكلة الأكثر مباشرة: الأساس لا يتصلب بشكل صحيح. الوكيل ينفق 80% من جهده على كود الميزات و20% في إعداد بعض البنية التحتية بشكل عابر. إطار الاختبار مضبوط لكن لم يُتحقق منه قط، وقواعد lint محددة لكنها متساهلة جدًا، ولم يُنشأ ملف تقدم. هذه العيوب ليست واضحة في الجلسة الأولى (لأن الوكيل لا يزال يتذكر ما فعله)، لكنها تظهر في الجلسة الثانية — الوكيل الجديد لا يعرف كيف يُشغّل، أو يختبر، أو أين تقف الأمور. أساس رديء، مبنى مهتز.
+المشكلة الأكثر مباشرة: الأساس لا يتصلب بشكل صحيح. الوكيل ينفق معظم جهده على كود الميزات ويتعامل مع البنية التحتية كفكرة لاحقة. إطار الاختبار مضبوط لكن لم يُتحقق منه قط، وقواعد lint محددة لكنها متساهلة جدًا، ولم يُنشأ ملف تقدم. هذه العيوب ليست واضحة في الجلسة الأولى (لأن الوكيل لا يزال يتذكر ما فعله)، لكنها تظهر في الجلسة الثانية — الوكيل الجديد لا يعرف كيف يُشغّل، أو يختبر، أو أين تقف الأمور. أساس رديء، مبنى مهتز.
تكلفة أخفى هي "التراكم غير المُتحقَق" — كود الميزات المكتوب قبل ضبط إطار الاختبار هو كود بدون تحقق. عندما تعود أخيرًا لإضافة اختبارات لهذا الكود، قد تكتشف أن التصميم كان خاطئًا من البداية — لو كنت تعرف، لطبّقته بشكل مختلف. مثل تبليط سطح خرسانة رطبة — عندما تكتشف أن الأرضية غير مستوية، يجب نزع كل البلاط وإعادة العمل.
@@ -45,7 +45,7 @@ flowchart TB
المشكلة الأكثر تجاهلًا هي ألغام الافتراضات الضمنية. القرارات التي يتخذها الوكيل أثناء التهيئة (أي إطار اختبار، كيف تنظيم الأدلة، إدارة التبعيات) — إذا لم تُسجَّل صراحةً، لا يمكن للجلسات اللاحقة فهم هذه الخيارات. الأسوأ، أن الجلسات اللاحقة قد تتخذ خيارات متناقضة. طاقم البناء الأول استخدم أساسًا خرسانيًا، والطاقم الثاني لا يعرف وغرس فيه أوتادًا خشبية — الأساس يتشقق.
-أبحاث Anthropic لتطوير التطبيقات طويلة التشغيل توصي صراحةً بفصل التهيئة عن التنفيذ. بياناتهم التجريبية: المشاريع التي استخدمت مرحلة تهيئة مخصصة أظهرت معدلات إكمال ميزات أعلى بنسبة 31% في سيناريوهات الجلسات المتعددة مقارنة بالأساليب المختلطة. الرؤية الأساسية — الوقت المستثمر في مرحلة التهيئة يُسترد بالكامل في الجلسات الـ 3-4 التالية. كلما كان الأساس أصلب، ارتفعت الجدران أسرع.
+أبحاث Anthropic لتطوير التطبيقات طويلة التشغيل توصي صراحةً بفصل التهيئة عن التنفيذ. عملهم على الوكلاء طويلة التشغيل [يجعل التهيئة جلسة أولى منفصلة](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents): يكتب المُهيّئ سكربت `init.sh`، وملف تقدم، وقائمة ميزات، وcommit أوليًا في git؛ ثم تقرأ جلسات البرمجة اللاحقة تلك الحالة، وتعمل على ميزة واحدة في كل مرة، وتختبرها من الطرف إلى الطرف، وتُثبّت التغيير، وتحدّث ملف التقدم. كلما كان الأساس أصلب، ارتفعت الجدران أسرع.
دليل OpenAI Codex لهندسة harness يُؤكد أيضًا على مبدأ "المستودع كسجل عمليات" — أَسِّس هيكل عمليات واضحًا من التشغيل الأول، وإلا ستضطر كل جلسة جديدة إلى استنتاج اصطلاحات المشروع من جديد.
diff --git a/docs/ar/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/ar/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
index c00c9f1..b4b467d 100644
--- a/docs/ar/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
+++ b/docs/ar/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -26,7 +26,7 @@
بعد ست خطوات، كل واحدة نصف مكتملة. بدون تحقق شامل، وارتباط معقد بين الكود غير المكتمل، والجلسة التالية التي ستلتقط القطع ستكون ضائعة تمامًا. مثل شخص يطبخ ستة أطباق في وقت واحد — كل طبق في المقلاة لكن لم يُقدم أي منها. جميعها تحترق.
-البيانات التجريبية من Anthropic تدعم هذا مباشرة: الوكلاء الذين يستخدمون استراتيجية "الخطوة التالية الصغيرة" (ما يعادل WIP=1) يُظهرون معدل إكمال مهام أعلى بنسبة 37% من الوكلاء الذين يستخدمون prompts واسعة. والأكثر إثارة للاهتمام، أن عدد أسطر الكود التي يُنتجها الوكلاء مرتبط ارتباطًا سلبيًا ضعيفًا مع إكمال الميزات الفعلي — كود أكثر مكتوب، ميزات أقل مُنجزة. العض أكثر مما تستطيع مضغه، مُثبت بالبيانات.
+إرشادات Anthropic للوكلاء طويلة التشغيل [تطلب من وكيل البرمجة العمل على ميزة واحدة في كل مرة](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)، ثم التحقق والـ commit وتحديث التقدم قبل الانتقال. المطالبة الواسعة تدعو الوكيل إلى فتح عدة مسارات، وكل مسار ينافس غيره على السياق وميزانية التحقق نفسيهما.
## سير عمل WIP=1
diff --git a/docs/ar/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/ar/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
index 8ee7907..ce23425 100644
--- a/docs/ar/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
+++ b/docs/ar/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -22,7 +22,7 @@ Did user auth, shopping cart mostly done, still need payments
```
هل يمكن لجلسة agent جديدة الإجابة على هذه الأسئلة من هذه الملاحظة؟ ماذا يعني "مكتملة إلى حد كبير"؟ أي اختبارات اجتازتها السلة؟ ما الذي يعيق المدفوعات؟ الإجابة على الكل هي "لا أحد يعرف." مثلما تخبر طبيبك "معدتي تؤلمني، كنت بخير مؤخرًا" — أي دواء يمكنه وصفه؟
-النتيجة: تقضي الجلسة الجديدة 20 دقيقة في استنتاج حالة المشروع، وقد تعيد تنفيذ الميزات المكتملة. تُظهر بيانات هندسة Anthropic أن سجلات التقدم الجيدة تقلل وقت تشخيص بدء الجلسة بنسبة 60-80%.
+النتيجة: على الجلسة الجديدة أن تستنتج حالة المشروع، وقد تعيد تنفيذ الميزات المكتملة. نصيحة Anthropic هي [تسجيل التقدم ونتائج التحقق في ملفات مُدارة بالإصدارات](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) حتى تتمكن الجلسة التالية من فحص الحالة.
## آلة حالة الميزات
@@ -111,7 +111,7 @@ flowchart LR
**وضع العمود الفقري**: كل ميزة لها حالة واضحة وأمر تحقق. تقرأ الجلسة الجديدة قائمة الميزات وتعرف في 3 دقائق: F01-F05 `passing`، F06 `active`، F07-F10 `not_started`. تستأنف من F06 مباشرة، صيانة صفرية.
-النتيجة المُقاسة: تُظهر المشاريع التي تستخدم قوائم ميزات منظمة معدل إنجاز ميزات أعلى بنسبة 45% من التتبع الحر، مع صفر عمليات تنفيذ مكررة.
+القائمة المنظمة تضع حالة كل ميزة وأمر التحقق في مكان واحد، فتعرف الجلسة الجديدة ما أُنجز.
## الخلاصات الأساسية
diff --git a/docs/ar/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/ar/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
index 1920fcc..cc7d550 100644
--- a/docs/ar/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
+++ b/docs/ar/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -70,7 +70,7 @@ agent تقييم مستقل، مُضبوط خصيصًا ليكون "صارمًا
| Architecture | Runtime | Cost | Core Features Working? |
|--------------|---------|------|------------------------|
| Single Agent (bare run) | 20 mins | $9 | No (game entities unresponsive to input) |
-| Three Agents (planner + generator + evaluator) | 6 hours | $200 | Yes (game is fully playable) |
+| Three Agents (planner + generator + evaluator) | 6 hours | $200 | Core gameplay worked; physics and level issues remained |
هذا هو نفس النموذج بالضبط (Opus 4.5) مع نفس الموجه بالضبط ("build a 2D retro game editor"). الفرق الوحيد هو harness — من "التشغيل المجرّد" إلى "المخطط يُوسّع المتطلبات ← المُنشئ ينفذ ميزة بميزة ← المُقيّم يقوم باختبار النقر الفعلي باستخدام Playwright".
@@ -119,7 +119,7 @@ agent تقييم مستقل، مُضبوط خصيصًا ليكون "صارمًا
**خصومات الدرجات الفعلية**: (1) التدفق الشامل غير مُختبَر — لم يتم تأكيد الإرسال والتحقق الفعلي لرابط إعادة التعيين أبدًا. (2) فشل ترحيل قاعدة البيانات بعد التنفيذ الجزئي، مما تسبب في عدم اتساق المخطط. (3) إعدادات خدمة البريد الإلكتروني كانت مفقودة في البيئة المستهدفة.
-**تدخل harness**: فُرض تحقق الإنهاء — (1) بدء التطبيق الكامل للتحقق من إمكانية الوصول لنقطة نهاية إعادة التعيين؛ (2) تنفيذ تدفق إعادة التعيين الكامل؛ (3) التحقق من اتساق حالة قاعدة البيانات. وُجدت جميع العيوب خلال الجلسة، مما وفر 5-10 أضعاف تكلفة الإصلاحات اللاحقة. المصحح المستقل وجد المشاكل الحقيقية.
+**تدخل harness**: فُرض تحقق الإنهاء — (1) بدء التطبيق الكامل للتحقق من إمكانية الوصول لنقطة نهاية إعادة التعيين؛ (2) تنفيذ تدفق إعادة التعيين الكامل؛ (3) التحقق من اتساق حالة قاعدة البيانات. وُجدت جميع العيوب خلال الجلسة، بينما لا تزال تكلفة الإصلاح محلية. المصحح المستقل وجد المشاكل الحقيقية.
## الخلاصات الأساسية
diff --git a/docs/ar/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/ar/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
index c618bed..7949982 100644
--- a/docs/ar/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
+++ b/docs/ar/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -132,7 +132,7 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.rea
| Permission Issue | Different permissions in packaged environment | Missed | Caught |
| Error Propagation | Service layer exceptions didn't reach UI layer | Missed | Caught |
-كل العيوب الخمسة اكتُشفت بواسطة اختبارات end-to-end، بينما لم تكتشف اختبارات الوحدات أيًا منها. كانت التكلفة زيادة في وقت الاختبار من ثانيتين إلى 15 ثانية — مقبولة تمامًا في سير عمل agent. مهما غنى كل جزء بشكل جيد بشكل فردي، لا يمكنه التغلب على بروفة جماعية كاملة.
+كل العيوب الخمسة اكتُشفت بواسطة اختبارات end-to-end، بينما لم تكتشف اختبارات الوحدات أيًا منها. التشغيل من الطرف إلى الطرف أبطأ، لكن هذه التكلفة صغيرة مقارنة بشحن خمسة عيوب على الحدود. مهما غنى كل جزء بشكل جيد بشكل فردي، لا يمكنه التغلب على بروفة جماعية كاملة.
## الخلاصات الأساسية
diff --git a/docs/ar/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/ar/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
index 9dc3ba6..85c6cb1 100644
--- a/docs/ar/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
+++ b/docs/ar/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -44,7 +44,7 @@ flowchart LR
**تصبح المحاولات المتكررة تخمينات عمياء**: عندما لا يعرف الوكيل سبب الفشل، يكون اتجاه المحاولة التالية عشوائيًا. قد يصلح مسارات كود غير مرتبطة بينما يتجاهل السبب الجذري. كل محاولة عمياء تكلف tokens ووقتًا.
-**انحدار معلومات handoff بين الجلسات**: عندما ينتقل عمل غير مكتمل إلى جلسة جديدة، يعني غياب observability أن الجلسة الجديدة يجب أن تشخص حالة النظام من الصفر. تشير ملاحظات Anthropic إلى أن هذا التشخيص المتكرر قد يستهلك 30-50% من وقت الجلسة.
+**انحدار معلومات handoff بين الجلسات**: عندما ينتقل عمل غير مكتمل إلى جلسة جديدة، يعني غياب observability أن الجلسة الجديدة يجب أن تشخص حالة النظام من الصفر. عليها إعادة قراءة الكود وإعادة تشغيل الأوامر وتقرير أي الإشارات تهم؛ [سجلات التقدم والتحقق المُدارة بالإصدارات](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) توفر حالة قابلة للفحص.
### سيناريو واقعي مع Claude Code
@@ -54,7 +54,7 @@ flowchart LR
**مع observability كاملة**: يخرج planner عقد sprint contract يعدد المكونات التي يجب تعديلها، ومعايير التحقق، والاستثناءات. ينفذ generator وفق العقد. تسجل runtime observability تحميل وتطبيق الأنماط لكل مكون. يستخدم evaluator rubric لتقييم كل بُعد مع أدلة محددة. تنتج دورة واحدة نتيجة عالية الجودة في نحو 15 دقيقة.
-فرق الكفاءة 3x. التغيير الوحيد هو observability.
+الفرق يأتي من وجود العقد والأدلة خارج رأس الوكيل.
### لماذا لا يستطيع الوكلاء حل ذلك وحدهم
@@ -128,7 +128,7 @@ Harness يستخدم workflow من planner-generator-evaluator لتنفيذ "إ
- rubric يوفر تقييمًا منظمًا لكل بُعد
- دورة واحدة تنتج نتيجة عالية الجودة في 15 دقيقة
-تحسن كفاءة 3x، جودة أكثر استقرارًا، وتقييمات قابلة لإعادة الإنتاج.
+نتيجة أوضح، جودة أكثر استقرارًا، وتقييمات قابلة لإعادة الإنتاج.
## الخلاصات الأساسية
@@ -136,7 +136,7 @@ Harness يستخدم workflow من planner-generator-evaluator لتنفيذ "إ
- **طبقتا observability ضروريتان**: إشارات runtime تشرح "ماذا حدث"، وآثار العملية تشرح "لماذا حدث بهذه الطريقة".
- **Sprint contracts تسبق التنفيذ بالتوافق**، فتمنع بناء شيء سيرفضه evaluator فورًا لأسباب متوقعة.
- **Rubrics تجعل التقييم قابلًا لإعادة الإنتاج**، بحيث يعطي مقيمون مختلفون درجات متقاربة لنفس الناتج.
-- **غياب observability يهدر 30-50% من وقت الجلسة في تشخيص مكرر.**
+- **observability تحوّل رفضًا غامضًا إلى عيب محدد قابل للإصلاح.**
## قراءات إضافية
diff --git a/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
index eb56c5c..b591bea 100644
--- a/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
+++ b/docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -54,7 +54,7 @@ flowchart LR
تخبرنا قوانين ليهمان لتطور البرمجيات: الأنظمة التي تخضع لتغيير مستمر ستزداد حتمًا في التعقيد ما لم تُدار بشكل نشط. هذا صحيح بشكل خاص لوكلاء البرمجة بالذكاء الاصطناعي — كل جلسة تُدخل تغييرات، وبدون تنظيف عند الخروج، يتراكم الدين الفني بشكل أسي.
-البيانات الحقيقية دالة. مشروع طُوّر باستخدام الوكلاء لمدة 12 أسبوعًا، بدون استراتيجية تنظيف:
+لنأخذ مشروعًا افتراضيًا مدته 12 أسبوعًا، ولنفترض القيم التالية:
- الأسبوع 1: معدل اجتياز البناء 100%، معدل اجتياز الاختبارات 100%، بدء الجلسة الجديدة 5 دقائق
- الأسبوع 4: البناء 95%، الاختبارات 92%، البدء 15 دقيقة
@@ -66,7 +66,7 @@ flowchart LR
- الأسبوع 1: 100%، 100%، 5 دقائق
- الأسبوع 12: 97%، 95%، 9 دقائق
-بعد 12 أسبوعًا: معدل اجتياز البناء يختلف بنسبة 29 نقطة مئوية، وقت بدء الجلسة الجديدة يختلف بنسبة 85%. هذا ليس نظريًا — إنه فرق مُلاحظ.
+حلقة تنظيف أسبوعية تحافظ على ثبات حالة البداية: تنتهي كل جلسة ببناء واختبارات وتقدم وقطع أثرية مؤقتة مرتبة، فتبدأ الجلسة التالية من خط الأساس نفسه.
### الأبعاد الخمسة للحالة النظيفة
@@ -76,7 +76,7 @@ flowchart LR
**بُعد الاختبار**: هل تجتاز جميع الاختبارات؟ بما فيها الاختبارات التي وُجدت قبل الجلسة — الجلسة مسؤولة عن عدم كسر الوظائف الموجودة. وينبغي التحقق في CI، وليس فقط "يعمل على جهازي."
-**بُعد التقدم**: هل التقدم الحالي مُسجَّل في قطعة أثرية قابلة للقراءة آليًا؟ المهام الفرعية المكتملة مع معايير اجتيازها، المهام الفرعية قيد التقدم لكن غير المكتملة مع حالتها الحالية، المهام الفرعية التي لم تبدأ بعد. سجلات التقدم الجيدة تقلل 60-80% من وقت تشخيص بدء الجلسة.
+**بُعد التقدم**: هل التقدم الحالي مُسجَّل في قطعة أثرية قابلة للقراءة آليًا؟ المهام الفرعية المكتملة مع معايير اجتيازها، المهام الفرعية قيد التقدم لكن غير المكتملة مع حالتها الحالية، المهام الفرعية التي لم تبدأ بعد. سجّل التقدم ونتائج التحقق في ملفات مُدارة بالإصدارات حتى تتمكن الجلسة التالية من فحص الحالة.
**بُعد القطع الأثرية**: هل توجد قطع أثرية مؤقتة قديمة أو غامضة؟ سجلات التصحيح، الملفات المؤقتة، الكود المُعلَّق، علامات TODO — كل هذه تزيد العبء المعرفي للجلسة التالية.
@@ -160,7 +160,7 @@ npm run test # Verify cleanup didn't break anything
**مع استراتيجية تنظيف** (المجموعة التجريبية): فحص حالة نظيفة كامل في نهاية كل جلسة + حلقة تنظيف أسبوعية. الأسبوع 12، معدل اجتياز البناء 97%، معدل اجتياز الاختبارات 95%، بدء الجلسة الجديدة 9 دقائق، قطع أثرية قديمة 11.
-بنهاية الأسبوع 12، معدل اجتياز البناء للمجموعة التجريبية أعلى بـ 29 نقطة مئوية، معدل اجتياز الاختبارات أعلى بـ 34 نقطة مئوية، ووقت بدء الجلسة الجديدة أقل بنسبة 85%.
+بنهاية الأسبوع 12، بقيت معدلات اجتياز البناء والاختبارات في مجموعة التنظيف قريبة من نقطة البداية، وأمكن لجلسة جديدة أن تبدأ بسرعة، وكانت القطع الأثرية القديمة قليلة. استغرق التنظيف بضع دقائق لكل جلسة وأعاد حالة بداية يمكن للجلسة التالية الوثوق بها.
## الخلاصات الأساسية
diff --git a/docs/ar/lectures/lecture-13-loop-engineering/index.md b/docs/ar/lectures/lecture-13-loop-engineering/index.md
index a22c606..ebe3d92 100644
--- a/docs/ar/lectures/lecture-13-loop-engineering/index.md
+++ b/docs/ar/lectures/lecture-13-loop-engineering/index.md
@@ -84,11 +84,11 @@
ليس عليك كتابة `/goal` في كل مرة. لكن فهم من أين جاء ولماذا يبدو كما هو - ذلك هو فهم جوهر هندسة الحلقات. الحلقات الأكثر تعقيدًا تضيف فقط أجزاء مثل الجدولة، والتوازي، والعزل، والذاكرة فوق هذه الأساسيات الثلاثة نفسها: الهدف، والتحقق، وشرط التوقف.
-## يونيو 2026: ثلاثة أشخاص أشعلوا نفس الفتيلة في أسبوع واحد
+## تواريخ مختلفة، الاتجاه نفسه
-في الأسبوع الأول من يونيو 2026، قال ثلاثة ممارسين يبنون بنية تحتية لوكالة البرمجة - دون مقارنة ملاحظات - نفس الشيء بكلمات مختلفة.
+ظهرت الفكرة نفسها في أماكن مختلفة، وفي أوقات مختلفة.
-**بيتر شتاينبرغر** (مبتكر OpenClaw، [مقالته وصلت إلى 8 مليون مشاهدة](https://x.com/steipete/status/2063697162748260627)): "لا يجب أن تطالب وكلاء البرمجة بعد الآن. يجب أن تصمم حلقات تطلب من وكلائك."
+**بيتر شتاينبرغر** (مبتكر OpenClaw، [في منشور](https://x.com/steipete/status/2063697162748260627)): "لا يجب أن تطالب وكلاء البرمجة بعد الآن. يجب أن تصمم حلقات تطلب من وكلائك."
**بوريس تشيرني** (رئيس Claude Code في Anthropic، [على بودكاست Acquired](https://x.com/rohanpaul_ai/status/2063289804708835412)): "أنا لا أطالب Claude بعد الآن. لدي حلقات تعمل تطالب Claude وتكتشف ماذا تفعل. وظيفتي هي كتابة الحلقات."
@@ -96,9 +96,9 @@
> **هندسة الحلقات هي استبدال نفسك كشخص الذي يطالب الوكيل. أنت تصمم النظام الذي يفعل ذلك بدلاً منك.**
-كشف تشيرني عن أرقام: على مدار 30 يومًا متتالية، تم إجراء جميع مساهمات الكود في Claude Code بشكل مستقل بواسطة الذكاء الاصطناعي - 259 PR مدمجة، وأكثر من 80٪ من كود الإنتاج كتبه Claude، ومعدل نجاح 76٪ في مهام البرمجة مفتوحة النهاية.
+كتب تشيرني في [تقرير شخصي بتاريخ 2025-12-27](https://twitter.com/bcherny/status/2004887829252317325) أنه على مدار 30 يومًا دمج 259 PR — و497 commit، وأضاف 40,000 سطر وحذف 38,000 — وأن كل سطر كتبه Claude Code + Opus 4.5.
-ثلاثة أشخاص. أسبوع واحد. نفس الاستنتاج. ليس لأنهم تناسقوا - بل لأن البنية التحتية عبرت بهدوء عتبة. أصبحت الوكلاء موثوقين بما يكفي لإنجاز المهام غير البسيطة دون إشراف. أصبحت بدائيات الجدولة (`/loop`، `/goal`، cron) مدمجة الآن في الأدوات. انخفضت تكلفة تشغيل وكيل واحد بما يكفي بحيث لم يعد تشغيله بشكل متكرر على مؤقت يبدو مُبذرًا. عندما تكون جميع الأجزاء موجودة، فإن الخطوة التي تجمعها تصبح واضحة للجميع في نفس الوقت.
+جاءت الاقتباسات من تواريخ وصيغ وفرق مختلفة. اتجاهها المشترك هو نقل الجدولة والتحقق وقرار التوقف من المطالبة اللحظية إلى نظام. بحلول منتصف 2026، أصبحت الوكلاء قادرة على إنجاز مهام غير بسيطة دون إشراف، وكانت بدائيات الجدولة مدمجة، وأصبح تشغيل واحد رخيصًا بما يكفي لتكراره على مؤقت. عندما تكون الأجزاء موجودة، يركبها أكثر من شخص.
> المصدر: [آدي عثماني: هندسة الحلقات](https://addyosmani.com/blog/loop-engineering/)
@@ -267,7 +267,7 @@ flowchart TD
هذه لم تعد تشغيل وكيل واحد. إنها نظام يعمل باستمرار يستيقظ كل صباح، وينظف الأرضية من تلقاء نفسه، ويضع الأشياء التي تحتاج إلى اهتمامك أمامك. يصبح دورك: **راجع محتويات الصندوق، واتخذ القرارات، وعندما تكتشف نمطًا لا يستطيع النظام التعامل معه، صقل المهارات والقواعد.**
-استخدم تشيرني هذا النمط لدمج 259 PR في 30 يومًا دون فتح IDE مرة واحدة. استخدم مهندسو OpenAI نفس النمط لبناء منتج بيتا يبلغ حوالي مليون سطر كود يدويًا - دون كتابة سطر كود واحد بأنفسهم.
+تقرير تشيرني لمدة 30 يومًا هو نقطة بيانات لهذا النمط: 259 PR، والكود كتبه Claude Code + Opus 4.5. [تقرير OpenAI عن الـ harness](https://openai.com/index/harness-engineering/) مثال آخر: استخدم فريق صغير Codex على مستودع جديد لمدة خمسة أشهر، وأبلغ عن نحو مليون سطر وحوالي 1,500 PR.
## فصل المولد/المقيّم: لماذا لا يمكنك السماح للنموذج بتصحيح عمله بنفسه
@@ -293,7 +293,7 @@ flowchart TD
إذا كنت تريد أن ترى كيف تبدو حلقة مصممة جيدًا وتعمل بالفعل، فإن [autoresearch لكارباثي](https://github.com/karpathy/autoresearch) هي المثال النموذجي.
-في مارس 2026، أصدر كارباثي مشروع Python مكونًا من 630 سطرًا. أعطِه GPU واحدًا واتجاه بحثي، ويعمل طوال الليل - مكتملًا بمئات تجارب تدريب ML، ويحتفظ فقط بتلك التي تحسن حقًا. وصل المشروع إلى أكثر من 66,000 نجمة في غضون أيام من الإصدار.
+في مارس 2026، أصدر كارباثي [autoresearch](https://github.com/karpathy/autoresearch). المستودع صغير عن قصد: `prepare.py` بنية تحتية ثابتة، و`train.py` هو الملف الذي يعدّله الوكيل (نحو 630 سطرًا)، و`program.md` هو منهجية البحث التي يعدّلها الإنسان. أعطِه GPU واحدًا واتجاه بحثي، ويعمل طوال الليل - كل تجربة تحصل على ميزانية تدريب ثابتة 5 دقائق من الساعة الحائطية (باستثناء بدء التشغيل والترجمة)، ولا تُحفظ إلا التغييرات التي تحسّن `val_bpb`.
### ثلاثة ملفات، ثلاثة أدوار
@@ -343,9 +343,9 @@ flowchart TD
8b --> 9
```
-تعمل بـ 12 تجربة تقريبًا في الساعة. تشغيل ليلة واحدة (8 ساعات) حوالي 100 تجربة. قام كارباثي نفسه بتشغيلها لمدة يومين - ~700 تجربة.
+يقدّر README نحو 12 تجربة في الساعة، أو نحو 100 في تشغيل ليلي من 8 ساعات. ميزانية 5 دقائق تغطي التدريب، لا بدء التشغيل أو الترجمة؛ ويذهب بقية كل جولة إلى التحرير والإطلاق والتقييم. ذكر كارباثي أنه شغّل نسخة خاصة من autoresearch ذاتيًا لنحو يومين لجولة nanochat الموصوفة أدناه.
-ميزانية الساعة الحائط الثابتة البالغة 5 دقائق هي خيار تصميمي رئيسي - بغض النظر عما يغيره الوكيل، تستغرق كل تجربة نفس الوقت بالضبط. هذا يعني أن جميع النتائج قابلة للمقارنة مباشرة ضمن نفس الميزانية الزمنية - لا جدال حول "هذه شغلت لفترة أطول لذا فهي أفضل."
+ميزانية التدريب الثابتة البالغة 5 دقائق هي خيار تصميمي رئيسي - بغض النظر عما يغيره الوكيل، تحصل جولة التدريب على نفس ميزانية الساعة الحائطية. هذا يعني أن جميع النتائج قابلة للمقارنة مباشرة ضمن ميزانية التدريب نفسها.
### المخرج: ما تراه عند الاستيقاظ
@@ -375,13 +375,9 @@ timestamp commit_hash val_bpb vram_mb description
### ما وجده بالفعل
-النتائج من تشغيل كارباثي الأولي لمدة يومين، ~700 تجربة:
+خفّضت [الجولة الأولى](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b) من autoresearch وقت تدريب مستوى GPT-2 لـ nanochat على 8×H100 [من **2.02 ساعة إلى 1.80 ساعة**](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b)، أي انخفاض بنحو **10.9٪** في وقت التدريب.
-- من بين ~700 محاولة، تم العثور على حوالي **20 تحسنًا حقيقيًا قابلًا للتكديس**
-- خفض وقت تدريب مستوى GPT-2 لـ nanochat على 8×H100 من **2.02 ساعة → 1.80 ساعة**، حوالي **أسرع بنسبة 11٪**
-- شملت النتائج: تعديلات معدل التعلم، وضبط المحسن، وتبديلات التنشيط، وتحسينات نمط الانتباه، إلخ.
-
-هل كانت جميع التحسينات اكتشافات مذهلة؟ لا. كانت معظمها تحسينات صغيرة تكدست. لكن تلك التحسينات الصالحة البالغ عددها 20 كانت ستستغرق باحثًا بشريًا أسابيع من العمل اليدوي - وفعلها الوكيل في 48 ساعة.
+كانت معظم التغييرات تحسينات صغيرة تكدست. الجزء المفيد هو الحلقة نفسها: ميزانية ثابتة، وسجل تجارب كامل، وقاعدة تقول إن التحسينات المتحقق منها فقط هي التي تبقى.
### التفاصيل الأكثر دلالة: الحلقة مكتوبة باللغة الإنجليزية، وليس بالكود.
@@ -399,7 +395,7 @@ timestamp commit_hash val_bpb vram_mb description
### 2. تعفن الفهم
-كلما زادت سرعة شحن الحلقة للكود، زاد تباعد فهمك لقاعدة الكود الخاصة بك عن الواقع. كان لدى فريق تشيرني 80٪ من الكود مكتوبًا بواسطة الوكلاء - مما يعني أن معظم كود الفريق لم يكتبه شخص. إذا لم تقرأ وتستخدم ما تنتجه الحلقة، فإن فهمك يتحلل باستمرار. **الحلقات السريعة تتطلب قراءة سريعة.**
+كلما زادت سرعة شحن الحلقة للكود، زاد تباعد فهمك لقاعدة الكود الخاصة بك عن الواقع. تنشر حلقة مئات الـ PR؛ يقرأ الفريق تلك الـ PR، ويراجع الفروق المهمة، ويستمر في استخدام الكود، فيواكب نموذجه الذهني. **الحلقات السريعة تتطلب قراءة سريعة.**
### 3. الاستسلام المعرفي
@@ -407,11 +403,11 @@ timestamp commit_hash val_bpb vram_mb description
### 4. انفجار التوكنز
-يتراكم كل تكرار للحلقة المزيد من السياق: الكود المكتوب، والأخطاء التي تمت مواجهتها، والقرارات المتخذة. بدون إدارة السياق، ينمو حجم المطالبة تقريبًا تربعيًا مع عدد الدورات. يعالج Codex ذلك من خلال الضغط التلقائي للسياق - API مخصص يضغط أدوار المحادثة القديمة إلى ملخصات محتوى مشفرة، مع الاحتفاظ بالمعرفة الأساسية مع التخلص من التفاصيل الزائدة. هذا هو اهتمام هندسي يجب معالجته من الحلقة الأولى، وليس إضافة لاحقة.
+يتراكم كل تكرار للحلقة المزيد من السياق: الكود المكتوب، والأخطاء التي تمت مواجهتها، والقرارات المتخذة. عندما تضيف كل جولة كمية شبه ثابتة من المحتوى الجديد، ينمو طول السجل الذي تراه جولة واحدة خطيًا تقريبًا مع عدد الجولات. وإذا أعاد النظام معالجة السجل كاملًا في كل جولة، فإن المدخل التراكمي عبر N جولة ينمو تربعيًا تقريبًا. يعالج Codex ذلك من خلال الضغط التلقائي للسياق - API مخصص يضغط أدوار المحادثة القديمة إلى ملخصات محتوى مشفرة، مع الاحتفاظ بالمعرفة الأساسية مع التخلص من التفاصيل الزائدة. هذا هو اهتمام هندسي يجب معالجته من الحلقة الأولى، وليس إضافة لاحقة.
## بناء أول حلقة لك
-ليس عليك البدء بخط أنابيب بمقياس Stripe يدمج 1,300 PR في الأسبوع. ابدأ بأصغر شيء يعمل.
+ليس عليك البدء بخط أنابيب عالي الإنتاجية. ابدأ بأصغر شيء يعمل.
### الخطوة 1: اختر مهمة متكررة واحدة
diff --git a/docs/ar/lectures/lecture-14-graph-engineering/index.md b/docs/ar/lectures/lecture-14-graph-engineering/index.md
index ca965be..1163931 100644
--- a/docs/ar/lectures/lecture-14-graph-engineering/index.md
+++ b/docs/ar/lectures/lecture-14-graph-engineering/index.md
@@ -9,7 +9,7 @@
> "هل ما زلنا نتحدث عن الحلقات، أم انتقلنا بالفعل إلى الرسوم البيانية؟"
-تغريدة واحدة — حصلت على حوالي 575 ألف مشاهدة خلال يوم واحد، وارتفعت إلى حوالي 3 ملايين بنهاية الشهر. وبعد ساعات قليلة، نشر مهندس التعلم الآلي هامل حسين مقالًا بعنوان *Loop Engineering Is Dead. Enter Graph Engineering* — جسم المقال كله لم يكن سوى صورة متحركة واحدة مكتوب عليها "Stop it" — وحصل على حوالي 680 ألف مشاهدة إضافية.
+تغريدة واحدة. وبعد ساعات قليلة، نشر مهندس التعلم الآلي هامل حسين مقالًا بعنوان *Loop Engineering Is Dead. Enter Graph Engineering* — جسم المقال كله لم يكن سوى صورة متحركة واحدة مكتوب عليها "Stop it".
والأكثر إثارة للاهتمام: **كلاهما كانا يمزحان.** الأول كان يسخر من صناعة تختلق مصطلحًا جديدًا كل ستة أسابيع، والثاني كان يتابع النكتة بمواصلة هذه المزحة. لكن النكتة عاشت حوالي عطلة نهاية أسبوع واحدة فقط — الدورات والخرائط الذهنية ومجموعات الأدوات غرقت في الخط الزمني قبل نهاية عطلة نهاية الأسبوع، متبوعة بكومة من الأرقام المختلقة: "دقة +18%، تكلفة -85%" بيانات مزيفة (الرقمان موجودان فعلًا، لكنهما من ورقة بحثية عن مخططات الأنابيب الكيميائية، وبمقارنة مع خطوط أساس مختلفة تمامًا)، و"اكتشفت مايكروسوفت وستانفورد وAnthropic هندسة الرسوم البيانية في نفس الوقت" خبر أيضًا كاذب. التحقق من الحقائق وحده أكد "رائدًا" حقيقيًا واحدًا: جوش سيمونز، الذي كُتبت مقالته *We Are Entering the Graph Engineering Phase* في 4 يوليو — قبل النكتة بأسبوعين كاملين — **النكتة هي التي جعلت هذا الأمر رائجًا، والنكتة لم تُنشئ هذا الأمر.**
@@ -257,11 +257,11 @@ run(graph, entry={"requirements": "إصلاح خطأ صفحة تسجيل الد
## مشاريع مفتوحة المصدر: بعد الاسم، وقبل الاسم
-أولًا، حدد الخط الفاصل: **"Graph Engineering" اسم له وجود فقط بعد 18 يوليو 2026.** الأطر التي صدرت مفتوحة المصدر قبل ذلك التاريخ ليست "مشاريع بعد إطلاق هندسة الرسوم البيانية". حتى أوائل أغسطس 2026، المشروع مفتوح المصدر الوحيد الذي يتبنى هذا الاسم مباشرة ويصمد هو واحد:
+أولًا، حدد الخط الفاصل: **"Graph Engineering" اسم له وجود فقط بعد 18 يوليو 2026.** الأطر التي صدرت مفتوحة المصدر قبل ذلك التاريخ ليست "مشاريع بعد إطلاق هندسة الرسوم البيانية". أحد المشاريع التي تستخدم الاسم صراحةً هو GraphARC:
**موجود بعد إطلاق المفهوم**
-- [GraphArc](https://github.com/CodeGraphContext/grapharc) (2026-08-02): يسمي نفسه "أول تنفيذ فوري في الوقت الحقيقي لهندسة الرسوم البيانية". يحوّل تنفيذ الوكيل من سجلات مدفونة في السجلات إلى **رسم بياني تنسيق تفاعلي في الوقت الحقيقي** — كل وكيل وكل تبعية وكل نقطة قرار مرسومة، تُعرض للتصور قبل التنفيذ (ويمكنك حتى النظر إليها من هاتفك)، ثم تسمح بالاستمرار بعد التأكيد. خلفية المؤلف هي بناء أدوات رسوم بيانية لأكثر من 4000 مطور، والاتجاه هو "قابل للملاحظة، قابل للتصحيح، قابل للهندسة". جديد جدًا، والوظائف ما زالت في مرحلة مبكرة.
+- [GraphARC](https://github.com/CodeGraphContext/GraphARC) (أُنشئ في يوليو 2026): يصف نفسه بأنه "تنفيذ من الطرف إلى الطرف لهندسة الرسوم البيانية كما اقترحها Andrew NG وPeter Steinberger". إنه مشروع Python في مرحلة مبكرة. الخطوة المفيدة هي قراءة نموذج التنسيق الخاص به وتقرير ما إذا كان النهج يناسب سير عملك.
**موجود قبل إطلاق المفهوم (لا يسمونها هندسة الرسوم البيانية، لكنها هي ما ستستخدمه فعليًا عند البناء)**
@@ -325,7 +325,7 @@ run(graph, entry={"requirements": "إصلاح خطأ صفحة تسجيل الد
- [goddaehee: التحقق من حقائق هندسة الرسوم البيانية (كورية، 2026-07-30)](https://goddaehee.tistory.com/628) — التحقق الأكثر اكتمالًا: الخط الزمني لنشأة النكتة، وتفكيك الأرقام المزيفة، وبيانات LangGraph، ومقارنة حرارة Hacker News
- [جوش سيمونز: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — المقالة الجادة المكتوبة قبل النكتة بأسبوعين
- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — الرد الرسمي: "ليست فكرة جديدة، بل الاسم الأحدث لنهج راسخ"؛ أكثر من 65 مليون تحميل شهري لـ LangGraph
-- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — بيانات انتشار الضجة (575 ألف مشاهدة للتغريدة الأصلية)
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — رواية عن كيفية انتشار المصطلح
- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — مقارنة أفقية لسبعة أطر مفتوحة المصدر رئيسية: LangGraph، CrewAI، Microsoft Agent Framework، LlamaIndex، Google ADK، OpenAI Agents SDK، Mastra
- [وثائق LangGraph الرسمية](https://docs.langchain.com/oss/python/langgraph/graph-api) — "العقد تقوم بالعمل، والحواف تخبر بما يجب أن يحدث بعد ذلك"؛ التعريفات الدقيقة للعقد والحواف، المرجع الأولي لبناء الرسوم البيانية
- [Anthropic: Building Effective Agents (ديسمبر 2024)](https://www.anthropic.com/engineering/building-effective-agents) — الأنماط الخمسة التي تُرسم كرسوم بيانية؛ التمييز الموثوق بين سير العمل والوكيل
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.md
index e14086b..44270df 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
@@ -9,13 +9,13 @@ Du kennst dich in der KI-Welt gut aus: Claude-Pro-Abo, GPT-4o-API-Key, SWE-bench
Dein erster Impuls? "Dieses Modell ist nicht gut genug. Zeit für ein Upgrade." Warte kurz. Bevor du zur Kreditkarte greifst, solltest du in Betracht ziehen, dass das Problem vielleicht gar nicht das Modell ist.
-Schauen wir auf ein paar Zahlen. Ende 2025 erreichen die stärksten Coding-Agenten auf SWE-bench Verified ungefähr 50-60%. Und das bei sorgfältig ausgewählten Aufgaben mit klaren Issue-Beschreibungen und vorhandenen Tests. Übertrage das auf deine tägliche Entwicklungsumgebung - vage Anforderungen, keine vorhandenen Tests, überall verstreute implizite Geschäftsregeln - und diese Zahl sinkt weiter.
+Am 29. September 2025 meldete Anthropic für Claude Sonnet 4.5 [77,2 % auf SWE-bench Verified](https://www.anthropic.com/news/claude-sonnet-4-5). Und das bei sorgfältig ausgewählten Aufgaben mit klaren Issue-Beschreibungen und vorhandenen Tests. Übertrage das auf deine tägliche Entwicklungsumgebung - vage Anforderungen, keine vorhandenen Tests, überall verstreute implizite Geschäftsregeln - und diese Zahl sinkt weiter.
Hinter diesen Zahlen steckt aber eine kontraintuitive Wahrheit.
## Gleiches Pferd, anderes Ergebnis
-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.
+Anthropic verglich denselben Prompt ("baue einen 2D-Retro-Game-Maker") mit demselben Modell (Opus 4.5) unter zwei Harnesses. Erster Lauf: nackt, ohne Unterstützung - 20 Minuten, 9 Dollar; die App öffnete sich, aber die Entitäten reagierten nicht auf Eingaben. Zweiter Lauf: vollständiger Harness (Planner + Generator + Evaluator als Drei-Agenten-Architektur) - 6 Stunden, 200 Dollar; eine Entität ließ sich bewegen, aber die Physik hatte raue Kanten und eine Wand blockierte den Fortschritt. [Die Kernfunktionen liefen, fertig war die App nicht.](https://www.anthropic.com/engineering/harness-design-long-running-apps)
Sie änderten nicht das Modell. Opus 4.5 blieb Opus 4.5. Was sich änderte, war das Zaumzeug.
@@ -39,9 +39,9 @@ Lange Aufgaben über mehrere Sitzungen sind noch schlimmer: Alle Erkenntnisse au
Mit 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.
+- **Capability Gap**: Die große Lücke zwischen Modellleistung auf Benchmarks und Leistung bei realen Aufgaben. Benchmark-Aufgaben bringen klare Issue-Beschreibungen, Tests und eine Umgebung mit; bei realen Aufgaben musst du diese oft selbst liefern.
- **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.
+- **Harness-Induced Failure**: Das Modell hat grundsätzlich genug Fähigkeit, aber die Ausführungsumgebung hat strukturelle Defekte. Der Retro-Game-Vergleich oben ist ein Beispiel.
- **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.
- **Definition of Done**: Eine Menge maschinell überprüfbarer Bedingungen - Tests grün, Lint sauber, Type Checks bestanden. Ohne explizite Definition of Done erfindet der Agent seine eigene.
@@ -72,7 +72,7 @@ Completion criteria:
## Das Millionen-Zeilen-Experiment
-OpenAI führte 2025 ein aggressives Experiment durch: Codex sollte aus einem leeren Git-Repository ein vollständiges internes Produkt bauen. Fünf Monate später hatte das Repository ungefähr eine Million Zeilen Code - Anwendungslogik, Infrastruktur, Tooling, Dokumentation, interne Entwicklerwerkzeuge - alles von Agenten erzeugt. Drei Engineers steuerten Codex und öffneten sowie mergten etwa 1.500 PRs. Im Schnitt 3,5 PRs pro Person und Tag.
+Im August 2025 starteten drei Engineers bei OpenAI ein Experiment: Codex sollte aus einem leeren Git-Repository ein vollständiges internes Produkt bauen. [Fünf Monate später enthielt das Repository ungefähr eine Million Zeilen Code](https://openai.com/index/harness-engineering/) - Anwendungslogik, Infrastruktur, Tooling, Dokumentation, interne Entwicklerwerkzeuge - alles von Agenten erzeugt. Das Team wuchs später auf sieben Engineers; insgesamt wurden etwa 1.500 PRs gemergt, im Schnitt 3,5 pro Engineer und Tag.
Die zentrale Einschränkung: **Menschen schreiben nie direkt Code.** Das war kein Trick, sondern sollte das Team zwingen herauszufinden, was sich ändert, wenn die Hauptaufgabe des Engineers nicht mehr Code schreiben ist, sondern Umgebungen zu entwerfen, Absichten präzise auszudrücken und Feedbackschleifen zu bauen.
@@ -86,9 +86,9 @@ Dieses Experiment belegt direkt die Kernaussage dieser Lektion: **Dasselbe Model
Ein Team nutzte Claude Sonnet, um einer mittelgroßen Python-Web-App (FastAPI + PostgreSQL + Redis, ca. 15.000 Codezeilen) einen neuen API-Endpunkt hinzuzufügen.
-Zunächst gaben sie nur einen Satz: "add user preferences endpoints under `/api/v2/users`." Das Ergebnis? Der Agent verbrauchte 40% seines Kontextfensters damit, die Repository-Struktur zu erkunden, erzeugte Code, der plausibel aussah, aber nicht den Error-Handling-Mustern des Projekts folgte, verwendete alte SQLAlchemy-Syntax und erklärte die Aufgabe für abgeschlossen, obwohl der Endpunkt Laufzeitfehler hatte. Die nächste Sitzung musste die gesamte Entdeckungsarbeit erneut leisten.
+Zunächst gaben sie nur einen Satz: "add user preferences endpoints under `/api/v2/users`." Das Ergebnis? Der Agent verbrachte viel Zeit damit, die Repository-Struktur zu erkunden, erzeugte Code, der plausibel aussah, aber nicht den Error-Handling-Mustern des Projekts folgte, verwendete alte SQLAlchemy-Syntax und erklärte die Aufgabe für abgeschlossen, obwohl der Endpunkt Laufzeitfehler hatte. Die nächste Sitzung musste die gesamte Entdeckungsarbeit erneut leisten.
-Später ergänzten sie `AGENTS.md` (mit Projektarchitektur und Tech-Stack-Versionen), explizite Verifikationsbefehle (`pytest tests/api/v2/ && python -m mypy src/`) und Architecture Decision Records. Dasselbe Modell war in allen drei unabhängigen Läufen erfolgreich, mit etwa 60% besserer Kontext-Effizienz.
+Später ergänzten sie `AGENTS.md` (mit Projektarchitektur und Tech-Stack-Versionen), explizite Verifikationsbefehle (`pytest tests/api/v2/ && python -m mypy src/`) und Architecture Decision Records. Dasselbe Modell folgte danach den Konventionen des Projekts und prüfte seine Arbeit mit Befehlen, die es ausführen konnte.
Sie änderten nicht das Modell. Sie änderten den Harness.
diff --git a/docs/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
index fa893de..5d0db0e 100644
--- a/docs/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
+++ b/docs/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -52,7 +52,7 @@ flowchart LR
- **Kontextfenster sind endlich**: Egal welche Fenstergröße behauptet wird (128K, 200K, 1M) — lange Aufgaben werden sie schließlich erschöpfen. Nach der Erschöpfung ist entweder Kompression (Informationsverlust) oder ein Reset (neue Session) erforderlich. Beide verlieren etwas.
- **Kontinuitäts-Artefakte**: Persistierte Zustandsdateien, die es einer neuen Session ermöglichen, eindeutig dort fortzufahren, wo die letzte aufgehört hat. Die Grundform: Fortschrittsprotokoll + Verifizierungsdatensatz + nächste Aktionen. Das Tagebuch dieses Handwerkers.
-- **Rebuild-Kosten**: Die Zeit, die eine neue Session benötigt, um einen ausführbaren Zustand zu erreichen. Gute harness-Konstruktionen können die Rebuild-Kosten von 15 Minuten auf 3 Minuten komprimieren.
+- **Rebuild-Kosten**: Die Zeit, die eine neue Session benötigt, um einen ausführbaren Zustand zu erreichen. Ein guter Harness hinterlässt Fortschritt, Verifikationsergebnisse und nächste Aktionen in Dateien, sodass die neue Session von einem schriftlich festgehaltenen Zustand aus startet.
- **Drift**: Die Lücke zwischen dem Verständnis des Agenten und dem tatsächlichen Zustand des Code-Repositorys. Jede Sitzungsgrenze führt Drift ein; ohne Kontrolle summiert er sich.
- **Context Anxiety**: Ein von Anthropic beobachtetes Phänomen — Agenten zeigen voreiliges Konvergenzverhalten, wenn sie sich wahrgenommenen Kontextgrenzen nähern, und beenden Aufgaben vorzeitig, um Informationsverlust zu vermeiden. Es ist eine irrationale Ressourcenangst.
- **Kompression vs. Reset**: Kompression fasst den Kontext innerhalb derselben Session zusammen (behält das „was", verliert möglicherweise das „warum"); Reset öffnet eine neue Session, die aus persistiertem Zustand wieder aufgebaut wird (sauber, aber abhängig von der Vollständigkeit der Artefakte).
@@ -160,7 +160,7 @@ LangChain berichtet bei gleichem gpt-5.2-codex auf Terminal Bench 2.0 mit 89 Auf
- Kontextfenster sind eine endliche Ressource. Lange Aufgaben werden Sessions überspannen, und Sessions werden Informationen verlieren — wie der Handwerker, der jeden Tag vergisst, ist das objektive Realität.
- Die Lösung sind nicht größere Fenster — sondern bessere Zustandspersistenz. Fortschrittsdateien + Entscheidungsprotokolle + Git-Kontrollpunkte — geben Sie dem amnestischen Handwerker ein zuverlässiges Tagebuch.
- Behandeln Sie den Agenten wie einen Ingenieur mit Amnesie: Bevor er „aussticht", schreibt er auf, was getan wurde, warum und was als Nächstes ansteht.
-- Rebuild-Kosten sind die zentrale Kennzahl. Gute harness-Konstruktionen sollten neue Sessions innerhalb von 3 Minuten in einen ausführbaren Zustand bringen.
+- Rebuild-Kosten sind die zentrale Kennzahl. Ein guter Harness hinterlässt Fortschritt, Verifikationsergebnisse und nächste Aktionen in Dateien, sodass eine neue Session schnell wieder arbeitsfähig ist.
- Gemischte Strategie: kurze Aufgaben innerhalb von Sessions, lange Aufgaben mit strukturierten Artefakten für Kontinuität.
## Weiterführende Literatur
diff --git a/docs/de/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/de/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
index ae1c4f6..ac254cf 100644
--- a/docs/de/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
+++ b/docs/de/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -37,7 +37,7 @@ flowchart TB
## Was passiert, wenn man beides vermischt
-Das direkteste Problem: Das Fundament härtet nicht richtig aus. Der Agent verbringt 80% seiner Mühe auf Feature-Code und 20% mit beiläufigem Aufbau etwas Infrastruktur. Das Test-Framework ist konfiguriert, aber nie verifiziert, Lint-Regeln sind gesetzt, aber zu lasch, keine Fortschrittsdatei erstellt. Diese Mängel sind in der ersten Session nicht offensichtlich (weil der Agent sich noch an das erinnert, was er getan hat), aber sie tauchen in der zweiten Session auf — der neue Agent weiß nicht, wie man ausführt, testet oder wo die Dinge stehen. Schlechtes Fundament, wackeliges Gebäude.
+Das direkteste Problem: Das Fundament härtet nicht richtig aus. Der Agent verbringt den Großteil seiner Mühe mit Feature-Code und behandelt Infrastruktur als Nebensache. Das Test-Framework ist konfiguriert, aber nie verifiziert, Lint-Regeln sind gesetzt, aber zu lasch, keine Fortschrittsdatei erstellt. Diese Mängel sind in der ersten Session nicht offensichtlich (weil der Agent sich noch an das erinnert, was er getan hat), aber sie tauchen in der zweiten Session auf — der neue Agent weiß nicht, wie man ausführt, testet oder wo die Dinge stehen. Schlechtes Fundament, wackeliges Gebäude.
Ein noch verborgenerer Kostenfaktor ist die „unverifizierte Akkumulation" — Feature-Code, der geschrieben wurde, bevor das Test-Framework konfiguriert ist, ist Code ohne Verifizierung. Wenn man schließlich zurückgeht, um Tests für diesen Code hinzuzufügen, könnte man feststellen, dass das Design von Anfang an falsch war — hätte man es gewusst, hätte man es anders implementiert. Wie Fliesen auf nassem Beton — wenn man entdeckt, dass der Boden nicht eben ist, müssen alle Fliesen herausgebrochen und neu verlegt werden.
@@ -45,7 +45,7 @@ Das Session-Budget wird ebenfalls verschwendet. Initialisierungsarbeit (Umgebung
Das am leichtesten übersehene Problem sind implizite Annahmen-Landminen. Entscheidungen, die der Agent während der Initialisierung trifft (welches Test-Framework, wie Verzeichnisse organisieren, Abhängigkeitsverwaltung) — wenn sie nicht explizit dokumentiert werden, können nachfolgende Sessions diese Entscheidungen nicht nachvollziehen. Schlimmer noch, nachfolgende Sessions könnten widersprüchliche Entscheidungen treffen. Die erste Baumannschaft hat ein Betonfundament verwendet, die zweite weiß es nicht und hat Holzpfähle hineingetrieben — das Fundament reißt.
-Anthropics Forschung zur Entwicklung langlebiger Anwendungen empfiehlt ausdrücklich die Trennung von Initialisierung und Implementierung. Ihre experimentellen Daten: Projekte mit einer dedizierten Initialisierungsphase zeigten in Multi-Session-Szenarien eine um 31% höhere Feature-Abschlussrate im Vergleich zu gemischten Ansätzen. Die zentrale Erkenntnis — die in die Initialisierungsphase investierte Zeit wird in den nächsten 3–4 Sessions vollständig zurückgewonnen. Je solider das Fundament, desto schneller gehen die Wände hoch.
+Anthropics Arbeit zu langlebigen Agenten [macht die Initialisierung zu einer eigenen ersten Session](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents). Der Initializer schreibt ein `init.sh`-Skript, eine Fortschrittsdatei, eine Feature-Liste und einen initialen Git-Commit; spätere Coding-Sessions lesen diesen Zustand, arbeiten jeweils an einem Feature, testen es end-to-end, committen und aktualisieren die Fortschrittsdatei.
OpenAIs Codex harness Engineering-Leitfaden betont ebenfalls das Prinzip „Repository als operativer Datensatz" — etablieren Sie von Anfang an eine klare Betriebsstruktur, sonst muss jede neue Session Projektkonventionen neu erschließen.
diff --git a/docs/de/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/de/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
index c052b15..afad759 100644
--- a/docs/de/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
+++ b/docs/de/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -26,7 +26,7 @@ Claude Codes tatsächliches Verhalten ist aufschlussreich. Bitten Sie es, „Ben
Sechs Schritte später ist jeder halb fertig. Keine End-to-End-Verifizierung, komplexe Kopplung zwischen dem halbfertigen Code, und die nächste Session, die alles aufarbeiten muss, wird völlig verloren sein. Wie jemand, der sechs Gerichte gleichzeitig kocht — jedes Gericht ist in der Pfanne, aber keines ist angerichtet. Sie alle verbrennen.
-Anthropics experimentelle Daten unterstützen dies direkt: Agenten mit einer „kleiner nächster Schritt"-Strategie (entspricht WIP=1) zeigen eine um 37% höhere Aufgaben-Abschlussrate als Agenten mit breiten Prompts. Noch interessanter: Die Anzahl der vom Agenten generierten Codezeilen ist schwach negativ korreliert mit dem tatsächlichen Feature-Abschluss — mehr Code geschrieben, weniger Features abgeschlossen. Sich mehr auf den Teller laden, als man bewältigen kann, datenbewiesen.
+Anthropics Leitfaden für langlebige Agenten [verlangt vom Coding-Agenten, jeweils an einem Feature zu arbeiten](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), es dann zu verifizieren, zu committen und den Fortschritt zu aktualisieren, bevor es weitergeht. Ein breiter Prompt lädt den Agenten ein, mehrere Stränge gleichzeitig zu beginnen, und jeder Strang konkurriert um dasselbe Kontext- und Verifikationsbudget.
## WIP=1-Workflow
diff --git a/docs/de/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/de/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
index 62211e6..a2c2f3d 100644
--- a/docs/de/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
+++ b/docs/de/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -23,7 +23,7 @@ Did user auth, shopping cart mostly done, still need payments
Kann eine neue Agentensitzung daraus diese Fragen beantworten? Was bedeutet "mostly done"? Welche Tests hat der Warenkorb bestanden? Was blockiert Payments? Die Antwort auf alles lautet: "Niemand weiß es." Wie wenn du deinem Arzt sagst: "Mein Bauch tut weh, war in letzter Zeit schon okay" - welches Medikament soll er verschreiben?
-Das Ergebnis: Die neue Sitzung verbringt 20 Minuten damit, den Projektzustand zu erschließen, und implementiert möglicherweise bereits fertige Features erneut. Anthropics Engineering-Daten zeigen, dass gute Fortschrittsaufzeichnungen die Diagnosezeit beim Sitzungsstart um 60-80% reduzieren.
+Das Ergebnis: Die neue Sitzung muss den Projektzustand erst erschließen und implementiert möglicherweise bereits fertige Features erneut. Anthropics Empfehlung ist, [Fortschritt und Verifikationsergebnisse in versionierten Dateien festzuhalten](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), damit die nächste Sitzung den Zustand einsehen kann.
## Feature-Zustandsmaschine
@@ -112,7 +112,7 @@ Eine E-Commerce-Plattform mit 10 Features. Zwei Tracking-Ansätze wurden verglic
**Rückgrat-Modus**: Jedes Feature hat einen klaren Zustand und einen Verifikationsbefehl. Eine neue Sitzung liest die Feature-Liste und weiß in 3 Minuten: F01-F05 sind `passing`, F06 ist `active`, F07-F10 sind `not_started`. Sie macht direkt bei F06 weiter, ohne Nacharbeit.
-Quantifiziertes Ergebnis: Projekte mit strukturierten Feature-Listen zeigen eine 45% höhere Feature-Abschlussrate als Freiform-Tracking, bei null doppelten Implementierungen.
+Eine strukturierte Liste bringt Zustand und Verifikationsbefehl jedes Features an einen Ort, sodass die neue Sitzung weiß, was erledigt ist.
## Wichtigste Erkenntnisse
diff --git a/docs/de/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/de/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
index 6cbcdb1..97a1cda 100644
--- a/docs/de/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
+++ b/docs/de/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -70,7 +70,7 @@ Ein unabhängiger evaluierender Agent, der speziell darauf abgestimmt ist, „pi
| Architektur | Laufzeit | Kosten | Kernfunktionen funktionsfähig? |
|--------------|---------|------|------------------------|
| Einzelner Agent (ohne Harness) | 20 Min. | $9 | Nein (Spiel-Entitäten reagieren nicht auf Eingabe) |
-| Drei Agenten (Planer + Generator + Evaluator) | 6 Stunden | $200 | Ja (Spiel ist vollständig spielbar) |
+| Drei Agenten (Planer + Generator + Evaluator) | 6 Stunden | $200 | Kern-Gameplay lief; Physik- und Level-Probleme blieben |
Dies ist exakt dasselbe Modell (Opus 4.5) mit exakt demselben Prompt („build a 2D retro game editor"). Der einzige Unterschied ist der Harness — vom „nackten Ausführen" zu „Planer entfaltet Anforderungen → Generator implementiert Feature für Feature → Evaluator führt tatsächliches Klick-Testing mit Playwright durch".
@@ -119,7 +119,7 @@ Wirksame Laufzeit-Signale umfassen:
**Tatsächliche Punkteabzüge**: (1) End-to-End-Ablauf ungetestet — das tatsächliche Senden und Verifizieren des Zurücksetzungslinks wurde nie bestätigt. (2) Datenbankmigration scheiterte nach teilweiser Ausführung, was eine Schemainkonsistenz verursachte. (3) E-Mail-Service-Konfiguration fehlte in der Zielumgebung.
-**Harness-Intervention**: Terminierungsvalidierung erzwungen — (1) Vollständige App starten, um die Erreichbarkeit des Reset-Endpunkts zu verifizieren; (2) Den vollständigen Reset-Flow ausführen; (3) Datenbankzustandskonsistenz verifizieren. Alle Defekte wurden innerhalb der Session gefunden, was 5-10x der Kosten für spätere Reparaturen einsparte. Der unabhängige Korrektor fand die echten Probleme.
+**Harness-Intervention**: Terminierungsvalidierung erzwungen — (1) Vollständige App starten, um die Erreichbarkeit des Reset-Endpunkts zu verifizieren; (2) Den vollständigen Reset-Flow ausführen; (3) Datenbankzustandskonsistenz verifizieren. Alle drei Defekte tauchen innerhalb der Session auf, solange die Behebung noch lokal ist. Der unabhängige Korrektor fand die echten Probleme.
## Wichtigste Erkenntnisse
diff --git a/docs/de/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/de/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
index 2ff7028..f8453ae 100644
--- a/docs/de/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
+++ b/docs/de/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -132,7 +132,7 @@ Jedes Mal, wenn eine neue Art von Agentenfehler beim Code-Review gefunden wird,
| Berechtigungsproblem | Unterschiedliche Berechtigungen in der Paketumgebung | Verpasst | Gefunden |
| Fehlerpropagation | Service-Layer-Exceptions erreichten UI-Schicht nicht | Verpasst | Gefunden |
-Alle 5 Defekte wurden von End-to-End-Tests gefunden, während Unit-Tests keinen einzigen entdeckten. Die Kosten waren ein Anstieg der Testzeit von 2 Sekunden auf 15 Sekunden — in einem Agenten-Workflow völlig akzeptabel. Egal wie gut jeder Teil einzeln singt, es kann nicht mit einer vollständigen Ensemble-Probe mithalten.
+Alle 5 Defekte wurden von End-to-End-Tests gefunden, während Unit-Tests keinen einzigen entdeckten. Der End-to-End-Lauf ist langsamer, aber diese Kosten sind klein im Vergleich dazu, fünf Grenzfall-Defekte auszuliefern. Egal wie gut jeder Teil einzeln singt, es kann nicht mit einer vollständigen Ensemble-Probe mithalten.
## Wichtigste Erkenntnisse
diff --git a/docs/de/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/de/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
index 321ea27..8cbd577 100644
--- a/docs/de/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
+++ b/docs/de/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -44,7 +44,7 @@ Wenn einem harness Beobachtbarkeit fehlt, treten vier Problemtypen systematisch
**Retries werden blinde Vermutungen**: Wenn der Agent nicht weiß, warum etwas fehlschlägt, ist die Retry-Richtung zufällig. Er kann irrelevante Codepfade reparieren, während die eigentliche Ursache unberührt bleibt. Jeder blinde retry kostet Tokens und Zeit.
-**Informationsklippe beim Handoff**: Wenn unvollständige Arbeit an die nächste Session übergeben wird, muss die neue Session ohne Beobachtbarkeit den Systemzustand von Grund auf diagnostizieren. Anthropic beobachtet, dass diese redundante Diagnose 30-50 % der Sessionzeit verbrauchen kann.
+**Informationsklippe beim Handoff**: Wenn unvollständige Arbeit an die nächste Session übergeben wird, muss die neue Session ohne Beobachtbarkeit den Systemzustand von Grund auf diagnostizieren. Die neue Session muss Code erneut lesen, Befehle erneut ausführen und entscheiden, welche Signale zählen; [versionierte Fortschritts- und Verifikationsaufzeichnungen](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) liefern einen inspizierbaren Zustand.
### Ein realistisches Claude-Code-Szenario
@@ -54,7 +54,7 @@ Stell dir einen harness mit planner-generator-evaluator-Workflow vor, der "Dark
**Mit vollständiger Beobachtbarkeit**: Der planner liefert einen sprint contract mit zu ändernden Komponenten, Verifikationsstandards und Ausschlüssen. Der generator implementiert gemäß Vertrag. Runtime-Beobachtbarkeit zeichnet das Laden und Anwenden der Styles jeder Komponente auf. Der evaluator bewertet Dimension für Dimension anhand einer Rubrik und konkreter Evidenz. Eine Iteration liefert ein hochwertiges Ergebnis in etwa 15 Minuten.
-3x Effizienzunterschied. Die einzige Änderung ist Beobachtbarkeit.
+Der Unterschied hängt davon ab, ob Vertrag und Evidenz außerhalb des Kopfes des Agenten existieren.
### Warum Agenten das nicht selbst lösen können
@@ -128,7 +128,7 @@ Ein harness mit planner-generator-evaluator-Workflow führt "Dark Mode Support h
- Bewertungsrubrik liefert strukturierte Bewertung pro Dimension
- Eine Iteration liefert hochwertige Ergebnisse in 15 Minuten
-3x Effizienzgewinn, stabilere Qualität, reproduzierbare Bewertungen.
+Stabilere Qualität und reproduzierbare Bewertungen.
## Wichtigste Erkenntnisse
@@ -136,7 +136,7 @@ Ein harness mit planner-generator-evaluator-Workflow führt "Dark Mode Support h
- **Beide Beobachtbarkeitsschichten sind wesentlich**: Runtime-Signale erklären "was passiert ist", Prozessartefakte erklären "warum es so gemacht wurde".
- **Sprint contracts richten früh aus** und verhindern vorhersehbare Ablehnungen durch evaluator.
- **Rubriken machen Bewertung reproduzierbar**, sodass verschiedene Evaluatoren ähnliche Scores liefern.
-- **Fehlende Beobachtbarkeit verschwendet 30-50 % der Sessionzeit für redundante Diagnose.**
+- **Beobachtbarkeit verwandelt eine vage Ablehnung in einen konkreten, behebbaren Defekt.**
## Weiterführende Literatur
diff --git a/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
index 4b283d2..1daf7ad 100644
--- a/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
+++ b/docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -52,7 +52,7 @@ flowchart LR
Lehmans Gesetze der Software-Evolution sagen uns: Systeme, die kontinuierlichen Änderungen unterliegen, werden unausweichlich an Komplexität zunehmen, es sei denn, sie werden aktiv verwaltet. Dies gilt insbesondere für KI-Coding-Agenten — jede Session führt Änderungen ein, und ohne Cleanup beim Exit akkumuliert sich technische Schuld exponentiell.
-Echte Daten sind aussagekräftig. Ein Projekt, das 12 Wochen lang mit Agenten entwickelt wurde, ohne Cleanup-Strategie:
+Für ein hypothetisches 12-Wochen-Projekt nehmen wir die folgenden Werte an:
- Woche 1: Build-Pass-Rate 100%, Test-Pass-Rate 100%, neue Session Startup 5 Min.
- Woche 4: Build 95%, Tests 92%, Startup 15 Min.
@@ -64,7 +64,7 @@ Dasselbe Projekt mit einer Cleanup-Strategie:
- Woche 1: 100%, 100%, 5 Min.
- Woche 12: 97%, 95%, 9 Min.
-Nach 12 Wochen: Die Build-Pass-Rate unterscheidet sich um 29 Prozentpunkte, die Startup-Zeit für neue Sessions um 85%. Das ist nicht theoretisch — es ist ein beobachteter Unterschied.
+Eine wöchentliche Cleanup-Schleife hält den Ausgangszustand stabil: Jede Session endet mit bestandenem Build, bestandenen Tests, dokumentiertem Fortschritt und aufgeräumten temporären Artefakten, sodass die nächste Session von derselben Basis startet.
### Fünf Dimensionen des Clean State
@@ -74,7 +74,7 @@ Clean State bedeutet nicht nur „der Code kompiliert". Es sind fünf Dimensione
**Test-Dimension**: Bestehen alle Tests? Einschließlich der Tests, die vor der Session existierten — die Session ist dafür verantwortlich, bestehende Funktionalität nicht zu beschädigen. Und es sollte in CI verifiziert werden, nicht nur „funktioniert auf meinem Rechner".
-**Fortschritts-Dimension**: Ist der aktuelle Fortschritt in einem maschinenlesbaren Artefakt dokumentiert? Abgeschlossene Teilaufgaben mit ihren Bestehenskriterien, in Bearbeitung befindliche aber unvollständige Teilaufgaben mit aktuellem Zustand, noch nicht gestartete Teilaufgaben. Gute Fortschrittsaufzeichnungen reduzieren 60-80% der Diagnosezeit beim Session-Startup.
+**Fortschritts-Dimension**: Ist der aktuelle Fortschritt in einem maschinenlesbaren Artefakt dokumentiert? Abgeschlossene Teilaufgaben mit ihren Bestehenskriterien, in Bearbeitung befindliche aber unvollständige Teilaufgaben mit aktuellem Zustand, noch nicht gestartete Teilaufgaben. Fortschritt und Verifikationsergebnisse gehören in versionierte Dateien, damit die nächste Session den Zustand einsehen kann.
**Artefakt-Dimension**: Gibt es veraltete oder mehrdeutige temporäre Artefakte? Debug-Logs, temporäre Dateien, auskommentierter Code, TODO-Marker — all diese erhöhen die kognitive Belastung für die nächste Session.
@@ -158,7 +158,7 @@ Eine Electron-App, die über 12 Wochen mit Agenten entwickelt wurde, im Vergleic
**Mit Cleanup-Strategie** (Versuchsgruppe): Vollständiger Clean-State-Check am Ende jeder Session + wöchentliche Cleanup-Schleife. Woche 12, Build-Pass-Rate 97%, Test-Pass-Rate 95%, neue Session Startup 9 Min., veraltete Artefakte 11.
-In Woche 12 liegt die Build-Pass-Rate der Versuchsgruppe um 29 Prozentpunkte höher, die Test-Pass-Rate um 34 Punkte höher und die Startup-Zeit für neue Sessions um 85% niedriger.
+In Woche 12 lagen Build- und Test-Pass-Rate der Cleanup-Gruppe noch nahe am Ausgangspunkt, eine neue Session konnte schnell starten, und es gab nur wenige veraltete Artefakte. Das Cleanup kostete pro Session nur wenige Minuten und hinterließ einen Ausgangszustand, dem die nächste Session vertrauen konnte.
## Wichtigste Erkenntnisse
diff --git a/docs/de/lectures/lecture-13-loop-engineering/index.md b/docs/de/lectures/lecture-13-loop-engineering/index.md
index a9425c4..54e13b6 100644
--- a/docs/de/lectures/lecture-13-loop-engineering/index.md
+++ b/docs/de/lectures/lecture-13-loop-engineering/index.md
@@ -84,11 +84,11 @@ Loop Engineering, das Thema dieser Lektion, geht es nicht um irgendeinen einzeln
Du musst nicht jedes Mal `/goal` eingeben. Aber zu verstehen, woher es kommt und warum es so aussieht, wie es aussieht — das ist das Verständnis des Kerns von Loop Engineering. Komplexere Loops fügen nur Teile wie Scheduling, Parallelismus, Isolation und Speicher auf diesen selben drei Grundlagen hinzu: Ziel, Verifikation, Stoppbedingung.
-## Juni 2026: Drei Leute haben in einer Woche dieselbe Zündung ausgelöst
+## Verschiedene Daten, dieselbe Richtung
-In der ersten Juniwoche 2026 haben drei Praktiker, die Infrastruktur für Coding-Agenten aufbauen — ohne sich abzusprechen — dasselbe in verschiedenen Worten gesagt.
+Dieselbe Idee tauchte an verschiedenen Orten und zu verschiedenen Zeiten auf.
-**Peter Steinberger** (Erfinder von OpenClaw, [sein Beitrag erreichte 8 Millionen Aufrufe](https://x.com/steipete/status/2063697162748260627)): „Du solltest Coding-Agenten nicht mehr prompten. Du solltest Loops designen, die deine Agenten prompten.“
+**Peter Steinberger** (Erfinder von OpenClaw, [in einem Beitrag](https://x.com/steipete/status/2063697162748260627)): „Du solltest Coding-Agenten nicht mehr prompten. Du solltest Loops designen, die deine Agenten prompten.“
**Boris Cherny** (Leiter von Claude Code bei Anthropic, [im Acquired-Podcast](https://x.com/rohanpaul_ai/status/2063289804708835412)): „Ich prompt Claude nicht mehr. Ich habe Loops laufen, die Claude prompten und herausfinden, was zu tun ist. Mein Job ist es, Loops zu schreiben.“
@@ -96,9 +96,9 @@ In der ersten Juniwoche 2026 haben drei Praktiker, die Infrastruktur für Coding
> **Loop Engineering bedeutet, dich selbst als die Person zu ersetzen, die den Agenten promptet. Du designst stattdessen das System, das es tut.**
-Cherny hat Zahlen genannt: Über 30 aufeinanderfolgende Tage wurden alle Code-Beiträge zu Claude Code autonom von KI erstellt — 259 gemergte PRs, über 80 % des Produktionscodes von Claude verfasst, und eine Erfolgsrate von 76 % bei offenen Softwareaufgaben.
+Cherny schrieb in einem [persönlichen Bericht vom 27.12.2025](https://twitter.com/bcherny/status/2004887829252317325), dass er über 30 Tage 259 PRs gemergt hat — 497 Commits, 40.000 Zeilen hinzugefügt, 38.000 entfernt — und dass jede Zeile von Claude Code + Opus 4.5 geschrieben wurde.
-Drei Leute. Eine Woche. Dieselbe Schlussfolgerung. Nicht weil sie koordiniert haben — sondern weil die Infrastruktur leise eine Schwelle überschritten hat. Agenten waren zuverlässig genug geworden, um nicht-triviale Aufgaben unbeaufsichtigt abzuschließen. Scheduling-Primitive (`/loop`, `/goal`, cron) waren jetzt in die Werkzeuge eingebaut. Die Kosten eines einzelnen Agenten-Laufs waren so niedrig geworden, dass das wiederholte Ausführen auf einem Timer nicht mehr verschwenderisch wirkte. Wenn alle Teile vorhanden sind, wird der Schritt, sie zu kombinieren, für alle gleichzeitig offensichtlich.
+Die Zitate stammen aus verschiedenen Daten, Formaten und Teams. Ihre gemeinsame Richtung: Scheduling, Verifikation und die Stopp-Entscheidung aus dem momentanen Prompt herauszunehmen und in ein System zu verlagern. Mitte 2026 konnten Agenten nicht-triviale Aufgaben unbeaufsichtigt abschließen, Scheduling-Primitive waren eingebaut, und ein Lauf war billig genug, um ihn per Timer zu wiederholen. Wenn die Teile vorhanden sind, setzen mehr als eine Person sie zusammen.
> Quelle: [Addy Osmani: Loop Engineering](https://addyosmani.com/blog/loop-engineering/)
@@ -267,7 +267,7 @@ flowchart TD
Das ist nicht mehr ein einzelner Agent-Lauf. Es ist ein kontinuierlich arbeitendes System, das jeden Morgen aufwacht, den Boden selbst fegt und die Dinge, die deine Aufmerksamkeit brauchen, vor dich legt. Deine Rolle wird: **Überprüfe den Eingangsinhalt, triff Entscheidungen, und wenn du ein Muster erkennst, das das System nicht handhaben kann, verfeinere die Skills und Regeln.**
-Cherny hat dieses Muster verwendet, um 259 PRs in 30 Tagen zu mergen, ohne jemals eine IDE zu öffnen. OpenAI-Ingenieure haben dasselbe Muster verwendet, um ein etwa eine Million Zeilen großes Beta-Produkt von Hand zu bauen — ohne selbst eine einzige Codezeile zu schreiben.
+Chernys 30-Tage-Bericht ist ein Datenpunkt für dieses Muster: 259 PRs, der Code von Claude Code + Opus 4.5 geschrieben. OpenAIs [Harness-Bericht](https://openai.com/index/harness-engineering/) ist ein weiterer: Ein kleines Team nutzte Codex fünf Monate lang in einem Greenfield-Repository und berichtete von etwa einer Million Zeilen und rund 1.500 PRs.
## Generator/Evaluator-Trennung: Warum du das Modell nicht seine eigene Arbeit benoten lassen kannst
@@ -293,7 +293,7 @@ Ein Satz zum Merken: **Jemand in deiner Crew muss dir nicht glauben.**
Wenn du sehen willst, wie ein gut designter, tatsächlich laufender Loop aussieht, ist [Karpathy's autoresearch](https://github.com/karpathy/autoresearch) das Lehrbuchbeispiel.
-Im März 2026 veröffentlichte Karpathy ein 630-Zeilen-Python-Projekt. Gib ihm eine GPU und eine Forschungsrichtung, und es läuft die ganze Nacht — es führt Hunderte von ML-Trainingsexperimenten durch und behält nur die, die wirklich verbessern. Das Projekt erreichte innerhalb weniger Tage nach der Veröffentlichung 66.000+ Stars.
+Im März 2026 veröffentlichte Karpathy [autoresearch](https://github.com/karpathy/autoresearch). Das Repository ist bewusst klein: `prepare.py` ist feste Infrastruktur, `train.py` ist die Datei, die der Agent bearbeitet (etwa 630 Zeilen), und `program.md` ist die Forschungsmethodik, die der Mensch bearbeitet. Gib ihm eine GPU und eine Forschungsrichtung, und es läuft über Nacht — jedes Experiment bekommt ein festes Trainingsbudget von 5 Minuten Wanduhrzeit (ohne Start und Kompilierung), und nur Änderungen, die `val_bpb` verbessern, bleiben erhalten.
### Drei Dateien, drei Rollen
@@ -343,9 +343,9 @@ flowchart TD
8b --> 9
```
-Es laufen etwa 12 Experimente pro Stunde. Ein Übernacht-Lauf (8 Stunden) ergibt etwa 100 Experimente. Karpathy selbst hat es 2 Tage laufen lassen — ~700 Experimente.
+Die README schätzt etwa 12 Experimente pro Stunde, also rund 100 in einem 8-stündigen Übernacht-Lauf. Das 5-Minuten-Budget deckt das Training ab, nicht Start oder Kompilierung; der Rest jeder Runde geht für Bearbeiten, Starten und Auswerten drauf. Karpathy berichtete, dass er eine private Version von autoresearch für die unten beschriebene nanochat-Runde etwa zwei Tage autonom laufen ließ.
-Das feste 5-Minuten-Wall-Clock-Budget ist eine wichtige Designentscheidung — egal was der Agent ändert, jedes Experiment dauert genau gleich lange. Das bedeutet, alle Ergebnisse sind unter demselben Zeitbudget direkt vergleichbar — keine Diskussion darüber, dass „dieses länger gelaufen ist, also ist es besser“.
+Das feste 5-Minuten-Trainingsbudget ist eine wichtige Designentscheidung — egal was der Agent ändert, der Trainingslauf bekommt dasselbe Wanduhr-Budget. Das bedeutet, alle Ergebnisse sind unter demselben Trainingsbudget direkt vergleichbar.
### Ausgabe: Was du siehst, wenn du aufwachst
@@ -375,13 +375,9 @@ Der Agent schreibt klare Commit-Nachrichten darüber, was er ausprobiert hat, wa
### Was er tatsächlich gefunden hat
-Ergebnisse von Karpathy's anfänglichem 2-tägigen, ~700-Experimente-Lauf:
+Die Ergebnisse von autoresearch [Runde 1](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b) verkürzten nanochats Trainingszeit für GPT-2-Niveau auf 8×H100 [von **2,02 Stunden auf 1,80 Stunden**](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b), eine Reduktion der Trainingszeit um etwa **10,9 %**.
-- Von ~700 Versuchen wurden etwa **20 stapelbare echte Verbesserungen** gefunden
-- Reduzierte nanochat's GPT-2-level Trainingszeit auf 8×H100 von **2,02 Stunden → 1,80 Stunden**, etwa **11 % schneller**
-- Funde umfassten: Lernratenanpassungen, Optimierer-Tuning, Aktivierungswechsel, Attention-Muster-Optimierungen usw.
-
-Waren alle Verbesserungen bahnbrechende Entdeckungen? Nein. Die meisten waren kleine Optimierungen, die sich gestapelt haben. Aber diese 20 gültigen Verbesserungen hätten einem menschlichen Forscher Wochen manueller Arbeit gedauert — der Agent hat es in 48 Stunden geschafft.
+Die meisten Änderungen waren kleine Optimierungen, die sich stapelten. Der nützliche Teil ist der Loop: ein festes Budget, ein vollständiges Experimentprotokoll und die Regel, dass nur verifizierte Verbesserungen bleiben.
### Das aussagekräftigste Detail: Der Loop ist in Englisch geschrieben, nicht in Code.
@@ -399,7 +395,7 @@ Schnelle Loops verführen dich dazu, Verifikation zu überspringen. „Sieht gut
### 2. Verständnisverfall
-Je schneller ein Loop Code ausliefert, desto weiter driftet dein Verständnis deiner eigenen Codebase von der Realität ab. Cherny's Team hatte 80 % des Codes von Agenten verfasst — das bedeutet, der meiste Code eines Teams wurde nicht von einer Person geschrieben. Wenn du nicht liest und nutzt, was der Loop erzeugt, verfällt dein Verständnis kontinuierlich. **Schnelle Loops erfordern schnelles Lesen.**
+Je schneller ein Loop Code ausliefert, desto weiter driftet dein Verständnis deiner eigenen Codebase von der Realität ab. Ein Loop landet Hunderte PRs; das Team liest diese PRs, prüft die wichtigen Diffs und nutzt den Code weiter, sodass sein mentales Modell mithält. **Schnelle Loops erfordern schnelles Lesen.**
### 3. Kognitive Kapitulation
@@ -407,11 +403,11 @@ Wenn der Loop reibungslos läuft, ist die bequemste Haltung, aufzuhören, Meinun
### 4. Token-Explosion
-Jede Iteration eines Loops sammelt mehr Kontext an: geschriebener Code, aufgetretene Fehler, getroffene Entscheidungen. Ohne Kontextmanagement wächst die Prompt-Größe grob quadratisch mit der Anzahl der Züge. Codex adressiert das mit automatischer Kontextkompaktierung — eine dedizierte API komprimiert ältere Konversationszüge in verschlüsselte Inhaltszusammenfassungen, behält wesentliches Wissen und verwirft redundante Details. Das ist eine Engineering-Angelegenheit, die du ab dem ersten Loop adressieren musst, nicht ein späterer Nachrüstding.
+Jede Iteration eines Loops sammelt mehr Kontext an: geschriebener Code, aufgetretene Fehler, getroffene Entscheidungen. Wenn jede Runde ungefähr eine feste Menge neuer Inhalte hinzufügt, wächst die von einer einzelnen Runde gesehene Historie ungefähr linear mit der Anzahl der Runden. Wenn das System jede Runde die gesamte Historie neu verarbeitet, wächst die kumulierte Eingabe über N Runden ungefähr quadratisch. Codex adressiert das mit automatischer Kontextkompaktierung — eine dedizierte API komprimiert ältere Konversationszüge in verschlüsselte Inhaltszusammenfassungen, behält wesentliches Wissen und verwirft redundante Details. Das ist eine Engineering-Angelegenheit, die du ab dem ersten Loop adressieren musst, nicht ein späterer Nachrüstding.
## Deinen ersten Loop bauen
-Du musst nicht mit einer Pipeline im Stripe-Maßstab anfangen, die 1.300 PRs pro Woche merged. Fang mit dem Kleinsten an, das funktioniert.
+Du musst nicht mit einer Hochdurchsatz-Pipeline anfangen. Fang mit dem Kleinsten an, das funktioniert.
### Schritt 1: Wähle eine wiederkehrende Aufgabe
diff --git a/docs/de/lectures/lecture-14-graph-engineering/index.md b/docs/de/lectures/lecture-14-graph-engineering/index.md
index 29daf7c..705f15d 100644
--- a/docs/de/lectures/lecture-14-graph-engineering/index.md
+++ b/docs/de/lectures/lecture-14-graph-engineering/index.md
@@ -9,7 +9,7 @@ Sechs Wochen nachdem Loop Engineering zum Mainstream wurde, am 18. Juli 2026, po
> „Reden wir noch über Loops oder sind wir schon zu Graphen übergegangen?“
-Ein Tweet — etwa 575.000 Aufrufe innerhalb eines Tages, bis zum Monatsende auf rund 3 Millionen ansteigend. Ein paar Stunden später veröffentlichte ML-Ingenieur Hamel Husain *Loop Engineering Is Dead. Enter Graph Engineering* — einen Artikel, dessen ganzer Inhalt aus einem einzigen „Stop it“-GIF bestand — und holte damit noch einmal rund 680.000 Aufrufe.
+Ein Tweet. Ein paar Stunden später veröffentlichte ML-Ingenieur Hamel Husain *Loop Engineering Is Dead. Enter Graph Engineering* — einen Artikel, dessen ganzer Inhalt aus einem einzigen „Stop it“-GIF bestand.
Hier ist die Wendung: **Beide haben nur gescherzt.** Der eine machte sich über eine Branche lustig, die alle sechs Wochen einen neuen Begriff erfindet; der andere spielte auf diesem Gag auf. Aber der Witz überlebte etwa ein Wochenende — Kurse, Roadmaps und Tool-Stacks fluteten die Timeline, bevor das Wochenende vorbei war, gefolgt von einem Haufen erfundener Zahlen: die Behauptung „+18 % Genauigkeit, −85 % Kosten“ ist gefälscht (die beiden Zahlen existieren zwar, stammen aber aus einem Paper über chemische Rohrleitungsdiagramme und vergleichen unterschiedliche Baselines), und auch die Behauptung „Microsoft, Stanford und Anthropic haben gleichzeitig Graph Engineering entdeckt“ ist falsch. Die Faktenprüfung findet genau einen echten „Vorläufer“: Josh Simmons, dessen *We Are Entering the Graph Engineering Phase* auf den 4. Juli datiert ist — zwei volle Wochen vor dem Witz. **Der Witz hat die Idee populär gemacht. Er hat sie nicht erschaffen.**
@@ -257,11 +257,11 @@ Hältst du das am Ende gegen das Diagramm oben? Dein handgeschriebenes `graph.md
## Open-Source-Projekte: Nach dem Namen, vor dem Namen
-Zuerst ziehe die Linie: **„Graph Engineering“ ist ein Name, der erst nach dem 18. Juli 2026 existiert.** Frameworks, die vor diesem Datum open-sourced wurden, sind keine „Graph-Engineering-Projekte nach der Veröffentlichung“. Stand Anfang August 2026 hält nur ein Open-Source-Projekt, das diesen Namen trägt, stand:
+Zuerst ziehe die Linie: **„Graph Engineering“ ist ein Name, der erst nach dem 18. Juli 2026 existiert.** Frameworks, die vor diesem Datum open-sourced wurden, sind keine „Graph-Engineering-Projekte nach der Veröffentlichung“. Ein Projekt, das den Namen ausdrücklich verwendet, ist GraphARC:
**Projekte nach der Veröffentlichung (das eine, das wirklich Graph Engineering heißt)**
-- [GraphArc](https://github.com/CodeGraphContext/grapharc) (2026-08-02): nennt sich selbst „die erste Echtzeit-Implementierung von Graph Engineering“. Es verwandelt die Agenten-Ausführung von Traces, die in Logs vergraben sind, in einen **interaktiven Echtzeit-Orchestrierungsgraphen** — jeder Agent, jede Abhängigkeit und jeder Entscheidungspunkt wird gezeichnet, zur Freigabe vor der Ausführung visualisiert (du kannst es sogar vom Handy aus ansehen). Der Hintergrund des Autors ist das Bauen von Graph-Tools für 4.000+ Entwickler; die Richtung ist „beobachtbar, debugbar, engineerbar“. Sehr neu, noch in einem frühen Stadium.
+- [GraphARC](https://github.com/CodeGraphContext/GraphARC) (im Juli 2026 erstellt): beschreibt sich selbst als „an end to end implementation of Graph Engineering as proposed by Andrew NG and Peter Steinberger“. Es ist ein frühes Python-Projekt. Der nützliche Schritt ist, sein Orchestrierungsmodell zu lesen und zu entscheiden, ob der Ansatz zu deinem Workflow passt.
**Projekte vor der Veröffentlichung (sie nennen es nicht Graph Engineering — aber mit ihnen baust du tatsächlich)**
@@ -325,7 +325,7 @@ Nicht jede Aufgabe verdient einen Graphen. Fünf Kriterien — versuche mindeste
- [goddaehee: Graph Engineering Faktencheck (KR, 2026-07-30)](https://goddaehee.tistory.com/628) — der vollständigste Faktencheck: die Witz-Ursprungs-Zeitlinie, die auseinandergenommenen falschen Zahlen, LangGraph-Daten, Hacker-News-Hitze-Vergleich
- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — der ernste Beitrag, der zwei Wochen vor dem Witz geschrieben wurde
- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — die offizielle Antwort: „keine neue Idee, der neueste Name für einen etablierten Ansatz“; LangGraphs 65 Mio.+ monatliche Downloads
-- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — Hype-Verbreitungsdaten (575.000 Aufrufe auf dem ursprünglichen Tweet)
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — eine erzählerische Darstellung davon, wie sich der Begriff verbreitete
- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — ein Kopf-an-Kopf-Vergleich von sieben Mainstream-Open-Source-Frameworks: LangGraph, CrewAI, Microsoft Agent Framework, LlamaIndex, Google ADK, OpenAI Agents SDK, Mastra
- [LangGraph offizielle Dokumentation](https://docs.langchain.com/oss/python/langgraph/graph-api) — „Nodes do the work, edges tell what to do next“; die präzisen Definitionen von Knoten und Kanten, die Referenz aus erster Hand für das Bauen von Graphen
- [Anthropic: Building Effective Agents (Dez 2024)](https://www.anthropic.com/engineering/building-effective-agents) — fünf Muster, die gezeichnet Graphen sind; die maßgebliche Workflow-vs-Agent-Unterscheidung
diff --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.md
index 890bdb3..764cc21 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
@@ -5,13 +5,13 @@
# Lecture 01. Strong Models Don't Mean Reliable Execution
-As of late 2025, the strongest coding agents on SWE-bench Verified achieve roughly a 50-60% pass rate. That number sounds decent at first glance — but don't celebrate just yet. Those are carefully selected tasks with clear issue descriptions and ready-made test cases. Hand the agent your everyday requirements instead — vague specs, no existing tests, implicit business rules scattered across the codebase — and the pass rate only drops further. You hand off a task brimming with confidence, the agent runs for 20 minutes and tells you "all done," and you look at the code: it added a feature but broke the tests, fixed a bug but introduced new ones, and it's not even what you asked for.
+On September 29, 2025, Anthropic reported Claude Sonnet 4.5 at [77.2% on SWE-bench Verified](https://www.anthropic.com/news/claude-sonnet-4-5). That number sounds decent at first glance — but don't celebrate just yet. Those are carefully selected tasks with clear issue descriptions and ready-made test cases. Hand the agent your everyday requirements instead — vague specs, no existing tests, implicit business rules scattered across the codebase — and the pass rate only drops further. You hand off a task brimming with confidence, the agent runs for 20 minutes and tells you "all done," and you look at the code: it added a feature but broke the tests, fixed a bug but introduced new ones, and it's not even what you asked for.
When this happens, most people's first reaction is "the model isn't good enough — let me try a more expensive one." Before you reach for your wallet, consider that the problem might not be the model at all.
## Same Horse, Different Fates
-Anthropic ran a controlled experiment that illustrates the point perfectly. Same prompt ("build a 2D retro game editor"), same model (Opus 4.5), two runs. First run: bare, no support — 20 minutes, $9, the game's core features didn't work. Second run: full harness — a planner, generator, evaluator three-agent architecture — 6 hours, $200, the game was fully playable.
+Anthropic compared the same prompt ("build a 2D retro game editor") and the same model (Opus 4.5) under two harnesses. First run: bare, no support — 20 minutes, $9; the app opened, but entities did not respond to input. Second run: full harness — a planner, generator, evaluator three-agent architecture — 6 hours, $200; the author could move an entity, but physics had rough edges and a wall blocked progress. [Core gameplay worked; the app was not finished.](https://www.anthropic.com/engineering/harness-design-long-running-apps)
They didn't change the model. Opus 4.5 was still Opus 4.5. What changed was the tack.
@@ -31,9 +31,9 @@ The specific failure modes really come down to just a handful:
With the scenarios above 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 go unresolved.
+- **Capability Gap**: The huge gulf between model performance on benchmarks and performance on real tasks. Benchmark tasks come with clear issue descriptions, tests, and an environment; real tasks often require you to supply them.
- **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 sufficient capability, but the execution environment has structural defects. Anthropic's controlled experiment already proved this.
+- **Harness-Induced Failure**: The model has sufficient capability, but the execution environment has structural defects. The retro-game comparison above is an example.
- **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 — 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.
- **Definition of Done**: A set of conditions that can be verified by command — tests pass, lint is clean, type checks pass. Without an explicit definition of done, the agent will invent its own.
@@ -60,7 +60,7 @@ From there, build a diagnostic loop. Don't treat failures as "the model being du
## The Million-Line Experiment
-In 2025, three engineers at OpenAI started an experiment. The rules were simple: they wouldn't write code themselves — only Codex would. Starting from an empty git repository, five months later the repo contained roughly one million lines of code. Application logic, infrastructure, tooling, documentation — all agent-generated. The three engineers opened a total of 1,500 PRs, an average of 3.5 per person per day.
+In August 2025, three engineers at OpenAI started an experiment. The rules were simple: they wouldn't write code themselves — only Codex would. Starting from an empty git repository, [five months later the repo contained roughly one million lines of code](https://openai.com/index/harness-engineering/). Application logic, infrastructure, tooling, documentation — all agent-generated. The team later grew to seven engineers; over the period it merged about 1,500 PRs, an average of 3.5 per engineer per day.
Early progress was surprisingly slow. Codex wasn't bad — it just lacked tools and structures complete enough to drive toward high-level objectives. The three engineers gradually found the pattern: break large goals into small building blocks — design, code, review, test — let the agent assemble them one by one, then use those blocks to compose more complex tasks. Whenever something went wrong, the problem was almost never "not trying hard enough." It was always "what is the agent still missing, and can that missing capability be supplied in a way that is both understandable and executable?"
@@ -72,9 +72,9 @@ This experiment directly proves this lecture's core thesis: **the same model pro
A team used Claude Sonnet to add new API endpoints to a mid-sized Python web app (FastAPI + PostgreSQL + Redis, ~15,000 lines of code).
-Initially they gave only one sentence: "add user preferences endpoints under `/api/v2/users`." The result? The agent spent 40% of its context window exploring the repo structure, produced code that looked reasonable but didn't follow the project's error handling patterns, used old SQLAlchemy syntax, and declared completion while the endpoint had runtime errors. The next session had to redo all the discovery work.
+Initially they gave only one sentence: "add user preferences endpoints under `/api/v2/users`." The result? The agent spent much of the session exploring the repo structure, produced code that looked reasonable but didn't follow the project's error handling patterns, used old SQLAlchemy syntax, and declared completion while the endpoint had runtime errors. The next session had to redo all the discovery work.
-Later they added `AGENTS.md` (describing project architecture and tech stack versions), explicit verification commands (`pytest tests/api/v2/ && python -m mypy src/`), and architecture decision records. The same model succeeded in all three independent runs, with ~60% better context efficiency.
+Later they added `AGENTS.md` (describing project architecture and tech stack versions), explicit verification commands (`pytest tests/api/v2/ && python -m mypy src/`), and architecture decision records. The same model then followed the project's conventions and checked its work with commands it could run.
They didn't change the model. They changed the harness.
diff --git a/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
index c5135b5..e672eb6 100644
--- a/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
+++ b/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -50,7 +50,7 @@ flowchart LR
- **Context windows are finite**: No matter what window size is claimed (128K, 200K, 1M), long tasks will eventually exhaust them. After exhaustion, either compaction (losing information) or reset (starting a new session) is required — both lose something.
- **State persistence files**: Persisted state files that let a new session unambiguously resume where the last one left off. The most basic form includes progress logs, verification records, and next actions.
-- **Rebuild cost**: The time a new session needs to reach an executable state. A good harness can compress rebuild cost from 15 minutes to 3 minutes.
+- **Rebuild cost**: The time a new session needs to reach an executable state. A good harness leaves progress, verification results, and next actions in files, so the new session starts from a written state.
- **Drift**: The gap between the agent's understanding and the actual state of the code repository. Every session boundary introduces drift; without control, it compounds session after session.
- **Context anxiety**: A phenomenon observed by Anthropic — agents exhibit rushed finish behavior when approaching context limits, ending tasks early to avoid information loss. At its core, it's an irrational resource anxiety.
- **Compaction vs. reset**: Compaction summarizes context within the same session (keeps "what," may lose "why"); reset opens a new session rebuilding from persisted state (clean but depends on artifact completeness).
@@ -158,7 +158,7 @@ LangChain reports an actual harness improvement using the same gpt-5.2-codex mod
- Context windows are a finite resource. Long tasks will span sessions, and sessions will lose information — this is objective reality.
- The solution isn't bigger windows — it's better state persistence. Progress files, decision logs, and git checkpoints work together to let new sessions pick up where previous ones left off.
- Treat the agent like an engineer whose short-term memory gets wiped every session: before "clocking out," write down what was done, why, and what's next.
-- Rebuild cost is the key metric. A good harness should get new sessions to an executable state within 3 minutes.
+- Rebuild cost is the key metric. A good harness leaves progress, verification results, and next actions in files, so a new session recovers quickly.
- Mixed strategy: short tasks within sessions, long tasks with structured artifacts for continuity.
## Further Reading
diff --git a/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
index 3f1f74a..c64317f 100644
--- a/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
+++ b/docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -37,7 +37,7 @@ flowchart TB
## What Happens When You Mix Them
-The most direct problem: infrastructure doesn't get built solidly. The agent spends 80% of its effort on feature code and the remaining 20% casually setting up some infrastructure. The test framework is configured but never verified, lint rules are set but too loose, no progress file created. These defects aren't obvious in the first session (because the agent still remembers what it did), but they surface in the second session: the new agent doesn't know how to run the project, how to test, or where things stand.
+The most direct problem: infrastructure doesn't get built solidly. The agent spends most of its effort on feature code and treats infrastructure as an afterthought. The test framework is configured but never verified, lint rules are set but too loose, no progress file created. These defects aren't obvious in the first session (because the agent still remembers what it did), but they surface in the second session: the new agent doesn't know how to run the project, how to test, or where things stand.
A more hidden cost is "unverified accumulation." Feature code written before the test framework is properly configured — when you finally go back to add tests, you might discover the design itself was flawed. Had you known earlier, you would have implemented it differently. The more code written up front, the more has to be torn down and redone later.
@@ -45,7 +45,7 @@ Context budget is being wasted too. Initialization work (configuring environment
The most easily overlooked problem is implicit assumption landmines. Decisions the agent makes during initialization (which test framework, how to organize directories, dependency management) — if not explicitly recorded, subsequent sessions may make contradictory choices. The first session chose Vitest as the test framework, but the second session's agent doesn't know and introduces Jest. Two test frameworks coexist, and maintenance costs double.
-Anthropic's long-running application development research explicitly recommends separating initialization from implementation. Their experimental data: projects using a dedicated initialization phase showed 31% higher feature completion rates in multi-session scenarios compared to mixed approaches. And the time invested in the initialization phase is fully recovered within the next 3-4 sessions.
+Anthropic's long-running-agent work [makes initialization a separate first session](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents). The initializer writes an `init.sh` script, a progress file, a feature list, and an initial git commit; later coding sessions read that state, work on one feature at a time, test it end to end, commit, and update the progress file.
OpenAI's Codex harness engineering guide also emphasizes the "repository as operational record" principle: establish clear operational structure from the very first run, or every new session has to re-infer project conventions.
diff --git a/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
index 7912d6b..c828b6f 100644
--- a/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
+++ b/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -26,7 +26,7 @@ Claude Code's real behavior is telling. Ask it to "add user registration" and it
Six steps later, every one is half-done. No end-to-end verification, complex coupling between the half-baked code, and the next session to pick up the pieces will be completely lost.
-Anthropic's experimental data directly supports this: agents using a "small next step" strategy (equivalent to WIP=1) show a 37% higher task completion rate than agents using broad prompts. More interestingly, the number of lines of code generated by agents is weakly negatively correlated with actual feature completion — more code written, fewer features completed. Biting off more than you can chew, proven by data.
+Anthropic's long-running-agent guidance [asks the coding agent to work on one feature at a time](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), then verify, commit, and update progress before moving on. A broad prompt invites the agent to start several threads, and each thread competes for the same context and verification budget.
## WIP=1 Workflow
diff --git a/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
index f03a8f9..d7a47d3 100644
--- a/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
+++ b/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -25,7 +25,7 @@ Did user auth, shopping cart mostly done, still need payments
Can a new agent session answer these questions from this note? What does "mostly done" mean? Which tests did the cart pass? What's blocking payments? The answer to all is "nobody knows."
-The result: the new session spends 20 minutes inferring project state, and may end up re-implementing completed features. Anthropic's engineering data shows that good progress records reduce session startup diagnostic time by 60-80%.
+The result: the new session has to infer project state, and may end up re-implementing completed features. Anthropic's advice is to [record progress and verification results in versioned files](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) so the next session can inspect state.
## Feature State Machine
@@ -116,7 +116,7 @@ An e-commerce platform with 10 features. Two tracking approaches compared:
**Structured mode**: Every feature has a clear state and verification command. A new session reads the feature list and in 3 minutes knows: F01-F05 are `passing`, F06 is `active` (in progress), F07-F10 are `not_started`. It picks up directly from F06, with zero rework.
-Quantified result: projects using structured feature lists show 45% higher feature completion rate than free-form tracking, with zero duplicate implementations.
+A structured list puts each feature's state and verification command in one place, so the new session knows what is done.
## Key Takeaways
diff --git a/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
index 85b782c..2f94a52 100644
--- a/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
+++ b/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -68,7 +68,7 @@ An independent evaluation agent, specifically tuned to be "nitpicky," is far mor
| Architecture | Runtime | Cost | Core Features Working? |
|--------------|---------|------|------------------------|
| Single agent (bare run) | 20 mins | $9 | No (game entities unresponsive to input) |
-| Three agents (planner + generator + evaluator) | 6 hours | $200 | Yes (game is fully playable) |
+| Three agents (planner + generator + evaluator) | 6 hours | $200 | Core gameplay worked; physics and level issues remained |
This is the exact same model (Opus 4.5) with the exact same prompt ("build a 2D retro game editor"). The only difference is the harness: from "running bare" to "planner expands requirements → generator implements feature by feature → evaluator performs actual click testing using Playwright."
@@ -117,7 +117,7 @@ Effective runtime signals include:
**Actual omissions**: (1) End-to-end flow untested—the actual sending and verification of the reset link was never confirmed. (2) Database migration failed after partial execution, leaving the schema inconsistent. (3) Email service configuration was missing in the target environment.
-**Harness intervention**: Termination validation is enforced—(1) start the full application to verify the reset endpoint is accessible; (2) execute the complete reset flow; (3) verify database state consistency. All defects were discovered within the session, saving 5-10x the cost of post-hoc fixes.
+**Harness intervention**: Termination validation is enforced—(1) start the full application to verify the reset endpoint is accessible; (2) execute the complete reset flow; (3) verify database state consistency. All three defects surface inside the session, while the fix cost is still local.
## Key Takeaways
diff --git a/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
index 65f28b8..b58b899 100644
--- a/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
+++ b/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -130,7 +130,7 @@ Every time you discover a new category of agent error during code review, turn i
| Permission Issue | Different permissions in packaged environment | Missed | Caught |
| Error Propagation | Service layer exceptions didn't reach UI layer | Missed | Caught |
-All 5 defects were caught by end-to-end tests; unit tests caught none. The trade-off was test time increasing from 2 seconds to 15 seconds — perfectly acceptable in an agent workflow.
+All 5 defects were caught by end-to-end tests; unit tests caught none. The end-to-end run is slower, but that cost is small compared with shipping five boundary defects.
## Key Takeaways
diff --git a/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
index bca8172..1ec3acf 100644
--- a/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
+++ b/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -21,7 +21,7 @@ When a harness lacks observability, four categories of problems appear systemati
**Retries become blind guesses.** When the agent doesn't know why something failed, its retry direction is random. It might hammer away in the wrong direction — fixing unrelated code paths while ignoring the real root cause. Every blind retry burns tokens and time.
-**Session handoff information cliff.** When incomplete work is handed to the next session, missing observability means the new session has to diagnose the system state from scratch. Anthropic's observations of long-running agents show that this redundant diagnosis can eat up 30-50% of total session time.
+**Session handoff information cliff.** When incomplete work is handed to the next session, missing observability means the new session has to diagnose the system state from scratch. The new session has to reread code, rerun commands, and decide which signals matter; [versioned progress and verification records](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) provide inspectable state.
## A Real Claude Code Scenario
@@ -31,7 +31,7 @@ Consider a harness using a "planner-generator-evaluator" three-role workflow, ex
**With full observability:** The planner outputs a sprint contract listing which components to modify, verification standards for each, and exclusions (e.g., no print styles). The generator implements according to the contract, and runtime observability records each component's style loading and application process. The evaluator uses a scoring rubric to evaluate dimension by dimension, citing specific evidence: "Button color contrast is insufficient (WCAG AA standard 4.5:1, measured 2.1:1)." One iteration produces a high-quality result, in about 15 minutes.
-3x efficiency difference. The only variable is observability.
+The difference comes from whether the contract and evidence exist outside the agent's head.
## Layered Observability
@@ -122,7 +122,7 @@ Create a trace for each harness session, a span for each task, and sub-spans for
## Anthropic's Three-Agent Architecture Experiment
-In March 2026, Anthropic published a systematic harness experiment. They ran the same task ("build a browser-based DAW using the Web Audio API") with three different architectures and recorded detailed phase-by-phase data:
+Anthropic's March 2026 report gives the [updated DAW run of the same three-agent architecture](https://www.anthropic.com/engineering/harness-design-long-running-apps) ("build a browser-based DAW using the Web Audio API"). The first version, built for Opus 4.5, used a generator working in sprints and an evaluator grading each sprint. The updated version, run on Opus 4.6, removed the sprint construct: the builder works continuously, and the evaluator reviews after each build round. The table below is the updated run:
| Agent & Phase | Duration | Cost |
|---------------|----------|------|
@@ -135,7 +135,7 @@ In March 2026, Anthropic published a systematic harness experiment. They ran the
| QA round 3 | 9.6 min | $4.06 |
| **Total** | **3 hr 50 min** | **$124.70** |
-Each of the three agents had a distinct role, and each played a clear part in observability:
+Each role plays a clear part in observability. The role descriptions below cover the first version; the updated version removes the generator's sprint layer:
**Planner:** Receives a 1-4 sentence user requirement and expands it into a full product spec. It was instructed to "be bold in scope" and "focus on product context and high-level technical design rather than detailed technical implementation." The reasoning: if the planner prematurely specifies granular technical details and gets them wrong, those errors cascade downstream. A better approach is to constrain deliverables and let the agent find its own path during execution.
@@ -155,7 +155,7 @@ The evaluator wasn't always this sharp. Early versions would identify reasonable
- **Both observability layers are essential.** Runtime signals explain "what happened," process artifacts explain "why it was done this way."
- **Sprint contracts front-load alignment.** They prevent the generator from building something the evaluator immediately rejects for foreseeable reasons.
- **Scoring rubrics make evaluation reproducible.** Different evaluators produce similar scores for the same output.
-- **Missing observability wastes 30-50% of session time on redundant diagnosis.**
+- **Observability turns a vague rejection into a specific, fixable defect.**
## Further Reading
diff --git a/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
index 6f2be17..194284e 100644
--- a/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
+++ b/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -15,7 +15,7 @@ Lehman's laws of software evolution tell us that systems undergoing continuous c
During five months of Codex experiments, OpenAI observed something striking: **agents copy patterns already present in the repository, even when those patterns are inconsistent or suboptimal.** Over time, this copying inevitably leads to drift. The first person leaves a coffee cup in the common area; the second person figures "it's already messy" and leaves another; a week later the table is buried under cups. A codebase works the same way.
-The OpenAI team initially spent 20% of every Friday manually cleaning up "AI slop," but this approach clearly doesn't scale. They eventually arrived at a systematic solution:
+The OpenAI team initially set aside Fridays — [one workday, about 20% of the week's capacity](https://openai.com/index/harness-engineering/) — for manually cleaning up "AI slop." As throughput grew, manual cleanup cost more than it returned. They eventually arrived at a systematic solution:
1. **Encode "golden rules" into the repository**: Rules like "prefer the shared utility package over hand-rolled ad-hoc helpers" (keep invariants centralized) and "don't YOLO-guess data structures" (validate boundaries or depend on typed SDKs). These rules are concrete, mechanical, and automatically checkable.
2. **Establish periodic cleanup workflows**: A fleet of background Codex tasks that regularly scan for deviations, update quality scores, and open targeted refactoring PRs. Most can be reviewed and auto-merged within a minute.
@@ -43,7 +43,7 @@ flowchart LR
Fix --> Build
```
-But that's still not enough. Current progress must be recorded in machine-readable artifacts: completed subtasks with their passing criteria, in-progress but incomplete subtasks with current state, and not-yet-started subtasks. Good progress records can reduce session startup diagnostic time by 60–80%. Temporary artifacts — debug logs, temporary files, commented-out code, TODO markers — must also be cleaned up, because they increase cognitive load for the next session. The standard startup path must remain functional too. Can the next session start working without manual intervention? Environment initialization, codebase loading, context acquisition, task selection — none of these paths can be broken.
+But that's still not enough. Current progress must be recorded in machine-readable artifacts: completed subtasks with their passing criteria, in-progress but incomplete subtasks with current state, and not-yet-started subtasks. Record progress and verification results in versioned files so the next session can inspect state. Temporary artifacts — debug logs, temporary files, commented-out code, TODO markers — must also be cleaned up, because they increase cognitive load for the next session. The standard startup path must remain functional too. Can the next session start working without manual intervention? Environment initialization, codebase loading, context acquisition, task selection — none of these paths can be broken.
```mermaid
flowchart LR
@@ -72,7 +72,7 @@ The most common mental trap is "no time to clean up this session, I'll do it nex
Worse, every session has its own task objectives. The new session is there to do new work, not clean up the previous session's mess. It'll ignore the chaos and start new work on top of it, introducing even more chaos. This is entropy's positive feedback loop.
-The numbers tell the story. A project developed with agents for 12 weeks, without a cleanup strategy:
+For a hypothetical 12-week project, suppose the following values:
- Week 1: Build pass rate 100%, test pass rate 100%, new session startup 5 min
- Week 4: Build 95%, tests 92%, startup 15 min
@@ -84,7 +84,7 @@ Same project with a cleanup strategy:
- Week 1: 100%, 100%, 5 min
- Week 12: 97%, 95%, 9 min
-After 12 weeks: build pass rate differs by 29 percentage points, new session startup time differs by 85%. This is not theoretical — it's an observed difference.
+A weekly cleanup loop keeps the starting state stable: each session ends with build, tests, progress, and temporary artifacts in order, so the next session starts from the same baseline.
## How to Do It
@@ -137,7 +137,7 @@ New sessions read this document and immediately know where to prioritize. Fix th
Every harness component exists because the model couldn't reliably do something on its own. But as models improve, these assumptions become outdated.
-Anthropic's experiments demonstrated this directly. Their initial harness included a sprint-splitting mechanism — breaking work into small chunks for Sonnet 4.5 to complete one at a time. When Opus 4.6 shipped, the model's native capabilities could handle work decomposition autonomously, making sprint construction unnecessary overhead. After removing it, the builder agent could work continuously for over two hours without drifting — and was actually smoother.
+Anthropic's harness report shows this directly. The first three-agent harness, built for Opus 4.5, had the generator work in sprints. When [Opus 4.6](https://www.anthropic.com/engineering/harness-design-long-running-apps) shipped, the model could handle work decomposition, so the sprint construct became unnecessary. In the updated DAW run, the builder worked continuously for over two hours without drifting.
But the evaluator told a different story. Even with Opus 4.6's stronger capabilities, when tasks approached the model's capability boundary, the evaluator still provided real value — catching the generator's missing functionality and stub implementations. This means the evaluator isn't a fixed yes/no decision; it depends on where task difficulty sits relative to model capability.
@@ -170,7 +170,7 @@ An Electron app developed with agents over 12 weeks, comparing two approaches:
**With cleanup strategy** (experimental group): Full clean-state check at every session end, plus a weekly cleanup loop. Week 12, build pass rate 97%, test pass rate 95%, new session startup 9 min, 11 stale artifacts.
-By week 12, the experimental group's build pass rate was 29 percentage points higher, test pass rate 34 points higher, and new session startup time 85% lower. Each session spent an extra 5 minutes on cleanup, but over 12 weeks that saved dozens of hours of chaos.
+By week 12, the cleanup group's build and test pass rates remained close to the starting point, a new session could start quickly, and stale artifacts were few. Cleanup took a few minutes per session and returned a starting state the next session could trust.
## Key Takeaways
diff --git a/docs/en/lectures/lecture-13-loop-engineering/index.md b/docs/en/lectures/lecture-13-loop-engineering/index.md
index 9b1b319..ac9ae6f 100644
--- a/docs/en/lectures/lecture-13-loop-engineering/index.md
+++ b/docs/en/lectures/lecture-13-loop-engineering/index.md
@@ -84,11 +84,11 @@ Loop Engineering, the subject of this lecture, isn't about any one command. It's
You don't have to type `/goal` every time. But understanding where it came from and why it looks the way it does — that's understanding the core of loop engineering. More complex loops just add parts like scheduling, parallelism, isolation, and memory on top of these same three fundamentals: goal, verification, stopping condition.
-## June 2026: Three People Lit the Same Fuse in One Week
+## Different Dates, the Same Direction
-In the first week of June 2026, three practitioners building coding agent infrastructure — without comparing notes — said the same thing in different words.
+The same idea surfaced in different places, at different times.
-**Peter Steinberger** (creator of OpenClaw, [his post reached 8 million views](https://x.com/steipete/status/2063697162748260627)): "You shouldn't be prompting coding agents anymore. You should be designing loops that prompt your agents."
+**Peter Steinberger** (creator of OpenClaw, [in a post](https://x.com/steipete/status/2063697162748260627)): "You shouldn't be prompting coding agents anymore. You should be designing loops that prompt your agents."
**Boris Cherny** (head of Claude Code at Anthropic, [on the Acquired podcast](https://x.com/rohanpaul_ai/status/2063289804708835412)): "I don't prompt Claude anymore. I have loops running that prompt Claude and figure out what to do. My job is to write loops."
@@ -96,9 +96,9 @@ In the first week of June 2026, three practitioners building coding agent infras
> **Loop engineering is replacing yourself as the person who prompts the agent. You design the system that does it instead.**
-Cherny disclosed numbers: over 30 consecutive days, all code contributions to Claude Code were made autonomously by AI — 259 merged PRs, over 80% of production code authored by Claude, and a 76% success rate on open-ended software tasks.
+Cherny wrote in a [2025-12-27 personal report](https://twitter.com/bcherny/status/2004887829252317325) that over 30 days he landed 259 PRs — 497 commits, 40,000 lines added, 38,000 removed — and that every line was written by Claude Code + Opus 4.5.
-Three people. One week. The same conclusion. Not because they coordinated — because the infrastructure had quietly crossed a threshold. Agents had become reliable enough to finish non-trivial tasks unattended. Scheduling primitives (`/loop`, `/goal`, cron) were now built into the tools. The cost of a single agent run had dropped low enough that running one repeatedly on a timer stopped looking wasteful. When all the parts are present, the move that combines them becomes obvious to everyone at once.
+The quotes come from different dates, formats, and teams. Their shared direction is to move scheduling, verification, and the stopping decision out of the moment-to-moment prompt and into a system. By mid-2026, agents could finish non-trivial tasks unattended, scheduling primitives were built in, and a run was cheap enough to repeat on a timer. When the pieces are present, more than one person puts them together.
> Source: [Addy Osmani: Loop Engineering](https://addyosmani.com/blog/loop-engineering/)
@@ -267,7 +267,7 @@ flowchart TD
This is no longer a single agent run. It is a continuously operating system that wakes up every morning, sweeps the floor on its own, and puts the things that need your attention in front of you. Your role becomes: **review the inbox contents, make decisions, and when you spot a pattern the system can't handle, refine the skills and rules.**
-Cherny used this pattern to merge 259 PRs in 30 days without opening an IDE once. OpenAI engineers used the same pattern to build a roughly one-million-line beta product by hand — without writing a single line of code themselves.
+Cherny's 30-day report is one data point for this pattern: 259 PRs, with the code written by Claude Code + Opus 4.5. OpenAI's [harness account](https://openai.com/index/harness-engineering/) is another: a small team used Codex on a greenfield repository for five months and reported about one million lines and roughly 1,500 PRs.
## Generator/Evaluator Separation: Why You Can't Let the Model Grade Its Own Work
@@ -293,7 +293,7 @@ One sentence to remember: **someone in your crew must not believe you.**
If you want to see what a well-designed, actually-running loop looks like, [Karpathy's autoresearch](https://github.com/karpathy/autoresearch) is the textbook example.
-In March 2026, Karpathy released a 630-line Python project. Give it one GPU and a research direction, and it runs all night — completing hundreds of ML training experiments, keeping only the ones that truly improve. The project hit 66,000+ stars within days of release.
+In March 2026, Karpathy released [autoresearch](https://github.com/karpathy/autoresearch). The repository is deliberately small: `prepare.py` is fixed infrastructure, `train.py` is the file the agent edits (about 630 lines), and `program.md` is the research methodology the human edits. Give it one GPU and a research direction, and it runs overnight — each experiment gets a fixed 5-minute training wall-clock budget (excluding startup and compilation), and only changes that improve `val_bpb` are kept.
### Three Files, Three Roles
@@ -343,9 +343,9 @@ flowchart TD
8b --> 9
```
-It runs roughly 12 experiments per hour. An overnight run (8 hours) is about 100 experiments. Karpathy himself ran it for 2 days — ~700 experiments.
+The README estimates about 12 experiments per hour, or roughly 100 in an 8-hour overnight run. The 5-minute budget covers training, not startup or compilation; the rest of each round goes to editing, launching, and evaluating. Karpathy reported running a private version of autoresearch autonomously for about two days for the nanochat round described below.
-The fixed 5-minute wall-clock budget is a key design choice — no matter what the agent changes, every experiment takes exactly the same time. This means all results are directly comparable under the same time budget — no argument about "this one ran longer so it's better."
+The fixed 5-minute training budget is a key design choice — no matter what the agent changes, the training run gets the same wall-clock budget. This means all results are directly comparable under the same training budget.
### Output: What You See When You Wake Up
@@ -375,13 +375,9 @@ The agent writes clear commit messages about what it tried, what worked, what di
### What It Actually Found
-Results from Karpathy's initial 2-day, ~700-experiment run:
+Results from autoresearch [round 1](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b) reduced nanochat's GPT-2-level training time on 8×H100 [from **2.02 hours to 1.80 hours**](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b), a reduction of about **10.9%** in training time.
-- Out of ~700 attempts, about **20 stackable real improvements** were found
-- Reduced nanochat's GPT-2-level training time on 8×H100 from **2.02 hours → 1.80 hours**, about **11% faster**
-- Findings included: learning rate adjustments, optimizer tuning, activation swaps, attention pattern optimizations, etc.
-
-Were all improvements earth-shattering discoveries? No. Most were small optimizations that stacked. But those 20 valid improvements would have taken a human researcher weeks of manual work — the agent did it in 48 hours.
+Most of the changes were small optimizations that stacked. The useful part is the loop: a fixed budget, a complete experiment log, and a rule that only verified improvements stay.
### The Most Telling Detail: The Loop Is Written in English, Not Code.
@@ -399,7 +395,7 @@ Fast loops tempt you to skip verification. "Looks fine" is not the same as "conf
### 2. Comprehension Rot
-The faster a loop ships code, the further your understanding of your own codebase drifts from reality. Cherny's team had 80% of code authored by agents — meaning most of a team's code wasn't written by a person. If you don't read and use what the loop produces, your comprehension decays continuously. **Fast loops require fast reading.**
+The faster a loop ships code, the further your understanding of your own codebase drifts from reality. A loop lands hundreds of PRs; the team reads those PRs, reviews the diffs that matter, and keeps using the code, so its mental model keeps up. **Fast loops require fast reading.**
### 3. Cognitive Surrender
@@ -407,11 +403,11 @@ When the loop runs smoothly, the most comfortable posture is to stop having opin
### 4. Token Blowout
-Every iteration of a loop accumulates more context: code written, errors encountered, decisions made. Without context management, prompt size grows roughly quadratically with the number of turns. Codex addresses this with automatic context compaction — a dedicated API compresses older conversation turns into encrypted content summaries, retaining essential knowledge while discarding redundant detail. This is an engineering concern you must address from the first loop, not a bolt-on later.
+Every iteration of a loop accumulates more context: code written, errors encountered, decisions made. When each round adds roughly a fixed amount of new content, the history length seen by a single round grows roughly linearly with the number of rounds. If the system reprocesses the entire history every round, the cumulative input across N rounds grows roughly quadratically. Codex addresses this with automatic context compaction — a dedicated API compresses older conversation turns into encrypted content summaries, retaining essential knowledge while discarding redundant detail. This is an engineering concern you must address from the first loop, not a bolt-on later.
## Building Your First Loop
-You don't need to start with a Stripe-scale pipeline merging 1,300 PRs a week. Start with the smallest thing that works.
+You don't need to start with a high-throughput pipeline. Start with the smallest thing that works.
### Step 1: Pick One Recurring Task
diff --git a/docs/en/lectures/lecture-14-graph-engineering/index.md b/docs/en/lectures/lecture-14-graph-engineering/index.md
index 78e4ffb..e1a1b6b 100644
--- a/docs/en/lectures/lecture-14-graph-engineering/index.md
+++ b/docs/en/lectures/lecture-14-graph-engineering/index.md
@@ -9,7 +9,7 @@ Six weeks after Loop Engineering hit the mainstream, on July 18, 2026, Peter Ste
> "Are we still talking loops or have we moved on to graphs yet?"
-One tweet — ~575K views within a day, rising to roughly 3M by the end of the month. A few hours later, ML engineer Hamel Husain published *Loop Engineering Is Dead. Enter Graph Engineering* — an article whose entire body was a single "Stop it" GIF — and pulled another ~680k views.
+One tweet. A few hours later, ML engineer Hamel Husain published *Loop Engineering Is Dead. Enter Graph Engineering* — an article whose entire body was a single "Stop it" GIF.
Here's the twist: **both of them were joking.** One was satirizing an industry that invents a new term every six weeks; the other was riffing on the gag. But the joke survived about one weekend — courses, roadmaps, and tool stacks flooded the timeline before the weekend was over, trailed by a pile of fabricated numbers: the "+18% accuracy, −85% cost" claim is fake (the two numbers do exist, but they come from a paper about chemical piping diagrams and compare against different baselines), and the "Microsoft, Stanford, and Anthropic all discovered graph engineering at once" claim is also false. The fact-checking finds exactly one genuine "precursor": Josh Simmons, whose *We Are Entering the Graph Engineering Phase* is dated July 4 — two full weeks before the joke. **The joke made the idea trendy. It did not create the idea.**
@@ -257,11 +257,11 @@ When you're done, hold this against the diagram above: your hand-written `graph.
## Open-Source Projects: After the Name, Before the Name
-First, draw the line: **"Graph Engineering" is a name that only exists after July 18, 2026.** Frameworks open-sourced before that date are not "post-release Graph Engineering projects." As of early August 2026, only one open-source project carrying the name holds up:
+First, draw the line: **"Graph Engineering" is a name that only exists after July 18, 2026.** Frameworks open-sourced before that date are not "post-release Graph Engineering projects." One project that explicitly uses the name is GraphARC:
**Post-release projects (the one actually called Graph Engineering)**
-- [GraphArc](https://github.com/CodeGraphContext/grapharc) (2026-08-02): calls itself "the first real-time implementation of Graph Engineering." It turns agent execution from traces buried in logs into an **interactive real-time orchestration graph** — every agent, dependency, and decision point drawn out, visualized for your approval before execution (you can even inspect it from your phone). The author's background is building graph tooling for 4,000+ developers; the direction is "observable, debuggable, engineerable." Very new, still early-stage.
+- [GraphARC](https://github.com/CodeGraphContext/GraphARC) (created July 2026): describes itself as "an end to end implementation of Graph Engineering as proposed by Andrew NG and Peter Steinberger." It is an early-stage Python project. The useful move is to read its orchestration model and decide whether the approach fits your workflow.
**Pre-release projects (they don't call it Graph Engineering — but they're what you actually build with)**
@@ -325,7 +325,7 @@ Not every task deserves a graph. Five criteria — try at least three before you
- [goddaehee: Graph Engineering Fact-Check (KR, 2026-07-30)](https://goddaehee.tistory.com/628) — the most complete fact-check: the joke-origin timeline, the fake numbers taken apart, LangGraph data, Hacker News heat comparison
- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — the serious piece written two weeks before the joke
- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — the official reply: "not a new idea, the latest name for a well established approach"; LangGraph's 65M+ monthly downloads
-- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — hype-spread data (575K views on the original tweet)
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — a narrative account of how the term spread
- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — a head-to-head of seven mainstream open-source frameworks: LangGraph, CrewAI, Microsoft Agent Framework, LlamaIndex, Google ADK, OpenAI Agents SDK, Mastra
- [LangGraph official docs](https://docs.langchain.com/oss/python/langgraph/graph-api) — "Nodes do the work, edges tell what to do next"; the precise definitions of nodes and edges, the first-hand reference for building graphs
- [Anthropic: Building Effective Agents (Dec 2024)](https://www.anthropic.com/engineering/building-effective-agents) — five patterns that are graphs when drawn; the authoritative workflow-vs-agent distinction
diff --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.md
index cff51b6..284054c 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
@@ -9,13 +9,13 @@ Te consideras una persona con experiencia en el mundo de la IA: suscripción a C
Tu primer instinto puede ser: "este modelo no es suficientemente bueno, toca actualizar". Espera. Antes de sacar la tarjeta, considera que quizá el problema no sea el modelo.
-Veamos algunos números. A finales de 2025, los agentes de programación más fuertes en SWE-bench Verified logran aproximadamente 50-60%. Y eso en tareas cuidadosamente seleccionadas, con descripciones claras y tests existentes. Si lo llevas a tu entorno diario de desarrollo — requisitos vagos, sin tests existentes, reglas de negocio implícitas por todas partes — ese número solo baja.
+Veamos algunos números. El 29 de septiembre de 2025, Anthropic reportó Claude Sonnet 4.5 con un [77,2% en SWE-bench Verified](https://www.anthropic.com/news/claude-sonnet-4-5). Y eso en tareas cuidadosamente seleccionadas, con descripciones claras y tests existentes. Si lo llevas a tu entorno diario de desarrollo — requisitos vagos, sin tests existentes, reglas de negocio implícitas por todas partes — ese número solo baja.
Pero detrás de estos números hay una verdad contraintuitiva.
## El mismo caballo, destinos distintos
-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.
+Anthropic comparó el mismo prompt ("construye un creador de juegos retro 2D") y el mismo modelo (Opus 4.5) con dos harness. Primera ejecución: sin apoyo, sin harness — 20 minutos, 9 dólares; la aplicación abría, pero las entidades no respondían a la entrada. Segunda ejecución: harness completo, con arquitectura de tres agentes planner + generator + evaluator — 6 horas, 200 dólares; se podía mover una entidad, pero la física tenía asperezas y una pared bloqueaba el avance. [El núcleo de la jugabilidad funcionaba; la aplicación no estaba terminada.](https://www.anthropic.com/engineering/harness-design-long-running-apps)
No cambiaron el modelo. Opus 4.5 seguía siendo Opus 4.5. Lo que cambió fue el equipo de monta.
@@ -39,9 +39,9 @@ Las tareas largas que cruzan sesiones son aún peores: los descubrimientos de la
Con 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.
+- **Brecha de capacidad**: la distancia enorme entre el rendimiento del modelo en benchmarks y su rendimiento en tareas reales. Las tareas de benchmark traen descripción del issue, tests y entorno; las tareas reales a menudo exigen que los aportes tú.
- **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ó.
+- **Fallo inducido por harness**: el modelo tiene capacidad suficiente, pero el entorno de ejecución tiene defectos estructurales. La comparación del juego retro de arriba es un ejemplo.
- **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.
- **Definition of Done**: conjunto de condiciones verificables por máquina: tests pasan, lint limpio, type checks pasan. Sin una definición explícita, el agente inventará la suya.
@@ -72,7 +72,7 @@ Completion criteria:
## El experimento del millón de líneas
-OpenAI realizó en 2025 un experimento agresivo: usar Codex para construir un producto interno completo desde un repositorio git vacío. Cinco meses después, el repositorio tenía alrededor de un millón de líneas de código: lógica de aplicación, infraestructura, tooling, documentación y herramientas internas de desarrollo, todo generado por agentes. Tres ingenieros dirigieron Codex, abriendo y fusionando unas 1.500 PRs, con una media de 3,5 PRs por persona al día.
+En agosto de 2025, tres ingenieros de OpenAI comenzaron un experimento agresivo: usar Codex para construir un producto interno completo desde un repositorio git vacío. Cinco meses después, [el repositorio tenía alrededor de un millón de líneas de código](https://openai.com/index/harness-engineering/): lógica de aplicación, infraestructura, tooling, documentación y herramientas internas de desarrollo, todo generado por agentes. El equipo después creció a siete ingenieros; en total se fusionaron unas 1.500 PRs, con una media de 3,5 PRs por ingeniero al día.
La restricción clave: **los humanos nunca escriben código directamente.** No era un truco; estaba diseñado para obligar al equipo a descubrir qué cambia cuando el trabajo principal del ingeniero deja de ser escribir código y pasa a ser diseñar entornos, expresar intención y construir bucles de feedback.
@@ -86,9 +86,9 @@ Este experimento demuestra directamente la tesis central de la lección: **el mi
Un equipo usó Claude Sonnet para añadir un nuevo endpoint a una aplicación web Python mediana (FastAPI + PostgreSQL + Redis, unas 15.000 líneas).
-Al principio dieron solo una frase: "añade endpoints de preferencias de usuario bajo `/api/v2/users`". ¿El resultado? El agente gastó 40% de su ventana de contexto explorando la estructura del repo, produjo código que parecía razonable pero no seguía los patrones de manejo de errores del proyecto, usó sintaxis antigua de SQLAlchemy y declaró finalización aunque el endpoint tenía errores en runtime. La siguiente sesión tuvo que repetir todo el descubrimiento.
+Al principio dieron solo una frase: "añade endpoints de preferencias de usuario bajo `/api/v2/users`". ¿El resultado? El agente pasó buena parte de la sesión explorando la estructura del repo, produjo código que parecía razonable pero no seguía los patrones de manejo de errores del proyecto, usó sintaxis antigua de SQLAlchemy y declaró finalización aunque el endpoint tenía errores en runtime. La siguiente sesión tuvo que repetir todo el descubrimiento.
-Más tarde añadieron `AGENTS.md`, con arquitectura del proyecto y versiones del stack, comandos de verificación explícitos (`pytest tests/api/v2/ && python -m mypy src/`) y registros de decisiones arquitectónicas. El mismo modelo tuvo éxito en tres ejecuciones independientes, con alrededor de 60% más eficiencia de contexto.
+Más tarde añadieron `AGENTS.md`, con arquitectura del proyecto y versiones del stack, comandos de verificación explícitos (`pytest tests/api/v2/ && python -m mypy src/`) y registros de decisiones arquitectónicas. El mismo modelo entonces siguió las convenciones del proyecto y comprobó su trabajo con comandos que podía ejecutar.
No cambiaron el modelo. Cambiaron el harness.
diff --git a/docs/es/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/es/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
index 802398c..4c08e0b 100644
--- a/docs/es/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
+++ b/docs/es/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -52,7 +52,7 @@ flowchart LR
- **Las ventanas de contexto son finitas**: No importa qué tamaño de ventana se reclame (128K, 200K, 1M), las tareas largas eventualmente las agotarán. Tras el agotamiento, se requiere compaction (perdiendo información) o reset (nueva sesión). Ambas pierden algo.
- **Artefactos de continuidad**: Archivos de estado persistido que permiten a una nueva sesión retomar sin ambigüedad donde la anterior lo dejó. La forma básica: registro de progreso + registro de verificación + próximas acciones. Ese diario del artesano.
-- **Costo de reconstrucción**: El tiempo que una nueva sesión necesita para alcanzar un estado ejecutable. Los buenos harness pueden comprimir el costo de reconstrucción de 15 minutos a 3 minutos.
+- **Costo de reconstrucción**: El tiempo que una nueva sesión necesita para alcanzar un estado ejecutable. Un buen harness deja el progreso, los resultados de verificación y las próximas acciones en archivos, de modo que la nueva sesión parte de un estado escrito.
- **Deriva (Drift)**: La brecha entre la comprensión del agente y el estado real del repositorio de código. Cada límite de sesión introduce deriva; sin control, se acumula.
- **Ansiedad de contexto**: Un fenómeno observado por Anthropic — los agentes exhiben un comportamiento de convergencia prematura cuando se acercan a los límites de contexto percibidos, terminando tareas temprano para evitar pérdida de información. Es una ansiedad irracional por los recursos.
- **Compaction vs reset**: La compaction resume el contexto dentro de la misma sesión (conserva el "qué," puede perder el "por qué"); el reset abre una nueva sesión reconstruyendo desde artefactos persistidos (limpio pero depende de la completitud de los artefactos).
@@ -160,7 +160,7 @@ LangChain informa de una mejora de 52,8% a 66,5%, 13,7 puntos porcentuales, usan
- Las ventanas de contexto son un recurso finito. Las tareas largas abarcarán sesiones, y las sesiones perderán información — como el artesano que olvida cada día, esto es una realidad objetiva.
- La solución no son ventanas más grandes — es mejor persistencia del estado. Archivos de progreso + registros de decisiones + puntos de control de git — dale al artesano amnésico un diario confiable.
- Trata al agente como un ingeniero con amnesia: antes de "terminar el turno," escribe qué se hizo, por qué y qué sigue.
-- El costo de reconstrucción es la métrica clave. Los buenos harness deberían llevar a las nuevas sesiones a un estado ejecutable en menos de 3 minutos.
+- El costo de reconstrucción es la métrica clave. Un buen harness deja el progreso, los resultados de verificación y las próximas acciones en archivos, de modo que una nueva sesión se recupera rápido.
- Estrategia mixta: tareas cortas dentro de las sesiones, tareas largas con artefactos estructurados para la continuidad.
## Lecturas adicionales
diff --git a/docs/es/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/es/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
index 276941d..b959327 100644
--- a/docs/es/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
+++ b/docs/es/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -37,7 +37,7 @@ flowchart TB
## Qué sucede cuando los mezclas
-El problema más directo: los cimientos no se asientan correctamente. El agente gasta el 80% de su esfuerzo en código de funcionalidades y el 20% configurando casualmente algo de infraestructura. El framework de pruebas está configurado pero nunca verificado, las reglas de lint están establecidas pero demasiado laxas, no se creó ningún archivo de progreso. Estos defectos no son obvios en la primera sesión (porque el agente todavía recuerda lo que hizo), pero salen a la luz en la segunda sesión — el nuevo agente no sabe cómo ejecutar, probar o en qué punto están las cosas. Cimientos chapuceros, edificio inestable.
+El problema más directo: los cimientos no se asientan correctamente. El agente gasta la mayor parte de su esfuerzo en código de funcionalidades y trata la infraestructura como algo secundario. El framework de pruebas está configurado pero nunca verificado, las reglas de lint están establecidas pero demasiado laxas, no se creó ningún archivo de progreso. Estos defectos no son obvios en la primera sesión (porque el agente todavía recuerda lo que hizo), pero salen a la luz en la segunda sesión — el nuevo agente no sabe cómo ejecutar, probar o en qué punto están las cosas. Cimientos chapuceros, edificio inestable.
Un costo más oculto es la "acumulación no verificada" — el código de funcionalidades escrito antes de que el framework de pruebas esté configurado es código sin verificación. Cuando finalmente vuelves para añadir pruebas a ese código, podrías descubrir que el diseño estaba mal desde el principio — si lo hubieras sabido, lo habrías implementado de manera diferente. Como colocar baldosas sobre hormigón húmedo — cuando descubres que el suelo no está nivelado, todas las baldosas tienen que ser levantadas y rehechas.
@@ -45,7 +45,7 @@ El presupuesto de sesión también se está desperdiciando. El trabajo de inicia
El problema más fácilmente pasado por alto son las minas de suposiciones implícitas. Las decisiones que el agente toma durante la inicialización (qué framework de pruebas, cómo organizar directorios, gestión de dependencias) — si no se registran explícitamente, las sesiones posteriores no pueden entender estas decisiones. Peor aún, las sesiones posteriores podrían tomar decisiones contradictorias. El primer equipo de construcción usó cimientos de hormigón, el segundo equipo no lo sabe y clavó pilotes de madera en ellos — los cimientos se agrietan.
-La investigación de Anthropic sobre desarrollo de aplicaciones de larga duración recomienda explícitamente separar la inicialización de la implementación. Sus datos experimentales: los proyectos que usan una fase de inicialización dedicada mostraron un 31% más de tasa de completitud de funcionalidades en escenarios de múltiples sesiones comparado con enfoques mixtos. La perspectiva clave — el tiempo invertido en la fase de inicialización se recupera completamente en las siguientes 3-4 sesiones. Cuanto más sólidos los cimientos, más rápido se levantan las paredes.
+La investigación de Anthropic sobre agentes de larga duración [convierte la inicialización en una primera sesión aparte](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents). El inicializador escribe un script `init.sh`, un archivo de progreso, una lista de funcionalidades y un commit inicial de git; las sesiones de codificación posteriores leen ese estado, trabajan en una funcionalidad a la vez, la prueban de extremo a extremo, hacen commit y actualizan el archivo de progreso. Cuanto más sólidos los cimientos, más rápido se levantan las paredes.
La guía de ingeniería de harness de Codex de OpenAI también enfatiza el principio del "repositorio como registro operativo" — establece una estructura operativa clara desde la primera ejecución, o cada nueva sesión tendrá que re-inferir las convenciones del proyecto.
diff --git a/docs/es/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/es/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
index b8139ea..4960c03 100644
--- a/docs/es/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
+++ b/docs/es/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -26,7 +26,7 @@ El comportamiento real de Claude Code es revelador. Pídele que "añada registro
Seis pasos después, cada uno está a medio hacer. Sin verificación end-to-end, acoplamiento complejo entre el código a medio cocinar, y la siguiente sesión que tenga que recoger los pedazos estará completamente perdida. Como alguien cocinando seis platos simultáneamente — cada plato está en la sartén pero ninguno ha sido emplatado. Todos se queman.
-Los datos experimentales de Anthropic apoyan esto directamente: los agentes que usan una estrategia de "pequeño siguiente paso" (equivalente a WIP=1) muestran un 37% más de tasa de completitud de tareas que los agentes que usan prompts amplios. Más interesante aún, el número de líneas de código generadas por los agentes está débilmente correlacionado negativamente con la completitud real de funcionalidades — más código escrito, menos funcionalidades completadas. Morder más de lo que puedes masticar, comprobado con datos.
+La guía de Anthropic para agentes de larga duración [pide al agente de codificación trabajar en una funcionalidad a la vez](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), y luego verificar, hacer commit y actualizar el progreso antes de pasar a la siguiente. Un prompt amplio invita al agente a abrir varios frentes, y cada frente compite por el mismo contexto y el mismo presupuesto de verificación.
## Flujo de trabajo WIP=1
diff --git a/docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
index 8a6677b..70beb97 100644
--- a/docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
+++ b/docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -23,7 +23,7 @@ Did user auth, shopping cart mostly done, still need payments
¿Puede una nueva sesión de agente responder preguntas a partir de esta nota? ¿Qué significa "mostly done"? ¿Qué tests pasó el carrito? ¿Qué bloquea los pagos? La respuesta a todo es "nadie lo sabe". Es como decirle al médico "me duele el estómago, últimamente más o menos bien": ¿qué medicina puede recetar?
-Resultado: la nueva sesión gasta 20 minutos infiriendo el estado del proyecto y quizá reimplementa funciones ya terminadas. Los datos de ingeniería de Anthropic muestran que buenos registros de progreso reducen el tiempo de diagnóstico al iniciar sesión entre 60% y 80%.
+Resultado: la nueva sesión tiene que inferir el estado del proyecto y quizá reimplementa funciones ya terminadas. La recomendación de Anthropic es [registrar el progreso y los resultados de verificación en archivos versionados](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) para que la siguiente sesión pueda inspeccionar el estado.
## Máquina de estados de funciones
@@ -112,7 +112,7 @@ Una plataforma e-commerce con 10 funciones. Se compararon dos enfoques de seguim
**Modo columna vertebral**: Cada función tiene estado claro y comando de verificación. La nueva sesión lee la lista y en 3 minutos sabe: F01-F05 están `passing`, F06 está `active`, F07-F10 están `not_started`. Continúa directamente desde F06, sin retrabajo.
-Resultado cuantificado: los proyectos que usan listas de funciones estructuradas muestran una tasa de finalización de funciones 45% mayor que el seguimiento libre, con cero implementaciones duplicadas.
+Una lista estructurada pone el estado de cada funcionalidad y su comando de verificación en un solo lugar, de modo que la nueva sesión sabe qué está hecho.
## Ideas clave
diff --git a/docs/es/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/es/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
index 3471a2e..d8df7bf 100644
--- a/docs/es/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
+++ b/docs/es/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -70,7 +70,7 @@ Un agent evaluador independiente, ajustado específicamente para ser "exigente",
| Architecture | Runtime | Cost | Core Features Working? |
|--------------|---------|------|------------------------|
| Single Agent (bare run) | 20 mins | $9 | No (game entities unresponsive to input) |
-| Three Agents (planner + generator + evaluator) | 6 hours | $200 | Yes (game is fully playable) |
+| Three Agents (planner + generator + evaluator) | 6 hours | $200 | Core gameplay worked; physics and level issues remained |
Este es exactamente el mismo modelo (Opus 4.5) con exactamente el mismo prompt ("build a 2D retro game editor"). La única diferencia es el harness—desde "ejecución sin arnés" hasta "el planner expande los requisitos → el generador implementa funcionalidad por funcionalidad → el evaluador realiza pruebas reales de clics usando Playwright".
@@ -119,7 +119,7 @@ Las señales efectivas en tiempo de ejecución incluyen:
**Deducciones reales**: (1) Flujo end-to-end sin probar—el envío y verificación real del enlace de restablecimiento nunca se confirmó. (2) La migración de base de datos falló después de una ejecución parcial, causando inconsistencia en el esquema. (3) Faltaba la configuración del servicio de correo electrónico en el entorno destino.
-**Intervención del harness**: Validación de terminación impuesta—(1) Iniciar la aplicación completa para verificar la accesibilidad del endpoint de restablecimiento; (2) Ejecutar el flujo completo de restablecimiento; (3) Verificar la consistencia del estado de la base de datos. Todos los defectos se encontraron dentro de la sesión, ahorrando 5-10x el costo de correcciones posteriores. El calificador independiente encontró los problemas reales.
+**Intervención del harness**: Validación de terminación impuesta—(1) Iniciar la aplicación completa para verificar la accesibilidad del endpoint de restablecimiento; (2) Ejecutar el flujo completo de restablecimiento; (3) Verificar la consistencia del estado de la base de datos. Los tres defectos aparecen dentro de la sesión, cuando el costo de arreglo todavía es local. El calificador independiente encontró los problemas reales.
## Ideas clave
diff --git a/docs/es/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/es/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
index 32bdc83..90f41f2 100644
--- a/docs/es/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
+++ b/docs/es/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -132,7 +132,7 @@ Cada vez que se encuentre un nuevo tipo de error del agent durante una revisión
| Permission Issue | Different permissions in packaged environment | Missed | Caught |
| Error Propagation | Service layer exceptions didn't reach UI layer | Missed | Caught |
-Los 5 defectos fueron detectados por las pruebas end-to-end, mientras que las pruebas unitarias no detectaron ninguno. El costo fue un aumento en el tiempo de prueba de 2 segundos a 15 segundos—completamente aceptable en un flujo de trabajo de agent. Por muy bien que cada parte cante individualmente, no puede superar un ensayo completo del conjunto.
+Los 5 defectos fueron detectados por las pruebas end-to-end, mientras que las pruebas unitarias no detectaron ninguno. La ejecución end-to-end es más lenta, pero ese costo es pequeño comparado con entregar cinco defectos de frontera. Por muy bien que cada parte cante individualmente, no puede superar un ensayo completo del conjunto.
## Ideas clave
diff --git a/docs/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
index 09160e2..117e328 100644
--- a/docs/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
+++ b/docs/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -44,7 +44,7 @@ Cuando un harness no tiene observabilidad, aparecen sistemáticamente cuatro tip
**Los reintentos se vuelven conjeturas ciegas**: cuando el agente no sabe por qué falló algo, la dirección del reintento es aleatoria. Puede corregir rutas de código irrelevantes mientras ignora la causa raíz. Cada reintento ciego cuesta tokens y tiempo.
-**Acantilado de información en el handoff**: cuando se entrega trabajo incompleto a la siguiente sesión, la falta de observabilidad obliga a diagnosticar el estado del sistema desde cero. Las observaciones de Anthropic muestran que ese diagnóstico redundante puede consumir 30-50% del tiempo total de sesión.
+**Acantilado de información en el handoff**: cuando se entrega trabajo incompleto a la siguiente sesión, la falta de observabilidad obliga a diagnosticar el estado del sistema desde cero. La nueva sesión tiene que releer código, reejecutar comandos y decidir qué señales importan; [los registros versionados de progreso y verificación](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) ofrecen un estado inspeccionable.
### Un escenario realista con Claude Code
@@ -54,7 +54,7 @@ Imagina un harness con workflow de tres roles, planner-generator-evaluator, ejec
**Con observabilidad completa**: el planner produce un sprint contract que lista los componentes a modificar, los estándares de verificación y las exclusiones. El generator implementa según el contrato. La observabilidad de runtime registra cómo carga y aplica estilos cada componente. El evaluator usa una rúbrica con evidencias concretas por dimensión. Una iteración produce un resultado de alta calidad en unos 15 minutos.
-La diferencia de eficiencia es 3x. Lo único que cambió fue la observabilidad.
+La diferencia está en si el contrato y la evidencia existen fuera de la cabeza del agente.
### Por qué los agentes no pueden resolverlo solos
@@ -128,7 +128,7 @@ Un harness con workflow planner-generator-evaluator ejecuta "añadir soporte de
- La rúbrica da una evaluación estructurada por dimensiones
- Una iteración produce resultados de alta calidad en 15 minutos
-Mejora de eficiencia 3x, calidad más estable y evaluaciones reproducibles.
+Menos reintentos ciegos, calidad más estable y evaluaciones reproducibles.
## Ideas clave
@@ -136,7 +136,7 @@ Mejora de eficiencia 3x, calidad más estable y evaluaciones reproducibles.
- **Ambas capas de observabilidad son esenciales**: las señales de runtime explican "qué pasó"; los artefactos de proceso explican "por qué se hizo así".
- **Los sprint contracts alinean por adelantado**, evitando que el generator construya algo que el evaluator rechaza por razones previsibles.
- **Las rúbricas hacen reproducible la evaluación**, de modo que distintos evaluadores produzcan puntuaciones parecidas.
-- **La falta de observabilidad desperdicia 30-50% del tiempo de sesión en diagnóstico redundante.**
+- **La observabilidad convierte un rechazo vago en un defecto concreto y corregible.**
## Lecturas adicionales
diff --git a/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
index c9bf3cf..8d3922a 100644
--- a/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
+++ b/docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -52,7 +52,7 @@ flowchart LR
Las leyes de Lehman sobre la evolución del software nos dicen: los sistemas sometidos a cambios continuos aumentarán inevitablemente en complejidad a menos que se gestionen activamente. Esto es especialmente cierto para los agentes de codificación con IA—cada sesión introduce cambios, y sin limpieza al salir, la deuda técnica se acumula exponencialmente.
-Los datos reales son reveladores. Un proyecto desarrollado con agentes durante 12 semanas, sin estrategia de limpieza:
+Para un proyecto hipotético de 12 semanas, supongamos los siguientes valores, sin estrategia de limpieza:
- Semana 1: Tasa de build exitoso 100%, tasa de pruebas exitosas 100%, inicio de nueva sesión 5 min
- Semana 4: Build 95%, pruebas 92%, inicio 15 min
@@ -64,7 +64,7 @@ Mismo proyecto con una estrategia de limpieza:
- Semana 1: 100%, 100%, 5 min
- Semana 12: 97%, 95%, 9 min
-Después de 12 semanas: la tasa de build exitoso difiere en 29 puntos porcentuales, el tiempo de inicio de nueva sesión difiere en un 85%. Esto no es teórico—es una diferencia observada.
+Un bucle de limpieza semanal mantiene estable el estado de partida: cada sesión termina con build, pruebas, progreso y artefactos temporales en orden, de modo que la siguiente sesión parte de la misma base.
### Cinco dimensiones del clean state
@@ -74,7 +74,7 @@ El clean state no es solo "el código compila." Son cinco dimensiones evaluadas
**Dimensión de pruebas**: ¿Pasán todas las pruebas? Incluyendo las pruebas que existían antes de la sesión—la sesión es responsable de no romper la funcionalidad existente. Y debería verificarse en CI, no solo "funciona en mi máquina."
-**Dimensión de progreso**: ¿Está el progreso actual registrado en un artefacto legible por máquina? Subtareas completadas con sus criterios de aprobación, subtareas en progreso pero incompletas con su estado actual, subtareas aún no iniciadas. Los buenos registros de progreso reducen un 60-80% del tiempo de diagnóstico al inicio de la sesión.
+**Dimensión de progreso**: ¿Está el progreso actual registrado en un artefacto legible por máquina? Subtareas completadas con sus criterios de aprobación, subtareas en progreso pero incompletas con su estado actual, subtareas aún no iniciadas. Registrar el progreso y los resultados de verificación en archivos versionados permite que la siguiente sesión inspeccione el estado.
**Dimensión de artefactos**: ¿Hay artefactos temporales obsoletos o ambiguos? Logs de debug, archivos temporales, código comentado, marcadores TODO—todos estos aumentan la carga cognitiva para la siguiente sesión.
@@ -158,7 +158,7 @@ Una aplicación Electron desarrollada con agentes durante 12 semanas, comparando
**Con estrategia de limpieza** (grupo experimental): Verificación completa de clean state al final de cada sesión + bucle de limpieza semanal. Semana 12, tasa de build exitoso 97%, tasa de pruebas exitosas 95%, inicio de nueva sesión 9 min, artefactos obsoletos 11.
-En la semana 12, la tasa de build exitoso del grupo experimental es 29 puntos porcentuales más alta, la tasa de pruebas exitosas 34 puntos más alta, y el tiempo de inicio de nueva sesión un 85% menor.
+En la semana 12, las tasas de build y pruebas del grupo con limpieza se mantuvieron cerca del punto de partida, una nueva sesión podía empezar rápido y los artefactos obsoletos eran pocos. La limpieza tomaba unos minutos por sesión y devolvía un estado de partida en el que la siguiente sesión podía confiar.
## Ideas clave
diff --git a/docs/es/lectures/lecture-13-loop-engineering/index.md b/docs/es/lectures/lecture-13-loop-engineering/index.md
index dbe12f7..a94de1e 100644
--- a/docs/es/lectures/lecture-13-loop-engineering/index.md
+++ b/docs/es/lectures/lecture-13-loop-engineering/index.md
@@ -84,11 +84,11 @@ Loop Engineering, el tema de esta lección, no trata sobre ningún comando en pa
No tienes que escribir `/goal` cada vez. Pero entender de dónde vino y por qué se ve como se ve — eso es entender el núcleo del loop engineering. Los loops más complejos solo añaden partes como planificación, paralelismo, aislamiento y memoria sobre estos mismos tres fundamentos: objetivo, verificación, condición de parada.
-## Junio 2026: Tres Personas Encendieron la Mecha en Una Semana
+## Fechas Distintas, la Misma Dirección
-En la primera semana de junio de 2026, tres profesionales que construían infraestructura de agentes de codificación — sin comparar notas — dijeron lo mismo con palabras diferentes.
+La misma idea surgió en lugares y momentos distintos.
-**Peter Steinberger** (creador de OpenClaw, [su publicación alcanzó 8 millones de vistas](https://x.com/steipete/status/2063697162748260627)): "Ya no deberías estar haciendo prompting a agentes de codificación. Deberías estar diseñando loops que hacen prompting a tus agentes."
+**Peter Steinberger** (creador de OpenClaw, [en una publicación](https://x.com/steipete/status/2063697162748260627)): "Ya no deberías estar haciendo prompting a agentes de codificación. Deberías estar diseñando loops que hacen prompting a tus agentes."
**Boris Cherny** (jefe de Claude Code en Anthropic, [en el podcast Acquired](https://x.com/rohanpaul_ai/status/2063289804708835412)): "Ya no le hago prompting a Claude. Tengo loops ejecutándose que le hacen prompting a Claude y descubren qué hacer. Mi trabajo es escribir loops."
@@ -96,9 +96,9 @@ En la primera semana de junio de 2026, tres profesionales que construían infrae
> **Loop engineering es reemplazarte a ti mismo como la persona que hace prompting al agente. Diseñas el sistema que lo hace en su lugar.**
-Cherny reveló cifras: durante más de 30 días consecutivos, todas las contribuciones de código a Claude Code fueron realizadas autónomamente por IA — 259 PRs fusionados, más del 80% del código de producción autorado por Claude, y una tasa de éxito del 76% en tareas de software de final abierto.
+Cherny escribió en un [informe personal del 2025-12-27](https://twitter.com/bcherny/status/2004887829252317325) que en 30 días fusionó 259 PRs — 497 commits, 40.000 líneas añadidas y 38.000 eliminadas — y que cada línea la escribió Claude Code + Opus 4.5.
-Tres personas. Una semana. La misma conclusión. No porque se coordinaran — sino porque la infraestructura había cruzado silenciosamente un umbral. Los agentes se habían vuelto lo suficientemente confiables como para terminar tareas no triviales sin supervisión. Las primitivas de planificación (`/loop`, `/goal`, cron) ahora estaban integradas en las herramientas. El costo de una sola ejecución de agente había bajado lo suficiente como para que ejecutar uno repetidamente en un temporizador dejara de parecer un desperdicio. Cuando todas las piezas están presentes, el movimiento que las combina se vuelve obvio para todos al mismo tiempo.
+Las citas provienen de fechas, formatos y equipos distintos. Su dirección compartida es mover la planificación, la verificación y la decisión de parada fuera del prompt momento a momento y hacia un sistema. A mediados de 2026, los agentes podían terminar tareas no triviales sin supervisión, las primitivas de planificación estaban integradas y una ejecución era lo bastante barata como para repetirla con un temporizador. Cuando las piezas están presentes, más de una persona las junta.
> Fuente: [Addy Osmani: Loop Engineering](https://addyosmani.com/blog/loop-engineering/)
@@ -267,7 +267,7 @@ flowchart TD
Esto ya no es una sola ejecución de agente. Es un sistema que opera continuamente que se despierta cada mañana, barre el piso por sí solo, y pone las cosas que necesitan tu atención frente a ti. Tu rol se convierte en: **revisar el contenido de la bandeja, tomar decisiones, y cuando detectes un patrón que el sistema no puede manejar, refinar los skills y las reglas.**
-Cherny usó este patrón para fusionar 259 PRs en 30 días sin abrir un IDE ni una vez. Los ingenieros de OpenAI usaron el mismo patrón para construir un producto beta de aproximadamente un millón de líneas a mano — sin escribir una sola línea de código ellos mismos.
+El informe de 30 días de Cherny es un punto de datos para este patrón: 259 PRs, con el código escrito por Claude Code + Opus 4.5. El [informe de harness de OpenAI](https://openai.com/index/harness-engineering/) es otro: un equipo pequeño usó Codex en un repositorio desde cero durante cinco meses y reportó cerca de un millón de líneas y unas 1.500 PRs.
## Separación Generador/Evaluador: Por Qué No Puedes Dejar que el Modelo Califique Su Propio Trabajo
@@ -293,7 +293,7 @@ Una frase para recordar: **alguien en tu equipo no debe creerte.**
Si quieres ver cómo se ve un loop bien diseñado y realmente en ejecución, [el autoresearch de Karpathy](https://github.com/karpathy/autoresearch) es el ejemplo de libro de texto.
-En marzo de 2026, Karpathy lanzó un proyecto Python de 630 líneas. Dale una GPU y una dirección de investigación, y corre toda la noche — completando cientos de experimentos de entrenamiento de ML, quedándose solo con los que realmente mejoran. El proyecto alcanzó 66,000+ estrellas en pocos días después del lanzamiento.
+En marzo de 2026, Karpathy lanzó [autoresearch](https://github.com/karpathy/autoresearch). El repositorio es deliberadamente pequeño: `prepare.py` es infraestructura fija, `train.py` es el archivo que edita el agente (unas 630 líneas) y `program.md` es la metodología de investigación que edita la persona. Dale una GPU y una dirección de investigación, y corre toda la noche — cada experimento recibe un presupuesto fijo de 5 minutos de tiempo de reloj para el entrenamiento (sin contar arranque ni compilación), y solo se conservan los cambios que mejoran `val_bpb`.
### Tres Archivos, Tres Roles
@@ -343,9 +343,9 @@ flowchart TD
8b --> 9
```
-Ejecuta aproximadamente 12 experimentos por hora. Una ejecución nocturna (8 horas) son unos 100 experimentos. El propio Karpathy lo ejecutó durante 2 días — ~700 experimentos.
+El README estima unos 12 experimentos por hora, o aproximadamente 100 en una ejecución nocturna de 8 horas. El presupuesto de 5 minutos cubre el entrenamiento, no el arranque ni la compilación; el resto de cada ronda se va en editar, lanzar y evaluar. Karpathy reportó que ejecutó una versión privada de autoresearch de forma autónoma durante unos dos días para la ronda de nanochat que se describe abajo.
-El presupuesto fijo de 5 minutos de reloj es una elección de diseño clave — sin importar lo que cambie el agente, cada experimento toma exactamente el mismo tiempo. Esto significa que todos los resultados son directamente comparables bajo el mismo presupuesto de tiempo — sin discusiones sobre "este corrió más tiempo así que es mejor".
+El presupuesto fijo de 5 minutos de entrenamiento es una elección de diseño clave — sin importar lo que cambie el agente, la ejecución de entrenamiento recibe el mismo presupuesto de tiempo de reloj. Esto significa que todos los resultados son directamente comparables bajo el mismo presupuesto de entrenamiento.
### Salida: Lo Que Ves Cuando Te Despiertas
@@ -375,13 +375,9 @@ El agente escribe mensajes de commit claros sobre lo que probó, lo que funcion
### Lo Que Realmente Encontró
-Resultados de la ejecución inicial de 2 días y ~700 experimentos de Karpathy:
+Los resultados de la [ronda 1](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b) de autoresearch redujeron el tiempo de entrenamiento a nivel GPT-2 de nanochat en 8×H100 [de **2,02 horas a 1,80 horas**](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b), una reducción de aproximadamente **10,9%** del tiempo de entrenamiento.
-- De ~700 intentos, se encontraron aproximadamente **20 mejoras reales acumulables**
-- Redujo el tiempo de entrenamiento a nivel GPT-2 de nanochat en 8×H100 de **2.02 horas → 1.80 horas**, aproximadamente **11% más rápido**
-- Los hallazgos incluyeron: ajustes de tasa de aprendizaje, afinación de optimizador, cambios de activación, optimizaciones de patrón de atención, etc.
-
-¿Fueron todas las mejoras descubrimientos trascendentales? No. La mayoría fueron pequeñas optimizaciones que se acumularon. Pero esas 20 mejoras válidas le habrían tomado a un investigador humano semanas de trabajo manual — el agente lo hizo en 48 horas.
+La mayoría de los cambios fueron pequeñas optimizaciones que se acumularon. Lo útil es el loop en sí: un presupuesto fijo, un registro completo de experimentos y una regla de que solo se quedan las mejoras verificadas.
### El Detalle Más Revelador: El Loop Está Escrito en Inglés, No en Código.
@@ -399,7 +395,7 @@ Los loops rápidos te tientan a saltarte la verificación. "Se ve bien" no es lo
### 2. Deterioro de la Comprensión
-Cuanto más rápido envía código un loop, más se aleja tu comprensión de tu propia base de código de la realidad. El equipo de Cherny tenía el 80% del código autorado por agentes — lo que significa que la mayor parte del código de un equipo no fue escrito por una persona. Si no lees y usas lo que produce el loop, tu comprensión decae continuamente. **Los loops rápidos requieren lectura rápida.**
+Cuanto más rápido envía código un loop, más se aleja tu comprensión de tu propia base de código de la realidad. Un loop aterriza cientos de PRs; el equipo los lee, revisa los diffs que importan y sigue usando el código, de modo que su modelo mental se mantiene al día. **Los loops rápidos requieren lectura rápida.**
### 3. Rendición Cognitiva
@@ -407,11 +403,11 @@ Cuando el loop corre sin problemas, la postura más cómoda es dejar de tener op
### 4. Explosión de Tokens
-Cada iteración de un loop acumula más contexto: código escrito, errores encontrados, decisiones tomadas. Sin gestión del contexto, el tamaño del prompt crece aproximadamente cuadráticamente con el número de turnos. Codex aborda esto con la compactación automática de contexto — una API dedicada comprime los turnos de conversación antiguos en resúmenes de contenido cifrados, reteniendo el conocimiento esencial mientras descarta el detalle redundante. Esto es una preocupación de ingeniería que debes abordar desde el primer loop, no un añadido posterior.
+Cada iteración de un loop acumula más contexto: código escrito, errores encontrados, decisiones tomadas. Cuando cada ronda añade una cantidad aproximadamente fija de contenido nuevo, la longitud del historial que ve una sola ronda crece aproximadamente de forma lineal con el número de rondas. Si el sistema reprocesa todo el historial en cada ronda, la entrada acumulada a lo largo de N rondas crece aproximadamente de forma cuadrática. Codex aborda esto con la compactación automática de contexto — una API dedicada comprime los turnos de conversación antiguos en resúmenes de contenido cifrados, reteniendo el conocimiento esencial mientras descarta el detalle redundante. Esto es una preocupación de ingeniería que debes abordar desde el primer loop, no un añadido posterior.
## Construyendo Tu Primer Loop
-No necesitas empezar con un pipeline a escala de Stripe fusionando 1,300 PRs a la semana. Empieza con lo más pequeño que funcione.
+No necesitas empezar con un pipeline de alto rendimiento. Empieza con lo más pequeño que funcione.
### Paso 1: Elige Una Tarea Recurrente
diff --git a/docs/es/lectures/lecture-14-graph-engineering/index.md b/docs/es/lectures/lecture-14-graph-engineering/index.md
index 7d4c0cc..2391f34 100644
--- a/docs/es/lectures/lecture-14-graph-engineering/index.md
+++ b/docs/es/lectures/lecture-14-graph-engineering/index.md
@@ -9,7 +9,7 @@ Seis semanas después de que la lección anterior terminara de contar Loop Engin
> "¿Todavía hablamos de loops, o ya hemos pasado a los graphs?"
-Un tweet — unas 575 mil visitas en un día, subiendo a unos 3 millones para fin de mes. Unas horas después, el ingeniero de ML Hamel Husain publicó *Loop Engineering Is Dead. Enter Graph Engineering* — un artículo cuyo cuerpo entero era un solo GIF de "Stop it" — y consiguió otras ~680 mil visitas.
+Un tweet. Unas horas después, el ingeniero de ML Hamel Husain publicó *Loop Engineering Is Dead. Enter Graph Engineering* — un artículo cuyo cuerpo entero era un solo GIF de "Stop it".
Lo más interesante: **los dos estaban bromeando.** Uno satirizaba a una industria que inventa un término nuevo cada seis semanas; el otro seguía el chiste. Pero el chiste sobrevivió alrededor de un fin de semana — cursos, hojas de ruta y stacks de herramientas inundaron el timeline antes de que terminara el fin de semana, seguidos de un montón de números inventados: la afirmación de "+18% de precisión, −85% de coste" es falsa (los dos números existen, pero provienen de un artículo sobre diagramas de tuberías químicas y comparan contra líneas base completamente diferentes), y la afirmación de que "Microsoft, Stanford y Anthropic descubrieron la ingeniería de grafos al mismo tiempo" también es falsa. La verificación de datos confirma un único "precursor" real: Josh Simmons, cuyo *We Are Entering the Graph Engineering Phase* está fechado el 4 de julio — dos semanas completas antes del chiste. **El chiste hizo que el concepto se volviera popular. No fue el chiste el que lo creó.**
@@ -257,11 +257,11 @@ Cuando termines, compara con el grafo de arriba: tu `graph.md` escrito a mano es
## Proyectos open source: los que vinieron después de la publicación y los que ya estaban antes
-Primero, delimitemos: **Graph Engineering es un nombre que solo existe después del 18 de julio de 2026.** Los frameworks de código abierto publicados antes de esa fecha no son "proyectos posteriores al lanzamiento de Graph Engineering". De los proyectos open source que realmente aparecieron con este nombre después del boom del concepto, hasta principios de agosto de 2026 solo hay uno que se sostiene:
+Primero, delimitemos: **Graph Engineering es un nombre que solo existe después del 18 de julio de 2026.** Los frameworks de código abierto publicados antes de esa fecha no son "proyectos posteriores al lanzamiento de Graph Engineering". Un proyecto que usa explícitamente el nombre es GraphARC:
**Solo existen después de la publicación del concepto**
-- [GraphArc](https://github.com/CodeGraphContext/grapharc) (2026-08-02): se autodenomina "la primera implementación en tiempo real de Graph Engineering". Convierte la ejecución del agente — antes un trace enterrado en los logs — en un **grafo de orquestación interactivo y en tiempo real**: cada agente, cada dependencia y cada punto de decisión se dibujan, la gráfica completa se visualiza antes de ejecutar, y tú das el visto bueno (incluso puedes mirarlo desde el móvil) antes de que se lance. El autor viene de hacer herramientas de grafos para más de 4000 desarrolladores, y la dirección es "observable, depurable, ingenieril". Es muy nuevo, y las funciones aún están en fase temprana.
+- [GraphARC](https://github.com/CodeGraphContext/GraphARC) (creado en julio de 2026): se describe como "una implementación de extremo a extremo de Graph Engineering, según lo propuesto por Andrew NG y Peter Steinberger". Es un proyecto Python en fase temprana. El movimiento útil es leer su modelo de orquestación y decidir si el enfoque encaja en tu flujo de trabajo.
**Existían antes de la publicación del concepto (no se llaman Graph Engineering, pero son justo los que usarás para construir)**
@@ -325,7 +325,7 @@ No todas las tareas merecen que las dibujes. Cinco criterios; si se cumplen al m
- [goddaehee: Verificación de datos de Graph Engineering (coreano, 2026-07-30)](https://goddaehee.tistory.com/628) — la verificación de datos más completa: la línea de tiempo del origen del chiste, el desmontaje de los números falsos, los datos de LangGraph, la comparación de popularidad en Hacker News
- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — el artículo serio que apareció dos semanas antes del chiste
- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — la respuesta oficial: "no es una idea nueva, es el nombre más reciente de un método existente"; LangGraph con 65 millones+ de descargas mensuales
-- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — datos de la difusión del término (el tweet original con 575 mil visitas)
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — un relato de cómo se difundió el término
- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — comparación horizontal de siete frameworks open source importantes: LangGraph, CrewAI, Microsoft Agent Framework, LlamaIndex, Google ADK, OpenAI Agents SDK, Mastra
- [Documentación oficial de LangGraph](https://docs.langchain.com/oss/python/langgraph/graph-api) — "Nodes do the work, edges tell what to do next"; las definiciones precisas de nodo y arista, la referencia de primera mano para construir grafos
- [Anthropic: Building Effective Agents (dic 2024)](https://www.anthropic.com/engineering/building-effective-agents) — cinco patrones que, dibujados, son grafos; la distinción autoritativa entre workflow y agente
diff --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.md
index b9f865c..05a5383 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
@@ -9,13 +9,13 @@ Vous pensez connaître le monde de l'IA : abonnement Claude Pro, clé API GPT-4o
Votre premier réflexe pourrait être : « ce modèle n'est pas assez bon, il faut passer au niveau supérieur ». Attendez. Avant de sortir la carte bancaire, envisagez que le problème ne soit peut-être pas le modèle.
-Regardons quelques chiffres. Fin 2025, les meilleurs agents de codage atteignent environ 50-60 % sur SWE-bench Verified. Et cela sur des tâches soigneusement choisies, avec descriptions claires et tests existants. Dans votre environnement quotidien — exigences floues, peu ou pas de tests, règles métier implicites partout — ce chiffre baisse encore.
+Regardons quelques chiffres. Le 29 septembre 2025, Anthropic a annoncé Claude Sonnet 4.5 à [77,2 % sur SWE-bench Verified](https://www.anthropic.com/news/claude-sonnet-4-5). Et cela sur des tâches soigneusement choisies, avec descriptions claires et tests existants. Dans votre environnement quotidien — exigences floues, peu ou pas de tests, règles métier implicites partout — ce chiffre baisse encore.
Derrière ces chiffres se cache pourtant une vérité contre-intuitive.
## Même cheval, destins différents
-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.
+Anthropic a comparé le même prompt (« construire un éditeur de jeux rétro 2D ») et le même modèle (Opus 4.5) sous deux harness. Premier essai : nu, sans support — 20 minutes, 9 dollars ; l'application s'ouvre, mais les entités ne réagissent pas aux entrées. Deuxième essai : harness complet (architecture planner + generator + evaluator) — 6 heures, 200 dollars ; on peut déplacer une entité, mais la physique est approximative et un mur bloque la progression. [Le cœur du gameplay fonctionne ; l'application reste inachevée.](https://www.anthropic.com/engineering/harness-design-long-running-apps)
Ils n'ont pas changé de modèle. Opus 4.5 restait Opus 4.5. Ce qui a changé, c'est le harnachement.
@@ -37,9 +37,9 @@ Les tâches longues sur plusieurs sessions sont encore pires : les découvertes
## Concepts clés
-- **Écart de capacité** : l'écart entre performance sur benchmark et performance réelle. 50-60 % sur SWE-bench Verified signifie que près de la moitié des vrais problèmes restent non résolus.
+- **Écart de capacité** : l'écart entre performance sur benchmark et performance réelle. Les tâches de benchmark fournissent une description claire, des tests et un environnement ; les tâches réelles demandent souvent de les fournir soi-même.
- **Harness** : tout ce qui est hors du modèle — instructions, outils, environnement, gestion d'état, feedback de vérification. Si ce ne sont pas des poids de modèle, c'est du harness.
-- **Échec induit par le harness** : le modèle a la capacité, mais l'environnement d'exécution a des défauts structurels.
+- **Échec induit par le harness** : le modèle a la capacité, mais l'environnement d'exécution a des défauts structurels. La comparaison du jeu rétro ci-dessus en est un exemple.
- **Écart de vérification** : différence entre la confiance de l'agent et la correction réelle. L'agent dit « terminé » alors que ce n'est pas terminé.
- **Boucle de diagnostic** : exécuter, observer l'échec, l'attribuer à une couche du harness, corriger cette couche, réexécuter.
- **Definition of Done** : ensemble de conditions vérifiables par machine — tests passent, lint propre, types valides. Sans définition explicite, l'agent invente la sienne.
@@ -68,7 +68,7 @@ Completion criteria:
## L'expérience du million de lignes
-OpenAI a mené en 2025 une expérience ambitieuse : utiliser Codex pour construire un produit interne complet depuis un dépôt git vide. Cinq mois plus tard, le dépôt comptait environ un million de lignes — logique applicative, infrastructure, tooling, documentation, outils internes — toutes générées par agents. Trois ingénieurs pilotaient Codex, ouvrant et fusionnant environ 1 500 PRs, soit 3,5 PRs par personne et par jour.
+OpenAI a mené en août 2025 une expérience ambitieuse : utiliser Codex pour construire un produit interne complet depuis un dépôt git vide. [Cinq mois plus tard, le dépôt comptait environ un million de lignes](https://openai.com/index/harness-engineering/) — logique applicative, infrastructure, tooling, documentation, outils internes — toutes générées par agents. Trois ingénieurs pilotaient Codex ; l'équipe est ensuite passée à sept personnes et a fusionné environ 1 500 PRs, soit 3,5 PRs par ingénieur et par jour.
Contrainte clé : **les humains n'écrivent jamais directement le code.** Ce n'était pas un gadget, mais un moyen de forcer l'équipe à comprendre ce qui change quand le travail principal de l'ingénieur n'est plus d'écrire du code, mais de concevoir des environnements, exprimer l'intention et construire des boucles de feedback.
@@ -82,9 +82,9 @@ Cette expérience prouve directement la thèse de cette leçon : **le même mod
Une équipe a utilisé Claude Sonnet pour ajouter un endpoint API à une application Python moyenne (FastAPI + PostgreSQL + Redis, environ 15 000 lignes).
-Au départ, elle donne une seule phrase : « ajoute les endpoints de préférences utilisateur sous `/api/v2/users` ». Résultat : l'agent consomme 40 % de son contexte à explorer le dépôt, produit un code plausible mais incompatible avec les patterns d'erreur du projet, utilise l'ancienne syntaxe SQLAlchemy et déclare terminé alors que l'endpoint échoue au runtime. La session suivante doit refaire toute la découverte.
+Au départ, elle donne une seule phrase : « ajoute les endpoints de préférences utilisateur sous `/api/v2/users` ». Résultat : l'agent passe une grande partie de la session à explorer le dépôt, produit un code plausible mais incompatible avec les patterns d'erreur du projet, utilise l'ancienne syntaxe SQLAlchemy et déclare terminé alors que l'endpoint échoue au runtime. La session suivante doit refaire toute la découverte.
-Plus tard, l'équipe ajoute `AGENTS.md`, des commandes de vérification explicites (`pytest tests/api/v2/ && python -m mypy src/`) et des décisions d'architecture. Le même modèle réussit trois exécutions indépendantes, avec environ 60 % d'efficacité de contexte en plus.
+Plus tard, l'équipe ajoute `AGENTS.md`, des commandes de vérification explicites (`pytest tests/api/v2/ && python -m mypy src/`) et des décisions d'architecture. Le même modèle suit alors les conventions du projet et vérifie son travail avec des commandes qu'il peut exécuter.
Ils n'ont pas changé le modèle. Ils ont changé le harness.
diff --git a/docs/fr/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/fr/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
index 03f6ee3..fdb245c 100644
--- a/docs/fr/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
+++ b/docs/fr/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -52,7 +52,7 @@ flowchart LR
- **Les fenêtres de contexte sont finies** : Quelle que soit la taille de fenêtre annoncée (128K, 200K, 1M), les tâches longues finiront par les épuiser. Après épuisement, soit la compaction (perte d'informations) soit la réinitialisation (nouvelle session) est nécessaire. Les deux perdent quelque chose.
- **Artefacts de continuité** : Fichiers d'état persistés qui permettent à une nouvelle session de reprendre sans ambiguïté là où la précédente s'est arrêtée. La forme de base : journal de progression + enregistrement de vérification + actions suivantes. Le journal de l'artisan.
-- **Coût de reconstruction** : Le temps nécessaire à une nouvelle session pour atteindre un état exécutable. Les bons harness peuvent comprimer le coût de reconstruction de 15 minutes à 3 minutes.
+- **Coût de reconstruction** : Le temps nécessaire à une nouvelle session pour atteindre un état exécutable. Un bon harness laisse la progression, les résultats de vérification et les prochaines actions dans des fichiers, pour que la nouvelle session démarre depuis un état écrit.
- **Dérive** : L'écart entre la compréhension de l'agent et l'état réel du dépôt de code. Chaque frontière de session introduit de la dérive ; sans contrôle, elle se cumule.
- **Anxiété de contexte** : Un phénomène observé par Anthropic — les agents présentent un comportement de convergence prématurée à l'approche des limites de contexte perçues, terminant les tâches prématurément pour éviter la perte d'informations. C'est une anxiété irrationnelle face aux ressources.
- **Compaction vs réinitialisation** : La compaction résume le contexte au sein de la même session (conserve le « quoi », peut perdre le « pourquoi ») ; la réinitialisation ouvre une nouvelle session reconstruisant à partir de l'état persisté (propre mais dépend de l'exhaustivité des artefacts).
@@ -160,7 +160,7 @@ LangChain rapporte un score passant de 52,8% à 66,5%, soit 13,7 points, avec le
- Les fenêtres de contexte sont une ressource finie. Les tâches longues s'étaleront sur plusieurs sessions, et les sessions perdront de l'information — comme l'artisan qui oublie chaque jour, c'est une réalité objective.
- La solution n'est pas des fenêtres plus grandes — c'est une meilleure persistance de l'état. Fichiers de progression + journaux de décisions + points de contrôle git — donnez à l'artisan amnésique un journal fiable.
- Traitez l'agent comme un ingénieur atteint d'amnésie : avant de « terminer sa journée », notez ce qui a été fait, pourquoi, et ce qui reste à faire.
-- Le coût de reconstruction est la métrique clé. Les bons harness devraient amener les nouvelles sessions à un état exécutable en moins de 3 minutes.
+- Le coût de reconstruction est la métrique clé. Un bon harness laisse la progression, les résultats de vérification et les prochaines actions dans des fichiers, pour qu'une nouvelle session récupère rapidement.
- Stratégie mixte : tâches courtes en session, tâches longues avec des artefacts structurés pour la continuité.
## Pour aller plus loin
diff --git a/docs/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
index 224ee59..e93188e 100644
--- a/docs/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
+++ b/docs/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -37,7 +37,7 @@ flowchart TB
## Ce qui se passe quand on les mélange
-Le problème le plus direct : les fondations ne sèchent pas correctement. L'agent passe 80 % de ses efforts sur le code de fonctionnalité et 20 % à configurer vaguement de l'infrastructure. Le framework de test est configuré mais jamais vérifié, les règles lint sont définies mais trop laxistes, aucun fichier de progression créé. Ces défauts ne sont pas évidents lors de la première session (parce que l'agent se souvient encore de ce qu'il a fait), mais ils surgissent lors de la deuxième session — le nouvel agent ne sait pas comment lancer, tester, ou où en sont les choses. Fondations bâclées, bâtiment instable.
+Le problème le plus direct : les fondations ne sèchent pas correctement. L'agent passe l'essentiel de ses efforts sur le code de fonctionnalité et traite l'infrastructure comme une réflexion après coup. Le framework de test est configuré mais jamais vérifié, les règles lint sont définies mais trop laxistes, aucun fichier de progression créé. Ces défauts ne sont pas évidents lors de la première session (parce que l'agent se souvient encore de ce qu'il a fait), mais ils surgissent lors de la deuxième session — le nouvel agent ne sait pas comment lancer, tester, ou où en sont les choses. Fondations bâclées, bâtiment instable.
Un coût plus caché est l'« accumulation non vérifiée » — le code de fonctionnalité écrit avant que le framework de test ne soit configuré est du code sans vérification. Quand vous revenez enfin pour ajouter des tests à ce code, vous pourriez découvrir que la conception était fausse dès le départ — si vous l'aviez su, vous l'auriez implémenté différemment. Comme carreler sur du béton encore humide — quand vous découvrez que le sol n'est pas de niveau, toutes les tuiles doivent être arrachées et refaites.
@@ -45,7 +45,7 @@ Le budget de session est également gaspillé. Le travail d'initialisation (conf
Le problème le plus facilement négligé est celui des mines d'hypothèses implicites. Les décisions que l'agent prend pendant l'initialisation (quel framework de test, comment organiser les répertoires, gestion des dépendances) — si elles ne sont pas explicitement enregistrées, les sessions suivantes ne peuvent pas comprendre ces choix. Pire, les sessions suivantes pourraient prendre des décisions contradictoires. La première équipe de construction a utilisé des fondations en béton, la deuxième ne le sait pas et y a enfoncé des pilotis en bois — les fondations se fissurent.
-La recherche d'Anthropic sur le développement d'applications longue durée recommande explicitement de séparer l'initialisation de l'implémentation. Leurs données expérimentales : les projets utilisant une phase d'initialisation dédiée ont montré des taux de complétion de fonctionnalités 31 % plus élevés dans les scénarios multi-sessions par rapport aux approches mixtes. L'insight clé — le temps investi dans la phase d'initialisation est entièrement récupéré dans les 3-4 sessions suivantes. Plus les fondations sont solides, plus vite les murs montent.
+Le travail d'Anthropic sur les agents longue durée [fait de l'initialisation une première session séparée](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents). L'initialiseur écrit un script `init.sh`, un fichier de progression, une liste de fonctionnalités et un commit git initial ; les sessions de codage suivantes lisent cet état, traitent une fonctionnalité à la fois, la testent de bout en bout, committent et mettent à jour le fichier de progression.
Le guide de harness engineering d'OpenAI Codex souligne également le principe du « dépôt comme registre opérationnel » — établir une structure opérationnelle claire dès la première exécution, ou chaque nouvelle session doit ré-inférer les conventions du projet.
diff --git a/docs/fr/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/fr/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
index 3653893..1e29ec0 100644
--- a/docs/fr/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
+++ b/docs/fr/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -26,7 +26,7 @@ Le comportement réel de Claude Code est révélateur. Demandez-lui d'« ajouter
Six étapes plus tard, chacune est à moitié faite. Pas de vérification de bout en bout, couplage complexe entre le code à moitié cuit, et la session suivante qui devra ramasser les morceaux sera complètement perdue. Comme quelqu'un qui cuisine six plats simultanément — chaque plat est dans la poêle mais aucun n'est dressé. Ils brûlent tous.
-Les données expérimentales d'Anthropic le confirment directement : les agents utilisant une stratégie de « petit pas suivant » (équivalent à WIP=1) affichent un taux de complétion de tâches 37 % plus élevé que les agents utilisant des prompts larges. Plus intéressant encore, le nombre de lignes de code générées par les agents est faiblement corrélé négativement avec la complétion réelle des fonctionnalités — plus de code écrit, moins de fonctionnalités complétées. Prendre plus qu'on ne peut mâcher, prouvé par les données.
+Le travail d'Anthropic sur les agents longue durée [demande à l'agent de codage de traiter une fonctionnalité à la fois](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), puis de vérifier, committer et mettre à jour la progression avant de passer à la suivante. Un prompt large invite l'agent à ouvrir plusieurs fils en parallèle, et chaque fil dispute le même contexte et le même budget de vérification.
## Flux de travail WIP=1
diff --git a/docs/fr/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/fr/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
index b1e2975..7c1efb1 100644
--- a/docs/fr/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
+++ b/docs/fr/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -23,7 +23,7 @@ Did user auth, shopping cart mostly done, still need payments
Une nouvelle session d'agent peut-elle répondre à ces questions à partir de cette note ? Que signifie "mostly done" ? Quels tests le panier a-t-il réussis ? Qu'est-ce qui bloque les paiements ? La réponse à tout cela est "personne ne sait". Comme dire à votre médecin "j'ai mal au ventre, ça va à peu près ces derniers temps" : quel médicament peut-il prescrire ?
-Résultat : la nouvelle session passe 20 minutes à inférer l'état du projet et peut réimplémenter des fonctionnalités déjà terminées. Les données d'ingénierie d'Anthropic montrent que de bons enregistrements de progression réduisent le temps de diagnostic au démarrage d'une session de 60 à 80%.
+Résultat : la nouvelle session doit inférer l'état du projet et peut réimplémenter des fonctionnalités déjà terminées. Le conseil d'Anthropic est de [consigner la progression et les résultats de vérification dans des fichiers versionnés](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) pour que la session suivante puisse inspecter l'état.
## Machine d'état des fonctionnalités
@@ -112,7 +112,7 @@ Une plateforme e-commerce avec 10 fonctionnalités. Deux approches de suivi ont
**Mode colonne vertébrale** : chaque fonctionnalité a un état clair et une commande de vérification. La nouvelle session lit la liste et sait en 3 minutes : F01-F05 sont `passing`, F06 est `active`, F07-F10 sont `not_started`. Elle reprend directement à F06, sans retravail.
-Résultat quantifié : les projets utilisant des listes de fonctionnalités structurées affichent un taux d'achèvement 45% supérieur au suivi libre, avec zéro implémentation dupliquée.
+Une liste structurée rassemble l'état de chaque fonctionnalité et sa commande de vérification au même endroit, si bien que la nouvelle session sait ce qui est terminé.
## Points clés
diff --git a/docs/fr/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/fr/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
index ba9e7e3..cb2aa18 100644
--- a/docs/fr/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
+++ b/docs/fr/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -70,7 +70,7 @@ Un agent d'évaluation indépendant, spécifiquement réglé pour être « point
| Architecture | Durée d'exécution | Coût | Fonctionnalités principales fonctionnelles ? |
|--------------|---------|------|------------------------|
| Agent unique (exécution nue) | 20 min | 9 $ | Non (entités du jeu ne réagissent pas aux entrées) |
-| Trois agents (planificateur + générateur + évaluateur) | 6 heures | 200 $ | Oui (le jeu est entièrement jouable) |
+| Trois agents (planificateur + générateur + évaluateur) | 6 heures | 200 $ | Le cœur du gameplay fonctionnait ; la physique et les niveaux posaient encore problème |
C'est exactement le même modèle (Opus 4.5) avec exactement le même prompt (« construire un éditeur de jeu rétro 2D »). La seule différence est le harness — passer d'une « exécution nue » à « planificateur détaille les exigences → générateur implémente fonctionnalité par fonctionnalité → évaluateur effectue des tests de clic réels avec Playwright ».
@@ -119,7 +119,7 @@ Les signaux à l'exécution efficaces incluent :
**Déductions de points réelles** : (1) Le flux de bout en bout n'a pas été testé — l'envoi et la vérification réels du lien de réinitialisation n'ont jamais été confirmés. (2) La migration de la base de données a échoué après une exécution partielle, causant une incohérence du schéma. (3) La configuration du service email manquait dans l'environnement cible.
-**Intervention du harness** : Validation d'achèvement imposée — (1) Démarrer l'application complète pour vérifier l'accessibilité de l'endpoint de réinitialisation ; (2) Exécuter le flux complet de réinitialisation ; (3) Vérifier la cohérence de l'état de la base de données. Tous les défauts ont été trouvés dans la session, permettant d'économiser 5 à 10 fois le coût des corrections ultérieures. Le correcteur indépendant a trouvé les vrais problèmes.
+**Intervention du harness** : Validation d'achèvement imposée — (1) Démarrer l'application complète pour vérifier l'accessibilité de l'endpoint de réinitialisation ; (2) Exécuter le flux complet de réinitialisation ; (3) Vérifier la cohérence de l'état de la base de données. Les trois défauts apparaissent dans la session, quand le coût de correction reste local. Le correcteur indépendant a trouvé les vrais problèmes.
## Points clés
diff --git a/docs/fr/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/fr/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
index 58a537e..14e120b 100644
--- a/docs/fr/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
+++ b/docs/fr/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -132,7 +132,7 @@ Chaque fois qu'un nouveau type d'erreur d'agent est découvert lors d'une revue
| Problème de permissions | Permissions différentes dans l'environnement packaging | Manqué | Détecté |
| Propagation d'erreur | Les exceptions de la couche service n'atteignaient pas la couche UI | Manqué | Détecté |
-Les 5 défauts ont été détectés par les tests de bout en bout, tandis que les tests unitaires n'en ont détecté aucun. Le coût a été une augmentation du temps de test de 2 secondes à 15 secondes — tout à fait acceptable dans un flux de travail d'agent. Aussi bien que chaque partie chante individuellement, ça ne remplace pas une répétition générale complète.
+Les 5 défauts ont été détectés par les tests de bout en bout, tandis que les tests unitaires n'en ont détecté aucun. L'exécution de bout en bout est plus lente, mais ce coût est faible face à la livraison de cinq défauts de frontière. Aussi bien que chaque partie chante individuellement, ça ne remplace pas une répétition générale complète.
## Points clés
diff --git a/docs/fr/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/fr/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
index 9d2ddaa..a00f700 100644
--- a/docs/fr/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
+++ b/docs/fr/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -44,7 +44,7 @@ Quand un harness manque d'observabilité, quatre problèmes apparaissent systém
**Les retries deviennent des paris aveugles** : quand l'agent ne sait pas pourquoi quelque chose a échoué, la direction du retry est aléatoire. Il peut corriger des chemins de code sans rapport en ignorant la vraie cause racine. Chaque retry aveugle coûte des tokens et du temps.
-**Falaise d'information au handoff** : quand un travail incomplet passe à la session suivante, l'absence d'observabilité oblige la nouvelle session à diagnostiquer l'état du système depuis zéro. Les observations d'Anthropic sur les agents longue durée montrent que ce diagnostic redondant peut consommer 30-50 % du temps total de session.
+**Falaise d'information au handoff** : quand un travail incomplet passe à la session suivante, l'absence d'observabilité oblige la nouvelle session à diagnostiquer l'état du système depuis zéro. Elle doit relire le code, relancer les commandes et décider quels signaux comptent ; [des enregistrements versionnés de progression et de vérification](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) fournissent un état inspectable.
### Un scénario réaliste avec Claude Code
@@ -54,7 +54,7 @@ Imaginez un harness avec workflow à trois rôles, planner-generator-evaluator,
**Avec observabilité complète** : le planner produit un sprint contract listant les composants à modifier, les critères de vérification et les exclusions. Le generator implémente selon le contrat. L'observabilité runtime enregistre le chargement et l'application des styles de chaque composant. L'evaluator utilise une grille de score, dimension par dimension, avec citations de preuves. Une itération produit un résultat de haute qualité en environ 15 minutes.
-La différence d'efficacité est de 3x. Le seul changement est l'observabilité.
+La différence tient au fait que le contrat et les preuves existent en dehors de la tête de l'agent.
### Pourquoi les agents ne peuvent pas résoudre cela seuls
@@ -128,7 +128,7 @@ Un harness avec workflow planner-generator-evaluator exécute « ajouter le supp
- La grille fournit une évaluation structurée dimension par dimension
- Une itération produit des résultats de haute qualité en 15 minutes
-Amélioration d'efficacité de 3x, qualité plus stable, évaluations reproductibles.
+Qualité plus stable, évaluations reproductibles.
## Points clés
@@ -136,7 +136,7 @@ Amélioration d'efficacité de 3x, qualité plus stable, évaluations reproducti
- **Les deux couches d'observabilité sont essentielles** : les signaux runtime expliquent « ce qui s'est passé », les artefacts de processus expliquent « pourquoi cela a été fait ainsi ».
- **Les sprint contracts alignent en amont**, évitant qu'un generator construise quelque chose que l'evaluator rejette immédiatement pour des raisons prévisibles.
- **Les grilles rendent l'évaluation reproductible**, différents évaluateurs produisant des scores proches pour le même résultat.
-- **Le manque d'observabilité gaspille 30-50 % du temps de session en diagnostic redondant.**
+- **L'observabilité transforme un rejet vague en défaut concret et corrigeable.**
## Pour aller plus loin
diff --git a/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
index 0106296..0223c13 100644
--- a/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
+++ b/docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -54,7 +54,7 @@ flowchart LR
Les lois de Lehman sur l'évolution logicielle nous disent : les systèmes soumis à des changements continus augmenteront inévitablement en complexité s'ils ne sont pas activement gérés. C'est particulièrement vrai pour les agents de codage IA — chaque session introduit des changements, et sans nettoyage à la sortie, la dette technique s'accumule de manière exponentielle.
-Les données réelles sont éloquentes. Un projet développé avec des agents pendant 12 semaines, sans stratégie de nettoyage :
+Pour un projet hypothétique de 12 semaines, supposons les valeurs suivantes :
- Semaine 1 : Taux de réussite du build 100 %, taux de réussite des tests 100 %, démarrage de nouvelle session 5 min
- Semaine 4 : Build 95 %, tests 92 %, démarrage 15 min
@@ -66,7 +66,7 @@ Le même projet avec une stratégie de nettoyage :
- Semaine 1 : 100 %, 100 %, 5 min
- Semaine 12 : 97 %, 95 %, 9 min
-Après 12 semaines : le taux de réussite du build diffère de 29 points de pourcentage, le temps de démarrage d'une nouvelle session diffère de 85 %. Ce n'est pas théorique — c'est une différence observée.
+Une boucle de nettoyage hebdomadaire maintient l'état de départ stable : chaque session se termine avec le build, les tests, l'avancement et les artefacts temporaires en ordre, si bien que la session suivante part de la même base.
### Les cinq dimensions de l'état propre
@@ -76,7 +76,7 @@ L'état propre, ce n'est pas juste « le code compile ». C'est cinq dimensions
**Dimension tests** : Tous les tests passent-ils ? Y compris les tests qui existaient avant la session — la session est responsable de ne pas casser les fonctionnalités existantes. Et cela devrait être vérifié dans le CI, pas juste « ça marche chez moi ».
-**Dimension avancement** : L'avancement actuel est-il enregistré dans un artefact lisible par machine ? Sous-tâches terminées avec leurs critères de réussite, sous-tâches en cours mais incomplètes avec leur état actuel, sous-tâches non encore commencées. De bons enregistrements d'avancement réduisent de 60 à 80 % le temps de diagnostic au démarrage d'une session.
+**Dimension avancement** : L'avancement actuel est-il enregistré dans un artefact lisible par machine ? Sous-tâches terminées avec leurs critères de réussite, sous-tâches en cours mais incomplètes avec leur état actuel, sous-tâches non encore commencées. Enregistrez l'avancement et les résultats de vérification dans des fichiers versionnés pour que la session suivante puisse inspecter l'état.
**Dimension artefacts** : Y a-t-il des artefacts temporaires périmés ou ambigus ? Logs de debug, fichiers temporaires, code commenté, marqueurs TODO — tous ces éléments augmentent la charge cognitive pour la prochaine session.
@@ -160,7 +160,7 @@ Une application Electron développée avec des agents sur 12 semaines, comparant
**Avec stratégie de nettoyage** (groupe expérimental) : Vérification complète d'état propre à chaque fin de session + boucle de nettoyage hebdomadaire. Semaine 12, taux de réussite du build 97 %, taux de réussite des tests 95 %, démarrage de nouvelle session 9 min, artefacts périmés 11.
-À la semaine 12, le taux de réussite du build du groupe expérimental est de 29 points de pourcentage plus élevé, le taux de réussite des tests de 34 points plus élevé, et le temps de démarrage d'une nouvelle session réduit de 85 %.
+À la semaine 12, le groupe expérimental garde des taux de build et de tests proches du point de départ, démarre plus vite et laisse peu d'artefacts périmés. Le nettoyage coûte quelques minutes par session et donne à la session suivante un état de départ fiable.
## Points clés
diff --git a/docs/fr/lectures/lecture-13-loop-engineering/index.md b/docs/fr/lectures/lecture-13-loop-engineering/index.md
index 5ca1683..b843d41 100644
--- a/docs/fr/lectures/lecture-13-loop-engineering/index.md
+++ b/docs/fr/lectures/lecture-13-loop-engineering/index.md
@@ -84,11 +84,11 @@ L'ingénierie des boucles, sujet de ce cours, ne concerne pas une commande en pa
Vous n'avez pas à taper `/goal` à chaque fois. Mais comprendre d'où il vient et pourquoi il a cette apparence — c'est comprendre le cœur de l'ingénierie des boucles. Les boucles plus complexes ajoutent simplement des éléments comme la planification, le parallélisme, l'isolation et la mémoire sur ces mêmes trois fondamentaux : but, vérification, condition d'arrêt.
-## Juin 2026 : Trois personnes ont allumé la même mèche en une semaine
+## Des dates différentes, la même direction
-La première semaine de juin 2026, trois praticiens construisant une infrastructure d'agents de codage — sans se consulter — ont dit la même chose avec des mots différents.
+La même idée a émergé à des endroits et à des moments différents.
-**Peter Steinberger** (créateur d'OpenClaw, [son post a atteint 8 millions de vues](https://x.com/steipete/status/2063697162748260627)) : « Vous ne devriez plus faire de prompting à des agents de codage. Vous devriez concevoir des boucles qui font du prompting à vos agents. »
+**Peter Steinberger** (créateur d'OpenClaw, [dans un post](https://x.com/steipete/status/2063697162748260627)) : « Vous ne devriez plus faire de prompting à des agents de codage. Vous devriez concevoir des boucles qui font du prompting à vos agents. »
**Boris Cherny** (responsable de Claude Code chez Anthropic, [sur le podcast Acquired](https://x.com/rohanpaul_ai/status/2063289804708835412)) : « Je ne fais plus de prompting à Claude. J'ai des boucles qui tournent et qui font du prompting à Claude et trouvent quoi faire. Mon travail, c'est écrire des boucles. »
@@ -96,9 +96,9 @@ La première semaine de juin 2026, trois praticiens construisant une infrastruct
> **L'ingénierie des boucles, c'est vous remplacer vous-même comme la personne qui fait du prompting à l'agent. Vous concevez le système qui le fait à votre place.**
-Cherny a divulgué des chiffres : pendant plus de 30 jours consécutifs, toutes les contributions de code à Claude Code ont été faites de manière autonome par l'IA — 259 PR fusionnées, plus de 80 % du code de production écrit par Claude, et un taux de réussite de 76 % sur les tâches logicielles ouvertes.
+Cherny écrit dans un [rapport personnel du 2025-12-27](https://twitter.com/bcherny/status/2004887829252317325) qu'en 30 jours il a fusionné 259 PR — 497 commits, 40 000 lignes ajoutées, 38 000 supprimées — et que chaque ligne a été écrite par Claude Code + Opus 4.5.
-Trois personnes. Une semaine. La même conclusion. Pas parce qu'ils se sont coordonnés — mais parce que l'infrastructure avait discrètement franchi un seuil. Les agents étaient devenus suffisamment fiables pour terminer des tâches non triviales sans surveillance. Les primitives de planification (`/loop`, `/goal`, cron) étaient désormais intégrées aux outils. Le coût d'une seule exécution d'agent avait suffisamment baissé pour que l'exécuter répétitivement sur une minuterie ne paraisse plus gaspillé. Quand toutes les pièces sont présentes, le mouvement qui les combine devient évident pour tout le monde en même temps.
+Ces citations viennent de dates, de formats et d'équipes différents. Leur direction commune : sortir la planification, la vérification et la décision d'arrêt du prompt du moment pour les confier à un système. Mi-2026, les agents pouvaient terminer des tâches non triviales sans surveillance, les primitives de planification étaient intégrées, et une exécution coûtait assez peu pour être répétée sur une minuterie. Quand les pièces sont là, plus d'une personne les assemble.
> Source : [Addy Osmani : Loop Engineering](https://addyosmani.com/blog/loop-engineering/)
@@ -267,7 +267,7 @@ flowchart TD
Ce n'est plus une simple exécution d'agent. C'est un système en fonctionnement continu qui se réveille chaque matin, balaye le sol de lui-même, et met les choses qui nécessitent votre attention devant vous. Votre rôle devient : **revoir le contenu de la boîte de réception, prendre des décisions, et quand vous repérez un schéma que le système ne peut pas gérer, affiner les skills et les règles.**
-Cherny a utilisé ce schéma pour fusionner 259 PR en 30 jours sans ouvrir un IDE une seule fois. Les ingénieurs d'OpenAI ont utilisé le même schéma pour construire un produit bêta d'environ un million de lignes à la main — sans écrire une seule ligne de code eux-mêmes.
+Le rapport de 30 jours de Cherny est un point de données pour ce schéma : 259 PR, code écrit par Claude Code + Opus 4.5. Le [compte rendu du harness d'OpenAI](https://openai.com/index/harness-engineering/) en est un autre : une petite équipe a utilisé Codex sur un dépôt vierge pendant cinq mois et rapporte environ un million de lignes et près de 1 500 PR.
## Séparation générateur/évaluateur : Pourquoi vous ne pouvez pas laisser le modèle noter son propre travail
@@ -293,7 +293,7 @@ Une phrase à retenir : **quelqu'un dans votre équipe ne doit pas vous croire.*
Si vous voulez voir à quoi ressemble une boucle bien conçue et qui tourne réellement, [l'autoresearch de Karpathy](https://github.com/karpathy/autoresearch) est l'exemple de manuel.
-En mars 2026, Karpathy a publié un projet Python de 630 lignes. Donnez-lui un GPU et une direction de recherche, et il tourne toute la nuit — complétant des centaines d'expériences d'entraînement ML, ne gardant que celles qui s'améliorent réellement. Le projet a atteint 66 000+ étoiles en quelques jours après sa sortie.
+En mars 2026, Karpathy a publié [autoresearch](https://github.com/karpathy/autoresearch). Le dépôt est volontairement petit : `prepare.py` est l'infrastructure fixe, `train.py` est le fichier que l'agent modifie (environ 630 lignes), et `program.md` est la méthodologie de recherche que l'humain modifie. Donnez-lui un GPU et une direction de recherche, et il tourne toute la nuit — chaque expérience reçoit un budget d'entraînement fixe de 5 minutes (temps d'horloge, hors démarrage et compilation), et seuls les changements qui améliorent `val_bpb` sont conservés.
### Trois fichiers, trois rôles
@@ -343,9 +343,9 @@ flowchart TD
8b --> 9
```
-Il exécute environ 12 expériences par heure. Une exécution de nuit (8 heures) représente environ 100 expériences. Karpathy lui-même l'a fait tourner pendant 2 jours — ~700 expériences.
+Le README estime environ 12 expériences par heure, soit environ 100 pour une exécution de nuit de 8 heures. Le budget de 5 minutes couvre l'entraînement, pas le démarrage ni la compilation ; le reste de chaque tour sert à modifier le code, lancer l'expérience et évaluer le résultat. Karpathy rapporte avoir fait tourner une version privée d'autoresearch de façon autonome pendant environ deux jours pour le tour nanochat décrit ci-dessous.
-Le budget de temps réel fixe de 5 minutes est un choix de conception clé — peu importe ce que l'agent modifie, chaque expérience prend exactement le même temps. Cela signifie que tous les résultats sont directement comparables sous le même budget temps — pas de débat sur « celui-ci a tourné plus longtemps donc c'est mieux ».
+Le budget d'entraînement fixe de 5 minutes est un choix de conception clé — peu importe ce que l'agent modifie, l'entraînement reçoit le même budget d'horloge. Cela signifie que tous les résultats sont directement comparables sous le même budget d'entraînement.
### Sortie : Ce que vous voyez quand vous vous réveillez
@@ -375,13 +375,9 @@ L'agent écrit des messages de commit clairs sur ce qu'il a essayé, ce qui a fo
### Ce qu'il a réellement trouvé
-Résultats de la course initiale de 2 jours, ~700 expériences de Karpathy :
+Le [tour 1](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b) d'autoresearch a réduit le temps d'entraînement de niveau GPT-2 de nanochat sur 8×H100 [de **2,02 heures à 1,80 heure**](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b), soit une réduction d'environ **10,9 %** du temps d'entraînement.
-- Sur ~700 tentatives, environ **20 améliorations réelles empilables** ont été trouvées
-- Réduit le temps d'entraînement de niveau GPT-2 de nanochat sur 8×H100 de **2,02 heures → 1,80 heure**, environ **11 % plus rapide**
-- Les découvertes incluaient : ajustements du taux d'apprentissage, réglage de l'optimiseur, échanges d'activation, optimisations de schéma d'attention, etc.
-
-Toutes les améliorations étaient-elles des découvertes bouleversantes ? Non. La plupart étaient de petites optimisations qui se sont empilées. Mais ces 20 améliorations valides auraient pris à un chercheur humain des semaines de travail manuel — l'agent l'a fait en 48 heures.
+La plupart des changements étaient de petites optimisations empilées. Ce qui compte, c'est la boucle : un budget fixe, un journal d'expériences complet et une règle selon laquelle seules les améliorations vérifiées restent.
### Le détail le plus révélateur : La boucle est écrite en anglais, pas en code.
@@ -399,7 +395,7 @@ Les boucles rapides vous tentent de sauter la vérification. « Ça a l'air bien
### 2. Pourriture de compréhension
-Plus une boucle livre du code vite, plus votre compréhension de votre propre base de code s'éloigne de la réalité. L'équipe de Cherny avait 80 % du code écrit par des agents — ce qui signifie que la plupart du code d'une équipe n'a pas été écrit par une personne. Si vous ne lisez pas et n'utilisez pas ce que la boucle produit, votre compréhension décline continuellement. **Les boucles rapides nécessitent une lecture rapide.**
+Plus une boucle livre du code vite, plus votre compréhension de votre propre base de code s'éloigne de la réalité. Une boucle fusionne des centaines de PR ; l'équipe lit ces PR, examine les diffs qui comptent et continue d'utiliser le code, si bien que son modèle mental suit. **Les boucles rapides nécessitent une lecture rapide.**
### 3. Abandon cognitif
@@ -407,11 +403,11 @@ Quand la boucle tourne bien, la posture la plus confortable est d'arrêter d'avo
### 4. Explosion de tokens
-Chaque itération d'une boucle accumule plus de contexte : code écrit, erreurs rencontrées, décisions prises. Sans gestion du contexte, la taille du prompt grossit approximativement quadratiquement avec le nombre de tours. Codex résout ça avec une compaction automatique du contexte — une API dédiée compresse les anciens tours de conversation en résumés de contenu chiffrés, conservant les connaissances essentielles tout en rejetant les détails redondants. C'est une préoccupation d'ingénierie que vous devez aborder dès la première boucle, pas un ajout ultérieur.
+Chaque itération d'une boucle accumule plus de contexte : code écrit, erreurs rencontrées, décisions prises. Quand chaque tour ajoute à peu près une quantité fixe de contenu nouveau, la longueur d'historique vue par un tour croît approximativement linéairement avec le nombre de tours. Si le système retraite tout l'historique à chaque tour, l'entrée cumulée sur N tours croît approximativement quadratiquement. Codex résout ça avec une compaction automatique du contexte — une API dédiée compresse les anciens tours de conversation en résumés de contenu chiffrés, conservant les connaissances essentielles tout en rejetant les détails redondants. C'est une préoccupation d'ingénierie que vous devez aborder dès la première boucle, pas un ajout ultérieur.
## Construire votre première boucle
-Vous n'avez pas besoin de commencer par un pipeline à l'échelle Stripe fusionnant 1 300 PR par semaine. Commencez par la plus petite chose qui fonctionne.
+Vous n'avez pas besoin de commencer par un pipeline à haut débit fusionnant des centaines de PR par semaine. Commencez par la plus petite chose qui fonctionne.
### Étape 1 : Choisissez une tâche récurrente
diff --git a/docs/fr/lectures/lecture-14-graph-engineering/index.md b/docs/fr/lectures/lecture-14-graph-engineering/index.md
index ef41498..fb96a9d 100644
--- a/docs/fr/lectures/lecture-14-graph-engineering/index.md
+++ b/docs/fr/lectures/lecture-14-graph-engineering/index.md
@@ -9,7 +9,7 @@ Six semaines après le cours sur l'ingénierie des boucles, le 18 juillet 2026,
> « On parle encore de Loop, ou on est déjà passé à Graph ? »
-Un tweet, environ 570 000 vues en une journée, puis environ 3 millions à la fin du mois. Quelques heures plus tard, l'ingénieur en machine learning Hamel Husain a publié un article intitulé *Loop Engineering Is Dead. Enter Graph Engineering* — le corps du texte ne contenant qu'un GIF disant « Stop it » — qui a récolté environ 680 000 vues.
+Un tweet. Quelques heures plus tard, l'ingénieur en machine learning Hamel Husain a publié un article intitulé *Loop Engineering Is Dead. Enter Graph Engineering* — le corps du texte ne contenant qu'un GIF disant « Stop it ».
Le plus révélateur : **ces deux personnes plaisantaient.** L'un parodiait une industrie qui invente un nouveau terme toutes les six semaines, l'autre suivait le fil pour enchaîner la blague. Mais la blague n'a vécu qu'environ un week-end — cours, feuilles de route, piles d'outils ont recouvert les timelines avant la fin du week-end, accompagnés d'une série de chiffres inventés : « précision +18 %, coût -85 % » étaient des données fausses (le 18 % et le 85 % existent bien, mais proviennent d'un article sur des schémas de tuyauterie industrielle, avec des lignes de base tout à fait différentes), et « Microsoft, Stanford et Anthropic ont découvert l'ingénierie des graphes en même temps » était aussi une fausse information. La seule « pionnière » confirmée par la vérification des faits est Josh Simmons : son *We Are Entering the Graph Engineering Phase* a été écrit le 4 juillet, deux semaines pleines avant cette blague — **c'est la blague qui a rendu le sujet populaire, pas la blague qui l'a créé.**
@@ -257,11 +257,11 @@ Une fois exécuté, comparez avec le graphe ci-dessus : votre `graph.md` écrit
## Projets open source : ce qui existe après la publication, ce qui existait avant
-D'abord, clarifions les limites : **le Graph Engineering est un nom qui n'existe que depuis le 18 juillet 2026.** Les frameworks open source publiés avant cette date ne sont pas des « projets d'après la publication du Graph Engineering ». Ceux qui sont vraiment apparus avec ce nom après que le concept a explosé — à début août 2026, il n'y en a qu'un qui tienne la route :
+D'abord, clarifions les limites : **le Graph Engineering est un nom qui n'existe que depuis le 18 juillet 2026.** Les frameworks open source publiés avant cette date ne sont pas des « projets d'après la publication du Graph Engineering ». Un projet qui utilise explicitement ce nom est GraphARC :
**Ce qui existe après la publication du concept**
-- [GraphArc](https://github.com/CodeGraphContext/grapharc) (2026-08-02) : se présente comme « la première implémentation en temps réel du Graph Engineering ». Il transforme l'exécution d'agent, de trace enfouie dans les logs, en un **graphe d'orchestration interactif en temps réel** — chaque agent, chaque dépendance, chaque point de décision est dessiné, l'ensemble du graphe est visualisé avant exécution, et vous l'approuvez (même depuis votre téléphone) avant de le laisser partir. L'auteur a construit des outils de graphes pour plus de 4000 développeurs, avec une direction « observable, débogable, ingénierisable ». Très récent, fonctionnalités encore en phase précoce.
+- [GraphARC](https://github.com/CodeGraphContext/GraphARC) (créé en juillet 2026) : se décrit comme « an end to end implementation of Graph Engineering as proposed by Andrew NG and Peter Steinberger ». C'est un projet Python à un stade précoce. Le geste utile est de lire son modèle d'orchestration et de décider si l'approche convient à votre workflow.
**Ce qui existait avant la publication du concept (ils ne s'appellent pas Graph Engineering, mais ce sont eux que vous utiliserez pour construire)**
@@ -325,7 +325,7 @@ Toutes les tâches ne méritent pas d'être dessinées en graphe. Cinq critères
- [goddaehee: Graph Engineering : vérification des faits (koréen, 2026-07-30)](https://goddaehee.tistory.com/628) — la vérification des faits la plus complète : chronologie de l'origine de la blague, décomposition des faux chiffres, données LangGraph, comparaison de la popularité Hacker News
- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — l'article sérieux qui précède la blague de deux semaines
- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — la réponse officielle : « pas une nouvelle idée, le plus récent nom d'une méthode existante » ; 65 millions de téléchargements mensuels pour LangGraph
-- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — les données de propagation du buzzword (tweet original à 575 000 vues)
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — un récit de la façon dont ce terme s'est propagé
- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — la comparaison transversale de sept frameworks open source majeurs : LangGraph, CrewAI, Microsoft Agent Framework, LlamaIndex, Google ADK, OpenAI Agents SDK, Mastra
- [Documentation officielle de LangGraph](https://docs.langchain.com/oss/python/langgraph/graph-api) — « Nodes do the work, edges tell what to do next » ; la définition précise des nœuds et des arêtes, la référence de première main pour construire un graphe
- [Anthropic: Building Effective Agents (déc. 2024)](https://www.anthropic.com/engineering/building-effective-agents) — les cinq motifs, dessinés, ce sont des graphes ; la distinction autorisée entre workflow et agent
diff --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.md
index e9a147b..ec20b3e 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
@@ -9,13 +9,13 @@
最初の反応は「このモデルはまだ足りない。アップグレードしよう」かもしれません。少し待ってください。財布を開く前に、問題はモデルではない可能性があります。
-数字を見てみましょう。2025 年後半時点で、最強クラスの coding agent でも SWE-bench Verified ではおおむね 50-60% 程度です。しかもこれは、明確な issue 説明と既存テストがある、慎重に選ばれたタスクでの数字です。日常の開発環境、つまり曖昧な要求、既存テストなし、暗黙のビジネスルールが散らばった環境に移ると、その数字はさらに下がります。
+数字を見てみましょう。2025 年 9 月 29 日、Anthropic は Claude Sonnet 4.5 が [SWE-bench Verified で 77.2%](https://www.anthropic.com/news/claude-sonnet-4-5) を記録したと発表しました。しかもこれは、明確な issue 説明と既存テストがある、慎重に選ばれたタスクでの数字です。日常の開発環境、つまり曖昧な要求、既存テストなし、暗黙のビジネスルールが散らばった環境に移ると、その数字はさらに下がります。
しかし、この数字の裏には直感に反する真実があります。
## 同じ馬、違う運命
-Anthropic は制御実験を行いました。同じプロンプト(「2D レトロゲームメーカーを作る」)、同じモデル(Opus 4.5)。1 回目は bare、支援なし。20 分、9 ドル、ゲームの中核機能はまったく動きませんでした。2 回目は完全な harness(planner + generator + evaluator の 3 エージェント構成)。6 時間、200 ドル、ゲームはプレイ可能でした。
+Anthropic は同じプロンプト(「2D レトロゲームメーカーを作る」)と同じモデル(Opus 4.5)を、2 つの harness で比較しました。1 回目は bare、支援なし。20 分、9 ドル:アプリは起動しましたが、エンティティが入力に反応しませんでした。2 回目は完全な harness(planner + generator + evaluator の 3 エージェント構成)。6 時間、200 ドル:エンティティは動かせましたが、物理に粗さが残り、壁が進行を妨げました。[中核のゲームプレイは動作し、アプリは未完成でした。](https://www.anthropic.com/engineering/harness-design-long-running-apps)
モデルは変えていません。Opus 4.5 は同じ Opus 4.5 です。変わったのは馬具です。
@@ -39,9 +39,9 @@ OpenAI の harness engineering 記事ははっきり言っています。よく
こうした状況を踏まえると、次の概念は単なる流行語ではありません。
-- **能力ギャップ**: ベンチマーク上のモデル性能と実タスクでの性能の大きな差。SWE-bench Verified で 50-60% ということは、実 issue のほぼ半分は解けないということです。
+- **能力ギャップ**: ベンチマーク上のモデル性能と実タスクでの性能の大きな差。ベンチマークのタスクは issue 説明、テスト、環境が揃っていますが、実タスクではそれらを自分で用意しなければならないことが多いです。
- **Harness**: モデルの外側にあるすべて。指示、ツール、環境、状態管理、検証フィードバック。モデル重みでなければ harness です。この講義で言う「馬具」です。
-- **Harness 起因の失敗**: モデルには能力があるのに、実行環境に構造的欠陥があるため失敗すること。Anthropic の制御実験がこれを示しています。
+- **Harness 起因の失敗**: モデルには能力があるのに、実行環境に構造的欠陥があるため失敗すること。上のレトロゲームの比較がその一例です。
- **検証ギャップ**: エージェントの出力への自信と実際の正しさの差。エージェントが「完了」と言うが完了していない。最も多い失敗モードです。
- **診断ループ**: 実行し、失敗を観察し、特定の harness 層に原因を割り当て、その層を修正し、再実行する。harness engineering の中核手法です。
- **Definition of Done**: 機械的に検証可能な完了条件。テスト通過、lint クリーン、型チェック通過。明示しなければ、エージェントは勝手に完了条件を作ります。
@@ -72,7 +72,7 @@ Completion criteria:
## 100 万行の実験
-OpenAI は 2025 年に強烈な実験を行いました。空の git リポジトリから、Codex で完全な社内プロダクトを構築する。5 か月後、そのリポジトリにはおよそ 100 万行のコードがありました。アプリケーションロジック、インフラ、ツール、ドキュメント、社内開発ツール。すべてエージェント生成です。3 人のエンジニアが Codex を操作し、約 1,500 PR を作成してマージしました。1 人あたり 1 日平均 3.5 PR です。
+OpenAI は 2025 年 8 月に強烈な実験を始めました。空の git リポジトリから、Codex で完全な社内プロダクトを構築する。[5 か月後、そのリポジトリにはおよそ 100 万行のコードがありました](https://openai.com/index/harness-engineering/)。アプリケーションロジック、インフラ、ツール、ドキュメント、社内開発ツール。すべてエージェント生成です。チームは後に 7 人へ増え、期間中に約 1,500 PR をマージしました。1 人あたり 1 日平均 3.5 PR です。
重要な制約は、**人間が直接コードを書かない**ことでした。これは見世物ではありません。エンジニアの主仕事がコードを書くことではなく、環境を設計し、意図を表現し、フィードバックループを作ることになったとき、何が変わるかを強制的に学ぶための設計でした。
@@ -86,9 +86,9 @@ OpenAI は 2025 年に強烈な実験を行いました。空の git リポジ
あるチームは Claude Sonnet を使って、中規模の Python Web アプリ(FastAPI + PostgreSQL + Redis、約 15,000 行)に新しい API endpoint を追加しようとしました。
-最初は「`/api/v2/users` 配下に user preferences endpoints を追加して」という 1 文だけを渡しました。結果は、エージェントがコンテキストの 40% をリポジトリ探索に使い、見た目は妥当だがプロジェクトのエラーハンドリングパターンに従わず、古い SQLAlchemy 構文を使い、endpoint にランタイムエラーがあるのに完了宣言しました。次のセッションは探索をやり直す必要がありました。
+最初は「`/api/v2/users` 配下に user preferences endpoints を追加して」という 1 文だけを渡しました。結果は、エージェントがセッションの大半をリポジトリ探索に使い、見た目は妥当だがプロジェクトのエラーハンドリングパターンに従わず、古い SQLAlchemy 構文を使い、endpoint にランタイムエラーがあるのに完了宣言しました。次のセッションは探索をやり直す必要がありました。
-その後、彼らは `AGENTS.md`(プロジェクト構造と技術スタックバージョンの説明)、明示的な検証コマンド(`pytest tests/api/v2/ && python -m mypy src/`)、ADR を追加しました。同じモデルは 3 回の独立実行すべてで成功し、コンテキスト効率は約 60% 改善しました。
+その後、彼らは `AGENTS.md`(プロジェクト構造と技術スタックバージョンの説明)、明示的な検証コマンド(`pytest tests/api/v2/ && python -m mypy src/`)、ADR を追加しました。同じモデルはプロジェクトの規約に従い、実行できるコマンドで作業を検証するようになりました。
モデルは変えていません。harness を変えました。
diff --git a/docs/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
index b1b35f0..fec5be8 100644
--- a/docs/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
+++ b/docs/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -52,7 +52,7 @@ flowchart LR
- **コンテキストウィンドウは有限**: ウィンドウサイズがどう謳われていても(128K、200K、1M)、長時間のタスクは最終的にそれを使い果たします。使い切った後は、圧縮(情報を失う)かリセット(新しいセッション)が必要です。どちらも何かを失います。
- **継続性アーティファクト**: 新しいセッションが前回のセッションの続きを明確に再開できるようにする、永続化された状態ファイル。基本形: 進捗ログ + 検証記録 + 次のアクション。あの職人の日記です。
-- **リビルドコスト**: 新しいセッションが実行可能な状態に到達するまでに必要な時間。良い harness はリビルドコストを15分から3分に圧縮できます。
+- **リビルドコスト**: 新しいセッションが実行可能な状態に到達するまでに必要な時間。良い harness は進捗、検証結果、次のアクションをファイルに残し、新しいセッションが書き残された状態から始められるようにします。
- **ドリフト**: エージェントの理解とコードリポジトリの実際の状態との乖離。すべてのセッション境界でドリフトが発生し、制御しなければ複利で増大します。
- **コンテキスト不安**: Anthropic が観察した現象 — エージェントは知覚されるコンテキスト制限に近づくと早期収束行動を示し、情報損失を避けるためにタスクを早期に終了させます。これは非合理的なリソース不安です。
- **圧縮 vs リセット**: 圧縮は同じセッション内でコンテキストを要約します(「何をしたか」は保持、「なぜ」は失われる可能性あり)。リセットは新しいセッションを開始し、永続化された状態から再構築します(クリーンだが、アーティファクトの完全性に依存)。
@@ -160,7 +160,7 @@ LangChain は、同じ gpt-5.2-codex を使う 89 タスクの Terminal Bench 2.
- コンテキストウィンドウは有限のリソースです。長時間のタスクはセッションにまたがり、セッションは情報を失います — 毎日忘れる職人のように、これは客観的な現実です。
- 解決策はより大きなウィンドウではなく、より良い状態の永続化です。進捗ファイル + 決定ログ + Git チェックポイント — 記憶喪失の職人に信頼できる日記を与えます。
- エージェントを記憶喪失のエンジニアとして扱う: 「退勤」前に、何をしたか、なぜ、次は何かを書き留める。
-- リビルドコストが主要な指標です。良い harness は新しいセッションを3分以内に実行可能な状態にするべきです。
+- リビルドコストが主要な指標です。良い harness は進捗、検証結果、次のアクションをファイルに残し、新しいセッションが素早く復帰できるようにします。
- 混合戦略: 短いタスクはセッション内で、長時間のタスクは構造化されたアーティファクトで継続性を確保。
## 参考資料
diff --git a/docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
index acd9b98..3eb839c 100644
--- a/docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
+++ b/docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -37,7 +37,7 @@ flowchart TB
## 混ぜたときに何が起きるか
-最も直接的な問題: 基礎が正しく固まらない。エージェントは労力の80%を機能コードに、20%を適当にインフラの設定に使います。テストフレームワークは設定されたが検証されていない、lint ルールは設定されたが緩すぎる、進捗ファイルは作成されていない。これらの欠陥は最初のセッションでは明らかではありません(エージェントは自分が何をしたかまだ覚えているからです)が、2回目のセッションで表面化します — 新しいエージェントは実行方法、テスト方法、現状がどうなっているかを知りません。ずさんな基礎、ぐらつく建物です。
+最も直接的な問題: 基礎が正しく固まらない。エージェントは労力の大半を機能コードに使い、インフラは後回しにします。テストフレームワークは設定されたが検証されていない、lint ルールは設定されたが緩すぎる、進捗ファイルは作成されていない。これらの欠陥は最初のセッションでは明らかではありません(エージェントは自分が何をしたかまだ覚えているからです)が、2回目のセッションで表面化します — 新しいエージェントは実行方法、テスト方法、現状がどうなっているかを知りません。ずさんな基礎、ぐらつく建物です。
より隠れたコストは「未検証の蓄積」です — テストフレームワークが設定される前に書かれた機能コードは、検証のないコードです。後からそのコードにテストを追加しに行くと、設計が最初から間違っていたことに気づくかもしれません — 知っていれば別の方法で実装していたでしょう。生のコンクリートの上にタイルを貼るようなものです — 床が水平でないことに気づいたとき、すべてのタイルを剥がしてやり直さなければなりません。
@@ -45,7 +45,7 @@ flowchart TB
最も見落とされやすい問題は、暗黙の前提の地雷です。初期化中にエージェントが行う決定(どのテストフレームワーク、ディレクトリの整理方法、依存関係の管理)— 明示的に記録されていなければ、後続のセッションはこれらの選択を理解できません。さらに悪いことに、後続のセッションが矛盾する選択をする可能性があります。最初の建設チームがコンクリート基礎を使ったのに、2番目のチームはそれを知らずに木製の杭を打ち込んだ — 基礎にひびが入ります。
-Anthropic の長時間アプリケーション開発研究は、初期化と実装を分離することを明確に推奨しています。彼らの実験データ: 専用の初期化フェーズを使用したプロジェクトは、混在アプローチと比較してマルチセッションシナリオで31%高い機能完了率を示しました。重要な洞察 — 初期化フェーズに投資した時間は、次の3〜4セッションで完全に回収されます。基礎がしっかりしているほど、壁は速く立ち上がります。
+Anthropic の長時間エージェントの研究では、初期化を[独立した最初のセッション](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)にしています。initializer は `init.sh`、進捗ファイル、機能リスト、初期 git commit を書き、後続の coding セッションはその状態を読み、一度に 1 機能だけ進め、エンドツーエンドでテストし、commit して進捗ファイルを更新します。
OpenAI の Codex harness engineering ガイドも「リポジトリを運用記録とする」原則を強調しています — 最初の実行から明確な運用構造を確立しなければ、新しいセッションは毎回プロジェクトの規約を推測し直すことになります。
diff --git a/docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
index f3cb6b2..386dd53 100644
--- a/docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
+++ b/docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -26,7 +26,7 @@ Claude Code の実際の行動がそれを物語っています。「ユーザ
6ステップ後、すべてが半完成。エンドツーエンドの検証はなく、半完成のコード間に複雑な結合があり、次のセッションで片付けを引き継ぐ者は完全に途方に暮れます。6つの料理を同時に作るようなもの — すべての料理が鍋に入っているが、どれも皿に盛られていません。すべて焦げます。
-Anthropic の実験データはこれを直接的に裏付けています: 「小さな次のステップ」戦略(WIP=1 に相当)を使うエージェントは、広範なプロンプトを使うエージェントより37%高いタスク完了率を示します。さらに興味深いことに、エージェントが生成するコード行数と実際の機能完了率は弱い負の相関があります — より多くのコードを書いた方が、より少ない機能が完了する。背に腹は代えられない、データによる証明です。
+Anthropic の長時間エージェントのガイドは、coding agent に[一度に 1 機能だけを扱うこと](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)を求めます。検証し、commit し、進捗を更新してから次へ進む、という順序です。広範なプロンプトは agent にいくつもの作業を同時に始めさせ、どれも同じコンテキストと検証予算を奪い合います。
## WIP=1 ワークフロー
diff --git a/docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
index ffa1346..5b1b9ee 100644
--- a/docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
+++ b/docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -23,7 +23,7 @@ Did user auth, shopping cart mostly done, still need payments
新しいエージェントセッションは、このメモから次の質問に答えられるだろうか? 「mostly done」とは何か? カートはどのテストに通ったのか? 決済は何でブロックされているのか? 答えはすべて「誰も分からない」だ。医者に「最近お腹が痛いけど、まあ大丈夫」と言うようなもので、どんな薬を出せばよいのか分からない。
-結果として、新しいセッションはプロジェクト状態の推測に 20 分を費やし、完了済み機能を再実装することさえある。Anthropic の engineering data では、よい進捗記録はセッション開始時の診断時間を 60-80% 削減する。
+結果として、新しいセッションはプロジェクト状態を推測しなければならず、完了済み機能を再実装することさえある。Anthropic の助言は、[進捗と検証結果をバージョン管理されたファイルに記録する](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)ことで、次のセッションが状態を検査できるようにすることだ。
## 機能状態マシン
@@ -112,7 +112,7 @@ flowchart LR
**背骨モード**: すべての機能が明確な状態と検証コマンドを持つ。新しいセッションは機能リストを読み、3 分で F01-F05 は `passing`、F06 は `active`、F07-F10 は `not_started` と分かる。F06 から直接再開し、手戻りはゼロ。
-定量結果: 構造化された機能リストを使うプロジェクトは、自由形式の追跡より機能完了率が 45% 高く、重複実装はゼロだった。
+構造化されたリストは各機能の状態と検証コマンドを 1 か所にまとめるので、新しいセッションは何が終わっているかを把握できます。
## 重要なポイント
diff --git a/docs/ja/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/ja/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
index 8cb28e3..ff54a68 100644
--- a/docs/ja/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
+++ b/docs/ja/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -70,7 +70,7 @@ Anthropicは2026年の研究で、より深い失敗パターンを発見しま
| Architecture | Runtime | Cost | Core Features Working? |
|--------------|---------|------|------------------------|
| Single Agent (bare run) | 20 mins | $9 | No (game entities unresponsive to input) |
-| Three Agents (planner + generator + evaluator) | 6 hours | $200 | Yes (game is fully playable) |
+| Three Agents (planner + generator + evaluator) | 6 hours | $200 | Core gameplay worked; physics and level issues remained |
これは全く同じモデル(Opus 4.5)で、全く同じプロンプト("build a 2D retro game editor")を使用しています。唯一の違いはharnessです——「ベア実行」から「plannerが要件を展開 → generatorが機能ごとに実装 → evaluatorがPlaywrightを使って実際のクリックテストを実行」へ。
@@ -119,7 +119,7 @@ OpenAIはCodexの実践で特に効果的なパターンを導入しました:
**実際の減点**:(1)End-to-endフローが未テスト——リセットリンクの実際の送信と検証が一度も確認されていない。(2)データベースマイグレーションが部分実行後に失敗し、スキーマの不整合が発生。(3)対象環境にメールサービスの設定が不足。
-**Harness介入**:終了検証を強制——(1)フルアプリを起動してリセットエンドポイントのアクセシビリティを検証。(2)フルリセットフローを実行。(3)データベース状態の一貫性を検証。すべての欠陥がセッション内で発見され、後続の修正コストの5〜10倍を節約。独立した採点者が本当の問題を見つけました。
+**Harness介入**:終了検証を強制——(1)フルアプリを起動してリセットエンドポイントのアクセシビリティを検証。(2)フルリセットフローを実行。(3)データベース状態の一貫性を検証。3 つの欠陥はすべてセッション内で表面化し、修正コストがまだ局所的なうちに対処できました。独立した採点者が本当の問題を見つけました。
## 重要なポイント
diff --git a/docs/ja/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/ja/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
index 84ff412..28f6f16 100644
--- a/docs/ja/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
+++ b/docs/ja/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -132,7 +132,7 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.rea
| Permission Issue | Different permissions in packaged environment | Missed | Caught |
| Error Propagation | Service layer exceptions didn't reach UI layer | Missed | Caught |
-5つの欠陥すべてがend-to-endテストで検出され、ユニットテストは一つも検出しませんでした。コストはテスト時間が2秒から15秒への増加——agentのワークフローでは完全に許容範囲です。各パートがどれほど上手に単独で歌えても、合同リハーサルには勝てません。
+5つの欠陥すべてがend-to-endテストで検出され、ユニットテストは一つも検出しませんでした。エンドツーエンドの実行は遅くなりますが、そのコストは 5 つの境界欠陥を出荷するのに比べれば小さいものです。各パートがどれほど上手に単独で歌えても、合同リハーサルには勝てません。
## 重要なポイント
diff --git a/docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
index c3031be..8c93041 100644
--- a/docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
+++ b/docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -44,7 +44,7 @@ harness に観測性がないと、4 種類の問題が体系的に発生しま
**再試行が盲目的な推測になる**: 失敗理由がわからないと、再試行の方向はランダムになります。本当の原因を無視して関係ないコード経路を直し続けるかもしれません。盲目的な再試行はすべてトークンと時間を消費します。
-**セッション引き継ぎの情報断崖**: 未完了の作業を次セッションに渡すとき、観測性がないと新しいセッションはシステム状態をゼロから診断し直す必要があります。Anthropic の長時間エージェント観察では、この重複診断がセッション時間の 30-50% を消費することがあります。
+**セッション引き継ぎの情報断崖**: 未完了の作業を次セッションに渡すとき、観測性がないと新しいセッションはシステム状態をゼロから診断し直す必要があります。新しいセッションはコードを読み直し、コマンドを再実行し、どの信号が重要かを判断しなければなりません。[バージョン管理された進捗と検証記録](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)があれば、検査可能な状態が手に入ります。
### Claude Code での現実的なシナリオ
@@ -54,7 +54,7 @@ harness に観測性がないと、4 種類の問題が体系的に発生しま
**完全な観測性あり**: planner はスプリント契約を出します。どのコンポーネントを変更するか、各コンポーネントの検証基準、除外項目(印刷スタイルは扱わない等)を列挙します。generator は契約に従って実装します。ランタイム観測性は各コンポーネントのスタイル読み込みと適用過程を記録します。evaluator は採点ルーブリックで次元ごとに評価し、証拠を引用します。1 回の反復で高品質な結果が出て、約 15 分で終わります。
-効率差は 3 倍です。変わったのは観測性だけです。
+違いは、契約と証拠が agent の頭の外に存在するかどうかから来ます。
### エージェントだけでは解決できない理由
@@ -128,7 +128,7 @@ planner-generator-evaluator workflow の harness で「ダークモード対応
- 採点ルーブリックが次元ごとの構造化評価を提供
- 1 回の反復で高品質な結果、15 分
-効率は 3 倍改善し、品質はより安定し、評価は再現可能になります。
+契約と証拠が手元にあれば、品質はより安定し、評価は再現可能になります。
## 重要なポイント
@@ -136,7 +136,7 @@ planner-generator-evaluator workflow の harness で「ダークモード対応
- **2 つの観測性レイヤーはどちらも必須**です。ランタイム信号は「何が起きたか」を説明し、プロセス成果物は「なぜそうしたか」を説明します。
- **スプリント契約は事前に認識を揃える**ため、「generator が作ったものを evaluator が予見可能な理由で即却下する」事態を防ぎます。
- **採点ルーブリックは評価を再現可能にする**ため、異なる評価者でも同じ出力に近いスコアを出せます。
-- **観測性不足はセッション時間の 30-50% を重複診断に浪費します。**
+- **観測性は、曖昧な却下を具体的で修正可能な欠陥に変えます。**
## 参考資料
diff --git a/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
index 6682cdf..f562739 100644
--- a/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
+++ b/docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -54,7 +54,7 @@ flowchart LR
Lehmanのソフトウェア進化の法則が教えてくれること:継続的な変更を受けるシステムは、積極的に管理されない限り、必然的に複雑さが増大します。これはAIコーディングagentにとって特に当てはまります——すべてのセッションが変更を導入し、終了時のクリーンアップがなければ、技術的負債は指数関数的に蓄積します。
-実際のデータが物語っています。agentを使って12週間開発されたプロジェクト、クリーンアップ戦略なしの場合:
+12週間の仮想的なプロジェクトで、次の値だとします:
- 週1:ビルド合格率 100%、テスト合格率 100%、新セッション起動 5分
- 週4:ビルド 95%、テスト 92%、起動 15分
@@ -66,7 +66,7 @@ Lehmanのソフトウェア進化の法則が教えてくれること:継続
- 週1:100%、100%、5分
- 週12:97%、95%、9分
-12週間後:ビルド合格率の差は29ポイント、新セッション起動時間の差は85%。これは理論ではなく、観察された差異です。
+週次クリーンアップループがスタート時の状態を安定させます。各セッションがビルド、テスト、進捗、一時アーティファクトを整えた状態で終わるので、次のセッションは同じベースラインから始められます。
### クリーン状態の5つの次元
@@ -76,7 +76,7 @@ Lehmanのソフトウェア進化の法則が教えてくれること:継続
**テストの次元**:すべてのテストは通るか?セッションの前に存在していたテストも含みます——セッションは既存の機能を壊さない責任があります。そして「自分のマシンでは動く」ではなく、CIで検証されるべきです。
-**進捗の次元**:現在の進捗は機械可読なアーティファクトに記録されているか?合格基準と共に完了したサブタスク、現在の状態と共に進行中だが未完了のサブタスク、未着手のサブタスク。良い進捗記録は、セッション起動時の診断時間を60〜80%削減します。
+**進捗の次元**:現在の進捗は機械可読なアーティファクトに記録されているか?合格基準と共に完了したサブタスク、現在の状態と共に進行中だが未完了のサブタスク、未着手のサブタスク。進捗と検証結果をバージョン管理されたファイルに記録すれば、次のセッションが状態を検査できます。
**アーティファクトの次元**:古い、または不明瞭な一時アーティファクトが残っていないか?デバッグログ、一時ファイル、コメントアウトされたコード、TODOマーカー——これらはすべて次のセッションの認知負荷を増やします。
@@ -154,13 +154,13 @@ npm run test # Verify cleanup didn't break anything
## 実際のケース
-agentを使って12週間にわたり開発されたElectronアプリ、2つのアプローチの比較:
+12週間の仮想的な Electron アプリで、2 つのアプローチを比較します:
**クリーンアップ戦略なし**(対照群):週12でビルド合格率 68%、テスト合格率 61%、新セッション起動 60分以上、古いアーティファクト 103。
**クリーンアップ戦略あり**(実験群):各セッション終了時にフルクリーン状態チェック + 週次クリーンアップループ。週12でビルド合格率 97%、テスト合格率 95%、新セッション起動 9分、古いアーティファクト 11。
-週12までに、実験群のビルド合格率は29ポイント高く、テスト合格率は34ポイント高く、新セッション起動時間は85%短縮されました。
+週12の時点で、クリーンアップ戦略がある側はビルドとテストの合格率が起点に近いまま保たれ、新しいセッションも早く作業を始められます。
## 重要なポイント
diff --git a/docs/ja/lectures/lecture-13-loop-engineering/index.md b/docs/ja/lectures/lecture-13-loop-engineering/index.md
index 8e349e7..4c48a4c 100644
--- a/docs/ja/lectures/lecture-13-loop-engineering/index.md
+++ b/docs/ja/lectures/lecture-13-loop-engineering/index.md
@@ -84,11 +84,11 @@
毎回 `/goal` を入力する必要はありません。しかし、それがどこから来て、なぜこのような形になったのかを理解すること——それがループエンジニアリングの核心を理解することです。より複雑なループは、スケジューリング、並列性、隔離、メモリといった部品を、この同じ3つの基本——ゴール、検証、停止条件——の上に追加しているだけです。
-## 2026年6月:3人が1週間で同じ導火線に火をつけた
+## 違う日付、同じ方向
-2026年6月の第1週、コーディングエージェントのインフラを構築していた3人の実践者が——情報を交換することなく——異なる言葉で同じことを言いました。
+同じ考えが、違う場所、違う時期に現れました。
-**Peter Steinberger**(OpenClawの生みの親、[彼の投稿は800万回閲覧されました](https://x.com/steipete/status/2063697162748260627)):「もうコーディングエージェントにプロンプトを与えるべきではない。エージェントにプロンプトを与えるループを設計すべきだ。」
+**Peter Steinberger**(OpenClawの生みの親、[ある投稿で](https://x.com/steipete/status/2063697162748260627)):「もうコーディングエージェントにプロンプトを与えるべきではない。エージェントにプロンプトを与えるループを設計すべきだ。」
**Boris Cherny**(AnthropicのClaude Code責任者、[Acquiredポッドキャストにて](https://x.com/rohanpaul_ai/status/2063289804708835412)):「もうClaudeにプロンプトを与えていない。Claudeにプロンプトを与えて何をするか考えるループを動かしている。私の仕事はループを書くことだ。」
@@ -96,9 +96,9 @@
> **ループエンジニアリングとは、エージェントにプロンプトを与える人としての自分自身を置き換えることです。その代わりにシステムを設計するのです。**
-Chernyは数字を明かしています:30日間連続で、Claude Codeへのすべてのコード貢献はAIによって自律的に行われ——259のマージされたPR、本番コードの80%以上がClaudeによって作成され、オープンエンドなソフトウェアタスクで76%の成功率を記録しました。
+Chernyは[2025-12-27の個人レポート](https://twitter.com/bcherny/status/2004887829252317325)で、30日間で259のPRをマージしたと書いています——497のcommit、4万行の追加、3万8千行の削除——そのすべての行がClaude Code + Opus 4.5によって書かれました。
-3人。1週間。同じ結論。調整したからではありません——インフラが静かに臨界点を越えたからです。エージェントは、監視なしでも些細でないタスクを完了できるほど信頼できるようになっていました。スケジューリングのプリミティブ(`/loop`、`/goal`、cron)がツールに組み込まれるようになりました。1回のエージェント実行のコストが十分に低くなり、タイマーで繰り返し実行することが無駄に思えなくなりました。すべての部品が揃ったとき、それらを組み合わせる動きは、誰にでも同時に明らかになるのです。
+これらの引用は、違う日付、違う形式、違うチームから出てきています。共通する方向は、スケジューリング、検証、停止の判断を、その場のプロンプトからシステムへ移すことです。2026年半ばまでには、エージェントは非自明なタスクを監視なしで完了できるようになり、スケジューリングのプリミティブはツールに組み込まれ、1回の実行はタイマーで繰り返すのに十分安くなっていました。部品が揃えば、組み合わせる人は1人ではありません。
> 出典: [Addy Osmani: Loop Engineering](https://addyosmani.com/blog/loop-engineering/)
@@ -267,7 +267,7 @@ flowchart TD
これはもはや単一のエージェント実行ではありません。毎朝起動し、自ら床を掃き、あなたの注意が必要なものを目の前に置いてくれる、継続的に動作するシステムです。あなたの役割は次のようになります:**受信箱の中身をレビューし、意思決定をし、システムが対処できないパターンを見つけたらスキルとルールを洗練する。**
-Chernyはこのパターンを使って、IDEを一度も開くことなく30日で259のPRをマージしました。OpenAIのエンジニアたちは同じパターンを使って、約100万行のベータ製品を——自分で一行もコードを書くことなく——構築しました。
+Chernyの30日レポートはこのパターンのひとつのデータ点です:259のPR、コードはClaude Code + Opus 4.5が書いたもの。OpenAIの[harnessの記録](https://openai.com/index/harness-engineering/)ももうひとつです:小さなチームが新規リポジトリで5か月間Codexを使い、約100万行、約1,500 PRを報告しました。
## 生成者/評価者の分離:なぜモデルに自分の仕事を採点させてはいけないのか
@@ -293,7 +293,7 @@ Chernyはこのパターンを使って、IDEを一度も開くことなく30日
よく設計され、実際に動いているループがどんなものかを見たいなら、[Karpathyのautoresearch](https://github.com/karpathy/autoresearch) が教科書的な例です。
-2026年3月、Karpathyは630行のPythonプロジェクトをリリースしました。GPUを1つと研究の方向性を与えると、一晩中動き続け——何百ものML学習実験を完了し、本当に改善するものだけを保持します。このプロジェクトはリリース後数日で66,000スター以上を獲得しました。
+2026年3月、Karpathyは[autoresearch](https://github.com/karpathy/autoresearch)をリリースしました。リポジトリは意図的に小さく、`prepare.py` は固定インフラ、`train.py` はエージェントが編集するファイル(約630行)、`program.md` は人間が編集する研究方法論です。GPUを1つと研究の方向性を与えると一晩中動き続けます——各実験の学習実時間予算は固定の5分(起動とコンパイルを除く)で、`val_bpb` を改善した変更だけが残ります。
### 3つのファイル、3つの役割
@@ -343,9 +343,9 @@ flowchart TD
8b --> 9
```
-1時間に約12回の実験を実行します。一晩(8時間)で約100回の実験になります。Karpathy自身は2日間実行しました——約700回の実験です。
+READMEは1時間に約12回、8時間の夜間実行で約100回と見積もっています。5分は学習だけをカバーし、起動とコンパイルは含みません。各ラウンドの残り時間は編集、起動、評価に使われます。Karpathyは、下記のnanochatのラウンドをプライベート版のautoresearchで約2日間自律実行したと報告しています。
-固定の5分実時間予算は重要な設計選択です——エージェントが何を変更しようとも、すべての実験にはまったく同じ時間がかかります。これは、同じ時間予算のもとですべての結果が直接比較可能であることを意味します——「これは長く実行したから良い」という議論は成り立ちません。
+固定の5分の学習予算は重要な設計選択です——エージェントが何を変更しようとも、学習実行は同じ実時間予算を受け取ります。これにより、すべての結果が同じ学習予算のもとで直接比較可能になります。
### 出力:目覚めたときに見るもの
@@ -375,13 +375,9 @@ timestamp commit_hash val_bpb vram_mb description
### 実際に何が見つかったか
-Karpathyの最初の2日間、約700回の実験ランからの結果:
+autoresearchの[第1ラウンド](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)は、nanochatのGPT-2レベルの学習時間を8×H100上で[**2.02時間から1.80時間**](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b)に短縮し、学習時間で約**10.9%**の削減でした。
-- 約700回の試行のうち、約**20個の積み重ね可能な真の改善**が見つかった
-- nanochatのGPT-2レベルの学習時間を、8×H100上で**2.02時間 → 1.80時間**に短縮、約**11%の高速化**
-- 発見内容:学習率調整、オプティマイザーチューニング、活性化関数の交換、アテンションパターンの最適化など
-
-すべての改善が画期的な発見だったわけではありません。ほとんどは積み重ね可能な小さな最適化でした。しかし、これら20個の有効な改善は、人間の研究者なら数週間の手作業がかかったであろうものです——エージェントは48時間でそれを成し遂げました。
+ほとんどは積み重ね可能な小さな最適化でした。有用なのはループそのものです:固定予算、完全な実験ログ、検証済みの改善だけを残すルール。
### 最も物語を語る詳細:ループは英語で書かれている、コードではなく
@@ -399,7 +395,7 @@ Karpathyの最初の2日間、約700回の実験ランからの結果:
### 2. 理解の腐敗
-ループがコードを出荷するのが速いほど、自分自身のコードベースに対する理解が現実から乖離していきます。Chernyのチームはコードの80%がエージェントによって作成されていました——つまり、チームのコードの大部分が人間によって書かれていないのです。ループが生み出したものを読んで使わなければ、理解は継続的に減衰します。**速いループには速い読みが必要です。**
+ループがコードを出荷するのが速いほど、自分自身のコードベースに対する理解が現実から乖離していきます。ループが数百のPRを生み出すと、チームはそのPRを読み、重要なdiffをレビューし、コードを使い続けることで、メンタルモデルを最新に保ちます。**速いループには速い読みが必要です。**
### 3. 認知的降伏
@@ -407,11 +403,11 @@ Karpathyの最初の2日間、約700回の実験ランからの結果:
### 4. トークンの爆発
-ループの各反復はより多くのコンテキストを蓄積します:書かれたコード、遭遇したエラー、下された決定。コンテキスト管理がなければ、プロンプトサイズはターン数のおよそ2乗で成長します。Codexは自動コンテキスト圧縮でこれに対処しています——専用のAPIが古い会話ターンを暗号化されたコンテンツサマリーに圧縮し、冗長な詳細を捨てつつ本質的な知識を保持します。これは後付けではなく、最初のループから対処しなければならないエンジニアリング上の関心事です。
+ループの各反復はより多くのコンテキストを蓄積します:書かれたコード、遭遇したエラー、下された決定。各ラウンドがほぼ固定量の新しい内容を追加するとき、単一のラウンドが見る履歴の長さはラウンド数に対してほぼ線形に伸びます。システムが毎ラウンド全履歴を再処理するなら、N ラウンドの累積入力はほぼ二次関数的に増えます。Codexは自動コンテキスト圧縮でこれに対処しています——専用のAPIが古い会話ターンを暗号化されたコンテンツサマリーに圧縮し、冗長な詳細を捨てつつ本質的な知識を保持します。これは後付けではなく、最初のループから対処しなければならないエンジニアリング上の関心事です。
## 最初のループを構築する
-Stripe規模のパイプライン——週に1,300のPRをマージする——から始める必要はありません。動く最小のものから始めましょう。
+高スループットのパイプラインから始める必要はありません。動く最小のものから始めましょう。
### ステップ1:一つの定期的なタスクを選ぶ
diff --git a/docs/ja/lectures/lecture-14-graph-engineering/index.md b/docs/ja/lectures/lecture-14-graph-engineering/index.md
index d0257f7..8276824 100644
--- a/docs/ja/lectures/lecture-14-graph-engineering/index.md
+++ b/docs/ja/lectures/lecture-14-graph-engineering/index.md
@@ -9,7 +9,7 @@
> 「まだループの話をしているの?それとももうグラフに移ったの?」
-1本のツイートが、1日で約57万回の閲覧を獲得し、月末には約300万回にまで増えました。数時間後、機械学習エンジニアのHamel Husainが『Loop Engineering Is Dead. Enter Graph Engineering』というタイトルの記事を投稿しました——本文は「Stop it」と書かれた動画一枚だけ——それも約68万回の閲覧を獲得しました。
+1本のツイート。数時間後、機械学習エンジニアのHamel Husainが『Loop Engineering Is Dead. Enter Graph Engineering』というタイトルの記事を投稿しました——本文は「Stop it」と書かれた動画一枚だけでした。
さらに興味深いのは:**この2人はどちらも冗談として投稿していたことです。** 一人は業界が6週間ごとに新しい流行語を発明していることを皮肉り、もう一人はそのネタに乗って一搭一宕で応じました。しかし、その冗談はおよそ1週末しか持ちませんでした——コース、ロードマップ、ツールスタックが週末のうちにタイムラインを埋め尽くし、さらに一連の捏造された数字も付いてきました:「精度+18%、コスト-85%」は偽のデータです(18%と85%は確かに存在しますが、化学プラントの配管図に関する論文からのもので、比較基線も根本的に異なります)、「マイクロソフト、スタンフォード、Anthropicが同時にグラフエンジニアリングを発見した」も偽の情報です。事実確認で確認された唯一の「先行者」はJosh Simmonsです:彼の『We Are Entering the Graph Engineering Phase』は7月4日に書かれており、この冗談より丸2週間も早いのです——**この流行を流行らせたのは冗談であり、冗談がその現象を作り出したわけではありません。**
@@ -257,11 +257,11 @@ run(graph, entry={"requirements": "ログインページのバグを修正"}, th
## オープンソースプロジェクト:公開後に出たもの、公開前にあったもの
-先に線を引きます:**Graph Engineeringは2026年7月18日以降にできた名前です。** それ以前にオープンソース化されたフレームワークは、いずれも「Graph Engineering公開後のプロジェクト」ではありません。概念が爆発的に流行った後に、直接この名前で出てきたオープンソースプロジェクトは、2026年8月初時点で、ちゃんと立っているのは一つだけです:
+先に線を引きます:**Graph Engineeringという名前が生まれたのは2026年7月18日以降です。** それ以前にオープンソース化されたフレームワークは、より早い段階のグラフ/ワークフローツールです。名前の上でGraph Engineeringを直接使っているプロジェクトのひとつがGraphARCです:
**概念公開後に出たもの**
-- [GraphArc](https://github.com/CodeGraphContext/grapharc)(2026-08-02):自称「Graph Engineeringの最初のリアルタイム実装」。エージェント実行をログに埋もれたtraceから、一枚の**インタラクティブなリアルタイム編成グラフ**に変えます——各エージェント、各依存関係、各決定ポイントが描かれ、実行前にグラフ全体を可視化し、あなたが確認して(スマホで見ることもできます)から放行します。作者の背景は4000人以上の開発者向けのグラフツール作りで、方向性は「観測可能、デバッグ可能、エンジニアリング可能」です。非常に新しいので、機能はまだ初期段階です。
+- [GraphARC](https://github.com/CodeGraphContext/GraphARC)(2026年7月作成):自称「an end to end implementation of Graph Engineering as proposed by Andrew NG and Peter Steinberger」。初期段階のPythonプロジェクトです。有用なのは、その編成モデルを読んで、この方法が自分のワークフローに合うかどうかを判断することです。
**概念公開前にあったもの(それらはGraph Engineeringと呼ばれていないが、あなたが構築するときに使うのはそれら)**
@@ -325,7 +325,7 @@ run(graph, entry={"requirements": "ログインページのバグを修正"}, th
- [goddaehee: Graph Engineering ファクトチェック(韓国語、2026-07-30)](https://goddaehee.tistory.com/628) — 最も完全なファクトチェック:冗談の起源のタイムライン、偽の数字の分解、LangGraphデータ、Hacker Newsの熱度比較
- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — あの冗談より2週間早い真面目な記事
- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — 公式の応答:「新しいアイデアではなく、既存の方法の最新の名前」;LangGraphの月間ダウンロード6500万+
-- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — 流行語の伝播データ(最初のツイート57.5万回閲覧)
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — この言葉がどのように広まったかについての叙述
- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — 7つの主流オープンソースフレームワークの横断比較:LangGraph、CrewAI、Microsoft Agent Framework、LlamaIndex、Google ADK、OpenAI Agents SDK、Mastra
- [LangGraph公式ドキュメント](https://docs.langchain.com/oss/python/langgraph/graph-api) — "Nodes do the work, edges tell what to do next";ノードとエッジの正確な定義、グラフ構築の第一手リファレンス
- [Anthropic: Building Effective Agents (Dec 2024)](https://www.anthropic.com/engineering/building-effective-agents) — 5つのパターン、描けばそれがグラフ;workflow vs agentの権威ある区別
diff --git a/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/index.md
index 564cb96..bb42d14 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
@@ -11,13 +11,13 @@ AI 세계에 꽤 익숙하다고 자부합니다 — Claude Pro 구독, GPT-4o A
처음 든 생각은 이겁니다: "이 모델은 아직 부족해. 더 좋은 걸로 바꿔야겠어." 잠깐, 지갑을 꺼내기 전에 — 문제가 모델에 있지 않을 수도 있다는 점을 먼저 짚어봐야 합니다.
-숫자를 봅시다. 2025년 말 기준 SWE-bench Verified에서 가장 강력한 코딩 에이전트들은 대략 50-60%의 정확도를 기록합니다. 그것도 명확한 이슈 설명과 기존 테스트 케이스가 갖춰진 엄선된 작업 기준입니다. 막연한 요구사항, 테스트 없음, 암묵적 비즈니스 규칙이 여기저기 흩어진 실제 개발 환경으로 넘어오면 그 수치는 더 낮아집니다.
+숫자를 봅시다. 2025년 9월 29일, Anthropic은 Claude Sonnet 4.5가 [SWE-bench Verified에서 77.2%를 기록했다고 발표했습니다](https://www.anthropic.com/news/claude-sonnet-4-5). 그것도 명확한 이슈 설명과 기존 테스트 케이스가 갖춰진 엄선된 작업 기준입니다. 막연한 요구사항, 테스트 없음, 암묵적 비즈니스 규칙이 여기저기 흩어진 실제 개발 환경으로 넘어오면 그 수치는 더 낮아집니다.
그런데 이 수치들 뒤에는 직관에 반하는 진실이 있습니다.
## 같은 말(馬), 다른 결과
-Anthropic이 통제 실험을 진행했습니다. 동일한 프롬프트("2D 레트로 게임 메이커를 만들어라"), 동일한 모델(Opus 4.5). 첫 번째 실행: 아무런 지원 없이 맨손 — 20분, 9달러, 게임의 핵심 기능은 전혀 작동하지 않았습니다. 두 번째 실행: 완전한 하네스(harness) 적용(플래너 + 제너레이터 + 이밸류에이터 3에이전트 아키텍처) — 6시간, 200달러, 게임을 실제로 플레이할 수 있었습니다.
+Anthropic은 동일한 프롬프트("2D 레트로 게임 메이커를 만들어라")와 동일한 모델(Opus 4.5)을 두 가지 하네스에서 비교했습니다. 첫 번째 실행: 아무런 지원 없이 맨손 — 20분, 9달러. 앱은 열렸지만 엔티티가 입력에 반응하지 않았습니다. 두 번째 실행: 완전한 하네스(harness) 적용(플래너 + 제너레이터 + 이밸류에이터 3에이전트 아키텍처) — 6시간, 200달러. 엔티티는 움직일 수 있었지만 물리가 거칠고 벽이 진행을 막았습니다. [핵심 게임플레이는 작동했지만 앱은 완성되지 않았습니다.](https://www.anthropic.com/engineering/harness-design-long-running-apps)
하네스(harness)란 AI 코딩 에이전트가 안정적으로 동작하도록 환경·상태(state)·검증(verification)·제어를 묶어서 제공하는 외골격(스캐폴딩) 시스템입니다. 모델 가중치 외부에 있는 모든 엔지니어링 인프라가 하네스에 해당합니다.
@@ -43,9 +43,9 @@ OpenAI의 2025년 하네스 엔지니어링 글은 명확하게 밝힙니다:
이 시나리오들을 염두에 두면 다음 개념들이 단순한 전문 용어 이상으로 다가옵니다.
-- **역량 격차(Capability Gap)**: 벤치마크 성능과 실제 작업 성능 사이의 큰 간극. SWE-bench Verified에서 50-60%의 통과율은 실제 이슈의 거의 절반이 해결되지 않는다는 의미입니다.
+- **역량 격차(Capability Gap)**: 벤치마크 성능과 실제 작업 성능 사이의 큰 간극. 벤치마크 작업에는 명확한 이슈 설명과 테스트, 환경이 주어지지만, 실제 작업에서는 대개 직접 마련해야 합니다.
- **하네스(Harness)**: 모델 외부의 모든 것 — 지시사항, 도구, 환경, 상태(state) 관리, 검증(verification) 피드백. 모델 가중치가 아니라면 모두 하네스입니다. 우리가 "마구"라고 부른 것입니다.
-- **하네스 유발 실패(Harness-Induced Failure)**: 모델은 충분한 역량을 갖췄지만 실행 환경에 구조적 결함이 있는 경우. Anthropic의 통제 실험이 이를 이미 증명했습니다.
+- **하네스 유발 실패(Harness-Induced Failure)**: 모델은 충분한 역량을 갖췄지만 실행 환경에 구조적 결함이 있는 경우. 위의 레트로 게임 비교가 그 예입니다.
- **검증 격차(Verification Gap)**: 에이전트가 자신의 산출물(deliverable)에 대해 갖는 자신감과 실제 정확성 사이의 간극. 에이전트가 "완료했다"고 말하지만 완료하지 않은 상태 — 이것이 가장 흔한 실패 유형입니다.
- **진단 루프(Diagnostic Loop)**: 실행 → 실패 관찰 → 특정 하네스 레이어에 귀속 → 해당 레이어 수정 → 재실행. 이것이 하네스 엔지니어링의 핵심 방법론입니다.
- **완료 기준(Definition of Done)**: 기계 검증 가능한 조건들의 집합 — 테스트 통과, 린트 클린, 타입 검사 통과. 명시적인 완료 기준이 없으면 에이전트는 자체 기준을 만들어냅니다.
@@ -76,7 +76,7 @@ OpenAI의 2025년 하네스 엔지니어링 글은 명확하게 밝힙니다:
## 백만 줄 코드 실험
-OpenAI는 2025년에 공격적인 실험을 진행했습니다: Codex를 사용하여 빈 git 저장소에서 완전한 내부 제품을 구축하는 것. 5개월 후 저장소에는 약 100만 줄의 코드가 생성되었습니다 — 애플리케이션 로직, 인프라, 툴링, 문서, 내부 개발 도구 모두 에이전트가 생성했습니다. 세 명의 엔지니어가 Codex를 운영하며 약 1,500개의 PR을 열고 병합했습니다. 1인당 하루 평균 3.5개의 PR.
+OpenAI는 2025년 8월에 공격적인 실험을 진행했습니다: Codex를 사용하여 빈 git 저장소에서 완전한 내부 제품을 구축하는 것. 5개월 후 저장소에는 [약 100만 줄의 코드가 생성되었습니다](https://openai.com/index/harness-engineering/) — 애플리케이션 로직, 인프라, 툴링, 문서, 내부 개발 도구 모두 에이전트가 생성했습니다. 세 명의 엔지니어가 Codex를 운영했고, 팀은 이후 일곱 명으로 늘었습니다. 그 기간 동안 약 1,500개의 PR을 병합했으며, 엔지니어 1인당 하루 평균 3.5개입니다.
핵심 제약: **인간은 코드를 직접 작성하지 않습니다.** 이것은 단순한 실험적 설정이 아니었습니다 — 엔지니어의 주요 업무가 더 이상 코드 작성이 아니라 환경 설계, 의도 표현, 피드백 루프 구축이 될 때 무엇이 달라지는지 파악하도록 강제하기 위한 설계였습니다.
@@ -90,9 +90,9 @@ OpenAI는 2025년에 공격적인 실험을 진행했습니다: Codex를 사용
한 팀이 중간 규모의 Python 웹 앱(FastAPI + PostgreSQL + Redis, 약 15,000줄)에 새 API 엔드포인트를 추가하기 위해 Claude Sonnet을 사용했습니다.
-처음에는 한 문장만 제공했습니다: "/api/v2/users 아래에 사용자 환경설정 엔드포인트를 추가해." 결과는? 에이전트가 컨텍스트(context) 윈도의 40%를 저장소 구조 탐색에 사용했고, 겉으로는 합리적으로 보이지만 프로젝트의 오류 처리 패턴을 따르지 않는 코드를 생성했으며, 구식 SQLAlchemy 문법을 사용했고, 엔드포인트에 런타임 오류가 있는 상태에서 완료를 선언했습니다. 다음 세션은 모든 탐색 작업을 처음부터 다시 해야 했습니다.
+처음에는 한 문장만 제공했습니다: "/api/v2/users 아래에 사용자 환경설정 엔드포인트를 추가해." 결과는? 에이전트가 세션의 상당 부분을 저장소 구조 탐색에 사용했고, 겉으로는 합리적으로 보이지만 프로젝트의 오류 처리 패턴을 따르지 않는 코드를 생성했으며, 구식 SQLAlchemy 문법을 사용했고, 엔드포인트에 런타임 오류가 있는 상태에서 완료를 선언했습니다. 다음 세션은 모든 탐색 작업을 처음부터 다시 해야 했습니다.
-이후 AGENTS.md(프로젝트 아키텍처 및 기술 스택 버전 설명), 명시적 검증 명령어(`pytest tests/api/v2/ && python -m mypy src/`), 아키텍처 결정 기록을 추가했습니다. 같은 모델이 독립적으로 세 번 실행한 모두에서 성공했고, 컨텍스트 효율도 약 60% 향상되었습니다.
+이후 AGENTS.md(프로젝트 아키텍처 및 기술 스택 버전 설명), 명시적 검증 명령어(`pytest tests/api/v2/ && python -m mypy src/`), 아키텍처 결정 기록을 추가했습니다. 같은 모델은 이후 프로젝트 컨벤션을 따르고 실행 가능한 명령으로 작업을 확인했습니다.
모델을 바꾸지 않았습니다. 하네스를 바꿨습니다.
diff --git a/docs/ko/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/ko/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
index 3a49036..2f90d95 100644
--- a/docs/ko/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
+++ b/docs/ko/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -52,7 +52,7 @@ flowchart LR
- **컨텍스트 윈도는 유한합니다**: 어떤 윈도 크기가 주장되더라도(128K, 200K, 1M), 긴 작업은 결국 소진됩니다. 소진 후에는 컴팩션(정보 손실) 또는 리셋(새 세션)이 필요합니다. 둘 다 무언가를 잃습니다.
- **연속성 산출물**: 새 세션이 이전 세션이 중단한 곳에서 명확하게 재개할 수 있도록 해주는 영속화된 상태 파일입니다. 기본 형태: 진행 로그 + 검증(verification) 기록 + 다음 행동. 그 장인의 일지입니다.
-- **재구축 비용(Rebuild cost)**: 새 세션이 실행 가능한 상태에 도달하는 데 필요한 시간. 좋은 하네스는 재구축 비용을 15분에서 3분으로 줄일 수 있습니다.
+- **재구축 비용(Rebuild cost)**: 새 세션이 실행 가능한 상태에 도달하는 데 필요한 시간. 좋은 하네스는 진행 상황, 검증 결과, 다음 행동을 파일에 남겨 새 세션이 기록된 상태에서 시작하게 합니다.
- **드리프트(Drift)**: 에이전트의 이해와 코드 저장소(repository)의 실제 상태 사이의 간극. 모든 세션 경계는 드리프트를 유발하며, 통제하지 않으면 누적됩니다.
- **컨텍스트 불안(Context anxiety)**: Anthropic이 관찰한 현상으로, 에이전트가 인식된 컨텍스트 한계에 접근하면 조기 수렴 행동을 보이며 정보 손실을 피하기 위해 작업을 일찍 마무리합니다. 비합리적인 자원 불안입니다.
- **컴팩션 vs 리셋**: 컴팩션은 동일 세션 내에서 초기 대화를 요약합니다("무엇"은 유지하지만 "왜"를 잃을 수 있음). 리셋은 새 세션을 열어 영속화된 상태에서 재구축합니다(깔끔하지만 산출물 완전성에 의존함).
@@ -160,7 +160,7 @@ LangChain은 같은 gpt-5.2-codex로 89개 작업의 Terminal Bench 2.0 점수
- 컨텍스트 윈도는 유한한 자원입니다. 긴 작업은 세션에 걸쳐 이어지고, 세션은 정보를 잃습니다. 매일 잊어버리는 장인처럼, 이것은 객관적인 현실입니다.
- 해결책은 더 큰 윈도가 아닙니다. 더 나은 상태 영속화입니다. 진행 파일 + 결정 로그 + git 체크포인트로 건망증 장인에게 신뢰할 수 있는 일지를 제공하세요.
- 에이전트를 건망증 있는 엔지니어처럼 취급하세요. "퇴근" 전에 무엇을 했는지, 왜 했는지, 다음은 무엇인지를 적어두세요.
-- 재구축 비용이 핵심 지표입니다. 좋은 하네스는 새 세션이 3분 이내에 실행 가능한 상태에 도달하도록 해야 합니다.
+- 재구축 비용이 핵심 지표입니다. 좋은 하네스는 진행 상황, 검증 결과, 다음 행동을 파일에 남겨 새 세션이 빠르게 회복하게 합니다.
- 혼합 전략: 짧은 작업은 세션 내에서, 긴 작업은 구조화된 산출물로 연속성을 유지합니다.
## 더 읽어보기
diff --git a/docs/ko/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/ko/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
index f914785..1750a12 100644
--- a/docs/ko/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
+++ b/docs/ko/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -37,7 +37,7 @@ flowchart TB
## 혼합했을 때 어떤 일이 벌어지나
-가장 직접적인 문제: 기초가 제대로 굳지 않습니다. 에이전트가 기능 코드에 80%의 노력을 쓰고 인프라 설정에 20%만 임시로 씁니다. 테스트 프레임워크가 설정됐지만 검증되지 않았고, 린트 규칙이 설정됐지만 너무 느슨하고, 진행 파일이 만들어지지 않았습니다. 이 결함은 첫 번째 세션에서 명확하지 않습니다(에이전트가 무엇을 했는지 여전히 기억하기 때문에). 하지만 두 번째 세션에서 표면화됩니다. 새 에이전트는 실행 방법, 테스트 방법, 상황이 어떤지를 알지 못합니다. 기초가 부실하면 건물이 흔들립니다.
+가장 직접적인 문제: 기초가 제대로 굳지 않습니다. 에이전트가 대부분의 노력을 기능 코드에 쓰고 인프라 설정은 뒷전으로 미룹니다. 테스트 프레임워크가 설정됐지만 검증되지 않았고, 린트 규칙이 설정됐지만 너무 느슨하고, 진행 파일이 만들어지지 않았습니다. 이 결함은 첫 번째 세션에서 명확하지 않습니다(에이전트가 무엇을 했는지 여전히 기억하기 때문에). 하지만 두 번째 세션에서 표면화됩니다. 새 에이전트는 실행 방법, 테스트 방법, 상황이 어떤지를 알지 못합니다. 기초가 부실하면 건물이 흔들립니다.
더 숨겨진 비용은 "미검증 누적"입니다. 테스트 프레임워크가 설정되기 전에 작성된 기능 코드는 검증 없는 코드입니다. 마침내 그 코드에 테스트를 추가하러 돌아갈 때, 처음부터 설계가 잘못됐다는 것을 발견할 수도 있습니다. 알았더라면 다르게 구현했을 것입니다. 젖은 콘크리트 위에 타일을 붙이는 것과 같습니다. 바닥이 평평하지 않다는 것을 발견하면 모든 타일을 들어내고 다시 해야 합니다.
@@ -45,7 +45,7 @@ flowchart TB
가장 쉽게 간과하는 문제는 암묵적 가정의 지뢰밭입니다. 에이전트가 초기화 중에 내리는 결정들(어떤 테스트 프레임워크, 디렉터리 구성 방식, 의존성 관리)이 명시적으로 기록되지 않으면 이후 세션이 이러한 선택을 이해할 수 없습니다. 더 나쁜 경우, 이후 세션이 상충되는 선택을 할 수도 있습니다. 첫 번째 건설 팀이 콘크리트 기초를 사용했는데 두 번째 팀은 그것을 모르고 그 위에 나무 말뚝을 박습니다. 기초가 갈라집니다.
-Anthropic의 장기 실행 애플리케이션 개발 연구는 초기화와 구현을 분리할 것을 명시적으로 권장합니다. 그들의 실험 데이터: 전용 초기화 단계를 사용한 프로젝트는 멀티 세션 시나리오에서 혼합 접근법 대비 기능 완료율이 31% 높았습니다. 핵심 통찰은 초기화 단계에 투자한 시간이 이후 3~4세션에서 완전히 회수된다는 것입니다. 기초가 견고할수록 벽이 더 빨리 올라갑니다.
+Anthropic의 장기 실행 에이전트 연구는 [초기화를 별도의 첫 세션으로 분리](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)합니다. initializer가 `init.sh` 스크립트, 진행 파일, 기능 목록, 초기 git commit을 작성하고, 이후 코딩 세션은 그 상태를 읽어 기능 하나를 끝까지 테스트하고 commit한 뒤 진행 파일을 갱신합니다. 기초가 견고할수록 벽이 더 빨리 올라갑니다.
OpenAI의 Codex 하네스 엔지니어링 가이드도 "저장소(repository)를 운영 기록으로" 원칙을 강조합니다. 첫 번째 실행에서 명확한 운영 구조를 확립하거나, 모든 새 세션이 프로젝트 컨벤션을 다시 추론해야 합니다.
diff --git a/docs/ko/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/ko/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
index ce138f3..29b3e45 100644
--- a/docs/ko/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
+++ b/docs/ko/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -26,7 +26,7 @@ Claude Code의 실제 동작이 이를 잘 보여줍니다. "사용자 등록
여섯 단계 후, 하나도 완성되지 않았습니다. 엔드투엔드 검증(verification)은 없고, 미완성 코드 간의 복잡한 결합만 남으며, 다음에 이어받을 세션은 완전히 길을 잃습니다. 마치 여섯 가지 요리를 동시에 하는 사람처럼 — 모든 요리가 냄비 안에 있지만 접시에 담긴 것은 하나도 없습니다. 다 타버립니다.
-Anthropic의 실험 데이터가 이를 직접 뒷받침합니다: "작은 다음 단계" 전략(WIP=1에 해당)을 사용한 에이전트는 넓은 프롬프트를 사용한 에이전트보다 작업 완료율이 37% 높습니다. 더 흥미로운 점은, 에이전트가 생성한 코드 줄 수와 실제 기능 완료 수가 약한 음의 상관관계를 보인다는 것입니다 — 코드를 많이 작성할수록 완성된 기능은 적습니다. 데이터로 증명된 과욕(overreach)입니다.
+Anthropic의 장기 실행 에이전트 가이드는 [코딩 에이전트가 한 번에 기능 하나만 다루도록](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) 요구합니다. 검증하고, commit하고, 진행 상황을 갱신한 뒤 다음으로 넘어갑니다. 넓은 프롬프트는 에이전트가 여러 실마리를 동시에 열게 만들고, 각 실마리는 같은 컨텍스트와 검증 예산을 두고 경쟁합니다.
## WIP=1 워크플로우
diff --git a/docs/ko/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/ko/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
index 225e62b..fb2f8c9 100644
--- a/docs/ko/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
+++ b/docs/ko/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -22,7 +22,7 @@ Claude Code도 Codex도 "완료"가 무엇을 의미하는지 자동으로 알
```
새로운 에이전트 세션이 이 메모에서 다음 질문들에 답할 수 있을까요? "거의 완료"가 무엇을 의미하는지? 장바구니가 통과한 테스트는 무엇인지? 결제를 막는 것이 무엇인지? 모든 답은 "아무도 모른다"입니다. 의사에게 "배가 아픈데, 요즘엔 괜찮아요"라고 하는 것과 같습니다 — 어떤 약을 처방할 수 있을까요?
-결과: 새 세션이 프로젝트 상태를 추론하는 데 20분을 소비하고, 이미 완료된 기능을 재구현할 수도 있습니다. Anthropic의 엔지니어링 데이터에 따르면 좋은 진행 기록은 세션 시작 진단 시간을 60-80% 줄입니다.
+결과: 새 세션이 프로젝트 상태를 추론해야 하고, 이미 완료된 기능을 재구현할 수도 있습니다. Anthropic의 권고는 [진행 상황과 검증 결과를 버전 관리되는 파일에 기록](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)해 다음 세션이 상태를 확인할 수 있게 하라는 것입니다.
## 기능 상태 기계
@@ -111,7 +111,7 @@ flowchart LR
**근간 모드**: 모든 기능이 명확한 상태와 검증 명령을 가집니다. 새 세션은 기능 목록을 읽고 3분 만에 알 수 있습니다: F01-F05는 `passing`, F06은 `active`, F07-F10은 `not_started`. F06에서 직접 이어받고, 재작업 없이 진행합니다.
-정량화된 결과: 구조화된 기능 목록을 사용하는 프로젝트는 자유 형식 추적에 비해 기능 완료율이 45% 높으며, 중복 구현이 전혀 없습니다.
+구조화된 목록은 각 기능의 상태와 검증 명령을 한곳에 모아 두므로, 새 세션은 무엇이 끝났는지 바로 알 수 있습니다.
## 핵심 요점
diff --git a/docs/ko/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/ko/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
index e611693..7d81301 100644
--- a/docs/ko/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
+++ b/docs/ko/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -70,7 +70,7 @@ Anthropic은 2026년 연구에서 더 깊은 실패 패턴을 발견했습니다
| 아키텍처 | 실행 시간 | 비용 | 핵심 기능 작동 여부 |
|----------|-----------|------|---------------------|
| 단일 에이전트(bare run) | 20분 | $9 | 아니오(게임 개체가 입력에 반응 없음) |
-| 세 에이전트(planner + generator + evaluator) | 6시간 | $200 | 예(게임이 완전히 플레이 가능) |
+| 세 에이전트(planner + generator + evaluator) | 6시간 | $200 | 핵심 게임플레이는 작동했지만 물리와 레벨 문제가 남음 |
이것은 정확히 같은 모델(Opus 4.5)에 정확히 같은 프롬프트("2D 레트로 게임 에디터 구축")입니다. 유일한 차이점은 하네스입니다 — "bare 실행"에서 "플래너가 요구사항 확장 → 생성기가 기능별 구현 → 평가기가 Playwright를 사용하여 실제 클릭 테스트 수행"으로 변경된 것입니다.
@@ -119,7 +119,7 @@ OpenAI는 Codex 실천 과정에서 특히 효과적인 패턴을 소개했습
**실제 감점 항목**: (1) 엔드투엔드 흐름 미테스트 — 재설정 링크의 실제 전송 및 검증이 확인된 적 없음. (2) 데이터베이스 마이그레이션이 부분 실행 후 실패하여 스키마 불일치 발생. (3) 대상 환경에서 이메일 서비스 설정 누락.
-**하네스 개입**: 종료 유효성 검사 강제 실행 — (1) 전체 앱을 시작하여 재설정 엔드포인트 접근성 확인; (2) 전체 재설정 흐름 실행; (3) 데이터베이스 상태 일관성 검증. 모든 결함이 세션 내에서 발견되어, 이후 수정 비용의 5-10배를 절약했습니다. 독립적인 채점자가 실제 문제를 발견했습니다.
+**하네스 개입**: 종료 유효성 검사 강제 실행 — (1) 전체 앱을 시작하여 재설정 엔드포인트 접근성 확인; (2) 전체 재설정 흐름 실행; (3) 데이터베이스 상태 일관성 검증. 모든 결함이 세션 내에서 발견되어, 수정 비용이 아직 국소적일 때 해결됩니다. 독립적인 채점자가 실제 문제를 발견했습니다.
## 핵심 요점
diff --git a/docs/ko/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/ko/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
index 4472b4f..bb0486f 100644
--- a/docs/ko/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
+++ b/docs/ko/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -132,7 +132,7 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.rea
| 권한 문제 | 패키징된 환경에서 권한 차이 | 놓침 | 잡음 |
| 오류 전파 | 서비스 계층 예외가 UI 계층까지 도달하지 않음 | 놓침 | 잡음 |
-5개의 결함 모두 엔드투엔드 테스트로 잡혔고, 단위 테스트는 하나도 잡지 못했습니다. 비용은 테스트 시간이 2초에서 15초로 늘어난 것뿐이었습니다—에이전트 워크플로에서는 완전히 수용 가능합니다. 각 파트가 개별적으로 아무리 잘 노래해도, 전체 앙상블 리허설을 이길 수는 없습니다.
+5개의 결함 모두 엔드투엔드 테스트로 잡혔고, 단위 테스트는 하나도 잡지 못했습니다. 엔드투엔드 실행은 더 느리지만, 그 비용은 다섯 개의 경계 결함을 출시까지 끌고 가는 것에 비하면 작습니다. 각 파트가 개별적으로 아무리 잘 노래해도, 전체 앙상블 리허설을 이길 수는 없습니다.
## 핵심 정리
diff --git a/docs/ko/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/ko/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
index d1d718a..6152cfc 100644
--- a/docs/ko/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
+++ b/docs/ko/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -44,7 +44,7 @@ flowchart LR
**재시도가 맹목적인 추측이 된다**: 에이전트가 왜 실패했는지 모르면, 재시도 방향이 무작위입니다. 실제 실패 근본 원인을 무시하고 관련 없는 코드 경로를 고치면서 잘못된 방향으로 반복적으로 시도할 수 있습니다. 모든 맹목적 재시도는 토큰과 시간을 소비합니다.
-**세션 핸드오프(handoff) 정보 절벽**: 완료되지 않은 작업이 다음 세션으로 인계될 때, 관측 가능성 부재는 새 세션이 시스템 상태를 처음부터 진단해야 함을 의미합니다. Anthropic의 장시간 실행 에이전트 관찰에 따르면 이러한 중복 진단이 총 세션 시간의 30-50%를 소비할 수 있습니다.
+**세션 핸드오프(handoff) 정보 절벽**: 완료되지 않은 작업이 다음 세션으로 인계될 때, 관측 가능성 부재는 새 세션이 시스템 상태를 처음부터 진단해야 함을 의미합니다. 새 세션은 코드를 다시 읽고, 명령을 다시 실행하고, 어떤 신호가 중요한지 판단해야 합니다. [버전 관리되는 진행 및 검증 기록](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)은 검사 가능한 상태를 제공합니다.
### 실제 Claude Code 시나리오
@@ -54,7 +54,7 @@ flowchart LR
**완전한 관측 가능성으로**: 계획자가 스프린트 계약을 출력합니다—수정할 컴포넌트, 각각의 검증 기준, 제외 사항(인쇄 스타일 처리 안 함)을 나열합니다. 생성자가 계약에 따라 구현합니다. 런타임 관측 가능성이 각 컴포넌트의 스타일 로딩 및 적용 프로세스를 기록합니다. 평가자가 채점 루브릭을 사용해 차원별로 평가하며, 구체적인 증거를 인용합니다. 한 번의 반복으로 고품질 결과가 나오고, 약 15분이 소요됩니다.
-3배의 효율성 차이. 유일한 변화는 관측 가능성입니다.
+차이는 계약과 증거가 에이전트 머리 밖에 있느냐에서 나옵니다.
### 에이전트가 이것을 스스로 해결할 수 없는 이유
@@ -128,7 +128,7 @@ flowchart LR
- 채점 루브릭이 차원별 구조화된 평가를 제공
- 한 번의 반복으로 고품질 결과, 15분
-3배 효율성 향상, 더 안정적인 품질, 재현 가능한 평가.
+관측 가능성이 있으면 품질이 더 안정적이고 평가가 재현 가능해집니다.
## 핵심 정리
@@ -136,7 +136,7 @@ flowchart LR
- **두 관측 가능성 계층이 모두 필수적입니다**—런타임 신호는 "무슨 일이 있었는가"를 설명하고, 프로세스 산출물은 "왜 그렇게 했는가"를 설명합니다.
- **스프린트 계약은 사전 정렬(front-load alignment)을 수행합니다**—"생성자가 구축한 것을 평가자가 예측 가능한 이유로 즉시 거부하는" 상황을 방지합니다.
- **채점 루브릭은 평가를 재현 가능하게 만듭니다**—서로 다른 평가자가 동일한 출력에 대해 유사한 점수를 부여합니다.
-- **관측 가능성 부재는 세션 시간의 30-50%를 중복 진단에 낭비합니다.**
+- **관측 가능성은 모호한 거부를 구체적이고 고칠 수 있는 결함으로 바꿉니다.**
## 더 읽을거리
diff --git a/docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
index ae45c83..c3771ee 100644
--- a/docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
+++ b/docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -54,7 +54,7 @@ flowchart LR
소프트웨어 진화의 Lehman 법칙에 따르면 지속적으로 변경되는 시스템은 능동적으로 관리되지 않으면 복잡성이 불가피하게 증가합니다. 이것은 AI 코딩 에이전트에게 특히 사실입니다—매 세션마다 변경 사항을 도입하고, 종료 시 정리하지 않으면 기술 부채가 기하급수적으로 쌓입니다.
-실제 데이터가 이를 말해줍니다. 정리 전략 없이 12주간 에이전트로 개발된 프로젝트:
+12주짜리 가상 프로젝트를 가정하고, 다음과 같은 값을 생각해 봅시다:
- 1주차: 빌드 통과율 100%, 테스트 통과율 100%, 새 세션 시작 5분
- 4주차: 빌드 95%, 테스트 92%, 시작 15분
@@ -66,7 +66,7 @@ flowchart LR
- 1주차: 100%, 100%, 5분
- 12주차: 97%, 95%, 9분
-12주 후: 빌드 통과율 29퍼센트포인트 차이, 새 세션 시작 시간 85% 차이. 이것은 이론이 아닙니다—관찰된 차이입니다.
+주간 클린업 루프가 시작 상태를 안정적으로 유지합니다. 각 세션이 빌드, 테스트, 진행 상황, 임시 산출물을 정리한 채 끝나므로 다음 세션이 같은 기준선에서 시작합니다.
### 클린 상태의 다섯 가지 차원
@@ -76,7 +76,7 @@ flowchart LR
**테스트 차원**: 모든 테스트가 통과하는가? 세션 전에 존재했던 테스트도 포함해서입니다—세션은 기존 기능을 깨뜨리지 않을 책임이 있습니다. 그리고 "내 기계에서는 작동해"가 아니라 CI에서 검증되어야 합니다.
-**진행 상황 차원**: 현재 진행 상황이 기계가 읽을 수 있는 산출물에 기록되어 있는가? 통과 기준이 있는 완료된 하위 작업, 현재 상태가 있는 진행 중이지만 완료되지 않은 하위 작업, 아직 시작되지 않은 하위 작업. 좋은 진행 상황 기록은 세션 시작 진단 시간의 60-80%를 줄입니다.
+**진행 상황 차원**: 현재 진행 상황이 기계가 읽을 수 있는 산출물에 기록되어 있는가? 통과 기준이 있는 완료된 하위 작업, 현재 상태가 있는 진행 중이지만 완료되지 않은 하위 작업, 아직 시작되지 않은 하위 작업. 진행 상황과 검증 결과를 버전 관리되는 파일에 기록하면 다음 세션이 상태를 확인할 수 있습니다.
**산출물 차원**: 오래되거나 모호한 임시 산출물이 있는가? 디버그 로그, 임시 파일, 주석 처리된 코드, TODO 마커—이 모두가 다음 세션의 인지 부하를 높입니다.
@@ -160,7 +160,7 @@ npm run test # 정리가 아무것도 깨뜨리지 않았는지 확인
**정리 전략으로** (실험군): 모든 세션 종료 시 완전한 클린 상태 검사 + 주간 클린업 루프. 12주차, 빌드 통과율 97%, 테스트 통과율 95%, 새 세션 시작 9분, 오래된 산출물 11개.
-12주차에 실험군의 빌드 통과율은 29퍼센트포인트 높고, 테스트 통과율은 34포인트 높으며, 새 세션 시작 시간은 85% 낮습니다.
+12주차에도 정리 전략이 있는 쪽은 빌드와 테스트 통과율이 시작점에 가깝고, 새 세션도 빠르게 시작하며, 오래된 산출물이 적습니다. 세션마다 몇 분을 더 쓰지만, 그 대가로 다음 세션이 신뢰할 수 있는 시작 상태를 얻습니다.
## 핵심 정리
diff --git a/docs/ko/lectures/lecture-13-loop-engineering/index.md b/docs/ko/lectures/lecture-13-loop-engineering/index.md
index 2be56d7..d56ddc3 100644
--- a/docs/ko/lectures/lecture-13-loop-engineering/index.md
+++ b/docs/ko/lectures/lecture-13-loop-engineering/index.md
@@ -84,11 +84,11 @@
매번 `/goal`을 입력할 필요는 없습니다. 하지만 그것이 어디서 왔고 왜 그런 모습인지 이해하는 것 — 그것이 루프 엔지니어링의 핵심을 이해하는 것입니다. 더 복잡한 루프는 스케줄링, 병렬성, 격리, 메모리 같은 부품을 이 세 가지 기본 요소 위에 얹을 뿐입니다: 목표, 검증, 중단 조건.
-## 2026년 6월: 세 사람이 한 주 동안 같은 성냥을 붙였다
+## 다른 날짜, 같은 방향
-2026년 6월 첫째 주, 코딩 에이전트 인프라를 구축하는 세 명의 실무자가 — 서로 의견을 나누지 않고 — 다른 말로 같은 말을 했습니다.
+같은 아이디어가 서로 다른 곳에서, 서로 다른 시점에 나타났습니다.
-**Peter Steinberger** (OpenClaw 창시자, [그의 글은 8백만 뷰를 돌파](https://x.com/steipete/status/2063697162748260627)): "더 이상 코딩 에이전트에게 프롬프트해서는 안 됩니다. 에이전트에게 프롬프트하는 루프를 설계해야 합니다."
+**Peter Steinberger** (OpenClaw 창시자, [한 게시물에서](https://x.com/steipete/status/2063697162748260627)): "더 이상 코딩 에이전트에게 프롬프트해서는 안 됩니다. 에이전트에게 프롬프트하는 루프를 설계해야 합니다."
**Boris Cherny** (Anthropic의 Claude Code 책임자, [Acquired 팟캐스트에서](https://x.com/rohanpaul_ai/status/2063289804708835412)): "더 이상 Claude에게 프롬프트하지 않습니다. Claude에게 프롬프트하고 무엇을 해야 할지 알아내는 루프를 돌리고 있습니다. 제 일은 루프를 쓰는 것입니다."
@@ -96,9 +96,9 @@
> **루프 엔지니어링은 에이전트에게 프롬프트하는 사람으로서의 자신을 대체하는 것입니다. 대신 그 일을 하는 시스템을 설계하는 것입니다.**
-Cherny는 수치를 공개했습니다: 연속 30일 이상, Claude Code에 대한 모든 코드 기여는 AI가 자율적으로 수행했습니다 — 259개의 병합된 PR, 프로덕션 코드의 80% 이상이 Claude가 작성했으며, 개방형 소프트웨어 작업에서 76%의 성공률을 보였습니다.
+Cherny는 [2025-12-27 개인 보고서](https://twitter.com/bcherny/status/2004887829252317325)에서 30일 동안 259개의 PR을 병합했다고 썼습니다 — 497개의 커밋, 40,000줄 추가, 38,000줄 삭제 — 그리고 모든 줄이 Claude Code + Opus 4.5로 작성되었습니다.
-세 사람. 한 주. 같은 결론. 조율해서가 아니라 — 인프라가 조용히 임계점을 넘었기 때문입니다. 에이전트는 감독 없이도 사소하지 않은 작업을 완료할 만큼 충분히 신뢰할 수 있게 되었습니다. 스케줄링 프리미티브(`/loop`, `/goal`, cron)가 이제 도구에 내장되었습니다. 단일 에이전트 실행 비용은 타이머로 반복해서 실행하는 것이 낭비로 보이지 않을 만큼 충분히 낮아졌습니다. 모든 부품이 갖춰지면, 그것들을 결합하는 움직임은 모두에게 동시에 당연해집니다.
+인용문들은 서로 다른 날짜, 형식, 팀에서 나왔습니다. 이들이 공유하는 방향은 스케줄링, 검증, 중단 판단을 순간순간의 프롬프트에서 꺼내 시스템으로 옮기는 것입니다. 2026년 중반이 되자 에이전트는 사소하지 않은 작업을 감독 없이 끝낼 수 있었고, 스케줄링 프리미티브는 도구에 내장되었으며, 한 번의 실행 비용은 타이머로 반복해도 아깝지 않을 만큼 낮아졌습니다. 부품이 갖춰지면 그것을 조립하는 사람은 한 명이 아닙니다.
> 출처: [Addy Osmani: Loop Engineering](https://addyosmani.com/blog/loop-engineering/)
@@ -267,7 +267,7 @@ flowchart TD
이것은 더 이상 단일 에이전트 실행이 아닙니다. 매일 아침 깨어나서 스스로 정리하고 여러분의 주의가 필요한 것들을 앞에 내놓는, 지속적으로 작동하는 시스템입니다. 여러분의 역할은 다음과 같습니다: **받은 편지함 내용을 검토하고, 결정을 내리고, 시스템이 처리할 수 없는 패턴을 발견하면 스킬과 규칙을 개선하는 것.**
-Cherny는 이 패턴을 사용하여 IDE를 한 번도 열지 않고 30일 만에 259개의 PR을 병합했습니다. OpenAI 엔지니어들은 같은 패턴을 사용하여 대략 백만 줄 규모의 베타 제품을 손으로 — 직접 코드를 한 줄도 쓰지 않고 구축했습니다.
+Cherny의 30일 보고서는 이 패턴의 한 데이터 포인트입니다: 259개의 PR, 코드는 Claude Code + Opus 4.5가 작성했습니다. OpenAI의 [하네스 기록](https://openai.com/index/harness-engineering/)은 또 다른 데이터 포인트입니다: 작은 팀이 새 저장소에서 Codex로 다섯 달 동안 작업해 약 100만 줄과 약 1,500개의 PR을 보고했습니다.
## 생성자/평가자 분리: 왜 모델이 자신의 작업을 채점하게 하면 안 되는가
@@ -293,7 +293,7 @@ Cherny는 이 패턴을 사용하여 IDE를 한 번도 열지 않고 30일 만
잘 설계되고 실제로 돌아가는 루프가 어떤 모습인지 보고 싶다면, [Karpathy의 autoresearch](https://github.com/karpathy/autoresearch)가 교과서적인 예시입니다.
-2026년 3월, Karpathy는 630줄짜리 Python 프로젝트를 공개했습니다. GPU 하나와 연구 방향만 주면 밤새도록 실행됩니다 — 수백 개의 ML 훈련 실험을 완료하고, 진정으로 개선된 것만 남깁니다. 이 프로젝트는 공개된 지 며칠 만에 66,000개 이상의 스타를 받았습니다.
+2026년 3월, Karpathy는 [autoresearch](https://github.com/karpathy/autoresearch)를 공개했습니다. 저장소는 의도적으로 작습니다: `prepare.py`는 고정된 인프라, `train.py`는 에이전트가 편집하는 파일(약 630줄), `program.md`는 사람이 편집하는 연구 방법론입니다. GPU 하나와 연구 방향만 주면 밤새도록 실행됩니다 — 각 실험은 고정된 5분 훈련 벽시계 예산(시작과 컴파일 제외)을 받고, `val_bpb`를 개선하는 변경만 유지됩니다.
### 세 개의 파일, 세 가지 역할
@@ -343,9 +343,9 @@ flowchart TD
8b --> 9
```
-대략 시간당 12개의 실험을 실행합니다. 밤새 실행(8시간)하면 약 100개의 실험이 됩니다. Karpathy 본인은 2일 동안 실행했습니다 — 약 700개의 실험.
+README는 시간당 약 12개의 실험, 8시간 야간 실행에서 약 100개로 추정합니다. 5분 예산은 훈련에만 적용되고 시작과 컴파일은 제외됩니다. 매 라운드의 나머지 시간은 편집, 실행, 평가에 쓰입니다. Karpathy는 아래에 설명된 nanochat 라운드를 위해 비공개 버전의 autoresearch를 약 이틀 동안 자율 실행했다고 보고했습니다.
-고정된 5분 실제 시간 예산은 핵심 설계 선택입니다 — 에이전트가 무엇을 바꾸든, 모든 실험은 정확히 같은 시간이 걸립니다. 이것은 모든 결과가 같은 시간 예산 하에서 직접 비교 가능하다는 것을 의미합니다 — "이건 더 오래 돌렸으니 더 좋아" 같은 논쟁이 없습니다.
+고정된 5분 훈련 예산은 핵심 설계 선택입니다 — 에이전트가 무엇을 바꾸든 훈련 실행은 같은 벽시계 예산을 받습니다. 따라서 모든 결과가 같은 훈련 예산 아래에서 직접 비교 가능합니다.
### 출력: 잠에서 깼을 때 보이는 것
@@ -375,13 +375,9 @@ timestamp commit_hash val_bpb vram_mb description
### 실제로 무엇을 발견했는가
-Karpathy의 초기 2일, 약 700개 실험 실행 결과:
+autoresearch [1라운드](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)는 nanochat의 8×H100에서의 GPT-2 수준 훈련 시간을 [**2.02시간에서 1.80시간으로**](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b) 줄여 훈련 시간을 약 **10.9%** 단축했습니다.
-- 약 700번의 시도 중, **누적 가능한 실제 개선 사항이 약 20개** 발견되었습니다
-- nanochat의 GPT-2 수준 훈련 시간을 8×H100에서 **2.02시간 → 1.80시간**으로 단축했으며, 약 **11% 더 빨라졌습니다**
-- 발견 사항에는 학습률 조정, 옵티마이저 튜닝, 활성화 함수 교체, 어텐션 패턴 최적화 등이 포함되었습니다
-
-모든 개선 사항이 충격적인 발견이었을까요? 아닙니다. 대부분은 누적되는 작은 최적화였습니다. 하지만 그 20개의 유효한 개선 사항은 인간 연구자가 몇 주 동안 수동으로 작업했을 것입니다 — 에이전트는 48시간 만에 해냈습니다.
+대부분은 누적되는 작은 최적화였습니다. 유용한 것은 루프 자체입니다: 고정 예산, 완전한 실험 로그, 그리고 검증된 개선만 남기는 규칙입니다.
### 가장 시사하는 디테일: 루프는 코드가 아니라 영어로 쓰여 있다
@@ -399,7 +395,7 @@ Karpathy의 초기 2일, 약 700개 실험 실행 결과:
### 2. 이해 부패
-루프가 코드를 더 빨리 배포할수록, 여러분의 자신의 코드베이스에 대한 이해는 현실에서 더 멀어집니다. Cherny의 팀은 코드의 80%를 에이전트가 작성했습니다 — 팀 코드의 대부분이 사람이 작성하지 않았다는 의미입니다. 루프가 생산하는 것을 읽고 사용하지 않으면, 여러분의 이해는 지속적으로 쇠퇴합니다. **빠른 루프는 빠른 읽기를 요구합니다.**
+루프가 코드를 더 빨리 배포할수록, 여러분의 자신의 코드베이스에 대한 이해는 현실에서 더 멀어집니다. 루프가 수백 개의 PR을 병합하면, 팀은 그 PR들을 읽고, 중요한 diff를 리뷰하고, 코드를 계속 사용합니다. 그래서 팀의 멘탈 모델이 코드를 따라갑니다. **빠른 루프는 빠른 읽기를 요구합니다.**
### 3. 인지 항복
@@ -407,11 +403,11 @@ Karpathy의 초기 2일, 약 700개 실험 실행 결과:
### 4. 토큰 폭발
-루프의 매 반복은 더 많은 컨텍스트를 축적합니다: 작성된 코드, 마주친 오류, 내려진 결정. 컨텍스트 관리가 없으면, 프롬프트 크기는 턴 수에 따라 대략 2차 함수적으로 증가합니다. Codex는 자동 컨텍스트 압축으로 이것을 해결합니다 — 전용 API가 이전 대화 턴을 암호화된 내용 요약으로 압축하여, 필수 지식은 유지하면서 중복된 세부 사항은 버립니다. 이것은 나중에 덧붙이는 것이 아니라, 첫 루프부터 다루어야 하는 엔지니어링 문제입니다.
+루프의 매 반복은 더 많은 컨텍스트를 축적합니다: 작성된 코드, 마주친 오류, 내려진 결정. 매 라운드가 대략 고정된 양의 새 내용을 추가하면, 한 라운드가 보는 히스토리 길이는 라운드 수에 따라 대략 선형으로 늘어납니다. 시스템이 매 라운드 전체 히스토리를 다시 처리하면, N개 라운드의 누적 입력은 대략 2차 함수적으로 증가합니다. Codex는 자동 컨텍스트 압축으로 이것을 해결합니다 — 전용 API가 이전 대화 턴을 암호화된 내용 요약으로 압축하여, 필수 지식은 유지하면서 중복된 세부 사항은 버립니다. 이것은 나중에 덧붙이는 것이 아니라, 첫 루프부터 다루어야 하는 엔지니어링 문제입니다.
## 첫 번째 루프 구축하기
-Stripe 규모의 파이프라인이 주 1,300개의 PR을 병합하는 것부터 시작할 필요는 없습니다. 작동하는 가장 작은 것부터 시작하세요.
+처리량이 높은 파이프라인부터 시작할 필요는 없습니다. 작동하는 가장 작은 것부터 시작하세요.
### 1단계: 반복적인 작업 하나 고르기
diff --git a/docs/ko/lectures/lecture-14-graph-engineering/index.md b/docs/ko/lectures/lecture-14-graph-engineering/index.md
index 86e8882..c17f901 100644
--- a/docs/ko/lectures/lecture-14-graph-engineering/index.md
+++ b/docs/ko/lectures/lecture-14-graph-engineering/index.md
@@ -9,7 +9,7 @@
> "우리는 아직 Loop을 이야기하고 있는가, 아니면 이미 Graph로 넘어갔는가?"
-트윗 하나가 하루 만에 약 57만 뷰를 얻었고, 월말에는 약 300만 뷰까지 늘었습니다. 몇 시간 뒤 머신러닝 엔지니어 Hamel Husain은 《Loop Engineering Is Dead. Enter Graph Engineering》이라는 제목의 글을 올렸습니다 — 본문은 "Stop it"이라고 쓰인 움짤 하나뿐이었습니다 — 또 약 68만 뷰를 얻었습니다.
+트윗 하나. 몇 시간 뒤 머신러닝 엔지니어 Hamel Husain은 《Loop Engineering Is Dead. Enter Graph Engineering》이라는 제목의 글을 올렸습니다 — 본문은 "Stop it"이라고 쓰인 움짤 하나뿐이었습니다.
더 흥미로운 점은 이렇습니다: **두 사람 모두 농담으로 올린 것입니다.** 한쪽은 이 업계가 6주마다 새 용어를 만들어낸다는 것을 풍자했고, 한쪽은 그 밈에 맞장구를 쳤습니다. 하지만 농담은 겨우 한 주말 정도만 살아남았습니다 — 강의, 로드맵, 도구 스택이 주말이 끝나기 전에 타임라인을 가득 채웠고, 그 뒤에 지어낸 숫자들도 따라왔습니다: "정확도 +18%, 비용 -85%"는 가짜 데이터입니다(18%와 85%는 실제로 존재하지만, 화학 배관 도면에 관한 논문에서 나온 것이며 비교 기준도 완전히 다릅니다), "마이크로소프트, 스탠포드, Anthropic이 동시에 그래프 엔지니어링을 발견했다"는 것도 가짜 뉴스입니다. 사실 확인을 통해 확인된 유일한 "선행자"는 Josh Simmons입니다. 그의 《We Are Entering the Graph Engineering Phase》는 7월 4일에 쓰였는데, 이 농담보다 꼭 2주 앞선 것입니다 — **농담이 이 일을 유행하게 만든 것이지, 농담이 이 일을 만들어낸 것이 아닙니다.**
@@ -257,11 +257,11 @@ run(graph, entry={"requirements": "로그인 페이지 버그 수정"}, thread="
## 오픈소스 프로젝트: 출시 후에 생긴 것, 출시 전에 있던 것
-먼저 선을 그어 봅시다: **Graph Engineering은 2026년 7월 18일 이후에야 생긴 이름입니다.** 그 전에 오픈소스로 출시된 프레임워크는 "Graph Engineering 출시 후의 프로젝트"가 아닙니다. 개념이 폭발적으로 뜬 뒤 정말로 이 이름으로 직접 나타난 오픈소스 프로젝트는, 2026년 8월 초 기준으로 근거 있는 것이 하나뿐입니다:
+먼저 선을 그어 봅시다: **Graph Engineering은 2026년 7월 18일 이후에야 생긴 이름입니다.** 그 전에 오픈소스로 출시된 프레임워크는 "Graph Engineering 출시 후의 프로젝트"가 아닙니다. 이 이름을 직접 사용하는 프로젝트 하나가 GraphARC입니다:
**개념 출시 후에 생긴 것**
-- [GraphArc](https://github.com/CodeGraphContext/grapharc)(2026-08-02): 스스로 "Graph Engineering의 첫 번째 실시간 구현"이라고 부릅니다. 에이전트 실행을 로그에 묻혀 있던 trace에서 **상호작용 가능한 실시간 오케스트레이션 그래프**로 바꿉니다 — 각 엔진, 각 의존성, 각 결정 지점을 그려서, 실행 전에 전체 그래프를 시각화하고, 당신이 확인한(심지어 휴대폰으로 볼 수도 있는) 뒤에야 통과시킵니다. 저자는 4,000+ 개발자용 그래프 도구를 만든 배경이며, 방향은 "관측 가능, 디버그 가능, 공학화 가능"입니다. 아주 새롭고, 기능은 아직 초기 단계입니다.
+- [GraphARC](https://github.com/CodeGraphContext/GraphARC)(2026년 7월 생성): 스스로 "an end to end implementation of Graph Engineering as proposed by Andrew NG and Peter Steinberger"라고 설명합니다. 초기 단계의 Python 프로젝트입니다. 유용한 방법은 그 오케스트레이션 모델을 읽고 이 접근이 자신의 워크플로에 맞는지 판단하는 것입니다.
**개념 출시 전에 있던 것 (Graph Engineering이라고 부르지 않지만, 당신이 구축할 때 쓸 것은 바로 이것들)**
@@ -325,7 +325,7 @@ agent를 시작하는 것은 버튼 하나, 한 마디입니다. 그러나 agent
- [goddaehee: Graph Engineering 사실 확인 (한국어, 2026-07-30)](https://goddaehee.tistory.com/628) — 가장 완전한 사실 확인: 농담 기원 타임라인, 가짜 숫자 분해, LangGraph 데이터, Hacker News 인기 비교
- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — 그 농담보다 2주 앞선 진지한 글
- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — 공식 응답: "새 아이디어가 아니라 기존 방법의 최신 이름"; LangGraph 월 다운로드 6,500만+
-- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — 뜨거운 용어의 전파 데이터(첫 트윗 57.5만 뷰)
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — 이 용어가 어떻게 퍼졌는지에 대한 서술
- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — 일곱 개 주요 오픈소스 프레임워크의 가로 비교: LangGraph, CrewAI, Microsoft Agent Framework, LlamaIndex, Google ADK, OpenAI Agents SDK, Mastra
- [LangGraph 공식 문서](https://docs.langchain.com/oss/python/langgraph/graph-api) — "Nodes do the work, edges tell what to do next"; 노드와 엣지의 정확한 정의, 그래프 구축의 1차 참조
- [Anthropic: Building Effective Agents (Dec 2024)](https://www.anthropic.com/engineering/building-effective-agents) — 다섯 가지 패턴, 그리면 그래프; workflow vs agent의 권위 있는 구분
diff --git a/docs/pt-BR/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/pt-BR/lectures/lecture-01-why-capable-agents-still-fail/index.md
index 562db7e..5756032 100644
--- a/docs/pt-BR/lectures/lecture-01-why-capable-agents-still-fail/index.md
+++ b/docs/pt-BR/lectures/lecture-01-why-capable-agents-still-fail/index.md
@@ -5,13 +5,13 @@
# Aula 01. Modelos Fortes Não Significam Execução Confiável
-No final de 2025, os agentes de programação mais fortes no SWE-bench Verified alcançam aproximadamente uma taxa de sucesso entre 50% e 60%. À primeira vista, esse número parece razoável — mas ainda não comemore. Essas são tarefas cuidadosamente selecionadas, com descrições claras de problemas e testes prontos. Agora entregue ao agente os requisitos do dia a dia — especificações vagas, ausência de testes existentes, regras de negócio implícitas espalhadas pela base de código — e essa taxa cai ainda mais. Você delega uma tarefa cheio de confiança, o agente trabalha por 20 minutos e responde “tudo pronto”, mas ao olhar o código: ele adicionou a funcionalidade e quebrou os testes, corrigiu um bug e introduziu outros, e ainda nem era exatamente o que você pediu.
+Em 29 de setembro de 2025, a Anthropic reportou o Claude Sonnet 4.5 com [77,2% no SWE-bench Verified](https://www.anthropic.com/news/claude-sonnet-4-5). À primeira vista, esse número parece razoável — mas ainda não comemore. Essas são tarefas cuidadosamente selecionadas, com descrições claras de problemas e testes prontos. Agora entregue ao agente os requisitos do dia a dia — especificações vagas, ausência de testes existentes, regras de negócio implícitas espalhadas pela base de código — e essa taxa cai ainda mais. Você delega uma tarefa cheio de confiança, o agente trabalha por 20 minutos e responde “tudo pronto”, mas ao olhar o código: ele adicionou a funcionalidade e quebrou os testes, corrigiu um bug e introduziu outros, e ainda nem era exatamente o que você pediu.
Quando isso acontece, a primeira reação da maioria das pessoas é: “o modelo não é bom o suficiente — vou tentar um mais caro”. Antes de abrir a carteira, considere que talvez o problema não seja o modelo.
## Mesmo Cavalo, Destinos Diferentes
-A Anthropic realizou um experimento controlado que ilustra perfeitamente esse ponto. Mesmo prompt (“crie um editor de jogos retrô 2D”), mesmo modelo (Opus 4.5), duas execuções. Primeira execução: ambiente cru, sem suporte — 20 minutos, US$9, e as funcionalidades principais do jogo não funcionavam. Segunda execução: harness completo — arquitetura de três agentes com planejador, gerador e avaliador — 6 horas, US$200, e o jogo ficou totalmente jogável.
+A Anthropic comparou o mesmo prompt (“crie um editor de jogos retrô 2D”) e o mesmo modelo (Opus 4.5) sob dois harnesses. Primeira execução: ambiente cru, sem suporte — 20 minutos, US$9; o aplicativo abria, mas as entidades não respondiam à entrada. Segunda execução: harness completo — arquitetura de três agentes com planejador, gerador e avaliador — 6 horas, US$200; era possível mover uma entidade, mas a física ainda tinha imperfeições e uma parede bloqueava o progresso. [A jogabilidade central funcionava; o aplicativo não estava concluído.](https://www.anthropic.com/engineering/harness-design-long-running-apps)
Eles não mudaram o modelo. Opus 4.5 continuava sendo Opus 4.5. O que mudou foi o equipamento.
@@ -31,9 +31,9 @@ Os modos de falha específicos se resumem basicamente a alguns pontos:
Com os cenários acima em mente, estes conceitos deixam de ser apenas jargões:
-- **Capability Gap**: O enorme abismo entre o desempenho do modelo em benchmarks e o desempenho em tarefas reais. Uma taxa de sucesso de 50–60% no SWE-bench Verified significa que quase metade dos problemas reais continuam sem solução.
+- **Capability Gap**: O enorme abismo entre o desempenho do modelo em benchmarks e o desempenho em tarefas reais. Tarefas de benchmark vêm com descrições claras de problemas, testes e um ambiente; tarefas reais muitas vezes exigem que você forneça tudo isso.
- **Harness**: Tudo que está fora do modelo — instruções, ferramentas, ambiente, gerenciamento de estado e feedback de verificação. Se não são os pesos do modelo, então é harness. O que chamamos anteriormente de “equipamento”.
-- **Harness-Induced Failure**: O modelo possui capacidade suficiente, mas o ambiente de execução possui defeitos estruturais. O experimento controlado da Anthropic já demonstrou isso.
+- **Harness-Induced Failure**: O modelo possui capacidade suficiente, mas o ambiente de execução possui defeitos estruturais. A comparação com o jogo retrô acima é um exemplo.
- **Verification Gap**: A diferença entre a confiança do agente em sua resposta e a correção real. O agente diz “terminei” quando ainda não terminou — esse é o modo de falha mais comum.
- **Diagnostic Loop**: Executar, observar a falha, atribuir a uma camada específica do harness, corrigir essa camada e executar novamente. Essa é a metodologia central da harness engineering.
- **Definition of Done**: Um conjunto de condições verificáveis por comando — testes passando, lint limpo, type checks aprovados. Sem uma definição explícita de conclusão, o agente inventará a própria definição.
@@ -60,7 +60,7 @@ A partir daí, construa um loop de diagnóstico. Não trate falhas como “o mod
## O Experimento do Milhão de Linhas
-Em 2025, três engenheiros da OpenAI iniciaram um experimento. As regras eram simples: eles não escreveriam código manualmente — apenas o Codex escreveria. Partindo de um repositório Git vazio, cinco meses depois o projeto continha aproximadamente um milhão de linhas de código. Lógica da aplicação, infraestrutura, ferramentas, documentação — tudo gerado por agentes. Os três engenheiros abriram um total de 1.500 PRs, média de 3,5 PRs por pessoa por dia.
+Em agosto de 2025, três engenheiros da OpenAI iniciaram um experimento. As regras eram simples: eles não escreveriam código manualmente — apenas o Codex escreveria. Partindo de um repositório Git vazio, [cinco meses depois o repositório continha aproximadamente um milhão de linhas de código](https://openai.com/index/harness-engineering/). Lógica da aplicação, infraestrutura, ferramentas, documentação — tudo gerado por agentes. A equipe depois cresceu para sete engenheiros; no período, foram mesclados cerca de 1.500 PRs, uma média de 3,5 por engenheiro por dia.
O progresso inicial foi surpreendentemente lento. O Codex não era ruim — apenas não possuía ferramentas e estruturas suficientes para avançar em direção a objetivos de alto nível. Aos poucos, os engenheiros descobriram um padrão: quebrar grandes objetivos em pequenos blocos — design, código, revisão, testes — deixar o agente montar esses blocos individualmente e depois combiná-los em tarefas mais complexas. Sempre que algo dava errado, o problema quase nunca era “não estamos tentando o suficiente”. A pergunta correta era sempre: “o que o agente ainda não possui, e essa capacidade pode ser fornecida de maneira compreensível e executável?”
@@ -72,9 +72,9 @@ Esse experimento comprova diretamente a tese central desta aula: **o mesmo model
Um time utilizou Claude Sonnet para adicionar novos endpoints de API em uma aplicação web Python de médio porte (FastAPI + PostgreSQL + Redis, ~15 mil linhas de código).
-Inicialmente, forneceram apenas uma frase: “adicione endpoints de preferências do usuário em `/api/v2/users`”. O resultado? O agente gastou 40% da janela de contexto explorando a estrutura do repositório, gerou código aparentemente razoável, mas sem seguir os padrões de tratamento de erros do projeto, utilizou sintaxe antiga do SQLAlchemy e declarou conclusão enquanto os endpoints ainda apresentavam erros em runtime. A sessão seguinte precisou refazer todo o trabalho de descoberta.
+Inicialmente, forneceram apenas uma frase: “adicione endpoints de preferências do usuário em `/api/v2/users`”. O resultado? O agente passou boa parte da sessão explorando a estrutura do repositório, gerou código aparentemente razoável, mas sem seguir os padrões de tratamento de erros do projeto, utilizou sintaxe antiga do SQLAlchemy e declarou conclusão enquanto os endpoints ainda apresentavam erros em runtime. A sessão seguinte precisou refazer todo o trabalho de descoberta.
-Depois, adicionaram um `AGENTS.md` (descrevendo arquitetura do projeto e versões da stack), comandos explícitos de verificação (`pytest tests/api/v2/ && python -m mypy src/`) e registros de decisões arquiteturais. O mesmo modelo passou a ter sucesso em todas as três execuções independentes, com aproximadamente 60% mais eficiência de contexto.
+Depois, adicionaram um `AGENTS.md` (descrevendo arquitetura do projeto e versões da stack), comandos explícitos de verificação (`pytest tests/api/v2/ && python -m mypy src/`) e registros de decisões arquiteturais. O mesmo modelo então seguiu as convenções do projeto e verificou o trabalho com comandos que conseguia executar.
Eles não mudaram o modelo. Mudaram o harness.
diff --git a/docs/pt-BR/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/pt-BR/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
index fe91822..79889c9 100644
--- a/docs/pt-BR/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
+++ b/docs/pt-BR/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -49,7 +49,7 @@ flowchart LR
* **Janelas de contexto são finitas**: Não importa o tamanho anunciado da janela (128K, 200K, 1M de tokens), tarefas longas eventualmente irão esgotá-la. Quando isso acontece, é necessário realizar uma compactação do contexto (com perda de informações) ou iniciar uma nova sessão — e ambas as opções implicam algum tipo de perda.
* **Arquivos de persistência de estado**: Arquivos que armazenam o estado atual do trabalho e permitem que uma nova sessão retome exatamente de onde a anterior parou. Na forma mais simples, incluem registros de progresso, resultados de verificações e próximos passos.
-* **Custo de reconstrução** (*rebuild cost*): O tempo necessário para que uma nova sessão alcance um estado em que consiga executar trabalho de forma produtiva. Um bom *harness* pode reduzir esse tempo de 15 minutos para apenas 3 minutos.
+* **Custo de reconstrução** (*rebuild cost*): O tempo necessário para que uma nova sessão alcance um estado em que consiga executar trabalho de forma produtiva. Um bom *harness* deixa o progresso, os resultados de verificação e os próximos passos em arquivos, para que a nova sessão comece a partir de um estado escrito.
* **Drift (desvio)**: A diferença entre o entendimento do agente e o estado real do repositório de código. Cada troca de sessão introduz algum nível de desvio; sem controle, esse efeito se acumula ao longo do tempo.
* **Ansiedade de contexto** (*context anxiety*): Fenômeno observado pela Anthropic em que agentes passam a acelerar a conclusão de tarefas ao perceberem que o limite de contexto está próximo. Eles encerram atividades prematuramente para evitar perda de informação. Em essência, trata-se de uma ansiedade irracional relacionada ao consumo de recursos.
* **Compactação versus reinicialização** (*compaction vs. reset*): A compactação resume informações dentro da mesma sessão (preservando o "o quê", mas potencialmente perdendo o "porquê"). A reinicialização inicia uma nova sessão a partir de artefatos persistidos (ambiente mais limpo, mas dependente da qualidade e completude desses artefatos).
@@ -156,7 +156,7 @@ A LangChain relata aumento de 52,8% para 66,5%, 13,7 pontos percentuais, com o m
- Janelas de contexto são um recurso finito. Tarefas longas inevitavelmente se estenderão por múltiplas sessões, e as sessões perderão informações ao longo do tempo — essa é uma realidade objetiva.
- A solução não é ter janelas de contexto maiores, mas sim uma melhor persistência de estado. Arquivos de progresso, registros de decisões e checkpoints do Git trabalham em conjunto para permitir que novas sessões retomem o trabalho de onde as anteriores pararam.
- Trate o agente como um engenheiro cuja memória de curto prazo é apagada ao final de cada sessão: antes de “encerrar o expediente”, registre o que foi feito, por que foi feito e quais são os próximos passos.
-- O custo de reconstrução (*rebuild cost*) é a métrica principal. Um bom *harness* deve permitir que novas sessões retornem a um estado executável em até 3 minutos.
+- O custo de reconstrução (*rebuild cost*) é a métrica principal. Um bom *harness* deixa o progresso, os resultados de verificação e os próximos passos em arquivos, para que uma nova sessão se recupere rapidamente.
- Estratégia híbrida: tarefas curtas dentro de uma mesma sessão; tarefas longas utilizando artefatos estruturados para garantir continuidade entre sessões.
## Leitura Complementar
diff --git a/docs/pt-BR/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/pt-BR/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
index b504cac..d620650 100644
--- a/docs/pt-BR/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
+++ b/docs/pt-BR/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -37,7 +37,7 @@ flowchart TB
## O Que Acontece Quando Você Mistura as Duas Coisas
-O problema mais direto é que a infraestrutura não é construída de forma sólida. O agente gasta 80% do esforço escrevendo código de funcionalidades e os 20% restantes configurando alguma infraestrutura de maneira superficial. O framework de testes é configurado, mas nunca validado; as regras de lint são definidas, mas permissivas demais; nenhum arquivo de progresso é criado. Esses problemas não são evidentes na primeira sessão (porque o agente ainda se lembra do que fez), mas aparecem na segunda sessão: o novo agente não sabe como executar o projeto, como testá-lo ou em que estado ele se encontra.
+O problema mais direto é que a infraestrutura não é construída de forma sólida. O agente gasta a maior parte do esforço em código de funcionalidades e trata a infraestrutura como algo secundário. O framework de testes é configurado, mas nunca validado; as regras de lint são definidas, mas permissivas demais; nenhum arquivo de progresso é criado. Esses problemas não são evidentes na primeira sessão (porque o agente ainda se lembra do que fez), mas aparecem na segunda sessão: o novo agente não sabe como executar o projeto, como testá-lo ou em que estado ele se encontra.
Um custo mais oculto é o "acúmulo de código não verificado". Código de funcionalidades é escrito antes que o framework de testes esteja corretamente configurado — quando você finalmente volta para adicionar testes, pode descobrir que o próprio design estava incorreto. Se isso tivesse sido percebido antes, a implementação teria seguido outro caminho. Quanto mais código é escrito antecipadamente, mais código precisará ser descartado e refeito posteriormente.
@@ -45,7 +45,7 @@ O orçamento de contexto também é desperdiçado. O trabalho de inicialização
O problema mais fácil de ignorar são as armadilhas das suposições implícitas. Decisões tomadas pelo agente durante a inicialização (qual framework de testes usar, como organizar diretórios, como gerenciar dependências) — se não forem registradas explicitamente, sessões posteriores podem tomar decisões contraditórias. A primeira sessão escolheu o Vitest como framework de testes, mas o agente da segunda sessão não sabe disso e introduz o Jest. Dois frameworks de testes passam a coexistir, e o custo de manutenção dobra.
-A pesquisa da Anthropic sobre desenvolvimento de aplicações de longa duração recomenda explicitamente separar inicialização de implementação. Os dados experimentais mostraram que projetos que utilizam uma fase dedicada de inicialização apresentaram taxas de conclusão de funcionalidades 31% maiores em cenários com múltiplas sessões quando comparados a abordagens mistas. Além disso, o tempo investido na fase de inicialização é totalmente recuperado ao longo das 3 ou 4 sessões seguintes.
+O trabalho da Anthropic com agentes de longa duração [faz a inicialização ser uma primeira sessão separada](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents). O inicializador escreve um script `init.sh`, um arquivo de progresso, uma lista de funcionalidades e um commit inicial no Git; as sessões de codificação seguintes leem esse estado, trabalham em uma funcionalidade por vez, testam de ponta a ponta, fazem commit e atualizam o arquivo de progresso.
O guia de *harness engineering* do Codex da OpenAI também enfatiza o princípio de que o "repositório é o registro operacional": é necessário estabelecer uma estrutura operacional clara desde a primeira execução; caso contrário, cada nova sessão precisará inferir novamente as convenções do projeto.
diff --git a/docs/pt-BR/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/pt-BR/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
index 46f9089..677372b 100644
--- a/docs/pt-BR/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
+++ b/docs/pt-BR/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -26,7 +26,7 @@ O comportamento real do Claude Code é bastante revelador. Peça para ele "adici
Seis etapas depois, todas estão pela metade. Não existe verificação end-to-end, há um acoplamento complexo entre partes incompletas do código e a próxima sessão que tentar continuar o trabalho ficará completamente perdida.
-Os dados experimentais da Anthropic corroboram diretamente esse comportamento: agentes que utilizam uma estratégia de "próximo pequeno passo" (*small next step*), equivalente a WIP=1, apresentam uma taxa de conclusão de tarefas 37% maior do que agentes que recebem prompts amplos. Mais interessante ainda: o número de linhas de código geradas pelos agentes possui uma correlação fracamente negativa com a conclusão efetiva de funcionalidades — quanto mais código é escrito, menos funcionalidades são concluídas. Uma demonstração baseada em dados de que assumir mais trabalho do que se consegue concluir é contraproducente.
+A orientação da Anthropic para agentes de longa duração [pede que o agente de codificação trabalhe em uma funcionalidade por vez](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), depois verifique, faça commit e atualize o progresso antes de seguir. Um prompt amplo convida o agente a abrir várias frentes, e cada frente disputa o mesmo contexto e o mesmo orçamento de verificação.
## Fluxo de Trabalho WIP=1
diff --git a/docs/pt-BR/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/pt-BR/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
index a646e7d..e02791f 100644
--- a/docs/pt-BR/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
+++ b/docs/pt-BR/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -25,7 +25,7 @@ Autenticação do usuário concluída, carrinho de compras quase pronto, faltam
Uma nova sessão de agente consegue responder às seguintes perguntas com base nessa anotação? O que significa "quase concluído"? Quais testes o carrinho passou? O que está bloqueando os pagamentos? A resposta para todas elas é: "ninguém sabe".
-O resultado: a nova sessão passa 20 minutos tentando inferir o estado do projeto e pode acabar reimplementando funcionalidades já concluídas. Dados de engenharia da Anthropic mostram que bons registros de progresso reduzem o tempo de diagnóstico no início de uma sessão em 60–80%.
+O resultado: a nova sessão precisa inferir o estado do projeto e pode acabar reimplementando funcionalidades já concluídas. A recomendação da Anthropic é [registrar o progresso e os resultados de verificação em arquivos versionados](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), para que a próxima sessão possa inspecionar o estado.
## Máquina de Estados das Funcionalidades
@@ -116,7 +116,7 @@ Uma plataforma de e-commerce com 10 funcionalidades. Duas abordagens de acompanh
**Modo estruturado**: Cada funcionalidade possui um estado claro e um comando de verificação. Uma nova sessão lê a lista de funcionalidades e, em 3 minutos, sabe que: F01–F05 estão em `passing`, F06 está em `active` (em andamento) e F07–F10 estão em `not_started`. Ela continua diretamente a partir da F06, sem retrabalho.
-Resultado quantificado: projetos que utilizam listas de funcionalidades estruturadas apresentam uma taxa de conclusão de funcionalidades 45% maior do que aqueles que utilizam acompanhamento livre, com zero implementações duplicadas.
+Uma lista estruturada coloca o estado de cada funcionalidade e seu comando de verificação em um único lugar, para que a nova sessão saiba o que já foi feito.
## Principais Aprendizados
diff --git a/docs/pt-BR/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/pt-BR/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
index 72da255..5e6847b 100644
--- a/docs/pt-BR/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
+++ b/docs/pt-BR/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -68,7 +68,7 @@ Um agente de avaliação independente, especificamente ajustado para ser criteri
| Arquitetura | Tempo de Execução | Custo | Funcionalidades Principais Funcionando? |
| ----------------------------------------------- | ----------------- | ------- | ---------------------------------------------------------- |
| Agente único (execução simples) | 20 min | US$ 9 | Não (entidades do jogo não respondem à entrada do usuário) |
-| Três agentes (planejador + gerador + avaliador) | 6 horas | US$ 200 | Sim (o jogo é totalmente jogável) |
+| Três agentes (planejador + gerador + avaliador) | 6 horas | US$ 200 | A jogabilidade central funcionava; a física e o nível ainda tinham problemas |
Trata-se exatamente do mesmo modelo (Opus 4.5) com exatamente o mesmo prompt ("construa um editor de jogos retrô 2D"). A única diferença é o harness: em vez de uma **execução simples**, utiliza-se um fluxo em que o **planejador expande os requisitos → o gerador implementa funcionalidade por funcionalidade → o avaliador realiza testes reais de clique usando Playwright**.
@@ -128,7 +128,7 @@ Sinais eficazes de tempo de execução incluem:
2. Executar o fluxo completo de redefinição.
3. Verificar a consistência do estado do banco de dados.
-Todos os defeitos foram descobertos durante a sessão, economizando de 5 a 10 vezes o custo de correções posteriores.
+Todos os três defeitos aparecem ainda dentro da sessão, quando o custo da correção ainda é local.
## Principais Aprendizados
diff --git a/docs/pt-BR/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/pt-BR/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
index 0d729d8..fd9b9fc 100644
--- a/docs/pt-BR/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
+++ b/docs/pt-BR/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -130,7 +130,7 @@ Sempre que você descobrir uma nova categoria de erro cometido por agentes duran
| Problema de Permissão | Permissões diferentes no ambiente empacotado | Não detectado | Detectado |
| Propagação de Erros | Exceções da camada de serviço não chegaram à camada de UI | Não detectado | Detectado |
-Todos os 5 defeitos foram detectados pelos testes end-to-end; os testes unitários não detectaram nenhum. O custo foi um aumento no tempo de execução dos testes de 2 segundos para 15 segundos — perfeitamente aceitável em um fluxo de trabalho com agentes.
+Todos os 5 defeitos foram detectados pelos testes end-to-end; os testes unitários não detectaram nenhum. A execução end-to-end é mais lenta, mas esse custo é pequeno comparado ao de publicar cinco defeitos de fronteira.
## Principais Conclusões
diff --git a/docs/pt-BR/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/pt-BR/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
index 7045c34..1fcb814 100644
--- a/docs/pt-BR/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
+++ b/docs/pt-BR/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -21,7 +21,7 @@ Quando um harness não possui observabilidade, quatro categorias de problemas ap
**As tentativas de correção se tornam suposições cegas.** Quando o agente não sabe por que algo falhou, a direção da correção é aleatória. Ele pode insistir repetidamente na direção errada — corrigindo caminhos de código não relacionados enquanto ignora a verdadeira causa raiz. Cada tentativa cega consome tokens e tempo.
-**Abismo de informação na troca de sessão.** Quando um trabalho incompleto é transferido para uma nova sessão, a falta de observabilidade faz com que a nova sessão precise diagnosticar o estado do sistema do zero. Observações da Anthropic sobre agentes de longa duração mostram que esse diagnóstico redundante pode consumir entre 30% e 50% do tempo total da sessão.
+**Abismo de informação na troca de sessão.** Quando um trabalho incompleto é transferido para uma nova sessão, a falta de observabilidade faz com que a nova sessão precise diagnosticar o estado do sistema do zero. Ela precisa reler o código, rerodar comandos e decidir quais sinais importam; [registros versionados de progresso e verificação](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) fornecem um estado inspecionável.
## Um Cenário Real com Claude Code
@@ -31,7 +31,7 @@ Considere um harness utilizando um fluxo de trabalho com três papéis: planejad
**Com observabilidade completa:** O planejador produz um contrato de sprint listando quais componentes devem ser modificados, os critérios de verificação de cada um e as exclusões (por exemplo, não alterar estilos de impressão). O gerador implementa a funcionalidade seguindo esse contrato, e a observabilidade de runtime registra o processo de carregamento e aplicação de estilos em cada componente. O avaliador utiliza uma rubrica de pontuação para avaliar cada dimensão separadamente, apresentando evidências específicas: "O contraste de cores do botão é insuficiente (padrão WCAG AA 4,5:1, valor medido 2,1:1)." Uma única iteração produz um resultado de alta qualidade em aproximadamente 15 minutos.
-Uma diferença de eficiência de 3x. A única variável alterada é a observabilidade.
+A diferença vem de o contrato e as evidências existirem fora da cabeça do agente.
## Observabilidade em Camadas
@@ -122,7 +122,7 @@ Crie um *trace* para cada sessão do harness, um *span* para cada tarefa e *sub-
## Experimento da Anthropic com Arquitetura de Três Agentes
-Em março de 2026, a Anthropic publicou um experimento sistemático de harness. Eles executaram a mesma tarefa ("construir uma DAW baseada em navegador utilizando a Web Audio API") com três arquiteturas diferentes e registraram dados detalhados de cada fase:
+A Anthropic publicou em março de 2026 a [execução atualizada da DAW com a mesma arquitetura de três agentes](https://www.anthropic.com/engineering/harness-design-long-running-apps) (“construir uma DAW baseada em navegador utilizando a Web Audio API”). A primeira versão, criada para o Opus 4.5, usava um gerador trabalhando em sprints e um avaliador que pontuava cada sprint. A versão atualizada, executada no Opus 4.6, removeu o conceito de sprint: o construtor trabalha continuamente, e o avaliador revisa após cada rodada de construção. A tabela abaixo é a execução atualizada:
| Agente e Fase | Duração | Custo |
|---------------|----------|--------|
@@ -135,7 +135,7 @@ Em março de 2026, a Anthropic publicou um experimento sistemático de harness.
| QA rodada 3 | 9,6 min | US$ 4,06 |
| **Total** | **3 h 50 min** | **US$ 124,70** |
-Cada um dos três agentes possuía uma função distinta, e cada um desempenhava um papel importante na observabilidade:
+Cada papel desempenha uma parte clara na observabilidade. As descrições de papéis abaixo cobrem a primeira versão; a versão atualizada remove a camada de sprint do gerador:
**Planejador (*Planner*):** Recebe um requisito do usuário com 1 a 4 frases e o expande para uma especificação completa de produto. Ele foi instruído a "ser ousado no escopo" e a "focar no contexto do produto e no design técnico de alto nível, em vez de detalhes técnicos de implementação". O motivo é simples: se o planejador especificar detalhes técnicos granulares prematuramente e estiver errado, esses erros se propagam para as etapas seguintes. Uma abordagem melhor é restringir os entregáveis e permitir que o agente encontre seu próprio caminho durante a execução.
@@ -159,7 +159,7 @@ O avaliador nem sempre foi tão eficaz. As primeiras versões identificavam prob
- **Ambas as camadas de observabilidade são essenciais.** Os sinais de runtime explicam "o que aconteceu"; os artefatos de processo explicam "por que foi feito dessa forma".
- **Contratos de sprint antecipam o alinhamento.** Eles evitam que o gerador implemente algo que o avaliador rejeitará imediatamente por motivos previsíveis.
- **Rubricas de pontuação tornam a avaliação reproduzível.** Diferentes avaliadores produzem pontuações semelhantes para a mesma entrega.
-- **A falta de observabilidade desperdiça de 30% a 50% do tempo da sessão em diagnósticos redundantes.**
+- **A observabilidade transforma uma rejeição vaga em um defeito específico e corrigível.**
## Leitura Complementar
diff --git a/docs/pt-BR/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/pt-BR/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
index 79853d1..df4d371 100644
--- a/docs/pt-BR/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
+++ b/docs/pt-BR/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -15,7 +15,7 @@ As leis da evolução de software de Lehman nos dizem que sistemas submetidos a
Durante cinco meses de experimentos com o Codex, a OpenAI observou algo marcante: **os agentes copiam padrões já presentes no repositório, mesmo quando esses padrões são inconsistentes ou subótimos.** Com o tempo, essa cópia inevitavelmente leva à deriva. A primeira pessoa deixa uma xícara de café na área comum; a segunda pensa "já está bagunçado mesmo" e deixa outra; uma semana depois a mesa está coberta de xícaras. Uma base de código funciona da mesma forma.
-A equipe da OpenAI inicialmente gastava 20% de todas as sextas-feiras limpando manualmente a "bagunça de IA", mas essa abordagem claramente não escala. Eles eventualmente chegaram a uma solução sistemática:
+A equipe da OpenAI inicialmente reservava as sextas-feiras — [um dia de trabalho, cerca de 20% da capacidade semanal](https://openai.com/index/harness-engineering/) — para limpar manualmente a “bagunça de IA”. Conforme a vazão cresceu, a limpeza manual passou a custar mais do que rendia. Eles eventualmente chegaram a uma solução sistemática:
1. **Codifique as "regras de ouro" no repositório**: Regras como "prefira o pacote utilitário compartilhado em vez de helpers ad hoc criados manualmente" (mantenha os invariantes centralizados) e "não faça suposições aleatórias sobre estruturas de dados" (valide os limites ou dependa de SDKs tipados). Essas regras são concretas, mecânicas e verificáveis automaticamente.
@@ -45,7 +45,7 @@ flowchart LR
Fix --> Build
```
-Mas isso ainda não é suficiente. O progresso atual precisa ser registrado em artefatos legíveis por máquina: subtarefas concluídas com seus critérios de aprovação atendidos, subtarefas em andamento mas ainda incompletas com seu estado atual, e subtarefas que ainda não foram iniciadas. Bons registros de progresso podem reduzir o tempo de diagnóstico no início de uma sessão em 60–80%.
+Mas isso ainda não é suficiente. O progresso atual precisa ser registrado em artefatos legíveis por máquina: subtarefas concluídas com seus critérios de aprovação atendidos, subtarefas em andamento mas ainda incompletas com seu estado atual, e subtarefas que ainda não foram iniciadas. Registre o progresso e os resultados de verificação em arquivos versionados, para que a próxima sessão possa inspecionar o estado.
Artefatos temporários — logs de depuração, arquivos temporários, código comentado, marcadores TODO — também devem ser removidos, pois aumentam a carga cognitiva da próxima sessão. O fluxo padrão de inicialização também deve continuar funcionando. A próxima sessão consegue começar a trabalhar sem intervenção manual? Inicialização do ambiente, carregamento da base de código, aquisição de contexto e seleção de tarefas — nenhum desses caminhos pode estar quebrado.
@@ -76,7 +76,7 @@ A armadilha mental mais comum é pensar: "não tenho tempo para limpar nesta ses
Pior ainda, cada sessão possui seus próprios objetivos. A nova sessão está ali para realizar trabalho novo, não para limpar a bagunça da sessão anterior. Ela ignorará o caos e começará a trabalhar por cima dele, introduzindo ainda mais caos. Esse é o ciclo de retroalimentação positiva da entropia.
-Os números contam a história. Um projeto desenvolvido com agentes durante 12 semanas, sem estratégia de limpeza:
+Para um projeto hipotético de 12 semanas, suponha os seguintes valores:
- Semana 1: taxa de sucesso do build 100%, taxa de sucesso dos testes 100%, inicialização de nova sessão em 5 min
- Semana 4: build 95%, testes 92%, inicialização em 15 min
@@ -88,7 +88,7 @@ O mesmo projeto com uma estratégia de limpeza:
- Semana 1: 100%, 100%, 5 min
- Semana 12: 97%, 95%, 9 min
-Após 12 semanas: a taxa de sucesso do build difere em 29 pontos percentuais e o tempo de inicialização de uma nova sessão difere em 85%. Isso não é teórico — é uma diferença observada.
+Um loop semanal de limpeza mantém o estado inicial estável: cada sessão termina com build, testes, progresso e artefatos temporários em ordem, então a próxima sessão começa da mesma linha de base.
## Como Fazer
@@ -141,7 +141,7 @@ Novas sessões leem esse documento e sabem imediatamente onde priorizar esforço
Todo componente do harness existe porque o modelo não conseguia realizar algo de forma confiável sozinho. Mas, à medida que os modelos evoluem, essas premissas ficam desatualizadas.
-Os experimentos da Anthropic demonstraram isso diretamente. O harness inicial incluía um mecanismo de divisão de sprints — quebrando o trabalho em pequenas partes para que o Sonnet 4.5 pudesse concluí-las uma por vez. Quando o Opus 4.6 foi lançado, as capacidades nativas do modelo passaram a lidar autonomamente com a decomposição do trabalho, tornando a construção de sprints uma sobrecarga desnecessária. Após sua remoção, o agente construtor conseguiu trabalhar continuamente por mais de duas horas sem perder o foco — e de forma mais fluida.
+O relatório de harness da Anthropic mostra isso diretamente. O primeiro harness de três agentes, criado para o Opus 4.5, tinha o gerador trabalhando em sprints. Quando o [Opus 4.6](https://www.anthropic.com/engineering/harness-design-long-running-apps) foi lançado, o modelo já conseguia lidar com a decomposição do trabalho, então a construção de sprints se tornou desnecessária. Na execução atualizada da DAW, o construtor trabalhou continuamente por mais de duas horas sem perder o foco.
Mas o avaliador contou uma história diferente. Mesmo com as capacidades mais fortes do Opus 4.6, quando as tarefas se aproximavam do limite de capacidade do modelo, o avaliador continuava agregando valor real — detectando funcionalidades ausentes e implementações simuladas deixadas pelo gerador. Isso significa que o avaliador não é uma decisão fixa de sim ou não; sua utilidade depende de quão próxima a dificuldade da tarefa está da capacidade do modelo.
@@ -174,7 +174,7 @@ Um aplicativo Electron desenvolvido com agentes durante 12 semanas, comparando d
**Com estratégia de limpeza** (grupo experimental): Verificação completa de estado limpo ao final de cada sessão, além de um loop semanal de limpeza. Na semana 12, taxa de sucesso do build de 97%, taxa de sucesso dos testes de 95%, inicialização de nova sessão em 9 minutos, 11 artefatos obsoletos.
-Na semana 12, a taxa de sucesso do build do grupo experimental era 29 pontos percentuais maior, a taxa de sucesso dos testes era 34 pontos maior e o tempo de inicialização de novas sessões era 85% menor. Cada sessão gastava cerca de 5 minutos extras com limpeza, mas ao longo de 12 semanas isso economizou dezenas de horas de caos.
+Na semana 12, o grupo com limpeza ainda estava perto do ponto de partida em build e testes, a nova sessão começava rápido e havia poucos artefatos obsoletos. A limpeza custava alguns minutos por sessão, mas mantinha um estado inicial em que a próxima sessão podia confiar.
## Principais Conclusões
diff --git a/docs/pt-BR/lectures/lecture-13-loop-engineering/index.md b/docs/pt-BR/lectures/lecture-13-loop-engineering/index.md
index 33489f0..ad54a2d 100644
--- a/docs/pt-BR/lectures/lecture-13-loop-engineering/index.md
+++ b/docs/pt-BR/lectures/lecture-13-loop-engineering/index.md
@@ -84,11 +84,11 @@ Engenharia de Loops, o assunto desta aula, não é sobre nenhum comando específ
Você não precisa digitar `/goal` toda vez. Mas entender de onde ele veio e por que é como é — isso é entender o núcleo da engenharia de loops. Loops mais complexos apenas adicionam peças como agendamento, paralelismo, isolamento e memória sobre esses mesmos três fundamentos: objetivo, verificação, condição de parada.
-## Junho de 2026: Três Pessoas Acenderam o Mesmo Fusível em Uma Semana
+## Datas Diferentes, a Mesma Direção
-Na primeira semana de junho de 2026, três profissionais que construíam infraestrutura de agentes de codificação — sem comparar notas — disseram a mesma coisa em palavras diferentes.
+A mesma ideia surgiu em lugares e momentos diferentes.
-**Peter Steinberger** (criador do OpenClaw, [sua postagem alcançou 8 milhões de visualizações](https://x.com/steipete/status/2063697162748260627)): "Você não deveria mais estar dando prompt em agentes de codificação. Você deveria estar projetando loops que dão prompt em seus agentes."
+**Peter Steinberger** (criador do OpenClaw, [em uma postagem](https://x.com/steipete/status/2063697162748260627)): "Você não deveria mais estar dando prompt em agentes de codificação. Você deveria estar projetando loops que dão prompt em seus agentes."
**Boris Cherny** (chefe do Claude Code na Anthropic, [no podcast Acquired](https://x.com/rohanpaul_ai/status/2063289804708835412)): "Eu não dou mais prompt no Claude. Tenho loops rodando que dão prompt no Claude e descobrem o que fazer. Meu trabalho é escrever loops."
@@ -96,9 +96,9 @@ Na primeira semana de junho de 2026, três profissionais que construíam infraes
> **Loop engineering é substituir você mesmo como a pessoa que dá prompt ao agente. Você projeta o sistema que faz isso em vez de você.**
-Cherny divulgou números: por mais de 30 dias consecutivos, todas as contribuições de código para o Claude Code foram feitas autonomamente por IA — 259 PRs mescladas, mais de 80% do código de produção autoriado pelo Claude, e uma taxa de sucesso de 76% em tarefas de software abertas.
+Cherny escreveu em um [relatório pessoal de 27/12/2025](https://twitter.com/bcherny/status/2004887829252317325) que, ao longo de 30 dias, mesclou 259 PRs — 497 commits, 40.000 linhas adicionadas e 38.000 removidas — e que cada linha foi escrita por Claude Code + Opus 4.5.
-Três pessoas. Uma semana. A mesma conclusão. Não porque coordenaram — mas porque a infraestrutura havia silenciosamente cruzado um limiar. Os agentes haviam se tornado confiáveis o suficiente para terminar tarefas não triviais sem supervisão. Primitivas de agendamento (`/loop`, `/goal`, cron) agora estavam embutidas nas ferramentas. O custo de uma única execução de agente havia caído o suficiente para que rodar uma repetidamente em um temporizador parasse de parecer desperdício. Quando todas as peças estão presentes, o movimento que as combina se torna óbvio para todos ao mesmo tempo.
+As citações vêm de datas, formatos e equipes diferentes. A direção comum é tirar o agendamento, a verificação e a decisão de parada do prompt momento a momento e colocá-los em um sistema. Em meados de 2026, os agentes conseguiam concluir tarefas não triviais sem supervisão, as primitivas de agendamento vinham embutidas e uma execução era barata o suficiente para repetir no temporizador. Quando as peças estão presentes, mais de uma pessoa as junta.
> Fonte: [Addy Osmani: Loop Engineering](https://addyosmani.com/blog/loop-engineering/)
@@ -267,7 +267,7 @@ flowchart TD
Isso não é mais uma única execução de agente. É um sistema operacional continuamente que acorda todas as manhãs, varre o chão sozinho e coloca as coisas que precisam da sua atenção na sua frente. Seu papel se torna: **revisar o conteúdo da caixa de entrada, tomar decisões e, quando identificar um padrão que o sistema não consegue lidar, refinar as skills e regras.**
-Cherny usou esse padrão para mesclar 259 PRs em 30 dias sem abrir uma IDE uma única vez. Engenheiros da OpenAI usaram o mesmo padrão para construir um produto beta de aproximadamente um milhão de linhas — sem escrever uma única linha de código eles mesmos.
+O relatório de 30 dias de Cherny é um dado para esse padrão: 259 PRs, com o código escrito por Claude Code + Opus 4.5. A [conta de harness da OpenAI](https://openai.com/index/harness-engineering/) é outro: uma equipe pequena usou o Codex em um repositório novo por cinco meses e relatou cerca de um milhão de linhas e aproximadamente 1.500 PRs.
## Separação Gerador/Avaliador: Por Que Você Não Pode Deixar o Modelo Corrigir o Próprio Trabalho
@@ -293,7 +293,7 @@ Uma frase para lembrar: **alguém na sua equipe não deve acreditar em você.**
Se você quer ver como é um loop bem projetado e realmente rodando, o [autoresearch do Karpathy](https://github.com/karpathy/autoresearch) é o exemplo didático.
-Em março de 2026, Karpathy lançou um projeto Python de 630 linhas. Dê a ele uma GPU e uma direção de pesquisa, e ele roda a noite toda — completando centenas de experimentos de treinamento de ML, mantendo apenas aqueles que realmente melhoram. O projeto atingiu 66.000+ estrelas em poucos dias do lançamento.
+Em março de 2026, Karpathy lançou o [autoresearch](https://github.com/karpathy/autoresearch). O repositório é deliberadamente pequeno: `prepare.py` é infraestrutura fixa, `train.py` é o arquivo que o agente edita (cerca de 630 linhas) e `program.md` é a metodologia de pesquisa que o humano edita. Dê a ele uma GPU e uma direção de pesquisa, e ele roda a noite toda — cada experimento recebe um orçamento fixo de 5 minutos de tempo de treinamento (excluindo inicialização e compilação), e só as mudanças que melhoram `val_bpb` são mantidas.
### Três Arquivos, Três Papéis
@@ -343,9 +343,9 @@ flowchart TD
8b --> 9
```
-Ele roda aproximadamente 12 experimentos por hora. Uma execução noturna (8 horas) são cerca de 100 experimentos. O próprio Karpathy o rodou por 2 dias — ~700 experimentos.
+O README estima cerca de 12 experimentos por hora, ou aproximadamente 100 em uma execução noturna de 8 horas. O orçamento de 5 minutos cobre o treinamento, não a inicialização ou a compilação; o restante de cada rodada vai para edição, lançamento e avaliação. Karpathy relatou ter rodado uma versão privada do autoresearch de forma autônoma por cerca de dois dias, para a rodada do nanochat descrita abaixo.
-O orçamento fixo de 5 minutos de relógio é uma escolha chave de design — não importa o que o agente mude, cada experimento leva exatamente o mesmo tempo. Isso significa que todos os resultados são diretamente comparáveis sob o mesmo orçamento de tempo — sem discussão sobre "esse rodou mais tempo então é melhor".
+O orçamento fixo de 5 minutos de treinamento é uma escolha chave de design — não importa o que o agente mude, a execução de treinamento recebe o mesmo orçamento de tempo. Isso significa que todos os resultados são diretamente comparáveis sob o mesmo orçamento de treinamento.
### Saída: O Que Você Vê Quando Acorda
@@ -375,13 +375,9 @@ O agente escreve mensagens de commit claras sobre o que tentou, o que funcionou,
### O Que Ele Realmente Encontrou
-Resultados da execução inicial de 2 dias, ~700 experimentos de Karpathy:
+Resultados da [rodada 1](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b) do autoresearch reduziram o tempo de treinamento em nível GPT-2 do nanochat em 8×H100 [de **2,02 horas para 1,80 horas**](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b), uma redução de cerca de **10,9%** no tempo de treinamento.
-- De ~700 tentativas, cerca de **20 melhorias reais empilháveis** foram encontradas
-- Reduziu o tempo de treinamento em nível GPT-2 do nanochat em 8×H100 de **2,02 horas → 1,80 horas**, cerca de **11% mais rápido**
-- Descobertas incluíram: ajustes de taxa de aprendizado, ajuste de otimizador, trocas de ativação, otimizações de padrão de atenção, etc.
-
-Todas as melhorias foram descobertas revolucionárias? Não. A maioria eram pequenas otimizações que se empilharam. Mas essas 20 melhorias válidas teriam levado semanas de trabalho manual a um pesquisador humano — o agente fez em 48 horas.
+A maioria das mudanças eram pequenas otimizações que se empilharam. A parte útil é o loop: um orçamento fixo, um log completo de experimentos e uma regra de que só melhorias verificadas permanecem.
### O Detalhe Mais Revelador: O Loop Está Escrito em Inglês, Não em Código.
@@ -399,7 +395,7 @@ Loops rápidos tentam você a pular a verificação. "Parece bom" não é a mesm
### 2. Deterioração da Compreensão
-Quanto mais rápido um loop entrega código, mais a sua compreensão da sua própria base de código se afasta da realidade. A equipe de Cherny tinha 80% do código autoriado por agentes — o que significa que a maior parte do código de uma equipe não foi escrita por uma pessoa. Se você não ler e usar o que o loop produz, sua compreensão decai continuamente. **Loops rápidos exigem leitura rápida.**
+Quanto mais rápido um loop entrega código, mais a sua compreensão da sua própria base de código se afasta da realidade. Um loop mescla centenas de PRs; a equipe lê esses PRs, revisa os diffs que importam e continua usando o código, para que o modelo mental acompanhe. **Loops rápidos exigem leitura rápida.**
### 3. Rendição Cognitiva
@@ -407,11 +403,11 @@ Quando o loop roda suavemente, a postura mais confortável é parar de ter opini
### 4. Explosão de Tokens
-Cada iteração de um loop acumula mais contexto: código escrito, erros encontrados, decisões tomadas. Sem gerenciamento de contexto, o tamanho do prompt cresce aproximadamente quadraticamente com o número de turnos. O Codex resolve isso com compactação automática de contexto — uma API dedicada comprime turnos mais antigos de conversa em resumos criptografados de conteúdo, retendo conhecimento essencial enquanto descarta detalhes redundantes. Esta é uma preocupação de engenharia que você deve abordar desde o primeiro loop, não um complemento posterior.
+Cada iteração de um loop acumula mais contexto: código escrito, erros encontrados, decisões tomadas. Quando cada rodada adiciona aproximadamente uma quantidade fixa de conteúdo novo, o histórico visto por uma única rodada cresce aproximadamente de forma linear com o número de rodadas. Se o sistema reprocessa o histórico completo a cada rodada, a entrada cumulativa ao longo de N rodadas cresce aproximadamente de forma quadrática. O Codex resolve isso com compactação automática de contexto — uma API dedicada comprime turnos mais antigos de conversa em resumos criptografados de conteúdo, retendo conhecimento essencial enquanto descarta detalhes redundantes. Esta é uma preocupação de engenharia que você deve abordar desde o primeiro loop, não um complemento posterior.
## Construindo Seu Primeiro Loop
-Você não precisa começar com um pipeline em escala Stripe mesclando 1.300 PRs por semana. Comece com a menor coisa que funciona.
+Você não precisa começar com um pipeline de alta vazão. Comece com a menor coisa que funciona.
### Passo 1: Escolha Uma Tarefa Recorrente
diff --git a/docs/pt-BR/lectures/lecture-14-graph-engineering/index.md b/docs/pt-BR/lectures/lecture-14-graph-engineering/index.md
index fff7f7f..32cf940 100644
--- a/docs/pt-BR/lectures/lecture-14-graph-engineering/index.md
+++ b/docs/pt-BR/lectures/lecture-14-graph-engineering/index.md
@@ -9,7 +9,7 @@ Seis semanas depois que a aula anterior terminou de abordar a Engenharia de Loop
> "Ainda estamos falando de loops, ou já mudamos para graphs?"
-Um tweet — cerca de 570 mil visualizações em um dia, subindo para cerca de 3 milhões até o fim do mês. Algumas horas depois, o engenheiro de machine learning Hamel Husain publicou um artigo intitulado *Loop Engineering Is Dead. Enter Graph Engineering* — cujo corpo inteiro era um único GIF dizendo "Stop it" — e alcançou cerca de 680 mil visualizações.
+Um tweet. Algumas horas depois, o engenheiro de machine learning Hamel Husain publicou um artigo intitulado *Loop Engineering Is Dead. Enter Graph Engineering* — cujo corpo inteiro era um único GIF dizendo "Stop it".
O mais interessante é: **os dois estavam fazendo uma piada.** Um estava satirizando uma indústria que inventa um novo termo a cada seis semanas; o outro estava aproveitando a piada. Mas a piada sobreviveu apenas cerca de um fim de semana — cursos, roteiros e stacks de ferramentas inundaram a timeline antes do fim de semana terminar, seguidos por uma pilha de números fabricados: "+18% de precisão, −85% de custo" é dado falso (os 18% e os 85% realmente existem, mas vêm de um artigo sobre diagramas de tubulação química, e comparam contra linhas de base completamente diferentes), e "Microsoft, Stanford e Anthropic descobriram a engenharia de grafos ao mesmo tempo" também é falso. A verificação de fatos confirmou apenas um "pioneiro" real: Josh Simmons, cujo *We Are Entering the Graph Engineering Phase* foi escrito em 4 de julho — duas semanas inteiras antes da piada — **foi a piada que tornou a ideia popular; não foi a piada que criou a ideia.**
@@ -257,11 +257,11 @@ Depois de rodar, compare com o grafo acima: o `graph.md` que você escreveu à m
## Projetos de Código Aberto: Depois vs. Antes do Lançamento do Conceito
-Primeiro, deixe claro o limite: **Graph Engineering é um nome que só existe depois de 18 de julho de 2026.** Os frameworks open source anteriores a essa data não são "projetos pós-lançamento da Graph Engineering". Um projeto de código aberto que realmente apareceu com esse nome depois que o conceito explodiu, até o início de agosto de 2026, só existe um que se sustenta:
+Primeiro, deixe claro o limite: **Graph Engineering é um nome que só existe depois de 18 de julho de 2026.** Os frameworks open source anteriores a essa data não são "projetos pós-lançamento da Graph Engineering". Um projeto que usa explicitamente esse nome é o GraphARC:
**Depois do lançamento do conceito**
-- [GraphArc](https://github.com/CodeGraphContext/grapharc) (2026-08-02): afirma ser "a primeira implementação em tempo real da Graph Engineering". Ele transforma a execução de agentes, de um trace escondido nos logs, em uma **orquestração em tempo real interativa** — cada agente, cada dependência, cada ponto de decisão é desenhado, e você visualiza o grafo inteiro antes da execução, confirma (pode até ver no celular) e só então libera. O autor tem experiência em construir ferramentas de grafo para 4.000+ desenvolvedores, com a direção de "observável, depurável, passível de engenharia". Muito novo, funcionalidades ainda em fase inicial.
+- [GraphARC](https://github.com/CodeGraphContext/GraphARC) (criado em julho de 2026): descreve-se como "an end to end implementation of Graph Engineering as proposed by Andrew NG and Peter Steinberger". É um projeto Python em estágio inicial. O movimento útil é ler seu modelo de orquestração e decidir se a abordagem se encaixa no seu fluxo de trabalho.
**Antes do lançamento do conceito (não se chamam Graph Engineering, mas são o que você vai usar na prática)**
@@ -325,7 +325,7 @@ Nem toda tarefa merece um grafo. Cinco critérios; satisfaça pelo menos três a
- [goddaehee: Verificação de fatos de Graph Engineering (coreano, 2026-07-30)](https://goddaehee.tistory.com/628) — a verificação de fatos mais completa: a linha do tempo da origem da piada, a análise dos números falsos, os dados do LangGraph e a comparação de popularidade no Hacker News
- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — o artigo sério duas semanas antes da piada
- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — a resposta oficial: "não é uma ideia nova, é o nome mais recente de um método existente"; mais de 65 milhões de downloads mensais do LangGraph
-- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — os dados de propagação da buzzword (o tweet original com 575 mil visualizações)
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — uma narrativa de como o termo se espalhou
- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — a comparação horizontal dos sete frameworks open source mais populares: LangGraph, CrewAI, Microsoft Agent Framework, LlamaIndex, Google ADK, OpenAI Agents SDK, Mastra
- [Documentação oficial do LangGraph](https://docs.langchain.com/oss/python/langgraph/graph-api) — "Nodes do the work, edges tell what to do next"; a definição precisa de nós e arestas, a referência de primeira mão para construir grafos
- [Anthropic: Building Effective Agents (Dec 2024)](https://www.anthropic.com/engineering/building-effective-agents) — os cinco padrões, que, desenhados, formam um grafo; a distinção autoritativa entre workflow e agent
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.md
index 3159f6d..6185eab 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
@@ -9,13 +9,13 @@
Первая мысль? «Модель слабовата. Пора апгрейдиться». Стоп. Прежде чем доставать кошелёк, подумайте: возможно, проблема вовсе не в модели.
-Посмотрим на цифры. К концу 2025 года самые сильные кодинг-агенты на SWE-bench Verified выдают примерно 50–60%. И это на тщательно отобранных задачах с понятными описаниями issue и существующими тестами. Перейдите в свою повседневную среду разработки — расплывчатые требования, отсутствие тестов, неявные бизнес-правила, разбросанные повсюду — и эта цифра только падает.
+Посмотрим на цифры. 29 сентября 2025 года Anthropic сообщила, что Claude Sonnet 4.5 [набрал 77,2% на SWE-bench Verified](https://www.anthropic.com/news/claude-sonnet-4-5). И это на тщательно отобранных задачах с понятными описаниями issue и существующими тестами. Перейдите в свою повседневную среду разработки — расплывчатые требования, отсутствие тестов, неявные бизнес-правила, разбросанные повсюду — и эта цифра только падает.
Но за этими числами скрывается контринтуитивная истина.
## Один и тот же конь, разные судьбы
-Anthropic провели контролируемый эксперимент. Один и тот же промпт («собери 2D ретро-конструктор игр»), одна и та же модель (Opus 4.5). Первый прогон: голая среда без поддержки — 20 минут, $9, ключевые механики игры просто не работают. Второй прогон: полный harness (архитектура из трёх агентов: planner + generator + evaluator) — 6 часов, $200, в игру можно играть.
+Anthropic сравнила один и тот же промпт («собери 2D ретро-конструктор игр») и одну и ту же модель (Opus 4.5) в двух вариантах harness. Первый прогон: голая среда без поддержки — 20 минут, $9; приложение открывалось, но сущности не реагировали на ввод. Второй прогон: полный harness (архитектура из трёх агентов: planner + generator + evaluator) — 6 часов, $200; автор мог двигать сущность, но физика была грубоватой, а стена перекрывала путь. [Основной геймплей работал; приложение осталось незавершённым.](https://www.anthropic.com/engineering/harness-design-long-running-apps)
Модель не меняли. Opus 4.5 оставался Opus 4.5. Изменилась упряжь.
@@ -39,9 +39,9 @@ Anthropic провели контролируемый эксперимент. О
Когда вы видите эти сценарии вживую, термины перестают быть просто жаргоном:
-- **Capability Gap**: огромная пропасть между производительностью модели на бенчмарках и на реальных задачах. 50–60% pass rate на SWE-bench Verified означает, что почти половина реальных issue не решается.
+- **Capability Gap**: огромная пропасть между производительностью модели на бенчмарках и на реальных задачах. Бенчмарковые задачи приходят с понятным описанием issue, тестами и окружением; в реальных задачах всё это часто нужно обеспечить самому.
- **Harness**: всё за пределами модели — инструкции, инструменты, среда, управление состоянием, верификационная обратная связь. Если это не веса модели — это harness. Та самая «упряжь».
-- **Harness-Induced Failure**: у модели достаточно способностей, но в среде исполнения есть структурные дефекты. Контролируемый эксперимент Anthropic это уже доказал.
+- **Harness-Induced Failure**: у модели достаточно способностей, но в среде исполнения есть структурные дефекты. Сравнение с ретро-игрой выше — один из примеров.
- **Verification Gap**: разрыв между уверенностью агента в своей работе и реальной корректностью. Агент говорит «я закончил», когда не закончил — самый частый паттерн провала.
- **Diagnostic Loop**: выполнить, увидеть провал, отнести его к конкретному слою harness, починить этот слой, выполнить снова. Это ядро методологии harness engineering.
- **Definition of Done**: набор машинно-проверяемых условий — тесты проходят, линт чистый, проверки типов проходят. Без явного definition of done агент придумает свой.
@@ -72,7 +72,7 @@ Anthropic провели контролируемый эксперимент. О
## Эксперимент в миллион строк
-В 2025 году OpenAI провели агрессивный эксперимент: с помощью Codex построить целый внутренний продукт из пустого git-репозитория. Через пять месяцев в репо было примерно миллион строк кода — прикладная логика, инфраструктура, инструментарий, документация, внутренние dev-инструменты — всё сгенерировано агентом. Три инженера управляли Codex, открыли и смержили около 1500 PR. В среднем 3,5 PR на человека в день.
+В августе 2025 года OpenAI начали агрессивный эксперимент: с помощью Codex построить целый внутренний продукт из пустого git-репозитория. Через пять месяцев [в репо было примерно миллион строк кода](https://openai.com/index/harness-engineering/) — прикладная логика, инфраструктура, инструментарий, документация, внутренние dev-инструменты — всё сгенерировано агентом. Три инженера управляли Codex; позже команда выросла до семи инженеров, и за это время было смержено около 1500 PR — в среднем 3,5 PR на инженера в день.
Ключевое ограничение: **люди не пишут код напрямую.** Это была не показуха — так заставили команду понять, что меняется, когда основная работа инженера — уже не написание кода, а проектирование сред, формулирование намерения и построение петель обратной связи.
@@ -86,9 +86,9 @@ Anthropic провели контролируемый эксперимент. О
Команда использовала Claude Sonnet, чтобы добавить новый API-эндпоинт в среднеразмерное Python-веб-приложение (FastAPI + PostgreSQL + Redis, ~15 000 строк кода).
-Сначала они дали только одну фразу: «добавь эндпоинты пользовательских настроек под `/api/v2/users`». Результат? Агент потратил 40% окна контекста на исследование структуры репо, выдал код, который выглядел разумно, но не следовал паттернам обработки ошибок проекта, использовал старый синтаксис SQLAlchemy и заявил о завершении, в то время как у эндпоинта были рантайм-ошибки. Следующая сессия должна была заново проделать всю разведку.
+Сначала они дали только одну фразу: «добавь эндпоинты пользовательских настроек под `/api/v2/users`». Результат? Агент потратил значительную часть сессии на исследование структуры репо, выдал код, который выглядел разумно, но не следовал паттернам обработки ошибок проекта, использовал старый синтаксис SQLAlchemy и заявил о завершении, в то время как у эндпоинта были рантайм-ошибки. Следующая сессия должна была заново проделать всю разведку.
-Потом они добавили `AGENTS.md` (с описанием архитектуры проекта и версий стека), явные команды верификации (`pytest tests/api/v2/ && python -m mypy src/`) и architecture decision records. Та же модель успешно справилась во всех трёх независимых прогонах, и эффективность контекста выросла примерно на 60%.
+Потом они добавили `AGENTS.md` (с описанием архитектуры проекта и версий стека), явные команды верификации (`pytest tests/api/v2/ && python -m mypy src/`) и architecture decision records. Та же модель начала следовать конвенциям проекта и проверять работу командами, которые могла запустить.
Модель они не меняли. Они меняли harness.
diff --git a/docs/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
index ef16578..6cb048e 100644
--- a/docs/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
+++ b/docs/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -52,7 +52,7 @@ flowchart LR
- **Контекстные окна конечны**: какой бы размер ни заявлялся (128K, 200K, 1M), длинные задачи рано или поздно их исчерпают. После исчерпания требуется либо компакция (с потерей информации), либо сброс (новая сессия). Оба варианта что-то теряют.
- **Артефакты непрерывности**: сохранённые файлы состояния, которые позволяют новой сессии однозначно продолжить с того места, где остановилась предыдущая. Базовая форма: лог прогресса + запись верификации + следующие действия. Тот самый журнал мастера.
-- **Стоимость восстановления**: время, нужное новой сессии, чтобы выйти в рабочее состояние. Хорошие harness'ы сжимают её с 15 минут до 3 минут.
+- **Стоимость восстановления**: время, нужное новой сессии, чтобы выйти в рабочее состояние. Хороший harness оставляет прогресс, результаты верификации и следующие действия в файлах, чтобы новая сессия начинала с записанного состояния.
- **Дрейф (drift)**: разрыв между пониманием агента и реальным состоянием репозитория. Каждая граница сессии вносит дрейф; без контроля он накапливается.
- **Контекстная тревожность**: явление, наблюдаемое Anthropic, — агенты демонстрируют преждевременное схождение при приближении к воспринимаемому пределу контекста, преждевременно завершая задачи, чтобы избежать потери информации. Это иррациональная ресурсная тревожность.
- **Компакция против сброса**: компакция суммирует контекст внутри той же сессии (сохраняет «что», может потерять «почему»); сброс открывает новую сессию, восстанавливаясь из сохранённого состояния (чисто, но зависит от полноты артефактов).
@@ -160,7 +160,7 @@ LangChain сообщает о росте с 52,8% до 66,5%, на 13,7 проц
- Контекстное окно — конечный ресурс. Длинные задачи будут охватывать несколько сессий, а сессии будут терять информацию — как мастер, забывающий каждый день, это объективная реальность.
- Решение не в больших окнах, а в лучшем сохранении состояния. Файлы прогресса + логи решений + git-чекпоинты — дайте мастеру с амнезией надёжный журнал.
- Относитесь к агенту как к инженеру с амнезией: перед «уходом со смены» запишите, что сделано, почему и что дальше.
-- Стоимость восстановления — ключевая метрика. Хороший harness должен выводить новую сессию в рабочее состояние за 3 минуты.
+- Стоимость восстановления — ключевая метрика. Хороший harness оставляет прогресс, результаты верификации и следующие действия в файлах, чтобы новая сессия быстро восстанавливалась.
- Смешанная стратегия: короткие задачи внутри сессии, длинные — через структурированные артефакты непрерывности.
## Дополнительное чтение
diff --git a/docs/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
index 968d9fe..9889e81 100644
--- a/docs/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
+++ b/docs/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -37,7 +37,7 @@ flowchart TB
## Что происходит, когда вы их смешиваете
-Самая прямая проблема: фундамент не схватывается как следует. Агент тратит 80% усилий на код фич и 20% — на кое-как настроенную инфраструктуру. Тестовый фреймворк настроен, но не проверен; правила линтера выставлены, но слишком слабые; файл прогресса не создан. Эти дефекты не очевидны в первой сессии (агент ещё помнит, что делал), но проявляются во второй — новый агент не знает, как запускать, как тестировать и где сейчас находится проект. Хлипкий фундамент — шаткое здание.
+Самая прямая проблема: фундамент не схватывается как следует. Агент тратит большую часть усилий на код фич, а инфраструктуру настраивает по остаточному принципу. Тестовый фреймворк настроен, но не проверен; правила линтера выставлены, но слишком слабые; файл прогресса не создан. Эти дефекты не очевидны в первой сессии (агент ещё помнит, что делал), но проявляются во второй — новый агент не знает, как запускать, как тестировать и где сейчас находится проект. Хлипкий фундамент — шаткое здание.
Более скрытая стоимость — «непроверенное накопление»: код фич, написанный до настройки тестового фреймворка, — это код без верификации. Когда вы наконец возвращаетесь добавить тесты к этому коду, вы можете обнаружить, что архитектура была неверной с самого начала — знай вы это, реализовали бы иначе. Это как класть плитку на сырой бетон: когда обнаруживаете, что пол неровный, всю плитку приходится отдирать и переделывать.
@@ -45,7 +45,7 @@ flowchart TB
Самая легко упускаемая проблема — «мины» неявных предположений. Решения, принимаемые агентом во время инициализации (какой тестовый фреймворк, как организовать каталоги, как управлять зависимостями), — если их явно не записать, последующие сессии не смогут их понять. Хуже того, последующие сессии могут принять противоречащие решения. Первая бригада сделала бетонный фундамент, вторая бригада об этом не знала и забила в него деревянные сваи — фундамент трескается.
-В исследовании long-running разработки приложений Anthropic явно рекомендует отделять инициализацию от реализации. Их экспериментальные данные: проекты с выделенной фазой инициализации показывали на 31% более высокую долю завершённых фич в многосессионных сценариях по сравнению со смешанным подходом. Ключевая мысль — время, вложенное в фазу инициализации, полностью окупается в следующих 3–4 сессиях. Чем крепче фундамент, тем быстрее идут стены.
+В работе Anthropic по long-running агентам инициализация [вынесена в отдельную первую сессию](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents). Инициализатор пишет `init.sh`, файл прогресса, список фич и начальный git-коммит; последующие сессии читают это состояние, работают над одной фичей за раз, проверяют её end-to-end, коммитят и обновляют файл прогресса. Чем крепче фундамент, тем быстрее идут стены.
Руководство OpenAI Codex по harness engineering тоже подчёркивает принцип «репозиторий как операционный журнал»: с первого запуска нужно установить ясную операционную структуру, иначе каждая новая сессия будет вынуждена заново выводить соглашения проекта.
diff --git a/docs/ru/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/ru/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
index 5c74c66..180b74f 100644
--- a/docs/ru/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
+++ b/docs/ru/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -26,7 +26,7 @@
Шесть шагов спустя — каждый сделан наполовину. Никакой сквозной верификации, сложная связанность между полу-готовыми кусками кода, и следующая сессия, которая попробует это разобрать, окончательно потеряется. Как тот, кто готовит шесть блюд одновременно: каждое в сковородке, но ни одно не выложено на тарелку. Все подгорают.
-Экспериментальные данные Anthropic прямо это подтверждают: агенты, использующие стратегию «маленький следующий шаг» (эквивалентно WIP=1), показывают на 37% более высокую долю завершённых задач, чем агенты с широкими промптами. Что интереснее, число строк кода, генерируемых агентами, слабо отрицательно коррелирует с реальным завершением фич — больше написанного кода, меньше доведённых до конца фич. Откусил больше, чем прожуёшь — подтверждено данными.
+Руководство Anthropic по long-running агентам [просит coding-агента работать над одной фичей за раз](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), затем проверить, закоммитить и обновить прогресс, прежде чем двигаться дальше. Широкий промпт предлагает агенту открыть несколько линий одновременно, и каждая линия конкурирует за один и тот же бюджет контекста и верификации.
## Рабочий процесс WIP=1
diff --git a/docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
index 747d700..030fdaa 100644
--- a/docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
+++ b/docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -22,7 +22,7 @@ Did user auth, shopping cart mostly done, still need payments
```
Может ли новая сессия агента ответить по этой записи? Что значит «mostly done»? Какие тесты прошла корзина? Что блокирует оплату? Ответ на всё — «никто не знает». Это как сказать врачу «болит живот, в последнее время нормально» — какое лекарство он выпишет?
-Результат: новая сессия тратит 20 минут на восстановление состояния и может пере-реализовать уже готовые фичи. Инженерные данные Anthropic показывают, что хорошие записи прогресса сокращают время диагностики при старте сессии на 60–80%.
+Результат: новой сессии приходится восстанавливать состояние, и она может пере-реализовать уже готовые фичи. Совет Anthropic — [записывать прогресс и результаты верификации в версионируемые файлы](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), чтобы следующая сессия могла проверить состояние.
## Конечный автомат фичи
@@ -111,7 +111,7 @@ flowchart LR
**Режим позвоночника**: у каждой фичи чёткое состояние и команда верификации. Новая сессия читает список фич и за 3 минуты знает: F01–F05 — `passing`, F06 — `active`, F07–F10 — `not_started`. Сразу подхватывает с F06, никаких переделок.
-Количественно: проекты со структурированными списками фич показывают на 45% более высокую долю завершения по сравнению со свободной формой учёта, при нулевом дублировании реализаций.
+Структурированный список собирает состояние каждой фичи и команду верификации в одном месте, поэтому новая сессия знает, что уже сделано.
## Главные выводы
diff --git a/docs/ru/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/ru/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
index e0dc7a2..224c8dd 100644
--- a/docs/ru/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
+++ b/docs/ru/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -70,7 +70,7 @@ Anthropic обнаружила более глубокий паттерн про
| Архитектура | Время | Стоимость | Основные фичи работают? |
|--------------|---------|------|------------------------|
| Одиночный агент (bare run) | 20 мин | $9 | Нет (игровые сущности не реагируют на ввод) |
-| Три агента (planner + generator + evaluator) | 6 часов | $200 | Да (игра полностью играбельна) |
+| Три агента (planner + generator + evaluator) | 6 часов | $200 | Основной геймплей работал; проблемы с физикой и уровнем остались |
Это та же самая модель (Opus 4.5) с тем же самым промптом («создать 2D ретро-игровой редактор»). Единственная разница — harness: от «bare run» к «планировщик разворачивает требования → генератор реализует фича за фичей → оценщик выполняет реальное клик-тестирование через Playwright».
@@ -119,7 +119,7 @@ OpenAI внедрила особенно эффективный паттерн
**Фактические вычеты баллов**: (1) Сквозной поток не протестирован — фактическая отправка и верификация ссылки сброса никогда не подтверждались. (2) Миграция БД упала после частичного выполнения, вызвав несогласованность схемы. (3) Конфигурация email-сервиса отсутствовала в целевом окружении.
-**Вмешательство harness'а**: Принудительная валидация завершения — (1) Запустить полное приложение для проверки доступности эндпоинта сброса; (2) Выполнить полный поток сброса; (3) Верифицировать согласованность состояния БД. Все дефекты были обнаружены в рамках сессии, сэкономив в 5–10 раз стоимость последующих исправлений. Независимый проверяющий нашёл реальные проблемы.
+**Вмешательство harness'а**: Принудительная валидация завершения — (1) Запустить полное приложение для проверки доступности эндпоинта сброса; (2) Выполнить полный поток сброса; (3) Верифицировать согласованность состояния БД. Все дефекты всплывают внутри сессии, пока стоимость исправления ещё локальна. Независимый проверяющий нашёл реальные проблемы.
## Ключевые выводы
diff --git a/docs/ru/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/ru/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
index 4d6707a..206162d 100644
--- a/docs/ru/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
+++ b/docs/ru/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -132,7 +132,7 @@ FIX: Перенесите файловые операции в src/preload/file-
| Проблема разрешений | Различные разрешения в упакованном окружении | Пропущен | Пойман |
| Распространение ошибок | Исключения сервисного слоя не достигли слоя UI | Пропущен | Пойман |
-Все 5 дефектов были пойманы сквозными тестами, в то время как юнит-тесты не поймали ни одного. Стоимость — увеличение времени тестирования с 2 секунд до 15 секунд — полностью приемлемо в workflow агента. Как бы хорошо каждая часть ни пела индивидуально, это не заменит полную совместную репетицию.
+Все 5 дефектов были пойманы сквозными тестами, в то время как юнит-тесты не поймали ни одного. Сквозной прогон идёт медленнее, но эта цена мала по сравнению с пятью граничными дефектами, ушедшими в релиз. Как бы хорошо каждая часть ни пела индивидуально, это не заменит полную совместную репетицию.
## Ключевые выводы
diff --git a/docs/ru/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/ru/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
index da9668f..be2fe40 100644
--- a/docs/ru/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
+++ b/docs/ru/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -44,7 +44,7 @@ flowchart LR
**Ретраи превращаются в слепые догадки**: когда агент не знает, почему что-то не сработало, направление ретрая случайно. Он может многократно пытаться в неверном направлении — чинить несвязанные пути кода, игнорируя реальную корневую причину сбоя. Каждый слепой ретрай стоит токенов и времени.
-**Информационный обрыв при передаче сессии**: когда незавершённая работа передаётся следующей сессии, отсутствие наблюдаемости означает, что новая сессия должна диагностировать состояние системы с нуля. Наблюдения Anthropic за долгоработающими агентами показывают, что эта избыточная диагностика может съедать 30–50% общего времени сессии.
+**Информационный обрыв при передаче сессии**: когда незавершённая работа передаётся следующей сессии, отсутствие наблюдаемости означает, что новая сессия должна диагностировать состояние системы с нуля. Новой сессии приходится перечитывать код, заново запускать команды и решать, какие сигналы важны; [версионируемые записи прогресса и верификации](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) дают состояние, которое можно проверить.
### Реальный сценарий с Claude Code
@@ -54,7 +54,7 @@ flowchart LR
**С полной наблюдаемостью**: планировщик выдаёт sprint contract — список компонентов для модификации, стандарты верификации для каждого и исключения (никаких стилей для печати). Генератор реализует согласно контракту. Рантайм-наблюдаемость фиксирует процесс загрузки и применения стилей для каждого компонента. Оценщик использует балльную рубрику для оценки по измерениям с конкретными ссылками на доказательства. Одна итерация даёт высококачественный результат, около 15 минут.
-Разница в эффективности в 3 раза. Единственное изменение — наблюдаемость.
+Разница в том, существуют ли контракт и доказательства вне головы агента.
### Почему агенты не могут решить это сами
@@ -128,7 +128,7 @@ Harness, использующий воркфлоу «планировщик-ге
- Балльная рубрика обеспечивает структурированную оценку по измерениям
- Одна итерация даёт высококачественные результаты, 15 минут
-Прирост эффективности в 3 раза, более стабильное качество, воспроизводимые оценки.
+Более стабильное качество и воспроизводимые оценки.
## Ключевые выводы
@@ -136,7 +136,7 @@ Harness, использующий воркфлоу «планировщик-ге
- **Оба слоя наблюдаемости обязательны** — рантайм-сигналы объясняют «что произошло», процессные артефакты объясняют «почему это сделано именно так».
- **Sprint contracts заранее выравнивают понимание** — предотвращают ситуации, когда «генератор построил то, что оценщик сразу отвергает по предсказуемым причинам».
- **Балльные рубрики делают оценку воспроизводимой** — разные оценщики выдают схожие баллы для одного и того же выхода.
-- **Отсутствие наблюдаемости тратит 30–50% времени сессии на избыточную диагностику.**
+- **Наблюдаемость превращает расплывчатое «не то» в конкретный, исправимый дефект.**
## Дополнительное чтение
diff --git a/docs/ru/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/ru/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
index 58390cb..d73beef 100644
--- a/docs/ru/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
+++ b/docs/ru/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -54,7 +54,7 @@ flowchart LR
Законы эволюции ПО Лемана говорят нам: системы, подвергающиеся непрерывным изменениям, неизбежно усложняются, если ими активно не управлять. Это особенно верно для AI-агентов кодинга — каждая сессия вносит изменения, и без очистки на выходе технический долг накапливается экспоненциально.
-Реальные данные красноречивы. Проект, разрабатывавшийся с агентами 12 недель без стратегии очистки:
+Для гипотетического 12-недельного проекта без стратегии очистки предположим следующие значения:
- Неделя 1: успех сборки 100%, успех тестов 100%, запуск новой сессии 5 мин
- Неделя 4: сборка 95%, тесты 92%, запуск 15 мин
@@ -66,7 +66,7 @@ flowchart LR
- Неделя 1: 100%, 100%, 5 мин
- Неделя 12: 97%, 95%, 9 мин
-После 12 недель: успех сборки отличается на 29 процентных пунктов, время запуска новой сессии — на 85%. Это не теория — это наблюдаемая разница.
+Еженедельный цикл очистки удерживает стартовое состояние стабильным: каждая сессия заканчивается с собранным кодом, проходящими тестами, обновлённым прогрессом и убранными временными артефактами, поэтому следующая начинается с той же базовой линии.
### Пять измерений чистого состояния
@@ -76,7 +76,7 @@ flowchart LR
**Измерение тестов**: проходят ли все тесты? Включая тесты, существовавшие до сессии — сессия отвечает за то, чтобы не сломать существующую функциональность. И это должно быть проверено в CI, а не только «работает у меня на машине».
-**Измерение прогресса**: зафиксирован ли текущий прогресс в машиночитаемом артефакте? Завершённые подзадачи с критериями их прохождения, начатые, но незавершённые подзадачи с текущим состоянием, ещё не начатые подзадачи. Хорошие записи прогресса сокращают 60–80% времени диагностики при старте сессии.
+**Измерение прогресса**: зафиксирован ли текущий прогресс в машиночитаемом артефакте? Завершённые подзадачи с критериями их прохождения, начатые, но незавершённые подзадачи с текущим состоянием, ещё не начатые подзадачи. Записывайте прогресс и результаты верификации в версионируемые файлы, чтобы следующая сессия могла проверить состояние.
**Измерение артефактов**: есть ли устаревшие или неоднозначные временные артефакты? Дебаг-логи, временные файлы, закомментированный код, TODO-маркеры — всё это увеличивает когнитивную нагрузку для следующей сессии.
@@ -160,7 +160,7 @@ Electron-приложение, разрабатываемое с агентам
**Со стратегией очистки** (экспериментальная группа): полная проверка чистого состояния в конце каждой сессии + еженедельный cleanup loop. Неделя 12, успех сборки 97%, успех тестов 95%, запуск новой сессии 9 мин, устаревших артефактов 11.
-К 12-й неделе у экспериментальной группы успех сборки выше на 29 процентных пунктов, успех тестов — на 34 пункта, время запуска новой сессии ниже на 85%.
+К 12-й неделе у группы с очисткой сборка и тесты остаются близко к стартовым значениям, новая сессия стартует быстро, а устаревших артефактов мало. Очистка добавляет несколько минут на сессию, но даёт стартовое состояние, которому следующая сессия может доверять.
## Ключевые выводы
diff --git a/docs/ru/lectures/lecture-13-loop-engineering/index.md b/docs/ru/lectures/lecture-13-loop-engineering/index.md
index f09467f..70cee15 100644
--- a/docs/ru/lectures/lecture-13-loop-engineering/index.md
+++ b/docs/ru/lectures/lecture-13-loop-engineering/index.md
@@ -84,11 +84,11 @@ Loop Engineering, тема этой лекции — не о какой-то о
Вам не нужно каждый раз вводить `/goal`. Но понимание того, откуда она взялась и почему выглядит именно так — это понимание ядра loop engineering. Более сложные циклы просто добавляют такие части, как планирование, параллелизм, изоляция и память, поверх этих же трёх основ: цель, верификация, условие остановки.
-## Июнь 2026: Три человека зажгли один и тот же фитиль за одну неделю
+## Разные даты, одно направление
-В первую неделю июня 2026 года три практика, строящих инфраструктуру для кодовых агентов — не обмениваясь заметками — сказали одно и то же разными словами.
+Одна и та же идея всплыла в разных местах и в разное время.
-**Питер Стайнбергер** (создатель OpenClaw, [его пост набрал 8 миллионов просмотров](https://x.com/steipete/status/2063697162748260627)): «Вы больше не должны делать запросы к кодовым агентам. Вы должны проектировать циклы, которые делают запросы к вашим агентам.»
+**Питер Стайнбергер** (создатель OpenClaw, [в посте](https://x.com/steipete/status/2063697162748260627)): «Вы больше не должны делать запросы к кодовым агентам. Вы должны проектировать циклы, которые делают запросы к вашим агентам.»
**Борис Черный** (руководитель Claude Code в Anthropic, [на подкасте Acquired](https://x.com/rohanpaul_ai/status/2063289804708835412)): «Я больше не делаю запросы к Claude. У меня запущены циклы, которые делают запросы к Claude и решают, что делать. Моя работа — писать циклы.»
@@ -96,9 +96,9 @@ Loop Engineering, тема этой лекции — не о какой-то о
> **Loop engineering — это замена себя как человека, который делает запросы к агенту. Вы проектируете систему, которая делает это вместо вас.**
-Черный сообщил цифры: более 30 дней подряд все вклад кода в Claude Code вносились автономно ИИ — 259 слитых PR, более 80% производственного кода, написанного Claude, и 76% успеха в открытых программных задачах.
+Черный написал в [личном отчёте от 2025-12-27](https://twitter.com/bcherny/status/2004887829252317325), что за 30 дней слил 259 PR — 497 коммитов, 40 000 добавленных строк и 38 000 удалённых, — и что каждая строка написана Claude Code + Opus 4.5.
-Три человека. Одна неделя. Один и тот же вывод. Не потому, что они скоординировались — а потому, что инфраструктура тихо пересекла порог. Агенты стали достаточно надёжными, чтобы завершать нетривиальные задачи без присмотра. Примитивы планирования (`/loop`, `/goal`, cron) теперь встроены в инструменты. Стоимость одного запуска агента упала достаточно низко, чтобы запускать его повторно по таймеру перестало выглядеть расточительным. Когда все части на месте, шаг, который их объединяет, становится очевидным для всех сразу.
+Цитаты относятся к разным датам, форматам и командам. Их общее направление — вынести планирование, верификацию и решение об остановке из сиюминутного промпта в систему. К середине 2026 года агенты могли самостоятельно доводить нетривиальные задачи до конца, примитивы планирования были встроены в инструменты, а запуск стоил достаточно дёшево, чтобы повторять его по таймеру. Когда части на месте, их вместе собирает не один человек.
> Источник: [Addy Osmani: Loop Engineering](https://addyosmani.com/blog/loop-engineering/)
@@ -267,7 +267,7 @@ flowchart TD
Это уже не один запуск агента. Это непрерывно работающая система, которая просыпается каждое утро, сама убирает пол и ставит то, что требует вашего внимания, перед вами. Ваша роль становится такой: **проверять содержимое входящих, принимать решения и, когда вы замечаете закономерность, с которой система не может справиться, уточнять навыки и правила.**
-Черный использовал этот паттерн, чтобы слить 259 PR за 30 дней, ни разу не открыв IDE. Инженеры OpenAI использовали тот же паттерн, чтобы построить бета-продукт примерно на миллион строк — без написания ни одной строки кода самими.
+Отчёт Черного за 30 дней — одна точка данных для этого паттерна: 259 PR, код написан Claude Code + Opus 4.5. [Отчёт OpenAI о harness](https://openai.com/index/harness-engineering/) — другая: небольшая команда пять месяцев работала с Codex над репозиторием с нуля и сообщила примерно о миллионе строк и около 1500 PR.
## Разделение генератора и оценщика: Почему нельзя позволять модели проверять свою собственную работу
@@ -293,7 +293,7 @@ flowchart TD
Если вы хотите увидеть, как выглядит хорошо спроектированный, реально работающий цикл — [autoresearch Карпати](https://github.com/karpathy/autoresearch) это учебный пример.
-В марте 2026 года Карпати выпустил 630-строчный Python-проект. Дайте ему один GPU и направление исследований, и он работает всю ночь — выполняя сотни экспериментов ML-обучения, сохраняя только те, которые действительно улучшают результат. Проект набрал 66 000+ звёзд в течение дней после релиза.
+В марте 2026 года Карпати выпустил [autoresearch](https://github.com/karpathy/autoresearch). Репозиторий намеренно небольшой: `prepare.py` — фиксированная инфраструктура, `train.py` — файл, который правит агент (около 630 строк), а `program.md` — методология исследования, которую правит человек. Дайте ему один GPU и направление исследований, и он работает всю ночь: каждый эксперимент получает фиксированный 5-минутный бюджет обучения по настенным часам (без учёта запуска и компиляции), и сохраняются только изменения, улучшающие `val_bpb`.
### Три файла, три роли
@@ -343,9 +343,9 @@ flowchart TD
8b --> 9
```
-Он выполняет примерно 12 экспериментов в час. Ночная сессия (8 часов) — это около 100 экспериментов. Сам Карпати запускал его 2 дня — ~700 экспериментов.
+README оценивает примерно 12 экспериментов в час, то есть около 100 за 8-часовую ночную сессию. 5-минутный бюджет покрывает обучение, а не запуск и компиляцию; остальное время каждого раунда уходит на редактирование, запуск и оценку. Карпати сообщил, что гонял приватную версию autoresearch автономно около двух дней для раунда nanochat, описанного ниже.
-Фиксированный 5-минутный бюджет реального времени — ключевой дизайнерский выбор: независимо от того, что агент меняет, каждый эксперимент занимает ровно столько же времени. Это означает, что все результаты напрямую сравнимы при одинаковом бюджете времени — без споров о «этот запускался дольше, поэтому он лучше».
+Фиксированный 5-минутный бюджет обучения — ключевой дизайнерский выбор: независимо от того, что агент меняет, прогон обучения получает одинаковый бюджет настенного времени. Это означает, что все результаты напрямую сравнимы при одинаковом бюджете обучения.
### Вывод: Что вы видите, когда просыпаетесь
@@ -375,13 +375,9 @@ timestamp commit_hash val_bpb vram_mb description
### Что он реально нашёл
-Результаты начального 2-дневного запуска Карпати с ~700 экспериментами:
+Результаты [первого раунда](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b) autoresearch: время обучения nanochat на уровне GPT-2 на 8×H100 [сократилось с **2,02 часа до 1,80 часа**](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b), то есть примерно на **10,9%**.
-- Из ~700 попыток было найдено примерно **20 складывающихся реальных улучшений**
-- Время обучения nanochat на уровне GPT-2 на 8×H100 сократилось с **2,02 часа → 1,80 часа**, примерно **на 11% быстрее**
-- Находки включали: корректировки скорости обучения, тюнинг оптимизатора, замены активации, оптимизации паттернов внимания и т.д.
-
-Все ли улучшения были потрясающими открытиями? Нет. Большинство были небольшими оптимизациями, которые складывались вместе. Но эти 20 действительных улучшений заняли бы у человеческого исследователя недели ручной работы — агент сделал это за 48 часов.
+Большинство изменений были небольшими оптимизациями, которые складывались. Полезная часть — сам цикл: фиксированный бюджет, полный журнал экспериментов и правило, по которому остаются только проверенные улучшения.
### Самый говорящий деталь: Цикл написан на английском, а не на коде.
@@ -399,7 +395,7 @@ timestamp commit_hash val_bpb vram_mb description
### 2. Деградация понимания
-Чем быстрее цикл поставляет код, тем дальше ваше понимание собственной кодовой базы уходит от реальности. У команды Черного 80% кода было написано агентами — что означает, что большая часть кода команды не была написана человеком. Если вы не читаете и не используете то, что производит цикл, ваше понимание непрерывно деградирует. **Быстрые циклы требуют быстрого чтения.**
+Чем быстрее цикл поставляет код, тем дальше ваше понимание собственной кодовой базы уходит от реальности. Цикл сливает сотни PR; команда читает эти PR, просматривает важные диффы и продолжает пользоваться кодом, поэтому её мысленная модель не отстаёт. Если вы не читаете и не используете то, что производит цикл, ваше понимание непрерывно деградирует. **Быстрые циклы требуют быстрого чтения.**
### 3. Когнитивная капитуляция
@@ -407,11 +403,11 @@ timestamp commit_hash val_bpb vram_mb description
### 4. Раздувание токенов
-Каждая итерация цикла накапливает больше контекста: написанный код, встреченные ошибки, принятые решения. Без управления контекстом размер запроса растёт примерно квадратично с количеством шагов. Codex решает это с помощью автоматического уплотнения контекста — специальное API сжимает старые повороты разговора в зашифрованные сводки содержания, сохраняя существенные знания при отбрасывании избыточных деталей. Это инженерный вопрос, который вы должны решить с самого первого цикла, а не прикручивать позже.
+Каждая итерация цикла накапливает больше контекста: написанный код, встреченные ошибки, принятые решения. Когда каждый раунд добавляет примерно фиксированный объём нового содержимого, длина истории, которую видит один раунд, растёт примерно линейно с числом раундов. Если система заново обрабатывает всю историю каждый раунд, суммарный вход за N раундов растёт примерно квадратично. Codex решает это с помощью автоматического уплотнения контекста — специальное API сжимает старые повороты разговора в зашифрованные сводки содержания, сохраняя существенные знания при отбрасывании избыточных деталей. Это инженерный вопрос, который вы должны решить с самого первого цикла, а не прикручивать позже.
## Построение вашего первого цикла
-Вам не нужно начинать с конвейера масштаба Stripe, сливающего 1300 PR в неделю. Начните с самой маленькой вещи, которая работает.
+Вам не нужно начинать с высокопроизводительного конвейера. Начните с самой маленькой вещи, которая работает.
### Шаг 1: Выберите одну повторяющуюся задачу
diff --git a/docs/ru/lectures/lecture-14-graph-engineering/index.md b/docs/ru/lectures/lecture-14-graph-engineering/index.md
index 120703e..fd9eca9 100644
--- a/docs/ru/lectures/lecture-14-graph-engineering/index.md
+++ b/docs/ru/lectures/lecture-14-graph-engineering/index.md
@@ -9,7 +9,7 @@
> «Мы всё ещё говорим о циклах, или уже перешли к графам?»
-Один твит — около 570 тысяч просмотров за день, к концу месяца выросло до примерно 3 миллионов. Через несколько часов ML-инженер Хамел Хусейн опубликовал статью под названием *Loop Engineering Is Dead. Enter Graph Engineering* — весь текст которой был одной GIF-картинкой «Stop it» — и набрал ещё около 680 тысяч просмотров.
+Один твит. Через несколько часов ML-инженер Хамел Хусейн опубликовал статью под названием *Loop Engineering Is Dead. Enter Graph Engineering* — весь текст которой был одной GIF-картинкой «Stop it».
Ещё интереснее: **оба они шутили.** Один высмеивал индустрию, которая каждые шесть недель придумывает новый термин, другой подыгрывал этому мему. Но шутка прожила примерно один уикенд — курсы, роадмапы и технологические стеки заполонили таймлайн ещё до его конца, а за ними потянулся и ворох выдуманных цифр: «+18% точности, −85% стоимости» — это фейк (18% и 85% действительно существуют, но взяты из статьи о химических трубопроводных схемах и сравниваются с совершенно другими базовыми линиями), так же как и «Microsoft, Stanford и Anthropic одновременно обнаружили графовую инженерию». Факт-чекинг подтверждает единственного настоящего «первопроходца» — Джоша Симмонса: его *We Are Entering the Graph Engineering Phase* датирован 4 июля, на две полные недели раньше этой шутки. **Шутка сделала идею модной. Но она не создала идею.**
@@ -257,11 +257,11 @@ run(graph, entry={"requirements": "исправить баг на страниц
## Open-source-проекты: те, что появились после релиза, и те, что были до него
-Сначала проведём границу: **Graph Engineering — это имя, появившееся после 18 июля 2026 года.** Фреймворки, открытые до этого, — не «проекты после релиза Graph Engineering». Реально появившийся после взрыва концепции и прямо называющийся этим именем open-source-проект, по состоянию на начало августа 2026 года, держится один:
+**Graph Engineering — это имя, появившееся после 18 июля 2026 года.** Фреймворки, открытые до этого, — не «проекты после релиза Graph Engineering». Один проект, который прямо использует это имя, — GraphARC:
**Появившиеся после релиза концепции**
-- [GraphArc](https://github.com/CodeGraphContext/grapharc) (2026-08-02): позиционирует себя как «первую живую реализацию Graph Engineering». Он превращает исполнение агентов из trace, зарытого в логах, в **интерактивный оркестрационный граф в реальном времени** — каждый агент, каждая зависимость, каждая точка принятия решения нарисованы, вся картина визуализируется до исполнения, и вы подтверждаете (можно даже с телефона) перед тем, как он даст добро. Автор по опыту делал графовые инструменты для 4000+ разработчиков, направление — «наблюдаемость, отлаживаемость, инженеризируемость». Совсем свежий, функциональность ещё ранняя.
+- [GraphARC](https://github.com/CodeGraphContext/GraphARC) (создан в июле 2026): описывает себя как «an end to end implementation of Graph Engineering as proposed by Andrew NG and Peter Steinberger». Это ранний Python-проект. Полезный ход — прочитать его модель оркестрации и решить, подходит ли подход вашему рабочему процессу.
**Существовавшие до релиза концепции (они не называются Graph Engineering, но именно их вы будете использовать при сборке)**
@@ -325,7 +325,7 @@ run(graph, entry={"requirements": "исправить баг на страниц
- [goddaehee: Факт-чекинг Graph Engineering (корейский, 2026-07-30)](https://goddaehee.tistory.com/628) — самый полный факт-чекинг: таймлайн происхождения шутки, разбор фейковых цифр, данные LangGraph, сравнение популярности на Hacker News
- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — серьёзная статья за две недели до той шутки
- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — официальный ответ: «не новая идея, а новое имя для существующего подхода»; 65 млн+ загрузок LangGraph в месяц
-- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — данные распространения хайпа (первый твит — 575 тыс. просмотров)
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — повествование о том, как распространился этот термин
- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — горизонтальное сравнение семи популярных open-source фреймворков: LangGraph, CrewAI, Microsoft Agent Framework, LlamaIndex, Google ADK, OpenAI Agents SDK, Mastra
- [Официальная документация LangGraph](https://docs.langchain.com/oss/python/langgraph/graph-api) — «Nodes do the work, edges tell what to do next»; точные определения узлов и рёбер, первоисточник при построении графа
- [Anthropic: Building Effective Agents (Dec 2024)](https://www.anthropic.com/engineering/building-effective-agents) — пять паттернов, нарисованные — это графы; авторитетное различие workflow и агента
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.md
index 10712c7..1fdfd3c 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
@@ -9,13 +9,13 @@ Kendinizi yapay zeka dünyasında tecrübeli sayıyorsunuz — Claude Pro abonel
İlk içgüdünüz nedir? "Bu model yeterli değil. Yükseltme zamanı." Bir dakika durun. Cüzdanınıza uzanmadan önce, sorunun model olmama ihtimalini de düşünün.
-Birkaç sayıya bakalım. 2025'in sonlarında SWE-bench Verified üzerindeki en güçlü kod yazma ajanları yaklaşık %50-60'a ulaşıyor. Üstelik bu, net açıklamaları ve mevcut test senaryoları olan, özenle seçilmiş görevlerde. Günlük geliştirme ortamınıza geçin — belirsiz gereksinimler, mevcut testin olmaması, her yere dağılmış örtük iş kuralları — ve bu sayı yalnızca düşer.
+29 Eylül 2025'te Anthropic, Claude Sonnet 4.5'in SWE-bench Verified üzerinde [%77,2 başarı oranına](https://www.anthropic.com/news/claude-sonnet-4-5) ulaştığını bildirdi. Bu sayı ilk bakışta fena görünmüyor — ama hemen sevinmeyin: bunlar net açıklamaları ve mevcut test senaryoları olan, özenle seçilmiş görevler. Günlük geliştirme ortamınıza geçin — belirsiz gereksinimler, mevcut testin olmaması, her yere dağılmış örtük iş kuralları — ve bu sayı yalnızca düşer.
Ama bu sayıların ardında sezgilere ters bir gerçek yatıyor.
## Aynı at, farklı kaderler
-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.
+Anthropic aynı prompt'u ("2B retro oyun yapımcısı geliştir") ve aynı modeli (Opus 4.5) iki farklı harness altında karşılaştırdı. İlk koşu: çıplak, hiçbir destek yok — 20 dakika, 9 dolar; uygulama açıldı ama varlıklar girdiye yanıt vermedi. İkinci koşu: tam harness (planlayıcı + üretici + değerlendirici üç-ajan mimarisi) — 6 saat, 200 dolar; yazar bir varlığı hareket ettirebildi ama fizik pürüzlüydü ve bir duvar ilerlemeyi engelledi. [Temel oynanış çalıştı; uygulama tamamlanmadı.](https://www.anthropic.com/engineering/harness-design-long-running-apps)
Modeli değiştirmediler. Opus 4.5 yine Opus 4.5'ti. Değişen şey koşum takımıydı.
@@ -39,9 +39,9 @@ Birden fazla oturuma yayılan uzun görevler daha da kötüdür — önceki otur
Bu 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.
+- **Yetenek farkı (Capability Gap)**: Modelin benchmark performansı ile gerçek görev performansı arasındaki büyük uçurum. Benchmark görevleri net hata açıklamaları, testler ve bir ortamla gelir; gerçek görevler bunları çoğu zaman sizin sağlamanızı gerektirir.
- **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ı.
+- **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. Yukarıdaki retro oyun karşılaştırması buna bir örnektir.
- **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.
- **Bitirme tanımı (Definition of Done)**: Makine tarafından doğrulanabilir bir dizi koşul — testler geçer, lint temizdir, tip kontrolleri geçer. Açık bir bitirme tanımı olmadan ajan kendi tanımını uyduracaktır.
@@ -72,7 +72,7 @@ Tamamlanma kriterleri:
## Milyon satırlık deney
-OpenAI 2025'te iddialı bir deney yaptı: boş bir git deposundan tam bir iç ürün geliştirmek için Codex kullanın. Beş ay sonra depo yaklaşık bir milyon satır kod içeriyordu — uygulama mantığı, altyapı, araçlar, dokümantasyon, dahili geliştirici araçları — hepsi ajan tarafından üretilmişti. Üç mühendis Codex'i yönetti, yaklaşık 1.500 PR açıp birleştirdi. Kişi başına günde ortalama 3,5 PR.
+Ağustos 2025'te OpenAI'de üç mühendis iddialı bir deney başlattı: boş bir git deposundan tam bir iç ürün geliştirmek için yalnızca Codex kullanılacaktı. [Beş ay sonra depo yaklaşık bir milyon satır kod içeriyordu](https://openai.com/index/harness-engineering/) — uygulama mantığı, altyapı, araçlar, dokümantasyon, dahili geliştirici araçları — hepsi ajan tarafından üretilmişti. Ekip sonradan yedi mühendise çıktı; dönem boyunca yaklaşık 1.500 PR açıp birleştirdiler. Mühendis başına günde ortalama 3,5 PR.
Temel kısıt: **insanlar asla doğrudan kod yazmadı.** Bu bir gösteri değildi — mühendisin birincil işi artık kod yazmak değil, ortamları tasarlamak, niyeti ifade etmek ve geri bildirim döngüleri kurmak olduğunda neyin değiştiğini takımın anlamasını zorlamak için tasarlanmıştı.
@@ -86,9 +86,9 @@ Bu deney bu dersin temel tezini doğrudan kanıtlıyor: **aynı model çıplak b
Bir takım orta ölçekli bir Python web uygulamasına (FastAPI + PostgreSQL + Redis, ~15.000 satır kod) yeni bir API uç noktası eklemek için Claude Sonnet kullandı.
-Başlangıçta yalnızca tek bir cümle verdiler: "`/api/v2/users` altında kullanıcı tercihleri uç noktaları ekle." Sonuç? Ajan, bağlam penceresinin %40'ını depo yapısını keşfetmek için harcadı, makul görünen ama projenin hata işleme kalıplarını izlemeyen kod üretti, eski SQLAlchemy sözdizimini kullandı ve uç nokta çalışma zamanı hataları içerirken tamamlandığını ilan etti. Sonraki oturumun tüm keşif çalışmasını yeniden yapması gerekti.
+Başlangıçta yalnızca tek bir cümle verdiler: "`/api/v2/users` altında kullanıcı tercihleri uç noktaları ekle." Sonuç? Ajan, oturumun büyük bölümünü depo yapısını keşfetmek için harcadı, makul görünen ama projenin hata işleme kalıplarını izlemeyen kod üretti, eski SQLAlchemy sözdizimini kullandı ve uç nokta çalışma zamanı hataları içerirken tamamlandığını ilan etti. Sonraki oturumun tüm keşif çalışmasını yeniden yapması gerekti.
-Daha sonra `AGENTS.md` (proje mimarisi ve teknoloji yığını sürümlerini açıklayan), açık doğrulama komutları (`pytest tests/api/v2/ && python -m mypy src/`) ve mimari karar kayıtları eklediler. Aynı model üç bağımsız koşuda da başarılı oldu, ~%60 daha iyi bağlam verimliliği ile.
+Daha sonra `AGENTS.md` (proje mimarisi ve teknoloji yığını sürümlerini açıklayan), açık doğrulama komutları (`pytest tests/api/v2/ && python -m mypy src/`) ve mimari karar kayıtları eklediler. Aynı model ardından projenin konvansiyonlarına uydu ve işini çalıştırabildiği komutlarla doğruladı.
Modeli değiştirmediler. Harness'ı değiştirdiler.
diff --git a/docs/tr/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/tr/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
index 5d40ace..2393342 100644
--- a/docs/tr/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
+++ b/docs/tr/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -52,7 +52,7 @@ flowchart LR
- **Bağlam pencereleri sonludur**: Hangi pencere boyutu iddia edilirse edilsin (128K, 200K, 1M), uzun görevler sonunda bunları tüketecektir. Tüketildikten sonra ya sıkıştırma (bilgi kaybı) ya da sıfırlama (yeni oturum) gerekir. Her ikisi de bir şey kaybeder.
- **Süreklilik artefaktları**: Yeni bir oturumun geçen oturumun bıraktığı yerden net bir şekilde devam etmesini sağlayan kalıcılaştırılmış durum dosyaları. Temel form: ilerleme günlüğü + doğrulama kaydı + sonraki eylemler. O zanaatkârın günlüğü.
-- **Yeniden inşa maliyeti**: Yeni bir oturumun yürütülebilir bir duruma ulaşması için gereken süre. İyi harness'lar yeniden inşa maliyetini 15 dakikadan 3 dakikaya sıkıştırabilir.
+- **Yeniden inşa maliyeti**: Yeni bir oturumun yürütülebilir bir duruma ulaşması için gereken süre. İyi bir harness ilerlemeyi, doğrulama sonuçlarını ve sonraki eylemleri dosyalarda bırakır; böylece yeni oturum yazılı bir durumdan başlar.
- **Sürüklenme (Drift)**: Ajanın anlayışı ile kod deposunun gerçek durumu arasındaki fark. Her oturum sınırı sürüklenme getirir; kontrol olmadan birikir.
- **Bağlam kaygısı**: Anthropic tarafından gözlemlenen bir olgu — ajanlar algılanan bağlam sınırlarına yaklaştıklarında bilgi kaybını önlemek için görevleri erken bitirerek erken yakınsama davranışı sergiler. Bu mantıksız bir kaynak kaygısıdır.
- **Sıkıştırma vs sıfırlama**: Sıkıştırma aynı oturum içinde bağlamı özetler ("neyi" tutar, "neden"i kaybedebilir); sıfırlama kalıcılaştırılmış durumdan yeniden inşa eden yeni bir oturum açar (temiz ama artefakt eksiksizliğine bağımlıdır).
@@ -160,7 +160,7 @@ LangChain, aynı gpt-5.2-codex ile 89 görevlik Terminal Bench 2.0 skorunun %52,
- Bağlam pencereleri sonlu bir kaynaktır. Uzun görevler oturumları aşacak ve oturumlar bilgi kaybedecektir — her gün unutan zanaatkâr gibi, bu objektif bir gerçektir.
- Çözüm daha büyük pencereler değil — daha iyi durum kalıcılığıdır. İlerleme dosyaları + karar günlükleri + git kontrol noktaları — unutkan zanaatkâra güvenilir bir günlük verin.
- Ajanı amnezili bir mühendis gibi ele alın: "iş çıkışından" önce ne yapıldığını, neden yapıldığını ve sıradakinin ne olduğunu yazın.
-- Yeniden inşa maliyeti kilit metriktir. İyi harness'lar yeni oturumları 3 dakika içinde yürütülebilir bir duruma getirebilmelidir.
+- Yeniden inşa maliyeti kilit metriktir. İyi bir harness ilerlemeyi, doğrulama sonuçlarını ve sonraki eylemleri dosyalarda bırakır; böylece yeni oturum hızla toparlanır.
- Karma strateji: oturumlar içinde kısa görevler, süreklilik için yapılandırılmış artefaktlarla uzun görevler.
## Daha fazla okuma
diff --git a/docs/tr/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/tr/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
index 9d232dc..a195d33 100644
--- a/docs/tr/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
+++ b/docs/tr/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -37,7 +37,7 @@ flowchart TB
## Karıştırdığınızda ne olur
-En doğrudan sorun: temel düzgün oturmaz. Ajan çabasının %80'ini özellik koduna ve %20'sini gelişigüzel bazı altyapı kurmaya harcar. Test çerçevesi yapılandırılır ama hiç doğrulanmaz, lint kuralları ayarlanır ama çok gevşektir, ilerleme dosyası oluşturulmaz. Bu kusurlar ilk oturumda belirgin değildir (çünkü ajan hâlâ ne yaptığını hatırlar), ancak ikinci oturumda yüzeye çıkar — yeni ajan nasıl çalıştırılacağını, test edileceğini veya nerede durduğunu bilmiyor. Özensiz temel, sallantılı bina.
+En doğrudan sorun: temel düzgün oturmaz. Ajan çabasının çoğunu özellik koduna harcar ve altyapıyı sonradan akla gelen bir iş olarak görür. Test çerçevesi yapılandırılır ama hiç doğrulanmaz, lint kuralları ayarlanır ama çok gevşektir, ilerleme dosyası oluşturulmaz. Bu kusurlar ilk oturumda belirgin değildir (çünkü ajan hâlâ ne yaptığını hatırlar), ancak ikinci oturumda yüzeye çıkar — yeni ajan nasıl çalıştırılacağını, test edileceğini veya nerede durduğunu bilmiyor. Özensiz temel, sallantılı bina.
Daha gizli bir maliyet "doğrulanmamış birikme"dir — test çerçevesi yapılandırılmadan önce yazılan özellik kodu doğrulanmamış koddur. Sonunda o kod için test eklemeye geri döndüğünüzde, tasarımın en başından yanlış olduğunu keşfedebilirsiniz — bilseydiniz farklı şekilde uygulayacaktınız. Islak betona fayans döşemek gibi — zeminin düz olmadığını keşfettiğinizde tüm fayansları kaldırıp yeniden döşemek zorundasınız.
@@ -45,7 +45,7 @@ Oturum bütçesi de boşa harcanır. Başlatma işi (ortamları yapılandırma,
En kolay gözden kaçırılan sorun örtük varsayım mayınlarıdır. Ajanın başlatma sırasında verdiği kararlar (hangi test çerçevesi, dizinleri nasıl organize etmek, bağımlılık yönetimi) — açıkça kaydedilmezse, sonraki oturumlar bu seçimleri anlayamaz. Daha kötüsü, sonraki oturumlar çelişen seçimler yapabilir. İlk inşaat ekibi beton temel kullandı, ikinci ekip bilmediği için içine ahşap kazıklar çaktı — temel çatlar.
-Anthropic'in uzun süre çalışan uygulama geliştirme araştırması başlatmayı uygulamadan ayırmayı açıkça önerir. Deneysel verileri: adanmış bir başlatma aşaması kullanan projeler, karışık yaklaşımlara kıyasla çok oturumlu senaryolarda %31 daha yüksek özellik tamamlanma oranı gösterdi. Temel içgörü — başlatma aşamasında yatırılan zaman sonraki 3-4 oturumda tamamen geri kazanılır. Temel ne kadar sağlamsa duvarlar o kadar hızlı yükselir.
+Anthropic'in uzun süre çalışan ajan çalışması [başlatmayı ayrı bir ilk oturum hâline getirir](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents). Başlatıcı bir `init.sh` betiği, bir ilerleme dosyası, bir özellik listesi ve başlangıç git commit'i yazar; sonraki kodlama oturumları bu durumu okur, her seferinde tek bir özellik üzerinde çalışır, uçtan uca test eder, commit eder ve ilerleme dosyasını günceller. Temel ne kadar sağlamsa duvarlar o kadar hızlı yükselir.
OpenAI'nin Codex harness mühendisliği kılavuzu da "operasyonel kayıt olarak depo" ilkesini vurgular — ilk koşudan itibaren net operasyonel yapı kurun, aksi takdirde her yeni oturum proje kurallarını yeniden çıkarmak zorunda kalır.
diff --git a/docs/tr/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/tr/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
index d08c119..e9f7d12 100644
--- a/docs/tr/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
+++ b/docs/tr/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -26,7 +26,7 @@ Claude Code'un gerçek davranışı söyleyicidir. Ona "kullanıcı kaydı ekle"
Altı adım sonra her biri yarı tamamlandı. Uçtan uca doğrulama yok, yarı pişmiş kodlar arasında karmaşık bağlaşım var ve parçaları toplamak için bir sonraki oturum tamamen kayıp olacak. Aynı anda altı yemek pişiren biri gibi — her yemek tencerede ama hiçbiri tabağa konmadı. Hepsi yanıyor.
-Anthropic'in deneysel verileri bunu doğrudan destekliyor: "küçük bir sonraki adım" stratejisi kullanan ajanlar (WIP=1'e eşdeğer) geniş promptlar kullanan ajanlardan %37 daha yüksek görev tamamlanma oranı gösteriyor. Daha ilginç olanı, ajanlar tarafından üretilen kod satırı sayısı gerçek özellik tamamlamasıyla zayıf negatif korelasyona sahiptir — daha fazla kod yazıldı, daha az özellik tamamlandı. Çiğneyebileceğinden fazlasını ısırmak, veriyle kanıtlandı.
+Anthropic'in uzun süre çalışan ajan rehberi [kodlama ajanının her seferinde tek bir özellik üzerinde çalışmasını ister](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents); ardından doğrula, commit et ve ilerlemeyi güncelle. Geniş bir prompt ajanı birkaç iş parçacığı başlatmaya davet eder ve her parçacık aynı bağlam ve doğrulama bütçesi için yarışır.
## WIP=1 iş akışı
diff --git a/docs/tr/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/tr/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
index 306dc3c..42ee58a 100644
--- a/docs/tr/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
+++ b/docs/tr/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -22,7 +22,7 @@ Kullanıcı kimlik doğrulamasını yaptım, alışveriş sepeti çoğunlukla ta
```
Yeni bir ajan oturumu bu nottan şu sorulara cevap verebilir mi? "Çoğunlukla tamam" ne demek? Sepet hangi testleri geçti? Ödemeleri ne engelliyor? Hepsinin cevabı "kimse bilmiyor." Doktorunuza "midem ağrıyor, son zamanlarda iyiydi" demek gibi — hangi ilacı yazabilirler?
-Sonuç: yeni oturum proje durumunu çıkarmak için 20 dakika harcar ve tamamlanmış özellikleri yeniden uygulayabilir. Anthropic'in mühendislik verileri iyi ilerleme kayıtlarının oturum başlatma tanı süresini %60-80 azalttığını gösteriyor.
+Sonuç: yeni oturum proje durumunu çıkarmak zorundadır ve tamamlanmış özellikleri yeniden uygulayabilir. Anthropic'in önerisi, [ilerleme ve doğrulama sonuçlarını sürümlenmiş dosyalara kaydetmektir](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents); böylece bir sonraki oturum durumu inceleyebilir.
## Özellik durum makinesi
@@ -111,7 +111,7 @@ Her özellik öğesi "bir oturumda tamamlanabilir" olacak şekilde kapsamlandır
**Omurga modu**: Her özelliğin net bir durumu ve doğrulama komutu vardır. Yeni oturum özellik listesini okur ve 3 dakika içinde bilir: F01-F05 `passing`, F06 `active`, F07-F10 `not_started`. Doğrudan F06'dan devam eder, sıfır yeniden çalışma.
-Nicel sonuç: yapılandırılmış özellik listeleri kullanan projeler serbest formatlı takipten %45 daha yüksek özellik tamamlanma oranı gösterir, sıfır mükerrer uygulama ile.
+Yapılandırılmış bir liste, her özelliğin durumunu ve doğrulama komutunu tek bir yerde tutar; böylece yeni oturum neyin tamamlandığını bilir.
## Önemli çıkarımlar
diff --git a/docs/tr/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/tr/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
index 20ec464..210a538 100644
--- a/docs/tr/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
+++ b/docs/tr/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -70,7 +70,7 @@ Bu sorun öznel görevlerde (tasarım estetiği gibi) özellikle şiddetlidir
| Mimari | Runtime | Maliyet | Çekirdek özellikler çalışıyor mu? |
|--------------|---------|------|------------------------|
| Tek Ajan (çıplak koşu) | 20 dk | 9$ | Hayır (oyun varlıkları girdiye yanıt vermiyor) |
-| Üç Ajan (planlayıcı + üretici + değerlendirici) | 6 saat | 200$ | Evet (oyun tamamen oynanabilir) |
+| Üç Ajan (planlayıcı + üretici + değerlendirici) | 6 saat | 200$ | Çekirdek oynanış çalıştı; fizik ve seviye sorunları kaldı |
Bu tam olarak aynı model (Opus 4.5) ve tam olarak aynı prompt ("2B retro oyun editörü inşa et"). Tek fark harness — "çıplak çalıştırma"dan "planlayıcı gereksinimleri genişletir → üretici özellik bazında uygular → değerlendirici Playwright kullanarak gerçek tıklama testi yapar"a.
@@ -119,7 +119,7 @@ Etkili runtime sinyalleri şunları içerir:
**Gerçek puan düşürmeleri**: (1) Uçtan uca akış test edilmedi — sıfırlama bağlantısının gerçek gönderimi ve doğrulanması hiçbir zaman onaylanmadı. (2) Veritabanı geçişi kısmi yürütmeden sonra başarısız oldu, şema tutarsızlığına neden oldu. (3) Hedef ortamda e-posta servis yapılandırması eksikti.
-**Harness müdahalesi**: Sonlandırma doğrulaması zorlandı — (1) Sıfırlama uç noktası erişilebilirliğini doğrulamak için tam uygulamayı başlatın; (2) Tam sıfırlama akışını yürütün; (3) Veritabanı durumu tutarlılığını doğrulayın. Tüm kusurlar oturum içinde bulundu, sonraki düzeltmelerin maliyetinin 5-10 katından tasarruf edildi. Bağımsız notlayıcı gerçek sorunları buldu.
+**Harness müdahalesi**: Sonlandırma doğrulaması zorlandı — (1) Sıfırlama uç noktası erişilebilirliğini doğrulamak için tam uygulamayı başlatın; (2) Tam sıfırlama akışını yürütün; (3) Veritabanı durumu tutarlılığını doğrulayın. Üç kusur da oturum içinde yüzeye çıktı ve düzeltme maliyeti hâlâ yereldi. Bağımsız notlayıcı gerçek sorunları buldu.
## Önemli çıkarımlar
diff --git a/docs/tr/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/tr/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
index b13f4b4..775847b 100644
--- a/docs/tr/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
+++ b/docs/tr/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -132,7 +132,7 @@ Kod incelemesi sırasında yeni bir ajan hatası türü bulunduğunda, onu otoma
| İzin sorunu | Paketlenmiş ortamda farklı izinler | Kaçırıldı | Yakalandı |
| Hata yayma | Servis katmanı istisnaları UI katmanına ulaşmadı | Kaçırıldı | Yakalandı |
-5 kusurun hepsi uçtan uca testlerle yakalandı, birim testleri hiçbirini yakalamadı. Maliyet test süresinin 2 saniyeden 15 saniyeye çıkmasıydı — ajan iş akışında tamamen kabul edilebilir. Her parçanın bireysel olarak ne kadar iyi söylediği önemli değil, tam bir ansambl provasını yenemez.
+5 kusurun hepsi uçtan uca testlerle yakalandı, birim testleri hiçbirini yakalamadı. Uçtan uca koşu daha yavaştır, ancak bu maliyet beş sınır hatasını üretime göndermekle karşılaştırıldığında küçüktür. Her parçanın bireysel olarak ne kadar iyi söylediği önemli değil, tam bir ansambl provasını yenemez.
## Önemli çıkarımlar
diff --git a/docs/tr/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/tr/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
index 1cea207..37bd494 100644
--- a/docs/tr/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
+++ b/docs/tr/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -44,7 +44,7 @@ Bir harness gözlemlenebilirlikten yoksun olduğunda dört tür sorun sistematik
**Yeniden denemeler kör tahminlere dönüşür**: Ajan neden başarısız olduğunu bilmediğinde yeniden deneme yönü rastgeledir. Yanlış yönde tekrar tekrar deneyebilir — gerçek başarısızlık kök nedenini göz ardı ederken ilgisiz kod yollarını düzeltebilir. Her kör yeniden deneme token ve zamana mal olur.
-**Oturum devir bilgi uçurumu**: Eksiksiz olmayan iş bir sonraki oturuma teslim edildiğinde, gözlemlenebilirlik eksikliği yeni oturumun sistem durumunu sıfırdan teşhis etmek zorunda olduğu anlamına gelir. Anthropic'in uzun süre çalışan ajan gözlemleri bu gereksiz tanının toplam oturum süresinin %30-50'sini tüketebileceğini gösteriyor.
+**Oturum devir bilgi uçurumu**: Eksiksiz olmayan iş bir sonraki oturuma teslim edildiğinde, gözlemlenebilirlik eksikliği yeni oturumun sistem durumunu sıfırdan teşhis etmek zorunda olduğu anlamına gelir. Yeni oturum kodu yeniden okumak, komutları yeniden çalıştırmak ve hangi sinyallerin önemli olduğuna karar vermek zorundadır; [sürümlenmiş ilerleme ve doğrulama kayıtları](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) incelenebilir bir durum sağlar.
### Gerçek bir Claude Code senaryosu
@@ -54,7 +54,7 @@ Bir harness gözlemlenebilirlikten yoksun olduğunda dört tür sorun sistematik
**Tam gözlemlenebilirlikle**: Planlayıcı bir sprint sözleşmesi çıkarır — hangi bileşenleri değiştireceğini, her biri için doğrulama standartlarını ve hariç tutmaları (yazdırma stilleri yok) listeler. Üretici sözleşmeye göre uygular. Runtime gözlemlenebilirliği her bileşenin stil yükleme ve uygulama sürecini kaydeder. Değerlendirici spesifik kanıt alıntılarıyla boyut boyut değerlendirmek için bir puanlama ölçütü kullanır. Bir iterasyon yüksek kaliteli bir sonuç üretir, yaklaşık 15 dakika.
-3 kat verim farkı. Tek değişen şey gözlemlenebilirlik.
+Fark, sözleşmenin ve kanıtın ajanın kafasının dışında var olup olmamasından geliyor.
### Ajanlar bunu neden kendileri çözemez
@@ -128,7 +128,7 @@ Her harness oturumu için bir iz, her görev için bir span ve her doğrulama ad
- Puanlama ölçütü boyut boyut yapılandırılmış değerlendirme sağlar
- Bir iterasyon yüksek kaliteli sonuçlar üretir, 15 dakika
-3 kat verim iyileştirmesi, daha kararlı kalite, tekrarlanabilir değerlendirmeler.
+Kalite daha kararlı, değerlendirmeler tekrarlanabilir.
## Önemli çıkarımlar
@@ -136,7 +136,7 @@ Her harness oturumu için bir iz, her görev için bir span ve her doğrulama ad
- **Her iki gözlemlenebilirlik katmanı da gereklidir** — runtime sinyalleri "ne oldu"yu, süreç artefaktları "neden bu şekilde yapıldı"yı açıklar.
- **Sprint sözleşmeleri hizalamayı öne çeker** — "üreticinin değerlendiricinin öngörülebilir nedenlerle hemen reddedeceği bir şey inşa etmesi"ni önler.
- **Puanlama ölçütleri değerlendirmeyi tekrarlanabilir yapar** — farklı değerlendiriciler aynı çıktı için benzer puanlar üretir.
-- **Gözlemlenebilirlik eksikliği oturum süresinin %30-50'sini gereksiz tanılara harcar.**
+- **Gözlemlenebilirlik, belirsiz bir reddi spesifik ve düzeltilebilir bir kusura dönüştürür.**
## Daha fazla okuma
diff --git a/docs/tr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/tr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
index 9fe87ee..74ce663 100644
--- a/docs/tr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
+++ b/docs/tr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -54,7 +54,7 @@ flowchart LR
Lehman'ın yazılım evrim yasaları bize şunu söylüyor: sürekli değişime uğrayan sistemler, aktif olarak yönetilmedikçe kaçınılmaz olarak karmaşıklıkta artar. Bu özellikle AI kod yazma ajanları için doğrudur — her oturum değişiklikler getirir ve çıkışta temizlik olmadan teknik borç katlanarak birikir.
-Gerçek veriler söyleyicidir. Temizleme stratejisi olmadan ajanlarla 12 hafta geliştirilen bir proje:
+12 haftalık varsayımsal bir proje için şu değerleri ele alalım:
- Hafta 1: Yapı geçme oranı %100, test geçme oranı %100, yeni oturum başlatma 5 dk
- Hafta 4: Yapı %95, testler %92, başlatma 15 dk
@@ -66,7 +66,7 @@ Aynı proje bir temizleme stratejisiyle:
- Hafta 1: %100, %100, 5 dk
- Hafta 12: %97, %95, 9 dk
-12 hafta sonra: yapı geçme oranı 29 puan, yeni oturum başlatma süresi %85 farklı. Bu teorik değil — gözlemlenen bir farktır.
+Haftalık bir temizleme döngüsü başlangıç durumunu sabit tutar: her oturum yapı, testler, ilerleme ve geçici artefaktlar düzenli olarak biter, böylece bir sonraki oturum aynı temelden başlar.
### Temiz durumun beş boyutu
@@ -76,7 +76,7 @@ Temiz durum yalnızca "kod derler" değildir. Birlikte değerlendirilen beş boy
**Test boyutu**: Tüm testler geçer mi? Oturum öncesi var olan testler dahil — oturum mevcut işlevselliği bozmamaktan sorumludur. Ve "benim makinemde çalışıyor" yerine CI'de doğrulanmalıdır.
-**İlerleme boyutu**: Mevcut ilerleme makine tarafından okunabilir bir artefakta kaydedilmiş mi? Tamamlanan alt görevler geçme kriterleriyle, devam eden ancak tamamlanmayan alt görevler mevcut durumla, henüz başlamamış alt görevler. İyi ilerleme kayıtları oturum başlatma tanı süresini %60-80 azaltır.
+**İlerleme boyutu**: Mevcut ilerleme makine tarafından okunabilir bir artefakta kaydedilmiş mi? Tamamlanan alt görevler geçme kriterleriyle, devam eden ancak tamamlanmayan alt görevler mevcut durumla, henüz başlamamış alt görevler. İlerleme ve doğrulama sonuçlarını sürümlenmiş dosyalara kaydedin, böylece bir sonraki oturum durumu inceleyebilir.
**Artefakt boyutu**: Bayatlamış veya belirsiz geçici artefaktlar var mı? Hata ayıklama günlükleri, geçici dosyalar, yorum satırı yapılmış kod, TODO işaretleri — bunların hepsi bir sonraki oturum için bilişsel yükü artırır.
@@ -160,7 +160,7 @@ npm run test # Temizliğin bir şey bozmadığını doğrula
**Temizleme stratejisiyle** (deneysel grup): Her oturum sonunda tam temiz durum kontrolü + haftalık temizleme döngüsü. Hafta 12, yapı geçme oranı %97, test geçme oranı %95, yeni oturum başlatma 9 dk, bayatlamış artefaktlar 11.
-12 haftaya kadar, deneysel grubun yapı geçme oranı 29 puan, test geçme oranı 34 puan daha yüksek ve yeni oturum başlatma süresi %85 daha düşüktür.
+12. haftaya gelindiğinde temizleme grubunun yapı ve test geçme oranları başlangıç noktasına yakın kaldı, yeni bir oturum hızla başlayabildi ve bayat artefaktlar azdı. Temizleme oturum başına birkaç dakika aldı ve bir sonraki oturumun güvenebileceği bir başlangıç durumu bıraktı.
## Önemli çıkarımlar
diff --git a/docs/tr/lectures/lecture-13-loop-engineering/index.md b/docs/tr/lectures/lecture-13-loop-engineering/index.md
index d77ca97..4b030ce 100644
--- a/docs/tr/lectures/lecture-13-loop-engineering/index.md
+++ b/docs/tr/lectures/lecture-13-loop-engineering/index.md
@@ -84,11 +84,11 @@ Bu dersin konusu olan Loop Mühendisliği, tek bir komutla ilgili değildir. **T
Her seferinde `/goal` yazmak zorunda değilsiniz. Ama nereden geldiğini ve neden göründüğü gibi olduğunu anlamak — loop mühendisliğinin özünü anlamaktır. Daha karmaşık loop'lar sadece zamanlama, paralellik, izolasyon ve bellek gibi parçaları aynı üç temel üzerine ekler: hedef, doğrulama, durdurma koşulu.
-## Haziran 2026: Üç kişi aynı haftada aynı sigortayı yaktı
+## Farklı tarihler, aynı yön
-2026 Haziran'ın ilk haftasında, kodlama ajan altyapısı inşa eden üç pratisyen — notlar karşılaştırmadan — farklı kelimelerle aynı şeyi söyledi.
+Aynı fikir farklı yerlerde, farklı zamanlarda ortaya çıktı.
-**Peter Steinberger** (OpenClaw yaratıcısı, [yazısı 8 milyon görüntüleme ulaştı](https://x.com/steipete/status/2063697162748260627)): "Artık kodlama ajanlarını prompt etmemelisiniz. Ajanlarınızı prompt eden loop'lar tasarlamalısınız."
+**Peter Steinberger** (OpenClaw yaratıcısı, [bir gönderisinde](https://x.com/steipete/status/2063697162748260627)): "Artık kodlama ajanlarını prompt etmemelisiniz. Ajanlarınızı prompt eden loop'lar tasarlamalısınız."
**Boris Cherny** (Anthropic'te Claude Code başkanı, [Acquired podcast'te](https://x.com/rohanpaul_ai/status/2063289804708835412)): "Artık Claude'ı prompt etmiyorum. Claude'ı prompt eden ve ne yapacağını çözen loop'larım var. Benim işim loop yazmak."
@@ -96,9 +96,9 @@ Her seferinde `/goal` yazmak zorunda değilsiniz. Ama nereden geldiğini ve nede
> **Loop mühendisliği, ajanı prompt eden kişi olarak kendinizi değiştirmektir. Onun yerine bunu yapan sistemi tasarlarsınız.**
-Cherny sayıları açıkladı: art arda 30 günden fazla, Claude Code'a tüm kod katkıları AI tarafından özerk olarak yapıldı — 259 merge edilmiş PR, üretim kodunun %80'inden fazlası Claude tarafından yazıldı ve açık uçlu yazılım görevlerinde %76 başarı oranı.
+Cherny, [2025-12-27 tarihli kişisel raporunda](https://twitter.com/bcherny/status/2004887829252317325) 30 gün içinde 259 PR birleştirdiğini — 497 commit, 40.000 satır ekleme, 38.000 satır silme — ve her satırın Claude Code + Opus 4.5 tarafından yazıldığını belirtti.
-Üç kişi. Bir hafta. Aynı sonuç. Koordine oldukları için değil — altyapı sessizce bir eşiği aştığı için. Ajanlar önemsiz olmayan görevleri denetimsiz bitirecek kadar güvenilir hale gelmişti. Zamanlama ilkelleri (`/loop`, `/goal`, cron) artık araçlara yerleşmişti. Tek bir ajan çalıştırmanın maliyeti, bir zamanlayıcıda tekrar tekrar çalıştırmanın israfçı görünmemesini sağlayacak kadar düşmüştü. Tüm parçalar mevcut olduğunda, onları birleştiren hareket herkes için aynı anda açık hale gelir.
+Alıntılar farklı tarihlerden, formatlardan ve ekiplerden geliyor. Ortak yönleri, zamanlama, doğrulama ve durdurma kararını anlık prompt'tan çıkarıp bir sisteme taşımak. 2026 ortalarına gelindiğinde ajanlar önemsiz olmayan görevleri denetimsiz bitirebiliyordu, zamanlama ilkelleri araçlara yerleşmişti ve tek bir koşu bir zamanlayıcıda tekrarlanacak kadar ucuzdu. Parçalar mevcut olduğunda, birden fazla kişi onları bir araya getirir.
> Kaynak: [Addy Osmani: Loop Engineering](https://addyosmani.com/blog/loop-engineering/)
@@ -267,7 +267,7 @@ flowchart TD
Bu artık tek bir ajan çalışması değil. Her sabah uyanan, kendi kendine yeri süpüren ve dikkatinizi gerektiren şeyleri önünüze koyan sürekli çalışan bir sistemdir. Rolünüz şu hale gelir: **gelen kutusu içeriğini gözden geçirin, kararlar verin ve sistemin kaldıramayacağı bir desen gördüğünüzde becerileri ve kuralları iyileştirin.**
-Cherny bu deseni kullanarak 30 günde 259 PR'ı tek bir IDE açmadan merge etti. OpenAI mühendisleri aynı deseni kullanarak kabaca bir milyon satırlık bir beta ürünü elle — tek bir satır kod kendileri yazmadan — inşa ettiler.
+Cherny'nin 30 günlük raporu bu desen için bir veri noktasıdır: 259 PR, kod Claude Code + Opus 4.5 tarafından yazıldı. OpenAI'nin [harness raporu](https://openai.com/index/harness-engineering/) bir başkasıdır: küçük bir ekip Codex'i sıfırdan bir depoda beş ay kullandı ve yaklaşık bir milyon satır ile yaklaşık 1.500 PR bildirdi.
## Üretici/Değerlendirici Ayrımı: Neden Modelin Kendi Çalışmasını Notlandırmasına İzin Veremezsiniz
@@ -293,7 +293,7 @@ Hatırlanacak tek cümle: **ekibinizdeki biri size inanmamalıdır.**
İyi tasarlanmış, gerçekten çalışan bir loop'un neye benzediğini görmek istiyorsanız, [Karpathy'nin autoresearch'ı](https://github.com/karpathy/autoresearch) ders kitabı örneğidir.
-Mart 2026'da Karpathy 630 satırlık bir Python projesi yayınladı. Ona bir GPU ve bir araştırma yönü verin ve bütün gece çalışır — yüzlerce ML eğitim deneyi tamamlar, sadece gerçekten iyileştirenleri tutar. Proje yayınlanmasından birkaç gün içinde 66.000+ yıldıza ulaştı.
+Mart 2026'da Karpathy [autoresearch](https://github.com/karpathy/autoresearch)'ı yayınladı. Depo kasıtlı olarak küçüktür: `prepare.py` sabit altyapıdır, `train.py` ajanın düzenlediği dosyadır (yaklaşık 630 satır) ve `program.md` insanın düzenlediği araştırma metodolojisidir. Ona bir GPU ve bir araştırma yönü verin; bütün gece çalışır — her deney sabit 5 dakikalık bir eğitim duvar saati bütçesi alır (başlatma ve derleme hariç) ve yalnızca `val_bpb`'yi iyileştiren değişiklikler tutulur.
### Üç Dosya, Üç Rol
@@ -343,9 +343,9 @@ flowchart TD
8b --> 9
```
-Saatte kabaca 12 deney çalıştırır. Bir gecelik çalışma (8 saat) yaklaşık 100 deneydir. Karpathy kendisi 2 gün çalıştırdı — ~700 deney.
+README saatte yaklaşık 12 deney, 8 saatlik bir gecelik çalışmada ise yaklaşık 100 deney öngörüyor. 5 dakikalık bütçe eğitimi kapsar, başlatma veya derlemeyi değil; her turun geri kalanı düzenleme, başlatma ve değerlendirmeye gider. Karpathy, aşağıda anlatılan nanochat turu için autoresearch'ın özel bir sürümünü yaklaşık iki gün boyunca özerk olarak çalıştırdığını bildirdi.
-Sabit 5 dakikalık duvar saati bütçesi önemli bir tasarım seçimidir — ajan ne değiştirirse değiştirsin, her deney tam olarak aynı zamanı alır. Bu, tüm sonuçların aynı zaman bütçesi altında doğrudan karşılaştırılabilir olduğu anlamına gelir — "bunun daha uzun süre çalıştığı için daha iyi" tartışması yok.
+Sabit 5 dakikalık eğitim bütçesi önemli bir tasarım seçimidir — ajan ne değiştirirse değiştirsin, eğitim koşusu aynı duvar saati bütçesini alır. Bu, tüm sonuçların aynı eğitim bütçesi altında doğrudan karşılaştırılabilir olduğu anlamına gelir.
### Çıktı: Uyandığınızda ne görürsünüz
@@ -375,13 +375,9 @@ Ajan ne denediğini, neyin işe yaradığını, neyin yaramadığını ve sırad
### Gerçekte ne buldu
-Karpathy'nin ilk 2 günlük ~700 deney çalışmasının sonuçları:
+autoresearch [1. tur](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b) sonuçları, nanochat'in 8×H100 üzerindeki GPT-2 seviyesi eğitim süresini [**2,02 saatten 1,80 saate**](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b) düşürdü — eğitim süresinde yaklaşık **%10,9** azalma.
-- ~700 denemeden yaklaşık **20 yığılabilir gerçek iyileştirme** bulundu
-- nanochat'ın GPT-2 seviyesi eğitim süresini 8×H100'de **2,02 saat → 1,80 saat** olarak azalttı, yaklaşık **%11 daha hızlı**
-- Bulgular şunları içeriyordu: öğrenme oranı ayarlamaları, optimize edici ayarı, aktivasyon değişimleri, dikkat deseni optimizasyonları vb.
-
-Tüm iyileştirmeler yer sarsıcı keşifler miydi? Hayır. Çoğu yığılan küçük optimizasyonlardı. Ama bu 20 geçerli iyileştirme bir insan araştırmacının haftalarca manuel çalışmasını alırdı — ajan 48 saatte yaptı.
+Değişikliklerin çoğu yığılan küçük optimizasyonlardı. İşe yarayan kısım loop'un kendisi: sabit bütçe, eksiksiz deney günlüğü ve yalnızca doğrulanmış iyileştirmelerin kalması kuralı.
### En anlatıcı detay: Loop İngilizce yazılır, kodla değil.
@@ -399,7 +395,7 @@ Hızlı loop'lar sizi doğrulamayı atlamaya kışkırtır. "Güzel görünüyor
### 2. Anlama Çürümesi
-Bir loop kod o kadar hızlı gönderir ki, kendi kod tabanınıza dair anlayışınız gerçeklikten o kadar uzaklaşır. Cherny'nin ekibinin kodunun %80'i ajanlar tarafından yazıldı — yani bir ekibin kodunun çoğu bir kişi tarafından yazılmadı. Loop'un ürettiğini okumaz ve kullanmazsanız, anlayışınız sürekli olarak çürür. **Hızlı loop'lar hızlı okuma gerektirir.**
+Bir loop kod o kadar hızlı gönderir ki, kendi kod tabanınıza dair anlayışınız gerçeklikten o kadar uzaklaşır. Bir loop yüzlerce PR üretir; ekip bu PR'ları okur, önemli diff'leri inceler ve kodu kullanmaya devam eder, böylece zihinsel modeli güncel kalır. **Hızlı loop'lar hızlı okuma gerektirir.**
### 3. Bilişsel Teslimiyet
@@ -407,11 +403,11 @@ Loop sorunsuz çalıştığında, en rahat duruş fikir sahibi olmayı bırakmak
### 4. Token Patlaması
-Bir loop'un her iterasyonu daha fazla bağlam biriktirir: yazılan kod, karşılaşılan hatalar, verilen kararlar. Bağlam yönetimi olmadan, prompt boyutu tur sayısıyla kabaca ikinci dereceden büyür. Codex bunu otomatik bağlam sıkıştırmasıyla ele alır — özel bir API eski konuşma turlarını şifreli içerik özetlerine sıkıştırır, temel bilgiyi korurken gereksiz detayı atar. Bu, ilk loop'tan ele almanız gereken bir mühendislik endişesidir, sonradan takılan bir ek değil.
+Bir loop'un her iterasyonu daha fazla bağlam biriktirir: yazılan kod, karşılaşılan hatalar, verilen kararlar. Her tur yaklaşık sabit miktarda yeni içerik eklediğinde, tek bir turun gördüğü geçmiş uzunluğu tur sayısıyla kabaca doğrusal büyür. Sistem her turda tüm geçmişi yeniden işlerse, N tur boyunca kümülatif girdi kabaca ikinci dereceden büyür. Codex bunu otomatik bağlam sıkıştırmasıyla ele alır — özel bir API eski konuşma turlarını şifreli içerik özetlerine sıkıştırır, temel bilgiyi korurken gereksiz detayı atar. Bu, ilk loop'tan ele almanız gereken bir mühendislik endişesidir, sonradan takılan bir ek değil.
## İlk Loop'unuzu Oluşturmak
-Haftada 1.300 PR merge eden Stripe ölçeğinde bir pipeline ile başlamak zorunda değilsiniz. Çalışan en küçük şeyle başlayın.
+Yüksek verimli bir pipeline ile başlamak zorunda değilsiniz. Çalışan en küçük şeyle başlayın.
### Adım 1: Tekrarlayan Bir Görev Seçin
diff --git a/docs/tr/lectures/lecture-14-graph-engineering/index.md b/docs/tr/lectures/lecture-14-graph-engineering/index.md
index 9ea7b70..256b867 100644
--- a/docs/tr/lectures/lecture-14-graph-engineering/index.md
+++ b/docs/tr/lectures/lecture-14-graph-engineering/index.md
@@ -9,7 +9,7 @@ Loop Engineering ana akıma girdikten altı hafta sonra, 18 Temmuz 2026'da Peter
> "Hâlâ loop'lardan mı bahsediyoruz, yoksa graph'lara mı geçtik?"
-Tek bir tweet — bir gün içinde yaklaşık 570 bin görüntüleme, ay sonuna kadar kabaca 3 milyona ulaştı. Birkaç saat sonra, makine öğrenimi mühendisi Hamel Husain, *Loop Engineering Is Dead. Enter Graph Engineering* başlıklı bir makale yayınladı — gövdesi tek bir "Stop it" GIF'i olan bir makale — ve yaklaşık 680 bin görüntüleme daha topladı.
+Tek bir tweet. Birkaç saat sonra, makine öğrenimi mühendisi Hamel Husain, *Loop Engineering Is Dead. Enter Graph Engineering* başlıklı bir makale yayınladı — gövdesi tek bir "Stop it" GIF'i olan bir makale.
İşin daha da ilginç yanı: **ikisi de şaka olarak atmıştı.** Biri her altı haftada bir yeni terim icat eden bir sektörü hicvediyordu; diğeri şakanın üzerine gidiyordu. Ama şaka yalnızca yaklaşık bir hafta sonu yaşadı — hafta sonu bitmeden kurslar, yol haritaları ve araç yığınları zaman çizelgesine doldu ve arkasında bir yığın uydurma sayı geldi: "+18% doğruluk, −85% maliyet" iddiası sahte (iki sayı gerçekten var ama kimyasal boru hattı şemaları hakkındaki bir makaleden geliyor ve farklı tabanlara karşı karşılaştırılıyor) ve "Microsoft, Stanford ve Anthropic aynı anda graf mühendisliğini keşfetti" iddiası da yanlış. Gerçek denetimi yalnızca tek bir gerçek "öncü" buluyor: Josh Simmons — *We Are Entering the Graph Engineering Phase* adlı yazısı 4 Temmuz tarihli, şakadan tam iki hafta önce. **Şaka fikri popüler yaptı. Fikri yaratmadı.**
@@ -257,11 +257,11 @@ Bittiğinde bunu yukarıdaki diyagramla karşılaştırın: el yazınız `graph.
## Açık Kaynak Projeler: İsimden Sonra, İsimden Önce
-Önce çizgiyi çekin: **"Graph Engineering", yalnızca 18 Temmuz 2026'dan sonra var olan bir isimdir.** O tarihten önce açık kaynak yapılan framework'ler, "Graph Engineering sonrası projeler" değildir. Ağustos 2026 başı itibarıyla, ismi doğrudan taşıyan ve ayakta kalan yalnızca bir açık kaynak proje var:
+Önce çizgiyi çekin: **"Graph Engineering", yalnızca 18 Temmuz 2026'dan sonra var olan bir isimdir.** O tarihten önce açık kaynak yapılan framework'ler, "Graph Engineering sonrası projeler" değildir. İsmi açıkça kullanan bir proje GraphARC:
**İsimden sonra gelen projeler**
-- [GraphArc](https://github.com/CodeGraphContext/grapharc) (2026-08-02): kendisini "Graph Engineering'in ilk gerçek zamanlı uygulaması" olarak adlandırıyor. Ajan yürütmeyi, loglara gömülü trace'lerden **etkileşimli gerçek zamanlı bir orkestrasyon graf'ına** dönüştürüyor — her ajan, her bağımlılık, her karar noktası çizilir, yürütmeden önce tüm graf görselleştirilir ve siz onayladıktan sonra (telefonunuzdan bile bakabilirsiniz) serbest bırakılır. Yazarın geçmişi 4.000+ geliştirici için graf araçları oluşturmaya dayanıyor; yönü "gözlemlenebilir, hata ayıklanabilir, mühendislik yapılabilir". Çok yeni, hâlâ erken aşamada.
+- [GraphARC](https://github.com/CodeGraphContext/GraphARC) (Temmuz 2026'da oluşturuldu): kendisini "Graph Engineering'in, Andrew NG ve Peter Steinberger tarafından önerildiği şekliyle uçtan uca bir uygulaması" olarak tanımlıyor. Erken aşamada bir Python projesi. Kullanışlı hamle, onun orkestrasyon modelini okuyup yaklaşımın iş akışınıza uyup uymadığına karar vermektir.
**İsimden önce gelen projeler (onu Graph Engineering olarak adlandırmıyorlar — ama gerçekten inşa ederken kullanacağınız şeyler) bunlar**
@@ -325,7 +325,7 @@ Her görev bir graf hak etmez. Beş kriter — başlamadan önce en az üçünü
- [goddaehee: Graph Engineering gerçek denetimi (Korece, 2026-07-30)](https://goddaehee.tistory.com/628) — en kapsamlı gerçek denetimi: şaka köken zaman çizelgesi, sahte sayıların parçalanması, LangGraph verisi, Hacker News sıcaklık karşılaştırması
- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — şakadan iki hafta önce yazılmış ciddi makale
- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — resmi yanıt: "yeni bir fikir değil, köklü bir yaklaşımın en yeni adı"; LangGraph'ın 65M+ aylık indirmesi
-- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — moda yayılma verisi (ilk tweet'te 575 bin görüntüleme)
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — terimin nasıl yayıldığına dair bir anlatı
- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — yedi ana akım açık kaynak framework'ün kafa kafaya karşılaştırması: LangGraph, CrewAI, Microsoft Agent Framework, LlamaIndex, Google ADK, OpenAI Agents SDK, Mastra
- [LangGraph resmi dokümantasyonu](https://docs.langchain.com/oss/python/langgraph/graph-api) — "Nodes do the work, edges tell what to do next"; düğüm ve kenarların kesin tanımları, graf inşa etmek için ilk elden referans
- [Anthropic: Building Effective Agents (Dec 2024)](https://www.anthropic.com/engineering/building-effective-agents) — çizildiğinde graf olan beş desen; workflow vs agent'ın yetkili ayrımı
diff --git a/docs/uk/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/uk/lectures/lecture-01-why-capable-agents-still-fail/index.md
index a56df92..6b8866b 100644
--- a/docs/uk/lectures/lecture-01-why-capable-agents-still-fail/index.md
+++ b/docs/uk/lectures/lecture-01-why-capable-agents-still-fail/index.md
@@ -5,13 +5,13 @@
# Лекція 01. Сильна модель — ще не гарантія надійного виконання
-Наприкінці 2025 року найсильніші агенти для написання коду на SWE-bench Verified досягають приблизно 50–60% успішних проходжень. На перший погляд цифра здається непоганою — але не поспішайте радіти. Це ретельно відібрані задачі з чіткими описами і готовими тестами. Дайте агенту ваші повсякденні вимоги — розмиті специфікації, відсутні тести, неявні бізнес-правила, розкидані по всьому коду, — і відсоток успіху впаде ще нижче. Ви передаєте задачу з повною впевненістю, агент працює 20 хвилин і повідомляє «все зроблено», а ви дивитесь на код: функціонал додано, але тести зламані, баг виправлено, але з'явилися нові, та й взагалі — це не те, про що ви просили.
+29 вересня 2025 року Anthropic повідомила, що Claude Sonnet 4.5 досягає [77,2% на SWE-bench Verified](https://www.anthropic.com/news/claude-sonnet-4-5). На перший погляд цифра здається непоганою — але не поспішайте радіти. Це ретельно відібрані задачі з чіткими описами і готовими тестами. Дайте агенту ваші повсякденні вимоги — розмиті специфікації, відсутні тести, неявні бізнес-правила, розкидані по всьому коду, — і відсоток успіху впаде ще нижче. Ви передаєте задачу з повною впевненістю, агент працює 20 хвилин і повідомляє «все зроблено», а ви дивитесь на код: функціонал додано, але тести зламані, баг виправлено, але з'явилися нові, та й взагалі — це не те, про що ви просили.
Коли таке трапляється, перша реакція більшості — «модель недостатньо хороша, спробую дорожчу». Перш ніж тягтися до гаманця, подумайте: проблема може бути зовсім не в моделі.
## Один кінь, дві долі
-Anthropic провела контрольований експеримент, який ідеально ілюструє цю думку. Один і той самий промпт («збудуй 2D-редактор ретро-ігор»), одна й та сама модель (Opus 4.5), два запуски. Перший запуск: без підтримки — 20 хвилин, $9, основний функціонал гри не працював. Другий запуск: повноцінний harness — архітектура з трьох агентів (планувальник, генератор, оцінювач) — 6 годин, $200, гра повністю готова до гри.
+Anthropic порівняла один і той самий промпт («збудуй 2D-редактор ретро-ігор») і одну й ту саму модель (Opus 4.5) у двох harness. Перший запуск: без підтримки — 20 хвилин, $9; застосунок відкривався, але об'єкти не реагували на ввід. Другий запуск: повноцінний harness — архітектура з трьох агентів (планувальник, генератор, оцінювач) — 6 годин, $200; автор міг рухати об'єкт, але фізика мала шорсткості, а стіна блокувала прогрес. [Основний геймплей працював; застосунок залишився незавершеним.](https://www.anthropic.com/engineering/harness-design-long-running-apps)
Модель не змінювали. Opus 4.5 залишався Opus 4.5. Змінилося спорядження.
@@ -31,9 +31,9 @@ Anthropic провела контрольований експеримент, я
З огляду на описані вище сценарії ці концепції вже не є просто жаргоном:
-- **Capability Gap (Розрив у можливостях)**: Величезна прірва між продуктивністю моделі на бенчмарках і продуктивністю на реальних задачах. 50–60% на SWE-bench Verified означає, що майже половина реальних проблем залишається невирішеною.
+- **Capability Gap (Розрив у можливостях)**: Величезна прірва між продуктивністю моделі на бенчмарках і продуктивністю на реальних задачах. Бенчмаркові задачі мають чіткі описи, тести й середовище; для реальних задач це часто доводиться забезпечувати самому.
- **Harness**: Все, що знаходиться поза моделлю — інструкції, інструменти, середовище, управління станом, зворотний зв'язок для верифікації. Якщо це не ваги моделі — це harness. Те, що ми називали «спорядженням».
-- **Harness-Induced Failure (Збій, спричинений harness)**: Модель має достатні можливості, але середовище виконання має структурні дефекти. Контрольований експеримент Anthropic вже довів це.
+- **Harness-Induced Failure (Збій, спричинений harness)**: Модель має достатні можливості, але середовище виконання має структурні дефекти. Порівняння з ретро-грою вище — приклад цього.
- **Verification Gap (Розрив верифікації)**: Розрив між впевненістю агента у своєму результаті та реальною коректністю. Агент каже «я готовий», коли насправді ні — це найпоширеніший сценарій збою.
- **Diagnostic Loop (Діагностичний цикл)**: Виконати — зафіксувати збій — встановити, який шар harness його спричинив — виправити цей шар — виконати знову. Це основна методологія harness engineering.
- **Definition of Done (Визначення завершеності)**: Набір умов, перевірних командою — тести проходять, лінтер чистий, перевірка типів пройдена. Без явного визначення завершеності агент вигадає власне.
@@ -60,7 +60,7 @@ Anthropic провела контрольований експеримент, я
## Експеримент з мільйоном рядків
-У 2025 році троє інженерів OpenAI розпочали експеримент. Правила були прості: вони самі не пишуть код — тільки Codex. Починаючи з порожнього git-репозиторію, через п'ять місяців у репозиторії було приблизно мільйон рядків коду. Логіка застосунку, інфраструктура, інструментарій, документація — все згенеровано агентом. Троє інженерів відкрили загалом 1500 PR, в середньому 3,5 на людину на день.
+У серпні 2025 року троє інженерів OpenAI розпочали експеримент. Правила були прості: вони самі не пишуть код — тільки Codex. Починаючи з порожнього git-репозиторію, через п'ять місяців у репозиторії було [приблизно мільйон рядків коду](https://openai.com/index/harness-engineering/). Логіка застосунку, інфраструктура, інструментарій, документація — все згенеровано агентом. Команда згодом зросла до семи інженерів; за цей період було змерджено близько 1500 PR, у середньому 3,5 на інженера на день.
Перші кроки виявилися напрочуд повільними. Codex був не поганий — він просто не мав інструментів і структур, достатньо повних для досягнення цілей високого рівня. Троє інженерів поступово виявили закономірність: розбивайте великі цілі на дрібні будівельні блоки — проектування, код, рев'ю, тести — давайте агенту складати їх один за одним, а потім використовуйте ці блоки для компонування складніших задач. Щоразу, коли щось ішло не так, проблема майже ніколи не була «недостатнє старання». Завжди: «чого агенту ще не вистачає, і чи можна надати цю відсутню можливість у спосіб, зрозумілий і придатний до виконання?»
@@ -72,9 +72,9 @@ Anthropic провела контрольований експеримент, я
Одна команда використовувала Claude Sonnet для додавання нових API-ендпоінтів до середнього Python-веб-застосунку (FastAPI + PostgreSQL + Redis, ~15 000 рядків коду).
-Спочатку вони дали лише одне речення: «додай ендпоінти налаштувань користувача під `/api/v2/users`». Результат? Агент витратив 40% контекстного вікна на дослідження структури репозиторію, написав код, що виглядав розумно, але не відповідав паттернам обробки помилок у проєкті, використав старий синтаксис SQLAlchemy та оголосив про завершення, коли в ендпоінті були runtime-помилки. Наступна сесія мала заново виконати всю розвідку.
+Спочатку вони дали лише одне речення: «додай ендпоінти налаштувань користувача під `/api/v2/users`». Результат? Агент витратив значну частину сесії на дослідження структури репозиторію, написав код, що виглядав розумно, але не відповідав паттернам обробки помилок у проєкті, використав старий синтаксис SQLAlchemy та оголосив про завершення, коли в ендпоінті були runtime-помилки. Наступна сесія мала заново виконати всю розвідку.
-Пізніше вони додали `AGENTS.md` (з описом архітектури проєкту та версій технологічного стека), явні верифікаційні команди (`pytest tests/api/v2/ && python -m mypy src/`) та записи про архітектурні рішення. Та сама модель успішно виконала завдання в усіх трьох незалежних запусках, з ефективністю використання контексту приблизно на 60% вищою.
+Пізніше вони додали `AGENTS.md` (з описом архітектури проєкту та версій технологічного стека), явні верифікаційні команди (`pytest tests/api/v2/ && python -m mypy src/`) та записи про архітектурні рішення. Та сама модель тоді дотримувалася конвенцій проєкту й перевіряла свою роботу командами, які могла запустити.
Модель не змінювали. Змінили harness.
diff --git a/docs/uk/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/uk/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
index 32964ff..6dfb5ee 100644
--- a/docs/uk/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
+++ b/docs/uk/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -50,7 +50,7 @@ flowchart LR
- **Контекстні вікна обмежені**: незалежно від заявленого розміру вікна (128K, 200K, 1M), тривалі задачі врешті-решт їх вичерпають. Після вичерпання потрібна або компресія (втрата інформації), або скидання контексту (початок нової сесії) — обидва варіанти щось втрачають.
- **Файли збереження стану (State persistence files)**: файли зі збереженим станом, що дозволяють новій сесії однозначно продовжити роботу з того місця, де зупинилась попередня. Найпростіша форма включає журнали прогресу, записи верифікації та наступні дії.
-- **Вартість відновлення (Rebuild cost)**: час, необхідний новій сесії для досягнення виконуваного стану. Хороший harness може скоротити вартість відновлення з 15 хвилин до 3 хвилин.
+- **Вартість відновлення (Rebuild cost)**: час, необхідний новій сесії для досягнення виконуваного стану. Хороший harness залишає прогрес, результати верифікації та наступні дії у файлах, тож нова сесія стартує із записаного стану.
- **Дрейф (Drift)**: розрив між розумінням агента та реальним станом репозиторію коду. Кожна межа між сесіями вносить дрейф; без контролю він накопичується від сесії до сесії.
- **Контекстна тривога (Context anxiety)**: явище, зафіксоване Anthropic, — агенти виявляють поведінку поспішного завершення, коли наближаються до меж контексту, дочасно завершуючи задачі, щоб уникнути втрати інформації. По суті, це ірраціональна тривога через ресурси.
- **Компресія проти скидання (Compaction vs. reset)**: компресія підсумовує контекст у межах тієї самої сесії (зберігає «що», може втратити «чому»); скидання відкриває нову сесію, відбудовуючись із збережених артефактів (чистий стан, але залежить від повноти артефактів).
@@ -158,7 +158,7 @@ LangChain повідомляє про зростання з 52,8% до 66,5%, н
- Контекстні вікна — обмежений ресурс. Тривалі задачі охоплюватимуть кілька сесій, а сесії втрачатимуть інформацію — це об'єктивна реальність.
- Рішення — не більші вікна, а краще збереження стану. Файли прогресу, журнали рішень і git-контрольні точки разом дозволяють новим сесіям продовжувати роботу з того місця, де зупинились попередні.
- Ставтеся до агента як до інженера, чия короткострокова пам'ять стирається наприкінці кожної сесії: перед «виходом з зміни» запишіть, що було зроблено, чому і що далі.
-- Вартість відновлення — ключова метрика. Хороший harness повинен доводити нові сесії до виконуваного стану за 3 хвилини.
+- Вартість відновлення — ключова метрика. Хороший harness залишає прогрес, результати верифікації та наступні дії у файлах, тож нова сесія швидко відновлюється.
- Змішана стратегія: короткі задачі — в межах сесії, тривалі — з структурованими артефактами для забезпечення наступності.
## Додаткові матеріали
diff --git a/docs/uk/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/uk/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
index a4f6ede..fad1ca5 100644
--- a/docs/uk/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
+++ b/docs/uk/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -37,7 +37,7 @@ flowchart TB
## Що відбувається, коли їх змішують
-Найочевидніша проблема: інфраструктура будується ненадійно. Агент витрачає 80% зусиль на код функцій, а решту 20% — на поверхневе налаштування інфраструктури. Тестовий фреймворк налаштований, але не перевірений; правила лінтера встановлені, але занадто м'які; файл прогресу не створено. Ці вади непомітні в першій сесії (бо агент ще пам'ятає, що робив), але спливають у другій: новий агент не знає, як запустити проєкт, як тестувати і де що знаходиться.
+Найочевидніша проблема: інфраструктура будується ненадійно. Агент витрачає більшу частину зусиль на код функцій, а інфраструктуру сприймає як другорядне. Тестовий фреймворк налаштований, але не перевірений; правила лінтера встановлені, але занадто м'які; файл прогресу не створено. Ці вади непомітні в першій сесії (бо агент ще пам'ятає, що робив), але спливають у другій: новий агент не знає, як запустити проєкт, як тестувати і де що знаходиться.
Прихованіша проблема — «накопичення неперевіреного коду». Код функцій написаний до того, як тестовий фреймворк правильно налаштований — коли ви нарешті повертаєтеся додавати тести, може виявитися, що сам дизайн був хибним. Знаючи це раніше, ви б реалізували інакше. Що більше коду написано заздалегідь, то більше доведеться зносити і переробляти потім.
@@ -45,7 +45,7 @@ flowchart TB
Найлегше проігнорована проблема — приховані припущення, що стають пастками. Рішення, прийняті агентом під час ініціалізації (який тестовий фреймворк, як організувати директорії, керування залежностями) — якщо вони не зафіксовані явно, наступні сесії можуть зробити суперечливі вибори. Перша сесія вибрала Vitest як тестовий фреймворк, але агент другої сесії цього не знає і впроваджує Jest. Два тестових фреймворки існують паралельно, а витрати на підтримку подвоюються.
-Дослідження Anthropic у сфері розробки довготривалих застосунків явно рекомендує розділяти ініціалізацію та реалізацію. Їхні експериментальні дані: проєкти з виділеною фазою ініціалізації показали на 31% вищий відсоток завершення функцій у багатосесійних сценаріях порівняно зі змішаним підходом. А час, витрачений на фазу ініціалізації, повністю окупається вже в наступних 3–4 сесіях.
+Робота Anthropic з довготривалими агентами [робить ініціалізацію окремою першою сесією](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents). Ініціалізатор пише скрипт `init.sh`, файл прогресу, список функцій і початковий git-коміт; наступні сесії з написання коду читають цей стан, працюють над однією функцією за раз, перевіряють її наскрізно, комітять і оновлюють файл прогресу.
Посібник з harness engineering від OpenAI Codex також наголошує на принципі «репозиторій як операційний запис»: з самого першого запуску встановіть чітку операційну структуру, інакше кожна нова сесія змушена заново виводити конвенції проєкту.
diff --git a/docs/uk/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/uk/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
index 8bf000f..8f4f92d 100644
--- a/docs/uk/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
+++ b/docs/uk/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -26,7 +26,7 @@
Шість кроків — і кожен наполовину зроблений. Жодної наскрізної верифікації, складне зв'язування між напівготовим кодом, а наступна сесія, що підхопить уламки, буде повністю розгублена.
-Експериментальні дані Anthropic це підтверджують безпосередньо: агенти, що використовують стратегію «маленького наступного кроку» (еквівалент WIP=1), показують на 37% вищий відсоток завершення задач, ніж агенти з широкими промптами. Цікавіше те, що кількість рядків коду, згенерованих агентами, слабко негативно корелює з фактичним завершенням функцій — більше написаного коду, менше завершених функцій. Захопити більше, ніж можеш з'їсти, — доведено даними.
+Настанови Anthropic щодо довготривалих агентів [просять агента з написання коду працювати над однією функцією за раз](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), а потім перевірити, закомітити й оновити прогрес, перш ніж рухатися далі. Широкий промпт спонукає агента відкрити кілька потоків роботи, і кожен потік конкурує за той самий контекст і бюджет верифікації.
## Робочий процес WIP=1
diff --git a/docs/uk/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/uk/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
index 57d792b..255c2dc 100644
--- a/docs/uk/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
+++ b/docs/uk/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -25,7 +25,7 @@ Did user auth, shopping cart mostly done, still need payments
Чи може новий сеанс агента відповісти на ці запитання з цієї нотатки? Що означає «mostly done»? Які тести пройшов кошик? Що блокує платежі? Відповідь на всі — «ніхто не знає».
-Результат: новий сеанс витрачає 20 хвилин на з'ясування стану проєкту і може зрештою заново реалізувати вже завершені функції. За інженерними даними Anthropic, хороші записи прогресу скорочують час діагностики на початку сеансу на 60–80%.
+Результат: новий сеанс має з'ясувати стан проєкту і може зрештою заново реалізувати вже завершені функції. Anthropic радить [записувати прогрес і результати верифікації у версійовані файли](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), щоб наступний сеанс міг оглянути стан.
## Машина станів функціональності
@@ -116,7 +116,7 @@ E-commerce платформа з 10 функціями. Порівняння д
**Структурований режим**: кожна функція має чіткий стан і команду верифікації. Новий сеанс читає список функціональності і за 3 хвилини знає: F01–F05 — `passing`, F06 — `active` (в роботі), F07–F10 — `not_started`. Він продовжує безпосередньо з F06, без жодного повтору роботи.
-Кількісний результат: проєкти зі структурованими списками функціональності показують на 45% вищий рівень завершення функцій порівняно з довільним відстеженням, без жодних дублікатів реалізацій.
+Структурований список збирає стан кожної функції та команду її верифікації в одному місці, тож новий сеанс знає, що вже зроблено.
## Ключові висновки
diff --git a/docs/uk/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/uk/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
index 0a4a070..fae6961 100644
--- a/docs/uk/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
+++ b/docs/uk/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -68,7 +68,7 @@ Anthropic виявив глибший патерн відмови у своїх
| Архітектура | Час виконання | Вартість | Основні функції працюють? |
|-------------|---------------|----------|--------------------------|
| Один агент (без обгортки) | 20 хв | $9 | Ні (ігрові сутності не реагують на введення) |
-| Три агенти (планувальник + генератор + оцінювач) | 6 год | $200 | Так (гра повністю грається) |
+| Три агенти (планувальник + генератор + оцінювач) | 6 год | $200 | Основний геймплей працював; залишалися проблеми з фізикою та рівнями |
Це та сама модель (Opus 4.5) з тим самим промптом («побудуй 2D-редактор ретро-ігор»). Єдина відмінність — harness: від «запуску без обгортки» до «планувальник розширює вимоги → генератор реалізує функцію за функцією → оцінювач виконує реальне клік-тестування через Playwright».
@@ -117,7 +117,7 @@ OpenAI представив особливо ефективний патерн
**Фактичні упущення**: (1) наскрізний потік не перевірявся — фактичне надсилання та верифікація посилання для скидання ніколи не були підтверджені. (2) Міграція бази даних завершилась після часткового виконання, залишивши схему суперечливою. (3) Конфігурація поштового сервісу була відсутня в цільовому середовищі.
-**Втручання harness**: валідація завершення є обов'язковою — (1) запустити повний застосунок для перевірки доступності ендпоінта скидання; (2) виконати повний потік скидання; (3) верифікувати узгодженість стану бази даних. Всі дефекти були виявлені в межах сеансу, що зекономило в 5–10 разів більше ресурсів порівняно з виправленнями після факту.
+**Втручання harness**: валідація завершення є обов'язковою — (1) запустити повний застосунок для перевірки доступності ендпоінта скидання; (2) виконати повний потік скидання; (3) верифікувати узгодженість стану бази даних. Всі три дефекти виявляються всередині сеансу, поки вартість виправлення ще локальна.
## Ключові висновки
diff --git a/docs/uk/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/uk/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
index fde1332..c560860 100644
--- a/docs/uk/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
+++ b/docs/uk/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -130,7 +130,7 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.rea
| Проблема дозволів | Відмінні дозволи в пакетному середовищі | Пропущено | Виявлено |
| Поширення помилок | Винятки сервісного шару не досягали шару UI | Пропущено | Виявлено |
-Всі 5 дефектів виявлені наскрізними тестами; юніт-тести не виявили жодного. Компроміс — час тестування зріс з 2 секунд до 15 секунд — цілком прийнятно в агентному робочому процесі.
+Всі 5 дефектів виявлені наскрізними тестами; юніт-тести не виявили жодного. Наскрізний прогін повільніший, але ця ціна мала порівняно з випуском п'яти дефектів на межі систем.
## Ключові висновки
diff --git a/docs/uk/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/uk/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
index 99e3a3c..875dd50 100644
--- a/docs/uk/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
+++ b/docs/uk/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -21,7 +21,7 @@
**Повторні спроби стають сліпими здогадками.** Коли агент не знає, чому щось не спрацювало, напрямок повторної спроби випадковий. Він може безуспішно стукатись у хибному напрямку — виправляти непов'язані шляхи коду, ігноруючи справжню першопричину. Кожна сліпа повторна спроба спалює токени і час.
-**Інформаційна прірва при передачі сесії.** Коли незавершена робота передається наступній сесії, відсутність спостережуваності означає, що нова сесія має діагностувати стан системи з нуля. Спостереження Anthropic за довготривалими агентами показують, що ця надлишкова діагностика може поглинати 30–50% загального часу сесії.
+**Інформаційна прірва при передачі сесії.** Коли незавершена робота передається наступній сесії, відсутність спостережуваності означає, що нова сесія має діагностувати стан системи з нуля. Новій сесії доводиться перечитувати код, повторно запускати команди й вирішувати, які сигнали важливі; [версійовані записи прогресу та верифікації](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) дають стан, який можна оглянути.
## Реальний сценарій Claude Code
@@ -31,7 +31,7 @@
**З повною спостережуваністю:** Планувальник виводить sprint-контракт із переліком компонентів для модифікації, стандартів верифікації для кожного та виключень (наприклад, без стилів для друку). Генератор реалізує відповідно до контракту, а спостережуваність runtime фіксує процес завантаження та застосування стилів кожного компонента. Оцінювач використовує рубрику оцінювання для покрокової оцінки кожного виміру з конкретними доказами: «Контраст кольору кнопки недостатній (стандарт WCAG AA 4.5:1, виміряно 2.1:1).» Одна ітерація дає якісний результат приблизно за 15 хвилин.
-Триразова різниця в ефективності. Єдина змінна — спостережуваність.
+Різниця походить від того, чи існують контракт і докази поза головою агента.
## Шарувата спостережуваність
@@ -122,7 +122,7 @@ flowchart LR
## Експеримент Anthropic із триагентною архітектурою
-У березні 2026 року Anthropic опублікував систематичний harness-експеримент. Вони запускали одне й те саме завдання («побудувати браузерний DAW за допомогою Web Audio API») із трьома різними архітектурами й записували детальні дані по кожній фазі:
+У березні 2026 року звіт Anthropic подає [оновлений прогін DAW тієї самої триагентної архітектури](https://www.anthropic.com/engineering/harness-design-long-running-apps) («побудувати браузерний DAW за допомогою Web Audio API»). Перша версія, створена для Opus 4.5, використовувала генератор, що працював спринтами, та оцінювача, який оцінював кожен спринт. Оновлена версія, запущена на Opus 4.6, прибрала конструкцію спринту: будівельник працює безперервно, а оцінювач переглядає після кожного раунду збірки. Таблиця нижче — оновлений прогін:
| Агент і фаза | Тривалість | Вартість |
|--------------|-----------|---------|
@@ -135,7 +135,7 @@ flowchart LR
| QA, раунд 3 | 9,6 хв | $4,06 |
| **Разом** | **3 год 50 хв** | **$124,70** |
-Кожен із трьох агентів мав чітку роль, і кожен відігравав очевидну частину у спостережуваності:
+Кожна роль відіграє очевидну частину у спостережуваності. Описи ролей нижче стосуються першої версії; в оновленій версії шар спринтів генератора прибрано:
**Планувальник:** Отримує вимогу користувача з 1–4 речень і розгортає її в повну специфікацію продукту. Йому було доручено «бути сміливим у масштабі» та «зосередитись на контексті продукту й високорівневому технічному проєктуванні, а не на детальній технічній реалізації». Логіка: якщо планувальник передчасно вказує детальні технічні деталі й помиляється, ці помилки каскадуються вниз. Кращий підхід — обмежити результати й дозволити агенту знайти власний шлях під час виконання.
@@ -155,7 +155,7 @@ flowchart LR
- **Обидва шари спостережуваності необхідні.** Сигнали runtime пояснюють «що сталось», артефакти процесу пояснюють «чому це було зроблено саме так».
- **Sprint-контракти зміщують узгодження на початок.** Вони запобігають тому, що генератор будує щось, що оцінювач одразу відхиляє з передбачуваних причин.
- **Рубрики оцінювання роблять оцінювання відтворюваним.** Різні оцінювачі отримують схожі оцінки для одного й того самого результату.
-- **Відсутність спостережуваності витрачає 30–50% часу сесії на надлишкову діагностику.**
+- **Спостережуваність перетворює розпливчасте відхилення на конкретний дефект, який можна виправити.**
## Додаткова література
diff --git a/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
index 8eed39e..e386abc 100644
--- a/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
+++ b/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -15,7 +15,7 @@
Під час п'яти місяців експериментів із Codex OpenAI помітила дещо разюче: **агенти копіюють патерни, що вже є в репозиторії, навіть коли ці патерни непослідовні або неоптимальні.** З часом таке копіювання неминуче призводить до деградації. Перша людина залишає чашку кави в загальному просторі; друга вирішує «і так уже безлад» та залишає ще одну; через тиждень стіл завалений чашками. З кодовою базою відбувається те саме.
-Команда OpenAI спочатку витрачала 20% кожної п'ятниці на ручне прибирання «AI-мотлоху», але такий підхід явно не масштабується. Зрештою вони дійшли до систематичного рішення:
+Команда OpenAI спочатку відводила п'ятниці — [один робочий день, близько 20% тижневої спроможності](https://openai.com/index/harness-engineering/) — на ручне прибирання «AI-мотлоху». Зі зростанням пропускної здатності ручне очищення коштувало більше, ніж повертало. Зрештою вони дійшли до систематичного рішення:
1. **Закодувати «золоті правила» в репозиторій**: правила на кшталт «надавайте перевагу спільному utility-пакету перед написаними нашвидкуруч допоміжними функціями» (тримайте інваріанти централізовано) і «не вгадуйте наосліп структури даних» (валідуйте межі або покладайтеся на типізовані SDK). Ці правила конкретні, механічні та автоматично перевірювані.
2. **Встановити регулярні робочі процеси очищення**: флот фонових завдань Codex, які регулярно сканують відхилення, оновлюють оцінки якості та відкривають цільові PR рефакторингу. Більшість можна переглянути й автоматично злити за хвилину.
@@ -43,7 +43,7 @@ flowchart LR
Fix --> Build
```
-Але й цього недостатньо. Поточний прогрес має бути зафіксований у машинозчитуваних артефактах: виконані підзавдання з їхніми критеріями проходження, підзавдання в процесі виконання з поточним станом, а також ті, що ще не розпочато. Хороші записи прогресу можуть скоротити час діагностики при запуску сесії на 60–80%. Тимчасові артефакти — debug-логи, тимчасові файли, закоментований код, маркери TODO — також потрібно прибирати, оскільки вони підвищують когнітивне навантаження для наступної сесії. Стандартний шлях запуску теж має залишатися робочим. Чи може наступна сесія приступити до роботи без ручного втручання? Ініціалізація середовища, завантаження кодової бази, отримання контексту, вибір задачі — жоден із цих шляхів не може бути зламаний.
+Але й цього недостатньо. Поточний прогрес має бути зафіксований у машинозчитуваних артефактах: виконані підзавдання з їхніми критеріями проходження, підзавдання в процесі виконання з поточним станом, а також ті, що ще не розпочато. Записуйте прогрес і результати верифікації у версійовані файли, щоб наступна сесія могла оглянути стан. Тимчасові артефакти — debug-логи, тимчасові файли, закоментований код, маркери TODO — також потрібно прибирати, оскільки вони підвищують когнітивне навантаження для наступної сесії. Стандартний шлях запуску теж має залишатися робочим. Чи може наступна сесія приступити до роботи без ручного втручання? Ініціалізація середовища, завантаження кодової бази, отримання контексту, вибір задачі — жоден із цих шляхів не може бути зламаний.
```mermaid
flowchart LR
@@ -72,7 +72,7 @@ flowchart LR
Гірше того, кожна сесія має власні цільові завдання. Нова сесія існує для нової роботи, а не для прибирання безладу попередньої. Вона проігнорує хаос і почне нову роботу поверх нього, додаючи ще більше хаосу. Це петля позитивного зворотного зв'язку ентропії.
-Цифри говорять самі за себе. Проєкт, що розроблявся з агентами 12 тижнів без стратегії очищення:
+Для гіпотетичного 12-тижневого проєкту припустімо такі значення:
- Тиждень 1: рівень проходження збірки 100%, рівень проходження тестів 100%, запуск нової сесії 5 хв
- Тиждень 4: збірка 95%, тести 92%, запуск 15 хв
@@ -84,7 +84,7 @@ flowchart LR
- Тиждень 1: 100%, 100%, 5 хв
- Тиждень 12: 97%, 95%, 9 хв
-Після 12 тижнів: рівень проходження збірки відрізняється на 29 відсоткових пунктів, час запуску нової сесії — на 85%. Це не теорія — це спостережувана різниця.
+Щотижневий цикл очищення зберігає стартовий стан стабільним: кожна сесія завершується з упорядкованими збіркою, тестами, прогресом і тимчасовими артефактами, тож наступна сесія стартує з тієї самої базової лінії.
## Як це зробити
@@ -137,7 +137,7 @@ flowchart LR
Кожен компонент harness існує тому, що модель не могла самостійно надійно виконати щось. Але з покращенням моделей ці припущення застарівають.
-Експерименти Anthropic продемонстрували це безпосередньо. Початковий harness включав механізм розбивки на спринти — ділення роботи на невеликі частини для того, щоб Sonnet 4.5 виконував їх по одній. Коли вийшов Opus 4.6, нативні можливості моделі могли самостійно обробляти декомпозицію роботи, що зробило побудову спринтів зайвими накладними витратами. Після видалення цього компонента агент-будівник міг безперервно працювати понад дві години без відхилень — і насправді ставав плавнішим.
+Звіт Anthropic про harness показує це безпосередньо. Перший триагентний harness, створений для Opus 4.5, мав генератор, що працював спринтами. Коли вийшов [Opus 4.6](https://www.anthropic.com/engineering/harness-design-long-running-apps), модель могла самостійно впоратися з декомпозицією роботи, тож конструкція спринту стала зайвою. В оновленому прогоні DAW будівельник працював безперервно понад дві години без відхилень.
Але з евалюатором ситуація була іншою. Навіть із посиленими можливостями Opus 4.6, коли задачі наближалися до межі можливостей моделі, евалюатор усе ще давав реальну цінність — виявляв відсутній функціонал і заглушки в реалізації генератора. Це означає, що евалюатор — не фіксоване рішення «так/ні»; він залежить від того, де складність задачі знаходиться відносно можливостей моделі.
@@ -170,7 +170,7 @@ Electron-застосунок, що розроблявся з агентами 1
**Зі стратегією очищення** (експериментальна група): повна перевірка чистого стану наприкінці кожної сесії плюс щотижневий цикл очищення. Тиждень 12, рівень проходження збірки 97%, рівень проходження тестів 95%, запуск нової сесії 9 хв, 11 застарілих артефактів.
-До тижня 12 рівень проходження збірки в експериментальній групі був вищим на 29 відсоткових пунктів, рівень проходження тестів — на 34 пункти, а час запуску нової сесії — на 85% нижчим. Кожна сесія витрачала додаткові 5 хвилин на очищення, але за 12 тижнів це заощадило десятки годин хаосу.
+До тижня 12 рівні проходження збірки й тестів у групі з очищенням залишалися близькими до стартових, нова сесія могла швидко стартувати, а застарілих артефактів було мало. Очищення займало кілька хвилин на сесію і повертало стартовий стан, якому наступна сесія могла довіряти.
## Головні висновки
diff --git a/docs/uk/lectures/lecture-13-loop-engineering/index.md b/docs/uk/lectures/lecture-13-loop-engineering/index.md
index e5f096e..891c4fa 100644
--- a/docs/uk/lectures/lecture-13-loop-engineering/index.md
+++ b/docs/uk/lectures/lecture-13-loop-engineering/index.md
@@ -84,11 +84,11 @@ Loop Engineering, тема цієї лекції — не про якусь од
Вам не потрібно вводити `/goal` кожного разу. Але розуміння, звідки воно взялося і чому воно виглядає саме так — це розуміння суті loop engineering. Більш складні цикли просто додають такі частини, як планування, паралелізм, ізоляція та пам'ять поверх цих самих трьох основ: мета, перевірка, умова зупинки.
-## Червень 2026: Троє людей запалили той самий запал за один тиждень
+## Різні дати, один напрямок
-У перший тиждень червня 2026 року троє практиків, що будували інфраструктуру агентів кодування — не порівнюючи нотатки — сказали те ж саме різними словами.
+Та сама думка виникла в різних місцях, у різний час.
-**Пітер Штайнбергер** (творець OpenClaw, [його допис набрав 8 мільйонів переглядів](https://x.com/steipete/status/2063697162748260627)): «Ви більше не повинні писати промпти для агентів кодування. Ви повинні проектувати цикли, які пишуть промпти для ваших агентів.»
+**Пітер Штайнбергер** (творець OpenClaw, [у дописі](https://x.com/steipete/status/2063697162748260627)): «Ви більше не повинні писати промпти для агентів кодування. Ви повинні проектувати цикли, які пишуть промпти для ваших агентів.»
**Борис Черний** (керівник Claude Code в Anthropic, [на підкасті Acquired](https://x.com/rohanpaul_ai/status/2063289804708835412)): «Я більше не пишу промпти для Claude. У мене працюють цикли, які пишуть промпти для Claude і вирішують, що робити. Моя робота — писати цикли.»
@@ -96,9 +96,9 @@ Loop Engineering, тема цієї лекції — не про якусь од
> **Loop engineering — це заміна себе як людини, яка пише промпти для агента. Ви проектуєте систему, яка робить це замість вас.**
-Черний розкрив цифри: протягом понад 30 послідовних днів усі внески коду в Claude Code були зроблені автономно ШІ — 259 злитих PR, понад 80% продуктивного коду, написаного Claude, і 76% успішності у відкритих програмних завданнях.
+Черний написав у [особистому звіті від 2025-12-27](https://twitter.com/bcherny/status/2004887829252317325), що за 30 днів злив 259 PR — 497 комітів, 40 000 рядків додано, 38 000 видалено — і що кожен рядок написано Claude Code + Opus 4.5.
-Троє людей. Один тиждень. Однаковий висновок. Не тому що вони координувалися — а тому що інфраструктура тихо перетнула поріг. Агенти стали достатньо надійними, щоб виконувати нетривіальні завдання без нагляду. Примітиви планування (`/loop`, `/goal`, cron) тепер вбудовані в інструменти. Вартість одного запуску агента впала достатньо низько, щоб запускати його повторно за таймером і не вважати це марнотратством. Коли всі частини на місці, хід, який їх поєднує, стає очевидним для всіх одночасно.
+Цитати походять із різних дат, форматів і команд. Їхній спільний напрямок — перенести планування, верифікацію та рішення про зупинку з моменту промпту в систему. До середини 2026 року агенти могли завершувати нетривіальні завдання без нагляду, примітиви планування були вбудовані, а запуск був достатньо дешевим, щоб повторювати його за таймером. Коли частини на місці, більше ніж одна людина їх поєднує.
> Джерело: [Едді Османі: Loop Engineering](https://addyosmani.com/blog/loop-engineering/)
@@ -267,7 +267,7 @@ flowchart TD
Це вже не один запуск агента. Це безперервно працююча система, яка прокидається кожного ранку, самостійно прибирає на робочому місці і ставить те, що потребує вашої уваги, перед вами. Ваша роль стає такою: **переглядати вміст вхідної скриньки, приймати рішення, і коли ви помічаєте патерн, з яким система не може впоратися, уточнювати навички та правила.**
-Черний використав цей патерн, щоб злити 259 PR за 30 днів, жодного разу не відкриваючи IDE. Інженери OpenAI використали той самий патерн, щоб вручну побудувати бета-продукт приблизно на мільйон рядків — жодного разу не написавши рядок коду самостійно.
+Звіт Черного за 30 днів — одна точка даних для цього патерну: 259 PR, код написано Claude Code + Opus 4.5. [Звіт OpenAI про harness](https://openai.com/index/harness-engineering/) — інша: невелика команда використовувала Codex у greenfield-репозиторії п'ять місяців і повідомила про приблизно мільйон рядків і близько 1500 PR.
## Розділення генератора/оцінювача: чому ви не можете дозволити моделі оцінювати власну роботу
@@ -293,7 +293,7 @@ flowchart TD
Якщо ви хочете побачити, як виглядає добре спроектований, реально працюючий цикл, [autoresearch Karpathy](https://github.com/karpathy/autoresearch) — це підручниковий приклад.
-У березні 2026 року Карпатський випустив Python-проект на 630 рядків. Дайте йому один GPU і напрямок досліджень, і він працює всю ніч — виконуючи сотні експериментів навчання ML, залишаючи лише ті, які дійсно покращують результат. Проект набрав 66 000+ зірок протягом кількох днів після випуску.
+У березні 2026 року Карпатський випустив [autoresearch](https://github.com/karpathy/autoresearch). Репозиторій навмисно невеликий: `prepare.py` — фіксована інфраструктура, `train.py` — файл, який редагує агент (близько 630 рядків), а `program.md` — методологія дослідження, яку редагує людина. Дайте йому один GPU і напрямок досліджень, і він працює всю ніч — кожен експеримент отримує фіксований 5-хвилинний бюджет навчання за реальним часом (без урахування запуску й компіляції), і зберігаються лише зміни, що покращують `val_bpb`.
### Три файли, три ролі
@@ -343,9 +343,9 @@ flowchart TD
8b --> 9
```
-Він виконує приблизно 12 експериментів на годину. Нічний запуск (8 годин) — це близько 100 експериментів. Сам Карпатський запускав його протягом 2 днів — ~700 експериментів.
+README оцінює приблизно 12 експериментів на годину, або близько 100 за 8-годинний нічний запуск. 5-хвилинний бюджет охоплює навчання, а не запуск чи компіляцію; решта кожного раунду йде на редагування, запуск та оцінювання. Карпатський повідомив, що запускав приватну версію autoresearch автономно близько двох днів для раунду nanochat, описаного нижче.
-Фіксований 5-хвилинний бюджет реального часу — ключовий дизайнерський вибір — незалежно від того, що агент змінює, кожен експеримент займає рівно стільки ж часу. Це означає, що усі результати можна безпосередньо порівнювати за однакового бюджету часу — жодних суперечок про «цей працював довше, тому він кращий».
+Фіксований 5-хвилинний бюджет навчання — ключовий дизайнерський вибір — незалежно від того, що агент змінює, навчальний прогін отримує однаковий бюджет реального часу. Це означає, що всі результати можна безпосередньо порівнювати за однакового бюджету навчання.
### Вивід: що ви бачите, коли прокидаєтеся
@@ -375,13 +375,9 @@ timestamp commit_hash val_bpb vram_mb description
### Що він насправді знайшов
-Результати початкового 2-денного запуску Карпатського з ~700 експериментами:
+Результати [раунду 1](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b) autoresearch скоротили час навчання nanochat на рівні GPT-2 на 8×H100 [з **2,02 години до 1,80 години**](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b), приблизно на **10,9%** часу навчання.
-- З ~700 спроб знайдено приблизно **20 дійсних поліпшень, що складаються**
-- Час навчання nanochat на рівні GPT-2 на 8×H100 зменшився з **2,02 години → 1,80 години**, приблизно **на 11% швидше**
-- Знахідки включали: корекції швидкості навчання, налаштування оптимізатора, заміни активації, оптимізації патернів уваги тощо.
-
-Чи були усі поліпшення земними відкриттями? Ні. Більшість були малими оптимізаціями, що складалися разом. Але ці 20 дійсних поліпшень зайняли б у людського дослідника тижні ручної роботи — агент зробив це за 48 годин.
+Більшість змін були малими оптимізаціями, що складалися. Корисна частина — це цикл: фіксований бюджет, повний журнал експериментів і правило, за яким залишаються лише перевірені поліпшення.
### Найпоказовіша деталь: цикл написано англійською, а не кодом.
@@ -399,7 +395,7 @@ timestamp commit_hash val_bpb vram_mb description
### 2. Розуміннява гниль
-Чим швидше цикл випускає код, тим далі ваше розуміння власної кодової бази відходить від реальності. У команди Черного 80% коду було написано агентами — що означає, що більша частина коду команди не була написана людиною. Якщо ви не читаєте і не використовуєте те, що виробляє цикл, ваше розуміння постійно погіршується. **Швидкі цикли вимагають швидкого читання.**
+Чим швидше цикл випускає код, тим далі ваше розуміння власної кодової бази відходить від реальності. Цикл приносить сотні PR; команда читає ці PR, переглядає важливі дифи й продовжує користуватися кодом, тож її ментальна модель встигає. **Швидкі цикли вимагають швидкого читання.**
### 3. Когнітивна здача
@@ -407,11 +403,11 @@ timestamp commit_hash val_bpb vram_mb description
### 4. Вибух токенів
-Кожна ітерація циклу накопичує більше контексту: написаний код, зустрічені помилки, прийняті рішення. Без управління контекстом розмір промпту зростає приблизно квадратично залежно від кількості ходів. Codex вирішує це за допомогою автоматичного стиснення контексту — спеціалізований API стискає старі ходи розмови в зашифровані зведення вмісту, зберігаючи важливі знання, відкидаючи зайві деталі. Це інженерне питання, яке ви повинні вирішити з першого циклу, а не додавати пізніше.
+Кожна ітерація циклу накопичує більше контексту: написаний код, зустрічені помилки, прийняті рішення. Коли кожен раунд додає приблизно фіксований обсяг нового вмісту, історія, яку бачить один раунд, зростає приблизно лінійно з кількістю раундів. Якщо система переобробляє всю історію щоразу, сукупний вхід за N раундів зростає приблизно квадратично. Codex вирішує це за допомогою автоматичного стиснення контексту — спеціалізований API стискає старі ходи розмови в зашифровані зведення вмісту, зберігаючи важливі знання, відкидаючи зайві деталі. Це інженерне питання, яке ви повинні вирішити з першого циклу, а не додавати пізніше.
## Побудова вашого першого циклу
-Вам не потрібно починати з конвеєра масштабу Stripe, що зливає 1300 PR на тиждень. Почніть з найменшої речі, яка працює.
+Вам не потрібно починати з високопропускного конвеєра. Почніть з найменшої речі, яка працює.
### Крок 1: Виберіть одне повторюване завдання
diff --git a/docs/uk/lectures/lecture-14-graph-engineering/index.md b/docs/uk/lectures/lecture-14-graph-engineering/index.md
index bb5d338..8241946 100644
--- a/docs/uk/lectures/lecture-14-graph-engineering/index.md
+++ b/docs/uk/lectures/lecture-14-graph-engineering/index.md
@@ -9,7 +9,7 @@
> «Ми все ще говоримо про Loop, чи вже перейшли до Graph?»
-Один твіт — за день він набрав приблизно 570 тисяч переглядів, а до кінця місяця виріс приблизно до 3 мільйонів. За кілька годин інженер з машинного навчання Хамел Хусейн опублікував статтю під назвою «Loop Engineering Is Dead. Enter Graph Engineering» — у тілі якої була лише одна гіфка зі словами «Stop it» — і теж набрав приблизно 680 тисяч переглядів.
+Один твіт. За кілька годин інженер з машинного навчання Хамел Хусейн опублікував статтю під назвою «Loop Engineering Is Dead. Enter Graph Engineering» — у тілі якої була лише одна гіфка зі словами «Stop it».
Ще цікавіше: **обидва написали це як жарт.** Один висміював те, що індустрія вигадує новий термін кожні шість тижнів, а другий підхопив цей мем і відповів у тон. Але жарт прожив лише приблизно один вихідний — курси, дорожні карти та стеки інструментів заполонили стрічку до кінця вікенду, а з ними й купа вигаданих цифр: «точність +18%, вартість −85%» — це фейкові дані (18% і 85% справді існують, але з наукової статті про креслення хімічних трубопроводів, і зі зовсім іншим базовим порівнянням), а «Microsoft, Stanford і Anthropic одночасно відкрили Graph Engineering» — теж фейк. Єдиним «першопрохідцем», якого підтвердила фактчек, був Джош Сіммонс: його стаття «We Are Entering the Graph Engineering Phase» написана 4 липня, за два тижні до цього жарту — **жарт зробив цю тему популярною, але не він її створив.**
@@ -257,11 +257,11 @@ run(graph, entry={"requirements": "виправити баг на сторінц
## Відкриті проєкти: ті, що з'явилися після публікації, і ті, що до неї
-Спершу розмежуй: **Graph Engineering — це назва, яка з'явилася лише після 18 липня 2026 року.** Фреймворки, відкриті до цього, — не «проєкти після публікації Graph Engineering». Той відкритий проєкт, який з'явився вже після спалаху концепції і напряму з такою назвою, станом на початок серпня 2026 року втримується лише один:
+Спершу розмежуй: **Graph Engineering — це назва, яка з'явилася лише після 18 липня 2026 року.** Фреймворки, відкриті до цього, — не «проєкти після публікації Graph Engineering». Один проєкт, який прямо використовує цю назву, — GraphARC:
**Ті, що з'явилися після публікації концепції**
-- [GraphArc](https://github.com/CodeGraphContext/grapharc) (2026-08-02): називає себе «першою живою реалізацією Graph Engineering». Він перетворює виконання агента з trace, захованого в логах, на **інтерактивну графу оркестрації в реальному часі** — кожен агент, кожна залежність, кожна точка рішення намальовані, і ти видиш увесь граф до виконання, підтверджуєш (можна навіть подивитися з телефона), а потім відпускаєш. Автор робив графові інструменти для 4000+ розробників, напрямок — «спостережуваність, можливість налагодження, інженерна міцність». Дуже новий, функціонально ще в ранній стадії.
+- [GraphARC](https://github.com/CodeGraphContext/GraphARC) (створений у липні 2026): описує себе як «наскрізну реалізацію Graph Engineering, запропонованого Ендрю Нгом і Пітером Штайнбергером». Це ранній Python-проєкт. Корисний крок — прочитати його модель оркестрації й вирішити, чи підходить цей підхід для вашого робочого процесу.
**Ті, що існували до публікації концепції (вони не називаються Graph Engineering, але саме ними ти будеш користуватися, коли будуватимеш)**
@@ -325,7 +325,7 @@ run(graph, entry={"requirements": "виправити баг на сторінц
- [goddaehee: фактчек Graph Engineering (корейською, 2026-07-30)](https://goddaehee.tistory.com/628) — найповніший фактчек: хронологія походження жарту, розбір фейкових цифр, дані LangGraph, порівняння популярності на Hacker News
- [Джош Сіммонс: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — серйозна стаття, що вийшла за два тижні до жарту
- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — офіційна відповідь: «не нова ідея, а найновіша назва наявного підходу»; LangGraph — 65+ мільйонів завантажень на місяць
-- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — дані про поширення модного слова (перший твіт — 575 тисяч переглядів)
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — розповідь про те, як поширювався термін
- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — горизонтальне порівняння семи основних відкритих фреймворків: LangGraph, CrewAI, Microsoft Agent Framework, LlamaIndex, Google ADK, OpenAI Agents SDK, Mastra
- [Офіційна документація LangGraph](https://docs.langchain.com/oss/python/langgraph/graph-api) — «Nodes do the work, edges tell what to do next»; точні визначення вузлів і ребер, першоджерело для побудови графа
- [Anthropic: Building Effective Agents (груд 2024)](https://www.anthropic.com/engineering/building-effective-agents) — п'ять патернів, намальовані — це граф; авторитетне розрізнення workflow та агента
diff --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.md
index 53b5c91..2200975 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
@@ -9,13 +9,13 @@ Oʻzingizni AI olamida tajribali deb hisoblaysiz — Claude Pro obunangiz bor, G
Birinchi reaksiyangiz? “Bu model yetarli emas. Yaxshiroq modelga oʻtish vaqti keldi.” Toʻxtang. Yangi obunaga pul sarflashga shoshilmang — ehtimol, muammo umuman modelda emasdir.
-Raqamlarga qaraylik. 2025-yil oxiriga kelib, SWE-bench Verifiedʼdagi eng kuchli kodlash agentlari taxminan 50–60% natija koʻrsatmoqda. Bu — sinchiklab tanlangan, aniq tavsifli va testlari mavjud vazifalarda. Kundalik dasturlash muhitiga oʻtsangiz — talablar noaniq, testlar yoʻq, biznes qoidalari hamma joyga sochilib yotgan — bu raqam yana ham pasayadi.
+Raqamlarga qaraylik. 2025-yil 29-sentabrda Anthropic Claude Sonnet 4.5 modelini eʼlon qildi: [SWE-bench Verified boʻyicha 77,2%](https://www.anthropic.com/news/claude-sonnet-4-5). Bu — sinchiklab tanlangan, aniq tavsifli va testlari mavjud vazifalarda. Kundalik dasturlash muhitiga oʻtsangiz — talablar noaniq, testlar yoʻq, biznes qoidalari hamma joyga sochilib yotgan — bu raqam yana ham pasayadi.
Ammo bu raqamlar ortida intuitsiyaga zid bir haqiqat yashiringan.
## Bir xil ot, turlicha taqdir
-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.
+Anthropic bir xil prompt (“2D retro oʻyinlar yaratish dasturini qur”) va bir xil modelni (Opus 4.5) ikki xil harness ostida solishtirdi. Birinchi sinov — hech qanday qoʻshimcha vositasiz: 20 daqiqa, 9 dollar; dastur ochildi, lekin obyektlar kiritilgan buyruqlarga javob bermadi. Ikkinchi sinov — toʻliq harness bilan (planner + generator + evaluator — uch agentli arxitektura): 6 soat, 200 dollar; bitta obyektni siljitish mumkin edi, ammo fizika dagʻal, devor esa yoʻlni toʻsib qoʻygan edi. [Asosiy oʻyin mexanikasi ishladi, ammo dastur tugallanmagan.](https://www.anthropic.com/engineering/harness-design-long-running-apps)
Ular modelni oʻzgartirmadi. Opus 4.5 hamon Opus 4.5 edi. Oʻzgargan narsa — ot anjomlari.
@@ -39,9 +39,9 @@ Bir necha sessiyaga choʻzilgan uzun vazifalar yana ham yomonroq — oldingi ses
Bu 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.
+- **Capability Gap (Imkoniyatlar tafovuti)**: Modelning benchmark natijalari va haqiqiy vazifalarda koʻrsatadigan natijalari oʻrtasidagi katta tafovut. Benchmark vazifalarida aniq tavsif, testlar va tayyor muhit boʻladi; haqiqiy vazifalarda bularning koʻpini siz taʼminlashingizga toʻgʻri keladi.
- **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.
+- **Harness-Induced Failure (Harness keltirib chiqargan muvaffaqiyatsizlik)**: Modelda yetarli imkoniyat mavjud, ammo bajarilish muhitida strukturaviy nuqsonlar bor. Yuqoridagi retro oʻyin taqqoslamasi — shunga misol.
- **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.
- **Definition of Done (Bajarilganlik mezonlari)**: Mashina tomonidan tekshirilishi mumkin boʻlgan shartlar toʻplami — testlar oʻtadi, lint toza, type check muvaffaqiyatli. Aniq DoD boʻlmasa, agent oʻzicha ixtiro qiladi.
@@ -73,7 +73,7 @@ Bajarilganlik mezonlari:
## Million qatorlik tajriba
-OpenAI 2025-yilda jasoratli tajriba oʻtkazdi: boʻsh git repozitoriyasidan boshlab, Codex yordamida butun ichki mahsulotni qurish. Besh oydan soʻng repoda taxminan bir million qator kod paydo boʻldi — ilova mantiqi, infratuzilma, asboblar, hujjatlar, ichki dev vositalar — barchasi agent tomonidan yaratilgan. Uchta muhandis Codexʼni boshqarib, taxminan 1 500 ta PR ochib va birlashtirib bordi. Kuniga har bir kishiga oʻrtacha 3,5 ta PR.
+2025-yil avgustida OpenAIʼda uchta muhandis jasoratli tajriba boshladi va qoidalar oddiy edi: ular oʻzlari kod yozmaydi — faqat Codex yozadi. Boʻsh git repozitoriyasidan boshlab, [besh oydan soʻng repoda taxminan bir million qator kod](https://openai.com/index/harness-engineering/) paydo boʻldi — ilova mantiqi, infratuzilma, asboblar, hujjatlar, ichki dev vositalar — barchasi agent tomonidan yaratilgan. Keyinchalik jamoa yettita muhandisga yetdi; shu davr mobaynida taxminan 1 500 ta PR birlashtirildi — kuniga har bir muhandisga oʻrtacha 3,5 tadan.
Asosiy cheklov: **odamlar hech qachon kodni toʻgʻridan-toʻgʻri yozmagan.** Bu hiyla emas edi — bu jamoani muhandisning asosiy ishi endi kod yozish emas, balki muhitlarni loyihalash, niyatni ifodalash va qayta aloqa sikllarini qurishga aylanganda nima oʻzgarishini aniqlashga majbur qilish uchun moʻljallangan edi.
@@ -87,9 +87,9 @@ Bu tajriba mazkur maʼruzaning asosiy tezisini bevosita isbotlaydi: **bir xil mo
Bir jamoa Claude Sonnetʼdan foydalanib oʻrta hajmdagi Python web ilovasiga (FastAPI + PostgreSQL + Redis, ~15 000 qator kod) yangi API endpoint qoʻshdi.
-Boshida ular faqat bir jumla berishdi: “`/api/v2/users` ostida foydalanuvchi sozlamalari endpointʼlarini qoʻsh”. Natija? Agent kontekst oynasining 40%'ini repo strukturasini oʻrganishga sarfladi, koʻrinishidan oqilona kodni yozdi, ammo loyihaning xatoliklarni boshqarish naqshlariga rioya qilmadi, eski SQLAlchemy sintaksisidan foydalandi va endpointʼda esa runtime xatoliklari mavjud edi — agent buni eʼtiborga olmay “tayyor” deb eʼlon qildi. Keyingi sessiya butun oʻrganish ishini boshidan boshlashga majbur boʻldi.
+Boshida ular faqat bir jumla berishdi: “`/api/v2/users` ostida foydalanuvchi sozlamalari endpointʼlarini qoʻsh”. Natija? Agent sessiyasining katta qismini repo strukturasini oʻrganishga sarfladi, koʻrinishidan oqilona kodni yozdi, ammo loyihaning xatoliklarni boshqarish naqshlariga rioya qilmadi, eski SQLAlchemy sintaksisidan foydalandi va endpointʼda esa runtime xatoliklari mavjud edi — agent buni eʼtiborga olmay “tayyor” deb eʼlon qildi. Keyingi sessiya butun oʻrganish ishini boshidan boshlashga majbur boʻldi.
-Keyin ular `AGENTS.md` qoʻshdi (loyiha arxitekturasi va texnologiya versiyalari tasviri bilan), aniq tekshirish buyruqlari (`pytest tests/api/v2/ && python -m mypy src/`) va arxitektura qaroriga oid yozuvlar qoʻshdilar. Aynan oʻsha model uchchala mustaqil sinovda muvaffaqiyatga erishdi, kontekst samaradorligi taxminan 60%'ga yaxshilandi.
+Keyin ular `AGENTS.md` qoʻshdi (loyiha arxitekturasi va texnologiya versiyalari tasviri bilan), aniq tekshirish buyruqlari (`pytest tests/api/v2/ && python -m mypy src/`) va arxitektura qaroriga oid yozuvlar qoʻshdilar. Aynan oʻsha model loyiha konvensiyalariga rioya qildi va ishini oʻzi ishga tushira oladigan buyruqlar bilan tekshirdi.
Ular modelni oʻzgartirmadi. Ular harnessʼni oʻzgartirdi.
diff --git a/docs/uz/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/uz/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
index 3adac12..7c20926 100644
--- a/docs/uz/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
+++ b/docs/uz/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -52,7 +52,7 @@ flowchart LR
- **Kontekst oynalari cheklangan**: Qanday oyna oʻlchami daʼvo qilinmasin (128K, 200K, 1M), uzoq davom etadigan vazifalar oxir-oqibat ularni yeb tugatadi. Tugagandan soʻng, zichlash (maʼlumot yoʻqotish) yoki qayta ishga tushirish (yangi sessiya) talab qilinadi. Ikkalasida ham nimanidir yoʻqotasiz.
- **Uzluksizlik artefaktlari (Continuity artifacts)**: Yangi sessiyaga oxirgi sessiya toʻxtagan joydan hech qanday noaniqliksiz davom ettirish imkonini beruvchi doimiy saqlangan holat fayllari. Asosiy shakli: jarayon jurnali + tekshiruv qaydnomasi + keyingi qadamlar. Oʻsha ustaning kundaligi kabi.
-- **Tiklash narxi (Rebuild cost)**: Yangi sessiyaning bajariladigan holatga kelishi uchun kerak boʻladigan vaqt. Yaxshi harnessʼlar tiklash narxini 15 daqiqadan 3 daqiqagacha qisqartirishi mumkin.
+- **Tiklash narxi (Rebuild cost)**: Yangi sessiyaning bajariladigan holatga kelishi uchun kerak boʻladigan vaqt. Yaxshi harnessʼ jarayon, tekshiruv natijalari va keyingi qadamlarni fayllarda qoldiradi, shunda yangi sessiya yozib qoʻyilgan holatdan boshlaydi.
- **Siljish (Drift)**: Agentʼning tushunchasi va kod repozitoriysining haqiqiy holati oʻrtasidagi farq. Har bir sessiya chegarasi siljishni keltirib chiqaradi; nazoratsiz u tobora ortib boradi.
- **Kontekst xavotiri (Context anxiety)**: Anthropic tomonidan kuzatilgan hodisa — agentlar idrok qilinayotgan kontekst chegaralariga yaqinlashganda erta yakunlash xatti-harakatlarini namoyish etadilar, maʼlumot yoʻqotilishining oldini olish uchun vazifalarni erta yakunlaydilar. Bu asossiz resurs xavotiridir.
- **Zichlash va qayta ishga tushirish (Compaction vs reset)**: Zichlash joriy sessiya ichidagi kontekstni xulosalaydi (“nima” saqlanadi, lekin “nega” yoʻqolishi mumkin); qayta ishga tushirish esa doimiy saqlangan holatdan tiklanadigan yangi sessiyani ochadi (toza, lekin artefaktlarning toʻliqligiga bogʻliq).
@@ -160,7 +160,7 @@ LangChain bir xil gpt-5.2-codex bilan 89 vazifali Terminal Bench 2.0 natijasi 52
- Kontekst oynalari cheklangan resursdir. Uzoq vazifalar sessiyalarga boʻlinadi, va sessiyalarda maʼlumot yoʻqoladi — har kuni hamma narsani unutadigan usta kabi, bu obyektiv haqiqatdir.
- Yechim kattaroq oynalar emas — bu holatni saqlashni yaxshilash. Jarayon fayllari + qaror jurnallari + git checkpointʼlari — amneziyali ustaga ishonchli kundalik bering.
- Agentʼga xotirasini yoʻqotgan muhandis kabi munosabatda boʻling: u “ishni tugatishidan” (clock out) oldin, nima qilingani, nega qilingani va keyingi nima ekanini yozib qoldirsin.
-- Tiklash narxi (rebuild cost) asosiy koʻrsatkichdir. Yaxshi harnessʼlar yangi sessiyani 3 daqiqa ichida ishga tushiradigan holatga keltirishi kerak.
+- Tiklash narxi (rebuild cost) asosiy koʻrsatkichdir. Yaxshi harnessʼ jarayon, tekshiruv natijalari va keyingi qadamlarni fayllarda qoldiradi, shunda yangi sessiya tezda tiklanadi.
- Aralash strategiya (Mixed strategy): qisqa vazifalar bitta sessiyada, uzoq davom etadigan vazifalar uzluksizlik uchun tizimli artefaktlar bilan sessiyalararo.
## Qoʻshimcha oʻqish uchun
diff --git a/docs/uz/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/uz/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
index 68075e6..6784e45 100644
--- a/docs/uz/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
+++ b/docs/uz/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -37,7 +37,7 @@ flowchart TB
## Ularni aralashtirib yuborsangiz nima boʻladi
-Eng toʻgʻridan-toʻgʻri muammo: poydevor toʻgʻri qotmaydi. Agent oʻz kuchining 80 foizini funksiya kodiga, 20 foizini esa shoshilinch qandaydir infratuzilmani sozlashga sarflaydi. Test freymvorki sozlangan, lekin hech qachon tekshirilmagan, lint qoidalari qoʻyilgan, lekin oʻta yumshoq, jarayon fayli (progress file) tuzilmagan. Bu kamchiliklar birinchi sessiyada darhol bilinmaydi (chunki agent oʻzi nima qilganini hali eslaydi), lekin ikkinchi sessiyada namoyon boʻladi — yangi agent qanday ishlashni, qanday test qilishni yoki ishlarning qayerda ekanligini bilmaydi. Qaltis poydevor, titroq bino.
+Eng toʻgʻridan-toʻgʻri muammo: poydevor toʻgʻri qotmaydi. Agent oʻz kuchining katta qismini funksiya kodiga sarflaydi, infratuzilmani esa keyinga surib, shoshilinch sozlab oʻtadi. Test freymvorki sozlangan, lekin hech qachon tekshirilmagan, lint qoidalari qoʻyilgan, lekin oʻta yumshoq, jarayon fayli (progress file) tuzilmagan. Bu kamchiliklar birinchi sessiyada darhol bilinmaydi (chunki agent oʻzi nima qilganini hali eslaydi), lekin ikkinchi sessiyada namoyon boʻladi — yangi agent qanday ishlashni, qanday test qilishni yoki ishlarning qayerda ekanligini bilmaydi. Qaltis poydevor, titroq bino.
Yana bir yashirin xarajat bu “tekshirilmagan toʻplanish” (unverified accumulation) — test freymvorki sozlanishidan oldin yozilgan kod, bu tekshiruvi yoʻq kod degani. Oxir-oqibat oʻsha kod uchun testlar yozishga qaytganingizda, boshidanoq dizayn notoʻgʻri qilinganini koʻrishingiz mumkin — agar shuni avvalroq bilganingizda, uni boshqacha amalga oshirgan boʻlardingiz. Bu hoʻl beton ustiga kafel yotqizishga oʻxshaydi — polning tekis emasligini anglab yetganingizda, barcha kafelni qoʻporib, qaytadan terishga toʻgʻri keladi.
@@ -45,7 +45,7 @@ Sessiya byudjeti ham bekorga sarflanadi. Inisializatsiya ishlari (muhitlarni soz
Eng osongina koʻzdan qochadigan muammo — bu oshkor qilinmagan taxminlar, minalar kabi yashirin tahdidlar (implicit assumption landmines). Agentning inisializatsiya davomida qabul qilgan qarorlari (qaysi test freymvorki ishlatilgan, kataloglar qanday tartiblangan, bogʻliqliklar qanday boshqarilgan) — agar ochiq-oydin yozib qoldirilmasa, keyingi sessiyalar bu tanlovlarni tushunolmaydi. Eng yomoni shundaki, keyingi sessiyalar unga zid qarorlar qabul qilishi mumkin. Birinchi qurilish jamoasi beton poydevordan foydalandi, ikkinchi jamoa buni bilmasdan turib uning ustiga yogʻoch qoqdi — poydevor yorilib ketdi.
-Anthropicʼning uzoq muddatli dasturlarni yaratish boʻyicha tadqiqoti inisializatsiyani implementatsiyadan ajratishni ochiq-oydin tavsiya qiladi. Ularning tajriba maʼlumotlari: maxsus inisializatsiya bosqichidan foydalangan loyihalar, aralash usulga nisbatan, koʻp sessiyali (multi-session) ssenariylarda funksiyalarning 31% koʻproq tugallanish koʻrsatkichini namoyish etgan. Asosiy tushuncha — inisializatsiya bosqichiga sarflangan vaqt, keyingi 3-4 sessiyada toʻliq oqlanadi. Poydevor qanchalik mustahkam boʻlsa, devorlar shuncha tez koʻtariladi.
+Anthropicʼning uzoq davom etadigan agentlar boʻyicha ishi [inisializatsiyani alohida birinchi sessiya](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) qilib ajratishni tavsiya qiladi. Inisializator `init.sh` skriptini, jarayon faylini, funksiyalar roʻyxatini va dastlabki git commitʼini yozadi; keyingi kodlash sessiyalari oʻsha holatni oʻqiydi, bir vaqtda bitta funksiya ustida ishlaydi, uni end-to-end test qiladi, commit qiladi va jarayon faylini yangilaydi.
OpenAIʼning Codex harness muhandislik qoʻllanmasi ham “repo operatsion yozuv sifatida” (repository as operational record) tamoyilini taʼkidlaydi — birinchi ishga tushishdanoq aniq operatsion strukturani oʻrnating, aks holda har bir yangi sessiya loyiha qoidalarini (conventions) qaytadan aniqlashiga toʻgʻri keladi.
diff --git a/docs/uz/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/uz/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
index fcfbcb5..71c0ecc 100644
--- a/docs/uz/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
+++ b/docs/uz/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -26,7 +26,7 @@ Claude Codeʼning haqiqiy xatti-harakati buni aniq koʻrsatadi. Unga “foydalan
Oltita qadam oʻtgach, ularning har biri chala bajarilgan boʻladi. Hech qanday end-to-end tekshiruv (verification) yoʻq, chala pishgan kodlar oʻrtasida murakkab bogʻlanishlar mavjud boʻladi va chala ishlarni davom ettirishi kerak boʻlgan keyingi sessiya mutlaqo adashib qoladi. Xuddi bir vaqtning oʻzida oltita taom pishirayotgan odamga oʻxshaydi — hamma ovqat tovadadir, lekin birortasi ham tortilmagan (plated). Ularning hammasi kuyadi.
-Anthropicʼning eksperimental maʼlumotlari buni bevosita tasdiqlaydi: “kichik keyingi qadam” (small next step) strategiyasidan (WIP=1 ga teng) foydalanadigan agentlar keng promptʼlardan foydalanadigan agentlarga qaraganda 37% yuqori vazifa yakunlash darajasini koʻrsatadi. Eng qizigʻi shundaki, agentlar tomonidan yozilgan kod qatorlarining soni haqiqatda yakunlangan funksiyalar bilan zaif manfiy (teskari) korrelyatsiyaga ega — kod qanchalik koʻp yozilsa, shuncha kam funksiyalar yakunlanadi. Oʻzi chaynay oladiganidan kattaroq tishlash, maʼlumotlar bilan isbotlangan.
+Anthropicʼning uzoq davom etadigan agentlar boʻyicha koʻrsatmasi [kodlash agentidan bir vaqtda bitta funksiya ustida ishlashni](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) soʻraydi, soʻng davom etishdan oldin tekshirishni, commit qilishni va jarayonni yangilashni talab qiladi. Keng prompt esa agentni bir nechta yoʻnalishni birvarakayiga boshlashga undaydi, va har bir yoʻnalish bir xil kontekst hamda tekshiruv byudjeti uchun raqobatlashadi.
## WIP=1 Ish jarayoni (Workflow)
diff --git a/docs/uz/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/uz/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
index 13e5cb8..68b6aa5 100644
--- a/docs/uz/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
+++ b/docs/uz/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -22,7 +22,7 @@ User auth qilindi, savat asosan tugatildi, toʻlov qismi (payments) hali kerak
```
Yangi agent sessiyasi ushbu eslatmadan quyidagi savollarga javob bera oladimi? “Asosan tugatildi” deganda nima nazarda tutilgan? Savat qaysi testlardan oʻtdi? Toʻlovlar (payments) qilinishiga nima toʻsqinlik qilyapti (blocking)? Bularning barchasiga javob — “hech kim bilmaydi”. Xuddi shifokorga “oshqozonim ogʻriyapti, lekin oxirgi paytda yaxshi edim” deyishga oʻxshaydi — u sizga qanday dori yozib bera oladi?
-Natija: yangi sessiya loyiha holatini (project state) tushunish uchun 20 daqiqa sarflaydi va allaqachon bajarilgan funksiyalarni qaytadan yozib chiqishi mumkin. Anthropicʼning muhandislik maʼlumotlari shuni koʻrsatadiki, jarayon boʻyicha yaxshi qaydlar sessiyani ishga tushishdan keyingi tashxis vaqtini 60-80% ga qisqartiradi.
+Natija: yangi sessiya loyiha holatini (project state) oʻzi taxmin qilishiga toʻgʻri keladi va allaqachon bajarilgan funksiyalarni qaytadan yozib chiqishi mumkin. Anthropicʼning maslahati — [jarayon va tekshiruv natijalarini versiyalangan fayllarda qayd etish](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), shunda keyingi sessiya holatni koʻzdan kechira oladi.
## Funksiya holati mashinasi (Feature State Machine)
@@ -111,7 +111,7 @@ Har bir funksiya (feature) bandi “bitta sessiyada tugatilishi mumkin” boʻlg
**Umurtqa pogʻona rejimi (Backbone mode)**: Har bir funksiyaning (feature) aniq holati va tekshiruv buyrugʻi (verification command) bor. Yangi sessiya funksiyalar roʻyxatini oʻqiydi va 3 daqiqa ichida hamma narsani tushunib oladi: F01-F05 — `passing`, F06 — `active`, F07-F10 — `not_started`. Ishni toʻgʻridan-toʻgʻri F06 dan boshlaydi, hech qanday ishni boshidan qilmaydi (zero rework).
-Miqdoriy natija (Quantified result): Strukturalangan funksiyalar roʻyxatidan (structured feature lists) foydalangan loyihalar erkin kuzatish (free-form tracking) tizimidagiga qaraganda 45% ga yuqori funksiyalarni tugallash (feature completion) darajasini koʻrsatdi va hech qanday funksiya takror amalga oshirilmadi.
+Strukturalangan roʻyxat har bir funksiyaning holati va tekshiruv buyrugʻini bir joyga jamlaydi, shunda yangi sessiya nima bajarilganini biladi.
## Asosiy xulosalar
diff --git a/docs/uz/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/uz/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
index c5974c4..98ddf9c 100644
--- a/docs/uz/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
+++ b/docs/uz/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -70,7 +70,7 @@ Mustaqil baholovchi (evaluator) agentni aynan “injiq” (picky) boʻlishga soz
| Arxitektura | Runtime | Narx | Asosiy funksiyalar ishlayaptimi? |
|--------------|---------|------|------------------------|
| Bitta Agent (bare run) | 20 daq | $9 | Yoʻq (oʻyin obyektlari javob qaytarmaydi) |
-| Uchta Agent (rejalashtiruvchi + yaratuvchi + tekshiruvchi) | 6 soat | $200 | Ha (oʻyin toʻliq ishlaydi) |
+| Uchta Agent (rejalashtiruvchi + yaratuvchi + tekshiruvchi) | 6 soat | $200 | Asosiy oʻyin mexanikasi ishladi; fizika va daraja muammolari qoldi |
Bu ayni bitta model (Opus 4.5) va bitta prompt (“2D retro oʻyin muharririni yarat”). Faqatgina harness farq qiladi — “qoʻshimcha tuzilmasiz muhit (bare environment)” dan “rejalashtiruvchi talablarni kengaytiradi → yaratuvchi birin-ketin funksiyalarni bajaradi → tekshiruvchi Playwright yordamida haqiqiy klik orqali testlarni (click testing) amalga oshiradi” formatiga oʻtilgan.
@@ -119,7 +119,7 @@ Samarali runtime signallarga quyidagilar kiradi:
**Aslida qayerdan ball olib tashlangan (Point deductions)**: (1) End-to-end oqimi sinovdan oʻtmagan — haqiqiy havolani yuborish va parolni tiklash ishlashi tasdiqlanmagan. (2) Maʼlumotlar bazasi migratsiyasi yarmi ishlagandan soʻng yiqilib, sxema nomuvofiqligini keltirib chiqargan. (3) Target muhitda elektron pochta xizmati sozlamalari (config) kiritilmagan.
-**Harness aralashuvi**: Tugatish validatsiyasi (Termination validation) ishga tushdi — (1) Tiklash (reset) endpointʼiga kirish mumkinligini tekshirish uchun toʻliq ilovani ishga tushirish; (2) Toʻliq tiklash oqimini (reset flow) bajarish; (3) Maʼlumotlar bazasi holati toʻgʻriligini (consistency) tekshirish. Barcha xatoliklar shu sessiyaning oʻzida aniqlandi, bu esa keyingi yuzaga keladigan tuzatish narxini 5-10 barobargacha tejadi. Haqiqiy muammolarni mustaqil baholovchi (evaluator) topdi.
+**Harness aralashuvi**: Tugatish validatsiyasi (Termination validation) ishga tushdi — (1) Tiklash (reset) endpointʼiga kirish mumkinligini tekshirish uchun toʻliq ilovani ishga tushirish; (2) Toʻliq tiklash oqimini (reset flow) bajarish; (3) Maʼlumotlar bazasi holati toʻgʻriligini (consistency) tekshirish. Uchala xatolik ham shu sessiyaning ichida yuzaga chiqadi — tuzatish narxi hali mahalliy boʻlganda. Haqiqiy muammolarni mustaqil baholovchi (evaluator) topdi.
## Asosiy xulosalar
diff --git a/docs/uz/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/uz/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
index e249589..d8a2456 100644
--- a/docs/uz/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
+++ b/docs/uz/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -132,7 +132,7 @@ Har gal kod review (kodni tekshirish) paytida yangi agent xatosi topilsa, shunga
| Ruxsat berish (Permission Issue) | Yuklangan (packaged) muhitida ruxsat berish konfiguratsiyasi xatosi | Oʻtkazib yuborilgan | Tutilgan |
| Xatolar (Error Propagation) | Service qatlamidagi istisnolar UI qatlamiga yetib bormagan | Oʻtkazib yuborilgan | Tutilgan |
-Yuqoridagi 5 muammoni E2E tutilganida, unit testlarning birontasi ushlab qola olmadi. Bunga 2 soniyadan 15 soniyagacha oshgan sinov vaqti evaziga erishildi — agent workflowʼida buning hech yomon yeri yoʻq. Har bir partiya alohida qanchalik yaxshi kuylanmasin, toʻliq xor mashqi bilan tenglasholmaydi.
+Yuqoridagi 5 muammoni E2E tutilganida, unit testlarning birontasi ushlab qola olmadi. Bunga end-to-end sinovning sekinroq ishlashi evaziga erishildi — ammo bu xarajat beshta chegara nuqsonini chiqarib yuborish bilan solishtirganda kichik. Har bir partiya alohida qanchalik yaxshi kuylanmasin, toʻliq xor mashqi bilan tenglasholmaydi.
## Asosiy xulosalar
diff --git a/docs/uz/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/uz/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
index 3ef3bd9..75e9865 100644
--- a/docs/uz/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
+++ b/docs/uz/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -44,7 +44,7 @@ Harnessʼda kuzatuvchanlik boʻlmasa, tizimli ravishda toʻrt turdagi muammo yuz
**Qayta urinishlar (Retries) koʻr-koʻrona taxminga aylanadi**: Qachonki agent biror narsa nega yiqilganini bilmasa, qayta urinish yoʻnalishi mutlaqo tasodifiy boʻladi. U notoʻgʻri yoʻnalishda qayta-qayta urinishi mumkin — xatoning asl sababini eʼtiborsiz qoldirib, unga umuman aloqasi boʻlmagan joylarni tuzatib yotadi. Har bir koʻr-koʻrona urinish token va vaqt sarflaydi.
-**Sessiyalararo maʼlumot jarligi (Session handoff information cliff)**: Chala bajarilgan ish keyingi sessiyaga uzatilsa, kuzatuvchanlikning yoʻqligi yangi sessiya tizim holatini boshidan oʻrganishga majbur boʻlishini anglatadi. Anthropicʼning uzoq davom etadigan agentlar boʻyicha kuzatuvlari shuni koʻrsatadiki, bu takroriy oʻrganish (redundant diagnosis) jami sessiya vaqtining 30-50% ini yeb qoʻyishi mumkin.
+**Sessiyalararo maʼlumot jarligi (Session handoff information cliff)**: Chala bajarilgan ish keyingi sessiyaga uzatilsa, kuzatuvchanlikning yoʻqligi yangi sessiya tizim holatini boshidan oʻrganishga majbur boʻlishini anglatadi. Yangi sessiya kodni qayta oʻqishi, buyruqlarni qayta ishga tushirishi va qaysi signallar muhimligini oʻzi hal qilishi kerak; [versiyalangan jarayon va tekshiruv qaydlari](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) koʻzdan kechirsa boʻladigan holatni beradi.
### Claude Code ishtirokidagi hayotiy vaziyat
@@ -54,7 +54,7 @@ Faraz qiling, harness “rejalashtiruvchi-yaratuvchi-baholovchi (planner-generat
**Toʻliq kuzatuvchanlik bilan**: Rejalashtiruvchi sprint shartnomasini — qaysi komponentlar oʻzgarishi, har biri uchun tekshirish standartlari va istisnolar (masalan, bosma uchun stillar chiqarilmasin) ni aniq chiqarib beradi. Yaratuvchi xuddi shu shartnoma asosida kod yozadi. Runtime kuzatuvchanligi har bir komponentning stil yuklanishi va qoʻllanish jarayonini qayd etadi. Baholovchi baholash rubrikasidan foydalanib oʻlchamlar boʻyicha baholaydi va aniq dalillarni keltiradi. Bitta iteratsiya (aylanish) yuqori sifatli natija beradi va bor-yoʻgʻi 15 daqiqa oladi.
-3 barobar samaradorlik farqi. Yagona farq — kuzatuvchanlikdir.
+Farq shundan kelib chiqadiki, shartnoma va dalillar agentning boshidan tashqarida mavjudmi yoki yoʻq.
### Nega agentlar buni oʻzlari yecha olishmaydi
@@ -128,7 +128,7 @@ Rejalashtiruvchi-yaratuvchi-baholovchi (planner-generator-evaluator) jarayonidan
- Baholash rubrikasi oʻlchamlar boʻyicha tuzilmali baho berish imkoniyatini taqdim etadi
- Bitta aylanishda (iteration) 15 daqiqada yuqori sifatli natija yuzaga keladi
-Samaradorlik 3 barobar yaxshilanadi, sifat barqarorlashadi va baholashlar takrorlanuvchan (reproducible) boʻladi.
+Natija sifati barqarorlashadi va baholashlar takrorlanuvchan (reproducible) boʻladi.
## Asosiy xulosalar
@@ -136,7 +136,7 @@ Samaradorlik 3 barobar yaxshilanadi, sifat barqarorlashadi va baholashlar takror
- **Ikkala kuzatuv qatlami ham zarur** — runtime signallar “nima boʻlganini” tushuntirsa, jarayon artefaktlari “nima uchun aynan shunday qilinganini” tushuntiradi.
- **Sprint shartnomalari tushunmovchilikni boshidanoq yoʻqotadi** — “yaratuvchi baholovchi koʻriboq rad etadigan narsani yasashini” oldini oladi.
- **Baholash rubrikalari bahoni takrorlanuvchan (reproducible) qiladi** — turli xil baholovchilar ayni bitta natija uchun bir xil baho berishini taʼminlaydi.
-- **Kuzatuvchanliksiz sessiya vaqtining 30-50% qismi ortiqcha narsalarni takror oʻrganishga sarflanadi.**
+- **Kuzatuvchanlik noaniq rad etishni aniq, tuzatish mumkin boʻlgan nuqsonga aylantiradi.**
## Qoʻshimcha oʻqish uchun
diff --git a/docs/uz/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/uz/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
index e56e697..1683973 100644
--- a/docs/uz/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
+++ b/docs/uz/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -54,7 +54,7 @@ flowchart LR
Dasturiy taʼminot evolyutsiyasining Leman qonunlariga (Lehmanʼs laws) koʻra: doimiy oʻzgarishdagi tizimlarning murakkabligi faol boshqarilmas ekan, u muqarrar ravishda oshib boraveradi. Bu ayniqsa AI kod yozish agentlari uchun toʻgʻri — har bir sessiya oʻzgarishlar olib kiradi va chiqishda tozalab ketilmasa, texnik qarz (technical debt) eksponensial tarzda koʻpayib boradi.
-Haqiqiy maʼlumotlar soʻzlaydi. Hech qanday tozalash strategiyasisiz agentlar bilan 12 hafta davomida ishlab chiqilgan loyiha:
+Faraziy 12 haftalik loyiha uchun quyidagi qiymatlarni tasavvur qiling:
- 1-hafta: Build oʻtish darajasi 100%, testlar oʻtish darajasi 100%, yangi sessiyani boshlash 5 daq
- 4-hafta: Build 95%, testlar 92%, boshlash 15 daq
@@ -66,7 +66,7 @@ Xuddi shu loyiha tozalash strategiyasi bilan:
- 1-hafta: 100%, 100%, 5 daq
- 12-hafta: 97%, 95%, 9 daq
-12 haftadan soʻng: build oʻtish darajasi oʻrtasida 29 foiz punkti farq, yangi sessiyani boshlash vaqti oʻrtasida esa 85% farq bor. Bu faqat nazariya emas — bu kuzatilgan aniq farqdir.
+Haftalik tozalash sikli boshlangʻich holatni barqaror ushlab turadi: har bir sessiya build, testlar, jarayon va vaqtinchalik artefaktlarni tartibga solingan holda tugaydi, shuning uchun keyingi sessiya xuddi shu bazadan boshlaydi.
### Toza holatning besh oʻlchami
@@ -76,7 +76,7 @@ Toza holat bu shunchaki “kod kompilyatsiya boʻladi” degani emas. U beshta o
**Test oʻlchami**: Barcha testlar oʻtmoqdami? Sessiyadan oldin mavjud boʻlgan testlar ham — bu sessiya mavjud funksiyani (functionality) buzmaslikka masʼuldir. Va u faqat “mening kompyuterimda ishlayapti” boʻlib qolmay, CIʼda ham tekshirilishi shart.
-**Jarayon (Progress) oʻlchami**: Joriy ishning jarayoni mashina oʻqiy oladigan artefaktga yozilganmi? Oʻzining qabul qilish shartlariga (passing criteria) ega tugatilgan sub-vazifalar, jarayonda boʻlgan lekin tugallanmaganlarining joriy holati va hali boshlanmaganlari kiritilishi kerak. Yaxshi jarayon qaydlari yangi sessiya ishga tushgandagi diagnostika vaqtini 60-80% gacha kamaytiradi.
+**Jarayon (Progress) oʻlchami**: Joriy ishning jarayoni mashina oʻqiy oladigan artefaktga yozilganmi? Oʻzining qabul qilish shartlariga (passing criteria) ega tugatilgan sub-vazifalar, jarayonda boʻlgan lekin tugallanmaganlarining joriy holati va hali boshlanmaganlari kiritilishi kerak. Jarayon va tekshiruv natijalarini versiyalangan fayllarda qayd eting, shunda keyingi sessiya holatni koʻzdan kechira oladi.
**Artefakt oʻlchami**: Eskirgan yoki noaniq vaqtinchalik artefaktlar qolmadimi? Debug loglari, vaqtinchalik fayllar, izoh qilib qoldirilgan kodlar (commented-out code), TODO eslatmalari — bularning barchasi keyingi sessiya uchun bilish kerak boʻlgan kognitiv yukni (cognitive load) oshiradi.
@@ -160,7 +160,7 @@ Ikkita yondashuv bilan 12 hafta davomida agentlar yordamida ishlab chiqilgan Ele
**Tozalash strategiyasi bilan** (tajriba guruhi - experimental group): Har bir sessiya yakunida toʻliq toza-holat tekshiruvi (clean-state check) + haftalik tozalash sikli (weekly cleanup loop). 12-haftada, build oʻtish darajasi 97%, test oʻtish darajasi 95%, yangi sessiyani boshlash vaqti 9 daq, eskirgan artefaktlar 11 ta.
-12-haftaga kelib, tajriba guruhining build oʻtish darajasi 29 foiz punkti yuqori, test oʻtish darajasi 34 foiz punkti yuqori va yangi sessiyani boshlash vaqti 85% ga qisqa.
+12-haftaga kelib, tozalash guruhining build va test oʻtish darajalari boshlangʻich darajaga yaqin qoldi, yangi sessiya tez boshlanadi va eskirgan artefaktlar ham oz edi. Tozalash har sessiyada bir necha daqiqa oladi va keyingi sessiya ishonsa boʻladigan boshlangʻich holatni qaytaradi.
## Asosiy xulosalar
diff --git a/docs/uz/lectures/lecture-13-loop-engineering/index.md b/docs/uz/lectures/lecture-13-loop-engineering/index.md
index fe6be2e..e837c0f 100644
--- a/docs/uz/lectures/lecture-13-loop-engineering/index.md
+++ b/docs/uz/lectures/lecture-13-loop-engineering/index.md
@@ -84,11 +84,11 @@ Ushbu maʼruza mavzusi boʻlgan Loop Engineering (Loop muhandisligi) hech qanday
Siz har safar `/goal` terishingiz shart emas. Lekin u qayerdan kelganini va nima uchun shunday koʻrinishini tushunish — bu loop muhandisligining yadrosini tushunishdir. Murakkabroq loopʼlar shunchaki rejalashtirish, parallelizm, izolyatsiya va xotira kabi qismlarni shu uchta asos: maqsad, tekshirish, toʻxtash sharti ustiga qoʻshadi.
-## 2026-yil iyun: Bir haftada uchta odam bir xil gʻoyani oldi
+## Har xil sanalar, bir xil yoʻnalish
-2026-yil iyun oyining birinchi haftasida kodlash agentlari infratuzilmasini qurgan uchta amaliyotchilar — bir-birlari bilan maslahatlashmasdan — turli soʻzlar bilan bir xil narsani aytdilar.
+Bir xil gʻoya turli joylarda, turli paytlarda yuzaga chiqdi.
-**Peter Steinberger** (OpenClaw yaratuvchisi, [uning postʼi 8 million marta koʻrildi](https://x.com/steipete/status/2063697162748260627)): "Siz endi kodlash agentlariga prompt yozmasligingiz kerak. Siz agentlaringizga prompt yozadigan loopʼlarni loyihalashingiz kerak."
+**Peter Steinberger** (OpenClaw yaratuvchisi, [oʻz postida](https://x.com/steipete/status/2063697162748260627)): "Siz endi kodlash agentlariga prompt yozmasligingiz kerak. Siz agentlaringizga prompt yozadigan loopʼlarni loyihalashingiz kerak."
**Boris Cherny** (Anthropicʼda Claude Code boshligʻi, [Acquired podkastida](https://x.com/rohanpaul_ai/status/2063289804708835412)): "Men endi Claudeʼga prompt yozmayman. Claudeʼga prompt yozadigan va nima qilishni aniqlaydigan loopʼlarim bor. Mening ishim loopʼlar yozishdan iborat."
@@ -96,9 +96,9 @@ Siz har safar `/goal` terishingiz shart emas. Lekin u qayerdan kelganini va nima
> **Loop muhandisligi — agentga prompt yozuvchi odam oʻrnini egallashdir. Buning oʻrniga qiluvchi tizimni siz loyihalasiz.**
-Cherny raqamlarni oshkor qildi: 30 dan ortiq ketma-ket kun davomida Claude Codeʼga barcha kod hissalari AI tomonidan mustaqil ravishda kiritildi — 259 ta merge qilingan PR, production kodining 80% dan ortigʻi Cloude tomonidan yozildi va ochiq dasturiy vazifalarda 76% muvaffaqiyat darajasi.
+Cherny [2025-yil 27-dekabrdagi shaxsiy hisobotida](https://twitter.com/bcherny/status/2004887829252317325) 30 kun ichida 259 ta PR birlashtirganini yozgan — 497 ta commit, 40 000 qator qoʻshilgan, 38 000 qator oʻchirilgan — va har bir satr Claude Code + Opus 4.5 tomonidan yozilganini taʼkidlagan.
-Uchta odam. Bir hafta. Bir xil xulosa. Bu ular kelishganligi uchun emas — infratuzilma jim qorindi oʻtdi. Agentlar no trivial vazifalarni kuzatuvsiz tugatish uchun etarlicha ishonchli holga keldi. Rejalashtirish primitivlari (`/loop`, `/goal`, cron) endi vositalarga oʻrnatilgan edi. Bitta agent ishlashining narxi shunchalik pastlashganki, taymerda qayta-qayta ishlatish isrofgarchi koʻrinishdan chiqdi. Barcha qismlar mavjud boʻlganda, ularni birlashtiruvchi harakat hamma uchun bir zumda aniq boʻladi.
+Bu iqtiboslar turli sanalar, turli formatlar va turli jamoalardan. Ularning umumiy yoʻnalishi — rejalashtirish, tekshirish va toʻxtash qarorini bevosita promptdan tizimga koʻchirish. 2026-yil oʻrtalariga kelib agentlar no trivial vazifalarni kuzatuvsiz tugata oldi, rejalashtirish primitivlari (`/loop`, `/goal`, cron) vositalarga oʻrnatildi va bitta ishga tushirish narxi taymerda takrorlashga arziydigan darajada pasaydi. Qismlar mavjud boʻlganda, ularni bir joyga ulash bir kishining fikri boʻlib qolmaydi.
> Manba: [Addy Osmani: Loop Engineering](https://addyosmani.com/blog/loop-engineering/)
@@ -267,7 +267,7 @@ flowchart TD
Bu endi bitta agent ishlash emas. Bu har ertalab uygʻonib, oʻzi yerni supurib, eʼtiboringizga chiqadigan narsalarni oldingizga qoʻyadigan doimiy ishlaydigan tizim. Sizning rolingiz quyidagicha boʻladi: **qutik tarkibini koʻrib chiqish, qarorlar qabul qilish va tizim qila olmaydigan naqshni koʻrganingizda, skill va qoidalarni takomillashtirish.**
-Cherny bu naqshni ishlatib, 30 kunda hech qachon IDE ochmasdan 259 PR ni merge qildi. OpenAI muhandislari xuddi shu naqshni ishlatib, qoʻlda million qatorda beta mahsulotini qurdilar — hech bir qator kodni oʻzlari yozmasdan.
+Chernyʼning 30 kunlik hisoboti bu naqshning bir maʼlumot nuqtasi: 259 ta PR, kod Claude Code + Opus 4.5 tomonidan yozilgan. OpenAIʼning [harness hisoboti](https://openai.com/index/harness-engineering/) — yana biri: kichik jamoa yangi repozitoriyda Codex bilan besh oy ishlab, taxminan bir million qator kod va 1 500 ga yaqin PR haqida xabar berdi.
## Generator/Evaluator boʻlinishi: Nega modelni oʻz ishlari baholashiga yoʻl qoʻymaslik kerak
@@ -293,7 +293,7 @@ Esda tutish uchun bir jumla: **ekipajingizda bir kishi sizga ishonmasligi kerak.
Agar siz yaxshi loyihalangan, haqiqatan ishlayotgan loop nima koʻrinishini koʻrmoqchi boʻlsangiz, [Karpathy autoresearch](https://github.com/karpathy/autoresearch) oʻquv qoʻllanma misolidir.
-2026-yil martida Karpathy 630 qatordan iborat Python loyihasini chiqardi. Bunga bitta GPU va tadqiqot yoʻnalishini bering, u tun boʻyi ishlaydi — yuzlab ML trening eksperimentlarini bajaradi, faqat haqiqatan yaxshilaydiganlarini saqlab turadi. Loyiha chiqqandan keyin bir necha kun ichida 66,000+ yulduzga erishdi.
+2026-yil martida Karpathy [autoresearch](https://github.com/karpathy/autoresearch) loyihasini chiqardi. Repozitoriy ataylab kichik qilib qurilgan: `prepare.py` — qatʼiy infratuzilma, `train.py` — agent tahrirlaydigan fayl (taxminan 630 qator), `program.md` — inson tahrirlaydigan tadqiqot metodologiyasi. Bunga bitta GPU va tadqiqot yoʻnalishini bering, u tun boʻyi ishlaydi — har bir eksperiment trening uchun 5 daqiqalik qatʼiy vaqt byudjeti oladi (ishga tushirish va kompilyatsiyadan tashqari) va faqat `val_bpb` ni yaxshilaydigan oʻzgarishlar saqlanadi.
### Uchta fayl, uchta rol
@@ -343,9 +343,9 @@ flowchart TD
8b --> 9
```
-U soatiga taxminan 12 ta eksperiment ishlatadi. Tunda ishlash (8 soat) taxminan 100 ta eksperiment. Karpathy oʻzi 2 kun davom ettirdi — ~700 ta eksperiment.
+README soatiga taxminan 12 ta eksperiment, yaʼni 8 soatlik tungi ishlashda taxminan 100 ta eksperiment deb baholaydi. 5 daqiqa faqat treningni qoplaydi, ishga tushirish va kompilyatsiyani emas; raundning qolgan qismi tahrirlash, ishga tushirish va baholashga ketadi. Karpathy quyida tasvirlangan nanochat raundi uchun xususiy versiyadagi autoresearchʼni taxminan ikki kun avtonom ishlatganini maʼlum qilgan.
-Sobiq 5-daqiqalik vaqt byudjeti muhim dizayn tanlovidir — agent nima oʻzgartirishi qatʼiy nazar, har bir eksperiment bir xil vaqtni oladi. Bu barcha natijalar bir xil vaqt byudjeti ostida bevosita solishtirilishi mumkinligini anglatadi — "buning ishlash vaqti uzoqroq, shuning uchun yaxshiroq" degan bahs yoʻq.
+Qatʼiy 5 daqiqalik trening byudjeti muhim dizayn tanlovidir — agent nima oʻzgartirishidan qatʼiy nazar, trening ishga tushirilishi bir xil vaqt byudjetini oladi. Bu barcha natijalar bir xil trening byudjeti ostida bevosita solishtirilishini anglatadi.
### Chiqish: Uyqudan uygʻonganda nima koʻrasiz
@@ -375,13 +375,9 @@ Agent nima sinaganini, nima ishlaganini, nima ishlamaganini va keyin nima sinash
### Haqiqatan nima topdi
-Karpathyʼning dastlabki 2 kunlik, ~700 eksperimentlik ishlashidan olingan natijalar:
+autoresearch [birinchi raund](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b) natijalari nanochatʼning GPT-2 darajasidagi trening vaqtini 8×H100 da [**2.02 soatdan 1.80 soatga**](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b) qisqartirdi — trening vaqtida taxminan **10,9%** kamayish.
-- ~700 ta urinish ichidan, taxminan **20 ta yonma-yon ishlaydigan haqiqiy yaxshilash** topildi
-- nanochatʼning GPT-2 darajasidagi trening vaqtini 8×H100 da **2.02 soat → 1.80 soat** ga qisqartirdi, taxminan **11% tezroq**
-- Topilmalar orasida: oʻrganish darajasi sozlamalari, optimizator sozlash, aktivatsiyani almashtirish, diqqat naqshlari optimallashtirish va boshqalar
-
-Barcha yaxshilanmalar yer sakraydigan kashfiyotlar edimi? Yoʻq. Koʻpchiligi yonma-yon ishlaydigan kichik optimallashtirishlar edi. Lekin bu 20 ta haqiqiy yaxshilash inson tadqiqotchisiga haftalar qoʻlda ish olib kelgan boʻlar edi — agent buni 48 soatda bajardi.
+Oʻzgarishlarning koʻpchiligi yonma-yon qoʻshiladigan kichik optimallashtirishlar edi. Foydali qismi — loopning oʻzi: qatʼiy byudjet, toʻliq eksperiment jurnali va faqat tasdiqlangan yaxshilanishlar qoladigan qoida.
### Eng koʻrsatuvchi batafsil: loop ingliz tilida yozilgan, kodda emas.
@@ -399,7 +395,7 @@ Tez loopʼlar sizni tekshirishni oʻtkazib yuborishga vasvasilaydi. "Yaxshi koʻ
### 2. Tushunish parchalanishi (Comprehension rot)
-Loop qancha tez code joʻnatsa, sizning oʻz kod bazangizni tushunishingiz haqiqatdan shunchalik uzoqlashadi. Chernyning jamoasida kodning 80% i agentlar tomonidan yozilgan — yaʼni jamoaning aksariyat kodi odam tomonidan yozilmagan. Agar siz loop ishlab chiqargan narsani oʻqmasangiz va ishlatmasangiz, tushunishingiz doimiy ravishda pasayadi. **Tez loopʼlar tez oʻqishni talab qiladi.**
+Loop qancha tez kod chiqarsa, sizning oʻz kod bazangizni tushunishingiz haqiqatdan shunchalik uzoqlashadi. Loop yuzlab PR chiqaradi; jamoa ularni oʻqiydi, muhim diffʼlarni koʻrib chiqadi va kodni ishlatishda davom etadi — shu bilan uning aqliy modeli kod bilan hamqadam boʻlib turadi. **Tez loopʼlar tez oʻqishni talab qiladi.**
### 3. Kognitiv taslim boʻlish (Cognitive surrender)
@@ -407,11 +403,11 @@ Loop silliq ishlaganda, eng qulay holat — fikr bildirishni bas qilishdir. U qa
### 4. Token portlashi (Token blowout)
-Loop ning har bir iteratsiyasi koʻproq kontekst toʻplaydi: yozilgan kod, duch kelgan xatolar, qabul qilingan qarorlar. Kontekst boshqaruvisiz, prompt kattaligi turnlar soniga taxminan kvadratik oʻsadi. Codex buni avtomatik kontekst siqish bilan hal qiladi — maxsus API eski suhbat burilishlarini shifrlangan mazmuni xulosalarga siqib, kerakli bilimni saqlab, ortiqcha detallarni tashlaydi. Bu siz birinchi loopʼdan boshlab hal qilishingiz kerak boʻlgan muhandislik muammosi, keyinroq qoʻshiladigan narsa emas.
+Loop ning har bir iteratsiyasi koʻproq kontekst toʻplaydi: yozilgan kod, duch kelgan xatolar, qabul qilingan qarorlar. Har bir raund taxminan qatʼiy miqdorda yangi kontent qoʻshsa, bitta raund koʻradigan tarix uzunligi raundlar soniga taxminan chiziqli oʻsadi. Agar tizim har raundda butun tarixni qayta ishlasa, N raund boʻyicha jami kirish hajmi taxminan kvadratik oʻsadi. Codex buni avtomatik kontekst siqish bilan hal qiladi — maxsus API eski suhbat burilishlarini shifrlangan mazmuni xulosalarga siqib, kerakli bilimni saqlab, ortiqcha detallarni tashlaydi. Bu siz birinchi loopʼdan boshlab hal qilishingiz kerak boʻlgan muhandislik muammosi, keyinroq qoʻshiladigan narsa emas.
## Birinchi loopʼingizni qurish
-Siz Stripe miqyosidagi pipeline haftasiga 1300 PR merge qilishdan boshlashingiz shart emas. Ishlaydigan eng kichik narsadan boshlang.
+Siz yuqori oʻtkazuvchanlikdagi (high-throughput) pipeline qurishdan boshlashingiz shart emas. Ishlaydigan eng kichik narsadan boshlang.
### 1-qadam: Bir takrorlanuvchi vazifani tanlang
diff --git a/docs/uz/lectures/lecture-14-graph-engineering/index.md b/docs/uz/lectures/lecture-14-graph-engineering/index.md
index a915d77..821e726 100644
--- a/docs/uz/lectures/lecture-14-graph-engineering/index.md
+++ b/docs/uz/lectures/lecture-14-graph-engineering/index.md
@@ -9,7 +9,7 @@ Oʻtgan maʼruzadagi Loop Engineering tugaganidan olti hafta oʻtib, 2026-yil 18
> "Biz hali ham Loop haqida gapiryapmizmi, yoki allaqachon Graphʼga oʻtib boʻldikmi?"
-Bitta tvit bir kunda taxminan 570 ming koʻrish, oy oxiriga kelib esa taxminan 3 million koʻrish oldi. Bir necha soatdan soʻng, mashina oʻqitish boʻyicha muhandis Hamel Husain "Loop Engineering Is Dead. Enter Graph Engineering" nomli maqola chop etdi — matnida faqat "Stop it" yozuvi tushirilgan GIF bor edi — va u ham taxminan 680 ming koʻrish oldi.
+Bitta tvit. Bir necha soatdan soʻng, mashina oʻqitish boʻyicha muhandis Hamel Husain "Loop Engineering Is Dead. Enter Graph Engineering" nomli maqola chop etdi — matnida faqat "Stop it" yozuvi tushirilgan GIF bor edi.
Eng qiziq tomoni: **ikkalasi ham buni hazil sifatida yozgan edi.** Biri sanoat har olti haftada yangi atama ixtiro qilishini masxara qilayotgan edi, ikkinchisi esa shu memʼni davom ettirib, hazillashib javob berayotgan edi. Ammo hazil faqat taxminan bir dam olish kunigacha yashadi — oʻquv kurslari, yoʻl xaritalari va vositalar toʻplami hafta oxirigacha feedʼni toʻldirib tashladi, bir toʻda uydirma raqamlar bilan: "aniqlik +18%, xarajat −85%" — bu soxta maʼlumot (18% va 85% haqiqatan mavjud, lekin ular kimyo quvurlari sxemalari haqidagi ilmiy maqoladan olingan va taqqoslash bazisi butunlay boshqacha), "Microsoft, Stanford va Anthropic bir vaqtda grafik muhandisligini kashf etdi" degani ham yolgʻon xabar. Fakt-tekshiruv tasdiqlagan yagona "kashfiyotchi" — Josh Simmons: uning "We Are Entering the Graph Engineering Phase" maqolasi 4-iyulda yozilgan, bu hazildan roppa-rosa ikki hafta oldin — **hazil bu narsani mashhur qildi, lekin bu narsani yaratgan emas.**
@@ -257,11 +257,11 @@ Ishga tushirgach, yuqoridagi grafik bilan solishtiring: qoʻlda yozgan `graph.md
## Ochiq manbali loyihalar: eʼlondan keyin paydo boʻlganlar va eʼlondan oldin mavjud boʻlganlar
-Avval chegarani aniq belgilaylik: **Graph Engineering — 2026-yil 18-iyuldan keyin paydo boʻlgan nom.** Undan oldin ochiq manbali boʻlgan freymvorklar "Graph Engineering eʼlondan keyingi loyihalar" emas. Kontsepsiya portlab ketgandan keyin, toʻgʻridan-toʻgʻri shu nom bilan paydo boʻlgan ochiq manbali loyihalar, 2026-yil avgust boshi holatiga koʻra, faqat bittasi tan olinadi:
+Avval chegarani aniq belgilaylik: **Graph Engineering — 2026-yil 18-iyuldan keyin paydo boʻlgan nom.** Undan oldin ochiq manbali boʻlgan freymvorklar "Graph Engineering eʼlondan keyingi loyihalar" emas. GraphARC nomini bevosita ishlatadigan bitta loyiha bor:
-**Kontsepsiya eʼlonidan keyin paydo boʻlganlar**
+**Eʼlondan keyingi loyihalar (aslida Graph Engineering deb ataladigan yagona loyiha)**
-- [GraphArc](https://github.com/CodeGraphContext/grapharc) (2026-08-02): oʻzini "Graph Engineeringʼning birinchi real vaqt implementatsiyasi" deb ataydi. U agent bajarilishini logʼlarga koʻmilgan traceʼdan **interaktiv real vaqt orkestratsiya grafigiga** aylantiradi — har bir agent, har bir bogʻliqlik, har bir qaror nuqtasi chiziladi, bajarilishdan oldin butun grafik vizualizatsiya qilinadi, siz tasdiqlaganingizdan (hatto telefonda koʻrib) keyin ruxsat beriladi. Muallifning tajribasi — 4000+ ishlab chiquvchi uchun grafik vositalari yaratish, yoʻnalish — "kuzatiladigan, tuzatiladigan, muhandislashtiriladigan". Juda yangi, funksiyalari hali erta bosqichda.
+- [GraphARC](https://github.com/CodeGraphContext/GraphARC) (2026-yil iyulda yaratilgan): oʻzini "an end to end implementation of Graph Engineering as proposed by Andrew NG and Peter Steinberger" deb taʼriflaydi. Bu erta bosqichdagi Python loyihasi. Foydali yoʻl — uning orkestratsiya modelini oʻqib chiqish va bu yondashuv sizning ish oqimingizga mos keladimi-yoʻqmi, shuni hal qilish.
**Kontsepsiya eʼlonidan oldin mavjud boʻlganlar (ular Graph Engineering deb atalmaydi, lekin siz qurishda aynan ularni ishlatasiz)**
@@ -325,7 +325,7 @@ Barcha vazifalar grafik chizishga arzimaydi. Beshta mezon, kamida uchtasi bajari
- [goddaehee: Graph Engineering fakt-tekshiruvi (koreyscha, 2026-07-30)](https://goddaehee.tistory.com/628) — eng toʻliq fakt-tekshiruv: hazil kelib chiqishi xronologiyasi, soxta raqamlar tahlili, LangGraph maʼlumotlari, Hacker News qiziqish taqqoslash
- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — oʻsha hazildan ikki hafta oldin yozilgan jiddiy maqola
- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — rasmiy javob: "yangi gʻoya emas, mavjud yondashuvning eng yangi nomi"; LangGraph oylik 65 million+ yuklab olish
-- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — hot atama tarqalish maʼlumotlari (birinchi tvit 575 ming koʻrish)
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — bu atama qanday tarqalgani haqidagi hikoya
- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — yettita asosiy ochiq manbali freymvorkning yonma-yon taqqoslash: LangGraph, CrewAI, Microsoft Agent Framework, LlamaIndex, Google ADK, OpenAI Agents SDK, Mastra
- [LangGraph rasmiy hujjatlari](https://docs.langchain.com/oss/python/langgraph/graph-api) — "Nodes do the work, edges tell what to do next"; tugun va chekkaning aniq taʼrifi, grafik qurish uchun birinchi qoʻl maʼlumotnoma
- [Anthropic: Building Effective Agents (Dec 2024)](https://www.anthropic.com/engineering/building-effective-agents) — besh naqsh, chizilganda grafik boʻladi; workflow vs agentʼning nufuzli farqi
diff --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.md
index 6a70fe3..c05a359 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
@@ -5,13 +5,13 @@
# Bài 01. Mô hình mạnh không có nghĩa là thực thi đáng tin cậy
-Tính đến cuối năm 2025, các coding agent mạnh nhất trên SWE-bench Verified đạt tỷ lệ vượt qua khoảng 50-60%. Nghe thì có vẻ khá, nhưng đừng vội ăn mừng. Đó là những tác vụ được lựa chọn cẩn thận với mô tả vấn đề rõ ràng và bộ test có sẵn. Đưa cho agent yêu cầu thực tế hàng ngày của bạn: đặc tả mơ hồ, không có test, quy tắc nghiệp vụ ẩn rải rác trong codebase, thì tỷ lệ vượt qua chỉ giảm thêm nữa. Bạn hào hứng giao một tác vụ, agent chạy 20 phút rồi báo "xong rồi", và bạn nhìn vào code: nó thêm một tính năng nhưng làm hỏng test, sửa một lỗi nhưng sinh ra lỗi mới, và kết quả cuối cùng còn không đúng thứ bạn yêu cầu.
+Ngày 29 tháng 9 năm 2025, Anthropic công bố Claude Sonnet 4.5 đạt [77,2% trên SWE-bench Verified](https://www.anthropic.com/news/claude-sonnet-4-5). Con số đó nghe có vẻ khá, nhưng đừng vội ăn mừng. Đó là những tác vụ được lựa chọn cẩn thận với mô tả vấn đề rõ ràng và bộ test có sẵn. Đưa cho agent yêu cầu thực tế hàng ngày của bạn: đặc tả mơ hồ, không có test, quy tắc nghiệp vụ ẩn rải rác trong codebase, thì tỷ lệ vượt qua chỉ giảm thêm nữa. Bạn hào hứng giao một tác vụ, agent chạy 20 phút rồi báo "xong rồi", và bạn nhìn vào code: nó thêm một tính năng nhưng làm hỏng test, sửa một lỗi nhưng sinh ra lỗi mới, và kết quả cuối cùng còn không đúng thứ bạn yêu cầu.
Khi chuyện này xảy ra, phản ứng đầu tiên của hầu hết mọi người là "mô hình chưa đủ tốt, thử sang cái đắt tiền hơn xem sao". Trước khi mở ví, hãy cân nhắc: vấn đề có thể hoàn toàn không nằm ở mô hình.
## Cùng con ngựa, số phận khác nhau
-Anthropic đã thực hiện một thí nghiệm có kiểm soát minh họa chính xác điểm này. 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), hai lần chạy. 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 không hoạt động. Lần chạy thứ hai: harness đầy đủ, kiến trúc ba agent gồm planner, generator, evaluator, 6 giờ, $200, trò chơi có thể chơi được hoàn toàn.
+Anthropic đã so sánh cùng một prompt ("xây dựng một trình tạo trò chơi retro 2D") và cùng một mô hình (Opus 4.5) dưới hai harness. Lần chạy đầu tiên: trần trụi, không có hỗ trợ, 20 phút, $9; ứng dụng mở được, nhưng các thực thể không phản hồi với input. Lần chạy thứ hai: harness đầy đủ, kiến trúc ba agent gồm planner, generator, evaluator, 6 giờ, $200; có thể di chuyển một thực thể, nhưng vật lý còn thô và một bức tường chặn đường đi. [Gameplay cốt lõi chạy được; ứng dụng vẫn chưa hoàn thành.](https://www.anthropic.com/engineering/harness-design-long-running-apps)
Họ không thay đổi mô hình. Opus 4.5 vẫn là Opus 4.5. Thứ thay đổi là bộ yên cương.
@@ -31,9 +31,9 @@ Các chế độ thất bại cụ thể thực ra chỉ gói gọn trong vài
Với các tình huống trên, những khái niệm này không còn chỉ là thuật ngữ suông:
-- **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 benchmark và hiệu suất trên tác vụ thực tế. Tỷ lệ 50-60% trên SWE-bench Verified có nghĩa là gần một nửa vấn đề thực tế không được giải quyết.
+- **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 benchmark và hiệu suất trên tác vụ thực tế. Các tác vụ benchmark đi kèm mô tả vấn đề rõ ràng, test và môi trường; tác vụ thực tế thường buộc bạn phải tự cung cấp những thứ đó.
- **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. Không phải trọng số mô hình, thì đó là harness. Chính là thứ chúng ta vẫn 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.
+- **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. So sánh trò chơi retro ở trên là một ví dụ.
- **Khoảng cách Xác minh (Verification Gap)**: Khoảng cách giữa sự tự tin của agent về kết quả đầu ra và tính đúng đắn thực tế. Agent nói "tôi đã xong" khi chưa xong, đây là chế độ thất bạ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.
- **Định nghĩa Hoàn thành (Definition of Done)**: Một tập các điều kiện có thể xác minh bằng lệnh: test vượt qua, lint sạch, type check vượt qua. Không có định nghĩa hoàn thành rõ ràng, agent sẽ tự bịa ra định nghĩa của riêng nó.
@@ -60,7 +60,7 @@ Từ đó, xây dựng vòng lặp chẩn đoán. Đừng xem lỗi là "mô hì
## Thí nghiệm triệu dòng code
-Vào năm 2025, ba kỹ sư tại OpenAI bắt đầu một thí nghiệm. Quy tắc đơn giản: chính họ không viết code, chỉ Codex viết. Bắt đầu từ một kho git trống, năm tháng sau kho chứa khoảng một triệu dòng code. Logic ứng dụng, hạ tầng, công cụ, tài liệu, tất cả đều do agent tạo. Ba kỹ sư mở tổng cộng 1.500 PR, trung bình 3.5 PR mỗi người mỗi ngày.
+Vào tháng 8 năm 2025, ba kỹ sư tại OpenAI bắt đầu một thí nghiệm. Quy tắc đơn giản: chính họ không viết code, chỉ Codex viết. Bắt đầu từ một kho git trống, năm tháng sau [kho chứa khoảng một triệu dòng code](https://openai.com/index/harness-engineering/). Logic ứng dụng, hạ tầng, công cụ, tài liệu, tất cả đều do agent tạo. Nhóm sau đó phát triển lên bảy kỹ sư; trong cả giai đoạn đã hợp nhất khoảng 1.500 PR, trung bình 3,5 PR mỗi kỹ sư mỗi ngày.
Tiến độ ban đầu chậm hơn dự kiến một cách đáng ngạc nhiên. Codex không tệ, nó chỉ thiếu các công cụ và cấu trúc đủ hoàn chỉnh để hướng đến mục tiêu cấp cao. Ba kỹ sư dần tìm ra quy luật: chia nhỏ mục tiêu lớn thành các khối xây dựng nhỏ, thiết kế, code, review, test, để agent lắp ráp từng khối một, rồi dùng các khối đó để tổng hợp các tác vụ phức tạp hơn. Mỗi khi có trục trặc, vấn đề hầu như không bao giờ là "cố gắng chưa đủ", mà luôn là "agent còn thiếu năng lực gì, và thiếu năng lực đó có thể được cung cấp theo cách vừa dễ hiểu vừa có thể thực thi không".
@@ -72,9 +72,9 @@ Thí nghiệm này chứng minh trực tiếp luận điểm cốt lõi của b
Một nhóm dùng Claude Sonnet để thêm API endpoint mới vào một ứng dụng web Python cỡ trung (FastAPI + PostgreSQL + Redis, khoảng 15.000 dòng code).
-Ban đầu họ chỉ đưa ra một câu: "thêm endpoint tùy chọn người dùng dưới `/api/v2/users`". Kết quả? Agent dành 40% cửa sổ ngữ cảnh để khám phá cấu trúc repo, tạo ra code trông có vẻ hợp lý nhưng không theo mẫu xử lý lỗi của dự án, dùng cú pháp SQLAlchemy cũ, và tuyên bố hoàn thành trong khi endpoint vẫn có lỗi runtime. Phiên tiếp theo phải làm lại toàn bộ phần khám phá.
+Ban đầu họ chỉ đưa ra một câu: "thêm endpoint tùy chọn người dùng dưới `/api/v2/users`". Kết quả? Agent dành phần lớn phiên để khám phá cấu trúc repo, tạo ra code trông có vẻ hợp lý nhưng không theo mẫu xử lý lỗi của dự án, dùng cú pháp SQLAlchemy cũ, và tuyên bố hoàn thành trong khi endpoint vẫn có lỗi runtime. Phiên tiếp theo phải làm lại toàn bộ phần khám phá.
-Sau đó họ bổ sung `AGENTS.md` (mô tả kiến trúc dự án và phiên bản tech stack), các lệnh xác minh rõ ràng (`pytest tests/api/v2/ && python -m mypy src/`), và các bản ghi quyết định kiến trúc. Cùng một mô hình thành công trong cả ba lần chạy độc lập, với hiệu quả ngữ cảnh tốt hơn khoảng 60%.
+Sau đó họ bổ sung `AGENTS.md` (mô tả kiến trúc dự án và phiên bản tech stack), các lệnh xác minh rõ ràng (`pytest tests/api/v2/ && python -m mypy src/`), và các bản ghi quyết định kiến trúc. Cùng một mô hình sau đó đã tuân theo quy ước của dự án và kiểm tra công việc bằng các lệnh nó có thể chạy.
Họ không thay đổi mô hình. Họ thay đổi harness.
diff --git a/docs/vi/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/vi/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
index 7627dc8..a52945a 100644
--- a/docs/vi/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
+++ b/docs/vi/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -52,7 +52,7 @@ flowchart LR
- **Cửa sổ ngữ cảnh là hữu hạn**: Dù kích thước cửa sổ được quảng bá là bao nhiêu (128K, 200K, 1M), tác vụ dài rồi cũng sẽ cạn kiệt. Sau khi cạn, chỉ có hai lối: nén (mất thông tin) hoặc reset (mở phiên mới), cả hai đều mất thứ gì đó.
- **Tệp lưu trữ trạng thái (State persistence files)**: Các tệp trạng thái được lưu lại, để phiên mới có thể tiếp tục rõ ràng ngay từ chỗ phiên trước dừng lại. Dạng cơ bản nhất gồm nhật ký tiến độ, bản ghi xác minh và các bước kế tiếp.
-- **Chi phí tái thiết lập (Rebuild cost)**: Thời gian phiên mới cần để đạt tới trạng thái có thể thực thi. Một harness tốt có thể nén chi phí này từ 15 phút xuống còn 3 phút.
+- **Chi phí tái thiết lập (Rebuild cost)**: Thời gian phiên mới cần để đạt tới trạng thái có thể thực thi. Một harness tốt để lại tiến độ, kết quả xác minh và các bước kế tiếp trong tệp, để phiên mới bắt đầu từ một trạng thái đã được viết ra.
- **Trôi dạt (Drift)**: Khoảng cách giữa hiểu biết của agent và trạng thái thật của kho lưu trữ code. Mỗi ranh giới phiên lại tạo ra trôi dạt; không kiểm soát, nó sẽ tích tụ qua từng phiên.
- **Lo lắng ngữ cảnh (Context anxiety)**: Hiện tượng Anthropic quan sát thấy: agent thể hiện hành vi vội vàng kết thúc khi ngữ cảnh gần tới giới hạn, kết thúc tác vụ sớm để tránh mất thông tin. Bản chất là sự lo lắng tài nguyên vô lý.
- **Nén so với đặt lại (Compaction vs. reset)**: Nén tóm tắt ngữ cảnh trong cùng phiên (giữ "cái gì", có thể mất "vì sao"); đặt lại mở phiên mới, tái thiết lập từ trạng thái đã lưu (sạch sẽ nhưng phụ thuộc vào độ đầy đủ của các artifact).
@@ -160,7 +160,7 @@ LangChain báo cáo điểm tăng từ 52,8% lên 66,5%, tức 13,7 điểm ph
- Cửa sổ ngữ cảnh là tài nguyên hữu hạn. Tác vụ dài sẽ trải qua nhiều phiên, và các phiên sẽ mất thông tin, đó là thực tế khách quan.
- Giải pháp không phải cửa sổ lớn hơn, mà là lưu trữ trạng thái tốt hơn. Tệp tiến độ, nhật ký quyết định và git checkpoint phối hợp với nhau, để phiên mới nối tiếp phiên cũ.
- Hãy đối xử với agent như một kỹ sư bị xóa trắng bộ nhớ ngắn hạn mỗi phiên: trước khi "tan ca", phải ghi lại đã làm gì, vì sao, và bước tiếp theo là gì.
-- Chi phí tái thiết lập là chỉ số then chốt. Một harness tốt cần đưa phiên mới vào trạng thái có thể thực thi trong vòng 3 phút.
+- Chi phí tái thiết lập là chỉ số then chốt. Một harness tốt để lại tiến độ, kết quả xác minh và các bước kế tiếp trong tệp, để phiên mới phục hồi nhanh chóng.
- Chiến lược hỗn hợp: tác vụ ngắn xử lý trong phiên, tác vụ dài dùng artifact có cấu trúc để duy trì tính liên tục.
## Đọc thêm
diff --git a/docs/vi/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/vi/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
index 3971e6c..8c4a063 100644
--- a/docs/vi/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
+++ b/docs/vi/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -37,7 +37,7 @@ flowchart TB
## Chuyện gì xảy ra khi bạn trộn chúng
-Vấn đề trực tiếp nhất: hạ tầng không được xây cho ra hồn. Agent dành 80% sức cho code tính năng, 20% còn lại tiện tay dựng đại vài thứ cho hạ tầng. Khung test cấu hình xong nhưng chưa bao giờ được xác minh, quy tắc lint đặt ra nhưng quá lỏng, không có tệp tiến độ nào được tạo. Những khiếm khuyết ấy không lộ ra ở phiên đầu (vì agent vẫn còn nhớ mình đã làm gì), nhưng bùng lên ở phiên thứ hai: agent mới không biết cách chạy dự án, không biết test ở đâu, không biết mọi thứ đang tới đâu.
+Vấn đề trực tiếp nhất: hạ tầng không được xây cho ra hồn. Agent dành phần lớn sức cho code tính năng và chỉ tiện tay dựng đại hạ tầng như một việc phụ. Khung test cấu hình xong nhưng chưa bao giờ được xác minh, quy tắc lint đặt ra nhưng quá lỏng, không có tệp tiến độ nào được tạo. Những khiếm khuyết ấy không lộ ra ở phiên đầu (vì agent vẫn còn nhớ mình đã làm gì), nhưng bùng lên ở phiên thứ hai: agent mới không biết cách chạy dự án, không biết test ở đâu, không biết mọi thứ đang tới đâu.
Một chi phí ẩn hơn là "tích tụ chưa xác minh". Code tính năng viết trước khi khung test được cấu hình chuẩn, bản thân nó là code không có xác minh. Khi bạn quay lại thêm test, có khi phát hiện ra ngay từ đầu thiết kế đã sai, nếu biết trước, bạn đã triển khai khác đi. Code viết trước càng nhiều, phần phải đập đi làm lại càng lớn.
@@ -45,7 +45,7 @@ Ngân sách ngữ cảnh cũng đang bị lãng phí. Phần việc khởi tạo
Vấn đề dễ bị bỏ qua nhất là bãi mìn giả định ngầm. Những quyết định agent đưa ra trong lúc khởi tạo (dùng khung test nào, tổ chức thư mục ra sao, quản lý dependency thế nào) nếu không ghi lại tường minh, các phiên sau có thể đưa ra lựa chọn mâu thuẫn. Phiên đầu chọn Vitest làm khung test, phiên sau agent không biết, lại đưa Jest vào. Hai khung test cùng tồn tại, chi phí bảo trì nhân đôi.
-Nghiên cứu về phát triển ứng dụng chạy lâu của Anthropic đặc biệt khuyến nghị tách khởi tạo khỏi triển khai. Dữ liệu thực nghiệm của họ: các dự án có giai đoạn khởi tạo riêng biệt đạt tỷ lệ hoàn thành tính năng cao hơn 31% trong kịch bản đa phiên, so với cách trộn lẫn. Thời gian đầu tư cho khởi tạo được thu hồi hoàn toàn trong 3-4 phiên kế tiếp.
+Công trình về long-running agent của Anthropic [đặt khởi tạo vào một phiên đầu tiên riêng biệt](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents). Initializer viết script `init.sh`, tệp tiến độ, danh sách tính năng và commit Git đầu tiên; các phiên code sau đọc trạng thái đó, làm từng tính năng một, test đầu-cuối, commit và cập nhật tệp tiến độ.
Hướng dẫn harness engineering cho Codex của OpenAI cũng nhấn mạnh nguyên tắc "kho lưu trữ là bản ghi hoạt động": thiết lập cấu trúc vận hành rõ ràng ngay từ lần chạy đầu tiên, nếu không mỗi phiên mới sẽ phải tự suy ra quy ước dự án.
diff --git a/docs/vi/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/vi/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
index 26b6e7b..054b0f6 100644
--- a/docs/vi/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
+++ b/docs/vi/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -26,7 +26,7 @@ Hành vi thật của Claude Code rất minh họa. Bảo nó "thêm đăng ký
Sáu bước sau, mỗi cái đều làm dở. Không có xác minh end-to-end, code nửa vời cộng lẫn vào nhau rất phức tạp, phiên sau muốn dọn cũng chẳng biết bắt đầu từ đâu.
-Dữ liệu thực nghiệm của Anthropic hỗ trợ trực tiếp điều này: agent sử dụng chiến lược "bước tiếp theo nhỏ" (tương đương WIP=1) đạt tỷ lệ hoàn thành tác vụ cao hơn 37% so với agent nhận prompt rộng. Thú vị hơn, số dòng code agent tạo ra có tương quan âm yếu với tỷ lệ hoàn thành tính năng thực tế, viết nhiều code hơn, hoàn thành ít tính năng hơn. Câu "ăn vội nuốt tươi" được dữ liệu xác nhận.
+Hướng dẫn về long-running agent của Anthropic [yêu cầu coding agent làm từng tính năng một](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), sau đó xác minh, commit và cập nhật tiến độ trước khi chuyển sang việc tiếp theo. Một prompt rộng mời gọi agent mở nhiều luồng cùng lúc, và mỗi luồng lại tranh nhau cùng một ngân sách ngữ cảnh và xác minh.
## Quy trình WIP=1
diff --git a/docs/vi/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/vi/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
index 8cefbe9..aaa8c59 100644
--- a/docs/vi/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
+++ b/docs/vi/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -25,7 +25,7 @@ Nhìn mẫu ghi chú tiến độ quen thuộc này:
Một phiên agent mới đọc ghi chú này thì trả lời được gì? "Hầu như xong" nghĩa là gì? Giỏ hàng đã pass test nào? Cái gì đang chặn thanh toán? Câu trả lời cho tất cả: "không ai biết". Cũng giống như bảo bác sĩ "bụng tôi đau, dạo này có vẻ ổn hơn", bác sĩ biết kê đơn thuốc nào đây?
-Hệ quả: phiên mới tốn 20 phút để dò ra trạng thái dự án, và có khi lại triển khai lại những tính năng đã hoàn thành. Dữ liệu kỹ thuật của Anthropic cho thấy bản ghi tiến độ tốt giảm thời gian chẩn đoán lúc khởi động phiên từ 60% đến 80%.
+Hệ quả: phiên mới phải dò ra trạng thái dự án, và có khi lại triển khai lại những tính năng đã hoàn thành. Lời khuyên của Anthropic là [ghi tiến độ và kết quả xác minh vào các tệp được quản lý phiên bản](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), để phiên tiếp theo có thể kiểm tra trạng thái.
## Máy trạng thái tính năng
@@ -116,7 +116,7 @@ Một nền tảng thương mại điện tử với 10 tính năng. Hai cách t
**Chế độ có cấu trúc**: Mỗi tính năng có trạng thái và lệnh xác minh rõ ràng. Phiên mới đọc feature list và trong 3 phút đã biết: F01-F05 đang `passing`, F06 đang `active` (đang triển khai), F07-F10 đang `not_started`. Nối tiếp thẳng vào F06, không có phần việc nào phải làm lại.
-Kết quả định lượng: các dự án dùng feature list có cấu trúc đạt tỷ lệ hoàn thành tính năng cao hơn 45% so với theo dõi tự do, và số lần triển khai trùng lặp bằng 0.
+Một danh sách có cấu trúc đặt trạng thái và lệnh xác minh của từng tính năng vào một chỗ, nên phiên mới biết cái gì đã xong.
## Những điểm chính cần nhớ
diff --git a/docs/vi/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/vi/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
index 77d2207..4889626 100644
--- a/docs/vi/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
+++ b/docs/vi/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -68,7 +68,7 @@ Một agent đánh giá độc lập, được tinh chỉnh để cố tình "k
| Kiến trúc | Thời gian chạy | Chi phí | Tính năng cốt lõi chạy được không? |
|--------------|---------|------|------------------------|
| Một agent (chạy trần) | 20 phút | $9 | Không (các thực thể trong trò chơi không phản hồi input) |
-| Ba agent (planner + generator + evaluator) | 6 giờ | $200 | Có (trò chơi chơi được hoàn toàn) |
+| Ba agent (planner + generator + evaluator) | 6 giờ | $200 | Gameplay cốt lõi chạy được; vật lý và màn chơi vẫn còn vấn đề |
Đây là cùng một mô hình (Opus 4.5) với cùng một prompt ("xây dựng trình tạo trò chơi retro 2D"). Điểm khác biệt duy nhất nằm ở harness: từ "chạy trần" sang "planner mở rộng yêu cầu, generator triển khai từng tính năng, evaluator thực sự bấm thử bằng Playwright".
@@ -117,7 +117,7 @@ Các tín hiệu runtime hiệu quả gồm:
**Những điểm bị bỏ sót thật sự**: (1) Luồng end-to-end chưa từng được kiểm tra, việc gửi và xác minh thật sự liên kết đặt lại chưa bao giờ được xác nhận. (2) Migration cơ sở dữ liệu lỗi sau khi thực thi một phần, để lại schema không nhất quán. (3) Cấu hình dịch vụ email bị thiếu trong môi trường đích.
-**Harness can thiệp**: Xác nhận kết thúc được thực thi, (1) khởi động toàn bộ ứng dụng để xác minh endpoint đặt lại truy cập được; (2) chạy toàn bộ luồng đặt lại; (3) xác minh tính nhất quán trạng thái cơ sở dữ liệu. Mọi khiếm khuyết đều được phát hiện trong phiên, tiết kiệm chi phí sửa sau gấp 5-10 lần.
+**Harness can thiệp**: Xác nhận kết thúc được thực thi, (1) khởi động toàn bộ ứng dụng để xác minh endpoint đặt lại truy cập được; (2) chạy toàn bộ luồng đặt lại; (3) xác minh tính nhất quán trạng thái cơ sở dữ liệu. Cả ba khiếm khuyết đều lộ ra ngay trong phiên, khi chi phí sửa vẫn còn cục bộ.
## Những điểm chính cần nhớ
diff --git a/docs/vi/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/vi/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
index 8fa069b..8544165 100644
--- a/docs/vi/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
+++ b/docs/vi/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -130,7 +130,7 @@ Mỗi lần phát hiện một loại lỗi agent mới trong code review, hãy
| Vấn đề quyền | Quyền khác nhau trong môi trường đã đóng gói | Bỏ sót | Bắt được |
| Lan truyền lỗi | Ngoại lệ lớp service không đến được lớp UI | Bỏ sót | Bắt được |
-Cả 5 khiếm khuyết đều bị end-to-end test bắt, unit test không bắt được cái nào. Đánh đổi là thời gian test tăng từ 2 giây lên 15 giây, hoàn toàn chấp nhận được trong quy trình làm việc với agent.
+Cả 5 khiếm khuyết đều bị end-to-end test bắt, unit test không bắt được cái nào. Chạy end-to-end chậm hơn, nhưng chi phí đó nhỏ so với việc đưa năm khiếm khuyết biên ra bản phát hành.
## Những điểm chính cần nhớ
diff --git a/docs/vi/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/vi/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
index 9e0ceed..b35f11f 100644
--- a/docs/vi/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
+++ b/docs/vi/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -21,7 +21,7 @@ Khi harness thiếu khả năng quan sát, bốn nhóm vấn đề sẽ xuất h
**Thử lại trở thành đoán mù.** Khi agent không biết vì sao một việc fail, hướng thử lại hoàn toàn ngẫu nhiên. Nó có khi sửa mãi những đường đi không liên quan, bỏ qua tận gốc nguyên nhân thật. Mỗi lần thử lại mù quáng đốt cả token lẫn thời gian.
-**Vực thông tin lúc bàn giao phiên.** Khi phần việc chưa xong được chuyển cho phiên sau, thiếu khả năng quan sát đồng nghĩa với việc phiên mới phải chẩn đoán lại trạng thái hệ thống từ đầu. Quan sát của Anthropic về các long-running agent cho thấy khâu chẩn đoán trùng lặp này có thể nuốt tới 30-50% tổng thời gian phiên.
+**Vực thông tin lúc bàn giao phiên.** Khi phần việc chưa xong được chuyển cho phiên sau, thiếu khả năng quan sát đồng nghĩa với việc phiên mới phải chẩn đoán lại trạng thái hệ thống từ đầu. Phiên mới phải đọc lại code, chạy lại lệnh và quyết định tín hiệu nào quan trọng; [bản ghi tiến độ và xác minh được quản lý phiên bản](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) cung cấp trạng thái có thể kiểm tra.
## Một kịch bản Claude Code thật
@@ -31,7 +31,7 @@ Hãy hình dung một harness dùng quy trình ba vai "planner-generator-evaluat
**Có đầy đủ khả năng quan sát:** Planner đưa ra sprint contract, liệt kê component nào cần sửa, tiêu chuẩn xác minh cho từng cái, và các ngoại lệ (ví dụ không xử lý print styles). Generator triển khai theo contract, và khả năng quan sát runtime ghi lại quá trình tải style của từng component. Evaluator dùng rubric chấm điểm để đánh giá từng chiều, kèm bằng chứng cụ thể: "Độ tương phản màu nút chưa đạt (chuẩn WCAG AA 4.5:1, đo được 2.1:1)". Một vòng lặp cho ra kết quả chất lượng cao, trong khoảng 15 phút.
-Hiệu quả chênh nhau 3 lần. Biến duy nhất là khả năng quan sát.
+Sự khác biệt đến từ việc hợp đồng và bằng chứng có tồn tại bên ngoài đầu agent hay không.
## Quan sát phân lớp
@@ -122,7 +122,7 @@ Tạo một trace cho mỗi phiên harness, một span cho mỗi tác vụ, và
## Thí nghiệm kiến trúc ba agent của Anthropic
-Tháng 3 năm 2026, Anthropic công bố một thí nghiệm harness có hệ thống. Họ chạy cùng một tác vụ ("xây dựng một DAW trên trình duyệt dùng Web Audio API") với ba kiến trúc khác nhau và ghi lại dữ liệu chi tiết theo từng pha:
+Báo cáo tháng 3 năm 2026 của Anthropic đưa ra [dữ liệu chạy DAW cập nhật của cùng kiến trúc ba agent](https://www.anthropic.com/engineering/harness-design-long-running-apps) ("xây dựng một DAW trên trình duyệt dùng Web Audio API"). Bản đầu tiên, xây cho Opus 4.5, dùng generator làm việc theo sprint và evaluator chấm từng sprint. Bản cập nhật, chạy trên Opus 4.6, bỏ cấu trúc sprint: builder làm việc liên tục, evaluator xem xét sau mỗi vòng build. Bảng dưới đây là dữ liệu của bản cập nhật:
| Agent và pha | Thời lượng | Chi phí |
|---------------|----------|------|
@@ -135,7 +135,7 @@ Tháng 3 năm 2026, Anthropic công bố một thí nghiệm harness có hệ th
| QA vòng 3 | 9.6 phút | $4.06 |
| **Tổng** | **3 giờ 50 phút** | **$124.70** |
-Mỗi agent trong ba đó giữ vai trò riêng, và mỗi vai đều đóng góp rõ ràng vào khả năng quan sát:
+Mỗi vai đóng một phần rõ ràng vào khả năng quan sát. Các mô tả vai dưới đây ứng với bản đầu tiên; bản cập nhật bỏ lớp sprint của generator:
**Planner:** Nhận yêu cầu người dùng từ 1-4 câu rồi mở rộng thành product spec đầy đủ. Nó được nhắc "mạnh dạn về phạm vi" và "tập trung vào ngữ cảnh sản phẩm và thiết kế kỹ thuật cấp cao thay vì chi tiết triển khai". Lý do: nếu planner sớm chốt chi tiết kỹ thuật nhỏ mà sai, lỗi ấy sẽ lan xuống các bước sau. Cách tốt hơn là ràng buộc sản phẩm đầu ra, để agent tự tìm đường đi trong lúc thực thi.
@@ -155,7 +155,7 @@ Evaluator không phải lúc nào cũng bén nhạy như vậy. Phiên bản đ
- **Cả hai lớp quan sát đều cần thiết.** Tín hiệu runtime giải thích "chuyện gì đã xảy ra", artifact quá trình giải thích "vì sao lại làm thế này".
- **Sprint contract đẩy việc căn chỉnh lên đầu.** Chúng ngăn generator xây thứ mà evaluator sẽ lập tức từ chối vì lý do có thể dự đoán trước.
- **Rubric chấm điểm làm đánh giá có thể tái lập.** Evaluator khác nhau cho điểm tương tự với cùng một đầu ra.
-- **Thiếu khả năng quan sát phí phạm 30-50% thời gian phiên cho khâu chẩn đoán trùng lặp.**
+- **Khả năng quan sát biến một lời từ chối mơ hồ thành một khiếm khuyết cụ thể, có thể sửa.**
## Đọc thêm
diff --git a/docs/vi/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/vi/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
index ab37ee6..029f64d 100644
--- a/docs/vi/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
+++ b/docs/vi/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -15,7 +15,7 @@ Các định luật tiến hoá phần mềm của Lehman cho thấy hệ thốn
Trong năm tháng thí nghiệm Codex, OpenAI quan sát thấy một điều đáng chú ý: **agent sao chép các pattern đang có trong kho lưu trữ, ngay cả khi những pattern ấy không nhất quán hoặc chưa tối ưu.** Lâu dần, việc sao chép này tất yếu dẫn đến trôi dạt. Người đầu tiên để lại một cái cốc cà phê ở khu vực chung; người thứ hai thấy "chỗ này đã lộn xộn rồi" và cũng để thêm một cái; một tuần sau, cả mặt bàn chìm trong cốc. Một codebase cũng vận hành y hệt thế.
-Đội ngũ OpenAI ban đầu dành 20% thời gian mỗi thứ Sáu để dọn thủ công "rác do AI", nhưng cách này rõ ràng không mở rộng được. Cuối cùng họ đi đến một giải pháp có hệ thống:
+Đội ngũ OpenAI ban đầu dành thứ Sáu, [một ngày làm việc, khoảng 20% năng lực của tuần](https://openai.com/index/harness-engineering/), để dọn thủ công "rác do AI". Khi thông lượng tăng lên, chi phí dọn thủ công vượt quá lợi ích thu về. Cuối cùng họ đi đến một giải pháp có hệ thống:
1. **Mã hoá "quy tắc vàng" vào kho lưu trữ**: Các quy tắc kiểu "ưu tiên dùng package tiện ích dùng chung thay vì helper tự chế tay" (giữ bất biến ở một nơi) và "đừng đoán mò cấu trúc dữ liệu" (xác minh ranh giới hoặc dựa vào SDK có kiểu). Những quy tắc này cụ thể, cơ học và kiểm tra được tự động.
2. **Thiết lập quy trình dọn dẹp định kỳ**: Một đội các task Codex nền thường xuyên quét tìm sai lệch, cập nhật điểm chất lượng, mở PR tái cấu trúc có mục tiêu. Phần lớn có thể review và auto-merge trong vòng một phút.
@@ -43,7 +43,7 @@ flowchart LR
Fix --> Build
```
-Nhưng thế vẫn chưa đủ. Tiến độ hiện tại phải được ghi vào artifact máy đọc được: các subtask đã hoàn thành kèm tiêu chí pass, các subtask đang làm dở kèm trạng thái hiện tại, các subtask chưa bắt đầu. Bản ghi tiến độ tốt giảm thời gian chẩn đoán lúc khởi động phiên từ 60-80%. Artifact tạm (debug log, tệp tạm, code bị comment out, marker TODO) cũng phải được dọn, vì chúng tăng tải nhận thức cho phiên sau. Đường khởi động chuẩn phải còn chạy được. Phiên sau có thể bắt đầu làm việc mà không cần can thiệp thủ công không? Khởi tạo môi trường, tải codebase, thu thập ngữ cảnh, chọn tác vụ, không đường nào được hỏng cả.
+Nhưng thế vẫn chưa đủ. Tiến độ hiện tại phải được ghi vào artifact máy đọc được: các subtask đã hoàn thành kèm tiêu chí pass, các subtask đang làm dở kèm trạng thái hiện tại, các subtask chưa bắt đầu. Ghi tiến độ và kết quả xác minh vào các tệp được quản lý phiên bản để phiên sau có thể kiểm tra trạng thái. Artifact tạm (debug log, tệp tạm, code bị comment out, marker TODO) cũng phải được dọn, vì chúng tăng tải nhận thức cho phiên sau. Đường khởi động chuẩn phải còn chạy được. Phiên sau có thể bắt đầu làm việc mà không cần can thiệp thủ công không? Khởi tạo môi trường, tải codebase, thu thập ngữ cảnh, chọn tác vụ, không đường nào được hỏng cả.
```mermaid
flowchart LR
@@ -72,7 +72,7 @@ Cái bẫy tâm lý phổ biến nhất là "phiên này không có thời gian
Tệ hơn, mỗi phiên có mục tiêu tác vụ riêng. Phiên mới vào để làm việc mới, không phải dọn mớ hỗn độn của phiên trước. Nó sẽ phớt lờ sự lộn xộn rồi xây tiếp lên trên, lại đẻ thêm hỗn loạn. Đó chính là vòng phản hồi dương của entropy.
-Con số kể lại tất cả. Một dự án phát triển bằng agent trong 12 tuần, không có chiến lược dọn dẹp:
+Với một dự án 12 tuần giả định, hãy giả sử các giá trị sau:
- Tuần 1: build pass 100%, test pass 100%, khởi động phiên mới 5 phút
- Tuần 4: build 95%, test 92%, khởi động 15 phút
@@ -84,7 +84,7 @@ Cùng dự án nhưng có chiến lược dọn dẹp:
- Tuần 1: 100%, 100%, 5 phút
- Tuần 12: 97%, 95%, 9 phút
-Sau 12 tuần: tỷ lệ build pass chênh 29 điểm phần trăm, thời gian khởi động phiên mới chênh 85%. Đây không phải lý thuyết, đây là khác biệt được quan sát.
+Một vòng dọn hàng tuần giữ trạng thái xuất phát ổn định: mỗi phiên kết thúc với build, test, tiến độ và artifact tạm đều ngăn nắp, để phiên sau bắt đầu từ cùng một đường cơ sở.
## Cách làm đúng
@@ -137,7 +137,7 @@ Phiên mới đọc tài liệu này là biết ngay ưu tiên ở đâu. Sửa
Mỗi thành phần harness tồn tại vì mô hình chưa thể tự làm việc đó một cách đáng tin. Nhưng khi mô hình mạnh lên, những giả định ấy trở nên lỗi thời.
-Thí nghiệm của Anthropic chứng minh trực tiếp điều này. Harness ban đầu của họ có cơ chế chia sprint, chia việc thành từng khúc nhỏ để Sonnet 4.5 làm từng khúc một. Khi Opus 4.6 ra mắt, năng lực của mô hình đã tự phân rã công việc được, việc dựng sprint trở thành overhead thừa. Gỡ bỏ xong, agent builder làm việc liên tục hơn hai tiếng không trôi dạt, và còn trôi chảy hơn.
+Báo cáo harness của Anthropic cho thấy trực tiếp điều này. Harness ba agent đầu tiên, xây cho Opus 4.5, có generator làm việc theo sprint. Khi [Opus 4.6](https://www.anthropic.com/engineering/harness-design-long-running-apps) ra mắt, mô hình đã tự phân rã được công việc, nên cấu trúc sprint trở thành thứ thừa. Trong lần chạy DAW cập nhật, builder làm việc liên tục hơn hai tiếng mà không trôi dạt.
Nhưng câu chuyện ở evaluator lại khác. Kể cả với Opus 4.6 mạnh hơn, khi tác vụ tiệm cận biên năng lực mô hình, evaluator vẫn mang lại giá trị thật, bắt được các tính năng thiếu và stub của generator. Điều này nghĩa là evaluator không phải quyết định có/không cố định, nó phụ thuộc vào vị trí độ khó tác vụ so với năng lực mô hình.
@@ -170,7 +170,7 @@ Một ứng dụng Electron phát triển bằng agent trong 12 tuần, so sánh
**Có chiến lược dọn dẹp** (nhóm thực nghiệm): Kiểm tra trạng thái sạch đầy đủ cuối mỗi phiên, cộng với vòng dọn hàng tuần. Tuần 12, build pass 97%, test pass 95%, khởi động phiên mới 9 phút, 11 artifact cũ.
-Đến tuần 12, nhóm thực nghiệm có build pass cao hơn 29 điểm phần trăm, test pass cao hơn 34 điểm, và thời gian khởi động phiên mới thấp hơn 85%. Mỗi phiên chỉ tốn thêm 5 phút dọn dẹp, nhưng suốt 12 tuần nó tiết kiệm được hàng chục giờ hỗn loạn.
+Đến tuần 12, nhóm có dọn dẹp giữ tỷ lệ build và test pass gần với điểm xuất phát, phiên mới có thể bắt đầu nhanh, và artifact cũ còn rất ít. Dọn dẹp tốn vài phút mỗi phiên và trả lại một trạng thái xuất phát mà phiên sau có thể tin tưởng.
## Những điểm chính cần nhớ
diff --git a/docs/vi/lectures/lecture-13-loop-engineering/index.md b/docs/vi/lectures/lecture-13-loop-engineering/index.md
index 19b214e..c1a03f7 100644
--- a/docs/vi/lectures/lecture-13-loop-engineering/index.md
+++ b/docs/vi/lectures/lecture-13-loop-engineering/index.md
@@ -84,11 +84,11 @@ Loop Engineering, chủ đề của bài giảng này, không phải về một
Bạn không cần phải gõ `/goal` mỗi lần. Nhưng hiểu nó đến từ đâu và tại sao nó trông như thế nào — đó là hiểu cốt lõi của loop engineering. Các vòng lặp phức tạp hơn chỉ thêm các phần như lập lịch, song song, cô lập, và bộ nhớ lên trên ba nguyên tắc cơ bản giống nhau: mục tiêu, xác minh, điều kiện dừng.
-## Tháng Sáu 2026: Ba Người Đốt Cùng Một Que Diêm Trong Một Tuần
+## Những Ngày Khác Nhau, Cùng Một Hướng
-Trong tuần đầu tiên của tháng 6 năm 2026, ba người thực hành xây dựng cơ sở hạ tầng agent coding — mà không so sánh ghi chú — đã nói cùng một điều bằng những lời khác nhau.
+Cùng một ý tưởng xuất hiện ở những nơi khác nhau, vào những thời điểm khác nhau.
-**Peter Steinberger** (người tạo ra OpenClaw, [bài đăng của ông đạt 8 triệu lượt xem](https://x.com/steipete/status/2063697162748260627)): "Bạn không nên còn đang nhắc lệnh các agent coding nữa. Bạn nên thiết kế các vòng lặp nhắc lệnh agent của bạn."
+**Peter Steinberger** (người tạo ra OpenClaw, [trong một bài đăng](https://x.com/steipete/status/2063697162748260627)): "Bạn không nên còn đang nhắc lệnh các agent coding nữa. Bạn nên thiết kế các vòng lặp nhắc lệnh agent của bạn."
**Boris Cherny** (trưởng phòng Claude Code tại Anthropic, [trên podcast Acquired](https://x.com/rohanpaul_ai/status/2063289804708835412)): "Tôi không còn nhắc lệnh Claude nữa. Tôi có các vòng lặp chạy nhắc lệnh Claude và tìm ra phải làm gì. Công việc của tôi là viết các vòng lặp."
@@ -96,9 +96,9 @@ Trong tuần đầu tiên của tháng 6 năm 2026, ba người thực hành xâ
> **Loop engineering là thay thế bản thân bạn với tư cách là người nhắc lệnh agent. Bạn thiết kế hệ thống làm việc đó thay thế.**
-Cherny tiết lộ con số: trong hơn 30 ngày liên tiếp, tất cả các đóng góp code cho Claude Code đều được thực hiện tự chủ bởi AI — 259 PR đã được merge, hơn 80% code sản xuất được viết bởi Claude, và tỷ lệ thành công 76% đối với các nhiệm vụ phần mềm mở.
+Cherny viết trong một [báo cáo cá nhân ngày 27-12-2025](https://twitter.com/bcherny/status/2004887829252317325) rằng trong hơn 30 ngày anh đã merge 259 PR — 497 commit, thêm 40.000 dòng, xóa 38.000 dòng — và mọi dòng đều do Claude Code + Opus 4.5 viết.
-Ba người. Một tuần. Cùng một kết luận. Không phải vì họ phối hợp — mà vì cơ sở hạ tầng đã lặng lẽ vượt qua một ngưỡng. Các agent đã trở nên đủ tin cậy để hoàn thành các nhiệm vụ không tầm thường mà không cần giám sát. Các nguyên thủy lập lịch (`/loop`, `/goal`, cron) giờ đã được tích hợp sẵn trong các công cụ. Chi phí của một lần chạy agent đã giảm đủ thấp để việc chạy một cách lặp đi lặp lại theo bộ hẹn giờ trông không còn lãng phí. Khi tất cả các bộ phận đều có mặt, bước di chuyển kết hợp chúng trở nên hiển nhiên với mọi người cùng một lúc.
+Những câu trích dẫn đến từ các ngày, định dạng và đội ngũ khác nhau. Hướng đi chung của họ là đưa việc lập lịch, xác minh và quyết định dừng ra khỏi prompt thời điểm và vào trong một hệ thống. Đến giữa năm 2026, agent đã có thể hoàn thành các tác vụ không tầm thường mà không cần giám sát, các nguyên thủy lập lịch đã được tích hợp sẵn, và một lần chạy đã đủ rẻ để lặp lại theo bộ hẹn giờ. Khi các mảnh đã có mặt, không chỉ một người ghép chúng lại.
> Nguồn: [Addy Osmani: Loop Engineering](https://addyosmani.com/blog/loop-engineering/)
@@ -267,7 +267,7 @@ flowchart TD
Đây không còn là một lần chạy agent đơn lẻ nữa. Đó là một hệ thống vận hành liên tục thức dậy mỗi buổi sáng, tự quét dọn sàn nhà, và đặt những thứ cần sự chú ý của bạn ra trước mặt bạn. Vai trò của bạn trở thành: **review nội dung hộp thư, đưa ra quyết định, và khi bạn phát hiện một mẫu hệ thống không thể xử lý, tinh chỉnh các kỹ năng và quy tắc.**
-Cherny đã sử dụng mẫu này để merge 259 PR trong 30 ngày mà không cần mở IDE một lần nào. Các kỹ sư OpenAI đã sử dụng cùng một mẫu để xây dựng một sản phẩm beta khoảng một triệu dòng mã bằng tay — mà không cần tự viết một dòng mã nào.
+Báo cáo 30 ngày của Cherny là một điểm dữ liệu cho mẫu này: 259 PR, với code do Claude Code + Opus 4.5 viết. [Bản ghi harness của OpenAI](https://openai.com/index/harness-engineering/) là một điểm khác: một đội nhỏ dùng Codex trên một kho lưu trữ hoàn toàn mới trong năm tháng và báo cáo khoảng một triệu dòng cùng khoảng 1.500 PR.
## Phân tách Generator/Evaluator: Tại sao Bạn Không thể Để Mô hình Chấm Điểm Công việc của Chính Mình
@@ -293,7 +293,7 @@ Một câu để nhớ: **ai đó trong đội của bạn phải không tin b
Nếu bạn muốn xem một vòng lặp được thiết kế tốt, thực sự đang chạy trông như thế nào, [autoresearch của Karpathy](https://github.com/karpathy/autoresearch) là ví dụ sách giáo khoa.
-Vào tháng 3 năm 2026, Karpathy phát hành một dự án Python 630 dòng. Đưa cho nó một GPU và một hướng nghiên cứu, và nó chạy cả đêm — hoàn thành hàng trăm thí nghiệm huấn luyện ML, chỉ giữ lại những cái thực sự cải thiện. Dự án đạt 66.000+ sao trong vài ngày sau khi phát hành.
+Vào tháng 3 năm 2026, Karpathy phát hành [autoresearch](https://github.com/karpathy/autoresearch). Kho lưu trữ được cố ý làm nhỏ: `prepare.py` là hạ tầng cố định, `train.py` là tệp agent sửa (khoảng 630 dòng), và `program.md` là phương pháp luận nghiên cứu do người sửa. Đưa cho nó một GPU và một hướng nghiên cứu, và nó chạy qua đêm — mỗi thí nghiệm có ngân sách thời gian thực huấn luyện cố định 5 phút (không tính khởi động và biên dịch), và chỉ những thay đổi cải thiện `val_bpb` mới được giữ lại.
### Ba Tệp, Ba Vai trò
@@ -343,9 +343,9 @@ flowchart TD
8b --> 9
```
-Nó chạy khoảng 12 thí nghiệm mỗi giờ. Một lần chạy qua đêm (8 giờ) là khoảng 100 thí nghiệm. Bản thân Karpathy đã chạy nó trong 2 ngày — ~700 thí nghiệm.
+README ước tính khoảng 12 thí nghiệm mỗi giờ, tức khoảng 100 trong một lần chạy qua đêm 8 giờ. Ngân sách 5 phút chỉ bao gồm huấn luyện, không tính khởi động hay biên dịch; phần còn lại của mỗi vòng dành cho sửa, chạy và đánh giá. Karpathy báo cáo đã tự chủ chạy một phiên bản riêng của autoresearch trong khoảng hai ngày cho vòng nanochat dưới đây.
-Ngân sách thời gian thực 5 phút cố định là một lựa chọn thiết kế quan trọng — bất kể agent thay đổi gì, mọi thí nghiệm đều mất đúng cùng một thời gian. Điều này có nghĩa là tất cả các kết quả đều có thể so sánh trực tiếp dưới cùng một ngân sách thời gian — không có tranh cãi về "cái này chạy lâu hơn nên nó tốt hơn."
+Ngân sách huấn luyện 5 phút cố định là một lựa chọn thiết kế quan trọng — bất kể agent thay đổi gì, lần chạy huấn luyện nhận cùng một ngân sách thời gian thực. Điều này có nghĩa là tất cả các kết quả đều có thể so sánh trực tiếp dưới cùng một ngân sách huấn luyện.
### Đầu ra: Bạn Nhìn Thấy Gì Khi Thức Dậy
@@ -375,13 +375,9 @@ Agent viết các thông điệp commit rõ ràng về những gì nó đã th
### Nó Thực sự Tìm Thấy Gì
-Kết quả từ lần chạy 2 ngày, ~700 thí nghiệm ban đầu của Karpathy:
+Kết quả từ [vòng 1](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b) của autoresearch đã giảm thời gian huấn luyện GPT-2 của nanochat trên 8×H100 [từ **2,02 giờ xuống 1,80 giờ**](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b), tức giảm khoảng **10,9%** thời gian huấn luyện.
-- Trong khoảng ~700 lần thử, đã tìm thấy khoảng **20 cải thiện thực sự có thể xếp chồng lên nhau**
-- Giảm thời gian huấn luyện cấp GPT-2 của nanochat trên 8×H100 từ **2,02 giờ → 1,80 giờ**, nhanh hơn khoảng **11%**
-- Các phát hiện bao gồm: điều chỉnh learning rate, tinh chỉnh optimizer, hoán đổi hàm kích hoạt, tối ưu hóa mẫu attention, v.v.
-
-Tất cả các cải thiện có phải là những khám phá làm chấn động địa cầu không? Không. Hầu hết là các tối ưu nhỏ xếp chồng lên nhau. Nhưng 20 cải thiện hợp lệ đó sẽ mất một nhà nghiên cứu con người hàng tuần công việc thủ công — agent đã làm nó trong 48 giờ.
+Hầu hết các thay đổi là những tối ưu nhỏ xếp chồng lên nhau. Phần hữu ích là vòng lặp: ngân sách cố định, nhật ký thí nghiệm đầy đủ, và quy tắc chỉ giữ lại những cải thiện đã được xác minh.
### Chi tiết Nói lên Nhiều Nhất: Vòng lặp được Viết Bằng Tiếng Anh, Không Phải Code.
@@ -399,7 +395,7 @@ Các vòng lặp nhanh cám dỗ bạn bỏ qua xác minh. "Trông ổn" không
### 2. Sự thối rữa Hiểu biết
-Vòng lặp giao code càng nhanh, sự hiểu biết của bạn về chính codebase của bạn càng trôi dạt xa khỏi thực tế. Đội của Cherny có 80% code được viết bởi agent — có nghĩa là hầu hết code của một đội không được viết bởi một con người. Nếu bạn không đọc và sử dụng những gì vòng lặp tạo ra, sự hiểu biết của bạn liên tục suy thoái. **Các vòng lặp nhanh đòi hỏi đọc nhanh.**
+Vòng lặp giao code càng nhanh, sự hiểu biết của bạn về chính codebase của bạn càng trôi dạt xa khỏi thực tế. Một vòng lặp merge hàng trăm PR; đội đọc những PR đó, review những diff quan trọng, và tiếp tục dùng chính code ấy, nên mô hình tinh thần của họ bắt kịp. **Các vòng lặp nhanh đòi hỏi đọc nhanh.**
### 3. Sự đầu hàng Nhận thức
@@ -407,11 +403,11 @@ Khi vòng lặp chạy trơn tru, tư thế thoải mái nhất là ngừng có
### 4. Bùng nổ Token
-Mỗi lần lặp của một vòng lặp tích lũy thêm ngữ cảnh: code đã viết, lỗi đã gặp, quyết định đã đưa ra. Nếu không có quản lý ngữ cảnh, kích thước prompt tăng khoảng bậc hai theo số lượt. Codex giải quyết vấn đề này với nén ngữ cảnh tự động — một API chuyên dụng nén các lượt cuộc trò chuyện cũ thành các tóm tắt nội dung được mã hóa, giữ lại kiến thức thiết yếu trong khi loại bỏ chi tiết dư thừa. Đây là một mối quan tâm kỹ thuật bạn phải giải quyết từ vòng lặp đầu tiên, không phải thêm vào sau này.
+Mỗi lần lặp của một vòng lặp tích lũy thêm ngữ cảnh: code đã viết, lỗi đã gặp, quyết định đã đưa ra. Khi mỗi vòng chỉ thêm một lượng nội dung mới gần như cố định, độ dài lịch sử mà một vòng đơn lẻ nhìn thấy tăng gần như tuyến tính theo số vòng. Nếu hệ thống xử lý lại toàn bộ lịch sử mỗi vòng, tổng đầu vào tích lũy qua N vòng tăng gần như bậc hai. Codex giải quyết vấn đề này với nén ngữ cảnh tự động — một API chuyên dụng nén các lượt cuộc trò chuyện cũ thành các tóm tắt nội dung được mã hóa, giữ lại kiến thức thiết yếu trong khi loại bỏ chi tiết dư thừa. Đây là một mối quan tâm kỹ thuật bạn phải giải quyết từ vòng lặp đầu tiên, không phải thêm vào sau này.
## Xây dựng Vòng lặp Đầu tiên của Bạn
-Bạn không cần bắt đầu với một đường ống quy mô Stripe merge 1.300 PR một tuần. Bắt đầu với thứ nhỏ nhất hoạt động được.
+Bạn không cần bắt đầu với một pipeline thông lượng cao. Hãy bắt đầu với thứ nhỏ nhất hoạt động được.
### Bước 1: Chọn Một Nhiệm vụ Lặp lại
diff --git a/docs/vi/lectures/lecture-14-graph-engineering/index.md b/docs/vi/lectures/lecture-14-graph-engineering/index.md
index ec4cb78..781c273 100644
--- a/docs/vi/lectures/lecture-14-graph-engineering/index.md
+++ b/docs/vi/lectures/lecture-14-graph-engineering/index.md
@@ -9,7 +9,7 @@ Sáu tuần sau khi Bài giảng trước vừa giới thiệu xong Loop Enginee
> "Chúng ta vẫn đang nói về Loop, hay đã chuyển sang Graph rồi?"
-Một dòng tweet, trong một ngày đã đạt khoảng 575 nghìn lượt xem, đến cuối tháng tăng lên khoảng 3 triệu. Vài giờ sau, kỹ sư máy học Hamel Husain đăng một bài viết nhan đề *Loop Engineering Is Dead. Enter Graph Engineering* — toàn bộ nội dung chỉ là một ảnh động ghi chữ "Stop it" — và nhận thêm khoảng 680 nghìn lượt xem.
+Một dòng tweet. Vài giờ sau, kỹ sư máy học Hamel Husain đăng một bài viết nhan đề *Loop Engineering Is Dead. Enter Graph Engineering* — toàn bộ nội dung chỉ là một ảnh động ghi chữ "Stop it".
Điều đáng suy ngẫm hơn: **cả hai người đều đăng như một trò đùa.** Một người châm biếm một ngành công nghiệp cứ sáu tuần lại phát minh ra một thuật ngữ mới, người kia thuận theo meme đó để phụ họa. Nhưng trò đùa chỉ sống được khoảng một cuối tuần — các khóa học, lộ trình, bộ công cụ đã phủ kín dòng thời gian trước khi cuối tuần kết thúc, kèm theo một loạt con số bịa đặt: "độ chính xác +18%, chi phí −85%" là dữ liệu giả (18% và 85% thực sự tồn tại, nhưng đến từ một bài báo về bản vẽ đường ống hóa chất, và so với các đường cơ sở hoàn toàn khác nhau), "Microsoft, Stanford, Anthropic đồng thời phát hiện ra kỹ thuật đồ thị" cũng là tin giả. Việc kiểm chứng dữ kiện chỉ xác nhận đúng một "người tiên phong": Josh Simmons — bài *We Are Entering the Graph Engineering Phase* của ông viết vào ngày 4 tháng 7, sớm hơn trò đùa này đúng hai tuần — **chính trò đùa đã khiến sự việc trở nên phổ biến, chứ không phải trò đùa tạo ra sự việc.**
@@ -257,11 +257,11 @@ Chạy xong đối chiếu với đồ thị phía trên: `graph.md` bạn viế
## Dự án mã nguồn mở: thứ chỉ có sau khi phát hành, thứ đã có trước khi phát hành
-Trước tiên vạch rõ ranh giới: **Graph Engineering là cái tên chỉ tồn tại sau ngày 18 tháng 7 năm 2026.** Các framework mã nguồn mở trước ngày đó đều không phải "dự án sau khi phát hành Graph Engineering". Kể đến đầu tháng 8 năm 2026, các dự án mã nguồn mở thực sự xuất hiện trực tiếp với cái tên này sau khi khái niệm bùng nổ, mới chỉ có một dự án đứng vững:
+Trước tiên vạch rõ ranh giới: **Graph Engineering là cái tên chỉ tồn tại sau ngày 18 tháng 7 năm 2026.** Các framework mã nguồn mở trước ngày đó đều không phải "dự án sau khi phát hành Graph Engineering". Một dự án sử dụng tên này một cách tường minh là GraphARC:
**Thứ chỉ có sau khi khái niệm phát hành**
-- [GraphArc](https://github.com/CodeGraphContext/grapharc) (2026-08-02): tự xưng là "triển khai thời gian thực đầu tiên của Graph Engineering". Nó biến quá trình thực thi agent từ trace chôn trong log thành một **đồ thị điều phối thời gian thực tương tác** — mỗi agent, mỗi quan hệ phụ thuộc, mỗi điểm quyết định đều được vẽ ra, trực quan hóa toàn bộ đồ thị trước khi thực thi, bạn xác nhận (thậm chí có thể xem bằng điện thoại) rồi mới cho chạy. Tác giả có nền tảng làm công cụ đồ thị cho hơn 4000 nhà phát triển, định hướng là "quan sát được, gỡ lỗi được, kỹ thuật hóa được". Rất mới, tính năng còn ở giai đoạn đầu.
+- [GraphARC](https://github.com/CodeGraphContext/GraphARC) (tạo tháng 7 năm 2026): tự mô tả là "an end to end implementation of Graph Engineering as proposed by Andrew NG and Peter Steinberger". Đây là một dự án Python ở giai đoạn đầu. Việc hữu ích là đọc mô hình điều phối của nó và quyết định xem cách tiếp cận này có phù hợp với quy trình của bạn không.
**Thứ đã có trước khi khái niệm phát hành (chúng không gọi là Graph Engineering, nhưng chúng mới là thứ bạn dùng khi xây dựng)**
@@ -325,7 +325,7 @@ Không phải mọi nhiệm vụ đều đáng để vẽ đồ thị. Năm tiê
- [goddaehee: Kiểm chứng dữ kiện Graph Engineering (tiếng Hàn, 2026-07-30)](https://goddaehee.tistory.com/628) — kiểm chứng dữ kiện đầy đủ nhất: dòng thời gian nguồn gốc trò đùa, phân tích các con số giả, dữ liệu LangGraph, so sánh độ nóng Hacker News
- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — bài viết nghiêm túc đi trước trò đùa đó hai tuần
- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — phản hồi chính thức: "không phải ý tưởng mới, là cái tên mới nhất của một cách tiếp cận đã có"; LangGraph 65 triệu+ lượt tải mỗi tháng
-- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — dữ liệu lan truyền từ khóa nóng (575 nghìn lượt xem trên tweet đầu tiên)
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — một tường thuật về cách thuật ngữ lan truyền
- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — so sánh ngang bảy framework mã nguồn mở chủ lưu: LangGraph, CrewAI, Microsoft Agent Framework, LlamaIndex, Google ADK, OpenAI Agents SDK, Mastra
- [Tài liệu chính thức LangGraph](https://docs.langchain.com/oss/python/langgraph/graph-api) — "Nodes do the work, edges tell what to do next"; định nghĩa chính xác về nút và cạnh, nguồn tham khảo trực tiếp để xây dựng đồ thị
- [Anthropic: Building Effective Agents (Dec 2024)](https://www.anthropic.com/engineering/building-effective-agents) — năm mẫu hình, vẽ ra chính là đồ thị; phân biệt workflow vs agent có thẩm quyền
diff --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.md
index fe2b5b0..4b9a3b7 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
@@ -5,13 +5,13 @@
# 第一講. 模型能力強,不等於執行可靠
-截至 2025 年底,最強的 coding agent 在 SWE-bench Verified 上的通過率大約在 50-60%。這個數字乍看還行,但別急著慶祝。那都是精心挑選過的、有明確 issue 描述和現成測試用例的任務。換到你日常開發的場景,需求模糊、沒有現成測試、隱含的業務規則散落在各處,這個數字只會更低。你信心滿滿地交代任務,agent 跑了 20 分鐘告訴你「完成了」,你一看程式碼,加了功能但測試掛了,改了 bug 但引入了新 bug,根本不是你要的東西。
+2025 年 9 月 29 日,Anthropic 公布 Claude Sonnet 4.5 [在 SWE-bench Verified 上取得 77.2%](https://www.anthropic.com/news/claude-sonnet-4-5)。這個數字乍看還行,但別急著慶祝。那都是精心挑選過的、有明確 issue 描述和現成測試用例的任務。換到你日常開發的場景,需求模糊、沒有現成測試、隱含的業務規則散落在各處,這個數字只會更低。你信心滿滿地交代任務,agent 跑了 20 分鐘告訴你「完成了」,你一看程式碼,加了功能但測試掛了,改了 bug 但引入了新 bug,根本不是你要的東西。
遇到這種情況,大部分人的第一反應是「這模型不行,得換一個更貴的。」先別急著掏錢包。問題可能根本不在模型身上。
## 同一匹馬,兩種命運
-Anthropic 做過一個對照實驗。同一個 prompt(「做一個 2D 復古遊戲編輯器」),同一個模型(Opus 4.5)。第一次讓它裸跑,20 分鐘,花了 $9,遊戲核心功能根本跑不起來。第二次給它配上完整的 harness(planner + generator + evaluator 三 agent 架構),6 小時,花了 $200,遊戲可以正常遊玩。
+Anthropic 比較過同一個 prompt(「做一個 2D 復古遊戲編輯器」)、同一個模型(Opus 4.5)在兩種 harness 下的表現。第一次讓它裸跑,20 分鐘,花了 $9:應用能開啟,但實體對輸入沒有反應。第二次給它配上完整的 harness(planner + generator + evaluator 三 agent 架構),6 小時,花了 $200:能移動實體,但物理有粗糙之處,還有一面牆擋住去路。[核心玩法能跑,應用仍不完整](https://www.anthropic.com/engineering/harness-design-long-running-apps)。
模型沒換。Opus 4.5 還是那個 Opus 4.5。換的是馬具。
@@ -35,9 +35,9 @@ OpenAI 在 2025 年發佈的 harness engineering 文章裡說得更直接,Code
理解了上面的場景,這些概念就不再是一堆術語了:
-- **能力鴻溝(Capability Gap)**:模型在基準測試上的表現和真實任務上的表現之間的巨大落差。SWE-bench Verified 上 50-60% 的通過率意味著近一半的真實 issue 解不了。
+- **能力鴻溝(Capability Gap)**:模型在基準測試上的表現和真實任務上的表現之間的巨大落差。基準任務的 issue 描述、測試和環境是給定的;真實任務裡,這些往往要你自己補。
- **Harness**:模型之外的一切,包括指令、工具與環境,以及狀態管理和驗證機制。不是模型權重的部分,全是 harness。
-- **Harness 誘導失敗**:模型本身能力足夠,但因為執行環境有結構性缺陷而失敗。Anthropic 的對照實驗已經證明了這一點。
+- **Harness 誘導失敗**:模型本身能力足夠,但因為執行環境有結構性缺陷而失敗。上面的復古遊戲對比就是一個例子。
- **驗證缺口**:agent 對自己輸出的信心評估和實際正確性之間的偏差。agent 說「我做完了」但實際沒做完,這是最常見的失敗模式。
- **診斷循環**:執行 → 觀察失敗 → 定位到 harness 的哪一層出了問題 → 修補那一層 → 重新執行。這是 harness 工程的核心方法論。
- **完成定義(Definition of Done)**:一組可以用命令驗證的條件,測試通過、lint 沒報錯、類型檢查通過。沒有顯式的完成定義,agent 就會自己編一個。
@@ -68,7 +68,7 @@ OpenAI 在 2025 年發佈的 harness engineering 文章裡說得更直接,Code
## 一百萬行程式碼的實驗
-OpenAI 在 2025 年做了一個激進的實驗,用 Codex 從一個空的 git 儲存庫起步,建構一個完整的內部產品。五個月後,這個儲存庫有大約 100 萬行程式碼,應用邏輯、基礎設施、工具、文件、內部開發工具,全部由 agent 生成。三個工程師驅動 Codex,開了大約 1,500 個 PR 並完成合併。平均每人每天 3.5 個 PR。
+2025 年 8 月,OpenAI 的三個工程師用 Codex 從一個空的 git 儲存庫起步,建構一個完整的內部產品。[五個月後,這個儲存庫有大約 100 萬行程式碼](https://openai.com/index/harness-engineering/),應用邏輯、基礎設施、工具、文件、內部開發工具,全部由 agent 生成。團隊後來擴展到七個工程師,一共合併了大約 1,500 個 PR,平均每人每天 3.5 個 PR。
這個實驗的關鍵約束,是**人類永遠不直接寫程式碼。** 這個設定是為了逼團隊搞清楚,當工程師的主要工作不再是寫程式碼,而是設計環境、表達意圖、建構回饋迴路時,到底什麼變了?
@@ -82,9 +82,9 @@ OpenAI 在 2025 年做了一個激進的實驗,用 Codex 從一個空的 git
一個團隊用 Claude Sonnet 給一個中等規模的 Python Web 應用(FastAPI + PostgreSQL + Redis,約 15,000 行程式碼)添加新的 API 端點。
-起初他們只給了一句話:「在 `/api/v2/users` 下添加使用者偏好設置端點」。結果呢?agent 花了 40% 的脈絡視窗探索儲存庫結構,產出了看似合理的程式碼但沒遵循專案的錯誤處理模式,用了舊版 SQLAlchemy 語法,宣稱完成但端點實際有執行時期錯誤。下一個工作階段還得重新做發現工作。
+起初他們只給了一句話:「在 `/api/v2/users` 下添加使用者偏好設置端點」。結果呢?agent 把大量時間花在探索儲存庫結構上,產出了看似合理的程式碼但沒遵循專案的錯誤處理模式,用了舊版 SQLAlchemy 語法,宣稱完成但端點實際有執行時期錯誤。下一個工作階段還得重新做發現工作。
-後來他們加了 `AGENTS.md`(描述專案架構和技術堆疊版本)、顯式的驗證命令(`pytest tests/api/v2/ && python -m mypy src/`)、和架構決策記錄。同一模型在三次獨立執行中全部成功,脈絡使用效率提高了約 60%。
+後來他們加了 `AGENTS.md`(描述專案架構和技術堆疊版本)、顯式的驗證命令(`pytest tests/api/v2/ && python -m mypy src/`)、和架構決策記錄。同一個模型開始遵循專案約定,並用能執行的命令檢查工作。
模型沒變。變的還是 harness。
diff --git a/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
index fe124c9..50e3b40 100644
--- a/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
+++ b/docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -50,7 +50,7 @@ flowchart LR
- **脈絡視窗是有限的**:不管模型吹多大的視窗(128K、200K、1M),長任務總會用完。用完之後要麼壓縮(丟資訊),要麼重置(開新工作階段)。兩種方式都會丟東西。
- **連續性工件**:持久化的狀態檔案,讓新工作階段能無歧義地恢復到上次離開的地方。最基本的形式:進度日誌 + 驗證記錄 + 下一步行動。
-- **重建成本**:新工作階段恢復到可執行狀態所需的時間。好的 harness 能把重建成本從 15 分鐘壓到 3 分鐘。
+- **重建成本**:新工作階段恢復到可執行狀態所需的時間。好的 harness 會把進度、驗證結果和下一步寫進檔案,讓新工作階段從寫下來的狀態開始。
- **漂移(Drift)**:agent 的理解跟程式碼儲存庫實際狀態之間的偏差。每次工作階段邊界都會引入漂移,不加控制會越漂越遠。
- **脈絡焦慮**:Anthropic 觀察到的現象,agent 在接近脈絡限制時表現異常,過早結束任務以避免資訊遺失。是一種非理性的資源焦慮。
- **壓縮 vs 重置**:壓縮是在同一個工作階段裡把脈絡摘要化(保留「是什麼」,可能丟了「為什麼」);重置是開新工作階段從持久化狀態重建(乾淨但依賴工件完備性)。
@@ -158,7 +158,7 @@ LangChain 報告了一組真實的 harness 改進結果:固定使用 gpt-5.2-c
- 脈絡視窗是有限的資源。長任務一定會跨工作階段,跨工作階段一定會丟資訊,這是客觀現實。
- 解決方案在於更好的狀態持久化,而非更大的視窗。進度檔案 + 決策日誌 + git 檢查點,讓每個工作階段都能從可靠的記錄起步。
- 把 agent 當成會失憶的工程師來管理:每次「下班」前寫清楚做了什麼、為什麼、下一步做什麼。
-- 重建成本是關鍵指標。好的 harness 應該讓新工作階段在 3 分鐘內恢復到可執行狀態。
+- 重建成本是關鍵指標。好的 harness 會把進度、驗證結果和下一步寫進檔案,讓新工作階段快速恢復。
- 混合策略:短任務在工作階段內完成,長任務用結構化工件維持連續性。
## 延伸閱讀
diff --git a/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
index c60ec87..dd6d8c8 100644
--- a/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
+++ b/docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -37,7 +37,7 @@ flowchart TB
## 混在一起做會怎樣
-最直接的問題:基礎設施不紮實。Agent 花了 80% 的精力寫功能程式碼,剩下 20% 隨便搭了點基礎設施。測試框架配了但沒驗證過,lint 規則設了但太寬鬆,進度檔案沒建立。這些缺陷在第一個工作階段裡不明顯(因為 agent 還記得它做了什麼),但到第二個工作階段就暴露了,新 agent 不知道專案怎麼跑、怎麼測、做到哪了。
+最直接的問題:基礎設施不紮實。Agent 把大部分精力花在功能程式碼上,基礎設施只是順手搭一點。測試框架配了但沒驗證過,lint 規則設了但太寬鬆,進度檔案沒建立。這些缺陷在第一個工作階段裡不明顯(因為 agent 還記得它做了什麼),但到第二個工作階段就暴露了,新 agent 不知道專案怎麼跑、怎麼測、做到哪了。
更隱蔽的代價是「未驗證的累積」,在測試框架配好之前寫的功能程式碼,等回頭補測試的時候可能發現設計上就有問題,早知道的話應該用不同的方式實作。等回頭補測試時才發現設計有問題,要重構才能讓測試通過。
@@ -45,7 +45,7 @@ flowchart TB
最容易被忽略的是隱式假設埋下的雷。Agent 在初始化過程中做的決策(用什麼測試框架、目錄怎麼組織、依賴怎麼管理)如果不顯式記錄下來,後續工作階段就可能做出矛盾的選擇。
-Anthropic 在他們的長執行應用開發研究中明確建議把初始化和實作分離。他們的實驗資料顯示,使用獨立初始化階段的專案,多工作階段場景中的功能完成率比混合方式高 31%。關鍵是,初始化階段投入的時間在後續 3-4 個工作階段中就能完全收回。
+Anthropic 的長執行 agent 工作[把初始化放在獨立的第一次工作階段](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents):initializer 寫出 `init.sh`、進度檔案、功能清單和初始 commit;後續 coding 工作階段讀取這些狀態,一次做一個功能,端到端測試,提交並更新進度。
OpenAI 的 Codex harness engineering 指南也強調「儲存庫作為操作記錄」的原則,第一次執行就要建立有效的操作結構,否則每次新工作階段都得重新推斷專案約定。
diff --git a/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
index 1006597..5f8d7d6 100644
--- a/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
+++ b/docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -26,7 +26,7 @@ Claude Code 的真實行為很說明問題。你讓它「新增使用者註冊
6 步之後,每一個都是半成品。沒有端到端驗證,程式碼之間耦合複雜,下一個工作階段來接手時將完全無從下手。
-Anthropic 的實驗資料直接支援這一點:使用「小下一步」策略(等價於 WIP=1)的 agent,任務完成率比使用寬泛提示的 agent 高 37%。更有意思的是,agent 生成的程式碼行數和實際完成的功能數量呈弱負相關,寫得越多,完成得越少。貪多嚼不爛,資料為證。
+Anthropic 的長執行 agent 指南[要求 coding agent 一次只做一個功能](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents),驗證、提交、更新進度,再繼續下一個。寬泛的 prompt 會讓 agent 同時開幾條線,每條線都在爭搶同一份脈絡和驗證預算。
## WIP=1 工作流
diff --git a/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
index b30533c..bc768fa 100644
--- a/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
+++ b/docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -25,7 +25,7 @@ Claude Code 和 Codex 都不會自動知道你心目中的「做完」是什麼
新的 agent 工作階段看到這個記錄,無法判斷「基本完成」的定義、購物車已通過的測試,以及支付目前的阻塞條件。答案都是「不知道」。
-結果是:新工作階段花 20 分鐘推斷專案狀態,最終可能重複實現已完成的功能。Anthropic 的工程實踐資料表明,好的進度記錄可以減少 60-80% 的工作階段啟動診斷時間。
+結果是:新工作階段要花時間推斷專案狀態,最終可能重複實現已完成的功能。Anthropic 的建議是[把進度和驗證結果寫進版本化檔案](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents),讓下一次工作階段能檢查狀態。
## 功能狀態機
@@ -116,7 +116,7 @@ agent 不能直接把狀態改成 `passing`。它只能提交驗證請求,harn
**結構化模式**:每個功能項有明確的狀態和驗證命令。新工作階段讀取功能清單,3 分鐘內知道:F01-F05 是 `passing`,F06 是 `active`(正在做),F07-F10 是 `not_started`。直接從 F06 繼續,零重複。
-定量結果:使用結構化功能清單的專案,功能完成率比自由形式高 45%,零重複實現。
+結構化清單把每個功能的狀態和驗證命令寫清楚,新工作階段一讀就知道哪些已經做完。
## 關鍵要點
diff --git a/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
index 98e8b89..6a151c1 100644
--- a/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
+++ b/docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -68,7 +68,7 @@ Anthropic 在 2026 年的研究中發現了一個更深層的失敗模式:**
| 架構 | 執行時期長 | 成本 | 核心功能是否可用 |
|------|---------|------|---------------|
| 單 agent 裸跑 | 20 分鐘 | $9 | 否(遊戲實體無法響應輸入) |
-| 三 agent(planner + generator + evaluator) | 6 小時 | $200 | 是(遊戲可以正常遊玩) |
+| 三 agent(planner + generator + evaluator) | 6 小時 | $200 | 核心玩法能跑;物理和關卡仍有問題 |
這是同一個模型(Opus 4.5),同一段提示詞(「做一個 2D 復古遊戲編輯器」)。區別只在 harness,從「裸奔」到「planner 擴展需求 → generator 逐功能實現 → evaluator 用 Playwright 實際點擊測試」。
@@ -117,7 +117,7 @@ OpenAI 在 Codex 實踐中提出了一個特別有效的模式,**給 agent 寫
**實際扣分項**,(1) 端到端流程未測試,重置連結的實際發送和驗證未確認。(2) 資料庫遷移在部分執行後失敗,導致 schema 不一致。(3) 郵件服務配置在目標環境中缺失。
-**harness 介入**,終止校驗強制執行,(1) 啟動完整應用驗證重置端點可訪問;(2) 執行完整重置流程;(3) 驗證資料庫狀態一致性。所有缺陷在工作階段內被發現,節省了 5-10 倍的後續修復成本。
+**harness 介入**,終止校驗強制執行,(1) 啟動完整應用驗證重置端點可訪問;(2) 執行完整重置流程;(3) 驗證資料庫狀態一致性。所有缺陷在工作階段內被發現,此時修復成本還是局部的。
## 關鍵要點
diff --git a/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
index 593af3f..cd210e9 100644
--- a/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
+++ b/docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -132,7 +132,7 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.rea
| 權限問題 | 打包環境權限不同 | 未檢測 | 檢測 |
| 錯誤傳播 | 服務層例外未到 UI 層 | 未檢測 | 檢測 |
-5 個缺陷全部被端到端測試捕獲,單元測試一個都沒發現。代價是測試時間從 2 秒增加到 15 秒,在 agent 工作流裡完全可以接受。
+5 個缺陷全部被端到端測試捕獲,單元測試一個都沒發現。端到端執行更慢,但在 agent 工作流裡,這點成本遠小於把五個邊界缺陷帶到發佈。
## 關鍵要點
diff --git a/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
index 5935250..e5c0202 100644
--- a/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
+++ b/docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -21,7 +21,7 @@
**重試變成盲猜**,agent 不知道為什麼失敗時,重試方向是隨機的。它可能在錯誤的方向上反覆嘗試,修復了不相關的程式碼路徑而忽略真正的故障根源。每次錯誤方向的重試都擴大了與真正根因的距離。每次盲重試都消耗 token 和時間。
-**工作階段交接資訊斷崖**,當未完成的工作移交給下一個工作階段時,缺乏可觀測性意味著新工作階段必須從零診斷系統狀態。Anthropic 的長期執行 agent 觀察表明,這種重複診斷可能佔工作階段總時間的 30-50%。新工作階段缺乏前一階段的脈絡,必須從頭診斷,重複投入本可省略的工作。
+**工作階段交接資訊斷崖**,當未完成的工作移交給下一個工作階段時,缺乏可觀測性意味著新工作階段必須從零診斷系統狀態。新工作階段要重讀程式碼、重跑命令、判斷哪些訊號重要;[版本化的進度和驗證記錄](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)能提供可檢查的狀態。
## Claude Code 的真實場景
@@ -31,7 +31,7 @@
**具備完整可觀測性**,計劃者輸出衝刺合約,列明要改哪些元件、每個元件的驗證標準、排除項(不處理列印樣式)。生成者按合約實現。執行時期可觀測性記錄每個元件的樣式加載和應用過程。評估者用評分標準逐維度評估,附具體證據引用,「按鈕顏色對比度不足(WCAG AA 標準 4.5:1,實測 2.1:1)」。一次迭代出高品質結果,總耗時約 15 分鐘。
-效率差 3 倍。區別只在可觀測性。
+差別來自合約和證據是否存在於 agent 的腦子之外。
## 雙層可觀測性
@@ -122,7 +122,7 @@ flowchart LR
## Anthropic 的三 agent 架構實驗
-Anthropic 在 2026 年 3 月發佈了一項系統性的 harness 實驗。他們用三種架構跑同一個任務(「用 Web Audio API 做一個瀏覽器端 DAW」),記錄了詳細的階段資料:
+Anthropic 2026 年 3 月的報告給出了[同一套三 agent 架構更新版的 DAW 執行資料](https://www.anthropic.com/engineering/harness-design-long-running-apps)(「用 Web Audio API 做一個瀏覽器端 DAW」)。第一版為 Opus 4.5 構建,generator 按 sprint 工作、evaluator 逐 sprint 評分;更新版在 Opus 4.6 上去掉 sprint,builder 連續實現,evaluator 在每輪構建後審查。下面的表是更新版的資料:
| Agent 和階段 | 時長 | 成本 |
|------------|------|------|
@@ -135,7 +135,7 @@ Anthropic 在 2026 年 3 月發佈了一項系統性的 harness 實驗。他們
| QA 第 3 輪 | 9.6 分鐘 | $4.06 |
| **總計** | **3 小時 50 分鐘** | **$124.70** |
-三個 agent 各司其職,每個都有明確的可觀測性角色:
+三個角色各司其職。下面的角色描述對應第一版;更新版把 generator 的 sprint 去掉,builder 連續工作,evaluator 每輪審查:
**Planner(規劃者)**,接收一段 1-4 句話的使用者需求,擴展成完整產品規格。被要求「大膽設定範圍」並且「專注於產品脈絡和高層技術設計,而不是詳細的技術實現」。原因是,如果 planner 過早指定了粒度技術細節且搞錯了,錯誤會級聯到下游實現。更好的做法是約束交付物,讓 agent 在執行中自己找到路徑。粒度過細的技術規格若有誤,錯誤會在實現階段逐層放大。
@@ -155,7 +155,7 @@ Evaluator 不是一開始就這麼強。早期版本會識別出合理的問題
- **雙層可觀測性缺一不可**,執行時期訊號解釋「發生了什麼」,過程工件解釋「為什麼這樣做」。
- **衝刺合約前置對齊工作**,防止「生成者做了評估者因可預見原因立即拒絕的東西」。施工協定要在開工前簽,不是完工後補。
- **評分標準讓評估可復現**,不同評估者對同一輸出產生相似評分。
-- **可觀測性缺失導致 30-50% 的工作階段時間浪費在重複診斷上**。
+- **可觀測性把模糊的拒絕變成具體、可修的缺陷**。
## 延伸閱讀
diff --git a/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
index cc533e3..c482b9e 100644
--- a/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
+++ b/docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -17,7 +17,7 @@ Lehman 的軟體演化定律表明,持續變更的系統,除非主動管理
OpenAI 在 5 個月的 Codex 實驗中觀察到,**agent 會複製儲存庫中已有的模式,即使那些模式是不均勻的或次優的。** 隨著時間的推移,這種複製必然導致漂移。初始的模式不均勻性在反覆複製後會逐漸放大,最終導致程式碼庫明顯漂移。
-OpenAI 團隊最初花每週五(20% 的工作時間)手動清理「AI slop」。不出所料,這種方式不可擴展。週期性的手動清理無法阻止日常累積的技術債。他們的解決方案是:
+OpenAI 團隊最初把週五留出來——[一個工作日,約佔一週工作量的 20%](https://openai.com/index/harness-engineering/)——手動清理「AI slop」。隨著吞吐量上升,手動清理的成本壓過了收益。他們的解決方案是:
1. **把「黃金原則」編碼進儲存庫**,比如「優先使用共享工具套件而非手寫的 ad-hoc 輔助函式」(保持不變數集中)、「不要 YOLO 式地猜資料結構」(驗證邊界或依賴類型化 SDK)。這些原則是具體的、機械的、可自動檢查的。
2. **建立週期性的清理流程**,一組背景 Codex 任務定期掃描偏差,更新品質評分,開針對性的重構 PR。大多數可以在一分鐘內審查並自動合併。自動化清理任務取代了手動定期大掃除,降低維護成本。
@@ -45,7 +45,7 @@ flowchart LR
Fix --> Build
```
-但這還不夠。目前進度必須記錄在機器可讀的工件中,已完成的子任務和通過標準、進行中但未完成的子任務和目前狀態、尚未開始的子任務。好的進度記錄減少 60-80% 的工作階段啟動診斷時間。調試日誌、臨時檔案、註解掉的程式碼、TODO 標記這些臨時工件得清理乾淨,它們增加下一個工作階段的認知負擔。標準啟動路徑也必須可用,下一個工作階段能不能不人工干預就開始工作?環境初始化、程式碼庫載入、脈絡獲取、任務選擇,這些路徑不能被破壞。
+但這還不夠。目前進度必須記錄在機器可讀的工件中,已完成的子任務和通過標準、進行中但未完成的子任務和目前狀態、尚未開始的子任務。把進度和驗證結果記錄在版本化檔案裡,下一次工作階段就能檢查狀態、接著工作。調試日誌、臨時檔案、註解掉的程式碼、TODO 標記這些臨時工件得清理乾淨,它們增加下一個工作階段的認知負擔。標準啟動路徑也必須可用,下一個工作階段能不能不人工干預就開始工作?環境初始化、程式碼庫載入、脈絡獲取、任務選擇,這些路徑不能被破壞。
```mermaid
flowchart LR
@@ -74,7 +74,7 @@ flowchart LR
更糟的是,每個工作階段都有自己的任務目標。新工作階段來的時候是要做新功能的,不是來清理上一個工作階段的爛攤子的。它會忽略混亂直接開始新工作,然後在混亂的基礎上引入更多混亂。這是熵增的正回饋循環,混亂基礎上引入更多變更,使狀態愈發難以追蹤,形成自我強化的惡性循環。
-資料為證。一個使用 agent 持續開發 12 週的專案,沒有清潔策略的情況下:
+下面用一個 12 週的假設例子說明趨勢。沒有清潔策略的情況下:
- 第 1 週:建構通過率 100%,測試通過率 100%,新工作階段啟動 5 分鐘
- 第 4 週:建構 95%,測試 92%,啟動 15 分鐘
@@ -86,7 +86,7 @@ flowchart LR
- 第 1 週:100%,100%,5 分鐘
- 第 12 週:97%,95%,9 分鐘
-12 週後,建構通過率差 29 個百分點,新工作階段啟動時間差 85%。以上資料源自實際觀測,有明確的可重現紀錄。
+每週清理讓起步狀態保持穩定:每個工作階段結束時把建構、測試、進度和臨時工件收拾乾淨,下一個工作階段從同一個基線開始。
## 怎麼做
@@ -139,7 +139,7 @@ flowchart LR
harness 裡的每個元件之所以存在,是因為模型無法獨立做好某件事。但隨著模型改進,這些假設會過時。模型能力提升後,原本必要的 harness 元件可能變成多餘的開銷,而部分元件在特定任務難度下仍具價值。
-Anthropic 的實驗直接展示了這一點。他們最初的 harness 包含 sprint 拆分機制,把工作分成小塊讓 Sonnet 4.5 逐個完成。當 Opus 4.6 發佈後,模型的原生能力已經可以自主處理工作分解,sprint 構造變成了不必要的開銷。移除後,builder agent 能連續工作超過兩小時而不會跑偏,反而更流暢。
+Anthropic 的 harness 報告直接展示了這一點。第一版三 agent harness 為 Opus 4.5 構建,generator 按 sprint 工作。當 [Opus 4.6](https://www.anthropic.com/engineering/harness-design-long-running-apps) 發佈後,模型已經可以自主處理工作分解,sprint 構造變成不必要的開銷。在更新版的 DAW 執行中,builder 連續工作超過兩小時而不會跑偏。
但 evaluator 的情況不同。即使 Opus 4.6 能力更強,在任務接近模型能力邊界時,evaluator 仍然提供了實際價值,捕獲 generator 的遺漏功能和存根實現。這意味著 evaluator 的必要性取決於任務難度相對於模型能力的位置。
@@ -172,7 +172,7 @@ npm run test # 驗證清理未破壞功能
**有清潔策略(實驗組)**,每個工作階段結束時執行完整清潔檢查 + 每週清理循環。第 12 週,建構通過率 97%,測試通過率 95%,新工作階段啟動 9 分鐘,過時工件 11 個。
-到第 12 週,實驗組的建構通過率比對照組高 29 個百分點,測試通過率高 34 個百分點,新工作階段啟動時間減少 85%。每個工作階段多花 5 分鐘清理,12 週後省下了幾十個小時的混亂時間。
+到第 12 週,有清理策略的一組,建構和測試通過率仍接近起點,新工作階段能較快開始,過時工件很少。清理每個工作階段只多花幾分鐘,換來的是一份下一個工作階段可以信任的起步狀態。
## 關鍵要點
diff --git a/docs/zh-TW/lectures/lecture-13-loop-engineering/index.md b/docs/zh-TW/lectures/lecture-13-loop-engineering/index.md
index c60c2e0..a5b450b 100644
--- a/docs/zh-TW/lectures/lecture-13-loop-engineering/index.md
+++ b/docs/zh-TW/lectures/lecture-13-loop-engineering/index.md
@@ -84,11 +84,11 @@
你不必每次都寫 `/goal`。但理解它從哪來、為什麼長這樣,就理解了 loop engineering 的核心——更複雜的 loop 只是在三樣基礎(目標、驗證、停止)之上,加上了排程、平行、隔離、記憶這些零件。
-## 2026 年 6 月,三個人在同一週點了一把火
+## 不同的日期,同一個方向
-2026 年 6 月第一週,三位構建 coding agent 基礎設施的核心人物,在沒有通氣的情況下,說了同一句話的不同版本。
+同一個想法出現在不同的地方、不同的時間。
-**Peter Steinberger**(OpenClaw 作者,[其推文收穫 800 萬瀏覽](https://x.com/steipete/status/2063697162748260627)):「你不應該再給 coding agent 寫 prompt 了。你應該設計循環去 prompt 你的 agent。」
+**Peter Steinberger**(OpenClaw 作者,[在一條推文裡](https://x.com/steipete/status/2063697162748260627)):「你不應該再給 coding agent 寫 prompt 了。你應該設計循環去 prompt 你的 agent。」
**Boris Cherny**(Anthropic Claude Code 負責人,[在 Acquired 播客上](https://x.com/rohanpaul_ai/status/2063289804708835412)):「我已經不手動 prompt Claude 了。我有一堆循環在跑,它們負責 prompt Claude、搞清楚要做什麼。我的工作變成了寫循環。」
@@ -96,9 +96,9 @@
> **Loop engineering 就是用系統取代你自己去 prompt agent。**
-Cherny 透露了一個數字:在連續 30 天裡,Claude Code 的所有程式碼貢獻全部由 AI 自主完成,累計合併 259 個 PR,其中超過 80% 的生產程式碼由 Claude 編寫,開放式軟體任務成功率達到 76%。
+Cherny 在[2025-12-27 的個人報告](https://twitter.com/bcherny/status/2004887829252317325)裡寫道:30 天內他合併了 259 個 PR——497 次 commit,新增 40,000 行、刪除 38,000 行——每一行都由 Claude Code + Opus 4.5 寫成。
-三個人、同一週、同一個結論。不是因為商量好的,是因為基礎設施剛好跨過了一個門檻:agent 已經可靠到能獨立完成非 trivial 任務、排程原語(`/loop`、`/goal`、cron)已經內建於工具中、單次運行的 token 成本也低到值得反覆跑。當零件全部就定位,把零件拼在一起的動作,所有人在同一時間想到了。
+這些引文來自不同的日期、形式和團隊,共同方向是把排程、驗證和停止判斷從當下的 prompt 裡移出來,放進一個系統。到 2026 年中,agent 能獨立完成非平凡任務、排程原語已經內建、單次執行成本也低到值得按計時器反覆跑;零件齊了,把零件拼起來的動作就不止一個人想得到。
> 來源:[Addy Osmani: Loop Engineering](https://addyosmani.com/blog/loop-engineering/)
@@ -267,7 +267,7 @@ flowchart TD
這不再是一個 agent 的一次運行。它是一個持續運轉的系統,每天早上自己醒來,自己掃地,自己把需要你關注的東西放到你面前。你的角色變成了:**審閱 inbox 的內容,做決策,遇到系統處理不了的模式就最佳化 skill 或規則。**
-Cherny 用這個模式讓 Claude Code 團隊在 30 天內合併了 259 個 PR,自己一次都沒有打開 IDE。OpenAI 的工程師用同樣的模式建立了約一百萬行程式碼的 beta 產品,一行都沒有手寫。
+Cherny 的 30 天報告是這個模式的一個資料點:259 個 PR,程式碼由 Claude Code + Opus 4.5 寫成。OpenAI 的 [harness 記錄](https://openai.com/index/harness-engineering/)是另一個:一個小團隊用 Codex 在一個全新儲存庫上工作了五個月,報告了約 100 萬行程式碼和約 1,500 個 PR。
## Generator/Evaluator 分離:為什麼不能讓自己批自己作業
@@ -293,7 +293,7 @@ Cherny 用這個模式讓 Claude Code 團隊在 30 天內合併了 259 個 PR,
如果想看一個設計精良、真實跑通的 loop 長什麼樣,Andrej Karpathy 的 [autoresearch](https://github.com/karpathy/autoresearch) 是最好的教材。
-2026 年 3 月,Karpathy 發布了一個 630 行 Python 的專案。給它一張 GPU、一份研究方向,它能自己跑一整夜,完成上百個 ML 訓練實驗,只保留真正有改進的。專案上線幾天內獲得 66,000+ star。
+2026 年 3 月,Karpathy 發布了 [autoresearch](https://github.com/karpathy/autoresearch)。儲存庫刻意做得很小:`prepare.py` 是固定基礎設施,`train.py` 是 agent 改的檔案(約 630 行),`program.md` 是人改的研究方法論。給它一張 GPU、一份研究方向,它能自己跑一整夜——每次實驗的訓練牆鐘預算固定為 5 分鐘(不含啟動和編譯),只保留讓 `val_bpb` 變好的改動。
### 三個檔案,三種角色
@@ -343,9 +343,9 @@ flowchart TD
8b --> 9
```
-每小時大約跑 12 次實驗。睡一覺(8 小時)就是約 100 次。Karpathy 自己跑了 2 天,約 700 次實驗。
+README 估計每小時約 12 次實驗,8 小時夜間運行約 100 次。5 分鐘只覆蓋訓練,不含啟動和編譯;每一輪的其餘時間用於編輯、啟動和評估。Karpathy 報告說,下面這輪 nanochat 改進是用一個私有版 autoresearch 自主運行約兩天得到的。
-固定 5 分鐘牆鐘是個關鍵設計——不管 agent 改了什麼,每次實驗時間完全一樣。這意味著所有結果在同一時間預算下直接可比,不會出現「這個跑久一點所以更好」的爭議。
+固定的 5 分鐘訓練預算是關鍵設計——不管 agent 改了什麼,訓練運行拿到的牆鐘預算相同。這意味著所有結果在同一訓練預算下直接可比。
### 輸出:你早上起來看到什麼
@@ -375,13 +375,9 @@ Agent 會在 commit message 裡寫清楚它試了什麼、什麼有效、什麼
### 實際跑出了什麼結果
-Karpathy 首輪 2 天、約 700 次實驗的結果:
+autoresearch [第一輪](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)把 nanochat 在 8×H100 上復現 GPT-2 水準的訓練時間[從 **2.02 小時降到 1.80 小時**](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b),訓練耗時縮短約 **10.9%**。
-- 從約 700 次嘗試中篩出了約 **20 個可堆疊的有效改進**
-- 將 nanochat 在 8×H100 上復現 GPT-2 水準的訓練時間從 **2.02 小時壓縮到 1.80 小時**,提速約 **11%**
-- 找到的改進包括:學習率調整、最佳化器微調、啟動函數替換、注意力模式最佳化等
-
-不是所有改進都是驚天動地的大發現嗎?不是。大部分是小最佳化堆疊出來的。但這 20 個有效改進,靠人手動做要花幾週——agent 用 48 小時跑完了。
+大部分是小最佳化堆疊出來的。真正有用的是 loop 本身:固定預算、完整實驗日誌,以及「只保留已驗證改進」的規則。
### 最值得注意的細節:loop 是用英文寫的,不是用程式碼。
@@ -399,7 +395,7 @@ loop 跑得快的時候,你很容易跳過驗證。「看起來沒問題」不
### 2. Comprehension Rot(理解腐爛)
-loop 出程式碼的速度越快,你對自己程式碼庫的理解就越跟不上。Cherny 的團隊 80% 的程式碼是 agent 寫的——這意味著一個團隊大部分程式碼不是人寫的。如果不讀不用,你對系統的理解會持續衰減。**快速跑 loop 的前提是快速讀結果。**
+loop 出程式碼的速度越快,你對自己程式碼庫的理解就越跟不上。一個 loop 合併了上百個 PR,團隊要讀這些 PR、審查真正重要的 diff、繼續親自使用這些程式碼,讓心智模型跟上程式碼。**快速跑 loop 的前提是快速讀結果。**
### 3. Cognitive Surrender(認知投降)
@@ -407,11 +403,11 @@ loop 出程式碼的速度越快,你對自己程式碼庫的理解就越跟不
### 4. Token Blowout(權杖爆炸)
-loop 的每一次迭代都會積累更多上下文。程式碼寫過了,錯誤遇到了,決策做過了。如果不做上下文壓縮,prompt size 會隨著迭代次數近似平方成長。Codex 的解決方案是自動 context compaction——用一個專門的 API 將老的對話輪次壓縮成加密的內容摘要,保留關鍵知識,丟棄冗餘細節。這是每個 loop 設計之初就要考慮的工程問題。
+loop 的每一次迭代都會積累更多上下文。程式碼寫過了,錯誤遇到了,決策做過了。當每一輪只新增近似固定數量的內容時,單輪看到的歷史長度隨輪數近似線性成長;如果系統每一輪都重新處理完整歷史,N 輪的累計輸入量才近似二次成長。Codex 的解決方案是自動 context compaction——用一個專門的 API 將老的對話輪次壓縮成加密的內容摘要,保留關鍵知識,丟棄冗餘細節。這是每個 loop 設計之初就要考慮的工程問題。
## 從零構建你的第一個 Loop
-不需要一上來就搭一個 Stripe 級別、每週合併 1,300 個 PR 的系統。從最小可行的版本開始。
+不需要一開始就搭一個高吞吐量的流水線。從最小可行的版本開始。
### 第一步:選一個重複發生的任務
diff --git a/docs/zh-TW/lectures/lecture-14-graph-engineering/index.md b/docs/zh-TW/lectures/lecture-14-graph-engineering/index.md
index 4ceada8..d7137fd 100644
--- a/docs/zh-TW/lectures/lecture-14-graph-engineering/index.md
+++ b/docs/zh-TW/lectures/lecture-14-graph-engineering/index.md
@@ -9,7 +9,7 @@
> 「我們還在談 Loop,還是已經轉向 Graph 了?」
-一條推,一天內就拿到約 57 萬瀏覽,到月底漲到約 300 萬。幾小時後,機器學習工程師 Hamel Husain 發了一篇題為《Loop Engineering Is Dead. Enter Graph Engineering》的文章——正文只有一張寫著 "Stop it" 的動圖——又拿了約 68 萬瀏覽。
+一條推。幾小時後,機器學習工程師 Hamel Husain 發了一篇題為《Loop Engineering Is Dead. Enter Graph Engineering》的文章——正文只有一張寫著 "Stop it" 的動圖。
更耐人尋味的是:**這兩個人都是當作玩笑在發。** 一個在諷刺行業每六週發明一個新名詞,一個在順著這個梗一捧一逗。但玩笑只存活了大約一個週末——課程、路線圖、工具棧在週末結束前就鋪滿了時間軸,還跟著一堆編造出來的數字:「準確率 +18%、成本 -85%」是假數據(18% 和 85% 確實存在,但出自一篇關於化工管道圖紙的論文,且對照基線根本不同),「微軟、史丹佛、Anthropic 同時發現了圖工程」也是假消息。事實查核確認的唯一「先行者」是 Josh Simmons:他的《We Are Entering the Graph Engineering Phase》寫於 7 月 4 日,比這場玩笑早了整整兩週——**是玩笑讓這件事變得流行,不是玩笑創造了這件事。**
@@ -257,11 +257,11 @@ run(graph, entry={"requirements": "修復登入頁 bug"}, thread="session-1")
## 開源專案:發布後才有的,發布前就有的
-先劃清界線:**Graph Engineering 是 2026 年 7 月 18 日之後才有的名字。** 在那之前開源的框架,都不是「Graph Engineering 發布後的專案」。真正在概念爆火後、直接以這個名字出現的開源專案,截至 2026 年 8 月初,站得住的只有一個:
+先劃清界線:**Graph Engineering 是 2026 年 7 月 18 日之後才有的名字。** 在那之前開源的框架,都不是「Graph Engineering 發布後的專案」。一個直接在名字上使用 Graph Engineering 的專案是 GraphARC:
**概念發布後才有的**
-- [GraphArc](https://github.com/CodeGraphContext/grapharc)(2026-08-02):自稱「Graph Engineering 的第一個即時實作」。它把 agent 執行從埋在日誌裡的 trace 變成一張**可互動的即時編排圖**——每個 agent、每條依賴、每個決策點都畫出來,在執行前視覺化整張圖,你確認(甚至可以拿手機看)之後再放行。作者背景是給 4000+ 開發者做圖工具,方向是「可觀測、可除錯、可工程化」。非常新,功能還在早期。
+- [GraphARC](https://github.com/CodeGraphContext/GraphARC)(2026 年 7 月建立):自稱「an end to end implementation of Graph Engineering as proposed by Andrew NG and Peter Steinberger」。它是一個早期階段的 Python 專案。有用的做法是讀它的編排模型,判斷這套方法是否適合你的工作流。
**概念發布前就有的(它們不叫 Graph Engineering,但它們才是你建構時要用的)**
@@ -325,7 +325,7 @@ run(graph, entry={"requirements": "修復登入頁 bug"}, thread="session-1")
- [goddaehee: Graph Engineering 事實查核(韓語,2026-07-30)](https://goddaehee.tistory.com/628) — 最完整的事實查核:玩笑起源時間軸、假數字拆解、LangGraph 數據、Hacker News 熱度對比
- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — 比那場玩笑早兩週的嚴肅文章
- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — 官方回應:「不是新想法,是既有方法的最新名字」;LangGraph 月下載 6500 萬+
-- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — 熱詞傳播數據(首發推文 57.5 萬瀏覽)
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — 對這個詞如何傳播的敘述
- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — 七個主流開源框架的橫向對比:LangGraph、CrewAI、Microsoft Agent Framework、LlamaIndex、Google ADK、OpenAI Agents SDK、Mastra
- [LangGraph 官方文件](https://docs.langchain.com/oss/python/langgraph/graph-api) — "Nodes do the work, edges tell what to do next";節點和邊的精確定義,建構圖的第一手參考
- [Anthropic: Building Effective Agents (Dec 2024)](https://www.anthropic.com/engineering/building-effective-agents) — 五種模式,畫出來就是圖;workflow vs agent 的權威區分
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.md
index e6ef132..501bb9a 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
@@ -5,13 +5,13 @@
# 第一讲. 模型能力强,不等于执行可靠
-截至 2025 年底,最强的 coding agent 在 SWE-bench Verified 上的通过率大约在 50-60%。这个数字听起来还不错,但别急着高兴——那些都是精心挑选过的任务,有明确的 issue 描述,有现成的测试用例。等你把自己日常的需求丢过去,需求模糊、没有现成测试、隐含的业务规则散落在各处,通过率只会更低。你信心满满地交代一个任务,agent 跑了 20 分钟后告诉你"做完了",你一看代码,加了功能但测试挂了,改了 bug 但引入了新 bug,根本不是你要的东西。
+2025 年 9 月 29 日,Anthropic 公布 Claude Sonnet 4.5 [在 SWE-bench Verified 上取得 77.2%](https://www.anthropic.com/news/claude-sonnet-4-5)。这个数字听起来还不错,但别急着高兴——那些都是精心挑选过的任务,有明确的 issue 描述,有现成的测试用例。等你把自己日常的需求丢过去,需求模糊、没有现成测试、隐含的业务规则散落在各处,通过率只会更低。你信心满满地交代一个任务,agent 跑了 20 分钟后告诉你"做完了",你一看代码,加了功能但测试挂了,改了 bug 但引入了新 bug,根本不是你要的东西。
遇到这种情况,大多数人的第一反应是"这模型不行,换一个更贵的"。先别急着掏钱包。问题可能不在模型身上。
## 同一匹马,两种命运
-Anthropic 做过一个对照实验,很能说明问题。同一个 prompt,"做一个 2D 复古游戏编辑器",同一个模型 Opus 4.5,跑了两次。第一次裸跑,20 分钟花了 $9,游戏核心功能跑不起来。第二次配上了完整的 harness——planner、generator、evaluator 三 agent 架构——6 小时花了 $200,游戏可以正常游玩。
+Anthropic 比较了同一个 prompt、"做一个 2D 复古游戏编辑器"、同一个模型 Opus 4.5 在两种 harness 下的表现。第一次裸跑,20 分钟花了 $9:应用能打开,但实体出现在屏幕上、对输入没有反应,实体定义和游戏运行时的接线断了。第二次配上了完整的 harness——planner、generator、evaluator 三 agent 架构——6 小时花了 $200:能移动实体,但物理有粗糙之处,还会被墙挡住,[核心玩法能跑,应用仍不完整](https://www.anthropic.com/engineering/harness-design-long-running-apps)。
Opus 4.5 还是那个 Opus 4.5,模型没有换。换的是马具。
@@ -31,9 +31,9 @@ OpenAI 在 2025 年的 harness engineering 文章里把这件事说得更直白
理解了上面的场景,这些概念就不再是一堆术语了:
-- **能力鸿沟(Capability Gap)**:模型在基准测试上的表现和真实任务上的表现之间的巨大落差。SWE-bench Verified 上 50-60% 的通过率意味着近一半的真实 issue 解不了。
+- **能力鸿沟(Capability Gap)**:模型在基准测试上的表现和真实任务上的表现之间的巨大落差。基准任务的 issue 描述、测试和环境是给定的;真实任务里,这些往往要你自己补。
- **Harness**:模型之外的一切——指令、工具、环境、状态管理、验证反馈。不是模型权重的部分,全是 harness。也就是我们说的"马具"。
-- **Harness 诱导失败**:模型本身能力足够,但因为执行环境有结构性缺陷而失败。Anthropic 的对照实验已经证明了这一点。
+- **Harness 诱导失败**:模型本身能力足够,但因为执行环境有结构性缺陷而失败。上面的复古游戏对比就是一个例子。
- **验证缺口**:agent 对自己输出的信心评估和实际正确性之间的偏差。agent 说"我做完了"但实际没做完——这是最常见的失败模式。
- **诊断循环**:执行 → 观察失败 → 定位到 harness 的哪一层出了问题 → 修补那一层 → 重新执行。这是 harness 工程的核心方法论。
- **完成定义(Definition of Done)**:一组可以用命令验证的条件——测试通过、lint 没报错、类型检查通过。没有显式的完成定义,agent 就会自己编一个。
@@ -60,7 +60,7 @@ OpenAI 在 2025 年的 harness engineering 文章里把这件事说得更直白
## 一百万行代码的实验
-2025 年,OpenAI 的三个工程师开始了一项实验。规则很简单:他们不写代码,只让 Codex 写。从一个空的 git 仓库起步,五个月下来,仓库里有了大约 100 万行代码。应用逻辑、基础设施、工具、文档——全是 agent 生成的。三个工程师一共开了 1,500 个 PR,平均每人每天 3.5 个。
+2025 年 8 月,OpenAI 的三个工程师开始了一项实验。规则很简单:他们不写代码,只让 Codex 写。从一个空的 git 仓库起步,[五个月下来,仓库里有了大约 100 万行代码](https://openai.com/index/harness-engineering/)。应用逻辑、基础设施、工具、文档——全是 agent 生成的。团队后来扩展到七人,一共合并了约 1,500 个 PR,平均每人每天 3.5 个。
起初的进展出乎意料地慢。Codex 并不差,但它缺少足够完整的工具和结构去推进那些高层次的目标。三个工程师慢慢摸到了门道:把大的目标拆成小的积木块——设计、编码、审查、测试——让 agent 逐个搭建,再用这些积木去组合更复杂的任务。每当某件事做砸了,问题几乎从来不是"不够努力",而是 agent 还缺什么——缺的能力能不能用一种既可理解又可执行的方式补上去。
@@ -72,9 +72,9 @@ OpenAI 在 2025 年的 harness engineering 文章里把这件事说得更直白
一个团队用 Claude Sonnet 给一个中等规模的 Python Web 应用(FastAPI + PostgreSQL + Redis,约 15,000 行代码)添加新的 API 端点。
-起初他们只给了一句话:"在 `/api/v2/users` 下添加用户偏好设置端点"。结果呢?agent 花了 40% 的上下文窗口探索仓库结构,产出了看似合理的代码但没遵循项目的错误处理模式,用了旧版 SQLAlchemy 语法,宣称完成但端点实际有运行时错误。下一个会话还得重新做发现工作。
+起初他们只给了一句话:"在 `/api/v2/users` 下添加用户偏好设置端点"。结果呢?agent 把大量时间花在探索仓库结构上,产出了看似合理的代码但没遵循项目的错误处理模式,用了旧版 SQLAlchemy 语法,宣称完成但端点实际有运行时错误。下一个会话还得重新做发现工作。
-后来他们加了 `AGENTS.md`(描述项目架构和技术栈版本)、显式的验证命令(`pytest tests/api/v2/ && python -m mypy src/`)、和架构决策记录。同一模型在三次独立运行中全部成功,上下文使用效率提高了约 60%。
+后来他们加了 `AGENTS.md`(描述项目架构和技术栈版本)、显式的验证命令(`pytest tests/api/v2/ && python -m mypy src/`)、和架构决策记录。同一个模型开始遵循项目约定,并用能执行的命令检查工作。
模型没变。变的还是 harness。
diff --git a/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
index ec94111..1a7de19 100644
--- a/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
+++ b/docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -50,7 +50,7 @@ flowchart LR
- **上下文窗口是有限的**:不管模型宣称多大的窗口(128K、200K、1M),长任务总会用完。用完之后要么压缩(丢信息),要么重置(开新会话),两种方式都会丢东西。
- **状态持久化文件**:持久化的状态文件,让新会话能无歧义地恢复到上次离开的地方。最基本的形式包括进度日志、验证记录和下一步行动。
-- **重建成本**:新会话恢复到可执行状态所需的时间。好的 harness 能把重建成本从 15 分钟压到 3 分钟。
+- **重建成本**:新会话恢复到可执行状态所需的时间。好的 harness 会把进度、验证结果和下一步写进文件,让新会话从写下来的状态开始。
- **漂移(Drift)**:agent 的理解跟代码仓库实际状态之间的偏差。每次会话边界都会引入漂移,不加控制会越漂越远。
- **上下文焦虑**:Anthropic 观察到的现象,agent 在接近上下文限制时表现异常,过早结束任务以避免信息丢失,本质上是一种非理性的资源焦虑。
- **压缩 vs 重置**:压缩是在同一个会话里把上下文摘要化,保留"是什么"但可能丢了"为什么";重置是开新会话从持久化状态重建,状态干净但依赖工件的完备性。
@@ -158,7 +158,7 @@ LangChain 报告了一组真实的 harness 改进结果:固定使用 gpt-5.2-c
- 上下文窗口是有限的资源。长任务一定会跨会话,跨会话一定会丢信息,这是客观现实。
- 解决方案不是更大的窗口,而是更好的状态持久化。进度文件、决策日志、git 检查点,三者配合让新会话能接上之前的工作。
- 把 agent 当成每次会话都会清空短期记忆的工程师来管理:每次"下班"前写清楚做了什么、为什么、下一步做什么。
-- 重建成本是关键指标。好的 harness 应该让新会话在 3 分钟内恢复到可执行状态。
+- 重建成本是关键指标。好的 harness 会把进度、验证结果和下一步写进文件,让新会话快速恢复。
- 混合策略:短任务在会话内完成,长任务用结构化工件维持连续性。
## 延伸阅读
diff --git a/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
index ef0127a..6338524 100644
--- a/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
+++ b/docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -37,7 +37,7 @@ flowchart TB
## 初始化与实现同时进行的问题
-最直接的问题是基础设施搭不牢。Agent 花了 80% 的精力写功能代码,剩下 20% 随便搭了点基础设施。测试框架配了但没验证过,lint 规则设了但太宽松,进度文件没创建。这些缺陷在第一个会话里不明显(因为 agent 还记得它做了什么),但到第二个会话就暴露了:新 agent 不知道项目怎么跑、怎么测、做到哪了。
+最直接的问题是基础设施搭不牢。Agent 把大部分精力花在功能代码上,基础设施只是顺手搭一点。测试框架配了但没验证过,lint 规则设了但太宽松,进度文件没创建。这些缺陷在第一个会话里不明显(因为 agent 还记得它做了什么),但到第二个会话就暴露了:新 agent 不知道项目怎么跑、怎么测、做到哪了。
更隐蔽的代价是"未验证的累积"。在测试框架配好之前写的功能代码,等回头补测试的时候可能发现设计上就有问题,早知道的话应该用不同的方式实现。前面写的代码越多,后面需要推翻重来的就越多。
@@ -45,7 +45,7 @@ flowchart TB
最容易被忽略的是隐式假设埋下的雷。Agent 在初始化过程中做的决策(用什么测试框架、目录怎么组织、依赖怎么管理)如果不显式记录下来,后续会话就可能做出矛盾的选择。第一个会话选了 Vitest 做测试框架,第二个会话的 agent 不知道,又引入了 Jest,两套测试框架共存,维护成本翻倍。
-Anthropic 在他们的长运行应用开发研究中明确建议把初始化和实现分离。他们的实验数据:使用独立初始化阶段的项目,多会话场景中的功能完成率比混合方式高 31%。而且初始化阶段投入的时间在后续 3-4 个会话中就能完全收回。
+Anthropic 的长运行 agent 工作[把初始化放在独立的第一个会话里](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents):initializer 写 `init.sh`、进度文件、功能清单和初始 commit;后续 coding 会话读取这些状态,一次做一个功能,端到端测试,提交并更新进度。
OpenAI 的 Codex harness engineering 指南也强调"仓库作为操作记录"的原则:第一次运行就要建立清晰的操作结构,否则每次新会话都得重新推断项目约定。
diff --git a/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
index 89817e9..eaebbf4 100644
--- a/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
+++ b/docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -26,7 +26,7 @@ Claude Code 的真实行为很说明问题。你让它"添加用户注册功能"
6 步之后,每一个都是半成品。没有端到端验证,代码之间耦合复杂,下一个会话来接手时会一脸懵。
-Anthropic 的实验数据直接支持这一点:使用"小下一步"策略(等价于 WIP=1)的 agent,任务完成率比使用宽泛提示的 agent 高 37%。更有意思的是,agent 生成的代码行数和实际完成的功能数量呈弱负相关,写得越多,完成得越少。贪多嚼不烂,数据为证。
+Anthropic 的长运行 agent 指南[要求 coding agent 一次只做一个功能](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents),验证、提交、更新进度,再继续下一个。宽泛的 prompt 会让 agent 同时开几条线,每条线都在争抢同一份上下文和验证预算。
## WIP=1 工作流
diff --git a/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
index 640a15e..0a8661c 100644
--- a/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
+++ b/docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -25,7 +25,7 @@ Claude Code 和 Codex 都不会自动知道你心目中的"做完"是什么意
新的 agent 会话看到这个记录,能回答以下问题吗?"基本完成"意味着什么?购物车通过了哪些测试?支付的阻塞条件是什么?答案都是"不知道"。
-结果是:新会话花 20 分钟推断项目状态,最终可能重复实现已完成的功能。Anthropic 的工程实践数据表明,好的进度记录可以减少 60-80% 的会话启动诊断时间。
+结果是:新会话要花时间推断项目状态,最终可能重复实现已完成的功能。Anthropic 的建议是[把进度和验证结果写进版本化文件](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents),让下一次会话能检查状态。
## 功能状态机
@@ -116,7 +116,7 @@ agent 不能直接把状态改成 `passing`。它只能提交验证请求,harn
**结构化模式**:每个功能项有明确的状态和验证命令。新会话读取功能清单,3 分钟内知道:F01-F05 是 `passing`,F06 是 `active`(正在做),F07-F10 是 `not_started`。直接从 F06 继续,零重复。
-定量结果:使用结构化功能清单的项目,功能完成率比自由形式高 45%,零重复实现。
+结构化清单把每个功能的状态和验证命令写清楚,新会话一读就知道哪些已经做完。
## 核心要点
diff --git a/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
index bed230d..7fc43c3 100644
--- a/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
+++ b/docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -68,7 +68,7 @@ Anthropic 在 2026 年的研究中发现了一个更深层的失败模式:**
| 架构 | 运行时长 | 成本 | 核心功能是否可用 |
|------|---------|------|---------------|
| 单 agent 裸跑 | 20 分钟 | $9 | 否(游戏实体无法响应输入) |
-| 三 agent(planner + generator + evaluator) | 6 小时 | $200 | 是(游戏可以正常游玩) |
+| 三 agent(planner + generator + evaluator) | 6 小时 | $200 | 核心玩法能跑;物理和关卡仍有问题 |
这是同一个模型(Opus 4.5),同一段提示词("做一个 2D 复古游戏编辑器")。区别只在 harness:从"裸奔"到"planner 扩展需求 → generator 逐功能实现 → evaluator 用 Playwright 实际点击测试"。
@@ -117,7 +117,7 @@ OpenAI 在 Codex 实践中提出了一个特别有效的模式:**给 agent 写
**实际遗漏项**:(1) 端到端流程未测试,重置链接的实际发送和验证未确认。(2) 数据库迁移在部分执行后失败,导致 schema 不一致。(3) 邮件服务配置在目标环境中缺失。
-**harness 介入**:终止校验强制执行,(1) 启动完整应用验证重置端点可访问;(2) 执行完整重置流程;(3) 验证数据库状态一致性。所有缺陷在会话内被发现,节省了 5-10 倍的后续修复成本。
+**harness 介入**:终止校验强制执行,(1) 启动完整应用验证重置端点可访问;(2) 执行完整重置流程;(3) 验证数据库状态一致性。所有缺陷在会话内被发现,此时修复成本还是局部的。
## 核心要点
diff --git a/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
index 6d8c31f..0366289 100644
--- a/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
+++ b/docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -130,7 +130,7 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.rea
| 权限问题 | 打包环境权限不同 | 未检测 | 检测 |
| 错误传播 | 服务层异常未到 UI 层 | 未检测 | 检测 |
-5 个缺陷全部被端到端测试捕获,单元测试一个都没发现。代价是测试时间从 2 秒增加到 15 秒,在 agent 工作流里完全可以接受。
+5 个缺陷全部被端到端测试捕获,单元测试一个都没发现。端到端运行更慢,但在 agent 工作流里,这点成本远小于把五个边界缺陷带到发布。
## 核心要点
diff --git a/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
index d6baee8..e55e221 100644
--- a/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
+++ b/docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -21,7 +21,7 @@ Agent 执行任务时常常像一个黑盒:它跑了 20 分钟,改了一堆
**重试变成盲猜**:agent 不知道为什么失败时,重试方向是随机的。它可能在错误的方向上反复尝试,修复了不相关的代码路径而忽略真正的故障根源。每次盲重试都消耗 token 和时间。
-**会话交接信息断崖**:当未完成的工作移交给下一个会话时,缺乏可观测性意味着新会话必须从零诊断系统状态。Anthropic 的长期运行 agent 观察表明,这种重复诊断可能占会话总时间的 30-50%。
+**会话交接信息断崖**:当未完成的工作移交给下一个会话时,缺乏可观测性意味着新会话必须从零诊断系统状态。新会话要重读代码、重跑命令、判断哪些信号重要;[版本化的进度和验证记录](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)能提供可检查的状态。
## 实际运行示例
@@ -31,7 +31,7 @@ Agent 执行任务时常常像一个黑盒:它跑了 20 分钟,改了一堆
**有完整可观测性**:计划者输出冲刺合同,列明要改哪些组件、每个组件的验证标准、排除项(不处理打印样式)。生成者按合同实现,运行时可观测性记录每个组件的样式加载和应用过程。评估者用评分标准逐维度评估,附具体证据引用:"按钮颜色对比度不足(WCAG AA 标准 4.5:1,实测 2.1:1)"。一次迭代出高质量结果,总耗时约 15 分钟。
-效率差 3 倍,区别只在可观测性。
+差别来自合同和证据是否存在于 agent 脑子之外。
## 双层可观测性
@@ -122,7 +122,7 @@ flowchart LR
## Anthropic 的三 agent 架构实验
-Anthropic 在 2026 年 3 月发布了一项系统性的 harness 实验。他们用三种架构跑同一个任务("用 Web Audio API 做一个浏览器端 DAW"),记录了详细的阶段数据:
+Anthropic 2026 年 3 月的报告给出了[同一套三 agent 架构更新版的 DAW 运行数据](https://www.anthropic.com/engineering/harness-design-long-running-apps)("用 Web Audio API 做一个浏览器端 DAW")。第一版为 Opus 4.5 构建,generator 按 sprint 工作、evaluator 逐 sprint 评分;更新版在 Opus 4.6 上去掉 sprint,builder 连续实现,evaluator 在每轮构建后审查。下面的表是更新版的数据:
| Agent 和阶段 | 时长 | 成本 |
|------------|------|------|
@@ -135,7 +135,7 @@ Anthropic 在 2026 年 3 月发布了一项系统性的 harness 实验。他们
| QA 第 3 轮 | 9.6 分钟 | $4.06 |
| **总计** | **3 小时 50 分钟** | **$124.70** |
-三个 agent 各司其职,每个都有明确的可观测性角色:
+三个角色各司其职。下面的角色描述对应第一版;更新版把 generator 的 sprint 去掉,builder 连续工作,evaluator 每轮审查:
**Planner(规划者)**:接收一段 1-4 句话的用户需求,扩展成完整产品规格。被要求"大胆设定范围"并且"专注于产品上下文和高层技术设计,而不深入详细的技术实现"。原因是:如果 planner 过早指定了粒度技术细节且搞错了,错误会级联到下游实现。更好的做法是约束交付物,让 agent 在执行中自己找到路径。
@@ -155,7 +155,7 @@ Evaluator 不是一开始就这么强。早期版本会识别出合理的问题
- **双层可观测性缺一不可**:运行时信号解释"发生了什么",过程工件解释"为什么这样做"。
- **冲刺合同前置对齐工作**:防止"生成者做了评估者因可预见原因立即拒绝的东西"。
- **评分标准让评估可复现**:不同评估者对同一输出产生相似评分。
-- **可观测性缺失导致 30-50% 的会话时间浪费在重复诊断上**。
+- **可观测性把模糊的拒绝变成具体、可修的缺陷**。
## 延伸阅读
diff --git a/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
index 50cbf8b..6a7d57a 100644
--- a/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
+++ b/docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -15,7 +15,7 @@ Lehman 的软件演化定律告诉我们:一个持续变更的系统,如果
OpenAI 在 5 个月的 Codex 实验中观察到一个现象:agent 会复制仓库中已有的模式,哪怕那些模式是不一致或次优的。随着时间推移,这种复制必然导致整体质量漂移。打个比方:第一个人在公共区域放了一个杯子,第二个人路过时心想"反正已经乱了",自己也放了一个。一周后,桌上就堆满了。代码库的退化也是同样的过程。
-OpenAI 团队最初每周五花 20% 的工作时间手动清理 agent 留下的烂摊子,但这种做法显然不可持续。他们最终找到了系统性的解决方案:
+OpenAI 团队最初把周五留出来——[一个工作日,约占一周工作量的 20%](https://openai.com/index/harness-engineering/)——手动清理 agent 留下的"AI 垃圾"。随着吞吐量上升,手动清理的成本压过了收益。他们最终找到了系统性的解决方案:
1. **把好习惯写进仓库规则**:比如"优先使用共享工具包,不要手写 ad-hoc 辅助函数"、"不要瞎猜数据结构,查类型定义或用类型安全 SDK"。这些规则是具体的、机械的、可以自动检查的。
2. **建立周期性清理流程**:一组后台任务定期扫描偏离规则的代码,更新质量评分,自动开重构 PR。大多数 PR 可以在一分钟内审查并自动合并。
@@ -45,7 +45,7 @@ flowchart LR
构建和测试只是底线,还有三条容易被忽略的要求。
-第一,当前进度必须记录在机器可读的工件中。具体来说包括三类:已完成的子任务和它的通过标准、正在做但还没做完的子任务和它当前卡在哪、还没开始的子任务。好的进度记录可以减少 60% 到 80% 的会话启动诊断时间。
+第一,当前进度必须记录在机器可读的工件中。具体来说包括三类:已完成的子任务和它的通过标准、正在做但还没做完的子任务和它当前卡在哪、还没开始的子任务。把进度和验证结果记录在版本化文件里,下一次会话就能检查状态、接着工作。
第二,临时调试产物必须清理干净。调试日志、临时文件、注释掉的代码、TODO 标记,这些东西都会增加下一个会话的认知负担。新会话看到一堆 `console.log('debug')` 和 `// 临时方案,回头改`,根本分不清哪些是有意的、哪些是垃圾。
@@ -80,7 +80,7 @@ flowchart LR
更糟的是,每个会话都有自己的任务目标。新会话来的时候是为了做新功能,不是为了清理上一个会话遗留问题的。它会直接忽略混乱,在混乱的基础上开始新工作,然后引入更多混乱。这是一个熵增的正反馈循环——越乱越不管,越不管越乱。
-数据最能说明问题。下面是一个使用 agent 持续开发 12 周的项目的实际对比:
+下面用一个 12 周的假设例子说明趋势:
**没有清洁策略**:
@@ -98,7 +98,7 @@ flowchart LR
| 第 1 周 | 100% | 100% | 5 分钟 |
| 第 12 周 | 97% | 95% | 9 分钟 |
-12 周下来,两组之间的构建通过率差了 29 个百分点,测试通过率差了 34 个百分点,新会话启动时间差了 85%。这是实测数据,差距已经非常明显。
+每周清理让起步状态保持稳定:每个会话结束时把构建、测试、进度和临时工件收拾干净,下一个会话从同一个基线开始。
## 怎么做
@@ -153,7 +153,7 @@ flowchart LR
Harness 中每个组件的存在,都源于模型在某个方面尚无法独立完成。随着模型能力不断演进,这些前提会逐渐过时。
-Anthropic 的实验直观地展示了这一点。他们最初的 Harness 包含一个任务拆分机制:因为当时的模型一次性处理不了太大的任务,所以需要把大任务先拆成多个小步骤,让模型按顺序逐个完成。当 Opus 4.6 发布后,模型自己就能规划好该怎么一步步做事,不再需要外部帮忙拆解,这个机制反而成了多余的步骤。移除后,Builder Agent 能够连续工作超过两小时而不偏离方向,流程反而更流畅了。
+Anthropic 的实验直观地展示了这一点。他们最初的 Harness 包含一个任务拆分机制:因为当时的模型一次性处理不了太大的任务,所以需要把大任务先拆成多个小步骤,让模型按顺序逐个完成。当 [Opus 4.6 发布](https://www.anthropic.com/engineering/harness-design-long-running-apps)后,模型自己就能规划好该怎么一步步做事,原来的任务拆分机制成了多余的步骤。移除后,Builder Agent 能够连续工作超过两小时而不偏离方向,流程反而更流畅了。
Evaluator 的情况则有所不同。Evaluator 是 Harness 中的评估组件,负责检查生成的代码质量,找出遗漏的功能和未完成的实现。尽管 Opus 4.6 能力更强,当任务难度较高、逼近模型能力的上限时,Evaluator 依然很有用。但如果任务本身很简单,远在模型能力范围之内,Evaluator 可能就是多余的。因此,要不要保留 Evaluator,取决于你的任务有多难、模型有多强——这两者的相对关系才是关键。
@@ -188,7 +188,7 @@ npm run test # 验证清理没有破坏功能
**有清洁策略(实验组)**:每个会话结束时执行完整清洁检查,加上每周一次清理循环。第 12 周时,构建通过率 97%,测试通过率 95%,新会话启动 9 分钟,过时工件 11 个。
-到第 12 周,实验组的构建通过率比对照组高 29 个百分点,测试通过率高 34 个百分点,新会话启动时间减少 85%。每个会话只多花 5 分钟做清理,12 周下来却省了几十个小时的混乱时间。
+到第 12 周,有清理策略的一组,构建和测试通过率仍接近起点,新会话能较快开始,过时工件很少。清理每个会话只多花几分钟,换来的是一份下一个会话可以信任的起步状态。
## 核心要点
diff --git a/docs/zh/lectures/lecture-13-loop-engineering/index.md b/docs/zh/lectures/lecture-13-loop-engineering/index.md
index 81446de..d0b688e 100644
--- a/docs/zh/lectures/lecture-13-loop-engineering/index.md
+++ b/docs/zh/lectures/lecture-13-loop-engineering/index.md
@@ -84,11 +84,11 @@
你不必每次都写 `/goal`。但理解它从哪来、为什么长这样,就理解了 loop engineering 的核心——更复杂的 loop 只是在三样基础(目标、验证、停止)之上,加上了调度、并行、隔离、记忆这些零件。
-## 2026 年 6 月,三个人在同一周点了一把火
+## 不同的日期,同一个方向
-2026 年 6 月第一周,三位构建 coding agent 基础设施的核心人物,在没有通气的情况下,说了同一句话的不同版本。
+同一个想法出现在不同的地方、不同的时间。
-**Peter Steinberger**(OpenClaw 作者,[其推文收获 800 万浏览](https://x.com/steipete/status/2063697162748260627)):「你不应该再给 coding agent 写 prompt 了。你应该设计循环去 prompt 你的 agent。」
+**Peter Steinberger**(OpenClaw 作者,[一条推文](https://x.com/steipete/status/2063697162748260627)):「你不应该再给 coding agent 写 prompt 了。你应该设计循环去 prompt 你的 agent。」
**Boris Cherny**(Anthropic Claude Code 负责人,[在 Acquired 播客上](https://x.com/rohanpaul_ai/status/2063289804708835412)):「我已经不手动 prompt Claude 了。我有一堆循环在跑,它们负责 prompt Claude、搞清楚要做什么。我的工作变成了写循环。」
@@ -96,9 +96,9 @@
> **Loop engineering 就是用系统取代你自己去 prompt agent。**
-Cherny 透露了一个数字:在连续 30 天里,Claude Code 的所有代码贡献全部由 AI 自主完成,累计合并 259 个 PR,其中超过 80% 的生产代码由 Claude 编写,开放式软件任务成功率达到 76%。
+Cherny 在[2025-12-27 的个人报告](https://twitter.com/bcherny/status/2004887829252317325)里写道:30 天内他合并了 259 个 PR——497 次 commit,新增 40,000 行、删除 38,000 行——每一行都由 Claude Code + Opus 4.5 写成。
-三个人、同一周、同一个结论。不是因为商量好的,是因为基础设施刚好跨过了一个门槛:agent 已经可靠到能独立完成非 trivial 任务、调度原语(`/loop`、`/goal`、cron)已经内置于工具中、单次运行的 token 成本也低到值得反复跑。当零件全部就位,把零件拼在一起的动作,所有人在同一时间想到了。
+这些引文来自不同的日期、形式和团队,共同方向是把调度、验证和停止判断从当下的 prompt 里移出来,放进一个系统。到 2026 年中,agent 能独立完成非平凡任务、调度原语已经内置、单次运行成本也低到值得按定时器反复跑;零件齐了,把零件拼起来的动作就不止一个人想得到。
> 来源:[Addy Osmani: Loop Engineering](https://addyosmani.com/blog/loop-engineering/)
@@ -267,7 +267,7 @@ flowchart TD
这不再是一个 agent 的一次运行。它是一个持续运转的系统,每天早上自己醒来,自己扫地,自己把需要你关注的东西放到你面前。你的角色变成了:**审阅 inbox 的内容,做决策,遇到系统处理不了的模式就优化 skill 或规则。**
-Cherny 用这个模式让 Claude Code 团队在 30 天内合并了 259 个 PR,自己一次都没有打开 IDE。OpenAI 的工程师用同样的模式创建了约一百万行代码的 beta 产品,一行都没有手写。
+Cherny 的 30 天报告是这个模式的一个数据点:259 个 PR,代码由 Claude Code + Opus 4.5 写成。OpenAI 的 [harness 记录](https://openai.com/index/harness-engineering/)是另一个:一个小团队用 Codex 在一个全新仓库上工作了五个月,报告了约 100 万行代码和约 1,500 个 PR。
## Generator/Evaluator 分离:为什么不能让自己批自己作业
@@ -293,7 +293,7 @@ Cherny 用这个模式让 Claude Code 团队在 30 天内合并了 259 个 PR,
如果想看一个设计精良、真实跑通的 loop 长什么样,Andrej Karpathy 的 [autoresearch](https://github.com/karpathy/autoresearch) 是最好的教材。
-2026 年 3 月,Karpathy 发布了一个 630 行 Python 的项目。给它一张 GPU、一份研究方向,它能自己跑一整夜,完成上百个 ML 训练实验,只保留真正有改进的。项目上线几天内获得 66,000+ star。
+2026 年 3 月,Karpathy 发布了 [autoresearch](https://github.com/karpathy/autoresearch)。仓库刻意做得很小:`prepare.py` 是固定基础设施,`train.py` 是 agent 改的文件(约 630 行),`program.md` 是人改的研究方法论。给它一张 GPU、一份研究方向,它能自己跑一整夜——每次实验的训练墙钟预算固定为 5 分钟(不含启动和编译),只保留让 `val_bpb` 变好的改动。
### 三个文件,三种角色
@@ -343,9 +343,9 @@ flowchart TD
8b --> 9
```
-每小时大约跑 12 次实验。睡一觉(8 小时)就是约 100 次。Karpathy 自己跑了 2 天,约 700 次实验。
+README 估计每小时约 12 次实验,8 小时夜间运行约 100 次。5 分钟只覆盖训练,不含启动和编译;每一轮的其余时间用于编辑、启动和评估。Karpathy 报告说,下面这轮 nanochat 改进是用一个私有版 autoresearch 自主运行约两天得到的。
-固定 5 分钟墙钟是个关键设计——不管 agent 改了什么,每次实验时间完全一样。这意味着所有结果在同一时间预算下直接可比,不会出现"这个跑久一点所以更好"的争议。
+固定的 5 分钟训练预算是关键设计——不管 agent 改了什么,训练运行拿到的墙钟预算相同。这意味着所有结果在同一训练预算下直接可比。
### 输出:你早上起来看到什么
@@ -375,13 +375,9 @@ Agent 会在 commit message 里写清楚它试了什么、什么有效、什么
### 实际跑出了什么结果
-Karpathy 首轮 2 天、约 700 次实验的结果:
+autoresearch [第一轮](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)把 nanochat 在 8×H100 上复现 GPT-2 水平的训练时间[从 **2.02 小时降到 1.80 小时**](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b),训练耗时缩短约 **10.9%**。
-- 从约 700 次尝试中筛出了约 **20 个可堆叠的有效改进**
-- 将 nanochat 在 8×H100 上复现 GPT-2 水平的训练时间从 **2.02 小时压缩到 1.80 小时**,提速约 **11%**
-- 找到的改进包括:学习率调整、优化器微调、激活函数替换、注意力模式优化等
-
-不是所有改进都是惊天动地的大发现吗?不是。大部分是小优化堆叠出来的。但这 20 个有效改进,靠人手动做要花几周——agent 用 48 小时跑完了。
+大部分是小优化堆叠出来的。真正有用的是 loop 本身:固定预算、完整实验日志,以及"只保留已验证改进"的规则。
### 最值得注意的细节:loop 是用英文写的,不是用代码。
@@ -399,7 +395,7 @@ loop 跑得快的时候,你很容易跳过验证。"看起来没问题"不等
### 2. Comprehension Rot(理解腐烂)
-loop 出代码的速度越快,你对自己代码库的理解就越跟不上。Cherny 的团队 80% 的代码是 agent 写的——这意味着一个团队大部分代码不是人写的。如果不读不用,你对系统的理解会持续衰减。**快速跑 loop 的前提是快速读结果。**
+loop 出代码的速度越快,你对自己代码库的理解就越跟不上。一个 loop 合并了上百个 PR,团队要读这些 PR、审查真正重要的 diff、继续亲自使用这些代码,让心智模型跟上代码。**快速跑 loop 的前提是快速读结果。**
### 3. Cognitive Surrender(认知投降)
@@ -407,11 +403,11 @@ loop 出代码的速度越快,你对自己代码库的理解就越跟不上。
### 4. Token Blowout(令牌爆炸)
-loop 的每一次迭代都会积累更多上下文。代码写过了,错误遇到了,决策做过了。如果不做上下文压缩,prompt size 会随着迭代次数近似平方增长。Codex 的解决方案是自动 context compaction——用一个专门的 API 将老的对话轮次压缩成加密的内容摘要,保留关键知识,丢弃冗余细节。这是每个 loop 设计之初就要考虑的工程问题。
+loop 的每一次迭代都会积累更多上下文。代码写过了,错误遇到了,决策做过了。当每一轮只新增近似固定数量的内容时,单轮看到的历史长度随轮数近似线性增长;如果系统每一轮都重新处理完整历史,N 轮的累计输入量才近似二次增长。Codex 的解决方案是自动 context compaction——用一个专门的 API 将老的对话轮次压缩成加密的内容摘要,保留关键知识,丢弃冗余细节。这是每个 loop 设计之初就要考虑的工程问题。
## 从零构建你的第一个 Loop
-不需要一上来就搭一个 Stripe 级别、每周合并 1,300 个 PR 的系统。从最小可行的版本开始。
+不需要一开始就搭一个高吞吐的流水线。从最小可行的版本开始。
### 第一步:选一个重复发生的任务
diff --git a/docs/zh/lectures/lecture-14-graph-engineering/index.md b/docs/zh/lectures/lecture-14-graph-engineering/index.md
index 55377ba..80f2d68 100644
--- a/docs/zh/lectures/lecture-14-graph-engineering/index.md
+++ b/docs/zh/lectures/lecture-14-graph-engineering/index.md
@@ -9,7 +9,7 @@
> "我们还在谈 Loop,还是已经转向 Graph 了?"
-一条推,一天内就拿到约 57 万浏览,到月底涨到约 300 万。几小时后,机器学习工程师 Hamel Husain 发了一篇题为《Loop Engineering Is Dead. Enter Graph Engineering》的文章——正文只有一张写着 "Stop it" 的动图——又拿了约 68 万浏览。
+一条推。几小时后,机器学习工程师 Hamel Husain 发了一篇题为《Loop Engineering Is Dead. Enter Graph Engineering》的文章——正文只有一张写着 "Stop it" 的动图。
更耐人寻味的是:**这两个人都是当玩笑发的。** 一个在讽刺行业每六周发明一个新名词,一个在顺着这个梗一捧一逗。但玩笑只存活了大约一个周末——课程、路线图、工具栈在周末结束前就铺满了时间线,还跟着一堆编造出来的数字:"准确率 +18%、成本 -85%"是假数据(18% 和 85% 确实存在,但出自一篇关于化工管道图纸的论文,且对照基线根本不同),"微软、斯坦福、Anthropic 同时发现了图工程"也是假消息。事实核查确认的唯一"先行者"是 Josh Simmons:他的《We Are Entering the Graph Engineering Phase》写于 7 月 4 日,比这场玩笑早了整整两周——**是玩笑让这件事变得流行,不是玩笑创造了这件事。**
@@ -257,11 +257,11 @@ run(graph, entry={"requirements": "修复登录页 bug"}, thread="session-1")
## 开源项目:发布后才有的,发布前就有的
-先划清界限:**Graph Engineering 是 2026 年 7 月 18 日之后才有的名字。** 在那之前开源的框架,都不是"Graph Engineering 发布后的项目"。真正在概念爆火后、直接以这个名字出现的开源项目,截至 2026 年 8 月初,站得住的只有一个:
+**Graph Engineering 这个名字出现在 2026 年 7 月 18 日之后;此前开源的框架属于更早的图/工作流工具。** 一个直接在名字上使用 Graph Engineering 的项目是 GraphARC:
**概念发布后才有的**
-- [GraphArc](https://github.com/CodeGraphContext/grapharc)(2026-08-02):自称"Graph Engineering 的第一个实时实现"。它把 agent 执行从埋在日志里的 trace 变成一张**可交互的实时编排图**——每个 agent、每条依赖、每个决策点都画出来,在执行前可视化整张图,你确认(甚至可以拿手机看)之后再放行。作者背景是给 4000+ 开发者做图工具,方向是"可观测、可调试、可工程化"。非常新,功能还在早期。
+- [GraphARC](https://github.com/CodeGraphContext/GraphARC)(2026 年 7 月创建):自称"an end to end implementation of Graph Engineering as proposed by Andrew NG and Peter Steinberger"。它是一个早期阶段的 Python 项目。有用的做法是读它的编排模型,判断这套方法是否适合你的工作流。
**概念发布前就有的(它们不叫 Graph Engineering,但它们才是你构建时要用的)**
@@ -325,7 +325,7 @@ run(graph, entry={"requirements": "修复登录页 bug"}, thread="session-1")
- [goddaehee: Graph Engineering 事实核查(韩语,2026-07-30)](https://goddaehee.tistory.com/628) — 最完整的事实核查:玩笑起源时间线、假数字拆解、LangGraph 数据、Hacker News 热度对比
- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — 比那场玩笑早两周的严肃文章
- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — 官方回应:"不是新想法,是既有方法的最新名字";LangGraph 月下载 6500 万+
-- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — 热词传播数据(首发推文 57.5 万浏览)
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — 对这个词如何传播的叙述
- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — 七个主流开源框架的横向对比:LangGraph、CrewAI、Microsoft Agent Framework、LlamaIndex、Google ADK、OpenAI Agents SDK、Mastra
- [LangGraph 官方文档](https://docs.langchain.com/oss/python/langgraph/graph-api) — "Nodes do the work, edges tell what to do next";节点和边的精确定义,构建图的第一手参考
- [Anthropic: Building Effective Agents (Dec 2024)](https://www.anthropic.com/engineering/building-effective-agents) — 五种模式,画出来就是图;workflow vs agent 的权威区分