Skip to content

Harness engineering beginner tutorial, from 0 to 1

Add Ukrainian (uk) translation across the project

Maksym Karnaukhf2acdb0b9b26
diff --git a/README.md b/README.md
index 0cb996e..faa4de9 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,7 @@
<a href="docs-readme/uz-UZ/README.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>
<a href="docs-readme/tr-TR/README.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?style=flat-square"></a>
<a href="docs-readme/pt-BR/README.md"><img alt="Português-BR" src="https://img.shields.io/badge/PT--BR-Português-1A8BBA?style=flat-square"></a>
+ <a href="docs-readme/uk-UA/README.md"><img alt="Українська" src="https://img.shields.io/badge/UK-Українська-0057B7?style=flat-square"></a>
</p>
<h1 align="center">Learn Harness Engineering</h1>
@@ -22,12 +23,12 @@
<p align="center">
<img src="https://img.shields.io/badge/Lectures-12-blue?style=flat-square" alt="12 Lectures">
<img src="https://img.shields.io/badge/Projects-6-green?style=flat-square" alt="6 Projects">
- <img src="https://img.shields.io/badge/Languages-14-yellow?style=flat-square" alt="14 Languages">
+ <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>
</p>
-> 🌍 This course is available in **14 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.
+> 🌍 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.
Learn Harness Engineering is a course dedicated to the engineering of AI coding agents. We have deeply studied and synthesized the most advanced Harness Engineering theories and practices in the industry. Our core references include:
diff --git a/docs-readme/README.md b/docs-readme/README.md
index 5771d5d..80a222f 100644
--- a/docs-readme/README.md
+++ b/docs-readme/README.md
@@ -19,3 +19,4 @@ Translated README files live in this directory:
- [Oʻzbekcha](uz-UZ/README.md)
- [Türkçe](tr-TR/README.md)
- [Português (Brasil)](pt-BR/README.md)
+- [Українська](uk-UA/README.md)
diff --git a/docs-readme/ar-SA/README.md b/docs-readme/ar-SA/README.md
index b2f7843..dc630f0 100644
--- a/docs-readme/ar-SA/README.md
+++ b/docs-readme/ar-SA/README.md
@@ -13,6 +13,7 @@
<a href="../uz-UZ/README.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>
<a href="../tr-TR/README.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?style=flat-square"></a>
<a href="../pt-BR/README.md"><img alt="Português-BR" src="https://img.shields.io/badge/PT--BR-Português-1A8BBA?style=flat-square"></a>
+ <a href="../uk-UA/README.md"><img alt="Українська" src="https://img.shields.io/badge/UK-Українська-0057B7?style=flat-square"></a>
</p>
# تعلّم هندسة الحزام (Learn Harness Engineering)
diff --git a/docs-readme/de-DE/README.md b/docs-readme/de-DE/README.md
index faebe7e..f877718 100644
--- a/docs-readme/de-DE/README.md
+++ b/docs-readme/de-DE/README.md
@@ -13,6 +13,7 @@
<a href="../uz-UZ/README.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>
<a href="../tr-TR/README.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?style=flat-square"></a>
<a href="../pt-BR/README.md"><img alt="Português-BR" src="https://img.shields.io/badge/PT--BR-Português-1A8BBA?style=flat-square"></a>
+ <a href="../uk-UA/README.md"><img alt="Українська" src="https://img.shields.io/badge/UK-Українська-0057B7?style=flat-square"></a>
</p>
# Learn Harness Engineering
diff --git a/docs-readme/es-ES/README.md b/docs-readme/es-ES/README.md
index c0109cb..7d4b408 100644
--- a/docs-readme/es-ES/README.md
+++ b/docs-readme/es-ES/README.md
@@ -13,6 +13,7 @@
<a href="../uz-UZ/README.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>
<a href="../tr-TR/README.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?style=flat-square"></a>
<a href="../pt-BR/README.md"><img alt="Português-BR" src="https://img.shields.io/badge/PT--BR-Português-1A8BBA?style=flat-square"></a>
+ <a href="../uk-UA/README.md"><img alt="Українська" src="https://img.shields.io/badge/UK-Українська-0057B7?style=flat-square"></a>
</p>
# Learn Harness Engineering
diff --git a/docs-readme/fr-FR/README.md b/docs-readme/fr-FR/README.md
index 27ac309..36626f4 100644
--- a/docs-readme/fr-FR/README.md
+++ b/docs-readme/fr-FR/README.md
@@ -13,6 +13,7 @@
<a href="../uz-UZ/README.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>
<a href="../tr-TR/README.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?style=flat-square"></a>
<a href="../pt-BR/README.md"><img alt="Português-BR" src="https://img.shields.io/badge/PT--BR-Português-1A8BBA?style=flat-square"></a>
+ <a href="../uk-UA/README.md"><img alt="Українська" src="https://img.shields.io/badge/UK-Українська-0057B7?style=flat-square"></a>
</p>
# Learn Harness Engineering
diff --git a/docs-readme/ja-JP/README.md b/docs-readme/ja-JP/README.md
index 190be9d..15da3d0 100644
--- a/docs-readme/ja-JP/README.md
+++ b/docs-readme/ja-JP/README.md
@@ -13,6 +13,7 @@
<a href="../uz-UZ/README.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>
<a href="../tr-TR/README.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?style=flat-square"></a>
<a href="../pt-BR/README.md"><img alt="Português-BR" src="https://img.shields.io/badge/PT--BR-Português-1A8BBA?style=flat-square"></a>
+ <a href="../uk-UA/README.md"><img alt="Українська" src="https://img.shields.io/badge/UK-Українська-0057B7?style=flat-square"></a>
</p>
# Learn Harness Engineering
diff --git a/docs-readme/ko-KR/README.md b/docs-readme/ko-KR/README.md
index 561529a..adff02a 100644
--- a/docs-readme/ko-KR/README.md
+++ b/docs-readme/ko-KR/README.md
@@ -13,6 +13,7 @@
<a href="../uz-UZ/README.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>
<a href="../tr-TR/README.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?style=flat-square"></a>
<a href="../pt-BR/README.md"><img alt="Português-BR" src="https://img.shields.io/badge/PT--BR-Português-1A8BBA?style=flat-square"></a>
+ <a href="../uk-UA/README.md"><img alt="Українська" src="https://img.shields.io/badge/UK-Українська-0057B7?style=flat-square"></a>
</p>
# Learn Harness Engineering
diff --git a/docs-readme/pt-BR/README.md b/docs-readme/pt-BR/README.md
index d4ca451..88aff18 100644
--- a/docs-readme/pt-BR/README.md
+++ b/docs-readme/pt-BR/README.md
@@ -13,6 +13,7 @@
<a href="docs-readme/uz-UZ/README.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>
<a href="docs-readme/tr-TR/README.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?style=flat-square"></a>
<a href="docs-readme/pt-BR/README.md"><img alt="Português-BR" src="https://img.shields.io/badge/PT--BR-Português-1A8BBA?style=flat-square"></a>
+ <a href="docs-readme/uk-UA/README.md"><img alt="Українська" src="https://img.shields.io/badge/UK-Українська-0057B7?style=flat-square"></a>
</p>
<h1 align="center">Aprenda Engenharia de Harness</h1>
@@ -22,11 +23,11 @@
<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/Idiomas-14-yellow?style=flat-square" alt="14 Idiomas">
+ <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>
-> 🌍 Este curso está disponível em **14 idiomas**: Inglês, 简体中文, 繁體中文, 日本語, 한국어, Español, Français, Русский, Deutsch, العربية, Tiếng Việt, Oʻzbekcha, Türkçe e Português (BR). Escolha seu idioma nos emblemas acima.
+> 🌍 Este curso está disponível em **15 idiomas**: Inglês, 简体中文, 繁體中文, 日本語, 한국어, Español, Français, Русский, Deutsch, العربية, Tiếng Việt, Oʻzbekcha, Türkçe, Português (BR) e Українська. Escolha seu idioma nos emblemas acima.
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:
diff --git a/docs-readme/ru-RU/README.md b/docs-readme/ru-RU/README.md
index 27e4abc..7b78211 100644
--- a/docs-readme/ru-RU/README.md
+++ b/docs-readme/ru-RU/README.md
@@ -13,6 +13,7 @@
<a href="../uz-UZ/README.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>
<a href="../tr-TR/README.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?style=flat-square"></a>
<a href="../pt-BR/README.md"><img alt="Português-BR" src="https://img.shields.io/badge/PT--BR-Português-1A8BBA?style=flat-square"></a>
+ <a href="../uk-UA/README.md"><img alt="Українська" src="https://img.shields.io/badge/UK-Українська-0057B7?style=flat-square"></a>
</p>
# Learn Harness Engineering
diff --git a/docs-readme/tr-TR/README.md b/docs-readme/tr-TR/README.md
index 803b1fc..bd053a7 100644
--- a/docs-readme/tr-TR/README.md
+++ b/docs-readme/tr-TR/README.md
@@ -13,6 +13,7 @@
<a href="../uz-UZ/README.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>
<a href="../tr-TR/README.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?style=flat-square"></a>
<a href="../pt-BR/README.md"><img alt="Português-BR" src="https://img.shields.io/badge/PT--BR-Português-1A8BBA?style=flat-square"></a>
+ <a href="../uk-UA/README.md"><img alt="Українська" src="https://img.shields.io/badge/UK-Українська-0057B7?style=flat-square"></a>
</p>
# Learn Harness Engineering
diff --git a/docs-readme/uk-UA/README.md b/docs-readme/uk-UA/README.md
new file mode 100644
index 0000000..37fd823
--- /dev/null
+++ b/docs-readme/uk-UA/README.md
@@ -0,0 +1,596 @@
+<p align="center">
+ <a href="../../README.md"><img alt="English" src="https://img.shields.io/badge/EN-English-blue?style=flat-square"></a>
+ <a href="../zh-CN/README.md"><img alt="简体中文" src="https://img.shields.io/badge/ZH-简体中文-red?style=flat-square"></a>
+ <a href="../zh-TW/README.md"><img alt="繁體中文" src="https://img.shields.io/badge/ZH--TW-繁體中文-orange?style=flat-square"></a>
+ <a href="../ja-JP/README.md"><img alt="日本語" src="https://img.shields.io/badge/JA-日本語-green?style=flat-square"></a>
+ <a href="../ko-KR/README.md"><img alt="한국어" src="https://img.shields.io/badge/KO-한국어-blueviolet?style=flat-square"></a>
+ <a href="../es-ES/README.md"><img alt="Español" src="https://img.shields.io/badge/ES-Español-yellow?style=flat-square"></a>
+ <a href="../fr-FR/README.md"><img alt="Français" src="https://img.shields.io/badge/FR-Français-007EC6?style=flat-square"></a>
+ <a href="../ru-RU/README.md"><img alt="Русский" src="https://img.shields.io/badge/RU-Русский-informational?style=flat-square"></a>
+ <a href="../de-DE/README.md"><img alt="Deutsch" src="https://img.shields.io/badge/DE-Deutsch-2EA043?style=flat-square"></a>
+ <a href="../ar-SA/README.md"><img alt="العربية" src="https://img.shields.io/badge/AR-العربية-success?style=flat-square"></a>
+ <a href="../vi-VN/README.md"><img alt="Tiếng Việt" src="https://img.shields.io/badge/VI-Tiếng_Việt-cc6699?style=flat-square"></a>
+ <a href="../uz-UZ/README.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>
+ <a href="../tr-TR/README.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?style=flat-square"></a>
+ <a href="../pt-BR/README.md"><img alt="Português-BR" src="https://img.shields.io/badge/PT--BR-Português-1A8BBA?style=flat-square"></a>
+ <a href="../uk-UA/README.md"><img alt="Українська" src="https://img.shields.io/badge/UK-Українська-0057B7?style=flat-square"></a>
+</p>
+
+<h1 align="center">Learn Harness Engineering</h1>
+
+<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/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>
+</p>
+
+> 🌍 Цей курс доступний **15 мовами**: English, 简体中文, 繁體中文, 日本語, 한국어, Español, Français, Русский, Deutsch, العربية, Tiếng Việt, Oʻzbekcha, Türkçe, Portuguese (BR), Українська. Оберіть свою мову за допомогою значків вище.
+
+Learn Harness Engineering — курс, присвячений інженерії AI-агентів для написання коду. Ми ретельно вивчили та синтезували найбільш передові теорії та практики Harness Engineering в індустрії. Основні джерела:
+
+- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
+- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
+- [Awesome Harness Engineering](https://github.com/walkinglabs/awesome-harness-engineering)
+
+> **Швидкий старт?** Навичка [`skills/harness-creator/`](./skills/harness-creator/) допоможе вам за лічені хвилини підготувати harness виробничого рівня (AGENTS.md, списки функцій, init.sh, процеси верифікації) для вашого власного проєкту.
+
+---
+
+## Зміст
+
+- [✨ Візуальний огляд](#-візуальний-огляд)
+- [Що насправді означає Harness Engineering](#що-насправді-означає-harness-engineering)
+- [Швидкий старт: покращте свого агента вже сьогодні](#швидкий-старт-покращте-свого-агента-вже-сьогодні)
+- [Підсумковий проєкт: реальний застосунок](#підсумковий-проєкт-реальний-застосунок)
+- [Навчальний маршрут](#навчальний-маршрут)
+- [Навчальна програма](#навчальна-програма)
+- [Навички](#навички)
+- [Інші курси](#інші-курси)
+
+---
+
+## ✨ Візуальний огляд
+
+### 🏠 Головна сторінка курсу
+> Вичерпна структура курсу та вступ до основних концепцій із чітким шляхом для початку навчання.
+
+![Попередній перегляд головної сторінки курсу](../../docs/public/screenshots/readme/uk-home.png)
+
+### 📖 Занурювальні лекції
+> Глибокий аналіз реальних проблем і практичні проєкти (наприклад, Project 01) для занурювального навчального досвіду.
+
+![Попередній перегляд лекції курсу](../../docs/public/screenshots/readme/uk-lecture-01.png)
+
+### 🗂️ Готова до використання бібліотека ресурсів
+> Шаблони та референсні конфігурації для вирішення поширених проблем у розробці з багатоходовими AI-агентами, таких як втрата контексту та передчасне завершення завдань.
+
+![Попередній перегляд бібліотеки ресурсів](../../docs/public/screenshots/readme/uk-resources.png)
+
+## PDF-підручники курсу
+
+Репозиторій тепер включає конвеєр збирання PDF для матеріалів курсу.
+
+- Запустіть `npm run pdf:build`, щоб локально згенерувати поточно налаштовані PDF-підручники.
+- Вихідні файли записуються до `artifacts/pdfs/`.
+- Запустіть `npm run screenshots:readme`, якщо потрібно оновити зображення попереднього перегляду README.
+- Робочий процес GitHub Actions [`release-course-pdfs.yml`](./.github/workflows/release-course-pdfs.yml) може збирати PDF та публікувати їх у GitHub Releases.
+
+---
+
+## Модель розумна — harness робить її надійною
+
+Є одна сувора правда, яку більшість людей засвоює на власному досвіді: **навіть найпотужніша модель у світі провалить реальні інженерні завдання, якщо навколо неї не побудовано належне середовище.**
+
+Ви, мабуть, і самі це спостерігали. Ви даєте Claude або GPT завдання у своєму репозиторії. Спочатку все йде добре — агент читає файли, пише код, виглядає продуктивно. Потім щось іде не так. Він пропускає крок. Ламає тест. Каже «готово», але нічого насправді не працює. Ви витрачаєте більше часу на виправлення, ніж якби зробили все самостійно.
+
+Це не проблема моделі. Це проблема harness.
+
+Докази очевидні. Anthropic провів контрольований експеримент: та сама модель (Opus 4.5), той самий промпт («побудуй 2D-редактор ретро-ігор»). Без harness агент витратив $9 за 20 хвилин і отримав результат, який не працював. З повноцінним harness (планувальник + генератор + оцінювач) агент витратив $200 за 6 годин і збудував гру, в яку справді можна було грати. Модель не змінилася. Змінився harness.
+
+OpenAI повідомив про те саме з Codex: у добре оснащеному harness репозиторії та сама модель переходить від «ненадійна» до «надійна». Не маргінальне поліпшення — якісний стрибок.
+
+**Цей курс вчить вас будувати таке середовище.**
+
+```text
+ THE HARNESS PATTERN
+ ====================
+
+ You --> give task --> Agent reads harness files --> Agent executes
+ |
+ harness governs every step:
+ |
+ +--> Instructions: what to do, in what order
+ +--> Scope: one feature at a time, no overreach
+ +--> State: progress log, feature list, git history
+ +--> Verification: tests, lint, type-check, smoke runs
+ +--> Lifecycle: init at start, clean state at end
+ |
+ v
+ Agent stops only when
+ verification passes
+```
+
+---
+
+## Що насправді означає Harness Engineering
+
+Harness Engineering — це побудова повноцінного робочого середовища навколо моделі, щоб вона давала надійні результати. Мова йде не про написання кращих промптів. Мова йде про проєктування системи, всередині якої функціонує модель.
+
+Harness складається з п'яти підсистем:
+
+```text
+ ┌────────────────────────────────────────────────────────────────┐
+ │ THE HARNESS │
+ │ │
+ │ ┌──────────────┐ ┌──────────────┐ ┌────────────────────┐ │
+ │ │ Instructions │ │ State │ │ Verification │ │
+ │ │ │ │ │ │ │ │
+ │ │ AGENTS.md │ │ progress.md │ │ tests + lint │ │
+ │ │ CLAUDE.md │ │ feature_list │ │ type-check │ │
+ │ │ feature_list │ │ git log │ │ smoke runs │ │
+ │ │ docs/ │ │ session hand │ │ e2e pipeline │ │
+ │ └──────────────┘ └──────────────┘ └────────────────────┘ │
+ │ │
+ │ ┌──────────────┐ ┌──────────────────────────────────────┐ │
+ │ │ Scope │ │ Session Lifecycle │ │
+ │ │ │ │ │ │
+ │ │ one feature │ │ init.sh at start │ │
+ │ │ at a time │ │ clean-state checklist at end │ │
+ │ │ definition │ │ handoff note for next session │ │
+ │ │ of done │ │ commit only when safe to resume │ │
+ │ └──────────────┘ └──────────────────────────────────────┘ │
+ │ │
+ └────────────────────────────────────────────────────────────────┘
+
+ The MODEL decides what code to write.
+ The HARNESS governs when, where, and how it writes it.
+ The harness doesn't make the model smarter.
+ It makes the model's output reliable.
+```
+
+Кожна підсистема виконує одне завдання:
+
+- **Інструкції** — Повідомляють агенту, що робити, в якому порядку та що прочитати перед початком. Не один гігантський файл, а структура прогресивного розкриття інформації, якою агент навігує за потребою.
+- **Стан** — Відстежує, що зроблено, що в процесі та що далі. Зберігається на диску, щоб наступна сесія підхоплювала роботу рівно звідти, де закінчила попередня.
+- **Верифікація** — Лише успішно виконаний набір тестів є доказом. Агент не може оголосити перемогу без виконуваного підтвердження.
+- **Обсяг** — Обмежує агента однією функцією за раз. Без виходу за межі. Без незакінченого виконання трьох речей одночасно. Без переписування списку функцій, щоб приховати незавершену роботу.
+- **Життєвий цикл сесії** — Ініціалізувати на початку. Прибрати наприкінці. Залишити чистий шлях перезапуску для наступної сесії.
+
+---
+
+## Навіщо існує цей курс
+
+Питання не в тому, «чи можуть моделі писати код?». Можуть. Питання таке: **чи можуть вони надійно виконувати реальні інженерні завдання всередині реальних репозиторіїв, протягом кількох сесій, без постійного контролю з боку людини?**
+
+Наразі відповідь: ні, якщо немає harness.
+
+```text
+ WITHOUT HARNESS WITH HARNESS
+ ============== ============
+
+ Session 1: agent writes code Session 1: agent reads instructions
+ agent breaks tests agent runs init.sh
+ agent says "done" agent works on one feature
+ you fix it manually agent verifies before claiming done
+ agent updates progress log
+ Session 2: agent starts fresh agent commits clean state
+ agent has no memory
+ of what happened before Session 2: agent reads progress log
+ agent re-does work agent picks up exactly where it left off
+ or does something else entirely agent continues the unfinished feature
+ you fix it again you review, not rescue
+
+ Result: you spend more time Result: agent does the work,
+ cleaning up than if you you verify the result
+ did it yourself
+```
+
+Питання, яким насправді переймається цей курс:
+
+- Які конструкції harness підвищують рівень виконання завдань?
+- Які конструкції зменшують обсяг повторної роботи та некоректних завершень?
+- Які механізми підтримують стабільний прогрес у тривалих завданнях?
+- Які структури забезпечують підтримуваність системи після кількох запусків агента?
+
+---
+
+## Навчальна програма та документація
+
+Повні матеріали курсу доступні на **[вебсайті документації](https://walkinglabs.github.io/learn-harness-engineering/)**.
+
+Навчальна програма розділена на три частини:
+
+1. **Лекції**: 12 концептуальних модулів, що пояснюють теорію Harness Engineering.
+2. **Проєкти**: 6 практичних проєктів, у яких ви будуєте агентне робоче середовище з нуля.
+3. **Бібліотека ресурсів**: Готові до копіювання шаблони (`AGENTS.md`, `feature_list.json`, `init.sh` тощо) для використання у ваших репозиторіях вже сьогодні.
+
+---
+
+## Швидкий старт: покращте свого агента вже сьогодні
+
+Не потрібно прочитати всі 12 лекцій, перш ніж отримати користь. Якщо ви вже використовуєте агент для написання коду у реальному проєкті, ось як покращити його прямо зараз.
+
+Ідея проста: замість того щоб просто писати промпти, надайте своєму агенту набір структурованих файлів, які визначають що робити, що вже зроблено та як верифікувати роботу. Ці файли зберігаються у вашому репозиторії, тому кожна сесія починається з одного й того самого стану.
+
+```text
+ YOUR PROJECT ROOT
+ ├── AGENTS.md <-- the agent's operating manual
+ ├── CLAUDE.md <-- (alternative, if using Claude Code)
+ ├── init.sh <-- runs install + verify + start
+ ├── feature_list.json <-- what features exist, which are done
+ ├── claude-progress.md <-- what happened each session
+ └── src/ <-- your actual code
+```
+
+Візьміть стартові шаблони з [Бібліотеки ресурсів](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) та додайте їх до свого проєкту. Ось і все. Чотири файли — і ваші сесії з агентом стануть значно стабільнішими, ніж при роботі лише з промптами.
+
+---
+
+## Підсумковий проєкт: реальний застосунок
+
+Усі шість проєктів курсу обертаються навколо одного продукту: **настільного застосунку персональної бази знань на основі Electron**.
+
+```text
+ ┌──────────────────────────────────────────────────────┐
+ │ Knowledge Base Desktop App │
+ │ │
+ │ ┌──────────────┐ ┌──────────────────────────────┐ │
+ │ │ Document List│ │ Q&A Panel │ │
+ │ │ │ │ │ │
+ │ │ doc-001.md │ │ Q: What is harness eng? │ │
+ │ │ doc-002.md │ │ A: The environment built │ │
+ │ │ doc-003.md │ │ around an agent model... │ │
+ │ │ ... │ │ [citation: doc-002.md] │ │
+ │ └──────────────┘ └──────────────────────────────┘ │
+ │ │
+ │ ┌─────────────────────────────────────────────────┐ │
+ │ │ Status Bar: 42 docs | 38 indexed | last sync 3m │ │
+ │ └─────────────────────────────────────────────────┘ │
+ └──────────────────────────────────────────────────────┘
+
+ Core features:
+ ├── Import local documents
+ ├── Manage a document library
+ ├── Process and index documents
+ ├── Run AI-powered Q&A over imported content
+ └── Return grounded answers with citations
+```
+
+Цей проєкт обрано тому, що він поєднує сильну практичну цінність, достатньо реальної продуктової складності та є хорошим середовищем для спостереження покращень harness до і після.
+
+Стартова/фінальна версія кожного проєкту курсу — це повна копія цього Electron-застосунку на відповідній стадії розвитку. Стартова точка P(N+1) похідна від рішення P(N) — застосунок еволюціонує разом із зростанням ваших навичок Harness Engineering.
+
+---
+
+## Навчальний маршрут
+
+Курс спроєктовано для проходження по порядку. Кожна фаза спирається на попередню.
+
+```text
+ Phase 1: SEE THE PROBLEM Phase 2: STRUCTURE THE REPO
+ ======================== ==========================
+
+ L01 Strong models ≠ reliable L03 Repository as single
+ execution source of truth
+ L02 What harness actually means
+ L04 Split instructions across
+ | files, not one giant file
+ v
+ P01 Prompt-only vs. |
+ rules-first comparison v
+ P02 Agent-readable workspace
+
+
+ Phase 3: CONNECT SESSIONS Phase 4: FEEDBACK & SCOPE
+ ========================== =========================
+
+ L05 Keep context alive L07 Draw clear task boundaries
+ across sessions
+ L08 Feature lists as harness
+ L06 Initialize before every primitives
+ agent session
+ |
+ | v
+ v P04 Runtime feedback to
+ P03 Multi-session continuity correct agent behavior
+
+
+ Phase 5: VERIFICATION Phase 6: PUT IT ALL TOGETHER
+ ===================== ============================
+
+ L09 Stop agents from L11 Make agent's runtime
+ declaring victory early observable
+
+ L10 Full-pipeline run = L12 Clean handoff at end of
+ real verification every session
+
+ | |
+ v v
+ P05 Agent verifies its own work P06 Build a complete harness
+ (capstone project)
+```
+
+Кожна фаза займає приблизно тиждень при навчанні неповний робочий день. Якщо ви хочете просуватися швидше, фази 1–3 можна пройти за довгий вихідний.
+
+---
+
+## Навчальна програма
+
+### Лекції — 12 концептуальних модулів, кожен відповідає на одне ключове питання
+
+*Повний текст кожної лекції читайте на [вебсайті документації](https://walkinglabs.github.io/learn-harness-engineering/).*
+
+| Сесія | Питання | Основна ідея |
+|-------|---------|--------------|
+| [L01](./docs/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-застосунку
+
+| Проєкт | Що ви робите | Механізм 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: усі механізми + спостережуваність + дослідження абляції |
+
+```text
+ PROJECT EVOLUTION
+ =================
+
+ P01 Prompt-only vs. rules-first You see the problem
+ |
+ v
+ P02 Agent-readable workspace You restructure the repo
+ |
+ v
+ P03 Multi-session continuity You connect sessions
+ |
+ v
+ P04 Runtime feedback & scope You add feedback loops
+ |
+ v
+ P05 Self-verification You make the agent check itself
+ |
+ v
+ P06 Complete harness (capstone) You build the full system
+
+ Each project's solution becomes the next project's starter.
+ The app evolves. Your harness skills grow with it.
+```
+
+### Бібліотека ресурсів
+
+- [English](https://walkinglabs.github.io/learn-harness-engineering/en/resources/) — templates, checklists, and method references
+- [简体中文](https://walkinglabs.github.io/learn-harness-engineering/zh/resources/) — 中文模板、清单和方法参考
+- [繁體中文](https://walkinglabs.github.io/learn-harness-engineering/zh-TW/resources/) — 繁體中文範本、清單和方法參考
+- [日本語](https://walkinglabs.github.io/learn-harness-engineering/ja/resources/) — テンプレート、チェックリスト、方法リファレンス
+- [한국어](https://walkinglabs.github.io/learn-harness-engineering/ko/resources/) — 템플릿, 체크리스트, 방법 참고 자료
+- [Español](https://walkinglabs.github.io/learn-harness-engineering/es/resources/) — plantillas, listas de verificación y referencias
+- [Français](https://walkinglabs.github.io/learn-harness-engineering/fr/resources/) — modèles, listes de contrôle et références
+- [Русский](https://walkinglabs.github.io/learn-harness-engineering/ru/resources/) — шаблоны, чек-листы и справочники
+- [Deutsch](https://walkinglabs.github.io/learn-harness-engineering/de/resources/) — Vorlagen, Checklisten und Referenzen
+- [العربية](https://walkinglabs.github.io/learn-harness-engineering/ar/resources/) — قوالب، قوائم تحقق ومراجع
+- [Tiếng Việt](https://walkinglabs.github.io/learn-harness-engineering/vi/resources/) — mẫu, danh sách kiểm tra và tài liệu tham khảo
+- [Oʻzbekcha](https://walkinglabs.github.io/learn-harness-engineering/uz/resources/) — andozalar, tekshiruv roʻyxatlari va maʼlumotnomalar
+- [Türkçe](https://walkinglabs.github.io/learn-harness-engineering/tr/resources/) — şablonlar, kontrol listeleri ve referanslar
+- [Português (BR)](https://walkinglabs.github.io/learn-harness-engineering/pt-BR/resources/) — modelos, listas de verificação e referências de métodos
+
+---
+
+## Життєвий цикл агентної сесії
+
+Одна з ключових ідей курсу: **сесія агента має дотримуватися структурованого життєвого циклу, а не відбуватися хаотично.** Ось як це виглядає:
+
+```text
+ AGENT SESSION LIFECYCLE
+ ======================
+
+ ┌──────────────────────────────────────────────────────────────────┐
+ │ START │
+ │ │
+ │ 1. Agent reads AGENTS.md / CLAUDE.md │
+ │ 2. Agent runs init.sh (install, verify, health check) │
+ │ 3. Agent reads claude-progress.md (what happened last time) │
+ │ 4. Agent reads feature_list.json (what's done, what's next) │
+ │ 5. Agent checks git log (recent changes) │
+ │ │
+ │ SELECT │
+ │ │
+ │ 6. Agent picks exactly ONE unfinished feature │
+ │ 7. Agent works only on that feature │
+ │ │
+ │ EXECUTE │
+ │ │
+ │ 8. Agent implements the feature │
+ │ 9. Agent runs verification (tests, lint, type-check) │
+ │ 10. If verification fails: fix and re-run │
+ │ 11. If verification passes: record evidence │
+ │ │
+ │ WRAP UP │
+ │ │
+ │ 12. Agent updates claude-progress.md │
+ │ 13. Agent updates feature_list.json │
+ │ 14. Agent records what's still broken or unverified │
+ │ 15. Agent commits (only when safe to resume) │
+ │ 16. Agent leaves clean restart path for next session │
+ │ │
+ └──────────────────────────────────────────────────────────────────┘
+
+ The harness governs every transition in this lifecycle.
+ The model decides what code to write at each step.
+ Without the harness, step 9 becomes "agent says it looks fine."
+ With the harness, step 9 is "tests pass, lint is clean, types check."
+```
+
+---
+
+## Для кого цей курс
+
+Цей курс призначений для:
+
+- Інженерів, які вже використовують агенти для написання коду і хочуть отримати кращу стабільність та якість
+- Дослідників або розробників, які прагнуть систематичного розуміння проєктування harness
+- Технічних лідів, яким потрібно зрозуміти, як проєктування середовища впливає на продуктивність агента
+
+Цей курс не призначений для:
+
+- Тих, хто шукає вступ до AI без написання коду
+- Тих, кого цікавлять лише промпти і хто не планує будувати реальні реалізації
+- Тих, хто не готовий дозволяти агентам працювати всередині реальних репозиторіїв
+
+---
+
+## Вимоги
+
+Це курс, де ви реально запускаєте агенти для написання коду.
+
+Вам потрібен принаймні один із цих інструментів:
+
+- Claude Code
+- Codex
+- Інший IDE або CLI-агент для написання коду, що підтримує редагування файлів, виконання команд і багатоетапні завдання
+
+Курс передбачає, що ви можете:
+
+- Відкрити локальний репозиторій
+- Дозволити агенту редагувати файли
+- Дозволити агенту виконувати команди
+- Перевіряти результати та повторно запускати завдання
+
+Якщо у вас немає такого інструменту, ви все одно можете читати матеріали курсу, але не зможете виконати проєкти у передбаченому форматі.
+
+---
+
+## Локальний перегляд
+
+Цей репозиторій використовує VitePress як засіб перегляду документації.
+
+```sh
+npm install
+npm run docs:dev # Dev server with hot reload
+npm run docs:build # Production build
+npm run docs:preview # Preview built site
+```
+
+Потім відкрийте в браузері локальну URL-адресу, яку виведе VitePress.
+
+---
+
+## Передумови
+
+Обов'язкові:
+
+- Знайомство з терміналом, Git і локальними середовищами розробки
+- Здатність читати і писати код принаймні в одному поширеному прикладному стеку
+- Базовий досвід налагодження програмного забезпечення (читання логів, тестів і поведінки runtime)
+- Достатньо часу для навчання, орієнтованого на реалізацію
+
+Корисно, але не обов'язково:
+
+- Досвід роботи з Electron, настільними застосунками або локальними інструментами
+- Досвід тестування, логування або архітектури програмного забезпечення
+- Попередній досвід роботи з Codex, Claude Code або подібними агентами для написання коду
+
+---
+
+## Основні джерела
+
+Первинні:
+
+- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
+- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
+- [OpenAI: Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/)
+- [Anthropic: Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)
+- [LangChain: Improving Deep Agents with harness engineering](https://www.langchain.com/blog/improving-deep-agents-with-harness-engineering)
+- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html)
+- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness)
+
+Повний багаторівневий список джерел дивіться у [`docs/en/resources/reference/`](./docs/en/resources/reference/index.md).
+
+---
+
+## Структура репозиторію
+
+```text
+learn-harness-engineering/
+├── docs/ # VitePress documentation site
+│ ├── lectures/ # 12 lectures (index.md + code/ examples)
+│ │ ├── lecture-01-*/
+│ │ └── ... (12 total)
+│ ├── projects/ # 6 project descriptions
+│ │ ├── project-01-*/
+│ │ └── ... (6 total)
+│ └── resources/ # Multilingual templates & references (14 languages)
+│ ├── en/
+│ └── ... (14 total)
+├── projects/
+│ ├── shared/ # Shared Electron + TypeScript + React foundation
+│ └── project-NN/ # Per-project starter/ and solution/ directories
+├── skills/ # Reusable AI agent skills
+│ └── harness-creator/ # Harness engineering skill
+├── package.json # VitePress + dev tooling
+└── CLAUDE.md # Claude Code instructions for this repo
+```
+
+---
+
+## Як організований курс
+
+- Кожна лекція зосереджена на одному питанні
+- Курс включає 6 проєктів
+- Кожен проєкт вимагає від агента виконання реальної роботи
+- Кожен проєкт порівнює результати слабкого та сильного harness
+- Важлива вимірювана різниця, а не кількість написаної документації
+
+---
+
+## Навички
+
+Цей репозиторій також включає багаторазові навички AI-агентів, які можна встановити безпосередньо у ваш IDE або агентне робоче середовище.
+
+- [**harness-creator**](./skills/harness-creator/): Навичка, яка допомагає за лічені хвилини підготувати harness виробничого рівня для вашого власного проєкту.
+
+---
+
+## Інші курси
+
+Наша команда також створила інші курси! Ознайомтеся з ними:
+
+[![Hands-on Modern RL](https://img.shields.io/badge/HANDS--ON_MODERN_RL-0052cc?style=for-the-badge)](https://github.com/walkinglabs/hands-on-modern-rl)
+
+**Hands-on Modern RL**: Відкритий практичний навчальний план, що усуває розрив між базовими концепціями RL та вирівнюванням LLM, RLVR і просунутими агентними системами.
+
+[![Modern LLM Notebook](https://img.shields.io/badge/MODERN_LLM_NOTEBOOK-0052cc?style=for-the-badge)](https://github.com/walkinglabs/modern-llm-notebook)
+
+**Modern LLM Notebook**: Практичний курс із побудови сучасних LLM з нуля на PyTorch, включаючи 23 запускабельних Jupyter Notebooks з темами токенізаторів, уваги, MoE, RLHF, висновку, оцінювання та дистиляції.
+
+---
+
+## Історія зірок
+
+[![Star History Chart](https://api.star-history.com/svg?repos=walkinglabs/learn-harness-engineering&type=date&legend=top-left)](https://www.star-history.com/#walkinglabs/learn-harness-engineering&type=date&legend=top-left)
+
+---
+
+## Подяки
+
+Цей курс натхненний та черпає ідеї з [learn-claude-code](https://github.com/shareAI-lab/learn-claude-code) — покрокового посібника з побудови агента з нуля, від простого циклу до ізольованого автономного виконання.
diff --git a/docs-readme/uz-UZ/README.md b/docs-readme/uz-UZ/README.md
index 6580f88..f9c9c32 100644
--- a/docs-readme/uz-UZ/README.md
+++ b/docs-readme/uz-UZ/README.md
@@ -13,6 +13,7 @@
<a href="../uz-UZ/README.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>
<a href="../tr-TR/README.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?style=flat-square"></a>
<a href="../pt-BR/README.md"><img alt="Português-BR" src="https://img.shields.io/badge/PT--BR-Português-1A8BBA?style=flat-square"></a>
+ <a href="../uk-UA/README.md"><img alt="Українська" src="https://img.shields.io/badge/UK-Українська-0057B7?style=flat-square"></a>
</p>
# Learn Harness Engineering
diff --git a/docs-readme/vi-VN/README.md b/docs-readme/vi-VN/README.md
index 133f3d3..64c4405 100644
--- a/docs-readme/vi-VN/README.md
+++ b/docs-readme/vi-VN/README.md
@@ -13,6 +13,7 @@
<a href="../uz-UZ/README.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>
<a href="../tr-TR/README.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?style=flat-square"></a>
<a href="../pt-BR/README.md"><img alt="Português-BR" src="https://img.shields.io/badge/PT--BR-Português-1A8BBA?style=flat-square"></a>
+ <a href="../uk-UA/README.md"><img alt="Українська" src="https://img.shields.io/badge/UK-Українська-0057B7?style=flat-square"></a>
</p>
# Learn Harness Engineering
diff --git a/docs-readme/zh-CN/README.md b/docs-readme/zh-CN/README.md
index a1cb0db..7006c6b 100644
--- a/docs-readme/zh-CN/README.md
+++ b/docs-readme/zh-CN/README.md
@@ -13,6 +13,7 @@
<a href="../uz-UZ/README.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>
<a href="../tr-TR/README.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?style=flat-square"></a>
<a href="../pt-BR/README.md"><img alt="Português-BR" src="https://img.shields.io/badge/PT--BR-Português-1A8BBA?style=flat-square"></a>
+ <a href="../uk-UA/README.md"><img alt="Українська" src="https://img.shields.io/badge/UK-Українська-0057B7?style=flat-square"></a>
</p>
# Learn Harness Engineering
diff --git a/docs-readme/zh-TW/README.md b/docs-readme/zh-TW/README.md
index 5835f62..c12cc7f 100644
--- a/docs-readme/zh-TW/README.md
+++ b/docs-readme/zh-TW/README.md
@@ -13,6 +13,7 @@
<a href="../uz-UZ/README.md"><img alt="Oʻzbekcha" src="https://img.shields.io/badge/UZ-Oʻzbekcha-1A8BBA?style=flat-square"></a>
<a href="../tr-TR/README.md"><img alt="Türkçe" src="https://img.shields.io/badge/TR-Türkçe-E30A17?style=flat-square"></a>
<a href="../pt-BR/README.md"><img alt="Português-BR" src="https://img.shields.io/badge/PT--BR-Português-1A8BBA?style=flat-square"></a>
+ <a href="../uk-UA/README.md"><img alt="Українська" src="https://img.shields.io/badge/UK-Українська-0057B7?style=flat-square"></a>
</p>
# Learn Harness Engineering
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index f7a8611..1dfc373 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -529,6 +529,43 @@ const ptBRSkillItems = [
{ text: "Visão Geral das Skills", link: "/pt-BR/skills/" },
];
+const ukLectureItems = [
+ { text: "Вітаємо", link: "/uk/" },
+ { text: "Сильна модель не гарантує надійного виконання", link: "/uk/lectures/lecture-01-why-capable-agents-still-fail/" },
+ { text: "Що таке harness насправді", link: "/uk/lectures/lecture-02-what-a-harness-actually-is/" },
+ { text: "Чому репозиторій має стати єдиним джерелом правди", link: "/uk/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/" },
+ { text: "Чому один величезний файл інструкцій не працює", link: "/uk/lectures/lecture-04-why-one-giant-instruction-file-fails/" },
+ { text: "Чому довготривалі задачі втрачають контекст", link: "/uk/lectures/lecture-05-why-long-running-tasks-lose-continuity/" },
+ { text: "Чому ініціалізація потребує окремої фази", link: "/uk/lectures/lecture-06-why-initialization-needs-its-own-phase/" },
+ { text: "Чому агенти беруть забагато й не доводять до кінця", link: "/uk/lectures/lecture-07-why-agents-overreach-and-under-finish/" },
+ { text: "Чому списки функціональності — це примітиви harness", link: "/uk/lectures/lecture-08-why-feature-lists-are-harness-primitives/" },
+ { text: "Чому агенти надто рано оголошують перемогу", link: "/uk/lectures/lecture-09-why-agents-declare-victory-too-early/" },
+ { text: "Чому наскрізне тестування змінює результати", link: "/uk/lectures/lecture-10-why-end-to-end-testing-changes-results/" },
+ { text: "Чому спостережуваність має бути всередині harness", link: "/uk/lectures/lecture-11-why-observability-belongs-inside-the-harness/" },
+ { text: "Чому кожна сесія має залишати чистий стан", link: "/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" },
+];
+
+const ukProjectItems = [
+ { text: "Вітаємо", link: "/uk/projects/" },
+ { text: "Тільки промпт vs. правила спочатку", link: "/uk/projects/project-01-baseline-vs-minimal-harness/" },
+ { text: "Робоче середовище, зрозуміле агенту", link: "/uk/projects/project-02-agent-readable-workspace/" },
+ { text: "Безперервність між сесіями", link: "/uk/projects/project-03-multi-session-continuity/" },
+ { text: "Зворотний зв'язок у runtime і контроль обсягу", link: "/uk/projects/project-04-incremental-indexing/" },
+ { text: "Самоверифікація та розподіл ролей", link: "/uk/projects/project-05-grounded-qa-verification/" },
+ { text: "Повний harness (підсумковий проєкт)", link: "/uk/projects/project-06-runtime-observability-and-debugging/" },
+];
+
+const ukResourceItems = [
+ { text: "Огляд", link: "/uk/resources/" },
+ { text: "Шаблони", link: "/uk/resources/templates/" },
+ { text: "Довідник", link: "/uk/resources/reference/" },
+ { text: "Розширений пакет", link: "/uk/resources/openai-advanced/" },
+];
+
+const ukSkillItems = [
+ { text: "Огляд Skills", link: "/uk/skills/" },
+];
+
const jaSourceItems = { lectures: jaLectureItems, projects: jaProjectItems, resources: jaResourceItems, skills: jaSkillItems };
const esSourceItems = { lectures: esLectureItems, projects: esProjectItems, resources: esResourceItems, skills: esSkillItems };
const frSourceItems = { lectures: frLectureItems, projects: frProjectItems, resources: frResourceItems, skills: frSkillItems };
@@ -536,12 +573,13 @@ const deSourceItems = { lectures: deLectureItems, projects: deProjectItems, reso
const arSourceItems = { lectures: arLectureItems, projects: arProjectItems, resources: arResourceItems, skills: arSkillItems };
const zhTWSourceItems = { lectures: zhTWLectureItems, projects: zhTWProjectItems, resources: zhTWResourceItems, skills: zhTWSkillItems };
const trSourceItems = { lectures: trLectureItems, projects: trProjectItems, resources: trResourceItems, skills: trSkillItems };
+const ukSourceItems = { lectures: ukLectureItems, projects: ukProjectItems, resources: ukResourceItems, skills: ukSkillItems };
const relinkItems = (items: Array<{ text: string; link: string }>, locale: string) =>
items.map((item) => ({
...item,
link: item.link.replace(
- /^\/(en|zh|vi|ko|uz|ru|ja|es|fr|de|ar|zh-TW|tr|pt-BR)\//,
+ /^\/(en|zh|vi|ko|uz|ru|ja|es|fr|de|ar|zh-TW|tr|pt-BR|uk)\//,
`/${locale}/`,
),
}));
@@ -1183,6 +1221,28 @@ export default withMermaid(
socialLinks,
},
},
+ uk: {
+ label: "Українська",
+ lang: "uk",
+ link: "/uk/",
+ themeConfig: createLocaleTheme("uk", ukSourceItems, {
+ lectures: "Лекції",
+ projects: "Проєкти",
+ resources: "Бібліотека",
+ skills: "Skills",
+ resourceLibrary: "Бібліотека ресурсів",
+ tryHarness: "Try Harness ↗",
+ outline: "На цій сторінці",
+ prev: "Назад",
+ next: "Далі",
+ lastUpdated: "Останнє оновлення",
+ returnToTop: "Повернутися нагору",
+ sidebarMenu: "Меню",
+ darkModeSwitch: "Тема",
+ lightModeSwitchTitle: "Перемкнути на світлу тему",
+ darkModeSwitchTitle: "Перемкнути на темну тему",
+ }),
+ },
},
}),
);
diff --git a/docs/index.md b/docs/index.md
index 74ba35f..a9df0b9 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -19,6 +19,7 @@ if (typeof window !== 'undefined') {
else if (lang.startsWith('fr')) locale = 'fr/'
else if (lang.startsWith('de')) locale = 'de/'
else if (lang.startsWith('ar')) locale = 'ar/'
+ else if (lang.startsWith('uk')) locale = 'uk/'
else if (lang.startsWith('tr')) locale = 'tr/'
const target = `${base}${locale}`
diff --git a/docs/public/screenshots/readme/uk-home.png b/docs/public/screenshots/readme/uk-home.png
new file mode 100644
index 0000000..09d689d
Binary files /dev/null and b/docs/public/screenshots/readme/uk-home.png differ
diff --git a/docs/public/screenshots/readme/uk-lecture-01.png b/docs/public/screenshots/readme/uk-lecture-01.png
new file mode 100644
index 0000000..299c3f7
Binary files /dev/null and b/docs/public/screenshots/readme/uk-lecture-01.png differ
diff --git a/docs/public/screenshots/readme/uk-resources.png b/docs/public/screenshots/readme/uk-resources.png
new file mode 100644
index 0000000..3519ef7
Binary files /dev/null and b/docs/public/screenshots/readme/uk-resources.png differ
diff --git a/docs/uk/index.md b/docs/uk/index.md
new file mode 100644
index 0000000..43657c8
--- /dev/null
+++ b/docs/uk/index.md
@@ -0,0 +1,73 @@
+# Ласкаво просимо до Learn Harness Engineering
+
+Learn Harness Engineering — це курс, присвячений інженерії AI-агентів для написання коду. Ми детально вивчили та синтезували найбільш передові теорії і практики Harness Engineering у галузі. Наші основні джерела:
+- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
+- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
+- [Awesome Harness Engineering](https://github.com/walkinglabs/awesome-harness-engineering)
+
+Через системне проектування середовища, управління станом, верифікацію та системи контролю цей курс навчає, як зробити агентні інструменти для написання коду — Codex і Claude Code — справді надійними. Він допомагає вам будувати функціонал, виправляти помилки та автоматизувати задачі розробки, обмежуючи AI-асистента чіткими правилами і межами.
+
+## Початок роботи
+
+Оберіть свій навчальний шлях. Курс поділено на теоретичні лекції, практичні проєкти та бібліотеку готових до використання ресурсів.
+
+<div class="card-grid">
+ <a href="./lectures/lecture-01-why-capable-agents-still-fail/" class="card">
+ <h3>Лекції</h3>
+ <p>Зрозумійте, чому сильні моделі все одно помиляються, і вивчіть теорію ефективних harness.</p>
+ </a>
+ <a href="./projects/" class="card">
+ <h3>Проєкти</h3>
+ <p>Практика: побудуйте надійне агентне середовище з нуля.</p>
+ </a>
+ <a href="./resources/" class="card">
+ <h3>Бібліотека ресурсів</h3>
+ <p>Готові шаблони (AGENTS.md, feature_list.json) для використання у власних репозиторіях.</p>
+ </a>
+</div>
+
+## Основний механізм harness
+
+Harness не «робить модель розумнішою» — він встановлює для моделі замкнуту **робочу систему**. Основний робочий процес можна зрозуміти з цієї простої діаграми:
+
+```mermaid
+graph TD
+ A["Clear Objective<br/>AGENTS.md"] --> B("Initialization<br/>init.sh")
+ B --> C{"Run Tasks<br/>AI Agent"}
+ C -->|Encounter Issues| D["Runtime Feedback<br/>CLI / Logs"]
+ D -->|Auto-fix| C
+ C -->|Code Completed| E{"Verify & QA<br/>Test suite"}
+ E -->|Failed| D
+ E -->|Passed| F["Cleanup & Handoff<br/>claude-progress.md"]
+
+ classDef primary fill:#D95C41,stroke:#C14E36,color:#fff,font-weight:bold;
+ classDef process fill:#F4F3EE,stroke:#D1D1D1,color:#1A1A1A;
+ classDef check fill:#EAE8E1,stroke:#B3B3B3,color:#1A1A1A;
+
+ class A,F primary;
+ class B,D process;
+ class C,E check;
+```
+
+## Що ви вивчите
+
+Ось деякі з ключових концепцій, якими ви оволодієте:
+
+<ul class="index-list">
+ <li><strong>Обмежуйте поведінку агента</strong> чіткими правилами і межами.</li>
+ <li><strong>Підтримуйте контекст</strong> впродовж тривалих багатосесійних задач.</li>
+ <li><strong>Зупиняйте агентів</strong>, що занадто рано оголошують про завершення.</li>
+ <li><strong>Верифікуйте роботу</strong> за допомогою наскрізних тестів і самоаналізу.</li>
+ <li><strong>Робіть runtime спостережуваним</strong> і зручним для налагодження.</li>
+</ul>
+
+## Наступні кроки
+
+Після того як ви засвоїте базові концепції, ці матеріали допоможуть поглибити знання:
+
+<ul class="index-list">
+ <li><a href="./lectures/lecture-01-why-capable-agents-still-fail/">Лекція 01: Чому здатні агенти все одно зазнають збоїв</a>: Починайте з теорії harness engineering.</li>
+ <li><a href="./projects/project-01-baseline-vs-minimal-harness/">Проєкт 01: Baseline vs Minimal Harness</a>: Виконайте свою першу реальну задачу.</li>
+ <li><a href="./resources/templates/">Шаблони</a>: Візьміть мінімальний harness-пакет (AGENTS.md, feature_list.json, claude-progress.md) для власних проєктів.</li>
+</ul>
diff --git a/docs/uk/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts b/docs/uk/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts
new file mode 100644
index 0000000..311e665
--- /dev/null
+++ b/docs/uk/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts
@@ -0,0 +1,170 @@
+/**
+ * failure-pattern-demo.ts
+ *
+ * Simulates the 4-step failure pattern that capable agents fall into:
+ * 1. Incomplete context
+ * 2. Locally reasonable changes
+ * 3. No global verification
+ * 4. Premature completion
+ *
+ * Run: npx tsx docs/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface StepState {
+ step: number;
+ name: string;
+ contextAvailable: string[];
+ contextMissing: string[];
+ actionTaken: string;
+ localOutcome: string;
+ globalImpact: string;
+ completed: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Simulated "model" -- a simple decision function that bases its output
+// solely on whatever context it has been given.
+// ---------------------------------------------------------------------------
+
+function modelDecide(context: string[], task: string): string {
+ const has = (s: string) => context.some((c) => c.includes(s));
+
+ // The task is to "add a search endpoint to the API".
+ // Correct answer requires knowing about auth middleware and rate limiting.
+
+ if (!has("auth")) {
+ return "Created new route handler /search without authentication checks";
+ }
+ if (!has("rate-limit")) {
+ return "Added search route with auth but forgot rate limiting";
+ }
+ if (!has("test-standards")) {
+ return "Implemented search with auth and rate-limit, but no tests";
+ }
+ return "Fully implemented search endpoint with auth, rate-limit, and tests";
+}
+
+// ---------------------------------------------------------------------------
+// Failure simulation
+// ---------------------------------------------------------------------------
+
+function simulateFailurePattern(): StepState[] {
+ const steps: StepState[] = [];
+
+ // ---- Step 1: Incomplete Context ----
+ const step1Context = ["project structure", "route definitions"];
+ const step1Missing = ["auth middleware", "rate-limiting policy", "test standards"];
+ const step1Decision = modelDecide(step1Context, "add search endpoint");
+
+ steps.push({
+ step: 1,
+ name: "Incomplete Context",
+ contextAvailable: step1Context,
+ contextMissing: step1Missing,
+ actionTaken: step1Decision,
+ localOutcome: "Looks good -- route compiles, returns data",
+ globalImpact: "Missing auth means unauthenticated access to search",
+ completed: false,
+ });
+
+ // ---- Step 2: Locally Reasonable Changes ----
+ // The agent adds auth after a hint, but still lacks other context.
+ const step2Context = [...step1Context, "auth middleware"];
+ const step2Missing = ["rate-limiting policy", "test standards"];
+ const step2Decision = modelDecide(step2Context, "add search endpoint");
+
+ steps.push({
+ step: 2,
+ name: "Locally Reasonable Changes",
+ contextAvailable: step2Context,
+ contextMissing: step2Missing,
+ actionTaken: step2Decision,
+ localOutcome: "Route has auth -- looks complete locally",
+ globalImpact: "No rate limiting means the endpoint can be abused",
+ completed: false,
+ });
+
+ // ---- Step 3: No Global Verification ----
+ const step3Context = [...step2Context, "rate-limiting policy"];
+ const step3Missing = ["test standards"];
+ const step3Decision = modelDecide(step3Context, "add search endpoint");
+
+ steps.push({
+ step: 3,
+ name: "No Global Verification",
+ contextAvailable: step3Context,
+ contextMissing: step3Missing,
+ actionTaken: step3Decision,
+ localOutcome: "Feature appears fully implemented",
+ globalImpact: "No tests -- regression risk, violates project standards",
+ completed: false,
+ });
+
+ // ---- Step 4: Premature Completion ----
+ steps.push({
+ step: 4,
+ name: "Premature Completion",
+ contextAvailable: step3Context,
+ contextMissing: step3Missing,
+ actionTaken: 'Agent outputs: "Done. Added search endpoint."',
+ localOutcome: "Agent is satisfied, task marked complete",
+ globalImpact: "Task is incomplete -- missing tests, no E2E verification",
+ completed: true,
+ });
+
+ return steps;
+}
+
+// ---------------------------------------------------------------------------
+// Comparison table
+// ---------------------------------------------------------------------------
+
+function printComparisonTable(steps: StepState[]): void {
+ console.log("\n" + "=".repeat(90));
+ console.log(" FAILURE PATTERN DEMO -- 4 Steps to a Broken Deliverable");
+ console.log("=".repeat(90));
+
+ for (const s of steps) {
+ console.log(`\n Step ${s.step}: ${s.name}`);
+ console.log(" " + "-".repeat(60));
+ console.log(` Context available : ${s.contextAvailable.join(", ")}`);
+ console.log(` Context missing : ${s.contextMissing.join(", ") || "(none)"}`);
+ console.log(` Action taken : ${s.actionTaken}`);
+ console.log(` Local outcome : ${s.localOutcome}`);
+ console.log(` Global impact : ${s.globalImpact}`);
+ console.log(` Marked complete? : ${s.completed ? "YES (premature)" : "No"}`);
+ }
+
+ // Summary comparison
+ console.log("\n" + "=".repeat(90));
+ console.log(" COMPARISON: What the agent saw vs. what was actually needed");
+ console.log("=".repeat(90));
+
+ const totalRequired = ["project structure", "route definitions", "auth middleware", "rate-limiting policy", "test standards"];
+ const finalAvailable = steps[steps.length - 1].contextAvailable;
+
+ const header = "| Criterion | Available | Missing | Status |";
+ const sep = "|------------------------|-----------|---------|----------|";
+ console.log("\n" + header);
+ console.log(sep);
+
+ for (const item of totalRequired) {
+ const avail = finalAvailable.includes(item);
+ const row = `| ${item.padEnd(23)}| ${(avail ? "Yes" : "No").padEnd(10)}| ${(!avail ? "Yes" : "").padEnd(8)}| ${(avail ? "OK" : "GAP").padEnd(9)}|`;
+ console.log(row);
+ }
+
+ const gapCount = totalRequired.filter((i) => !finalAvailable.includes(i)).length;
+ console.log("\n Result: Agent completed with " + gapCount + " of " + totalRequired.length + " context items missing.");
+ console.log(" This is the core failure pattern: each step looked reasonable in isolation.\n");
+}
+
+// ---------------------------------------------------------------------------
+// Run
+// ---------------------------------------------------------------------------
+
+printComparisonTable(simulateFailurePattern());
diff --git a/docs/uk/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md b/docs/uk/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md
new file mode 100644
index 0000000..0dc56ef
--- /dev/null
+++ b/docs/uk/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md
@@ -0,0 +1,9 @@
+# Чекліст сигналів збою
+
+Використовуйте цей чекліст під час аналізу запуску зі слабким harness.
+
+- Чи запитував агент, або невірно здогадувався, як запустити застосунок?
+- Чи створював він директорії або абстракції, що не відповідають задуманому продукту?
+- Чи зупинявся він після створення видимої UI-оболонки без повноцінного робочого процесу?
+- Чи залишав він нотатки або артефакти, що допомогли б наступному запуску продовжити роботу?
+- Чи зможе нова сесія зрозуміти, що відбулося, менш ніж за п'ять хвилин?
diff --git a/docs/uk/lectures/lecture-01-why-capable-agents-still-fail/code/index.md b/docs/uk/lectures/lecture-01-why-capable-agents-still-fail/code/index.md
new file mode 100644
index 0000000..790d57e
--- /dev/null
+++ b/docs/uk/lectures/lecture-01-why-capable-agents-still-fail/code/index.md
@@ -0,0 +1,7 @@
+# Код до Лекції 01
+
+Використовуйте цю теку для невеликих прикладів, що демонструють:
+
+- сильну модель, що зазнає збою в слабкому середовищі
+- репозиторій із неповним налаштуванням
+- відсутні зворотні зв'язки
diff --git a/docs/uk/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md b/docs/uk/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md
new file mode 100644
index 0000000..1c77d63
--- /dev/null
+++ b/docs/uk/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md
@@ -0,0 +1,18 @@
+# Приклад недостатньо специфікованої задачі
+
+Збудуй десктопний застосунок для бази знань із відповідями на запитання за допомогою AI.
+
+Обмеження:
+
+- Не вказані
+- Команда запуску не надана
+- Структура тек не визначена
+- Модель даних не описана
+- Явних критеріїв завершення немає
+
+Типові результати такого промпту:
+
+- агент вигадує структуру ad hoc
+- застосунок може компілюватися, але запускатися нестабільно
+- UI може з'явитися раніше, ніж з'явиться будь-який придатний для використання шлях інтеграції/запиту даних
+- агент нерідко зупиняється після косметичного успіху
diff --git a/docs/uk/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/uk/lectures/lecture-01-why-capable-agents-still-fail/index.md
new file mode 100644
index 0000000..fe426a6
--- /dev/null
+++ b/docs/uk/lectures/lecture-01-why-capable-agents-still-fail/index.md
@@ -0,0 +1,103 @@
+[中文版 →](../../../zh/lectures/lecture-01-why-capable-agents-still-fail/)
+
+> Приклади коду: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/uk/lectures/lecture-01-why-capable-agents-still-fail/code/)
+> Практичний проєкт: [Проєкт 01. Тільки промпт проти підходу «правила насамперед»: наскільки велика різниця від harness](./../../projects/project-01-baseline-vs-minimal-harness/index.md)
+
+# Лекція 01. Сильна модель — ще не гарантія надійного виконання
+
+Наприкінці 2025 року найсильніші агенти для написання коду на SWE-bench Verified досягають приблизно 50–60% успішних проходжень. На перший погляд цифра здається непоганою — але не поспішайте радіти. Це ретельно відібрані задачі з чіткими описами і готовими тестами. Дайте агенту ваші повсякденні вимоги — розмиті специфікації, відсутні тести, неявні бізнес-правила, розкидані по всьому коду, — і відсоток успіху впаде ще нижче. Ви передаєте задачу з повною впевненістю, агент працює 20 хвилин і повідомляє «все зроблено», а ви дивитесь на код: функціонал додано, але тести зламані, баг виправлено, але з'явилися нові, та й взагалі — це не те, про що ви просили.
+
+Коли таке трапляється, перша реакція більшості — «модель недостатньо хороша, спробую дорожчу». Перш ніж тягтися до гаманця, подумайте: проблема може бути зовсім не в моделі.
+
+## Один кінь, дві долі
+
+Anthropic провела контрольований експеримент, який ідеально ілюструє цю думку. Один і той самий промпт («збудуй 2D-редактор ретро-ігор»), одна й та сама модель (Opus 4.5), два запуски. Перший запуск: без підтримки — 20 хвилин, $9, основний функціонал гри не працював. Другий запуск: повноцінний harness — архітектура з трьох агентів (планувальник, генератор, оцінювач) — 6 годин, $200, гра повністю готова до гри.
+
+Модель не змінювали. Opus 4.5 залишався Opus 4.5. Змінилося спорядження.
+
+Стаття OpenAI про harness engineering 2025 року висловлюється ще прямолінійніше. Там сказано, що Codex у добре підготовленому репозиторії переходить від «ненадійного» прямо до «надійного». Зверніть увагу на формулювання — не «трохи кращий», а якісний стрибок. Harness тут означає **всю інженерну інфраструктуру поза вагами моделі.**
+
+## Де агенти насправді застрягають
+
+Конкретні сценарії збоїв зводяться лише до кількох типових ситуацій:
+
+- **Розмиті вимоги — агент змушений вгадувати.** «Додай функцію пошуку» — це речення майже нічого не означає. Пошук чого? Повнотекстовий чи структурований? Чи потрібна пагінація? Підсвічування? Ви не уточнили — агент вгадує. Правильне вгадування — це удача; неправильне — переробка, яка коштує в рази дорожче за конкретизацію на старті.
+- **Неявні конвенції, не зафіксовані в жодному документі, — агент не може їх дотримуватися.** Уся команда використовує новий синтаксис SQLAlchemy 2.0, а агент за замовчуванням пише код 1.x. Усі API-ендпоінти мають проходити через автентифікацію OAuth 2.0, але це правило існує лише у вашій голові та в повідомленні Slack тримісячної давнини. Агент не має жодного уявлення про це — не тому що не хоче дотримуватися правил, а тому що він їх просто ніколи не бачив.
+- **Неповне налаштування середовища — агент витрачає сили на виправлення оточення.** Незавершений dev-сетап, відсутні залежності, невірні версії інструментів — агент спалює дорогоцінне контекстне вікно на помилки `pip install` і конфлікти версій Node замість того, щоб виконувати реальну роботу.
+- **Відсутність методів верифікації — агент вважає задачу завершеною, коли йому так здається.** Немає тестів, немає лінтера чи верифікаційних команд, про які агенту не повідомили. Агент пише код, перечитує його, вирішує, що все виглядає нормально, і оголошує про завершення. Anthropic також зафіксувала цікавий феномен: коли агенти відчувають, що контекстне вікно закінчується, вони поспішають із завершенням, пропускають кроки верифікації та обирають просте рішення замість оптимального. Це явище називають «контекстною тривогою».
+- **Втрата стану між сесіями — кожна нова сесія починається з нуля.** Усі відкриття попередньої сесії зникають. Кожна нова сесія змушена заново досліджувати структуру проєкту і заново розуміти організацію коду. Агенти без збереження стану демонструють різке зростання відсотка відмов на задачах, що перевищують 30 хвилин.
+
+## Ключова термінологія
+
+З огляду на описані вище сценарії ці концепції вже не є просто жаргоном:
+
+- **Capability Gap (Розрив у можливостях)**: Величезна прірва між продуктивністю моделі на бенчмарках і продуктивністю на реальних задачах. 50–60% на SWE-bench Verified означає, що майже половина реальних проблем залишається невирішеною.
+- **Harness**: Все, що знаходиться поза моделлю — інструкції, інструменти, середовище, управління станом, зворотний зв'язок для верифікації. Якщо це не ваги моделі — це harness. Те, що ми називали «спорядженням».
+- **Harness-Induced Failure (Збій, спричинений harness)**: Модель має достатні можливості, але середовище виконання має структурні дефекти. Контрольований експеримент Anthropic вже довів це.
+- **Verification Gap (Розрив верифікації)**: Розрив між впевненістю агента у своєму результаті та реальною коректністю. Агент каже «я готовий», коли насправді ні — це найпоширеніший сценарій збою.
+- **Diagnostic Loop (Діагностичний цикл)**: Виконати — зафіксувати збій — встановити, який шар harness його спричинив — виправити цей шар — виконати знову. Це основна методологія harness engineering.
+- **Definition of Done (Визначення завершеності)**: Набір умов, перевірних командою — тести проходять, лінтер чистий, перевірка типів пройдена. Без явного визначення завершеності агент вигадає власне.
+
+## Коли щось іде не так — спочатку перевіряйте harness
+
+Є лише один ключовий принцип: **Коли щось іде не так — не міняйте модель першою, перевіряйте harness.** Якщо та сама модель успішно справляється зі схожими, добре структурованими задачами — вважайте, що проблема в harness.
+
+Як це виглядає на практиці? Відносьте кожен збій до конкретного шару. Не кажіть просто «модель недостатньо хороша». Запитайте себе: задача була незрозумілою? Контексту не вистачало? Методів верифікації не було? Зіставляйте кожен збій з одним із п'яти захисних шарів: специфікація задачі, надання контексту, середовище виконання, зворотний зв'язок для верифікації, управління станом. Виробіть цю звичку — і ви побачите, що фраза «модель недостатньо хороша» все рідше з'являтиметься у ваших нотатках.
+
+Потім пишіть явне Визначення завершеності для кожної задачі. Не кажіть «додай функцію пошуку». Деталізуйте:
+```
+Критерії завершення:
+- Новий ендпоінт GET /api/search?q=xxx
+- Підтримує пагінацію, за замовчуванням 20 елементів
+- Результати містять підсвічені фрагменти
+- Весь новий код проходить pytest
+- Перевірка типів пройдена (mypy --strict)
+```
+
+Розмістіть файл `AGENTS.md` у корені репозиторію — він повідомить агенту про технологічний стек проєкту, архітектурні конвенції та верифікаційні команди. Це перший крок у harness engineering і той, що дає найвищу віддачу від вкладень. Один файл `AGENTS.md` може бути ефективнішим за перехід на дорожчу модель — і це не жарт.
+
+Далі будуйте діагностичний цикл. Не сприймайте збої як «модель знову тупить». Сприймайте їх як сигнали про те, що ваш harness виявив дефект. При кожному збої визначайте шар, виправляйте його — і більше ніколи не провалюйтеся на цьому місці. Після кількох ітерацій harness стає міцнішим, а продуктивність агента стабілізується. Достатньо простого журналу — для кожної задачі фіксуйте: успіх чи збій, і який шар спричинив збій. Після кількох раундів ви побачите, який шар є вузьким місцем, і зможете зосередити зусилля саме там.
+
+## Експеримент з мільйоном рядків
+
+У 2025 році троє інженерів OpenAI розпочали експеримент. Правила були прості: вони самі не пишуть код — тільки Codex. Починаючи з порожнього git-репозиторію, через п'ять місяців у репозиторії було приблизно мільйон рядків коду. Логіка застосунку, інфраструктура, інструментарій, документація — все згенеровано агентом. Троє інженерів відкрили загалом 1500 PR, в середньому 3,5 на людину на день.
+
+Перші кроки виявилися напрочуд повільними. Codex був не поганий — він просто не мав інструментів і структур, достатньо повних для досягнення цілей високого рівня. Троє інженерів поступово виявили закономірність: розбивайте великі цілі на дрібні будівельні блоки — проектування, код, рев'ю, тести — давайте агенту складати їх один за одним, а потім використовуйте ці блоки для компонування складніших задач. Щоразу, коли щось ішло не так, проблема майже ніколи не була «недостатнє старання». Завжди: «чого агенту ще не вистачає, і чи можна надати цю відсутню можливість у спосіб, зрозумілий і придатний до виконання?»
+
+Цей експеримент безпосередньо доводить головну тезу лекції: **та сама модель дає принципово різний результат у голому середовищі та в середовищі з повноцінним harness.** Модель не змінилася. Змінилося середовище.
+
+> Джерело: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
+
+## Більш приземлений приклад
+
+Одна команда використовувала Claude Sonnet для додавання нових API-ендпоінтів до середнього Python-веб-застосунку (FastAPI + PostgreSQL + Redis, ~15 000 рядків коду).
+
+Спочатку вони дали лише одне речення: «додай ендпоінти налаштувань користувача під `/api/v2/users`». Результат? Агент витратив 40% контекстного вікна на дослідження структури репозиторію, написав код, що виглядав розумно, але не відповідав паттернам обробки помилок у проєкті, використав старий синтаксис SQLAlchemy та оголосив про завершення, коли в ендпоінті були runtime-помилки. Наступна сесія мала заново виконати всю розвідку.
+
+Пізніше вони додали `AGENTS.md` (з описом архітектури проєкту та версій технологічного стека), явні верифікаційні команди (`pytest tests/api/v2/ && python -m mypy src/`) та записи про архітектурні рішення. Та сама модель успішно виконала завдання в усіх трьох незалежних запусках, з ефективністю використання контексту приблизно на 60% вищою.
+
+Модель не змінювали. Змінили harness.
+
+## Ключові висновки
+
+- Можливості моделі та надійність виконання — це дві різні речі. Навіть породистий кінь потребує гарного спорядження.
+- Коли щось іде не так — спочатку перевіряйте harness, потім модель. Заміна моделі — найдорожчий варіант, і найчастіше проблема взагалі не в ній.
+- Кожен збій — це сигнал: у вашому harness є структурний дефект. Знайдіть його й виправте.
+- Не кажіть просто «модель недостатньо хороша». Систематично проходьте п'ять шарів: задача нечітко визначена, недостатньо контексту, неправильно налаштоване середовище, відсутня верифікація, втрата стану між сесіями. Дев'ять разів із десяти проблема знаходиться в одному з цих шарів.
+- Один файл `AGENTS.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)
+- [HumanLayer: Skill Issue — Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)
+- [SWE-bench Leaderboard](https://www.swebench.com/)
+- [Thoughtworks Technology Radar: Harness Engineering](https://www.thoughtworks.com/radar)
+
+## Вправи
+
+1. **Порівняльний експеримент**: Візьміть кодову базу, яку ви добре знаєте, і нетривіальну задачу на модифікацію. Спочатку запустіть агент без підтримки harness і зафіксуйте збої. Потім додайте `AGENTS.md` та явні верифікаційні команди і запустіть знову з тим самим агентом. Порівняйте два результати, відносячи кожен збій до одного з п'яти захисних шарів.
+
+2. **Вимірювання розриву верифікації**: Виберіть 5 задач на написання коду. Після кожної задачі фіксуйте: чи оголошує агент про завершення, — а потім перевіряйте реальну коректність незалежними тестами. Обчисліть частку випадків, коли агент вважає задачу виконаною, а насправді ні — це і є ваш розрив верифікації. Потім подумайте: які верифікаційні команди зменшили б цю частку?
+
+3. **Практика діагностичного циклу**: Знайдіть задачу, на якій агент регулярно зазнає збоїв у вашому проєкті. Запустіть один раз, зафіксуйте збій. Віднесіть його до одного з п'яти шарів. Виправте цей шар. Запустіть знову. Повторіть три-п'ять раундів, щоразу фіксуючи покращення.
diff --git a/docs/uk/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md b/docs/uk/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md
new file mode 100644
index 0000000..af7250d
--- /dev/null
+++ b/docs/uk/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md
@@ -0,0 +1,21 @@
+# Приклад компонентів harness
+
+Для агента написання коду, що працює в локальному репозиторії:
+
+- Модель:
+ сам LLM
+
+- Harness:
+ - системний промпт
+ - AGENTS.md
+ - bash-інструмент
+ - інструменти читання/запису файлів
+ - доступ до git
+ - локальна файлова система
+ - стартові скрипти
+ - команди для запуску тестів
+ - stop hooks
+ - перевірки лінтером
+ - цикл оцінювача
+
+Якщо змінити будь-яку з наведених частин harness, зміниться й ефективний агент.
diff --git a/docs/uk/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts b/docs/uk/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts
new file mode 100644
index 0000000..d856ba3
--- /dev/null
+++ b/docs/uk/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts
@@ -0,0 +1,180 @@
+/**
+ * harness-vs-no-harness.ts
+ *
+ * Side-by-side comparison of the same task executor running with and without
+ * a harness. The harness version adds explicit rules, verification steps,
+ * and stop conditions.
+ *
+ * Run: npx tsx docs/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts
+ */
+
+// ---------------------------------------------------------------------------
+// Types & helpers
+// ---------------------------------------------------------------------------
+
+interface TaskResult {
+ name: string;
+ passed: boolean;
+ durationMs: number;
+ issues: string[];
+}
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+// ---------------------------------------------------------------------------
+// Simulated task executor
+// ---------------------------------------------------------------------------
+
+/** A simple task that can succeed or fail depending on rules. */
+type Task = {
+ name: string;
+ requiresAuth: boolean;
+ hasTests: boolean;
+ withinScope: boolean;
+};
+
+const tasks: Task[] = [
+ { name: "Add search endpoint", requiresAuth: true, hasTests: false, withinScope: true },
+ { name: "Add delete endpoint", requiresAuth: true, hasTests: true, withinScope: true },
+ { name: "Refactor auth middleware", requiresAuth: true, hasTests: true, withinScope: false },
+ { name: "Add health check", requiresAuth: false, hasTests: true, withinScope: true },
+ { name: "Add rate limiter", requiresAuth: true, hasTests: false, withinScope: true },
+];
+
+// ---------------------------------------------------------------------------
+// Run WITHOUT harness -- just execute every task, no checks
+// ---------------------------------------------------------------------------
+
+function runWithoutHarness(taskList: Task[]): TaskResult[] {
+ const results: TaskResult[] = [];
+
+ for (const t of taskList) {
+ const start = performance.now();
+ const issues: string[] = [];
+
+ // The "agent" does the work and calls it done.
+ let passed = true;
+
+ // Problems that go undetected without a harness
+ if (t.requiresAuth && !t.hasTests) {
+ issues.push("No tests for auth-protected endpoint");
+ // Agent doesn't notice -- marks as pass anyway
+ }
+ if (!t.withinScope) {
+ issues.push("Task is outside current scope");
+ // Agent doesn't notice
+ }
+
+ const duration = performance.now() - start;
+ results.push({ name: t.name, passed, durationMs: duration, issues });
+ }
+
+ return results;
+}
+
+// ---------------------------------------------------------------------------
+// Run WITH harness -- rules, verification, stop conditions
+// ---------------------------------------------------------------------------
+
+function runWithHarness(taskList: Task[]): TaskResult[] {
+ const rules = {
+ requireTestsForAuth: true,
+ enforceScope: true,
+ };
+
+ const results: TaskResult[] = [];
+
+ for (const t of taskList) {
+ const start = performance.now();
+ const issues: string[] = [];
+ let passed = true;
+
+ // Rule: auth endpoints must have tests
+ if (rules.requireTestsForAuth && t.requiresAuth && !t.hasTests) {
+ issues.push("BLOCKED: Auth-protected endpoint missing tests");
+ passed = false;
+ }
+
+ // Rule: stay in scope
+ if (rules.enforceScope && !t.withinScope) {
+ issues.push("BLOCKED: Task outside active scope -- skipped");
+ passed = false;
+ }
+
+ // Verification: re-check after execution
+ if (passed && !t.hasTests) {
+ issues.push("WARNING: No tests exist for this change");
+ }
+
+ const duration = performance.now() - start;
+ results.push({ name: t.name, passed, durationMs: duration, issues });
+ }
+
+ return results;
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function printComparison(
+ noHarness: TaskResult[],
+ withHarness: TaskResult[]
+): void {
+ console.log("\n" + "=".repeat(80));
+ console.log(" HARNESS vs NO-HARNESS COMPARISON");
+ console.log("=".repeat(80));
+
+ const header = `| ${pad("Task", 28)}| ${pad("No-Harness", 12)}| ${pad("Issues(NH)", 35)}| ${pad("Harness", 12)}| ${pad("Issues(H)", 35)}|`;
+ const sep = `|${"-".repeat(30)}|${"-".repeat(14)}|${"-".repeat(37)}|${"-".repeat(14)}|${"-".repeat(37)}|`;
+
+ console.log("\n" + header);
+ console.log(sep);
+
+ for (let i = 0; i < noHarness.length; i++) {
+ const nh = noHarness[i];
+ const wh = withHarness[i];
+ const nhPass = nh.passed ? "PASS" : "FAIL";
+ const whPass = wh.passed ? "PASS" : "FAIL";
+ const nhIssue = nh.issues[0] ?? "(none)";
+ const whIssue = wh.issues[0] ?? "(none)";
+
+ console.log(
+ `| ${pad(nh.name, 28)}| ${pad(nhPass, 12)}| ${pad(nhIssue, 35)}| ${pad(whPass, 12)}| ${pad(whIssue, 35)}|`
+ );
+ }
+
+ // Metrics
+ const nhPassed = noHarness.filter((r) => r.passed).length;
+ const whPassed = withHarness.filter((r) => r.passed).length;
+ const nhIssues = noHarness.reduce((sum, r) => sum + r.issues.length, 0);
+ const whIssues = withHarness.reduce((sum, r) => sum + r.issues.length, 0);
+
+ console.log("\n" + "=".repeat(80));
+ console.log(" SUMMARY METRICS");
+ console.log("=".repeat(80));
+
+ const metricsHeader = `| ${pad("Metric", 30)}| ${pad("No Harness", 15)}| ${pad("With Harness", 15)}|`;
+ const metricsSep = `|${"-".repeat(32)}|${"-".repeat(17)}|${"-".repeat(17)}|`;
+ console.log("\n" + metricsHeader);
+ console.log(metricsSep);
+ console.log(`| ${pad("Tasks passed", 30)}| ${pad(String(nhPassed) + "/" + noHarness.length, 15)}| ${pad(String(whPassed) + "/" + withHarness.length, 15)}|`);
+ console.log(`| ${pad("Issues detected", 30)}| ${pad(String(nhIssues), 15)}| ${pad(String(whIssues), 15)}|`);
+ console.log(`| ${pad("False positives (passed but flawed)", 30)}| ${pad(String(nhPassed - truePassCount(noHarness)), 15)}| ${pad(String(whPassed - truePassCount(withHarness)), 15)}|`);
+
+ console.log("\n The harness catches problems the no-harness run silently ignores.");
+ console.log(" Without a harness, every task 'passes' even when it shouldn't.\n");
+}
+
+/** Count tasks that actually pass (have tests and are in scope). */
+function truePassCount(results: TaskResult[]): number {
+ return results.filter((r) => r.passed && r.issues.length === 0).length;
+}
+
+// ---------------------------------------------------------------------------
+// Run
+// ---------------------------------------------------------------------------
+
+printComparison(runWithoutHarness(tasks), runWithHarness(tasks));
diff --git a/docs/uk/lectures/lecture-02-what-a-harness-actually-is/code/index.md b/docs/uk/lectures/lecture-02-what-a-harness-actually-is/code/index.md
new file mode 100644
index 0000000..a249c68
--- /dev/null
+++ b/docs/uk/lectures/lecture-02-what-a-harness-actually-is/code/index.md
@@ -0,0 +1,8 @@
+# Код до лекції 02
+
+Використовуйте цю теку для невеликих прикладів, що демонструють різницю між:
+
+- поведінкою моделі
+- поведінкою harness
+- налаштуваннями тільки з промптом
+- налаштуваннями агента зі середовищем
diff --git a/docs/uk/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts b/docs/uk/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts
new file mode 100644
index 0000000..e56cddd
--- /dev/null
+++ b/docs/uk/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts
@@ -0,0 +1,36 @@
+type Message = {
+ role: "user" | "assistant";
+ content: string;
+};
+
+type ToolResult = {
+ ok: boolean;
+ output: string;
+};
+
+function runTool(name: string, input: string): ToolResult {
+ if (name === "read_file") {
+ return { ok: true, output: `contents of ${input}` };
+ }
+
+ return { ok: false, output: `unknown tool: ${name}` };
+}
+
+export function minimalHarness(messages: Message[]) {
+ const nextAction = {
+ tool: "read_file",
+ input: "README.md"
+ };
+
+ const result = runTool(nextAction.tool, nextAction.input);
+
+ return {
+ messages: [
+ ...messages,
+ {
+ role: "assistant",
+ content: `Tool ${nextAction.tool} returned: ${result.output}`
+ }
+ ]
+ };
+}
diff --git a/docs/uk/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/uk/lectures/lecture-02-what-a-harness-actually-is/index.md
new file mode 100644
index 0000000..1ab631f
--- /dev/null
+++ b/docs/uk/lectures/lecture-02-what-a-harness-actually-is/index.md
@@ -0,0 +1,109 @@
+[中文版 →](../../../zh/lectures/lecture-02-what-a-harness-actually-is/)
+
+> Приклади коду: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/uk/lectures/lecture-02-what-a-harness-actually-is/code/)
+> Практичний проєкт: [Проєкт 01. Тільки промпт проти підходу «правила перш за все»](./../../projects/project-01-baseline-vs-minimal-harness/index.md)
+
+# Лекція 02. Що таке harness насправді
+
+Слово "harness" часто вживається у спільноті AI-агентів для написання коду, але здебільшого, коли люди кажуть "harness", вони мають на увазі просто файл-промпт. Файл-промпт — це не harness.
+
+У цій лекції ми дамо harness точне, прикладне визначення — не академічну абстракцію, а фреймворк, який можна застосувати вже сьогодні. Harness складається з п'яти підсистем: інструкції, інструменти, середовище, стан і зворотний зв'язок. Кожна підсистема має чіткі обов'язки та критерії оцінки.
+
+## Почнемо з аналогії
+
+Уявіть, що ви — новий інженер, якого кинули в проєкт без жодної документації. Нема README, нема коментарів у коді, ніхто не пояснює, як запускати тести, а конфігурація CI захована десь у глибині. Чи зможете ви писати якісний код? Можливо — якщо ви достатньо розумні й терплячі. Але ви витратите колосальну кількість часу на «розбирання, що це взагалі за проєкт», а не на «вирішення задачі».
+
+AI-агент стикається рівно з тією ж проблемою, і навіть у гіршому становищі. Ви принаймні можете запитати колегу. Агент бачить лише ті файли, що ви поклали перед ним, і команди, які він може виконати.
+
+OpenAI формулює ключовий принцип Harness Engineering так: «репозиторій — це специфікація». Весь необхідний контекст повинен зберігатися в репозиторії: через структуровані файли інструкцій, явні команди верифікації та чітку організацію директорій. У документації Anthropic щодо агентів для тривалих завдань наголошується на збереженні стану, явних шляхах відновлення та структурованому відстеженні прогресу. Обидві компанії акцентують на різних аспектах, але говорять про одне: **все в інженерній інфраструктурі поза вагами моделі визначає, наскільки реально реалізуються можливості моделі.**
+
+Подивіться на кілька знайомих інструментів:
+
+**Claude Code** уособлює підхід harness. Він читає `CLAUDE.md` з вашого репозиторію, може виконувати shell-команди, працює у вашому локальному середовищі, зберігає історію сесії й може запускати тести для перевірки результатів. Але якщо ви не скажете йому, як запускати тести, у нього не буде способу перевірити правильність зроблених змін.
+
+**Cursor** дотримується схожої логіки. Його файл `.cursorrules` є джерелом інструкцій, термінал — інструментом, і він може читати структуру проєкту та конфігурацію лінтера. Однак управління станом у Cursor відносно слабке — закрийте IDE й відкрийте знову, і попередній контекст зникне.
+
+**Codex** (агент OpenAI для написання коду) використовує git worktrees для ізоляції runtime-середовища кожного завдання в поєднанні з локальним стеком спостережуваності (логи, метрики, трейси), завдяки чому кожна зміна верифікується в незалежному середовищі. Він значно краще справляється в репозиторіях з `AGENTS.md` і чіткими командами верифікації, ніж у «порожніх» репозиторіях.
+
+**AutoGPT** — це застережний приклад. Відсутність структурованого управління станом призводить до нескінченного накопичення контексту під час тривалих завдань, а відсутність точних механізмів зворотного зв'язку змушує агента зациклюватись. Багато хто каже, що AutoGPT «не працює», але насправді не працює harness.
+
+## Ключові концепції
+
+- **Що таке harness**: все в інженерній інфраструктурі поза вагами моделі. OpenAI зводить основну роботу інженера до трьох речей: проєктування середовищ, вираження намірів і побудова циклів зворотного зв'язку. Anthropic прямо називає свій Claude Agent SDK «harness загального призначення».
+- **Репозиторій — єдине джерело правди**: все, чого агент не може побачити, для нього практично не існує. OpenAI трактує репозиторій як «систему обліку» — весь необхідний контекст повинен зберігатися там, у вигляді структурованих файлів і чіткої організації директорій.
+- **Дайте карту, а не підручник**: за досвідом OpenAI, `AGENTS.md` має бути сторінкою-довідником, а не енциклопедією. Близько 100 рядків — достатньо. Якщо не вміщається — розбийте на директорію `docs/` і дозвольте агенту читати за потребою.
+- **Обмежуйте, а не мікроменеджьте**: хороший harness використовує виконувані правила для обмеження агента, а не перераховує інструкції по одній. OpenAI каже: «дотримуйтесь інваріантів, не мікроменеджьте реалізацію»; Anthropic виявив, що агенти впевнено хвалять власну роботу, і рішення — розділити «того, хто виконує роботу» і «того, хто перевіряє роботу».
+- **Вилучайте по одному та спостерігайте**: щоб кількісно оцінити граничний внесок кожного компонента harness, вилучайте їх по одному та дивіться, яке вилучення спричиняє найбільше падіння продуктивності. Це показує, які компоненти зараз найцінніші, і водночас виявляє ті, що поки не дають реального внеску. Anthropic використав цей метод і виявив: в міру посилення моделей деякі компоненти перестають бути критичними, але завжди виникають нові критичні компоненти.
+
+## П'ятикомпонентна модель harness
+
+Повернімося до аналогії. Harness має п'ять підсистем:
+
+```mermaid
+flowchart LR
+ Rules["Project rules<br/>AGENTS.md / CLAUDE.md"] --> Agent["AI Agent"]
+ State["Progress and git<br/>PROGRESS.md / commits"] --> Agent
+ Agent --> Tools["Tools<br/>shell / files / tests"]
+ Tools --> Env["Runtime<br/>deps / services / versions"]
+ Env --> Checks["Check results<br/>test / lint / build"]
+ Checks --> Agent
+```
+
+**Підсистема інструкцій**: створіть `AGENTS.md` (або `CLAUDE.md`), що містить огляд і мету проєкту, технологічний стек і версії, команди для першого запуску, жорсткі обмеження, які не підлягають обговоренню, і посилання на детальнішу документацію.
+
+**Підсистема інструментів**: забезпечте агенту достатній доступ до інструментів. Не вимикайте shell «з міркувань безпеки» — якщо агент не може навіть виконати `pip install`, як він взагалі щось зробить? Але й не відкривайте все підряд — дотримуйтесь принципу найменших привілеїв.
+
+**Підсистема середовища**: зробіть стан середовища самоописовим. Використовуйте `pyproject.toml` або `package.json` для фіксації залежностей, `.nvmrc` або `.python-version` — для вказівки версій runtime, Docker або devcontainers — для відтворюваності середовища.
+
+**Підсистема стану**: тривалі завдання мають відстежувати прогрес. Використовуйте простий файл `PROGRESS.md`, де записано: що зроблено, що в процесі, що заблоковано. Оновлюйте перед завершенням кожної сесії; читайте на початку наступної.
+
+**Підсистема зворотного зв'язку**: це підсистема з найвищим ROI. Явно перелічіть команди верифікації в `AGENTS.md`:
+```
+Verification commands:
+- Tests: pytest tests/ -x
+- Type check: mypy src/ --strict
+- Lint: ruff check src/
+- Full verification: make check (includes all above)
+```
+
+Відсутність будь-якої з п'яти підсистем означає неповний harness, і агент завжди буде «незручним» у використанні.
+
+**Кількісна оцінка цінності компонентів harness**: використовуйте «тест контрольованого вилучення змінних». Тримайте модель незмінною, вилучайте п'ять підсистем по одній і дивіться, яке вилучення спричиняє найбільше падіння продуктивності. Компонент із найбільшим падінням має найвищий граничний внесок для поточного завдання і заслуговує на пріоритетну увагу. Чи варто його посилювати — залежить від атрибуції відмов, а не лише від розміру падіння. Компоненти з майже нульовим впливом не слід відкидати одразу: вони можуть бути надлишковими, погано спроєктованими або просто незадіяними в поточному завданні. Цей експеримент відповідає на питання «який компонент зараз найцінніший» — але не може сам по собі довести «де знаходиться вузьке місце». Щоб справді локалізувати вузьке місце, потрібно спочатку проаналізувати записи відмов і їхню атрибуцію: задача була незрозумілою, контексту не вистачало, середовище не відтворювалося, зворотний зв'язок верифікації був відсутній чи управління станом не працювало? Результати абляції компонентів можуть слугувати лише підтверджуючими доказами.
+
+## Реальна історія команди
+
+Команда використовувала GPT-4o для розробки TypeScript + React фронтенд-застосунку (~20 000 рядків коду). Вони пройшли чотири етапи, які по суті були послідовним додаванням компонентів harness:
+
+**Етап 1**: лише базовий опис проєкту в README. 1 з 5 запусків завершувався успіхом (20%). Основні відмови: неправильний менеджер пакетів (npm vs yarn), недотримання конвенцій іменування компонентів, неможливість запустити тести.
+
+**Етап 2**: додали `AGENTS.md` із версіями технологічного стеку, конвенціями іменування та ключовими архітектурними рішеннями. Відсоток успіху зріс до 60%. Відмови, що залишилися, були переважно пов'язані з проблемами середовища та відсутністю верифікації.
+
+**Етап 3**: перелічили команди верифікації в `AGENTS.md`: `yarn test && yarn lint && yarn build`. Відсоток успіху зріс до 80%.
+
+**Етап 4**: запровадили шаблони файлів прогресу, де агент записував виконану та невиконану роботу в кожному запуску. Відсоток успіху стабілізувався на рівні 80–100%.
+
+Чотири ітерації, модель жодного разу не змінювалась, а відсоток успіху зріс з 20% до майже 100%. Ви не перейшли на кращу модель — змінився harness.
+
+## Ключові висновки
+
+- Harness = Інструкції + Інструменти + Середовище + Стан + Зворотний зв'язок. Усі п'ять підсистем обов'язкові.
+- Якщо це не ваги моделі — це harness. Ваш harness визначає, наскільки реально реалізуються можливості моделі.
+- Серед п'яти підсистем підсистема зворотного зв'язку зазвичай потребує найменших вкладень і дає найбільшу віддачу. Насамперед налаштуйте команди верифікації.
+- Використовуйте «тест контрольованого вилучення змінних» для кількісної оцінки граничного внеску кожної підсистеми; для локалізації реального вузького місця спирайтеся на записи відмов і атрибуцію, а не лише на абляцію.
+- Harness застаріває, як і код. Регулярно проводьте аудит і виплачуйте «технічний борг harness» так само, як виплачуєте технічний борг.
+
+## Додаткове читання
+
+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)
+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+- [HumanLayer: Harness Engineering for Coding Agents](https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents)
+- [SWE-agent: Agent-Computer Interfaces](https://github.com/princeton-nlp/SWE-agent)
+- [Thoughtworks: Harness Engineering on Technology Radar](https://www.thoughtworks.com/radar)
+
+## Вправи
+
+1. **Аудит harness за п'ятьма компонентами**: візьміть проєкт, де ви зараз використовуєте AI-агента, і проведіть повний аудит за п'ятикомпонентним фреймворком. Оцініть кожну підсистему від 1 до 5. Знайдіть підсистему з найнижчою оцінкою, витратьте 30 хвилин на її покращення, а потім спостерігайте за зміною продуктивності агента.
+
+2. **Тест контрольованого вилучення змінних**: виберіть одну модель і одне складне завдання. Послідовно вилучайте: інструкції (видаліть AGENTS.md), зворотний зв'язок (не надавайте команди верифікації), стан (ніяких файлів прогресу) — вилучаючи лише по одному за раз і вимірюючи падіння продуктивності. Використайте результати для ранжування граничної цінності кожної підсистеми для поточного завдання. Якщо хочете знайти вузьке місце, під час абляції також записуйте логи відмов і проводьте атрибуцію першопричин.
+
+3. **Аналіз можливостей**: знайдіть у вашому проєкті сценарій, де агент «хоче щось зробити, але не може» (наприклад, знає, що треба використовувати параметризовані запити, але не знає патернів вашого ORM). Проаналізуйте, чи це «прогалина виконання» (не знає, як діяти) чи «прогалина оцінки» (не знає, чи зробив правильно), а потім спроєктуйте покращення harness для усунення цієї прогалини.
diff --git a/docs/uk/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md b/docs/uk/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md
new file mode 100644
index 0000000..482fba0
--- /dev/null
+++ b/docs/uk/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md
@@ -0,0 +1,7 @@
+# Код до лекції 03
+
+Використовуйте цю теку для прикладів:
+
+- структур репозиторіїв, зручних для читання агентом
+- документів як системи обліку
+- поганого та хорошого розміщення знань
diff --git a/docs/uk/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt b/docs/uk/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt
new file mode 100644
index 0000000..45315da
--- /dev/null
+++ b/docs/uk/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt
@@ -0,0 +1,13 @@
+AGENTS.md
+docs/
+ ARCHITECTURE.md
+ PRODUCT.md
+ RELIABILITY.md
+ references/
+ electron.md
+ sqlite.md
+ plans/
+ active/
+ completed/
+src/
+scripts/
diff --git a/docs/uk/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts b/docs/uk/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts
new file mode 100644
index 0000000..46f6a62
--- /dev/null
+++ b/docs/uk/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts
@@ -0,0 +1,189 @@
+/**
+ * repo-reader.ts
+ *
+ * Reads a directory structure and scores it on discoverability.
+ * Checks for: AGENTS.md, docs/, architecture docs, feature tracking,
+ * handoff files, and other signals of a repository that serves as the
+ * system of record.
+ *
+ * Usage:
+ * npx tsx docs/lectures/lecture-03.../code/repo-reader.ts [path]
+ * (defaults to current working directory if no path given)
+ *
+ * Run: npx tsx docs/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+// ---------------------------------------------------------------------------
+// Scoring criteria
+// ---------------------------------------------------------------------------
+
+interface Check {
+ name: string;
+ description: string;
+ maxPoints: number;
+ check: (dir: string) => { points: number; found: string[]; missing: string[] };
+}
+
+const checks: Check[] = [
+ {
+ name: "AGENTS.md / CLAUDE.md",
+ description: "Agent-readable instruction file at repo root",
+ maxPoints: 15,
+ check: (dir) => {
+ const candidates = ["AGENTS.md", "CLAUDE.md", ".claude/CLAUDE.md"];
+ const found = candidates.filter((f) => fs.existsSync(path.join(dir, f)));
+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : candidates };
+ },
+ },
+ {
+ name: "Documentation directory",
+ description: "Dedicated docs/ or documentation/ directory",
+ maxPoints: 10,
+ check: (dir) => {
+ const candidates = ["docs", "documentation", "doc"];
+ const found = candidates.filter((f) => {
+ const p = path.join(dir, f);
+ return fs.existsSync(p) && fs.statSync(p).isDirectory();
+ });
+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["docs/"] };
+ },
+ },
+ {
+ name: "Architecture documentation",
+ description: "Files describing system architecture",
+ maxPoints: 15,
+ check: (dir) => {
+ const patterns = [
+ "architecture.md", "ARCHITECTURE.md", "docs/architecture.md",
+ "docs/architecture/", "design.md", "DESIGN.md",
+ ];
+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));
+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["architecture.md or docs/architecture/"] };
+ },
+ },
+ {
+ name: "Feature tracking",
+ description: "Feature list or task tracking file",
+ maxPoints: 15,
+ check: (dir) => {
+ const patterns = [
+ "feature_list.json", "features.md", "FEATURES.md",
+ "docs/features.md", "tasks.json", "TODO.md",
+ ];
+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));
+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["feature_list.json or features.md"] };
+ },
+ },
+ {
+ name: "Handoff / session continuity",
+ description: "Files for multi-session continuity",
+ maxPoints: 15,
+ check: (dir) => {
+ const patterns = [
+ "HANDOFF.md", "handoff.md", "SESSION_NOTES.md",
+ "docs/handoff.md", ".handoff", "PROGRESS.md",
+ ];
+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));
+ return { points: found.length > 0 ? 15 : 0, found, missing: found.length > 0 ? [] : ["HANDOFF.md or PROGRESS.md"] };
+ },
+ },
+ {
+ name: "Testing structure",
+ description: "Test directory or test configuration",
+ maxPoints: 10,
+ check: (dir) => {
+ const patterns = ["test", "tests", "__tests__", "spec"];
+ const found = patterns.filter((f) => {
+ const p = path.join(dir, f);
+ return fs.existsSync(p) && fs.statSync(p).isDirectory();
+ });
+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["test/ or tests/"] };
+ },
+ },
+ {
+ name: "Configuration files",
+ description: "Project config (package.json, tsconfig, etc.)",
+ maxPoints: 10,
+ check: (dir) => {
+ const patterns = ["package.json", "tsconfig.json", "pyproject.toml", "Cargo.toml", "go.mod"];
+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));
+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["package.json or equivalent"] };
+ },
+ },
+ {
+ name: "README",
+ description: "Root README file",
+ maxPoints: 10,
+ check: (dir) => {
+ const patterns = ["README.md", "README.rst", "README.txt", "README"];
+ const found = patterns.filter((f) => fs.existsSync(path.join(dir, f)));
+ return { points: found.length > 0 ? 10 : 0, found, missing: found.length > 0 ? [] : ["README.md"] };
+ },
+ },
+];
+
+// ---------------------------------------------------------------------------
+// Report generation
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function scoreRepo(targetDir: string): void {
+ const resolved = path.resolve(targetDir);
+
+ if (!fs.existsSync(resolved)) {
+ console.error(` Error: Directory not found: ${resolved}`);
+ process.exit(1);
+ }
+
+ console.log("\n" + "=".repeat(80));
+ console.log(" REPOSITORY DISCOVERABILITY SCORE");
+ console.log("=".repeat(80));
+ console.log(` Target: ${resolved}\n`);
+
+ const header = `| ${pad("Criterion", 30)}| ${pad("Points", 8)}| ${pad("Status", 10)}| Details`;
+ const sep = `|${"-".repeat(32)}|${"-".repeat(10)}|${"-".repeat(12)}|${"-".repeat(30)}`;
+ console.log(header);
+ console.log(sep);
+
+ let totalScore = 0;
+ let maxScore = 0;
+
+ for (const check of checks) {
+ const result = check.check(resolved);
+ totalScore += result.points;
+ maxScore += check.maxPoints;
+ const status = result.points > 0 ? "PASS" : "FAIL";
+ const detail = result.found.length > 0 ? result.found.join(", ") : result.missing[0];
+
+ console.log(`| ${pad(check.name, 30)}| ${pad(result.points + "/" + check.maxPoints, 8)}| ${pad(status, 10)}| ${detail}`);
+ }
+
+ // Final score
+ console.log("\n" + "-".repeat(80));
+ console.log(` TOTAL SCORE: ${totalScore} / ${maxScore} (${Math.round((totalScore / maxScore) * 100)}%)`);
+
+ // Grade
+ const pct = totalScore / maxScore;
+ let grade: string;
+ if (pct >= 0.9) grade = "A -- Repository is a strong system of record";
+ else if (pct >= 0.7) grade = "B -- Good foundation, minor gaps";
+ else if (pct >= 0.5) grade = "C -- Partial structure, significant gaps";
+ else if (pct >= 0.3) grade = "D -- Minimal structure, hard for agents to navigate";
+ else grade = "F -- Repository lacks discoverability signals";
+
+ console.log(` GRADE: ${grade}`);
+ console.log("=".repeat(80) + "\n");
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const target = process.argv[2] || process.cwd();
+scoreRepo(target);
diff --git a/docs/uk/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md b/docs/uk/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md
new file mode 100644
index 0000000..096ee5b
--- /dev/null
+++ b/docs/uk/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md
@@ -0,0 +1,11 @@
+# Контрольний список системи обліку
+
+Чи може новий агент дізнатися наступне лише з репозиторію?
+
+- Який продукт створюється?
+- Що застосунок повинен робити для користувачів?
+- Як організовано кодову базу?
+- Як запускається застосунок?
+- Як перевіряється його справність?
+- Яка робота зараз у процесі виконання?
+- Які стандарти якості важливі?
diff --git a/docs/uk/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/uk/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
new file mode 100644
index 0000000..10b6789
--- /dev/null
+++ b/docs/uk/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
@@ -0,0 +1,137 @@
+[中文版 →](../../../zh/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/)
+
+> Приклади коду: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/uk/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/)
+> Практичний проєкт: [Проєкт 02. Зробити так, щоб агент читав проєкт і продовжував з того місця, де зупинився](./../../projects/project-02-agent-readable-workspace/index.md)
+
+# Лекція 03. Чому репозиторій має стати єдиним джерелом правди
+
+Архітектурні рішення вашої команди розкидані між Confluence, Slack, Jira і кількома головами старших інженерів. Для людей це якось працює — можна запитати колегу, знайти щось у логах чату, покопатися в документації, а якщо нічого не допомогло — зловити когось у перерві. Але для AI-агента інформація, якої немає в репозиторії, просто не існує.
+
+Це не перебільшення. Агент має лише три джерела вхідних даних: системні промпти і описи завдань, вміст файлів з репозиторію та результати виконання інструментів. Ваша історія Slack, тікети Jira, сторінки Confluence і архітектурне рішення, яке ви обговорили з колегою в п'ятницю після обіду, — агент нічого з цього не бачить. Він не може «піти запитати когось» чи «знайти в логах чату». Весь його робочий світ — це сам репозиторій. Про все, що за його межами, він не знає нічого.
+
+Тож справжнє питання звучить так: ви збираєтесь дати йому достатньо хорошу карту?
+
+## Що має бути на карті
+
+OpenAI прямо формулює це у своїй статті про Harness Engineering: **інформація, якої немає в репозиторії, для агента не існує.** Вони називають це принципом «репозиторій як специфікація» — репозиторій є документом-специфікацією найвищого авторитету.
+
+Документація Anthropic щодо агентів для тривалих завдань перегукується з цим: збереження стану — необхідна умова безперервності довгих завдань, а можливість відновлення знань між сесіями безпосередньо визначає відсоток успішного виконання завдань. І цей стан повинен знаходитись у репозиторії — адже це єдине стабільне, надійно доступне сховище, яке має агент.
+
+Ви можете подумати: «Наша команда невелика, знання живуть у головах у всіх, і це нормально працює». Цілком вірно — для людей. Але якщо ви хочете використовувати агента, доведеться прийняти один факт: агент не може запитати людей. Все, що йому потрібно знати, має бути записано і покладено туди, де він це знайде.
+
+Це не проблема «писати більше документації» — це проблема «покласти інформацію про рішення в правильне місце». `ARCHITECTURE.md` на 50 рядків у директорії `src/api/` набагато кориснішій, ніж 500-сторінковий проєктний документ у Confluence, який ніхто не підтримує. Близькість важливіша за обсяг, адже інформація по-справжньому корисна лише тоді, коли вона під рукою саме в той момент, коли потрібна.
+
+## Видимість знань
+
+```mermaid
+flowchart LR
+ Slack["Rules in Slack"] --> Write["Write into repo files<br/>AGENTS.md / ARCHITECTURE.md / PROGRESS.md"]
+ Confluence["Rules in Confluence"] --> Write
+ Heads["Rules in engineers' heads"] --> Write
+ Jira["Rules in Jira"] --> Write
+ Write --> Repo["Repository files"]
+ Repo --> Agent["New agent session<br/>reads the repo directly"]
+ Warning["If a rule isn't in the repo,<br/>the agent can't see it"] --> Agent
+```
+
+Як перевірити, чи достатньо хороша ваша карта? Проведіть «тест нової сесії»: відкрийте абсолютно нову сесію агента, надайте йому лише вміст репозиторію і подивіться, чи зможе він відповісти на п'ять базових питань.
+
+```mermaid
+flowchart TB
+ Q1["What is this system?"] --> A1["AGENTS.md / README"]
+ Q2["How is it organized?"] --> A2["ARCHITECTURE.md / module docs"]
+ Q3["How do I run it?"] --> A3["Makefile / init.sh / package scripts"]
+ Q4["How do I verify it?"] --> A4["Test, lint, check commands"]
+ Q5["Where are we now?"] --> A5["PROGRESS.md / feature list / git history"]
+
+ A1 --> Ready["A new session can start work<br/>without asking a human"]
+ A2 --> Ready
+ A3 --> Ready
+ A4 --> Ready
+ A5 --> Ready
+```
+
+Якщо не може — на карті є білі плями. Де карта порожня, агент змушений вгадувати — неправильні здогадки стають помилками, надмірне вгадування витрачає контекст. І кожна нова сесія мусить вгадувати знову й знову. Ціна вгадування завжди набагато вища, ніж ціна правильного складання карти від початку.
+
+## Ключові концепції
+
+- **Прогалина видимості знань**: частка загальних знань про проєкт, яка НЕ знаходиться в репозиторії. Чим більша прогалина, тим вищий відсоток відмов агента. Оцінити її можна так: порахуйте всі неявні знання про проєкт, що живуть у головах людей, а потім подивіться, яка їх частина справді потрапила до репозиторію. Різниця і є вашою прогалиною видимості.
+- **Система обліку**: репозиторій коду як авторитетне джерело для рішень проєкту, архітектурних обмежень, стану виконання та стандартів верифікації. Репозиторій має останнє слово — більше нічого не рахується. Якщо інформація «ця дорога закрита» живе лише в голові в Іваненка, то кожного разу доведеться питати Іваненка. Запишіть у репозиторій — і питати більше нікому не доведеться.
+- **Тест нової сесії**: п'ять питань із попереднього розділу. Скільки з них агент може відповісти — настільки повна ваша карта.
+- **Вартість виявлення**: скільки бюджету контексту агент витрачає на пошук одного ключового фрагмента інформації в репозиторії. Чим прихованіша інформація, тим вища вартість виявлення і тим менше бюджету залишається на саме завдання. Критичну інформацію слід розміщувати там, де агент побачить її першою — а не ховати на десять рівнів директорій углиб.
+- **Швидкість застарівання знань**: частка записів знань у репозиторії, що втрачають актуальність за одиницю часу. Документація, що розходиться з кодом, — найбільший ворог: застаріла документація гірша, ніж жодна документація взагалі.
+- **Аналогія ACID**: застосування принципів транзакцій бази даних (атомарність, узгодженість, ізольованість, стійкість) до управління станом агента. Розкриємо це нижче.
+
+## Як намалювати хорошу карту
+
+**Принцип 1: Знання живуть поряд з кодом.** Правило про автентифікацію API-ендпоінтів належить поруч з кодом API, а не захованим у величезному глобальному документі. Розмістіть короткий документ у кожній директорії модуля, що пояснює відповідальність, інтерфейси та особливі обмеження цього модуля. Сама директорія модуля є природним індексом — коли агент дістається до коду, він одразу дістається й до обмежень, без жодного пошуку.
+
+**Принцип 2: Використовуйте стандартизований вхідний файл.** `AGENTS.md` (або `CLAUDE.md`) — це «посадкова сторінка» агента. Він не зобов'язаний містити всю інформацію, але повинен дозволяти агенту швидко відповісти на три питання: «Що це за проєкт», «Як його запустити» і «Як його верифікувати». 50–100 рядків — достатньо.
+
+**Принцип 3: Мінімально, але повно.** Кожен фрагмент знань повинен мати чіткий сценарій використання. Якщо вилучення правила не впливає на якість рішень агента, цього правила не повинно існувати. Але на кожне питання з тесту нової сесії має бути відповідь. Це постійний баланс, який треба підтримувати — не занадто багато, не занадто мало, рівно стільки, скільки потрібно.
+
+**Принцип 4: Оновлюйте разом з кодом.** Прив'яжіть оновлення знань до змін коду. Найпростіший підхід: розміщуйте документацію по архітектурі у відповідній директорії модуля. Коли ви змінюєте код, ви природно помічаєте документ. Після змін коду CI може нагадати вам перевірити, чи потрібно оновлювати документи.
+
+**Конкретна структура репозиторію**:
+
+```
+project/
+├── AGENTS.md # Entry: project overview, run commands, hard constraints
+├── src/
+│ ├── api/
+│ │ ├── ARCHITECTURE.md # API layer architecture decisions
+│ │ └── ...
+│ ├── db/
+│ │ ├── CONSTRAINTS.md # Database operation hard constraints
+│ │ └── ...
+│ └── ...
+├── PROGRESS.md # Current progress: done, in-progress, blocked
+└── Makefile # Standardized commands: setup, test, lint, check
+```
+
+## Управління станом агента за принципами ACID
+
+Ця аналогія походить з управління транзакціями баз даних. Може здатися, що це надмірне ускладнення, але насправді вона дає дуже практичний фреймворк:
+
+- **Атомарність**: кожна «логічна операція» (наприклад, «додати новий ендпоінт і оновити тести») отримує один git-коміт. Якщо щось пішло не так посередині — `git stash` для відкату. Або все, або нічого — ніяких «наполовину зроблено».
+- **Узгодженість**: визначте предикати верифікації «узгодженого стану» — всі тести проходять, лінтер не повідомляє про помилки. Агент запускає верифікацію після кожної операції; неузгоджені проміжні стани не повинні комітитися. Після операції система має перебувати у верифіковано правильному стані.
+- **Ізольованість**: коли кілька агентів працюють паралельно, проєктуйте файли стану так, щоб уникнути конфліктів. Простий підхід: кожен агент використовує власний файл прогресу, або використовуйте git-гілки для ізоляції. Паралельний запис у один і той самий файл — типове джерело проблем.
+- **Стійкість**: критичні знання проєкту зберігаються у відстежуваних git-файлах. Тимчасовий стан може залишатися в пам'яті сесії, але знання, що мають переживати між сесіями, необхідно записувати у файли. Те, що у вас в голові, не рахується — рахується лише те, що записано.
+
+## Реальна історія перетворення
+
+Команда підтримувала платформу електронної комерції приблизно з 30 мікросервісами. Архітектурні рішення — протоколи міжсервісної комунікації, стратегії узгодженості даних, правила версіонування API — були розкидані по: Confluence (частково застарілий), Slack (важко шукати), кільком головам старших інженерів (не масштабується) та уривчастим коментарям у коді (несистемно).
+
+Після впровадження AI-агентів 70% завдань вимагали втручання людини. Майже кожна відмова була пов'язана з тим, що агент порушував якесь неявне обмеження — те, що «всі знають, але ніхто ніколи не записав». Агент не міг знати, чого він не знає — він міг лише діяти за власним розумінням і потрапляти в пастку.
+
+Команда провела перетворення:
+1. Створили `AGENTS.md` у корені репозиторію з оглядом проєкту, версіями технологічного стеку та глобальними жорсткими обмеженнями
+2. Додали `ARCHITECTURE.md` у директорію кожного мікросервісу, що описує відповідальність, інтерфейси та залежності цього сервісу
+3. Створили централізований `CONSTRAINTS.md`, використовуючи явні формулювання «MUST / MUST NOT» для жорстких обмежень
+4. Додали `PROGRESS.md` у директорію кожного сервісу для відстеження поточного робочого статусу
+
+Після перетворення: той самий агент у новій сесії міг відповісти на всі ключові питання проєкту, а якість виконання завдань суттєво покращилася.
+
+## Ключові висновки
+
+- Знання, яких немає в репозиторії, для агента не існує. Перенесення критичної інформації про рішення до репозиторію — найфундаментальніша інвестиція в harness: намалюйте хорошу карту, щоб не заблукати.
+- Використовуйте «тест нової сесії» для оцінки якості репозиторію: чи може абсолютно нова сесія відповісти на п'ять базових питань, використовуючи лише вміст репозиторію?
+- Знання повинні бути поряд з кодом, мінімальними але повними, і оновлюватися разом з кодом. Справа не в написанні більше документів — а в розміщенні інформації в правильному місці.
+- Застосовуйте принципи ACID до стану агента: атомарні коміти, верифікація узгодженості, ізоляція паралелізму та стійкість критичних знань.
+- Застарівання знань — найбільший ворог. Застаріла документація небезпечніша, ніж жодна документація — вона веде агента в хибному напрямку, поки агент думає, що на правильному шляху.
+
+## Додаткове читання
+
+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)
+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+- [Infrastructure as Code — Martin Fowler](https://martinfowler.com/bliki/InfrastructureAsCode.html)
+- [ADR: Architecture Decision Records](https://adr.github.io/)
+- [The Twelve-Factor App](https://12factor.net/)
+
+## Вправи
+
+1. **Тест нової сесії**: відкрийте абсолютно нову сесію агента у вашому проєкті (не надавайте жодного усного контексту), дозвольте бачити лише вміст репозиторію, а потім поставте п'ять питань: Що це за система? Як вона організована? Як її запустити? Як її верифікувати? Який поточний прогрес? Запишіть, на що не може відповісти, а потім покращуйте репозиторій, поки він не відповість на всі питання.
+
+2. **Кількісна оцінка екстерналізації знань**: перелічіть всі рішення та обмеження, важливі для розробки вашого проєкту. Позначте кожен пункт як «в репозиторії» або «поза репозиторієм». Порахуйте прогалину видимості знань (частку пунктів поза репозиторієм). Складіть план для зменшення прогалини нижче 10%.
+
+3. **Оцінка за ACID**: оцініть управління станом вашого проєкту за допомогою аналогії ACID з цієї лекції. Атомарність — чи можна чисто відкотити операції агента? Узгодженість — чи є у репозиторії верифікація «узгодженого стану»? Ізольованість — чи заважають одне одному кілька паралельних агентів? Стійкість — чи правильно збережені всі міжсесійні знання?
diff --git a/docs/uk/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md b/docs/uk/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md
new file mode 100644
index 0000000..538487d
--- /dev/null
+++ b/docs/uk/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md
@@ -0,0 +1,15 @@
+# AGENTS.md
+
+## Починайте звідси
+
+- Прочитайте `docs/ARCHITECTURE.md`
+- Прочитайте `docs/PRODUCT.md`
+- Використовуйте `npm run dev` для запуску застосунку
+- Використовуйте `npm run check` перед тим, як позначити роботу завершеною
+
+## Жорсткі правила
+
+- Не змінюйте межі між Electron main/preload/renderer без попереднього читання
+ `docs/ARCHITECTURE.md`
+- Не позначайте функцію завершеною без верифікації
+- Залишайте чистий стан для наступної сесії
diff --git a/docs/uk/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md b/docs/uk/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md
new file mode 100644
index 0000000..ee5ce8c
--- /dev/null
+++ b/docs/uk/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md
@@ -0,0 +1,7 @@
+# Антипатерни файлів інструкцій
+
+- Розміщення всіх знань про репозиторій в одному файлі
+- Повторення одного й того самого правила в кількох місцях
+- Збереження застарілих правил, які ніхто не перевіряє
+- Написання умовних інструкцій, настільки специфічних, що вони рідко застосовуються
+- Вбудовування об'ємних посібників з інструментів у стартовий контекст
diff --git a/docs/uk/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md b/docs/uk/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md
new file mode 100644
index 0000000..c657517
--- /dev/null
+++ b/docs/uk/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md
@@ -0,0 +1,7 @@
+# Код до лекції 04
+
+Використовуйте цю теку для прикладів:
+
+- монолітних файлів інструкцій
+- коротких вхідних файлів
+- патернів прогресивного розкриття
diff --git a/docs/uk/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts b/docs/uk/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts
new file mode 100644
index 0000000..59a9632
--- /dev/null
+++ b/docs/uk/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts
@@ -0,0 +1,209 @@
+/**
+ * split-vs-monolithic.ts
+ *
+ * Creates a monolithic instruction file (~200 lines) and then shows how
+ * splitting into 4 focused files dramatically reduces the context needed
+ * for any single query. Simulates an "agent" searching for a specific rule
+ * and measures how many lines it must read in each approach.
+ *
+ * Run: npx tsx docs/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts
+ */
+
+// ---------------------------------------------------------------------------
+// Simulated monolithic instruction file (200 lines of rules)
+// ---------------------------------------------------------------------------
+
+const monolithicInstructions: { lineNumber: number; section: string; content: string }[] = [];
+
+// Section 1: Project Overview (lines 1-50)
+for (let i = 1; i <= 50; i++) {
+ monolithicInstructions.push({
+ lineNumber: i,
+ section: "Project Overview",
+ content: i === 25 ? "This project uses React 18 with TypeScript strict mode." : `Overview detail line ${i}`,
+ });
+}
+
+// Section 2: Code Style Rules (lines 51-100)
+for (let i = 51; i <= 100; i++) {
+ monolithicInstructions.push({
+ lineNumber: i,
+ section: "Code Style",
+ content:
+ i === 72
+ ? "RULE: Always use explicit return types on exported functions."
+ : i === 78
+ ? "RULE: Use const assertions for immutable arrays."
+ : `Style rule detail line ${i}`,
+ });
+}
+
+// Section 3: Testing Standards (lines 101-150)
+for (let i = 101; i <= 150; i++) {
+ monolithicInstructions.push({
+ lineNumber: i,
+ section: "Testing",
+ content:
+ i === 120
+ ? "RULE: Every new endpoint must have integration tests."
+ : i === 135
+ ? "RULE: Test files must mirror the source file structure."
+ : `Testing detail line ${i}`,
+ });
+}
+
+// Section 4: Deployment Rules (lines 151-200)
+for (let i = 151; i <= 200; i++) {
+ monolithicInstructions.push({
+ lineNumber: i,
+ section: "Deployment",
+ content:
+ i === 175
+ ? "RULE: Never deploy on Fridays. Deploy window is Tue-Thu 10am-3pm."
+ : `Deployment detail line ${i}`,
+ });
+}
+
+// ---------------------------------------------------------------------------
+// Split instruction files (4 focused files)
+// ---------------------------------------------------------------------------
+
+const splitInstructions: Record<string, { lineNumber: number; section: string; content: string }[]> = {
+ "01-project-overview.md": monolithicInstructions.filter((l) => l.section === "Project Overview"),
+ "02-code-style.md": monolithicInstructions.filter((l) => l.section === "Code Style"),
+ "03-testing.md": monolithicInstructions.filter((l) => l.section === "Testing"),
+ "04-deployment.md": monolithicInstructions.filter((l) => l.section === "Deployment"),
+};
+
+// ---------------------------------------------------------------------------
+// Simulated queries -- the agent needs to find specific rules
+// ---------------------------------------------------------------------------
+
+interface Query {
+ description: string;
+ targetRule: string;
+ relevantSection: string;
+}
+
+const queries: Query[] = [
+ {
+ description: "Find the rule about return types",
+ targetRule: "explicit return types",
+ relevantSection: "Code Style",
+ },
+ {
+ description: "Find the deployment window rule",
+ targetRule: "deploy on Fridays",
+ relevantSection: "Deployment",
+ },
+ {
+ description: "Find the integration test rule",
+ targetRule: "integration tests",
+ relevantSection: "Testing",
+ },
+ {
+ description: "Find the test file structure rule",
+ targetRule: "mirror the source file",
+ relevantSection: "Testing",
+ },
+];
+
+// ---------------------------------------------------------------------------
+// Search simulation
+// ---------------------------------------------------------------------------
+
+function searchMonolithic(query: Query): { linesRead: number; found: boolean } {
+ // Agent must scan from the top, reading each line until it finds the rule.
+ // In the worst case it reads all lines.
+ let linesRead = 0;
+ let found = false;
+
+ for (const line of monolithicInstructions) {
+ linesRead++;
+ if (line.content.toLowerCase().includes(query.targetRule.toLowerCase())) {
+ found = true;
+ break;
+ }
+ }
+
+ return { linesRead, found };
+}
+
+function searchSplit(query: Query): { linesRead: number; found: boolean; fileAccessed: string } {
+ // Agent knows which file to look in based on the section.
+ // It only reads lines from that one file.
+ const fileMap: Record<string, string> = {
+ "Project Overview": "01-project-overview.md",
+ "Code Style": "02-code-style.md",
+ Testing: "03-testing.md",
+ Deployment: "04-deployment.md",
+ };
+
+ const targetFile = fileMap[query.relevantSection];
+ const lines = splitInstructions[targetFile];
+ let linesRead = 0;
+ let found = false;
+
+ for (const line of lines) {
+ linesRead++;
+ if (line.content.toLowerCase().includes(query.targetRule.toLowerCase())) {
+ found = true;
+ break;
+ }
+ }
+
+ return { linesRead, found, fileAccessed: targetFile };
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function run(): void {
+ console.log("\n" + "=".repeat(90));
+ console.log(" MONOLITHIC vs SPLIT INSTRUCTION FILES");
+ console.log("=".repeat(90));
+
+ console.log("\n Monolithic file: 1 file, " + monolithicInstructions.length + " lines total");
+ console.log(" Split files: 4 files, ~" + Math.round(monolithicInstructions.length / 4) + " lines each\n");
+
+ const header = `| ${pad("Query", 42)}| ${pad("Monolithic (lines)", 20)}| ${pad("Split (lines)", 15)}| ${pad("File Accessed", 22)}| Savings`;
+ const sep = `|${"-".repeat(44)}|${"-".repeat(22)}|${"-".repeat(17)}|${"-".repeat(24)}|${"-".repeat(10)}`;
+ console.log(header);
+ console.log(sep);
+
+ let totalMono = 0;
+ let totalSplit = 0;
+
+ for (const q of queries) {
+ const mono = searchMonolithic(q);
+ const split = searchSplit(q);
+ totalMono += mono.linesRead;
+ totalSplit += split.linesRead;
+
+ const savings = Math.round(((mono.linesRead - split.linesRead) / mono.linesRead) * 100);
+ console.log(
+ `| ${pad(q.description, 42)}| ${pad(String(mono.linesRead), 20)}| ${pad(String(split.linesRead), 15)}| ${pad(split.fileAccessed, 22)}| ${savings}%`
+ );
+ }
+
+ console.log(sep);
+ const avgMono = Math.round(totalMono / queries.length);
+ const avgSplit = Math.round(totalSplit / queries.length);
+ console.log(
+ `| ${pad("AVERAGE", 42)}| ${pad(String(avgMono), 20)}| ${pad(String(avgSplit), 15)}| ${pad("(targeted file)", 22)}| ${Math.round(((avgMono - avgSplit) / avgMono) * 100)}%`
+ );
+
+ console.log("\n" + "=".repeat(90));
+ console.log(" KEY INSIGHT");
+ console.log("=".repeat(90));
+ console.log(" With a monolithic file, the agent must scan up to " + monolithicInstructions.length + " lines for every query.");
+ console.log(" With split files, it reads only the relevant " + Math.round(monolithicInstructions.length / 4) + "-line file.");
+ console.log(" This means less context window usage, fewer hallucinations, and faster execution.\n");
+}
+
+run();
diff --git a/docs/uk/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/uk/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
new file mode 100644
index 0000000..6efa87a
--- /dev/null
+++ b/docs/uk/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
@@ -0,0 +1,132 @@
+[中文版 →](../../../zh/lectures/lecture-04-why-one-giant-instruction-file-fails/)
+
+> Приклади коду: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/uk/lectures/lecture-04-why-one-giant-instruction-file-fails/code/)
+> Практичний проєкт: [Проєкт 02. Робочий простір, зручний для агента](./../../projects/project-02-agent-readable-workspace/index.md)
+
+# Лекція 04. Розподіліть інструкції між файлами
+
+Ви почали серйозно займатися harness engineering — чудово. Ви створили `AGENTS.md` і вклали туди кожне правило, обмеження та засвоєний урок, про який тільки могли подумати. Через місяць файл розрісся до 300 рядків, через два — до 450, через три — до 600. І тут ви помічаєте, що продуктивність агента насправді погіршується: під час простого виправлення помилки агент витрачає величезну кількість контексту на обробку інструкцій щодо розгортання, які не мають жодного відношення до задачі; критичне обмеження безпеки, заховане на рядку 300, ігнорується взагалі; три суперечливі правила стилю коду змушують агента щоразу вибирати одне навмання.
+
+Це пастка «гігантського файлу інструкцій». Все здається корисним, тому ви все туди запихаєте, а знайти конкретне правило означає перегортати весь файл. Ви написали 600 рядків, але лише третина з них стосується поточної задачі.
+
+## Порочне коло в основі проблеми
+
+Найпоширеніше порочне коло виглядає так: агент робить помилку, ви кажете «додай правило, щоб це не повторювалось», додаєте його до AGENTS.md, і це спрацьовує — тимчасово. Потім агент робить іншу помилку, і ви додаєте ще одне правило. Повторюйте, поки файл не вийде з-під контролю.
+
+Це цілком природна реакція. «Додати правило» щоразу, коли щось іде не так, здається розумним. Але кумулятивний ефект катастрофічний. Розгляньмо детально, що саме йде не так.
+
+**Контекстний бюджет з'їдається живцем.** Контекстне вікно агента обмежене. Припустимо, ваш агент має вікно на 200K токенів (стандарт Claude). Роздутий файл інструкцій може споживати 10–20K токенів. Здається, запасу ще достатньо? Але складна задача може потребувати читання десятків вихідних файлів, результати виконання інструментів також займають контекст, а історія розмови постійно накопичується. До того часу, коли агент справді мусить розуміти код, бюджет вже вичерпано.
+
+**Загублений у середині.** Стаття «Lost in the Middle» (Liu et al., 2023) чітко продемонструвала, що LLM значно гірше використовують інформацію в середині довгих текстів, ніж на початку або в кінці. Ваш AGENTS.md налічує 600 рядків, і на рядку 300 написано «всі запити до бази даних мають використовувати параметризовані запити» — це жорстке обмеження безпеки. Але воно заховане в середині, і агент майже напевно його проігнорує.
+
+**Конфлікти пріоритетів.** Файл змішує безперечні жорсткі обмеження («ніколи не використовуй eval()»), важливі проєктні настанови («перевагу надавай функціональному стилю») та конкретний histórico урок («минулого тижня виправили витік пам'яті у WebSocket, стеж за подібними патернами»). Ці три правила мають абсолютно різний рівень важливості, але у файлі вони виглядають однаково. Агент не має надійного сигналу, щоб відрізнити червону лінію від простої рекомендації.
+
+**Деградація підтримки.** Великі файли за своєю природою важко підтримувати. Застарілі інструкції рідко видаляють, бо наслідки видалення невизначені («може, щось інше залежить від цього правила?»), але додавати нові інструкції здається безкоштовним. Результат: файл лише росте, ніколи не зменшується, і відношення сигналу до шуму неухильно падає. Це та сама проблема, що й накопичення технічного боргу в програмному забезпеченні.
+
+**Накопичення суперечностей.** Інструкції, додані в різний час, починають суперечити одна одній — одна каже «використовуй TypeScript strict mode», інша — «деякі legacy-файли можуть використовувати `any`». Агент щоразу вибирає щось одне навмання.
+
+## Ключові концепції
+
+- **Роздуття інструкцій (Instruction Bloat)**: коли файл інструкцій займає 10–15% контекстного вікна, він починає витісняти бюджет для читання коду та міркування над задачею. `AGENTS.md` на 600 рядків може споживати 10 000–20 000 токенів — це 8–15% вікна на 128K.
+- **Загублений у середині (Lost in the Middle)**: інформація в середині довгих текстів легко залишається непоміченою. Дослідження Liu et al. 2023 року показало, що LLM значно гірше використовують інформацію в середині довгих текстів, ніж на початку або в кінці. Критичне обмеження, заховане на рядку 300 з 600, має дуже високу ймовірність бути проігнорованим.
+- **Відношення сигналу до шуму в інструкціях (SNR)**: частка інструкцій у файлі, що стосуються поточної задачі. Бути змушеним читати 50 рядків інструкцій щодо розгортання під час виправлення помилки — це низький SNR.
+- **Вхідний файл (Entry File)**: короткий файл, призначення якого — направляти агента до детальнішої документації, а не містити все самому. 50–200 рядків достатньо.
+- **Розкриття на вимогу (Reveal on Demand)**: спочатку загальна інформація, детальна — коли потрібна. Хороший дизайн harness — як хороший UI-дизайн: не вивалюй всі опції на користувача одразу.
+- **Неможливість визначити важливість (Can't Tell What Matters)**: коли всі інструкції представлені в однаковому форматі та в одному місці, агент не може відрізнити обов'язкові жорсткі обмеження від рекомендаційних м'яких настанов.
+
+## Архітектура інструкцій
+
+```mermaid
+flowchart LR
+ Mono["One giant AGENTS.md"] --> MonoLoad["Even a small bug fix<br/>means reading all deploy rules and old notes"]
+ MonoLoad --> MonoRisk["Critical rules buried in the middle<br/>easily missed"]
+
+ Router["Short AGENTS.md"] --> Topics["Read API / DB / testing docs<br/>only when this task needs them"]
+ Topics --> RoutedResult["More context left for code reading<br/>and verification"]
+```
+
+```mermaid
+flowchart TB
+ File["600-line instruction file"] --> Top["Top section<br/>quick start + hard constraints"]
+ File --> Mid["Middle section<br/>security rule at line 300"]
+ File --> Bot["Bottom section<br/>explicit end-of-file checklist"]
+ Top --> Seen["High probability of recall"]
+ Bot --> Seen
+ Mid --> Missed["High probability of being diluted or ignored"]
+```
+
+## Як розбити файл
+
+Основний принцип: тримайте часто потрібну інформацію під рукою, прибирайте інколи потрібну і не носіть те, що ніколи не знадобиться.
+
+Вхідний файл `AGENTS.md` залишається в межах 50–200 рядків і містить лише найважливіше: огляд проєкту (одне-два речення, що одразу дають зрозуміти, що це таке), команди першого запуску (`make setup && make test`), глобальні жорсткі обмеження (не більше 15 безперечних правил) і посилання на тематичні документи (однорядковий опис та умова застосування).
+
+```markdown
+# AGENTS.md
+
+## Project Overview
+Python 3.11 FastAPI backend, PostgreSQL 15 database.
+
+## Quick Start
+- Install: `make setup`
+- Test: `make test`
+- Full verification: `make check`
+
+## Hard Constraints
+- All APIs must use OAuth 2.0 authentication
+- All database queries must use SQLAlchemy 2.0 syntax
+- All PRs must pass pytest + mypy --strict + ruff check
+
+## Topic Docs
+- API Design Patterns (`docs/api-patterns.md`) — Required reading when adding endpoints
+- Database Rules (`docs/database-rules.md`) — Required when modifying database operations
+- Testing Standards (`docs/testing-standards.md`) — Reference when writing tests
+```
+
+Кожен тематичний документ — 50–150 рядків, організований за темою в директорії `docs/` або поруч із відповідним модулем. Агент читає їх лише тоді, коли потрібно. Думайте про це як про органайзери для валізи: спідня білизна в одному відсіку, засоби гігієни в іншому, зарядні пристрої в третьому. Знайти потрібне не означає висипати всю валізу.
+
+Деяку інформацію краще розмістити безпосередньо в коді — визначення типів, коментарі до інтерфейсів, пояснення в конфігураційних файлах. Агент природно бачить їх при читанні коду, тому дублювати їх в інструкціях не потрібно.
+
+Кожна інструкція повинна документувати своє джерело («чому це правило було додано?»), умову застосування («коли це правило потрібне?») і умову вилучення («за яких обставин це правило можна видалити?»). Регулярно проводьте аудит і видаляйте застарілі, надлишкові або суперечливі записи. Керуйте своїми інструкціями так, як ви керуєте залежностями коду — невикористані залежності слід видаляти, інакше вони лише сповільнюють систему.
+
+Якщо інструкцію абсолютно необхідно залишити у вхідному файлі, розмістіть її на початку або в кінці, але ніколи — в середині. Ефект «загубленого в середині» говорить нам, що LLM значно краще використовують інформацію на краях довгого тексту, ніж у центрі. Але кращий підхід — перенести інструкції в тематичні документи для завантаження на вимогу.
+
+Як OpenAI, так і Anthropic неявно підтримують цей підхід із розбиттям. OpenAI каже, що вхідні файли мають бути «короткими і орієнтованими на маршрутизацію», тоді як Anthropic каже, що керуюча інформація для агентів із тривалим виконанням має бути «стислою та пріоритетною». Обидві компанії кажуть одне й те саме: не запихайте все в один файл.
+
+## Приклад із реального проєкту
+
+`AGENTS.md` команди SaaS-продукту розрісся з 50 рядків до 600. Вміст перемішував версії технологічного стеку, стандарти кодування, нотатки про виправлення минулих помилок, посібники з використання API, процедури розгортання та особисті переваги членів команди — все було там, але знайти частину, що стосується поточної задачі, було важко.
+
+Продуктивність агента почала помітно знижуватись: під час простих виправлень помилок агент витрачав значний контекст на обробку не пов'язаних із задачею інструкцій щодо розгортання; обмеження безпеки «всі запити до бази даних мають використовувати параметризовані запити» було заховане на рядку 300 і часто ігнорувалось; три суперечливі правила стилю коду змушували агента вибирати одне навмання.
+
+Команда провела рефакторинг із розбиттям:
+1. `AGENTS.md` скорочено до 80 рядків: лише огляд проєкту, команди запуску та 15 глобальних жорстких обмежень
+2. Створено тематичні документи: `docs/api-patterns.md` (120 рядків), `docs/database-rules.md` (60 рядків), `docs/testing-standards.md` (80 рядків)
+3. У вхідному файлі додано посилання на тематичні документи
+4. Історичні нотатки або перетворено на тест-кейси, або видалено повністю
+
+Після рефакторингу: відсоток успіху на тому самому наборі задач зріс із 45% до 72%. Дотримання обмежень безпеки підвищилось із 60% до 95%, оскільки правило перемістилося з середини файлу на початок вхідного файлу — більше не «загублене в середині».
+
+## Головне
+
+- «Додати правило» — короткострокове полегшення і довгострокова отрута. Перед додаванням будь-якого правила подумайте, чи не краще воно вписується в тематичний документ.
+- Вхідний файл — це маршрутизатор, а не енциклопедія. 50–200 рядків — лише огляд, жорсткі обмеження та посилання.
+- Використовуйте ефект «загубленого в середині»: розміщуйте важливу інформацію на початку або в кінці, а менш критичні пункти переносьте в тематичні документи.
+- Керуйте роздуттям інструкцій так само, як технічним боргом. Регулярний аудит, і кожна інструкція повинна мати джерело, умову застосування та умову вилучення.
+- Після розбиття SNR покращується, і агент витрачає більше контекстного бюджету на реальну задачу, а не на обробку нерелевантних інструкцій.
+
+## Додаткові матеріали
+
+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)
+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+- [Lost in the Middle: How Language Models Use Long Contexts](https://arxiv.org/abs/2307.03172)
+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)
+- [Nielsen Norman Group: Progressive Disclosure](https://www.nngroup.com/articles/progressive-disclosure/)
+
+## Вправи
+
+1. **Аудит SNR**: Візьміть свій поточний вхідний файл інструкцій і перелічіть усі записи. Виберіть 5 різних поширених типів задач і позначте, чи є кожна інструкція релевантною для цієї задачі. Обчисліть SNR для кожного типу задач. Інструкції, що є шумом для більшості задач, слід перенести до тематичних документів.
+
+2. **Рефакторинг «розкриття на вимогу»**: Якщо у вас є файл інструкцій понад 300 рядків, розбийте його на: (а) вхідний файл до 100 рядків, (б) 3–5 тематичних документів. Запустіть той самий набір задач (не менше 5) до і після рефакторингу та порівняйте відсоток успіху.
+
+3. **Перевірка «загубленого в середині»**: У довгому файлі інструкцій розмістіть критичне обмеження відповідно на початку, в середині та в кінці, щоразу запускаючи той самий набір задач (не менше 5 запусків на позицію). Подивіться, чи є різниця у відсотку дотримання. Ефект позиції може вас здивувати.
diff --git a/docs/uk/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md b/docs/uk/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md
new file mode 100644
index 0000000..16f59dc
--- /dev/null
+++ b/docs/uk/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md
@@ -0,0 +1,6 @@
+# Контрольний список наступності
+
+- Чи може новий агент визначити нещодавні зміни менш ніж за п'ять хвилин?
+- Чи задокументований поточний стабільний шлях запуску?
+- Чи чітко позначена незавершена робота?
+- Чи видна наступна найкраща задача без читання старих журналів чату?
diff --git a/docs/uk/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md b/docs/uk/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md
new file mode 100644
index 0000000..9d1c59a
--- /dev/null
+++ b/docs/uk/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md
@@ -0,0 +1,7 @@
+# Код до лекції 05
+
+Використовуйте цю теку для прикладів:
+
+- перерваних міжсесійних задач
+- відсутніх артефактів наступності
+- патернів відновлення наступності
diff --git a/docs/uk/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md b/docs/uk/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md
new file mode 100644
index 0000000..a35cf96
--- /dev/null
+++ b/docs/uk/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md
@@ -0,0 +1,17 @@
+# Приклад передачі між сесіями
+
+## Виконано
+
+- Додано підтримку імпорту Markdown
+- Додано базовий список документів у renderer
+
+## Зламано або не верифіковано
+
+- Імпорт успішний для `.md`, але не вдається для великих файлів `.txt`
+- Застосунок запускається, але детальний вигляд ще не підключено
+
+## Наступний найкращий крок
+
+- Виправити шлях імпорту `.txt`
+- Верифікувати імпорт наскрізно
+- Потім додати панель деталей документа
diff --git a/docs/uk/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts b/docs/uk/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts
new file mode 100644
index 0000000..69f9c3e
--- /dev/null
+++ b/docs/uk/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts
@@ -0,0 +1,162 @@
+/**
+ * session-simulator.ts
+ *
+ * Simulates two sessions working on a multi-step task.
+ * Run 1: No handoff file -- Session B starts from scratch and duplicates work.
+ * Run 2: With handoff file -- Session B picks up where Session A left off.
+ *
+ * Run: npx tsx docs/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface TaskStep {
+ id: number;
+ name: string;
+ durationMs: number;
+}
+
+interface SessionResult {
+ session: string;
+ stepsCompleted: number;
+ totalDurationMs: number;
+ duplicatedSteps: number;
+ output: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Task definition
+// ---------------------------------------------------------------------------
+
+const taskSteps: TaskStep[] = [
+ { id: 1, name: "Read project structure", durationMs: 50 },
+ { id: 2, name: "Understand existing auth module", durationMs: 80 },
+ { id: 3, name: "Design new search endpoint", durationMs: 60 },
+ { id: 4, name: "Implement search endpoint", durationMs: 100 },
+ { id: 5, name: "Write integration tests", durationMs: 70 },
+ { id: 6, name: "Update documentation", durationMs: 40 },
+];
+
+// ---------------------------------------------------------------------------
+// Simulated session executor
+// ---------------------------------------------------------------------------
+
+/** Simulate a session doing work. */
+function runSession(
+ sessionName: string,
+ startStep: number,
+ endStep: number
+): SessionResult {
+ const output: string[] = [];
+ let totalDuration = 0;
+
+ for (let i = startStep; i <= endStep; i++) {
+ const step = taskSteps.find((s) => s.id === i)!;
+ totalDuration += step.durationMs;
+ output.push(` [${sessionName}] Step ${step.id}: ${step.name} (${step.durationMs}ms)`);
+ }
+
+ return {
+ session: sessionName,
+ stepsCompleted: endStep - startStep + 1,
+ totalDurationMs: totalDuration,
+ duplicatedSteps: 0,
+ output,
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Run 1: No handoff file
+// ---------------------------------------------------------------------------
+
+function simulateNoHandoff(): { sessionA: SessionResult; sessionB: SessionResult } {
+ // Session A does steps 1-3 before timing out
+ const sessionA = runSession("Session A", 1, 3);
+
+ // Session B has no context, starts from scratch
+ const sessionB = runSession("Session B", 1, 6);
+ sessionB.duplicatedSteps = 3; // Redoes steps 1-3 that A already did
+
+ return { sessionA, sessionB };
+}
+
+// ---------------------------------------------------------------------------
+// Run 2: With handoff file
+// ---------------------------------------------------------------------------
+
+function simulateWithHandoff(): { sessionA: SessionResult; sessionB: SessionResult } {
+ // Session A does steps 1-3 and writes a handoff file
+ const sessionA = runSession("Session A", 1, 3);
+
+ // Session B reads handoff, starts from step 4
+ const sessionB = runSession("Session B", 4, 6);
+ sessionB.duplicatedSteps = 0;
+
+ return { sessionA, sessionB };
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function printRun(title: string, result: { sessionA: SessionResult; sessionB: SessionResult }): void {
+ console.log("\n" + "=".repeat(80));
+ console.log(` ${title}`);
+ console.log("=".repeat(80));
+
+ console.log("\n Session A output:");
+ for (const line of result.sessionA.output) {
+ console.log(line);
+ }
+
+ console.log("\n Session B output:");
+ for (const line of result.sessionB.output) {
+ console.log(line);
+ }
+
+ console.log("\n Session B notes:");
+ if (result.sessionB.duplicatedSteps > 0) {
+ console.log(` - Redid ${result.sessionB.duplicatedSteps} steps that Session A already completed`);
+ console.log(` - Wasted ${result.sessionB.totalDurationMs - (taskSteps.slice(3).reduce((s, t) => s + t.durationMs, 0))}ms on duplicate work`);
+ } else {
+ console.log(" - Read handoff file, continued from step 4");
+ console.log(" - No duplicate work performed");
+ }
+}
+
+function printComparison(): void {
+ const noHandoff = simulateNoHandoff();
+ const withHandoff = simulateWithHandoff();
+
+ printRun("RUN 1: NO HANDOFF FILE", noHandoff);
+ printRun("RUN 2: WITH HANDOFF FILE", withHandoff);
+
+ // Comparison table
+ console.log("\n" + "=".repeat(80));
+ console.log(" COMPARISON TABLE");
+ console.log("=".repeat(80) + "\n");
+
+ const header = `| ${pad("Metric", 35)}| ${pad("No Handoff", 15)}| ${pad("With Handoff", 15)}|`;
+ const sep = `|${"-".repeat(37)}|${"-".repeat(17)}|${"-".repeat(17)}|`;
+ console.log(header);
+ console.log(sep);
+
+ const noTotal = noHandoff.sessionA.totalDurationMs + noHandoff.sessionB.totalDurationMs;
+ const withTotal = withHandoff.sessionA.totalDurationMs + withHandoff.sessionB.totalDurationMs;
+
+ console.log(`| ${pad("Session A steps completed", 35)}| ${pad(String(noHandoff.sessionA.stepsCompleted), 15)}| ${pad(String(withHandoff.sessionA.stepsCompleted), 15)}|`);
+ console.log(`| ${pad("Session B steps completed", 35)}| ${pad(String(noHandoff.sessionB.stepsCompleted), 15)}| ${pad(String(withHandoff.sessionB.stepsCompleted), 15)}|`);
+ console.log(`| ${pad("Duplicated steps", 35)}| ${pad(String(noHandoff.sessionB.duplicatedSteps), 15)}| ${pad(String(withHandoff.sessionB.duplicatedSteps), 15)}|`);
+ console.log(`| ${pad("Total work (ms)", 35)}| ${pad(String(noTotal), 15)}| ${pad(String(withTotal), 15)}|`);
+ console.log(`| ${pad("Time saved by handoff", 35)}| ${pad("-", 15)}| ${pad(String(noTotal - withTotal) + "ms", 15)}|`);
+
+ console.log("\n A handoff file eliminates duplicate work and ensures continuity across sessions.\n");
+}
+
+printComparison();
diff --git a/docs/uk/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/uk/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
new file mode 100644
index 0000000..b483957
--- /dev/null
+++ b/docs/uk/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -0,0 +1,178 @@
+[中文版 →](../../../zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/)
+
+> Приклади коду: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/uk/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/)
+> Практичний проєкт: [Проєкт 03. Наступність між сесіями](./../../projects/project-03-multi-session-continuity/index.md)
+
+# Лекція 05. Збереження контексту між сесіями
+
+Ви просите Claude Code реалізувати повноцінну функцію. Він працює 30 хвилин, виконує більшу частину роботи, але контекст добігає кінця. Ви починаєте нову сесію, щоб продовжити — і виявляєте, що він не пам'ятає, які рішення були прийняті минулого разу, чому варіант А був відхилений на користь варіанта Б, які файли вже були змінені та в якому стані перебувають тести. Він витрачає 15 хвилин на повторне дослідження проєкту і може обрати підхід, несумісний із попереднім.
+
+Це реальна дилема, з якою стикаються AI-агенти для написання коду при міжсесійних задачах. У цій лекції пояснюється, чому агенти «втрачають нитку» під час тривалих задач і як структуроване збереження стану дозволяє новій сесії швидко продовжити роботу з того місця, де зупинилась попередня.
+
+## Контекстні вікна: не нескінченні
+
+Контекстні вікна обмежені. Це не та проблема, яку вирішать оновлення моделей — навіть якщо розміри вікон виростуть до 1M токенів, складні задачі все одно їх вичерпуватимуть. Агенти не просто генерують код: вони розуміють кодові бази, відстежують власну історію рішень, обробляють вивід інструментів і підтримують контекст розмови. Вся ця інформація зростає швидше, ніж розширюється вікно.
+
+Глибша проблема: інформація, яку продукують агенти, не є рівномірно важливою. Проміжні кроки міркування містять «чому» рішень — чому обрано варіант А замість Б, чому ця бібліотека, а не та, чому певна оптимізація була пропущена. Кінцевий результат містить лише «що» — сам код. Стратегії компресії зазвичай зберігають останнє, але втрачають перше. Наступна сесія бачить код, але не знає, чому він написаний саме так, і може «оптимізувати» навмисне проєктне рішення.
+
+Anthropic помітила щось цікаве у своїх дослідженнях агентів із тривалим виконанням: коли агенти відчувають, що контекст закінчується, вони виявляють поведінку «поспішного завершення» — намагаються завершити поточну роботу, пропускаючи кроки верифікації або обираючи просте рішення замість оптимального. Anthropic називає це «контекстною тривогою» (context anxiety).
+
+## Потік збереження наступності між сесіями
+
+Без файлів збереження стану кожна нова сесія змушена починати з нуля:
+
+```mermaid
+flowchart LR
+ S1["Session 1<br/>feature is half done"] --> End1["Context is nearly full<br/>session ends"]
+ End1 --> S2["Session 2 starts fresh"]
+ S2 --> Guess["Re-read folders, rerun tests,<br/>guess why the code was written this way"]
+ Guess --> Drift["Work gets repeated<br/>and recovery is slow"]
+```
+
+З файлами збереження стану нові сесії можуть швидко продовжити роботу:
+
+```mermaid
+flowchart LR
+ Work["Session 1 work"] --> Progress["PROGRESS.md<br/>done / in progress / next step"]
+ Work --> Decisions["DECISIONS.md<br/>why this approach was chosen"]
+ Work --> Verify["Verification notes<br/>which tests pass and fail"]
+ Work --> Commit["Git checkpoint<br/>exact repo state"]
+
+ Progress --> Rebuild["Session 2 rebuild"]
+ Decisions --> Rebuild
+ Verify --> Rebuild
+ Commit --> Rebuild
+
+ Rebuild --> Resume["New session picks up quickly"]
+```
+
+## Ключові концепції
+
+- **Контекстні вікна обмежені**: незалежно від заявленого розміру вікна (128K, 200K, 1M), тривалі задачі врешті-решт їх вичерпають. Після вичерпання потрібна або компресія (втрата інформації), або скидання контексту (початок нової сесії) — обидва варіанти щось втрачають.
+- **Файли збереження стану (State persistence files)**: файли зі збереженим станом, що дозволяють новій сесії однозначно продовжити роботу з того місця, де зупинилась попередня. Найпростіша форма включає журнали прогресу, записи верифікації та наступні дії.
+- **Вартість відновлення (Rebuild cost)**: час, необхідний новій сесії для досягнення виконуваного стану. Хороший harness може скоротити вартість відновлення з 15 хвилин до 3 хвилин.
+- **Дрейф (Drift)**: розрив між розумінням агента та реальним станом репозиторію коду. Кожна межа між сесіями вносить дрейф; без контролю він накопичується від сесії до сесії.
+- **Контекстна тривога (Context anxiety)**: явище, зафіксоване Anthropic, — агенти виявляють поведінку поспішного завершення, коли наближаються до меж контексту, дочасно завершуючи задачі, щоб уникнути втрати інформації. По суті, це ірраціональна тривога через ресурси.
+- **Компресія проти скидання (Compaction vs. reset)**: компресія підсумовує контекст у межах тієї самої сесії (зберігає «що», може втратити «чому»); скидання відкриває нову сесію, відбудовуючись із збережених артефактів (чистий стан, але залежить від повноти артефактів).
+
+## Що відбувається, коли наступність переривається
+
+Попередня сесія витратила значний контекстний бюджет на аналіз трьох підходів і вибір варіанта Б. Агент у цій сесії нічого не знає про той аналіз і може переприйняти рішення на основі неповної інформації — потенційно обравши варіант А. Та сама інформація, різний висновок, тому що контекст прийняття рішення зник.
+
+Ще гірше — дублювання роботи. Агент не впевнений, чи певна робота вже була виконана, і робить її знову. Або, що гірше, виконує половину, виявляє конфлікт із наявною реалізацією і змушений переробляти. Без записів прогресу нова сесія не знає, що вже зроблено.
+
+Протягом кількох сесій напрямок реалізації може непомітно відхилитися від початкових вимог. Кожна нова сесія має дещо інше розуміння цілей проєкту. Кожне відхилення накладається на попереднє, і кінцевий результат може бути далеким від початкового задуму.
+
+Є також прогалина верифікації. Результати верифікації попередньої сесії (які тести проходять, які ні, чому вони не проходять) не були записані. Нова сесія змушена повторно запускати всю верифікацію, щоб зрозуміти поточний стан. Кожна сесія діагностує з нуля, щоразу витрачаючи цінний контекст.
+
+Як OpenAI, так і Anthropic підкреслюють важливість структурованого збереження стану у своїй документації. Стаття OpenAI про harness engineering розглядає репозиторій як «операційний журнал» — результати кожної операції повинні залишати відстежувані сліди в репозиторії. Документація Anthropic щодо агентів із тривалим виконанням спеціально рекомендує «handoff files» — структуровані документи, що містять поточний стан, відомі проблеми та наступні дії.
+
+## Практичні підходи до збереження стану
+
+Основний підхід: **Ставтеся до агента як до інженера, чия короткострокова пам'ять стирається наприкінці кожної сесії.** Перед «виходом з зміни» він повинен записати критичну інформацію, щоб агент наступної «зміни» міг швидко включитися.
+
+**Інструмент 1: Файл прогресу (PROGRESS.md).** Найпростіший файл збереження стану:
+
+```markdown
+# Project Progress
+
+## Current State
+- Latest commit: abc1234 (feat: add user preferences endpoint)
+- Test status: 42/43 passing (test_pagination_edge_case failing)
+- Lint: passing
+
+## Completed
+- [x] User model and database migration
+- [x] Basic CRUD endpoints
+- [x] Auth middleware integration
+
+## In Progress
+- [ ] Pagination feature (90% - edge case test failing)
+
+## Known Issues
+- test_pagination_edge_case returns 500 on empty result sets
+- Need to confirm whether deleted users should appear in listings
+
+## Next Steps
+1. Fix pagination edge case bug
+2. Add "include deleted users" query parameter
+3. Update API documentation
+```
+
+**Інструмент 2: Журнал рішень (DECISIONS.md).** Записуйте важливі проєктні рішення та причини. Детальні проєктні документи не потрібні — лише «яке рішення, чому, коли»:
+
+```markdown
+# Design Decisions
+
+## 2024-01-15: Use Redis for user preferences caching
+- Reason: High read frequency (every API call), small data size
+- Rejected alternative: PostgreSQL materialized view (high change frequency makes maintenance cost not worthwhile)
+- Constraint: Cache TTL of 5 minutes, active invalidation on write
+```
+
+**Інструмент 3: Git-коміти як контрольні точки.** Робіть коміт після завершення кожної атомарної одиниці роботи. Повідомлення комітів повинні пояснювати, що було зроблено і чому. Це безкоштовні, автоматично версіоновані знімки стану.
+
+**Інструмент 4: init.sh або процес ініціалізації harness.** Вкажіть в `AGENTS.md` процедури «входу на зміну» і «виходу з зміни»:
+
+```markdown
+## At session start (clock in)
+1. Read PROGRESS.md for current state
+2. Read DECISIONS.md for important decisions
+3. Run make check to confirm repo is in consistent state
+4. Continue from PROGRESS.md "Next Steps" section
+
+## Before session end (clock out)
+1. Update PROGRESS.md
+2. Run make check to confirm consistent state
+3. Commit all completed work
+```
+
+**Змішана стратегія**: не кожна задача потребує скидання контексту. Короткі задачі (до 30 хвилин) можна завершити в межах однієї сесії. Тривалі задачі (що охоплюють кілька сесій) обов'язково використовують файли прогресу та журнали рішень для забезпечення наступності. Критерій вибору: якщо задача потребує більше 60% вікна, починайте готувати handoff.
+
+### Детальніше про контекстну тривогу
+
+Дослідження Anthropic у березні 2026 року детально розкрило конкретні прояви контекстної тривоги: на Sonnet 4.5, коли контекст наближається до межі вікна, агент демонструє виражену поведінку «поспішного завершення».
+
+Дві стратегії вирішують цю проблему:
+
+**Компресія (Compaction)**: підсумовування ранньої розмови в межах тієї самої сесії. Перевага: підтримує наступність, агент бачить «що». Недолік: «чому» часто губиться в резюме — чому варіант Б обраний замість А, чому певна оптимізація була пропущена. Що важливіше, компресія не усуває контекстну тривогу — агент знає, що контекст колись був більшим, і психологічно все одно схильний поспішати із завершенням.
+
+**Скидання контексту (Context reset)**: повне очищення контексту, відкриття нової сесії, відбудова із збережених артефактів. Перевага: чистий ментальний стан — нова сесія не має тривоги «я вичерпую час». Недолік: залежить від повноти handoff-артефактів. Якщо в файлі прогресу відсутня критична інформація, нова сесія може витратити час, рухаючись у хибному напрямку.
+
+Реальні дані Anthropic: для Sonnet 4.5 контекстна тривога настільки виражена, що компресія сама по собі недостатня — скидання контексту стає критичним компонентом дизайну harness. Але для Opus 4.5 ця поведінка значно менш виражена, і компресія може керувати контекстом без покладання на скидання. Це означає: **дизайн harness вимагає конкретного розуміння цільової моделі, а не шаблону «одне рішення для всіх».**
+
+> Джерело: [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
+
+## Приклад із реального проєкту
+
+Агенту було доручено реалізувати систему блогу з автентифікацією користувачів — 12 функціональних пунктів, орієнтовно 5 сесій.
+
+**Базовий варіант без файлів збереження стану**: Сесія 1 реалізувала модель користувача та базові маршрути. Сесія 2 почалася без пам'яті агента про інтерфейсний контракт middleware автентифікації, витративши ~15 хвилин на відтворення попереднього проєктного задуму. До сесії 3 накопичений дрейф змусив агента почати повторно реалізовувати вже завершені функції. До сесії 5 репозиторій містив багато надлишкового коду, але основна функція автентифікації так і не пройшла наскрізні тести. Завершено лише 7 із 12 функціональних пунктів, 3 з прихованими проблемами коректності.
+
+**З файлами збереження стану**: використовуючи файли прогресу, журнали рішень, записи верифікації та git-контрольні точки. Звіт про стан оновлювався автоматично наприкінці кожної сесії. Вартість відновлення в сесії 2 скоротилась до ~3 хвилин. До сесії 5 всі 12 функціональних пунктів завершено та верифіковано.
+
+Кількісне порівняння: час відновлення скорочено на ~78%, відсоток виконання функцій зріс із 58% до 100%, відсоток прихованих дефектів знизився з 43% до 8%.
+
+## Головне
+
+- Контекстні вікна — обмежений ресурс. Тривалі задачі охоплюватимуть кілька сесій, а сесії втрачатимуть інформацію — це об'єктивна реальність.
+- Рішення — не більші вікна, а краще збереження стану. Файли прогресу, журнали рішень і git-контрольні точки разом дозволяють новим сесіям продовжувати роботу з того місця, де зупинились попередні.
+- Ставтеся до агента як до інженера, чия короткострокова пам'ять стирається наприкінці кожної сесії: перед «виходом з зміни» запишіть, що було зроблено, чому і що далі.
+- Вартість відновлення — ключова метрика. Хороший harness повинен доводити нові сесії до виконуваного стану за 3 хвилини.
+- Змішана стратегія: короткі задачі — в межах сесії, тривалі — з структурованими артефактами для забезпечення наступності.
+
+## Додаткові матеріали
+
+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)
+- [Lost in the Middle: How Language Models Use Long Contexts](https://arxiv.org/abs/2307.03172)
+- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)
+
+## Вправи
+
+1. **Вимірювання збереження стану**: Виберіть задачу розробки, що потребує принаймні 3 сесій. Без надання будь-яких файлів збереження стану зафіксуйте на початку кожної сесії, скільки контексту агент витрачає на «з'ясування того, що відбулось минулого разу». Після кожної сесії створіть файл прогресу і дозвольте наступній сесії починати з нього. Порівняйте вартість відновлення з файлами прогресу і без них.
+
+2. **Розробка шаблону handoff**: Розробіть мінімальний шаблон handoff з чотирма полями: стан репозиторію (хеш коміту), стан runtime (відсоток проходження тестів), блокери, наступні дії. Дозвольте абсолютно новій агентській сесії відновити стан проєкту, використовуючи лише цей шаблон. Зафіксуйте неясності, що виникли під час відновлення, ітеративно вдосконалюйте шаблон.
+
+3. **Експеримент зі змішаною стратегією**: У задачі розробки на 5 сесій порівняйте три стратегії: (а) завжди починати нові сесії + файли прогресу, (б) робити якомога більше в одній сесії (компресія контексту), (в) змішана стратегія (короткі задачі — в межах сесії, тривалі — між сесіями + файли прогресу). Порівняйте час відновлення, відсоток виконання функцій і узгодженість рішень.
diff --git a/docs/uk/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md b/docs/uk/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md
new file mode 100644
index 0000000..e046ced
--- /dev/null
+++ b/docs/uk/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md
@@ -0,0 +1,8 @@
+# Код до лекції 06
+
+Використовуйте цю теку для прикладів:
+
+- результатів ініціалізатора
+- скриптів ініціалізації
+- файлів прогресу
+- каркасу першого запуску
diff --git a/docs/uk/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts b/docs/uk/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts
new file mode 100644
index 0000000..52dcd98
--- /dev/null
+++ b/docs/uk/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts
@@ -0,0 +1,296 @@
+/**
+ * init-check.ts
+ *
+ * Programmatically checks initialization prerequisites:
+ * - Node.js version
+ * - Dependencies installed (node_modules exists)
+ * - Data directory exists
+ * - Config files present
+ *
+ * Simulates running with and without an explicit init phase,
+ * showing how missing prerequisites cause silent failures later.
+ *
+ * Run: npx tsx docs/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as childProcess from "node:child_process";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface CheckItem {
+ name: string;
+ category: string;
+ check: () => { pass: boolean; detail: string };
+ impactIfMissing: string;
+}
+
+interface CheckResult {
+ name: string;
+ category: string;
+ passed: boolean;
+ detail: string;
+ impactIfMissing: string;
+}
+
+// ---------------------------------------------------------------------------
+// Checks
+// ---------------------------------------------------------------------------
+
+function createChecks(targetDir: string): CheckItem[] {
+ return [
+ {
+ name: "Node.js version >= 18",
+ category: "Runtime",
+ check: () => {
+ try {
+ const version = process.version; // e.g. "v20.11.0"
+ const major = parseInt(version.replace("v", "").split(".")[0], 10);
+ return {
+ pass: major >= 18,
+ detail: `Detected: ${version} (need >= v18)`,
+ };
+ } catch {
+ return { pass: false, detail: "Could not detect Node.js version" };
+ }
+ },
+ impactIfMissing: "TypeScript features and built-in APIs unavailable",
+ },
+ {
+ name: "package.json exists",
+ category: "Config",
+ check: () => {
+ const p = path.join(targetDir, "package.json");
+ const exists = fs.existsSync(p);
+ return {
+ pass: exists,
+ detail: exists ? `Found: ${p}` : "Not found in target directory",
+ };
+ },
+ impactIfMissing: "Cannot install dependencies or run scripts",
+ },
+ {
+ name: "Dependencies installed (node_modules)",
+ category: "Dependencies",
+ check: () => {
+ const p = path.join(targetDir, "node_modules");
+ const exists = fs.existsSync(p);
+ return {
+ pass: exists,
+ detail: exists ? `Found: ${p}` : "node_modules/ not found -- run npm install",
+ };
+ },
+ impactIfMissing: "All imports fail at runtime",
+ },
+ {
+ name: "TypeScript available",
+ category: "Toolchain",
+ check: () => {
+ try {
+ const result = childProcess.execSync("npx tsc --version", {
+ encoding: "utf-8",
+ timeout: 10000,
+ stdio: ["pipe", "pipe", "pipe"],
+ }).trim();
+ return { pass: true, detail: `Detected: ${result}` };
+ } catch {
+ return { pass: false, detail: "TypeScript not available via npx" };
+ }
+ },
+ impactIfMissing: "Cannot compile TypeScript files",
+ },
+ {
+ name: "tsconfig.json exists",
+ category: "Config",
+ check: () => {
+ const p = path.join(targetDir, "tsconfig.json");
+ const exists = fs.existsSync(p);
+ return {
+ pass: exists,
+ detail: exists ? `Found: ${p}` : "Not found",
+ };
+ },
+ impactIfMissing: "TypeScript compiler uses defaults, may not match project needs",
+ },
+ {
+ name: "Source directory exists",
+ category: "Structure",
+ check: () => {
+ const candidates = ["src", "lib", "app"];
+ const found = candidates.filter((d) => {
+ const p = path.join(targetDir, d);
+ return fs.existsSync(p) && fs.statSync(p).isDirectory();
+ });
+ return {
+ pass: found.length > 0,
+ detail: found.length > 0 ? `Found: ${found.join(", ")}` : "No src/ lib/ or app/ directory found",
+ };
+ },
+ impactIfMissing: "Agent cannot locate source files to modify",
+ },
+ {
+ name: "Test directory exists",
+ category: "Structure",
+ check: () => {
+ const candidates = ["test", "tests", "__tests__", "spec"];
+ const found = candidates.filter((d) => {
+ const p = path.join(targetDir, d);
+ return fs.existsSync(p) && fs.statSync(p).isDirectory();
+ });
+ return {
+ pass: found.length > 0,
+ detail: found.length > 0 ? `Found: ${found.join(", ")}` : "No test directory found",
+ };
+ },
+ impactIfMissing: "Agent cannot find or run existing tests",
+ },
+ {
+ name: "Git repository initialized",
+ category: "Version Control",
+ check: () => {
+ const gitDir = path.join(targetDir, ".git");
+ const exists = fs.existsSync(gitDir);
+ return {
+ pass: exists,
+ detail: exists ? "Git repository detected" : "No .git directory found",
+ };
+ },
+ impactIfMissing: "No rollback capability, no change history",
+ },
+ ];
+}
+
+// ---------------------------------------------------------------------------
+// Simulation: with and without init phase
+// ---------------------------------------------------------------------------
+
+interface SimResult {
+ scenario: string;
+ checksRun: boolean;
+ failuresBeforeWork: number;
+ workAttempted: boolean;
+ workSucceeded: boolean;
+ timeWastedMs: number;
+}
+
+function simulateWithoutInit(): SimResult {
+ // Agent skips init, goes straight to work.
+ // Encounters failures one at a time as it hits missing prerequisites.
+ const checks = createChecks(process.cwd());
+ let failures = 0;
+ let timeWasted = 0;
+
+ for (const check of checks) {
+ const result = check.check();
+ if (!result.pass) {
+ failures++;
+ timeWasted += 200; // Agent spends time discovering each missing piece
+ }
+ }
+
+ return {
+ scenario: "NO INIT PHASE",
+ checksRun: false,
+ failuresBeforeWork: 0, // Didn't check upfront
+ workAttempted: true,
+ workSucceeded: failures === 0,
+ timeWastedMs: timeWasted,
+ };
+}
+
+function simulateWithInit(): SimResult {
+ // Agent runs init phase first, discovers all issues upfront.
+ const checks = createChecks(process.cwd());
+ let failures = 0;
+
+ for (const check of checks) {
+ if (!check.check().pass) {
+ failures++;
+ }
+ }
+
+ return {
+ scenario: "WITH INIT PHASE",
+ checksRun: true,
+ failuresBeforeWork: failures,
+ workAttempted: failures === 0,
+ workSucceeded: failures === 0,
+ timeWastedMs: 0,
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function run(): void {
+ const targetDir = process.cwd();
+ console.log("\n" + "=".repeat(80));
+ console.log(" INITIALIZATION PREREQUISITE CHECK");
+ console.log("=".repeat(80));
+ console.log(` Target: ${targetDir}\n`);
+
+ const checks = createChecks(targetDir);
+ const results: CheckResult[] = checks.map((c) => {
+ const r = c.check();
+ return {
+ name: c.name,
+ category: c.category,
+ passed: r.pass,
+ detail: r.detail,
+ impactIfMissing: c.impactIfMissing,
+ };
+ });
+
+ // Detailed report
+ const header = `| ${pad("Check", 35)}| ${pad("Category", 12)}| ${pad("Status", 6)}| Detail`;
+ const sep = `|${"-".repeat(37)}|${"-".repeat(14)}|${"-".repeat(8)}|${"-".repeat(40)}`;
+ console.log(header);
+ console.log(sep);
+
+ for (const r of results) {
+ const status = r.passed ? "PASS" : "FAIL";
+ console.log(`| ${pad(r.name, 35)}| ${pad(r.category, 12)}| ${pad(status, 6)}| ${r.detail}`);
+ }
+
+ const passCount = results.filter((r) => r.passed).length;
+ const failCount = results.filter((r) => !r.passed).length;
+
+ console.log("\n" + "-".repeat(80));
+ console.log(` Results: ${passCount} passed, ${failCount} failed out of ${results.length} checks`);
+
+ if (failCount > 0) {
+ console.log("\n FAILED CHECKS -- Impact if not resolved:");
+ for (const r of results.filter((r) => !r.passed)) {
+ console.log(` - ${r.name}: ${r.impactIfMissing}`);
+ }
+ }
+
+ // Comparison: with vs without init
+ const noInit = simulateWithoutInit();
+ const withInit = simulateWithInit();
+
+ console.log("\n" + "=".repeat(80));
+ console.log(" INIT PHASE COMPARISON");
+ console.log("=".repeat(80) + "\n");
+
+ const cHeader = `| ${pad("Metric", 35)}| ${pad("No Init Phase", 18)}| ${pad("With Init Phase", 18)}|`;
+ const cSep = `|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(20)}|`;
+ console.log(cHeader);
+ console.log(cSep);
+ console.log(`| ${pad("Prerequisites checked upfront", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);
+ console.log(`| ${pad("Work attempted despite issues", 35)}| ${pad(String(noInit.workAttempted), 18)}| ${pad(String(withInit.workAttempted), 18)}|`);
+ console.log(`| ${pad("Time wasted discovering issues late", 35)}| ${pad(noInit.timeWastedMs + "ms", 18)}| ${pad(withInit.timeWastedMs + "ms", 18)}|`);
+ console.log(`| ${pad("Work succeeded", 35)}| ${pad(String(noInit.workSucceeded), 18)}| ${pad(String(withInit.workSucceeded), 18)}|`);
+
+ console.log("\n An explicit init phase catches problems before they waste time.\n");
+}
+
+run();
diff --git a/docs/uk/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh b/docs/uk/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh
new file mode 100644
index 0000000..2c6e1b0
--- /dev/null
+++ b/docs/uk/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh
@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "[init] installing dependencies"
+npm install
+
+echo "[init] starting the docs site is optional"
+echo "[init] use npm run docs:dev for course docs"
+
+echo "[init] project-specific startup would go here"
diff --git a/docs/uk/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md b/docs/uk/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md
new file mode 100644
index 0000000..8017432
--- /dev/null
+++ b/docs/uk/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md
@@ -0,0 +1,7 @@
+# Чеклист результатів ініціалізатора
+
+- Чи є канонічна команда запуску?
+- Чи є канонічна команда верифікації?
+- Чи є перший артефакт прогресу?
+- Чи є стабільний перший коміт?
+- Чи є видима поверхня функцій для наступних запусків?
diff --git a/docs/uk/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/uk/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
new file mode 100644
index 0000000..e97349e
--- /dev/null
+++ b/docs/uk/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
@@ -0,0 +1,157 @@
+[中文版 →](../../../zh/lectures/lecture-06-why-initialization-needs-its-own-phase/)
+
+> Приклади коду: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/uk/lectures/lecture-06-why-initialization-needs-its-own-phase/code/)
+> Практичний проєкт: [Проєкт 03. Безперервність між сесіями](./../../projects/project-03-multi-session-continuity/index.md)
+
+# Лекція 06. Нехай агент ініціалізується перед кожною робочою сесією
+
+Ви починаєте нову сесію агента і кажете йому «додай функцію пошуку». Він одразу кидається писати код — похвальний ентузіазм. Через 20 хвилин виявляється, що тестовий фреймворк налаштований неправильно, і витрачається ще 10 хвилин на виправлення; потім з'ясовується, що формат скрипту міграції бази даних не той — ще метушня. Функцію пошуку врешті-решт додано, але вся сесія виявилася неефективною. Більша частина часу пішла на «розбирання того, як влаштований проєкт», а не на написання самої функції пошуку.
+
+Кращий підхід: перш ніж дозволити агенту почати роботу, виділіть окрему фазу для підготовки базового середовища, виконання перевірочних команд і знайомства зі структурою проєкту. Роботу з ініціалізації не можна змішувати з реалізацією функцій — це два принципово різні типи задач.
+
+Ця лекція пояснює, чому ініціалізація має бути окремою фазою, а не перемішуватися з реалізацією.
+
+## Два принципово різні типи роботи
+
+Ініціалізація та реалізація мають зовсім різні цілі оптимізації. Фаза реалізації спрямована на максимізацію кількості та якості верифікованих функцій. Фаза ініціалізації спрямована на максимізацію надійності й ефективності всієї подальшої реалізації.
+
+Коли ви змішуєте ініціалізацію з реалізацією, агент стикається з багатоцільовою задачею оптимізації: йому доводиться одночасно будувати інфраструктуру і писати код функцій. Без чіткого визначення пріоритетів агент природно тяжіє до написання коду (бо це безпосередньо видимий результат), жертвуючи інфраструктурою (бо її цінність проявляється лише в наступних сесіях). Наслідок: інфраструктура будується хитко, а надійність коду функцій теж страждає.
+
+## Життєвий цикл ініціалізації
+
+```mermaid
+flowchart TB
+ subgraph Wrong["Mixed into one session (wrong)"]
+ W1["Start feature work immediately"] --> W2["Discover env and test gaps mid-task"]
+ W2 --> W3["Accumulate unverified code"]
+ W3 --> W4["Next session must rediscover project state"]
+ end
+
+ subgraph Right["Dedicated initialization phase (right)"]
+ R1["Session 1: environment runnable"] --> R2["Example test passing"]
+ R2 --> R3["Startup readiness checklist + task list written"]
+ R3 --> R4["Clean checkpoint committed"]
+ R4 --> R5["Later sessions start directly on verified tasks"]
+ end
+```
+
+## Що відбувається, коли їх змішують
+
+Найочевидніша проблема: інфраструктура будується ненадійно. Агент витрачає 80% зусиль на код функцій, а решту 20% — на поверхневе налаштування інфраструктури. Тестовий фреймворк налаштований, але не перевірений; правила лінтера встановлені, але занадто м'які; файл прогресу не створено. Ці вади непомітні в першій сесії (бо агент ще пам'ятає, що робив), але спливають у другій: новий агент не знає, як запустити проєкт, як тестувати і де що знаходиться.
+
+Прихованіша проблема — «накопичення неперевіреного коду». Код функцій написаний до того, як тестовий фреймворк правильно налаштований — коли ви нарешті повертаєтеся додавати тести, може виявитися, що сам дизайн був хибним. Знаючи це раніше, ви б реалізували інакше. Що більше коду написано заздалегідь, то більше доведеться зносити і переробляти потім.
+
+Бюджет контексту витрачається даремно. Робота з ініціалізації (налаштування середовища, налаштування тестів, вивчення структури проєкту) поглинає велику частину бюджету, залишаючи менше для реальної реалізації функцій. Перша сесія завершує лише половину функцій, а друга все одно починає з нуля в розумінні проєкту. Бюджет витрачений на ініціалізацію, але ініціалізацію так і не зроблено як слід — найгірший з варіантів.
+
+Найлегше проігнорована проблема — приховані припущення, що стають пастками. Рішення, прийняті агентом під час ініціалізації (який тестовий фреймворк, як організувати директорії, керування залежностями) — якщо вони не зафіксовані явно, наступні сесії можуть зробити суперечливі вибори. Перша сесія вибрала Vitest як тестовий фреймворк, але агент другої сесії цього не знає і впроваджує Jest. Два тестових фреймворки існують паралельно, а витрати на підтримку подвоюються.
+
+Дослідження Anthropic у сфері розробки довготривалих застосунків явно рекомендує розділяти ініціалізацію та реалізацію. Їхні експериментальні дані: проєкти з виділеною фазою ініціалізації показали на 31% вищий відсоток завершення функцій у багатосесійних сценаріях порівняно зі змішаним підходом. А час, витрачений на фазу ініціалізації, повністю окупається вже в наступних 3–4 сесіях.
+
+Посібник з harness engineering від OpenAI Codex також наголошує на принципі «репозиторій як операційний запис»: з самого першого запуску встановіть чітку операційну структуру, інакше кожна нова сесія змушена заново виводити конвенції проєкту.
+
+## Ключові поняття
+
+- **Фаза ініціалізації**: Перша фаза в життєвому циклі агента — вона лише встановлює передумови для подальшої реалізації, без жодної розробки функцій. Її результат — інфраструктура, а не бізнес-код.
+- **Чеклист готовності до запуску**: Умови, за яких проєкт може однозначно обслуговуватися новою сесією агента: можна запустити, можна протестувати, можна побачити прогрес, можна підхопити наступні кроки. Чотири умови, всі обов'язкові.
+- **З нуля vs за шаблоном**: Старт з нуля означає, що агент мусить самостійно виводити структуру проєкту з порожньої директорії; старт за шаблоном означає, що інфраструктура вже є. Старт за шаблоном значно перевищує старт з нуля.
+- **Завжди готовий до передачі**: Проєкт у будь-який момент перебуває в стані, коли нова сесія агента може підхопити роботу. Жодних усних пояснень не потрібно — достатньо подивитися на вміст репозиторію.
+- **Час від початку до першого тесту, що пройшов**: Час від старту проєкту до моменту, коли перша точка функції проходить верифікацію. Це основна метрика ефективності ініціалізації.
+- **Відсоток успішних наступних сесій**: Частка наступних сесій, які можуть успішно виконувати задачі без покладання на неявні знання. Це найкраща оцінка якості ініціалізації.
+
+## Як правильно проводити ініціалізацію
+
+**Розглядайте ініціалізацію як окрему фазу.** Перша сесія займається виключно ініціалізацією — жодного бізнес-коду. Ініціалізація виробляє:
+
+**1. Запускне середовище.** Проєкт стартує, залежності встановлені, жодних проблем з середовищем.
+
+**2. Верифікований тестовий фреймворк.** Хоча б один приклад тесту проходить, доводячи, що сам тестовий фреймворк правильно налаштований.
+
+**3. Документ чеклиста готовності до запуску.** Чіткий документ, що повідомляє наступним сесіям:
+```markdown
+# Startup Readiness Checklist
+
+## Start Commands
+- Install dependencies: `make setup`
+- Start dev server: `make dev`
+- Run tests: `make test`
+- Full verification: `make check`
+
+## Current State
+- All dependencies installed and locked
+- Test framework configured (Vitest + React Testing Library)
+- Example test passing (1/1)
+- Lint rules configured (ESLint + Prettier)
+
+## Project Structure
+- src/ — Source code
+- src/components/ — React components
+- src/api/ — API client
+- tests/ — Test files
+```
+
+**4. Розбивка на задачі.** Весь проєкт поділяється на впорядкований список задач, кожна з чіткими критеріями прийняття:
+```markdown
+# Task Breakdown
+
+## Task 1: User Authentication Basics
+- Implement JWT auth middleware
+- Add login/register endpoints
+- Acceptance: pytest tests/test_auth.py all passing
+
+## Task 2: User Profile Page
+- Implement user profile CRUD
+- Add profile edit form
+- Acceptance: pytest tests/test_profile.py all passing
+
+## Task 3: Search Feature
+- ...
+```
+
+**5. Git-коміт як контрольна точка.** Після завершення ініціалізації зафіксуйте чисту контрольну точку комітом. Уся подальша робота починається з цієї точки.
+
+**Старт за шаблоном**: Не починайте з порожньої директорії. Використовуйте шаблон проєкту (create-react-app, fastapi-template тощо), щоб заздалегідь задати стандартну структуру директорій, конфігурацію залежностей і тестовий фреймворк. Вбудуйте в шаблон поширені кроки ініціалізації, залишаючи лише специфічну для проєкту роботу з ініціалізації.
+
+**Критерії завершення ініціалізації**: Не «скільки коду написано», а чи виконані всі чотири умови чеклиста готовності до запуску: можна запустити, можна протестувати, можна побачити прогрес, можна підхопити наступні кроки. Використовуйте цей чеклист для валідації ініціалізації:
+
+```markdown
+## Initialization Acceptance Checklist
+- [ ] `make setup` succeeds from scratch
+- [ ] `make test` has at least one passing test
+- [ ] A new agent session can answer "how to run" and "how to test" from repo contents alone
+- [ ] Task breakdown file exists with at least 3 tasks
+- [ ] Everything committed to git
+```
+
+## Реальний приклад
+
+Порівняння двох підходів до ініціалізації для React-проєкту фронтенду:
+
+**Змішаний підхід**: Агент одночасно створював каркас проєкту і реалізовував першу функцію в сесії 1. Наприкінці сесії репозиторій мав робочий код, але без явної документації команд запуску/тестування, без файлу відстеження прогресу, без розбивки на задачі. Сесія 2 витратила близько 20 хвилин на виведення структури проєкту, тестового фреймворку і процесу збірки.
+
+**Виділена ініціалізація**: Сесія 1 займалася виключно ініціалізацією — створила структуру директорій за шаблоном, налаштувала тестовий фреймворк (Vitest + React Testing Library), написала й верифікувала один приклад тесту, створила чеклист готовності до запуску та файл розбивки на задачі, зафіксувала початкову контрольну точку. Час відновлення роботи в сесії 2 склав менше 3 хвилин, і вона одразу почала працювати за списком задач.
+
+Порівняння повного циклу проєкту: сумарний час відновлення роботи (упродовж усіх сесій) при змішаному підході був приблизно на 60% більшим, ніж при виділеній ініціалізації. Додаткові 20 хвилин, витрачені на ініціалізацію, окупились із лишком у наступних сесіях. Трохи більше часу на початку для якісної ініціалізації — і фактична ефективність наступних сесій виявляється вищою.
+
+## Ключові висновки
+
+- Ініціалізація та реалізація мають різні цілі оптимізації — змішування тягне обидві вниз.
+- Результат ініціалізації — не бізнес-код, а інфраструктура: запускне середовище, верифіковані тести, чеклист готовності до запуску, розбивка на задачі.
+- Перевіряйте ініціалізацію за чотирма умовами чеклиста готовності до запуску: можна запустити, можна протестувати, можна побачити прогрес, можна підхопити наступні кроки.
+- Старт за шаблоном перевершує старт з нуля. Використовуйте шаблони проєктів для заздалегідь налаштованої стандартної інфраструктури.
+- Час, витрачений на ініціалізацію, окупається вже в наступних 3–4 сесіях. Це не зайві витрати — це інвестиція наперед.
+
+## Додаткова література
+
+- [Anthropic: Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+- [OpenAI: Harness Engineering](https://openai.com/index/harness-engineering/)
+- [HumanLayer: Harness Engineering for Coding Agents](https://humanlayer.dev/articles/harness-engineering-for-coding-agents/)
+- [Infrastructure as Code — Martin Fowler](https://martinfowler.com/bliki/InfrastructureAsCode.html)
+- [SWE-agent: Agent-Computer Interfaces](https://github.com/princeton-nlp/SWE-agent)
+
+## Вправи
+
+1. **Розробка чеклиста готовності до запуску**: Напишіть повний чеклист готовності до запуску для проєкту, який ви розробляєте. Потім відкрийте абсолютно нову сесію агента, покажіть їй лише вміст репозиторію (жодного усного контексту), і попросіть її спробувати запустити проєкт, виконати тести та зрозуміти поточний прогрес. Зафіксуйте кожну проблему, з якою вона зіткнеться, — кожна відповідає відсутньому пункту вашого чеклиста готовності до запуску.
+
+2. **Порівняльний експеримент**: Оберіть помірно складний новий проєкт. Підхід А: дозвольте агенту одночасно ініціалізуватися і виконати першу реалізацію. Підхід Б: витратьте одну сесію на виділену ініціалізацію, починайте реалізацію в сесії 2. Після 4 сесій порівняйте час від початку до першого тесту, що пройшов, витрати на відновлення роботи та відсоток завершення функцій.
+
+3. **Чеклист прийняття ініціалізації**: Розробіть чеклист прийняття ініціалізації для вашого проєкту. Нехай нова сесія агента виконає кожен пункт чеклиста та зафіксує, які пройшли, а які ні. Пункти, що не пройшли, — це місця, де ваш harness потребує зміцнення.
diff --git a/docs/uk/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md b/docs/uk/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md
new file mode 100644
index 0000000..a71bfa0
--- /dev/null
+++ b/docs/uk/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md
@@ -0,0 +1,8 @@
+# Код до лекції 07
+
+Використовуйте цю теку для прикладів:
+
+- одноразових невдач
+- надмірно великих промптів задач
+- поступового формування задач
+- структурованих поверхонь функцій
diff --git a/docs/uk/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md b/docs/uk/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md
new file mode 100644
index 0000000..d864a26
--- /dev/null
+++ b/docs/uk/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md
@@ -0,0 +1,6 @@
+# Шаблон наступної задачі
+
+- Поточна функція найвищого пріоритету:
+- Чому ця функція наступна:
+- Що вважається виконаним:
+- Що не можна змінювати під час цього кроку:
diff --git a/docs/uk/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md b/docs/uk/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md
new file mode 100644
index 0000000..370355f
--- /dev/null
+++ b/docs/uk/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md
@@ -0,0 +1,17 @@
+# Приклад поверхні меж
+
+Задача:
+
+- Додати індексування до Electron-застосунку знань
+
+Погана форма меж:
+
+- «Реалізувати індексування»
+
+Краща форма меж:
+
+- Парсити імпортовані документи
+- Розбивати документи на фрагменти
+- Зберігати метадані фрагментів
+- Відображати статус індексування в UI
+- Додати дію повторного індексування
diff --git a/docs/uk/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts b/docs/uk/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts
new file mode 100644
index 0000000..c587a1d
--- /dev/null
+++ b/docs/uk/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts
@@ -0,0 +1,151 @@
+/**
+ * scope-tracker.ts
+ *
+ * Reads a feature list and a change log. Enforces single-active-feature
+ * policy. Given a log of changes, flags any changes outside the active
+ * feature scope. Demonstrates how scope drift happens and how the tracker
+ * catches it.
+ *
+ * Run: npx tsx docs/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface Feature {
+ id: string;
+ name: string;
+ status: "active" | "pending" | "done";
+}
+
+interface ChangeLogEntry {
+ step: number;
+ file: string;
+ description: string;
+ featureId: string; // The feature this change claims to belong to
+}
+
+// ---------------------------------------------------------------------------
+// Sample data
+// ---------------------------------------------------------------------------
+
+const features: Feature[] = [
+ { id: "F-001", name: "Search endpoint", status: "active" },
+ { id: "F-002", name: "Delete endpoint", status: "pending" },
+ { id: "F-003", name: "Rate limiting", status: "pending" },
+ { id: "F-004", name: "User dashboard", status: "pending" },
+];
+
+// A realistic change log where the agent gradually drifts from the active feature
+const changeLog: ChangeLogEntry[] = [
+ { step: 1, file: "src/routes/search.ts", description: "Add search route handler", featureId: "F-001" },
+ { step: 2, file: "src/routes/search.ts", description: "Add query parameter validation", featureId: "F-001" },
+ { step: 3, file: "src/routes/search.ts", description: "Add search results pagination", featureId: "F-001" },
+ { step: 4, file: "src/routes/delete.ts", description: "Add delete route handler", featureId: "F-002" }, // DRIFT
+ { step: 5, file: "src/middleware/rate-limit.ts", description: "Add rate limiter middleware", featureId: "F-003" }, // DRIFT
+ { step: 6, file: "src/routes/search.ts", description: "Integrate rate limiter into search", featureId: "F-001" },
+ { step: 7, file: "src/dashboard/ui.tsx", description: "Create dashboard layout component", featureId: "F-004" }, // DRIFT
+ { step: 8, file: "src/routes/search.ts", description: "Add search response formatting", featureId: "F-001" },
+ { step: 9, file: "src/routes/delete.ts", description: "Add delete confirmation logic", featureId: "F-002" }, // DRIFT
+ { step: 10, file: "src/routes/search.ts", description: "Add search tests", featureId: "F-001" },
+];
+
+// ---------------------------------------------------------------------------
+// Scope tracker
+// ---------------------------------------------------------------------------
+
+interface ScopeCheckResult {
+ step: number;
+ file: string;
+ description: string;
+ featureId: string;
+ inScope: boolean;
+ activeFeature: string;
+}
+
+function trackScope(
+ featureList: Feature[],
+ changes: ChangeLogEntry[]
+): ScopeCheckResult[] {
+ const activeFeatures = featureList.filter((f) => f.status === "active");
+ const activeIds = new Set(activeFeatures.map((f) => f.id));
+ const activeNames = activeFeatures.map((f) => f.name).join(", ");
+
+ return changes.map((change) => ({
+ step: change.step,
+ file: change.file,
+ description: change.description,
+ featureId: change.featureId,
+ inScope: activeIds.has(change.featureId),
+ activeFeature: activeNames,
+ }));
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function run(): void {
+ const results = trackScope(features, changeLog);
+
+ console.log("\n" + "=".repeat(100));
+ console.log(" SCOPE TRACKER -- Single Active Feature Enforcement");
+ console.log("=".repeat(100));
+
+ console.log("\n Active feature: " + features.filter((f) => f.status === "active").map((f) => `${f.id} (${f.name})`).join(", "));
+ console.log(" Pending features: " + features.filter((f) => f.status === "pending").map((f) => `${f.id} (${f.name})`).join(", "));
+
+ // Detailed change log
+ console.log("\n" + "-".repeat(100));
+ const header = `| ${pad("Step", 5)}| ${pad("File", 35)}| ${pad("Description", 40)}| ${pad("Feature", 8)}| ${pad("In Scope", 10)}|`;
+ const sep = `|${"-".repeat(7)}|${"-".repeat(37)}|${"-".repeat(42)}|${"-".repeat(10)}|${"-".repeat(12)}|`;
+ console.log(header);
+ console.log(sep);
+
+ let inScopeCount = 0;
+ let driftCount = 0;
+
+ for (const r of results) {
+ const scopeLabel = r.inScope ? "OK" : "DRIFT";
+ if (r.inScope) inScopeCount++;
+ else driftCount++;
+
+ const marker = r.inScope ? " " : ">>";
+ console.log(`${marker}| ${pad(String(r.step), 5)}| ${pad(r.file, 35)}| ${pad(r.description, 40)}| ${pad(r.featureId, 8)}| ${pad(scopeLabel, 10)}|`);
+ }
+
+ // Summary
+ console.log("\n" + "=".repeat(100));
+ console.log(" SCOPE DRIFT SUMMARY");
+ console.log("=".repeat(100) + "\n");
+
+ const sHeader = `| ${pad("Metric", 40)}| ${pad("Value", 15)}|`;
+ const sSep = `|${"-".repeat(42)}|${"-".repeat(17)}|`;
+ console.log(sHeader);
+ console.log(sSep);
+ console.log(`| ${pad("Total changes", 40)}| ${pad(String(results.length), 15)}|`);
+ console.log(`| ${pad("Changes within active scope (F-001)", 40)}| ${pad(String(inScopeCount), 15)}|`);
+ console.log(`| ${pad("Changes outside active scope (DRIFT)", 40)}| ${pad(String(driftCount), 15)}|`);
+ console.log(`| ${pad("Features touched (total)", 40)}| ${pad(String(new Set(results.map((r) => r.featureId)).size), 15)}|`);
+
+ // Drift detail
+ const driftFeatures = [...new Set(results.filter((r) => !r.inScope).map((r) => r.featureId))];
+ if (driftFeatures.length > 0) {
+ console.log("\n DRIFTED FEATURES:");
+ for (const fid of driftFeatures) {
+ const feat = features.find((f) => f.id === fid);
+ const driftChanges = results.filter((r) => r.featureId === fid);
+ console.log(` ${fid} (${feat?.name}): ${driftChanges.length} unauthorized changes`);
+ }
+ }
+
+ console.log("\n Without a scope tracker, the agent silently worked on " + driftFeatures.length + " unrelated features.");
+ console.log(" The tracker catches this drift and enforces the single-active-feature policy.\n");
+}
+
+run();
diff --git a/docs/uk/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/uk/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
new file mode 100644
index 0000000..8bf000f
--- /dev/null
+++ b/docs/uk/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -0,0 +1,132 @@
+[中文版 →](../../../zh/lectures/lecture-07-why-agents-overreach-and-under-finish/)
+
+> Приклади коду: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/uk/lectures/lecture-07-why-agents-overreach-and-under-finish/code/)
+> Практичний проєкт: [Проєкт 04. Використання зворотного зв'язку runtime для коригування поведінки агента](./../../projects/project-04-incremental-indexing/index.md)
+
+# Лекція 07. Встановіть чіткі межі задач для агентів
+
+Ви кажете Claude Code «додай автентифікацію користувачів до цього проєкту», і він починає змінювати схему бази даних, писати маршрути, змінювати компоненти фронтенду і — заодно — рефакторити middleware для обробки помилок. Через дві години перевіряєте: 12 змінених файлів, 800 рядків нового коду, і жодна функція не працює наскрізь.
+
+Агенти від природи схильні «зробити трохи більше» — бачать суміжні речі і просто вирішують їх по дорозі. Проблема в тому, що надто велика кількість одночасних справ майже гарантовано призводить до того, що жодна з них не буде зроблена добре.
+
+В інженерному блозі Anthropic «Effective harnesses for long-running agents» прямо сказано: коли промпти надто широкі, агенти схильні «починати кілька речей одночасно», а не «спочатку завершувати одну». Практики розробки Codex від OpenAI виявили те саме — задачі без явного контролю меж мають різко нижчий відсоток завершення. Це не проблема моделі — це проблема harness. Ви не провели межу.
+
+## Увага — скінченний ресурс
+
+Це не метафора — це математика. Припустимо, ємність контексту агента дорівнює C, і він активує k задач одночасно. Кожна задача отримує в середньому C/k ресурсів міркування. Коли C/k падає нижче мінімального порогу, необхідного для завершення однієї задачі, жодна з них не виконується до кінця.
+
+Реальна поведінка Claude Code показова. Скажіть йому «додай реєстрацію користувачів», і він може:
+
+1. Створити модель User
+2. Написати маршрут реєстрації
+3. Помітити, що потрібна email-верифікація, і додати поштовий сервіс
+4. Побачити, що паролі потребують хешування, і підключити bcrypt
+5. Помітити, що обробка помилок непослідовна, і зробити рефакторинг глобального middleware для помилок
+6. Побачити, що структура тестових файлів безладна, і переорганізувати директорію
+
+Шість кроків — і кожен наполовину зроблений. Жодної наскрізної верифікації, складне зв'язування між напівготовим кодом, а наступна сесія, що підхопить уламки, буде повністю розгублена.
+
+Експериментальні дані Anthropic це підтверджують безпосередньо: агенти, що використовують стратегію «маленького наступного кроку» (еквівалент WIP=1), показують на 37% вищий відсоток завершення задач, ніж агенти з широкими промптами. Цікавіше те, що кількість рядків коду, згенерованих агентами, слабко негативно корелює з фактичним завершенням функцій — більше написаного коду, менше завершених функцій. Захопити більше, ніж можеш з'їсти, — доведено даними.
+
+## Робочий процес WIP=1
+
+```mermaid
+flowchart LR
+ Queue["Feature queue"] --> Pick["Pick exactly one task"]
+ Pick --> Active["Only one active item"]
+ Active --> Verify["Run end-to-end verification"]
+ Verify -->|pass| Commit["Commit and unlock next task"]
+ Verify -->|fail| Active
+ Commit --> Queue
+```
+
+```mermaid
+flowchart TB
+ Budget["Available reasoning budget = C"] --> One["WIP = 1<br/>C / 1 per task"]
+ Budget --> Many["WIP = 5<br/>C / 5 per task"]
+
+ One --> Finish["One feature reaches passing state"]
+ Many --> Partial["Five partial implementations"]
+ Partial --> VCR["Low verified completion rate<br/>high rework next session"]
+```
+
+## Ключові поняття
+
+- **Надмірне охоплення (Overreach)**: Агент активує в одній сесії більше задач, ніж оптимально. Це не суб'єктивно — це вимірювано: виконувати 5 функцій з 0 наскрізних перевірок є надмірним охопленням.
+- **Незавершення (Under-finish)**: Відношення задач, що пройшли наскрізну верифікацію, до всіх активованих задач падає нижче порогу. Код написаний, але тести не проходять — це незавершення.
+- **Ліміт WIP (Work-in-Progress Limit)**: З методології Kanban. Основна ідея: обмежити кількість задач, що виконуються одночасно. Для агентів WIP=1 є найбезпечнішим значенням за замовчуванням — завершіть одне перед початком наступного.
+- **Доказ завершення (Completion Evidence)**: Верифікована умова, яку задача має задовольнити, щоб перейти зі стану «в роботі» до «завершено». Без цього агенти замінюють «код виглядає добре» на «поведінка проходить тести».
+- **Поверхня меж (Scope Surface)**: Структура DAG, де кожен вузол — одиниця роботи, а ребра — залежності. Допустимі стани: not_started, active, blocked, passing.
+- **Тиск завершення (Completion Pressure)**: Обмежувальна сила, яку harness чинить через ліміти WIP та вимоги до доказів завершення, змушуючи агента завершити поточну задачу перед початком нової.
+
+## Надмірне охоплення і незавершення — дві сторони одної монети
+
+Ці дві проблеми не є незалежними — вони підсилюють одна одну. Надмірне охоплення розпорошує увагу, розпорошена увага спричиняє незавершення, а напівготовий код, що залишається, збільшує складність системи, що ще більше провокує надмірне охоплення в наступній задачі. Замкнене коло.
+
+У термінах Kanban: закон Літтла каже нам L = lambda * W. Якщо обсяг незавершеної роботи L зависокий (надто багато справ одночасно), час виконання W кожної задачі неминуче зростає. Для агентів це означає, що кожна функція потребує більше часу від початку до верифікованого завершення, а ймовірність невдачі зростає.
+
+Це давня проблема і в людському світі. Стів МакКоннелл задокументував у «Rapid Development», що повзуча зміна вимог є головною причиною провалу проєктів. Але люди принаймні мають інтуїцію «я зробив достатньо». У агентів її немає. Генерація наступної ідеї коштує моделі майже нічого — написати «дозвольте я заодно виправлю це» ледь потребує додаткових токенів, але кожна додаткова модифікація розпорошує увагу агента.
+
+## Як робити правильно
+
+### 1. Застосовуйте WIP=1
+
+Це найпрямолінійніший і найефективніший метод. У вашому harness явно скажіть агенту: **в будь-який момент лише одна задача може мати статус «активна».** У CLAUDE.md для Claude Code або AGENTS.md для Codex напишіть:
+
+```
+## Work Rules
+- Work on one feature at a time
+- Only start the next feature after the current one passes end-to-end verification
+- Don't "also refactor" feature B while implementing feature A
+```
+
+### 2. Визначте явний доказ завершення для кожної задачі
+
+Завершено — це не «код написаний», а «верифікація поведінки пройшла». У вашому списку функцій кожен запис потребує команди верифікації:
+
+```
+F01: User Registration
+ Verification: curl -X POST /api/register -d '{"email":"[email protected]","password":"123456"}' | jq .status == 201
+ State: passing
+```
+
+### 3. Винесіть поверхню меж назовні
+
+Використовуйте машинозчитуваний файл (JSON або Markdown) для запису всіх станів задач. Будь-яка нова сесія може прочитати цей файл і одразу знати: яка задача активна? Яка поведінка вважається завершеною? Які верифікації пройдено?
+
+### 4. Відстежуйте відсоток верифікованого завершення
+
+Harness має постійно відстежувати VCR (Verified Completion Rate) = верифіковані задачі / активовані задачі. Блокуйте активацію нових задач, коли VCR < 1.0.
+
+## Реальний кейс
+
+Проєкт REST API з 8 функціями, порівняння двох стратегій:
+
+**Режим без обмежень**: Агент активує 5 функцій одночасно в сесії 1. Продукує ~800 рядків у 12 файлах. Відсоток проходження наскрізних тестів: 20% — працює лише реєстрація користувачів. Решта 4 функції: схема бази даних створена, але відсутня логіка валідації; маршрути визначені, але повертають неправильні формати відповідей. До кінця сесії 3 завершено лише 3 з 8 функцій.
+
+**Режим WIP=1**: Агент працює лише над реєстрацією користувачів у сесії 1. Продукує ~200 рядків у 4 файлах. Наскрізні тести: 100% проходять. Фіксує чисту, верифіковану реалізацію. До кінця сесії 4 завершено 7 з 8 функцій (8-а заблокована зовнішньою залежністю).
+
+Підсумок: менше загального коду (800 проти 1200 рядків), але ефективніший. Відсоток завершення: 87,5% проти 37,5%.
+
+## Ключові висновки
+
+- **WIP=1 — це безпечне значення за замовчуванням для harness агентів** — завершіть одне, потім беріться за наступне; не намагайтеся розпаралелювати.
+- **Доказ завершення має бути виконуваним** — «код виглядає добре» не рахується; «curl повертає 201» — рахується.
+- **Поверхня меж має бути винесена у файл** — не просто згадана в розмові, а зафіксована в машинозчитуваному форматі в репозиторії.
+- **Надмірне охоплення і незавершення симбіотичні** — вирішення одного вирішує інше.
+- **«Роби менше, але завершуй» завжди перемагає «роби більше, але залишай напівготовим»** — рядки коду агента та відсоток завершення функцій негативно корелюють. Якість завжди перемагає кількість.
+
+## Додаткова література
+
+- [Effective harnesses for long-running agents - Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — інженерний блог Anthropic, детальне обговорення стратегії «маленького наступного кроку»
+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — повний розгляд harness engineering від OpenAI
+- [Kanban: Successful Evolutionary Change - David Anderson](https://www.goodreads.com/book/show/1070822.Kanban) — класичне джерело про ліміти WIP
+- [Rapid Development - Steve McConnell](https://www.goodreads.com/book/show/125171.Rapid_Development) — емпіричні дані про повзучу зміну вимог як головну причину провалу проєктів
+
+## Вправи
+
+1. **Атомізація задач**: Візьміть широку вимогу (наприклад, «реалізуй систему управління користувачами») і розбийте її на щонайменше 5 атомарних одиниць роботи. Для кожної одиниці вкажіть: (а) опис однієї поведінки, (б) виконувану команду верифікації, (в) залежності. Перевірте, чи задовольняє розбивка обмеження WIP=1.
+
+2. **Порівняльний експеримент**: Запустіть один і той самий проєкт двічі — без обмежень і з примусовим WIP=1. Порівняйте відсоток верифікованого завершення, загальну кількість рядків коду та частку ефективного коду.
+
+3. **Аудит доказів завершення**: Перегляньте результати нещодавнього запуску агента, класифікуючи кожну зміну коду як «завершена поведінка», «незавершена поведінка» або «каркас». Додайте відсутні команди верифікації для кожної незавершеної поведінки.
diff --git a/docs/uk/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts b/docs/uk/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts
new file mode 100644
index 0000000..52d6a2b
--- /dev/null
+++ b/docs/uk/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts
@@ -0,0 +1,218 @@
+/**
+ * feature-list-validator.ts
+ *
+ * Reads a feature_list.json, validates its schema, and checks for features
+ * marked "pass" without verification evidence. Outputs a structured report.
+ * Can run against any project directory that has a feature_list.json.
+ *
+ * Usage:
+ * npx tsx docs/lectures/lecture-08.../code/feature-list-validator.ts [path-to-dir]
+ * (defaults to the directory containing this script)
+ *
+ * Run: npx tsx docs/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface FeatureEntry {
+ id?: string;
+ category?: string;
+ description?: string;
+ verification?: string[];
+ passes?: boolean;
+ // Allow unknown fields for flexibility
+ [key: string]: unknown;
+}
+
+interface ValidationResult {
+ featureId: string;
+ schemaValid: boolean;
+ schemaErrors: string[];
+ hasVerification: boolean;
+ markedPassWithoutEvidence: boolean;
+ passes: boolean;
+ verificationCount: number;
+}
+
+// ---------------------------------------------------------------------------
+// Schema validation
+// ---------------------------------------------------------------------------
+
+function validateSchema(entry: FeatureEntry, index: number): string[] {
+ const errors: string[] = [];
+ const label = entry.id ?? `entry ${index + 1}`;
+
+ if (!entry.id || typeof entry.id !== "string") {
+ errors.push(`[${label}] Missing or invalid 'id' field`);
+ }
+ if (!entry.category || typeof entry.category !== "string") {
+ errors.push(`[${label}] Missing or invalid 'category' field`);
+ }
+ if (!entry.description || typeof entry.description !== "string") {
+ errors.push(`[${label}] Missing or invalid 'description' field`);
+ }
+ if (entry.verification !== undefined && !Array.isArray(entry.verification)) {
+ errors.push(`[${label}] 'verification' must be an array if present`);
+ }
+ if (entry.passes !== undefined && typeof entry.passes !== "boolean") {
+ errors.push(`[${label}] 'passes' must be a boolean if present`);
+ }
+
+ return errors;
+}
+
+// ---------------------------------------------------------------------------
+// Evidence validation
+// ---------------------------------------------------------------------------
+
+function checkEvidence(entry: FeatureEntry): {
+ hasVerification: boolean;
+ markedPassWithoutEvidence: boolean;
+} {
+ const hasVerification = Array.isArray(entry.verification) && entry.verification.length > 0;
+ const markedPassWithoutEvidence = entry.passes === true && !hasVerification;
+
+ return { hasVerification, markedPassWithoutEvidence };
+}
+
+// ---------------------------------------------------------------------------
+// Process feature list
+// ---------------------------------------------------------------------------
+
+function processFeatureList(entries: FeatureEntry[]): ValidationResult[] {
+ return entries.map((entry, index) => {
+ const schemaErrors = validateSchema(entry, index);
+ const evidence = checkEvidence(entry);
+
+ return {
+ featureId: (entry.id as string) ?? `entry-${index + 1}`,
+ schemaValid: schemaErrors.length === 0,
+ schemaErrors,
+ hasVerification: evidence.hasVerification,
+ markedPassWithoutEvidence: evidence.markedPassWithoutEvidence,
+ passes: entry.passes === true,
+ verificationCount: Array.isArray(entry.verification) ? entry.verification.length : 0,
+ };
+ });
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function run(): void {
+ // Resolve target directory
+ const scriptDir = path.dirname(new URL(import.meta.url).pathname);
+ const targetDir = process.argv[2]
+ ? path.resolve(process.argv[2])
+ : scriptDir;
+
+ const filePath = path.join(targetDir, "feature_list.json");
+
+ console.log("\n" + "=".repeat(90));
+ console.log(" FEATURE LIST VALIDATOR");
+ console.log("=".repeat(90));
+ console.log(` Reading: ${filePath}\n`);
+
+ if (!fs.existsSync(filePath)) {
+ console.error(` ERROR: feature_list.json not found at ${filePath}`);
+ console.error(" Usage: npx tsx feature-list-validator.ts [path-to-directory-containing-feature_list.json]\n");
+ process.exit(1);
+ }
+
+ let entries: FeatureEntry[];
+ try {
+ const raw = fs.readFileSync(filePath, "utf-8");
+ entries = JSON.parse(raw);
+ } catch (err) {
+ console.error(` ERROR: Could not parse feature_list.json: ${err}`);
+ process.exit(1);
+ }
+
+ if (!Array.isArray(entries)) {
+ console.error(" ERROR: feature_list.json must contain a JSON array at the top level.");
+ process.exit(1);
+ }
+
+ // For demo purposes, also validate an extended test set
+ const demoEntries: FeatureEntry[] = [
+ ...entries,
+ {
+ id: "qna-002",
+ category: "import",
+ description: "User can import a PDF document.",
+ verification: ["Upload a PDF file", "Verify it appears in the document list"],
+ passes: true,
+ },
+ {
+ id: "qna-003",
+ category: "grounded_qa",
+ description: "System hallucination rate is below 5%.",
+ verification: [], // Empty -- no evidence
+ passes: true, // Marked as pass WITHOUT evidence
+ },
+ {
+ id: "missing-fields",
+ // Missing 'category' and 'description'
+ passes: true,
+ } as FeatureEntry,
+ ];
+
+ const results = processFeatureList(demoEntries);
+
+ // Print report
+ const header = `| ${pad("Feature ID", 14)}| ${pad("Schema", 8)}| ${pad("Passes", 7)}| ${pad("Verifications", 14)}| ${pad("Evidence?", 12)}| Notes`;
+ const sep = `|${"-".repeat(16)}|${"-".repeat(10)}|${"-".repeat(9)}|${"-".repeat(16)}|${"-".repeat(14)}|${"-".repeat(30)}`;
+ console.log(header);
+ console.log(sep);
+
+ for (const r of results) {
+ const schemaLabel = r.schemaValid ? "OK" : "INVALID";
+ const passesLabel = r.passes ? "PASS" : "FAIL";
+ const evidenceLabel = r.hasVerification ? "Present" : "MISSING";
+ const notes = r.markedPassWithoutEvidence
+ ? "FLAGGED: passes without evidence!"
+ : r.schemaErrors.length > 0
+ ? r.schemaErrors[0]
+ : "";
+
+ const marker = r.markedPassWithoutEvidence ? ">>" : r.schemaValid ? " " : "!!";
+ console.log(
+ `${marker}| ${pad(r.featureId, 14)}| ${pad(schemaLabel, 8)}| ${pad(passesLabel, 7)}| ${pad(String(r.verificationCount), 14)}| ${pad(evidenceLabel, 12)}| ${notes}`
+ );
+ }
+
+ // Summary
+ const total = results.length;
+ const schemaOk = results.filter((r) => r.schemaValid).length;
+ const passing = results.filter((r) => r.passes).length;
+ const flagged = results.filter((r) => r.markedPassWithoutEvidence).length;
+ const withEvidence = results.filter((r) => r.hasVerification).length;
+
+ console.log("\n" + "-".repeat(90));
+ console.log(" SUMMARY");
+ console.log("-".repeat(90));
+ console.log(` Total features: ${total}`);
+ console.log(` Schema valid: ${schemaOk}/${total}`);
+ console.log(` Marked as passing: ${passing}/${total}`);
+ console.log(` With verification evidence: ${withEvidence}/${total}`);
+ console.log(` Flagged (pass without evidence): ${flagged}`);
+
+ if (flagged > 0) {
+ console.log(`\n WARNING: ${flagged} feature(s) marked as "pass" without any verification evidence.`);
+ console.log(" These features need verification before they can be trusted.\n");
+ } else {
+ console.log("\n All passing features have verification evidence. Feature list is healthy.\n");
+ }
+}
+
+run();
diff --git a/docs/uk/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json b/docs/uk/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json
new file mode 100644
index 0000000..8b973e3
--- /dev/null
+++ b/docs/uk/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json
@@ -0,0 +1,15 @@
+[
+ {
+ "id": "qna-001",
+ "category": "grounded_qa",
+ "description": "User can ask a question about an imported document and receive an answer with visible citations.",
+ "verification": [
+ "Import a markdown document",
+ "Open the Q&A panel",
+ "Ask a question about known content",
+ "Verify the answer is returned",
+ "Verify one or more citations are displayed"
+ ],
+ "passes": false
+ }
+]
diff --git a/docs/uk/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md b/docs/uk/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md
new file mode 100644
index 0000000..881c2d9
--- /dev/null
+++ b/docs/uk/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md
@@ -0,0 +1,8 @@
+# Код до лекції 08
+
+Використовуйте цю теку для прикладів:
+
+- вентиль стану passing
+- наскрізна верифікація
+- слабкі vs строгі критерії завершення
+- приклади циклу оцінювача
diff --git a/docs/uk/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md b/docs/uk/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md
new file mode 100644
index 0000000..e903948
--- /dev/null
+++ b/docs/uk/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md
@@ -0,0 +1,8 @@
+# Політика вентиля стану passing
+
+Функція може перейти з `passes: false` у `passes: true` лише якщо:
+
+- очікуваний робочий процес був виконаний
+- свідчення успіху зафіксовані
+- у протестованому шляху немає блокуючих помилок
+- реалізація не залишає застосунок у зламаному або неоднозначному стані
diff --git a/docs/uk/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/uk/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
new file mode 100644
index 0000000..071d7c0
--- /dev/null
+++ b/docs/uk/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -0,0 +1,142 @@
+[中文版 →](../../../zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/)
+
+> Приклади коду: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/uk/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/)
+> Практичний проєкт: [Проєкт 04. Зворотний зв'язок під час виконання та контроль обсягу](./../../projects/project-04-incremental-indexing/index.md)
+
+# Лекція 08. Використовуйте списки функціональності для обмеження дій агента
+
+Ви просите агента побудувати e-commerce сайт. Після завершення він повідомляє: «готово». Ви дивитесь на код — автентифікація користувачів працює, але кнопка оформлення замовлення в кошику нічого не робить, а платіжний потік взагалі не підключений. Де щось пішло не так? Ви ніколи не пояснили, що означає «готово», тому агент застосував власний стандарт: «я написав багато коду, і він виглядає достатньо повним».
+
+У більшості людей списки функціональності асоціюються лише з нотатками — записати, щоб не забути, а потім відкласти вбік. Але у світі harness список функціональності — це не нотатка для людини. Це фундаментальна структура, на якій побудований увесь harness. Планувальник спирається на нього, щоб вибирати завдання, верифікатор — щоб оцінювати завершеність, а генератор звітів про передачу — щоб формувати підсумки. Без нього ці компоненти не мають спільного консенсусу.
+
+Anthropic і OpenAI наголошують: **артефакти мають бути зовнішніми.** Стан функціональності повинен зберігатися у машиночитаному файлі в репозиторії, а не в неструктурованому тексті розмови.
+
+## Агенти не знають, що означає «готово»
+
+Ні Claude Code, ні Codex автоматично не розуміють, що ви маєте на увазі під «готово». Ви кажете «додай функцію кошика», і модель може інтерпретувати це як «напиши компонент Cart і метод addToCart». Але ви мали на увазі «користувач може переглядати товари, додавати до кошика і завершити оформлення замовлення наскрізно».
+
+Цей розрив у розумінні зберігається без списку функціональності. Агент застосовує власний неявний стандарт — зазвичай «код не має очевидних синтаксичних помилок». Вам потрібна наскрізна поведінкова верифікація. Без списку обидві сторони ніколи не дійдуть згоди щодо того, що означає «готово».
+
+Погляньте на цей типовий запис прогресу:
+
+```
+Did user auth, shopping cart mostly done, still need payments
+```
+
+Чи може новий сеанс агента відповісти на ці запитання з цієї нотатки? Що означає «mostly done»? Які тести пройшов кошик? Що блокує платежі? Відповідь на всі — «ніхто не знає».
+
+Результат: новий сеанс витрачає 20 хвилин на з'ясування стану проєкту і може зрештою заново реалізувати вже завершені функції. За інженерними даними Anthropic, хороші записи прогресу скорочують час діагностики на початку сеансу на 60–80%.
+
+## Машина станів функціональності
+
+```mermaid
+flowchart LR
+ Feature["One feature row"] --> Behavior["Behavior<br/>e.g.: POST /cart/items returns 201"]
+ Feature --> Check["Verification command<br/>the exact check to run"]
+ Feature --> State["State<br/>not_started / active / blocked / passing"]
+
+ Behavior --> Complete["All three fields present<br/>the feature row is usable"]
+ Check --> Complete
+ State --> Complete
+```
+
+```mermaid
+flowchart LR
+ List["feature_list.json / features.md"] --> Scheduler["Pick the next not_started item"]
+ Scheduler --> Agent["Agent works on that one item"]
+ Agent --> Verifier["Run that item's verification command"]
+ Verifier -->|pass| Passing["Mark it passing<br/>and attach evidence"]
+ Verifier -->|fail| Active["Keep it active"]
+ Verifier -->|dependency issue| Blocked["Mark it blocked"]
+ Passing --> Handoff["Update handoff note<br/>and current progress"]
+ Active --> Agent
+```
+
+## Основні концепції
+
+- **Списки функціональності — це harness-примітиви**: не «необов'язкові інструменти планування», а фундаментальні структури даних, від яких залежать усі інші компоненти harness. Планувальник, верифікатор і генератор звітів про передачу — усі вони читають список функціональності для своєї роботи.
+- **Потрійна структура**: кожен елемент списку містить три складові: `(опис поведінки, команда верифікації, поточний стан)`. Поведінка повідомляє агенту, що робити; верифікація — що вважається виконаним; стан — де знаходяться справи. Відсутність будь-якого елемента робить запис неповним.
+- **Модель машини станів**: кожен елемент функціональності має чотири стани — `not_started`, `active`, `blocked`, `passing`. Переходи між станами контролює harness, агент не може їх змінювати довільно.
+- **Вентиль стану passing**: єдиний спосіб перевести функцію з `active` у `passing` — успішне виконання команди верифікації. Цей перехід незворотний — після `passing` повернення неможливе.
+- **Єдине джерело правди**: уся інформація про «що потрібно зробити» повинна походити з одного списку функціональності. Жодних суперечностей між списком і історією розмови.
+- **Зворотний тиск**: кількість функцій, що ще не перейшли у `passing`, — це тиск, який harness чинить на агента. Нульовий тиск = проєкт завершено.
+
+## Чому списки функціональності мають бути «примітивами»
+
+Документи призначені для читання людьми; примітиви — для виконання системами. Документи можна ігнорувати; примітиви не можна обійти.
+
+Уявіть це як обмеження тригерів бази даних на противагу перевіркам на рівні застосунку: перші виконуються рушієм бази даних — жоден SQL не може їх пропустити. Другі залежать від коректності коду застосунку і можуть бути випадково обійдені. Списки функціональності як harness-примітиви відіграють ту саму роль, що й обмеження на рівні бази даних, — агент не може їх обійти.
+
+Конкретно, список функціональності обслуговує чотири компоненти harness:
+
+1. **Планувальник**: читає стани, вибирає наступну функцію зі статусом `not_started`.
+2. **Верифікатор**: виконує команди верифікації, вирішує, чи дозволяти переходи між станами.
+3. **Генератор звітів про передачу**: автоматично формує підсумки передачі сеансу зі списку функціональності.
+4. **Трекер прогресу**: підраховує розподіл станів, надає метрики стану проєкту.
+
+## Як це робити
+
+### 1. Визначте мінімальний формат списку функціональності
+
+Складна система не потрібна — підійде структурований файл Markdown або JSON. Головне — кожен запис повинен мати потрійну структуру:
+
+```json
+{
+ "id": "F03",
+ "behavior": "POST /cart/items with {product_id, quantity} returns 201",
+ "verification": "curl -X POST http://localhost:3000/api/cart/items -H 'Content-Type: application/json' -d '{\"product_id\":1,\"quantity\":2}' | jq .status == 201",
+ "state": "passing",
+ "evidence": "commit abc123, test output log"
+}
+```
+
+### 2. Дозвольте harness контролювати переходи між станами
+
+Агент не може безпосередньо змінити стан функції на `passing`. Він може лише надіслати запит на верифікацію. Harness виконує команду верифікації і вирішує, чи дозволяти перехід. Це і є «вентиль стану passing».
+
+### 3. Запишіть правила у CLAUDE.md
+
+```
+## Feature List Rules
+- Feature list file: /docs/features.md
+- Only one feature active at a time
+- Verification command must pass before marking as passing
+- Don't modify feature list states yourself — the verification script updates them automatically
+```
+
+### 4. Калібруйте гранулярність
+
+Кожен елемент функціональності має бути розрахований на «виконання за один сеанс». Надто широкий — не завершиться; надто вузький — зростають накладні витрати на управління. «Користувач може додавати товари до кошика» — правильна гранулярність. «Реалізувати кошик» — надто широко. «Створити поле name у моделі Cart» — надто вузько.
+
+## Реальний кейс
+
+E-commerce платформа з 10 функціями. Порівняння двох підходів до відстеження:
+
+**Режим нотаток**: агент використовує неструктуровані нотатки для відстеження прогресу. Після 3 сеансів нотатки виглядають як «зробив автентифікацію і список товарів, кошик в основному готовий, але є баги, платежі не починались». Новий сеанс витрачає 20 хвилин на з'ясування стану і зрештою заново реалізує завершені функції.
+
+**Структурований режим**: кожна функція має чіткий стан і команду верифікації. Новий сеанс читає список функціональності і за 3 хвилини знає: F01–F05 — `passing`, F06 — `active` (в роботі), F07–F10 — `not_started`. Він продовжує безпосередньо з F06, без жодного повтору роботи.
+
+Кількісний результат: проєкти зі структурованими списками функціональності показують на 45% вищий рівень завершення функцій порівняно з довільним відстеженням, без жодних дублікатів реалізацій.
+
+## Ключові висновки
+
+- **Списки функціональності — це фундаментальна структура harness**, а не нотатки для людей. Від них залежать планувальник, верифікатор і генератор звітів про передачу.
+- **Кожен елемент функціональності повинен мати потрійну структуру**: опис поведінки + команда верифікації + поточний стан. Відсутність одного елемента робить його неповним.
+- **Переходи між станами контролює harness** — агент не може змінювати стани самостійно. Проходження верифікації — єдиний шлях до підвищення статусу.
+- **Список функціональності — єдине джерело правди проєкту** — уся інформація «що робити» походить з нього.
+- **Калібруйте гранулярність до «виконуваного за один сеанс».** Надто широкий — не завершиться; надто вузький — некерований.
+
+## Додаткове читання
+
+- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents) — явно визначає список функціональності як «ключову структуру даних» для контролю обсягу агента
+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — підкреслює принцип «екстерналізації артефактів»
+- [Design by Contract - Bertrand Meyer](https://www.goodreads.com/book/show/130439.Object_Oriented_Software_Construction) — принципи проєктування за контрактом, теоретична основа списків функціональності
+- [How Google Tests Software](https://www.goodreads.com/book/show/13563030-how-google-tests-software) — піраміда тестування та інженерні практики поведінкової специфікації
+
+## Вправи
+
+1. **Проєктування списку функціональності**: визначте мінімальну JSON-схему списку функціональності. Включіть: id, опис поведінки, команду верифікації, поточний стан, посилання на свідчення. Використайте її для опису реального проєкту з 5 функціями.
+
+2. **Порівняння строгості верифікації**: виберіть 3 функції та розробіть як «слабку» верифікацію (наприклад, «код без синтаксичних помилок»), так і «строгу» (наприклад, «наскрізний тест проходить»). Порівняйте рівень хибнопозитивних результатів за кожного підходу.
+
+3. **Аудит принципу єдиного джерела**: перевірте наявний проєкт агента на наявність інформації про обсяг, що суперечить списку функціональності (неявні вимоги в розмовах, TODO-коментарі в коді тощо). Розробіть план для об'єднання всієї інформації у списку функціональності.
diff --git a/docs/uk/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md b/docs/uk/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md
new file mode 100644
index 0000000..177badc
--- /dev/null
+++ b/docs/uk/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md
@@ -0,0 +1,6 @@
+# Чекліст чистого стану
+
+- Застосунок запускається без ручного відновлення
+- Поточний прогрес зафіксовано
+- Жодного незавершеного кроку імпорту або індексування не залишається без документації
+- Наступний агент може негайно запустити стандартний шлях запуску та верифікації
diff --git a/docs/uk/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md b/docs/uk/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md
new file mode 100644
index 0000000..a5ba1e1
--- /dev/null
+++ b/docs/uk/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md
@@ -0,0 +1,8 @@
+# Код до лекції 09
+
+Використовуйте цю теку для прикладів:
+
+- логи як зворотний зв'язок
+- видимість стану під час виконання
+- перевірки чистого стану
+- приклади відновлення
diff --git a/docs/uk/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts b/docs/uk/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts
new file mode 100644
index 0000000..fad1a3b
--- /dev/null
+++ b/docs/uk/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts
@@ -0,0 +1,241 @@
+/**
+ * victory-detector.ts
+ *
+ * Simulates an agent that claims task completion, then checks the claimed
+ * state against actual verification. Outputs: claimed vs actual, highlighting
+ * gaps between what the agent said and what's really true.
+ *
+ * Run: npx tsx docs/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface Task {
+ name: string;
+ claimedComplete: boolean;
+ checks: VerificationCheck[];
+}
+
+interface VerificationCheck {
+ description: string;
+ claimed: boolean; // What the agent says
+ actual: boolean; // What is actually true
+ severity: "critical" | "warning";
+}
+
+// ---------------------------------------------------------------------------
+// Simulated tasks with claimed vs actual states
+// ---------------------------------------------------------------------------
+
+const tasks: Task[] = [
+ {
+ name: "Add search endpoint",
+ claimedComplete: true,
+ checks: [
+ {
+ description: "Route handler exists",
+ claimed: true,
+ actual: true,
+ severity: "critical",
+ },
+ {
+ description: "Authentication middleware applied",
+ claimed: true,
+ actual: false, // Agent forgot auth
+ severity: "critical",
+ },
+ {
+ description: "Input validation added",
+ claimed: true,
+ actual: true,
+ severity: "critical",
+ },
+ {
+ description: "Unit tests written",
+ claimed: true,
+ actual: false, // Agent skipped tests
+ severity: "critical",
+ },
+ {
+ description: "Integration tests pass",
+ claimed: true,
+ actual: false, // No tests to run
+ severity: "critical",
+ },
+ {
+ description: "Documentation updated",
+ claimed: true,
+ actual: false, // Agent skipped docs
+ severity: "warning",
+ },
+ ],
+ },
+ {
+ name: "Fix pagination bug",
+ claimedComplete: true,
+ checks: [
+ {
+ description: "Bug reproduction case confirmed",
+ claimed: true,
+ actual: true,
+ severity: "critical",
+ },
+ {
+ description: "Root cause identified",
+ claimed: true,
+ actual: true,
+ severity: "critical",
+ },
+ {
+ description: "Fix applied",
+ claimed: true,
+ actual: true,
+ severity: "critical",
+ },
+ {
+ description: "Edge cases tested",
+ claimed: true,
+ actual: false, // Only happy path tested
+ severity: "warning",
+ },
+ {
+ description: "Regression tests added",
+ claimed: true,
+ actual: false,
+ severity: "critical",
+ },
+ ],
+ },
+ {
+ name: "Refactor auth module",
+ claimedComplete: true,
+ checks: [
+ {
+ description: "Old code removed",
+ claimed: true,
+ actual: false, // Old code still present
+ severity: "warning",
+ },
+ {
+ description: "All existing tests still pass",
+ claimed: true,
+ actual: false, // Two tests broke
+ severity: "critical",
+ },
+ {
+ description: "New auth flow works",
+ claimed: true,
+ actual: true,
+ severity: "critical",
+ },
+ {
+ description: "Migration guide written",
+ claimed: true,
+ actual: false,
+ severity: "warning",
+ },
+ ],
+ },
+];
+
+// ---------------------------------------------------------------------------
+// Verification
+// ---------------------------------------------------------------------------
+
+interface TaskVerification {
+ taskName: string;
+ claimedComplete: boolean;
+ actuallyComplete: boolean;
+ totalChecks: number;
+ claimedPassing: number;
+ actualPassing: number;
+ gaps: { description: string; severity: string }[];
+}
+
+function verifyTask(task: Task): TaskVerification {
+ const claimedPassing = task.checks.filter((c) => c.claimed).length;
+ const actualPassing = task.checks.filter((c) => c.actual).length;
+ const gaps = task.checks.filter((c) => c.claimed && !c.actual);
+
+ return {
+ taskName: task.name,
+ claimedComplete: task.claimedComplete,
+ actuallyComplete: gaps.length === 0,
+ totalChecks: task.checks.length,
+ claimedPassing,
+ actualPassing,
+ gaps: gaps.map((g) => ({ description: g.description, severity: g.severity })),
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function run(): void {
+ console.log("\n" + "=".repeat(90));
+ console.log(" VICTORY DETECTOR -- Claimed vs Actual Verification");
+ console.log("=".repeat(90));
+
+ const verifications = tasks.map(verifyTask);
+
+ for (const v of verifications) {
+ console.log("\n Task: " + v.taskName);
+ console.log(" " + "-".repeat(70));
+ console.log(` Agent claimed: ${v.claimedComplete ? "COMPLETE" : "NOT COMPLETE"}`);
+ console.log(` Actually is: ${v.actuallyComplete ? "COMPLETE" : "INCOMPLETE"}`);
+
+ if (!v.actuallyComplete) {
+ console.log(` MISMATCH: Agent declared victory but ${v.gaps.length} check(s) failed!`);
+ }
+
+ // Detailed checks for this task
+ const task = tasks.find((t) => t.name === v.taskName)!;
+ console.log("\n Check detail:");
+ const header = ` | ${pad("Check", 40)}| ${pad("Claimed", 9)}| ${pad("Actual", 9)}| ${pad("Gap?", 6)}|`;
+ const sep = ` |${"-".repeat(42)}|${"-".repeat(11)}|${"-".repeat(11)}|${"-".repeat(8)}|`;
+ console.log(header);
+ console.log(sep);
+
+ for (const check of task.checks) {
+ const claimedLabel = check.claimed ? "PASS" : "FAIL";
+ const actualLabel = check.actual ? "PASS" : "FAIL";
+ const gapLabel = check.claimed && !check.actual ? "GAP" : "";
+ const marker = gapLabel ? ">>" : " ";
+ console.log(`${marker}| ${pad(check.description, 40)}| ${pad(claimedLabel, 9)}| ${pad(actualLabel, 9)}| ${pad(gapLabel, 6)}|`);
+ }
+ }
+
+ // Overall summary
+ console.log("\n" + "=".repeat(90));
+ console.log(" OVERALL SUMMARY");
+ console.log("=".repeat(90) + "\n");
+
+ const sHeader = `| ${pad("Task", 28)}| ${pad("Claimed", 10)}| ${pad("Actual", 10)}| ${pad("Gaps", 6)}| ${pad("Accuracy", 10)}|`;
+ const sSep = `|${"-".repeat(30)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(8)}|${"-".repeat(12)}|`;
+ console.log(sHeader);
+ console.log(sSep);
+
+ for (const v of verifications) {
+ const accuracy = Math.round((v.actualPassing / v.totalChecks) * 100);
+ const cLabel = v.claimedComplete ? "Done" : "Pending";
+ const aLabel = v.actuallyComplete ? "Done" : "Incomplete";
+ console.log(`| ${pad(v.taskName, 28)}| ${pad(cLabel, 10)}| ${pad(aLabel, 10)}| ${pad(String(v.gaps.length), 6)}| ${pad(accuracy + "%", 10)}|`);
+ }
+
+ const totalGaps = verifications.reduce((s, v) => s + v.gaps.length, 0);
+ const falseVictories = verifications.filter((v) => v.claimedComplete && !v.actuallyComplete).length;
+
+ console.log("\n False victories: " + falseVictories + " of " + verifications.length + " tasks");
+ console.log(" Total undetected gaps: " + totalGaps);
+ console.log("\n The agent declared 'done' on every task, but verification reveals " + totalGaps + " unmet criteria.");
+ console.log(" Without explicit verification, premature victory declarations go unchecked.\n");
+}
+
+run();
diff --git a/docs/uk/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/uk/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
new file mode 100644
index 0000000..0a4a070
--- /dev/null
+++ b/docs/uk/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -0,0 +1,143 @@
+[中文版 →](../../../zh/lectures/lecture-09-why-agents-declare-victory-too-early/)
+
+> Приклади коду до цієї лекції: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/uk/lectures/lecture-09-why-agents-declare-victory-too-early/code/)
+> Практичне завдання: [Проєкт 05. Нехай агент верифікує власну роботу](./../../projects/project-05-grounded-qa-verification/index.md)
+
+# Лекція 09. Запобігання передчасному оголошенню перемоги агентами
+
+Ви просите агента реалізувати функцію «скидання пароля». Він змінює схему бази даних, пише API-ендпоінт, додає шаблон електронного листа, запускає юніт-тести (всі проходять) і впевнено повідомляє: «готово». Але коли ви насправді спробуєте запустити — посилання для скидання пароля не надсилається через відсутню конфігурацію поштового сервісу; міграція бази даних завершується на половині, залишаючи схему в суперечливому стані; а наскрізний потік жодного разу не виконувався.
+
+Це не поодинокий випадок. Класична стаття ICML 2017 року Guo et al. довела: **сучасні нейронні мережі систематично переоцінюють свою впевненість** — довіра, яку повідомляють моделі, значно вища за їхню фактичну точність. Агенти для написання коду на основі ШІ нічим не відрізняються. Вони «відчувають» завершеність, але насправді далекі від неї. Ваш harness повинен замінити «відчуття» агента зовнішньою верифікацією на основі виконання.
+
+## Слизький схил
+
+Передчасні оголошення про завершення майже завжди слідують одним і тим самим сценарієм: код виглядає нормально — синтаксис правильний, логіка здається розумною, статичний аналіз не показує очевидних помилок. Але harness не вимагає комплексної верифікації виконання, тому агент або взагалі не запускає код, або запускає лише часткові тести. Він виконує юніт-тести, але пропускає інтеграційні; запускає тести, але не перевіряє покриття. Зрештою «код виглядає добре» сприймається як свідчення того, що «функція завершена».
+
+Інформація втрачається на кожному кроці. Від специфікації завдання до реалізації коду та поведінки під час виконання — кожне перетворення може вносити упередженість, а кожна пропущена верифікація посилює інформаційну асиметрію.
+
+## Тришаровий контроль завершення
+
+```mermaid
+flowchart LR
+ Claim["Agent says: done"] --> L1["First run<br/>lint / typecheck"]
+ L1 --> L2["Then run<br/>tests and startup checks"]
+ L2 --> L3["Finally run<br/>complete user flow"]
+ L3 --> Done["Pass all three to be done"]
+```
+
+```mermaid
+flowchart LR
+ A["Code is written<br/>unit tests are green"] --> B["But app didn't really start<br/>full flow never ran"]
+ B --> C["Config, DB, external service issues<br/>all remain hidden"]
+ C --> D["So agent declares victory too early"]
+```
+
+## Основні концепції
+
+- **Передчасне оголошення завершення**: агент стверджує, що завдання виконано, але незадоволені специфікації коректності залишаються. Корінна проблема в тому, що агент судить на основі локальної, кодорівневої впевненості, тоді як системна коректність вимагає глобальної верифікації.
+- **Упередженість калібрування впевненості**: систематичний розрив між самозвітованою впевненістю агента у завершеності та фактичною якістю виконання. Для складних багатофайлових завдань це упередження значно позитивне — агент стабільно впевненіший, ніж його фактичні результати.
+- **Критерії завершення**: чіткий, виконуваний набір умов оцінювання, визначений у harness. Агент повинен задовольнити всі умови перед оголошенням завершення. «Готово» переходить від суб'єктивного судження до об'єктивного визначення.
+- **Подвійний вентиль верифікація-валідація**: перший шар (верифікація) перевіряє, чи код правильно реалізує задану поведінку; другий шар (валідація) перевіряє, чи системна поведінка відповідає наскрізним вимогам. Обидва мають пройти, перш ніж завдання вважається виконаним.
+- **Сигнали зворотного зв'язку під час виконання**: логи, стани процесів та перевірки стану від виконання програми — вони формують об'єктивну основу для оцінки harness якості завершення.
+- **Обмеження пріоритету завершення**: спочатку верифікуйте функціональну коректність, потім вирішуйте питання продуктивності, і нарешті — стиль. Рефакторинг не дозволяється, поки основна функціональність не верифікована.
+
+## Проходження юніт-тестів ≠ завдання виконано
+
+Це найпоширеніша пастка і найнебезпечніша. Агент пише код, запускає юніт-тести, бачить «всі зелені» і каже «готово». Але філософія проєктування юніт-тестів — ізоляція модуля, що тестується, і мокування залежностей — саме це і робить їх нездатними виявляти проблеми між компонентами:
+
+**Невідповідність інтерфейсу**: рендерер передає відносний шлях до файлу в preload-скрипт, але preload-скрипт очікує абсолютний шлях. Їхні відповідні юніт-тести обидва використовують моки і обидва проходять. Проблема виявляється лише під час наскрізного тестування.
+
+**Помилки поширення стану**: міграція бази даних змінює схему таблиці, але кешуючий шар ORM ще зберігає кешовані записи зі старою схемою. Юніт-тести запускаються в новому мок-середовищі щоразу, тому такий тип кросшарової невідповідності стану ніколи не виявляється.
+
+**Залежність від середовища**: код поводиться правильно в тестовому середовищі (де все замоковано), але збоїть у реальному через відмінності конфігурації, затримку мережі або недоступність сервісу.
+
+### «Рефакторинг заодно» — отрута для оцінки завершеності
+
+У Claude Code є поширений поведінковий патерн: він починає рефакторити код, оптимізувати продуктивність і покращувати стиль, перш ніж основна функціональність пройшла верифікацію. Прислів'я Кнута про те, що «передчасна оптимізація — корінь усього зла», набуває нового сенсу в сценарії з агентами — рефакторинг зміщує межу між верифікованим і неверифікованим кодом, потенційно ламаючи шляхи коду, які раніше були неявно коректними.
+
+### Систематичне упередження самооцінки
+
+Anthropic виявив глибший патерн відмови у своїх дослідженнях 2026 року: **коли агента просять оцінити власну роботу, він систематично дає надмірно позитивні оцінки — навіть коли людський спостерігач визначить якість як явно незадовільну.**
+
+Ця проблема особливо гостра для суб'єктивних завдань (наприклад, естетика дизайну). Те, чи «макет відполірований», — питання судження, і агент стабільно схиляється до позитивної оцінки. Навіть у завданнях з перевіряємими результатами погана здатність агента до судження погіршує його продуктивність.
+
+Рішення — не в тому, щоб зробити агента «об'єктивнішим». Та сама модель і генерує, і оцінює, тому вона за своєю суттю схильна ставитися до себе поблажливо. **Рішення — розділити «виконавця» і «перевіряльника».**
+
+Незалежний агент-оцінювач, спеціально налаштований бути «прискіпливим», значно ефективніший, ніж самооцінка агента-генератора. Експериментальні дані Anthropic:
+
+| Архітектура | Час виконання | Вартість | Основні функції працюють? |
+|-------------|---------------|----------|--------------------------|
+| Один агент (без обгортки) | 20 хв | $9 | Ні (ігрові сутності не реагують на введення) |
+| Три агенти (планувальник + генератор + оцінювач) | 6 год | $200 | Так (гра повністю грається) |
+
+Це та сама модель (Opus 4.5) з тим самим промптом («побудуй 2D-редактор ретро-ігор»). Єдина відмінність — harness: від «запуску без обгортки» до «планувальник розширює вимоги → генератор реалізує функцію за функцією → оцінювач виконує реальне клік-тестування через Playwright».
+
+> Джерело: [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
+
+## Як запобігати передчасним оголошенням завершення
+
+### 1. Екстерналізуйте оцінку завершення
+
+Оцінка завершення не повинна здійснюватися самим агентом. Harness незалежно виконує валідацію завершення, використовуючи сигнали виконання як вхідні дані, а не впевненість агента. У CLAUDE.md це можна прописати явно:
+
+```
+## Definition of Done
+- Feature complete = end-to-end verification passed, not "code is written"
+- Required verification levels:
+ 1. Unit tests pass
+ 2. Integration tests pass
+ 3. End-to-end flow verification passes
+- Do not proceed to level 2 if level 1 fails
+- Do not proceed to level 3 if level 2 fails
+```
+
+### 2. Побудуйте тришарову валідацію завершення
+
+- **Шар 1: Синтаксис і статичний аналіз**. Найнижча вартість, найменше інформації, але обов'язковий для проходження. Це абсолютний мінімум — потрібно правильно написати слова, перш ніж читати далі.
+- **Шар 2: Верифікація поведінки під час виконання**. Виконання тестів, перевірки запуску застосунку, валідація критичних шляхів. Це основне свідчення завершення — не просто написаний, але й запускаємий.
+- **Шар 3: Системне підтвердження**. Наскрізне тестування, інтеграційна валідація, симуляція сценаріїв користувача. Остання лінія захисту від передчасних оголошень — не просто запускається, але й коректний.
+
+### 3. Надавайте агенту дієвий зворотний зв'язок про помилки
+
+OpenAI представив особливо ефективний патерн у своїй практиці з Codex: **повідомлення про помилки, написані для агентів, повинні містити інструкції з виправлення**. Не просто кажіть агенту «це неправильно» — вкажіть, що саме неправильно і як це виправити. Не використовуйте `"Test failed"`, використовуйте `"Test failed: POST /api/reset-password returned 500. Check that the email service config exists in environment variables. The template file should be at templates/reset-email.html."` Такий конкретний, дієвий зворотний зв'язок дозволяє агенту самостійно виправлятися без втручання людини.
+
+### 4. Фіксуйте сигнали виконання
+
+Ефективні сигнали виконання включають:
+- Чи успішно запустився застосунок і досяг стану готовності?
+- Чи критичні шляхи функцій виконувались успішно під час виконання?
+- Чи були коректні записи в базу даних, файлові операції та інші побічні ефекти?
+- Чи були очищені тимчасові ресурси?
+
+## Реальний кейс
+
+**Завдання**: реалізувати функціональність скидання пароля. Включає операції з базою даних, надсилання електронної пошти та зміни API-ендпоінта.
+
+**Шлях передчасної здачі**: агент змінює схему бази даних, пише API-ендпоінт, додає шаблон електронного листа, запускає юніт-тести (всі проходять) і оголошує завершення. Здається, зроблено багато, але всі критичні кроки були пропущені.
+
+**Фактичні упущення**: (1) наскрізний потік не перевірявся — фактичне надсилання та верифікація посилання для скидання ніколи не були підтверджені. (2) Міграція бази даних завершилась після часткового виконання, залишивши схему суперечливою. (3) Конфігурація поштового сервісу була відсутня в цільовому середовищі.
+
+**Втручання harness**: валідація завершення є обов'язковою — (1) запустити повний застосунок для перевірки доступності ендпоінта скидання; (2) виконати повний потік скидання; (3) верифікувати узгодженість стану бази даних. Всі дефекти були виявлені в межах сеансу, що зекономило в 5–10 разів більше ресурсів порівняно з виправленнями після факту.
+
+## Ключові висновки
+
+- **Агенти систематично переоцінюють свою впевненість** — упередженість калібрування є об'єктивною реальністю. Написаний код не означає написаний правильно.
+- **Оцінка завершення повинна бути екстерналізована** — harness верифікує незалежно. Не довіряйте «відчуттям» агента.
+- **Усі три шари валідації є обов'язковими**: синтаксис проходить, поведінка проходить, система проходить — шар за шаром, без скорочень.
+- **Повідомлення про помилки мають містити конкретні кроки виправлення**, дозволяючи агенту самостійно виправлятися, а не просто повідомляти «це неправильно».
+- **Жодного рефакторингу, поки основна функціональність не верифікована** — обмеження пріоритету завершення є ключем до запобігання передчасній оптимізації.
+
+## Додаткове читання
+
+- [On Calibration of Modern Neural Networks - Guo et al.](https://arxiv.org/abs/1706.04599) — доводить, що сучасні глибокі мережі систематично переоцінюють свою впевненість
+- [Building Effective Agents - Anthropic](https://www.anthropic.com/research/building-effective-agents) — критична роль свідчень виконання в оцінці завершення
+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — передчасне оголошення завершення є одним з основних режимів відмови агентів
+- [The Art of Software Testing - Myers](https://www.goodreads.com/book/show/137543.The_Art_of_Software_Testing) — класичний довідник з ієрархій методів тестування та їхньої ефективності
+
+## Вправи
+
+1. **Проєктування функції валідації завершення**: розробіть повну валідацію завершення для завдання, що включає міграцію бази даних і зміни API. Перерахуйте необхідні сигнали виконання і критерії проходження/непроходження для кожного. Запустіть на реальному завданні і зафіксуйте, які приховані проблеми це виявить.
+
+2. **Вимірювання упередженості калібрування**: виберіть 10 завдань з написання коду різних типів. Запишіть самозвітовану впевненість агента у завершеності порівняно з фактичною якістю виконання. Розрахуйте упередженість і проаналізуйте її зв'язок зі складністю завдання.
+
+3. **Експеримент з багатошаровим захистом**: запустіть три конфігурації на тому самому наборі завдань: (a) лише статичний аналіз, (b) додати юніт-тестування, (c) повна тришарова валідація. Порівняйте частку передчасних оголошень завершення і кількість незнайдених дефектів.
diff --git a/docs/uk/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md b/docs/uk/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md
new file mode 100644
index 0000000..5d0328e
--- /dev/null
+++ b/docs/uk/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md
@@ -0,0 +1,6 @@
+# Архітектурні правила Electron
+
+- Код рендерера не може безпосередньо звертатись до файлової системи.
+- Preload є єдиним мостом між рендерером і головним процесом Electron.
+- Логіка отримання та індексування даних знаходиться в сервісних модулях, а не в UI-компонентах.
+- Логування має бути структурованим і виводитись на межах сервісів.
diff --git a/docs/uk/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts b/docs/uk/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts
new file mode 100644
index 0000000..2428416
--- /dev/null
+++ b/docs/uk/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts
@@ -0,0 +1,253 @@
+/**
+ * e2e-runner.ts
+ *
+ * A minimal E2E test harness. Defines test cases as user action sequences
+ * (import doc -> index -> ask question -> verify citation). Simulates
+ * running them and shows the difference between "unit tests pass" and
+ * "full pipeline works".
+ *
+ * Run: npx tsx docs/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface PipelineStep {
+ name: string;
+ unitTestPasses: boolean;
+ // Simulated actual behavior in the pipeline
+ actualBehavior: "works" | "fails" | "partial";
+ failureReason?: string;
+}
+
+interface TestCase {
+ name: string;
+ steps: PipelineStep[];
+}
+
+interface TestResult {
+ testCase: string;
+ unitTestsPassed: number;
+ unitTestsTotal: number;
+ unitTestResult: "PASS" | "FAIL";
+ e2eResult: "PASS" | "FAIL";
+ e2eFailureStep?: string;
+ e2eFailureReason?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Test cases -- realistic scenarios where unit tests pass but E2E fails
+// ---------------------------------------------------------------------------
+
+const testCases: TestCase[] = [
+ {
+ name: "Import document and ask question",
+ steps: [
+ {
+ name: "Parse uploaded document",
+ unitTestPasses: true,
+ actualBehavior: "works",
+ },
+ {
+ name: "Store document chunks",
+ unitTestPasses: true,
+ actualBehavior: "works",
+ },
+ {
+ name: "Index chunks for retrieval",
+ unitTestPasses: true,
+ actualBehavior: "partial", // Indexes but with wrong embedding dimensions
+ failureReason: "Embedding dimension mismatch between indexer and retriever",
+ },
+ {
+ name: "Retrieve relevant chunks",
+ unitTestPasses: true, // Unit test uses mock data with correct dimensions
+ actualBehavior: "fails",
+ failureReason: "Empty results due to dimension mismatch from previous step",
+ },
+ {
+ name: "Generate answer with citations",
+ unitTestPasses: true, // Unit test provides pre-retrieved chunks
+ actualBehavior: "fails",
+ failureReason: "No chunks retrieved, so answer has no citations",
+ },
+ ],
+ },
+ {
+ name: "Delete document and verify removal",
+ steps: [
+ {
+ name: "Find document by ID",
+ unitTestPasses: true,
+ actualBehavior: "works",
+ },
+ {
+ name: "Delete document record",
+ unitTestPasses: true,
+ actualBehavior: "works",
+ },
+ {
+ name: "Remove indexed chunks",
+ unitTestPasses: true,
+ actualBehavior: "fails", // Orphaned chunks remain in the index
+ failureReason: "Index cleanup query timed out, chunks remain orphaned",
+ },
+ {
+ name: "Verify document not in search results",
+ unitTestPasses: true, // Unit test mocks the search
+ actualBehavior: "fails",
+ failureReason: "Orphaned chunks from previous step still appear in results",
+ },
+ ],
+ },
+ {
+ name: "Multi-user concurrent access",
+ steps: [
+ {
+ name: "User A imports document",
+ unitTestPasses: true,
+ actualBehavior: "works",
+ },
+ {
+ name: "User B imports document",
+ unitTestPasses: true,
+ actualBehavior: "works",
+ },
+ {
+ name: "User A queries their document",
+ unitTestPasses: true,
+ actualBehavior: "partial", // Cross-contamination of results
+ failureReason: "No user-scoping on retrieval, returns chunks from User B's doc",
+ },
+ {
+ name: "Verify only User A's results returned",
+ unitTestPasses: true,
+ actualBehavior: "fails",
+ failureReason: "Results include documents from other users",
+ },
+ ],
+ },
+];
+
+// ---------------------------------------------------------------------------
+// Run tests
+// ---------------------------------------------------------------------------
+
+function runUnitTests(tc: TestCase): { passed: number; total: number } {
+ const passed = tc.steps.filter((s) => s.unitTestPasses).length;
+ return { passed, total: tc.steps.length };
+}
+
+function runE2ETest(tc: TestCase): { pass: boolean; failureStep?: string; failureReason?: string } {
+ // Pipeline: if any step actually fails, the whole E2E fails
+ for (const step of tc.steps) {
+ if (step.actualBehavior === "fails") {
+ return {
+ pass: false,
+ failureStep: step.name,
+ failureReason: step.failureReason ?? "Unknown failure",
+ };
+ }
+ // "partial" means the step technically completes but creates problems downstream
+ // We let it continue but track it
+ }
+ // Check if any step was "partial" (which may cause downstream issues)
+ const partialSteps = tc.steps.filter((s) => s.actualBehavior === "partial");
+ if (partialSteps.length > 0) {
+ // The partial steps may or may not cause overall failure
+ // In our simulation, partial steps always lead to failure downstream
+ // unless there's an explicit "fails" step that already caught it
+ // This case means all steps were either "works" or "partial"
+ return {
+ pass: false,
+ failureStep: partialSteps[partialSteps.length - 1].name,
+ failureReason: partialSteps[partialSteps.length - 1].failureReason ?? "Partial completion",
+ };
+ }
+
+ return { pass: true };
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function run(): void {
+ console.log("\n" + "=".repeat(95));
+ console.log(" E2E TEST RUNNER -- Unit Tests vs Full Pipeline");
+ console.log("=".repeat(95));
+
+ const results: TestResult[] = testCases.map((tc) => {
+ const unit = runUnitTests(tc);
+ const e2e = runE2ETest(tc);
+
+ return {
+ testCase: tc.name,
+ unitTestsPassed: unit.passed,
+ unitTestsTotal: unit.total,
+ unitTestResult: unit.passed === unit.total ? "PASS" : "FAIL",
+ e2eResult: e2e.pass ? "PASS" : "FAIL",
+ e2eFailureStep: e2e.failureStep,
+ e2eFailureReason: e2e.failureReason,
+ };
+ });
+
+ // Per-test-case detail
+ for (let i = 0; i < testCases.length; i++) {
+ const tc = testCases[i];
+ const r = results[i];
+
+ console.log("\n Test Case: " + tc.name);
+ console.log(" " + "-".repeat(70));
+
+ const stepHeader = ` | ${pad("Step", 40)}| ${pad("Unit Test", 11)}| ${pad("E2E Actual", 12)}|`;
+ const stepSep = ` |${"-".repeat(42)}|${"-".repeat(13)}|${"-".repeat(14)}|`;
+ console.log(stepHeader);
+ console.log(stepSep);
+
+ for (const step of tc.steps) {
+ const utLabel = step.unitTestPasses ? "PASS" : "FAIL";
+ let e2eLabel: string;
+ if (step.actualBehavior === "works") e2eLabel = "PASS";
+ else if (step.actualBehavior === "partial") e2eLabel = "PARTIAL*";
+ else e2eLabel = "FAIL";
+
+ const marker = step.actualBehavior !== "works" ? ">>" : " ";
+ console.log(`${marker}| ${pad(step.name, 40)}| ${pad(utLabel, 11)}| ${pad(e2eLabel, 12)}|`);
+ }
+
+ if (r.e2eFailureStep) {
+ console.log(`\n E2E Failure at: ${r.e2eFailureStep}`);
+ console.log(` Reason: ${r.e2eFailureReason}`);
+ }
+ }
+
+ // Summary comparison
+ console.log("\n" + "=".repeat(95));
+ console.log(" COMPARISON: Unit Tests vs E2E Tests");
+ console.log("=".repeat(95) + "\n");
+
+ const header = `| ${pad("Test Case", 35)}| ${pad("Unit Tests", 15)}| ${pad("E2E Result", 12)}| Discrepancy`;
+ const sep = `|${"-".repeat(37)}|${"-".repeat(17)}|${"-".repeat(14)}|${"-".repeat(30)}`;
+ console.log(header);
+ console.log(sep);
+
+ for (const r of results) {
+ const utLabel = `${r.unitTestsPassed}/${r.unitTestsTotal} ${r.unitTestResult}`;
+ const discrepancy = r.unitTestResult === "PASS" && r.e2eResult === "FAIL";
+ const discLabel = discrepancy ? "UNIT PASS BUT E2E FAIL" : "Consistent";
+
+ console.log(`| ${pad(r.testCase, 35)}| ${pad(utLabel, 15)}| ${pad(r.e2eResult, 12)}| ${discLabel}`);
+ }
+
+ const falseConfidence = results.filter((r) => r.unitTestResult === "PASS" && r.e2eResult === "FAIL").length;
+ console.log("\n False confidence count: " + falseConfidence + " of " + results.length);
+ console.log(" Unit tests pass but E2E reveals integration failures that units cannot catch.\n");
+}
+
+run();
diff --git a/docs/uk/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md b/docs/uk/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md
new file mode 100644
index 0000000..6f5b0ce
--- /dev/null
+++ b/docs/uk/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md
@@ -0,0 +1,8 @@
+# Код до лекції 10
+
+Використовуйте цю папку для прикладів:
+
+- архітектурних обмежень
+- структурних тестів
+- смакових інваріантів
+- lint-повідомлень, орієнтованих на усунення проблем
diff --git a/docs/uk/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md b/docs/uk/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md
new file mode 100644
index 0000000..179ddff
--- /dev/null
+++ b/docs/uk/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md
@@ -0,0 +1,10 @@
+# Приклад: перетворення review-фідбеку на правило
+
+Повторюваний коментар у review:
+
+> Не викликайте утиліти файлової системи з рендерера. Використовуйте preload-міст.
+
+Просунуте правило harness:
+
+- додати lint- або import-правило, що забороняє використання `fs` у коді рендерера
+- додати текст усунення проблеми з поясненням межі preload
diff --git a/docs/uk/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/uk/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
new file mode 100644
index 0000000..c243879
--- /dev/null
+++ b/docs/uk/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -0,0 +1,156 @@
+[中文版 →](../../../zh/lectures/lecture-10-why-end-to-end-testing-changes-results/)
+
+> Приклади коду до цієї лекції: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/uk/lectures/lecture-10-why-end-to-end-testing-changes-results/code/)
+> Практичне завдання: [Проєкт 05. Нехай агент верифікує власну роботу](./../../projects/project-05-grounded-qa-verification/index.md)
+
+# Лекція 10. Лише повний запуск пайплайну є справжньою верифікацією
+
+Ви просите агента додати функцію експорту файлів до Electron-застосунку. Він пише компонент рендерера, preload-скрипт і логіку сервісного шару. Юніт-тести для кожного компонента проходять. Агент каже «готово». Ви насправді натискаєте кнопку експорту — формат шляху до файлу неправильний, прогрес-бар не реагує, а експорт великих файлів призводить до витоку пам'яті. П'ять дефектів на межах компонентів, і жодного з них юніт-тести не виявили.
+
+Кожна частина виглядає «правильною» окремо, але проблеми виникають у момент з'єднання. Testing Pyramid від Google говорить, що велика база юніт-тестів необхідна, але зупинятись на цьому означає систематично пропускати проблеми взаємодії компонентів. Для агентів AI-кодування ця проблема ще гостріша, бо агенти схильні запускати лише найшвидші тести, а потім оголошувати завершення. **Лише наскрізне тестування може довести відсутність дефектів системного рівня.**
+
+## Сліпі зони юніт-тестів
+
+Філософія проєктування юніт-тестування — ізоляція: мокувати залежності, зосередитись на модулі під тестом. Ця філософія робить юніт-тести швидкими і точними, але водночас створює систематичні сліпі зони. Кожен модуль бездоганно працює в ізоляції, проте наступні категорії проблем виникають лише тоді, коли все справді запускається разом:
+
+**Невідповідність інтерфейсів**: Рендерер передає preload-скрипту відносний шлях до файлу, але preload-скрипт очікує абсолютний. Відповідні юніт-тести обох частин використовують моки й обидва проходять. Проблема виявляється лише при виконанні наскрізного сценарію.
+
+**Помилки поширення стану**: Міграція бази даних змінює схему таблиці, але кешувальний шар ORM все ще зберігає записи кешу зі старою схемою. Юніт-тести щоразу піднімають чисте мок-середовище, тому ніколи не виявляють такої між-шарової невідповідності стану.
+
+**Проблеми життєвого циклу ресурсів**: Отримання та звільнення файлових дескрипторів, з'єднань з базою даних і мережевих сокетів охоплює кілька компонентів. Юніт-тести створюють і знищують незалежні ресурси для кожного тест-кейсу, тому ніколи не виявляють суперечок за ресурси або витоків.
+
+**Залежність від середовища**: Код працює правильно в тестовому середовищі (де все замоковано), але падає у реальному через відмінності конфігурації, мережеву затримку або недоступність сервісу.
+
+## Наскрізне тестування не лише змінює результати — воно змінює поведінку
+
+Це те, що багато хто упускає: коли агент знає, що його роботу буде перевірено наскрізними тестами, його поведінка при написанні коду змінюється.
+
+1. **Врахування взаємодії компонентів**: Під час написання коду він починає запитувати «як цей інтерфейс з'єднується з upstream?» замість того, щоб зосереджуватись на окремій функції ізольовано.
+2. **Дотримання архітектурних меж**: У системах з архітектурними обмеженнями наскрізні тести змушують агента дотримуватись правил меж.
+3. **Обробка шляхів помилок**: Наскрізні тести зазвичай включають сценарії збоїв, що спонукає агента думати про обробку винятків.
+
+## Testing Pyramid і просування review-фідбеку
+
+```mermaid
+flowchart TB
+ subgraph Unit["Unit tests only check isolated parts"]
+ U1["Renderer tests"]
+ U2["Preload tests"]
+ U3["Service tests"]
+ end
+
+ subgraph E2E["E2E runs through the real system"]
+ R["Click renderer button"] --> P["Preload bridge"]
+ P --> S["Service layer"]
+ S --> F["File System / OS"]
+ F --> Result["Actual exported file"]
+ end
+```
+
+```mermaid
+flowchart LR
+ Review["Review feedback:<br/>renderer cannot import fs directly"] --> Rule["Add a direct fs import check"]
+ Rule --> Message["Tell the agent in the error message<br/>to move file access to preload"]
+ Message --> Harness["Add this check to the harness"]
+ Harness --> Stronger["Next violation fails immediately"]
+```
+
+OpenAI підкреслює у своїх інженерних практиках Codex: **повідомлення про помилки, написані для агентів, повинні містити інструкції щодо виправлення.** Замість `"Direct filesystem access in renderer"` слід писати `"Direct filesystem access in renderer. All file operations must go through the preload bridge. Move this call to preload/file-ops.ts and invoke it via window.api."` Це перетворює архітектурні правила на цикл автокорекції. Повідомлення про помилки не просто кажуть «що пішло не так» — вони кажуть «як це виправити», дозволяючи агенту коригувати себе автономно.
+
+## Ключові поняття
+
+- **Дефекти на межах компонентів**: Компоненти A і B кожен проходять свої юніт-тести, але їхня взаємодія дає неправильний результат. Це категорія проблем, яку наскрізне тестування виявляє найкраще.
+- **Градієнт достатності тестування**: Дефекти, виявні юніт-тестами <= дефекти, виявні інтеграційними тестами <= дефекти, виявні наскрізними тестами. Здатність виявлення зростає з кожним шаром.
+- **Правила забезпечення архітектурних меж**: Перетворення правил з архітектурних документів (наприклад, «процес рендерера не повинен безпосередньо звертатись до файлової системи») на виконувані автоматизовані перевірки — від «записаного на папері» до «запущеного в CI».
+- **Просування review-фідбеку**: Перетворення повторюваних коментарів code review на автоматизовані тести. Щоразу, коли виявляється нова категорія повторюваної проблеми, додається правило, і harness автоматично стає сильнішим.
+- **Повідомлення про помилки, орієнтовані на агента**: Повідомлення про збій мають не просто констатувати «що пішло не так», а й точно вказувати агенту, як це виправити, перетворюючи збої тестів на петлі самокорекції.
+
+## Як це робити
+
+### 0. Визначте архітектурні межі до написання E2E-тестів
+
+Передумова для наскрізного тестування — чіткі межі системи. Якщо архітектура є заплутаним клубком, наскрізне тестування лише доведе «весь безлад запускається», не показавши, де порушено проєктний намір.
+
+Досвід OpenAI: **для кодових баз, генерованих агентами, архітектурні обмеження мають бути встановлені як ранні передумови з першого дня — а не те, про що думають після того, як команда виросла.** Причина проста: агенти копіюють існуючі патерни в репозиторії, навіть якщо ці патерни суперечливі або неоптимальні. Без архітектурних обмежень агенти вносять все більше відхилень із кожною сесією.
+
+OpenAI прийняла «Layered Domain Architecture», де кожен бізнес-домен розділений на фіксовані шари: Types -> Config -> Repo -> Service -> Runtime -> UI. Залежності течуть суворо вперед, а міждоменні аспекти надходять через явні інтерфейси Providers. Будь-яка інша залежність заборонена й механічно забезпечується через кастомний лінтинг.
+
+Ключовий принцип: **Забезпечуйте інваріанти; не мікрокеруйте реалізацією.** Наприклад, вимагайте, щоб «дані парсились на межі», але не вказуйте, яку бібліотеку використовувати. Повідомлення про помилки мають містити інструкції щодо виправлення — не просто «порушення», а конкретне пояснення агенту, як це змінити.
+
+> Джерело: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
+
+### 1. Harness повинен включати наскрізний шар
+
+Зробіть це явним у своєму потоці валідації: для завдань, що включають зміни між компонентами, проходження наскрізних тестів є передумовою завершення:
+
+```
+## Validation Hierarchy
+- Level 1: Unit tests (Must pass)
+- Level 2: Integration tests (Must pass)
+- Level 3: End-to-end tests (Must pass when cross-component changes are involved)
+- Skipping any required level = Not Complete
+```
+
+### 2. Перетворіть архітектурні правила на виконувані перевірки
+
+Кожне архітектурне обмеження має мати відповідний тест або lint-правило:
+
+```bash
+# Check whether the renderer process directly calls Node.js APIs
+grep -r "require('fs')" src/renderer/ && exit 1 || echo "OK: no direct fs access in renderer"
+```
+
+### 3. Проєктуйте повідомлення про помилки, орієнтовані на агента
+
+Повідомлення про збій мають містити три елементи: що пішло не так, чому і як виправити:
+
+```
+ERROR: Found direct import of 'fs' in src/renderer/App.tsx:12
+WHY: Renderer process has no access to Node.js APIs for security
+FIX: Move file operations to src/preload/file-ops.ts and call via window.api.readFile()
+```
+
+### 4. Встановіть процес просування review-фідбеку
+
+Щоразу, коли під час code review ви виявляєте нову категорію помилок агента, перетворюйте її на автоматизовану перевірку. Через місяць ваш harness буде значно сильнішим, ніж на початку місяця.
+
+## Реальний кейс
+
+**Завдання**: Реалізувати функцію експорту файлів в Electron-застосунку. Задіяні: UI процесу рендерера, файловий проксі preload-скрипту та перетворення даних сервісного шару.
+
+**Фаза юніт-тестів**: Тести компонента рендерера (пройшли, файлові операції замоковано), тести preload-скрипту (пройшли, файлова система замокована), тести сервісного шару (пройшли, джерело даних замоковано). Агент оголошує завершення.
+
+**Дефекти, виявлені наскрізними тестами**:
+
+| Дефект | Опис | Юніт-тест | E2E |
+|--------|------|-----------|-----|
+| Невідповідність інтерфейсів | Несумісний формат шляху до файлу | Пропущено | Виявлено |
+| Поширення стану | Прогрес експорту не повертається до UI через IPC | Пропущено | Виявлено |
+| Витік ресурсів | Дескриптори великих файлів не звільняються | Пропущено | Виявлено |
+| Проблема дозволів | Відмінні дозволи в пакетному середовищі | Пропущено | Виявлено |
+| Поширення помилок | Винятки сервісного шару не досягали шару UI | Пропущено | Виявлено |
+
+Всі 5 дефектів виявлені наскрізними тестами; юніт-тести не виявили жодного. Компроміс — час тестування зріс з 2 секунд до 15 секунд — цілком прийнятно в агентному робочому процесі.
+
+## Ключові висновки
+
+- **Юніт-тести систематично сліпі до дефектів на межах компонентів**: їхня ізоляційна конструкція — саме те, що заважає їм виявляти проблеми взаємодії.
+- **Наскрізне тестування не лише виявляє дефекти, воно змінює спосіб написання коду агентами**: зміщує фокус на інтеграцію та межі.
+- **Архітектурні правила мають бути виконуваними**: не записаними в документі в очікуванні, поки хтось їх прочитає, а автоматично перевіряються при кожному коміті.
+- **Повідомлення про помилки мають бути спроєктовані для агентів**: включати конкретні кроки «як виправити», щоб утворити петлю самокорекції.
+- **Просування review-фідбеку автоматично робить harness сильнішим**: кожна захоплена категорія дефектів стає постійною лінією захисту.
+
+## Додаткова література
+
+- [How Google Tests Software - Whittaker et al.](https://www.goodreads.com/book/show/13563030-how-google-tests-software) — Класичне джерело моделі Testing Pyramid
+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — Інженерні практики автоматизованого забезпечення архітектурних обмежень
+- [Chaos Engineering - Netflix (Basiri et al.)](https://ieeexplore.ieee.org/document/7466237) — Проактивне введення збоїв для верифікації стійкості системи
+- [QuickCheck - Claessen & Hughes](https://www.cs.tufts.edu/~nr/cs257/archive/john-hughes/quick.pdf) — Методологія тестування властивостей, що знаходиться між тестуванням на прикладах та формальною верифікацією
+
+## Вправи
+
+1. **Виявлення міжкомпонентних дефектів**: Оберіть завдання з модифікацією, що залучає щонайменше три компоненти. Спочатку запустіть лише юніт-тести й запишіть результати, потім запустіть наскрізні тести. Проаналізуйте кожен додатково виявлений дефект і класифікуйте, який тип між-шарової проблеми взаємодії він представляє.
+
+2. **Автоматизація архітектурних правил**: Оберіть архітектурне обмеження у своєму проєкті та перетворіть його на виконувану перевірку (разом з орієнтованим на агента повідомленням про помилку). Інтегруйте у harness і перевірте ефективність за допомогою базового завдання.
+
+3. **Просування review-фідбеку**: Знайдіть повторюваний тип коментарів в історії code review та перетворіть його на автоматизовану перевірку за п'ятикроковим процесом. Порівняйте частоту цієї категорії проблем до і після просування.
diff --git a/docs/uk/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md b/docs/uk/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md
new file mode 100644
index 0000000..7057588
--- /dev/null
+++ b/docs/uk/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md
@@ -0,0 +1,8 @@
+# Приклад рубрики оцінювача
+
+Використовуйте оцінювання від 1 до 5 для кожного виміру:
+
+- Заземленість: чи пов'язані відповіді чітко з імпортованими джерелами?
+- Якість цитування: чи є посилання на джерела видимими та конкретними?
+- Функціональність: чи може користувач завершити потік запитань і відповідей?
+- Узгодженість продукту: чи відчувається робочий процес інтегрованим?
diff --git a/docs/uk/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md b/docs/uk/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md
new file mode 100644
index 0000000..d1f082f
--- /dev/null
+++ b/docs/uk/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md
@@ -0,0 +1,8 @@
+# Код до лекції 11
+
+Використовуйте цю папку для прикладів:
+
+- результатів планувальника
+- рубрик оцінювача
+- циклів генератор/оцінювач
+- порівнянь одноагентного та багаторолевого підходів
diff --git a/docs/uk/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts b/docs/uk/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts
new file mode 100644
index 0000000..213dc19
--- /dev/null
+++ b/docs/uk/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts
@@ -0,0 +1,260 @@
+/**
+ * runtime-logger.ts
+ *
+ * A structured logging module demo. Shows ad-hoc console.log output vs
+ * structured JSON log output when diagnosing a failure. Includes a seeded
+ * failure scenario and demonstrates how structured logs pinpoint the issue
+ * faster.
+ *
+ * Run: npx tsx docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface StructuredLogEntry {
+ timestamp: string;
+ level: "info" | "warn" | "error" | "debug";
+ component: string;
+ action: string;
+ durationMs?: number;
+ input?: unknown;
+ output?: unknown;
+ error?: string;
+ correlationId: string;
+}
+
+// ---------------------------------------------------------------------------
+// Simulated pipeline with a seeded failure
+// ---------------------------------------------------------------------------
+
+const CORRELATION_ID = "req-" + Math.random().toString(36).slice(2, 8);
+
+// Simulated stages of a document Q&A pipeline
+interface PipelineStage {
+ component: string;
+ action: string;
+ durationMs: number;
+ success: boolean;
+ errorMessage?: string;
+ input?: unknown;
+ output?: unknown;
+}
+
+function runPipeline(): PipelineStage[] {
+ return [
+ {
+ component: "DocumentLoader",
+ action: "parse_upload",
+ durationMs: 45,
+ success: true,
+ input: { filename: "report.pdf", size: "2.3MB" },
+ output: { chunks: 47 },
+ },
+ {
+ component: "ChunkIndexer",
+ action: "embed_and_store",
+ durationMs: 230,
+ success: true,
+ input: { chunks: 47 },
+ output: { indexed: 47, embeddingDim: 1536 },
+ },
+ {
+ component: "QueryRouter",
+ action: "route_query",
+ durationMs: 12,
+ success: true,
+ input: { query: "What is the revenue target?" },
+ output: { routedTo: "RetrievalEngine" },
+ },
+ {
+ // SEEDED FAILURE: Retrieval returns 0 results due to dimension mismatch
+ component: "RetrievalEngine",
+ action: "semantic_search",
+ durationMs: 180,
+ success: false,
+ errorMessage: "Vector dimension mismatch: query embedding dim=768, index embedding dim=1536",
+ input: { query: "What is the revenue target?", topK: 5 },
+ output: { results: 0 },
+ },
+ {
+ component: "AnswerGenerator",
+ action: "generate_with_citations",
+ durationMs: 1500,
+ success: true, // Doesn't crash, but produces a bad answer
+ input: { context: [], query: "What is the revenue target?" },
+ output: { answer: "I could not find relevant information.", citations: 0 },
+ },
+ ];
+}
+
+// ---------------------------------------------------------------------------
+// Ad-hoc logging (console.log style)
+// ---------------------------------------------------------------------------
+
+function printAdHocLog(stages: PipelineStage[]): void {
+ console.log("Starting document Q&A pipeline...");
+ console.log("User uploaded report.pdf");
+
+ for (const stage of stages) {
+ if (stage.success) {
+ console.log(`${stage.component}: ${stage.action} done (${stage.durationMs}ms)`);
+ } else {
+ console.log(`${stage.component}: something went wrong`);
+ }
+ }
+
+ console.log("Pipeline finished. Answer: I could not find relevant information.");
+}
+
+// ---------------------------------------------------------------------------
+// Structured logging (JSON)
+// ---------------------------------------------------------------------------
+
+function printStructuredLog(stages: PipelineStage[]): StructuredLogEntry[] {
+ const entries: StructuredLogEntry[] = [];
+
+ for (const stage of stages) {
+ entries.push({
+ timestamp: new Date().toISOString(),
+ level: stage.success ? "info" : "error",
+ component: stage.component,
+ action: stage.action,
+ durationMs: stage.durationMs,
+ input: stage.input,
+ output: stage.output,
+ error: stage.errorMessage,
+ correlationId: CORRELATION_ID,
+ });
+ }
+
+ return entries;
+}
+
+// ---------------------------------------------------------------------------
+// Diagnose failure from structured logs
+// ---------------------------------------------------------------------------
+
+function diagnoseFromStructured(entries: StructuredLogEntry[]): string[] {
+ const diagnosis: string[] = [];
+
+ // Find errors
+ const errors = entries.filter((e) => e.level === "error");
+ if (errors.length > 0) {
+ diagnosis.push("ERRORS FOUND:");
+ for (const err of errors) {
+ diagnosis.push(` - ${err.component}.${err.action}: ${err.error}`);
+ }
+ }
+
+ // Check for latency spikes
+ const slowStages = entries.filter((e) => (e.durationMs ?? 0) > 1000);
+ if (slowStages.length > 0) {
+ diagnosis.push("LATENCY SPIKES:");
+ for (const s of slowStages) {
+ diagnosis.push(` - ${s.component}.${s.action}: ${s.durationMs}ms`);
+ }
+ }
+
+ // Check for cascading failures
+ const emptyOutputs = entries.filter((e) => {
+ const out = e.output as Record<string, unknown> | undefined;
+ return out && typeof out === "object" && "results" in out && (out.results as number) === 0;
+ });
+ if (emptyOutputs.length > 0) {
+ diagnosis.push("EMPTY OUTPUTS (possible cascade):");
+ for (const e of emptyOutputs) {
+ diagnosis.push(` - ${e.component}.${e.action}: returned 0 results`);
+ }
+ }
+
+ return diagnosis;
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function run(): void {
+ const pipeline = runPipeline();
+
+ console.log("\n" + "=".repeat(90));
+ console.log(" OBSERVABILITY DEMO -- Ad-hoc vs Structured Logging");
+ console.log("=".repeat(90));
+
+ // --- Ad-hoc output ---
+ console.log("\n" + "-".repeat(90));
+ console.log(" SCENARIO A: Ad-hoc console.log output");
+ console.log("-".repeat(90) + "\n");
+ printAdHocLog(pipeline);
+ console.log("\n Diagnosis from ad-hoc logs: ??? Hard to tell what went wrong.");
+ console.log(" The failure message is vague: 'something went wrong'.");
+ console.log(" No dimensions, no input/output data, no correlation ID.");
+
+ // --- Structured output ---
+ console.log("\n" + "-".repeat(90));
+ console.log(" SCENARIO B: Structured JSON log output");
+ console.log("-".repeat(90) + "\n");
+
+ const structuredEntries = printStructuredLog(pipeline);
+
+ const header = `| ${pad("Timestamp", 26)}| ${pad("Level", 6)}| ${pad("Component", 20)}| ${pad("Action", 25)}| ${pad("Duration", 9)}| Error?`;
+ const sep = `|${"-".repeat(28)}|${"-".repeat(8)}|${"-".repeat(22)}|${"-".repeat(27)}|${"-".repeat(11)}|${"-".repeat(30)}`;
+ console.log(header);
+ console.log(sep);
+
+ for (const entry of structuredEntries) {
+ const hasError = entry.error ? entry.error.slice(0, 30) : "";
+ const marker = entry.level === "error" ? ">>" : " ";
+ console.log(
+ `${marker}| ${pad(entry.timestamp, 26)}| ${pad(entry.level, 6)}| ${pad(entry.component, 20)}| ${pad(entry.action, 25)}| ${pad(String(entry.durationMs) + "ms", 9)}| ${hasError}`
+ );
+ }
+
+ // --- Diagnosis ---
+ console.log("\n" + "-".repeat(90));
+ console.log(" AUTOMATED DIAGNOSIS FROM STRUCTURED LOGS");
+ console.log("-".repeat(90) + "\n");
+
+ const errors = structuredEntries.filter((e) => e.level === "error");
+ for (const err of errors) {
+ console.log(` ROOT CAUSE: ${err.component}.${err.action}`);
+ console.log(` Error: ${err.error}`);
+ console.log(` Input: ${JSON.stringify(err.input)}`);
+ console.log(` Output: ${JSON.stringify(err.output)}`);
+ console.log(` Correlation ID: ${err.correlationId}`);
+ }
+
+ // Downstream impact
+ console.log("\n DOWNSTREAM IMPACT:");
+ const answerGen = structuredEntries.find((e) => e.component === "AnswerGenerator");
+ if (answerGen) {
+ const out = answerGen.output as Record<string, unknown>;
+ console.log(` AnswerGenerator received empty context (${JSON.stringify(answerGen.input)})`);
+ console.log(` Produced answer: "${out.answer}" with ${out.citations} citations`);
+ }
+
+ // Comparison summary
+ console.log("\n" + "=".repeat(90));
+ console.log(" COMPARISON");
+ console.log("=".repeat(90) + "\n");
+
+ const cHeader = `| ${pad("Metric", 35)}| ${pad("Ad-hoc Logs", 18)}| ${pad("Structured Logs", 18)}|`;
+ const cSep = `|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(20)}|`;
+ console.log(cHeader);
+ console.log(cSep);
+ console.log(`| ${pad("Root cause identifiable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);
+ console.log(`| ${pad("Input/output traceable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);
+ console.log(`| ${pad("Correlation across steps", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);
+ console.log(`| ${pad("Machine-parseable", 35)}| ${pad("No", 18)}| ${pad("Yes", 18)}|`);
+ console.log(`| ${pad("Time to diagnose", 35)}| ${pad("Minutes (manual)", 18)}| ${pad("Seconds (auto)", 18)}|`);
+
+ console.log("\n Structured logging transforms debugging from guesswork into a deterministic lookup.\n");
+}
+
+run();
diff --git a/docs/uk/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md b/docs/uk/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md
new file mode 100644
index 0000000..3c65e84
--- /dev/null
+++ b/docs/uk/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md
@@ -0,0 +1,12 @@
+# Приклад sprint-контракту
+
+Мета спринту:
+
+- Додати видимі цитати до результатів заземленого Q&A
+
+Готово означає:
+
+- Користувач ставить питання
+- Застосунок повертає відповідь
+- Відображається щонайменше одна цитата
+- Натискання на цитату відкриває розташування джерела у виді документа
diff --git a/docs/uk/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/uk/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
new file mode 100644
index 0000000..99e3a3c
--- /dev/null
+++ b/docs/uk/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -0,0 +1,173 @@
+[中文版 →](../../../zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/)
+
+> Приклади коду: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/uk/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/)
+> Практичний проєкт: [Проєкт 06. Побудуйте повноцінний harness агента](./../../projects/project-06-runtime-observability-and-debugging/index.md)
+
+# Лекція 11. Спостережуваність runtime агента
+
+Ви просите агента реалізувати функцію. Він працює 20 хвилин, торкається купи файлів, потім каже «готово, але два тести падають». Ви питаєте чому — «не впевнений, можливо проблема із таймінгом». Ви питаєте, які критичні шляхи він змінив — «дозвольте подивитись на код...»
+
+Цей сценарій трапляється занадто часто, і першопричина не в здатностях агента — це відсутність спостережуваності у harness. Коли агент виконує завдання без бачення реального стану runtime, кожне рішення, яке він приймає, — по суті здогадка.
+
+**Без спостережуваності агенти приймають рішення в умовах невизначеності, оцінювання стає суб'єктивними судженнями, а повторні спроби — сліпим блуканням.** І OpenAI, і Anthropic формулюють надійність як проблему доказів: harness повинен відкривати поведінку runtime та сигнали оцінювання у формі, яка справді може спрямовувати наступне рішення.
+
+## Реальна ціна відсутності спостережуваності
+
+Коли harness позбавлений спостережуваності, систематично виникають чотири категорії проблем.
+
+**Неможливо відрізнити «правильне» від «виглядає правильним».** Функція виглядає бездоганно при code review — правильний синтаксис, звукова логіка. Але під час runtime помилка обробки граничної умови дає неправильні результати при певних вхідних даних. Лише runtime-трейси можуть виявити, що фактичний шлях виконання відхилився від очікувань. Code review показує «що було написано»; runtime-трейсинг показує «що насправді виконалось». Потрібні обидва.
+
+**Оцінювання перетворюється на містицизм.** Без рубрик оцінювання та критеріїв прийняття оцінювачі (людина або агент) змушені покладатись на неявні припущення. Один і той самий результат може отримати разюче різні оцінки від різних оцінювачів. Оцінювання якості стає невідтворюваним.
+
+**Повторні спроби стають сліпими здогадками.** Коли агент не знає, чому щось не спрацювало, напрямок повторної спроби випадковий. Він може безуспішно стукатись у хибному напрямку — виправляти непов'язані шляхи коду, ігноруючи справжню першопричину. Кожна сліпа повторна спроба спалює токени і час.
+
+**Інформаційна прірва при передачі сесії.** Коли незавершена робота передається наступній сесії, відсутність спостережуваності означає, що нова сесія має діагностувати стан системи з нуля. Спостереження Anthropic за довготривалими агентами показують, що ця надлишкова діагностика може поглинати 30–50% загального часу сесії.
+
+## Реальний сценарій Claude Code
+
+Розглянемо harness, що використовує робочий процес із трьома ролями «планувальник–генератор–оцінювач» для виконання завдання «додати темний режим до застосунку».
+
+**Без спостережуваності:** Планувальник виводить розпливчастий опис. Генератор реалізує темний режим на основі цієї розпливчастості, але результат не відповідає неявним очікуванням планувальника. Оцінювач відхиляє його на основі власних неявних стандартів, але не може сформулювати, що конкретно не так — просто «це не відчувається правильним». Генератор повторює спроби наосліп через розпливчасті причини відхилення. Цикл повторюється 3–4 рази, займає близько 45 хвилин і ледь дає прийнятний результат.
+
+**З повною спостережуваністю:** Планувальник виводить sprint-контракт із переліком компонентів для модифікації, стандартів верифікації для кожного та виключень (наприклад, без стилів для друку). Генератор реалізує відповідно до контракту, а спостережуваність runtime фіксує процес завантаження та застосування стилів кожного компонента. Оцінювач використовує рубрику оцінювання для покрокової оцінки кожного виміру з конкретними доказами: «Контраст кольору кнопки недостатній (стандарт WCAG AA 4.5:1, виміряно 2.1:1).» Одна ітерація дає якісний результат приблизно за 15 хвилин.
+
+Триразова різниця в ефективності. Єдина змінна — спостережуваність.
+
+## Шарувата спостережуваність
+
+Спостережуваність — це не просто «додати більше логів». Вона функціонує на двох шарах, і обидва є необхідними.
+
+```mermaid
+flowchart LR
+ Contract["Define the task upfront<br/>which files to change / what not to touch / pass criteria"] --> Generator["Generator"]
+ Generator --> Signals["Collect at runtime<br/>logs / traces / health checks"]
+ Contract --> Review["Check item by item against the list<br/>functionality / tests / boundaries"]
+ Signals --> Review
+ Review --> Verdict["Point out which item failed<br/>and where to fix it"]
+ Verdict --> Generator
+```
+
+**Спостережуваність runtime:** Сигнали системного рівня — логи, трейси, події процесів, перевірки стану. Відповідає на «що зробила система».
+
+**Спостережуваність процесу:** Бачення артефактів рішень harness — планів, рубрик оцінювання, критеріїв прийняття. Відповідає на «чому цю зміну слід прийняти».
+
+## Ключові поняття
+
+- **Спостережуваність runtime**: Сигнали системного рівня, включаючи логи, трейси, події процесів і перевірки стану. Відповідає на «що зробила система».
+- **Спостережуваність процесу**: Бачення артефактів рішень harness, включаючи плани, рубрики оцінювання й критерії прийняття. Відповідає на «чому цю зміну слід прийняти».
+- **Трейс завдання**: Повний запис шляху рішень від початку завдання до завершення, аналогічний трейсингу запитів у розподілених системах. Кожен крок агента разом із його контекстом фіксується — тому коли щось іде не так, весь процес можна відтворити.
+- **Sprint-контракт**: Короткострокова угода, узгоджена до початку кодування, що визначає обсяг завдання, стандарти верифікації та виключення. Основний інструмент спостережуваності процесу.
+- **Рубрика оцінювача**: Перетворює оцінювання якості із суб'єктивного судження на засноване на доказах структуроване оцінювання, що дозволяє різним оцінювачам приходити до схожих висновків для одного й того самого результату.
+- **Шарувата спостережуваність**: Спостережуваність системного і процесного шарів, спроєктована одночасно й доповнює одна одну. Сигнали runtime пояснюють поведінку; артефакти процесу пояснюють намір.
+
+## Чому агенти не можуть вирішити це самостійно
+
+Ви можете думати: «Хіба агент не може просто виводити власні логи?» Проблема в тому, що:
+
+1. **Агенти не знають того, чого не знають.** Вони не будуть проактивно записувати сигнали, про необхідність яких не здогадуються. Без обмежень на рівні harness агенти логують лише те, що вважають важливим — а те, що вони вважають важливим, зазвичай недостатньо.
+2. **Формати логів непослідовні.** Різні сесії використовують різні формати логів, що унеможливлює систематичний аналіз.
+3. **Спостережуваність процесу не вирішується логуванням.** Sprint-контракти та рубрики оцінювання — це структуровані артефакти, що потребують підтримки на рівні harness — кількох print-інструкцій буде недостатньо.
+
+## Як побудувати спостережуваність
+
+### 1. Вбудуйте збір сигналів runtime у harness
+
+Не покладайтесь на те, що агент сам виводитиме свої логи. Harness повинен автоматично збирати такі сигнали:
+
+- **Життєвий цикл застосунку**: Стани фаз запуску, готовності, роботи, завершення
+- **Виконання функціонального шляху**: Записи виконання критичних шляхів, включаючи точки входу, контрольні точки та виходи
+- **Потік даних**: Записи даних, що течуть між компонентами
+- **Використання ресурсів**: Аномальні патерни використання ресурсів (наприклад, пам'ять, що постійно зростає)
+- **Помилки та винятки**: Повний контекст помилок, а не лише повідомлення про помилки
+
+### 2. Реалізуйте sprint-контракти
+
+До початку кожного завдання генератор і оцінювач (які можуть бути різними викликами одного й того самого агента) узгоджують контракт, що визначає що будувати та як виглядає «готово»:
+
+```markdown
+# Sprint Contract: Dark Mode Support
+
+## Scope
+- Modify the theme toggle component
+- Update global CSS variables
+- Add dark mode tests
+
+## Verification Standards
+- Visual regression tests pass for each component
+- Main flow end-to-end tests pass
+- No flash of unstyled content (FOUC)
+
+## Exclusions
+- Not handling print styles
+- Not handling third-party component dark mode
+```
+
+### 3. Встановіть рубрику оцінювача
+
+Перетворіть «добре чи ні» на кількісне оцінювання:
+
+```markdown
+# Scoring Rubric
+
+| Dimension | A | B | C | D |
+|-----------|---|---|---|---|
+| Code correctness | All tests pass | Main flow passes | Partial pass | Build fails |
+| Architecture compliance | Fully compliant | Minor deviations | Obvious deviations | Serious violations |
+| Test coverage | Main + edge cases | Main flow only | Only skeleton | No tests |
+```
+
+### 4. Стандартизуйте за допомогою OpenTelemetry
+
+Створіть трейс для кожної сесії harness, спан для кожного завдання й під-спани для кожного кроку верифікації. Використовуйте стандартні атрибути для анотування ключової інформації. Так дані спостережуваності інтегруються зі стандартними ланцюжками інструментів (Jaeger, Zipkin).
+
+## Експеримент Anthropic із триагентною архітектурою
+
+У березні 2026 року Anthropic опублікував систематичний harness-експеримент. Вони запускали одне й те саме завдання («побудувати браузерний DAW за допомогою Web Audio API») із трьома різними архітектурами й записували детальні дані по кожній фазі:
+
+| Агент і фаза | Тривалість | Вартість |
+|--------------|-----------|---------|
+| Планувальник | 4,7 хв | $0,46 |
+| Збірка, раунд 1 | 2 год 7 хв | $71,08 |
+| QA, раунд 1 | 8,8 хв | $3,24 |
+| Збірка, раунд 2 | 1 год 2 хв | $36,89 |
+| QA, раунд 2 | 6,8 хв | $3,09 |
+| Збірка, раунд 3 | 10,9 хв | $5,88 |
+| QA, раунд 3 | 9,6 хв | $4,06 |
+| **Разом** | **3 год 50 хв** | **$124,70** |
+
+Кожен із трьох агентів мав чітку роль, і кожен відігравав очевидну частину у спостережуваності:
+
+**Планувальник:** Отримує вимогу користувача з 1–4 речень і розгортає її в повну специфікацію продукту. Йому було доручено «бути сміливим у масштабі» та «зосередитись на контексті продукту й високорівневому технічному проєктуванні, а не на детальній технічній реалізації». Логіка: якщо планувальник передчасно вказує детальні технічні деталі й помиляється, ці помилки каскадуються вниз. Кращий підхід — обмежити результати й дозволити агенту знайти власний шлях під час виконання.
+
+**Генератор:** Реалізує функцію за функцією, спринт за спринтом. Перед кожним спринтом він узгоджує sprint-контракт з оцінювачем, що визначає, що означає «готово» для цього функціонального блоку. Потім реалізує відповідно до контракту, самооцінює та передає в QA.
+
+**Оцінювач:** Використовує Playwright MCP для взаємодії із запущеним застосунком як реальний користувач — тестує функціональність UI, API-ендпоінти та стан бази даних. Він оцінює кожен спринт за чотирма вимірами: глибина продукту, функціональність, візуальний дизайн та якість коду. Кожен вимір має жорсткий поріг — якщо будь-який не відповідає вимогам, спринт провалюється й генератор отримує детальний фідбек для виправлень.
+
+Приклад фідбеку після QA-раунду 1: «Це візуально вражаючий застосунок з хорошою AI-інтеграцією, але кілька основних функцій DAW є лише презентаційними, без глибини взаємодії: кліпи не можна перетягувати/переміщати, немає панелі інструментів (ручки синтезатора, пади барабанів) та немає візуального редактора ефектів (криві EQ, метри компресора).» Це не крайові випадки — це основні взаємодії, що роблять DAW придатним для використання. Конкретний, підкріплений доказами фідбек — не «це не відчувається правильним».
+
+Оцінювач не завжди був таким точним. Ранні версії виявляли розумні проблеми, а потім переконували себе відхилити ці проблеми як несерйозні, в підсумку схвалюючи роботу. Виправлення: читати логи оцінювача, знаходити точки, де його судження розходилось із людським, і оновлювати QA-промпт для вирішення цих конкретних проблем. Після кількох раундів цього циклу розробки оцінювання оцінювача стало надійним.
+
+> Джерело: [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps)
+
+## Ключові висновки
+
+- **Спостережуваність — це властивість архітектури harness.** Це не функція, яку додають постфактум — це базова здатність, що має бути спроєктована з самого початку.
+- **Обидва шари спостережуваності необхідні.** Сигнали runtime пояснюють «що сталось», артефакти процесу пояснюють «чому це було зроблено саме так».
+- **Sprint-контракти зміщують узгодження на початок.** Вони запобігають тому, що генератор будує щось, що оцінювач одразу відхиляє з передбачуваних причин.
+- **Рубрики оцінювання роблять оцінювання відтворюваним.** Різні оцінювачі отримують схожі оцінки для одного й того самого результату.
+- **Відсутність спостережуваності витрачає 30–50% часу сесії на надлишкову діагностику.**
+
+## Додаткова література
+
+- [Observability Engineering - Charity Majors](https://www.honeycomb.io/blog/observability-engineering-book) — Теоретична і практична рамка для сучасної інженерії спостережуваності
+- [Dapper - Google (Sigelman et al.)](https://research.google/pubs/pub36356/) — Проривна практика у великомасштабному розподіленому трейсингу
+- [Harness Design - Anthropic](https://www.anthropic.com/engineering/harness-design-long-running-apps) — Введення sprint-контрактів та рубрик оцінювача
+- [Site Reliability Engineering - Google](https://sre.google/sre-book/table-of-contents/) — Систематичне застосування спостережуваності у виробничих системах
+
+## Вправи
+
+1. **Аналіз прогалин спостережуваності**: Перевірте свій поточний harness на предмет спостережуваності системного та процесного шарів. Знайдіть стани системи, які неможливо розрізнити за наявними сигналами, та запропонуйте доповнення.
+
+2. **Практика sprint-контрактів**: Напишіть sprint-контракт для реального завдання. Нехай агент виконає відповідно до контракту та порівняйте ефективність і якість з контрактом і без.
+
+3. **Побудова трейсу завдання**: Запишіть кожен крок, який агент робить під час повного завдання кодування. Анотуйте за семантичними конвенціями OpenTelemetry. Проаналізуйте трейс на наявність інформаційних вузьких місць — які кроки мають недостатній сигнал для підтримки своїх рішень.
diff --git a/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md b/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md
new file mode 100644
index 0000000..c7b06a7
--- /dev/null
+++ b/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md
@@ -0,0 +1,18 @@
+# Шаблон порівняння бенчмарків
+
+Harness A:
+
+- рівень завершення
+- середня кількість повторних спроб
+- баги, виявлені до перегляду людиною
+
+Harness B:
+
+- рівень завершення
+- середня кількість повторних спроб
+- баги, виявлені до перегляду людиною
+
+Інтерпретація:
+
+- Який harness змінив результат?
+- Який harness змінив вартість отримання результату?
diff --git a/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts b/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts
new file mode 100644
index 0000000..0388cad
--- /dev/null
+++ b/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts
@@ -0,0 +1,216 @@
+/**
+ * benchmark-runner.ts
+ *
+ * Reads a benchmark task definition (JSON array of tasks with pass criteria),
+ * "executes" each task, records timing and pass/fail, outputs a comparison
+ * report showing which tasks pass and which fail.
+ *
+ * Run: npx tsx docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface BenchmarkTask {
+ id: string;
+ name: string;
+ category: string;
+ passCriteria: string[];
+ expectedDurationMs: number;
+ // Simulated actual results
+ actualDurationMs: number;
+ actualPass: boolean;
+ failureReason?: string;
+}
+
+interface BenchmarkResult {
+ id: string;
+ name: string;
+ category: string;
+ criteriaTotal: number;
+ criteriaPassed: number;
+ pass: boolean;
+ expectedMs: number;
+ actualMs: number;
+ durationDelta: number;
+ failureReason?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark task definitions
+// ---------------------------------------------------------------------------
+
+const benchmarkTasks: BenchmarkTask[] = [
+ {
+ id: "bench-001",
+ name: "Import markdown document",
+ category: "Document Pipeline",
+ passCriteria: ["File accepted", "Chunks created", "Metadata stored"],
+ expectedDurationMs: 100,
+ actualDurationMs: 95,
+ actualPass: true,
+ },
+ {
+ id: "bench-002",
+ name: "Import PDF document",
+ category: "Document Pipeline",
+ passCriteria: ["File accepted", "Text extracted", "Chunks created", "Metadata stored"],
+ expectedDurationMs: 200,
+ actualDurationMs: 310,
+ actualPass: false,
+ failureReason: "PDF text extraction failed on page 3 -- encoding issue",
+ },
+ {
+ id: "bench-003",
+ name: "Ask grounded question",
+ category: "Q&A Pipeline",
+ passCriteria: ["Query received", "Relevant chunks retrieved", "Answer generated", "Citations present"],
+ expectedDurationMs: 500,
+ actualDurationMs: 480,
+ actualPass: true,
+ },
+ {
+ id: "bench-004",
+ name: "Ask question with no relevant docs",
+ category: "Q&A Pipeline",
+ passCriteria: ["Query received", "Graceful 'no results' message", "No hallucinated citations"],
+ expectedDurationMs: 400,
+ actualDurationMs: 420,
+ actualPass: false,
+ failureReason: "Model hallucinated a citation instead of saying 'no results'",
+ },
+ {
+ id: "bench-005",
+ name: "Delete imported document",
+ category: "Document Pipeline",
+ passCriteria: ["Document removed from list", "Chunks removed from index", "No orphan data"],
+ expectedDurationMs: 150,
+ actualDurationMs: 145,
+ actualPass: true,
+ },
+ {
+ id: "bench-006",
+ name: "Concurrent user access",
+ category: "Security",
+ passCriteria: ["Users isolated", "No cross-user data leak", "Performance within SLA"],
+ expectedDurationMs: 300,
+ actualDurationMs: 850,
+ actualPass: false,
+ failureReason: "Cross-user data leak detected + response time exceeded SLA (850ms > 500ms)",
+ },
+ {
+ id: "bench-007",
+ name: "Session continuity after restart",
+ category: "Reliability",
+ passCriteria: ["State persisted", "Session recovers", "No data loss"],
+ expectedDurationMs: 200,
+ actualDurationMs: 180,
+ actualPass: true,
+ },
+ {
+ id: "bench-008",
+ name: "API rate limiting",
+ category: "Security",
+ passCriteria: ["Rate limit enforced", "429 response after limit", "Legitimate traffic unaffected"],
+ expectedDurationMs: 100,
+ actualDurationMs: 100,
+ actualPass: true,
+ },
+];
+
+// ---------------------------------------------------------------------------
+// Execution simulation
+// ---------------------------------------------------------------------------
+
+function executeBenchmark(tasks: BenchmarkTask[]): BenchmarkResult[] {
+ return tasks.map((task) => ({
+ id: task.id,
+ name: task.name,
+ category: task.category,
+ criteriaTotal: task.passCriteria.length,
+ criteriaPassed: task.actualPass ? task.passCriteria.length : Math.floor(task.passCriteria.length * 0.5),
+ pass: task.actualPass,
+ expectedMs: task.expectedDurationMs,
+ actualMs: task.actualDurationMs,
+ durationDelta: task.actualDurationMs - task.expectedDurationMs,
+ failureReason: task.failureReason,
+ }));
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function run(): void {
+ console.log("\n" + "=".repeat(100));
+ console.log(" BENCHMARK RUNNER -- Task Execution Report");
+ console.log("=".repeat(100));
+
+ const results = executeBenchmark(benchmarkTasks);
+
+ // Detailed results
+ const header = `| ${pad("ID", 10)}| ${pad("Task", 35)}| ${pad("Category", 18)}| ${pad("Pass?", 6)}| ${pad("Criteria", 10)}| ${pad("Expected", 10)}| ${pad("Actual", 10)}| ${pad("Delta", 8)}|`;
+ const sep = `|${"-".repeat(12)}|${"-".repeat(37)}|${"-".repeat(20)}|${"-".repeat(8)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(12)}|${"-".repeat(10)}|`;
+ console.log("\n" + header);
+ console.log(sep);
+
+ for (const r of results) {
+ const passLabel = r.pass ? "PASS" : "FAIL";
+ const criteriaLabel = `${r.criteriaPassed}/${r.criteriaTotal}`;
+ const deltaLabel = r.durationDelta >= 0 ? `+${r.durationDelta}ms` : `${r.durationDelta}ms`;
+ const marker = r.pass ? " " : ">>";
+
+ console.log(
+ `${marker}| ${pad(r.id, 10)}| ${pad(r.name, 35)}| ${pad(r.category, 18)}| ${pad(passLabel, 6)}| ${pad(criteriaLabel, 10)}| ${pad(r.expectedMs + "ms", 10)}| ${pad(r.actualMs + "ms", 10)}| ${pad(deltaLabel, 8)}|`
+ );
+ }
+
+ // Failure details
+ const failures = results.filter((r) => !r.pass);
+ if (failures.length > 0) {
+ console.log("\n" + "-".repeat(100));
+ console.log(" FAILURE DETAILS");
+ console.log("-".repeat(100));
+ for (const f of failures) {
+ console.log(`\n [${f.id}] ${f.name}`);
+ console.log(` Category: ${f.category}`);
+ console.log(` Criteria: ${f.criteriaPassed}/${f.criteriaTotal} passed`);
+ console.log(` Reason: ${f.failureReason ?? "Unknown"}`);
+ console.log(` Timing: Expected ${f.expectedMs}ms, actual ${f.actualMs}ms (delta: ${f.durationDelta >= 0 ? "+" : ""}${f.durationDelta}ms)`);
+ }
+ }
+
+ // Summary
+ console.log("\n" + "=".repeat(100));
+ console.log(" SUMMARY BY CATEGORY");
+ console.log("=".repeat(100) + "\n");
+
+ const categories = [...new Set(results.map((r) => r.category))];
+ const catHeader = `| ${pad("Category", 20)}| ${pad("Total", 8)}| ${pad("Passed", 8)}| ${pad("Failed", 8)}| ${pad("Pass Rate", 12)}|`;
+ const catSep = `|${"-".repeat(22)}|${"-".repeat(10)}|${"-".repeat(10)}|${"-".repeat(10)}|${"-".repeat(14)}|`;
+ console.log(catHeader);
+ console.log(catSep);
+
+ for (const cat of categories) {
+ const catResults = results.filter((r) => r.category === cat);
+ const catPassed = catResults.filter((r) => r.pass).length;
+ const catFailed = catResults.filter((r) => !r.pass).length;
+ const rate = Math.round((catPassed / catResults.length) * 100);
+
+ console.log(`| ${pad(cat, 20)}| ${pad(String(catResults.length), 8)}| ${pad(String(catPassed), 8)}| ${pad(String(catFailed), 8)}| ${pad(rate + "%", 12)}|`);
+ }
+
+ // Overall
+ const totalPassed = results.filter((r) => r.pass).length;
+ const totalFailed = results.filter((r) => !r.pass).length;
+ console.log("\n" + "-".repeat(100));
+ console.log(` OVERALL: ${totalPassed}/${results.length} passed (${Math.round((totalPassed / results.length) * 100)}%), ${totalFailed} failures`);
+ console.log("=".repeat(100) + "\n");
+}
+
+run();
diff --git a/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md b/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md
new file mode 100644
index 0000000..cca435a
--- /dev/null
+++ b/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md
@@ -0,0 +1,9 @@
+# Приклад циклу очищення
+
+Регулярні завдання очищення:
+
+- сканування застарілої документації
+- сканування структурних порушень
+- оновлення оцінок якості
+- відкриття цільових PR очищення
+- повторний запуск фіксованого зрізу бенчмарку після очищення
diff --git a/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts b/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts
new file mode 100644
index 0000000..6b35905
--- /dev/null
+++ b/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts
@@ -0,0 +1,336 @@
+/**
+ * cleanup-scanner.ts
+ *
+ * Scans a project directory for stale artifacts, dead code, structural
+ * violations, and outputs a cleanup report. Helps enforce the "clean state
+ * at end of every session" principle.
+ *
+ * Usage:
+ * npx tsx docs/lectures/lecture-12.../code/cleanup-scanner.ts [path]
+ * (defaults to current working directory)
+ *
+ * Run: npx tsx docs/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface ScanResult {
+ category: string;
+ check: string;
+ severity: "critical" | "warning" | "info";
+ found: string[];
+ description: string;
+}
+
+// ---------------------------------------------------------------------------
+// Scanner checks
+// ---------------------------------------------------------------------------
+
+interface ScannerCheck {
+ category: string;
+ name: string;
+ severity: "critical" | "warning" | "info";
+ description: string;
+ scan: (dir: string) => string[];
+}
+
+function createChecks(): ScannerCheck[] {
+ return [
+ {
+ category: "Stale Artifacts",
+ name: "Temporary files (*.tmp, *.bak, *.swp)",
+ severity: "warning",
+ description: "Leftover temp files from editing or processing",
+ scan: (dir) => findFiles(dir, [".tmp", ".bak", ".swp", "~"]),
+ },
+ {
+ category: "Stale Artifacts",
+ name: "Debug/log files in source",
+ severity: "warning",
+ description: "Log files that should not be in the source tree",
+ scan: (dir) => {
+ const found: string[] = [];
+ const logPatterns = [".log"];
+ for (const p of findFiles(dir, logPatterns)) {
+ // Only flag log files in source directories
+ if (p.includes("/src/") || p.includes("/lib/") || p.includes("/app/")) {
+ found.push(p);
+ }
+ }
+ return found;
+ },
+ },
+ {
+ category: "Dead Code",
+ name: "Unused imports (placeholder detection)",
+ severity: "info",
+ description: "Files that may contain unused code (heuristic scan)",
+ scan: (dir) => {
+ const found: string[] = [];
+ const srcDirs = ["src", "lib", "app"];
+ for (const srcDir of srcDirs) {
+ const srcPath = path.join(dir, srcDir);
+ if (fs.existsSync(srcPath)) {
+ scanForPatterns(srcPath, ["TODO:", "FIXME:", "HACK:", "XXX:"], found, dir);
+ }
+ }
+ return found;
+ },
+ },
+ {
+ category: "Structural Violations",
+ name: "Missing .gitignore",
+ severity: "warning",
+ description: "No .gitignore file found -- risk of committing build artifacts",
+ scan: (dir) => fs.existsSync(path.join(dir, ".gitignore")) ? [] : [".gitignore (MISSING)"],
+ },
+ {
+ category: "Structural Violations",
+ name: "Build artifacts in source",
+ severity: "critical",
+ description: "Compiled output (dist/, build/) mixed with source",
+ scan: (dir) => {
+ const found: string[] = [];
+ // Check if dist/ or build/ exists inside src/
+ const dirs = ["src/dist", "src/build", "lib/dist", "lib/build"];
+ for (const d of dirs) {
+ if (fs.existsSync(path.join(dir, d))) {
+ found.push(d + "/");
+ }
+ }
+ return found;
+ },
+ },
+ {
+ category: "Structural Violations",
+ name: "node_modules in source tree",
+ severity: "critical",
+ description: "node_modules directory found outside root (nested dependency)",
+ scan: (dir) => {
+ const found: string[] = [];
+ const srcDirs = ["src", "lib", "app", "test", "tests"];
+ for (const srcDir of srcDirs) {
+ const nmPath = path.join(dir, srcDir, "node_modules");
+ if (fs.existsSync(nmPath)) {
+ found.push(srcDir + "/node_modules/");
+ }
+ }
+ return found;
+ },
+ },
+ {
+ category: "Session Cleanliness",
+ name: "Uncommitted changes indicator",
+ severity: "info",
+ description: "Checks for common artifacts of incomplete sessions",
+ scan: (dir) => {
+ const found: string[] = [];
+ const indicators = [
+ "WIP.md", "IN_PROGRESS.md", "scratch.ts", "scratch.js",
+ "debug.ts", "test-manual.ts", "temp.ts",
+ ];
+ for (const f of indicators) {
+ if (fs.existsSync(path.join(dir, f))) {
+ found.push(f);
+ }
+ }
+ return found;
+ },
+ },
+ {
+ category: "Session Cleanliness",
+ name: "Empty directories",
+ severity: "info",
+ description: "Empty directories that may be leftover from incomplete work",
+ scan: (dir) => {
+ const found: string[] = [];
+ const commonDirs = ["src", "lib", "app", "test", "tests", "docs"];
+ for (const d of commonDirs) {
+ const dp = path.join(dir, d);
+ if (fs.existsSync(dp) && fs.statSync(dp).isDirectory()) {
+ try {
+ const contents = fs.readdirSync(dp);
+ if (contents.length === 0) {
+ found.push(d + "/");
+ }
+ } catch {
+ // Skip directories we can't read
+ }
+ }
+ }
+ return found;
+ },
+ },
+ {
+ category: "Configuration",
+ name: "Environment files in source",
+ severity: "critical",
+ description: ".env files that may contain secrets",
+ scan: (dir) => {
+ const found: string[] = [];
+ const envFiles = [".env", ".env.local", ".env.production", ".env.staging"];
+ for (const f of envFiles) {
+ if (fs.existsSync(path.join(dir, f))) {
+ found.push(f);
+ }
+ }
+ return found;
+ },
+ },
+ ];
+}
+
+// ---------------------------------------------------------------------------
+// Helper functions
+// ---------------------------------------------------------------------------
+
+function findFiles(dir: string, extensions: string[]): string[] {
+ const found: string[] = [];
+
+ function walk(current: string, depth: number): void {
+ if (depth > 4) return; // Limit recursion depth
+ try {
+ const entries = fs.readdirSync(current, { withFileTypes: true });
+ for (const entry of entries) {
+ // Skip common non-source directories
+ if (entry.isDirectory() && ["node_modules", ".git", "dist", "build", ".next", "coverage"].includes(entry.name)) {
+ continue;
+ }
+
+ const fullPath = path.join(current, entry.name);
+ const relativePath = path.relative(dir, fullPath);
+
+ if (entry.isDirectory()) {
+ walk(fullPath, depth + 1);
+ } else if (entry.isFile()) {
+ if (extensions.some((ext) => entry.name.endsWith(ext))) {
+ found.push(relativePath);
+ }
+ }
+ }
+ } catch {
+ // Skip directories we can't read
+ }
+ }
+
+ walk(dir, 0);
+ return found;
+}
+
+function scanForPatterns(dir: string, patterns: string[], results: string[], baseDir: string): void {
+ try {
+ const entries = fs.readdirSync(dir, { withFileTypes: true });
+ for (const entry of entries) {
+ if (entry.isDirectory()) {
+ if (!["node_modules", ".git", "dist", "build"].includes(entry.name)) {
+ scanForPatterns(path.join(dir, entry.name), patterns, results, baseDir);
+ }
+ continue;
+ }
+
+ const fullPath = path.join(dir, entry.name);
+ if (!entry.name.endsWith(".ts") && !entry.name.endsWith(".tsx") && !entry.name.endsWith(".js")) {
+ continue;
+ }
+
+ try {
+ const content = fs.readFileSync(fullPath, "utf-8");
+ const lines = content.split("\n");
+ for (let i = 0; i < Math.min(lines.length, 50); i++) {
+ for (const pattern of patterns) {
+ if (lines[i].includes(pattern)) {
+ const relative = path.relative(baseDir, fullPath);
+ results.push(`${relative}:${i + 1} contains ${pattern}`);
+ }
+ }
+ }
+ } catch {
+ // Skip files we can't read
+ }
+ }
+ } catch {
+ // Skip directories we can't read
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+
+function pad(s: string, len: number): string {
+ return s.length >= len ? s : s + " ".repeat(len - s.length);
+}
+
+function run(): void {
+ const targetDir = process.argv[2] ? path.resolve(process.argv[2]) : process.cwd();
+
+ console.log("\n" + "=".repeat(90));
+ console.log(" CLEANUP SCANNER -- Stale Artifact & Violation Report");
+ console.log("=".repeat(90));
+ console.log(` Scanning: ${targetDir}\n`);
+
+ const checks = createChecks();
+ const results: ScanResult[] = [];
+
+ for (const check of checks) {
+ const found = check.scan(targetDir);
+ results.push({
+ category: check.category,
+ check: check.name,
+ severity: check.severity,
+ found,
+ description: check.description,
+ });
+ }
+
+ // Report
+ const header = `| ${pad("Category", 20)}| ${pad("Check", 40)}| ${pad("Severity", 10)}| ${pad("Count", 6)}| Details`;
+ const sep = `|${"-".repeat(22)}|${"-".repeat(42)}|${"-".repeat(12)}|${"-".repeat(8)}|${"-".repeat(30)}`;
+ console.log(header);
+ console.log(sep);
+
+ for (const r of results) {
+ const count = r.found.length;
+ const detail = count > 0 ? r.found.slice(0, 2).join(", ") : "(clean)";
+ const marker = count > 0 && r.severity === "critical" ? ">>" : count > 0 ? " * " : " ";
+
+ console.log(`${marker}| ${pad(r.category, 20)}| ${pad(r.check, 40)}| ${pad(r.severity, 10)}| ${pad(String(count), 6)}| ${detail}`);
+ }
+
+ // Summary
+ const criticals = results.filter((r) => r.severity === "critical" && r.found.length > 0);
+ const warnings = results.filter((r) => r.severity === "warning" && r.found.length > 0);
+ const infos = results.filter((r) => r.severity === "info" && r.found.length > 0);
+ const clean = results.filter((r) => r.found.length === 0);
+
+ console.log("\n" + "=".repeat(90));
+ console.log(" CLEANUP SUMMARY");
+ console.log("=".repeat(90) + "\n");
+
+ console.log(` Critical issues: ${criticals.length}`);
+ console.log(` Warnings: ${warnings.length}`);
+ console.log(` Info items: ${infos.length}`);
+ console.log(` Clean checks: ${clean.length}/${results.length}`);
+
+ if (criticals.length > 0) {
+ console.log("\n ACTION REQUIRED (Critical):");
+ for (const c of criticals) {
+ console.log(` - ${c.check}: ${c.found.length} item(s) found`);
+ console.log(` ${c.description}`);
+ }
+ }
+
+ const totalIssues = results.reduce((s, r) => s + r.found.length, 0);
+ if (totalIssues === 0) {
+ console.log("\n Project is in a clean state. No issues found.\n");
+ } else {
+ console.log(`\n Total issues found: ${totalIssues}. Run this scanner at the end of every session to maintain clean state.\n`);
+ }
+}
+
+run();
diff --git a/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md b/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md
new file mode 100644
index 0000000..0dc7e74
--- /dev/null
+++ b/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md
@@ -0,0 +1,8 @@
+# Код до Лекції 12
+
+Використовуйте цю теку для прикладів:
+
+- зрізів бенчмарків
+- завдань очищення
+- прикладів зниження ентропії
+- повторюваних запусків harness
diff --git a/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
new file mode 100644
index 0000000..8eed39e
--- /dev/null
+++ b/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -0,0 +1,196 @@
+[中文版 →](../../../zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/)
+
+> Приклади коду: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/uk/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/)
+> Практичний проєкт: [Проєкт 06. Побудова повного робочого простору агента](./../../projects/project-06-runtime-observability-and-debugging/index.md)
+
+# Лекція 12. Залишайте чистий стан наприкінці кожної сесії
+
+Ваш агент працює цілий день, змінює 20 файлів, комітить код, і сесія завершується. Наступна сесія стартує і одразу виявляє: збірка зламана, тести червоні, тимчасові debug-файли розкидані скрізь, список функцій не оновлено, а прогрес повністю непрозорий. Перші 30 хвилин нової сесії витрачаються виключно на те, щоб «з'ясувати, що ж насправді зробила попередня сесія».
+
+Як OpenAI, так і Anthropic чітко стверджують: **довгострокова надійність залежить від операційної дисципліни, а не лише від успіху одного запуску.** Якість стану наприкінці кожної сесії безпосередньо визначає ефективність наступної.
+
+## Зростання ентропії — це стан за замовчуванням
+
+Закони Лемана про еволюцію програмного забезпечення говорять нам, що системи, які безперервно змінюються, неминуче ускладнюватимуться, якщо не керувати ними активно. Це особливо справедливо для агентів AI-кодування. Кожна сесія вносить зміни, і без очищення при виході технічний борг накопичується в геометричній прогресії.
+
+Під час п'яти місяців експериментів із Codex OpenAI помітила дещо разюче: **агенти копіюють патерни, що вже є в репозиторії, навіть коли ці патерни непослідовні або неоптимальні.** З часом таке копіювання неминуче призводить до деградації. Перша людина залишає чашку кави в загальному просторі; друга вирішує «і так уже безлад» та залишає ще одну; через тиждень стіл завалений чашками. З кодовою базою відбувається те саме.
+
+Команда OpenAI спочатку витрачала 20% кожної п'ятниці на ручне прибирання «AI-мотлоху», але такий підхід явно не масштабується. Зрештою вони дійшли до систематичного рішення:
+
+1. **Закодувати «золоті правила» в репозиторій**: правила на кшталт «надавайте перевагу спільному utility-пакету перед написаними нашвидкуруч допоміжними функціями» (тримайте інваріанти централізовано) і «не вгадуйте наосліп структури даних» (валідуйте межі або покладайтеся на типізовані SDK). Ці правила конкретні, механічні та автоматично перевірювані.
+2. **Встановити регулярні робочі процеси очищення**: флот фонових завдань Codex, які регулярно сканують відхилення, оновлюють оцінки якості та відкривають цільові PR рефакторингу. Більшість можна переглянути й автоматично злити за хвилину.
+3. **Один раз зафіксувати смак людини, застосовувати його постійно**: коментарі до рев'ю, PR рефакторингу та баги, що дійшли до користувачів, — усе це перекладається в оновлення документації або безпосередньо кодується в інструментарії. Коли документації недостатньо, переводьте правило в код.
+
+Технічний борг — це кредит з високими відсотками. Безперервно погашати його невеликими частинами майже завжди краще, ніж дати йому накопичитися до одного масштабного погашення.
+
+> Джерело: [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/)
+
+## Чистий стан: більше ніж «код компілюється»
+
+Чистий стан — це не просто «код компілюється». Збірка без помилок — найбазовіша вимога: наступна сесія не повинна спочатку виправляти помилки збірки. Усі тести теж мають проходити, включно з тими, що існували до сесії; сесія відповідає за те, щоб не зламати наявний функціонал. І це потрібно перевіряти в CI, а не просто «працює у мене».
+
+```mermaid
+flowchart LR
+ Work["Feature work complete"] --> Build{"Build passes?"}
+ Build -->|yes| Test{"Tests pass?"}
+ Build -->|no| Fix["Fix before exit"]
+ Test -->|yes| Record["Update feature list + progress"]
+ Test -->|no| Fix
+ Record --> Cleanup["Remove temp artifacts / debug code"]
+ Cleanup --> Startup{"Standard startup path works?"}
+ Startup -->|yes| Clean["Clean handoff"]
+ Startup -->|no| Fix
+ Fix --> Build
+```
+
+Але й цього недостатньо. Поточний прогрес має бути зафіксований у машинозчитуваних артефактах: виконані підзавдання з їхніми критеріями проходження, підзавдання в процесі виконання з поточним станом, а також ті, що ще не розпочато. Хороші записи прогресу можуть скоротити час діагностики при запуску сесії на 60–80%. Тимчасові артефакти — debug-логи, тимчасові файли, закоментований код, маркери TODO — також потрібно прибирати, оскільки вони підвищують когнітивне навантаження для наступної сесії. Стандартний шлях запуску теж має залишатися робочим. Чи може наступна сесія приступити до роботи без ручного втручання? Ініціалізація середовища, завантаження кодової бази, отримання контексту, вибір задачі — жоден із цих шляхів не може бути зламаний.
+
+```mermaid
+flowchart LR
+ Dirty["Session ends with<br/>red tests / temp files not deleted / no progress recorded"] --> Diagnose["Next session first has to<br/>figure out what happened"]
+ Diagnose --> Fragile["Then continues modifying<br/>an already messy repo"]
+ Fragile --> More["More debug files, more broken checks,<br/>more unclear progress"]
+ More --> Dirty
+
+ Clean["Session ends with<br/>green tests / progress updated / temp files deleted"] --> Fast["Next session opens the repo<br/>and can keep coding"]
+ Fast --> Stable["No need to fight fires first"]
+ Stable --> Clean
+```
+
+## Основні концепції
+
+- **Чистий стан**: система повинна задовольняти п'ять умов наприкінці сесії — збірка проходить, тести проходять, прогрес зафіксовано, застарілих артефактів немає, шлях запуску доступний. Відсутність будь-якої з умов означає, що сесія не «завершена».
+- **Цілісність сесії**: за аналогією з транзакціями бази даних — або повний коміт і чистий стан, або відкат до останнього узгодженого стану. Ніяких проміжних варіантів.
+- **Документ якості**: активний артефакт, що безперервно фіксує оцінки якості кожного модуля. Не одноразова оцінка, а трекер, що показує, стає кодова база міцнішою чи слабшою з часом.
+- **Цикл очищення**: регулярна сесія технічного обслуговування, спрямована на систематичне зниження ентропії в кодовій базі. Не аварійне виправлення, а рутинні операції.
+- **Спрощення harness**: у міру покращення можливостей моделі — періодично видаляти компоненти harness, які більше не потрібні. Обмеження, яке є необхідним сьогодні, може виявитися зайвим накладним витратами через три місяці.
+- **Ідемпотентне очищення**: операції очищення дають однаковий результат незалежно від кількості запусків, що гарантує безпечність очищення навіть у сценаріях повторних спроб після збою.
+
+## «Прибрати пізніше» означає ніколи не прибирати
+
+Найпоширеніша ментальна пастка — «у цій сесії часу прибирати немає, зроблю наступного разу». Але наступна сесія агента не знає, що ви залишили — вона бачить хаотичний код і невизначений стан. Вона витратить значний час на те, щоб вивести «яка частина цього коду навмисна, а яка тимчасова».
+
+Гірше того, кожна сесія має власні цільові завдання. Нова сесія існує для нової роботи, а не для прибирання безладу попередньої. Вона проігнорує хаос і почне нову роботу поверх нього, додаючи ще більше хаосу. Це петля позитивного зворотного зв'язку ентропії.
+
+Цифри говорять самі за себе. Проєкт, що розроблявся з агентами 12 тижнів без стратегії очищення:
+
+- Тиждень 1: рівень проходження збірки 100%, рівень проходження тестів 100%, запуск нової сесії 5 хв
+- Тиждень 4: збірка 95%, тести 92%, запуск 15 хв
+- Тиждень 8: збірка 82%, тести 78%, запуск 35 хв
+- Тиждень 12: збірка 68%, тести 61%, запуск 60+ хв
+
+Той самий проєкт зі стратегією очищення:
+
+- Тиждень 1: 100%, 100%, 5 хв
+- Тиждень 12: 97%, 95%, 9 хв
+
+Після 12 тижнів: рівень проходження збірки відрізняється на 29 відсоткових пунктів, час запуску нової сесії — на 85%. Це не теорія — це спостережувана різниця.
+
+## Як це зробити
+
+### 1. Чистий стан — необхідна умова завершення
+
+Визначте явно в harness: **завершення сесії = задача проходить верифікацію І перевірка чистого стану проходить.** Відсутність будь-якої з умов означає незавершеність сесії. Запишіть у CLAUDE.md:
+
+```
+## Session Exit Checklist
+- [ ] Build passes (npm run build)
+- [ ] All tests pass (npm test)
+- [ ] Feature list updated
+- [ ] No debug code remaining (console.log, debugger, TODO)
+- [ ] Standard startup path available (npm run dev)
+```
+
+### 2. Двохрежимна стратегія очищення
+
+Поєднуйте два режими очищення:
+
+**Негайне очищення (наприкінці кожної сесії)**: прибирайте тимчасові артефакти, створені під час сесії, оновлюйте стан списку функцій, переконуйтесь у проходженні збірки та тестів. Це очищення за принципом «підрахунку посилань» — прибирайте одразу після того, як щось перестало використовуватись.
+
+**Periodичне очищення (щотижня)**: повне сканування системи — обробка накопичених структурних проблем, оновлення документів якості, запуск бенчмаркових тестів для виявлення деградації. Це очищення за принципом «трасування» — комплексний прохід технічного обслуговування з регулярною каденцією.
+
+### 3. Ведіть документ якості
+
+Документ якості — це активний артефакт, що безперервно оцінює кожний модуль:
+
+```markdown
+# Quality Document
+
+## User Authentication Module (Quality: A)
+- Verification passing: Yes
+- Agent understandable: Yes
+- Test stability: Stable
+- Architecture boundaries: Compliant
+- Code conventions: Followed
+
+## Payment Module (Quality: C)
+- Verification passing: Partial (payment callback untested)
+- Agent understandable: Difficult (logic spread across 3 files)
+- Test stability: Unstable (2 flaky tests)
+- Architecture boundaries: Violations present
+- Code conventions: Partially followed
+```
+
+Нові сесії читають цей документ і одразу знають, що пріоритизувати. Виправляйте спочатку модуль із найнижчою оцінкою.
+
+### 4. Periodично спрощуйте harness
+
+Кожен компонент harness існує тому, що модель не могла самостійно надійно виконати щось. Але з покращенням моделей ці припущення застарівають.
+
+Експерименти Anthropic продемонстрували це безпосередньо. Початковий harness включав механізм розбивки на спринти — ділення роботи на невеликі частини для того, щоб Sonnet 4.5 виконував їх по одній. Коли вийшов Opus 4.6, нативні можливості моделі могли самостійно обробляти декомпозицію роботи, що зробило побудову спринтів зайвими накладними витратами. Після видалення цього компонента агент-будівник міг безперервно працювати понад дві години без відхилень — і насправді ставав плавнішим.
+
+Але з евалюатором ситуація була іншою. Навіть із посиленими можливостями Opus 4.6, коли задачі наближалися до межі можливостей моделі, евалюатор усе ще давав реальну цінність — виявляв відсутній функціонал і заглушки в реалізації генератора. Це означає, що евалюатор — не фіксоване рішення «так/ні»; він залежить від того, де складність задачі знаходиться відносно можливостей моделі.
+
+**Рекомендована практика**: щомісяця обирайте один компонент harness, тимчасово вимикайте його та запускайте бенчмаркові задачі. Якщо результати не погіршуються — видаляйте назавжди. Якщо погіршуються — відновлюйте або замінюйте легшою альтернативою.
+
+Більш глибокий принцип: **у міру покращення моделей цікаві комбінації в harness не зменшуються — вони зміщуються.** Проблеми, які раніше вимагали явних рішень, поглинаються можливостями моделі, але нові межі можливостей відкривають простори дизайну harness, які раніше були неможливі. Завдання AI-інженера — безперервно знаходити наступну цінну комбінацію.
+
+### 5. Операції очищення мають бути ідемпотентними
+
+Скрипти очищення повинні бути безпечними для багаторазового запуску — ще один запуск не повинен давати побічних ефектів:
+
+```bash
+# Idempotent cleanup operations
+rm -f /tmp/debug-*.log # -f ensures no error when files don't exist
+git checkout -- .env.local # Restore to known state
+npm run test # Verify cleanup didn't break anything
+```
+
+### 6. Висока пропускна здатність змінює філософію злиття
+
+Коли вихід агента значно перевищує можливості людини переглядати, традиційна філософія злиття потребує коригування. Досвід команди OpenAI: у середовищі, де агент відкриває 3,5 PR на день (а згодом і більше), мінімізація блокуючих воріт злиття — правильне рішення. PR мають бути короткоживучими; нестабільність тестів зазвичай усувається наступними запусками, а не блокує прогрес безкінечно. У системі, де вартість виправлення низька, а вартість очікування висока, рухатись швидко з швидкими виправленнями — краща стратегія, ніж повільне підтвердження.
+
+**Застереження**: це безвідповідально в середовищі з низькою пропускною здатністю. Але коли вихід агента значно перевищує увагу людини, це часто правильний компроміс. Ключовий критерій: **середня вартість виправлення бага проти середньої вартості очікування, доки людина переглядає PR.** Коли перше нижче другого — швидке злиття є правильним рішенням.
+
+## Реальний кейс
+
+Electron-застосунок, що розроблявся з агентами 12 тижнів, порівняння двох підходів:
+
+**Без стратегії очищення** (контрольна група): тиждень 12, рівень проходження збірки 68%, рівень проходження тестів 61%, запуск нової сесії 60+ хв, 103 застарілих артефакти.
+
+**Зі стратегією очищення** (експериментальна група): повна перевірка чистого стану наприкінці кожної сесії плюс щотижневий цикл очищення. Тиждень 12, рівень проходження збірки 97%, рівень проходження тестів 95%, запуск нової сесії 9 хв, 11 застарілих артефактів.
+
+До тижня 12 рівень проходження збірки в експериментальній групі був вищим на 29 відсоткових пунктів, рівень проходження тестів — на 34 пункти, а час запуску нової сесії — на 85% нижчим. Кожна сесія витрачала додаткові 5 хвилин на очищення, але за 12 тижнів це заощадило десятки годин хаосу.
+
+## Головні висновки
+
+- **Чистий стан — необхідна умова завершення сесії** — не опціональне прибирання, а частина «визначення завершеності».
+- **Усі п'ять вимірів є обов'язковими** — збірка, тести, прогрес, артефакти, запуск — кожен має бути явно перевірений.
+- **Документи якості роблять здоров'я кодової бази відстежуваним** — ви можете проактивно виправляти лише те, про що знаєте, що деградує.
+- **Periodично спрощуйте harness** — у міру покращення можливостей моделі видаляйте обмеження, які більше не потрібні.
+- **«Прибрати пізніше» дорівнює «ніколи не прибирати».** Зростання ентропії — стан за замовчуванням; лише активне очищення протидіє йому.
+
+## Додаткова література
+
+- [Clean Code - Robert C. Martin](https://www.goodreads.com/book/show/3735293-clean-code) — Систематичні принципи чистоти коду
+- [Harness Engineering - OpenAI](https://openai.com/index/harness-engineering/) — Відтворюваність як основна вимога дизайну harness
+- [Effective Harnesses - Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — Критична роль чистих виходів із сесій для довгострокової надійності
+- [Programs, Life Cycles, and Laws of Software Evolution - Lehman](https://ieeexplore.ieee.org/document/1702314) — Закони еволюції програмного забезпечення, що доводять неминуче зростання складності системи без активного обслуговування
+
+## Вправи
+
+1. **Чекліст чистого стану**: розробіть чекліст виходу із сесії для вашої кодової бази, що охоплює всі п'ять вимірів. Застосуйте його протягом 5 послідовних сесій і зафіксуйте кількість порушень за кожним виміром.
+
+2. **Порівняння бенчмарків**: використайте фіксований набір задач із двома варіантами harness (з/без вимог чистого стану). Порівняйте рівень завершення, кількість повторних спроб та рівень виходу дефектів.
+
+3. **Практика спрощення harness**: оберіть один компонент harness, тимчасово вимкніть його та запустіть бенчмаркові задачі. Порівняйте результати з ним і без нього. Вирішіть: залишити, видалити або замінити.
diff --git a/docs/uk/projects/index.md b/docs/uk/projects/index.md
new file mode 100644
index 0000000..c7d86cf
--- /dev/null
+++ b/docs/uk/projects/index.md
@@ -0,0 +1,23 @@
+# Ласкаво просимо до проєктів
+
+Це практична частина курсу Learn Harness Engineering. Читати лекції недостатньо — потрібно самостійно будувати середовища та спостерігати, як Codex, Claude Code або інші AI-агенти поводяться за різних правил.
+
+## Огляд проєктів
+
+Курс містить 6 послідовних практичних проєктів, які навчають, як побудувати надійне робоче середовище для агента з нуля:
+
+1. **Тільки промпт vs. правила спочатку**: Порівняйте, як агент виконує завдання з одним промптом і з базовим harness.
+2. **Простір роботи, зрозумілий агенту**: Дізнайтеся, як структурувати репозиторій, щоб він був зручний для AI, і як організувати механізми передачі роботи.
+3. **Безперервність між сесіями**: Спроєктуйте файли стану та скрипти ініціалізації, щоб агент міг безперервно відновлювати роботу між сесіями.
+4. **Зворотний зв'язок у runtime та контроль обсягу**: Запровадьте інструменти, які дозволяють агенту тестувати власний код і виправляти помилки під час виконання.
+5. **Самоверифікація та розподіл ролей**: Побудуйте незалежний механізм перевірки, щоб запобігти галюцинаціям і передчасному оголошенню завершення.
+6. **Повний harness (підсумковий проєкт)**: Зберіть фінальне, спостережуване, наскрізне робоче середовище агента.
+
+## Як діяти
+
+Кожна папка проєкту зазвичай містить:
+- `starter/`: Ваш початковий простір роботи.
+- `solution/`: Референсну реалізацію (якщо ви зайшли в глухий кут).
+- Інструкції до завдання з описом контексту та конкретних цілей.
+
+Для виконання завдань у директорії `starter/` використовуйте будь-який AI-агент для написання коду (наприклад, Claude Code, Cursor, Trae).
diff --git a/docs/uk/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/uk/projects/project-01-baseline-vs-minimal-harness/index.md
new file mode 100644
index 0000000..78b08d1
--- /dev/null
+++ b/docs/uk/projects/project-01-baseline-vs-minimal-harness/index.md
@@ -0,0 +1,36 @@
+[中文版本 →](../../../zh/projects/project-01-baseline-vs-minimal-harness/)
+
+> Пов'язані лекції: [Лекція 01. Потужні моделі не гарантують надійне виконання](./../../lectures/lecture-01-why-capable-agents-still-fail/index.md) · [Лекція 02. Що насправді означає harness](./../../lectures/lecture-02-what-a-harness-actually-is/index.md)
+> Файли шаблонів: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/uk/resources/templates/)
+
+# Проєкт 01. Тільки промпт vs. правила спочатку: наскільки велика різниця
+
+## Що ви робите
+
+Побудуйте мінімальну оболонку Electron-застосунку для бази знань — вікно зі списком документів ліворуч, панель запитань і відповідей праворуч та локальна директорія даних. Саме завдання не є складним. Складність — у тому, як змусити агента виконати його.
+
+Ви запускаєте завдання двічі. Перший раз: лише промпт, без підготовки. Другий раз: `AGENTS.md`, `init.sh`, `feature_list.json` заздалегідь розміщені в репозиторії. Потім порівнюєте результати.
+
+Цей сценарій курсу використовує короткий інтервал повторного ознайомлення/підготовки як приклад, а не як фіксований вимірюваний результат.
+
+## Інструменти
+
+- Claude Code або Codex (оберіть один, використовуйте для обох запусків)
+- Git (керування гілками та порівняння)
+- Node.js + Electron (стек проєкту)
+- Таймер (фіксуйте тривалість кожного запуску)
+
+## Механізм harness
+
+Мінімальний harness: `AGENTS.md` + `init.sh` + `feature_list.json`
+
+## Використовуйте зафіксований у репозиторії проєкт
+
+Шлях у репозиторії: [`projects/project-01/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-01)
+
+| Директорія | Що містить | Як використовувати |
+|------|------|------|
+| [`starter/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-01/starter) | Запуск зі слабким harness. Містить лише [`task-prompt.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-01/starter/task-prompt.md) як опис завдання та не містить `AGENTS.md` або `feature_list.json`. | Передайте промпт вашому AI-агенту для написання коду та виміряйте, що він виконає без додаткової структури. |
+| [`solution/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-01/solution) | Той самий продуктовий зріз з явними артефактами harness: [`AGENTS.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-01/solution/AGENTS.md), [`CLAUDE.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-01/solution/CLAUDE.md), [`init.sh`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-01/solution/init.sh), [`feature_list.json`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-01/solution/feature_list.json) та [`claude-progress.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-01/solution/claude-progress.md). | Порівняйте, як те саме завдання конкретизується через правила та докази верифікації. |
+
+Чотири конкретні функції: запуск вікна, список документів, панель запитань та створення локальної директорії даних. Перегляньте `solution/feature_list.json`, щоб дізнатися про очікувані докази для кожної функції.
diff --git a/docs/uk/projects/project-02-agent-readable-workspace/index.md b/docs/uk/projects/project-02-agent-readable-workspace/index.md
new file mode 100644
index 0000000..ac63c95
--- /dev/null
+++ b/docs/uk/projects/project-02-agent-readable-workspace/index.md
@@ -0,0 +1,33 @@
+[中文版本 →](../../../zh/projects/project-02-agent-readable-workspace/)
+
+> Пов'язані лекції: [Лекція 03. Зробіть репозиторій єдиним джерелом правди](./../../lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md) · [Лекція 04. Розподіляйте інструкції між файлами](./../../lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)
+> Файли шаблонів: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/uk/resources/templates/)
+
+# Проєкт 02. Зробіть проєкт зрозумілим і відновлюйте роботу з місця зупинки
+
+## Що ви робите
+
+Додайте «зрозумілість» до репозиторію, щоб новий агент міг швидко зрозуміти структуру проєкту, дізнатися поточний прогрес і продовжити роботу. Конкретно: реалізуйте імпорт документів, деталізований перегляд документа та локальну персистентність — протягом двох сесій.
+
+Ви запускаєте завдання двічі з зафіксованих у репозиторії директорій: спочатку з тоншим стартовим простором роботи без `session-handoff.md`, потім з варіантом рішення, який має розширені `ARCHITECTURE.md`, `PRODUCT.md` та `session-handoff.md`.
+
+## Інструменти
+
+- Claude Code або Codex
+- Git
+- Node.js + Electron
+
+## Механізм harness
+
+Простір роботи, зрозумілий агенту, + файли постійного стану
+
+## Використовуйте зафіксований у репозиторії проєкт
+
+Шлях у репозиторії: [`projects/project-02/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-02)
+
+| Директорія | Що містить | Що порівнювати |
+|------|------|------|
+| [`starter/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-02/starter) | Код проєкту 01 плюс незавершені імпорт документів, деталізований перегляд і персистентність. Документи існують, але навмисно є тоншими, і відсутній `session-handoff.md`. | Скільки повторного ознайомлення виконує друга сесія агента. |
+| [`solution/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-02/solution) | Той самий зріз у завершеному вигляді, з розширеними документами в [`projects/project-02/solution/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-02/solution) (плюс [`feature_list.json`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-02/solution/feature_list.json) та [`session-handoff.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-02/solution/session-handoff.md)). | Чи може нова сесія відновити роботу зі стану репозиторію без усного контексту. |
+
+Продуктові функції: імпорт документів, повне завантаження деталей/вмісту документа та персистентність між перезапусками. Функція harness — простір роботи, зрозумілий для передачі між сесіями.
diff --git a/docs/uk/projects/project-03-multi-session-continuity/index.md b/docs/uk/projects/project-03-multi-session-continuity/index.md
new file mode 100644
index 0000000..aff821e
--- /dev/null
+++ b/docs/uk/projects/project-03-multi-session-continuity/index.md
@@ -0,0 +1,33 @@
+[中文版本 →](../../../zh/projects/project-03-multi-session-continuity/)
+
+> Пов'язані лекції: [Лекція 05. Зберігайте контекст між сесіями](./../../lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md) · [Лекція 06. Ініціалізуйте перед кожною сесією агента](./../../lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)
+> Файли шаблонів: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/uk/resources/templates/)
+
+# Проєкт 03. Підтримуйте роботу агента під час перезапуску сесій
+
+## Що ви робите
+
+Додайте контроль обсягу та перевірочні шлюзи до агента. Реалізуйте розбиття документів на частини, вилучення метаданих, відображення прогресу індексування та потік запитань і відповідей на основі цитат. Використовуйте `feature_list.json` для відстеження статусу функцій — по одній функції за раз, без позначення як «пройдено» без доказів верифікації.
+
+Ви порівнюєте зафіксовані в репозиторії стартову версію та рішення: стартова версія має лише початкову поверхню відстеження, тоді як рішення додає більш суворі артефакти перезапуску та передачі роботи навколо того самого списку функцій.
+
+## Інструменти
+
+- Claude Code або Codex
+- Git
+- Node.js + Electron
+
+## Механізм harness
+
+Журнал прогресу + передача сесії + безперервність між сесіями + верифікація по одній функції за раз
+
+## Використовуйте зафіксований у репозиторії проєкт
+
+Шлях у репозиторії: [`projects/project-03/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-03)
+
+| Директорія | Що містить | Що порівнювати |
+|------|------|------|
+| [`starter/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-03/starter) | Код проєкту 02 з незавершеними індексуванням і grounded QA. Містить початковий [`feature_list.json`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-03/starter/feature_list.json), але бракує фінальних артефактів перезапуску/передачі. | Чи відхиляється агент між кількома функціями або чи втрачає стан після перезапуску. |
+| [`solution/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-03/solution) | Завершене розбиття на частини, метадані, статус індексу та QA на основі цитат, плюс [`init.sh`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-03/solution/init.sh), [`session-handoff.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-03/solution/session-handoff.md), [`claude-progress.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-03/solution/claude-progress.md) та [`clean-state-checklist.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-03/solution/clean-state-checklist.md). | Чи є конкретні докази верифікації для кожної функції до того, як вона позначається як пройдена. |
+
+Цей проєкт — не загальна вправа з «кількох сесій». Зафіксоване в репозиторії рішення відповідає чотирьом конкретним продуктовим функціям: розбиття документів на частини, вилучення метаданих, інтерфейс статусу індексування та grounded Q&A з цитатами.
diff --git a/docs/uk/projects/project-04-incremental-indexing/index.md b/docs/uk/projects/project-04-incremental-indexing/index.md
new file mode 100644
index 0000000..9a82fbc
--- /dev/null
+++ b/docs/uk/projects/project-04-incremental-indexing/index.md
@@ -0,0 +1,36 @@
+[中文版本 →](../../../zh/projects/project-04-incremental-indexing/)
+
+> Пов'язані лекції: [Лекція 07. Встановлюйте чіткі межі завдань для агентів](./../../lectures/lecture-07-why-agents-overreach-and-under-finish/index.md) · [Лекція 08. Використовуйте списки функцій для обмеження дій агента](./../../lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)
+> Файли шаблонів: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/uk/resources/templates/)
+
+# Проєкт 04. Використовуйте зворотний зв'язок у runtime для корекції поведінки агента
+
+## Що ви робите
+
+Додайте спостережуваність у runtime (журнали запуску, журнали імпорту/індексування, стани помилок) та архітектурні обмеження для запобігання порушенням між шарами. Посадіть помилку у runtime, яку агент має виправити.
+
+Ви порівнюєте зафіксовані в репозиторії стартову версію та рішення: стартова версія має слабку діагностику і жодного скрипта перевірки архітектури, тоді як рішення додає структуровані журнали, перевірки меж і виправлення помилки.
+
+## Інструменти
+
+- Claude Code або Codex
+- Git
+- Node.js + Electron
+
+## Механізм harness
+
+Зворотний зв'язок у runtime + контроль обсягу + інкрементальне індексування
+
+## Використовуйте зафіксований у репозиторії проєкт
+
+Шлях у репозиторії: [`projects/project-04/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-04)
+
+| Директорія | Що містить | Що порівнювати |
+|------|------|------|
+| [`starter/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-04/starter) | Код проєкту 03 зі слабкою діагностикою. Навмисно посаджений дефект індексування може спричинити збій розбиття великих файлів на частини, і відсутній скрипт перевірки архітектури. | Скільки часу агент витрачає на пошук першопричини без сигналів runtime. |
+| [`solution/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-04/solution) | Структурований логер, документи та скрипт меж архітектури, виправлена логіка розбиття та [`clean-state-checklist.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-04/solution/clean-state-checklist.md). | Чи роблять журнали та перевірки меж виправлення швидшим і менш інвазивним. |
+
+Конкретні файли для перевірки: [`projects/project-04/solution/src/services/logger.ts`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-04/solution/src/services/logger.ts),
+[`projects/project-04/solution/scripts/check-architecture.sh`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-04/solution/scripts/check-architecture.sh),
+[`projects/project-04/solution/docs/ARCHITECTURE.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-04/solution/docs/ARCHITECTURE.md) та
+[`projects/project-04/solution/src/services/indexing-service.ts`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-04/solution/src/services/indexing-service.ts).
diff --git a/docs/uk/projects/project-05-grounded-qa-verification/index.md b/docs/uk/projects/project-05-grounded-qa-verification/index.md
new file mode 100644
index 0000000..aa7e299
--- /dev/null
+++ b/docs/uk/projects/project-05-grounded-qa-verification/index.md
@@ -0,0 +1,35 @@
+[中文版本 →](../../../zh/projects/project-05-grounded-qa-verification/)
+
+> Пов'язані лекції: [Лекція 09. Зупиніть агентів від передчасного оголошення перемоги](./../../lectures/lecture-09-why-agents-declare-victory-too-early/index.md) · [Лекція 10. Лише повний прогін конвеєра вважається справжньою верифікацією](./../../lectures/lecture-10-why-end-to-end-testing-changes-results/index.md)
+> Файли шаблонів: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/uk/resources/templates/)
+
+# Проєкт 05. Змусьте агента верифікувати власну роботу
+
+## Що ви робите
+
+Реалізуйте розподіл ролей — генератор, який реалізує, оцінювач, який перевіряє, та опційно планувальник. Запустіть тричі, щоб виміряти ефект кожної доданої ролі.
+
+Оберіть суттєве покращення функціональності (багатоходова розмова, редизайн панелі цитат або фільтрація документів) і підтримуйте його незмінним у всіх запусках.
+
+## Інструменти
+
+- Claude Code або Codex
+- Git
+- Node.js + Electron
+
+## Механізм harness
+
+Самоверифікація + grounded Q&A + завершення на основі доказів
+
+## Використовуйте зафіксований у репозиторії проєкт
+
+Шлях у репозиторії: [`projects/project-05/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-05)
+
+| Директорія | Що містить | Що порівнювати |
+|------|------|------|
+| [`starter/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-05/starter) | Застосунок на основі проєкту 04 до оновлення функції збереження історії розмови. | Відправна точка, якщо ви хочете самостійно перезапустити три варіанти. |
+| [`solution/single-role/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-05/solution/single-role) | Один агент планує, реалізує та самостійно перевіряє. | Оцінка [`evaluator-rubric.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-05/solution/single-role/evaluator-rubric.md): 1,6/5 і перелік дефектів. |
+| [`solution/gen-eval/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-05/solution/gen-eval) | Генератор плюс оцінювач із доказами ревізії. | Оцінка [`evaluator-rubric.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-05/solution/gen-eval/evaluator-rubric.md): 3,3/5 і нотатки щодо ревізій. |
+| [`solution/plan-gen-eval/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-05/solution/plan-gen-eval) | Планувальник плюс генератор плюс оцінювач. | [`sprint-contract.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-05/solution/plan-gen-eval/sprint-contract.md), оцінка [`evaluator-rubric.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-05/solution/plan-gen-eval/evaluator-rubric.md): 4,9/5. |
+
+Зафіксована в репозиторії функція — збереження історії багатоходової розмови Q&A. Підтримуйте цю функцію незмінною у всіх трьох варіантах, щоб єдиною змінною був розподіл ролей.
diff --git a/docs/uk/projects/project-06-runtime-observability-and-debugging/index.md b/docs/uk/projects/project-06-runtime-observability-and-debugging/index.md
new file mode 100644
index 0000000..7107abb
--- /dev/null
+++ b/docs/uk/projects/project-06-runtime-observability-and-debugging/index.md
@@ -0,0 +1,36 @@
+[中文版本 →](../../../zh/projects/project-06-runtime-observability-and-debugging/)
+
+> Пов'язані лекції: [Лекція 11. Зробіть runtime агента спостережуваним](./../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) · [Лекція 12. Чистий перехід наприкінці кожної сесії](./../../lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)
+> Файли шаблонів: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/uk/resources/templates/)
+
+# Проєкт 06. Побудуйте повний harness агента (підсумковий проєкт)
+
+## Що ви робите
+
+Це підсумковий проєкт. Зберіть усе, чого ви навчилися в перших п'яти проєктах, запустіть повний бенчмарк, а потім виконайте прохід очищення, щоб переконатися, що якість підтримувана.
+
+Використовуйте фіксований набір багатофункціональних завдань, що охоплює повний продуктовий зріз: імпорт документів, індексування, Q&A на основі цитат, спостережуваність у runtime та зрозумілий перезапускуваний стан репозиторію. Спочатку запустіть зі слабким базовим harness, потім із вашим найсильнішим harness, далі — очищення та повторний запуск. Нарешті, проведіть абляційний експеримент harness — видаляйте по одному компоненту і спостерігайте, які з них насправді мають значення.
+
+## Інструменти
+
+- Claude Code або Codex
+- Git
+- Node.js + Electron
+- Шаблон якісного документа
+- Рубрика оцінювача
+- Усі компоненти harness, накопичені з перших п'яти проєктів
+
+## Механізм harness
+
+Повний harness: усі механізми + спостережуваність + абляційне дослідження
+
+## Використовуйте зафіксований у репозиторії проєкт
+
+Шлях у репозиторії: [`projects/project-06/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-06)
+
+| Директорія | Що містить | Що порівнювати |
+|------|------|------|
+| [`starter/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-06/starter) | Здебільшого завершений продуктовий код із навмисно слабкою поверхнею harness: базовий [`AGENTS.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-06/starter/AGENTS.md), без `feature_list.json`, без `session-handoff.md`, без чеклисту чистого стану. | Ручні спостереження базового рівня зі слабким harness. Стартова версія навмисно не містить скриптів бенчмарку. |
+| [`solution/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/projects/project-06/solution) | Повна поверхня harness: [`AGENTS.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-06/solution/AGENTS.md), [`CLAUDE.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-06/solution/CLAUDE.md), [`feature_list.json`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-06/solution/feature_list.json), [`init.sh`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-06/solution/init.sh), [`session-handoff.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-06/solution/session-handoff.md), [`clean-state-checklist.md`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-06/solution/clean-state-checklist.md), документи якості/оцінювача, скрипти бенчмарку та очищення. | Запустіть [`projects/project-06/solution/scripts/benchmark.sh`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-06/solution/scripts/benchmark.sh) та [`projects/project-06/solution/scripts/cleanup-scanner.sh`](https://github.com/walkinglabs/learn-harness-engineering/blob/main/projects/project-06/solution/scripts/cleanup-scanner.sh), потім порівняйте докази з якісних документів. |
+
+На відміну від попередніх проєктів, стартова версія підсумкового проєкту не є здебільшого неповною з точки зору продуктових функцій. Основний пробіл — у робочому harness навколо застосунку.
diff --git a/docs/uk/resources/index.md b/docs/uk/resources/index.md
new file mode 100644
index 0000000..566d766
--- /dev/null
+++ b/docs/uk/resources/index.md
@@ -0,0 +1,59 @@
+# Бібліотека ресурсів
+
+Ця папка перетворює методи курсу на готові до копіювання шаблони та компактні
+довідники, які можна використовувати в реальному репозиторії.
+
+## Коли використовувати
+
+Починайте тут, якщо ви хочете, щоб Codex, Claude Code або інший агент кодування
+працював впродовж кількох сесій без постійного повторного виведення налаштувань,
+статусу та обсягу задач.
+
+Особливо корисно, коли:
+
+- робота охоплює кілька сесій
+- функцій багато і їх легко залишити напівзробленими
+- агенти схильні оголошувати перемогу завчасно
+- кроки запуску доводиться відкривати заново щоразу
+
+## Починайте тут
+
+Для мінімального налаштування почніть із:
+
+- кореневих інструкцій: [`templates/AGENTS.md`](./templates/AGENTS.md) або [`templates/CLAUDE.md`](./templates/CLAUDE.md)
+- стану функцій: [`templates/feature_list.json`](./templates/feature_list.json)
+- журналу прогресу: [`templates/claude-progress.md`](./templates/claude-progress.md)
+- довідника по сценарію завантаження: `docs/uk/resources/templates/init.sh`
+
+Потім додайте:
+
+- передачу сесії: [`templates/session-handoff.md`](./templates/session-handoff.md)
+- контрольний список чистого виходу: [`templates/clean-state-checklist.md`](./templates/clean-state-checklist.md)
+- рубрику оцінювача: [`templates/evaluator-rubric.md`](./templates/evaluator-rubric.md)
+
+Якщо вам потрібна повна структура репозиторію у стилі OpenAI з публікації
+"Harness engineering", скористайтесь розширеним пакетом:
+
+- [`openai-advanced/index.md`](./openai-advanced/index.md)
+
+## Структура бібліотеки
+
+- [`templates/`](./templates/index.md): шаблони для копіювання в реальний репозиторій
+- [`reference/`](./reference/index.md): нотатки щодо методів, процес запуску та карти режимів збою
+- [`openai-advanced/`](./openai-advanced/index.md): розширений скелет репозиторію,
+ документи системи обліку та шаблони управління для агентів
+
+## Рекомендований мінімальний пакет
+
+- `AGENTS.md` або `CLAUDE.md`
+- `feature_list.json`
+- `claude-progress.md`
+- `init.sh`
+
+Цих чотирьох файлів достатньо, щоб зробити більшість робочих процесів з агентами
+помітно стабільнішими.
+
+Коли репозиторій переростає в довгострокову систему з кількома доменами, активними
+планами, оцінюванням якості та політиками надійності, переходьте до пакету
+[`openai-advanced/`](./openai-advanced/index.md) замість того, щоб надто
+розтягувати мінімальний пакет.
diff --git a/docs/uk/resources/openai-advanced/index.md b/docs/uk/resources/openai-advanced/index.md
new file mode 100644
index 0000000..927aca7
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/index.md
@@ -0,0 +1,83 @@
+# OpenAI Advanced Pack
+
+Ця тека містить більш структурований вигляд репозиторію, описаний у статті
+OpenAI "Harness engineering: leveraging Codex in an agent-first world",
+упакований у готові до копіювання стартові файли.
+
+Використовуйте цей пакет, коли мінімального harness вже недостатньо і ваш репозиторій
+потребує:
+
+- короткого `AGENTS.md` у стилі маршрутизатора
+- постійних документів-системи-обліку всередині репозиторію
+- активних і завершених планів виконання
+- явних файлів політики продукту, надійності, безпеки та фронтенду
+- оцінки якості за продуктовим доменом і архітектурним шаром
+- теок з довідковими матеріалами, зручними для моделей
+- стандартних операційних процедур для архітектури, фіксації знань і верифікації runtime
+
+## Стартовий макет
+
+Стартовий пакет у [`repo-template/`](./repo-template/index.md) відтворює
+таку структуру:
+
+```text
+AGENTS.md
+ARCHITECTURE.md
+docs/
+├── design-docs/
+│ ├── index.md
+│ └── core-beliefs.md
+├── exec-plans/
+│ ├── active/
+│ ├── completed/
+│ └── tech-debt-tracker.md
+├── generated/
+│ └── db-schema.md
+├── product-specs/
+│ ├── index.md
+│ └── new-user-onboarding.md
+├── references/
+│ ├── design-system-reference-llms.txt
+│ ├── nixpacks-llms.txt
+│ └── uv-llms.txt
+├── DESIGN.md
+├── FRONTEND.md
+├── PLANS.md
+├── PRODUCT_SENSE.md
+├── QUALITY_SCORE.md
+├── RELIABILITY.md
+└── SECURITY.md
+```
+
+## Як прийняти цей пакет
+
+1. Почніть з мінімального пакету, якщо репозиторій ще невеликий.
+2. Скопіюйте файли з [`repo-template/`](./repo-template/index.md) у власний
+ репозиторій, коли потрібна міцніша структура.
+3. Тримайте `AGENTS.md` коротким. Розглядайте його як маршрутизатор до глибших
+ документів, а не як енциклопедію.
+4. Оновлюйте документи якості, надійності та планів у процесі звичайної роботи,
+ а не в окремий день прибирання.
+5. Робіть згенеровані артефакти та зовнішні посилання явними, щоб агенти могли
+ їх знаходити без опори на історію чатів.
+
+## Бібліотека SOP
+
+Тека [`sops/`](./sops/index.md) перетворює діаграми зі статті на
+покрокові операційні процедури:
+
+- налаштування багаторівневої доменної архітектури
+- фіксація прихованих знань у репозиторії
+- локальний стек спостережуваності та робочий процес зворотного зв'язку
+- цикл валідації через Chrome DevTools для UI-роботи
+
+## Принципи проектування
+
+- Короткий вхідний пункт, глибші пов'язані документи
+- Репозиторій як система обліку
+- Механічні перевірки перемагають запам'ятовані правила
+- Плани та історія якості живуть поруч із кодом
+- Прибирання та спрощення є відповідальністю першого рівня
+
+Цей пакет є навмисно структурованим, але його все одно слід адаптувати під ваш
+проєкт, а не копіювати сліпо.
diff --git a/docs/uk/resources/openai-advanced/repo-template/AGENTS.md b/docs/uk/resources/openai-advanced/repo-template/AGENTS.md
new file mode 100644
index 0000000..ed064f7
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/repo-template/AGENTS.md
@@ -0,0 +1,59 @@
+# AGENTS.md
+
+Цей репозиторій оптимізований для тривалої роботи агентів з кодом. Тримайте цей файл
+коротким. Використовуйте його як маршрутизатор до основних документів системи, а не як
+великий звалювальник інструкцій.
+
+## Стартовий робочий процес
+
+Перед змінами у коді:
+
+1. Підтвердьте корінь репозиторію за допомогою `pwd`.
+2. Прочитайте `ARCHITECTURE.md` — поточну карту системи та жорсткі правила залежностей.
+3. Прочитайте `docs/QUALITY_SCORE.md`, щоб дізнатися, які домени або шари найслабші.
+4. Прочитайте `docs/PLANS.md`, а потім відкрийте активний план, з якого ви працюєте.
+5. Прочитайте відповідну специфікацію продукту в `docs/product-specs/`.
+6. Запустіть стандартний шлях завантаження та верифікації для цього репозиторію.
+7. Якщо базова верифікація зазнає невдачі, виправте базовий стан перед розширенням обсягу.
+
+## Карта маршрутизації
+
+- `ARCHITECTURE.md`: карта доменів, модель шарів, правила залежностей
+- `docs/design-docs/index.md`: проєктні рішення та ключові принципи
+- `docs/product-specs/index.md`: поточна поведінка продукту та цільові критерії прийнятності
+- `docs/PLANS.md`: життєвий цикл плану та політика планів виконання
+- `docs/QUALITY_SCORE.md`: здоров'я доменів продукту та шарів
+- `docs/RELIABILITY.md`: сигнали runtime, бенчмарки та очікування щодо перезапуску
+- `docs/SECURITY.md`: секрети, пісочниця, дані та правила зовнішніх дій
+- `docs/FRONTEND.md`: обмеження інтерфейсу, правила дизайн-системи, перевірки доступності
+
+## Робочий договір
+
+- Працюйте з одним обмеженим планом або фрагментом функціональності за раз.
+- Не позначайте роботу виконаною лише на основі перевірки коду; потрібні докази запуску.
+- Якщо ви змінюєте поведінку, оновіть відповідні документи продукту, плану або надійності
+ в тій самій сесії.
+- Якщо ви бачите повторний зворотний зв'язок при ревью, перетворіть його на механічне
+ правило, перевірку або лінтер — замість того, щоб повторно пояснювати в чаті.
+- Тримайте згенеровані матеріали в `docs/generated/`, а першоджерела — в `docs/references/`.
+- Надавайте перевагу додаванню невеликих актуальних документів замість збільшення цього файлу.
+
+## Визначення готовності
+
+Зміна вважається готовою лише тоді, коли виконані всі наступні умови:
+
+- цільову поведінку реалізовано
+- необхідна верифікація фактично виконана
+- докази прив'язані до відповідного плану або документа якості
+- уражені документи залишаються актуальними
+- репозиторій може чисто перезапуститися зі стандартного стартового шляху
+
+## Кінець сесії
+
+Перед завершенням сесії:
+
+1. Оновіть активний план виконання.
+2. Оновіть `docs/QUALITY_SCORE.md`, якщо будь-який домен або шар суттєво змінився.
+3. Зафіксуйте новий борг у `docs/exec-plans/tech-debt-tracker.md`, якщо ви його відклали.
+4. Перемістіть завершені плани до `docs/exec-plans/completed/` за потреби.
+5. Залиште репозиторій у стані, придатному до перезапуску, з чітко визначеною наступною дією.
diff --git a/docs/uk/resources/openai-advanced/repo-template/ARCHITECTURE.md b/docs/uk/resources/openai-advanced/repo-template/ARCHITECTURE.md
new file mode 100644
index 0000000..1a88715
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/repo-template/ARCHITECTURE.md
@@ -0,0 +1,57 @@
+# ARCHITECTURE.md
+
+Цей файл є картою системи верхнього рівня. Він має залишатися стислим та посилатися на
+більш детальні документи за потреби.
+
+## Форма системи
+
+- Продукт: `[замінити назвою продукту]`
+- Основний робочий процес користувача: `[замінити основним процесом]`
+- Поверхні runtime: `[desktop / web / cli / services / workers]`
+- Джерело істини для поведінки продукту: `docs/product-specs/`
+
+## Карта доменів
+
+| Домен | Призначення | Основні точки входу | Пов'язана специфікація |
+|-------|-------------|---------------------|------------------------|
+| `[domain-a]` | `[що він охоплює]` | `[modules / routes / commands]` | `[spec path]` |
+| `[domain-b]` | `[що він охоплює]` | `[modules / routes / commands]` | `[spec path]` |
+
+## Модель шарів
+
+Використовуйте фіксовану напрямлену модель, щоб агенти не вигадували архітектуру ad hoc:
+
+`Types -> Config -> Repo -> Service -> Runtime -> UI`
+
+Наскрізні завдання мають входити через явні межі провайдера або адаптера, а не
+звертатися між шарами напряму.
+
+## Жорсткі правила залежностей
+
+- Нижні шари не повинні залежати від верхніх.
+- UI не повинен обходити контракти runtime або сервісів.
+- Доступ до даних має здійснюватися через репозиторії або еквівалентні адаптери.
+- Спільні утиліти мають залишатися загальними та не накопичувати доменну логіку.
+- Нові залежності мають бути обґрунтовані у відповідному плані або документі проєктування.
+
+## Наскрізні інтерфейси
+
+| Завдання | Затверджена межа | Примітки |
+|----------|-----------------|---------|
+| Логування та трасування | `[provider / utility path]` | `[тільки структуровано, без довільного console]` |
+| Автентифікація | `[provider path]` | `[правила токена/сесії]` |
+| Зовнішні API | `[client or provider path]` | `[обмеження швидкості / поради щодо повторних спроб]` |
+| Прапорці функцій | `[flag boundary]` | `[власник]` |
+
+## Поточні проблемні зони
+
+- `[область, яку найважче безпечно змінювати агентам]`
+- `[область зі слабкими межами або крихкими тестами]`
+
+## Контрольний список змін
+
+Коли ви торкаєтеся коду, що стосується архітектури:
+
+1. Оновіть цей файл, якщо змінилася карта доменів або дозволені межі.
+2. Оновіть відповідний документ проєктування в `docs/design-docs/`, якщо змінилося обґрунтування.
+3. Додайте або оновіть виконувану перевірку, якщо правило має виконуватися механічно.
diff --git a/docs/uk/resources/openai-advanced/repo-template/docs/DESIGN.md b/docs/uk/resources/openai-advanced/repo-template/docs/DESIGN.md
new file mode 100644
index 0000000..45eec1b
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/repo-template/docs/DESIGN.md
@@ -0,0 +1,28 @@
+# DESIGN.md
+
+Цей файл є точкою входу для проєктування. Тримайте його коротким і використовуйте для
+маршрутизації до більш детальних файлів у `docs/design-docs/`.
+
+## Призначення
+
+Фіксуйте тривалі рішення щодо продукту та системного проєктування, які мають
+пережити одну розмову, спринт або пам'ять рецензента.
+
+## Читайте цей файл, коли
+
+- вам потрібна поточна філософія проєктування
+- ви збираєтеся ввести новий патерн
+- вам потрібно знати, які рішення щодо проєктування є остаточними, а які ще відкриті
+
+## Канонічні документи проєктування
+
+- `docs/design-docs/index.md`: індекс прийнятих, запропонованих і застарілих документів
+- `docs/design-docs/core-beliefs.md`: загальні для проєкту принципи, орієнтовані на агентів
+
+## Правила проєктування
+
+- Тримайте документи проєктування невеликими й актуальними.
+- Надавайте перевагу одному документу на область рішення.
+- Пов'язуйте документи проєктування з планами та специфікаціями, коли зміна залежить від них.
+- Якщо правило проєктування стає операційно критичним, перетворіть його на автоматизовану
+ перевірку або оновіть `ARCHITECTURE.md`.
diff --git a/docs/uk/resources/openai-advanced/repo-template/docs/FRONTEND.md b/docs/uk/resources/openai-advanced/repo-template/docs/FRONTEND.md
new file mode 100644
index 0000000..3bd6502
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/repo-template/docs/FRONTEND.md
@@ -0,0 +1,25 @@
+# FRONTEND.md
+
+Цей файл визначає стабільні очікування frontend, щоб агенти не вигадували UI-патерни
+непередбачувано.
+
+## Принципи UI
+
+- Оптимізуйте для ясності, а не новизни.
+- Тримайте інтерфейсні потоки такими, що легко знайти та можна перезапустити.
+- Надавайте перевагу невеликій кількості повторно використовуваних компонентів замість
+ одноразових варіантів.
+- Перевірки доступності є частиною звичайної верифікації, а не роботи з поліруванням.
+
+## Запобіжні заходи
+
+- Документуйте дизайн-систему або бібліотеку компонентів у `docs/references/`.
+- Фіксуйте ключові стани, видимі користувачеві: порожній, завантаження, успіх, помилка, повтор.
+- Тримайте тексти, поведінку клавіатури та візуальну ієрархію послідовними між потоками.
+- Коли виправляєте UI-помилку, додайте або оновіть відповідний крок валідації.
+
+## Очікування верифікації
+
+- Збирайте докази для критичних шляхів користувача.
+- Фіксуйте кроки валідації браузера або runtime у відповідному плані.
+- Якщо візуальні регресії є частими, стандартизуйте перевірки знімків екрана або DOM.
diff --git a/docs/uk/resources/openai-advanced/repo-template/docs/PLANS.md b/docs/uk/resources/openai-advanced/repo-template/docs/PLANS.md
new file mode 100644
index 0000000..83ae89b
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/repo-template/docs/PLANS.md
@@ -0,0 +1,35 @@
+# PLANS.md
+
+Цей файл визначає, як плани виконання створюються, оновлюються, завершуються та
+архівуються.
+
+## Коли потрібен план
+
+Створюйте план виконання, якщо робота:
+
+- охоплює більше однієї сесії
+- змінює більше однієї підсистеми
+- має нетривіальну верифікацію або ризики розгортання
+- залежить від відкритих рішень, які мають бути зафіксовані
+
+## Розташування планів
+
+- `docs/exec-plans/active/`: плани, що наразі керують роботою
+- `docs/exec-plans/completed/`: завершені плани, збережені для майбутнього контексту агентів
+- `docs/exec-plans/tech-debt-tracker.md`: відкладена робота та подальші дії
+
+## Мінімальні розділи плану
+
+- мета
+- обсяг та поза обсягом
+- шлях верифікації
+- ризики та блокери
+- журнал прогресу
+- відкриті рішення
+
+## Операційні правила
+
+- Один активний план повинен мати один чітко визначений поточний крок.
+- Оновлюйте план по ходу роботи; не ставтеся до нього як до статичного тексту.
+- Якщо рішення змінює напрям реалізації, зафіксуйте це в плані.
+- Переміщуйте завершені плани до `completed/`, щоб агенти могли знаходити попередній контекст.
diff --git a/docs/uk/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md b/docs/uk/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md
new file mode 100644
index 0000000..38f71a5
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md
@@ -0,0 +1,26 @@
+# PRODUCT_SENSE.md
+
+Цей файл фіксує тривале продуктове судження, яке агенти не можуть надійно
+вивести лише з коду.
+
+## Ядро продукту
+
+- Основний користувач: `[замінити]`
+- Завдання, що виконується: `[замінити]`
+- Основне розчарування, яке потрібно усунути: `[замінити]`
+- Планка якості для прийнятності: `[замінити]`
+
+## Правила продукту
+
+- Надавайте перевагу надійності, видимій користувачеві, над кількістю функцій.
+- Розглядайте неоднозначну поведінку як прогалину в специфікації, а не як дозвіл вгадувати.
+- Якщо реалізація змінює те, що бачать або чому довіряють користувачі, оновіть відповідну специфікацію.
+- Використовуйте специфікації продукту для конкретних потоків, а цей файл — для наскрізних
+ продуктових пріоритетів.
+
+## Заборонені патерни
+
+- Приховані деструктивні дії
+- Тихі збої без зворотного зв'язку для користувача
+- Незрозуміле джерело істини для видимого стану
+- Функції, які неможливо пояснити одним реченням
diff --git a/docs/uk/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md b/docs/uk/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md
new file mode 100644
index 0000000..bcea857
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md
@@ -0,0 +1,39 @@
+# QUALITY_SCORE.md
+
+Цей документ відстежує, чи стає репозиторій міцнішим або слабшим з часом.
+
+## Шкала оцінювання
+
+- `A`: верифіковано, читабельно, стабільно, межі дотримуються
+- `B`: працює з незначними прогалинами
+- `C`: частково працює, помітна плутанина або нестабільність
+- `D`: зламано, небезпечно або структурно незрозуміло
+
+## Домени продукту
+
+| Домен | Оцінка | Верифікація | Читабельність для агентів | Стабільність тестів | Ключові прогалини | Останнє оновлення |
+|-------|--------|-------------|--------------------------|---------------------|-------------------|-------------------|
+| `[domain-a]` | - | - | - | - | - | - |
+| `[domain-b]` | - | - | - | - | - | - |
+| `[domain-c]` | - | - | - | - | - | - |
+
+## Архітектурні шари
+
+| Шар | Оцінка | Дотримання меж | Читабельність для агентів | Ключові прогалини | Останнє оновлення |
+|-----|--------|----------------|--------------------------|-------------------|-------------------|
+| Types | - | - | - | - | - |
+| Services | - | - | - | - | - |
+| Runtime | - | - | - | - | - |
+| UI | - | - | - | - | - |
+
+## Знімки бенчмарків
+
+| Дата | Варіант Harness | Відсоток Завершення | Повторні спроби | Дефекти до ревью | Примітки |
+|------|-----------------|---------------------|-----------------|------------------|---------|
+| YYYY-MM-DD | `[baseline / improved / simplified]` | - | - | - | - |
+
+## Журнал спрощень
+
+| Дата | Видалений Компонент | Результат | Рішення |
+|------|---------------------|-----------|---------|
+| YYYY-MM-DD | `[component]` | `[degraded / unchanged]` | `[restore / keep removed]` |
diff --git a/docs/uk/resources/openai-advanced/repo-template/docs/RELIABILITY.md b/docs/uk/resources/openai-advanced/repo-template/docs/RELIABILITY.md
new file mode 100644
index 0000000..3e339a4
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/repo-template/docs/RELIABILITY.md
@@ -0,0 +1,32 @@
+# RELIABILITY.md
+
+Цей файл визначає, як система доводить, що вона здорова та може перезапуститися.
+
+## Стандартні шляхи
+
+- Завантаження: `[command]`
+- Верифікація: `[command]`
+- Запуск застосунку або сервісу: `[command]`
+- Налагодження або інспекція runtime: `[command]`
+
+## Обов'язкові сигнали Runtime
+
+- структуровані журнали для запуску та критичних потоків
+- перевірки стану здоров'я для ключових сервісів
+- дані трасування або таймінгу для повільних шляхів, коли доступні
+- стани помилок, видимі користувачеві, для відновлюваних збоїв
+
+## Золоті шляхи
+
+- `[шлях 1]`
+- `[шлях 2]`
+- `[шлях 3]`
+
+Кожен золотий шлях повинен мати повторюваний шлях верифікації та чіткі сигнали збою.
+
+## Правила надійності
+
+- Жодна функція не є завершеною, якщо після неї система не може чисто перезапуститися.
+- Збої runtime мають діагностуватися за сигналами, доступними локально в репозиторії.
+- Якщо з'являється повторюваний режим збою, додайте для нього бенчмарк або запобіжний захід.
+- Очищення є частиною надійності, а не окремою проблемою.
diff --git a/docs/uk/resources/openai-advanced/repo-template/docs/SECURITY.md b/docs/uk/resources/openai-advanced/repo-template/docs/SECURITY.md
new file mode 100644
index 0000000..5cb6f7b
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/repo-template/docs/SECURITY.md
@@ -0,0 +1,27 @@
+# SECURITY.md
+
+Цей файл визначає правила безпеки та захисту, які агенти не мають права вгадувати.
+
+## Секрети та облікові дані
+
+- Ніколи не вбудовуйте секрети у вихідний код або документацію.
+- Документуйте тут затверджені шляхи завантаження секретів.
+- Видаляйте токени, ключі API та персональні дані з журналів і знімків екрана.
+
+## Ненадійний ввід
+
+- Ставтеся до зовнішнього вмісту як до ненадійного, поки не перевірено.
+- Фіксуйте тут дозволені межі завантаження або виконання.
+- Якщо існує ризик ін'єкції в промпт або ін'єкції команди, задокументуйте запобіжний захід.
+
+## Зовнішні дії
+
+- Перелічіть, які дії вимагають явного підтвердження.
+- Зафіксуйте всі продуктивні або деструктивні команди, які агенти не мають запускати за замовчуванням.
+- Надавайте перевагу безпечним для пісочниці робочим процесам при налагодженні та верифікації.
+
+## Правила залежностей та ревью
+
+- Нові залежності мають бути обґрунтовані в активному плані.
+- Зміни, що стосуються безпеки, вимагають явних кроків верифікації.
+- Повторні коментарі при ревью безпеки мають ставати перевірками, а не племінними знаннями.
diff --git a/docs/uk/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md b/docs/uk/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md
new file mode 100644
index 0000000..2ad2823
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md
@@ -0,0 +1,9 @@
+# Ключові принципи
+
+- Репозиторій є системою запису для агентів.
+- `AGENTS.md` — це маршрутизатор, а не енциклопедія.
+- Докази верифікації важливіші за впевненість.
+- Одне обмежене завдання краще, ніж багато напівзавершених.
+- Повторний зворотний зв'язок від людей має ставати повторно використовуваними правилами harness.
+- Очищення та спрощення є частиною випуску, а не доопрацюванням після нього.
+- Якщо агент не може знайти факт у репозиторії, вважайте цей факт операційно недоступним.
diff --git a/docs/uk/resources/openai-advanced/repo-template/docs/design-docs/index.md b/docs/uk/resources/openai-advanced/repo-template/docs/design-docs/index.md
new file mode 100644
index 0000000..29af1ce
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/repo-template/docs/design-docs/index.md
@@ -0,0 +1,21 @@
+# Індекс документів проєктування
+
+Використовуйте цей індекс як доступну карту історії проєктних рішень.
+
+## Прийняті
+
+- `core-beliefs.md`: принципи роботи агентів та тривалі норми проєкту
+
+## Запропоновані
+
+- `[додайте тут шляхи до нових документів проєктування]`
+
+## Застарілі
+
+- `[перемістіть сюди старі або замінені документи проєктування з посиланнями на замінники]`
+
+## Правила підтримки
+
+- Кожен документ проєктування повинен мати власника або тригер для оновлення.
+- Видаляйте застарілі документи або позначайте їх як застарілі замість того, щоб залишати їх дрейфувати.
+- Пов'язуйте активні плани виконання з документами проєктування, від яких вони залежать.
diff --git a/docs/uk/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md b/docs/uk/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md
new file mode 100644
index 0000000..dec3c0c
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md
@@ -0,0 +1,10 @@
+# Активні плани
+
+Зберігайте один файл Markdown на кожен активний план виконання в цій папці.
+
+Рекомендований шаблон імені файлу:
+
+- `YYYY-MM-DD-коротка-тема.md`
+
+Кожен активний план має бути достатньо актуальним, щоб нова сесія агента могла
+відновити роботу лише з репозиторію.
diff --git a/docs/uk/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md b/docs/uk/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md
new file mode 100644
index 0000000..6631b3b
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md
@@ -0,0 +1,5 @@
+# Завершені плани
+
+Переміщуйте готові плани сюди замість того, щоб їх видаляти. Завершені плани є
+частиною поверхні пам'яті репозиторію та допомагають майбутнім запускам агентів
+зрозуміти, чому код виглядає саме так.
diff --git a/docs/uk/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md b/docs/uk/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md
new file mode 100644
index 0000000..ac0fc5d
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md
@@ -0,0 +1,7 @@
+# Трекер технічного боргу
+
+Використовуйте цей файл для боргу, який є реальним, визнаним і навмисно відкладеним.
+
+| Дата | Область | Борг | Причина відкладення | Ризик | Наступний Тригер |
+|------|---------|------|---------------------|-------|-----------------|
+| YYYY-MM-DD | `[area]` | `[debt]` | `[reason]` | `[risk]` | `[when to revisit]` |
diff --git a/docs/uk/resources/openai-advanced/repo-template/docs/generated/db-schema.md b/docs/uk/resources/openai-advanced/repo-template/docs/generated/db-schema.md
new file mode 100644
index 0000000..02b2afa
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/repo-template/docs/generated/db-schema.md
@@ -0,0 +1,14 @@
+# Схема бази даних
+
+Використовуйте цю папку для згенерованих або похідних артефактів, які агенти мають
+мати змогу перевіряти без зворотного інжинірингу з коду.
+
+## Джерело
+
+- Згенеровано з: `[command or source path]`
+- Останнє оновлення: `YYYY-MM-DD`
+
+## Примітки
+
+- Не редагуйте вручну згенеровані розділи.
+- Перегенеруйте цей файл, коли змінюється базова схема.
diff --git a/docs/uk/resources/openai-advanced/repo-template/docs/product-specs/index.md b/docs/uk/resources/openai-advanced/repo-template/docs/product-specs/index.md
new file mode 100644
index 0000000..feefdb5
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/repo-template/docs/product-specs/index.md
@@ -0,0 +1,13 @@
+# Індекс специфікацій продукту
+
+Використовуйте цю папку для актуальних специфікацій поведінки продукту, видимої користувачеві.
+
+## Активні специфікації
+
+- `new-user-onboarding.md`
+
+## Правила
+
+- Специфікації мають описувати поведінку, видиму користувачеві, та критерії прийнятності.
+- Якщо реалізація розходиться зі специфікацією, оновіть один із них в тій самій сесії.
+- Тримайте цей індекс актуальним, щоб новий агент міг швидко дізнатися про обсяг продукту.
diff --git a/docs/uk/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md b/docs/uk/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md
new file mode 100644
index 0000000..8081a3b
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md
@@ -0,0 +1,26 @@
+# Онбординг нового користувача
+
+## Мета
+
+Описати досвід першого запуску, який має отримати новий користувач.
+
+## Початкові умови
+
+- `[стан до початку потоку]`
+
+## Потік користувача
+
+1. `[крок перший]`
+2. `[крок другий]`
+3. `[крок третій]`
+
+## Критерії прийнятності
+
+- `[спостережуваний результат]`
+- `[спостережуваний результат]`
+- `[спостережуваний результат]`
+
+## Стани збою
+
+- `[відновлювана помилка та зворотний зв'язок для користувача]`
+- `[заблокований стан і запасний варіант]`
diff --git a/docs/uk/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txt b/docs/uk/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txt
new file mode 100644
index 0000000..6f1c612
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txt
@@ -0,0 +1,9 @@
+Purpose: store model-friendly reference material for the design system.
+
+Suggested contents:
+- component naming rules
+- spacing and typography tokens
+- state variants
+- accessibility expectations
+
+Keep this file concise and refresh it when the upstream design system changes.
diff --git a/docs/uk/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txt b/docs/uk/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txt
new file mode 100644
index 0000000..c30cc9c
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txt
@@ -0,0 +1,8 @@
+Purpose: store a clean agent-readable extract of the deployment or packaging
+rules your repository depends on.
+
+Suggested contents:
+- build entrypoints
+- runtime assumptions
+- environment variable expectations
+- common failure signatures
diff --git a/docs/uk/resources/openai-advanced/repo-template/docs/references/uv-llms.txt b/docs/uk/resources/openai-advanced/repo-template/docs/references/uv-llms.txt
new file mode 100644
index 0000000..f2ceba9
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/repo-template/docs/references/uv-llms.txt
@@ -0,0 +1,8 @@
+Purpose: store a compact reference for your Python package and environment
+workflow when `uv` or similar tooling matters to the repo.
+
+Suggested contents:
+- install and sync commands
+- lockfile policy
+- virtualenv expectations
+- verification commands
diff --git a/docs/uk/resources/openai-advanced/repo-template/index.md b/docs/uk/resources/openai-advanced/repo-template/index.md
new file mode 100644
index 0000000..e7f727a
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/repo-template/index.md
@@ -0,0 +1,24 @@
+# Розширений шаблон репозиторію
+
+Скопіюйте цей стартовий набір у реальний репозиторій, якщо хочете отримати
+документаційну поверхню у стилі OpenAI, орієнтовану на агентів, замість лише мінімального harness.
+
+## Порядок копіювання
+
+1. Скопіюйте `AGENTS.md` і `ARCHITECTURE.md` до кореня репозиторію.
+2. Скопіюйте всю директорію `docs/`.
+3. Заповніть `docs/PRODUCT_SENSE.md`, `docs/QUALITY_SCORE.md` і
+ `docs/RELIABILITY.md` насамперед.
+4. Додайте свій перший активний план у `docs/exec-plans/active/`.
+5. Тримайте вхідні файли короткими та направляйте деталі до пов'язаних документів.
+
+## Для чого оптимізовано цей шаблон
+
+- тривалий локальний контекст репозиторію
+- прогресивне розкриття інформації замість одного великого файлу інструкцій
+- явний життєвий цикл планів
+- відстеження якості з часом
+- читабельні межі для агентів і людей
+
+Ставтеся до кожного файлу тут як до стартового. Замінюйте заповнювачі, приклади та
+зразки команд реальними деталями вашого проєкту перед використанням.
diff --git a/docs/uk/resources/openai-advanced/sops/chrome-devtools-validation-loop.md b/docs/uk/resources/openai-advanced/sops/chrome-devtools-validation-loop.md
new file mode 100644
index 0000000..6e253f9
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/sops/chrome-devtools-validation-loop.md
@@ -0,0 +1,51 @@
+# SOP: Цикл валідації через Chrome DevTools
+
+Використовуйте цей SOP, коли UI-робота залежить від реальної runtime-взаємодії,
+а знімки екрана, стан DOM і виведення консолі важливіші за одну лише інспекцію коду.
+
+## Мета
+
+Перетворити валідацію UI на повторюваний цикл взаємодії, який агент може
+запускати до отримання чистого результату.
+
+## Основний цикл
+
+1. Вибрати цільову сторінку або екземпляр застосунку.
+2. Очистити застарілий шум консолі.
+3. Зафіксувати стан ДО.
+4. Запустити UI-шлях.
+5. Спостерігати runtime-події під час взаємодії.
+6. Зафіксувати стан ПІСЛЯ.
+7. Застосувати виправлення та перезапустити застосунок за потреби.
+8. Повторювати валідацію до отримання чистого результату.
+
+## Необхідні вхідні дані
+
+- стабільна команда запуску
+- відтворюваний UI-шлях користувача
+- засіб для знімків DOM, консолі або скріншотів
+- правило визначення «чистого» стану
+
+## Виконання SOP
+
+1. Записати цільовий шлях в активний план.
+2. Визначити успіх у вимірюваних термінах: текст присутній, кнопка активна,
+ помилка зникла, консоль чиста, запит успішний.
+3. Зробити знімок початкового стану перед взаємодією.
+4. Запускати рівно один шлях за раз.
+5. Фіксувати runtime-події, зміни DOM і видиме виведення.
+6. Якщо шлях не вдається, виправити найменший відповідальний шар і перезапустити.
+7. Повторити той самий шлях і порівняти свідчення ДО/ПІСЛЯ.
+
+## Критерії чистоти
+
+- передбачений видимий стан присутній
+- несподівані помилки відсутні
+- шум консолі зрозумілий або очищений
+- повторний запуск того самого шляху дає той самий результат
+
+## Артефакти репозиторію для оновлення
+
+- активний план виконання
+- `docs/RELIABILITY.md`, якщо шлях стає золотим еталоном
+- специфікація продукту, якщо видима поведінка змінилась
diff --git a/docs/uk/resources/openai-advanced/sops/encode-knowledge-into-repo.md b/docs/uk/resources/openai-advanced/sops/encode-knowledge-into-repo.md
new file mode 100644
index 0000000..8a184fb
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/sops/encode-knowledge-into-repo.md
@@ -0,0 +1,46 @@
+# SOP: Фіксація прихованих знань у репозиторії
+
+Використовуйте цей SOP, коли важливий контекст досі живе в Google Docs,
+тредах чатів, тікетах або головах людей.
+
+## Мета
+
+Зробити знання, невидимі для агента, доступними для виявлення в кодовій базі,
+щоб нова сесія могла діяти на їх основі без опори на попередні розмови.
+
+## Сигнали-тригери
+
+- Агент продовжує запитувати, як працює система.
+- Люди кажуть «ми вирішили це в Slack» або «дотримуйся того, що X сказав минулого тижня».
+- Рев'ю посилаються на правила продукту або безпеки, яких немає у репозиторії.
+- Нові сесії повторюють роботу виявлення, яка вже мала бути зафіксована.
+
+## Виконання SOP
+
+1. Перелічити невидимі джерела знань: документи, чати, негласні командні правила, усні рішення.
+2. Для кожного джерела запитати: це архітектура, поведінка продукту, політика безпеки,
+ очікування надійності, контекст плану чи довідковий матеріал?
+3. Зафіксувати у відповідному артефакті репозиторію:
+ - архітектура -> `ARCHITECTURE.md`
+ - поведінка продукту -> `docs/product-specs/`
+ - обґрунтування дизайну -> `docs/design-docs/`
+ - стан виконання -> `docs/exec-plans/`
+ - повторювані зовнішні посилання -> `docs/references/`
+ - очікування якості або надійності -> `docs/QUALITY_SCORE.md` або `docs/RELIABILITY.md`
+4. Замінювати розмиті формулювання операційно корисними.
+5. Видаляти або позначати як застарілі дублікати, щоб репозиторій зберігав одну
+ знайдену істину.
+
+## Правила якісної фіксації
+
+- Писати для виявлення, а не для літературної повноти.
+- Надавати перевагу коротким документам із зрозумілими назвами файлів.
+- Зв'язувати пов'язані артефакти між собою.
+- Зберігати стійкі правила, а не протоколи нарад.
+- Оновлювати репозиторій у тій самій сесії, в якій приймається рішення.
+
+## Визначення завершення
+
+- Свіжий агент може знайти відповідне правило без запиту до людини.
+- Один і той самий факт не розкиданий по кількох суперечливих файлах.
+- Новий артефакт розташований поруч із кодом або процесом, який він регулює.
diff --git a/docs/uk/resources/openai-advanced/sops/index.md b/docs/uk/resources/openai-advanced/sops/index.md
new file mode 100644
index 0000000..b6db9b4
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/sops/index.md
@@ -0,0 +1,25 @@
+# OpenAI Advanced SOPs
+
+Ці SOP перекладають операційні патерни зі статті в конкретні плейбуки
+виконання, яким можна слідувати або які можна адаптувати.
+
+## Включені SOP
+
+- [`layered-domain-architecture.md`](./layered-domain-architecture.md):
+ встановити явні шари та міжшарові межі
+- [`encode-knowledge-into-repo.md`](./encode-knowledge-into-repo.md):
+ перенести невидимі знання з чатів, документів і пам'яті у файли всередині репозиторію
+- [`observability-feedback-loop.md`](./observability-feedback-loop.md):
+ надати агентам логи, метрики, трейси та повторюваний цикл налагодження
+- [`chrome-devtools-validation-loop.md`](./chrome-devtools-validation-loop.md):
+ використовувати браузерну автоматизацію та знімки для валідації UI-поведінки до досягнення чистого стану
+
+## Як ними користуватися
+
+1. Виберіть SOP, що відповідає вашому поточному вузькому місцю.
+2. Використовуйте контрольний список для налаштування відсутніх артефактів або інструментів.
+3. Зафіксуйте отримані правила у скопійованих документах `repo-template/`.
+4. Перетворюйте повторювані зауваження на рев'ю у перевірки, скрипти або захисні бар'єри.
+
+Ці процедури не призначені для сліпого виконання. Вони покликані зробити harness
+більш прозорим, керованим і відтворюваним.
diff --git a/docs/uk/resources/openai-advanced/sops/layered-domain-architecture.md b/docs/uk/resources/openai-advanced/sops/layered-domain-architecture.md
new file mode 100644
index 0000000..c7dd401
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/sops/layered-domain-architecture.md
@@ -0,0 +1,50 @@
+# SOP: Багаторівнева доменна архітектура
+
+Використовуйте цей SOP, коли агент постійно порушує межі, дублює логіку між
+шарами або виробляє код, який стає важко рев'ювати після кількох сесій.
+
+## Мета
+
+Зробити доменні межі достатньо явними, щоб агенти могли рухатися швидко без
+непомітної деградації структури.
+
+## Цільова модель
+
+Усередині бізнес-домену надавайте перевагу такому напрямку потоку:
+
+`Types -> Config -> Repo -> Service -> Runtime -> UI`
+
+Наскрізні аспекти мають входити через явні провайдери або адаптери.
+Спільні утиліти залишаються поза доменом і не повинні накопичувати доменну логіку.
+
+## Контрольний список налаштування
+
+- Визначити поточні домени в `ARCHITECTURE.md`.
+- Записати дозволені напрями залежностей в `ARCHITECTURE.md`.
+- Зафіксувати наскрізні інтерфейси: аутентифікацію, телеметрію, зовнішні API.
+- Додати одну коротку нотатку про найскладніше поточне порушення межі.
+- Вирішити, що має бути забезпечено механічно — лінтером, тестами або скриптами.
+
+## Виконання SOP
+
+1. Нанести кодову базу на карту доменів до змін стилю реалізації.
+2. Для кожного домену визначити допустиму послідовність шарів.
+3. Виявити всі наскрізні аспекти та маршрутизувати їх через провайдери або адаптери.
+4. Перемістити неоднозначну спільну логіку або в домен-власник, або в справді загальні утиліти.
+5. Задокументувати правила в `ARCHITECTURE.md`.
+6. Додати один виконуваний захисний бар'єр для порушення з найвищою вартістю.
+7. Оновити оцінку якості після змін.
+
+## Визначення завершення
+
+- Свіжий агент може визначити, якому шару належить зміна.
+- UI-код більше не звертається безпосередньо до репозиторію або зовнішніх побічних ефектів.
+- Наскрізні аспекти мають іменовані точки входу.
+- Принаймні одна важлива межа забезпечена механічно.
+
+## Артефакти репозиторію для оновлення
+
+- `ARCHITECTURE.md`
+- `docs/QUALITY_SCORE.md`
+- `docs/design-docs/` коли обґрунтування змінилось
+- `docs/PLANS.md` або активний план виконання
diff --git a/docs/uk/resources/openai-advanced/sops/observability-feedback-loop.md b/docs/uk/resources/openai-advanced/sops/observability-feedback-loop.md
new file mode 100644
index 0000000..7805fc6
--- /dev/null
+++ b/docs/uk/resources/openai-advanced/sops/observability-feedback-loop.md
@@ -0,0 +1,45 @@
+# SOP: Цикл зворотного зв'язку спостережуваності
+
+Використовуйте цей SOP, коли налагодження повільне, агенти продовжують заявляти
+про успіх без доказів або runtime-поведінка важча для інспекції, ніж сам код.
+
+## Мета
+
+Надати агенту локальний цикл зворотного зв'язку через логи, метрики, трейси та
+відтворювані навантаження, щоб він міг міркувати на основі виконання, а не лише
+інспекції коду.
+
+## Мінімальний стек
+
+- застосунок видає структуровані логи
+- застосунок видає метрики та трейси там, де це доцільно
+- локальний шар збору або розподілу сигналів
+- інтерфейси запитів для логів, метрик і трейсів
+- відтворюване навантаження або шлях користувача для повторного запуску після кожної зміни
+
+## Виконання SOP
+
+1. Визначити золоті runtime-шляхи, які мають найбільше значення.
+2. Додати структуровані логи до запуску та критичного шляху.
+3. Додати метрики для затримки, кількості збоїв або глибини черги там, де це корисно.
+4. Додати трейси або маркери часу для повільних або багатокрокових потоків.
+5. Зробити сигнали доступними для запиту з локального середовища розробки.
+6. Надати агенту одне відтворюване навантаження або сценарій для повторного запуску.
+7. Вимагати цикл: запит -> кореляція -> міркування -> реалізація -> перезапуск ->
+ повторний запуск -> верифікація.
+
+## Контрольний список сесії налагодження
+
+- Що не вдалось?
+- Який сигнал доводить збій?
+- Якому шару належить збій?
+- Що змінилось після виправлення?
+- Чи перезапустився застосунок чисто?
+- Чи пройшло те саме навантаження після повторного запуску?
+
+## Визначення завершення
+
+- Агент може пояснити режим збою на основі runtime-свідчень.
+- Те саме навантаження можна повторно запустити після кожної зміни.
+- Перезапуск і повторний запуск є частиною нормального циклу завдання.
+- Сигнали надійності задокументовані в `docs/RELIABILITY.md`.
diff --git a/docs/uk/resources/reference/coding-agent-startup-flow.md b/docs/uk/resources/reference/coding-agent-startup-flow.md
new file mode 100644
index 0000000..1bc497d
--- /dev/null
+++ b/docs/uk/resources/reference/coding-agent-startup-flow.md
@@ -0,0 +1,33 @@
+# Процес запуску агента кодування
+
+Використовуйте це на початку кожної сесії після завершення ініціалізації.
+
+## Фіксований шаблон запуску
+
+1. Виконайте `pwd` і підтвердьте кореневу директорію репозиторію.
+2. Прочитайте `claude-progress.md`.
+3. Прочитайте `feature_list.json`.
+4. Перегляньте останні коміти за допомогою `git log --oneline -5`.
+5. Виконайте `./init.sh`.
+6. Запустіть базовий димовий тест або наскрізний сценарій.
+7. Якщо базовий стан зламано, спочатку виправте це.
+8. Виберіть незавершену функцію з найвищим пріоритетом.
+9. Працюйте лише над цією функцією, доки вона не буде верифікована або явно заблокована.
+
+## Чому важливий саме такий порядок
+
+- `pwd` запобігає випадковій роботі в неправильній директорії.
+- файли прогресу та функцій відновлюють довгостроковий стан до початку нових правок.
+- останні коміти пояснюють, що змінювалось найостанніше.
+- `init.sh` стандартизує запуск замість покладання на пам'ять.
+- базова верифікація виявляє зламані початкові стани до того, як нова робота їх приховає.
+
+## Дзеркало кінця сесії
+
+Та сама сесія повинна завершуватись:
+
+1. записом прогресу
+2. оновленням стану функцій
+3. написанням передачі за потреби
+4. комітом безпечної роботи
+5. залишенням чистого шляху для перезапуску
diff --git a/docs/uk/resources/reference/index.md b/docs/uk/resources/reference/index.md
new file mode 100644
index 0000000..d8f33ae
--- /dev/null
+++ b/docs/uk/resources/reference/index.md
@@ -0,0 +1,85 @@
+# Довідник
+
+Ці нотатки пояснюють, як використовувати шаблони як повноцінний harness, а не
+просто набір розрізнених файлів.
+
+## Внутрішні довідкові нотатки
+
+- [`method-map.md`](./method-map.md): відображення поширених режимів збою при
+ тривалій роботі на артефакт або політику, що усуває їх у першу чергу
+- [`initializer-agent-playbook.md`](./initializer-agent-playbook.md): що
+ ініціалізатор повинен залишити після себе до початку роботи над функціями
+- [`coding-agent-startup-flow.md`](./coding-agent-startup-flow.md): фіксований
+ процес запуску сесії для подальших сесій кодування
+- [`prompt-calibration.md`](./prompt-calibration.md): як підтримувати кореневі
+ інструкції чіткими без перевантаження та крихкості
+
+## Основні статті
+
+Цей список навмисно вузький. Harness означає систему виконання навколо моделі:
+цикл агента, виконання інструментів, ізоляцію, стан, контекст, верифікацію,
+завершення, оркестрацію та спостережуваність. Загальні статті про prompt-інженерію
+або широкі фреймворки агентів до основного списку не включаються.
+
+Три оригінальні статті залишаються основою курсу:
+
+- [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/) (2026-02-11): репозиторії з пріоритетом агентів, локальний контекст репозиторію, власний лінтинг та структурні запобіжники.
+- [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) (2025-11-26): агент-ініціалізатор, агент кодування, список функцій, журнал прогресу та передача між контекстними вікнами.
+- [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps) (2026-03-24): ролі планувальника / генератора / оцінювача, скидання контексту, спрощення harness та застарілі припущення.
+
+Додано лише кілька вкрай актуальних статей 2026 року:
+
+- [OpenAI: Unrolling the Codex agent loop](https://openai.com/index/unrolling-the-codex-agent-loop/) (2026-01-23): harness runtime Codex, виклики інструментів, зростання контексту та завершення циклу.
+- [Anthropic: Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents) (2026-01-09): спільна оцінка моделі та harness, розмежування harness оцінювання та harness агента.
+- [LangChain: Improving Deep Agents with harness engineering](https://www.langchain.com/blog/improving-deep-agents-with-harness-engineering) (2026-02-17): фіксація моделі при покращенні системних підказок, інструментів, middleware, трасування та самоверифікації для переміщення агента кодування з Топ-30 у Топ-5 на Terminal Bench 2.0.
+- [Thoughtworks / Martin Fowler: Harness engineering for coding agent users](https://martinfowler.com/articles/harness-engineering.html) (2026-04-02): harness для користувачів агентів кодування як випереджувальні напрямники та зворотні датчики, з детермінованими та інференційними засобами управління.
+- [Cursor: Continually improving our agent harness](https://cursor.com/blog/continually-improving-agent-harness) (2026-04-30): harness як безперервно вдосконалюваний продукт з офлайн-оцінками, онлайн-метриками, таксономією помилок інструментів, налаштуванням під конкретні моделі та перемиканням моделей під час чату.
+
+## Розширені посилання 2026 року
+
+Це не основні джерела курсу, але вони корисні при проектуванні конкретних модулів
+harness. Цей розділ містить лише джерела, тіло яких безпосередньо охоплює цикл
+агента, виконання інструментів, управління контекстом, верифікацію, ізоляцію,
+рівні управління або регресійне управління. Суто агентні продукти, оголошення
+платформ, кейси команд та тести продуктивності виключаються.
+
+- [OpenAI: Unlocking the Codex harness: how we built the App Server](https://openai.com/index/unlocking-the-codex-harness/) (2026-02-04): harness як протокол App Server для повторного використання з lifecycle потоку, відновленням, форком, дифами та клієнтськими інтеграціями.
+- [OpenAI Developers: Run long horizon tasks with Codex](https://developers.openai.com/blog/run-long-horizon-tasks-with-codex) (2026-02-23): довгострокова пам'ять проекту, валідація проміжних результатів та приклади умов завершення для тривалих задач.
+- [OpenAI: The next evolution of the Agents SDK](https://openai.com/index/the-next-evolution-of-the-agents-sdk/) (2026-04-15): нативні для моделі harness, виконання в пісочниці та виконання файлів/команд.
+- [OpenAI: An open-source spec for Codex orchestration: Symphony](https://openai.com/index/open-source-codex-orchestration-symphony/) (2026-04-27): перетворення трекера задач або дошки Linear на площину управління мультиагентами.
+- [Anthropic: Building a C compiler with a team of parallel Claudes](https://www.anthropic.com/engineering/building-c-compiler) (2026-02-05): паралельні команди агентів, блокування задач, синхронізація git, ізоляція контейнерів та автономні цикли.
+- [Anthropic: Scaling Managed Agents: Decoupling the brain from the hands](https://www.anthropic.com/engineering/managed-agents) (2026-04-08): погляд на мета-harness, що розділяє сесію, harness та пісочницю як замінні інтерфейси.
+- [Anthropic: An update on recent Claude Code quality reports](https://www.anthropic.com/engineering/april-23-postmortem) (2026-04-23): зусилля на міркування, скорочення контексту та системні підказки як зміни harness, що потребують регресійного управління.
+- [LangChain: Context Management for Deep Agents](https://www.langchain.com/blog/context-management-for-deepagents) (2026-01-28): вивантаження у файлову систему, скорочення викликів інструментів, резюмування та цільові оцінки для harness управління контекстом.
+- [LangChain: Tuning Deep Agents to Work Well with Different Models](https://www.langchain.com/blog/tuning-deep-agents-different-models) (2026-04-29): профілі harness для конкретних моделей щодо підказок, назв інструментів, middleware та конфігурації підагентів.
+- [LangChain: Continual learning for AI agents](https://www.langchain.com/blog/continual-learning-for-ai-agents) (2026-04-05): розподіл вдосконалення агента на рівні моделі, harness та контексту на основі трасувань.
+- [Microsoft: Agent Harness in Agent Framework](https://devblogs.microsoft.com/agent-framework/agent-harness-in-agent-framework/) (2026-03-12): harness оболонки/файлової системи, процес затвердження, виконання оболонки на хості та ущільнення контексту.
+- [Google: Announcing ADK for Java 1.0.0](https://developers.googleblog.com/announcing-adk-for-java-100-building-the-future-of-ai-agents-in-java/) (2026-03-30): плагіни, ущільнення подій, HITL, сервіси сесій/пам'яті та A2A як примітиви harness для повторного використання.
+- [GitHub: Automate repository tasks with GitHub Agentic Workflows](https://github.blog/ai-and-ml/automate-repository-tasks-with-github-agentic-workflows/) (2026-02-13): GitHub Actions як виконавець агентних робочих процесів із захищеними виводами, ізоляцією, дозволами та перевіркою.
+- [AWS: AI agents in enterprises: Best practices with Amazon Bedrock AgentCore](https://aws.amazon.com/blogs/machine-learning/ai-agents-in-enterprises-best-practices-with-amazon-bedrock-agentcore/) (2026-02-03): enterprise-рівні harness для Runtime, Memory, Gateway, Identity/Policy, Observability та Evaluations.
+- [Stripe: Minions: Stripe's one-shot, end-to-end coding agents](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents) (2026-02-09) та [Частина 2](https://stripe.dev/blog/minions-stripes-one-shot-end-to-end-coding-agents-part-2) (2026-02-19): ізоляція devbox, власні harness агентів, машини станів blueprint, файли правил, підбір інструментів MCP, засоби безпеки та цикли зворотного зв'язку pre-push/CI.
+- [Cognition: What We Learned Building Cloud Agents](https://cognition.ai/blog/what-we-learned-building-cloud-agents) (2026-04-23): ізоляція ВМ, знімок/відновлення сесії, оркестрація, управління, журналювання аудиту та інтеграції для runtime хмарних агентів.
+- [Cognition: Multi-Agents: What's Actually Working](https://cognition.ai/blog/multi-agents-working) (2026-04-22): цикли генератор-верифікатор, рецензенти з чистим контекстом, маршрутизація розумного помічника, координація менеджер-дочірній агент та межі міжагентної комунікації.
+- [Replit: Decision-Time Guidance: Keeping Replit Agent Reliable](https://blog.replit.com/decision-time-guidance) (2026-01-20, оновлено 2026-01-23): легкий класифікатор вставляє коротку ситуативну настанову в момент прийняття рішення замість завантаження всіх правил у системну підказку.
+- [Vercel: How we made v0 an effective coding agent](https://vercel.com/blog/how-we-made-v0-an-effective-coding-agent) (2026-01-07): динамічні системні підказки, шар потокового переписування та детерміновані/керовані моделлю автовиправники.
+- [Vercel: Introducing deepsec](https://vercel.com/blog/introducing-deepsec-find-and-fix-vulnerabilities-in-your-code-base) (2026-05-04): harness агента кодування з акцентом на безпеці зі кроками сканування, дослідження, повторної валідації, збагачення, експорту, плагінів та перевірки відмов.
+- [Sourcegraph: CodeScaleBench](https://sourcegraph.com/blog/codescalebench-testing-coding-agents-on-large-codebases-and-multi-repo-software-engineering-tasks) (2026-03-03): довідник harness оцінювання/інструментарію, що охоплює прийняття інструментів MCP, транскрипти використання інструментів, контроль якості тестів, верифікаційні/відтворювані шлюзи та ітерації підказок/преамбул.
+
+Суто загальні посилання лише 2025 року виключені з основного списку. Оригінальна
+стаття Anthropic про harness 2025 року залишається, оскільки є базовим джерелом
+курсу.
+
+## Рекомендований порядок читання
+
+1. `method-map.md`
+2. `initializer-agent-playbook.md`
+3. `coding-agent-startup-flow.md`
+4. `prompt-calibration.md`
+5. OpenAI Harness engineering
+6. Anthropic Effective harnesses
+7. Anthropic Harness design for long-running application development
+8. OpenAI Codex agent loop
+9. Anthropic agent evals
+10. LangChain Improving Deep Agents
+11. Thoughtworks / Martin Fowler Harness engineering for coding agent users
+12. Cursor Continually improving our agent harness
diff --git a/docs/uk/resources/reference/initializer-agent-playbook.md b/docs/uk/resources/reference/initializer-agent-playbook.md
new file mode 100644
index 0000000..00796df
--- /dev/null
+++ b/docs/uk/resources/reference/initializer-agent-playbook.md
@@ -0,0 +1,37 @@
+# Посібник агента-ініціалізатора
+
+Використовуйте цей посібник для першої повноцінної сесії в репозиторії, до початку
+поступової роботи над функціями.
+
+## Мета
+
+Створити стабільну робочу поверхню, щоб наступні сесії могли реалізовувати
+поведінку без повторного виведення команд запуску, поточного статусу або меж задачі.
+
+## Обов'язкові результати
+
+Ініціалізатор повинен залишити після себе принаймні такі артефакти:
+
+- кореневий файл інструкцій, наприклад `AGENTS.md` або `CLAUDE.md`
+- машиночитаний перелік функцій, наприклад `feature_list.json`
+- довгостроковий артефакт прогресу, наприклад `claude-progress.md`
+- стандартний допоміжний сценарій запуску, наприклад `init.sh`
+- початковий безпечний коміт, що фіксує базовий каркас
+
+## Контрольний список
+
+1. Визначте стандартний шлях запуску.
+2. Визначте стандартний шлях верифікації.
+3. Створіть журнал прогресу та запишіть початковий стан.
+4. Декомпозуйте роботу на явні функції зі статусами.
+5. Створіть перший чистий базовий коміт.
+
+## Тест на успіх
+
+Нова сесія без попереднього контексту чату повинна бути здатна відповісти на питання:
+
+- що робить цей репозиторій
+- як його запустити
+- як верифікувати
+- що не завершено
+- який наступний найкращий крок
diff --git a/docs/uk/resources/reference/method-map.md b/docs/uk/resources/reference/method-map.md
new file mode 100644
index 0000000..033224e
--- /dev/null
+++ b/docs/uk/resources/reference/method-map.md
@@ -0,0 +1,19 @@
+# Карта методів
+
+Ця таблиця відображає найпоширеніші режими збою агента кодування при тривалій
+роботі на артефакт або операційне правило, що зазвичай усуває їх у першу чергу.
+
+| Режим збою | Як виглядає на практиці | Основне рішення | Допоміжний артефакт |
+| --- | --- | --- | --- |
+| Плутанина при холодному старті | Нова сесія витрачає більшу частину часу на повторне виявлення налаштувань і статусу | Зробити репозиторій системою обліку | `claude-progress.md` |
+| Розповзання обсягу | Агент починає кілька функцій і жодну не завершує чисто | Обмежити активний обсяг | `feature_list.json` |
+| Передчасне завершення | Агент оголошує виконаним після правок коду, але до отримання запущеного доказу | Прив'язати завершення до доказів | `clean-state-checklist.md` |
+| Нестійкий запуск | Кожна сесія заново вчиться запускати проект | Стандартизувати налаштування і верифікацію | `init.sh` |
+| Слабка передача | Наступна сесія не може визначити, що верифіковано, що зламано і що далі | Завершувати явною передачею | `session-handoff.md` |
+| Суб'єктивний огляд | Якість огляду залежить від смаку або пам'яті | Оцінювати результат за фіксованими категоріями | `evaluator-rubric.md` |
+
+## Операційний принцип
+
+Додавайте найменший артефакт, що безпосередньо усуває спостережуваний режим збою.
+Уникайте вирішення всіх проблем надійності шляхом додавання ще більше тексту до
+одного глобального файлу інструкцій.
diff --git a/docs/uk/resources/reference/prompt-calibration.md b/docs/uk/resources/reference/prompt-calibration.md
new file mode 100644
index 0000000..24bb630
--- /dev/null
+++ b/docs/uk/resources/reference/prompt-calibration.md
@@ -0,0 +1,25 @@
+# Калібрування підказок
+
+Кореневі інструкції мають визначати операційну рамку, а не кожен можливий крок.
+
+## Залишати в кореневому файлі
+
+- призначення та обсяг репозиторію
+- шлях запуску
+- шлях верифікації
+- незмінні обмеження
+- обов'язкові артефакти стану
+- правила завершення сесії
+
+## Виносити з кореневого файлу
+
+- тривалі історичні крайні випадки
+- деталі реалізації для конкретних тем
+- локальні архітектурні нотатки, що належать поруч із кодом
+- приклади, що стосуються лише одного підсистемного компонента
+
+## Робоче правило
+
+Кореневий файл повинен допомагати новій сесії швидко орієнтуватись. Якщо файл
+перетворюється на звалище для кожного минулого збою, розбийте деталі на менші
+документи і посилайтесь на них.
diff --git a/docs/uk/resources/templates/AGENTS.md b/docs/uk/resources/templates/AGENTS.md
new file mode 100644
index 0000000..b9e2fec
--- /dev/null
+++ b/docs/uk/resources/templates/AGENTS.md
@@ -0,0 +1,54 @@
+# AGENTS.md
+
+Цей репозиторій призначений для тривалої роботи агента з написання коду. Мета — не
+максимізувати обсяг коду. Мета — залишити репозиторій у стані, в якому наступна
+сесія зможе продовжити роботу без жодних здогадок.
+
+## Робочий процес запуску
+
+Перш ніж писати код:
+
+1. Підтвердіть робочу директорію командою `pwd`.
+2. Прочитайте `claude-progress.md`, щоб дізнатися про останній верифікований стан і наступний крок.
+3. Прочитайте `feature_list.json` і оберіть незавершену функцію з найвищим пріоритетом.
+4. Перегляньте останні коміти командою `git log --oneline -5`.
+5. Запустіть `./init.sh`.
+6. Виконайте необхідну smoke-перевірку або наскрізну верифікацію, перш ніж розпочинати нову роботу.
+
+Якщо базова верифікація вже завершується помилкою, спочатку виправте це. Не накладайте
+роботу над новими функціями на несправний початковий стан.
+
+## Правила роботи
+
+- Працюйте над однією функцією за раз.
+- Не позначайте функцію як завершену лише тому, що код було додано.
+- Тримайте зміни в межах обраної функції, якщо тільки блокер не вимагає
+ вузького допоміжного виправлення.
+- Не змінюйте правила верифікації непомітно під час реалізації.
+- Надавайте перевагу артефактам репозиторію над підсумками в чаті.
+
+## Обов'язкові артефакти
+
+- `feature_list.json`: єдине джерело істини щодо стану функцій
+- `claude-progress.md`: журнал сесій і поточний верифікований стан
+- `init.sh`: стандартний шлях запуску та верифікації
+- `session-handoff.md`: необов'язкова компактна передача стану для великих сесій
+
+## Визначення завершеності
+
+Функція вважається завершеною лише тоді, коли виконані всі наступні умови:
+
+- цільова поведінка реалізована
+- необхідна верифікація дійсно запущена
+- докази зафіксовані у `feature_list.json` або `claude-progress.md`
+- репозиторій залишається готовим до перезапуску зі стандартного шляху запуску
+
+## Завершення сесії
+
+Перш ніж закінчити сесію:
+
+1. Оновіть `claude-progress.md`.
+2. Оновіть `feature_list.json`.
+3. Зафіксуйте будь-який невирішений ризик або блокер.
+4. Зробіть коміт з описовим повідомленням, коли робота перебуває у безпечному стані.
+5. Залиште репозиторій достатньо чистим, щоб наступна сесія могла одразу запустити `./init.sh`.
diff --git a/docs/uk/resources/templates/CLAUDE.md b/docs/uk/resources/templates/CLAUDE.md
new file mode 100644
index 0000000..2c08194
--- /dev/null
+++ b/docs/uk/resources/templates/CLAUDE.md
@@ -0,0 +1,46 @@
+# CLAUDE.md
+
+Ви працюєте в репозиторії, призначеному для тривалої реалізації. Надавайте пріоритет
+надійному завершенню, неперервності між сесіями та явній верифікації, а не швидкості.
+
+## Операційний цикл
+
+На початку кожної сесії:
+
+1. Запустіть `pwd` і підтвердіть, що ви знаходитесь у кореневій директорії потрібного репозиторію.
+2. Прочитайте `claude-progress.md`.
+3. Прочитайте `feature_list.json`.
+4. Перегляньте останні коміти командою `git log --oneline -5`.
+5. Запустіть `./init.sh`.
+6. Перевірте, чи не порушений вже базовий шлях smoke-перевірки або наскрізної верифікації.
+
+Потім оберіть рівно одну незавершену функцію і працюйте лише над нею, доки
+не верифікуєте її або не задокументуєте причину блокування.
+
+## Правила
+
+- Одна активна функція за раз.
+- Не заявляйте про завершення без виконуваних доказів.
+- Не переписуйте список функцій, щоб приховати незавершену роботу.
+- Не видаляйте та не послаблюйте тести лише для того, щоб завдання виглядало завершеним.
+- Використовуйте артефакти репозиторію як систему обліку.
+
+## Обов'язкові файли
+
+- `feature_list.json`
+- `claude-progress.md`
+- `init.sh`
+- `session-handoff.md` — коли компактна передача стану є корисною
+
+## Критерій завершеності
+
+Функцію можна перевести в статус `passing` лише після того, як необхідна верифікація
+успішно виконана і результат зафіксований.
+
+## Перш ніж зупинитися
+
+1. Оновіть журнал прогресу.
+2. Оновіть стан функцій.
+3. Зафіксуйте, що ще не виправлено або не верифіковано.
+4. Зробіть коміт, коли репозиторій готовий до продовження роботи.
+5. Залиште чистий шлях перезапуску для наступної сесії.
diff --git a/docs/uk/resources/templates/claude-progress.md b/docs/uk/resources/templates/claude-progress.md
new file mode 100644
index 0000000..22bcc99
--- /dev/null
+++ b/docs/uk/resources/templates/claude-progress.md
@@ -0,0 +1,35 @@
+# Журнал прогресу
+
+## Поточний верифікований стан
+
+- Корінь репозиторію:
+- Стандартний шлях запуску:
+- Стандартний шлях верифікації:
+- Поточна незавершена функція з найвищим пріоритетом:
+- Поточний блокер:
+
+## Журнал сесій
+
+### Сесія 001
+
+- Дата:
+- Мета:
+- Виконано:
+- Верифікація запущена:
+- Докази зафіксовані:
+- Коміти:
+- Оновлені файли або артефакти:
+- Відомий ризик або невирішена проблема:
+- Найкращий наступний крок:
+
+### Сесія 002
+
+- Дата:
+- Мета:
+- Виконано:
+- Верифікація запущена:
+- Докази зафіксовані:
+- Коміти:
+- Оновлені файли або артефакти:
+- Відомий ризик або невирішена проблема:
+- Найкращий наступний крок:
diff --git a/docs/uk/resources/templates/clean-state-checklist.md b/docs/uk/resources/templates/clean-state-checklist.md
new file mode 100644
index 0000000..97e2b3b
--- /dev/null
+++ b/docs/uk/resources/templates/clean-state-checklist.md
@@ -0,0 +1,8 @@
+# Контрольний список чистого стану
+
+- [ ] Стандартний шлях запуску досі працює.
+- [ ] Стандартний шлях верифікації досі виконується.
+- [ ] Поточний прогрес зафіксований у журналі прогресу.
+- [ ] Стан функцій відображає те, що дійсно проходить верифікацію, а не лише заявлено.
+- [ ] Жодний незавершений крок не залишений без документування.
+- [ ] Наступна сесія може продовжити роботу без ручного виправлення.
diff --git a/docs/uk/resources/templates/evaluator-rubric.md b/docs/uk/resources/templates/evaluator-rubric.md
new file mode 100644
index 0000000..b103389
--- /dev/null
+++ b/docs/uk/resources/templates/evaluator-rubric.md
@@ -0,0 +1,24 @@
+# Рубрика оцінювача
+
+Використовуйте цю рубрику після реалізації та перед фінальним прийняттям.
+
+| Категорія | Питання | Оцінка (0-2) | Примітки |
+| --- | --- | --- | --- |
+| Коректність | Чи відповідає реалізована поведінка запитаній функції? | | |
+| Верифікація | Чи були дійсно виконані необхідні перевірки з доказами? | | |
+| Дисципліна обсягу | Чи залишалася сесія в межах обраної функції? | | |
+| Надійність | Чи витримує результат перезапуск або повторний запуск без виправлень? | | |
+| Супроводжуваність | Чи є код і документація достатньо зрозумілими для наступної сесії? | | |
+| Готовність до передачі | Чи може нова сесія продовжити роботу, спираючись лише на артефакти репозиторію? | | |
+
+## Висновок
+
+- Прийняти
+- Переробити
+- Заблокувати
+
+## Обов'язкові подальші дії
+
+- Відсутні докази:
+- Обов'язкові виправлення:
+- Тригер наступного перегляду:
diff --git a/docs/uk/resources/templates/feature_list.json b/docs/uk/resources/templates/feature_list.json
new file mode 100644
index 0000000..138adc6
--- /dev/null
+++ b/docs/uk/resources/templates/feature_list.json
@@ -0,0 +1,64 @@
+{
+ "project": "replace-with-project-name",
+ "last_updated": "YYYY-MM-DD",
+ "rules": {
+ "single_active_feature": true,
+ "passing_requires_evidence": true,
+ "do_not_skip_verification": true
+ },
+ "status_legend": {
+ "not_started": "Work has not begun.",
+ "in_progress": "The feature is the current active task.",
+ "blocked": "Work cannot continue until a documented blocker is resolved.",
+ "passing": "Required verification has passed and evidence is recorded."
+ },
+ "features": [
+ {
+ "id": "chat-001",
+ "priority": 1,
+ "area": "chat",
+ "title": "Create a new conversation",
+ "user_visible_behavior": "A user can click New Chat and see a fresh empty conversation.",
+ "status": "not_started",
+ "verification": [
+ "Open the app.",
+ "Click New Chat.",
+ "Verify a new conversation appears in the sidebar.",
+ "Verify the main panel shows an empty conversation state."
+ ],
+ "evidence": [],
+ "notes": ""
+ },
+ {
+ "id": "chat-002",
+ "priority": 2,
+ "area": "chat",
+ "title": "Send a message in the current conversation",
+ "user_visible_behavior": "A user can submit a message and see it appear in the active thread.",
+ "status": "not_started",
+ "verification": [
+ "Open an existing conversation.",
+ "Type a message into the input.",
+ "Submit the message.",
+ "Verify the new message appears in the thread."
+ ],
+ "evidence": [],
+ "notes": ""
+ },
+ {
+ "id": "chat-003",
+ "priority": 3,
+ "area": "chat",
+ "title": "Persist the active conversation list",
+ "user_visible_behavior": "A user sees previously created conversations after restarting the app.",
+ "status": "not_started",
+ "verification": [
+ "Create two conversations.",
+ "Restart the app.",
+ "Verify both conversations still appear in the sidebar."
+ ],
+ "evidence": [],
+ "notes": ""
+ }
+ ]
+}
diff --git a/docs/uk/resources/templates/index.md b/docs/uk/resources/templates/index.md
new file mode 100644
index 0000000..c6d9a1d
--- /dev/null
+++ b/docs/uk/resources/templates/index.md
@@ -0,0 +1,249 @@
+# Посібник із шаблонів
+
+Ці шаблони готові до копіювання у ваш власний проект. Кожен із них виконує конкретну
+роль у робочому процесі агента. Відредагуйте вміст відповідно до команд, шляхів,
+назв функцій і кроків верифікації вашого проекту.
+
+## Як розпочати
+
+Спочатку скопіюйте ці чотири файли до кореня вашого проекту:
+
+1. `AGENTS.md` або `CLAUDE.md`
+2. `init.sh`
+3. `claude-progress.md`
+4. `feature_list.json`
+
+Решту файлів додавайте в міру розвитку проекту.
+
+---
+
+## AGENTS.md
+
+Кореневий файл інструкцій. Це перше, що агент читає на початку сесії. Він визначає
+операційні правила: що робити перед написанням коду, як працювати і як завершувати роботу.
+
+**Як використовувати:**
+
+- Скопіюйте до кореневої директорії вашого проекту
+- Замініть кроки робочого процесу запуску на реальні шляхи та команди вашого проекту
+- Скоригуйте правила роботи відповідно до угод вашої команди
+- Залиште розділ визначення завершеності — це найважливіша частина
+
+**Що він дає агенту:**
+
+- Наказує читати прогрес і стан функцій перед початком роботи
+- Змушує працювати над однією функцією за раз
+- Вимагає доказів перед тим, як позначити щось як виконане
+- Визначає, як виглядає чисте завершення сесії
+
+Використовуйте `AGENTS.md` для Codex або інших агентів. Використовуйте `CLAUDE.md`,
+якщо ви працюєте з Claude Code — структура однакова, просто відформатована під стиль
+інструкцій Claude.
+
+## init.sh
+
+Скрипт запуску. Виконує встановлення залежностей, верифікацію і виводить команду
+запуску — все за один раз.
+
+**Як використовувати:**
+
+- Скопіюйте до кореня вашого проекту
+- Відредагуйте ці три змінні на початку файлу:
+ - `INSTALL_CMD` — команда встановлення залежностей (наприклад, `npm install`, `pip install -r requirements.txt`)
+ - `VERIFY_CMD` — базова команда верифікації (наприклад, `npm test`, `pytest`)
+ - `START_CMD` — команда запуску dev-сервера (наприклад, `npm run dev`)
+- Зробіть файл виконуваним: `chmod +x init.sh`
+
+**Що він робить:**
+
+1. Виводить поточну директорію (щоб підтвердити, що запущений у правильному місці)
+2. Встановлює залежності
+3. Запускає команду верифікації
+4. Виводить команду запуску (або запускає її, якщо встановлено `RUN_START_COMMAND=1`)
+
+Якщо верифікація завершується помилкою, агент повинен зупинитися і виправити базовий
+стан, перш ніж робити щось інше.
+
+## claude-progress.md
+
+Журнал прогресу. Кожна сесія записує до цього файлу, і кожна нова сесія читає його першим.
+
+**Як використовувати:**
+
+- Скопіюйте до кореня вашого проекту
+- Заповніть розділ «Поточний верифікований стан» інформацією про ваш проект
+- Після кожної сесії оновлюйте запис сесії
+
+**Що означає кожне поле:**
+
+- **Поточний верифікований стан** — єдине джерело істини про стан проекту
+ - `Корінь репозиторію` — де знаходиться проект
+ - `Стандартний шлях запуску` — команда для запуску проекту
+ - `Стандартний шлях верифікації` — команда для запуску тестів
+ - `Незавершена функція з найвищим пріоритетом` — над чим має працювати наступна сесія
+ - `Поточний блокер` — що застрягло
+- **Запис сесії** — один запис на сесію
+ - `Мета` — що ви планували зробити
+ - `Виконано` — що насправді було зроблено
+ - `Верифікація запущена` — які тести виконувалися
+ - `Докази зафіксовані` — які докази були збережені
+ - `Коміти` — що було закомічено
+ - `Відомі ризики` — що може бути зламаним
+ - `Найкраща наступна дія` — з чого має починати наступна сесія
+
+## feature_list.json
+
+Трекер функцій. Машинозчитуваний список кожної функції, яку має реалізувати агент,
+разом із її статусом, кроками верифікації та доказами.
+
+**Як використовувати:**
+
+- Скопіюйте до кореня вашого проекту
+- Замініть приклади функцій своїми власними
+- Кожна функція потребує:
+ - `id` — короткий унікальний ідентифікатор
+ - `priority` — ціле число, менше = вищий пріоритет
+ - `area` — яка частина застосунку (наприклад, "chat", "import", "search")
+ - `title` — короткий опис
+ - `user_visible_behavior` — що користувач має побачити, коли функція працює
+ - `status` — одне з: `not_started`, `in_progress`, `blocked`, `passing`
+ - `verification` — покрокові інструкції для підтвердження роботи функції
+ - `evidence` — зафіксовані докази того, що верифікація пройшла (заповнює агент)
+ - `notes` — будь-який додатковий контекст
+
+**Правила статусів:**
+
+- `not_started` — до неї ще не торкалися
+- `in_progress` — єдина функція, над якою зараз ведеться робота (лише одна за раз)
+- `blocked` — неможливо продовжити через задокументовану проблему
+- `passing` — верифікація пройшла і докази зафіксовані
+
+Агент повинен мати лише одну функцію зі статусом `in_progress` у будь-який момент часу.
+
+## session-handoff.md
+
+Компактна передача стану між сесіями. Використовуйте цей файл, коли сесія завершується
+і ви хочете, щоб наступна підхопила роботу швидко.
+
+**Як використовувати:**
+
+- Скопіюйте до кореня вашого проекту
+- Заповніть наприкінці кожної сесії (або попросіть агента заповнити)
+
+**Що охоплює кожен розділ:**
+
+- **Верифіковано зараз** — що підтверджено як таке, що працює, і яка верифікація запускалася
+- **Змінено в цій сесії** — який код або інфраструктура змінилися
+- **Зламане або не верифіковане** — відомі проблеми та ризиковані ділянки
+- **Найкращий наступний крок** — що має зробити наступна сесія і що не можна чіпати
+- **Команди** — команди запуску, верифікації та відлагодження для швидкої довідки
+
+Цей файл необов'язковий для невеликих сесій. Він стає важливим, коли сесії тривалі
+або коли в проекті є кілька активних напрямків.
+
+## clean-state-checklist.md
+
+Контрольний список для перевірки перед завершенням кожної сесії. Гарантує, що
+репозиторій перебуває у хорошому стані для чистого початку наступної сесії.
+
+**Як використовувати:**
+
+- Скопіюйте до кореня вашого проекту
+- Пройдіться по ньому перед закриттям сесії
+- Агент також має перевіряти ці пункти як частину свого процесу завершення сесії
+
+**Що перевіряється:**
+
+- Стандартний запуск досі працює
+- Стандартна верифікація досі виконується
+- Журнал прогресу оновлено
+- Список функцій відображає реальний стан (жодних хибних записів `passing`)
+- Жодна незавершена робота не залишена незафіксованою
+- Наступна сесія може продовжити роботу без ручних виправлень
+
+## evaluator-rubric.md
+
+Картка оцінювання якості виводу агента. Використовуйте її після сесії або на
+контрольних точках проекту, щоб оцінити, чи відповідає робота необхідному рівню.
+
+**Як використовувати:**
+
+- Скопіюйте до кореня вашого проекту
+- Після сесії (або набору сесій) оцініть роботу агента за шістьма вимірами
+- Кожен вимір оцінюється від 0 до 2
+
+**Шість вимірів:**
+
+1. **Коректність** — чи відповідає реалізація цільовій поведінці?
+2. **Верифікація** — чи були дійсно виконані необхідні перевірки з доказами?
+3. **Дисципліна обсягу** — чи залишався агент у межах обраної функції?
+4. **Надійність** — чи витримує результат перезапуск або повторний запуск?
+5. **Супроводжуваність** — чи є код і документація достатньо зрозумілими для наступної сесії?
+6. **Готовність до передачі** — чи може нова сесія продовжити роботу, спираючись лише на артефакти репозиторію?
+
+**Варіанти висновку:**
+
+- Прийняти — відповідає вимогам
+- Переробити — потрібні виправлення перед прийняттям
+- Заблокувати — фундаментальні проблеми, які потрібно вирішити спочатку
+
+**Важливо: оцінювач потребує налаштування.** За замовчуванням агенти погано оцінюють
+самі себе — вони виявляють проблеми, а потім переконують себе схвалити роботу. Вам
+доведеться ітерувати:
+
+1. Запустіть оцінювач на завершеному спринті.
+2. Порівняйте його оцінки з вашою власною людською думкою.
+3. Де вони розходяться, зробіть рубрику конкретнішою щодо критеріїв прийнятності.
+4. Перезапустіть і перевірте узгодженість.
+5. Повторюйте, доки оцінювач стабільно не збігатиметься з людським переглядом.
+
+Плануйте 3–5 раундів налаштування. Фіксуйте кожну зміну, щоб відстежувати, що
+покращило узгодженість.
+
+## quality-document.md
+
+Знімок якості, який оцінює кожен продуктовий домен та архітектурний шар вашого проекту.
+Відстежує здоров'я кодової бази з часом, а не лише вивід окремої сесії.
+
+**Як використовувати:**
+
+- Скопіюйте до кореня вашого проекту
+- Перед початком сесії: прочитайте, щоб зрозуміти найслабші місця кодової бази
+- Після сесії: оновіть оцінки на основі змін
+- З часом: порівнюйте знімки, щоб побачити, які зміни harness дійсно покращили
+ здоров'я кодової бази
+
+**Що оцінюється:**
+
+- **Продуктові домени** (наприклад, імпорт документів, потік Q&A, індексація): кожен домен
+ отримує оцінку (A–D) за верифікаційним статусом, зрозумілістю для агентів, стабільністю
+ тестів і ключовими прогалинами
+- **Архітектурні шари** (наприклад, головний процес, preload, renderer, сервіси): кожен шар
+ отримує оцінку за дотриманням меж і зрозумілістю для агентів
+
+**Чому це важливо:**
+
+Рубрика оцінювача оцінює окремі виводи агента. Документ якості оцінює саму кодову базу.
+Вони відповідають на різні питання:
+
+- Рубрика оцінювача: «Чи добре агент попрацював у цій сесії?»
+- Документ якості: «Чи стає проект міцнішим або слабшим з часом?»
+
+**Коли оновлювати:**
+
+- Після кожної значущої сесії
+- Перед порівняльними тестуваннями
+- Після проходів з очищення або спрощення
+- При підключенні нового агента або моделі до проекту
+
+**Зв'язок зі спрощенням harness:**
+
+Документ якості також підтримує спрощення harness. Кожен компонент harness кодує
+припущення про те, чого модель не може робити. З покращенням моделей ці припущення
+застарівають. Щоб перевірити, чи компонент ще потрібен:
+
+1. Зробіть знімок документа якості.
+2. Видаліть один компонент harness.
+3. Запустіть еталонний набір завдань.
+4. Зробіть ще один знімок.
+5. Порівняйте — якщо оцінки не впали, компонент був зайвим. Якщо впали — відновіть його.
diff --git a/docs/uk/resources/templates/init.sh b/docs/uk/resources/templates/init.sh
new file mode 100755
index 0000000..d7522d6
--- /dev/null
+++ b/docs/uk/resources/templates/init.sh
@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$ROOT_DIR"
+
+# Replace these commands with the correct commands for your repository.
+INSTALL_CMD=(npm install)
+VERIFY_CMD=(npm test)
+START_CMD=(npm run dev)
+
+echo "==> Working directory: $PWD"
+echo "==> Syncing dependencies"
+"${INSTALL_CMD[@]}"
+
+echo "==> Running baseline verification"
+"${VERIFY_CMD[@]}"
+
+echo "==> Startup command"
+printf ' %q' "${START_CMD[@]}"
+printf '\n'
+
+if [ "${RUN_START_COMMAND:-0}" = "1" ]; then
+ echo "==> Starting the app"
+ exec "${START_CMD[@]}"
+fi
+
+echo "Set RUN_START_COMMAND=1 if you want init.sh to launch the app directly."
diff --git a/docs/uk/resources/templates/quality-document.md b/docs/uk/resources/templates/quality-document.md
new file mode 100644
index 0000000..fd0bfc6
--- /dev/null
+++ b/docs/uk/resources/templates/quality-document.md
@@ -0,0 +1,45 @@
+# Документ якості
+
+Знімок якості для кожного продуктового домену та архітектурного шару. Як агенти, так і
+люди можуть використовувати цей документ, щоб швидко зрозуміти, де кодова база є міцною,
+а де потребує роботи.
+
+**Частота оновлення:** Після кожної значущої сесії або перед початком нової фази роботи.
+
+**Шкала оцінювання:**
+
+- **A**: Вся верифікація проходить, чиста архітектура, зрозуміла для агентів, стабільні тести
+- **B**: Верифікація проходить, переважно чиста, незначні прогалини в зрозумілості або покритті тестами
+- **C**: Частково працює, відомі прогалини, деякі ділянки коду важко зрозуміти агентам
+- **D**: Не працює або є суттєві структурні проблеми
+
+---
+
+## Продуктові домени
+
+| Домен | Оцінка | Верифікація | Зрозумілість для агентів | Стабільність тестів | Ключові прогалини | Останнє оновлення |
+|--------|-------|-------------|-----------------|---------------|----------|-------------|
+| Імпорт документів | - | - | - | - | - | - |
+| Управління документами | - | - | - | - | - | - |
+| Індексація документів | - | - | - | - | - | - |
+| Потік Q&A | - | - | - | - | - | - |
+| Обґрунтовані відповіді | - | - | - | - | - | - |
+
+## Архітектурні шари
+
+| Шар | Оцінка | Дотримання меж | Зрозумілість для агентів | Ключові прогалини | Останнє оновлення |
+|-------|-------|---------------------|-----------------|----------|-------------|
+| Головний процес | - | - | - | - | - |
+| Preload | - | - | - | - | - |
+| Renderer | - | - | - | - | - |
+| Сервіси | - | - | - | - | - |
+
+## Історія змін
+
+### РРРР-ММ-ДД
+
+- Зміни:
+- Домени підвищені:
+- Знижені:
+- Нові виявлені прогалини:
+- Закриті прогалини:
diff --git a/docs/uk/resources/templates/session-handoff.md b/docs/uk/resources/templates/session-handoff.md
new file mode 100644
index 0000000..16c20bf
--- /dev/null
+++ b/docs/uk/resources/templates/session-handoff.md
@@ -0,0 +1,30 @@
+# Передача стану сесії
+
+## Верифіковано зараз
+
+- Що наразі працює:
+- Яка верифікація дійсно запускалася:
+
+## Змінено в цій сесії
+
+- Доданий код або змінена поведінка:
+- Зміни інфраструктури або harness:
+
+## Зламане або не верифіковане
+
+- Відомий дефект:
+- Неперевірений шлях:
+- Ризик для наступної сесії:
+
+## Найкращий наступний крок
+
+- Незавершена функція з найвищим пріоритетом:
+- Чому вона наступна:
+- Що вважається проходженням:
+- Що не можна змінювати під час цього кроку:
+
+## Команди
+
+- Запуск:
+- Верифікація:
+- Команда цільового відлагодження:
diff --git a/docs/uk/skills/index.md b/docs/uk/skills/index.md
new file mode 100644
index 0000000..325dabc
--- /dev/null
+++ b/docs/uk/skills/index.md
@@ -0,0 +1,59 @@
+# Skills
+
+Цей каталог містить вбудовані Skills для AI-агентів, що входять до цього курсу. Skills — це самодостатні шаблони промптів, які можуть завантажувати AI-агенти з кодування (Claude Code, Codex, Cursor, Windsurf тощо) для виконання спеціалізованих завдань.
+
+## harness-creator
+
+Продакшн-рівневий skill з Harness Engineering для AI-агентів кодування. Він допомагає створювати, оцінювати та покращувати п'ять основних підсистем harness: інструкції, стан, верифікацію, область застосування та життєвий цикл сесії.
+
+### Що він робить
+
+- **Створення harness з нуля** — AGENTS.md, списки функцій, робочі процеси верифікації
+- **Покращення наявних harness** — оцінювання за п'ятьма підсистемами з пріоритизованими покращеннями
+- **Проєктування безперервності сесій** — збереження пам'яті, відстеження прогресу, процедури передачі стану
+- **Застосування продакшн-патернів** — пам'ять, інжиніринг контексту, безпека інструментів, координація між агентами
+
+### Швидкий старт
+
+Файли Skills розміщені в репозиторії за адресою [`skills/harness-creator/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/skills/harness-creator).
+
+```bash
+npx skills add walkinglabs/learn-harness-engineering --skill harness-creator
+```
+
+Щоб використовувати зі Claude Code, скопіюйте каталог `harness-creator/` до шляху Skills вашого проєкту або вкажіть агенту на файл SKILL.md.
+
+### Довідкові патерни
+
+Skill включає 7 сфокусованих довідкових документів:
+
+| Патерн | Коли використовувати |
+|--------|----------------------|
+| Memory Persistence | Агент забуває між сесіями |
+| Skill Runtime | Пакування повторно використовуваних робочих процесів як Skills |
+| Context Engineering | Управління бюджетом контексту, JIT-завантаження |
+| Tool Registry | Безпека інструментів, контроль паралелізму |
+| Multi-Agent Coordination | Паралелізм, спеціалізовані робочі процеси |
+| Lifecycle & Bootstrap | Хуки, фонові завдання, ініціалізація |
+| Gotchas | 15 неочевидних режимів відмов із виправленнями |
+
+### Шаблони
+
+Skill містить готові до використання шаблони:
+
+- `agents.md` — каркас AGENTS.md із робочими правилами
+- `feature-list.json` — JSON Schema + приклад списку функцій
+- `init.sh` — стандартний скрипт ініціалізації
+- `progress.md` — шаблон журналу прогресу сесії
+- `session-handoff.md` — шаблон передачі стану сесії
+
+### Скрипти
+
+Skill також включає прості Node.js-скрипти для генерації каркасів, валідації, HTML-звітів оцінювання та структурних звітів бенчмарків.
+
+### Як було створено цей Skill
+
+`harness-creator` розроблено з використанням методології **skill-creator** — офіційного мета-skill Anthropic для створення, тестування та ітерації Skills для агентів. skill-creator надає структурований робочий процес (чернетка → тестування → оцінювання → ітерація) із вбудованими запускальниками eval, оцінювачами та переглядачем бенчмарків.
+
+- **Джерело skill-creator**: [anthropics/skills — skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator)
+- **Документація Claude Code skills**: [anthropics/claude-code — plugin-dev/skills](https://github.com/anthropics/claude-code/tree/main/plugins/plugin-dev/skills)
diff --git a/projects/project-01/README-UK.md b/projects/project-01/README-UK.md
new file mode 100644
index 0000000..bde53ee
--- /dev/null
+++ b/projects/project-01/README-UK.md
@@ -0,0 +1,63 @@
+[English](./README.md) · **Українська**
+
+# Проєкт 01: Базовий та мінімальний harness
+
+Порівняйте, як слабкий harness (лише промпт) та явний harness (файли правил і механізми верифікації) впливають на показник виконання завдань агентом AI-кодування.
+
+## Структура каталогів
+
+| Каталог | Призначення |
+|------|------|
+| `starter/` | **Відправна точка**: лише розмитий `task-prompt.md`, без AGENTS.md і без feature_list.json. Це версія зі «слабким harness», яку передають агенту. |
+| `solution/` | **Еталонна реалізація**: той самий код застосунку, але з повними файлами harness (AGENTS.md, feature_list.json, init.sh, claude-progress.md). Це версія з «явним harness». |
+
+## Як використовувати
+
+```sh
+# 1. Запустіть завдання агента один раз із starter (слабкий harness)
+cd starter
+npm install
+# Передайте вміст task-prompt.md як промпт до Claude Code / Codex
+# Попросіть агента виконати: запуск вікна, список документів, панель QA, каталог даних
+# Не надавайте агенту файли solution під час цього запуску.
+
+# 2. Запустіть те саме завдання із solution (явний harness)
+cd ../solution
+npm install
+# Попросіть агента прочитати AGENTS.md, init.sh, feature_list.json і claude-progress.md
+# перед тим як торкатися коду. Код продукту вже має задовольняти ті самі чотири функції.
+
+# 3. Порівняйте два результати
+# - Чи було виконано завдання?
+# - Скільки повторних спроб знадобилося?
+# - Чи оголосив агент «готово» занадто рано?
+```
+
+## Точний контракт завдання
+
+Стартовий промпт навмисно розмитий (`starter/task-prompt.md` містить лише
+«Build an Electron app that can show documents and answer questions.»). Використовуйте
+solution harness, щоб зробити цей розмитий запит конкретним:
+
+| Функція | Докази в starter для перевірки | Докази в solution для порівняння |
+|------|------|------|
+| Запуск вікна | `src/main/main.ts`, `src/preload/preload.ts` | елемент `window-launch` у feature_list.json |
+| Панель списку документів | `src/renderer/components/DocumentList.tsx` | елемент `document-list` у feature_list.json |
+| Панель запитань | `src/renderer/components/QuestionPanel.tsx` | елемент `question-panel` у feature_list.json |
+| Каталог даних | `src/services/persistence-service.ts` | елемент `data-directory` у feature_list.json |
+
+Цей проєкт є експериментом, а не звичайним завданням «заповни starter, поки він не дорівнюватиме
+solution». Навчальний результат — це виміряна різниця між запуском лише з промптом
+і запуском, що починається з явних правил репозиторію та артефактів верифікації.
+
+## Охоплені функції
+
+- Electron-вікно успішно запускається
+- UI відображає область списку документів
+- UI відображає панель QA
+- Застосунок створює та використовує локальний каталог даних
+
+## Пов'язані лекції
+
+- [Лекція 01: Чому здатні агенти все одно зазнають невдачі](../../docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md)
+- [Лекція 02: Що таке harness насправді](../../docs/en/lectures/lecture-02-what-a-harness-actually-is/index.md)
diff --git a/projects/project-02/README-UK.md b/projects/project-02/README-UK.md
new file mode 100644
index 0000000..852d311
--- /dev/null
+++ b/projects/project-02/README-UK.md
@@ -0,0 +1,55 @@
+[English](./README.md) · **Українська**
+
+# Проєкт 02: Робочий простір, зрозумілий для агента
+
+Продемонструйте, як читабельність репозиторію та явні артефакти безперервності зменшують втрату контексту під час розробки в кількох сесіях.
+
+## Структура каталогів
+
+| Каталог | Призначення |
+|------|------|
+| `starter/` | **Відправна точка**: базується на рішенні P1, де імпорт документів, детальний перегляд і збереження ще потрібно реалізувати. Harness слабкий: AGENTS.md мінімальний, а передачі сесії немає. |
+| `solution/` | **Еталонна реалізація**: усі нові функції реалізовано, з повною документацією робочого простору (ARCHITECTURE.md, PRODUCT.md, session-handoff.md). |
+
+## Як використовувати
+
+```sh
+# Для виконання потрібно щонайменше 2 сесії агента
+cd starter
+npm install
+# Сесія A: реалізуйте імпорт документів і детальний перегляд
+# Сесія B: реалізуйте збереження (спостерігайте, чи агент швидко відновлює контекст)
+
+cd ../solution
+npm install
+# Повторіть запуск із повним harness і порівняйте швидкість відновлення сесії
+```
+
+## Точний контракт завдання
+
+Почніть із `starter/`. Стартова точка вже містить оболонку Проєкту 01 і
+мінімальний harness. Завдання — додати зріз продукту Проєкту 02 і
+документацію робочого простору, яка дозволяє другій сесії швидко відновитися.
+
+| Функція / артефакт | Стан у starter | Докази в solution |
+|------|------|------|
+| Імпорт документів | Потік імпорту є неповним у renderer, preload, IPC та `DocumentService` | `src/renderer/components/ImportPanel.tsx`, `src/main/ipc-handlers.ts`, `src/services/document-service.ts` |
+| Деталі документа | Панель деталей не завантажує та не відображає повний вміст файлу через IPC | `src/renderer/components/DocumentDetail.tsx`, `IPC_CHANNELS.GET_DOCUMENT_CONTENT` |
+| Базове збереження | Імпортовані документи не відновлюються повністю після перезапуску | `src/services/persistence-service.ts`, обробка `documents-meta.json` |
+| Стан, зрозумілий для агента | У starter немає фінального файлу передачі | `session-handoff.md`, розширений `docs/ARCHITECTURE.md`, розширений `docs/PRODUCT.md` |
+
+Виконуйте це як вправу в двох сесіях. Зупиніть Сесію A до завершення всіх трьох
+функцій продукту, потім розпочніть Сесію B лише зі стану репозиторію. Головне
+порівняння — наскільки швидше Сесія B може відновити роботу, коли `session-handoff.md`
+і документація існують.
+
+## Охоплені функції
+
+- Потік імпорту документів (вибір файлу та передача через IPC)
+- Детальний перегляд документа (відображення метаданих і вмісту)
+- Базове збереження (імпортовані документи залишаються після перезапуску)
+
+## Пов'язані лекції
+
+- [Лекція 03: Чому репозиторій має стати системою обліку](../../docs/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md)
+- [Лекція 04: Чому один великий файл інструкцій не працює](../../docs/en/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md)
diff --git a/projects/project-03/README-UK.md b/projects/project-03/README-UK.md
new file mode 100644
index 0000000..10bcb72
--- /dev/null
+++ b/projects/project-03/README-UK.md
@@ -0,0 +1,55 @@
+[English](./README.md) · **Українська**
+
+# Проєкт 03: Безперервність кількох сесій і контроль обсягу
+
+Оцініть, чи покращують журнали прогресу, передача сесії, явний контроль обсягу та
+верифікаційні вентилі точність виконання після перезапусків.
+
+## Структура каталогів
+
+| Каталог | Призначення |
+|------|------|
+| `starter/` | **Відправна точка**: базується на рішенні P2, де поділ документів на частини, витягування метаданих, статус індексу та обґрунтований QA ще потрібно реалізувати. Містить стартовий `feature_list.json`, але бракує повного harness перезапуску (`init.sh`, `session-handoff.md`, `claude-progress.md`, контрольного списку чистого стану). |
+| `solution/` | **Еталонна реалізація**: усі функції реалізовано. AGENTS.md включає стратегію «одна функція за раз», а репозиторій доповнено артефактами перезапуску/безперервності (`init.sh`, `session-handoff.md`, `claude-progress.md`, `clean-state-checklist.md`). |
+
+## Як використовувати
+
+```sh
+cd starter
+npm install
+# Запустіть щонайменше дві сесії агента. Зупиніть посередині задачі, потім відновіть зі стану репозиторію.
+# Спостерігайте, чи агент зберігає обсяг і оновлює feature_list.json.
+
+cd ../solution
+npm install
+# Перегляньте завершені артефакти безперервності та докази функцій.
+```
+
+## Точний контракт завдання
+
+Стартова точка Проєкту 03 — не порожній застосунок. Це Проєкт 02 плюс незавершена
+робота з індексування та обґрунтованого QA. Виконуйте ці пункти по одному за раз:
+
+| Функція / артефакт | Стан у starter | Докази в solution |
+|------|------|------|
+| Поділ документів на частини | `IndexingService` потребує створення частин з урахуванням абзаців | `src/services/indexing-service.ts`, елемент `document-chunking` у feature_list.json |
+| Витягування метаданих | Метадані документа є неповними для роботи з індексуванням | `src/services/document-service.ts`, `DocumentDetail.tsx`, елемент `metadata-extraction` |
+| UI статусу індексування | Рядок статусу потребує кількості проіндексованих / загальної кількості частин / кольорів статусу | `src/renderer/components/StatusBar.tsx`, `App.tsx`, елемент `indexing-status-ui` |
+| Обґрунтований QA | QA має цитувати отримані частини з уривками та рівнем впевненості | `src/services/qa-service.ts`, `QuestionPanel.tsx`, елемент `grounded-qa` |
+| Harness безперервності | У starter бракує фінальних артефактів перезапуску/передачі | `init.sh`, `session-handoff.md`, `claude-progress.md`, `clean-state-checklist.md` |
+
+Не трактуйте це як «додай будь-яку функцію для кількох сесій». Запланований зріз
+продукту — індексування плюс QA із посиланнями на джерела, а запланований зріз
+harness — відстеження прогресу з можливістю перезапуску.
+
+## Охоплені функції
+
+- Поділ документів на частини (з урахуванням абзаців, близько 500 символів)
+- Витягування метаданих (кількість слів, рядків, абзаців)
+- Статус індексу, відображений в UI
+- Базовий потік QA із посиланнями на джерела
+
+## Пов'язані лекції
+
+- [Лекція 05: Чому тривалі задачі втрачають безперервність](../../docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md)
+- [Лекція 06: Чому ініціалізація потребує власної фази](../../docs/en/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md)
diff --git a/projects/project-04/README-UK.md b/projects/project-04/README-UK.md
new file mode 100644
index 0000000..a296ed2
--- /dev/null
+++ b/projects/project-04/README-UK.md
@@ -0,0 +1,56 @@
+[English](./README.md) · **Українська**
+
+# Проєкт 04: Зворотний зв'язок від runtime та структурний контроль
+
+Впровадження спостережуваності runtime та перевірок структурних меж під час налагодження вбудованого дефекту runtime.
+
+## Довідник по директоріях
+
+| Директорія | Значення |
+|------|------|
+| `starter/` | **Відправна точка**: базується на рішенні P3, функції логування та структурних меж ще не реалізовано. `IndexingService` містить прихований вбудований баг: файли довжиною більше 1000 символів можуть генерувати порожні чанки. Немає скрипту перевірки архітектури та фінального чеклиста чистого стану. |
+| `solution/` | **Еталонна реалізація**: модуль структурованого логування, скрипт перевірки архітектурних меж і виправлений вбудований баг. |
+
+## Як використовувати
+
+```sh
+cd starter
+npm install
+# 1. Спостерігайте, чи може агент знайти баг через логи
+# 2. Імпортуйте великий файл і перевірте, чи коректно відбувається чанкінг
+
+cd ../solution
+npm install
+# Порівняйте, як структуровані логи прискорюють діагностику
+```
+
+## Точний контракт завдання
+
+Проєкт 04 — це вправа з налагодження та встановлення захисних бар'єрів. Стартер вже містить
+продуктовий зріз Проєкту 03, але runtime важче інспектувати, а вбудований
+дефект чанкінгу слід виправляти лише після того, як агент побачить достатньо доказів.
+
+| Функція / артефакт | Стан стартера | Докази рішення |
+|------|------|------|
+| Структуроване логування | Немає спільного сервісу логера | `src/services/logger.ts`, виклики логування у `main.ts`, `ipc-handlers.ts` та сервісах |
+| Діагностика імпорту / індексування | Збої важко відстежити за виводом runtime | Записи логів навколо імпорту, початку/завершення індексування та шляхів збою QA |
+| Архітектурні межі | Немає скрипту для перевірки дрейфу меж renderer/main/service | `scripts/check-architecture.sh`, `docs/ARCHITECTURE.md`, правила меж у AGENTS |
+| Вбудований баг чанкінгу | Великі файли можуть генерувати некоректний/порожній вивід чанків | Виправлена логіка параграфів/чанків у `src/services/indexing-service.ts` |
+| Чисте передавання | У стартері немає фінального чеклиста | `clean-state-checklist.md` |
+
+Використовуйте довгий зразок документа для відтворення бага до та після виправлення. Успішне
+рішення має демонструвати як зміни коду, так і діагностичні докази, а не лише
+твердження про проходження.
+
+## Охоплені функції
+
+- Логи запуску
+- Логи імпорту та індексування
+- Видимий шлях збою QA
+- Явні межі між шарами main, preload, renderer та services
+- Налагодження вбудованого дефекту runtime
+
+## Пов'язані лекції
+
+- [Лекція 07: Чому агенти виходять за межі та не доводять до кінця](../../docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md)
+- [Лекція 08: Чому списки функцій є примітивами harness](../../docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md)
diff --git a/projects/project-05/README-UK.md b/projects/project-05/README-UK.md
new file mode 100644
index 0000000..04777e8
--- /dev/null
+++ b/projects/project-05/README-UK.md
@@ -0,0 +1,62 @@
+[English](./README.md) · **Українська**
+
+# Проєкт 05: Цикли оцінювача та апгрейди з трьома ролями
+
+Вимірювання того, як розподіл ролей (одна роль, генератор плюс оцінювач, планувальник плюс генератор плюс оцінювач) впливає на якість реалізації.
+
+## Довідник по директоріях
+
+| Директорія | Значення |
+|------|------|
+| `starter/` | **Відправна точка**: базується на рішенні P4, багатоходова історія QA ще не реалізована. |
+| `solution/single-role/` | **Варіант A**: один агент виконує всю роботу (планування, реалізацію та самоперевірку). Базова якість. |
+| `solution/gen-eval/` | **Варіант B**: патерн генератор плюс оцінювач. Вища якість, з доказами ревізії. |
+| `solution/plan-gen-eval/` | **Варіант C**: планувальник плюс генератор плюс оцінювач. Найвища якість, з контрактом спринту та критеріями оцінювання. |
+
+## Як використовувати
+
+```sh
+# Починайте зі стартера, якщо хочете виконати вправу самостійно.
+cd starter
+npm install
+# Реалізуйте один і той самий апгрейд ConversationHistory тричі, використовуючи налаштування ролей нижче.
+
+# Інспектуйте три еталонні варіанти незалежно
+cd solution/single-role && npm install # режим однієї ролі
+cd solution/gen-eval && npm install # режим генератор плюс оцінювач
+cd solution/plan-gen-eval && npm install # режим трьох ролей
+
+# Порівняйте три варіанти:
+# - Якість коду (оцінка за evaluator-rubric.md)
+# - Кількість знайдених дефектів
+# - Обсяг необхідного доопрацювання
+```
+
+## Точний контракт завдання
+
+Продуктовий апгрейд для зафіксованих рішень є незмінним: реалізувати багатоходову
+історію Q&A через `ConversationHistory`. Три директорії з рішеннями — це не
+послідовні етапи; це три незалежних запуски однієї функції з
+різними ролями harness.
+
+| Варіант | Що демонструє | Докази для інспекції |
+|------|------|------|
+| `starter/` | Застосунок на базі P4 до апгрейду історії розмов | `src/renderer/components/ConversationHistory.tsx`, `App.tsx` |
+| `solution/single-role/` | Один агент планує, реалізує та самостійно перевіряє | Оцінка `evaluator-rubric.md` 1.6/5 та перелік дефектів |
+| `solution/gen-eval/` | Окремий генератор і оцінювач з доказами ревізії | Оцінка `evaluator-rubric.md` 3.3/5 та нотатки ревізії |
+| `solution/plan-gen-eval/` | Планувальник + генератор + оцінювач з контрактом спринту | `sprint-contract.md`, оцінка `evaluator-rubric.md` 4.9/5 |
+
+Зберігайте функцію незмінною під час повторних запусків проєкту. Зміна функції
+між варіантами унеможливлює порівняння, оскільки розподіл ролей є єдиною
+цільовою змінною.
+
+## Охоплені функції
+
+- Багатоходова історія QA (розмовний UI)
+- Контракт спринту
+- Налаштування рубрики оцінювача
+
+## Пов'язані лекції
+
+- [Лекція 09: Чому агенти оголошують перемогу передчасно](../../docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md)
+- [Лекція 10: Чому наскрізне тестування змінює результати](../../docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md)
diff --git a/projects/project-06/README-UK.md b/projects/project-06/README-UK.md
new file mode 100644
index 0000000..13226b2
--- /dev/null
+++ b/projects/project-06/README-UK.md
@@ -0,0 +1,65 @@
+[English](./README.md) · **Українська**
+
+# Проєкт 06: Спостережуваність runtime та налагодження (фінальний проєкт)
+
+Фінальний проєкт: побудова та бенчмаркінг повного harness, а потім запуск циклів очищення для верифікації якості та підтримуваності.
+
+## Довідник по директоріях
+
+| Директорія | Значення |
+|------|------|
+| `starter/` | **Відправна точка**: повний продуктовий код, але harness навмисно ослаблений (лише базовий AGENTS.md, без feature_list.json, передавання сесій або чеклиста чистого стану). |
+| `solution/` | **Еталонна реалізація**: максимальний harness з усіма файлами артефактів, високими оцінками якісних документів, скриптами бенчмаркінгу та сканерами очищення. |
+
+## Як використовувати
+
+```sh
+cd starter
+npm install
+# Запустіть застосунок і вручну зафіксуйте поведінку зі слабким harness.
+# Стартер навмисно не містить benchmark.sh та cleanup-scanner.sh.
+
+cd ../solution
+npm install
+# Запустіть той самий бенчмарк із повним harness
+# Виконайте цикли очищення
+# Порівняйте зміни оцінок у quality-document.md
+
+# Запустіть тести бенчмаркінгу
+./scripts/benchmark.sh
+
+# Запустіть сканування очищення
+./scripts/cleanup-scanner.sh
+```
+
+## Точний контракт завдання
+
+Проєкт 06 — це фінальне порівняння між повним продуктом із слабким покриттям harness
+та тим самим продуктом, зміцненим повним набором артефактів harness. На відміну від попередніх
+проєктів, стартер вже містить більшість функціональності продукту. Прогалина — це
+операційна система навколо коду.
+
+| Область | Стан стартера | Докази рішення |
+|------|------|------|
+| Поведінка продукту | Імпорт, індексування, QA, історія, зворотний зв'язок, скидання здебільшого є | Ті самі функції плюс більш строга верифікація та докази збереження стану |
+| Файли harness | Базовий `AGENTS.md`, немає `feature_list.json`, `session-handoff.md`, чеклиста чистого стану | `AGENTS.md`, `CLAUDE.md`, `feature_list.json`, `init.sh`, `session-handoff.md`, `clean-state-checklist.md` |
+| Відстеження якості | Лише початковий `quality-document.md` | `quality-document.md` з вищою оцінкою, `evaluator-rubric.md` |
+| Бенчмаркінг | Немає скриптів бенчмарку або очищення | `scripts/benchmark.sh`, `scripts/cleanup-scanner.sh`, `scripts/check-architecture.sh` |
+| Документи надійності | Мінімальна документація | `docs/ARCHITECTURE.md`, `docs/PRODUCT.md`, `docs/RELIABILITY.md` |
+
+Не очікуйте, що стартер міститиме команди бенчмаркінгу, показані для
+рішення. Для запуску зі слабким harness фіксуйте вручну базові спостереження; для
+запуску рішення використовуйте зафіксовані скрипти бенчмаркінгу та очищення.
+
+## Охоплені функції
+
+- Імпорт документів
+- Побудова або оновлення індексу
+- Відповіді на запитання з цитатами
+- Зворотний зв'язок від runtime
+- Читабельний стан репозиторію, з якого можна перезапустити роботу
+
+## Пов'язані лекції
+
+- [Лекція 11: Чому спостережуваність належить всередині harness](../../docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md)
+- [Лекція 12: Чому кожна сесія має залишати чистий стан](../../docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)
diff --git a/scripts/export-site-utils.ts b/scripts/export-site-utils.ts
index 88812f0..d90aa2b 100644
--- a/scripts/export-site-utils.ts
+++ b/scripts/export-site-utils.ts
@@ -57,7 +57,14 @@ export const readmeScreenshotTargets: ScreenshotTarget[] = [
routePath: '/zh/lectures/lecture-01-why-capable-agents-still-fail/',
outputName: 'zh-lecture-01.png'
},
- { language: 'zh', routePath: '/zh/resources/', outputName: 'zh-resources.png' }
+ { language: 'zh', routePath: '/zh/resources/', outputName: 'zh-resources.png' },
+ { language: 'uk', routePath: '/uk/', outputName: 'uk-home.png' },
+ {
+ language: 'uk',
+ routePath: '/uk/lectures/lecture-01-why-capable-agents-still-fail/',
+ outputName: 'uk-lecture-01.png'
+ },
+ { language: 'uk', routePath: '/uk/resources/', outputName: 'uk-resources.png' }
]
export async function ensureDirectory(targetPath: string) {
diff --git a/skills/README-AR.md b/skills/README-AR.md
index 0e819a3..a49be46 100644
--- a/skills/README-AR.md
+++ b/skills/README-AR.md
@@ -11,6 +11,7 @@
<a href="README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>
<a href="README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/Türkçe-d9d9d9"></a>
<a href="README-PT-BR.md"><img alt="Português (Brasil)" src="https://img.shields.io/badge/Português (Brasil)-d9d9d9"></a>
+ <a href="README-UK.md"><img alt="Українська" src="https://img.shields.io/badge/Українська-d9d9d9"></a>
</p>
# Skills
diff --git a/skills/README-CN.md b/skills/README-CN.md
index 58bbffd..887e1c8 100644
--- a/skills/README-CN.md
+++ b/skills/README-CN.md
@@ -11,6 +11,7 @@
<a href="README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>
<a href="README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/Türkçe-d9d9d9"></a>
<a href="README-PT-BR.md"><img alt="Português (Brasil)" src="https://img.shields.io/badge/Português (Brasil)-d9d9d9"></a>
+ <a href="README-UK.md"><img alt="Українська" src="https://img.shields.io/badge/Українська-d9d9d9"></a>
</p>
# Skills(技能集)
diff --git a/skills/README-DE.md b/skills/README-DE.md
index 0cb69bc..ffd144d 100644
--- a/skills/README-DE.md
+++ b/skills/README-DE.md
@@ -11,6 +11,7 @@
<a href="README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>
<a href="README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/Türkçe-d9d9d9"></a>
<a href="README-PT-BR.md"><img alt="Português (Brasil)" src="https://img.shields.io/badge/Português (Brasil)-d9d9d9"></a>
+ <a href="README-UK.md"><img alt="Українська" src="https://img.shields.io/badge/Українська-d9d9d9"></a>
</p>
# Skills
diff --git a/skills/README-ES.md b/skills/README-ES.md
index 57ca4d4..2b42835 100644
--- a/skills/README-ES.md
+++ b/skills/README-ES.md
@@ -11,6 +11,7 @@
<a href="README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>
<a href="README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/Türkçe-d9d9d9"></a>
<a href="README-PT-BR.md"><img alt="Português (Brasil)" src="https://img.shields.io/badge/Português (Brasil)-d9d9d9"></a>
+ <a href="README-UK.md"><img alt="Українська" src="https://img.shields.io/badge/Українська-d9d9d9"></a>
</p>
# Skills
diff --git a/skills/README-FR.md b/skills/README-FR.md
index e9f1a19..c5e01b7 100644
--- a/skills/README-FR.md
+++ b/skills/README-FR.md
@@ -11,6 +11,7 @@
<a href="README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>
<a href="README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/Türkçe-d9d9d9"></a>
<a href="README-PT-BR.md"><img alt="Português (Brasil)" src="https://img.shields.io/badge/Português (Brasil)-d9d9d9"></a>
+ <a href="README-UK.md"><img alt="Українська" src="https://img.shields.io/badge/Українська-d9d9d9"></a>
</p>
# Skills
diff --git a/skills/README-JA.md b/skills/README-JA.md
index 1c28818..6a98167 100644
--- a/skills/README-JA.md
+++ b/skills/README-JA.md
@@ -11,6 +11,7 @@
<a href="README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>
<a href="README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/Türkçe-d9d9d9"></a>
<a href="README-PT-BR.md"><img alt="Português (Brasil)" src="https://img.shields.io/badge/Português (Brasil)-d9d9d9"></a>
+ <a href="README-UK.md"><img alt="Українська" src="https://img.shields.io/badge/Українська-d9d9d9"></a>
</p>
# Skills
diff --git a/skills/README-KO.md b/skills/README-KO.md
index 7d28fb9..340439b 100644
--- a/skills/README-KO.md
+++ b/skills/README-KO.md
@@ -11,6 +11,7 @@
<a href="README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>
<a href="README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/Türkçe-d9d9d9"></a>
<a href="README-PT-BR.md"><img alt="Português (Brasil)" src="https://img.shields.io/badge/Português (Brasil)-d9d9d9"></a>
+ <a href="README-UK.md"><img alt="Українська" src="https://img.shields.io/badge/Українська-d9d9d9"></a>
</p>
# 스킬(Skills)
diff --git a/skills/README-TR.md b/skills/README-TR.md
index 4946ed1..3017f9a 100644
--- a/skills/README-TR.md
+++ b/skills/README-TR.md
@@ -11,6 +11,7 @@
<a href="README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>
<a href="README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/Türkçe-d9d9d9"></a>
<a href="README-PT-BR.md"><img alt="Português (Brasil)" src="https://img.shields.io/badge/Português (Brasil)-d9d9d9"></a>
+ <a href="README-UK.md"><img alt="Українська" src="https://img.shields.io/badge/Українська-d9d9d9"></a>
</p>
# Skill'ler
diff --git a/skills/README-UK.md b/skills/README-UK.md
new file mode 100644
index 0000000..034474a
--- /dev/null
+++ b/skills/README-UK.md
@@ -0,0 +1,91 @@
+<p align="center">
+ <a href="README.md"><img alt="English" src="https://img.shields.io/badge/English-d9d9d9"></a>
+ <a href="README-CN.md"><img alt="简体中文" src="https://img.shields.io/badge/简体中文-d9d9d9"></a>
+ <a href="README-ZH-TW.md"><img alt="繁體中文" src="https://img.shields.io/badge/繁體中文-d9d9d9"></a>
+ <a href="README-JA.md"><img alt="日本語" src="https://img.shields.io/badge/日本語-d9d9d9"></a>
+ <a href="README-ES.md"><img alt="Español" src="https://img.shields.io/badge/Español-d9d9d9"></a>
+ <a href="README-FR.md"><img alt="Français" src="https://img.shields.io/badge/Français-d9d9d9"></a>
+ <a href="README-KO.md"><img alt="한국어" src="https://img.shields.io/badge/한국어-d9d9d9"></a>
+ <a href="README-AR.md"><img alt="العربية" src="https://img.shields.io/badge/العربية-d9d9d9"></a>
+ <a href="README-VI.md"><img alt="Tiếng_Việt" src="https://img.shields.io/badge/Tiếng_Việt-d9d9d9"></a>
+ <a href="README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>
+ <a href="README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/Türkçe-d9d9d9"></a>
+ <a href="README-PT-BR.md"><img alt="Português (Brasil)" src="https://img.shields.io/badge/Português (Brasil)-d9d9d9"></a>
+ <a href="README-UK.md"><img alt="Українська" src="https://img.shields.io/badge/Українська-d9d9d9"></a>
+</p>
+
+# Skills
+
+Цей каталог містить багаторазові навички (skills) для AI-агентів проєкту Learn Harness Engineering. Кожна навичка — це самодостатній шаблон промту, який AI-агенти для написання коду (Claude Code, Codex, Cursor, Windsurf тощо) можуть завантажити для виконання спеціалізованих задач.
+
+## Доступні навички
+
+### harness-creator
+
+Навичка для інженерії harness виробничого рівня для AI-агентів написання коду. Допомагає створювати, оцінювати та покращувати файли harness агента (AGENTS.md, списки функціональності, процеси верифікації, механізми безперервності сесій).
+
+- **7 еталонних патернів**: Memory Persistence, Skill Runtime, Context Engineering, Tool Registry, Multi-Agent Coordination, Lifecycle & Bootstrap, Gotchas
+- **Шаблони**: AGENTS.md/CLAUDE.md, feature-list.json, init.sh, progress.md, session-handoff.md
+- **Скрипти**: скафолдинг, валідація, рендеринг HTML-оцінювання, запуск структурного бенчмарку
+- **10 вбудованих тестових кейсів для оцінювання (eval)**
+
+Повну документацію див. у [harness-creator/README.md](harness-creator/README.md).
+
+## Як було створено harness-creator
+
+Навичку `harness-creator` було розроблено за методологією **skill-creator** — офіційної мета-навички Anthropic для створення, тестування та ітеративного вдосконалення навичок агентів. skill-creator надає структурований процес (чернетка → тестування → оцінювання → ітерація) із вбудованими запускачами eval, оцінювачами та переглядачем бенчмарків.
+
+- **Джерело skill-creator**: [anthropics/skills — skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator)
+- **Документація Anthropic щодо навичок Claude Code**: [anthropics/claude-code — plugin-dev/skills](https://github.com/anthropics/claude-code/tree/main/plugins/plugin-dev/skills)
+
+## Структура каталогу
+
+```
+skills/
+├── README.md # Цей файл
+├── README-CN.md # Китайська версія
+├── README-ZH-TW.md # Традиційна китайська версія
+├── README-JA.md # Японська версія
+├── README-ES.md # Іспанська версія
+├── README-FR.md # Французька версія
+├── README-AR.md # Арабська версія
+├── README-VI.md # В'єтнамська версія
+├── README-DE.md # Німецька версія
+├── README-TR.md # Турецька версія
+├── README-PT-BR.md # Версія португальською (Бразилія)
+├── README-UK.md # Українська версія
+└── harness-creator/ # Навичка для інженерії harness
+ ├── SKILL.md # Основне визначення навички
+ ├── SKILL.md.en # Версія лише англійською
+ ├── README.md # Детальна документація
+ ├── metadata.json # Метадані та тригери навички
+ ├── agents/ # Метадані UI навички
+ ├── scripts/ # Помічники: скафолдинг, валідація, бенчмарк
+ ├── evals/ # Тестові кейси
+ ├── templates/ # Шаблони для скафолдингу
+ └── references/ # Докладні документи з патернів
+```
+
+## Як працюють навички
+
+Кожна навичка має стандартну структуру:
+
+1. **SKILL.md** — точка входу. Містить YAML-фронтматер (name, description для тригерингу) та інструкції для агента у форматі Markdown.
+2. **references/** — додаткові документи, що завантажуються в контекст за потреби.
+3. **templates/** — початкові шаблони, які навичка може генерувати для користувачів.
+
+Навички використовують прогресивне розкриття (progressive disclosure): агент спочатку бачить лише name + description, потім, коли спрацьовує тригер, завантажує повний вміст SKILL.md і лише за потреби читає супутні ресурси.
+
+## Аудит безпеки
+
+Усі файли в цьому каталозі пройшли аудит безпеки:
+
+- Без бекдорів, прихованих URL чи закодованих корисних навантажень
+- Без витоку даних чи жорстко закодованих облікових даних
+- Без вразливостей до ін'єкції команд
+- Скрипти використовують лише вбудовані модулі Node.js
+- Згенерований `init.sh` запускає виявлені команди верифікації проєкту
+
+## Ліцензія
+
+MIT
diff --git a/skills/README-VI.md b/skills/README-VI.md
index 0f61d81..0e73004 100644
--- a/skills/README-VI.md
+++ b/skills/README-VI.md
@@ -11,6 +11,7 @@
<a href="README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>
<a href="README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/Türkçe-d9d9d9"></a>
<a href="README-PT-BR.md"><img alt="Português (Brasil)" src="https://img.shields.io/badge/Português (Brasil)-d9d9d9"></a>
+ <a href="README-UK.md"><img alt="Українська" src="https://img.shields.io/badge/Українська-d9d9d9"></a>
</p>
# Skills
diff --git a/skills/README-ZH-TW.md b/skills/README-ZH-TW.md
index 8669fd4..0875c5d 100644
--- a/skills/README-ZH-TW.md
+++ b/skills/README-ZH-TW.md
@@ -11,6 +11,7 @@
<a href="README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>
<a href="README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/Türkçe-d9d9d9"></a>
<a href="README-PT-BR.md"><img alt="Português (Brasil)" src="https://img.shields.io/badge/Português (Brasil)-d9d9d9"></a>
+ <a href="README-UK.md"><img alt="Українська" src="https://img.shields.io/badge/Українська-d9d9d9"></a>
</p>
# Skills(技能集)
diff --git a/skills/README.md b/skills/README.md
index e6c6be8..ce482ed 100644
--- a/skills/README.md
+++ b/skills/README.md
@@ -11,6 +11,7 @@
<a href="README-DE.md"><img alt="Deutsch" src="https://img.shields.io/badge/Deutsch-d9d9d9"></a>
<a href="README-TR.md"><img alt="Türkçe" src="https://img.shields.io/badge/Türkçe-d9d9d9"></a>
<a href="README-PT-BR.md"><img alt="Português (Brasil)" src="https://img.shields.io/badge/Português (Brasil)-d9d9d9"></a>
+ <a href="README-UK.md"><img alt="Українська" src="https://img.shields.io/badge/Українська-d9d9d9"></a>
</p>
# Skills
@@ -52,6 +53,7 @@ skills/
├── README-DE.md # German version
├── README-TR.md # Turkish version
├── README-PT-BR.md # Portuguese (Brazil) version
+├── README-UK.md # Ukrainian version
└── harness-creator/ # Harness engineering skill
├── SKILL.md # Main skill definition
├── SKILL.md.en # English-only version
diff --git a/skills/harness-creator/README-UK.md b/skills/harness-creator/README-UK.md
new file mode 100644
index 0000000..037418f
--- /dev/null
+++ b/skills/harness-creator/README-UK.md
@@ -0,0 +1,83 @@
+# harness-creator
+
+Компактний скіл для побудови та аудиту harness навколо агентів AI-кодування.
+
+Він допомагає репозиторію забезпечити агентам п'ять необхідних речей: інструкції, стан, верифікацію, межі обсягу та передачу життєвого циклу.
+
+## Встановлення
+
+```bash
+npx skills add walkinglabs/learn-harness-engineering --skill harness-creator
+```
+
+Або скопіюйте `skills/harness-creator/` до вашого шляху скілів.
+
+## Використання
+
+```bash
+node skills/harness-creator/scripts/create-harness.mjs --target /path/to/project
+node skills/harness-creator/scripts/validate-harness.mjs --target /path/to/project
+node skills/harness-creator/scripts/run-benchmark.mjs --target /path/to/project --html /path/to/report.html
+```
+
+Скрипти використовують лише вбудовані модулі Node.js. Їх можна запускати після копіювання директорії скіла до іншого репозиторію.
+
+## Що створюється
+
+- `AGENTS.md` або `CLAUDE.md`
+- `feature_list.json`
+- `progress.md`
+- `init.sh`
+- `session-handoff.md`
+
+`create-harness.mjs` визначає поширені типи проєктів і пакетні менеджери. Підтримуються Node/npm/pnpm/yarn/bun, Python, Go, Rust, Maven, Gradle і .NET на базовому рівні команд верифікації.
+
+## Що перевіряється
+
+`validate-harness.mjs` оцінює п'ять підсистем harness:
+
+1. Інструкції
+2. Стан
+3. Верифікація
+4. Обсяг
+5. Життєвий цикл
+
+Оцінка є структурною. Вона показує, чи наявний harness і чи є він узгодженим; вона не замінює реального тестування сесій агента до і після змін.
+
+## Стан
+
+- [x] Мінімальне scaffolding harness
+- [x] Валідація п'яти підсистем
+- [x] HTML-звіт оцінки
+- [x] Структурний benchmark-звіт
+- [x] 10 eval-кейсів
+- [x] Загальне визначення верифікації для поширених стеків
+- [ ] Опціональне відтворення сесій агента до/після (реальне)
+
+## Файли
+
+```text
+harness-creator/
+├── SKILL.md
+├── metadata.json
+├── agents/openai.yaml
+├── scripts/
+│ ├── create-harness.mjs
+│ ├── validate-harness.mjs
+│ ├── render-assessment-html.mjs
+│ ├── run-benchmark.mjs
+│ └── lib/harness-utils.mjs
+├── templates/
+│ ├── agents.md
+│ ├── feature-list.json
+│ ├── feature-list.schema.json
+│ ├── init.sh
+│ ├── progress.md
+│ └── session-handoff.md
+├── references/
+└── evals/evals.json
+```
+
+## Межі
+
+Цей скіл призначений для інженерії harness, а не для вибору моделей, виключно для налаштування промптів або архітектури застосунку. Зберігайте специфічні факти проєкту в цільовому репозиторії.
diff --git a/skills/harness-creator/SKILL.md.uk b/skills/harness-creator/SKILL.md.uk
new file mode 100644
index 0000000..e6a0932
--- /dev/null
+++ b/skills/harness-creator/SKILL.md.uk
@@ -0,0 +1,107 @@
+---
+name: harness-creator
+description: >-
+ Побудова, аудит і вдосконалення легковагих harness для агентів AI-кодування: AGENTS.md/CLAUDE.md,
+ стан фіч, робочі процеси верифікації, межі обсягу, передача життєвого циклу,
+ персистентність пам'яті, керування контекстом, безпека інструментів і координація мультиагентів.
+license: MIT
+---
+
+# Harness Creator
+
+Використовуйте цей скіл, щоб зробити репозиторій зручнішим для агентів кодування: для старту роботи, утримання в межах обсягу, верифікації результатів і відновлення роботи між сесіями. Зберігайте harness достатньо малим, щоб агенти справді його дотримувались.
+
+Не призначений для вибору моделей, налаштування промптів окремо, проєктування chat UI або загальної архітектури застосунку.
+
+## Базова модель
+
+Кожен корисний harness агента кодування має п'ять підсистем:
+
+| Підсистема | Мінімальний артефакт | Призначення |
+|---|---|---|
+| Інструкції | `AGENTS.md` або `CLAUDE.md` | Шлях запуску, робочі правила, визначення завершеності |
+| Стан | `feature_list.json`, `progress.md` | Поточна фіча, статус, докази, наступний крок |
+| Верифікація | `init.sh` або задокументовані команди | Тести/перевірки, які агент має виконати перед тим, як оголосити завдання виконаним |
+| Обсяг | Залежності фіч і критерії завершеності | Запобігає виходу за межі та незавершеній роботі |
+| Життєвий цикл | `session-handoff.md`, процедура завершення сесії | Забезпечує можливість відновлення наступної сесії |
+
+## Перший крок
+
+1. Огляньте наявне: файли інструкцій, файли фіч/стану, команди верифікації, документацію, маніфести пакетів.
+2. Запитуйте лише про відсутній контекст, який неможливо безпечно вивести: цільовий агент, бажана назва файлу, допустима структура та чи дозволено перезаписування.
+3. Спочатку надавайте перевагу мінімальному harness. Додавайте пам'ять, безпеку інструментів, мультиагентність або деталі benchmark лише тоді, коли цього вимагає завдання користувача.
+
+## Типові завдання
+
+### Створення harness
+
+Використовуйте вбудований скрипт при роботі з локальним репозиторієм:
+
+```bash
+node skills/harness-creator/scripts/create-harness.mjs --target /path/to/project
+```
+
+Параметри:
+
+- `--agent-file CLAUDE.md` для проєктів, орієнтованих на Claude.
+- `--package-manager npm|pnpm|yarn|bun` якщо автовизначення невірне.
+- `--commands "cmd one,cmd two"` для власних команд верифікації.
+- `--force` лише після підтвердження, що перезаписування є прийнятним.
+
+Після цього поясніть, що було створено, і як користувач має замінити placeholder-записи фіч.
+
+### Аудит наявного harness
+
+Запустіть:
+
+```bash
+node skills/harness-creator/scripts/validate-harness.mjs --target /path/to/project
+```
+
+Надайте звіт з оцінками п'яти підсистем, найнижчою оцінкою та першими 2-3 змінами, які підвищать надійність. Розглядайте найнижчу оцінку як потенційне вузьке місце; підтверджуйте це через збої, логи або результати завдань, перш ніж стверджувати про причинно-наслідковий зв'язок.
+
+### Формування звіту
+
+Використовуйте, коли користувач хоче отримати звіт для поширення:
+
+```bash
+node skills/harness-creator/scripts/render-assessment-html.mjs --target /path/to/project
+node skills/harness-creator/scripts/run-benchmark.mjs --target /path/to/project --html /path/to/report.html
+```
+
+Чітко зазначайте, що це структурний benchmark. Реальна ефективність потребує сесій агента до і після на репрезентативних завданнях.
+
+## Коли читати довідники
+
+Завантажуйте лише той довідник, який потрібний для вирішення завдання користувача:
+
+- Пам'ять між сесіями: [Memory Persistence](references/memory-persistence-pattern.md)
+- Повторно використовувані робочі процеси як скіли: [Skill Runtime](references/skill-runtime-pattern.md)
+- Дозволи, інструменти, конкурентність: [Tool Registry & Safety](references/tool-registry-pattern.md)
+- Бюджет контексту та поступове розкриття: [Context Engineering](references/context-engineering-pattern.md)
+- Делегування та паралельні агенти: [Multi-Agent Coordination](references/multi-agent-pattern.md)
+- Хуки, запуск, тривала робота: [Lifecycle & Bootstrap](references/lifecycle-bootstrap-pattern.md)
+- Неочевидні режими збоїв: [Gotchas](references/gotchas.md)
+
+## Правила проєктування
+
+- Зберігайте кореневий файл інструкцій коротким: маршрутизація та інваріанти, а не повний посібник.
+- Розміщуйте факти проєкту в документації проєкту, а не в скілі.
+- Робіть команди верифікації явними і придатними до виконання.
+- Вимагайте доказів перед тим, як позначати фічу виконаною.
+- Використовуйте одну активну фічу, якщо harness не має явних меж власності для мультиагентів.
+- Надавайте перевагу додаванню/оновленню файлів стану над покладанням на історію чату.
+- Ніколи не приховуйте деструктивну поведінку в скриптах; перезаписування потребує явного схвалення користувача.
+
+## Контрольний список результатів
+
+Для придатного до використання мінімального harness залиште в цільовому проєкті:
+
+- [ ] `AGENTS.md` або `CLAUDE.md`
+- [ ] `feature_list.json`
+- [ ] `progress.md`
+- [ ] `init.sh`
+- [ ] Опціональний `session-handoff.md` для багатосесійної роботи
+- [ ] Задокументовані докази верифікації або наступна дія
+
+Якщо ви не можете створити файли — надайте точний вміст файлів і команди замість цього.