Harness engineering beginner tutorial, from 0 to 1
TypeScript agentagenticagentic-aiaiai-agentai-agentsdshdsh-pluginharnessharness-engineeringharness-frameworkllm
docs: complete course evidence audit and label illustrative results
sanbuphy9fb48af904ac
diff --git a/docs/.vitepress/anchor-map.json b/docs/.vitepress/anchor-map.jsonindex d26b921..d77a738 100644--- a/docs/.vitepress/anchor-map.json+++ b/docs/.vitepress/anchor-map.json@@ -247,7 +247,7 @@"key-terminology","when-things-fail-fix-the-harness-first","the-million-line-experiment",- "a-more-down-to-earth-example",+ "illustrative-example","key-takeaways","further-reading","exercises"@@ -320,7 +320,7 @@"start-with-an-analogy","core-concepts","the-five-subsystem-harness-model",- "a-team-s-real-story",+ "illustrative-example","key-takeaways","further-reading","exercises"@@ -669,7 +669,7 @@"what-happens-when-you-mix-them","core-concepts","how-to-do-initialization-right",- "real-world-example",+ "illustrative-example","key-takeaways","further-reading","exercises"@@ -770,7 +770,7 @@"_2-define-explicit-completion-evidence-for-every-task","_3-externalize-the-scope-surface","_4-monitor-verified-completion-rate",- "real-world-case",+ "illustrative-example","key-takeaways","further-reading","exercises"@@ -849,7 +849,7 @@"_2-let-the-harness-control-state-transitions","_3-write-the-rules-in-claude-md","_4-calibrate-granularity",- "real-world-case",+ "illustrative-example","key-takeaways","further-reading","exercises"@@ -930,7 +930,7 @@"_2-build-a-three-layer-termination-validation","_3-provide-actionable-error-feedback-to-the-agent","_4-capture-runtime-signals",- "real-world-case",+ "illustrative-example","key-takeaways","further-reading","exercises"@@ -1032,7 +1032,7 @@"_2-turn-architectural-rules-into-executable-checks","_3-design-agent-oriented-error-messages","_4-establish-a-review-feedback-promotion-process",- "real-world-case",+ "illustrative-example","key-takeaways","further-reading","exercises"@@ -1125,7 +1125,7 @@"ids": ["lecture-11-making-the-agent-s-runtime-observable","the-real-cost-of-missing-observability",- "a-real-claude-code-scenario",+ "illustrative-example","layered-observability","core-concepts","why-agents-can-t-solve-this-themselves",@@ -1237,7 +1237,7 @@"_4-periodically-simplify-the-harness","_5-cleanup-operations-must-be-idempotent","_6-high-throughput-changes-the-merge-philosophy",- "real-world-case",+ "illustrative-example","key-takeaways","further-reading","exercises"diff --git a/docs/ar/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/ar/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex 552328c..7e618b6 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,17 +9,30 @@غريزتك الأولى؟ "هذا النموذج ليس جيدًا بما يكفي. حان وقت الترقية." تمهل. قبل أن تمد يدك إلى محفظتك، فكّر في احتمال أن المشكلة ليست في النموذج أصلًا.-لننظر إلى بعض الأرقام. بحلول أواخر عام 2025، كانت أقوى وكلاء البرمجة على SWE-bench Verified تحقق تقريبًا 50-60%. وهذا على مهام مختارة بعناية، مع أوصاف Issues واضحة وحالات اختبار موجودة. انقل الأمر إلى بيئة تطويرك اليومية - متطلبات غامضة، لا اختبارات جاهزة، وقواعد عمل ضمنية مبعثرة في كل مكان - وستنخفض هذه النسبة أكثر.+Claude Sonnet 4.5 · 2025-09-29 · SWE-bench Verified++| Score | Tasks | Trials | Scaffold |+| --- | --- | --- | --- |+| 77.2% | 500 | 10 | bash + string replacement |++نتائج الإنتاج لا تعزل سببًا واحدًا. درجات benchmark تخص النموذج وscaffold والبيانات وشروط التقييم المحددة. [Anthropic: methodology](https://www.anthropic.com/news/claude-sonnet-4-5)لكن خلف هذه الأرقام توجد حقيقة غير بديهية.## الحصان نفسه، مصائر مختلفة-أجرت Anthropic تجربة مضبوطة. المطالبة نفسها ("ابنِ صانع ألعاب ريترو ثنائية الأبعاد")، والنموذج نفسه (Opus 4.5). التشغيل الأول: عارٍ بلا دعم - 20 دقيقة، 9 دولارات، والميزات الأساسية للعبة لم تعمل إطلاقًا. التشغيل الثاني: Harness كامل (مخطط + مولد + مقيم في بنية من ثلاثة وكلاء) - 6 ساعات، 200 دولار، وأصبحت اللعبة قابلة للعب.+> النموذج والطلب متماثلان، لكن ميزانيتي الوقت والتكلفة مختلفتان. ليست تجربة متساوية الميزانية تعزل مكونًا واحدًا. عملت وظائف اللعب الأساسية مع بقاء عيوب. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++النموذج والطلب متماثلان، لكن ميزانيتي الوقت والتكلفة مختلفتان. ليست تجربة متساوية الميزانية تعزل مكونًا واحدًا. عملت وظائف اللعب الأساسية مع بقاء عيوب. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++| Opus 4.5 | Duration | USD |+| --- | --- | --- |+| Solo | 20 min | 9 |+| Full harness | 6 h | 200 |لم يغيروا النموذج. بقي Opus 4.5 هو Opus 4.5. ما تغيّر هو العدة الكاملة للفرس.-مقال OpenAI لعام 2025 عن هندسة الـ Harness يقولها بوضوح: ينتقل Codex في مستودع مجهز جيدًا بالـ Harness من "غير موثوق" إلى "موثوق". لاحظ الصياغة - ليست "أفضل قليلًا"، بل انتقال نوعي. مثل حصان أصيل: يمكنك ركوبه بلا عدة مناسبة، لكنك لن تذهب بعيدًا، ولن تتحرك بسرعة، والسقوط لن يكون مفاجأة. الـ Harness هو تلك العدة الكاملة - **كل ما في البنية الهندسية خارج أوزان النموذج.**+نتائج الإنتاج لا تعزل سببًا واحدًا. درجات benchmark تخص النموذج وscaffold والبيانات وشروط التقييم المحددة. [OpenAI: 2026-02-11](https://openai.com/index/harness-engineering/)## أين تتعطل الوكلاء فعليًا@@ -39,9 +52,9 @@مع هذه السيناريوهات في الذهن، لم تعد هذه المفاهيم مجرد مصطلحات:-- **Capability Gap**: الفجوة الكبيرة بين أداء النموذج على المعايير القياسية وأدائه في المهام الحقيقية. معدل نجاح 50-60% على SWE-bench Verified يعني أن قرابة نصف القضايا الحقيقية لا تُحل.+- نتائج الإنتاج لا تعزل سببًا واحدًا. درجات benchmark تخص النموذج وscaffold والبيانات وشروط التقييم المحددة.- **Harness**: كل ما هو خارج النموذج - التعليمات، الأدوات، البيئة، إدارة الحالة، وتغذية التحقق الراجعة. إن لم يكن من أوزان النموذج فهو جزء من الـ Harness. هذه هي "العدة الكاملة" التي نتحدث عنها.-- **Harness-Induced Failure**: لدى النموذج قدرة كافية، لكن بيئة التنفيذ فيها عيوب بنيوية. تجربة Anthropic المضبوطة أثبتت ذلك بالفعل.+- **Harness-Induced Failure**: لدى النموذج قدرة كافية، لكن بيئة التنفيذ فيها عيوب بنيوية. تجربة- **Verification Gap**: الفجوة بين ثقة الوكيل في مخرجاته والصحة الفعلية. يقول الوكيل "انتهيت" وهو لم ينتهِ - وهذا هو نمط الفشل الأكثر شيوعًا.- **Diagnostic Loop**: نفّذ، لاحظ الفشل، انسبه إلى طبقة Harness محددة، أصلح تلك الطبقة، ثم نفّذ مرة أخرى. هذه هي المنهجية الأساسية لهندسة الـ Harness.- **Definition of Done**: مجموعة شروط قابلة للتحقق آليًا - الاختبارات تمر، الـ lint نظيف، وفحوصات الأنواع ناجحة. من دون Definition of Done صريحة، سيخترع الوكيل تعريفه الخاص.@@ -72,17 +85,19 @@ Completion criteria:## تجربة المليون سطر-أجرت OpenAI في 2025 تجربة جريئة: استخدام Codex لبناء منتج داخلي كامل من مستودع Git فارغ. بعد خمسة أشهر، احتوى المستودع على نحو مليون سطر كود - منطق تطبيق، بنية تحتية، أدوات، توثيق، وأدوات تطوير داخلية - كلها مولدة بواسطة الوكلاء. قاد ثلاثة مهندسين Codex، وفتحوا ودمجوا نحو 1,500 Pull Request. بمعدل 3.5 Pull Request لكل شخص يوميًا.+أجرت OpenAI في 2025 تجربة جريئة: استخدام Codex لبناء منتج داخلي كامل من مستودع Git فارغ. بعد خمسة أشهر، احتوى المستودع على نحو مليون سطر كود - منطق تطبيق، بنية تحتية، أدوات، توثيق، وأدوات تطوير داخلية - كلها مولدة بواسطة الوكلاء. قاد ثلاثة مهندسين Codex، وفتحوا ودمجوا نحو 1,500 Pull Request. بمعدل 3.5 Pull Request لكل شخص يوميًا. [OpenAI](https://openai.com/index/harness-engineering/)-القيد الأساسي: **البشر لا يكتبون الكود مباشرة أبدًا.** لم تكن هذه حيلة، بل صُممت لإجبار الفريق على فهم ما يتغير عندما لا تكون وظيفة المهندس الأساسية هي كتابة الكود، بل تصميم البيئات، وصياغة النية، وبناء حلقات التغذية الراجعة.+نتائج الإنتاج لا تعزل سببًا واحدًا. درجات benchmark تخص النموذج وscaffold والبيانات وشروط التقييم المحددة.كان التقدم في البداية أبطأ من المتوقع. ليس لأن Codex لم يكن قادرًا، بل لأن البيئة لم تكن مكتملة بما يكفي - كان الوكيل يفتقد الأدوات، والتجريدات، والبنى الداخلية اللازمة للتقدم نحو أهداف عالية المستوى. أصبح عمل المهندسين: تقسيم الأهداف الكبيرة إلى لبنات صغيرة (تصميم، كود، مراجعة، اختبار)، وترك الوكيل يركبها، ثم استخدام تلك اللبنات لفتح مهام أكثر تعقيدًا. عندما يفشل شيء، لم يكن الحل تقريبًا "حاول بجهد أكبر"، بل "ما القدرة التي يفتقدها الوكيل، وكيف نجعلها مفهومة وقابلة للتنفيذ؟"-تثبت هذه التجربة مباشرة الأطروحة المركزية لهذه المحاضرة: **النموذج نفسه ينتج مخرجات مختلفة جوهريًا في بيئة عارية مقارنة ببيئة ذات Harness كامل.** النموذج لم يتغير. البيئة تغيرت.+نتائج الإنتاج لا تعزل سببًا واحدًا. درجات benchmark تخص النموذج وscaffold والبيانات وشروط التقييم المحددة.> المصدر: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)-## مثال أقرب إلى الواقع+## مثال تعليمي++> مثال تعليمي: هذا السيناريو وأرقامه افتراضات لشرح الآلية، وليست قياسات من تجربة منشورة.استخدم فريق Claude Sonnet لإضافة نقطة API جديدة إلى تطبيق ويب Python متوسط الحجم (FastAPI + PostgreSQL + Redis، نحو 15,000 سطر كود).@@ -108,6 +123,8 @@ Completion criteria:- [SWE-bench Leaderboard](https://www.swebench.com/)- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)+- [Anthropic: Sonnet 4.5 SWE-bench methodology, 2025-09-29](https://www.anthropic.com/news/claude-sonnet-4-5)+## تمارين1. **تجربة مقارنة**: اختر قاعدة كود تعرفها جيدًا ومهمة تعديل غير تافهة. شغّل الوكيل أولًا بلا دعم Harness وسجل الإخفاقات. ثم أضف `AGENTS.md` يحتوي على أوامر تحقق صريحة وشغّل الوكيل نفسه مرة أخرى. قارن النتائج، وانسب كل فشل إلى إحدى طبقات الدفاع الخمس.diff --git a/docs/ar/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/ar/lectures/lecture-02-what-a-harness-actually-is/index.mdindex d567ef9..dfe82f8 100644--- a/docs/ar/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/ar/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -70,7 +70,9 @@ Verification commands:**قياس قيمة مكونات harness**: استخدم تجربة تفكيك المكونات مع إبقاء النموذج ثابتًا. أبقِ النموذج ثابتًا، وأزل الأنظمة الفرعية واحدًا تلو الآخر، وقِس أي إزالة تسبب أكبر انخفاض في الأداء. أكبر انخفاض يحدد المكون صاحب أعلى مساهمة حدية في تلك المهمة؛ لكنه لا يحدد عنق الزجاجة تلقائيًا. والانخفاض القريب من الصفر يحتاج تفسيرًا أيضًا: قد يكون المكون زائدًا، أو مصممًا بشكل ضعيف، أو لم تُفعّله هذه المهمة بما يكفي. لتشخيص عنق الزجاجة، ابدأ بسجلات الفشل ونسب الأسباب، ثم استخدم تجربة التفكيك كدليل مساعد: هل سبب الفشل مهمة غير واضحة، سياق غير كافٍ، بيئة غير قابلة لإعادة الإنتاج، غياب تغذية التحقق الراجعة، أم انقطاع إدارة الحالة؟-## قصة فريق حقيقية+## مثال تعليمي++> مثال تعليمي: هذا السيناريو وأرقامه افتراضات لشرح الآلية، وليست قياسات من تجربة منشورة.استخدم فريق GPT-4o على تطبيق واجهة أمامية بـ TypeScript + React (~20,000 سطر كود). مرّوا بأربع مراحل — بشكل أساسي إضافة معدات المطبخ قطعة قطعة:diff --git a/docs/ar/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/ar/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdindex 2fe7745..4b3b330 100644--- a/docs/ar/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md+++ b/docs/ar/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -5,6 +5,8 @@# المحاضرة 03. اجعل المستودع مصدر الحقيقة الوحيد+> إرشادات هندسية: الحدود الرقمية قيم تعليمية قابلة للتعديل، لا عتبات مثبتة تجريبيًا. عدد الرموز يعتمد على tokenizer والمحتوى، لا عدد الأسطر وحده.+قرارات المعمارية في فريقك مبعثرة بين Confluence وSlack وJira ورؤوس بعض المهندسين الكبار. بالنسبة للبشر، هذا يعمل بالكاد: يمكنك سؤال زميل، أو البحث في سجل المحادثات، أو التنقيب في الوثائق. وإذا فشل كل شيء، يمكنك الإمساك بشخص في غرفة الاستراحة. لكن بالنسبة إلى وكيل ذكاء اصطناعي، فإن المعلومات غير الموجودة في المستودع لا وجود لها ببساطة.هذا ليس مبالغة. فكّر في مدخلات الوكيل الفعلية: مطالبات النظام ووصف المهمة، محتوى الملفات من المستودع، ومخرجات تنفيذ الأدوات. هذا كل شيء. سجل Slack، وتذاكر Jira، وصفحات Confluence، وقرار المعمارية الذي ناقشته مع زميل على القهوة بعد ظهر الجمعة - لا يرى الوكيل شيئًا من ذلك. لا يستطيع "الذهاب ليسأل شخصًا" ولا "البحث في سجل المحادثة". إنه مهندس محبوس داخل المستودع؛ كل ما هو خارجه لا يعرف عنه شيئًا.diff --git a/docs/ar/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/ar/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdindex baed4fe..2562e7f 100644--- a/docs/ar/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md+++ b/docs/ar/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -5,6 +5,8 @@# المحاضرة 04. قسّم التعليمات عبر ملفات+> إرشادات هندسية: الحدود الرقمية قيم تعليمية قابلة للتعديل، لا عتبات مثبتة تجريبيًا. عدد الرموز يعتمد على tokenizer والمحتوى، لا عدد الأسطر وحده.+أخذت هندسة الـ Harness بجدية. أنشأت ملف `AGENTS.md` ووضعت فيه كل قاعدة، وكل قيد، وكل درس تعلمته يخطر في بالك. بعد شهر أصبح الملف 300 سطر، وبعد شهرين 450 سطرًا، وبعد ثلاثة أشهر 600 سطر. ثم لاحظت أن أداء الوكيل يزداد سوءًا: في إصلاح عيب بسيط، يستهلك الوكيل قدرًا كبيرًا من السياق في معالجة تعليمات نشر غير ذات صلة؛ قيد أمني حرج مدفون في السطر 300 يتم تجاهله تمامًا؛ وثلاث قواعد متناقضة لأسلوب الكود تجعل الوكيل يختار واحدة عشوائيًا كل مرة.هذا هو فخ "ملف التعليمات العملاق". يشبه حقيبة سفر محشوة أكثر من اللازم: كل شيء يبدو مفيدًا، فتضغطه داخلها حتى توشك السحّابة أن تنفجر. للعثور على قطعة ملابس بديلة، عليك إفراغ الحقيبة كلها. تحمل حقيبة ممتلئة، لكنك تستخدم ربما ثلث ما بداخلها فقط.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.mdindex 599d422..69c592d 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@@ -5,6 +5,8 @@# المحاضرة 05. حافظ على السياق عبر الجلسات+> إرشادات هندسية: الحدود الرقمية قيم تعليمية قابلة للتعديل، لا عتبات مثبتة تجريبيًا. عدد الرموز يعتمد على tokenizer والمحتوى، لا عدد الأسطر وحده.+تطلب من Claude Code تنفيذ ميزة كاملة. يعمل لمدة 30 دقيقة، وينجز معظم العمل، لكن السياق ينفد. تبدأ جلسة جديدة للاستمرار — وتكتشف أنه لا يتذكر ما القرارات التي اتُخذت في المرة السابقة، ولا لماذا خُيرت الخيار A على الخيار B، ولا أي الملفات عدّلت بالفعل، ولا في أي حالة تكون الاختبارات. يقضي 15 دقيقة في إعادة استكشاف المشروع، وقد يكون غير متسق مع النهج السابق.تخيل لو كنت حرفيًا ينسى كل شيء كل صباح عند الاستيقاظ. سيتعين عليك إعادة التعرف على موقع البناء بالكامل — أي جدار نصف مكتمل، ولماذا اختيرت الطوب الأحمر بدلاً من الأزرق، وأين وصلت مسارات السباكة. والأخطر، قد تقتلع نافذة رُكّبت بالفعل أمس، ببساطة لأنك لم تتذكر أنه تم إنجازها.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.mdindex 2394b6d..b6d6094 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@@ -5,6 +5,8 @@# المحاضرة 06. هيئ قبل كل جلسة وكيل+> إرشادات هندسية: الحدود الرقمية قيم تعليمية قابلة للتعديل، لا عتبات مثبتة تجريبيًا. عدد الرموز يعتمد على tokenizer والمحتوى، لا عدد الأسطر وحده.+تبدأ جلسة وكيل جديدة وتقول "أضف ميزة بحث." يقفز مباشرة إلى البرمجة — حماس مُعجب. بعد 20 دقيقة يكتشف أن إطار الاختبار غير مضبوط بشكل صحيح، يقضي 10 دقائق أخرى في إصلاح ذلك، ثم تنسيق نص ترحيل قاعدة البيانات خاطئ، المزيد من العبث. ميزة البحث تُضاف في النهاية، لكن الجلسة كلها كانت غير فعالة — معظم الوقت ذهب إلى "اكتشاف كيف يعمل هذا المشروع" بدلاً من كتابة ميزة البحث.النهج الأفضل: قبل السماح للوكيل ببدء العمل، استخدم مرحلة منفصلة لتجهيز البيئة الأساسية، واجعل أوامر التحقق ناجحة، وهيكل المشروع مفهومًا. الأمر أشهر ببناء منزل — لا تصب الأساس وترفع الجدران في وقت واحد. إذا فعلت، ترتفع الجدران قبل أن يتصلب الأساس، ويجب هدم المبنى بالكامل والبدء من جديد. صب الأساس أولًا، دعه يتصلب، ثم ابنِ الجدران — نظيف وفعال.@@ -37,6 +39,8 @@ flowchart TB## ماذا يحدث عند خلطهما+> مثال تعليمي: هذا السيناريو وأرقامه افتراضات لشرح الآلية، وليست قياسات من تجربة منشورة.+المشكلة الأكثر مباشرة: الأساس لا يتصلب بشكل صحيح. الوكيل ينفق 80% من جهده على كود الميزات و20% في إعداد بعض البنية التحتية بشكل عابر. إطار الاختبار مضبوط لكن لم يُتحقق منه قط، وقواعد lint محددة لكنها متساهلة جدًا، ولم يُنشأ ملف تقدم. هذه العيوب ليست واضحة في الجلسة الأولى (لأن الوكيل لا يزال يتذكر ما فعله)، لكنها تظهر في الجلسة الثانية — الوكيل الجديد لا يعرف كيف يُشغّل، أو يختبر، أو أين تقف الأمور. أساس رديء، مبنى مهتز.تكلفة أخفى هي "التراكم غير المُتحقَق" — كود الميزات المكتوب قبل ضبط إطار الاختبار هو كود بدون تحقق. عندما تعود أخيرًا لإضافة اختبارات لهذا الكود، قد تكتشف أن التصميم كان خاطئًا من البداية — لو كنت تعرف، لطبّقته بشكل مختلف. مثل تبليط سطح خرسانة رطبة — عندما تكتشف أن الأرضية غير مستوية، يجب نزع كل البلاط وإعادة العمل.@@ -45,7 +49,7 @@ flowchart TBالمشكلة الأكثر تجاهلًا هي ألغام الافتراضات الضمنية. القرارات التي يتخذها الوكيل أثناء التهيئة (أي إطار اختبار، كيف تنظيم الأدلة، إدارة التبعيات) — إذا لم تُسجَّل صراحةً، لا يمكن للجلسات اللاحقة فهم هذه الخيارات. الأسوأ، أن الجلسات اللاحقة قد تتخذ خيارات متناقضة. طاقم البناء الأول استخدم أساسًا خرسانيًا، والطاقم الثاني لا يعرف وغرس فيه أوتادًا خشبية — الأساس يتشقق.-أبحاث Anthropic لتطوير التطبيقات طويلة التشغيل توصي صراحةً بفصل التهيئة عن التنفيذ. بياناتهم التجريبية: المشاريع التي استخدمت مرحلة تهيئة مخصصة أظهرت معدلات إكمال ميزات أعلى بنسبة 31% في سيناريوهات الجلسات المتعددة مقارنة بالأساليب المختلطة. الرؤية الأساسية — الوقت المستثمر في مرحلة التهيئة يُسترد بالكامل في الجلسات الـ 3-4 التالية. كلما كان الأساس أصلب، ارتفعت الجدران أسرع.+[Anthropic: initializer / coding agent](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)دليل OpenAI Codex لهندسة harness يُؤكد أيضًا على مبدأ "المستودع كسجل عمليات" — أَسِّس هيكل عمليات واضحًا من التشغيل الأول، وإلا ستضطر كل جلسة جديدة إلى استنتاج اصطلاحات المشروع من جديد.@@ -122,7 +126,9 @@ flowchart TB- [ ] Everything committed to git```-## مثال من الواقع+## مثال تعليمي++> مثال تعليمي: هذا السيناريو وأرقامه افتراضات لشرح الآلية، وليست قياسات من تجربة منشورة.أسلوبا تهيئة لمشروع واجهة أمامية بـ React: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.mdindex c00c9f1..a70957b 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@@ -5,6 +5,8 @@# المحاضرة 07. ارسم حدود مهمة واضحة للوكلاء+> إرشادات هندسية: الحدود الرقمية قيم تعليمية قابلة للتعديل، لا عتبات مثبتة تجريبيًا. عدد الرموز يعتمد على tokenizer والمحتوى، لا عدد الأسطر وحده.+تطلب من Claude Code "إضافة مصادقة المستخدم إلى هذا المشروع"، فيبدأ بتعديل مخطط قاعدة البيانات، وكتابة المسارات، وتغيير مكونات الواجهة الأمامية، و — أثناء وجوده في ذلك — إعادة هيكلة middleware معالجة الأخطاء. بعد ساعتين تتفقد: 12 ملفًا معدّلًا، 800 سطر كود جديد، ولا ميزة واحدة تعمل من البداية للنهاية.العض أكثر مما تستطيع مضغه — هذا القول ينطبق على وكلاء الذكاء الاصطناعي بشكل خاص. الوكلاء يولدون بدافع "فعل القليل الإضافي" — يرون أشياء مرتبطة فيتعاملون معها في الطريق، مثل شخص يذهب إلى السوبرماركت لزجاجة صلصة صويا ويخرج يدفع عربة كاملة. المشكلة هي أن البشر الذين يشترون أكثر مما ينب مضيعون للمال فقط؛ الوكلاء الذين يفعلون أشياء كثيرة في وقت واحد يعني أنه لا شيء يُنجز بشكل صحيح.@@ -26,7 +28,7 @@بعد ست خطوات، كل واحدة نصف مكتملة. بدون تحقق شامل، وارتباط معقد بين الكود غير المكتمل، والجلسة التالية التي ستلتقط القطع ستكون ضائعة تمامًا. مثل شخص يطبخ ستة أطباق في وقت واحد — كل طبق في المقلاة لكن لم يُقدم أي منها. جميعها تحترق.-البيانات التجريبية من Anthropic تدعم هذا مباشرة: الوكلاء الذين يستخدمون استراتيجية "الخطوة التالية الصغيرة" (ما يعادل WIP=1) يُظهرون معدل إكمال مهام أعلى بنسبة 37% من الوكلاء الذين يستخدمون prompts واسعة. والأكثر إثارة للاهتمام، أن عدد أسطر الكود التي يُنتجها الوكلاء مرتبط ارتباطًا سلبيًا ضعيفًا مع إكمال الميزات الفعلي — كود أكثر مكتوب، ميزات أقل مُنجزة. العض أكثر مما تستطيع مضغه، مُثبت بالبيانات.+[Anthropic: incremental feature work](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## سير عمل WIP=1@@ -100,7 +102,9 @@ F01: User Registrationيجب على harness تتبع VCR (معدل الإكمال المُتحقَق) = مهام مُتحقَقة / مهام مُنشطة باستمرار. احظر تنشيط مهام جديدة عندما يكون VCR < 1.0.-## حالة من الواقع+## مثال تعليمي++> مثال تعليمي: هذا السيناريو وأرقامه افتراضات لشرح الآلية، وليست قياسات من تجربة منشورة.مشروع REST API مع 8 ميزات، استراتيجيتان مقارنتان: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.mdindex 8ee7907..c275987 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@@ -5,6 +5,8 @@# المحاضرة 08. استخدم قوائم الميزات لتقييد الوكيل+> إرشادات هندسية: الحدود الرقمية قيم تعليمية قابلة للتعديل، لا عتبات مثبتة تجريبيًا. عدد الرموز يعتمد على tokenizer والمحتوى، لا عدد الأسطر وحده.+تطلب من agent بناء موقع تجارة إلكترونية. بعد أن ينتهي، يخبرك "انتهيت". تنظر إلى الكود — مصادقة المستخدم تعمل، لكن زر الدفع في سلة التسوق لا يفعل شيئًا، وتدفق الدفع غير متصل على الإطلاق. المشكلة: لم تخبره أبدًا ما يعنيه "انتهيت"، لذا استخدم معياره الخاص — "كتبت الكثير من الكود ويبدو مكتملًا إلى حد ما."قوائم الميزات، في نظر الكثير من الناس، هي مجرد مذكرة — اكتب الأشياء حتى لا تنساها، ثم ألقِها جانبًا. لكن في عالم harness، قائمة الميزات ليست مذكرة للبشر — إنها العمود الفقري لـ harness بالكامل. يعتمد المجدول عليها لاختيار المهام، ويعتمد المدقق عليها للحكم على الاكتمال، ويعتمد مُعدّ التسليم عليها لإنشاء الملخصات. اكسر العمود الفقري والجسم كله يشل.@@ -22,7 +24,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)## آلة حالة الميزات@@ -103,7 +105,9 @@ flowchart LRيجب أن يكون نطاق كل عنصر ميزة "قابل للإنجاز في جلسة واحدة." واسع جدًا ولن ينتهي؛ ضيق جدًا وتزداد تكلفة الإدارة. "يمكن للمستخدم إضافة عناصر إلى السلة" دقة جيدة. "تنفيذ سلة التسوق" واسع جدًا. "إنشاء حقل الاسم في نموذج Cart" ضيق جدًا. مثل تقطيع شريحة لحم — ليس القطعة كاملة، وليست لحماً مفروماً.-## حالة من العالم الحقيقي+## مثال تعليمي++> مثال تعليمي: هذا السيناريو وأرقامه افتراضات لشرح الآلية، وليست قياسات من تجربة منشورة.منصة تجارة إلكترونية مع 10 ميزات. مقارنة نهجي تتبع:@@ -111,8 +115,6 @@ flowchart LR**وضع العمود الفقري**: كل ميزة لها حالة واضحة وأمر تحقق. تقرأ الجلسة الجديدة قائمة الميزات وتعرف في 3 دقائق: F01-F05 `passing`، F06 `active`، F07-F10 `not_started`. تستأنف من F06 مباشرة، صيانة صفرية.-النتيجة المُقاسة: تُظهر المشاريع التي تستخدم قوائم ميزات منظمة معدل إنجاز ميزات أعلى بنسبة 45% من التتبع الحر، مع صفر عمليات تنفيذ مكررة.-## الخلاصات الأساسية- **قوائم الميزات هي العمود الفقري لـ harness**، وليست مذكرات للبشر. المجدول والمدقق ومُعدّ التسليم يعتمدون عليها جميعًا.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.mdindex 1920fcc..7c7db3c 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@@ -5,6 +5,8 @@# المحاضرة 09. منع الوكلاء من إعلان النجاح مبكرًا+> إرشادات هندسية: الحدود الرقمية قيم تعليمية قابلة للتعديل، لا عتبات مثبتة تجريبيًا. عدد الرموز يعتمد على tokenizer والمحتوى، لا عدد الأسطر وحده.+تطلب من agent تنفيذ ميزة "إعادة تعيين كلمة المرور". يُعدّل مخطط قاعدة البيانات، ويكتب نقطة نهاية API، ويضيف قالب البريد الإلكتروني، ويشغّل اختبارات الوحدة (جميعها تجتاز)، ثم يخبرك بثقة "انتهيت." عندما تحاول تشغيله فعليًا — لا يمكن إرسال رابط إعادة تعيين كلمة المرور (نقص إعدادات خدمة البريد)، تفشل عملية ترحيل قاعدة البيانات في منتصف الطريق (عدم اتساق المخطط)، ولم يتم تنفيذ التدفق الشامل ولو لمرة واحدة.هذا الشعور لا ينبغي أن يكون غير مألوف — إنه مثل ملء ورقة الامتحان بالكامل، وأن تكون أول من يسلمها بثقة، فقط لترسب عند خروج الدرجات. مجرد أن الورقة ممتلئة لا يعني أن الإجابات صحيحة.@@ -13,6 +15,8 @@## المنحدر الزلق+> النموذج والطلب متماثلان، لكن ميزانيتي الوقت والتكلفة مختلفتان. ليست تجربة متساوية الميزانية تعزل مكونًا واحدًا. عملت وظائف اللعب الأساسية مع بقاء عيوب. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)+إعلانات الاكتمال المبكر تتبع دائمًا تقريبًا نفس النمط: الكود يبدو جيدًا — البنية صحيحة، المنطق يبدو معقولًا، والتحليل الثابت لا يظهر أخطاء واضحة. لكن harness لا يفرض تحققًا شاملاً قائمًا على التنفيذ، لذا يتخطى agent التشغيل الفعلي أو يشغّل اختبارات جزئية فقط. يشغّل اختبارات الوحدة لكن يتخطى اختبارات التكامل؛ يشغّل الاختبارات لكن لا يتحقق من التغطية. في النهاية، "الكود يبدو جيدًا" يُتخذ كدليل على أن "الميزة مكتملة." وتُسلم ورقة الامتحان.تُفقد المعلومات في كل خطوة. من مواصفات المهام إلى تنفيذ الكود إلى السلوك وقت التشغيل، كل تحول يمكن أن يُدخل انحيازًا، وكل تحقق متخطع يزيد من تفاقم عدم تماثل المعلومات.@@ -111,7 +115,9 @@ agent تقييم مستقل، مُضبوط خصيصًا ليكون "صارمًا- هل كانت عمليات كتابة قاعدة البيانات وعمليات الملفات والآثار الجانبية الأخرى صحيحة؟- هل تم تنظيف الموارد المؤقتة؟-## حالة من العالم الحقيقي+## مثال تعليمي++> مثال تعليمي: هذا السيناريو وأرقامه افتراضات لشرح الآلية، وليست قياسات من تجربة منشورة.**المهمة**: تنفيذ وظيفة إعادة تعيين كلمة مرور المستخدم. تتضمن عمليات قاعدة البيانات وإرسال البريد الإلكتروني وتعديلات نقطة نهاية API.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.mdindex c618bed..e0512ef 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@@ -5,6 +5,8 @@# المحاضرة 10. الاختبار end-to-end هو التحقق الحقيقي+> إرشادات هندسية: الحدود الرقمية قيم تعليمية قابلة للتعديل، لا عتبات مثبتة تجريبيًا. عدد الرموز يعتمد على tokenizer والمحتوى، لا عدد الأسطر وحده.+تطلب من agent إضافة ميزة تصدير ملفات إلى تطبيق Electron. يكتب مكوّن عرض (render process) وpreload script ومنطق طبقة الخدمة. اختبارات الوحدة لكل مكون تجتاز بشكل مثالي. يقول agent "انتهيت." عندما تنقر فعليًا على زر التصدير — تنسيق مسار الملف خاطئ، شريط التقدم لا يُحدَّث، وتصدير الملفات الكبيرة يسبب تسربًا في الذاكرة. خمسة عيوب في حدود المكونات، واختبارات الوحدة لم تكتشف أيًا منها.إنه مثل بروفة جوقة — كل جزء صوتي يبدو مثاليًا عند الغناء بشكل فردي، لكن عند الغناء معًا، السوبرانو أسرع بنصف نبضة من الباصات، والمرافقة بعيدة نصف نغمة عن اللحن الرئيسي. كل جزء "صحيح" بمفرده، لكن الكل غير متناغم.@@ -116,7 +118,9 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.reaفي كل مرة يُعثر على نوع جديد من أخطاء agent أثناء مراجعة الكود، حوّله إلى فحص آلي. بعد شهر، سيكون harness أقوى بكثير مما كان في بداية الشهر. إنه مثل ملاحظات بروفة الجوقة — تسجيل المشاكل الموجودة في كل بروفة حتى يمكن فحصها قبل البروفة التالية. بمرور الوقت، تنخفض الأخطاء الشائعة، وتصبح الموسيقى أكثر تناغمًا.-## حالة من العالم الحقيقي+## مثال تعليمي++> مثال تعليمي: هذا السيناريو وأرقامه افتراضات لشرح الآلية، وليست قياسات من تجربة منشورة.**المهمة**: تنفيذ ميزة تصدير ملفات في تطبيق Electron. تتضمن واجهة مستخدم عرض (render process) ووكيل نظام ملفات preload script وتحويل بيانات طبقة الخدمة.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.mdindex 9dc3ba6..5966d42 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@@ -32,7 +32,9 @@ flowchart LRVerdict --> Generator```-## لماذا يحدث هذا+## مثال تعليمي++> مثال تعليمي: هذا السيناريو وأرقامه افتراضات لشرح الآلية، وليست قياسات من تجربة منشورة.### التكلفة الحقيقية لغياب observability@@ -44,7 +46,7 @@ flowchart LR**تصبح المحاولات المتكررة تخمينات عمياء**: عندما لا يعرف الوكيل سبب الفشل، يكون اتجاه المحاولة التالية عشوائيًا. قد يصلح مسارات كود غير مرتبطة بينما يتجاهل السبب الجذري. كل محاولة عمياء تكلف tokens ووقتًا.-**انحدار معلومات handoff بين الجلسات**: عندما ينتقل عمل غير مكتمل إلى جلسة جديدة، يعني غياب observability أن الجلسة الجديدة يجب أن تشخص حالة النظام من الصفر. تشير ملاحظات Anthropic إلى أن هذا التشخيص المتكرر قد يستهلك 30-50% من وقت الجلسة.+سجل التقدم ونتائج التحقق في ملفات ذات إصدارات لتفحص الجلسة التالية الحالة. يشرح المصدر الآلية دون نسبة انخفاض زمن البدء. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)### سيناريو واقعي مع Claude Code@@ -116,7 +118,9 @@ flowchart LRأنشئ trace لكل جلسة harness، و span لكل مهمة، و sub-spans لكل خطوة تحقق. استخدم attributes قياسية لتسجيل المعلومات المهمة. هكذا يمكن دمج بيانات observability مع أدوات مثل Jaeger و Zipkin.-## حالة واقعية+## مثال تعليمي++> مثال تعليمي: هذا السيناريو وأرقامه افتراضات لشرح الآلية، وليست قياسات من تجربة منشورة.Harness يستخدم workflow من planner-generator-evaluator لتنفيذ "إضافة دعم dark mode":@@ -136,7 +140,7 @@ Harness يستخدم workflow من planner-generator-evaluator لتنفيذ "إ- **طبقتا observability ضروريتان**: إشارات runtime تشرح "ماذا حدث"، وآثار العملية تشرح "لماذا حدث بهذه الطريقة".- **Sprint contracts تسبق التنفيذ بالتوافق**، فتمنع بناء شيء سيرفضه evaluator فورًا لأسباب متوقعة.- **Rubrics تجعل التقييم قابلًا لإعادة الإنتاج**، بحيث يعطي مقيمون مختلفون درجات متقاربة لنفس الناتج.-- **غياب observability يهدر 30-50% من وقت الجلسة في تشخيص مكرر.**+- سجل التقدم ونتائج التحقق في ملفات ذات إصدارات لتفحص الجلسة التالية الحالة. يشرح المصدر الآلية دون نسبة انخفاض زمن البدء.## قراءات إضافية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.mdindex eb56c5c..cd4c4b0 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@@ -5,6 +5,8 @@# المحاضرة 12. اترك handoff نظيفًا في نهاية كل جلسة+> إرشادات هندسية: الحدود الرقمية قيم تعليمية قابلة للتعديل، لا عتبات مثبتة تجريبيًا. عدد الرموز يعتمد على tokenizer والمحتوى، لا عدد الأسطر وحده.+## ما المشكلة التي تحلها هذه المحاضرة؟يعمل agent طوال فترة بعد الظهر، يُعدّل 20 ملفًا، يُرسل الكود، تنتهي الجلسة. تبدأ جلسة agent التالية وتكتشف فورًا: البناء (build) مكسور، الاختبارات حمراء، ملفات التصحيح المؤقتة في كل مكان، قائمة الميزات لم تُحدَّث، والتقدم غير واضح تمامًا. تقضي الجلسة الجديدة أول 30 دقيقة فقط في محاولة معرفة "ماذا فعلت الجلسة السابقة فعليًا."@@ -54,6 +56,8 @@ flowchart LRتخبرنا قوانين ليهمان لتطور البرمجيات: الأنظمة التي تخضع لتغيير مستمر ستزداد حتمًا في التعقيد ما لم تُدار بشكل نشط. هذا صحيح بشكل خاص لوكلاء البرمجة بالذكاء الاصطناعي — كل جلسة تُدخل تغييرات، وبدون تنظيف عند الخروج، يتراكم الدين الفني بشكل أسي.+> مثال تعليمي: هذا السيناريو وأرقامه افتراضات لشرح الآلية، وليست قياسات من تجربة منشورة.+البيانات الحقيقية دالة. مشروع طُوّر باستخدام الوكلاء لمدة 12 أسبوعًا، بدون استراتيجية تنظيف:- الأسبوع 1: معدل اجتياز البناء 100%، معدل اجتياز الاختبارات 100%، بدء الجلسة الجديدة 5 دقائق@@ -66,8 +70,6 @@ flowchart LR- الأسبوع 1: 100%، 100%، 5 دقائق- الأسبوع 12: 97%، 95%، 9 دقائق-بعد 12 أسبوعًا: معدل اجتياز البناء يختلف بنسبة 29 نقطة مئوية، وقت بدء الجلسة الجديدة يختلف بنسبة 85%. هذا ليس نظريًا — إنه فرق مُلاحظ.-### الأبعاد الخمسة للحالة النظيفةالحالة النظيفة ليست مجرد "الكود يُبنى." إنها خمسة أبعاد تُقيَّم معًا:@@ -76,7 +78,7 @@ flowchart LR**بُعد الاختبار**: هل تجتاز جميع الاختبارات؟ بما فيها الاختبارات التي وُجدت قبل الجلسة — الجلسة مسؤولة عن عدم كسر الوظائف الموجودة. وينبغي التحقق في CI، وليس فقط "يعمل على جهازي."-**بُعد التقدم**: هل التقدم الحالي مُسجَّل في قطعة أثرية قابلة للقراءة آليًا؟ المهام الفرعية المكتملة مع معايير اجتيازها، المهام الفرعية قيد التقدم لكن غير المكتملة مع حالتها الحالية، المهام الفرعية التي لم تبدأ بعد. سجلات التقدم الجيدة تقلل 60-80% من وقت تشخيص بدء الجلسة.+سجل التقدم ونتائج التحقق في ملفات ذات إصدارات لتفحص الجلسة التالية الحالة. يشرح المصدر الآلية دون نسبة انخفاض زمن البدء. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)**بُعد القطع الأثرية**: هل توجد قطع أثرية مؤقتة قديمة أو غامضة؟ سجلات التصحيح، الملفات المؤقتة، الكود المُعلَّق، علامات TODO — كل هذه تزيد العبء المعرفي للجلسة التالية.@@ -152,7 +154,9 @@ git checkout -- .env.local # Restore to known statenpm run test # Verify cleanup didn't break anything```-## حالة من العالم الحقيقي+## مثال تعليمي++> مثال تعليمي: هذا السيناريو وأرقامه افتراضات لشرح الآلية، وليست قياسات من تجربة منشورة.تطبيق Electron طُوّر باستخدام الوكلاء على مدار 12 أسبوعًا، مقارنة نهجين:@@ -160,8 +164,6 @@ npm run test # Verify cleanup didn't break anything**مع استراتيجية تنظيف** (المجموعة التجريبية): فحص حالة نظيفة كامل في نهاية كل جلسة + حلقة تنظيف أسبوعية. الأسبوع 12، معدل اجتياز البناء 97%، معدل اجتياز الاختبارات 95%، بدء الجلسة الجديدة 9 دقائق، قطع أثرية قديمة 11.-بنهاية الأسبوع 12، معدل اجتياز البناء للمجموعة التجريبية أعلى بـ 29 نقطة مئوية، معدل اجتياز الاختبارات أعلى بـ 34 نقطة مئوية، ووقت بدء الجلسة الجديدة أقل بنسبة 85%.-## الخلاصات الأساسية- **الحالة النظيفة شرط ضروري لاكتمال الجلسة** — ليست تنظيفًا اختياريًا، بل جزء من "تعريف الانتهاء."diff --git a/docs/ar/lectures/lecture-13-loop-engineering/index.md b/docs/ar/lectures/lecture-13-loop-engineering/index.mdindex a22c606..8973ef2 100644--- a/docs/ar/lectures/lecture-13-loop-engineering/index.md+++ b/docs/ar/lectures/lecture-13-loop-engineering/index.md@@ -5,6 +5,8 @@# المحاضرة 13. من المطالبة اليدوية إلى الحلقات المستقلة+> إرشادات هندسية: الحدود الرقمية قيم تعليمية قابلة للتعديل، لا عتبات مثبتة تجريبيًا. عدد الرموز يعتمد على tokenizer والمحتوى، لا عدد الأسطر وحده.+كل ما تعلمته في المحاضرات الاثنتي عشرة الأولى يستند إلى افتراض واحد: **أنت تجلس أمام لوحة المفاتيح، وتكتب التعليمات واحدة تلو الأخرى.**لقد كتبت `AGENTS.md` (المحاضرات 1-4)، وبنيت إدارة الحالة (المحاضرات 5-6)، وحددت النطاق بقوائم الميزات (المحاضرات 7-8)، وتركت تسليمات نظيفة في نهاية الجلسة (المحاضرات 9، 12)، وجعلت وقت التشغيل قابلًا للملاحظة (المحاضرات 10-11). لكن المحفز لكل ذلك كان دائمًا أنت. لم يقرر الوكيل من تلقاء نفسه متى يبدأ العمل - لأن لا أحد ضغط على زر "ابدأ".@@ -96,7 +98,13 @@> **هندسة الحلقات هي استبدال نفسك كشخص الذي يطالب الوكيل. أنت تصمم النظام الذي يفعل ذلك بدلاً منك.**-كشف تشيرني عن أرقام: على مدار 30 يومًا متتالية، تم إجراء جميع مساهمات الكود في Claude Code بشكل مستقل بواسطة الذكاء الاصطناعي - 259 PR مدمجة، وأكثر من 80٪ من كود الإنتاج كتبه Claude، ومعدل نجاح 76٪ في مهام البرمجة مفتوحة النهاية.+Boris Cherny · 2025-12-27++| PR | Git commits | + LoC | − LoC | Model |+| --- | --- | --- | --- | --- |+| 259 / 30 days | 497 | 40,000 | 38,000 | Claude Code + Opus 4.5 |++نشاط شخصي أبلغ عنه المؤلف، لا معدل نجاح benchmark ولا دليل على غياب الإشراف البشري. [Boris Cherny](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)ثلاثة أشخاص. أسبوع واحد. نفس الاستنتاج. ليس لأنهم تناسقوا - بل لأن البنية التحتية عبرت بهدوء عتبة. أصبحت الوكلاء موثوقين بما يكفي لإنجاز المهام غير البسيطة دون إشراف. أصبحت بدائيات الجدولة (`/loop`، `/goal`، cron) مدمجة الآن في الأدوات. انخفضت تكلفة تشغيل وكيل واحد بما يكفي بحيث لم يعد تشغيله بشكل متكرر على مؤقت يبدو مُبذرًا. عندما تكون جميع الأجزاء موجودة، فإن الخطوة التي تجمعها تصبح واضحة للجميع في نفس الوقت.@@ -267,7 +275,7 @@ flowchart TDهذه لم تعد تشغيل وكيل واحد. إنها نظام يعمل باستمرار يستيقظ كل صباح، وينظف الأرضية من تلقاء نفسه، ويضع الأشياء التي تحتاج إلى اهتمامك أمامك. يصبح دورك: **راجع محتويات الصندوق، واتخذ القرارات، وعندما تكتشف نمطًا لا يستطيع النظام التعامل معه، صقل المهارات والقواعد.**-استخدم تشيرني هذا النمط لدمج 259 PR في 30 يومًا دون فتح IDE مرة واحدة. استخدم مهندسو OpenAI نفس النمط لبناء منتج بيتا يبلغ حوالي مليون سطر كود يدويًا - دون كتابة سطر كود واحد بأنفسهم.+نشاط شخصي أبلغ عنه المؤلف، لا معدل نجاح benchmark ولا دليل على غياب الإشراف البشري.## فصل المولد/المقيّم: لماذا لا يمكنك السماح للنموذج بتصحيح عمله بنفسه@@ -293,7 +301,7 @@ flowchart TDإذا كنت تريد أن ترى كيف تبدو حلقة مصممة جيدًا وتعمل بالفعل، فإن [autoresearch لكارباثي](https://github.com/karpathy/autoresearch) هي المثال النموذجي.-في مارس 2026، أصدر كارباثي مشروع Python مكونًا من 630 سطرًا. أعطِه GPU واحدًا واتجاه بحثي، ويعمل طوال الليل - مكتملًا بمئات تجارب تدريب ML، ويحتفظ فقط بتلك التي تحسن حقًا. وصل المشروع إلى أكثر من 66,000 نجمة في غضون أيام من الإصدار.+[Karpathy: autoresearch](https://github.com/karpathy/autoresearch) · [announcement](https://x.com/karpathy/status/2030371219518931079)### ثلاثة ملفات، ثلاثة أدوار@@ -343,8 +351,6 @@ flowchart TD8b --> 9```-تعمل بـ 12 تجربة تقريبًا في الساعة. تشغيل ليلة واحدة (8 ساعات) حوالي 100 تجربة. قام كارباثي نفسه بتشغيلها لمدة يومين - ~700 تجربة.-ميزانية الساعة الحائط الثابتة البالغة 5 دقائق هي خيار تصميمي رئيسي - بغض النظر عما يغيره الوكيل، تستغرق كل تجربة نفس الوقت بالضبط. هذا يعني أن جميع النتائج قابلة للمقارنة مباشرة ضمن نفس الميزانية الزمنية - لا جدال حول "هذه شغلت لفترة أطول لذا فهي أفضل."### المخرج: ما تراه عند الاستيقاظ@@ -359,6 +365,8 @@ flowchart TDكل تجربة واحدة - نجاح أو فشل - مسجلة:+> مثال تعليمي: هذا السيناريو وأرقامه افتراضات لشرح الآلية، وليست قياسات من تجربة منشورة.+```timestamp commit_hash val_bpb vram_mb description--------- ------------- ---------- ---------- ----------------------------@@ -375,11 +383,8 @@ timestamp commit_hash val_bpb vram_mb description### ما وجده بالفعل-النتائج من تشغيل كارباثي الأولي لمدة يومين، ~700 تجربة:--- من بين ~700 محاولة، تم العثور على حوالي **20 تحسنًا حقيقيًا قابلًا للتكديس**-- خفض وقت تدريب مستوى GPT-2 لـ nanochat على 8×H100 من **2.02 ساعة → 1.80 ساعة**، حوالي **أسرع بنسبة 11٪**-- شملت النتائج: تعديلات معدل التعلم، وضبط المحسن، وتبديلات التنشيط، وتحسينات نمط الانتباه، إلخ.+- خفض وقت تدريب مستوى GPT-2 لـ nanochat على 8×H100 من **2.02 ساعة → 1.80 ساعة**، حوالي **أسرع بنسبة 10.89٪**+- شملت النتائج: تعديلات معدل التعلم، وضبط المحسن، وتبديلات التنشيط، وتحسينات نمط الانتباه، إلخ. [Karpathy: leaderboard commit](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b) · [tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)هل كانت جميع التحسينات اكتشافات مذهلة؟ لا. كانت معظمها تحسينات صغيرة تكدست. لكن تلك التحسينات الصالحة البالغ عددها 20 كانت ستستغرق باحثًا بشريًا أسابيع من العمل اليدوي - وفعلها الوكيل في 48 ساعة.@@ -399,7 +404,7 @@ timestamp commit_hash val_bpb vram_mb description### 2. تعفن الفهم-كلما زادت سرعة شحن الحلقة للكود، زاد تباعد فهمك لقاعدة الكود الخاصة بك عن الواقع. كان لدى فريق تشيرني 80٪ من الكود مكتوبًا بواسطة الوكلاء - مما يعني أن معظم كود الفريق لم يكتبه شخص. إذا لم تقرأ وتستخدم ما تنتجه الحلقة، فإن فهمك يتحلل باستمرار. **الحلقات السريعة تتطلب قراءة سريعة.**+نتائج الإنتاج لا تعزل سببًا واحدًا. درجات benchmark تخص النموذج وscaffold والبيانات وشروط التقييم المحددة.### 3. الاستسلام المعرفيdiff --git a/docs/ar/lectures/lecture-14-graph-engineering/index.md b/docs/ar/lectures/lecture-14-graph-engineering/index.mdindex ca965be..9267a39 100644--- a/docs/ar/lectures/lecture-14-graph-engineering/index.md+++ b/docs/ar/lectures/lecture-14-graph-engineering/index.md@@ -261,7 +261,7 @@ run(graph, entry={"requirements": "إصلاح خطأ صفحة تسجيل الد**موجود بعد إطلاق المفهوم**-- [GraphArc](https://github.com/CodeGraphContext/grapharc) (2026-08-02): يسمي نفسه "أول تنفيذ فوري في الوقت الحقيقي لهندسة الرسوم البيانية". يحوّل تنفيذ الوكيل من سجلات مدفونة في السجلات إلى **رسم بياني تنسيق تفاعلي في الوقت الحقيقي** — كل وكيل وكل تبعية وكل نقطة قرار مرسومة، تُعرض للتصور قبل التنفيذ (ويمكنك حتى النظر إليها من هاتفك)، ثم تسمح بالاستمرار بعد التأكيد. خلفية المؤلف هي بناء أدوات رسوم بيانية لأكثر من 4000 مطور، والاتجاه هو "قابل للملاحظة، قابل للتصحيح، قابل للهندسة". جديد جدًا، والوظائف ما زالت في مرحلة مبكرة.+- [GraphArc](https://github.com/CodeGraphContext/grapharc)**موجود قبل إطلاق المفهوم (لا يسمونها هندسة الرسوم البيانية، لكنها هي ما ستستخدمه فعليًا عند البناء)**@@ -346,4 +346,4 @@ run(graph, entry={"requirements": "إصلاح خطأ صفحة تسجيل الد4. **قيّم مهمة بالمعايير الخمسة:** اختر مهمة تتردد في "تحويلها إلى رسم بياني" وقم بقياسها بالمعايير الخمسة واحدًا واحدًا. تحتاج ثلاثة على الأقل لتستحق رسمًا بيانيًا. إذا كان أقل من ثلاثة، فما تحتاجه فعلًا هو نص سير عمل أفضل — لا ترسم رسمًا بيانيًا لمجرد الرسم.-5. **حوّل `graph.md` إلى برنامج قابل للتنفيذ:** اتبع الخطوات الست في "ابنِ أول رسم بياني لك من الصفر" ونفّذ رسم maker-checker الذي رسمته إلى رسم قابل للتشغيل (التنفيذ المرجعي: `code/maker_checker_graph.py`، مكتوب بـ LangGraph). لا تتخطَّ الخطوات الست: عرّف الحالة → اسرد العقد → صِل الحواف → اكتب التوجيه → علّق checkpoint → شغّل. بعد الانتهاء قارن `graph.md` بالكود، وابحث عن أول مكان لا يتطابقان فيه، واشرح لماذا — هل الرسم خاطئ، أم الكود خاطئ؟\ No newline at end of file+5. **حوّل `graph.md` إلى برنامج قابل للتنفيذ:** اتبع الخطوات الست في "ابنِ أول رسم بياني لك من الصفر" ونفّذ رسم maker-checker الذي رسمته إلى رسم قابل للتشغيل (التنفيذ المرجعي: `code/maker_checker_graph.py`، مكتوب بـ LangGraph). لا تتخطَّ الخطوات الست: عرّف الحالة → اسرد العقد → صِل الحواف → اكتب التوجيه → علّق checkpoint → شغّل. بعد الانتهاء قارن `graph.md` بالكود، وابحث عن أول مكان لا يتطابقان فيه، واشرح لماذا — هل الرسم خاطئ، أم الكود خاطئ؟diff --git a/docs/ar/resources/reference/index.md b/docs/ar/resources/reference/index.mdindex eb404f3..f44c261 100644--- a/docs/ar/resources/reference/index.md+++ b/docs/ar/resources/reference/index.md@@ -24,6 +24,11 @@- [On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents](https://arxiv.org/html/2601.20404v2): gpt-5.2-codex; 10 repos / 124 PR tasks; Table 1.+- [Anthropic: Sonnet 4.5 — SWE-bench Verified methodology (2025-09-29)](https://www.anthropic.com/news/claude-sonnet-4-5)+- [Boris Cherny: personal 30-day production report (2025-12-27)](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)+- [Karpathy: measured autoresearch leaderboard improvement](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b)+- [Karpathy: two-day autonomous tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)+## ترتيب القراءة المقترح1. `method-map.md`diff --git a/docs/de/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/de/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex e14086b..60c8dea 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,17 +9,30 @@ Du kennst dich in der KI-Welt gut aus: Claude-Pro-Abo, GPT-4o-API-Key, SWE-benchDein 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.+Claude Sonnet 4.5 · 2025-09-29 · SWE-bench Verified++| Score | Tasks | Trials | Scaffold |+| --- | --- | --- | --- |+| 77.2% | 500 | 10 | bash + string replacement |++Produktionsberichte isolieren keinen einzelnen kausalen Beitrag. Benchmarkwerte gelten für Modell, Scaffold, Datensatz und Auswertung, nicht für jede Produktionsaufgabe. [Anthropic: methodology](https://www.anthropic.com/news/claude-sonnet-4-5)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.+> Gleiches Modell und gleicher Prompt, aber unterschiedliche Laufzeit- und Kostenbudgets. Kein Experiment mit gleichem Budget zur Isolation eines einzelnen Bestandteils. Das Spiel funktionierte im Kern, hatte aber weiterhin Fehler. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++Gleiches Modell und gleicher Prompt, aber unterschiedliche Laufzeit- und Kostenbudgets. Kein Experiment mit gleichem Budget zur Isolation eines einzelnen Bestandteils. Das Spiel funktionierte im Kern, hatte aber weiterhin Fehler. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++| Opus 4.5 | Duration | USD |+| --- | --- | --- |+| Solo | 20 min | 9 |+| Full harness | 6 h | 200 |Sie änderten nicht das Modell. Opus 4.5 blieb Opus 4.5. Was sich änderte, war das Zaumzeug.-OpenAIs Artikel zu Harness Engineering aus dem Jahr 2025 formuliert es direkt: Codex wechselt in einem gut geharnessten Repository von "unzuverlässig" zu "zuverlässig". Achte auf die Wortwahl - nicht "ein bisschen besser", sondern ein qualitativer Sprung. Wie bei einem Vollblutpferd: Du kannst ohne passendes Zaumzeug reiten, aber du kommst nicht weit, nicht schnell, und ein Sturz ist keine Überraschung. Der Harness ist dieses gesamte Zaumzeug - **alles in der Engineering-Infrastruktur außerhalb der Modellgewichte.**+Produktionsberichte isolieren keinen einzelnen kausalen Beitrag. Benchmarkwerte gelten für Modell, Scaffold, Datensatz und Auswertung, nicht für jede Produktionsaufgabe. [OpenAI: 2026-02-11](https://openai.com/index/harness-engineering/)## Wo Agenten tatsächlich stecken bleiben@@ -39,7 +52,7 @@ Lange Aufgaben über mehrere Sitzungen sind noch schlimmer: Alle Erkenntnisse auMit diesen Szenarien im Hinterkopf sind die folgenden Begriffe kein bloßer Jargon mehr:-- **Capability Gap**: Die große Lücke zwischen Modellleistung auf Benchmarks und Leistung bei realen Aufgaben. Eine Erfolgsrate von 50-60% auf SWE-bench Verified bedeutet, dass fast die Hälfte realer Issues nicht gelöst wird.+- Produktionsberichte isolieren keinen einzelnen kausalen Beitrag. Benchmarkwerte gelten für Modell, Scaffold, Datensatz und Auswertung, nicht für jede Produktionsaufgabe.- **Harness**: Alles außerhalb des Modells - Anweisungen, Tools, Umgebung, Zustandsverwaltung, Verifikationsfeedback. Wenn es keine Modellgewichte sind, gehört es zum Harness. Das ist das "Zaumzeug", von dem wir gesprochen haben.- **Harness-Induced Failure**: Das Modell hat grundsätzlich genug Fähigkeit, aber die Ausführungsumgebung hat strukturelle Defekte. Anthropics kontrolliertes Experiment hat genau das gezeigt.- **Verification Gap**: Die Lücke zwischen dem Vertrauen des Agenten in sein Ergebnis und der tatsächlichen Korrektheit. Der Agent sagt "ich bin fertig", obwohl er nicht fertig ist - der häufigste Fehlermodus.@@ -72,17 +85,19 @@ 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.+Produktionsberichte isolieren keinen einzelnen kausalen Beitrag. Benchmarkwerte gelten für Modell, Scaffold, Datensatz und Auswertung, nicht für jede Produktionsaufgabe. [OpenAI: 2026-02-11](https://openai.com/index/harness-engineering/)-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.+Produktionsberichte isolieren keinen einzelnen kausalen Beitrag. Benchmarkwerte gelten für Modell, Scaffold, Datensatz und Auswertung, nicht für jede Produktionsaufgabe.Der frühe Fortschritt war langsamer als erwartet. Nicht weil Codex unfähig war, sondern weil die Umgebung nicht vollständig genug war - dem Agenten fehlten notwendige Werkzeuge, Abstraktionen und interne Strukturen, um übergeordnete Ziele voranzubringen. Die Arbeit der Engineers wurde: große Ziele in kleine Bausteine zerlegen (Design, Code, Review, Test), den Agenten diese zusammensetzen lassen und diese Bausteine dann nutzen, um komplexere Aufgaben freizuschalten. Wenn etwas scheiterte, lautete die Lösung fast nie "streng dich mehr an", sondern "welche Fähigkeit fehlt dem Agenten, und wie machen wir sie verständlich und ausführbar?"-Dieses Experiment belegt direkt die Kernaussage dieser Lektion: **Dasselbe Modell erzeugt in einer nackten Umgebung grundlegend andere Ergebnisse als in einer Umgebung mit vollständigem Harness.** Das Modell änderte sich nicht. Die Umgebung änderte sich.+Produktionsberichte isolieren keinen einzelnen kausalen Beitrag. Benchmarkwerte gelten für Modell, Scaffold, Datensatz und Auswertung, nicht für jede Produktionsaufgabe.> Quelle: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)-## Ein bodenständigeres Beispiel+## Lehrbeispiel++> Lehrbeispiel: Dieses Szenario und seine Zahlen dienen der Erklärung und sind keine Messwerte eines veröffentlichten Experiments.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.@@ -108,6 +123,8 @@ Sie änderten nicht das Modell. Sie änderten den Harness.- [SWE-bench Leaderboard](https://www.swebench.com/)- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)+- [Anthropic: Sonnet 4.5 SWE-bench methodology, 2025-09-29](https://www.anthropic.com/news/claude-sonnet-4-5)+## Übungen1. **Vergleichsexperiment**: Wähle eine Codebase, die du gut kennst, und eine nicht triviale Änderungsaufgabe. Führe den Agenten zuerst ohne Harness-Unterstützung aus und protokolliere die Fehler. Füge dann eine `AGENTS.md` mit expliziten Verifikationsbefehlen hinzu und führe denselben Agenten erneut aus. Vergleiche die Ergebnisse und ordne jeden Fehler einer der fünf Verteidigungsschichten zu.diff --git a/docs/de/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/de/lectures/lecture-02-what-a-harness-actually-is/index.mdindex cb2d7dc..365990d 100644--- a/docs/de/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/de/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -70,7 +70,9 @@ Wenn ein Subsystem fehlt, ist das wie ein fehlender Funktionsbereich in der Küc**Wert von harness-Komponenten quantifizieren**: Verwenden Sie eine Ablation mit fester Modellkontrolle. Halten Sie das Modell fest, entfernen Sie Subsysteme einzeln und messen Sie, welche Entfernung den größten Leistungsabfall verursacht. Der größte Abfall zeigt die Komponente mit dem höchsten Grenzbeitrag in dieser Aufgabe; er identifiziert nicht automatisch den Engpass. Auch ein nahezu ausbleibender Abfall braucht Interpretation: Die Komponente kann redundant, schlecht entworfen oder durch diese Aufgabe schlicht nicht ausgelöst worden sein. Um Engpässe zu diagnostizieren, nutzen Sie zuerst Fehlerprotokolle und Attribution und verwenden Ablation nur als unterstützende Evidenz: War die Ursache eine unklare Aufgabe, zu wenig Kontext, eine nicht reproduzierbare Umgebung, fehlendes Verifikationsfeedback oder gebrochene Zustandsverwaltung?-## Die wahre Geschichte eines Teams+## Lehrbeispiel++> Lehrbeispiel: Dieses Szenario und seine Zahlen dienen der Erklärung und sind keine Messwerte eines veröffentlichten Experiments.Ein Team verwendete GPT-4o für eine TypeScript + React Frontend-App (~20.000 Zeilen Code). Sie durchliefen vier Stufen — im Grunde rüsteten sie die Küche Stück für Stück aus:diff --git a/docs/de/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/de/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdindex bd9e3e0..fb9e78f 100644--- a/docs/de/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md+++ b/docs/de/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -5,6 +5,8 @@# Lektion 03. Das Repository zur einzigen Quelle der Wahrheit machen+> Technische Richtwerte: Die Zahlen sind anpassbare Lehrannahmen, keine experimentell bestätigten Grenzen. Tokenzahlen hängen von Tokenizer und Inhalt ab, nicht allein von Zeilen.+Die Architekturentscheidungen deines Teams sind über Confluence, Slack, Jira und die Köpfe einiger Senior Engineers verstreut. Für Menschen funktioniert das gerade so: Man kann Kolleginnen fragen, Chatverläufe durchsuchen, Dokumente ausgraben. Wenn alles scheitert, kann man jemanden im Pausenraum abfangen. Für einen KI-Agenten aber existiert Information, die nicht im Repository steht, schlicht nicht.Das ist keine Übertreibung. Denk darüber nach, was die Eingaben eines Agenten tatsächlich sind: Systemprompts und Aufgabenbeschreibungen, Dateiinhalte aus dem Repository und Tool-Ausgaben. Das war's. Deine Slack-Historie, Jira-Tickets, Confluence-Seiten und die Architekturentscheidung, die du am Freitagnachmittag bei Kaffee mit einem Kollegen besprochen hast - der Agent sieht nichts davon. Er kann nicht "jemanden fragen" oder "den Chatverlauf durchsuchen". Er ist ein Engineer, der im Repository eingeschlossen ist. Alles außerhalb kennt er nicht.diff --git a/docs/de/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/de/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdindex caa77c9..a84e68e 100644--- a/docs/de/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md+++ b/docs/de/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -5,6 +5,8 @@# Lektion 04. Anweisungen auf Dateien verteilen+> Technische Richtwerte: Die Zahlen sind anpassbare Lehrannahmen, keine experimentell bestätigten Grenzen. Tokenzahlen hängen von Tokenizer und Inhalt ab, nicht allein von Zeilen.+Du hast Harness Engineering ernst genommen. Du hast eine `AGENTS.md` erstellt und jede Regel, jede Einschränkung und jede gelernte Lektion hineingepackt, die dir eingefallen ist. Einen Monat später war die Datei auf 300 Zeilen angewachsen, nach zwei Monaten auf 450, nach drei Monaten auf 600. Dann merkst du, dass die Leistung des Agenten tatsächlich schlechter wird: Bei einem einfachen Bugfix verbrennt er massenhaft Kontext für irrelevante Deployment-Anweisungen; eine kritische Sicherheitsregel in Zeile 300 wird komplett ignoriert; drei widersprüchliche Code-Style-Regeln führen dazu, dass der Agent jedes Mal zufällig eine auswählt.Das ist die Falle der "riesigen Anweisungsdatei". Es ist wie ein überfüllter Koffer: Alles scheint nützlich, also stopfst du es hinein, bis der Reißverschluss fast platzt. Um frische Unterwäsche zu finden, musst du den ganzen Koffer ausleeren. Du trägst einen vollen Koffer, nutzt aber vielleicht nur ein Drittel des Inhalts.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.mdindex fa893de..c8984e6 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@@ -5,6 +5,8 @@# Lektion 05. Kontext über Sessions hinweg erhalten+> Technische Richtwerte: Die Zahlen sind anpassbare Lehrannahmen, keine experimentell bestätigten Grenzen. Tokenzahlen hängen von Tokenizer und Inhalt ab, nicht allein von Zeilen.+Sie bitten Claude Code, ein vollständiges Feature zu implementieren. Es läuft 30 Minuten, erledigt den Großteil der Arbeit, aber der Kontext wird knapp. Sie starten eine neue Session, um fortzufahren — und stellen fest, dass es sich nicht an die Entscheidungen der letzten Session erinnert, warum Option A gegenüber Option B gewählt wurde, welche Dateien bereits geändert wurden oder in welchem Zustand sich die Tests befinden. Es verbringt 15 Minuten damit, das Projekt neu zu erkunden, und könnte inkonsistent zum vorherigen Ansatz sein.Stellen Sie sich vor, Sie wären ein Handwerker, der jeden Morgen beim Aufwachen alles vergisst. Sie müssten sich die gesamte Baustelle neu vertraut machen — welche Mauer halb fertig ist, warum rote statt blaue Ziegel gewählt wurden, wo die Rohrleitungen verlaufen. Schlimmer noch, Sie könnten ein Fenster herausreißen, das gestern bereits eingebaut wurde, einfach weil Sie sich nicht erinnern, dass es erledigt war.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.mdindex ae1c4f6..89c13d1 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@@ -5,6 +5,8 @@# Lektion 06. Vor jeder Agenten-Session initialisieren+> Technische Richtwerte: Die Zahlen sind anpassbare Lehrannahmen, keine experimentell bestätigten Grenzen. Tokenzahlen hängen von Tokenizer und Inhalt ab, nicht allein von Zeilen.+Sie starten eine neue Agenten-Session und sagen „Füge eine Suchfunktion hinzu." Es stürzt sich direkt ins Programmieren — bewundernswerte Begeisterung. Nach 20 Minuten stellt es fest, dass das Test-Framework nicht richtig konfiguriert ist, verbringt weitere 10 Minuten mit der Reparatur, dann ist das Format des Datenbankmigrationsskripts falsch, weiteres Herumgefummel. Die Suchfunktion wird schließlich hinzugefügt, aber die gesamte Session war ineffizient — die meiste Zeit floss in „herausfinden, wie dieses Projekt funktioniert" anstatt die Suchfunktion zu schreiben.Der bessere Ansatz: Bevor der Agent mit der Arbeit beginnt, eine separate Phase nutzen, um die Basisumgebung vorzubereiten, Verifizierungsbefehle zum Laufen zu bringen und die Projektstruktur zu verstehen. Es ist wie beim Hausbau — man gießt nicht das Fundament und stellt gleichzeitig die Wände auf. Wenn man es doch tut, stehen die Wände, bevor das Fundament ausgehärtet ist, und das gesamte Gebäude muss abgerissen und neu begonnen werden. Erst das Fundament gießen, aushärten lassen, dann die Wände bauen — sauber und effizient.@@ -37,6 +39,8 @@ flowchart TB## Was passiert, wenn man beides vermischt+> Lehrbeispiel: Dieses Szenario und seine Zahlen dienen der Erklärung und sind keine Messwerte eines veröffentlichten Experiments.+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.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 +49,7 @@ Das Session-Budget wird ebenfalls verschwendet. Initialisierungsarbeit (UmgebungDas 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.+[Anthropic: initializer / coding agent](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)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.@@ -122,7 +126,9 @@ OpenAIs Codex harness Engineering-Leitfaden betont ebenfalls das Prinzip „Repo- [ ] Everything committed to git```-## Praxisbeispiel+## Lehrbeispiel++> Lehrbeispiel: Dieses Szenario und seine Zahlen dienen der Erklärung und sind keine Messwerte eines veröffentlichten Experiments.Zwei Initialisierungsansätze für ein React-Frontend-Projekt: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.mdindex c052b15..cb45c2d 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@@ -5,6 +5,8 @@# Lektion 07. Klare Aufgabengrenzen für Agenten ziehen+> Technische Richtwerte: Die Zahlen sind anpassbare Lehrannahmen, keine experimentell bestätigten Grenzen. Tokenzahlen hängen von Tokenizer und Inhalt ab, nicht allein von Zeilen.+Sie sagen Claude Code, es soll „Benutzerauthentifizierung zu diesem Projekt hinzufügen", und es beginnt, das Datenbankschema zu ändern, Routen zu schreiben, Frontend-Komponenten zu bearbeiten und — während es gerade dabei ist — die Fehlerbehandlungs-Middleware zu refactoren. Zwei Stunden später überprüfen Sie: 12 Dateien geändert, 800 Zeilen neuer Code, und kein einziges Feature funktioniert End-to-End.Sich mehr auf den Teller laden, als man bewältigen kann — dieses Sprichwort gilt für KI-Agenten ganz besonders. Agenten werden mit einem Impuls geboren, „noch etwas Extra zu erledigen" — sie sehen verwandte Dinge und erledigen sie einfach nebenbei, wie jemand, der für eine Flasche Sojasauce in den Supermarkt geht und mit einem vollen Einkaufswagen herauskommt. Das Problem ist: Menschen, die zu viel kaufen, verschwenden nur Geld; Agenten, die zu viele Dinge gleichzeitig tun, bedeuten, dass keines davon richtig erledigt wird.@@ -26,7 +28,7 @@ Claude Codes tatsächliches Verhalten ist aufschlussreich. Bitten Sie es, „BenSechs 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.+[Anthropic: incremental feature work](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## WIP=1-Workflow@@ -100,7 +102,9 @@ Verwenden Sie eine maschinenlesbare Datei (JSON oder Markdown), um alle AufgabenDas harness sollte kontinuierlich VCR (Verified Completion Rate) = verifizierte Aufgaben / aktivierte Aufgaben verfolgen. Blockieren Sie neue Aufgabenaktivierungen, wenn VCR < 1.0.-## Praxisbeispiel+## Lehrbeispiel++> Lehrbeispiel: Dieses Szenario und seine Zahlen dienen der Erklärung und sind keine Messwerte eines veröffentlichten Experiments.Ein REST-API-Projekt mit 8 Features, zwei Strategien im Vergleich: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.mdindex 62211e6..abea117 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@@ -5,6 +5,8 @@# Lektion 08. Feature-Listen nutzen, um Agentenarbeit zu begrenzen+> Technische Richtwerte: Die Zahlen sind anpassbare Lehrannahmen, keine experimentell bestätigten Grenzen. Tokenzahlen hängen von Tokenizer und Inhalt ab, nicht allein von Zeilen.+Du bittest einen Agenten, eine E-Commerce-Seite zu bauen. Nachdem er fertig ist, sagt er "done". Du schaust in den Code: Die Benutzeranmeldung funktioniert, aber der Checkout-Button im Warenkorb macht nichts, und der Zahlungsfluss ist gar nicht verbunden. Das Problem: Du hast nie gesagt, was "done" bedeutet. Also verwendet der Agent seinen eigenen Standard: "Ich habe viel Code geschrieben, und es sieht ziemlich vollständig aus."In den Augen vieler Menschen sind Feature-Listen nur Notizzettel: Dinge aufschreiben, damit man sie nicht vergisst, und dann beiseitelegen. In der Harness-Welt aber ist eine Feature-Liste kein Memo für Menschen, sondern das Rückgrat des gesamten Harness. Der Scheduler nutzt sie, um Aufgaben auszuwählen; der Verifier nutzt sie, um Abschluss zu beurteilen; der Handoff Reporter nutzt sie, um Zusammenfassungen zu erzeugen. Bricht das Rückgrat, ist der ganze Körper gelähmt.@@ -23,7 +25,7 @@ Did user auth, shopping cart mostly done, still need paymentsKann 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.+Fortschritt und Prüfergebnisse gehören in versionierte Dateien, damit die nächste Sitzung den Zustand prüfen kann. Die Quelle beschreibt den Mechanismus ohne prozentuale Zeitersparnis. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## Feature-Zustandsmaschine@@ -104,7 +106,9 @@ Der Agent kann den Zustand eines Features nicht direkt auf `passing` setzen. ErJedes Feature-Element sollte auf "in einer Sitzung abschließbar" zugeschnitten sein. Zu breit, und es wird nicht fertig; zu eng, und der Verwaltungsaufwand steigt. "Nutzer kann Artikel in den Warenkorb legen" ist gute Granularität. "Den Warenkorb implementieren" ist zu breit. "Das name-Feld im Cart-Modell erstellen" ist zu eng. Wie ein Steak schneiden: nicht das ganze Stück und nicht Hackfleisch.-## Praxisfall+## Lehrbeispiel++> Lehrbeispiel: Dieses Szenario und seine Zahlen dienen der Erklärung und sind keine Messwerte eines veröffentlichten Experiments.Eine E-Commerce-Plattform mit 10 Features. Zwei Tracking-Ansätze wurden verglichen:@@ -112,8 +116,6 @@ 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.-## Wichtigste Erkenntnisse- **Feature-Listen sind das Rückgrat des Harness**, keine Memos für Menschen. Scheduler, Verifier und Handoff Reporter hängen alle davon ab.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.mdindex 6cbcdb1..66c1c54 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@@ -5,6 +5,8 @@# Lektion 09. Verhindern, dass Agenten zu früh Erfolg melden+> Technische Richtwerte: Die Zahlen sind anpassbare Lehrannahmen, keine experimentell bestätigten Grenzen. Tokenzahlen hängen von Tokenizer und Inhalt ab, nicht allein von Zeilen.+Sie bitten einen Agenten, eine „Passwort zurücksetzen"-Funktion zu implementieren. Er ändert das Datenbankschema, schreibt den API-Endpunkt, fügt die E-Mail-Vorlage hinzu, führt Unit-Tests aus (alle bestanden) und teilt Ihnen zuversichtlich mit: „Es ist fertig." Wenn Sie es tatsächlich ausprobieren — der Link zum Zurücksetzen des Passworts kann nicht gesendet werden (E-Mail-Service-Konfiguration fehlt), die Datenbankmigration scheitert zur Hälfte (Schemainkonsistenz), und der End-to-End-Ablauf wurde kein einziges Mal ausgeführt.Dieses Gefühl sollte nicht un vertraut sein — es ist, als würde man das gesamte Klausurheft ausfüllen, zuversichtlich als Erster abgeben und dann durchfallen, wenn die Noten kommen. Nur weil das Heft voll ist, heißt das nicht, dass die Antworten richtig sind.@@ -13,6 +15,8 @@ Dies ist kein Einzelfall. Das klassische ICML-Papier von Guo et al. (2017) hat b## Die rutschige Abwärtsspirale+> Gleiches Modell und gleicher Prompt, aber unterschiedliche Laufzeit- und Kostenbudgets. Kein Experiment mit gleichem Budget zur Isolation eines einzelnen Bestandteils. Das Spiel funktionierte im Kern, hatte aber weiterhin Fehler. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)+Voreilige Fertigstellungsmeldungen folgen fast immer demselben Muster: Der Code sieht in Ordnung aus — Syntax ist korrekt, Logik erscheint plausibel, und die statische Analyse zeigt keine offensichtlichen Fehler. Aber der Harness erzwingt keine umfassende Ausführungs verifikation, also überspringt der Agent das tatsächliche Ausführen oder führt nur teilweise Tests durch. Er führt Unit-Tests durch, überspringt aber Integrationstests; er führt Tests durch, prüft aber keine Abdeckung. Letztendlich wird „der Code sieht gut aus" als Beweis dafür genommen, dass „die Funktion vollständig ist". Und das Klausurheft wird abgegeben.Bei jedem Schritt geht Information verloren. Von der Aufgaben spezifikation über die Code-Implementierung bis zum Laufzeitverhalten — jede Transformation kann Verzerrungen einführen, und jede übersprungene Verifikation verschärft die Informationsasymmetrie.@@ -111,7 +115,9 @@ Wirksame Laufzeit-Signale umfassen:- Waren Datenbank-Schreibvorgänge, Dateioperationen und andere Seiteneffekte korrekt?- Wurden temporäre Ressourcen bereinigt?-## Fallbeispiel aus der Praxis+## Lehrbeispiel++> Lehrbeispiel: Dieses Szenario und seine Zahlen dienen der Erklärung und sind keine Messwerte eines veröffentlichten Experiments.**Aufgabe**: Passwort-Zurücksetzen-Funktionalität für Benutzer implementieren. Umfasst Datenbankoperationen, E-Mail-Versand und API-Endpunkt-Änderungen.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.mdindex 2ff7028..7413002 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@@ -5,6 +5,8 @@# Lektion 10. Nur End-to-End-Tests sind echte Verifikation+> Technische Richtwerte: Die Zahlen sind anpassbare Lehrannahmen, keine experimentell bestätigten Grenzen. Tokenzahlen hängen von Tokenizer und Inhalt ab, nicht allein von Zeilen.+Sie bitten den Agenten, eine Datei-Export-Funktion zu einer Electron-App hinzuzufügen. Er schreibt die Render-Prozess-Komponente, das Preload-Skript und die Service-Layer-Logik. Die Unit-Tests für jede Komponente bestehen perfekt. Der Agent sagt: „Es ist fertig." Wenn Sie tatsächlich auf den Export-Button klicken — das Dateipfad-Format ist falsch, die Fortschrittsanzeige aktualisiert sich nicht und der Export großer Dateien verursacht einen Memory-Leak. Fünf Komponenten-Grenzfläche-Defekte, und die Unit-Tests haben keinen einzigen davon erkannt.Es ist wie bei einer Chorprobe — jede Stimme klingt einzeln perfekt, aber wenn sie zusammen singen, sind die Soprane einen halben Takt schneller als die Bässe, und die Begleitung ist einen Halbton von der Hauptmelodie entfernt. Jede Stimme ist für sich „korrekt", aber das Ganze ist nicht harmonisch.@@ -116,7 +118,9 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.reaJedes Mal, wenn eine neue Art von Agentenfehler beim Code-Review gefunden wird, wandeln Sie ihn in einen automatisierten Check um. Einen Monat später wird Ihr Harness deutlich stärker sein als zu Monatsbeginn. Es ist wie Probenotizen für einen Chor — Probleme aus jeder Probe aufzeichnen, damit sie vor der nächsten überprüft werden können. Im Laufe der Zeit nehmen häufige Fehler ab, und die Musik wird harmonischer.-## Fallbeispiel aus der Praxis+## Lehrbeispiel++> Lehrbeispiel: Dieses Szenario und seine Zahlen dienen der Erklärung und sind keine Messwerte eines veröffentlichten Experiments.**Aufgabe**: Implementierung einer Datei-Export-Funktion in einer Electron-App. Umfasst Render-Prozess-UI, Preload-Skript-Dateisystem-Proxy und Service-Layer-Datentransformation.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.mdindex 321ea27..d41654b 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@@ -32,7 +32,9 @@ flowchart LRVerdict --> Generator```-## Warum das passiert+## Lehrbeispiel++> Lehrbeispiel: Dieses Szenario und seine Zahlen dienen der Erklärung und sind keine Messwerte eines veröffentlichten Experiments.### Die echten Kosten fehlender Beobachtbarkeit@@ -44,7 +46,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.+Fortschritt und Prüfergebnisse gehören in versionierte Dateien, damit die nächste Sitzung den Zustand prüfen kann. Die Quelle beschreibt den Mechanismus ohne prozentuale Zeitersparnis. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)### Ein realistisches Claude-Code-Szenario@@ -116,7 +118,9 @@ Mache aus "ist es gut oder nicht" eine quantifizierbare Bewertung:Erzeuge einen trace für jede harness-Session, einen span für jede Aufgabe und sub-spans für jeden Verifikationsschritt. Standardattribute annotieren wichtige Informationen. So integrieren sich Beobachtbarkeitsdaten in Tools wie Jaeger oder Zipkin.-## Praxisfall+## Lehrbeispiel++> Lehrbeispiel: Dieses Szenario und seine Zahlen dienen der Erklärung und sind keine Messwerte eines veröffentlichten Experiments.Ein harness mit planner-generator-evaluator-Workflow führt "Dark Mode Support hinzufügen" aus:@@ -136,7 +140,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.**+- Fortschritt und Prüfergebnisse gehören in versionierte Dateien, damit die nächste Sitzung den Zustand prüfen kann. Die Quelle beschreibt den Mechanismus ohne prozentuale Zeitersparnis.## Weiterführende Literaturdiff --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.mdindex 4b283d2..4af9675 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@@ -5,6 +5,8 @@# Lektion 12. Sauberes Handoff am Ende jeder Session+> Technische Richtwerte: Die Zahlen sind anpassbare Lehrannahmen, keine experimentell bestätigten Grenzen. Tokenzahlen hängen von Tokenizer und Inhalt ab, nicht allein von Zeilen.+Ihr Agent läuft den ganzen Nachmittag, ändert 20 Dateien, committet den Code, die Session endet. Die nächste Agenten-Session startet und stellt sofort fest: der Build ist kaputt, die Tests sind rot, temporäre Debug-Dateien sind überall, die Feature-Liste wurde nicht aktualisiert und der Fortschritt ist völlig unklar. Die neue Session verbringt ihre ersten 30 Minuten nur damit herauszufinden, „was die letzte Session eigentlich gemacht hat."Sowohl OpenAI als auch Anthropic stellen klar: **Langfristige Zuverlässigkeit hängt von operativer Disziplin ab, nicht nur vom Erfolg einzelner Läufe.** Die Qualität des Zustands beim Session-Exit bestimmt direkt die Effizienz der nächsten Session. Betrachten Sie es wie Git-Best-Practices — jeder Commit sollte eine atomare, kompilierbare Änderung sein, kein Haufen halbfertigen Codes.@@ -52,6 +54,8 @@ flowchart LRLehmans 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.+> Lehrbeispiel: Dieses Szenario und seine Zahlen dienen der Erklärung und sind keine Messwerte eines veröffentlichten Experiments.+Echte Daten sind aussagekräftig. Ein Projekt, das 12 Wochen lang mit Agenten entwickelt wurde, ohne Cleanup-Strategie:- Woche 1: Build-Pass-Rate 100%, Test-Pass-Rate 100%, neue Session Startup 5 Min.@@ -64,8 +68,6 @@ 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.-### Fünf Dimensionen des Clean StateClean State bedeutet nicht nur „der Code kompiliert". Es sind fünf Dimensionen, die zusammen bewertet werden:@@ -74,7 +76,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.+Fortschritt und Prüfergebnisse gehören in versionierte Dateien, damit die nächste Sitzung den Zustand prüfen kann. Die Quelle beschreibt den Mechanismus ohne prozentuale Zeitersparnis. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)**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.@@ -150,7 +152,9 @@ git checkout -- .env.local # Restore to known statenpm run test # Verify cleanup didn't break anything```-## Fallbeispiel aus der Praxis+## Lehrbeispiel++> Lehrbeispiel: Dieses Szenario und seine Zahlen dienen der Erklärung und sind keine Messwerte eines veröffentlichten Experiments.Eine Electron-App, die über 12 Wochen mit Agenten entwickelt wurde, im Vergleich zweier Ansätze:@@ -158,8 +162,6 @@ 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.-## Wichtigste Erkenntnisse- **Clean State ist eine notwendige Bedingung für den Session-Abschluss** — kein optionales Aufräumen, sondern Teil der „Definition of Done".diff --git a/docs/de/lectures/lecture-13-loop-engineering/index.md b/docs/de/lectures/lecture-13-loop-engineering/index.mdindex a9425c4..fbce8d4 100644--- a/docs/de/lectures/lecture-13-loop-engineering/index.md+++ b/docs/de/lectures/lecture-13-loop-engineering/index.md@@ -5,6 +5,8 @@# Lektion 13. Von manuellen Prompts zu autonomen Loops+> Technische Richtwerte: Die Zahlen sind anpassbare Lehrannahmen, keine experimentell bestätigten Grenzen. Tokenzahlen hängen von Tokenizer und Inhalt ab, nicht allein von Zeilen.+Alles, was du in den ersten zwölf Lektionen gelernt hast, beruht auf einer Annahme: **du sitzt an der Tastatur und tippst Anweisungen nacheinander ein.**Du hast `AGENTS.md` geschrieben (Lektionen 1–4), State-Management aufgebaut (Lektionen 5–6), den Scope mit Feature-Listen begrenzt (Lektionen 7–8), saubere Übergaben am Sitzungsende hinterlassen (Lektionen 9, 12) und die Runtime beobachtbar gemacht (Lektionen 10–11). Aber der Auslöser für alles warst immer du. Der Agent hat nie selbst entschieden, wann er mit der Arbeit beginnt — weil niemand auf „Start“ gedrückt hat.@@ -96,7 +98,13 @@ 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.+Boris Cherny · 2025-12-27++| PR | Git commits | + LoC | − LoC | Model |+| --- | --- | --- | --- | --- |+| 259 / 30 days | 497 | 40,000 | 38,000 | Claude Code + Opus 4.5 |++Selbstberichtete persönliche Entwicklungsleistung, keine Benchmark-Erfolgsquote und kein Beleg für Arbeit ohne menschliche Aufsicht. [Boris Cherny](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)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.@@ -267,7 +275,7 @@ flowchart TDDas 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.+Selbstberichtete persönliche Entwicklungsleistung, keine Benchmark-Erfolgsquote und kein Beleg für Arbeit ohne menschliche Aufsicht.## Generator/Evaluator-Trennung: Warum du das Modell nicht seine eigene Arbeit benoten lassen kannst@@ -293,7 +301,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.+[Karpathy: autoresearch](https://github.com/karpathy/autoresearch) · [announcement](https://x.com/karpathy/status/2030371219518931079)### Drei Dateien, drei Rollen@@ -343,8 +351,6 @@ flowchart TD8b --> 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.-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“.### Ausgabe: Was du siehst, wenn du aufwachst@@ -359,6 +365,8 @@ Nur Commits, die tatsächlich verbessert haben, bleiben auf dem Main-Branch. AllJedes einzelne Experiment — Erfolg oder Misserfolg — wird protokolliert:+> Lehrbeispiel: Dieses Szenario und seine Zahlen dienen der Erklärung und sind keine Messwerte eines veröffentlichten Experiments.+```timestamp commit_hash val_bpb vram_mb description--------- ------------- ---------- ---------- ----------------------------@@ -375,11 +383,10 @@ 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:+- Reduzierte nanochat's GPT-2-level Trainingszeit auf 8×H100 von **2,02 Stunden → 1,80 Stunden**, etwa **10.89% schneller**+- Funde umfassten: Lernratenanpassungen, Optimierer-Tuning, Aktivierungswechsel, Attention-Muster-Optimierungen usw. [Karpathy: leaderboard commit](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b) · [tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)-- 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.+> Lehrbeispiel: Dieses Szenario und seine Zahlen dienen der Erklärung und sind keine Messwerte eines veröffentlichten Experiments.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.@@ -399,7 +406,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.**+Produktionsberichte isolieren keinen einzelnen kausalen Beitrag. Benchmarkwerte gelten für Modell, Scaffold, Datensatz und Auswertung, nicht für jede Produktionsaufgabe.### 3. Kognitive Kapitulationdiff --git a/docs/de/lectures/lecture-14-graph-engineering/index.md b/docs/de/lectures/lecture-14-graph-engineering/index.mdindex 29daf7c..f39187e 100644--- a/docs/de/lectures/lecture-14-graph-engineering/index.md+++ b/docs/de/lectures/lecture-14-graph-engineering/index.md@@ -261,7 +261,7 @@ Zuerst ziehe die Linie: **„Graph Engineering“ ist ein Name, der erst nach de**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)**Projekte vor der Veröffentlichung (sie nennen es nicht Graph Engineering — aber mit ihnen baust du tatsächlich)**@@ -346,4 +346,4 @@ Nicht jede Aufgabe verdient einen Graphen. Fünf Kriterien — versuche mindeste4. **Bewerte einen Kandidaten mit den fünf Kriterien:** Wähle eine Aufgabe, bei der du hin- und hergerissen bist, sie zu „graphifizieren“, und bewerte sie gegen die fünf Kriterien. Sie braucht mindestens drei, um einen Graphen wert zu sein. Wenn sie unter drei landet, braucht sie eigentlich ein besseres Workflow-Skript — zeichne keinen Graphen nur, um einen Graphen zu zeichnen.-5. **Verwandle dein `graph.md` in ein ausführbares Programm:** Folge den sechs Schritten in „Baue deinen ersten Graphen von Grund auf“ und implementiere dein Maker-Checker-Diagramm als lauffähigen Graphen (Referenzimplementierung: `code/maker_checker_graph.py`, geschrieben mit LangGraph). Überspringe keinen der sechs: den Status definieren, die Knoten auflisten, die Kanten verdrahten, den Router schreiben, einen Checkpoint anhängen, ausführen. Vergleiche dann das Diagramm mit dem Code und finde die erste Stelle, an der sie nicht übereinstimmen, und erkläre, warum — war das Diagramm falsch oder der Code falsch?\ No newline at end of file+5. **Verwandle dein `graph.md` in ein ausführbares Programm:** Folge den sechs Schritten in „Baue deinen ersten Graphen von Grund auf“ und implementiere dein Maker-Checker-Diagramm als lauffähigen Graphen (Referenzimplementierung: `code/maker_checker_graph.py`, geschrieben mit LangGraph). Überspringe keinen der sechs: den Status definieren, die Knoten auflisten, die Kanten verdrahten, den Router schreiben, einen Checkpoint anhängen, ausführen. Vergleiche dann das Diagramm mit dem Code und finde die erste Stelle, an der sie nicht übereinstimmen, und erkläre, warum — war das Diagramm falsch oder der Code falsch?diff --git a/docs/de/resources/reference/index.md b/docs/de/resources/reference/index.mdindex 2e163e3..0d242ac 100644--- a/docs/de/resources/reference/index.md+++ b/docs/de/resources/reference/index.md@@ -47,6 +47,11 @@ Harness-Module.- [On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents](https://arxiv.org/html/2601.20404v2): gpt-5.2-codex; 10 repos / 124 PR tasks; Table 1.+- [Anthropic: Sonnet 4.5 — SWE-bench Verified methodology (2025-09-29)](https://www.anthropic.com/news/claude-sonnet-4-5)+- [Boris Cherny: personal 30-day production report (2025-12-27)](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)+- [Karpathy: measured autoresearch leaderboard improvement](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b)+- [Karpathy: two-day autonomous tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)+## Empfohlene Lesereihenfolge1. `method-map.md`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.mdindex 890bdb3..9be23f2 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,17 +5,30 @@# 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.+Claude Sonnet 4.5 · 2025-09-29 · SWE-bench Verified++| Score | Tasks | Trials | Scaffold |+| --- | --- | --- | --- |+| 77.2% | 500 | 10 | bash + string replacement |++Reported engineering outcomes do not isolate the causal contribution of one component. Benchmark scores apply to the stated model, scaffold, dataset and evaluation settings, not every production task. [Anthropic: methodology](https://www.anthropic.com/news/claude-sonnet-4-5)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.+> Same model and prompt, different runtime and cost budgets. This is a reported application comparison, not an equal-budget experiment isolating one harness component. Core gameplay worked, but bugs and limitations remained. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++Same model and prompt, different runtime and cost budgets. This is a reported application comparison, not an equal-budget experiment isolating one harness component. Core gameplay worked, but bugs and limitations remained. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++| Opus 4.5 | Duration | USD |+| --- | --- | --- |+| Solo | 20 min | 9 |+| Full harness | 6 h | 200 |They didn't change the model. Opus 4.5 was still Opus 4.5. What changed was the tack.-OpenAI's 2025 harness engineering article puts it even more bluntly. They said that Codex in a well-harnessed repository goes from "unreliable" straight to "reliable." Note the wording — not "a bit better," but a qualitative leap. Harness here means **all the engineering infrastructure beyond the model weights.**+Reported engineering outcomes do not isolate the causal contribution of one component. Benchmark scores apply to the stated model, scaffold, dataset and evaluation settings, not every production task. [OpenAI: 2026-02-11](https://openai.com/index/harness-engineering/)## Where Agents Actually Get Stuck@@ -25,15 +38,15 @@ The specific failure modes really come down to just a handful:- **Implicit conventions not written down — the agent has no way to comply.** Your whole team uses the new SQLAlchemy 2.0 syntax, but the agent writes 1.x code by default. All API endpoints must go through OAuth 2.0 authentication, but that rule only exists in your head and a Slack message from three months ago. The agent has no idea — it's not that it doesn't want to comply, it literally has never seen the rule.- **Incomplete environment setup — the agent spends energy fixing the environment.** Incomplete dev setup, missing dependencies, wrong tool versions — the agent burns precious context window on `pip install` errors and Node version conflicts instead of doing the actual work you gave it.- **No verification methods — the agent calls it done when it feels done.** No tests, no lint, or verification commands that were never communicated to the agent. The agent writes code, looks it over, decides it seems fine, and declares completion. Anthropic also observed an interesting phenomenon: when agents sense their context is running low, they rush to finish, skip verification steps, and choose a simple solution over the optimal one. They call this "context anxiety."-- **Cross-session state loss — every new session starts from scratch.** All discoveries from the previous session are lost. Every new session has to re-explore the project structure and re-understand the code organization. Agents without persistent state see failure rates spike sharply on tasks exceeding 30 minutes.+- **Cross-session state loss — every new session starts from scratch.** — Record progress and verification results in versioned files so the next session can inspect project state. The cited source describes the mechanism without reporting a percentage reduction in startup time. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## Key TerminologyWith 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.+- Reported engineering outcomes do not isolate the causal contribution of one component. Benchmark scores apply to the stated model, scaffold, dataset and evaluation settings, not every production task.- **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.- **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,15 +73,17 @@ 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 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. [OpenAI](https://openai.com/index/harness-engineering/)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?"-This experiment directly proves this lecture's core thesis: **the same model produces fundamentally different output in a bare environment versus one with a complete harness.** The model didn't change. The environment did.+Reported engineering outcomes do not isolate the causal contribution of one component. Benchmark scores apply to the stated model, scaffold, dataset and evaluation settings, not every production task.> Source: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)-## A More Down-to-Earth Example+## Illustrative Example++> Teaching illustration: this scenario and its numerical values are assumed for explanation, not observations from a published experiment.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).@@ -94,6 +109,8 @@ They didn't change the model. They changed the harness.- [SWE-bench Leaderboard](https://www.swebench.com/)- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)+- [Anthropic: Sonnet 4.5 SWE-bench methodology, 2025-09-29](https://www.anthropic.com/news/claude-sonnet-4-5)+## Exercises1. **Comparison experiment**: Pick a codebase you know well and a non-trivial modification task. First, run the agent with no harness support and record failures. Then add an `AGENTS.md` and explicit verification commands, and run again with the same agent. Compare the two results, attributing each failure to one of the five defense layers.diff --git a/docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/en/lectures/lecture-02-what-a-harness-actually-is/index.mdindex ec80257..7f7e4e7 100644--- a/docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -70,7 +70,9 @@ Missing any one of the five subsystems means an incomplete harness, and the agen**Quantifying harness component value**: Use a "controlled variable exclusion test." Keep the model fixed, remove the five subsystems one at a time, and see which subsystem's removal causes the biggest performance drop. The component with the largest drop has the highest marginal contribution for the current task and is worth prioritizing. Whether to strengthen it depends on failure attribution, not just the size of the drop. Components with near-zero impact should not be dismissed outright: they may be redundant, poorly designed, or simply not exercised by the current task. This experiment answers "which component is most valuable right now" — it cannot, by itself, prove "where the bottleneck is." To truly locate a bottleneck, you must first examine failure records and attributions: was the task unclear, was context insufficient, was the environment unreproducible, was verification feedback missing, or was state management broken? Component ablation results can only serve as supporting evidence.-## A Team's Real Story+## Illustrative Example++> Teaching illustration: this scenario and its numerical values are assumed for explanation, not observations from a published experiment.A team used GPT-4o to develop a TypeScript + React frontend application (~20,000 lines of code). They went through four stages, which were essentially adding harness components one at a time:diff --git a/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdindex 8991ec2..019c731 100644--- a/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md+++ b/docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -5,6 +5,8 @@# Lecture 03. Making the Repository the Single Source of Truth+> Engineering guideline: numerical cutoffs here are adjustable teaching defaults, not experimentally established thresholds. Token counts depend on the tokenizer and content, not line count alone.+Your team's architecture decisions are scattered across Confluence, Slack, Jira, and a few senior engineers' heads. For humans this barely works — you can ask a colleague, search chat logs, dig through documentation, and if all else fails, you can corner someone in the break room. But for an AI agent, information that's not in the repository simply does not exist.This isn't an exaggeration. An agent has only three sources of input: system prompts and task descriptions, file contents from the repository, and tool execution output. Your Slack history, Jira tickets, Confluence pages, and that architecture decision you hashed out with a colleague on Friday afternoon — the agent can't see any of it. It can't "go ask someone" or "search the chat logs." Its entire working world is the repository itself. Everything outside, it knows nothing about.diff --git a/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdindex c01a157..2e0778e 100644--- a/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md+++ b/docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -5,6 +5,8 @@# Lecture 04. Split Instructions Across Files+> Engineering guideline: numerical cutoffs here are adjustable teaching defaults, not experimentally established thresholds. Token counts depend on the tokenizer and content, not line count alone.+You started taking harness engineering seriously — good. You created an `AGENTS.md` and packed in every rule, constraint, and lesson learned you could think of. One month later the file had ballooned to 300 lines, two months 450, three months 600. Then you notice the agent's performance is actually getting worse: on a simple bug fix, the agent burns through huge amounts of context processing irrelevant deployment instructions; a critical security constraint buried at line 300 gets ignored outright; three contradictory code style rules mean the agent picks one at random each time.This is the "giant instruction file" trap. Everything seems useful, so you cram it all in, and finding one specific rule means rifling through the entire file. You wrote 600 lines, but only a third of it is relevant to the task at hand.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.mdindex c5135b5..c951673 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@@ -5,6 +5,8 @@# Lecture 05. Keeping Context Alive Across Sessions+> Engineering guideline: numerical cutoffs here are adjustable teaching defaults, not experimentally established thresholds. Token counts depend on the tokenizer and content, not line count alone.+You ask Claude Code to implement a complete feature. It runs for 30 minutes, does most of the work, but context is running low. You start a new session to continue — and discover it doesn't remember what decisions were made last time, why option A was chosen over option B, which files were already modified, or what state the tests are in. It spends 15 minutes re-exploring the project, and might take an inconsistent approach from last time.This is the real dilemma AI coding agents face in cross-session tasks. This lecture explains why agents "lose the thread" during long tasks, and how structured state persistence lets a new session quickly pick up where the last one left off.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.mdindex 3f1f74a..406f206 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@@ -5,6 +5,8 @@# Lecture 06. Make the Agent Initialize Before Every Work Session+> Engineering guideline: numerical cutoffs here are adjustable teaching defaults, not experimentally established thresholds. Token counts depend on the tokenizer and content, not line count alone.+You start a new agent session and tell it "add a search feature." It jumps straight into coding — admirable enthusiasm. After 20 minutes it discovers the test framework isn't configured properly, spends another 10 minutes fixing that, then finds the database migration script format is wrong, more fiddling. The search feature does get added in the end, but the whole session was inefficient. Most of the time went to "figuring out how this project works" rather than writing the search feature itself.The better approach: before letting the agent start working, use a separate phase to get the base environment ready, run verification commands through, and understand the project structure. Initialization work should not be crammed together with feature implementation — they are two fundamentally different kinds of tasks.@@ -37,6 +39,8 @@ flowchart TB## What Happens When You Mix Them+> Teaching illustration: this scenario and its numerical values are assumed for explanation, not observations from a published experiment.+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.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 +49,7 @@ Context budget is being wasted too. Initialization work (configuring environmentThe 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: initializer / coding agent](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)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.@@ -122,7 +126,9 @@ OpenAI's Codex harness engineering guide also emphasizes the "repository as oper- [ ] Everything committed to git```-## Real-World Example+## Illustrative Example++> Teaching illustration: this scenario and its numerical values are assumed for explanation, not observations from a published experiment.Two initialization approaches for a React frontend project, compared: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.mdindex 7912d6b..9823e09 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@@ -5,6 +5,8 @@# Lecture 07. Draw Clear Task Boundaries for Agents+> Engineering guideline: numerical cutoffs here are adjustable teaching defaults, not experimentally established thresholds. Token counts depend on the tokenizer and content, not line count alone.+You tell Claude Code to "add user authentication to this project," and it starts modifying the database schema, writing routes, changing frontend components, and — while it's at it — refactoring the error-handling middleware. Two hours later you check: 12 files modified, 800 lines of new code, and not a single feature works end-to-end.Agents are born with an impulse to "do a little extra" — they see related things and just handle them along the way. The problem is, doing too many things at once almost guarantees none of them get done well.@@ -26,7 +28,7 @@ Claude Code's real behavior is telling. Ask it to "add user registration" and itSix 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: incremental feature work](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## WIP=1 Workflow@@ -98,7 +100,9 @@ Use a machine-readable file (JSON or Markdown) to record all task states. Any neThe harness should continuously track VCR (Verified Completion Rate) = verified tasks / activated tasks. Block new task activations when VCR < 1.0.-## Real-World Case+## Illustrative Example++> Teaching illustration: this scenario and its numerical values are assumed for explanation, not observations from a published experiment.A REST API project with 8 features, two strategies compared: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.mdindex f03a8f9..05cb553 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@@ -5,6 +5,8 @@# Lecture 08. Use Feature Lists to Constrain What the Agent Does+> Engineering guideline: numerical cutoffs here are adjustable teaching defaults, not experimentally established thresholds. Token counts depend on the tokenizer and content, not line count alone.+You ask an agent to build an e-commerce site. After it finishes, it tells you "done." You look at the code — user authentication works, but the checkout button in the shopping cart does nothing, and the payment flow isn't connected at all. Where did things go wrong? You never told it what "done" means, so it used its own standard: "I wrote a lot of code and it looks fairly complete."Feature lists, in many people's eyes, are just a memo — write things down so you don't forget, then toss them aside. But in the harness world, a feature list isn't a memo for humans. It's the foundational structure the entire harness is built on. The scheduler relies on it to pick tasks, the verifier relies on it to judge completion, and the handoff reporter relies on it to generate summaries. Without it, these components have no shared consensus to depend on.@@ -25,7 +27,7 @@ Did user auth, shopping cart mostly done, still need paymentsCan 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%.+Record progress and verification results in versioned files so the next session can inspect project state. The cited source describes the mechanism without reporting a percentage reduction in startup time. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## Feature State Machine@@ -108,7 +110,9 @@ The agent can't directly change a feature's state to `passing`. It can only submEach feature item should be scoped to "completable in one session." Too broad and it won't finish; too narrow and the management overhead grows. "User can add items to cart" is good granularity. "Implement the shopping cart" is too broad. "Create the name field on the Cart model" is too narrow.-## Real-World Case+## Illustrative Example++> Teaching illustration: this scenario and its numerical values are assumed for explanation, not observations from a published experiment.An e-commerce platform with 10 features. Two tracking approaches compared:@@ -116,8 +120,6 @@ 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.-## Key Takeaways- **Feature lists are the harness's foundational structure**, not memos for humans. The scheduler, verifier, and handoff reporter all depend on them.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.mdindex 85b782c..d10dd34 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@@ -5,6 +5,8 @@# Lecture 9. Preventing Agents from Declaring Victory Too Early+> Engineering guideline: numerical cutoffs here are adjustable teaching defaults, not experimentally established thresholds. Token counts depend on the tokenizer and content, not line count alone.+You ask an agent to implement a "password reset" feature. It modifies the database schema, writes the API endpoint, adds the email template, runs the unit tests (all pass), and then confidently tells you "it's done." But when you actually try to run it—the password reset link can't be sent because the email service config is missing; the database migration fails halfway through, leaving the schema in an inconsistent state; and the end-to-end flow hasn't been executed even once.This isn't an isolated incident. The classic 2017 ICML paper by Guo et al. proved: **modern neural networks are systematically overconfident**—the confidence reported by models is significantly higher than their actual accuracy. AI coding agents are no different. They "feel" done, but in reality they're far from it. Your harness must replace the agent's "feelings" with externalized, execution-based verification.@@ -70,7 +72,7 @@ An independent evaluation agent, specifically tuned to be "nitpicky," is far mor| 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) |-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."+Reported engineering outcomes do not isolate the causal contribution of one component. Benchmark scores apply to the stated model, scaffold, dataset and evaluation settings, not every production task. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)> Source: [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)@@ -78,6 +80,8 @@ This is the exact same model (Opus 4.5) with the exact same prompt ("build a 2D### 1. Externalize Termination Judgment+> Same model and prompt, different runtime and cost budgets. This is a reported application comparison, not an equal-budget experiment isolating one harness component. Core gameplay worked, but bugs and limitations remained. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)+The completion judgment should not be made by the agent itself. The harness independently executes termination validation, using runtime signals as input rather than the agent's confidence. In CLAUDE.md, you can spell this out:```@@ -109,7 +113,9 @@ Effective runtime signals include:- Were database writes, file operations, and other side effects correct?- Were temporary resources cleaned up?-## Real-World Case+## Illustrative Example++> Teaching illustration: this scenario and its numerical values are assumed for explanation, not observations from a published experiment.**Task**: Implement user password reset functionality. Involves database operations, email sending, and API endpoint modifications.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.mdindex 65f28b8..3330155 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@@ -5,6 +5,8 @@# Lecture 10. Only a Full Pipeline Run Counts as Real Verification+> Engineering guideline: numerical cutoffs here are adjustable teaching defaults, not experimentally established thresholds. Token counts depend on the tokenizer and content, not line count alone.+You ask the agent to add a file export feature to an Electron app. It writes the renderer component, the preload script, and the service layer logic. Unit tests for every component pass. The agent says "done." You actually click the export button — the file path format is wrong, the progress bar doesn't respond, and exporting large files leaks memory. Five component boundary defects, and unit tests didn't catch a single one.Each part looks "correct" on its own, but problems surface the moment they are wired together. Google's Testing Pyramid tells us that a large base of unit tests is essential, but stopping there means you will systematically miss component interaction issues. For AI coding agents this problem is even worse, because agents tend to run only the fastest tests and then declare completion. **Only end-to-end testing can prove the absence of system-level defects.**@@ -114,7 +116,9 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.reaEvery time you discover a new category of agent error during code review, turn it into an automated check. A month later your harness will be far stronger than it was at the start of the month.-## Real-World Case+## Illustrative Example++> Teaching illustration: this scenario and its numerical values are assumed for explanation, not observations from a published experiment.**Task**: Implement a file export feature in an Electron app. Involves renderer process UI, preload script filesystem proxy, and service layer data transformation.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.mdindex bca8172..de9d808 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,15 +21,17 @@ 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.+Record progress and verification results in versioned files so the next session can inspect project state. The cited source describes the mechanism without reporting a percentage reduction in startup time. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)-## A Real Claude Code Scenario+## Illustrative Example++> Teaching illustration: this scenario and its numerical values are assumed for explanation, not observations from a published experiment.Consider a harness using a "planner-generator-evaluator" three-role workflow, executing the task "add dark mode to the app."**Without observability:** The planner outputs a vague description. The generator implements dark mode based on that vagueness, but the result doesn't match the planner's implicit expectations. The evaluator rejects it based on their own implicit standards but can't articulate what's specifically wrong — just "it doesn't feel right." The generator retries blindly on vague rejection reasons. The cycle repeats 3-4 times, taking about 45 minutes, and barely produces an acceptable output.-**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.+**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. [W3C: contrast minimum](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)3x efficiency difference. The only variable is observability.@@ -122,7 +124,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:+This table describes the updated Opus 4.6 harness: one architecture with three agents, not three architectures. Sprint decomposition was removed. The planner creates the specification; the builder implements it; the evaluator tests the running application and sends feedback for another build round. [Anthropic: updated harness results](https://www.anthropic.com/engineering/harness-design-long-running-apps)| Agent & Phase | Duration | Cost ||---------------|----------|------|@@ -137,12 +139,6 @@ In March 2026, Anthropic published a systematic harness experiment. They ran theEach of the three agents had a distinct role, and each played a clear part in observability:-**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.--**Generator:** Implements feature by feature, sprint by sprint. Before each sprint, it negotiates a sprint contract with the evaluator defining what "done" means for that feature block. It then implements according to the contract, self-evaluates, and hands off to QA.--**Evaluator:** Uses Playwright MCP to interact with the running app like a real user — testing UI functionality, API endpoints, and database state. It scores each sprint across four dimensions: product depth, functionality, visual design, and code quality. Each dimension has a hard threshold — if any falls short, the sprint fails and the generator receives detailed feedback for fixes.-Example feedback from QA round 1: "This is a visually impressive app with good AI integration, but several core DAW features are presentational only, lacking interaction depth: clips can't be dragged/moved, there's no instrument UI panel (synth knobs, drum pads), and no visual effects editor (EQ curves, compressor meters)." These aren't edge cases — they're the core interactions that make a DAW usable. Specific, evidence-backed feedback — not "it doesn't feel right."The evaluator wasn't always this sharp. Early versions would identify reasonable issues, then talk themselves into dismissing those issues as not severe, ultimately approving the work. The fix: read the evaluator's logs, find the points where its judgment diverged from human judgment, and update the QA prompt to address those specific problems. After several rounds of this development loop, the evaluator's scoring became reliable.@@ -155,7 +151,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.**+- Record progress and verification results in versioned files so the next session can inspect project state. The cited source describes the mechanism without reporting a percentage reduction in startup time.## Further Readingdiff --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.mdindex 6f2be17..f44bc56 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@@ -5,6 +5,8 @@# Lecture 12. Leave a Clean Handoff at the End of Every Session+> Engineering guideline: numerical cutoffs here are adjustable teaching defaults, not experimentally established thresholds. Token counts depend on the tokenizer and content, not line count alone.+Your agent runs all afternoon, modifies 20 files, commits the code, and the session ends. The next agent session starts up and immediately discovers: build is broken, tests are red, temporary debug files are scattered everywhere, the feature list hasn't been updated, and progress is completely opaque. The first 30 minutes of the new session are spent entirely on "figuring out what the last session actually did."Both OpenAI and Anthropic state clearly: **long-term reliability depends on operational discipline, not just single-run success.** The quality of state at the end of each session directly determines the next session's efficiency.@@ -15,7 +17,7 @@ Lehman's laws of software evolution tell us that systems undergoing continuous cDuring 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:+OpenAI reports spending Fridays on cleanup: one workday, or 20% of the week. This is not 20% of Friday. [OpenAI](https://openai.com/index/harness-engineering/)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 +45,7 @@ flowchart LRFix --> 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.+Record progress and verification results in versioned files so the next session can inspect project state. The cited source describes the mechanism without reporting a percentage reduction in startup time. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)```mermaidflowchart LR@@ -72,6 +74,8 @@ The most common mental trap is "no time to clean up this session, I'll do it nexWorse, 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.+> Teaching illustration: this scenario and its numerical values are assumed for explanation, not observations from a published experiment.+The numbers tell the story. A project developed with agents for 12 weeks, without a cleanup strategy:- Week 1: Build pass rate 100%, test pass rate 100%, new session startup 5 min@@ -84,8 +88,6 @@ 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.-## How to Do It### 1. Clean State Is a Necessary Condition for Completion@@ -137,7 +139,7 @@ New sessions read this document and immediately know where to prioritize. Fix thEvery 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.+This table describes the updated Opus 4.6 harness: one architecture with three agents, not three architectures. Sprint decomposition was removed. The planner creates the specification; the builder implements it; the evaluator tests the running application and sends feedback for another build round. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)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.@@ -162,7 +164,9 @@ When agent output far exceeds human review capacity, the traditional merge philo**Caveat**: This is irresponsible in a low-throughput environment. But when agent output far exceeds human attention, it's often the correct tradeoff. The key criterion: **average cost of fixing a bug vs. average cost of waiting for a human to review a PR.** When the former is lower than the latter, fast merging is the right call.-## Real-World Case+## Illustrative Example++> Teaching illustration: this scenario and its numerical values are assumed for explanation, not observations from a published experiment.An Electron app developed with agents over 12 weeks, comparing two approaches:@@ -170,8 +174,6 @@ 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.-## Key Takeaways- **Clean state is a necessary condition for session completion** — not optional housekeeping, but part of the "definition of done."diff --git a/docs/en/lectures/lecture-13-loop-engineering/index.md b/docs/en/lectures/lecture-13-loop-engineering/index.mdindex 9b1b319..ab3f806 100644--- a/docs/en/lectures/lecture-13-loop-engineering/index.md+++ b/docs/en/lectures/lecture-13-loop-engineering/index.md@@ -5,6 +5,8 @@# Lecture 13. From Manual Prompting to Autonomous Loops+> Engineering guideline: numerical cutoffs here are adjustable teaching defaults, not experimentally established thresholds. Token counts depend on the tokenizer and content, not line count alone.+Everything you learned in the first twelve lectures rests on one assumption: **you are sitting at the keyboard, typing instructions one at a time.**You wrote `AGENTS.md` (Lectures 1–4), built state management (Lectures 5–6), constrained scope with feature lists (Lectures 7–8), left clean handoffs at session end (Lectures 9, 12), and made the runtime observable (Lectures 10–11). But the trigger for all of it was always you. The agent never decided on its own when to start working — because no one pressed "start."@@ -86,6 +88,8 @@ You don't have to type `/goal` every time. But understanding where it came from## June 2026: Three People Lit the Same Fuse in One Week+> Teaching illustration: this scenario and its numerical values are assumed for explanation, not observations from a published experiment.+In the first week of June 2026, three practitioners building coding agent infrastructure — without comparing notes — said the same thing in different words.**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."@@ -96,7 +100,13 @@ 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.+Boris Cherny · 2025-12-27++| PR | Git commits | + LoC | − LoC | Model |+| --- | --- | --- | --- | --- |+| 259 / 30 days | 497 | 40,000 | 38,000 | Claude Code + Opus 4.5 |++Author-reported personal production activity; this is not a benchmark success rate or evidence that the whole team worked without human oversight. [Boris Cherny](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)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.@@ -267,7 +277,7 @@ flowchart TDThis 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.+Author-reported personal production activity; this is not a benchmark success rate or evidence that the whole team worked without human oversight.## Generator/Evaluator Separation: Why You Can't Let the Model Grade Its Own Work@@ -293,7 +303,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.+[Karpathy: autoresearch](https://github.com/karpathy/autoresearch) · [announcement](https://x.com/karpathy/status/2030371219518931079)### Three Files, Three Roles@@ -343,8 +353,6 @@ flowchart TD8b --> 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 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."### Output: What You See When You Wake Up@@ -359,6 +367,8 @@ Only commits that actually improved stay on the main branch. Everything that faiEvery single experiment — success or failure — is logged:+> Teaching illustration: this scenario and its numerical values are assumed for explanation, not observations from a published experiment.+```timestamp commit_hash val_bpb vram_mb description--------- ------------- ---------- ---------- ----------------------------@@ -375,11 +385,10 @@ 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:+- Reduced nanochat's GPT-2-level training time on 8×H100 from **2.02 hours → 1.80 hours**, about **10.89% faster**+- Findings included: learning rate adjustments, optimizer tuning, activation swaps, attention pattern optimizations, etc. [Karpathy: leaderboard commit](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b) · [tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)-- 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.+> Teaching illustration: this scenario and its numerical values are assumed for explanation, not observations from a published experiment.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.@@ -399,7 +408,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.**+Reported engineering outcomes do not isolate the causal contribution of one component. Benchmark scores apply to the stated model, scaffold, dataset and evaluation settings, not every production task.### 3. Cognitive Surrenderdiff --git a/docs/en/lectures/lecture-14-graph-engineering/index.md b/docs/en/lectures/lecture-14-graph-engineering/index.mdindex 78e4ffb..52aa4c7 100644--- a/docs/en/lectures/lecture-14-graph-engineering/index.md+++ b/docs/en/lectures/lecture-14-graph-engineering/index.md@@ -261,7 +261,7 @@ First, draw the line: **"Graph Engineering" is a name that only exists after Jul**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)**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) — hype-spread data- [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 distinctiondiff --git a/docs/en/resources/reference/index.md b/docs/en/resources/reference/index.mdindex b092532..40b2d54 100644--- a/docs/en/resources/reference/index.md+++ b/docs/en/resources/reference/index.md@@ -75,6 +75,11 @@ source for the course.- [On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents](https://arxiv.org/html/2601.20404v2): gpt-5.2-codex; 10 repos / 124 PR tasks; Table 1.+- [Anthropic: Sonnet 4.5 — SWE-bench Verified methodology (2025-09-29)](https://www.anthropic.com/news/claude-sonnet-4-5)+- [Boris Cherny: personal 30-day production report (2025-12-27)](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)+- [Karpathy: measured autoresearch leaderboard improvement](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b)+- [Karpathy: two-day autonomous tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)+## Suggested Reading Order1. `method-map.md`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.mdindex cff51b6..73d7033 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,26 @@ Te consideras una persona con experiencia en el mundo de la IA: suscripción a CTu 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.+Claude Sonnet 4.5 · 2025-09-29 · SWE-bench Verified++| Score | Tasks | Trials | Scaffold |+| --- | --- | --- | --- |+| 77.2% | 500 | 10 | bash + string replacement |++Los resultados de producción no aíslan una causa. Las puntuaciones corresponden al modelo, scaffold, conjunto de datos y evaluación indicados, no a toda tarea real. [Anthropic: methodology](https://www.anthropic.com/news/claude-sonnet-4-5)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.+> Mismo modelo y prompt, pero distintos presupuestos de tiempo y coste. No es un experimento de igual presupuesto que aísle un componente. El juego funcionaba en lo esencial, pero conservaba errores. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++Mismo modelo y prompt, pero distintos presupuestos de tiempo y coste. No es un experimento de igual presupuesto que aísle un componente. El juego funcionaba en lo esencial, pero conservaba errores. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++| Opus 4.5 | Duration | USD |+| --- | --- | --- |+| Solo | 20 min | 9 |+| Full harness | 6 h | 200 |No cambiaron el modelo. Opus 4.5 seguía siendo Opus 4.5. Lo que cambió fue el equipo de monta.@@ -39,7 +52,7 @@ Las tareas largas que cruzan sesiones son aún peores: los descubrimientos de laCon estos escenarios en mente, estos conceptos ya no son jerga:-- **Brecha de capacidad**: la distancia enorme entre el rendimiento del modelo en benchmarks y su rendimiento en tareas reales. Un 50-60% en SWE-bench Verified significa que casi la mitad de los issues reales no se resuelven.+- Los resultados de producción no aíslan una causa. Las puntuaciones corresponden al modelo, scaffold, conjunto de datos y evaluación indicados, no a toda tarea real.- **Harness**: todo lo que está fuera del modelo: instrucciones, herramientas, entorno, gestión de estado y feedback de verificación. Si no son pesos del modelo, es harness. Es el "equipo de monta" del que hablamos.- **Fallo inducido por harness**: el modelo tiene capacidad suficiente, pero el entorno de ejecución tiene defectos estructurales. El experimento controlado de Anthropic ya lo demostró.- **Brecha de verificación**: la diferencia entre la confianza del agente en su salida y la corrección real. El agente dice "terminé" cuando no terminó. Es el modo de fallo más común.@@ -72,17 +85,19 @@ 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.+Los resultados de producción no aíslan una causa. Las puntuaciones corresponden al modelo, scaffold, conjunto de datos y evaluación indicados, no a toda tarea real. [OpenAI: 2026-02-11](https://openai.com/index/harness-engineering/)-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.+Los resultados de producción no aíslan una causa. Las puntuaciones corresponden al modelo, scaffold, conjunto de datos y evaluación indicados, no a toda tarea real.El progreso inicial fue más lento de lo esperado. No porque Codex no pudiera, sino porque el entorno no estaba completo: al agente le faltaban herramientas, abstracciones y estructuras internas para avanzar hacia objetivos de alto nivel. El trabajo de los ingenieros se convirtió en descomponer metas grandes en bloques pequeños — diseño, código, revisión, test — dejar que el agente los ensamblara y luego usar esos bloques para desbloquear tareas más complejas. Cuando algo fallaba, la solución casi nunca era "intenta más fuerte"; era "qué capacidad le falta al agente, y cómo la hacemos comprensible y ejecutable".-Este experimento demuestra directamente la tesis central de la lección: **el mismo modelo produce resultados fundamentalmente distintos en un entorno desnudo y en uno con harness completo.** El modelo no cambió. El entorno sí.+Los resultados de producción no aíslan una causa. Las puntuaciones corresponden al modelo, scaffold, conjunto de datos y evaluación indicados, no a toda tarea real.> Fuente: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)-## Un ejemplo más cotidiano+## Ejemplo didáctico++> Ejemplo didáctico: el escenario y sus cifras son supuestos para explicar el mecanismo, no mediciones de un experimento publicado.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).@@ -108,6 +123,8 @@ No cambiaron el modelo. Cambiaron el harness.- [SWE-bench Leaderboard](https://www.swebench.com/)- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)+- [Anthropic: Sonnet 4.5 SWE-bench methodology, 2025-09-29](https://www.anthropic.com/news/claude-sonnet-4-5)+## Ejercicios1. **Experimento comparativo**: elige un codebase que conozcas bien y una modificación no trivial. Primero ejecuta el agente sin soporte de harness y registra fallos. Luego añade un `AGENTS.md` con comandos de verificación explícitos y ejecuta de nuevo con el mismo agente. Compara resultados atribuyendo cada fallo a una de las cinco capas.diff --git a/docs/es/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/es/lectures/lecture-02-what-a-harness-actually-is/index.mdindex f40bfe2..a23a52c 100644--- a/docs/es/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/es/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -70,7 +70,9 @@ Que falte cualquier subsistema es como que falte un área funcional en la cocina**Cuantificar el valor de los componentes del harness**: Usa una ablación con el mismo modelo fijo. Mantén el modelo fijo, elimina subsistemas uno a la vez y mide cuál eliminación causa la mayor caída de rendimiento. La mayor caída identifica el componente con mayor contribución marginal en esa tarea; no identifica automáticamente el cuello de botella. Una caída casi nula también necesita interpretación: el componente puede ser redundante, estar mal diseñado o simplemente no haber sido ejercitado por esa tarea. Para diagnosticar cuellos de botella, usa primero registros de fallos y atribución, y usa la ablación como evidencia de apoyo: ¿falló por intención de tarea poco clara, contexto insuficiente, entorno no reproducible, falta de feedback de verificación o gestión de estado rota?-## La historia real de un equipo+## Ejemplo didáctico++> Ejemplo didáctico: el escenario y sus cifras son supuestos para explicar el mecanismo, no mediciones de un experimento publicado.Un equipo usó GPT-4o en una aplicación frontend de TypeScript + React (~20,000 líneas de código). Pasaron por cuatro etapas — esencialmente añadiendo equipamiento de cocina pieza por pieza:diff --git a/docs/es/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/es/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdindex 04beb80..d0ecda0 100644--- a/docs/es/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md+++ b/docs/es/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -5,6 +5,8 @@# Lección 03. Convierte el repositorio en la fuente única de verdad+> Guía de ingeniería: los umbrales son valores didácticos ajustables, no límites demostrados. Los tokens dependen del tokenizador y del contenido, no solo de las líneas.+Las decisiones de arquitectura de tu equipo están dispersas entre Confluence, Slack, Jira y la cabeza de unos cuantos ingenieros senior. Para los humanos esto apenas funciona: puedes preguntar a un compañero, buscar en el historial del chat, revisar documentación. Si todo falla, puedes acorralar a alguien en la sala de descanso. Pero para un agente de IA, la información que no está en el repositorio simplemente no existe.No es una exageración. Piensa en cuáles son realmente las entradas de un agente: prompts de sistema y descripciones de tarea, contenidos de archivos del repositorio y salidas de herramientas. Eso es todo. Tu historial de Slack, tickets de Jira, páginas de Confluence y esa decisión de arquitectura que hablaste con un compañero tomando café un viernes por la tarde: el agente no ve nada de eso. No puede "ir a preguntar a alguien" ni "buscar en el historial del chat". Es un ingeniero encerrado dentro del repositorio; de todo lo que queda fuera no sabe nada.diff --git a/docs/es/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/es/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdindex 8070434..cbe2b09 100644--- a/docs/es/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md+++ b/docs/es/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -5,6 +5,8 @@# Lección 04. Divide las instrucciones entre archivos+> Guía de ingeniería: los umbrales son valores didácticos ajustables, no límites demostrados. Los tokens dependen del tokenizador y del contenido, no solo de las líneas.+Te tomaste en serio la ingeniería de harness. Creaste un `AGENTS.md` y metiste en él todas las reglas, restricciones y lecciones aprendidas que se te ocurrieron. Un mes después el archivo tenía 300 líneas; dos meses después, 450; tres meses después, 600. Entonces notas que el rendimiento del agente está empeorando: para corregir un bug simple, consume mucho contexto procesando instrucciones de despliegue irrelevantes; una restricción de seguridad crítica enterrada en la línea 300 se ignora por completo; tres reglas contradictorias de estilo hacen que el agente elija una al azar cada vez.Esta es la trampa del "archivo gigante de instrucciones". Es como sobrecargar una maleta: todo parece útil, así que lo metes hasta que la cremallera está a punto de reventar. Para encontrar ropa interior de cambio tienes que vaciar toda la bolsa. Cargas una maleta llena, pero en realidad usas quizá un tercio de lo que hay dentro.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.mdindex 802398c..5a0b219 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@@ -5,6 +5,8 @@# Lección 05. Mantén vivo el contexto entre sesiones+> Guía de ingeniería: los umbrales son valores didácticos ajustables, no límites demostrados. Los tokens dependen del tokenizador y del contenido, no solo de las líneas.+Le pides a Claude Code que implemente una funcionalidad completa. Se ejecuta durante 30 minutos, hace la mayor parte del trabajo, pero el contexto se está agotando. Inicias una nueva sesión para continuar — y descubres que no recuerda qué decisiones se tomaron la última vez, por qué se eligió la opción A sobre la B, qué archivos ya fueron modificados o en qué estado están las pruebas. Dedica 15 minutos a re-explorar el proyecto, y podría ser inconsistente con el enfoque anterior.Imagina si fueras un artesano que olvida todo cada mañana al despertar. Tendrías que volver a familiarizarte con todo el sitio de construcción — qué pared está a medio construir, por qué se eligieron ladrillos rojos en lugar de azules, dónde llegaron las tuberías. Peor aún, podrías arrancar una ventana que ya fue instalada ayer, simplemente porque no recordabas que ya estaba hecha.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.mdindex 276941d..7456056 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@@ -5,6 +5,8 @@# Lección 06. Inicializa antes de cada sesión del agente+> Guía de ingeniería: los umbrales son valores didácticos ajustables, no límites demostrados. Los tokens dependen del tokenizador y del contenido, no solo de las líneas.+Inicias una nueva sesión de agente y dices "añade una funcionalidad de búsqueda." Salta directamente a codificar — un entusiasmo admirable. Después de 20 minutos descubre que el framework de pruebas no está configurado correctamente, dedica otros 10 a arreglar eso, luego el formato del script de migración de base de datos está mal, más ajustes. La funcionalidad de búsqueda eventualmente se añade, pero toda la sesión fue ineficiente — la mayor parte del tiempo se fue en "averiguar cómo funciona este proyecto" en lugar de escribir la funcionalidad de búsqueda.El mejor enfoque: antes de dejar que el agente comience a trabajar, usa una fase separada para preparar el entorno base, hacer pasar los comandos de verificación y entender la estructura del proyecto. Es como construir una casa — no viertes los cimientos y levantas paredes simultáneamente. Si lo haces, las paredes se levantan antes de que los cimientos hayan curado, y todo el edificio tiene que ser demolido y empezado de nuevo. Vierte los cimientos primero, deja que curen, luego construye las paredes — limpio y eficiente.@@ -37,6 +39,8 @@ flowchart TB## Qué sucede cuando los mezclas+> Ejemplo didáctico: el escenario y sus cifras son supuestos para explicar el mecanismo, no mediciones de un experimento publicado.+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.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 +49,7 @@ El presupuesto de sesión también se está desperdiciando. El trabajo de iniciaEl 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.+[Anthropic: initializer / coding agent](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)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.@@ -122,7 +126,9 @@ La guía de ingeniería de harness de Codex de OpenAI también enfatiza el princ- [ ] Everything committed to git```-## Ejemplo del mundo real+## Ejemplo didáctico++> Ejemplo didáctico: el escenario y sus cifras son supuestos para explicar el mecanismo, no mediciones de un experimento publicado.Dos enfoques de inicialización para un proyecto frontend de React: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.mdindex b8139ea..c4725a6 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@@ -5,6 +5,8 @@# Lección 07. Define límites claros para las tareas del agente+> Guía de ingeniería: los umbrales son valores didácticos ajustables, no límites demostrados. Los tokens dependen del tokenizador y del contenido, no solo de las líneas.+Le dices a Claude Code que "añada autenticación de usuarios a este proyecto," y comienza a modificar el esquema de la base de datos, escribir rutas, cambiar componentes del frontend y — de paso — refactorizar el middleware de manejo de errores. Dos horas después verificas: 12 archivos modificados, 800 líneas de código nuevo, y ni una sola funcionalidad funciona end-to-end.Morder más de lo que puedes masticar — este dicho se aplica a los agentes de IA especialmente bien. Los agentes nacen con un impulso de "hacer un poco más" — ven cosas relacionadas y simplemente las manejan de paso, como alguien que va al supermercado por una botella de salsa de soya y sale empujando un carrito lleno. El problema es, los humanos que compran demasiado solo desperdician dinero; los agentes haciendo demasiadas cosas simultáneamente significa que ninguna se hace bien.@@ -26,7 +28,7 @@ El comportamiento real de Claude Code es revelador. Pídele que "añada registroSeis 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.+[Anthropic: incremental feature work](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## Flujo de trabajo WIP=1@@ -100,7 +102,9 @@ Usa un archivo legible por máquina (JSON o Markdown) para registrar todos los eEl harness debería rastrear continuamente el VCR (Verified Completion Rate) = tareas verificadas / tareas activadas. Bloquea nuevas activaciones de tareas cuando VCR < 1.0.-## Caso del mundo real+## Ejemplo didáctico++> Ejemplo didáctico: el escenario y sus cifras son supuestos para explicar el mecanismo, no mediciones de un experimento publicado.Un proyecto de API REST con 8 funcionalidades, se compararon dos estrategias: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.mdindex 8a6677b..02746fd 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@@ -5,6 +5,8 @@# Lección 08. Usa listas de funciones para limitar al agente+> Guía de ingeniería: los umbrales son valores didácticos ajustables, no límites demostrados. Los tokens dependen del tokenizador y del contenido, no solo de las líneas.+Pides a un agente que construya un sitio de e-commerce. Cuando termina, te dice "done". Miras el código: la autenticación de usuario funciona, pero el botón de checkout del carrito no hace nada y el flujo de pago no está conectado. El problema: nunca le dijiste qué significa "done", así que usó su propio estándar: "escribí mucho código y parece bastante completo".Para muchas personas, las listas de funciones son solo una nota: escribes cosas para no olvidarlas y luego las dejas de lado. Pero en el mundo del harness, una lista de funciones no es una nota para humanos: es la columna vertebral de todo el harness. El scheduler depende de ella para elegir tareas, el verifier para juzgar la finalización y el handoff reporter para generar resúmenes. Si rompes la columna, todo el cuerpo queda paralizado.@@ -23,7 +25,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%.+Registra progreso y verificación en archivos versionados para que la siguiente sesión inspeccione el estado. La fuente explica el mecanismo sin cuantificar el ahorro de arranque. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## Máquina de estados de funciones@@ -104,7 +106,9 @@ El agente no puede cambiar directamente el estado de una función a `passing`. SCada función debe tener alcance "completable en una sesión". Si es demasiado amplia no terminará; si es demasiado pequeña, crece el coste de gestión. "El usuario puede añadir items al carrito" tiene buena granularidad. "Implementar el carrito" es demasiado amplio. "Crear el campo name en el modelo Cart" es demasiado estrecho. Como cortar un filete: ni la pieza entera ni carne molida.-## Caso real+## Ejemplo didáctico++> Ejemplo didáctico: el escenario y sus cifras son supuestos para explicar el mecanismo, no mediciones de un experimento publicado.Una plataforma e-commerce con 10 funciones. Se compararon dos enfoques de seguimiento:@@ -112,8 +116,6 @@ 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.-## Ideas clave- **Las listas de funciones son la columna vertebral del harness**, no notas para humanos. Scheduler, verifier y handoff reporter dependen de ellas.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.mdindex 3471a2e..1759352 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@@ -5,6 +5,8 @@# Lección 09. Evita que los agentes declaren victoria demasiado pronto+> Guía de ingeniería: los umbrales son valores didácticos ajustables, no límites demostrados. Los tokens dependen del tokenizador y del contenido, no solo de las líneas.+Le pides a un agent que implemente una funcionalidad de "restablecimiento de contraseña". Modifica el esquema de la base de datos, escribe el endpoint de la API, añade la plantilla de correo electrónico, ejecuta las pruebas unitarias (todas pasan) y luego te dice con confianza "ya está". Cuando realmente intentas ejecutarlo—el enlace de restablecimiento no se puede enviar (falta la configuración del servicio de correo electrónico), la migración de la base de datos falla a mitad de camino (inconsistencia en el esquema), y el flujo end-to-end no se ha ejecutado ni una sola vez.Esta sensación no debería resultar desconocida—es como llenar todo el examen, ser el primero en entregarlo con confianza, y luego suspender cuando salen las notas. Que el examen esté lleno no significa que las respuestas sean correctas.@@ -13,6 +15,8 @@ No es un incidente aislado. El clásico artículo de 2017 en ICML de Guo et al.## La pendiente resbaladiza+> Mismo modelo y prompt, pero distintos presupuestos de tiempo y coste. No es un experimento de igual presupuesto que aísle un componente. El juego funcionaba en lo esencial, pero conservaba errores. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)+Las declaraciones prematuras de finalización casi siempre siguen el mismo patrón: el código parece correcto—la sintaxis es correcta, la lógica parece razonable, y el análisis estático no muestra errores obvios. Pero el harness no impone una verificación de ejecución exhaustiva, así que el agent se salta ejecutarlo realmente o solo ejecuta pruebas parciales. Ejecuta pruebas unitarias pero se salta las de integración; ejecuta pruebas pero no verifica la cobertura. En última instancia, "el código parece bien" se toma como evidencia de que "la funcionalidad está completa". Y el examen se entrega.Se pierde información en cada paso. Desde las especificaciones de la tarea hasta la implementación del código y el comportamiento en tiempo de ejecución, cada transformación puede introducir sesgos, y cada verificación omitida exacerba la asimetría de información.@@ -111,7 +115,9 @@ Las señales efectivas en tiempo de ejecución incluyen:- ¿Las escrituras en base de datos, operaciones de archivos y otros efectos secundarios fueron correctos?- ¿Se limpiaron los recursos temporales?-## Caso del mundo real+## Ejemplo didáctico++> Ejemplo didáctico: el escenario y sus cifras son supuestos para explicar el mecanismo, no mediciones de un experimento publicado.**Tarea**: Implementar la funcionalidad de restablecimiento de contraseña de usuario. Involucra operaciones de base de datos, envío de correo electrónico y modificaciones de endpoints de API.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.mdindex 32bdc83..74d4a18 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@@ -5,6 +5,8 @@# Lección 10. Solo las pruebas end-to-end son verificación real+> Guía de ingeniería: los umbrales son valores didácticos ajustables, no límites demostrados. Los tokens dependen del tokenizador y del contenido, no solo de las líneas.+Le pides al agent que añada una funcionalidad de exportación de archivos a una aplicación Electron. Escribe el componente del proceso de render, el preload script y la lógica de la capa de servicio. Las pruebas unitarias de cada componente pasan perfectamente. El agent dice: "Ya está." Cuando realmente haces clic en el botón de exportación—el formato de la ruta del archivo es incorrecto, la barra de progreso no se actualiza, y exportar archivos grandes causa una fuga de memoria. Cinco defectos en los límites de componentes, y las pruebas unitarias no detectaron ni uno solo.Es como un ensayo de coro—cada parte vocal suena perfecta cuando se canta individualmente, pero cuando cantan juntos, las sopranos van medio tiempo más rápido que los bajos, y el acompañamiento está un semitono desfasado de la melodía principal. Cada parte es "correcta" por sí sola, pero el conjunto está desafinado.@@ -116,7 +118,9 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.reaCada vez que se encuentre un nuevo tipo de error del agent durante una revisión de código, conviértelo en una verificación automatizada. Un mes después, tu harness será significativamente más fuerte que al inicio del mes. Es como las notas de ensayo de un coro—registrar los problemas encontrados en cada ensayo para poder verificarlos antes del siguiente. Con el tiempo, los errores comunes disminuyen, y la música se vuelve más armoniosa.-## Caso del mundo real+## Ejemplo didáctico++> Ejemplo didáctico: el escenario y sus cifras son supuestos para explicar el mecanismo, no mediciones de un experimento publicado.**Tarea**: Implementar una funcionalidad de exportación de archivos en una aplicación Electron. Involucra la UI del proceso de render, el proxy del sistema de archivos del preload script y la transformación de datos de la capa de servicio.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.mdindex 09160e2..06508a3 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@@ -32,7 +32,9 @@ flowchart LRVerdict --> Generator```-## Por qué ocurre+## Ejemplo didáctico++> Ejemplo didáctico: el escenario y sus cifras son supuestos para explicar el mecanismo, no mediciones de un experimento publicado.### El coste real de no tener observabilidad@@ -44,7 +46,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.+Registra progreso y verificación en archivos versionados para que la siguiente sesión inspeccione el estado. La fuente explica el mecanismo sin cuantificar el ahorro de arranque. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)### Un escenario realista con Claude Code@@ -116,7 +118,9 @@ Convierte "¿está bien o no?" en puntuación cuantificable:Crea una traza para cada sesión de harness, un span para cada tarea y sub-spans para cada paso de verificación. Usa atributos estándar para anotar información clave. Así, los datos de observabilidad se integran con herramientas como Jaeger o Zipkin.-## Caso real+## Ejemplo didáctico++> Ejemplo didáctico: el escenario y sus cifras son supuestos para explicar el mecanismo, no mediciones de un experimento publicado.Un harness con workflow planner-generator-evaluator ejecuta "añadir soporte de dark mode":@@ -136,7 +140,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.**+- Registra progreso y verificación en archivos versionados para que la siguiente sesión inspeccione el estado. La fuente explica el mecanismo sin cuantificar el ahorro de arranque.## Lecturas adicionalesdiff --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.mdindex c9bf3cf..4e78870 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@@ -5,6 +5,8 @@# Lección 12. Deja un handoff limpio al final de cada sesión+> Guía de ingeniería: los umbrales son valores didácticos ajustables, no límites demostrados. Los tokens dependen del tokenizador y del contenido, no solo de las líneas.+Tu agent ejecuta toda la tarde, modifica 20 archivos, hace commit del código, la sesión termina. La siguiente sesión del agent comienza y descubre inmediatamente: el build está roto, las pruebas están en rojo, los archivos temporales de debug están por todas partes, la feature list no se actualizó, y el progreso es completamente incierto. La nueva sesión dedica sus primeros 30 minutos solo a averiguar "qué hizo realmente la última sesión."Tanto OpenAI como Anthropic afirman claramente: **la confiabilidad a largo plazo depende de la disciplina operacional, no solo del éxito en una única ejecución.** La calidad del estado al final de la sesión determina directamente la eficiencia de la siguiente sesión. Piensa en ello como las buenas prácticas de Git—cada commit debería ser un cambio atómico y compilable, no un montón de código a medio terminar.@@ -52,6 +54,8 @@ flowchart LRLas 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.+> Ejemplo didáctico: el escenario y sus cifras son supuestos para explicar el mecanismo, no mediciones de un experimento publicado.+Los datos reales son reveladores. Un proyecto desarrollado con agentes durante 12 semanas, sin estrategia de limpieza:- Semana 1: Tasa de build exitoso 100%, tasa de pruebas exitosas 100%, inicio de nueva sesión 5 min@@ -64,8 +68,6 @@ 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.-### Cinco dimensiones del clean stateEl clean state no es solo "el código compila." Son cinco dimensiones evaluadas juntas:@@ -74,7 +76,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.+Registra progreso y verificación en archivos versionados para que la siguiente sesión inspeccione el estado. La fuente explica el mecanismo sin cuantificar el ahorro de arranque. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)**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.@@ -150,7 +152,9 @@ git checkout -- .env.local # Restore to known statenpm run test # Verify cleanup didn't break anything```-## Caso del mundo real+## Ejemplo didáctico++> Ejemplo didáctico: el escenario y sus cifras son supuestos para explicar el mecanismo, no mediciones de un experimento publicado.Una aplicación Electron desarrollada con agentes durante 12 semanas, comparando dos enfoques:@@ -158,8 +162,6 @@ 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.-## Ideas clave- **El clean state es una condición necesaria para la finalización de la sesión**—no es limpieza opcional, sino parte de la "definición de terminado."diff --git a/docs/es/lectures/lecture-13-loop-engineering/index.md b/docs/es/lectures/lecture-13-loop-engineering/index.mdindex dbe12f7..26fb54a 100644--- a/docs/es/lectures/lecture-13-loop-engineering/index.md+++ b/docs/es/lectures/lecture-13-loop-engineering/index.md@@ -5,6 +5,8 @@# Lección 13. Del Prompting Manual a los Loops Autónomos+> Guía de ingeniería: los umbrales son valores didácticos ajustables, no límites demostrados. Los tokens dependen del tokenizador y del contenido, no solo de las líneas.+Todo lo que aprendiste en las primeras doce lecciones se basa en un supuesto: **estás sentado frente al teclado, escribiendo instrucciones una a una.**Escribiste `AGENTS.md` (Lecciones 1–4), construiste gestión del estado (Lecciones 5–6), limitaste el alcance con listas de características (Lecciones 7–8), dejaste handoffs limpios al final de la sesión (Lecciones 9, 12), e hiciste el runtime observable (Lecciones 10–11). Pero el disparador de todo siempre eras tú. El agente nunca decidía por sí mismo cuándo empezar a trabajar — porque nadie presionaba "inicio".@@ -86,6 +88,8 @@ No tienes que escribir `/goal` cada vez. Pero entender de dónde vino y por qué## Junio 2026: Tres Personas Encendieron la Mecha en Una Semana+> Ejemplo didáctico: el escenario y sus cifras son supuestos para explicar el mecanismo, no mediciones de un experimento publicado.+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.**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."@@ -96,7 +100,13 @@ 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.+Boris Cherny · 2025-12-27++| PR | Git commits | + LoC | − LoC | Model |+| --- | --- | --- | --- | --- |+| 259 / 30 days | 497 | 40,000 | 38,000 | Claude Code + Opus 4.5 |++Actividad personal declarada por el autor, no tasa de éxito de un benchmark ni prueba de ausencia de supervisión humana. [Boris Cherny](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)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.@@ -267,7 +277,7 @@ flowchart TDEsto 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.+Actividad personal declarada por el autor, no tasa de éxito de un benchmark ni prueba de ausencia de supervisión humana.## Separación Generador/Evaluador: Por Qué No Puedes Dejar que el Modelo Califique Su Propio Trabajo@@ -293,7 +303,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.+[Karpathy: autoresearch](https://github.com/karpathy/autoresearch) · [announcement](https://x.com/karpathy/status/2030371219518931079)### Tres Archivos, Tres Roles@@ -343,8 +353,6 @@ flowchart TD8b --> 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 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".### Salida: Lo Que Ves Cuando Te Despiertas@@ -359,6 +367,8 @@ Solo los commits que realmente mejoraron se quedan en la rama principal. Todo loCada solo experimento — éxito o fracaso — está registrado:+> Ejemplo didáctico: el escenario y sus cifras son supuestos para explicar el mecanismo, no mediciones de un experimento publicado.+```timestamp commit_hash val_bpb vram_mb description--------- ------------- ---------- ---------- ----------------------------@@ -375,11 +385,10 @@ 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:+- Redujo el tiempo de entrenamiento a nivel GPT-2 de nanochat en 8×H100 de **2.02 horas → 1.80 horas**, aproximadamente **10.89% 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. [Karpathy: leaderboard commit](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b) · [tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)-- 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.+> Ejemplo didáctico: el escenario y sus cifras son supuestos para explicar el mecanismo, no mediciones de un experimento publicado.¿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.@@ -399,7 +408,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.**+Los resultados de producción no aíslan una causa. Las puntuaciones corresponden al modelo, scaffold, conjunto de datos y evaluación indicados, no a toda tarea real.### 3. Rendición Cognitivadiff --git a/docs/es/lectures/lecture-14-graph-engineering/index.md b/docs/es/lectures/lecture-14-graph-engineering/index.mdindex 7d4c0cc..46d7d64 100644--- a/docs/es/lectures/lecture-14-graph-engineering/index.md+++ b/docs/es/lectures/lecture-14-graph-engineering/index.md@@ -261,7 +261,7 @@ Primero, delimitemos: **Graph Engineering es un nombre que solo existe después**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)**Existían antes de la publicación del concepto (no se llaman Graph Engineering, pero son justo los que usarás para construir)**diff --git a/docs/es/resources/reference/index.md b/docs/es/resources/reference/index.mdindex f1a98a3..103d0fa 100644--- a/docs/es/resources/reference/index.md+++ b/docs/es/resources/reference/index.md@@ -73,6 +73,11 @@ fundacional del curso.- [On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents](https://arxiv.org/html/2601.20404v2): gpt-5.2-codex; 10 repos / 124 PR tasks; Table 1.+- [Anthropic: Sonnet 4.5 — SWE-bench Verified methodology (2025-09-29)](https://www.anthropic.com/news/claude-sonnet-4-5)+- [Boris Cherny: personal 30-day production report (2025-12-27)](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)+- [Karpathy: measured autoresearch leaderboard improvement](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b)+- [Karpathy: two-day autonomous tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)+## Orden de Lectura Sugerido1. `method-map.md`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.mdindex b9f865c..990c2ff 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,26 @@ Vous pensez connaître le monde de l'IA : abonnement Claude Pro, clé API GPT-4oVotre 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.+Claude Sonnet 4.5 · 2025-09-29 · SWE-bench Verified++| Score | Tasks | Trials | Scaffold |+| --- | --- | --- | --- |+| 77.2% | 500 | 10 | bash + string replacement |++Les résultats de production n’isolent pas une cause. Les scores s’appliquent au modèle, scaffold, jeu de données et protocole indiqués, pas à toutes les tâches réelles. [Anthropic: methodology](https://www.anthropic.com/news/claude-sonnet-4-5)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.+> Même modèle et même prompt, mais budgets de temps et de coût différents. Ce n’est pas une expérience à budget égal isolant un composant. Le jeu fonctionnait au niveau essentiel, avec des défauts persistants. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++Même modèle et même prompt, mais budgets de temps et de coût différents. Ce n’est pas une expérience à budget égal isolant un composant. Le jeu fonctionnait au niveau essentiel, avec des défauts persistants. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++| Opus 4.5 | Duration | USD |+| --- | --- | --- |+| Solo | 20 min | 9 |+| Full harness | 6 h | 200 |Ils n'ont pas changé de modèle. Opus 4.5 restait Opus 4.5. Ce qui a changé, c'est le harnachement.@@ -37,7 +50,7 @@ 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.+- Les résultats de production n’isolent pas une cause. Les scores s’appliquent au modèle, scaffold, jeu de données et protocole indiqués, pas à toutes les tâches réelles.- **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.- **É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é.@@ -68,17 +81,19 @@ 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.+Les résultats de production n’isolent pas une cause. Les scores s’appliquent au modèle, scaffold, jeu de données et protocole indiqués, pas à toutes les tâches réelles. [OpenAI: 2026-02-11](https://openai.com/index/harness-engineering/)-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.+Les résultats de production n’isolent pas une cause. Les scores s’appliquent au modèle, scaffold, jeu de données et protocole indiqués, pas à toutes les tâches réelles.Au début, la progression était plus lente que prévu. Non pas parce que Codex était incapable, mais parce que l'environnement était incomplet : il manquait outils, abstractions et structures internes. Le travail des ingénieurs est devenu : découper de grands objectifs en petits blocs (design, code, review, test), laisser l'agent les assembler, puis utiliser ces blocs pour débloquer des tâches plus complexes. Quand quelque chose échouait, la correction était rarement « essaie plus fort », mais plutôt « quelle capacité manque à l'agent, et comment la rendre compréhensible et exécutable ? ».-Cette expérience prouve directement la thèse de cette leçon : **le même modèle produit des résultats radicalement différents dans un environnement nu et dans un environnement avec harness complet.** Le modèle n'a pas changé. L'environnement, oui.+Les résultats de production n’isolent pas une cause. Les scores s’appliquent au modèle, scaffold, jeu de données et protocole indiqués, pas à toutes les tâches réelles.> Source : [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)-## Un exemple plus terre à terre+## Exemple pédagogique++> Illustration pédagogique : le scénario et ses chiffres sont des hypothèses explicatives, pas des mesures d’une expérience publiée.Une équipe a utilisé Claude Sonnet pour ajouter un endpoint API à une application Python moyenne (FastAPI + PostgreSQL + Redis, environ 15 000 lignes).@@ -104,6 +119,8 @@ Ils n'ont pas changé le modèle. Ils ont changé le harness.- [SWE-bench Leaderboard](https://www.swebench.com/)- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)+- [Anthropic: Sonnet 4.5 SWE-bench methodology, 2025-09-29](https://www.anthropic.com/news/claude-sonnet-4-5)+## Exercices1. **Expérience comparative** : choisissez un codebase connu et une tâche non triviale. Exécutez d'abord sans harness, puis avec `AGENTS.md` et commandes de vérification explicites. Comparez les échecs par couche.diff --git a/docs/fr/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/fr/lectures/lecture-02-what-a-harness-actually-is/index.mdindex f91c2b3..2a03896 100644--- a/docs/fr/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/fr/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -70,7 +70,9 @@ L'absence d'un sous-système est comme l'absence d'une zone fonctionnelle dans l**Quantifier la valeur des composants du harness** : Utilisez une ablation à modèle fixe. Gardez le modèle fixe, retirez les sous-systèmes un par un et mesurez quel retrait provoque la plus forte baisse de performance. La plus forte baisse indique le composant à plus forte contribution marginale dans cette tâche ; elle n’identifie pas automatiquement le goulot d’étranglement. Une baisse quasi nulle doit aussi être interprétée : le composant peut être redondant, mal conçu ou simplement non sollicité par cette tâche. Pour diagnostiquer les goulots, utilisez d’abord les journaux d’échec et l’attribution, puis l’ablation comme preuve d’appui : l’échec vient-il d’une intention floue, d’un contexte insuffisant, d’un environnement non reproductible, d’un feedback de vérification manquant ou d’une gestion d’état rompue ?-## L'histoire vraie d'une équipe+## Exemple pédagogique++> Illustration pédagogique : le scénario et ses chiffres sont des hypothèses explicatives, pas des mesures d’une expérience publiée.Une équipe a utilisé GPT-4o sur une application frontend TypeScript + React (~20 000 lignes de code). Ils ont traversé quatre étapes — essentiellement ajouter des équipements de cuisine un par un :diff --git a/docs/fr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/fr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdindex 3263c3c..b483c4d 100644--- a/docs/fr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md+++ b/docs/fr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -5,6 +5,8 @@# Leçon 03. Faire du dépôt la source unique de vérité+> Conseil d’ingénierie : ces seuils sont des valeurs pédagogiques ajustables, pas des limites démontrées. Les tokens dépendent du tokenizer et du contenu, pas seulement des lignes.+Les décisions d'architecture de votre équipe sont dispersées entre Confluence, Slack, Jira et la tête de quelques ingénieurs seniors. Pour les humains, cela fonctionne tout juste : vous pouvez demander à un collègue, chercher dans l'historique du chat, fouiller la documentation. En dernier recours, vous pouvez coincer quelqu'un en salle de pause. Mais pour un agent IA, l'information qui n'est pas dans le dépôt n'existe tout simplement pas.Ce n'est pas une exagération. Pensez à ce que sont réellement les entrées d'un agent : prompts système et descriptions de tâche, contenu des fichiers du dépôt, sorties d'outils. C'est tout. Votre historique Slack, vos tickets Jira, vos pages Confluence, et cette décision d'architecture discutée autour d'un café un vendredi après-midi : l'agent ne voit rien de tout cela. Il ne peut pas "aller demander à quelqu'un" ni "chercher dans l'historique du chat". C'est un ingénieur enfermé dans le dépôt ; de tout ce qui est dehors, il ne sait rien.diff --git a/docs/fr/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/fr/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdindex d24d904..5d22e35 100644--- a/docs/fr/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md+++ b/docs/fr/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -5,6 +5,8 @@# Leçon 04. Répartir les instructions entre fichiers+> Conseil d’ingénierie : ces seuils sont des valeurs pédagogiques ajustables, pas des limites démontrées. Les tokens dépendent du tokenizer et du contenu, pas seulement des lignes.+Vous avez pris le harness engineering au sérieux. Vous avez créé un `AGENTS.md` et vous y avez mis toutes les règles, contraintes et leçons apprises auxquelles vous pouviez penser. Un mois plus tard, le fichier faisait 300 lignes ; deux mois plus tard, 450 ; trois mois plus tard, 600. Puis vous remarquez que les performances de l'agent se dégradent : sur une simple correction de bug, il consomme beaucoup de contexte à traiter des instructions de déploiement sans rapport ; une contrainte de sécurité critique enfouie à la ligne 300 est ignorée ; trois règles de style contradictoires font que l'agent en choisit une au hasard à chaque fois.C'est le piège du "fichier d'instructions géant". C'est comme une valise trop remplie : tout semble utile, donc on tasse jusqu'à ce que la fermeture menace de céder. Pour trouver un sous-vêtement de rechange, il faut vider tout le sac. Vous transportez une valise pleine, mais vous n'utilisez peut-être qu'un tiers de ce qu'elle contient.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.mdindex 03f6ee3..400a068 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@@ -5,6 +5,8 @@# Leçon 05. Garder le contexte vivant entre les sessions+> Conseil d’ingénierie : ces seuils sont des valeurs pédagogiques ajustables, pas des limites démontrées. Les tokens dépendent du tokenizer et du contenu, pas seulement des lignes.+Vous demandez à Claude Code d'implémenter une fonctionnalité complète. Il tourne pendant 30 minutes, fait la majeure partie du travail, mais le contexte commence à manquer. Vous lancez une nouvelle session pour continuer — et découvrez qu'il ne se souvient pas des décisions prises la dernière fois, pourquoi l'option A a été choisie plutôt que l'option B, quels fichiers ont déjà été modifiés, ou dans quel état se trouvent les tests. Il passe 15 minutes à réexplorer le projet, et risque d'être en contradiction avec l'approche précédente.Imaginez que vous êtes un artisan qui oublie tout chaque matin en vous réveillant. Vous devriez vous refamiliariser avec l'ensemble du chantier — quel mur est à moitié construit, pourquoi des briques rouges ont été choisies plutôt que des bleues, où en sont les passages de plomberie. Pire, vous pourriez arracher une fenêtre qui a déjà été installée hier, simplement parce que vous ne vous souveniez pas que c'était fait.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.mdindex 224ee59..c313097 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@@ -5,6 +5,8 @@# Leçon 06. Initialiser avant chaque session d'agent+> Conseil d’ingénierie : ces seuils sont des valeurs pédagogiques ajustables, pas des limites démontrées. Les tokens dépendent du tokenizer et du contenu, pas seulement des lignes.+Vous démarrez une nouvelle session d'agent et dites « ajoute une fonctionnalité de recherche ». Il se lance directement dans le code — un bel enthousiasme. Après 20 minutes, il découvre que le framework de test n'est pas correctement configuré, passe encore 10 minutes à le corriger, puis le format du script de migration de base de données est incorrect, encore des ajustements. La fonctionnalité de recherche finit par être ajoutée, mais toute la session a été inefficace — la majeure partie du temps a été consacrée à « comprendre comment fonctionne ce projet » plutôt qu'à écrire la fonctionnalité de recherche.La meilleure approche : avant de laisser l'agent commencer à travailler, utiliser une phase séparée pour préparer l'environnement de base, faire passer les commandes de vérification, et faire comprendre la structure du projet. C'est comme construire une maison — vous ne coulez pas les fondations et n'érigez pas les murs simultanément. Si vous le faites, les murs montent avant que les fondations n'aient séché, et tout le bâtiment doit être démoli et recommencé. Coulez d'abord les fondations, laissez-les sécher, puis construisez les murs — propre et efficace.@@ -37,6 +39,8 @@ flowchart TB## Ce qui se passe quand on les mélange+> Illustration pédagogique : le scénario et ses chiffres sont des hypothèses explicatives, pas des mesures d’une expérience publiée.+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.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 +49,7 @@ Le budget de session est également gaspillé. Le travail d'initialisation (confLe 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.+[Anthropic: initializer / coding agent](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)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.@@ -122,7 +126,9 @@ Le guide de harness engineering d'OpenAI Codex souligne également le principe d- [ ] Everything committed to git```-## Exemple concret+## Exemple pédagogique++> Illustration pédagogique : le scénario et ses chiffres sont des hypothèses explicatives, pas des mesures d’une expérience publiée.Deux approches d'initialisation pour un projet frontend React :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.mdindex 3653893..f4a8d65 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@@ -5,6 +5,8 @@# Leçon 07. Définir des limites de tâche claires+> Conseil d’ingénierie : ces seuils sont des valeurs pédagogiques ajustables, pas des limites démontrées. Les tokens dépendent du tokenizer et du contenu, pas seulement des lignes.+Vous demandez à Claude Code d'« ajouter l'authentification utilisateur à ce projet », et il commence à modifier le schéma de base de données, à écrire des routes, à changer des composants frontend, et — tant qu'à faire — à refactorer le middleware de gestion d'erreurs. Deux heures plus tard, vous vérifiez : 12 fichiers modifiés, 800 lignes de nouveau code, et pas une seule fonctionnalité qui fonctionne de bout en bout.Mordre plus qu'on ne peut mâcher — ce dicton s'applique particulièrement bien aux agents IA. Les agents ont un instinct inné pour « faire un peu plus » — ils voient des choses liées et les traitent au passage, comme quelqu'un qui va au supermarché pour une bouteille de sauce soja et ressort en poussant un caddy plein. Le problème, c'est que les humains qui achètent trop gaspillent juste de l'argent ; les agents qui font trop de choses simultanément n'en terminent aucune correctement.@@ -26,7 +28,7 @@ Le comportement réel de Claude Code est révélateur. Demandez-lui d'« ajouterSix é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.+[Anthropic: incremental feature work](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## Flux de travail WIP=1@@ -100,7 +102,9 @@ Utilisez un fichier lisible par machine (JSON ou Markdown) pour enregistrer tousLe harness devrait suivre en continu le VCR (Verified Completion Rate) = tâches vérifiées / tâches activées. Bloquer les activations de nouvelles tâches quand VCR < 1.0.-## Cas concret+## Exemple pédagogique++> Illustration pédagogique : le scénario et ses chiffres sont des hypothèses explicatives, pas des mesures d’une expérience publiée.Un projet d'API REST avec 8 fonctionnalités, deux stratégies comparées :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.mdindex b1e2975..5f11f85 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@@ -5,6 +5,8 @@# Leçon 08. Utiliser les listes de fonctionnalités pour contraindre l'agent+> Conseil d’ingénierie : ces seuils sont des valeurs pédagogiques ajustables, pas des limites démontrées. Les tokens dépendent du tokenizer et du contenu, pas seulement des lignes.+Vous demandez à un agent de construire un site e-commerce. Une fois terminé, il vous dit "done". Vous regardez le code : l'authentification utilisateur fonctionne, mais le bouton de checkout du panier ne fait rien, et le flux de paiement n'est pas connecté. Le problème : vous ne lui avez jamais dit ce que "done" signifie, donc il a utilisé son propre standard : "j'ai écrit beaucoup de code et ça a l'air assez complet".Aux yeux de beaucoup de gens, les listes de fonctionnalités ne sont qu'un mémo : on note les choses pour ne pas oublier, puis on les met de côté. Mais dans le monde du harness, une liste de fonctionnalités n'est pas un mémo pour humains : c'est la colonne vertébrale de tout le harness. Le scheduler s'en sert pour choisir les tâches, le verifier pour juger l'achèvement, le handoff reporter pour générer les résumés. Si la colonne vertébrale casse, tout le corps est paralysé.@@ -23,7 +25,7 @@ Did user auth, shopping cart mostly done, still need paymentsUne 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%.+Conserver l’avancement et les vérifications dans des fichiers versionnés permet à la session suivante d’inspecter l’état. La source décrit le mécanisme sans chiffrer le gain de démarrage. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## Machine d'état des fonctionnalités@@ -104,7 +106,9 @@ L'agent ne peut pas modifier directement l'état d'une fonctionnalité en `passiChaque item de fonctionnalité doit être dimensionné pour être "terminable en une session". Trop large, il ne se terminera pas ; trop étroit, le coût de gestion augmente. "L'utilisateur peut ajouter des articles au panier" est une bonne granularité. "Implémenter le panier" est trop large. "Créer le champ name sur le modèle Cart" est trop étroit. Comme découper un steak : ni la pièce entière, ni de la viande hachée.-## Cas réel+## Exemple pédagogique++> Illustration pédagogique : le scénario et ses chiffres sont des hypothèses explicatives, pas des mesures d’une expérience publiée.Une plateforme e-commerce avec 10 fonctionnalités. Deux approches de suivi ont été comparées :@@ -112,8 +116,6 @@ 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.-## Points clés- **Les listes de fonctionnalités sont la colonne vertébrale du harness**, pas des mémos pour humains. Scheduler, verifier et handoff reporter en dépendent tous.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.mdindex ba9e7e3..c5418c8 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@@ -5,6 +5,8 @@# Leçon 09. Empêcher les agents de déclarer victoire trop tôt+> Conseil d’ingénierie : ces seuils sont des valeurs pédagogiques ajustables, pas des limites démontrées. Les tokens dépendent du tokenizer et du contenu, pas seulement des lignes.+Vous demandez à un agent d'implémenter une fonctionnalité de « réinitialisation de mot de passe ». Il modifie le schéma de la base de données, écrit l'endpoint API, ajoute le template d'email, lance les tests unitaires (tous réussis), puis vous annonce avec assurance « c'est fait ». Quand vous essayez réellement de l'exécuter — le lien de réinitialisation ne peut pas être envoyé (configuration du service email manquante), la migration de la base de données échoue à mi-chemin (incohérence du schéma), et le flux de bout en bout n'a jamais été exécuté une seule fois.Ce sentiment ne devrait pas vous être étranger — c'est comme remplir entièrement sa copie d'examen, être le premier à la remettre en toute confiance, pour finalement échouer quand les notes arrivent. Ce n'est pas parce que la copie est pleine que les réponses sont justes.@@ -13,6 +15,8 @@ Ce n'est pas un incident isolé. L'article classique de 2017 à l'ICML de Guo et## La pente glissante+> Même modèle et même prompt, mais budgets de temps et de coût différents. Ce n’est pas une expérience à budget égal isolant un composant. Le jeu fonctionnait au niveau essentiel, avec des défauts persistants. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)+Les déclarations prématurées de complétion suivent presque toujours le même schéma : le code semble correct — la syntaxe est bonne, la logique paraît raisonnable, et l'analyse statique ne montre aucune erreur évidente. Mais le harness n'impose pas de vérification d'exécution complète, donc l'agent skip l'exécution réelle ou ne lance que des tests partiels. Il exécute les tests unitaires mais ignore les tests d'intégration ; il lance les tests mais ne vérifie pas la couverture. Finalement, « le code semble bon » est pris comme preuve que « la fonctionnalité est complète ». Et la copie d'examen est remise.De l'information est perdue à chaque étape. Des spécifications de la tâche à l'implémentation du code jusqu'au comportement à l'exécution, chaque transformation peut introduire un biais, et chaque vérification ignorée aggrave l'asymétrie d'information.@@ -111,7 +115,9 @@ Les signaux à l'exécution efficaces incluent :- Les écritures en base de données, opérations sur fichiers et autres effets de bord étaient-ils corrects ?- Les ressources temporaires ont-elles été nettoyées ?-## Cas concret+## Exemple pédagogique++> Illustration pédagogique : le scénario et ses chiffres sont des hypothèses explicatives, pas des mesures d’une expérience publiée.**Tâche** : Implémenter une fonctionnalité de réinitialisation de mot de passe utilisateur. Implique des opérations en base de données, l'envoi d'emails et des modifications d'endpoints API.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.mdindex 58a537e..1ffc923 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@@ -5,6 +5,8 @@# Leçon 10. Seul le test end-to-end est une vraie vérification+> Conseil d’ingénierie : ces seuils sont des valeurs pédagogiques ajustables, pas des limites démontrées. Les tokens dépendent du tokenizer et du contenu, pas seulement des lignes.+Vous demandez à l'agent d'ajouter une fonctionnalité d'export de fichier à une application Electron. Il écrit le composant du processus de rendu, le script preload et la logique de la couche service. Les tests unitaires de chaque composant passent parfaitement. L'agent dit : « C'est fait. » Quand vous cliquez réellement sur le bouton d'export — le format du chemin de fichier est incorrect, la barre de progression ne se met pas à jour, et l'export de gros fichiers provoque une fuite de mémoire. Cinq défauts aux frontières des composants, et les tests unitaires n'en ont attrapé aucun.C'est comme une répétition de chœur — chaque pupitre sonne parfaitement chanté individuellement, mais quand ils chantent ensemble, les sopranes sont un demi-temps plus rapides que les basses, et l'accompagnement est un demi-ton décalé par rapport à la mélodie principale. Chaque partie est « correcte » individuellement, mais l'ensemble est faux.@@ -116,7 +118,9 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.reaChaque fois qu'un nouveau type d'erreur d'agent est découvert lors d'une revue de code, transformez-le en vérification automatisée. Un mois plus tard, votre harness sera significativement plus fort qu'au début du mois. C'est comme les notes de répétition d'un chœur — enregistrer les problèmes trouvés à chaque répétition pour pouvoir les vérifier avant la suivante. Avec le temps, les erreurs courantes diminuent, et la musique devient plus harmonieuse.-## Cas concret+## Exemple pédagogique++> Illustration pédagogique : le scénario et ses chiffres sont des hypothèses explicatives, pas des mesures d’une expérience publiée.**Tâche** : Implémenter une fonctionnalité d'export de fichier dans une application Electron. Implique l'UI du processus de rendu, le proxy de système de fichiers du script preload et la transformation de données de la couche service.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.mdindex 9d2ddaa..c2e9a7e 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@@ -32,7 +32,9 @@ flowchart LRVerdict --> Generator```-## Pourquoi cela arrive+## Exemple pédagogique++> Illustration pédagogique : le scénario et ses chiffres sont des hypothèses explicatives, pas des mesures d’une expérience publiée.### Le vrai coût du manque d'observabilité@@ -44,7 +46,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.+Conserver l’avancement et les vérifications dans des fichiers versionnés permet à la session suivante d’inspecter l’état. La source décrit le mécanisme sans chiffrer le gain de démarrage. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)### Un scénario réaliste avec Claude Code@@ -116,7 +118,9 @@ Transformez « est-ce bon ou non » en score quantifiable :Créez une trace pour chaque session de harness, un span pour chaque tâche et des sous-spans pour chaque étape de vérification. Utilisez des attributs standards pour annoter les informations clés. Les données d'observabilité peuvent ainsi s'intégrer à des outils comme Jaeger ou Zipkin.-## Cas réel+## Exemple pédagogique++> Illustration pédagogique : le scénario et ses chiffres sont des hypothèses explicatives, pas des mesures d’une expérience publiée.Un harness avec workflow planner-generator-evaluator exécute « ajouter le support dark mode » :@@ -136,7 +140,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.**+- Conserver l’avancement et les vérifications dans des fichiers versionnés permet à la session suivante d’inspecter l’état. La source décrit le mécanisme sans chiffrer le gain de démarrage.## Pour aller plus loindiff --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.mdindex 0106296..add924f 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@@ -5,6 +5,8 @@# Leçon 12. Laisser un handoff propre à la fin de chaque session+> Conseil d’ingénierie : ces seuils sont des valeurs pédagogiques ajustables, pas des limites démontrées. Les tokens dépendent du tokenizer et du contenu, pas seulement des lignes.+## Quel problème cette leçon résout-elle ?Votre agent travaille tout l'après-midi, modifie 20 fichiers, commite le code, la session se termine. La prochaine session d'agent démarre et découvre immédiatement : le build est cassé, les tests sont rouges, des fichiers de debug temporaires sont partout, la feature list n'a pas été mise à jour, et l'avancement est totalement flou. La nouvelle session passe ses 30 premières minutes juste à comprendre « ce que la session précédente a réellement fait. »@@ -54,6 +56,8 @@ flowchart LRLes 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.+> Illustration pédagogique : le scénario et ses chiffres sont des hypothèses explicatives, pas des mesures d’une expérience publiée.+Les données réelles sont éloquentes. Un projet développé avec des agents pendant 12 semaines, sans stratégie de nettoyage :- Semaine 1 : Taux de réussite du build 100 %, taux de réussite des tests 100 %, démarrage de nouvelle session 5 min@@ -66,8 +70,6 @@ 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.-### Les cinq dimensions de l'état propreL'état propre, ce n'est pas juste « le code compile ». C'est cinq dimensions évaluées ensemble :@@ -76,7 +78,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.+Conserver l’avancement et les vérifications dans des fichiers versionnés permet à la session suivante d’inspecter l’état. La source décrit le mécanisme sans chiffrer le gain de démarrage. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)**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.@@ -152,7 +154,9 @@ git checkout -- .env.local # Restore to known statenpm run test # Verify cleanup didn't break anything```-## Cas concret+## Exemple pédagogique++> Illustration pédagogique : le scénario et ses chiffres sont des hypothèses explicatives, pas des mesures d’une expérience publiée.Une application Electron développée avec des agents sur 12 semaines, comparant deux approches :@@ -160,8 +164,6 @@ 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 %.-## Points clés- **L'état propre est une condition nécessaire à l'achèvement de la session** — pas du ménage optionnel, mais partie intégrante de la « définition du fini ».diff --git a/docs/fr/lectures/lecture-13-loop-engineering/index.md b/docs/fr/lectures/lecture-13-loop-engineering/index.mdindex 5ca1683..5db7086 100644--- a/docs/fr/lectures/lecture-13-loop-engineering/index.md+++ b/docs/fr/lectures/lecture-13-loop-engineering/index.md@@ -5,6 +5,8 @@# Cours 13. Du prompting manuel aux boucles autonomes+> Conseil d’ingénierie : ces seuils sont des valeurs pédagogiques ajustables, pas des limites démontrées. Les tokens dépendent du tokenizer et du contenu, pas seulement des lignes.+Tout ce que vous avez appris dans les douze premiers cours repose sur une hypothèse : **vous êtes assis devant le clavier, en tapant des instructions une par une.**Vous avez écrit `AGENTS.md` (Cours 1–4), construit la gestion d'état (Cours 5–6), contraint le périmètre avec des listes de fonctionnalités (Cours 7–8), laissé des transferts propres à la fin de chaque session (Cours 9, 12), et rendu l'exécution observable (Cours 10–11). Mais le déclencheur de tout cela, c'était toujours vous. L'agent ne décidait jamais seul de commencer à travailler — car personne n'avait appuyé sur « démarrer ».@@ -96,7 +98,13 @@ 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.+Boris Cherny · 2025-12-27++| PR | Git commits | + LoC | − LoC | Model |+| --- | --- | --- | --- | --- |+| 259 / 30 days | 497 | 40,000 | 38,000 | Claude Code + Opus 4.5 |++Activité personnelle déclarée par l’auteur, pas un taux de réussite de benchmark ni une preuve d’absence de supervision humaine. [Boris Cherny](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)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.@@ -267,7 +275,7 @@ flowchart TDCe 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.+Activité personnelle déclarée par l’auteur, pas un taux de réussite de benchmark ni une preuve d’absence de supervision humaine.## Séparation générateur/évaluateur : Pourquoi vous ne pouvez pas laisser le modèle noter son propre travail@@ -293,7 +301,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.+[Karpathy: autoresearch](https://github.com/karpathy/autoresearch) · [announcement](https://x.com/karpathy/status/2030371219518931079)### Trois fichiers, trois rôles@@ -343,8 +351,6 @@ flowchart TD8b --> 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 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 ».### Sortie : Ce que vous voyez quand vous vous réveillez@@ -359,6 +365,8 @@ Seuls les commits qui se sont réellement améliorés restent sur la branche priChaque expérience — succès ou échec — est journalisée :+> Illustration pédagogique : le scénario et ses chiffres sont des hypothèses explicatives, pas des mesures d’une expérience publiée.+```timestamp commit_hash val_bpb vram_mb description--------- ------------- ---------- ---------- ----------------------------@@ -375,11 +383,8 @@ 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 :--- 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.+- Réduit le temps d'entraînement de niveau GPT-2 de nanochat sur 8×H100 de **2,02 heures → 1,80 heure**, environ **10.89% 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. [Karpathy: leaderboard commit](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b) · [tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)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.@@ -399,7 +404,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.**+Les résultats de production n’isolent pas une cause. Les scores s’appliquent au modèle, scaffold, jeu de données et protocole indiqués, pas à toutes les tâches réelles.### 3. Abandon cognitifdiff --git a/docs/fr/lectures/lecture-14-graph-engineering/index.md b/docs/fr/lectures/lecture-14-graph-engineering/index.mdindex ef41498..8a385ca 100644--- a/docs/fr/lectures/lecture-14-graph-engineering/index.md+++ b/docs/fr/lectures/lecture-14-graph-engineering/index.md@@ -261,7 +261,7 @@ D'abord, clarifions les limites : **le Graph Engineering est un nom qui n'existe**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)**Ce qui existait avant la publication du concept (ils ne s'appellent pas Graph Engineering, mais ce sont eux que vous utiliserez pour construire)**@@ -346,4 +346,4 @@ Toutes les tâches ne méritent pas d'être dessinées en graphe. Cinq critères4. **Évaluez avec les cinq critères :** choisissez une tâche dont vous hésitez à « transformer en graphe », et notez-la critère par critère. Il faut au moins trois critères pour que le graphe en vaille la peine. S'il y en a moins de trois, ce dont elle a besoin, c'est en fait d'un meilleur script de workflow — ne dessinez pas un graphe pour utiliser un graphe.-5. **Transformez graph.md en programme exécutable :** en suivant les six étapes de « Construire votre premier graphe à partir de zéro », implémentez le graphe maker-checker que vous avez dessiné en un graphe qui tourne (implémentation de référence : `code/maker_checker_graph.py`, écrit avec LangGraph). Ne sautez aucune des six étapes : définir l'état → lister les nœuds → connecter les arêtes → écrire le routage → accrocher les checkpoints → exécuter. Après l'exécution, comparez `graph.md` et le code, trouvez la première divergence, et expliquez pourquoi elle existe — le graphe est-il mal dessiné, ou le code est-il mal écrit ?\ No newline at end of file+5. **Transformez graph.md en programme exécutable :** en suivant les six étapes de « Construire votre premier graphe à partir de zéro », implémentez le graphe maker-checker que vous avez dessiné en un graphe qui tourne (implémentation de référence : `code/maker_checker_graph.py`, écrit avec LangGraph). Ne sautez aucune des six étapes : définir l'état → lister les nœuds → connecter les arêtes → écrire le routage → accrocher les checkpoints → exécuter. Après l'exécution, comparez `graph.md` et le code, trouvez la première divergence, et expliquez pourquoi elle existe — le graphe est-il mal dessiné, ou le code est-il mal écrit ?diff --git a/docs/fr/resources/reference/index.md b/docs/fr/resources/reference/index.mdindex f44902c..4b14fa8 100644--- a/docs/fr/resources/reference/index.md+++ b/docs/fr/resources/reference/index.md@@ -77,6 +77,11 @@ fondamentale du cours.- [On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents](https://arxiv.org/html/2601.20404v2): gpt-5.2-codex; 10 repos / 124 PR tasks; Table 1.+- [Anthropic: Sonnet 4.5 — SWE-bench Verified methodology (2025-09-29)](https://www.anthropic.com/news/claude-sonnet-4-5)+- [Boris Cherny: personal 30-day production report (2025-12-27)](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)+- [Karpathy: measured autoresearch leaderboard improvement](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b)+- [Karpathy: two-day autonomous tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)+## Ordre de lecture suggéré1. `method-map.md`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.mdindex e9a147b..1d19c30 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,26 @@最初の反応は「このモデルはまだ足りない。アップグレードしよう」かもしれません。少し待ってください。財布を開く前に、問題はモデルではない可能性があります。-数字を見てみましょう。2025 年後半時点で、最強クラスの coding agent でも SWE-bench Verified ではおおむね 50-60% 程度です。しかもこれは、明確な issue 説明と既存テストがある、慎重に選ばれたタスクでの数字です。日常の開発環境、つまり曖昧な要求、既存テストなし、暗黙のビジネスルールが散らばった環境に移ると、その数字はさらに下がります。+Claude Sonnet 4.5 · 2025-09-29 · SWE-bench Verified++| Score | Tasks | Trials | Scaffold |+| --- | --- | --- | --- |+| 77.2% | 500 | 10 | bash + string replacement |++実際の開発結果は一つの要因だけの因果効果を示しません。ベンチマーク値は指定されたモデル、scaffold、データ、評価条件に限られます。 [Anthropic: methodology](https://www.anthropic.com/news/claude-sonnet-4-5)しかし、この数字の裏には直感に反する真実があります。## 同じ馬、違う運命-Anthropic は制御実験を行いました。同じプロンプト(「2D レトロゲームメーカーを作る」)、同じモデル(Opus 4.5)。1 回目は bare、支援なし。20 分、9 ドル、ゲームの中核機能はまったく動きませんでした。2 回目は完全な harness(planner + generator + evaluator の 3 エージェント構成)。6 時間、200 ドル、ゲームはプレイ可能でした。+> モデルとプロンプトは同じですが、時間と費用の予算が異なります。同予算で一つの構成要素を分離した実験ではありません。基本的なゲーム操作は動作しましたが、不具合は残りました。 [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++モデルとプロンプトは同じですが、時間と費用の予算が異なります。同予算で一つの構成要素を分離した実験ではありません。基本的なゲーム操作は動作しましたが、不具合は残りました。 [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++| Opus 4.5 | Duration | USD |+| --- | --- | --- |+| Solo | 20 min | 9 |+| Full harness | 6 h | 200 |モデルは変えていません。Opus 4.5 は同じ Opus 4.5 です。変わったのは馬具です。@@ -39,7 +52,7 @@ OpenAI の harness engineering 記事ははっきり言っています。よくこうした状況を踏まえると、次の概念は単なる流行語ではありません。-- **能力ギャップ**: ベンチマーク上のモデル性能と実タスクでの性能の大きな差。SWE-bench Verified で 50-60% ということは、実 issue のほぼ半分は解けないということです。+- 実際の開発結果は一つの要因だけの因果効果を示しません。ベンチマーク値は指定されたモデル、scaffold、データ、評価条件に限られます。- **Harness**: モデルの外側にあるすべて。指示、ツール、環境、状態管理、検証フィードバック。モデル重みでなければ harness です。この講義で言う「馬具」です。- **Harness 起因の失敗**: モデルには能力があるのに、実行環境に構造的欠陥があるため失敗すること。Anthropic の制御実験がこれを示しています。- **検証ギャップ**: エージェントの出力への自信と実際の正しさの差。エージェントが「完了」と言うが完了していない。最も多い失敗モードです。@@ -72,17 +85,19 @@ Completion criteria:## 100 万行の実験-OpenAI は 2025 年に強烈な実験を行いました。空の git リポジトリから、Codex で完全な社内プロダクトを構築する。5 か月後、そのリポジトリにはおよそ 100 万行のコードがありました。アプリケーションロジック、インフラ、ツール、ドキュメント、社内開発ツール。すべてエージェント生成です。3 人のエンジニアが Codex を操作し、約 1,500 PR を作成してマージしました。1 人あたり 1 日平均 3.5 PR です。+OpenAI は 2025 年に強烈な実験を行いました。空の git リポジトリから、Codex で完全な社内プロダクトを構築する。5 か月後、そのリポジトリにはおよそ 100 万行のコードがありました。アプリケーションロジック、インフラ、ツール、ドキュメント、社内開発ツール。すべてエージェント生成です。3 人のエンジニアが Codex を操作し、約 1,500 PR を作成してマージしました。1 人あたり 1 日平均 3.5 PR です。 [OpenAI](https://openai.com/index/harness-engineering/)-重要な制約は、**人間が直接コードを書かない**ことでした。これは見世物ではありません。エンジニアの主仕事がコードを書くことではなく、環境を設計し、意図を表現し、フィードバックループを作ることになったとき、何が変わるかを強制的に学ぶための設計でした。+実際の開発結果は一つの要因だけの因果効果を示しません。ベンチマーク値は指定されたモデル、scaffold、データ、評価条件に限られます。初期の進捗は予想より遅かった。Codex が無能だったからではなく、環境が不十分だったからです。エージェントには高レベル目標を進めるためのツール、抽象、内部構造が足りませんでした。エンジニアの仕事は、大きな目標を小さな構成要素(設計、コード、レビュー、テスト)に分解し、エージェントに組み立てさせ、それらの構成要素でより複雑なタスクを解けるようにすることになりました。何かが失敗したときの修正は、ほぼ常に「もっと頑張れ」ではなく、「エージェントに足りない能力は何か、それを理解可能かつ実行可能にするにはどうするか」でした。-この実験は、本講義の中心命題を直接示しています。**同じモデルでも、bare な環境と完全な harness を持つ環境では根本的に違う出力を出す。** モデルは変わっていません。環境が変わったのです。+実際の開発結果は一つの要因だけの因果効果を示しません。ベンチマーク値は指定されたモデル、scaffold、データ、評価条件に限られます。> Source: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)-## もっと身近な例+## 教育用の例++> 教育用の例:この場面と数値は仕組みを説明するための仮定であり、公表された実験の測定値ではありません。あるチームは Claude Sonnet を使って、中規模の Python Web アプリ(FastAPI + PostgreSQL + Redis、約 15,000 行)に新しい API endpoint を追加しようとしました。@@ -108,6 +123,8 @@ OpenAI は 2025 年に強烈な実験を行いました。空の git リポジ- [SWE-bench Leaderboard](https://www.swebench.com/)- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)+- [Anthropic: Sonnet 4.5 SWE-bench methodology, 2025-09-29](https://www.anthropic.com/news/claude-sonnet-4-5)+## 演習1. **比較実験**: よく知っているコードベースと非自明な変更タスクを選びます。まず harness 支援なしでエージェントを実行し、失敗を記録します。次に明示的な検証コマンドを含む `AGENTS.md` を追加し、同じエージェントで再実行します。結果を比較し、各失敗を 5 つの防御層のどれかに帰属させます。diff --git a/docs/ja/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/ja/lectures/lecture-02-what-a-harness-actually-is/index.mdindex 962a13d..c51201c 100644--- a/docs/ja/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/ja/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -70,7 +70,9 @@ Verification commands:**harness コンポーネントの価値を定量化する方法**: 同じモデルを固定したコンポーネント除去実験を使います。モデルを固定し、サブシステムを一つずつ削除し、どの削除が最大のパフォーマンス低下を引き起こすかを測定します。最大の低下は、そのタスクで限界貢献が最も大きいコンポーネントを示しますが、自動的にボトルネックを特定するわけではありません。低下がほぼゼロの場合も解釈が必要です。そのコンポーネントは冗長かもしれないし、設計が弱いだけかもしれないし、そのタスクでは十分に発火していないだけかもしれません。ボトルネックを診断するには、まず失敗ログと原因帰属を使い、除去実験は補助証拠として扱います。失敗の原因は、タスク意図の曖昧さ、コンテキスト不足、再現不能な環境、検証フィードバック不足、状態管理の断絶のどれだったのかを見ます。-## あるチームの実話+## 教育用の例++> 教育用の例:この場面と数値は仕組みを説明するための仮定であり、公表された実験の測定値ではありません。あるチームが GPT-4o を使って TypeScript + React のフロントエンドアプリ(約20,000行)に取り組みました。彼らは4つの段階を経ました — 本質的にはキッチン設備を一つずつ追加していったのです。diff --git a/docs/ja/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/ja/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdindex 6f3f57d..55621e6 100644--- a/docs/ja/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md+++ b/docs/ja/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -5,6 +5,8 @@# 講義 03. リポジトリを唯一の信頼できる情報源にする+> 設計上の目安:数値は調整可能な教材上の設定で、実験で確認された閾値ではありません。token 数は行数だけでなく、tokenizer と内容によります。+あなたのチームのアーキテクチャ判断は、Confluence、Slack、Jira、そして数人のシニアエンジニアの頭の中に散らばっている。人間にとっては、これはぎりぎり機能する。同僚に聞けるし、チャット履歴を検索できるし、ドキュメントを掘り返せる。どうにもならなければ、休憩室で誰かを捕まえることもできる。しかし AI エージェントにとって、リポジトリに存在しない情報は、単に存在しない。これは誇張ではない。エージェントの入力が実際に何かを考えてみよう。システムプロンプトとタスク説明、リポジトリ内のファイル内容、ツール実行の出力。それだけだ。Slack 履歴、Jira チケット、Confluence ページ、金曜午後に同僚とコーヒーを飲みながら話したアーキテクチャ判断。エージェントにはどれも見えない。「誰かに聞きに行く」ことも「チャット履歴を検索する」こともできない。リポジトリの中に閉じ込められたエンジニアであり、外側のことは何も知らない。diff --git a/docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdindex e52196a..c29d43d 100644--- a/docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md+++ b/docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -5,6 +5,8 @@# 講義 04. 指示を複数ファイルに分割する+> 設計上の目安:数値は調整可能な教材上の設定で、実験で確認された閾値ではありません。token 数は行数だけでなく、tokenizer と内容によります。+あなたは Harness Engineering に本気で取り組み始めた。`AGENTS.md` を作り、思いつく限りのルール、制約、学びをすべて詰め込んだ。1か月後には 300 行、2か月後には 450 行、3か月後には 600 行に膨れ上がった。そして気づく。エージェントの性能がむしろ悪くなっている。単純なバグ修正でも、関係のないデプロイ手順を読むために大量のコンテキストを消費する。300 行目に埋もれた重要なセキュリティ制約は完全に無視される。矛盾する 3 つのコードスタイル規則があり、エージェントは毎回ランダムに 1 つを選ぶ。これが「巨大な指示ファイル」の罠だ。スーツケースに荷物を詰め込みすぎるのに似ている。どれも役に立ちそうだから、ファスナーがはち切れそうになるまで全部入れてしまう。替えの下着を探すだけで、バッグ全体を空にしなければならない。満杯のスーツケースを運んでいるのに、実際に使うのは中身の 3 分の 1 くらいだ。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.mdindex b1b35f0..0ea3409 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@@ -5,6 +5,8 @@# 講義 05. セッションをまたいでコンテキストを保つ+> 設計上の目安:数値は調整可能な教材上の設定で、実験で確認された閾値ではありません。token 数は行数だけでなく、tokenizer と内容によります。+Claude Code に完全な機能の実装を頼んだとします。30分間実行され、大部分の作業を終えますが、コンテキストが残り少なくなっています。新しいセッションを開始して続きをさせると — 前回どのような決定がなされたか、なぜオプション A が B より選ばれたか、どのファイルがすでに変更されたか、テストがどのような状態かを覚えていないことがわかります。プロジェクトを再探索するのに15分を費やし、前回のアプローチと矛盾する可能性もあります。毎朝目覚めるとすべてを忘れてしまう職人だと想像してください。建設現場全体に再度慣れる必要があります — どの壁が半分まで建っているか、なぜ赤レンガが青レンガより選ばれたか、配管はどこまで進んでいるか。さらに悪いことに、昨日すでに設置された窓を、完了したことを覚えていないために取り壊してしまうかもしれません。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.mdindex acd9b98..627e196 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@@ -5,6 +5,8 @@# 講義 06. すべてのエージェントセッション前に初期化する+> 設計上の目安:数値は調整可能な教材上の設定で、実験で確認された閾値ではありません。token 数は行数だけでなく、tokenizer と内容によります。+新しいエージェントセッションを開始し、「検索機能を追加して」と言います。エージェントはすぐにコーディングに飛び込みます — 勇気ある意欲です。20分後、テストフレームワークが正しく設定されていないことを発見し、それを直すのにさらに10分、次にデータベースのマイグレーションスクリプトの形式が間違っていて、さらに調整。検索機能は最終的に追加されましたが、セッション全体として非効率でした — ほとんどの時間は「このプロジェクトがどう動いているかを理解する」ことに費やされ、「検索機能を書く」ことにはほとんど使われませんでした。より良いアプローチ: エージェントに作業を始めさせる前に、別のフェーズを使って基本環境を準備し、検証コマンドを通るようにし、プロジェクト構造を理解させます。家を建てるようなものです — 基礎を打つことと壁を立てることを同時には行いません。同時に行うと、基礎が固まる前に壁が立ち上がり、建物全体を取り壊してやり直すことになります。まず基礎を打ち、固まるのを待ってから壁を建てる — きれいで効率的です。@@ -37,6 +39,8 @@ flowchart TB## 混ぜたときに何が起きるか+> 教育用の例:この場面と数値は仕組みを説明するための仮定であり、公表された実験の測定値ではありません。+最も直接的な問題: 基礎が正しく固まらない。エージェントは労力の80%を機能コードに、20%を適当にインフラの設定に使います。テストフレームワークは設定されたが検証されていない、lint ルールは設定されたが緩すぎる、進捗ファイルは作成されていない。これらの欠陥は最初のセッションでは明らかではありません(エージェントは自分が何をしたかまだ覚えているからです)が、2回目のセッションで表面化します — 新しいエージェントは実行方法、テスト方法、現状がどうなっているかを知りません。ずさんな基礎、ぐらつく建物です。より隠れたコストは「未検証の蓄積」です — テストフレームワークが設定される前に書かれた機能コードは、検証のないコードです。後からそのコードにテストを追加しに行くと、設計が最初から間違っていたことに気づくかもしれません — 知っていれば別の方法で実装していたでしょう。生のコンクリートの上にタイルを貼るようなものです — 床が水平でないことに気づいたとき、すべてのタイルを剥がしてやり直さなければなりません。@@ -45,7 +49,7 @@ flowchart TB最も見落とされやすい問題は、暗黙の前提の地雷です。初期化中にエージェントが行う決定(どのテストフレームワーク、ディレクトリの整理方法、依存関係の管理)— 明示的に記録されていなければ、後続のセッションはこれらの選択を理解できません。さらに悪いことに、後続のセッションが矛盾する選択をする可能性があります。最初の建設チームがコンクリート基礎を使ったのに、2番目のチームはそれを知らずに木製の杭を打ち込んだ — 基礎にひびが入ります。-Anthropic の長時間アプリケーション開発研究は、初期化と実装を分離することを明確に推奨しています。彼らの実験データ: 専用の初期化フェーズを使用したプロジェクトは、混在アプローチと比較してマルチセッションシナリオで31%高い機能完了率を示しました。重要な洞察 — 初期化フェーズに投資した時間は、次の3〜4セッションで完全に回収されます。基礎がしっかりしているほど、壁は速く立ち上がります。+[Anthropic: initializer / coding agent](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)OpenAI の Codex harness engineering ガイドも「リポジトリを運用記録とする」原則を強調しています — 最初の実行から明確な運用構造を確立しなければ、新しいセッションは毎回プロジェクトの規約を推測し直すことになります。@@ -122,7 +126,9 @@ OpenAI の Codex harness engineering ガイドも「リポジトリを運用記- [ ] Everything committed to git```-## 実例+## 教育用の例++> 教育用の例:この場面と数値は仕組みを説明するための仮定であり、公表された実験の測定値ではありません。React フロントエンドプロジェクトの2つの初期化アプローチ: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.mdindex f3cb6b2..f792a84 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@@ -5,6 +5,8 @@# 講義 07. エージェントのタスク境界を明確にする+> 設計上の目安:数値は調整可能な教材上の設定で、実験で確認された閾値ではありません。token 数は行数だけでなく、tokenizer と内容によります。+Claude Code に「このプロジェクトにユーザー認証を追加して」と頼むと、データベーススキーマの変更を始め、ルートを書き、フロントエンドのコンポーネントを変更し、ついでにエラーハンドリングミドルウェアのリファクタリングまで始めます。2時間後に確認すると: 12ファイルが変更され、800行の新しいコードがあり、エンドツーエンドで動く機能は一つもありません。背に腹は代えられない — この言葉は AI エージェントに特に当てはまります。エージェントには「ついでにもう少しやっておこう」という衝動が生まれつき備わっています — 関連するものを見ると、つい道沿いに処理してしまう。醤油を1本買いにスーパーに行って、満載のカートを押して出てくるような人です。問題は、買いすぎた人はお金を無駄にするだけですが、エージェントが同時に多くのことをしようとすると、どれも適切に完了しないということです。@@ -26,7 +28,7 @@ Claude Code の実際の行動がそれを物語っています。「ユーザ6ステップ後、すべてが半完成。エンドツーエンドの検証はなく、半完成のコード間に複雑な結合があり、次のセッションで片付けを引き継ぐ者は完全に途方に暮れます。6つの料理を同時に作るようなもの — すべての料理が鍋に入っているが、どれも皿に盛られていません。すべて焦げます。-Anthropic の実験データはこれを直接的に裏付けています: 「小さな次のステップ」戦略(WIP=1 に相当)を使うエージェントは、広範なプロンプトを使うエージェントより37%高いタスク完了率を示します。さらに興味深いことに、エージェントが生成するコード行数と実際の機能完了率は弱い負の相関があります — より多くのコードを書いた方が、より少ない機能が完了する。背に腹は代えられない、データによる証明です。+[Anthropic: incremental feature work](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## WIP=1 ワークフロー@@ -100,7 +102,9 @@ F01: User Registrationharness は VCR(Verified Completion Rate)= 検証済みタスク数 / 起動タスク数 を継続的に追跡するべきです。VCR < 1.0 のときは新しいタスクの起動をブロックします。-## 実例+## 教育用の例++> 教育用の例:この場面と数値は仕組みを説明するための仮定であり、公表された実験の測定値ではありません。8つの機能を持つ REST API プロジェクト、2つの戦略を比較: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.mdindex ffa1346..0457e5b 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@@ -5,6 +5,8 @@# 講義 08. 機能リストでエージェントの作業を制約する+> 設計上の目安:数値は調整可能な教材上の設定で、実験で確認された閾値ではありません。token 数は行数だけでなく、tokenizer と内容によります。+エージェントに e コマースサイトを作らせる。完了後、エージェントは「done」と言う。コードを見ると、ユーザー認証は動くが、カートのチェックアウトボタンは何もせず、決済フローも接続されていない。問題は、あなたが「done」の意味を伝えていなかったことだ。そのためエージェントは自分の基準、つまり「たくさんコードを書いたし、かなり完成して見える」を使った。多くの人にとって、機能リストはただのメモだ。忘れないように書き出し、あとで脇に置くもの。しかし harness の世界では、機能リストは人間向けメモではない。harness 全体の背骨だ。スケジューラはそれを使ってタスクを選び、検証器は完了判定に使い、引き継ぎレポーターは要約生成に使う。背骨が折れれば、全身が動かなくなる。@@ -23,7 +25,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)## 機能状態マシン@@ -104,7 +106,9 @@ flowchart LR各機能項目は「1 セッションで完了できる」範囲にする。広すぎると終わらず、狭すぎると管理コストが増える。「ユーザーが商品をカートに追加できる」はよい粒度だ。「ショッピングカートを実装する」は広すぎる。「Cart モデルに name フィールドを作る」は狭すぎる。ステーキを切るのと同じで、丸ごとでもひき肉でもない。-## 実例+## 教育用の例++> 教育用の例:この場面と数値は仕組みを説明するための仮定であり、公表された実験の測定値ではありません。10 個の機能を持つ e コマースプラットフォームで、2 つの追跡方法を比較した。@@ -112,8 +116,6 @@ flowchart LR**背骨モード**: すべての機能が明確な状態と検証コマンドを持つ。新しいセッションは機能リストを読み、3 分で F01-F05 は `passing`、F06 は `active`、F07-F10 は `not_started` と分かる。F06 から直接再開し、手戻りはゼロ。-定量結果: 構造化された機能リストを使うプロジェクトは、自由形式の追跡より機能完了率が 45% 高く、重複実装はゼロだった。-## 重要なポイント- **機能リストは harness の背骨**であり、人間向けメモではない。Scheduler、verifier、handoff reporter はすべてそれに依存する。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.mdindex 8cb28e3..bf72454 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@@ -5,6 +5,8 @@# 講義 09. エージェントの早すぎる完了宣言を防ぐ+> 設計上の目安:数値は調整可能な教材上の設定で、実験で確認された閾値ではありません。token 数は行数だけでなく、tokenizer と内容によります。+agentに「パスワードリセット」機能の実装を依頼するとします。agentはデータベーススキーマを変更し、APIエンドポイントを書き、メールテンプレートを追加し、ユニットテストを実行(すべて合格)し、自信満々に「完了した」と報告します。しかし実際に動かしてみると——パスワードリセットリンクが送信できない(メールサービスの設定が不足)、データベースマイグレーションが途中で失敗する(スキーマの不整合)、end-to-endフローは一度も実行されていない。この感覚は馴染み深いはずです——試験用紙を全部埋め、自信満々に最初に提出したのに、成績発表で不合格になるのと同じです。用紙が埋まっていることと、答えが合っていることは別なのです。@@ -13,6 +15,8 @@ agentに「パスワードリセット」機能の実装を依頼するとしま## なだらかな斜面+> モデルとプロンプトは同じですが、時間と費用の予算が異なります。同予算で一つの構成要素を分離した実験ではありません。基本的なゲーム操作は動作しましたが、不具合は残りました。 [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)+早すぎる完了宣言は、ほぼ常に同じパターンを辿ります。コードは問題なさそうに見えます——構文は正しく、ロジックは妥当で、静的解析にも明らかなエラーはありません。しかし、harnessは包括的な実行検証を強制していないため、agentは実際の実行をスキップするか、部分的なテストしか実行しません。ユニットテストは実行するがインテグレーションテストはスキップし、テストは実行するがカバレッジは確認しません。最終的に「コードは問題ない」ことが「機能は完成している」の証拠として扱われます。そして試験用紙が提出されます。すべての段階で情報が失われます。タスク仕様からコード実装、そしてランタイム動作に至るまで、すべての変換でバイアスが生じる可能性があり、スキップされた検証ごとに情報の非対称性が悪化します。@@ -111,7 +115,9 @@ OpenAIはCodexの実践で特に効果的なパターンを導入しました:- データベース書き込み、ファイル操作、その他の副作用は正しかったか?- 一時リソースはクリーンアップされたか?-## 実際のケース+## 教育用の例++> 教育用の例:この場面と数値は仕組みを説明するための仮定であり、公表された実験の測定値ではありません。**タスク**:ユーザーのパスワードリセット機能の実装。データベース操作、メール送信、APIエンドポイントの変更が含まれます。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.mdindex 84ff412..bba6ddd 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@@ -5,6 +5,8 @@# 講義 10. End-to-End テストだけが本当の検証である+> 設計上の目安:数値は調整可能な教材上の設定で、実験で確認された閾値ではありません。token 数は行数だけでなく、tokenizer と内容によります。+agentにElectronアプリへのファイルエクスポート機能の追加を依頼するとします。agentはrenderプロセスコンポーネント、preloadスクリプト、サービスレイヤーロジックを書きます。各コンポーネントのユニットテストは完璧に合格します。agentは「完了した」と言います。実際にエクスポートボタンをクリックしてみると——ファイルパスの形式が間違っていて、プログレスバーが更新されず、大きなファイルのエクスポートでメモリリークが発生します。5つのコンポーネント境界の欠陥があり、ユニットテストは一つも検出していません。合唱のリハーサルのようなものです——各パートが単独で歌うときは完璧に聞こえますが、一緒に歌うと、ソプラノがベースより半拍速く、伴奏が主旋律から半音ずれています。各パートは単独では「正しい」のに、全体が音程を外しています。@@ -116,7 +118,9 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.reaコードレビュー中に新しいタイプのagentエラーが見つかるたびに、それを自動チェックに変換します。1ヶ月後には、harnessは月初めよりも大幅に強力になっています。合唱のリハーサルノートのようなもの——各リハーサルで見つかった問題を記録し、次回の前にチェックします。時間が経つにつれてよくあるエラーは減り、音楽はより調和の取れたものになります。-## 実際のケース+## 教育用の例++> 教育用の例:この場面と数値は仕組みを説明するための仮定であり、公表された実験の測定値ではありません。**タスク**:Electronアプリにファイルエクスポート機能を実装する。renderプロセスUI、preloadスクリプトのファイルシステムプロキシ、サービスレイヤーのデータ変換が含まれます。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.mdindex c3031be..5b5ae6e 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@@ -32,7 +32,9 @@ flowchart LRVerdict --> Generator```-## なぜこれが起きるのか+## 教育用の例++> 教育用の例:この場面と数値は仕組みを説明するための仮定であり、公表された実験の測定値ではありません。### 観測性不足の本当のコスト@@ -44,7 +46,7 @@ harness に観測性がないと、4 種類の問題が体系的に発生しま**再試行が盲目的な推測になる**: 失敗理由がわからないと、再試行の方向はランダムになります。本当の原因を無視して関係ないコード経路を直し続けるかもしれません。盲目的な再試行はすべてトークンと時間を消費します。-**セッション引き継ぎの情報断崖**: 未完了の作業を次セッションに渡すとき、観測性がないと新しいセッションはシステム状態をゼロから診断し直す必要があります。Anthropic の長時間エージェント観察では、この重複診断がセッション時間の 30-50% を消費することがあります。+進捗と検証結果をバージョン管理されたファイルに記録し、次のセッションが状態を確認できるようにします。引用元は仕組みを説明しており、起動時間の削減率は報告していません。 [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)### Claude Code での現実的なシナリオ@@ -116,7 +118,9 @@ harness に観測性がないと、4 種類の問題が体系的に発生しま各 harness セッションに trace、各タスクに span、各検証ステップに sub-span を作ります。標準属性で重要情報を注釈します。これにより、観測性データを Jaeger や Zipkin などの標準ツールチェーンに統合できます。-## 実例+## 教育用の例++> 教育用の例:この場面と数値は仕組みを説明するための仮定であり、公表された実験の測定値ではありません。planner-generator-evaluator workflow の harness で「ダークモード対応を追加する」場合です。@@ -136,7 +140,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.mdindex 6682cdf..e5e8409 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@@ -5,6 +5,8 @@# 講義 12. すべてのセッションをきれいな引き継ぎで終える+> 設計上の目安:数値は調整可能な教材上の設定で、実験で確認された閾値ではありません。token 数は行数だけでなく、tokenizer と内容によります。+## この講義が解決する問題agentが午後ずっと動いて、20のファイルを変更し、コードをコミットし、セッションが終了します。次のagentセッションが始まると、すぐに発見します:ビルドが壊れている、テストが赤い、一時的なデバッグファイルが至る所にある、feature listが更新されていない、進捗が完全に不明。新しいセッションは最初の30分を「前のセッションが実際に何をしたのか」を理解するだけに費やします。@@ -54,6 +56,8 @@ flowchart LRLehmanのソフトウェア進化の法則が教えてくれること:継続的な変更を受けるシステムは、積極的に管理されない限り、必然的に複雑さが増大します。これはAIコーディングagentにとって特に当てはまります——すべてのセッションが変更を導入し、終了時のクリーンアップがなければ、技術的負債は指数関数的に蓄積します。+> 教育用の例:この場面と数値は仕組みを説明するための仮定であり、公表された実験の測定値ではありません。+実際のデータが物語っています。agentを使って12週間開発されたプロジェクト、クリーンアップ戦略なしの場合:- 週1:ビルド合格率 100%、テスト合格率 100%、新セッション起動 5分@@ -66,8 +70,6 @@ Lehmanのソフトウェア進化の法則が教えてくれること:継続- 週1:100%、100%、5分- 週12:97%、95%、9分-12週間後:ビルド合格率の差は29ポイント、新セッション起動時間の差は85%。これは理論ではなく、観察された差異です。-### クリーン状態の5つの次元クリーン状態とは単に「コードがコンパイルできる」ことではありません。5つの次元を総合的に評価するものです:@@ -76,7 +78,7 @@ Lehmanのソフトウェア進化の法則が教えてくれること:継続**テストの次元**:すべてのテストは通るか?セッションの前に存在していたテストも含みます——セッションは既存の機能を壊さない責任があります。そして「自分のマシンでは動く」ではなく、CIで検証されるべきです。-**進捗の次元**:現在の進捗は機械可読なアーティファクトに記録されているか?合格基準と共に完了したサブタスク、現在の状態と共に進行中だが未完了のサブタスク、未着手のサブタスク。良い進捗記録は、セッション起動時の診断時間を60〜80%削減します。+進捗と検証結果をバージョン管理されたファイルに記録し、次のセッションが状態を確認できるようにします。引用元は仕組みを説明しており、起動時間の削減率は報告していません。 [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)**アーティファクトの次元**:古い、または不明瞭な一時アーティファクトが残っていないか?デバッグログ、一時ファイル、コメントアウトされたコード、TODOマーカー——これらはすべて次のセッションの認知負荷を増やします。@@ -152,7 +154,9 @@ git checkout -- .env.local # Restore to known statenpm run test # Verify cleanup didn't break anything```-## 実際のケース+## 教育用の例++> 教育用の例:この場面と数値は仕組みを説明するための仮定であり、公表された実験の測定値ではありません。agentを使って12週間にわたり開発されたElectronアプリ、2つのアプローチの比較:@@ -160,8 +164,6 @@ agentを使って12週間にわたり開発されたElectronアプリ、2つの**クリーンアップ戦略あり**(実験群):各セッション終了時にフルクリーン状態チェック + 週次クリーンアップループ。週12でビルド合格率 97%、テスト合格率 95%、新セッション起動 9分、古いアーティファクト 11。-週12までに、実験群のビルド合格率は29ポイント高く、テスト合格率は34ポイント高く、新セッション起動時間は85%短縮されました。-## 重要なポイント- **クリーン状態はセッション完了の必要条件**——オプションの片付けではなく、「完了の定義」の一部。diff --git a/docs/ja/lectures/lecture-13-loop-engineering/index.md b/docs/ja/lectures/lecture-13-loop-engineering/index.mdindex 8e349e7..f336cfd 100644--- a/docs/ja/lectures/lecture-13-loop-engineering/index.md+++ b/docs/ja/lectures/lecture-13-loop-engineering/index.md@@ -5,6 +5,8 @@# 第13回 手動プロンプトから自律ループへ+> 設計上の目安:数値は調整可能な教材上の設定で、実験で確認された閾値ではありません。token 数は行数だけでなく、tokenizer と内容によります。+これまでの12回の講義で学んだことはすべて、次の前提に基づいています:**あなたがキーボードの前に座り、一度に一つずつ指示を入力すること。**あなたは `AGENTS.md` を書き(第1–4回)、状態管理を構築し(第5–6回)、機能リストでスコープを制約し(第7–8回)、セッション終了時にクリーンな引き継ぎを残し(第9、12回)、ランタイムを観測可能にしました(第10–11回)。しかし、そのすべてのトリガーは常にあなたでした。エージェントが自発的に仕事を始めることはなかったのです——「スタート」を押す人がいなかったからです。@@ -84,8 +86,12 @@毎回 `/goal` を入力する必要はありません。しかし、それがどこから来て、なぜこのような形になったのかを理解すること——それがループエンジニアリングの核心を理解することです。より複雑なループは、スケジューリング、並列性、隔離、メモリといった部品を、この同じ3つの基本——ゴール、検証、停止条件——の上に追加しているだけです。+> 教育用の例:この場面と数値は仕組みを説明するための仮定であり、公表された実験の測定値ではありません。+## 2026年6月:3人が1週間で同じ導火線に火をつけた+> 教育用の例:この場面と数値は仕組みを説明するための仮定であり、公表された実験の測定値ではありません。+2026年6月の第1週、コーディングエージェントのインフラを構築していた3人の実践者が——情報を交換することなく——異なる言葉で同じことを言いました。**Peter Steinberger**(OpenClawの生みの親、[彼の投稿は800万回閲覧されました](https://x.com/steipete/status/2063697162748260627)):「もうコーディングエージェントにプロンプトを与えるべきではない。エージェントにプロンプトを与えるループを設計すべきだ。」@@ -96,7 +102,13 @@> **ループエンジニアリングとは、エージェントにプロンプトを与える人としての自分自身を置き換えることです。その代わりにシステムを設計するのです。**-Chernyは数字を明かしています:30日間連続で、Claude Codeへのすべてのコード貢献はAIによって自律的に行われ——259のマージされたPR、本番コードの80%以上がClaudeによって作成され、オープンエンドなソフトウェアタスクで76%の成功率を記録しました。+Boris Cherny · 2025-12-27++| PR | Git commits | + LoC | − LoC | Model |+| --- | --- | --- | --- | --- |+| 259 / 30 days | 497 | 40,000 | 38,000 | Claude Code + Opus 4.5 |++著者本人が報告した個人の開発実績で、ベンチマーク成功率や人間の監督がなかった証拠ではありません。 [Boris Cherny](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)3人。1週間。同じ結論。調整したからではありません——インフラが静かに臨界点を越えたからです。エージェントは、監視なしでも些細でないタスクを完了できるほど信頼できるようになっていました。スケジューリングのプリミティブ(`/loop`、`/goal`、cron)がツールに組み込まれるようになりました。1回のエージェント実行のコストが十分に低くなり、タイマーで繰り返し実行することが無駄に思えなくなりました。すべての部品が揃ったとき、それらを組み合わせる動きは、誰にでも同時に明らかになるのです。@@ -267,7 +279,7 @@ flowchart TDこれはもはや単一のエージェント実行ではありません。毎朝起動し、自ら床を掃き、あなたの注意が必要なものを目の前に置いてくれる、継続的に動作するシステムです。あなたの役割は次のようになります:**受信箱の中身をレビューし、意思決定をし、システムが対処できないパターンを見つけたらスキルとルールを洗練する。**-Chernyはこのパターンを使って、IDEを一度も開くことなく30日で259のPRをマージしました。OpenAIのエンジニアたちは同じパターンを使って、約100万行のベータ製品を——自分で一行もコードを書くことなく——構築しました。+著者本人が報告した個人の開発実績で、ベンチマーク成功率や人間の監督がなかった証拠ではありません。## 生成者/評価者の分離:なぜモデルに自分の仕事を採点させてはいけないのか@@ -293,7 +305,7 @@ Chernyはこのパターンを使って、IDEを一度も開くことなく30日よく設計され、実際に動いているループがどんなものかを見たいなら、[Karpathyのautoresearch](https://github.com/karpathy/autoresearch) が教科書的な例です。-2026年3月、Karpathyは630行のPythonプロジェクトをリリースしました。GPUを1つと研究の方向性を与えると、一晩中動き続け——何百ものML学習実験を完了し、本当に改善するものだけを保持します。このプロジェクトはリリース後数日で66,000スター以上を獲得しました。+[Karpathy: autoresearch](https://github.com/karpathy/autoresearch) · [announcement](https://x.com/karpathy/status/2030371219518931079)### 3つのファイル、3つの役割@@ -343,8 +355,6 @@ flowchart TD8b --> 9```-1時間に約12回の実験を実行します。一晩(8時間)で約100回の実験になります。Karpathy自身は2日間実行しました——約700回の実験です。-固定の5分実時間予算は重要な設計選択です——エージェントが何を変更しようとも、すべての実験にはまったく同じ時間がかかります。これは、同じ時間予算のもとですべての結果が直接比較可能であることを意味します——「これは長く実行したから良い」という議論は成り立ちません。### 出力:目覚めたときに見るもの@@ -359,6 +369,8 @@ flowchart TDすべての実験——成功か失敗か——が記録されます:+> 教育用の例:この場面と数値は仕組みを説明するための仮定であり、公表された実験の測定値ではありません。+```timestamp commit_hash val_bpb vram_mb description--------- ------------- ---------- ---------- ----------------------------@@ -375,11 +387,10 @@ timestamp commit_hash val_bpb vram_mb description### 実際に何が見つかったか-Karpathyの最初の2日間、約700回の実験ランからの結果:+- nanochatのGPT-2レベルの学習時間を、8×H100上で**2.02時間 → 1.80時間**に短縮、約**10.89%の高速化**+- 発見内容:学習率調整、オプティマイザーチューニング、活性化関数の交換、アテンションパターンの最適化など [Karpathy: leaderboard commit](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b) · [tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)-- 約700回の試行のうち、約**20個の積み重ね可能な真の改善**が見つかった-- nanochatのGPT-2レベルの学習時間を、8×H100上で**2.02時間 → 1.80時間**に短縮、約**11%の高速化**-- 発見内容:学習率調整、オプティマイザーチューニング、活性化関数の交換、アテンションパターンの最適化など+> 教育用の例:この場面と数値は仕組みを説明するための仮定であり、公表された実験の測定値ではありません。すべての改善が画期的な発見だったわけではありません。ほとんどは積み重ね可能な小さな最適化でした。しかし、これら20個の有効な改善は、人間の研究者なら数週間の手作業がかかったであろうものです——エージェントは48時間でそれを成し遂げました。@@ -399,7 +410,7 @@ Karpathyの最初の2日間、約700回の実験ランからの結果:### 2. 理解の腐敗-ループがコードを出荷するのが速いほど、自分自身のコードベースに対する理解が現実から乖離していきます。Chernyのチームはコードの80%がエージェントによって作成されていました——つまり、チームのコードの大部分が人間によって書かれていないのです。ループが生み出したものを読んで使わなければ、理解は継続的に減衰します。**速いループには速い読みが必要です。**+実際の開発結果は一つの要因だけの因果効果を示しません。ベンチマーク値は指定されたモデル、scaffold、データ、評価条件に限られます。### 3. 認知的降伏diff --git a/docs/ja/lectures/lecture-14-graph-engineering/index.md b/docs/ja/lectures/lecture-14-graph-engineering/index.mdindex d0257f7..933e927 100644--- a/docs/ja/lectures/lecture-14-graph-engineering/index.md+++ b/docs/ja/lectures/lecture-14-graph-engineering/index.md@@ -261,7 +261,7 @@ run(graph, entry={"requirements": "ログインページのバグを修正"}, th**概念公開後に出たもの**-- [GraphArc](https://github.com/CodeGraphContext/grapharc)(2026-08-02):自称「Graph Engineeringの最初のリアルタイム実装」。エージェント実行をログに埋もれたtraceから、一枚の**インタラクティブなリアルタイム編成グラフ**に変えます——各エージェント、各依存関係、各決定ポイントが描かれ、実行前にグラフ全体を可視化し、あなたが確認して(スマホで見ることもできます)から放行します。作者の背景は4000人以上の開発者向けのグラフツール作りで、方向性は「観測可能、デバッグ可能、エンジニアリング可能」です。非常に新しいので、機能はまだ初期段階です。+- [GraphArc](https://github.com/CodeGraphContext/grapharc)**概念公開前にあったもの(それらはGraph Engineeringと呼ばれていないが、あなたが構築するときに使うのはそれら)**@@ -346,4 +346,4 @@ run(graph, entry={"requirements": "ログインページのバグを修正"}, th4. **5つの判断基準で評価する:** 現在「グラフ化」するか迷っているタスクを一つ選び、5つの判断基準で一つずつ採点する。少なくとも3つを満たして初めて図を描く価値がある。3つ未満なら、それに必要なのは実はより良いワークフロースクリプト——グラフを使うために使うな。-5. **graph.mdを実行可能なプログラムにする:** 本講義の「ゼロから最初のグラフを構築する」の6ステップに従って、描いたmaker-checkerグラフを実際に動くグラフとして実装する(リファレンス実装:`code/maker_checker_graph.py`、LangGraphで書かれている)。6ステップを飛ばさない:状態の定義 → ノードの列挙 → エッジの接続 → ルーティングの記述 → checkpointの設置 → 実行。実行後、`graph.md`とコードを照合し、最初に対応しない場所を見つけて、なぜ対応しないのかを説明する——図の描き方が間違っているのか、コードの書き方が間違っているのか?\ No newline at end of file+5. **graph.mdを実行可能なプログラムにする:** 本講義の「ゼロから最初のグラフを構築する」の6ステップに従って、描いたmaker-checkerグラフを実際に動くグラフとして実装する(リファレンス実装:`code/maker_checker_graph.py`、LangGraphで書かれている)。6ステップを飛ばさない:状態の定義 → ノードの列挙 → エッジの接続 → ルーティングの記述 → checkpointの設置 → 実行。実行後、`graph.md`とコードを照合し、最初に対応しない場所を見つけて、なぜ対応しないのかを説明する——図の描き方が間違っているのか、コードの書き方が間違っているのか?diff --git a/docs/ja/resources/reference/index.md b/docs/ja/resources/reference/index.mdindex d647a4c..463b7dd 100644--- a/docs/ja/resources/reference/index.md+++ b/docs/ja/resources/reference/index.md@@ -24,6 +24,11 @@- [On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents](https://arxiv.org/html/2601.20404v2): gpt-5.2-codex; 10 repos / 124 PR tasks; Table 1.+- [Anthropic: Sonnet 4.5 — SWE-bench Verified methodology (2025-09-29)](https://www.anthropic.com/news/claude-sonnet-4-5)+- [Boris Cherny: personal 30-day production report (2025-12-27)](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)+- [Karpathy: measured autoresearch leaderboard improvement](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b)+- [Karpathy: two-day autonomous tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)+## 推奨読書順1. `method-map.md`diff --git a/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex 564cb96..a975529 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,19 +11,32 @@ AI 세계에 꽤 익숙하다고 자부합니다 — Claude Pro 구독, GPT-4o A처음 든 생각은 이겁니다: "이 모델은 아직 부족해. 더 좋은 걸로 바꿔야겠어." 잠깐, 지갑을 꺼내기 전에 — 문제가 모델에 있지 않을 수도 있다는 점을 먼저 짚어봐야 합니다.-숫자를 봅시다. 2025년 말 기준 SWE-bench Verified에서 가장 강력한 코딩 에이전트들은 대략 50-60%의 정확도를 기록합니다. 그것도 명확한 이슈 설명과 기존 테스트 케이스가 갖춰진 엄선된 작업 기준입니다. 막연한 요구사항, 테스트 없음, 암묵적 비즈니스 규칙이 여기저기 흩어진 실제 개발 환경으로 넘어오면 그 수치는 더 낮아집니다.+Claude Sonnet 4.5 · 2025-09-29 · SWE-bench Verified++| Score | Tasks | Trials | Scaffold |+| --- | --- | --- | --- |+| 77.2% | 500 | 10 | bash + string replacement |++실제 개발 성과는 단일 원인의 효과를 분리하지 않습니다. 벤치마크 값은 명시된 모델, scaffold, 데이터와 평가 조건에 적용됩니다. [Anthropic: methodology](https://www.anthropic.com/news/claude-sonnet-4-5)그런데 이 수치들 뒤에는 직관에 반하는 진실이 있습니다.## 같은 말(馬), 다른 결과-Anthropic이 통제 실험을 진행했습니다. 동일한 프롬프트("2D 레트로 게임 메이커를 만들어라"), 동일한 모델(Opus 4.5). 첫 번째 실행: 아무런 지원 없이 맨손 — 20분, 9달러, 게임의 핵심 기능은 전혀 작동하지 않았습니다. 두 번째 실행: 완전한 하네스(harness) 적용(플래너 + 제너레이터 + 이밸류에이터 3에이전트 아키텍처) — 6시간, 200달러, 게임을 실제로 플레이할 수 있었습니다.+> 모델과 프롬프트는 같지만 시간과 비용 예산이 다릅니다. 동일 예산에서 구성 요소 하나를 분리한 실험이 아닙니다. 핵심 게임 기능은 작동했으나 결함이 남았습니다. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++모델과 프롬프트는 같지만 시간과 비용 예산이 다릅니다. 동일 예산에서 구성 요소 하나를 분리한 실험이 아닙니다. 핵심 게임 기능은 작동했으나 결함이 남았습니다. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++| Opus 4.5 | Duration | USD |+| --- | --- | --- |+| Solo | 20 min | 9 |+| Full harness | 6 h | 200 |하네스(harness)란 AI 코딩 에이전트가 안정적으로 동작하도록 환경·상태(state)·검증(verification)·제어를 묶어서 제공하는 외골격(스캐폴딩) 시스템입니다. 모델 가중치 외부에 있는 모든 엔지니어링 인프라가 하네스에 해당합니다.모델은 바꾸지 않았습니다. Opus 4.5는 여전히 Opus 4.5였죠. 바뀐 것은 마구(tack)였습니다.-OpenAI의 2025년 하네스 엔지니어링 글은 명확하게 밝힙니다: 잘 갖춰진 저장소(repository)에서의 Codex는 "불안정"에서 "안정"으로 질적 전환을 이룬다고. 표현에 주목하세요 — "조금 나아진"이 아니라 질적 변화입니다. 마치 경주마처럼: 적절한 마구 없이도 탈 수 있지만, 멀리 갈 수 없고, 빠르게 달릴 수 없으며, 낙마도 놀랍지 않습니다. 하네스는 그 전체 마구입니다 — **모델 가중치 외부의 엔지니어링 인프라 전체입니다.**+실제 개발 성과는 단일 원인의 효과를 분리하지 않습니다. 벤치마크 값은 명시된 모델, scaffold, 데이터와 평가 조건에 적용됩니다. [OpenAI: 2026-02-11](https://openai.com/index/harness-engineering/)## 에이전트가 실제로 막히는 지점@@ -43,9 +56,9 @@ OpenAI의 2025년 하네스 엔지니어링 글은 명확하게 밝힙니다:이 시나리오들을 염두에 두면 다음 개념들이 단순한 전문 용어 이상으로 다가옵니다.-- **역량 격차(Capability Gap)**: 벤치마크 성능과 실제 작업 성능 사이의 큰 간극. SWE-bench Verified에서 50-60%의 통과율은 실제 이슈의 거의 절반이 해결되지 않는다는 의미입니다.+- 실제 개발 성과는 단일 원인의 효과를 분리하지 않습니다. 벤치마크 값은 명시된 모델, scaffold, 데이터와 평가 조건에 적용됩니다.- **하네스(Harness)**: 모델 외부의 모든 것 — 지시사항, 도구, 환경, 상태(state) 관리, 검증(verification) 피드백. 모델 가중치가 아니라면 모두 하네스입니다. 우리가 "마구"라고 부른 것입니다.-- **하네스 유발 실패(Harness-Induced Failure)**: 모델은 충분한 역량을 갖췄지만 실행 환경에 구조적 결함이 있는 경우. Anthropic의 통제 실험이 이를 이미 증명했습니다.+- **하네스 유발 실패(Harness-Induced Failure)**: 모델은 충분한 역량을 갖췄지만 실행 환경에 구조적 결함이 있는 경우.- **검증 격차(Verification Gap)**: 에이전트가 자신의 산출물(deliverable)에 대해 갖는 자신감과 실제 정확성 사이의 간극. 에이전트가 "완료했다"고 말하지만 완료하지 않은 상태 — 이것이 가장 흔한 실패 유형입니다.- **진단 루프(Diagnostic Loop)**: 실행 → 실패 관찰 → 특정 하네스 레이어에 귀속 → 해당 레이어 수정 → 재실행. 이것이 하네스 엔지니어링의 핵심 방법론입니다.- **완료 기준(Definition of Done)**: 기계 검증 가능한 조건들의 집합 — 테스트 통과, 린트 클린, 타입 검사 통과. 명시적인 완료 기준이 없으면 에이전트는 자체 기준을 만들어냅니다.@@ -76,17 +89,19 @@ OpenAI의 2025년 하네스 엔지니어링 글은 명확하게 밝힙니다:## 백만 줄 코드 실험-OpenAI는 2025년에 공격적인 실험을 진행했습니다: Codex를 사용하여 빈 git 저장소에서 완전한 내부 제품을 구축하는 것. 5개월 후 저장소에는 약 100만 줄의 코드가 생성되었습니다 — 애플리케이션 로직, 인프라, 툴링, 문서, 내부 개발 도구 모두 에이전트가 생성했습니다. 세 명의 엔지니어가 Codex를 운영하며 약 1,500개의 PR을 열고 병합했습니다. 1인당 하루 평균 3.5개의 PR.+OpenAI는 2025년에 공격적인 실험을 진행했습니다: Codex를 사용하여 빈 git 저장소에서 완전한 내부 제품을 구축하는 것. 5개월 후 저장소에는 약 100만 줄의 코드가 생성되었습니다 — 애플리케이션 로직, 인프라, 툴링, 문서, 내부 개발 도구 모두 에이전트가 생성했습니다. 세 명의 엔지니어가 Codex를 운영하며 약 1,500개의 PR을 열고 병합했습니다. 1인당 하루 평균 3.5개의 PR. [OpenAI](https://openai.com/index/harness-engineering/)-핵심 제약: **인간은 코드를 직접 작성하지 않습니다.** 이것은 단순한 실험적 설정이 아니었습니다 — 엔지니어의 주요 업무가 더 이상 코드 작성이 아니라 환경 설계, 의도 표현, 피드백 루프 구축이 될 때 무엇이 달라지는지 파악하도록 강제하기 위한 설계였습니다.+실제 개발 성과는 단일 원인의 효과를 분리하지 않습니다. 벤치마크 값은 명시된 모델, scaffold, 데이터와 평가 조건에 적용됩니다.초기 진행은 예상보다 느렸습니다. Codex의 역량이 부족해서가 아니라 환경이 아직 충분히 갖춰지지 않았기 때문입니다 — 에이전트에게 고수준 목표를 진전시키는 데 필요한 도구, 추상화, 내부 구조가 부족했습니다. 엔지니어들의 작업은 이렇게 바뀌었습니다: 큰 목표를 작은 구성 요소(설계, 코드, 리뷰, 테스트)로 분해하고, 에이전트가 조합하도록 한 다음, 그 구성 요소들을 활용하여 더 복잡한 작업을 가능하게 하는 것. 무언가 실패했을 때 해결책은 거의 "더 열심히 해봐"가 아니었습니다 — "에이전트에게 어떤 역량이 부족하고, 어떻게 하면 이해 가능하고 실행 가능하게 만들 수 있는가?"였습니다.-이 실험은 이 강의의 핵심 테제를 직접 증명합니다: **동일한 모델이 맨손 환경과 완전한 하네스 환경에서 근본적으로 다른 산출물을 만들어냅니다.** 모델은 변하지 않았습니다. 환경이 변했습니다.+실제 개발 성과는 단일 원인의 효과를 분리하지 않습니다. 벤치마크 값은 명시된 모델, scaffold, 데이터와 평가 조건에 적용됩니다.> 출처: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)-## 현실적인 예시+## 교육용 예시++> 교육용 예시: 이 상황과 수치는 설명을 위한 가정이며 공개 실험의 측정 결과가 아닙니다.한 팀이 중간 규모의 Python 웹 앱(FastAPI + PostgreSQL + Redis, 약 15,000줄)에 새 API 엔드포인트를 추가하기 위해 Claude Sonnet을 사용했습니다.@@ -112,6 +127,8 @@ OpenAI는 2025년에 공격적인 실험을 진행했습니다: Codex를 사용- [SWE-bench Leaderboard](https://www.swebench.com/)- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)+- [Anthropic: Sonnet 4.5 SWE-bench methodology, 2025-09-29](https://www.anthropic.com/news/claude-sonnet-4-5)+## 연습 문제1. **비교 실험**: 잘 아는 코드베이스와 비사소한 수정 작업을 선택하십시오. 먼저 하네스 지원 없이 에이전트를 실행하고 실패를 기록하십시오. 그런 다음 명시적 검증 명령어가 포함된 AGENTS.md를 추가하고 같은 에이전트로 다시 실행하십시오. 결과를 비교하고, 각 실패를 다섯 가지 방어 레이어 중 하나에 귀속시키십시오.diff --git a/docs/ko/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/ko/lectures/lecture-02-what-a-harness-actually-is/index.mdindex 0350e59..f1e1c88 100644--- a/docs/ko/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/ko/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -70,7 +70,9 @@ flowchart LR**하네스 컴포넌트 가치 정량화**: 같은 모델을 고정한 컴포넌트 제거 실험을 사용하십시오. 모델을 고정하고 하위 시스템을 하나씩 제거하면서 어떤 제거가 가장 큰 성능 저하를 유발하는지 측정하십시오. 가장 큰 하락은 해당 작업에서 한계 기여도가 가장 큰 컴포넌트를 보여주지만, 자동으로 병목을 식별하지는 않습니다. 하락이 거의 없는 경우도 해석이 필요합니다. 해당 컴포넌트가 중복이거나, 설계가 약하거나, 그 작업에서 충분히 사용되지 않았을 수 있습니다. 병목을 진단하려면 먼저 실패 기록과 귀인을 사용하고, 제거 실험은 보조 증거로 다루십시오. 실패 원인이 불명확한 작업 의도, 부족한 컨텍스트, 재현 불가능한 환경, 검증 피드백 부재, 끊긴 상태 관리 중 무엇인지 확인해야 합니다.-## 한 팀의 실제 이야기+## 교육용 예시++> 교육용 예시: 이 상황과 수치는 설명을 위한 가정이며 공개 실험의 측정 결과가 아닙니다.한 팀이 TypeScript + React 프론트엔드 앱(약 20,000줄)에 GPT-4o를 사용했습니다. 필수적으로 주방 장비를 하나씩 추가하는 4단계를 거쳤습니다:diff --git a/docs/ko/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/ko/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdindex 485cd42..0dac010 100644--- a/docs/ko/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md+++ b/docs/ko/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -5,6 +5,8 @@# 강의 03. 저장소를 단일 진실 원천으로 만들어라+> 설계 지침: 수치 기준은 조정 가능한 교육용 기본값이며 검증된 임계값이 아닙니다. token 수는 줄 수뿐 아니라 tokenizer와 내용에 따라 달라집니다.+팀의 아키텍처 결정이 Confluence, Slack, Jira, 그리고 몇몇 시니어 엔지니어의 머릿속에 흩어져 있습니다. 사람에게는 이것이 겨우 통합니다 — 동료에게 물어보고, 채팅 기록을 검색하고, 문서를 뒤지면 됩니다. 도저히 안 되면 휴게실에서 누군가를 붙잡을 수도 있습니다. 하지만 AI 에이전트(agent)에게는, 저장소(repository)에 없는 정보는 단순히 존재하지 않습니다.이것은 과장이 아닙니다. 에이전트의 입력이 실제로 무엇인지 생각해보십시오: 시스템 프롬프트와 작업 설명, 저장소의 파일 내용, 그리고 도구 실행 결과. 그뿐입니다. 슬랙 기록, Jira 티켓, Confluence 페이지, 금요일 오후 동료와 커피 한 잔 하며 나눈 아키텍처 결정 — 에이전트는 이 중 어느 것도 볼 수 없습니다. "누군가에게 물어보거나" "채팅 기록을 검색"할 수 없습니다. 저장소 안에 갇힌 엔지니어입니다 — 외부에 있는 것은 아무것도 모릅니다.diff --git a/docs/ko/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/ko/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdindex b9f19cb..50694d7 100644--- a/docs/ko/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md+++ b/docs/ko/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -5,6 +5,8 @@# 강의 04. 명령 파일을 여러 파일로 분산하라+> 설계 지침: 수치 기준은 조정 가능한 교육용 기본값이며 검증된 임계값이 아닙니다. token 수는 줄 수뿐 아니라 tokenizer와 내용에 따라 달라집니다.+하네스 엔지니어링(harness engineering)에 진지하게 임하기 시작했습니다. `AGENTS.md`를 만들고, 떠오르는 모든 규칙과 제약과 교훈을 그 안에 빼곡히 담았습니다. 한 달이 지나자 파일이 300줄로 불었고, 두 달 뒤엔 450줄, 세 달 뒤엔 600줄이 됐습니다. 그런데 에이전트(agent) 성능이 오히려 나빠지고 있다는 것을 알게 됩니다. 간단한 버그 수정을 할 때도 에이전트가 불필요한 배포 명령을 처리하느라 컨텍스트(context)를 낭비하고, 300번째 줄에 묻혀 있는 중요한 보안 제약은 완전히 무시되며, 서로 모순된 코드 스타일 규칙 세 개를 매번 임의로 골라 따릅니다.이것이 "거대한 명령 파일" 함정입니다. 여행 가방을 과도하게 채우는 것과 같습니다. 모든 물건이 필요해 보여서 계속 욱여넣다 보면 지퍼가 터질 지경이 됩니다. 속옷 한 장을 찾으려면 가방 전체를 비워야 합니다. 가득 찬 가방을 들고 다니지만, 실제로 꺼내 쓰는 물건은 그 중 3분의 1도 안 됩니다.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.mdindex 3a49036..83750b6 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@@ -5,6 +5,8 @@# 강의 05. 세션을 넘어 컨텍스트를 살아있게 유지하라+> 설계 지침: 수치 기준은 조정 가능한 교육용 기본값이며 검증된 임계값이 아닙니다. token 수는 줄 수뿐 아니라 tokenizer와 내용에 따라 달라집니다.+Claude Code에게 완전한 기능을 구현하도록 요청합니다. 30분 동안 실행되며 대부분의 작업을 완료하지만 컨텍스트(context)가 거의 소진됩니다. 계속하기 위해 새 세션을 시작하면, 지난번에 어떤 결정이 내려졌는지, 왜 옵션 A가 아닌 옵션 B가 선택됐는지, 어떤 파일이 이미 수정됐는지, 테스트 상태가 어떤지를 기억하지 못한다는 것을 발견합니다. 프로젝트를 재탐색하는 데 15분을 쓰고, 이전 접근법과 일관성이 없을 수도 있습니다.매일 아침 일어나면 모든 것을 잊어버리는 장인을 상상해 보세요. 건설 현장 전체를 다시 파악해야 합니다. 어떤 벽이 반쯤 지어졌는지, 왜 파란 벽돌이 아닌 빨간 벽돌을 선택했는지, 배관 공사가 어디까지 진행됐는지를요. 더 나쁜 경우, 어제 이미 설치된 창문을 그것이 완료됐다는 것을 기억하지 못해서 뜯어낼 수도 있습니다.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.mdindex f914785..6b8307b 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@@ -5,6 +5,8 @@# 강의 06. 모든 에이전트 세션 전에 초기화하라+> 설계 지침: 수치 기준은 조정 가능한 교육용 기본값이며 검증된 임계값이 아닙니다. token 수는 줄 수뿐 아니라 tokenizer와 내용에 따라 달라집니다.+새 에이전트(agent) 세션을 시작하고 "검색 기능을 추가해줘"라고 말합니다. 에이전트가 바로 코딩에 뛰어듭니다. 훌륭한 열정입니다. 20분 후 테스트 프레임워크가 제대로 설정되지 않았다는 것을 발견하고, 그것을 수정하는 데 10분을 더 씁니다. 그러다 데이터베이스 마이그레이션 스크립트 형식이 잘못됐다는 것을 알게 되어 또 수정합니다. 검색 기능은 결국 추가되지만, 전체 세션이 비효율적이었습니다. 대부분의 시간이 검색 기능을 작성하는 것이 아닌 "이 프로젝트가 어떻게 작동하는지 파악하기"에 사용됐습니다.더 나은 접근법은 이렇습니다. 에이전트가 작업을 시작하기 전에, 별도의 단계를 사용해 기본 환경을 준비하고, 검증 명령이 통과하도록 하고, 프로젝트 구조를 이해합니다. 집을 짓는 것과 같습니다. 기초를 붓고 동시에 벽을 세우지 않습니다. 그렇게 하면 기초가 굳기 전에 벽이 올라가고, 건물 전체를 허물고 다시 시작해야 합니다. 먼저 기초를 붓고, 굳힌 다음, 벽을 세웁니다. 깔끔하고 효율적입니다.@@ -37,6 +39,8 @@ flowchart TB## 혼합했을 때 어떤 일이 벌어지나+> 교육용 예시: 이 상황과 수치는 설명을 위한 가정이며 공개 실험의 측정 결과가 아닙니다.+가장 직접적인 문제: 기초가 제대로 굳지 않습니다. 에이전트가 기능 코드에 80%의 노력을 쓰고 인프라 설정에 20%만 임시로 씁니다. 테스트 프레임워크가 설정됐지만 검증되지 않았고, 린트 규칙이 설정됐지만 너무 느슨하고, 진행 파일이 만들어지지 않았습니다. 이 결함은 첫 번째 세션에서 명확하지 않습니다(에이전트가 무엇을 했는지 여전히 기억하기 때문에). 하지만 두 번째 세션에서 표면화됩니다. 새 에이전트는 실행 방법, 테스트 방법, 상황이 어떤지를 알지 못합니다. 기초가 부실하면 건물이 흔들립니다.더 숨겨진 비용은 "미검증 누적"입니다. 테스트 프레임워크가 설정되기 전에 작성된 기능 코드는 검증 없는 코드입니다. 마침내 그 코드에 테스트를 추가하러 돌아갈 때, 처음부터 설계가 잘못됐다는 것을 발견할 수도 있습니다. 알았더라면 다르게 구현했을 것입니다. 젖은 콘크리트 위에 타일을 붙이는 것과 같습니다. 바닥이 평평하지 않다는 것을 발견하면 모든 타일을 들어내고 다시 해야 합니다.@@ -45,7 +49,7 @@ flowchart TB가장 쉽게 간과하는 문제는 암묵적 가정의 지뢰밭입니다. 에이전트가 초기화 중에 내리는 결정들(어떤 테스트 프레임워크, 디렉터리 구성 방식, 의존성 관리)이 명시적으로 기록되지 않으면 이후 세션이 이러한 선택을 이해할 수 없습니다. 더 나쁜 경우, 이후 세션이 상충되는 선택을 할 수도 있습니다. 첫 번째 건설 팀이 콘크리트 기초를 사용했는데 두 번째 팀은 그것을 모르고 그 위에 나무 말뚝을 박습니다. 기초가 갈라집니다.-Anthropic의 장기 실행 애플리케이션 개발 연구는 초기화와 구현을 분리할 것을 명시적으로 권장합니다. 그들의 실험 데이터: 전용 초기화 단계를 사용한 프로젝트는 멀티 세션 시나리오에서 혼합 접근법 대비 기능 완료율이 31% 높았습니다. 핵심 통찰은 초기화 단계에 투자한 시간이 이후 3~4세션에서 완전히 회수된다는 것입니다. 기초가 견고할수록 벽이 더 빨리 올라갑니다.+[Anthropic: initializer / coding agent](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)OpenAI의 Codex 하네스 엔지니어링 가이드도 "저장소(repository)를 운영 기록으로" 원칙을 강조합니다. 첫 번째 실행에서 명확한 운영 구조를 확립하거나, 모든 새 세션이 프로젝트 컨벤션을 다시 추론해야 합니다.@@ -122,7 +126,9 @@ OpenAI의 Codex 하네스 엔지니어링 가이드도 "저장소(repository)를- [ ] 모든 것이 git에 커밋됨```-## 실제 사례+## 교육용 예시++> 교육용 예시: 이 상황과 수치는 설명을 위한 가정이며 공개 실험의 측정 결과가 아닙니다.React 프론트엔드 프로젝트에 대한 두 가지 초기화 접근법: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.mdindex ce138f3..cbd131d 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@@ -5,6 +5,8 @@# 강의 07. 에이전트에게 명확한 작업 경계를 그어 주어야 합니다+> 설계 지침: 수치 기준은 조정 가능한 교육용 기본값이며 검증된 임계값이 아닙니다. token 수는 줄 수뿐 아니라 tokenizer와 내용에 따라 달라집니다.+Claude Code에게 "이 프로젝트에 사용자 인증을 추가해 줘"라고 지시하면, 에이전트(agent)는 데이터베이스 스키마를 수정하고, 라우트를 작성하고, 프론트엔드 컴포넌트를 변경하고 — 그 김에 오류 처리 미들웨어까지 리팩터링하기 시작합니다. 두 시간 후 확인해 보면: 수정된 파일 12개, 새로운 코드 800줄, 그리고 단 하나의 기능도 엔드투엔드로 동작하지 않습니다."한 번에 너무 많이 베어 물다" — 이 표현은 AI 에이전트에게 특히 잘 들어맞습니다. 에이전트는 "조금 더 해두자"는 충동을 타고납니다. 관련된 것들을 보면 그냥 처리해 버립니다. 마치 간장 한 병 사러 마트에 갔다가 카트 가득 채워 나오는 사람처럼요. 문제는, 사람이 너무 많이 사면 돈만 낭비하지만, 에이전트가 너무 많은 것을 동시에 하면 어느 것 하나도 제대로 마무리되지 않는다는 점입니다.@@ -26,7 +28,7 @@ Claude Code의 실제 동작이 이를 잘 보여줍니다. "사용자 등록여섯 단계 후, 하나도 완성되지 않았습니다. 엔드투엔드 검증(verification)은 없고, 미완성 코드 간의 복잡한 결합만 남으며, 다음에 이어받을 세션은 완전히 길을 잃습니다. 마치 여섯 가지 요리를 동시에 하는 사람처럼 — 모든 요리가 냄비 안에 있지만 접시에 담긴 것은 하나도 없습니다. 다 타버립니다.-Anthropic의 실험 데이터가 이를 직접 뒷받침합니다: "작은 다음 단계" 전략(WIP=1에 해당)을 사용한 에이전트는 넓은 프롬프트를 사용한 에이전트보다 작업 완료율이 37% 높습니다. 더 흥미로운 점은, 에이전트가 생성한 코드 줄 수와 실제 기능 완료 수가 약한 음의 상관관계를 보인다는 것입니다 — 코드를 많이 작성할수록 완성된 기능은 적습니다. 데이터로 증명된 과욕(overreach)입니다.+[Anthropic: incremental feature work](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## WIP=1 워크플로우@@ -100,7 +102,9 @@ F01: 사용자 등록하네스는 VCR(Verified Completion Rate) = 검증된 작업 / 활성화된 작업을 지속적으로 추적해야 합니다. VCR < 1.0일 때 새 작업 활성화를 차단합니다.-## 실제 사례+## 교육용 예시++> 교육용 예시: 이 상황과 수치는 설명을 위한 가정이며 공개 실험의 측정 결과가 아닙니다.8개의 기능을 가진 REST API 프로젝트, 두 가지 전략 비교: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.mdindex 225e62b..e34f41e 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@@ -5,6 +5,8 @@# 강의 08. 기능 목록으로 에이전트의 행동을 제약하십시오+> 설계 지침: 수치 기준은 조정 가능한 교육용 기본값이며 검증된 임계값이 아닙니다. token 수는 줄 수뿐 아니라 tokenizer와 내용에 따라 달라집니다.+에이전트에게 전자상거래 사이트를 구축하라고 요청합니다. 완성 후 에이전트는 "완료"라고 말합니다. 코드를 살펴보니 — 사용자 인증은 작동하지만 장바구니의 결제 버튼은 아무것도 하지 않고, 결제 흐름은 전혀 연결되어 있지 않습니다. 문제는: "완료"가 무엇을 의미하는지 전혀 알려주지 않았기 때문에, 에이전트는 자신만의 기준을 사용했습니다 — "코드를 많이 작성했고 꽤 완성된 것처럼 보인다."기능 목록(feature list)은 많은 사람들의 눈에 그저 메모처럼 보입니다 — 잊지 않으려고 적어두고 나서 옆으로 치워두는 것. 하지만 하네스(harness) 세계에서 기능 목록은 인간을 위한 메모가 아닙니다 — 전체 하네스의 근간(backbone)입니다. 스케줄러(scheduler)는 이것을 바탕으로 작업을 선택하고, 검증기(verifier)는 이것을 바탕으로 완료를 판단하며, 핸드오프(handoff) 보고기는 이것을 바탕으로 요약본을 생성합니다. 근간이 부러지면 온 몸이 마비됩니다.@@ -22,7 +24,7 @@ Claude Code도 Codex도 "완료"가 무엇을 의미하는지 자동으로 알```새로운 에이전트 세션이 이 메모에서 다음 질문들에 답할 수 있을까요? "거의 완료"가 무엇을 의미하는지? 장바구니가 통과한 테스트는 무엇인지? 결제를 막는 것이 무엇인지? 모든 답은 "아무도 모른다"입니다. 의사에게 "배가 아픈데, 요즘엔 괜찮아요"라고 하는 것과 같습니다 — 어떤 약을 처방할 수 있을까요?-결과: 새 세션이 프로젝트 상태를 추론하는 데 20분을 소비하고, 이미 완료된 기능을 재구현할 수도 있습니다. Anthropic의 엔지니어링 데이터에 따르면 좋은 진행 기록은 세션 시작 진단 시간을 60-80% 줄입니다.+진행과 검증 결과를 버전 관리 파일에 기록해 다음 세션이 상태를 확인하게 합니다. 출처는 이 메커니즘을 설명하며 시작 시간 감소율을 보고하지 않습니다. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## 기능 상태 기계@@ -103,7 +105,9 @@ flowchart LR각 기능 항목은 "하나의 세션 내에서 완료 가능"한 범위여야 합니다. 너무 넓으면 완료되지 않고, 너무 좁으면 관리 오버헤드가 늘어납니다. "사용자가 장바구니에 항목을 추가할 수 있다"는 적절한 세분화입니다. "장바구니 구현"은 너무 넓습니다. "Cart 모델에 name 필드 생성"은 너무 좁습니다. 스테이크 자르는 것처럼 — 통째로도 아니고, 간 고기도 아닌 적절한 한 입 크기.-## 실제 사례+## 교육용 예시++> 교육용 예시: 이 상황과 수치는 설명을 위한 가정이며 공개 실험의 측정 결과가 아닙니다.10개의 기능을 가진 전자상거래 플랫폼. 두 가지 추적 방법 비교:@@ -111,8 +115,6 @@ 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.mdindex e611693..714d674 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@@ -5,6 +5,8 @@# 강의 9. 에이전트가 너무 일찍 완료를 선언하지 못하도록 방지하기+> 설계 지침: 수치 기준은 조정 가능한 교육용 기본값이며 검증된 임계값이 아닙니다. token 수는 줄 수뿐 아니라 tokenizer와 내용에 따라 달라집니다.+에이전트에게 "비밀번호 재설정" 기능을 구현하라고 요청합니다. 에이전트는 데이터베이스 스키마를 수정하고, API 엔드포인트를 작성하고, 이메일 템플릿을 추가하고, 단위 테스트를 실행합니다(모두 통과). 그런 다음 자신 있게 "완료되었습니다"라고 알립니다. 실제로 실행해 보면 — 비밀번호 재설정 링크를 보낼 수 없고(이메일 서비스 설정 누락), 데이터베이스 마이그레이션이 중간에 실패하며(스키마 불일치), 엔드투엔드 흐름은 단 한 번도 실행되지 않았습니다.이 느낌이 낯설지 않을 것입니다 — 시험지를 가득 채우고 자신 있게 가장 먼저 제출했는데, 성적이 나왔을 때 낙제하는 경우와 같습니다. 시험지가 가득 찼다고 해서 답이 맞는 것은 아닙니다.@@ -13,6 +15,8 @@## 미끄러운 경사면+> 모델과 프롬프트는 같지만 시간과 비용 예산이 다릅니다. 동일 예산에서 구성 요소 하나를 분리한 실험이 아닙니다. 핵심 게임 기능은 작동했으나 결함이 남았습니다. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)+조기 완료 선언은 거의 항상 같은 패턴을 따릅니다: 코드가 괜찮아 보입니다 — 문법이 올바르고, 로직이 합리적으로 보이며, 정적 분석에서 명백한 오류가 없습니다. 하지만 하네스가 포괄적인 실행 검증을 강제하지 않기 때문에, 에이전트는 실제 실행을 건너뛰거나 부분적인 테스트만 수행합니다. 단위 테스트는 실행하지만 통합 테스트는 건너뜁니다. 테스트는 실행하지만 커버리지를 확인하지 않습니다. 결국 "코드가 멀쩡해 보인다"가 "기능이 완료되었다"의 증거로 사용됩니다. 그리고 시험지가 제출됩니다.정보는 모든 단계에서 손실됩니다. 작업 명세에서 코드 구현을 거쳐 런타임 동작에 이르기까지, 모든 변환은 편향을 유발할 수 있으며, 건너뛴 모든 검증은 정보 비대칭을 악화시킵니다.@@ -111,7 +115,9 @@ OpenAI는 Codex 실천 과정에서 특히 효과적인 패턴을 소개했습- 데이터베이스 쓰기, 파일 작업 및 기타 부작용이 올바른가?- 임시 리소스가 정리되었는가?-## 실제 사례+## 교육용 예시++> 교육용 예시: 이 상황과 수치는 설명을 위한 가정이며 공개 실험의 측정 결과가 아닙니다.**작업**: 사용자 비밀번호 재설정 기능 구현. 데이터베이스 작업, 이메일 전송, API 엔드포인트 수정이 포함됩니다.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.mdindex 4472b4f..9c095ec 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@@ -5,6 +5,8 @@# 강의 10. 엔드투엔드 테스트(end-to-end testing)만이 진정한 검증이다+> 설계 지침: 수치 기준은 조정 가능한 교육용 기본값이며 검증된 임계값이 아닙니다. token 수는 줄 수뿐 아니라 tokenizer와 내용에 따라 달라집니다.+에이전트에게 Electron 앱에 파일 내보내기 기능을 추가해 달라고 합니다. 에이전트는 렌더 프로세스 컴포넌트, 프리로드 스크립트, 서비스 계층 로직을 작성합니다. 각 컴포넌트에 대한 단위 테스트(unit test)는 완벽하게 통과합니다. 에이전트는 "완료됐습니다"라고 말합니다. 실제로 내보내기 버튼을 클릭하면—파일 경로 형식이 잘못되어 있고, 진행 표시줄이 업데이트되지 않으며, 대용량 파일 내보내기 시 메모리 누수가 발생합니다. 다섯 개의 컴포넌트 경계 결함이 있었는데, 단위 테스트는 하나도 잡아내지 못한 것입니다.마치 합창 리허설에서 각 성부가 개별적으로 연습할 때는 완벽하게 들리지만, 함께 노래하면 소프라노가 베이스보다 반 박자 빠르고, 반주는 주 선율보다 반음 낮은 것과 같습니다. 각 파트는 개별적으로는 "정확"하지만, 전체적으로는 엇나갑니다.@@ -116,7 +118,9 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.rea코드 리뷰 중에 새로운 유형의 에이전트 오류가 발견될 때마다, 자동화된 검사로 전환하세요. 한 달 후에는 하네스가 한 달 전보다 크게 강화되어 있을 것입니다. 합창의 리허설 노트처럼—매 리허설에서 발견된 문제를 기록해두면, 다음 리허설 전에 확인할 수 있습니다. 시간이 지날수록 흔한 오류는 줄어들고, 음악은 더 조화로워집니다.-## 실제 사례+## 교육용 예시++> 교육용 예시: 이 상황과 수치는 설명을 위한 가정이며 공개 실험의 측정 결과가 아닙니다.**작업**: Electron 앱에 파일 내보내기 기능 구현. 렌더 프로세스 UI, 프리로드 스크립트 파일시스템 프록시, 서비스 계층 데이터 변환이 포함됩니다.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.mdindex d1d718a..a981018 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@@ -32,7 +32,9 @@ flowchart LRVerdict --> Generator```-## 왜 이런 일이 발생하는가+## 교육용 예시++> 교육용 예시: 이 상황과 수치는 설명을 위한 가정이며 공개 실험의 측정 결과가 아닙니다.### 관측 가능성 부재의 실제 비용@@ -44,7 +46,7 @@ flowchart LR**재시도가 맹목적인 추측이 된다**: 에이전트가 왜 실패했는지 모르면, 재시도 방향이 무작위입니다. 실제 실패 근본 원인을 무시하고 관련 없는 코드 경로를 고치면서 잘못된 방향으로 반복적으로 시도할 수 있습니다. 모든 맹목적 재시도는 토큰과 시간을 소비합니다.-**세션 핸드오프(handoff) 정보 절벽**: 완료되지 않은 작업이 다음 세션으로 인계될 때, 관측 가능성 부재는 새 세션이 시스템 상태를 처음부터 진단해야 함을 의미합니다. Anthropic의 장시간 실행 에이전트 관찰에 따르면 이러한 중복 진단이 총 세션 시간의 30-50%를 소비할 수 있습니다.+진행과 검증 결과를 버전 관리 파일에 기록해 다음 세션이 상태를 확인하게 합니다. 출처는 이 메커니즘을 설명하며 시작 시간 감소율을 보고하지 않습니다. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)### 실제 Claude Code 시나리오@@ -116,7 +118,9 @@ flowchart LR각 하네스 세션에 대한 트레이스(trace)를, 각 작업에 대한 스팬(span)을, 각 검증 단계에 대한 하위 스팬을 생성하세요. 표준 속성을 사용해 주요 정보에 주석을 달 수 있습니다. 이렇게 하면 관측 가능성 데이터가 표준 툴체인(Jaeger, Zipkin)과 통합됩니다.-## 실제 사례+## 교육용 예시++> 교육용 예시: 이 상황과 수치는 설명을 위한 가정이며 공개 실험의 측정 결과가 아닙니다.계획자-생성자-평가자 워크플로를 사용하는 하네스가 "다크 모드 지원 추가"를 실행합니다.@@ -136,7 +140,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.mdindex ae45c83..c5aaf71 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@@ -5,6 +5,8 @@# 강의 12. 모든 세션은 클린 상태(clean state)로 끝나야 한다+> 설계 지침: 수치 기준은 조정 가능한 교육용 기본값이며 검증된 임계값이 아닙니다. token 수는 줄 수뿐 아니라 tokenizer와 내용에 따라 달라집니다.+## 이 강의가 해결하는 문제에이전트가 오후 내내 실행되고, 20개의 파일을 수정하고, 코드를 커밋하고, 세션이 종료됩니다. 다음 에이전트 세션이 시작되고 즉시 발견합니다. 빌드가 깨져 있고, 테스트는 빨간 상태이며, 임시 디버그 파일이 곳곳에 있고, 기능 목록은 업데이트되지 않았으며, 진행 상황이 전혀 불분명합니다. 새 세션은 "지난 세션이 실제로 무엇을 했는가"를 파악하는 데 첫 30분을 씁니다.@@ -54,6 +56,8 @@ flowchart LR소프트웨어 진화의 Lehman 법칙에 따르면 지속적으로 변경되는 시스템은 능동적으로 관리되지 않으면 복잡성이 불가피하게 증가합니다. 이것은 AI 코딩 에이전트에게 특히 사실입니다—매 세션마다 변경 사항을 도입하고, 종료 시 정리하지 않으면 기술 부채가 기하급수적으로 쌓입니다.+> 교육용 예시: 이 상황과 수치는 설명을 위한 가정이며 공개 실험의 측정 결과가 아닙니다.+실제 데이터가 이를 말해줍니다. 정리 전략 없이 12주간 에이전트로 개발된 프로젝트:- 1주차: 빌드 통과율 100%, 테스트 통과율 100%, 새 세션 시작 5분@@ -66,8 +70,6 @@ flowchart LR- 1주차: 100%, 100%, 5분- 12주차: 97%, 95%, 9분-12주 후: 빌드 통과율 29퍼센트포인트 차이, 새 세션 시작 시간 85% 차이. 이것은 이론이 아닙니다—관찰된 차이입니다.-### 클린 상태의 다섯 가지 차원클린 상태는 단순히 "코드가 컴파일된다"는 것이 아닙니다. 함께 평가되는 다섯 가지 차원입니다.@@ -76,7 +78,7 @@ flowchart LR**테스트 차원**: 모든 테스트가 통과하는가? 세션 전에 존재했던 테스트도 포함해서입니다—세션은 기존 기능을 깨뜨리지 않을 책임이 있습니다. 그리고 "내 기계에서는 작동해"가 아니라 CI에서 검증되어야 합니다.-**진행 상황 차원**: 현재 진행 상황이 기계가 읽을 수 있는 산출물에 기록되어 있는가? 통과 기준이 있는 완료된 하위 작업, 현재 상태가 있는 진행 중이지만 완료되지 않은 하위 작업, 아직 시작되지 않은 하위 작업. 좋은 진행 상황 기록은 세션 시작 진단 시간의 60-80%를 줄입니다.+진행과 검증 결과를 버전 관리 파일에 기록해 다음 세션이 상태를 확인하게 합니다. 출처는 이 메커니즘을 설명하며 시작 시간 감소율을 보고하지 않습니다. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)**산출물 차원**: 오래되거나 모호한 임시 산출물이 있는가? 디버그 로그, 임시 파일, 주석 처리된 코드, TODO 마커—이 모두가 다음 세션의 인지 부하를 높입니다.@@ -152,7 +154,9 @@ git checkout -- .env.local # 알려진 상태로 복원npm run test # 정리가 아무것도 깨뜨리지 않았는지 확인```-## 실제 사례+## 교육용 예시++> 교육용 예시: 이 상황과 수치는 설명을 위한 가정이며 공개 실험의 측정 결과가 아닙니다.12주 동안 에이전트로 개발된 Electron 앱으로 두 가지 접근 방식을 비교합니다.@@ -160,8 +164,6 @@ npm run test # 정리가 아무것도 깨뜨리지 않았는지 확인**정리 전략으로** (실험군): 모든 세션 종료 시 완전한 클린 상태 검사 + 주간 클린업 루프. 12주차, 빌드 통과율 97%, 테스트 통과율 95%, 새 세션 시작 9분, 오래된 산출물 11개.-12주차에 실험군의 빌드 통과율은 29퍼센트포인트 높고, 테스트 통과율은 34포인트 높으며, 새 세션 시작 시간은 85% 낮습니다.-## 핵심 정리- **클린 상태는 세션 완료의 필요 조건입니다**—선택적 정리 작업이 아니라, "완료의 정의"의 일부입니다.diff --git a/docs/ko/lectures/lecture-13-loop-engineering/index.md b/docs/ko/lectures/lecture-13-loop-engineering/index.mdindex 2be56d7..f9a06d8 100644--- a/docs/ko/lectures/lecture-13-loop-engineering/index.md+++ b/docs/ko/lectures/lecture-13-loop-engineering/index.md@@ -5,6 +5,8 @@# 13강. 수동 프롬프팅에서 자율 루프로+> 설계 지침: 수치 기준은 조정 가능한 교육용 기본값이며 검증된 임계값이 아닙니다. token 수는 줄 수뿐 아니라 tokenizer와 내용에 따라 달라집니다.+지난 12개 강의에서 배운 모든 것은 하나의 가정에 기반합니다: **여러분이 키보드 앞에 앉아 한 번에 하나씩 지시를 입력한다는 것.**`AGENTS.md`를 작성했고(1-4강), 상태 관리를 구축했으며(5-6강), 기능 목록으로 범위를 제한했고(7-8강), 세션 종료 시 깔끔한 인계를 남겼으며(9, 12강), 런타임을 관찰 가능하게 만들었습니다(10-11강). 하지만 이 모든 것의 트리거는 항상 여러분이었습니다. 에이전트는 스스로 언제 작업을 시작할지 결정하지 않았습니다 — 누군가 "시작" 버튼을 누르지 않았기 때문입니다.@@ -96,7 +98,13 @@> **루프 엔지니어링은 에이전트에게 프롬프트하는 사람으로서의 자신을 대체하는 것입니다. 대신 그 일을 하는 시스템을 설계하는 것입니다.**-Cherny는 수치를 공개했습니다: 연속 30일 이상, Claude Code에 대한 모든 코드 기여는 AI가 자율적으로 수행했습니다 — 259개의 병합된 PR, 프로덕션 코드의 80% 이상이 Claude가 작성했으며, 개방형 소프트웨어 작업에서 76%의 성공률을 보였습니다.+Boris Cherny · 2025-12-27++| PR | Git commits | + LoC | − LoC | Model |+| --- | --- | --- | --- | --- |+| 259 / 30 days | 497 | 40,000 | 38,000 | Claude Code + Opus 4.5 |++저자가 보고한 개인 개발 실적이며 벤치마크 성공률이나 인간 감독 부재의 증거는 아닙니다. [Boris Cherny](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)세 사람. 한 주. 같은 결론. 조율해서가 아니라 — 인프라가 조용히 임계점을 넘었기 때문입니다. 에이전트는 감독 없이도 사소하지 않은 작업을 완료할 만큼 충분히 신뢰할 수 있게 되었습니다. 스케줄링 프리미티브(`/loop`, `/goal`, cron)가 이제 도구에 내장되었습니다. 단일 에이전트 실행 비용은 타이머로 반복해서 실행하는 것이 낭비로 보이지 않을 만큼 충분히 낮아졌습니다. 모든 부품이 갖춰지면, 그것들을 결합하는 움직임은 모두에게 동시에 당연해집니다.@@ -267,7 +275,7 @@ flowchart TD이것은 더 이상 단일 에이전트 실행이 아닙니다. 매일 아침 깨어나서 스스로 정리하고 여러분의 주의가 필요한 것들을 앞에 내놓는, 지속적으로 작동하는 시스템입니다. 여러분의 역할은 다음과 같습니다: **받은 편지함 내용을 검토하고, 결정을 내리고, 시스템이 처리할 수 없는 패턴을 발견하면 스킬과 규칙을 개선하는 것.**-Cherny는 이 패턴을 사용하여 IDE를 한 번도 열지 않고 30일 만에 259개의 PR을 병합했습니다. OpenAI 엔지니어들은 같은 패턴을 사용하여 대략 백만 줄 규모의 베타 제품을 손으로 — 직접 코드를 한 줄도 쓰지 않고 구축했습니다.+저자가 보고한 개인 개발 실적이며 벤치마크 성공률이나 인간 감독 부재의 증거는 아닙니다.## 생성자/평가자 분리: 왜 모델이 자신의 작업을 채점하게 하면 안 되는가@@ -293,7 +301,7 @@ Cherny는 이 패턴을 사용하여 IDE를 한 번도 열지 않고 30일 만잘 설계되고 실제로 돌아가는 루프가 어떤 모습인지 보고 싶다면, [Karpathy의 autoresearch](https://github.com/karpathy/autoresearch)가 교과서적인 예시입니다.-2026년 3월, Karpathy는 630줄짜리 Python 프로젝트를 공개했습니다. GPU 하나와 연구 방향만 주면 밤새도록 실행됩니다 — 수백 개의 ML 훈련 실험을 완료하고, 진정으로 개선된 것만 남깁니다. 이 프로젝트는 공개된 지 며칠 만에 66,000개 이상의 스타를 받았습니다.+[Karpathy: autoresearch](https://github.com/karpathy/autoresearch) · [announcement](https://x.com/karpathy/status/2030371219518931079)### 세 개의 파일, 세 가지 역할@@ -343,8 +351,6 @@ flowchart TD8b --> 9```-대략 시간당 12개의 실험을 실행합니다. 밤새 실행(8시간)하면 약 100개의 실험이 됩니다. Karpathy 본인은 2일 동안 실행했습니다 — 약 700개의 실험.-고정된 5분 실제 시간 예산은 핵심 설계 선택입니다 — 에이전트가 무엇을 바꾸든, 모든 실험은 정확히 같은 시간이 걸립니다. 이것은 모든 결과가 같은 시간 예산 하에서 직접 비교 가능하다는 것을 의미합니다 — "이건 더 오래 돌렸으니 더 좋아" 같은 논쟁이 없습니다.### 출력: 잠에서 깼을 때 보이는 것@@ -359,6 +365,8 @@ flowchart TD단일 실험마다 — 성공이든 실패든 — 기록됩니다:+> 교육용 예시: 이 상황과 수치는 설명을 위한 가정이며 공개 실험의 측정 결과가 아닙니다.+```timestamp commit_hash val_bpb vram_mb description--------- ------------- ---------- ---------- ----------------------------@@ -375,11 +383,8 @@ timestamp commit_hash val_bpb vram_mb description### 실제로 무엇을 발견했는가-Karpathy의 초기 2일, 약 700개 실험 실행 결과:--- 약 700번의 시도 중, **누적 가능한 실제 개선 사항이 약 20개** 발견되었습니다-- nanochat의 GPT-2 수준 훈련 시간을 8×H100에서 **2.02시간 → 1.80시간**으로 단축했으며, 약 **11% 더 빨라졌습니다**-- 발견 사항에는 학습률 조정, 옵티마이저 튜닝, 활성화 함수 교체, 어텐션 패턴 최적화 등이 포함되었습니다+- nanochat의 GPT-2 수준 훈련 시간을 8×H100에서 **2.02시간 → 1.80시간**으로 단축했으며, 약 **10.89% 더 빨라졌습니다**+- 발견 사항에는 학습률 조정, 옵티마이저 튜닝, 활성화 함수 교체, 어텐션 패턴 최적화 등이 포함되었습니다 [Karpathy: leaderboard commit](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b) · [tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)모든 개선 사항이 충격적인 발견이었을까요? 아닙니다. 대부분은 누적되는 작은 최적화였습니다. 하지만 그 20개의 유효한 개선 사항은 인간 연구자가 몇 주 동안 수동으로 작업했을 것입니다 — 에이전트는 48시간 만에 해냈습니다.@@ -399,7 +404,7 @@ Karpathy의 초기 2일, 약 700개 실험 실행 결과:### 2. 이해 부패-루프가 코드를 더 빨리 배포할수록, 여러분의 자신의 코드베이스에 대한 이해는 현실에서 더 멀어집니다. Cherny의 팀은 코드의 80%를 에이전트가 작성했습니다 — 팀 코드의 대부분이 사람이 작성하지 않았다는 의미입니다. 루프가 생산하는 것을 읽고 사용하지 않으면, 여러분의 이해는 지속적으로 쇠퇴합니다. **빠른 루프는 빠른 읽기를 요구합니다.**+실제 개발 성과는 단일 원인의 효과를 분리하지 않습니다. 벤치마크 값은 명시된 모델, scaffold, 데이터와 평가 조건에 적용됩니다.### 3. 인지 항복diff --git a/docs/ko/lectures/lecture-14-graph-engineering/index.md b/docs/ko/lectures/lecture-14-graph-engineering/index.mdindex 86e8882..eec1a5d 100644--- a/docs/ko/lectures/lecture-14-graph-engineering/index.md+++ b/docs/ko/lectures/lecture-14-graph-engineering/index.md@@ -261,7 +261,7 @@ run(graph, entry={"requirements": "로그인 페이지 버그 수정"}, thread="**개념 출시 후에 생긴 것**-- [GraphArc](https://github.com/CodeGraphContext/grapharc)(2026-08-02): 스스로 "Graph Engineering의 첫 번째 실시간 구현"이라고 부릅니다. 에이전트 실행을 로그에 묻혀 있던 trace에서 **상호작용 가능한 실시간 오케스트레이션 그래프**로 바꿉니다 — 각 엔진, 각 의존성, 각 결정 지점을 그려서, 실행 전에 전체 그래프를 시각화하고, 당신이 확인한(심지어 휴대폰으로 볼 수도 있는) 뒤에야 통과시킵니다. 저자는 4,000+ 개발자용 그래프 도구를 만든 배경이며, 방향은 "관측 가능, 디버그 가능, 공학화 가능"입니다. 아주 새롭고, 기능은 아직 초기 단계입니다.+- [GraphArc](https://github.com/CodeGraphContext/grapharc)**개념 출시 전에 있던 것 (Graph Engineering이라고 부르지 않지만, 당신이 구축할 때 쓸 것은 바로 이것들)**@@ -346,4 +346,4 @@ agent를 시작하는 것은 버튼 하나, 한 마디입니다. 그러나 agent4. **다섯 가지 판단 기준 평가:** 목표를 정한 "그래프화"할지 고민 중인 작업을 하나 고르고, 다섯 가지 기준을 하나씩 점수로 매겨 보세요. 적어도 세 개를 충족해야 그래프를 그릴 가치가 있습니다. 세 개가 안 되면, 그것이 실제로 필요한 것은 더 나은 workflow 스크립트입니다 — 그래프를 쓰려고 그래프를 쓰지 마세요.-5. **graph.md를 실행 가능한 프로그램으로 만들기:** 이 강의 "첫 번째 그래프를 처음부터 구축하기"의 여섯 단계에 따라, 그린 maker-checker 그래프를 실제로 돌아가는 그래프로 구현하세요(참조 구현: `code/maker_checker_graph.py`, LangGraph로 작성). 여섯 단계를 건너뛰지 마세요: 상태 정의 → 노드 나열 → 엣지 연결 → 라우팅 작성 → checkpoint 달기 → 실행. 실행한 뒤 `graph.md`와 코드를 비교하고, 첫 번째로 안 맞는 곳을 찾아 그 이유를 설명하세요 — 그래프를 잘못 그린 건가요, 코드를 잘못 쓴 건가요?\ No newline at end of file+5. **graph.md를 실행 가능한 프로그램으로 만들기:** 이 강의 "첫 번째 그래프를 처음부터 구축하기"의 여섯 단계에 따라, 그린 maker-checker 그래프를 실제로 돌아가는 그래프로 구현하세요(참조 구현: `code/maker_checker_graph.py`, LangGraph로 작성). 여섯 단계를 건너뛰지 마세요: 상태 정의 → 노드 나열 → 엣지 연결 → 라우팅 작성 → checkpoint 달기 → 실행. 실행한 뒤 `graph.md`와 코드를 비교하고, 첫 번째로 안 맞는 곳을 찾아 그 이유를 설명하세요 — 그래프를 잘못 그린 건가요, 코드를 잘못 쓴 건가요?diff --git a/docs/ko/resources/reference/index.md b/docs/ko/resources/reference/index.mdindex a4baa05..6305051 100644--- a/docs/ko/resources/reference/index.md+++ b/docs/ko/resources/reference/index.md@@ -13,6 +13,11 @@- [On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents](https://arxiv.org/html/2601.20404v2): gpt-5.2-codex; 10 repos / 124 PR tasks; Table 1.+- [Anthropic: Sonnet 4.5 — SWE-bench Verified methodology (2025-09-29)](https://www.anthropic.com/news/claude-sonnet-4-5)+- [Boris Cherny: personal 30-day production report (2025-12-27)](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)+- [Karpathy: measured autoresearch leaderboard improvement](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b)+- [Karpathy: two-day autonomous tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)+## 권장 읽기 순서 (Suggested Reading Order)1. `method-map.md`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.mdindex 562db7e..4d92d3a 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,17 +5,30 @@# 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.+Claude Sonnet 4.5 · 2025-09-29 · SWE-bench Verified++| Score | Tasks | Trials | Scaffold |+| --- | --- | --- | --- |+| 77.2% | 500 | 10 | bash + string replacement |++Resultados de produção não isolam uma causa. Pontuações valem para o modelo, scaffold, dados e condições de avaliação indicados, não toda tarefa real. [Anthropic: methodology](https://www.anthropic.com/news/claude-sonnet-4-5)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.+> Mesmo modelo e prompt, mas diferentes orçamentos de tempo e custo. Não é um experimento de orçamento igual isolando um componente. A jogabilidade essencial funcionou, mas havia defeitos. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++Mesmo modelo e prompt, mas diferentes orçamentos de tempo e custo. Não é um experimento de orçamento igual isolando um componente. A jogabilidade essencial funcionou, mas havia defeitos. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++| Opus 4.5 | Duration | USD |+| --- | --- | --- |+| Solo | 20 min | 9 |+| Full harness | 6 h | 200 |Eles não mudaram o modelo. Opus 4.5 continuava sendo Opus 4.5. O que mudou foi o equipamento.-O artigo de Harness Engineering da OpenAI em 2025 foi ainda mais direto. Eles disseram que o Codex em um repositório com um bom harness deixa de ser “não confiável” e passa a ser “confiável”. Repare na escolha das palavras — não “um pouco melhor”, mas uma mudança qualitativa. Harness aqui significa **toda a infraestrutura de engenharia além dos pesos do modelo.**+Resultados de produção não isolam uma causa. Pontuações valem para o modelo, scaffold, dados e condições de avaliação indicados, não toda tarefa real. [OpenAI: 2026-02-11](https://openai.com/index/harness-engineering/)## Onde os Agentes Realmente Falham@@ -25,13 +38,13 @@ Os modos de falha específicos se resumem basicamente a alguns pontos:- **Convenções implícitas não documentadas — o agente não tem como seguir.** Todo o seu time usa a nova sintaxe do SQLAlchemy 2.0, mas o agente gera código 1.x por padrão. Todos os endpoints da API devem utilizar OAuth 2.0, mas essa regra existe apenas na sua cabeça e em uma mensagem no Slack de três meses atrás. O agente não faz ideia disso — não é que ele não queira seguir a regra, ele literalmente nunca a viu.- **Configuração de ambiente incompleta — o agente desperdiça energia corrigindo o ambiente.** Setup de desenvolvimento incompleto, dependências ausentes, versões erradas de ferramentas — o agente gasta contexto precioso lidando com erros de `pip install` e conflitos de versão do Node em vez de fazer o trabalho real.- **Ausência de métodos de verificação — o agente considera concluído quando acha que terminou.** Sem testes, sem lint ou comandos de verificação nunca comunicados ao agente. O agente escreve o código, revisa superficialmente, acha que está tudo certo e declara conclusão. A Anthropic também observou um fenômeno interessante: quando os agentes percebem que o contexto está acabando, eles aceleram para terminar, pulam etapas de verificação e escolhem soluções simples em vez das melhores soluções. Eles chamam isso de “ansiedade de contexto”.-- **Perda de estado entre sessões — toda nova sessão começa do zero.** Todas as descobertas da sessão anterior são perdidas. Cada nova sessão precisa redescobrir a estrutura do projeto e entender novamente a organização do código. Agentes sem estado persistente apresentam aumento significativo nas falhas em tarefas que ultrapassam 30 minutos.+- **Perda de estado entre sessões — toda nova sessão começa do zero.** — Registre progresso e verificações em arquivos versionados para a próxima sessão inspecionar o estado. A fonte explica o mecanismo sem quantificar redução no tempo de início. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## Terminologia EssencialCom 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.+- Resultados de produção não isolam uma causa. Pontuações valem para o modelo, scaffold, dados e condições de avaliação indicados, não toda tarefa real.- **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.- **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.@@ -60,15 +73,17 @@ 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.+Resultados de produção não isolam uma causa. Pontuações valem para o modelo, scaffold, dados e condições de avaliação indicados, não toda tarefa real. [OpenAI: 2026-02-11](https://openai.com/index/harness-engineering/)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?”-Esse experimento comprova diretamente a tese central desta aula: **o mesmo modelo produz resultados fundamentalmente diferentes em um ambiente cru versus um ambiente com harness completo.** O modelo não mudou. O ambiente mudou.+Resultados de produção não isolam uma causa. Pontuações valem para o modelo, scaffold, dados e condições de avaliação indicados, não toda tarefa real.> Fonte: [OpenAI: Engenharia de aproveitamento: alavancando o Codex em um mundo centrado em agentes.](https://openai.com/index/harness-engineering/)-## Um Exemplo Mais Próximo da Realidade+## Exemplo didático++> Ilustração didática: o cenário e seus números são hipóteses explicativas, não medições de um experimento publicado.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).@@ -94,6 +109,8 @@ Eles não mudaram o modelo. Mudaram o harness.- [SWE-bench Leaderboard](https://www.swebench.com/)- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)+- [Anthropic: Sonnet 4.5 SWE-bench methodology, 2025-09-29](https://www.anthropic.com/news/claude-sonnet-4-5)+## Exercícios1. **Experimento de comparação**: Escolha uma base de código que você conhece bem e uma tarefa de modificação não trivial. Primeiro, execute o agente sem suporte de harness e registre as falhas. Depois, adicione um `AGENTS.md` e comandos explícitos de verificação, execute novamente com o mesmo agente e compare os resultados, atribuindo cada falha a uma das cinco camadas de defesa.diff --git a/docs/pt-BR/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/pt-BR/lectures/lecture-02-what-a-harness-actually-is/index.mdindex 3974bb5..1047c7d 100644--- a/docs/pt-BR/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/pt-BR/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -69,7 +69,9 @@ A ausência de qualquer um dos cinco subsistemas significa um harness incompleto**Quantificando o valor dos componentes do harness**: Utilize um “teste de exclusão com variável controlada”. Mantenha o modelo fixo, remova os cinco subsistemas um de cada vez e observe qual remoção causa a maior queda de desempenho. O componente cuja remoção gera a maior queda possui a maior contribuição marginal para a tarefa atual e vale priorizar. Decidir se ele deve ser fortalecido depende da atribuição das falhas, não apenas do tamanho da queda. Componentes com impacto próximo de zero não devem ser descartados imediatamente: eles podem ser redundantes, mal projetados ou simplesmente não exercitados pela tarefa atual. Esse experimento responde “qual componente é mais valioso agora” — mas, sozinho, não consegue provar “onde está o gargalo”. Para realmente localizar um gargalo, primeiro é necessário examinar registros e atribuições de falha: a tarefa estava mal definida? O contexto era insuficiente? O ambiente não era reproduzível? Faltava feedback de verificação? O gerenciamento de estado estava quebrado? Resultados de ablação de componentes servem apenas como evidência complementar.-## A História Real de um Time+## Exemplo didático++> Ilustração didática: o cenário e seus números são hipóteses explicativas, não medições de um experimento publicado.Um time utilizou o GPT-4o para desenvolver uma aplicação frontend em TypeScript + React (~20.000 linhas de código). Eles passaram por quatro etapas, que basicamente consistiram em adicionar componentes de harness um de cada vez:diff --git a/docs/pt-BR/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/pt-BR/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdindex a8335fd..b9c5ec2 100644--- a/docs/pt-BR/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md+++ b/docs/pt-BR/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -5,6 +5,8 @@# Aula 03. Tornando o Repositório a Fonte Única da Verdade+> Orientação de engenharia: os limites numéricos são valores didáticos ajustáveis, não fronteiras demonstradas. Tokens dependem do tokenizador e do conteúdo, não apenas das linhas.+As decisões de arquitetura da sua equipe estão espalhadas entre Confluence, Slack, Jira e a cabeça de alguns engenheiros mais experientes. Para humanos isso mal funciona — você pode perguntar para um colega, pesquisar no histórico do chat, vasculhar documentação e, se tudo falhar, encontrar alguém na copa para tirar uma dúvida. Mas, para um agente de IA, informações que não estão no repositório simplesmente não existem.Isso não é exagero. Um agente possui apenas três fontes de entrada: prompts de sistema e descrições de tarefas, conteúdos de arquivos do repositório e saídas de execução de ferramentas. Seu histórico do Slack, tickets do Jira, páginas do Confluence e aquela decisão de arquitetura discutida com um colega numa sexta-feira à tarde — o agente não consegue ver nada disso. Ele não pode “perguntar para alguém” ou “pesquisar no histórico do chat”. Todo o universo de trabalho dele é o próprio repositório. Tudo o que está fora dele é desconhecido.@@ -132,7 +134,7 @@ A OpenAI relata cerca de 1.500 PR abertos e integrados em cinco meses por três- Como eu executo isso?- Como eu verifico isso?- Qual é o progresso atual?-+Registre quais perguntas ele não consegue responder e melhore o repositório até que consiga responder todas.2. **Quantificação da externalização de conhecimento**: Liste todas as decisões e restrições importantes para o desenvolvimento do seu projeto. Marque cada item como “dentro” ou “fora” do repositório. Calcule sua knowledge visibility gap (a proporção de itens fora do repo). Crie um plano para reduzir essa lacuna para menos de 10%.@@ -141,4 +143,4 @@ A OpenAI relata cerca de 1.500 PR abertos e integrados em cinco meses por três- Atomicidade — as operações do agente podem ser revertidas de forma limpa?- Consistência — o repositório possui verificações de “estado consistente”?- Isolamento — múltiplos agentes concorrentes interferem entre si?- - Durabilidade — todo o conhecimento entre sessões está devidamente persistido?\ No newline at end of file+ - Durabilidade — todo o conhecimento entre sessões está devidamente persistido?diff --git a/docs/pt-BR/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/pt-BR/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdindex 0a9db07..838cc26 100644--- a/docs/pt-BR/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md+++ b/docs/pt-BR/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -5,6 +5,8 @@# Aula 04. Divida as Instruções em Múltiplos Arquivos+> Orientação de engenharia: os limites numéricos são valores didáticos ajustáveis, não fronteiras demonstradas. Tokens dependem do tokenizador e do conteúdo, não apenas das linhas.+Você começou a levar harness engineering a sério — ótimo. Criou um `AGENTS.md` e colocou nele toda regra, restrição e lição aprendida que conseguiu imaginar. Um mês depois o arquivo tinha crescido para 300 linhas, dois meses depois 450, três meses depois 600. Então você percebe que a performance do agente está piorando: em uma simples correção de bug, o agente consome enormes quantidades de contexto processando instruções irrelevantes de deploy; uma restrição crítica de segurança escondida na linha 300 é completamente ignorada; três regras contraditórias de estilo de código fazem o agente escolher uma aleatoriamente a cada execução.Essa é a armadilha do “arquivo gigante de instruções”. Tudo parece importante, então você coloca tudo no mesmo lugar, e encontrar uma regra específica passa a exigir percorrer o arquivo inteiro. Você escreveu 600 linhas, mas apenas um terço delas realmente é relevante para a tarefa atual.@@ -137,4 +139,4 @@ Um estudo pareado usou gpt-5.2-codex em 124 tarefas de PR de 10 repositórios, c2. **Refatoração Reveal on Demand**: Se você possui um arquivo de instruções com mais de 300 linhas, divida-o em: (a) um arquivo de entrada com menos de 100 linhas, (b) entre 3 e 5 documentos de tópico. Execute o mesmo conjunto de tarefas (pelo menos 5) antes e depois da refatoração e compare as taxas de sucesso.-3. **Verificação do Lost in the Middle**: Em um arquivo longo de instruções, coloque uma restrição crítica no topo, no meio e no final, executando o mesmo conjunto de tarefas em cada caso (pelo menos 5 execuções por posição). Veja se existe diferença na taxa de conformidade. Você pode se surpreender com o quão forte é o efeito da posição.\ No newline at end of file+3. **Verificação do Lost in the Middle**: Em um arquivo longo de instruções, coloque uma restrição crítica no topo, no meio e no final, executando o mesmo conjunto de tarefas em cada caso (pelo menos 5 execuções por posição). Veja se existe diferença na taxa de conformidade. Você pode se surpreender com o quão forte é o efeito da posição.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.mdindex fe91822..829b607 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@@ -5,6 +5,8 @@# Aula 05. Mantendo o Contexto Vivo Entre Sessões+> Orientação de engenharia: os limites numéricos são valores didáticos ajustáveis, não fronteiras demonstradas. Tokens dependem do tokenizador e do conteúdo, não apenas das linhas.+Você pede ao Claude Code para implementar uma funcionalidade completa. Ele trabalha por 30 minutos, realiza a maior parte da tarefa, mas o contexto está se esgotando. Você inicia uma nova sessão para continuar — e descobre que ele não se lembra das decisões tomadas anteriormente, por que a opção A foi escolhida em vez da opção B, quais arquivos já foram modificados ou em que estado os testes se encontram. Ele gasta mais 15 minutos explorando novamente o projeto e pode até seguir uma abordagem diferente da utilizada anteriormente.Esse é o dilema real que agentes de IA enfrentam em tarefas que se estendem por múltiplas sessões. Nesta aula, veremos por que os agentes "perdem o fio da meada" durante tarefas longas e como a persistência estruturada de estado permite que uma nova sessão retome rapidamente o trabalho de onde a anterior parou.@@ -175,4 +177,4 @@ A LangChain relata aumento de 52,8% para 66,5%, 13,7 pontos percentuais, com o m2. **Criação de um template de handoff**: Desenvolva um template mínimo de handoff com quatro campos: estado do repositório (hash do commit), estado de execução (taxa de sucesso dos testes), bloqueios (*blockers*) e próximas ações. Permita que uma sessão completamente nova do agente restaure o estado do projeto utilizando apenas esse template. Registre as ambiguidades encontradas durante a restauração e refine o template iterativamente.-3. **Experimento com estratégia híbrida**: Em uma tarefa de desenvolvimento com 5 sessões, compare três abordagens: (a) sempre iniciar sessões novas utilizando arquivos de progresso, (b) fazer o máximo possível dentro de uma única sessão (compactação de contexto), e (c) estratégia híbrida (tarefas curtas dentro da sessão e tarefas longas distribuídas entre sessões com arquivos de progresso). Compare o tempo de reconstrução, a taxa de conclusão de funcionalidades e a consistência das decisões.\ No newline at end of file+3. **Experimento com estratégia híbrida**: Em uma tarefa de desenvolvimento com 5 sessões, compare três abordagens: (a) sempre iniciar sessões novas utilizando arquivos de progresso, (b) fazer o máximo possível dentro de uma única sessão (compactação de contexto), e (c) estratégia híbrida (tarefas curtas dentro da sessão e tarefas longas distribuídas entre sessões com arquivos de progresso). Compare o tempo de reconstrução, a taxa de conclusão de funcionalidades e a consistência das decisões.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.mdindex b504cac..550150c 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@@ -5,6 +5,8 @@# Aula 06. Faça o Agente Inicializar Antes de Cada Sessão de Trabalho+> Orientação de engenharia: os limites numéricos são valores didáticos ajustáveis, não fronteiras demonstradas. Tokens dependem do tokenizador e do conteúdo, não apenas das linhas.+Você inicia uma nova sessão do agente e pede: "adicione uma funcionalidade de busca". Ele parte imediatamente para a implementação — um entusiasmo admirável. Após 20 minutos, descobre que o framework de testes não está configurado corretamente, passa mais 10 minutos corrigindo isso e, em seguida, percebe que o formato do script de migração do banco de dados está incorreto, exigindo mais ajustes. No final, a funcionalidade de busca é implementada, mas toda a sessão foi ineficiente. A maior parte do tempo foi gasta "descobrindo como este projeto funciona" em vez de implementar a funcionalidade de busca em si.Uma abordagem melhor é utilizar uma fase separada antes de permitir que o agente comece a trabalhar: preparar o ambiente base, executar os comandos de verificação e compreender a estrutura do projeto. O trabalho de inicialização não deve ser agrupado com a implementação de funcionalidades — são dois tipos de tarefas fundamentalmente diferentes.@@ -37,6 +39,8 @@ flowchart TB## O Que Acontece Quando Você Mistura as Duas Coisas+> Ilustração didática: o cenário e seus números são hipóteses explicativas, não medições de um experimento publicado.+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.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 +49,7 @@ O orçamento de contexto também é desperdiçado. O trabalho de inicializaçãoO 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.+[Anthropic: initializer / coding agent](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)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.@@ -128,7 +132,9 @@ O guia de *harness engineering* do Codex da OpenAI também enfatiza o princípio- [ ] Tudo está registrado em commits no Git```-## Exemplo do Mundo Real+## Exemplo didático++> Ilustração didática: o cenário e seus números são hipóteses explicativas, não medições de um experimento publicado.Comparação entre duas abordagens de inicialização para um projeto frontend em React:@@ -160,4 +166,4 @@ Comparação do ciclo completo do projeto: a abordagem mista apresentou um tempo2. **Experimento de comparação**: Escolha um novo projeto de complexidade moderada. Abordagem A: permita que o agente realize a inicialização e a primeira implementação simultaneamente. Abordagem B: dedique uma sessão inteira à inicialização e inicie a implementação apenas na sessão 2. Após 4 sessões, compare o tempo até o primeiro teste aprovado, o custo de reconstrução e a taxa de conclusão de funcionalidades.-3. **Checklist de aceitação da inicialização**: Desenvolva um checklist de aceitação da inicialização para o seu projeto. Faça com que uma nova sessão do agente execute cada item do checklist e registre quais itens passaram e quais falharam. Os itens que falharem indicam exatamente onde o seu *harness* precisa ser fortalecido.\ No newline at end of file+3. **Checklist de aceitação da inicialização**: Desenvolva um checklist de aceitação da inicialização para o seu projeto. Faça com que uma nova sessão do agente execute cada item do checklist e registre quais itens passaram e quais falharam. Os itens que falharem indicam exatamente onde o seu *harness* precisa ser fortalecido.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.mdindex 46f9089..6ccc278 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@@ -5,6 +5,8 @@# Aula 07. Defina Limites Claros de Tarefa para os Agentes+> Orientação de engenharia: os limites numéricos são valores didáticos ajustáveis, não fronteiras demonstradas. Tokens dependem do tokenizador e do conteúdo, não apenas das linhas.+Você pede ao Claude Code para "adicionar autenticação de usuários a este projeto", e ele começa a modificar o esquema do banco de dados, criar rotas, alterar componentes do frontend e — já que está mexendo nisso — refatorar também o middleware de tratamento de erros. Duas horas depois você verifica o resultado: 12 arquivos modificados, 800 linhas de código novas e nem uma única funcionalidade funcionando de ponta a ponta.Os agentes nascem com um impulso de "fazer só mais um pouquinho" — eles identificam elementos relacionados e simplesmente resolvem tudo no mesmo fluxo. O problema é que tentar fazer muitas coisas ao mesmo tempo praticamente garante que nenhuma delas será bem concluída.@@ -26,7 +28,7 @@ O comportamento real do Claude Code é bastante revelador. Peça para ele "adiciSeis 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.+[Anthropic: incremental feature work](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## Fluxo de Trabalho WIP=1@@ -103,7 +105,9 @@ Utilize um arquivo legível por máquina (JSON ou Markdown) para registrar o estO *harness* deve acompanhar continuamente a VCR (*Verified Completion Rate*) = tarefas verificadas / tarefas ativadas. Bloqueie a ativação de novas tarefas quando VCR < 1.0.-## Caso do Mundo Real+## Exemplo didático++> Ilustração didática: o cenário e seus números são hipóteses explicativas, não medições de um experimento publicado.Projeto de API REST com 8 funcionalidades, comparando duas estratégias: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.mdindex a646e7d..4b2cebf 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@@ -5,6 +5,8 @@# Aula 08. Use Listas de Funcionalidades para Restringir o que o Agente Faz+> Orientação de engenharia: os limites numéricos são valores didáticos ajustáveis, não fronteiras demonstradas. Tokens dependem do tokenizador e do conteúdo, não apenas das linhas.+Você pede a um agente para construir um site de e-commerce. Depois que ele termina, ele diz: "concluído". Você olha o código — a autenticação de usuários funciona, mas o botão de checkout no carrinho não faz nada, e o fluxo de pagamento nem sequer está conectado. Onde as coisas deram errado? Você nunca disse ao agente o que significa "concluído", então ele usou o próprio padrão: "escrevi bastante código e parece razoavelmente completo".Na visão de muitas pessoas, listas de funcionalidades são apenas um lembrete — anote as coisas para não esquecer e depois descarte. Mas no mundo dos harnesses, uma lista de funcionalidades não é um lembrete para humanos. Ela é a estrutura fundamental sobre a qual todo o harness é construído. O escalonador depende dela para selecionar tarefas, o verificador depende dela para julgar a conclusão, e o gerador de relatórios de handoff depende dela para criar resumos. Sem ela, esses componentes não têm um consenso compartilhado em que possam se apoiar.@@ -25,7 +27,7 @@ Autenticação do usuário concluída, carrinho de compras quase pronto, faltamUma 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%.+Registre progresso e verificações em arquivos versionados para a próxima sessão inspecionar o estado. A fonte explica o mecanismo sem quantificar redução no tempo de início. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## Máquina de Estados das Funcionalidades@@ -108,7 +110,9 @@ O agente não pode alterar diretamente o estado de uma funcionalidade para `passCada item de funcionalidade deve ter um escopo que possa ser **concluído em uma única sessão**. Se for amplo demais, não será finalizado; se for detalhado demais, o custo de gerenciamento aumenta. "O usuário pode adicionar itens ao carrinho" é uma boa granularidade. "Implementar o carrinho de compras" é amplo demais. "Criar o campo `name` no modelo Cart" é detalhado demais.-## Caso Real+## Exemplo didático++> Ilustração didática: o cenário e seus números são hipóteses explicativas, não medições de um experimento publicado.Uma plataforma de e-commerce com 10 funcionalidades. Duas abordagens de acompanhamento foram comparadas:@@ -116,8 +120,6 @@ 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.-## Principais Aprendizados* **Listas de funcionalidades são a estrutura fundamental do harness**, não memorandos para humanos. O scheduler, o verifier e o handoff reporter dependem delas.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.mdindex 72da255..610379d 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@@ -5,12 +5,16 @@# Aula 09. Como Impedir que Agentes Declarem Vitória Cedo Demais+> Orientação de engenharia: os limites numéricos são valores didáticos ajustáveis, não fronteiras demonstradas. Tokens dependem do tokenizador e do conteúdo, não apenas das linhas.+Você pede a um agente para implementar uma funcionalidade de "redefinição de senha". Ele modifica o esquema do banco de dados, cria o endpoint da API, adiciona o template de e-mail, executa os testes unitários (todos passam) e então afirma com confiança: "está pronto". Mas quando você realmente tenta usar a funcionalidade, descobre que o link de redefinição de senha não pode ser enviado porque a configuração do serviço de e-mail está ausente; a migração do banco de dados falha no meio da execução, deixando o esquema em um estado inconsistente; e o fluxo completo de ponta a ponta nunca foi executado sequer uma vez.Isso não é um incidente isolado. O clássico artigo da ICML de 2017, de Guo et al., demonstrou que **redes neurais modernas são sistematicamente excessivamente confiantes** — a confiança relatada pelos modelos é significativamente maior do que sua precisão real. Agentes de programação com IA não são diferentes. Eles "sentem" que terminaram, mas, na prática, estão longe disso. Seu harness deve substituir os "sentimentos" do agente por verificações externalizadas e baseadas em execução.## A Ladeira Escorregadia+> Mesmo modelo e prompt, mas diferentes orçamentos de tempo e custo. Não é um experimento de orçamento igual isolando um componente. A jogabilidade essencial funcionou, mas havia defeitos. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)+Declarações prematuras de conclusão quase sempre seguem o mesmo roteiro: o código parece correto — a sintaxe está certa, a lógica parece razoável e a análise estática não aponta erros evidentes. Porém, o harness não exige uma verificação completa por execução, então o agente deixa de executar o sistema de fato ou executa apenas testes parciais. Ele roda os testes unitários, mas ignora os testes de integração; executa testes, mas não verifica cobertura. No final, "o código parece bom" é tratado como evidência de que "a funcionalidade está concluída".Informação é perdida em cada etapa. Da especificação da tarefa à implementação do código e ao comportamento em tempo de execução, cada transformação pode introduzir vieses, e cada verificação ignorada aumenta a assimetria de informação.@@ -110,7 +114,9 @@ Sinais eficazes de tempo de execução incluem:* As gravações no banco de dados, operações de arquivo e outros efeitos colaterais ocorreram corretamente?* Os recursos temporários foram limpos adequadamente?-## Caso Real+## Exemplo didático++> Ilustração didática: o cenário e seus números são hipóteses explicativas, não medições de um experimento publicado.**Tarefa**: Implementar a funcionalidade de redefinição de senha de usuários. Envolve operações de banco de dados, envio de e-mails e modificações em endpoints da API.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.mdindex 0d729d8..71e9d9d 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@@ -5,6 +5,8 @@# Aula 10. Apenas uma Execução Completa do Pipeline Conta como Verificação Real+> Orientação de engenharia: os limites numéricos são valores didáticos ajustáveis, não fronteiras demonstradas. Tokens dependem do tokenizador e do conteúdo, não apenas das linhas.+Você pede ao agente para adicionar uma funcionalidade de exportação de arquivos a uma aplicação Electron. Ele escreve o componente do renderer, o script de preload e a lógica da camada de serviço. Os testes unitários de todos os componentes passam. O agente diz "concluído". Você realmente clica no botão de exportação — o formato do caminho do arquivo está incorreto, a barra de progresso não responde e a exportação de arquivos grandes causa vazamento de memória. Cinco defeitos nas fronteiras entre componentes, e os testes unitários não detectaram nenhum deles.Cada parte parece "correta" por si só, mas os problemas surgem no momento em que tudo é conectado. A Pirâmide de Testes do Google nos diz que uma ampla base de testes unitários é essencial, mas parar por aí significa que você deixará de identificar sistematicamente problemas de interação entre componentes. Para agentes de programação com IA, esse problema é ainda pior, porque eles tendem a executar apenas os testes mais rápidos e então declarar a tarefa concluída. **Somente testes end-to-end podem comprovar a ausência de defeitos em nível de sistema.**@@ -114,7 +116,9 @@ CORREÇÃO: Mova as operações de arquivo para src/preload/file-ops.ts e façaSempre que você descobrir uma nova categoria de erro cometido por agentes durante a revisão de código, transforme-a em uma verificação automatizada. Um mês depois, seu harness estará muito mais robusto do que estava no início do mês.-## Caso Real+## Exemplo didático++> Ilustração didática: o cenário e seus números são hipóteses explicativas, não medições de um experimento publicado.**Tarefa**: Implementar uma funcionalidade de exportação de arquivos em uma aplicação Electron. Envolve a interface do processo renderer, um proxy de sistema de arquivos no script de preload e a camada de serviço responsável pela transformação dos dados.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.mdindex 7045c34..009dcca 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@@ -23,13 +23,15 @@ Quando um harness não possui observabilidade, quatro categorias de problemas ap**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.-## Um Cenário Real com Claude Code+## Exemplo didático++> Ilustração didática: o cenário e seus números são hipóteses explicativas, não medições de um experimento publicado.Considere um harness utilizando um fluxo de trabalho com três papéis: planejador (*planner*), gerador (*generator*) e avaliador (*evaluator*), executando a tarefa "adicionar modo escuro ao aplicativo".**Sem observabilidade:** O planejador produz uma descrição vaga. O gerador implementa o modo escuro com base nessa descrição imprecisa, mas o resultado não corresponde às expectativas implícitas do planejador. O avaliador rejeita a implementação com base em seus próprios critérios implícitos, mas não consegue explicar especificamente o problema — apenas afirma que "não parece correto". O gerador tenta corrigir o problema usando justificativas vagas. O ciclo se repete de três a quatro vezes, consumindo cerca de 45 minutos e produzindo apenas um resultado aceitável.-**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.+**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. [W3C: contrast minimum](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)Uma diferença de eficiência de 3x. A única variável alterada é a observabilidade.@@ -120,7 +122,9 @@ Transforme a pergunta "está bom ou não?" em uma pontuação quantificável:Crie um *trace* para cada sessão do harness, um *span* para cada tarefa e *sub-spans* para cada etapa de verificação. Utilize atributos padronizados para anotar informações importantes. Dessa forma, os dados de observabilidade podem ser integrados a ferramentas padrão do mercado (Jaeger, Zipkin).-## Experimento da Anthropic com Arquitetura de Três Agentes+## Exemplo didático++> Ilustração didática: o cenário e seus números são hipóteses explicativas, não medições de um experimento publicado.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: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.mdindex 79853d1..db33555 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@@ -5,6 +5,8 @@# Aula 12. Deixe uma Transferência Limpa ao Final de Cada Sessão+> Orientação de engenharia: os limites numéricos são valores didáticos ajustáveis, não fronteiras demonstradas. Tokens dependem do tokenizador e do conteúdo, não apenas das linhas.+Seu agente executa tarefas durante toda a tarde, modifica 20 arquivos, faz commit do código e a sessão termina. A próxima sessão do agente é iniciada e imediatamente descobre: o build está quebrado, os testes estão falhando, arquivos temporários de debug estão espalhados por toda parte, a lista de funcionalidades não foi atualizada e o progresso está completamente opaco. Os primeiros 30 minutos da nova sessão são gastos inteiramente tentando "descobrir o que a sessão anterior realmente fez".Tanto a OpenAI quanto a Anthropic afirmam claramente: **a confiabilidade de longo prazo depende de disciplina operacional, não apenas de sucesso em uma única execução.** A qualidade do estado ao final de cada sessão determina diretamente a eficiência da próxima sessão.@@ -15,7 +17,7 @@ As leis da evolução de software de Lehman nos dizem que sistemas submetidos aDurante 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 OpenAI dedicava as sextas à limpeza: um dia útil, 20% da semana, não 20% da sexta-feira. [OpenAI](https://openai.com/index/harness-engineering/)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 +47,7 @@ flowchart LRFix --> 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%.+Registre progresso e verificações em arquivos versionados para a próxima sessão inspecionar o estado. A fonte explica o mecanismo sem quantificar redução no tempo de início. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)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,6 +78,8 @@ A armadilha mental mais comum é pensar: "não tenho tempo para limpar nesta sesPior 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.+> Ilustração didática: o cenário e seus números são hipóteses explicativas, não medições de um experimento publicado.+Os números contam a história. Um projeto desenvolvido com agentes durante 12 semanas, sem estratégia de limpeza:- Semana 1: taxa de sucesso do build 100%, taxa de sucesso dos testes 100%, inicialização de nova sessão em 5 min@@ -88,8 +92,6 @@ 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.-## Como Fazer### 1. Estado Limpo É uma Condição Necessária para Conclusão@@ -141,7 +143,7 @@ Novas sessões leem esse documento e sabem imediatamente onde priorizar esforçoTodo 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.+A tabela corresponde ao harness atualizado com Opus 4.6: uma arquitetura com três agentes. A divisão em sprints foi removida. Planner define a especificação, builder implementa e evaluator testa a aplicação e envia feedback para a próxima rodada. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)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.@@ -166,7 +168,9 @@ Quando a produção dos agentes excede em muito a capacidade humana de revisão,**Ressalva**: Isso é irresponsável em um ambiente de baixa vazão. Mas quando a produção dos agentes excede em muito a atenção humana disponível, geralmente é a troca correta. O critério principal é: **custo médio para corrigir um bug versus custo médio de esperar um humano revisar um PR.** Quando o primeiro é menor que o segundo, realizar merges rapidamente é a decisão correta.-## Caso Real+## Exemplo didático++> Ilustração didática: o cenário e seus números são hipóteses explicativas, não medições de um experimento publicado.Um aplicativo Electron desenvolvido com agentes durante 12 semanas, comparando duas abordagens:@@ -174,8 +178,6 @@ 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.-## Principais Conclusões- **Estado limpo é uma condição necessária para concluir uma sessão** — não é uma tarefa opcional de organização, mas parte da própria "definição de concluído".diff --git a/docs/pt-BR/lectures/lecture-13-loop-engineering/index.md b/docs/pt-BR/lectures/lecture-13-loop-engineering/index.mdindex 33489f0..3435db6 100644--- a/docs/pt-BR/lectures/lecture-13-loop-engineering/index.md+++ b/docs/pt-BR/lectures/lecture-13-loop-engineering/index.md@@ -5,6 +5,8 @@# Aula 13. Do Prompting Manual aos Loops Autônomos+> Orientação de engenharia: os limites numéricos são valores didáticos ajustáveis, não fronteiras demonstradas. Tokens dependem do tokenizador e do conteúdo, não apenas das linhas.+Tudo o que você aprendeu nas primeiras doze aulas se baseia em uma premissa: **você está sentado ao teclado, digitando instruções uma de cada vez.**Você escreveu o `AGENTS.md` (Aulas 1–4), construiu o gerenciamento de estado (Aulas 5–6), restringiu o escopo com listas de funcionalidades (Aulas 7–8), deixou transferências limpas ao final das sessões (Aulas 9, 12) e tornou o runtime observável (Aulas 10–11). Mas o gatilho para tudo isso sempre foi você. O agente nunca decidiu por conta própria quando começar a trabalhar — porque ninguém pressionou "iniciar".@@ -86,6 +88,8 @@ Você não precisa digitar `/goal` toda vez. Mas entender de onde ele veio e por## Junho de 2026: Três Pessoas Acenderam o Mesmo Fusível em Uma Semana+> Ilustração didática: o cenário e seus números são hipóteses explicativas, não medições de um experimento publicado.+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.**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."@@ -96,7 +100,13 @@ 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.+Boris Cherny · 2025-12-27++| PR | Git commits | + LoC | − LoC | Model |+| --- | --- | --- | --- | --- |+| 259 / 30 days | 497 | 40,000 | 38,000 | Claude Code + Opus 4.5 |++Atividade pessoal declarada pelo autor, não taxa de sucesso de benchmark ou prova de ausência de supervisão humana. [Boris Cherny](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)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.@@ -267,7 +277,7 @@ flowchart TDIsso 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.+Atividade pessoal declarada pelo autor, não taxa de sucesso de benchmark ou prova de ausência de supervisão humana.## Separação Gerador/Avaliador: Por Que Você Não Pode Deixar o Modelo Corrigir o Próprio Trabalho@@ -293,7 +303,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.+[Karpathy: autoresearch](https://github.com/karpathy/autoresearch) · [announcement](https://x.com/karpathy/status/2030371219518931079)### Três Arquivos, Três Papéis@@ -343,8 +353,6 @@ flowchart TD8b --> 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 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".### Saída: O Que Você Vê Quando Acorda@@ -359,6 +367,8 @@ Apenas commits que realmente melhoraram ficam na branch principal. Tudo que falhCada experimento — sucesso ou falha — é registrado:+> Ilustração didática: o cenário e seus números são hipóteses explicativas, não medições de um experimento publicado.+```timestamp commit_hash val_bpb vram_mb description--------- ------------- ---------- ---------- ----------------------------@@ -375,11 +385,10 @@ 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:+- Reduziu o tempo de treinamento em nível GPT-2 do nanochat em 8×H100 de **2,02 horas → 1,80 horas**, cerca de **10.89% 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. [Karpathy: leaderboard commit](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b) · [tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)-- 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.+> Ilustração didática: o cenário e seus números são hipóteses explicativas, não medições de um experimento publicado.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.@@ -399,7 +408,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.**+Resultados de produção não isolam uma causa. Pontuações valem para o modelo, scaffold, dados e condições de avaliação indicados, não toda tarefa real.### 3. Rendição Cognitivadiff --git a/docs/pt-BR/lectures/lecture-14-graph-engineering/index.md b/docs/pt-BR/lectures/lecture-14-graph-engineering/index.mdindex fff7f7f..8a12955 100644--- a/docs/pt-BR/lectures/lecture-14-graph-engineering/index.md+++ b/docs/pt-BR/lectures/lecture-14-graph-engineering/index.md@@ -261,7 +261,7 @@ Primeiro, deixe claro o limite: **Graph Engineering é um nome que só existe de**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)**Antes do lançamento do conceito (não se chamam Graph Engineering, mas são o que você vai usar na prática)**@@ -346,4 +346,4 @@ Nem toda tarefa merece um grafo. Cinco critérios; satisfaça pelo menos três a4. **Avaliação dos cinco critérios:** escolha uma tarefa em que você está em dúvida se deve "graficar" e pontue-a item a item com os cinco critérios. Só vale a pena desenhar se satisfizer pelo menos três. Se não chegar a três, o que ela precisa é de um script de workflow melhor — não use grafo só por usar grafo.-5. **Transforme o graph.md em um programa executável:** seguindo os seis passos de "Construindo Seu Primeiro Grafo do Zero" desta aula, implemente o grafo maker-checker que você desenhou como um grafo que realmente roda (referência: `code/maker_checker_graph.py`, escrito em LangGraph). Não pule os seis passos: definir estado → listar nós → conectar arestas → escrever roteamento → adicionar checkpoints → rodar. Depois de rodar, compare o `graph.md` com o código, encontre a primeira divergência e explique por que ela existe — o grafo foi desenhado errado, ou o código foi escrito errado?\ No newline at end of file+5. **Transforme o graph.md em um programa executável:** seguindo os seis passos de "Construindo Seu Primeiro Grafo do Zero" desta aula, implemente o grafo maker-checker que você desenhou como um grafo que realmente roda (referência: `code/maker_checker_graph.py`, escrito em LangGraph). Não pule os seis passos: definir estado → listar nós → conectar arestas → escrever roteamento → adicionar checkpoints → rodar. Depois de rodar, compare o `graph.md` com o código, encontre a primeira divergência e explique por que ela existe — o grafo foi desenhado errado, ou o código foi escrito errado?diff --git a/docs/pt-BR/resources/reference/index.md b/docs/pt-BR/resources/reference/index.mdindex 770da0b..06d3f05 100644--- a/docs/pt-BR/resources/reference/index.md+++ b/docs/pt-BR/resources/reference/index.md@@ -59,6 +59,11 @@ Referências gerais estritamente de 2025 foram excluídas da lista principal. O- [On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents](https://arxiv.org/html/2601.20404v2): gpt-5.2-codex; 10 repos / 124 PR tasks; Table 1.+- [Anthropic: Sonnet 4.5 — SWE-bench Verified methodology (2025-09-29)](https://www.anthropic.com/news/claude-sonnet-4-5)+- [Boris Cherny: personal 30-day production report (2025-12-27)](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)+- [Karpathy: measured autoresearch leaderboard improvement](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b)+- [Karpathy: two-day autonomous tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)+## Ordem de Leitura Sugerida1. `method-map.md`diff --git a/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex 3159f6d..bc94535 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,17 +9,30 @@Первая мысль? «Модель слабовата. Пора апгрейдиться». Стоп. Прежде чем доставать кошелёк, подумайте: возможно, проблема вовсе не в модели.-Посмотрим на цифры. К концу 2025 года самые сильные кодинг-агенты на SWE-bench Verified выдают примерно 50–60%. И это на тщательно отобранных задачах с понятными описаниями issue и существующими тестами. Перейдите в свою повседневную среду разработки — расплывчатые требования, отсутствие тестов, неявные бизнес-правила, разбросанные повсюду — и эта цифра только падает.+Claude Sonnet 4.5 · 2025-09-29 · SWE-bench Verified++| Score | Tasks | Trials | Scaffold |+| --- | --- | --- | --- |+| 77.2% | 500 | 10 | bash + string replacement |++Производственные результаты не изолируют одну причину. Оценки относятся к указанным модели, scaffold, данным и условиям, не к любой реальной задаче. [Anthropic: methodology](https://www.anthropic.com/news/claude-sonnet-4-5)Но за этими числами скрывается контринтуитивная истина.## Один и тот же конь, разные судьбы-Anthropic провели контролируемый эксперимент. Один и тот же промпт («собери 2D ретро-конструктор игр»), одна и та же модель (Opus 4.5). Первый прогон: голая среда без поддержки — 20 минут, $9, ключевые механики игры просто не работают. Второй прогон: полный harness (архитектура из трёх агентов: planner + generator + evaluator) — 6 часов, $200, в игру можно играть.+> Модель и запрос одинаковые, но бюджеты времени и стоимости различаются. Это не равнобюджетный эксперимент, изолирующий один компонент. Основная игра работала, но дефекты оставались. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++Модель и запрос одинаковые, но бюджеты времени и стоимости различаются. Это не равнобюджетный эксперимент, изолирующий один компонент. Основная игра работала, но дефекты оставались. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++| Opus 4.5 | Duration | USD |+| --- | --- | --- |+| Solo | 20 min | 9 |+| Full harness | 6 h | 200 |Модель не меняли. Opus 4.5 оставался Opus 4.5. Изменилась упряжь.-Статья OpenAI 2025 года про harness engineering говорит прямо: Codex в репозитории с хорошим harness переходит из «ненадёжного» в «надёжный». Обратите внимание на формулировку — не «чуть лучше», а качественный сдвиг. Как с породистой лошадью: ездить можно и без подходящей упряжи, но далеко не уедете, быстро не разгонитесь, и упасть — не сюрприз. Harness и есть вся эта упряжь — **всё в инженерной инфраструктуре, что находится за пределами весов модели.**+Производственные результаты не изолируют одну причину. Оценки относятся к указанным модели, scaffold, данным и условиям, не к любой реальной задаче. [OpenAI: 2026-02-11](https://openai.com/index/harness-engineering/)## Где на самом деле застревают агенты@@ -39,9 +52,9 @@ Anthropic провели контролируемый эксперимент. ОКогда вы видите эти сценарии вживую, термины перестают быть просто жаргоном:-- **Capability Gap**: огромная пропасть между производительностью модели на бенчмарках и на реальных задачах. 50–60% pass rate на SWE-bench Verified означает, что почти половина реальных issue не решается.+- Производственные результаты не изолируют одну причину. Оценки относятся к указанным модели, scaffold, данным и условиям, не к любой реальной задаче.- **Harness**: всё за пределами модели — инструкции, инструменты, среда, управление состоянием, верификационная обратная связь. Если это не веса модели — это harness. Та самая «упряжь».-- **Harness-Induced Failure**: у модели достаточно способностей, но в среде исполнения есть структурные дефекты. Контролируемый эксперимент Anthropic это уже доказал.+- **Harness-Induced Failure**: у модели достаточно способностей, но в среде исполнения есть структурные дефекты. Контролируемый эксперимент- **Verification Gap**: разрыв между уверенностью агента в своей работе и реальной корректностью. Агент говорит «я закончил», когда не закончил — самый частый паттерн провала.- **Diagnostic Loop**: выполнить, увидеть провал, отнести его к конкретному слою harness, починить этот слой, выполнить снова. Это ядро методологии harness engineering.- **Definition of Done**: набор машинно-проверяемых условий — тесты проходят, линт чистый, проверки типов проходят. Без явного definition of done агент придумает свой.@@ -72,17 +85,19 @@ Anthropic провели контролируемый эксперимент. О## Эксперимент в миллион строк-В 2025 году OpenAI провели агрессивный эксперимент: с помощью Codex построить целый внутренний продукт из пустого git-репозитория. Через пять месяцев в репо было примерно миллион строк кода — прикладная логика, инфраструктура, инструментарий, документация, внутренние dev-инструменты — всё сгенерировано агентом. Три инженера управляли Codex, открыли и смержили около 1500 PR. В среднем 3,5 PR на человека в день.+Производственные результаты не изолируют одну причину. Оценки относятся к указанным модели, scaffold, данным и условиям, не к любой реальной задаче. [OpenAI: 2026-02-11](https://openai.com/index/harness-engineering/)-Ключевое ограничение: **люди не пишут код напрямую.** Это была не показуха — так заставили команду понять, что меняется, когда основная работа инженера — уже не написание кода, а проектирование сред, формулирование намерения и построение петель обратной связи.+Производственные результаты не изолируют одну причину. Оценки относятся к указанным модели, scaffold, данным и условиям, не к любой реальной задаче.В начале прогресс был медленнее ожидаемого. Не потому что у Codex не хватало способностей, а потому что среда была недостаточно полной — агенту не хватало нужных инструментов, абстракций и внутренних структур, чтобы продвигаться к высокоуровневым целям. Работа инженеров превратилась в: разбиение больших целей на маленькие строительные блоки (дизайн, код, ревью, тест), сборку их агентом, а затем использование этих блоков для разблокирования более сложных задач. Когда что-то ломалось, фиксом почти никогда не было «попробуем сильнее» — было «какой способности агенту не хватает и как сделать её одновременно понятной и исполняемой?».-Этот эксперимент напрямую подтверждает главный тезис лекции: **одна и та же модель в голой среде и в среде с полным harness даёт принципиально разные результаты.** Модель не менялась. Менялась среда.+Производственные результаты не изолируют одну причину. Оценки относятся к указанным модели, scaffold, данным и условиям, не к любой реальной задаче.> Источник: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)-## Более приземлённый пример+## Учебный пример++> Учебная иллюстрация: сценарий и его числа являются поясняющими допущениями, не измерениями опубликованного эксперимента.Команда использовала Claude Sonnet, чтобы добавить новый API-эндпоинт в среднеразмерное Python-веб-приложение (FastAPI + PostgreSQL + Redis, ~15 000 строк кода).@@ -108,6 +123,8 @@ Anthropic провели контролируемый эксперимент. О- [SWE-bench Leaderboard](https://www.swebench.com/)- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)+- [Anthropic: Sonnet 4.5 SWE-bench methodology, 2025-09-29](https://www.anthropic.com/news/claude-sonnet-4-5)+## Упражнения1. **Сравнительный эксперимент**: возьмите хорошо знакомую вам кодовую базу и нетривиальную задачу на изменение. Сначала прогоните агента без harness-поддержки и зафиксируйте провалы. Затем добавьте `AGENTS.md` с явными командами верификации и прогоните снова с тем же агентом. Сравните результаты, относя каждый провал к одному из пяти защитных слоёв.diff --git a/docs/ru/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/ru/lectures/lecture-02-what-a-harness-actually-is/index.mdindex e9ef390..c776fab 100644--- a/docs/ru/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/ru/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -70,7 +70,9 @@ flowchart LR**Оценка ценности компонентов harness**: используйте абляцию компонентов при фиксированной модели. Зафиксируйте модель, удаляйте подсистемы по одной и измеряйте, какое удаление сильнее всего просаживает производительность. Самая большая просадка показывает компонент с наибольшим предельным вкладом в этой задаче; она не определяет бутылочное горлышко автоматически. Почти нулевая просадка тоже требует интерпретации: компонент может быть избыточным, плохо спроектированным или просто не задействованным этой задачей. Чтобы диагностировать бутылочные горлышки, сначала используйте журналы сбоев и атрибуцию, а абляцию — как вспомогательное доказательство: сбой вызван размытой задачей, нехваткой контекста, невоспроизводимой средой, отсутствием верификационной обратной связи или сломанным управлением состоянием?-## Реальная история одной команды+## Учебный пример++> Учебная иллюстрация: сценарий и его числа являются поясняющими допущениями, не измерениями опубликованного эксперимента.Команда использовала GPT-4o на TypeScript + React фронтенде (~20 000 строк кода). Они прошли четыре стадии — по сути, добавляя кухонное оборудование по одной единице:diff --git a/docs/ru/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/ru/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdindex 3873898..e85748d 100644--- a/docs/ru/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md+++ b/docs/ru/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -5,6 +5,8 @@# Лекция 03. Сделайте репозиторий своим единственным источником истины+> Инженерные ориентиры: числа — настраиваемые учебные значения, не доказанные пороги. Количество токенов зависит от токенизатора и содержания, не только строк.+Архитектурные решения вашей команды разбросаны по Confluence, Slack, Jira и головам нескольких сеньоров. Для людей это кое-как работает — можно спросить коллегу, поискать в чате, покопаться в доках. В крайнем случае поймать кого-то в курилке. Но для AI-агента информация, которой нет в репозитории, попросту не существует.Это не преувеличение. Подумайте, что вообще является входом для агента: системные промпты и описания задач, содержимое файлов из репозитория, вывод инструментов. И всё. Ваша история в Slack, тикеты в Jira, страницы в Confluence и то архитектурное решение, которое вы обсудили с коллегой за кофе в пятницу днём — агент ничего из этого не видит. Он не может «пойти спросить» или «поискать в чате». Это инженер, запертый внутри репозитория — что снаружи, он не знает.diff --git a/docs/ru/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/ru/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdindex af06fe6..4a8133b 100644--- a/docs/ru/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md+++ b/docs/ru/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -5,6 +5,8 @@# Лекция 04. Разносите инструкции по файлам+> Инженерные ориентиры: числа — настраиваемые учебные значения, не доказанные пороги. Количество токенов зависит от токенизатора и содержания, не только строк.+Вы серьёзно занялись harness engineering — здорово. Создали `AGENTS.md` и впихнули туда каждое правило, ограничение и вынесенный урок, какой только смогли вспомнить. Через месяц файл раздулся до 300 строк, через два — до 450, через три — до 600. И тут вы замечаете, что качество работы агента на самом деле падает: на простом фиксе бага агент сжигает кучу контекста на ненужные деплой-инструкции; критичное правило безопасности, закопанное на 300-й строке, просто игнорируется; три противоречащих друг другу правила стиля заставляют агента каждый раз случайно выбирать одно из них.Это ловушка «гигантского файла инструкций». Это как переупаковать чемодан — всё кажется полезным, поэтому вы запихиваете всё, пока молния не лопнет. Чтобы найти смену белья, приходится опустошить весь чемодан. Вы тащили полный чемодан, а реально использовали примерно треть содержимого.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.mdindex ef16578..32c91db 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@@ -5,6 +5,8 @@# Лекция 05. Сохраняйте контекст между сессиями+> Инженерные ориентиры: числа — настраиваемые учебные значения, не доказанные пороги. Количество токенов зависит от токенизатора и содержания, не только строк.+Вы просите Claude Code реализовать целую фичу. Он работает 30 минут, делает большую часть работы, но контекст подходит к концу. Вы открываете новую сессию, чтобы продолжить, — и обнаруживаете, что он не помнит ни какие решения были приняты, ни почему вариант A был выбран вместо варианта B, ни какие файлы уже изменены, ни в каком состоянии находятся тесты. Он тратит 15 минут на повторное изучение проекта и может действовать вразрез с предыдущим подходом.Представьте, что вы мастер, который каждое утро после пробуждения всё забывает. Вам пришлось бы заново знакомиться со всей стройкой — какая стена недостроена, почему выбрали красный кирпич вместо синего, докуда дошли с водопроводом. Хуже того, вы могли бы выломать окно, которое уже было установлено вчера, просто потому что не помнили об этом.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.mdindex 968d9fe..965b475 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@@ -5,6 +5,8 @@# Лекция 06. Инициализируйте проект перед каждой сессией агента+> Инженерные ориентиры: числа — настраиваемые учебные значения, не доказанные пороги. Количество токенов зависит от токенизатора и содержания, не только строк.+Вы открываете новую сессию агента и говорите «добавь поиск». Он сразу бросается писать код — похвальный энтузиазм. Через 20 минут он обнаруживает, что тестовый фреймворк настроен неправильно, тратит ещё 10 минут на починку, потом оказывается, что формат скрипта миграции неверен, ещё возня. Поиск в итоге добавлен, но вся сессия прошла неэффективно — большая часть времени ушла на «разбирательство, как устроен этот проект», а не на саму фичу.Лучший подход: прежде чем дать агенту начать работу, в отдельной фазе подготовьте базовое окружение, рабочие команды верификации и понимание структуры проекта. Это как строить дом — нельзя одновременно заливать фундамент и поднимать стены. Если так сделать, стены пойдут вверх, пока фундамент не схватился, и всё здание придётся сносить и начинать заново. Залейте фундамент, дайте ему встать, потом стройте стены — чисто и эффективно.@@ -37,6 +39,8 @@ flowchart TB## Что происходит, когда вы их смешиваете+> Учебная иллюстрация: сценарий и его числа являются поясняющими допущениями, не измерениями опубликованного эксперимента.+Самая прямая проблема: фундамент не схватывается как следует. Агент тратит 80% усилий на код фич и 20% — на кое-как настроенную инфраструктуру. Тестовый фреймворк настроен, но не проверен; правила линтера выставлены, но слишком слабые; файл прогресса не создан. Эти дефекты не очевидны в первой сессии (агент ещё помнит, что делал), но проявляются во второй — новый агент не знает, как запускать, как тестировать и где сейчас находится проект. Хлипкий фундамент — шаткое здание.Более скрытая стоимость — «непроверенное накопление»: код фич, написанный до настройки тестового фреймворка, — это код без верификации. Когда вы наконец возвращаетесь добавить тесты к этому коду, вы можете обнаружить, что архитектура была неверной с самого начала — знай вы это, реализовали бы иначе. Это как класть плитку на сырой бетон: когда обнаруживаете, что пол неровный, всю плитку приходится отдирать и переделывать.@@ -45,7 +49,7 @@ flowchart TBСамая легко упускаемая проблема — «мины» неявных предположений. Решения, принимаемые агентом во время инициализации (какой тестовый фреймворк, как организовать каталоги, как управлять зависимостями), — если их явно не записать, последующие сессии не смогут их понять. Хуже того, последующие сессии могут принять противоречащие решения. Первая бригада сделала бетонный фундамент, вторая бригада об этом не знала и забила в него деревянные сваи — фундамент трескается.-В исследовании long-running разработки приложений Anthropic явно рекомендует отделять инициализацию от реализации. Их экспериментальные данные: проекты с выделенной фазой инициализации показывали на 31% более высокую долю завершённых фич в многосессионных сценариях по сравнению со смешанным подходом. Ключевая мысль — время, вложенное в фазу инициализации, полностью окупается в следующих 3–4 сессиях. Чем крепче фундамент, тем быстрее идут стены.+[Anthropic: initializer / coding agent](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)Руководство OpenAI Codex по harness engineering тоже подчёркивает принцип «репозиторий как операционный журнал»: с первого запуска нужно установить ясную операционную структуру, иначе каждая новая сессия будет вынуждена заново выводить соглашения проекта.@@ -122,7 +126,9 @@ flowchart TB- [ ] Everything committed to git```-## Пример из реальной практики+## Учебный пример++> Учебная иллюстрация: сценарий и его числа являются поясняющими допущениями, не измерениями опубликованного эксперимента.Два подхода к инициализации фронтенд-проекта на React: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.mdindex 5c74c66..4520d7b 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@@ -5,6 +5,8 @@# Лекция 07. Очерчивайте чёткие границы задач для агентов+> Инженерные ориентиры: числа — настраиваемые учебные значения, не доказанные пороги. Количество токенов зависит от токенизатора и содержания, не только строк.+Вы говорите Claude Code: «добавь в проект аутентификацию пользователей», и он начинает менять схему БД, писать маршруты, переделывать фронтенд-компоненты и заодно — рефакторить middleware обработки ошибок. Через два часа вы проверяете: 12 файлов изменено, 800 строк нового кода, и ни одна фича не работает сквозно.Откусил больше, чем сможешь прожевать — эта поговорка отлично подходит к AI-агентам. У агентов врождённый импульс «сделать чуть больше» — они видят что-то связанное и заодно это правят, как тот, кто пошёл в магазин за бутылкой соевого соуса и вышел с полной тележкой. Проблема в том, что человек, который купил лишнего, всего лишь потратил деньги; агент, делающий слишком много дел одновременно, не доводит до конца ни одного.@@ -26,7 +28,7 @@Шесть шагов спустя — каждый сделан наполовину. Никакой сквозной верификации, сложная связанность между полу-готовыми кусками кода, и следующая сессия, которая попробует это разобрать, окончательно потеряется. Как тот, кто готовит шесть блюд одновременно: каждое в сковородке, но ни одно не выложено на тарелку. Все подгорают.-Экспериментальные данные Anthropic прямо это подтверждают: агенты, использующие стратегию «маленький следующий шаг» (эквивалентно WIP=1), показывают на 37% более высокую долю завершённых задач, чем агенты с широкими промптами. Что интереснее, число строк кода, генерируемых агентами, слабо отрицательно коррелирует с реальным завершением фич — больше написанного кода, меньше доведённых до конца фич. Откусил больше, чем прожуёшь — подтверждено данными.+[Anthropic: incremental feature work](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## Рабочий процесс WIP=1@@ -100,7 +102,9 @@ F01: User RegistrationHarness должен непрерывно отслеживать VCR (Verified Completion Rate) = проверенные задачи / активированные задачи. Блокируйте активацию новых задач, когда VCR < 1.0.-## Пример из реальной практики+## Учебный пример++> Учебная иллюстрация: сценарий и его числа являются поясняющими допущениями, не измерениями опубликованного эксперимента.Проект REST API с 8 фичами, сравниваются две стратегии: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.mdindex 747d700..2a32b10 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@@ -5,6 +5,8 @@# Лекция 08. Используйте списки фич, чтобы ограничивать поведение агента+> Инженерные ориентиры: числа — настраиваемые учебные значения, не доказанные пороги. Количество токенов зависит от токенизатора и содержания, не только строк.+Вы просите агента построить интернет-магазин. Когда он закончил, он говорит «готово». Вы смотрите код — аутентификация работает, но кнопка оформления заказа в корзине ничего не делает, а оплата вообще не подключена. Проблема: вы никогда не сказали, что значит «готово», поэтому он использовал свой собственный стандарт — «я написал много кода, и он выглядит достаточно полным».Список фич, в глазах многих, — просто памятка: записал, чтобы не забыть, и отложил. Но в мире harness'а список фич — не памятка для людей, а позвоночник всего harness'а. Планировщик опирается на него, чтобы выбирать задачи; верификатор — чтобы судить о завершении; репортёр handoff — чтобы генерировать саммари. Сломайте позвоночник — и тело парализовано.@@ -22,7 +24,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)## Конечный автомат фичи@@ -103,7 +105,9 @@ flowchart LRКаждая запись фичи должна быть масштаба «можно завершить за одну сессию». Слишком широко — не закончится; слишком узко — растёт накладной расход на управление. «Пользователь может добавить товар в корзину» — хорошая гранулярность. «Реализовать корзину» — слишком широко. «Создать поле name в модели Cart» — слишком узко. Как нарезать стейк — не цельным куском и не фаршем.-## Пример из реальной практики+## Учебный пример++> Учебная иллюстрация: сценарий и его числа являются поясняющими допущениями, не измерениями опубликованного эксперимента.Платформа e-commerce с 10 фичами. Сравниваются два подхода к учёту:@@ -111,8 +115,6 @@ flowchart LR**Режим позвоночника**: у каждой фичи чёткое состояние и команда верификации. Новая сессия читает список фич и за 3 минуты знает: F01–F05 — `passing`, F06 — `active`, F07–F10 — `not_started`. Сразу подхватывает с F06, никаких переделок.-Количественно: проекты со структурированными списками фич показывают на 45% более высокую долю завершения по сравнению со свободной формой учёта, при нулевом дублировании реализаций.-## Главные выводы- **Списки фич — позвоночник harness'а**, а не памятки для людей. Планировщик, верификатор и репортёр handoff все зависят от них.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.mdindex e0dc7a2..1fb767b 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@@ -5,6 +5,8 @@# Лекция 09. Предотвращение преждевременных заявлений о завершении+> Инженерные ориентиры: числа — настраиваемые учебные значения, не доказанные пороги. Количество токенов зависит от токенизатора и содержания, не только строк.+Вы просите агента реализовать функцию «сброс пароля». Он изменяет схему базы данных, пишет API-эндпоинт, добавляет email-шаблон, запускает юнит-тесты (все проходят) и уверенно сообщает: «готово». Когда вы реально пытаетесь это запустить — ссылка сброса пароля не отправляется (отсутствует конфигурация email-сервиса), миграция базы данных падает на середине (несогласованность схемы), а сквозной поток ни разу не выполнялся.Это чувство не должно быть незнакомым — это как заполнить всю экзаменационную работу, уверенно сдать её первым и затем провалиться при выставлении оценок. То, что работа заполнена, не значит, что ответы правильные.@@ -13,6 +15,8 @@## Скользкий склон+> Модель и запрос одинаковые, но бюджеты времени и стоимости различаются. Это не равнобюджетный эксперимент, изолирующий один компонент. Основная игра работала, но дефекты оставались. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)+Преждевременные заявления о завершении почти всегда следуют одному паттерну: код выглядит нормально — синтаксис правильный, логика кажется разумной, статический анализ не показывает очевидных ошибок. Но harness не обеспечивает комплексной верификации выполнения, поэтому агент пропускает реальный запуск или запускает только часть тестов. Он запускает юнит-тесты, но пропускает интеграционные; запускает тесты, но не проверяет покрытие. В итоге «код выглядит нормально» принимается как доказательство того, что «фича завершена». И экзаменационная работа сдаётся.На каждом шаге теряется информация. От спецификации задачи к реализации кода к runtime-поведению — каждое преобразование может внести искажение, и каждая пропущенная верификация усугубляет информационную асимметрию.@@ -111,7 +115,9 @@ OpenAI внедрила особенно эффективный паттерн- Были ли корректными записи в БД, файловые операции и другие побочные эффекты?- Были ли очищены временные ресурсы?-## Реальный кейс+## Учебный пример++> Учебная иллюстрация: сценарий и его числа являются поясняющими допущениями, не измерениями опубликованного эксперимента.**Задача**: Реализовать функциональность сброса пароля пользователя. Включает операции с базой данных, отправку email и модификацию API-эндпоинтов.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.mdindex 4d6707a..be5c7c3 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@@ -5,6 +5,8 @@# Лекция 10. Только сквозное тестирование — настоящая верификация+> Инженерные ориентиры: числа — настраиваемые учебные значения, не доказанные пороги. Количество токенов зависит от токенизатора и содержания, не только строк.+Вы просите агента добавить функцию экспорта файлов в Electron-приложение. Он пишет компонент процесса рендеринга, preload-скрипт и логику сервисного слоя. Юнит-тесты каждого компонента проходят идеально. Агент говорит: «Готово». Когда вы реально нажимаете кнопку экспорта — формат файлового пути неправильный, прогресс-бар не обновляется, а экспорт больших файлов вызывает утечку памяти. Пять дефектов на границах компонентов, и юнит-тесты не поймали ни одного.Это как репетиция хора — каждая партия звучит идеально по отдельности, но когда поют вместе, сопрано на полбита быстрее басов, а аккомпанемент на полтона расходится с основной мелодией. Каждая часть «правильна» сама по себе, но整体 — фальшиво.@@ -116,7 +118,9 @@ FIX: Перенесите файловые операции в src/preload/file-Каждый раз, когда обнаруживается новый тип ошибки агента при code review, превратите его в автоматизированную проверку. Через месяц ваш harness будет значительно сильнее, чем в начале месяца. Как заметки к репетиции хора — запись проблем, найденных на каждой репетиции, для проверки перед следующей. Со временем типичные ошибки уменьшаются, и музыка становится гармоничнее.-## Реальный кейс+## Учебный пример++> Учебная иллюстрация: сценарий и его числа являются поясняющими допущениями, не измерениями опубликованного эксперимента.**Задача**: Реализовать функцию экспорта файлов в Electron-приложении. Включает UI процесса рендеринга, прокси файловой системы preload-скрипта и трансформацию данных сервисного слоя.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.mdindex da9668f..b7a2aa5 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@@ -32,7 +32,9 @@ flowchart LRVerdict --> Generator```-## Почему так происходит+## Учебный пример++> Учебная иллюстрация: сценарий и его числа являются поясняющими допущениями, не измерениями опубликованного эксперимента.### Реальная цена отсутствия наблюдаемости@@ -44,7 +46,7 @@ flowchart LR**Ретраи превращаются в слепые догадки**: когда агент не знает, почему что-то не сработало, направление ретрая случайно. Он может многократно пытаться в неверном направлении — чинить несвязанные пути кода, игнорируя реальную корневую причину сбоя. Каждый слепой ретрай стоит токенов и времени.-**Информационный обрыв при передаче сессии**: когда незавершённая работа передаётся следующей сессии, отсутствие наблюдаемости означает, что новая сессия должна диагностировать состояние системы с нуля. Наблюдения Anthropic за долгоработающими агентами показывают, что эта избыточная диагностика может съедать 30–50% общего времени сессии.+Записывайте прогресс и проверки в версионируемые файлы, чтобы следующая сессия могла проверить состояние. Источник описывает механизм без процентного сокращения времени запуска. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)### Реальный сценарий с Claude Code@@ -116,7 +118,9 @@ flowchart LRСоздавайте трейс для каждой сессии harness, span для каждой задачи и саб-span для каждого шага верификации. Используйте стандартные атрибуты для аннотации ключевой информации. Так данные наблюдаемости интегрируются со стандартными цепочками инструментов (Jaeger, Zipkin).-## Реальный кейс+## Учебный пример++> Учебная иллюстрация: сценарий и его числа являются поясняющими допущениями, не измерениями опубликованного эксперимента.Harness, использующий воркфлоу «планировщик-генератор-оценщик», выполняющий задачу «добавить поддержку тёмной темы»:@@ -136,7 +140,7 @@ Harness, использующий воркфлоу «планировщик-ге- **Оба слоя наблюдаемости обязательны** — рантайм-сигналы объясняют «что произошло», процессные артефакты объясняют «почему это сделано именно так».- **Sprint contracts заранее выравнивают понимание** — предотвращают ситуации, когда «генератор построил то, что оценщик сразу отвергает по предсказуемым причинам».- **Балльные рубрики делают оценку воспроизводимой** — разные оценщики выдают схожие баллы для одного и того же выхода.-- **Отсутствие наблюдаемости тратит 30–50% времени сессии на избыточную диагностику.**+- Записывайте прогресс и проверки в версионируемые файлы, чтобы следующая сессия могла проверить состояние. Источник описывает механизм без процентного сокращения времени запуска.## Дополнительное чтение@@ -151,4 +155,4 @@ Harness, использующий воркфлоу «планировщик-ге2. **Практика Sprint Contract**: напишите sprint contract для реальной задачи. Заставьте агента выполнить её согласно контракту и сравните эффективность и качество с контрактом и без него.-3. **Построение трейса задачи**: запишите каждый шаг операций агента в течение полной задачи кодинга. Аннотируйте семантическими конвенциями OpenTelemetry. Проанализируйте узкие места информации в трейсе — на каких шагах не хватает достаточных сигналов для решений.\ No newline at end of file+3. **Построение трейса задачи**: запишите каждый шаг операций агента в течение полной задачи кодинга. Аннотируйте семантическими конвенциями OpenTelemetry. Проанализируйте узкие места информации в трейсе — на каких шагах не хватает достаточных сигналов для решений.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.mdindex 58390cb..2069eee 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@@ -5,6 +5,8 @@# Лекция 12. Чистая передача в конце каждой сессии+> Инженерные ориентиры: числа — настраиваемые учебные значения, не доказанные пороги. Количество токенов зависит от токенизатора и содержания, не только строк.+## Какую проблему решает эта лекция?Ваш агент работает весь день, меняет 20 файлов, коммитит код, сессия заканчивается. Следующая сессия агента стартует и сразу обнаруживает: сборка сломана, тесты красные, повсюду временные дебаг-файлы, список фич не обновлён, прогресс совершенно неясен. Новая сессия тратит первые 30 минут просто на выяснение «что вообще делала прошлая сессия».@@ -54,6 +56,8 @@ flowchart LRЗаконы эволюции ПО Лемана говорят нам: системы, подвергающиеся непрерывным изменениям, неизбежно усложняются, если ими активно не управлять. Это особенно верно для AI-агентов кодинга — каждая сессия вносит изменения, и без очистки на выходе технический долг накапливается экспоненциально.+> Учебная иллюстрация: сценарий и его числа являются поясняющими допущениями, не измерениями опубликованного эксперимента.+Реальные данные красноречивы. Проект, разрабатывавшийся с агентами 12 недель без стратегии очистки:- Неделя 1: успех сборки 100%, успех тестов 100%, запуск новой сессии 5 мин@@ -66,8 +70,6 @@ flowchart LR- Неделя 1: 100%, 100%, 5 мин- Неделя 12: 97%, 95%, 9 мин-После 12 недель: успех сборки отличается на 29 процентных пунктов, время запуска новой сессии — на 85%. Это не теория — это наблюдаемая разница.-### Пять измерений чистого состоянияЧистое состояние — это не просто «код собирается». Это пять измерений, оцениваемых вместе:@@ -76,7 +78,7 @@ flowchart LR**Измерение тестов**: проходят ли все тесты? Включая тесты, существовавшие до сессии — сессия отвечает за то, чтобы не сломать существующую функциональность. И это должно быть проверено в CI, а не только «работает у меня на машине».-**Измерение прогресса**: зафиксирован ли текущий прогресс в машиночитаемом артефакте? Завершённые подзадачи с критериями их прохождения, начатые, но незавершённые подзадачи с текущим состоянием, ещё не начатые подзадачи. Хорошие записи прогресса сокращают 60–80% времени диагностики при старте сессии.+Записывайте прогресс и проверки в версионируемые файлы, чтобы следующая сессия могла проверить состояние. Источник описывает механизм без процентного сокращения времени запуска. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)**Измерение артефактов**: есть ли устаревшие или неоднозначные временные артефакты? Дебаг-логи, временные файлы, закомментированный код, TODO-маркеры — всё это увеличивает когнитивную нагрузку для следующей сессии.@@ -152,7 +154,9 @@ git checkout -- .env.local # Restore to known statenpm run test # Verify cleanup didn't break anything```-## Реальный кейс+## Учебный пример++> Учебная иллюстрация: сценарий и его числа являются поясняющими допущениями, не измерениями опубликованного эксперимента.Electron-приложение, разрабатываемое с агентами 12 недель, сравнение двух подходов:@@ -160,8 +164,6 @@ Electron-приложение, разрабатываемое с агентам**Со стратегией очистки** (экспериментальная группа): полная проверка чистого состояния в конце каждой сессии + еженедельный cleanup loop. Неделя 12, успех сборки 97%, успех тестов 95%, запуск новой сессии 9 мин, устаревших артефактов 11.-К 12-й неделе у экспериментальной группы успех сборки выше на 29 процентных пунктов, успех тестов — на 34 пункта, время запуска новой сессии ниже на 85%.-## Ключевые выводы- **Чистое состояние — необходимое условие завершения сессии** — не опциональная уборка, а часть «definition of done».@@ -183,4 +185,4 @@ Electron-приложение, разрабатываемое с агентам2. **Сравнение бенчмарков**: используйте фиксированный набор задач с двумя вариантами harness (с требованиями чистого состояния и без). Сравните долю завершённых, число ретраев и долю просочившихся дефектов.-3. **Практика упрощения harness**: выберите один компонент harness, временно отключите его и прогоните бенчмарк-задачи. Сравните результаты с ним и без него. Решите, оставить, удалить или заменить.\ No newline at end of file+3. **Практика упрощения harness**: выберите один компонент harness, временно отключите его и прогоните бенчмарк-задачи. Сравните результаты с ним и без него. Решите, оставить, удалить или заменить.diff --git a/docs/ru/lectures/lecture-13-loop-engineering/index.md b/docs/ru/lectures/lecture-13-loop-engineering/index.mdindex f09467f..8e87cf1 100644--- a/docs/ru/lectures/lecture-13-loop-engineering/index.md+++ b/docs/ru/lectures/lecture-13-loop-engineering/index.md@@ -5,6 +5,8 @@# Лекция 13. От ручных запросов к автономным циклам+> Инженерные ориентиры: числа — настраиваемые учебные значения, не доказанные пороги. Количество токенов зависит от токенизатора и содержания, не только строк.+Всё, что вы изучили в первых двенадцати лекциях, основано на одном предположении: **вы сидите за клавиатурой и вводите инструкции одну за другой.**Вы написали `AGENTS.md` (лекции 1–4), построили управление состоянием (лекции 5–6), ограничили область применения списками функций (лекции 7–8), оставляли чистые передачи в конце сессии (лекции 9, 12) и сделали среду выполнения наблюдаемой (лекции 10–11). Но триггером для всего этого всегда были вы. Агент никогда не решал сам, когда начинать работать — потому что никто не нажимал «старт».@@ -84,8 +86,12 @@ Loop Engineering, тема этой лекции — не о какой-то оВам не нужно каждый раз вводить `/goal`. Но понимание того, откуда она взялась и почему выглядит именно так — это понимание ядра loop engineering. Более сложные циклы просто добавляют такие части, как планирование, параллелизм, изоляция и память, поверх этих же трёх основ: цель, верификация, условие остановки.+> Учебная иллюстрация: сценарий и его числа являются поясняющими допущениями, не измерениями опубликованного эксперимента.+## Июнь 2026: Три человека зажгли один и тот же фитиль за одну неделю+> Учебная иллюстрация: сценарий и его числа являются поясняющими допущениями, не измерениями опубликованного эксперимента.+В первую неделю июня 2026 года три практика, строящих инфраструктуру для кодовых агентов — не обмениваясь заметками — сказали одно и то же разными словами.**Питер Стайнбергер** (создатель OpenClaw, [его пост набрал 8 миллионов просмотров](https://x.com/steipete/status/2063697162748260627)): «Вы больше не должны делать запросы к кодовым агентам. Вы должны проектировать циклы, которые делают запросы к вашим агентам.»@@ -96,7 +102,13 @@ Loop Engineering, тема этой лекции — не о какой-то о> **Loop engineering — это замена себя как человека, который делает запросы к агенту. Вы проектируете систему, которая делает это вместо вас.**-Черный сообщил цифры: более 30 дней подряд все вклад кода в Claude Code вносились автономно ИИ — 259 слитых PR, более 80% производственного кода, написанного Claude, и 76% успеха в открытых программных задачах.+Boris Cherny · 2025-12-27++| PR | Git commits | + LoC | − LoC | Model |+| --- | --- | --- | --- | --- |+| 259 / 30 days | 497 | 40,000 | 38,000 | Claude Code + Opus 4.5 |++Личный результат, сообщённый автором, не показатель benchmark и не доказательство отсутствия человеческого контроля. [Boris Cherny](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)Три человека. Одна неделя. Один и тот же вывод. Не потому, что они скоординировались — а потому, что инфраструктура тихо пересекла порог. Агенты стали достаточно надёжными, чтобы завершать нетривиальные задачи без присмотра. Примитивы планирования (`/loop`, `/goal`, cron) теперь встроены в инструменты. Стоимость одного запуска агента упала достаточно низко, чтобы запускать его повторно по таймеру перестало выглядеть расточительным. Когда все части на месте, шаг, который их объединяет, становится очевидным для всех сразу.@@ -267,7 +279,7 @@ flowchart TDЭто уже не один запуск агента. Это непрерывно работающая система, которая просыпается каждое утро, сама убирает пол и ставит то, что требует вашего внимания, перед вами. Ваша роль становится такой: **проверять содержимое входящих, принимать решения и, когда вы замечаете закономерность, с которой система не может справиться, уточнять навыки и правила.**-Черный использовал этот паттерн, чтобы слить 259 PR за 30 дней, ни разу не открыв IDE. Инженеры OpenAI использовали тот же паттерн, чтобы построить бета-продукт примерно на миллион строк — без написания ни одной строки кода самими.+Личный результат, сообщённый автором, не показатель benchmark и не доказательство отсутствия человеческого контроля.## Разделение генератора и оценщика: Почему нельзя позволять модели проверять свою собственную работу@@ -293,7 +305,7 @@ flowchart TDЕсли вы хотите увидеть, как выглядит хорошо спроектированный, реально работающий цикл — [autoresearch Карпати](https://github.com/karpathy/autoresearch) это учебный пример.-В марте 2026 года Карпати выпустил 630-строчный Python-проект. Дайте ему один GPU и направление исследований, и он работает всю ночь — выполняя сотни экспериментов ML-обучения, сохраняя только те, которые действительно улучшают результат. Проект набрал 66 000+ звёзд в течение дней после релиза.+[Karpathy: autoresearch](https://github.com/karpathy/autoresearch) · [announcement](https://x.com/karpathy/status/2030371219518931079)### Три файла, три роли@@ -343,8 +355,6 @@ flowchart TD8b --> 9```-Он выполняет примерно 12 экспериментов в час. Ночная сессия (8 часов) — это около 100 экспериментов. Сам Карпати запускал его 2 дня — ~700 экспериментов.-Фиксированный 5-минутный бюджет реального времени — ключевой дизайнерский выбор: независимо от того, что агент меняет, каждый эксперимент занимает ровно столько же времени. Это означает, что все результаты напрямую сравнимы при одинаковом бюджете времени — без споров о «этот запускался дольше, поэтому он лучше».### Вывод: Что вы видите, когда просыпаетесь@@ -359,6 +369,8 @@ flowchart TDКаждый отдельный эксперимент — успех или неудача — логируется:+> Учебная иллюстрация: сценарий и его числа являются поясняющими допущениями, не измерениями опубликованного эксперимента.+```timestamp commit_hash val_bpb vram_mb description--------- ------------- ---------- ---------- ----------------------------@@ -375,11 +387,10 @@ timestamp commit_hash val_bpb vram_mb description### Что он реально нашёл-Результаты начального 2-дневного запуска Карпати с ~700 экспериментами:+- Время обучения nanochat на уровне GPT-2 на 8×H100 сократилось с **2,02 часа → 1,80 часа**, примерно **на 10.89% быстрее**+- Находки включали: корректировки скорости обучения, тюнинг оптимизатора, замены активации, оптимизации паттернов внимания и т.д. [Karpathy: leaderboard commit](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b) · [tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)-- Из ~700 попыток было найдено примерно **20 складывающихся реальных улучшений**-- Время обучения nanochat на уровне GPT-2 на 8×H100 сократилось с **2,02 часа → 1,80 часа**, примерно **на 11% быстрее**-- Находки включали: корректировки скорости обучения, тюнинг оптимизатора, замены активации, оптимизации паттернов внимания и т.д.+> Учебная иллюстрация: сценарий и его числа являются поясняющими допущениями, не измерениями опубликованного эксперимента.Все ли улучшения были потрясающими открытиями? Нет. Большинство были небольшими оптимизациями, которые складывались вместе. Но эти 20 действительных улучшений заняли бы у человеческого исследователя недели ручной работы — агент сделал это за 48 часов.@@ -399,7 +410,7 @@ timestamp commit_hash val_bpb vram_mb description### 2. Деградация понимания-Чем быстрее цикл поставляет код, тем дальше ваше понимание собственной кодовой базы уходит от реальности. У команды Черного 80% кода было написано агентами — что означает, что большая часть кода команды не была написана человеком. Если вы не читаете и не используете то, что производит цикл, ваше понимание непрерывно деградирует. **Быстрые циклы требуют быстрого чтения.**+Производственные результаты не изолируют одну причину. Оценки относятся к указанным модели, scaffold, данным и условиям, не к любой реальной задаче.### 3. Когнитивная капитуляцияdiff --git a/docs/ru/lectures/lecture-14-graph-engineering/index.md b/docs/ru/lectures/lecture-14-graph-engineering/index.mdindex 120703e..67faa81 100644--- a/docs/ru/lectures/lecture-14-graph-engineering/index.md+++ b/docs/ru/lectures/lecture-14-graph-engineering/index.md@@ -261,7 +261,7 @@ run(graph, entry={"requirements": "исправить баг на страниц**Появившиеся после релиза концепции**-- [GraphArc](https://github.com/CodeGraphContext/grapharc) (2026-08-02): позиционирует себя как «первую живую реализацию Graph Engineering». Он превращает исполнение агентов из trace, зарытого в логах, в **интерактивный оркестрационный граф в реальном времени** — каждый агент, каждая зависимость, каждая точка принятия решения нарисованы, вся картина визуализируется до исполнения, и вы подтверждаете (можно даже с телефона) перед тем, как он даст добро. Автор по опыту делал графовые инструменты для 4000+ разработчиков, направление — «наблюдаемость, отлаживаемость, инженеризируемость». Совсем свежий, функциональность ещё ранняя.+- [GraphArc](https://github.com/CodeGraphContext/grapharc)**Существовавшие до релиза концепции (они не называются Graph Engineering, но именно их вы будете использовать при сборке)**@@ -346,4 +346,4 @@ run(graph, entry={"requirements": "исправить баг на страниц4. **Оценка по пяти критериям:** возьмите задачу, которую вы никак не решите, «графизировать» ли её, и оцените её по пяти критериям. Рисовать стоит, если выполнены хотя бы три. Если меньше трёх — ей нужен просто лучший workflow-скрипт; не используйте граф ради использования графа.-5. **Превратите graph.md в исполняемую программу:** по шести шагам из раздела «Построение вашего первого графа с нуля» реализуйте нарисованный вами maker-checker граф как запускаемый граф (эталонная реализация: `code/maker_checker_graph.py`, написан на LangGraph). Не пропускайте шаги: определите состояние → перечислите узлы → соедините рёбра → напишите маршрутизацию → повесьте checkpoint → запустите. После запуска сверьте `graph.md` и код, найдите первое несоответствие и объясните, почему оно возникло — граф нарисован неверно или код написан неверно?\ No newline at end of file+5. **Превратите graph.md в исполняемую программу:** по шести шагам из раздела «Построение вашего первого графа с нуля» реализуйте нарисованный вами maker-checker граф как запускаемый граф (эталонная реализация: `code/maker_checker_graph.py`, написан на LangGraph). Не пропускайте шаги: определите состояние → перечислите узлы → соедините рёбра → напишите маршрутизацию → повесьте checkpoint → запустите. После запуска сверьте `graph.md` и код, найдите первое несоответствие и объясните, почему оно возникло — граф нарисован неверно или код написан неверно?diff --git a/docs/ru/resources/reference/index.md b/docs/ru/resources/reference/index.mdindex e2203ca..0b9d437 100644--- a/docs/ru/resources/reference/index.md+++ b/docs/ru/resources/reference/index.md@@ -13,6 +13,11 @@- [On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents](https://arxiv.org/html/2601.20404v2): gpt-5.2-codex; 10 repos / 124 PR tasks; Table 1.+- [Anthropic: Sonnet 4.5 — SWE-bench Verified methodology (2025-09-29)](https://www.anthropic.com/news/claude-sonnet-4-5)+- [Boris Cherny: personal 30-day production report (2025-12-27)](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)+- [Karpathy: measured autoresearch leaderboard improvement](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b)+- [Karpathy: two-day autonomous tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)+## Рекомендуемый порядок чтения1. `method-map.md`diff --git a/docs/tr/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/tr/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex 10712c7..b732c15 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,17 +9,30 @@ 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.+Claude Sonnet 4.5 · 2025-09-29 · SWE-bench Verified++| Score | Tasks | Trials | Scaffold |+| --- | --- | --- | --- |+| 77.2% | 500 | 10 | bash + string replacement |++Üretim sonuçları tek nedeni ayırmaz. Benchmark skorları belirtilen model, scaffold, veri ve değerlendirme koşulları içindir. [Anthropic: methodology](https://www.anthropic.com/news/claude-sonnet-4-5)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.+> Model ve prompt aynı, zaman ve maliyet bütçeleri farklıdır. Tek bileşeni ayıran eşit bütçeli deney değildir. Temel oyun çalıştı, fakat hatalar kaldı. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++Model ve prompt aynı, zaman ve maliyet bütçeleri farklıdır. Tek bileşeni ayıran eşit bütçeli deney değildir. Temel oyun çalıştı, fakat hatalar kaldı. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++| Opus 4.5 | Duration | USD |+| --- | --- | --- |+| Solo | 20 min | 9 |+| Full harness | 6 h | 200 |Modeli değiştirmediler. Opus 4.5 yine Opus 4.5'ti. Değişen şey koşum takımıydı.-OpenAI'nin 2025 harness mühendisliği makalesi bunu açıkça söylüyor: iyi bir harness'a sahip bir depoda Codex "güvenilmez"den "güvenilir"e geçiyor. İfadeye dikkat edin — "biraz daha iyi" değil, niteliksel bir sıçrama. Tıpkı safkan bir at gibi: doğru koşum takımı olmadan binebilirsiniz ama uzağa gidemezsiniz, hızlı gidemezsiniz, düşmek de sürpriz olmaz. Harness işte o tam koşum takımıdır — **model ağırlıkları dışındaki tüm mühendislik altyapısı.**+Üretim sonuçları tek nedeni ayırmaz. Benchmark skorları belirtilen model, scaffold, veri ve değerlendirme koşulları içindir. [OpenAI: 2026-02-11](https://openai.com/index/harness-engineering/)## Ajanlar gerçekte nerede takılıyor@@ -39,9 +52,9 @@ Birden fazla oturuma yayılan uzun görevler daha da kötüdür — önceki oturBu senaryolar göz önünde bulundurulduğunda bu kavramlar artık sadece jargon değil:-- **Yetenek farkı (Capability Gap)**: Modelin benchmark performansı ile gerçek görev performansı arasındaki büyük uçurum. SWE-bench Verified üzerindeki %50-60 başarı oranı, gerçek sorunların neredeyse yarısının çözülemediği anlamına gelir.+- Üretim sonuçları tek nedeni ayırmaz. Benchmark skorları belirtilen model, scaffold, veri ve değerlendirme koşulları içindir.- **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.- **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,17 +85,19 @@ 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.+Üretim sonuçları tek nedeni ayırmaz. Benchmark skorları belirtilen model, scaffold, veri ve değerlendirme koşulları içindir. [OpenAI: 2026-02-11](https://openai.com/index/harness-engineering/)-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ı.+Üretim sonuçları tek nedeni ayırmaz. Benchmark skorları belirtilen model, scaffold, veri ve değerlendirme koşulları içindir.Erken ilerleme beklenenden daha yavaştı. Codex yetersiz olduğu için değil, ortam yeterince eksiksiz olmadığı için — ajanın üst düzey hedefleri ilerletmek için gerekli araçlardan, soyutlamalardan ve dahili yapılardan yoksun olmasıydı. Mühendislerin işi şuna dönüştü: büyük hedefleri küçük yapı taşlarına bölmek (tasarım, kod, inceleme, test), ajanın bunları birleştirmesine izin vermek, ardından bu blokları daha karmaşık görevleri açmak için kullanmak. Bir şey başarısız olduğunda, düzeltme neredeyse hiçbir zaman "daha fazla dene" değildi — "ajanın hangi yetenekten yoksun olduğu ve bunu hem anlaşılır hem de yürütülebilir kılmak için ne yapabiliriz?" idi.-Bu deney bu dersin temel tezini doğrudan kanıtlıyor: **aynı model çıplak bir ortamda ve eksiksiz bir harness ile temelden farklı çıktı üretir.** Model değişmedi. Ortam değişti.+Üretim sonuçları tek nedeni ayırmaz. Benchmark skorları belirtilen model, scaffold, veri ve değerlendirme koşulları içindir.> Kaynak: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)-## Daha somut bir örnek+## Öğretim örneği++> Öğretim örneği: senaryo ve sayılar açıklama için varsayılmıştır, yayımlanmış deney ölçümleri değildir.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ı.@@ -108,6 +123,8 @@ Modeli değiştirmediler. Harness'ı değiştirdiler.- [SWE-bench Liderlik Tablosu](https://www.swebench.com/)- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)+- [Anthropic: Sonnet 4.5 SWE-bench methodology, 2025-09-29](https://www.anthropic.com/news/claude-sonnet-4-5)+## Alıştırmalar1. **Karşılaştırma deneyi**: İyi tanıdığınız bir kod tabanı ve önemsiz olmayan bir değişiklik görevi seçin. Önce ajanı harness desteği olmadan çalıştırın ve başarısızlıkları kaydedin. Sonra açık doğrulama komutları içeren bir `AGENTS.md` ekleyin ve aynı ajanla tekrar çalıştırın. Sonuçları karşılaştırın, her başarısızlığı beş savunma katmanından birine atfedin.diff --git a/docs/tr/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/tr/lectures/lecture-02-what-a-harness-actually-is/index.mdindex 46c73a9..2c764fe 100644--- a/docs/tr/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/tr/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -70,7 +70,9 @@ Herhangi bir alt sistemin eksikliği mutfakta bir işlevsel alanın eksikliği g**Harness bileşen değerini ölçme**: Modeli sabit tutan bir bileşen çıkarma deneyi kullanın. Modeli sabit tutun, alt sistemleri tek tek kaldırın ve hangisinin kaldırılmasının en büyük performans düşüşüne neden olduğunu ölçün. En büyük düşüş, o görevde marjinal katkısı en yüksek olan bileşeni belirler; darboğazı otomatik olarak belirlemez. Neredeyse sıfır düşüş de yorum gerektirir: bileşen gereksiz olabilir, kötü tasarlanmış olabilir veya bu görev tarafından yeterince tetiklenmemiş olabilir. Darboğazları teşhis etmek için önce başarısızlık günlükleri ve atıfları kullanın, çıkarma deneyini ise destekleyici kanıt olarak ele alın: başarısızlık belirsiz görev niyetinden mi, yetersiz bağlamdan mı, yeniden üretilemeyen ortamdan mı, eksik doğrulama geri bildiriminden mi, yoksa bozuk durum yönetiminden mi kaynaklandı?-## Bir takımın gerçek hikâyesi+## Öğretim örneği++> Öğretim örneği: senaryo ve sayılar açıklama için varsayılmıştır, yayımlanmış deney ölçümleri değildir.Bir takım TypeScript + React frontend uygulamasında (~20.000 satır kod) GPT-4o kullandı. Dört aşamadan geçtiler — esasen mutfak ekipmanını parça parça eklemek:diff --git a/docs/tr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/tr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdindex 370051f..2ba3e2d 100644--- a/docs/tr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md+++ b/docs/tr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -5,6 +5,8 @@# Ders 03. Depo neden kayıt sistemi olmalı+> Mühendislik önerisi: sayısal eşikler ayarlanabilir öğretim değerleridir, deneysel sınırlar değildir. Token sayısı yalnız satıra değil tokenizer ve içeriğe bağlıdır.+Takımınızın mimari kararları Confluence, Slack, Jira ve birkaç kıdemli mühendisin kafasına dağılmış durumda. İnsanlar için bu zar zor işe yarar — bir meslektaşa sorabilirsiniz, sohbet geçmişini arayabilirsiniz, dokümanları kazıyabilirsiniz. Tüm bunlar başarısız olursa, birini mola odasında köşeye sıkıştırabilirsiniz. Ancak bir AI ajanı için, depoda olmayan bilgi basitçe yoktur.Bu abartı değil. Bir ajanın girdilerinin gerçekten ne olduğunu düşünün: sistem promptları ve görev açıklamaları, depodaki dosya içerikleri ve araç yürütme çıktısı. Hepsi bu. Slack geçmişiniz, Jira biletleriniz, Confluence sayfalarınız ve Cuma öğleden sonra bir meslektaşınızla kahve eşliğinde tartıştığınız o mimari karar — ajan bunların hiçbirini göremez. "Birine gidip soramaz" ya da "sohbet geçmişini arayamaz." Depoya kilitlenmiş bir mühendistir — dışarıdaki her şey hakkında hiçbir şey bilmez.diff --git a/docs/tr/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/tr/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdindex 77c77c1..8edac98 100644--- a/docs/tr/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md+++ b/docs/tr/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -5,6 +5,8 @@# Ders 04. Tek bir dev talimat dosyası neden yetmez+> Mühendislik önerisi: sayısal eşikler ayarlanabilir öğretim değerleridir, deneysel sınırlar değildir. Token sayısı yalnız satıra değil tokenizer ve içeriğe bağlıdır.+Harness mühendisliğini ciddiye aldınız — aferin size. Bir `AGENTS.md` oluşturdunuz ve aklınıza gelen her kural, kısıtlama ve öğrenilen dersi içine tıktınız. Bir ay sonra dosya 300 satıra, iki ay sonra 450 satıra, üç ay sonra 600 satıra şişti. Sonra ajan performansının aslında kötüleştiğini fark ettiniz — basit bir hata düzeltmesinde ajan ilgisiz dağıtım talimatlarını işlemek için bolca bağlam yakıyor; 300. satıra gömülü kritik bir güvenlik kısıtlaması doğrudan göz ardı ediliyor; üç çelişkili kod stili kuralı ajanın her seferinde rastgele birini seçmesi anlamına geliyor.Bu "dev talimat dosyası" tuzağıdır. Bir bavulu fazla doldurmak gibidir — her şey faydalı görünür, hepsini sıkıştırırsınız fermuar patlamak üzeredir. İç çamaşırı bulmak tüm çantayı boşaltmak anlamına gelir. Dolu bir bavul taşıdınız ama aslında içindekilerin belki üçte birini kullandınız.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.mdindex 5d40ace..5cae556 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@@ -5,6 +5,8 @@# Ders 05. Uzun süren görevler neden sürekliliği kaybeder+> Mühendislik önerisi: sayısal eşikler ayarlanabilir öğretim değerleridir, deneysel sınırlar değildir. Token sayısı yalnız satıra değil tokenizer ve içeriğe bağlıdır.+Claude Code'dan eksiksiz bir özellik uygulamasını istiyorsunuz. 30 dakika çalışıyor, işin çoğunu yapıyor ama bağlam tükenmek üzere. Devam etmek için yeni bir oturum başlatıyorsunuz — ve geçen sefer hangi kararların alındığını, A seçeneği yerine neden B'nin seçildiğini, hangi dosyaların değiştirildiğini veya testlerin ne durumda olduğunu hatırlamadığını fark ediyorsunuz. Projeyi yeniden keşfetmek için 15 dakika harcıyor ve önceki yaklaşımla tutarsız olabiliyor.Her sabah uyandığında her şeyi unutan bir zanaatkâr olduğunuzu hayal edin. Tüm inşaat sahasıyla yeniden tanışmak zorunda kalırdınız — hangi duvar yarı yapılmış, kırmızı tuğla neden mavi yerine seçilmiş, su tesisatı nereye ulaşmış. Daha kötüsü, dün takılmış bir pencereyi sadece yapıldığını hatırlamadığınız için söküp atabilirsiniz.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.mdindex 9d232dc..e5bf96d 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@@ -5,6 +5,8 @@# Ders 06. Başlatma neden kendine ait bir aşama olmalı+> Mühendislik önerisi: sayısal eşikler ayarlanabilir öğretim değerleridir, deneysel sınırlar değildir. Token sayısı yalnız satıra değil tokenizer ve içeriğe bağlıdır.+Yeni bir ajan oturumu başlatıyor ve "arama özelliği ekle" diyorsunuz. Doğrudan kodlamaya atlıyor — takdire şayan bir hevesle. 20 dakika sonra test çerçevesinin düzgün yapılandırılmadığını keşfediyor, bunu düzeltmek için 10 dakika daha harcıyor, ardından veritabanı geçiş betiği formatı yanlış, daha fazla uğraşma. Arama özelliği sonunda ekleniyor ama tüm oturum verimsizdi — zamanın çoğu arama özelliğini yazmak yerine "bu projenin nasıl çalıştığını çözmeye" gitti.Daha iyi yaklaşım: ajanın çalışmaya başlamasına izin vermeden önce, temel ortamı hazır hâle getirmek, doğrulama komutlarını çalıştırmak ve proje yapısını anlamak için ayrı bir aşama kullanın. Bu bir ev inşa etmek gibidir — temeli dökerken aynı anda duvarları kaldırmazsınız. Yaparsanız, temel kürlenmeden duvarlar yükselir ve tüm binayı yıkıp baştan başlamak zorunda kalırsınız. Önce temeli dökün, kürlenmesine izin verin, sonra duvarları kaldırın — temiz ve verimli.@@ -37,6 +39,8 @@ flowchart TB## Karıştırdığınızda ne olur+> Öğretim örneği: senaryo ve sayılar açıklama için varsayılmıştır, yayımlanmış deney ölçümleri değildir.+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.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 +49,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: initializer / coding agent](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)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.@@ -122,7 +126,9 @@ OpenAI'nin Codex harness mühendisliği kılavuzu da "operasyonel kayıt olarak- [ ] Her şey git'e commit edildi```-## Gerçek dünya örneği+## Öğretim örneği++> Öğretim örneği: senaryo ve sayılar açıklama için varsayılmıştır, yayımlanmış deney ölçümleri değildir.Bir React frontend projesi için iki başlatma yaklaşımı: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.mdindex d08c119..85584e5 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@@ -5,6 +5,8 @@# Ders 07. Ajanlar neden sınırı aşar ve bitirmez+> Mühendislik önerisi: sayısal eşikler ayarlanabilir öğretim değerleridir, deneysel sınırlar değildir. Token sayısı yalnız satıra değil tokenizer ve içeriğe bağlıdır.+Claude Code'a "bu projeye kullanıcı kimlik doğrulaması ekle" diyorsunuz ve veritabanı şemasını değiştirmeye, rotalar yazmaya, frontend bileşenlerini değiştirmeye başlıyor — bu arada hata işleme middleware'ini de yeniden yapılandırıyor. İki saat sonra kontrol ediyorsunuz: 12 dosya değiştirilmiş, 800 satır yeni kod yazılmış ve tek bir özellik uçtan uca çalışmıyor.Çiğneyebileceğinden fazlasını ısırmak — bu söz AI ajanları için özellikle iyi geçerlidir. Ajanlar "biraz fazla yapma" dürtüsüyle doğarlar — ilgili bir şey görürler ve onunla birlikte halledilebilir, süpermarkete bir şişe soya sosu için gidip dolu bir arabayla çıkan biri gibi. Sorun şu ki, fazla satın alan insanlar sadece para harcar; aynı anda çok fazla şey yapan ajanlar hiçbirini düzgün bitirmez.@@ -26,7 +28,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: incremental feature work](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## WIP=1 iş akışı@@ -100,7 +102,9 @@ Tüm görev durumlarını kaydetmek için makine tarafından okunabilir bir dosyHarness sürekli olarak VCR (Verified Completion Rate) = doğrulanmış görevler / etkinleştirilen görevler izlemelidir. VCR < 1.0 olduğunda yeni görev etkinleştirmelerini engelleyin.-## Gerçek dünya örneği+## Öğretim örneği++> Öğretim örneği: senaryo ve sayılar açıklama için varsayılmıştır, yayımlanmış deney ölçümleri değildir.8 özellikli bir REST API projesi, iki strateji karşılaştırıldı: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.mdindex 306dc3c..cb841eb 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@@ -5,6 +5,8 @@# Ders 08. Özellik listeleri neden harness'ın temel yapı taşı+> Mühendislik önerisi: sayısal eşikler ayarlanabilir öğretim değerleridir, deneysel sınırlar değildir. Token sayısı yalnız satıra değil tokenizer ve içeriğe bağlıdır.+Bir ajandan bir e-ticaret sitesi inşa etmesini istiyorsunuz. Bitirdikten sonra size "tamam" diyor. Koda bakıyorsunuz — kullanıcı kimlik doğrulaması çalışıyor ama alışveriş sepetindeki ödeme düğmesi hiçbir şey yapmıyor ve ödeme akışı hiç bağlanmamış. Sorun: ona "tamam"ın ne anlama geldiğini söylemediniz, bu yüzden kendi standardını kullandı — "çok kod yazdım ve oldukça eksiksiz görünüyor."Özellik listeleri, birçok insanın gözünde sadece bir not — unutmamak için bir şeyleri yazıp sonra bir kenara atın. Ancak harness dünyasında bir özellik listesi insanlar için bir not değildir — tüm harness'ın omurgasıdır. Zamanlayıcı görevleri seçmek için ona güvenir, doğrulayıcı tamamlanmaya karar vermek için ona güvenir, devir raportörü özetleri oluşturmak için ona güvenir. Omurgayı kırın, tüm beden felç olur.@@ -22,7 +24,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.+İlerleme ve doğrulama sonuçlarını sürümlenen dosyalara kaydedin; sonraki oturum durumu inceleyebilsin. Kaynak mekanizmayı anlatır, başlangıç süresinde yüzde azalma vermez. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## Özellik durum makinesi@@ -103,7 +105,9 @@ Ajan bir özelliğin durumunu doğrudan `passing` olarak değiştiremez. YalnızHer özellik öğesi "bir oturumda tamamlanabilir" olacak şekilde kapsamlandırılmalıdır. Çok geniş olursa bitmez; çok dar olursa yönetim yükü büyür. "Kullanıcı sepete öğe ekleyebilir" iyi bir ayrıntı düzeyidir. "Alışveriş sepetini uygula" çok geniştir. "Cart modelinde isim alanını oluştur" çok dardır. Bir bifteği kesmek gibi — bütün parça değil, kıyma da değil.-## Gerçek dünya örneği+## Öğretim örneği++> Öğretim örneği: senaryo ve sayılar açıklama için varsayılmıştır, yayımlanmış deney ölçümleri değildir.10 özellikli bir e-ticaret platformu. İki takip yaklaşımı karşılaştırıldı:@@ -111,8 +115,6 @@ 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.-## Önemli çıkarımlar- **Özellik listeleri harness'ın omurgasıdır**, insanlar için not değildir. Zamanlayıcı, doğrulayıcı ve devir raportörü hepsi onlara bağlıdır.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.mdindex 20ec464..0eaae36 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@@ -5,6 +5,8 @@# Ders 9. Ajanların çok erken zaferi ilan etmesini önlemek+> Mühendislik önerisi: sayısal eşikler ayarlanabilir öğretim değerleridir, deneysel sınırlar değildir. Token sayısı yalnız satıra değil tokenizer ve içeriğe bağlıdır.+Bir ajandan "şifre sıfırlama" özelliğini uygulamasını istiyorsunuz. Veritabanı şemasını değiştiriyor, API uç noktasını yazıyor, e-posta şablonunu ekliyor, birim testleri çalıştırıyor (hepsi geçiyor) ve sonra güvenle "tamam" diyor. Aslında çalıştırmaya çalıştığınızda — şifre sıfırlama bağlantısı gönderilemez (eksik e-posta servis yapılandırması), veritabanı geçişi yarı yolda başarısız olur (şema tutarsızlığı) ve uçtan uca akış bir kez bile yürütülmemiştir.Bu his size yabancı gelmemeli — tüm sınav kâğıdını doldurmak, güvenle ilk teslim etmek, ardından notlar geldiğinde başarısız olmak gibi. Kâğıdın dolu olması cevapların doğru olduğu anlamına gelmez.@@ -13,6 +15,8 @@ Bu izole bir vaka değildir. Guo ve diğerlerinin 2017 ICML klasik makalesi şun## Kaygan zemin+> Model ve prompt aynı, zaman ve maliyet bütçeleri farklıdır. Tek bileşeni ayıran eşit bütçeli deney değildir. Temel oyun çalıştı, fakat hatalar kaldı. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)+Erken tamamlanma ilanları neredeyse her zaman aynı kalıbı izler: kod iyi görünür — sözdizimi doğrudur, mantık makul görünür ve statik analiz belirgin hata göstermez. Ancak harness kapsamlı yürütme doğrulamasını zorlamaz, bu yüzden ajan gerçekten çalıştırmayı atlar veya yalnızca kısmi testleri çalıştırır. Birim testleri çalıştırır ama entegrasyon testlerini atlar; testleri çalıştırır ama kapsamı kontrol etmez. Nihayetinde "kod iyi görünüyor" "özellik tamamlandı"nın kanıtı olarak alınır. Ve sınav kâğıdı teslim edilir.Her adımda bilgi kaybedilir. Görev spesifikasyonlarından kod uygulamasına, çalışma zamanı davranışına kadar her dönüşüm önyargı getirebilir ve atlanan her doğrulama bilgi asimetrisini şiddetlendirir.@@ -111,7 +115,9 @@ Etkili runtime sinyalleri şunları içerir:- Veritabanı yazımları, dosya işlemleri ve diğer yan etkiler doğru muydu?- Geçici kaynaklar temizlendi mi?-## Gerçek dünya örneği+## Öğretim örneği++> Öğretim örneği: senaryo ve sayılar açıklama için varsayılmıştır, yayımlanmış deney ölçümleri değildir.**Görev**: Kullanıcı şifre sıfırlama işlevini uygulayın. Veritabanı işlemlerini, e-posta göndermeyi ve API uç nokta değişikliklerini içerir.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.mdindex b13f4b4..134e8e2 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@@ -5,6 +5,8 @@# Ders 10. Uçtan uca test sonuçları neden değiştirir+> Mühendislik önerisi: sayısal eşikler ayarlanabilir öğretim değerleridir, deneysel sınırlar değildir. Token sayısı yalnız satıra değil tokenizer ve içeriğe bağlıdır.+Bir Electron uygulamasına dosya dışa aktarma özelliği eklemesini ajandan istiyorsunuz. Render süreci bileşenini, preload betiğini ve servis katmanı mantığını yazıyor. Her bileşenin birim testleri mükemmel şekilde geçiyor. Ajan "tamam" diyor. Aslında dışa aktarma düğmesine tıkladığınızda — dosya yolu formatı yanlış, ilerleme çubuğu güncellenmiyor ve büyük dosyaları dışa aktarmak bellek sızıntısına neden oluyor. Beş bileşen sınır kusuru ve birim testleri bir tane bile yakalamadı.Bu bir koro provası gibi — her ses parçası tek başına söylendiğinde mükemmel duyulur ama birlikte söylediklerinde, sopranolar baslardan yarım vuruş daha hızlı ve eşlik ana melodiyle yarım ton uzakta. Her parça kendi başına "doğru" ama bütün akortsuz.@@ -116,7 +118,9 @@ FIX: Dosya işlemlerini src/preload/file-ops.ts'e taşıyın ve window.api.readFKod incelemesi sırasında yeni bir ajan hatası türü bulunduğunda, onu otomatik bir kontrole dönüştürün. Bir ay sonra harness'ınız ayın başındakinden önemli ölçüde daha güçlü olacaktır. Bir koro için prova notları gibi — her provada bulunan sorunları kaydederek bir sonrakinden önce kontrol edilebilirler. Zamanla yaygın hatalar azalır ve müzik daha uyumlu hâle gelir.-## Gerçek dünya örneği+## Öğretim örneği++> Öğretim örneği: senaryo ve sayılar açıklama için varsayılmıştır, yayımlanmış deney ölçümleri değildir.**Görev**: Bir Electron uygulamasında dosya dışa aktarma özelliği uygulayın. Render süreci UI'sini, preload betiği dosya sistemi proxy'sini ve servis katmanı veri dönüşümünü içerir.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.mdindex 1cea207..e763bba 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@@ -32,7 +32,9 @@ flowchart LRVerdict --> Generator```-## Bu neden olur+## Öğretim örneği++> Öğretim örneği: senaryo ve sayılar açıklama için varsayılmıştır, yayımlanmış deney ölçümleri değildir.### Gözlemlenebilirlik eksikliğinin gerçek maliyeti@@ -44,7 +46,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.+İlerleme ve doğrulama sonuçlarını sürümlenen dosyalara kaydedin; sonraki oturum durumu inceleyebilsin. Kaynak mekanizmayı anlatır, başlangıç süresinde yüzde azalma vermez. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)### Gerçek bir Claude Code senaryosu@@ -116,7 +118,9 @@ Her görev başlamadan önce üretici ve değerlendirici (aynı ajanın farklıHer harness oturumu için bir iz, her görev için bir span ve her doğrulama adımı için alt span'lar oluşturun. Kilit bilgileri etiketlemek için standart öznitelikler kullanın. Bu şekilde gözlemlenebilirlik verisi standart araç zincirleriyle (Jaeger, Zipkin) entegre olur.-## Gerçek dünya örneği+## Öğretim örneği++> Öğretim örneği: senaryo ve sayılar açıklama için varsayılmıştır, yayımlanmış deney ölçümleri değildir."Karanlık mod desteği ekle" yürüten planlayıcı-üretici-değerlendirici iş akışı kullanan bir harness:@@ -136,7 +140,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.**+- İlerleme ve doğrulama sonuçlarını sürümlenen dosyalara kaydedin; sonraki oturum durumu inceleyebilsin. Kaynak mekanizmayı anlatır, başlangıç süresinde yüzde azalma vermez.## Daha fazla okumadiff --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.mdindex 9fe87ee..0e63324 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@@ -5,6 +5,8 @@# Ders 12. Her oturum neden temiz bir durumla bitmeli+> Mühendislik önerisi: sayısal eşikler ayarlanabilir öğretim değerleridir, deneysel sınırlar değildir. Token sayısı yalnız satıra değil tokenizer ve içeriğe bağlıdır.+## Bu ders hangi sorunu çözer?Ajanınız tüm öğleden sonra çalışıyor, 20 dosyayı değiştiriyor, kodu commit ediyor, oturum sona eriyor. Sonraki ajan oturumu başlıyor ve hemen şunları keşfediyor: yapı bozuk, testler kırmızı, geçici hata ayıklama dosyaları her yerde, özellik listesi güncellenmemiş ve ilerleme tamamen belirsiz. Yeni oturum ilk 30 dakikasını sadece "geçen oturum aslında ne yaptı" çözmek için harcıyor.@@ -54,6 +56,8 @@ flowchart LRLehman'ı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.+> Öğretim örneği: senaryo ve sayılar açıklama için varsayılmıştır, yayımlanmış deney ölçümleri değildir.+Gerçek veriler söyleyicidir. Temizleme stratejisi olmadan ajanlarla 12 hafta geliştirilen bir proje:- Hafta 1: Yapı geçme oranı %100, test geçme oranı %100, yeni oturum başlatma 5 dk@@ -66,8 +70,6 @@ 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.-### Temiz durumun beş boyutuTemiz durum yalnızca "kod derler" değildir. Birlikte değerlendirilen beş boyuttur:@@ -76,7 +78,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 ve doğrulama sonuçlarını sürümlenen dosyalara kaydedin; sonraki oturum durumu inceleyebilsin. Kaynak mekanizmayı anlatır, başlangıç süresinde yüzde azalma vermez. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)**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.@@ -152,7 +154,9 @@ git checkout -- .env.local # Bilinen duruma geri yüklenpm run test # Temizliğin bir şey bozmadığını doğrula```-## Gerçek dünya örneği+## Öğretim örneği++> Öğretim örneği: senaryo ve sayılar açıklama için varsayılmıştır, yayımlanmış deney ölçümleri değildir.12 hafta boyunca ajanlarla geliştirilen bir Electron uygulaması, iki yaklaşımın karşılaştırması:@@ -160,8 +164,6 @@ 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.-## Önemli çıkarımlar- **Temiz durum oturum tamamlanması için gerekli bir koşuldur** — isteğe bağlı ev temizliği değil, "bitirme tanımının" bir parçası.diff --git a/docs/tr/lectures/lecture-13-loop-engineering/index.md b/docs/tr/lectures/lecture-13-loop-engineering/index.mdindex d77ca97..b2f9a4b 100644--- a/docs/tr/lectures/lecture-13-loop-engineering/index.md+++ b/docs/tr/lectures/lecture-13-loop-engineering/index.md@@ -5,6 +5,8 @@# Ders 13. Manuel Prompting'den Otonom Loop'lara+> Mühendislik önerisi: sayısal eşikler ayarlanabilir öğretim değerleridir, deneysel sınırlar değildir. Token sayısı yalnız satıra değil tokenizer ve içeriğe bağlıdır.+İlk on iki derste öğrendiklerinizin hepsi tek bir varsayıma dayanıyor: **klavyenin başında oturup teker teker talimatlar yazıyorsunuz.**`AGENTS.md` yazdınız (Ders 1–4), durum yönetimi oluşturdunuz (Ders 5–6), özellik listeleriyle kapsamı kısıtladınız (Ders 7–8), oturum sonunda temiz devirler bıraktınız (Ders 9, 12) ve runtime'ı gözlemlenebilir kıldınız (Ders 10–11). Ama tüm bunların tetikleyicisi her zaman siz oldunuz. Ajan ne zaman çalışmaya başlayacağına kendi kendine karar vermedi — çünkü kimse "başlat" tuşuna basmadı.@@ -84,8 +86,12 @@ Bu dersin konusu olan Loop Mühendisliği, tek bir komutla ilgili değildir. **THer 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.+> Öğretim örneği: senaryo ve sayılar açıklama için varsayılmıştır, yayımlanmış deney ölçümleri değildir.+## Haziran 2026: Üç kişi aynı haftada aynı sigortayı yaktı+> Öğretim örneği: senaryo ve sayılar açıklama için varsayılmıştır, yayımlanmış deney ölçümleri değildir.+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.**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."@@ -96,7 +102,13 @@ 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ı.+Boris Cherny · 2025-12-27++| PR | Git commits | + LoC | − LoC | Model |+| --- | --- | --- | --- | --- |+| 259 / 30 days | 497 | 40,000 | 38,000 | Claude Code + Opus 4.5 |++Yazarın bildirdiği kişisel üretim, benchmark başarı oranı veya insan denetiminin yokluğu kanıtı değildir. [Boris Cherny](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)Üç 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.@@ -267,7 +279,7 @@ flowchart TDBu 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.+Yazarın bildirdiği kişisel üretim, benchmark başarı oranı veya insan denetiminin yokluğu kanıtı değildir.## Üretici/Değerlendirici Ayrımı: Neden Modelin Kendi Çalışmasını Notlandırmasına İzin Veremezsiniz@@ -293,7 +305,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ı.+[Karpathy: autoresearch](https://github.com/karpathy/autoresearch) · [announcement](https://x.com/karpathy/status/2030371219518931079)### Üç Dosya, Üç Rol@@ -343,8 +355,6 @@ flowchart TD8b --> 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.-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.### Çıktı: Uyandığınızda ne görürsünüz@@ -359,6 +369,8 @@ Sadece gerçekten iyileştiren commit'ler ana dalda kalır. Başarısız olan heHer tek deney — başarılı veya başarısız — günlüğe kaydedilir:+> Öğretim örneği: senaryo ve sayılar açıklama için varsayılmıştır, yayımlanmış deney ölçümleri değildir.+```timestamp commit_hash val_bpb vram_mb description--------- ------------- ---------- ---------- ----------------------------@@ -375,11 +387,10 @@ 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ı:--- ~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.+- Bulgular şunları içeriyordu: öğrenme oranı ayarlamaları, optimize edici ayarı, aktivasyon değişimleri, dikkat deseni optimizasyonları vb. [Karpathy: leaderboard commit](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b) · [tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)++> Öğretim örneği: senaryo ve sayılar açıklama için varsayılmıştır, yayımlanmış deney ölçümleri değildir.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ı.@@ -399,7 +410,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.**+Üretim sonuçları tek nedeni ayırmaz. Benchmark skorları belirtilen model, scaffold, veri ve değerlendirme koşulları içindir.### 3. Bilişsel Teslimiyetdiff --git a/docs/tr/lectures/lecture-14-graph-engineering/index.md b/docs/tr/lectures/lecture-14-graph-engineering/index.mdindex 9ea7b70..f0d4e9a 100644--- a/docs/tr/lectures/lecture-14-graph-engineering/index.md+++ b/docs/tr/lectures/lecture-14-graph-engineering/index.md@@ -261,7 +261,7 @@ Bittiğinde bunu yukarıdaki diyagramla karşılaştırın: el yazınız `graph.**İ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)**İsimden önce gelen projeler (onu Graph Engineering olarak adlandırmıyorlar — ama gerçekten inşa ederken kullanacağınız şeyler) bunlar**@@ -346,4 +346,4 @@ Her görev bir graf hak etmez. Beş kriter — başlamadan önce en az üçünü4. **Bir adayı beş kriterle puanlayın:** "Graflamayı" düşündüğünüz bir görev seçin ve beş kritere göre puanlayın. Bir graf hak etmek için en az üçü gerekir. Üçten az puan alırsa, gerçekten ihtiyacı olan daha iyi bir workflow betiğidir — graf çizmek için graf çizmeyin.-5. **`graph.md`'nizi yürütülebilir bir programa dönüştürün:** "İlk Graf'ınızı Sıfırdan Oluşturun" bölümündeki altı adımı izleyerek çizdiğiniz maker-checker diyagramını çalıştırılabilir bir graf olarak uygulayın (referans uygulama: `code/maker_checker_graph.py`, LangGraph ile yazılmış). Altı adımın hiçbirini atlamayın: durumu tanımla, düğümleri listele, kenarları bağla, router'ı yaz, checkpoint ekle, çalıştır. Sonra diyagramı kodla karşılaştırın ve uyuşmayan ilk yeri bulun, neden uyuşmadığını açıklayın — diyagram mı yanlıştı, yoksa kod mu?\ No newline at end of file+5. **`graph.md`'nizi yürütülebilir bir programa dönüştürün:** "İlk Graf'ınızı Sıfırdan Oluşturun" bölümündeki altı adımı izleyerek çizdiğiniz maker-checker diyagramını çalıştırılabilir bir graf olarak uygulayın (referans uygulama: `code/maker_checker_graph.py`, LangGraph ile yazılmış). Altı adımın hiçbirini atlamayın: durumu tanımla, düğümleri listele, kenarları bağla, router'ı yaz, checkpoint ekle, çalıştır. Sonra diyagramı kodla karşılaştırın ve uyuşmayan ilk yeri bulun, neden uyuşmadığını açıklayın — diyagram mı yanlıştı, yoksa kod mu?diff --git a/docs/tr/resources/reference/index.md b/docs/tr/resources/reference/index.mdindex 500d173..aa1cf80 100644--- a/docs/tr/resources/reference/index.md+++ b/docs/tr/resources/reference/index.md@@ -73,6 +73,11 @@ kalmıştır.- [On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents](https://arxiv.org/html/2601.20404v2): gpt-5.2-codex; 10 repos / 124 PR tasks; Table 1.+- [Anthropic: Sonnet 4.5 — SWE-bench Verified methodology (2025-09-29)](https://www.anthropic.com/news/claude-sonnet-4-5)+- [Boris Cherny: personal 30-day production report (2025-12-27)](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)+- [Karpathy: measured autoresearch leaderboard improvement](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b)+- [Karpathy: two-day autonomous tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)+## Önerilen Okuma Sırası1. `method-map.md`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.mdindex a56df92..d863695 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,17 +5,30 @@# Лекція 01. Сильна модель — ще не гарантія надійного виконання-Наприкінці 2025 року найсильніші агенти для написання коду на SWE-bench Verified досягають приблизно 50–60% успішних проходжень. На перший погляд цифра здається непоганою — але не поспішайте радіти. Це ретельно відібрані задачі з чіткими описами і готовими тестами. Дайте агенту ваші повсякденні вимоги — розмиті специфікації, відсутні тести, неявні бізнес-правила, розкидані по всьому коду, — і відсоток успіху впаде ще нижче. Ви передаєте задачу з повною впевненістю, агент працює 20 хвилин і повідомляє «все зроблено», а ви дивитесь на код: функціонал додано, але тести зламані, баг виправлено, але з'явилися нові, та й взагалі — це не те, про що ви просили.+Claude Sonnet 4.5 · 2025-09-29 · SWE-bench Verified++| Score | Tasks | Trials | Scaffold |+| --- | --- | --- | --- |+| 77.2% | 500 | 10 | bash + string replacement |++Виробничі результати не ізолюють одну причину. Оцінки стосуються зазначених моделі, scaffold, даних і умов, не будь-якого реального завдання. [Anthropic: methodology](https://www.anthropic.com/news/claude-sonnet-4-5)Коли таке трапляється, перша реакція більшості — «модель недостатньо хороша, спробую дорожчу». Перш ніж тягтися до гаманця, подумайте: проблема може бути зовсім не в моделі.## Один кінь, дві долі-Anthropic провела контрольований експеримент, який ідеально ілюструє цю думку. Один і той самий промпт («збудуй 2D-редактор ретро-ігор»), одна й та сама модель (Opus 4.5), два запуски. Перший запуск: без підтримки — 20 хвилин, $9, основний функціонал гри не працював. Другий запуск: повноцінний harness — архітектура з трьох агентів (планувальник, генератор, оцінювач) — 6 годин, $200, гра повністю готова до гри.+> Модель і запит однакові, але бюджети часу та вартості різні. Це не експеримент із рівним бюджетом, що ізолює один компонент. Основна гра працювала, але залишалися дефекти. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++Модель і запит однакові, але бюджети часу та вартості різні. Це не експеримент із рівним бюджетом, що ізолює один компонент. Основна гра працювала, але залишалися дефекти. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++| Opus 4.5 | Duration | USD |+| --- | --- | --- |+| Solo | 20 min | 9 |+| Full harness | 6 h | 200 |Модель не змінювали. Opus 4.5 залишався Opus 4.5. Змінилося спорядження.-Стаття OpenAI про harness engineering 2025 року висловлюється ще прямолінійніше. Там сказано, що Codex у добре підготовленому репозиторії переходить від «ненадійного» прямо до «надійного». Зверніть увагу на формулювання — не «трохи кращий», а якісний стрибок. Harness тут означає **всю інженерну інфраструктуру поза вагами моделі.**+Виробничі результати не ізолюють одну причину. Оцінки стосуються зазначених моделі, scaffold, даних і умов, не будь-якого реального завдання. [OpenAI: 2026-02-11](https://openai.com/index/harness-engineering/)## Де агенти насправді застрягають@@ -25,13 +38,13 @@ Anthropic провела контрольований експеримент, я- **Неявні конвенції, не зафіксовані в жодному документі, — агент не може їх дотримуватися.** Уся команда використовує новий синтаксис SQLAlchemy 2.0, а агент за замовчуванням пише код 1.x. Усі API-ендпоінти мають проходити через автентифікацію OAuth 2.0, але це правило існує лише у вашій голові та в повідомленні Slack тримісячної давнини. Агент не має жодного уявлення про це — не тому що не хоче дотримуватися правил, а тому що він їх просто ніколи не бачив.- **Неповне налаштування середовища — агент витрачає сили на виправлення оточення.** Незавершений dev-сетап, відсутні залежності, невірні версії інструментів — агент спалює дорогоцінне контекстне вікно на помилки `pip install` і конфлікти версій Node замість того, щоб виконувати реальну роботу.- **Відсутність методів верифікації — агент вважає задачу завершеною, коли йому так здається.** Немає тестів, немає лінтера чи верифікаційних команд, про які агенту не повідомили. Агент пише код, перечитує його, вирішує, що все виглядає нормально, і оголошує про завершення. Anthropic також зафіксувала цікавий феномен: коли агенти відчувають, що контекстне вікно закінчується, вони поспішають із завершенням, пропускають кроки верифікації та обирають просте рішення замість оптимального. Це явище називають «контекстною тривогою».-- **Втрата стану між сесіями — кожна нова сесія починається з нуля.** Усі відкриття попередньої сесії зникають. Кожна нова сесія змушена заново досліджувати структуру проєкту і заново розуміти організацію коду. Агенти без збереження стану демонструють різке зростання відсотка відмов на задачах, що перевищують 30 хвилин.+- **Втрата стану між сесіями — кожна нова сесія починається з нуля.** — Записуйте прогрес і перевірки у версійовані файли, щоб наступна сесія могла перевірити стан. Джерело описує механізм без відсоткового скорочення часу запуску. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## Ключова термінологіяЗ огляду на описані вище сценарії ці концепції вже не є просто жаргоном:-- **Capability Gap (Розрив у можливостях)**: Величезна прірва між продуктивністю моделі на бенчмарках і продуктивністю на реальних задачах. 50–60% на SWE-bench Verified означає, що майже половина реальних проблем залишається невирішеною.+- Виробничі результати не ізолюють одну причину. Оцінки стосуються зазначених моделі, scaffold, даних і умов, не будь-якого реального завдання.- **Harness**: Все, що знаходиться поза моделлю — інструкції, інструменти, середовище, управління станом, зворотний зв'язок для верифікації. Якщо це не ваги моделі — це harness. Те, що ми називали «спорядженням».- **Harness-Induced Failure (Збій, спричинений harness)**: Модель має достатні можливості, але середовище виконання має структурні дефекти. Контрольований експеримент Anthropic вже довів це.- **Verification Gap (Розрив верифікації)**: Розрив між впевненістю агента у своєму результаті та реальною коректністю. Агент каже «я готовий», коли насправді ні — це найпоширеніший сценарій збою.@@ -60,15 +73,17 @@ Anthropic провела контрольований експеримент, я## Експеримент з мільйоном рядків-У 2025 році троє інженерів OpenAI розпочали експеримент. Правила були прості: вони самі не пишуть код — тільки Codex. Починаючи з порожнього git-репозиторію, через п'ять місяців у репозиторії було приблизно мільйон рядків коду. Логіка застосунку, інфраструктура, інструментарій, документація — все згенеровано агентом. Троє інженерів відкрили загалом 1500 PR, в середньому 3,5 на людину на день.+Виробничі результати не ізолюють одну причину. Оцінки стосуються зазначених моделі, scaffold, даних і умов, не будь-якого реального завдання. [OpenAI: 2026-02-11](https://openai.com/index/harness-engineering/)Перші кроки виявилися напрочуд повільними. Codex був не поганий — він просто не мав інструментів і структур, достатньо повних для досягнення цілей високого рівня. Троє інженерів поступово виявили закономірність: розбивайте великі цілі на дрібні будівельні блоки — проектування, код, рев'ю, тести — давайте агенту складати їх один за одним, а потім використовуйте ці блоки для компонування складніших задач. Щоразу, коли щось ішло не так, проблема майже ніколи не була «недостатнє старання». Завжди: «чого агенту ще не вистачає, і чи можна надати цю відсутню можливість у спосіб, зрозумілий і придатний до виконання?»-Цей експеримент безпосередньо доводить головну тезу лекції: **та сама модель дає принципово різний результат у голому середовищі та в середовищі з повноцінним harness.** Модель не змінилася. Змінилося середовище.+Виробничі результати не ізолюють одну причину. Оцінки стосуються зазначених моделі, scaffold, даних і умов, не будь-якого реального завдання.> Джерело: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)-## Більш приземлений приклад+## Навчальний приклад++> Навчальна ілюстрація: сценарій і числа є пояснювальними припущеннями, не вимірюваннями опублікованого експерименту.Одна команда використовувала Claude Sonnet для додавання нових API-ендпоінтів до середнього Python-веб-застосунку (FastAPI + PostgreSQL + Redis, ~15 000 рядків коду).@@ -94,6 +109,8 @@ Anthropic провела контрольований експеримент, я- [SWE-bench Leaderboard](https://www.swebench.com/)- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)+- [Anthropic: Sonnet 4.5 SWE-bench methodology, 2025-09-29](https://www.anthropic.com/news/claude-sonnet-4-5)+## Вправи1. **Порівняльний експеримент**: Візьміть кодову базу, яку ви добре знаєте, і нетривіальну задачу на модифікацію. Спочатку запустіть агент без підтримки harness і зафіксуйте збої. Потім додайте `AGENTS.md` та явні верифікаційні команди і запустіть знову з тим самим агентом. Порівняйте два результати, відносячи кожен збій до одного з п'яти захисних шарів.diff --git a/docs/uk/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/uk/lectures/lecture-02-what-a-harness-actually-is/index.mdindex 1ab631f..6dad52f 100644--- a/docs/uk/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/uk/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -70,7 +70,9 @@ Verification commands:**Кількісна оцінка цінності компонентів harness**: використовуйте «тест контрольованого вилучення змінних». Тримайте модель незмінною, вилучайте п'ять підсистем по одній і дивіться, яке вилучення спричиняє найбільше падіння продуктивності. Компонент із найбільшим падінням має найвищий граничний внесок для поточного завдання і заслуговує на пріоритетну увагу. Чи варто його посилювати — залежить від атрибуції відмов, а не лише від розміру падіння. Компоненти з майже нульовим впливом не слід відкидати одразу: вони можуть бути надлишковими, погано спроєктованими або просто незадіяними в поточному завданні. Цей експеримент відповідає на питання «який компонент зараз найцінніший» — але не може сам по собі довести «де знаходиться вузьке місце». Щоб справді локалізувати вузьке місце, потрібно спочатку проаналізувати записи відмов і їхню атрибуцію: задача була незрозумілою, контексту не вистачало, середовище не відтворювалося, зворотний зв'язок верифікації був відсутній чи управління станом не працювало? Результати абляції компонентів можуть слугувати лише підтверджуючими доказами.-## Реальна історія команди+## Навчальний приклад++> Навчальна ілюстрація: сценарій і числа є пояснювальними припущеннями, не вимірюваннями опублікованого експерименту.Команда використовувала GPT-4o для розробки TypeScript + React фронтенд-застосунку (~20 000 рядків коду). Вони пройшли чотири етапи, які по суті були послідовним додаванням компонентів harness:diff --git a/docs/uk/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/uk/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdindex 45dca48..c32de9e 100644--- a/docs/uk/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md+++ b/docs/uk/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -5,6 +5,8 @@# Лекція 03. Чому репозиторій має стати єдиним джерелом правди+> Інженерні орієнтири: числа — регульовані навчальні значення, не доведені пороги. Кількість токенів залежить від токенізатора й змісту, не лише рядків.+Архітектурні рішення вашої команди розкидані між Confluence, Slack, Jira і кількома головами старших інженерів. Для людей це якось працює — можна запитати колегу, знайти щось у логах чату, покопатися в документації, а якщо нічого не допомогло — зловити когось у перерві. Але для AI-агента інформація, якої немає в репозиторії, просто не існує.Це не перебільшення. Агент має лише три джерела вхідних даних: системні промпти і описи завдань, вміст файлів з репозиторію та результати виконання інструментів. Ваша історія Slack, тікети Jira, сторінки Confluence і архітектурне рішення, яке ви обговорили з колегою в п'ятницю після обіду, — агент нічого з цього не бачить. Він не може «піти запитати когось» чи «знайти в логах чату». Весь його робочий світ — це сам репозиторій. Про все, що за його межами, він не знає нічого.diff --git a/docs/uk/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/uk/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdindex 8459bf6..93c2f9a 100644--- a/docs/uk/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md+++ b/docs/uk/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -5,6 +5,8 @@# Лекція 04. Розподіліть інструкції між файлами+> Інженерні орієнтири: числа — регульовані навчальні значення, не доведені пороги. Кількість токенів залежить від токенізатора й змісту, не лише рядків.+Ви почали серйозно займатися harness engineering — чудово. Ви створили `AGENTS.md` і вклали туди кожне правило, обмеження та засвоєний урок, про який тільки могли подумати. Через місяць файл розрісся до 300 рядків, через два — до 450, через три — до 600. І тут ви помічаєте, що продуктивність агента насправді погіршується: під час простого виправлення помилки агент витрачає величезну кількість контексту на обробку інструкцій щодо розгортання, які не мають жодного відношення до задачі; критичне обмеження безпеки, заховане на рядку 300, ігнорується взагалі; три суперечливі правила стилю коду змушують агента щоразу вибирати одне навмання.Це пастка «гігантського файлу інструкцій». Все здається корисним, тому ви все туди запихаєте, а знайти конкретне правило означає перегортати весь файл. Ви написали 600 рядків, але лише третина з них стосується поточної задачі.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.mdindex 32964ff..ef5331e 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@@ -5,6 +5,8 @@# Лекція 05. Збереження контексту між сесіями+> Інженерні орієнтири: числа — регульовані навчальні значення, не доведені пороги. Кількість токенів залежить від токенізатора й змісту, не лише рядків.+Ви просите Claude Code реалізувати повноцінну функцію. Він працює 30 хвилин, виконує більшу частину роботи, але контекст добігає кінця. Ви починаєте нову сесію, щоб продовжити — і виявляєте, що він не пам'ятає, які рішення були прийняті минулого разу, чому варіант А був відхилений на користь варіанта Б, які файли вже були змінені та в якому стані перебувають тести. Він витрачає 15 хвилин на повторне дослідження проєкту і може обрати підхід, несумісний із попереднім.Це реальна дилема, з якою стикаються AI-агенти для написання коду при міжсесійних задачах. У цій лекції пояснюється, чому агенти «втрачають нитку» під час тривалих задач і як структуроване збереження стану дозволяє новій сесії швидко продовжити роботу з того місця, де зупинилась попередня.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.mdindex a4f6ede..a0a8702 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@@ -5,6 +5,8 @@# Лекція 06. Нехай агент ініціалізується перед кожною робочою сесією+> Інженерні орієнтири: числа — регульовані навчальні значення, не доведені пороги. Кількість токенів залежить від токенізатора й змісту, не лише рядків.+Ви починаєте нову сесію агента і кажете йому «додай функцію пошуку». Він одразу кидається писати код — похвальний ентузіазм. Через 20 хвилин виявляється, що тестовий фреймворк налаштований неправильно, і витрачається ще 10 хвилин на виправлення; потім з'ясовується, що формат скрипту міграції бази даних не той — ще метушня. Функцію пошуку врешті-решт додано, але вся сесія виявилася неефективною. Більша частина часу пішла на «розбирання того, як влаштований проєкт», а не на написання самої функції пошуку.Кращий підхід: перш ніж дозволити агенту почати роботу, виділіть окрему фазу для підготовки базового середовища, виконання перевірочних команд і знайомства зі структурою проєкту. Роботу з ініціалізації не можна змішувати з реалізацією функцій — це два принципово різні типи задач.@@ -37,6 +39,8 @@ flowchart TB## Що відбувається, коли їх змішують+> Навчальна ілюстрація: сценарій і числа є пояснювальними припущеннями, не вимірюваннями опублікованого експерименту.+Найочевидніша проблема: інфраструктура будується ненадійно. Агент витрачає 80% зусиль на код функцій, а решту 20% — на поверхневе налаштування інфраструктури. Тестовий фреймворк налаштований, але не перевірений; правила лінтера встановлені, але занадто м'які; файл прогресу не створено. Ці вади непомітні в першій сесії (бо агент ще пам'ятає, що робив), але спливають у другій: новий агент не знає, як запустити проєкт, як тестувати і де що знаходиться.Прихованіша проблема — «накопичення неперевіреного коду». Код функцій написаний до того, як тестовий фреймворк правильно налаштований — коли ви нарешті повертаєтеся додавати тести, може виявитися, що сам дизайн був хибним. Знаючи це раніше, ви б реалізували інакше. Що більше коду написано заздалегідь, то більше доведеться зносити і переробляти потім.@@ -45,7 +49,7 @@ flowchart TBНайлегше проігнорована проблема — приховані припущення, що стають пастками. Рішення, прийняті агентом під час ініціалізації (який тестовий фреймворк, як організувати директорії, керування залежностями) — якщо вони не зафіксовані явно, наступні сесії можуть зробити суперечливі вибори. Перша сесія вибрала Vitest як тестовий фреймворк, але агент другої сесії цього не знає і впроваджує Jest. Два тестових фреймворки існують паралельно, а витрати на підтримку подвоюються.-Дослідження Anthropic у сфері розробки довготривалих застосунків явно рекомендує розділяти ініціалізацію та реалізацію. Їхні експериментальні дані: проєкти з виділеною фазою ініціалізації показали на 31% вищий відсоток завершення функцій у багатосесійних сценаріях порівняно зі змішаним підходом. А час, витрачений на фазу ініціалізації, повністю окупається вже в наступних 3–4 сесіях.+[Anthropic: initializer / coding agent](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)Посібник з harness engineering від OpenAI Codex також наголошує на принципі «репозиторій як операційний запис»: з самого першого запуску встановіть чітку операційну структуру, інакше кожна нова сесія змушена заново виводити конвенції проєкту.@@ -122,7 +126,9 @@ flowchart TB- [ ] Everything committed to git```-## Реальний приклад+## Навчальний приклад++> Навчальна ілюстрація: сценарій і числа є пояснювальними припущеннями, не вимірюваннями опублікованого експерименту.Порівняння двох підходів до ініціалізації для React-проєкту фронтенду: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.mdindex 8bf000f..84d5d84 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@@ -5,6 +5,8 @@# Лекція 07. Встановіть чіткі межі задач для агентів+> Інженерні орієнтири: числа — регульовані навчальні значення, не доведені пороги. Кількість токенів залежить від токенізатора й змісту, не лише рядків.+Ви кажете Claude Code «додай автентифікацію користувачів до цього проєкту», і він починає змінювати схему бази даних, писати маршрути, змінювати компоненти фронтенду і — заодно — рефакторити middleware для обробки помилок. Через дві години перевіряєте: 12 змінених файлів, 800 рядків нового коду, і жодна функція не працює наскрізь.Агенти від природи схильні «зробити трохи більше» — бачать суміжні речі і просто вирішують їх по дорозі. Проблема в тому, що надто велика кількість одночасних справ майже гарантовано призводить до того, що жодна з них не буде зроблена добре.@@ -26,7 +28,7 @@Шість кроків — і кожен наполовину зроблений. Жодної наскрізної верифікації, складне зв'язування між напівготовим кодом, а наступна сесія, що підхопить уламки, буде повністю розгублена.-Експериментальні дані Anthropic це підтверджують безпосередньо: агенти, що використовують стратегію «маленького наступного кроку» (еквівалент WIP=1), показують на 37% вищий відсоток завершення задач, ніж агенти з широкими промптами. Цікавіше те, що кількість рядків коду, згенерованих агентами, слабко негативно корелює з фактичним завершенням функцій — більше написаного коду, менше завершених функцій. Захопити більше, ніж можеш з'їсти, — доведено даними.+[Anthropic: incremental feature work](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## Робочий процес WIP=1@@ -98,7 +100,9 @@ F01: User RegistrationHarness має постійно відстежувати VCR (Verified Completion Rate) = верифіковані задачі / активовані задачі. Блокуйте активацію нових задач, коли VCR < 1.0.-## Реальний кейс+## Навчальний приклад++> Навчальна ілюстрація: сценарій і числа є пояснювальними припущеннями, не вимірюваннями опублікованого експерименту.Проєкт REST API з 8 функціями, порівняння двох стратегій: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.mdindex 57d792b..087c7b0 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@@ -5,6 +5,8 @@# Лекція 08. Використовуйте списки функціональності для обмеження дій агента+> Інженерні орієнтири: числа — регульовані навчальні значення, не доведені пороги. Кількість токенів залежить від токенізатора й змісту, не лише рядків.+Ви просите агента побудувати e-commerce сайт. Після завершення він повідомляє: «готово». Ви дивитесь на код — автентифікація користувачів працює, але кнопка оформлення замовлення в кошику нічого не робить, а платіжний потік взагалі не підключений. Де щось пішло не так? Ви ніколи не пояснили, що означає «готово», тому агент застосував власний стандарт: «я написав багато коду, і він виглядає достатньо повним».У більшості людей списки функціональності асоціюються лише з нотатками — записати, щоб не забути, а потім відкласти вбік. Але у світі harness список функціональності — це не нотатка для людини. Це фундаментальна структура, на якій побудований увесь harness. Планувальник спирається на нього, щоб вибирати завдання, верифікатор — щоб оцінювати завершеність, а генератор звітів про передачу — щоб формувати підсумки. Без нього ці компоненти не мають спільного консенсусу.@@ -25,7 +27,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)## Машина станів функціональності@@ -108,7 +110,9 @@ flowchart LRКожен елемент функціональності має бути розрахований на «виконання за один сеанс». Надто широкий — не завершиться; надто вузький — зростають накладні витрати на управління. «Користувач може додавати товари до кошика» — правильна гранулярність. «Реалізувати кошик» — надто широко. «Створити поле name у моделі Cart» — надто вузько.-## Реальний кейс+## Навчальний приклад++> Навчальна ілюстрація: сценарій і числа є пояснювальними припущеннями, не вимірюваннями опублікованого експерименту.E-commerce платформа з 10 функціями. Порівняння двох підходів до відстеження:@@ -116,8 +120,6 @@ E-commerce платформа з 10 функціями. Порівняння д**Структурований режим**: кожна функція має чіткий стан і команду верифікації. Новий сеанс читає список функціональності і за 3 хвилини знає: F01–F05 — `passing`, F06 — `active` (в роботі), F07–F10 — `not_started`. Він продовжує безпосередньо з F06, без жодного повтору роботи.-Кількісний результат: проєкти зі структурованими списками функціональності показують на 45% вищий рівень завершення функцій порівняно з довільним відстеженням, без жодних дублікатів реалізацій.-## Ключові висновки- **Списки функціональності — це фундаментальна структура harness**, а не нотатки для людей. Від них залежать планувальник, верифікатор і генератор звітів про передачу.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.mdindex 0a4a070..3f5511a 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@@ -5,12 +5,16 @@# Лекція 09. Запобігання передчасному оголошенню перемоги агентами+> Інженерні орієнтири: числа — регульовані навчальні значення, не доведені пороги. Кількість токенів залежить від токенізатора й змісту, не лише рядків.+Ви просите агента реалізувати функцію «скидання пароля». Він змінює схему бази даних, пише API-ендпоінт, додає шаблон електронного листа, запускає юніт-тести (всі проходять) і впевнено повідомляє: «готово». Але коли ви насправді спробуєте запустити — посилання для скидання пароля не надсилається через відсутню конфігурацію поштового сервісу; міграція бази даних завершується на половині, залишаючи схему в суперечливому стані; а наскрізний потік жодного разу не виконувався.Це не поодинокий випадок. Класична стаття ICML 2017 року Guo et al. довела: **сучасні нейронні мережі систематично переоцінюють свою впевненість** — довіра, яку повідомляють моделі, значно вища за їхню фактичну точність. Агенти для написання коду на основі ШІ нічим не відрізняються. Вони «відчувають» завершеність, але насправді далекі від неї. Ваш harness повинен замінити «відчуття» агента зовнішньою верифікацією на основі виконання.## Слизький схил+> Модель і запит однакові, але бюджети часу та вартості різні. Це не експеримент із рівним бюджетом, що ізолює один компонент. Основна гра працювала, але залишалися дефекти. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)+Передчасні оголошення про завершення майже завжди слідують одним і тим самим сценарієм: код виглядає нормально — синтаксис правильний, логіка здається розумною, статичний аналіз не показує очевидних помилок. Але harness не вимагає комплексної верифікації виконання, тому агент або взагалі не запускає код, або запускає лише часткові тести. Він виконує юніт-тести, але пропускає інтеграційні; запускає тести, але не перевіряє покриття. Зрештою «код виглядає добре» сприймається як свідчення того, що «функція завершена».Інформація втрачається на кожному кроці. Від специфікації завдання до реалізації коду та поведінки під час виконання — кожне перетворення може вносити упередженість, а кожна пропущена верифікація посилює інформаційну асиметрію.@@ -109,7 +113,9 @@ OpenAI представив особливо ефективний патерн- Чи були коректні записи в базу даних, файлові операції та інші побічні ефекти?- Чи були очищені тимчасові ресурси?-## Реальний кейс+## Навчальний приклад++> Навчальна ілюстрація: сценарій і числа є пояснювальними припущеннями, не вимірюваннями опублікованого експерименту.**Завдання**: реалізувати функціональність скидання пароля. Включає операції з базою даних, надсилання електронної пошти та зміни API-ендпоінта.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.mdindex fde1332..e46d842 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@@ -5,6 +5,8 @@# Лекція 10. Лише повний запуск пайплайну є справжньою верифікацією+> Інженерні орієнтири: числа — регульовані навчальні значення, не доведені пороги. Кількість токенів залежить від токенізатора й змісту, не лише рядків.+Ви просите агента додати функцію експорту файлів до Electron-застосунку. Він пише компонент рендерера, preload-скрипт і логіку сервісного шару. Юніт-тести для кожного компонента проходять. Агент каже «готово». Ви насправді натискаєте кнопку експорту — формат шляху до файлу неправильний, прогрес-бар не реагує, а експорт великих файлів призводить до витоку пам'яті. П'ять дефектів на межах компонентів, і жодного з них юніт-тести не виявили.Кожна частина виглядає «правильною» окремо, але проблеми виникають у момент з'єднання. Testing Pyramid від Google говорить, що велика база юніт-тестів необхідна, але зупинятись на цьому означає систематично пропускати проблеми взаємодії компонентів. Для агентів AI-кодування ця проблема ще гостріша, бо агенти схильні запускати лише найшвидші тести, а потім оголошувати завершення. **Лише наскрізне тестування може довести відсутність дефектів системного рівня.**@@ -114,7 +116,9 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.reaЩоразу, коли під час code review ви виявляєте нову категорію помилок агента, перетворюйте її на автоматизовану перевірку. Через місяць ваш harness буде значно сильнішим, ніж на початку місяця.-## Реальний кейс+## Навчальний приклад++> Навчальна ілюстрація: сценарій і числа є пояснювальними припущеннями, не вимірюваннями опублікованого експерименту.**Завдання**: Реалізувати функцію експорту файлів в Electron-застосунку. Задіяні: UI процесу рендерера, файловий проксі preload-скрипту та перетворення даних сервісного шару.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.mdindex 99e3a3c..1cb9d2c 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,15 +21,17 @@**Повторні спроби стають сліпими здогадками.** Коли агент не знає, чому щось не спрацювало, напрямок повторної спроби випадковий. Він може безуспішно стукатись у хибному напрямку — виправляти непов'язані шляхи коду, ігноруючи справжню першопричину. Кожна сліпа повторна спроба спалює токени і час.-**Інформаційна прірва при передачі сесії.** Коли незавершена робота передається наступній сесії, відсутність спостережуваності означає, що нова сесія має діагностувати стан системи з нуля. Спостереження Anthropic за довготривалими агентами показують, що ця надлишкова діагностика може поглинати 30–50% загального часу сесії.+Записуйте прогрес і перевірки у версійовані файли, щоб наступна сесія могла перевірити стан. Джерело описує механізм без відсоткового скорочення часу запуску. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)-## Реальний сценарій Claude Code+## Навчальний приклад++> Навчальна ілюстрація: сценарій і числа є пояснювальними припущеннями, не вимірюваннями опублікованого експерименту.Розглянемо harness, що використовує робочий процес із трьома ролями «планувальник–генератор–оцінювач» для виконання завдання «додати темний режим до застосунку».**Без спостережуваності:** Планувальник виводить розпливчастий опис. Генератор реалізує темний режим на основі цієї розпливчастості, але результат не відповідає неявним очікуванням планувальника. Оцінювач відхиляє його на основі власних неявних стандартів, але не може сформулювати, що конкретно не так — просто «це не відчувається правильним». Генератор повторює спроби наосліп через розпливчасті причини відхилення. Цикл повторюється 3–4 рази, займає близько 45 хвилин і ледь дає прийнятний результат.-**З повною спостережуваністю:** Планувальник виводить sprint-контракт із переліком компонентів для модифікації, стандартів верифікації для кожного та виключень (наприклад, без стилів для друку). Генератор реалізує відповідно до контракту, а спостережуваність runtime фіксує процес завантаження та застосування стилів кожного компонента. Оцінювач використовує рубрику оцінювання для покрокової оцінки кожного виміру з конкретними доказами: «Контраст кольору кнопки недостатній (стандарт WCAG AA 4.5:1, виміряно 2.1:1).» Одна ітерація дає якісний результат приблизно за 15 хвилин.+**З повною спостережуваністю:** Планувальник виводить sprint-контракт із переліком компонентів для модифікації, стандартів верифікації для кожного та виключень (наприклад, без стилів для друку). Генератор реалізує відповідно до контракту, а спостережуваність runtime фіксує процес завантаження та застосування стилів кожного компонента. Оцінювач використовує рубрику оцінювання для покрокової оцінки кожного виміру з конкретними доказами: «Контраст кольору кнопки недостатній (стандарт WCAG AA 4.5:1, виміряно 2.1:1).» Одна ітерація дає якісний результат приблизно за 15 хвилин. [W3C: contrast minimum](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)Триразова різниця в ефективності. Єдина змінна — спостережуваність.@@ -120,7 +122,9 @@ flowchart LRСтворіть трейс для кожної сесії harness, спан для кожного завдання й під-спани для кожного кроку верифікації. Використовуйте стандартні атрибути для анотування ключової інформації. Так дані спостережуваності інтегруються зі стандартними ланцюжками інструментів (Jaeger, Zipkin).-## Експеримент Anthropic із триагентною архітектурою+## Навчальний приклад++> Навчальна ілюстрація: сценарій і числа є пояснювальними припущеннями, не вимірюваннями опублікованого експерименту.У березні 2026 року Anthropic опублікував систематичний harness-експеримент. Вони запускали одне й те саме завдання («побудувати браузерний DAW за допомогою Web Audio API») із трьома різними архітектурами й записували детальні дані по кожній фазі:@@ -155,7 +159,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.mdindex 8eed39e..a7cf854 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@@ -5,6 +5,8 @@# Лекція 12. Залишайте чистий стан наприкінці кожної сесії+> Інженерні орієнтири: числа — регульовані навчальні значення, не доведені пороги. Кількість токенів залежить від токенізатора й змісту, не лише рядків.+Ваш агент працює цілий день, змінює 20 файлів, комітить код, і сесія завершується. Наступна сесія стартує і одразу виявляє: збірка зламана, тести червоні, тимчасові debug-файли розкидані скрізь, список функцій не оновлено, а прогрес повністю непрозорий. Перші 30 хвилин нової сесії витрачаються виключно на те, щоб «з'ясувати, що ж насправді зробила попередня сесія».Як OpenAI, так і Anthropic чітко стверджують: **довгострокова надійність залежить від операційної дисципліни, а не лише від успіху одного запуску.** Якість стану наприкінці кожної сесії безпосередньо визначає ефективність наступної.@@ -15,7 +17,7 @@Під час п'яти місяців експериментів із Codex OpenAI помітила дещо разюче: **агенти копіюють патерни, що вже є в репозиторії, навіть коли ці патерни непослідовні або неоптимальні.** З часом таке копіювання неминуче призводить до деградації. Перша людина залишає чашку кави в загальному просторі; друга вирішує «і так уже безлад» та залишає ще одну; через тиждень стіл завалений чашками. З кодовою базою відбувається те саме.-Команда OpenAI спочатку витрачала 20% кожної п'ятниці на ручне прибирання «AI-мотлоху», але такий підхід явно не масштабується. Зрештою вони дійшли до систематичного рішення:+OpenAI відводила п’ятниці на прибирання: один робочий день, 20% тижня, не 20% п’ятниці. [OpenAI](https://openai.com/index/harness-engineering/)1. **Закодувати «золоті правила» в репозиторій**: правила на кшталт «надавайте перевагу спільному utility-пакету перед написаними нашвидкуруч допоміжними функціями» (тримайте інваріанти централізовано) і «не вгадуйте наосліп структури даних» (валідуйте межі або покладайтеся на типізовані SDK). Ці правила конкретні, механічні та автоматично перевірювані.2. **Встановити регулярні робочі процеси очищення**: флот фонових завдань Codex, які регулярно сканують відхилення, оновлюють оцінки якості та відкривають цільові PR рефакторингу. Більшість можна переглянути й автоматично злити за хвилину.@@ -43,7 +45,7 @@ flowchart LRFix --> Build```-Але й цього недостатньо. Поточний прогрес має бути зафіксований у машинозчитуваних артефактах: виконані підзавдання з їхніми критеріями проходження, підзавдання в процесі виконання з поточним станом, а також ті, що ще не розпочато. Хороші записи прогресу можуть скоротити час діагностики при запуску сесії на 60–80%. Тимчасові артефакти — debug-логи, тимчасові файли, закоментований код, маркери TODO — також потрібно прибирати, оскільки вони підвищують когнітивне навантаження для наступної сесії. Стандартний шлях запуску теж має залишатися робочим. Чи може наступна сесія приступити до роботи без ручного втручання? Ініціалізація середовища, завантаження кодової бази, отримання контексту, вибір задачі — жоден із цих шляхів не може бути зламаний.+Записуйте прогрес і перевірки у версійовані файли, щоб наступна сесія могла перевірити стан. Джерело описує механізм без відсоткового скорочення часу запуску. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)```mermaidflowchart LR@@ -72,6 +74,8 @@ flowchart LRГірше того, кожна сесія має власні цільові завдання. Нова сесія існує для нової роботи, а не для прибирання безладу попередньої. Вона проігнорує хаос і почне нову роботу поверх нього, додаючи ще більше хаосу. Це петля позитивного зворотного зв'язку ентропії.+> Навчальна ілюстрація: сценарій і числа є пояснювальними припущеннями, не вимірюваннями опублікованого експерименту.+Цифри говорять самі за себе. Проєкт, що розроблявся з агентами 12 тижнів без стратегії очищення:- Тиждень 1: рівень проходження збірки 100%, рівень проходження тестів 100%, запуск нової сесії 5 хв@@ -84,8 +88,6 @@ flowchart LR- Тиждень 1: 100%, 100%, 5 хв- Тиждень 12: 97%, 95%, 9 хв-Після 12 тижнів: рівень проходження збірки відрізняється на 29 відсоткових пунктів, час запуску нової сесії — на 85%. Це не теорія — це спостережувана різниця.-## Як це зробити### 1. Чистий стан — необхідна умова завершення@@ -137,7 +139,7 @@ flowchart LRКожен компонент harness існує тому, що модель не могла самостійно надійно виконати щось. Але з покращенням моделей ці припущення застарівають.-Експерименти Anthropic продемонстрували це безпосередньо. Початковий harness включав механізм розбивки на спринти — ділення роботи на невеликі частини для того, щоб Sonnet 4.5 виконував їх по одній. Коли вийшов Opus 4.6, нативні можливості моделі могли самостійно обробляти декомпозицію роботи, що зробило побудову спринтів зайвими накладними витратами. Після видалення цього компонента агент-будівник міг безперервно працювати понад дві години без відхилень — і насправді ставав плавнішим.+Таблиця стосується оновленого harness з Opus 4.6: одна архітектура з трьома агентами. Поділ на спринти прибрали. Planner задає специфікацію, builder реалізує, evaluator перевіряє застосунок і передає відгуки наступному циклу. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)Але з евалюатором ситуація була іншою. Навіть із посиленими можливостями Opus 4.6, коли задачі наближалися до межі можливостей моделі, евалюатор усе ще давав реальну цінність — виявляв відсутній функціонал і заглушки в реалізації генератора. Це означає, що евалюатор — не фіксоване рішення «так/ні»; він залежить від того, де складність задачі знаходиться відносно можливостей моделі.@@ -162,7 +164,9 @@ npm run test # Verify cleanup didn't break anything**Застереження**: це безвідповідально в середовищі з низькою пропускною здатністю. Але коли вихід агента значно перевищує увагу людини, це часто правильний компроміс. Ключовий критерій: **середня вартість виправлення бага проти середньої вартості очікування, доки людина переглядає PR.** Коли перше нижче другого — швидке злиття є правильним рішенням.-## Реальний кейс+## Навчальний приклад++> Навчальна ілюстрація: сценарій і числа є пояснювальними припущеннями, не вимірюваннями опублікованого експерименту.Electron-застосунок, що розроблявся з агентами 12 тижнів, порівняння двох підходів:@@ -170,8 +174,6 @@ Electron-застосунок, що розроблявся з агентами 1**Зі стратегією очищення** (експериментальна група): повна перевірка чистого стану наприкінці кожної сесії плюс щотижневий цикл очищення. Тиждень 12, рівень проходження збірки 97%, рівень проходження тестів 95%, запуск нової сесії 9 хв, 11 застарілих артефактів.-До тижня 12 рівень проходження збірки в експериментальній групі був вищим на 29 відсоткових пунктів, рівень проходження тестів — на 34 пункти, а час запуску нової сесії — на 85% нижчим. Кожна сесія витрачала додаткові 5 хвилин на очищення, але за 12 тижнів це заощадило десятки годин хаосу.-## Головні висновки- **Чистий стан — необхідна умова завершення сесії** — не опціональне прибирання, а частина «визначення завершеності».diff --git a/docs/uk/lectures/lecture-13-loop-engineering/index.md b/docs/uk/lectures/lecture-13-loop-engineering/index.mdindex e5f096e..3fd6297 100644--- a/docs/uk/lectures/lecture-13-loop-engineering/index.md+++ b/docs/uk/lectures/lecture-13-loop-engineering/index.md@@ -5,6 +5,8 @@# Лекція 13. Від ручного введення промптів до автономних циклів+> Інженерні орієнтири: числа — регульовані навчальні значення, не доведені пороги. Кількість токенів залежить від токенізатора й змісту, не лише рядків.+Все, що ви вивчили у перших дванадцяти лекціях, спирається на одному припущенні: **ви сидите за клавіатурою і вводите інструкції одну за одною.**Ви написали `AGENTS.md` (Лекції 1–4), створили управління станом (Лекції 5–6), обмежили обсяг за допомогою списків функцій (Лекції 7–8), залишали чисті передачі наприкінці сесій (Лекції 9, 12) та зробили середовище виконання спостережуваним (Лекції 10–11). Але тригером для всього цього завжди були ви. Агент ніколи сам не вирішував, коли почати роботу — бо ніхто не натиснув «старт».@@ -96,7 +98,13 @@ Loop Engineering, тема цієї лекції — не про якусь од> **Loop engineering — це заміна себе як людини, яка пише промпти для агента. Ви проектуєте систему, яка робить це замість вас.**-Черний розкрив цифри: протягом понад 30 послідовних днів усі внески коду в Claude Code були зроблені автономно ШІ — 259 злитих PR, понад 80% продуктивного коду, написаного Claude, і 76% успішності у відкритих програмних завданнях.+Boris Cherny · 2025-12-27++| PR | Git commits | + LoC | − LoC | Model |+| --- | --- | --- | --- | --- |+| 259 / 30 days | 497 | 40,000 | 38,000 | Claude Code + Opus 4.5 |++Особистий результат, повідомлений автором, не показник benchmark і не доказ відсутності людського контролю. [Boris Cherny](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)Троє людей. Один тиждень. Однаковий висновок. Не тому що вони координувалися — а тому що інфраструктура тихо перетнула поріг. Агенти стали достатньо надійними, щоб виконувати нетривіальні завдання без нагляду. Примітиви планування (`/loop`, `/goal`, cron) тепер вбудовані в інструменти. Вартість одного запуску агента впала достатньо низько, щоб запускати його повторно за таймером і не вважати це марнотратством. Коли всі частини на місці, хід, який їх поєднує, стає очевидним для всіх одночасно.@@ -267,7 +275,7 @@ flowchart TDЦе вже не один запуск агента. Це безперервно працююча система, яка прокидається кожного ранку, самостійно прибирає на робочому місці і ставить те, що потребує вашої уваги, перед вами. Ваша роль стає такою: **переглядати вміст вхідної скриньки, приймати рішення, і коли ви помічаєте патерн, з яким система не може впоратися, уточнювати навички та правила.**-Черний використав цей патерн, щоб злити 259 PR за 30 днів, жодного разу не відкриваючи IDE. Інженери OpenAI використали той самий патерн, щоб вручну побудувати бета-продукт приблизно на мільйон рядків — жодного разу не написавши рядок коду самостійно.+Особистий результат, повідомлений автором, не показник benchmark і не доказ відсутності людського контролю.## Розділення генератора/оцінювача: чому ви не можете дозволити моделі оцінювати власну роботу@@ -293,7 +301,7 @@ flowchart TDЯкщо ви хочете побачити, як виглядає добре спроектований, реально працюючий цикл, [autoresearch Karpathy](https://github.com/karpathy/autoresearch) — це підручниковий приклад.-У березні 2026 року Карпатський випустив Python-проект на 630 рядків. Дайте йому один GPU і напрямок досліджень, і він працює всю ніч — виконуючи сотні експериментів навчання ML, залишаючи лише ті, які дійсно покращують результат. Проект набрав 66 000+ зірок протягом кількох днів після випуску.+[Karpathy: autoresearch](https://github.com/karpathy/autoresearch) · [announcement](https://x.com/karpathy/status/2030371219518931079)### Три файли, три ролі@@ -343,8 +351,6 @@ flowchart TD8b --> 9```-Він виконує приблизно 12 експериментів на годину. Нічний запуск (8 годин) — це близько 100 експериментів. Сам Карпатський запускав його протягом 2 днів — ~700 експериментів.-Фіксований 5-хвилинний бюджет реального часу — ключовий дизайнерський вибір — незалежно від того, що агент змінює, кожен експеримент займає рівно стільки ж часу. Це означає, що усі результати можна безпосередньо порівнювати за однакового бюджету часу — жодних суперечок про «цей працював довше, тому він кращий».### Вивід: що ви бачите, коли прокидаєтеся@@ -359,6 +365,8 @@ flowchart TDКожен окремий експеримент — успішний чи невдалий — логується:+> Навчальна ілюстрація: сценарій і числа є пояснювальними припущеннями, не вимірюваннями опублікованого експерименту.+```timestamp commit_hash val_bpb vram_mb description--------- ------------- ---------- ---------- ----------------------------@@ -375,11 +383,8 @@ timestamp commit_hash val_bpb vram_mb description### Що він насправді знайшов-Результати початкового 2-денного запуску Карпатського з ~700 експериментами:--- З ~700 спроб знайдено приблизно **20 дійсних поліпшень, що складаються**-- Час навчання nanochat на рівні GPT-2 на 8×H100 зменшився з **2,02 години → 1,80 години**, приблизно **на 11% швидше**-- Знахідки включали: корекції швидкості навчання, налаштування оптимізатора, заміни активації, оптимізації патернів уваги тощо.+- Час навчання nanochat на рівні GPT-2 на 8×H100 зменшився з **2,02 години → 1,80 години**, приблизно **на 10.89% швидше**+- Знахідки включали: корекції швидкості навчання, налаштування оптимізатора, заміни активації, оптимізації патернів уваги тощо. [Karpathy: leaderboard commit](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b) · [tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)Чи були усі поліпшення земними відкриттями? Ні. Більшість були малими оптимізаціями, що складалися разом. Але ці 20 дійсних поліпшень зайняли б у людського дослідника тижні ручної роботи — агент зробив це за 48 годин.@@ -399,7 +404,7 @@ timestamp commit_hash val_bpb vram_mb description### 2. Розуміннява гниль-Чим швидше цикл випускає код, тим далі ваше розуміння власної кодової бази відходить від реальності. У команди Черного 80% коду було написано агентами — що означає, що більша частина коду команди не була написана людиною. Якщо ви не читаєте і не використовуєте те, що виробляє цикл, ваше розуміння постійно погіршується. **Швидкі цикли вимагають швидкого читання.**+Виробничі результати не ізолюють одну причину. Оцінки стосуються зазначених моделі, scaffold, даних і умов, не будь-якого реального завдання.### 3. Когнітивна здачаdiff --git a/docs/uk/lectures/lecture-14-graph-engineering/index.md b/docs/uk/lectures/lecture-14-graph-engineering/index.mdindex bb5d338..8f46ad3 100644--- a/docs/uk/lectures/lecture-14-graph-engineering/index.md+++ b/docs/uk/lectures/lecture-14-graph-engineering/index.md@@ -261,7 +261,7 @@ run(graph, entry={"requirements": "виправити баг на сторінц**Ті, що з'явилися після публікації концепції**-- [GraphArc](https://github.com/CodeGraphContext/grapharc) (2026-08-02): називає себе «першою живою реалізацією Graph Engineering». Він перетворює виконання агента з trace, захованого в логах, на **інтерактивну графу оркестрації в реальному часі** — кожен агент, кожна залежність, кожна точка рішення намальовані, і ти видиш увесь граф до виконання, підтверджуєш (можна навіть подивитися з телефона), а потім відпускаєш. Автор робив графові інструменти для 4000+ розробників, напрямок — «спостережуваність, можливість налагодження, інженерна міцність». Дуже новий, функціонально ще в ранній стадії.+- [GraphArc](https://github.com/CodeGraphContext/grapharc)**Ті, що існували до публікації концепції (вони не називаються Graph Engineering, але саме ними ти будеш користуватися, коли будуватимеш)**@@ -346,4 +346,4 @@ run(graph, entry={"requirements": "виправити баг на сторінц4. **Оцінка за п'ятьма критеріями:** обери завдання, яке ти обмірковуєш «графізувати», і оціни його по пунктах за п'ятьма критеріями. Граф вартий малювання, якщо виконано принаймні три. Якщо менше трьох — йому потрібен кращий workflow-скрипт, а не граф заради графа.-5. **Перетвори `graph.md` на виконувану програму:** за шістьма кроками з розділу «Побудова свого першого графа з нуля» цієї лекції реалізуй намальований maker-checker граф так, щоб він запрацював (реалізація для довідки: `code/maker_checker_graph.py`, написаний на LangGraph). Шість кроків не пропускай: визначити стан → перелічити вузли → з'єднати ребра → написати маршрутизацію → повісити checkpoint → запустити. Після запуску порівняй `graph.md` і код і знайди перше місце, де вони не збігаються, і поясни, чому не збігаються — граф намальовано неправильно чи код написано неправильно?\ No newline at end of file+5. **Перетвори `graph.md` на виконувану програму:** за шістьма кроками з розділу «Побудова свого першого графа з нуля» цієї лекції реалізуй намальований maker-checker граф так, щоб він запрацював (реалізація для довідки: `code/maker_checker_graph.py`, написаний на LangGraph). Шість кроків не пропускай: визначити стан → перелічити вузли → з'єднати ребра → написати маршрутизацію → повісити checkpoint → запустити. Після запуску порівняй `graph.md` і код і знайди перше місце, де вони не збігаються, і поясни, чому не збігаються — граф намальовано неправильно чи код написано неправильно?diff --git a/docs/uk/resources/reference/index.md b/docs/uk/resources/reference/index.mdindex ff36797..b07632d 100644--- a/docs/uk/resources/reference/index.md+++ b/docs/uk/resources/reference/index.md@@ -73,6 +73,11 @@ harness. Цей розділ містить лише джерела, тіло я- [On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents](https://arxiv.org/html/2601.20404v2): gpt-5.2-codex; 10 repos / 124 PR tasks; Table 1.+- [Anthropic: Sonnet 4.5 — SWE-bench Verified methodology (2025-09-29)](https://www.anthropic.com/news/claude-sonnet-4-5)+- [Boris Cherny: personal 30-day production report (2025-12-27)](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)+- [Karpathy: measured autoresearch leaderboard improvement](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b)+- [Karpathy: two-day autonomous tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)+## Рекомендований порядок читання1. `method-map.md`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.mdindex 53b5c91..8ee5c39 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,17 +9,30 @@ Oʻzingizni AI olamida tajribali deb hisoblaysiz — Claude Pro obunangiz bor, GBirinchi 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.+Claude Sonnet 4.5 · 2025-09-29 · SWE-bench Verified++| Score | Tasks | Trials | Scaffold |+| --- | --- | --- | --- |+| 77.2% | 500 | 10 | bash + string replacement |++Ishlab chiqarish natijalari bitta sababni ajratmaydi. Benchmark natijalari ko‘rsatilgan model, scaffold, ma’lumot va baholash sharoitlariga tegishli. [Anthropic: methodology](https://www.anthropic.com/news/claude-sonnet-4-5)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.+> Model va prompt bir xil, vaqt va xarajat budjetlari boshqa. Bitta komponentni ajratgan teng budjetli tajriba emas. Asosiy o‘yin ishlagan, ammo xatolar qolgan. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++Model va prompt bir xil, vaqt va xarajat budjetlari boshqa. Bitta komponentni ajratgan teng budjetli tajriba emas. Asosiy o‘yin ishlagan, ammo xatolar qolgan. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++| Opus 4.5 | Duration | USD |+| --- | --- | --- |+| Solo | 20 min | 9 |+| Full harness | 6 h | 200 |Ular modelni oʻzgartirmadi. Opus 4.5 hamon Opus 4.5 edi. Oʻzgargan narsa — ot anjomlari.-OpenAIʼning 2025-yilgi harness engineering maqolasi buni ochiq aytadi: yaxshi tuzilgan harnessʼga ega repozitoriyadagi Codex “ishonchsiz”dan “ishonchli”ga oʻtadi. Eʼtibor bering — “biroz yaxshi” emas, sifat jihatidan tubdan boshqacha. Bu xuddi zotli otga oʻxshaydi: mos ot anjomlarisiz minib boʻladi, lekin uzoqqa bormaysiz, tez ham yura olmaysiz, yiqilishingiz esa hech kimni ajablantirmaydi. Harness — aynan oʻsha toʻliq ot anjomlari; **model ogʻirliklaridan tashqaridagi barcha muhandislik infratuzilmasi.**+Ishlab chiqarish natijalari bitta sababni ajratmaydi. Benchmark natijalari ko‘rsatilgan model, scaffold, ma’lumot va baholash sharoitlariga tegishli. [OpenAI: 2026-02-11](https://openai.com/index/harness-engineering/)## Agentlar aslida qayerda tiqilib qoladi@@ -39,9 +52,9 @@ Bir necha sessiyaga choʻzilgan uzun vazifalar yana ham yomonroq — oldingi sesBu ssenariylarni nazarda tutsak, quyidagi atamalar endi shunchaki jargon emas — har biri aniq muvaffaqiyatsizlik turini nomlaydi:-- **Capability Gap (Imkoniyatlar tafovuti)**: Modelning benchmark natijalari va haqiqiy vazifalarda koʻrsatadigan natijalari oʻrtasidagi katta tafovut. SWE-bench Verifiedʼda 50–60% muvaffaqiyat darajasi haqiqiy muammolarning deyarli yarmi hal qilinmasligini bildiradi.+- Ishlab chiqarish natijalari bitta sababni ajratmaydi. Benchmark natijalari ko‘rsatilgan model, scaffold, ma’lumot va baholash sharoitlariga tegishli.- **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.- **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,17 +86,19 @@ 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.+Ishlab chiqarish natijalari bitta sababni ajratmaydi. Benchmark natijalari ko‘rsatilgan model, scaffold, ma’lumot va baholash sharoitlariga tegishli. [OpenAI: 2026-02-11](https://openai.com/index/harness-engineering/)-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.+Ishlab chiqarish natijalari bitta sababni ajratmaydi. Benchmark natijalari ko‘rsatilgan model, scaffold, ma’lumot va baholash sharoitlariga tegishli.Boshlanishdagi rivoj kutilganidan sekinroq boʻldi. Codexning imkoniyati yetmagani uchun emas, balki muhit yetarlicha toʻliq emas edi — agent yuqori darajadagi maqsadlarni oldinga siljitish uchun zarur vositalar, abstraksiyalar va ichki strukturalarni topa olmas edi. Muhandislarning ishi quyidagicha oʻzgardi: katta maqsadlarni kichik qurilish bloklariga (dizayn, kod, koʻrib chiqish, test) boʻlib chiqish, agentga ularni yigʻishga ruxsat berish, soʻng oʻsha bloklardan foydalanib murakkabroq vazifalarni ochish. Biror narsa yiqilganda yechim deyarli hech qachon “yana qattiqroq harakat qil” emas edi — “agentda qaysi imkoniyat yetishmayapti va biz uni qanday qilib tushunarli va bajariladigan qilamiz?” edi.-Bu tajriba mazkur maʼruzaning asosiy tezisini bevosita isbotlaydi: **bir xil model qoʻshimcha tuzilmasiz muhitda va toʻliq harnessʼga ega muhitda tubdan farq qiluvchi natija beradi.** Model oʻzgarmadi. Muhit oʻzgardi.+Ishlab chiqarish natijalari bitta sababni ajratmaydi. Benchmark natijalari ko‘rsatilgan model, scaffold, ma’lumot va baholash sharoitlariga tegishli.> Manba: [OpenAI: Harness engineering — agent ustuvor dunyoda Codexdan foydalanish](https://openai.com/index/harness-engineering/)-## Yanada amaliy misol+## O‘quv misoli++> O‘quv misoli: vaziyat va raqamlar tushuntirish uchun faraz qilingan, chop etilgan tajriba o‘lchovlari emas.Bir jamoa Claude Sonnetʼdan foydalanib oʻrta hajmdagi Python web ilovasiga (FastAPI + PostgreSQL + Redis, ~15 000 qator kod) yangi API endpoint qoʻshdi.@@ -109,6 +124,8 @@ Ular modelni oʻzgartirmadi. Ular harnessʼni oʻzgartirdi.- [SWE-bench Leaderboard](https://www.swebench.com/)- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)+- [Anthropic: Sonnet 4.5 SWE-bench methodology, 2025-09-29](https://www.anthropic.com/news/claude-sonnet-4-5)+## Mashqlar1. **Solishtirish tajribasi**: Oʻzingiz yaxshi biladigan kod bazasini va sezilarli oʻzgartirish vazifasini tanlang. Avval agentni hech qanday harness yordamisiz ishga tushiring va muvaffaqiyatsizliklarni qayd eting. Keyin aniq tekshirish buyruqlari bilan `AGENTS.md` qoʻshing va aynan oʻsha agent bilan qayta ishga tushiring. Natijalarni solishtiring va har bir muvaffaqiyatsizlikni beshta himoya qatlamlaridan biriga bogʻlang.diff --git a/docs/uz/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/uz/lectures/lecture-02-what-a-harness-actually-is/index.mdindex b9fd48e..3677a30 100644--- a/docs/uz/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/uz/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -70,7 +70,9 @@ Qandaydir bir quyi tizimning yoʻqligi, xuddi oshxonada qaysidir funksional hudu**Harness komponentlari qiymatini oʻlchash**: modelni oʻzgarmas saqlagan holda komponentlarni olib tashlash tajribasidan foydalaning. Modelni oʻzgarmas qoldiring, quyi tizimlarni birma-bir olib tashlang va qaysi birining olib tashlanishi unumdorlikning eng katta pasayishiga olib kelishini oʻlchang. Eng katta pasayish shu vazifada chegaraviy hissasi eng yuqori komponentni koʻrsatadi; bu avtomatik ravishda haqiqiy toʻsiqni anglatmaydi. Deyarli nol pasayish ham izoh talab qiladi: komponent ortiqcha boʻlishi, yomon loyihalangan boʻlishi yoki bu vazifada yetarli darajada ishga tushmagan boʻlishi mumkin. Toʻsiqni tashxislash uchun avval muvaffaqiyatsizlik jurnallari va sababga bogʻlashdan foydalaning, olib tashlash tajribasini esa yordamchi dalil sifatida talqin qiling: muvaffaqiyatsizlik noaniq vazifa niyati, yetishmagan kontekst, qayta tiklanmaydigan muhit, tekshiruv qayta aloqasi yoʻqligi yoki uzilgan holat boshqaruvi sabablimi?-## Jamoaning hayotiy misoli+## O‘quv misoli++> O‘quv misoli: vaziyat va raqamlar tushuntirish uchun faraz qilingan, chop etilgan tajriba o‘lchovlari emas.Bir jamoa TypeScript + React asosidagi frontend ilovasida (~20,000 qator kod) GPT-4oʼdan foydalandi. Ular toʻrtta bosqichdan oʻtishdi — aslini olganda oshxona jihozlarini birma-bir qoʻshib chiqishdi:diff --git a/docs/uz/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/uz/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdindex 77309b2..b319fe7 100644--- a/docs/uz/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md+++ b/docs/uz/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -5,6 +5,8 @@# 3-maʼruza. Repozitoriyni yagona haqiqat manbaiga aylantiring+> Muhandislik tavsiyasi: raqamli chegaralar sozlanadigan o‘quv qiymatlari, tajribada tasdiqlangan chegaralar emas. Token soni faqat qatorga emas, tokenizer va mazmunga bog‘liq.+Jamoangizning arxitektura qarorlari Confluence, Slack, Jira va bir nechta tajribali muhandislarning boshida tarqalib ketgan. Odamlar uchun bu amallab ishlaydi — siz hamkasbingizdan soʻrashingiz, chat tarixini qidirishingiz, hujjatlarni titkilab chiqishingiz mumkin. Agar boshqa hech narsa yordam bermasa, tanaffus xonasida kimnidir burchakka taqab soʻrab olasiz. Lekin AI agent uchun repozitoriyda mavjud boʻlmagan maʼlumot shunchaki yoʻq degani.Bu mubolagʻa emas. Agentʼning kiruvchi maʼlumotlari (inputs) aslida nima ekanligini oʻylab koʻring: system promptʼlar va vazifa tavsiflari, repozitoriydagi fayllar tarkibi va vositalardan chiqqan natijalar. Bori shu. Sizning Slack tarixingiz, Jira tiketlari, Confluence sahifalari va juma kuni tushdan keyin qahva ustida hamkasbingiz bilan muhokama qilgan arxitektura qaroringiz — bularning birortasini agent koʻra olmaydi. U “borib birovdan soʻray” yoki “chat tarixini qidiray” deya olmaydi. U repozitoriy ichiga qamab qoʻyilgan muhandisdir — undan tashqaridagi barcha narsalar haqida u hech narsani bilmaydi.diff --git a/docs/uz/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/uz/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdindex 809df2b..60350df 100644--- a/docs/uz/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md+++ b/docs/uz/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -5,6 +5,8 @@# 4-maʼruza. Yoʻriqnomalarni fayllar boʻylab ajrating+> Muhandislik tavsiyasi: raqamli chegaralar sozlanadigan o‘quv qiymatlari, tajribada tasdiqlangan chegaralar emas. Token soni faqat qatorga emas, tokenizer va mazmunga bog‘liq.+Siz harness muhandisligiga jiddiy yondashdingiz — tabriklaymiz. Siz `AGENTS.md` faylini yaratdingiz va oʻzingiz oʻylay olgan barcha qoidalar, cheklovlar va olingan saboqlarni uning ichiga joyladingiz. Bir oydan soʻng fayl 300 qatorga, ikki oydan soʻng 450 qatorga, uch oydan soʻng esa 600 qatorga yetdi. Keyin siz agentʼning samaradorligi aslida yomonlashayotganini seza boshlaysiz — oddiy bugʼni tuzatish uchun agent juda koʻp kontekstni hech qanday aloqasi boʻlmagan deploy yoʻriqnomalarini oʻqishga sarflaydi; 300-qatorda koʻmilgan muhim xavfsizlik cheklovi mutlaqo eʼtiborsiz qoldiriladi; kod yozish uslubi boʻyicha bir-biriga zid uchta qoida mavjudligi sababli, agent har safar oʻzboshimchalik bilan ulardan birini tanlaydi.Bu “ulkan yoʻriqnoma fayli” tuzogʻidir. Bu xuddi chamadonni haddan tashqari toʻldirishga oʻxshaydi — hamma narsa foydali koʻrinadi, shuning uchun zanjirsimon yopqich yorilib ketgudek boʻlguncha tiqib tashlaysiz. Ichki kiyimingizni almashtirish uchun butun sumkani boʻshatishingiz kerak boʻladi. Siz toʻla chamadonni koʻtarib yurasiz, lekin aslida uning ichidagilarning faqat uchdan bir qismini ishlatasiz, xolos.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.mdindex 3adac12..ea26dfb 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@@ -5,6 +5,8 @@# 5-maʼruza. Sessiyalar oʻrtasida kontekstni saqlab qoling+> Muhandislik tavsiyasi: raqamli chegaralar sozlanadigan o‘quv qiymatlari, tajribada tasdiqlangan chegaralar emas. Token soni faqat qatorga emas, tokenizer va mazmunga bog‘liq.+Siz Claude Codeʼdan toʻliq bitta funksiyani (feature) yaratishni soʻraysiz. U 30 daqiqa ishlaydi, ishning koʻp qismini bajaradi, lekin kontekst tugab bormoqda. Siz davom ettirish uchun yangi sessiya boshlaysiz — va u oʻtgan safar qanday qarorlar qabul qilinganini, nima uchun B varianti A variantdan afzal koʻrilganini, qaysi fayllar allaqachon oʻzgartirilganini yoki testlar qanday holatda ekanini eslay olmasligini bilib olasiz. U loyihani qayta oʻrganish uchun 15 daqiqa sarflaydi va oldingi yondashuvga zid ishlarni qilishi mumkin.Tasavvur qiling, siz har tong uygʻonganda hamma narsani unutib qoʻyadigan usta boʻlsangiz. Siz butun qurilish maydoni bilan qaytadan tanishib chiqishingiz kerak boʻladi — qaysi devor yarim qurilgan, nima uchun koʻk gʻishtlar oʻrniga qizil gʻishtlar tanlangan, vodoprovod quvurlari qayergacha yetib kelgan. Eng yomoni, kecha oʻrnatib boʻlingan derazani — uning oʻrnatilganligini eslay olmaganingiz uchungina — buzib tashlashingiz mumkin.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.mdindex 68075e6..872dac7 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@@ -5,6 +5,8 @@# 6-maʼruza. Har bir agent sessiyasidan oldin inisializatsiya qiling+> Muhandislik tavsiyasi: raqamli chegaralar sozlanadigan o‘quv qiymatlari, tajribada tasdiqlangan chegaralar emas. Token soni faqat qatorga emas, tokenizer va mazmunga bog‘liq.+Siz yangi agent sessiyasini boshlaysiz va “qidiruv funksiyasini qoʻsh” deysiz. U darhol kod yozishga oʻtadi — tahsinga loyiq ishtiyoq. 20 daqiqadan soʻng, test freymvorki toʻgʻri sozlanmaganini bilib qoladi va uni toʻgʻrilash uchun yana 10 daqiqa sarflaydi. Keyin maʼlumotlar bazasi migratsiya skripti formati notoʻgʻri ekani aniqlanadi, yana ovoragarchilik. Oxir-oqibat qidiruv funksiyasi qoʻshiladi, lekin butun sessiya samarasiz boʻldi — chunki vaqtning katta qismi qidiruv funksiyasini yozishga emas, balki “bu loyiha oʻzi qanday ishlashini tushunish”ga sarflandi.Yaxshiroq yondashuv: agentni ishlashga qoʻyib berishdan oldin, bazaviy muhitni tayyorlash, tekshiruv buyruqlarini (verification commands) muvaffaqiyatli oʻtkazish va loyiha strukturasini tushunish uchun alohida bosqich ajrating. Bu xuddi uy qurishga oʻxshaydi — siz poydevor quyib, devorlarni bir vaqtning oʻzida qurmaysiz. Agar shunday qilsangiz, devorlar poydevor qotmasidan oldin koʻtariladi va butun binoni buzib, qaytadan boshlashga toʻgʻri keladi. Avval poydevor quying, uning qotishini kuting, soʻngra devorlarni quring — toza va samarali.@@ -45,7 +47,7 @@ Sessiya byudjeti ham bekorga sarflanadi. Inisializatsiya ishlari (muhitlarni sozEng 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: initializer / coding agent](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)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.@@ -122,7 +124,9 @@ OpenAIʼning Codex harness muhandislik qoʻllanmasi ham “repo operatsion yozuv- [ ] Hamma narsa gitʼga commit qilingan```-## Hayotiy misol+## O‘quv misoli++> O‘quv misoli: vaziyat va raqamlar tushuntirish uchun faraz qilingan, chop etilgan tajriba o‘lchovlari emas.React frontend loyihasi uchun ikkita inisializatsiya yondashuvi: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.mdindex fcfbcb5..8b126c1 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@@ -5,6 +5,8 @@# 7-maʼruza. Agentlar uchun aniq vazifa chegaralarini chizing+> Muhandislik tavsiyasi: raqamli chegaralar sozlanadigan o‘quv qiymatlari, tajribada tasdiqlangan chegaralar emas. Token soni faqat qatorga emas, tokenizer va mazmunga bog‘liq.+Siz Claude Codeʼga “bu loyihaga foydalanuvchi autentifikatsiyasini qoʻsh” deysiz, u esa maʼlumotlar bazasi sxemasini oʻzgartirishdan, marshrutlarni (routes) yozishdan, frontend komponentlarini oʻzgartirishdan boshlaydi va — shu yoʻl-yoʻlakay — xatoliklarni qayta ishlash middlewareʼini (error-handling middleware) refaktoring qilib ketadi. Ikki soatdan keyin tekshirasiz: 12 ta fayl oʻzgartirilgan, 800 qator yangi kod yozilgan, lekin bittayam funksionallik (feature) boshidan oxirigacha (end-to-end) ishlamayapti.Qornidan kattaroq tishlash — bu ibora AI agentlariga juda mos tushadi. Agentlar “bir oz qoʻshimcha ish qilish” impulsi bilan tugʻiladi — ular bir-biriga bogʻliq narsalarni koʻrishadi va ularni shunchaki yoʻl-yoʻlakay hal qilib ketishadi, xuddi supermarketga bir shisha soya sousi uchun kirib, toʻla aravacha bilan chiqib kelgan odam kabi. Muammo shundaki, haddan tashqari koʻp narsa sotib olgan odam shunchaki pulini isrof qiladi; agentlarning bir vaqtning oʻzida juda koʻp ishlarni qilishi esa u ishlarning birortasi ham toʻgʻri oxiriga yetmaydi deganidir.@@ -26,7 +28,7 @@ Claude Codeʼning haqiqiy xatti-harakati buni aniq koʻrsatadi. Unga “foydalanOltita 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: incremental feature work](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## WIP=1 Ish jarayoni (Workflow)@@ -100,7 +102,9 @@ Barcha vazifa holatlarini yozib borish uchun mashina oʻqiy oladigan fayldan (JSHarness VCR (Verified Completion Rate) ni doimiy kuzatib borishi kerak = tekshirilgan vazifalar / faollashtirilgan vazifalar. Agar VCR < 1.0 boʻlsa, yangi vazifa faollashtirilishini bloklang.-## Hayotiy misol+## O‘quv misoli++> O‘quv misoli: vaziyat va raqamlar tushuntirish uchun faraz qilingan, chop etilgan tajriba o‘lchovlari emas.8 ta funksiyaga ega REST API loyihasi, taqqoslangan ikkita strategiya: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.mdindex 13e5cb8..96d9c81 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@@ -5,6 +5,8 @@# 8-maʼruza. Agent nima qilishini cheklash uchun funksiyalar roʻyxatidan foydalaning+> Muhandislik tavsiyasi: raqamli chegaralar sozlanadigan o‘quv qiymatlari, tajribada tasdiqlangan chegaralar emas. Token soni faqat qatorga emas, tokenizer va mazmunga bog‘liq.+Siz agentdan e-tijorat saytini qurishni soʻraysiz. Ishini tugatgandan soʻng, u sizga “tugatdim” deydi. Kodni koʻrib chiqasiz — foydalanuvchi autentifikatsiyasi ishlayapti, lekin savatdagi (shopping cart) “sotib olish” (checkout) tugmasi hech narsa qilmaydi va toʻlov jarayoni (payment flow) umuman ulanmagan. Muammo shundaki: siz unga hech qachon “tugatish” (done) nimani anglatishini aytmagansiz, shuning uchun u oʻzining shaxsiy standartini — “Men juda koʻp kod yozdim va u ancha tugallanganga oʻxshaydi” degan standartni ishlatdi.Koʻpchilikning nazarida funksiyalar roʻyxati (feature lists) shunchaki eslatma (memo) — esdan chiqarmaslik uchun yoziladi, soʻngra bir chetga yigʻishtirib qoʻyiladi. Lekin harness olamida funksiyalar roʻyxati odamlar uchun eslatma emas — u butun harnessʼning umurtqa pogʻonasidir (backbone). Rejalashtiruvchi (scheduler) qaysi vazifani tanlashda unga suyanadi, tekshiruvchi (verifier) yakunlanganligini baholashda unga suyanadi, topshirish hisobotchisi (handoff reporter) xulosalar yaratishda unga suyanadi. Umurtqani sindirsangiz butun tana falaj boʻladi.@@ -22,7 +24,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.+Jarayon va tekshiruvlarni versiyalanadigan fayllarga yozing, keyingi sessiya holatni tekshira olsin. Manba mexanizmni tushuntiradi, boshlash vaqtining foiz kamayishini bermaydi. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## Funksiya holati mashinasi (Feature State Machine)@@ -103,7 +105,9 @@ Agent bitta funksiya holatini toʻgʻridan-toʻgʻri `passing` ga oʻzgartira olHar bir funksiya (feature) bandi “bitta sessiyada tugatilishi mumkin” boʻlgan darajada belgilanishi kerak. Juda keng boʻlsa — tugamaydi; juda kichik boʻlsa — boshqarish qiyinlashadi. “Foydalanuvchi savatga mahsulot qoʻshishi mumkin” — bu toʻgʻri darajalash (granularity). “Savat (shopping cart)ni amalga oshirish (implement qilish)” — juda keng. “Cart modelida name maydonini (field) yaratish” — juda tor. Xuddi goʻshtni kesishga oʻxshaydi — butun boʻlak ham emas, qiyma ham emas.-## Hayotiy misol+## O‘quv misoli++> O‘quv misoli: vaziyat va raqamlar tushuntirish uchun faraz qilingan, chop etilgan tajriba o‘lchovlari emas.10 ta funksiyaga ega boʻlgan e-tijorat (e-commerce) platformasi. Taqqoslangan ikkita kuzatish (tracking) yondashuvi:@@ -111,8 +115,6 @@ 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.-## Asosiy xulosalar- **Funksiyalar roʻyxatlari — bu odamlar uchun eslatma emas, ular harnessʼning umurtqa pogʻonasidir (backbone).** Rejalashtiruvchi, tekshiruvchi va topshirish hisobotchisi barchasi shunga tayanadi.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.mdindex c5974c4..77c1f4e 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@@ -5,6 +5,8 @@# 9-maʼruza. Agentlarni vaqtidan oldin gʻalabani eʼlon qilishdan saqlash+> Muhandislik tavsiyasi: raqamli chegaralar sozlanadigan o‘quv qiymatlari, tajribada tasdiqlangan chegaralar emas. Token soni faqat qatorga emas, tokenizer va mazmunga bog‘liq.+Siz agentdan “parolni tiklash” funksiyasini qoʻshishni soʻraysiz. U maʼlumotlar bazasi sxemasini oʻzgartiradi, API endpointʼini yozadi, elektron pochta andozasini (email template) qoʻshadi, unit testlarni ishga tushiradi (hammasi oʻtadi) va soʻngra sizga ishonch bilan “tugatdim” deydi. Haqiqatda ishlatib koʻrsangiz—parolni tiklash havolasi yuborilmaydi (elektron pochta xizmati sozlamalari yoʻq), maʼlumotlar bazasi migratsiyasi yarmida yiqiladi (sxema noaniqligi), va end-to-end oqimi (flow) biror marta ham ishga tushirib koʻrilmagan.Bu tuygʻu sizga begona boʻlmasa kerak — u imtihon qogʻozini toʻldirib chiqib, birinchi boʻlib oʻziga ishonch bilan topshiradigan, lekin baholar eʼlon qilinganda yiqiladigan talabaga oʻxshaydi. Qogʻozning toʻla boʻlishi javoblar toʻgʻri ekanligini anglatmaydi.@@ -13,6 +15,8 @@ Bu tasodifiy voqea emas. 2017-yildagi ICML konferensiyasida Guo va boshqalarning## Sirpanchiq qiyalik (The Slippery Slope)+> Model va prompt bir xil, vaqt va xarajat budjetlari boshqa. Bitta komponentni ajratgan teng budjetli tajriba emas. Asosiy o‘yin ishlagan, ammo xatolar qolgan. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)+Vaqtidan oldin “tugadim” deyish deyarli har doim bir xil andozada (pattern) kechadi: kod yuzaki qaraganda mantiqli koʻrinadi — sintaksis toʻgʻri, mantiq joyidadek, va statik tahlil (static analysis) aniq xatolarni koʻrsatmaydi. Lekin harness qamrovli runtime tekshiruvni majbur qilmaydi, shu sababli agent uni haqiqatda ishga tushirib koʻrishni oʻtkazib yuboradi yoki faqat qisman testlarni ishga tushiradi. U unit testlarni ishga tushiradi, lekin integratsiya testlarini (integration tests) oʻtkazib yuboradi; u testlarni ishga tushiradi, lekin qamrovni (coverage) tekshirmaydi. Oxir-oqibat, “kod yaxshi koʻrinyapti” degan dalil “funksiya (feature) tugatildi” degan xulosaga asos qilib olinadi. Va imtihon qogʻozi topshiriladi.Har bir bosqichda maʼlumot yoʻqoladi. Vazifa spetsifikatsiyasidan kod implementatsiyasiga, undan esa runtime xatti-harakatigacha, har bir oʻzgarish biroz ogʻish (bias) keltirib chiqarishi mumkin va har bir oʻtkazib yuborilgan tekshiruv bu maʼlumot assimetriyasini kuchaytiradi.@@ -111,7 +115,9 @@ Samarali runtime signallarga quyidagilar kiradi:- Maʼlumotlar bazasiga yozishlar, fayl operatsiyalari va boshqa side effectʼlar toʻgʻrimi?- Vaqtinchalik resurslar tozalandimi?-## Hayotiy misol+## O‘quv misoli++> O‘quv misoli: vaziyat va raqamlar tushuntirish uchun faraz qilingan, chop etilgan tajriba o‘lchovlari emas.**Vazifa**: Foydalanuvchi parolini tiklash (password reset) funksiyasini qoʻshish. Bunga maʼlumotlar bazasi amallari, elektron pochta yuborish va API endpointʼlarini oʻzgartirish kiradi.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.mdindex e249589..a731abc 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@@ -5,6 +5,8 @@# 10-maʼruza. Faqatgina End-to-End testlash chinakam tekshiruvdir+> Muhandislik tavsiyasi: raqamli chegaralar sozlanadigan o‘quv qiymatlari, tajribada tasdiqlangan chegaralar emas. Token soni faqat qatorga emas, tokenizer va mazmunga bog‘liq.+Siz agentdan Electron ilovasiga faylni eksport qilish funksiyasini qoʻshishni soʻraysiz. U render process komponentini, preload skriptini va xizmat qatlami mantigʻini yozadi. Har bir komponent uchun unit testlar ajoyib tarzda oʻtadi. Agent “Tugatildi” deydi. Export tugmasini bosganingizda esa — fayl yoʻli formati notoʻgʻri, progress bar ishlamayapti va katta fayllarni eksport qilish xotira sizib chiqishiga (memory leak) sabab boʻlyapti. Beshta komponent chegarasi muammolari, va unit testlar ularning bittasini ham tutib qola olmagan.Bu xuddi xor (choir) repetitsiyasiga oʻxshaydi — har bir ovoz alohida aytganda mukammal eshitiladi, lekin hammalari birgalikda kuylashganda, sopranolar baslardan yarim takt tezlashib ketadi, joʻr ovoz esa asosiy ohangdan yarim tonda farq qiladi. Har bir qism oʻz-oʻzidan “toʻgʻri”, lekin umumiy ovoz ohangsiz.@@ -116,7 +118,9 @@ FIX: Fayl operatsiyalarini src/preload/file-ops.ts fayliga koʻchiring va ularniHar gal kod review (kodni tekshirish) paytida yangi agent xatosi topilsa, shunga bagʻishlangan yana bitta avtomatlashtirilgan qoida yozing. Oradan bir oy oʻtgach sizning harnessʼingiz bir oy oldingidan koʻra yaxshiroq natija koʻrsatadi. Xuddi repetitsiya jurnaliga oʻxshaydi — navbatdagi darsda eʼtibor qilish uchun xatoliklar jurnali qilinadi. Takroriy eslatish orqali xatolar yoʻqoladi va musiqa uygʻunlasha boradi.-## Hayotiy misol+## O‘quv misoli++> O‘quv misoli: vaziyat va raqamlar tushuntirish uchun faraz qilingan, chop etilgan tajriba o‘lchovlari emas.**Vazifa**: Electron ilovasiga (app) fayl eksporti funksiyasini kiritish. Bunga render jarayoni (UI), preload fayl tizimi proksisi (filesystem proxy) va xizmat koʻrsatish (service) qatlamidagi maʼlumotlarni konversiya qilish (data transformation) kiradi.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.mdindex 3ef3bd9..dbf026b 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@@ -32,7 +32,9 @@ flowchart LRVerdict --> Generator```-## Nega bunday boʻladi+## O‘quv misoli++> O‘quv misoli: vaziyat va raqamlar tushuntirish uchun faraz qilingan, chop etilgan tajriba o‘lchovlari emas.### Kuzatuvchanlikning yoʻqligining haqiqiy badali@@ -44,7 +46,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.+Jarayon va tekshiruvlarni versiyalanadigan fayllarga yozing, keyingi sessiya holatni tekshira olsin. Manba mexanizmni tushuntiradi, boshlash vaqtining foiz kamayishini bermaydi. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)### Claude Code ishtirokidagi hayotiy vaziyat@@ -116,7 +118,9 @@ Har bir vazifa boshlanishidan oldin, yaratuvchi (generator) va baholovchi (evaluHar bir harness sessiyasi uchun bitta treys (trace), har bir vazifa uchun bitta span va har bir tekshirish bosqichi uchun ichki spanʼlar (sub-spans) yarating. Muhim maʼlumotlarni izohlash (annotate) uchun standart atributlardan foydalaning. Shu orqali kuzatuv maʼlumotlari odatiy vositalar (Jaeger, Zipkin) bilan birlashadi.-## Hayotiy misol+## O‘quv misoli++> O‘quv misoli: vaziyat va raqamlar tushuntirish uchun faraz qilingan, chop etilgan tajriba o‘lchovlari emas.Rejalashtiruvchi-yaratuvchi-baholovchi (planner-generator-evaluator) jarayonidan foydalanib “qorongʻu rejim qoʻshish” vazifasini bajaruvchi harness:@@ -136,7 +140,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.**+- Jarayon va tekshiruvlarni versiyalanadigan fayllarga yozing, keyingi sessiya holatni tekshira olsin. Manba mexanizmni tushuntiradi, boshlash vaqtining foiz kamayishini bermaydi.## Qoʻshimcha oʻqish uchundiff --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.mdindex e56e697..2051851 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@@ -5,6 +5,8 @@# 12-maʼruza. Har bir sessiya oxirida toza holat topshiring+> Muhandislik tavsiyasi: raqamli chegaralar sozlanadigan o‘quv qiymatlari, tajribada tasdiqlangan chegaralar emas. Token soni faqat qatorga emas, tokenizer va mazmunga bog‘liq.+## Ushbu maʼruza qanday muammoni hal qiladi?Sizning agentingiz tushdan keyin ishlaydi, 20 ta faylni oʻzgartiradi, kodni commit qiladi va sessiya tugaydi. Keyingi agent sessiyasi ish boshlaydi va birdan shularni aniqlaydi: build yiqilyapti (broken), testlar qizil (yiqilgan), vaqtinchalik debug fayllar sochilib yotibdi, funksiyalar roʻyxati yangilanmagan va ishlarning qay holatdaligi butunlay noaniq. Yangi sessiya birinchi 30 daqiqasini faqatgina “oʻtgan sessiya oʻzi nima qilgandi” degan narsani tushunishga sarflaydi.@@ -54,6 +56,8 @@ flowchart LRDasturiy 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.+> O‘quv misoli: vaziyat va raqamlar tushuntirish uchun faraz qilingan, chop etilgan tajriba o‘lchovlari emas.+Haqiqiy maʼlumotlar soʻzlaydi. Hech qanday tozalash strategiyasisiz agentlar bilan 12 hafta davomida ishlab chiqilgan loyiha:- 1-hafta: Build oʻtish darajasi 100%, testlar oʻtish darajasi 100%, yangi sessiyani boshlash 5 daq@@ -66,8 +70,6 @@ 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.-### Toza holatning besh oʻlchamiToza holat bu shunchaki “kod kompilyatsiya boʻladi” degani emas. U beshta oʻlchamni birgalikda baholaydi:@@ -76,7 +78,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 va tekshiruvlarni versiyalanadigan fayllarga yozing, keyingi sessiya holatni tekshira olsin. Manba mexanizmni tushuntiradi, boshlash vaqtining foiz kamayishini bermaydi. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)**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.@@ -152,7 +154,9 @@ git checkout -- .env.local # Maʼlum boʻlgan barqaror holatga (known state) qanpm run test # Tozalash hech narsani buzmaganini tasdiqlash```-## Hayotiy misol+## O‘quv misoli++> O‘quv misoli: vaziyat va raqamlar tushuntirish uchun faraz qilingan, chop etilgan tajriba o‘lchovlari emas.Ikkita yondashuv bilan 12 hafta davomida agentlar yordamida ishlab chiqilgan Electron ilovasi (app):@@ -160,8 +164,6 @@ 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.-## Asosiy xulosalar- **Toza holat — bu sessiyani tugatish uchun muhim va zarur shartdir** — bu ixtiyoriy “uy tozalash” (housekeeping) ishi emas, balki “bajarilganlik mezonlari (definition of done)”ning bir qismidir.diff --git a/docs/uz/lectures/lecture-13-loop-engineering/index.md b/docs/uz/lectures/lecture-13-loop-engineering/index.mdindex fe6be2e..e8ae682 100644--- a/docs/uz/lectures/lecture-13-loop-engineering/index.md+++ b/docs/uz/lectures/lecture-13-loop-engineering/index.md@@ -5,6 +5,8 @@# 13-maʼruza. Qoʻlda prompt yozishdan avtonom loop'largacha+> Muhandislik tavsiyasi: raqamli chegaralar sozlanadigan o‘quv qiymatlari, tajribada tasdiqlangan chegaralar emas. Token soni faqat qatorga emas, tokenizer va mazmunga bog‘liq.+Birinchi oʻn ikki maʼruzada oʻrgangan hamma narsa bir taxminga tayanadi: **siz klaviatura oldida oʻtirib, birma-bir koʻrsatmalar terasiz.**Siz `AGENTS.md` ni yozdingiz (1–4-maʼruzalar), holat boshqaruvini qurdingiz (5–6-maʼruzalar), funksiyalar roʻyxati bilan skopni chekladingiz (7–8-maʼruzalar), sessiya oxirida toza topshirish qoldirdingiz (9, 12-maʼruzalar) va runtime ni kuzatuvchan qildingiz (10–11-maʼruzalar). Lekin bularning barchasi uchun har doim siz trigger edingiz. Agent hech qachon oʻzi ish boshlashga qaror qilmagan — chunki hech kim "boshlash" tugmasini bosmagan.@@ -84,8 +86,12 @@ Ushbu maʼruza mavzusi boʻlgan Loop Engineering (Loop muhandisligi) hech qandaySiz 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.+> O‘quv misoli: vaziyat va raqamlar tushuntirish uchun faraz qilingan, chop etilgan tajriba o‘lchovlari emas.+## 2026-yil iyun: Bir haftada uchta odam bir xil gʻoyani oldi+> O‘quv misoli: vaziyat va raqamlar tushuntirish uchun faraz qilingan, chop etilgan tajriba o‘lchovlari emas.+2026-yil iyun oyining birinchi haftasida kodlash agentlari infratuzilmasini qurgan uchta amaliyotchilar — bir-birlari bilan maslahatlashmasdan — turli soʻzlar bilan bir xil narsani aytdilar.**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."@@ -96,7 +102,13 @@ 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.+Boris Cherny · 2025-12-27++| PR | Git commits | + LoC | − LoC | Model |+| --- | --- | --- | --- | --- |+| 259 / 30 days | 497 | 40,000 | 38,000 | Claude Code + Opus 4.5 |++Muallif bildirgan shaxsiy ishlab chiqarish, benchmark muvaffaqiyat darajasi yoki inson nazorati yo‘qligining dalili emas. [Boris Cherny](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)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.@@ -267,7 +279,7 @@ flowchart TDBu 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.+Muallif bildirgan shaxsiy ishlab chiqarish, benchmark muvaffaqiyat darajasi yoki inson nazorati yo‘qligining dalili emas.## Generator/Evaluator boʻlinishi: Nega modelni oʻz ishlari baholashiga yoʻl qoʻymaslik kerak@@ -293,7 +305,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.+[Karpathy: autoresearch](https://github.com/karpathy/autoresearch) · [announcement](https://x.com/karpathy/status/2030371219518931079)### Uchta fayl, uchta rol@@ -343,8 +355,6 @@ flowchart TD8b --> 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.-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.### Chiqish: Uyqudan uygʻonganda nima koʻrasiz@@ -359,6 +369,8 @@ Faqat haqiqatan yaxshilagan commitlar main novdasida qoladi. Barcha muvaffaqiyatHar bir eksperiment — muvaffaqiyatli yoki muvaffaqiyatsiz — yozib boriladi:+> O‘quv misoli: vaziyat va raqamlar tushuntirish uchun faraz qilingan, chop etilgan tajriba o‘lchovlari emas.+```timestamp commit_hash val_bpb vram_mb description--------- ------------- ---------- ---------- ----------------------------@@ -375,11 +387,10 @@ Agent nima sinaganini, nima ishlaganini, nima ishlamaganini va keyin nima sinash### Haqiqatan nima topdi-Karpathyʼning dastlabki 2 kunlik, ~700 eksperimentlik ishlashidan olingan natijalar:+- nanochatʼning GPT-2 darajasidagi trening vaqtini 8×H100 da **2.02 soat → 1.80 soat** ga qisqartirdi, taxminan **10.89% tezroq**+- Topilmalar orasida: oʻrganish darajasi sozlamalari, optimizator sozlash, aktivatsiyani almashtirish, diqqat naqshlari optimallashtirish va boshqalar [Karpathy: leaderboard commit](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b) · [tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)-- ~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+> O‘quv misoli: vaziyat va raqamlar tushuntirish uchun faraz qilingan, chop etilgan tajriba o‘lchovlari emas.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.@@ -399,7 +410,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.**+Ishlab chiqarish natijalari bitta sababni ajratmaydi. Benchmark natijalari ko‘rsatilgan model, scaffold, ma’lumot va baholash sharoitlariga tegishli.### 3. Kognitiv taslim boʻlish (Cognitive surrender)diff --git a/docs/uz/lectures/lecture-14-graph-engineering/index.md b/docs/uz/lectures/lecture-14-graph-engineering/index.mdindex a915d77..9e0d553 100644--- a/docs/uz/lectures/lecture-14-graph-engineering/index.md+++ b/docs/uz/lectures/lecture-14-graph-engineering/index.md@@ -261,7 +261,7 @@ Avval chegarani aniq belgilaylik: **Graph Engineering — 2026-yil 18-iyuldan ke**Kontsepsiya eʼlonidan keyin paydo boʻlganlar**-- [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)**Kontsepsiya eʼlonidan oldin mavjud boʻlganlar (ular Graph Engineering deb atalmaydi, lekin siz qurishda aynan ularni ishlatasiz)**@@ -346,4 +346,4 @@ Barcha vazifalar grafik chizishga arzimaydi. Beshta mezon, kamida uchtasi bajari4. **Besh mezon bilan baholash:** "grafiklash" qilish kerakmi yoʻqmi deb qiyinlayotgan bitta vazifani tanlang, besh mezon bilan birma-bir baholang. Kamida uchtasi bajarilgan boʻlsa grafik chizishga arzir. Uchtadan kam boʻlsa, unga aslida yaxshiroq workflow skripti kerak — faqat grafik ishlatish uchun ishlatmang.-5. **graph.md ni bajariladigan dasturga aylantiring:** Ushbu maʼruzadagi "noldan birinchi grafikʼingizni qurish" olti qadamiga koʻra, chizgan maker-checker grafigingizni ishlaydigan grafikka aylantiring (maʼlumotnoma implementatsiyasi: `code/maker_checker_graph.py`, LangGraph bilan yozilgan). Olti qadamni oʻtkazib yubormang: holatni aniqlash → tugunlarni roʻyxatlash → chekkalarni ulash → marshrutni yozish → checkpoint oʻrnatish → ishga tushirish. Ishga tushirgach `graph.md` va kodni solishtiring, birinchi mos kelmaydigan joyni toping va nima uchun mos kelmasligini tushuntiring — grafik notoʻgʻri chizilganmi, yoki kod notoʻgʻri yozilganmi?\ No newline at end of file+5. **graph.md ni bajariladigan dasturga aylantiring:** Ushbu maʼruzadagi "noldan birinchi grafikʼingizni qurish" olti qadamiga koʻra, chizgan maker-checker grafigingizni ishlaydigan grafikka aylantiring (maʼlumotnoma implementatsiyasi: `code/maker_checker_graph.py`, LangGraph bilan yozilgan). Olti qadamni oʻtkazib yubormang: holatni aniqlash → tugunlarni roʻyxatlash → chekkalarni ulash → marshrutni yozish → checkpoint oʻrnatish → ishga tushirish. Ishga tushirgach `graph.md` va kodni solishtiring, birinchi mos kelmaydigan joyni toping va nima uchun mos kelmasligini tushuntiring — grafik notoʻgʻri chizilganmi, yoki kod notoʻgʻri yozilganmi?diff --git a/docs/uz/resources/reference/index.md b/docs/uz/resources/reference/index.mdindex 11fb751..fc9d277 100644--- a/docs/uz/resources/reference/index.md+++ b/docs/uz/resources/reference/index.md@@ -59,6 +59,11 @@ Faqatgina 2025-yilga oid umumiy manbalar asosiy roʻyxatdan chiqarildi. Dastlabk- [On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents](https://arxiv.org/html/2601.20404v2): gpt-5.2-codex; 10 repos / 124 PR tasks; Table 1.+- [Anthropic: Sonnet 4.5 — SWE-bench Verified methodology (2025-09-29)](https://www.anthropic.com/news/claude-sonnet-4-5)+- [Boris Cherny: personal 30-day production report (2025-12-27)](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)+- [Karpathy: measured autoresearch leaderboard improvement](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b)+- [Karpathy: two-day autonomous tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)+## Oʻqish boʻyicha tavsiya etilgan ketma-ketlik1. `method-map.md`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.mdindex 6a70fe3..9ec8326 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,17 +5,30 @@# 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.+Claude Sonnet 4.5 · 2025-09-29 · SWE-bench Verified++| Score | Tasks | Trials | Scaffold |+| --- | --- | --- | --- |+| 77.2% | 500 | 10 | bash + string replacement |++Kết quả sản xuất không tách riêng nguyên nhân. Điểm benchmark chỉ áp dụng cho mô hình, scaffold, dữ liệu và điều kiện đánh giá đã nêu. [Anthropic: methodology](https://www.anthropic.com/news/claude-sonnet-4-5)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.+> Cùng mô hình và prompt nhưng khác ngân sách thời gian và chi phí. Không phải thí nghiệm cùng ngân sách tách riêng một thành phần. Chức năng chơi cơ bản hoạt động nhưng vẫn còn lỗi. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++Cùng mô hình và prompt nhưng khác ngân sách thời gian và chi phí. Không phải thí nghiệm cùng ngân sách tách riêng một thành phần. Chức năng chơi cơ bản hoạt động nhưng vẫn còn lỗi. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++| Opus 4.5 | Duration | USD |+| --- | --- | --- |+| Solo | 20 min | 9 |+| Full harness | 6 h | 200 |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.-Bài viết về harness engineering năm 2025 của OpenAI còn nói thẳng hơn. Họ cho biết Codex trong một kho lưu trữ được trang bị harness tốt đi từ "không đáng tin cậy" thẳng đến "đáng tin cậy". Chú ý cách diễn đạt: không phải "tốt hơn một chút", mà là một bước nhảy về chất. Harness ở đây có nghĩa là **toàn bộ cơ sở hạ tầng kỹ thuật bên ngoài trọng số mô hình**.+Kết quả sản xuất không tách riêng nguyên nhân. Điểm benchmark chỉ áp dụng cho mô hình, scaffold, dữ liệu và điều kiện đánh giá đã nêu. [OpenAI: 2026-02-11](https://openai.com/index/harness-engineering/)## Agent thực sự bị kẹt ở đâu@@ -25,13 +38,13 @@ Các chế độ thất bại cụ thể thực ra chỉ gói gọn trong vài- **Quy ước ẩn không được viết ra, agent không có cách nào tuân thủ.** Cả nhóm bạn dùng cú pháp SQLAlchemy 2.0, nhưng agent mặc định viết code 1.x. Mọi API endpoint phải đi qua xác thực OAuth 2.0, nhưng quy tắc đó chỉ tồn tại trong đầu bạn và một tin nhắn Slack từ ba tháng trước. Agent không hề biết, không phải nó không muốn tuân thủ, mà là nó chưa từng thấy quy tắc đó.- **Thiết lập môi trường chưa đầy đủ, agent tốn năng lượng sửa môi trường.** Môi trường dev chưa hoàn chỉnh, thiếu dependency, sai phiên bản công cụ, agent đốt cửa sổ ngữ cảnh quý giá vào lỗi `pip install` và xung đột phiên bản Node thay vì làm việc bạn thực sự giao.- **Không có phương pháp xác minh, agent tự coi là xong khi nó cảm thấy xong.** Không có test, không có lint, hoặc các lệnh xác minh chưa bao giờ được truyền đạt cho agent. Agent viết code, nhìn lại, thấy có vẻ ổn rồi tuyên bố hoàn thành. Anthropic cũng quan sát thấy một hiện tượng thú vị: khi agent cảm nhận ngữ cảnh sắp cạn, nó vội vàng kết thúc, bỏ qua bước xác minh, và chọn giải pháp đơn giản thay vì tối ưu. Họ gọi đây là "context anxiety" (lo lắng ngữ cảnh).-- **Mất trạng thái giữa các phiên, mỗi phiên mới bắt đầu lại từ đầu.** Mọi phát hiện từ phiên trước đều biến mất. Mỗi phiên mới phải khám phá lại cấu trúc dự án và hiểu lại cách tổ chức code. Agent không có trạng thái liên tục thì tỷ lệ thất bại tăng vọt trên các tác vụ kéo dài quá 30 phút.+- **Mất trạng thái giữa các phiên, mỗi phiên mới bắt đầu lại từ đầu.** — Ghi tiến độ và kết quả kiểm tra vào tệp quản lý phiên bản để phiên sau kiểm tra trạng thái. Nguồn mô tả cơ chế, không báo cáo phần trăm giảm thời gian khởi động. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## Giải thích thuật ngữ chínhVớ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.+- Kết quả sản xuất không tách riêng nguyên nhân. Điểm benchmark chỉ áp dụng cho mô hình, scaffold, dữ liệu và điều kiện đánh giá đã nêu.- **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.- **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.@@ -60,15 +73,17 @@ 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.+Kết quả sản xuất không tách riêng nguyên nhân. Điểm benchmark chỉ áp dụng cho mô hình, scaffold, dữ liệu và điều kiện đánh giá đã nêu. [OpenAI: 2026-02-11](https://openai.com/index/harness-engineering/)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".-Thí nghiệm này chứng minh trực tiếp luận điểm cốt lõi của bài giảng: **cùng một mô hình, trong môi trường trần trụi và trong môi trường có harness đầy đủ, tạo ra kết quả về cơ bản khác nhau.** Mô hình không thay đổi. Môi trường thay đổi.+Kết quả sản xuất không tách riêng nguyên nhân. Điểm benchmark chỉ áp dụng cho mô hình, scaffold, dữ liệu và điều kiện đánh giá đã nêu.> Nguồn: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)-## Một ví dụ gần gũi hơn+## Ví dụ giảng dạy++> Minh họa giảng dạy: tình huống và số liệu là giả định để giải thích, không phải đo lường của thí nghiệm công 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).@@ -94,6 +109,8 @@ Họ không thay đổi mô hình. Họ thay đổi harness.- [SWE-bench Leaderboard](https://www.swebench.com/)- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)+- [Anthropic: Sonnet 4.5 SWE-bench methodology, 2025-09-29](https://www.anthropic.com/news/claude-sonnet-4-5)+## Bài tập1. **Thí nghiệm so sánh**: Chọn một codebase bạn biết rõ và một tác vụ sửa đổi không tầm thường. Trước tiên, chạy agent mà không có hỗ trợ harness và ghi lại các lỗi. Sau đó thêm `AGENTS.md` cùng các lệnh xác minh rõ ràng, rồi chạy lại với cùng agent đó. So sánh hai kết quả, quy mỗi lỗi vào một trong năm lớp phòng thủ.diff --git a/docs/vi/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/vi/lectures/lecture-02-what-a-harness-actually-is/index.mdindex 957b068..880e7b3 100644--- a/docs/vi/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/vi/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -70,7 +70,9 @@ Thiếu bất kỳ hệ thống phụ nào trong năm cái trên thì harness ch**Định lượng giá trị từng thành phần harness**: Dùng thí nghiệm "loại trừ biến có kiểm soát". Giữ cố định mô hình, lần lượt gỡ từng hệ thống phụ trong năm hệ thống, xem hệ thống nào khi bị gỡ gây giảm hiệu suất lớn nhất. Thành phần có mức giảm lớn nhất chính là thành phần có đóng góp biên cao nhất cho tác vụ hiện tại và đáng ưu tiên củng cố. Có nên củng cố nó hay không thì phụ thuộc vào quy kết nguyên nhân lỗi, chứ không riêng vào độ lớn của mức giảm. Những thành phần gần như không có tác động cũng không nên vội loại bỏ: chúng có thể đang dư thừa, được thiết kế chưa tốt, hoặc đơn giản là tác vụ hiện tại chưa khai thác đến. Thí nghiệm này trả lời câu hỏi "thành phần nào đang có giá trị nhất ngay lúc này", bản thân nó không chứng minh được "điểm nghẽn nằm ở đâu". Để thật sự xác định điểm nghẽn, bạn phải xem xét nhật ký lỗi và quy kết nguyên nhân trước: tác vụ có mơ hồ không, ngữ cảnh có thiếu không, môi trường có tái lập được không, phản hồi xác minh có bị thiếu không, hay quản lý trạng thái đang đứt gãy? Kết quả ablation chỉ đóng vai trò bằng chứng hỗ trợ mà thôi.-## Câu chuyện thật của một nhóm+## Ví dụ giảng dạy++> Minh họa giảng dạy: tình huống và số liệu là giả định để giải thích, không phải đo lường của thí nghiệm công bố.Một nhóm dùng GPT-4o để phát triển ứng dụng frontend TypeScript + React (khoảng 20.000 dòng code). Họ trải qua bốn giai đoạn, về bản chất là thêm từng thành phần harness vào từng bước một:diff --git a/docs/vi/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/vi/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdindex 1cb3abf..0310fc7 100644--- a/docs/vi/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md+++ b/docs/vi/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -5,6 +5,8 @@# Bài 03. Biến kho lưu trữ thành nguồn sự thật duy nhất+> Hướng dẫn kỹ thuật: ngưỡng số là mặc định giảng dạy có thể chỉnh, không phải ranh giới thực nghiệm. Token phụ thuộc tokenizer và nội dung, không chỉ số dòng.+Các quyết định kiến trúc của nhóm bạn đang nằm rải rác khắp Confluence, Slack, Jira và đầu của vài kỹ sư cấp cao. Với con người thì cách này gượng gạo mà xong: bạn có thể hỏi đồng nghiệp, tìm trong lịch sử chat, đào tài liệu. Tệ hơn nữa thì chặn ai đó ngoài hành lang cũng xong. Nhưng với AI agent, thông tin không có trong kho lưu trữ thì đơn giản là không tồn tại.Điều này không phải phóng đại. Agent chỉ có ba nguồn đầu vào: system prompt và mô tả tác vụ, nội dung tệp trong kho lưu trữ, và kết quả thực thi công cụ. Lịch sử Slack, ticket Jira, trang Confluence, hay quyết định kiến trúc bạn bàn với đồng nghiệp trong cafe chiều thứ Sáu, agent không thấy bất kỳ thứ nào cả. Nó không thể "đi hỏi ai" hay "tìm trong lịch sử chat". Toàn bộ thế giới làm việc của nó chính là cái kho lưu trữ, mọi thứ nằm ngoài đó, nó hoàn toàn mù tịt.diff --git a/docs/vi/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/vi/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdindex 7f416d6..24aa58f 100644--- a/docs/vi/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md+++ b/docs/vi/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -5,6 +5,8 @@# Bài 04. Chia hướng dẫn ra thành nhiều tệp+> Hướng dẫn kỹ thuật: ngưỡng số là mặc định giảng dạy có thể chỉnh, không phải ranh giới thực nghiệm. Token phụ thuộc tokenizer và nội dung, không chỉ số dòng.+Bạn đã bắt đầu nghiêm túc với harness engineering, điều đó tốt. Bạn tạo một `AGENTS.md` rồi nhồi vào đó mọi quy tắc, ràng buộc và bài học mà bạn nghĩ ra. Một tháng sau tệp phình lên 300 dòng, hai tháng 450 dòng, ba tháng 600 dòng. Rồi bạn nhận ra hiệu suất agent lại đang tệ đi: với một sửa lỗi đơn giản, agent đốt một lượng lớn ngữ cảnh để xử lý mấy hướng dẫn triển khai chẳng liên quan; một ràng buộc bảo mật cốt tử chôn ở dòng 300 bị bỏ qua phăng phăng; ba quy tắc phong cách code mâu thuẫn khiến agent mỗi lần chọn đại một cái.Đó chính là bẫy "tệp hướng dẫn khổng lồ". Mọi thứ trông đều hữu ích, thế là bạn nhồi hết vào, và muốn tìm một quy tắc cụ thể phải lục tung cả tệp. Bạn viết 600 dòng, nhưng tác vụ trước mắt chỉ cần đúng một phần ba.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.mdindex 7627dc8..880b377 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@@ -5,6 +5,8 @@# Bài 05. Duy trì ngữ cảnh xuyên suốt các phiên+> Hướng dẫn kỹ thuật: ngưỡng số là mặc định giảng dạy có thể chỉnh, không phải ranh giới thực nghiệm. Token phụ thuộc tokenizer và nội dung, không chỉ số dòng.+Bạn yêu cầu Claude Code triển khai một tính năng hoàn chỉnh. Nó chạy 30 phút, xong phần lớn công việc, nhưng ngữ cảnh bắt đầu cạn. Bạn mở một phiên mới để tiếp tục, và phát hiện nó chẳng nhớ lần trước đã quyết định gì, vì sao lại chọn phương án A thay vì B, đã sửa những tệp nào, hay trạng thái test đang ra sao. Nó tốn 15 phút để khám phá lại dự án, rồi có khi còn đi theo hướng khác với lần trước.Hãy tưởng tượng bạn là một người thợ mộng, mỗi buổi sáng thức dậy lại quên sạch chuyện hôm qua. Bạn phải làm quen lại với toàn bộ công trường: bức tường nào xây dở, vì sao chọn gạch đỏ thay vì gạch xanh, hệ thống ống nước đang chạy tới đâu. Tệ hơn nữa, bạn có thể tháo cả cái cửa sổ hôm qua đã lắp, chỉ vì không nhớ nó đã xong từ trước.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.mdindex 3971e6c..54c9667 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@@ -5,6 +5,8 @@# Bài 06. Khởi tạo trước mỗi phiên agent+> Hướng dẫn kỹ thuật: ngưỡng số là mặc định giảng dạy có thể chỉnh, không phải ranh giới thực nghiệm. Token phụ thuộc tokenizer và nội dung, không chỉ số dòng.+Bạn mở một phiên agent mới và nói "thêm tính năng tìm kiếm". Nó lao thẳng vào code, nhiệt tình đáng khen. 20 phút sau nó phát hiện khung test chưa cấu hình xong, mất thêm 10 phút sửa, rồi lại thấy script migration cơ sở dữ liệu sai định dạng, lại loay hoay tiếp. Tính năng tìm kiếm cuối cùng cũng xong, nhưng cả phiên rất kém hiệu quả. Phần lớn thời gian đổ vào chuyện "tìm hiểu dự án này vận hành ra sao" thay vì viết tính năng tìm kiếm.Cách làm tốt hơn: trước khi cho agent bắt tay vào việc, hãy dành một giai đoạn riêng để chuẩn bị môi trường nền, chạy thông suốt các lệnh xác minh, và nắm được cấu trúc dự án. Việc khởi tạo không nên bị nhồi chung với việc triển khai tính năng, vì chúng là hai loại công việc về bản chất khác nhau.@@ -37,6 +39,8 @@ flowchart TB## Chuyện gì xảy ra khi bạn trộn chúng+> Minh họa giảng dạy: tình huống và số liệu là giả định để giải thích, không phải đo lường của thí nghiệm công bố.+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.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 +49,7 @@ Ngân sách ngữ cảnh cũng đang bị lãng phí. Phần việc khởi tạoVấ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.+[Anthropic: initializer / coding agent](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)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.@@ -122,7 +126,9 @@ Hướng dẫn harness engineering cho Codex của OpenAI cũng nhấn mạnh ng- [ ] Tất cả đã được commit vào git```-## Ví dụ thật+## Ví dụ giảng dạy++> Minh họa giảng dạy: tình huống và số liệu là giả định để giải thích, không phải đo lường của thí nghiệm công bố.Hai cách khởi tạo cho một dự án frontend React, đặt cạnh nhau để so sánh: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.mdindex 26b6e7b..9d16017 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@@ -5,6 +5,8 @@# Bài 07. Vạch ranh giới tác vụ rõ ràng cho agent+> Hướng dẫn kỹ thuật: ngưỡng số là mặc định giảng dạy có thể chỉnh, không phải ranh giới thực nghiệm. Token phụ thuộc tokenizer và nội dung, không chỉ số dòng.+Bạn nói với Claude Code "thêm xác thực người dùng vào dự án này", và nó bắt đầu sửa schema cơ sở dữ liệu, viết route, thay đổi component frontend, và tiện thể tái cấu trúc luôn error-handling middleware. Hai tiếng sau bạn kiểm tra: 12 tệp bị sửa, 800 dòng code mới, mà chẳng có tính năng nào chạy được end-to-end.Agent vốn có xung lực "làm thêm một chút", thấy thứ gì liên quan là xử lý luôn. Vấn đề là làm quá nhiều thứ cùng lúc gần như chắc chắn dẫn đến chẳng cái nào ra hồn.@@ -26,7 +28,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.+[Anthropic: incremental feature work](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## Quy trình WIP=1@@ -98,7 +100,9 @@ Dùng một tệp máy đọc được (JSON hoặc Markdown) để ghi lại trHarness nên liên tục theo dõi VCR (Verified Completion Rate) = số tác vụ đã xác minh / số tác vụ đã kích hoạt. Chặn kích hoạt tác vụ mới khi VCR < 1.0.-## Câu chuyện thật+## Ví dụ giảng dạy++> Minh họa giảng dạy: tình huống và số liệu là giả định để giải thích, không phải đo lường của thí nghiệm công bố.Một dự án REST API với 8 tính năng, hai chiến lược đặt cạnh nhau: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.mdindex 8cefbe9..098c5b4 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@@ -5,6 +5,8 @@# Bài 08. Sử dụng feature list để ràng buộc những gì agent làm+> Hướng dẫn kỹ thuật: ngưỡng số là mặc định giảng dạy có thể chỉnh, không phải ranh giới thực nghiệm. Token phụ thuộc tokenizer và nội dung, không chỉ số dòng.+Bạn yêu cầu một agent xây dựng một trang thương mại điện tử. Sau khi nó làm xong, nó báo "xong rồi". Bạn nhìn vào code: phần xác thực người dùng chạy ổn, nhưng nút thanh toán trong giỏ hàng không làm gì cả, còn luồng thanh toán thì chẳng kết nối với ai. Vấn đề ở đâu? Bạn chưa bao giờ nói với nó "xong" nghĩa là cái gì, nên nó tự lấy một chuẩn riêng: "tôi viết khá nhiều code và trông cũng tạm đầy đủ".Trong mắt nhiều người, feature list chỉ là một ghi chú nhắc nhở, viết ra để khỏi quên, xong rồi vứt sang một bên. Nhưng trong thế giới harness, feature list không phải ghi chú cho người, mà là cấu trúc nền tảng mà cả harness dựa lên. Bộ lập lịch dựa vào nó để chọn tác vụ, bộ xác minh dựa vào nó để phán xét hoàn thành, trình báo cáo bàn giao dựa vào nó để sinh tóm tắt. Không có nó, các thành phần ấy chẳng có chỗ bám víu.@@ -25,7 +27,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%.+Ghi tiến độ và kết quả kiểm tra vào tệp quản lý phiên bản để phiên sau kiểm tra trạng thái. Nguồn mô tả cơ chế, không báo cáo phần trăm giảm thời gian khởi động. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## Máy trạng thái tính năng@@ -108,7 +110,9 @@ Agent không được trực tiếp đổi trạng thái một tính năng thànMỗi mục tính năng nên có phạm vi "hoàn thành được trong một phiên". Quá rộng thì không xong, quá hẹp thì overhead quản lý phình lên. "Người dùng có thể thêm sản phẩm vào giỏ" là độ hạt vừa đẹp. "Triển khai giỏ hàng" là quá rộng. "Tạo trường tên trên Cart model" là quá hẹp. Cũng giống như cắt miếng bít tết, không phải cả tảng, cũng không phải thịt băm nhỏ.-## Câu chuyện thật+## Ví dụ giảng dạy++> Minh họa giảng dạy: tình huống và số liệu là giả định để giải thích, không phải đo lường của thí nghiệm công bố.Một nền tảng thương mại điện tử với 10 tính năng. Hai cách theo dõi đặt cạnh nhau:@@ -116,8 +120,6 @@ 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.-## Những điểm chính cần nhớ- **Feature list là cấu trúc nền của harness**, không phải ghi chú cho người. Bộ lập lịch, bộ xác minh và trình báo cáo bàn giao đều dựa vào nó.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.mdindex 77d2207..553077d 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@@ -5,12 +5,16 @@# Bài 9. Ngăn chặn agent tuyên bố thành công quá sớm+> Hướng dẫn kỹ thuật: ngưỡng số là mặc định giảng dạy có thể chỉnh, không phải ranh giới thực nghiệm. Token phụ thuộc tokenizer và nội dung, không chỉ số dòng.+Bạn yêu cầu agent triển khai tính năng "đặt lại mật khẩu". Nó sửa schema cơ sở dữ liệu, viết API endpoint, thêm mẫu email, chạy unit test (tất cả pass) rồi đầy tự tin thông báo "xong rồi". Nhưng đến khi bạn thử chạy thật, liên kết đặt lại mật khẩu gửi không đi vì thiếu cấu hình dịch vụ email; migration cơ sở dữ liệu lỗi giữa chừng, để lại schema không nhất quán; toàn bộ luồng end-to-end chưa hề được chạy dù chỉ một lần.Đây không phải sự cố cá biệt. Bài báo ICML kinh điển năm 2017 của Guo và cộng sự đã chứng minh: **các mạng nơ-ron hiện đại tự tin thái quá một cách có hệ thống**, độ tự tin mà mô hình báo cáo cao hơn nhiều so với độ chính xác thực tế. AI coding agent cũng không ngoại lệ. Chúng "cảm thấy" xong, nhưng thực tế còn xa mới xong. Harness của bạn phải thay "cảm giác" của agent bằng sự xác minh dựa trên thực thi từ bên ngoài.## Con dốc trơn trượt+> Cùng mô hình và prompt nhưng khác ngân sách thời gian và chi phí. Không phải thí nghiệm cùng ngân sách tách riêng một thành phần. Chức năng chơi cơ bản hoạt động nhưng vẫn còn lỗi. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)+Tuyên bố hoàn thành sớm hầu như luôn đi theo đúng một kịch bản: code trông có vẻ ổn, cú pháp đúng, logic có vẻ hợp lý, phân tích tĩnh không thấy lỗi rõ ràng. Nhưng harness không ép buộc xác minh thực thi toàn diện, nên agent bỏ qua bước thực sự chạy thử, hoặc chỉ chạy một phần test. Nó chạy unit test nhưng bỏ qua integration test; nó chạy test nhưng không kiểm tra coverage. Cuối cùng, "code trông có vẻ ổn" được coi là bằng chứng cho "tính năng đã hoàn thành".Thông tin bị hao hụt ở mỗi bước. Từ đặc tả tác vụ sang triển khai code rồi sang hành vi runtime, mỗi lần chuyển đổi đều có thể đưa vào sai lệch, và mỗi bước xác minh bị bỏ qua lại càng khiến sự bất đối xứng thông tin trầm trọng thêm.@@ -109,7 +113,9 @@ Các tín hiệu runtime hiệu quả gồm:- Thao tác ghi cơ sở dữ liệu, thao tác tệp và các side effect khác có đúng không?- Tài nguyên tạm có được dọn dẹp không?-## Câu chuyện thật+## Ví dụ giảng dạy++> Minh họa giảng dạy: tình huống và số liệu là giả định để giải thích, không phải đo lường của thí nghiệm công bố.**Tác vụ**: Triển khai chức năng đặt lại mật khẩu người dùng. Liên quan đến thao tác cơ sở dữ liệu, gửi email và sửa API endpoint.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.mdindex 8fa069b..cdc0f49 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@@ -5,6 +5,8 @@# Bài 10. Chỉ chạy toàn bộ pipeline mới tính là xác minh thật sự+> Hướng dẫn kỹ thuật: ngưỡng số là mặc định giảng dạy có thể chỉnh, không phải ranh giới thực nghiệm. Token phụ thuộc tokenizer và nội dung, không chỉ số dòng.+Bạn yêu cầu agent thêm tính năng xuất tệp vào ứng dụng Electron. Nó viết component cho renderer, preload script và logic lớp service. Unit test cho từng component đều pass. Agent báo "xong rồi". Bạn nhấn thật vào nút xuất, định dạng đường dẫn tệp sai, thanh tiến trình không phản hồi, xuất tệp lớn thì rò rỉ bộ nhớ. Năm lỗi ở ranh giới component, và unit test chẳng bắt được cái nào.Từng phần nhìn "đúng" khi đứng riêng, nhưng vấn đề lộ ra ngay khi chúng nối vào nhau. Tháp kiểm thử của Google cho thấy một nền unit test lớn là thiết yếu, nhưng dừng ở đó thì bạn sẽ bỏ lỡ có hệ thống các vấn đề tương tác giữa component. Với AI coding agent, chuyện này càng tệ hơn, vì agent có xu hướng chỉ chạy những test nhanh nhất rồi tuyên bố hoàn thành. **Chỉ kiểm thử toàn bộ quy trình mới chứng minh được rằng không có khiếm khuyết ở cấp hệ thống.**@@ -114,7 +116,9 @@ CÁCH SỬA: Chuyển thao tác tệp sang src/preload/file-ops.ts và gọi quaMỗi lần phát hiện một loại lỗi agent mới trong code review, hãy biến nó thành kiểm tra tự động. Một tháng sau, harness của bạn sẽ mạnh hơn rất nhiều so với đầu tháng.-## Câu chuyện thật+## Ví dụ giảng dạy++> Minh họa giảng dạy: tình huống và số liệu là giả định để giải thích, không phải đo lường của thí nghiệm công bố.**Tác vụ**: Triển khai tính năng xuất tệp trong ứng dụng Electron. Liên quan đến UI của renderer, proxy hệ thống tệp của preload script và chuyển đổi dữ liệu lớp service.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.mdindex 9e0ceed..4e2b356 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,15 +21,17 @@ 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.+Ghi tiến độ và kết quả kiểm tra vào tệp quản lý phiên bản để phiên sau kiểm tra trạng thái. Nguồn mô tả cơ chế, không báo cáo phần trăm giảm thời gian khởi động. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)-## Một kịch bản Claude Code thật+## Ví dụ giảng dạy++> Minh họa giảng dạy: tình huống và số liệu là giả định để giải thích, không phải đo lường của thí nghiệm công bố.Hãy hình dung một harness dùng quy trình ba vai "planner-generator-evaluator", thực thi tác vụ "thêm dark mode cho ứng dụng".**Không có khả năng quan sát:** Planner đưa ra mô tả mơ hồ. Generator triển khai dark mode dựa trên sự mơ hồ đó, nhưng kết quả không khớp với kỳ vọng ngầm của planner. Evaluator từ chối theo chuẩn ngầm của riêng mình mà không diễn đạt cụ thể được chỗ nào sai, chỉ biết "cảm giác không ổn". Generator thử lại mù quáng dựa trên lý do mơ hồ. Chu kỳ lặp 3-4 lần, mất khoảng 45 phút, và sản phẩm cuối cùng cũng chỉ tạm chấp nhận được.-**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.+**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. [W3C: contrast minimum](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)Hiệu quả chênh nhau 3 lần. Biến duy nhất là khả năng quan sát.@@ -122,7 +124,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ảng thuộc harness cập nhật dùng Opus 4.6: một kiến trúc ba agent, không phải ba kiến trúc. Đã bỏ chia sprint. Planner viết đặc tả, builder triển khai, evaluator kiểm tra ứng dụng và gửi phản hồi cho vòng xây dựng sau. [Anthropic: updated harness results](https://www.anthropic.com/engineering/harness-design-long-running-apps)| Agent và pha | Thời lượng | Chi phí ||---------------|----------|------|@@ -137,12 +139,6 @@ Tháng 3 năm 2026, Anthropic công bố một thí nghiệm harness có hệ thMỗ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:-**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.--**Generator:** Triển khai từng tính năng, từng sprint. Trước mỗi sprint, nó thương lượng với evaluator một sprint contract định nghĩa "xong" nghĩa là gì cho khối tính năng đó. Rồi nó triển khai theo contract, tự đánh giá, và chuyển giao cho QA.--**Evaluator:** Dùng Playwright MCP để tương tác với ứng dụng đang chạy như một người dùng thật, kiểm thử chức năng UI, API endpoint, và trạng thái cơ sở dữ liệu. Nó chấm mỗi sprint trên bốn chiều: độ sâu sản phẩm, chức năng, thiết kế trực quan, chất lượng code. Mỗi chiều có ngưỡng cứng, nếu chiều nào chưa đạt, sprint fail và generator nhận phản hồi chi tiết để sửa.-Phản hồi mẫu từ QA vòng 1: "Đây là ứng dụng ấn tượng về mặt thị giác với tích hợp AI tốt, nhưng một số tính năng cốt lõi của DAW chỉ mang tính trình diễn, chưa có chiều sâu tương tác: clip không thể kéo/di chuyển, chưa có UI panel cho nhạc cụ (nút synth, pad trống), và chưa có trình chỉnh hiệu ứng trực quan (đường cong EQ, đồng hồ compressor)." Đây không phải edge case, mà là những tương tác cốt lõi làm nên một DAW dùng được. Phản hồi cụ thể, có bằng chứng, không phải "cảm giác không ổn".Evaluator không phải lúc nào cũng bén nhạy như vậy. Phiên bản đầu có thể phát hiện vấn đề hợp lý, rồi tự thuyết phục mình rằng vấn đề ấy không nghiêm trọng, cuối cùng duyệt. Cách sửa: đọc log của evaluator, tìm chỗ phán đoán của nó lệch khỏi phán đoán của người, rồi cập nhật prompt QA để xử lý đúng những điểm cụ thể đó. Sau vài vòng lặp phát triển thế này, điểm của evaluator trở nên đáng tin.@@ -155,7 +151,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.**+- Ghi tiến độ và kết quả kiểm tra vào tệp quản lý phiên bản để phiên sau kiểm tra trạng thái. Nguồn mô tả cơ chế, không báo cáo phần trăm giảm thời gian khởi động.## Đọc thêmdiff --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.mdindex ab37ee6..24a8fc8 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@@ -5,6 +5,8 @@# Bài 12. Bàn giao sạch ở cuối mỗi phiên+> Hướng dẫn kỹ thuật: ngưỡng số là mặc định giảng dạy có thể chỉnh, không phải ranh giới thực nghiệm. Token phụ thuộc tokenizer và nội dung, không chỉ số dòng.+Agent của bạn chạy cả buổi chiều, sửa 20 tệp, commit code, rồi phiên kết thúc. Phiên agent tiếp theo vừa mở ra đã phát hiện ngay: build hỏng, test đang đỏ, các tệp debug tạm rải rác khắp nơi, feature list chưa cập nhật, và tiến độ hoàn toàn mù mờ. 30 phút đầu của phiên mới chỉ để dò xem "phiên trước thật sự đã làm gì".Cả OpenAI và Anthropic đều phát biểu rõ: **độ tin cậy dài hạn phụ thuộc vào kỷ luật vận hành, không chỉ thành công một lần chạy.** Chất lượng trạng thái khi thoát phiên trực tiếp quyết định hiệu quả của phiên kế tiếp. Cũng giống như thực hành tốt với Git vậy, mỗi commit nên là một thay đổi nguyên tử, build được, chứ không phải đống code làm dở.@@ -15,7 +17,7 @@ Các định luật tiến hoá phần mềm của Lehman cho thấy hệ thốnTrong 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:+OpenAI dành thứ Sáu để dọn dẹp: một ngày làm việc, 20% tuần, không phải 20% thứ Sáu. [OpenAI](https://openai.com/index/harness-engineering/)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 +45,7 @@ flowchart LRFix --> 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ả.+Ghi tiến độ và kết quả kiểm tra vào tệp quản lý phiên bản để phiên sau kiểm tra trạng thái. Nguồn mô tả cơ chế, không báo cáo phần trăm giảm thời gian khởi động. [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)```mermaidflowchart LR@@ -72,6 +74,8 @@ Cái bẫy tâm lý phổ biến nhất là "phiên này không có thời gianTệ 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.+> Minh họa giảng dạy: tình huống và số liệu là giả định để giải thích, không phải đo lường của thí nghiệm công bố.+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:- Tuần 1: build pass 100%, test pass 100%, khởi động phiên mới 5 phút@@ -84,8 +88,6 @@ 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.-## Cách làm đúng### 1. Trạng thái sạch là điều kiện cần để hoàn thành@@ -137,7 +139,7 @@ Phiên mới đọc tài liệu này là biết ngay ưu tiên ở đâu. SửaMỗ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ảng thuộc harness cập nhật dùng Opus 4.6: một kiến trúc ba agent, không phải ba kiến trúc. Đã bỏ chia sprint. Planner viết đặc tả, builder triển khai, evaluator kiểm tra ứng dụng và gửi phản hồi cho vòng xây dựng sau. [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)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.@@ -162,7 +164,9 @@ Khi đầu ra của agent vượt xa năng lực review của người, triết**Lưu ý**: Cách này thiếu trách nhiệm trong môi trường thông lượng thấp. Nhưng khi đầu ra của agent vượt xa sự chú ý của con người, đó thường là đánh đổi đúng. Tiêu chí then chốt: **chi phí trung bình sửa một bug so với chi phí trung bình chờ người review một PR.** Khi cái trước thấp hơn cái sau, merge nhanh là lựa chọn đúng.-## Câu chuyện thật+## Ví dụ giảng dạy++> Minh họa giảng dạy: tình huống và số liệu là giả định để giải thích, không phải đo lường của thí nghiệm công bố.Một ứng dụng Electron phát triển bằng agent trong 12 tuần, so sánh hai cách tiếp cận:@@ -170,8 +174,6 @@ 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.-## Những điểm chính cần nhớ- **Trạng thái sạch là điều kiện cần để hoàn thành phiên**, không phải dọn dẹp tuỳ chọn, mà là một phần của "định nghĩa hoàn thành".diff --git a/docs/vi/lectures/lecture-13-loop-engineering/index.md b/docs/vi/lectures/lecture-13-loop-engineering/index.mdindex 19b214e..ca91a64 100644--- a/docs/vi/lectures/lecture-13-loop-engineering/index.md+++ b/docs/vi/lectures/lecture-13-loop-engineering/index.md@@ -5,6 +5,8 @@# Bài 13. Từ Nhắc lệnh Thủ công đến Vòng lặp Tự chủ+> Hướng dẫn kỹ thuật: ngưỡng số là mặc định giảng dạy có thể chỉnh, không phải ranh giới thực nghiệm. Token phụ thuộc tokenizer và nội dung, không chỉ số dòng.+Tất cả những gì bạn đã học trong mười hai bài đầu tiên đều dựa trên một giả định: **bạn đang ngồi trước bàn phím, gõ các chỉ dẫn từng cái một.**Bạn đã viết `AGENTS.md` (Bài 1–4), xây dựng quản lý trạng thái (Bài 5–6), giới hạn phạm vi với danh sách tính năng (Bài 7–8), để lại bàn giao sạch ở cuối phiên (Bài 9, 12), và làm cho runtime có thể quan sát được (Bài 10–11). Nhưng tác nhân kích hoạt tất cả mọi thứ luôn là bạn. Agent không bao giờ tự quyết định khi nào bắt đầu làm việc — vì không ai nhấn nút "bắt đầu".@@ -96,7 +98,13 @@ 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ở.+Boris Cherny · 2025-12-27++| PR | Git commits | + LoC | − LoC | Model |+| --- | --- | --- | --- | --- |+| 259 / 30 days | 497 | 40,000 | 38,000 | Claude Code + Opus 4.5 |++Hoạt động cá nhân do tác giả báo cáo, không phải tỷ lệ thành công benchmark hay bằng chứng không có giám sát con người. [Boris Cherny](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)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.@@ -267,7 +275,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.+Hoạt động cá nhân do tác giả báo cáo, không phải tỷ lệ thành công benchmark hay bằng chứng không có giám sát con người.## 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 +301,7 @@ Một câu để nhớ: **ai đó trong đội của bạn phải không tin bNế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.+[Karpathy: autoresearch](https://github.com/karpathy/autoresearch) · [announcement](https://x.com/karpathy/status/2030371219518931079)### Ba Tệp, Ba Vai trò@@ -343,8 +351,6 @@ flowchart TD8b --> 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.-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."### Đầu ra: Bạn Nhìn Thấy Gì Khi Thức Dậy@@ -359,6 +365,8 @@ Chỉ các commit thực sự cải thiện mới được giữ trên nhánh chMỗi thí nghiệm — thành công hay thất bại — đều được ghi lại:+> Minh họa giảng dạy: tình huống và số liệu là giả định để giải thích, không phải đo lường của thí nghiệm công bố.+```timestamp commit_hash val_bpb vram_mb description--------- ------------- ---------- ---------- ----------------------------@@ -375,11 +383,8 @@ 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:--- 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.+- 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 **10.89%**+- 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. [Karpathy: leaderboard commit](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b) · [tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)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ờ.@@ -399,7 +404,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.**+Kết quả sản xuất không tách riêng nguyên nhân. Điểm benchmark chỉ áp dụng cho mô hình, scaffold, dữ liệu và điều kiện đánh giá đã nêu.### 3. Sự đầu hàng Nhận thứcdiff --git a/docs/vi/lectures/lecture-14-graph-engineering/index.md b/docs/vi/lectures/lecture-14-graph-engineering/index.mdindex ec4cb78..ad9e020 100644--- a/docs/vi/lectures/lecture-14-graph-engineering/index.md+++ b/docs/vi/lectures/lecture-14-graph-engineering/index.md@@ -261,7 +261,7 @@ Trước tiên vạch rõ ranh giới: **Graph Engineering là cái tên chỉ t**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)**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)**@@ -346,4 +346,4 @@ Không phải mọi nhiệm vụ đều đáng để vẽ đồ thị. Năm tiê4. **Đánh giá bằng năm tiêu chí:** chọn một nhiệm vụ bạn đang phân vân có nên "đồ thị hóa" hay không, chấm điểm từng tiêu chí trong năm tiêu chí. Đạt ít nhất ba cái mới đáng vẽ đồ thị. Nếu chưa đủ ba, thứ nó cần thực ra là một đoạn script workflow tốt hơn — đừng vì muốn dùng đồ thị mà dùng đồ thị.-5. **Biến graph.md thành chương trình thực thi được:** theo sáu bước trong "Xây dựng đồ thị đầu tiên của bạn từ con số không" của bài giảng này, triển khai đồ thị maker-checker bạn đã vẽ thành một đồ thị chạy được (triển khai tham chiếu: `code/maker_checker_graph.py`, viết bằng LangGraph). Đừng bỏ qua bước nào trong sáu bước: định nghĩa trạng thái → liệt kê nút → nối cạnh → viết định tuyến → gắn checkpoint → chạy. Chạy xong so sánh `graph.md` và code, tìm ra chỗ đầu tiên không khớp, và giải thích vì sao không khớp — là đồ thị vẽ sai, hay code viết sai?\ No newline at end of file+5. **Biến graph.md thành chương trình thực thi được:** theo sáu bước trong "Xây dựng đồ thị đầu tiên của bạn từ con số không" của bài giảng này, triển khai đồ thị maker-checker bạn đã vẽ thành một đồ thị chạy được (triển khai tham chiếu: `code/maker_checker_graph.py`, viết bằng LangGraph). Đừng bỏ qua bước nào trong sáu bước: định nghĩa trạng thái → liệt kê nút → nối cạnh → viết định tuyến → gắn checkpoint → chạy. Chạy xong so sánh `graph.md` và code, tìm ra chỗ đầu tiên không khớp, và giải thích vì sao không khớp — là đồ thị vẽ sai, hay code viết sai?diff --git a/docs/vi/resources/reference/index.md b/docs/vi/resources/reference/index.mdindex 724f7fa..8d2006a 100644--- a/docs/vi/resources/reference/index.md+++ b/docs/vi/resources/reference/index.md@@ -15,6 +15,11 @@ Các ghi chú này giải thích cách sử dụng các mẫu như một harness- [On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents](https://arxiv.org/html/2601.20404v2): gpt-5.2-codex; 10 repos / 124 PR tasks; Table 1.+- [Anthropic: Sonnet 4.5 — SWE-bench Verified methodology (2025-09-29)](https://www.anthropic.com/news/claude-sonnet-4-5)+- [Boris Cherny: personal 30-day production report (2025-12-27)](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)+- [Karpathy: measured autoresearch leaderboard improvement](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b)+- [Karpathy: two-day autonomous tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)+## Thứ tự Đọc Đề nghị1. `method-map.md`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.mdindex fe2b5b0..24bf6e5 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,17 +5,30 @@# 第一講. 模型能力強,不等於執行可靠-截至 2025 年底,最強的 coding agent 在 SWE-bench Verified 上的通過率大約在 50-60%。這個數字乍看還行,但別急著慶祝。那都是精心挑選過的、有明確 issue 描述和現成測試用例的任務。換到你日常開發的場景,需求模糊、沒有現成測試、隱含的業務規則散落在各處,這個數字只會更低。你信心滿滿地交代任務,agent 跑了 20 分鐘告訴你「完成了」,你一看程式碼,加了功能但測試掛了,改了 bug 但引入了新 bug,根本不是你要的東西。+Claude Sonnet 4.5 · 2025-09-29 · SWE-bench Verified++| Score | Tasks | Trials | Scaffold |+| --- | --- | --- | --- |+| 77.2% | 500 | 10 | bash + string replacement |++公開工程產出不能單獨證明某一元件的因果貢獻。基準分數只對應所述模型、框架、資料集和評估條件,不能直接當作所有實際任務的成功率。 [Anthropic: methodology](https://www.anthropic.com/news/claude-sonnet-4-5)遇到這種情況,大部分人的第一反應是「這模型不行,得換一個更貴的。」先別急著掏錢包。問題可能根本不在模型身上。## 同一匹馬,兩種命運-Anthropic 做過一個對照實驗。同一個 prompt(「做一個 2D 復古遊戲編輯器」),同一個模型(Opus 4.5)。第一次讓它裸跑,20 分鐘,花了 $9,遊戲核心功能根本跑不起來。第二次給它配上完整的 harness(planner + generator + evaluator 三 agent 架構),6 小時,花了 $200,遊戲可以正常遊玩。+> 模型和提示相同,但執行時間與費用預算不同。這是公開的應用建置對比,不是等預算、單獨隔離某個 harness 元件的實驗。核心遊戲功能可用,仍有缺陷和局限。 [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++模型和提示相同,但執行時間與費用預算不同。這是公開的應用建置對比,不是等預算、單獨隔離某個 harness 元件的實驗。核心遊戲功能可用,仍有缺陷和局限。 [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++| Opus 4.5 | Duration | USD |+| --- | --- | --- |+| Solo | 20 min | 9 |+| Full harness | 6 h | 200 |模型沒換。Opus 4.5 還是那個 Opus 4.5。換的是馬具。-OpenAI 在 2025 年發佈的 harness engineering 文章裡說得更直接,Codex 在一個 harness 搭得好的儲存庫裡,表現能從「不可靠」變成「可靠」。注意他們的用詞,那不是「好了一點」,是質變。harness 就是**模型權重之外的一切工程基礎設施**。+公開工程產出不能單獨證明某一元件的因果貢獻。基準分數只對應所述模型、框架、資料集和評估條件,不能直接當作所有實際任務的成功率。 [OpenAI: 2026-02-11](https://openai.com/index/harness-engineering/)## agent 到底卡在哪@@ -35,9 +48,9 @@ OpenAI 在 2025 年發佈的 harness engineering 文章裡說得更直接,Code理解了上面的場景,這些概念就不再是一堆術語了:-- **能力鴻溝(Capability Gap)**:模型在基準測試上的表現和真實任務上的表現之間的巨大落差。SWE-bench Verified 上 50-60% 的通過率意味著近一半的真實 issue 解不了。+- 公開工程產出不能單獨證明某一元件的因果貢獻。基準分數只對應所述模型、框架、資料集和評估條件,不能直接當作所有實際任務的成功率。- **Harness**:模型之外的一切,包括指令、工具與環境,以及狀態管理和驗證機制。不是模型權重的部分,全是 harness。-- **Harness 誘導失敗**:模型本身能力足夠,但因為執行環境有結構性缺陷而失敗。Anthropic 的對照實驗已經證明了這一點。+- **Harness 誘導失敗**:模型本身能力足夠,但因為執行環境有結構性缺陷而失敗。- **驗證缺口**:agent 對自己輸出的信心評估和實際正確性之間的偏差。agent 說「我做完了」但實際沒做完,這是最常見的失敗模式。- **診斷循環**:執行 → 觀察失敗 → 定位到 harness 的哪一層出了問題 → 修補那一層 → 重新執行。這是 harness 工程的核心方法論。- **完成定義(Definition of Done)**:一組可以用命令驗證的條件,測試通過、lint 沒報錯、類型檢查通過。沒有顯式的完成定義,agent 就會自己編一個。@@ -68,17 +81,19 @@ OpenAI 在 2025 年發佈的 harness engineering 文章裡說得更直接,Code## 一百萬行程式碼的實驗-OpenAI 在 2025 年做了一個激進的實驗,用 Codex 從一個空的 git 儲存庫起步,建構一個完整的內部產品。五個月後,這個儲存庫有大約 100 萬行程式碼,應用邏輯、基礎設施、工具、文件、內部開發工具,全部由 agent 生成。三個工程師驅動 Codex,開了大約 1,500 個 PR 並完成合併。平均每人每天 3.5 個 PR。+OpenAI 在 2025 年做了一個激進的實驗,用 Codex 從一個空的 git 儲存庫起步,建構一個完整的內部產品。五個月後,這個儲存庫有大約 100 萬行程式碼,應用邏輯、基礎設施、工具、文件、內部開發工具,全部由 agent 生成。三個工程師驅動 Codex,開了大約 1,500 個 PR 並完成合併。平均每人每天 3.5 個 PR。 [OpenAI](https://openai.com/index/harness-engineering/)-這個實驗的關鍵約束,是**人類永遠不直接寫程式碼。** 這個設定是為了逼團隊搞清楚,當工程師的主要工作不再是寫程式碼,而是設計環境、表達意圖、建構回饋迴路時,到底什麼變了?+公開工程產出不能單獨證明某一元件的因果貢獻。基準分數只對應所述模型、框架、資料集和評估條件,不能直接當作所有實際任務的成功率。早期進展比預期慢。原因在於環境不夠完整,agent 缺少必要的工具、抽象和內部結構來推進高層次目標。工程師的工作變成了,把大目標拆成小積木(設計、編碼、審查、測試),讓 agent 去搭建,然後用這些積木解鎖更復雜的任務。當某件事失敗了,修復方向幾乎從來都不靠「更努力」,真正的問題是找清楚 agent 缺什麼能力、怎麼讓它既可理解又可執行。-這個實驗直接證明了本講的核心論點,**同一個模型,在空白環境裡和在有完整 harness 的環境裡,產出有本質差異。** 模型沒變,變的是環境。+公開工程產出不能單獨證明某一元件的因果貢獻。基準分數只對應所述模型、框架、資料集和評估條件,不能直接當作所有實際任務的成功率。> 來源:[OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)-## 一個更親民的例子+## 教學示意++> 教學示意:這個場景及其中的數字是為解釋機制設定的,不是已發表實驗的實測結果。一個團隊用 Claude Sonnet 給一個中等規模的 Python Web 應用(FastAPI + PostgreSQL + Redis,約 15,000 行程式碼)添加新的 API 端點。@@ -104,6 +119,8 @@ OpenAI 在 2025 年做了一個激進的實驗,用 Codex 從一個空的 git- [SWE-bench Leaderboard](https://www.swebench.com/)- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)+- [Anthropic: Sonnet 4.5 SWE-bench methodology, 2025-09-29](https://www.anthropic.com/news/claude-sonnet-4-5)+## 練習1. **對比實驗**:選一個你熟悉的程式碼儲存庫和一項非平凡的修改任務。先不給任何 harness 支援,讓 agent 跑一次,記錄失敗。然後加一個 `AGENTS.md` 和顯式的驗證命令,讓同一個 agent 再跑一次。對比兩次的結果,把失敗歸因到五層防禦中的某一層。diff --git a/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/index.mdindex c76a436..7fcf7f4 100644--- a/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -70,7 +70,9 @@ flowchart LR**量化 harness 組件價值的方法**:用「等模型對照下的組件拆除實驗」。保持模型不變,逐個移除五個子系統,看哪個子系統缺失時效能下降最多。下降最多的組件,說明它在目前任務裡邊際貢獻最大,值得優先保留;是否要加強它,取決於失敗歸因,而不是只看下降幅度。幾乎沒有影響的組件,也不能直接判定為無用,它可能是冗餘、設計失效,或還沒有被這個任務充分觸發。這個實驗回答的是「目前哪個組件最有價值」,不能單獨證明「瓶頸在哪裡」。真正定位瓶頸,要先看失敗記錄和歸因,包含任務沒說清楚、脈絡不足、環境不可復現、驗證回饋缺失,還是狀態管理斷裂;組件拆除結果只能作為輔助證據。-## 一個團隊的真實經歷+## 教學示意++> 教學示意:這個場景及其中的數字是為解釋機制設定的,不是已發表實驗的實測結果。一個團隊用 GPT-4o 開發一個 TypeScript + React 前端應用(約 20,000 行程式碼)。他們經歷了四個階段。diff --git a/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdindex 90c644d..36d22b2 100644--- a/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md+++ b/docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -5,6 +5,8 @@# 第三講. 讓程式碼儲存庫成為唯一的事實來源+> 工程建議:這裡的數字門檻是可調整的教學預設值,不是實驗確認的分界線。token 數取決於分詞器和內容,不能只按行數推算。+你團隊的架構決策散落在 Confluence、Slack、Jira、和幾個資深工程師的腦子裡。對人類來說這勉強夠用,你可以問同事、搜聊天記錄、翻文件。實在不行還能去茶水間堵人。但對 AI agent 來說,不在儲存庫裡的資訊等於不存在。這不是誇張。想想 agent 的輸入,系統提示和任務描述、儲存庫裡的檔案內容、以及工具執行的輸出。就這三樣。你的 Slack 歷史、Jira 工單、Confluence 頁面、和週五下午跟同事在茶水間聊的架構決定,agent 全都看不到。它不能「去問一下」,也不能「搜一下聊天記錄」。它就是一個被關在儲存庫裡的工程師,儲存庫外面的事,它一概不知。diff --git a/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdindex b0a5203..c0a5600 100644--- a/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md+++ b/docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -5,6 +5,8 @@# 第四講. 把指令拆分到不同檔案裡+> 工程建議:這裡的數字門檻是可調整的教學預設值,不是實驗確認的分界線。token 數取決於分詞器和內容,不能只按行數推算。+你開始認真對待 harness 了,好事。你建了個 `AGENTS.md`,把你能想到的所有規則、約束、歷史教訓都塞了進去。一個月後這個檔案膨脹到了 300 行,兩個月 450 行,三個月 600 行。然後你發現 agent 的表現反而變差了,改一個小 bug,agent 花大量脈絡處理無關的部署指令;關鍵的安全約束埋在第 300 行,被直接忽略了;檔案裡有三條互相矛盾的程式碼風格規則,agent 每次隨機選一條。這就是「巨型指令檔案」陷阱。什麼都往裡寫、覺得都有用,最後檔案膨脹,想找一條關鍵規則就得把整份文件翻一遍;agent 真正用到的可能只有三分之一。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.mdindex fe124c9..2c1f0cf 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@@ -5,6 +5,8 @@# 第五講. 讓跨工作階段的任務保持脈絡連續+> 工程建議:這裡的數字門檻是可調整的教學預設值,不是實驗確認的分界線。token 數取決於分詞器和內容,不能只按行數推算。+你讓 Claude Code 幫你實作一個完整的功能,它跑了 30 分鐘,做了大部分工作,但脈絡快滿了。你開個新工作階段繼續,然後發現,它不記得上次做了什麼決策、為什麼選了方案 A 而不是方案 B、哪些檔案已經改過、測試跑到什麼狀態了。它得花 15 分鐘重新探索一遍專案,而且可能跟上次的做法不一致。這就是 AI coding agent 在跨工作階段任務中面對的困境。本節課講為什麼 agent 會「斷片」,以及如何透過結構化的狀態持久化讓它快速恢復到可執行狀態。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.mdindex c60ec87..8bb8527 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@@ -5,6 +5,8 @@# 第六講. 讓 agent 每次工作前先初始化+> 工程建議:這裡的數字門檻是可調整的教學預設值,不是實驗確認的分界線。token 數取決於分詞器和內容,不能只按行數推算。+你開了一個新的 agent 工作階段,讓它「幫我加個搜尋功能」。它上來就開始改程式碼,精神可嘉。改了 20 分鐘發現測試框架沒配好,又花 10 分鐘搞測試框架,然後發現資料庫遷移腳本格式不對,又折騰了一會兒。最後搜尋功能倒是加了,但整個工作階段的效率很低,大部分時間花在了「搞清楚這個專案怎麼運作」上,而不是寫搜尋功能。更好的做法是在讓 agent 開始幹活之前,先用一個獨立的階段把基礎環境搭好、驗證命令跑通、專案結構搞清楚。@@ -37,6 +39,8 @@ flowchart TB## 混在一起做會怎樣+> 教學示意:這個場景及其中的數字是為解釋機制設定的,不是已發表實驗的實測結果。+最直接的問題:基礎設施不紮實。Agent 花了 80% 的精力寫功能程式碼,剩下 20% 隨便搭了點基礎設施。測試框架配了但沒驗證過,lint 規則設了但太寬鬆,進度檔案沒建立。這些缺陷在第一個工作階段裡不明顯(因為 agent 還記得它做了什麼),但到第二個工作階段就暴露了,新 agent 不知道專案怎麼跑、怎麼測、做到哪了。更隱蔽的代價是「未驗證的累積」,在測試框架配好之前寫的功能程式碼,等回頭補測試的時候可能發現設計上就有問題,早知道的話應該用不同的方式實作。等回頭補測試時才發現設計有問題,要重構才能讓測試通過。@@ -45,7 +49,7 @@ flowchart TB最容易被忽略的是隱式假設埋下的雷。Agent 在初始化過程中做的決策(用什麼測試框架、目錄怎麼組織、依賴怎麼管理)如果不顯式記錄下來,後續工作階段就可能做出矛盾的選擇。-Anthropic 在他們的長執行應用開發研究中明確建議把初始化和實作分離。他們的實驗資料顯示,使用獨立初始化階段的專案,多工作階段場景中的功能完成率比混合方式高 31%。關鍵是,初始化階段投入的時間在後續 3-4 個工作階段中就能完全收回。+[Anthropic: initializer / coding agent](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)OpenAI 的 Codex harness engineering 指南也強調「儲存庫作為操作記錄」的原則,第一次執行就要建立有效的操作結構,否則每次新工作階段都得重新推斷專案約定。@@ -122,7 +126,9 @@ OpenAI 的 Codex harness engineering 指南也強調「儲存庫作為操作記- [ ] 所有内容已提交到 git```-## 實際案例+## 教學示意++> 教學示意:這個場景及其中的數字是為解釋機制設定的,不是已發表實驗的實測結果。一個 React 前端專案的兩種初始化方式對比: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.mdindex 1006597..728477c 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@@ -5,6 +5,8 @@# 第七講. 給 agent 劃清每次任務的邊界+> 工程建議:這裡的數字門檻是可調整的教學預設值,不是實驗確認的分界線。token 數取決於分詞器和內容,不能只按行數推算。+你讓 Claude Code「給這個專案加上使用者認證功能」,結果它同時開始改資料庫 schema、寫路由、改前端元件、還順手重構了錯誤處理中介軟體。兩個小時後你一看——12 個檔案被修改,800 行新程式碼,但沒有一個功能是端到端跑通的。Agent 天生就有「多做一點」的衝動,看到相關的事情就順手一起做了。問題是,同時做太多事情,幾乎保證每一件都做不好。@@ -26,7 +28,7 @@ Claude Code 的真實行為很說明問題。你讓它「新增使用者註冊6 步之後,每一個都是半成品。沒有端到端驗證,程式碼之間耦合複雜,下一個工作階段來接手時將完全無從下手。-Anthropic 的實驗資料直接支援這一點:使用「小下一步」策略(等價於 WIP=1)的 agent,任務完成率比使用寬泛提示的 agent 高 37%。更有意思的是,agent 生成的程式碼行數和實際完成的功能數量呈弱負相關,寫得越多,完成得越少。貪多嚼不爛,資料為證。+[Anthropic: incremental feature work](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## WIP=1 工作流@@ -98,7 +100,9 @@ F01: 使用者註冊harness 應該持續跟蹤 VCR(Verified Completion Rate)= 已通過驗證的任務數 / 已啟動的任務數。VCR < 1.0 時,阻止新任務啟動。-## 實際案例+## 教學示意++> 教學示意:這個場景及其中的數字是為解釋機制設定的,不是已發表實驗的實測結果。一個 8 個功能項的 REST API 專案,兩種策略對比: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.mdindex b30533c..63cf6bb 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@@ -5,6 +5,8 @@# 第八講. 用功能清單約束 agent 該做什麼+> 工程建議:這裡的數字門檻是可調整的教學預設值,不是實驗確認的分界線。token 數取決於分詞器和內容,不能只按行數推算。+你讓 agent 做一個電商網站,跑完之後它告訴你「做完了」。你打開程式碼一看——使用者認證有了,但購物車的結算按鈕點了沒反應,支付流程根本沒接上。問題是:你從來沒告訴它「做完」的標準是什麼,所以它用自己的標準,「程式碼寫了不少,看起來挺完整」。功能清單(feature list)在很多人眼裡就是個備忘錄,寫下來怕忘了,寫完扔在一邊。但在 harness 的世界裡,功能清單是整個 harness 的基礎結構,不只是一份給人看的備忘錄。調度器靠它選任務,驗證器靠它判完成,交接器靠它生成報告。缺少它,這些元件就沒有共同的共識可以依賴。@@ -25,7 +27,7 @@ Claude Code 和 Codex 都不會自動知道你心目中的「做完」是什麼新的 agent 工作階段看到這個記錄,無法判斷「基本完成」的定義、購物車已通過的測試,以及支付目前的阻塞條件。答案都是「不知道」。-結果是:新工作階段花 20 分鐘推斷專案狀態,最終可能重複實現已完成的功能。Anthropic 的工程實踐資料表明,好的進度記錄可以減少 60-80% 的工作階段啟動診斷時間。+把進度和驗證結果記錄在版本化檔案中,讓下一次工作階段能檢查專案狀態。引用原文介紹了這個機制,沒有報告啟動耗時減少的百分比。 [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## 功能狀態機@@ -108,7 +110,9 @@ agent 不能直接把狀態改成 `passing`。它只能提交驗證請求,harn每個功能項應該是「一次工作階段能完成」的範圍。太粗了做不完,太細了管理開銷大。「使用者可以新增商品到購物車」是一個好粒度,「實現購物車」太粗了,「建立 Cart 模型的 name 欄位」太細了。-## 實際案例+## 教學示意++> 教學示意:這個場景及其中的數字是為解釋機制設定的,不是已發表實驗的實測結果。一個電商平台的開發任務,10 個功能項。對比兩種追蹤方式:@@ -116,8 +120,6 @@ agent 不能直接把狀態改成 `passing`。它只能提交驗證請求,harn**結構化模式**:每個功能項有明確的狀態和驗證命令。新工作階段讀取功能清單,3 分鐘內知道:F01-F05 是 `passing`,F06 是 `active`(正在做),F07-F10 是 `not_started`。直接從 F06 繼續,零重複。-定量結果:使用結構化功能清單的專案,功能完成率比自由形式高 45%,零重複實現。-## 關鍵要點- **功能清單是 harness 的基礎結構**,不是給人看的備忘錄。調度器、驗證器、交接器都依賴它。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.mdindex 98e8b89..95304d7 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@@ -5,12 +5,16 @@# 第九講. 防止 agent 提前宣告完成+> 工程建議:這裡的數字門檻是可調整的教學預設值,不是實驗確認的分界線。token 數取決於分詞器和內容,不能只按行數推算。+你讓 agent 實現「密碼重置」功能。它改了資料庫 schema、寫了 API 端點、加了郵件範本,跑了單元測試(全部通過),然後自信地告訴你「做完了」。你實際一跑,密碼重置連結發不出去(郵件服務配置缺失)、資料庫遷移半途失敗(schema 不一致)、端到端流程根本沒走過一遍。這不是偶然事件。Guo 等人 2017 年在 ICML 上的經典論文證明:**現代神經網路一致性地過度自信**——模型自報的置信度顯著高於實際準確率。AI 程式碼代理也一樣,它「覺得」做完了,但實際上差得遠。你的 harness 必須用外部化的、基於執行的驗證來替代 agent 的「感覺」。## 滑坡效應+> 模型和提示相同,但執行時間與費用預算不同。這是公開的應用建置對比,不是等預算、單獨隔離某個 harness 元件的實驗。核心遊戲功能可用,仍有缺陷和局限。 [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)+過早完成聲明幾乎總是一樣的手法,程式碼看著還行,語法正確、邏輯似乎合理,靜態檢查沒有明顯錯誤。但 harness 沒有強制要求全面執行驗證,agent 跳過了實際執行或只跑了部分測試。跑了單元測試但跳過整合測試,跑了測試但沒檢查覆蓋率。最後「程式碼看起來沒問題」就被當作了「功能已完成」的證據。每一步都在遺失資訊。從任務規範到程式碼實現到執行時期行為,每次轉換都可能引入偏差,而每次跳過的驗證都加劇了資訊不對稱。@@ -109,7 +113,9 @@ OpenAI 在 Codex 實踐中提出了一個特別有效的模式,**給 agent 寫- 資料庫寫入、檔案操作等副作用是否正確?- 臨時資源是否被清理?-## 實際案例+## 教學示意++> 教學示意:這個場景及其中的數字是為解釋機制設定的,不是已發表實驗的實測結果。**任務**,實現使用者密碼重置功能。涉及資料庫操作、郵件發送和 API 端點修改。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.mdindex 593af3f..3fe0631 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@@ -5,6 +5,8 @@# 第十講. 跑通完整流程才算真正驗證+> 工程建議:這裡的數字門檻是可調整的教學預設值,不是實驗確認的分界線。token 數取決於分詞器和內容,不能只按行數推算。+你讓 agent 給 Electron 應用加一個檔案匯出功能。它寫了渲染程式元件、預載腳本、服務層邏輯,每個元件的單元測試都通過了。agent 說「做完了」。你實際一點擊匯出按鈕,檔案路徑格式不對、進度列沒反應、大檔案匯出時記憶體洩漏。5 個元件邊界缺陷,單元測試一個都沒發現。每個部分各自「正確」,但真正串連起來後,問題才會浮現。@@ -116,7 +118,9 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.rea每次在程式碼審查中發現新類型的 agent 錯誤,就把它變成自動化檢查。一個月後你的 harness 會比月初強得多。-## 實際案例+## 教學示意++> 教學示意:這個場景及其中的數字是為解釋機制設定的,不是已發表實驗的實測結果。**任務**:在 Electron 應用中實現檔案匯出功能。涉及渲染程式 UI、預載腳本檔案系統代理、服務層資料轉換。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.mdindex 5935250..46dcdba 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,15 +21,17 @@**重試變成盲猜**,agent 不知道為什麼失敗時,重試方向是隨機的。它可能在錯誤的方向上反覆嘗試,修復了不相關的程式碼路徑而忽略真正的故障根源。每次錯誤方向的重試都擴大了與真正根因的距離。每次盲重試都消耗 token 和時間。-**工作階段交接資訊斷崖**,當未完成的工作移交給下一個工作階段時,缺乏可觀測性意味著新工作階段必須從零診斷系統狀態。Anthropic 的長期執行 agent 觀察表明,這種重複診斷可能佔工作階段總時間的 30-50%。新工作階段缺乏前一階段的脈絡,必須從頭診斷,重複投入本可省略的工作。+把進度和驗證結果記錄在版本化檔案中,讓下一次工作階段能檢查專案狀態。引用原文介紹了這個機制,沒有報告啟動耗時減少的百分比。 [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)-## Claude Code 的真實場景+## 教學示意++> 教學示意:這個場景及其中的數字是為解釋機制設定的,不是已發表實驗的實測結果。想象一個使用「計劃者-生成者-評估者」三角色工作流的 harness,執行「為應用添加暗色模式」任務。**缺乏可觀測性**,計劃者輸出模糊描述。生成者根據模糊描述實現暗色模式,但和計劃者的隱式預期不一致。評估者基於自己的隱式標準拒絕,但說不出具體哪裡不對,「感覺不太對」。生成者基於模糊拒絕理由盲重試。循環 3-4 次,總耗時約 45 分鐘,最終勉強產出。-**具備完整可觀測性**,計劃者輸出衝刺合約,列明要改哪些元件、每個元件的驗證標準、排除項(不處理列印樣式)。生成者按合約實現。執行時期可觀測性記錄每個元件的樣式加載和應用過程。評估者用評分標準逐維度評估,附具體證據引用,「按鈕顏色對比度不足(WCAG AA 標準 4.5:1,實測 2.1:1)」。一次迭代出高品質結果,總耗時約 15 分鐘。+**具備完整可觀測性**,計劃者輸出衝刺合約,列明要改哪些元件、每個元件的驗證標準、排除項(不處理列印樣式)。生成者按合約實現。執行時期可觀測性記錄每個元件的樣式加載和應用過程。評估者用評分標準逐維度評估,附具體證據引用,「按鈕顏色對比度不足(WCAG AA 標準 4.5:1,實測 2.1:1)」。一次迭代出高品質結果,總耗時約 15 分鐘。 [W3C: contrast minimum](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)效率差 3 倍。區別只在可觀測性。@@ -122,7 +124,7 @@ flowchart LR## Anthropic 的三 agent 架構實驗-Anthropic 在 2026 年 3 月發佈了一項系統性的 harness 實驗。他們用三種架構跑同一個任務(「用 Web Audio API 做一個瀏覽器端 DAW」),記錄了詳細的階段資料:+這張表對應更新後的 Opus 4.6 harness:一套架構中的三個 agent,不是三種架構。該版本移除了 sprint 拆分。planner 制定規格,builder 實作,evaluator 測試執行中的應用,把回饋交給下一輪建置。 [Anthropic: updated harness results](https://www.anthropic.com/engineering/harness-design-long-running-apps)| Agent 和階段 | 時長 | 成本 ||------------|------|------|@@ -155,7 +157,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.mdindex cc533e3..8c2e2d9 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@@ -5,6 +5,8 @@# 第十二講. 每次工作階段結束前都做好交接+> 工程建議:這裡的數字門檻是可調整的教學預設值,不是實驗確認的分界線。token 數取決於分詞器和內容,不能只按行數推算。+你的 agent 跑了一下午,改了 20 個檔案,提交了程式碼,工作階段結束。下一個 agent 工作階段開始,一上來就發現:建構失敗了、測試紅了、臨時調試檔案到處都是、功能清單沒更新、進度完全不清楚。新工作階段的前 30 分鐘全花在「搞清楚上一個工作階段到底幹了什麼」上。一個工作階段留下的混亂,直接壓縮了下一個工作階段的可用時間。新工作階段本來要做新功能,卻先花半小時釐清上一個工作階段的殘局,環境混亂更會降低後續工作品質。@@ -17,7 +19,7 @@ Lehman 的軟體演化定律表明,持續變更的系統,除非主動管理OpenAI 在 5 個月的 Codex 實驗中觀察到,**agent 會複製儲存庫中已有的模式,即使那些模式是不均勻的或次優的。** 隨著時間的推移,這種複製必然導致漂移。初始的模式不均勻性在反覆複製後會逐漸放大,最終導致程式碼庫明顯漂移。-OpenAI 團隊最初花每週五(20% 的工作時間)手動清理「AI slop」。不出所料,這種方式不可擴展。週期性的手動清理無法阻止日常累積的技術債。他們的解決方案是:+OpenAI 報告每週五用於清理:一個工作日,即每週時間的 20%,不是週五時間的 20%。 [OpenAI](https://openai.com/index/harness-engineering/)1. **把「黃金原則」編碼進儲存庫**,比如「優先使用共享工具套件而非手寫的 ad-hoc 輔助函式」(保持不變數集中)、「不要 YOLO 式地猜資料結構」(驗證邊界或依賴類型化 SDK)。這些原則是具體的、機械的、可自動檢查的。2. **建立週期性的清理流程**,一組背景 Codex 任務定期掃描偏差,更新品質評分,開針對性的重構 PR。大多數可以在一分鐘內審查並自動合併。自動化清理任務取代了手動定期大掃除,降低維護成本。@@ -45,7 +47,7 @@ flowchart LRFix --> Build```-但這還不夠。目前進度必須記錄在機器可讀的工件中,已完成的子任務和通過標準、進行中但未完成的子任務和目前狀態、尚未開始的子任務。好的進度記錄減少 60-80% 的工作階段啟動診斷時間。調試日誌、臨時檔案、註解掉的程式碼、TODO 標記這些臨時工件得清理乾淨,它們增加下一個工作階段的認知負擔。標準啟動路徑也必須可用,下一個工作階段能不能不人工干預就開始工作?環境初始化、程式碼庫載入、脈絡獲取、任務選擇,這些路徑不能被破壞。+把進度和驗證結果記錄在版本化檔案中,讓下一次工作階段能檢查專案狀態。引用原文介紹了這個機制,沒有報告啟動耗時減少的百分比。 [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)```mermaidflowchart LR@@ -74,6 +76,8 @@ flowchart LR更糟的是,每個工作階段都有自己的任務目標。新工作階段來的時候是要做新功能的,不是來清理上一個工作階段的爛攤子的。它會忽略混亂直接開始新工作,然後在混亂的基礎上引入更多混亂。這是熵增的正回饋循環,混亂基礎上引入更多變更,使狀態愈發難以追蹤,形成自我強化的惡性循環。+> 教學示意:這個場景及其中的數字是為解釋機制設定的,不是已發表實驗的實測結果。+資料為證。一個使用 agent 持續開發 12 週的專案,沒有清潔策略的情況下:- 第 1 週:建構通過率 100%,測試通過率 100%,新工作階段啟動 5 分鐘@@ -86,8 +90,6 @@ flowchart LR- 第 1 週:100%,100%,5 分鐘- 第 12 週:97%,95%,9 分鐘-12 週後,建構通過率差 29 個百分點,新工作階段啟動時間差 85%。以上資料源自實際觀測,有明確的可重現紀錄。-## 怎麼做### 1. 清潔狀態是完成的必要條件@@ -139,7 +141,7 @@ flowchart LRharness 裡的每個元件之所以存在,是因為模型無法獨立做好某件事。但隨著模型改進,這些假設會過時。模型能力提升後,原本必要的 harness 元件可能變成多餘的開銷,而部分元件在特定任務難度下仍具價值。-Anthropic 的實驗直接展示了這一點。他們最初的 harness 包含 sprint 拆分機制,把工作分成小塊讓 Sonnet 4.5 逐個完成。當 Opus 4.6 發佈後,模型的原生能力已經可以自主處理工作分解,sprint 構造變成了不必要的開銷。移除後,builder agent 能連續工作超過兩小時而不會跑偏,反而更流暢。+這張表對應更新後的 Opus 4.6 harness:一套架構中的三個 agent,不是三種架構。該版本移除了 sprint 拆分。planner 制定規格,builder 實作,evaluator 測試執行中的應用,把回饋交給下一輪建置。 [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)但 evaluator 的情況不同。即使 Opus 4.6 能力更強,在任務接近模型能力邊界時,evaluator 仍然提供了實際價值,捕獲 generator 的遺漏功能和存根實現。這意味著 evaluator 的必要性取決於任務難度相對於模型能力的位置。@@ -164,7 +166,9 @@ npm run test # 驗證清理未破壞功能**注意**,這在低產出環境裡是不負責任的。但在 agent 產出遠超人類注意力的環境裡,這通常是正確的權衡。關鍵判斷標準,**修正一個 bug 的平均成本 vs 等待人類審查一個 PR 的平均成本。** 前者低於後者時,快速合併是對的。-## 實際案例+## 教學示意++> 教學示意:這個場景及其中的數字是為解釋機制設定的,不是已發表實驗的實測結果。一個使用 agent 持續開發的 Electron 應用,12 週演化過程的對比資料:@@ -172,8 +176,6 @@ npm run test # 驗證清理未破壞功能**有清潔策略(實驗組)**,每個工作階段結束時執行完整清潔檢查 + 每週清理循環。第 12 週,建構通過率 97%,測試通過率 95%,新工作階段啟動 9 分鐘,過時工件 11 個。-到第 12 週,實驗組的建構通過率比對照組高 29 個百分點,測試通過率高 34 個百分點,新工作階段啟動時間減少 85%。每個工作階段多花 5 分鐘清理,12 週後省下了幾十個小時的混亂時間。-## 關鍵要點- **清潔狀態是工作階段完成的必要條件**,不是可選的善後工作,是「完成定義」的一部分。diff --git a/docs/zh-TW/lectures/lecture-13-loop-engineering/index.md b/docs/zh-TW/lectures/lecture-13-loop-engineering/index.mdindex c60c2e0..e25e689 100644--- a/docs/zh-TW/lectures/lecture-13-loop-engineering/index.md+++ b/docs/zh-TW/lectures/lecture-13-loop-engineering/index.md@@ -5,6 +5,8 @@# 第十三講. 從手動驅動到自動循環+> 工程建議:這裡的數字門檻是可調整的教學預設值,不是實驗確認的分界線。token 數取決於分詞器和內容,不能只按行數推算。+前十二講,你做的事情始終有一個共同前提:**你坐在鍵盤前,一次一次地輸入指令。**你寫好了 `AGENTS.md`(第一到四講),建立了狀態管理(第五、六講),用功能清單約束範圍(第七、八講),讓 agent 在結束時留下乾淨交接(第九、十二講),讓運行過程可觀測(第十、十一講)——但所有這些工作的觸發者,始終是你。agent 不會自己決定什麼時候該幹活,因為沒有人按下「開始」按鈕。@@ -84,8 +86,12 @@你不必每次都寫 `/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。」@@ -96,7 +102,13 @@> **Loop engineering 就是用系統取代你自己去 prompt agent。**-Cherny 透露了一個數字:在連續 30 天裡,Claude Code 的所有程式碼貢獻全部由 AI 自主完成,累計合併 259 個 PR,其中超過 80% 的生產程式碼由 Claude 編寫,開放式軟體任務成功率達到 76%。+Boris Cherny · 2025-12-27++| PR | Git commits | + LoC | − LoC | Model |+| --- | --- | --- | --- | --- |+| 259 / 30 days | 497 | 40,000 | 38,000 | Claude Code + Opus 4.5 |++作者報告的個人開發產出,不是基準成功率,也不代表整個團隊沒有人工監督。 [Boris Cherny](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)三個人、同一週、同一個結論。不是因為商量好的,是因為基礎設施剛好跨過了一個門檻:agent 已經可靠到能獨立完成非 trivial 任務、排程原語(`/loop`、`/goal`、cron)已經內建於工具中、單次運行的 token 成本也低到值得反覆跑。當零件全部就定位,把零件拼在一起的動作,所有人在同一時間想到了。@@ -267,7 +279,7 @@ flowchart TD這不再是一個 agent 的一次運行。它是一個持續運轉的系統,每天早上自己醒來,自己掃地,自己把需要你關注的東西放到你面前。你的角色變成了:**審閱 inbox 的內容,做決策,遇到系統處理不了的模式就最佳化 skill 或規則。**-Cherny 用這個模式讓 Claude Code 團隊在 30 天內合併了 259 個 PR,自己一次都沒有打開 IDE。OpenAI 的工程師用同樣的模式建立了約一百萬行程式碼的 beta 產品,一行都沒有手寫。+作者報告的個人開發產出,不是基準成功率,也不代表整個團隊沒有人工監督。## Generator/Evaluator 分離:為什麼不能讓自己批自己作業@@ -293,7 +305,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。+[Karpathy: autoresearch](https://github.com/karpathy/autoresearch) · [announcement](https://x.com/karpathy/status/2030371219518931079)### 三個檔案,三種角色@@ -343,8 +355,6 @@ flowchart TD8b --> 9```-每小時大約跑 12 次實驗。睡一覺(8 小時)就是約 100 次。Karpathy 自己跑了 2 天,約 700 次實驗。-固定 5 分鐘牆鐘是個關鍵設計——不管 agent 改了什麼,每次實驗時間完全一樣。這意味著所有結果在同一時間預算下直接可比,不會出現「這個跑久一點所以更好」的爭議。### 輸出:你早上起來看到什麼@@ -359,6 +369,8 @@ Loop 跑完一夜,你早上打開電腦會看到三樣東西:每一次實驗——不管成功失敗——都記在裡面:+> 教學示意:這個場景及其中的數字是為解釋機制設定的,不是已發表實驗的實測結果。+```timestamp commit_hash val_bpb vram_mb description--------- ------------- ---------- ---------- ----------------------------@@ -375,11 +387,10 @@ Agent 會在 commit message 裡寫清楚它試了什麼、什麼有效、什麼### 實際跑出了什麼結果-Karpathy 首輪 2 天、約 700 次實驗的結果:+- 將 nanochat 在 8×H100 上復現 GPT-2 水準的訓練時間從 **2.02 小時壓縮到 1.80 小時**,提速約 **10.89%**+- 找到的改進包括:學習率調整、最佳化器微調、啟動函數替換、注意力模式最佳化等 [Karpathy: leaderboard commit](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b) · [tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)-- 從約 700 次嘗試中篩出了約 **20 個可堆疊的有效改進**-- 將 nanochat 在 8×H100 上復現 GPT-2 水準的訓練時間從 **2.02 小時壓縮到 1.80 小時**,提速約 **11%**-- 找到的改進包括:學習率調整、最佳化器微調、啟動函數替換、注意力模式最佳化等+> 教學示意:這個場景及其中的數字是為解釋機制設定的,不是已發表實驗的實測結果。不是所有改進都是驚天動地的大發現嗎?不是。大部分是小最佳化堆疊出來的。但這 20 個有效改進,靠人手動做要花幾週——agent 用 48 小時跑完了。@@ -399,7 +410,7 @@ loop 跑得快的時候,你很容易跳過驗證。「看起來沒問題」不### 2. Comprehension Rot(理解腐爛)-loop 出程式碼的速度越快,你對自己程式碼庫的理解就越跟不上。Cherny 的團隊 80% 的程式碼是 agent 寫的——這意味著一個團隊大部分程式碼不是人寫的。如果不讀不用,你對系統的理解會持續衰減。**快速跑 loop 的前提是快速讀結果。**+公開工程產出不能單獨證明某一元件的因果貢獻。基準分數只對應所述模型、框架、資料集和評估條件,不能直接當作所有實際任務的成功率。### 3. Cognitive Surrender(認知投降)diff --git a/docs/zh-TW/lectures/lecture-14-graph-engineering/index.md b/docs/zh-TW/lectures/lecture-14-graph-engineering/index.mdindex 4ceada8..e3e5c73 100644--- a/docs/zh-TW/lectures/lecture-14-graph-engineering/index.md+++ b/docs/zh-TW/lectures/lecture-14-graph-engineering/index.md@@ -261,7 +261,7 @@ run(graph, entry={"requirements": "修復登入頁 bug"}, thread="session-1")**概念發布後才有的**-- [GraphArc](https://github.com/CodeGraphContext/grapharc)(2026-08-02):自稱「Graph Engineering 的第一個即時實作」。它把 agent 執行從埋在日誌裡的 trace 變成一張**可互動的即時編排圖**——每個 agent、每條依賴、每個決策點都畫出來,在執行前視覺化整張圖,你確認(甚至可以拿手機看)之後再放行。作者背景是給 4000+ 開發者做圖工具,方向是「可觀測、可除錯、可工程化」。非常新,功能還在早期。+- [GraphArc](https://github.com/CodeGraphContext/grapharc)**概念發布前就有的(它們不叫 Graph Engineering,但它們才是你建構時要用的)**diff --git a/docs/zh-TW/resources/reference/index.md b/docs/zh-TW/resources/reference/index.mdindex f6bac00..c1f6e37 100644--- a/docs/zh-TW/resources/reference/index.md+++ b/docs/zh-TW/resources/reference/index.md@@ -59,6 +59,11 @@- [On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents](https://arxiv.org/html/2601.20404v2): gpt-5.2-codex; 10 repos / 124 PR tasks; Table 1.+- [Anthropic: Sonnet 4.5 — SWE-bench Verified methodology (2025-09-29)](https://www.anthropic.com/news/claude-sonnet-4-5)+- [Boris Cherny: personal 30-day production report (2025-12-27)](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)+- [Karpathy: measured autoresearch leaderboard improvement](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b)+- [Karpathy: two-day autonomous tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)+## 建議閱讀順序1. `method-map.md`diff --git a/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.mdindex e6ef132..f035115 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,17 +5,30 @@# 第一讲. 模型能力强,不等于执行可靠-截至 2025 年底,最强的 coding agent 在 SWE-bench Verified 上的通过率大约在 50-60%。这个数字听起来还不错,但别急着高兴——那些都是精心挑选过的任务,有明确的 issue 描述,有现成的测试用例。等你把自己日常的需求丢过去,需求模糊、没有现成测试、隐含的业务规则散落在各处,通过率只会更低。你信心满满地交代一个任务,agent 跑了 20 分钟后告诉你"做完了",你一看代码,加了功能但测试挂了,改了 bug 但引入了新 bug,根本不是你要的东西。+Claude Sonnet 4.5 · 2025-09-29 · SWE-bench Verified++| Score | Tasks | Trials | Scaffold |+| --- | --- | --- | --- |+| 77.2% | 500 | 10 | bash + string replacement |++公开工程产出不能单独证明某一组件的因果贡献。基准分数只对应所述模型、框架、数据集和评估条件,不能直接当作所有实际任务的成功率。 [Anthropic: methodology](https://www.anthropic.com/news/claude-sonnet-4-5)遇到这种情况,大多数人的第一反应是"这模型不行,换一个更贵的"。先别急着掏钱包。问题可能不在模型身上。## 同一匹马,两种命运-Anthropic 做过一个对照实验,很能说明问题。同一个 prompt,"做一个 2D 复古游戏编辑器",同一个模型 Opus 4.5,跑了两次。第一次裸跑,20 分钟花了 $9,游戏核心功能跑不起来。第二次配上了完整的 harness——planner、generator、evaluator 三 agent 架构——6 小时花了 $200,游戏可以正常游玩。+> 模型和提示相同,但运行时间与费用预算不同。这是公开的应用构建对比,不是等预算、单独隔离某个 harness 组件的实验。核心游戏功能可用,仍有缺陷和局限。 [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++模型和提示相同,但运行时间与费用预算不同。这是公开的应用构建对比,不是等预算、单独隔离某个 harness 组件的实验。核心游戏功能可用,仍有缺陷和局限。 [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)++| Opus 4.5 | Duration | USD |+| --- | --- | --- |+| Solo | 20 min | 9 |+| Full harness | 6 h | 200 |Opus 4.5 还是那个 Opus 4.5,模型没有换。换的是马具。-OpenAI 在 2025 年的 harness engineering 文章里把这件事说得更直白。他们说 Codex 在一个 harness 搭得好的仓库里,表现能从"不可靠"直接跳到"可靠"。注意这个用词——不是"好了一点",是质变。harness 这个词在这里的意思就是**模型权重之外的一切工程基础设施**。+公开工程产出不能单独证明某一组件的因果贡献。基准分数只对应所述模型、框架、数据集和评估条件,不能直接当作所有实际任务的成功率。 [OpenAI: 2026-02-11](https://openai.com/index/harness-engineering/)## agent 到底卡在哪@@ -25,15 +38,15 @@ OpenAI 在 2025 年的 harness engineering 文章里把这件事说得更直白- **隐性约定没写下来,agent 无从遵守。** 你们全组都用 SQLAlchemy 2.0 的新语法,但 agent 默认写了 1.x 的代码;所有 API 端点必须走 OAuth 2.0 认证,可这条规矩只存在于你脑子里和三个月前一条 Slack 消息里。Agent 压根不知道有这么回事,不是不想遵守,是真没见过。- **环境配置有缺口,agent 把精力花在修环境上。** 开发环境配置不完整、依赖缺了、工具版本不对,agent 把宝贵的上下文窗口花在了 `pip install` 报错、Node 版本冲突这些事上,真正该干的活反而没精力做。- **缺少验证手段,agent 自己觉得做完了就算完成。** 没有测试、没有 lint、或者验证命令根本没告诉 agent。Agent 写完代码,自己看了看觉得没问题,就说完成了。Anthropic 还观察到一个有意思的现象:当 agent 感觉上下文快满了,它们会匆忙结束当前工作,跳过验证步骤,选一个简单的方案而不是最优方案。他们把这叫"上下文焦虑"。-- **跨会话状态丢失,每个新会话都要重新探索。** 上次会话的发现全丢了,每个新会话都得重新探索项目结构、理解代码组织。缺乏持久化状态的 agent 在超过 30 分钟的任务中失败率急剧上升。+- **跨会话状态丢失,每个新会话都要重新探索。** — 把进度和验证结果记录在版本化文件中,让下一次会话能检查项目状态。引用原文介绍了这个机制,没有报告启动耗时减少的百分比。 [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## 关键名词解释理解了上面的场景,这些概念就不再是一堆术语了:-- **能力鸿沟(Capability Gap)**:模型在基准测试上的表现和真实任务上的表现之间的巨大落差。SWE-bench Verified 上 50-60% 的通过率意味着近一半的真实 issue 解不了。+- 公开工程产出不能单独证明某一组件的因果贡献。基准分数只对应所述模型、框架、数据集和评估条件,不能直接当作所有实际任务的成功率。- **Harness**:模型之外的一切——指令、工具、环境、状态管理、验证反馈。不是模型权重的部分,全是 harness。也就是我们说的"马具"。-- **Harness 诱导失败**:模型本身能力足够,但因为执行环境有结构性缺陷而失败。Anthropic 的对照实验已经证明了这一点。+- **Harness 诱导失败**:模型本身能力足够,但因为执行环境有结构性缺陷而失败。- **验证缺口**:agent 对自己输出的信心评估和实际正确性之间的偏差。agent 说"我做完了"但实际没做完——这是最常见的失败模式。- **诊断循环**:执行 → 观察失败 → 定位到 harness 的哪一层出了问题 → 修补那一层 → 重新执行。这是 harness 工程的核心方法论。- **完成定义(Definition of Done)**:一组可以用命令验证的条件——测试通过、lint 没报错、类型检查通过。没有显式的完成定义,agent 就会自己编一个。@@ -60,15 +73,17 @@ OpenAI 在 2025 年的 harness engineering 文章里把这件事说得更直白## 一百万行代码的实验-2025 年,OpenAI 的三个工程师开始了一项实验。规则很简单:他们不写代码,只让 Codex 写。从一个空的 git 仓库起步,五个月下来,仓库里有了大约 100 万行代码。应用逻辑、基础设施、工具、文档——全是 agent 生成的。三个工程师一共开了 1,500 个 PR,平均每人每天 3.5 个。+2025 年,OpenAI 的三个工程师开始了一项实验。规则很简单:他们不写代码,只让 Codex 写。从一个空的 git 仓库起步,五个月下来,仓库里有了大约 100 万行代码。应用逻辑、基础设施、工具、文档——全是 agent 生成的。三个工程师一共开了 1,500 个 PR,平均每人每天 3.5 个。 [OpenAI](https://openai.com/index/harness-engineering/)起初的进展出乎意料地慢。Codex 并不差,但它缺少足够完整的工具和结构去推进那些高层次的目标。三个工程师慢慢摸到了门道:把大的目标拆成小的积木块——设计、编码、审查、测试——让 agent 逐个搭建,再用这些积木去组合更复杂的任务。每当某件事做砸了,问题几乎从来不是"不够努力",而是 agent 还缺什么——缺的能力能不能用一种既可理解又可执行的方式补上去。-这个实验直接印证了本讲的核心论点:**同一个模型,在空白环境里和在有完整 harness 的环境里,产出有本质差异。** 模型没变,变的是环境。+公开工程产出不能单独证明某一组件的因果贡献。基准分数只对应所述模型、框架、数据集和评估条件,不能直接当作所有实际任务的成功率。> 来源:[OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)-## 一个更接地气的例子+## 教学示意++> 教学示意:这个场景及其中的数字是为解释机制设定的,不是已发表实验的实测结果。一个团队用 Claude Sonnet 给一个中等规模的 Python Web 应用(FastAPI + PostgreSQL + Redis,约 15,000 行代码)添加新的 API 端点。@@ -94,6 +109,8 @@ OpenAI 在 2025 年的 harness engineering 文章里把这件事说得更直白- [SWE-bench Leaderboard](https://www.swebench.com/)- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)+- [Anthropic: Sonnet 4.5 SWE-bench methodology, 2025-09-29](https://www.anthropic.com/news/claude-sonnet-4-5)+## 练习1. **对比实验**:选一个你熟悉的代码仓库和一项非平凡的修改任务。先不给任何 harness 支持,让 agent 跑一次,记录失败。然后加一个 `AGENTS.md` 和显式的验证命令,让同一个 agent 再跑一次。对比两次的结果,把失败归因到五层防御中的某一层。diff --git a/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.mdindex 7eac4f2..b58668b 100644--- a/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md+++ b/docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md@@ -70,7 +70,9 @@ flowchart LR**量化 harness 组件价值的方法**:用"控制变量排除法"。保持模型不变,逐个移除五个子系统,看哪个子系统缺失时性能下降最多。下降最多的组件,说明它在当前任务里边际贡献最大,值得优先保留;是否要加强它,取决于失败归因,而不是只看下降幅度。几乎没有影响的组件,也不能直接判定为无用:它可能是冗余、设计失效,或还没有被这个任务充分触发。这个实验回答的是"当前哪个组件最有价值",不能单独证明"瓶颈在哪里"。真正定位瓶颈,要先看失败记录和归因:任务没说清楚、上下文不足、环境不可复现、验证反馈缺失,还是状态管理断裂;组件拆除结果只能作为辅助证据。-## 一个团队的真实经历+## 教学示意++> 教学示意:这个场景及其中的数字是为解释机制设定的,不是已发表实验的实测结果。一个团队用 GPT-4o 开发一个 TypeScript + React 前端应用(约 20,000 行代码)。他们经历了四个阶段,其实就是在一件一件地添置 harness 的组件:diff --git a/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.mdindex f93783d..9c416c5 100644--- a/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md+++ b/docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md@@ -5,6 +5,8 @@# 第三讲. 让代码仓库成为唯一的事实来源+> 工程建议:这里的数字阈值是可调整的教学默认值,不是实验确认的分界线。token 数取决于分词器和内容,不能只按行数推算。+你团队的架构决策散落在 Confluence、Slack、Jira、和几个资深工程师的脑子里。对人类来说这勉强够用,你可以问同事、搜聊天记录、翻文档,实在不行还能去茶水间堵人。但对 AI agent 来说,不在仓库里的信息等于不存在。这不是夸张。Agent 的输入只有三样东西:系统提示和任务描述、仓库里的文件内容、工具执行的输出。你的 Slack 历史、Jira 工单、Confluence 页面、和周五下午跟同事聊的架构决定,agent 全都看不到。它不能"去问一下",也不能"搜一下聊天记录"。它的整个工作世界就是仓库本身,仓库外面的事它一概不知。diff --git a/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.mdindex f802095..94e9223 100644--- a/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md+++ b/docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md@@ -5,6 +5,8 @@# 第四讲. 把指令拆分到不同文件里+> 工程建议:这里的数字阈值是可调整的教学默认值,不是实验确认的分界线。token 数取决于分词器和内容,不能只按行数推算。+你开始认真对待 harness 了,这很好。你建了个 `AGENTS.md`,把能想到的所有规则、约束、历史教训都塞了进去。一个月后这个文件膨胀到了 300 行,两个月 450 行,三个月 600 行。然后你发现 agent 的表现反而变差了:改一个小 bug,agent 花大量上下文处理无关的部署指令;关键的安全约束埋在第 300 行,被直接忽略了;文件里有三条互相矛盾的代码风格规则,agent 每次随机选一条。这就是"巨型指令文件"陷阱。觉得什么都有用,什么都往里装,结果想找一条具体规则得把整个文件翻一遍。写了 600 行,但真正跟当前任务相关的可能只有三分之一。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.mdindex ec94111..cfbd8e8 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@@ -5,6 +5,8 @@# 第五讲. 让跨会话的任务保持上下文连续+> 工程建议:这里的数字阈值是可调整的教学默认值,不是实验确认的分界线。token 数取决于分词器和内容,不能只按行数推算。+你让 Claude Code 帮你实现一个完整的功能,它跑了 30 分钟,做了大部分工作,但上下文快满了。你开个新会话继续,然后发现:它不记得上次做了什么决策、为什么选了方案 A 而不是方案 B、哪些文件已经改过、测试跑到什么状态了。它得花 15 分钟重新探索一遍项目,而且可能跟上次的做法不一致。这是 AI coding agent 在跨会话任务中面对的真实困境。本节课讲为什么 agent 会"断片",以及如何通过结构化的状态持久化,让新会话能快速接上上次的工作。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.mdindex ef0127a..7672320 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@@ -5,6 +5,8 @@# 第六讲. 让 agent 每次工作前先初始化+> 工程建议:这里的数字阈值是可调整的教学默认值,不是实验确认的分界线。token 数取决于分词器和内容,不能只按行数推算。+在使用 AI 编码 agent 时,一个常见的低效模式是:让 agent 直接开始做功能,它上来就写代码,但很快会发现测试框架没配好、环境有问题、项目结构不清晰,大量时间花在了"搞清楚这个项目怎么运作"上面,真正用于写功能的时间反而很少。更好的做法是,在让 agent 开始干活之前,先用一个独立的阶段把基础环境搭好、验证命令跑通、项目结构搞清楚。初始化工作应该和功能实现分开,它们是两种性质完全不同的任务。@@ -37,6 +39,8 @@ flowchart TB## 初始化与实现同时进行的问题+> 教学示意:这个场景及其中的数字是为解释机制设定的,不是已发表实验的实测结果。+最直接的问题是基础设施搭不牢。Agent 花了 80% 的精力写功能代码,剩下 20% 随便搭了点基础设施。测试框架配了但没验证过,lint 规则设了但太宽松,进度文件没创建。这些缺陷在第一个会话里不明显(因为 agent 还记得它做了什么),但到第二个会话就暴露了:新 agent 不知道项目怎么跑、怎么测、做到哪了。更隐蔽的代价是"未验证的累积"。在测试框架配好之前写的功能代码,等回头补测试的时候可能发现设计上就有问题,早知道的话应该用不同的方式实现。前面写的代码越多,后面需要推翻重来的就越多。@@ -45,7 +49,7 @@ flowchart TB最容易被忽略的是隐式假设埋下的雷。Agent 在初始化过程中做的决策(用什么测试框架、目录怎么组织、依赖怎么管理)如果不显式记录下来,后续会话就可能做出矛盾的选择。第一个会话选了 Vitest 做测试框架,第二个会话的 agent 不知道,又引入了 Jest,两套测试框架共存,维护成本翻倍。-Anthropic 在他们的长运行应用开发研究中明确建议把初始化和实现分离。他们的实验数据:使用独立初始化阶段的项目,多会话场景中的功能完成率比混合方式高 31%。而且初始化阶段投入的时间在后续 3-4 个会话中就能完全收回。+[Anthropic: initializer / coding agent](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)OpenAI 的 Codex harness engineering 指南也强调"仓库作为操作记录"的原则:第一次运行就要建立清晰的操作结构,否则每次新会话都得重新推断项目约定。@@ -122,7 +126,9 @@ OpenAI 的 Codex harness engineering 指南也强调"仓库作为操作记录"- [ ] 所有内容已提交到 git```-## 实际案例+## 教学示意++> 教学示意:这个场景及其中的数字是为解释机制设定的,不是已发表实验的实测结果。一个 React 前端项目的两种初始化方式对比: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.mdindex 89817e9..33c64ca 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@@ -5,6 +5,8 @@# 第七讲. 给 agent 划清每次任务的边界+> 工程建议:这里的数字阈值是可调整的教学默认值,不是实验确认的分界线。token 数取决于分词器和内容,不能只按行数推算。+Agent 经常会越界,同时做太多事情。在一个典型场景中,你让它给项目加上用户认证功能,结果它同时开始改数据库 schema、写路由、改前端组件,还顺手重构了错误处理中间件。两个小时后一看,12 个文件被修改,800 行新代码,但没有一个功能是端到端跑通的。Agent 天生就有"多做一点"的冲动:看到相关的事情就顺手一起做了。问题是,同时做太多事情,结果往往每一件都做不好。@@ -26,7 +28,7 @@ Claude Code 的真实行为很说明问题。你让它"添加用户注册功能"6 步之后,每一个都是半成品。没有端到端验证,代码之间耦合复杂,下一个会话来接手时会一脸懵。-Anthropic 的实验数据直接支持这一点:使用"小下一步"策略(等价于 WIP=1)的 agent,任务完成率比使用宽泛提示的 agent 高 37%。更有意思的是,agent 生成的代码行数和实际完成的功能数量呈弱负相关,写得越多,完成得越少。贪多嚼不烂,数据为证。+[Anthropic: incremental feature work](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## WIP=1 工作流@@ -98,7 +100,9 @@ F01: 用户注册harness 应该持续跟踪 VCR(Verified Completion Rate)= 已通过验证的任务数 / 已启动的任务数。VCR < 1.0 时,阻止新任务启动。-## 实际案例+## 教学示意++> 教学示意:这个场景及其中的数字是为解释机制设定的,不是已发表实验的实测结果。一个 8 个功能点的 REST API 项目,两种策略对比: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.mdindex 640a15e..c2649cd 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@@ -5,6 +5,8 @@# 第八讲. 用功能清单约束 agent 该做什么+> 工程建议:这里的数字阈值是可调整的教学默认值,不是实验确认的分界线。token 数取决于分词器和内容,不能只按行数推算。+一个常见的场景:让 agent 做一个电商网站,跑完之后它告诉你"做完了"。但你打开代码一看,用户认证有了,但购物车的结算按钮点了没反应,支付流程根本没接上。问题的根源在于:没有告诉过它"做完"的具体标准,所以它用自己的标准来判断——"代码写了不少,看起来挺完整"。功能清单(feature list)在很多人眼里就是个备忘录,写下来怕忘了,写完扔在一边。但在 harness 的世界里,功能清单是整个 harness 的基础结构。调度器靠它选任务,验证器靠它判完成,交接器靠它生成报告。没有它,这些组件就没有可以依赖的共识。@@ -25,7 +27,7 @@ Claude Code 和 Codex 都不会自动知道你心目中的"做完"是什么意新的 agent 会话看到这个记录,能回答以下问题吗?"基本完成"意味着什么?购物车通过了哪些测试?支付的阻塞条件是什么?答案都是"不知道"。-结果是:新会话花 20 分钟推断项目状态,最终可能重复实现已完成的功能。Anthropic 的工程实践数据表明,好的进度记录可以减少 60-80% 的会话启动诊断时间。+把进度和验证结果记录在版本化文件中,让下一次会话能检查项目状态。引用原文介绍了这个机制,没有报告启动耗时减少的百分比。 [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)## 功能状态机@@ -108,7 +110,9 @@ agent 不能直接把状态改成 `passing`。它只能提交验证请求,harn每个功能项应该是"一次会话能完成"的范围。太粗了做不完,太细了管理开销大。"用户可以添加商品到购物车"是一个好粒度,"实现购物车"太粗了,"创建 Cart 模型的 name 字段"太细了。-## 实际案例+## 教学示意++> 教学示意:这个场景及其中的数字是为解释机制设定的,不是已发表实验的实测结果。一个电商平台的开发任务,10 个功能项。对比两种追踪方式:@@ -116,8 +120,6 @@ agent 不能直接把状态改成 `passing`。它只能提交验证请求,harn**结构化模式**:每个功能项有明确的状态和验证命令。新会话读取功能清单,3 分钟内知道:F01-F05 是 `passing`,F06 是 `active`(正在做),F07-F10 是 `not_started`。直接从 F06 继续,零重复。-定量结果:使用结构化功能清单的项目,功能完成率比自由形式高 45%,零重复实现。-## 核心要点- **功能清单是 harness 的基础结构**,不是给人看的备忘录。调度器、验证器、交接器都依赖它。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.mdindex bed230d..aefbdda 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@@ -5,12 +5,16 @@# 第九讲. 防止 agent 提前宣告完成+> 工程建议:这里的数字阈值是可调整的教学默认值,不是实验确认的分界线。token 数取决于分词器和内容,不能只按行数推算。+Agent 有一个系统性倾向:过早宣称任务完成。举例来说,你让它实现"密码重置"功能,它改了数据库 schema、写了 API 端点、加了邮件模板,跑了单元测试全部通过,然后告诉你"做完了"。但实际一跑才发现:密码重置链接发不出去,邮件服务配置缺失;数据库迁移半途失败,schema 不一致;端到端流程根本没走过一遍。Guo 等人 2017 年在 ICML 上的经典论文证明:**现代神经网络系统性地过度自信**,模型自报的置信度显著高于实际准确率。AI 编码 agent 也一样,它"觉得"做完了,但实际上差得远。harness 必须用外部化的、基于执行的验证来替代 agent 的"感觉"。## 滑坡效应+> 模型和提示相同,但运行时间与费用预算不同。这是公开的应用构建对比,不是等预算、单独隔离某个 harness 组件的实验。核心游戏功能可用,仍有缺陷和局限。 [Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps)+过早完成声明几乎总是一样的套路:代码看着还行,语法正确、逻辑似乎合理,静态检查没有明显错误。但 harness 没有强制要求全面执行验证,agent 跳过了实际运行或只跑了部分测试。跑了单元测试但跳过集成测试,跑了测试但没检查覆盖率。最后"代码看起来没问题"就被当作了"功能已完成"的证据。每一步都在丢失信息。从任务规范到代码实现,再到运行时行为,每次转换都可能引入偏差,每次跳过的验证都加剧了信息不对称。@@ -109,7 +113,9 @@ OpenAI 在 Codex 实践中提出了一个特别有效的模式:**给 agent 写- 数据库写入、文件操作等副作用是否正确?- 临时资源是否被清理?-## 实际案例+## 教学示意++> 教学示意:这个场景及其中的数字是为解释机制设定的,不是已发表实验的实测结果。**任务**:实现用户密码重置功能。涉及数据库操作、邮件发送和 API 端点修改。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.mdindex 6d8c31f..c9b81e9 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@@ -5,6 +5,8 @@# 第十讲. 跑通完整流程才算真正验证+> 工程建议:这里的数字阈值是可调整的教学默认值,不是实验确认的分界线。token 数取决于分词器和内容,不能只按行数推算。+单元测试通过后,agent 经常会说"做完了",但端到端运行时才会暴露真正的问题。举例来说,让 agent 给 Electron 应用加一个文件导出功能,它写了渲染进程组件、预加载脚本、服务层逻辑,每个组件的单元测试都通过了。agent 说"做完了"。实际点击导出按钮时:文件路径格式不对、进度条没反应、大文件导出时内存泄漏。5 个组件边界缺陷,单元测试一个都没发现。每个部分单独看都"对"了,但拼在一起就出了问题。Google 的测试金字塔告诉我们,大量单元测试是基础,但如果你止步于此,就会系统性地漏掉组件交互问题。对于 AI 编码 agent 来说,这个问题更严重,因为 agent 倾向于只跑最快的测试然后宣告完成。**只有端到端测试能证明系统级缺陷不存在**。@@ -114,7 +116,9 @@ FIX: Move file operations to src/preload/file-ops.ts and call via window.api.rea每次在代码审查中发现新类型的 agent 错误,就把它变成自动化检查。一个月后你的 harness 会比月初强得多。-## 实际案例+## 教学示意++> 教学示意:这个场景及其中的数字是为解释机制设定的,不是已发表实验的实测结果。**任务**:在 Electron 应用中实现文件导出功能。涉及渲染进程 UI、预加载脚本文件系统代理、服务层数据转换。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.mdindex d6baee8..61e1fcf 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,15 +21,17 @@ Agent 执行任务时常常像一个黑盒:它跑了 20 分钟,改了一堆**重试变成盲猜**:agent 不知道为什么失败时,重试方向是随机的。它可能在错误的方向上反复尝试,修复了不相关的代码路径而忽略真正的故障根源。每次盲重试都消耗 token 和时间。-**会话交接信息断崖**:当未完成的工作移交给下一个会话时,缺乏可观测性意味着新会话必须从零诊断系统状态。Anthropic 的长期运行 agent 观察表明,这种重复诊断可能占会话总时间的 30-50%。+把进度和验证结果记录在版本化文件中,让下一次会话能检查项目状态。引用原文介绍了这个机制,没有报告启动耗时减少的百分比。 [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)-## 实际运行示例+## 教学示意++> 教学示意:这个场景及其中的数字是为解释机制设定的,不是已发表实验的实测结果。来看一个使用"计划者-生成者-评估者"三角色工作流的 harness,执行"为应用添加暗色模式"任务。**没有可观测性**:计划者输出模糊描述,生成者根据模糊描述实现暗色模式,但和计划者的隐式预期不一致。评估者基于自己的隐式标准拒绝,但说不出具体哪里不对,只有一句"感觉不太对"。生成者基于模糊拒绝理由盲重试,循环 3-4 次,总耗时约 45 分钟,最终勉强产出。-**有完整可观测性**:计划者输出冲刺合同,列明要改哪些组件、每个组件的验证标准、排除项(不处理打印样式)。生成者按合同实现,运行时可观测性记录每个组件的样式加载和应用过程。评估者用评分标准逐维度评估,附具体证据引用:"按钮颜色对比度不足(WCAG AA 标准 4.5:1,实测 2.1:1)"。一次迭代出高质量结果,总耗时约 15 分钟。+**有完整可观测性**:计划者输出冲刺合同,列明要改哪些组件、每个组件的验证标准、排除项(不处理打印样式)。生成者按合同实现,运行时可观测性记录每个组件的样式加载和应用过程。评估者用评分标准逐维度评估,附具体证据引用:"按钮颜色对比度不足(WCAG AA 标准 4.5:1,实测 2.1:1)"。一次迭代出高质量结果,总耗时约 15 分钟。 [W3C: contrast minimum](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)效率差 3 倍,区别只在可观测性。@@ -122,7 +124,7 @@ flowchart LR## Anthropic 的三 agent 架构实验-Anthropic 在 2026 年 3 月发布了一项系统性的 harness 实验。他们用三种架构跑同一个任务("用 Web Audio API 做一个浏览器端 DAW"),记录了详细的阶段数据:+这张表对应更新后的 Opus 4.6 harness:一套架构中的三个 agent,不是三种架构。该版本移除了 sprint 拆分。planner 制定规格,builder 实现,evaluator 测试运行中的应用,把反馈交给下一轮构建。 [Anthropic: updated harness results](https://www.anthropic.com/engineering/harness-design-long-running-apps)| Agent 和阶段 | 时长 | 成本 ||------------|------|------|@@ -137,12 +139,6 @@ Anthropic 在 2026 年 3 月发布了一项系统性的 harness 实验。他们三个 agent 各司其职,每个都有明确的可观测性角色:-**Planner(规划者)**:接收一段 1-4 句话的用户需求,扩展成完整产品规格。被要求"大胆设定范围"并且"专注于产品上下文和高层技术设计,而不深入详细的技术实现"。原因是:如果 planner 过早指定了粒度技术细节且搞错了,错误会级联到下游实现。更好的做法是约束交付物,让 agent 在执行中自己找到路径。--**Generator(生成者)**:按 sprint 逐个功能实现。每个 sprint 前和 evaluator 协商一份 sprint 合同,约定这个功能块"做完"的标准。然后按合同实现,自评后交给 QA。--**Evaluator(评估者)**:用 Playwright MCP 像用户一样点击运行中的应用,测试 UI 功能、API 端点和数据库状态。对每个 sprint 按四个维度评分:产品深度、功能性、视觉设计和代码质量。每个维度有硬性阈值,任一不达标则 sprint 失败,generator 收到详细反馈后修复。-QA 第 1 轮反馈的示例:"这是一个视觉上令人印象深刻的应用,AI 集成工作良好,但核心 DAW 功能有几个是展示性的,没有交互深度:剪辑不能拖拽/移动,没有乐器 UI 面板(合成器旋钮、鼓垫),没有视觉效果编辑器(EQ 曲线、压缩器仪表)"。这些不是边缘情况,它们是让 DAW 可用的核心交互。具体的、有证据的反馈,不是"感觉不对"。Evaluator 不是一开始就这么强。早期版本会识别出合理的问题,然后说服自己这些问题不严重,最终批准工作。调校方式是:读 evaluator 的日志,找到它的判断和人类判断分叉的地方,更新 QA 的 prompt 解决那些问题。经过几轮这种开发循环,evaluator 的评分才变得合理。@@ -155,7 +151,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.mdindex 50cbf8b..58bb61b 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@@ -5,6 +5,8 @@# 第十二讲. 每次会话结束前都做好交接+> 工程建议:这里的数字阈值是可调整的教学默认值,不是实验确认的分界线。token 数取决于分词器和内容,不能只按行数推算。+在使用 AI 编码 agent 进行持续开发时,一个常见的问题是:每个 agent 会话结束时,如果没有刻意做清理,代码库的状态会越来越混乱。举例来说,一个 agent 会话修改了 20 个文件并提交代码后退出,下一个会话启动时,可能发现构建失败、测试变红、临时调试文件散落各处,功能清单和进度记录也没有更新。新会话需要花费大量时间诊断上一个会话做了什么,才能继续工作。OpenAI 和 Anthropic 都明确指出,长期可靠性取决于操作纪律,单次运行成功并不够。每个会话结束时的状态质量,直接决定下一个会话的效率。这一讲要讨论的,就是如何让每个会话在结束时留下一个干净的状态,让下一个会话可以立刻开始工作。@@ -15,7 +17,7 @@ Lehman 的软件演化定律告诉我们:一个持续变更的系统,如果OpenAI 在 5 个月的 Codex 实验中观察到一个现象:agent 会复制仓库中已有的模式,哪怕那些模式是不一致或次优的。随着时间推移,这种复制必然导致整体质量漂移。打个比方:第一个人在公共区域放了一个杯子,第二个人路过时心想"反正已经乱了",自己也放了一个。一周后,桌上就堆满了。代码库的退化也是同样的过程。-OpenAI 团队最初每周五花 20% 的工作时间手动清理 agent 留下的烂摊子,但这种做法显然不可持续。他们最终找到了系统性的解决方案:+OpenAI 报告每周五用于清理:一个工作日,即每周时间的 20%,不是周五时间的 20%。 [OpenAI](https://openai.com/index/harness-engineering/)1. **把好习惯写进仓库规则**:比如"优先使用共享工具包,不要手写 ad-hoc 辅助函数"、"不要瞎猜数据结构,查类型定义或用类型安全 SDK"。这些规则是具体的、机械的、可以自动检查的。2. **建立周期性清理流程**:一组后台任务定期扫描偏离规则的代码,更新质量评分,自动开重构 PR。大多数 PR 可以在一分钟内审查并自动合并。@@ -45,7 +47,7 @@ flowchart LR构建和测试只是底线,还有三条容易被忽略的要求。-第一,当前进度必须记录在机器可读的工件中。具体来说包括三类:已完成的子任务和它的通过标准、正在做但还没做完的子任务和它当前卡在哪、还没开始的子任务。好的进度记录可以减少 60% 到 80% 的会话启动诊断时间。+把进度和验证结果记录在版本化文件中,让下一次会话能检查项目状态。引用原文介绍了这个机制,没有报告启动耗时减少的百分比。 [Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)第二,临时调试产物必须清理干净。调试日志、临时文件、注释掉的代码、TODO 标记,这些东西都会增加下一个会话的认知负担。新会话看到一堆 `console.log('debug')` 和 `// 临时方案,回头改`,根本分不清哪些是有意的、哪些是垃圾。@@ -80,6 +82,8 @@ flowchart LR更糟的是,每个会话都有自己的任务目标。新会话来的时候是为了做新功能,不是为了清理上一个会话遗留问题的。它会直接忽略混乱,在混乱的基础上开始新工作,然后引入更多混乱。这是一个熵增的正反馈循环——越乱越不管,越不管越乱。+> 教学示意:这个场景及其中的数字是为解释机制设定的,不是已发表实验的实测结果。+数据最能说明问题。下面是一个使用 agent 持续开发 12 周的项目的实际对比:**没有清洁策略**:@@ -98,8 +102,6 @@ flowchart LR| 第 1 周 | 100% | 100% | 5 分钟 || 第 12 周 | 97% | 95% | 9 分钟 |-12 周下来,两组之间的构建通过率差了 29 个百分点,测试通过率差了 34 个百分点,新会话启动时间差了 85%。这是实测数据,差距已经非常明显。-## 怎么做### 1. 清洁状态是完成的必要条件@@ -180,7 +182,9 @@ npm run test # 验证清理没有破坏功能**注意**:这条规则的前提是 agent 的高产出远超过人类的审查带宽。在一个低产出环境里,快速合并没有意义。但在 agent 每天提交几十个 PR 的环境里,等待人工审查的成本远高于修一个漏网 bug 的成本。-## 实际案例+## 教学示意++> 教学示意:这个场景及其中的数字是为解释机制设定的,不是已发表实验的实测结果。一个使用 agent 持续开发的 Electron 应用,12 周的演化过程:@@ -188,8 +192,6 @@ npm run test # 验证清理没有破坏功能**有清洁策略(实验组)**:每个会话结束时执行完整清洁检查,加上每周一次清理循环。第 12 周时,构建通过率 97%,测试通过率 95%,新会话启动 9 分钟,过时工件 11 个。-到第 12 周,实验组的构建通过率比对照组高 29 个百分点,测试通过率高 34 个百分点,新会话启动时间减少 85%。每个会话只多花 5 分钟做清理,12 周下来却省了几十个小时的混乱时间。-## 核心要点- **清洁状态是会话完成的必要条件**。它是"完成"定义的一部分,属于必要条件。代码写完了但状态是脏的,那就不算做完。diff --git a/docs/zh/lectures/lecture-13-loop-engineering/index.md b/docs/zh/lectures/lecture-13-loop-engineering/index.mdindex 81446de..acb09d1 100644--- a/docs/zh/lectures/lecture-13-loop-engineering/index.md+++ b/docs/zh/lectures/lecture-13-loop-engineering/index.md@@ -5,6 +5,8 @@# 第十三讲. 从手动驱动到自动循环+> 工程建议:这里的数字阈值是可调整的教学默认值,不是实验确认的分界线。token 数取决于分词器和内容,不能只按行数推算。+前十二讲,你做的事情始终有一个共同前提:**你坐在键盘前,一次一次地输入指令。**你写好了 `AGENTS.md`(第一到四讲),建立了状态管理(第五、六讲),用功能清单约束范围(第七、八讲),让 agent 在结束时留下干净交接(第九、十二讲),让运行过程可观测(第十、十一讲)——但所有这些工作的触发者,始终是你。agent 不会自己决定什么时候该干活,因为没有人按下"开始"按钮。@@ -84,8 +86,12 @@你不必每次都写 `/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。」@@ -96,7 +102,13 @@> **Loop engineering 就是用系统取代你自己去 prompt agent。**-Cherny 透露了一个数字:在连续 30 天里,Claude Code 的所有代码贡献全部由 AI 自主完成,累计合并 259 个 PR,其中超过 80% 的生产代码由 Claude 编写,开放式软件任务成功率达到 76%。+Boris Cherny · 2025-12-27++| PR | Git commits | + LoC | − LoC | Model |+| --- | --- | --- | --- | --- |+| 259 / 30 days | 497 | 40,000 | 38,000 | Claude Code + Opus 4.5 |++作者报告的个人开发产出,不是基准成功率,也不代表整个团队没有人工监督。 [Boris Cherny](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)三个人、同一周、同一个结论。不是因为商量好的,是因为基础设施刚好跨过了一个门槛:agent 已经可靠到能独立完成非 trivial 任务、调度原语(`/loop`、`/goal`、cron)已经内置于工具中、单次运行的 token 成本也低到值得反复跑。当零件全部就位,把零件拼在一起的动作,所有人在同一时间想到了。@@ -267,7 +279,7 @@ flowchart TD这不再是一个 agent 的一次运行。它是一个持续运转的系统,每天早上自己醒来,自己扫地,自己把需要你关注的东西放到你面前。你的角色变成了:**审阅 inbox 的内容,做决策,遇到系统处理不了的模式就优化 skill 或规则。**-Cherny 用这个模式让 Claude Code 团队在 30 天内合并了 259 个 PR,自己一次都没有打开 IDE。OpenAI 的工程师用同样的模式创建了约一百万行代码的 beta 产品,一行都没有手写。+作者报告的个人开发产出,不是基准成功率,也不代表整个团队没有人工监督。## Generator/Evaluator 分离:为什么不能让自己批自己作业@@ -293,7 +305,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。+[Karpathy: autoresearch](https://github.com/karpathy/autoresearch) · [announcement](https://x.com/karpathy/status/2030371219518931079)### 三个文件,三种角色@@ -343,8 +355,6 @@ flowchart TD8b --> 9```-每小时大约跑 12 次实验。睡一觉(8 小时)就是约 100 次。Karpathy 自己跑了 2 天,约 700 次实验。-固定 5 分钟墙钟是个关键设计——不管 agent 改了什么,每次实验时间完全一样。这意味着所有结果在同一时间预算下直接可比,不会出现"这个跑久一点所以更好"的争议。### 输出:你早上起来看到什么@@ -359,6 +369,8 @@ Loop 跑完一夜,你早上打开电脑会看到三样东西:每一次实验——不管成功失败——都记在里面:+> 教学示意:这个场景及其中的数字是为解释机制设定的,不是已发表实验的实测结果。+```timestamp commit_hash val_bpb vram_mb description--------- ------------- ---------- ---------- ----------------------------@@ -375,11 +387,10 @@ Agent 会在 commit message 里写清楚它试了什么、什么有效、什么### 实际跑出了什么结果-Karpathy 首轮 2 天、约 700 次实验的结果:+- 将 nanochat 在 8×H100 上复现 GPT-2 水平的训练时间从 **2.02 小时压缩到 1.80 小时**,提速约 **10.89%**+- 找到的改进包括:学习率调整、优化器微调、激活函数替换、注意力模式优化等 [Karpathy: leaderboard commit](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b) · [tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)-- 从约 700 次尝试中筛出了约 **20 个可堆叠的有效改进**-- 将 nanochat 在 8×H100 上复现 GPT-2 水平的训练时间从 **2.02 小时压缩到 1.80 小时**,提速约 **11%**-- 找到的改进包括:学习率调整、优化器微调、激活函数替换、注意力模式优化等+> 教学示意:这个场景及其中的数字是为解释机制设定的,不是已发表实验的实测结果。不是所有改进都是惊天动地的大发现吗?不是。大部分是小优化堆叠出来的。但这 20 个有效改进,靠人手动做要花几周——agent 用 48 小时跑完了。@@ -399,7 +410,7 @@ loop 跑得快的时候,你很容易跳过验证。"看起来没问题"不等### 2. Comprehension Rot(理解腐烂)-loop 出代码的速度越快,你对自己代码库的理解就越跟不上。Cherny 的团队 80% 的代码是 agent 写的——这意味着一个团队大部分代码不是人写的。如果不读不用,你对系统的理解会持续衰减。**快速跑 loop 的前提是快速读结果。**+公开工程产出不能单独证明某一组件的因果贡献。基准分数只对应所述模型、框架、数据集和评估条件,不能直接当作所有实际任务的成功率。### 3. Cognitive Surrender(认知投降)diff --git a/docs/zh/lectures/lecture-14-graph-engineering/index.md b/docs/zh/lectures/lecture-14-graph-engineering/index.mdindex 55377ba..d556425 100644--- a/docs/zh/lectures/lecture-14-graph-engineering/index.md+++ b/docs/zh/lectures/lecture-14-graph-engineering/index.md@@ -261,7 +261,7 @@ run(graph, entry={"requirements": "修复登录页 bug"}, thread="session-1")**概念发布后才有的**-- [GraphArc](https://github.com/CodeGraphContext/grapharc)(2026-08-02):自称"Graph Engineering 的第一个实时实现"。它把 agent 执行从埋在日志里的 trace 变成一张**可交互的实时编排图**——每个 agent、每条依赖、每个决策点都画出来,在执行前可视化整张图,你确认(甚至可以拿手机看)之后再放行。作者背景是给 4000+ 开发者做图工具,方向是"可观测、可调试、可工程化"。非常新,功能还在早期。+- [GraphArc](https://github.com/CodeGraphContext/grapharc)**概念发布前就有的(它们不叫 Graph Engineering,但它们才是你构建时要用的)**diff --git a/docs/zh/resources/reference/index.md b/docs/zh/resources/reference/index.mdindex 8e95c4e..4580e53 100644--- a/docs/zh/resources/reference/index.md+++ b/docs/zh/resources/reference/index.md@@ -60,6 +60,11 @@- [On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents](https://arxiv.org/html/2601.20404v2): gpt-5.2-codex; 10 repos / 124 PR tasks; Table 1.+- [Anthropic: Sonnet 4.5 — SWE-bench Verified methodology (2025-09-29)](https://www.anthropic.com/news/claude-sonnet-4-5)+- [Boris Cherny: personal 30-day production report (2025-12-27)](https://twitter.com/bcherny/status/2004887829252317325) · [quoted original post](https://simonwillison.net/tags/boris-cherny/)+- [Karpathy: measured autoresearch leaderboard improvement](https://github.com/karpathy/nanochat/commit/f06860494848db080c9a80a0ffa83203b042056b)+- [Karpathy: two-day autonomous tuning commit](https://github.com/karpathy/nanochat/commit/6ed7d1d82cee16c2e26f45d559ad3338447a6c1b)+## 推荐阅读顺序1. `method-map.md`