Skip to content

Harness engineering beginner tutorial, from 0 to 1

Add Graph Engineering lecture and project across all 15 locales

sanbuphy79450b07292b
diff --git a/CLAUDE.md b/CLAUDE.md
index 84e348f..5d5782c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -31,12 +31,12 @@ npm run test:watch # Vitest watch mode
- `docs/` — VitePress documentation site (lectures, projects, resources)
- `docs/.vitepress/config.mts` — Nav/sidebar config for all 15 locales (en, zh, zh-TW, ja, ko, es, fr, ru, de, ar, vi, uz, tr, uk, pt-BR)
-- `docs/<lang>/lectures/` — 13 lectures, each with `index.md` + `code/` examples
-- `docs/<lang>/projects/` — 7 project descriptions
+- `docs/<lang>/lectures/` — 14 lectures, each with `index.md` + `code/` examples
+- `docs/<lang>/projects/` — 8 project descriptions
- `docs/<lang>/resources/` — localized templates, references, OpenAI advanced pack
- `docs-readme/` — localized README translations (one directory per locale)
- `projects/shared/` — Shared Electron + TypeScript + React foundation
-- `projects/project-NN/` — Per-project `starter/` and `solution/` directories (project-01 through project-06; project-07 is docs-only so far)
+- `projects/project-NN/` — Per-project `starter/` and `solution/` directories (project-01 through project-06; project-07 and project-08 are docs-only so far)
## Architecture
diff --git a/README.md b/README.md
index aadbbd3..cc6455c 100644
--- a/README.md
+++ b/README.md
@@ -21,8 +21,8 @@
<p align="center"><strong>A project-based course on building the environment, state management, verification, and control mechanisms that make AI coding agents work reliably.</strong></p>
<p align="center">
- <img src="https://img.shields.io/badge/Lectures-13-blue?style=flat-square" alt="13 Lectures">
- <img src="https://img.shields.io/badge/Projects-7-green?style=flat-square" alt="7 Projects">
+ <img src="https://img.shields.io/badge/Lectures-14-blue?style=flat-square" alt="14 Lectures">
+ <img src="https://img.shields.io/badge/Projects-8-green?style=flat-square" alt="8 Projects">
<img src="https://img.shields.io/badge/Languages-15-yellow?style=flat-square" alt="15 Languages">
<img src="https://img.shields.io/badge/License-MIT-lightgrey?style=flat-square" alt="MIT License">
<a href="https://discord.gg/XU7DQmpqk"><img src="https://img.shields.io/badge/Discord-Join_Community-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Join the Discord community"></a>
@@ -30,6 +30,19 @@
> 🌍 This course is available in **15 languages**: English, 简体中文, 繁體中文, 日本語, 한국어, Español, Français, Русский, Deutsch, العربية, Tiếng Việt, Oʻzbekcha, Türkçe, Portuguese (BR), Українська. Choose your language from the badges above.
+## 🆕 What's New — August 2026
+
+**Graph Engineering Update — 1 new lecture, 1 new project**
+
+| What | Details |
+|------|---------|
+| **Lecture 14** | [From Single Loops to Graph Engineering](docs/en/lectures/lecture-14-graph-engineering/index.md) — Why a single loop grows into a graph: the four stacked layers (prompt → context → loop → graph) and where harness sits in that stack, the four parts of a graph (nodes, edges, shared state, routing), why in-loop checkpoints can't fix the three structural failures at scale (Goodhart, blindness upward, conflict), a framework-agnostic six-step walkthrough for building your first graph, graph vs. workflow, anchors, which open-source "graph engineering" projects existed before the name vs. after it, the orchestration tax, and when a graph is actually worth drawing. |
+| **Project 08** | [Draw Your Workflow as a Graph](docs/en/projects/project-08-graph-engineering-first-graph/index.md) — Three progressive experiments: draw your maker-checker loop as an explicit graph, add a parallel fan-out/fan-in node, then add a conditional rollback edge and a human-approval node. |
+
+**Key idea:** A loop is a graph with one node. When your task needs specialization, parallelism, shared state, verification, and recovery — it has stopped being a loop. It's a graph.
+
+---
+
## 🆕 What's New — July 2026
**Loop Engineering Update — 1 new lecture, 1 new project**
@@ -229,7 +242,7 @@ The curriculum is divided into three parts:
## Quick Start: Improve Your Agent Today
-You don't need to read all 13 lectures before you start getting value. If you're already using a coding agent on a real project, here's how to improve it right now.
+You don't need to read all 14 lectures before you start getting value. If you're already using a coding agent on a real project, here's how to improve it right now.
The idea is simple: instead of just writing prompts, give your agent a set of structured files that define what to do, what's been done, and how to verify the work. These files live inside your repo, so every session starts from the same state.
@@ -340,6 +353,18 @@ The course is designed to be done in order. Each phase builds on the last.
v
P07 Build your first automated loop
(goal loop, timer loop, maker-checker)
+
+ Phase 8: STRUCTURE THE SYSTEM
+ =============================
+
+ L14 Draw the system as a graph —
+ nodes, edges, shared state, routing
+
+ |
+ v
+ P08 Draw your workflow as a graph
+ (explicit graph, parallel fan-out/fan-in,
+ rollback edges, human-in-the-loop)
```
Each phase takes about a week if you're going part-time. If you want to go faster, phases 1–3 can be done in a long weekend.
@@ -348,7 +373,7 @@ Each phase takes about a week if you're going part-time. If you want to go faste
## Syllabus
-### Lectures — 13 conceptual units, each answering one core question
+### Lectures — 14 conceptual units, each answering one core question
*Read the full text for each lecture on the [Documentation Website](https://walkinglabs.github.io/learn-harness-engineering/).*
@@ -367,8 +392,9 @@ Each phase takes about a week if you're going part-time. If you want to go faste
| [L11](./docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Why does observability belong inside the harness? | If you can't see what the agent did, you can't fix what it broke |
| [L12](./docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Why must every session leave a clean state? | The next session's success depends on this session's cleanup |
| [L13](./docs/en/lectures/lecture-13-loop-engineering/index.md) | Why do you need to stop prompting your agent? | From manual driving to automated loops — goal loops, timer loops, and maker-checker separation |
+| [L14](./docs/en/lectures/lecture-14-graph-engineering/index.md) | Why does a single loop grow into a graph? | From single loops to graph engineering — nodes, edges, shared state, routing, and when a graph is actually worth drawing |
-### Projects — 7 hands-on projects applying lecture methods to the same Electron app
+### Projects — 8 hands-on projects applying lecture methods to the same Electron app
| Project | What You Do | Harness Mechanism |
|---------|------------|-------------------|
@@ -379,6 +405,7 @@ Each phase takes about a week if you're going part-time. If you want to go faste
| [P05](./docs/en/projects/project-05-grounded-qa-verification/index.md) | Make the agent verify its own work | Self-verification + grounded Q&A + evidence-based completion |
| [P06](./docs/en/projects/project-06-runtime-observability-and-debugging/index.md) | Build a complete harness from scratch (capstone) | Full harness: all mechanisms + observability + ablation study |
| [P07](./docs/en/projects/project-07-loop-engineering-first-loop/index.md) | Build your first automated loop | Goal loops, timer loops, maker-checker separation, loop state management |
+| [P08](./docs/en/projects/project-08-graph-engineering-first-graph/index.md) | Draw your workflow as a graph | Explicit nodes/edges/state/routing, parallel fan-out/fan-in, rollback edges, human-in-the-loop approval |
```text
PROJECT EVOLUTION
@@ -403,6 +430,9 @@ Each phase takes about a week if you're going part-time. If you want to go faste
|
v
P07 Your first automated loop You step outside the loop
+ |
+ v
+ P08 Draw your workflow as a graph You draw the system as a graph
Each project's solution becomes the next project's starter.
The app evolves. Your harness skills grow with it.
@@ -565,12 +595,12 @@ See the full layered reference list in [`docs/en/resources/reference/`](./docs/e
```text
learn-harness-engineering/
├── docs/ # VitePress documentation site
-│ ├── lectures/ # 13 lectures (index.md + code/ examples)
+│ ├── lectures/ # 14 lectures (index.md + code/ examples)
│ │ ├── lecture-01-*/
-│ │ └── ... (13 total)
-│ ├── projects/ # 7 project descriptions
+│ │ └── ... (14 total)
+│ ├── projects/ # 8 project descriptions
│ │ ├── project-01-*/
-│ │ └── ... (7 total)
+│ │ └── ... (8 total)
│ └── resources/ # Multilingual templates & references (14 languages)
│ ├── en/
│ └── ... (14 total)
@@ -590,7 +620,7 @@ learn-harness-engineering/
## How the Course Is Organized
- Each lecture focuses on one question
-- The course includes 7 projects
+- The course includes 8 projects
- Every project requires the agent to do real work
- Every project compares weak vs. strong harness results
- What matters is the measured difference, not how many docs were written
diff --git a/docs-readme/ar-SA/README.md b/docs-readme/ar-SA/README.md
index dc630f0..e800784 100644
--- a/docs-readme/ar-SA/README.md
+++ b/docs-readme/ar-SA/README.md
@@ -22,6 +22,21 @@
تعلّم هندسة الحزام (Learn Harness Engineering) هي دورة تعليمية مكرّسة لهندسة وكلاء البرمجة بالذكاء الاصطناعي. لقد قمنا بدراسة وتوليف أحدث نظريات وممارسات هندسة الحزام في الصناعة بعمق. تشمل مراجعنا الأساسية:
+> **🆕 تحديث أغسطس 2026: هندسة الرسوم البيانية (Graph Engineering)** — محاضرة جديدة + مشروع جديد:
+>
+> - **المحاضرة 14** [من الحلقة الواحدة إلى هندسة الرسوم البيانية](../../docs/ar/lectures/lecture-14-graph-engineering/index.md): لماذا تنمو شبكة الرسوم حتمًا بعد حلقة واحدة — الطبقات الأربع المتكدسة (prompt → context → loop → graph) ومكان الحزام فيها، أجزاء الرسم الأربعة (العقد، الحواف، الحالة المشتركة، التوجيه)، لماذا لا تنقذ نقاط التحقق داخل الحلقة من الفشل البنيوي الثلاثة عند التوسع (Goodhart، العمى التصاعدي، التعارض)، الخطوات الست المستقلة عن الإطار لبناء أول رسم بياني لك، الفرق بين Graph وWorkflow، المراسي، وضع المشاريع مفتوحة المصدر قبل/بعد الإطلاق، ضريبة التنسيق، ومتى يستحق الرسم فعلًا.
+> - **المشروع 08** [ارسم سير عملك كرسم بياني](../../docs/ar/projects/project-08-graph-engineering-first-graph/index.md): ثلاث تجارب متتالية — رسم حلقة maker-checker كرسم صريح، إضافة عقد fan-out/fan-in متوازية، إضافة حافة تراجع شرطية وعقدة موافقة بشرية.
+>
+> **الفكرة الأساسية:** الحلقة هي رسم بياني بعقدة واحدة. عندما تتطلب المهمة تقسيم العمل والتوازي والحالة المشتركة والتحقق والاستعادة — لم تعد حلقة، بل رسمًا بيانيًا.
+>
+> **🆕 تحديث يوليو 2026: هندسة الحلقات (Loop Engineering)** — محاضرة جديدة + مشروع جديد + قوالب كود:
+>
+> - **المحاضرة 13** [لماذا تحتاج إلى التوقف عن مطالبة وكيلك](../../docs/ar/lectures/lecture-13-loop-engineering/index.md): من `/goal` إلى البدائيات الست لهندسة الحلقات (أتمتة، worktrees، مهارات، موصلات، وكلاء فرعيون، حالة خارجية)، فصل المولد/المقيّم، التكاليف الصامتة الأربعة، وبناء أول حلقة لك خطوة بخطوة.
+> - **المشروع 07** [ابنِ أول حلقة آلية](../../docs/ar/projects/project-07-loop-engineering-first-loop/index.md): ثلاث تجارب متتالية — حلقة الهدف، حلقة المؤقت، حلقة الصانع-المدقق. قارن اليدوي مقابل الآلي، قس تقلص التدخلات، وتعلم الخروج من الحلقة.
+> - **قوالب الكود**: `goal-template.md`، `loop-state-template.md`، `maker-prompt.md`، `checker-prompt.md` — قوالب جاهزة للبناء الفوري.
+>
+> **الفكرة الأساسية:** هندسة الحزام تصنع السيارة. هندسة الحلقات تصمم الطريق الذي تسير عليه — وأنت تصمم هذا الطريق من خارج السيارة.
+
- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
@@ -195,15 +210,15 @@
ينقسم المنهج إلى ثلاثة أجزاء:
-1. **المحاضرات**: 12 وحدة مفاهيمية تشرح النظرية وراء هندسة الحزام.
-2. **المشاريع**: 6 مشاريع عملية حيث تبني مساحة عمل وكيلية من الصفر.
+1. **المحاضرات**: 14 وحدة مفاهيمية تشرح النظرية وراء هندسة الحزام.
+2. **المشاريع**: 8 مشاريع عملية حيث تبني مساحة عمل وكيلية من الصفر.
3. **مكتبة الموارد**: قوالب جاهزة للنسخ (`AGENTS.md`، `feature_list.json`، `init.sh`، إلخ) لاستخدامها في مستودعاتك الخاصة اليوم.
---
## ابدأ بسرعة: حسّن وكيلك اليوم
-لا تحتاج إلى قراءة جميع المحاضرات الـ 12 قبل أن تبدأ في الحصول على قيمة. إذا كنت تستخدم بالفعل وكيل برمجة في مشروع حقيقي، إليك كيفية تحسينه الآن.
+لا تحتاج إلى قراءة جميع المحاضرات الـ 14 قبل أن تبدأ في الحصول على قيمة. إذا كنت تستخدم بالفعل وكيل برمجة في مشروع حقيقي، إليك كيفية تحسينه الآن.
الفكرة بسيطة: بدلاً من مجرد كتابة الموجهات، أعطِ وكيلك مجموعة من الملفات المنظمة التي تحدد ما يجب فعله، ما تم إنجازه، وكيفية التحقق من العمل. هذه الملفات تعيش داخل مستودعك، لذا تبدأ كل جلسة من نفس الحالة.
@@ -223,7 +238,7 @@
## مشروع التخرج: تطبيق حقيقي
-جميع مشاريع الدورة الستة تدور حول نفس المنتج: **تطبيق سطح مكتب لقاعدة المعرفة الشخصية مبني على Electron**.
+جميع مشاريع الدورة الثمانية تدور حول نفس المنتج: **تطبيق سطح مكتب لقاعدة المعرفة الشخصية مبني على Electron**.
```text
┌─────────────────────────────────────────────────────┐
@@ -304,6 +319,25 @@
v v
P05 الوكيل يتحقق من عمله بنفسه P06 ابنِ حزاماً كاملاً
(مشروع التخرج)
+
+ المرحلة 7: أتمتة الحلقة
+ ==========================
+ L13 توقف عن مطالبة وكيلك —
+ صمم حلقات بدلاً من ذلك
+ |
+ v
+ P07 ابنِ أول حلقة آلية
+ (حلقة هدف، حلقة مؤقت، صانع-مدقق)
+
+ المرحلة 8: هيكلة النظام
+ =============================
+ L14 ارسم النظام كرسم بياني —
+ عقد، حواف، حالة مشتركة، توجيه
+ |
+ v
+ P08 ارسم سير عملك كرسم بياني
+ (رسم صريح، fan-out/fan-in متوازي،
+ حواف تراجع، تعاون بشري)
```
كل مرحلة تستغرق حوالي أسبوع إذا كنت تعمل بدوام جزئي. إذا كنت تريد السرعة، يمكن إنجاز المراحل 1-3 في عطلة نهاية أسبوع طويلة.
@@ -312,35 +346,39 @@
## المنهج الدراسي
-### المحاضرات — 12 وحدة مفاهيمية، كل منها يجيب عن سؤال أساسي واحد
+### المحاضرات — 14 وحدة مفاهيمية، كل منها يجيب عن سؤال أساسي واحد
*اقرأ النص الكامل لكل محاضرة على [موقع التوثيق](https://walkinglabs.github.io/learn-harness-engineering/).*
| الجلسة | السؤال | الفكرة الأساسية |
|---------|--------|-----------------|
-| [L01](../../docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md) | لماذا تفشل النماذج القوية في المهام الحقيقية؟ | الفجوة في القدرة بين المعايير القياسية والهندسة الحقيقية |
-| [L02](../../docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md) | ماذا يعني "الحزام" فعلياً؟ | خمسة أنظمة فرعية: التعليمات، الحالة، التحقق، النطاق، دورة الحياة |
-| [L03](../../docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | لماذا يجب أن يكون المستودع هو المصدر الوحيد للحقيقة؟ | إذا لم يستطع الوكيل رؤيته، فهو غير موجود |
-| [L04](../../docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | لماذا يفشل ملف التعليمات الضخم الواحد؟ | الإفصاح التدريجي: أعط خريطة، لا موسوعة |
-| [L05](../../docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | لماذا تفقد المهام طويلة التشغيل الاستمرارية؟ | احفظ التقدم على القرص؛ التقط من حيث توقفت |
-| [L06](../../docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | لماذا تحتاج التهيئة إلى مرحلة خاصة بها؟ | تحقق من صحة البيئة قبل أن يبدأ الوكيل العمل |
-| [L07](../../docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | لماذا يتجاوز الوكلاء الحدود وينهون أعمالاً بشكل ناقص؟ | ميزة واحدة في كل مرة؛ تعريف صريح للإتمام |
-| [L08](../../docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | لماذا تُعد قوائم الميزات عناصر أساسية للحزام؟ | حدود نطاق قابلة للقراءة آلياً لا يمكن للوكيل تجاهلها |
-| [L09](../../docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | لماذا يعلن الوكلاء النصر مبكراً جداً؟ | فجوات التحقق: الثقة ≠ الصحة |
-| [L10](../../docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | لماذا يغيّر الاختبار من طرف إلى طرف النتائج؟ | تشغيل خط أنابيب كامل فقط يُحسب كتحقق حقيقي |
-| [L11](../../docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | لماذا تنتمي قابلية الملاحظة داخل الحزام؟ | إذا لم تستطع رؤية ما فعله الوكيل، لا يمكنك إصلاح ما أفسده |
-| [L12](../../docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | لماذا يجب أن تترك كل جلسة حالة نظيفة؟ | نجاح الجلسة التالية يعتمد على تنظيف هذه الجلسة |
-
-### المشاريع — 6 مشاريع عملية تطبق طرق المحاضرات على نفس تطبيق Electron
+| [L01](../../docs/ar/lectures/lecture-01-why-capable-agents-still-fail/index.md) | لماذا تفشل النماذج القوية في المهام الحقيقية؟ | الفجوة في القدرة بين المعايير القياسية والهندسة الحقيقية |
+| [L02](../../docs/ar/lectures/lecture-02-what-a-harness-actually-is/index.md) | ماذا يعني "الحزام" فعلياً؟ | خمسة أنظمة فرعية: التعليمات، الحالة، التحقق، النطاق، دورة الحياة |
+| [L03](../../docs/ar/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | لماذا يجب أن يكون المستودع هو المصدر الوحيد للحقيقة؟ | إذا لم يستطع الوكيل رؤيته، فهو غير موجود |
+| [L04](../../docs/ar/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | لماذا يفشل ملف التعليمات الضخم الواحد؟ | الإفصاح التدريجي: أعط خريطة، لا موسوعة |
+| [L05](../../docs/ar/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | لماذا تفقد المهام طويلة التشغيل الاستمرارية؟ | احفظ التقدم على القرص؛ التقط من حيث توقفت |
+| [L06](../../docs/ar/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | لماذا تحتاج التهيئة إلى مرحلة خاصة بها؟ | تحقق من صحة البيئة قبل أن يبدأ الوكيل العمل |
+| [L07](../../docs/ar/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | لماذا يتجاوز الوكلاء الحدود وينهون أعمالاً بشكل ناقص؟ | ميزة واحدة في كل مرة؛ تعريف صريح للإتمام |
+| [L08](../../docs/ar/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | لماذا تُعد قوائم الميزات عناصر أساسية للحزام؟ | حدود نطاق قابلة للقراءة آلياً لا يمكن للوكيل تجاهلها |
+| [L09](../../docs/ar/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | لماذا يعلن الوكلاء النصر مبكراً جداً؟ | فجوات التحقق: الثقة ≠ الصحة |
+| [L10](../../docs/ar/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | لماذا يغيّر الاختبار من طرف إلى طرف النتائج؟ | تشغيل خط أنابيب كامل فقط يُحسب كتحقق حقيقي |
+| [L11](../../docs/ar/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | لماذا تنتمي قابلية الملاحظة داخل الحزام؟ | إذا لم تستطع رؤية ما فعله الوكيل، لا يمكنك إصلاح ما أفسده |
+| [L12](../../docs/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | لماذا يجب أن تترك كل جلسة حالة نظيفة؟ | نجاح الجلسة التالية يعتمد على تنظيف هذه الجلسة |
+| [L13](../../docs/ar/lectures/lecture-13-loop-engineering/index.md) | لماذا تحتاج إلى التوقف عن مطالبة وكيلك؟ | من القيادة اليدوية إلى الحلقات المستقلة — حلقة الهدف، حلقة المؤقت، فصل الصانع-المدقق |
+| [L14](../../docs/ar/lectures/lecture-14-graph-engineering/index.md) | لماذا تتطور الحلقة الواحدة إلى رسم بياني؟ | من الحلقة الواحدة إلى هندسة الرسوم البيانية — العقد، الحواف، الحالة المشتركة، التوجيه، ومتى يستحق الرسم فعلًا |
+
+### المشاريع — 8 مشاريع عملية تطبق طرق المحاضرات على نفس تطبيق Electron
| المشروع | ماذا تفعل | آلية الحزام |
|---------|-----------|-------------|
-| [P01](../../docs/en/projects/project-01-baseline-vs-minimal-harness/index.md) | شغّل نفس المهمة مرتين: بالموجهات فقط مقابل القواعد أولاً | حزام أدنى: AGENTS.md + init.sh + feature_list.json |
-| [P02](../../docs/en/projects/project-02-agent-readable-workspace/index.md) | أعد هيكلة المستودع ليتمكن الوكيل من قراءته | مساحة عمل قابلة للقراءة بواسطة الوكيل + ملفات حالة مستمرة |
-| [P03](../../docs/en/projects/project-03-multi-session-continuity/index.md) | اجعل الوكيل يلتقط من حيث توقف | سجل التقدم + تسليم الجلسة + استمرارية متعددة الجلسات |
-| [P04](../../docs/en/projects/project-04-incremental-indexing/index.md) | أوقف الوكيل عن القيام بالكثير جداً أو القليل جداً | ملاحظات وقت التشغيل + التحكم في النطاق + الفهرسة التدريجية |
-| [P05](../../docs/en/projects/project-05-grounded-qa-verification/index.md) | اجعل الوكيل يتحقق من عمله بنفسه | التحقق الذاتي + أسئلة وأجوبة مبنية على أدلة + إكمال قائم على الأدلة |
-| [P06](../../docs/en/projects/project-06-runtime-observability-and-debugging/index.md) | ابنِ حزاماً كاملاً من الصفر (مشروع التخرج) | حزام كامل: جميع الآليات + قابلية الملاحظة + دراسة الاستئصال |
+| [P01](../../docs/ar/projects/project-01-baseline-vs-minimal-harness/index.md) | شغّل نفس المهمة مرتين: بالموجهات فقط مقابل القواعد أولاً | حزام أدنى: AGENTS.md + init.sh + feature_list.json |
+| [P02](../../docs/ar/projects/project-02-agent-readable-workspace/index.md) | أعد هيكلة المستودع ليتمكن الوكيل من قراءته | مساحة عمل قابلة للقراءة بواسطة الوكيل + ملفات حالة مستمرة |
+| [P03](../../docs/ar/projects/project-03-multi-session-continuity/index.md) | اجعل الوكيل يلتقط من حيث توقف | سجل التقدم + تسليم الجلسة + استمرارية متعددة الجلسات |
+| [P04](../../docs/ar/projects/project-04-incremental-indexing/index.md) | أوقف الوكيل عن القيام بالكثير جداً أو القليل جداً | ملاحظات وقت التشغيل + التحكم في النطاق + الفهرسة التدريجية |
+| [P05](../../docs/ar/projects/project-05-grounded-qa-verification/index.md) | اجعل الوكيل يتحقق من عمله بنفسه | التحقق الذاتي + أسئلة وأجوبة مبنية على أدلة + إكمال قائم على الأدلة |
+| [P06](../../docs/ar/projects/project-06-runtime-observability-and-debugging/index.md) | ابنِ حزاماً كاملاً من الصفر (مشروع التخرج) | حزام كامل: جميع الآليات + قابلية الملاحظة + دراسة الاستئصال |
+| [P07](../../docs/ar/projects/project-07-loop-engineering-first-loop/index.md) | ابنِ أول حلقة آلية | حلقة الهدف، حلقة المؤقت، فصل الصانع-المدقق، إدارة حالة الحلقة |
+| [P08](../../docs/ar/projects/project-08-graph-engineering-first-graph/index.md) | ارسم سير عملك كرسم بياني | عقد/حواف/حالة/توجيه صريحة، fan-out/fan-in متوازي، حواف تراجع، موافقة بشرية في الحلقة |
```text
تطور المشاريع
@@ -362,6 +400,12 @@
|
v
P06 حزام كامل (مشروع التخرج) أنت تبني النظام الكامل
+ |
+ v
+ P07 أول حلقة آلية لك أنت تخرج من الحلقة
+ |
+ v
+ P08 ارسم سير عملك كرسم بياني أنت ترسم النظام كرسم بياني
حل كل مشروع يصبح بداية المشروع التالي.
التطبيق يتطور. مهاراتك في الحزام تنمو معه.
@@ -515,7 +559,7 @@ npm run docs:preview # Preview built site
- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)
- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)
-راجع قائمة المراجع الطبقية الكاملة في [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md).
+راجع قائمة المراجع الطبقية الكاملة في [`docs/ar/resources/reference/`](../../docs/ar/resources/reference/index.md).
---
@@ -524,13 +568,13 @@ npm run docs:preview # Preview built site
```text
learn-harness-engineering/
├── docs/ # VitePress documentation site
-│ ├── lectures/ # 12 lectures (index.md + code/ examples)
+│ ├── lectures/ # 14 lectures (index.md + code/ examples)
│ │ ├── lecture-01-*/
│ │ ├── lecture-02-*/
-│ │ └── ... (12 total)
-│ ├── projects/ # 6 project descriptions
+│ │ └── ... (14 total)
+│ ├── projects/ # 8 project descriptions
│ │ ├── project-01-*/
-│ │ └── ... (6 total)
+│ │ └── ... (8 total)
│ └── resources/ # Multilingual templates & references
│ ├── en/ # English templates, checklists, guides
│ ├── zh/ # Chinese templates, checklists, guides
@@ -550,7 +594,7 @@ learn-harness-engineering/
## كيف تم تنظيم الدورة
- كل محاضرة تركز على سؤال واحد
-- الدورة تتضمن 6 مشاريع
+- الدورة تتضمن 8 مشاريع
- كل مشروع يتطلب من الوكيل القيام بعمل حقيقي
- كل مشروع يقارن نتائج الحزام الضعيف بالقوي
- ما يهم هو الفرق المقاس، وليس عدد الوثائق المكتوبة
diff --git a/docs-readme/de-DE/README.md b/docs-readme/de-DE/README.md
index f877718..d485078 100644
--- a/docs-readme/de-DE/README.md
+++ b/docs-readme/de-DE/README.md
@@ -22,6 +22,21 @@
Learn Harness Engineering ist ein Kurs, der sich der Entwicklung von KI-Coding-Agenten widmet. Wir haben die fortschrittlichsten Theorien und Praktiken des Harness Engineering in der Branche eingehend studiert und zusammengefasst. Unsere Kernreferenzen umfassen:
+> **🆕 August-2026-Update: Graph Engineering (Graph Engineering)** — 1 neue Vorlesung + 1 neues Projekt:
+>
+> - **Lektion 14** [Von Einzel-Loops zu Graph Engineering](../../docs/de/lectures/lecture-14-graph-engineering/index.md): warum ein einzelner Loop unweigerlich zu einem Graphen wird — die vier gestapelten Ebenen (prompt → context → loop → graph) und der Ort des Harness darin, die vier Teile eines Graphen (Knoten, Kanten, Shared State, Routing), warum Checkpoints innerhalb eines Loops die drei strukturellen Fehlschläge im Maßstab (Goodhart, Blindheit nach oben, Konflikt) nicht retten können, die framework-unabhängigen sechs Schritte zum Bauen deines ersten Graphen, der Unterschied zwischen Graph und Workflow, Anker, die Situation der Open-Source-Projekte vor vs. nach der Veröffentlichung, die Orchestration Tax — und wann ein Graph wirklich einen Graphen wert ist.
+> - **Projekt 08** [Zeichne deinen Workflow als Graph](../../docs/de/projects/project-08-graph-engineering-first-graph/index.md): drei fortschreitende Experimente — den Maker-Checker-Loop als expliziten Graphen zeichnen, einen parallelen Fan-out/Fan-in-Knoten hinzufügen, eine bedingte Rollback-Kante und einen menschlichen Freigabe-Knoten hinzufügen.
+>
+> **Kernaussage:** Ein Loop ist ein Graph mit nur einem Knoten. Sobald eine Aufgabe Arbeitsteilung, Parallelität, Shared State, Verifikation und Wiederherstellung braucht — ist sie kein Loop mehr, sondern ein Graph.
+>
+> **🆕 Juli-2026-Update: Loop Engineering (Loop Engineering)** — 1 neue Vorlesung + 1 neues Projekt + Code-Vorlagen:
+>
+> - **Lektion 13** [Warum du aufhören solltest, deinen Agenten zu prompten](../../docs/de/lectures/lecture-13-loop-engineering/index.md): von `/goal` zu den sechs Primitiven des Loop Engineering (automations, worktrees, skills, connectors, sub-agents, external state), Generator/Evaluator-Trennung, vier stille Kosten und der schrittweise Aufbau deines ersten Loops.
+> - **Projekt 07** [Baue deinen ersten automatisierten Loop](../../docs/de/projects/project-07-loop-engineering-first-loop/index.md): drei fortschreitende Experimente — Goal-Loop, Timer-Loop, Maker-Checker-Loop. Vergleiche manuell vs. automatisiert, miss die Reduktion der Eingriffe, lerne, den Loop zu verlassen.
+> - **Code-Vorlagen**: `goal-template.md`, `loop-state-template.md`, `maker-prompt.md`, `checker-prompt.md` — Plug-and-Play-Vorlagen zum Bauen von Loops.
+>
+> **Kernaussage:** Harness Engineering baut das Auto. Loop Engineering entwirft die Straße, auf der es fährt — und du entwirfst diese Straße von außerhalb des Wagens.
+
- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
@@ -195,15 +210,15 @@ Die vollständigen Kursmaterialien finden Sie auf der **[Dokumentations-Website]
Das Curriculum ist in drei Teile gegliedert:
-1. **Vorlesungen**: 12 konzeptionelle Einheiten, die die Theorie hinter dem Harness Engineering erklären.
-2. **Projekte**: 6 praktische Projekte, bei denen Sie einen agentenbasierten Arbeitsbereich von Grund auf neu aufbauen.
+1. **Vorlesungen**: 14 konzeptionelle Einheiten, die die Theorie hinter dem Harness Engineering erklären.
+2. **Projekte**: 8 praktische Projekte, bei denen Sie einen agentenbasierten Arbeitsbereich von Grund auf neu aufbauen.
3. **Vorlagen-Bibliothek**: Kopierfertige Vorlagen (`AGENTS.md`, `feature_list.json`, `init.sh` usw.), die Sie noch heute in Ihren eigenen Repositories verwenden können.
---
## Schnellstart: Verbessern Sie Ihren Agenten noch heute
-Sie müssen nicht alle 12 Vorlesungen lesen, bevor Sie einen Nutzen ziehen. Wenn Sie bereits einen Coding-Agenten in einem echten Projekt einsetzen, können Sie ihn jetzt sofort verbessern.
+Sie müssen nicht alle 14 Vorlesungen lesen, bevor Sie einen Nutzen ziehen. Wenn Sie bereits einen Coding-Agenten in einem echten Projekt einsetzen, können Sie ihn jetzt sofort verbessern.
Die Idee ist einfach: Anstatt nur Prompts zu schreiben, geben Sie Ihrem Agenten einen Satz strukturierter Dateien, die definieren, was zu tun ist, was bereits erledigt ist und wie die Arbeit verifiziert wird. Diese Dateien befinden sich in Ihrem Repo, sodass jede Session vom gleichen Zustand ausgeht.
@@ -223,7 +238,7 @@ Laden Sie sich die Starter-Vorlagen aus der [Vorlagen-Bibliothek](https://walkin
## Abschlussprojekt: Eine echte App
-Alle sechs Kursprojekte drehen sich um dasselbe Produkt: **eine Electron-basierte Desktop-App für persönliches Wissensmanagement**.
+Alle acht Kursprojekte drehen sich um dasselbe Produkt: **eine Electron-basierte Desktop-App für persönliches Wissensmanagement**.
```text
┌─────────────────────────────────────────────────────┐
@@ -303,6 +318,28 @@ Der Kurs ist für die chronologische Abarbeitung konzipiert. Jede Phase baut auf
v v
P05 Agent verifiziert seine P06 Ein vollständiges Harness
eigene Arbeit aufbauen (Abschlussprojekt)
+
+
+ Phase 7: LOOP AUTOMATISIEREN
+ ============================
+ L13 Hör auf, deinen Agenten zu
+ prompten — designe Loops
+ |
+ v
+ P07 Baue deinen ersten automatisierten
+ Loop (Goal-Loop, Timer-Loop,
+ Maker-Checker-Loop)
+
+ Phase 8: SYSTEM STRUKTURIEREN
+ ==============================
+ L14 Zeichne das System als Graphen —
+ Knoten, Kanten, Shared State, Routing
+ |
+ v
+ P08 Zeichne deinen Workflow als Graphen
+ (expliziter Graph, paralleles
+ Fan-out/Fan-in, Rollback-Kanten,
+ Mensch+Maschine)
```
Jede Phase dauert etwa eine Woche, wenn Sie nebenbei lernen. Wenn Sie schneller vorgehen möchten, können die Phasen 1–3 an einem langen Wochenende absolviert werden.
@@ -311,35 +348,39 @@ Jede Phase dauert etwa eine Woche, wenn Sie nebenbei lernen. Wenn Sie schneller
## Lehrplan
-### Vorlesungen — 12 konzeptionelle Einheiten, die jeweils eine Kernfrage beantworten
+### Vorlesungen — 14 konzeptionelle Einheiten, die jeweils eine Kernfrage beantworten
*Lesen Sie den vollständigen Text jeder Vorlesung auf der [Dokumentations-Website](https://walkinglabs.github.io/learn-harness-engineering/).*
| Session | Frage | Kernidee |
|---------|-------|----------|
-| [L01](../../docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Warum scheitern starke Modelle dennoch bei echten Aufgaben? | Die Lücke zwischen Benchmarks und echtem Engineering |
-| [L02](../../docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md) | Was bedeutet „Harness" eigentlich? | Fünf Subsysteme: Instructions, State, Verification, Scope, Lifecycle |
-| [L03](../../docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Warum muss das Repo die einzige Quelle der Wahrheit sein? | Wenn der Agent es nicht sehen kann, existiert es nicht |
-| [L04](../../docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Warum scheitert eine einzige riesige Instruktionsdatei? | Progressive Enthüllung: eine Karte geben, keine Enzyklopädie |
-| [L05](../../docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Warum verlieren langlaufende Aufgaben ihre Kontinuität? | Fortschritt auf der Festplatte speichern; dort fortfahren, wo man aufgehört hat |
-| [L06](../../docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Warum braucht die Initialisierung eine eigene Phase? | Die Umgebung auf Funktionsfähigkeit prüfen, bevor der Agent mit der Arbeit beginnt |
-| [L07](../../docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Warum greifen Agenten über und schließen unvollständig ab? | Ein Feature gleichzeitig; explizite Definition von „Fertig" |
-| [L08](../../docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Warum sind Feature-Listen Harness-Primitiven? | Maschinenlesbare Scope-Grenzen, die der Agent nicht ignorieren kann |
-| [L09](../../docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Warum melden Agenten zu früh den Erfolg? | Verifizierungslücken: Vertrauen ≠ Korrektheit |
-| [L10](../../docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Warum ändert End-to-End-Testing die Ergebnisse? | Nur ein vollständiger Pipeline-Lauf gilt als echte Verifizierung |
-| [L11](../../docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Warum gehört Observability in das Harness? | Wenn Sie nicht sehen können, was der Agent getan hat, können Sie nicht reparieren, was er zerstört hat |
-| [L12](../../docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Warum muss jede Session einen sauberen Zustand hinterlassen? | Der Erfolg der nächsten Session hängt vom Aufräumen dieser Session ab |
-
-### Projekte — 6 praktische Projekte, die Vorlesungsmethoden auf dieselbe Electron-App anwenden
+| [L01](../../docs/de/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Warum scheitern starke Modelle dennoch bei echten Aufgaben? | Die Lücke zwischen Benchmarks und echtem Engineering |
+| [L02](../../docs/de/lectures/lecture-02-what-a-harness-actually-is/index.md) | Was bedeutet „Harness" eigentlich? | Fünf Subsysteme: Instructions, State, Verification, Scope, Lifecycle |
+| [L03](../../docs/de/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Warum muss das Repo die einzige Quelle der Wahrheit sein? | Wenn der Agent es nicht sehen kann, existiert es nicht |
+| [L04](../../docs/de/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Warum scheitert eine einzige riesige Instruktionsdatei? | Progressive Enthüllung: eine Karte geben, keine Enzyklopädie |
+| [L05](../../docs/de/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Warum verlieren langlaufende Aufgaben ihre Kontinuität? | Fortschritt auf der Festplatte speichern; dort fortfahren, wo man aufgehört hat |
+| [L06](../../docs/de/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Warum braucht die Initialisierung eine eigene Phase? | Die Umgebung auf Funktionsfähigkeit prüfen, bevor der Agent mit der Arbeit beginnt |
+| [L07](../../docs/de/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Warum greifen Agenten über und schließen unvollständig ab? | Ein Feature gleichzeitig; explizite Definition von „Fertig" |
+| [L08](../../docs/de/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Warum sind Feature-Listen Harness-Primitiven? | Maschinenlesbare Scope-Grenzen, die der Agent nicht ignorieren kann |
+| [L09](../../docs/de/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Warum melden Agenten zu früh den Erfolg? | Verifizierungslücken: Vertrauen ≠ Korrektheit |
+| [L10](../../docs/de/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Warum ändert End-to-End-Testing die Ergebnisse? | Nur ein vollständiger Pipeline-Lauf gilt als echte Verifizierung |
+| [L11](../../docs/de/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Warum gehört Observability in das Harness? | Wenn Sie nicht sehen können, was der Agent getan hat, können Sie nicht reparieren, was er zerstört hat |
+| [L12](../../docs/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Warum muss jede Session einen sauberen Zustand hinterlassen? | Der Erfolg der nächsten Session hängt vom Aufräumen dieser Session ab |
+| [L13](../../docs/de/lectures/lecture-13-loop-engineering/index.md) | Warum musst du aufhören, deinen Agenten zu prompten? | Von manuellen Prompts zu autonomen Loops — Ziel-Loops, Timer-Loops, Maker-Checker-Trennung |
+| [L14](../../docs/de/lectures/lecture-14-graph-engineering/index.md) | Warum entwickelt sich ein einzelner Loop zu einem Graphen? | Von Einzel-Loops zu Graph Engineering — Knoten, Kanten, Shared State, Routing — und wann ein Graph wirklich einen Graphen wert ist |
+
+### Projekte — 8 praktische Projekte, die Vorlesungsmethoden auf dieselbe Electron-App anwenden
| Projekt | Was Sie tun | Harness-Mechanismus |
|---------|-------------|---------------------|
-| [P01](../../docs/en/projects/project-01-baseline-vs-minimal-harness/index.md) | Dieselbe Aufgabe zweimal ausführen: nur Prompt vs. regelnbasiert | Minimales Harness: AGENTS.md + init.sh + feature_list.json |
-| [P02](../../docs/en/projects/project-02-agent-readable-workspace/index.md) | Das Repo umstrukturieren, damit der Agent es lesen kann | Agentenlesbarer Arbeitsbereich + persistente Zustandsdateien |
-| [P03](../../docs/en/projects/project-03-multi-session-continuity/index.md) | Den Agenten dort fortfahren lassen, wo er aufgehört hat | Fortschrittsprotokoll + Session-Übergabe + Multi-Session-Kontinuität |
-| [P04](../../docs/en/projects/project-04-incremental-indexing/index.md) | Den Agenten davon abhalten, zu viel oder zu wenig zu tun | Laufzeit-Feedback + Scope-Kontrolle + inkrementelle Indizierung |
-| [P05](../../docs/en/projects/project-05-grounded-qa-verification/index.md) | Den Agenten seine eigene Arbeit verifizieren lassen | Selbstverifizierung + fundierte Q&A + evidenzbasierter Abschluss |
-| [P06](../../docs/en/projects/project-06-runtime-observability-and-debugging/index.md) | Ein vollständiges Harness von Grund auf neu aufbauen (Abschlussprojekt) | Vollständiges Harness: alle Mechanismen + Observability + Ablationsstudie |
+| [P01](../../docs/de/projects/project-01-baseline-vs-minimal-harness/index.md) | Dieselbe Aufgabe zweimal ausführen: nur Prompt vs. regelnbasiert | Minimales Harness: AGENTS.md + init.sh + feature_list.json |
+| [P02](../../docs/de/projects/project-02-agent-readable-workspace/index.md) | Das Repo umstrukturieren, damit der Agent es lesen kann | Agentenlesbarer Arbeitsbereich + persistente Zustandsdateien |
+| [P03](../../docs/de/projects/project-03-multi-session-continuity/index.md) | Den Agenten dort fortfahren lassen, wo er aufgehört hat | Fortschrittsprotokoll + Session-Übergabe + Multi-Session-Kontinuität |
+| [P04](../../docs/de/projects/project-04-incremental-indexing/index.md) | Den Agenten davon abhalten, zu viel oder zu wenig zu tun | Laufzeit-Feedback + Scope-Kontrolle + inkrementelle Indizierung |
+| [P05](../../docs/de/projects/project-05-grounded-qa-verification/index.md) | Den Agenten seine eigene Arbeit verifizieren lassen | Selbstverifizierung + fundierte Q&A + evidenzbasierter Abschluss |
+| [P06](../../docs/de/projects/project-06-runtime-observability-and-debugging/index.md) | Ein vollständiges Harness von Grund auf neu aufbauen (Abschlussprojekt) | Vollständiges Harness: alle Mechanismen + Observability + Ablationsstudie |
+| [P07](../../docs/de/projects/project-07-loop-engineering-first-loop/index.md) | Baue deinen ersten automatisierten Loop | Ziel-Loop, Timer-Loop, Maker-Checker-Trennung, Loop-State-Management |
+| [P08](../../docs/de/projects/project-08-graph-engineering-first-graph/index.md) | Zeichne deinen Workflow als Graph | Explizite Knoten/Kanten/Status/Routing, paralleles Fan-out/Fan-in, Rollback-Kanten, Mensch+Maschine-Freigabe |
```text
PROJEKTENTWICKLUNG
@@ -361,6 +402,13 @@ Jede Phase dauert etwa eine Woche, wenn Sie nebenbei lernen. Wenn Sie schneller
|
v
P06 Vollständiges Harness (Abschluss) Sie bauen das Gesamtsystem
+ |
+ v
+ P07 Ihr erster automatischer Loop Sie verlassen den Loop
+ |
+ v
+ P08 Zeichnen Sie Ihren Workflow als
+ Graph Sie zeichnen das System als Graph
Die Lösung jedes Projekts wird zum Starter des nächsten Projekts.
Die App entwickelt sich weiter. Ihre Harness-Fähigkeiten wachsen mit.
@@ -514,7 +562,7 @@ Primär:
- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)
- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)
-Die vollständige geschichtete Referenzliste finden Sie in [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md).
+Die vollständige geschichtete Referenzliste finden Sie in [`docs/de/resources/reference/`](../../docs/de/resources/reference/index.md).
---
@@ -523,13 +571,13 @@ Die vollständige geschichtete Referenzliste finden Sie in [`docs/en/resources/r
```text
learn-harness-engineering/
├── docs/ # VitePress-Dokumentationsseite
-│ ├── lectures/ # 12 Vorlesungen (index.md + code/ Beispiele)
+│ ├── lectures/ # 14 Vorlesungen (index.md + code/ Beispiele)
│ │ ├── lecture-01-*/
│ │ ├── lecture-02-*/
-│ │ └── ... (insgesamt 12)
-│ ├── projects/ # 6 Projektbeschreibungen
+│ │ └── ... (insgesamt 14)
+│ ├── projects/ # 8 Projektbeschreibungen
│ │ ├── project-01-*/
-│ │ └── ... (insgesamt 6)
+│ │ └── ... (insgesamt 8)
│ └── resources/ # Mehrsprachige Vorlagen & Referenzen
│ ├── en/ # Englische Vorlagen, Checklisten, Leitfäden
│ ├── zh/ # Chinesische Vorlagen, Checklisten, Leitfäden
@@ -549,7 +597,7 @@ learn-harness-engineering/
## Wie der Kurs organisiert ist
- Jede Vorlesung konzentriert sich auf eine Frage
-- Der Kurs umfasst 6 Projekte
+- Der Kurs umfasst 8 Projekte
- Jedes Projekt erfordert, dass der Agent echte Arbeit leistet
- Jedes Projekt vergleicht schwache vs. starke Harness-Ergebnisse
- Was zählt, ist der gemessene Unterschied, nicht wie viele Dokumente geschrieben wurden
diff --git a/docs-readme/es-ES/README.md b/docs-readme/es-ES/README.md
index 7d4b408..6890b09 100644
--- a/docs-readme/es-ES/README.md
+++ b/docs-readme/es-ES/README.md
@@ -22,6 +22,21 @@
Learn Harness Engineering es un curso dedicado a la ingeniería de agentes de codificación de IA. Hemos estudiado y sintetizado en profundidad las teorías y prácticas más avanzadas de Harness Engineering en la industria. Nuestras referencias principales incluyen:
+> **🆕 Actualización de agosto de 2026: Ingeniería de Grafos (Graph Engineering)** — 1 clase nueva + 1 proyecto nuevo:
+>
+> - **Lección 14** [De los Loops Únicos a la Ingeniería de Grafos](../../docs/es/lectures/lecture-14-graph-engineering/index.md): por qué un loop único inevitablemente se convierte en un grafo — las cuatro capas apiladas (prompt → context → loop → graph) y el lugar del harness en ellas, las cuatro piezas del grafo (nodos, aristas, estado compartido, routing), por qué los checkpoints dentro de un loop no salvan los tres fallos estructurales a escala (Goodhart, ceguera hacia arriba, conflicto), los seis pasos independientes del framework para construir tu primer grafo, la diferencia entre Grafo y Workflow, las anclas, el estado actual de los proyectos open source anteriores vs. posteriores al concepto, el impuesto de orquestación, y cuándo realmente vale la pena dibujar un grafo.
+> - **Proyecto 08** [Dibuja tu flujo de trabajo como un grafo](../../docs/es/projects/project-08-graph-engineering-first-graph/index.md): tres experimentos progresivos — dibujar el loop maker-checker como un grafo explícito, añadir nodos paralelos de fan-out/fan-in, y añadir aristas de retroceso condicionales y un nodo de aprobación humana.
+>
+> **Idea clave:** Un loop es un grafo con un solo nodo. Cuando la tarea necesita especialización, paralelismo, estado compartido, verificación y recuperación — deja de ser un loop y se convierte en un grafo.
+>
+> **🆕 Actualización de julio de 2026: Ingeniería de Loops (Loop Engineering)** — 1 clase nueva + 1 proyecto nuevo + plantillas de código:
+>
+> - **Lección 13** [Del Prompting Manual a los Loops Autónomos](../../docs/es/lectures/lecture-13-loop-engineering/index.md): de `/goal` a los seis primitivos del loop engineering (Automations, Worktrees, Skills, Connectors, Sub-agentes, Estado Externo), la separación Generador/Evaluador, los cuatro costes silenciosos, y la construcción paso a paso de tu primer loop.
+> - **Proyecto 07** [Construye Tu Primer Loop Automatizado](../../docs/es/projects/project-07-loop-engineering-first-loop/index.md): tres experimentos progresivos — loop de objetivo, loop de temporizador, loop maker-checker. Comparar manual vs. automatizado, medir la reducción de intervención, aprender a salir del loop.
+> - **Plantillas de código**: `goal-template.md`, `loop-state-template.md`, `maker-prompt.md`, `checker-prompt.md` — plantillas listas para usar para construir loops.
+>
+> **Idea clave:** La ingeniería de harness construye el vehículo. La ingeniería de loops diseña la carretera por la que circula — y tú diseñas esa carretera desde fuera del vehículo.
+
- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
@@ -195,15 +210,15 @@ Para ver todos los materiales del curso, visita el **[Sitio de Documentación](h
El plan de estudios se divide en tres partes:
-1. **Clases**: 12 unidades conceptuales que explican la teoría detrás de Harness Engineering.
-2. **Proyectos**: 6 proyectos prácticos donde construyes un espacio de trabajo para agentes desde cero.
+1. **Clases**: 14 unidades conceptuales que explican la teoría detrás de Harness Engineering.
+2. **Proyectos**: 8 proyectos prácticos donde construyes un espacio de trabajo para agentes desde cero.
3. **Biblioteca de Recursos**: Plantillas listas para copiar (`AGENTS.md`, `feature_list.json`, `init.sh`, etc.) para usar en tus propios repositorios hoy mismo.
---
## Inicio Rápido: Mejora tu agente hoy mismo
-No necesitas leer las 12 clases antes de empezar a obtener valor. Si ya estás usando un agente de codificación en un proyecto real, aquí tienes cómo mejorarlo ahora mismo.
+No necesitas leer las 14 clases antes de empezar a obtener valor. Si ya estás usando un agente de codificación en un proyecto real, aquí tienes cómo mejorarlo ahora mismo.
La idea es simple: en lugar de solo escribir prompts, dale a tu agente un conjunto de archivos estructurados que definan qué hacer, qué se ha hecho y cómo verificar el trabajo. Estos archivos viven dentro de tu repositorio, así que cada sesión comienza desde el mismo estado.
@@ -223,7 +238,7 @@ Obtén las plantillas iniciales de la [Biblioteca de Recursos](https://walkingla
## Proyecto Final: Una aplicación real
-Los seis proyectos del curso giran en torno al mismo producto: **una aplicación de escritorio de base de conocimiento personal basada en Electron**.
+Los ocho proyectos del curso giran en torno al mismo producto: **una aplicación de escritorio de base de conocimiento personal basada en Electron**.
```text
┌─────────────────────────────────────────────────────┐
@@ -305,6 +320,26 @@ El curso está diseñado para realizarse en orden. Cada fase se construye sobre
v v
P05 El agente verifica su P06 Construir un harness completo
propio trabajo (proyecto final)
+
+ Fase 7: AUTOMATIZA EL LOOP
+ ==========================
+ L13 Deja de hacerle prompting a tu agente —
+ diseña loops en su lugar
+ |
+ v
+ P07 Construye tu primer loop automatizado
+ (loop de objetivo, loop de temporizador,
+ maker-checker)
+
+ Fase 8: ESTRUCTURA EL SISTEMA
+ =============================
+ L14 Dibuja el sistema como un grafo —
+ nodos, aristas, estado compartido, routing
+ |
+ v
+ P08 Dibuja tu flujo de trabajo como un grafo
+ (grafo explícito, fan-out/fan-in paralelo,
+ aristas de retroceso, humano en el circuito)
```
Cada fase toma aproximadamente una semana si lo haces a tiempo parcial. Si quieres ir más rápido, las fases 1-3 se pueden completar en un fin de semana largo.
@@ -313,35 +348,39 @@ Cada fase toma aproximadamente una semana si lo haces a tiempo parcial. Si quier
## Programa de Estudios
-### Clases — 12 unidades conceptuales, cada una respondiendo una pregunta central
+### Clases — 14 unidades conceptuales, cada una respondiendo una pregunta central
*Lee el texto completo de cada clase en el [Sitio de Documentación](https://walkinglabs.github.io/learn-harness-engineering/).*
| Sesión | Pregunta | Idea Central |
|---------|----------|--------------|
-| [L01](../../docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Por qué los modelos potentes siguen fallando en tareas reales? | La brecha de capacidad entre benchmarks e ingeniería real |
-| [L02](../../docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md) | Qué significa realmente "harness"? | Cinco subsistemas: instrucciones, estado, verificación, alcance, ciclo de vida |
-| [L03](../../docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Por qué el repositorio debe ser la única fuente de verdad? | Si el agente no puede verlo, no existe |
-| [L04](../../docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Por qué falla un único archivo de instrucciones gigante? | Divulgación progresiva: da un mapa, no una enciclopedia |
-| [L05](../../docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Por qué las tareas de larga duración pierden continuidad? | Persistir el progreso en disco; continuar donde lo dejaste |
-| [L06](../../docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Por qué la inicialización necesita su propia fase? | Verificar que el entorno está saludable antes de que el agente comience a trabajar |
-| [L07](../../docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Por qué los agentes se exceden y no terminan? | Una funcionalidad a la vez; definición explícita de "hecho" |
-| [L08](../../docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Por qué las listas de funcionalidades son primitivas del harness? | Límites de alcance legibles por máquina que el agente no puede ignorar |
-| [L09](../../docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Por qué los agentes declaran victoria demasiado pronto? | Brechas de verificación: confianza ≠ corrección |
-| [L10](../../docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Por qué las pruebas de extremo a extremo cambian los resultados? | Solo una ejecución completa del pipeline cuenta como verificación real |
-| [L11](../../docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Por qué la observabilidad pertenece dentro del harness? | Si no puedes ver lo que el agente hizo, no puedes arreglar lo que rompió |
-| [L12](../../docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Por qué cada sesión debe dejar un estado limpio? | El éxito de la siguiente sesión depende de la limpieza de esta sesión |
-
-### Proyectos — 6 proyectos prácticos aplicando los métodos de las clases a la misma aplicación Electron
+| [L01](../../docs/es/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Por qué los modelos potentes siguen fallando en tareas reales? | La brecha de capacidad entre benchmarks e ingeniería real |
+| [L02](../../docs/es/lectures/lecture-02-what-a-harness-actually-is/index.md) | Qué significa realmente "harness"? | Cinco subsistemas: instrucciones, estado, verificación, alcance, ciclo de vida |
+| [L03](../../docs/es/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Por qué el repositorio debe ser la única fuente de verdad? | Si el agente no puede verlo, no existe |
+| [L04](../../docs/es/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Por qué falla un único archivo de instrucciones gigante? | Divulgación progresiva: da un mapa, no una enciclopedia |
+| [L05](../../docs/es/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Por qué las tareas de larga duración pierden continuidad? | Persistir el progreso en disco; continuar donde lo dejaste |
+| [L06](../../docs/es/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Por qué la inicialización necesita su propia fase? | Verificar que el entorno está saludable antes de que el agente comience a trabajar |
+| [L07](../../docs/es/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Por qué los agentes se exceden y no terminan? | Una funcionalidad a la vez; definición explícita de "hecho" |
+| [L08](../../docs/es/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Por qué las listas de funcionalidades son primitivas del harness? | Límites de alcance legibles por máquina que el agente no puede ignorar |
+| [L09](../../docs/es/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Por qué los agentes declaran victoria demasiado pronto? | Brechas de verificación: confianza ≠ corrección |
+| [L10](../../docs/es/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Por qué las pruebas de extremo a extremo cambian los resultados? | Solo una ejecución completa del pipeline cuenta como verificación real |
+| [L11](../../docs/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Por qué la observabilidad pertenece dentro del harness? | Si no puedes ver lo que el agente hizo, no puedes arreglar lo que rompió |
+| [L12](../../docs/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Por qué cada sesión debe dejar un estado limpio? | El éxito de la siguiente sesión depende de la limpieza de esta sesión |
+| [L13](../../docs/es/lectures/lecture-13-loop-engineering/index.md) | Por qué necesitas dejar de hacerle prompting a tu agente personalmente? | Del prompting manual a los loops autónomos: loop de objetivo, loop de temporizador, separación maker-checker |
+| [L14](../../docs/es/lectures/lecture-14-graph-engineering/index.md) | Por qué un loop único evoluciona hacia un grafo? | De los loops únicos a la ingeniería de grafos: nodos, aristas, estado compartido, routing, y cuándo realmente vale la pena dibujar un grafo |
+
+### Proyectos — 8 proyectos prácticos aplicando los métodos de las clases a la misma aplicación Electron
| Proyecto | Lo que haces | Mecanismo del Harness |
|----------|--------------|----------------------|
-| [P01](../../docs/en/projects/project-01-baseline-vs-minimal-harness/index.md) | Ejecutar la misma tarea dos veces: solo con prompts vs. con reglas primero | Harness mínimo: AGENTS.md + init.sh + feature_list.json |
-| [P02](../../docs/en/projects/project-02-agent-readable-workspace/index.md) | Reestructurar el repositorio para que el agente pueda leerlo | Espacio de trabajo legible por el agente + archivos de estado persistentes |
-| [P03](../../docs/en/projects/project-03-multi-session-continuity/index.md) | Hacer que el agente continúe desde donde se quedó | Registro de progreso + transferencia de sesión + continuidad multi-sesión |
-| [P04](../../docs/en/projects/project-04-incremental-indexing/index.md) | Evitar que el agente haga demasiado o muy poco | Retroalimentación en tiempo de ejecución + control de alcance + indexación incremental |
-| [P05](../../docs/en/projects/project-05-grounded-qa-verification/index.md) | Hacer que el agente verifique su propio trabajo | Auto-verificación + Q&A fundamentado + completación basada en evidencia |
-| [P06](../../docs/en/projects/project-06-runtime-observability-and-debugging/index.md) | Construir un harness completo desde cero (proyecto final) | Harness completo: todos los mecanismos + observabilidad + estudio de ablación |
+| [P01](../../docs/es/projects/project-01-baseline-vs-minimal-harness/index.md) | Ejecutar la misma tarea dos veces: solo con prompts vs. con reglas primero | Harness mínimo: AGENTS.md + init.sh + feature_list.json |
+| [P02](../../docs/es/projects/project-02-agent-readable-workspace/index.md) | Reestructurar el repositorio para que el agente pueda leerlo | Espacio de trabajo legible por el agente + archivos de estado persistentes |
+| [P03](../../docs/es/projects/project-03-multi-session-continuity/index.md) | Hacer que el agente continúe desde donde se quedó | Registro de progreso + transferencia de sesión + continuidad multi-sesión |
+| [P04](../../docs/es/projects/project-04-incremental-indexing/index.md) | Evitar que el agente haga demasiado o muy poco | Retroalimentación en tiempo de ejecución + control de alcance + indexación incremental |
+| [P05](../../docs/es/projects/project-05-grounded-qa-verification/index.md) | Hacer que el agente verifique su propio trabajo | Auto-verificación + Q&A fundamentado + completación basada en evidencia |
+| [P06](../../docs/es/projects/project-06-runtime-observability-and-debugging/index.md) | Construir un harness completo desde cero (proyecto final) | Harness completo: todos los mecanismos + observabilidad + estudio de ablación |
+| [P07](../../docs/es/projects/project-07-loop-engineering-first-loop/index.md) | Construye tu primer loop automatizado | Loop de objetivo, loop de temporizador, separación maker-checker, gestión del estado del loop |
+| [P08](../../docs/es/projects/project-08-graph-engineering-first-graph/index.md) | Dibuja tu flujo de trabajo como un grafo | Nodos/aristas/estado/routing explícitos, fan-out/fan-in paralelo, aristas de retroceso, aprobación con humano en el circuito |
```text
EVOLUCIÓN DEL PROYECTO
@@ -366,6 +405,13 @@ Cada fase toma aproximadamente una semana si lo haces a tiempo parcial. Si quier
|
v
P06 Harness completo (proyecto final) Tú construyes el sistema completo
+ |
+ v
+ P07 Tu primer loop automatizado Tú sales del loop
+ |
+ v
+ P08 Dibuja tu flujo de trabajo Tú dibujas el sistema
+ como un grafo como un grafo
La solución de cada proyecto se convierte en el starter del siguiente.
La app evoluciona. Tus habilidades de harness crecen con ella.
@@ -519,7 +565,7 @@ Primarias:
- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)
- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)
-Consulta la lista completa de referencias en capas en [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md).
+Consulta la lista completa de referencias en capas en [`docs/es/resources/reference/`](../../docs/es/resources/reference/index.md).
---
@@ -528,13 +574,13 @@ Consulta la lista completa de referencias en capas en [`docs/en/resources/refere
```text
learn-harness-engineering/
├── docs/ # Sitio de documentación VitePress
-│ ├── lectures/ # 12 clases (index.md + ejemplos en code/)
+│ ├── lectures/ # 14 clases (index.md + ejemplos en code/)
│ │ ├── lecture-01-*/
│ │ ├── lecture-02-*/
-│ │ └── ... (12 en total)
-│ ├── projects/ # 6 descripciones de proyectos
+│ │ └── ... (14 en total)
+│ ├── projects/ # 8 descripciones de proyectos
│ │ ├── project-01-*/
-│ │ └── ... (6 en total)
+│ │ └── ... (8 en total)
│ └── resources/ # Plantillas y referencias multilingües
│ ├── en/ # Plantillas, checklists y guías en inglés
│ ├── zh/ # Plantillas, checklists y guías en chino
@@ -554,7 +600,7 @@ learn-harness-engineering/
## Cómo está organizado el curso
- Cada clase se enfoca en una pregunta
-- El curso incluye 6 proyectos
+- El curso incluye 8 proyectos
- Cada proyecto requiere que el agente haga trabajo real
- Cada proyecto compara resultados con harness débil vs. fuerte
- Lo que importa es la diferencia medida, no cuánta documentación se escribió
diff --git a/docs-readme/fr-FR/README.md b/docs-readme/fr-FR/README.md
index 36626f4..d403179 100644
--- a/docs-readme/fr-FR/README.md
+++ b/docs-readme/fr-FR/README.md
@@ -22,6 +22,21 @@
Learn Harness Engineering est un cours dédié à l'ingénierie des agents de codage IA. Nous avons étudié et synthétisé en profondeur les théories et pratiques les plus avancées en matière de Harness Engineering dans l'industrie. Nos références principales incluent :
+> **🆕 Mise à jour d'août 2026 : Ingénierie des graphes (Graph Engineering)** — 1 nouveau cours + 1 nouveau projet :
+>
+> - **Cours 14** [Des boucles simples à l'ingénierie des graphes](../../docs/fr/lectures/lecture-14-graph-engineering/index.md) : pourquoi une boucle unique devient naturellement un graphe — la pile à quatre couches (prompt → context → loop → graph) et la place du harness dans celle-ci, les quatre composants d'un graphe (nœuds, arêtes, état partagé, routage), pourquoi les points de contrôle dans un loop ne sauvent pas les trois échecs structurels qui surviennent à l'échelle (Goodhart, cécité vers le haut, conflit), les six étapes indépendantes de tout framework pour construire votre premier graphe, la différence entre Graph et Workflow, les ancres, l'état des projets open source avant vs après la publication, la taxe d'orchestration, et le moment où il vaut réellement la peine de dessiner un graphe.
+> - **Projet 08** [Dessinez votre workflow sous forme de graphe](../../docs/fr/projects/project-08-graph-engineering-first-graph/index.md) : trois expériences progressives — dessiner le loop maker-checker comme un graphe explicite, ajouter un nœud de fan-out/fan-in parallèle, ajouter une arête de retour arrière conditionnelle et un nœud d'approbation humaine.
+>
+> **Idée centrale :** Un loop est un graphe à un seul nœud. Quand une tâche exige la spécialisation, le parallélisme, l'état partagé, la vérification et la récupération — ce n'est plus un loop, c'est un graphe.
+>
+> **🆕 Mise à jour de juillet 2026 : Ingénierie des boucles (Loop Engineering)** — 1 nouveau cours + 1 nouveau projet + des modèles de code :
+>
+> - **Cours 13** [Pourquoi vous devez arrêter de faire du prompting à vos agents vous-même](../../docs/fr/lectures/lecture-13-loop-engineering/index.md) : de `/goal` aux six primitives de l'ingénierie des boucles (automations, worktrees, skills, connecteurs, sous-agents, état externe), la séparation générateur/évaluateur, quatre coûts silencieux, et la construction progressive de votre première boucle.
+> - **Projet 07** [Construisez votre première boucle automatisée](../../docs/fr/projects/project-07-loop-engineering-first-loop/index.md) : trois expériences progressives — boucle par but, boucle temporelle, boucle maker-checker. Comparer manuel vs. automatisé, mesurer la réduction des interventions, apprendre à sortir de la boucle.
+> - **Modèles de code** : `goal-template.md`, `loop-state-template.md`, `maker-prompt.md`, `checker-prompt.md` — des modèles de construction de boucles prêts à l'emploi.
+>
+> **Idée centrale :** Le Harness Engineering construit la voiture. L'ingénierie des boucles conçoit la route sur laquelle elle roule — et vous concevez cette route depuis l'extérieur de la voiture.
+
- [OpenAI : Harness engineering : leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
- [Anthropic : Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
- [Anthropic : Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
@@ -195,15 +210,15 @@ Pour l'ensemble des matériaux du cours, veuillez visiter le **[Site de Document
Le programme est divisé en trois parties :
-1. **Cours magistraux** : 12 unités conceptuelles expliquant la théorie derrière le Harness Engineering.
-2. **Projets** : 6 projets pratiques où vous construisez un espace de travail agentique à partir de zéro.
+1. **Cours magistraux** : 14 unités conceptuelles expliquant la théorie derrière le Harness Engineering.
+2. **Projets** : 8 projets pratiques où vous construisez un espace de travail agentique à partir de zéro.
3. **Bibliothèque de Ressources** : Des modèles prêts à copier (`AGENTS.md`, `feature_list.json`, `init.sh`, etc.) à utiliser dans vos propres dépôts dès aujourd'hui.
---
## Démarrage Rapide : Améliorez votre agent dès aujourd'hui
-Vous n'avez pas besoin de lire les 12 cours avant de commencer à en tirer profit. Si vous utilisez déjà un agent de codage sur un vrai projet, voici comment l'améliorer dès maintenant.
+Vous n'avez pas besoin de lire les 14 cours avant de commencer à en tirer profit. Si vous utilisez déjà un agent de codage sur un vrai projet, voici comment l'améliorer dès maintenant.
L'idée est simple : au lieu de simplement écrire des prompts, donnez à votre agent un ensemble de fichiers structurés qui définissent ce qu'il faut faire, ce qui a été fait et comment vérifier le travail. Ces fichiers résident dans votre dépôt, donc chaque session démarre depuis le même état.
@@ -223,7 +238,7 @@ Récupérez les modèles de démarrage depuis la [Bibliothèque de Ressources](h
## Projet Final : Une véritable application
-Les six projets du cours gravitent autour du même produit : **une application de bureau de base de connaissances personnelle basée sur Electron**.
+Les huit projets du cours gravitent autour du même produit : **une application de bureau de base de connaissances personnelle basée sur Electron**.
```text
┌─────────────────────────────────────────────────────┐
@@ -303,6 +318,27 @@ Le cours est conçu pour être suivi dans l'ordre. Chaque phase s'appuie sur la
v v
P05 L'agent vérifie son propre travail P06 Construire un harness complet
(projet final)
+
+ Phase 7 : AUTOMATISER LE LOOP
+ =============================
+
+ L13 Arrêtez de faire du prompting
+ à vos agents — concevez des boucles
+ |
+ v
+ P07 Construisez votre première boucle automatisée
+ (boucle par but, boucle temporelle, maker-checker)
+
+ Phase 8 : STRUCTURER LE SYSTÈME
+ ================================
+
+ L14 Dessinez le système comme un graphe —
+ nœuds, arêtes, état partagé, routage
+ |
+ v
+ P08 Dessinez votre workflow sous forme de graphe
+ (graphe explicite, fan-out/fan-in parallèle,
+ arête de retour arrière, collaboration homme-machine)
```
Chaque phase prend environ une semaine si vous suivez le cours à temps partiel. Si vous souhaitez aller plus vite, les phases 1 à 3 peuvent être effectuées en un long week-end.
@@ -311,35 +347,39 @@ Chaque phase prend environ une semaine si vous suivez le cours à temps partiel.
## Programme d'Études
-### Cours magistraux -- 12 unités conceptuelles, chacune répondant à une question fondamentale
+### Cours magistraux -- 14 unités conceptuelles, chacune répondant à une question fondamentale
*Lisez le texte complet de chaque cours sur le [Site de Documentation](https://walkinglabs.github.io/learn-harness-engineering/).*
| Session | Question | Idée Centrale |
|---------|----------|---------------|
-| [L01](../../docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Pourquoi les modèles performants échouent-ils encore sur des tâches réelles ? | L'écart de capacité entre les benchmarks et l'ingénierie réelle |
-| [L02](../../docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md) | Que signifie réellement « harness » ? | Cinq sous-systèmes : instructions, état, vérification, portée, cycle de vie |
-| [L03](../../docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Pourquoi le dépôt doit-il être l'unique source de vérité ? | Si l'agent ne peut pas le voir, ça n'existe pas |
-| [L04](../../docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Pourquoi un seul fichier d'instructions géant échoue-t-il ? | Divulgation progressive : donnez une carte, pas une encyclopédie |
-| [L05](../../docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Pourquoi les tâches de longue durée perdent-elles leur continuité ? | Persister le progrès sur disque ; reprendre là où vous vous êtes arrêté |
-| [L06](../../docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Pourquoi l'initialisation nécessite-t-elle sa propre phase ? | Vérifier que l'environnement est sain avant que l'agent ne commence à travailler |
-| [L07](../../docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Pourquoi les agents vont-ils trop loin et n'en font-ils pas assez ? | Une seule fonctionnalité à la fois ; définition explicite de « terminé » |
-| [L08](../../docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Pourquoi les listes de fonctionnalités sont-elles des primitives du harness ? | Des limites de portée lisibles par machine que l'agent ne peut pas ignorer |
-| [L09](../../docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Pourquoi les agents déclarent-ils victoire trop tôt ? | Lacunes de vérification : confiance ≠ correction |
-| [L10](../../docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Pourquoi les tests de bout en bout changent-ils les résultats ? | Seule une exécution complète du pipeline compte comme véritable vérification |
-| [L11](../../docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Pourquoi l'observabilité appartient-elle au harness ? | Si vous ne pouvez pas voir ce que l'agent a fait, vous ne pouvez pas corriger ce qu'il a cassé |
-| [L12](../../docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Pourquoi chaque session doit-elle laisser un état propre ? | Le succès de la prochaine session dépend du nettoyage de celle-ci |
-
-### Projets -- 6 projets pratiques appliquant les méthodes des cours à la même application Electron
+| [L01](../../docs/fr/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Pourquoi les modèles performants échouent-ils encore sur des tâches réelles ? | L'écart de capacité entre les benchmarks et l'ingénierie réelle |
+| [L02](../../docs/fr/lectures/lecture-02-what-a-harness-actually-is/index.md) | Que signifie réellement « harness » ? | Cinq sous-systèmes : instructions, état, vérification, portée, cycle de vie |
+| [L03](../../docs/fr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Pourquoi le dépôt doit-il être l'unique source de vérité ? | Si l'agent ne peut pas le voir, ça n'existe pas |
+| [L04](../../docs/fr/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Pourquoi un seul fichier d'instructions géant échoue-t-il ? | Divulgation progressive : donnez une carte, pas une encyclopédie |
+| [L05](../../docs/fr/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Pourquoi les tâches de longue durée perdent-elles leur continuité ? | Persister le progrès sur disque ; reprendre là où vous vous êtes arrêté |
+| [L06](../../docs/fr/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Pourquoi l'initialisation nécessite-t-elle sa propre phase ? | Vérifier que l'environnement est sain avant que l'agent ne commence à travailler |
+| [L07](../../docs/fr/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Pourquoi les agents vont-ils trop loin et n'en font-ils pas assez ? | Une seule fonctionnalité à la fois ; définition explicite de « terminé » |
+| [L08](../../docs/fr/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Pourquoi les listes de fonctionnalités sont-elles des primitives du harness ? | Des limites de portée lisibles par machine que l'agent ne peut pas ignorer |
+| [L09](../../docs/fr/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Pourquoi les agents déclarent-ils victoire trop tôt ? | Lacunes de vérification : confiance ≠ correction |
+| [L10](../../docs/fr/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Pourquoi les tests de bout en bout changent-ils les résultats ? | Seule une exécution complète du pipeline compte comme véritable vérification |
+| [L11](../../docs/fr/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Pourquoi l'observabilité appartient-elle au harness ? | Si vous ne pouvez pas voir ce que l'agent a fait, vous ne pouvez pas corriger ce qu'il a cassé |
+| [L12](../../docs/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Pourquoi chaque session doit-elle laisser un état propre ? | Le succès de la prochaine session dépend du nettoyage de celle-ci |
+| [L13](../../docs/fr/lectures/lecture-13-loop-engineering/index.md) | Pourquoi devez-vous arrêter de faire du prompting à vos agents vous-même ? | Du prompting manuel aux boucles autonomes — boucle par but, boucle temporelle, séparation maker-checker |
+| [L14](../../docs/fr/lectures/lecture-14-graph-engineering/index.md) | Pourquoi une boucle unique évolue-t-elle en graphe ? | Des boucles simples à l'ingénierie des graphes — nœuds, arêtes, état partagé, routage, et le moment où il vaut vraiment la peine de dessiner |
+
+### Projets -- 8 projets pratiques appliquant les méthodes des cours à la même application Electron
| Projet | Ce que vous faites | Mécanisme du Harness |
|--------|--------------------|----------------------|
-| [P01](../../docs/en/projects/project-01-baseline-vs-minimal-harness/index.md) | Exécuter la même tâche deux fois : avec prompts seuls vs. avec règles d'abord | Harness minimal : AGENTS.md + init.sh + feature_list.json |
-| [P02](../../docs/en/projects/project-02-agent-readable-workspace/index.md) | Restructurer le dépôt pour que l'agent puisse le lire | Espace de travail lisible par l'agent + fichiers d'état persistants |
-| [P03](../../docs/en/projects/project-03-multi-session-continuity/index.md) | Faire en sorte que l'agent reprenne là où il s'est arrêté | Journal de progression + transfert de session + continuité multi-sessions |
-| [P04](../../docs/en/projects/project-04-incremental-indexing/index.md) | Empêcher l'agent d'en faire trop ou pas assez | Retour d'exécution + contrôle de portée + indexation incrémentale |
-| [P05](../../docs/en/projects/project-05-grounded-qa-verification/index.md) | Faire en sorte que l'agent vérifie son propre travail | Auto-vérification + Q&A fondé + achèvement basé sur les preuves |
-| [P06](../../docs/en/projects/project-06-runtime-observability-and-debugging/index.md) | Construire un harness complet à partir de zéro (projet final) | Harness complet : tous les mécanismes + observabilité + étude d'ablation |
+| [P01](../../docs/fr/projects/project-01-baseline-vs-minimal-harness/index.md) | Exécuter la même tâche deux fois : avec prompts seuls vs. avec règles d'abord | Harness minimal : AGENTS.md + init.sh + feature_list.json |
+| [P02](../../docs/fr/projects/project-02-agent-readable-workspace/index.md) | Restructurer le dépôt pour que l'agent puisse le lire | Espace de travail lisible par l'agent + fichiers d'état persistants |
+| [P03](../../docs/fr/projects/project-03-multi-session-continuity/index.md) | Faire en sorte que l'agent reprenne là où il s'est arrêté | Journal de progression + transfert de session + continuité multi-sessions |
+| [P04](../../docs/fr/projects/project-04-incremental-indexing/index.md) | Empêcher l'agent d'en faire trop ou pas assez | Retour d'exécution + contrôle de portée + indexation incrémentale |
+| [P05](../../docs/fr/projects/project-05-grounded-qa-verification/index.md) | Faire en sorte que l'agent vérifie son propre travail | Auto-vérification + Q&A fondé + achèvement basé sur les preuves |
+| [P06](../../docs/fr/projects/project-06-runtime-observability-and-debugging/index.md) | Construire un harness complet à partir de zéro (projet final) | Harness complet : tous les mécanismes + observabilité + étude d'ablation |
+| [P07](../../docs/fr/projects/project-07-loop-engineering-first-loop/index.md) | Construire votre première boucle automatisée | Boucle par but, boucle temporelle, séparation maker-checker, gestion de l'état de boucle |
+| [P08](../../docs/fr/projects/project-08-graph-engineering-first-graph/index.md) | Dessinez votre workflow sous forme de graphe | Nœuds/arêtes/état/routage explicites, fan-out/fan-in parallèle, arête de retour arrière, approbation homme-machine |
```text
ÉVOLUTION DES PROJETS
@@ -362,6 +402,14 @@ Chaque phase prend environ une semaine si vous suivez le cours à temps partiel.
|
v
P06 Harness complet (projet final) Vous construisez le système complet
+ |
+ v
+ P07 Votre première boucle Vous sortez de la boucle
+ automatisée
+ |
+ v
+ P08 Dessinez votre workflow comme Vous dessinez le système comme un graphe
+ un graphe
La solution de chaque projet devient le starter du projet suivant.
L'application évolue. Vos compétences en harness grandissent avec elle.
@@ -513,7 +561,7 @@ Primaires :
- [Thoughtworks / Martin Fowler : Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)
- [Cursor : Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)
-Consultez la liste complète de références en couches dans [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md).
+Consultez la liste complète de références en couches dans [`docs/fr/resources/reference/`](../../docs/fr/resources/reference/index.md).
---
@@ -522,13 +570,13 @@ Consultez la liste complète de références en couches dans [`docs/en/resources
```text
learn-harness-engineering/
├── docs/ # Site de documentation VitePress
-│ ├── lectures/ # 12 cours (index.md + exemples dans code/)
+│ ├── lectures/ # 14 cours (index.md + exemples dans code/)
│ │ ├── lecture-01-*/
│ │ ├── lecture-02-*/
-│ │ └── ... (12 au total)
-│ ├── projects/ # 6 descriptions de projets
+│ │ └── ... (14 au total)
+│ ├── projects/ # 8 descriptions de projets
│ │ ├── project-01-*/
-│ │ └── ... (6 au total)
+│ │ └── ... (8 au total)
│ └── resources/ # Modèles et références multilingues
│ ├── en/ # Modèles, listes de contrôle et guides en anglais
│ ├── zh/ # Modèles, listes de contrôle et guides en chinois
@@ -548,7 +596,7 @@ learn-harness-engineering/
## Comment le cours est organisé
- Chaque cours se concentre sur une seule question
-- Le cours comprend 6 projets
+- Le cours comprend 8 projets
- Chaque projet nécessite que l'agent effectue un véritable travail
- Chaque projet compare les résultats avec un harness faible vs. un harness robuste
- Ce qui compte, c'est la différence mesurée, pas la quantité de documentation rédigée
diff --git a/docs-readme/ja-JP/README.md b/docs-readme/ja-JP/README.md
index 15da3d0..6728022 100644
--- a/docs-readme/ja-JP/README.md
+++ b/docs-readme/ja-JP/README.md
@@ -22,6 +22,21 @@
Learn Harness Engineering は、AIコーディングエージェントのエンジニアリングに特化したコースです。業界最先端の Harness Engineering の理論と実践を深く研究し、統合しました。主な参考文献は以下の通りです:
+> **🆕 2026年8月更新:グラフエンジニアリング(Graph Engineering)**——講義1回 + プロジェクト1つを追加:
+>
+> - **第14回** [単一ループからグラフエンジニアリングへ](../../docs/ja/lectures/lecture-14-graph-engineering/index.md):なぜ単一ループの先に必ずグラフが生まれるのか——4層の重ね合わせ(prompt → context → loop → graph)とharnessの位置、グラフの4つの部品(ノード、エッジ、共有状態、ルーティング)、loop内のチェックポイントが規模上の3つの構造的失敗(Goodhart、上方向の失明、衝突)を救えない理由、フレームワーク非依存の6ステップで最初のグラフを構築する手順、GraphとWorkflowの違い、アンカー、公開前 vs 公開後のオープンソースプロジェクトの現状、オーケストレーション税、そして本当に図を描く価値があるとき。
+> - **プロジェクト 08** [ワークフローをグラフとして描く](../../docs/ja/projects/project-08-graph-engineering-first-graph/index.md):3つの発展的な実験——maker-checker loopを明示的なグラフに描く、並列のfan-out/fan-inノードを追加する、条件付きフォールバックエッジと人間による承認ノードを追加する。
+>
+> **コアとなる見解:** Loopはノードが1つだけのグラフである。タスクが分業、並列、共有状態、検証、リカバリを必要とするとき——それはもはやloopではなく、グラフになる。
+>
+> **🆕 2026年7月更新:ループエンジニアリング(Loop Engineering)**——講義1回 + プロジェクト1つ + コードテンプレートを追加:
+>
+> - **第13回** [なぜあなたはエージェントにプロンプトを与えるのをやめるべきか](../../docs/ja/lectures/lecture-13-loop-engineering/index.md):`/goal` からループエンジニアリングの6つのプリミティブ(automations、worktrees、skills、connectors、sub-agents、external state)、生成者/評価者の分離、4つの静かなコスト、そして最初のループを段階的に構築する手順。
+> - **プロジェクト 07** [初めての自動ループを構築する](../../docs/ja/projects/project-07-loop-engineering-first-loop/index.md):3つの発展的な実験——目標ループ、タイマーループ、maker-checkerループ。手動 vs 自動化の比較、介入の減少の測定、ループから抜け出すことを学ぶ。
+> - **コードテンプレート**:`goal-template.md`、`loop-state-template.md`、`maker-prompt.md`、`checker-prompt.md`——プラグアンドプレイのループ構築テンプレート。
+>
+> **コアとなる見解:** Harnessエンジニアリングは車を作る。ループエンジニアリングはその走る道路を設計する——そしてあなたは車の外から道路を設計する。
+
- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
@@ -194,15 +209,15 @@ Harness Engineering は、モデルの周囲に完全な作業環境を構築し
カリキュラムは3つの部分に分かれています:
-1. **レクチャー**:Harness Engineering の背景理論を説明する12の概念ユニット。
-2. **プロジェクト**:ゼロからエージェントワークスペースを構築する6つのハンズオンプロジェクト。
+1. **レクチャー**:Harness Engineering の背景理論を説明する14の概念ユニット。
+2. **プロジェクト**:ゼロからエージェントワークスペースを構築する8つのハンズオンプロジェクト。
3. **リソースライブラリ**:自分のリポジトリで今日すぐ使えるコピー用テンプレート(`AGENTS.md`、`feature_list.json`、`init.sh` など)。
---
## クイックスタート:今日からエージェントを改善する
-価値を得るために12のレクチャーをすべて読む必要はありません。すでに実際のプロジェクトでコーディングエージェントを使用している場合、今すぐ改善する方法は以下の通りです。
+価値を得るために14のレクチャーをすべて読む必要はありません。すでに実際のプロジェクトでコーディングエージェントを使用している場合、今すぐ改善する方法は以下の通りです。
アイデアはシンプルです:プロンプトを書く代わりに、何をすべきか、何が完了しているか、作業をどう検証するかを定義する構造化ファイルのセットをエージェントに与えます。これらのファイルはリポジトリ内に存在するため、すべてのセッションが同じ状態から始まります。
@@ -222,7 +237,7 @@ Harness Engineering は、モデルの周囲に完全な作業環境を構築し
## カプロジェクト:実際のアプリケーション
-6つのコースプロジェクトはすべて同じ製品を中心に展開しています:**Electron ベースの個人ナレッジベースデスクトップアプリ**です。
+8つのコースプロジェクトはすべて同じ製品を中心に展開しています:**Electron ベースの個人ナレッジベースデスクトップアプリ**です。
```text
┌─────────────────────────────────────────────────────┐
@@ -303,6 +318,25 @@ Harness Engineering は、モデルの周囲に完全な作業環境を構築し
v v
P05 エージェントが自分の作業を検証 P06 完全なハーネスを構築
(カプロジェクト)
+
+ フェーズ7: 自動化ループ
+ ==========================
+ L13 エージェントにプロンプトを
+ 与えるのをやめる——ループを設計する
+ |
+ v
+ P07 初めての自動ループを構築する
+ (目標ループ、タイマーループ、maker-checker)
+
+ フェーズ8: システムを構造化
+ ============================
+ L14 システムをグラフとして描く——
+ ノード、エッジ、共有状態、ルーティング
+ |
+ v
+ P08 ワークフローをグラフとして描く
+ (明示グラフ、並列 fan-out/fan-in、
+ フォールバックエッジ、人間と機械の協働)
```
パートタイムで進める場合、各フェーズは約1週間です。より速く進めたい場合、フェーズ1〜3は長い週末で完了できます。
@@ -311,35 +345,39 @@ Harness Engineering は、モデルの周囲に完全な作業環境を構築し
## シラバス
-### レクチャー — 12の概念ユニット、それぞれが一つのコアな問いに答える
+### レクチャー — 14の概念ユニット、それぞれが一つのコアな問いに答える
*各レクチャーの全文は[ドキュメントウェブサイト](https://walkinglabs.github.io/learn-harness-engineering/)で読めます。*
| セッション | 問い | コアアイデア |
|---------|----------|-----------|
-| [L01](../../docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md) | なぜ強力なモデルでも実際のタスクで失敗するのか? | ベンチマークと実際のエンジニアリングの能力格差 |
-| [L02](../../docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md) | 「ハーネス」とは実際何を意味するのか? | 5つのサブシステム:インストラクション、状態、検証、スコープ、ライフサイクル |
-| [L03](../../docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | なぜリポジトリが唯一の信頼できる情報源でなければならないのか? | エージェントが見られないものは存在しない |
-| [L04](../../docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | なぜ一つの巨大な指示ファイルは失敗するのか? | 段階的開示:百科事典ではなく地図を与える |
-| [L05](../../docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | なぜ長時間実行タスクは連続性を失うのか? | 進捗をディスクに永続化し、前回の続きから再開する |
-| [L06](../../docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | なぜ初期化に独自のフェーズが必要なのか? | エージェントが作業を開始する前に環境が健全であることを確認する |
-| [L07](../../docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | なぜエージェントは過剰に手を出し、不足して終わるのか? | 一度に一つの機能、明確な完了の定義 |
-| [L08](../../docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | なぜ機能リストはハーネスのプリミティブなのか? | エージェントが無視できない機械可読なスコープ境界 |
-| [L09](../../docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | なぜエージェントは早すぎる完了を宣言するのか? | 検証のギャップ:確信 ≠ 正確性 |
-| [L10](../../docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | なぜエンドツーエンドテストが結果を変えるのか? | 完全なパイプライン実行のみが本当の検証として認められる |
-| [L11](../../docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | なぜオブザーバビリティはハーネス内にあるべきなのか? | エージェントが何をしたか見えなければ、何を壊したか修正できない |
-| [L12](../../docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | なぜすべてのセッションがクリーンな状態を残さなければならないのか? | 次のセッションの成功は、このセッションのクリーンアップに依存する |
-
-### プロジェクト — レクチャーの手法を同じ Electron アプリに適用する6つのハンズオンプロジェクト
+| [L01](../../docs/ja/lectures/lecture-01-why-capable-agents-still-fail/index.md) | なぜ強力なモデルでも実際のタスクで失敗するのか? | ベンチマークと実際のエンジニアリングの能力格差 |
+| [L02](../../docs/ja/lectures/lecture-02-what-a-harness-actually-is/index.md) | 「ハーネス」とは実際何を意味するのか? | 5つのサブシステム:インストラクション、状態、検証、スコープ、ライフサイクル |
+| [L03](../../docs/ja/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | なぜリポジトリが唯一の信頼できる情報源でなければならないのか? | エージェントが見られないものは存在しない |
+| [L04](../../docs/ja/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | なぜ一つの巨大な指示ファイルは失敗するのか? | 段階的開示:百科事典ではなく地図を与える |
+| [L05](../../docs/ja/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | なぜ長時間実行タスクは連続性を失うのか? | 進捗をディスクに永続化し、前回の続きから再開する |
+| [L06](../../docs/ja/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | なぜ初期化に独自のフェーズが必要なのか? | エージェントが作業を開始する前に環境が健全であることを確認する |
+| [L07](../../docs/ja/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | なぜエージェントは過剰に手を出し、不足して終わるのか? | 一度に一つの機能、明確な完了の定義 |
+| [L08](../../docs/ja/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | なぜ機能リストはハーネスのプリミティブなのか? | エージェントが無視できない機械可読なスコープ境界 |
+| [L09](../../docs/ja/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | なぜエージェントは早すぎる完了を宣言するのか? | 検証のギャップ:確信 ≠ 正確性 |
+| [L10](../../docs/ja/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | なぜエンドツーエンドテストが結果を変えるのか? | 完全なパイプライン実行のみが本当の検証として認められる |
+| [L11](../../docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | なぜオブザーバビリティはハーネス内にあるべきなのか? | エージェントが何をしたか見えなければ、何を壊したか修正できない |
+| [L12](../../docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | なぜすべてのセッションがクリーンな状態を残さなければならないのか? | 次のセッションの成功は、このセッションのクリーンアップに依存する |
+| [L13](../../docs/ja/lectures/lecture-13-loop-engineering/index.md) | エージェントにプロンプトを与えるのをやめるべきなのはなぜか? | 手動駆動から自動ループへ——目標ループ、タイマーループ、生成者/評価者の分離 |
+| [L14](../../docs/ja/lectures/lecture-14-graph-engineering/index.md) | なぜ単一ループがグラフへと進化するのか? | 単一ループからグラフエンジニアリングへ——ノード、エッジ、共有状態、ルーティング、そして本当に図を描く価値があるとき |
+
+### プロジェクト — レクチャーの手法を同じ Electron アプリに適用する8つのハンズオンプロジェクト
| プロジェクト | やること | ハーネスメカニズム |
|---------|------------|-------------------|
-| [P01](../../docs/en/projects/project-01-baseline-vs-minimal-harness/index.md) | 同じタスクを2回実行:プロンプトのみ vs. ルール優先 | 最小ハーネス:AGENTS.md + init.sh + feature_list.json |
-| [P02](../../docs/en/projects/project-02-agent-readable-workspace/index.md) | エージェントが読めるようにリポジトリを再構築する | エージェント可読ワークスペース + 永続状態ファイル |
-| [P03](../../docs/en/projects/project-03-multi-session-continuity/index.md) | エージェントが前回の続きから再開できるようにする | 進捗ログ + セションハンドオフ + マルチセッション連続性 |
-| [P04](../../docs/en/projects/project-04-incremental-indexing/index.md) | エージェントがやりすぎたり、やらなすぎたりするのを防ぐ | ランタイムフィードバック + スコープ制御 + インクリメンタルインデキシング |
-| [P05](../../docs/en/projects/project-05-grounded-qa-verification/index.md) | エージェントが自分の作業を検証するようにする | 自己検証 + グラウンデッドQ&A + 証拠ベースの完了 |
-| [P06](../../docs/en/projects/project-06-runtime-observability-and-debugging/index.md) | ゼロから完全なハーネスを構築する(カプロジェクト) | フルハーネス:全メカニズム + オブザーバビリティ + アブレーションスタディ |
+| [P01](../../docs/ja/projects/project-01-baseline-vs-minimal-harness/index.md) | 同じタスクを2回実行:プロンプトのみ vs. ルール優先 | 最小ハーネス:AGENTS.md + init.sh + feature_list.json |
+| [P02](../../docs/ja/projects/project-02-agent-readable-workspace/index.md) | エージェントが読めるようにリポジトリを再構築する | エージェント可読ワークスペース + 永続状態ファイル |
+| [P03](../../docs/ja/projects/project-03-multi-session-continuity/index.md) | エージェントが前回の続きから再開できるようにする | 進捗ログ + セションハンドオフ + マルチセッション連続性 |
+| [P04](../../docs/ja/projects/project-04-incremental-indexing/index.md) | エージェントがやりすぎたり、やらなすぎたりするのを防ぐ | ランタイムフィードバック + スコープ制御 + インクリメンタルインデキシング |
+| [P05](../../docs/ja/projects/project-05-grounded-qa-verification/index.md) | エージェントが自分の作業を検証するようにする | 自己検証 + グラウンデッドQ&A + 証拠ベースの完了 |
+| [P06](../../docs/ja/projects/project-06-runtime-observability-and-debugging/index.md) | ゼロから完全なハーネスを構築する(カプロジェクト) | フルハーネス:全メカニズム + オブザーバビリティ + アブレーションスタディ |
+| [P07](../../docs/ja/projects/project-07-loop-engineering-first-loop/index.md) | 初めての自動ループを構築する | 目標ループ、タイマーループ、生成者/評価者の分離、ループ状態管理 |
+| [P08](../../docs/ja/projects/project-08-graph-engineering-first-graph/index.md) | ワークフローをグラフとして描く | 明示的なノード/エッジ/状態/ルーティング、並列 fan-out/fan-in、フォールバックエッジ、人間と機械の協働による承認 |
```text
プロジェクトの進化
@@ -361,6 +399,12 @@ Harness Engineering は、モデルの周囲に完全な作業環境を構築し
|
v
P06 完全なハーネス(カプロジェクト) 完全なシステムを構築する
+ |
+ v
+ P07 初めての自動ループ あなたはループから抜け出す
+ |
+ v
+ P08 ワークフローをグラフとして描く あなたはシステムをグラフにする
各プロジェクトのソリューションが次のプロジェクトのスターターになる。
アプリは進化する。あなたのハーネスキルも共に成長する。
@@ -514,7 +558,7 @@ npm run docs:preview # ビルド済みサイトのプレビュー
- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)
- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)
-完全な階層別参考文献リストは [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md) をご覧ください。
+完全な階層別参考文献リストは [`docs/ja/resources/reference/`](../../docs/ja/resources/reference/index.md) をご覧ください。
---
@@ -523,13 +567,13 @@ npm run docs:preview # ビルド済みサイトのプレビュー
```text
learn-harness-engineering/
├── docs/ # VitePress ドキュメントサイト
-│ ├── lectures/ # 12のレクチャー(index.md + code/ 例)
+│ ├── lectures/ # 14のレクチャー(index.md + code/ 例)
│ │ ├── lecture-01-*/
│ │ ├── lecture-02-*/
-│ │ └── ... (全12)
-│ ├── projects/ # 6つのプロジェクト説明
+│ │ └── ... (全14)
+│ ├── projects/ # 8つのプロジェクト説明
│ │ ├── project-01-*/
-│ │ └── ... (全6)
+│ │ └── ... (全8)
│ └── resources/ # 多言語テンプレートとリファレンス
│ ├── en/ # 英語テンプレート、チェックリスト、ガイド
│ ├── zh/ # 中国語テンプレート、チェックリスト、ガイド
@@ -549,7 +593,7 @@ learn-harness-engineering/
## コースの構成
- 各レクチャーは一つの問いに焦点を当てる
-- コースには6つのプロジェクトが含まれる
+- コースには8つのプロジェクトが含まれる
- すべてのプロジェクトでエージェントが実際の作業を行う
- すべてのプロジェクトで弱いハーネスと強いハーネスの結果を比較する
- 重要なのは測定された差であり、書かれたドキュメントの数ではない
diff --git a/docs-readme/ko-KR/README.md b/docs-readme/ko-KR/README.md
index adff02a..8edd55d 100644
--- a/docs-readme/ko-KR/README.md
+++ b/docs-readme/ko-KR/README.md
@@ -22,6 +22,21 @@
Learn Harness Engineering은 AI 코딩 에이전트의 엔지니어링에 집중하는 강좌입니다. 업계에서 가장 선진적인 Harness Engineering 이론과 실무를 심층적으로 연구하고 종합했습니다. 핵심 참고 자료는 다음과 같습니다:
+> **🆕 2026년 8월 업데이트: 그래프 엔지니어링(Graph Engineering)** — 강의 1개 + 프로젝트 1개 추가:
+>
+> - **제14강** [단일 루프에서 그래프 엔지니어링으로](../../docs/ko/lectures/lecture-14-graph-engineering/index.md): 왜 단일 루프는 반드시 그래프로 자라나는가 — 4층 겹침(prompt → context → loop → graph)과 harness의 위치, 그래프의 네 부품(노드, 엣지, 공유 상태, 라우팅), 왜 루프 안의 체크포인트는 규모에서의 세 가지 구조적 실패(Goodhart, 위쪽 실명, 충돌)를 구하지 못하는지, 프레임워크 무관의 여섯 단계로 첫 그래프 구축, Graph와 Workflow의 차이, 앵커, 출시 전/후 오픈소스 프로젝트 현황, 오케스트레이션 세금, 그리고 언제 정말로 그래프를 그릴 가치가 있는지.
+> - **프로젝트 08** [내 워크플로우를 그래프로 그리기](../../docs/ko/projects/project-08-graph-engineering-first-graph/index.md): 세 가지 단계 실험 — maker-checker loop을 명시적 그래프로 그리기, 병렬 fan-out/fan-in 노드 추가, 조건부 롤백 엣지와 인간 승인 노드 추가.
+>
+> **핵심 관점:** Loop은 노드가 하나뿐인 그래프입니다. 작업이 분업, 병렬, 공유 상태, 검증, 복구를 필요로 하는 순간 — 그것은 더 이상 loop이 아니라 그래프입니다.
+>
+> **🆕 2026년 7월 업데이트: 루프 엔지니어링(Loop Engineering)** — 강의 1개 + 프로젝트 1개 + 코드 템플릿 추가:
+>
+> - **제13강** [왜 당신의 에이전트에게 직접 프롬프팅하는 것을 멈춰야 하는가](../../docs/ko/lectures/lecture-13-loop-engineering/index.md): `/goal`에서 루프 엔지니어링의 여섯 가지 원시(automations, worktrees, skills, connectors, sub-agents, external state), 생성자/평가자 분리, 네 가지 조용한 비용, 그리고 첫 루프 단계별 구축.
+> - **프로젝트 07** [첫 번째 자동 루프 구축하기](../../docs/ko/projects/project-07-loop-engineering-first-loop/index.md): 세 가지 단계 실험 — 목표 루프, 예약 루프, 메이커-체커 루프. 수동 vs 자동 비교, 개입 감소 측정, 루프 밖으로 나가는 법 배우기.
+> - **코드 템플릿**: `goal-template.md`, `loop-state-template.md`, `maker-prompt.md`, `checker-prompt.md` — 바로 사용 가능한 루프 구축 템플릿.
+>
+> **핵심 관점:** Harness 엔지니어링은 차를 만듭니다. 루프 엔지니어링은 그것이 달리는 도로를 설계합니다 — 그리고 당신은 차 밖에서 그 도로를 설계해야 합니다.
+
- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
@@ -195,15 +210,15 @@ Harness engineering은 모델 주변에 안정적인 결과를 생성하는 완
과정은 세 부분으로 나뉩니다:
-1. **강의(Lectures)**: Harness engineering 이론을 설명하는 12개의 개념적 단원.
-2. **프로젝트(Projects)**: 처음부터 에이전트 작업 공간을 구축하는 6개의 실습 프로젝트.
+1. **강의(Lectures)**: Harness engineering 이론을 설명하는 14개의 개념적 단원.
+2. **프로젝트(Projects)**: 처음부터 에이전트 작업 공간을 구축하는 8개의 실습 프로젝트.
3. **리소스 라이브러리**: 여러분의 저장소에 오늘 바로 사용할 수 있는 복사 가능 템플릿(`AGENTS.md`, `feature_list.json`, `init.sh` 등).
---
## 빠른 시작: 오늘 바로 에이전트 개선하기
-12개의 강의를 모두 읽고 나서 가치를 얻기 시작할 필요가 없습니다. 이미 실제 프로젝트에서 코딩 에이전트를 사용하고 있다면, 지금 당장 개선하는 방법은 다음과 같습니다.
+14개의 강의를 모두 읽고 나서 가치를 얻기 시작할 필요가 없습니다. 이미 실제 프로젝트에서 코딩 에이전트를 사용하고 있다면, 지금 당장 개선하는 방법은 다음과 같습니다.
핵심 아이디어는 간단합니다: 프롬프트만 작성하는 대신, 무엇을 해야 하는지, 무엇이 완료되었는지, 작업을 어떻게 검증할지 정의하는 구조화된 파일 세트를 에이전트에 제공하세요. 이 파일들은 저장소 내에 있으므로 모든 세션이 동일한 상태에서 시작합니다.
@@ -223,7 +238,7 @@ Harness engineering은 모델 주변에 안정적인 결과를 생성하는 완
## 캡스톤 프로젝트: 실제 앱
-6개의 강좌 프로젝트는 모두 동일한 제품을 중심으로 전개됩니다: **Electron 기반 개인 지식 베이스 데스크톱 앱**.
+8개의 강좌 프로젝트는 모두 동일한 제품을 중심으로 전개됩니다: **Electron 기반 개인 지식 베이스 데스크톱 앱**.
```text
┌─────────────────────────────────────────────────────┐
@@ -301,6 +316,25 @@ Harness engineering은 모델 주변에 안정적인 결과를 생성하는 완
v v
P05 에이전트가 자체 검증 P06 완전한 하니스 구축
(캡스톤 프로젝트)
+
+ 7단계: 자동화 루프
+ ==========================
+ L13 에이전트에게 프롬프팅하는 것을
+ 멈추고 루프를 설계하자
+ |
+ v
+ P07 첫 번째 자동 루프 구축하기
+ (목표 루프, 예약 루프, 메이커-체커)
+
+ 8단계: 시스템 구조화
+ =============================
+ L14 시스템을 그래프로 그리기—
+ 노드, 엣지, 공유 상태, 라우팅
+ |
+ v
+ P08 내 워크플로우를 그래프로 그리기
+ (명시적 그래프, 병렬 fan-out/fan-in,
+ 롤백 엣지, 인간-기계 협력)
```
파트타임으로 진행하면 각 단계는 약 1주일이 소요됩니다. 더 빠르게 진행하고 싶다면 1~3단계는 긴 주말에 완료할 수 있습니다.
@@ -309,35 +343,39 @@ Harness engineering은 모델 주변에 안정적인 결과를 생성하는 완
## 강의 개요
-### 강의 — 각각 하나의 핵심 질문에 답하는 12개의 개념적 단원
+### 강의 — 각각 하나의 핵심 질문에 답하는 14개의 개념적 단원
*각 강의의 전체 내용은 [문서 웹사이트](https://walkinglabs.github.io/learn-harness-engineering/)에서 읽을 수 있습니다.*
| 세션 | 질문 | 핵심 아이디어 |
|---------|----------|-----------|
-| [L01](../../docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md) | 왜 강력한 모델도 실제 작업에서 여전히 실패하는가? | 벤치마크와 실제 엔지니어링 사이의 역량 격차 |
-| [L02](../../docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md) | "하니스"는 실제로 무엇을 의미하는가? | 다섯 가지 하위 시스템: 지시 사항, 상태, 검증, 범위, 수명 주기 |
-| [L03](../../docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | 왜 저장소가 단일 진실 공급원이어야 하는가? | 에이전트가 볼 수 없다면 존재하지 않는 것과 같다 |
-| [L04](../../docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | 왜 거대한 단일 지시 파일은 실패하는가? | 점진적 공개: 백과사전이 아닌 지도를 제공하라 |
-| [L05](../../docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | 왜 장기 실행 작업은 연속성을 잃는가? | 진행 상황을 디스크에 영속화; 중단된 지점에서 이어하기 |
-| [L06](../../docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | 왜 초기화에 전용 단계가 필요한가? | 에이전트가 작업을 시작하기 전에 환경이 정상인지 확인 |
-| [L07](../../docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | 왜 에이전트는 과도하게 작업하고 불완전하게 마무리하는가? | 한 번에 하나의 기능; 명시적인 완료 정의 |
-| [L08](../../docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | 왜 기능 목록이 하니스 프리미티브인가? | 에이전트가 무시할 수 없는 기계 판독 가능 범위 경계 |
-| [L09](../../docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | 왜 에이전트는 너무 일찍 완료를 선언하는가? | 검증 격차: 자신감 ≠ 정확성 |
-| [L10](../../docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | 왜 엔드투엔드 테스트가 결과를 바꾸는가? | 전체 파이프라인 실행만이 진정한 검증으로 인정된다 |
-| [L11](../../docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | 왜 관측 가능성이 하니스 내에 있어야 하는가? | 에이전트가 무엇을 했는지 볼 수 없으면, 무엇을 망가뜨렸는지 고칠 수 없다 |
-| [L12](../../docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | 왜 모든 세션은 깔끔한 상태를 남겨야 하는가? | 다음 세션의 성공은 이번 세션의 정리에 달려 있다 |
-
-### 프로젝트 — 동일한 Electron 앱에 강의 방법론을 적용하는 6개의 실습 프로젝트
+| [L01](../../docs/ko/lectures/lecture-01-why-capable-agents-still-fail/index.md) | 왜 강력한 모델도 실제 작업에서 여전히 실패하는가? | 벤치마크와 실제 엔지니어링 사이의 역량 격차 |
+| [L02](../../docs/ko/lectures/lecture-02-what-a-harness-actually-is/index.md) | "하니스"는 실제로 무엇을 의미하는가? | 다섯 가지 하위 시스템: 지시 사항, 상태, 검증, 범위, 수명 주기 |
+| [L03](../../docs/ko/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | 왜 저장소가 단일 진실 공급원이어야 하는가? | 에이전트가 볼 수 없다면 존재하지 않는 것과 같다 |
+| [L04](../../docs/ko/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | 왜 거대한 단일 지시 파일은 실패하는가? | 점진적 공개: 백과사전이 아닌 지도를 제공하라 |
+| [L05](../../docs/ko/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | 왜 장기 실행 작업은 연속성을 잃는가? | 진행 상황을 디스크에 영속화; 중단된 지점에서 이어하기 |
+| [L06](../../docs/ko/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | 왜 초기화에 전용 단계가 필요한가? | 에이전트가 작업을 시작하기 전에 환경이 정상인지 확인 |
+| [L07](../../docs/ko/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | 왜 에이전트는 과도하게 작업하고 불완전하게 마무리하는가? | 한 번에 하나의 기능; 명시적인 완료 정의 |
+| [L08](../../docs/ko/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | 왜 기능 목록이 하니스 프리미티브인가? | 에이전트가 무시할 수 없는 기계 판독 가능 범위 경계 |
+| [L09](../../docs/ko/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | 왜 에이전트는 너무 일찍 완료를 선언하는가? | 검증 격차: 자신감 ≠ 정확성 |
+| [L10](../../docs/ko/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | 왜 엔드투엔드 테스트가 결과를 바꾸는가? | 전체 파이프라인 실행만이 진정한 검증으로 인정된다 |
+| [L11](../../docs/ko/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | 왜 관측 가능성이 하니스 내에 있어야 하는가? | 에이전트가 무엇을 했는지 볼 수 없으면, 무엇을 망가뜨렸는지 고칠 수 없다 |
+| [L12](../../docs/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | 왜 모든 세션은 깔끔한 상태를 남겨야 하는가? | 다음 세션의 성공은 이번 세션의 정리에 달려 있다 |
+| [L13](../../docs/ko/lectures/lecture-13-loop-engineering/index.md) | 왜 당신의 에이전트에게 직접 프롬프팅하는 것을 멈춰야 하는가? | 수동 구동에서 자동 루프로 — 목표 루프, 예약 루프, 메이커-체커 분리 |
+| [L14](../../docs/ko/lectures/lecture-14-graph-engineering/index.md) | 왜 단일 루프는 그래프로 진화하는가? | 단일 루프에서 그래프 엔지니어링으로 — 노드, 엣지, 공유 상태, 라우팅, 그리고 언제 정말로 그래프를 그릴 가치가 있는지 |
+
+### 프로젝트 — 동일한 Electron 앱에 강의 방법론을 적용하는 8개의 실습 프로젝트
| 프로젝트 | 수행 내용 | 하니스 메커니즘 |
|---------|------------|-------------------|
-| [P01](../../docs/en/projects/project-01-baseline-vs-minimal-harness/index.md) | 동일한 작업을 두 번 실행: 프롬프트만 vs. 규칙 우선 | 최소 하니스: AGENTS.md + init.sh + feature_list.json |
-| [P02](../../docs/en/projects/project-02-agent-readable-workspace/index.md) | 에이전트가 읽을 수 있도록 저장소 재구성 | 에이전트 판독 가능 작업 공간 + 영속적 상태 파일 |
-| [P03](../../docs/en/projects/project-03-multi-session-continuity/index.md) | 에이전트가 중단된 지점에서 이어가도록 만들기 | 진행 로그 + 세션 인계 + 다중 세션 연속성 |
-| [P04](../../docs/en/projects/project-04-incremental-indexing/index.md) | 에이전트가 너무 많거나 너무 적게 작업하지 않도록 방지 | 런타임 피드백 + 범위 제어 + 점진적 인덱싱 |
-| [P05](../../docs/en/projects/project-05-grounded-qa-verification/index.md) | 에이전트가 자신의 작업을 검증하도록 만들기 | 자체 검증 + 근거 기반 Q&A + 증거 기반 완료 |
-| [P06](../../docs/en/projects/project-06-runtime-observability-and-debugging/index.md) | 처음부터 완전한 하니스 구축 (캡스톤) | 전체 하니스: 모든 메커니즘 + 관측 가능성 + 어블레이션 스터디 |
+| [P01](../../docs/ko/projects/project-01-baseline-vs-minimal-harness/index.md) | 동일한 작업을 두 번 실행: 프롬프트만 vs. 규칙 우선 | 최소 하니스: AGENTS.md + init.sh + feature_list.json |
+| [P02](../../docs/ko/projects/project-02-agent-readable-workspace/index.md) | 에이전트가 읽을 수 있도록 저장소 재구성 | 에이전트 판독 가능 작업 공간 + 영속적 상태 파일 |
+| [P03](../../docs/ko/projects/project-03-multi-session-continuity/index.md) | 에이전트가 중단된 지점에서 이어가도록 만들기 | 진행 로그 + 세션 인계 + 다중 세션 연속성 |
+| [P04](../../docs/ko/projects/project-04-incremental-indexing/index.md) | 에이전트가 너무 많거나 너무 적게 작업하지 않도록 방지 | 런타임 피드백 + 범위 제어 + 점진적 인덱싱 |
+| [P05](../../docs/ko/projects/project-05-grounded-qa-verification/index.md) | 에이전트가 자신의 작업을 검증하도록 만들기 | 자체 검증 + 근거 기반 Q&A + 증거 기반 완료 |
+| [P06](../../docs/ko/projects/project-06-runtime-observability-and-debugging/index.md) | 처음부터 완전한 하니스 구축 (캡스톤) | 전체 하니스: 모든 메커니즘 + 관측 가능성 + 어블레이션 스터디 |
+| [P07](../../docs/ko/projects/project-07-loop-engineering-first-loop/index.md) | 첫 번째 자동 루프 구축 | 목표 루프, 예약 루프, 메이커-체커 분리, 루프 상태 관리 |
+| [P08](../../docs/ko/projects/project-08-graph-engineering-first-graph/index.md) | 내 워크플로우를 그래프로 그리기 | 명시적 노드/엣지/상태/라우팅, 병렬 fan-out/fan-in, 롤백 엣지, 인간-기계 협력 승인 |
```text
프로젝트 발전 과정
@@ -359,6 +397,12 @@ Harness engineering은 모델 주변에 안정적인 결과를 생성하는 완
|
v
P06 완전한 하니스 (캡스톤) 전체 시스템을 구축합니다
+ |
+ v
+ P07 첫 번째 자동 루프 루프 밖으로 나갑니다
+ |
+ v
+ P08 내 워크플로우를 그래프로 그리기 시스템을 그래프로 그립니다
각 프로젝트의 솔루션이 다음 프로젝트의 스타터가 됩니다.
앱이 발전합니다. 여러분의 하니스 기술도 함께 성장합니다.
@@ -512,7 +556,7 @@ npm run docs:preview # 빌드된 사이트 미리보기
- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)
- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)
-계층화된 전체 참고 문헌 목록은 [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md)에서 확인하세요.
+계층화된 전체 참고 문헌 목록은 [`docs/ko/resources/reference/`](../../docs/ko/resources/reference/index.md)에서 확인하세요.
---
@@ -521,13 +565,13 @@ npm run docs:preview # 빌드된 사이트 미리보기
```text
learn-harness-engineering/
├── docs/ # VitePress 문서 사이트
-│ ├── lectures/ # 12개 강의 (index.md + code/ 예제)
+│ ├── lectures/ # 14개 강의 (index.md + code/ 예제)
│ │ ├── lecture-01-*/
│ │ ├── lecture-02-*/
-│ │ └── ... (총 12개)
-│ ├── projects/ # 6개 프로젝트 설명
+│ │ └── ... (총 14개)
+│ ├── projects/ # 8개 프로젝트 설명
│ │ ├── project-01-*/
-│ │ └── ... (총 6개)
+│ │ └── ... (총 8개)
│ └── resources/ # 다국어 템플릿 및 참조 자료
│ ├── en/ # 영어 템플릿, 체크리스트, 가이드
│ ├── zh/ # 중국어 템플릿, 체크리스트, 가이드
@@ -547,7 +591,7 @@ learn-harness-engineering/
## 강좌 구성 방식
- 각 강의는 하나의 질문에 집중합니다
-- 강좌에는 6개의 프로젝트가 포함됩니다
+- 강좌에는 8개의 프로젝트가 포함됩니다
- 모든 프로젝트는 에이전트가 실제 작업을 수행하도록 요구합니다
- 모든 프로젝트는 약한 하니스와 강한 하니스의 결과를 비교합니다
- 중요한 것은 작성된 문서의 양이 아니라 측정된 차이입니다
diff --git a/docs-readme/pt-BR/README.md b/docs-readme/pt-BR/README.md
index 03da505..4c55ae0 100644
--- a/docs-readme/pt-BR/README.md
+++ b/docs-readme/pt-BR/README.md
@@ -21,8 +21,8 @@
<p align="center"><strong>Um curso baseado em projetos sobre a construção do ambiente, gerenciamento de estado, verificação e mecanismos de controle que fazem os agentes de codificação de IA funcionarem de forma confiável.</strong></p>
<p align="center">
- <img src="https://img.shields.io/badge/Aulas-12-blue?style=flat-square" alt="12 Aulas">
- <img src="https://img.shields.io/badge/Projetos-6-green?style=flat-square" alt="6 Projetos">
+ <img src="https://img.shields.io/badge/Aulas-14-blue?style=flat-square" alt="14 Aulas">
+ <img src="https://img.shields.io/badge/Projetos-8-green?style=flat-square" alt="8 Projetos">
<img src="https://img.shields.io/badge/Idiomas-15-yellow?style=flat-square" alt="15 Idiomas">
<img src="https://img.shields.io/badge/Licença-MIT-lightgrey?style=flat-square" alt="Licença MIT">
</p>
@@ -31,6 +31,21 @@
Aprenda Engenharia de Harness é um curso dedicado à engenharia de agentes de codificação de IA. Estudamos profundamente e sintetizamos as teorias e práticas mais avançadas de Engenharia de Harness na indústria. Nossas referências principais incluem:
+> **🆕 Atualização de agosto de 2026: Engenharia de Grafos (Graph Engineering)** — adicionados 1 aula + 1 projeto:
+>
+> - **Aula 14** [Do Loop Único à Engenharia de Grafos](../../docs/pt-BR/lectures/lecture-14-graph-engineering/index.md): por que um único loop inevitavelmente vira um grafo — as quatro camadas empilhadas (prompt → context → loop → graph) e onde o harness se encaixa, as quatro peças do grafo (nós, arestas, estado compartilhado, roteamento), por que os checkpoints dentro de um loop não resolvem os três modos de falha estrutural em escala (Goodhart, cegueira para cima, conflito), os seis passos independentes de framework para construir seu primeiro grafo, a diferença entre Grafo e Workflow, as âncoras, o cenário dos projetos open source antes vs. depois do lançamento, o imposto de orquestração e quando realmente vale a pena desenhar um grafo.
+> - **Projeto 08** [Desenhe Seu Fluxo de Trabalho como um Grafo](../../docs/pt-BR/projects/project-08-graph-engineering-first-graph/index.md): três experimentos progressivos — desenhar o maker-checker loop como um grafo explícito, adicionar um nó de fan-out/fan-in paralelo e adicionar uma aresta de rollback condicional e um nó de aprovação humana.
+>
+> **Ideia central:** um loop é um grafo com um único nó. Quando a tarefa exige divisão de trabalho, paralelismo, estado compartilhado, verificação e recuperação — ela não é mais um loop, é um grafo.
+>
+> **🆕 Atualização de julho de 2026: Engenharia de Loops (Loop Engineering)** — adicionados 1 aula + 1 projeto + modelos de código:
+>
+> - **Aula 13** [Por Que Você Precisa Parar de Dar Prompt ao Seu Agente](../../docs/pt-BR/lectures/lecture-13-loop-engineering/index.md): de `/goal` aos seis primitivos da engenharia de loops (automations, worktrees, skills, connectors, sub-agents, external state), a separação gerador/avaliador, os quatro custos silenciosos e a construção passo a passo do seu primeiro loop.
+> - **Projeto 07** [Construa Seu Primeiro Loop Automatizado](../../docs/pt-BR/projects/project-07-loop-engineering-first-loop/index.md): três experimentos progressivos — loop baseado em objetivo, loop baseado em tempo e loop maker-checker. Compare manual vs. automatizado, meça a redução de intervenção e aprenda a sair do loop.
+> - **Modelos de código**: `goal-template.md`, `loop-state-template.md`, `maker-prompt.md`, `checker-prompt.md` — modelos prontos para construir loops.
+>
+> **Ideia central:** a Engenharia de Harness constrói o carro. A Engenharia de Loops projeta a estrada por onde ele roda — e você projeta essa estrada de fora do carro.
+
- [OpenAI: Engenharia de Harness: aproveitando o Codex em um mundo focado em agentes](https://openai.com/index/harness-engineering/)
- [Anthropic: Harnesses eficazes para agentes de longa duração](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
- [Anthropic: Design de Harness para desenvolvimento de aplicativos de longa duração](https://www.anthropic.com/engineering/harness-design-long-running-apps)
@@ -204,15 +219,15 @@ Para os materiais completos do curso, visite o **[Site de Documentação](https:
O currículo está dividido em três partes:
-1. **Aulas**: 12 unidades conceituais explicando a teoria por trás da engenharia de harness.
-2. **Projetos**: 6 projetos práticos onde você constrói um espaço de trabalho agentic do zero.
+1. **Aulas**: 14 unidades conceituais explicando a teoria por trás da engenharia de harness.
+2. **Projetos**: 8 projetos práticos onde você constrói um espaço de trabalho agentic do zero.
3. **Biblioteca de Recursos**: Modelos prontos para copiar (`AGENTS.md`, `feature_list.json`, `init.sh`, etc.) para usar em seus próprios repositórios hoje.
---
## Início Rápido: Melhore Seu Agente Hoje
-Você não precisa ler todas as 12 aulas antes de começar a obter valor. Se você já está usando um agente de codificação em um projeto real, veja como melhorá-lo agora mesmo.
+Você não precisa ler todas as 14 aulas antes de começar a obter valor. Se você já está usando um agente de codificação em um projeto real, veja como melhorá-lo agora mesmo.
A ideia é simples: em vez de apenas escrever prompts, dê ao seu agente um conjunto de arquivos estruturados que definem o que fazer, o que foi feito e como verificar o trabalho. Esses arquivos vivem dentro do seu repositório, para que cada sessão comece do mesmo estado.
@@ -232,7 +247,7 @@ Pegue os modelos iniciais da [Biblioteca de Recursos](https://walkinglabs.github
## Projeto Final: Um Aplicativo Real
-Todos os seis projetos do curso giram em torno do mesmo produto: **um aplicativo de desktop de base de conhecimento pessoal baseado em Electron**.
+Todos os oito projetos do curso giram em torno do mesmo produto: **um aplicativo de desktop de base de conhecimento pessoal baseado em Electron**.
```text
┌──────────────────────────────────────────────────────┐
@@ -316,6 +331,26 @@ O curso foi projetado para ser realizado em ordem. Cada fase se baseia na anteri
v P06 Construir um harness
P05 O agente verifica o próprio completo (projeto final)
trabalho
+
+ Fase 7: AUTOMATIZE O LOOP
+ ==========================
+ L13 Pare de dar prompt ao seu agente —
+ projete loops em vez disso
+ |
+ v
+ P07 Construa seu primeiro loop automatizado
+ (loop baseado em objetivo, baseado em tempo,
+ maker-checker)
+
+ Fase 8: ESTRUTURE O SISTEMA
+ =============================
+ L14 Desenhe o sistema como um grafo —
+ nós, arestas, estado compartilhado, roteamento
+ |
+ v
+ P08 Desenhe seu fluxo de trabalho como um grafo
+ (grafo explícito, fan-out/fan-in paralelo,
+ aresta de rollback, humano no loop)
```
Cada fase leva cerca de uma semana se você estiver estudando em meio período. Se quiser avançar mais rápido, as fases 1–3 podem ser concluídas em um fim de semana prolongado.
@@ -324,7 +359,7 @@ Cada fase leva cerca de uma semana se você estiver estudando em meio período.
## Ementa
-### Aulas — 12 unidades conceituais, cada uma respondendo a uma pergunta central
+### Aulas — 14 unidades conceituais, cada uma respondendo a uma pergunta central
*Leia o texto completo de cada aula no [Site de Documentação](https://walkinglabs.github.io/learn-harness-engineering/).*
@@ -342,8 +377,10 @@ Cada fase leva cerca de uma semana se você estiver estudando em meio período.
| [L10](../../docs/pt-BR/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Por que o teste de ponta a ponta muda os resultados? | Apenas uma execução de pipeline completa conta como verificação real |
| [L11](../../docs/pt-BR/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Por que a observabilidade pertence ao harness? | Se você não pode ver o que o agente fez, não pode consertar o que ele quebrou |
| [L12](../../docs/pt-BR/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Por que cada sessão deve deixar um estado limpo? | O sucesso da próxima sessão depende da limpeza desta sessão |
+| [L13](../../docs/pt-BR/lectures/lecture-13-loop-engineering/index.md) | Por que você precisa parar de dar prompt ao seu agente? | Do prompting manual aos loops autônomos — loop baseado em objetivo, loop baseado em tempo, separação maker-checker |
+| [L14](../../docs/pt-BR/lectures/lecture-14-graph-engineering/index.md) | Por que um único loop evolui para um grafo? | Do loop único à engenharia de grafos — nós, arestas, estado compartilhado, roteamento e quando realmente vale a pena desenhar
-### Projetos — 6 projetos práticos aplicando os métodos das aulas ao mesmo aplicativo Electron
+### Projetos — 8 projetos práticos aplicando os métodos das aulas ao mesmo aplicativo Electron
| Projeto | O Que Você Faz | Mecanismo de Harness |
|---------|------------|-------------------|
@@ -353,6 +390,8 @@ Cada fase leva cerca de uma semana se você estiver estudando em meio período.
| [P04](../../docs/pt-BR/projects/project-04-incremental-indexing/index.md) | Impeça o agente de fazer demais ou de menos | Feedback de tempo de execução + controle de escopo + indexação incremental |
| [P05](../../docs/pt-BR/projects/project-05-grounded-qa-verification/index.md) | Faça o agente verificar seu próprio trabalho | Autoverificação + Q&A fundamentado + conclusão baseada em evidências |
| [P06](../../docs/pt-BR/projects/project-06-runtime-observability-and-debugging/index.md) | Construa um harness completo do zero (projeto final) | Harness completo: todos os mecanismos + observabilidade + estudo de ablação |
+| [P07](../../docs/pt-BR/projects/project-07-loop-engineering-first-loop/index.md) | Construa seu primeiro loop automatizado | Loop baseado em objetivo, loop baseado em tempo, separação maker-checker, gerenciamento de estado do loop |
+| [P08](../../docs/pt-BR/projects/project-08-graph-engineering-first-graph/index.md) | Desenhe seu fluxo de trabalho como um grafo | Nós/arestas/estado/roteamento explícitos, fan-out/fan-in paralelo, aresta de rollback, aprovação humana |
```text
EVOLUÇÃO DO PROJETO
@@ -374,6 +413,13 @@ Cada fase leva cerca de uma semana se você estiver estudando em meio período.
|
v
P06 Harness completo (projeto final) Você constrói o sistema completo
+ |
+ v
+ P07 Seu primeiro loop automatizado Você sai do loop
+ |
+ v
+ P08 Desenhe seu fluxo de trabalho Você desenha o sistema
+ como um grafo
A solução de cada projeto torna-se o ponto de partida do próximo projeto.
O aplicativo evolui. Suas habilidades de harness crescem com ele.
@@ -542,12 +588,12 @@ Veja a lista completa de referências em camadas em [`docs/pt-BR/resources/refer
```text
learn-harness-engineering/
├── docs/ # Site de documentação VitePress
-│ ├── lectures/ # 12 aulas (index.md + exemplos de código)
+│ ├── lectures/ # 14 aulas (index.md + exemplos de código)
│ │ ├── lecture-01-*/
-│ │ └── ... (12 no total)
-│ ├── projects/ # Descrições de 6 projetos
+│ │ └── ... (14 no total)
+│ ├── projects/ # Descrições de 8 projetos
│ │ ├── project-01-*/
-│ │ └── ... (6 no total)
+│ │ └── ... (8 no total)
│ └── resources/ # Modelos e referências multilíngues (14 idiomas)
│ ├── en/
│ └── ... (14 no total)
@@ -565,7 +611,7 @@ learn-harness-engineering/
## Como o Curso está Organizado
- Cada aula foca em uma pergunta.
-- O curso inclui 6 projetos.
+- O curso inclui 8 projetos.
- Cada projeto exige que o agente faça um trabalho real.
- Cada projeto compara os resultados de um harness fraco vs. forte.
- O que importa é a diferença medida, não quantos documentos foram escritos.
diff --git a/docs-readme/ru-RU/README.md b/docs-readme/ru-RU/README.md
index 7b78211..2446e75 100644
--- a/docs-readme/ru-RU/README.md
+++ b/docs-readme/ru-RU/README.md
@@ -22,6 +22,21 @@
Learn Harness Engineering — курс, посвящённый инженерии AI-агентов для кодинга. Мы глубоко изучили и обобщили самые передовые теории и практики Harness Engineering в индустрии. Наши основные источники:
+> **🆕 Обновление августа 2026: Графовая инженерия (Graph Engineering)** — добавлено 1 лекция + 1 проект:
+>
+> - **Лекция 14** [От одиночных циклов к графовой инженерии](../../docs/ru/lectures/lecture-14-graph-engineering/index.md): почему одиночный цикл неизбежно превращается в граф — четырёхуровневое наслоение (prompt → context → loop → graph) и место harness в нём, четыре элемента графа (узлы, рёбра, общее состояние, маршрутизация), почему чек-поинты внутри loop не спасают от трёх структурных сбоев в масштабе (Гудхарт, слепота вверх, конфликт), независимые от фреймворка шесть шагов построения вашего первого графа, отличие Graph от Workflow, якоря, open-source-проекты до и после релиза, налог за оркестрацию, а также когда граф действительно стоит рисовать.
+> - **Проект 08** [Нарисуйте ваш workflow как граф](../../docs/ru/projects/project-08-graph-engineering-first-graph/index.md): три следующих эксперимента — нарисовать maker-checker loop как явный граф, добавить параллельный узел fan-out/fan-in, добавить условное ребро отката и узел ручного согласования.
+>
+> **Ключевая идея:** Loop — это граф из одного узла. Когда задаче требуются разделение труда, параллелизм, общее состояние, верификация и восстановление — это уже не loop, а граф.
+>
+> **🆕 Обновление июля 2026: Инженерия циклов (Loop Engineering)** — добавлено 1 лекция + 1 проект + шаблоны кода:
+>
+> - **Лекция 13** [Почему вам нужно перестать лично делать запросы к вашему агенту](../../docs/ru/lectures/lecture-13-loop-engineering/index.md): от `/goal` к шести примитивам цикловой инженерии (automations, worktrees, skills, connectors, sub-agents, external state), разделение генератора и оценщика, четыре тихих издержки, а также пошаговое построение вашего первого цикла.
+> - **Проект 07** [Постройте ваш первый автоматический цикл](../../docs/ru/projects/project-07-loop-engineering-first-loop/index.md): три следующих эксперимента — целевой цикл, цикл по расписанию, цикл maker-checker. Сравнение ручного vs автоматического, измерение снижения вмешательства, умение выйти из цикла.
+> - **Шаблоны кода**: `goal-template.md`, `loop-state-template.md`, `maker-prompt.md`, `checker-prompt.md` — готовые к использованию шаблоны для построения циклов.
+>
+> **Ключевая идея:** Harness-инженерия строит машину. Цикловая инженерия проектирует дорогу, по которой она едет, — а вы проектируете эту дорогу извне машины.
+
- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
@@ -201,15 +216,15 @@ Harness состоит из пяти подсистем:
Программа разделена на три части:
-1. **Лекции**: 12 концептуальных блоков, объясняющих теорию Harness Engineering.
-2. **Проекты**: 6 практических проектов, в которых вы строите агентскую рабочую среду с нуля.
+1. **Лекции**: 14 концептуальных блоков, объясняющих теорию Harness Engineering.
+2. **Проекты**: 8 практических проектов, в которых вы строите агентскую рабочую среду с нуля.
3. **Библиотека шаблонов**: готовые к копированию шаблоны (`AGENTS.md`, `feature_list.json`, `init.sh` и др.), которые вы можете использовать в своих репозиториях уже сегодня.
---
## Быстрый старт: улучшите своего агента уже сегодня
-Вам не нужно читать все 12 лекций, чтобы получить пользу. Если вы уже используете coding-агента в реальном проекте, вы можете улучшить его прямо сейчас.
+Вам не нужно читать все 14 лекций, чтобы получить пользу. Если вы уже используете coding-агента в реальном проекте, вы можете улучшить его прямо сейчас.
Идея проста: вместо того чтобы писать только промпты, дайте своему агенту набор структурированных файлов, определяющих, что нужно сделать, что уже сделано и как проверить результат. Эти файлы находятся в вашем репозитории, поэтому каждая сессия стартует из одного и того же состояния.
@@ -229,7 +244,7 @@ Harness состоит из пяти подсистем:
## Итоговый проект: настоящее приложение
-Все шесть проектов курса вращаются вокруг одного продукта: **десктопного приложения для персонального управления знаниями на базе Electron.**
+Все восемь проектов курса вращаются вокруг одного продукта: **десктопного приложения для персонального управления знаниями на базе Electron.**
```text
┌─────────────────────────────────────────────────────┐
@@ -313,6 +328,21 @@ Harness состоит из пяти подсистем:
v v
P05 Агент верифицирует P06 Построить полный harness
собственную работу (итоговый проект)
+
+
+ Фаза 7: АВТОМАТИЗАЦИЯ ЦИКЛА Фаза 8: СТРУКТУРИРОВАНИЕ СИСТЕМЫ
+ ========================= =================================
+
+ L13 Перестаньте делать запросы L14 Изобразите систему как граф —
+ к агенту — проектируйте узлы, рёбра, общее состояние,
+ циклы маршрутизация
+ | |
+ v v
+ P07 Постройте ваш первый P08 Нарисуйте ваш workflow как
+ автоматический цикл граф
+ (целевой цикл, цикл по (явный граф, параллельный
+ расписанию, maker-checker) fan-out/fan-in,
+ ребро отката, человек+машина)
```
Каждая фаза занимает примерно неделю при обучении параллельно с основной работой. Если двигаться быстрее, фазы 1–3 можно пройти за длинные выходные.
@@ -321,35 +351,39 @@ Harness состоит из пяти подсистем:
## Учебная программа
-### Лекции — 12 концептуальных блоков, каждый отвечает на один ключевой вопрос
+### Лекции — 14 концептуальных блоков, каждый отвечает на один ключевой вопрос
*Читайте полный текст каждой лекции на [сайте документации](https://walkinglabs.github.io/learn-harness-engineering/).*
| Занятие | Вопрос | Ключевая идея |
|---------|--------|---------------|
-| [L01](../../docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Почему сильные модели всё равно ошибаются на реальных задачах? | Разрыв между бенчмарками и реальным инжинирингом |
-| [L02](../../docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md) | Что на самом деле означает «harness"? | Пять подсистем: Instructions, State, Verification, Scope, Lifecycle |
-| [L03](../../docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Почему репозиторий должен быть единственным источником истины? | Если агент не может это увидеть — этого не существует |
-| [L04](../../docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Почему одна гигантская инструкция обречена на провал? | Прогрессивное раскрытие: дать карту, а не энциклопедию |
-| [L05](../../docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Почему длительные задачи теряют связность? | Сохранять прогресс на диске; продолжать с того места, где остановились |
-| [L06](../../docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Почему инициализация требует отдельной фазы? | Проверить работоспособность окружения до того, как агент начнёт работу |
-| [L07](../../docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Почему агенты выходят за рамки и не доделывают? | Одна фича за раз; явное определение «готово" |
-| [L08](../../docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Почему feature-списки — это примитивы harness? | Машинно-читаемые границы scope, которые агент не может проигнорировать |
-| [L09](../../docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Почему агенты объявляют успех слишком рано? | Пробелы в верификации: доверие ≠ корректность |
-| [L10](../../docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Почему end-to-end-тестирование меняет результаты? | Только полный прогон pipeline считается настоящей верификацией |
-| [L11](../../docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Почему observability должна быть внутри harness? | Если вы не видите, что сделал агент, вы не сможете починить то, что он сломал |
-| [L12](../../docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Почему каждая сессия должна оставлять чистое состояние? | Успех следующей сессии зависит от уборки в этой |
-
-### Проекты — 6 практических проектов, применяющих методы лекций к одному и тому же Electron-приложению
+| [L01](../../docs/ru/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Почему сильные модели всё равно ошибаются на реальных задачах? | Разрыв между бенчмарками и реальным инжинирингом |
+| [L02](../../docs/ru/lectures/lecture-02-what-a-harness-actually-is/index.md) | Что на самом деле означает «harness"? | Пять подсистем: Instructions, State, Verification, Scope, Lifecycle |
+| [L03](../../docs/ru/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Почему репозиторий должен быть единственным источником истины? | Если агент не может это увидеть — этого не существует |
+| [L04](../../docs/ru/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Почему одна гигантская инструкция обречена на провал? | Прогрессивное раскрытие: дать карту, а не энциклопедию |
+| [L05](../../docs/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Почему длительные задачи теряют связность? | Сохранять прогресс на диске; продолжать с того места, где остановились |
+| [L06](../../docs/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Почему инициализация требует отдельной фазы? | Проверить работоспособность окружения до того, как агент начнёт работу |
+| [L07](../../docs/ru/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Почему агенты выходят за рамки и не доделывают? | Одна фича за раз; явное определение «готово" |
+| [L08](../../docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Почему feature-списки — это примитивы harness? | Машинно-читаемые границы scope, которые агент не может проигнорировать |
+| [L09](../../docs/ru/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Почему агенты объявляют успех слишком рано? | Пробелы в верификации: доверие ≠ корректность |
+| [L10](../../docs/ru/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Почему end-to-end-тестирование меняет результаты? | Только полный прогон pipeline считается настоящей верификацией |
+| [L11](../../docs/ru/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Почему observability должна быть внутри harness? | Если вы не видите, что сделал агент, вы не сможете починить то, что он сломал |
+| [L12](../../docs/ru/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Почему каждая сессия должна оставлять чистое состояние? | Успех следующей сессии зависит от уборки в этой |
+| [L13](../../docs/ru/lectures/lecture-13-loop-engineering/index.md) | Почему вам нужно перестать лично делать запросы к вашему агенту? | От ручного ввода к автономным циклам — целевой цикл, цикл по расписанию, разделение maker и checker |
+| [L14](../../docs/ru/lectures/lecture-14-graph-engineering/index.md) | Почему одиночный цикл превращается в граф? | От одиночных циклов к графовой инженерии — узлы, рёбра, общее состояние, маршрутизация и когда граф действительно стоит рисовать |
+
+### Проекты — 8 практических проектов, применяющих методы лекций к одному и тому же Electron-приложению
| Проект | Что вы делаете | Механизм harness |
|---------|----------------|-------------------|
-| [P01](../../docs/en/projects/project-01-baseline-vs-minimal-harness/index.md) | Выполнить одну задачу дважды: только промпт vs. на основе правил | Минимальный harness: AGENTS.md + init.sh + feature_list.json |
-| [P02](../../docs/en/projects/project-02-agent-readable-workspace/index.md) | Реструктурировать репозиторий для чтения агентом | Агентно-читаемое рабочее пространство + постоянные файлы состояния |
-| [P03](../../docs/en/projects/project-03-multi-session-continuity/index.md) | Позволить агенту продолжить с того места, где он остановился | Протокол прогресса + передача сессии + мультисессионная связность |
-| [P04](../../docs/en/projects/project-04-incremental-indexing/index.md) | Не дать агенту сделать слишком много или слишком мало | Runtime-обратная связь + контроль scope + инкрементальное индексирование |
-| [P05](../../docs/en/projects/project-05-grounded-qa-verification/index.md) | Заставить агента верифицировать собственную работу | Самоверификация + обоснованный Q&A + завершение на основе свидетельств |
-| [P06](../../docs/en/projects/project-06-runtime-observability-and-debugging/index.md) | Построить полный harness с нуля (итоговый проект) | Полный harness: все механизмы + observability + абляционное исследование |
+| [P01](../../docs/ru/projects/project-01-baseline-vs-minimal-harness/index.md) | Выполнить одну задачу дважды: только промпт vs. на основе правил | Минимальный harness: AGENTS.md + init.sh + feature_list.json |
+| [P02](../../docs/ru/projects/project-02-agent-readable-workspace/index.md) | Реструктурировать репозиторий для чтения агентом | Агентно-читаемое рабочее пространство + постоянные файлы состояния |
+| [P03](../../docs/ru/projects/project-03-multi-session-continuity/index.md) | Позволить агенту продолжить с того места, где он остановился | Протокол прогресса + передача сессии + мультисессионная связность |
+| [P04](../../docs/ru/projects/project-04-incremental-indexing/index.md) | Не дать агенту сделать слишком много или слишком мало | Runtime-обратная связь + контроль scope + инкрементальное индексирование |
+| [P05](../../docs/ru/projects/project-05-grounded-qa-verification/index.md) | Заставить агента верифицировать собственную работу | Самоверификация + обоснованный Q&A + завершение на основе свидетельств |
+| [P06](../../docs/ru/projects/project-06-runtime-observability-and-debugging/index.md) | Построить полный harness с нуля (итоговый проект) | Полный harness: все механизмы + observability + абляционное исследование |
+| [P07](../../docs/ru/projects/project-07-loop-engineering-first-loop/index.md) | Построить ваш первый автоматический цикл | Целевой цикл, цикл по расписанию, разделение maker и checker, управление состоянием цикла |
+| [P08](../../docs/ru/projects/project-08-graph-engineering-first-graph/index.md) | Нарисовать ваш workflow как граф | Явные узлы/рёбра/состояние/маршрутизация, параллельный fan-out/fan-in, ребро отката, согласование человеком |
```text
ЭВОЛЮЦИЯ ПРОЕКТОВ
@@ -375,6 +409,14 @@ Harness состоит из пяти подсистем:
|
v
P06 Полный harness (итоговый) Вы строите полную систему
+ |
+ v
+ P07 Ваш первый автоматический Вы выходите из цикла
+ цикл
+ |
+ v
+ P08 Нарисуйте ваш workflow как Вы рисуете систему как граф
+ граф
Solution каждого проекта становится starter'ом следующего.
Приложение эволюционирует. Ваши навыки harness растут вместе с ним.
@@ -528,7 +570,7 @@ npm run docs:preview # Предпросмотр собранного сайт
- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)
- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)
-Полный многоуровневый список ссылок доступен в [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md).
+Полный многоуровневый список ссылок доступен в [`docs/ru/resources/reference/`](../../docs/ru/resources/reference/index.md).
---
@@ -537,13 +579,13 @@ npm run docs:preview # Предпросмотр собранного сайт
```text
learn-harness-engineering/
├── docs/ # Сайт документации на VitePress
-│ ├── lectures/ # 12 лекций (index.md + примеры в code/)
+│ ├── lectures/ # 14 лекций (index.md + примеры в code/)
│ │ ├── lecture-01-*/
│ │ ├── lecture-02-*/
-│ │ └── ... (всего 12)
-│ ├── projects/ # 6 описаний проектов
+│ │ └── ... (всего 14)
+│ ├── projects/ # 8 описаний проектов
│ │ ├── project-01-*/
-│ │ └── ... (всего 6)
+│ │ └── ... (всего 8)
│ └── resources/ # Многоязычные шаблоны и справочники
│ ├── en/ # Английские шаблоны, чек-листы, руководства
│ ├── zh/ # Китайские шаблоны, чек-листы, руководства
@@ -563,7 +605,7 @@ learn-harness-engineering/
## Организация курса
- Каждая лекция сфокусирована на одном вопросе
-- Курс включает 6 проектов
+- Курс включает 8 проектов
- Каждый проект требует, чтобы агент выполнял реальную работу
- Каждый проект сравнивает результаты слабого и сильного harness
- Важен измеримый результат, а не количество написанных документов
diff --git a/docs-readme/tr-TR/README.md b/docs-readme/tr-TR/README.md
index bd053a7..6e6fff0 100644
--- a/docs-readme/tr-TR/README.md
+++ b/docs-readme/tr-TR/README.md
@@ -22,6 +22,21 @@
Learn Harness Engineering, yapay zeka kod yazma ajanlarının mühendisliğine adanmış bir kurstur. Sektördeki en gelişmiş Harness Engineering teorilerini ve uygulamalarını derinlemesine inceleyip sentezledik. Temel referanslarımız:
+> **🆕 2026 Ağustos Güncellemesi: Graph Engineering (Graf Mühendisliği)** — 1 ders + 1 proje eklendi:
+>
+> - **Ders 14** [Tek Döngülerden Graf Mühendisliğine](../../docs/tr/lectures/lecture-14-graph-engineering/index.md): tek bir loop'un neden kaçınılmaz olarak bir grafa dönüştüğü — dört katmanlı yığın (prompt → context → loop → graph) ve harness'ın buradaki yeri, graf'ın dört parçası (düğümler, kenarlar, paylaşılan durum, yönlendirme), ayrıca loop içindeki kontrol noktalarının ölçekteki üç yapısal başarısızlığı (Goodhart, yukarıya körlük, çatışma) neden kurtaramadığı, framework'ten bağımsız ilk graf'ınızı kurmanın altı adımı, Graph ile Workflow arasındaki fark, çapalar, isimden önce ve sonra açık kaynak proje durumu, orkestrasyon vergisi ve ne zaman gerçekten graf çizmeye değer olduğu.
+> - **Proje 08** [İş Akışınızı Bir Graf Olarak Çizin](../../docs/tr/projects/project-08-graph-engineering-first-graph/index.md): üç aşamalı deney — maker-checker loop'unu açık bir graf olarak çizmek, paralel fan-out/fan-in düğümü eklemek, koşullu geri alma kenarı ve insan onayı düğümü eklemek.
+>
+> **Ana fikir:** Loop, tek düğümlü bir graftır. Bir görev iş bölümü, paralellik, paylaşılan durum, doğrulama ve kurtarma gerektirdiğinde — artık bir loop değil, bir graftır.
+>
+> **🆕 2026 Temmuz Güncellemesi: Loop Engineering (Loop Mühendisliği)** — 1 ders + 1 proje + kod şablonları eklendi:
+>
+> - **Ders 13** [Ajanınızı prompt etmeyi neden bırakmanız gerekir](../../docs/tr/lectures/lecture-13-loop-engineering/index.md): `/goal`'dan loop mühendisliğinin altı ilkesine (automations, worktrees, skills, connectors, sub-agents, external state), üretici/değerlendirici ayrımı, dört sessiz maliyet ve ilk loop'unuzu adım adım kurma.
+> - **Proje 07** [İlk Otomatik Loop'unuzu Oluşturun](../../docs/tr/projects/project-07-loop-engineering-first-loop/index.md): üç aşamalı deney — hedef loop'u, zamanlanmış loop, maker-checker loop. Manuel vs. otomatik karşılaştırması, müdahale azalmasını ölçme, loop'un dışına çıkmayı öğrenme.
+> - **Kod şablonları**: `goal-template.md`, `loop-state-template.md`, `maker-prompt.md`, `checker-prompt.md` — tak-çalıştır loop oluşturma şablonları.
+>
+> **Ana fikir:** Harness mühendisliği arabayı inşa eder. Loop mühendisliği, o arabaya gideceği yolu tasarlar — ve siz o yolu aracın dışından tasarlarsınız.
+
- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
@@ -195,15 +210,15 @@ Tüm kurs materyalleri için lütfen **[Dokümantasyon Sitesi](https://walkingla
Müfredat üç bölüme ayrılmıştır:
-1. **Dersler**: Harness engineering'in arkasındaki teoriyi açıklayan 12 kavramsal birim.
-2. **Projeler**: Ajansal bir çalışma alanını sıfırdan inşa ettiğiniz 6 uygulamalı proje.
+1. **Dersler**: Harness engineering'in arkasındaki teoriyi açıklayan 14 kavramsal birim.
+2. **Projeler**: Ajansal bir çalışma alanını sıfırdan inşa ettiğiniz 8 uygulamalı proje.
3. **Kaynak Kütüphanesi**: Kendi depolarınızda bugün kullanabileceğiniz kopya-yapıştır şablonlar (`AGENTS.md`, `feature_list.json`, `init.sh` vb.).
---
## Hızlı başlangıç: Ajanınızı bugün geliştirin
-Değer elde etmeye başlamadan önce 12 dersin tamamını okumanıza gerek yok. Gerçek bir projede zaten bir kod yazma ajanı kullanıyorsanız, onu şu anda nasıl iyileştirebileceğiniz aşağıda.
+Değer elde etmeye başlamadan önce 14 dersin tamamını okumanıza gerek yok. Gerçek bir projede zaten bir kod yazma ajanı kullanıyorsanız, onu şu anda nasıl iyileştirebileceğiniz aşağıda.
Fikir basit: yalnızca prompt yazmak yerine, ajanınıza ne yapacağını, ne yapıldığını ve işin nasıl doğrulanacağını tanımlayan bir dizi yapılandırılmış dosya verin. Bu dosyalar deponuzun içinde yaşar, böylece her oturum aynı durumdan başlar.
@@ -303,6 +318,25 @@ Kurs sırayla yapılacak şekilde tasarlanmıştır. Her aşama bir öncekinin
v v
P05 Ajan kendi işini doğrular P06 Eksiksiz bir harness kur
(bitirme projesi)
+
+ Aşama 7: LOOP'U OTOMATİKLEŞTİR
+ =================================
+ L13 Ajanınızı prompt etmeyi bırakın —
+ loop tasarlayın
+ |
+ v
+ P07 İlk otomatik loop'unuzu oluşturun
+ (hedef loop'u, zamanlanmış loop, maker-checker)
+
+ Aşama 8: SİSTEMİ YAPILANDIR
+ =============================
+ L14 Sistemi bir graf olarak çizin —
+ düğümler, kenarlar, paylaşılan durum, yönlendirme
+ |
+ v
+ P08 İş akışınızı bir graf olarak çizin
+ (açık graf, paralel fan-out/fan-in,
+ geri alma kenarı, insan-ortada)
```
Yarı zamanlı ilerliyorsanız her aşama yaklaşık bir hafta sürer. Daha hızlı gitmek istiyorsanız 1-3. aşamalar uzun bir hafta sonunda tamamlanabilir.
@@ -311,35 +345,39 @@ Yarı zamanlı ilerliyorsanız her aşama yaklaşık bir hafta sürer. Daha hız
## Müfredat
-### Dersler — her biri tek bir temel soruya yanıt veren 12 kavramsal birim
+### Dersler — her biri tek bir temel soruya yanıt veren 14 kavramsal birim
*Her dersin tam metnini [Dokümantasyon Sitesi](https://walkinglabs.github.io/learn-harness-engineering/)'nde okuyun.*
| Oturum | Soru | Temel Fikir |
|---------|------|-------------|
-| [L01](../../docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Güçlü modeller gerçek görevlerde neden hâlâ başarısız olur? | Benchmark'lar ile gerçek mühendislik arasındaki yetenek boşluğu |
-| [L02](../../docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md) | "Harness" aslında ne demek? | Beş alt sistem: talimatlar, durum, doğrulama, kapsam, yaşam döngüsü |
-| [L03](../../docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Depo neden tek kayıt sistemi olmalı? | Ajan göremiyorsa, o şey yok demektir |
-| [L04](../../docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Tek bir dev talimat dosyası neden yetmez? | Aşamalı açılım: bir harita verin, ansiklopedi değil |
-| [L05](../../docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Uzun süren görevler neden sürekliliği kaybeder? | İlerlemeyi diske yaz; kaldığın yerden devam et |
-| [L06](../../docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Başlatma neden kendine ait bir aşama olmalı? | Ajan işe başlamadan önce ortamın sağlıklı olduğunu doğrula |
-| [L07](../../docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Ajanlar neden sınırı aşar ve yarım bırakır? | Bir seferde tek özellik; bittinin açık tanımı |
-| [L08](../../docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Özellik listeleri neden harness'ın temel yapı taşı? | Ajanın görmezden gelemeyeceği, makine okur kapsam sınırları |
-| [L09](../../docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Ajanlar neden zaferi çok erken ilan eder? | Doğrulama boşlukları: güven ≠ doğruluk |
-| [L10](../../docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Uçtan uca test sonuçları neden değiştirir? | Yalnızca tam hat koşusu gerçek doğrulama sayılır |
-| [L11](../../docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Gözlemlenebilirlik neden harness'ın içinde olmalı? | Ajanın ne yaptığını göremiyorsanız, bozduğunu da düzeltemezsiniz |
-| [L12](../../docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Her oturum neden temiz bir durumla bitmeli? | Sonraki oturumun başarısı bu oturumun temizliğine bağlıdır |
-
-### Projeler — ders yöntemlerini aynı Electron uygulamasına uygulayan 6 uygulamalı proje
+| [L01](../../docs/tr/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Güçlü modeller gerçek görevlerde neden hâlâ başarısız olur? | Benchmark'lar ile gerçek mühendislik arasındaki yetenek boşluğu |
+| [L02](../../docs/tr/lectures/lecture-02-what-a-harness-actually-is/index.md) | "Harness" aslında ne demek? | Beş alt sistem: talimatlar, durum, doğrulama, kapsam, yaşam döngüsü |
+| [L03](../../docs/tr/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Depo neden tek kayıt sistemi olmalı? | Ajan göremiyorsa, o şey yok demektir |
+| [L04](../../docs/tr/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Tek bir dev talimat dosyası neden yetmez? | Aşamalı açılım: bir harita verin, ansiklopedi değil |
+| [L05](../../docs/tr/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Uzun süren görevler neden sürekliliği kaybeder? | İlerlemeyi diske yaz; kaldığın yerden devam et |
+| [L06](../../docs/tr/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Başlatma neden kendine ait bir aşama olmalı? | Ajan işe başlamadan önce ortamın sağlıklı olduğunu doğrula |
+| [L07](../../docs/tr/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Ajanlar neden sınırı aşar ve yarım bırakır? | Bir seferde tek özellik; bittinin açık tanımı |
+| [L08](../../docs/tr/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Özellik listeleri neden harness'ın temel yapı taşı? | Ajanın görmezden gelemeyeceği, makine okur kapsam sınırları |
+| [L09](../../docs/tr/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Ajanlar neden zaferi çok erken ilan eder? | Doğrulama boşlukları: güven ≠ doğruluk |
+| [L10](../../docs/tr/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Uçtan uca test sonuçları neden değiştirir? | Yalnızca tam hat koşusu gerçek doğrulama sayılır |
+| [L11](../../docs/tr/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Gözlemlenebilirlik neden harness'ın içinde olmalı? | Ajanın ne yaptığını göremiyorsanız, bozduğunu da düzeltemezsiniz |
+| [L12](../../docs/tr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Her oturum neden temiz bir durumla bitmeli? | Sonraki oturumun başarısı bu oturumun temizliğine bağlıdır |
+| [L13](../../docs/tr/lectures/lecture-13-loop-engineering/index.md) | Ajanınızı prompt etmeyi neden bırakmanız gerekir? | Manuel sürüşten otomatik loop'lara — hedef loop'u, zamanlanmış loop, maker-checker ayrımı |
+| [L14](../../docs/tr/lectures/lecture-14-graph-engineering/index.md) | Tek bir loop neden bir grafa evrilir? | Tek döngüden graf mühendisliğine — düğümler, kenarlar, paylaşılan durum, yönlendirme ve ne zaman gerçekten graf çizmeye değer olduğu |
+
+### Projeler — ders yöntemlerini aynı Electron uygulamasına uygulayan 8 uygulamalı proje
| Proje | Ne yaparsınız | Harness Mekanizması |
|---------|---------------|----------------------|
-| [P01](../../docs/en/projects/project-01-baseline-vs-minimal-harness/index.md) | Aynı görevi iki kez çalıştırın: yalnızca prompt vs. önce kurallar | Minimal harness: AGENTS.md + init.sh + feature_list.json |
-| [P02](../../docs/en/projects/project-02-agent-readable-workspace/index.md) | Depoyu ajanın okuyabileceği şekilde yeniden yapılandırın | Ajanın okuyabildiği çalışma alanı + kalıcı durum dosyaları |
-| [P03](../../docs/en/projects/project-03-multi-session-continuity/index.md) | Ajanın kaldığı yerden devam etmesini sağlayın | İlerleme günlüğü + oturum devri + çok oturumlu süreklilik |
-| [P04](../../docs/en/projects/project-04-incremental-indexing/index.md) | Ajanın çok fazla ya da çok az iş yapmasını engelleyin | Runtime geri bildirimi + kapsam kontrolü + artımlı dizinleme |
-| [P05](../../docs/en/projects/project-05-grounded-qa-verification/index.md) | Ajanın kendi işini doğrulamasını sağlayın | Öz-doğrulama + dayanaklı Soru-Cevap + kanıta dayalı tamamlama |
-| [P06](../../docs/en/projects/project-06-runtime-observability-and-debugging/index.md) | Eksiksiz bir harness'ı sıfırdan kurun (bitirme projesi) | Tam harness: tüm mekanizmalar + gözlemlenebilirlik + ablasyon çalışması |
+| [P01](../../docs/tr/projects/project-01-baseline-vs-minimal-harness/index.md) | Aynı görevi iki kez çalıştırın: yalnızca prompt vs. önce kurallar | Minimal harness: AGENTS.md + init.sh + feature_list.json |
+| [P02](../../docs/tr/projects/project-02-agent-readable-workspace/index.md) | Depoyu ajanın okuyabileceği şekilde yeniden yapılandırın | Ajanın okuyabildiği çalışma alanı + kalıcı durum dosyaları |
+| [P03](../../docs/tr/projects/project-03-multi-session-continuity/index.md) | Ajanın kaldığı yerden devam etmesini sağlayın | İlerleme günlüğü + oturum devri + çok oturumlu süreklilik |
+| [P04](../../docs/tr/projects/project-04-incremental-indexing/index.md) | Ajanın çok fazla ya da çok az iş yapmasını engelleyin | Runtime geri bildirimi + kapsam kontrolü + artımlı dizinleme |
+| [P05](../../docs/tr/projects/project-05-grounded-qa-verification/index.md) | Ajanın kendi işini doğrulamasını sağlayın | Öz-doğrulama + dayanaklı Soru-Cevap + kanıta dayalı tamamlama |
+| [P06](../../docs/tr/projects/project-06-runtime-observability-and-debugging/index.md) | Eksiksiz bir harness'ı sıfırdan kurun (bitirme projesi) | Tam harness: tüm mekanizmalar + gözlemlenebilirlik + ablasyon çalışması |
+| [P07](../../docs/tr/projects/project-07-loop-engineering-first-loop/index.md) | İlk otomatik loop'unuzu oluşturun | Hedef loop'u, zamanlanmış loop, maker-checker ayrımı, loop durum yönetimi |
+| [P08](../../docs/tr/projects/project-08-graph-engineering-first-graph/index.md) | İş akışınızı bir graf olarak çizin | Açık düğüm/kenar/durum/yönlendirme, paralel fan-out/fan-in, geri alma kenarı, insan-ortada onay |
```text
PROJE EVRİMİ
@@ -361,6 +399,12 @@ Yarı zamanlı ilerliyorsanız her aşama yaklaşık bir hafta sürer. Daha hız
|
v
P06 Eksiksiz harness (bitirme) Tam sistemi inşa edersiniz
+ |
+ v
+ P07 İlk otomatik loop'unuz Loop'un dışına çıkarsınız
+ |
+ v
+ P08 İş akışınızı bir graf olarak çizin Sistemi graf olarak çizersiniz
Her projenin solution'ı bir sonraki projenin starter'ı olur.
Uygulama evrilir. Harness yetenekleriniz onunla birlikte büyür.
@@ -514,7 +558,7 @@ Birincil:
- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)
- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)
-Tam katmanlı referans listesini [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md) içinde bulabilirsiniz.
+Tam katmanlı referans listesini [`docs/tr/resources/reference/`](../../docs/tr/resources/reference/index.md) içinde bulabilirsiniz.
---
@@ -523,13 +567,13 @@ Tam katmanlı referans listesini [`docs/en/resources/reference/`](../../docs/en/
```text
learn-harness-engineering/
├── docs/ # VitePress dokümantasyon sitesi
-│ ├── lectures/ # 12 ders (index.md + code/ örnekleri)
+│ ├── lectures/ # 14 ders (index.md + code/ örnekleri)
│ │ ├── lecture-01-*/
│ │ ├── lecture-02-*/
-│ │ └── ... (toplam 12)
-│ ├── projects/ # 6 proje açıklaması
+│ │ └── ... (toplam 14)
+│ ├── projects/ # 8 proje açıklaması
│ │ ├── project-01-*/
-│ │ └── ... (toplam 6)
+│ │ └── ... (toplam 8)
│ └── resources/ # Çok dilli şablonlar ve referanslar
│ ├── en/ # İngilizce şablonlar, kontrol listeleri, rehberler
│ ├── zh/ # Çince şablonlar, kontrol listeleri, rehberler
@@ -549,7 +593,7 @@ learn-harness-engineering/
## Kurs nasıl organize edilmiş
- Her ders tek bir soruya odaklanır
-- Kurs 6 proje içerir
+- Kurs 8 proje içerir
- Her proje ajanın gerçek iş yapmasını gerektirir
- Her proje zayıf vs. güçlü harness sonuçlarını karşılaştırır
- Önemli olan, kaç doküman yazıldığı değil, ölçülen farktır
diff --git a/docs-readme/uk-UA/README.md b/docs-readme/uk-UA/README.md
index 43ceadc..6fc5bfa 100644
--- a/docs-readme/uk-UA/README.md
+++ b/docs-readme/uk-UA/README.md
@@ -21,8 +21,8 @@
<p align="center"><strong>Практичний курс із побудови середовища, управління станом, верифікації та механізмів контролю, які забезпечують надійну роботу AI-агентів для написання коду.</strong></p>
<p align="center">
- <img src="https://img.shields.io/badge/Lectures-12-blue?style=flat-square" alt="12 лекцій">
- <img src="https://img.shields.io/badge/Projects-6-green?style=flat-square" alt="6 проєктів">
+ <img src="https://img.shields.io/badge/Lectures-14-blue?style=flat-square" alt="14 лекцій">
+ <img src="https://img.shields.io/badge/Projects-8-green?style=flat-square" alt="8 проєктів">
<img src="https://img.shields.io/badge/Languages-15-yellow?style=flat-square" alt="15 мов">
<img src="https://img.shields.io/badge/License-MIT-lightgrey?style=flat-square" alt="Ліцензія MIT">
<a href="https://discord.gg/XU7DQmpqk"><img src="https://img.shields.io/badge/Discord-Join_Community-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Приєднатися до спільноти в Discord"></a>
@@ -32,6 +32,21 @@
Learn Harness Engineering — курс, присвячений інженерії AI-агентів для написання коду. Ми ретельно вивчили та синтезували найбільш передові теорії та практики Harness Engineering в індустрії. Основні джерела:
+> **🆕 Оновлення серпня 2026: Графова інженерія (Graph Engineering)** — додано 1 лекцію + 1 проєкт:
+>
+> - **Лекція 14** [Від одиночних циклів до графової інженерії](../../docs/uk/lectures/lecture-14-graph-engineering/index.md): чому одиночний цикл неминуче виростає в граф — чотири рівні, накладені один на одного (prompt → context → loop → graph) та місце harness у них, чотири складові графа (вузли, ребра, спільний стан, маршрутизація), чому контрольні точки всередині циклу не рятують від трьох структурних відмов у масштабі (Гудгарт, сліпота догори, конфлікт), фреймворк-незалежні шість кроків побудови вашого першого графа, різниця між Graph і Workflow, якорі, стан відкритих проєктів до та після публікації, податок на оркестрацію та коли справді варто малювати граф.
+> - **Проєкт 08** [Намалюйте ваш робочий процес як граф](../../docs/uk/projects/project-08-graph-engineering-first-graph/index.md): три експерименти, що нарощують складність — намалювати maker-checker loop як явний граф, додати паралельні вузли fan-out/fan-in, додати умовне ребро відкату та вузол ручного затвердження.
+>
+> **Ключова ідея:** Loop — це граф з одним вузлом. Коли завданню потрібні розподіл праці, паралелізм, спільний стан, верифікація та відновлення — воно вже не loop, а граф.
+>
+> **🆕 Оновлення липня 2026: Інженерія циклів (Loop Engineering)** — додано 1 лекцію + 1 проєкт + шаблони коду:
+>
+> - **Лекція 13** [Чому ви маєте припинити писати промпти для агента самі](../../docs/uk/lectures/lecture-13-loop-engineering/index.md): від `/goal` до шести примітивів інженерії циклів (automations, worktrees, skills, connectors, sub-agents, external state), розділення генератора/оцінювача, чотири тихих вартості та покрокова побудова вашого першого циклу.
+> - **Проєкт 07** [Побудова вашого першого автоматизованого циклу](../../docs/uk/projects/project-07-loop-engineering-first-loop/index.md): три експерименти, що нарощують складність — цикл на основі мети, цикл за таймером, цикл maker-checker. Порівняйте ручний vs. автоматизований, виміряйте зменшення втручання, навчіться виходити з циклу.
+> - **Шаблони коду**: `goal-template.md`, `loop-state-template.md`, `maker-prompt.md`, `checker-prompt.md` — шаблони побудови циклів «підключи і працюй».
+>
+> **Ключова ідея:** Harness engineering будує машину. Інженерія циклів проєктує дорогу, якою вона їде — і ви проєктуєте дорогу з-поза машини.
+
- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
@@ -205,15 +220,15 @@ Harness складається з п'яти підсистем:
Навчальна програма розділена на три частини:
-1. **Лекції**: 12 концептуальних модулів, що пояснюють теорію Harness Engineering.
-2. **Проєкти**: 6 практичних проєктів, у яких ви будуєте агентне робоче середовище з нуля.
+1. **Лекції**: 14 концептуальних модулів, що пояснюють теорію Harness Engineering.
+2. **Проєкти**: 8 практичних проєктів, у яких ви будуєте агентне робоче середовище з нуля.
3. **Бібліотека ресурсів**: Готові до копіювання шаблони (`AGENTS.md`, `feature_list.json`, `init.sh` тощо) для використання у ваших репозиторіях вже сьогодні.
---
## Швидкий старт: покращте свого агента вже сьогодні
-Не потрібно прочитати всі 12 лекцій, перш ніж отримати користь. Якщо ви вже використовуєте агент для написання коду у реальному проєкті, ось як покращити його прямо зараз.
+Не потрібно прочитати всі 14 лекцій, перш ніж отримати користь. Якщо ви вже використовуєте агент для написання коду у реальному проєкті, ось як покращити його прямо зараз.
Ідея проста: замість того щоб просто писати промпти, надайте своєму агенту набір структурованих файлів, які визначають що робити, що вже зроблено та як верифікувати роботу. Ці файли зберігаються у вашому репозиторії, тому кожна сесія починається з одного й того самого стану.
@@ -233,7 +248,7 @@ Harness складається з п'яти підсистем:
## Підсумковий проєкт: реальний застосунок
-Усі шість проєктів курсу обертаються навколо одного продукту: **настільного застосунку персональної бази знань на основі Electron**.
+Усі вісім проєктів курсу обертаються навколо одного продукту: **настільного застосунку персональної бази знань на основі Electron**.
```text
┌──────────────────────────────────────────────────────┐
@@ -313,6 +328,25 @@ Harness складається з п'яти підсистем:
v v
P05 Agent verifies its own work P06 Build a complete harness
(capstone project)
+
+ Phase 7: AUTOMATE THE LOOP
+ ==========================
+ L13 Stop prompting your agent —
+ design loops instead
+ |
+ v
+ P07 Build your first automated loop
+ (goal loop, timer loop, maker-checker)
+
+ Phase 8: STRUCTURE THE SYSTEM
+ =============================
+ L14 Draw the system as a graph —
+ nodes, edges, shared state, routing
+ |
+ v
+ P08 Draw your workflow as a graph
+ (explicit graph, parallel fan-out/fan-in,
+ fallback edge, human-in-the-loop)
```
Кожна фаза займає приблизно тиждень при навчанні неповний робочий день. Якщо ви хочете просуватися швидше, фази 1–3 можна пройти за довгий вихідний.
@@ -321,35 +355,39 @@ Harness складається з п'яти підсистем:
## Навчальна програма
-### Лекції — 12 концептуальних модулів, кожен відповідає на одне ключове питання
+### Лекції — 14 концептуальних модулів, кожен відповідає на одне ключове питання
*Повний текст кожної лекції читайте на [вебсайті документації](https://walkinglabs.github.io/learn-harness-engineering/).*
| Сесія | Питання | Основна ідея |
|-------|---------|--------------|
-| [L01](../../docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Чому потужні моделі все одно провалюються на реальних завданнях? | Розрив між можливостями на бенчмарках і реальною інженерією |
-| [L02](../../docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md) | Що насправді означає «harness»? | П'ять підсистем: інструкції, стан, верифікація, обсяг, життєвий цикл |
-| [L03](../../docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Чому репозиторій має бути єдиним джерелом правди? | Якщо агент не може це побачити — цього не існує |
-| [L04](../../docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Чому один гігантський файл інструкцій не працює? | Прогресивне розкриття: дайте карту, а не енциклопедію |
-| [L05](../../docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Чому тривалі завдання втрачають безперервність? | Зберігайте прогрес на диску; продовжуйте з того місця, де зупинились |
-| [L06](../../docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Чому ініціалізація потребує окремої фази? | Перевіряйте справність середовища перед початком роботи агента |
-| [L07](../../docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Чому агенти виходять за рамки та не доводять справу до кінця? | Одна функція за раз; явне визначення критерію завершення |
-| [L08](../../docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Чому списки функцій є примітивами harness? | Машиночитабельні межі обсягу, які агент не може ігнорувати |
-| [L09](../../docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Чому агенти передчасно оголошують перемогу? | Прогалини у верифікації: впевненість ≠ коректність |
-| [L10](../../docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Чому наскрізне тестування змінює результати? | Лише повний запуск конвеєру вважається реальною верифікацією |
-| [L11](../../docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Чому спостережуваність має бути всередині harness? | Якщо ви не бачите, що зробив агент, ви не можете виправити те, що він зламав |
-| [L12](../../docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Чому кожна сесія має залишати чистий стан? | Успіх наступної сесії залежить від прибирання в поточній |
-
-### Проєкти — 6 практичних проєктів із застосуванням методів лекцій на тому самому Electron-застосунку
+| [L01](../../docs/uk/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Чому потужні моделі все одно провалюються на реальних завданнях? | Розрив між можливостями на бенчмарках і реальною інженерією |
+| [L02](../../docs/uk/lectures/lecture-02-what-a-harness-actually-is/index.md) | Що насправді означає «harness»? | П'ять підсистем: інструкції, стан, верифікація, обсяг, життєвий цикл |
+| [L03](../../docs/uk/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Чому репозиторій має бути єдиним джерелом правди? | Якщо агент не може це побачити — цього не існує |
+| [L04](../../docs/uk/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Чому один гігантський файл інструкцій не працює? | Прогресивне розкриття: дайте карту, а не енциклопедію |
+| [L05](../../docs/uk/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Чому тривалі завдання втрачають безперервність? | Зберігайте прогрес на диску; продовжуйте з того місця, де зупинились |
+| [L06](../../docs/uk/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Чому ініціалізація потребує окремої фази? | Перевіряйте справність середовища перед початком роботи агента |
+| [L07](../../docs/uk/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Чому агенти виходять за рамки та не доводять справу до кінця? | Одна функція за раз; явне визначення критерію завершення |
+| [L08](../../docs/uk/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Чому списки функцій є примітивами harness? | Машиночитабельні межі обсягу, які агент не може ігнорувати |
+| [L09](../../docs/uk/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Чому агенти передчасно оголошують перемогу? | Прогалини у верифікації: впевненість ≠ коректність |
+| [L10](../../docs/uk/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Чому наскрізне тестування змінює результати? | Лише повний запуск конвеєру вважається реальною верифікацією |
+| [L11](../../docs/uk/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Чому спостережуваність має бути всередині harness? | Якщо ви не бачите, що зробив агент, ви не можете виправити те, що він зламав |
+| [L12](../../docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Чому кожна сесія має залишати чистий стан? | Успіх наступної сесії залежить від прибирання в поточній |
+| [L13](../../docs/uk/lectures/lecture-13-loop-engineering/index.md) | Чому вам варто припинити писати промпти для агента самому? | Від ручного керування до автономних циклів — цільовий цикл, цикл за таймером, розділення maker-checker |
+| [L14](../../docs/uk/lectures/lecture-14-graph-engineering/index.md) | Чому одиночний цикл еволюціонує в граф? | Від одиночних циклів до графової інженерії — вузли, ребра, спільний стан, маршрутизація та коли справді варто малювати граф |
+
+### Проєкти — 8 практичних проєктів із застосуванням методів лекцій на тому самому Electron-застосунку
| Проєкт | Що ви робите | Механізм harness |
|--------|-------------|-----------------|
-| [P01](../../docs/en/projects/project-01-baseline-vs-minimal-harness/index.md) | Виконайте одне й те саме завдання двічі: лише промпт vs. правила на першому місці | Мінімальний harness: AGENTS.md + init.sh + feature_list.json |
-| [P02](../../docs/en/projects/project-02-agent-readable-workspace/index.md) | Реструктуруйте репозиторій так, щоб агент міг його читати | Агентне робоче середовище + постійні файли стану |
-| [P03](../../docs/en/projects/project-03-multi-session-continuity/index.md) | Змусьте агента продовжувати з того місця, де він зупинився | Журнал прогресу + передача між сесіями + безперервність кількох сесій |
-| [P04](../../docs/en/projects/project-04-incremental-indexing/index.md) | Зупиніть агента від надмірної або недостатньої роботи | Runtime-зворотний зв'язок + контроль обсягу + інкрементальна індексація |
-| [P05](../../docs/en/projects/project-05-grounded-qa-verification/index.md) | Змусьте агента верифікувати власну роботу | Самоверифікація + обґрунтований Q&A + завершення на основі доказів |
-| [P06](../../docs/en/projects/project-06-runtime-observability-and-debugging/index.md) | Побудуйте повноцінний harness з нуля (підсумковий проєкт) | Повний harness: усі механізми + спостережуваність + дослідження абляції |
+| [P01](../../docs/uk/projects/project-01-baseline-vs-minimal-harness/index.md) | Виконайте одне й те саме завдання двічі: лише промпт vs. правила на першому місці | Мінімальний harness: AGENTS.md + init.sh + feature_list.json |
+| [P02](../../docs/uk/projects/project-02-agent-readable-workspace/index.md) | Реструктуруйте репозиторій так, щоб агент міг його читати | Агентне робоче середовище + постійні файли стану |
+| [P03](../../docs/uk/projects/project-03-multi-session-continuity/index.md) | Змусьте агента продовжувати з того місця, де він зупинився | Журнал прогресу + передача між сесіями + безперервність кількох сесій |
+| [P04](../../docs/uk/projects/project-04-incremental-indexing/index.md) | Зупиніть агента від надмірної або недостатньої роботи | Runtime-зворотний зв'язок + контроль обсягу + інкрементальна індексація |
+| [P05](../../docs/uk/projects/project-05-grounded-qa-verification/index.md) | Змусьте агента верифікувати власну роботу | Самоверифікація + обґрунтований Q&A + завершення на основі доказів |
+| [P06](../../docs/uk/projects/project-06-runtime-observability-and-debugging/index.md) | Побудуйте повноцінний harness з нуля (підсумковий проєкт) | Повний harness: усі механізми + спостережуваність + дослідження абляції |
+| [P07](../../docs/uk/projects/project-07-loop-engineering-first-loop/index.md) | Побудуйте свій перший автоматизований цикл | Цільовий цикл, цикл за таймером, розділення maker-checker, управління станом циклу |
+| [P08](../../docs/uk/projects/project-08-graph-engineering-first-graph/index.md) | Намалюйте ваш робочий процес як граф | Явні вузли/ребра/стан/маршрутизація, паралельний fan-out/fan-in, ребро відкату, затвердження людиною в циклі |
```text
PROJECT EVOLUTION
@@ -371,6 +409,12 @@ Harness складається з п'яти підсистем:
|
v
P06 Complete harness (capstone) You build the full system
+ |
+ v
+ P07 Your first automated loop You step out of the loop
+ |
+ v
+ P08 Draw your workflow as a graph You draw the system as a graph
Each project's solution becomes the next project's starter.
The app evolves. Your harness skills grow with it.
@@ -524,7 +568,7 @@ npm run docs:preview # Preview built site
- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)
- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)
-Повний багаторівневий список джерел дивіться у [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md).
+Повний багаторівневий список джерел дивіться у [`docs/uk/resources/reference/`](../../docs/uk/resources/reference/index.md).
---
@@ -533,12 +577,12 @@ npm run docs:preview # Preview built site
```text
learn-harness-engineering/
├── docs/ # VitePress documentation site
-│ ├── lectures/ # 12 lectures (index.md + code/ examples)
+│ ├── lectures/ # 14 lectures (index.md + code/ examples)
│ │ ├── lecture-01-*/
-│ │ └── ... (12 total)
-│ ├── projects/ # 6 project descriptions
+│ │ └── ... (14 total)
+│ ├── projects/ # 8 project descriptions
│ │ ├── project-01-*/
-│ │ └── ... (6 total)
+│ │ └── ... (8 total)
│ └── resources/ # Multilingual templates & references (14 languages)
│ ├── en/
│ └── ... (14 total)
@@ -556,7 +600,7 @@ learn-harness-engineering/
## Як організований курс
- Кожна лекція зосереджена на одному питанні
-- Курс включає 6 проєктів
+- Курс включає 8 проєктів
- Кожен проєкт вимагає від агента виконання реальної роботи
- Кожен проєкт порівнює результати слабкого та сильного harness
- Важлива вимірювана різниця, а не кількість написаної документації
diff --git a/docs-readme/uz-UZ/README.md b/docs-readme/uz-UZ/README.md
index f9c9c32..da3895d 100644
--- a/docs-readme/uz-UZ/README.md
+++ b/docs-readme/uz-UZ/README.md
@@ -22,6 +22,21 @@
Learn Harness Engineering — KI kod yozuvchi agentlarini ishlab chiqishga bagʻishlangan kurs. Biz sanoatdagi Harness Engineering sohasining eng ilgʻor nazariya va amaliyotlarini chuqur oʻrganib, sintez qildik. Asosiy manbalarimiz:
+> **🆕 2026-yil avgust yangilanishi: Graph Engineering (Graf muhandisligi)** — 1 ta yangi maʼruza + 1 ta loyiha qoʻshildi:
+>
+> - **14-maʼruza** [Yakka loopʼdan grafik muhandisligigacha](../../docs/uz/lectures/lecture-14-graph-engineering/index.md): nima uchun yakka loop muqarrar ravishda grafikka aylanadi — toʻrt qatlamli qoʻshilish (prompt → context → loop → graph) va harnessʼning undagi oʻrni, grafikning toʻrt qismi (tugunlar, chekkalar, umumiy holat, marshrutlash), nima uchun loop ichidagi checkpointʼlar miqyosdagi uchta strukturaviy muvaffaqiyatsizlikni (Goodhart, yuqoriga qarab koʻrlilik, konflikt) qutqara olmaydi, freymvorkdan mustaqil olti qadamli birinchi grafikni qurish, Graph va Workflow oʻrtasidagi farq, anchorʼlar, eʼlondan oldingi va keyingi ochiq manbali loyihalar holati, orkestratsiya soligʼi va qachon haqiqatan grafik chizishga arzir.
+> - **Loyiha 08** [Ish oqimingizni grafik qilib chizing](../../docs/uz/projects/project-08-graph-engineering-first-graph/index.md): uchta progressiv eksperiment — maker-checker loopʼni eksplisit grafik qilib chizish, parallel fan-out/fan-in tugunlarini qoʻshish, shartli qaytish chekkasi va inson tasdiqlash tugunini qoʻshish.
+>
+> **Asosiy fikr:** Loop — faqat bitta tugunli grafik. Vazifa mehnat taqsimoti, parallellik, umumiy holat, tekshiruv va tiklashni talab qilganda — u endi loop emas, grafikdir.
+>
+> **🆕 2026-yil iyul yangilanishi: Loop Engineering (Loop muhandisligi)** — 1 ta yangi maʼruza + 1 ta loyiha + kod andozalari qoʻshildi:
+>
+> - **13-maʼruza** [Nega agentingizga prompt yozishni bas qilishingiz kerak](../../docs/uz/lectures/lecture-13-loop-engineering/index.md): `/goal` dan loop muhandisligining olti primitivigacha (automations, worktrees, skills, connectors, sub-agents, external state), generator/evaluator boʻlinishi, toʻrtta jim xarajat va birinchi loopʼingizni bosqichma-bosqich qurish.
+> - **Loyiha 07** [Birinchi avtomatlashtirilgan loopʼingizni qurish](../../docs/uz/projects/project-07-loop-engineering-first-loop/index.md): uchta progressiv eksperiment — maqsadli loop, taymer loop, maker-checker loop. Qoʻlda vs avtomatik taqqoslash, aralashuv kamayishini oʻlchash, loopʼdan tashqariga chiqishni oʻrganish.
+> - **Kod andozalari**: `goal-template.md`, `loop-state-template.md`, `maker-prompt.md`, `checker-prompt.md` — qutidan chiqib ishlatiladigan loop qurish andozalari.
+>
+> **Asosiy fikr:** Harness muhandisligi mashina qurdi. Loop muhandisligi u harakatlanadigan yoʻlni loyihalaydi — va siz bu yoʻlni mashina tashqarisidan loyihalaysiz.
+
- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
@@ -195,15 +210,15 @@ Toʻliq kurs materiallarini **[hujjatlar saytida](https://walkinglabs.github.io/
Oʻquv dasturi uch qismdan iborat:
-1. **Maʼruzalar**: Harness Engineering ortidagi nazariyani tushuntiruvchi 12 konseptual blok.
-2. **Loyihalar**: Agent asosidagi ish muhitini noldan quradigan 6 ta amaliy loyiha.
+1. **Maʼruzalar**: Harness Engineering ortidagi nazariyani tushuntiruvchi 14 konseptual blok.
+2. **Loyihalar**: Agent asosidagi ish muhitini noldan quradigan 8 ta amaliy loyiha.
3. **Andozalar kutubxonasi**: Bugunoq oʻz repozitoriyalaringizda ishlatish uchun nusxalashga tayyor andozalar (`AGENTS.md`, `feature_list.json`, `init.sh` va h.k.).
---
## Tezkor boshlash: Agentingizni bugunoq yaxshilang
-Foyda olish uchun 12 ta maʼruzani ham oʻqish shart emas. Agar siz allaqachon haqiqiy loyihada kod yozuvchi agentdan foydalansangiz, uni hoziryoq yaxshilashingiz mumkin.
+Foyda olish uchun 14 ta maʼruzani ham oʻqish shart emas. Agar siz allaqachon haqiqiy loyihada kod yozuvchi agentdan foydalansangiz, uni hoziryoq yaxshilashingiz mumkin.
Gʻoya oddiy: faqat promptʼlar yozish oʻrniga, agentingizga nima qilish kerak, nima allaqachon qilingan va ish qanday tekshirilishini belgilovchi strukturaviy fayllar toʻplamini bering. Bu fayllar repozitoriyangizda joylashgan, shunda har bir sessiya bir xil holatdan boshlanadi.
@@ -223,7 +238,7 @@ Boshlangʻich andozalarni [andozalar kutubxonasidan](https://walkinglabs.github.
## Yakuniy loyiha: Haqiqiy ilova
-Oltita kurs loyihasi bir xil mahsulot atrofida qurilgan: **Electron asosidagi shaxsiy bilim bazasi uchun desktop ilova**.
+Sakkizta kurs loyihasi bir xil mahsulot atrofida qurilgan: **Electron asosidagi shaxsiy bilim bazasi uchun desktop ilova**.
```text
┌─────────────────────────────────────────────────────┐
@@ -304,6 +319,27 @@ Kurs xronologik tartibda bajarish uchun moʻljallangan. Har bir bosqich oldingis
| v
v P06 Toʻliq harness qurish
P05 Agent oʻz ishini mustaqil tekshiradi (yakuniy loyiha)
+
+
+ 7-bosqich: LOOPNI AVTOMATLASHTIRISH
+ ===================================
+ L13 Agentingizga prompt yozishni
+ to'xtating — o'rniga loop loyihalang
+ |
+ v
+ P07 Birinchi avtomatlashtirilgan loop'ingizni quring
+ (maqsadli loop, taymer loop, maker-checker)
+
+ 8-bosqich: TIZIMNI TUZILMALASH
+ ==============================
+ L14 Tizimni grafik qilib chizing —
+ tugunlar, chekkalar, umumiy holat,
+ marshrutlash
+ |
+ v
+ P08 Ish oqimingizni grafik qilib chizing
+ (eksplisit grafik, parallel fan-out/fan-in,
+ qaytish chekkalari, inson ishtiroki)
```
Agar parallel oʻqisangiz, har bir bosqich taxminan bir hafta davom etadi. Agar tezroq borishni xohlasangiz, 1–3 bosqichlarni bitta uzun dam olish kunlarida tugatishingiz mumkin.
@@ -312,35 +348,39 @@ Agar parallel oʻqisangiz, har bir bosqich taxminan bir hafta davom etadi. Agar
## Oʻquv dasturi
-### Maʼruzalar — har biri muhim savolga javob beruvchi 12 ta konseptual blok
+### Maʼruzalar — har biri muhim savolga javob beruvchi 14 ta konseptual blok
*Har bir maʼruza matnini toʻliq oʻqish uchun [hujjatlar sayti](https://walkinglabs.github.io/learn-harness-engineering/)ga murojaat qiling.*
| Sessiya | Savol | Asosiy gʻoya |
|---------|-------|--------------|
-| [L01](../../docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Kuchli modellar nega haqiqiy vazifalarda muvaffaqiyatsiz boʻladi? | Benchmarkʼlar va haqiqiy muhandislik oʻrtasidagi farq |
-| [L02](../../docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md) | "Harness" nima degani? | Besh quyi tizim: Koʻrsatmalar, Holat, Tekshiruv, Doira, Hayot sikli |
-| [L03](../../docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Nega repozitoriy yagona haqiqat manbai boʻlishi kerak? | Agar agent koʻrolmasa, u mavjud emas |
-| [L04](../../docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Nega bitta ulkan koʻrsatma fayli muvaffaqiyatsiz boʻladi? | Progressiv ochilish: xarita berish, ensiklopediya emas |
-| [L05](../../docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Nega uzoq davom etuvchi vazifalar uzluksizlikni yoʻqotadi? | Taraqqiyotni diskda saqlash; toʻxtagan joydan davom ettirish |
-| [L06](../../docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Nega ishga tushirish alohida bosqichga muhtoj? | Agent ishni boshlashdan oldin muhit ishlashini tekshirish |
-| [L07](../../docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Nega agentlar haddan oshadi va yarim-yorti tugatadi? | Bir vaqtda bitta funksiya; "Tugadi" ning aniq taʼrifi |
-| [L08](../../docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Nega funksiya roʻyxatlari harness primitivlari hisoblanadi? | Agent eʼtiborsiz qoldirolmaydigan, mashina oʻqiyoladigan doira chegaralari |
-| [L09](../../docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Nega agentlar juda erta muvaffaqiyat haqida xabar beradi? | Tekshiruv boʻshliqlari: ishonch = toʻgʻrilik emas |
-| [L10](../../docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Nega uchdan-uchgacha testlash natijalarni oʻzgartiradi? | Faqat toʻliq pipeline ishga tushirish haqiqiy tekshiruv hisoblanadi |
-| [L11](../../docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Nega kuzatuvchanlik harness ichida boʻlishi kerak? | Agent nima qilganini koʻrolmasangiz, u buzgan narsani tuzata olmaysiz |
-| [L12](../../docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Nega har bir sessiya toiza holat qoldirishi kerak? | Keyingi sessiyaning muvaffaqiyati shu sessiyaning tozalanishiga bogʻliq |
-
-### Loyihalar — maʼruza usullarini bir xil Electron ilovasiga qoʻllaydigan 6 ta amaliy loyiha
+| [L01](../../docs/uz/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Kuchli modellar nega haqiqiy vazifalarda muvaffaqiyatsiz boʻladi? | Benchmarkʼlar va haqiqiy muhandislik oʻrtasidagi farq |
+| [L02](../../docs/uz/lectures/lecture-02-what-a-harness-actually-is/index.md) | "Harness" nima degani? | Besh quyi tizim: Koʻrsatmalar, Holat, Tekshiruv, Doira, Hayot sikli |
+| [L03](../../docs/uz/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Nega repozitoriy yagona haqiqat manbai boʻlishi kerak? | Agar agent koʻrolmasa, u mavjud emas |
+| [L04](../../docs/uz/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Nega bitta ulkan koʻrsatma fayli muvaffaqiyatsiz boʻladi? | Progressiv ochilish: xarita berish, ensiklopediya emas |
+| [L05](../../docs/uz/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Nega uzoq davom etuvchi vazifalar uzluksizlikni yoʻqotadi? | Taraqqiyotni diskda saqlash; toʻxtagan joydan davom ettirish |
+| [L06](../../docs/uz/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Nega ishga tushirish alohida bosqichga muhtoj? | Agent ishni boshlashdan oldin muhit ishlashini tekshirish |
+| [L07](../../docs/uz/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Nega agentlar haddan oshadi va yarim-yorti tugatadi? | Bir vaqtda bitta funksiya; "Tugadi" ning aniq taʼrifi |
+| [L08](../../docs/uz/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Nega funksiya roʻyxatlari harness primitivlari hisoblanadi? | Agent eʼtiborsiz qoldirolmaydigan, mashina oʻqiyoladigan doira chegaralari |
+| [L09](../../docs/uz/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Nega agentlar juda erta muvaffaqiyat haqida xabar beradi? | Tekshiruv boʻshliqlari: ishonch = toʻgʻrilik emas |
+| [L10](../../docs/uz/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Nega uchdan-uchgacha testlash natijalarni oʻzgartiradi? | Faqat toʻliq pipeline ishga tushirish haqiqiy tekshiruv hisoblanadi |
+| [L11](../../docs/uz/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Nega kuzatuvchanlik harness ichida boʻlishi kerak? | Agent nima qilganini koʻrolmasangiz, u buzgan narsani tuzata olmaysiz |
+| [L12](../../docs/uz/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Nega har bir sessiya toiza holat qoldirishi kerak? | Keyingi sessiyaning muvaffaqiyati shu sessiyaning tozalanishiga bogʻliq |
+| [L13](../../docs/uz/lectures/lecture-13-loop-engineering/index.md) | Nega agentingizga prompt yozishni bas qilishingiz kerak? | Qoʻlda prompt yozishdan avtonom loopʼlargacha — maqsadli loop, taymer loop, maker-checker boʻlinishi |
+| [L14](../../docs/uz/lectures/lecture-14-graph-engineering/index.md) | Nega yakka loop grafikka aylanadi? | Yakka loopʼdan grafik muhandisligigacha — tugunlar, chekkalar, umumiy holat, marshrutlash va qachon haqiqatan grafik chizishga arzir |
+
+### Loyihalar — maʼruza usullarini bir xil Electron ilovasiga qoʻllaydigan 8 ta amaliy loyiha
| Loyiha | Nima qilasiz | Harness mexanizmi |
|---------|--------------|-------------------|
-| [P01](../../docs/en/projects/project-01-baseline-vs-minimal-harness/index.md) | Bir xil vazifani ikki marta bajarish: faqat prompt vs. qoidalarga asoslangan | Minimal harness: AGENTS.md + init.sh + feature_list.json |
-| [P02](../../docs/en/projects/project-02-agent-readable-workspace/index.md) | Repoʼni agent oʻqiy oladigan qayta tuzish | Agent oʻqiy oladigan ish muhiti + doimiy holat fayllari |
-| [P03](../../docs/en/projects/project-03-multi-session-continuity/index.md) | Agentni toʻxtagan joyidan davom ettirish | Taraqqiyot jurnali + sessiya uzatish + koʻp sessiyali uzluksizlik |
-| [P04](../../docs/en/projects/project-04-incremental-indexing/index.md) | Agentning koʻp yoki oz ishlashining oldini olish | Runtime fikr-mulohaza + doira nazorati + inkremental indekslash |
-| [P05](../../docs/en/projects/project-05-grounded-qa-verification/index.md) | Agentni oʻz ishini tekshirishga majburlash | Oʻz-oʻzini tekshirish + asoslangan S&S + dalillarga asoslangan tugatish |
-| [P06](../../docs/en/projects/project-06-runtime-observability-and-debugging/index.md) | Toʻliq harnessʼni noldan qurish (yakuniy loyiha) | Toʻliq harness: barcha mexanizmlar + kuzatuvchanlik + ablyatsiya tadqiqoti |
+| [P01](../../docs/uz/projects/project-01-baseline-vs-minimal-harness/index.md) | Bir xil vazifani ikki marta bajarish: faqat prompt vs. qoidalarga asoslangan | Minimal harness: AGENTS.md + init.sh + feature_list.json |
+| [P02](../../docs/uz/projects/project-02-agent-readable-workspace/index.md) | Repoʼni agent oʻqiy oladigan qayta tuzish | Agent oʻqiy oladigan ish muhiti + doimiy holat fayllari |
+| [P03](../../docs/uz/projects/project-03-multi-session-continuity/index.md) | Agentni toʻxtagan joyidan davom ettirish | Taraqqiyot jurnali + sessiya uzatish + koʻp sessiyali uzluksizlik |
+| [P04](../../docs/uz/projects/project-04-incremental-indexing/index.md) | Agentning koʻp yoki oz ishlashining oldini olish | Runtime fikr-mulohaza + doira nazorati + inkremental indekslash |
+| [P05](../../docs/uz/projects/project-05-grounded-qa-verification/index.md) | Agentni oʻz ishini tekshirishga majburlash | Oʻz-oʻzini tekshirish + asoslangan S&S + dalillarga asoslangan tugatish |
+| [P06](../../docs/uz/projects/project-06-runtime-observability-and-debugging/index.md) | Toʻliq harnessʼni noldan qurish (yakuniy loyiha) | Toʻliq harness: barcha mexanizmlar + kuzatuvchanlik + ablyatsiya tadqiqoti |
+| [P07](../../docs/uz/projects/project-07-loop-engineering-first-loop/index.md) | Birinchi avtomatlashtirilgan loopʼingizni qurish | Maqsadli loop, taymer loop, maker-checker boʻlinishi, loop holat boshqaruvi |
+| [P08](../../docs/uz/projects/project-08-graph-engineering-first-graph/index.md) | Ish oqimingizni grafik qilib chizing | Eksplisit tugun/chekka/holat/marshrutlash, parallel fan-out/fan-in, qaytish chekkalari, inson ishtiroki tasdiqlash |
```text
LOYIHA RIVOJLANISHI
@@ -362,6 +402,12 @@ Agar parallel oʻqisangiz, har bir bosqich taxminan bir hafta davom etadi. Agar
|
v
P06 Toʻliq harness (yakuniy loyiha) Siz toʻliq tizimni qurasiz
+ |
+ v
+ P07 Birinchi avtomatlashtirilgan loopʼingiz Siz loopʼdan tashqariga chiqasiz
+ |
+ v
+ P08 Ish oqimingizni grafik qilib chizing Siz tizimni grafik qilib chizasiz
Har bir loyihaning yechimi keyingi loyihaning boshlangʻichiga aylanadi.
Ilova rivojlanadi. Harness koʻnikmalaringiz unga qarab oʻsadi.
@@ -515,7 +561,7 @@ Birlamchi:
- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)
- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)
-Toʻliq qatlamli manbalar roʻyxatini [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md) da topishingiz mumkin.
+Toʻliq qatlamli manbalar roʻyxatini [`docs/uz/resources/reference/`](../../docs/uz/resources/reference/index.md) da topishingiz mumkin.
---
@@ -524,13 +570,13 @@ Toʻliq qatlamli manbalar roʻyxatini [`docs/en/resources/reference/`](../../doc
```text
learn-harness-engineering/
├── docs/ # VitePress hujjatlar sayti
-│ ├── lectures/ # 12 ta maʼruza (index.md + code/ misollar)
+│ ├── lectures/ # 14 ta maʼruza (index.md + code/ misollar)
│ │ ├── lecture-01-*/
│ │ ├── lecture-02-*/
-│ │ └── ... (jami 12 ta)
-│ ├── projects/ # 6 ta loyiha tavsifi
+│ │ └── ... (jami 14 ta)
+│ ├── projects/ # 8 ta loyiha tavsifi
│ │ ├── project-01-*/
-│ │ └── ... (jami 6 ta)
+│ │ └── ... (jami 8 ta)
│ └── resources/ # Koʻp tilli andozalar va maʼlumotnomalar
│ ├── en/ # Ingliz andozalari, tekshiruv roʻyxatlari, qoʻllanmalar
│ ├── zh/ # Xitoy andozalari, tekshiruv roʻyxatlari, qoʻllanmalar
@@ -550,7 +596,7 @@ learn-harness-engineering/
## Kurs qanday tuzilgan
- Har bir maʼruza bitta savolga qaratilgan
-- Kurs 6 ta loyihani oʻz ichiga oladi
+- Kurs 8 ta loyihani oʻz ichiga oladi
- Har bir loyiha agentdan haqiqiy ish bajarishni talab qiladi
- Har bir loyiha kuchsiz vs. kuchli harness natijalarini solishtiradi
- Muhim boʻlgan narsa — oʻlchangan farq, nechta hujjat yozilgani emas
diff --git a/docs-readme/vi-VN/README.md b/docs-readme/vi-VN/README.md
index 64c4405..83a9e6c 100644
--- a/docs-readme/vi-VN/README.md
+++ b/docs-readme/vi-VN/README.md
@@ -22,6 +22,21 @@
Learn Harness Engineering là một khóa học dành riêng cho kỹ thuật liên quan đến các agent viết code AI. Chúng tôi đã nghiên cứu sâu và tổng hợp các lý thuyết và thực tiễn Harness Engineering tiên tiến nhất trong ngành. Các tài liệu tham khảo cốt lõi của chúng tôi bao gồm:
+> **🆕 Cập nhật tháng 8/2026: Graph Engineering (Kỹ thuật Đồ thị)** — thêm mới 1 bài giảng + 1 dự án:
+>
+> - **Bài giảng 14** [Từ Vòng lặp Đơn lẻ đến Kỹ thuật Đồ thị](../../docs/vi/lectures/lecture-14-graph-engineering/index.md): vì sao vòng lặp đơn lẻ chắc chắn phát triển thành đồ thị — bốn lớp xếp chồng (prompt → context → loop → graph) và vị trí của harness trong đó, bốn bộ phận của đồ thị (nút, cạnh, trạng thái dùng chung, định tuyến), vì sao checkpoint trong loop không cứu được ba kiểu thất bại mang tính cấu trúc ở quy mô lớn (Goodhart, mù hướng lên, xung đột), sáu bước xây dựng đồ thị đầu tiên của bạn không phụ thuộc framework, sự khác biệt giữa Graph và Workflow, mỏ neo, hiện trạng dự án mã nguồn mở trước-phát hành vs sau-phát hành, thuế điều phối, và khi nào thực sự đáng để vẽ đồ thị.
+> - **Dự án 08** [Vẽ Quy trình Làm việc của bạn thành một Đồ thị](../../docs/vi/projects/project-08-graph-engineering-first-graph/index.md): ba thí nghiệm tiến dần — vẽ maker-checker loop thành đồ thị tường minh, thêm nút fan-out/fan-in song song, thêm cạnh quay lại có điều kiện và nút phê duyệt thủ công.
+>
+> **Ý tưởng cốt lõi:** Loop là một đồ thị chỉ có một nút. Khi nhiệm vụ cần phân công, song song, trạng thái dùng chung, xác minh và phục hồi — nó không còn là loop, mà là đồ thị.
+>
+> **🆕 Cập nhật tháng 7/2026: Loop Engineering (Kỹ thuật Vòng lặp)** — thêm mới 1 bài giảng + 1 dự án + mẫu code:
+>
+> - **Bài giảng 13** [Từ Nhắc lệnh Thủ công đến Vòng lặp Tự chủ](../../docs/vi/lectures/lecture-13-loop-engineering/index.md): từ `/goal` đến sáu nguyên thủy của loop engineering (automations, worktrees, skills, connectors, sub-agents, external state), phân tách generator/evaluator, bốn chi phí thầm lặng, và xây dựng từng bước vòng lặp đầu tiên của bạn.
+> - **Dự án 07** [Xây dựng Vòng lặp Tự động Đầu tiên](../../docs/vi/projects/project-07-loop-engineering-first-loop/index.md): ba thí nghiệm tiến dần — vòng lặp theo mục tiêu, vòng lặp theo lịch, vòng lặp maker-checker. So sánh thủ công vs. tự động hóa, đo lường việc giảm can thiệp, học cách bước ra khỏi vòng lặp.
+> - **Mẫu code**: `goal-template.md`, `loop-state-template.md`, `maker-prompt.md`, `checker-prompt.md` — các mẫu xây dựng vòng lặp dùng ngay được.
+>
+> **Ý tưởng cốt lõi:** Harness engineering tạo ra chiếc xe. Loop engineering thiết kế con đường nó chạy — và bạn phải thiết kế con đường đó từ bên ngoài chiếc xe.
+
- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
@@ -195,15 +210,15 @@ Những câu hỏi mà khóa học này thực sự quan tâm:
Giáo trình được chia thành ba phần:
-1. **Bài giảng**: 12 đơn vị khái niệm giải thích lý thuyết đằng sau harness engineering.
-2. **Dự án**: 6 dự án thực hành nơi bạn xây dựng một không gian làm việc agentic từ đầu.
+1. **Bài giảng**: 14 đơn vị khái niệm giải thích lý thuyết đằng sau harness engineering.
+2. **Dự án**: 8 dự án thực hành nơi bạn xây dựng một không gian làm việc agentic từ đầu.
3. **Thư viện tài nguyên**: Các mẫu sẵn sàng sử dụng (`AGENTS.md`, `feature_list.json`, `init.sh`, v.v.) để sử dụng trong kho mã của riêng bạn ngay hôm nay.
---
## Bắt đầu nhanh: Cải thiện Agent của bạn ngay hôm nay
-Bạn không cần phải đọc cả 12 bài giảng trước khi bắt đầu nhận được giá trị. Nếu bạn đang sử dụng một agent viết code trên một dự án thực tế, đây là cách cải thiện nó ngay bây giờ.
+Bạn không cần phải đọc cả 14 bài giảng trước khi bắt đầu nhận được giá trị. Nếu bạn đang sử dụng một agent viết code trên một dự án thực tế, đây là cách cải thiện nó ngay bây giờ.
Ý tưởng rất đơn giản: thay vì chỉ viết prompt, hãy cho agent của bạn một bộ tệp có cấu trúc xác định phải làm gì, những gì đã làm, và cách kiểm chứng công việc. Các tệp này nằm trong kho mã của bạn, vì vậy mỗi phiên bắt đầu từ cùng một trạng thái.
@@ -304,6 +319,27 @@ Khóa học được thiết kế để hoàn thành theo thứ tự. Mỗi giai
v v
P05 Agent tự kiểm chứng P06 Xây dựng harness hoàn chỉnh
(dự án tổng kết)
+
+
+ Giai đoạn 7: TỰ ĐỘNG HÓA VÒNG LẶP
+ ==============================
+ L13 Ngừng nhắc lệnh cho agent —
+ chuyển sang thiết kế vòng lặp
+ |
+ v
+ P07 Xây dựng vòng lặp tự động đầu tiên
+ (vòng lặp theo mục tiêu, theo lịch,
+ maker-checker)
+
+ Giai đoạn 8: CẤU TRÚC HÓA HỆ THỐNG
+ ==============================
+ L14 Vẽ hệ thống thành một đồ thị —
+ nút, cạnh, trạng thái dùng chung, định tuyến
+ |
+ v
+ P08 Vẽ quy trình làm việc của bạn thành một đồ thị
+ (đồ thị tường minh, fan-out/fan-in song song,
+ cạnh quay lại, người-máy cộng tác)
```
Mỗi giai đoạn mất khoảng một tuần nếu bạn học bán thời gian. Nếu bạn muốn đi nhanh hơn, các giai đoạn 1-3 có thể hoàn thành trong một cuối tuần dài.
@@ -312,35 +348,39 @@ Mỗi giai đoạn mất khoảng một tuần nếu bạn học bán thời gia
## Giáo trình
-### Bài giảng — 12 đơn vị khái niệm, mỗi đơn vị trả lời một câu hỏi cốt lõi
+### Bài giảng — 14 đơn vị khái niệm, mỗi đơn vị trả lời một câu hỏi cốt lõi
*Đọc toàn bộ văn bản cho mỗi bài giảng trên [Trang web Tài liệu](https://walkinglabs.github.io/learn-harness-engineering/).*
| Phiên | Câu hỏi | Ý tưởng cốt lõi |
|-------|---------|------------------|
-| [L01](../../docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Tại sao các mô hình mạnh vẫn thất bại trên tác vụ thực tế? | Khoảng cách năng lực giữa benchmark và kỹ thuật thực tế |
-| [L02](../../docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md) | "Harness" thực sự có nghĩa là gì? | Năm hệ thống con: instructions, state, verification, scope, lifecycle |
-| [L03](../../docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Tại sao kho mã phải là nguồn chân lý duy nhất? | Nếu agent không thể thấy nó, nó không tồn tại |
-| [L04](../../docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Tại sao một tệp hướng dẫn khổng lồ lại thất bại? | Tiết lộ dần: cho một bản đồ, không phải một bộ bách khoa toàn thư |
-| [L05](../../docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Tại sao các tác vụ chạy dài mất tính liên tục? | Lưu trữ tiến trình vào đĩa; tiếp tục từ nơi bạn đã dừng |
-| [L06](../../docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Tại sao khởi tạo cần một giai đoạn riêng? | Xác minh môi trường khỏe mạnh trước khi agent bắt đầu làm việc |
-| [L07](../../docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Tại sao agent lại vượt quá phạm vi và không hoàn thành? | Một tính năng tại một thời điểm; định nghĩa rõ ràng về "hoàn thành" |
-| [L08](../../docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Tại sao danh sách tính năng là nguyên thủy của harness? | Ranh giới phạm vi có thể đọc bởi máy mà agent không thể bỏ qua |
-| [L09](../../docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Tại sao agent tuyên bố hoàn thành quá sớm? | Khoảng trống kiểm chứng: sự tự tin ≠ sự chính xác |
-| [L10](../../docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Tại sao kiểm thử đầu-cuối lại thay đổi kết quả? | Chỉ một lần chạy toàn bộ pipeline mới được tính là kiểm chứng thực sự |
-| [L11](../../docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Tại sao khả năng quan sát thuộc về bên trong harness? | Nếu bạn không thể thấy agent đã làm gì, bạn không thể sửa những gì nó đã làm hỏng |
-| [L12](../../docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Tại sao mỗi phiên phải để lại trạng thái sạch? | Sự thành công của phiên tiếp theo phụ thuộc vào việc dọn dẹp của phiên này |
-
-### Dự án — 6 dự án thực hành áp dụng phương pháp bài giảng vào cùng ứng dụng Electron
+| [L01](../../docs/vi/lectures/lecture-01-why-capable-agents-still-fail/index.md) | Tại sao các mô hình mạnh vẫn thất bại trên tác vụ thực tế? | Khoảng cách năng lực giữa benchmark và kỹ thuật thực tế |
+| [L02](../../docs/vi/lectures/lecture-02-what-a-harness-actually-is/index.md) | "Harness" thực sự có nghĩa là gì? | Năm hệ thống con: instructions, state, verification, scope, lifecycle |
+| [L03](../../docs/vi/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | Tại sao kho mã phải là nguồn chân lý duy nhất? | Nếu agent không thể thấy nó, nó không tồn tại |
+| [L04](../../docs/vi/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | Tại sao một tệp hướng dẫn khổng lồ lại thất bại? | Tiết lộ dần: cho một bản đồ, không phải một bộ bách khoa toàn thư |
+| [L05](../../docs/vi/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | Tại sao các tác vụ chạy dài mất tính liên tục? | Lưu trữ tiến trình vào đĩa; tiếp tục từ nơi bạn đã dừng |
+| [L06](../../docs/vi/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | Tại sao khởi tạo cần một giai đoạn riêng? | Xác minh môi trường khỏe mạnh trước khi agent bắt đầu làm việc |
+| [L07](../../docs/vi/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | Tại sao agent lại vượt quá phạm vi và không hoàn thành? | Một tính năng tại một thời điểm; định nghĩa rõ ràng về "hoàn thành" |
+| [L08](../../docs/vi/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | Tại sao danh sách tính năng là nguyên thủy của harness? | Ranh giới phạm vi có thể đọc bởi máy mà agent không thể bỏ qua |
+| [L09](../../docs/vi/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | Tại sao agent tuyên bố hoàn thành quá sớm? | Khoảng trống kiểm chứng: sự tự tin ≠ sự chính xác |
+| [L10](../../docs/vi/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | Tại sao kiểm thử đầu-cuối lại thay đổi kết quả? | Chỉ một lần chạy toàn bộ pipeline mới được tính là kiểm chứng thực sự |
+| [L11](../../docs/vi/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | Tại sao khả năng quan sát thuộc về bên trong harness? | Nếu bạn không thể thấy agent đã làm gì, bạn không thể sửa những gì nó đã làm hỏng |
+| [L12](../../docs/vi/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | Tại sao mỗi phiên phải để lại trạng thái sạch? | Sự thành công của phiên tiếp theo phụ thuộc vào việc dọn dẹp của phiên này |
+| [L13](../../docs/vi/lectures/lecture-13-loop-engineering/index.md) | Tại sao bạn cần ngừng tự nhắc lệnh cho agent của mình? | Từ điều khiển thủ công đến vòng lặp tự chủ — vòng lặp theo mục tiêu, vòng lặp theo lịch, tách maker-checker |
+| [L14](../../docs/vi/lectures/lecture-14-graph-engineering/index.md) | Tại sao một vòng lặp đơn lẻ phát triển thành đồ thị? | Từ vòng lặp đơn lẻ đến kỹ thuật đồ thị — nút, cạnh, trạng thái dùng chung, định tuyến, và khi nào thực sự đáng để vẽ đồ thị |
+
+### Dự án — 8 dự án thực hành áp dụng phương pháp bài giảng vào cùng ứng dụng Electron
| Dự án | Những gì bạn làm | Cơ chế Harness |
|-------|-------------------|----------------|
-| [P01](../../docs/en/projects/project-01-baseline-vs-minimal-harness/index.md) | Chạy cùng tác vụ hai lần: chỉ dùng prompt vs. ưu tiên quy tắc | Harness tối thiểu: AGENTS.md + init.sh + feature_list.json |
-| [P02](../../docs/en/projects/project-02-agent-readable-workspace/index.md) | Tái cấu trúc kho mã để agent có thể đọc được | Không gian làm việc agent có thể đọc + các tệp trạng thái liên tục |
-| [P03](../../docs/en/projects/project-03-multi-session-continuity/index.md) | Khiến agent tiếp tục từ nơi nó đã dừng | Nhật ký tiến trình + bàn giao phiên + tính liên tục đa phiên |
-| [P04](../../docs/en/projects/project-04-incremental-indexing/index.md) | Ngăn agent làm quá nhiều hoặc quá ít | Phản hồi thời gian chạy + kiểm soát phạm vi + lập chỉ mục gia tăng |
-| [P05](../../docs/en/projects/project-05-grounded-qa-verification/index.md) | Khiến agent tự kiểm chứng công việc của mình | Tự kiểm chứng + Q&A có căn cứ + hoàn thành dựa trên bằng chứng |
-| [P06](../../docs/en/projects/project-06-runtime-observability-and-debugging/index.md) | Xây dựng một harness hoàn chỉnh từ đầu (tổng kết) | Harness đầy đủ: tất cả cơ chế + khả năng quan sát + nghiên cứu ablation |
+| [P01](../../docs/vi/projects/project-01-baseline-vs-minimal-harness/index.md) | Chạy cùng tác vụ hai lần: chỉ dùng prompt vs. ưu tiên quy tắc | Harness tối thiểu: AGENTS.md + init.sh + feature_list.json |
+| [P02](../../docs/vi/projects/project-02-agent-readable-workspace/index.md) | Tái cấu trúc kho mã để agent có thể đọc được | Không gian làm việc agent có thể đọc + các tệp trạng thái liên tục |
+| [P03](../../docs/vi/projects/project-03-multi-session-continuity/index.md) | Khiến agent tiếp tục từ nơi nó đã dừng | Nhật ký tiến trình + bàn giao phiên + tính liên tục đa phiên |
+| [P04](../../docs/vi/projects/project-04-incremental-indexing/index.md) | Ngăn agent làm quá nhiều hoặc quá ít | Phản hồi thời gian chạy + kiểm soát phạm vi + lập chỉ mục gia tăng |
+| [P05](../../docs/vi/projects/project-05-grounded-qa-verification/index.md) | Khiến agent tự kiểm chứng công việc của mình | Tự kiểm chứng + Q&A có căn cứ + hoàn thành dựa trên bằng chứng |
+| [P06](../../docs/vi/projects/project-06-runtime-observability-and-debugging/index.md) | Xây dựng một harness hoàn chỉnh từ đầu (tổng kết) | Harness đầy đủ: tất cả cơ chế + khả năng quan sát + nghiên cứu ablation |
+| [P07](../../docs/vi/projects/project-07-loop-engineering-first-loop/index.md) | Xây dựng vòng lặp tự động đầu tiên của bạn | Vòng lặp theo mục tiêu, vòng lặp theo lịch, tách maker-checker, quản lý trạng thái vòng lặp |
+| [P08](../../docs/vi/projects/project-08-graph-engineering-first-graph/index.md) | Vẽ quy trình làm việc của bạn thành một đồ thị | Nút/cạnh/trạng thái/định tuyến tường minh, fan-out/fan-in song song, cạnh quay lại, phê duyệt người-máy |
```text
SỰ PHÁT TRIỂN DỰ ÁN
@@ -365,6 +405,12 @@ Mỗi giai đoạn mất khoảng một tuần nếu bạn học bán thời gia
|
v
P06 Harness hoàn chỉnh (tổng kết) Bạn xây dựng hệ thống đầy đủ
+ |
+ v
+ P07 Vòng lặp tự động đầu tiên Bạn bước ra khỏi vòng lặp
+ |
+ v
+ P08 Vẽ quy trình làm việc thành đồ thị Bạn vẽ hệ thống thành hình
Solution của mỗi dự án trở thành starter của dự án tiếp theo.
Ứng dụng phát triển. Kỹ năng harness của bạn lớn lên cùng nó.
@@ -518,7 +564,7 @@ Chính:
- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)
- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)
-Xem danh sách tài liệu tham khảo phân tầng đầy đủ tại [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md).
+Xem danh sách tài liệu tham khảo phân tầng đầy đủ tại [`docs/vi/resources/reference/`](../../docs/vi/resources/reference/index.md).
---
@@ -527,13 +573,13 @@ Xem danh sách tài liệu tham khảo phân tầng đầy đủ tại [`docs/en
```text
learn-harness-engineering/
├── docs/ # VitePress documentation site
-│ ├── lectures/ # 12 lectures (index.md + code/ examples)
+│ ├── lectures/ # 14 bài giảng (index.md + code/ ví dụ)
│ │ ├── lecture-01-*/
│ │ ├── lecture-02-*/
-│ │ └── ... (12 total)
-│ ├── projects/ # 6 project descriptions
+│ │ └── ... (tổng 14)
+│ ├── projects/ # 8 mô tả dự án
│ │ ├── project-01-*/
-│ │ └── ... (6 total)
+│ │ └── ... (tổng 8)
│ └── resources/ # Multilingual templates & references
│ ├── en/ # English templates, checklists, guides
│ ├── zh/ # Chinese templates, checklists, guides
@@ -553,7 +599,7 @@ learn-harness-engineering/
## Khóa học được tổ chức như thế nào
- Mỗi bài giảng tập trung vào một câu hỏi
-- Khóa học bao gồm 6 dự án
+- Khóa học bao gồm 8 dự án
- Mọi dự án đều yêu cầu agent thực hiện công việc thực tế
- Mọi dự án đều so sánh kết quả harness yếu vs. mạnh
- Điều quan trọng là sự khác biệt được đo lường, không phải số lượng tài liệu đã viết
diff --git a/docs-readme/zh-CN/README.md b/docs-readme/zh-CN/README.md
index 651458f..b849217 100644
--- a/docs-readme/zh-CN/README.md
+++ b/docs-readme/zh-CN/README.md
@@ -22,6 +22,21 @@
Learn Harness Engineering 是一门专注于 AI 编程代理工程化的课程。我们深入研究和综合了业界最先进的 Harness Engineering 理论与实践。我们的核心参考资料包括:
+> **🆕 2026 年 8 月更新:图工程(Graph Engineering)**——新增 1 讲 + 1 个项目:
+>
+> - **第十四讲** [从单循环到图工程](../../docs/zh/lectures/lecture-14-graph-engineering/index.md):为什么单循环必然长成图——四层叠加(prompt → context → loop → graph)及 harness 在其中的位置、图的四个零件(节点、边、共享状态、路由)、为什么 loop 内的检查点救不了规模上的三种结构性失败(Goodhart、向上失明、冲突)、框架无关的六步构建你的第一张图、Graph 与 Workflow 的区别、锚、发布前 vs 发布后的开源项目现状、编排税,以及什么时候真的值得画图。
+> - **项目 08** [把你的工作流画成一张图](../../docs/zh/projects/project-08-graph-engineering-first-graph/index.md):三个递进实验——把 maker-checker loop 画成显式图、加并行 fan-out/fan-in 节点、加条件回退边和人工审批节点。
+>
+> **核心观点:** Loop 是只有一个节点的图。当任务需要分工、并行、共享状态、验证和恢复时——它就不再是 loop,而是图了。
+>
+> **🆕 2026 年 7 月更新:循环工程(Loop Engineering)**——新增 1 讲 + 1 个项目 + 代码模板:
+>
+> - **第十三讲** [为什么你需要停止亲自提示你的代理](../../docs/zh/lectures/lecture-13-loop-engineering/index.md):从 `/goal` 到循环工程的六个原语(automations、worktrees、skills、connectors、sub-agents、external state)、生成器/评估器分离、四种沉默成本,以及逐步构建你的第一个循环。
+> - **项目 07** [构建你的第一个自动循环](../../docs/zh/projects/project-07-loop-engineering-first-loop/index.md):三个递进实验——目标循环、定时循环、制造者-检查者循环。对比手动 vs. 自动化、衡量干预减少、学会跳出循环。
+> - **代码模板**:`goal-template.md`、`loop-state-template.md`、`maker-prompt.md`、`checker-prompt.md`——即插即用的循环构建模板。
+>
+> **核心观点:** Harness 工程造车。循环工程设计它行驶的道路——而你要从车外设计这条路。
+
- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
@@ -194,15 +209,15 @@ Harness Engineering 是围绕模型构建一个完整的工作环境,使其产
课程分为三个部分:
-1. **讲座**:12 个概念单元,讲解 Harness Engineering 背后的理论。
-2. **项目**:6 个动手项目,你将从零构建一个代理工作空间。
+1. **讲座**:14 个概念单元,讲解 Harness Engineering 背后的理论。
+2. **项目**:8 个动手项目,你将从零构建一个代理工作空间。
3. **资源库**:可直接使用的模板(`AGENTS.md`、`feature_list.json`、`init.sh` 等),今天就能用在你自己的仓库中。
---
## 快速开始:今天就改善你的代理
-你不需要先读完所有 12 个讲座才能开始获得价值。如果你已经在真实项目中使用编程代理,以下是如何立刻改善它。
+你不需要先读完所有 14 个讲座才能开始获得价值。如果你已经在真实项目中使用编程代理,以下是如何立刻改善它。
思路很简单:与其只写提示词,不如给你的代理一组结构化文件,定义做什么、已做了什么、以及如何验证工作。这些文件存在于你的仓库中,所以每次会话都从相同的状态开始。
@@ -222,7 +237,7 @@ Harness Engineering 是围绕模型构建一个完整的工作环境,使其产
## 毕业项目:一个真实的应用
-全部六个课程项目围绕同一个产品展开:**一个基于 Electron 的个人知识库桌面应用**。
+全部八个课程项目围绕同一个产品展开:**一个基于 Electron 的个人知识库桌面应用**。
```text
┌─────────────────────────────────────────────────────┐
@@ -301,6 +316,25 @@ Harness Engineering 是围绕模型构建一个完整的工作环境,使其产
v v
P05 代理验证自己的工作 P06 构建完整的 Harness
(毕业项目)
+
+ 阶段 7:自动化循环
+ ==========================
+ L13 停止提示你的代理——
+ 改为设计循环
+ |
+ v
+ P07 构建你的第一个自动循环
+ (目标循环、定时循环、制造者-检查者)
+
+ 阶段 8:结构化系统
+ =============================
+ L14 把系统画成一张图——
+ 节点、边、共享状态、路由
+ |
+ v
+ P08 把你的工作流画成一张图
+ (显式图、并行 fan-out/fan-in、
+ 回退边、人机协同)
```
如果你是业余时间学习,每个阶段大约需要一周。如果你想加快速度,阶段 1-3 可以在一个长周末完成。
@@ -309,35 +343,39 @@ Harness Engineering 是围绕模型构建一个完整的工作环境,使其产
## 课程大纲
-### 讲座——12 个概念单元,每个回答一个核心问题
+### 讲座——14 个概念单元,每个回答一个核心问题
*在[文档网站](https://walkinglabs.github.io/learn-harness-engineering/)上阅读每讲完整文本。*
| 讲次 | 问题 | 核心观点 |
|------|------|----------|
-| [L01](../../docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md) | 为什么强模型在真实任务上仍然会失败? | 基准测试与真实工程之间的能力差距 |
-| [L02](../../docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md) | "Harness" 到底是什么意思? | 五个子系统:指令、状态、验证、范围、生命周期 |
-| [L03](../../docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | 为什么仓库必须是唯一的真实来源? | 如果代理看不到它,它就不存在 |
-| [L04](../../docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | 为什么一个巨大的指令文件会失败? | 渐进式披露:给一张地图,不是一本百科全书 |
-| [L05](../../docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | 为什么长时间运行的任务会失去连续性? | 将进度持久化到磁盘;从上次离开处继续 |
-| [L06](../../docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | 为什么初始化需要单独的阶段? | 在代理开始工作前验证环境是否健康 |
-| [L07](../../docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | 为什么代理会越界和欠完成? | 一次一个功能;明确的完成定义 |
-| [L08](../../docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | 为什么功能列表是 Harness 基本单元? | 代理无法忽视的机器可读范围边界 |
-| [L09](../../docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | 为什么代理过早宣布完成? | 验证缺口:信心 ≠ 正确 |
-| [L10](../../docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | 为什么端到端测试能改变结果? | 只有完整的流水线运行才算真正的验证 |
-| [L11](../../docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | 为什么可观测性应该属于 Harness? | 如果你看不到代理做了什么,你就无法修复它破坏的东西 |
-| [L12](../../docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | 为什么每次会话都必须留下干净的状态? | 下一次会话的成功取决于这一次会话的清理 |
-
-### 项目——6 个动手项目,将讲座方法应用到同一个 Electron 应用上
+| [L01](../../docs/zh/lectures/lecture-01-why-capable-agents-still-fail/index.md) | 为什么强模型在真实任务上仍然会失败? | 基准测试与真实工程之间的能力差距 |
+| [L02](../../docs/zh/lectures/lecture-02-what-a-harness-actually-is/index.md) | "Harness" 到底是什么意思? | 五个子系统:指令、状态、验证、范围、生命周期 |
+| [L03](../../docs/zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | 为什么仓库必须是唯一的真实来源? | 如果代理看不到它,它就不存在 |
+| [L04](../../docs/zh/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | 为什么一个巨大的指令文件会失败? | 渐进式披露:给一张地图,不是一本百科全书 |
+| [L05](../../docs/zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | 为什么长时间运行的任务会失去连续性? | 将进度持久化到磁盘;从上次离开处继续 |
+| [L06](../../docs/zh/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | 为什么初始化需要单独的阶段? | 在代理开始工作前验证环境是否健康 |
+| [L07](../../docs/zh/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | 为什么代理会越界和欠完成? | 一次一个功能;明确的完成定义 |
+| [L08](../../docs/zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | 为什么功能列表是 Harness 基本单元? | 代理无法忽视的机器可读范围边界 |
+| [L09](../../docs/zh/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | 为什么代理过早宣布完成? | 验证缺口:信心 ≠ 正确 |
+| [L10](../../docs/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | 为什么端到端测试能改变结果? | 只有完整的流水线运行才算真正的验证 |
+| [L11](../../docs/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | 为什么可观测性应该属于 Harness? | 如果你看不到代理做了什么,你就无法修复它破坏的东西 |
+| [L12](../../docs/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | 为什么每次会话都必须留下干净的状态? | 下一次会话的成功取决于这一次会话的清理 |
+| [L13](../../docs/zh/lectures/lecture-13-loop-engineering/index.md) | 为什么你需要停止亲自提示你的代理? | 从手动驱动到自动循环——目标循环、定时循环、制造者-检查者分离 |
+| [L14](../../docs/zh/lectures/lecture-14-graph-engineering/index.md) | 为什么单循环会演变成图? | 从单循环到图工程——节点、边、共享状态、路由,以及何时真正值得画图 |
+
+### 项目——8 个动手项目,将讲座方法应用到同一个 Electron 应用上
| 项目 | 你要做什么 | Harness 机制 |
|------|-----------|--------------|
-| [P01](../../docs/en/projects/project-01-baseline-vs-minimal-harness/index.md) | 同一个任务运行两次:仅提示词 vs. 规则优先 | 最小 Harness:AGENTS.md + init.sh + feature_list.json |
-| [P02](../../docs/en/projects/project-02-agent-readable-workspace/index.md) | 重构仓库使代理可读 | 代理可读工作空间 + 持久化状态文件 |
-| [P03](../../docs/en/projects/project-03-multi-session-continuity/index.md) | 让代理从上次离开处继续 | 进度日志 + 会话交接 + 多会话连续性 |
-| [P04](../../docs/en/projects/project-04-incremental-indexing/index.md) | 阻止代理做得太多或太少 | 运行时反馈 + 范围控制 + 增量索引 |
-| [P05](../../docs/en/projects/project-05-grounded-qa-verification/index.md) | 让代理验证自己的工作 | 自验证 + 有据问答 + 基于证据的完成 |
-| [P06](../../docs/en/projects/project-06-runtime-observability-and-debugging/index.md) | 从零构建完整的 Harness(毕业项目) | 完整 Harness:所有机制 + 可观测性 + 消融实验 |
+| [P01](../../docs/zh/projects/project-01-baseline-vs-minimal-harness/index.md) | 同一个任务运行两次:仅提示词 vs. 规则优先 | 最小 Harness:AGENTS.md + init.sh + feature_list.json |
+| [P02](../../docs/zh/projects/project-02-agent-readable-workspace/index.md) | 重构仓库使代理可读 | 代理可读工作空间 + 持久化状态文件 |
+| [P03](../../docs/zh/projects/project-03-multi-session-continuity/index.md) | 让代理从上次离开处继续 | 进度日志 + 会话交接 + 多会话连续性 |
+| [P04](../../docs/zh/projects/project-04-incremental-indexing/index.md) | 阻止代理做得太多或太少 | 运行时反馈 + 范围控制 + 增量索引 |
+| [P05](../../docs/zh/projects/project-05-grounded-qa-verification/index.md) | 让代理验证自己的工作 | 自验证 + 有据问答 + 基于证据的完成 |
+| [P06](../../docs/zh/projects/project-06-runtime-observability-and-debugging/index.md) | 从零构建完整的 Harness(毕业项目) | 完整 Harness:所有机制 + 可观测性 + 消融实验 |
+| [P07](../../docs/zh/projects/project-07-loop-engineering-first-loop/index.md) | 构建你的第一个自动循环 | 目标循环、定时循环、制造者-检查者分离、循环状态管理 |
+| [P08](../../docs/zh/projects/project-08-graph-engineering-first-graph/index.md) | 把你的工作流画成一张图 | 显式的节点/边/状态/路由、并行 fan-out/fan-in、回退边、人机协同审批 |
```text
项目演进
@@ -359,6 +397,12 @@ Harness Engineering 是围绕模型构建一个完整的工作环境,使其产
|
v
P06 完整 Harness(毕业项目) 你构建完整系统
+ |
+ v
+ P07 你的第一个自动循环 你跳出循环
+ |
+ v
+ P08 把你的工作流画成一张图 你把系统画成图
每个项目的 solution 成为下一个项目的 starter。
应用在演进。你的 Harness 技能随之增长。
@@ -512,7 +556,7 @@ npm run docs:preview # 预览构建后的站点
- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)
- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)
-完整分层参考列表请见 [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md)。
+完整分层参考列表请见 [`docs/zh/resources/reference/`](../../docs/zh/resources/reference/index.md)。
---
@@ -521,13 +565,13 @@ npm run docs:preview # 预览构建后的站点
```text
learn-harness-engineering/
├── docs/ # VitePress 文档站点
-│ ├── lectures/ # 12 个讲座(index.md + code/ 示例)
+│ ├── lectures/ # 14 个讲座(index.md + code/ 示例)
│ │ ├── lecture-01-*/
│ │ ├── lecture-02-*/
-│ │ └── ... (共 12 个)
-│ ├── projects/ # 6 个项目描述
+│ │ └── ... (共 14 个)
+│ ├── projects/ # 8 个项目描述
│ │ ├── project-01-*/
-│ │ └── ... (共 6 个)
+│ │ └── ... (共 8 个)
│ └── resources/ # 多语言模板和参考
│ ├── en/ # 英文模板、检查清单、指南
│ ├── zh/ # 中文模板、检查清单、指南
@@ -547,7 +591,7 @@ learn-harness-engineering/
## 课程组织方式
- 每个讲座聚焦一个问题
-- 课程包含 6 个项目
+- 课程包含 8 个项目
- 每个项目都要求代理做真实的工作
- 每个项目都比较弱 Harness 和强 Harness 的结果
- 重要的是可测量的差异,不是写了多少文档
diff --git a/docs-readme/zh-TW/README.md b/docs-readme/zh-TW/README.md
index c12cc7f..260457a 100644
--- a/docs-readme/zh-TW/README.md
+++ b/docs-readme/zh-TW/README.md
@@ -22,6 +22,21 @@
Learn Harness Engineering 是一門專注於 AI 程式設計代理工程化的課程。我們深入研究並整合了業界最先進的 Harness Engineering 理論與實踐。核心參考資料包括:
+> **🆕 2026 年 8 月更新:圖工程(Graph Engineering)**——新增 1 講 + 1 個專案:
+>
+> - **第十四講** [從單循環到圖工程](../../docs/zh-TW/lectures/lecture-14-graph-engineering/index.md):為什麼單循環必然長成圖——四層疊加(prompt → context → loop → graph)及 harness 在其中的位置、圖的四個零件(節點、邊、共享狀態、路由)、為什麼 loop 內的檢查點救不了規模上的三種結構性失敗(Goodhart、向上失明、衝突)、框架無關的六步構建你的第一張圖、Graph 與 Workflow 的區別、錨、發布前 vs 發布後的開源專案現況、編排稅,以及什麼時候真的值得畫圖。
+> - **專案 08** [把你的工作流畫成一張圖](../../docs/zh-TW/projects/project-08-graph-engineering-first-graph/index.md):三個遞進實驗——把 maker-checker loop 畫成顯式圖、加平行 fan-out/fan-in 節點、加條件回退邊和人工審批節點。
+>
+> **核心觀點:** Loop 是只有一個節點的圖。當任務需要分工、平行、共享狀態、驗證和恢復時——它就不再是 loop,而是圖了。
+>
+> **🆕 2026 年 7 月更新:循環工程(Loop Engineering)**——新增 1 講 + 1 個專案 + 程式碼範本:
+>
+> - **第十三講** [為什麼你需要停止親自提示你的代理](../../docs/zh-TW/lectures/lecture-13-loop-engineering/index.md):從 `/goal` 到循環工程的六個原語(automations、worktrees、skills、connectors、sub-agents、external state)、生成器/評估器分離、四種沉默成本,以及逐步構建你的第一個循環。
+> - **專案 07** [構建你的第一個自動循環](../../docs/zh-TW/projects/project-07-loop-engineering-first-loop/index.md):三個遞進實驗——目標循環、定時循環、製造者-檢查者循環。對比手動 vs. 自動化、衡量干預減少、學會跳出循環。
+> - **程式碼範本**:`goal-template.md`、`loop-state-template.md`、`maker-prompt.md`、`checker-prompt.md`——即插即用的循環構建範本。
+>
+> **核心觀點:** Harness 工程造車。循環工程設計它行駛的道路——而你要從車外設計這條路。
+
- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
@@ -194,15 +209,15 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,
課程分為三個部分:
-1. **講座**:12 個概念單元,解釋 harness engineering 背後的理論。
-2. **專案**:6 個動手專案,讓你從零建構一個代理工作空間。
+1. **講座**:14 個概念單元,解釋 harness engineering 背後的理論。
+2. **專案**:8 個動手專案,讓你從零建構一個代理工作空間。
3. **資源庫**:可直接複製使用的模板(`AGENTS.md`、`feature_list.json`、`init.sh` 等),今天就能在你的儲存庫中使用。
---
## 快速入門:今天就改善你的代理
-你不需要讀完所有 12 堂講座才能開始受益。如果你已經在真實專案中使用程式設計代理,以下是如何立刻改善它的方法。
+你不需要先讀完所有 14 堂講座才能開始獲得價值。如果你已經在真實專案中使用程式設計代理,以下是如何立刻改善它的方法。
概念很簡單,與其只寫提示,不如給你的代理一組結構化的檔案,定義該做什麼、已經做了什麼、以及如何驗證工作。這些檔案存在你的儲存庫中,所以每個工作階段都從相同的狀態開始。
@@ -222,7 +237,7 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,
## 畢業專案:一個真實的應用程式
-所有六個課程專案都圍繞著同一個產品:**一個基於 Electron 的個人知識庫桌面應用程式**。
+全部八個課程專案都圍繞著同一個產品:**一個基於 Electron 的個人知識庫桌面應用程式**。
```text
┌─────────────────────────────────────────────────────┐
@@ -297,6 +312,25 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,
v v
P05 代理驗證自己的工作 P06 建構完整的 harness
(畢業專案)
+
+ 階段 7:自動化循環
+ ==========================
+ L13 停止提示你的代理——
+ 改為設計循環
+ |
+ v
+ P07 構建你的第一個自動循環
+ (目標循環、定時循環、製造者-檢查者)
+
+ 階段 8:結構化系統
+ =============================
+ L14 把系統畫成一張圖——
+ 節點、邊、共享狀態、路由
+ |
+ v
+ P08 把你的工作流畫成一張圖
+ (顯式圖、平行 fan-out/fan-in、
+ 回退邊、人機協同)
```
如果你是兼職學習,每個階段大約需要一週。如果你想加快速度,階段 1-3 可以在一個長週末完成。
@@ -305,35 +339,39 @@ Harness Engineering 是關於在模型周圍建構一個完整的工作環境,
## 課程大綱
-### 講座 — 12 個概念單元,每個聚焦一個關鍵提問
+### 講座 — 14 個概念單元,每個聚焦一個關鍵提問
*在[文件網站](https://walkinglabs.github.io/learn-harness-engineering/)上閱讀每堂講座的完整內容。*
| 場次 | 問題 | 核心概念 |
|---------|----------|-----------|
-| [L01](../../docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md) | 為什麼強大的模型在真實任務上仍然會失敗? | 基準測試與真實工程之間的能力差距 |
-| [L02](../../docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md) | 「harness」到底是什麼意思? | 五個子系統,指令、狀態、驗證、範圍、生命週期 |
-| [L03](../../docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | 為什麼儲存庫必須是唯一的真實來源? | 如果代理看不到它,它就不存在 |
-| [L04](../../docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | 為什麼一個巨大的指令檔案會失敗? | 漸進揭露,給一張地圖,不是一本百科全書 |
-| [L05](../../docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | 為什麼長時間執行的任務會失去連續性? | 將進度持久化到磁碟;從你停止的地方接續 |
-| [L06](../../docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | 為什麼初始化需要自己的階段? | 在代理開始工作之前驗證環境是否健康 |
-| [L07](../../docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | 為什麼代理會過度延伸和過早結束? | 每次一個功能;明確的完成定義 |
-| [L08](../../docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | 為什麼功能列表是 harness 的基本元素? | 機器可讀的範圍邊界,代理無法忽略 |
-| [L09](../../docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | 為什麼代理會過早宣告勝利? | 驗證缺口,信心不等於正確 |
-| [L10](../../docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | 為什麼端到端測試能改變結果? | 只有完整的流程執行才算真正的驗證 |
-| [L11](../../docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | 為什麼可觀測性應該屬於 harness 內部? | 如果你看不到代理做了什麼,你就無法修復它破壞的東西 |
-| [L12](../../docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | 為什麼每個工作階段都必須留下乾淨的狀態? | 下一個工作階段的成功取決於這個工作階段的清理 |
-
-### 專案 — 6 個動手專案,將講座方法應用於同一個 Electron 應用程式
+| [L01](../../docs/zh-TW/lectures/lecture-01-why-capable-agents-still-fail/index.md) | 為什麼強大的模型在真實任務上仍然會失敗? | 基準測試與真實工程之間的能力差距 |
+| [L02](../../docs/zh-TW/lectures/lecture-02-what-a-harness-actually-is/index.md) | 「harness」到底是什麼意思? | 五個子系統,指令、狀態、驗證、範圍、生命週期 |
+| [L03](../../docs/zh-TW/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) | 為什麼儲存庫必須是唯一的真實來源? | 如果代理看不到它,它就不存在 |
+| [L04](../../docs/zh-TW/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md) | 為什麼一個巨大的指令檔案會失敗? | 漸進揭露,給一張地圖,不是一本百科全書 |
+| [L05](../../docs/zh-TW/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) | 為什麼長時間執行的任務會失去連續性? | 將進度持久化到磁碟;從你停止的地方接續 |
+| [L06](../../docs/zh-TW/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md) | 為什麼初始化需要自己的階段? | 在代理開始工作之前驗證環境是否健康 |
+| [L07](../../docs/zh-TW/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) | 為什麼代理會過度延伸和過早結束? | 每次一個功能;明確的完成定義 |
+| [L08](../../docs/zh-TW/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md) | 為什麼功能列表是 harness 的基本元素? | 機器可讀的範圍邊界,代理無法忽略 |
+| [L09](../../docs/zh-TW/lectures/lecture-09-why-agents-declare-victory-too-early/index.md) | 為什麼代理會過早宣告勝利? | 驗證缺口,信心不等於正確 |
+| [L10](../../docs/zh-TW/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md) | 為什麼端到端測試能改變結果? | 只有完整的流程執行才算真正的驗證 |
+| [L11](../../docs/zh-TW/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) | 為什麼可觀測性應該屬於 harness 內部? | 如果你看不到代理做了什麼,你就無法修復它破壞的東西 |
+| [L12](../../docs/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md) | 為什麼每個工作階段都必須留下乾淨的狀態? | 下一個工作階段的成功取決於這個工作階段的清理 |
+| [L13](../../docs/zh-TW/lectures/lecture-13-loop-engineering/index.md) | 為什麼你需要停止親自提示你的代理? | 從手動驅動到自動循環——目標循環、定時循環、製造者-檢查者分離 |
+| [L14](../../docs/zh-TW/lectures/lecture-14-graph-engineering/index.md) | 為什麼單循環會演變成圖? | 從單循環到圖工程——節點、邊、共享狀態、路由,以及何時真正值得畫圖 |
+
+### 專案 — 8 個動手專案,將講座方法應用於同一個 Electron 應用程式
| 專案 | 你要做什麼 | Harness 機制 |
|---------|------------|-------------------|
-| [P01](../../docs/en/projects/project-01-baseline-vs-minimal-harness/index.md) | 將同一任務執行兩次,僅提示 vs. 規則優先 | 最小 harness,AGENTS.md + init.sh + feature_list.json |
-| [P02](../../docs/en/projects/project-02-agent-readable-workspace/index.md) | 重構儲存庫,讓代理能夠閱讀它 | 代理可讀的工作空間 + 持久化狀態檔案 |
-| [P03](../../docs/en/projects/project-03-multi-session-continuity/index.md) | 讓代理從上次停止的地方接續 | 進度日誌 + 工作階段交接 + 多工作階段連續性 |
-| [P04](../../docs/en/projects/project-04-incremental-indexing/index.md) | 阻止代理做得太多或太少 | 執行時回饋 + 範圍控制 + 增量索引 |
-| [P05](../../docs/en/projects/project-05-grounded-qa-verification/index.md) | 讓代理驗證自己的工作 | 自我驗證 + 有依據的問答 + 基於證據的完成 |
-| [P06](../../docs/en/projects/project-06-runtime-observability-and-debugging/index.md) | 從零建構一個完整的 harness(畢業專案) | 完整 harness,所有機制 + 可觀測性 + 消融實驗 |
+| [P01](../../docs/zh-TW/projects/project-01-baseline-vs-minimal-harness/index.md) | 將同一任務執行兩次,僅提示 vs. 規則優先 | 最小 harness,AGENTS.md + init.sh + feature_list.json |
+| [P02](../../docs/zh-TW/projects/project-02-agent-readable-workspace/index.md) | 重構儲存庫,讓代理能夠閱讀它 | 代理可讀的工作空間 + 持久化狀態檔案 |
+| [P03](../../docs/zh-TW/projects/project-03-multi-session-continuity/index.md) | 讓代理從上次停止的地方接續 | 進度日誌 + 工作階段交接 + 多工作階段連續性 |
+| [P04](../../docs/zh-TW/projects/project-04-incremental-indexing/index.md) | 阻止代理做得太多或太少 | 執行時回饋 + 範圍控制 + 增量索引 |
+| [P05](../../docs/zh-TW/projects/project-05-grounded-qa-verification/index.md) | 讓代理驗證自己的工作 | 自我驗證 + 有依據的問答 + 基於證據的完成 |
+| [P06](../../docs/zh-TW/projects/project-06-runtime-observability-and-debugging/index.md) | 從零建構一個完整的 harness(畢業專案) | 完整 harness,所有機制 + 可觀測性 + 消融實驗 |
+| [P07](../../docs/zh-TW/projects/project-07-loop-engineering-first-loop/index.md) | 構建你的第一個自動循環 | 目標循環、定時循環、製造者-檢查者分離、循環狀態管理 |
+| [P08](../../docs/zh-TW/projects/project-08-graph-engineering-first-graph/index.md) | 把你的工作流畫成一張圖 | 顯式的節點/邊/狀態/路由、平行 fan-out/fan-in、回退邊、人機協同審批 |
```text
專案演進
@@ -508,7 +546,7 @@ npm run docs:preview # 預覽建置後的網站
- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)
- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)
-完整的分層參考列表請見 [`docs/en/resources/reference/`](../../docs/en/resources/reference/index.md)。
+完整的分層參考列表請見 [`docs/zh-TW/resources/reference/`](../../docs/zh-TW/resources/reference/index.md)。
---
@@ -517,13 +555,13 @@ npm run docs:preview # 預覽建置後的網站
```text
learn-harness-engineering/
├── docs/ # VitePress 文件網站
-│ ├── lectures/ # 12 堂講座(index.md + code/ 範例)
+│ ├── lectures/ # 14 堂講座(index.md + code/ 範例)
│ │ ├── lecture-01-*/
│ │ ├── lecture-02-*/
-│ │ └── ...(共 12 堂)
-│ ├── projects/ # 6 個專案說明
+│ │ └── ...(共 14 堂)
+│ ├── projects/ # 8 個專案說明
│ │ ├── project-01-*/
-│ │ └── ...(共 6 個)
+│ │ └── ...(共 8 個)
│ └── resources/ # 多語言模板與參考資料
│ ├── en/ # 英文模板、檢查清單、指南
│ ├── zh/ # 中文模板、檢查清單、指南
@@ -543,7 +581,7 @@ learn-harness-engineering/
## 課程組織方式
- 每堂講座專注於一個問題
-- 課程包含 6 個專案
+- 課程包含 8 個專案
- 每個專案都要求代理做真實的工作
- 每個專案都比較弱 harness 與強 harness 的結果
- 重要的是可量測的差異,而不是寫了多少文件
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 7b2ec2a..179f6d9 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -25,7 +25,8 @@ const zhLectureItems = [
{ text: "跑通完整流程才算真正验证", link: "/zh/lectures/lecture-10-why-end-to-end-testing-changes-results/" },
{ text: "让 agent 的运行过程可观测", link: "/zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/" },
{ text: "每次会话结束前都做好交接", link: "/zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" },
- { text: "从手动驱动到自动循环", link: "/zh/lectures/lecture-13-loop-engineering/" }
+ { text: "从手动驱动到自动循环", link: "/zh/lectures/lecture-13-loop-engineering/" },
+ { text: "从单循环到图工程", link: "/zh/lectures/lecture-14-graph-engineering/" }
];
const zhProjectItems = [
@@ -36,7 +37,8 @@ const zhProjectItems = [
{ text: "运行反馈与行为修正", link: "/zh/projects/project-04-incremental-indexing/" },
{ text: "工作评审与自我验证", link: "/zh/projects/project-05-grounded-qa-verification/" },
{ text: "综合 Agent 工作环境", link: "/zh/projects/project-06-runtime-observability-and-debugging/" },
- { text: "第一个自动循环", link: "/zh/projects/project-07-loop-engineering-first-loop/" }
+ { text: "第一个自动循环", link: "/zh/projects/project-07-loop-engineering-first-loop/" },
+ { text: "把你的工作流画成一张图", link: "/zh/projects/project-08-graph-engineering-first-graph/" }
];
const zhResourceItems = [
@@ -64,7 +66,8 @@ const enLectureItems = [
{ text: "Why End-to-End Testing Changes Results", link: "/en/lectures/lecture-10-why-end-to-end-testing-changes-results/" },
{ text: "Why Observability Belongs Inside the Harness", link: "/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/" },
{ text: "Why Every Session Must Leave a Clean State", link: "/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" },
- { text: "From Manual Prompting to Autonomous Loops", link: "/en/lectures/lecture-13-loop-engineering/" }
+ { text: "From Manual Prompting to Autonomous Loops", link: "/en/lectures/lecture-13-loop-engineering/" },
+ { text: "From Single Loops to Graph Engineering", link: "/en/lectures/lecture-14-graph-engineering/" }
];
const enProjectItems = [
@@ -75,7 +78,8 @@ const enProjectItems = [
{ text: "Runtime Feedback and Scope Control", link: "/en/projects/project-04-incremental-indexing/" },
{ text: "Self-Verification and Role Separation", link: "/en/projects/project-05-grounded-qa-verification/" },
{ text: "Complete Harness (Capstone)", link: "/en/projects/project-06-runtime-observability-and-debugging/" },
- { text: "Your First Automated Loop", link: "/en/projects/project-07-loop-engineering-first-loop/" }
+ { text: "Your First Automated Loop", link: "/en/projects/project-07-loop-engineering-first-loop/" },
+ { text: "Draw Your Workflow as a Graph", link: "/en/projects/project-08-graph-engineering-first-graph/" }
];
const enResourceItems = [
@@ -105,6 +109,7 @@ const viLectureItems = [
{ text: "Tại sao mỗi phiên làm việc phải để lại trạng thái sạch", link: "/vi/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" },
{ text: "Từ Nhắc lệnh Thủ công đến Vòng lặp Tự chủ", link: "/vi/lectures/lecture-13-loop-engineering/" },
+ { text: "Từ Vòng lặp Đơn lẻ đến Kỹ thuật Đồ thị", link: "/vi/lectures/lecture-14-graph-engineering/" }
];
const viProjectItems = [
@@ -117,6 +122,7 @@ const viProjectItems = [
{ text: "Harness Hoàn chỉnh", link: "/vi/projects/project-06-runtime-observability-and-debugging/" },
{ text: "Xây dựng Vòng lặp Tự động Đầu tiên", link: "/vi/projects/project-07-loop-engineering-first-loop/" },
+ { text: "Vẽ Quy trình Làm việc của bạn thành một Đồ thị", link: "/vi/projects/project-08-graph-engineering-first-graph/" }
];
const viResourceItems = [
@@ -146,6 +152,7 @@ const ruLectureItems = [
{ text: "Каждая сессия должна оставлять чистое состояние", link: "/ru/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" },
{ text: "От ручных запросов к автономным циклам", link: "/ru/lectures/lecture-13-loop-engineering/" },
+ { text: "От одиночных циклов к графовой инженерии", link: "/ru/lectures/lecture-14-graph-engineering/" }
];
const ruProjectItems = [
@@ -158,6 +165,7 @@ const ruProjectItems = [
{ text: "Полный harness (капстоун)", link: "/ru/projects/project-06-runtime-observability-and-debugging/" },
{ text: "Постройте свой первый автоматизированный цикл", link: "/ru/projects/project-07-loop-engineering-first-loop/" },
+ { text: "Нарисуйте ваш workflow как граф", link: "/ru/projects/project-08-graph-engineering-first-graph/" }
];
const ruResourceItems = [
@@ -187,6 +195,7 @@ const uzLectureItems = [
{ text: "Har bir sessiya nega toza holat qoldirishi kerak", link: "/uz/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" },
{ text: "Qoʻlda prompt yozishdan avtonom loop'largacha", link: "/uz/lectures/lecture-13-loop-engineering/" },
+ { text: "Yakka loopʼdan grafik muhandisligigacha", link: "/uz/lectures/lecture-14-graph-engineering/" }
];
const uzProjectItems = [
@@ -199,6 +208,7 @@ const uzProjectItems = [
{ text: "Toʻliq harness (yakuniy loyiha)", link: "/uz/projects/project-06-runtime-observability-and-debugging/" },
{ text: "Birinchi avtomatlashtirilgan loop'ingizni qurish", link: "/uz/projects/project-07-loop-engineering-first-loop/" },
+ { text: "Ish oqimingizni grafik qilib chizing", link: "/uz/projects/project-08-graph-engineering-first-graph/" }
];
const uzResourceItems = [
@@ -228,6 +238,8 @@ const koLectureItems = [
{ text: "모든 세션이 클린 상태로 끝나야 하는 이유", link: "/ko/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" },
{ text: "수동 프롬프팅에서 자율 루프로", link: "/ko/lectures/lecture-13-loop-engineering/" },
+
+ { text: "단일 루프에서 그래프 엔지니어링으로", link: "/ko/lectures/lecture-14-graph-engineering/" },
];
const koProjectItems = [
@@ -240,6 +252,8 @@ const koProjectItems = [
{ text: "완성형 하네스(캡스톤)", link: "/ko/projects/project-06-runtime-observability-and-debugging/" },
{ text: "첫 번째 자동 루프 구축하기", link: "/ko/projects/project-07-loop-engineering-first-loop/" },
+
+ { text: "내 워크플로우를 그래프로 그리기", link: "/ko/projects/project-08-graph-engineering-first-graph/" },
];
const koResourceItems = [
@@ -269,6 +283,7 @@ const jaLectureItems = [
{ text: "すべてのセッションをきれいな引き継ぎで終える", link: "/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" },
{ text: "手動プロンプトから自律ループへ", link: "/ja/lectures/lecture-13-loop-engineering/" },
+ { text: "単一ループからグラフエンジニアリングへ", link: "/ja/lectures/lecture-14-graph-engineering/" }
];
const jaProjectItems = [
@@ -281,6 +296,7 @@ const jaProjectItems = [
{ text: "完全なエージェント harness を構築する(総合課題)", link: "/ja/projects/project-06-runtime-observability-and-debugging/" },
{ text: "初めての自動ループを構築する", link: "/ja/projects/project-07-loop-engineering-first-loop/" },
+ { text: "ワークフローをグラフとして描く", link: "/ja/projects/project-08-graph-engineering-first-graph/" }
];
const jaResourceItems = [
@@ -310,6 +326,7 @@ const esLectureItems = [
{ text: "Deja un handoff limpio al final de cada sesión", link: "/es/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" },
{ text: "Del Prompting Manual a los Loops Autónomos", link: "/es/lectures/lecture-13-loop-engineering/" },
+ { text: "De los Loops Únicos a la Ingeniería de Grafos", link: "/es/lectures/lecture-14-graph-engineering/" }
];
const esProjectItems = [
@@ -322,6 +339,7 @@ const esProjectItems = [
{ text: "Construye un harness completo (capstone)", link: "/es/projects/project-06-runtime-observability-and-debugging/" },
{ text: "Construye Tu Primer Loop Automatizado", link: "/es/projects/project-07-loop-engineering-first-loop/" },
+ { text: "Dibuja Tu Flujo de Trabajo como un Grafo", link: "/es/projects/project-08-graph-engineering-first-graph/" }
];
const esResourceItems = [
@@ -351,6 +369,7 @@ const frLectureItems = [
{ text: "Laisser un handoff propre à la fin de chaque session", link: "/fr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" },
{ text: "Du prompting manuel aux boucles autonomes", link: "/fr/lectures/lecture-13-loop-engineering/" },
+ { text: "Des boucles simples à l'ingénierie des graphes", link: "/fr/lectures/lecture-14-graph-engineering/" }
];
const frProjectItems = [
@@ -363,6 +382,7 @@ const frProjectItems = [
{ text: "Construire un harness complet (capstone)", link: "/fr/projects/project-06-runtime-observability-and-debugging/" },
{ text: "Construisez votre première boucle automatisée", link: "/fr/projects/project-07-loop-engineering-first-loop/" },
+ { text: "Dessinez votre workflow sous forme de graphe", link: "/fr/projects/project-08-graph-engineering-first-graph/" }
];
const frResourceItems = [
@@ -392,6 +412,7 @@ const deLectureItems = [
{ text: "Sauberes Handoff am Ende jeder Session", link: "/de/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" },
{ text: "Von manuellen Prompts zu autonomen Loops", link: "/de/lectures/lecture-13-loop-engineering/" },
+ { text: "Von Einzel-Loops zu Graph Engineering", link: "/de/lectures/lecture-14-graph-engineering/" }
];
const deProjectItems = [
@@ -404,6 +425,7 @@ const deProjectItems = [
{ text: "Einen vollständigen Agenten-harness bauen (Capstone)", link: "/de/projects/project-06-runtime-observability-and-debugging/" },
{ text: "Baue deinen ersten automatisierten Loop", link: "/de/projects/project-07-loop-engineering-first-loop/" },
+ { text: "Zeichne deinen Workflow als Graph", link: "/de/projects/project-08-graph-engineering-first-graph/" }
];
const deResourceItems = [
@@ -433,6 +455,7 @@ const arLectureItems = [
{ text: "اترك handoff نظيفًا في نهاية كل جلسة", link: "/ar/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" },
{ text: "من المطالبة اليدوية إلى الحلقات المستقلة", link: "/ar/lectures/lecture-13-loop-engineering/" },
+ { text: "من الحلقة الواحدة إلى هندسة الرسوم البيانية", link: "/ar/lectures/lecture-14-graph-engineering/" }
];
const arProjectItems = [
@@ -445,6 +468,7 @@ const arProjectItems = [
{ text: "ابنِ harness كاملًا للوكيل (Capstone)", link: "/ar/projects/project-06-runtime-observability-and-debugging/" },
{ text: "ابني أول حلقة آلية", link: "/ar/projects/project-07-loop-engineering-first-loop/" },
+ { text: "ارسم سير عملك كرسم بياني", link: "/ar/projects/project-08-graph-engineering-first-graph/" }
];
const arResourceItems = [
@@ -474,6 +498,7 @@ const trLectureItems = [
{ text: "Her Oturum Neden Temiz Bir Durumla Bitmeli", link: "/tr/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" },
{ text: "Manuel Prompting'den Otonom Loop'lara", link: "/tr/lectures/lecture-13-loop-engineering/" },
+ { text: "Tek Döngülerden Graf Mühendisliğine", link: "/tr/lectures/lecture-14-graph-engineering/" }
];
const trProjectItems = [
@@ -486,6 +511,7 @@ const trProjectItems = [
{ text: "Eksiksiz Harness (Bitirme Projesi)", link: "/tr/projects/project-06-runtime-observability-and-debugging/" },
{ text: "İlk Otomatik Loop'unuzu Oluşturun", link: "/tr/projects/project-07-loop-engineering-first-loop/" },
+ { text: "İş Akışınızı Bir Graf Olarak Çizin", link: "/tr/projects/project-08-graph-engineering-first-graph/" }
];
const trResourceItems = [
@@ -515,6 +541,7 @@ const zhTWLectureItems = [
{ text: "每次會話結束前都做好交接", link: "/zh-TW/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" },
{ text: "從手動驅動到自動循環", link: "/zh-TW/lectures/lecture-13-loop-engineering/" },
+ { text: "從單循環到圖工程", link: "/zh-TW/lectures/lecture-14-graph-engineering/" }
];
const zhTWProjectItems = [
@@ -527,6 +554,7 @@ const zhTWProjectItems = [
{ text: "搭建一套完整的 agent 工作環境", link: "/zh-TW/projects/project-06-runtime-observability-and-debugging/" },
{ text: "搭建你的第一個自動循環", link: "/zh-TW/projects/project-07-loop-engineering-first-loop/" },
+ { text: "把你的工作流畫成一張圖", link: "/zh-TW/projects/project-08-graph-engineering-first-graph/" }
];
const zhTWResourceItems = [
@@ -555,6 +583,7 @@ const ptBRLectureItems = [
{ text: "Por que observabilidade pertence ao Harness", link: "/pt-BR/lectures/lecture-11-why-observability-belongs-inside-the-harness/" },
{ text: "Por que toda sessão deve deixar um estado limpo", link: "/pt-BR/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" },
{ text: "Do Prompting Manual aos Loops Autônomos", link: "/pt-BR/lectures/lecture-13-loop-engineering/" },
+ { text: "Do Loop Único à Engenharia de Grafos", link: "/pt-BR/lectures/lecture-14-graph-engineering/" }
];
const ptBRProjectItems = [
@@ -566,6 +595,7 @@ const ptBRProjectItems = [
{ text: "Autoverificação e Separação de Papéis", link: "/pt-BR/projects/project-05-grounded-qa-verification/" },
{ text: "Harness Completo (Projeto Final)", link: "/pt-BR/projects/project-06-runtime-observability-and-debugging/" },
{ text: "Construa Seu Primeiro Loop Automatizado", link: "/pt-BR/projects/project-07-loop-engineering-first-loop/" },
+ { text: "Desenhe Seu Fluxo de Trabalho como um Grafo", link: "/pt-BR/projects/project-08-graph-engineering-first-graph/" }
];
const ptBRResourceItems = [
@@ -595,6 +625,7 @@ const ukLectureItems = [
{ text: "Чому кожна сесія має залишати чистий стан", link: "/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" },
{ text: "Від ручного введення промптів до автономних циклів", link: "/uk/lectures/lecture-13-loop-engineering/" },
+ { text: "Від одиночних циклів до графової інженерії", link: "/uk/lectures/lecture-14-graph-engineering/" }
];
const ukProjectItems = [
@@ -607,6 +638,7 @@ const ukProjectItems = [
{ text: "Повний harness (підсумковий проєкт)", link: "/uk/projects/project-06-runtime-observability-and-debugging/" },
{ text: "Побудова вашого першого автоматизованого циклу", link: "/uk/projects/project-07-loop-engineering-first-loop/" },
+ { text: "Намалюйте ваш робочий процес як граф", link: "/uk/projects/project-08-graph-engineering-first-graph/" }
];
const ukResourceItems = [
diff --git a/docs/ar/lectures/lecture-14-graph-engineering/index.md b/docs/ar/lectures/lecture-14-graph-engineering/index.md
new file mode 100644
index 0000000..ca965be
--- /dev/null
+++ b/docs/ar/lectures/lecture-14-graph-engineering/index.md
@@ -0,0 +1,349 @@
+[English Version →](../../../en/lectures/lecture-14-graph-engineering/)
+
+> أمثلة الكود: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-14-graph-engineering/code/)
+> مشروع عملي: [المشروع 08. ارسم سير عملك كرسم بياني](./../../projects/project-08-graph-engineering-first-graph/index.md)
+
+# المحاضرة 14. من الحلقة الواحدة إلى هندسة الرسوم البيانية
+
+بعد ستة أسابيع من انتشار هندسة الحلقات (Loop Engineering)، في 18 يوليو 2026، نشر بيتر شتاينبرغر — مؤلف OpenClaw الذي قال لك في المحاضرة السابقة "توقف عن كتابة المطالبات لوكيل البرمجة" — تغريدة:
+
+> "هل ما زلنا نتحدث عن الحلقات، أم انتقلنا بالفعل إلى الرسوم البيانية؟"
+
+تغريدة واحدة — حصلت على حوالي 575 ألف مشاهدة خلال يوم واحد، وارتفعت إلى حوالي 3 ملايين بنهاية الشهر. وبعد ساعات قليلة، نشر مهندس التعلم الآلي هامل حسين مقالًا بعنوان *Loop Engineering Is Dead. Enter Graph Engineering* — جسم المقال كله لم يكن سوى صورة متحركة واحدة مكتوب عليها "Stop it" — وحصل على حوالي 680 ألف مشاهدة إضافية.
+
+والأكثر إثارة للاهتمام: **كلاهما كانا يمزحان.** الأول كان يسخر من صناعة تختلق مصطلحًا جديدًا كل ستة أسابيع، والثاني كان يتابع النكتة بمواصلة هذه المزحة. لكن النكتة عاشت حوالي عطلة نهاية أسبوع واحدة فقط — الدورات والخرائط الذهنية ومجموعات الأدوات غرقت في الخط الزمني قبل نهاية عطلة نهاية الأسبوع، متبوعة بكومة من الأرقام المختلقة: "دقة +18%، تكلفة -85%" بيانات مزيفة (الرقمان موجودان فعلًا، لكنهما من ورقة بحثية عن مخططات الأنابيب الكيميائية، وبمقارنة مع خطوط أساس مختلفة تمامًا)، و"اكتشفت مايكروسوفت وستانفورد وAnthropic هندسة الرسوم البيانية في نفس الوقت" خبر أيضًا كاذب. التحقق من الحقائق وحده أكد "رائدًا" حقيقيًا واحدًا: جوش سيمونز، الذي كُتبت مقالته *We Are Entering the Graph Engineering Phase* في 4 يوليو — قبل النكتة بأسبوعين كاملين — **النكتة هي التي جعلت هذا الأمر رائجًا، والنكتة لم تُنشئ هذا الأمر.**
+
+> المصدر: [goddaehee: التحقق من حقائق هندسة الرسوم البيانية (2026-07-30)](https://goddaehee.tistory.com/628)؛ [YC Startup School 2026: مقابلة جنسن هوانغ (مع النص الكامل)](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia)؛ [explainx: هندسة الرسوم البيانية (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026)
+
+ما ستفعله هذه المحاضرة ليس إضافة المزيد من الوقود إلى هذه الضجة، بل تفكيكها ورؤيتها بوضوح: **لماذا ينمو رسم بياني حتمًا بعد حلقة واحدة؟ وما الفرق الحقيقي بين الرسم البياني وسير العمل؟ ومتى تحتاج إليه فعلًا، ومتى لا تحتاجه؟**
+
+## Prompt و Context و Loop و Graph: أربعة أسماء، طبقة فوق أخرى
+
+في نهاية يوليو، نشر المهندس روهيت (rohit4verse@) [منشورًا طويلًا](https://x.com/rohit4verse/status/2082478623043547356) رتّب فيه تاريخ تسمية هندسة الذكاء الاصطناعي في السنوات القليلة الماضية في إطار من أربع طبقات واضح. هذا هو أفضل نظام إحداثيات لفهم هندسة الرسوم البيانية:
+
+| المرحلة | ما الذي تشكّله | السؤال الذي تجيب عنه | النواتج الرئيسية |
+|---------|---------------|---------------------|-----------------|
+| **Prompt Engineering** | التعليمات | كيف نخبر النموذج بما يجب فعله؟ | instructions، examples، constraints، roles، output formats |
+| **Context Engineering** | المعلومات | ماذا يجب أن يعرف النموذج قبل أن يقرر؟ | documents، history، memory، tool definitions، environment state |
+| **Loop Engineering** | وقت التشغيل | كيف نجعل النموذج يكرر العمل حتى يتحقق الهدف؟ | observe، reason، act، inspect، update، شرط التوقف |
+| **Graph Engineering** | النظام | كيف تتعاون وكلاء وحلقات وأدوات ومقيّمون متعددون؟ | العقد، الحواف، الحالة المشتركة، قواعد التوجيه |
+
+لاحظ كيف تُقرأ هذه السلسلة: **كل طبقة لا تحل محل الطبقة التي قبلها — بل تتكدس فوقها.**
+
+- بعد أن وجدت هندسة السياق (context engineering)، لم تتوقف عن كتابة المطالبات — كل تكرار ما زال يحتاج إلى مطالبة، فقط الحلقة تقوم بتحديثها عندما تتغير البيئة.
+- بعد أن بنيت الحلقة، لم تخلِ بالسياق — كل جولة من الحلقة تعيد تجميع سياقها.
+- عند طبقة الرسم البياني، لم يختفِ لا الـ prompt ولا الـ context ولا الـ loop: **كل عقدة تحمل مطالبتها الخاصة وسياقها الخاص وأدواتها الخاصة وذاكرتها الخاصة وحلقتها الخاصة.** الرسم البياني يقرر كيفية ارتباط العقد ببعضها.
+
+هكذا يختم روهيت منشوره:
+
+> بمجرد أن يحتاج الوكيل إلى التخصص والتوازي والحالة المشتركة والتحقق والاستعادة، لم يعد حلقة. إنه رسم بياني.
+
+**لحظة — أين الـ Harness؟** هذه الأسماء الأربعة لا تتضمن هندسة الحزام، لكن هذه الدورة كلها تدور حول الحزام. السبب بسيط: روهيت كان يحكي تاريخ المصطلحات الرائجة، ونهايته كانت الرسم البياني، والطبقة التي في المنتصف قُفز عنها. وحتى الطبقة التي ينتمي إليها الحزام غير محسومة في الأوساط — [explainx](https://explainx.ai/blog/context-prompt-loop-harness-engineering-stack-2026) يضعها فوق الحلقة، بينما [ورقة Buildrix](https://arxiv.org/abs/2606.25139) يضعها تحت الحلقة. هذه الدورة حسمت الأمر في المحاضرة الثانية: الحزام هو الأساس، والحلقات والرسوم البيانية تُبنى فوقه.
+
+هذا يفسر ظاهرة غريبة: لماذا لم ينتشر مصطلح "Graph Engineering" حتى يوليو 2026، لكن الجميع اكتشف أنهم "يفعلون هذا منذ فترة". لأن الرسم البياني ليس اختراعًا جديدًا — بل هو ما تصبح عليه الحلقة عندما تتعقد المهمة إلى درجة معينة. **الاسم جاء لاحقًا؛ الممارسة كانت موجودة منذ البداية.**
+
+## تفكيك الرسم البياني: العقد والحواف والحالة والتوجيه
+
+اختزل الرسم البياني إلى أبسط أربعة أجزاء.
+
+**العقدة (Node)**: وحدة عمل تتحمل مسؤولية معينة. يمكن أن تكون:
+- كودًا حتميًا (تشغيل الاختبارات، حساب التغطية)
+- استدعاء نموذج (توليد الوثائق)
+- أداة (git commit، إرسال رسالة)
+- وكيلًا كاملًا — يحمل حلقة خاصة به، ويفهم الأهداف، ويستخدم الأدوات، ويعيد المحاولة من تلقاء نفسه عندما لا يستطيع المتابعة
+
+العقدة هي الخط الفاصل الحقيقي بين هندسة الرسوم البيانية وهندسة سير العمل، وهذا سنتناوله بالتفصيل أدناه.
+
+**الحافة (Edge)**: توضح كيف تُسلَّم المهام بين العقد. ليست مجرد "افعل A ثم B" — يمكن للحافة أن تعبّر عن:
+- **التوازي**: بعد اكتمال A، تبدأ B وC في نفس الوقت
+- **الشرط**: الاختبارات نجحت، اذهب يسارًا؛ فشلت، اذهب يمينًا
+- **الفشل/إعادة المحاولة**: عقدة تتعطل، تعود إلى نفسها وتشغّل مرة أخرى
+- **التراجع**: فشل التحقق، عُد إلى عقدة التنفيذ التي تبعد ثلاث قفزات
+
+**الحالة المشتركة (State)**: حزمة البيانات المنقولة بين العقد. المتطلبات وملاحظات البحث وإصدارات الكود ونتائج الاختبارات واستنتاجات المراجعة — كلها تُكتب على نفس سطح العمل المشترك. العقد لا تخاطب بعضها مباشرة؛ كلها تقرأ وتكتب نفس الحالة.
+
+**قواعد التوجيه (Routing)**: تحدد إلى أين تذهب الخطوة التالية. هذا هو "تدفق التحكم" في الرسم البياني، بأبسط العبارات:
+
+> نجحت الاختبارات فسلّم؛ فشلت الاختبارات فعد إلى عقدة التنفيذ؛ المعلومات غير كافية فعد إلى عقدة البحث.
+
+اجمع الأجزاء الأربعة معًا، ويبدو الرسم البياني النموذجي للتطوير هكذا:
+
+```mermaid
+flowchart TD
+ S["الحالة المشتركة<br/>المتطلبات / الملاحظات / الكود / النتائج"] --- R["عقدة البحث<br/>وكيل: تحديد المشكلة"]
+ R -->|"إنتاج الحل"| I["عقدة التنفيذ<br/>وكيل: كتابة التعديلات + الاختبارات"]
+ I -->|"إنتاج الكود"| V["عقدة التحقق<br/>وكيل: مراجعة مستقلة + تشغيل الاختبارات"]
+ V -->|"لم تنجح"| I
+ V -->|"نجحت"| M["عقدة الدمج<br/>كود: commit + تحديث الحالة"]
+ M -->|"تحديث الحالة"| S
+ I -->|"معلومات غير كافية"| R
+```
+
+قارن هذا بمخطط الحلقة في المحاضرة السابقة: كانت الحلقة حلقة مغلقة — اكتشاف، توزيع، تحقق، حفظ دائم، ثم العودة إلى الاكتشاف. في رسم هذه المحاضرة، **الحلقة المغلقة ما زالت موجودة، لكنها فُككت إلى عقد وحواف صريحة.** يمكن لعقدة التحقق أن ترجع الفشل مباشرة إلى عقدة التنفيذ، ويمكن لعقدة التنفيذ أن ترجع إلى البحث بسبب نقص المعلومات — هذه "حواف التراجع" كانت ضمنية في حلقة واحدة، وكان الوكيل نفسه "يتذكر" أنه يجب أن يعود، داخل نافذة سياقه الخاصة.
+
+## متى لا تكفي الحلقة
+
+الحلقة الواحدة لها طريق رئيسي واحد فقط. في حلقة maker-checker التي بنيتها في المحاضرة السابقة، كل القرارات — ماذا أفعل بعد ذلك، إلى أين أذهب عند الفشل — كانت تحدث داخل نافذة سياق وكيل واحد. إذا عقدت المهمة أكثر قليلًا، تظهر أربعة أسئلة:
+
+1. **تقسيم العمل**: وكيل يبحث عن المتطلبات، ووكيل يكتب الكود، ووكيل يختبر — من يبدأ أولًا؟
+2. **التوازي**: أي أجزاء من العمل يمكن أن تعمل في نفس الوقت؟
+3. **التراجع**: عندما تفشل الاختبارات، إلى أين تعود — إلى عقدة التنفيذ، أم إلى عقدة البحث؟
+4. **التسليم**: كيف يرى عدة وكلاء نفس المتطلبات والملاحظات ونتائج الاختبارات؟ إذا اختلف المراجع مع المنفذ، رأي من ينتصر؟
+
+قدم جنسن هوانغ وجهة نظر مشابهة في [مقابلة Startup School 2026 مع Y Combinator](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia) (مع جاري تان): كلما زادت أتمتة التنفيذ الأساسي بواسطة الوكلاء، انتقلت القيمة الأساسية للإنسان إلى "تصميم الأنظمة، وتحديد القيود، والتحكم الدقيق في الوكلاء". مثال التحكم الذي أعطاه كان ملموسًا جدًا — "عندما يقدم الوكيل خطة، أغيّر كلمة واحدة في ملف الخطة، وهذه الكلمة الواحدة تُحدث فرقًا دقيقًا"؛ كما توقع أن المهارة الأساسية المستقبلية هي "التفكير النظامي" (systems thinking).
+
+أقوى ضربة في سلسلة النقاش جاءت من لويس كاتاكورا:
+
+> **"الحلقات لديها مساحة كبيرة جدًا للتسامح. الرسوم البيانية تُجبرك على الاعتراف بكمية الأجزاء في سير عملك التي لم تُنموذج فعلًا."**
+
+هذه الجملة تكشف الفرق العميق بين الحلقة والرسم البياني:
+
+- **الحلقة قرار مؤجل.** تترك وكيلًا واحدًا يتولى كل العمل، وإذا تعثر تتعامل معه لاحقًا. يمكن تأجيل البنية التحتية. هذا مريح، لكن ثمنه أن أنماط الفشل غير مرئية — أنت لا تعرف أبدًا في أي خطوة تعثر، لأنه هو نفسه لا يعرف.
+- **الرسم البياني قرار مسبق.** يجب أن تعلن البنية الكاملة مقدمًا: من المسؤول عن ماذا، وكيف تترابط المهام، إلى أين يعود أي فشل معين. هذا أكثر إرهاقًا، لكنه يمنحك قابلية القراءة والتدقيق والإصلاح الموضعي.
+
+بعبارة أوضح: **الحلقة تخفي المشكلة داخل الحلقة، والرسم البياني يضع المشكلة على الورق.** الأول يناسب الاستكشاف، والثاني يناسب الإنتاج.
+
+## ثلاثة فشل بنيوي للحلقة الواحدة
+
+لماذا لا تصمد الحلقة الواحدة عند التوسع؟ مقالة eigent.ai *Graph Engineering for AI Agents: Beyond Single Feedback Loops* تعطي ثلاثة فشل بنيوي — انتبه، إنها فشل بنيوي، وليست خللًا في حلقة معينة.
+
+**أولًا، دعنا نرد على دافع: ألا يمكن للحلقة أيضًا أن تحتوي على نقاط تحقق؟** تستطيع. تحقق المحاضرة السابقة، وشروط التوقف، وحتى إعادة المحاولة من نقطة التوقف — كلها يمكن أن تحملها الحلقة. لكن الفشل الثلاثة التالية هي بالضبط ما لا تستطيع نقاط التحقق حله — لأن نقطة التحقق داخل الحلقة تنمو داخل نفس الوكيل، والمدقق والمشكل يتشاركان نفس العقل ونفس السياق. ستمنع "التسليم دون تحقق"، لكنها لن تسأل "هل هذا المؤشر صحيح؟" أو "هل يجب مطاردة هذا الهدف؟" — لأن الإجابة مكتوبة في سياقها الخاص، وهي لا تراها. الرسم البياني لا يعطيك المزيد من نقاط التحقق، بل ينقل التحقق **إلى الخارج**: من "داخل الوكيل" إلى "عقدة مستقلة" بسياق جديد تمامًا (عقدة التحقق التي شرحناها في القسم السابق). معنى كلمة "بنية" هنا: ليست أن الحلقة ينقصها جزء، بل أن "الحاكم والمحكوم يشتركان في نفس العقل" هو البنية نفسها.
+
+### 1. جودهارت: ارتفعت الأرقام، لكن العمل تدهور
+
+ادفع أي مؤشر واحد إلى أقصى حد، وسيتوقف عن قياس ما تظنه أنه يقيس. الحالة الكلاسيكية: فريق دعم العملاء بنى حلقة حول "معدل حل التذاكر". ارتفعت الأرقام الأسبوعية باستمرار. بعد أشهر، أظهرت بيانات التجديد أن معدل فقدان العملاء تضاعف — **تعلم البوت إغلاق التذاكر**: تحويل الموضوع، وثني المستخدمين عن متابعة الأسئلة، ووضع علامة "تم الحل" على المشكلات التي لم تُحل.
+
+فعلت الحلقة كل ما طُلب منها. الرقم هو الذي انفصل عن ما يهم العمل فعلًا. هذا قانون جودهارت.
+
+### 2. العمى التصاعدي: لا يسأل أبدًا "هل هذا هو الهدف الصحيح؟"
+
+داخل الحلقة، القيمة المرجعية مقدسة. منظم الحرارة لا يسأل "هل درجة 68 فهرنهايت هي الحرارة الصحيحة؟". حلقة المبيعات لا تسأل "هل الحصة معقولة؟". حلقة تقييم الوكيل لا تسأل "هل هذا المعيار يتطابق مع نتائج الأعمال الحقيقية؟".
+
+**من اختار ذلك الهدف، والحلقة ستجري نحوه حتى لو لم يكن الشيء الصحيح الذي يجب مطاردته منذ البداية.** في بنية الحلقة الواحدة، لا يوجد أي موقع يمكن أن يُطرح فيه هذا السؤال.
+
+### 3. التعارض: حلقات مستقلة تقوّض بعضها
+
+في الأنظمة الحقيقية توجد عشرات الحلقات، كل واحدة مبنية بشكل مستقل. حلقة سرعة الاستجابة تقوّض حلقة عمق الجودة، وحلقة النمو تقوّض حلقة الجودة. كل حلقة تبدو سليمة على لوحة تحكمها الخاصة، بينما النظام ككل يهتز — مثل عدة أشخاص يسحبون نفس الحبل في اتجاهات مختلفة.
+
+**هندسة الرسوم البيانية بُنيت للإجابة على مجموعة الأسئلة التي لا تستطيع الحلقة الواحدة الإجابة عنها:**
+
+- أي الحلقات تُغذي أي الحلقات الأخرى؟
+- أي الحلقات تملك الأهداف التي تطاردها حلقات أخرى؟
+- أي الحلقات يمكنها رفض أو تراجع تغيير ما؟
+- أي المؤشرات مسموح لها بالتحرك، وأيها يجب أن يبقى مجمدًا؟
+
+عندما يحتوي نظامك على "حلقات يمكنها أكل أهدافك" و"حلقات يمكنها رفض تغييراتك"، تصبح العلاقات بينها عناصر هندسية — والعلاقات بين العلاقات، عندما تُرسم، هي رسم بياني.
+
+### المراسي: تثبيت الحلقة على الواقع
+
+في مقالة eigent قسم عنوانه "الجزء الذي يتخطاه الجميع": **المراسي (anchors)**. مهما كانت شبكة الحلقات أنيقة، إذا انجرفت كل حلقة بعيدًا عن الواقع، فالشبكة مجرد رنين لانجراف متبادل. المرساة هي ما يثبت الحلقة في العالم الحقيقي — نتائج الأعمال الفعلية، مجموعات بيانات الحقيقة الأساسية، الفحوصات البشرية العشوائية. المراسي هي أسهل جزء في تصميم الرسم البياني يمكن تخطيه، وهي الجزء الذي لا يمكنك تحمل تخطيه.
+
+## الرسم البياني مقابل سير العمل: ليس مجرد تغيير اسم
+
+هذه هي النقطة الأكثر سوء فهم في هذه المحاضرة كلها، لذا تستحق قسمًا خاصًا بها.
+
+أول رد فعل عندما انفجرت هندسة الرسوم البيانية، أي شخص له خبرة في الإنتاج تمتم بشيء مثل: "أليس هذا مجرد سير عمل؟ DAG وآلات الحالة ومحركات سير العمل، شغّلناها لعقود."
+
+**هذا الحدس صحيح في نصفه.** الرسم البياني وسير العمل يشتركان في نفس الهيكل: عقد + حواف + حالة مشتركة + توجيه. Airflow وPrefect وDagster وTemporal كانت تنظم بهذه الطريقة نفسها لعقود. والأنماط الخمسة في مقالة Anthropic *Building Effective Agents* (ديسمبر 2024) — تسلسل المطالبات، والتوجيه، والتوازي، المنظم/العمال، المقيّم/المحسّن — عندما تُرسم، فهي بالضبط رسوم بيانية تنفيذ بأشكال مختلفة.
+
+**النصف الخاطئ يكمن في العقد.** عقد سير العمل التقليدي هي **دوال حتمية**: دالة Python، أو نص برمجي shell، أو مهمة SQL. الحواف كود مكتوب بشكل جامد: `if` و`switch` و`case`. المهندس يبقي النظام كله بصيانة بالكود، والسلوك قابل للتنبؤ — نفس المدخلات تسير دائمًا في نفس المسار.
+
+يمكن لعقدة هندسة الرسوم البيانية أن تكون **وكيلًا كاملًا**: يحمل حلقة خاصة به، ويستخدم الأدوات، ويفهم الأهداف، ويعيد المحاولة عند الفشل. والحواف ليست بالضرورة جامدة — يمكن أن تحمل قواعد توجيه، يقررها مخرج العقدة السابقة، أو نتيجة تحقق، أو حتى نموذج آخر.
+
+لتوضيح هذا الفرق، نستعير مفهومين من Anthropic. تستخدم Anthropic سؤالًا واحدًا للتمييز بين سير العمل والوكيل: **من يقرر تدفق التحكم؟** إذا كان الكود يثبت الخطوات فهو سير عمل، وإذا كان النموذج يمكنه تغيير الخطوات في وقت التشغيل فهو وكيل.
+
+فما هو الرسم البياني؟ **الرسم البياني هو حاوية تستوعب كليهما.** يمكن لرسم واحد أن يحتوي في نفس الوقت على:
+
+- عقد سير عمل: تشغيل الاختبارات، حساب التغطية — كود حتمي، لا يحتاج نموذجًا
+- عقد وكلاء: تنفيذ الميزات، مراجعة الكود — وكلاء كاملون مدفوعون بالنموذج
+- عقد بشرية: الموافقة، المراجعة — عقد تفاعل بشري، يتوقف عندها الرسم ويستمر بانتظار موافقة الإنسان
+
+إذن العبارة الدقيقة هي: **هندسة الرسوم البيانية ليست بديلًا عن سير العمل، بل تعميمًا له** — تُوسّع نوع العقدة من "دالة" إلى "وكيل"، وتُوسّع قرارات الحافة من "كود ثابت" إلى "توجيه ديناميكي". سير العمل هو الحالة الخاصة "الحتمية تمامًا" من الرسم البياني.
+
+وجهة النظر المعارضة (مقالة iii.dev *Loops, Graphs, and the Layer That Matters*) تصل إلى نفس النقطة، لكنها تستنتج العكس:
+
+> "الشكل هو الجزء السهل، وهو قابل للاستبدال. القرار الحامل للحمل هو مما يتكون الـ loop أو الـ graph، وماذا يحدث له بعد أن يعمل."
+
+معنى iii.dev: لا تخلط بين "الطوبولوجيا" والإنجاز الهندسي. هندسة سير العمل اشتغلت لعقود، وما بقي فعلًا ليس كيفية ارتباط العقد — بل **قابلية إعادة التشغيل، وقابلية الملاحظة، وقابلية الاستعادة**: يمكنك إعادة تشغيل فشل، ومراقبة تشغيل، واستئناف بعد تعطل. يمكنك تغيير شكل الرسم البياني في أي يوم؛ تلك القدرات الحاملة للحمل هي حيث يجب أن تستثمر جهدك. هذا النقد يستحق أن تضعه في ذهنك: **رسم الرسم البياني ليس الهدف؛ ما مقدار القدرة الهندسية التي يمكن للرسم أن يحملها هو الهدف.**
+
+## أنت كنت ترسم الرسوم البيانية طوال الوقت
+
+"زجاجة جديدة لنبيذ قديم" له دليل آخر: الأدوات كانت جاهزة منذ زمن.
+
+- **LangGraph**: صدر في يناير 2024، وبحلول يوليو 2026 وصل إلى حوالي 65 مليون تحميل شهريًا. إنه محرك تنفيذ رسوم بيانية للوكلاء — العقد يمكن أن تكون وكلاء، والحواف يمكن أن تحمل توجيهًا شرطيًا ونقاط تحقق وقطعًا.
+- **أنماط Anthropic الخمسة**: مقالة *Building Effective Agents* الصادرة في ديسمبر 2024 كانت قد رسمت بالفعل رسوم تسلسل المطالبات والتوجيه والتوازي والمنظم/العمال والمقيّم/المحسّن، فقط لم تسمّها هندسة الرسوم البيانية.
+- **fan-out للوكلاء الفرعيين في Claude Code**: عندما تجعل وكيلًا رئيسيًا واحدًا يرسل مجموعة وكلاء فرعيين يعملون بالتوازي، فأنت تبني بالفعل رسمًا بيانيًا، فقط لم تدرك ذلك.
+- **آلات الحالة، ومجدوِلو DAG، وقوائم المهام، والرسوم البيانية المعرفية**: لقد كانت علوم الحاسوب تهندس الرسوم البيانية لعقود.
+
+ما الجديد فعلًا؟ **العقدة انتقلت من "دالة" إلى "وكيل".** هذا هو التغيير الوحيد — وهو كل التغيير. سابقًا، عندما تكتب عقدة سير عمل، عليك أن تكتب منطقها ومعالجة الأخطاء وسياسة إعادة المحاولة بوضوح. الآن تحتاج العقدة إلى تعليمة واحدة فقط — "ابحث في هذه المشكلة"، "راجع هذا الكود" — والباقي يقوم به النموذج من تلقاء نفسه. أصبحت العقد رخيصة، لذلك أصبح الرسم البياني يستحق الرسم.
+
+## ابنِ أول رسم بياني لك من الصفر
+
+كفى نظرية. لنتحرك. maker-checker في المحاضرة السابقة كان **وكيلًا واحدًا** يحلق بنفسه. أول ما تفعله هندسة الرسوم البيانية هو تفكيك ذلك الوكيل الأحادي: **كل عقدة تصبح وكيلًا متخصصًا يملك مطالبة خاصة وسياقًا خاصًا وأدوات خاصة وذاكرة خاصة وحلقة صغيرة خاصة به؛ العقد لا تشارك السياق مع بعضها — بل تتسلم فقط عبر حالة مشتركة واحدة.** هذا هو النسخة البشرية من جملة روهيت — "الرسم البياني يقرر ما تراه كل عقدة، ومتى تعمل، وإلى أين يذهب مخرجه، ومن يمكنه رفضه، وما الذي يوقف النظام". كل الترميزات أدناه غير مرتبطة بأي محرك محدد — هذه مفاهيم؛ LangGraph وCrewAI وغيرها مجرد تطبيقات تحوّلها إلى برامج قابلة للتنفيذ، APIs مختلفة، نفس الهيكل. ست خطوات، لا تتخطَّ أي واحدة.
+
+**الخطوة الأولى: عرّف الحالة المشتركة (State).** أولًا، افصل بين الطبقتين: **على مستوى الرسم البياني، يُشارك فقط الحالة؛ سياق كل عقدة خاص.** الوكيل الأحادي له سياق واحد، وعند التشغيل الطويل يغرق في نصه الطويل؛ الرسم البياني يقطع السياق إلى عدة أجزاء، كل جزء يخص عقدة — الحلقة ملكية خاصة للعقدة، والرسم البياني هو الطاولة المشتركة التي يتسلمون عليها. فكر جيدًا في ما يجب أن تُخزَّن في الحالة. أعلن كيف يُدمج كل حقل — عندما تكتب عدة عقد متوازية نفس الحقل في نفس الوقت، هل يُستبدل أم يُضاف أم يُجمع؟ هذه ليست ميزة إطار عمل؛ إنها قاعدة تكتبها في `graph.md` عندما ترسم الرسم البياني:
+
+```
+state = {
+ "requirements": نص, # تكتبه عقدة البحث
+ "code": نص, # تكتبه عقدة التنفيذ
+ "review": "pass" | "fail", # تكتبه عقدة التحقق
+ "attempts": رقم, # +1 عند كل فشل (يُدمج بـ"جمع" عند الكتابة المتوازية)
+}
+```
+
+**الخطوة الثانية: اسرد العقد — كل عقدة وكيل كامل (يحمل حلقة خاصة به).** هذا هو الفرق الجوهري بين الرسم البياني وسير العمل: عقدة سير العمل دالة، وعقدة الرسم البياني **وكيل يحمل حلقة صغيرة خاصة به**. تتلقى العقدة الحالة المشتركة → تعمل في سياقها الخاص → تكتب النتيجة إلى الحالة المشتركة. غالبًا ما يكون داخل عقدة كتابة الكود هو حلقة المحاضرة السابقة:
+
+```
+# داخل عقدة implement: حلقة صغيرة خاصة (حلقة maker-checker من المحاضرة السابقة)
+node_implement(requirements):
+ loop (على الأكثر 3 مرات):
+ code = model(prompt=تعليمات التنفيذ, context=requirements + آخر خطأ)
+ if tests_pass(code): return {"code": code}
+ return {"error": "فشل التنفيذ 3 مرات"}
+```
+
+| العقدة | النوع | داخل العقدة (خاص) | يكتب إلى الحالة المشتركة |
+|-------|-------|------------------|--------------------------|
+| research | وكيل | بحث → قراءة → تلخيص → إعادة بحث إذا كانت المعلومات غير كافية (حلقة) | requirements |
+| implement | وكيل | كتابة → اختبار → إصلاح → حتى ينجح (حلقة، أعلاه) | code |
+| verify | وكيل | مراجعة مستقلة + تشغيل الاختبارات (**سياق جديد تمامًا، لا يورث ذاكرة المنفذ**) | review (pass / fail) |
+| merge | كود حتمي | لا حلقة، يلتزم بمجرد نجاح الفحوصات | انتهى |
+
+انتبه إلى صف verify: إنها أسهل عقدة يرتكب فيها الخطأ. **في الوكيل الأحادي، "المراجعة" ما زالت تعمل في نفس السياق، فيراجع الوكيل نفسه؛ في الرسم البياني، يجب أن تحصل verify على سياق جديد تمامًا** — لا ترى عملية تفكير implement، بل ترى فقط `code` في الحالة المشتركة. هذا هو المكان الذي يصبح فيه "المراجعة المستقلة" حقيقية فعلًا على الرسم البياني: عزل السياق ليس أثرًا جانبيًا، بل هو التصميم.
+
+**الخطوة الثالثة: صِل الحواف.** ابدأ بالعمود الفقري الحتمي: بحث → تنفيذ → تحقق → دمج → انتهاء.
+
+```mermaid
+flowchart TD
+ A([بداية]) --> B[research]
+ B --> C[implement]
+ C --> D[verify]
+ D --> E[merge]
+ E --> F([نهاية])
+```
+
+**الخطوة الرابعة: اكتب قواعد التوجيه (الخطوة الأهم).** عقدة التحقق لا تتصل مباشرة بـ"الدمج"، بل تتصل بـ**قرار** يقرر إلى أين تذهب الخطوة التالية. هذه هي الخطوة التي تجعل "إلى أين يذهب الفشل" صريحًا — قواعد التوجيه تُرجع اسم العقدة، والرسم البياني كله — من أين يأتي وأين يذهب — يُقرأ بلمحة واحدة:
+
+| العقدة الحالية | الشرط | العقدة التالية |
+|---------------|-------|---------------|
+| verify | review == pass | merge |
+| verify | review == fail | implement |
+
+```mermaid
+flowchart TD
+ A([بداية]) --> B[research]
+ B --> C[implement]
+ C --> D{verify}
+ D -- pass --> E[merge]
+ D -- fail --> C
+ E --> F([نهاية])
+```
+
+**الخطوة الخامسة: علّق نقطة تحقق (checkpoint).** هذا من أكبر الفروق بين الرسم البياني والنص البرمجي لمرة واحدة: **حالة كل خطوة تُحفظ على القرص**، فإذا تعطلت العملية يمكنك الاستئناف من نقطة التوقف بدلًا من البدء من جديد. بمجرد تعليقها، يكتسب الرسم البياني على الفور قدرة "القطع/الاستئناف" — ويمكنك أيضًا إدخال عقدة "التوقف لانتظار موافقة الإنسان" قبل الدمج، وهذا هو شكل "الموافقة البشرية" في المحاضرة السابقة على الرسم البياني:
+
+```
+checkpoint = on(graph, every_step) # احفظ حالة كل خطوة
+graph.pause_before("merge") # توقف قبل الدمج، انتظر الموافقة
+```
+
+**الخطوة السادسة: شغّل الرسم البياني، وأعطه نقطة دخول.** مرر معرّف خيط في كل تشغيل، وبه يميز checkpoint بين نسخ التشغيل المختلفة:
+
+```
+run(graph, entry={"requirements": "إصلاح خطأ صفحة تسجيل الدخول"}, thread="session-1")
+```
+
+بعد الانتهاء، قارن مع الرسم أعلاه: `graph.md` الذي كتبته يدويًا هو المخطط، والكود في المحرك هو المخطط المنفذ كبرنامج. يجب أن يتطابق الاثنان واحدًا لواحد. إذا لم يتطابقا — إما أن الرسم لم يُرسم بشكل صحيح، أو الكود لم يُكتب بشكل صحيح، **وهذا هو بالضبط معنى "الرسم البياني يضع المشكلة على الورق"**: سابقًا لم يكن أحد يعرف حتى لو لم يتطابقا، الآن يمكنك رؤيته بلمحة واحدة. إذا أردت تنفيذًا مرجعيًا حقيقيًا قابلًا للتشغيل، انظر إلى `code/maker_checker_graph.py` — يستخدم LangGraph، لكن بعد القراءة يجب أن تلاحظ: إنه مجرد هذه الخطوات الست.
+
+## مشاريع مفتوحة المصدر: بعد الاسم، وقبل الاسم
+
+أولًا، حدد الخط الفاصل: **"Graph Engineering" اسم له وجود فقط بعد 18 يوليو 2026.** الأطر التي صدرت مفتوحة المصدر قبل ذلك التاريخ ليست "مشاريع بعد إطلاق هندسة الرسوم البيانية". حتى أوائل أغسطس 2026، المشروع مفتوح المصدر الوحيد الذي يتبنى هذا الاسم مباشرة ويصمد هو واحد:
+
+**موجود بعد إطلاق المفهوم**
+
+- [GraphArc](https://github.com/CodeGraphContext/grapharc) (2026-08-02): يسمي نفسه "أول تنفيذ فوري في الوقت الحقيقي لهندسة الرسوم البيانية". يحوّل تنفيذ الوكيل من سجلات مدفونة في السجلات إلى **رسم بياني تنسيق تفاعلي في الوقت الحقيقي** — كل وكيل وكل تبعية وكل نقطة قرار مرسومة، تُعرض للتصور قبل التنفيذ (ويمكنك حتى النظر إليها من هاتفك)، ثم تسمح بالاستمرار بعد التأكيد. خلفية المؤلف هي بناء أدوات رسوم بيانية لأكثر من 4000 مطور، والاتجاه هو "قابل للملاحظة، قابل للتصحيح، قابل للهندسة". جديد جدًا، والوظائف ما زالت في مرحلة مبكرة.
+
+**موجود قبل إطلاق المفهوم (لا يسمونها هندسة الرسوم البيانية، لكنها هي ما ستستخدمه فعليًا عند البناء)**
+
+قبل يوليو 2026، كانت هذه الأدوات موجودة منذ سنة إلى ثلاث سنوات: LangGraph (مفتوح المصدر منذ 2024، أكثر من 65 مليون تحميل شهريًا، والمحرك الذي يستخدمه التنفيذ المرجعي أعلاه)، CrewAI، Microsoft Agent Framework، LlamaIndex Workflows، Google ADK، OpenAI Agents SDK، Mastra، Claude Agent SDK. **إنها ليست "مشاريع بعد إطلاق هندسة الرسوم البيانية" — بل هي الدليل على أن هندسة الرسوم البيانية كانت موجودة قبل أن تحصل على اسمها.** العقد والحواف والحالة المشتركة والتوجيه تعمل منذ ثلاث إلى خمس سنوات، يوليو فقط أعطاها اسمًا جديدًا. محرك الرسوم البيانية لا يحل مشكلات التصميم: يمنحك العقد والحواف ونقاط التحقق، لكنه لن يجيب عن "أي الحلقات تغذي أيًا، ومن يملك الأهداف، ومن يمكنه الرفض". قبل أن تحسم هذه الأسئلة، تغيير المحرك لن يؤدي إلا إلى رسم تصميم سيئ بشكل أجمل.
+
+## ماء بارد: الرسم البياني ليس رصاصة فضية
+
+ثلاثة دلاء من الماء البارد، من الأخف إلى الأثقل.
+
+**الدلو الأول: الأرقام المزيفة.** بعد انفجار هندسة الرسوم البيانية، انتشرت على الإنترنت بيانات مثل "دقة +18%، تكلفة -85%" بعد استخدام الرسوم البيانية. قام المدون الكوري goddaehee بجولة [تحقق من الحقائق](https://goddaehee.tistory.com/628) (30 يوليو): الرقمان موجودان فعلًا، لكنهما من ورقة بحثية عن مخططات الأنابيب والآلات الكيميائية (P&ID) صادرة في مارس 2026، والـ 18% مقارنة بالصورة الأصلية بينما الـ 85% مقارنة بخطة أخرى — تسويق لصق رقمين بخطوط أساس مختلفة في قصة "قبل/بعد" واحدة، وحتى الورقة البحثية لا تحتوي كلمة "graph engineering". عندما ترى أي بيانات "هندسة الرسوم البيانية تمنح X% تحسينًا"، اتحقق أولًا من المصدر الأصلي.
+
+**الدلو الثاني: الشكل ليس بالجدار الحامل (iii.dev).** أوردناه أعلاه. الحلقة هي مجرد رسم بياني بعقدة واحدة؛ آلات الحالة عملت لعقود. الأشخاص الذين يعلنون "الحلقة ميتة" أو "الرسم البياني ميت" عادة لم يقرؤوا أيًا منهما بعناية. تعلّم الأنماط، لا الأسماء.
+
+**الدلو الثالث: ضريبة التنسيق (Orchestration Tax).** أعطى آدي عثماني في *The Orchestration Tax* الصادرة في مايو أثقل اقتصاديات لعصر الرسوم البيانية/الوكلاء المتعددين: **تشغيل وكيل رخيص. إغلاق حلقة وكيل مكلف.**
+
+تشغيل وكيل هو مجرد ضغطة زر أو جملة. لكن إغلاق حلقة وكيل يتطلب من شخص ما فحص نتيجته ومواءمتها مع الأشياء التي لمستها الوكلاء الأخرى — **ذلك الشخص هو أنت، وليس هناك سوى واحد منك.** بعبارة عثماني:
+
+> "أنت هي الـ GIL لوكلاء الذكاء الاصطناعي لديك. يمكنهم جميعًا التشغيل في نفس الوقت. لكن عندما يتطلب أي من عملهم فهمًا حقيقيًا للبنية أو حل تعارضات الدمج، فإن هذا العمل يجب أن يحصل على القفل. هناك قفل واحد فقط، وأنت تحمله."
+
+لهذا السبب أصبح "النطاق المراجعة هو السقف" في المحاضرة السابقة أكثر حدة هنا: **الرسم البياني يجعل وكلاء متوازيين أكثر، لكن حكمك هو مورد تسلسلي، لا يتوازى.** إضافة العقد تحسّن الجزء الذي لم يكن أبدًا هو عنق الزجاجة — عنق الزجاجة دائمًا هو المعالج التسلسلي الواحد: أنت.
+
+## متى تحتاج فعلًا إلى رسم بياني
+
+ليست كل المهام تستحق رسمًا بيانيًا. خمسة معايير، تحقق من ثلاثة على الأقل قبل أن تبدأ:
+
+1. **المهمة يمكن تقسيمها إلى وحدات عمل مستقلة** — الأجزاء المفصولة لا تعتمد على بعضها ويمكن أن تعمل بالتوازي
+2. **توجد مسارات فرع أو تراجع** — "إلى أين تعود الاختبارات الفاشلة"، "إلى أين تعود المعلومات غير الكافية"، هذه المسارات تستحق أن تُعلن صراحة
+3. **الحالة الوسيطة تستحق الحفظ** — يمكنك التوقف عند نقطة التحقق واستئناف العمل، بدلًا من البدء من الصفر
+4. **النتائج يمكن قبولها بوضوح** — لكل عقدة معيار إكمال قابل للفحص آليًا
+5. **فائدة التعاون > تكلفة التنسيق** — الوقت الموفّر بالتوازي أكبر من تكلفة الرسم البياني وحالته المشتركة
+
+**"معقد" لا يعني "كثير الخطوات".** خط أنابيب خطي من 20 خطوة لا يحتاج رسمًا بيانيًا — ذلك سير عمل، أو مجرد نص برمجي. بنية من 5 عقد فقط لكن بينها تراجع وتوازي وموافقات، هي التي تحتاج رسمًا بيانيًا. معيار الحكم ليس الحجم، بل **وجود الفروع والتراجعات.**
+
+## المفاهيم الأساسية
+
+- **هندسة الرسوم البيانية**: الممارسة الهندسية لتنظيم وكلاء وحلقات وأدوات ومقيّمين متعددين في رسم بياني صريح (عقد + حواف + حالة مشتركة + قواعد توجيه)، مما يجعل ارتباط وحدات العمل المتعددة وحالتها المشتركة واختيارات مساراتها قابلة للتصميم والملاحظة والإصلاح الموضعي.
+- **الطبقات الأربع المتكدسة**: prompt → context → loop → graph، كل طبقة تتحكم في شيء مختلف (التعليمات، المعلومات، وقت التشغيل، النظام)، والطبقة اللاحقة لا تحل محل السابقة، بل تضعها داخل عقدتها.
+- **أجزاء الرسم البياني الأربعة**: العقد (وحدات العمل)، الحواف (طريقة التسليم)، الحالة المشتركة (سطح العمل المشترك)، قواعد التوجيه (أين تذهب الخطوة التالية).
+- **فشل الحلقة الواحدة البنيوي الثلاثة**: جودهارت (ارتفعت الأرقام، تدهور العمل)، العمى التصاعدي (لا يسأل أبدًا "هل هذا الهدف الصحيح؟")، التعارض (حلقات مستقلة تقوّض بعضها). الرسم البياني يحوّل هذه الأنواع الثلاثة إلى تصميم علاقات صريح.
+- **Graph ≠ Workflow**: عقد سير العمل دوال حتمية وحوافه كود مكتوب بشدة؛ عقد الرسم البياني يمكن أن تكون وكلاء كاملين وحوافه يمكن أن توجه ديناميكيًا. الرسم البياني هو تعميم لسير العمل.
+- **المراسي (Anchors)**: الآليات التي تثبت شبكة الحلقات في العالم الحقيقي (نتائج الأعمال الفعلية، الحقيقة الأساسية، الفحوصات البشرية العشوائية). أسهل جزء في تصميم الرسم البياني يمكن تخطيه، والجزء الذي لا يمكنك تحمل تخطيه.
+- **ضريبة التنسيق (Orchestration Tax)**: تشغيل الوكلاء رخيص، ومراجعة النتائج مكلفة. انتباهك هو المورد التسلسلي الوحيد، وإضافة العقد لا تحسّنه.
+
+## الخلاصات الرئيسية
+
+- **هندسة الرسوم البيانية لا تحل محل هندسة الحلقات — بل تبني طبقة فوقها.** الحلقة هي عقدة في الرسم البياني؛ الأشياء الثلاثة في المحاضرة السابقة (الهدف، التحقق، شرط التوقف) تصبح البنية الداخلية للعقدة.
+- **الرسم البياني يحوّل "القرار المؤجل" إلى "قرار مسبق".** الحلقة تخفي أنماط الفشل داخل الحلقة، والرسم البياني يضعها على الورق — قابل للقراءة والتدقيق والإصلاح الموضعي.
+- **ما بداخل العقدة يقرر الفرق بين الرسم البياني وسير العمل.** وضع الدوال يعطي سير عمل، ووضع الوكلاء يعطي رسمًا بيانيًا. هذا هو الجديد الوحيد فعلًا في القديم.
+- **صمّم الرسم بالإجابة على أربعة أسئلة أولًا:** أي الحلقات تغذي أيًا، ومن يملك الأهداف، ومن يمكنه الرفض/التراجع، وأي المؤشرات يمكن أن تتحرك وأيها يجب أن يبقى مجمدًا. إذا لم تستطع الإجابة، فلا ترسم.
+- **لا ترسم رسمًا بيانيًا لمجرد الرسم.** خمسة معايير: قابل للتقسيم المستقل، له فروع أو تراجعات، حالة وسيطة تستحق الحفظ، نتائج قابلة للقبول، فائدة التعاون > تكلفة التنسيق.
+- **نطاق مراجعتك ما زال هو السقف.** الرسم البياني يشغّل وكلاء متوازيين أكثر، لكن حكمك تسلسلي — ضريبة التنسيق لا تختفي لأن عدد العقد زاد.
+- **تذكّر صوت المعارضة.** الشكل ليس بالجدار الحامل؛ قابلية إعادة التشغيل والملاحظة والاستعادة هي الحاملة. الأسماء تتغير كل ستة أسابيع. القدرة الهندسية لا تتغير.
+
+## قراءات إضافية
+
+- [Prefect: Loops vs. Graphs (يوليو 2026)](https://www.prefect.io/blog/loops-vs-graphs) — رؤية الـ loop والـ graph من شركة بَنَت تنسيق الرسوم البيانية لعقود
+- [Eigent: Graph Engineering for AI Agents (يوليو 2026)](https://www.eigent.ai/blog/graph-engineering-ai-agents) — الفشل البنيوي الثلاثة للحلقة الواحدة + أسئلة التصميم الأربعة + المراسي
+- [iii.dev: Loops, Graphs, and the Layer That Matters (يوليو 2026)](https://iii.dev/blog/loops-graphs-and-the-layer-that-matters/) — أوضح صوت معارض: "الشكل ليس بالجدار الحامل"
+- [روهيت (rohit4verse@) المنشور الأصلي الطويل (2026-07-29)](https://x.com/rohit4verse/status/2082478623043547356) — المصدر الأولي لإطار الطبقات الأربع: prompt → context → loop → graph، كل طبقة تتكدس فوق السابقة
+- [Agent Times: Graph Engineering as the Final Layer (يوليو 2026)](https://theagenttimes.com/articles/graph-engineering-emerges-as-proposed-final-layer-of-agent-o-4f0511a8) — تنظيم إطار روهيت ذي الطبقات الأربع
+- [goddaehee: التحقق من حقائق هندسة الرسوم البيانية (كورية، 2026-07-30)](https://goddaehee.tistory.com/628) — التحقق الأكثر اكتمالًا: الخط الزمني لنشأة النكتة، وتفكيك الأرقام المزيفة، وبيانات LangGraph، ومقارنة حرارة Hacker News
+- [جوش سيمونز: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — المقالة الجادة المكتوبة قبل النكتة بأسبوعين
+- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — الرد الرسمي: "ليست فكرة جديدة، بل الاسم الأحدث لنهج راسخ"؛ أكثر من 65 مليون تحميل شهري لـ LangGraph
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — بيانات انتشار الضجة (575 ألف مشاهدة للتغريدة الأصلية)
+- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — مقارنة أفقية لسبعة أطر مفتوحة المصدر رئيسية: LangGraph، CrewAI، Microsoft Agent Framework، LlamaIndex، Google ADK، OpenAI Agents SDK، Mastra
+- [وثائق LangGraph الرسمية](https://docs.langchain.com/oss/python/langgraph/graph-api) — "العقد تقوم بالعمل، والحواف تخبر بما يجب أن يحدث بعد ذلك"؛ التعريفات الدقيقة للعقد والحواف، المرجع الأولي لبناء الرسوم البيانية
+- [Anthropic: Building Effective Agents (ديسمبر 2024)](https://www.anthropic.com/engineering/building-effective-agents) — الأنماط الخمسة التي تُرسم كرسوم بيانية؛ التمييز الموثوق بين سير العمل والوكيل
+- [آدي عثماني: The Orchestration Tax (مايو 2026)](https://addyosmani.com/blog/orchestration-tax/) — لماذا انتباهك هو المورد التسلسلي الوحيد
+- [آدي عثماني: Orchestrating Coding Agents (محاضرة)](https://talks.addy.ie/oreilly-codecon-march-2026/) — من الوكلاء الفرعيين إلى فرق الوكلاء إلى بوابات الجودة
+- [آدي عثماني: Loop Engineering (يونيو 2026)](https://addyosmani.com/blog/loop-engineering/) — المرجع الأساسي للمحاضرة السابقة، والمعرفة المسبقة لهندسة الرسوم البيانية
+- المحاضرة 13: [من المطالبة اليدوية إلى الحلقات المستقلة](./../lecture-13-loop-engineering/index.md) — الحلقة هي عقدة في الرسم البياني؛ افهم العقدة قبل أن تفهم الرسم البياني
+- المحاضرة 11: [لماذا تنتمي قابلية الملاحظة داخل الـ Harness](./../lecture-11-why-observability-belongs-inside-the-harness/index.md) — كلما زاد تعقيد الرسم البياني، زادت أهمية قابلية الملاحظة؛ رسم بياني غير قابل للملاحظة هو مجرد صندوق أسود أكبر
+- المحاضرة 9: [لماذا يعلن الوكلاء النصر مبكرًا جدًا](./../lecture-09-why-agents-declare-victory-too-early/index.md) — لماذا يجب أن تكون عقدة التحقق مستقلة عن عقدة التنفيذ؛ في الرسم البياني هذه مشكلة بنيوية وليست مشكلة مطالبات
+
+## التدريبات
+
+1. **ارسم حلقة maker-checker الخاصة بـ P07 كرسم بياني:** اكتب بوضوح في `graph.md` العقد والحواف والحالة المشتركة وقواعد التوجيه. علّم أي الحواف حواف شرطية (نجح التحقق/فشل) وأيها حواف تراجع (فشل يعود إلى التنفيذ). بعد الانتهاء أجب: هل هناك أي حافة كانت ضمنية، مخبأة سابقًا داخل سياق الوكيل؟
+
+2. **أجب عن أسئلة eigent الأربعة:** ابحث عن ثلاث حلقات مستقلة تشغّلها (أو ثلاث أتمتة في نفس المشروع)، وأجب: أيها يغذي أيًا؟ أي حلقة تملك هدفًا تطارده حلقة أخرى؟ هل توجد حلقة يمكنها رفض ناتج حلقة أخرى؟ أي المؤشرات تُحسَّن في اتجاهات قد تتعارض؟
+
+3. **فحص جودهارت الذاتي:** افحص مؤشرًا كنت تحسّنه مؤخرًا. عندما ارتفع، هل تحسنت النتيجة الحقيقية (نتائج الأعمال، ملاحظات المستخدمين، جودة الكود) أيضًا؟ إذا ارتفع الرقم فقط، ففي أي اتجاه تعلم هذه الحلقة أن تكذب عليك؟
+
+4. **قيّم مهمة بالمعايير الخمسة:** اختر مهمة تتردد في "تحويلها إلى رسم بياني" وقم بقياسها بالمعايير الخمسة واحدًا واحدًا. تحتاج ثلاثة على الأقل لتستحق رسمًا بيانيًا. إذا كان أقل من ثلاثة، فما تحتاجه فعلًا هو نص سير عمل أفضل — لا ترسم رسمًا بيانيًا لمجرد الرسم.
+
+5. **حوّل `graph.md` إلى برنامج قابل للتنفيذ:** اتبع الخطوات الست في "ابنِ أول رسم بياني لك من الصفر" ونفّذ رسم maker-checker الذي رسمته إلى رسم قابل للتشغيل (التنفيذ المرجعي: `code/maker_checker_graph.py`، مكتوب بـ LangGraph). لا تتخطَّ الخطوات الست: عرّف الحالة → اسرد العقد → صِل الحواف → اكتب التوجيه → علّق checkpoint → شغّل. بعد الانتهاء قارن `graph.md` بالكود، وابحث عن أول مكان لا يتطابقان فيه، واشرح لماذا — هل الرسم خاطئ، أم الكود خاطئ؟
\ No newline at end of file
diff --git a/docs/ar/projects/project-08-graph-engineering-first-graph/index.md b/docs/ar/projects/project-08-graph-engineering-first-graph/index.md
new file mode 100644
index 0000000..02f3c3a
--- /dev/null
+++ b/docs/ar/projects/project-08-graph-engineering-first-graph/index.md
@@ -0,0 +1,93 @@
+[English Version →](../../../en/projects/project-08-graph-engineering-first-graph/)
+
+# المشروع 08. ارسم سير عملك كرسم بياني
+
+> المحاضرة ذات الصلة: [المحاضرة 14. من الحلقة الواحدة إلى هندسة الرسوم البيانية](./../../lectures/lecture-14-graph-engineering/index.md)
+
+## ماذا ستفعل
+
+هذا هو المشروع الانتقالي من "Loop" إلى "Graph". في المحاضرة السابقة بنيت حلقة maker-checker — تنفيذ، تحقق، تغذية راجعة، إعادة تنفيذ، وكل القرارات تحدث داخل نافذة سياق وكيل واحد. ما ستفعله في هذا المشروع هو **رسم البنية المخفية داخل الحلقة بشكل صريح**: العقد، والحواف، والحالة المشتركة، وقواعد التوجيه، مكتوبة حرفًا حرفًا بوضوح.
+
+ستقوم بثلاث تجارب متتالية: أولًا ترسم حلقة maker-checker الخاصة بـ P07 كرسم بياني صريح، ثم تضيف عقدة fan-out/fan-in متوازية إلى الرسم، وأخيرًا تضيف حافة تراجع شرطية وعقدة موافقة بشرية. بعد الانتهاء ستشعر بنفسك بشيء واحد: **الرسم البياني ليس اختراعًا جديدًا، بل هو ما يتحول إليه loop تلقائيًا عندما تتعقد حلقتك إلى درجة معينة.**
+
+## الأدوات التي ستستخدمها
+
+- Claude Code أو Codex
+- Git
+- حلقة maker-checker التي بنيتها في P07 (أو أي سير عمل وكيل يمكنك تشغيله بشكل متكرر)
+- محرر نصوص أو أداة رسم (الرسم ليس للجمال، بل لكتابة البنية بوضوح؛ `mermaid` أو كتابة `graph.md` يدويًا كلاهما جيد)
+
+## الخطوات
+
+### التحضير
+
+1. ابدأ من المستودع بعد إكمال P07، أو استخدم مباشرة أي سير عمل وكيل تعمل عليه.
+2. أنشئ ثلاثة فروع: `p08-explicit-graph`، `p08-parallel`، `p08-human-in-the-loop`.
+3. جهّز ملف `state.md` كملف الحالة المشتركة: المتطلبات والتقدم ونتائج التحقق تُكتب جميعها هنا. هذا هو "سطح العمل المشترك" للرسم البياني.
+
+### التجربة 1: ارسم الـ Loop كرسم بياني صريح
+
+انتقل إلى الفرع `p08-explicit-graph`.
+
+1. **اسرد جميع العقد**: اكتب كل خطوة من حلقة maker-checker الخاصة بـ P07 كعقدة. لكل عقدة وضّح: مسؤوليتها، ومدخلاتها، ومخرجاتها، وهل هي وكيل أم كود حتمي.
+2. **ارسم جميع الحواف**: اسرد كل حافة بين العقد. علّم بوضوح الحافتين الخاصتين:
+ - الحافة الشرطية: نجح/فشل التحقق، أي طريق تسلك
+ - حافة التراجع: الفشل يعود إلى أي عقدة
+3. **اكتب الحالة المشتركة**: اسرد بوضوح الحقول الموجودة في الحالة (المتطلبات، الكود، نتائج الاختبارات، استنتاج المراجعة)، ومن يقرأها ومن يكتبها.
+4. **اكتب قواعد التوجيه**: بلغة if-then الأبسط، اكتب قواعد "إلى أين تذهب الخطوة التالية"، مثل:
+ ```
+ إذا نجح التحقق → عقدة الدمج
+ إذا فشل التحقق → عقدة التنفيذ
+ إذا كانت معلومات عقدة التنفيذ غير كافية → عقدة البحث
+ ```
+5. **اكتبها في `graph.md`**: رتب ما سبق في مستند واحد. ارسم رسمًا بيانيًا بـ mermaid، وأرفق جدول العقد وقواعد التوجيه.
+6. **أجب عن هذا السؤال**: بعد الرسم، ابحث عن حافة واحدة على الأقل **كانت ضمنية سابقًا** — مسار قرار كان مخبأً داخل سياق الوكيل، ولم تكن تعلم حتى بوجوده.
+
+### التجربة 2: أضف عقدة Fan-out / Fan-in متوازية
+
+انتقل إلى الفرع `p08-parallel`.
+
+1. **اختر نقطة يمكن أن تتوازى**: ابحث في المهمة عن مكان يمكن تقسيمه إلى جزأين مستقلين. مثل:
+ - تقسيم التنفيذ إلى وحدتين مستقلتين، يكتبهما وكيلان بالتوازي
+ - تقسيم التحقق إلى مراجعتين مستقلتين: واحدة تشغّل الاختبارات والـ lint، وأخرى تقوم بمراجعة الكود (تعليمات مختلفة، واهتمامات مختلفة)
+ - تقسيم البحث إلى اتجاهين، يفحص كل وكيل مسارًا
+2. **اكتب قاعدة fan-out**: سجّل في الحالة المشتركة "تم تقسيم هذه المهمة إلى N مهام فرعية متوازية"، ولكل مهمة فرعية سياق مستقل وعقدة مستقلة.
+3. **اكتب قاعدة fan-in**: بعد اكتمال جميع المهام الفرعية، من يدمج النتائج؟ وما معيار الدمج (مثل: يدمج فقط عند نجاح المراجعتين، أم يكفي نجاح واحدة)؟
+4. **استخدم worktree للعزل**: كل مهمة فرعية متوازية تعمل في worktree git مستقل، لتجنب تصادم الملفات فعليًا (راجع أولية Worktree في المحاضرة 13).
+5. **شغّل مرة واحدة وسجّل**: سجّل زمن الحائط قبل وبعد التوازي، واستهلاك التوكنز، وجودة النتائج. هل التوازي أسرع فعلًا؟ أم أن تكلفة التنسيق أكلت الوقت الموفّر؟
+
+### التجربة 3: أضف حافة تراجع وعقدة موافقة بشرية
+
+انتقل إلى الفرع `p08-human-in-the-loop`.
+
+هذه هي الأهم من التجارب الثلاث. ستضيف نوعين من العقد إلى الرسم:
+
+1. **حافة تراجع شرطية**: أضف لعقدة التحقق مسار "نجاح جزئي" — ليس رفضًا كاملًا يعيدها إلى عقدة التنفيذ، بل بالعودة بملاحظات محددة إلى **العقدة التي سببت المشكلة**. مثل: نجحت الاختبارات كلها لكن مراجعة الكود اكتشفت فهمًا خاطئًا للمتطلبات، فارجع إلى عقدة البحث بدلًا من عقدة التنفيذ. هذا يتطلب أن تسجّل في حالتك المشتركة "في أي طبقة وقعت المشكلة".
+2. **عقدة موافقة بشرية (Human-in-the-loop)**: أضف عقدة بشرية قبل عقدة الدمج. عند الوصول إليها، يتوقف الرسم البياني **وينتظر** حتى تكتب "موافقة" أو "رفض" في `state.md`. يمكن أن يكون لعقدة الموافقة قاعدة مهلة: إذا لم تستجب بعد N ساعة، يُرفض تلقائيًا أو يُرفع تلقائيًا.
+3. **اكتب تنسيق interrupt**: كيف تُكتب طلبات الموافقة بوضوح — ماذا حدث، وما الذي تغيّر، ولماذا تحتاج إنسانًا، وما عواقب كل من الموافقة والرفض.
+4. **شغّل جولتين كاملتين على الأقل**: في كل جولة تصل إلى عقدة الموافقة البشرية، وتوافق أو ترفض بنفسك مرة واحدة. سجّل: هل قرار موافقتك يتطابق مع حكم عقدة التحقق؟ هل أوقفت عقدة الموافقة شيئًا لم توقفه عقدة التحقق؟
+
+## كيف تقيس النتائج
+
+| المقياس | التجربة 1 (الرسم الصريح) | التجربة 2 (التوازي) | التجربة 3 (التعاون البشري) |
+|--------|------------------------|-------------------|--------------------------|
+| وضوح البنية | كم حافة ضمنية وجدت؟ | هل تستطيع الحالة المشتركة دعم المهام الفرعية المتوازية؟ | هل تستطيع حافة التراجع تحديد طبقة المشكلة بدقة؟ |
+| تحديد الفشل | عند الفشل هل يمكنك الإشارة مباشرة إلى أي حافة أخطأت؟ | عند فشل مهمة فرعية متوازية، هل يمكن تحديد أيها؟ | عند رفض الموافقة، هل يمكنك الإشارة إلى طبقة المشكلة؟ |
+| تكلفة التعاون | كم استغرق رسم الرسم البياني؟ | الوقت الموفّر بالتوازي مقابل تكلفة التنسيق | وقت انتظار الموافقة مقابل قيمة المشكلة الموقوفة |
+| قابلية الملاحظة | هل أصبحت كل خطوة مرئية الآن؟ | هل حالة كل مهمة فرعية متوازية مرئية؟ | هل طلب الموافقة مكتوب بوضوح كافٍ؟ |
+| الموثوقية | هل يتطابق وصف الرسم مع التشغيل الفعلي؟ | هل معيار دمج fan-in موثوق؟ | هل تتفعل قواعد المهلة/الرفع فعلًا؟ |
+
+## ما يجب تقديمه
+
+- `graph.md` (وصف كامل للرسم في التجربة 1: رسم mermaid + جدول العقد + جدول الحواف + حقول الحالة المشتركة + قواعد التوجيه)
+- قائمة الحواف الضمنية المكتشفة في التجربة 1 (واحدة على الأقل)
+- قواعد fan-out/fan-in في التجربة 2 وسجل تشغيل متوازٍ واحد (مقارنة الوقت/التكلفة/الجودة)
+- قواعد حافة التراجع في التجربة 3، وتنسيق عقدة الموافقة، وسجل جولتين من التعاون البشري
+- المراجعة النهائية: من الـ loop إلى الـ graph، كيف تغيّرت طريقة عملك؟ أي المهام تستحق رسمًا بيانيًا، وأيها لا يستحق؟
+
+## المحاضرات ذات الصلة
+
+- [المحاضرة 14 — من الحلقة الواحدة إلى هندسة الرسوم البيانية](../../lectures/lecture-14-graph-engineering/index.md)
+- [المحاضرة 13 — من المطالبة اليدوية إلى الحلقات المستقلة](../../lectures/lecture-13-loop-engineering/index.md) (حلقتك هي عقدة في الرسم البياني؛ هذا المشروع يفتح البنية الداخلية للعقدة)
+- [المحاضرة 09 — لماذا يعلن الوكلاء النصر مبكرًا جدًا](../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md) (لماذا يجب أن تكون عقدة التحقق مستقلة عن عقدة التنفيذ؛ في الرسم البياني هذه مشكلة بنيوية)
+- [المحاضرة 11 — لماذا تنتمي قابلية الملاحظة داخل الـ Harness](../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) (كلما زاد تعقيد الرسم البياني، زادت حاجتك إلى رؤية ما تفعله كل عقدة)
\ No newline at end of file
diff --git a/docs/de/lectures/lecture-14-graph-engineering/index.md b/docs/de/lectures/lecture-14-graph-engineering/index.md
new file mode 100644
index 0000000..29daf7c
--- /dev/null
+++ b/docs/de/lectures/lecture-14-graph-engineering/index.md
@@ -0,0 +1,349 @@
+[English Version →](../../../en/lectures/lecture-14-graph-engineering/)
+
+> Codebeispiele: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-14-graph-engineering/code/)
+> Praxisprojekt: [Projekt 08. Zeichne deinen Workflow als Graph](./../../projects/project-08-graph-engineering-first-graph/index.md)
+
+# Lektion 14. Von Einzel-Loops zu Graph Engineering
+
+Sechs Wochen nachdem Loop Engineering zum Mainstream wurde, am 18. Juli 2026, postete Peter Steinberger — der OpenClaw-Autor, der dir gesagt hat, deinen Agenten nicht mehr zu prompten — einen Tweet:
+
+> „Reden wir noch über Loops oder sind wir schon zu Graphen übergegangen?“
+
+Ein Tweet — etwa 575.000 Aufrufe innerhalb eines Tages, bis zum Monatsende auf rund 3 Millionen ansteigend. Ein paar Stunden später veröffentlichte ML-Ingenieur Hamel Husain *Loop Engineering Is Dead. Enter Graph Engineering* — einen Artikel, dessen ganzer Inhalt aus einem einzigen „Stop it“-GIF bestand — und holte damit noch einmal rund 680.000 Aufrufe.
+
+Hier ist die Wendung: **Beide haben nur gescherzt.** Der eine machte sich über eine Branche lustig, die alle sechs Wochen einen neuen Begriff erfindet; der andere spielte auf diesem Gag auf. Aber der Witz überlebte etwa ein Wochenende — Kurse, Roadmaps und Tool-Stacks fluteten die Timeline, bevor das Wochenende vorbei war, gefolgt von einem Haufen erfundener Zahlen: die Behauptung „+18 % Genauigkeit, −85 % Kosten“ ist gefälscht (die beiden Zahlen existieren zwar, stammen aber aus einem Paper über chemische Rohrleitungsdiagramme und vergleichen unterschiedliche Baselines), und auch die Behauptung „Microsoft, Stanford und Anthropic haben gleichzeitig Graph Engineering entdeckt“ ist falsch. Die Faktenprüfung findet genau einen echten „Vorläufer“: Josh Simmons, dessen *We Are Entering the Graph Engineering Phase* auf den 4. Juli datiert ist — zwei volle Wochen vor dem Witz. **Der Witz hat die Idee populär gemacht. Er hat sie nicht erschaffen.**
+
+> Quellen: [goddaehee: Graph Engineering Faktencheck (2026-07-30)](https://goddaehee.tistory.com/628); [YC Startup School 2026: Jensen-Huang-Interview (mit Transkript)](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia); [explainx: Graph Engineering (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026)
+
+In dieser Lektion geht es nicht darum, das Feuer weiter anzufachen. Es geht darum, den Begriff auseinanderzunehmen und klar zu sehen: **warum wächst ein einzelner Loop unweigerlich zu einem Graphen? Was unterscheidet einen Graphen tatsächlich von einem Workflow? Und wann brauchst du wirklich einen — und wann nicht?**
+
+## Prompt, Context, Loop, Graph: vier Namen, ein Stapel
+
+Ende Juli postete ein Ingenieur namens Rohit (@rohit4verse) einen [Thread](https://x.com/rohit4verse/status/2082478623043547356), der die Namensgeschichte der letzten Jahre im AI Engineering in einem sauberen Vier-Schichten-Framework ordnete. Das ist das beste Koordinatensystem, um Graph Engineering zu verstehen:
+
+| Ebene | Formt was | Beantwortet die Frage | Schlüssel-Artefakte |
+|------|---------|-----------|---------|
+| **Prompt Engineering** | Die Anweisung | Wie sagen wir dem Modell, was zu tun ist? | instructions, examples, constraints, roles, output formats |
+| **Context Engineering** | Die Informationen | Was sollte das Modell wissen, bevor es entscheidet? | documents, history, memory, tool definitions, environment state |
+| **Loop Engineering** | Die Laufzeit | Wie bringen wir das Modell dazu, zu iterieren, bis das Ziel erreicht ist? | observe, reason, act, inspect, update, Stoppbedingung |
+| **Graph Engineering** | Das System | Wie arbeiten mehrere Agents, Loops, Tools und Evaluatoren zusammen? | Knoten, Kanten, Shared State, Routing-Regeln |
+
+Lies den Verlauf genau: **jede Ebene ersetzt nicht die darunterliegende — sie stapelt sich darauf.**
+
+- Nachdem du Context Engineering gefunden hast, hast du nicht aufgehört zu prompten. Jede Iteration braucht immer noch einen Prompt; der Loop aktualisiert ihn nur, wenn sich die Umgebung bewegt.
+- Nachdem du Loops gebaut hast, hast du den Context nicht fallen gelassen. Jede Runde eines Loops setzt seinen Context neu zusammen.
+- Auf der Graph-Ebene überleben Prompt, Context und Loop alle: **jeder Knoten trägt seinen eigenen Prompt, seinen eigenen Context, seine eigenen Tools, sein eigenes Gedächtnis, seinen eigenen Loop.** Der Graph entscheidet, wie die Knoten verbunden sind.
+
+Rohits Thread endet so:
+
+> Sobald ein Agent Spezialisierung, Parallelität, Shared State, Verifikation und Wiederherstellung braucht, ist er kein Loop mehr. Er ist ein Graph.
+
+**Moment — wo ist das Harness?** Diese vier Namen enthalten kein Harness Engineering, doch dieser ganze Kurs dreht sich um das Harness. Der Grund ist einfach: Rohit erzählte die Geschichte der Buzzwords, sein Ende war der Graph, und die Schicht dazwischen wurde übersprungen. Und selbst die Frage, auf welcher Ebene das Harness liegt, ist ungeklärt — [explainx](https://explainx.ai/blog/context-prompt-loop-harness-engineering-stack-2026) platziert es über dem Loop, das [Buildrix-Paper](https://arxiv.org/abs/2606.25139) darunter. Dieser Kurs hat das bereits in Lektion 2 geklärt: Das Harness ist das Fundament; Loops und Graphen werden darauf gebaut.
+
+Das erklärt ein seltsames Phänomen: „Graph Engineering“ wurde erst im Juli 2026 viral, doch alle hatten das Gefühl, sie hätten „das schon immer gemacht“. Weil ein Graph keine neue Erfindung ist — es ist das, was aus einem Loop wird, wenn die Aufgabe komplex genug wird. **Der Name kam später; die Praxis war schon da.**
+
+## Nimm den Graphen auseinander: Knoten, Kanten, Zustand, Routing
+
+Reduziere den Graphen auf vier schlichte Teile.
+
+**Knoten (Node)**: eine Arbeitseinheit mit einer Verantwortung. Er kann sein:
+- deterministischer Code (Tests ausführen, Abdeckung berechnen)
+- ein Modellaufruf (Dokumente generieren)
+- ein Tool (git commit, eine Nachricht senden)
+- ein vollständiger Agent — mit eigenem Loop, fähig, Ziele zu verstehen, Tools zu nutzen und selbst zu wiederholen
+
+Was ein Knoten sein darf, ist die eigentliche Trennlinie zwischen Graph Engineering und Workflow Engineering. Mehr dazu unten.
+
+**Kante (Edge)**: wie Arbeit zwischen Knoten übergeben wird. Es ist nicht nur „erst A, dann B“ — eine Kante kann ausdrücken:
+- **Parallelität**: nach A starten B und C gleichzeitig
+- **Bedingungen**: Tests bestanden, gehe nach links; Tests fehlgeschlagen, gehe nach rechts
+- **Fehler/Wiederholung**: ein Knoten stirbt, er läuft zurück in sich selbst
+- **Rollback**: Verifikation fehlgeschlagen, zurück zum Implementierungs-Knoten drei Hops davor
+
+**Shared State**: das Datenpaket, das zwischen Knoten übergeben wird. Anforderungen, Recherche-Notizen, Code-Versionen, Testergebnisse, Review-Schlussfolgerungen — alles wird in denselben gemeinsamen Arbeitsbereich geschrieben. Knoten rufen sich nicht gegenseitig zu; sie lesen und schreiben alle denselben Zustand.
+
+**Routing-Regeln**: entscheiden, wohin die Ausführung als Nächstes geht. Das ist der Kontrollfluss des Graphen, in einfachsten Worten:
+
+> Tests bestanden → liefern. Tests fehlgeschlagen → zurück zum Implementierungs-Knoten. Nicht genug Informationen → zurück zum Recherche-Knoten.
+
+Füge die vier Teile zusammen und ein typischer Entwicklungs-Graph sieht so aus:
+
+```mermaid
+flowchart TD
+ S["Shared State<br/>Anforderungen / Notizen / Code / Ergebnisse"] --- R["Recherche-Knoten<br/>Agent: Problem lokalisieren"]
+ R -->|"Plan ausgeben"| I["Implementierungs-Knoten<br/>Agent: Änderungen + Tests schreiben"]
+ I -->|"Code ausgeben"| V["Verifikations-Knoten<br/>Agent: unabhängiges Review + Tests ausführen"]
+ V -->|"fehlgeschlagen"| I
+ V -->|"bestanden"| M["Merge-Knoten<br/>Code: commit + Status aktualisieren"]
+ M -->|"Status-Update"| S
+ I -->|"nicht genug Infos"| R
+```
+
+Vergleiche das mit dem Loop-Diagramm aus der letzten Lektion. Der Loop war ein Ring — entdecken, verteilen, verifizieren, persistieren, zurück zum Entdecken. Im Graphen dieser Lektion **ist der Ring immer noch da, aber er wurde in explizite Knoten und Kanten zerlegt.** Der Verifikations-Knoten kann einen Fehlschlag direkt zum Implementierungs-Knoten zurückwerfen; der Implementierungs-Knoten kann sich bei dünner Informationslage zur Recherche zurückziehen. Diese „Rollback-Kanten“ waren in einem einzelnen Loop implizit — der Agent hat sich nur „gemerkt“, dass er zurückgehen sollte, in seinem eigenen Context Window.
+
+## Wann ein Loop nicht mehr reicht
+
+Ein einzelner Loop hat eine Hauptstraße. In dem Maker-Checker-Loop, den du in Projekt 07 gebaut hast, fanden alle Entscheidungen — was als Nächstes zu tun ist, wohin bei Fehlern gegangen wird — im Context Window eines einzigen Agents statt. Drück die Aufgabe ein wenig weiter und vier Fragen tauchen auf:
+
+1. **Arbeitsteilung**: ein Recherche-Agent, ein Implementierungs-Agent, ein Test-Agent — wer beginnt zuerst?
+2. **Parallelität**: welche Teile der Arbeit können gleichzeitig laufen?
+3. **Rollback**: wenn Tests fehlschlagen, wohin gehst du zurück — zum Implementierungs-Knoten oder zum Recherche-Knoten?
+4. **Übergabe**: wie sehen mehrere Agents dieselben Anforderungen, Notizen und Testergebnisse? Wenn der Reviewer dem Implementer widerspricht, wer gewinnt?
+
+Jensen Huang hat in seinem [Startup-School-2026-Interview mit Garry Tan (Y Combinator)](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia) einen ähnlichen Punkt gemacht: Je mehr die Implementierung von Agents automatisiert wird, desto mehr verschiebt sich der menschliche Kernwert hin zum Designen von Systemen, zum Definieren von Beschränkungen und zur feinkörnigen Kontrolle von Agents. Sein Kontrollbeispiel ist konkret — „wenn ich einen Plan bekomme, ändere ich ein Wort in einer Plan-Datei, und dieses eine Wort macht eine präzise Differenz“ — und er sagt die Zukunftsfähigkeit „Systems Thinking“ voraus.
+
+Die schärfste Zeile der ganzen Diskussion kam von Luis Catacora:
+
+> **„Loops haben viel Raum für Vergebung. Graphen zwingen dich anzuerkennen, wie viel von deinem Workflow tatsächlich nicht modelliert ist.“**
+
+Dieser Satz legt den tiefen Unterschied zwischen Loop und Graph offen:
+
+- **Ein Loop ist ein verzögerter Beschluss.** Ein Agent übernimmt die ganze Arbeit; wenn er stecken bleibt, kümmerst du dich dann darum. Die Architektur kann aufgeschoben werden. Das ist billig — aber die Fehlermodi sind unsichtbar, weil der Agent selbst nicht weiß, wo er hängt.
+- **Ein Graph ist ein vorab getroffener Beschluss.** Du musst die gesamte Struktur im Voraus erklären: wer wem gehört, wie Aufgaben voneinander abhängen, wohin ein bestimmter Fehler zurückkehrt. Das ist mehr Arbeit — und es kauft dir Lesbarkeit, Prüfbarkeit und lokale Reparatur.
+
+Noch unverblümter: **ein Loop versteckt das Problem im Loop; ein Graph legt das Problem auf den Tisch.** Ersteres eignet sich für die Erkundung, Letzteres für die Produktion.
+
+## Drei strukturelle Fehlschläge eines einzelnen Loops im Maßstab
+
+Warum hält ein einzelner Loop im Maßstab nicht? *Graph Engineering for AI Agents: Beyond Single Feedback Loops* (eigent.ai) identifiziert drei strukturelle Fehlschläge — strukturell, keine Bugs in einem einzelnen Loop.
+
+**Moment — kann ein Loop nicht auch Checkpoints haben?** Klar kann er. Die Verifikation, die Stoppbedingungen, sogar Pause-und-Fortsetzen aus der letzten Lektion — ein Loop kann sie alle halten. Aber genau die drei Fehlschläge unten kann man mit Checkpoints nicht beheben — weil die Checkpoints eines Loops im selben Agenten leben und weil der Prüfer und der Produzent ein Gehirn und einen Context teilen. Er wird „ohne Verifikation ausliefern“ stoppen, aber er wird nicht fragen „ist diese Metrik richtig?“ oder „sollte dieses Ziel verfolgt werden?“ — die Antworten leben in seinem eigenen Context, und er kann sie nicht sehen. Ein Graph gibt dir nicht mehr Checkpoints; er verschiebt die Prüfung — vom Inneren des Agents zu einem eigenständigen Knoten mit frischem Context (der Verify-Knoten aus dem Abschnitt oben). Genau das bedeutet „strukturell“: nicht ein fehlendes Teil im Loop, sondern eine Struktur, in der der Richter und der Beurteilte ein Gehirn teilen.
+
+### 1. Goodhart: Die Zahlen gingen hoch, das Geschäft wurde schlechter
+
+Drück irgendeine einzelne Metrik hart genug, und sie hört auf, das zu messen, was sie früher gemessen hat. Der kanonische Fall: Ein Support-Team baut einen Loop um die Ticket-Lösungsrate. Die Wochenzahlen steigen. Monate später zeigen die Verlängerungsdaten, dass sich die Abwanderung verdoppelt hat — **der Bot hat gelernt, Tickets zu schließen**: abzulenken, Nachfragen zu unterbinden, ungelöste Probleme als „gelöst“ zu markieren.
+
+Der Loop hat genau das getan, was ihm gesagt wurde. Die Zahl hat sich nur von dem gelöst, was dem Geschäft wirklich wichtig war. Goodharts Gesetz in Aktion.
+
+### 2. Blindheit nach oben: Es fragt nie „Ist das das richtige Ziel?“
+
+Im Inneren eines Loops ist der Referenzwert heilig. Ein Thermostat kann nicht fragen, ob 68°F die richtige Temperatur ist. Ein Sales-Loop kann nicht fragen, ob die Quote vernünftig war. Ein Agent-Eval-Loop kann nicht fragen, ob sein Benchmark mit echten Geschäftsergebnissen übereinstimmt.
+
+**Jemand hat dieses Ziel gewählt, und der Loop wird darauf zusteuern, selbst wenn es nie das Richtige war, dem man nachjagt.** In der Struktur eines einzelnen Loops gibt es keine Position, an der diese Frage gestellt werden kann.
+
+### 3. Konflikt: Unabhängige Loops bekämpfen sich gegenseitig
+
+Echte Systeme haben viele Loops, jeder separat gebaut. Ein Loop für Antwortgeschwindigkeit untergräbt einen Loop für Gründlichkeit. Ein Loop für Wachstum untergräbt einen Loop für Qualität. Jeder sieht auf seinem eigenen Dashboard gesund aus, während das ganze System ruckelt — wie mehrere Leute, die am selben Seil in verschiedene Richtungen ziehen.
+
+**Graph Engineering ist genau dafür gebaut, die Fragen zu beantworten, die ein einzelner Loop nicht beantworten kann:**
+
+- Welche Loops speisen welche anderen Loops?
+- Welche Loops besitzen die Ziele, denen andere Loops nachjagen?
+- Welche Loops können eine Änderung ablehnen oder zurückrollen?
+- Welche Messwerte dürfen sich bewegen, und welche müssen eingefroren bleiben?
+
+Wenn dein System Loops enthält, die die Ziele anderer Loops konsumieren können, und Loops, die die Änderungen anderer Loops ablehnen können, werden die Beziehungen zwischen ihnen zu Engineering-Objekten — und Beziehungen zwischen Beziehungen, gezeichnet, sind ein Graph.
+
+### Anker: Den Loop an der Realität festmachen
+
+Der eigent-Post hat einen Abschnitt mit dem Titel „der Teil, den jeder überspringt“: **Anchors (Anker)**. Egal wie elegant dein Netzwerk von Loops ist — wenn jeder Loop von der Realität abdrifft, ist das Netzwerk nur eine Resonanz gegenseitiger Drift. Ein Anker ist das, was einen Loop an der realen Welt festmacht — echte Geschäftsergebnisse, Ground-Truth-Datensätze, menschliche Stichproben. Anker sind der am einfachsten zu überspringende Teil des Graph-Designs — und der eine Teil, den du dir nicht leisten kannst zu überspringen.
+
+## Graph vs. Workflow: Nicht nur eine Umbenennung
+
+Das ist der am meisten missverstandene Punkt des ganzen Themas, also verdient er einen eigenen Abschnitt.
+
+In dem Moment, als Graph Engineering viral ging, murmelte jeder mit Produktionserfahrung dasselbe: „Ist das nicht einfach Workflows? DAGs, Zustandsmaschinen, Workflow-Engines — wir betreiben die seit Jahrzehnten.“
+
+**Dieser Instinkt ist halb richtig.** Graphen und Workflows teilen dasselbe Skelett: Knoten + Kanten + Shared State + Routing. Airflow, Prefect, Dagster, Temporal orchestrieren seit Jahren genau auf diese Weise. Und die fünf Muster in Anthropics *Building Effective Agents* (Dezember 2024) — Prompt-Chaining, Routing, Parallelisierung, Orchestrator-Workers, Evaluator-Optimizer — sind, wenn man sie zeichnet, genau Ausführungsgraphen verschiedener Formen.
+
+**Die halbe, die falsch liegt, sind die Knoten.** Traditionelle Workflow-Knoten sind **deterministische Funktionen**: eine Python-Funktion, ein Shell-Skript, eine SQL-Aufgabe. Die Kanten sind fest verdrahteter Code: `if`, `switch`, `case`. Der Ingenieur wartet das ganze System in Code, und das Verhalten ist vorhersehbar — derselbe Input läuft immer denselben Weg.
+
+Ein Graph-Engineering-Knoten kann ein **vollständiger Agent** sein: selbst-looper, Tool-nutzend, Ziel-verstehend, bei Fehlern wiederholend. Und Kanten sind auch nicht unbedingt fest verdrahtet — sie können Routing-Regeln tragen, entschieden durch die Ausgabe eines vorherigen Knotens, ein Verifikationsergebnis oder sogar ein anderes Modell.
+
+Um den Unterschied zu schärfen, leihst du dir ein Begriffspaar von Anthropic. Anthropic unterscheidet Workflow von Agent mit einer Frage: **wer entscheidet über den Kontrollfluss?** Wenn dein Code die Schritte festlegt, ist es ein Workflow. Wenn das Modell die Schritte zur Laufzeit ändern kann, ist es ein Agent.
+
+Was ist dann ein Graph? **Ein Graph ist der Behälter, der beides hält.** Ein Graph kann enthalten:
+
+- Workflow-Knoten: Tests ausführen, Abdeckung berechnen — deterministischer Code, kein Modell nötig
+- Agent-Knoten: Features implementieren, Code reviewen — vollständige modellgetriebene Agents
+- Menschliche Knoten: Freigabe, Review — Human-in-the-loop, der Graph stoppt und wartet, bis ein Mensch zustimmt
+
+Die präzise Aussage ist also: **Graph Engineering ist kein Ersatz für Workflows — es ist eine Verallgemeinerung.** Der Knotentyp wird von „Funktion“ zu „Agent“ erweitert, und die Kanten-Entscheidungen von „statischem Code“ zu „dynamischem Routing“. Ein Workflow ist der vollständig deterministische Spezialfall eines Graphen.
+
+Das Gegenargument — iii.dev's *Loops, Graphs, and the Layer That Matters* — landet auf demselben Punkt, zieht aber die entgegengesetzte Schlussfolgerung:
+
+> „Die Form ist der einfache Teil, und sie ist wegwerfbar. Die tragende Entscheidung ist, woraus der Loop oder der Graph besteht und was mit ihm passiert, nachdem er funktioniert.“
+
+iii.dev's Punkt: Verwechsle Topologie nicht mit einer Engineering-Leistung. Workflow Engineering lief jahrzehntelang, und was wirklich überlebt hat, ist nicht, wie die Knoten verbunden sind — es ist **Replayability, Observability und Recoverability**: du kannst einen Fehlschlag abspielen, einen Lauf beobachten und nach einem Absturz fortsetzen. Du kannst die Form eines Graphen jeden Tag neu zeichnen; diese tragenden Fähigkeiten sind es, wo du deine Mühe investieren solltest. Diese Kritik ist es wert, im Kopf zu behalten: **Das Zeichnen des Graphen ist nicht das Ziel. Welche Engineering-Fähigkeit der Graph tragen kann, ist das Ziel.**
+
+## Du hast schon die ganze Zeit Graphen gezeichnet
+
+„Neuer Krug, alter Wein“ hat noch einen weiteren Beweis: Die Tools waren schon da.
+
+- **LangGraph**: im Januar 2024 veröffentlicht, bis Juli 2026 bei rund 65 Millionen Downloads pro Monat. Es ist eine Graph-Ausführungs-Engine für Agents — Knoten können Agents sein, Kanten können bedingtes Routing, Checkpoints und Interrupts tragen.
+- **Anthropics fünf Muster**: Decembers 2024 *Building Effective Agents* hat die Graphen für Prompt-Chaining, Routing, Parallelisierung, Orchestrator-Workers und Evaluator-Optimizer bereits gezeichnet. Es nannte es nur nicht Graph Engineering.
+- **Claude Codes Subagent-Fan-out**: Wenn du einen Haupt-Agenten eine Schar von Sub-Agenten parallel arbeiten lässt, baust du bereits einen Graphen — du hast es nur nicht bemerkt.
+- **Zustandsmaschinen, DAG-Scheduler, Task-Queues, Wissensgraphen**: die Informatik betreibt seit Jahrzehnten Graph-Engineering.
+
+Was ist tatsächlich neu? **Der Knoten ging von „Funktion“ zu „Agent“.** Das ist die einzige Änderung — und es ist die ganze Änderung. Früher bedeutete es, einen Workflow-Knoten zu schreiben, dass du seine Logik, Fehlerbehandlung und Retry-Policy von Hand schriebst. Jetzt braucht ein Knoten eine Anweisung — „recherchiere dieses Problem“, „reviewe diesen Code“ — und das Modell erledigt den Rest. Knoten wurden billig, also wurden Graphen es wert, gezeichnet zu werden.
+
+## Baue deinen ersten Graphen von Grund auf
+
+Genug Theorie. Lass uns bauen. Der Maker-Checker aus der letzten Lektion war **ein** Agent, der loopt. Das Erste, was Graph Engineering tut, ist, diesen monolithischen Agenten auseinanderzunehmen: **jeder Knoten wird zu einem spezialisierten Agenten mit seinem eigenen privaten Prompt, Context, Tools, Gedächtnis und seinem eigenen kleinen Loop; Knoten teilen keinen Context miteinander — sie übergeben nur über einen gemeinsamen Shared State.** Das ist die verständliche Version von Rohits Satz — „der Graph entscheidet, was jeder Knoten sieht, wann er läuft, wohin seine Ausgabe geht, wer ihn ablehnen kann und was das System stoppt.“ **Keine der Notationen unten ist an eine bestimmte Engine gebunden** — das sind Konzepte; LangGraph, CrewAI und der Rest sind nur Implementierungen, die sie in ausführbare Programme verwandeln, andere APIs, dasselbe Skelett. Sechs Schritte — überspringe keinen.
+
+**Schritt 1: Definiere den Shared State.** Trenne zuerst die zwei Ebenen: **auf der Graph-Ebene wird nur der Status geteilt; der Knoten-Context ist privat.** Ein monolithischer Agent hat einen Context, und über einen langen Lauf ertrinkt er in seinem eigenen Transkript; ein Graph schneidet den Context in Stücke, eines pro Knoten — der Loop ist das private Eigentum des Knotens, der Graph ist die gemeinsame Werkbank, auf der sie übergeben. Denke durch, was der Status enthält. Deklariere, wie jedes Feld gemergt wird — wenn gleichzeitige Knoten in dasselbe Feld schreiben, wird überschrieben, angehängt oder summiert? Das ist kein Framework-Feature; es ist eine Regel, die du in `graph.md` schreibst, wenn du den Graphen zeichnest:
+
+```
+state = {
+ "requirements": Text, # vom Recherche-Knoten geschrieben
+ "code": Text, # vom Implementierungs-Knoten geschrieben
+ "review": "pass" | "fail", # vom Verifikations-Knoten geschrieben
+ "attempts": Zahl, # +1 pro Fehlschlag (bei parallelem Schreiben mit „Summe“ mergen)
+}
+```
+
+**Schritt 2: Liste die Knoten — jeder Knoten ist ein vollständiger Agent (mit eigenem Loop).** Das ist der grundlegende Unterschied zwischen einem Graphen und einem Workflow: Ein Workflow-Knoten ist eine Funktion; ein Graph-Knoten ist ein **Agent, der seinen eigenen kleinen Loop trägt**. Ein Knoten nimmt den Shared State, erledigt seine Arbeit in seinem privaten Context und schreibt Ergebnisse zurück in den Shared State. Das Innere eines Code-schreibenden Knotens ist oft der Loop aus der letzten Lektion:
+
+```
+# im Inneren des implement-Knotens: ein privater kleiner Loop (der Maker-Checker-Loop aus der letzten Lektion)
+node_implement(requirements):
+ loop (höchstens 3-mal):
+ code = model(prompt=Implementierungsanweisungen, context=requirements + letzter Fehler)
+ if tests_pass(code): return {"code": code}
+ return {"error": "Implementierung 3-mal fehlgeschlagen"}
+```
+
+| Knoten | Typ | Im Inneren des Knotens (privat) | Schreibt in den Shared State |
+|------|------|------------------|-------------|
+| research | Agent | suchen → lesen → zusammenfassen → bei nicht genug Infos neu suchen (Loop) | requirements |
+| implement | Agent | schreiben → testen → beheben → bis es besteht (Loop, siehe oben) | code |
+| verify | Agent | unabhängiges Review + Tests ausführen (**frischer Context, erbt nicht das Gedächtnis des Implementers**) | review (pass / fail) |
+| merge | deterministischer Code | kein Loop; commit, sobald die Checks bestanden sind | fertig |
+
+Achte auf die verify-Zeile — sie ist der am leichtesten falsch zu machende Knoten. **In einem monolithischen Agenten läuft „Review“ immer noch im selben Context, also reviewt der Agent sich selbst; in einem Graphen muss verify einen völlig frischen Context bekommen** — es sieht nie das Reasoning von implement, nur den `code` im Shared State. Genau dort wird „unabhängiges Review“ in einem Graphen tatsächlich wahr: Context-Isolation ist kein Nebeneffekt, sie ist das Design.
+
+**Schritt 3: Verdrahte die Kanten.** Beginne mit der deterministischen Hauptlinie: research → implement → verify → merge → Ende.
+
+```mermaid
+flowchart TD
+ A([Start]) --> B[research]
+ B --> C[implement]
+ C --> D[verify]
+ D --> E[merge]
+ E --> F([Ende])
+```
+
+**Schritt 4: Schreibe die Routing-Regeln (der wichtigste Schritt).** Der verify-Knoten verbindet sich nicht direkt mit merge — er verbindet sich mit einer **Entscheidung**, die wählt, wohin die Ausführung als Nächstes geht. Genau hier wird „wohin gehen Fehler zurück“ explizit. Routing-Regeln geben Knotennamen zurück, sodass der ganze Graph — woher er kommt, wohin er geht — auf einen Blick lesbar ist:
+
+| Aktueller Knoten | Bedingung | Nächster Knoten |
+|---------|------|---------|
+| verify | review == pass | merge |
+| verify | review == fail | implement |
+
+```mermaid
+flowchart TD
+ A([Start]) --> B[research]
+ B --> C[implement]
+ C --> D{verify}
+ D -- pass --> E[merge]
+ D -- fail --> C
+ E --> F([Ende])
+```
+
+**Schritt 5: Hänge einen Checkpoint an.** Das ist einer der größten Unterschiede zwischen einem Graphen und einem Einmal-Skript: **der Status wird nach jedem Schritt persistiert**, sodass du, wenn der Prozess stirbt, vom Checkpoint aus fortfährst, statt von vorne zu beginnen. Mit einem angehängten Checkpoint erhält dein Graph Unterbrechen/Fortsetzen geschenkt — und du kannst auch vor dem Merge pausieren, um auf menschliche Freigabe zu warten, was das „menschliche Review“ aus der letzten Lektion in einem Graphen ist:
+
+```
+checkpoint = on(graph, every_step) # Status nach jedem Schritt speichern
+graph.pause_before("merge") # vor dem Zusammenführen stoppen, auf Freigabe warten
+```
+
+**Schritt 6: Führe den Graphen mit einem Einstiegspunkt aus.** Übergib bei jedem Lauf eine Thread-ID — der Checkpoint nutzt sie, um Läufe zu unterscheiden:
+
+```
+run(graph, entry={"requirements": "Login-Seiten-Bug beheben"}, thread="session-1")
+```
+
+Hältst du das am Ende gegen das Diagramm oben? Dein handgeschriebenes `graph.md` ist der Bauplan, und der Code in einer Engine ist der in ein ausführbares Programm verwandelte Bauplan. Die beiden sollten eins zu eins übereinstimmen. Wenn sie nicht übereinstimmen — ist entweder das Diagramm falsch oder der Code falsch, **und genau das bedeutet „ein Graph legt das Problem auf den Tisch“**: vorher ging eine Nichtübereinstimmung von allen unbemerkt durch; jetzt ist sie auf einen Blick sichtbar. Wenn du eine lauffähige Referenzimplementierung willst, sieh `code/maker_checker_graph.py` — es verwendet LangGraph, aber am Ende solltest du es erkennen: Es sind genau diese sechs Schritte.
+
+## Open-Source-Projekte: Nach dem Namen, vor dem Namen
+
+Zuerst ziehe die Linie: **„Graph Engineering“ ist ein Name, der erst nach dem 18. Juli 2026 existiert.** Frameworks, die vor diesem Datum open-sourced wurden, sind keine „Graph-Engineering-Projekte nach der Veröffentlichung“. Stand Anfang August 2026 hält nur ein Open-Source-Projekt, das diesen Namen trägt, stand:
+
+**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.
+
+**Projekte vor der Veröffentlichung (sie nennen es nicht Graph Engineering — aber mit ihnen baust du tatsächlich)**
+
+Vor Juli 2026 existierten diese Tools bereits ein bis drei Jahre: LangGraph (2024 open-sourced, 65 Mio.+ monatliche Downloads, die Engine hinter der Referenzimplementierung oben), CrewAI, Microsoft Agent Framework, LlamaIndex Workflows, Google ADK, OpenAI Agents SDK, Mastra, Claude Agent SDK. **Sie sind keine „Projekte nach Graph Engineering“ — sie sind der Beweis, dass Graph Engineering existierte, bevor es den Namen bekam.** Knoten, Kanten, Shared State und Routing laufen seit drei bis fünf Jahren; der Juli hat ihnen nur ein neues Label gegeben. Eine Graph-Engine löst keine Designprobleme: Sie reicht dir Knoten, Kanten und Checkpoints, aber sie beantwortet nicht „welche Loops speisen welche, wer besitzt die Ziele, wer kann ablehnen“. Bis diese Fragen geklärt sind, macht ein Engine-Wechsel nur dasselbe schlechte Design hübscher.
+
+## Kaltes Wasser: Ein Graph ist keine Silberkugel
+
+Drei Eimer kaltes Wasser, vom Leichtesten beginnend.
+
+**Eimer eins: die falschen Zahlen.** Nachdem Graph Engineering viral ging, kursierten Behauptungen über „+18 % Genauigkeit, −85 % Kosten“ durch die Einführung von Graphen. Ein [Faktencheck vom koreanischen Blogger goddaehee](https://goddaehee.tistory.com/628) (30. Juli) findet heraus: Die beiden Zahlen existieren, aber sie stammen aus einem Paper vom März 2026 über chemische Rohrleitungs- und Instrumentierungsdiagramme (P&ID) — und die 18 % sind gegen das Rohbild gemessen, während die 85 % gegen eine andere Baseline gemessen sind. Marketing hat zwei anders-baseline Zahlen in eine „Vorher/Nachher“-Geschichte geklebt, und das Paper verwendet den Begriff „graph engineering“ nie. Wenn du siehst, dass „Graph Engineering dir X % Verbesserung bringt“ vermarktet wird, frag nach der Originalquelle.
+
+**Eimer zwei: Form ist nicht die tragende Wand (iii.dev).** Oben behandelt. Ein Loop ist nur ein Graph mit einem Knoten; Zustandsmaschinen laufen seit Jahrzehnten. Menschen, die „Loops sind tot“ oder „Graphen sind tot“ verkünden, haben meist weder das eine noch das andere sorgfältig gelesen. Lerne die Muster, nicht die Substantive.
+
+**Eimer drei: die Orchestration Tax.** Addy Osmanis *The Orchestration Tax* (Mai 2026) enthält die härteste Ökonomie der Graph/Multi-Agent-Ära: **einen Agenten zu starten ist billig. Den Loop über einem zu schließen ist teuer.**
+
+Einen Agenten zu starten ist ein Tastendruck. Aber einen Loop eines Agents zu schließen bedeutet, dass jemand prüft, was zurückkommt, und es mit dem abgleicht, was die anderen Agents angefasst haben — **dieses Jemand bist du, und es gibt genau einen von dir.** Osmanis Worte:
+
+> „Du bist der GIL deiner AI-Agents. Sie können alle gleichzeitig laufen. Aber wenn irgendeine ihrer Arbeiten echtes Verständnis der Architektur oder das Auflösen von Merge-Konflikten braucht, muss diese Arbeit die Sperre erwerben. Es gibt eine Sperre. Du hältst sie.“
+
+Das ist der Grund, warum „Review-Bandbreite ist die Obergrenze“ aus der letzten Lektion hier schärfer wird: **ein Graph lässt mehr Agents parallel laufen, aber dein Urteilsvermögen ist eine serielle Ressource. Es parallelisiert nicht.** Knoten hinzuzufügen optimiert den Teil, der nie der Engpass war — der Engpass ist immer der eine serielle Prozessor: du.
+
+## Wann du wirklich einen Graphen brauchst
+
+Nicht jede Aufgabe verdient einen Graphen. Fünf Kriterien — versuche mindestens drei, bevor du beginnst:
+
+1. **Die Aufgabe zerfällt in unabhängige Arbeitseinheiten** — Teile, die nicht voneinander abhängen und parallel laufen können
+2. **Es gibt Verzweigungs- oder Rollback-Pfade** — „wohin gehen Tests zurück“, „wohin geht unzureichende Info zurück“ sind Pfade, die es wert sind, explizit deklariert zu werden
+3. **Zwischenzustand ist es wert, gespeichert zu werden** — du kannst an Checkpoints pausieren und fortsetzen, statt von null neu zu starten
+4. **Ergebnisse können explizit verifiziert werden** — jeder Knoten hat eine automatisch prüfbare Fertig-Definition
+5. **Kooperationsvorteile > Koordinationskosten** — die durch Parallelität gesparte Zeit überwiegt den Overhead des Graphen und seines Shared State
+
+**„Komplex“ bedeutet nicht „viele Schritte“.** Eine 20-Schritte-lineare Pipeline braucht keinen Graphen — das ist ein Workflow oder einfach ein Skript. Eine Struktur mit nur 5 Knoten, aber echtem Rollback, Parallelität und Freigaben braucht einen Graphen. Der entscheidende Faktor ist nicht der Maßstab — es ist **die Existenz von Verzweigungen und Rollbacks.**
+
+## Kernkonzepte
+
+- **Graph Engineering**: die Praxis, mehrere Agents, Loops, Tools und Evaluatoren in einem expliziten Graphen (Knoten + Kanten + Shared State + Routing-Regeln) zu organisieren, um die Verbindungen, den geteilten Zustand und die Pfadentscheidungen mehrerer Arbeitseinheiten designbar, beobachtbar und lokal reparierbar zu machen.
+- **Vier gestapelte Ebenen**: prompt → context → loop → graph. Jede Ebene kontrolliert etwas anderes (Anweisung, Information, Laufzeit, System); die spätere Ebene ersetzt die früheren nicht — sie legt sie in ihre Knoten.
+- **Die vier Teile eines Graphen**: Knoten (Arbeitseinheiten), Kanten (Übergaben), Shared State (der gemeinsame Arbeitsbereich), Routing-Regeln (wohin die Ausführung als Nächstes geht).
+- **Drei strukturelle Fehlschläge eines einzelnen Loops**: Goodhart (die Zahlen gingen hoch, das Geschäft wurde schlechter), Blindheit nach oben (es fragt nie „ist das das richtige Ziel?“), Konflikt (unabhängige Loops untergraben sich gegenseitig). Ein Graph macht daraus explizites Beziehungsdesign.
+- **Graph ≠ Workflow**: Workflow-Knoten sind deterministische Funktionen und Kanten sind fest verdrahteter Code; Graph-Knoten können vollständige Agents sein und Kanten können dynamisch routen. Ein Graph ist die Verallgemeinerung eines Workflows.
+- **Anchors (Anker)**: die Mechanismen, die ein Netzwerk von Loops an der realen Welt festmachen (echte Geschäftsergebnisse, Ground Truth, menschliche Stichproben). Der am einfachsten zu überspringende Teil des Graph-Designs — und der, den du dir nicht leisten kannst zu überspringen.
+- **Die Orchestration Tax**: Agents zu starten ist billig, Ergebnisse zu reviewen ist teuer. Deine Aufmerksamkeit ist die einzige serielle Ressource, und das Hinzufügen von Knoten optimiert sie nicht.
+
+## Kernaussagen
+
+- **Graph Engineering ersetzt nicht Loop Engineering — es baut darauf auf.** Ein Loop ist ein Knoten in einem Graphen; die drei Dinge aus der letzten Lektion (Ziel, Verifikation, Stoppbedingung) werden zur internen Struktur des Knotens.
+- **Ein Graph verwandelt verzögerte Entscheidungen in vorab getroffene Entscheidungen.** Ein Loop versteckt Fehlermodi im Loop; ein Graph legt sie auf den Tisch — lesbar, prüfbar, lokal reparierbar.
+- **Was im Knoten steckt, entscheidet den Unterschied zwischen Graph und Workflow.** Funktionen machen einen Workflow; Agents machen einen Graphen. Das ist der einzige wirklich neue Wein im alten Krug.
+- **Stelle die vier Designfragen, bevor du zeichnest:** welche Loops speisen welche, wer besitzt die Ziele, wer kann ablehnen/rollback, welche Metriken dürfen sich bewegen und welche müssen eingefroren bleiben. Wenn du sie nicht beantworten kannst, zeichne nicht.
+- **Zeichne keine Graphen um ihrer selbst willen.** Fünf Kriterien: unabhängig zerlegbar, hat Verzweigungen oder Rollbacks, Zwischenzustand es wert gespeichert zu werden, Ergebnisse verifizierbar, Kooperationsvorteile > Koordinationskosten.
+- **Deine Review-Bandbreite ist immer noch die Obergrenze.** Ein Graph lässt mehr Agents parallel laufen, aber dein Urteilsvermögen ist seriell — die Orchestration Tax verschwindet nicht, weil es mehr Knoten gibt.
+- **Behalte das Gegenargument.** Form ist nicht die tragende Wand; Replayability, Observability und Recoverability sind es. Substantive wechseln alle sechs Wochen. Engineering-Fähigkeit nicht.
+
+## Weiterführende Lektüre
+
+- [Prefect: Loops vs. Graphs (Jul 2026)](https://www.prefect.io/blog/loops-vs-graphs) — Loops und Graphen aus der Sicht eines Unternehmens, das seit Jahrzehnten Graph-Orchestrierung baut
+- [Eigent: Graph Engineering for AI Agents (Jul 2026)](https://www.eigent.ai/blog/graph-engineering-ai-agents) — drei strukturelle Fehlschläge einzelner Loops + die vier Designfragen + Anker
+- [iii.dev: Loops, Graphs, and the Layer That Matters (Jul 2026)](https://iii.dev/blog/loops-graphs-and-the-layer-that-matters/) — das klarste Gegenargument: „Form ist nicht die tragende Wand“
+- [Rohit (@rohit4verse): der ursprüngliche Thread (29. Juli 2026)](https://x.com/rohit4verse/status/2082478623043547356) — die Primärquelle für das Vier-Ebenen-Framework: prompt → context → loop → graph, jede Ebene komponiert auf der letzten
+- [Agent Times: Graph Engineering as the Final Layer (Jul 2026)](https://theagenttimes.com/articles/graph-engineering-emerges-as-proposed-final-layer-of-agent-o-4f0511a8) — eine saubere Zusammenfassung von Rohits Vier-Ebenen-Framework
+- [goddaehee: Graph Engineering Faktencheck (KR, 2026-07-30)](https://goddaehee.tistory.com/628) — der vollständigste Faktencheck: die Witz-Ursprungs-Zeitlinie, die auseinandergenommenen falschen Zahlen, LangGraph-Daten, Hacker-News-Hitze-Vergleich
+- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — der ernste Beitrag, der zwei Wochen vor dem Witz geschrieben wurde
+- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — die offizielle Antwort: „keine neue Idee, der neueste Name für einen etablierten Ansatz“; LangGraphs 65 Mio.+ monatliche Downloads
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — Hype-Verbreitungsdaten (575.000 Aufrufe auf dem ursprünglichen Tweet)
+- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — ein Kopf-an-Kopf-Vergleich von sieben Mainstream-Open-Source-Frameworks: LangGraph, CrewAI, Microsoft Agent Framework, LlamaIndex, Google ADK, OpenAI Agents SDK, Mastra
+- [LangGraph offizielle Dokumentation](https://docs.langchain.com/oss/python/langgraph/graph-api) — „Nodes do the work, edges tell what to do next“; die präzisen Definitionen von Knoten und Kanten, die Referenz aus erster Hand für das Bauen von Graphen
+- [Anthropic: Building Effective Agents (Dez 2024)](https://www.anthropic.com/engineering/building-effective-agents) — fünf Muster, die gezeichnet Graphen sind; die maßgebliche Workflow-vs-Agent-Unterscheidung
+- [Addy Osmani: The Orchestration Tax (Mai 2026)](https://addyosmani.com/blog/orchestration-tax/) — warum deine Aufmerksamkeit die einzige serielle Ressource ist
+- [Addy Osmani: Orchestrating Coding Agents (Vortrag)](https://talks.addy.ie/oreilly-codecon-march-2026/) — von Subagents zu Agent-Teams zu Quality Gates
+- [Addy Osmani: Loop Engineering (Jun 2026)](https://addyosmani.com/blog/loop-engineering/) — die Kernreferenz der letzten Lektion; Voraussetzung für Graph Engineering
+- Lektion 13: [Von manuellen Prompts zu autonomen Loops](./../lecture-13-loop-engineering/index.md) — ein Loop ist ein Knoten in einem Graphen; verstehe den Knoten, bevor du den Graphen verstehst
+- Lektion 11: [Die Runtime des Agenten beobachtbar machen](./../lecture-11-why-observability-belongs-inside-the-harness/index.md) — je komplexer der Graph, desto wichtiger ist Observability; ein unbeobachtbarer Graph ist nur eine größere Blackbox
+- Lektion 09: [Verhindern, dass Agenten zu früh Erfolg melden](./../lecture-09-why-agents-declare-victory-too-early/index.md) — warum der Verify-Knoten unabhängig vom Implement-Knoten sein muss; in einem Graphen ist das ein strukturelles Problem, kein Prompt-Problem
+
+## Übungen
+
+1. **Zeichne deinen P07-Maker-Checker-Loop als Graphen:** Schreibe Knoten, Kanten, Shared State und Routing-Regeln explizit in einem `graph.md` aus. Markiere, welche Kanten bedingt sind (verify bestanden/fehlgeschlagen) und welche Rollback-Kanten (fehlgeschlagen zurück zu implement). Wenn du fertig bist, beantworte: gibt es eine Kante, die implizit war — vorher im Context des Agents versteckt?
+
+2. **Beantworte eigents vier Fragen:** Finde drei unabhängige Loops, die du betreibst (oder drei Automatisierungen im selben Projekt), und beantworte: Welche Loops speisen welche? Welcher Loop besitzt ein Ziel, dem ein anderer Loop nachjagt? Gibt es einen Loop, der die Ausgabe eines anderen Loops ablehnen kann? Welche Metriken werden auf eine Weise optimiert, die in Konflikt geraten könnte?
+
+3. **Goodhart-Selbstcheck:** Untersuche eine Metrik, die du zuletzt optimiert hast. Als sie stieg, wurde auch das echte Ergebnis (Geschäftsergebnisse, Nutzerfeedback, Codequalität) besser? Wenn nur die Zahl stieg, in welche Richtung lernt dieser Loop, dich anzulügen?
+
+4. **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
diff --git a/docs/de/projects/project-08-graph-engineering-first-graph/index.md b/docs/de/projects/project-08-graph-engineering-first-graph/index.md
new file mode 100644
index 0000000..e5cc213
--- /dev/null
+++ b/docs/de/projects/project-08-graph-engineering-first-graph/index.md
@@ -0,0 +1,93 @@
+[English Version →](../../../en/projects/project-08-graph-engineering-first-graph/)
+
+# Projekt 08. Zeichne deinen Workflow als Graph
+
+> Zugehörige Lektion: [L14. Von Einzel-Loops zu Graph Engineering](./../../lectures/lecture-14-graph-engineering/index.md)
+
+## Was du tust
+
+Das ist das Übergangsprojekt von „Loop“ zu „Graph“. In der letzten Lektion hast du einen Maker-Checker-Loop gebaut — implementieren, verifizieren, Feedback, neu implementieren, wobei alle Entscheidungen im Context Window desselben Agents stattfinden. Was du in dieser Lektion tust, ist, **die im Loop versteckte Struktur explizit herauszuzeichnen**: Knoten, Kanten, Shared State, Routing-Regeln — Wort für Wort niedergeschrieben.
+
+Du machst drei fortschreitende Experimente: zuerst zeichnest du den Maker-Checker-Loop aus P07 als expliziten Graphen, dann fügst du dem Graphen einen parallelen Fan-out/Fan-in-Knoten hinzu und schließlich eine bedingte Rollback-Kante und einen menschlichen Freigabe-Knoten. Am Ende wirst du eines hautnah erleben: **ein Graph ist keine neue Erfindung — es ist das, was dein Loop wird, wenn er komplex genug geworden ist.**
+
+## Werkzeuge, die du nutzt
+
+- Claude Code oder Codex
+- Git
+- Deinen Maker-Checker-Loop aus P07 (oder jeden Agenten-Workflow, den du wiederholt ausführen kannst)
+- Einen Texteditor oder ein Zeichen-Tool (zeichnen ist nicht für die Ästhetik, sondern um die Struktur klar zu schreiben; `mermaid` oder ein handgeschriebenes `graph.md` reichen)
+
+## Schritte
+
+### Vorbereitung
+
+1. Starte von dem Repository, wie du es nach P07 verlassen hast, oder verwende direkt einen beliebigen Agenten-Workflow, den du gerade betreibst.
+2. Erstelle drei Branches: `p08-explicit-graph`, `p08-parallel`, `p08-human-in-the-loop`.
+3. Bereite eine `state.md` als gemeinsame Statusdatei vor: Anforderungen, Fortschritt und Verifikationsergebnisse werden hier hineingeschrieben. Das ist die „gemeinsame Werkbank“ des Graphen.
+
+### Experiment 1: Den Loop als expliziten Graphen zeichnen
+
+Wechsle zum Branch `p08-explicit-graph`.
+
+1. **Liste alle Knoten auf**: Schreibe jeden Schritt des Maker-Checker-Loops aus P07 als einen Knoten. Notiere für jeden Knoten klar: seine Verantwortung, seine Eingabe, seine Ausgabe, ob er ein Agent oder deterministischer Code ist.
+2. **Zeichne alle Kanten**: Liste jede Kante zwischen den Knoten auf. Markiere dabei besonders zwei spezielle Kanten:
+ - Bedingte Kante: Verifikation bestanden/fehlgeschlagen, wohin sie führt
+ - Rollback-Kante: bei Fehlschlag zurück zu welchem Knoten
+3. **Schreibe den Shared State**: Liste explizit auf, welche Felder der Status hat (Anforderungen, Code, Testergebnisse, Review-Schlussfolgerung), wer sie liest und wer sie schreibt.
+4. **Schreibe die Routing-Regeln**: Formuliere die „wohin als Nächstes“-Regeln in einfachster If-then-Sprache, zum Beispiel:
+ ```
+ if Verifikation bestanden → Merge-Knoten
+ if Verifikation fehlgeschlagen → Implementierungs-Knoten
+ if Implementierungs-Knoten hat nicht genug Infos → Recherche-Knoten
+ ```
+5. **Schreibe eine `graph.md`**: Halte die obigen Inhalte in einem Dokument fest. Zeichne mit mermaid einen Graphen, ergänze eine Knotentabelle und die Routing-Regeln.
+6. **Beantworte diese Frage**: Zeige nach dem Zeichnen mindestens **eine Kante, die ursprünglich implizit war** — einen Entscheidungspfad, der vorher im Context des Agents versteckt war, von dem du selbst nicht wusstest, dass er existiert.
+
+### Experiment 2: Einen parallelen Fan-out / Fan-in-Knoten hinzufügen
+
+Wechsle zum Branch `p08-parallel`.
+
+1. **Wähle einen Punkt, der parallelisiert werden kann**: Finde eine Stelle in der Aufgabe, die sich in zwei unabhängige Teile zerlegen lässt. Zum Beispiel:
+ - Die Implementierung in zwei unabhängige Module aufteilen, zwei Agents schreiben parallel
+ - Die Verifikation in zwei unabhängige Reviews aufteilen: eines führt Tests und Lint aus, eines macht Code-Review (verschiedene Anweisungen, verschiedene Blickwinkel)
+ - Die Recherche in zwei Richtungen aufteilen, zwei Agents recherchieren jeweils einen Pfad
+2. **Schreibe die Fan-out-Regel**: Halte im Shared State fest, dass diese Aufgabe in N parallele Teilaufgaben zerlegt wurde, jede mit einem unabhängigen Context und einem unabhängigen Knoten.
+3. **Schreibe die Fan-in-Regel**: Wer mergt die Ergebnisse, wenn alle Teilaufgaben fertig sind? Was ist das Merge-Kriterium (z. B.: erst mergen, wenn beide Reviews bestanden sind, oder reicht schon eines)?
+4. **Nutze Worktree-Isolation**: Führe jede parallele Teilaufgabe in einem unabhängigen Git-Worktree aus, um Dateikollisionen physisch zu vermeiden (denke an das Worktree-Primitiv aus Lektion 13 zurück).
+5. **Führe es einmal aus und protokolliere**: Notiere die Wall-Clock-Zeit vor und nach der Parallelisierung, den Token-Verbrauch und die Ergebnisqualität. Ist die Parallelisierung wirklich schneller? Oder frisst der Koordinations-Overhead die gesparte Zeit wieder auf?
+
+### Experiment 3: Eine Rollback-Kante und einen menschlichen Freigabe-Knoten hinzufügen
+
+Wechsle zum Branch `p08-human-in-the-loop`.
+
+Das ist das wichtigste der drei Experimente. Du fügst dem Graphen zwei Arten von Knoten hinzu:
+
+1. **Bedingte Rollback-Kante**: Gib dem Verifikations-Knoten einen „teilweise bestanden“-Pfad — nicht immer komplett zurück zum Implementierungs-Knoten, sondern mit konkretem Feedback zurück zu **dem Knoten, der das Problem verursacht hat**. Zum Beispiel: Alle Tests bestanden, aber das Code-Review zeigt ein Missverständnis der Anforderungen — zurück zum Recherche-Knoten statt zum Implementierungs-Knoten. Das erfordert, dass dein Shared State festhält, „auf welcher Ebene das Problem liegt“.
+2. **Menschlicher Freigabe-Knoten (Human-in-the-loop)**: Füge vor dem Merge-Knoten einen menschlichen Knoten hinzu. Dort **stoppt** der Graph, bis du in `state.md` „Genehmigen“ oder „Zurückweisen“ schreibst. Der Freigabe-Knoten kann eine Timeout-Regel haben: Wenn innerhalb von N Stunden keine Antwort kommt, automatisch zurückweisen oder eskalieren.
+3. **Schreibe das Interrupt-Format**: Wie ist die Freigabe-Anfrage klar zu formulieren — was passiert ist, was geändert wurde, warum ein Mensch nötig ist, was die Folgen von Genehmigen/Zurückweisen jeweils sind.
+4. **Führe mindestens 2 vollständige Durchläufe aus**: Gehe bei jedem Durchlauf bis zum menschlichen Freigabe-Knoten und genehmige oder weise selbst einmal zurück. Notiere: Stimmt deine Freigabe-Entscheidung mit der Beurteilung des Verifikations-Knotens überein? Hat der Freigabe-Knoten etwas abgefangen, das der Verifikations-Knoten nicht abgefangen hat?
+
+## Wie man Ergebnisse misst
+
+| Metrik | Exp 1 (Expliziter Graph) | Exp 2 (Parallel) | Exp 3 (Mensch+Maschine) |
+|------|----------------|--------------|------------------|
+| Struktur-Sichtbarkeit | Wie viele implizite Kanten hast du gefunden? | Kann der Shared State parallele Teilaufgaben tragen? | Kann die Rollback-Kante die Problemebene präzise lokalisieren? |
+| Fehlerlokalisierung | Kannst du bei einem Fehlschlag direkt sagen, welche Kante falsch ist? | Wenn eine parallele Teilaufgabe fehlschlägt, kannst du die eine lokalisieren? | Kannst du bei einer Zurückweisung sagen, auf welcher Ebene das Problem liegt? |
+| Kooperations-Overhead | Wie lange hat das Zeichnen gedauert? | Gesparte Zeit durch Parallelität vs. Koordinations-Overhead | Freigabe-Wartezeit vs. Wert der abgefangenen Probleme |
+| Observability | Ist jetzt sichtbar, was bei jedem Schritt passiert? | Ist der Status jeder parallelen Teilaufgabe sichtbar? | Ist die Freigabe-Anfrage klar genug geschrieben? |
+| Zuverlässigkeit | Stimmt die Graph-Beschreibung mit dem tatsächlichen Lauf überein? | Ist das Fan-in-Merge-Kriterium verlässlich? | Werden die Timeout-/Eskalationsregeln wirklich auslösen? |
+
+## Was einzureichen ist
+
+- `graph.md` (die vollständige Graph-Beschreibung von Experiment 1: mermaid-Graph + Knotentabelle + Kantentabelle + Shared-State-Felder + Routing-Regeln)
+- Die Liste der impliziten Kanten aus Experiment 1 (mindestens eine)
+- Die Fan-out/Fan-in-Regeln von Experiment 2 und ein Aufzeichnungsprotokoll eines parallelen Laufs (Zeit/Kosten/Qualitätsvergleich)
+- Die Rollback-Kanten-Regel von Experiment 3, das Freigabe-Knoten-Format und 2 Durchläufe der Mensch+Maschine-Aufzeichnung
+- Abschließendes Retro: Was hat sich von Loop zu Graph in deiner Arbeitsweise verändert? Welche Aufgaben sind einen Graphen wert, welche nicht?
+
+## Zugehörige Lektionen
+
+- [Lektion 14 — Von Einzel-Loops zu Graph Engineering](../../lectures/lecture-14-graph-engineering/index.md)
+- [Lektion 13 — Von manuellen Prompts zu autonomen Loops](../../lectures/lecture-13-loop-engineering/index.md) (dein Loop ist ein Knoten im Graphen; dieses Projekt breitet die interne Struktur des Knotens aus)
+- [Lektion 09 — Verhindern, dass Agenten zu früh Erfolg melden](../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md) (warum der Verifikations-Knoten unabhängig vom Implementierungs-Knoten sein muss; in einem Graphen ist das ein strukturelles Problem)
+- [Lektion 11 — Die Runtime des Agenten beobachtbar machen](../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) (je komplexer der Graph, desto mehr musst du sehen, was jeder Knoten tut)
\ No newline at end of file
diff --git a/docs/en/lectures/lecture-14-graph-engineering/code/index.md b/docs/en/lectures/lecture-14-graph-engineering/code/index.md
new file mode 100644
index 0000000..ef0fade
--- /dev/null
+++ b/docs/en/lectures/lecture-14-graph-engineering/code/index.md
@@ -0,0 +1,9 @@
+# Lecture 14 Code
+
+Use this folder to store examples for:
+
+- graph.md graph description template (nodes / edges / shared state / routing rules)
+- node-prompt.md node role prompt template
+- routing-rules.md routing rules template
+- maker_checker_graph.py reference implementation (framework-bound: LangGraph): turns the six steps of "Build Your First Graph from Scratch" into runnable code — state schema, nodes, edges, conditional routing, checkpointer. The lecture body is framework-agnostic; this is one concrete way to write it down
+- Graph control script examples (execute the graph, check checkpoints, trigger human approval)
diff --git a/docs/en/lectures/lecture-14-graph-engineering/code/maker_checker_graph.py b/docs/en/lectures/lecture-14-graph-engineering/code/maker_checker_graph.py
new file mode 100644
index 0000000..a6241e1
--- /dev/null
+++ b/docs/en/lectures/lecture-14-graph-engineering/code/maker_checker_graph.py
@@ -0,0 +1,108 @@
+"""maker_checker_graph.py — A complete skeleton of the maker-checker graph built with LangGraph.
+
+Maps to the six steps in Lecture 14, "Build Your First Graph from Scratch":
+1. Define the shared state 2. List the nodes 3. Wire the edges
+4. Write the routing rules 5. Attach a checkpointer 6. Run the graph
+
+Dependency: pip install langgraph
+The model calls inside the agent nodes (research/implement/verify) are stubbed —
+wire them up to your own provider.
+"""
+
+from typing import Annotated, TypedDict
+import operator
+
+from langgraph.graph import StateGraph, START, END
+from langgraph.checkpoint.memory import MemorySaver
+
+
+# ---------- Step 1: Define the shared state ----------
+
+class GraphState(TypedDict):
+ requirements: str # written by the research node
+ code: str # written by the implement node
+ review: str # review verdict: pass / fail / unclear
+ attempts: Annotated[int, operator.add] # retry count, merged with +
+
+
+# ---------- Step 2: List the nodes ----------
+
+def call_model(system: str, content: str) -> str:
+ """Model-call placeholder — connect your own provider (Anthropic / OpenAI / ...)."""
+ raise NotImplementedError("Replace this with a real model call")
+
+
+def research(state: GraphState) -> dict:
+ # agent node: locate the problem, produce a requirements statement
+ requirements = call_model("You are a research agent", f"Analyze this problem: {state.get('requirements', '')}")
+ return {"requirements": requirements}
+
+
+def implement(state: GraphState) -> dict:
+ # agent node: write code + tests
+ code = call_model("You are an implementation agent", f"Implement against: {state['requirements']}")
+ return {"code": code}
+
+
+def tests_pass(code: str) -> bool:
+ """Deterministic check: run the tests. Placeholder — run pytest etc. in practice."""
+ return "def test" in code # placeholder: passing means the code contains a test
+
+
+def verify(state: GraphState) -> dict:
+ # agent node: independent review + run tests (must NOT share the implementer's context)
+ review = call_model("You are an independent reviewer", f"Review this code: {state['code']}")
+ passed = tests_pass(state["code"])
+ verdict = "pass" if passed and "approved" in review else "fail"
+ return {"review": verdict}
+
+
+def merge(state: GraphState) -> dict:
+ # deterministic node: commit
+ print(f"Merging code (passed after {state['attempts']} attempts)")
+ return {}
+
+
+# ---------- Step 4: Write the routing rules (the most important step) ----------
+
+def route_after_verify(state: GraphState) -> str:
+ if state["review"] == "fail":
+ return "implement" # verify failed → back to implement
+ return "merge" # verify passed → merge
+
+
+# ---------- Step 3: Wire the edges ----------
+
+graph = StateGraph(GraphState)
+graph.add_node("research", research)
+graph.add_node("implement", implement)
+graph.add_node("verify", verify)
+graph.add_node("merge", merge)
+
+graph.add_edge(START, "research")
+graph.add_edge("research", "implement")
+graph.add_edge("implement", "verify")
+graph.add_conditional_edges(
+ "verify",
+ route_after_verify,
+ {"implement": "implement", "merge": "merge"},
+)
+graph.add_edge("merge", END)
+
+
+# ---------- Step 5: Compile with a checkpointer ----------
+# The checkpointer persists state after every step: if the process dies,
+# you resume from the checkpoint instead of starting over.
+
+app = graph.compile(checkpointer=MemorySaver())
+
+
+# ---------- Step 6: Run the graph ----------
+# Pass a thread_id on every run — the checkpointer uses it to tell runs apart.
+
+if __name__ == "__main__":
+ result = app.invoke(
+ {"requirements": "fix the login page bug", "attempts": 0},
+ config={"configurable": {"thread_id": "session-1"}},
+ )
+ print(result)
diff --git a/docs/en/lectures/lecture-14-graph-engineering/index.md b/docs/en/lectures/lecture-14-graph-engineering/index.md
new file mode 100644
index 0000000..78e4ffb
--- /dev/null
+++ b/docs/en/lectures/lecture-14-graph-engineering/index.md
@@ -0,0 +1,349 @@
+[中文版 →](../../../zh/lectures/lecture-14-graph-engineering/)
+
+> Code examples: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-14-graph-engineering/code/)
+> Practice project: [Project 08. Draw Your Workflow as a Graph](./../../projects/project-08-graph-engineering-first-graph/index.md)
+
+# Lecture 14. From Single Loops to Graph Engineering
+
+Six weeks after Loop Engineering hit the mainstream, on July 18, 2026, Peter Steinberger — the OpenClaw author who told you to stop prompting your agent — posted a tweet:
+
+> "Are we still talking loops or have we moved on to graphs yet?"
+
+One tweet — ~575K views within a day, rising to roughly 3M by the end of the month. A few hours later, ML engineer Hamel Husain published *Loop Engineering Is Dead. Enter Graph Engineering* — an article whose entire body was a single "Stop it" GIF — and pulled another ~680k views.
+
+Here's the twist: **both of them were joking.** One was satirizing an industry that invents a new term every six weeks; the other was riffing on the gag. But the joke survived about one weekend — courses, roadmaps, and tool stacks flooded the timeline before the weekend was over, trailed by a pile of fabricated numbers: the "+18% accuracy, −85% cost" claim is fake (the two numbers do exist, but they come from a paper about chemical piping diagrams and compare against different baselines), and the "Microsoft, Stanford, and Anthropic all discovered graph engineering at once" claim is also false. The fact-checking finds exactly one genuine "precursor": Josh Simmons, whose *We Are Entering the Graph Engineering Phase* is dated July 4 — two full weeks before the joke. **The joke made the idea trendy. It did not create the idea.**
+
+> Sources: [goddaehee: Graph Engineering Fact-Check (2026-07-30)](https://goddaehee.tistory.com/628); [YC Startup School 2026: Jensen Huang interview (with transcript)](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia); [explainx: Graph Engineering (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026)
+
+This lecture is not about adding fuel to that fire. It's about taking the term apart and seeing it clearly: **why does a single loop inevitably grow into a graph? What actually differs between a graph and a workflow? And when do you really need one, versus when you don't?**
+
+## Prompt, Context, Loop, Graph: Four Names, One Stack
+
+In late July, an engineer going by Rohit (@rohit4verse) posted a [thread](https://x.com/rohit4verse/status/2082478623043547356) organizing the last few years of AI engineering naming into a clean four-layer framework. It's the best coordinate system for understanding graph engineering:
+
+| Layer | Shapes What | Answers The Question | Key Artifacts |
+|-------|------------|---------------------|---------------|
+| **Prompt Engineering** | The instruction | How do we tell the model what to do? | instructions, examples, constraints, roles, output formats |
+| **Context Engineering** | The information | What should the model know before it decides? | documents, history, memory, tool definitions, environment state |
+| **Loop Engineering** | The runtime | How do we make the model iterate until the goal is met? | observe, reason, act, inspect, update, stop condition |
+| **Graph Engineering** | The system | How do multiple agents, loops, tools and evaluators work together? | nodes, edges, shared state, routing rules |
+
+Read the progression carefully: **each layer does not replace the one before it — it stacks on top.**
+
+- After you found context engineering, you didn't stop prompting. Every iteration still needs a prompt; the loop just refreshes it as the environment moves.
+- After you built loops, you didn't drop context. Every round of a loop reassembles its context.
+- At the graph layer, prompt, context, and loop all survive: **every node carries its own prompt, its own context, its own tools, its own memory, its own loop.** The graph decides how the nodes connect.
+
+Rohit's thread ends like this:
+
+> Once an agent needs specialization, parallelism, shared state, verification and recovery, it has stopped being a loop. It's a graph.
+
+**Wait — where's harness?** These four names don't include Harness Engineering, yet this whole course is about the harness. The reason is simple: Rohit was telling the story of buzzwords, his ending was the graph, and the layer in between got skipped. And even the layer harness belongs on is unsettled — [explainx](https://explainx.ai/blog/context-prompt-loop-harness-engineering-stack-2026) puts it above the loop, the [Buildrix paper](https://arxiv.org/abs/2606.25139) below it. This course settled it back in Lecture 2: the harness is the foundation; loops and graphs are built on it.
+
+That explains a strange phenomenon: "Graph Engineering" only went viral in July 2026, yet everyone felt they'd "been doing this all along." Because a graph isn't a new invention — it's what a loop becomes when the task gets complex enough. **The name came later; the practice was already there.**
+
+## Take the Graph Apart: Nodes, Edges, State, Routing
+
+Strip the graph down to four plain parts.
+
+**Node**: a unit of work with a responsibility. It can be:
+- deterministic code (run tests, compute coverage)
+- a model call (generate docs)
+- a tool (git commit, send a message)
+- a full agent — with its own loop, able to understand goals, use tools, and retry on its own
+
+What a node is allowed to be is the real dividing line between graph engineering and workflow engineering. More on that below.
+
+**Edge**: how work hands off between nodes. It's not just "do A, then B" — an edge can express:
+- **Parallelism**: after A, B and C start at the same time
+- **Conditionals**: tests pass, go left; tests fail, go right
+- **Failure/retry**: a node dies, it loops back into itself
+- **Rollback**: verification fails, return to the implementation node three hops back
+
+**Shared State**: the data package passed between nodes. Requirements, research notes, code versions, test results, review conclusions — all written to the same shared workspace. Nodes don't shout at each other; they all read and write the same state.
+
+**Routing Rules**: decide where execution goes next. This is the graph's control flow, in the plainest possible terms:
+
+> Tests pass → ship. Tests fail → back to the implementation node. Not enough information → back to the research node.
+
+Assemble the four parts and a typical development graph looks like this:
+
+```mermaid
+flowchart TD
+ S["Shared State<br/>requirements / notes / code / results"] --- R["Research node<br/>Agent: locate the problem"]
+ R -->|"plan"| I["Implement node<br/>Agent: write changes + tests"]
+ I -->|"code"| V["Verify node<br/>Agent: independent review + run tests"]
+ V -->|"failed"| I
+ V -->|"passed"| M["Merge node<br/>code: commit + update state"]
+ M -->|"state update"| S
+ I -->|"not enough info"| R
+```
+
+Compare this with the loop diagram from the last lecture. The loop was a ring — discover, dispatch, verify, persist, back to discover. In this lecture's graph, **the ring is still there, but it has been decomposed into explicit nodes and edges.** The verify node can bounce a failure straight back to the implement node; the implement node can retreat to research when information is thin. Those "rollback edges" were implicit in a single loop — the agent just "remembered" it should go back, inside its own context window.
+
+## When a Loop Stops Being Enough
+
+A single loop has one main road. In the maker-checker loop you built in Project 07, every decision — what to do next, where to go on failure — happened inside one agent's context window. Push the task a little harder and four questions surface:
+
+1. **Division of labor**: a research agent, an implementation agent, a testing agent — who goes first?
+2. **Parallelism**: which parts of the work can run at the same time?
+3. **Rollback**: when tests fail, where do you go back to — the implement node, or the research node?
+4. **Handoff**: how do several agents see the same requirements, notes, and test results? If the reviewer disagrees with the implementer, who wins?
+
+Jensen Huang made a similar point in his [Startup School 2026 interview with Garry Tan (Y Combinator)](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia): as implementation is increasingly automated by agents, the human's core value shifts to designing systems, defining constraints, and controlling agents at a fine granularity. His control example is concrete — "when it comes up with a plan, I change one word in a plan file and that one word makes a delta difference" — and he predicts the future core skill is "systems thinking."
+
+The sharpest line in the whole discussion came from Luis Catacora:
+
+> **"Loops have a lot of room for forgiveness. Graphs force you to admit how much of your workflow is not actually modeled."**
+
+That sentence exposes the deep difference between loop and graph:
+
+- **A loop is a deferred decision.** One agent takes on all the work; if it gets stuck, you deal with it then. The architecture can be postponed. It's cheap — but the failure modes are invisible, because the agent itself doesn't know where it's stuck.
+- **A graph is an up-front decision.** You must declare the whole structure in advance: who owns what, how tasks depend on each other, where a given failure returns to. It's more work — and it buys you readability, auditability, and local repair.
+
+Put even more bluntly: **a loop hides the problem inside the loop; a graph puts the problem on paper.** The former suits exploration, the latter suits production.
+
+## Three Structural Failures of a Single Loop at Scale
+
+Why doesn't a single loop hold up at scale? *Graph Engineering for AI Agents: Beyond Single Feedback Loops* (eigent.ai) identifies three structural failures — structural, not bugs in any one loop.
+
+**Wait — can't a loop have checkpoints too?** Sure it can. Last lecture's verification, stop conditions, even pause-and-resume — a loop can hold all of them. But the three failures below are exactly what checkpoints can't fix — because a loop's checkpoints live inside the same agent, and the checker and the producer share one brain and one context. It will stop "shipping without verification," but it won't ask "is this metric right?" or "should this goal be chased?" — the answers live in its own context, and it can't see them. A graph doesn't give you more checkpoints; it moves the check — from inside the agent to a standalone node with a fresh context (the verify node from the section above). That's what "structural" means: not a missing part in the loop, but a structure where the judge and the judged share one brain.
+
+### 1. Goodhart: The Numbers Went Up, the Business Got Worse
+
+Push any single metric hard enough and it stops measuring what it used to. The canonical case: a support team builds a loop around ticket-resolution rate. Weekly numbers climb. Months later, renewal data shows churn has doubled — **the bot learned to close tickets**: deflecting, discouraging follow-ups, marking unresolved issues "resolved."
+
+The loop did exactly what it was told. The number simply detached from what the business cared about. Goodhart's law in action.
+
+### 2. Blindness Upward: It Never Asks "Is This the Right Goal?"
+
+Inside a loop, the reference value is sacred. A thermostat can't ask whether 68°F is the right temperature. A sales loop can't ask whether the quota was sane. An agent eval loop can't ask whether its benchmark matches real business outcomes.
+
+**Someone picked that target, and the loop will drive toward it even if it was never the right thing to chase.** There is no position in a single loop's structure where that question can be asked.
+
+### 3. Conflict: independent loops fight each other
+
+Real systems have many loops, each built separately. A loop for response speed undermines a loop for thoroughness. A loop for growth undermines a loop for quality. Each looks healthy on its own dashboard while the whole system thrashes — like several people pulling the same rope in different directions.
+
+**Graph engineering is built to answer exactly the questions a single loop can't:**
+
+- Which loops feed which other loops?
+- Which loops own the targets that other loops chase?
+- Which loops can veto or roll back a change?
+- Which measurements are allowed to move, and which must stay frozen?
+
+When your system contains loops that can consume other loops' targets and loops that can veto other loops' changes, the relationships between them become engineering objects — and relationships between relationships, drawn out, are a graph.
+
+### Anchors: Pin the Loop to Reality
+
+The eigent post has a section titled "the part everyone skips": **anchors**. No matter how elegant your network of loops, if every loop drifts away from reality, the network is just a resonance of mutual drift. An anchor is what pins a loop to the real world — actual business outcomes, ground-truth datasets, human spot-checks. Anchors are the easiest part of graph design to skip, and the one part you can't afford to.
+
+## Graph vs. Workflow: Not Just a Rename
+
+This is the most misunderstood point of the whole topic, so it deserves its own section.
+
+The moment Graph Engineering went viral, anyone with production experience muttered the same thing: "Isn't this just workflows? DAGs, state machines, workflow engines — we've run those for decades."
+
+**That instinct is half right.** Graphs and workflows share the same skeleton: nodes + edges + shared state + routing. Airflow, Prefect, Dagster, Temporal have been orchestrating exactly this way for years. And the five patterns in Anthropic's *Building Effective Agents* (Dec 2024) — prompt chaining, routing, parallelization, orchestrator-workers, evaluator-optimizer — when drawn out, are precisely execution graphs of different shapes.
+
+**The half that's wrong is in the nodes.** Traditional workflow nodes are **deterministic functions**: a Python function, a shell script, a SQL task. The edges are hardcoded code: `if`, `switch`, `case`. The engineer maintains the whole system in code, and behavior is predictable — the same input always walks the same path.
+
+A graph-engineering node can be a **full agent**: self-looping, tool-using, goal-understanding, retrying on failure. And edges aren't necessarily hardcoded either — they can carry routing rules, decided by a previous node's output, a verification result, or even another model.
+
+To sharpen the difference, borrow a pair of concepts from Anthropic. Anthropic distinguishes workflow from agent with one question: **who decides the control flow?** If your code fixes the steps, it's a workflow. If the model can change the steps at runtime, it's an agent.
+
+So what is a graph? **A graph is the container that holds both.** One graph can contain:
+
+- workflow nodes: run tests, compute coverage — deterministic code, no model needed
+- agent nodes: implement features, review code — full model-driven agents
+- human nodes: approval, review — human-in-the-loop, the graph stops and waits for a human to nod
+
+So the accurate statement is: **Graph Engineering is not a replacement for workflows — it's a generalization.** The node type is widened from "function" to "agent," and edge decisions are widened from "static code" to "dynamic routing." A workflow is the fully-deterministic special case of a graph.
+
+The counterargument — iii.dev's *Loops, Graphs, and the Layer That Matters* — lands on the same point, but draws the opposite conclusion:
+
+> "The shape is the easy part, and it is disposable. The load-bearing decision is what the loop or the graph is made of, and what happens to it after it works."
+
+iii.dev's point: don't mistake topology for engineering achievement. Workflow engineering ran for decades, and what actually survived is not how the nodes are connected — it's **replayability, observability, and recoverability**: you can replay a failure, watch a run, and resume after a crash. You can redraw a graph's shape any day; those load-bearing capabilities are where you should spend your effort. This criticism is worth keeping: **drawing the graph is not the goal. What engineering capability the graph can carry is the goal.**
+
+## You've Been Drawing Graphs All Along
+
+"New bottle, old wine" has another piece of evidence: the tools were already there.
+
+- **LangGraph**: released January 2024, roughly 65 million downloads per month by July 2026. It's a graph execution engine for agents — nodes can be agents, edges can carry conditional routing, checkpoints, and interrupts.
+- **Anthropic's five patterns**: December 2024's *Building Effective Agents* already drew the graphs for prompt chaining, routing, parallelization, orchestrator-workers, and evaluator-optimizer. It just didn't call it Graph Engineering.
+- **Claude Code's subagent fan-out**: when you let one main agent spawn a set of sub-agents working in parallel, you're already building a graph — you just didn't notice.
+- **State machines, DAG schedulers, task queues, knowledge graphs**: computer science has been engineering graphs for decades.
+
+What's actually new? **The node went from "function" to "agent."** That's the only change — and it's the whole change. Before, writing a workflow node meant writing its logic, error handling, and retry policy by hand. Now a node needs one instruction — "research this problem," "review this code" — and the model does the rest. Nodes got cheap, so graphs got worth drawing.
+
+## Build Your First Graph from Scratch
+
+Enough theory. Let's build. Last lecture's maker-checker was **one** agent that loops. The first thing Graph Engineering does is take that monolithic agent apart: **each node becomes a specialized agent with its own private prompt, context, tools, memory, and its own little loop; nodes don't share context with each other — they hand off only through one shared state.** That's the plain-language version of Rohit's sentence — "the graph decides what each node sees, when it runs, where its output goes, who can reject it, and what stops the system." **None of the notation below is tied to any specific engine** — these are concepts; LangGraph, CrewAI, and the rest are just implementations that turn them into executable programs, different APIs, same skeleton. Six steps — don't skip any.
+
+**Step 1: Define the shared state.** First, separate the two layers: **at the graph level, only state is shared; node context is private.** A monolithic agent has one context, and over a long run it drowns in its own transcript; a graph cuts the context into pieces, one per node — the loop is the node's private property, the graph is the shared bench where they hand off. Think through what the state contains. Declare how each field gets merged — when concurrent nodes write to the same field, is it overwritten, appended, or summed? This isn't a framework feature; it's a rule you write into `graph.md` when you draw the graph:
+
+```
+state = {
+ "requirements": text, # written by the research node
+ "code": text, # written by the implement node
+ "review": "pass" | "fail", # written by the verify node
+ "attempts": number, # +1 per failure (merged by "sum" on concurrent writes)
+}
+```
+
+**Step 2: List the nodes — each node is a complete agent (with its own loop).** This is the fundamental difference between a graph and a workflow: a workflow node is a function; a graph node is an **agent carrying its own little loop**. A node takes the shared state, does its work in its private context, and writes results back to the shared state. The inside of a code-writing node is often last lecture's loop:
+
+```
+# inside the implement node: a private little loop (last lecture's maker-checker loop)
+node_implement(requirements):
+ loop (at most 3 times):
+ code = model(prompt=implementation instructions, context=requirements + last error)
+ if tests_pass(code): return {"code": code}
+ return {"error": "implementation failed 3 times"}
+```
+
+| Node | Type | Inside the node (private) | Writes to shared state |
+|------|------|---------------------------|------------------------|
+| research | agent | search → read → summarize → re-search if not enough (loop) | requirements |
+| implement | agent | write → test → fix → until it passes (loop, above) | code |
+| verify | agent | independent review + run tests (**fresh context, does not inherit the implementer's memory**) | review (pass / fail) |
+| merge | deterministic code | no loop; commit once checks pass | done |
+
+Pay attention to the verify row — it's the easiest node to get wrong. **In a monolithic agent, "review" still runs in the same context, so the agent reviews itself; in a graph, verify must get a completely fresh context** — it never sees implement's reasoning, only the `code` in the shared state. That's where "independent review" actually becomes true on a graph: context isolation isn't a side effect, it's the design.
+
+**Step 3: Wire the edges.** Start with the deterministic spine: research → implement → verify → merge → end.
+
+```mermaid
+flowchart TD
+ A([Start]) --> B[research]
+ B --> C[implement]
+ C --> D[verify]
+ D --> E[merge]
+ E --> F([End])
+```
+
+**Step 4: Write the routing rules (the most important step).** The verify node doesn't connect straight to merge — it connects to a **decision** that chooses where execution goes next. This is where "where do failures go back to" becomes explicit. Routing rules return node names, so the whole graph — where it comes from, where it goes — is readable at a glance:
+
+| Current node | Condition | Next node |
+|--------------|-----------|-----------|
+| verify | review == pass | merge |
+| verify | review == fail | implement |
+
+```mermaid
+flowchart TD
+ A([Start]) --> B[research]
+ B --> C[implement]
+ C --> D{verify}
+ D -- pass --> E[merge]
+ D -- fail --> C
+ E --> F([End])
+```
+
+**Step 5: Attach a checkpoint.** This is one of the biggest differences between a graph and a one-shot script: **the state is persisted after every step**, so if the process dies you resume from the checkpoint instead of starting over. With one attached, your graph gains interrupt/resume for free — and you can also pause before merge to wait for human approval, which is what last lecture's "human review" looks like on a graph:
+
+```
+checkpoint = on(graph, every_step) # save state after every step
+graph.pause_before("merge") # stop before merging, wait for approval
+```
+
+**Step 6: Run the graph with an entry point.** Pass a thread id on every run — the checkpoint uses it to tell runs apart:
+
+```
+run(graph, entry={"requirements": "fix the login page bug"}, thread="session-1")
+```
+
+When you're done, hold this against the diagram above: your hand-written `graph.md` is the blueprint, and the code in an engine is the blueprint turned into an executable program. The two should match one-to-one. If they don't — either the diagram is wrong or the code is wrong, **and that's exactly what "a graph puts the problem on paper" means**: before, a mismatch went unnoticed by everyone; now it's visible at a glance. If you want a runnable reference implementation, see `code/maker_checker_graph.py` — it uses LangGraph, but by the end you should recognize it: it's just these six steps.
+
+## Open-Source Projects: After the Name, Before the Name
+
+First, draw the line: **"Graph Engineering" is a name that only exists after July 18, 2026.** Frameworks open-sourced before that date are not "post-release Graph Engineering projects." As of early August 2026, only one open-source project carrying the name holds up:
+
+**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.
+
+**Pre-release projects (they don't call it Graph Engineering — but they're what you actually build with)**
+
+Before July 2026, these tools already existed for one to three years: LangGraph (open-sourced in 2024, 65M+ monthly downloads, the engine behind the reference implementation above), CrewAI, Microsoft Agent Framework, LlamaIndex Workflows, Google ADK, OpenAI Agents SDK, Mastra, Claude Agent SDK. **They aren't "post-Graph-Engineering projects" — they're the evidence that Graph Engineering existed before it got the name.** Nodes, edges, shared state, and routing have been running for three to five years; July just gave them a new label. A graph engine doesn't solve design problems: it hands you nodes, edges, and checkpoints, but it won't answer "which loops feed which, who owns the targets, who can veto." Until those questions are settled, switching engines just makes the same bad design prettier.
+
+## Cold Water: A Graph Is Not a Silver Bullet
+
+Three buckets of cold water, lightest first.
+
+**Bucket one: the fake numbers.** After Graph Engineering went viral, claims circulated about "+18% accuracy, −85% cost" from adopting graphs. A [fact-check by Korean blogger goddaehee](https://goddaehee.tistory.com/628) (July 30) finds: the two numbers do exist, but they come from a March 2026 paper about chemical piping and instrumentation diagrams (P&ID) — and the 18% is measured against the raw image while the 85% is measured against a different baseline. Marketing pasted two differently-baselined numbers into one "before/after" story, and the paper never even uses the phrase "graph engineering." Whenever you see "graph engineering gives you X% improvement" marketing, ask for the original source.
+
+**Bucket two: shape is not the load-bearing wall (iii.dev).** Covered above. A loop is just a graph with one node; state machines have run for decades. People who declare "loops are dead" or "graphs are dead" usually haven't read either one carefully. Learn the patterns, not the nouns.
+
+**Bucket three: the Orchestration Tax.** Addy Osmani's *The Orchestration Tax* (May 2026) contains the hardest economics of the graph/multi-agent era: **starting an agent is cheap. Closing the loop on one is expensive.**
+
+Launching an agent is a keystroke. But closing an agent's loop means someone checks what came back and reconciles it with whatever the other agents touched — **that someone is you, and there is exactly one of you.** Osmani's words:
+
+> "You are the GIL of your AI agents. They can all run at once. But when any of their work needs genuine understanding of the architecture or resolving merge conflicts, that work has to acquire the lock. There is one lock. You hold it."
+
+This is why "review bandwidth is the ceiling" from the last lecture gets sharper here: **a graph makes more agents run in parallel, but your judgment is a serial resource. It does not parallelize.** Adding nodes optimizes the part that was never the bottleneck — the bottleneck is always the one serial processor: you.
+
+## When You Actually Need a Graph
+
+Not every task deserves a graph. Five criteria — try at least three before you start:
+
+1. **The task decomposes into independent work units** — parts that don't depend on each other and can run in parallel
+2. **There are branch or rollback paths** — "where do tests go back to," "where does insufficient info go back to" are paths worth declaring explicitly
+3. **Intermediate state is worth saving** — you can pause at checkpoints and resume, instead of restarting from zero
+4. **Results can be verified explicitly** — every node has an automatically checkable definition of done
+5. **Coordination benefits > coordination costs** — the time saved by parallelism outweighs the overhead of the graph and its shared state
+
+**"Complex" doesn't mean "many steps."** A 20-step linear pipeline doesn't need a graph — that's a workflow, or just a script. A structure with only 5 nodes but real rollback, parallelism, and approvals does need a graph. The deciding factor isn't scale — it's **the existence of branches and rollbacks.**
+
+## Core Concepts
+
+- **Graph Engineering**: the practice of organizing multiple agents, loops, tools, and evaluators into an explicit graph (nodes + edges + shared state + routing rules), making the connections, shared state, and path choices of multiple work units designable, observable, and locally repairable.
+- **Four stacked layers**: prompt → context → loop → graph. Each layer controls something different (instruction, information, runtime, system); the later layer doesn't replace the earlier ones — it puts them inside its nodes.
+- **The four parts of a graph**: nodes (work units), edges (handoffs), shared state (the common workspace), routing rules (where execution goes next).
+- **Three structural failures of a single loop**: Goodhart (the numbers went up, the business got worse), blindness upward (it never asks "is this the right goal?"), conflict (independent loops undermine each other). A graph turns these into explicit relationship design.
+- **Graph ≠ Workflow**: workflow nodes are deterministic functions and edges are hardcoded code; graph nodes can be full agents and edges can route dynamically. A graph is the generalization of a workflow.
+- **Anchors**: the mechanisms that pin a network of loops to the real world (actual business outcomes, ground truth, human spot-checks). The easiest part of graph design to skip, and the one you can't afford to.
+- **The Orchestration Tax**: starting agents is cheap, reviewing results is expensive. Your attention is the only serial resource, and adding nodes doesn't optimize it.
+
+## Key Takeaways
+
+- **Graph Engineering doesn't replace Loop Engineering — it builds on top of it.** A loop is a node in a graph; the three things from the last lecture (goal, verification, stop condition) become the node's internal structure.
+- **A graph turns deferred decisions into up-front decisions.** A loop hides failure modes inside the loop; a graph puts them on paper — readable, auditable, locally repairable.
+- **What's inside the node decides the difference between a graph and a workflow.** Functions make a workflow; agents make a graph. That's the only genuinely new wine in the old bottle.
+- **Ask the four design questions before drawing:** which loops feed which, who owns the targets, who can veto/roll back, which metrics may move and which must stay frozen. If you can't answer them, don't draw.
+- **Don't draw graphs for their own sake.** Five criteria: independently decomposable, has branches or rollbacks, intermediate state worth saving, results verifiable, coordination benefits > coordination costs.
+- **Your review bandwidth is still the ceiling.** A graph runs more agents in parallel, but your judgment is serial — the orchestration tax doesn't disappear because there are more nodes.
+- **Keep the counterargument.** Shape isn't the load-bearing wall; replayability, observability, and recoverability are. Nouns change every six weeks. Engineering capability doesn't.
+
+## Further Reading
+
+- [Prefect: Loops vs. Graphs (Jul 2026)](https://www.prefect.io/blog/loops-vs-graphs) — loops and graphs from a company that has built graph orchestration for decades
+- [Eigent: Graph Engineering for AI Agents (Jul 2026)](https://www.eigent.ai/blog/graph-engineering-ai-agents) — three structural failures of single loops + the four design questions + anchors
+- [iii.dev: Loops, Graphs, and the Layer That Matters (Jul 2026)](https://iii.dev/blog/loops-graphs-and-the-layer-that-matters/) — the clearest counterargument: "shape is not the load-bearing wall"
+- [Rohit (@rohit4verse): the original thread (Jul 29, 2026)](https://x.com/rohit4verse/status/2082478623043547356) — the primary source for the four-layer framework: prompt → context → loop → graph, each layer composing on top of the last
+- [Agent Times: Graph Engineering as the Final Layer (Jul 2026)](https://theagenttimes.com/articles/graph-engineering-emerges-as-proposed-final-layer-of-agent-o-4f0511a8) — a clean summary of Rohit's four-layer framework
+- [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)
+- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — a head-to-head of seven mainstream open-source frameworks: LangGraph, CrewAI, Microsoft Agent Framework, LlamaIndex, Google ADK, OpenAI Agents SDK, Mastra
+- [LangGraph official docs](https://docs.langchain.com/oss/python/langgraph/graph-api) — "Nodes do the work, edges tell what to do next"; the precise definitions of nodes and edges, the first-hand reference for building graphs
+- [Anthropic: Building Effective Agents (Dec 2024)](https://www.anthropic.com/engineering/building-effective-agents) — five patterns that are graphs when drawn; the authoritative workflow-vs-agent distinction
+- [Addy Osmani: The Orchestration Tax (May 2026)](https://addyosmani.com/blog/orchestration-tax/) — why your attention is the only serial resource
+- [Addy Osmani: Orchestrating Coding Agents (talk)](https://talks.addy.ie/oreilly-codecon-march-2026/) — from subagents to agent teams to quality gates
+- [Addy Osmani: Loop Engineering (Jun 2026)](https://addyosmani.com/blog/loop-engineering/) — the core reference of the last lecture; prerequisite for graph engineering
+- Lecture 13: [From Manual Prompting to Autonomous Loops](./../lecture-13-loop-engineering/index.md) — a loop is a node in a graph; understand the node before you understand the graph
+- Lecture 11: [Why Observability Belongs Inside the Harness](./../lecture-11-why-observability-belongs-inside-the-harness/index.md) — the more complex the graph, the more observability matters; an unobservable graph is just a bigger black box
+- Lecture 09: [Why Agents Declare Victory Too Early](./../lecture-09-why-agents-declare-victory-too-early/index.md) — why the verify node must be independent of the implement node; in a graph this is a structural problem, not a prompt problem
+
+## Exercises
+
+1. **Draw your P07 maker-checker loop as a graph:** explicitly write out nodes, edges, shared state, and routing rules in a `graph.md`. Mark which edges are conditional (verify passed/failed) and which are rollback edges (failed back to implement). When you're done, answer: is there any edge that was implicit — previously hidden inside the agent's context?
+
+2. **Answer eigent's four questions:** find three independent loops you're running (or three automations in the same project), and answer: which loops feed which? Which loop owns a target another loop chases? Is there a loop that can veto another loop's output? Which metrics are being optimized in ways that could conflict?
+
+3. **Goodhart self-check:** examine a metric you've been optimizing recently. When it went up, did the real outcome (business results, user feedback, code quality) get better too? If only the number rose, which direction is this loop learning to lie to you?
+
+4. **Score a candidate with the five criteria:** pick a task you're torn about "graphifying" and score it against the five criteria. It needs at least three to be worth a graph. If it scores below three, what it actually needs is a better workflow script — don't draw a graph just to draw a graph.
+
+5. **Turn your `graph.md` into an executable program:** follow the six steps in "Build Your First Graph from Scratch" and implement your maker-checker diagram as a runnable graph (reference implementation: `code/maker_checker_graph.py`, written with LangGraph). Don't skip any of the six: define the state, list the nodes, wire the edges, write the router, attach a checkpoint, run it. Then diff the diagram against the code and find the first place they disagree, and explain why — was the diagram wrong, or the code wrong?
diff --git a/docs/en/projects/project-08-graph-engineering-first-graph/index.md b/docs/en/projects/project-08-graph-engineering-first-graph/index.md
new file mode 100644
index 0000000..ab8a7ab
--- /dev/null
+++ b/docs/en/projects/project-08-graph-engineering-first-graph/index.md
@@ -0,0 +1,91 @@
+# Project 08. Draw Your Workflow as a Graph
+
+> Related Lecture: [L14. From Single Loops to Graph Engineering](./../../lectures/lecture-14-graph-engineering/index.md)
+
+## What You'll Do
+
+This is the transition project from "Loop" to "Graph." In the last project you built a maker-checker loop — implement, verify, feed back, implement again — where every decision happened inside one agent's context window. In this project you'll **make the structure that was hidden inside the loop explicit**: nodes, edges, shared state, and routing rules, written out word by word.
+
+You'll do three progressive experiments: first draw your P07 maker-checker loop as an explicit graph, then add a parallel fan-out/fan-in node, then add a conditional rollback edge and a human-approval node. When you're done, you'll have felt this firsthand: **a graph isn't a new invention — it's what your loop becomes once it's complex enough.**
+
+## Tools You'll Use
+
+- Claude Code or Codex
+- Git
+- The maker-checker loop you built in P07 (or any agent workflow you can run repeatedly)
+- A text editor or diagramming tool (drawing is not for looks — it's for getting the structure down on paper; `mermaid` or a hand-written `graph.md` both work)
+
+## Steps
+
+### Prep
+
+1. Start from the repo where you finished P07, or from any agent workflow you're currently running.
+2. Create three branches: `p08-explicit-graph`, `p08-parallel`, `p08-human-in-the-loop`.
+3. Prepare a `state.md` as your shared state file: requirements, progress, and verification results all live here. This is the graph's "common workspace."
+
+### Experiment 1: Draw the Loop as an Explicit Graph
+
+Switch to the `p08-explicit-graph` branch.
+
+1. **List every node**: write each step of the P07 maker-checker loop as a node. For each node, write down: its responsibility, its inputs, its outputs, and whether it's an agent or deterministic code.
+2. **Draw every edge**: list each edge between nodes. Flag two special kinds:
+ - Conditional edges: verify passed/failed — which path does each take?
+ - Rollback edges: where does a failure return to?
+3. **Write the shared state**: explicitly list the fields in the state (requirements, code, test results, review conclusions) and who reads/writes each.
+4. **Write the routing rules**: state "where does execution go next" in the plainest if-then language, e.g.:
+ ```
+ if verify passed → merge node
+ if verify failed → implement node
+ if implement node lacks information → research node
+ ```
+5. **Write it all up as `graph.md`**: turn the above into one document — a mermaid diagram plus a node table and the routing rules.
+6. **Answer this question**: after drawing, find at least one **edge that was implicit** — a decision path that used to live inside the agent's context, one you didn't even know existed.
+
+### Experiment 2: Add a Parallel Fan-out / Fan-in Node
+
+Switch to the `p08-parallel` branch.
+
+1. **Pick a point that can parallelize**: find a spot where the task can be split into two independent parts. For example:
+ - Split implementation into two independent modules, written in parallel by two agents
+ - Split verification into two independent reviews: one runs tests and lint, the other does code review (different instructions, different focus)
+ - Split research into two directions, one agent per direction
+2. **Write the fan-out rule**: record in shared state that "this task is split into N parallel subtasks," each with its own context and its own node.
+3. **Write the fan-in rule**: once all subtasks finish, who merges the results? What's the merge standard (e.g., both reviews must pass, or one is enough)?
+4. **Isolate with worktrees**: run each parallel subtask in its own git worktree to physically avoid file collisions (review the Worktree primitive from Lecture 13).
+5. **Run once and record**: record wall-clock time, token cost, and result quality before and after parallelization. Is parallelization actually faster? Or did coordination overhead eat the savings?
+
+### Experiment 3: Add a Rollback Edge and a Human-Approval Node
+
+Switch to the `p08-human-in-the-loop` branch.
+
+This is the most important of the three experiments. You'll add two kinds of nodes to the graph:
+
+1. **Conditional rollback edge**: give the verify node a "partially passed" path — instead of bouncing the whole thing back to the implement node, return with specific feedback to **the node that produced the problem**. For example: tests all pass but code review finds the requirements were misunderstood — roll back to the research node, not the implement node. This requires your shared state to record "which layer the problem came from."
+2. **Human-approval node (human-in-the-loop)**: insert a human node before the merge node. Execution **stops** here and waits for you to write "approved" or "rejected" in `state.md`. The approval node can have a timeout rule: after N hours with no response, auto-reject or auto-escalate.
+3. **Write the interrupt format**: how should an approval request be written — what happened, what changed, why a human is needed, what are the consequences of approving/rejecting?
+4. **Run at least 2 full passes**: each pass stops at the human-approval node and you approve or reject once. Record: did your approval decisions agree with the verify node? Did the approval node catch anything the verify node missed?
+
+## How to Measure Results
+
+| Metric | Exp 1 (Explicit graph) | Exp 2 (Parallel) | Exp 3 (Human-in-the-loop) |
+|--------|----------------------|-----------------|---------------------------|
+| Structural visibility | How many implicit edges did you find? | Can shared state support parallel subtasks? | Can the rollback edge pinpoint the problem layer? |
+| Failure localization | Can you point at which edge is wrong? | When a subtask fails, can you locate which one? | When approval rejects, can you name the layer? |
+| Coordination cost | How long did writing the graph take? | Time saved by parallelism vs. coordination overhead | Approval wait time vs. value of problems caught |
+| Observability | Can you now see what happens at each step? | Is every subtask's state visible? | Are approval requests written clearly? |
+| Reliability | Does the graph description match actual runs? | Is the fan-in merge standard sound? | Do the timeout/escalation rules actually fire? |
+
+## What to Submit
+
+- `graph.md` (Experiment 1's complete graph description: mermaid diagram + node table + edge table + shared state fields + routing rules)
+- The list of implicit edges you found in Experiment 1 (at least one)
+- Experiment 2's fan-out/fan-in rules and one parallel run record (time/cost/quality comparison)
+- Experiment 3's rollback-edge rules, approval-node format, and 2 rounds of human-in-the-loop records
+- Final retro: as you moved from loop to graph, how did your way of working change? Which tasks deserve a graph, and which don't?
+
+## Related Lectures
+
+- [Lecture 14 — From Single Loops to Graph Engineering](../../lectures/lecture-14-graph-engineering/index.md)
+- [Lecture 13 — From Manual Prompting to Autonomous Loops](../../lectures/lecture-13-loop-engineering/index.md) (your loop is a node in a graph; this project unfolds that node's internal structure)
+- [Lecture 09 — Why Agents Declare Victory Too Early](../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md) (why the verify node must be independent of the implement node — a structural problem, not a prompt problem)
+- [Lecture 11 — Why Observability Belongs Inside the Harness](../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) (the more complex the graph, the more you need to see what each node is doing)
diff --git a/docs/es/lectures/lecture-14-graph-engineering/index.md b/docs/es/lectures/lecture-14-graph-engineering/index.md
new file mode 100644
index 0000000..7d4c0cc
--- /dev/null
+++ b/docs/es/lectures/lecture-14-graph-engineering/index.md
@@ -0,0 +1,349 @@
+[English Version →](../../../en/lectures/lecture-14-graph-engineering/)
+
+> Ejemplos de código: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-14-graph-engineering/code/)
+> Proyecto práctico: [Proyecto 08. Dibuja Tu Flujo de Trabajo como un Grafo](./../../projects/project-08-graph-engineering-first-graph/index.md)
+
+# Lección 14. De los Loops Únicos a la Ingeniería de Grafos
+
+Seis semanas después de que la lección anterior terminara de contar Loop Engineering, el 18 de julio de 2026, Peter Steinberger — el autor de OpenClaw de la lección anterior, aquel que dijo "deja de hacerle prompting a tu coding agent" — publicó un tweet:
+
+> "¿Todavía hablamos de loops, o ya hemos pasado a los graphs?"
+
+Un tweet — unas 575 mil visitas en un día, subiendo a unos 3 millones para fin de mes. Unas horas después, el ingeniero de ML Hamel Husain publicó *Loop Engineering Is Dead. Enter Graph Engineering* — un artículo cuyo cuerpo entero era un solo GIF de "Stop it" — y consiguió otras ~680 mil visitas.
+
+Lo más interesante: **los dos estaban bromeando.** Uno satirizaba a una industria que inventa un término nuevo cada seis semanas; el otro seguía el chiste. Pero el chiste sobrevivió alrededor de un fin de semana — cursos, hojas de ruta y stacks de herramientas inundaron el timeline antes de que terminara el fin de semana, seguidos de un montón de números inventados: la afirmación de "+18% de precisión, −85% de coste" es falsa (los dos números existen, pero provienen de un artículo sobre diagramas de tuberías químicas y comparan contra líneas base completamente diferentes), y la afirmación de que "Microsoft, Stanford y Anthropic descubrieron la ingeniería de grafos al mismo tiempo" también es falsa. La verificación de datos confirma un único "precursor" real: Josh Simmons, cuyo *We Are Entering the Graph Engineering Phase* está fechado el 4 de julio — dos semanas completas antes del chiste. **El chiste hizo que el concepto se volviera popular. No fue el chiste el que lo creó.**
+
+> Fuentes: [goddaehee: Verificación de datos de Graph Engineering (2026-07-30)](https://goddaehee.tistory.com/628); [YC Startup School 2026: Entrevista a Jensen Huang (con transcripción)](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia); [explainx: Graph Engineering (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026)
+
+Esta lección no trata de echar más leña al fuego de la palabra de moda, sino de desarmarla y verla con claridad: **¿por qué un loop único inevitablemente se convierte en un grafo? ¿Qué diferencia hay realmente entre un grafo y un workflow? ¿Y cuándo lo necesitas de verdad, y cuándo no?**
+
+## prompt, context, loop, graph: cuatro nombres, una capa sobre la otra
+
+A finales de julio, el ingeniero Rohit (@rohit4verse) publicó un [hilo largo](https://x.com/rohit4verse/status/2082478623043547356) que organizaba la historia de los nombres de la ingeniería de IA de los últimos años en un marco claro de cuatro capas. Es el mejor sistema de coordenadas para entender Graph Engineering:
+
+| Capa | Lo que da forma | La pregunta que responde | Artefactos clave |
+|------|---------------|------------------------|------------------|
+| **Prompt Engineering** | La instrucción | ¿Cómo le decimos al modelo qué hacer? | instructions, examples, constraints, roles, output formats |
+| **Context Engineering** | La información | ¿Qué debería saber el modelo antes de decidir? | documents, history, memory, tool definitions, environment state |
+| **Loop Engineering** | El runtime | ¿Cómo hacemos que el modelo itere solo hasta lograr el objetivo? | observe, reason, act, inspect, update, condición de parada |
+| **Graph Engineering** | El sistema | ¿Cómo colaboran múltiples agentes, loops, herramientas y evaluadores? | nodos, aristas, estado compartido, reglas de routing |
+
+Fíjate en cómo se lee esta línea: **cada capa no reemplaza a la anterior — se apila encima de ella.**
+
+- Después de encontrar el context engineering, no dejaste de hacer prompt engineering — cada iteración sigue necesitando un prompt; el loop solo lo refresca cuando el entorno cambia.
+- Después de construir loops, tampoco descartaste el context — cada ronda de un loop tiene que reensamblar su contexto.
+- Al llegar al grafo, ni el prompt, ni el context, ni el loop han desaparecido: **cada nodo lleva su propio prompt, su propio context, sus propias herramientas, su propia memoria y su propio loop.** El grafo decide cómo se conectan los nodos.
+
+Rohit cierra su hilo con estas palabras:
+
+> Una vez que un agente necesita especialización, paralelismo, estado compartido, verificación y recuperación, ya no es un loop. Es un grafo.
+
+**Espera — ¿y el harness?** En estos cuatro nombres no está Harness Engineering, y sin embargo este curso trata del harness. La razón es simple: Rohit contaba la historia de las palabras de moda, su final era el grafo, y la capa del medio quedó saltada. Y ni siquiera está clara la capa en la que debería estar el harness — [explainx](https://explainx.ai/blog/context-prompt-loop-harness-engineering-stack-2026) lo pone encima del loop, y el [paper de Buildrix](https://arxiv.org/abs/2606.25139) lo pone debajo. Este curso lo decidió en la segunda lección: el harness es la base; el loop y el grafo se construyen sobre él.
+
+Esto explica un fenómeno curioso: por qué "Graph Engineering" no se hizo viral hasta julio de 2026, y sin embargo todo el mundo descubrió que "ya lo estaba haciendo desde hace tiempo". Porque el grafo no es un invento nuevo — es lo que el loop se convierte automáticamente cuando tu tarea es lo bastante compleja. **El nombre llegó después; la práctica ya existía.**
+
+## Desarma el grafo: nodos, aristas, estado, routing
+
+Reduce el grafo a sus cuatro piezas más simples.
+
+**Nodo (Node)**: una unidad de trabajo con una responsabilidad. Puede ser:
+- código determinista (ejecutar tests, calcular cobertura)
+- una llamada de modelo (generar documentación)
+- una herramienta (git commit, enviar un mensaje)
+- un agente completo — con su propio loop, capaz de entender objetivos, usar herramientas y reintentar por su cuenta cuando no avanza
+
+Qué puede ser un nodo es la verdadera línea divisoria entre la ingeniería de grafos y la ingeniería de workflows. Se explica en detalle más abajo.
+
+**Arista (Edge)**: expresa cómo se hace la entrega entre nodos. No es tan simple como "primero A y luego B" — una arista puede expresar:
+- **Paralelismo**: después de A, B y C empiezan al mismo tiempo
+- **Condición**: si el test pasa, ve por la izquierda; si falla, ve por la derecha
+- **Fallo/reintento**: el nodo se cae, vuelve a sí mismo y se ejecuta otra vez
+- **Retroceso**: la verificación no pasa, vuelve al nodo de implementación que está tres pasos atrás
+
+**Estado compartido (State)**: el paquete de datos que se transmite entre nodos. Requisitos, notas de investigación, versiones de código, resultados de tests, conclusiones de revisión — todo se escribe en el mismo espacio de trabajo común. Los nodos no se hablan directamente entre sí; todos leen y escriben el mismo estado.
+
+**Reglas de routing (Routing)**: deciden a dónde ir a continuación. Es el "control de flujo" del grafo, dicho de la forma más simple:
+
+> Si el test pasa, entrega; si el test falla, vuelve al nodo de implementación; si la información es insuficiente, vuelve al nodo de investigación.
+
+Junta las cuatro piezas y un grafo de desarrollo típico se ve así:
+
+```mermaid
+flowchart TD
+ S["Estado compartido<br/>Requisitos / notas / código / resultados"] --- R["Nodo de investigación<br/>Agente: localizar el problema"]
+ R -->|"Produce plan"| I["Nodo de implementación<br/>Agente: escribir cambios + tests"]
+ I -->|"Produce código"| V["Nodo de verificación<br/>Agente: revisión independiente + ejecutar tests"]
+ V -->|"No pasa"| I
+ V -->|"Pasa"| M["Nodo de merge<br/>Código: commit + actualizar estado"]
+ M -->|"Actualizar estado"| S
+ I -->|"Información insuficiente"| R
+```
+
+Fíjate en la comparación con el grafo de loop de la lección anterior: la anterior era un anillo — descubrir, despachar, verificar, persistir, y volver a descubrir. En el grafo de esta lección, **el anillo sigue ahí, pero está descompuesto en nodos y aristas explícitos.** El nodo de verificación puede devolver directamente el fallo al nodo de implementación, y el nodo de implementación puede volver al nodo de investigación por información insuficiente — estas "aristas de retroceso" en un loop único son implícitas: es el propio agente el que recuerda en su contexto que "debe volver atrás".
+
+## Cuándo un loop no alcanza
+
+Un loop tiene un solo camino principal. En el loop maker-checker que construiste en la lección anterior, todas las decisiones — qué hacer después, a dónde ir si falla — ocurren dentro de la ventana de contexto del mismo agente. Cuando la tarea se complica un poco más, aparecen cuatro problemas:
+
+1. **División del trabajo**: el agente que investiga los requisitos, el que escribe el código y el que hace los tests — ¿quién empieza primero?
+2. **Paralelismo**: ¿qué trabajo se puede hacer al mismo tiempo?
+3. **Retroceso**: después de que falle el test, ¿a dónde se vuelve — al nodo de implementación o al nodo de investigación?
+4. **Entrega**: ¿cómo ven varios agentes los mismos requisitos, notas y resultados de tests? Si el revisor no está de acuerdo con el implementador, ¿a quién se le hace caso?
+
+Jensen Huang dijo algo similar en la [entrevista de Startup School 2026](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia) de Y Combinator (en conversación con Garry Tan): a medida que la implementación de base se automatiza cada vez más con agentes, el valor central de los humanos se desplaza a "diseñar sistemas, definir restricciones claras y tener control fino sobre los agentes". Su ejemplo de control era muy concreto — "después de que el agente da su plan, yo cambio una palabra en el archivo del plan, y esa palabra produce una diferencia precisa en un solo punto" — y también predijo que la habilidad central del futuro es el "pensamiento sistémico" (systems thinking).
+
+El golpe más brillante del hilo de discusión vino de Luis Catacora:
+
+> **"Un loop tiene mucho margen para la tolerancia a fallos. Un grafo te obliga a admitir cuántas partes de tu flujo de trabajo nunca han sido modeladas realmente."**
+
+Esta frase señala la diferencia profunda entre loop y grafo:
+
+- **El loop es decisión diferida.** Primero dejas que un agente se encargue de todo el trabajo; si no avanza, ya se verá; la arquitectura se puede posponer. Es cómodo, pero el coste es que los modos de fallo son invisibles — nunca sabes en qué paso se atascó, porque ni siquiera él mismo lo sabe.
+- **El grafo es decisión anticipada.** Tienes que declarar toda la estructura por adelantado: quién se encarga de qué, cómo dependen las tareas entre sí, a dónde vuelve cada fallo. Es más trabajoso, pero a cambio obtienes algo legible, auditable y reparable localmente.
+
+Dicho más directamente: **el loop esconde el problema dentro del ciclo; el grafo pone el problema sobre el papel.** El primero sirve para explorar; el segundo, para producción.
+
+## Los tres fallos estructurales del loop único
+
+¿Por qué un loop único no aguanta a escala? El artículo *Graph Engineering for AI Agents: Beyond Single Feedback Loops* de eigent.ai identifica tres fallos estructurales — fíjate que son estructurales, no un bug de un loop concreto.
+
+**Primero, una objeción: ¿no se pueden añadir checkpoints dentro del loop?** Se puede. La verificación, las condiciones de parada e incluso los reintentos desde un punto de ruptura de la lección anterior — el loop las admite todas. Pero los tres fallos siguientes son justamente lo que los checkpoints no pueden resolver — porque los checkpoints de un loop crecen dentro del mismo agente: el que comprueba y el que tiene el problema son el mismo cerebro, la misma ventana de contexto. Detiene "entregar sin verificar", pero nunca se pregunta "¿este indicador es el correcto?" o "¿merece la pena perseguir este objetivo?" — la respuesta está escrita en su propio context, y no puede verla. El grafo no te da más checkpoints; lo que hace es **sacar la comprobación fuera**: de "dentro del agente" a "un nodo independiente", dándole una ventana de contexto completamente nueva (como se explicó en la sección del nodo verify). Ahí está el sentido de "estructural": no es que al loop le falte una pieza, es que "el que juzga y el que es juzgado comparten el mismo cerebro" — esa estructura en sí misma es el problema.
+
+### 1. Goodhart: el número sube, pero el negocio empeora
+
+Lleva cualquier indicador único al extremo y dejará de medir lo que crees que mide. Caso clásico: un equipo de soporte construyó un loop alrededor de la "tasa de resolución de tickets". Los datos semanales no paraban de subir. Meses después, los datos de renovación mostraban que el churn se había duplicado — **el bot había aprendido a cerrar tickets**: desviar el tema, disuadir al usuario de preguntar más, y marcar como "resuelto" problemas que no estaban resueltos.
+
+El loop hizo todo lo que se le pidió. Solo que el número se había separado de lo que al negocio realmente le importa. Eso es la ley de Goodhart.
+
+### 2. Ceguera hacia arriba: nunca pregunta "¿es correcto este objetivo?"
+
+Dentro de un loop, la referencia es sagrada. Un termostato no pregunta "¿68°F es la temperatura correcta?". Un loop de ventas no pregunta "¿es razonable esta cuota?". Un loop de evals de agentes no pregunta "¿coincide este benchmark con los resultados reales del negocio?".
+
+**Quienquiera que eligiera el objetivo, el loop corre hacia él, aunque desde el principio no fuera lo que debía perseguir.** En la estructura de un loop único no hay ningún lugar donde quepa esta pregunta.
+
+### 3. Conflicto: loops independientes se sabotean entre sí
+
+En un sistema real hay decenas de loops, cada uno construido de forma independiente. El loop de velocidad de respuesta sabotea al loop de calidad de profundidad; el loop de crecimiento sabotea al loop de calidad. Cada loop está sano en su propio dashboard, pero el sistema en conjunto tiembla — como varias personas tirando de la misma cuerda en direcciones distintas.
+
+**Graph engineering responde justamente al conjunto de preguntas que un loop único no puede responder:**
+
+- ¿Qué loops alimentan a qué loops?
+- ¿Qué loops poseen los objetivos que otros loops persiguen?
+- ¿Qué loops pueden vetar o revertir un cambio?
+- ¿Qué indicadores pueden moverse y cuáles deben congelarse?
+
+Cuando en un sistema existen "loops que pueden comerse tu objetivo" y "loops que pueden vetar tu cambio", la relación entre ellos se convierte en un objeto de ingeniería — y las relaciones entre relaciones, dibujadas, son un grafo.
+
+### Anclas: fijar los loops a la realidad
+
+El artículo de eigent tiene una sección que "todo el mundo se salta": **anchors (anclas)**. Por muy refinada que sea la red de loops, si cada loop se aleja de la realidad, la red no es más que una resonancia de deriva mutua. Una ancla es lo que fija un loop al mundo real — resultados reales de negocio, conjuntos de datos ground truth, muestreos manuales. Al diseñar un grafo, las anclas son el paso que más fácil se salta — y el que menos se puede omitir.
+
+## Graph vs. Workflow: no es solo cambiar el nombre
+
+Esta es la parte de la lección que más se malinterpreta, y merece que la tratemos aparte.
+
+La primera reacción al boom de Graph Engineering, cualquier ingeniero con experiencia lo murmura: "¿Pero esto no es un workflow? DAGs, máquinas de estado, motores de flujo de trabajo — los llevamos corriendo décadas."
+
+**Esa intuición es correcta a medias.** El grafo y el workflow comparten de hecho el mismo esqueleto: nodos + aristas + estado compartido + routing. La forma en que Airflow, Prefect, Dagster y Temporal han orquestado durante décadas es exactamente este grafo. Y los cinco patrones que Anthropic resumió en diciembre de 2024 en *Building Effective Agents* — cadenas de prompts, routing, paralelización, orquestador/trabajadores, evaluador/optimizador — dibujados, no son más que grafos de ejecución con formas distintas.
+
+**La mitad que está mal está dentro del nodo.** Los nodos de un workflow tradicional son **funciones deterministas**: una función de Python, un script de shell, una tarea SQL. Las aristas son código fijo: `if`, `switch`, `case`. Todo el sistema lo mantiene el ingeniero con código, y el comportamiento es predecible — la misma entrada siempre recorre el mismo camino.
+
+El nodo de la ingeniería de grafos puede ser un **agente completo**: con su propio loop, capaz de usar herramientas, entender objetivos y reintentar por su cuenta ante un fallo. Y la arista tampoco tiene por qué estar fijada en código — puede llevar reglas de routing, donde el siguiente paso lo decide la salida del nodo anterior, el resultado de la verificación, o incluso otro modelo.
+
+Para explicar bien esta diferencia, tomamos prestado un par de conceptos de Anthropic. Anthropic distingue workflow y agente con una frase: **¿quién decide el control de flujo?** Si el código decide los pasos, es un workflow; si el modelo puede cambiar los pasos en tiempo de ejecución, es un agente.
+
+Entonces, ¿qué es un grafo? **Un grafo es el contenedor de ambos.** En un mismo grafo puede haber a la vez:
+
+- nodos de workflow: ejecutar tests, calcular cobertura — código determinista, no necesita modelo
+- nodos de agente: implementar funciones, revisar código — agentes completos impulsados por modelo
+- nodos humanos: aprobación, revisión — nodos de interacción humano-máquina; cuando el flujo llega aquí, se detiene y espera a que una persona dé el visto bueno
+
+Así que la afirmación correcta es: **Graph Engineering no es un sustituto del Workflow, es una generalización del Workflow** — amplía el tipo de nodo de "función" a "agente", y la decisión de la arista de "código estático" a "routing dinámico". El workflow es ese caso particular del grafo en el que todo es "completamente determinista".
+
+La visión contraria (*Loops, Graphs, and the Layer That Matters* de iii.dev) aterriza en el mismo punto, solo que con la conclusión opuesta:
+
+> "La forma es la parte fácil, y es desechable. Las decisiones que soportan peso son de qué están hechos el loop o el grafo, y cómo se comportan después de que funcionan."
+
+Lo que iii.dev quiere decir: no conviertas la "topología" en un logro de ingeniería. La ingeniería de workflows lleva décadas corriendo, y lo que realmente se ha asentado no es cómo se conectan los nodos, sino **reproducibilidad, observabilidad y recuperación** — si algo sale mal se puede reproducir, durante la ejecución se puede observar, y si se cae se puede continuar. La forma del grafo la puedes cambiar cuando quieras; estas capacidades de soporte de peso son donde deberías invertir. Esta crítica merece quedarse en la memoria: **dibujar el grafo no es el objetivo; cuánta capacidad de ingeniería puede soportar encima el grafo es el objetivo.**
+
+## Ya estabas dibujando grafos
+
+"Vino viejo en odres nuevos" tiene además otra prueba: las herramientas ya estaban listas.
+
+- **LangGraph**: se publicó en enero de 2024; para julio de 2026 rondaba los 65 millones de descargas mensuales. Es un motor de ejecución de grafos para agentes: los nodos pueden ser agentes y las aristas pueden llevar routing condicional, checkpoints e interrupts.
+- **Los cinco patrones de Anthropic**: *Building Effective Agents* de diciembre de 2024 ya había dibujado los grafos de cadenas de prompts, routing, paralelización, orquestador/trabajadores y evaluador/optimizador — solo que no los llamó Graph Engineering.
+- **El fan-out de subagentes de Claude Code**: cuando haces que un agente principal despache a un montón de subagentes para trabajar en paralelo, ya estás construyendo un grafo — solo que no te diste cuenta.
+- **Máquinas de estado, scheduling de DAGs, colas de tareas, grafos de conocimiento**: en las décadas de ciencias de la computación, la ingeniería de grafos no es un problema nuevo.
+
+¿Qué es realmente nuevo? **El nodo pasó de "función" a "agente".** Ese es el único cambio, y es todo el cambio. Antes, para escribir un nodo de workflow tenías que especificar su lógica, su manejo de errores y su estrategia de reintentos. Ahora un nodo solo necesita una instrucción — "investiga este problema", "revisa este código" — y el resto lo hace el modelo. El nodo se ha vuelto barato, y por eso el grafo ha pasado a valer la pena dibujarlo.
+
+## Construye tu primer grafo desde cero
+
+Basta de teoría, manos a la obra. El maker-checker de la lección anterior es **un** agente que se hace loop a sí mismo. Lo primero que hace Graph Engineering es desarmar ese agente monolítico: **cada nodo se convierte en un agente especializado, cada uno con su prompt privado, su context, sus tools, su memory y su propio loop pequeño; los nodos no comparten contexto entre sí, solo se pasan el relevo a través de un estado compartido.** Esta es la versión en lenguaje humano de la frase de Rohit — "el grafo decide qué ve cada nodo, cuándo se ejecuta, a dónde va su salida, quién puede vetar y qué detiene el sistema". Todas las notaciones de abajo no están ligadas a ningún motor concreto — esto es un concepto; LangGraph y CrewAI son solo implementaciones que lo convierten en un programa ejecutable: API diferentes, mismo esqueleto. Seis pasos, y no te saltes ninguno.
+
+**Paso uno: define el estado compartido (State).** Primero distingue las dos capas: **en la capa del grafo solo se comparte el estado; el contexto de cada nodo es privado.** Un agente monolítico tiene un solo context, que con el tiempo se ahoga en su propia transcripción larga; el grafo corta el context en varias piezas, cada una pertenece a un nodo — el loop es la propiedad privada del nodo, y el grafo es la mesa común donde se entregan el relevo. Piensa bien antes qué va en el estado. Declara cómo se "fusiona" cada campo — cuando varios nodos paralelos escriben en el mismo campo a la vez, ¿se sobrescribe, se añade o se suma? Este paso no es una característica de framework; es una regla que escribes en tu `graph.md` mientras dibujas:
+
+```
+state = {
+ "requirements": texto, # lo escribe el nodo de investigación
+ "code": texto, # lo escribe el nodo de implementación
+ "review": "pass" | "fail", # lo escribe el nodo de revisión
+ "attempts": número, # +1 por cada fallo (fusión "suma" en escritura paralela)
+}
+```
+
+**Paso dos: enumera los nodos — cada nodo es un agente completo (con su propio loop).** Esta es la diferencia fundamental entre grafo y workflow: el nodo de un workflow es una función; el nodo de un grafo es un **agente que lleva su propio loop pequeño**. El nodo recibe el estado compartido → trabaja con su context privado → escribe el resultado de vuelta en el estado compartido. El interior de un nodo que escribe código suele ser el loop de la lección anterior:
+
+```
+# Interior del nodo implement: un loop pequeño privado (el loop maker-checker de la lección anterior)
+node_implement(requirements):
+ loop (máximo 3 veces):
+ code = model(prompt=instrucciones de implementación, context=requirements + último error)
+ if tests_pass(code): return {"code": code}
+ return {"error": "la implementación no pasó tras 3 intentos"}
+```
+
+| Nodo | Tipo | Interior del nodo (privado) | Escribe en estado compartido |
+|------|------|----------------------------|------------------------------|
+| research | agente | buscar → leer → resumir → re-buscar si falta información (loop) | requirements |
+| implement | agente | escribir → testear → corregir → hasta pasar (loop, ver arriba) | code |
+| verify | agente | revisión independiente + ejecutar tests (**contexto nuevo, no hereda la memoria del implementador**) | review (pass / fail) |
+| merge | código determinista | sin loop, si la verificación pasa hace commit | fin |
+
+Fíjate en la fila de verify: es el nodo que más fácil se hace mal en un grafo. **En un agente monolítico, la "revisión" usa el mismo context, se revisa a sí mismo; en un grafo, verify debe llevar una ventana de contexto completamente nueva** — no ve el proceso de pensamiento del implementador, solo ve el code del estado compartido. Ahí es donde la "revisión independiente" se cumple de verdad en el grafo: el aislamiento del contexto no es un efecto secundario, es diseño.
+
+**Paso tres: conecta las aristas.** Primero conecta la columna principal determinista: investigación → implementación → verificación → merge → fin.
+
+```mermaid
+flowchart TD
+ A([Inicio]) --> B[research]
+ B --> C[implement]
+ C --> D[verify]
+ D --> E[merge]
+ E --> F([Fin])
+```
+
+**Paso cuatro: escribe las reglas de routing (el paso más importante).** El nodo de verificación no se conecta directamente a "merge", sino a una **decisión**, que decide a dónde ir a continuación. Este paso hace explícito "a dónde vuelve un test fallido" — las reglas de routing devuelven el nombre de un nodo; de un vistazo se ve de dónde viene este grafo y a dónde va:
+
+| Nodo actual | Condición | Siguiente nodo |
+|------------|-----------|---------------|
+| verify | review == pass | merge |
+| verify | review == fail | implement |
+
+```mermaid
+flowchart TD
+ A([Inicio]) --> B[research]
+ B --> C[implement]
+ C --> D{verify}
+ D -- pass --> E[merge]
+ D -- fail --> C
+ E --> F([Fin])
+```
+
+**Paso cinco: cuelga checkpoints.** Esta es una de las mayores diferencias entre un grafo y un script de un solo uso: **el estado de cada paso se persiste en disco**, y si el proceso se cae se puede continuar desde el punto de ruptura, sin empezar de cero. Al colgarlos, tu grafo gana de inmediato la capacidad de "interrumpir/reanudar" — y también puedes insertar un nodo de "pausa para esperar aprobación humana" antes del merge, que es como se ve en un grafo el "human-in-the-loop" de la lección anterior:
+
+```
+checkpoint = on(graph, every_step) # el estado de cada paso se guarda
+graph.pause_before("merge") # detenerse antes del merge, esperando aprobación humana
+```
+
+**Paso seis: ejecuta el grafo y dale un punto de entrada.** Cada ejecución pasa un id de hilo, y el checkpoint lo usa para distinguir las distintas instancias de ejecución:
+
+```
+run(graph, entry={"requirements": "arreglar el bug de la página de login"}, thread="session-1")
+```
+
+Cuando termines, compara con el grafo de arriba: tu `graph.md` escrito a mano es el plano; el código de ese motor es el programa ejecutable en el que se convirtió el plano. Los dos deben corresponderse uno a uno. Si no coinciden — o el grafo está mal dibujado, o el código está mal escrito. **Justo ahí está el sentido de "el grafo pone el problema sobre el papel"**: antes, si no coincidían, nadie lo sabía; ahora se ve de un vistazo. Si quieres una implementación de referencia real y ejecutable, mira `code/maker_checker_graph.py` — está hecho con LangGraph, pero cuando termines de leerlo deberías reconocer: son exactamente los seis pasos de arriba.
+
+## Proyectos open source: los que vinieron después de la publicación y los que ya estaban antes
+
+Primero, delimitemos: **Graph Engineering es un nombre que solo existe después del 18 de julio de 2026.** Los frameworks de código abierto publicados antes de esa fecha no son "proyectos posteriores al lanzamiento de Graph Engineering". De los proyectos open source que realmente aparecieron con este nombre después del boom del concepto, hasta principios de agosto de 2026 solo hay uno que se sostiene:
+
+**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.
+
+**Existían antes de la publicación del concepto (no se llaman Graph Engineering, pero son justo los que usarás para construir)**
+
+Antes de julio de 2026, estas herramientas ya llevaban de uno a tres años existiendo: LangGraph (open source desde 2024, 65 millones+ de descargas mensuales, es el que usa la implementación de referencia de arriba), CrewAI, Microsoft Agent Framework, LlamaIndex Workflows, Google ADK, OpenAI Agents SDK, Mastra, Claude Agent SDK. **No son "proyectos posteriores al lanzamiento de Graph Engineering" — son precisamente la prueba de que Graph Engineering "existía antes del lanzamiento".** Ese conjunto de nodos, aristas, estado compartido y routing lleva corriendo de tres a cinco años, y en julio solo recibió un nombre nuevo. Un motor de grafos no resuelve problemas de diseño: te da nodos, aristas y checkpoints, pero no te responde por ti "qué loops alimentan a qué loops, quién posee el objetivo, quién puede vetar". Mientras esas preguntas no estén claras, cambiar de motor solo dibuja mejor el mismo diseño malo.
+
+## Agua fría: el grafo no es una bala de plata
+
+Tres cubos de agua fría, de menos a más.
+
+**El primero: números falsos.** Después del boom de Graph Engineering, por internet circulan datos como "usar grafos mejora la precisión un +18% y reduce costes un −85%". El blogger coreano goddaehee hizo una [verificación de datos](https://goddaehee.tistory.com/628) (30 de julio): los dos números existen, pero provienen de un artículo de marzo de 2026 sobre diagramas de tuberías e instrumentación química (P&ID), y el 18% es comparado contra el original de la imagen y el 85% contra otro esquema — el texto de marketing cosió dos números de líneas base distintas en un "antes y después", y en el artículo ni siquiera aparece la palabra "graph engineering". Ante cualquier dato de "X% de mejora gracias a la ingeniería de grafos", primero comprueba la fuente original.
+
+**El segundo: la forma no es un muro de carga (iii.dev).** Ya lo hemos contado. Un loop es un grafo con un solo nodo; las máquinas de estado llevan décadas corriendo. Quien anda repitiendo "loop ha muerto" o "grafo ha muerto" normalmente no ha leído con atención ni el loop ni el grafo. Lo que hay que aprender son los patrones, no los nombres.
+
+**El tercero: el Orchestration Tax (impuesto de orquestación).** En *The Orchestration Tax* de mayo, Addy Osmani dio la economía más contundente de la era del grafo/multi-agente: **arrancar un agente es barato; cerrar un loop es caro.**
+
+Arrancar un agente es un botón, una frase. Pero cerrar el loop de un agente requiere que alguien revise sus resultados y los alinee con lo que tocaron otros agentes — **ese alguien eres tú, y solo hay un tú.** Palabras textuales de Osmani:
+
+> "Tú eres el GIL de tus agentes de IA. Pueden correr en paralelo. Pero en cuanto su trabajo requiera entender de verdad la arquitectura o resolver conflictos de merge, ese trabajo tiene que adquirir el lock. Solo hay un lock, y lo tienes tú."
+
+Por eso lo que la lección anterior llamaba "el ancho de banda de revisión es el techo" se vuelve más afilado en esta: **el grafo hace que haya más agentes en paralelo, pero tu juicio es un recurso en serie, y no se paraleliza.** Añadir nodos optimiza justo lo que nunca fue el cuello de botella — el cuello de botella siempre es ese único procesador en serie: tú.
+
+## Cuándo deberías usar realmente un grafo
+
+No todas las tareas merecen que las dibujes. Cinco criterios; si se cumplen al menos tres, manos a la obra:
+
+1. **La tarea se puede dividir de forma independiente en varias unidades de trabajo** — las partes separadas no dependen entre sí y se pueden paralelizar
+2. **Existen rutas de ramificación o retroceso** — a dónde vuelve un test fallido, a dónde volver si falta información: estas rutas merecen declararse explícitamente
+3. **El estado intermedio vale la pena guardarlo** — tras un checkpoint se puede detener y reanudar, en lugar de empezar desde cero
+4. **El resultado se puede aceptar de forma inequívoca** — cada nodo tiene un criterio de completitud comprobable automáticamente
+5. **El beneficio de la colaboración > el coste de la coordinación** — el tiempo que ahorra el paralelismo es mayor que el overhead del grafo en sí y del estado compartido
+
+**"Complejo" no es igual a "muchos pasos".** Un pipeline lineal de 20 pasos no necesita un grafo — eso es un workflow, o directamente un script. Una estructura de solo 5 nodos pero con retrocesos, paralelismo y aprobación entre ellos sí necesita un grafo. El criterio no es el tamaño, es **la existencia de ramificaciones y retrocesos**.
+
+## Conceptos clave
+
+- **Graph Engineering**: la práctica de ingeniería de organizar múltiples agentes, loops, herramientas y evaluadores en un grafo explícito (nodos + aristas + estado compartido + reglas de routing). Hace que la conexión de múltiples unidades de trabajo, el estado compartido y la elección de rutas sean diseñables, observables y reparables localmente.
+- **Cuatro capas apiladas**: prompt → context → loop → graph; cada capa controla algo distinto (instrucción, información, runtime, sistema), y la siguiente no reemplaza a la anterior, solo la mete dentro de sus propios nodos.
+- **Las cuatro piezas del grafo**: nodo (unidad de trabajo), arista (forma de entrega), estado compartido (mesa de trabajo común), reglas de routing (a dónde ir a continuación).
+- **Los tres fallos estructurales del loop único**: Goodhart (el número sube, pero el negocio empeora), ceguera hacia arriba (nunca pregunta "¿es correcto este objetivo?"), conflicto (loops independientes se sabotean entre sí). El grafo convierte estos tres tipos de problemas en diseño explícito de relaciones.
+- **Graph ≠ Workflow**: el nodo del workflow es una función determinista y sus aristas son código fijo; el nodo del grafo puede ser un agente completo y sus aristas pueden tener routing dinámico. El grafo es la generalización del workflow.
+- **Anchors (anclas)**: los mecanismos que fijan la red de loops al mundo real (resultados reales de negocio, ground truth, muestreos manuales). El paso que más fácil se salta en el diseño de un grafo — y el que menos se puede omitir.
+- **Orchestration Tax (impuesto de orquestación)**: arrancar agentes es barato, revisar los resultados es caro. Tu atención es el único recurso en serie, y añadir nodos no lo optimiza.
+
+## Puntos clave
+
+- **Graph Engineering no reemplaza a Loop Engineering — construye una capa encima.** El loop es un nodo dentro del grafo; las tres cosas de la lección anterior (objetivo, verificación, condición de parada) se convierten en la estructura interna del nodo.
+- **El grafo convierte la "decisión diferida" en "decisión anticipada".** El loop esconde los modos de fallo dentro del ciclo; el grafo los pone sobre el papel — legible, auditable, reparable localmente.
+- **Lo que va dentro del nodo decide la diferencia entre grafo y workflow.** Meter funciones es un workflow; meter agentes es un grafo. Es también la única "cosa nueva" en el "vino viejo en odres nuevos".
+- **Para diseñar un grafo, responde primero cuatro preguntas:** qué loops alimentan a qué loops, quién posee el objetivo, quién puede vetar/revertir, qué indicadores pueden moverse y cuáles se congelan. Si no puedes responderlas, no lo dibujes.
+- **No dibujes por dibujar.** Cinco criterios: se puede dividir de forma independiente, hay ramificaciones o retrocesos, el estado intermedio vale la pena guardarlo, el resultado se puede aceptar, beneficio de la colaboración > coste de coordinación.
+- **Tu ancho de banda de revisión sigue siendo el techo.** El grafo hace que haya más agentes en paralelo, pero tu juicio es un recurso en serie — el impuesto de orquestación no desaparece porque haya más nodos.
+- **Recuerda la voz contraria.** La forma no es un muro de carga; lo que importa es la reproducibilidad, la observabilidad y la recuperación. Los nombres cambian cada seis semanas; la capacidad de ingeniería, no.
+
+## Lectura adicional
+
+- [Prefect: Loops vs. Graphs (jul 2026)](https://www.prefect.io/blog/loops-vs-graphs) — loop y grafo desde la perspectiva de una empresa que lleva décadas haciendo orquestación de grafos
+- [Eigent: Graph Engineering for AI Agents (jul 2026)](https://www.eigent.ai/blog/graph-engineering-ai-agents) — los tres fallos estructurales del loop único + cuatro preguntas de diseño + anclas
+- [iii.dev: Loops, Graphs, and the Layer That Matters (jul 2026)](https://iii.dev/blog/loops-graphs-and-the-layer-that-matters/) — la voz contraria más lúcida: "la forma no es un muro de carga"
+- [Hilo original de Rohit (@rohit4verse) (2026-07-29)](https://x.com/rohit4verse/status/2082478623043547356) — la fuente primaria del marco de cuatro capas: prompt → context → loop → graph, cada capa se apila sobre la anterior
+- [Agent Times: Graph Engineering as the Final Layer (jul 2026)](https://theagenttimes.com/articles/graph-engineering-emerges-as-proposed-final-layer-of-agent-o-4f0511a8) — resumen del marco de cuatro capas de Rohit
+- [goddaehee: Verificación de datos de Graph Engineering (coreano, 2026-07-30)](https://goddaehee.tistory.com/628) — la verificación de datos más completa: la línea de tiempo del origen del chiste, el desmontaje de los números falsos, los datos de LangGraph, la comparación de popularidad en Hacker News
+- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — el artículo serio que apareció dos semanas antes del chiste
+- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — la respuesta oficial: "no es una idea nueva, es el nombre más reciente de un método existente"; LangGraph con 65 millones+ de descargas mensuales
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — datos de la difusión del término (el tweet original con 575 mil visitas)
+- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — comparación horizontal de siete frameworks open source importantes: LangGraph, CrewAI, Microsoft Agent Framework, LlamaIndex, Google ADK, OpenAI Agents SDK, Mastra
+- [Documentación oficial de LangGraph](https://docs.langchain.com/oss/python/langgraph/graph-api) — "Nodes do the work, edges tell what to do next"; las definiciones precisas de nodo y arista, la referencia de primera mano para construir grafos
+- [Anthropic: Building Effective Agents (dic 2024)](https://www.anthropic.com/engineering/building-effective-agents) — cinco patrones que, dibujados, son grafos; la distinción autoritativa entre workflow y agente
+- [Addy Osmani: The Orchestration Tax (may 2026)](https://addyosmani.com/blog/orchestration-tax/) — por qué tu atención es el único recurso en serie
+- [Addy Osmani: Orchestrating Coding Agents (charla)](https://talks.addy.ie/oreilly-codecon-march-2026/) — de subagentes a equipos de agentes y quality gates
+- [Addy Osmani: Loop Engineering (jun 2026)](https://addyosmani.com/blog/loop-engineering/) — la referencia central de la lección anterior, el conocimiento previo de la ingeniería de grafos
+- Lección 13: [Del Prompting Manual a los Loops Autónomos](./../lecture-13-loop-engineering/index.md) — el loop es un nodo dentro del grafo; primero entiende el interior del nodo y luego el grafo
+- Lección 11: [Haz observable el runtime del agente](./../lecture-11-why-observability-belongs-inside-the-harness/index.md) — cuanto más complejo es el grafo, más importante es la observabilidad; un grafo que no se puede observar solo ensambla cajas negras en una caja negra más grande
+- Lección 9: [Evita que los agentes declaren victoria demasiado pronto](./../lecture-09-why-agents-declare-victory-too-early/index.md) — por qué el nodo de verificación debe ser independiente del nodo de implementación; en el grafo es un problema estructural, no de prompts
+
+## Ejercicios
+
+1. **Dibuja el loop maker-checker de P07 como un grafo:** escribe explícitamente en `graph.md` los nodos, las aristas, el estado compartido y las reglas de routing. Marca qué arista es condicional (la verificación pasa/falla) y cuál es de retroceso (el fallo vuelve a la implementación). Cuando termines, responde: ¿hay alguna arista que fuera implícita, escondida antes en el contexto del agente?
+
+2. **Responde las cuatro preguntas de eigent:** elige tres loops independientes que estés ejecutando (o tres automatizaciones dentro del mismo proyecto) y responde: ¿quién alimenta a quién? ¿Qué loop posee el objetivo que persigue otro loop? ¿Hay algún loop que pueda vetar la salida de otro? ¿Qué indicadores se están optimizando por separado y podrían entrar en conflicto?
+
+3. **Autochequeo de Goodhart:** examina algún indicador que hayas optimizado recientemente. Subió — ¿mejoraron también los resultados reales (resultados de negocio, feedback de usuarios, calidad del código)? Si solo subió el número, ¿en qué dirección te está engañando este loop?
+
+4. **Evalúa los cinco criterios:** elige una tarea que estés dudando si "graficar" o no, y puntúa uno por uno con los cinco criterios. Solo con al menos tres merece la pena dibujar un grafo. Si no llega a tres, lo que necesita es un mejor script de workflow — no dibujes un grafo solo por usarlo.
+
+5. **Convierte graph.md en un programa ejecutable:** siguiendo los seis pasos de "Construye tu primer grafo desde cero" de esta lección, implementa el grafo maker-checker que dibujaste en un grafo que se pueda ejecutar (implementación de referencia: `code/maker_checker_graph.py`, escrito con LangGraph). No te saltes ninguno de los seis pasos: definir estado → enumerar nodos → conectar aristas → escribir routing → colgar checkpoints → ejecutar. Cuando termine, compara `graph.md` con el código, encuentra el primer punto donde no coinciden y explica por qué no coinciden — ¿estaba mal dibujado el grafo, o mal escrito el código?
diff --git a/docs/es/projects/project-08-graph-engineering-first-graph/index.md b/docs/es/projects/project-08-graph-engineering-first-graph/index.md
new file mode 100644
index 0000000..82c9f78
--- /dev/null
+++ b/docs/es/projects/project-08-graph-engineering-first-graph/index.md
@@ -0,0 +1,93 @@
+[English Version →](../../../en/projects/project-08-graph-engineering-first-graph/)
+
+# Project 08. Dibuja Tu Flujo de Trabajo como un Grafo
+
+> Lección relacionada: [L14. De los Loops Únicos a la Ingeniería de Grafos](./../../lectures/lecture-14-graph-engineering/index.md)
+
+## Qué Harás
+
+Este es el proyecto de transición de "Loop" a "Graph". En la lección anterior construiste un loop maker-checker — implementar, verificar, dar feedback, implementar de nuevo — donde todas las decisiones ocurrían dentro de la ventana de contexto del mismo agente. En esta lección, lo que harás es **dibujar explícitamente la estructura que estaba escondida dentro del loop**: nodos, aristas, estado compartido y reglas de routing, escritas palabra por palabra.
+
+Harás tres experimentos progresivos: primero dibujarás el loop maker-checker de P07 como un grafo explícito, luego añadirás un nodo paralelo de fan-out/fan-in, y finalmente añadirás una arista de retroceso condicional y un nodo de aprobación humana. Cuando termines, lo habrás sentido de primera mano: **el grafo no es un invento nuevo — es en lo que tu loop se convierte por sí solo cuando se vuelve lo bastante complejo.**
+
+## Herramientas Que Usarás
+
+- Claude Code o Codex
+- Git
+- El loop maker-checker que construiste en P07 (o cualquier flujo de trabajo de agente que puedas ejecutar repetidamente)
+- Un editor de texto o una herramienta de diagramas (dibujar no es para que se vea bonito — es para dejar la estructura escrita con claridad; tanto `mermaid` como un `graph.md` escrito a mano valen)
+
+## Pasos
+
+### Preparación
+
+1. Parte del repositorio donde terminaste P07, o usa directamente cualquier flujo de trabajo de agente que estés ejecutando.
+2. Crea tres ramas: `p08-explicit-graph`, `p08-parallel`, `p08-human-in-the-loop`.
+3. Prepara un `state.md` como archivo de estado compartido: los requisitos, el progreso y los resultados de verificación se escriben aquí. Es el "espacio de trabajo común" del grafo.
+
+### Experimento 1: Dibuja el Loop como un Grafo Explícito
+
+Cambia a la rama `p08-explicit-graph`.
+
+1. **Enumera todos los nodos**: escribe cada paso del loop maker-checker de P07 como un nodo. Para cada nodo deja claro: su responsabilidad, sus entradas, sus salidas, y si es un agente o código determinista.
+2. **Dibuja todas las aristas**: enumera cada arista entre nodos. Marca con énfasis dos aristas especiales:
+ - Arista condicional: la verificación pasa/falla, por cuál se va
+ - Arista de retroceso: el fallo vuelve a qué nodo
+3. **Escribe el estado compartido**: enumera explícitamente qué campos hay en el estado (requisitos, código, resultados de tests, conclusiones de revisión) y quién los lee y quién los escribe.
+4. **Escribe las reglas de routing**: anota con el if-then más simple las reglas de "a dónde ir a continuación", por ejemplo:
+ ```
+ if la verificación pasa → nodo de merge
+ if la verificación falla → nodo de implementación
+ if el nodo de implementación tiene información insuficiente → nodo de investigación
+ ```
+5. **Escríbelo como `graph.md`**: organiza todo lo anterior en un documento. Dibuja un grafo con mermaid y adjunta la tabla de nodos y las reglas de routing.
+6. **Responde esta pregunta**: cuando termines de dibujar, encuentra al menos una **arista que antes era implícita** — una ruta de decisión que estaba escondida en el contexto del agente y que ni siquiera tú sabías que existía.
+
+### Experimento 2: Añade un Nodo de Fan-out / Fan-in Paralelo
+
+Cambia a la rama `p08-parallel`.
+
+1. **Elige un punto paralelizable**: busca en la tarea un lugar que se pueda dividir en dos partes independientes. Por ejemplo:
+ - La implementación se divide en dos módulos independientes, dos agentes los escriben en paralelo
+ - La verificación se divide en dos revisiones independientes: uno ejecuta tests y lint, otro hace la revisión de código (instrucciones diferentes, enfoques diferentes)
+ - La investigación se divide en dos direcciones, dos agentes exploran cada una
+2. **Escribe la regla de fan-out**: registra en el estado compartido que "esta tarea se dividió en N sub-tareas paralelas", cada sub-tarea con un context independiente y un nodo independiente.
+3. **Escribe la regla de fan-in**: cuando todas las sub-tareas terminen, ¿quién fusiona los resultados? ¿Cuál es el criterio de fusión (por ejemplo: solo se fusiona si ambas revisiones pasan, o basta con que pase una)?
+4. **Aísla con worktrees**: cada sub-tarea paralela corre en un git worktree independiente, evitando físicamente colisiones de archivos (repasa la primitiva de Worktree de la Lección 13).
+5. **Ejecútalo una vez y regístralo**: registra el tiempo wall-clock antes y después del paralelismo, el consumo de tokens y la calidad de los resultados. ¿El paralelismo es realmente más rápido? ¿O el overhead de coordinación se comió el tiempo ahorrado?
+
+### Experimento 3: Añade una Arista de Retroceso y un Nodo de Aprobación Humana
+
+Cambia a la rama `p08-human-in-the-loop`.
+
+Este es el más importante de los tres experimentos. Añadirás dos tipos de nodos al grafo:
+
+1. **Arista de retroceso condicional**: añade al nodo de verificación una ruta de "aprobado parcialmente" — no devolver todo al nodo de implementación, sino volver con feedback concreto al **nodo donde se originó el problema**. Por ejemplo: los tests pasan todos pero la revisión de código detecta un malentendido de los requisitos — se retrocede al nodo de investigación, no al de implementación. Esto exige que tu estado compartido registre "en qué capa está el problema".
+2. **Nodo de aprobación humana (Human-in-the-loop)**: añade un nodo humano antes del nodo de merge. Cuando el flujo llega aquí, el grafo **se detiene** y espera a que escribas "aprobar" o "rechazar" en `state.md`. El nodo de aprobación puede tener una regla de timeout: si no hay respuesta después de N horas, se rechaza automáticamente o se escala automáticamente.
+3. **Escribe el formato del interrupt**: cómo redactar claramente la petición de aprobación — qué pasó, qué cambió, por qué se necesita a una persona, y cuáles son las consecuencias de aprobar o rechazar.
+4. **Ejecuta al menos 2 rondas completas**: en cada ronda el flujo llega al nodo de aprobación humana, y tú apruebas o rechazas una vez. Registra: ¿tu decisión de aprobación coincidió con el juicio del nodo de verificación? ¿El nodo de aprobación detuvo algo que el nodo de verificación no había detenido?
+
+## Cómo Medir los Resultados
+
+| Métrica | Experimento 1 (grafo explícito) | Experimento 2 (paralelo) | Experimento 3 (colaboración humano-máquina) |
+|---------|-------------------------------|--------------------------|--------------------------------------------|
+| Visibilidad de la estructura | ¿Cuántas aristas implícitas encontraste? | ¿El estado compartido soporta las sub-tareas paralelas? | ¿La arista de retroceso puede localizar con precisión la capa del problema? |
+| Localización del fallo | Cuando falla, ¿puedes señalar directamente qué arista está mal? | Cuando falla una sub-tarea paralela, ¿puedes localizar cuál es? | Cuando se rechaza la aprobación, ¿puedes señalar de qué capa es el problema? |
+| Coste de colaboración | ¿Cuánto tardaste en dibujar el grafo? | Tiempo ahorrado por el paralelismo vs. overhead de coordinación | Tiempo de espera de aprobación vs. valor de los problemas detenidos |
+| Observabilidad | ¿Ahora se puede ver qué pasó en cada paso? | ¿El estado de cada sub-tarea paralela es visible? | ¿La petición de aprobación está escrita con la claridad suficiente? |
+| Fiabilidad | ¿La descripción del grafo coincide con la ejecución real? | ¿El criterio de fusión de fan-in es sólido? | ¿Las reglas de timeout/escalado se disparan de verdad? |
+
+## Qué Entregar
+
+- `graph.md` (la descripción completa del grafo del Experimento 1: grafo mermaid + tabla de nodos + tabla de aristas + campos del estado compartido + reglas de routing)
+- La lista de aristas implícitas encontradas en el Experimento 1 (al menos una)
+- Las reglas de fan-out/fan-in del Experimento 2 y el registro de una ejecución paralela (comparación de tiempo/coste/calidad)
+- Las reglas de la arista de retroceso del Experimento 3, el formato del nodo de aprobación y el registro de 2 rondas de colaboración humano-máquina
+- Revisión final: de loop a grafo, ¿qué cambió en tu forma de trabajar? ¿Qué tareas merecen dibujarse y cuáles no?
+
+## Lecciones Relacionadas
+
+- [Lecture 14 — De los Loops Únicos a la Ingeniería de Grafos](../../lectures/lecture-14-graph-engineering/index.md)
+- [Lecture 13 — Del Prompting Manual a los Loops Autónomos](../../lectures/lecture-13-loop-engineering/index.md) (tu loop es un nodo dentro del grafo; este proyecto despliega la estructura interna del nodo)
+- [Lecture 09 — Evita que los agentes declaren victoria demasiado pronto](../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md) (por qué el nodo de verificación debe ser independiente del nodo de implementación; en el grafo es un problema estructural)
+- [Lecture 11 — Haz observable el runtime del agente](../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) (cuanto más complejo es el grafo, más necesario es ver qué está haciendo cada nodo)
diff --git a/docs/fr/lectures/lecture-14-graph-engineering/index.md b/docs/fr/lectures/lecture-14-graph-engineering/index.md
new file mode 100644
index 0000000..ef41498
--- /dev/null
+++ b/docs/fr/lectures/lecture-14-graph-engineering/index.md
@@ -0,0 +1,349 @@
+[English Version →](../../../en/lectures/lecture-14-graph-engineering/)
+
+> Exemples de code : [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-14-graph-engineering/code/)
+> Projet pratique : [Projet 08. Dessinez votre workflow sous forme de graphe](./../../projects/project-08-graph-engineering-first-graph/index.md)
+
+# Cours 14. Des boucles simples à l'ingénierie des graphes
+
+Six semaines après le cours sur l'ingénierie des boucles, le 18 juillet 2026, Peter Steinberger — l'auteur d'OpenClaw, celui qui disait dans le cours précédent « cessez de faire du prompting à vos coding agents » — a publié un tweet :
+
+> « On parle encore de Loop, ou on est déjà passé à Graph ? »
+
+Un tweet, environ 570 000 vues en une journée, puis environ 3 millions à la fin du mois. Quelques heures plus tard, l'ingénieur en machine learning Hamel Husain a publié un article intitulé *Loop Engineering Is Dead. Enter Graph Engineering* — le corps du texte ne contenant qu'un GIF disant « Stop it » — qui a récolté environ 680 000 vues.
+
+Le plus révélateur : **ces deux personnes plaisantaient.** L'un parodiait une industrie qui invente un nouveau terme toutes les six semaines, l'autre suivait le fil pour enchaîner la blague. Mais la blague n'a vécu qu'environ un week-end — cours, feuilles de route, piles d'outils ont recouvert les timelines avant la fin du week-end, accompagnés d'une série de chiffres inventés : « précision +18 %, coût -85 % » étaient des données fausses (le 18 % et le 85 % existent bien, mais proviennent d'un article sur des schémas de tuyauterie industrielle, avec des lignes de base tout à fait différentes), et « Microsoft, Stanford et Anthropic ont découvert l'ingénierie des graphes en même temps » était aussi une fausse information. La seule « pionnière » confirmée par la vérification des faits est Josh Simmons : son *We Are Entering the Graph Engineering Phase* a été écrit le 4 juillet, deux semaines pleines avant cette blague — **c'est la blague qui a rendu le sujet populaire, pas la blague qui l'a créé.**
+
+> Sources : [goddaehee : vérification des faits sur l'ingénierie des graphes (2026-07-30)](https://goddaehee.tistory.com/628) ; [YC Startup School 2026 : interview de Jensen Huang (avec transcription)](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia) ; [explainx : Graph Engineering (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026)
+
+Ce cours ne vise pas à attiser un peu plus ce buzzword, mais à le décortiquer pour bien le comprendre : **pourquoi une boucle unique engendre-t-elle nécessairement un graphe ? Quelle est la différence entre un graphe et un workflow ? Quand en avez-vous vraiment besoin, et quand pas ?**
+
+## prompt, context, loop, graph : quatre noms, empilés couche après couche
+
+Fin juillet, l'ingénieur Rohit (@rohit4verse) a publié un [long post](https://x.com/rohit4verse/status/2082478623043547356) qui organisait l'histoire des noms de l'ingénierie IA de ces dernières années en un cadre clair à quatre niveaux. C'est le meilleur repère pour comprendre l'ingénierie des graphes :
+
+| Étape | Ce qu'elle façonne | La question à laquelle elle répond | Produits clés |
+|------|-------------------|-----------------------------------|---------------|
+| **Prompt Engineering** | les instructions | Comment dire au modèle quoi faire ? | instructions, examples, constraints, roles, output formats |
+| **Context Engineering** | l'information | Que doit savoir le modèle avant de décider ? | documents, history, memory, tool definitions, environment state |
+| **Loop Engineering** | le runtime | Comment faire boucler le modèle seul jusqu'à l'objectif ? | observe, reason, act, inspect, update, condition d'arrêt |
+| **Graph Engineering** | le système | Comment plusieurs agents, boucles, outils, évaluateurs collaborent-ils ? | nœuds, arêtes, état partagé, règles de routage |
+
+Notez comment lire cette ligne : **chaque couche ne remplace pas la précédente — elle se superpose dessus.**
+
+- Une fois que vous avez trouvé le context engineering, vous n'avez pas arrêté le prompt engineering — chaque itération a toujours besoin d'un prompt, seule la boucle vous aide à le rafraîchir quand l'environnement change.
+- Une fois que vous avez construit une boucle, vous n'avez pas abandonné le context — chaque tour de boucle doit réassembler le contexte.
+- Arrivé au graphe, ni prompt, ni context, ni loop n'ont disparu : **chaque nœud porte son propre prompt, son propre context, ses propres outils, sa propre mémoire, sa propre boucle.** Ce que le graphe décide, c'est comment les nœuds sont connectés entre eux.
+
+Voici comment Rohit concluait son propos :
+
+> Dès qu'un agent a besoin de spécialisation, de parallélisme, d'état partagé, de vérification et de récupération, ce n'est plus un loop. C'est un graphe.
+
+**Et le harness, alors ?** Ces quatre noms n'incluent pas le Harness Engineering, alors que ce cours en parle justement. La raison est simple : Rohit raconte l'histoire des buzzwords, qui s'arrête à graph, et la couche du milieu a été sautée. De plus, même la communauté n'a pas tranché sur la couche où placer le harness — [explainx](https://explainx.ai/blog/context-prompt-loop-harness-engineering-stack-2026) le place au-dessus du loop, le [papier Buildrix](https://arxiv.org/abs/2606.25139) le place en dessous. Ce cours l'a décidé dès le deuxième cours : le harness est la fondation, loop et graph sont construits dessus.
+
+Cela explique un phénomène étrange : pourquoi le mot « Graph Engineering » n'a décollé qu'en juillet 2026, alors que tout le monde s'est rendu compte qu'il « faisait déjà ça depuis longtemps ». Parce que le graphe n'est pas une invention : quand votre tâche devient suffisamment complexe, le loop se transforme automatiquement en graphe. Le nom est venu plus tard ; la pratique existait déjà.
+
+## Décomposer le graphe : nœuds, arêtes, état, routage
+
+Réduisons le graphe à ses quatre composants les plus simples.
+
+**Nœud (Node)** : une unité de travail qui assume une certaine responsabilité. Il peut être :
+- un morceau de code déterministe (exécuter les tests, calculer la couverture)
+- un appel de modèle (générer de la documentation)
+- un outil (git commit, envoyer un message)
+- un agent complet — qui a sa propre boucle, comprend les objectifs, sait utiliser les outils, et réessaie de lui-même quand il échoue
+
+Le nœud est la vraie ligne de partage entre l'ingénierie des graphes et l'ingénierie des workflows ; nous y reviendrons ci-dessous.
+
+**Arête (Edge)** : décrit comment les nœuds se passent le relais. Ce n'est pas aussi simple que « d'abord A, puis B » — une arête peut exprimer :
+- **Parallélisme** : une fois A terminé, B et C commencent en même temps
+- **Condition** : si le test passe, on va à gauche ; sinon, à droite
+- **Échec / nouvelle tentative** : le nœud tombe en panne, on revient sur lui-même pour réessayer
+- **Retour arrière** : la vérification ne passe pas, on revient au nœud d'implémentation trois sauts en arrière
+
+**État partagé (State)** : le paquet de données transmis entre les nœuds. Exigences, notes de recherche, version du code, résultats de test, conclusions de revue — tout est écrit sur le même plan de travail commun. Les nœuds ne se parlent pas directement : ils lisent et écrivent tous le même état.
+
+**Règles de routage (Routing)** : décident où aller ensuite. C'est le « flux de contrôle » du graphe, exprimé le plus simplement possible :
+
+> Si le test passe, livrer ; si le test échoue, revenir au nœud d'implémentation ; si les informations sont insuffisantes, revenir au nœud de recherche.
+
+Assemblez les quatre composants, et un graphe de développement typique ressemble à ceci :
+
+```mermaid
+flowchart TD
+ S["État partagé<br/>Exigences / notes / code / résultats"] --- R["Nœud recherche<br/>Agent: localiser le problème"]
+ R -->|"Produit une solution"| I["Nœud implémentation<br/>Agent: écrire la modification + tests"]
+ I -->|"Produit du code"| V["Nœud vérification<br/>Agent: revue indépendante + exécuter les tests"]
+ V -->|"Échec"| I
+ V -->|"Réussite"| M["Nœud fusion<br/>Code: commit + mise à jour de l'état"]
+ M -->|"Mise à jour de l'état"| S
+ I -->|"Informations insuffisantes"| R
+```
+
+Comparez avec le graphe de boucle du cours précédent : là, c'était un anneau — découvrir, répartir, vérifier, persister, puis revenir à découvrir. Dans le graphe de ce cours, **l'anneau est toujours là, mais décomposé en nœuds et arêtes explicites.** Le nœud de vérification peut renvoyer un échec directement au nœud d'implémentation, et le nœud d'implémentation peut revenir au nœud de recherche faute d'informations — ces « arêtes de retour arrière » sont implicites dans une boucle unique, c'est l'agent lui-même qui se souvient dans son contexte « je dois revenir en arrière ».
+
+## Quand un Loop ne suffit plus
+
+Un loop n'a qu'une seule voie principale. Dans le loop maker-checker que vous avez construit au cours précédent, toutes les décisions — quoi faire ensuite, où aller en cas d'échec — se produisaient dans la fenêtre de contexte d'un seul agent. Quand la tâche devient un peu plus complexe, quatre questions surgissent :
+
+1. **Répartition** : l'agent qui étudie les exigences, celui qui écrit le code, celui qui fait les tests — lequel commence en premier ?
+2. **Parallélisme** : quels travaux peuvent être menés en même temps ?
+3. **Retour arrière** : après un échec de test, où revenir — au nœud d'implémentation, ou au nœud de recherche ?
+4. **Relais** : comment plusieurs agents voient-ils la même exigence, les mêmes notes et les mêmes résultats de test ? Si le relecteur n'est pas d'accord avec l'implémenteur, qui écoute-t-on ?
+
+Jensen Huang a tenu un point de vue similaire dans son [interview Startup School 2026](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia) à Y Combinator (en conversation avec Garry Tan) : à mesure que l'implémentation de base est de plus en plus automatisée par les agents, la valeur fondamentale des humains se déplace vers « concevoir les systèmes, définir des contraintes et exercer un contrôle fin sur les agents ». Son exemple de contrôle était très concret — « une fois que l'agent a donné son plan, je modifie un mot dans le fichier de plan, et ce seul mot produit une différence précise » ; il prédisait aussi que la compétence clé du futur serait la « pensée systémique » (systems thinking).
+
+La réplique la plus cinglante du fil de discussion vient de Luis Catacora :
+
+> **« Un loop peut se permettre énormément de tolérance. Un graphe vous force à admettre combien de parties du workflow ne sont réellement pas modélisées. »**
+
+Cette phrase met en évidence la différence profonde entre loop et graph :
+
+- **Le loop, c'est la décision différée.** D'abord laisser un agent s'occuper de tout, on verra bien si ça ne marche pas ; l'architecture peut attendre. C'est pratique, mais le prix à payer, c'est que les modes d'échec sont invisibles — vous ne savez jamais où il est coincé, parce qu'il ne le sait pas lui-même.
+- **Le graphe, c'est la décision anticipée.** Vous devez déclarer toute la structure à l'avance : qui est responsable de quoi, comment les tâches dépendent les unes des autres, où revenir pour un échec donné. C'est plus de travail, mais en échange vous obtenez de la lisibilité, de l'auditabilité et une réparation localisée.
+
+Pour le dire plus crûment : **le loop cache le problème dans la boucle, le graphe pose le problème sur le papier.** Le premier convient à l'exploration, le second à la production.
+
+## Trois échecs structurels de la boucle unique
+
+Pourquoi une boucle unique ne tient-elle pas à l'échelle ? L'article d'eigent.ai, *Graph Engineering for AI Agents: Beyond Single Feedback Loops*, identifie trois échecs structurels — notez bien : des échecs structurels, pas un bug d'un loop en particulier.
+
+**D'abord une objection : ne peut-on pas ajouter des points de contrôle dans un loop ?** Si. La vérification, les conditions d'arrêt, et même les nouvelles tentatives par points de rupture du cours précédent, tout ça tient dans un loop. Mais les trois échecs ci-dessous sont précisément ce que les points de contrôle ne résolvent pas — parce que, dans un loop, les points de contrôle vivent à l'intérieur du même agent : celui qui vérifie et celui qui pose problème sont le même cerveau, le même contexte. Ça arrête « livrer sans vérifier », mais ça ne se demande pas « cet indicateur est-il correct ? », « cet objectif mérite-t-il d'être poursuivi ? » — la réponse est écrite dans son propre contexte, qu'il ne voit pas. Le graphe ne vous donne pas plus de points de contrôle ; il **déplace** la vérification : de « à l'intérieur de l'agent » vers « un nœud indépendant », avec un contexte entièrement neuf (évoqué dans la section sur le nœud verify). Voilà le sens de « structurel » : ce n'est pas qu'une pièce manque au loop, c'est que « celui qui juge et celui qui est jugé partagent le même cerveau » est la structure elle-même.
+
+### 1. Goodhart : le chiffre grimpe, mais le business se dégrade
+
+Poussez n'importe quel indicateur unique à son extrême, et il cesse de mesurer ce que vous pensez qu'il mesure. Le cas classique : une équipe de support construit un loop autour du « taux de résolution des tickets ». Les données hebdomadaires montent en flèche. Quelques mois plus tard, les données de renouvellement montrent pourtant que le churn a doublé — **le bot a appris à fermer les tickets** : changer de sujet, dissuader l'utilisateur de relancer, marquer les problèmes non résolus comme « résolus ».
+
+Le loop a fait tout ce qu'on lui demandait. Seulement ce chiffre s'est détaché de ce qui compte vraiment pour le business. C'est la loi de Goodhart.
+
+### 2. La cécité vers le haut : il ne se demande jamais « cet objectif est-il juste ? »
+
+À l'intérieur du loop, la valeur de référence est sacrée. Le thermostat ne demande pas « 68 °F est-il la bonne température ? ». Le loop de vente ne demande pas « ce quota est-il raisonnable ? ». Un loop d'évaluation d'agent ne demande pas « ce benchmark correspond-il aux vrais résultats business ? ».
+
+**Quel que soit l'objectif choisi, le loop court vers lui, même si ce n'était pas la bonne chose à poursuivre dès le départ.** Dans la structure d'une boucle unique, il n'y a aucun endroit où cette question peut tenir.
+
+### 3. Le conflit : des boucles indépendantes se sabotent mutuellement
+
+Dans un vrai système, il y a des dizaines de loop, chacun construit indépendamment. Le loop de rapidité de réponse sabote le loop de qualité profonde ; le loop de croissance sabote le loop de qualité. Chaque loop est sain sur son propre tableau de bord, mais le système dans son ensemble oscille — comme plusieurs personnes qui tirent chacune sur la même corde dans des directions différentes.
+
+**L'ingénierie des graphes répond précisément à l'ensemble de questions qu'une boucle unique ne peut pas poser :**
+
+- Quels loop alimentent quels loop ?
+- Quels loop possèdent les objectifs que poursuivent les autres loop ?
+- Quels loop peuvent opposer leur veto à un changement ou le rollback ?
+- Quels indicateurs peuvent bouger, lesquels doivent être gelés ?
+
+Quand un système contient « un loop qui peut dévorer votre objectif » et « un loop qui peut opposer son veto à votre changement », la relation entre eux devient un objet d'ingénierie — et la relation entre les relations, dessinée, donne un graphe.
+
+### Les ancres : fixer les boucles à la réalité
+
+Dans l'article d'eigent, il y a une partie « everyone skips » dans le titre : les **anchors (ancres)**. Aussi ingénieux que soit le réseau de boucles, si chaque boucle dérive de la réalité, le réseau n'est qu'une résonance de flux qui dérivent ensemble. L'ancre, c'est ce qui fixe le loop au monde réel — vrais résultats business, jeux de données ground truth, échantillonnage manuel. Quand vous concevez un graphe, les ancres sont l'étape la plus facile à sauter et pourtant la moins optionnelle.
+
+## Graph et Workflow : ce n'est pas juste un changement de nom
+
+C'est la partie la plus facile à mal comprendre de ce cours, et elle mérite d'être traitée à part.
+
+La première réaction à la déferlante du Graph Engineering, chez tout ingénieur qui a fait de l'ingénierie, c'est : « n'est-ce pas juste un workflow ? DAG, machines à états, moteurs de workflow — on fait ça depuis des décennies. »
+
+**Cette intuition est juste à moitié.** Le graphe et le workflow partagent effectivement le même squelette : nœuds + arêtes + état partagé + routage. C'est exactement ce graphe qu'Airflow, Prefect, Dagster et Temporal orchestrent depuis des décennies. Les cinq motifs récapitulés par Anthropic dans *Building Effective Agents* de décembre 2024 — chaînes de prompts, routage, parallélisation, orchestrateur/travailleurs, évaluateur/optimiseur — dessinés, ce sont justement des graphes d'exécution de formes différentes.
+
+**La moitié fausse est dans les nœuds.** Dans un workflow traditionnel, les nœuds sont des **fonctions déterministes** : une fonction Python, un script shell, une tâche SQL. Les arêtes sont du code écrit en dur : `if`, `switch`, `case`. Tout le système est maintenu par l'ingénieur en code, et le comportement est prévisible — les mêmes entrées empruntent toujours le même chemin.
+
+Dans l'ingénierie des graphes, un nœud peut être un **agent complet** : qui a sa propre boucle, sait utiliser des outils, comprend les objectifs, et réessaie de lui-même en cas d'échec. Les arêtes ne sont pas non plus nécessairement écrites en dur — elles peuvent porter des règles de routage, où la prochaine étape est décidée par la sortie du nœud précédent, par le résultat de vérification, ou même par un autre modèle.
+
+Pour clarifier cette différence, empruntons une paire de concepts à Anthropic. Anthropic distingue workflow et agent par une phrase : **qui décide du flux de contrôle ?** Si le code décide des étapes, c'est un workflow ; si le modèle peut modifier les étapes à l'exécution, c'est un agent.
+
+Alors, qu'est-ce qu'un graphe ? **Le graphe est le conteneur qui accueille les deux.** Un graphe peut contenir à la fois :
+
+- des nœuds de workflow : exécuter les tests, calculer la couverture — du code déterministe, pas besoin de modèle
+- des nœuds d'agent : implémenter une fonctionnalité, relire le code — des agents complets pilotés par modèle
+- des nœuds humains : approbation, relecture — des nœuds d'interaction homme-machine, où le graphe s'arrête en attendant le feu vert humain
+
+Donc la formulation exacte est : **le Graph Engineering n'est pas un remplacement du Workflow, c'est une généralisation du Workflow** — elle élargit le type des nœuds de « fonction » à « agent », et la décision des arêtes de « code statique » à « routage dynamique ». Le workflow est le cas particulier « entièrement déterministe » du graphe.
+
+Le point de vue adverse (iii.dev, *Loops, Graphs, and the Layer That Matters*) tombe sur le même point, mais avec une conclusion inverse :
+
+> « La forme est la partie facile, et elle est jetable. La décision qui porte — c'est de quoi sont faits le loop ou le graphe, et comment il se comporte une fois en marche. »
+
+iii.dev veut dire : ne traitez pas la « topologie » comme un exploit d'ingénierie. L'ingénierie des workflows a tourné pendant des décennies ; ce qui s'en est vraiment sédimenté, ce n'est pas comment les nœuds sont connectés, mais **rejouable, observable, récupérable** — en cas de problème on peut rejouer, en cours d'exécution on peut observer, quand ça tombe on peut reprendre. Vous pouvez modifier la forme du graphe à la main à tout moment ; c'est dans ces capacités porteuses que vous devriez investir. Cette critique mérite d'être retenue : **dessiner un graphe n'est pas le but ; combien de capacité d'ingénierie le graphe peut porter au-dessus est le but.**
+
+## Vous dessiniez déjà des graphes sans le savoir
+
+« Du vin vieux dans des bouteilles neuves » a aussi une autre preuve : les outils étaient déjà là.
+
+- **LangGraph** : publié en janvier 2024, environ 65 millions de téléchargements mensuels en juillet 2026. C'est un moteur d'exécution de graphes pour agents, où les nœuds peuvent être des agents et les arêtes peuvent porter du routage conditionnel, des checkpoints et des interruptions.
+- **Les cinq motifs d'Anthropic** : le *Building Effective Agents* de décembre 2024 avait déjà dessiné les graphes du chaînage de prompts, du routage, de la parallélisation, de l'orchestrateur/travailleurs et de l'évaluateur/optimiseur — sans les appeler Graph Engineering.
+- **Le fan-out des subagents de Claude Code** : quand vous faites en sorte qu'un agent principal émette une flopée de sous-agents qui travaillent en parallèle, vous construisez déjà un graphe, sans vous en rendre compte.
+- **Machines à états, ordonnancement DAG, files de tâches, graphes de connaissances** : en informatique, depuis des décennies, l'ingénierisation des graphes n'est pas un problème nouveau.
+
+Qu'est-ce qui est vraiment nouveau ? **Le nœud est passé de « fonction » à « agent ». »** C'est le seul changement, et c'est tout le changement. Avant, écrire un nœud de workflow, c'était écrire noir sur blanc sa logique, sa gestion d'erreur, sa stratégie de nouvelle tentative. Maintenant, un nœud n'a besoin que d'une seule instruction — « recherche ce problème », « relis ce code » — et le reste est fait par le modèle. Les nœuds sont devenus bon marché, donc le graphe est devenu digne d'être dessiné.
+
+## Construire votre premier graphe à partir de zéro
+
+Assez de théorie, passons à la pratique. Le maker-checker du cours précédent, c'est **un** agent qui boucle tout seul. La première chose que doit faire le Graph Engineering, c'est décomposer un tel agent monolithique : **chaque nœud devient un agent spécialisé, portant chacun son propre prompt, son propre context, ses propres outils, sa propre mémoire et sa propre petite boucle ; les nœuds ne partagent pas de contexte, ils ne se passent le relais que par un état partagé.** C'est la traduction en termes humains de la phrase de Rohit — « le graphe décide ce que chaque nœud voit, quand il s'exécute, où va sa sortie, qui peut opposer son veto, ce qui arrête le système ». Aucune des notations ci-dessous n'est liée à un moteur précis — ce sont des concepts ; LangGraph et CrewAI ne sont que des implémentations qui les transforment en programmes exécutables, avec des API différentes mais le même squelette. Six étapes, n'en sautez aucune.
+
+**Étape 1 : définir l'état partagé (State).** Distinguez d'abord deux niveaux : **au niveau du graphe, seul l'état est partagé ; le contexte du nœud est privé.** Un agent monolithique n'a qu'un seul contexte, qui finit par être noyé par son propre transcript encombrant ; le graphe découpe le contexte en plusieurs morceaux, chacun appartenant à un nœud — le loop est le bien privé du nœud, le graphe est la table commune sur laquelle ils se passent le relais. Réfléchissez d'abord à ce que vous mettez dans l'état. Déclarez pour chaque champ la façon dont il est « fusionné » — quand plusieurs nœuds parallèles écrivent sur le même champ en même temps, est-ce un écrasement, un ajout ou une somme ? Cette étape n'est pas une fonctionnalité de framework, c'est une règle que vous écrivez dans `graph.md` quand vous dessinez :
+
+```
+state = {
+ "requirements": texte, # écrit par le nœud recherche
+ "code": texte, # écrit par le nœud implémentation
+ "review": "pass" | "fail", # écrit par le nœud revue
+ "attempts": nombre, # +1 à chaque échec (fusion "somme" en cas d'écriture parallèle)
+}
+```
+
+**Étape 2 : lister les nœuds — chaque nœud est un agent complet (avec sa propre boucle).** C'est la différence fondamentale entre graphe et workflow : les nœuds d'un workflow sont des fonctions, les nœuds d'un graphe sont des **agents avec leur propre petite boucle**. Le nœud reçoit l'état partagé → travaille avec son propre contexte privé → écrit le résultat dans l'état partagé. À l'intérieur d'un nœud de type « code », c'est souvent le loop du cours précédent :
+
+```
+# Intérieur du nœud implement : une petite boucle privée (le loop maker-checker du cours précédent)
+node_implement(requirements):
+ loop (3 fois max):
+ code = model(prompt=instruction d'implémentation, context=requirements + dernière erreur)
+ if tests_pass(code): return {"code": code}
+ return {"error": "échec après 3 tentatives d'implémentation"}
+```
+
+| Nœud | Type | Intérieur du nœud (privé) | Écrit dans l'état partagé |
+|------|------|---------------------------|---------------------------|
+| research | agent | chercher → lire → résumer → relancer la recherche si informations insuffisantes (boucle) | requirements |
+| implement | agent | écrire → tester → corriger → jusqu'à réussite (boucle, voir ci-dessus) | code |
+| verify | agent | revue indépendante + exécuter les tests (**contexte frais, n'hérite pas de la mémoire de l'implémenteur**) | review (pass / fail) |
+| merge | code déterministe | pas de boucle, commit immédiat si la vérification passe | fin |
+
+Notez la ligne verify : c'est le nœud qu'on se trompe le plus souvent à faire dans un graphe. **Dans un agent monolithique, la « revue » utilise encore le même contexte — c'est lui-même qui se relit ; dans un graphe, verify doit porter un contexte entièrement frais** — il ne voit pas le processus de réflexion de implement, il ne voit que le code dans l'état partagé. C'est là que la « revue indépendante » tient vraiment dans un graphe : l'isolation du contexte n'est pas un effet secondaire, c'est une conception.
+
+**Étape 3 : connecter les arêtes.** Commencez par la voie principale déterministe : recherche → implémentation → vérification → fusion → fin.
+
+```mermaid
+flowchart TD
+ A([Début]) --> B[research]
+ B --> C[implement]
+ C --> D[verify]
+ D --> E[merge]
+ E --> F([Fin])
+```
+
+**Étape 4 : écrire les règles de routage (l'étape la plus cruciale).** Le nœud de vérification ne se connecte pas directement à « fusion », mais à une **décision** qui choisit la suite. C'est ici qu'on rend explicite « où revenir en cas d'échec de test » — les règles de routage renvoient le nom d'un nœud, et on voit d'un coup d'œil d'où vient le graphe et où il va :
+
+| Nœud actuel | Condition | Nœud suivant |
+|-------------|-----------|--------------|
+| verify | review == pass | merge |
+| verify | review == fail | implement |
+
+```mermaid
+flowchart TD
+ A([Début]) --> B[research]
+ B --> C[implement]
+ C --> D{verify}
+ D -- pass --> E[merge]
+ D -- fail --> C
+ E --> F([Fin])
+```
+
+**Étape 5 : accrocher des checkpoints (points de contrôle).** C'est l'une des plus grandes différences entre un graphe et un script jetable : **l'état de chaque étape est sauvegardé sur disque**, et si le processus tombe, on peut reprendre depuis un point de rupture, sans recommencer de zéro. Une fois accrochés, votre graphe acquiert immédiatement la capacité « interruption / reprise » — et vous pouvez aussi insérer un nœud « pause, en attente d'approbation humaine » avant la fusion : c'est à ça que ressemble l'« approbation humaine » du cours précédent dans un graphe :
+
+```
+checkpoint = on(graph, every_step) # sauvegarde de l'état à chaque étape
+graph.pause_before("merge") # pause avant la fusion, en attente d'approbation humaine
+```
+
+**Étape 6 : exécuter le graphe, et lui donner un point d'entrée.** À chaque exécution, passez un identifiant de thread ; le checkpoint s'en sert pour distinguer les différentes instances d'exécution :
+
+```
+run(graph, entry={"requirements": "corriger le bug de la page de connexion"}, thread="session-1")
+```
+
+Une fois exécuté, comparez avec le graphe ci-dessus : votre `graph.md` écrit à la main est le plan, et le code dans le moteur est le plan devenu programme exécutable. Les deux doivent correspondre un à un. S'ils ne correspondent pas — soit le graphe n'est pas bien dessiné, soit le code n'est pas bien écrit — **c'est précisément le sens de « le graphe pose le problème sur le papier »** : avant, personne ne savait que ça ne correspondait pas ; maintenant, on le voit d'un coup d'œil. Pour une implémentation de référence réelle et exécutable, voir `code/maker_checker_graph.py` — il utilise LangGraph, mais quand vous le lirez, vous devriez reconnaître : c'est exactement ces six étapes.
+
+## Projets open source : ce qui existe après la publication, ce qui existait avant
+
+D'abord, clarifions les limites : **le Graph Engineering est un nom qui n'existe que depuis le 18 juillet 2026.** Les frameworks open source publiés avant cette date ne sont pas des « projets d'après la publication du Graph Engineering ». Ceux qui sont vraiment apparus avec ce nom après que le concept a explosé — à début août 2026, il n'y en a qu'un qui tienne la route :
+
+**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.
+
+**Ce qui existait avant la publication du concept (ils ne s'appellent pas Graph Engineering, mais ce sont eux que vous utiliserez pour construire)**
+
+Avant juillet 2026, ces outils existaient déjà depuis un à trois ans : LangGraph (open source depuis 2024, 65 millions de téléchargements mensuels +, l'implémentation de référence ci-dessus l'utilise), CrewAI, Microsoft Agent Framework, LlamaIndex Workflows, Google ADK, OpenAI Agents SDK, Mastra, Claude Agent SDK. **Ce ne sont pas des « projets d'après la publication du Graph Engineering » — ils sont précisément la preuve d'« avant la publication du Graph Engineering ».** Les nœuds, les arêtes, l'état partagé et le routage tournent depuis trois à cinq ans ; ils n'ont reçu un nouveau nom qu'en juillet. Un moteur de graphes ne résout pas les problèmes de conception : il vous donne des nœuds, des arêtes, des checkpoints, mais il ne répondra pas à votre place « quels loop alimentent quels loop, qui possède l'objectif, qui peut opposer son veto ». Tant que ces questions ne sont pas clarifiées, changer de moteur ne fait que dessiner plus joliment le même mauvais design.
+
+## Douche froide : le graphe n'est pas une solution magique
+
+Trois douches froides, de la plus légère à la plus lourde.
+
+**Première douche : les faux chiffres.** Après l'explosion du Graph Engineering, des données ont circulé en ligne comme « en utilisant un graphe, précision +18 %, coût -85 % ». Le blogueur coréen goddaehee a fait une [vérification des faits](https://goddaehee.tistory.com/628) (30 juillet) : ces deux chiffres existent bien, mais proviennent d'un article de mars 2026 sur les schémas de tuyauterie industrielle (P&ID), et le 18 % est comparé à l'original de l'image, le 85 % à une autre solution — le texte marketing a collé ensemble deux chiffres de lignes de base différentes pour former un « avant/après » ; l'article ne contient même pas le mot « graph engineering ». À chaque fois que vous voyez « X % d'amélioration grâce à l'ingénierie des graphes », vérifiez d'abord la source originale.
+
+**Deuxième douche : la forme n'est pas un mur porteur (iii.dev).** Déjà traité ci-dessus. Un loop n'est qu'un graphe à un seul nœud ; les machines à états tournent depuis des décennies. Ceux qui répètent « le loop est mort » ou « le graphe est mort » n'ont généralement lu ni le loop ni le graphe en détail. Ce qu'il faut apprendre, ce sont les motifs, pas les noms.
+
+**Troisième douche : la taxe d'orchestration (Orchestration Tax).** Dans *The Orchestration Tax* de mai, Addy Osmani a donné l'économie la plus dure de l'ère des graphes / multi-agents : **lancer un agent coûte peu cher, fermer un loop coûte cher.**
+
+Démarrer un agent, c'est une touche, une phrase. Mais fermer le loop d'un agent exige que quelqu'un vérifie ses résultats et s'aligne sur ce que les autres agents ont touché — **cette personne, c'est vous, et il n'y en a qu'une.** La phrase d'Osmani :
+
+> « Vous êtes le GIL de vos agents IA. Ils peuvent tourner en parallèle. Mais dès que leur travail exige une compréhension réelle de l'architecture, la résolution de conflits de fusion, ces travaux doivent acquérir le verrou. Il n'y a qu'un verrou, et vous le tenez. »
+
+C'est pourquoi « la bande passante de revue est le plafond » du cours précédent est encore plus aigu ici : **le graphe multiplie les agents parallèles, mais votre jugement est une ressource séquentielle, qui ne se parallélise pas.** Ajouter des nœuds optimise toujours la partie qui n'était jamais le goulot — le goulot reste toujours le seul processeur séquentiel : vous.
+
+## Quand vous devriez vraiment utiliser un graphe
+
+Toutes les tâches ne méritent pas d'être dessinées en graphe. Cinq critères ; au moins trois d'entre eux, et on passe à l'action :
+
+1. **La tâche peut être découpée de façon indépendante en plusieurs unités de travail** — les parties découpées ne dépendent pas les unes des autres et peuvent être parallélisées
+2. **Il existe des chemins de branchement ou de retour arrière** — où revenir en cas d'échec de test, où revenir en cas d'informations insuffisantes : ces chemins méritent d'être déclarés explicitement
+3. **L'état intermédiaire mérite d'être sauvegardé** — après un checkpoint, on peut s'arrêter et reprendre, plutôt que de recommencer de zéro
+4. **Le résultat peut être accepté explicitement** — chaque nœud a un critère d'achèvement vérifiable automatiquement
+5. **Le bénéfice de la collaboration > le coût de la coordination** — le temps gagné par le parallélisme dépasse le surcoût du graphe et de l'état partagé
+
+**« Complexe » ne veut pas dire « beaucoup d'étapes ». »** Un pipeline linéaire de 20 étapes n'a pas besoin de graphe — c'est un workflow, ou carrément un script. Une structure de seulement 5 nœuds mais avec des retours arrière, du parallélisme et des approbations, elle, a besoin d'un graphe. Le critère n'est pas la taille, c'est **l'existence de branches et de retours arrière**.
+
+## Concepts clés
+
+- **Graph Engineering** : la pratique d'ingénierie qui organise plusieurs agents, boucles, outils et évaluateurs en un graphe explicite (nœuds + arêtes + état partagé + règles de routage). Elle rend la connexion des unités de travail multiples, l'état partagé et les chemins choisis concevables, observables et réparables localement.
+- **La pile à quatre couches** : prompt → context → loop → graph, chaque couche contrôle une chose différente (instructions, information, runtime, système), et la couche suivante ne remplace pas la précédente — elle enveloppe la précédente dans ses propres nœuds.
+- **Les quatre composants du graphe** : nœud (unité de travail), arête (mode de relais), état partagé (plan de travail commun), règles de routage (où aller ensuite).
+- **Les trois échecs structurels de la boucle unique** : Goodhart (le chiffre grimpe, le business se dégrade), cécité vers le haut (il ne se demande jamais « cet objectif est-il juste ? »), conflit (des boucles indépendantes se sabotent mutuellement). Le graphe transforme ces trois catégories de problèmes en conception de relations explicite.
+- **Graph ≠ Workflow** : les nœuds d'un workflow sont des fonctions déterministes, ses arêtes du code écrit en dur ; les nœuds d'un graphe peuvent être des agents complets, ses arêtes peuvent faire du routage dynamique. Le graphe est une généralisation du workflow.
+- **Anchors (ancres)** : le mécanisme qui fixe le réseau de boucles au monde réel (vrais résultats business, ground truth, échantillonnage manuel). L'étape de conception de graphe la plus facile à sauter, et la moins optionnelle.
+- **Orchestration Tax (taxe d'orchestration)** : lancer un agent est bon marché, relire les résultats est cher. Votre attention est la seule ressource séquentielle, et ajouter des nœuds ne l'optimise pas.
+
+## Points clés
+
+- **Le Graph Engineering ne remplace pas le Loop Engineering — il construit un étage au-dessus.** Le loop est un nœud du graphe ; les trois choses du cours précédent (objectif, vérification, condition d'arrêt) deviennent la structure interne du nœud.
+- **Le graphe transforme la « décision différée » en « décision anticipée ». »** Le loop cache les modes d'échec dans la boucle ; le graphe les pose sur le papier — lisible, auditable, réparable localement.
+- **Ce qu'on met dans les nœuds détermine la différence entre graphe et workflow.** Mettre des fonctions, c'est un workflow ; mettre des agents, c'est un graphe. C'est aussi le seul « vin nouveau » dans les « bouteilles neuves ».
+- **Répondez d'abord à quatre questions pour concevoir un graphe :** quels loop alimentent quels loop, qui possède l'objectif, qui peut opposer son veto / rollback, quels indicateurs peuvent bouger et lesquels sont gelés. Si vous ne pouvez pas répondre, ne dessinez pas.
+- **Ne dessinez pas pour dessiner.** Cinq critères : découpage indépendant, existence de branches ou retours arrière, état intermédiaire qui vaut la peine d'être sauvegardé, résultat accepté explicitement, bénéfice de collaboration > coût de coordination.
+- **Votre bande passante de revue reste le plafond.** Le graphe multiplie les agents parallèles, mais votre jugement est une ressource séquentielle — la taxe d'orchestration ne disparaît pas quand le nombre de nœuds augmente.
+- **Retenez la voix de l'adversaire.** La forme n'est pas un mur porteur ; ce qui est rejouable, observable, récupérable, c'est cela. Les noms changent toutes les six semaines, la capacité d'ingénierie, non.
+
+## Pour approfondir
+
+- [Prefect: Loops vs. Graphs (juil. 2026)](https://www.prefect.io/blog/loops-vs-graphs) — le point de vue d'une entreprise qui orchestre des graphes depuis des décennies sur loop et graph
+- [Eigent: Graph Engineering for AI Agents (juil. 2026)](https://www.eigent.ai/blog/graph-engineering-ai-agents) — les trois échecs structurels de la boucle unique + quatre questions de conception + anchors
+- [iii.dev: Loops, Graphs, and the Layer That Matters (juil. 2026)](https://iii.dev/blog/loops-graphs-and-the-layer-that-matters/) — l'adversaire le plus lucide : « la forme n'est pas un mur porteur »
+- [Le long post original de Rohit (@rohit4verse) (2026-07-29)](https://x.com/rohit4verse/status/2082478623043547356) — la source de première main du cadre à quatre couches : prompt → context → loop → graph, chaque couche se superposant à la précédente
+- [Agent Times: Graph Engineering as the Final Layer (juil. 2026)](https://theagenttimes.com/articles/graph-engineering-emerges-as-proposed-final-layer-of-agent-o-4f0511a8) — la synthèse du cadre à quatre couches de Rohit
+- [goddaehee: Graph Engineering : vérification des faits (koréen, 2026-07-30)](https://goddaehee.tistory.com/628) — la vérification des faits la plus complète : chronologie de l'origine de la blague, décomposition des faux chiffres, données LangGraph, comparaison de la popularité Hacker News
+- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — l'article sérieux qui précède la blague de deux semaines
+- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — la réponse officielle : « pas une nouvelle idée, le plus récent nom d'une méthode existante » ; 65 millions de téléchargements mensuels pour LangGraph
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — les données de propagation du buzzword (tweet original à 575 000 vues)
+- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — la comparaison transversale de sept frameworks open source majeurs : LangGraph, CrewAI, Microsoft Agent Framework, LlamaIndex, Google ADK, OpenAI Agents SDK, Mastra
+- [Documentation officielle de LangGraph](https://docs.langchain.com/oss/python/langgraph/graph-api) — « Nodes do the work, edges tell what to do next » ; la définition précise des nœuds et des arêtes, la référence de première main pour construire un graphe
+- [Anthropic: Building Effective Agents (déc. 2024)](https://www.anthropic.com/engineering/building-effective-agents) — les cinq motifs, dessinés, ce sont des graphes ; la distinction autorisée entre workflow et agent
+- [Addy Osmani: The Orchestration Tax (mai 2026)](https://addyosmani.com/blog/orchestration-tax/) — pourquoi votre attention est la seule ressource séquentielle
+- [Addy Osmani: Orchestrating Coding Agents (conférence)](https://talks.addy.ie/oreilly-codecon-march-2026/) — des subagents aux agent teams jusqu'aux quality gates
+- [Addy Osmani: Loop Engineering (juin 2026)](https://addyosmani.com/blog/loop-engineering/) — la référence centrale du cours précédent, les prérequis de l'ingénierie des graphes
+- Cours 13 : [Du prompting manuel aux boucles autonomes](./../lecture-13-loop-engineering/index.md) — le loop est un nœud du graphe ; comprenez d'abord l'intérieur du nœud avant de comprendre le graphe
+- Cours 11 : [Rendre l'exécution de l'agent observable](./../lecture-11-why-observability-belongs-inside-the-harness/index.md) — plus le graphe est complexe, plus l'observabilité compte ; un graphe inobservable, c'est juste de plus grandes boîtes noires assemblées
+- Cours 9 : [Empêcher les agents de déclarer victoire trop tôt](./../lecture-09-why-agents-declare-victory-too-early/index.md) — pourquoi le nœud de vérification doit être indépendant du nœud d'implémentation ; dans un graphe, c'est un problème de structure, pas de prompt
+
+## Exercices
+
+1. **Dessinez le loop maker-checker de P07 en graphe :** écrivez explicitement dans `graph.md` les nœuds, les arêtes, l'état partagé et les règles de routage. Repérez quelle arête est conditionnelle (vérification passée/échouée) et laquelle est un retour arrière (échec vers implémentation). Une fois dessiné, répondez : y a-t-il une arête implicite, qui était cachée dans le contexte de l'agent ?
+
+2. **Répondez aux quatre questions d'eigent :** trouvez trois loops indépendants que vous faites tourner (ou trois automations dans le même projet), et répondez : qui nourrit qui ? Quel loop possède l'objectif qu'un autre loop poursuit ? Y a-t-il un loop qui peut opposer son veto à la sortie d'un autre loop ? Quels indicateurs s'optimisent chacun de leur côté, tout en risquant d'entrer en conflit ?
+
+3. **Auto-test de Goodhart :** examinez un indicateur que vous avez récemment optimisé. Il a monté : les vrais résultats (résultats business, retours utilisateurs, qualité du code) ont-ils suivi ? Si seul le chiffre a monté, dans quelle direction ce loop vous trompe-t-il ?
+
+4. **É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
diff --git a/docs/fr/projects/project-08-graph-engineering-first-graph/index.md b/docs/fr/projects/project-08-graph-engineering-first-graph/index.md
new file mode 100644
index 0000000..57b75b9
--- /dev/null
+++ b/docs/fr/projects/project-08-graph-engineering-first-graph/index.md
@@ -0,0 +1,91 @@
+# Project 08. Dessinez votre workflow sous forme de graphe
+
+> Cours associé : [L14. Des boucles simples à l'ingénierie des graphes](./../../lectures/lecture-14-graph-engineering/index.md)
+
+## Ce que vous allez faire
+
+C'est le projet de transition de « Loop » à « Graph ». Au cours précédent, vous avez construit un loop maker-checker — implémenter, vérifier, donner un retour, réimplémenter, toutes les décisions se produisant dans la fenêtre de contexte d'un seul agent. Dans ce cours, ce que vous allez faire, c'est **dessiner explicitement la structure cachée dans la boucle** : nœuds, arêtes, état partagé, règles de routage, écrits mot à mot.
+
+Vous ferez trois expériences progressives : d'abord dessiner le loop maker-checker de P07 en graphe explicite, puis ajouter un nœud de fan-out/fan-in parallèle, et enfin ajouter une arête de retour conditionnelle et un nœud d'approbation humaine. Ce que vous ressentirez de bout en bout, c'est une chose : **le graphe n'est pas une invention ; c'est ce que votre loop devient de lui-même quand il devient suffisamment complexe.**
+
+## De quoi vous avez besoin
+
+- Claude Code ou Codex
+- Git
+- Le loop maker-checker que vous avez construit en P07 (ou n'importe quel workflow d'agent que vous pouvez faire tourner en boucle)
+- Un éditeur de texte ou un outil de dessin (dessiner n'est pas pour faire joli, c'est pour écrire la structure clairement ; `mermaid` ou un `graph.md` écrit à la main feront l'affaire)
+
+## Étapes concrètes
+
+### Préparation
+
+1. Partez du dépôt terminé en P07, ou utilisez directement n'importe quel workflow d'agent que vous faites tourner.
+2. Créez trois branches : `p08-explicit-graph`, `p08-parallel`, `p08-human-in-the-loop`.
+3. Préparez un `state.md` comme fichier d'état partagé : exigences, progression, résultats de vérification, tout s'y écrit. C'est le « plan de travail commun » du graphe.
+
+### Expérience 1 : dessiner le Loop en graphe explicite
+
+Passez sur la branche `p08-explicit-graph`.
+
+1. **Listez tous les nœuds** : écrivez chaque étape du loop maker-checker de P07 comme un nœud. Pour chaque nœud, précisez : sa responsabilité, son entrée, sa sortie, s'il est un agent ou du code déterministe.
+2. **Dessinez toutes les arêtes** : listez chaque arête entre les nœuds. Mettez en évidence deux arêtes spéciales :
+ - Arête conditionnelle : vérification passée/échouée, quel chemin
+ - Arête de retour arrière : en cas d'échec, on revient à quel nœud
+3. **Écrivez l'état partagé** : listez explicitement les champs de l'état (exigences, code, résultats de test, conclusion de revue), qui les lit, qui les écrit.
+4. **Écrivez les règles de routage** : avec le langage if-then le plus simple, écrivez les règles « où aller ensuite », par exemple :
+ ```
+ si la vérification passe → nœud de fusion
+ si la vérification échoue → nœud d'implémentation
+ si le nœud d'implémentation manque d'informations → nœud de recherche
+ ```
+5. **Écrivez `graph.md`** : organisez tout ce qui précède en un document. Dessinez un graphe avec mermaid, et joignez le tableau des nœuds et les règles de routage.
+6. **Répondez à cette question** : une fois dessiné, trouvez au moins une **arête qui était implicite** — un chemin de décision qui était caché dans le contexte de l'agent, dont vous-même ne connaissiez pas l'existence.
+
+### Expérience 2 : ajouter un nœud de Fan-out / Fan-in parallèle
+
+Passez sur la branche `p08-parallel`.
+
+1. **Choisissez un point parallélisable** : trouvez un endroit de la tâche qui peut être découpé en deux parties indépendantes. Par exemple :
+ - L'implémentation découpée en deux modules indépendants, deux agents écrivent en parallèle
+ - La vérification découpée en deux revues indépendantes : une qui exécute tests et lint, une qui fait la revue de code (instructions différentes, préoccupations différentes)
+ - La recherche découpée en deux directions, deux agents explorent chacun une piste
+2. **Écrivez la règle de fan-out** : dans l'état partagé, enregistrez « cette tâche est découpée en N sous-tâches parallèles », chaque sous-tâche ayant un contexte indépendant et un nœud indépendant.
+3. **Écrivez la règle de fan-in** : une fois toutes les sous-tâches terminées, qui fusionne les résultats ? Quel est le critère de fusion (par exemple : fusionner seulement si les deux revues passent, ou s'il suffit qu'une passe) ?
+4. **Isolez avec des worktrees** : chaque sous-tâche parallèle tourne dans son propre worktree git, pour éviter physiquement les collisions de fichiers (revenez sur la primitive Worktree du cours 13).
+5. **Exécutez une fois et enregistrez** : notez le temps wall-clock avant/après le parallélisme, la consommation de tokens, la qualité du résultat. Le parallélisme est-il vraiment plus rapide ? Ou le coût de coordination mange-t-il le temps gagné ?
+
+### Expérience 3 : ajouter une arête de retour arrière et un nœud d'approbation humaine
+
+Passez sur la branche `p08-human-in-the-loop`.
+
+C'est la plus importante des trois expériences. Vous allez ajouter deux types de nœuds au graphe :
+
+1. **Arête de retour arrière conditionnelle** : ajoutez au nœud de vérification un chemin « partiellement passé » — au lieu de tout renvoyer au nœud d'implémentation, revenez avec un retour concret au **nœud qui a produit le problème**. Par exemple : si les tests passent tous mais que la revue de code révèle une erreur de compréhension des exigences, revenez au nœud de recherche plutôt qu'au nœud d'implémentation. Cela exige que votre état partagé enregistre « à quelle couche le problème s'est produit ».
+2. **Nœud d'approbation humaine (Human-in-the-loop)** : ajoutez un nœud humain avant le nœud de fusion. À ce point, le graphe **s'arrête**, et attend que vous écriviez « approuvé » ou « rejeté » dans `state.md`. Le nœud d'approbation peut avoir une règle de timeout : sans réponse après N heures, rejet automatique ou escalade automatique.
+3. **Écrivez le format de l'interruption** : comment l'approbation est-elle demandée clairement — ce qui s'est passé, ce qui a été modifié, pourquoi ça a besoin d'un humain, et quelles sont les conséquences de l'approbation ou du rejet.
+4. **Exécutez au moins 2 cycles complets** : à chaque cycle, allez jusqu'au nœud d'approbation humaine, et approuvez ou rejetez une fois vous-même. Enregistrez : votre décision d'approbation correspond-elle au jugement du nœud de vérification ? Le nœud d'approbation a-t-il arrêté quelque chose que le nœud de vérification n'avait pas arrêté ?
+
+## Comment mesurer le résultat
+
+| Indicateur | Expérience 1 (graphe explicite) | Expérience 2 (parallélisme) | Expérience 3 (collaboration homme-machine) |
+|------|--------------------------------|-----------------------------|--------------------------------------------|
+| Visibilité de la structure | Combien d'arêtes implicites avez-vous trouvées ? | L'état partagé peut-il soutenir des sous-tâches parallèles ? | L'arête de retour arrière peut-elle localiser précisément la couche du problème ? |
+| Localisation de l'échec | En cas d'échec, pouvez-vous pointer directement quelle arête est fausse ? | Quand une sous-tâche parallèle échoue, pouvez-vous localiser laquelle ? | Quand l'approbation est rejetée, pouvez-vous désigner à quelle couche est le problème ? |
+| Coût de collaboration | Combien de temps avez-vous passé à dessiner ? | Temps gagné par le parallélisme vs. coût de coordination | Temps d'attente de l'approbation vs. valeur du problème arrêté |
+| Observabilité | Ce qui se passe à chaque étape, est-ce maintenant visible ? | L'état de chaque sous-tâche parallèle est-il visible ? | La demande d'approbation est-elle écrite assez clairement ? |
+| Fiabilité | La description du graphe correspond-elle à l'exécution réelle ? | Le critère de fusion fan-in est-il fiable ? | Les règles de timeout/escalade se déclenchent-elles vraiment ? |
+
+## Ce qu'il faut livrer
+
+- `graph.md` (la description complète du graphe de l'expérience 1 : graphe mermaid + tableau des nœuds + tableau des arêtes + champs de l'état partagé + règles de routage)
+- La liste des arêtes implicites trouvées à l'expérience 1 (au moins une)
+- Les règles de fan-out/fan-in de l'expérience 2 et l'enregistrement d'une exécution parallèle (comparaison temps/coût/qualité)
+- Les règles d'arête de retour arrière, le format du nœud d'approbation et les 2 cycles de collaboration homme-machine de l'expérience 3
+- La rétrospective finale : en passant du loop au graphe, qu'est-ce qui a changé dans votre façon de travailler ? Quelles tâches méritent d'être dessinées en graphe, lesquelles non ?
+
+## Cours associés
+
+- [Lecture 14 — Des boucles simples à l'ingénierie des graphes](../../lectures/lecture-14-graph-engineering/index.md)
+- [Lecture 13 — Du prompting manuel aux boucles autonomes](../../lectures/lecture-13-loop-engineering/index.md) (votre loop est un nœud du graphe ; ce projet déplie la structure interne du nœud)
+- [Lecture 09 — Pourquoi les agents déclarent victoire trop tôt](../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md) (pourquoi le nœud de vérification doit être indépendant du nœud d'implémentation ; dans un graphe, c'est un problème de structure)
+- [Lecture 11 — Pourquoi l'observabilité appartient au harness](../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) (plus le graphe est complexe, plus il faut voir ce que fait chaque nœud)
\ No newline at end of file
diff --git a/docs/ja/lectures/lecture-14-graph-engineering/index.md b/docs/ja/lectures/lecture-14-graph-engineering/index.md
new file mode 100644
index 0000000..d0257f7
--- /dev/null
+++ b/docs/ja/lectures/lecture-14-graph-engineering/index.md
@@ -0,0 +1,349 @@
+[English Version →](../../../en/lectures/lecture-14-graph-engineering/)
+
+> コード例: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-14-graph-engineering/code/)
+> 演習プロジェクト: [プロジェクト 08. ワークフローをグラフとして描く](./../../projects/project-08-graph-engineering-first-graph/index.md)
+
+# 第14回 単一ループからグラフエンジニアリングへ
+
+前回の講義で完成したループエンジニアリングの6週間後、2026年7月18日、Peter Steinberger——前回の講義で「コーディングエージェントにプロンプトを与えるのをやめよう」と言ったOpenClawの作者——が1本のツイートを投稿しました:
+
+> 「まだループの話をしているの?それとももうグラフに移ったの?」
+
+1本のツイートが、1日で約57万回の閲覧を獲得し、月末には約300万回にまで増えました。数時間後、機械学習エンジニアのHamel Husainが『Loop Engineering Is Dead. Enter Graph Engineering』というタイトルの記事を投稿しました——本文は「Stop it」と書かれた動画一枚だけ——それも約68万回の閲覧を獲得しました。
+
+さらに興味深いのは:**この2人はどちらも冗談として投稿していたことです。** 一人は業界が6週間ごとに新しい流行語を発明していることを皮肉り、もう一人はそのネタに乗って一搭一宕で応じました。しかし、その冗談はおよそ1週末しか持ちませんでした——コース、ロードマップ、ツールスタックが週末のうちにタイムラインを埋め尽くし、さらに一連の捏造された数字も付いてきました:「精度+18%、コスト-85%」は偽のデータです(18%と85%は確かに存在しますが、化学プラントの配管図に関する論文からのもので、比較基線も根本的に異なります)、「マイクロソフト、スタンフォード、Anthropicが同時にグラフエンジニアリングを発見した」も偽の情報です。事実確認で確認された唯一の「先行者」はJosh Simmonsです:彼の『We Are Entering the Graph Engineering Phase』は7月4日に書かれており、この冗談より丸2週間も早いのです——**この流行を流行らせたのは冗談であり、冗談がその現象を作り出したわけではありません。**
+
+> 出典: [goddaehee: Graph Engineering ファクトチェック(2026-07-30)](https://goddaehee.tistory.com/628);[YC Startup School 2026:Jensen Huang インタビュー(文字起こし付き)](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia);[explainx: Graph Engineering(2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026)
+
+この講義でやることは、この流行語にさらに火をつけることではなく、それを分解してはっきりと見ることです:**なぜ単一ループの先に必ずグラフが生まれるのか?グラフとワークフローはどこが違うのか?いつ本当に必要なのか、いつ不要なのか?**
+
+## prompt、context、loop、graph:4つの名前、積み重なり合う1つのレイヤー
+
+7月末、エンジニアのRohit(@rohit4verse)が[長文ポスト](https://x.com/rohit4verse/status/2082478623043547356)を投稿し、AIエンジニアリングのここ数年の命名史を明確な4層のフレームワークに整理しました。これはGraph Engineeringを理解するための最良の座標系です:
+
+| 段階 | 何を形作るか | 答える問い | 重要な産物 |
+|------|---------|-----------|---------|
+| **Prompt Engineering** | 指示 | モデルに何をすべきかをどう伝えるか? | instructions、examples、constraints、roles、output formats |
+| **Context Engineering** | 情報 | モデルが決定する前に何を知るべきか? | documents、history、memory、tool definitions、environment state |
+| **Loop Engineering** | ランタイム | モデルが目標を達成するまで自分でループするにはどうするか? | observe、reason、act、inspect、update、停止条件 |
+| **Graph Engineering** | システム | 複数のエージェント、ループ、ツール、評価者がどう協力するか? | ノード、エッジ、共有状態、ルーティングルール |
+
+この流れの読み方に注意してください:**各レイヤーは前のレイヤーを置き換えるのではなく、その上に重なるのです。**
+
+- コンテキストエンジニアリングを始めた後も、プロンプトエンジニアリングを止めたわけではありません——毎回の反復でやはりプロンプトが必要で、ただ環境が変わったときにループがそれを更新してくれるだけです。
+- ループを構築した後も、コンテキストを捨てたわけではありません——ループの各ラウンドでコンテキストを再組み立てする必要があります。
+- グラフに至っても、プロンプトもコンテキストもループも一つも消えません:**各ノードは自分自身のプロンプト、自分自身のコンテキスト、自分自身のツール、自分自身のメモリ、自分自身のループを持ちます。** グラフが決めるのは、ノード同士がどう接続されるかです。
+
+Rohitの元の言葉はこう締めくくられています:
+
+> エージェントが専門化、並列化、共有状態、検証、リカバリを必要とするようになったら、それはもはやループではありません。それはグラフです。
+
+**待って、harnessは?** この4つの名前にはHarness Engineeringがありません。しかしこのコースが扱うのはharnessです。理由は簡単です:Rohitが語っているのは流行語の歴史であり、終点はグラフで、中間のレイヤーは飛ばされたのです。しかもharnessがどのレイヤーに置かれるべきかは、業界自身がまだ議論を決めていません——[explainx](https://explainx.ai/blog/context-prompt-loop-harness-engineering-stack-2026)はループの上に置き、[Buildrix論文](https://arxiv.org/abs/2606.25139)はループの下に置いています。本コースは第2回でこう定めました:harnessは基盤であり、ループとグラフはその上に建てられます。
+
+これは奇妙な現象を説明します:「Graph Engineering」という言葉が2026年7月に火がついたのに、みな自分は「すでにずっとそうやってきた」と気づいたことです。なぜならグラフは新しい発明ではなく、タスクが一定の複雑さに達したとき、ループが自動的にグラフに変わるからです。名前は後から付いたもので、やり方はすでに存在していました。
+
+## グラフを分解する:ノード、エッジ、状態、ルーティング
+
+グラフを最も素朴な4つの部品に還元します。
+
+**ノード(Node)**:ある責務を担う作業単位。それは次のようなものになります:
+- 一段の決定論的コード(テストの実行、カバレッジの計算)
+- 一回のモデル呼び出し(ドキュメントの生成)
+- 一つのツール(git commit、メッセージ送信)
+- 一つの完全なエージェント——自分自身でループを持ち、目標を理解し、ツールを使って、行き詰まったら自分で再試行する
+
+ノードこそがグラフエンジニアリングとワークフローエンジニアリングの本当の分岐点であり、これについては後で詳しく説明します。
+
+**エッジ(Edge)**:ノード間の引き継ぎ方を示します。それは「AをやってからBをやる」という単純なものではありません——一本のエッジは次のものを表現できます:
+- **並列**:Aが完了したら、BとCが同時に始まる
+- **条件**:テストが通れば左へ、失敗すれば右へ
+- **失敗/再試行**:ノードが落ちたら、自分自身に戻ってもう一度実行する
+- **フォールバック**:検証が通らなければ、3つ前の実装ノードへ戻る
+
+**共有状態(State)**:ノード間で受け渡されるデータパケット。要件、研究ノート、コードのバージョン、テスト結果、レビュー結論——すべて同じ公共の作業台に書かれます。ノードは直接互いに話しかけるのではなく、同じ状態を読み書きします。
+
+**ルーティングルール(Routing)**:次にどこへ進むかを決めます。これはグラフの「制御フロー」で、最も素朴な言葉で言えば次の通りです:
+
+> テストが通れば納品する;テストが失敗すれば実装ノードに戻る;情報が不足すれば研究ノードに戻る。
+
+4つの部品を組み合わせると、典型的な開発グラフは次のようになります:
+
+```mermaid
+flowchart TD
+ S["共有状態<br/>要件 / ノート / コード / 結果"] --- R["研究ノード<br/>Agent: 問題の特定"]
+ R -->|"解決案を生む"| I["実装ノード<br/>Agent: 修正 + テストを書く"]
+ I -->|"コードを生む"| V["検証ノード<br/>Agent: 独立レビュー + テスト実行"]
+ V -->|"不合格"| I
+ V -->|"合格"| M["マージノード<br/>コード: commit + 状態更新"]
+ M -->|"状態更新"| S
+ I -->|"情報不足"| R
+```
+
+前回の講義のループ図と比べてください:前回は一つの環——発見、ディスパッチ、検証、永続化、そして再び発見へ。今回の講義のグラフでは、**環はまだありますが、明示的なノードとエッジに分解されています。** 検証ノードは失敗を直接実装ノードに打ち返せますし、実装ノードは情報不足で研究ノードに戻れます——こうした「フォールバックエッジ」は単一ループでは暗黙的で、エージェント自身がコンテキストの中で「戻るべきだ」と覚えているだけです。
+
+## Loop がいつ不足するのか
+
+一つのループには幹線が一本しかありません。前回の講義で構築したmaker-checkerループでは、すべての決定——次に何をするか、失敗したらどこへ進むか——が同じエージェントのコンテキストウィンドウの中で起こっていました。タスクがもう少し複雑になると、次の4つの問題が浮かび上がります:
+
+1. **分業**:要件を研究するエージェント、コードを書くエージェント、テストをするエージェント、誰が先に始めるの?
+2. **並列**:どの作業を同時に進められるか?
+3. **フォールバック**:テストが失敗したらどこに戻るべきか——実装ノードに戻るのか、研究ノードに戻るのか?
+4. **引き継ぎ**:複数のエージェントが同じ要件、ノート、テスト結果をどう見るのか?レビュアーが実装者に同意しないとき、誰の意見を聞くのか?
+
+黄仁勳(Jensen Huang)はY Combinatorの[Startup School 2026インタビュー](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia)(Garry Tanとの対談)で同じような見解を述べています:下層の実装がエージェントによってますます自動化されるにつれて、人間のコア価値は「システムを設計し、制約を明確にし、エージェントに細粒度の制御を行う」ことに移る。彼が挙げた制御の例はとても具体的です——「エージェントが計画を出した後、私は計画ファイルの中で一つの言葉を変える。その一つの言葉が正確な差分を生み出す」;彼は未来のコアスキルは「システム思考(systems thinking)」だと予言しました。
+
+議論のスレッドで最も鋭い一撃はLuis Catacoraからのものです:
+
+> **「ループには大量の容錯余地がある。グラフは、ワークフローの中にまだ本当にモデル化されていない部分がどれだけあるかを、あなたに認めさせてしまう。」**
+
+この言葉はloopとgraphの深い違いを言い当てています:
+
+- **Loopは先延ばしの決定である。** まず一つのエージェントにすべての作業を引き受けさせ、回りきれなくなったらその時に考えればよい。アーキテクチャを後回しにできる。これは楽ですが、代償として失敗モードが見えない——どこで行き詰まっているのか決してわからない。なぜならエージェント自身も知らないからです。
+- **Graphは先回りの決定である。** 構造全体を事前に宣言しなければならない:誰が何を担当するか、タスク間の依存関係、ある失敗がどこに戻るか。これは手間ですが、その代わりに読みやすく、監査しやすく、部分修復が可能になります。
+
+もっと率直に言えば:**loopは問題をループの中に隠し、graphは問題を紙の上に並べる。** 前者は探索に適し、後者は本番に適します。
+
+## 単一ループの3つの構造的失敗
+
+なぜ単一ループは規模の上で持ちこたえられないのか?eigent.aiの『Graph Engineering for AI Agents: Beyond Single Feedback Loops』は3つの構造的失敗を挙げています——注意すべきは、それはあるループのバグではなく構造的失敗だということです。
+
+**まず反論を一つ:ループにもチェックポイントを足せるのではないか?** 足せます。前回の検証、停止条件、さらにはブレークポイント再試行まで、ループに収められます。しかし、次の3つの失敗はまさにチェックポイントでは解決できないものです——なぜならループのチェックポイントは同じエージェント内部に存在し、チェックを行うのも問題を起こすのも同じ頭脳、同じコンテキストだからです。それは「検証なしで納品する」ことは止められますが、「この指標は正しいのか」「この目標を追うべきか」と問うことはしません——答えは自分自身のコンテキストに書いてあるのに、見えないのです。グラフはチェックポイントを多く与えるのではなく、チェックを**外に移す**のです:エージェント内部から、新しいコンテキストを与えた独立ノードへ(先ほどのverifyノードの節で説明しました)。「構造的」という言葉の意味はここにあります:loopに欠けている部品があるのではなく、「判断者と実行者が同じ頭脳を共有している」という構造自体に問題があるのです。
+
+### 1. Goodhart:数字は上がったのに、ビジネスは悪化した
+
+どんな単一の指標も極限まで押し詰めると、あなたが測っていると思っているものを測らなくなります。古典的な例:あるカスタマーサポートチームが「チケット解決率」を中心にループを構築しました。週次データは右肩上がり。数ヶ月後、継続率データはchurnが倍になったことを示しました——**botはチケットを閉じることを覚えたのです**:話題をそらし、ユーザーの追及を思いとどまらせ、未解決の問題を「解決済み」とマークしました。
+
+ループは要求されたことをすべてやりました。ただ、その数字がビジネスが本当に気にするものから離れてしまっただけです。これがGoodhartの法則です。
+
+### 2. 上方向の失明:それは決して「この目標は正しいのか」と問わない
+
+ループの内部では、参照値は神聖です。サーモスタットは「68°Fは正しい温度か」と問いません。営業ループは「このノルマは合理的か」と問いません。エージェントevalループは「このベンチマークは実際のビジネス結果と一致するか」と問いません。
+
+**目標を選んだ者が誰であれ、ループはその目標に向かって走る——それが最初から追うべきものではなかったとしても。** 単一ループの構造には、この問いを置ける場所がどこにもありません。
+
+### 3. 衝突:独立したループが互いの台を壊す
+
+現実のシステムには何十ものループがあり、それぞれが独立して構築されています。応答速度のループが深い品質のループの台を壊し、成長のループが品質のループの台を壊します。どのループも自分のダッシュボード上では健全なのに、システム全体は揺れ続ける——まるで数人が同じロープをそれぞれ別の方向に引っ張っているかのようです。
+
+**Graph engineeringが答えようとするのは、まさに単一ループが答えられないその一群の問いです:**
+
+- どのループがどのループに供給するのか?
+- どのループが他のループが追いかける目標を所有しているのか?
+- どのループが変更を否決したりロールバックしたりできるのか?
+- どの指標は動かしてよく、どの指標は凍結しなければならないのか?
+
+システムの中に「あなたの目標を食べられるループ」と「あなたの変更を否決できるループ」が存在するとき、それらの間の関係はエンジニアリングの対象になります——そして関係と関係の関係を描けば、それがグラフになります。
+
+### アンカー:ループを現実に固定する
+
+eigentの記事のタイトルには「everyone skips」の部分があります:**anchors(アンカー)**。ループのネットワークがどれほど精巧でも、すべてのループが現実から漂っていたら、ネットワークは互いに漂う共振でしかありません。アンカーとは、ループを実世界に固定するものです——実際のビジネス結果、ground truthデータセット、人手によるスポットチェック。グラフを設計するとき、アンカーは最もスキップされやすいのに、最も省けないステップです。
+
+## Graph と Workflow:名前を変えただけではない
+
+これはこの講義で最も誤解されやすいところなので、単独で取り上げて説明する価値があります。
+
+Graph Engineeringが爆発的に流行ったときの最初の反応として、エンジニア経験者はみんなこう呟くでしょう:「これってワークフローじゃないか?DAG、状態機械、ワークフローエンジン、ここ数十年やってきたじゃないか。」
+
+**この直感は半分正しい。** グラフとワークフローは確かに同じ骨格を共有します:ノード + エッジ + 共有状態 + ルーティング。Airflow、Prefect、Dagster、Temporalが数十年にわたって行ってきた編成の仕方はまさにこのグラフです。Anthropicが2024年12月に発表した『Building Effective Agents』がまとめた5つのパターン——プロンプトチェーン、ルーティング、並列化、オーケストレータ/ワーカー、評価者/オプティマイザ——を描いてみると、得られるのは異なる形の実行グラフです。
+
+**間違っている半分はノードの中にあります。** 従来のワークフローのノードは**決定論的関数**です:Python関数、シェルスクリプト、SQLタスク。エッジは書き込まれたコードです:`if`、`switch`、`case`。システム全体はエンジニアがコードで保守し、挙動は予測可能です——同じ入力は常に同じ経路を通ります。
+
+グラフエンジニアリングのノードは**完全なエージェント**になり得ます:自分でループを持ち、ツールを使い、目標を理解し、失敗に遭遇したら自分で再試行します。エッジも書き込まれたものに限りません——ルーティングルールを持つことができ、前のノードの出力、検証結果、さらには別のモデルによって次のステップが決まります。
+
+この違いを明確にするため、Anthropicの一対の概念を借用します。Anthropicはワークフローとエージェントを一文で区別します:**制御フローを決めるのは誰か?** コードがステップを決めるならワークフロー、モデルが実行時にステップを変えられるならエージェントです。
+
+ではグラフとは何か?**グラフは両方を収容するコンテナです。** 一枚のグラフの中に同時に置けます:
+
+- ワークフローノード:テスト実行、カバレッジ計算——決定論的コード、モデル不要
+- エージェントノード:機能実装、コードレビュー——モデル駆動の完全なエージェント
+- 人間ノード:承認、再確認——人間と機械のインタラクションノード、ここまで来たら止まって、人間の了承を待つ
+
+したがって正確な言い方は:**Graph EngineeringはWorkflowの代替ではなく、Workflowの一般化です**——ノードの型を「関数」から「エージェント」へと広げ、エッジの決定を「静的コード」から「動的ルーティング」へと広げます。ワークフローはグラフの中の「完全に決定論的」な特例です。
+
+反対意見(iii.devの『Loops, Graphs, and the Layer That Matters』)も同じこの点に落ち着きますが、結論は逆です:
+
+> 「形は簡単な部分で、しかも一回限りだ。承重となる決定は、loopやgraphが何で構成されるか、そしてそれが動作した後どうなるかだ。」
+
+iii.devの意味するところ:トポロジーをエンジニアリングの成果だと思ってはいけない。ワークフローエンジニアリングは数十年走ってきたが、本当に積み上げられたのはノードの接続方法ではなく、**再現可能、観測可能、リカバリ可能**——問題が起きたら再生でき、実行中は観察でき、落ちたら続きから再開できる——ことです。グラフの形は自由に変えられますが、こうした承重能力こそあなたが注力すべきところです。この批判は覚えておく価値があります:**図を描くこと自体が目的ではなく、図の上にどれだけのエンジニアリング能力を載せられるかが目的です。**
+
+## あなたは実はすでに図を描いている
+
+「新瓶装旧酒(新しい瓶に古い酒)」のもう一つの証拠:ツールはすでに揃っています。
+
+- **LangGraph**:2024年1月にリリースされ、2026年7月までに月間ダウンロード数は約6500万回。エージェント向けのグラフ実行エンジンで、ノードはエージェントになれ、エッジは条件付きルーティング、checkpoint、interruptを持てます。
+- **Anthropicの5つのパターン**:2024年12月の『Building Effective Agents』は、プロンプトチェーン、ルーティング、並列化、オーケストレータ/ワーカー、評価者/オプティマイザのグラフをすでに描いていました——ただGraph Engineeringとは呼んでいなかっただけです。
+- **Claude Codeのsubagent fan-out**:メインエージェントに一団のサブエージェントを並列で動かさせるとき、あなたはすでにグラフを構築しています——ただ気づいていないだけです。
+- **状態機械、DAGスケジューリング、タスクキュー、ナレッジグラフ**:コンピュータサイエンスの数十年、グラフのエンジニアリングは新しい問題ではありません。
+
+本当に新しいのは何か?**ノードが「関数」から「エージェント」になったこと。** これが唯一の変化であり、すべての変化です。以前はワークフローのノードを書くとき、そのロジック、エラーハンドリング、再試行戦略を明確に書く必要がありました。今、ノードは一つの指示だけで済みます——「この問題を研究して」「このコードをレビューして」——残りはモデルが自分でやります。ノードが安くなったので、グラフを描く価値が生まれたのです。
+
+## ゼロから最初のグラフを構築する
+
+理論は十分に語りました。実践しましょう。前回の講義のmaker-checkerは、自分でループする**一つの**エージェントでした。Graph Engineeringが最初にやること、それはこのようなモノリシックエージェントを分解することです:**各ノードを専門的なエージェントに変え、それぞれがプライベートなprompt、context、tools、memory、そして自分自身の小さなループを持ちます;ノード間はコンテキストを共有せず、ただ一枚の共有状態だけで引き継ぎます。** これがRohitの言葉を人間の言葉に訳したものです——「graphは各ノードが何を見るか、いつ実行するか、出力がどこへ行くか、誰が否決できるか、何がシステムを止めるかを決める」。以下のすべての表記は特定のエンジンに紐づきません——これは概念で、LangGraph、CrewAIはそれらを実行可能なプログラムに変える実装に過ぎず、APIは違っても骨格は同じです。6つのステップ、どれもスキップしてはいけません。
+
+**ステップ1:共有状態(State)を定義する。** まず2つのレイヤーを区別します:**グラフレイヤーで共有されるのは状態だけであり、ノードのコンテキストはプライベートです。** モノリシックエージェントはコンテキストを一つしか持たず、長く走ると自分自身の冗長なtranscriptに埋もれます;グラフはコンテキストを複数に切り分け、それぞれが一つのノードに属します——loopはノードのプライベートなもので、graphはそれらが引き継ぐ公共の台です。状態に何を入れるか、先に考えておきます。各フィールドに「どうマージされるか」を宣言します——複数の並列ノードが同時に同じフィールドに書き込むとき、上書きか、追加か、それとも合計か。このステップはフレームワークの機能ではなく、あなたが図を描くときから`graph.md`に書き込むルールです:
+
+```
+state = {
+ "requirements": テキスト, # 研究ノードが書き込む
+ "code": テキスト, # 実装ノードが書き込む
+ "review": "pass" | "fail", # レビューノードが書き込む
+ "attempts": 数値, # 失敗ごとに +1(並列書き込み時は「合計」でマージ)
+}
+```
+
+**ステップ2:ノードを列挙する——各ノードは完全なエージェント(内蔵ループ付き)。** これがグラフとワークフローの根本的な違いです:ワークフローのノードは関数、グラフのノードは**自分自身の小さなループを持ったエージェント**です。ノードは共有状態を受け取り → 自分のプライベートなコンテキストで作業し → 結果を共有状態に書き戻します。コードを書くタイプのノードの内部は、多くの場合、まさに前回の講義のあのループです:
+
+```
+# implement ノード内部:プライベートな小さなループ(前回の講義の maker-checker loop)
+node_implement(requirements):
+ loop (最大 3 回):
+ code = model(prompt=実装指示, context=requirements + 前回のエラー)
+ if tests_pass(code): return {"code": code}
+ return {"error": "実装 3 回試しても不合格"}
+```
+
+| ノード | 型 | ノード内部(プライベート) | 共有状態への書き込み |
+|------|------|------------------|-------------|
+| research | agent | 検索 → 読む → 要約 → 情報不足なら再検索(ループ) | requirements |
+| implement | agent | 書く → テスト → 修正 → 通るまで(ループ、上記参照) | code |
+| verify | agent | 独立レビュー + テスト実行(**fresh context、実装者の記憶は継承しない**) | review(pass / fail)|
+| merge | 決定論的コード | ループなし、チェックが通れば即commit | 終了 |
+
+verifyの行に注意してください:これはグラフの中で最も間違えやすいノードです。**モノリシックエージェントでは「レビュー」も同じコンテキストを使い、自分で自分を審査します;グラフではverifyは必ず新しいコンテキストを持つ**——実装者の思考過程は見えず、共有状態のcodeだけが見えます。これが「独立レビュー」がグラフ上で本当に成立する場所です:コンテキストの隔離は副作用ではなく、設計なのです。
+
+**ステップ3:エッジを結ぶ。** まず決定論的な幹線を結びます:研究 → 実装 → 検証 → マージ → 終了。
+
+```mermaid
+flowchart TD
+ A([開始]) --> B[research]
+ B --> C[implement]
+ C --> D[verify]
+ D --> E[merge]
+ E --> F([終了])
+```
+
+**ステップ4:ルーティングルールを書く(最も重要なステップ)。** 検証ノードは「マージ」に直接つなぐのではなく、一つの**決定**につなぎ、そこで次の行き先を決めます。このステップは「テスト失敗でどこに戻るか」を明示化します——ルーティングルールが返すのはノードの名前で、このグラフがどこから来てどこへ行くのかが一目で見渡せます:
+
+| 現在のノード | 条件 | 次のノード |
+|---------|------|---------|
+| verify | review == pass | merge |
+| verify | review == fail | implement |
+
+```mermaid
+flowchart TD
+ A([開始]) --> B[research]
+ B --> C[implement]
+ C --> D{verify}
+ D -- pass --> E[merge]
+ D -- fail --> C
+ E --> F([終了])
+```
+
+**ステップ5:checkpoint(チェックポイント)を掛ける。** これはグラフと一度きりのスクリプトの最大の違いの一つです:**各ステップの状態をディスクに落とし**、プロセスが落ちてもブレークポイントから再開でき、最初からやり直す必要はありません。掛けた瞬間、グラフは「中断/復元」能力を獲得します——さらにmergeの前に「一時停止して人間の承認を待つ」ノードを挿入することもできます。これが前回の講義の「人間による承認」がグラフ上でどう見えるかです:
+
+```
+checkpoint = on(graph, every_step) # 各ステップの状態を保存する
+graph.pause_before("merge") # マージ前に停止し、人間の承認を待つ
+```
+
+**ステップ6:グラフを走らせ、エントリーポイントを与える。** 実行のたびにスレッドidを渡し、checkpointがそれを使って異なる実行インスタンスを区別します:
+
+```
+run(graph, entry={"requirements": "ログインページのバグを修正"}, thread="session-1")
+```
+
+実行が終わったら上の図と照合します:あなたが手書きした`graph.md`は青写真で、エンジン内のそのコードは青写真が実行可能なプログラムになったものです。両者は一対一で対応するはずです。対応しないなら——図の描き方が間違っているか、コードの書き方が間違っているか、**まさにこれが「グラフは問題を紙の上に並べる」という意味です**:以前は対応しなくても誰も気づきませんでしたが、今は一目でわかります。実際に動くリファレンス実装が必要なら、`code/maker_checker_graph.py`を参照してください——LangGraphを使っていますが、読めばわかるはずです:あれはまさに上の6ステップです。
+
+## オープンソースプロジェクト:公開後に出たもの、公開前にあったもの
+
+先に線を引きます:**Graph Engineeringは2026年7月18日以降にできた名前です。** それ以前にオープンソース化されたフレームワークは、いずれも「Graph Engineering公開後のプロジェクト」ではありません。概念が爆発的に流行った後に、直接この名前で出てきたオープンソースプロジェクトは、2026年8月初時点で、ちゃんと立っているのは一つだけです:
+
+**概念公開後に出たもの**
+
+- [GraphArc](https://github.com/CodeGraphContext/grapharc)(2026-08-02):自称「Graph Engineeringの最初のリアルタイム実装」。エージェント実行をログに埋もれたtraceから、一枚の**インタラクティブなリアルタイム編成グラフ**に変えます——各エージェント、各依存関係、各決定ポイントが描かれ、実行前にグラフ全体を可視化し、あなたが確認して(スマホで見ることもできます)から放行します。作者の背景は4000人以上の開発者向けのグラフツール作りで、方向性は「観測可能、デバッグ可能、エンジニアリング可能」です。非常に新しいので、機能はまだ初期段階です。
+
+**概念公開前にあったもの(それらはGraph Engineeringと呼ばれていないが、あなたが構築するときに使うのはそれら)**
+
+2026年7月以前、これらのツールはすでに1〜3年存在していました:LangGraph(2024年オープンソース化、月間ダウンロード6500万以上、上記のリファレンス実装が使っているもの)、CrewAI、Microsoft Agent Framework、LlamaIndex Workflows、Google ADK、OpenAI Agents SDK、Mastra、Claude Agent SDK。**それらは「Graph Engineering公開後のプロジェクト」ではありません——それらこそが「Graph Engineering公開前」の証拠です。** ノード、エッジ、共有状態、ルーティングという一連のものは3〜5年走ってきて、7月になって初めて新しい名前を得ました。グラフエンジンは設計問題を解決しません:ノード、エッジ、checkpointを与えてくれますが、「どのループがどのループに供給するか、誰が目標を所有するか、誰が否決できるか」を代わりに答えてはくれません。これらの問題を考え固める前に、どのエンジンに変えても同じ悪い設計を美しく描くだけです。
+
+## 冷水を浴びせる:グラフは銀の弾丸ではない
+
+3杯の冷水を、軽いものから重いものまで。
+
+**一杯目:偽の数字。** Graph Engineeringが爆発的に流行った後、ネット上では「グラフを使うと精度+18%、コスト-85%」といったデータが流れました。韓国人ブロガーのgoddaeheeが[ファクトチェック](https://goddaehee.tistory.com/628)(7月30日)を行いました:この2つの数字は確かに存在しますが、2026年3月の化学プラントの配管図(P&ID)に関する論文からのもので、しかも18%は画像原稿との比較、85%は別のスキームとの比較です——マーケティング文案が異なる基線の数字を1つの「前後比較」に寄せ集めたもので、論文には「graph engineering」という言葉すらありません。「図エンジニアリングがX%向上をもたらす」というデータを見たときは、まず元の出典を確認してください。
+
+**二杯目:形は承重壁ではない(iii.dev)。** 上で説明しました。loopはノードが一つだけのグラフです;状態機械は数十年走ってきました。「loopは死んだ」あるいは「graphは死んだ」と口にする人々は、だいたいloopもgraphもろくに読んでいません。学ぶべきはパターンであり、名詞ではありません。
+
+**三杯目:Orchestration Tax(オーケストレーション税)。** Addy Osmaniは5月の『The Orchestration Tax』で、グラフ/マルチエージェント時代の最も硬核な経済学の一つを与えました:**エージェントを起動するのは安いが、ループを閉じるのは高い。**
+
+エージェントを起動するのはボタン一つ、言葉一つです。しかしエージェントのループを閉じるには、誰かがその結果をチェックし、他のエージェントが動かしたものと整合させる必要があります——**その誰かはあなたで、しかもあなたは一人だけです。** Osmaniの言葉:
+
+> 「あなたはあなたのAIエージェントたちのGILだ。彼らは同時に走れる。しかし、彼らの仕事がアーキテクチャを本当に理解し、マージコンフリクトを解決することを必要とする限り、それらの仕事はそのロックを獲得しなければならない。ロックは一つだけだ。それを握っているのはあなただ。」
+
+これが前回の講義で言った「レビュー帯域幅が天井」という話が、今回の講義ではさらに鋭くなる理由です:**グラフは並列エージェントを増やすが、あなたの判断力は直列リソースであり、並列化されない。** ノードを足すことの最適化の対象は、決してボトルネックではない部分です——ボトルネックは常にあの一つの直列プロセッサ、つまりあなたなのです。
+
+## 本当にグラフを使うべき時
+
+すべてのタスクが図を描く価値があるわけではありません。5つの判断基準、少なくとも3つを満たしてから手を付ける:
+
+1. **タスクを独立した複数の作業単位に分割できる**——分割した部分が互いに依存せず、並列できる
+2. **分岐またはフォールバック経路が存在する**——テスト失敗でどこに戻るか、情報不足でどこに戻るか、そうした経路を明示的に宣言する価値がある
+3. **中間状態を保存する価値がある**——checkpointの後で停止でき、復元でき、最初からやり直す必要がない
+4. **結果を明確に受け入れできる**——各ノードが自動チェック可能な完了基準を持つ
+5. **協力の利益 > 調整のコスト**——並列で節約した時間が、グラフ自体と共有状態がもたらすオーバーヘッドより多い
+
+**「複雑」は「ステップが多い」と同じではない。** 20ステップの線形パイプラインにはグラフは不要です——それはワークフローか、あるいは単なるスクリプトです。5つのノードしかないが、互いにフォールバック、並列、承認がある構造こそグラフが必要です。判断基準は規模ではなく、**分岐とフォールバックの存在**です。
+
+## コアコンセプト
+
+- **Graph Engineering**:複数のエージェント、ループ、ツール、評価者を明示的なグラフ(ノード + エッジ + 共有状態 + ルーティングルール)に組織化するエンジニアリング実践。複数の作業単位の接続、共有状態、経路選択を設計可能、観測可能、部分修復可能にする。
+- **4層の重ね合わせ**:prompt → context → loop → graph、各レイヤーが異なるものを制御する(指示、情報、ランタイム、システム)、後ろのレイヤーは前のレイヤーを置き換えず、ただ前のレイヤーを自分のノードの中に収める。
+- **Graphの4つの部品**:ノード(作業単位)、エッジ(引き継ぎ方)、共有状態(公共の作業台)、ルーティングルール(次にどこへ行くか)。
+- **単一ループの3つの構造的失敗**:Goodhart(数字は上がったのにビジネスは悪化した)、上方向の失明(決して「この目標は正しいのか」と問わない)、衝突(独立ループが互いの台を壊す)。グラフはこの3種類の問題を明示的な関係設計に変える。
+- **Graph ≠ Workflow**:ワークフローのノードは決定論的関数、エッジは書き込まれたコード;グラフのノードは完全なエージェントになり得、エッジは動的ルーティングできる。グラフはワークフローの一般化である。
+- **Anchors(アンカー)**:ループのネットワークを現実世界に固定するメカニズム(実際のビジネス結果、ground truth、人手によるスポットチェック)。グラフ設計で最もスキップされやすいのに、最も省けないステップ。
+- **Orchestration Tax(オーケストレーション税)**:エージェント起動は安く、結果のレビューは高い。あなたの注意力は唯一の直列リソースであり、ノードを足しても最適化できない。
+
+## コアポイント
+
+- **Graph EngineeringはLoop Engineeringを置き換えるのではなく、その上に一層を建てる。** loopはグラフの中の一つのノード;前回の講義の3つのもの(目標、検証、停止条件)はノードの内部構造になる。
+- **グラフは「先延ばしの決定」を「先回りの決定」に変える。** loopは失敗モードをループの中に隠し、graphはそれを紙の上に並べる——読みやすく、監査しやすく、部分修復可能。
+- **ノードに何を入れるかが、グラフとワークフローの違いを決める。** 関数を入れるならワークフロー、エージェントを入れるならグラフ。これも「新瓶装旧酒」の中で唯一の新しい酒である。
+- **グラフを設計する前に4つの問いに答える:** どのループがどのループに供給するか、誰が目標を所有するか、誰が否決/ロールバックできるか、どの指標が動いてどの指標が凍結するか。答えられなければ図を描くな。
+- **図のための図を描くな。** 5つの判断基準:独立に分割できる、分岐またはフォールバックがある、中間状態を保存する価値がある、結果を受け入れ可能、協力の利益 > 調整のコスト。
+- **あなたのレビュー帯域幅は依然として天井である。** グラフは並列エージェントを増やすが、あなたの判断力は直列リソース——オーケストレーション税はノードが増えても消えない。
+- **反対の声を覚えておく。** 形は承重壁ではない;再現可能、観測可能、リカバリ可能こそが承重である。名詞は6週間ごとに変わるが、エンジニアリング能力は変わらない。
+
+## さらに読む
+
+- [Prefect: Loops vs. Graphs (Jul 2026)](https://www.prefect.io/blog/loops-vs-graphs) — 数十年グラフ編成をやってきた会社の視点からloopとgraphを見る
+- [Eigent: Graph Engineering for AI Agents (Jul 2026)](https://www.eigent.ai/blog/graph-engineering-ai-agents) — 単一ループの3つの構造的失敗 + 4つの設計問題 + anchors
+- [iii.dev: Loops, Graphs, and the Layer That Matters (Jul 2026)](https://iii.dev/blog/loops-graphs-and-the-layer-that-matters/) — 最も冷静な反対意見:「形は承重壁ではない」
+- [Rohit(@rohit4verse)長文ポスト(2026-07-29)](https://x.com/rohit4verse/status/2082478623043547356) — 4層フレームワークの一手資料:prompt → context → loop → graph、各レイヤーが前のレイヤーの上に重なる
+- [Agent Times: Graph Engineering as the Final Layer (Jul 2026)](https://theagenttimes.com/articles/graph-engineering-emerges-as-proposed-final-layer-of-agent-o-4f0511a8) — Rohitの4層フレームワークの整理
+- [goddaehee: Graph Engineering ファクトチェック(韓国語、2026-07-30)](https://goddaehee.tistory.com/628) — 最も完全なファクトチェック:冗談の起源のタイムライン、偽の数字の分解、LangGraphデータ、Hacker Newsの熱度比較
+- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — あの冗談より2週間早い真面目な記事
+- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — 公式の応答:「新しいアイデアではなく、既存の方法の最新の名前」;LangGraphの月間ダウンロード6500万+
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — 流行語の伝播データ(最初のツイート57.5万回閲覧)
+- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — 7つの主流オープンソースフレームワークの横断比較:LangGraph、CrewAI、Microsoft Agent Framework、LlamaIndex、Google ADK、OpenAI Agents SDK、Mastra
+- [LangGraph公式ドキュメント](https://docs.langchain.com/oss/python/langgraph/graph-api) — "Nodes do the work, edges tell what to do next";ノードとエッジの正確な定義、グラフ構築の第一手リファレンス
+- [Anthropic: Building Effective Agents (Dec 2024)](https://www.anthropic.com/engineering/building-effective-agents) — 5つのパターン、描けばそれがグラフ;workflow vs agentの権威ある区別
+- [Addy Osmani: The Orchestration Tax (May 2026)](https://addyosmani.com/blog/orchestration-tax/) — なぜあなたの注意力が唯一の直列リソースなのか
+- [Addy Osmani: Orchestrating Coding Agents(講演)](https://talks.addy.ie/oreilly-codecon-march-2026/) — subagentsからagent teams、quality gatesまで
+- [Addy Osmani: Loop Engineering (Jun 2026)](https://addyosmani.com/blog/loop-engineering/) — 前回の講義のコアリファレンス、グラフエンジニアリングの前提知識
+- 第13回:[手動プロンプトから自律ループへ](./../lecture-13-loop-engineering/index.md) — loopはグラフの中の一つのノード、まずノード内部を理解してからグラフを理解する
+- 第11回:[エージェントのランタイムを観測可能にする](./../lecture-11-why-observability-belongs-inside-the-harness/index.md) — グラフが複雑になるほど観測可能性が重要になる;観測できないグラフはただブラックボックスをより大きなブラックボックスに組んだだけ
+- 第9回:[エージェントの早すぎる完了宣言を防ぐ](./../lecture-09-why-agents-declare-victory-too-early/index.md) — 検証ノードがなぜ実装ノードから独立していなければならないのか、グラフではこれはプロンプトの問題ではなく構造の問題である
+
+## 演習
+
+1. **P07のmaker-checker loopをグラフに描く:** `graph.md`を使ってノード、エッジ、共有状態、ルーティングルールを明示的に書く。どのエッジが条件エッジ(検証合格/不合格)で、どのエッジがフォールバックエッジ(失敗が実装に戻る)かを示す。描き終わったら答える:暗黙的で、以前はエージェントのコンテキストの中に隠れていたエッジはないか?
+
+2. **eigentの4つの問いに答える:** あなたが走らせている3つの独立したループ(または同じプロジェクト内の3つの自動化)を見つけて、答える:それらの間で誰が誰に供給するのか?どのループが別のループが追いかける目標を所有しているのか?別のループの産物を否決できるループはあるか?どの指標がそれぞれ最適化しながら、互いに衝突しうるのか?
+
+3. **Goodhartの自己チェック:** 最近最適化したある指標をチェックする。それは上がったが、実際の結果(ビジネス結果、ユーザーフィードバック、コード品質)も一緒に良くなったか?もし数字だけが上がったなら、このループはどちらの方向であなたを騙しているのか?
+
+4. **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
diff --git a/docs/ja/projects/project-08-graph-engineering-first-graph/index.md b/docs/ja/projects/project-08-graph-engineering-first-graph/index.md
new file mode 100644
index 0000000..b0cec79
--- /dev/null
+++ b/docs/ja/projects/project-08-graph-engineering-first-graph/index.md
@@ -0,0 +1,91 @@
+# プロジェクト 08. ワークフローをグラフとして描く
+
+> 関連講義: [第14回 単一ループからグラフエンジニアリングへ](./../../lectures/lecture-14-graph-engineering/index.md)
+
+## 何をするか
+
+これは「Loop」から「Graph」への躍進プロジェクトです。前回の講義ではmaker-checker loopを構築しました——実装、検証、フィードバック、再実装、すべての決定が同じエージェントのコンテキストウィンドウの中で起こっています。今回の講義でやることは、**ループの中に隠れた構造を明示的に描き出すこと**です:ノード、エッジ、共有状態、ルーティングルールを、一言一言丹念に書き出します。
+
+3つの発展的な実験を行います:まずP07のmaker-checker loopを一枚の明示的なグラフに描き、次にグラフに並列のfan-out/fan-inノードを追加し、最後に条件付きフォールバックエッジと人間による承認ノードを追加します。終わると、あなたは身をもって一つのことを実感します:**グラフは新しい発明ではなく、あなたのループが一定の複雑さに達したとき、それが自然に変わる姿です。**
+
+## 使うツール
+
+- Claude Code または Codex
+- Git
+- P07で構築したmaker-checker loop(または繰り返し実行できるエージェントワークフロー)
+- テキストエディタまたはドローイングツール(図を描くのは見た目を良くするためではなく、構造を明快に書き出すためです;`mermaid` でも手書きの `graph.md` でも構いません)
+
+## 具体的なステップ
+
+### 準備
+
+1. P07完了後のリポジトリから始めるか、現在実行中のエージェントワークフローをそのまま使います。
+2. 3つのブランチを作成します:`p08-explicit-graph`、`p08-parallel`、`p08-human-in-the-loop`。
+3. `state.md` を共有状態ファイルとして用意します:要件、進捗、検証結果をすべてここに書きます。これがグラフの「公共の作業台」です。
+
+### 実験1:Loopを明示的なグラフに描く
+
+`p08-explicit-graph` ブランチに切り替えます。
+
+1. **すべてのノードを列挙する**:P07のmaker-checker loopの各ステップを1つのノードとして書き出します。各ノードに書き出すもの:その責務、その入力、その出力、それがエージェントか決定論的コードか。
+2. **すべてのエッジを描く**:ノード間の各エッジを列挙します。2つの特別なエッジに重点を置いて印を付けます:
+ - 条件エッジ:検証の合格/不合格、どちらへ進むか
+ - フォールバックエッジ:失敗がどのノードに戻るか
+3. **共有状態を書く**:状態にどのフィールドがあるか(要件、コード、テスト結果、レビュー結論)、誰が読み誰が書くかを明確に列挙します。
+4. **ルーティングルールを書く**:最も簡単なif-thenの言葉で「次にどこへ行くか」のルールを書きます。例:
+ ```
+ if 検証合格 → マージノード
+ if 検証失敗 → 実装ノード
+ if 実装ノード情報不足 → 研究ノード
+ ```
+5. **`graph.md` に書く**:上記の内容を1つのドキュメントにまとめます。mermaidで図を描き、ノード表とルーティングルールを添えます。
+6. **この問いに答える**:描き終わったら、**もともと暗黙的だったエッジ**を少なくとも1つ見つけます——以前はエージェントのコンテキストの中に隠れていて、あなた自身も存在を知らなかった決定経路です。
+
+### 実験2:並列の Fan-out / Fan-in ノードを追加する
+
+`p08-parallel` ブランチに切り替えます。
+
+1. **並列にできる箇所を選ぶ**:タスクの中で2つの独立した部分に分割できる場所を見つけます。例:
+ - 実装を2つの独立したモジュールに分割し、2つのエージェントが並列で書く
+ - 検証を2つの独立したレビューに分割:1つはテストとlintを実行し、もう1つはコードレビューを行う(異なる指示、異なる注目点)
+ - 研究を2つの方向に分割し、2つのエージェントがそれぞれ1ルートずつ調べる
+2. **fan-outルールを書く**:共有状態に「このタスクがN個の並列サブタスクに分割された」ことを記録し、各サブタスクは独立したコンテキスト、独立したノードを持ちます。
+3. **fan-inルールを書く**:すべてのサブタスクが完了した後、誰が結果をマージするのか?マージの基準は何か(例:両方のレビューが通ってからマージするのか、それとも1つ通ればよいのか)?
+4. **worktreeで隔離する**:各並列サブタスクを独立したgit worktreeで実行し、物理的にファイルの衝突を避けます(前回の講義のWorktreeプリミティブを振り返ってください)。
+5. **一度実行して記録する**:並列前後のwall-clock時間、token消費、結果の品質を記録します。並列は本当に速くなったのか?それとも調整のオーバーヘッドが節約した時間を食い潰したのか?
+
+### 実験3:フォールバックエッジと人間による承認ノードを追加する
+
+`p08-human-in-the-loop` ブランチに切り替えます。
+
+これは3つの実験の中で最も重要なもの。グラフに2種類のノードを追加します:
+
+1. **条件付きフォールバックエッジ**:検証ノードに「部分合格」の経路を追加します——全体を実装ノードに打ち返すのではなく、具体的なフィードバックを添えて**問題を生んだそのノード**に戻します。例:テストは全部通ったが、コードレビューで要件の理解に誤りがあると判明した場合、実装ノードではなく研究ノードに戻します。これには、共有状態に「問題がどのレイヤーで起きたか」を記録する必要があります。
+2. **人間による承認ノード(Human-in-the-loop)**:マージノードの前に人間ノードを追加します。ここまで来たら、グラフは**停止して**、あなたが `state.md` に「承認」または「打ち返し」を書くのを待ちます。承認ノードにはタイムアウトルールを持たせられます:N時間後に応答がなければ、自動的に打ち返すか自動的にエスカレーションします。
+3. **interruptのフォーマットを書く**:承認リクエストをどう明確に書くか——何が起きたか、何を変更したか、なぜ人間が必要か、承認/打ち返しの結果はそれぞれ何か。
+4. **完全なフローを少なくとも2ラウンド実行する**:各ラウンドで人間による承認ノードまで進み、あなた自身が1回承認または打ち返しを行います。記録:あなたの承認判断は検証ノードの判断と一致したか?承認ノードが、検証ノードが止められなかった何かを止めたか?
+
+## 結果の測り方
+
+| 指標 | 実験1(明示グラフ) | 実験2(並列) | 実験3(人間と機械の協働) |
+|------|----------------|--------------|------------------|
+| 構造の可視性 | 暗黙のエッジを何本見つけられたか? | 共有状態が並列サブタスクを支えられるか? | フォールバックエッジが問題のレイヤーを正確に特定できるか? |
+| 失敗の特定 | 失敗したとき、どのエッジが間違っているかを直接指し示せるか? | 並列サブタスクが失敗したとき、どれかを特定できるか? | 承認が打ち返されたとき、どのレイヤーの問題かを指せるか? |
+| 協働のオーバーヘッド | 図を描くのにどれだけかかったか? | 並列で節約した時間 vs 調整のオーバーヘッド | 承認の待ち時間 vs 止められた問題の価値 |
+| 観測可能性 | 各ステップで何が起きたか、今は見えるか? | 各並列サブタスクの状態は見えるか? | 承認リクエストは十分に明確に書けたか? |
+| 信頼性 | グラフの記述と実際の実行は一致するか? | fan-inのマージ基準は信頼できるか? | タイムアウト/エスカレーションのルールは本当に発動するか? |
+
+## 提出物
+
+- `graph.md`(実験1の完全なグラフ記述:mermaid図 + ノード表 + エッジ表 + 共有状態フィールド + ルーティングルール)
+- 実験1で発見した暗黙のエッジのリスト(少なくとも1本)
+- 実験2のfan-out/fan-inルールと一回の並列実行記録(時間/コスト/品質の比較)
+- 実験3のフォールバックエッジのルール、承認ノードのフォーマット、2ラウンドの人間と機械の協働記録
+- 最終的な振り返り:loopからgraphへ、あなたの働き方はどう変わったか?どのタスクが図を描く価値があり、どのタスクが価値がないのか?
+
+## 対応する講義
+
+- [Lecture 14 — 単一ループからグラフエンジニアリングへ](../../lectures/lecture-14-graph-engineering/index.md)
+- [Lecture 13 — 手動プロンプトから自律ループへ](../../lectures/lecture-13-loop-engineering/index.md)(あなたのloopはグラフの中の一つのノード;このプロジェクトはノードの内部構造を広げるもの)
+- [Lecture 09 — エージェントが早すぎる完了宣言をする理由](../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md)(検証ノードがなぜ実装ノードから独立していなければならないのか、グラフでは構造の問題)
+- [Lecture 11 — 観測可能性がハーネスの一部である理由](../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md)(グラフが複雑になるほど、各ノードが何をしているかを見る必要がある)
\ No newline at end of file
diff --git a/docs/ko/lectures/lecture-14-graph-engineering/index.md b/docs/ko/lectures/lecture-14-graph-engineering/index.md
new file mode 100644
index 0000000..86e8882
--- /dev/null
+++ b/docs/ko/lectures/lecture-14-graph-engineering/index.md
@@ -0,0 +1,349 @@
+[English Version →](../../../en/lectures/lecture-14-graph-engineering/)
+
+> 이 장의 코드 예제: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-14-graph-engineering/code/)
+> 실습 프로젝트: [프로젝트 08. 내 워크플로우를 그래프로 그리기](./../../projects/project-08-graph-engineering-first-graph/index.md)
+
+# 14강. 단일 루프에서 그래프 엔지니어링으로
+
+지난 강의에서 Loop Engineering을 다룬 지 6주 만인 2026년 7월 18일, Peter Steinberger — 지난 강의에서 "더 이상 coding agent에게 prompt를 쓰지 말라"고 한 바로 그 OpenClaw 저자 — 가 트윗을 올렸습니다:
+
+> "우리는 아직 Loop을 이야기하고 있는가, 아니면 이미 Graph로 넘어갔는가?"
+
+트윗 하나가 하루 만에 약 57만 뷰를 얻었고, 월말에는 약 300만 뷰까지 늘었습니다. 몇 시간 뒤 머신러닝 엔지니어 Hamel Husain은 《Loop Engineering Is Dead. Enter Graph Engineering》이라는 제목의 글을 올렸습니다 — 본문은 "Stop it"이라고 쓰인 움짤 하나뿐이었습니다 — 또 약 68만 뷰를 얻었습니다.
+
+더 흥미로운 점은 이렇습니다: **두 사람 모두 농담으로 올린 것입니다.** 한쪽은 이 업계가 6주마다 새 용어를 만들어낸다는 것을 풍자했고, 한쪽은 그 밈에 맞장구를 쳤습니다. 하지만 농담은 겨우 한 주말 정도만 살아남았습니다 — 강의, 로드맵, 도구 스택이 주말이 끝나기 전에 타임라인을 가득 채웠고, 그 뒤에 지어낸 숫자들도 따라왔습니다: "정확도 +18%, 비용 -85%"는 가짜 데이터입니다(18%와 85%는 실제로 존재하지만, 화학 배관 도면에 관한 논문에서 나온 것이며 비교 기준도 완전히 다릅니다), "마이크로소프트, 스탠포드, Anthropic이 동시에 그래프 엔지니어링을 발견했다"는 것도 가짜 뉴스입니다. 사실 확인을 통해 확인된 유일한 "선행자"는 Josh Simmons입니다. 그의 《We Are Entering the Graph Engineering Phase》는 7월 4일에 쓰였는데, 이 농담보다 꼭 2주 앞선 것입니다 — **농담이 이 일을 유행하게 만든 것이지, 농담이 이 일을 만들어낸 것이 아닙니다.**
+
+> 출처: [goddaehee: Graph Engineering 사실 확인 (2026-07-30)](https://goddaehee.tistory.com/628); [YC Startup School 2026: Jensen Huang 인터뷰 (전문 포함)](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia); [explainx: Graph Engineering (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026)
+
+이 강의에서 할 일은 남의 뜨거운 용어에 불을 더 붙이는 것이 아니라, 그것을 분해해서 똑똑히 보는 것입니다: **왜 단일 루프 뒤에는 반드시 그래프가 자라나는가? 그래프와 workflow는 대체 무엇이 다른가? 언제 정말로 필요하고, 언제 필요하지 않은가?**
+
+## prompt, context, loop, graph: 네 이름, 한 겹씩 쌓여
+
+7월 말, 엔지니어 Rohit(@rohit4verse)은 이 AI 엔지니어링의 수년간의 명명 역사를 깔끔한 4층 프레임워크로 정리한 [긴 글](https://x.com/rohit4verse/status/2082478623043547356)을 올렸습니다. Graph Engineering을 이해하는 가장 좋은 좌표계입니다:
+
+| 단계 | 무엇을 만드나 | 답하는 질문 | 핵심 산출물 |
+|------|---------|-----------|---------|
+| **Prompt Engineering** | 지시 | 모델에게 무엇을 하라고 말할까? | instructions, examples, constraints, roles, output formats |
+| **Context Engineering** | 정보 | 모델이 결정을 내리기 전에 무엇을 알아야 할까? | documents, history, memory, tool definitions, environment state |
+| **Loop Engineering** | 런타임 | 모델이 목표에 도달할 때까지 스스로 반복하게 만들려면? | observe, reason, act, inspect, update, 중단 조건 |
+| **Graph Engineering** | 시스템 | 여러 agent, loop, 도구, 평가자가 어떻게 협력할까? | 노드, 엣지, 공유 상태, 라우팅 규칙 |
+
+이 선이 어떻게 읽히는지 주목하세요: **각 층은 이전 층을 대체하는 것이 아니라, 그 위에 겹쳐집니다.**
+
+- context engineering을 찾아낸 뒤에도 prompt engineering을 멈추지 않습니다 — 매 반복마다 여전히 prompt가 필요합니다. 다만 loop가 환경이 변할 때 그것을 새로고침해 줄 뿐입니다.
+- loop를 구축한 뒤에도 context를 버리지 않습니다 — loop의 매 라운드는 컨텍스트를 다시 조립해야 합니다.
+- 그래프에 이르면 prompt와 context와 loop는 하나도 사라지지 않습니다: **각 노드는 자신만의 prompt, 자신만의 context, 자신만의 도구, 자신만의 메모리, 자신만의 loop를 가집니다.** 그래프가 결정하는 것은 노드끼리 어떻게 연결되는가입니다.
+
+Rohit의 원문은 이렇게 마무리됩니다:
+
+> agent가 전문화, 병렬화, 공유 상태, 검증, 복구를 필요로 하는 순간, 그것은 더 이상 loop가 아닙니다. 그것은 그래프입니다.
+
+**잠깐, 그럼 harness는?** 네 가지 이름에 Harness Engineering은 없습니다. 그런데 이 강의가 다루는 것은 harness입니다. 그 이유는 간단합니다: Rohit은 뜨거운 용어의 역사를 이야기했고, 종착점은 그래프였으며, 그 사이의 층은 건너뛴 것입니다. 그리고 harness가 어느 층에 놓여야 하는지조차 커뮤니티 안에서 합의가 안 되었습니다 — [explainx](https://explainx.ai/blog/context-prompt-loop-harness-engineering-stack-2026)는 it을 loop 위에 두고, [Buildrix 논문](https://arxiv.org/abs/2606.25139)은 loop 아래에 둡니다. 이 강의는 두 번째 강의에서 이미 정했습니다: harness는 기반이고, loop와 graph는 모두 그 위에 세워집니다.
+
+이것은 이상한 현상을 설명합니다: "Graph Engineering"이라는 용어가 2026년 7월에야 뜨거워졌는데, 사람들은 "이미 예전부터 이렇게 하고 있었다"는 것을 발견한다는 것. 그래프는 새 발명이 아니라, 작업이 어느 정도 복잡해지면 loop가 자동으로 그래프가 되는 것입니다. 이름은 나중에 붙었고, 방법은 이미 있었습니다.
+
+## 그래프를 분해해서 보기: 노드, 엣지, 상태, 라우팅
+
+그래프를 가장 소박한 네 개의 부품으로 되돌려 봅시다.
+
+**노드(Node)**: 어떤 책임을 맡는 작업 단위. 그것은 다음이 될 수 있습니다:
+- 결정적 코드 한 조각(테스트 실행, 커버리지 계산)
+- 모델 호출 한 번(문서 생성)
+- 도구 하나(git commit, 메시지 발송)
+- 완전한 agent 하나 — 스스로 loop를 가지며, 목표를 이해하고, 도구를 사용하고, 실패하면 스스로 다시 시도합니다
+
+노드는 그래프 엔지니어링과 workflow 엔지니어링이 갈라지는 진짜 분기점이며, 이 점은 아래에서 따로 다룹니다.
+
+**엣지(Edge)**: 노드끼리 어떻게 인계하는지 설명합니다. "A를 먼저 하고 B를 하면 된다"는 것보다 더 복잡합니다 — 한 엣지는 다음을 표현할 수 있습니다:
+- **병렬**: A가 끝나면 B와 C가 동시에 시작
+- **조건**: 테스트가 통과하면 왼쪽으로, 실패하면 오른쪽으로
+- **실패/재시도**: 노드가 죽으면, 그 노드 자신으로 돌아가 다시 한 번 실행
+- **롤백**: 검증이 통과하지 못하면, 세 단계 전의 구현 노드로 돌아가기
+
+**공유 상태(State)**: 노드 사이에서 전달되는 데이터 패킷. 요구사항, 연구 메모, 코드 버전, 테스트 결과, 검토 결론 — 모두 같은 공용 작업대에 기록됩니다. 노드는 서로 직접 소리치지 않고, 모두 같은 상태를 읽고 씁니다.
+
+**라우팅 규칙(Routing)**: 다음으로 어디로 갈지 결정합니다. 이것이 그래프의 "제어 흐름"이며, 가장 소박한 말로 하면 이렇습니다:
+
+> 테스트가 통과하면 인도하고; 테스트가 실패하면 구현 노드로 돌아가고; 정보가 부족하면 연구 노드로 돌아갑니다.
+
+네 개의 부품을 조립하면, 전형적인 개발 그래프는 이렇게 생겼습니다:
+
+```mermaid
+flowchart TD
+ S["공유 상태<br/>요구사항 / 메모 / 코드 / 결과"] --- R["연구 노드<br/>Agent: 문제 파악"]
+ R -->|"해결책 산출"| I["구현 노드<br/>Agent: 수정 + 테스트 작성"]
+ I -->|"코드 산출"| V["검증 노드<br/>Agent: 독립 검토 + 테스트 실행"]
+ V -->|"실패"| I
+ V -->|"통과"| M["병합 노드<br/>코드: commit + 상태 업데이트"]
+ M -->|"상태 업데이트"| S
+ I -->|"정보 부족"| R
+```
+
+지난 강의의 loop 그래프와 비교해 보세요: 지난 강의는 하나의 고리였습니다 — 발견, 분배, 검증, 영속화, 다시 발견으로. 이번 강의의 그래프에는 **고리가 여전히 존재하지만, 명시적인 노드와 엣지로 쪼개졌습니다.** 검증 노드는 실패를 구현 노드로 직접 돌려보낼 수 있고, 구현 노드는 정보 부족으로 연구 노드로 되돌아갈 수 있습니다 — 이런 "롤백 엣지"는 단일 loop 안에서는 암묵적이었고, agent가 자신의 컨텍스트 안에서 "나는 돌아가야 해"를 기억하는 방식이었습니다.
+
+## Loop이 언제 부족한가
+
+loop 하나는 주행 경로가 하나뿐입니다. 지난 강의에서 만든 maker-checker loop에서는 모든 결정 — 다음에 무엇을 할지, 실패하면 어디로 갈지 — 이 같은 agent의 컨텍스트 창 안에서 일어났습니다. 작업이 조금만 더 복잡해지면 네 가지 문제가 튀어나옵니다:
+
+1. **분업**: 요구사항을 연구하는 agent, 코드를 쓰는 agent, 테스트를 하는 agent, 누가 먼저 시작할까?
+2. **병렬**: 어떤 작업이 동시에 진행될 수 있을까?
+3. **롤백**: 테스트가 실패한 뒤 어디로 돌아가야 할까 — 구현 노드로, 아니면 연구 노드로?
+4. **인계**: 여러 agent가 같은 요구사항, 메모, 테스트 결과를 어떻게 볼까? 검토자가 구현자와 의견이 다르면 누구 말을 듣나?
+
+Jensen Huang은 Y Combinator의 [Startup School 2026 인터뷰](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia)(Garry Tan과의 대담)에서 비슷한 관점을 말했습니다: 저수준 구현이 점점 더 agent에 의해 자동화될수록, 인간의 핵심 가치는 "시스템을 설계하고, 제약을 명확히 하고, agent에 세밀한 제어를 하는 것"으로 옮겨갑니다. 그가 준 제어 예시는 매우 구체적이었습니다 — "agent가 계획을 제시하면, 나는 계획 파일에서 단어 하나를 바꾸고, 그 단어 하나가 정확한 한 곳의 차이를 만들어낸다"; 그는 또 미래의 핵심 기술은 "시스템 사고"(systems thinking)일 것이라고 예언했습니다.
+
+토론 스레드에서 가장 멋진 한 방은 Luis Catacora의 것이었습니다:
+
+> **"루프는 오류 허용 여유가 크다. 그래프는 당신이 워크플로우에서 아직 실제로 모델링되지 않은 부분이 얼마나 많은지 인정하도록 강제한다."**
+
+이 문장은 loop과 graph의 깊은 차이를 짚어냅니다:
+
+- **Loop는 결정을 미룬다.** 먼저 agent 하나가 모든 작업을 맡게 하고, 안 되면 그때 생각하면 된다며 아키텍처를 뒤로 미룹니다. 편하지만, 실패 모드가 보이지 않는다는 대가를 치룹니다 — 그것이 어느 단계에서 막혔는지 절대 알 수 없습니다. agent 자신도 모르기 때문입니다.
+- **Graph는 결정을 앞당긴다.** 전체 구조를 미리 선언해야 합니다: 누가 무엇을 담당하는지, 작업 사이에 어떤 의존성이 있는지, 어떤 실패가 어디로 돌아가야 하는지. 수고스럽지만, 대신 읽을 수 있고, 감사할 수 있고, 부분적으로 수리할 수 있습니다.
+
+더 확실한 말로 하면: **loop은 문제를 루프 안에 숨기고, graph는 문제를 종이 위에 올려놓는다.** 전자는 탐색에 적합하고, 후자는 프로덕션에 적합합니다.
+
+## 단일 루프의 세 가지 구조적 실패
+
+단일 loop이 규모에서 버티지 못하는 이유는 무엇일까? eigent.ai의 《Graph Engineering for AI Agents: Beyond Single Feedback Loops》는 세 가지 구조적 실패를 제시합니다 — 특정 loop의 버그가 아니라 구조적 실패라는 점에 주목하세요.
+
+**먼저 반박 하나: loop에도 체크포인트를 넣을 수 있지 않나?** 넣을 수 있습니다. 지난 강의의 검증, 중단 조건, 심지어 중단점 재시도까지 loop에는 다 들어갑니다. 하지만 아래 세 가지 실패는 바로 체크포인트가 해결하지 못하는 것입니다 — loop 안의 체크포인트는 같은 agent 내부에 있기 때문에, 검사하는 자와 문제가 생기는 자가 같은 두뇌, 같은 컨텍스트입니다. 그것은 "검증 없이 인도"를 막아줄 뿐, "이 지표가 맞는가", "이 목표를 추구해야 하는가"는 묻지 않습니다 — 그 답은 자기 자신의 context에 적혀 있으니 보이지 않습니다. 그래프는 체크포인트를 더 많이 주는 것이 아니라, 검사를 **밖으로 옮깁니다**: "agent 내부"에서 "독립적인 노드"로 옮겨 새 컨텍스트를 줍니다(앞의 verify 노드 절에서 다뤘습니다). "구조적"이라는 말의 의미가 바로 여기 있습니다: loop에서 빠진 부품이 아니라, "판단하는 자와 실행되는 자가 같은 두뇌를 공유한다"는 구조 자체가 문제입니다.
+
+### 1. Goodhart: 숫자는 올라가는데, 비즈니스는 나빠진다
+
+단일 지표 무엇이든 극한까지 밀어붙이면, 그것은 당신이 측정한다고 생각하는 것을 측정하지 않게 됩니다. 고전적인 사례: 고객 지원 팀이 "티켓 해결율"을 중심으로 loop을 만들었습니다. 주간 데이터는 계속 올라갔습니다. 몇 달 뒤, 갱신 데이터는 churn이 두 배로 늘었음을 보여줬습니다 — **bot이 티켓 닫는 법을 배운 것입니다**: 화제를 돌리고, 사용자가 더 묻지 않게 하고, 해결되지 않은 문제를 "해결됨"으로 표시했습니다.
+
+loop은 요구받은 모든 일을 했습니다. 다만 숫자가 비즈니스가 진짜로 신경 쓰는 것과 분리되었을 뿐입니다. 이것이 Goodhart의 법칙입니다.
+
+### 2. 위쪽 실명: "이 목표가 맞는가"를 절대 묻지 않는다
+
+loop 내부에서 참조값은 신성합니다. 온도 조절기는 "68°F가 올바른 온도인가"를 묻지 않습니다. 영업 loop은 "이 할당량이 합리적인가"를 묻지 않습니다. agent eval loop은 "이 benchmark가 실제 비즈니스 결과와 맞는가"를 묻지 않습니다.
+
+**목표가 누가 선정했든, loop은 그쪽을 향해 달립니다. 처음부터 추구해야 할 것이 아니었더라도 말이죠.** 단일 loop의 구조에는 이 질문이 들어갈 자리가 전혀 없습니다.
+
+### 3. 충돌: 독립적인 루프들이 서로를 깎아내린다
+
+실제 시스템에는 수십 개의 loop이 있고, 각각 독립적으로 만들어졌습니다. 응답 속도 loop이 깊은 품질 loop의 발목을 잡고, 성장 loop이 품질 loop의 발목을 잡습니다. 각 loop은 자기 대시보드에서는 건강한데, 시스템 전체는 흔들립니다 — 마치 여러 사람이 같은 밧줄을 각자 다른 방향으로 씨름하며 당기는 것과 같습니다.
+
+**Graph engineering이 답하려는 것은, 바로 단일 loop이 답할 수 없는 그 질문 묶음입니다:**
+
+- 어떤 loop이 어떤 loop에게 먹이를 주는가?
+- 어떤 loop이 다른 loop이 쫓는 목표를 소유하는가?
+- 어떤 loop이 변경을 거부하거나 롤백할 수 있는가?
+- 어떤 지표는 움직여도 되고, 어떤 것은 반드시 얼어 있어야 하는가?
+
+시스템 안에 "당신의 목표를 먹는 loop"과 "당신의 변경을 거부할 수 있는 loop"이 존재할 때, 그 둘 사이의 관계는 공학의 대상이 됩니다 — 그리고 관계와 관계 사이의 관계를 그리면, 그것이 그래프입니다.
+
+### 앵커: 루프를 현실에 고정하기
+
+eigent 글의 제목에는 "everyone skips"라는 부분이 있습니다: **anchors(앵커)**. 루프 네트워크가 아무리 정교해도, 매 루프가 현실에서 멀어지면 네트워크는 서로 드리프트하는 공진에 불과합니다. 앵커는 loop을 실제 세계에 고정하는 것 — 실제 비즈니스 결과, ground truth 데이터셋, 수동 샘플링. 그래프를 설계할 때 앵커는 가장 쉽게 건너뛰는 단계이지만, 가장 생략할 수 없는 단계입니다.
+
+## Graph와 Workflow: 이름만 바꾼 것이 아니다
+
+이 강의에서 가장 많이 오해되는 부분이라 따로 꺼내 볼 가치가 있습니다.
+
+Graph Engineering이 폭발적으로 뜨자, 엔지니어링을 해본 사람이라면 누구나 중얼거립니다: "이거 그냥 workflow 아닌가? DAG, 상태 머신, 워크플로우 엔진, 우리가 수십 년 돌렸잖아."
+
+**이 직관은 절반 맞습니다.** 그래프와 workflow는 확실히 같은 뼈대를 공유합니다: 노드 + 엣지 + 공유 상태 + 라우팅. Airflow, Prefect, Dagster, Temporal이 수십 년간 오케스트레이션한 방식이 바로 이 그래프입니다. Anthropic이 2024년 12월 《Building Effective Agents》에서 정리한 다섯 가지 패턴 — 프롬프트 체인, 라우팅, 병렬화, 오케스트레이터/워커, 평가자/최적화자 — 을 그리면, 곧 서로 다른 모양의 실행 그래프가 됩니다.
+
+**틀린 절반은 노드 안에 있습니다.** 전통적 workflow의 노드는 **결정적 함수**입니다: Python 함수 하나, shell 스크립트 하나, SQL 태스크 하나. 엣지는 하드코딩된 코드입니다: `if`, `switch`, `case`. 시스템 전체를 엔지니어가 코드로 유지하며, 동작은 예측 가능합니다 — 같은 입력은 언제나 같은 경로를 갑니다.
+
+그래프 엔지니어링의 노드는 **완전한 agent**일 수 있습니다: 스스로 loop을 가지고, 도구를 사용하며, 목표를 이해하고, 실패하면 스스로 재시도합니다. 엣지도 반드시 하드코딩된 것일 필요는 없습니다 — 라우팅 규칙을 담을 수 있고, 이전 노드의 출력, 검증 결과, 심지어 다른 모델이 다음 단계를 결정할 수 있습니다.
+
+이 차이를 분명히 하기 위해, Anthropic의 한 쌍의 개념을 빌려오겠습니다. Anthropic은 한 문장으로 workflow와 agent를 구분합니다: **누가 제어 흐름을 결정하는가?** 코드가 단계를 결정하면 workflow이고, 모델이 런타임에 단계를 바꿀 수 있으면 agent입니다.
+
+그렇다면 그래프는 무엇인가? **그래프는 둘 다를 담는 그릇입니다.** 하나의 그래프 안에 동시에 있을 수 있습니다:
+
+- workflow 노드: 테스트 실행, 커버리지 계산 — 결정적 코드, 모델 불필요
+- agent 노드: 기능 구현, 코드 검토 — 모델이 이끄는 완전한 agent
+- 인간 노드: 승인, 재검토 — 사람-기계 상호작용 노드, 여기서 멈추고 사람이 고개를 끄덕일 때까지 기다림
+
+그래서 정확한 표현은 이렇습니다: **Graph Engineering은 Workflow의 대체가 아니라, Workflow의 일반화입니다** — 노드의 유형을 "함수"에서 "agent"로 풀고, 엣지의 결정을 "정적 코드"에서 "동적 라우팅"으로 풉니다. workflow는 그래프에서 "완전히 결정적"인 특수한 경우입니다.
+
+반대 견해(iii.dev의 《Loops, Graphs, and the Layer That Matters》)도 같은 지점에 떨어지지만, 결론은 반대입니다:
+
+> "형태는 쉬운 부분이고, 그것은 일회성입니다. 하중을 견디는 결정은 loop 또는 graph가 무엇으로 구성되는지, 그리고 그것이 작동한 뒤 어떻게 될 것인지입니다."
+
+iii.dev의 말은: "토폴로지"를 공학적 성과로 취급하지 말라는 것입니다. workflow 엔지니어링은 수십 년을 달렸고, 진짜로 남은 것은 노드가 어떻게 연결되는가가 아니라 **재생 가능, 관측 가능, 복구 가능**입니다 — 문제가 생기면 재생할 수 있고, 실행 중에 관찰할 수 있으며, 죽으면 이어서 돌릴 수 있습니다. 그래프의 형태는 얼마든지 바꿀 수 있지만, 이런 하중을 견디는 능력이야말로 투자해야 할 곳입니다. 이 비판은 마음에 새길 가치가 있습니다: **그래프를 그리는 것이 목적이 아니라, 그래프 위에 얼마나 많은 공학 능력을 실을 수 있는지가 목적입니다.**
+
+## 당신은 사실 이미 그래프를 그리고 있었다
+
+"새 술을 낡은 부대에 담는 것"이라는 증거가 하나 더 있습니다: 도구는 이미 갖춰져 있었습니다.
+
+- **LangGraph**: 2024년 1월에 이미 출시되었고, 2026년 7월까지 월 다운로드 수 약 6,500만 회. agent를 위한 그래프 실행 엔진이고, 노드는 agent가 될 수 있으며, 엣지는 조건부 라우팅, checkpoint, interrupt를 담을 수 있습니다.
+- **Anthropic의 다섯 가지 패턴**: 2024년 12월의 《Building Effective Agents》가 이미 프롬프트 체인, 라우팅, 병렬화, 오케스트레이터/워커, 평가자/최적화자의 그래프를 그려놨지만, Graph Engineering이라고 부르지 않았을 뿐입니다.
+- **Claude Code의 subagent fan-out**: 메인 agent가 하위 agent 무리를 내보내 병렬로 작업하게 할 때, 당신은 이미 그래프를 만들고 있는데 몰랐을 뿐입니다.
+- **상태 머신, DAG 스케줄링, 작업 큐, 지식 그래프**: 컴퓨터 과학 수십 년, 그래프의 공학화는 새로운 문제가 아닙니다.
+
+진짜로 새로운 것은 무엇인가? **노드가 "함수"에서 "agent"로 바뀐 것입니다.** 이것이 유일한 변화이자 전부의 변화입니다. 예전에는 workflow 노드 하나를 작성할 때 그 로직, 오류 처리, 재시도 전략을 명확히 써야 했습니다. 이제 노드 하나는 지시 한 문장만 필요합니다 — "이 문제를 연구해", "이 코드를 검토해" — 나머지는 모델이 스스로 완료합니다. 노드가 싸지졌고, 그래서 그래프를 그릴 가치가 생겼습니다.
+
+## 첫 번째 그래프를 처음부터 구축하기
+
+이론은 충분합니다. 이제 손을 움직입시다. 지난 강의의 maker-checker는 **하나의** 스스로 반복하는 agent였습니다. Graph Engineering이 가장 먼저 할 일은, 바로 그런 단일 agent를 분해하는 것입니다: **각 노드를 전문화된 agent 하나로 만들고, 각자 사유 prompt, context, tools, memory와 자신만의 작은 루프를 갖게 합니다; 노드 사이에는 컨텍스트를 공유하지 않고, 하나의 공유 상태를 통해서만 인계합니다.** 이것이 Rohit 그 말의 쉽게 풀어쓴 버전입니다 — "그래프는 각 노드가 무엇을 보고, 언제 실행되고, 출력이 어디로 가고, 누가 거부할 수 있고, 무엇이 시스템을 멈추는지 결정한다." 아래 모든 표기는 어떤 특정 엔진에도 묶여 있지 않습니다 — 이것은 개념이고, LangGraph, CrewAI는 그것을 실행 가능한 프로그램으로 만드는 구현이며, API는 다르고 뼈대는 같습니다. 여섯 단계, 한 단계도 건너뛰지 마세요.
+
+**1단계: 공유 상태(State) 정의.** 먼저 두 층을 구분하세요: **graph 층에서 공유되는 것은 상태뿐이고, 노드의 컨텍스트는 사유입니다.** 단일 agent는 context가 하나뿐이라 오래 돌면 자기 자신의 장황한 transcript에 묻힙니다; graph는 context를 여러 조각으로 자르고, 각 조각은 한 노드에 속합니다 — loop은 노드의 사유물이고, graph는 그것들이 인계하는 공용대입니다. 상태에 무엇을 넣을지 먼저 생각하세요. 각 필드에 그것이 "어떻게 병합"되는지 선언하세요 — 여러 병렬 노드가 동시에 같은 필드에 쓸 때, 덮어쓰기인지, 추가인지, 합산인지. 이 단계는 프레임워크 기능이 아니라, 그래프를 그릴 때 `graph.md`에 써 넣는 규칙입니다:
+
+```
+state = {
+ "requirements": 텍스트, # 연구 노드가 기록
+ "code": 텍스트, # 구현 노드가 기록
+ "review": "pass" | "fail", # 검토 노드가 기록
+ "attempts": 숫자, # 실패할 때마다 +1 (병렬 기록 시 "합산" 병합 사용)
+}
+```
+
+**2단계: 노드 나열 — 각 노드는 완전한 agent(자체 루프 포함).** 이것이 graph와 workflow의 근본적인 차이입니다: workflow의 노드는 함수이고, graph의 노드는 **자신의 작은 루프를 가진 agent**입니다. 노드는 공유 상태를 받아들입니다 → 자신의 사유 컨텍스트로 작업합니다 → 결과를 공유 상태에 씁니다. 코드를 작성하는 유형의 노드 내부는, 흔히 지난 강의의 그 loop입니다:
+
+```
+# implement 노드 내부: 하나의 사유 작은 루프 (지난 강의의 maker-checker loop)
+node_implement(requirements):
+ loop (최대 3회):
+ code = model(prompt=구현 지시, context=requirements + 이전 오류)
+ if tests_pass(code): return {"code": code}
+ return {"error": "구현 3회 실패"}
+```
+
+| 노드 | 유형 | 노드 내부 (사유) | 공유 상태에 기록 |
+|------|------|------------------|-------------|
+| research | agent | 검색 → 읽기 → 요약 → 정보 부족이면 재검색 (루프) | requirements |
+| implement | agent | 쓰기 → 테스트 → 수정 → 통과할 때까지 (루프, 위 참조) | code |
+| verify | agent | 독립 검토 + 테스트 실행 (**fresh context, 구현자의 기억을 상속하지 않음**) | review (pass / fail) |
+| merge | 결정적 코드 | 루프 없음, 검사 통과 시 commit | 종료 |
+
+verify 행에 주목하세요: 그것은 그래프에서 가장 잘못 만들기 쉬운 노드입니다. **단일 agent에서 "검토"는 같은 컨텍스트를 사용하므로, 자기 자신이 자기 자신을 검토합니다; graph에서 verify는 반드시 완전히 새로운 컨텍스트를 가져야 합니다** — implement의 사고 과정을 볼 수 없고, 공유 상태의 code만 봅니다. 이것이 "독립 검토"가 그래프에서 진짜로 성립하는 곳입니다: 컨텍스트 격리는 부작용이 아니라 설계입니다.
+
+**3단계: 엣지 연결.** 먼저 결정적 주 간선을 연결하세요: 연구 → 구현 → 검증 → 병합 → 종료.
+
+```mermaid
+flowchart TD
+ A([시작]) --> B[research]
+ B --> C[implement]
+ C --> D[verify]
+ D --> E[merge]
+ E --> F([종료])
+```
+
+**4단계: 라우팅 규칙 작성 (가장 중요한 단계).** 검증 노드는 "병합"에 직접 연결하지 않고, **결정**에 연결하고, 그 결정이 다음에 어디로 갈지를 정합니다. 이 단계가 "테스트 실패 시 어디로 돌아갈까"를 명시화하는 것입니다 — 라우팅 규칙이 반환하는 것은 노드의 이름이고, 그래프가 어디서 와서 어디로 가는지 한눈에 보입니다:
+
+| 현재 노드 | 조건 | 다음 노드 |
+|---------|------|---------|
+| verify | review == pass | merge |
+| verify | review == fail | implement |
+
+```mermaid
+flowchart TD
+ A([시작]) --> B[research]
+ B --> C[implement]
+ C --> D{verify}
+ D -- pass --> E[merge]
+ D -- fail --> C
+ E --> F([종료])
+```
+
+**5단계: checkpoint(체크포인트) 달기.** 이것이 그래프와 일회성 스크립트의 가장 큰 차이 중 하나입니다: **매 단계의 상태가 디스크에 기록되어서**, 프로세스가 죽어도 중단점부터 이어서 돌릴 수 있고 처음부터 다시 할 필요가 없습니다. 이것을 달면 그래프는 즉시 "중단/복구" 능력을 얻습니다 — 그리고 merge 이전에 "사람 승인을 기다리며 멈추는" 노드를 끼워 넣을 수도 있습니다. 이것이 지난 강의의 "수동 승인"이 그래프 위에서 어떻게 생겼는지입니다:
+
+```
+checkpoint = on(graph, every_step) # 매 단계의 상태를 저장
+graph.pause_before("merge") # 병합 전에 멈추고 사람 승인을 기다림
+```
+
+**6단계: 그래프 실행, 그리고 진입점 제공.** 실행할 때마다 thread id를 넘기고, checkpoint는 그것으로 서로 다른 실행 인스턴스를 구분합니다:
+
+```
+run(graph, entry={"requirements": "로그인 페이지 버그 수정"}, thread="session-1")
+```
+
+실행이 끝나면 위의 그래프와 대조해 보세요: 직접 쓴 `graph.md`는 청사진이고, 엔진 안의 그 코드는 청사진이 실행 가능한 프로그램이 된 것입니다. 둘은 일대일로 대응해야 합니다. 만약 대응되지 않으면 — 그래프를 잘못 그렸거나, 코드를 잘못 쓴 것입니다. **바로 이것이 "그래프가 문제를 종이 위에 올려놓는다"는 뜻입니다**: 예전에는 안 맞아도 아무도 몰랐지만, 지금은 한눈에 보입니다. 진짜로 실행 가능한 참조 구현을 원한다면 `code/maker_checker_graph.py`를 보세요 — LangGraph를 썼지만, 읽고 나면 알아볼 것입니다: 그냥 위의 여섯 단계입니다.
+
+## 오픈소스 프로젝트: 출시 후에 생긴 것, 출시 전에 있던 것
+
+먼저 선을 그어 봅시다: **Graph Engineering은 2026년 7월 18일 이후에야 생긴 이름입니다.** 그 전에 오픈소스로 출시된 프레임워크는 "Graph Engineering 출시 후의 프로젝트"가 아닙니다. 개념이 폭발적으로 뜬 뒤 정말로 이 이름으로 직접 나타난 오픈소스 프로젝트는, 2026년 8월 초 기준으로 근거 있는 것이 하나뿐입니다:
+
+**개념 출시 후에 생긴 것**
+
+- [GraphArc](https://github.com/CodeGraphContext/grapharc)(2026-08-02): 스스로 "Graph Engineering의 첫 번째 실시간 구현"이라고 부릅니다. 에이전트 실행을 로그에 묻혀 있던 trace에서 **상호작용 가능한 실시간 오케스트레이션 그래프**로 바꿉니다 — 각 엔진, 각 의존성, 각 결정 지점을 그려서, 실행 전에 전체 그래프를 시각화하고, 당신이 확인한(심지어 휴대폰으로 볼 수도 있는) 뒤에야 통과시킵니다. 저자는 4,000+ 개발자용 그래프 도구를 만든 배경이며, 방향은 "관측 가능, 디버그 가능, 공학화 가능"입니다. 아주 새롭고, 기능은 아직 초기 단계입니다.
+
+**개념 출시 전에 있던 것 (Graph Engineering이라고 부르지 않지만, 당신이 구축할 때 쓸 것은 바로 이것들)**
+
+2026년 7월 이전에, 이 도구들은 이미 1~3년간 존재했습니다: LangGraph(2024년 오픈소스, 월 다운로드 6,500만+, 위 참조 구현은 그것을 사용), CrewAI, Microsoft Agent Framework, LlamaIndex Workflows, Google ADK, OpenAI Agents SDK, Mastra, Claude Agent SDK. **그것들은 "Graph Engineering 출시 후의 프로젝트"가 아닙니다 — 그것들은 바로 "Graph Engineering 출시 전"의 증거입니다.** 노드, 엣지, 공유 상태, 라우팅이라는 것들이 3~5년을 돌린 뒤 7월에야 새 이름을 얻었습니다. 그래프 엔진은 설계 문제를 해결하지 않습니다: 노드, 엣지, checkpoint를 주지만, "어떤 loop이 어떤 loop에게 먹이를 주는지, 누가 목표를 소유하는지, 누가 거부할 수 있는지"를 대신 답해 주지는 않습니다. 이런 질문을 생각하기 전에, 어떤 엔진으로 바꿔도 같은 낡은 설계를 더 예쁘게 그리는 것뿐입니다.
+
+## 찬물 끼얹기: 그래프는 은총알이 아니다
+
+찬물 세 바가지, 가벼운 것부터 무거운 것까지.
+
+**첫째: 가짜 숫자.** Graph Engineering이 폭발적으로 뜬 뒤, "그래프를 쓰면 정확도 +18%, 비용 -85%" 같은 데이터가 돌았습니다. 한국 블로거 goddaehee가 [사실 확인](https://goddaehee.tistory.com/628)(7월 30일)을 한 라운드 돌렸습니다: 이 두 숫자는 실제로 존재하지만, 2026년 3월 화학 배관 도면(P&ID)에 관한 논문에서 나온 것이고, 18%는 이미지 원본과 비교한 것이며 85%는 다른 방식과 비교한 것입니다 — 마케팅 문구가 서로 다른 기준의 두 숫자를 하나의 "전후 비교"로 이어 붙였고, 논문에는 "graph engineering"이라는 단어조차 없습니다. "그래프 엔지니어링이 X% 향상"이라는 데이터를 보면, 먼저 원출처를 확인하세요.
+
+**둘째: 형태는 하중을 견디는 벽이 아니다 (iii.dev).** 위에서 이미 다뤘습니다. loop은 노드가 하나뿐인 그래프입니다; 상태 머신은 수십 년을 돌렸습니다. "loop은 죽었다" 또는 "graph는 죽었다"를 입에 달고 사는 사람은, 대개 loop도 graph도 제대로 읽어본 적이 없습니다. 배워야 할 것은 패턴이지, 명사가 아닙니다.
+
+**셋째: Orchestration Tax(오케스트레이션 세금).** Addy Osmani가 5월의 《The Orchestration Tax》에서 그래프/멀티 에이전트 시대의 가장 냉철한 경제학을 내놨습니다: **agent를 켜는 것은 싸고, loop을 끄는 것은 비싸다.**
+
+agent를 시작하는 것은 버튼 하나, 한 마디입니다. 그러나 agent의 loop을 끄려면 그 결과를 확인하고, 다른 agent들이 건드린 것과 정렬해야 합니다 — **그 사람은 당신이고, 당신은 하나뿐입니다.** Osmani의 원문:
+
+> "당신은 당신의 AI agent들의 GIL입니다. 그것들은 동시에 돌릴 수 있습니다. 하지만 그것들의 작업이 정말로 아키텍처를 이해하고 병합 충돌을 해결하는 것을 요구한다면, 그 작업은 반드시 그 락을 얻어야 합니다. 락은 하나뿐이고, 당신이 그것을 쥐고 있습니다."
+
+이것이 지난 강의에서 말한 "검토 대역폭이 천장이다"가 이번 강의에서 더 날카로워지는 이유입니다: **그래프는 병렬 agent를 늘리지만, 당신의 판단력은 직렬 자원이고 병렬화되지 않습니다.** 노드를 추가하는 것은 결코 병목이 아닌 부분을 최적화하는 것입니다 — 병목은 언제나 그 하나의 직렬 프로세서, 곧 당신입니다.
+
+## 언제 정말로 그래프를 써야 하는가
+
+모든 작업이 그래프를 그릴 가치가 있는 것은 아닙니다. 다섯 가지 판단 기준, 적어도 세 개를 충족해야 손을 댑니다:
+
+1. **작업이 독립적으로 여러 작업 단위로 쪼갤 수 있다** — 쪼갠 부분끼리 서로 의존하지 않아 병렬화할 수 있다
+2. **분기 또는 롤백 경로가 존재한다** — 테스트 실패 시 어디로 돌아갈지, 정보 부족 시 어디로 돌아갈지, 그 경로를 명시적으로 선언할 가치가 있다
+3. **중간 상태를 저장할 가치가 있다** — checkpoint 이후에 멈출 수 있고, 복구할 수 있고, 처음부터 다시 하지 않는다
+4. **결과를 명확히 검수할 수 있다** — 각 노드에 자동으로 검사 가능한 완료 기준이 있다
+5. **협력 이득 > 조정 비용** — 병렬로 절약한 시간이 그래프 자체와 공유 상태가 가져오는 오버헤드보다 크다
+
+**"복잡" ≠ "단계가 많다".** 20단계의 선형 파이프라인은 그래프가 필요 없습니다 — 그것은 workflow이거나 그냥 스크립트입니다. 노드가 5개뿐이지만 서로 롤백, 병렬, 승인이 있는 구조가 그래프가 필요합니다. 판단 기준은 규모가 아니라 **분기와 롤백의 존재**입니다.
+
+## 핵심 개념
+
+- **Graph Engineering**: 여러 agent, loop, 도구, 평가자를 명시적 그래프(노드 + 엣지 + 공유 상태 + 라우팅 규칙)로 조직하는 공학 실천. 다중 작업 단위의 연결, 공유 상태, 선택 경로를 설계 가능하고, 관측 가능하고, 부분적으로 수리 가능하게 만듭니다.
+- **4층 겹침**: prompt → context → loop → graph, 각 층은 서로 다른 것을 제어합니다(지시, 정보, 런타임, 시스템), 다음 층은 이전 층을 대체하지 않고, 단지 이전 층을 자기 노드 안에 담을 뿐입니다.
+- **Graph의 네 부품**: 노드(작업 단위), 엣지(인계 방식), 공유 상태(공용 작업대), 라우팅 규칙(다음으로 어디로 갈지).
+- **단일 루프의 세 가지 구조적 실패**: Goodhart(숫자는 올라가는데 비즈니스는 나빠짐), 위쪽 실명("이 목표가 맞는가"를 절대 묻지 않음), 충돌(독립 루프들이 서로를 깎아내림). 그래프는 이 세 종류의 문제를 명시적 관계 설계로 바꿉니다.
+- **Graph ≠ Workflow**: workflow의 노드는 결정적 함수이고 엣지는 하드코딩된 코드입니다; graph의 노드는 완전한 agent가 될 수 있고 엣지는 동적 라우팅이 될 수 있습니다. graph는 workflow의 일반화입니다.
+- **Anchors(앵커)**: 루프 네트워크를 실제 세계에 고정하는 메커니즘(실제 비즈니스 결과, ground truth, 수동 샘플링). 그래프 설계에서 가장 쉽게 건너뛰지만 가장 생략할 수 없는 단계.
+- **Orchestration Tax(오케스트레이션 세금)**: agent를 시작하는 것은 싸고, 결과를 검토하는 것은 비쌉니다. 당신의 주의는 유일한 직렬 자원이고, 노드를 추가해도 그것은 최적화되지 않습니다.
+
+## 핵심 요점
+
+- **Graph Engineering은 Loop Engineering을 대체하는 것이 아니라, 그 위에 한 층을 쌓습니다.** loop은 그래프의 한 노드입니다; 지난 강의의 세 가지(목표, 검증, 중단 조건)는 노드의 내부 구조가 됩니다.
+- **그래프는 "결정을 미루는 것"을 "결정을 앞당기는 것"으로 바꿉니다.** loop은 실패 모드를 루프 안에 숨기고, graph는 그것을 종이 위에 올려놓습니다 — 읽을 수 있고, 감사할 수 있고, 부분적으로 수리할 수 있습니다.
+- **노드 안에 무엇을 담는지가 그래프와 workflow의 차이를 결정합니다.** 함수를 담으면 workflow이고, agent를 담으면 그래프입니다. 이것이 "새 술을 낡은 부대에 담는 것"에서 유일하게 새 술인 부분입니다.
+- **그래프를 설계하기 전에 네 가지 질문에 답하세요:** 어떤 loop이 어떤 loop에게 먹이를 주는지, 누가 목표를 소유하는지, 누가 거부/롤백할 수 있는지, 어떤 지표는 움직이고 어떤 것은 얼어야 하는지. 답할 수 없으면 그리지 마세요.
+- **그림을 그리려고 그리지 마세요.** 다섯 가지 판단 기준: 독립적으로 쪼갤 수 있고, 분기나 롤백이 있고, 중간 상태를 저장할 가치가 있고, 결과를 검수할 수 있고, 협력 이득 > 조정 비용.
+- **당신의 검토 대역폭은 여전히 천장입니다.** 그래프는 병렬 agent를 늘리지만, 당신의 판단력은 직렬 자원입니다 — 오케스트레이션 세금은 노드가 많아져도 사라지지 않습니다.
+- **반대의 목소리를 기억하세요.** 형태는 하중을 견디는 벽이 아닙니다; 재생 가능, 관측 가능, 복구 가능이 진짜입니다. 명사는 6주마다 바뀌지만, 공학 능력은 바뀌지 않습니다.
+
+## 더 읽을거리
+
+- [Prefect: Loops vs. Graphs (Jul 2026)](https://www.prefect.io/blog/loops-vs-graphs) — 수십 년간 그래프 오케스트레이션을 해온 회사의 관점에서 loop과 graph 보기
+- [Eigent: Graph Engineering for AI Agents (Jul 2026)](https://www.eigent.ai/blog/graph-engineering-ai-agents) — 단일 loop의 세 가지 구조적 실패 + 네 가지 설계 질문 + anchors
+- [iii.dev: Loops, Graphs, and the Layer That Matters (Jul 2026)](https://iii.dev/blog/loops-graphs-and-the-layer-that-matters/) — 가장 냉철한 반대: "형태는 하중을 견디는 벽이 아니다"
+- [Rohit(@rohit4verse) 원본 긴 글 (2026-07-29)](https://x.com/rohit4verse/status/2082478623043547356) — 4층 프레임워크의 1차 출처: prompt → context → loop → graph, 각 층은 이전 층 위에 겹침
+- [Agent Times: Graph Engineering as the Final Layer (Jul 2026)](https://theagenttimes.com/articles/graph-engineering-emerges-as-proposed-final-layer-of-agent-o-4f0511a8) — Rohit 4층 프레임워크의 정리
+- [goddaehee: Graph Engineering 사실 확인 (한국어, 2026-07-30)](https://goddaehee.tistory.com/628) — 가장 완전한 사실 확인: 농담 기원 타임라인, 가짜 숫자 분해, LangGraph 데이터, Hacker News 인기 비교
+- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — 그 농담보다 2주 앞선 진지한 글
+- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — 공식 응답: "새 아이디어가 아니라 기존 방법의 최신 이름"; LangGraph 월 다운로드 6,500만+
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — 뜨거운 용어의 전파 데이터(첫 트윗 57.5만 뷰)
+- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — 일곱 개 주요 오픈소스 프레임워크의 가로 비교: LangGraph, CrewAI, Microsoft Agent Framework, LlamaIndex, Google ADK, OpenAI Agents SDK, Mastra
+- [LangGraph 공식 문서](https://docs.langchain.com/oss/python/langgraph/graph-api) — "Nodes do the work, edges tell what to do next"; 노드와 엣지의 정확한 정의, 그래프 구축의 1차 참조
+- [Anthropic: Building Effective Agents (Dec 2024)](https://www.anthropic.com/engineering/building-effective-agents) — 다섯 가지 패턴, 그리면 그래프; workflow vs agent의 권위 있는 구분
+- [Addy Osmani: The Orchestration Tax (May 2026)](https://addyosmani.com/blog/orchestration-tax/) — 왜 당신의 주의가 유일한 직렬 자원인가
+- [Addy Osmani: Orchestrating Coding Agents(강연)](https://talks.addy.ie/oreilly-codecon-march-2026/) — subagents에서 agent teams, quality gates까지
+- [Addy Osmani: Loop Engineering (Jun 2026)](https://addyosmani.com/blog/loop-engineering/) — 지난 강의의 핵심 참조, 그래프 엔지니어링의 선행 지식
+- 13강: [수동 프롬프팅에서 자율 루프로](./../lecture-13-loop-engineering/index.md) — loop은 그래프의 한 노드, 먼저 노드 내부를 이해한 뒤 그래프를 이해하자
+- 11강: [왜 관찰 가능성은 하네스 내부에 속하는가](./../lecture-11-why-observability-belongs-inside-the-harness/index.md) — 그래프가 복잡할수록 관찰 가능성이 더 중요함; 관찰할 수 없는 그래프는 그저 블랙박스를 더 큰 블랙박스로 조립한 것
+- 9강: [왜 에이전트는 너무 일찍 완료를 선언하는가](./../lecture-09-why-agents-declare-victory-too-early/index.md) — 검증 노드가 왜 구현 노드와 독립이어야 하는지, 그래프에서는 이것이 프롬프트 문제가 아니라 구조 문제임
+
+## 연습문제
+
+1. **P07의 maker-checker loop을 그래프로 그리기:** `graph.md`로 노드, 엣지, 공유 상태, 라우팅 규칙을 명시적으로 써 보세요. 어떤 엣지가 조건 엣지(검증 통과/실패)이고 어떤 것이 롤백 엣지(실패 시 구현으로 돌아감)인지 표시하세요. 그리고 답하세요: 암묵적이었고 원래 agent의 컨텍스트 안에 숨어 있던 엣지가 있나요?
+
+2. **eigent의 네 가지 질문에 답하기:** 현재 돌고 있는 독립 loop 세 개(또는 같은 프로젝트의 자동화 세 개)를 찾아 답하세요: 그들 사이에 누가 누구에게 먹이를 주나요? 어떤 loop이 다른 loop이 쫓는 목표를 소유하나요? 어떤 loop이 다른 loop의 산출물을 거부할 수 있나요? 각각 최적화해서 서로 충돌할 수 있는 지표는 무엇인가요?
+
+3. **Goodhart 자가 점검:** 최근 최적화한 어떤 지표를 점검하세요. 그것이 올랐는데, 실제 결과(비즈니스 결과, 사용자 피드백, 코드 품질)도 함께 좋아졌나요? 숫자만 올랐다면, 이 loop은 어떤 방향으로 당신을 속이고 있나요?
+
+4. **다섯 가지 판단 기준 평가:** 목표를 정한 "그래프화"할지 고민 중인 작업을 하나 고르고, 다섯 가지 기준을 하나씩 점수로 매겨 보세요. 적어도 세 개를 충족해야 그래프를 그릴 가치가 있습니다. 세 개가 안 되면, 그것이 실제로 필요한 것은 더 나은 workflow 스크립트입니다 — 그래프를 쓰려고 그래프를 쓰지 마세요.
+
+5. **graph.md를 실행 가능한 프로그램으로 만들기:** 이 강의 "첫 번째 그래프를 처음부터 구축하기"의 여섯 단계에 따라, 그린 maker-checker 그래프를 실제로 돌아가는 그래프로 구현하세요(참조 구현: `code/maker_checker_graph.py`, LangGraph로 작성). 여섯 단계를 건너뛰지 마세요: 상태 정의 → 노드 나열 → 엣지 연결 → 라우팅 작성 → checkpoint 달기 → 실행. 실행한 뒤 `graph.md`와 코드를 비교하고, 첫 번째로 안 맞는 곳을 찾아 그 이유를 설명하세요 — 그래프를 잘못 그린 건가요, 코드를 잘못 쓴 건가요?
\ No newline at end of file
diff --git a/docs/ko/projects/project-08-graph-engineering-first-graph/index.md b/docs/ko/projects/project-08-graph-engineering-first-graph/index.md
new file mode 100644
index 0000000..e477f79
--- /dev/null
+++ b/docs/ko/projects/project-08-graph-engineering-first-graph/index.md
@@ -0,0 +1,91 @@
+# 프로젝트 08. 내 워크플로우를 그래프로 그리기
+
+> 관련 강의: [L14. 단일 루프에서 그래프 엔지니어링으로](./../../lectures/lecture-14-graph-engineering/index.md)
+
+## 무엇을 할 것인가
+
+이것은 "Loop"에서 "Graph"로 도약하는 프로젝트입니다. 지난 강의에서 maker-checker loop을 만들었습니다 — 구현, 검증, 피드백, 재구현, 모든 결정이 같은 agent의 컨텍스트 창 안에서 일어났습니다. 이번 강의에서 할 일은, **루프 안에 숨어 있던 구조를 명시적으로 그려내는 것**입니다: 노드, 엣지, 공유 상태, 라우팅 규칙을 한 글자 한 글자 명확히 씁니다.
+
+세 가지를 차례로 실험할 것입니다: 먼저 P07의 maker-checker loop을 명시적 그래프로 그리고, 그래프에 병렬 fan-out/fan-in 노드를 추가하고, 마지막으로 조건부 롤백 엣지와 인간 승인 노드를 추가합니다. 끝나면 직접 체감하게 될 것: **그래프는 새 발명이 아니라, 당신의 loop이 어느 정도 복잡해지면 스스로 변하는 모습입니다.**
+
+## 어떤 도구를 사용할 것인가
+
+- Claude Code 또는 Codex
+- Git
+- P07에서 만든 maker-checker loop (또는 반복해서 돌릴 수 있는 아무 agent 워크플로우)
+- 텍스트 편집기 또는 그리기 도구 (그래프를 그리는 것은 예쁘게 하려는 것이 아니라, 구조를 명확히 쓰려는 것입니다; `mermaid` 또는 손으로 쓰는 `graph.md` 모두 가능)
+
+## 구체적 단계
+
+### 준비 작업
+
+1. P07 완료 후의 저장소에서 출발하거나, 지금 돌고 있는 아무 agent 워크플로우를 그대로 사용하세요.
+2. 세 개의 브랜치를 만드세요: `p08-explicit-graph`, `p08-parallel`, `p08-human-in-the-loop`.
+3. 공유 상태 파일로 `state.md`를 준비하세요: 요구사항, 진행 상황, 검증 결과를 모두 여기에 씁니다. 이것이 그래프의 "공용 작업대"입니다.
+
+### 실험 1: Loop을 명시적 그래프로 그리기
+
+`p08-explicit-graph` 브랜치로 전환하세요.
+
+1. **모든 노드 나열**: P07 maker-checker loop의 매 단계를 노드 하나로 쓰세요. 각 노드에 명확히 쓰세요: 책임, 입력, 출력, agent인지 결정적 코드인지.
+2. **모든 엣지 그리기**: 노드 사이의 모든 엣지를 나열하세요. 두 개의 특수 엣지를 중점적으로 표시하세요:
+ - 조건 엣지: 검증 통과/실패, 어느 쪽으로 가는지
+ - 롤백 엣지: 실패 시 어느 노드로 돌아가는지
+3. **공유 상태 쓰기**: 상태에 어떤 필드가 있는지(요구사항, 코드, 테스트 결과, 검토 결론) 명확히 나열하고, 누가 읽고 누가 쓰는지 표시하세요.
+4. **라우팅 규칙 쓰기**: 가장 단순한 if-then 언어로 "다음에 어디로 갈지"를 적으세요. 예:
+ ```
+ if 검증 통과 → 병합 노드
+ if 검증 실패 → 구현 노드
+ if 구현 노드 정보 부족 → 연구 노드
+ ```
+5. **`graph.md`로 작성**: 위 내용을 하나의 문서로 정리하세요. mermaid로 그래프를 그리고, 노드 표와 라우팅 규칙을 함께 넣으세요.
+6. **이 질문에 답하기**: 그리고 나서, 적어도 한 개의 **원래 암묵적이던 엣지**를 찾으세요 — 예전에 agent 컨텍스트 안에 숨어 있어서 당신 자신도 그 존재를 몰랐던 결정 경로.
+
+### 실험 2: 병렬 Fan-out / Fan-in 노드 추가
+
+`p08-parallel` 브랜치로 전환하세요.
+
+1. **병렬화할 수 있는 지점 고르기**: 작업에서 두 개의 독립적인 부분으로 쪼갤 수 있는 곳을 찾으세요. 예:
+ - 구현을 두 개의 독립 모듈로 쪼개어 두 agent가 병렬로 작성
+ - 검증을 두 개의 독립 검토로 쪼개기: 하나는 테스트와 lint 실행, 하나는 코드 리뷰 (다른 지시, 다른 관심사)
+ - 연구를 두 방향으로 쪼개어 두 agent가 각자 한 가지를 조사
+2. **fan-out 규칙 쓰기**: 공유 상태에 "이 작업이 N개의 병렬 서브태스크로 쪼개졌다"를 기록하고, 각 서브태스크는 독립적인 context, 독립적인 노드를 가집니다.
+3. **fan-in 규칙 쓰기**: 모든 서브태스크가 끝난 뒤, 누가 결과를 병합할까요? 병합 기준은 무엇인가요(예: 두 검토가 모두 통과해야 병합, 아니면 하나만 통과해도 됨)?
+4. **worktree로 격리**: 각 병렬 서브태스크를 독립적인 git worktree에서 돌려, 파일 충돌을 물리적으로 방지하세요(13강의 Worktree 원시를 다시 보세요).
+5. **한 번 실행해 기록**: 병렬 전후의 wall-clock 시간, token 소비, 결과 품질을 기록하세요. 병렬이 정말로 더 빨랐나요? 아니면 조정 오버헤드가 절약한 시간을 먹었나요?
+
+### 실험 3: 롤백 엣지와 인간 승인 노드 추가
+
+`p08-human-in-the-loop` 브랜치로 전환하세요.
+
+이것은 세 실험 중 가장 중요합니다. 그래프에 두 종류의 노드를 추가할 것입니다:
+
+1. **조건부 롤백 엣지**: 검증 노드에 "부분 통과" 경로를 추가하세요 — 전부를 구현 노드로 되돌리는 것이 아니라, 구체적 피드백을 담고 **문제가 생긴 그 노드**로 돌아갑니다. 예: 테스트는 전부 통과했지만 코드 리뷰가 요구사항 이해 오류를 발견했다면, 구현 노드가 아니라 연구 노드로 롤백합니다. 이러려면 공유 상태에 "문제가 어느 층에서 생겼는지"를 기록해야 합니다.
+2. **인간 승인 노드(Human-in-the-loop)**: 병합 노드 앞에 인간 노드를 추가하세요. 여기까지 오면 그래프는 **멈추고**, 당신이 `state.md`에 "승인" 또는 "반려"를 쓰기를 기다립니다. 승인 노드는 타임아웃 규칙을 가질 수 있습니다: N시간 후 응답이 없으면 자동 반려 또는 자동 상위로 승격.
+3. **interrupt의 형식 쓰기**: 승인 요청을 어떻게 명확히 쓰는지 — 무슨 일이 일어났는지, 무엇이 바뀌었는지, 왜 사람이 필요한지, 승인/반려의 결과가 각각 무엇인지.
+4. **완전한 흐름을 적어도 2라운드 돌리기**: 매 라운드마다 인간 승인 노드까지 가고, 당신이 직접 한 번 승인하고 한 번 반려하세요. 기록하세요: 당신의 승인 결정과 검증 노드의 판단이 일치했나요? 승인 노드가 검증 노드가 막지 못한 어떤 것을 막았나요?
+
+## 결과를 어떻게 측정할 것인가
+
+| 지표 | 실험 1 (명시적 그래프) | 실험 2 (병렬) | 실험 3 (인간-기계 협력) |
+|------|----------------|--------------|------------------|
+| 구조 가시성 | 암묵적 엣지를 몇 개 찾았나? | 공유 상태가 병렬 서브태스크를 지원할 수 있나? | 롤백 엣지가 문제 층을 정확히 찾을 수 있나? |
+| 실패 위치 파악 | 실패 시 어떤 엣지가 잘못됐는지 바로 지적할 수 있나? | 병렬 서브태스크 실패 시, 어느 것인지 특정할 수 있나? | 승인 반려 시, 어느 층의 문제인지 지적할 수 있나? |
+| 협력 오버헤드 | 그래프를 쓰는 데 얼마나 걸렸나? | 병렬로 절약한 시간 vs 조정 오버헤드 | 승인 대기 시간 vs 막아낸 문제의 가치 |
+| 관측 가능성 | 매 단계에서 무슨 일이 일어나는지 이제 보이나? | 각 병렬 서브태스크의 상태가 보이나? | 승인 요청이 충분히 명확하게 쓰였나? |
+| 신뢰성 | 그래프 설명과 실제 실행이 일치하나? | fan-in 병합 기준이 신뢰할 만하나? | 타임아웃/승격 규칙이 정말로 발동하나? |
+
+## 무엇을 제출할 것인가
+
+- `graph.md`(실험 1의 완전한 그래프 설명: mermaid 그래프 + 노드 표 + 엣지 표 + 공유 상태 필드 + 라우팅 규칙)
+- 실험 1에서 찾은 암묵적 엣지 목록(적어도 하나)
+- 실험 2의 fan-out/fan-in 규칙과 병렬 실행 기록 한 번(시간/비용/품질 비교)
+- 실험 3의 롤백 엣지 규칙, 승인 노드 형식, 2라운드 인간-기계 협력 기록
+- 최종 회고: loop에서 graph로, 당신의 작업 방식이 어떻게 바뀌었나요? 어떤 작업이 그래프를 그릴 가치가 있고, 어떤 것은 아닌가요?
+
+## 관련 강의
+
+- [Lecture 14 — 단일 루프에서 그래프 엔지니어링으로](../../lectures/lecture-14-graph-engineering/index.md)
+- [Lecture 13 — 수동 프롬프팅에서 자율 루프로](../../lectures/lecture-13-loop-engineering/index.md)(당신의 loop은 그래프의 한 노드입니다; 이 프로젝트는 노드의 내부 구조를 펼쳐 보는 것입니다)
+- [Lecture 09 — 왜 에이전트는 너무 일찍 완료를 선언하는가](../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md)(검증 노드가 왜 구현 노드와 독립이어야 하는지, 그래프에서는 구조 문제입니다)
+- [Lecture 11 — 왜 관찰 가능성은 하네스 내부에 속하는가](../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md)(그래프가 복잡할수록, 각 노드가 무엇을 하는지 볼 필요가 커집니다)
\ No newline at end of file
diff --git a/docs/pt-BR/lectures/lecture-14-graph-engineering/index.md b/docs/pt-BR/lectures/lecture-14-graph-engineering/index.md
new file mode 100644
index 0000000..fff7f7f
--- /dev/null
+++ b/docs/pt-BR/lectures/lecture-14-graph-engineering/index.md
@@ -0,0 +1,349 @@
+[English Version →](../../../en/lectures/lecture-14-graph-engineering/)
+
+> Exemplos de código: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-14-graph-engineering/code/)
+> Projeto prático: [Projeto 08. Desenhe Seu Fluxo de Trabalho como um Grafo](./../../projects/project-08-graph-engineering-first-graph/index.md)
+
+# Aula 14. Do Loop Único à Engenharia de Grafos
+
+Seis semanas depois que a aula anterior terminou de abordar a Engenharia de Loops, em 18 de julho de 2026, Peter Steinberger — o autor do OpenClaw que, na aula anterior, disse "pare de dar prompt a agentes de codificação" — publicou um tweet:
+
+> "Ainda estamos falando de loops, ou já mudamos para graphs?"
+
+Um tweet — cerca de 570 mil visualizações em um dia, subindo para cerca de 3 milhões até o fim do mês. Algumas horas depois, o engenheiro de machine learning Hamel Husain publicou um artigo intitulado *Loop Engineering Is Dead. Enter Graph Engineering* — cujo corpo inteiro era um único GIF dizendo "Stop it" — e alcançou cerca de 680 mil visualizações.
+
+O mais interessante é: **os dois estavam fazendo uma piada.** Um estava satirizando uma indústria que inventa um novo termo a cada seis semanas; o outro estava aproveitando a piada. Mas a piada sobreviveu apenas cerca de um fim de semana — cursos, roteiros e stacks de ferramentas inundaram a timeline antes do fim de semana terminar, seguidos por uma pilha de números fabricados: "+18% de precisão, −85% de custo" é dado falso (os 18% e os 85% realmente existem, mas vêm de um artigo sobre diagramas de tubulação química, e comparam contra linhas de base completamente diferentes), e "Microsoft, Stanford e Anthropic descobriram a engenharia de grafos ao mesmo tempo" também é falso. A verificação de fatos confirmou apenas um "pioneiro" real: Josh Simmons, cujo *We Are Entering the Graph Engineering Phase* foi escrito em 4 de julho — duas semanas inteiras antes da piada — **foi a piada que tornou a ideia popular; não foi a piada que criou a ideia.**
+
+> Fonte: [goddaehee: Verificação de fatos de Graph Engineering (2026-07-30)](https://goddaehee.tistory.com/628); [YC Startup School 2026: Entrevista com Jensen Huang (com transcrição)](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia); [explainx: Graph Engineering (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026)
+
+O que esta aula faz não é alimentar ainda mais essa buzzword, mas desmontá-la para ver com clareza: **por que um grafo inevitavelmente cresce a partir de um único loop? O que um grafo e um fluxo de trabalho realmente têm de diferente? Quando você realmente precisa dele, e quando não precisa?**
+
+## prompt, context, loop, graph: quatro nomes, uma camada sobre a outra
+
+No fim de julho, o engenheiro Rohit (@rohit4verse) publicou uma [longa postagem](https://x.com/rohit4verse/status/2082478623043547356) que organizou a história da nomenclatura da engenharia de IA dos últimos anos em uma estrutura clara de quatro camadas. Este é o melhor sistema de coordenadas para entender a Graph Engineering:
+
+| Estágio | Modela o quê | Pergunta que responde | Artefato-chave |
+|------|---------|-----------|---------|
+| **Prompt Engineering** | Instruções | Como dizer ao modelo o que fazer? | instructions, examples, constraints, roles, output formats |
+| **Context Engineering** | Informação | O que o modelo deve saber antes de decidir? | documents, history, memory, tool definitions, environment state |
+| **Loop Engineering** | Runtime | Como fazer o modelo se repetir até atingir o objetivo? | observe, reason, act, inspect, update, condição de parada |
+| **Graph Engineering** | Sistema | Como múltiplos agentes, loops, ferramentas e avaliadores colaboram? | nós, arestas, estado compartilhado, regras de roteamento |
+
+Observe como ler essa linha: **cada camada não substitui a anterior, mas se acumula sobre ela.**
+
+- Você não parou de fazer prompt engineering depois de encontrar a context engineering — cada iteração ainda precisa de um prompt, só que o loop ajuda a atualizá-lo quando o ambiente muda.
+- Depois de construir o loop, você também não abandonou o context — cada rodada do loop precisa remontar o contexto.
+- No grafo, prompt, context e loop não desapareceram: **cada nó carrega seu próprio prompt, seu próprio context, suas próprias ferramentas, sua própria memória e seu próprio loop.** O grafo decide como os nós se conectam.
+
+A postagem original de Rohit termina assim:
+
+> Assim que um agente precisa de especialização, paralelismo, estado compartilhado, verificação e recuperação, ele não é mais um loop. É um grafo.
+
+**Espera, e o harness?** Nesses quatro nomes não há Harness Engineering, mas este curso é sobre harness. A razão é simples: Rohit está falando da história das buzzwords, e o ponto final é o grafo — a camada do meio foi pulada. Além disso, a própria comunidade não conseguiu concordar sobre onde colocar o harness — [explainx](https://explainx.ai/blog/context-prompt-loop-harness-engineering-stack-2026) o coloca acima do loop, e o [artigo Buildrix](https://arxiv.org/abs/2606.25139) o coloca abaixo do loop. Este curso definiu isso na segunda aula: o harness é o alicerce, e o loop e o grafo são construídos em cima dele.
+
+Isso explica um fenômeno estranho: por que o termo "Graph Engineering" só explodiu em julho de 2026, mas todos perceberam que "já faziam isso há muito tempo". Porque o grafo não é uma invenção nova — é o que acontece quando seu loop se torna complexo o suficiente: o loop se transforma automaticamente em um grafo. O nome veio depois; a prática já existia.
+
+## Desmontando o grafo: nós, arestas, estado, roteamento
+
+Reduza o grafo aos seus quatro componentes mais simples.
+
+**Nó (Node)**: a unidade de trabalho que assume algum tipo de responsabilidade. Pode ser:
+- Um pedaço de código determinístico (rodar testes, calcular cobertura)
+- Uma chamada de modelo (gerar documentação)
+- Uma ferramenta (git commit, enviar mensagem)
+- Um agente completo — tem seu próprio loop, entende o objetivo, usa ferramentas e tenta novamente sozinho quando não consegue
+
+O nó é a verdadeira linha divisória entre a engenharia de grafos e a engenharia de fluxos de trabalho — isso será abordado especificamente abaixo.
+
+**Aresta (Edge)**: descreve como os nós fazem a transição entre si. Não é tão simples quanto "fazer A e depois B" — uma aresta pode expressar:
+- **Paralelismo**: quando A termina, B e C começam ao mesmo tempo
+- **Condição**: se o teste passar, vai para a esquerda; se falhar, vai para a direita
+- **Falha/retentativa**: se o nó falhar, volte para ele mesmo e rode novamente
+- **Rollback**: se a verificação não passar, volte para o nó de implementação três saltos atrás
+
+**Estado compartilhado (State)**: o pacote de dados passado entre os nós. Requisitos, notas de pesquisa, versões de código, resultados de testes, conclusões de revisão — tudo escrito na mesma mesa de trabalho pública. Os nós não falam diretamente entre si; todos leem e escrevem o mesmo estado.
+
+**Regras de roteamento (Routing)**: decidem para onde ir em seguida. É o "fluxo de controle" do grafo, dito da forma mais simples:
+
+> Se os testes passarem, entregue; se falharem, volte para o nó de implementação; se faltar informação, volte para o nó de pesquisa.
+
+Juntando as quatro peças, um grafo de desenvolvimento típico fica assim:
+
+```mermaid
+flowchart TD
+ S["Estado compartilhado<br/>Requisitos / Notas / Código / Resultados"] --- R["Nó de pesquisa<br/>Agente: localizar problema"]
+ R -->|"Produzir plano"| I["Nó de implementação<br/>Agente: escrever alterações + testes"]
+ I -->|"Produzir código"| V["Nó de verificação<br/>Agente: revisão independente + rodar testes"]
+ V -->|"Não passou"| I
+ V -->|"Passou"| M["Nó de merge<br/>Código: commit + atualizar estado"]
+ M -->|"Atualização de estado"| S
+ I -->|"Falta informação"| R
+```
+
+Compare com o diagrama de loop da aula anterior: a aula anterior era um anel — descobrir, despachar, verificar, persistir e voltar a descobrir. No grafo desta aula, **o anel ainda existe, mas foi decomposto em nós e arestas explícitos.** O nó de verificação pode devolver diretamente uma falha para o nó de implementação, e o nó de implementação pode voltar para o nó de pesquisa por falta de informação — essas "arestas de rollback" são implícitas em um único loop, onde o próprio agente lembra no contexto que "devo voltar".
+
+## Quando um Loop Não é Suficiente
+
+Um loop tem apenas uma via principal. No maker-checker loop que você construiu na aula anterior, todas as decisões — o que fazer em seguida, para onde a falha vai — acontecem dentro da janela de contexto do mesmo agente. Quando a tarefa fica um pouco mais complexa, quatro problemas surgem:
+
+1. **Divisão de trabalho**: os agentes de pesquisa de requisitos, de escrita de código e de testes — quem começa primeiro?
+2. **Paralelismo**: quais trabalhos podem ser feitos ao mesmo tempo?
+3. **Rollback**: após uma falha de teste, para onde voltar — para o nó de implementação, ou para o nó de pesquisa?
+4. **Handoff**: como vários agentes veem o mesmo conjunto de requisitos, notas e resultados de teste? Se o revisor discordar do implementador, quem decide?
+
+Jensen Huang disse algo semelhante na [entrevista do Startup School 2026](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia) da Y Combinator (conversa com Garry Tan): quanto mais a implementação de baixo nível é automatizada por agentes, o valor central do humano se desloca para "projetar sistemas, definir restrições claras e ter controle refinado sobre os agentes". O exemplo de controle que ele deu é bem concreto — "depois que o agente apresenta um plano, eu mudo uma palavra no arquivo de plano, e essa única palavra produz uma diferença precisa"; ele também previu que a habilidade central do futuro é o "pensamento de sistemas" (systems thinking).
+
+A melhor provocação da discussão veio de Luis Catacora:
+
+> **"Um loop tem muita tolerância a falhas. Um grafo o força a admitir quantas partes do seu fluxo de trabalho nunca foram realmente modeladas."**
+
+Essa frase expõe a diferença profunda entre loop e grafo:
+
+- **Loop é decisão adiada.** Deixe um agente assumir todo o trabalho primeiro e resolva depois, se não der certo — a arquitetura pode ser adiada. Isso economiza esforço, mas o custo é que os modos de falha são invisíveis — você nunca sabe em que etapa ele está travado, porque ele também não sabe.
+- **Grafo é decisão antecipada.** Você precisa declarar toda a estrutura com antecedência: quem é responsável pelo quê, como as tarefas dependem entre si, para onde uma falha deve voltar. Isso dá trabalho, mas em troca você ganha algo legível, auditável e reparável localmente.
+
+Em outras palavras mais diretas: **o loop esconde o problema dentro do loop; o grafo coloca o problema no papel.** O primeiro é bom para explorar; o segundo, para produção.
+
+## Os Três Modos de Falha Estrutural de um Loop Único
+
+Por que um único loop não aguenta em escala? O artigo *Graph Engineering for AI Agents: Beyond Single Feedback Loops* da eigent.ai aponta três modos de falha estrutural — observe que são falhas estruturais, não bugs de um loop específico.
+
+**Primeiro, uma objeção: o loop não pode adicionar checkpoints também?** Pode. A verificação, a condição de parada e até a retentativa em pontos de interrupção da aula anterior cabem no loop. Mas os três modos de falha abaixo são exatamente o que os checkpoints não resolvem — porque os checkpoints de um loop crescem dentro do mesmo agente, e quem faz a verificação e quem causa o problema são o mesmo cérebro, a mesma porção de contexto. Ele bloqueia "entregar sem verificar", mas não pergunta "esse indicador está correto?" nem "esse objetivo deve ser perseguido?" — a resposta está escrita no próprio context dele, e ele não consegue vê-la. O grafo não dá mais checkpoints a você; ele **move** a verificação para fora: de "dentro do agente" para um "nó independente", com um contexto totalmente novo (como foi dito na seção sobre o nó verify). O sentido de "estrutural" está exatamente aqui: não é que o loop não tenha alguma peça — é que a estrutura em que "o julgador e o executado compartilham o mesmo cérebro" é o problema.
+
+### 1. Goodhart: os números subiram, mas o negócio piorou
+
+Leve qualquer métrica única ao extremo e ela para de medir o que você acha que está medindo. Caso clássico: uma equipe de suporte construiu um loop em torno da "taxa de resolução de tickets". Os dados semanais subiram sem parar. Meses depois, os dados de renovação mostraram que o churn dobrou — **o bot aprendeu a fechar tickets**: desviar o assunto, desencorajar o usuário de insistir e marcar problemas não resolvidos como "resolvidos".
+
+O loop fez tudo o que foi pedido a ele. Só que o número se descolou do que o negócio realmente se importa. Isso é a lei de Goodhart.
+
+### 2. Cegueira para cima: ele nunca pergunta "esse objetivo está certo?"
+
+Dentro de um loop, o valor de referência é sagrado. Um termostato não pergunta "68°F é a temperatura certa?". Um loop de vendas não pergunta "essa meta é razoável?". Um loop de eval de agente não pergunta "esse benchmark corresponde aos resultados reais do negócio?".
+
+**Qualquer que seja o objetivo escolhido, o loop corre em direção a ele, mesmo que não seja o que deveria ser perseguido desde o início.** Na estrutura de um único loop, não há lugar algum para essa pergunta.
+
+### 3. Conflito: loops independentes se sabotam
+
+Em sistemas reais há dezenas de loops, cada um construído de forma independente. O loop de velocidade de resposta sabota o loop de qualidade profunda; o loop de crescimento sabota o loop de qualidade. Cada loop está saudável no seu próprio dashboard, mas o sistema como um todo treme — como várias pessoas puxando a mesma corda em direções diferentes.
+
+**A engenharia de grafos responde exatamente o conjunto de perguntas que um único loop não consegue responder:**
+
+- Quais loops alimentam quais loops?
+- Quais loops possuem os objetivos que outros loops perseguem?
+- Quais loops podem vetar ou reverter uma mudança?
+- Quais métricas podem se mover e quais devem ser congeladas?
+
+Quando um sistema contém "loops que podem comer seu objetivo" e "loops que podem vetar sua mudança", a relação entre eles se torna um objeto de engenharia — e as relações e as relações entre relações, quando desenhadas, formam um grafo.
+
+### Âncoras: fixando os loops à realidade
+
+O artigo da eigent tem uma seção no título que diz "everyone skips": **anchors (âncoras)**. Não importa o quão engenhosa seja a rede de loops: se cada loop flutua para longe da realidade, a rede é apenas uma ressonância de flutuações mútuas. As âncoras são o que fixa o loop ao mundo real — resultados reais de negócio, datasets de ground truth, amostragem humana. Ao projetar um grafo, a âncora é a etapa mais fácil de pular, mas a que menos pode ser deixada de fora.
+
+## Grafo e Workflow: não é só uma mudança de nome
+
+Este é o ponto desta aula mais fácil de ser mal-entendido, e vale a pena destacá-lo separadamente.
+
+A primeira reação à explosão da Graph Engineering, para quem já fez engenharia, é murmurar: "isso não é só workflow? DAG, máquinas de estado, motores de fluxo de trabalho — rodamos isso há décadas."
+
+**Essa intuição está certa pela metade.** Grafo e workflow compartilham o mesmo esqueleto: nós + arestas + estado compartilhado + roteamento. A forma como Airflow, Prefect, Dagster e Temporal orquestram há décadas é exatamente esse grafo. Os cinco padrões que o *Building Effective Agents* da Anthropic resumiu em dezembro de 2024 — cadeias de prompt, roteamento, paralelização, orquestrador/trabalhadores e avaliador/otimizador —, quando desenhados, formam exatamente grafos de execução de diferentes formas.
+
+**A metade errada está nos nós.** Os nós de um workflow tradicional são **funções determinísticas**: uma função Python, um script shell, uma tarefa SQL. As arestas são código fixo: `if`, `switch`, `case`. O sistema inteiro é mantido por engenheiros com código, e o comportamento é previsível — a mesma entrada sempre segue o mesmo caminho.
+
+Os nós da engenharia de grafos podem ser um **agente completo**: com seu próprio loop, que usa ferramentas, entende o objetivo e tenta novamente sozinho em caso de falha. As arestas também não precisam ser fixas — podem carregar regras de roteamento, decidindo o próximo passo com base na saída do nó anterior, no resultado da verificação ou até em outro modelo.
+
+Para deixar essa diferença clara, vamos usar um par de conceitos da Anthropic. A Anthropic distingue workflow e agent em uma frase: **quem decide o fluxo de controle?** Se o código decide os passos, é workflow; se o modelo pode mudar os passos em tempo de execução, é agente.
+
+Então o que é um grafo? **O grafo é o contêiner que abriga ambos.** Em um único grafo pode haver ao mesmo tempo:
+
+- Nós de workflow: rodar testes, calcular cobertura — código determinístico, sem precisar de modelo
+- Nós de agente: implementar funcionalidades, revisar código — agentes completos orientados por modelo
+- Nós humanos: aprovação, dupla verificação — nós de interação humana, param aqui e esperam o "sim" de uma pessoa
+
+Então a afirmação correta é: **Graph Engineering não substitui o Workflow, é uma generalização do Workflow** — amplia o tipo de nó de "função" para "agente" e a decisão das arestas de "código estático" para "roteamento dinâmico". O workflow é o caso especial "totalmente determinístico" dentro do grafo.
+
+A visão contrária (o *Loops, Graphs, and the Layer That Matters* da iii.dev) também cai no mesmo ponto, só que com a conclusão oposta:
+
+> "A forma é a parte fácil, e descartável. A decisão que sustenta a carga é do que um loop ou grafo é constituído, e como ele se comporta depois que funciona."
+
+O que a iii.dev quer dizer: não trate a "topologia" como uma conquista de engenharia. A engenharia de workflow rodou por décadas, e o que realmente se consolidou não é como os nós se conectam, mas **reprodutibilidade, observabilidade e recuperabilidade** — se algo der errado, dá para reproduzir; em execução, dá para observar; se cair, dá para continuar. Você pode mudar a forma do grafo como quiser; essas capacidades que sustentam a carga são onde você deve investir. Essa crítica vale a pena guardar: **desenhar não é o objetivo; quanta capacidade de engenharia o grafo consegue sustentar é o objetivo.**
+
+## Você Já Estava Desenhando Grafos
+
+Há ainda mais uma evidência de "velho vinho em garrafa nova": as ferramentas já existiam.
+
+- **LangGraph**: lançado em janeiro de 2024, com cerca de 65 milhões de downloads mensais até julho de 2026. É um motor de execução de grafos para agentes — os nós podem ser agentes, e as arestas podem ter roteamento condicional, checkpoint e interrupt.
+- **Os cinco padrões da Anthropic**: o *Building Effective Agents* de dezembro de 2024 já havia desenhado os grafos de cadeias de prompt, roteamento, paralelização, orquestrador/trabalhadores e avaliador/otimizador, só que não os chamou de Graph Engineering.
+- **Fan-out de sub-agentes do Claude Code**: quando você faz um agente principal despachar vários sub-agentes para trabalhar em paralelo, você já está construindo um grafo, só que não percebeu.
+- **Máquinas de estado, agendamento DAG, filas de tarefas, grafos de conhecimento**: a ciência da computação já tem décadas; a engenharia de grafos não é um problema novo.
+
+O que é realmente novo? **O nó passou de "função" para "agente".** Essa é a única mudança, e é a mudança toda. Antes, para escrever um nó de workflow, você precisava especificar sua lógica, tratamento de erros e estratégia de retentativa. Agora, um nó precisa apenas de uma instrução — "pesquise este problema", "revise este código" — e o resto é feito pelo próprio modelo. Os nós ficaram baratos, então vale a pena desenhar o grafo.
+
+## Construindo Seu Primeiro Grafo do Zero
+
+Teoria basta, vamos à prática. O maker-checker da aula anterior é **um** agente que se repete sozinho. A primeira coisa que a Graph Engineering faz é dividir esse agente monolítico: **cada nó vira um agente especializado, cada um com seu próprio prompt, context, tools, memory e seu próprio loop interno; os nós não compartilham contexto entre si, apenas transitam por um único estado compartilhado.** Essa é a versão em linguagem simples da frase de Rohit — "o grafo decide o que cada nó vê, quando roda, para onde a saída vai, quem pode vetar e o que para o sistema". Nenhuma das notações abaixo está amarrada a um motor específico — são conceitos; LangGraph e CrewAI são apenas implementações que os transformam em programas executáveis, com APIs diferentes, mas o mesmo esqueleto. Seis passos, sem pular nenhum.
+
+**Passo 1: Defina o estado compartilhado (State).** Comece distinguindo duas camadas: **no nível do grafo, só o estado é compartilhado; o contexto de cada nó é privado.** Um agente monolítico tem apenas um context, que com o tempo acaba se afogando na própria transcrição longa; o grafo divide o context em várias partes, cada uma pertencente a um nó — o loop é o bem privado do nó, e o grafo é a mesa pública onde eles transitam. Pense primeiro no que colocar no estado. Declare para cada campo como ele é "mesclado" — quando vários nós paralelos escrevem no mesmo campo ao mesmo tempo, é sobrescrita, append ou soma? Esse passo não é um recurso do framework; é a regra que você escreve no `graph.md` ao desenhar:
+
+```
+state = {
+ "requirements": texto, # escrito pelo nó de pesquisa
+ "code": texto, # escrito pelo nó de implementação
+ "review": "pass" | "fail", # escrito pelo nó de revisão
+ "attempts": número, # +1 a cada falha (mesclar com "soma" em escrita paralela)
+}
+```
+
+**Passo 2: Liste os nós — cada nó é um agente completo (com seu próprio loop).** Essa é a diferença fundamental entre grafo e workflow: os nós do workflow são funções; os nós do grafo são **agentes com seu próprio loop interno**. O nó recebe o estado compartilhado → trabalha com seu contexto privado → escreve o resultado de volta no estado compartilhado. O interior de um nó que escreve código geralmente é justamente o loop da aula anterior:
+
+```
+# interior do nó implement: um pequeno loop privado (o maker-checker loop da aula anterior)
+node_implement(requirements):
+ loop (no máximo 3 vezes):
+ code = model(prompt=instrução de implementação, context=requirements + último erro)
+ if tests_pass(code): return {"code": code}
+ return {"error": "implementação falhou 3 vezes"}
+```
+
+| Nó | Tipo | Interior do nó (privado) | Escreve no estado compartilhado |
+|------|------|------------------|-------------|
+| research | agente | pesquisar → ler → resumir → se faltar informação, pesquisar de novo (loop) | requirements |
+| implement | agente | escrever → testar → corrigir → até passar (loop, veja acima) | code |
+| verify | agente | revisão independente + rodar testes (**fresh context, não herda a memória do implementador**) | review (pass / fail) |
+| merge | código determinístico | sem loop, faz commit quando a verificação passa | fim |
+
+Observe a linha do verify: é o nó mais fácil de fazer errado num grafo. **Num agente monolítico, a "revisão" ainda usa o mesmo context, revisando a si mesmo; no grafo, o verify deve ter um contexto totalmente novo** — ele não vê o processo de raciocínio do implement, só o code no estado compartilhado. É aqui que a "revisão independente" realmente se sustenta no grafo: o isolamento de contexto não é um efeito colateral, é um design.
+
+**Passo 3: Conecte as arestas.** Primeiro conecte a espinha dorsal determinística: pesquisa → implementação → verificação → merge → fim.
+
+```mermaid
+flowchart TD
+ A([Início]) --> B[research]
+ B --> C[implement]
+ C --> D[verify]
+ D --> E[merge]
+ E --> F([Fim])
+```
+
+**Passo 4: Escreva as regras de roteamento (o passo mais crítico).** O nó de verificação não se conecta diretamente ao "merge"; ele se conecta a uma **decisão**, que decide para onde ir em seguida. Este passo torna explícito "para onde uma falha de teste deve voltar" — a regra de roteamento retorna o nome do nó, e de onde o grafo vem e para onde vai fica visível de uma olhada:
+
+| Nó atual | Condição | Próximo nó |
+|---------|------|---------|
+| verify | review == pass | merge |
+| verify | review == fail | implement |
+
+```mermaid
+flowchart TD
+ A([Início]) --> B[research]
+ B --> C[implement]
+ C --> D{verify}
+ D -- pass --> E[merge]
+ D -- fail --> C
+ E --> F([Fim])
+```
+
+**Passo 5: Adicione checkpoints.** Essa é uma das maiores diferenças entre um grafo e um script descartável: **o estado de cada passo é persistido em disco**, e se o processo cair, dá para continuar do ponto de interrupção, sem recomeçar do zero. Depois de adicioná-los, seu grafo ganha imediatamente a capacidade de "interromper/retomar" — e você ainda pode inserir um nó de "pausar para aprovação humana" antes do merge; é assim que a "aprovação humana" da aula anterior se parece num grafo:
+
+```
+checkpoint = on(graph, every_step) # o estado de cada passo é salvo
+graph.pause_before("merge") # para antes do merge, esperando aprovação
+```
+
+**Passo 6: Rode o grafo e dê a ele um ponto de entrada.** A cada execução, passe um id de thread, que o checkpoint usa para distinguir diferentes instâncias de execução:
+
+```
+run(graph, entry={"requirements": "corrigir bug da página de login"}, thread="session-1")
+```
+
+Depois de rodar, compare com o grafo acima: o `graph.md` que você escreveu à mão é a planta; o código no motor é a planta transformada em programa executável. Os dois devem corresponder um a um. Se não batem — ou o grafo foi desenhado errado, ou o código foi escrito errado — **é exatamente o que significa "o grafo coloca o problema no papel"**: antes, quando não batia, ninguém sabia; agora, dá para ver de uma olhada. Para uma referência real e executável, veja `code/maker_checker_graph.py` — usa LangGraph, mas depois de ler você deve reconhecer: são exatamente os seis passos acima.
+
+## Projetos de Código Aberto: Depois vs. Antes do Lançamento do Conceito
+
+Primeiro, deixe claro o limite: **Graph Engineering é um nome que só existe depois de 18 de julho de 2026.** Os frameworks open source anteriores a essa data não são "projetos pós-lançamento da Graph Engineering". Um projeto de código aberto que realmente apareceu com esse nome depois que o conceito explodiu, até o início de agosto de 2026, só existe um que se sustenta:
+
+**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.
+
+**Antes do lançamento do conceito (não se chamam Graph Engineering, mas são o que você vai usar na prática)**
+
+Antes de julho de 2026, essas ferramentas já existiam há um a três anos: LangGraph (open source desde 2024, 65 milhões+ de downloads mensais, é o que a referência acima usa), CrewAI, Microsoft Agent Framework, LlamaIndex Workflows, Google ADK, OpenAI Agents SDK, Mastra e Claude Agent SDK. **Elas não são "projetos pós-lançamento da Graph Engineering" — elas são exatamente a evidência "pré-lançamento da Graph Engineering".** O conjunto de nós, arestas, estado compartilhado e roteamento roda há três ou cinco anos; só em julho ganhou um nome novo. O motor de grafo não resolve problemas de design: ele dá a você nós, arestas e checkpoint, mas não responde por você "quais loops alimentam quais loops, quem possui o objetivo, quem pode vetar". Antes de pensar nessas perguntas, trocar de motor é apenas desenhar o mesmo design ruim de forma mais bonita.
+
+## Um Balde de Água Fria: o Grafo Não é uma Bala de Prata
+
+Três baldes de água fria, do mais leve ao mais pesado.
+
+**Primeiro balde: números falsos.** Depois da explosão da Graph Engineering, circulou na internet dados como "com grafos, precisão +18%, custo −85%". O blogueiro coreano goddaehee fez uma [verificação de fatos](https://goddaehee.tistory.com/628) (30 de julho): os dois números realmente existem, mas vêm de um artigo de março de 2026 sobre diagramas de tubulação química (P&ID), e os 18% comparam com o rascunho original da imagem e os 85% com outra abordagem — o texto de marketing costurou dois números de linhas de base diferentes em um "antes e depois", e o artigo nem sequer contém o termo "graph engineering". Ao ver qualquer dado de "a engenharia de grafos traz X% de melhoria", verifique primeiro a fonte original.
+
+**Segundo balde: a forma não é uma parede estrutural (iii.dev).** Já foi dito acima. Um loop é simplesmente um grafo com um único nó; as máquinas de estado rodam há décadas. Quem fala o tempo todo "loop morreu" ou "grafo morreu" geralmente não leu com atenção nem o loop nem o grafo. O que se deve aprender são os padrões, não os nomes.
+
+**Terceiro balde: o Imposto de Orquestração (Orchestration Tax).** No *The Orchestration Tax* de maio, Addy Osmani deu a lição mais dura de economia da era de grafos/multi-agente: **ligar um agente é barato; desligar um loop é caro.**
+
+Iniciar um agente é só apertar um botão, dizer uma frase. Mas desligar o loop de um agente exige que alguém verifique seus resultados e alinhe com o que outros agentes mexeram — **essa pessoa é você, e só existe um você.** As palavras de Osmani:
+
+> "Você é o GIL dos seus agentes de IA. Eles podem rodar ao mesmo tempo. Mas, sempre que o trabalho deles exigir entender de verdade a arquitetura ou resolver conflitos de merge, esse trabalho precisa adquirir esse lock. Há apenas um lock, e está na sua mão."
+
+É por isso que o "a banda de revisão é o teto" da aula anterior se torna ainda mais agudo nesta aula: **o grafo aumenta o número de agentes paralelos, mas seu julgamento é um recurso serial, não paralelo.** Adicionar nós otimiza a parte que nunca é o gargalo — o gargalo é sempre aquele único processador serial: você.
+
+## Quando Você Realmente Deve Usar um Grafo
+
+Nem toda tarefa merece um grafo. Cinco critérios; satisfaça pelo menos três antes de começar:
+
+1. **A tarefa pode ser dividida em múltiplas unidades de trabalho independentes** — as partes divididas não dependem umas das outras e podem rodar em paralelo
+2. **Existem caminhos de ramificação ou rollback** — para onde a falha de teste deve voltar, para onde a falta de informação deve voltar; esses caminhos merecem ser declarados explicitamente
+3. **O estado intermediário vale a pena ser salvo** — depois do checkpoint dá para parar e retomar, em vez de recomeçar do zero
+4. **O resultado pode ser aceito de forma explícita** — cada nó tem um critério de conclusão verificável automaticamente
+5. **O benefício da colaboração > o custo da coordenação** — o tempo economizado em paralelismo é maior que a sobrecarga do próprio grafo e do estado compartilhado
+
+"Complexo" não é igual a "muitos passos". Um pipeline linear de 20 passos não precisa de grafo — é um workflow, ou apenas um script. Uma estrutura com só 5 nós, mas com rollback, paralelismo e aprovação entre eles, é que precisa de grafo. O critério de julgamento não é o tamanho — é **a existência de ramificações e rollbacks**.
+
+## Conceitos Fundamentais
+
+- **Graph Engineering**: a prática de engenharia de organizar múltiplos agentes, loops, ferramentas e avaliadores em um grafo explícito (nós + arestas + estado compartilhado + regras de roteamento). Torna a conexão entre unidades de trabalho, o estado compartilhado e os caminhos escolhidos projetáveis, observáveis e reparáveis localmente.
+- **Quatro camadas empilhadas**: prompt → context → loop → graph, cada camada controla uma coisa diferente (instruções, informação, runtime, sistema); a camada posterior não substitui a anterior, apenas coloca a anterior dentro dos seus próprios nós.
+- **As quatro peças do grafo**: nós (unidades de trabalho), arestas (forma de transição), estado compartilhado (mesa de trabalho pública) e regras de roteamento (para onde ir em seguida).
+- **Três modos de falha estrutural de um loop único**: Goodhart (os números sobem, mas o negócio piora), cegueira para cima (nunca pergunta "esse objetivo está certo?") e conflito (loops independentes se sabotam). O grafo transforma esses três tipos de problema em design de relações explícito.
+- **Graph ≠ Workflow**: os nós do workflow são funções determinísticas e as arestas são código fixo; os nós do grafo podem ser agentes completos e as arestas podem ter roteamento dinâmico. O grafo é uma generalização do workflow.
+- **Anchors (âncoras)**: o mecanismo que fixa a rede de loops ao mundo real (resultados reais de negócio, ground truth, amostragem humana). A etapa mais fácil de pular no design de grafos, mas a que menos pode ser deixada de fora.
+- **Orchestration Tax (Imposto de Orquestração)**: iniciar um agente é barato; revisar os resultados é caro. Sua atenção é o único recurso serial, e adicionar nós não a otimiza.
+
+## Principais Conclusões
+
+- **Graph Engineering não substitui a Loop Engineering; ela constrói uma camada acima.** O loop é um nó dentro do grafo; as três coisas da aula anterior (objetivo, verificação, condição de parada) se tornam a estrutura interna do nó.
+- **O grafo transforma "decisão adiada" em "decisão antecipada".** O loop esconde os modos de falha dentro do loop; o grafo os coloca no papel — legível, auditável e reparável localmente.
+- **O que você coloca dentro do nó determina a diferença entre grafo e workflow.** Colocar funções é workflow; colocar agentes é grafo. Esse também é o único "vinho novo" dentro do "vinho velho em garrafa nova".
+- **Ao desenhar o grafo, responda primeiro quatro perguntas:** quais loops alimentam quais loops, quem possui o objetivo, quem pode vetar/reverter, quais métricas podem se mover e quais congelar. Se não conseguir responder, não desenhe.
+- **Não desenhe por desenhar.** Cinco critérios: pode ser dividido de forma independente, tem ramificação ou rollback, o estado intermediário vale ser salvo, o resultado é aceitável e o benefício da colaboração > o custo da coordenação.
+- **Sua banda de revisão continua sendo o teto.** O grafo aumenta o número de agentes paralelos, mas seu julgamento é um recurso serial — o imposto de orquestração não desaparece porque há mais nós.
+- **Lembre-se da voz contrária.** A forma não é uma parede estrutural; reprodutibilidade, observabilidade e recuperabilidade é que são. Os nomes mudam a cada seis semanas; a capacidade de engenharia não muda.
+
+## Leitura Adicional
+
+- [Prefect: Loops vs. Graphs (Jul 2026)](https://www.prefect.io/blog/loops-vs-graphs) — loop e grafo sob a perspectiva de uma empresa que faz orquestração de grafos há décadas
+- [Eigent: Graph Engineering for AI Agents (Jul 2026)](https://www.eigent.ai/blog/graph-engineering-ai-agents) — os três modos de falha estrutural de um loop único + quatro perguntas de design + anchors
+- [iii.dev: Loops, Graphs, and the Layer That Matters (Jul 2026)](https://iii.dev/blog/loops-graphs-and-the-layer-that-matters/) — a voz contrária mais lúcida: "a forma não é uma parede estrutural"
+- [Rohit (@rohit4verse) postagem original longa (2026-07-29)](https://x.com/rohit4verse/status/2082478623043547356) — a fonte primária da estrutura de quatro camadas: prompt → context → loop → graph, cada camada empilhada sobre a anterior
+- [Agent Times: Graph Engineering as the Final Layer (Jul 2026)](https://theagenttimes.com/articles/graph-engineering-emerges-as-proposed-final-layer-of-agent-o-4f0511a8) — a organização da estrutura de quatro camadas de Rohit
+- [goddaehee: Verificação de fatos de Graph Engineering (coreano, 2026-07-30)](https://goddaehee.tistory.com/628) — a verificação de fatos mais completa: a linha do tempo da origem da piada, a análise dos números falsos, os dados do LangGraph e a comparação de popularidade no Hacker News
+- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — o artigo sério duas semanas antes da piada
+- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — a resposta oficial: "não é uma ideia nova, é o nome mais recente de um método existente"; mais de 65 milhões de downloads mensais do LangGraph
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — os dados de propagação da buzzword (o tweet original com 575 mil visualizações)
+- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — a comparação horizontal dos sete frameworks open source mais populares: LangGraph, CrewAI, Microsoft Agent Framework, LlamaIndex, Google ADK, OpenAI Agents SDK, Mastra
+- [Documentação oficial do LangGraph](https://docs.langchain.com/oss/python/langgraph/graph-api) — "Nodes do the work, edges tell what to do next"; a definição precisa de nós e arestas, a referência de primeira mão para construir grafos
+- [Anthropic: Building Effective Agents (Dec 2024)](https://www.anthropic.com/engineering/building-effective-agents) — os cinco padrões, que, desenhados, formam um grafo; a distinção autoritativa entre workflow e agent
+- [Addy Osmani: The Orchestration Tax (May 2026)](https://addyosmani.com/blog/orchestration-tax/) — por que sua atenção é o único recurso serial
+- [Addy Osmani: Orchestrating Coding Agents (palestra)](https://talks.addy.ie/oreilly-codecon-march-2026/) — de sub-agents a agent teams a quality gates
+- [Addy Osmani: Loop Engineering (Jun 2026)](https://addyosmani.com/blog/loop-engineering/) — a referência central da aula anterior, o conhecimento prévio da engenharia de grafos
+- Aula 13: [Do Prompting Manual aos Loops Autônomos](./../lecture-13-loop-engineering/index.md) — o loop é um nó dentro do grafo; antes de entender o grafo, entenda o interior do nó
+- Aula 11: [Por Que a Observabilidade Pertence ao Harness](./../lecture-11-why-observability-belongs-inside-the-harness/index.md) — quanto mais complexo o grafo, mais importante a observabilidade; um grafo inobservável é apenas empilhar caixas-pretas em uma caixa-preta ainda maior
+- Aula 9: [Por Que os Agentes Declaram Vitória Cedo Demais](./../lecture-09-why-agents-declare-victory-too-early/index.md) — por que o nó de verificação deve ser independente do nó de implementação; no grafo, isso é um problema estrutural, não um problema de prompt
+
+## Exercícios
+
+1. **Desenhe o maker-checker loop do P07 como um grafo:** escreva explicitamente no `graph.md` os nós, as arestas, o estado compartilhado e as regras de roteamento. Marque qual aresta é condicional (verificação passa/falha) e qual é de rollback (falha volta para a implementação). Depois de desenhar, responda: existe alguma aresta implícita que antes estava escondida no contexto do agente?
+
+2. **Responda as quatro perguntas da eigent:** encontre três loops independentes que você roda (ou três automações no mesmo projeto) e responda: quem alimenta quem entre eles? Qual loop possui o objetivo que outro loop persegue? Existe algum loop que pode vetar a produção de outro loop? Quais métricas estão sendo otimizadas separadamente, mas podem entrar em conflito?
+
+3. **Autocheck de Goodhart:** examine uma métrica que você otimizou recentemente. Ela subiu — mas os resultados reais (resultados de negócio, feedback de usuários, qualidade do código) melhoraram junto? Se apenas o número subiu, em que direção esse loop está te enganando?
+
+4. **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
diff --git a/docs/pt-BR/projects/project-08-graph-engineering-first-graph/index.md b/docs/pt-BR/projects/project-08-graph-engineering-first-graph/index.md
new file mode 100644
index 0000000..fb5f1e9
--- /dev/null
+++ b/docs/pt-BR/projects/project-08-graph-engineering-first-graph/index.md
@@ -0,0 +1,91 @@
+# Projeto 08. Desenhe Seu Fluxo de Trabalho como um Grafo
+
+> Aula relacionada: [L14. Do Loop Único à Engenharia de Grafos](./../../lectures/lecture-14-graph-engineering/index.md)
+
+## O Que Você Vai Fazer
+
+Este é o projeto de transição de "Loop" para "Graph". Na aula anterior você montou um maker-checker loop — implementar, verificar, feedback, implementar de novo — e todas as decisões acontecem dentro da janela de contexto do mesmo agente. O que você vai fazer nesta aula é **desenhar explicitamente a estrutura escondida dentro do loop**: nós, arestas, estado compartilhado e regras de roteamento, escritos com clareza, palavra por palavra.
+
+Você fará três experimentos progressivos: primeiro, desenhar o maker-checker loop do P07 como um grafo explícito; depois, adicionar um nó paralelo de fan-out/fan-in; e, por fim, adicionar uma aresta de rollback condicional e um nó de aprovação humana. Ao terminar, você vai sentir na prática uma coisa: **o grafo não é uma invenção nova — é o que o seu loop vira sozinho quando fica complexo o suficiente.**
+
+## Quais Ferramentas Usar
+
+- Claude Code ou Codex
+- Git
+- O maker-checker loop que você montou no P07 (ou qualquer fluxo de trabalho de agente que você consiga rodar repetidamente)
+- Um editor de texto ou ferramenta de desenho (desenhar não é para ficar bonito, é para escrever a estrutura com clareza; `mermaid` ou `graph.md` escrito à mão servem)
+
+## Passos Concretos
+
+### Preparação
+
+1. Comece do repositório que você terminou no P07, ou use diretamente qualquer fluxo de trabalho de agente que esteja rodando.
+2. Crie três branches: `p08-explicit-graph`, `p08-parallel` e `p08-human-in-the-loop`.
+3. Prepare um `state.md` como arquivo de estado compartilhado: requisitos, progresso e resultados de verificação são escritos aqui. Essa é a "mesa de trabalho pública" do grafo.
+
+### Experimento 1: Desenhe o Loop como um Grafo Explícito
+
+Mude para a branch `p08-explicit-graph`.
+
+1. **Liste todos os nós**: escreva cada passo do maker-checker loop do P07 como um nó. Para cada nó, escreva com clareza: sua responsabilidade, sua entrada, sua saída e se é um agente ou código determinístico.
+2. **Desenhe todas as arestas**: liste cada aresta entre os nós. Destaque duas arestas especiais:
+ - Aresta condicional: verificação passa/falha, para onde vai
+ - Aresta de rollback: para qual nó a falha volta
+3. **Escreva o estado compartilhado**: liste explicitamente quais campos há no estado (requisitos, código, resultados de teste, conclusões de revisão) e quem lê e quem escreve cada um.
+4. **Escreva as regras de roteamento**: usando a linguagem if-then mais simples, escreva as regras de "para onde ir em seguida", por exemplo:
+ ```
+ if a verificação passa → nó de merge
+ if a verificação falha → nó de implementação
+ if o nó de implementação tem informação insuficiente → nó de pesquisa
+ ```
+5. **Escreva em `graph.md`**: organize o conteúdo acima em um documento. Use mermaid para desenhar um grafo, anexando a tabela de nós e as regras de roteamento.
+6. **Responda a esta pergunta**: depois de desenhar, encontre pelo menos uma **aresta que era implícita** — um caminho de decisão que antes estava escondido no contexto do agente e cuja existência você nem conhecia.
+
+### Experimento 2: Adicione um Nó de Fan-out / Fan-in Paralelo
+
+Mude para a branch `p08-parallel`.
+
+1. **Escolha um ponto que possa ser paralelizado**: encontre um lugar na tarefa que possa ser dividido em duas partes independentes. Por exemplo:
+ - Implementação dividida em dois módulos independentes, dois agentes escrevendo em paralelo
+ - Verificação dividida em duas revisões independentes: uma roda testes e lint, outra faz revisão de código (instruções diferentes, focos diferentes)
+ - Pesquisa dividida em duas direções, cada agente investigando um caminho
+2. **Escreva as regras de fan-out**: registre no estado compartilhado que "esta tarefa foi dividida em N subtarefas paralelas", cada uma com um context independente e um nó independente.
+3. **Escreva as regras de fan-in**: quando todas as subtarefas terminarem, quem mescla os resultados? Qual é o critério de mesclagem (por exemplo: só mesclamos se as duas revisões passarem, ou basta uma passar)?
+4. **Use worktree para isolar**: cada subtarefa paralela roda em um git worktree independente, evitando fisicamente colisões de arquivos (reveja a primitiva Worktree da aula 13).
+5. **Rode uma vez e registre**: registre o tempo de wall-clock, o consumo de tokens e a qualidade dos resultados antes e depois do paralelismo. O paralelismo realmente foi mais rápido? Ou o custo de coordenação comeu o tempo economizado?
+
+### Experimento 3: Adicione uma Aresta de Rollback e um Nó de Aprovação Humana
+
+Mude para a branch `p08-human-in-the-loop`.
+
+Este é o mais importante dos três experimentos. Você vai adicionar dois tipos de nó ao grafo:
+
+1. **Aresta de rollback condicional**: adicione ao nó de verificação um caminho de "aprovação parcial" — em vez de devolver tudo para o nó de implementação, volte com feedback específico para o **nó que causou o problema**. Por exemplo: se todos os testes passam, mas a revisão de código descobriu que a compreensão dos requisitos estava errada, volte para o nó de pesquisa, não para o de implementação. Isso exige que seu estado compartilhado registre "em qual camada está o problema".
+2. **Nó de aprovação humana (Human-in-the-loop)**: adicione um nó humano antes do nó de merge. Ao chegar aqui, o grafo **para**, e espera você escrever "aprovar" ou "rejeitar" no `state.md`. O nó de aprovação pode ter uma regra de timeout: se não houver resposta em N horas, rejeita ou promove automaticamente.
+3. **Escreva o formato do interrupt**: como escrever com clareza a solicitação de aprovação — o que aconteceu, o que foi alterado, por que é necessária uma pessoa e quais são as consequências de aprovar/rejeitar.
+4. **Rode pelo menos 2 ciclos completos**: em cada ciclo, chegue ao nó de aprovação humana e você mesmo aprova ou rejeita uma vez. Registre: sua decisão de aprovação foi consistente com o julgamento do nó de verificação? O nó de aprovação bloqueou algo que o nó de verificação não bloqueou?
+
+## Como Medir os Resultados
+
+| Métrica | Experimento 1 (grafo explícito) | Experimento 2 (paralelo) | Experimento 3 (humano no loop) |
+|------|----------------|--------------|------------------|
+| Visibilidade da estrutura | Quantas arestas implícitas você encontrou? | O estado compartilhado consegue suportar as subtarefas paralelas? | A aresta de rollback consegue localizar com precisão a camada do problema? |
+| Localização de falhas | Quando algo falha, você consegue apontar diretamente qual aresta errou? | Quando uma subtarefa paralela falha, você consegue localizar qual delas? | Quando a aprovação rejeita, você consegue apontar de qual camada é o problema? |
+| Custo de colaboração | Quanto tempo demorou para escrever o grafo? | Tempo economizado pelo paralelismo vs. custo de coordenação | Tempo de espera da aprovação vs. valor do problema bloqueado |
+| Observabilidade | O que acontece em cada passo, agora fica visível? | O status de cada subtarefa paralela fica visível? | A solicitação de aprovação está escrita com clareza o suficiente? |
+| Confiabilidade | A descrição do grafo condiz com a execução real? | O critério de mesclagem do fan-in é confiável? | As regras de timeout/promoção realmente disparam? |
+
+## O Que Entregar
+
+- `graph.md` (a descrição completa do grafo do experimento 1: diagrama mermaid + tabela de nós + tabela de arestas + campos do estado compartilhado + regras de roteamento)
+- A lista de arestas implícitas encontradas no experimento 1 (pelo menos uma)
+- As regras de fan-out/fan-in do experimento 2 e o registro de uma execução paralela (comparação de tempo/custo/qualidade)
+- As regras de aresta de rollback do experimento 3, o formato do nó de aprovação e o registro de 2 ciclos de colaboração humano-agente
+- O balanço final: do loop ao grafo, o que mudou na sua forma de trabalhar? Quais tarefas valem a pena desenhar como grafo e quais não?
+
+## Aulas Relacionadas
+
+- [Lecture 14 — Do Loop Único à Engenharia de Grafos](../../lectures/lecture-14-graph-engineering/index.md)
+- [Lecture 13 — Do Prompting Manual aos Loops Autônomos](../../lectures/lecture-13-loop-engineering/index.md) (seu loop é um nó dentro do grafo; este projeto é para abrir a estrutura interna do nó)
+- [Lecture 09 — Por Que os Agentes Declaram Vitória Cedo Demais](../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md) (por que o nó de verificação deve ser independente do nó de implementação; no grafo, é um problema estrutural)
+- [Lecture 11 — Por Que a Observabilidade Pertence ao Harness](../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) (quanto mais complexo o grafo, mais você precisa ver o que cada nó está fazendo)
\ No newline at end of file
diff --git a/docs/ru/lectures/lecture-14-graph-engineering/index.md b/docs/ru/lectures/lecture-14-graph-engineering/index.md
new file mode 100644
index 0000000..120703e
--- /dev/null
+++ b/docs/ru/lectures/lecture-14-graph-engineering/index.md
@@ -0,0 +1,349 @@
+[English Version →](../../../en/lectures/lecture-14-graph-engineering/)
+
+> Примеры кода: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-14-graph-engineering/code/)
+> Практический проект: [Project 08. Нарисуйте ваш workflow как граф](./../../projects/project-08-graph-engineering-first-graph/index.md)
+
+# Лекция 14. От одиночных циклов к графовой инженерии
+
+Шесть недель спустя после того, как Loop Engineering вышел в мейнстрим, 18 июля 2026 года Питер Стайнбергер — автор OpenClaw, который в прошлой лекции говорил «перестаньте писать промпты для coding-агентов» — опубликовал твит:
+
+> «Мы всё ещё говорим о циклах, или уже перешли к графам?»
+
+Один твит — около 570 тысяч просмотров за день, к концу месяца выросло до примерно 3 миллионов. Через несколько часов ML-инженер Хамел Хусейн опубликовал статью под названием *Loop Engineering Is Dead. Enter Graph Engineering* — весь текст которой был одной GIF-картинкой «Stop it» — и набрал ещё около 680 тысяч просмотров.
+
+Ещё интереснее: **оба они шутили.** Один высмеивал индустрию, которая каждые шесть недель придумывает новый термин, другой подыгрывал этому мему. Но шутка прожила примерно один уикенд — курсы, роадмапы и технологические стеки заполонили таймлайн ещё до его конца, а за ними потянулся и ворох выдуманных цифр: «+18% точности, −85% стоимости» — это фейк (18% и 85% действительно существуют, но взяты из статьи о химических трубопроводных схемах и сравниваются с совершенно другими базовыми линиями), так же как и «Microsoft, Stanford и Anthropic одновременно обнаружили графовую инженерию». Факт-чекинг подтверждает единственного настоящего «первопроходца» — Джоша Симмонса: его *We Are Entering the Graph Engineering Phase* датирован 4 июля, на две полные недели раньше этой шутки. **Шутка сделала идею модной. Но она не создала идею.**
+
+> Источник: [goddaehee: Факт-чекинг Graph Engineering (2026-07-30)](https://goddaehee.tistory.com/628); [YC Startup School 2026: интервью Дженсена Хуана (с транскриптом)](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia); [explainx: Graph Engineering (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026)
+
+Задача этой лекции — не подлить масла в огонь этого хайпа, а разобрать термин по деталям и увидеть его ясно: **почему после одиночного цикла неизбежно вырастает граф? Чем граф на самом деле отличается от workflow? Когда он действительно нужен, а когда — нет?**
+
+## Prompt, Context, Loop, Graph: четыре имени, один слой поверх другого
+
+В конце июля инженер Рохит (@rohit4verse) опубликовал [длинный пост](https://x.com/rohit4verse/status/2082478623043547356), в котором организовал историю нейминга AI-инженерии за последние годы в чёткую четырёхуровневую структуру. Это лучшая система координат для понимания Graph Engineering:
+
+| Этап | Что формирует | На какой вопрос отвечает | Ключевой продукт |
+|------|---------|-----------|---------|
+| **Prompt Engineering** | Инструкции | Как сказать модели, что делать? | instructions, examples, constraints, roles, output formats |
+| **Context Engineering** | Информация | Что модель должна знать перед принятием решения? | documents, history, memory, tool definitions, environment state |
+| **Loop Engineering** | Среда выполнения | Как заставить модель циклически повторять, пока цель не достигнута? | observe, reason, act, inspect, update, условие остановки |
+| **Graph Engineering** | Система | Как сотрудничают несколько агентов, циклов, инструментов и оценщиков? | узлы, рёбра, общее состояние, правила маршрутизации |
+
+Обратите внимание, как читается эта линия: **каждый уровень не заменяет предыдущий, а ложится поверх него.**
+
+- Обнаружив context engineering, вы не перестали заниматься prompt engineering — на каждой итерации по-прежнему нужен промпт, просто loop обновляет его при изменении окружения.
+- Построив loop, вы не отказались от context — каждый раунд loop заново собирает контекст.
+- В графе не исчезли ни prompt, ни context, ни loop: **каждый узел несёт свой промпт, свой контекст, свои инструменты, свою память и свой маленький цикл.** Граф решает, как узлы соединяются друг с другом.
+
+Рохит завершает свою мысль так:
+
+> Как только агенту требуются специализация, параллелизм, общее состояние, верификация и восстановление — это больше не loop. Это граф.
+
+**Стоп, а где же harness?** Среди этих четырёх имён нет Harness Engineering, хотя этот курс как раз про harness. Причина проста: Рохит рассказывает историю хайповых терминов, конечная точка — graph, и средний слой в ней просто пропущен. А к тому же само комьюнити не определилось, куда поместить harness — [explainx](https://explainx.ai/blog/context-prompt-loop-harness-engineering-stack-2026) ставит его выше loop, [статья Buildrix](https://arxiv.org/abs/2606.25139) — ниже loop. Этот курс решил ещё во второй лекции: harness — это фундамент, и loop, и graph строятся на нём.
+
+Это объясняет странное явление: почему термин «Graph Engineering» стал популярным только в июле 2026 года, но все обнаружили, что «давно так работают». Потому что граф — не новое изобретение: когда задача становится достаточно сложной, loop автоматически превращается в граф. Сначала появилась практика, потом — имя.
+
+## Разбираем граф: узлы, рёбра, состояние, маршрутизация
+
+Сведём граф к четырём простейшим элементам.
+
+**Узел (Node)** — рабочая единица, несущая какую-то ответственность. Это может быть:
+- фрагмент детерминированного кода (запустить тесты, посчитать покрытие)
+- один вызов модели (сгенерировать документацию)
+- инструмент (git commit, отправить сообщение)
+- полноценный агент — со своим циклом, способный понимать цель, пользоваться инструментами и повторять попытки при неудаче
+
+Узел — настоящая граница раздела между графовой инженерией и workflow-инженерией; об этом поговорим отдельно ниже.
+
+**Ребро (Edge)** — описывает, как узлы передают друг другу работу. Это не просто «сначала A, потом B» — одно ребро может выражать:
+- **Параллельность**: после завершения A узлы B и C стартуют одновременно
+- **Условие**: тесты прошли — идём налево, упали — направо
+- **Сбой / повтор**: узел упал — возвращаемся к нему же и запускаем ещё раз
+- **Откат**: верификация не пройдена — возвращаемся к узлу реализации, который был тремя шагами раньше
+
+**Общее состояние (State)** — пакет данных, передаваемый между узлами. Требования, заметки по исследованию, версии кода, результаты тестов, выводы ревью — всё записывается в один общий рабочий стол. Узлы не перекликаются друг с другом напрямую — они читают и пишут одно и то же состояние.
+
+**Правила маршрутизации (Routing)** — решают, куда идти дальше. Это «поток управления» графа, если сказать совсем просто:
+
+> Тесты прошли — передаём; тесты упали — возвращаемся к узлу реализации; информации недостаточно — возвращаемся к узлу исследования.
+
+Соберём четыре элемента вместе — и типичный граф разработки выглядит так:
+
+```mermaid
+flowchart TD
+ S["Общее состояние<br/>Требования / заметки / код / результаты"] --- R["Узел исследования<br/>Agent: найти проблему"]
+ R -->|"предложить решение"| I["Узел реализации<br/>Agent: написать изменения + тесты"]
+ I -->|"выдать код"| V["Узел верификации<br/>Agent: независимое ревью + запуск тестов"]
+ V -->|"не пройдено"| I
+ V -->|"пройдено"| M["Узел слияния<br/>Код: commit + обновление состояния"]
+ M -->|"обновить состояние"| S
+ I -->|"не хватает данных"| R
+```
+
+Сравните с графом цикла из прошлой лекции: тогда это был один цикл — обнаружение, распределение, верификация, сохранение, и снова обнаружение. А в графе этой лекции **цикл всё ещё существует, но он разложен на явные узлы и рёбра.** Узел верификации может напрямую вернуть провал узлу реализации, узел реализации может из-за нехватки информации отступить к узлу исследования — эти «рёбра отката» в одиночном loop были неявными: агент сам помнил в контексте, что «мне нужно вернуться».
+
+## Когда одного loop недостаточно
+
+У одного loop только одна магистральная дорога. В maker-checker loop, который вы построили в прошлой лекции, все решения — что делать дальше, куда идти при сбое — происходят в контекстном окне одного и того же агента. Если задача становится ещё сложнее, всплывают четыре вопроса:
+
+1. **Разделение труда**: агент, исследующий требования, агент, пишущий код, агент, делающий тесты — кто начинает первым?
+2. **Параллелизм**: какая работа может выполняться одновременно?
+3. **Откат**: куда вернуться после падения тестов — к узлу реализации или к узлу исследования?
+4. **Передача работы**: как несколько агентов видят одни и те же требования, заметки и результаты тестов? Рецензент не согласен с реализатором — чьё мнение главнее?
+
+Дженсен Хуан на [интервью Startup School 2026](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia) в Y Combinator (разговор с Гарри Таном) высказал схожую мысль: когда базовая реализация всё больше автоматизируется агентами, ценность человека смещается к «проектированию систем, заданию явных ограничений и тонкому контролю над агентами». Его пример контроля очень конкретен — «агент даёт план, а я меняю одно слово в файле плана, и это слово даёт точное отличие»; он также предсказывает, что будущим ключевым навыком станет «системное мышление» (systems thinking).
+
+Самый точный удар в обсуждении нанёс Луис Катакора:
+
+> **«В цикле огромный запас допуска на ошибку. Граф заставляет вас признать, сколько частей вашего workflow вообще не было по-настоящему смоделировано.»**
+
+Эта фраза вскрывает глубинное различие loop и graph:
+
+- **Loop — это отложенное решение.** Сначала один агент берёт на себя всю работу, а если не справится — разберёмся в архитектуре потом. Это просто, но цена — невидимость режимов сбоя: вы никогда не знаете, где он застрял, потому что он и сам не знает.
+- **Graph — это решение заранее.** Вы должны заранее объявить всю структуру: кто за что отвечает, как задачи зависят друг от друга, куда возвращаться при определённом сбое. Это хлопотно, но взамен вы получаете читаемость, аудируемость и возможность локального ремонта.
+
+Ещё более прямо: **loop прячет проблему внутри цикла, graph выкладывает проблему на бумагу.** Первый подходит для исследования, второй — для продакшена.
+
+## Три структурных сбоя одиночного цикла
+
+Почему одиночный loop не выдерживает масштаба? Статья eigent.ai *Graph Engineering for AI Agents: Beyond Single Feedback Loops* называет три структурных сбоя — обратите внимание, именно структурных, а не бага конкретного loop.
+
+**Сначала возражение: разве в loop нельзя добавить чек-поинты?** Можно. Верификация, условие остановки и даже повторы с брейкпоинтов из прошлой лекции — всё это loop умещает. Но описанные ниже три сбоя как раз чек-поинты не решают — потому что чек-поинты в loop живут внутри одного и того же агента: проверяющий и тот, кто создаёт проблему, — это один мозг, один контекст. Он остановит «доставку без верификации», но не спросит «а правильная ли эта метрика», «а стоило ли гнаться за этой целью» — ответы записаны в его же контексте, и он их не видит. Граф даёт вам не больше чек-поинтов, а переносит проверку **наружу**: из «внутри агента» в «независимый узел» с полностью свежим контекстом (об этом — раздел про узел verify). Смысл слова «структурный» именно здесь: дело не в том, что у loop не хватает какой-то детали, а в том, что «судья и исполнитель делят один мозг» — это сама структура.
+
+### 1. Гудхарт: цифры растут, а бизнес портится
+
+Доведите любую единственную метрику до предела — и она перестанет измерять то, что, по вашему мнению, измеряет. Классический пример: команда поддержки построила loop вокруг «доли решённых тикетов». Недельные данные ползли вверх. Через несколько месяцев данные по продлению показали, что churn удвоился — **бот научился закрывать тикеты**: переводить тему, отговаривать пользователя от уточнений, помечать нерешённые проблемы как «решённые».
+
+Loop сделал всё, что от него требовали. Просто цифра оторвалась от того, что бизнесу действительно важно. Это закон Гудхарта.
+
+### 2. Слепота вверх: он никогда не спрашивает «а правильная ли эта цель»
+
+Внутри loop опорное значение священно. Термостат не спрашивает, «правильная ли температура 68°F». Продажный loop не спрашивает, «разумна ли эта квота». Agent eval loop не спрашивает, «совпадает ли этот бенчмарк с реальными бизнес-результатами».
+
+**Чью бы цель ни выбрали, loop бежит к ней, даже если это изначально было не то, за чем стоило гнаться.** В структуре одиночного loop нет места для этого вопроса.
+
+### 3. Конфликт: независимые циклы подрывают друг друга
+
+В реальных системах десятки loop, каждый построен независимо. Loop скорости ответа подрывает loop глубины качества, loop роста подрывает loop качества. Каждый loop здоров на своём дашборде, а вся система трясётся — как будто несколько человек тянут одну верёвку в разные стороны.
+
+**Graph engineering должен ответить именно на тот набор вопросов, на который одиночный loop ответить не может:**
+
+- Какие loop питают какие loop?
+- Какие loop владеют целями, за которыми гонятся другие loop?
+- Какие loop могут наложить вето или откатить изменение?
+- Каким метрикам разрешено двигаться, а какие должны быть заморожены?
+
+Когда в системе есть «loop, который может съесть вашу цель», и «loop, который может наложить вето на ваше изменение», их отношения становятся объектом инженерии — а отношения между отношениями, нарисованные, и есть граф.
+
+### Якоря: привязываем циклы к реальности
+
+В названии статьи eigent есть часть про «everyone skips»: **anchors (якоря)**. Какой бы изящной ни была сеть циклов, если каждый цикл дрейфует от реальности, сеть — это лишь радующий сам себя резонанс. Якорь — это то, что привязывает loop к реальному миру: реальные бизнес-результаты, ground truth-датасеты, ручные проверки. При проектировании графа якоря — самый пропускаемый и самый необходимый шаг.
+
+## Graph и Workflow: не просто смена имени
+
+Это самое недопонимаемое место лекции, и его стоит разобрать отдельно.
+
+Первая реакция на взрыв популярности Graph Engineering у любого инженера: «А разве это не workflow? DAG, стейт-машины, движки рабочих процессов — мы гоняем это уже несколько десятилетий».
+
+**Эта интуиция верна наполовину.** Граф и workflow действительно разделяют один скелет: узлы + рёбра + общее состояние + маршрутизация. Airflow, Prefect, Dagster, Temporal десятилетиями оркестрируют именно так. Пять паттернов из статьи Anthropic *Building Effective Agents* (декабрь 2024) — цепочка промптов, маршрутизация, параллелизация, оркестратор/рабочие, оценщик/оптимизатор — если их нарисовать, получаются исполняемые графы разной формы.
+
+**Ошибочная половина — в узлах.** Узлы традиционного workflow — это **детерминированные функции**: Python-функция, shell-скрипт, SQL-задача. Рёбра — зашитый код: `if`, `switch`, `case`. Всю систему инженер поддерживает кодом, поведение предсказуемо — одинаковый вход всегда идёт по одному и тому же пути.
+
+Узел графовой инженерии может быть **полноценным агентом**: со своим loop, умением пользоваться инструментами, пониманием цели и самостоятельными повторами при сбое. И рёбра не обязательно жёстко зашиты — они могут нести правила маршрутизации, где следующий шаг определяют выход предыдущего узла, результат верификации или даже другая модель.
+
+Чтобы прояснить это различие, заимствуем пару понятий у Anthropic. Anthropic одним предложением различает workflow и агента: **кто решает поток управления?** Если код решает шаги — это workflow, если модель в рантайме может менять шаги — это агент.
+
+Тогда что такое граф? **Граф — это контейнер, вмещающий оба.** В одном графе могут одновременно быть:
+
+- workflow-узлы: запустить тесты, посчитать покрытие — детерминированный код, модель не нужна
+- агентные узлы: реализовать фичу, провести ревью кода — полноценные агенты на модели
+- человеческие узлы: согласование, перепроверка — узел взаимодействия с человеком, здесь он останавливается и ждёт человеческого «да»
+
+Поэтому точная формулировка: **Graph Engineering — не замена Workflow, а обобщение Workflow** — тип узлов расширяется от «функции» до «агента», решения рёбер — от «статического кода» до «динамической маршрутизации». workflow — это «полностью детерминированный» частный случай графа.
+
+Контраргумент (статья iii.dev *Loops, Graphs, and the Layer That Matters*) попадает в ту же точку, но с противоположным выводом:
+
+> «Форма — это лёгкая и одноразовая часть. Несущие решения — это то, из чего состоят loop или граф, и что будет после того, как они заработают.»
+
+iii.dev имеет в виду: не выдавайте «топологию» за инженерное достижение. Workflow-инженерия работала десятилетиями, и по-настоящему в ней осело не то, как соединены узлы, а **воспроизводимость, наблюдаемость, восстанавливаемость** — при проблеме можно воспроизвести, в работе можно наблюдать, при сбое можно продолжить. Форму графа вы легко поменяете руками, а вот в эти несущие способности стоит вкладываться. Эту критику стоит держать в голове: **рисование графа — не цель; цель — это то, сколько инженерных способностей вы можете поверх него нести.**
+
+## Вы на самом деле давно рисуете графы
+
+«Старое вино в новых бутылках» — этому есть ещё одно доказательство: инструменты уже готовы.
+
+- **LangGraph**: выпущен в январе 2024 года, к июлю 2026 года — около 65 миллионов загрузок в месяц. Это движок исполнения графов для агентов: узлы могут быть агентами, рёбра могут иметь условную маршрутизацию, checkpoint, interrupt.
+- **Пять паттернов Anthropic**: *Building Effective Agents* за декабрь 2024 года уже нарисовал графы для цепочек промптов, маршрутизации, параллелизации, оркестратора/рабочих и оценщика/оптимизатора — просто не назвал это Graph Engineering.
+- **Claude Code subagent fan-out**: когда вы поручаете главному агенту разослать пачку суб-агентов на параллельную работу, вы уже строите граф — просто не осознаёте этого.
+- **Стейт-машины, DAG-планировщики, очереди задач, графы знаний**: в информатике десятилетиями инженерия графов — не новая проблема.
+
+Что действительно новое? **Узел превратился из «функции» в «агента».** Это единственное изменение — и одновременно все изменения. Раньше, чтобы написать узел workflow, вы описывали его логику, обработку ошибок, стратегию повторов. Теперь узлу достаточно одной инструкции — «исследуй эту проблему», «проверь этот код» — остальное модель делает сама. Узлы стали дешёвыми, и поэтому графы стало выгодно рисовать.
+
+## Построение вашего первого графа с нуля
+
+Теории достаточно, переходим к делу. Maker-checker из прошлой лекции — это **один** агент, который сам себя циклит. Первое, что делает Graph Engineering, — разбирает такого монолитного агента: **каждый узел становится специализированным агентом со своим приватным промптом, контекстом, инструментами, памятью и своим маленьким циклом; узлы не делят контекст, а передают друг другу только через общее состояние.** Это «человеческая» версия фразы Рохита — «graph решает, что видит каждый узел, когда он запускается, куда идёт его выход, кто может наложить вето и что останавливает систему». Все представления ниже не привязаны к какому-либо конкретному движку — это концепция; LangGraph, CrewAI просто превращают их в исполняемые программы, API у них разный, скелет один. Шесть шагов, не пропускайте ни одного.
+
+**Шаг первый: определите общее состояние (State).** Сначала разграничьте два уровня: **на уровне графа общим является только состояние, контекст узлов приватный.** У монолитного агента один контекст, и со временем он тонет в собственном длинном транскрипте; graph режет контекст на части, и каждая часть принадлежит своему узлу — loop — приватная вещь узла, граф — это общий стол, на котором они передают работу. Сначала продумайте, что класть в состояние. Для каждого поля объявите способ «объединения» — когда несколько параллельных узлов одновременно пишут в одно поле, это перезапись, добавление или суммирование. Этот шаг — не функция фреймворка, а правило, которое вы записываете в `graph.md` ещё при рисовании графа:
+
+```
+state = {
+ "requirements": текст, # пишет узел исследования
+ "code": текст, # пишет узел реализации
+ "review": "pass" | "fail", # пишет узел ревью
+ "attempts": число, # +1 за каждую неудачу (при параллельной записи — «суммирование»)
+}
+```
+
+**Шаг второй: перечислите узлы — каждый узел — это полноценный агент (со своим циклом).** Это главное различие графа и workflow: узел workflow — функция, узел графа — **агент со своим маленьким циклом.** Узел получает общее состояние → работает со своим приватным контекстом → записывает результат обратно в общее состояние. Внутри узла, пишущего код, часто живёт тот самый loop из прошлой лекции:
+
+```
+# внутри узла implement: приватный маленький цикл (тот самый maker-checker loop из прошлой лекции)
+node_implement(requirements):
+ loop (максимум 3 раза):
+ code = model(prompt=инструкция по реализации, context=requirements + последняя ошибка)
+ if tests_pass(code): return {"code": code}
+ return {"error": "реализация не прошла за 3 попытки"}
+```
+
+| Узел | Тип | Внутри узла (приватно) | Запись в общее состояние |
+|------|------|------------------|-------------|
+| research | агент | поиск → чтение → обобщение → при нехватке данных повторный поиск (цикл) | requirements |
+| implement | агент | пишет → тестирует → правит → пока не пройдёт (цикл, см. выше) | code |
+| verify | агент | независимое ревью + запуск тестов (**fresh context, не наследует память реализатора**) | review (pass / fail) |
+| merge | детерминированный код | без цикла, при проходе проверки — commit | конец |
+
+Обратите внимание на строку verify: это самый лёгкий для испортить узел графа. **В монолитном агенте «ревью» использует тот же контекст и судит сам себя; в графе verify обязан нести совершенно новый контекст** — он не видит ход мысли реализатора, только код из общего состояния. Именно здесь «независимое ревью» по-настоящему реализуется на графе: изоляция контекста — не побочный эффект, а дизайн.
+
+**Шаг третий: соедините рёбра.** Сначала соедините детерминированную магистраль: исследование → реализация → верификация → слияние → конец.
+
+```mermaid
+flowchart TD
+ A([Начало]) --> B[research]
+ B --> C[implement]
+ C --> D[verify]
+ D --> E[merge]
+ E --> F([Конец])
+```
+
+**Шаг четвёртый: напишите правила маршрутизации (самый важный шаг).** Узел верификации соединяется не напрямую со «слиянием», а с **решением**, которое определяет следующий шаг. Этот шаг и делает явным «куда вернуться при падении теста» — правила маршрутизации возвращают имя узла, и откуда граф пришёл и куда идёт, видно с одного взгляда:
+
+| Текущий узел | Условие | Следующий узел |
+|---------|------|---------|
+| verify | review == pass | merge |
+| verify | review == fail | implement |
+
+```mermaid
+flowchart TD
+ A([Начало]) --> B[research]
+ B --> C[implement]
+ C --> D{verify}
+ D -- pass --> E[merge]
+ D -- fail --> C
+ E --> F([Конец])
+```
+
+**Шаг пятый: повесьте checkpoint (чек-поинты).** Это одно из главных отличий графа от одноразового скрипта: **состояние каждого шага сохраняется на диск**, и если процесс упал, можно продолжить с брейкпоинта, а не начинать заново. После этого ваш граф сразу получает способность «прерывание/возобновление» — а ещё перед merge можно вставить узел «остановиться и ждать одобрения человека» — вот как выглядит на графе тот «ручной эскалейшн» из прошлой лекции:
+
+```
+checkpoint = on(graph, every_step) # состояние каждого шага сохраняется
+graph.pause_before("merge") # остановиться перед слиянием, ждать одобрения
+```
+
+**Шаг шестой: запустите граф и дайте ему точку входа.** Каждый запуск передаёт id треда, и checkpoint по нему различает разные экземпляры запуска:
+
+```
+run(graph, entry={"requirements": "исправить баг на странице логина"}, thread="session-1")
+```
+
+После запуска сверьтесь с рисунком выше: ваша рукописная `graph.md` — это чертёж, а код в движке — исполняемая программа, в которую превратился чертёж. Они должны соответствовать один к одному. Если не сходятся — либо граф нарисован неверно, либо код написан неверно. **В этом и есть смысл «граф выкладывает проблему на бумагу»**: раньше несоответствие никто не замечал, теперь оно видно сразу. Хотите реально работающую эталонную реализацию — см. `code/maker_checker_graph.py`; он написан на LangGraph, но прочитав его, вы должны узнать: это и есть те шесть шагов.
+
+## Open-source-проекты: те, что появились после релиза, и те, что были до него
+
+Сначала проведём границу: **Graph Engineering — это имя, появившееся после 18 июля 2026 года.** Фреймворки, открытые до этого, — не «проекты после релиза Graph Engineering». Реально появившийся после взрыва концепции и прямо называющийся этим именем open-source-проект, по состоянию на начало августа 2026 года, держится один:
+
+**Появившиеся после релиза концепции**
+
+- [GraphArc](https://github.com/CodeGraphContext/grapharc) (2026-08-02): позиционирует себя как «первую живую реализацию Graph Engineering». Он превращает исполнение агентов из trace, зарытого в логах, в **интерактивный оркестрационный граф в реальном времени** — каждый агент, каждая зависимость, каждая точка принятия решения нарисованы, вся картина визуализируется до исполнения, и вы подтверждаете (можно даже с телефона) перед тем, как он даст добро. Автор по опыту делал графовые инструменты для 4000+ разработчиков, направление — «наблюдаемость, отлаживаемость, инженеризируемость». Совсем свежий, функциональность ещё ранняя.
+
+**Существовавшие до релиза концепции (они не называются Graph Engineering, но именно их вы будете использовать при сборке)**
+
+До июля 2026 года эти инструменты существовали от одного до трёх лет: LangGraph (открыт в 2024, 65 млн+ загрузок в месяц, именно на нём написана эталонная реализация выше), CrewAI, Microsoft Agent Framework, LlamaIndex Workflows, Google ADK, OpenAI Agents SDK, Mastra, Claude Agent SDK. **Это не «проекты после релиза Graph Engineering» — это как раз доказательство «до релиза Graph Engineering».** Узлы, рёбра, общее состояние, маршрутизация — всё это работало три-пять лет, и только в июле получило новое имя. Графовый движок не решает проблемы дизайна: он даёт вам узлы, рёбра, checkpoint, но не ответит за вас, «какие loop питают какие, кто владеет целью, кто может наложить вето». Пока вы не продумали эти вопросы, смена движка — это просто рисование одного и того же плохого дизайна красивее.
+
+## Холодный душ: граф — не серебряная пуля
+
+Три ведра холодной воды, от лёгкого к тяжёлому.
+
+**Первое ведро: фейковые цифры.** После взрыва популярности Graph Engineering в сети гуляют данные вроде «с графом точность +18%, стоимость −85%». Корейский блогер goddaehee провёл [факт-чекинг](https://goddaehee.tistory.com/628) (30 июля): оба числа действительно существуют, но взяты из статьи за март 2026 года о химических трубопроводных схемах (P&ID), причём 18% сравнивается с оригиналом изображения, а 85% — с другой схемой — маркетинговый текст склеил два числа с разными базовыми линиями в «до/после», и в самой статье даже нет слова «graph engineering». Увидев любые данные «X% прироста от графовой инженерии», сначала проверьте первоисточник.
+
+**Второе ведро: форма — не несущая стена (iii.dev).** Об этом уже было сказано выше. Loop — это граф из одного узла; стейт-машины работают десятилетиями. Те, кто кричит «loop умер» или «graph умер», обычно не читали внимательно ни loop, ни graph. Учиться нужно паттернам, а не терминам.
+
+**Третье ведро: Orchestration Tax (налог за оркестрацию).** Адди Османи в майском *The Orchestration Tax* дал самую жёсткую экономику для эпохи графов/мульти-агентов: **запустить агента дёшево, закрыть loop — дорого.**
+
+Запустить агента — одна кнопка, одна фраза. Но чтобы закрыть loop агента, кто-то должен проверить его результаты и согласовать с тем, что изменили другие агенты — **этот кто-то вы, и вы один.** Слова Османи:
+
+> «Вы — GIL для ваших AI-агентов. Они могут работать параллельно. Но если их работа требует настоящего понимания архитектуры и разрешения конфликтов слияния, эта работа должна взять эту блокировку. Эта блокировка одна, и она у вас.»
+
+Вот почему сказанное в прошлой лекции «пропускная способность на ревью — потолок» в этой лекции звучит ещё резче: **граф делает параллельных агентов больше, но ваша способность судить — последовательный ресурс, она не параллелится.** Добавление узлов оптимизирует никогда не бывшую узким местом часть — узким местом всегда остаётся тот единственный последовательный процессор: вы.
+
+## Когда граф действительно стоит использовать
+
+Не каждая задача заслуживает графа. Пять критериев; беритесь за дело, когда выполнены хотя бы три:
+
+1. **Задача чисто разбивается на несколько рабочих единиц** — разбитые части не зависят друг от друга и могут идти параллельно
+2. **Существуют ветвления или пути отката** — куда вернуться при падении теста, куда вернуться при нехватке данных — эти пути стоит объявить явно
+3. **Промежуточное состояние стоит сохранять** — после checkpoint можно остановиться и возобновиться, а не начинать заново
+4. **Результат можно явно принять** — у каждого узла есть автоматически проверяемый критерий завершения
+5. **Выгода от сотрудничества > стоимость координации** — сэкономленное на параллелизме время больше, чем накладные расходы самого графа и общего состояния
+
+**«Сложность» ≠ «много шагов».** Линейному конвейеру из 20 шагов граф не нужен — это workflow или просто скрипт. А структуре всего из 5 узлов, но с откатами, параллелизмом и согласованием граф нужен. Критерий — не масштаб, а **наличие ветвлений и откатов**.
+
+## Основные понятия
+
+- **Graph Engineering**: инженерная практика организации нескольких агентов, циклов, инструментов и оценщиков в явный граф (узлы + рёбра + общее состояние + правила маршрутизации). Делает соединение множества рабочих единиц, общее состояние и выбор пути проектируемыми, наблюдаемыми и локально ремонтируемыми.
+- **Четырёхуровневое наслоение**: prompt → context → loop → graph, каждый уровень управляет своим (инструкции, информация, среда выполнения, система), следующий уровень не заменяет предыдущий, а вкладывает его в свои узлы.
+- **Четыре элемента графа**: узел (рабочая единица), ребро (способ передачи), общее состояние (общий рабочий стол), правила маршрутизации (куда идти дальше).
+- **Три структурных сбоя одиночного цикла**: Гудхарт (цифры растут, а бизнес портится), слепота вверх (никогда не спрашивает «а цель ли это»), конфликт (независимые циклы подрывают друг друга). Граф превращает эти три класса проблем в явный дизайн отношений.
+- **Graph ≠ Workflow**: у workflow узлы — детерминированные функции, рёбра — зашитый код; у графа узлы могут быть полноценными агентами, рёбра — динамической маршрутизацией. Граф — обобщение workflow.
+- **Anchors (якоря)**: механизм, привязывающий сеть циклов к реальному миру (реальные бизнес-результаты, ground truth, ручные проверки). Самый пропускаемый и самый необходимый шаг в дизайне графа.
+- **Orchestration Tax (налог за оркестрацию)**: запускать агента дёшево, рецензировать результаты дорого. Ваше внимание — единственный последовательный ресурс, добавление узлов его не оптимизирует.
+
+## Ключевые выводы
+
+- **Graph Engineering не заменяет Loop Engineering, а строит слой поверх него.** loop — это узел графа; три вещи из прошлой лекции (цель, верификация, условие остановки) превращаются во внутреннюю структуру узла.
+- **Граф превращает «отложенное решение» в «решение заранее».** loop прячет режимы сбоя внутри цикла, граф выкладывает их на бумагу — читаемо, аудируемо, локально ремонтируемо.
+- **Что лежит в узле, определяет разницу между графом и workflow.** Функция — это workflow, агент — это граф. И это единственное «новое вино» в «старых бутылках».
+- **Проектируя граф, сначала ответьте на четыре вопроса:** какие loop питают какие, кто владеет целью, кто может наложить вето/откатить, каким метрикам можно двигаться, а какие заморозить. Не можете ответить — не рисуйте.
+- **Не рисуйте граф ради графа.** Пять критериев: чисто разбивается, есть ветвления или откаты, промежуточное состояние стоит сохранить, результат можно принять, выгода от сотрудничества > стоимость координации.
+- **Ваша пропускная способность на ревью — всё ещё потолок.** Граф делает параллельных агентов больше, но ваша способность судить — последовательный ресурс — налог за оркестрацию не исчезает от роста числа узлов.
+- **Помните голос оппонента.** Форма — не несущая стена; воспроизводимость, наблюдаемость, восстанавливаемость — да. Термин меняется каждые шесть недель, инженерные способности — нет.
+
+## Дополнительная литература
+
+- [Prefect: Loops vs. Graphs (Jul 2026)](https://www.prefect.io/blog/loops-vs-graphs) — взгляд на loop и graph от компании, десятилетиями занимающейся оркестрацией графов
+- [Eigent: Graph Engineering for AI Agents (Jul 2026)](https://www.eigent.ai/blog/graph-engineering-ai-agents) — три структурных сбоя одиночного цикла + четыре вопроса дизайна + anchors
+- [iii.dev: Loops, Graphs, and the Layer That Matters (Jul 2026)](https://iii.dev/blog/loops-graphs-and-the-layer-that-matters/) — самый трезвый оппонент: «форма — не несущая стена»
+- [Rohit (@rohit4verse) оригинальный пост (2026-07-29)](https://x.com/rohit4verse/status/2082478623043547356) — первоисточник четырёхуровневой структуры: prompt → context → loop → graph, каждый уровень ложится поверх предыдущего
+- [Agent Times: Graph Engineering as the Final Layer (Jul 2026)](https://theagenttimes.com/articles/graph-engineering-emerges-as-proposed-final-layer-of-agent-o-4f0511a8) — разбор четырёхуровневой структуры Рохита
+- [goddaehee: Факт-чекинг Graph Engineering (корейский, 2026-07-30)](https://goddaehee.tistory.com/628) — самый полный факт-чекинг: таймлайн происхождения шутки, разбор фейковых цифр, данные LangGraph, сравнение популярности на Hacker News
+- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — серьёзная статья за две недели до той шутки
+- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — официальный ответ: «не новая идея, а новое имя для существующего подхода»; 65 млн+ загрузок LangGraph в месяц
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — данные распространения хайпа (первый твит — 575 тыс. просмотров)
+- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — горизонтальное сравнение семи популярных open-source фреймворков: LangGraph, CrewAI, Microsoft Agent Framework, LlamaIndex, Google ADK, OpenAI Agents SDK, Mastra
+- [Официальная документация LangGraph](https://docs.langchain.com/oss/python/langgraph/graph-api) — «Nodes do the work, edges tell what to do next»; точные определения узлов и рёбер, первоисточник при построении графа
+- [Anthropic: Building Effective Agents (Dec 2024)](https://www.anthropic.com/engineering/building-effective-agents) — пять паттернов, нарисованные — это графы; авторитетное различие workflow и агента
+- [Addy Osmani: The Orchestration Tax (May 2026)](https://addyosmani.com/blog/orchestration-tax/) — почему ваше внимание — единственный последовательный ресурс
+- [Addy Osmani: Orchestrating Coding Agents (лекция)](https://talks.addy.ie/oreilly-codecon-march-2026/) — от subagents к agent teams и quality gates
+- [Addy Osmani: Loop Engineering (Jun 2026)](https://addyosmani.com/blog/loop-engineering/) — ключевая ссылка прошлой лекции, предпосылка для графовой инженерии
+- Тринадцатая лекция: [От ручных запросов к автономным циклам](./../lecture-13-loop-engineering/index.md) — loop — это узел графа; сначала поймите внутренности узла, потом граф
+- Одиннадцатая лекция: [Почему наблюдаемость должна быть внутри harness](./../lecture-11-why-observability-belongs-inside-the-harness/index.md) — чем сложнее граф, тем важнее наблюдаемость; невидимый граф — это просто чёрные ящики, собранные в больший чёрный ящик
+- Девятая лекция: [Почему агенты объявляют победу слишком рано](./../lecture-09-why-agents-declare-victory-too-early/index.md) — почему узел верификации должен быть независим от узла реализации; в графе это структурная проблема, а не проблема промпта
+
+## Упражнения
+
+1. **Нарисуйте maker-checker loop из P07 как граф:** в `graph.md` явно выпишите узлы, рёбра, общее состояние и правила маршрутизации. Отметьте, какое ребро условное (верификация пройдена/упала), а какое — откат (сбой возвращается к реализации). После рисования ответьте: есть ли ребро, которое было неявным и раньше пряталось в контексте агента?
+
+2. **Ответьте на четыре вопроса eigent:** найдите три работающих независимых loop (или три автоматизации в одном проекте) и ответьте: кто из них питает кого? Какой loop владеет целью, за которой гонится другой loop? Может ли какой-то loop наложить вето на результат другого? Какие метрики оптимизируются по отдельности и могут конфликтовать?
+
+3. **Самопроверка по Гудхарту:** проверьте метрику, которую вы недавно оптимизировали. Она выросла — а реальные результаты (бизнес-результаты, отзывы пользователей, качество кода) улучшились вместе с ней? Если выросла только цифра — в какую сторону этот loop вас обманывает?
+
+4. **Оценка по пяти критериям:** возьмите задачу, которую вы никак не решите, «графизировать» ли её, и оцените её по пяти критериям. Рисовать стоит, если выполнены хотя бы три. Если меньше трёх — ей нужен просто лучший workflow-скрипт; не используйте граф ради использования графа.
+
+5. **Превратите graph.md в исполняемую программу:** по шести шагам из раздела «Построение вашего первого графа с нуля» реализуйте нарисованный вами maker-checker граф как запускаемый граф (эталонная реализация: `code/maker_checker_graph.py`, написан на LangGraph). Не пропускайте шаги: определите состояние → перечислите узлы → соедините рёбра → напишите маршрутизацию → повесьте checkpoint → запустите. После запуска сверьте `graph.md` и код, найдите первое несоответствие и объясните, почему оно возникло — граф нарисован неверно или код написан неверно?
\ No newline at end of file
diff --git a/docs/ru/projects/project-08-graph-engineering-first-graph/index.md b/docs/ru/projects/project-08-graph-engineering-first-graph/index.md
new file mode 100644
index 0000000..993382a
--- /dev/null
+++ b/docs/ru/projects/project-08-graph-engineering-first-graph/index.md
@@ -0,0 +1,91 @@
+# Project 08. Нарисуйте ваш workflow как граф
+
+> Связанная лекция: [L14. От одиночных циклов к графовой инженерии](./../../lectures/lecture-14-graph-engineering/index.md)
+
+## Что вы будете делать
+
+Это переходный проект от «Loop» к «Graph». В прошлой лекции вы построили maker-checker loop — реализация, верификация, обратная связь, снова реализация, все решения в контекстном окне одного и того же агента. В этой лекции вы **явно выпишете структуру, спрятанную в цикле**: узлы, рёбра, общее состояние, правила маршрутизации — слово за словом.
+
+Вы сделаете три следующих эксперимента: сначала нарисуете maker-checker loop из P07 как явный граф, затем добавите графу параллельный узел fan-out/fan-in, и наконец добавите условное ребро отката и узел ручного согласования. По завершении вы на себе почувствуете одну вещь: **граф — не новое изобретение, это то, во что превращается ваш loop, когда становится достаточно сложным.**
+
+## Какие инструменты
+
+- Claude Code или Codex
+- Git
+- maker-checker loop, который вы построили в P07 (или любой другой агентный workflow, который вы можете многократно запускать)
+- текстовый редактор или инструмент для рисования (рисовать не ради красоты, а чтобы выписать структуру; подойдёт `mermaid` или рукописный `graph.md`)
+
+## Конкретные шаги
+
+### Подготовка
+
+1. Начните с репозитория после P07 или просто возьмите любой агентный workflow, который вы сейчас запускаете.
+2. Создайте три ветки: `p08-explicit-graph`, `p08-parallel`, `p08-human-in-the-loop`.
+3. Подготовьте `state.md` как файл общего состояния: требования, прогресс, результаты верификации — всё записывается сюда. Это «общий рабочий стол» графа.
+
+### Эксперимент 1: нарисуйте Loop как явный граф
+
+Переключитесь на ветку `p08-explicit-graph`.
+
+1. **Перечислите все узлы**: запишите каждый шаг maker-checker loop из P07 как узел. Для каждого узла выпишите: его ответственность, его вход, его выход, агент это или детерминированный код.
+2. **Нарисуйте все рёбра**: перечислите каждое ребро между узлами. Особо отметьте два особых ребра:
+ - условное ребро: верификация пройдена/упала — куда идём
+ - ребро отката: сбой возвращается к какому узлу
+3. **Напишите общее состояние**: явно перечислите, какие поля есть в состоянии (требования, код, результаты тестов, вывод ревью), кто читает, кто пишет.
+4. **Напишите правила маршрутизации**: самым простым языком if-then запишите правила «куда идти дальше», например:
+ ```
+ if верификация пройдена → узел слияния
+ if верификация упала → узел реализации
+ if узлу реализации не хватает данных → узел исследования
+ ```
+5. **Оформите в `graph.md`**: соберите всё выше в документ. Нарисуйте граф через mermaid, приложите таблицу узлов и правила маршрутизации.
+6. **Ответьте на вопрос**: после рисования найдите как минимум одно **бывшее неявным ребро** — путь решения, который раньше прятался в контексте агента и о котором вы даже не знали, что он существует.
+
+### Эксперимент 2: добавьте параллельный узел Fan-out / Fan-in
+
+Переключитесь на ветку `p08-parallel`.
+
+1. **Выберите точку для параллелизма**: найдите в задаче место, которое можно разбить на две независимые части. Например:
+ - реализацию разбить на два независимых модуля, два агента пишут параллельно
+ - верификацию разбить на две независимые проверки: один запускает тесты и линт, другой делает ревью кода (разные инструкции, разные фокусы)
+ - исследование разбить на два направления, два агента ведут каждый свою линию
+2. **Напишите правило fan-out**: в общем состоянии запишите «эта задача разбита на N параллельных подзадач», у каждой подзадачи отдельный контекст и отдельный узел.
+3. **Напишите правило fan-in**: когда все подзадачи завершены, кто объединяет результаты? Каков критерий объединения (например, объединяем только если обе проверки прошли, или достаточно одной)?
+4. **Изолируйте с помощью worktree**: каждая параллельная подзадача работает в отдельном git worktree, физически исключая коллизии файлов (вспомните примитив Worktree из тринадцатой лекции).
+5. **Запустите один раз и запишите**: зафиксируйте wall-clock время до и после параллелизма, расход токенов, качество результата. Параллелизм реально быстрее? Или накладные расходы на координацию съели сэкономленное время?
+
+### Эксперимент 3: добавьте ребро отката и узел ручного согласования
+
+Переключитесь на ветку `p08-human-in-the-loop`.
+
+Это самый важный из трёх экспериментов. Вы добавите к графу два вида узлов:
+
+1. **Условное ребро отката**: добавьте узлу верификации путь «частично пройдено» — не возвращать всё к узлу реализации, а с конкретной обратной связью вернуться к **узлу, породившему проблему**. Например: тесты прошли, но ревью кода обнаружило, что требования поняты неверно — откат к узлу исследования, а не к реализации. Это требует, чтобы ваше общее состояние фиксировало «на каком уровне возникла проблема».
+2. **Узел ручного согласования (Human-in-the-loop)**: перед узлом слияния добавьте человеческий узел. Дойдя до него, граф **останавливается** и ждёт, пока вы напишете в `state.md` «одобрить» или «отклонить». У узла согласования может быть правило таймаута: если за N часов нет ответа — автоотклонение или авто-эскалация.
+3. **Напишите формат interrupt**: как чётко оформить запрос на согласование — что произошло, что изменилось, зачем нужен человек, каковы последствия одобрения/отклонения.
+4. **Пройдите минимум 2 полных цикла**: в каждом цикле дойдите до узла ручного согласования и сами одобрите или отклоните один раз. Запишите: совпадает ли ваше решение с суждением узла верификации? Останавливал ли узел согласования то, что узел верификации не остановил?
+
+## Как измерять результат
+
+| Показатель | Эксперимент 1 (явный граф) | Эксперимент 2 (параллелизм) | Эксперимент 3 (человек+машина) |
+|------|----------------|--------------|------------------|
+| Видимость структуры | Сколько неявных рёбер вы нашли? | Может ли общее состояние поддерживать параллельные подзадачи? | Может ли ребро отката точно локализовать проблемный слой? |
+| Локализация сбоя | При сбое можно ли напрямую указать, какое ребро неверно? | При сбое параллельной подзадачи можно ли локализовать, какой именно? | При отклонении можно ли указать, проблема какого слоя? |
+| Накладные расходы на сотрудничество | Сколько времени заняло рисование графа? | Сэкономленное на параллелизме время vs накладные расходы на координацию | Время ожидания согласования vs ценность остановленных проблем |
+| Наблюдаемость | Что происходит на каждом шаге, теперь видно? | Виден ли статус каждой параллельной подзадачи? | Достаточно ли чётко написан запрос на согласование? |
+| Надёжность | Совпадает ли описание графа с реальным запуском? | Корректен ли критерий объединения fan-in? | Действительно ли срабатывают правила таймаута/эскалации? |
+
+## Что сдать
+
+- `graph.md` (полное описание графа из эксперимента 1: mermaid-диаграмма + таблица узлов + таблица рёбер + поля общего состояния + правила маршрутизации)
+- список неявных рёбер, найденных в эксперименте 1 (минимум одно)
+- правила fan-out/fan-in из эксперимента 2 и одна запись параллельного запуска (сравнение времени/стоимости/качества)
+- правила ребра отката из эксперимента 3, формат узла согласования и записи 2 циклов человек+машина
+- финальная рефлексия: от loop к graph — как изменился ваш способ работы? Какие задачи заслуживают графа, а какие нет?
+
+## Связанные лекции
+
+- [Lecture 14 — От одиночных циклов к графовой инженерии](../../lectures/lecture-14-graph-engineering/index.md)
+- [Lecture 13 — От ручных запросов к автономным циклам](../../lectures/lecture-13-loop-engineering/index.md) (ваш loop — это узел графа; этот проект раскрывает внутреннюю структуру узла)
+- [Lecture 09 — Почему агенты объявляют победу слишком рано](../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md) (почему узел верификации должен быть независим от узла реализации; в графе это структурная проблема)
+- [Lecture 11 — Почему наблюдаемость должна быть внутри harness](../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) (чем сложнее граф, тем больше нужно видеть, что делает каждый узел)
\ No newline at end of file
diff --git a/docs/tr/lectures/lecture-14-graph-engineering/index.md b/docs/tr/lectures/lecture-14-graph-engineering/index.md
new file mode 100644
index 0000000..9ea7b70
--- /dev/null
+++ b/docs/tr/lectures/lecture-14-graph-engineering/index.md
@@ -0,0 +1,349 @@
+[English Version →](../../../en/lectures/lecture-14-graph-engineering/)
+
+> Kod örnekleri: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-14-graph-engineering/code/)
+> Uygulama projesi: [Proje 08. İş Akışınızı Bir Graf Olarak Çizin](./../../projects/project-08-graph-engineering-first-graph/index.md)
+
+# Ders 14. Tek Döngülerden Graf Mühendisliğine
+
+Loop Engineering ana akıma girdikten altı hafta sonra, 18 Temmuz 2026'da Peter Steinberger — bir önceki derste size "coding agent'ınıza artık prompt yazmayın" diyen OpenClaw yazarı — bir tweet attı:
+
+> "Hâlâ loop'lardan mı bahsediyoruz, yoksa graph'lara mı geçtik?"
+
+Tek bir tweet — bir gün içinde yaklaşık 570 bin görüntüleme, ay sonuna kadar kabaca 3 milyona ulaştı. Birkaç saat sonra, makine öğrenimi mühendisi Hamel Husain, *Loop Engineering Is Dead. Enter Graph Engineering* başlıklı bir makale yayınladı — gövdesi tek bir "Stop it" GIF'i olan bir makale — ve yaklaşık 680 bin görüntüleme daha topladı.
+
+İşin daha da ilginç yanı: **ikisi de şaka olarak atmıştı.** Biri her altı haftada bir yeni terim icat eden bir sektörü hicvediyordu; diğeri şakanın üzerine gidiyordu. Ama şaka yalnızca yaklaşık bir hafta sonu yaşadı — hafta sonu bitmeden kurslar, yol haritaları ve araç yığınları zaman çizelgesine doldu ve arkasında bir yığın uydurma sayı geldi: "+18% doğruluk, −85% maliyet" iddiası sahte (iki sayı gerçekten var ama kimyasal boru hattı şemaları hakkındaki bir makaleden geliyor ve farklı tabanlara karşı karşılaştırılıyor) ve "Microsoft, Stanford ve Anthropic aynı anda graf mühendisliğini keşfetti" iddiası da yanlış. Gerçek denetimi yalnızca tek bir gerçek "öncü" buluyor: Josh Simmons — *We Are Entering the Graph Engineering Phase* adlı yazısı 4 Temmuz tarihli, şakadan tam iki hafta önce. **Şaka fikri popüler yaptı. Fikri yaratmadı.**
+
+> Kaynak: [goddaehee: Graph Engineering gerçek denetimi (2026-07-30)](https://goddaehee.tistory.com/628); [YC Startup School 2026: Jensen Huang röportajı (transkript ile)](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia); [explainx: Graph Engineering (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026)
+
+Bu dersin amacı bu moda sözcüğe odun eklemek değil, terimi parçalara ayırıp net görmek: **tek bir loop neden kaçınılmaz olarak bir grafa dönüşür? Graf ile workflow arasında gerçekten ne fark var? Peki ne zaman gerçekten ihtiyacın olur, ne zaman olmaz?**
+
+## Prompt, Context, Loop, Graf: Dört İsim, Üst Üste Dört Katman
+
+Temmuz sonunda, Rohit (@rohit4verse) adlı bir mühendis, AI mühendisliğinin son birkaç yıldaki adlandırma tarihini dört katmanlı temiz bir çerçeve halinde düzenleyen bir [uzun gönderi](https://x.com/rohit4verse/status/2082478623043547356) paylaştı. Graf mühendisliğini anlamak için en iyi koordinat sistemi bu:
+
+| Katman | Şekillendirdiği | Cevap verdiği soru | Ana çıktılar |
+|------|---------|-----------|---------|
+| **Prompt Engineering** | Talimat | Modele ne yapacağını nasıl söyleriz? | instructions, examples, constraints, roles, output formats |
+| **Context Engineering** | Bilgi | Model karar vermeden önce neyi bilmeli? | documents, history, memory, tool definitions, environment state |
+| **Loop Engineering** | Çalışma zamanı | Hedefe ulaşılana kadar modeli nasıl döngüye sokarız? | observe, reason, act, inspect, update, stop condition |
+| **Graph Engineering** | Sistem | Birden fazla ajan, loop, araç ve değerlendirici nasıl iş birliği yapar? | nodes, edges, shared state, routing rules |
+
+Bu dizilimi nasıl okumanız gerektiğine dikkat edin: **her katman önceki katmanın yerini almaz — onun üzerine biner.**
+
+- Context engineering'i bulduktan sonra prompt engineering'i bırakmadınız — her iterasyon hâlâ bir prompt gerektirir; loop sadece ortam değiştikçe onu tazeler.
+- Loop'lar kurduktan sonra context'i bırakmadınız — bir loop'un her turu bağlamını yeniden birleştirir.
+- Graf katmanında prompt, context ve loop — hiçbiri kaybolmaz: **her düğüm kendi prompt'unu, kendi context'ini, kendi araçlarını, kendi belleğini, kendi loop'unu taşır.** Graf, düğümlerin nasıl bağlanacağına karar verir.
+
+Rohit'in gönderisi şöyle bitiyor:
+
+> Bir ajan uzmanlaşma, paralellik, paylaşılan durum, doğrulama ve kurtarma gerektirdiğinde, artık bir loop değildir. Bir graftır.
+
+**Bir dakika — peki harness?** Bu dört isim Harness Engineering'i içermiyor, oysa bu kursun tamamı harness hakkında. Sebep basit: Rohit moda sözcüklerin tarihini anlatıyordu, sonu graf'tı ve ortadaki katman atlandı. Üstelik harness'ın hangi katmana ait olduğu bile netleşmedi — [explainx](https://explainx.ai/blog/context-prompt-loop-harness-engineering-stack-2026) onu loop'un üstüne, [Buildrix makalesi](https://arxiv.org/abs/2606.25139) loop'un altına koyuyor. Bu kurs bunu ikinci derste çözüme kavuşturdu: harness temeldir; loop'lar ve graph'lar onun üzerine inşa edilir.
+
+Bu, tuhaf bir olguyu açıklıyor: "Graph Engineering" terimi neden yalnızca Temmuz 2026'da yaygınlaştı, oysa herkes "bunu hep yapıyordum" diye hissetti. Çünkü graf yeni bir icat değil — göreviniz yeterince karmaşık hale geldiğinde loop'un dönüştüğü şeydir. **İsim sonradan geldi; uygulama zaten vardı.**
+
+## Graf'ı Parçalara Ayırın: Düğümler, Kenarlar, Durum, Yönlendirme
+
+Graf'ı en basit dört parçaya indirin.
+
+**Düğüm (Node)**: bir sorumluluk taşıyan çalışma birimi. Şunlar olabilir:
+- deterministic kod (test çalıştırma, kapsam hesaplama)
+- bir model çağrısı (doküman üretme)
+- bir araç (git commit, mesaj gönderme)
+- tam bir ajan — kendi loop'uyla, hedefleri anlayabilen, araçları kullanabilen, takıldığında kendi kendine yeniden deneyen
+
+Düğümün ne olabileceği, graf mühendisliği ile workflow mühendisliği arasındaki gerçek ayrım çizgisidir. Bunu aşağıda ayrıca ele alacağız.
+
+**Kenar (Edge)**: işin düğümler arasında nasıl devredildiğini açıklar. Sadece "önce A'yı yap, sonra B'yi" değildir — bir kenar şunları ifade edebilir:
+- **Paralellik**: A tamamlandıktan sonra B ve C aynı anda başlar
+- **Koşullar**: testler geçerse sola, başarısız olursa sağa git
+- **Başarısızlık/yeniden deneme**: bir düğüm çökerse, kendi içine döner ve tekrar çalışır
+- **Geri alma**: doğrulama başarısız olursa, üç adım gerideki uygulama düğümüne dön
+
+**Paylaşılan Durum (State)**: düğümler arasında aktarılan veri paketi. Gereksinimler, araştırma notları, kod sürümleri, test sonuçları, inceleme sonuçları — hepsi aynı ortak çalışma yüzeyine yazılır. Düğümler birbirine bağırmaz; hepsi aynı durumu okur ve yazar.
+
+**Yönlendirme Kuralları (Routing)**: yürütmenin bir sonraki adımda nereye gideceğine karar verir. Bu, graf'ın "kontrol akışıdır" ve en sade ifadeyle:
+
+> Testler geçerse teslim et. Testler başarısız olursa uygulama düğümüne geri dön. Bilgi yetersizse araştırma düğümüne geri dön.
+
+Dört parçayı birleştirin ve tipik bir geliştirme grafiği şöyle görünür:
+
+```mermaid
+flowchart TD
+ S["Paylaşılan Durum<br/>gereksinimler / notlar / kod / sonuçlar"] --- R["Araştırma düğümü<br/>Agent: sorunu bul"]
+ R -->|"plan"| I["Uygulama düğümü<br/>Agent: değişiklikleri + testleri yaz"]
+ I -->|"kod"| V["Doğrulama düğümü<br/>Agent: bağımsız inceleme + testleri çalıştır"]
+ V -->|"başarısız"| I
+ V -->|"geçti"| M["Birleştirme düğümü<br/>kod: commit + durumu güncelle"]
+ M -->|"durum güncellemesi"| S
+ I -->|"bilgi yetersiz"| R
+```
+
+Bunu bir önceki dersteki loop diyagramıyla karşılaştırın: O loop bir halkaydı — keşfet, gönder, doğrula, kalıcı hale getir, keşfe dön. Bu dersin grafiğinde **halka hâlâ var ama açık düğümlere ve kenarlara ayrıştırıldı.** Doğrulama düğümü bir başarısızlığı doğrudan uygulama düğümüne geri gönderebilir; uygulama düğümü bilgi yetersiz olduğunda araştırmaya geri çekilebilir. Bu "geri alma kenarları" tek bir loop içinde örtüktü — ajan sadece kendi bağlam penceresinde "geri dönmem gerektiğini" hatırlıyordu.
+
+## Bir Loop Ne Zaman Yetersiz Kalır
+
+Tek bir loop'un kendi ana yolu vardır. Proje 07'de kurduğunuz maker-checker loop'unda, tüm kararlar — sırada ne yapılacağı, başarısızlıkta nereye gidileceği — tek bir ajanın bağlam penceresinde gerçekleşiyordu. Görevi biraz daha zorlayın ve dört soru ortaya çıkar:
+
+1. **İş bölümü**: araştırma ajanı, uygulama ajanı, test ajanı — hangisi önce başlar?
+2. **Paralellik**: işin hangi parçaları aynı anda çalışabilir?
+3. **Geri alma**: testler başarısız olduğunda nereye dönersiniz — uygulama düğümüne mi, yoksa araştırma düğümüne mi?
+4. **Devir**: birden fazla ajan aynı gereksinimleri, notları ve test sonuçlarını nasıl görür? İnceleyen uygulayanla aynı fikirde olmazsa, kim kazanır?
+
+Jensen Huang, Y Combinator'daki [Startup School 2026 röportajında](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia) (Garry Tan ile) benzer bir noktaya değindi: uygulama giderek ajanlar tarafından otomatikleştirilirken, insanın temel değeri sistemleri tasarlamaya, kısıtlar tanımlamaya ve ajanları ince taneli kontrol etmeye kayar. Verdiği kontrol örneği somut — "bir plan ürettiğinde, plan dosyasında bir kelime değiştiririm ve o bir kelime tam bir fark yaratır" — ve geleceğin temel becerisinin "sistem düşüncesi" (systems thinking) olacağını öngörüyor.
+
+Tartışma başlığındaki en keskin yorum Luis Catacora'dan geldi:
+
+> **"Loop'ların çok fazla hata payı var. Graf seni, iş akışının ne kadar çok bölümünün gerçekten modellenmediğini itiraf etmeye zorlar."**
+
+Bu cümle loop ile graf arasındaki derin farkı ortaya koyuyor:
+
+- **Loop ertelenmiş bir karardır.** Tek bir ajan tüm işi üstlensin; takılırsa sonra hallolur. Mimari ertelenebilir. Ucuzdur — ama başarısızlık modları görünmezdir, çünkü ajan nerede takıldığını kendisi de bilmez.
+- **Graf önceden verilmiş bir karardır.** Tüm yapıyı önceden ilan etmelisiniz: kimin neye sahip olduğu, görevlerin birbirine nasıl bağlı olduğu, belirli bir başarısızlığın nereye döneceği. Daha çok iştir — ama size okunabilirlik, denetlenebilirlik ve yerel onarım kazandırır.
+
+Daha da açık bir ifadeyle: **loop sorunu loop'un içinde gizler; graf sorunu kağıda koyar.** Birincisi keşif için uygundur, ikincisi üretim için.
+
+## Tek Bir Loop'un Ölçekte Üç Yapısal Başarısızlığı
+
+Tek bir loop ölçekte neden dayanmaz? eigent.ai'nin *Graph Engineering for AI Agents: Beyond Single Feedback Loops* makalesi üç yapısal başarısızlık tanımlar — yapısal, herhangi bir loop'un bug'ı değil.
+
+**Önce bir itiraz: loop'a kontrol noktaları da eklenemez mi?** Eklenebilir. Önceki dersin doğrulaması, durdurma koşulları, hatta duraklat-ve-devam etme — bir loop hepsini barındırabilir. Ama aşağıdaki üç başarısızlık, kontrol noktalarının tam olarak çözemediği şeylerdir — çünkü bir loop'un kontrol noktaları aynı ajanın içinde yaşar ve kontrol eden ile sorunu yaşayan aynı beyni, aynı bağlamı paylaşır. "Doğrulama olmadan teslim etmeyi" durdurur, ama "bu metrik doğru mu?" ya da "bu hedef kovalanmalı mı?" diye sormaz — cevaplar kendi context'inde yaşar ve onları göremez. Graf size daha fazla kontrol noktası vermez; kontrolü *dışarı* taşır: ajanın içinden bağımsız bir düğüme, ona tertemiz bir bağlam vererek (yukarıdaki verify düğümü bölümünde işlendiği gibi). "Yapısal" kelimesinin anlamı burada: loop'ta eksik olan bir parça değil, "yargılayan ile yargılanan aynı beyni paylaşır" yapısının kendisi.
+
+### 1. Goodhart: Rakamlar Yükseldi, İş Kötüleşti
+
+Herhangi bir tek metriği sonuna kadar zorlayın, ölçtüğünü sandığınız şeyi ölçmeyi bırakır. Klasik örnek: bir destek ekibi "bilet çözüm oranı" etrafında bir loop kurar. Haftalık sayılar yükselir. Aylar sonra, yenileme verileri churn'ın iki katına çıktığını gösterir — **bot biletleri kapatmayı öğrenmiştir**: konuyu değiştirir, takip sorularını caydırır, çözülmemiş sorunları "çözüldü" olarak işaretler.
+
+Loop, kendisinden istenen her şeyi yaptı. Sadece sayı, işin gerçekten önemsediği şeyden koptu. Goodhart yasası işte.
+
+### 2. Yukarıya Körlük: "Bu Doğru Hedef mi?" Diye Asla Sormaz
+
+Bir loop'un içinde referans değer kutsaldır. Bir termostat "68°F doğru sıcaklık mı?" diye sormaz. Bir satış loop'u "bu kota makul mü?" diye sormaz. Bir ajan eval loop'u "bu benchmark gerçek iş sonuçlarıyla eşleşiyor mu?" diye sormaz.
+
+**Birisi o hedefi seçti ve loop, baştan beri kovalanacak doğru şey olmasa bile ona doğru koşar.** Tek bir loop'un yapısında bu sorunun sorulabileceği hiçbir yer yoktur.
+
+### 3. Çatışma: Bağımsız Loop'lar Birbirini Baltalar
+
+Gerçek sistemlerde onlarca loop vardır, her biri bağımsız kurulur. Yanıt hızı loop'u derinlik/kalite loop'unu baltalar; büyüme loop'u kalite loop'unu baltalar. Her loop kendi panelinde sağlıklı görünürken sistemin bütünü sallanır — birkaç kişinin aynı ipi farklı yönlerde çekmesi gibi.
+
+**Graf mühendisliği, tam olarak tek bir loop'un cevaplayamadığı soruları yanıtlamak için kurulmuştur:**
+
+- Hangi loop'lar hangi loop'ları besler?
+- Hangi loop'lar diğer loop'ların kovaladığı hedeflere sahiptir?
+- Hangi loop'lar bir değişikliği veto edebilir veya geri alabilir?
+- Hangi ölçümlerin değişmesine izin verilir, hangileri donmuş kalmalıdır?
+
+Sisteminizde "hedeflerinizi tüketen loop'lar" ve "değişikliklerinizi veto edebilen loop'lar" olduğunda, aralarındaki ilişkiler mühendislik nesnesi haline gelir — ve ilişkiler arasındaki ilişkiler, çizildiğinde bir graftır.
+
+### Çapalar: Loop'u Gerçekliğe Sabitleyin
+
+eigent makalesinde "everyone skips" (herkesin atladığı) başlıklı bir bölüm vardır: **anchors (çapalar)**. Loop ağınız ne kadar zarif olursa olsun, her loop gerçeklikten uzaklaşırsa, ağ yalnızca karşılıklı sürüklenmenin bir rezonansıdır. Çapa, loop'u gerçek dünyaya sabitleyen şeydir — gerçek iş sonuçları, ground truth veri setleri, insan nokta kontrolleri. Graf tasarımının en kolay atlanan ve en çok atlanmaması gereken parçası.
+
+## Graf ve Workflow: Sadece Bir İsim Değişikliği Değil
+
+Bu, tüm konunun en çok yanlış anlaşılan noktasıdır, bu yüzden kendi bölümünü hak ediyor.
+
+Graph Engineering yaygınlaştığı anda, üretim deneyimi olan herkes aynı şeyi mırıldandı: "Bu sadece workflow değil mi? DAG'lar, durum makineleri, workflow motorları — onları yıllardır çalıştırıyoruz."
+
+**Bu sezgi yarı yarıya doğru.** Graf ve workflow gerçekten de aynı iskeleti paylaşır: düğümler + kenarlar + paylaşılan durum + yönlendirme. Airflow, Prefect, Dagster, Temporal yıllardır tam olarak bu şekilde orkestrasyon yapıyor. Ve Anthropic'in Aralık 2024'teki *Building Effective Agents*'ındaki beş desen — prompt zincirleme, yönlendirme, paralelleştirme, orkestratör-işçi, değerlendirici-optimize edici — çizildiğinde tam olarak farklı şekillerdeki yürütme graf'larıdır.
+
+**Yanlış olan yarı düğümlerin içindedir.** Geleneksel workflow düğümleri **deterministik fonksiyonlardır**: bir Python fonksiyonu, bir shell betiği, bir SQL görevi. Kenarlar kodla yazılmıştır: `if`, `switch`, `case`. Mühendis tüm sistemi kodla sürdürür ve davranış öngörülebilirdir — aynı girdi her zaman aynı yolu izler.
+
+Bir graf mühendisliği düğümü **tam bir ajan** olabilir: kendi loop'u, araç kullanımı, hedef anlayışı, başarısızlıkta yeniden deneme. Ve kenarlar mutlaka kodla yazılmak zorunda değildir — önceki düğümün çıktısı, bir doğrulama sonucu, hatta başka bir model tarafından kararlaştırılan yönlendirme kuralları taşıyabilirler.
+
+Farkı netleştirmek için Anthropic'in bir kavram çiftini ödünç alalım. Anthropic, workflow ve agent'ı tek bir soruyla ayırır: **kontrol akışına kim karar verir?** Adımları kod sabitlerseniz workflow'dur; model adımları çalışma zamanında değiştirebiliyorsa agent'dır.
+
+Peki graf nedir? **Graf, ikisini de barındıran kaptır.** Bir graf aynı anda şunları içerebilir:
+
+- workflow düğümleri: testleri çalıştırma, kapsam hesaplama — deterministic kod, model gerekmez
+- ajan düğümleri: özellikleri uygulama, kodu inceleme — tam model güdümlü ajanlar
+- insan düğümleri: onay, inceleme — insan-ortada, graf durur ve bir insanın onayını bekler
+
+Yani doğru ifade şudur: **Graph Engineering, Workflow'un yerine geçen değil, Workflow'un genelleştirilmesidir** — düğüm türü "fonksiyondan" "ajan'a", kenar kararları "statik koddan" "dinamik yönlendirmeye" genişletilir. Workflow, graf'ın "tamamen deterministik" özel durumudur.
+
+Karşı görüş (iii.dev'in *Loops, Graphs, and the Layer That Matters*'ı) aynı noktaya gelir, ancak zıt sonuca varır:
+
+> "Şekil kolay kısımdır ve tek kullanımlıktır. Taşıyıcı karar, loop'un veya graf'ın neden yapıldığı ve çalıştıktan sonra ona ne olduğudur."
+
+iii.dev'in noktası: "topolojiyi" mühendislik başarısı sanmayın. Workflow mühendisliği onlarca yıl çalıştı ve gerçekten hayatta kalan şey düğümlerin nasıl bağlandığı değil — **yeniden oynatılabilirlik, gözlemlenebilirlik ve kurtarılabilirliktir**: bir başarısızlığı yeniden oynatabilir, bir çalışmayı izleyebilir ve çökmeden sonra devam edebilirsiniz. Graf'ın şeklini her gün yeniden çizebilirsiniz; çabanızı harcayacağınız yer bu taşıyıcı yeteneklerdir. Bu eleştiri akılda tutulmaya değer: **graf çizmek amaç değildir. Graf'ın taşıyabileceği mühendislik kapasitesi amaçtır.**
+
+## Aslında Hep Graf Çiziyordunuz
+
+"Yeni şişe, eski şarap"ın bir kanıtı daha var: araçlar zaten oradaydı.
+
+- **LangGraph**: Ocak 2024'te yayınlandı, Temmuz 2026'ya kadar aylık yaklaşık 65 milyon indirme. Ajanlar için bir graf yürütme motorudur — düğümler ajan olabilir, kenarlar koşullu yönlendirme, checkpoint ve interrupt taşıyabilir.
+- **Anthropic'in beş deseni**: Aralık 2024'teki *Building Effective Agents* zaten prompt zincirleme, yönlendirme, paralelleştirme, orkestratör-işçi ve değerlendirici-optimize edici graf'larını çizmişti. Sadece ona Graph Engineering demedi.
+- **Claude Code'un subagent fan-out'u**: bir ana ajanın paralel çalışan bir grup alt ajan göndermesine izin verdiğinizde, zaten bir graf inşa ediyorsunuz — sadece fark etmediniz.
+- **Durum makineleri, DAG zamanlayıcıları, görev kuyrukları, bilgi graf'ları**: bilgisayar bilimi onlarca yıldır graf'ları mühendislik nesnesi yapıyor.
+
+Gerçekten yeni olan ne? **Düğüm "fonksiyondan" "ajan'a" dönüştü.** Bu tek değişiklik — ve tüm değişiklik. Eskiden bir workflow düğümü yazmak, mantığını, hata yönetimini ve yeniden deneme politikasını elle yazmak demekti. Şimdi bir düğüm tek bir talimat gerektiriyor — "bu sorunu araştır", "bu kodu incele" — gerisini model halleder. Düğümler ucuzladı, böylece graf'lar çizilmeye değer hale geldi.
+
+## İlk Graf'ınızı Sıfırdan Oluşturun
+
+Yeterince teori. Hadi inşa edelim. Önceki dersin maker-checker'ı, kendi kendine dönen **tek** bir ajandı. Graph Engineering'in yaptığı ilk şey, o monolitik ajanı parçalara ayırmaktır: **her düğüm, kendi özel prompt'u, context'i, araçları, belleği ve kendi küçük loop'u olan uzman bir ajan haline gelir; düğümler birbirleriyle bağlam paylaşmaz — yalnızca tek bir paylaşılan durum üzerinden devir yaparlar.** Bu, Rohit'in cümlesinin sade bir dille versiyonudur — "graf, her düğümün ne gördüğüne, ne zaman çalıştığına, çıktısının nereye gittiğine, kimin onu reddedebileceğine ve sistemi neyin durduracağına karar verir". **Aşağıdaki notasyonların hiçbiri belirli bir motora bağlı değildir** — bunlar kavramlardır; LangGraph, CrewAI ve diğerleri onları yürütülebilir programlara dönüştüren uygulamalardır, farklı API, aynı iskelet. Altı adım — hiçbirini atlamayın.
+
+**Adım 1: Paylaşılan durumu tanımlayın.** Önce iki katmanı ayırın: **graf seviyesinde yalnızca durum paylaşılır; düğüm context'i özeldir.** Monolitik bir ajanın tek bir context'i vardır ve uzun bir çalışmanın sonunda kendi transcript'ine boğulur; graf context'i düğüm başına bir parça olacak şekilde böler — loop düğümün özel mülküdür, graf onların devir yaptığı paylaşılan tezgâhtır. Durumun ne içerdiğini düşünün. Her alanın nasıl birleştirileceğini bildirin — eşzamanlı düğümler aynı alana yazdığında, üzerine yazılır mı, eklenir mi, toplanır mı? Bu bir framework özelliği değil; graf'ı çizerken `graph.md`'ye yazdığınız bir kuraldır:
+
+```
+state = {
+ "requirements": metin, # araştırma düğümü tarafından yazılır
+ "code": metin, # uygulama düğümü tarafından yazılır
+ "review": "pass" | "fail", # doğrulama düğümü tarafından yazılır
+ "attempts": sayı, # her başarısızlıkta +1 (eşzamanlı yazmalarda "toplama" ile birleştirilir)
+}
+```
+
+**Adım 2: Düğümleri listeleyin — her düğüm tam bir ajandır (kendi loop'uyla).** Bu, graf ile workflow arasındaki temel farktır: bir workflow düğümü bir fonksiyondur; bir graf düğümü, **kendi küçük loop'unu taşıyan bir ajan**dır. Düğüm paylaşılan durumu alır, özel context'inde işini yapar ve sonuçları paylaşılan duruma geri yazar. Kod yazan bir düğümün içi genellikle önceki dersin loop'udur:
+
+```
+# implement düğümünün içi: özel bir küçük loop (önceki dersin maker-checker loop'u)
+node_implement(requirements):
+ loop (en fazla 3 kez):
+ code = model(prompt=uygulama talimatları, context=requirements + son hata)
+ if tests_pass(code): return {"code": code}
+ return {"error": "uygulama 3 kez başarısız oldu"}
+```
+
+| Düğüm | Tür | Düğümün içi (özel) | Paylaşılan duruma yazar |
+|------|------|--------------------------|------------------------|
+| research | ajan | ara → oku → özetle → bilgi yetersizse yeniden ara (loop) | requirements |
+| implement | ajan | yaz → test et → düzelt → geçene kadar (loop, yukarıda) | code |
+| verify | ajan | bağımsız inceleme + testleri çalıştır (**taze context, uygulayıcının belleğini devralmaz**) | review (pass / fail) |
+| merge | deterministic kod | loop yok; kontroller geçince commit | done |
+
+verify satırına dikkat edin — graf'ta yanlış yapılması en kolay düğümdür. **Monolitik bir ajanda "inceleme" hâlâ aynı context'te çalışır, yani ajan kendini inceler; graf'ta verify tamamen taze bir bağlam almalıdır** — implement'in muhakemesini görmez, yalnızca paylaşılan durumdaki `code`'u görür. "Bağımsız incelemenin" bir graf üzerinde gerçekten gerçekleştiği yer burasıdır: bağlam izolasyonu bir yan etki değil, tasarımdır.
+
+**Adım 3: Kenarları bağlayın.** Deterministik ana hatla başlayın: research → implement → verify → merge → end.
+
+```mermaid
+flowchart TD
+ A([Başlangıç]) --> B[research]
+ B --> C[implement]
+ C --> D[verify]
+ D --> E[merge]
+ E --> F([Bitiş])
+```
+
+**Adım 4: Yönlendirme kurallarını yazın (en önemli adım).** verify düğümü doğrudan merge'e bağlanmaz — yürütmenin nereye gideceğini seçen bir **karara** bağlanır. "Başarısızlıklar nereye geri döner" burada açık hale gelir. Yönlendirme kuralları düğüm adlarını döndürür, böylece tüm graf — nereden geldiği, nereye gittiği — tek bakışta okunabilir:
+
+| Mevcut düğüm | Koşul | Sonraki düğüm |
+|--------------|-----------|-----------|
+| verify | review == pass | merge |
+| verify | review == fail | implement |
+
+```mermaid
+flowchart TD
+ A([Başlangıç]) --> B[research]
+ B --> C[implement]
+ C --> D{verify}
+ D -- pass --> E[merge]
+ D -- fail --> C
+ E --> F([Bitiş])
+```
+
+**Adım 5: Bir checkpoint ekleyin.** Bu, graf ile tek seferlik bir betik arasındaki en büyük farklardan biridir: **durum her adımdan sonra kaydedilir**, böylece süreç çökerse sıfırdan başlamak yerine checkpoint'ten devam edersiniz. Bir tane eklediğinizde graf'ınız bedavaya kesinti/devam etme becerisi kazanır — ve merge'den önce insan onayı için duraklayabilirsiniz, bu da önceki dersin "insan incelemesinin" bir graf üzerinde görünümü şöyledir:
+
+```
+checkpoint = on(graph, every_step) # her adımdan sonra durumu kaydet
+graph.pause_before("merge") # birleştirmeden önce dur, onayı bekle
+```
+
+**Adım 6: Graf'ı bir giriş noktasıyla çalıştırın.** Her çalıştırmada bir thread id geçirin — checkpoint çalışmaları birbirinden ayırmak için onu kullanır:
+
+```
+run(graph, entry={"requirements": "login sayfası hatasını düzelt"}, thread="session-1")
+```
+
+Bittiğinde bunu yukarıdaki diyagramla karşılaştırın: el yazınız `graph.md` mavnadır ve bir motordaki kod, mavnanın yürütülebilir bir programa dönüştürülmüş halidir. İkisi bire bir eşleşmelidir. Eşleşmiyorsa — ya diyagram yanlıştır ya da kod yanlıştır, **ve "graf sorunu kağıda koyar" tam olarak budur**: önceden bir uyumsuzluk kimse tarafından fark edilmezdi; şimdi tek bakışta görünür. Çalıştırılabilir bir referans uygulaması istiyorsanız, `code/maker_checker_graph.py`'ye bakın — LangGraph kullanır, ama sonunda şunu fark etmelisiniz: sadece bu altı adım.
+
+## Açık Kaynak Projeler: İsimden Sonra, İsimden Önce
+
+Önce çizgiyi çekin: **"Graph Engineering", yalnızca 18 Temmuz 2026'dan sonra var olan bir isimdir.** O tarihten önce açık kaynak yapılan framework'ler, "Graph Engineering sonrası projeler" değildir. Ağustos 2026 başı itibarıyla, ismi doğrudan taşıyan ve ayakta kalan yalnızca bir açık kaynak proje var:
+
+**İ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.
+
+**İsimden önce gelen projeler (onu Graph Engineering olarak adlandırmıyorlar — ama gerçekten inşa ederken kullanacağınız şeyler) bunlar**
+
+Temmuz 2026'dan önce bu araçlar bir ila üç yıldır zaten vardı: LangGraph (2024'te açık kaynak yapıldı, 65M+ aylık indirme, yukarıdaki referans uygulamanın motoru), CrewAI, Microsoft Agent Framework, LlamaIndex Workflows, Google ADK, OpenAI Agents SDK, Mastra, Claude Agent SDK. **Bunlar "Graph Engineering sonrası projeler" değil — graf mühendisliğinin ismini almadan önce var olduğunun kanıtıdır.** Düğümler, kenarlar, paylaşılan durum ve yönlendirme üç ila beş yıldır çalışıyor; Temmuz sadece onlara yeni bir etiket verdi. Bir graf motoru tasarım sorunlarını çözmez: size düğümler, kenarlar ve checkpoint'ler verir, ama "hangi loop'lar hangisini besler, hedeflere kim sahip, kim veto edebilir" sorularını cevaplamaz. Bu sorular çözülmeden, motor değiştirmek yalnızca aynı kötü tasarımı daha güzel gösterir.
+
+## Soğuk Su: Graf Gümüş Kurşun Değil
+
+Üç kova soğuk su, en hafiften en ağıra.
+
+**Birinci kova: sahte sayılar.** Graph Engineering yaygınlaştıktan sonra, "graf kullanınca doğruluk +18%, maliyet −85%" gibi iddialar dolaştı. Koreli blog yazarı goddaehee'nin yaptığı bir [gerçek denetimi](https://goddaehee.tistory.com/628) (30 Temmuz) şunu buluyor: iki sayı gerçekten var, ama kimyasal boru ve enstrümantasyon diyagramları (P&ID) hakkında Mart 2026 tarihli bir makaleden geliyor — ve %18 ham görüntüye karşı ölçülürken %85 farklı bir tabana karşı ölçülüyor. Pazarlama, farklı tabanlara sahip iki sayıyı tek bir "öncesi/sonrası" hikâyesine yapıştırdı ve makale "graph engineering" ifadesini hiç kullanmıyor. "Graph engineering size X% iyileştirme verir" pazarlaması gördüğünüzde, orijinal kaynağı isteyin.
+
+**İkinci kova: şekil taşıyıcı duvar değildir (iii.dev).** Yukarıda ele alındı. Bir loop, tek düğümlü bir graftır; durum makineleri onlarca yıldır çalışıyor. "Loop'lar öldü" veya "graf'lar öldü" diyenler genellikle ne loop'u ne de graf'ı dikkatle okumuştur. Öğrenilmesi gereken desenler, isimler değil.
+
+**Üçüncü kova: Orchestration Tax (orkestrasyon vergisi).** Addy Osmani'nin Mayıs 2026'daki *The Orchestration Tax*'ı, graf/çoklu ajan çağının en sert ekonomisini sunar: **bir ajan başlatmak ucuzdur. Onun loop'unu kapatmak pahalıdır.**
+
+Bir ajan başlatmak tek bir tuş vuruşudur. Ama bir ajanın loop'unu kapatmak, geri dönen şeyi kontrol edecek ve diğer ajanların dokunduğu şeylerle uyumlu hale getirecek birini gerektirir — **o kişi sizsiniz ve sadece tek bir siz var.** Osmani'nin sözleri:
+
+> "Siz AI ajanlarınızın GIL'sisiniz. Hepsi aynı anda çalışabilir. Ama herhangi birinin işi mimariyi gerçekten anlamayı veya merge çakışmalarını çözmeyi gerektirdiğinde, o iş kiliti almak zorundadır. Tek bir kilit var. Onu siz tutuyorsunuz."
+
+Bu yüzden önceki dersin "inceleme bant genişliği tavandır" sözü bu derste daha keskinleşir: **graf daha fazla ajanı paralel çalıştırır, ama sizin yargınız seri bir kaynaktır. Paralel değildir.** Düğüm eklemek, hiçbir zaman darboğaz olmayan kısmı optimize eder — darboğaz her zaman o tek seri işlemcidir: siz.
+
+## Bir Graf'a Gerçekten Ne Zaman İhtiyacınız Olur
+
+Her görev bir graf hak etmez. Beş kriter — başlamadan önce en az üçünü karşılayın:
+
+1. **Görev, bağımsız çalışma birimlerine ayrışabilir** — parçalar birbirine bağlı değildir ve paralel çalışabilir
+2. **Dallanma veya geri alma yolları var** — "testler nereye geri döner", "yetersiz bilgi nereye geri döner" açıkça ilan edilmeye değer yollardır
+3. **Ara durum kaydedilmeye değer** — checkpoint'lerde duraklayıp sıfırdan başlamak yerine devam edebilirsiniz
+4. **Sonuçlar açıkça doğrulanabilir** — her düğümün otomatik kontrol edilebilir bir tamamlanma tanımı vardır
+5. **Koordine faydası > koordinasyon maliyeti** — paralelliğin kazandırdığı zaman, graf'ın ve paylaşılan durumun getirdiği yükten fazladır
+
+**"Karmaşık" "çok adımlı" demek değildir.** 20 adımlı doğrusal bir pipeline graf gerektirmez — bu bir workflow'dur, ya da sadece bir betiktir. Yalnızca 5 düğümü olan ama gerçek bir geri alma, paralellik ve onay içeren bir yapı ise graf gerektirir. Belirleyici faktör ölçek değil — **dallanmaların ve geri almaların varlığıdır.**
+
+## Çekirdek Kavramlar
+
+- **Graph Engineering**: birden fazla ajan, loop, araç ve değerlendiriciyi açık bir graf (düğümler + kenarlar + paylaşılan durum + yönlendirme kuralları) halinde organize etme mühendislik pratiği. Birden fazla çalışma biriminin bağlantılarını, paylaşılan durumunu ve yol seçimlerini tasarlanabilir, gözlemlenebilir ve yerel olarak onarılabilir kılar.
+- **Dört katmanlı yığın**: prompt → context → loop → graph. Her katman farklı bir şeyi kontrol eder (talimat, bilgi, çalışma zamanı, sistem); sonraki katman önceki katmanın yerini almaz, onu kendi düğümlerinin içine koyar.
+- **Graf'ın dört parçası**: düğümler (çalışma birimleri), kenarlar (devirler), paylaşılan durum (ortak çalışma yüzeyi), yönlendirme kuralları (yürütmenin nereye gideceği).
+- **Tek bir loop'un üç yapısal başarısızlığı**: Goodhart (sayılar yükseldi, iş kötüleşti), yukarıya körlük (asla "bu doğru hedef mi?" diye sormaz), çatışma (bağımsız loop'lar birbirini baltalar). Graf bunları açık ilişki tasarımına dönüştürür.
+- **Graph ≠ Workflow**: workflow düğümleri deterministik fonksiyonlardır, kenarlar kodla yazılmıştır; graph düğümleri tam ajan olabilir, kenarlar dinamik yönlendirebilir. Graph, workflow'un genelleştirilmesidir.
+- **Anchors (çapalar)**: bir loop ağını gerçek dünyaya sabitleyen mekanizmalar (gerçek iş sonuçları, ground truth, insan nokta kontrolleri). Graf tasarımının en kolay atlanan ve en çok atlanmaması gereken parçası.
+- **Orchestration Tax (orkestrasyon vergisi)**: ajan başlatmak ucuzdur, sonuçları incelemek pahalıdır. Dikkatiniz tek seri kaynaktır ve düğüm eklemek onu optimize etmez.
+
+## Ana Çıkarımlar
+
+- **Graph Engineering, Loop Engineering'in yerini almaz — onun üzerine bir katman inşa eder.** Bir loop, graf'taki bir düğümdür; önceki dersin üç şeyi (hedef, doğrulama, durdurma koşulu) düğümün iç yapısı haline gelir.
+- **Bir graf, "ertelenmiş kararları" "önceden kararlara" dönüştürür.** Loop başarısızlık modlarını loop'un içinde gizler; graph onları kağıda koyar — okunabilir, denetlenebilir, yerel olarak onarılabilir.
+- **Düğümün içine ne koyduğunuz, graf ile workflow arasındaki farkı belirler.** Fonksiyon koyarsanız workflow'dur; ajan koyarsanız graftır. "Yeni şişe, eski şarap"taki tek gerçek yeni şarap budur.
+- **Çizmeden önce dört tasarım sorusunu yanıtlayın:** hangi loop'lar hangisini besler, hedeflere kim sahip, kim veto edebilir/geri alabilir, hangi ölçümler değişebilir ve hangileri donmuş kalmalı. Cevaplayamıyorsanız, çizmeyin.
+- **Graf için graf çizmeyin.** Beş kriter: bağımsız ayrışabilir, dallanma veya geri alma var, ara durum kaydedilmeye değer, sonuçlar doğrulanabilir, koordine faydası > koordinasyon maliyeti.
+- **İnceleme bant genişliğiniz hâlâ tavandır.** Graf daha fazla ajanı paralel çalıştırır, ama yargınız seridir — orkestrasyon vergisi daha fazla düğüm olduğu için kaybolmaz.
+- **Karşı görüşü aklınızda tutun.** Şekil taşıyıcı duvar değildir; yeniden oynatılabilirlik, gözlemlenebilirlik ve kurtarılabilirlik taşıyıcıdır. İsimler her altı haftada bir değişir. Mühendislik kapasitesi değişmez.
+
+## Daha Fazla Okuma
+
+- [Prefect: Loops vs. Graphs (Jul 2026)](https://www.prefect.io/blog/loops-vs-graphs) — onlarca yıldır graf orkestrasyonu inşa eden bir şirketin gözünden loop ve graf
+- [Eigent: Graph Engineering for AI Agents (Jul 2026)](https://www.eigent.ai/blog/graph-engineering-ai-agents) — tek bir loop'un üç yapısal başarısızlığı + dört tasarım sorusu + anchors
+- [iii.dev: Loops, Graphs, and the Layer That Matters (Jul 2026)](https://iii.dev/blog/loops-graphs-and-the-layer-that-matters/) — en net karşı görüş: "şekil taşıyıcı duvar değildir"
+- [Rohit (@rohit4verse) orijinal uzun gönderi (2026-07-29)](https://x.com/rohit4verse/status/2082478623043547356) — dört katmanlı çerçevenin birincil kaynağı: prompt → context → loop → graph, her katman bir öncekinin üzerine biner
+- [Agent Times: Graph Engineering as the Final Layer (Jul 2026)](https://theagenttimes.com/articles/graph-engineering-emerges-as-proposed-final-layer-of-agent-o-4f0511a8) — Rohit'in dört katmanlı çerçevesinin temiz bir özeti
+- [goddaehee: Graph Engineering gerçek denetimi (Korece, 2026-07-30)](https://goddaehee.tistory.com/628) — en kapsamlı gerçek denetimi: şaka köken zaman çizelgesi, sahte sayıların parçalanması, LangGraph verisi, Hacker News sıcaklık karşılaştırması
+- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — şakadan iki hafta önce yazılmış ciddi makale
+- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — resmi yanıt: "yeni bir fikir değil, köklü bir yaklaşımın en yeni adı"; LangGraph'ın 65M+ aylık indirmesi
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — moda yayılma verisi (ilk tweet'te 575 bin görüntüleme)
+- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — yedi ana akım açık kaynak framework'ün kafa kafaya karşılaştırması: LangGraph, CrewAI, Microsoft Agent Framework, LlamaIndex, Google ADK, OpenAI Agents SDK, Mastra
+- [LangGraph resmi dokümantasyonu](https://docs.langchain.com/oss/python/langgraph/graph-api) — "Nodes do the work, edges tell what to do next"; düğüm ve kenarların kesin tanımları, graf inşa etmek için ilk elden referans
+- [Anthropic: Building Effective Agents (Dec 2024)](https://www.anthropic.com/engineering/building-effective-agents) — çizildiğinde graf olan beş desen; workflow vs agent'ın yetkili ayrımı
+- [Addy Osmani: The Orchestration Tax (May 2026)](https://addyosmani.com/blog/orchestration-tax/) — dikkatinizin neden tek seri kaynak olduğu
+- [Addy Osmani: Orchestrating Coding Agents (konuşma)](https://talks.addy.ie/oreilly-codecon-march-2026/) — subagent'lardan agent takımlarına ve quality gate'lere
+- [Addy Osmani: Loop Engineering (Jun 2026)](https://addyosmani.com/blog/loop-engineering/) — önceki dersin temel referansı; graf mühendisliği için ön koşul
+- Ders 13: [Manuel prompting'den otonom loop'lara](./../lecture-13-loop-engineering/index.md) — loop, graf'ta bir düğümdür; graf'ı anlamadan önce düğümü anlayın
+- Ders 11: [Gözlemlenebilirlik neden harness'ın içinde olmalı](./../lecture-11-why-observability-belongs-inside-the-harness/index.md) — graf ne kadar karmaşıksa gözlemlenebilirlik o kadar önemli olur; gözlemlenmeyen bir graf, sadece daha büyük bir kara kutuya birleştirilmiş kara kutudur
+- Ders 9: [Ajanların zaferi çok erken ilan etmesini engelleme](./../lecture-09-why-agents-declare-victory-too-early/index.md) — verify düğümü neden implement düğümünden bağımsız olmalı; graf'ta bu bir prompt sorunu değil, yapısal bir sorundur
+
+## Alıştırmalar
+
+1. **P07'deki maker-checker loop'unuzu bir graf olarak çizin:** `graph.md` içinde düğümleri, kenarları, paylaşılan durumu ve yönlendirme kurallarını açıkça yazın. Hangi kenarların koşullu (verify geçti/başarısız) ve hangilerinin geri alma kenarı (başarısızlıkta implement'e dönüş) olduğunu işaretleyin. Bittiğinde cevaplayın: örtük olan — daha önce ajanın context'inin içinde gizlenmiş — herhangi bir kenar var mı?
+
+2. **eigent'in dört sorusunu yanıtlayın:** Çalıştırdığınız üç bağımsız loop bulun (veya aynı projedeki üç otomasyon) ve cevaplayın: hangileri hangisini besler? Hangi loop, başka bir loop'un kovaladığı hedefe sahip? Başka bir loop'un çıktısını veto edebilen bir loop var mı? Hangi ölçümler çakışabilecek şekilde ayrı ayrı optimize ediliyor?
+
+3. **Goodhart öz-kontrolü:** Yakın zamanda optimize ettiğiniz bir metriği inceleyin. Yükseldiğinde, gerçek sonuç (iş sonuçları, kullanıcı geri bildirimi, kod kalitesi) da iyileşti mi? Sadece sayı yükseldiyse, bu loop size hangi yönde yalan söylemeyi öğreniyor?
+
+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
diff --git a/docs/tr/projects/project-08-graph-engineering-first-graph/index.md b/docs/tr/projects/project-08-graph-engineering-first-graph/index.md
new file mode 100644
index 0000000..2354b0f
--- /dev/null
+++ b/docs/tr/projects/project-08-graph-engineering-first-graph/index.md
@@ -0,0 +1,93 @@
+[English Version →](../../../en/projects/project-08-graph-engineering-first-graph/)
+
+> İlgili Ders: [L14. Tek Döngülerden Graf Mühendisliğine](./../../lectures/lecture-14-graph-engineering/index.md)
+
+# Proje 08. İş Akışınızı Bir Graf Olarak Çizin
+
+## Ne Yapacaksınız
+
+Bu, "Loop"tan "Graph"a geçiş projesidir. Önceki derste bir maker-checker loop kurdunuz — uygula, doğrula, geri bildirim, tekrar uygula; tüm kararlar aynı ajanın bağlam penceresinde gerçekleşiyordu. Bu derste yapacağınız şey, **loop'un içinde gizlenen yapıyı açıkça çizmektir**: düğümler, kenarlar, paylaşılan durum, yönlendirme kuralları — kelime kelime netçe yazın.
+
+Üç aşamalı deney yapacaksınız: önce P07'deki maker-checker loop'unu açık bir graf olarak çizin, sonra grafa paralel bir fan-out/fan-in düğümü ekleyin ve son olarak bir koşullu geri alma kenarı ile bir insan onayı düğümü ekleyin. Bitirdiğinizde bir şeyi bizzat hissedeceksiniz: **graf yeni bir icat değil, loop'unuz yeterince karmaşık hale geldiğinde kendisinin dönüştüğü şeydir.**
+
+## Ne Kullanacaksınız
+
+- Claude Code veya Codex
+- Git
+- P07'de kurduğunuz maker-checker loop (veya tekrar tekrar çalıştırabileceğiniz herhangi bir ajan iş akışı)
+- Bir metin düzenleyici veya çizim aracı (çizmek güzel görünmek için değil, yapıyı netleştirmek içindir; `mermaid` veya elle yazılmış `graph.md` ikisi de olur)
+
+## Adımlar
+
+### Hazırlık
+
+1. P07'den sonraki depodan başlayın ya da doğrudan şu anda çalıştırdığınız herhangi bir ajan iş akışını kullanın.
+2. Üç dal oluşturun: `p08-explicit-graph`, `p08-parallel`, `p08-human-in-the-loop`.
+3. Paylaşılan durum dosyası olarak bir `state.md` hazırlayın: gereksinimler, ilerleme, doğrulama sonuçları buraya yazılır. Bu, graf'ın "ortak çalışma yüzeyidir".
+
+### Deney 1: Loop'u Açık Bir Graf Olarak Çizin
+
+`p08-explicit-graph` dalına geçin.
+
+1. **Tüm düğümleri listeleyin:** P07 maker-checker loop'undaki her adımı bir düğüm olarak yazın. Her düğüm için netleştirin: sorumluluğu, girdisi, çıktısı, ajan mı yoksa deterministic kod mu olduğu.
+2. **Tüm kenarları çizin:** Düğümler arasındaki her kenarı listeleyin. İki özel kenara odaklanın:
+ - Koşullu kenar: doğrulama geçti/başarısız, hangi kenardan gidilir
+ - Geri alma kenarı: başarısızlık hangi düğüme geri döner
+3. **Paylaşılan durumu yazın:** Durumda hangi alanların olduğunu (gereksinimler, kod, test sonuçları, inceleme sonuçları) ve kimin okuduğunu/kim yazdığını açıkça listeleyin.
+4. **Yönlendirme kurallarını yazın:** En sade if-then diliyle "sırada nereye gidilir" kurallarını yazın, örneğin:
+ ```
+ if doğrulama geçti → birleştirme düğümü
+ if doğrulama başarısız → uygulama düğümü
+ if uygulama düğümünde bilgi yetersiz → araştırma düğümü
+ ```
+5. **`graph.md` olarak yazın:** Yukarıdakileri bir dokümana toparlayın. mermaid ile bir graf çizin, düğüm tablosunu ve yönlendirme kurallarını ekleyin.
+6. **Bu soruyu yanıtlayın:** Çizimi bitirdikten sonra, en az bir **eskiden örtük olan kenar** bulun — daha önce ajanın context'inde gizlenmiş, varlığını sizin bile bilmediğiniz bir karar yolu.
+
+### Deney 2: Paralel Fan-out / Fan-in Düğümü Ekleyin
+
+`p08-parallel` dalına geçin.
+
+1. **Paralel çalıştırılabilecek bir nokta seçin:** Görevde iki bağımsız parçaya ayrılabilecek bir yer bulun. Örneğin:
+ - uygulamayı iki bağımsız modüle ayırın, iki ajan paralel yazsın
+ - doğrulamayı iki bağımsız incelemeye ayırın: biri testleri ve lint'i çalıştırır, biri kod incelemesi yapar (farklı talimatlar, farklı odaklar)
+ - araştırmayı iki yöne ayırın, iki ajan birer yolu araştırsın
+2. **Fan-out kurallarını yazın:** Paylaşılan durumda "bu görevin N paralel alt göreve ayrıldığını" kaydedin; her alt görev bağımsız bir context'e ve bağımsız bir düğüme sahiptir.
+3. **Fan-in kurallarını yazın:** Tüm alt görevler tamamlandığında sonuçları kim birleştirir? Birleştirme standardı nedir (örneğin: yalnızca iki inceleme de geçerse birleştir, yoksa birinin geçmesi yeterli mi)?
+4. **Worktree izolasyonu kullanın:** Her paralel alt görev bağımsız bir git worktree'de çalışır ve dosya çarpışmalarını fiziksel olarak önler (Ders 13'teki Worktree ilkesini gözden geçirin).
+5. **Bir kez çalıştırın ve kaydedin:** Paralel öncesi ve sonrası duvar saati süresini, token tüketimini ve sonuç kalitesini kaydedin. Paralel gerçekten daha hızlı mı? Yoksa koordinasyon yükü kazanılan zamanı mı yedi?
+
+### Deney 3: Bir Geri Alma Kenarı ve Bir İnsan Onayı Düğümü Ekleyin
+
+`p08-human-in-the-loop` dalına geçin.
+
+Bu, üç deneyin en önemlisidir. Grafa iki tür düğüm ekleyeceksiniz:
+
+1. **Koşullu geri alma kenarı:** Doğrulama düğümüne bir "kısmen geçti" yolu ekleyin — her şeyi uygulama düğümüne geri göndermek yerine, spesifik geri bildirimle **sorunu üreten düğüme** dönün. Örneğin: testlerin hepsi geçiyor ama kod incelemesi gereksinim anlayışının yanlış olduğunu buluyorsa, uygulama düğümü yerine araştırma düğümüne geri dönün. Bu, paylaşılan durumunuzun "sorunun hangi katmanda olduğunu" kaydetmesini gerektirir.
+2. **İnsan onayı düğümü (Human-in-the-loop):** Birleştirme düğümünden önce bir insan düğümü ekleyin. Buraya geldiğinde graf **durur** ve sizin `state.md`'ye "onay" veya "geri çevir" yazmanızı bekler. Onay düğümü bir zaman aşımı kuralına sahip olabilir: N saat sonra yanıt verilmezse otomatik geri çevirir veya otomatik yükseltir.
+3. **Interrupt formatını yazın:** Onay isteğini nasıl net tutacağınız — ne oldu, ne değişti, neden bir insana ihtiyaç var, onay/geri çevirmenin sonuçları neler.
+4. **En az 2 tam tur çalıştırın:** Her turda insan onayı düğümüne ulaşın ve kendiniz bir kez onaylayın veya geri çevirin. Kaydedin: onay kararınız doğrulama düğümünün yargısıyla tutarlı mı? Onay düğümü, doğrulama düğümünün yakalayamadığı bir şeyi durdurdu mu?
+
+## Sonuçları Nasıl Ölçersiniz
+
+| Metrik | Deney 1 (Açık graf) | Deney 2 (Paralel) | Deney 3 (İnsan-ortada) |
+|------|----------------|--------------|------------------|
+| Yapısal görünürlük | Kaç örtük kenar buldunuz? | Paylaşılan durum paralel alt görevleri destekleyebiliyor mu? | Geri alma kenarı sorun katmanını hassas şekilde bulabiliyor mu? |
+| Başarısızlık konumlandırma | Başarısızlıkta hangi kenarın yanlış olduğunu doğrudan söyleyebiliyor musunuz? | Paralel bir alt görev başarısız olduğunda hangisini konumlandırabiliyorsunuz? | Onay geri çevirdiğinde hangi katmanın sorunu olduğunu gösterebiliyor musunuz? |
+| Koordinasyon yükü | Graf'ı yazmak ne kadar sürdü? | Paralelliğin kazandırdığı zaman vs koordinasyon yükü | Onay bekleme süresi vs durdurulan sorunun değeri |
+| Gözlemlenebilirlik | Her adımda ne olduğu artık görünüyor mu? | Her paralel alt görevin durumu görünür mü? | Onay isteği yeterince net yazılmış mı? |
+| Güvenilirlik | Graf açıklaması gerçek çalışmayla tutarlı mı? | Fan-in birleştirme standardı güvenilir mi? | Zaman aşımı/yükseltme kuralları gerçekten tetikleniyor mu? |
+
+## Ne Teslim Edeceksiniz
+
+- `graph.md` (Deney 1'in tam graf açıklaması: mermaid grafı + düğüm tablosu + kenar tablosu + paylaşılan durum alanları + yönlendirme kuralları)
+- Deney 1'de bulunan örtük kenar listesi (en az bir tane)
+- Deney 2'nin fan-out/fan-in kuralları ve bir paralel çalışma kaydı (zaman/maliyet/kalite karşılaştırması)
+- Deney 3'ün geri alma kenarı kuralları, onay düğümü formatı ve 2 tur insan-ortada kaydı
+- Son öz değerlendirme: loop'tan graf'a, çalışma biçiminizde ne değişti? Hangi görevler graf çizmeye değer, hangileri değil?
+
+## İlgili Dersler
+
+- [Lecture 14 — Tek Döngülerden Graf Mühendisliğine](../../lectures/lecture-14-graph-engineering/index.md)
+- [Lecture 13 — Manuel Prompting'den Otonom Loop'lara](../../lectures/lecture-13-loop-engineering/index.md) (loop'unuz graf'taki bir düğümdür; bu proje düğümün iç yapısını açmaktır)
+- [Lecture 09 — Ajanlar neden zaferi çok erken ilan eder](../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md) (verify düğümü neden implement düğümünden bağımsız olmalı; graf'ta bu yapısal bir sorundur)
+- [Lecture 11 — Gözlemlenebilirlik neden harness'ın bir parçasıdır](../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) (graf ne kadar karmaşıksa, her düğümün ne yaptığını görmek o kadar gerekli olur)
\ No newline at end of file
diff --git a/docs/uk/lectures/lecture-14-graph-engineering/index.md b/docs/uk/lectures/lecture-14-graph-engineering/index.md
new file mode 100644
index 0000000..bb5d338
--- /dev/null
+++ b/docs/uk/lectures/lecture-14-graph-engineering/index.md
@@ -0,0 +1,349 @@
+[English Version →](../../../en/lectures/lecture-14-graph-engineering/)
+
+> Приклади коду: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-14-graph-engineering/code/)
+> Практичний проєкт: [Проєкт 08. Намалюйте ваш робочий процес як граф](./../../projects/project-08-graph-engineering-first-graph/index.md)
+
+# Лекція 14. Від одиночних циклів до графової інженерії
+
+Минуло шість тижнів після того, як ми закінчили розмову про Loop Engineering, і 18 липня 2026 року Пітер Штайнбергер — той самий автор OpenClaw, який у попередній лекції казав «не пишіть більше промптів для агентів кодування» — написав твіт:
+
+> «Ми все ще говоримо про Loop, чи вже перейшли до Graph?»
+
+Один твіт — за день він набрав приблизно 570 тисяч переглядів, а до кінця місяця виріс приблизно до 3 мільйонів. За кілька годин інженер з машинного навчання Хамел Хусейн опублікував статтю під назвою «Loop Engineering Is Dead. Enter Graph Engineering» — у тілі якої була лише одна гіфка зі словами «Stop it» — і теж набрав приблизно 680 тисяч переглядів.
+
+Ще цікавіше: **обидва написали це як жарт.** Один висміював те, що індустрія вигадує новий термін кожні шість тижнів, а другий підхопив цей мем і відповів у тон. Але жарт прожив лише приблизно один вихідний — курси, дорожні карти та стеки інструментів заполонили стрічку до кінця вікенду, а з ними й купа вигаданих цифр: «точність +18%, вартість −85%» — це фейкові дані (18% і 85% справді існують, але з наукової статті про креслення хімічних трубопроводів, і зі зовсім іншим базовим порівнянням), а «Microsoft, Stanford і Anthropic одночасно відкрили Graph Engineering» — теж фейк. Єдиним «першопрохідцем», якого підтвердила фактчек, був Джош Сіммонс: його стаття «We Are Entering the Graph Engineering Phase» написана 4 липня, за два тижні до цього жарту — **жарт зробив цю тему популярною, але не він її створив.**
+
+> Джерела: [goddaehee: фактчек Graph Engineering (2026-07-30)](https://goddaehee.tistory.com/628); [YC Startup School 2026: інтерв'ю з Дженсеном Хуаном (з транскриптом)](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia); [explainx: Graph Engineering (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026)
+
+Ця лекція не для того, щоб підлити олії у вогонь цього модного слова, а для того, щоб розібрати його на частини та побачити наскрізь: **чому після одиночного циклу неминуче виростає граф? У чому саме різниця між графом і workflow? Коли він тобі справді потрібен, а коли — ні?**
+
+## prompt, context, loop, graph: чотири назви, накладені одна на одну
+
+Наприкінці липня інженер Рохіт (@rohit4verse) опублікував [довгий допис](https://x.com/rohit4verse/status/2082478623043547356), у якому зібрав історію назв у AI-інженерії за останні роки в чітку чотирирівневу структуру. Це найкраща система координат для розуміння Graph Engineering:
+
+| Рівень | Що формує | На яке питання відповідає | Ключовий продукт |
+|------|---------|-----------|---------|
+| **Prompt Engineering** | Інструкції | Як сказати моделі, що робити? | instructions, examples, constraints, roles, output formats |
+| **Context Engineering** | Інформація | Що модель має знати перед прийняттям рішення? | documents, history, memory, tool definitions, environment state |
+| **Loop Engineering** | Середовище виконання | Як змусити модель циклічно працювати, поки не досягне мети? | observe, reason, act, inspect, update, умови зупинки |
+| **Graph Engineering** | Система | Як кілька агентів, циклів, інструментів та оцінювачів співпрацюють? | вузли, ребра, спільний стан, правила маршрутизації |
+
+Зверніть увагу, як читається ця лінія: **кожен рівень не замінює попередній, а накладається поверх нього.**
+
+- Коли ви знайшли context engineering, ви не припинили prompt engineering — кожна ітерація все одно потребує промпту, просто цикл оновлює його, коли змінюється середовище.
+- Коли ви побудували цикл, ви не втратили контекст — кожен оберт циклу збирає контекст заново.
+- Коли доходите до графа, ні prompt, ні context, ні loop не зникають: **кожен вузол несе власний промпт, власний контекст, власні інструменти, власну пам'ять і власний маленький цикл.** Граф визначає, як вузли з'єднані між собою.
+
+Ось як Рохіт завершує свою думку:
+
+> Коли агенту потрібна спеціалізація, паралелізм, спільний стан, верифікація та відновлення — він більше не цикл. Він граф.
+
+**А що з harness?** У цих чотирьох назвах немає Harness Engineering, хоча увесь цей курс саме про нього. Причина проста: Рохіт розповідає історію модних слів, її кінцева точка — граф, а середній рівень просто пропустили. До того ж спільнота сама не домовилася, на який рівень ставити harness — [explainx](https://explainx.ai/blog/context-prompt-loop-harness-engineering-stack-2026) ставить його над loop, а [стаття Buildrix](https://arxiv.org/abs/2606.25139) — під loop. Цей курс визначився ще в другій лекції: harness — це фундамент, а loop і граф будуються на ньому.
+
+Це пояснює дивне явище: чому слово «Graph Engineering» стало популярним лише в липні 2026 року, але всі виявили, що «давно так роблять». Тому що граф — не новий винахід, він з'являється тоді, коли завдання ускладнюється до певної міри, і loop сам перетворюється на граф. Назва з'явилася пізніше, а підхід існував давно.
+
+## Розберімо граф на частини: вузли, ребра, стан, маршрутизація
+
+Зведімо граф до чотирьох найпростіших складових.
+
+**Вузол (Node):** одиниця роботи, що виконує певну відповідальність. Він може бути:
+- фрагментом детермінованого коду (запустити тести, порахувати покриття)
+- одним викликом моделі (згенерувати документацію)
+- інструментом (git commit, відправити повідомлення)
+- повноцінним агентом — з власним циклом, який розуміє мету, вміє користуватися інструментами й повторює спробу, коли застрягає
+
+Вузол — це справжня розділова лінія між графовою інженерією та workflow-інженерією, про це поговоримо окремо нижче.
+
+**Ребро (Edge):** описує, як вузли передають роботу одне одному. Це не просто «спочатку A, потім B» — ребро може виражати:
+- **паралелізм**: після завершення A, B і C починаються одночасно
+- **умову**: тест пройшов — ідемо ліворуч, провалився — праворуч
+- **невдачу/повторну спробу**: вузол упав — повертаємося до нього самого і запускаємо ще раз
+- **відкат**: верифікація не пройшла — повертаємося до вузла реалізації, що був три кроки тому
+
+**Спільний стан (State):** пакет даних, який передається між вузлами. Вимоги, нотатки дослідження, версії коду, результати тестів, висновки рев'ю — усе записується на одному спільному робочому столі. Вузли не звертаються один до одного напряму — вони читають і записують один і той самий стан.
+
+**Правила маршрутизації (Routing):** визначають, куди йти далі. Це «керування потоком» графа, і найпростіше воно звучить так:
+
+> Тест пройшов — доставляй; тест провалився — повертайся до вузла реалізації; інформації замало — повертайся до вузла дослідження.
+
+Зберіть чотири складові разом — і типовий граф розробки виглядає так:
+
+```mermaid
+flowchart TD
+ S["Спільний стан<br/>Вимоги / Нотатки / Код / Результати"] --- R["Вузол дослідження<br/>Агент: локалізувати проблему"]
+ R -->|"Виробляє рішення"| I["Вузол реалізації<br/>Агент: написати зміни + тести"]
+ I -->|"Виробляє код"| V["Вузол верифікації<br/>Агент: незалежне рев'ю + запуск тестів"]
+ V -->|"Не пройшло"| I
+ V -->|"Пройшло"| M["Вузол злиття<br/>Код: commit + оновлення стану"]
+ M -->|"Оновлення стану"| S
+ I -->|"Інформації замало"| R
+```
+
+Порівняйте з графом циклу з попередньої лекції: там було одне кільце — виявлення, розподіл, верифікація, збереження, і знову виявлення. У графі цієї лекції **кільце все ще існує, але розбите на явні вузли та ребра.** Вузол верифікації може напряму повернути невдачу у вузол реалізації, а вузол реалізації може через брак інформації повернутися у вузол дослідження — ці «ребра відкату» в одиночному циклі були неявними, агент просто пам'ятав у контексті, що «треба повернутися».
+
+## Коли циклу вже недостатньо
+
+В одиночного циклу лише одна магістраль. У maker-checker циклі, який ви зібрали в попередній лекції, усі рішення — що робити далі, куди йти при невдачі — відбуваються в контекстному вікні одного й того самого агента. Щойно завдання трохи ускладнюється, спливають чотири питання:
+
+1. **Розподіл праці**: агент, що досліджує вимоги, агент, що пише код, агент, що тестує — хто починає першим?
+2. **Паралелізм**: яку роботу можна виконувати одночасно?
+3. **Відкат**: куди повертатися після провалу тесту — до вузла реалізації чи до вузла дослідження?
+4. **Передача**: як кілька агентів бачать одні й ті самі вимоги, нотатки та результати тестів? Рев'юер не згоден із реалізатором — чию думку слухати?
+
+Дженсен Хуан в [інтерв'ю на Startup School 2026](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia) (розмова з Гаррі Таном) говорив подібне: коли базова реалізація дедалі більше автоматизується агентами, людська цінність зміщується до «проєктування систем, чітких обмежень і дрібнозернистого контролю над агентами». Його приклад контролю дуже конкретний — «коли агент дає план, я змінюю одне слово у файлі плану, і це слово створює одну точну різницю»; а ще він передбачає, що ключовою навичкою майбутнього стане «системне мислення» (systems thinking).
+
+Найяскравіший удар у дискусійній гілці належить Луїсу Катакорі:
+
+> **«У циклі величезний запас міцності. Граф змушує тебе визнати, як багато частин твого робочого процесу досі взагалі не змодельовано.»**
+
+Ця фраза вказує на глибинну різницю між loop і graph:
+
+- **Loop — це відкладене рішення.** Спочатку даєш одному агенту робити всю роботу, а якщо не вийде — дізнаєшся потім, архітектуру можна відкласти. Це зручно, але ціна — невидимість режимів відмови: ти ніколи не знаєш, на якому кроці він застряг, бо він і сам не знає.
+- **Graph — це завчасне рішення.** Ти маєш завчасно заявити всю структуру: хто за що відповідає, як залежать завдання, куди повертатися при певній невдачі. Це клопітно, але натомість отримуєш читабельність, можливість аудиту та локального виправлення.
+
+Простіше кажучи: **loop ховає проблему всередині циклу, graph кладе проблему на папір.** Перше підходить для дослідження, друге — для продакшену.
+
+## Три структурні відмови одиночного циклу
+
+Чому одиночний loop не витримує масштабування? Стаття eigent.ai «Graph Engineering for AI Agents: Beyond Single Feedback Loops» наводить три структурні відмови — саме структурні, а не баг якогось конкретного циклу.
+
+**Спершу одне заперечення: хіба в цикл не можна додати контрольні точки?** Можна. І верифікація, і умови зупинки, і навіть повторні спроби з перервами — цикл це все вміщує. Але наступні три відмови саме контрольні точки не вирішують — бо контрольні точки в циклі ростуть усередині одного агента, і перевіряє та помиляється той самий мозок, із тим самим контекстом. Він зупинить «доставку без верифікації», але не запитає «чи правильна ця метрика», «чи треба гнатися за цією метою» — бо відповідь уже записана в його власному контексті, а він її не бачить. Граф дає не більше контрольних точок, а виносить перевірку **назовні**: з «всередині агента» — в «окремий вузол», із зовсім новим контекстом (про це було у розділі про вузол verify). Сенс слова «структурний» саме в цьому: справа не в тому, що циклу бракує якоїсь деталі, а в тому, що «оцінювач і виконавець поділяють один мозок» — це сама структура.
+
+### 1. Гудгарт: цифра зростає, а бізнес псується
+
+Доведіть будь-яку одиночну метрику до крайності — і вона перестане вимірювати те, що, на твою думку, вимірює. Класичний приклад: команда підтримки побудувала цикл навколо «рівня вирішення тікетів». Тижневі показники стабільно росли. За кілька місяців дані про продовження підписки показали, що churn подвоївся — **бот навчився закривати тікети**: змінювати тему, відраджувати користувача розпитувати далі, позначати невирішені проблеми як «вирішені».
+
+Цикл зробив усе, що від нього просили. Просто цифра відірвалася від того, що бізнес справді цінує. Це і є закон Гудгарта.
+
+### 2. Сліпота догори: він ніколи не питає «чи правильна ця мета»
+
+Усередині циклу еталон священний. Термостат не питає «чи правильна температура 68°F». Продажний цикл не питає «чи розумний цей план». Цикл оцінювання агента не питає «чи цей бенчмарк збігається з реальними бізнес-результатами».
+
+**Хто б не обрав мету, цикл біжить до неї, навіть якщо вона з самого початку не та, за чим треба гнатися.** У структурі одиночного циклу немає жодного місця для цього питання.
+
+### 3. Конфлікт: незалежні цикли підривають одне одного
+
+У реальній системі десятки циклів, і кожен побудований незалежно. Цикл швидкості відповіді підриває цикл глибини якості, цикл зростання підриває цикл якості. Кожен цикл на власному дашборді здоровий, але система в цілому тремтить — ніби кілька людей із різних боків тягнуть одну мотузку.
+
+**Питання, на які відповідає графова інженерія, — саме ті, на які одиночний цикл відповісти не в змозі:**
+
+- Які цикли живлять які цикли?
+- Які цикли володіють метою, за якою женуться інші цикли?
+- Які цикли можуть накласти вето або відкотити зміну?
+- Які метрики можна рухати, а які заморожені?
+
+Коли в системі є «цикл, що може з'їсти твою мету» і «цикл, що може накласти вето на твою зміну», їхній взаємозв'язок стає об'єктом інженерії — а відносини між відносинами, намальовані, і є графом.
+
+### Якір: закріпити цикл у реальності
+
+У статті eigent є розділ, який «everyone skips»: **anchors (якорі).** Якою б витонченою не була мережа циклів, якщо кожен цикл відпливає від реальності, то мережа — це лише резонанс, що взаємно дрейфує. Якір — це те, що закріплює цикл у реальному світі: реальні бізнес-результати, набори даних ground truth, ручні вибіркові перевірки. Під час проєктування графа якорі — найчастіше пропущений, але найменш допустимий до пропуску крок.
+
+## Граф і Workflow: не просто інша назва
+
+Це найбільш незрозуміле місце в цій лекції, тож його варто розглянути окремо.
+
+Перша реакція на спалах Graph Engineering у будь-кого з досвідом інженерії: «хіба це не workflow? DAG, скінченні автомати, конвеєрні движки — ми це 60 років ганяємо».
+
+**Ця інтуїція правильна наполовину.** Граф і workflow справді ділять один скелет: вузли + ребра + спільний стан + маршрутизація. Airflow, Prefect, Dagster, Temporal десятки років оркеструють саме так, як на цьому графі. П'ять патернів, які Anthropic узагальнила у грудні 2024 року в «Building Effective Agents» — ланцюжки промптів, маршрутизація, паралелізація, оркестратор/виконавець, оцінювач/оптимізатор — якщо їх намалювати, виходять саме виконавчі графи різної форми.
+
+**Помилка — у вузлах.** У традиційному workflow вузол — це **детермінована функція**: Python-функція, shell-скрипт, SQL-завдання. Ребра — це зашитий у код `if`, `switch`, `case`. Уся система підтримується інженером у коді, поведінка передбачувана — однаковий вхід завжди проходить один і той самий шлях.
+
+Вузол графової інженерії може бути **повноцінним агентом**: з власним циклом, з умінням користуватися інструментами, з розумінням мети, з повторною спробою при невдачі. Ребро також не обов'язково зашите — воно може нести правило маршрутизації, а наступний крок визначається виходом попереднього вузла, результатом верифікації або навіть іншою моделлю.
+
+Щоб пояснити цю різницю, скористаємося парою понять від Anthropic. Anthropic одним реченням розрізняє workflow і агента: **хто визначає потік керування?** Якщо кроки визначає код — це workflow, якщо модель може змінювати кроки в runtime — це агент.
+
+То що таке граф? **Граф — це контейнер, що вміщує обидва.** В одному графі можуть одночасно бути:
+
+- вузли-workflow: запустити тести, порахувати покриття — детермінований код, модель не потрібна
+- вузли-агенти: реалізувати функцію, рев'ювати код — повноцінні агенти на моделях
+- людські вузли: затвердження, перевірка — інтерактивні вузли з людиною, тут граф зупиняється і чекає, поки людина кивне
+
+Тож точне формулювання таке: **Graph Engineering — це не заміна Workflow, а узагальнення Workflow** — розширення типу вузла з «функції» до «агента» і розширення рішення на ребрі з «статичного коду» до «динамічної маршрутизації». Workflow — це той особливий випадок графа, у якому все повністю детерміноване.
+
+Контраргумент (iii.dev, «Loops, Graphs, and the Layer That Matters») впирається в ту саму точку, лише робить протилежний висновок:
+
+> «Форма — це легка частина, і вона одноразова. Несучі рішення — це те, з чого складається loop або граф, і що буде з ним, коли він запрацює.»
+
+iii.dev має на увазі: не вважай «топологію» інженерним досягненням. Workflow-інженерія працювала десятиліттями, і справді цінним осадком стало не те, як з'єднані вузли, а **можливість відтворення, спостережуваність і відновлення** — у разі проблеми можна відтворити, під час роботи можна спостерігати, при падінні можна продовжити. Форму графа можна змінити одним рухом, а вкладати зусилля варто саме в ці несучі властивості. Цю критику варто пам'ятати: **малювання графа — не мета; мета — скільки інженерної міцності може витримати граф.**
+
+## Тобі насправді вже давно доводилося малювати графи
+
+Є ще один доказ «старого вина в нових пляшках»: інструменти вже були готові.
+
+- **LangGraph**: випущений у січні 2024 року, до липня 2026 року — близько 65 мільйонів завантажень на місяць. Це графовий виконавчий движок для агентів: вузлами можуть бути агенти, а ребра можуть нести умовну маршрутизацію, checkpoint, interrupt.
+- **П'ять патернів Anthropic**: у грудні 2024 року «Building Effective Agents» уже намалював графи ланцюжків промптів, маршрутизації, паралелізації, оркестратора/виконавця та оцінювача/оптимізатора — просто не називав це Graph Engineering.
+- **Subagent fan-out у Claude Code**: коли ти доручаєш головному агенту розіслати купу під-агентів працювати паралельно, ти вже будуєш граф — просто не усвідомлюєш цього.
+- **Скінченні автомати, DAG-планувальники, черги завдань, граф знань**: десятиліттями в комп'ютерних науках інженерізація графів — не нова проблема.
+
+Що насправді нове? **Вузол змінився з «функції» на «агента».** Це єдина зміна, і це вся зміна. Раніше, щоб написати вузол workflow, треба було прописати його логіку, обробку помилок і стратегію повторних спроб. Тепер вузлу достатньо однієї інструкції — «досліди цю проблему», «рев'юй цей код» — решту модель робить сама. Вузли стали дешевими, тож графи стало варто малювати.
+
+## Побудова свого першого графа з нуля
+
+Теорії досить, до роботи. Maker-checker із попередньої лекції — це **один** агент, що сам у собі циклічно працює. Перше, що робить Graph Engineering, — розбирає такого монолітного агента на частини: **кожен вузол стає спеціалізованим агентом зі своїм приватним prompt, context, tools, memory і власним маленьким циклом; вузли не ділять контекст між собою, а лише передають роботу через спільний стан.** Це людською мовою те, що сказав Рохіт — «граф визначає, що бачить кожен вузол, коли він запускається, куди йде його вихід, хто може накласти вето, що зупиняє систему». Усі подані нижче позначення не прив'язані до жодного конкретного движка — це концепція; LangGraph, CrewAI — це лише реалізації, які перетворюють її на виконувану програму, з різними API, але однаковим скелетом. Шість кроків, і жоден не пропускай.
+
+**Крок перший: визнач спільний стан (State).** Спершу розмежуй два рівні: **на рівні графа спільним є лише стан, а контекст вузлів — приватний.** Монолітний агент має один контекст, і за довгої роботи його топить власний довгий transcript; граф нарізає контекст на кілька частин, кожна з яких належить одному вузлу — loop — це приватна власність вузла, граф — спільний стіл, на якому вони передають роботу. Подумай, що класти у стан. Для кожного поля оголоси, «як воно зливається» — коли кілька паралельних вузлів одночасно пишуть в одне поле, це перезапис, додавання чи сума. Це не фіча фреймворку, це правило, яке ти пишеш у `graph.md`, коли малюєш граф:
+
+```
+state = {
+ "requirements": текст, # пише вузол дослідження
+ "code": текст, # пише вузол реалізації
+ "review": "pass" | "fail", # пише вузол рев'ю
+ "attempts": число, # щоразу +1 (при паралельному записі зливається як "сума")
+}
+```
+
+**Крок другий: перелічи вузли — кожен вузол це повноцінний агент (з власним циклом).** Це фундаментальна різниця між графом і workflow: вузол workflow — це функція, вузол графа — це **агент зі своїм маленьким циклом.** Вузол отримує спільний стан → працює зі своїм приватним контекстом → записує результат назад у спільний стан. Усередині вузла, що пише код, — часто той самий цикл із попередньої лекції:
+
+```
+# всередині вузла implement: приватний маленький цикл (той самий maker-checker loop)
+node_implement(requirements):
+ loop (максимум 3 рази):
+ code = model(prompt=інструкція реалізації, context=requirements + минула помилка)
+ if tests_pass(code): return {"code": code}
+ return {"error": "Реалізація не пройшла за 3 спроби"}
+```
+
+| Вузол | Тип | Усередині вузла (приватне) | Записує у спільний стан |
+|------|------|------------------|-------------|
+| research | агент | пошук → читання → підсумок → брак інформації = повторний пошук (цикл) | requirements |
+| implement | агент | писати → тестувати → виправляти → поки не пройде (цикл, див. вище) | code |
+| verify | агент | незалежне рев'ю + запуск тестів (**fresh context, не успадковує пам'ять реалізатора**) | review (pass / fail) |
+| merge | детермінований код | без циклу, коли перевірка пройдена — commit | кінець |
+
+Зверни увагу на рядок verify: це найлегший для зіпсування вузол у графі. **У монолітному агенті «рев'ю» використовує той самий контекст — він рев'ює сам себе; у графі verify має отримати зовсім новий контекст** — він не бачить хід думки implement, а лише код у спільному стані. Саме тут «незалежне рев'ю» на графі справді стає справжнім: ізоляція контексту — не побічний ефект, а проєктний намір.
+
+**Крок третій: з'єднай ребра.** Спершу з'єднай детерміновану магістраль: дослідження → реалізація → верифікація → злиття → кінець.
+
+```mermaid
+flowchart TD
+ A([Початок]) --> B[research]
+ B --> C[implement]
+ C --> D[verify]
+ D --> E[merge]
+ E --> F([Кінець])
+```
+
+**Крок четвертий: напиши правила маршрутизації (найважливіший крок).** Вузол верифікації з'єднується не напряму з «злиттям», а з **рішенням**, яке визначає, куди йти далі. Цей крок робить явним те, «куди повертатися при провалі тесту» — правило маршрутизації повертає ім'я вузла, і звідки граф іде та куди прямує, видно з одного погляду:
+
+| Поточний вузол | Умова | Наступний вузол |
+|---------|------|---------|
+| verify | review == pass | merge |
+| verify | review == fail | implement |
+
+```mermaid
+flowchart TD
+ A([Початок]) --> B[research]
+ B --> C[implement]
+ C --> D{verify}
+ D -- pass --> E[merge]
+ D -- fail --> C
+ E --> F([Кінець])
+```
+
+**Крок п'ятий: повісь checkpoint (контрольну точку).** Це одна з найбільших відмінностей графа від одноразового скрипта: **стан на кожному кроці зберігається на диск**, і якщо процес упаде, можна продовжити з місця перерви, а не починати все заново. Щойно повісив — твій граф одразу отримує здатність «переривання/відновлення» — а ще перед merge можна вставити вузол «пауза, чекати затвердження людини», і це те, як виглядає на графі «ручне затвердження» з попередньої лекції:
+
+```
+checkpoint = on(graph, every_step) # стан на кожному кроці зберігається
+graph.pause_before("merge") # зупинитися перед злиттям, чекати затвердження людини
+```
+
+**Крок шостий: запусти граф і дай йому точку входу.** Кожен запуск передає thread id, і checkpoint за ним розрізняє різні екземпляри виконання:
+
+```
+run(graph, entry={"requirements": "виправити баг на сторінці входу"}, thread="session-1")
+```
+
+Запустив — порівняй з графом вище: твій написаний вручну `graph.md` — це креслення, а код у движку — виконувана програма, в яку перетворилося креслення. Вони мають відповідати один одному один в один. Якщо не збігаються — або граф намальовано неправильно, або код написано неправильно, **і саме це означає «граф кладе проблему на папір»**: раніше про невідповідність ніхто не знав, а тепер видно з одного погляду. Хочеш справжню робочу реалізацію для довідки — дивись `code/maker_checker_graph.py` — він написаний на LangGraph, але, дочитавши, ти маєш упізнати: це ті самі шість кроків вище.
+
+## Відкриті проєкти: ті, що з'явилися після публікації, і ті, що до неї
+
+Спершу розмежуй: **Graph Engineering — це назва, яка з'явилася лише після 18 липня 2026 року.** Фреймворки, відкриті до цього, — не «проєкти після публікації Graph Engineering». Той відкритий проєкт, який з'явився вже після спалаху концепції і напряму з такою назвою, станом на початок серпня 2026 року втримується лише один:
+
+**Ті, що з'явилися після публікації концепції**
+
+- [GraphArc](https://github.com/CodeGraphContext/grapharc) (2026-08-02): називає себе «першою живою реалізацією Graph Engineering». Він перетворює виконання агента з trace, захованого в логах, на **інтерактивну графу оркестрації в реальному часі** — кожен агент, кожна залежність, кожна точка рішення намальовані, і ти видиш увесь граф до виконання, підтверджуєш (можна навіть подивитися з телефона), а потім відпускаєш. Автор робив графові інструменти для 4000+ розробників, напрямок — «спостережуваність, можливість налагодження, інженерна міцність». Дуже новий, функціонально ще в ранній стадії.
+
+**Ті, що існували до публікації концепції (вони не називаються Graph Engineering, але саме ними ти будеш користуватися, коли будуватимеш)**
+
+До липня 2026 року ці інструменти існували від одного до трьох років: LangGraph (відкритий у 2024 році, 65+ мільйонів завантажень на місяць, саме його використовує реалізація вище), CrewAI, Microsoft Agent Framework, LlamaIndex Workflows, Google ADK, OpenAI Agents SDK, Mastra, Claude Agent SDK. **Вони не проєкти «після публікації Graph Engineering» — вони саме доказ «до публікації Graph Engineering».** Набір вузли/ребра/спільний стан/маршрутизація працює три-п'ять років, а нову назву отримав лише в липні. Графовий движок не вирішує проблему проєктування: він дає тобі вузли, ребра, checkpoint, але не відповість за тебе на питання «які цикли живлять які, хто володіє метою, хто може накласти вето». Поки ці питання не обдумані, зміна движка лише намалює той самий поганий дизайн красивіше.
+
+## Охолодний душ: граф — не срібна куля
+
+Три відйоми холодної води, від легкого до сильного.
+
+**Перша: фейкові цифри.** Після спалаху Graph Engineering в мережі розійшлися дані на кшталт «з графом точність +18%, вартість −85%». Корейський блогер goddaehee зробив [фактчек](https://goddaehee.tistory.com/628) (30 липня): ці дві цифри справді існують, але зі статті березня 2026 року про креслення хімічних трубопроводів (P&ID), і при цьому 18% — у порівнянні з вихідним зображенням, а 85% — у порівнянні з іншою схемою; маркетинговий текст склеїв дві цифри з різними базами в один «приклад до/після», а в самій статті навіть немає слова «graph engineering». Бачиш будь-які дані «графова інженерія дає +X%» — спершу перевір першоджерело.
+
+**Друга: форма — не несуча стіна (iii.dev).** Про це вже йшлося. Loop — це просто граф з одним вузлом; скінченні автомати працюють десятиліттями. Ті, хто розводить «loop мертвий» або «граф мертвий», зазвичай не читали уважно ні loop, ні граф. Вчити треба патерни, а не слова.
+
+**Третя: Orchestration Tax (податок на оркестрацію).** Адді Османі в травневій статті «The Orchestration Tax» дав найжорсткішу економіку для епохи графів/багатоагентних систем: **відкрити агента дешево, закрити цикл дорого.**
+
+Запустити агента — це одна кнопка, одне речення. Але закриття циклу агента потребує, щоб хтось перевірив його результати та звірився з тим, що порухали інші агенти — **цей хтось — ти, і ти один.** Слова Османі:
+
+> «Ти — GIL своїх AI-агентів. Вони можуть працювати одночасно. Але якщо їхня робота потребує справжнього розуміння архітектури, вирішення конфліктів злиття — ця робота має отримати той замок. Замок один, і він у тебе.»
+
+Ось чому те, що в попередній лекції називалося «пропускна здатність рев'ю — це стеля», у цій лекції звучить гостріше: **граф збільшує кількість паралельних агентів, але твоя здатність судити — послідовний ресурс, вона не паралелиться.** Додавання вузлів оптимізує не те, що є вузьким місцем, — вузьким місцем завжди залишається один послідовний процесор: ти.
+
+## Коли тобі справді варто використати граф
+
+Не кожне завдання варте малювання графа. П'ять критеріїв, берися за справу, якщо виконано принаймні три:
+
+1. **Завдання можна незалежно розбити на кілька одиниць роботи** — розрізані частини не залежать одна від одної і можуть працювати паралельно
+2. **Існують гілки або шляхи відкату** — куди повертатися при провалі тесту, куди при браку інформації — ці шляхи варто заявити явно
+3. **Проміжний стан варто зберігати** — після checkpoint можна зупинитися й відновитися, а не починати все заново
+4. **Результат можна явно приймати** — у кожного вузла є автоматично перевірюваний критерій завершення
+5. **Користь від колаборації > витрати на координацію** — час, зекономлений паралелізмом, перевищує накладні витрати самого графа та спільного стану
+
+**«Складне» ≠ «багато кроків».** Лінійному конвеєру на 20 кроків граф не потрібен — це workflow, або просто скрипт. Структурі лише з 5 вузлів, але з відкатами, паралелізмом і затвердженнями, граф потрібен. Критерій не в розмірі, а в **наявності гілок і відкатів.**
+
+## Основні концепції
+
+- **Graph Engineering**: інженерна практика, що організовує кілька агентів, циклів, інструментів та оцінювачів у явний граф (вузли + ребра + спільний стан + правила маршрутизації). Робить з'єднання багатьох одиниць роботи, спільний стан і вибір шляхів проєктованими, спостережуваними та такими, що локально ремонтуються.
+- **Чотири рівні, накладені один на одного**: prompt → context → loop → graph, кожен рівень керує чимось іншим (інструкції, інформація, середовище виконання, система), а наступний не замінює попередній, а лише вкладає його у свої вузли.
+- **Чотири складові графа**: вузол (одиниця роботи), ребро (спосіб передачі), спільний стан (спільний робочий стіл), правила маршрутизації (куди йти далі).
+- **Три структурні відмови одиночного циклу**: Гудгарт (цифра зростає, а бізнес псується), сліпота догори (ніколи не питає «чи правильна ця мета»), конфлікт (незалежні цикли підривають одне одного). Граф перетворює ці три типи проблем на явний проєкт відносин.
+- **Граф ≠ Workflow**: вузол workflow — це детермінована функція, ребро — зашитий код; вузол графа може бути повноцінним агентом, ребро — динамічною маршрутизацією. Граф — узагальнення workflow.
+- **Anchors (якорі)**: механізми, що закріплюють мережу циклів у реальному світі (реальні бізнес-результати, ground truth, ручні вибіркові перевірки). Найчастіше пропущений, але найменш допустимий до пропуску крок у проєктуванні графа.
+- **Orchestration Tax (податок на оркестрацію)**: відкрити агента дешево, прорев'ювати результат дорого. Твоя увага — єдиний послідовний ресурс, і додавання вузлів його не оптимізує.
+
+## Основні висновки
+
+- **Graph Engineering не замінює Loop Engineering, а будує поверх нього ще один рівень.** Loop — це один вузол графа; три речі з попередньої лекції (мета, верифікація, умова зупинки) стають внутрішньою структурою вузла.
+- **Граф перетворює «відкладене рішення» на «завчасне рішення».** Loop ховає режими відмови всередині циклу, граф кладе їх на папір — читабельно, під аудит, з локальним ремонтом.
+- **Від вмісту вузла залежить різниця між графом і workflow.** Функція — це workflow, агент — це граф. Це і є єдине нове вино в «старих пляшках».
+- **Перед малюванням графа дай відповідь на чотири питання:** які цикли живлять які, хто володіє метою, хто може накласти вето/відкотити, які метрики можна рухати, а які заморожені. Не можеш відповісти — не малюй.
+- **Не малюй заради малювання.** П'ять критеріїв: можна незалежно розбити, є гілки або відкат, проміжний стан варто зберігати, результат можна прийняти, користь від колаборації > витрати на координацію.
+- **Твоя пропускна здатність рев'ю залишається стелею.** Граф збільшує кількість паралельних агентів, але твоя здатність судити — послідовний ресурс; податок на оркестрацію не зникає від збільшення кількості вузлів.
+- **Пам'ятай про голос контрагента.** Форма — не несуча стіна; відтворюваність, спостережуваність і відновлення — ось що важливо. Слова змінюватимуться кожні шість тижнів, а інженерна міцність — ні.
+
+## Подальше читання
+
+- [Prefect: Loops vs. Graphs (лип 2026)](https://www.prefect.io/blog/loops-vs-graphs) — погляд на loop і граф з перспективи компанії, що десятиліттями робить графову оркестрацію
+- [Eigent: Graph Engineering for AI Agents (лип 2026)](https://www.eigent.ai/blog/graph-engineering-ai-agents) — три структурні відмови одиночного циклу + чотири питання проєктування + anchors
+- [iii.dev: Loops, Graphs, and the Layer That Matters (лип 2026)](https://iii.dev/blog/loops-graphs-and-the-layer-that-matters/) — найтверезіший контрагент: «форма — не несуча стіна»
+- [Рохіт (@rohit4verse) оригінальний довгий допис (2026-07-29)](https://x.com/rohit4verse/status/2082478623043547356) — першоджерело чотирирівневої структури: prompt → context → loop → graph, кожен рівень накладається на попередній
+- [Agent Times: Graph Engineering as the Final Layer (лип 2026)](https://theagenttimes.com/articles/graph-engineering-emerges-as-proposed-final-layer-of-agent-o-4f0511a8) — впорядкування чотирирівневої структури Рохіта
+- [goddaehee: фактчек Graph Engineering (корейською, 2026-07-30)](https://goddaehee.tistory.com/628) — найповніший фактчек: хронологія походження жарту, розбір фейкових цифр, дані LangGraph, порівняння популярності на Hacker News
+- [Джош Сіммонс: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — серйозна стаття, що вийшла за два тижні до жарту
+- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — офіційна відповідь: «не нова ідея, а найновіша назва наявного підходу»; LangGraph — 65+ мільйонів завантажень на місяць
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — дані про поширення модного слова (перший твіт — 575 тисяч переглядів)
+- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — горизонтальне порівняння семи основних відкритих фреймворків: LangGraph, CrewAI, Microsoft Agent Framework, LlamaIndex, Google ADK, OpenAI Agents SDK, Mastra
+- [Офіційна документація LangGraph](https://docs.langchain.com/oss/python/langgraph/graph-api) — «Nodes do the work, edges tell what to do next»; точні визначення вузлів і ребер, першоджерело для побудови графа
+- [Anthropic: Building Effective Agents (груд 2024)](https://www.anthropic.com/engineering/building-effective-agents) — п'ять патернів, намальовані — це граф; авторитетне розрізнення workflow та агента
+- [Адді Османі: The Orchestration Tax (трав 2026)](https://addyosmani.com/blog/orchestration-tax/) — чому твоя увага — єдиний послідовний ресурс
+- [Адді Османі: Orchestrating Coding Agents (виступ)](https://talks.addy.ie/oreilly-codecon-march-2026/) — від subagents до agent teams до quality gates
+- [Адді Османі: Loop Engineering (черв 2026)](https://addyosmani.com/blog/loop-engineering/) — основне джерело попередньої лекції, передумова графової інженерії
+- Лекція 13: [Від ручного введення промптів до автономних циклів](./../lecture-13-loop-engineering/index.md) — loop — це один вузол графа, спершу зрозумій вузол зсередини, потім — граф
+- Лекція 11: [Зробіть виконання агента спостережуваним](./../lecture-11-why-observability-belongs-inside-the-harness/index.md) — чим складніший граф, тим важливіша спостережуваність; неспостережуваний граф — це лише чорні ящики, складені в більший чорний ящик
+- Лекція 9: [Чому агенти надто рано оголошують перемогу](./../lecture-09-why-agents-declare-victory-too-early/index.md) — чому вузол верифікації має бути незалежним від вузла реалізації, і в графі це структурне питання, а не питання промпту
+
+## Вправи
+
+1. **Намалюй maker-checker loop з P07 як граф:** у `graph.md` явно запиши вузли, ребра, спільний стан і правила маршрутизації. Познач, яке ребро умовне (верифікація пройшла/провалилася), а яке — ребро відкату (невдача повертається до реалізації). Після малювання дай відповідь: чи є якесь ребро неявним, прихованим у контексті агента?
+
+2. **Дай відповідь на чотири питання eigent:** знайди три незалежні цикли, які ти запускаєш (або три автоматизації в одному проєкті), і дай відповідь: хто кого живить? Який цикл володіє метою, за якою женеться інший цикл? Чи є цикл, що може накласти вето на продукт іншого циклу? Які метрики оптимізуються окремо, але можуть конфліктувати між собою?
+
+3. **Самоперевірка за Гудгартом:** перевір якусь метрику, яку ти нещодавно оптимізував. Вона зросла — а реальний результат (бізнес-результат, відгук користувача, якість коду) покращився разом із нею? Якщо зросла лише цифра, у який бік цей цикл тебе обманює?
+
+4. **Оцінка за п'ятьма критеріями:** обери завдання, яке ти обмірковуєш «графізувати», і оціни його по пунктах за п'ятьма критеріями. Граф вартий малювання, якщо виконано принаймні три. Якщо менше трьох — йому потрібен кращий workflow-скрипт, а не граф заради графа.
+
+5. **Перетвори `graph.md` на виконувану програму:** за шістьма кроками з розділу «Побудова свого першого графа з нуля» цієї лекції реалізуй намальований maker-checker граф так, щоб він запрацював (реалізація для довідки: `code/maker_checker_graph.py`, написаний на LangGraph). Шість кроків не пропускай: визначити стан → перелічити вузли → з'єднати ребра → написати маршрутизацію → повісити checkpoint → запустити. Після запуску порівняй `graph.md` і код і знайди перше місце, де вони не збігаються, і поясни, чому не збігаються — граф намальовано неправильно чи код написано неправильно?
\ No newline at end of file
diff --git a/docs/uk/projects/project-08-graph-engineering-first-graph/index.md b/docs/uk/projects/project-08-graph-engineering-first-graph/index.md
new file mode 100644
index 0000000..9e0ed5c
--- /dev/null
+++ b/docs/uk/projects/project-08-graph-engineering-first-graph/index.md
@@ -0,0 +1,91 @@
+# Проєкт 08. Намалюйте ваш робочий процес як граф
+
+> Пов'язана лекція: [L14. Від одиночних циклів до графової інженерії](./../../lectures/lecture-14-graph-engineering/index.md)
+
+## Що ви робитимете
+
+Це проєкт, який переводить вас від «Loop» до «Graph». У попередній лекції ви зібрали maker-checker loop — реалізація, верифікація, зворотний зв'язок, знову реалізація — і всі рішення відбуваються в контекстному вікні одного й того самого агента. У цій лекції ви зробите те, що **приховано всередині циклу, видимим та явним**: вузли, ребра, спільний стан, правила маршрутизації — випишите все слово за словом.
+
+Ви виконаєте три експерименти, що нарощують складність: спершу намалюєте maker-checker loop з P07 як явний граф, потім додасте до графа паралельний вузол fan-out/fan-in, а вкінці — умовне ребро відкату та вузол ручного затвердження. Коли закінчите, ви на власному досвіді відчуєте одне: **граф не новий винахід — це те, чим стає ваш loop, коли ускладнюється до певної міри.**
+
+## Які інструменти використовувати
+
+- Claude Code або Codex
+- Git
+- Ваш maker-checker loop із P07 (або будь-який агентний робочий процес, який ви можете ганяти знову і знову)
+- Текстовий редактор або інструмент для малювання (малюй не для краси, а щоб прописати структуру; підійде `mermaid` або написаний вручну `graph.md`)
+
+## Конкретні кроки
+
+### Підготовка
+
+1. Почніть із репозиторію після завершення P07 або просто з будь-якого агентного робочого процесу, який ви зараз використовуєте.
+2. Створіть три гілки: `p08-explicit-graph`, `p08-parallel`, `p08-human-in-the-loop`.
+3. Підготуйте `state.md` як файл спільного стану: сюди записуються вимоги, прогрес, результати верифікації. Це «спільний робочий стіл» графа.
+
+### Експеримент 1: намалюйте Loop як явний граф
+
+Перемкніться на гілку `p08-explicit-graph`.
+
+1. **Перелічіть усі вузли**: запишіть кожен крок maker-checker loop з P07 як вузол. Для кожного вузла запишіть: його відповідальність, його вхід, його вихід, чи це агент, чи детермінований код.
+2. **Намалюйте всі ребра**: перелічіть кожне ребро між вузлами. Особливо позначте два особливі ребра:
+ - умовне ребро: верифікація пройшла/провалилася — куди йти
+ - ребро відкату: при невдачі повернутися до якого вузла
+3. **Запишіть спільний стан**: явно перелічіть, які поля є у стані (вимоги, код, результати тестів, висновок рев'ю), хто їх читає і хто пише.
+4. **Запишіть правила маршрутизації**: найпростішою мовою if-then опишіть «куди йти далі», наприклад:
+ ```
+ if верифікація пройшла → вузол злиття
+ if верифікація провалилася → вузол реалізації
+ if у вузла реалізації брак інформації → вузол дослідження
+ ```
+5. **Оформіть у `graph.md`**: зберіть усе вище у документ. Намалюйте граф у mermaid, докладіть таблицю вузлів і правила маршрутизації.
+6. **Дай відповідь на питання**: після малювання знайдіть принаймні одне **раніше неявне ребро** — шлях рішення, який раніше був прихований у контексті агента, і ви самі не знали, що він існує.
+
+### Експеримент 2: додайте паралельний вузол Fan-out / Fan-in
+
+Перемкніться на гілку `p08-parallel`.
+
+1. **Виберіть точку, яку можна паралелити**: знайдіть у завданні місце, яке можна розбити на дві незалежні частини. Наприклад:
+ - реалізацію розбити на два незалежні модулі, два агенти пишуть паралельно
+ - верифікацію розбити на два незалежні рев'ю: одне запускає тести та lint, інше робить код-рев'ю (різні інструкції, різні фокуси уваги)
+ - дослідження розбити на два напрямки, два агенти досліджують кожен свою гілку
+2. **Запишіть правило fan-out**: у спільному стані зафіксуйте, що «це завдання розбито на N паралельних підзавдань», кожне підзавдання — окремий контекст, окремий вузол.
+3. **Запишіть правило fan-in**: коли всі підзавдання завершені, хто зливає результати? Який критерій злиття (наприклад: зливати лише якщо обидва рев'ю пройшли, чи достатньо одного)?
+4. **Ізолюйте через worktree**: кожне паралельне підзавдання працює в окремому git worktree, щоб фізично уникнути колізій файлів (згадайте примітив Worktree з тринадцятої лекції).
+5. **Запустіть один раз і запишіть**: зафіксуйте wall-clock час до/після паралелізації, витрату токенів, якість результату. Паралелізм справді швидший? Чи координаційні накладні витрати з'їли зекономлений час?
+
+### Експеримент 3: додайте ребро відкату та вузол ручного затвердження
+
+Перемкніться на гілку `p08-human-in-the-loop`.
+
+Це найважливіший із трьох експериментів. Ви додасте до графа два види вузлів:
+
+1. **Умовне ребро відкату**: додайте вузлу верифікації шлях «частково пройшло» — не повертати все цілком у вузол реалізації, а з конкретним зворотним зв'язком повернутися до **того вузла, де виникла проблема**. Наприклад: тести пройшли, але код-рев'ю виявило, що вимоги зрозуміли неправильно — повертаємося у вузол дослідження, а не у вузол реалізації. Це вимагає, щоб ваш спільний стан фіксував «на якому рівні виникла проблема».
+2. **Вузол ручного затвердження (Human-in-the-loop)**: перед вузлом злиття додайте людський вузол. Дійшовши сюди, граф **зупиняється** і чекає, поки ви напишете в `state.md` «затвердити» або «відхилити». У вузла затвердження може бути правило таймауту: якщо за N годин немає відповіді — автоматично відхилити або автоматично підняти рівень.
+3. **Запишіть формат interrupt**: як зрозуміло оформити запит на затвердження — що сталося, що змінилося, навіщо потрібна людина, які наслідки затвердження/відхилення.
+4. **Прокрутіть щонайменше 2 повні цикли**: у кожному доходите до вузла ручного затвердження і один раз самі затверджуєте, один раз відхиляєте. Запишіть: чи збігається ваше рішення про затвердження з висновком вузла верифікації? Чи перехоплював вузол затвердження щось, чого вузол верифікації не перехопив?
+
+## Як виміряти результат
+
+| Показник | Експеримент 1 (явний граф) | Експеримент 2 (паралель) | Експеримент 3 (людина в циклі) |
+|------|----------------|--------------|------------------|
+| Видимість структури | Скільки неявних ребер ви знайшли? | Чи витримує спільний стан паралельні підзавдання? | Чи може ребро відкату точно локалізувати рівень проблеми? |
+| Локалізація невдачі | При невдачі ви можете вказати, яке ребро помилкове? | Коли паралельне підзавдання впало, ви можете локалізувати, яке саме? | При відхиленні затвердження ви можете вказати, на якому рівні проблема? |
+| Координаційні накладні | Скільки часу пішло на малювання графа? | Зекономлений паралелізмом час vs. координаційні накладні | Час очікування затвердження vs. цінність перехопленої проблеми |
+| Спостережуваність | Що відбувається на кожному кроці — тепер це видно? | Стан кожного паралельного підзавдання видимий? | Чи досить зрозуміло оформлений запит на затвердження? |
+| Надійність | Граф-опис і реальне виконання збігаються? | Критерій fan-in злиття надійний? | Чи реально спрацьовують правила таймауту/підняття рівня? |
+
+## Що здати
+
+- `graph.md` (повний опис графа з експерименту 1: mermaid-граф + таблиця вузлів + таблиця ребер + поля спільного стану + правила маршрутизації)
+- Перелік неявних ребер, знайдених в експерименті 1 (принаймні одне)
+- Правила fan-out/fan-in з експерименту 2 та запис одного паралельного запуску (порівняння часу/вартості/якості)
+- Правило ребра відкату з експерименту 3, формат вузла затвердження та запис 2 циклів колаборації «людина в циклі»
+- Фінальна рефлексія: що змінилося у вашому способі роботи від loop до графа? Які завдання варті малювання графа, а які — ні?
+
+## Пов'язані лекції
+
+- [Lecture 14 — Від одиночних циклів до графової інженерії](../../lectures/lecture-14-graph-engineering/index.md)
+- [Lecture 13 — Від ручного введення промптів до автономних циклів](../../lectures/lecture-13-loop-engineering/index.md) (ваш loop — це один вузол графа; цей проєкт розкладає внутрішню структуру вузла)
+- [Lecture 09 — Чому агенти оголошують перемогу надто рано](../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md) (чому вузол верифікації має бути незалежним від вузла реалізації, і в графі це структурне питання)
+- [Lecture 11 — Чому спостережуваність належить всередині harness](../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) (чим складніший граф, тим важливіше бачити, що робить кожен вузол)
\ No newline at end of file
diff --git a/docs/uz/lectures/lecture-14-graph-engineering/index.md b/docs/uz/lectures/lecture-14-graph-engineering/index.md
new file mode 100644
index 0000000..a915d77
--- /dev/null
+++ b/docs/uz/lectures/lecture-14-graph-engineering/index.md
@@ -0,0 +1,349 @@
+[English Version →](../../../en/lectures/lecture-14-graph-engineering/)
+
+> Kod misollari: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-14-graph-engineering/code/)
+> Amaliy loyiha: [Loyiha 08. Ish oqimingizni grafik qilib chizing](./../../projects/project-08-graph-engineering-first-graph/index.md)
+
+# 14-maʼruza. Yakka loopʼdan grafik muhandisligigacha
+
+Oʻtgan maʼruzadagi Loop Engineering tugaganidan olti hafta oʻtib, 2026-yil 18-iyulda Peter Steinberger — oʻtgan maʼruzadagi "coding agentʼlarga endi prompt yozmang" degan OpenClaw muallifi — bir tvit yozdi:
+
+> "Biz hali ham Loop haqida gapiryapmizmi, yoki allaqachon Graphʼga oʻtib boʻldikmi?"
+
+Bitta tvit bir kunda taxminan 570 ming koʻrish, oy oxiriga kelib esa taxminan 3 million koʻrish oldi. Bir necha soatdan soʻng, mashina oʻqitish boʻyicha muhandis Hamel Husain "Loop Engineering Is Dead. Enter Graph Engineering" nomli maqola chop etdi — matnida faqat "Stop it" yozuvi tushirilgan GIF bor edi — va u ham taxminan 680 ming koʻrish oldi.
+
+Eng qiziq tomoni: **ikkalasi ham buni hazil sifatida yozgan edi.** Biri sanoat har olti haftada yangi atama ixtiro qilishini masxara qilayotgan edi, ikkinchisi esa shu memʼni davom ettirib, hazillashib javob berayotgan edi. Ammo hazil faqat taxminan bir dam olish kunigacha yashadi — oʻquv kurslari, yoʻl xaritalari va vositalar toʻplami hafta oxirigacha feedʼni toʻldirib tashladi, bir toʻda uydirma raqamlar bilan: "aniqlik +18%, xarajat −85%" — bu soxta maʼlumot (18% va 85% haqiqatan mavjud, lekin ular kimyo quvurlari sxemalari haqidagi ilmiy maqoladan olingan va taqqoslash bazisi butunlay boshqacha), "Microsoft, Stanford va Anthropic bir vaqtda grafik muhandisligini kashf etdi" degani ham yolgʻon xabar. Fakt-tekshiruv tasdiqlagan yagona "kashfiyotchi" — Josh Simmons: uning "We Are Entering the Graph Engineering Phase" maqolasi 4-iyulda yozilgan, bu hazildan roppa-rosa ikki hafta oldin — **hazil bu narsani mashhur qildi, lekin bu narsani yaratgan emas.**
+
+> Manba: [goddaehee: Graph Engineering fakt-tekshiruvi (2026-07-30)](https://goddaehee.tistory.com/628);[YC Startup School 2026: Jensen Huang intervyusi (transkript bilan)](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia);[explainx: Graph Engineering (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026)
+
+Bu maʼruzaning ishi — bu hot atamaga yana bir alanga qoʻshish emas, balki uni ajratib, aniq koʻrish: **nima uchun yakka loopʼdan keyin muqarrar ravishda grafik oʻsib chiqadi? Grafik va workflow aslida nima bilan farq qiladi? Qachon unga haqiqatan kerak boʻladi, qachon kerak emas?**
+
+## prompt, context, loop, graph: toʻrtta nom, bir-birining ustiga o'rnatilgan qatlamlar
+
+Iyul oyi oxirida muhandis Rohit (@rohit4verse) [uzun post](https://x.com/rohit4verse/status/2082478623043547356) yozib, AI muhandisligining soʻnggi yillardagi nomlash tarixini aniq toʻrt qatlamli ramkaga jamladi. Bu Graph Engineeringʼni tushunish uchun eng yaxshi koordinatalar tizimidir:
+
+| Bosqich | Nima shakllantiriladi | Javob beriladigan savol | Asosiy mahsulot |
+|---------|-----------------------|-------------------------|-----------------|
+| **Prompt Engineering** | Koʻrsatmalar | Modelga nima qilishni qanday aytish kerak? | instructions, examples, constraints, roles, output formats |
+| **Context Engineering** | Axborot | Model qaror qilishdan oldin nimani bilishi kerak? | documents, history, memory, tool definitions, environment state |
+| **Loop Engineering** | Runtime | Modelni maqsadga erishgunga qadar oʻzi loop qilishiga qanday erishish kerak? | observe, reason, act, inspect, update, toʻxtash sharti |
+| **Graph Engineering** | Tizim | Bir nechta agent, loop, vosita va baholovchi qanday hamkorlik qiladi? | tugunlar, chekkalar, umumiy holat, marshrutlash qoidalari |
+
+Bu chiziqni qanday oʻqishga eʼtibor bering: **har bir qatlam oldingi qatlamni almashtirmaydi, balki uning ustiga oʼrnatiladi.**
+
+- Context engineeringʼni topgach, siz prompt engineeringʼni toʻxtatmadingiz — har bir iteratsiya hali ham prompt talab qiladi, shunchaki loop muhit oʻzgarganda uni yangilab turishga yordam beradi.
+- Loop qurgach ham, siz contextʼni tashlamadingiz — loopʼning har bir rundi kontekstni qayta yigʻishni talab qiladi.
+- Graphʼga kelganda, prompt, context va loop — hech biri yoʻqolmaydi: **har bir tugun oʻz promptʼini, oʻz contextʼini, oʻz vositalarini, oʻz xotirasini va oʻz loopʼini olib yuradi.** Grafik tugunlar oʻrtasida qanday ulanishni belgilaydi.
+
+Rohitʼning asl soʻzlari shunday yakunlanadi:
+
+> Bir agent ixtisoslashuv, parallellik, umumiy holat, tekshiruv va tiklashni talab qilganda, u endi loop emas. U grafikdir.
+
+**Bir daqiqa, harness-chi?** Bu toʻrtta nomning ichida Harness Engineering yoʻq, lekin bu kurs aynan harness haqida. Sababi oddiy: Rohit hot atamalar tarixini aytmoqda, oxiri graph, oʻrtadagi qatlam esa oʻtkazib yuborilgan. Bundan tashqari, harness qaysi qatlamga tegishli ekani haqida hamjamiyatning oʻzi ham kelisha olmagan — [explainx](https://explainx.ai/blog/context-prompt-loop-harness-engineering-stack-2026) uni loopʼning ustiga, [Buildrix maqolasi](https://arxiv.org/abs/2606.25139) esa loopʼning ostiga qoʻyadi. Bu kurs ikkinchi maʼruzada buni belgilab qoʻydi: harness — poydevor, loop va graph uning ustiga quriladi.
+
+Bu gʻalati hodisani tushuntiradi: nima uchun "Graph Engineering" atamasi 2026-yil iyulda mashhur boʻldi, lekin hamma "buni allaqachon qilgandim" deb topdi. Chunki grafik yangi ixtiro emas — vazifangiz maʼlum bir murakkablik darajasiga yetganda, loop avtomatik ravishda grafikka aylanadi. Nom keyin paydo boʻldi, amaliyot allaqachon bor edi.
+
+## Grafikni ajratib koʻrish: tugun, chekka, holat, marshrutlash
+
+Grafikni eng sodda toʻrt qismga qaytaraylik.
+
+**Tugun (Node)**: qandaydir vazifani bajaruvchi ish birligi. U quyidagilardan biri boʻlishi mumkin:
+- Deterministik kod (testlarni ishga tushirish, qamrovni hisoblash)
+- Bir model chaqiruvi (hujjatlarni yaratish)
+- Bir vosita (git commit, xabar yuborish)
+- Toʻliq agent — oʻz loopʼiga ega, maqsadni tushunadi, vositalardan foydalanadi, ishlamay qolganda oʻzi qayta urinadi
+
+Tugun — grafik muhandisligi va workflow muhandisligi oʻrtasidagi haqiqiy chegara chizigʻi, bu haqda quyida alohida toʻxtalamiz.
+
+**Chekka (Edge)**: tugunlar oʻrtasida qanday topshirilishini tasvirlaydi. Bu "avval A, keyin B" kabi oddiy emas — bitta chekka quyidagilarni ifodalashi mumkin:
+- **Parallellik**: A tugagach, B va C bir vaqtda boshlanadi
+- **Shart**: test oʻtsa chapga, yiqilsa oʻngga
+- **Muvaffaqiyatsizlik / qayta urinish**: tugun qulab tushsa, oʻziga qaytib yana bir marta ishlaydi
+- **Qaytish**: tekshiruv oʻtmasa, uch sakrash oldingi implementatsiya tuguniga qaytadi
+
+**Umumiy holat (State)**: tugunlar oʻrtasida uzatiladigan maʼlumot paketi. Talablar, tadqiqot yozuvlari, kod versiyalari, test natijalari, koʻrib chiqish xulosalari — barchasi bitta umumiy ish stoliga yoziladi. Tugunlar bir-biriga toʻgʻridan-toʻgʻri chaqirmaydi, ularning barchasi bir xil holatni oʻqiydi va yozadi.
+
+**Marshrutlash qoidalari (Routing)**: keyingi qadam qayerga borishini belgilaydi. Bu grafikning "boshqaruv oqimi", eng sodda qilib aytganda:
+
+> Test oʻtsa — topshir; test yiqilsa — implementatsiya tuguniga qayt; axborot yetarli boʻlmasa — tadqiqot tuguniga qayt.
+
+Toʻrt qismni birlashtirsak, odatiy rivojlanish grafigi shunday koʻrinadi:
+
+```mermaid
+flowchart TD
+ S["Umumiy holat<br/>Talablar / Yozuvlar / Kod / Natijalar"] --- R["Tadqiqot tuguni<br/>Agent: muammoni topish"]
+ R -->|"Yechim chiqarish"| I["Implementatsiya tuguni<br/>Agent: oʻzgarish + test yozish"]
+ I -->|"Kod chiqarish"| V["Tekshiruv tuguni<br/>Agent: mustaqil koʻrib chiqish + testlarni ishga tushirish"]
+ V -->|"Oʻtmadi"| I
+ V -->|"Oʻtdi"| M["Merg tuguni<br/>Kod: commit + holatni yangilash"]
+ M -->|"Holat yangilanishi"| S
+ I -->|"Axborot yetarli emas"| R
+```
+
+Oʻtgan maʼruzadagi loop diagrammasi bilan solishtiring: oʻtgan maʼruzada bitta halqa bor edi — aniqlash, tarqatish, tekshirish, saqlash, keyin yana aniqlashga. Bu maʼruzadagi grafikda **halqa hali ham mavjud, lekin u eksplisit tugunlar va chekkalarga boʻlingan**. Tekshiruv tuguni muvaffaqiyatsizlikni toʻgʻridan-toʻgʻri implementatsiya tuguniga qaytarishi mumkin, implementatsiya tuguni axborot yetarli boʻlmaganda tadqiqot tuguniga qaytishi mumkin — bu "qaytish chekkalari" yakka loopʼda yashirin, agent oʻz contextʼida "orqaga qaytishim kerak" deb eslab yuradi.
+
+## Loop qachon yetarli boʻlmaydi
+
+Loopʼda faqat bitta asosiy yoʻl bor. Oʻtgan maʼruzada qurgan maker-checker loopʼingizda barcha qarorlar — keyingi qadamda nima qilish, muvaffaqiyatsizlikda qayerga borish — bitta agentning kontekst oynasida roʻy beradi. Vazifa biroz murakkablashganda, toʻrtta savol paydo boʻladi:
+
+1. **Mehnat taqsimoti**: talabni tadqiq qiluvchi agent, kod yozuvchi agent, test yozuvchi agent — kim birinchi boshlaydi?
+2. **Parallellik**: qaysi ishlar bir vaqtda bajarilishi mumkin?
+3. **Qaytish**: test yiqilgandan keyin qayerga qaytish kerak — implementatsiya tugunigami, yoki tadqiqot tugunigami?
+4. **Topshirish**: bir nechta agent bir xil talab, yozuv va test natijalarini qanday koʻradi? Koʻrib chiq huvi implementator bilan rozi boʻlmasa, kimning gapiga quloq solish kerak?
+
+Jensen Huang Y Combinatorʼning [Startup School 2026 intervyusida](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia) (Garry Tan bilan suhbatda) shunga oʻxshash fikrni aytdi: asosiy darajadagi implementatsiya agentlar tomonidan tobora avtomatlashtirilganda, insonning asosiy qiymati "tizimlarni loyihalash, cheklovlarni aniq belgilash va agentlar ustida batafsil nazorat qilish"ga oʻtadi. Uning nazorat misoli juda aniq — "agent reja bergandan keyin, men reja faylida bitta soʻzni oʻzgartiraman, bu bitta soʻz aniq bitta farqni keltirib chiqaradi"; u kelajakning asosiy koʻnikmasi "tizimli fikrlash" (systems thinking) boʻlishini ham bashorat qildi.
+
+Munozara ipidagi eng kuchli zarba Luis Catacoraʼdan keldi:
+
+> **"Loopʼda katta xatoga yoʻl qoʻyish maydoni bor. Grafik esa sizni tan olishga majbur qiladi: ish oqimingizdagi qancha qism aslida modellashtirilmagan."**
+
+Bu gap loop va graph oʻrtasidagi chuqur farqni ochib beradi:
+
+- **Loop — kechiktirilgan qaror.** Avval bitta agent barcha ishni oʻz zimmasiga olsin, ishlamay qolganda bilib olamiz, arxitekturani keyinga surib boʻladi. Bu qulay, lekin narxi — muvaffaqiyatsizlik rejimlari koʻrinmas; u qaysi qadamda qotib qolganini hech qachon bilmaysiz, chunki uning oʻzi ham bilmaydi.
+- **Graph — oldindan qaror.** Siz butun tuzilmani oldindan eʼlon qilishingiz kerak: kim nima uchun javobgar, vazifalar oʻrtasida qanday bogʻliqlik, qanday muvaffaqiyatsizlik qayerga qaytadi. Bu mashaqqatli, lekin evaziga oʻqiladigan, audit qilinadigan va qisman tuzatiladigan boʻladi.
+
+Yanada ochiqroq aytganda: **loop muammoni loop ichida yashiradi, graph muammoni qogʻozga qoʻyadi.** Birinchisi kashfiyot uchun, ikkinchisi ishlab chiqarish uchun.
+
+## Yakka loopʼning uchta strukturaviy muvaffaqiyatsizligi
+
+Nima uchun yakka loop miqyosda chiday olmaydi? eigent.aiʼdagi "Graph Engineering for AI Agents: Beyond Single Feedback Loops" maqolasi uchta strukturaviy muvaffaqiyatsizlikni keltiradi — eʼtibor bering, bu strukturaviy muvaffaqiyatsizlik, bitta loopʼning bugʼi emas.
+
+**Avval bir eʼtiroz: loop ichiga ham checkpoint qoʻshish mumkin emasmi?** Mumkin. Oʻtgan maʼruzadagi tekshiruv, toʻxtash sharti, hatto tanaffusda qayta urinish — bularning barchasi loopʼga sigʻadi. Ammo quyidagi uchta muvaffaqiyatsizlikni aynan checkpointʼlar hal qila olmaydi — chunki loop ichidagi checkpoint bitta agentning ichida oʻsadi, tekshiruv oʻtkazuvchi va muammo yaratuvchi — bitta miya, bitta context. U "tekshiruvsiz topshirish"ni toʻxtata oladi, lekin "bu metrika toʻgʻrimi", "bu maqsadni taʼqib qilish kerakmi" degan savollarni soʻramaydi — javob uning oʻz contextʼida yozilgan, u koʻrolmaydi. Grafik sizga koʻproq checkpoint berish emas, balki tekshiruvni **tashqariga koʻchirish**: "agent ichidan" "mustaqil tugun"ga, unga butunlay yangi context berish (oldingi verify tuguni boʻlimida aytilgan edi). "Strukturaviy" soʻzining maʼnosi shu: loopʼda qaysidir qism yoʻq emas, balki "hukm qiluvchi va bajaruvchi bir xil miyani boʻlishadi" degan strukturaning oʻzi.
+
+### 1. Goodhart: raqam oʻsdi, lekin biznes yomonlashdi
+
+Har qanday bitta metrikani chegaragacha sursangiz, u siz oʻylagan narsani oʻlchashni toʻxtatadi. Klassik misol: yordam jamoasi "ticket yechish darajasi" atrofida loop qurdi. Haftalik koʻrsatkichlar tinmay oʻsdi. Bir necha oydan keyin toʻlov yangilash maʼlumotlari churn ikki barobar oshganini koʻrsatdi — **bot ticket yopishni oʻrgandi**: mavzuni oʻzgartirish, foydalanuvchini soʻroq qilishdan qaytarish, hal qilinmagan muammolarni "yechilgan" deb belgilash.
+
+Loop oʻzidan soʻralgan hamma narsani qildi. Faqat oʻsha raqam biznes uchun asl muhim boʻlgan narsadan ajralib chiqdi. Mana Goodhart qonuni.
+
+### 2. Yuqoriga qarab koʻrlilik: u hech qachon "bu maqsad toʻgʻrimi" deb soʻramaydi
+
+Loop ichida mos yozuv qiymatlari muqaddas. Termostat "68°F toʻgʻri haroratmi" deb soʻramaydi. Savdo loopʼi "bu reja oqilonami" deb soʻramaydi. Agent eval loopʼi "bu benchmark haqiqiy biznes natijalariga mos keladimi" deb soʻramaydi.
+
+**Maqsadni kim tanlagan boʻlsa, loop oʻsha tomonga yuguradi, hatto u boshidanoq taʼqib qilishga arzimas narsa boʻlsa ham.** Yakka loopʼning strukturasida bu savolga joyning oʻzi yoʻq.
+
+### 3. Konflikt: mustaqil loopʼlar bir-birini buzadi
+
+Haqiqiy tizimlarda oʻnlab loop bor, har biri mustaqil qurilgan. Javob tezligi loopʼi chuqur sifat loopʼining ishini buzmoqda, oʻsish loopʼi sifat loopʼining ishini buzmoqda. Har bir loop oʻz dashboardʼida sogʻlom koʻrinadi, lekin butun tizim titrayapti — xuddi bir necha kishi bir xil arqonni turli yoʻnalishda tortayotgandek.
+
+**Graph engineering aynan yakka loop javob bera olmaydigan savollar toʻplamiga javob beradi:**
+
+- Qaysi loopʼlar qaysi loopʼlarga oziq beradi?
+- Qaysi loopʼlar boshqa loopʼlar taʼqib qiladigan maqsadlarga egalik qiladi?
+- Qaysi loopʼlar oʻzgarishni veto qilishi yoki qaytarishi mumkin?
+- Qaysi metrikalar harakatlanishi mumkin, qaysilari muzlatilishi shart?
+
+Tizimda "sizning maqsadingizni yeb qoʻya oladigan loop" va "oʻzgarishingizni veto qila oladigan loop" mavjud boʻlganda, ular oʻrtasidagi munosabat muhandislik obyektiga aylanadi — va munosabatlar oʻrtasidagi munosabatlar, chizilganda, grafik boʻladi.
+
+### Anchor: loopʼni reallikka mahkamlash
+
+eigent maqolasining sarlavhasida "everyone skips" (hamma oʻtkazib yuboradigan) qism bor: **anchors (anchorʼlar)**. Loopʼlar tarmogʻi qanchalik nafis boʻlmasin, agar har bir loop reallikdan uzoqlashib ketsa, tarmoq faqat bir-biriga nisbatan suzuvchi rezonans boʻladi. Anchor — loopʼni haqiqiy dunyoga mahkamlaydigan narsa: haqiqiy biznes natijalari, ground truth maʼlumotlar toʻplami, qoʻlda tanlab tekshirish. Grafikni loyihalashda anchor eng koʻp oʻtkazib yuboriladigan, lekin eng kam oʻtkazib yuborilishi mumkin boʻlgan qadamdir.
+
+## Graph va Workflow: faqat nomni oʻzgartirish emas
+
+Bu bu maʼruzadagi eng koʻp notoʻgʻri tushuniladigan joy, uni alohida ajratib aytishga arzir.
+
+Graph Engineering portlab ketganda birinchi reaksiya — muhandislik qilgan har bir kishi oʻzicha gʻoʻldiradi: "Bu workflow emasmi? DAG, holat mashinalari, workflow dvigatellari — biz ularni oʻnlab yillardan beri ishlatamiz."
+
+**Bu sezgi yarim toʻgʻri.** Grafik va workflow haqiqatan bir xil skeletni boʻlishadi: tugun + chekka + umumiy holat + marshrutlash. Airflow, Prefect, Dagster, Temporal oʻnlab yillardan beri aynan shu grafik boʻyicha orkestratsiya qiladi. Anthropicʼning 2024-yil dekabridagi "Building Effective Agents" maqolasi jamlagan beshta naqsh — prompt zanjiri, marshrutlash, parallellashtirish, orkestrator/ishchi, baholovchi/optimallashtiruvchi — ularni chizsangiz, xuddi turli shakldagi bajarilish grafiklari chiqadi.
+
+**Xato boʻlgan qism — tugunda.** Anʼanaviy workflowʼning tuguni — **deterministik funksiya**: bitta Python funksiyasi, bitta shell skripti, bitta SQL vazifasi. Chekka — qotib qolgan kod: `if`, `switch`, `case`. Butun tizimni muhandis kod bilan boshqaradi, xatti-harakat bashorat qilinadi — bir xil kiritish doim bir xil yoʻldan boradi.
+
+Grafik muhandisligining tuguni **toʻliq agent** boʻlishi mumkin: oʻz loopʼiga ega, vositalardan foydalanadi, maqsadni tushunadi, muvaffaqiyatsizlikda oʻzi qayta urinadi. Chekka ham qotib qolgan boʻlishi shart emas — u marshrutlash qoidalariga ega boʻlishi mumkin, keyingi qadamni oldingi tugunning chiqishi, tekshiruv natijasi yoki hatto boshqa model belgilaydi.
+
+Bu farqni aniq tushuntirish uchun Anthropicʼning bir juft konsepsiyasini olaylik. Anthropic workflow va agentni bir jumla bilan farqlaydi: **boshqaruv oqimini kim belgilaydi?** Qadamlarni kod belgilasa — workflow, model runtimeʼda qadamlarni oʻzgartira olsa — agent.
+
+Xoʻsh, grafik nima? **Grafik — ikkalasini ham sigʻdiradigan konteyner.** Bitta grafikda bir vaqtda boʻlishi mumkin:
+
+- workflow tugunlari: testlarni ishga tushirish, qamrovni hisoblash — deterministik kod, model kerak emas
+- agent tugunlari: funksiyani implement qilish, kodni koʻrib chiqish — model tomonidan boshqariladigan toʻliq agent
+- inson tugunlari: tasdiqlash, qayta koʻrib chiqish — inson-mashina oʻzaro taʼsir tuguni, bu yerga yetganda toʻxtaydi, insonning bosh qimirlatishini kutadi
+
+Shuning uchun aniq taʼrif: **Graph Engineering Workflowʼning oʻrnini bosuvchi emas, balki Workflowʼning umumlashtirishidir** — tugun turini "funksiya"dan "agent"gacha, chekka qarorini "statik kod"dan "dinamik marshrutlash"gacha kengaytiradi. Workflow — grafikdagi "toʻliq aniqlangan" maxsus holat.
+
+Qarama-qarshi fikr (iii.devʼdagi "Loops, Graphs, and the Layer That Matters") ham aynan shu nuqtaga borib taqaladi, faqat xulosa — teskari:
+
+> "Shakl — oson qism, va u bir martalik. Yuk koʻtaruvchi qaror — loop yoki graph nimadan iboratligi va u ishlaganidan keyin qanday boʻlishi."
+
+iii.devʼning maʼnosi: "topologiya"ni muhandislik yutugʻi deb qabul qilma. Workflow muhandisligi oʻnlab yillar ishladi, asl qolgan narsa tugunlar qanday ulanganligi emas, balki **qayta ijro etiladigan, kuzatiladigan, tiklanadigan** — muammo boʻlsa qayta ijro etish, ishlayotganda kuzatish, qulab tushsa davom etish mumkin. Grafikning shaklini xohlagancha oʻzgartirasiz, bu yuk koʻtaruvchi qobiliyatlar siz investitsiya qilishi kerak boʻlgan joy. Bu tanqidni yodda tutishga arzir: **grafika chizish maqsad emas, grafik ustiga qancha muhandislik qobiliyatini koʻtara olishingiz maqsad.**
+
+## Siz aslida allaqachon grafik chizayotgan edingiz
+
+"Yangi shisha, eski sharob"ning yana bir dalili: vositalar allaqachon tayyor edi.
+
+- **LangGraph**: 2024-yil yanvarida chiqarilgan, 2026-yil iyuliga qadar oylik yuklab olish taxminan 65 million. Bu agentlar uchun grafik bajarilish dvigateli, tugunlar agent boʻlishi mumkin, chekkalar shartli marshrutlash, checkpoint, interruptʼga ega boʻlishi mumkin.
+- **Anthropic besh naqshi**: 2024-yil dekabridagi "Building Effective Agents" prompt zanjiri, marshrutlash, parallellashtirish, orkestrator/ishchi, baholovchi/optimallashtiruvchi grafiklarini allaqachon chizgan edi, faqat Graph Engineering deb atamagan.
+- **Claude Codeʼning subagent fan-outʼi**: bosh agentga bir toʻda sub-agentni parallel ishlashga yuborishni buyursangiz, siz allaqachon grafik qurayotgan boʻlasiz, shunchaki anglamayapsiz.
+- **Holat mashinalari, DAG rejalashtirish, vazifa navbatlari, bilim grafiklari**: kompyuter fanida oʻnlab yillar, grafikning muhandislashtirilishi yangi muammo emas.
+
+Asl yangi narsa nima? **Tugun "funksiya"dan "agent"ga aylandi.** Bu yagona oʻzgarish, va butun oʻzgarish. Ilgari workflow tugunini yozganda, uning mantiqini, xatolarni boshqarishini, qayta urinish strategiyasini aniq yozar edingiz. Endi bitta tugun faqat bitta koʻrsatma talab qiladi — "bu muammoni oʻrgan", "bu kodni koʻrib chiq" — qolganini model oʻzi bajaradi. Tugun arzonlashdi, shuning uchun grafik chizishga arzidigan boʻldi.
+
+## Noldan birinchi grafikʼingizni qurish
+
+Nazariya yetarli, keling amalga oʻtamiz. Oʻtgan maʼruzadagi maker-checker — oʻzi loop qiladigan **bitta** agent edi. Graph Engineering qiladigan birinchi ish — bunday monolit agentni boʻlish: **har bir tugun maxsus agentga aylanadi, har biri oʻz shaxsiy promptʼini, contextʼini, toolsʼini, memoryʼsini va oʻz kichik loopʼini koʻtaradi; tugunlar oʻrtasida kontekst boʻlishilmaydi, faqat umumiy holat orqali topshiriladi.** Mana Rohit gapining oddiy tili — "graph har bir tugun nimani koʻrishini, qachon ishlashini, chiqish qayerga ketishini, kim vetoni, nima tizimni toʻxtatishini belgilaydi". Quyidagi barcha yozuvlar hech qanday aniq dvigatelga bogʻlanmagan — bu tushuncha, LangGraph va CrewAI shunchaki ularni bajariladigan dasturga aylantiradigan implementatsiyalar, API farq qiladi, skelet bir xil. Olti qadam, birini ham oʻtkazib yubormang.
+
+**1-qadam: Umumiy holatni (State) aniqlang.** Avval ikki qatlamni farqlang: **graph qatlamida faqat holat boʻlishiladi, tugunlarning konteksti xususiydir.** Monolit agentda bitta context bor, uzoq ishlagach u oʻzining uzun transcriptʼi ostida qolib ketadi; graph contextʼni bir nechta qismga boʻladi, har biri bitta tugunga tegishli — loop tugunning shaxsiy mulki, graph esa ular topshiriladigan umumiy stol. Holatga nima qoʻyishni avval aniq oʻylang. Har bir maydon qanday "birlashtirilishini" eʼlon qiling — bir nechta parallel tugun bir vaqtda bir xil maydonga yozsa, ustidan yozish, qoʻshish yoki yigʻindimi. Bu qadam framework xususiyati emas, grafik chizayotganda `graph.md` ga yozishingiz kerak boʻlgan qoida:
+
+```
+state = {
+ "requirements": matn, # tadqiqot tuguni yozadi
+ "code": matn, # implementatsiya tuguni yozadi
+ "review": "pass" | "fail", # koʻrib chiqish tuguni yozadi
+ "attempts": raqam, # har muvaffaqiyatsizlikda +1 (parallel yozishda "yigʻindi" bilan birlashtiriladi)
+}
+```
+
+**2-qadam: Tugunlarni roʻyxatlang — har bir tugun toʻliq agent (oʻz loopʼi bilan).** Bu graph va workflow oʻrtasidagi asosiy farq: workflowʼning tuguni funksiya, graphʼning tuguni **oʻz kichik loopʼiga ega agent**. Tugun umumiy holatni qabul qiladi → oʻz shaxsiy konteksti bilan ishlaydi → natijani umumiy holatga qayta yozadi. Kod yozuvchi turdagi tugunning ichida koʻpincha oʻtgan maʼruzadagi loop boʻladi:
+
+```
+# implement tuguni ichida: shaxsiy kichik loop (oʻtgan maʼruzadagi maker-checker loopʼning oʻzi)
+node_implement(requirements):
+ loop (maksimal 3 marta):
+ code = model(prompt=implementatsiya koʻrsatmasi, context=requirements + oxirgi xato)
+ if tests_pass(code): return {"code": code}
+ return {"error": "Implementatsiya 3 marta ham oʻtmadi"}
+```
+
+| Tugun | Turi | Tugun ichida (xususiy) | Umumiy holatga yozadi |
+|------|------|------------------------|-----------------------|
+| research | agent | Qidirish → oʻqish → xulosa → axborot yetarli boʻlmasa qayta qidirish (loop) | requirements |
+| implement | agent | Yozish → test → tuzatish → oʻtguncha (loop, yuqoriga qarang) | code |
+| verify | agent | Mustaqil koʻrib chiqish + testlarni ishga tushirish (**fresh context, implementatorning xotirasini meros qilmaydi**) | review (pass / fail) |
+| merge | deterministik kod | Loop yoʻq, tekshiruv oʻtib commit qiladi | yakun |
+
+verify qatoriga eʼtibor bering: u grafikdagi eng koʻp xato qilinadigan tugun. **Monolit agentda "koʻrib chiqish" hali ham bir xil contextʼni ishlatadi, oʻzini oʻzi koʻrib chiqadi; graphʼda verify butunlay yangi kontekst bilan kelishi kerak** — u implementʼning fikrlash jarayonini koʻrmaydi, faqat umumiy holatdagi codeʼni koʻradi. Mana "mustaqil koʻrib chiqish" grafikda haqiqatan amalga oshadigan joy: kontekst izolyatsiyasi yon taʼsir emas, dizayn.
+
+**3-qadam: Chekkalarni ulang.** Avval aniq asosiy yoʻlni ulang: tadqiqot → implementatsiya → tekshiruv → merg → yakun.
+
+```mermaid
+flowchart TD
+ A([Boshlash]) --> B[research]
+ B --> C[implement]
+ C --> D[verify]
+ D --> E[merge]
+ E --> F([Yakun])
+```
+
+**4-qadam: Marshrutlash qoidalarini yozing (eng muhim qadam).** Tekshiruv tuguni toʻgʻridan-toʻgʻri "merg"ga ulanmaydi, balki **qaror**ga ulanadi, u keyingi qadam qayerga borishini belgilaydi. Bu qadam "test yiqilganda qayerga qaytish"ni eksplisit qiladi — marshrutlash qoidasi tugun nomini qaytaradi, bu grafik qayerdan kelib, qayerga ketishini bir qarashda koʻrasiz:
+
+| Joriy tugun | Shart | Keyingi tugun |
+|-----------|-------|----------------|
+| verify | review == pass | merge |
+| verify | review == fail | implement |
+
+```mermaid
+flowchart TD
+ A([Boshlash]) --> B[research]
+ B --> C[implement]
+ C --> D{verify}
+ D -- pass --> E[merge]
+ D -- fail --> C
+ E --> F([Yakun])
+```
+
+**5-qadam: Checkpointʼni oʻrnating.** Bu grafik va bir martalik skript oʻrtasidagi eng katta farqlardan biri: **har bir qadamning holati diskga yoziladi**, jarayon qulab tushsa, yangidan boshlash oʻrniga toʻxtagan joyidan davom etadi. Oʻrnatgach, grafikʼingiz darhol "toʻxtatish/tiklash" qobiliyatiga ega boʻladi — mergeʼdan oldin "inson tasdiqlashini kutish" tugunini ham qoʻshishingiz mumkin, oʻtgan maʼruzadagi "inson tasdiqlashi" grafikda aynan shunday koʻrinadi:
+
+```
+checkpoint = on(graph, every_step) # har bir qadamning holati saqlanadi
+graph.pause_before("merge") # merg'dan oldin toʻxtaydi, inson tasdiqlashini kutadi
+```
+
+**6-qadam: Grafikni ishga tushiring va unga kirish nuqtasi bering.** Har bir ishlashda thread id uzating, checkpoint u orqali turli ishlash instansiyalarini ajratadi:
+
+```
+run(graph, entry={"requirements": "Login sahifasidagi bug'ni tuzatish"}, thread="session-1")
+```
+
+Ishga tushirgach, yuqoridagi grafik bilan solishtiring: qoʻlda yozgan `graph.md` — loyiha, dvigateldagi oʻsha kod — loyiha aylangan bajariladigan dastur. Ular bir-biriga mos kelishi kerak. Agar mos kelmasa — yoki grafik notoʻgʻri chizilgan, yoki kod notoʻgʻri yozilgan, **mana "grafik muammoni qogʻozga qoʻyadi" deganining maʼnosi**: ilgari mos kelmasa ham hech kim bilmas edi, endi bir qarashda koʻrinadi. Haqiqiy ishlaydigan maʼlumotnoma implementatsiyasi uchun `code/maker_checker_graph.py` ni koʻring — LangGraph ishlatilgan, lekin oʻqib boʻlgach tanib olasiz: u aynan yuqoridagi olti qadam.
+
+## Ochiq manbali loyihalar: eʼlondan keyin paydo boʻlganlar va eʼlondan oldin mavjud boʻlganlar
+
+Avval chegarani aniq belgilaylik: **Graph Engineering — 2026-yil 18-iyuldan keyin paydo boʻlgan nom.** Undan oldin ochiq manbali boʻlgan freymvorklar "Graph Engineering eʼlondan keyingi loyihalar" emas. Kontsepsiya portlab ketgandan keyin, toʻgʻridan-toʻgʻri shu nom bilan paydo boʻlgan ochiq manbali loyihalar, 2026-yil avgust boshi holatiga koʻra, faqat bittasi tan olinadi:
+
+**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.
+
+**Kontsepsiya eʼlonidan oldin mavjud boʻlganlar (ular Graph Engineering deb atalmaydi, lekin siz qurishda aynan ularni ishlatasiz)**
+
+2026-yil iyuligacha bu vositalar bir yildan uch yilgacha mavjud boʻlgan: LangGraph (2024-yilda ochiq manbali boʻlgan, oylik 65 million+ yuklab olish, yuqoridagi maʼlumotnoma implementatsiyasi aynan uni ishlatadi), CrewAI, Microsoft Agent Framework, LlamaIndex Workflows, Google ADK, OpenAI Agents SDK, Mastra, Claude Agent SDK. **Ular "Graph Engineering eʼlonidan keyingi loyihalar" emas — ular aynan "Graph Engineering eʼlonidan oldin" mavjud boʻlganning dalili.** Tugun, chekka, umumiy holat, marshrutlash — bu toʻplam uch-besh yil ishlab, iyulda yangi nom oldi. Grafik dvigatel dizayn muammosini hal qilmaydi: u sizga tugun, chekka, checkpoint beradi, lekin "qaysi loop qaysi loopʼni oziqlantiradi, kim maqsadga egalik qiladi, kim veto qiladi" degan savollarga javob bermaydi. Bu savollarni aniqlamasdan turib, qaysi dvigatelga oʻtmasangiz ham, xuddi oʻsha yomon dizaynni yanada chiroyliroq chizgan boʻlasiz.
+
+## Sovuq suv: grafik kumush oʻq emas
+
+Uch chelak sovuq suv, engildan ogʻirga.
+
+**Birinchisi: soxta raqamlar.** Graph Engineering portlab ketgach, internetda "grafik ishlatganda aniqlik +18%, xarajat −85%" kabi maʼlumotlar tarqaldi. Koreyalik bloger goddaehee bir [fakt-tekshiruv](https://goddaehee.tistory.com/628) (30-iyul) oʻtkazdi: bu ikki raqam haqiqatan mavjud, lekin ular 2026-yil martidagi kimyo quvurlari sxemalari (P&ID) haqidagi ilmiy maqoladan olingan, va 18% tasvir asl nusxasi bilan solishtirilgan, 85% esa boshqa variant bilan solishtirilgan — marketing matni ikki turli bazisdagi raqamlarni bitta "oldin/keyin" qilib birlashtirgan, maqolada hatto "graph engineering" soʻzi ham yoʻq. "Grafik muhandisligi X% yaxshilanish beradi" degan har qanday maʼlumotni koʻrsangiz, avval asl manbani tekshiring.
+
+**Ikkinchisi: shakl yuk koʻtaruvchi devor emas (iii.dev).** Yuqorida aytib oʻtdik. Loop — faqat bitta tugunli grafik; holat mashinalari oʻnlab yillar ishladi. "Loop oʻldi" yoki "graph oʻldi" deb ogʻziga olgan odamlar, odatda, na loopʼni, na graphʼni sinchiklab oʻqimagan. Oʻrganish kerak boʻlgan — naqshlar, atamalar emas.
+
+**Uchinchisi: Orchestration Tax (Orkestratsiya soligʼi).** Addy Osmani may oyidagi "The Orchestration Tax" maqolasida grafik/koʻp agent davrining eng qattiq iqtisodiy qonunini berdi: **agent ishga tushirish arzon, loop yopish qimmat.**
+
+Bitta agentni ishga tushirish — bitta tugma, bitta gap. Ammo agentning loopʼini yopish uchun kimdir uning natijasini tekshirishi, boshqa agentlar oʻzgartirgan narsalar bilan moslashtirishi kerak — **oʻsha kimdir — siz, va siz faqat bittasiz.** Osmaniʼning asl soʻzlari:
+
+> "Siz AI agentʼlaringizning GILʼisiz. Ular bir vaqtda ishlashi mumkin. Ammo ularning ishi arxitekturani chindan tushunishni, merge konfliktlarni hal qilishni talab qilganda, bu ishlar oʻsha qulfni olishi kerak. Faqat bitta qulf, va uni siz ushlab turasiz."
+
+Oʻtgan maʼruzadagi "koʻrib chiqish kengligi — shifon" degan gap bu maʼruzada yanada keskinroq: **grafik parallel agentlarni koʻpaytiradi, lekin sizning hukm qilish qobiliyatingiz — ketma-ket resurs, parallel emas.** Tugun qoʻshish hech qachon bottleneck boʻlmagan qismni optimallashtiradi — bottleneck har doim oʻsha bitta ketma-ket protsessor: siz.
+
+## Qachon haqiqatan grafik ishlatish kerak
+
+Barcha vazifalar grafik chizishga arzimaydi. Beshta mezon, kamida uchtasi bajarilgan boʻlsa qoʻl uzing:
+
+1. **Vazifa mustaqil ish birliklariga boʻlinishi mumkin** — boʻlingan qismlar bir-biriga bogʻliq emas, parallel bajarilishi mumkin
+2. **Tarmoqlanish yoki qaytish yoʻllari mavjud** — test yiqilganda qayerga qaytish, axborot yetarli boʻlmaganda qayerga qaytish, bu yoʻllarni eksplisit eʼlon qilishga arzir
+3. **Oraliq holatni saqlashga arzir** — checkpoint dan keyin toʻxtab, tiklash mumkin, yangidan boshlash oʻrniga
+4. **Natijani aniq qabul qilish mumkin** — har bir tugun avtomatik tekshiriladigan tugallik mezoniga ega
+5. **Hamkorlik foydasi > muvofiqlashtirish xarajati** — parallel tejagan vaqt, grafikaning oʻzi va umumiy holat keltirgan qoʻshimcha xarajatdan koʻp
+
+**"Murakkab" "qadamlar koʻp" degani emas.** 20 qadamlik chiziqli pipeline grafik talab qilmaydi — bu workflow yoki oddiygina skript. Bor‑yoʻgʻi 5 tugunli, lekin ular orasida qaytish, parallel, tasdiqlash boʻlgan struktura grafikka muhtoj. Mezon — hajm emas, **tarmoqlanish va qaytishning mavjudligi**.
+
+## Asosiy tushunchalar
+
+- **Graph Engineering**: bir nechta agent, loop, vosita va baholovchini eksplisit grafikka (tugun + chekka + umumiy holat + marshrutlash qoidalari) tashkil qilish amaliyoti. Koʻp ish birliklarining ulanishi, umumiy holat va yoʻl tanlashni loyihalanishi, kuzatilishi va qisman tuzatilishi mumkin qiladi.
+- **Toʻrt qatlamli qoʻshilish**: prompt → context → loop → graph, har bir qatlam boshqa narsani boshqaradi (koʻrsatma, axborot, runtime, tizim), keyingi qatlam oldingisini almashtirmaydi, faqat oldingisini oʻz tuguniga joylashtiradi.
+- **Graphʼning toʻrt qismi**: tugun (ish birligi), chekka (topshirish usuli), umumiy holat (umumiy ish stoli), marshrutlash qoidalari (keyingi qadam qayerga).
+- **Yakka loopʼning uchta strukturaviy muvaffaqiyatsizligi**: Goodhart (raqam oʻsdi, biznes yomonlashdi), yuqoriga qarab koʻrlilik (hech qachon "bu maqsad toʻgʻrimi" deb soʻramaydi), konflikt (mustaqil loopʼlar bir-birini buzadi). Grafik bu uch turdagi muammoni eksplisit munosabat dizayniga aylantiradi.
+- **Graph ≠ Workflow**: workflowʼning tuguni deterministik funksiya, chekkasi qotib qolgan kod; graphʼning tuguni toʻliq agent boʻlishi mumkin, chekkasi dinamik marshrutlash mumkin. Graph — workflowʼning umumlashtirishi.
+- **Anchors (anchorʼlar)**: loopʼlar tarmogʻini haqiqiy dunyoga mahkamlash mexanizmi (haqiqiy biznes natijalari, ground truth, qoʻlda tanlab tekshirish). Grafik dizaynida eng koʻp oʻtkazib yuboriladigan, lekin eng kam oʻtkazib yuborilishi mumkin boʻlgan qadam.
+- **Orchestration Tax (Orkestratsiya solig'i)**: agent ishga tushirish arzon, natijalarni koʻrib chiqish qimmat. Sizning eʼtiboringiz — yagona ketma-ket resurs, tugun qoʻshish uni optimallashtira olmaydi.
+
+## Asosiy xulosalar
+
+- **Graph Engineering Loop Engineeringʼni almashtirmaydi, balki uning ustiga bir qavat quradi.** Loop — grafikdagi bitta tugun; oʻtgan maʼruzadagi uchta narsa (maqsad, tekshiruv, toʻxtash sharti) tugunning ichki tuzilishiga aylanadi.
+- **Grafik "kechiktirilgan qaror"ni "oldindan qaror"ga aylantiradi.** Loop muvaffaqiyatsizlik rejimlarini loop ichida yashiradi, graph uni qogʻozga qoʻyadi — oʻqiladigan, audit qilinadigan, qisman tuzatiladigan.
+- **Tugunga nima joylanganligi grafika va workflow oʻrtasidagi farqni belgilaydi.** Funksiya joylansa — workflow, agent joylansa — grafik. Bu ham "yangi shisha, eski sharob" ichidagi yagona yangi sharob.
+- **Grafikni loyihalashdan oldin toʻrtta savolga javob bering:** qaysi loop qaysi loopʼni oziqlantiradi, kim maqsadga egalik qiladi, kim veto/rollback qiladi, qaysi metrikalar oʻzgartirilishi mumkin, qaysilari muzlatiladi. Javob bera olmasangiz — chizmang.
+- **Faqat grafik chizish uchun chizmang.** Besh mezon: mustaqil boʻlinishi mumkin, tarmoqlanish yoki qaytish bor, oraliq holatni saqlashga arzir, natija qabul qilinishi mumkin, hamkorlik foydasi > muvofiqlashtirish xarajati.
+- **Koʻrib chiqish kengligingiz hali ham shifon.** Grafik parallel agentlarni koʻpaytiradi, lekin hukm qilish qobiliyatingiz — ketma-ket resurs; orkestratsiya soligʼi tugunlar koʻpayganda ham yoʻqolmaydi.
+- **Qarama-qarshi fikrni esda tuting.** Shakl yuk koʻtaruvchi devor emas; qayta ijro etiladigan, kuzatiladigan, tiklanadigan — ana shu. Atamalar har olti haftada oʻzgaradi, muhandislik qobiliyati oʻzgarmaydi.
+
+## Qoʻshimcha oʻqish
+
+- [Prefect: Loops vs. Graphs (Jul 2026)](https://www.prefect.io/blog/loops-vs-graphs) — oʻnlab yil grafik orkestratsiyasi bilan shugʻullangan kompaniya nuqtai nazaridan loop va graph
+- [Eigent: Graph Engineering for AI Agents (Jul 2026)](https://www.eigent.ai/blog/graph-engineering-ai-agents) — yakka loopʼning uchta strukturaviy muvaffaqiyatsizligi + toʻrt dizayn savoli + anchors
+- [iii.dev: Loops, Graphs, and the Layer That Matters (Jul 2026)](https://iii.dev/blog/loops-graphs-and-the-layer-that-matters/) — eng hushyor qarama-qarshi fikr: "shakl yuk koʻtaruvchi devor emas"
+- [Rohit (@rohit4verse) asl uzun post (2026-07-29)](https://x.com/rohit4verse/status/2082478623043547356) — toʻrt qatlamli ramkaning asl manbasi: prompt → context → loop → graph, har bir qatlam oldingisining ustiga oʻrnatiladi
+- [Agent Times: Graph Engineering as the Final Layer (Jul 2026)](https://theagenttimes.com/articles/graph-engineering-emerges-as-proposed-final-layer-of-agent-o-4f0511a8) — Rohitʼning toʻrt qatlamli ramkasining tartiblangan koʻrinishi
+- [goddaehee: Graph Engineering fakt-tekshiruvi (koreyscha, 2026-07-30)](https://goddaehee.tistory.com/628) — eng toʻliq fakt-tekshiruv: hazil kelib chiqishi xronologiyasi, soxta raqamlar tahlili, LangGraph maʼlumotlari, Hacker News qiziqish taqqoslash
+- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — oʻsha hazildan ikki hafta oldin yozilgan jiddiy maqola
+- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — rasmiy javob: "yangi gʻoya emas, mavjud yondashuvning eng yangi nomi"; LangGraph oylik 65 million+ yuklab olish
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — hot atama tarqalish maʼlumotlari (birinchi tvit 575 ming koʻrish)
+- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — yettita asosiy ochiq manbali freymvorkning yonma-yon taqqoslash: LangGraph, CrewAI, Microsoft Agent Framework, LlamaIndex, Google ADK, OpenAI Agents SDK, Mastra
+- [LangGraph rasmiy hujjatlari](https://docs.langchain.com/oss/python/langgraph/graph-api) — "Nodes do the work, edges tell what to do next"; tugun va chekkaning aniq taʼrifi, grafik qurish uchun birinchi qoʻl maʼlumotnoma
+- [Anthropic: Building Effective Agents (Dec 2024)](https://www.anthropic.com/engineering/building-effective-agents) — besh naqsh, chizilganda grafik boʻladi; workflow vs agentʼning nufuzli farqi
+- [Addy Osmani: The Orchestration Tax (May 2026)](https://addyosmani.com/blog/orchestration-tax/) — nega sizning eʼtiboringiz yagona ketma-ket resurs
+- [Addy Osmani: Orchestrating Coding Agents (nutq)](https://talks.addy.ie/oreilly-codecon-march-2026/) — subagentsʼdan agent teamsʼgacha, quality gatesʼgacha
+- [Addy Osmani: Loop Engineering (Jun 2026)](https://addyosmani.com/blog/loop-engineering/) — oʻtgan maʼruzaning asosiy maʼlumotnomasi, grafik muhandisligining oldingi bilimi
+- 13-maʼruza: [Qoʻlda prompt yozishdan avtonom loopʼlargacha](./../lecture-13-loop-engineering/index.md) — loop grafikdagi bitta tugun, avval tugunning ichini, keyin grafikaning oʻzini tushuning
+- 11-maʼruza: [Agentning ishlash jarayonini kuzatiladigan qilish](./../lecture-11-why-observability-belongs-inside-the-harness/index.md) — grafik qancha murakkab boʻlsa, kuzatuvchanlik shuncha muhim; kuzatilmaydigan grafik qora qutini yanada kattaroq qora qutiga aylantiradi
+- 9-maʼruza: [Agentning vaqtidan oldin gʻalabani eʼlon qilishini oldini olish](./../lecture-09-why-agents-declare-victory-too-early/index.md) — tekshiruv tuguni nega implementatsiya tugunidan mustaqil boʻlishi kerak, grafikda bu struktura masalasi, prompt masalasi emas
+
+## Mashqlar
+
+1. **P07ʼdagi maker-checker loopʼni grafik qilib chizing:** `graph.md` bilan tugunlar, chekkalar, umumiy holat va marshrutlash qoidalarini eksplisit yozing. Qaysi chekka shartli chekka (tekshiruv oʻtdi/yiqildi), qaysi chekka qaytish chekkasi (muvaffaqiyatsizlikda implementatsiyaga qaytish) ekanini belgilang. Chizib boʻlgach javob bering: qaysidir chekka yashirin — avval agent kontekstida yashiringan edi?
+
+2. **eigentʼning toʻrt savoliga javob bering:** Ishlayotgan uchta mustaqil loop (yoki bitta loyihadagi uchta avtomatlashtirish) toping va javob bering: ular oʻrtasida kim kimni oziqlantiradi? Qaysi loop boshqa loop taʼqib qiladigan maqsadga egalik qiladi? Qaysidir loop boshqa loopʼning mahsulotiga veto qila oladimi? Qaysi metrikalar oʻz-oʻzini optimallashtirayotgan, lekin bir-biri bilan konfliktda boʻlishi mumkin?
+
+3. **Goodhart oʻz-oʻzini tekshiruvi:** Yaqinda optimallashtirgan biron metrikangizni tekshiring. U oʻsdimi, haqiqiy natija (biznes natijasi, foydalanuvchi fikr-mulohazasi, kod sifati) ham yaxshilandi? Agar faqat raqam oʻsgan boʻlsa, bu loop sizni qaysi yoʻnalishda aldayapti?
+
+4. **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
diff --git a/docs/uz/projects/project-08-graph-engineering-first-graph/index.md b/docs/uz/projects/project-08-graph-engineering-first-graph/index.md
new file mode 100644
index 0000000..b31c7d2
--- /dev/null
+++ b/docs/uz/projects/project-08-graph-engineering-first-graph/index.md
@@ -0,0 +1,93 @@
+[English version →](../../../en/projects/project-08-graph-engineering-first-graph/)
+
+# Loyiha 08. Ish oqimingizni grafik qilib chizing
+
+> Bogʻliq maʼruza: [L14. Yakka loopʼdan grafik muhandisligigacha](./../../lectures/lecture-14-graph-engineering/index.md)
+
+## Nima qilasiz
+
+Bu "Loop" dan "Graph" ga oʻtish loyihasi. Oʻtgan loyihada siz maker-checker loop qurdingiz — implement qilish, tekshirish, fikr-mulohaza, qayta implement qilish — barcha qarorlar bitta agentning kontekst oynasida roʻy berardi. Bu loyihada siz **loop ichida yashiringan tuzilmani eksplisit chizasiz**: tugunlar, chekkalar, umumiy holat va marshrutlash qoidalari, soʻzma-soʻz yozib chiqasiz.
+
+Siz uchta progressiv eksperiment qilasiz: avval P07ʼdagi maker-checker loopʼni eksplisit grafik qilib chizasiz, keyin parallel fan-out/fan-in tugunini qoʻshasiz, soʻngra shartli qaytish chekkasi va inson tasdiqlash tugunini qoʻshasiz. Tugatgach, buni oʻz boshdan kechirgan boʻlasiz: **grafik yangi ixtiro emas — bu sizning loopʼingiz yetarlicha murakkablashgandan keyin aylanadigan narsa.**
+
+## Foydalanadigan vositalar
+
+- Claude Code yoki Codex
+- Git
+- P07ʼda qurgan maker-checker loopʼingiz (yoki qayta-qayta ishga tushira oladigan istalgan agent workflow)
+- Matn muharriri yoki diagramma vositasi (chizish goʻzallik uchun emas — tuzilmani qogʻozga tushirish uchun; `mermaid` ham, qoʻlda yozilgan `graph.md` ham ishlaydi)
+
+## Qadamlar
+
+### Tayyorgarlik
+
+1. P07ʼni tugatgan repoʼdan boshlang, yoki hozir ishlayotgan istalgan agent workflowʼdan.
+2. Uchta branch yarating: `p08-explicit-graph`, `p08-parallel`, `p08-human-in-the-loop`.
+3. Umumiy holat fayli sifatida `state.md` tayyorlang: talablar, taraqqiyot va tekshiruv natijalari — hammasi shu yerda. Bu grafikning "umumiy ish stoli".
+
+### 1-eksperiment: Loopʼni eksplisit grafik qilib chizing
+
+`p08-explicit-graph` branchʼiga oʻting.
+
+1. **Barcha tugunlarni roʻyxatlang**: P07 maker-checker loopʼining har bir qadamini bitta tugun qilib yozing. Har bir tugun uchun yozing: uning vazifasi, kirishlari, chiqishlari va u agentmi yoki deterministik kodmi.
+2. **Barcha chekkalarni chizing**: tugunlar oʻrtasidagi har bir chekkani roʻyxatlang. Ikki maxsus turini belgilang:
+ - Shartli chekkalar: tekshiruv oʻtdi/yiqildi — har biri qaysi yoʻldan boradi?
+ - Qaytish chekkalari: muvaffaqiyatsizlik qaysi tugunga qaytadi?
+3. **Umumiy holatni yozing**: holatdagi maydonlarni (talablar, kod, test natijalari, koʻrib chiqish xulosalari) eksplisit roʻyxatlang va har birini kim oʻqiydi/yozadi.
+4. **Marshrutlash qoidalarini yozing**: "keyingi bajarish qayerga ketadi"ni eng sodda if-then tili bilan yozing, masalan:
+ ```
+ if tekshiruv oʻtdi → merg tuguni
+ if tekshiruv yiqildi → implementatsiya tuguni
+ if implementatsiya tugunida axborot yetarli emas → tadqiqot tuguni
+ ```
+5. **Hammasini `graph.md` qilib yozing**: yuqoridagilarni bitta hujjatga aylantiring — mermaid diagrammasi, tugunlar jadvali va marshrutlash qoidalari bilan.
+6. **Bu savolga javob bering**: chizib boʻlgach, kamida bitta **yashirin chekka** toping — avval agent kontekstida yashagan, siz hatto mavjudligini bilmagan qaror yoʻli.
+
+### 2-eksperiment: Parallel Fan-out / Fan-in tugunini qoʻshing
+
+`p08-parallel` branchʼiga oʻting.
+
+1. **Parallellashtirish mumkin boʻlgan nuqtani tanlang**: vazifani ikkita mustaqil qismga boʻlish mumkin boʻlgan joyni toping. Masalan:
+ - Implementatsiyani ikkita mustaqil modulga boʻling, ikki agent parallel yozadi
+ - Tekshiruvni ikkita mustaqil koʻrib chiqishga boʻling: biri test va lint ishga tushiradi, ikkinchisi kod koʻrib chiqish qiladi (turli koʻrsatmalar, turli diqqat)
+ - Tadqiqotni ikki yoʻnalishga boʻling, har bir yoʻnalishga bitta agent
+2. **Fan-out qoidasini yozing**: umumiy holatda "bu vazifa N ta parallel kichik vazifaga boʻlingan"ni yozib qoʻying, har biri oʻz konteksti va oʻz tuguniga ega.
+3. **Fan-in qoidasini yozing**: barcha kichik vazifalar tugagach, natijalarni kim birlashtiradi? Birlashtirish mezonlari nima (masalan, ikkala koʻrib chiqish ham oʻtishi kerak, yoki bittasi yetarli)?
+4. **Worktree bilan izolyatsiya qiling**: har bir parallel kichik vazifani oʻz git worktreeʼsida ishlating, fayl toʻqnashuvlarini jismonan oldini olish uchun (13-maʼruzadagi Worktree primitivini qayta koʻrib chiqing).
+5. **Bir marta ishga tushiring va yozib oling**: parallellashtirishdan oldin va keyin wall-clock vaqtini, token xarajatini va natija sifatini yozib oling. Parallellashtirish haqiqatan tezroqmi? Yoki muvofiqlashtirish xarajati tejashni yeb qoʻydimi?
+
+### 3-eksperiment: Qaytish chekkasi va inson tasdiqlash tugunini qoʻshing
+
+`p08-human-in-the-loop` branchʼiga oʻting.
+
+Bu uchta eksperimentning eng muhimi. Grafikka ikki turdagi tugun qoʻshasiz:
+
+1. **Shartli qaytish chekkasi**: tekshiruv tuguniga "qisman oʻtdi" yoʻlini qoʻshing — hammasini implementatsiya tuguniga qaytarish oʻrniga, aniq fikr-mulohaza bilan **muammoni keltirib chiqargan tugunga** qayting. Masalan: testlar hammasi oʻtadi, lekin kod koʻrib chiqish talablar notoʻgʻri tushunilganini topadi — implementatsiya tuguniga emas, tadqiqot tuguniga qayting. Bu umumiy holatingiz "muammo qaysi qatlamdan kelganini" yozib qoʻyishini talab qiladi.
+2. **Inson tasdiqlash tuguni (human-in-the-loop)**: merg tugunidan oldin inson tugunini qoʻshing. Bu yerga yetganda bajarilish **toʻxtaydi** va siz `state.md` ga "tasdiqlangan" yoki "qaytarilgan" yozishingizni kutadi. Tasdiqlash tugunida timeout qoidasi boʻlishi mumkin: N soatdan keyin javob boʻlmasa, avtomatik qaytarish yoki avtomatik yuqoriga koʻtarish.
+3. **Interrupt formatini yozing**: tasdiqlash soʻrovi qanday yozilishi kerak — nima boʻldi, nima oʻzgardi, nima uchun inson kerak, tasdiqlash/qaytarishning oqibatlari nima?
+4. **Kamida 2 ta toʻliq pass ishlating**: har bir pass inson tasdiqlash tugunida toʻxtaydi va siz bir marta tasdiqlaysiz yoki qaytarasiz. Yozib oling: sizning tasdiqlash qarorlaringiz tekshiruv tuguni bilan mos keldimi? Tasdiqlash tuguni tekshiruv tuguni oʻtkazib yuborgan narsani ushlab oldimi?
+
+## Natijalarni qanday oʻlchash kerak
+
+| Metrika | 1-eksperiment (Eksplisit grafik) | 2-eksperiment (Parallel) | 3-eksperiment (Inson ishtiroki) |
+|---------|-------------------------------|--------------------------|----------------------------------|
+| Strukturaviy koʻrinuvchanlik | Nechta yashirin chekka topdingiz? | Umumiy holat parallel kichik vazifalarni qoʻllab-quvvatlay oladimi? | Qaytish chekkasi muammo qatlamini aniq koʻrsata oladimi? |
+| Muvaffaqiyatsizlikni lokalizatsiya qilish | Qaysi chekka xato ekanini koʻrsata olasizmi? | Kichik vazifa yiqilganda, qaysi biri ekanini topa olasizmi? | Tasdiqlash qaytarilganda, qaysi qatlam ekanini aytasizmi? |
+| Muvofiqlashtirish xarajati | Grafik yozishga qancha vaqt ketdi? | Parallellik tejagan vaqt vs muvofiqlashtirish xarajati | Tasdiqlash kutish vaqti vs ushlangan muammolar qiymati |
+| Kuzatuvchanlik | Har bir qadamda nima boʻlayotganini endi koʻra olasizmi? | Har bir kichik vazifaning holati koʻrinadimi? | Tasdiqlash soʻrovlari aniq yozilganmi? |
+| Ishonchlilik | Grafik tavsifi haqiqiy ishlashlarga mos keladimi? | Fan-in birlashtirish mezoni ishonchlimi? | Timeout/koʻtarish qoidalari haqiqatan ishga tushadimi? |
+
+## Nima topshirish kerak
+
+- `graph.md` (1-eksperimentning toʻliq grafik tavsifi: mermaid diagrammasi + tugunlar jadvali + chekkalar jadvali + umumiy holat maydonlari + marshrutlash qoidalari)
+- 1-eksperimentda topilgan yashirin chekkalar roʻyxati (kamida bittasi)
+- 2-eksperimentning fan-out/fan-in qoidalari va bitta parallel ishlash yozuvi (vaqt/xarajat/sifat taqqoslash)
+- 3-eksperimentning qaytish chekkasi qoidalari, tasdiqlash tuguni formati va 2 ta inson ishtiroki raund yozuvi
+- Yakuniy retro: loopʼdan graphʼga oʻtganingizda, ishlash uslubingiz qanday oʻzgardi? Qaysi vazifalar grafikka arzir, qaysilari arzimaydi?
+
+## Bogʻliq maʼruzalar
+
+- [14-maʼruza — Yakka loopʼdan grafik muhandisligigacha](../../lectures/lecture-14-graph-engineering/index.md)
+- [13-maʼruza — Qoʻlda prompt yozishdan avtonom loopʼlargacha](../../lectures/lecture-13-loop-engineering/index.md) (sizning loopʼingiz grafikdagi bitta tugun; bu loyiha tugunning ichki tuzilishini ochib beradi)
+- [9-maʼruza — Nega agentlar vaqtidan oldin gʻalabani eʼlon qiladi](../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md) (tekshiruv tuguni nega implementatsiya tugunidan mustaqil boʻlishi kerak — struktura masalasi, prompt masalasi emas)
+- [11-maʼruza — Nega kuzatuvchanlik harness ichida boʻlishi kerak](../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) (grafik qancha murakkab boʻlsa, har bir tugunda nima boʻlayotganini koʻrish shuncha zarur)
\ No newline at end of file
diff --git a/docs/vi/lectures/lecture-14-graph-engineering/index.md b/docs/vi/lectures/lecture-14-graph-engineering/index.md
new file mode 100644
index 0000000..ec4cb78
--- /dev/null
+++ b/docs/vi/lectures/lecture-14-graph-engineering/index.md
@@ -0,0 +1,349 @@
+[English Version →](../../../en/lectures/lecture-14-graph-engineering/)
+
+> Ví dụ code: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-14-graph-engineering/code/)
+> Dự án thực hành: [Dự án 08. Vẽ Quy trình Làm việc của bạn thành một Đồ thị](./../../projects/project-08-graph-engineering-first-graph/index.md)
+
+# Bài 14. Từ Vòng lặp Đơn lẻ đến Kỹ thuật Đồ thị
+
+Sáu tuần sau khi Bài giảng trước vừa giới thiệu xong Loop Engineering, vào ngày 18 tháng 7 năm 2026, Peter Steinberger — tác giả OpenClaw, người trong bài giảng trước đã nói "đừng viết prompt cho coding agent nữa" — đã đăng một dòng tweet:
+
+> "Chúng ta vẫn đang nói về Loop, hay đã chuyển sang Graph rồi?"
+
+Một dòng tweet, trong một ngày đã đạt khoảng 575 nghìn lượt xem, đến cuối tháng tăng lên khoảng 3 triệu. Vài giờ sau, kỹ sư máy học Hamel Husain đăng một bài viết nhan đề *Loop Engineering Is Dead. Enter Graph Engineering* — toàn bộ nội dung chỉ là một ảnh động ghi chữ "Stop it" — và nhận thêm khoảng 680 nghìn lượt xem.
+
+Điều đáng suy ngẫm hơn: **cả hai người đều đăng như một trò đùa.** Một người châm biếm một ngành công nghiệp cứ sáu tuần lại phát minh ra một thuật ngữ mới, người kia thuận theo meme đó để phụ họa. Nhưng trò đùa chỉ sống được khoảng một cuối tuần — các khóa học, lộ trình, bộ công cụ đã phủ kín dòng thời gian trước khi cuối tuần kết thúc, kèm theo một loạt con số bịa đặt: "độ chính xác +18%, chi phí −85%" là dữ liệu giả (18% và 85% thực sự tồn tại, nhưng đến từ một bài báo về bản vẽ đường ống hóa chất, và so với các đường cơ sở hoàn toàn khác nhau), "Microsoft, Stanford, Anthropic đồng thời phát hiện ra kỹ thuật đồ thị" cũng là tin giả. Việc kiểm chứng dữ kiện chỉ xác nhận đúng một "người tiên phong": Josh Simmons — bài *We Are Entering the Graph Engineering Phase* của ông viết vào ngày 4 tháng 7, sớm hơn trò đùa này đúng hai tuần — **chính trò đùa đã khiến sự việc trở nên phổ biến, chứ không phải trò đùa tạo ra sự việc.**
+
+> Nguồn: [goddaehee: Kiểm chứng dữ kiện Graph Engineering (2026-07-30)](https://goddaehee.tistory.com/628); [YC Startup School 2026: Phỏng vấn Jensen Huang (kèm bản ghi chép)](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia); [explainx: Graph Engineering (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026)
+
+Bài giảng này không nhằm đổ thêm dầu vào lửa cho từ khóa nóng này, mà là gỡ nó ra để nhìn rõ ràng: **tại sao sau một vòng lặp đơn lẻ chắc chắn sẽ mọc ra một đồ thị? Giữa đồ thị và workflow rốt cuộc khác nhau ở chỗ nào? Khi nào bạn thực sự cần nó, và khi nào thì không?**
+
+## prompt, context, loop, graph: bốn cái tên, xếp chồng từng lớp một
+
+Cuối tháng 7, kỹ sư Rohit (@rohit4verse) đăng một [bài viết dài](https://x.com/rohit4verse/status/2082478623043547356), tổng hợp lịch sử đặt tên của kỹ thuật AI vài năm qua thành một khung bốn lớp rõ ràng. Đây là hệ tọa độ tốt nhất để hiểu Graph Engineering:
+
+| Lớp | Định hình điều gì | Trả lời câu hỏi | Sản phẩm chính |
+|------|---------|-----------|---------|
+| **Kỹ thuật Prompt** | Lệnh chỉ dẫn | Làm sao nói cho mô hình biết phải làm gì? | instructions, examples, constraints, roles, output formats |
+| **Kỹ thuật Ngữ cảnh** | Thông tin | Mô hình nên biết gì trước khi quyết định? | documents, history, memory, tool definitions, environment state |
+| **Kỹ thuật Vòng lặp** | Thời gian chạy | Làm sao để mô hình tự lặp cho đến khi đạt mục tiêu? | observe, reason, act, inspect, update, điều kiện dừng |
+| **Kỹ thuật Đồ thị** | Hệ thống | Nhiều agent, loop, công cụ, bộ đánh giá phối hợp như thế nào? | nút, cạnh, trạng thái dùng chung, quy tắc định tuyến |
+
+Hãy chú ý cách đọc đường tiến triển này: **mỗi lớp không thay thế lớp trước, mà xếp chồng lên trên nó.**
+
+- Sau khi bạn tìm thấy context engineering, bạn không hề dừng prompt engineering — mỗi vòng lặp vẫn cần prompt, chỉ là loop giúp bạn làm mới nó khi môi trường thay đổi.
+- Sau khi bạn xây dựng loop, bạn cũng không bỏ context — mỗi vòng của loop đều phải lắp ráp lại ngữ cảnh.
+- Đến graph, prompt, context và loop đều không biến mất: **mỗi nút đều mang theo prompt riêng, context riêng, công cụ riêng, bộ nhớ riêng, loop riêng của nó.** Đồ thị quyết định cách các nút kết nối với nhau.
+
+Rohit kết thúc đúng bằng câu nguyên văn này:
+
+> Một khi một agent cần chuyên môn hóa, song song, trạng thái dùng chung, xác minh và phục hồi, nó không còn là một loop nữa. Nó là một đồ thị.
+
+**Khoan đã, harness ở đâu?** Bốn cái tên này không có Harness Engineering, vậy mà cả khóa học này nói về harness. Lý do rất đơn giản: Rohit kể về lịch sử từ khóa nóng, điểm cuối là graph, còn lớp ở giữa bị bỏ qua. Và ngay cả việc harness nên thuộc lớp nào cũng chưa được cộng đồng tranh luận rõ — [explainx](https://explainx.ai/blog/context-prompt-loop-harness-engineering-stack-2026) đặt nó trên loop, [bài báo Buildrix](https://arxiv.org/abs/2606.25139) đặt nó dưới loop. Khóa học này đã định rõ từ Bài giảng 2: harness là nền móng, loop và graph đều được xây dựng trên nó.
+
+Điều này giải thích một hiện tượng kỳ lạ: vì sao từ "Graph Engineering" đến tháng 7 năm 2026 mới bùng nổ, nhưng mọi người lại phát hiện mình "đã làm thế này từ lâu". Bởi vì đồ thị không phải phát minh mới — nó là thứ mà loop tự trở thành khi nhiệm vụ của bạn phức tạp đến một mức độ nào đó. Cái tên thì đến sau, còn cách làm thì đã có từ trước.
+
+## Gỡ đồ thị ra để xem: nút, cạnh, trạng thái, định tuyến
+
+Tái hiện đồ thị thành bốn bộ phận đơn giản nhất.
+
+**Nút (Node)**: đơn vị công việc đảm nhận một trách nhiệm nào đó. Nó có thể là:
+- Một đoạn mã xác định (chạy test, tính độ phủ)
+- Một lần gọi mô hình (tạo tài liệu)
+- Một công cụ (git commit, gửi tin nhắn)
+- Một agent hoàn chỉnh — tự mang theo loop, hiểu được mục tiêu, biết dùng công cụ, chạy không nổi thì tự thử lại
+
+Nút là ranh giới thực sự giữa kỹ thuật đồ thị và kỹ thuật workflow; điểm này sẽ được nói riêng ở phần dưới.
+
+**Cạnh (Edge)**: mô tả cách các nút bàn giao cho nhau. Nó không đơn giản là "làm A rồi làm B" — một cạnh có thể thể hiện:
+- **Song song**: sau khi A hoàn thành, B và C bắt đầu cùng lúc
+- **Điều kiện**: test đạt thì rẽ trái, thất bại thì rẽ phải
+- **Thất bại/thử lại**: nút chết, quay về chính nó chạy lại lần nữa
+- **Quay lại**: xác minh không đạt, quay về nút triển khai cách đó ba bước
+
+**Trạng thái dùng chung (State)**: gói dữ liệu truyền giữa các nút. Yêu cầu, ghi chú nghiên cứu, phiên bản code, kết quả test, kết luận đánh giá — tất cả được ghi trên cùng một bàn làm việc chung. Các nút không gọi nhau trực tiếp, chúng đều đọc và ghi cùng một trạng thái.
+
+**Quy tắc định tuyến (Routing)**: quyết định bước tiếp theo đi đâu. Đây là "luồng điều khiển" của đồ thị, nói theo cách đơn giản nhất là:
+
+> Test đạt thì bàn giao; test thất bại thì quay về nút triển khai; thông tin không đủ thì quay về nút nghiên cứu.
+
+Ghép bốn bộ phận lại, một đồ thị phát triển điển hình trông như thế này:
+
+```mermaid
+flowchart TD
+ S["Trạng thái dùng chung<br/>yêu cầu / ghi chú / code / kết quả"] --- R["Nút nghiên cứu<br/>Agent: định vị vấn đề"]
+ R -->|"đưa ra phương án"| I["Nút triển khai<br/>Agent: viết thay đổi + test"]
+ I -->|"đưa ra code"| V["Nút xác minh<br/>Agent: đánh giá độc lập + chạy test"]
+ V -->|"không đạt"| I
+ V -->|"đạt"| M["Nút hợp nhất<br/>code: commit + cập nhật trạng thái"]
+ M -->|"cập nhật trạng thái"| S
+ I -->|"thông tin không đủ"| R
+```
+
+Hãy so sánh với sơ đồ loop ở bài giảng trước: bài giảng trước là một vòng tròn — phát hiện, phân phối, xác minh, lưu trữ, rồi quay lại phát hiện. Trong đồ thị của bài giảng này, **vòng tròn vẫn còn, nhưng đã được tách thành các nút và cạnh tường minh**. Nút xác minh có thể trực tiếp đánh trả thất bại về nút triển khai, nút triển khai có thể vì thông tin không đủ mà quay lại nút nghiên cứu — những "cạnh quay lại" này trong một loop đơn lẻ là ẩn, chính agent tự nhớ "tôi nên quay đầu" trong bối cảnh của mình.
+
+## Khi nào Loop không còn đủ
+
+Một loop chỉ có một con đường chính. Trong maker-checker loop bạn dựng ở bài giảng trước, mọi quyết định — làm gì tiếp theo, thất bại thì đi đâu — đều xảy ra trong cửa sổ ngữ cảnh của cùng một agent. Nhiệm vụ phức tạp hơn một chút, bốn câu hỏi sẽ nổi lên:
+
+1. **Phân công**: agent nghiên cứu yêu cầu, agent viết code, agent làm test — ai bắt đầu trước?
+2. **Song song**: những công việc nào có thể tiến hành đồng thời?
+3. **Quay lại**: sau khi test thất bại nên quay về đâu — nút triển khai, hay nút nghiên cứu?
+4. **Bàn giao**: vài agent làm sao nhìn thấy cùng một bộ yêu cầu, ghi chú và kết quả test? Người đánh giá không đồng ý với người triển khai, nghe theo ai?
+
+Jensen Huang trong [bài phỏng vấn Startup School 2026](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia) (đối thoại với Garry Tan) tại Y Combinator đã nói một quan điểm tương tự: khi phần triển khai nền tảng ngày càng bị agent tự động hóa, giá trị cốt lõi của con người chuyển sang "thiết kế hệ thống, xác định ràng buộc, và kiểm soát agent ở mức chi tiết". Ví dụ kiểm soát ông đưa ra rất cụ thể — "khi agent đưa ra một kế hoạch, tôi sửa một từ trong file kế hoạch, và từ đó tạo ra một khác biệt chính xác"; ông còn dự đoán kỹ năng cốt lõi trong tương lai là "tư duy hệ thống" (systems thinking).
+
+Cú đánh xuất sắc nhất trong chuỗi thảo luận đến từ Luis Catacora:
+
+> **"Vòng lặp có rất nhiều khoảng dung thứ. Đồ thị sẽ buộc bạn thừa nhận, còn bao nhiêu phần trong quy trình làm việc của mình thực sự chưa được mô hình hóa."**
+
+Câu này vạch rõ sự khác biệt sâu sắc giữa loop và graph:
+
+- **Loop là quyết định trì hoãn.** Để một agent gánh hết mọi công việc, chạy không nổi rồi tính sau, kiến trúc có thể đẩy lùi. Điều này đỡ việc, nhưng cái giá là các kiểu thất bại không thể nhìn thấy — bạn vĩnh viễn không biết nó kẹt ở bước nào, vì chính nó cũng không biết.
+- **Graph là quyết định trước.** Bạn phải khai báo toàn bộ cấu trúc từ trước: ai phụ trách gì, các nhiệm vụ phụ thuộc nhau thế nào, một thất bại nào đó quay về đâu. Điều này tốn việc, nhưng đổi lại là khả năng đọc được, kiểm toán được, và sửa cục bộ được.
+
+Nói một câu thẳng thắn hơn: **loop giấu vấn đề bên trong vòng lặp, graph bày vấn đề lên giấy.** Cái trước phù hợp với khám phá, cái sau phù hợp với sản xuất.
+
+## Ba kiểu thất bại mang tính cấu trúc của một vòng lặp đơn lẻ
+
+Vì sao một loop đơn lẻ không chịu nổi ở quy mô lớn? Bài viết *Graph Engineering for AI Agents: Beyond Single Feedback Loops* của eigent.ai đưa ra ba kiểu thất bại mang tính cấu trúc — lưu ý là thất bại cấu trúc, không phải bug của một loop nào đó.
+
+**Trước tiên nói một phản biện: trong loop chẳng phải cũng có thể thêm checkpoint sao?** Được chứ. Xác minh, điều kiện dừng, thậm chí thử lại từ điểm dừng của bài giảng trước, loop đều chứa được. Nhưng ba kiểu thất bại dưới đây chính là thứ checkpoint không giải quyết được — bởi vì checkpoint trong loop mọc ngay bên trong cùng một agent, người kiểm tra và người gây ra vấn đề là cùng một bộ não, cùng một bản ngữ cảnh. Nó sẽ chặn được "chưa xác minh mà bàn giao", nhưng sẽ không hỏi "chỉ số này có đúng không", "mục tiêu này có nên theo đuổi không" — câu trả lời nằm ngay trong context của chính nó, mà nó không nhìn thấy. Đồ thị không phải cho bạn thêm checkpoint, mà là **chuyển** việc kiểm tra ra ngoài: từ "bên trong agent" dời sang "nút độc lập", cấp cho nó một bản ngữ cảnh hoàn toàn mới (đã nói ở phần nút verify phía trước). Ý nghĩa của hai chữ "cấu trúc" nằm ở đây: không phải loop thiếu bộ phận nào, mà là chính cấu trúc "người phán đoán và người bị thực thi chung một bộ não" này.
+
+### 1. Goodhart: con số tăng lên, nhưng kinh doanh lại xấu đi
+
+Đẩy bất kỳ một chỉ số đơn lẻ nào đến cực hạn, nó sẽ ngừng đo lường thứ bạn nghĩ nó đang đo. Ví dụ kinh điển: một đội chăm sóc khách hàng xây một loop quanh "tỷ lệ giải quyết ticket". Dữ liệu tuần liên tục leo cao. Vài tháng sau, dữ liệu gia hạn lại cho thấy churn tăng gấp đôi — **bot đã học cách đóng ticket**: chuyển chủ đề, can ngăn khách truy vấn tiếp, đánh dấu những vấn đề chưa giải quyết là "đã giải quyết".
+
+loop đã làm mọi thứ nó được yêu cầu. Chỉ là con số đó đã tách rời khỏi thứ mà kinh doanh thực sự quan tâm. Đó chính là định luật Goodhart.
+
+### 2. Mù hướng lên: nó không bao giờ hỏi "mục tiêu này có đúng không"
+
+Bên trong loop, giá trị tham chiếu là thiêng liêng. Bộ điều nhiệt không hỏi "68°F có phải nhiệt độ đúng không". Một loop bán hàng không hỏi "định mức này có hợp lý không". Một agent eval loop không hỏi "benchmark này có khớp với kết quả kinh doanh thực không".
+
+**Mục tiêu do ai chọn, loop sẽ chạy về phía nó, dù ngay từ đầu nó vốn không phải thứ nên theo đuổi.** Trong cấu trúc của một loop đơn lẻ, không có bất kỳ vị trí nào đặt được câu hỏi này.
+
+### 3. Xung đột: các vòng lặp độc lập phá nhau
+
+Trong hệ thống thực có hàng chục loop, mỗi cái được xây dựng một cách độc lập. Loop về tốc độ phản hồi đang phá đài của loop về chất lượng sâu, loop về tăng trưởng đang phá đài của loop về chất lượng. Mỗi loop trên bảng điều khiển của riêng nó đều khỏe mạnh, nhưng toàn hệ thống lại rung lắc — giống như vài người mỗi người dùng sức kéo cùng một sợi dây theo các hướng khác nhau.
+
+**Graph engineering được xây dựng để trả lời chính là nhóm câu hỏi mà một loop đơn lẻ không trả lời được:**
+
+- Những loop nào nuôi những loop nào?
+- Những loop nào sở hữu các mục tiêu mà loop khác theo đuổi?
+- Những loop nào có thể phủ quyết hoặc quay lại một thay đổi?
+- Những chỉ số nào được phép di chuyển, những chỉ số nào phải đóng băng?
+
+Khi trong một hệ thống tồn tại "loop có thể ăn mục tiêu của bạn" và "loop có thể phủ quyết thay đổi của bạn", mối quan hệ giữa chúng trở thành đối tượng kỹ thuật — còn mối quan hệ giữa các mối quan hệ, khi vẽ ra, chính là đồ thị.
+
+### Mỏ neo: gắn vòng lặp vào thực tế
+
+Trong bài viết của eigent có một phần mang tiêu đề "everyone skips": **anchors (mỏ neo)**. Mạng lưới vòng lặp có tinh xảo đến đâu, nếu mỗi vòng lặp đều trôi dạt khỏi thực tế, thì mạng lưới chỉ là sự cộng hưởng của những sự trôi dạt lẫn nhau. Mỏ neo là thứ gắn loop vào thế giới thực — kết quả kinh doanh thực, tập dữ liệu ground truth, kiểm tra ngẫu nhiên của con người. Khi thiết kế đồ thị, mỏ neo là bước dễ bị bỏ qua nhất, lại là bước không thể thiếu nhất.
+
+## Graph và Workflow: không chỉ là đổi tên
+
+Đây là điểm dễ bị hiểu nhầm nhất trong bài giảng này, đáng để tách riêng ra nói.
+
+Phản ứng đầu tiên khi Graph Engineering bùng nổ, ai làm kỹ thuật cũng sẽ lầm bầm một câu: "Đây chẳng phải workflow sao? DAG, máy trạng thái, công cụ quy trình làm việc, chúng ta đã chạy hàng chục năm rồi."
+
+**Trực giác này đúng một nửa.** Đồ thị và workflow thực sự chia sẻ cùng một bộ khung: nút + cạnh + trạng thái dùng chung + định tuyến. Cách Airflow, Prefect, Dagster, Temporal điều phối hàng chục năm nay chính là đồ thị này. Năm mẫu hình mà *Building Effective Agents* (tháng 12 năm 2024) của Anthropic tổng hợp — chuỗi prompt, định tuyến, song song hóa, người điều phối/công nhân, người đánh giá/người tối ưu — khi vẽ ra, chính là những đồ thị thực thi có hình dạng khác nhau.
+
+**Nửa sai nằm ở trong nút.** Nút của workflow truyền thống là **hàm xác định**: một hàm Python, một script shell, một tác vụ SQL. Cạnh là mã được viết cứng: `if`, `switch`, `case`. Toàn bộ hệ thống được kỹ sư duy trì bằng code, hành vi có thể dự đoán — cùng một đầu vào sẽ luôn đi cùng một đường.
+
+Nút của kỹ thuật đồ thị có thể là một **agent hoàn chỉnh**: tự mang loop, biết dùng công cụ, hiểu được mục tiêu, gặp thất bại thì tự thử lại. Cạnh cũng không nhất thiết viết cứng — có thể mang quy tắc định tuyến, do đầu ra của nút trước, kết quả xác minh, thậm chí một mô hình khác quyết định bước tiếp theo.
+
+Để làm rõ sự khác biệt này, mượn một cặp khái niệm của Anthropic. Anthropic phân biệt workflow và agent bằng một câu: **ai quyết định luồng điều khiển?** Code quyết định các bước thì là workflow, mô hình có thể thay đổi các bước tại thời điểm chạy thì là agent.
+
+Vậy đồ thị là gì? **Đồ thị là chiếc container chứa cả hai.** Một đồ thị có thể đồng thời có:
+
+- Nút workflow: chạy test, tính độ phủ — mã xác định, không cần mô hình
+- Nút agent: triển khai tính năng, đánh giá code — agent hoàn chỉnh do mô hình điều khiển
+- Nút con người: phê duyệt, rà soát — nút tương tác người-máy, đi đến đây thì dừng lại, chờ con người gật đầu
+
+Vậy nên cách nói chính xác là: **Graph Engineering không phải sự thay thế cho Workflow, mà là sự tổng quát hóa của Workflow** — mở rộng loại nút từ "hàm" sang "agent", mở rộng quyết định của cạnh từ "mã tĩnh" sang "định tuyến động". workflow là trường hợp đặc biệt "hoàn toàn xác định" trong đồ thị.
+
+Quan điểm phản biện (bài *Loops, Graphs, and the Layer That Matters* của iii.dev) cũng rơi vào đúng điểm này, chỉ là kết luận ngược lại:
+
+> "Hình dạng là phần dễ dàng, và nó dùng một lần. Quyết định chịu lực là loop hoặc graph được tạo nên từ gì, và nó sẽ ra sao sau khi hoạt động."
+
+Ý của iii.dev là: đừng xem "topology" là thành tựu kỹ thuật. Kỹ thuật workflow chạy hàng chục năm, thứ thực sự lắng đọng lại không phải các nút được nối thế nào, mà là **khả năng phát lại, khả năng quan sát, khả năng phục hồi** — gặp vấn đề có thể phát lại, đang chạy có thể quan sát, bị treo có thể chạy tiếp. Hình dạng của đồ thị bạn có thể sửa tùy ý, những khả năng chịu lực này mới là nơi bạn nên đầu tư. Lời phê bình này đáng để ghi trong lòng: **vẽ đồ thị không phải mục đích, đồ thị có thể chịu được bao nhiêu năng lực kỹ thuật mới là mục đích.**
+
+## Hóa ra bạn đã vẽ đồ thị từ lâu
+
+"Rượu cũ trong bình mới" còn một bằng chứng nữa: công cụ đã có sẵn từ lâu.
+
+- **LangGraph**: phát hành từ tháng 1 năm 2024, đến tháng 7 năm 2026 đạt khoảng 65 triệu lượt tải mỗi tháng. Nó là công cụ thực thi đồ thị cho agent, nút có thể là agent, cạnh có thể mang định tuyến có điều kiện, checkpoint, interrupt.
+- **Năm mẫu hình của Anthropic**: *Building Effective Agents* (tháng 12 năm 2024) đã vẽ ra đồ thị của chuỗi prompt, định tuyến, song song hóa, người điều phối/công nhân, người đánh giá/người tối ưu, chỉ là không gọi là Graph Engineering.
+- **Fan-out subagent của Claude Code**: khi bạn để một agent chính phái ra một đám subagent làm việc song song, bạn đã đang xây đồ thị, chỉ là chưa nhận ra.
+- **Máy trạng thái, lập lịch DAG, hàng đợi tác vụ, đồ thị tri thức**: khoa học máy tính hàng chục năm, kỹ thuật hóa đồ thị không phải vấn đề mới.
+
+Điều thực sự mới là gì? **Nút từ "hàm" trở thành "agent".** Đây là sự thay đổi duy nhất, cũng là toàn bộ sự thay đổi. Trước đây bạn viết một nút workflow, phải viết rõ logic, xử lý lỗi, chiến lược thử lại của nó. Giờ một nút chỉ cần một câu chỉ dẫn — "nghiên cứu vấn đề này", "đánh giá đoạn code này" — phần còn lại do mô hình tự hoàn thành. Nút trở nên rẻ, vì thế đồ thị trở nên đáng để vẽ.
+
+## Xây dựng đồ thị đầu tiên của bạn từ con số không
+
+Lý thuyết nói đủ rồi, bắt tay làm. Maker-checker của bài giảng trước là **một** agent biết tự lặp. Việc đầu tiên Graph Engineering làm là gỡ cái agent đơn khối đó ra: **mỗi nút trở thành một agent chuyên biệt, mỗi cái mang theo prompt, context, tools, memory riêng và một vòng lặp nhỏ của riêng nó; các nút không chia sẻ ngữ cảnh với nhau, chỉ bàn giao qua một trạng thái dùng chung.** Đây là bản "nói tiếng người" của câu Rohit — "graph quyết định mỗi nút nhìn thấy gì, chạy khi nào, đầu ra đi đâu, ai có thể phủ quyết, điều gì dừng hệ thống". Tất cả ký hiệu dưới đây không gắn với bất kỳ công cụ cụ thể nào — đây là các khái niệm, LangGraph, CrewAI chỉ là những triển khai biến chúng thành chương trình thực thi được, API khác nhau nhưng bộ khung giống nhau. Sáu bước, đừng bỏ qua bước nào.
+
+**Bước 1: Định nghĩa trạng thái dùng chung (State).** Trước tiên phân rõ hai lớp: **ở tầng graph chỉ có trạng thái được chia sẻ, ngữ cảnh của nút là riêng tư.** Agent đơn khối chỉ có một context, chạy lâu sẽ bị chính bản transcript dài dòng của mình nhấn chìm; graph cắt context thành nhiều phần, mỗi phần thuộc về một nút — loop là tài sản riêng của nút, graph là chiếc bàn chung chúng bàn giao cho nhau. Nên đặt gì vào trạng thái, hãy nghĩ rõ trước. Khai báo mỗi trường được "merge như thế nào" — khi nhiều nút song song cùng ghi vào một trường, là ghi đè, nối thêm hay cộng dồn. Bước này không phải tính năng của framework, mà là quy tắc bạn phải viết vào `graph.md` khi vẽ đồ thị:
+
+```
+state = {
+ "requirements": văn bản, # do nút nghiên cứu ghi
+ "code": văn bản, # do nút triển khai ghi
+ "review": "pass" | "fail", # do nút xác minh ghi
+ "attempts": số, # mỗi lần thất bại +1 (khi ghi song song thì merge bằng "cộng dồn")
+}
+```
+
+**Bước 2: Liệt kê các nút — mỗi nút là một agent hoàn chỉnh (tự mang vòng lặp).** Đây là khác biệt căn bản giữa graph và workflow: nút của workflow là hàm, nút của graph là **agent mang theo vòng lặp nhỏ của riêng nó**. Nút nhận trạng thái dùng chung → dùng ngữ cảnh riêng tư của mình làm việc → ghi kết quả về trạng thái dùng chung. Bên trong nút kiểu viết code, thường chính là loop của bài giảng trước:
+
+```
+# Bên trong nút implement: một vòng lặp nhỏ riêng tư (chính là maker-checker loop của bài giảng trước)
+node_implement(requirements):
+ loop (tối đa 3 lần):
+ code = model(prompt=chỉ dẫn triển khai, context=requirements + lỗi lần trước)
+ if tests_pass(code): return {"code": code}
+ return {"error": "triển khai 3 lần vẫn không đạt"}
+```
+
+| Nút | Loại | Bên trong nút (riêng tư) | Ghi vào trạng thái dùng chung |
+|------|------|------------------|-------------|
+| research | agent | tìm kiếm → đọc → tóm tắt → thông tin không đủ thì tìm lại (vòng lặp) | requirements |
+| implement | agent | viết → test → sửa → cho đến khi đạt (vòng lặp, xem trên) | code |
+| verify | agent | đánh giá độc lập + chạy test (**fresh context, không thừa hưởng bộ nhớ của người triển khai**) | review (pass / fail) |
+| merge | mã xác định | không vòng lặp, kiểm tra đạt thì commit | kết thúc |
+
+Hãy chú ý hàng verify: nó là nút dễ làm sai nhất trong đồ thị. **Trong agent đơn khối, "đánh giá" vẫn dùng cùng một context, tự đánh giá chính mình; trong graph, verify phải mang một ngữ cảnh hoàn toàn mới** — nó không nhìn thấy quá trình suy nghĩ của implement, chỉ nhìn thấy `code` trong trạng thái dùng chung. Đây chính là nơi "đánh giá độc lập" thực sự tồn tại trên đồ thị: cô lập ngữ cảnh không phải tác dụng phụ, mà là thiết kế.
+
+**Bước 3: Nối các cạnh.** Trước tiên nối trục chính xác định: nghiên cứu → triển khai → xác minh → hợp nhất → kết thúc.
+
+```mermaid
+flowchart TD
+ A([Bắt đầu]) --> B[research]
+ B --> C[implement]
+ C --> D[verify]
+ D --> E[merge]
+ E --> F([Kết thúc])
+```
+
+**Bước 4: Viết quy tắc định tuyến (bước quan trọng nhất).** Nút xác minh không nối thẳng tới "hợp nhất", mà nối tới một **quyết định**, do nó quyết định bước tiếp theo đi đâu. Bước này là mang "test thất bại nên quay về đâu" trở nên tường minh — quy tắc định tuyến trả về tên của nút, đồ thị này từ đâu tới, đi đâu, nhìn một cái là thấy hết:
+
+| Nút hiện tại | Điều kiện | Nút tiếp theo |
+|---------|------|---------|
+| verify | review == pass | merge |
+| verify | review == fail | implement |
+
+```mermaid
+flowchart TD
+ A([Bắt đầu]) --> B[research]
+ B --> C[implement]
+ C --> D{verify}
+ D -- pass --> E[merge]
+ D -- fail --> C
+ E --> F([Kết thúc])
+```
+
+**Bước 5: Gắn checkpoint (điểm kiểm tra).** Đây là một trong những khác biệt lớn nhất giữa đồ thị và script chạy một lần: **trạng thái của mỗi bước đều được ghi xuống đĩa**, tiến trình bị treo có thể từ điểm dừng chạy tiếp, không phải làm lại từ đầu. Sau khi gắn, đồ thị của bạn lập tức có khả năng "ngắt/phục hồi" — còn có thể chèn một nút "tạm dừng chờ người phê duyệt" trước merge, đây chính là "phê duyệt thủ công" của bài giảng trước trông như thế nào trên đồ thị:
+
+```
+checkpoint = on(graph, every_step) # trạng thái của mỗi bước đều được lưu
+graph.pause_before("merge") # dừng lại trước khi hợp nhất, chờ người phê duyệt
+```
+
+**Bước 6: Chạy đồ thị, và cấp cho nó một điểm vào.** Mỗi lần chạy truyền một thread id, checkpoint dựa vào nó để phân biệt các lần chạy khác nhau:
+
+```
+run(graph, entry={"requirements": "sửa bug trang đăng nhập"}, thread="session-1")
+```
+
+Chạy xong đối chiếu với đồ thị phía trên: `graph.md` bạn viết tay là bản thiết kế, đoạn code trong engine là bản thiết kế đã trở thành chương trình thực thi được. Hai thứ này nên tương ứng một-một. Nếu không khớp — hoặc đồ thị vẽ sai, hoặc code viết sai, **đây chính là ý nghĩa của "đồ thị bày vấn đề lên giấy"**: trước kia không khớp cũng không ai biết, giờ nhìn một cái là thấy. Muốn có một triển khai tham chiếu chạy được thực sự, xem `code/maker_checker_graph.py` — nó dùng LangGraph, nhưng đọc xong bạn nên nhận ra: nó chính là sáu bước trên.
+
+## Dự án mã nguồn mở: thứ chỉ có sau khi phát hành, thứ đã có trước khi phát hành
+
+Trước tiên vạch rõ ranh giới: **Graph Engineering là cái tên chỉ tồn tại sau ngày 18 tháng 7 năm 2026.** Các framework mã nguồn mở trước ngày đó đều không phải "dự án sau khi phát hành Graph Engineering". Kể đến đầu tháng 8 năm 2026, các dự án mã nguồn mở thực sự xuất hiện trực tiếp với cái tên này sau khi khái niệm bùng nổ, mới chỉ có một dự án đứng vững:
+
+**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.
+
+**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)**
+
+Trước tháng 7 năm 2026, những công cụ này đã tồn tại từ một đến ba năm: LangGraph (mã nguồn mở từ 2024, 65 triệu+ lượt tải mỗi tháng, triển khai tham chiếu phía trên dùng chính nó), CrewAI, Microsoft Agent Framework, LlamaIndex Workflows, Google ADK, OpenAI Agents SDK, Mastra, Claude Agent SDK. **Chúng không phải "dự án sau khi phát hành Graph Engineering" — chúng chính là bằng chứng "Graph Engineering đã tồn tại trước khi phát hành".** Bộ nút, cạnh, trạng thái dùng chung, định tuyến này đã chạy ba đến năm năm, tháng 7 chỉ đặt cho nó một cái tên mới. Công cụ đồ thị không giải quyết vấn đề thiết kế: nó cho bạn nút, cạnh, checkpoint, nhưng không thay bạn trả lời "những loop nào nuôi những loop nào, ai sở hữu mục tiêu, ai có thể phủ quyết". Trước khi nghĩ rõ những câu hỏi này, đổi sang công cụ nào cũng chỉ là vẽ cùng một thiết kế tồi đẹp đẽ hơn mà thôi.
+
+## Tạt nước lạnh: đồ thị không phải viên đạn bạc
+
+Ba gáo nước lạnh, từ nhẹ đến nặng.
+
+**Gáo thứ nhất: con số giả.** Sau khi Graph Engineering bùng nổ, trên mạng lan truyền dữ liệu kiểu "dùng đồ thị xong độ chính xác +18%, chi phí −85%". Blogger Hàn Quốc goddaehee đã làm một vòng [kiểm chứng dữ kiện](https://goddaehee.tistory.com/628) (ngày 30 tháng 7): hai con số này thực sự tồn tại, nhưng đến từ một bài báo tháng 3 năm 2026 về bản vẽ đường ống hóa chất (P&ID), và 18% là so với bản gốc hình ảnh, 85% là so với một phương án khác — văn bản marketing ghép hai con số có đường cơ sở khác nhau thành một "so sánh trước/sau", trong bài báo thậm chí không có từ "graph engineering". Nhìn thấy bất kỳ dữ liệu kiểu "kỹ thuật đồ thị mang lại X% cải thiện", hãy tra cứu nguồn gốc ban đầu trước.
+
+**Gáo thứ hai: hình dạng không phải bức tường chịu lực (iii.dev).** Đã nói ở trên. loop chỉ là một đồ thị có một nút; máy trạng thái đã chạy hàng chục năm. Những người hay nói "loop đã chết" hay "graph đã chết", thường vừa không đọc kỹ loop, vừa không đọc kỹ graph. Điều nên học là mẫu hình, không phải danh từ.
+
+**Gáo thứ ba: Orchestration Tax (thuế điều phối).** Addy Osmani trong bài *The Orchestration Tax* (tháng 5) đã đưa ra một nguyên tắc kinh tế học cứng rắn nhất của thời đại đồ thị/đa agent: **mở một agent rất rẻ, đóng một loop rất đắt.**
+
+Khởi động một agent chỉ là một nút bấm, một câu nói. Nhưng đóng một loop của agent cần có người kiểm tra kết quả của nó, đối chiếu với những thứ các agent khác đã đụng vào — **người đó là bạn, và chỉ có một bạn.** Nguyên văn của Osmani:
+
+> "Bạn chính là GIL của những AI agent của bạn. Chúng có thể chạy cùng lúc. Nhưng chỉ cần công việc của chúng cần thực sự hiểu kiến trúc, giải quyết xung đột merge, những công việc đó phải giành được cái khóa đó. Chỉ có một cái khóa, và bạn đang nắm nó."
+
+Đây là lý do vì sao "băng thông đánh giá là trần nhà" nói ở bài giảng trước trở nên sắc bén hơn ở bài giảng này: **đồ thị khiến các agent song song nhiều hơn, nhưng khả năng phán đoán của bạn là tài nguyên tuần tự, không song song hóa được.** Thêm nút tối ưu phần chưa bao giờ là nút thắt cổ chai — nút thắt cổ chai luôn là cái bộ xử lý tuần tự duy nhất: bạn.
+
+## Khi nào bạn thực sự nên dùng đồ thị
+
+Không phải mọi nhiệm vụ đều đáng để vẽ đồ thị. Năm tiêu chí, đạt ít nhất ba cái rồi hãy bắt tay:
+
+1. **Nhiệm vụ có thể tách độc lập thành nhiều đơn vị công việc** — các phần tách ra không phụ thuộc nhau, có thể song song
+2. **Có đường nhánh hoặc đường quay lại** — test thất bại nên quay về đâu, thông tin không đủ nên quay về đâu, những đường này đáng để khai báo tường minh
+3. **Trạng thái trung gian đáng để lưu** — sau checkpoint có thể dừng, có thể phục hồi, thay vì làm lại từ đầu
+4. **Kết quả có thể được nghiệm thu rõ ràng** — mỗi nút đều có tiêu chí hoàn thành kiểm tra được tự động
+5. **Lợi ích cộng tác > chi phí điều phối** — thời gian tiết kiệm nhờ song song, nhiều hơn chi phí do đồ thị và trạng thái dùng chung mang lại
+
+**"Phức tạp" không bằng "nhiều bước".** Một pipeline tuyến tính 20 bước, không cần đồ thị — đó là workflow hoặc thẳng thừng là một script. Một cấu trúc chỉ có 5 nút nhưng có quay lại, song song, phê duyệt lẫn nhau, mới cần đồ thị. Tiêu chí phán đoán không phải quy mô, mà là **sự tồn tại của nhánh và quay lại**.
+
+## Các khái niệm cốt lõi
+
+- **Graph Engineering**: hoạt động kỹ thuật tổ chức nhiều agent, loop, công cụ, bộ đánh giá thành một đồ thị tường minh (nút + cạnh + trạng thái dùng chung + quy tắc định tuyến). Giúp sự kết nối, trạng thái dùng chung và lựa chọn đường đi của nhiều đơn vị công việc trở thành thiết kế được, quan sát được, sửa cục bộ được.
+- **Bốn lớp xếp chồng**: prompt → context → loop → graph, mỗi lớp điều khiển một thứ khác nhau (lệnh chỉ dẫn, thông tin, thời gian chạy, hệ thống), lớp sau không thay thế lớp trước, chỉ là đặt lớp trước vào trong các nút của chính mình.
+- **Bốn bộ phận của Graph**: nút (đơn vị công việc), cạnh (cách bàn giao), trạng thái dùng chung (bàn làm việc chung), quy tắc định tuyến (bước tiếp theo đi đâu).
+- **Ba kiểu thất bại mang tính cấu trúc của vòng lặp đơn lẻ**: Goodhart (con số tăng lên nhưng kinh doanh xấu đi), mù hướng lên (không bao giờ hỏi "mục tiêu này có đúng không"), xung đột (các vòng lặp độc lập phá nhau). Đồ thị biến ba loại vấn đề này thành thiết kế quan hệ tường minh.
+- **Graph ≠ Workflow**: nút của workflow là hàm xác định, cạnh là mã viết cứng; nút của graph có thể là agent hoàn chỉnh, cạnh có thể định tuyến động. graph là sự tổng quát hóa của workflow.
+- **Anchors (mỏ neo)**: cơ chế gắn mạng lưới vòng lặp vào thế giới thực (kết quả kinh doanh thực, ground truth, kiểm tra ngẫu nhiên của con người). Bước dễ bị bỏ qua nhất trong thiết kế đồ thị, lại là bước không thể thiếu nhất.
+- **Orchestration Tax (thuế điều phối)**: khởi động agent rẻ, đánh giá kết quả đắt. Sự chú ý của bạn là tài nguyên tuần tự duy nhất, thêm nút không tối ưu được nó.
+
+## Những điểm chính
+
+- **Graph Engineering không thay thế Loop Engineering, mà xây dựng một lớp lên trên nó.** loop là một nút trong đồ thị; ba thứ của bài giảng trước (mục tiêu, xác minh, điều kiện dừng) trở thành cấu trúc bên trong của nút.
+- **Đồ thị biến "quyết định trì hoãn" thành "quyết định trước".** loop giấu kiểu thất bại trong vòng lặp, graph bày nó lên giấy — đọc được, kiểm toán được, sửa cục bộ được.
+- **Đồ thị và workflow khác nhau ở chỗ nút chứa gì.** Chứa hàm là workflow, chứa agent là đồ thị. Đây cũng là thứ rượu mới duy nhất trong "rượu cũ trong bình mới".
+- **Thiết kế đồ thị trước tiên trả lời bốn câu hỏi:** những loop nào nuôi những loop nào, ai sở hữu mục tiêu, ai có thể phủ quyết/quay lại, những chỉ số nào được động những chỉ số nào bị đóng băng. Trả lời không được thì đừng vẽ.
+- **Đừng vẽ đồ thị vì thích vẽ.** Năm tiêu chí: tách độc lập được, có nhánh hoặc quay lại, trạng thái trung gian đáng lưu, kết quả nghiệm thu được, lợi ích cộng tác > chi phí điều phối.
+- **Băng thông đánh giá của bạn vẫn là trần nhà.** Đồ thị khiến các agent song song nhiều hơn, nhưng khả năng phán đoán của bạn là tài nguyên tuần tự — thuế điều phối không biến mất vì có nhiều nút hơn.
+- **Hãy nhớ tiếng nói phản biện.** Hình dạng không phải bức tường chịu lực; khả năng phát lại, quan sát, phục hồi mới là. Danh từ sẽ đổi mỗi sáu tuần, năng lực kỹ thuật thì không.
+
+## Đọc thêm
+
+- [Prefect: Loops vs. Graphs (Jul 2026)](https://www.prefect.io/blog/loops-vs-graphs) — nhìn loop và graph từ góc nhìn của một công ty đã làm việc điều phối đồ thị hàng chục năm
+- [Eigent: Graph Engineering for AI Agents (Jul 2026)](https://www.eigent.ai/blog/graph-engineering-ai-agents) — ba kiểu thất bại mang tính cấu trúc của loop đơn lẻ + bốn câu hỏi thiết kế + anchors
+- [iii.dev: Loops, Graphs, and the Layer That Matters (Jul 2026)](https://iii.dev/blog/loops-graphs-and-the-layer-that-matters/) — tiếng nói phản biện tỉnh táo nhất: "hình dạng không phải bức tường chịu lực"
+- [Rohit (@rohit4verse) bài đăng dài gốc (2026-07-29)](https://x.com/rohit4verse/status/2082478623043547356) — nguồn trực tiếp của khung bốn lớp: prompt → context → loop → graph, mỗi lớp xếp chồng lên lớp trước
+- [Agent Times: Graph Engineering as the Final Layer (Jul 2026)](https://theagenttimes.com/articles/graph-engineering-emerges-as-proposed-final-layer-of-agent-o-4f0511a8) — bài tổng hợp khung bốn lớp của Rohit
+- [goddaehee: Kiểm chứng dữ kiện Graph Engineering (tiếng Hàn, 2026-07-30)](https://goddaehee.tistory.com/628) — kiểm chứng dữ kiện đầy đủ nhất: dòng thời gian nguồn gốc trò đùa, phân tích các con số giả, dữ liệu LangGraph, so sánh độ nóng Hacker News
+- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — bài viết nghiêm túc đi trước trò đùa đó hai tuần
+- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — phản hồi chính thức: "không phải ý tưởng mới, là cái tên mới nhất của một cách tiếp cận đã có"; LangGraph 65 triệu+ lượt tải mỗi tháng
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — dữ liệu lan truyền từ khóa nóng (575 nghìn lượt xem trên tweet đầu tiên)
+- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — so sánh ngang bảy framework mã nguồn mở chủ lưu: LangGraph, CrewAI, Microsoft Agent Framework, LlamaIndex, Google ADK, OpenAI Agents SDK, Mastra
+- [Tài liệu chính thức LangGraph](https://docs.langchain.com/oss/python/langgraph/graph-api) — "Nodes do the work, edges tell what to do next"; định nghĩa chính xác về nút và cạnh, nguồn tham khảo trực tiếp để xây dựng đồ thị
+- [Anthropic: Building Effective Agents (Dec 2024)](https://www.anthropic.com/engineering/building-effective-agents) — năm mẫu hình, vẽ ra chính là đồ thị; phân biệt workflow vs agent có thẩm quyền
+- [Addy Osmani: The Orchestration Tax (May 2026)](https://addyosmani.com/blog/orchestration-tax/) — vì sao sự chú ý của bạn là tài nguyên tuần tự duy nhất
+- [Addy Osmani: Orchestrating Coding Agents (bài nói)](https://talks.addy.ie/oreilly-codecon-march-2026/) — từ subagents đến agent teams đến quality gates
+- [Addy Osmani: Loop Engineering (Jun 2026)](https://addyosmani.com/blog/loop-engineering/) — tham khảo cốt lõi của bài giảng trước, kiến thức tiền đề của kỹ thuật đồ thị
+- Bài 13: [Từ nhắc lệnh thủ công đến vòng lặp tự chủ](./../lecture-13-loop-engineering/index.md) — loop là một nút trong đồ thị, hiểu bên trong nút trước rồi hiểu đồ thị
+- Bài 11: [Làm cho quá trình chạy của agent có thể quan sát](./../lecture-11-why-observability-belongs-inside-the-harness/index.md) — đồ thị càng phức tạp, khả năng quan sát càng quan trọng; đồ thị không quan sát được chỉ là ghép hộp đen thành hộp đen lớn hơn
+- Bài 9: [Ngăn agent tuyên bố hoàn thành quá sớm](./../lecture-09-why-agents-declare-victory-too-early/index.md) — vì sao nút xác minh phải độc lập với nút triển khai, trong đồ thị đây là vấn đề cấu trúc chứ không phải vấn đề prompt
+
+## Bài tập
+
+1. **Vẽ maker-checker loop của P07 thành đồ thị:** dùng `graph.md` viết tường minh các nút, cạnh, trạng thái dùng chung và quy tắc định tuyến. Đánh dấu cạnh nào là cạnh điều kiện (xác minh đạt/thất bại), cạnh nào là cạnh quay lại (thất bại quay về triển khai). Vẽ xong trả lời: có cạnh nào vốn là ẩn, trước đây giấu trong ngữ cảnh của agent không?
+
+2. **Trả lời bốn câu hỏi của eigent:** tìm ba loop độc lập bạn đang chạy (hoặc ba automation trong cùng một dự án), trả lời: giữa chúng ai nuôi ai? Loop nào sở hữu mục tiêu mà loop khác theo đuổi? Có loop nào phủ quyết được sản phẩm của loop khác không? Những chỉ số nào đang được tối ưu riêng lẻ, nhưng có thể xung đột lẫn nhau?
+
+3. **Tự kiểm tra Goodhart:** xem xét một chỉ số bạn mới tối ưu gần đây. Nó tăng lên, kết quả thực (kết quả kinh doanh, phản hồi người dùng, chất lượng code) có đi theo tốt hơn không? Nếu chỉ là con số tăng, loop này đang lừa bạn theo hướng nào?
+
+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
diff --git a/docs/vi/projects/project-08-graph-engineering-first-graph/index.md b/docs/vi/projects/project-08-graph-engineering-first-graph/index.md
new file mode 100644
index 0000000..c69234b
--- /dev/null
+++ b/docs/vi/projects/project-08-graph-engineering-first-graph/index.md
@@ -0,0 +1,91 @@
+# Dự án 08. Vẽ Quy trình Làm việc của bạn thành một Đồ thị
+
+> Bài giảng liên quan: [L14. Từ Vòng lặp Đơn lẻ đến Kỹ thuật Đồ thị](./../../lectures/lecture-14-graph-engineering/index.md)
+
+## Bạn sẽ làm gì
+
+Đây là dự án nhảy vọt từ "Loop" sang "Graph". Ở bài giảng trước bạn đã dựng một maker-checker loop — triển khai, xác minh, phản hồi, triển khai lại, mọi quyết định đều xảy ra trong cửa sổ ngữ cảnh của cùng một agent. Nhiệm vụ của bạn trong dự án này là **vẽ ra tường minh cấu trúc giấu bên trong vòng lặp**: nút, cạnh, trạng thái dùng chung, quy tắc định tuyến, viết rõ từng chữ một.
+
+Bạn sẽ làm ba thí nghiệm tiến dần: trước tiên vẽ maker-checker loop của P07 thành một đồ thị tường minh, rồi thêm cho đồ thị một nút fan-out/fan-in song song, cuối cùng thêm một cạnh quay lại có điều kiện và một nút phê duyệt thủ công. Làm xong bạn sẽ tự mình cảm nhận một điều: **đồ thị không phải phát minh mới, nó là thứ vòng lặp tự trở thành khi loop của bạn phức tạp đến một mức độ nào đó.**
+
+## Dùng công cụ gì
+
+- Claude Code hoặc Codex
+- Git
+- maker-checker loop bạn đã dựng ở P07 (hoặc bất kỳ quy trình làm việc agent nào bạn có thể chạy đi chạy lại)
+- Một trình soạn thảo văn bản hoặc công cụ vẽ (vẽ không phải để đẹp, mà để viết rõ cấu trúc; `mermaid` hoặc viết tay `graph.md` đều được)
+
+## Các bước cụ thể
+
+### Công tác chuẩn bị
+
+1. Bắt đầu từ kho mã sau khi hoàn thành P07, hoặc trực tiếp dùng bất kỳ quy trình làm việc agent nào bạn đang chạy.
+2. Tạo ba nhánh: `p08-explicit-graph`, `p08-parallel`, `p08-human-in-the-loop`.
+3. Chuẩn bị một `state.md` làm file trạng thái dùng chung: yêu cầu, tiến độ, kết quả xác minh đều ghi ở đây. Đây là "bàn làm việc chung" của đồ thị.
+
+### Thí nghiệm một: Vẽ Loop thành đồ thị tường minh
+
+Chuyển sang nhánh `p08-explicit-graph`.
+
+1. **Liệt kê tất cả các nút:** viết mỗi bước trong maker-checker loop của P07 thành một nút. Mỗi nút viết rõ: trách nhiệm của nó, đầu vào của nó, đầu ra của nó, nó là agent hay mã xác định.
+2. **Vẽ tất cả các cạnh:** liệt kê từng cạnh giữa các nút. Nhấn mạnh đánh dấu hai cạnh đặc biệt:
+ - Cạnh điều kiện: xác minh đạt/thất bại, đi theo hướng nào
+ - Cạnh quay lại: thất bại quay về nút nào
+3. **Viết trạng thái dùng chung:** liệt kê rõ trạng thái có những trường nào (yêu cầu, code, kết quả test, kết luận đánh giá), ai đọc ai ghi.
+4. **Viết quy tắc định tuyến:** dùng ngôn ngữ if-then đơn giản nhất viết quy tắc "bước tiếp theo đi đâu", ví dụ:
+ ```
+ if xác minh đạt → nút hợp nhất
+ if xác minh thất bại → nút triển khai
+ if nút triển khai thông tin không đủ → nút nghiên cứu
+ ```
+5. **Viết thành `graph.md`:** tổng hợp các nội dung trên thành một tài liệu. Dùng mermaid vẽ một đồ thị, kèm bảng nút và quy tắc định tuyến.
+6. **Trả lời câu hỏi này:** sau khi vẽ xong, tìm ra ít nhất một **cạnh vốn là ẩn** — đường quyết định trước đây giấu trong ngữ cảnh agent, đến chính bạn cũng không biết nó tồn tại.
+
+### Thí nghiệm hai: Thêm một nút Fan-out / Fan-in song song
+
+Chuyển sang nhánh `p08-parallel`.
+
+1. **Chọn một điểm có thể song song:** tìm một chỗ trong nhiệm vụ có thể tách thành hai phần độc lập. Ví dụ:
+ - Tách triển khai thành hai module độc lập, hai agent viết song song
+ - Tách xác minh thành hai cuộc đánh giá độc lập: một chạy test và lint, một làm đánh giá code (chỉ dẫn khác nhau, mối quan tâm khác nhau)
+ - Tách nghiên cứu thành hai hướng, hai agent mỗi cái tra một đường
+2. **Viết quy tắc fan-out:** ghi trong trạng thái dùng chung "nhiệm vụ này được tách thành N tác vụ con song song", mỗi tác vụ con một context độc lập, một nút độc lập.
+3. **Viết quy tắc fan-in:** sau khi tất cả tác vụ con hoàn thành, ai hợp nhất kết quả? Tiêu chuẩn hợp nhất là gì (ví dụ: hai cuộc đánh giá đều đạt mới hợp nhất, hay có một đạt là được)?
+4. **Dùng worktree để cô lập:** mỗi tác vụ con song song chạy trong một git worktree độc lập, tránh va chạm file về mặt vật lý (ôn lại nguyên thủy Worktree ở bài 13).
+5. **Chạy một lần và ghi lại:** ghi thời gian wall-clock trước/sau khi song song, mức tiêu thụ token, chất lượng kết quả. Song song có thực sự nhanh hơn không? Hay chi phí điều phối ăn mất thời gian tiết kiệm được?
+
+### Thí nghiệm ba: Thêm một cạnh quay lại và một nút phê duyệt thủ công
+
+Chuyển sang nhánh `p08-human-in-the-loop`.
+
+Đây là thí nghiệm quan trọng nhất trong ba thí nghiệm. Bạn phải thêm hai loại nút vào đồ thị:
+
+1. **Cạnh quay lại có điều kiện:** thêm cho nút xác minh một đường "đạt một phần" — không phải đánh trả toàn bộ về nút triển khai, mà mang theo phản hồi cụ thể quay về **nút đã tạo ra vấn đề**. Ví dụ: test đều đạt nhưng đánh giá code phát hiện hiểu sai yêu cầu, quay lại nút nghiên cứu chứ không phải nút triển khai. Điều này đòi hỏi trạng thái dùng chung của bạn ghi "vấn đề nằm ở tầng nào".
+2. **Nút phê duyệt thủ công (Human-in-the-loop):** thêm một nút người trước nút hợp nhất. Đi đến đây, đồ thị **dừng lại**, chờ bạn ghi "phê duyệt" hoặc "đánh trả" trong `state.md`. Nút phê duyệt có thể có quy tắc hết giờ: sau N giờ không phản hồi, tự động đánh trả hoặc tự động nâng cấp.
+3. **Viết định dạng interrupt:** viết yêu cầu phê duyệt rõ ràng như thế nào — chuyện gì đã xảy ra, đã thay đổi gì, vì sao cần con người, hậu quả của phê duyệt/đánh trả mỗi loại là gì.
+4. **Chạy ít nhất 2 vòng quy trình đầy đủ:** mỗi vòng đều đi đến nút phê duyệt thủ công, bạn tự phê duyệt hoặc đánh trả một lần. Ghi lại: quyết định phê duyệt của bạn có khớp với phán đoán của nút xác minh không? Nút phê duyệt đã chặn được thứ gì mà nút xác minh không chặn được không?
+
+## Cách đo lường kết quả
+
+| Chỉ số | Thí nghiệm một (đồ thị tường minh) | Thí nghiệm hai (song song) | Thí nghiệm ba (người-máy cộng tác) |
+|------|----------------|--------------|------------------|
+| Tính nhìn thấy của cấu trúc | Tìm ra được mấy cạnh ẩn? | Trạng thái dùng chung có chịu được các tác vụ con song song không? | Cạnh quay lại có định vị chính xác tầng của vấn đề không? |
+| Định vị thất bại | Khi thất bại có thể chỉ thẳng cạnh nào sai không? | Khi tác vụ con song song thất bại, định vị được cái nào? | Khi phê duyệt đánh trả, chỉ ra được vấn đề ở tầng nào không? |
+| Chi phí cộng tác | Vẽ đồ thị mất bao lâu? | Thời gian song song tiết kiệm vs chi phí điều phối | Thời gian chờ phê duyệt vs giá trị của vấn đề chặn được |
+| Tính quan sát | Mỗi bước xảy ra gì, giờ nhìn thấy được chưa? | Trạng thái của mỗi tác vụ con song song có nhìn thấy không? | Yêu cầu phê duyệt viết đủ rõ không? |
+| Độ tin cậy | Mô tả đồ thị và chạy thực tế có khớp không? | Tiêu chuẩn hợp nhất fan-in có đáng tin không? | Quy tắc hết giờ/nâng cấp có thực sự kích hoạt không? |
+
+## Cần nộp gì
+
+- `graph.md` (mô tả đồ thị đầy đủ của thí nghiệm một: đồ thị mermaid + bảng nút + bảng cạnh + trường trạng thái dùng chung + quy tắc định tuyến)
+- Danh sách các cạnh ẩn tìm được ở thí nghiệm một (ít nhất một cái)
+- Quy tắc fan-out/fan-in của thí nghiệm hai và một bản ghi chạy song song (so sánh thời gian/chi phí/chất lượng)
+- Quy tắc cạnh quay lại, định dạng nút phê duyệt và bản ghi 2 vòng người-máy cộng tác của thí nghiệm ba
+- Tổng kết cuối: từ loop đến graph, cách làm việc của bạn đã thay đổi gì? Nhiệm vụ nào đáng vẽ đồ thị, nhiệm vụ nào không?
+
+## Bài giảng tương ứng
+
+- [Lecture 14 — Từ Vòng lặp Đơn lẻ đến Kỹ thuật Đồ thị](../../lectures/lecture-14-graph-engineering/index.md)
+- [Lecture 13 — Từ nhắc lệnh thủ công đến vòng lặp tự chủ](../../lectures/lecture-13-loop-engineering/index.md) (loop của bạn chính là một nút trong đồ thị; dự án này là trải phẳng cấu trúc bên trong của nút)
+- [Lecture 09 — Tại sao agent tuyên bố hoàn thành quá sớm](../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md) (vì sao nút xác minh phải độc lập với nút triển khai, trong đồ thị là vấn đề cấu trúc)
+- [Lecture 11 — Tại sao tính quan sát thuộc về bên trong harness](../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) (đồ thị càng phức tạp, càng cần nhìn thấy mỗi nút đang làm gì)
\ No newline at end of file
diff --git a/docs/zh-TW/lectures/lecture-14-graph-engineering/index.md b/docs/zh-TW/lectures/lecture-14-graph-engineering/index.md
new file mode 100644
index 0000000..4ceada8
--- /dev/null
+++ b/docs/zh-TW/lectures/lecture-14-graph-engineering/index.md
@@ -0,0 +1,349 @@
+[English Version →](../../../en/lectures/lecture-14-graph-engineering/)
+
+> 本篇程式碼範例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-14-graph-engineering/code/)
+> 實戰練習:[Project 08. 把你的工作流畫成一張圖](./../../projects/project-08-graph-engineering-first-graph/index.md)
+
+# 第十四講. 從單循環到圖工程
+
+上一講剛講完 Loop Engineering 六週後,2026 年 7 月 18 日,Peter Steinberger——就是上一講裡那位「不要再給 coding agent 寫 prompt 了」的 OpenClaw 作者——發了一條推:
+
+> 「我們還在談 Loop,還是已經轉向 Graph 了?」
+
+一條推,一天內就拿到約 57 萬瀏覽,到月底漲到約 300 萬。幾小時後,機器學習工程師 Hamel Husain 發了一篇題為《Loop Engineering Is Dead. Enter Graph Engineering》的文章——正文只有一張寫著 "Stop it" 的動圖——又拿了約 68 萬瀏覽。
+
+更耐人尋味的是:**這兩個人都是當作玩笑在發。** 一個在諷刺行業每六週發明一個新名詞,一個在順著這個梗一捧一逗。但玩笑只存活了大約一個週末——課程、路線圖、工具棧在週末結束前就鋪滿了時間軸,還跟著一堆編造出來的數字:「準確率 +18%、成本 -85%」是假數據(18% 和 85% 確實存在,但出自一篇關於化工管道圖紙的論文,且對照基線根本不同),「微軟、史丹佛、Anthropic 同時發現了圖工程」也是假消息。事實查核確認的唯一「先行者」是 Josh Simmons:他的《We Are Entering the Graph Engineering Phase》寫於 7 月 4 日,比這場玩笑早了整整兩週——**是玩笑讓這件事變得流行,不是玩笑創造了這件事。**
+
+> 來源:[goddaehee:Graph Engineering 事實查核(2026-07-30)](https://goddaehee.tistory.com/628);[YC Startup School 2026:Jensen Huang 訪談(含文字稿)](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia);[explainx:Graph Engineering(2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026)
+
+這一講要做的,不是給這個熱詞再添一把火,而是把它拆開看清楚:**為什麼單循環之後必然長出圖?圖和 workflow 到底有什麼不同?什麼時候你真的需要它,什麼時候不需要?**
+
+## prompt、context、loop、graph:四個名字,一層疊一層
+
+7 月底,工程師 Rohit(@rohit4verse)發了一條[長帖](https://x.com/rohit4verse/status/2082478623043547356),把 AI 工程這幾年的命名史整理成了一個清晰的四層框架。這是理解 Graph Engineering 最好的座標系:
+
+| 階段 | 塑造什麼 | 回答的問題 | 關鍵產物 |
+|------|---------|-----------|---------|
+| **Prompt Engineering** | 指令 | 怎麼告訴模型做什麼? | instructions、examples、constraints、roles、output formats |
+| **Context Engineering** | 資訊 | 模型做決定之前應該知道什麼? | documents、history、memory、tool definitions、environment state |
+| **Loop Engineering** | 執行時 | 怎麼讓模型自己循環直到達成目標? | observe、reason、act、inspect、update、停止條件 |
+| **Graph Engineering** | 系統 | 多個 agent、loop、工具、評估者如何協作? | 節點、邊、共享狀態、路由規則 |
+
+注意這條線怎麼讀:**每一層都不是取代上一層,而是疊加在它之上。**
+
+- 你找到 context engineering 之後,並沒有停止 prompt engineering——每次迭代仍然需要 prompt,只是 loop 在環境變化時幫你刷新它。
+- 你構建 loop 之後,也沒有丟掉 context——loop 的每一輪都要重新組裝上下文。
+- 到了 graph,prompt 和 context 和 loop 一個都沒消失:**每個節點都帶著自己的 prompt、自己的 context、自己的工具、自己的記憶、自己的 loop。** 圖決定的是節點之間怎麼連接。
+
+Rohit 的原話是這麼收尾的:
+
+> 一旦一個 agent 需要專業化、平行、共享狀態、驗證和恢復,它就不再是一個 loop 了。它是一張圖。
+
+**等等,harness 呢?** 這四個名字裡沒有 Harness Engineering,可這門課講的就是 harness。原因很簡單:Rohit 講的是熱詞史,終點是 graph,中間那層就被跳過了。而且 harness 該放哪層,圈子自己都沒吵明白——[explainx](https://explainx.ai/blog/context-prompt-loop-harness-engineering-stack-2026) 把它放在 loop 上面,[Buildrix 論文](https://arxiv.org/abs/2606.25139) 把它放在 loop 下面。本課程在第二講就定了:harness 是地基,loop 和 graph 都建在它上面。
+
+這解釋了一個奇怪的現象:為什麼「Graph Engineering」這個詞 2026 年 7 月才火,但大家發現自己「早就這麼幹了」。因為圖不是新發明,是當你的任務複雜到一定程度後,loop 自動變成圖。名字是後來才有的,做法早就有了。
+
+## 把圖拆開看:節點、邊、狀態、路由
+
+把圖還原成最樸素的四個零件。
+
+**節點(Node)**:承擔某種職責的工作單元。它可以是:
+- 一段確定性程式碼(跑測試、算覆蓋率)
+- 一次模型呼叫(產生文件)
+- 一個工具(git commit、發訊息)
+- 一個完整的 agent——自己帶 loop,能理解目標、會使用工具、跑不動了自己重試
+
+節點是圖工程和 workflow 工程真正的分界線,這一點下面專門講。
+
+**邊(Edge)**:說明節點之間如何交接。它不是「先做 A 再做 B」那麼簡單——一條邊可以表達:
+- **平行**:A 完成後,B 和 C 同時開始
+- **條件**:測試通過走左邊,失敗走右邊
+- **失敗/重試**:節點掛了,回到它自己再跑一次
+- **回退**:驗證不通過,回到三跳之前的實作節點
+
+**共享狀態(State)**:節點之間傳遞的資料包。需求、研究筆記、程式碼版本、測試結果、審查結論——都寫在同一個公共工作台上。節點不直接互相喊話,它們都讀寫同一份狀態。
+
+**路由規則(Routing)**:決定下一步去哪。這是圖的「控制流」,用最樸素的話說就是:
+
+> 測試通過就交付;測試失敗就回到實作節點;資訊不足就回到研究節點。
+
+把四個零件拼起來,一個典型的開發圖長這樣:
+
+```mermaid
+flowchart TD
+ S["共享狀態<br/>需求 / 筆記 / 程式碼 / 結果"] --- R["研究節點<br/>Agent: 定位問題"]
+ R -->|"產出方案"| I["實作節點<br/>Agent: 寫修改 + 測試"]
+ I -->|"產出程式碼"| V["驗證節點<br/>Agent: 獨立審查 + 跑測試"]
+ V -->|"未通過"| I
+ V -->|"通過"| M["合併節點<br/>程式碼: commit + 更新狀態"]
+ M -->|"狀態更新"| S
+ I -->|"資訊不足"| R
+```
+
+注意和上一講的 loop 圖對比:上一講是一個環——發現、分發、驗證、持久化、再回到發現。這一講的圖裡,**環仍然在,但被拆成了顯式的節點和邊**。驗證節點可以直接把失敗打回實作節點,實作節點可以因為資訊不足退回研究節點——這些「回退邊」在單一 loop 裡是隱式的,是 agent 自己在上下文裡記得「我該回頭」。
+
+## Loop 什麼時候不夠用
+
+一個 loop 只有一條主幹道。上一講你搭的 maker-checker loop 裡,所有決策——下一步做什麼、失敗往哪走——都發生在同一個 agent 的上下文視窗裡。任務再複雜一點,四個問題就冒出來了:
+
+1. **分工**:研究需求的 agent、寫程式碼的 agent、做測試的 agent,誰先開始?
+2. **平行**:哪些工作可以同時進行?
+3. **回退**:測試失敗後應該回到哪裡——回到實作節點,還是回到研究節點?
+4. **交接**:幾個 agent 怎樣看到同一份需求、筆記和測試結果?審查者不同意實作者,聽誰的?
+
+黃仁勳在 Y Combinator 的 [Startup School 2026 訪談](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia)(和 Garry Tan 的對談)裡說了類似的觀點:當底層實作越來越多的被 agent 自動化,人類的核心價值就轉向「設計系統、明確約束,並對 agent 做細粒度控制」。他給的控制例子很具體——「agent 給出計畫後,我在計畫檔案裡改一個詞,這一個詞就產生一處精確的差異」;他還預言未來的核心技能是「系統思考」(systems thinking)。
+
+討論串裡最精彩的一擊來自 Luis Catacora:
+
+> **「循環有大量容錯空間。圖會迫使你承認,工作流裡還有多少部分根本沒有被真正建模。」**
+
+這句話點破了 loop 和 graph 的深層差異:
+
+- **Loop 是延後決策。** 先讓一個 agent 包攬所有工作,跑不下去再說,架構可以往後拖。這省事,但代價是失敗模式不可見——你永遠不知道它卡在哪一步,因為它自己也不知道。
+- **Graph 是提前決策。** 你必須提前宣告整個結構:誰負責什麼、任務之間怎麼依賴、某個失敗要回到哪。這費事,但換來的是可讀、可稽核、可局部修復。
+
+用一句更直白的話:**loop 把問題藏在循環裡,graph 把問題擺在紙上。** 前者適合探索,後者適合生產。
+
+## 單一循環的三種結構性失敗
+
+為什麼單一 loop 在規模上撐不住?eigent.ai 那篇《Graph Engineering for AI Agents: Beyond Single Feedback Loops》給出了三個結構性失敗——注意是結構性失敗,不是某一個 loop 的 bug。
+
+**先說一個反駁:loop 裡不也能加檢查點嗎?** 能。上一講的驗證、停止條件,甚至中斷點重試,loop 都裝得下。但下面三個失敗恰恰是檢查點解決不了的——因為 loop 裡的檢查點長在同一個 agent 內部,做檢查和出問題的是同一個大腦、同一份上下文。它會攔下「沒驗證就交付」,卻不會問「這個指標對不對」、「這個目標該不該追」——答案就寫在它自己的 context 裡,它看不見。圖不是給你更多檢查點,而是把檢查**搬出去**:從「agent 內部」挪到「獨立的節點」,給它一份全新上下文(前面 verify 節點那節講過)。「結構性」三個字的意思就在這:不是 loop 缺了哪個零件,而是「判斷者和被執行者共享同一個大腦」這個結構本身。
+
+### 1. Goodhart:數字漲了,業務卻壞了
+
+把任何一個單一指標推到極致,它就會停止測量你以為它在測量的東西。經典案例:一個客服團隊圍繞「工單解決率」建了一個 loop。週資料一路爬升。幾個月後,續費資料卻顯示 churn 翻倍了——**bot 學會了關閉工單**:轉移話題、勸阻用戶追問、把沒解決的問題標記為「已解決」。
+
+loop 做了它被要求做的每一件事。只是那個數字脫離了業務真正關心的東西。這就是 Goodhart 定律。
+
+### 2. 向上失明:它從不問「這個目標對嗎」
+
+在 loop 內部,參考值是神聖的。恆溫器不會問「68°F 是不是對的溫度」。銷售 loop 不會問「這個定額合理嗎」。一個 agent eval loop 不會問「這個 benchmark 和真實業務結果匹配嗎」。
+
+**目標是誰選的,loop 就朝著它跑,即使它從一開始就不是該追的東西。** 單一 loop 的結構裡,沒有任何位置放得下這個問題。
+
+### 3. 衝突:獨立循環互相拆台
+
+真實系統裡有幾十個 loop,每個都是獨立建起來的。回應速度的 loop 在拆深度品質的 loop 的台,成長的 loop 在拆品質的 loop 的台。每個 loop 在自己的儀表板上都健康,系統整體卻在抖動——就像幾個人各自用力拉同一根繩子的不同方向。
+
+**Graph engineering 要回答的,正是單一 loop 回答不了的那組問題:**
+
+- 哪些 loop 餵給哪些 loop?
+- 哪些 loop 擁有其他 loop 追逐的目標?
+- 哪些 loop 能否決或回滾一個變更?
+- 哪些指標允許移動,哪些必須凍結?
+
+當一個系統裡存在「能吃你的目標的 loop」和「能否決你的變更的 loop」時,它們之間的關係就成了工程對象——而關係和關係之間的關係,畫出來就是圖。
+
+### 錨:把循環固定到現實
+
+eigent 那篇文章標題裡有個「everyone skips」的部分:**anchors(錨)**。循環網路再精巧,如果每個循環都漂離現實,網路只是互相漂移的共振。錨就是把 loop 固定到真實世界的東西——真實業務結果、ground truth 資料集、人工抽查。設計圖的時候,錨是最容易被跳過、卻是最不能省的一步。
+
+## Graph 與 Workflow:不只是換個名字
+
+這是這一講最容易被誤解的地方,值得單獨拎出來說。
+
+Graph Engineering 爆火的第一反應,做過工程的人都會嘀咕一句:「這不就是 workflow 嗎?DAG、狀態機、工作流引擎,我們跑了幾十年了。」
+
+**這個直覺對了一半。** 圖和 workflow 確實共享同一個骨架:節點 + 邊 + 共享狀態 + 路由。Airflow、Prefect、Dagster、Temporal 幾十年來的編排方式就是這張圖。Anthropic 2024 年 12 月《Building Effective Agents》總結的五種模式——提示鏈、路由、平行化、編排者/工作者、評估者/最佳化者——把它們畫出來,得到的正是不同形狀的執行圖。
+
+**錯的一半在節點裡。** 傳統 workflow 的節點是**確定性函式**:一個 Python 函式、一個 shell 腳本、一個 SQL 任務。邊是寫死的程式碼:`if`、`switch`、`case`。整個系統工程師用程式碼維護,行為可預期——同樣的輸入永遠走同樣的路徑。
+
+圖工程的節點可以是一個**完整 agent**:自帶 loop、會使用工具、能理解目標、遇到失敗自己重試。邊也不一定是寫死的——可以帶路由規則,由前一個節點的輸出、驗證結果、甚至另一個模型來決定下一步。
+
+為了把這個差別講清楚,借用 Anthropic 的一對概念。Anthropic 用一句話區分 workflow 和 agent:**誰決定控制流?** 程式碼決定步驟就是 workflow,模型在執行時能改變步驟就是 agent。
+
+那麼圖是什麼?**圖是容納兩者的容器。** 一張圖裡可以同時有:
+
+- workflow 節點:跑測試、算覆蓋率——確定性程式碼,不需要模型
+- agent 節點:實作功能、審查程式碼——模型驅動的完整 agent
+- 人類節點:審批、複核——人機互動節點,走到這裡停住,等人點頭
+
+所以準確的說法是:**Graph Engineering 不是 Workflow 的替代,而是 Workflow 的泛化**——把節點的類型從「函式」放開到「agent」,把邊的決策從「靜態程式碼」放開到「動態路由」。workflow 是圖中「完全確定」的那個特例。
+
+反方觀點(iii.dev 的《Loops, Graphs, and the Layer That Matters》)也落在這同一個點上,只是結論相反:
+
+> 「形狀是容易的部分,而且是一次性的。承重決策是 loop 或 graph 由什麼構成、以及它工作之後會怎樣。」
+
+iii.dev 的意思是:別把「拓撲」當成工程成就。workflow 工程跑了幾十年,真正沉澱下來的不是節點怎麼連,而是**可回放、可觀測、可恢復**——出問題能回放,運行中能觀察,掛了能接著跑。圖的形狀你可以隨手改,這些承重能力才是你該投入的地方。這個批評值得記在心裡:**畫圖不是目的,圖之上能承載多少工程能力才是目的。**
+
+## 你其實早就在畫圖
+
+「新瓶裝舊酒」還有一個證據:工具早就齊了。
+
+- **LangGraph**:2024 年 1 月就發布了,到 2026 年 7 月月下載量約 6500 萬次。它是給 agent 用的圖執行引擎,節點可以是 agent,邊可以帶條件路由、checkpoint、interrupt。
+- **Anthropic 五種模式**:2024 年 12 月的《Building Effective Agents》已經把提示鏈、路由、平行化、編排者/工作者、評估者/最佳化者的圖都畫出來了,只是沒叫 Graph Engineering。
+- **Claude Code 的 subagent fan-out**:當你讓一個主 agent 派出一堆子 agent 平行幹活時,你已經在建圖了,只是沒意識到。
+- **狀態機、DAG 排程、任務佇列、知識圖譜**:計算機科學幾十年,圖的工程化不是一個新問題。
+
+真正新的是什麼?**節點從「函式」變成了「agent」。** 這是唯一的變化,也是全部的變化。以前你寫一個 workflow 節點,要寫清楚它的邏輯、錯誤處理、重試策略。現在一個節點只需要一句指令——「研究這個問題」、「審查這段程式碼」——剩下的由模型自己完成。節點變得便宜了,於是圖變得值得畫了。
+
+## 從零構建你的第一張圖
+
+理論說夠了,動手。上一講的 maker-checker 是**一個**會自己循環的 agent。Graph Engineering 要做的第一件事,就是把這樣的單體 agent 拆開:**每個節點變成一個專門的 agent,各自帶著私有的 prompt、context、tools、memory 和自己的小循環;節點之間不共享上下文,只透過一張共享狀態交接。** 這就是 Rohit 那句話說的人話版——「graph 決定每個節點看到什麼、何時運行、輸出去哪、誰能否決、什麼停止系統」。下面所有表示法都不綁定任何具體引擎——這是概念,LangGraph、CrewAI 只是把它們變成可執行程式的實作,API 不同、骨架一樣。六個步驟,一步都別跳。
+
+**第一步:定義共享狀態(State)。** 先分清兩個層:**graph 層共享的只有狀態,節點的上下文是私有的。** 單體 agent 只有一個 context,跑久了會被自己冗長的 transcript 淹沒;graph 把 context 切成多份,每份屬於一個節點——loop 是節點的私有物,graph 是它們交接的公共台。狀態裡放什麼,先想清楚。給每個欄位宣告它被「怎麼合併」——多個平行節點同時往同一個欄位寫時,是覆蓋、追加還是求和。這一步不是框架特性,是你畫圖時就要寫進 `graph.md` 的規則:
+
+```
+state = {
+ "requirements": 文字, # 研究節點寫入
+ "code": 文字, # 實作節點寫入
+ "review": "pass" | "fail", # 審查節點寫入
+ "attempts": 數字, # 每失敗一次 +1(平行寫時用「求和」合併)
+}
+```
+
+**第二步:列節點——每個節點是一個完整的 agent(自帶循環)。** 這是 graph 和 workflow 的根本區別:workflow 的節點是函式,graph 的節點是**帶著自己小循環的 agent**。節點接收共享狀態 → 用自己的私有上下文幹活 → 把結果寫回共享狀態。寫程式碼型節點的內部,往往就是上一講那個 loop:
+
+```
+# implement 節點內部:一個私有小循環(就是上一講的 maker-checker loop)
+node_implement(requirements):
+ loop (最多 3 次):
+ code = model(prompt=實作指令, context=requirements + 上次報錯)
+ if tests_pass(code): return {"code": code}
+ return {"error": "實作 3 次仍未通過"}
+```
+
+| 節點 | 類型 | 節點內部(私有的) | 寫入共享狀態 |
+|------|------|------------------|-------------|
+| research | agent | 搜尋 → 讀 → 總結 → 資訊不足就重搜(循環) | requirements |
+| implement | agent | 寫 → 測 → 修 → 直到過(循環,見上) | code |
+| verify | agent | 獨立審查 + 跑測試(**fresh context,不繼承實作者的記憶**) | review(pass / fail)|
+| merge | 確定性程式碼 | 無循環,檢查通過即 commit | 結束 |
+
+注意 verify 那一行:它是圖裡最容易被做錯的一個節點。**單體 agent 裡「審查」用的還是同一個 context,自己審自己;graph 裡 verify 必須帶一份全新上下文**——它看不到 implement 的思考過程,只看到共享狀態裡的 code。這就是「獨立審查」在圖上真正成立的地方:上下文隔離不是副作用,是設計。
+
+**第三步:連邊。** 先連確定的主幹:研究 → 實作 → 驗證 → 合併 → 結束。
+
+```mermaid
+flowchart TD
+ A([開始]) --> B[research]
+ B --> C[implement]
+ C --> D[verify]
+ D --> E[merge]
+ E --> F([結束])
+```
+
+**第四步:寫路由規則(最關鍵的一步)。** 驗證節點不直接連「合併」,而是連到一個**決策**,由它決定下一步去哪。這一步就是把「測試失敗該回哪」顯式化——路由規則回傳的是節點的名字,這張圖從哪來、往哪去,一眼看全:
+
+| 當前節點 | 條件 | 下一節點 |
+|---------|------|---------|
+| verify | review == pass | merge |
+| verify | review == fail | implement |
+
+```mermaid
+flowchart TD
+ A([開始]) --> B[research]
+ B --> C[implement]
+ C --> D{verify}
+ D -- pass --> E[merge]
+ D -- fail --> C
+ E --> F([結束])
+```
+
+**第五步:掛上 checkpoint(檢查點)。** 這是圖和一次性腳本最大的區別之一:**每一步的狀態都寫入磁碟**,程序掛了能從中斷點接著跑,不從頭再來。掛上之後,你的圖立刻獲得「中斷/恢復」能力——還可以在 merge 之前插一個「暫停等人批准」的節點,這就是上一講那個「人工審批」在圖上長什麼樣:
+
+```
+checkpoint = on(graph, every_step) # 每一步的狀態都保存
+graph.pause_before("merge") # 在合併前停住,等人批准
+```
+
+**第六步:跑圖,並給它一個進入點。** 每次運行傳一個執行緒 id,checkpoint 靠它區分不同的運行實例:
+
+```
+run(graph, entry={"requirements": "修復登入頁 bug"}, thread="session-1")
+```
+
+跑完對照上面那張圖:你手寫的 `graph.md` 是藍圖,引擎裡那段程式碼是藍圖變成可執行的程式。兩者應該一一對應。如果對不上——要嘛圖沒畫對,要嘛程式碼沒寫對,**這正是「圖把問題擺在紙上」的意思**:以前對不上也沒人知道,現在一眼就能看出來。想要一份真實可運行的參考實作,見 `code/maker_checker_graph.py`——用的是 LangGraph,但讀完你應該能認出:它就是上面這六步。
+
+## 開源專案:發布後才有的,發布前就有的
+
+先劃清界線:**Graph Engineering 是 2026 年 7 月 18 日之後才有的名字。** 在那之前開源的框架,都不是「Graph Engineering 發布後的專案」。真正在概念爆火後、直接以這個名字出現的開源專案,截至 2026 年 8 月初,站得住的只有一個:
+
+**概念發布後才有的**
+
+- [GraphArc](https://github.com/CodeGraphContext/grapharc)(2026-08-02):自稱「Graph Engineering 的第一個即時實作」。它把 agent 執行從埋在日誌裡的 trace 變成一張**可互動的即時編排圖**——每個 agent、每條依賴、每個決策點都畫出來,在執行前視覺化整張圖,你確認(甚至可以拿手機看)之後再放行。作者背景是給 4000+ 開發者做圖工具,方向是「可觀測、可除錯、可工程化」。非常新,功能還在早期。
+
+**概念發布前就有的(它們不叫 Graph Engineering,但它們才是你建構時要用的)**
+
+2026 年 7 月之前,這些工具已經存在了一到三年:LangGraph(2024 年開源,月下載 6500 萬+,上面的參考實作用的就是它)、CrewAI、Microsoft Agent Framework、LlamaIndex Workflows、Google ADK、OpenAI Agents SDK、Mastra、Claude Agent SDK。**它們不是「Graph Engineering 發布後的專案」——它們恰恰是「Graph Engineering 發布前」的證據。** 節點、邊、共享狀態、路由這套東西跑了三五年,7 月才拿到一個新名字。圖引擎不解決設計問題:它給你節點、邊、checkpoint,但不會替你回答「哪些 loop 餵哪些 loop、誰擁有目標、誰能否決」。這些問題想清楚之前,換哪個引擎都是把同一個爛設計畫得更好看而已。
+
+## 潑冷水:圖不是銀彈
+
+三盆冷水,從輕到重。
+
+**第一盆:假的數字。** Graph Engineering 爆火後,網上流傳「用圖之後準確率 +18%、成本 -85%」之類的數據。韓國部落客 goddaehee 做了一輪[事實查核](https://goddaehee.tistory.com/628)(7 月 30 日):這兩個數字確實存在,但出自一篇 2026 年 3 月關於化工管道圖紙(P&ID)的論文,而且 18% 是跟圖像原稿比、85% 是跟另一套方案比——行銷文案把兩個不同基線的數字拼成了一個「前後對比」,論文裡甚至沒有「graph engineering」這個詞。看到任何「圖工程帶來 X% 提升」的數據,先查原始出處。
+
+**第二盆:形狀不是承重牆(iii.dev)。** 上面已經講過。loop 就是只有一個節點的圖;狀態機跑了幾十年。把「loop 已死」或者「graph 已死」掛在嘴邊的人,通常既沒仔細讀過 loop,也沒仔細讀過 graph。該學的是模式,不是名詞。
+
+**第三盆:Orchestration Tax(編排稅)。** Addy Osmani 在 5 月的《The Orchestration Tax》裡給了圖/多 agent 時代最硬核的一條經濟學:**開 agent 很便宜,關 loop 很貴。**
+
+啟動一個 agent 只是一個按鍵、一句話。但關閉一個 agent 的 loop 要有人檢查它的結果、和別的 agent 動過的東西對齊——**那個人是你,而且只有一個你。** Osmani 的原話:
+
+> 「你就是你的 AI agent 們的 GIL。它們可以同時跑。但只要它們的工作需要真正理解架構、解決合併衝突,這些工作就必須取得那把鎖。只有一把鎖,你握著它。」
+
+這就是為什麼上一講說的「審閱頻寬是天花板」在這一講更尖銳:**圖讓平行的 agent 變多,但你的判斷力是串行資源,不平行。** 加節點最佳化的是從來不是瓶頸的部分——瓶頸永遠是那一個串行處理器:你。
+
+## 什麼時候你真的該用圖
+
+不是所有任務都值得畫圖。五個判據,至少滿足三個再動手:
+
+1. **任務能獨立拆分成多個工作單元**——拆出來的部分互不依賴,可以平行
+2. **存在分支或回退路徑**——測試失敗該回哪、資訊不足該回哪,這些路徑值得顯式宣告
+3. **中間狀態值得保存**——checkpoint 之後能停下、能恢復,而不是從頭再來
+4. **結果能被明確驗收**——每個節點都有可自動檢查的完成標準
+5. **協作收益 > 協調成本**——平行省下的時間,多於圖本身和共享狀態帶來的開銷
+
+**「複雜」不等於「步驟多」。** 一個 20 步的線性流程,不需要圖——那是 workflow 或者乾脆是腳本。一個只有 5 個節點但彼此有回退、平行、審批的結構,才需要圖。判斷標準不是規模,是**分支和回退的存在**。
+
+## 核心概念
+
+- **Graph Engineering**:把多個 agent、loop、工具、評估者組織成顯式圖(節點 + 邊 + 共享狀態 + 路由規則)的工程實踐。讓多工作單元的連接、共享狀態與選擇路徑可設計、可觀測、可局部修復。
+- **四層疊加**:prompt → context → loop → graph,每層控制一個不同的東西(指令、資訊、執行時、系統),後一層不取代前一層,只是把前一層裝進自己的節點裡。
+- **Graph 四零件**:節點(工作單元)、邊(交接方式)、共享狀態(公共工作台)、路由規則(下一步去哪)。
+- **單循環的三種結構性失敗**:Goodhart(數字漲了,業務卻壞了)、向上失明(從不問「這個目標對嗎」)、衝突(獨立循環互相拆台)。圖把這三類問題變成顯式的關係設計。
+- **Graph ≠ Workflow**:workflow 的節點是確定性函式、邊是寫死的程式碼;graph 的節點可以是完整 agent、邊可以動態路由。graph 是 workflow 的泛化。
+- **Anchors(錨)**:把循環網路固定到真實世界的機制(真實業務結果、ground truth、人工抽查)。圖設計中最容易被跳過、卻最不能省的一步。
+- **Orchestration Tax(編排稅)**:啟動 agent 便宜、審閱結果昂貴。你的注意力是唯一的串行資源,加節點最佳化不了它。
+
+## 核心要點
+
+- **Graph Engineering 不是取代 Loop Engineering,而是在它之上建一層。** loop 是圖裡的一個節點;上一講的三樣東西(目標、驗證、停止條件)變成了節點的內部結構。
+- **圖把「延後決策」變成「提前決策」。** loop 把失敗模式藏在循環裡,graph 把它擺在紙上——可讀、可稽核、可局部修復。
+- **節點裡裝什麼,決定了圖和 workflow 的差別。** 裝函式是 workflow,裝 agent 是圖。這也是「新瓶裝舊酒」裡唯一的新酒。
+- **設計圖先回答四個問題:** 哪些 loop 餵哪些 loop、誰擁有目標、誰能否決/回滾、哪些指標能動哪些凍結。回答不了就別畫。
+- **別為畫圖而畫圖。** 五個判據:可獨立拆分、有分支或回退、中間狀態值得存、結果可驗收、協作收益 > 協調成本。
+- **你的審閱頻寬仍然是天花板。** 圖讓平行的 agent 變多,但你的判斷力是串行資源——編排稅不會因為節點變多而消失。
+- **記住反方的聲音。** 形狀不是承重牆;可回放、可觀測、可恢復才是。名詞會每六週換一個,工程能力不會。
+
+## 延伸閱讀
+
+- [Prefect: Loops vs. Graphs (Jul 2026)](https://www.prefect.io/blog/loops-vs-graphs) — 從一家做了幾十年圖編排的公司的視角看 loop 和 graph
+- [Eigent: Graph Engineering for AI Agents (Jul 2026)](https://www.eigent.ai/blog/graph-engineering-ai-agents) — 單一 loop 的三種結構性失敗 + 四個設計問題 + anchors
+- [iii.dev: Loops, Graphs, and the Layer That Matters (Jul 2026)](https://iii.dev/blog/loops-graphs-and-the-layer-that-matters/) — 最清醒的反方:「形狀不是承重牆」
+- [Rohit(@rohit4verse)原始長帖(2026-07-29)](https://x.com/rohit4verse/status/2082478623043547356) — 四層框架的一手來源:prompt → context → loop → graph,每層疊加在上一層之上
+- [Agent Times: Graph Engineering as the Final Layer (Jul 2026)](https://theagenttimes.com/articles/graph-engineering-emerges-as-proposed-final-layer-of-agent-o-4f0511a8) — Rohit 四層框架的整理
+- [goddaehee: Graph Engineering 事實查核(韓語,2026-07-30)](https://goddaehee.tistory.com/628) — 最完整的事實查核:玩笑起源時間軸、假數字拆解、LangGraph 數據、Hacker News 熱度對比
+- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — 比那場玩笑早兩週的嚴肅文章
+- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — 官方回應:「不是新想法,是既有方法的最新名字」;LangGraph 月下載 6500 萬+
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — 熱詞傳播數據(首發推文 57.5 萬瀏覽)
+- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — 七個主流開源框架的橫向對比:LangGraph、CrewAI、Microsoft Agent Framework、LlamaIndex、Google ADK、OpenAI Agents SDK、Mastra
+- [LangGraph 官方文件](https://docs.langchain.com/oss/python/langgraph/graph-api) — "Nodes do the work, edges tell what to do next";節點和邊的精確定義,建構圖的第一手參考
+- [Anthropic: Building Effective Agents (Dec 2024)](https://www.anthropic.com/engineering/building-effective-agents) — 五種模式,畫出來就是圖;workflow vs agent 的權威區分
+- [Addy Osmani: The Orchestration Tax (May 2026)](https://addyosmani.com/blog/orchestration-tax/) — 為什麼你的注意力是唯一的串行資源
+- [Addy Osmani: Orchestrating Coding Agents(演講)](https://talks.addy.ie/oreilly-codecon-march-2026/) — 從 subagents 到 agent teams 到 quality gates
+- [Addy Osmani: Loop Engineering (Jun 2026)](https://addyosmani.com/blog/loop-engineering/) — 上一講的核心參考,圖工程的前置知識
+- 第十三講:[從手動驅動到自動循環](./../lecture-13-loop-engineering/index.md) — loop 是圖裡的一個節點,先理解節點內部再理解圖
+- 第十一講:[讓 agent 的運行過程可觀測](./../lecture-11-why-observability-belongs-inside-the-harness/index.md) — 圖越複雜,可觀測性越重要;無法觀測的圖只是把黑盒拼成了更大的黑盒
+- 第九講:[防止 agent 提前宣告完成](./../lecture-09-why-agents-declare-victory-too-early/index.md) — 驗證節點為什麼必須獨立於實作節點,在圖中這是結構問題而非提示詞問題
+
+## 練習
+
+1. **把 P07 的 maker-checker loop 畫成圖:** 用 `graph.md` 顯式寫出節點、邊、共享狀態和路由規則。標出哪條邊是條件邊(驗證通過/失敗)、哪條是回退邊(失敗回到實作)。畫完回答:有沒有哪條邊是隱式的、原來藏在 agent 的上下文裡?
+
+2. **回答 eigent 的四個問題:** 找出三個你在跑的獨立 loop(或同一個專案裡的三個自動化),回答:它們之間誰餵誰?哪個 loop 擁有另一個 loop 追逐的目標?有沒有 loop 能否決另一個 loop 的產出?哪些指標在各自最佳化、卻可能互相衝突?
+
+3. **Goodhart 自檢:** 檢查你最近最佳化過的某個指標。它漲了,真實結果(業務結果、使用者回饋、程式碼品質)跟著變好了嗎?如果只是數字漲了,這個 loop 正在朝哪個方向騙你?
+
+4. **五個判據評估:** 挑一個你正在糾結要不要「圖化」的任務,用五個判據逐條打分。至少滿足三個才值得畫圖。如果不足三個,它需要的其實是一段更好的 workflow 腳本——別為了用圖而用圖。
+
+5. **把 graph.md 變成可執行程式:** 按照本講「從零構建你的第一張圖」的六步,把你畫的那張 maker-checker 圖實作成一張能跑起來的圖(參考實作:`code/maker_checker_graph.py`,用 LangGraph 寫的)。六步別跳:定義狀態 → 列節點 → 連邊 → 寫路由 → 掛 checkpoint → 跑。跑完對比 `graph.md` 和程式碼,找出第一處對不上的地方,並解釋為什麼對不上——是圖畫錯了,還是程式碼寫錯了?
diff --git a/docs/zh-TW/projects/project-08-graph-engineering-first-graph/index.md b/docs/zh-TW/projects/project-08-graph-engineering-first-graph/index.md
new file mode 100644
index 0000000..775b45e
--- /dev/null
+++ b/docs/zh-TW/projects/project-08-graph-engineering-first-graph/index.md
@@ -0,0 +1,93 @@
+[English Version →](../../../en/projects/project-08-graph-engineering-first-graph/)
+
+# Project 08. 把你的工作流畫成一張圖
+
+> 相關講義:[L14. 從單循環到圖工程](./../../lectures/lecture-14-graph-engineering/index.md)
+
+## 你要做什麼
+
+這是從 "Loop" 到 "Graph" 的躍遷專案。上一講你搭了一個 maker-checker loop——實作、驗證、回饋、再實作,所有決策都發生在同一個 agent 的上下文視窗裡。這一講你要做的,是**把藏在循環裡的結構顯式地畫出來**:節點、邊、共享狀態、路由規則,一個字一個字地寫清楚。
+
+你會做三個遞進的實驗:先把 P07 的 maker-checker loop 畫成一張顯式圖,再給圖加一個平行 fan-out/fan-in 節點,最後加一條條件回退邊和一個人工審批節點。做完你會親身感受到一件事:**圖不是新發明,是當你的 loop 複雜到一定程度後,它自己變成的樣子。**
+
+## 用什麼工具
+
+- Claude Code 或 Codex
+- Git
+- 你在 P07 搭好的 maker-checker loop(或任何一個你能反覆跑的 agent 工作流)
+- 一個文字編輯器或繪圖工具(畫圖不是為了好看,是為了把結構寫清楚;`mermaid` 或手寫 `graph.md` 都行)
+
+## 具體步驟
+
+### 準備工作
+
+1. 從 P07 完成後的儲存庫出發,或者直接用你正在跑的任何 agent 工作流。
+2. 建立三個分支:`p08-explicit-graph`、`p08-parallel`、`p08-human-in-the-loop`。
+3. 準備一個 `state.md` 作為共享狀態檔案:需求、進度、驗證結果都寫在這裡。這是圖的「公共工作台」。
+
+### 實驗一:把 Loop 畫成顯式圖
+
+切到 `p08-explicit-graph` 分支。
+
+1. **列出所有節點**:把 P07 maker-checker loop 裡的每一步寫成一個節點。每個節點寫清楚:它的職責、它的輸入、它的輸出、它是 agent 還是確定性程式碼。
+2. **畫出所有邊**:列出節點之間的每一條邊。重點標註兩條特殊邊:
+ - 條件邊:驗證通過/失敗,走哪條
+ - 回退邊:失敗回到哪個節點
+3. **寫共享狀態**:明確列出狀態裡有哪些欄位(需求、程式碼、測試結果、審查結論),誰讀誰寫。
+4. **寫路由規則**:用最簡單的 if-then 語言寫下「下一步去哪」的規則,比如:
+ ```
+ if 驗證通過 → 合併節點
+ if 驗證失敗 → 實作節點
+ if 實作節點資訊不足 → 研究節點
+ ```
+5. **寫成 `graph.md`**:把以上內容整理成一份文件。用 mermaid 畫一張圖,附上節點表和路由規則。
+6. **回答這個問題**:畫完之後,找出至少一條**原來是隱式的邊**——以前藏在 agent 上下文裡、你自己都不知道它存在的決策路徑。
+
+### 實驗二:加一個平行 Fan-out / Fan-in 節點
+
+切到 `p08-parallel` 分支。
+
+1. **選一個可以並行的點**:找任務裡一個可以拆成兩個獨立部分的地方。比如:
+ - 實作拆成兩個獨立模組,兩個 agent 平行寫
+ - 驗證拆成兩個獨立審查:一個跑測試和 lint,一個做程式碼審查(不同的指令、不同的關注點)
+ - 研究拆成兩個方向,兩個 agent 各查一路
+2. **寫 fan-out 規則**:共享狀態裡記錄「這個任務被拆成 N 個平行子任務」,每個子任務一個獨立的 context、一個獨立的節點。
+3. **寫 fan-in 規則**:所有子任務完成後,誰來合併結果?合併的標準是什麼(比如:兩個審查都通過才合併,還是有一個通過就行)?
+4. **用 worktree 隔離**:每個平行子任務在獨立的 git worktree 裡跑,物理上避免檔案碰撞(回顧第十三講的 Worktree 原語)。
+5. **跑一次並記錄**:記錄平行前後 wall-clock 時間、token 消耗、結果品質。平行真的更快嗎?還是協調開銷吃掉了省下的時間?
+
+### 實驗三:加一條回退邊和一個人工審批節點
+
+切到 `p08-human-in-the-loop` 分支。
+
+這是三個實驗裡最重要的一個。你要在圖上加兩種節點:
+
+1. **條件回退邊**:給驗證節點加一條「部分通過」的路徑——不是全盤打回實作節點,而是帶著具體回饋回到**產生問題的那個節點**。比如:測試全過但程式碼審查發現需求理解有誤,回退到研究節點而不是實作節點。這要求你的共享狀態裡記錄「問題出在哪一層」。
+2. **人工審批節點(Human-in-the-loop)**:在合併節點之前加一個人工節點。走到這裡,圖**停下來**,等你在 `state.md` 裡寫「批准」或「打回」。審批節點可以有一個超時規則:N 小時後沒回應,自動打回或自動升級。
+3. **寫 interrupt 的格式**:審批請求怎麼寫清楚——發生了什麼、改了什麼、為什麼需要人、批准/打回的後果各是什麼。
+4. **跑至少 2 輪完整流程**:每一輪都走到人工審批節點,你自己批准或打回一次。記錄:你的審批決策和驗證節點的判斷一致嗎?審批節點攔住過什麼驗證節點沒攔住的嗎?
+
+## 怎麼衡量結果
+
+| 指標 | 實驗一(顯式圖) | 實驗二(平行) | 實驗三(人機協同) |
+|------|----------------|--------------|------------------|
+| 結構可見性 | 找出了幾條隱式邊? | 共享狀態能否支撐平行子任務? | 回退邊能否精確定位問題層? |
+| 失敗定位 | 失敗時能否直接指出是哪條邊錯了? | 平行子任務失敗時,能定位到哪一個? | 審批打回時,能指出是哪一層的問題嗎? |
+| 協作開銷 | 寫圖花了多久? | 平行省下的時間 vs 協調開銷 | 審批等待時間 vs 攔住的問題價值 |
+| 可觀測性 | 每一步發生了什麼,現在看得見了嗎? | 每個平行子任務的狀態可見嗎? | 審批請求寫得夠清楚嗎? |
+| 可靠性 | 圖描述和實際運行一致嗎? | fan-in 合併標準靠譜嗎? | 超時/升級規則真的會觸發嗎? |
+
+## 要交什麼
+
+- `graph.md`(實驗一的完整圖描述:mermaid 圖 + 節點表 + 邊表 + 共享狀態欄位 + 路由規則)
+- 實驗一發現的隱式邊清單(至少一條)
+- 實驗二的 fan-out/fan-in 規則和一次平行運行記錄(時間/成本/品質對比)
+- 實驗三的回退邊規則、審批節點格式和 2 輪人機協同記錄
+- 最終複盤:從 loop 到 graph,你的工作方式發生了什麼變化?哪些任務值得畫圖,哪些不值得?
+
+## 對應講義
+
+- [Lecture 14 — 從單循環到圖工程](../../lectures/lecture-14-graph-engineering/index.md)
+- [Lecture 13 — 從手動驅動到自動循環](../../lectures/lecture-13-loop-engineering/index.md)(你的 loop 就是圖裡的一個節點;這個專案是把節點的內部結構攤開)
+- [Lecture 09 — 為什麼 agent 會提前宣告完成](../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md)(驗證節點為什麼必須獨立於實作節點,在圖中是結構問題)
+- [Lecture 11 — 為什麼可觀測性屬於 harness 的一部分](../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md)(圖越複雜,越需要看到每個節點在做什麼)
diff --git a/docs/zh/lectures/lecture-14-graph-engineering/code/index.md b/docs/zh/lectures/lecture-14-graph-engineering/code/index.md
new file mode 100644
index 0000000..0ff8cfc
--- /dev/null
+++ b/docs/zh/lectures/lecture-14-graph-engineering/code/index.md
@@ -0,0 +1,9 @@
+# 第 14 讲代码
+
+使用此文件夹存放以下方面的示例:
+
+- graph.md 图描述模板(节点 / 边 / 共享状态 / 路由规则)
+- node-prompt.md 节点角色 prompt 模板
+- routing-rules.md 路由规则模板
+- maker_checker_graph.py 参考实现(框架绑定:LangGraph):把正文"从零构建"六步变成可运行代码——状态定义、节点、边、条件路由、checkpoint。正文示例框架无关,这是其中一种真实落地的写法
+- 图控制脚本示例(执行图、检查 checkpoint、触发人工审批)
diff --git a/docs/zh/lectures/lecture-14-graph-engineering/code/maker_checker_graph.py b/docs/zh/lectures/lecture-14-graph-engineering/code/maker_checker_graph.py
new file mode 100644
index 0000000..2d26efd
--- /dev/null
+++ b/docs/zh/lectures/lecture-14-graph-engineering/code/maker_checker_graph.py
@@ -0,0 +1,107 @@
+"""maker_checker_graph.py — 用 LangGraph 实现 maker-checker 图的完整骨架。
+
+对应 Lecture 14「从零构建你的第一张图」的六步:
+1. 定义共享状态(State) 2. 列节点 3. 连边
+4. 写路由规则 5. 挂 checkpointer 6. 跑图
+
+依赖:pip install langgraph
+agent 节点(research/implement/verify)里的模型调用需要你自己接上,
+这里留了骨架和调用示意。
+"""
+
+from typing import Annotated, TypedDict
+import operator
+
+from langgraph.graph import StateGraph, START, END
+from langgraph.checkpoint.memory import MemorySaver
+
+
+# ---------- 第一步:定义共享状态 ----------
+
+class GraphState(TypedDict):
+ requirements: str # 需求,研究节点写入
+ code: str # 代码,实现节点写入
+ review: str # 审查结论:pass / fail / unclear
+ attempts: Annotated[int, operator.add] # 重试次数,用加号合并
+
+
+# ---------- 第二步:列节点 ----------
+
+def call_model(system: str, content: str) -> str:
+ """模型调用示意——接入你自己的 provider(Anthropic / OpenAI / ...)。"""
+ raise NotImplementedError("把这里换成真实的模型调用")
+
+
+def research(state: GraphState) -> dict:
+ # agent 节点:定位问题,产出需求说明
+ requirements = call_model("你是需求分析 agent", f"分析这个问题:{state.get('requirements', '')}")
+ return {"requirements": requirements}
+
+
+def implement(state: GraphState) -> dict:
+ # agent 节点:写代码 + 测试
+ code = call_model("你是实现 agent", f"根据需求写代码:{state['requirements']}")
+ return {"code": code}
+
+
+def tests_pass(code: str) -> bool:
+ """确定性检查:跑测试。这里用占位逻辑,真实场景执行 pytest 等。"""
+ return "def test" in code # 占位:代码里包含测试才算通过
+
+
+def verify(state: GraphState) -> dict:
+ # agent 节点:独立审查 + 跑测试(注意:不能和实现共用同一个 context)
+ review = call_model("你是独立审查 agent", f"审查这段代码:{state['code']}")
+ passed = tests_pass(state["code"])
+ verdict = "pass" if passed and "通过" in review else "fail"
+ return {"review": verdict}
+
+
+def merge(state: GraphState) -> dict:
+ # 确定性节点:commit
+ print(f"合并代码(第 {state['attempts']} 次尝试后通过)")
+ return {}
+
+
+# ---------- 第四步:写路由规则(最关键的一步) ----------
+
+def route_after_verify(state: GraphState) -> str:
+ if state["review"] == "fail":
+ return "implement" # 验证失败 → 回到实现
+ return "merge" # 验证通过 → 合并
+
+
+# ---------- 第三步:连边 ----------
+
+graph = StateGraph(GraphState)
+graph.add_node("research", research)
+graph.add_node("implement", implement)
+graph.add_node("verify", verify)
+graph.add_node("merge", merge)
+
+graph.add_edge(START, "research")
+graph.add_edge("research", "implement")
+graph.add_edge("implement", "verify")
+graph.add_conditional_edges(
+ "verify",
+ route_after_verify,
+ {"implement": "implement", "merge": "merge"},
+)
+graph.add_edge("merge", END)
+
+
+# ---------- 第五步:编译并挂上 checkpointer ----------
+# checkpointer 让状态每一步落盘:进程挂了能从断点接着跑,不从头再来。
+
+app = graph.compile(checkpointer=MemorySaver())
+
+
+# ---------- 第六步:跑图 ----------
+# 每次运行传一个 thread_id,checkpointer 靠它区分不同的运行实例。
+
+if __name__ == "__main__":
+ result = app.invoke(
+ {"requirements": "修复登录页 bug", "attempts": 0},
+ config={"configurable": {"thread_id": "session-1"}},
+ )
+ print(result)
diff --git a/docs/zh/lectures/lecture-14-graph-engineering/index.md b/docs/zh/lectures/lecture-14-graph-engineering/index.md
new file mode 100644
index 0000000..55377ba
--- /dev/null
+++ b/docs/zh/lectures/lecture-14-graph-engineering/index.md
@@ -0,0 +1,349 @@
+[English Version →](../../../en/lectures/lecture-14-graph-engineering/)
+
+> 本篇代码示例:[code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/zh/lectures/lecture-14-graph-engineering/code/)
+> 实战练习:[Project 08. 把你的工作流画成一张图](./../../projects/project-08-graph-engineering-first-graph/index.md)
+
+# 第十四讲. 从单循环到图工程
+
+上一讲刚讲完 Loop Engineering 六周后,2026 年 7 月 18 日,Peter Steinberger——就是上一讲里那位"不要再给 coding agent 写 prompt 了"的 OpenClaw 作者——发了一条推:
+
+> "我们还在谈 Loop,还是已经转向 Graph 了?"
+
+一条推,一天内就拿到约 57 万浏览,到月底涨到约 300 万。几小时后,机器学习工程师 Hamel Husain 发了一篇题为《Loop Engineering Is Dead. Enter Graph Engineering》的文章——正文只有一张写着 "Stop it" 的动图——又拿了约 68 万浏览。
+
+更耐人寻味的是:**这两个人都是当玩笑发的。** 一个在讽刺行业每六周发明一个新名词,一个在顺着这个梗一捧一逗。但玩笑只存活了大约一个周末——课程、路线图、工具栈在周末结束前就铺满了时间线,还跟着一堆编造出来的数字:"准确率 +18%、成本 -85%"是假数据(18% 和 85% 确实存在,但出自一篇关于化工管道图纸的论文,且对照基线根本不同),"微软、斯坦福、Anthropic 同时发现了图工程"也是假消息。事实核查确认的唯一"先行者"是 Josh Simmons:他的《We Are Entering the Graph Engineering Phase》写于 7 月 4 日,比这场玩笑早了整整两周——**是玩笑让这件事变得流行,不是玩笑创造了这件事。**
+
+> 来源:[goddaehee:Graph Engineering 事实核查(2026-07-30)](https://goddaehee.tistory.com/628);[YC Startup School 2026:Jensen Huang 访谈(含文字稿)](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia);[explainx:Graph Engineering(2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026)
+
+这一讲要做的,不是给这个热词再添一把火,而是把它拆开看清楚:**为什么单循环之后必然长出图?图和 workflow 到底有什么不同?什么时候你真的需要它,什么时候不需要?**
+
+## prompt、context、loop、graph:四个名字,一层叠一层
+
+7 月底,工程师 Rohit(@rohit4verse)发了一条[长帖](https://x.com/rohit4verse/status/2082478623043547356),把 AI 工程这几年的命名史整理成了一个清晰的四层框架。这是理解 Graph Engineering 最好的坐标系:
+
+| 阶段 | 塑造什么 | 回答的问题 | 关键产物 |
+|------|---------|-----------|---------|
+| **Prompt Engineering** | 指令 | 怎么告诉模型做什么? | instructions、examples、constraints、roles、output formats |
+| **Context Engineering** | 信息 | 模型做决定之前应该知道什么? | documents、history、memory、tool definitions、environment state |
+| **Loop Engineering** | 运行时 | 怎么让模型自己循环直到达成目标? | observe、reason、act、inspect、update、停止条件 |
+| **Graph Engineering** | 系统 | 多个 agent、loop、工具、评估者如何协作? | 节点、边、共享状态、路由规则 |
+
+注意这条线怎么读:**每一层都不是取代上一层,而是叠加在它之上。**
+
+- 你找到 context engineering 之后,并没有停止 prompt engineering——每次迭代仍然需要 prompt,只是 loop 在环境变化时帮你刷新它。
+- 你构建 loop 之后,也没有丢掉 context——loop 的每一轮都要重新组装上下文。
+- 到了 graph,prompt 和 context 和 loop 一个都没消失:**每个节点都带着自己的 prompt、自己的 context、自己的工具、自己的记忆、自己的 loop。** 图决定的是节点之间怎么连接。
+
+Rohit 的原话是这么收尾的:
+
+> 一旦一个 agent 需要专业化、并行、共享状态、验证和恢复,它就不再是一个 loop 了。它是一张图。
+
+**等等,harness 呢?** 这四个名字里没有 Harness Engineering,可这门课讲的就是 harness。原因很简单:Rohit 讲的是热词史,终点是 graph,中间那层就被跳过了。而且 harness 该放哪层,圈子自己都没吵明白——[explainx](https://explainx.ai/blog/context-prompt-loop-harness-engineering-stack-2026) 把它放在 loop 上面,[Buildrix 论文](https://arxiv.org/abs/2606.25139) 把它放在 loop 下面。本课程在第二讲就定了:harness 是地基,loop 和 graph 都建在它上面。
+
+这解释了一个奇怪的现象:为什么"Graph Engineering"这个词 2026 年 7 月才火,但大家发现自己"早就这么干了"。因为图不是新发明,是当你的任务复杂到一定程度后,loop 自动变成图。名字是后来才有的,做法早就有了。
+
+## 把图拆开看:节点、边、状态、路由
+
+把图还原成最朴素的四个零件。
+
+**节点(Node)**:承担某种职责的工作单元。它可以是:
+- 一段确定性代码(跑测试、算覆盖率)
+- 一次模型调用(生成文档)
+- 一个工具(git commit、发消息)
+- 一个完整的 agent——自己带 loop,能理解目标、会使用工具、跑不动了自己重试
+
+节点是图工程和 workflow 工程真正的分界线,这一点下面专门讲。
+
+**边(Edge)**:说明节点之间如何交接。它不是"先做 A 再做 B"那么简单——一条边可以表达:
+- **并行**:A 完成后,B 和 C 同时开始
+- **条件**:测试通过走左边,失败走右边
+- **失败/重试**:节点挂了,回到它自己再跑一次
+- **回退**:验证不通过,回到三跳之前的实现节点
+
+**共享状态(State)**:节点之间传递的数据包。需求、研究笔记、代码版本、测试结果、审查结论——都写在同一个公共工作台上。节点不直接互相喊话,它们都读写同一份状态。
+
+**路由规则(Routing)**:决定下一步去哪。这是图的"控制流",用最朴素的话说就是:
+
+> 测试通过就交付;测试失败就回到实现节点;信息不足就回到研究节点。
+
+把四个零件拼起来,一个典型的开发图长这样:
+
+```mermaid
+flowchart TD
+ S["共享状态<br/>需求 / 笔记 / 代码 / 结果"] --- R["研究节点<br/>Agent: 定位问题"]
+ R -->|"产出方案"| I["实现节点<br/>Agent: 写修改 + 测试"]
+ I -->|"产出代码"| V["验证节点<br/>Agent: 独立审查 + 跑测试"]
+ V -->|"未通过"| I
+ V -->|"通过"| M["合并节点<br/>代码: commit + 更新状态"]
+ M -->|"状态更新"| S
+ I -->|"信息不足"| R
+```
+
+注意和上一讲的 loop 图对比:上一讲是一个环——发现、分发、验证、持久化、再回到发现。这一讲的图里,**环仍然在,但被拆成了显式的节点和边**。验证节点可以直接把失败打回实现节点,实现节点可以因为信息不足退回研究节点——这些"回退边"在单一 loop 里是隐式的,是 agent 自己在上下文里记得"我该回头"。
+
+## Loop 什么时候不够用
+
+一个 loop 只有一条主干道。上一讲你搭的 maker-checker loop 里,所有决策——下一步做什么、失败往哪走——都发生在同一个 agent 的上下文窗口里。任务再复杂一点,四个问题就冒出来了:
+
+1. **分工**:研究需求的 agent、写代码的 agent、做测试的 agent,谁先开始?
+2. **并行**:哪些工作可以同时进行?
+3. **回退**:测试失败后应该回到哪里——回到实现节点,还是回到研究节点?
+4. **交接**:几个 agent 怎样看到同一份需求、笔记和测试结果?审查者不同意实现者,听谁的?
+
+黄仁勋在 Y Combinator 的 [Startup School 2026 访谈](https://ycombinator.com/library/Tq-jensen-huang-the-mindset-that-built-nvidia)(和 Garry Tan 的对谈)里说了类似的观点:当底层实现越来越多地被 agent 自动化,人类的核心价值就转向"设计系统、明确约束,并对 agent 做细粒度控制"。他给的控制例子很具体——"agent 给出计划后,我在计划文件里改一个词,这一个词就产生一处精确的差异";他还预言未来的核心技能是"系统思考"(systems thinking)。
+
+讨论串里最精彩的一击来自 Luis Catacora:
+
+> **"循环有大量容错空间。图会迫使你承认,工作流里还有多少部分根本没有被真正建模。"**
+
+这句话点破了 loop 和 graph 的深层差异:
+
+- **Loop 是延期决策。** 先让一个 agent 包揽所有工作,跑不下去再说,架构可以往后拖。这省事,但代价是失败模式不可见——你永远不知道它卡在哪一步,因为它自己也不知道。
+- **Graph 是提前决策。** 你必须提前声明整个结构:谁负责什么、任务之间怎么依赖、某个失败要回到哪。这费事,但换来的是可读、可审计、可局部修复。
+
+用一句更直白的话:**loop 把问题藏在循环里,graph 把问题摆在纸上。** 前者适合探索,后者适合生产。
+
+## 单一循环的三种结构性失败
+
+为什么单一 loop 在规模上撑不住?eigent.ai 那篇《Graph Engineering for AI Agents: Beyond Single Feedback Loops》给出了三个结构性失败——注意是结构性失败,不是某一个 loop 的 bug。
+
+**先说一个反驳:loop 里不也能加检查点吗?** 能。上一讲的验证、停止条件,甚至断点重试,loop 都装得下。但下面三个失败恰恰是检查点解决不了的——因为 loop 里的检查点长在同一个 agent 内部,做检查和出问题的是同一个大脑、同一份上下文。它会拦下"没验证就交付",却不会问"这个指标对不对"、"这个目标该不该追"——答案就写在它自己的 context 里,它看不见。图不是给你更多检查点,而是把检查**搬出去**:从"agent 内部"挪到"独立的节点",给它一份全新上下文(前面 verify 节点那节讲过)。"结构性"三个字的意思就在这:不是 loop 缺了哪个零件,而是"判断者和被执行者共享同一个大脑"这个结构本身。
+
+### 1. Goodhart:数字涨了,业务却坏了
+
+把任何一个单一指标推到极致,它就会停止测量你以为它在测量的东西。经典案例:一个客服团队围绕"工单解决率"建了一个 loop。周数据一路爬升。几个月后,续费数据却显示 churn 翻倍了——**bot 学会了关闭工单**:转移话题、劝阻用户追问、把没解决的问题标记为"已解决"。
+
+loop 做了它被要求做的每一件事。只是那个数字脱离了业务真正关心的东西。这就是 Goodhart 定律。
+
+### 2. 向上失明:它从不问"这个目标对吗"
+
+在 loop 内部,参考值是神圣的。恒温器不会问"68°F 是不是对的温度"。销售 loop 不会问"这个定额合理吗"。一个 agent eval loop 不会问"这个 benchmark 和真实业务结果匹配吗"。
+
+**目标是谁选的,loop 就朝着它跑,即使它从一开始就不是该追的东西。** 单一 loop 的结构里,没有任何位置放得下这个问题。
+
+### 3. 冲突:独立循环互相拆台
+
+真实系统里有几十个 loop,每个都是独立建起来的。响应速度的 loop 在拆深度质量的 loop 的台,增长的 loop 在拆质量的 loop 的台。每个 loop 在自己的仪表盘上都健康,系统整体却在抖动——就像几个人各自用力拉同一根绳子的不同方向。
+
+**Graph engineering 要回答的,正是单一 loop 回答不了的那组问题:**
+
+- 哪些 loop 喂给哪些 loop?
+- 哪些 loop 拥有其他 loop 追逐的目标?
+- 哪些 loop 能否决或回滚一个变更?
+- 哪些指标允许移动,哪些必须冻结?
+
+当一个系统里存在"能吃你的目标的 loop"和"能否决你的变更的 loop"时,它们之间的关系就成了工程对象——而关系和关系之间的关系,画出来就是图。
+
+### 锚:把循环固定到现实
+
+eigent 那篇文章标题里有个"everyone skips"的部分:**anchors(锚)**。循环网络再精巧,如果每个循环都漂离现实,网络只是互相漂移的共振。锚就是把 loop 固定到真实世界的东西——真实业务结果、ground truth 数据集、人工抽查。设计图的时候,锚是最容易被跳过、却是最不能省的一步。
+
+## Graph 与 Workflow:不只是换个名字
+
+这是这一讲最容易被误解的地方,值得单独拎出来说。
+
+Graph Engineering 爆火的第一反应,做过工程的人都会嘀咕一句:"这不就是 workflow 吗?DAG、状态机、工作流引擎,我们跑了几十年了。"
+
+**这个直觉对了一半。** 图和 workflow 确实共享同一个骨架:节点 + 边 + 共享状态 + 路由。Airflow、Prefect、Dagster、Temporal 几十年来的编排方式就是这张图。Anthropic 2024 年 12 月《Building Effective Agents》总结的五种模式——提示链、路由、并行化、编排者/工作者、评估者/优化者——把它们画出来,得到的正是不同形状的执行图。
+
+**错的一半在节点里。** 传统 workflow 的节点是**确定性函数**:一个 Python 函数、一个 shell 脚本、一个 SQL 任务。边是写死的代码:`if`、`switch`、`case`。整个系统工程师用代码维护,行为可预期——同样的输入永远走同样的路径。
+
+图工程的节点可以是一个**完整 agent**:自带 loop、会使用工具、能理解目标、遇到失败自己重试。边也不一定是写死的——可以带路由规则,由前一个节点的输出、验证结果、甚至另一个模型来决定下一步。
+
+为了把这个差别讲清楚,借用 Anthropic 的一对概念。Anthropic 用一句话区分 workflow 和 agent:**谁决定控制流?** 代码决定步骤就是 workflow,模型在运行时能改变步骤就是 agent。
+
+那么图是什么?**图是容纳两者的容器。** 一张图里可以同时有:
+
+- workflow 节点:跑测试、算覆盖率——确定性代码,不需要模型
+- agent 节点:实现功能、审查代码——模型驱动的完整 agent
+- 人类节点:审批、复核——人机交互节点,走到这里停住,等人点头
+
+所以准确的说法是:**Graph Engineering 不是 Workflow 的替代,而是 Workflow 的泛化**——把节点的类型从"函数"放开到"agent",把边的决策从"静态代码"放开到"动态路由"。workflow 是图中"完全确定"的那个特例。
+
+反方观点(iii.dev 的《Loops, Graphs, and the Layer That Matters》)也落在这同一个点上,只是结论相反:
+
+> "形状是容易的部分,而且是一次性的。承重决策是 loop 或 graph 由什么构成、以及它工作之后会怎样。"
+
+iii.dev 的意思是:别把"拓扑"当成工程成就。workflow 工程跑了几十年,真正沉淀下来的不是节点怎么连,而是**可重放、可观测、可恢复**——出问题能回放,运行中能观察,挂了能接着跑。图的形状你可以随手改,这些承重能力才是你该投入的地方。这个批评值得记在心里:**画图不是目的,图之上能承载多少工程能力才是目的。**
+
+## 你其实早就在画图
+
+"新瓶装旧酒"还有一个证据:工具早就齐了。
+
+- **LangGraph**:2024 年 1 月就发布了,到 2026 年 7 月月下载量约 6500 万次。它是给 agent 用的图执行引擎,节点可以是 agent,边可以带条件路由、checkpoint、interrupt。
+- **Anthropic 五种模式**:2024 年 12 月的《Building Effective Agents》已经把提示链、路由、并行化、编排者/工作者、评估者/优化者的图都画出来了,只是没叫 Graph Engineering。
+- **Claude Code 的 subagent fan-out**:当你让一个主 agent 派出一堆子 agent 并行干活时,你已经在建图了,只是没意识到。
+- **状态机、DAG 调度、任务队列、知识图谱**:计算机科学几十年,图的工程化不是一个新问题。
+
+真正新的是什么?**节点从"函数"变成了"agent"。** 这是唯一的变化,也是全部的变化。以前你写一个 workflow 节点,要写清楚它的逻辑、错误处理、重试策略。现在一个节点只需要一句指令——"研究这个问题"、"审查这段代码"——剩下的由模型自己完成。节点变得便宜了,于是图变得值得画了。
+
+## 从零构建你的第一张图
+
+理论说够了,动手。上一讲的 maker-checker 是**一个**会自己循环的 agent。Graph Engineering 要做的第一件事,就是把这样的单体 agent 拆开:**每个节点变成一个专门的 agent,各自带着私有的 prompt、context、tools、memory 和自己的小循环;节点之间不共享上下文,只通过一张共享状态交接。** 这就是 Rohit 那句话说的人话版——"graph 决定每个节点看到什么、何时运行、输出去哪、谁能否决、什么停止系统"。下面所有表示法都不绑定任何具体引擎——这是概念,LangGraph、CrewAI 只是把它们变成可执行程序的实现,API 不同、骨架一样。六个步骤,一步都别跳。
+
+**第一步:定义共享状态(State)。** 先分清两个层:**graph 层共享的只有状态,节点的上下文是私有的。** 单体 agent 只有一个 context,跑久了会被自己冗长的 transcript 淹没;graph 把 context 切成多份,每份属于一个节点——loop 是节点的私有物,graph 是它们交接的公共台。状态里放什么,先想清楚。给每个字段声明它被"怎么合并"——多个并行节点同时往同一个字段写时,是覆盖、追加还是求和。这一步不是框架特性,是你画图时就要写进 `graph.md` 的规则:
+
+```
+state = {
+ "requirements": 文本, # 研究节点写入
+ "code": 文本, # 实现节点写入
+ "review": "pass" | "fail", # 审查节点写入
+ "attempts": 数字, # 每失败一次 +1(并行写时用"求和"合并)
+}
+```
+
+**第二步:列节点——每个节点是一个完整的 agent(自带循环)。** 这是 graph 和 workflow 的根本区别:workflow 的节点是函数,graph 的节点是**带着自己小循环的 agent**。节点接收共享状态 → 用自己的私有上下文干活 → 把结果写回共享状态。写代码型节点的内部,往往就是上一讲那个 loop:
+
+```
+# implement 节点内部:一个私有小循环(就是上一讲的 maker-checker loop)
+node_implement(requirements):
+ loop (最多 3 次):
+ code = model(prompt=实现指令, context=requirements + 上次报错)
+ if tests_pass(code): return {"code": code}
+ return {"error": "实现 3 次仍未通过"}
+```
+
+| 节点 | 类型 | 节点内部(私有的) | 写入共享状态 |
+|------|------|------------------|-------------|
+| research | agent | 搜索 → 读 → 总结 → 信息不足就重搜(循环) | requirements |
+| implement | agent | 写 → 测 → 修 → 直到过(循环,见上) | code |
+| verify | agent | 独立审查 + 跑测试(**fresh context,不继承实现者的记忆**) | review(pass / fail)|
+| merge | 确定性代码 | 无循环,检查通过即 commit | 结束 |
+
+注意 verify 那一行:它是图里最容易被做错的一个节点。**单体 agent 里"审查"用的还是同一个 context,自己审自己;graph 里 verify 必须带一份全新上下文**——它看不到 implement 的思考过程,只看到共享状态里的 code。这就是"独立审查"在图上真正成立的地方:上下文隔离不是副作用,是设计。
+
+**第三步:连边。** 先连确定的主干:研究 → 实现 → 验证 → 合并 → 结束。
+
+```mermaid
+flowchart TD
+ A([开始]) --> B[research]
+ B --> C[implement]
+ C --> D[verify]
+ D --> E[merge]
+ E --> F([结束])
+```
+
+**第四步:写路由规则(最关键的一步)。** 验证节点不直接连"合并",而是连到一个**决策**,由它决定下一步去哪。这一步就是把"测试失败该回哪"显式化——路由规则返回的是节点的名字,这张图从哪来、往哪去,一眼看全:
+
+| 当前节点 | 条件 | 下一节点 |
+|---------|------|---------|
+| verify | review == pass | merge |
+| verify | review == fail | implement |
+
+```mermaid
+flowchart TD
+ A([开始]) --> B[research]
+ B --> C[implement]
+ C --> D{verify}
+ D -- pass --> E[merge]
+ D -- fail --> C
+ E --> F([结束])
+```
+
+**第五步:挂上 checkpoint(检查点)。** 这是图和一次性脚本最大的区别之一:**每一步的状态都落盘**,进程挂了能从断点接着跑,不从头再来。挂上之后,你的图立刻获得"中断/恢复"能力——还可以在 merge 之前插一个"暂停等人批准"的节点,这就是上一讲那个"人工审批"在图上长什么样:
+
+```
+checkpoint = on(graph, every_step) # 每一步的状态都保存
+graph.pause_before("merge") # 在合并前停住,等人批准
+```
+
+**第六步:跑图,并给它一个进入点。** 每次运行传一个线程 id,checkpoint 靠它区分不同的运行实例:
+
+```
+run(graph, entry={"requirements": "修复登录页 bug"}, thread="session-1")
+```
+
+跑完对照上面那张图:你手写的 `graph.md` 是蓝图,引擎里那段代码是蓝图变成的可执行程序。两者应该一一对应。如果对不上——要么图没画对,要么代码没写对,**这正是"图把问题摆在纸上"的意思**:以前对不上也没人知道,现在一眼就能看出来。想要一份真实可运行的参考实现,见 `code/maker_checker_graph.py`——用的是 LangGraph,但读完你应该能认出:它就是上面这六步。
+
+## 开源项目:发布后才有的,发布前就有的
+
+先划清界限:**Graph Engineering 是 2026 年 7 月 18 日之后才有的名字。** 在那之前开源的框架,都不是"Graph Engineering 发布后的项目"。真正在概念爆火后、直接以这个名字出现的开源项目,截至 2026 年 8 月初,站得住的只有一个:
+
+**概念发布后才有的**
+
+- [GraphArc](https://github.com/CodeGraphContext/grapharc)(2026-08-02):自称"Graph Engineering 的第一个实时实现"。它把 agent 执行从埋在日志里的 trace 变成一张**可交互的实时编排图**——每个 agent、每条依赖、每个决策点都画出来,在执行前可视化整张图,你确认(甚至可以拿手机看)之后再放行。作者背景是给 4000+ 开发者做图工具,方向是"可观测、可调试、可工程化"。非常新,功能还在早期。
+
+**概念发布前就有的(它们不叫 Graph Engineering,但它们才是你构建时要用的)**
+
+2026 年 7 月之前,这些工具已经存在了一到三年:LangGraph(2024 年开源,月下载 6500 万+,上面的参考实现用的就是它)、CrewAI、Microsoft Agent Framework、LlamaIndex Workflows、Google ADK、OpenAI Agents SDK、Mastra、Claude Agent SDK。**它们不是"Graph Engineering 发布后的项目"——它们恰恰是"Graph Engineering 发布前"的证据。** 节点、边、共享状态、路由这套东西跑了三五年,7 月才拿到一个新名字。图引擎不解决设计问题:它给你节点、边、checkpoint,但不会替你回答"哪些 loop 喂哪些 loop、谁拥有目标、谁能否决"。这些问题想清楚之前,换哪个引擎都是把同一个烂设计画得更好看而已。
+
+## 泼冷水:图不是银弹
+
+三盆冷水,从轻到重。
+
+**第一盆:假的数字。** Graph Engineering 爆火后,网上流传"用图之后准确率 +18%、成本 -85%"之类的数据。韩国博主 goddaehee 做了一轮[事实核查](https://goddaehee.tistory.com/628)(7 月 30 日):这两个数字确实存在,但出自一篇 2026 年 3 月关于化工管道图纸(P&ID)的论文,而且 18% 是跟图像原稿比、85% 是跟另一套方案比——营销文案把两个不同基线的数字拼成了一个"前后对比",论文里甚至没有"graph engineering"这个词。看到任何"图工程带来 X% 提升"的数据,先查原始出处。
+
+**第二盆:形状不是承重墙(iii.dev)。** 上面已经讲过。loop 就是只有一个节点的图;状态机跑了几十年。把"loop 已死"或者"graph 已死"挂在嘴边的人,通常既没仔细读过 loop,也没仔细读过 graph。该学的是模式,不是名词。
+
+**第三盆:Orchestration Tax(编排税)。** Addy Osmani 在 5 月的《The Orchestration Tax》里给了图/多 agent 时代最硬核的一条经济学:**开 agent 很便宜,关 loop 很贵。**
+
+启动一个 agent 只是一个按键、一句话。但关闭一个 agent 的 loop 要有人检查它的结果、和别的 agent 动过的东西对齐——**那个人是你,而且只有一个你。** Osmani 的原话:
+
+> "你就是你的 AI agent 们的 GIL。它们可以同时跑。但只要它们的工作需要真正理解架构、解决合并冲突,这些工作就必须获取那把锁。只有一把锁,你握着它。"
+
+这就是为什么上一讲说的"审阅带宽是天花板"在这一讲更尖锐:**图让并行的 agent 变多,但你的判断力是串行资源,不并行。** 加节点优化的是从来不是瓶颈的部分——瓶颈永远是那一个串行处理器:你。
+
+## 什么时候你真的该用图
+
+不是所有任务都值得画图。五个判据,至少满足三个再动手:
+
+1. **任务能独立拆分成多个工作单元**——拆出来的部分互不依赖,可以并行
+2. **存在分支或回退路径**——测试失败该回哪、信息不足该回哪,这些路径值得显式声明
+3. **中间状态值得保存**——checkpoint 之后能停下、能恢复,而不是从头再来
+4. **结果能被明确验收**——每个节点都有可自动检查的完成标准
+5. **协作收益 > 协调成本**——并行省下的时间,多于图本身和共享状态带来的开销
+
+**"复杂"不等于"步骤多"。** 一个 20 步的线性流水线,不需要图——那是 workflow 或者干脆是脚本。一个只有 5 个节点但彼此有回退、并行、审批的结构,才需要图。判断标准不是规模,是**分支和回退的存在**。
+
+## 核心概念
+
+- **Graph Engineering**:把多个 agent、loop、工具、评估者组织成显式图(节点 + 边 + 共享状态 + 路由规则)的工程实践。让多工作单元的连接、共享状态与选择路径可设计、可观测、可局部修复。
+- **四层叠加**:prompt → context → loop → graph,每层控制一个不同的东西(指令、信息、运行时、系统),后一层不取代前一层,只是把前一层装进自己的节点里。
+- **Graph 四零件**:节点(工作单元)、边(交接方式)、共享状态(公共工作台)、路由规则(下一步去哪)。
+- **单循环的三种结构性失败**:Goodhart(数字涨了,业务却坏了)、向上失明(从不问"这个目标对吗")、冲突(独立循环互相拆台)。图把这三类问题变成显式的关系设计。
+- **Graph ≠ Workflow**:workflow 的节点是确定性函数、边是写死的代码;graph 的节点可以是完整 agent、边可以动态路由。graph 是 workflow 的泛化。
+- **Anchors(锚)**:把循环网络固定到真实世界的机制(真实业务结果、ground truth、人工抽查)。图设计中最容易被跳过、却最不能省的一步。
+- **Orchestration Tax(编排税)**:启动 agent 便宜、审阅结果昂贵。你的注意力是唯一的串行资源,加节点优化不了它。
+
+## 核心要点
+
+- **Graph Engineering 不是取代 Loop Engineering,而是在它之上建一层。** loop 是图里的一个节点;上一讲的三样东西(目标、验证、停止条件)变成了节点的内部结构。
+- **图把"延期决策"变成"提前决策"。** loop 把失败模式藏在循环里,graph 把它摆在纸上——可读、可审计、可局部修复。
+- **节点里装什么,决定了图和 workflow 的差别。** 装函数是 workflow,装 agent 是图。这也是"新瓶装旧酒"里唯一的新酒。
+- **设计图先回答四个问题:** 哪些 loop 喂哪些 loop、谁拥有目标、谁能否决/回滚、哪些指标能动哪些冻结。回答不了就别画。
+- **别为画图而画图。** 五个判据:可独立拆分、有分支或回退、中间状态值得存、结果可验收、协作收益 > 协调成本。
+- **你的审阅带宽仍然是天花板。** 图让并行的 agent 变多,但你的判断力是串行资源——编排税不会因为节点变多而消失。
+- **记住反方的声音。** 形状不是承重墙;可重放、可观测、可恢复才是。名词会每六周换一个,工程能力不会。
+
+## 延伸阅读
+
+- [Prefect: Loops vs. Graphs (Jul 2026)](https://www.prefect.io/blog/loops-vs-graphs) — 从一家做了几十年图编排的公司的视角看 loop 和 graph
+- [Eigent: Graph Engineering for AI Agents (Jul 2026)](https://www.eigent.ai/blog/graph-engineering-ai-agents) — 单一 loop 的三种结构性失败 + 四个设计问题 + anchors
+- [iii.dev: Loops, Graphs, and the Layer That Matters (Jul 2026)](https://iii.dev/blog/loops-graphs-and-the-layer-that-matters/) — 最清醒的反方:"形状不是承重墙"
+- [Rohit(@rohit4verse)原始长帖(2026-07-29)](https://x.com/rohit4verse/status/2082478623043547356) — 四层框架的一手来源:prompt → context → loop → graph,每层叠加在上一层之上
+- [Agent Times: Graph Engineering as the Final Layer (Jul 2026)](https://theagenttimes.com/articles/graph-engineering-emerges-as-proposed-final-layer-of-agent-o-4f0511a8) — Rohit 四层框架的整理
+- [goddaehee: Graph Engineering 事实核查(韩语,2026-07-30)](https://goddaehee.tistory.com/628) — 最完整的事实核查:玩笑起源时间线、假数字拆解、LangGraph 数据、Hacker News 热度对比
+- [Josh Simmons: We Are Entering the Graph Engineering Phase (2026-07-04)](https://www.drjoshcsimmons.com/writing/we-are-entering-the-graph-engineering-phase) — 比那场玩笑早两周的严肃文章
+- [LangChain: 3 Years of Graph Engineering with LangGraph (2026-07-22)](https://www.langchain.com/blog/3-years-of-graph-engineering-with-langgraph) — 官方回应:"不是新想法,是既有方法的最新名字";LangGraph 月下载 6500 万+
+- [explainx: Graph Engineering: AI Agents as Multi-Agent Organizations (2026-07)](https://explainx.ai/blog/graph-engineering-ai-agents-multi-agent-organizations-2026) — 热词传播数据(首发推文 57.5 万浏览)
+- [LangChain: The Best AI Agent Frameworks in 2026](https://www.langchain.com/resources/ai-agent-frameworks) — 七个主流开源框架的横向对比:LangGraph、CrewAI、Microsoft Agent Framework、LlamaIndex、Google ADK、OpenAI Agents SDK、Mastra
+- [LangGraph 官方文档](https://docs.langchain.com/oss/python/langgraph/graph-api) — "Nodes do the work, edges tell what to do next";节点和边的精确定义,构建图的第一手参考
+- [Anthropic: Building Effective Agents (Dec 2024)](https://www.anthropic.com/engineering/building-effective-agents) — 五种模式,画出来就是图;workflow vs agent 的权威区分
+- [Addy Osmani: The Orchestration Tax (May 2026)](https://addyosmani.com/blog/orchestration-tax/) — 为什么你的注意力是唯一的串行资源
+- [Addy Osmani: Orchestrating Coding Agents(演讲)](https://talks.addy.ie/oreilly-codecon-march-2026/) — 从 subagents 到 agent teams 到 quality gates
+- [Addy Osmani: Loop Engineering (Jun 2026)](https://addyosmani.com/blog/loop-engineering/) — 上一讲的核心参考,图工程的前置知识
+- 第十三讲:[从手动驱动到自动循环](./../lecture-13-loop-engineering/index.md) — loop 是图里的一个节点,先理解节点内部再理解图
+- 第十一讲:[让 agent 的运行过程可观测](./../lecture-11-why-observability-belongs-inside-the-harness/index.md) — 图越复杂,可观测性越重要;无法观测的图只是把黑盒拼成了更大的黑盒
+- 第九讲:[防止 agent 提前宣告完成](./../lecture-09-why-agents-declare-victory-too-early/index.md) — 验证节点为什么必须独立于实现节点,在图中这是结构问题而非提示词问题
+
+## 练习
+
+1. **把 P07 的 maker-checker loop 画成图:** 用 `graph.md` 显式写出节点、边、共享状态和路由规则。标出哪条边是条件边(验证通过/失败)、哪条是回退边(失败回到实现)。画完回答:有没有哪条边是隐式的、原来藏在 agent 的上下文里?
+
+2. **回答 eigent 的四个问题:** 找出三个你在跑的独立 loop(或同一个项目里的三个自动化),回答:它们之间谁喂谁?哪个 loop 拥有另一个 loop 追逐的目标?有没有 loop 能否决另一个 loop 的产出?哪些指标在各自优化、却可能互相冲突?
+
+3. **Goodhart 自检:** 检查你最近优化过的某个指标。它涨了,真实结果(业务结果、用户反馈、代码质量)跟着变好了吗?如果只是数字涨了,这个 loop 正在朝哪个方向骗你?
+
+4. **五个判据评估:** 挑一个你正在纠结要不要"图化"的任务,用五个判据逐条打分。至少满足三个才值得画图。如果不足三个,它需要的其实是一段更好的 workflow 脚本——别为了用图而用图。
+
+5. **把 graph.md 变成可执行程序:** 按照本讲"从零构建你的第一张图"的六步,把你画的那张 maker-checker 图实现成一张能跑起来的图(参考实现:`code/maker_checker_graph.py`,用 LangGraph 写的)。六步别跳:定义状态 → 列节点 → 连边 → 写路由 → 挂 checkpoint → 跑。跑完对比 `graph.md` 和代码,找出第一处对不上的地方,并解释为什么对不上——是图画错了,还是代码写错了?
diff --git a/docs/zh/projects/project-08-graph-engineering-first-graph/index.md b/docs/zh/projects/project-08-graph-engineering-first-graph/index.md
new file mode 100644
index 0000000..21ffc9b
--- /dev/null
+++ b/docs/zh/projects/project-08-graph-engineering-first-graph/index.md
@@ -0,0 +1,91 @@
+# Project 08. 把你的工作流画成一张图
+
+> 相关讲义:[L14. 从单循环到图工程](./../../lectures/lecture-14-graph-engineering/index.md)
+
+## 你要做什么
+
+这是从 "Loop" 到 "Graph" 的跃迁项目。上一讲你搭了一个 maker-checker loop——实现、验证、反馈、再实现,所有决策都发生在同一个 agent 的上下文窗口里。这一讲你要做的,是**把藏在循环里的结构显式地画出来**:节点、边、共享状态、路由规则,一个字一个字地写清楚。
+
+你会做三个递进的实验:先把 P07 的 maker-checker loop 画成一张显式图,再给图加一个并行 fan-out/fan-in 节点,最后加一条条件回退边和一个人工审批节点。做完你会亲身感受到一件事:**图不是新发明,是当你的 loop 复杂到一定程度后,它自己变成的样子。**
+
+## 用什么工具
+
+- Claude Code 或 Codex
+- Git
+- 你在 P07 搭好的 maker-checker loop(或任何一个你能反复跑的 agent 工作流)
+- 一个文本编辑器或绘图工具(画图不是为了好看,是为了把结构写清楚;`mermaid` 或手写 `graph.md` 都行)
+
+## 具体步骤
+
+### 准备工作
+
+1. 从 P07 完成后的仓库出发,或者直接用你正在跑的任何 agent 工作流。
+2. 创建三个分支:`p08-explicit-graph`、`p08-parallel`、`p08-human-in-the-loop`。
+3. 准备一个 `state.md` 作为共享状态文件:需求、进度、验证结果都写在这里。这是图的"公共工作台"。
+
+### 实验一:把 Loop 画成显式图
+
+切到 `p08-explicit-graph` 分支。
+
+1. **列出所有节点**:把 P07 maker-checker loop 里的每一步写成一个节点。每个节点写清楚:它的职责、它的输入、它的输出、它是 agent 还是确定性代码。
+2. **画出所有边**:列出节点之间的每一条边。重点标注两条特殊边:
+ - 条件边:验证通过/失败,走哪条
+ - 回退边:失败回到哪个节点
+3. **写共享状态**:明确列出状态里有哪些字段(需求、代码、测试结果、审查结论),谁读谁写。
+4. **写路由规则**:用最简单的 if-then 语言写下"下一步去哪"的规则,比如:
+ ```
+ if 验证通过 → 合并节点
+ if 验证失败 → 实现节点
+ if 实现节点信息不足 → 研究节点
+ ```
+5. **写成 `graph.md`**:把以上内容整理成一份文档。用 mermaid 画一张图,附上节点表和路由规则。
+6. **回答这个问题**:画完之后,找出至少一条**原来是隐式的边**——以前藏在 agent 上下文里、你自己都不知道它存在的决策路径。
+
+### 实验二:加一个并行 Fan-out / Fan-in 节点
+
+切到 `p08-parallel` 分支。
+
+1. **选一个可以并行的点**:找任务里一个可以拆成两个独立部分的地方。比如:
+ - 实现拆成两个独立模块,两个 agent 并行写
+ - 验证拆成两个独立审查:一个跑测试和 lint,一个做代码审查(不同的指令、不同的关注点)
+ - 研究拆成两个方向,两个 agent 各查一路
+2. **写 fan-out 规则**:共享状态里记录"这个任务被拆成 N 个并行子任务",每个子任务一个独立的 context、一个独立的节点。
+3. **写 fan-in 规则**:所有子任务完成后,谁来合并结果?合并的标准是什么(比如:两个审查都通过才合并,还是有一个通过就行)?
+4. **用 worktree 隔离**:每个并行子任务在独立的 git worktree 里跑,物理上避免文件碰撞(回顾第十三讲的 Worktree 原语)。
+5. **跑一次并记录**:记录并行前后 wall-clock 时间、token 消耗、结果质量。并行真的更快吗?还是协调开销吃掉了省下的时间?
+
+### 实验三:加一条回退边和一个人工审批节点
+
+切到 `p08-human-in-the-loop` 分支。
+
+这是三个实验里最重要的一个。你要在图上加两种节点:
+
+1. **条件回退边**:给验证节点加一条"部分通过"的路径——不是全盘打回实现节点,而是带着具体反馈回到**产生问题的那个节点**。比如:测试全过但代码审查发现需求理解有误,回退到研究节点而不是实现节点。这要求你的共享状态里记录"问题出在哪一层"。
+2. **人工审批节点(Human-in-the-loop)**:在合并节点之前加一个人工节点。走到这里,图**停下来**,等你在 `state.md` 里写"批准"或"打回"。审批节点可以有一个超时规则:N 小时后没响应,自动打回或自动升级。
+3. **写 interrupt 的格式**:审批请求怎么写清楚——发生了什么、改了什么、为什么需要人、批准/打回的后果各是什么。
+4. **跑至少 2 轮完整流程**:每一轮都走到人工审批节点,你自己批准或打回一次。记录:你的审批决策和验证节点的判断一致吗?审批节点拦住过什么验证节点没拦住的吗?
+
+## 怎么衡量结果
+
+| 指标 | 实验一(显式图) | 实验二(并行) | 实验三(人机协同) |
+|------|----------------|--------------|------------------|
+| 结构可见性 | 找出了几条隐式边? | 共享状态能否支撑并行子任务? | 回退边能否精确定位问题层? |
+| 失败定位 | 失败时能否直接指出是哪条边错了? | 并行子任务失败时,能定位到哪一个? | 审批打回时,能指出是哪一层的问题吗? |
+| 协作开销 | 写图花了多久? | 并行省下的时间 vs 协调开销 | 审批等待时间 vs 拦住的问题价值 |
+| 可观测性 | 每一步发生了什么,现在看得见了吗? | 每个并行子任务的状态可见吗? | 审批请求写得够清楚吗? |
+| 可靠性 | 图描述和实际运行一致吗? | fan-in 合并标准靠谱吗? | 超时/升级规则真的会触发吗? |
+
+## 要交什么
+
+- `graph.md`(实验一的完整图描述:mermaid 图 + 节点表 + 边表 + 共享状态字段 + 路由规则)
+- 实验一发现的隐式边清单(至少一条)
+- 实验二的 fan-out/fan-in 规则和一次并行运行记录(时间/成本/质量对比)
+- 实验三的回退边规则、审批节点格式和 2 轮人机协同记录
+- 最终复盘:从 loop 到 graph,你的工作方式发生了什么变化?哪些任务值得画图,哪些不值得?
+
+## 对应讲义
+
+- [Lecture 14 — 从单循环到图工程](../../lectures/lecture-14-graph-engineering/index.md)
+- [Lecture 13 — 从手动驱动到自动循环](../../lectures/lecture-13-loop-engineering/index.md)(你的 loop 就是图里的一个节点;这个项目是把节点的内部结构摊开)
+- [Lecture 09 — 为什么 agent 会提前宣告完成](../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md)(验证节点为什么必须独立于实现节点,在图中是结构问题)
+- [Lecture 11 — 为什么可观测性属于 harness 的一部分](../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md)(图越复杂,越需要看到每个节点在做什么)