Skip to content

Harness engineering beginner tutorial, from 0 to 1

add Russian (ru) locale

Aliaksei1722a9a47b36
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 14dd6f9..d1b4185 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -80,6 +80,43 @@ const enSkillItems = [
{ text: "Skills Overview", link: "/en/skills/" }
];
+const ruLectureItems = [
+ { text: "Добро пожаловать", link: "/ru/" },
+ { text: "Сильная модель ≠ надёжное исполнение", link: "/ru/lectures/lecture-01-why-capable-agents-still-fail/" },
+ { text: "Что такое harness на самом деле", link: "/ru/lectures/lecture-02-what-a-harness-actually-is/" },
+ { text: "Репозиторий как единый источник правды", link: "/ru/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/" },
+ { text: "Почему один большой файл инструкций не работает", link: "/ru/lectures/lecture-04-why-one-giant-instruction-file-fails/" },
+ { text: "Как сохранять контекст между сессиями", link: "/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/" },
+ { text: "Зачем инициализация — отдельная фаза", link: "/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/" },
+ { text: "Почему агенты делают слишком много или слишком мало", link: "/ru/lectures/lecture-07-why-agents-overreach-and-under-finish/" },
+ { text: "Списки фич как примитивы harness", link: "/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/" },
+ { text: "Почему агенты слишком рано объявляют успех", link: "/ru/lectures/lecture-09-why-agents-declare-victory-too-early/" },
+ { text: "Только сквозной прогон — настоящая проверка", link: "/ru/lectures/lecture-10-why-end-to-end-testing-changes-results/" },
+ { text: "Наблюдаемость — часть harness", link: "/ru/lectures/lecture-11-why-observability-belongs-inside-the-harness/" },
+ { text: "Каждая сессия должна оставлять чистое состояние", link: "/ru/lectures/lecture-12-why-every-session-must-leave-a-clean-state/" }
+];
+
+const ruProjectItems = [
+ { text: "Добро пожаловать", link: "/ru/projects/" },
+ { text: "Только промпты vs правила", link: "/ru/projects/project-01-baseline-vs-minimal-harness/" },
+ { text: "Рабочее пространство для агента", link: "/ru/projects/project-02-agent-readable-workspace/" },
+ { text: "Непрерывность между сессиями", link: "/ru/projects/project-03-multi-session-continuity/" },
+ { text: "Обратная связь и контроль скоупа", link: "/ru/projects/project-04-incremental-indexing/" },
+ { text: "Самопроверка и обоснованные ответы", link: "/ru/projects/project-05-grounded-qa-verification/" },
+ { text: "Полный harness (капстоун)", link: "/ru/projects/project-06-runtime-observability-and-debugging/" }
+];
+
+const ruResourceItems = [
+ { text: "Обзор", link: "/ru/resources/" },
+ { text: "Шаблоны", link: "/ru/resources/templates/" },
+ { text: "Справочник", link: "/ru/resources/reference/" },
+ { text: "Расширенный пакет", link: "/ru/resources/openai-advanced/" }
+];
+
+const ruSkillItems = [
+ { text: "Обзор скиллов", link: "/ru/skills/" }
+];
+
export default withMermaid(
defineConfig({
base: docsBase,
@@ -183,6 +220,43 @@ export default withMermaid(
darkModeSwitchTitle: "切换到深色模式",
socialLinks: [{ icon: "github", link: githubRepoTreeLink }]
}
+ },
+ ru: {
+ label: "Русский",
+ lang: "ru",
+ link: "/ru/",
+ themeConfig: {
+ nav: [
+ { text: "Лекции", link: ruLectureItems[1].link, activeMatch: '^/ru/(lectures/.*)?$' },
+ { text: "Проекты", link: ruProjectItems[0].link, activeMatch: '^/ru/projects/' },
+ { text: "Материалы", link: "/ru/resources/", activeMatch: '^/ru/resources/' },
+ { text: "Скиллы", link: "/ru/skills/", activeMatch: '^/ru/skills/' },
+ { text: "Try Harness ↗", link: "https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/ru/resources/templates/index.md", target: "_blank", rel: "noopener noreferrer" }
+ ],
+ sidebar: {
+ '/ru/projects/': [{ text: "Проекты", items: ruProjectItems }],
+ '/ru/resources/': [{ text: "Материалы", items: ruResourceItems }],
+ '/ru/skills/': [{ text: "Скиллы", items: ruSkillItems }],
+ '/ru/': [{ text: "Лекции", items: ruLectureItems }]
+ },
+ outline: {
+ level: [2, 3],
+ label: "На этой странице"
+ },
+ docFooter: {
+ prev: "Предыдущая",
+ next: "Следующая"
+ },
+ lastUpdated: {
+ text: "Последнее обновление"
+ },
+ returnToTopLabel: "Наверх",
+ sidebarMenuLabel: "Меню",
+ darkModeSwitchLabel: "Тема",
+ lightModeSwitchTitle: "Включить светлую тему",
+ darkModeSwitchTitle: "Включить тёмную тему",
+ socialLinks: [{ icon: "github", link: githubRepoTreeLink }]
+ }
}
}
}));
diff --git a/docs/ru/index.md b/docs/ru/index.md
new file mode 100644
index 0000000..66e916b
--- /dev/null
+++ b/docs/ru/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["Чёткая цель<br/>AGENTS.md"] --> B("Инициализация<br/>init.sh")
+ B --> C{"Выполнение задач<br/>AI Agent"}
+ C -->|Возникла проблема| D["Обратная связь<br/>CLI / Логи"]
+ D -->|Автоисправление| C
+ C -->|Код готов| E{"Проверка и QA<br/>Тесты"}
+ E -->|Провал| D
+ E -->|Пройдено| F["Очистка и передача<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: Базовый vs минимальный harness</a>: пройдите первое реальное задание.</li>
+ <li><a href="./resources/templates/">Шаблоны</a>: возьмите минимальный набор (AGENTS.md, feature_list.json, claude-progress.md) для своих проектов.</li>
+</ul>
diff --git a/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts b/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/code/failure-pattern-demo.ts
new file mode 100644
index 0000000..311e665
--- /dev/null
+++ b/docs/ru/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/ru/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md b/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md
new file mode 100644
index 0000000..ab35662
--- /dev/null
+++ b/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/code/failure-signals-checklist.md
@@ -0,0 +1,10 @@
+# Чеклист сигналов о провале
+
+Используйте этот чеклист при разборе прогона со слабым harness.
+
+- Спросил ли агент, как запускать приложение, или сделал неверные предположения?
+- Создал ли он каталоги или абстракции, не соответствующие задуманному
+ продукту?
+- Остановился ли он после визуальной UI-оболочки без полного рабочего сценария?
+- Оставил ли он заметки или артефакты, помогающие следующему прогону продолжить?
+- Сможет ли свежая сессия понять, что произошло, меньше чем за пять минут?
diff --git a/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/code/index.md b/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/code/index.md
new file mode 100644
index 0000000..1d72c04
--- /dev/null
+++ b/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/code/index.md
@@ -0,0 +1,7 @@
+# Код для Лекции 01
+
+Используйте эту папку для небольших примеров, демонстрирующих:
+
+- сильную модель, проваливающуюся в слабой среде
+- недоопределённую конфигурацию репозитория
+- отсутствие петель обратной связи
diff --git a/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md b/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md
new file mode 100644
index 0000000..f1af214
--- /dev/null
+++ b/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/code/underspecified-task.md
@@ -0,0 +1,18 @@
+# Пример недоопределённой задачи
+
+Сделай десктоп-приложение базы знаний с AI-ответами на вопросы.
+
+Ограничения:
+
+- Не указаны
+- Команда запуска не задана
+- Структура папок не описана
+- Модель данных не определена
+- Явных критериев готовности нет
+
+Типичные исходы такого промпта:
+
+- агент изобретает структуру на ходу
+- приложение может собираться, но запускается нестабильно
+- UI может появиться раньше, чем будет рабочий путь ингеста/запросов
+- агент часто останавливается после косметического успеха
diff --git a/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/index.md b/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/index.md
new file mode 100644
index 0000000..871733c
--- /dev/null
+++ b/docs/ru/lectures/lecture-01-why-capable-agents-still-fail/index.md
@@ -0,0 +1,117 @@
+[中文版本 →](../../../zh/lectures/lecture-01-why-capable-agents-still-fail/)
+
+> Примеры кода: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-01-why-capable-agents-still-fail/code/)
+> Практический проект: [Project 01. Prompt-only vs. rules-first](./../../projects/project-01-baseline-vs-minimal-harness/index.md)
+
+# Лекция 01. Сильные модели не означают надёжного исполнения
+
+Считаете себя бывалым в мире AI — есть подписка Claude Pro, ключ к API GPT-4o, цифры с лидерборда SWE-bench выучены наизусть. И вот вы наконец отдаёте AI-агенту реальный проект, переполненные уверенностью. Результат? Он добавляет фичу, но ломает тесты, чинит баг, но создаёт два новых, работает 20 минут и гордо заявляет «готово» — а вы смотрите на код и видите, что это совсем не то, о чём вы просили.
+
+Первая мысль? «Модель слабовата. Пора апгрейдиться». Стоп. Прежде чем доставать кошелёк, подумайте: возможно, проблема вовсе не в модели.
+
+Посмотрим на цифры. К концу 2025 года самые сильные кодинг-агенты на SWE-bench Verified выдают примерно 50–60%. И это на тщательно отобранных задачах с понятными описаниями issue и существующими тестами. Перейдите в свою повседневную среду разработки — расплывчатые требования, отсутствие тестов, неявные бизнес-правила, разбросанные повсюду — и эта цифра только падает.
+
+Но за этими числами скрывается контринтуитивная истина.
+
+## Один и тот же конь, разные судьбы
+
+Anthropic провели контролируемый эксперимент. Один и тот же промпт («собери 2D ретро-конструктор игр»), одна и та же модель (Opus 4.5). Первый прогон: голая среда без поддержки — 20 минут, $9, ключевые механики игры просто не работают. Второй прогон: полный harness (архитектура из трёх агентов: planner + generator + evaluator) — 6 часов, $200, в игру можно играть.
+
+Модель не меняли. Opus 4.5 оставался Opus 4.5. Изменилось седло.
+
+Статья OpenAI 2025 года про harness engineering говорит прямо: Codex в репозитории с хорошим harness переходит из «ненадёжного» в «надёжный». Обратите внимание на формулировку — не «чуть лучше», а качественный сдвиг. Как с породистой лошадью: ездить можно и без седла, но далеко не уедете, быстро не разгонитесь, и упасть — не сюрприз. Harness и есть это седло — **всё в инженерной инфраструктуре, что находится за пределами весов модели.**
+
+## Где на самом деле застревают агенты
+
+Так что же конкретно идёт не так?
+
+Самое частое: вы так и не определили задачу чётко. Говорите «добавь поиск», а агент понимает это совсем не так, как вы — поиск чего? Полнотекстовый или структурированный? Пагинация? Подсветка? Вы не уточнили — агент гадает. Угадал — повезло; не угадал — фиксить дороже, чем было бы изначально внятно поставить задачу. Это как зайти в ресторан и сказать повару «я буду рыбу» — будет ли она тушёная, на пару или в горячем горшочке, остаётся на волю случая.
+
+Даже если вы всё указали, в проекте есть неявные архитектурные конвенции, о которых агент не знает. Ваша команда стандартизировала синтаксис SQLAlchemy 2.0, а агент по умолчанию пишет код 1.x. Все API-эндпоинты должны использовать OAuth 2.0, но это правило существует только в вашей голове и в сообщении в Slack трёхмесячной давности. Агент этого не видит — не то чтобы он не хотел соблюдать, он буквально не знает, что эти правила существуют.
+
+Среда — тоже ловушка. Неполная dev-среда, отсутствующие зависимости, неправильные версии инструментов. Агент жжёт драгоценное окно контекста на ошибки `pip install` и несовпадения версий Node вместо того, чтобы решать вашу реальную задачу. Как нанять умелого плотника, но забыть дать ему молоток, гвозди и ровный верстак — каким бы талантливым он ни был, работу он не сделает.
+
+Ещё чаще: попросту нет способа верифицировать. Нет тестов, нет линта, или команды проверки никогда не были донесены до агента. Агент пишет код, смотрит на него, решает что норм, говорит «готово». Это как просить студента сдать домашку, не дав ему ответника — он думает, что всё правильно, а при проверке — куча ошибок. Anthropic заметили любопытное явление: когда агент чувствует, что контекст заканчивается, он торопится закончить, пропускает верификацию и выбирает простое решение вместо оптимального. Они называют это «контекстной тревогой» — тем же, что случается, когда вы понимаете, что время на экзамене на исходе, и начинаете наугад тыкать в оставшихся тестовых вопросах.
+
+Длинные задачи на несколько сессий — ещё хуже: все находки прошлой сессии теряются, и каждая новая сессия заново исследует структуру проекта и заново разбирается в организации кода. У агентов без персистентного состояния процент провалов резко растёт на задачах длиннее 30 минут.
+
+## Ключевые понятия
+
+Когда вы видите эти сценарии вживую, термины перестают быть просто жаргоном:
+
+- **Capability Gap**: огромная пропасть между производительностью модели на бенчмарках и на реальных задачах. 50–60% pass rate на SWE-bench Verified означает, что почти половина реальных issue не решается.
+- **Harness**: всё за пределами модели — инструкции, инструменты, среда, управление состоянием, верификационная обратная связь. Если это не веса модели — это harness. То самое «седло».
+- **Harness-Induced Failure**: у модели достаточно способностей, но в среде исполнения есть структурные дефекты. Контролируемый эксперимент Anthropic это уже доказал.
+- **Verification Gap**: разрыв между уверенностью агента в своей работе и реальной корректностью. Агент говорит «я закончил», когда не закончил — самый частый паттерн провала.
+- **Diagnostic Loop**: выполнить, увидеть провал, отнести его к конкретному слою harness, починить этот слой, выполнить снова. Это ядро методологии harness engineering.
+- **Definition of Done**: набор машинно-проверяемых условий — тесты проходят, линт чистый, проверки типов проходят. Без явного definition of done агент придумает свой.
+
+## Когда что-то ломается — чините harness первым
+
+Главный принцип: **когда что-то ломается, не меняйте сразу модель — проверьте harness.** Если та же модель справляется со схожими, хорошо структурированными задачами, считайте, что проблема в harness. Это как с поломкой машины — вы же не сразу подозреваете двигатель. Сначала проверяете, не закончился ли бензин.
+
+Конкретные шаги:
+
+**Привязывайте каждый провал к конкретному слою.** Не ограничивайтесь «модель тупит». Спросите: задача была размыта? Контекста не хватало? Не было способов верификации? Сопоставьте каждый провал с одним из пяти слоёв выше. Выработайте эту привычку — и в ваших логах «модель недостаточно хороша» будет всплывать всё реже.
+
+**Пишите явный Definition of Done для каждой задачи.** Не «добавь поиск». А:
+```
+Критерии готовности:
+- Новый эндпоинт GET /api/search?q=xxx
+- Поддержка пагинации, по умолчанию 20 элементов
+- В результатах подсвеченные сниппеты
+- Весь новый код проходит pytest
+- Проверка типов проходит (mypy --strict)
+```
+
+**Заведите файл AGENTS.md.** Положите его в корень репо, чтобы рассказать агенту про стек проекта, архитектурные конвенции и команды верификации. Это первый шаг harness engineering и шаг с самым высоким ROI. Один файл `AGENTS.md` может быть эффективнее апгрейда на более дорогую модель — я не шучу.
+
+**Постройте диагностическую петлю.** Не относитесь к провалам как к «модель опять тупит». Считайте их сигналами, что в вашем harness есть дефект. На каждом провале определите слой, почините его, никогда больше так не падайте. Через несколько итераций harness крепнет, а производительность агента стабилизируется. Как ремонт дороги — каждая засыпанная яма делает следующий участок ровнее.
+
+**Измеряйте улучшения.** Ведите простой лог: каждая задача — успех или провал, и какой слой стал причиной провала. Через несколько кругов вы увидите, какой слой — бутылочное горлышко. Туда и направляйте усилия.
+
+## Эксперимент в миллион строк
+
+В 2025 году OpenAI провели агрессивный эксперимент: с помощью Codex построить целый внутренний продукт из пустого git-репозитория. Через пять месяцев в репо было примерно миллион строк кода — прикладная логика, инфраструктура, инструментарий, документация, внутренние dev-инструменты — всё сгенерировано агентом. Три инженера управляли Codex, открыли и смержили около 1500 PR. В среднем 3,5 PR на человека в день.
+
+Ключевое ограничение: **люди не пишут код напрямую.** Это была не показуха — так заставили команду понять, что меняется, когда основная работа инженера — уже не написание кода, а проектирование сред, формулирование намерения и построение петель обратной связи.
+
+В начале прогресс был медленнее ожидаемого. Не потому что у 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 и заявил о завершении, в то время как у эндпоинта были рантайм-ошибки. Следующая сессия должна была заново проделать всю разведку.
+
+Потом они добавили `AGENTS.md` (с описанием архитектуры проекта и версий стека), явные команды верификации (`pytest tests/api/v2/ && python -m mypy src/`) и architecture decision records. Та же модель успешно справилась во всех трёх независимых прогонах, и эффективность контекста выросла примерно на 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. **Замер verification gap**: возьмите 5 кодинг-задач. После каждой зафиксируйте, заявил ли агент о завершении, а затем независимыми тестами проверьте реальную корректность. Посчитайте долю случаев, когда агент говорит «готово», а на самом деле нет — это и есть ваш verification gap. Затем подумайте: какие команды верификации сократили бы эту долю?
+
+3. **Практика диагностической петли**: найдите в проекте задачу, на которой агент стабильно падает. Прогоните один раз, зафиксируйте провал. Отнесите его к одному из пяти слоёв. Почините слой. Прогоните снова. Повторите три–пять раз, фиксируя улучшения каждый раз.
diff --git a/docs/ru/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md b/docs/ru/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md
new file mode 100644
index 0000000..46efa38
--- /dev/null
+++ b/docs/ru/lectures/lecture-02-what-a-harness-actually-is/code/harness-components.md
@@ -0,0 +1,21 @@
+# Пример компонентов harness
+
+Для кодинг-агента, работающего в локальном репозитории:
+
+- Модель:
+ сама LLM
+
+- Harness:
+ - системный промпт
+ - AGENTS.md
+ - инструмент bash
+ - инструменты чтения/записи файлов
+ - доступ к git
+ - локальная файловая система
+ - стартовые скрипты
+ - команды тестирования
+ - stop-хуки
+ - проверки линтера
+ - петля evaluator
+
+Если поменять любой из перечисленных компонентов harness — вы меняете эффективного агента.
diff --git a/docs/ru/lectures/lecture-02-what-a-harness-actually-is/code/harness-vs-no-harness.ts b/docs/ru/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/ru/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/ru/lectures/lecture-02-what-a-harness-actually-is/code/index.md b/docs/ru/lectures/lecture-02-what-a-harness-actually-is/code/index.md
new file mode 100644
index 0000000..3458324
--- /dev/null
+++ b/docs/ru/lectures/lecture-02-what-a-harness-actually-is/code/index.md
@@ -0,0 +1,8 @@
+# Код для Лекции 02
+
+Используйте эту папку для небольших примеров, разделяющих:
+
+- поведение модели
+- поведение harness
+- конфигурации только с промптом
+- конфигурации агента с поддержкой среды
diff --git a/docs/ru/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts b/docs/ru/lectures/lecture-02-what-a-harness-actually-is/code/minimal-harness-loop.ts
new file mode 100644
index 0000000..e56cddd
--- /dev/null
+++ b/docs/ru/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/ru/lectures/lecture-02-what-a-harness-actually-is/index.md b/docs/ru/lectures/lecture-02-what-a-harness-actually-is/index.md
new file mode 100644
index 0000000..3fd909a
--- /dev/null
+++ b/docs/ru/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/en/lectures/lecture-02-what-a-harness-actually-is/code/)
+> Практический проект: [Project 01. Prompt-only vs. rules-first](./../../projects/project-01-baseline-vs-minimal-harness/index.md)
+
+# Лекция 02. Что на самом деле означает harness
+
+Слово «harness» в кругах AI-кодинг-агентов разбрасывают направо и налево, но честно говоря, большинство людей под ним подразумевает «файл с промптом». Это не harness. Это как открыть ресторан, имея только продукты — без плиты, без ножей, без рецептов, без процесса подачи. Это не ресторан. Это холодильник.
+
+В этой лекции вы получите точное и применимое определение harness. Не академическую абстракцию, а фреймворк, который можно использовать уже сегодня: harness состоит из пяти подсистем, у каждой — чёткие обязанности и критерии оценки.
+
+## Начнём с аналогии
+
+Представьте, что вы только что нанятый инженер, которого бросили в проект без какой-либо документации. Нет README, нет комментариев в коде, никто не сказал, как запускать тесты, конфиг CI закопан где-то глубоко. Сможете ли вы писать хороший код? Возможно — если вы достаточно умны и терпеливы. Но огромное количество времени уйдёт на «разобраться, что это вообще за проект», а не на «решить задачу».
+
+AI-агент сталкивается ровно с той же ситуацией. И ему хуже — вы хоть коллегу можете спросить. Агент видит только файлы, которые вы ему положите, и команды, которые он может выполнить. Он не может постучать кому-то по плечу и спросить «слушай, какой версии ORM здесь используется?».
+
+OpenAI формулируют главный принцип так: «the repo IS the spec» — весь необходимый контекст должен жить в репозитории, передаваясь через структурированные файлы инструкций, явные команды верификации и понятную организацию каталогов. В документации Anthropic про долгоживущих агентов делается упор на персистентность состояния, явные пути восстановления и структурированное отслеживание прогресса. Эти две компании смотрят на разные аспекты, но говорят об одном и том же: **всё в инженерной инфраструктуре за пределами модели определяет, какая часть способностей модели реально проявится на практике.**
+
+Посмотрите на знакомые вам инструменты:
+
+**Claude Code** воплощает harness-мышление. Он читает `CLAUDE.md` из вашего репо (полка с рецептами), может выполнять shell-команды (стойка с ножами), исполняется в вашей локальной среде (плита), хранит историю сессии (заготовочный стол) и может запускать тесты и видеть результаты (окно контроля качества). Но если вы не сказали ему, как запускать тесты, окно контроля качества разбито — никто не знает, готово ли блюдо.
+
+**Cursor** следует той же логике. Файл `.cursorrules` — это полка с рецептами, терминал — стойка с ножами, он читает структуру проекта и конфиг линтера для плиты. Но управление состоянием у Cursor сравнительно слабое — закрыли IDE, открыли заново, и предыдущий контекст пропал.
+
+**Codex** (кодинг-агент OpenAI) использует git worktrees, чтобы изолировать рантайм-среду каждой задачи, в паре с локальным observability-стеком (логи, метрики, трейсы), так что каждое изменение проверяется в независимом окружении. В репозиториях с `AGENTS.md` и понятными командами верификации он работает гораздо лучше, чем в «голых» репо.
+
+**AutoGPT** — поучительный антипример: отсутствие структурированного управления состоянием приводит к накоплению контекста на длинных задачах, а отсутствие точных механизмов обратной связи заставляет агента ходить кругами. Многие говорят, что AutoGPT «не работает», но на самом деле не работает harness AutoGPT — дайте повару сломанную плиту, и даже из лучших продуктов еды не выйдет.
+
+## Ключевые понятия
+
+- **Что такое harness**: всё в инженерной инфраструктуре за пределами весов модели. OpenAI сводят основную работу инженера к трём вещам: проектирование сред, выражение намерения и построение петель обратной связи. Anthropic называют свой Claude Agent SDK «универсальным harness для агентов».
+- **Репозиторий — единственный источник истины**: то, чего агент не видит, для всех практических целей не существует. OpenAI рассматривают репо как «system of record» — весь необходимый контекст должен жить там, через структурированные файлы и понятную организацию каталогов.
+- **Дайте карту, а не учебник**: опыт OpenAI — `AGENTS.md` должен быть оглавлением, а не энциклопедией. Около 100 строк — достаточно. Если не помещается, выносите в каталог `docs/` и пусть агент читает по необходимости.
+- **Ограничивайте, а не микроменеджите**: хороший harness ограничивает агента исполняемыми правилами, а не перечисляет инструкции одну за другой. OpenAI говорят «enforce invariants, don't micromanage implementation»; Anthropic обнаружили, что агенты уверенно хвалят свою же работу, и решение — разделить «того, кто делает» и «того, кто проверяет».
+- **Удаляйте компоненты по одному**: чтобы измерить ценность каждого компонента harness, удаляйте их по одному и смотрите, какое удаление сильнее всего просаживает производительность. Anthropic именно так и делали — и обнаружили, что по мере усиления моделей некоторые компоненты перестают быть критичными, но всегда появляются новые.
+
+## Модель harness из пяти подсистем
+
+Возвращаемся к кухонной аналогии. У полноценной кухни пять функциональных зон, и у harness — пять подсистем:
+
+```mermaid
+flowchart LR
+ Rules["Правила проекта<br/>AGENTS.md / CLAUDE.md"] --> Agent["AI-агент"]
+ State["Прогресс и git<br/>PROGRESS.md / коммиты"] --> Agent
+ Agent --> Tools["Инструменты<br/>shell / файлы / тесты"]
+ Tools --> Env["Рантайм<br/>зависимости / сервисы / версии"]
+ Env --> Checks["Результаты проверок<br/>test / lint / build"]
+ Checks --> Agent
+```
+
+**Подсистема инструкций (полка с рецептами)**: создайте `AGENTS.md` (или `CLAUDE.md`), содержащий обзор и цель проекта (одно предложение), стек и версии (Python 3.11, FastAPI 0.100+, PostgreSQL 15), команды первого запуска (`make setup`, `make test`), необсуждаемые жёсткие ограничения («все API должны использовать OAuth 2.0») и ссылки на более детальную документацию.
+
+**Подсистема инструментов (стойка с ножами)**: убедитесь, что у агента есть достаточный доступ к инструментам. Не отключайте shell ради «безопасности» — если агент не может даже запустить `pip install`, как ему работать? Но и не открывайте всё подряд — следуйте принципу наименьших привилегий.
+
+**Подсистема среды (плита)**: сделайте состояние среды самоописательным. Используйте `pyproject.toml` или `package.json`, чтобы залочить зависимости, `.nvmrc` или `.python-version` — для версий рантайма, Docker или devcontainers — для воспроизводимости.
+
+**Подсистема состояния (заготовочный стол)**: длинным задачам нужно отслеживание прогресса. Используйте простой файл `PROGRESS.md`, фиксирующий: что сделано, что в работе, что заблокировано. Обновляйте перед концом каждой сессии, читайте в начале следующей.
+
+**Подсистема обратной связи (окно контроля качества)**: подсистема с самым высоким ROI. Явно перечислите команды верификации в `AGENTS.md`:
+```
+Команды верификации:
+- Тесты: pytest tests/ -x
+- Проверка типов: mypy src/ --strict
+- Линт: ruff check src/
+- Полная верификация: make check (включает всё выше)
+```
+
+Отсутствие любой подсистемы — как отсутствие функциональной зоны на кухне: готовить можно, но всегда будет неудобно.
+
+**Диагностика качества harness**: используйте «изометрический контроль модели». Зафиксируйте модель, удаляйте подсистемы по одной, измеряйте, какое удаление сильнее всего просаживает производительность. Это и есть бутылочное горлышко — туда направляйте усилия. Как в поиске бутылочного горлышка на кухне: уберите полку с рецептами и посмотрите, насколько всё замедлится; выключите плиту и оцените эффект.
+
+## Реальная история одной команды
+
+Команда использовала GPT-4o на TypeScript + React фронтенде (~20 000 строк кода). Они прошли четыре стадии — по сути, добавляя кухонное оборудование по одной единице:
+
+**Стадия 1 — пустая кухня**: только базовое описание проекта в README. Из 5 прогонов успешен 1 (20%). Главные провалы: выбран не тот пакетный менеджер (npm vs yarn), не соблюдены конвенции именования компонентов, не получалось запустить тесты.
+
+**Стадия 2 — установлена полка с рецептами**: добавили `AGENTS.md` с версиями стека, конвенциями именования, ключевыми архитектурными решениями. Успешность выросла до 60%. Оставшиеся провалы — в основном проблемы среды и отсутствие верификации.
+
+**Стадия 3 — открыто окно контроля качества**: в `AGENTS.md` перечислены команды верификации: `yarn test && yarn lint && yarn build`. Успешность выросла до 80%.
+
+**Стадия 4 — заготовочный стол готов**: ввели шаблоны файлов прогресса, в которых агент в каждом прогоне фиксировал сделанное и оставшееся. Успешность стабилизировалась на 80–100%.
+
+Четыре итерации, модель не менялась вообще, успешность ушла с 20% к почти 100%. В этом сила harness engineering. Вы не покупали более дорогие продукты — вы просто навели порядок на кухне.
+
+## Главное
+
+- 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://humanlayer.dev/articles/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. **Анализ affordance**: найдите в проекте сценарий, где агент «хочет что-то сделать, но не может» (например, знает, что нужны параметризованные запросы, но не знает паттернов ORM в вашем проекте). Разберите, это Gulf of Execution (не знает, как) или Gulf of Evaluation (не знает, правильно ли). Затем спроектируйте улучшение harness, чтобы перекрыть этот разрыв.
diff --git a/docs/ru/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md b/docs/ru/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md
new file mode 100644
index 0000000..ba8e0b0
--- /dev/null
+++ b/docs/ru/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/index.md
@@ -0,0 +1,7 @@
+# Код для Лекции 03
+
+Используйте эту папку для примеров:
+
+- читаемых агентом структур репо
+- документации как system of record
+- плохого vs хорошего размещения знаний
diff --git a/docs/ru/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-knowledge-layout.txt b/docs/ru/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/ru/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/ru/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/repo-reader.ts b/docs/ru/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/ru/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/ru/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md b/docs/ru/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md
new file mode 100644
index 0000000..da82f25
--- /dev/null
+++ b/docs/ru/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/system-of-record-checklist.md
@@ -0,0 +1,11 @@
+# Чеклист system of record
+
+Может ли свежий агент узнать из одного только репо:
+
+- Какой продукт строится?
+- Что приложение должно делать для пользователей?
+- Как устроена кодовая база?
+- Как запускается приложение?
+- Как проверяется здоровье?
+- Какая работа сейчас в процессе?
+- Какие стандарты качества важны?
diff --git a/docs/ru/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md b/docs/ru/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/index.md
new file mode 100644
index 0000000..8479be5
--- /dev/null
+++ b/docs/ru/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/en/lectures/lecture-03-why-the-repository-must-become-the-system-of-record/code/)
+> Практический проект: [Project 02. Agent-readable workspace](./../../projects/project-02-agent-readable-workspace/index.md)
+
+# Лекция 03. Сделайте репозиторий своим единственным источником истины
+
+Архитектурные решения вашей команды разбросаны по Confluence, Slack, Jira и головам нескольких сеньоров. Для людей это кое-как работает — можно спросить коллегу, поискать в чате, покопаться в доках. В крайнем случае поймать кого-то в курилке. Но для AI-агента информация, которой нет в репозитории, попросту не существует.
+
+Это не преувеличение. Подумайте, что вообще является входом для агента: системные промпты и описания задач, содержимое файлов из репозитория, вывод инструментов. И всё. Ваша история в Slack, тикеты в Jira, страницы в Confluence и то архитектурное решение, которое вы обсудили с коллегой за кофе в пятницу днём — агент ничего из этого не видит. Он не может «пойти спросить» или «поискать в чате». Это инженер, запертый внутри репозитория — что снаружи, он не знает.
+
+Так что вопрос ставится так: дадите ли вы этому инженеру хорошую карту?
+
+## Что должно быть на карте
+
+OpenAI говорят это прямо: **информации, которой нет в репо, для агента не существует.** Они называют это принципом «repo as spec» — сам репозиторий и есть спецификационный документ высшей инстанции.
+
+Документация Anthropic про долгоживущих агентов вторит: персистентное состояние — необходимое условие непрерывности длинных задач. Восстановимость знаний между сессиями напрямую определяет успешность задач. И это состояние должно жить в репозитории — потому что это единственное стабильное, доступное хранилище у агента.
+
+Вы можете подумать: «У нас маленькая команда, знания в головах, и всё нормально работает». Хорошо, для людей. Но если вы используете агента, примите факт: агент не может никого спрашивать. Всё, что ему нужно знать, должно быть записано и положено там, где он сможет это найти.
+
+Это не про «писать больше документации». Это про «класть информацию о решениях в правильное место». 50 строк `ARCHITECTURE.md` в каталоге `src/api/` в десять тысяч раз полезнее, чем 500-страничный design-документ в Confluence, который никто не поддерживает. Это как нарисованная от руки карта офиса, приклеенная к столу, против красивого архитектурного чертежа, запертого в шкафу — первая под рукой, когда нужно; вторая технически круче, но в нужный момент бесполезна.
+
+## Видимость знаний
+
+```mermaid
+flowchart LR
+ Slack["Правила в Slack"] --> Write["Запишите их в файлы репо<br/>AGENTS.md / ARCHITECTURE.md / PROGRESS.md"]
+ Confluence["Правила в Confluence"] --> Write
+ Heads["Правила в головах"] --> Write
+ Jira["Правила в тикетах Jira"] --> Write
+ Write --> Repo["Файлы репозитория"]
+ Repo --> Agent["Новая сессия агента<br/>читает репо напрямую"]
+ Warning["Если правила нет в репо,<br/>агент его не видит"] --> Agent
+```
+
+Как проверить, достаточно ли хороша ваша карта? Запустите «тест холодного старта»: откройте абсолютно новую сессию агента, дайте ему только содержимое репо и посмотрите, ответит ли он на пять базовых вопросов:
+
+```mermaid
+flowchart TB
+ Q1["Что это за система?"] --> A1["AGENTS.md / README"]
+ Q2["Как она устроена?"] --> A2["ARCHITECTURE.md / документы модулей"]
+ Q3["Как её запустить?"] --> A3["Makefile / init.sh / скрипты пакетов"]
+ Q4["Как её проверить?"] --> A4["Команды тестов, линта и проверок"]
+ Q5["Где мы сейчас?"] --> A5["PROGRESS.md / список фич / история git"]
+
+ A1 --> Ready["Новая сессия может начать работу<br/>не спрашивая человека"]
+ A2 --> Ready
+ A3 --> Ready
+ A4 --> Ready
+ A5 --> Ready
+```
+
+Если он не отвечает — на карте белые пятна. Где карта пустая, агент гадает: неверная догадка превращается в баг, излишнее гадание сжирает контекст. И каждая новая сессия гадает заново. Цена гадания всегда выше цены того, чтобы один раз нормально нарисовать карту.
+
+## Ключевые понятия
+
+- **Knowledge Visibility Gap**: доля общего знания о проекте, которой НЕТ в репозитории. Чем больше разрыв, тем выше процент провалов агента. Сколько неявного знания о проекте у вас в голове? Посчитайте всё, потом посмотрите, сколько попало в репо — разница и есть ваш visibility gap.
+- **System of Record**: репозиторий кода как авторитетный источник по проектным решениям, архитектурным ограничениям, состоянию исполнения и стандартам верификации. У репо последнее слово, нигде больше не считается. Как карта с пометкой «дорога закрыта» — вы туда не пойдёте. А если эта информация только в голове у Старого Чжана, придётся каждый раз идти к нему.
+- **Cold-Start Test**: те самые пять вопросов выше. Сколько он сможет ответить — настолько и полна ваша карта.
+- **Discovery Cost**: сколько контекстного бюджета агент сжигает, чтобы найти ключевую информацию в репо. Чем глубже спрятана информация, тем выше стоимость поиска и тем меньше бюджета остаётся на саму задачу. Спрятать критичную информацию в README на десятом уровне вложенности — это как закрыть огнетушитель в подвальном сейфе: он есть, но в нужный момент не достанете.
+- **Knowledge Decay Rate**: доля записей знаний, протухающих за единицу времени. Документация, расходящаяся с кодом — главный враг, хуже, чем отсутствие документации.
+- **ACID Analogy**: применение принципов транзакций БД (атомарность, согласованность, изолированность, долговечность) к управлению состоянием агента. Развернём ниже.
+
+## Как нарисовать хорошую карту
+
+**Принцип 1: знания живут рядом с кодом.** Правило аутентификации API-эндпоинтов должно лежать рядом с кодом API, а не быть закопанным в гигантском глобальном документе. Положите в каждый каталог модуля короткий документ с описанием обязанностей модуля, интерфейсов и особых ограничений. Как полочные ярлыки в библиотеке: нужны книги по истории — идёте сразу к полке «История». Не нужно прочёсывать всю библиотеку.
+
+**Принцип 2: используйте стандартизированный входной файл.** `AGENTS.md` (или `CLAUDE.md`) — «лендинг» агента. Он не должен содержать всё, но должен дать агенту быстро ответить на три вопроса: «Что это за проект», «Как его запустить», «Как его проверить». 50–100 строк — достаточно.
+
+**Принцип 3: минимально, но полно.** У каждого знания должен быть понятный сценарий использования. Если удаление правила не влияет на качество решений агента — этого правила быть не должно. Но на каждый вопрос cold-start теста должен быть ответ. Это тонкий баланс — не слишком много, не слишком мало, ровно столько, сколько нужно.
+
+**Принцип 4: обновляйте вместе с кодом.** Привяжите обновления знаний к изменениям кода. Самый простой подход: положите архитектурные доки в соответствующий каталог модуля. Меняя код, вы естественно видите документ. После изменений CI может напомнить проверить, нужно ли обновить доку.
+
+**Конкретная структура репо**:
+
+```
+project/
+├── AGENTS.md # Вход: обзор проекта, команды запуска, жёсткие ограничения
+├── src/
+│ ├── api/
+│ │ ├── ARCHITECTURE.md # Архитектурные решения слоя API
+│ │ └── ...
+│ ├── db/
+│ │ ├── CONSTRAINTS.md # Жёсткие ограничения работы с БД
+│ │ └── ...
+│ └── ...
+├── PROGRESS.md # Текущий прогресс: сделано, в работе, заблокировано
+└── Makefile # Стандартизированные команды: setup, test, lint, check
+```
+
+## Управление состоянием агента по принципам ACID
+
+Аналогия пришла из управления транзакциями в БД — может показаться оверкомплексом, но на деле даёт очень практичный фреймворк:
+
+- **Atomicity (атомарность)**: каждой «логической операции» (например, «добавить новый эндпоинт и обновить тесты») — один git-коммит. Если что-то пошло не так — `git stash` для отката. Всё или ничего, никакого «наполовину».
+- **Consistency (согласованность)**: определите проверяющие предикаты «согласованного состояния» — все тесты проходят, линт без ошибок. Агент запускает верификацию после каждой операции; несогласованные промежуточные состояния не коммитятся. Как банковский перевод — нельзя списать без зачисления.
+- **Isolation (изолированность)**: когда несколько агентов работают параллельно, спроектируйте файлы состояния так, чтобы избежать гонок. Простой подход: у каждого агента свой файл прогресса, или используйте git-ветки для изоляции. Два повара не могут одновременно солить одну кастрюлю — кому отвечать, если пересолили?
+- **Durability (долговечность)**: критическое знание о проекте живёт в файлах под git. Временное состояние может оставаться в памяти сессии, но межсессионное знание должно быть персистировано в файлы. Что в голове — не считается, считается только то, что на бумаге.
+
+## Реальная история трансформации
+
+Команда поддерживала e-commerce платформу с ~30 микросервисами. Архитектурные решения (протоколы межсервисного общения, стратегии согласованности данных, правила версионирования API) были разбросаны по: Confluence (частично устарел), Slack (плохо ищется), голов нескольких сеньоров (не масштабируется) и эпизодических комментариев в коде (не системно).
+
+После внедрения AI-агентов 70% задач требовали человеческого вмешательства. Почти каждый провал был связан с тем, что агент нарушал какое-то «все знают, но никто не записал» неявное ограничение. Это как новенький, которому никто не сказал «о своём заказе на обед нужно писать в группу» — он гадает, его ругают, но после ругани правило ему так и не озвучивают.
+
+Команда провела трансформацию:
+1. Создали `AGENTS.md` в корне репо с обзором проекта, версиями стека и глобальными жёсткими ограничениями
+2. Добавили `ARCHITECTURE.md` в каталог каждого микросервиса с описанием обязанностей, интерфейсов и зависимостей
+3. Создали централизованный `CONSTRAINTS.md` с жёсткими ограничениями в явных формулировках «MUST/MUST NOT»
+4. Добавили `PROGRESS.md` в каталог каждого сервиса для отслеживания текущего статуса работы
+
+После трансформации: тот же агент мог ответить на все ключевые вопросы по проекту на холодном старте, а качество выполнения задач существенно выросло.
+
+## Главное
+
+- Знания, которых нет в репо, для агента не существуют. Положить критические решения в репо — самая базовая инвестиция в harness. Нарисуйте хорошую карту, чтобы не заблудиться.
+- Используйте «cold-start тест» для оценки качества репо: может ли свежая сессия ответить на пять базовых вопросов, имея только содержимое репо?
+- Знания должны быть рядом с кодом, минимальны, но полны, и обновляться вместе с кодом. Дело не в том, чтобы писать больше доков — дело в том, чтобы класть информацию в правильные места.
+- Используйте принципы 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. **Cold-start тест**: откройте абсолютно свежую сессию агента в проекте (без устного контекста, только содержимое репо). Задайте ему пять вопросов: что это за система? как она устроена? как её запускать? как её проверять? каков текущий прогресс? Зафиксируйте, на что он не отвечает, и улучшайте репо, пока не сможет.
+
+2. **Количественная оценка экстернализации знаний**: перечислите все решения и ограничения, важные для разработки в проекте. Отметьте каждое: внутри репо или снаружи. Посчитайте knowledge visibility gap (долю снаружи). Составьте план, как опустить её ниже 10%.
+
+3. **ACID-оценка**: оцените управление состоянием в проекте по ACID-аналогии из лекции. Атомарность — можно ли чисто откатить операции агента? Согласованность — есть ли верификация «согласованного состояния»? Изолированность — мешают ли друг другу параллельные агенты? Долговечность — все ли межсессионные знания персистированы?
diff --git a/docs/ru/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md b/docs/ru/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md
new file mode 100644
index 0000000..cf0ae2d
--- /dev/null
+++ b/docs/ru/lectures/lecture-04-why-one-giant-instruction-file-fails/code/AGENTS-short.md
@@ -0,0 +1,15 @@
+# AGENTS.md
+
+## Start Here
+
+- Read `docs/ARCHITECTURE.md`
+- Read `docs/PRODUCT.md`
+- Use `npm run dev` to start the app
+- Use `npm run check` before marking work complete
+
+## Hard Rules
+
+- Do not change Electron main/preload/renderer boundaries without reading
+ `docs/ARCHITECTURE.md`
+- Do not mark a feature complete without verification
+- Leave a clean state for the next session
diff --git a/docs/ru/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md b/docs/ru/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md
new file mode 100644
index 0000000..6cdefa6
--- /dev/null
+++ b/docs/ru/lectures/lecture-04-why-one-giant-instruction-file-fails/code/anti-patterns.md
@@ -0,0 +1,7 @@
+# Антипаттерны файлов инструкций
+
+- Складывать всё знание о репозитории в один файл
+- Повторять одно и то же правило в нескольких местах
+- Кодировать устаревшие правила, которые никто не ревизует
+- Писать настолько специфичные условные инструкции, что они почти никогда не применяются
+- Встраивать длинные мануалы по инструментам в стартовый контекст
diff --git a/docs/ru/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md b/docs/ru/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md
new file mode 100644
index 0000000..020de0c
--- /dev/null
+++ b/docs/ru/lectures/lecture-04-why-one-giant-instruction-file-fails/code/index.md
@@ -0,0 +1,7 @@
+# Код для Лекции 04
+
+Используйте эту папку для примеров:
+
+- монолитных файлов инструкций
+- коротких входных точек
+- паттернов progressive disclosure
diff --git a/docs/ru/lectures/lecture-04-why-one-giant-instruction-file-fails/code/split-vs-monolithic.ts b/docs/ru/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/ru/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/ru/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md b/docs/ru/lectures/lecture-04-why-one-giant-instruction-file-fails/index.md
new file mode 100644
index 0000000..709b865
--- /dev/null
+++ b/docs/ru/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/en/lectures/lecture-04-why-one-giant-instruction-file-fails/code/)
+> Практический проект: [Project 02. Agent-readable workspace](./../../projects/project-02-agent-readable-workspace/index.md)
+
+# Лекция 04. Разносите инструкции по файлам
+
+Вы серьёзно занялись harness engineering — здорово. Создали `AGENTS.md` и впихнули туда каждое правило, ограничение и вынесенный урок, какой только смогли вспомнить. Через месяц файл раздулся до 300 строк, через два — до 450, через три — до 600. И тут вы замечаете, что качество работы агента на самом деле падает: на простом фиксе бага агент сжигает кучу контекста на ненужные деплой-инструкции; критичное правило безопасности, закопанное на 300-й строке, просто игнорируется; три противоречащих друг другу правила стиля заставляют агента каждый раз случайно выбирать одно из них.
+
+Это ловушка «гигантского файла инструкций». Это как переупаковать чемодан — всё кажется полезным, поэтому вы запихиваете всё, пока молния не лопнет. Чтобы найти смену белья, приходится опустошить весь чемодан. Вы тащили полный чемодан, а реально использовали примерно треть содержимого.
+
+## Порочный круг в основе
+
+Самый частый порочный круг такой: агент ошибается, вы говорите «добавим правило, чтобы это не повторилось», добавляете в AGENTS.md, временно работает, агент делает другую ошибку, добавляете ещё правило, повторяется, файл бесконтрольно раздувается.
+
+Это не ваша вина. Это очень естественная реакция — «добавить правило» каждый раз, как что-то пошло не так, кажется разумным, как закидывать ещё одну вещь в сумку «на всякий случай» каждый раз перед выходом. Но накопительный эффект разрушителен. Посмотрим, что конкретно идёт не так.
+
+**Бюджет контекста съедается живьём.** Окно контекста у агента конечно. Допустим, у вашего агента окно 200K токенов (стандарт Claude). Раздутый файл инструкций может съедать 10–20K токенов. Кажется, ещё много места? Но в сложной задаче нужно прочитать десятки исходных файлов, вывод инструментов тоже занимает контекст, и история диалога накапливается. К тому моменту, когда агент должен понять код, бюджет уже поджимает — как чемодан, настолько забитый «на всякий случай», что для ноутбука не остаётся места.
+
+**Lost in the middle.** Статья «Lost in the Middle» (Liu et al., 2023) ясно показала, что LLM используют информацию в середине длинных текстов значительно хуже, чем в начале или конце. Ваш AGENTS.md на 600 строк, и на 300-й строке написано «все запросы к БД должны использовать параметризованные запросы» — это жёсткое требование безопасности. Но оно зарыто посередине, и агент почти наверняка его проигнорирует. Как тот флакон с солнцезащитным кремом на самом дне переполненного чемодана: знаете, что он там, копаетесь три раза, не находите, в итоге покупаете новый.
+
+**Конфликты приоритетов.** В файле смешиваются необсуждаемые жёсткие ограничения («никогда не используй eval()»), важные дизайн-рекомендации («предпочитайте функциональный стиль») и конкретный исторический урок («на той неделе пофиксили утечку памяти в WebSocket, следите за похожими паттернами»). У этих трёх правил совершенно разная важность, но в файле они выглядят одинаково. У агента нет надёжного сигнала, чтобы их различить — как загранпаспорт и зарядка, перемешанные в чемодане: непонятно, что важнее.
+
+**Гниение из-за поддержки.** Большие файлы по природе плохо поддерживаются. Устаревшие инструкции редко удаляют — потому что последствия удаления неясны («может, какое-то правило от этого зависит?»), а добавлять новые — кажется бесплатным. Итог: файл только растёт, никогда не уменьшается, и отношение сигнал/шум падает. Это ровно как накопление техдолга в софте.
+
+**Накопление противоречий.** Инструкции, добавленные в разное время, начинают противоречить друг другу — одна говорит «используйте strict mode TypeScript», другая «в некоторых легаси-файлах разрешён any». Агент каждый раз выбирает одно случайно. Как мама говорит «тепло одевайся», а папа — «не кутайся», и вы стоите в дверях, не зная, кого слушать.
+
+## Ключевые понятия
+
+- **Instruction Bloat**: когда файл инструкций занимает больше 10–15% окна контекста, он начинает вытеснять бюджет на чтение кода и осмысление задачи. `AGENTS.md` на 600 строк может потреблять 10 000–20 000 токенов — это 8–15% окна на 128K, съеденных ещё до того, как агент начал работать.
+- **Lost in the Middle Effect**: исследование Liu et al. 2023 года доказало, что LLM используют информацию в середине длинных текстов значительно хуже, чем в начале или конце. У критического ограничения, зарытого на 300-й строке файла из 600, очень высокая вероятность быть фактически проигнорированным.
+- **Instruction Signal-to-Noise Ratio (SNR)**: доля инструкций в файле, релевантных текущей задаче. Когда вас заставляют читать 50 строк деплой-инструкций при фиксе бага — это низкий SNR.
+- **Routing File**: короткий входной файл, чья основная функция — указывать агенту на более детальные документы, а не содержать в себе всё. 50–200 строк за глаза.
+- **Progressive Disclosure**: сначала обзорная информация, детальная — по требованию. Хороший дизайн harness как хороший дизайн UI: не вываливайте все опции на пользователя сразу.
+- **Priority Ambiguity**: когда все инструкции выглядят одинаково по формату и месту, агент не может отличить необсуждаемые жёсткие ограничения от рекомендательных мягких советов.
+
+## Архитектура инструкций
+
+```mermaid
+flowchart LR
+ Mono["Один AGENTS.md на 600 строк"] --> MonoLoad["Даже мелкий фикс бага<br/>читает деплой-правила и старые заметки"]
+ MonoLoad --> MonoRisk["Важные правила в середине<br/>легко пропустить"]
+
+ Router["Короткий AGENTS.md"] --> Topics["Подгружать доки API / БД / тестов<br/>только когда нужно для задачи"]
+ Topics --> RoutedResult["Больше контекста остаётся на чтение кода<br/>и верификацию"]
+```
+
+```mermaid
+flowchart TB
+ File["Файл инструкций на 600 строк"] --> Top["Верх<br/>quick start + жёсткие ограничения"]
+ File --> Mid["Середина<br/>критичное правило безопасности на 300-й строке"]
+ File --> Bot["Низ<br/>явный итоговый чеклист"]
+ Top --> Seen["Высокий шанс вспомнить"]
+ Bot --> Seen
+ Mid --> Missed["Высокий шанс размыться или быть пропущенным"]
+```
+
+## Как разбивать
+
+Главный принцип: часто нужное — под рукой, иногда нужное — убрать поглубже, никогда не нужное — выкинуть.
+
+Входной файл `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/` или рядом с соответствующим модулем. Агент читает их только при необходимости. Как органайзеры в чемодане: бельё в одном, косметика в другом, зарядки в третьем. Не нужно вытряхивать весь чемодан, чтобы что-то найти.
+
+Часть информации лучше класть прямо в код — определения типов, комментарии к интерфейсам, пояснения в конфигах. Агент естественно увидит это при чтении кода, дублировать в инструкциях не надо.
+
+У каждой инструкции должен быть источник («почему это правило добавили?»), условие применимости («когда оно нужно?») и условие истечения срока («при каких обстоятельствах его можно удалить?»). Регулярно проводите ревизию, удаляйте устаревшее, дублирующее и противоречивое. Управляйте инструкциями как зависимостями кода — неиспользуемые удаляются, иначе только тормозят систему.
+
+Если инструкция обязана быть во входном файле, ставьте её в начало или в конец, никогда — в середину. Эффект «lost in the middle» говорит, что 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 строк: только обзор, жёсткие ограничения и ссылки.
+- Используйте эффект «lost in the middle»: важное — на верх или низ; неважное — в тематические документы.
+- Управляйте раздуванием инструкций как техдолгом. Регулярные ревизии, у каждой инструкции — источник, условие применимости и условие истечения срока.
+- После разбиения 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. **Рефакторинг под progressive disclosure**: если у вас есть файл инструкций больше 300 строк, разбейте его на: (a) роутинг-файл меньше 100 строк, (b) 3–5 тематических документов. Прогоните один и тот же набор задач (минимум 5) до и после, сравните успешность.
+
+3. **Проверка lost in the middle**: в длинном файле инструкций поставьте критическое ограничение последовательно в начало, в середину и в конец, каждый раз прогоняя один и тот же набор задач (минимум 5 прогонов на позицию). Посмотрите, есть ли разница в соблюдении. Можете удивиться, насколько сильным окажется эффект позиции.
diff --git a/docs/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md b/docs/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md
new file mode 100644
index 0000000..d4cae61
--- /dev/null
+++ b/docs/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/continuity-checklist.md
@@ -0,0 +1,6 @@
+# Чеклист непрерывности
+
+- Может ли свежий агент определить недавнюю работу менее чем за пять минут?
+- Задокументирован ли текущий стабильный путь запуска?
+- Чётко ли обозначена незавершённая работа?
+- Видна ли следующая лучшая задача без чтения старых логов чата?
diff --git a/docs/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md b/docs/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md
new file mode 100644
index 0000000..8189962
--- /dev/null
+++ b/docs/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/index.md
@@ -0,0 +1,7 @@
+# Код к лекции 05
+
+Используйте эту папку для примеров:
+
+- сломанные многосессионные задачи
+- отсутствующие артефакты непрерывности
+- паттерны восстановления непрерывности
diff --git a/docs/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md b/docs/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md
new file mode 100644
index 0000000..3858d50
--- /dev/null
+++ b/docs/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md
@@ -0,0 +1,17 @@
+# Пример Session Handoff
+
+## Сделано
+
+- Добавлена поддержка импорта markdown
+- Добавлен базовый список документов в renderer
+
+## Сломано или не проверено
+
+- Импорт работает для `.md`, но падает на больших `.txt` файлах
+- Приложение запускается, но детальное представление не подключено
+
+## Следующий лучший шаг
+
+- Починить путь импорта `.txt`
+- Проверить импорт сквозно
+- Затем добавить панель деталей документа
diff --git a/docs/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts b/docs/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts
new file mode 100644
index 0000000..69f9c3e
--- /dev/null
+++ b/docs/ru/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/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md b/docs/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
new file mode 100644
index 0000000..57df6df
--- /dev/null
+++ b/docs/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md
@@ -0,0 +1,180 @@
+[中文版本 →](../../../zh/lectures/lecture-05-why-long-running-tasks-lose-continuity/)
+
+> Примеры кода: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/)
+> Практический проект: [Project 03. Multi-session continuity](./../../projects/project-03-multi-session-continuity/index.md)
+
+# Лекция 05. Сохраняйте контекст между сессиями
+
+Вы просите Claude Code реализовать целую фичу. Он работает 30 минут, делает большую часть работы, но контекст подходит к концу. Вы открываете новую сессию, чтобы продолжить, — и обнаруживаете, что он не помнит ни какие решения были приняты, ни почему вариант A был выбран вместо варианта B, ни какие файлы уже изменены, ни в каком состоянии находятся тесты. Он тратит 15 минут на повторное изучение проекта и может действовать вразрез с предыдущим подходом.
+
+Представьте, что вы мастер, который каждое утро после пробуждения всё забывает. Вам пришлось бы заново знакомиться со всей стройкой — какая стена недостроена, почему выбрали красный кирпич вместо синего, докуда дошли с водопроводом. Хуже того, вы могли бы выломать окно, которое уже было установлено вчера, просто потому что не помнили об этом.
+
+Именно в таком положении находятся AI-агенты при многосессионных задачах. Эта лекция объясняет, почему агенты «отключаются» во время длинных задач, и как структурированное сохранение состояния превращает их в мастера, который ведёт надёжный ежедневный журнал — всё ещё страдающего амнезией, но журнал помнит всё.
+
+## Контекстные окна: не бесконечны
+
+Контекстные окна конечны. Это не решается обновлением модели — даже если размер окна вырастет до 1M токенов, сложные задачи всё равно их исчерпают. Потому что агенты не просто генерируют код; они изучают кодовые базы, отслеживают историю собственных решений, обрабатывают вывод инструментов и поддерживают контекст разговора. Вся эта информация растёт быстрее, чем расширяется окно.
+
+Более глубокая проблема: информация, которую производит агент, неравноценна по важности. Промежуточные шаги рассуждений содержат «почему» решений — почему вариант B был выбран вместо A, почему именно эта библиотека, а не другая, почему конкретная оптимизация была пропущена. Финальный вывод содержит только «что» — сам код. Стратегии компакции обычно сохраняют второе, но теряют первое. Следующая сессия видит код, но не знает, почему он написан именно так, и может «оптимизировать» осознанное проектное решение.
+
+Anthropic в своём исследовании long-running агентов обнаружила любопытный эффект: когда агент чувствует, что контекст подходит к концу, он демонстрирует поведение «преждевременного схождения» — спешит закончить текущую работу, пропускает шаги верификации или выбирает простое решение вместо оптимального. Это похоже на то, как на экзамене, поняв, что время заканчивается, вы быстро гадаете в оставшихся вопросах с выбором ответа. Anthropic называет это «контекстной тревожностью».
+
+## Поток непрерывности сессий
+
+Без артефактов непрерывности каждая новая сессия — это катастрофа:
+
+```mermaid
+flowchart LR
+ S1["Сессия 1<br/>фича сделана наполовину"] --> End1["Контекст почти полон<br/>сессия завершается"]
+ End1 --> S2["Сессия 2 стартует с нуля"]
+ S2 --> Guess["Пере-чтение папок, перезапуск тестов,<br/>догадки, почему код написан так"]
+ Guess --> Drift["Работа повторяется<br/>и восстановление идёт медленно"]
+```
+
+С артефактами непрерывности новые сессии могут быстро подхватить работу:
+
+```mermaid
+flowchart LR
+ Work["Работа сессии 1"] --> Progress["PROGRESS.md<br/>сделано / в работе / следующий шаг"]
+ Work --> Decisions["DECISIONS.md<br/>почему выбран этот подход"]
+ Work --> Verify["Заметки по верификации<br/>какие тесты прошли и упали"]
+ Work --> Commit["Git checkpoint<br/>точное состояние репо"]
+
+ Progress --> Rebuild["Восстановление в сессии 2"]
+ Decisions --> Rebuild
+ Verify --> Rebuild
+ Commit --> Rebuild
+
+ Rebuild --> Resume["Новая сессия быстро подхватывает"]
+```
+
+## Ключевые понятия
+
+- **Контекстные окна конечны**: какой бы размер ни заявлялся (128K, 200K, 1M), длинные задачи рано или поздно их исчерпают. После исчерпания требуется либо компакция (с потерей информации), либо сброс (новая сессия). Оба варианта что-то теряют.
+- **Артефакты непрерывности**: сохранённые файлы состояния, которые позволяют новой сессии однозначно продолжить с того места, где остановилась предыдущая. Базовая форма: лог прогресса + запись верификации + следующие действия. Тот самый журнал мастера.
+- **Стоимость восстановления**: время, нужное новой сессии, чтобы выйти в рабочее состояние. Хорошие harness'ы сжимают её с 15 минут до 3 минут.
+- **Дрейф (drift)**: разрыв между пониманием агента и реальным состоянием репозитория. Каждая граница сессии вносит дрейф; без контроля он накапливается.
+- **Контекстная тревожность**: явление, наблюдаемое Anthropic, — агенты демонстрируют преждевременное схождение при приближении к воспринимаемому пределу контекста, преждевременно завершая задачи, чтобы избежать потери информации. Это иррациональная ресурсная тревожность.
+- **Компакция против сброса**: компакция суммирует контекст внутри той же сессии (сохраняет «что», может потерять «почему»); сброс открывает новую сессию, восстанавливаясь из сохранённого состояния (чисто, но зависит от полноты артефактов).
+
+## Что происходит, когда непрерывность ломается
+
+Предыдущая сессия потратила значительный бюджет контекста на анализ трёх подходов и выбор варианта B. Текущая сессия не знает об этом анализе и может пере-решить вопрос на основе неполной информации — потенциально выбрав вариант A. Как мастер с амнезией, который не помнит, почему был выбран красный кирпич, смотрит сегодня на синий, думает, что он красивее, и сносит вчерашнюю стену, чтобы перестроить.
+
+Ещё хуже — дублирование работы. Агент не уверен, была ли уже выполнена определённая работа, и делает её снова. Или, что хуже, делает её наполовину, обнаруживает конфликт с существующей реализацией и вынужден переделывать. На стройке две бригады не могут одновременно строить одну стену, но без записей о прогрессе новая бригада не знает, что кто-то уже над ней работает.
+
+За несколько сессий направление реализации могло незаметно сместиться от исходных требований. Каждая новая сессия немного по-другому понимает цели проекта. Как в игре в «испорченный телефон»: после десяти передач «купи мне кофе» может превратиться в «купи мне кофемашину».
+
+Есть и пробел в верификации. Результаты верификации предыдущей сессии (какие тесты проходят, какие падают, почему падают) не были записаны. Новая сессия вынуждена перезапускать всю верификацию, чтобы понять текущее состояние. Каждая сессия диагностирует с нуля, каждый раз тратя драгоценный контекст.
+
+И OpenAI, и Anthropic подчёркивают в своей документации важность структурированного сохранения состояния. Статья OpenAI о harness engineering трактует репозиторий как «операционный журнал»: результаты каждой операции должны оставлять отслеживаемые следы в репо. Документация Anthropic по long-running агентам специально рекомендует «handoff-файлы» — структурированные документы, содержащие текущее состояние, известные проблемы и следующие действия.
+
+## Журнал для мастера с амнезией
+
+Основной подход: **относитесь к агенту как к гениальному инженеру с амнезией.** Прежде чем «уйти со смены», он должен записать критическую информацию, чтобы следующий «сменный» агент мог быстро подхватить работу.
+
+**Инструмент 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, когда контекст приближается к пределу окна, агент демонстрирует выраженное поведение «преждевременного схождения». Это похоже на то, как на экзамене, увидев, что время почти вышло, вы быстро ставите случайные ответы.
+
+Две стратегии решают эту проблему:
+
+**Компакция**: суммирование раннего разговора внутри той же сессии. Преимущество: сохраняет непрерывность, агент видит «что». Недостаток: «почему» часто теряется в выжимках — почему вариант B был выбран вместо A, почему конкретная оптимизация была пропущена. Что критичнее, компакция не устраняет контекстную тревожность — агент знает, что контекст когда-то был большим, и психологически всё ещё стремится к скорейшему закрытию.
+
+**Сброс контекста**: полная очистка контекста, открытие новой сессии, восстановление из сохранённых артефактов. Преимущество: чистое ментальное состояние — у новой сессии нет тревожности «у меня заканчивается время». Недостаток: зависит от полноты артефактов 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 началась без памяти о контракте интерфейса auth-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 с четырьмя полями: состояние репо (хеш коммита), состояние времени выполнения (доля проходящих тестов), блокеры, следующие действия. Дайте полностью свежей сессии агента восстановить состояние проекта, используя только этот шаблон. Записывайте неоднозначности, возникшие при восстановлении, и итеративно улучшайте шаблон.
+
+3. **Эксперимент со смешанной стратегией**: в задаче на 5 сессий сравните три стратегии: (a) всегда новая сессия + файлы прогресса, (b) делать как можно больше за одну сессию (компакция контекста), (c) смешанная стратегия (короткие задачи внутри сессии, длинные — между сессиями + файлы прогресса). Сравните время восстановления, долю завершённых фич и согласованность решений.
diff --git a/docs/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md b/docs/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md
new file mode 100644
index 0000000..d068f18
--- /dev/null
+++ b/docs/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/code/index.md
@@ -0,0 +1,8 @@
+# Код к лекции 06
+
+Используйте эту папку для примеров:
+
+- результатов работы инициализатора
+- скриптов инициализации
+- файлов прогресса
+- каркаса для первого запуска
diff --git a/docs/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts b/docs/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init-check.ts
new file mode 100644
index 0000000..52dcd98
--- /dev/null
+++ b/docs/ru/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/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh b/docs/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/code/init.sh
new file mode 100644
index 0000000..2c6e1b0
--- /dev/null
+++ b/docs/ru/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/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md b/docs/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md
new file mode 100644
index 0000000..a9fe6e4
--- /dev/null
+++ b/docs/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/code/initializer-output-checklist.md
@@ -0,0 +1,7 @@
+# Чеклист результатов инициализатора
+
+- Есть ли каноническая команда запуска?
+- Есть ли каноническая команда верификации?
+- Есть ли первый артефакт прогресса?
+- Есть ли стабильный первый коммит?
+- Есть ли видимый набор фич для последующих запусков?
diff --git a/docs/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md b/docs/ru/lectures/lecture-06-why-initialization-needs-its-own-phase/index.md
new file mode 100644
index 0000000..4314820
--- /dev/null
+++ b/docs/ru/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/en/lectures/lecture-06-why-initialization-needs-its-own-phase/code/)
+> Практический проект: [Project 03. Multi-session continuity](./../../projects/project-03-multi-session-continuity/index.md)
+
+# Лекция 06. Инициализируйте проект перед каждой сессией агента
+
+Вы открываете новую сессию агента и говорите «добавь поиск». Он сразу бросается писать код — похвальный энтузиазм. Через 20 минут он обнаруживает, что тестовый фреймворк настроен неправильно, тратит ещё 10 минут на починку, потом оказывается, что формат скрипта миграции неверен, ещё возня. Поиск в итоге добавлен, но вся сессия прошла неэффективно — большая часть времени ушла на «разбирательство, как устроен этот проект», а не на саму фичу.
+
+Лучший подход: прежде чем дать агенту начать работу, в отдельной фазе подготовьте базовое окружение, рабочие команды верификации и понимание структуры проекта. Это как строить дом — нельзя одновременно заливать фундамент и поднимать стены. Если так сделать, стены пойдут вверх, пока фундамент не схватился, и всё здание придётся сносить и начинать заново. Залейте фундамент, дайте ему встать, потом стройте стены — чисто и эффективно.
+
+Эта лекция объясняет, почему инициализация должна быть отдельной фазой, а не смешанной с реализацией.
+
+## Фундамент и стены: две принципиально разные задачи
+
+У инициализации и реализации совершенно разные цели оптимизации. Фаза реализации оптимизирует: максимизацию количества и качества проверенных фич. Фаза инициализации оптимизирует: максимизацию надёжности и эффективности всех последующих фаз реализации.
+
+Когда вы смешиваете инициализацию и реализацию, агент сталкивается с многоцелевой оптимизацией — одновременно строит инфраструктуру и пишет код фич. Без явной расстановки приоритетов агент естественным образом тяготеет к написанию кода (потому что это напрямую видимый результат), жертвуя инфраструктурой (потому что её ценность проявится только в последующих сессиях). Это как сказать строительной бригаде одновременно заливать фундамент и поднимать стены — они, скорее всего, бросятся возводить стены, потому что стены видны и их можно показать. Но дом с плохим фундаментом получит системные проблемы потом.
+
+## Жизненный цикл инициализации
+
+```mermaid
+flowchart TB
+ subgraph Wrong["Смешанная сессия (неправильно)"]
+ W1["Сразу начинаем работу над фичей"] --> W2["По ходу обнаруживаем пробелы в окружении и тестах"]
+ W2 --> W3["Накапливаем непроверенный код"]
+ W3 --> W4["Следующая сессия должна заново выяснять состояние проекта"]
+ end
+
+ subgraph Right["Выделенная инициализация (правильно)"]
+ R1["Сессия 1: окружение запускается"] --> R2["Пример теста проходит"]
+ R2 --> R3["Bootstrap-контракт + список задач написаны"]
+ R3 --> R4["Чистый чекпоинт закоммичен"]
+ R4 --> R5["Последующие сессии сразу берут проверенные задачи"]
+ end
+```
+
+## Что происходит, когда вы их смешиваете
+
+Самая прямая проблема: фундамент не схватывается как следует. Агент тратит 80% усилий на код фич и 20% — на кое-как настроенную инфраструктуру. Тестовый фреймворк настроен, но не проверен; правила линтера выставлены, но слишком слабые; файл прогресса не создан. Эти дефекты не очевидны в первой сессии (агент ещё помнит, что делал), но проявляются во второй — новый агент не знает, как запускать, как тестировать и где сейчас находится проект. Хлипкий фундамент — шаткое здание.
+
+Более скрытая стоимость — «непроверенное накопление»: код фич, написанный до настройки тестового фреймворка, — это код без верификации. Когда вы наконец возвращаетесь добавить тесты к этому коду, вы можете обнаружить, что архитектура была неверной с самого начала — знай вы это, реализовали бы иначе. Это как класть плитку на сырой бетон: когда обнаруживаете, что пол неровный, всю плитку приходится отдирать и переделывать.
+
+Бюджет сессии тоже расходуется впустую. Работа по инициализации (настройка окружения, тестов, понимание структуры проекта) потребляет значительный бюджет, оставляя меньше на реальную реализацию фич. Результат: первая сессия выполняет только половину фич, а вторая вынуждена снова разбираться с проектом. Бюджет ушёл на фундамент, но и фундамент тоже не крепкий — ни одна цель не достигнута.
+
+Самая легко упускаемая проблема — «мины» неявных предположений. Решения, принимаемые агентом во время инициализации (какой тестовый фреймворк, как организовать каталоги, как управлять зависимостями), — если их явно не записать, последующие сессии не смогут их понять. Хуже того, последующие сессии могут принять противоречащие решения. Первая бригада сделала бетонный фундамент, вторая бригада об этом не знала и забила в него деревянные сваи — фундамент трескается.
+
+В исследовании long-running разработки приложений Anthropic явно рекомендует отделять инициализацию от реализации. Их экспериментальные данные: проекты с выделенной фазой инициализации показывали на 31% более высокую долю завершённых фич в многосессионных сценариях по сравнению со смешанным подходом. Ключевая мысль — время, вложенное в фазу инициализации, полностью окупается в следующих 3–4 сессиях. Чем крепче фундамент, тем быстрее идут стены.
+
+Руководство OpenAI Codex по harness engineering тоже подчёркивает принцип «репозиторий как операционный журнал»: с первого запуска нужно установить ясную операционную структуру, иначе каждая новая сессия будет вынуждена заново выводить соглашения проекта.
+
+## Ключевые понятия
+
+- **Фаза инициализации**: первая фаза в жизненном цикле агента — никакой реализации фич, только подготовка предпосылок для всех последующих фаз реализации. На выходе не код, а инфраструктура.
+- **Bootstrap Contract**: условия, при которых проект может быть однозначно использован свежей сессией агента — может запуститься, может тестироваться, может видеть прогресс, может подхватывать следующие шаги. Четыре условия, все обязательны.
+- **Холодный старт против тёплого старта**: холодный старт — из пустого каталога, где агент должен угадывать структуру проекта; тёплый старт — из шаблона или существующего проекта, где инфраструктура уже на месте. Тёплый старт значительно превосходит холодный — как начинать стройку с водой и электричеством против начала с голой пустоши.
+- **Готовность к handoff**: проект в любой момент находится в состоянии, когда свежий агент может его подхватить. Никаких устных пояснений — только содержимое репо.
+- **Время до первой верификации**: время от старта проекта до момента, когда первая фича проходит верификацию. Это ключевая метрика эффективности инициализации.
+- **Полезность для последующих этапов**: лучшая мера качества инициализации — доля последующих сессий, которые успешно выполняют задачи, не опираясь на неявные знания.
+
+## Как делать инициализацию правильно
+
+**Считайте инициализацию выделенной фазой.** Первая сессия делает только инициализацию — никакого бизнес-кода. Инициализация производит:
+
+**1. Запускаемое окружение.** Проект стартует, зависимости установлены, проблем с окружением нет. Фундамент залит, без трещин.
+
+**2. Проверяемый тестовый фреймворк.** Хотя бы один пример теста проходит. Это доказывает, что сам тестовый фреймворк настроен правильно — как поставить столб на фундамент, чтобы убедиться, что он держит вес.
+
+**3. Документ bootstrap-контракта.** Чёткий документ, который сообщает последующим сессиям:
+```markdown
+# Initialization Contract
+
+## 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 и т. д.), чтобы предустановить стандартную структуру каталогов, конфигурацию зависимостей и тестовый фреймворк. Запекайте общие шаги инициализации в шаблон, оставляя только специфичную для проекта работу. Это как начинать стройку с водой и электричеством — в десять тысяч раз лучше, чем с голой пустоши.
+
+**Критерии завершения инициализации**: не «сколько кода написано», а выполнены ли четыре условия bootstrap-контракта — может запуститься, может тестироваться, может видеть прогресс, может подхватывать следующие шаги. Используйте этот чеклист для валидации:
+
+```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), написала и проверила один пример теста, создала документ bootstrap-контракта и файл декомпозиции задач, закоммитила начальный чекпоинт. Время восстановления в сессии 2 — менее 3 минут, и она сразу начала работать по списку задач — бригада приходит, бросает взгляд на чертёж и точно знает, где продолжать.
+
+Сравнение полного цикла проекта: общее время восстановления (по всем сессиям) при смешанном подходе было примерно на 60% больше, чем при выделенной инициализации. Дополнительные 20 минут на инициализацию многократно окупились в последующих сессиях. Как крепкий фундамент ускоряет возведение стен — медленнее значит быстрее.
+
+## Главные выводы
+
+- Цели оптимизации у инициализации и реализации разные — смешивание тянет вниз обе. Сначала фундамент, потом стены.
+- Результат инициализации — не код, а инфраструктура: запускаемое окружение, проверяемые тесты, bootstrap-контракт, декомпозиция задач.
+- Валидируйте инициализацию по четырём условиям bootstrap-контракта: может запуститься, может тестироваться, может видеть прогресс, может подхватывать следующие шаги.
+- Тёплый старт превосходит холодный. Используйте шаблоны проектов для предустановки стандартной инфраструктуры.
+- Время, вложенное в инициализацию, полностью окупается в следующих 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. **Проектирование bootstrap-контракта**: напишите полный bootstrap-контракт для проекта, который вы разрабатываете. Затем откройте полностью свежую сессию агента, покажите ей только содержимое репо (без устного контекста) и попросите запустить проект, прогнать тесты и понять текущий прогресс. Записывайте каждую возникшую проблему — каждая соответствует пробелу в вашем bootstrap-контракте.
+
+2. **Сравнительный эксперимент**: возьмите умеренно сложный новый проект. Подход A: пусть агент инициализирует и сразу делает первую реализацию. Подход B: одна сессия на выделенную инициализацию, реализация — со второй сессии. После 4 сессий сравните: время до первой верификации, стоимость восстановления, долю завершённых фич.
+
+3. **Чеклист приёмки инициализации**: разработайте чеклист приёмки инициализации для своего проекта. Дайте свежей сессии агента выполнить каждый пункт и фиксируйте, какие проходят, а какие падают. Падающие пункты — те места, где ваш harness нуждается в усилении.
diff --git a/docs/ru/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md b/docs/ru/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md
new file mode 100644
index 0000000..7f25870
--- /dev/null
+++ b/docs/ru/lectures/lecture-07-why-agents-overreach-and-under-finish/code/index.md
@@ -0,0 +1,8 @@
+# Код к лекции 07
+
+Используйте эту папку для примеров:
+
+- провалы при «one-shot»
+- слишком крупные промпты задач
+- инкрементальное оформление задач
+- структурированные поверхности фич
diff --git a/docs/ru/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md b/docs/ru/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md
new file mode 100644
index 0000000..85ee8e8
--- /dev/null
+++ b/docs/ru/lectures/lecture-07-why-agents-overreach-and-under-finish/code/next-task-template.md
@@ -0,0 +1,6 @@
+# Шаблон следующей задачи
+
+- Текущая фича с наивысшим приоритетом:
+- Почему именно эта фича следующая:
+- Что считается прохождением:
+- Что нельзя менять на этом шаге:
diff --git a/docs/ru/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md b/docs/ru/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md
new file mode 100644
index 0000000..9ae66cc
--- /dev/null
+++ b/docs/ru/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-surface-example.md
@@ -0,0 +1,17 @@
+# Пример поверхности скоупа
+
+Задача:
+
+- Добавить индексирование в Electron knowledge-приложение
+
+Плохая форма скоупа:
+
+- «Реализовать индексирование»
+
+Лучшая форма скоупа:
+
+- Парсить импортируемые документы
+- Делить документы на чанки
+- Сохранять метаданные чанков
+- Показывать статус индексирования в UI
+- Добавить действие переиндексации
diff --git a/docs/ru/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts b/docs/ru/lectures/lecture-07-why-agents-overreach-and-under-finish/code/scope-tracker.ts
new file mode 100644
index 0000000..c587a1d
--- /dev/null
+++ b/docs/ru/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/ru/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md b/docs/ru/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
new file mode 100644
index 0000000..5c74c66
--- /dev/null
+++ b/docs/ru/lectures/lecture-07-why-agents-overreach-and-under-finish/index.md
@@ -0,0 +1,134 @@
+[中文版本 →](../../../zh/lectures/lecture-07-why-agents-overreach-and-under-finish/)
+
+> Примеры кода: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-07-why-agents-overreach-and-under-finish/code/)
+> Практический проект: [Project 04. Runtime feedback and scope control](./../../projects/project-04-incremental-indexing/index.md)
+
+# Лекция 07. Очерчивайте чёткие границы задач для агентов
+
+Вы говорите Claude Code: «добавь в проект аутентификацию пользователей», и он начинает менять схему БД, писать маршруты, переделывать фронтенд-компоненты и заодно — рефакторить middleware обработки ошибок. Через два часа вы проверяете: 12 файлов изменено, 800 строк нового кода, и ни одна фича не работает сквозно.
+
+Откусил больше, чем сможешь прожевать — эта поговорка отлично подходит к AI-агентам. У агентов врождённый импульс «сделать чуть больше» — они видят что-то связанное и заодно это правят, как тот, кто пошёл в магазин за бутылкой соевого соуса и вышел с полной тележкой. Проблема в том, что человек, который купил лишнего, всего лишь потратил деньги; агент, делающий слишком много дел одновременно, не доводит до конца ни одного.
+
+Инженерный блог Anthropic «Effective harnesses for long-running agents» прямо говорит: когда промпты слишком широкие, агенты склонны «начинать сразу несколько дел», вместо того чтобы «сначала закончить одно». Инженерные практики OpenAI Codex показывают то же самое — у задач без явного контроля скоупа доля завершения обваливается. Это проблема не модели — это проблема harness'а. Вы не очертили границу.
+
+## Внимание — конечный ресурс
+
+Это не метафора, а математика. Допустим, ёмкость контекста агента — C, и он одновременно активирует k задач. Каждая задача получает в среднем C/k ресурсов рассуждения. Когда C/k опускается ниже минимального порога, нужного для завершения одной задачи, ни одна не доходит до конца. Желудок имеет свой объём — впихни десять пельменей разом, и ни один не переваришь, получишь десять расстройств желудка.
+
+Реальное поведение Claude Code красноречиво. Попросите «добавить регистрацию пользователей», и он может:
+
+1. Создать модель User
+2. Написать маршрут регистрации
+3. Заметить, что нужна верификация по email, и добавить почтовый сервис
+4. Увидеть, что пароли надо хешировать, и подключить bcrypt
+5. Заметить, что обработка ошибок непоследовательна, и отрефакторить глобальный error-middleware
+6. Увидеть, что структура тестовых файлов неаккуратная, и переорганизовать каталог
+
+Шесть шагов спустя — каждый сделан наполовину. Никакой сквозной верификации, сложная связанность между полу-готовыми кусками кода, и следующая сессия, которая попробует это разобрать, окончательно потеряется. Как тот, кто готовит шесть блюд одновременно: каждое в сковородке, но ни одно не выложено на тарелку. Все подгорают.
+
+Экспериментальные данные Anthropic прямо это подтверждают: агенты, использующие стратегию «маленький следующий шаг» (эквивалентно WIP=1), показывают на 37% более высокую долю завершённых задач, чем агенты с широкими промптами. Что интереснее, число строк кода, генерируемых агентами, слабо отрицательно коррелирует с реальным завершением фич — больше написанного кода, меньше доведённых до конца фич. Откусил больше, чем прожуёшь — подтверждено данными.
+
+## Рабочий процесс WIP=1
+
+```mermaid
+flowchart LR
+ Queue["Очередь фич"] --> Pick["Берём ровно одну задачу"]
+ Pick --> Active["Только один активный элемент"]
+ Active --> Verify["Запускаем сквозную верификацию"]
+ Verify -->|pass| Commit["Коммитим и разблокируем следующую"]
+ Verify -->|fail| Active
+ Commit --> Queue
+```
+
+```mermaid
+flowchart TB
+ Budget["Доступный бюджет рассуждения = C"] --> One["WIP = 1<br/>C / 1 на задачу"]
+ Budget --> Many["WIP = 5<br/>C / 5 на задачу"]
+
+ One --> Finish["Одна фича доходит до прохождения"]
+ Many --> Partial["Пять частичных реализаций"]
+ Partial --> VCR["Низкая доля проверенного завершения<br/>много переделок в следующей сессии"]
+```
+
+## Ключевые понятия
+
+- **Overreach (переусердствование)**: агент активирует за одну сессию больше задач, чем оптимально. Это поддаётся измерению — 5 фич с 0 проходящими сквозными — это overreach.
+- **Under-finish (недодел)**: доля задач, прошедших сквозную верификацию, среди всех активированных задач, опускается ниже порога. Код написан, но тесты не проходят — это under-finish.
+- **WIP Limit (лимит работы в процессе)**: из методологии Канбан. Главная идея: ограничить количество задач, находящихся в работе одновременно. Для агентов WIP=1 — самое безопасное значение по умолчанию: закончи одно, потом начинай следующее. Как на шведском столе — не накладывай горой, доешь одну тарелку, потом иди за следующей.
+- **Доказательство завершения**: проверяемое условие, которое задача обязана удовлетворить, чтобы перейти из «в работе» в «готово». Без него агенты подменяют «код выглядит нормально» на «поведение проходит тесты».
+- **Поверхность скоупа (Scope Surface)**: DAG-структура, где каждый узел — единица работы, а рёбра — зависимости. Состояний всего четыре: not_started, active, blocked, passing.
+- **Давление на завершение**: ограничивающая сила, которую harness прикладывает через WIP-лимиты и требования к доказательствам завершения, заставляя агента закончить текущую задачу перед началом новой.
+
+## Overreach и under-finish — симбиоз
+
+Эти две проблемы не независимы — они усиливают друг друга. Overreach размывает внимание, размытое внимание ведёт к under-finish, а оставшийся полу-готовый код увеличивает сложность системы, что дальше подталкивает к overreach в следующей задаче. Порочный круг.
+
+В терминах Канбан: закон Литтла говорит L = lambda * W. Если объём работы в процессе L слишком велик (одновременно делается слишком много), время выполнения W каждой задачи неизбежно растёт. Для агентов это значит, что путь от старта до проверенного завершения каждой фичи становится длиннее, а вероятность отказа — выше.
+
+Это и в человеческом мире давняя проблема — Стив Макконнелл в *Rapid Development* документировал, что расширение скоупа — главная причина провала проектов. Но у людей хотя бы есть интуиция «я уже сделал достаточно». У агентов её нет. Сгенерировать следующую идею модели стоит почти ничего по дополнительным токенам — написать «давайте заодно починим и это» едва заметно, — но каждое дополнительное изменение размывает внимание агента. Как на шведском столе: каждая лишняя тарелка имеет почти нулевую маржинальную стоимость, но желудок ограничен.
+
+## Как делать правильно
+
+### 1. Принудительный WIP=1
+
+Самый прямой и эффективный способ. В вашем harness'е явно скажите агенту: **в любой момент в статусе «active» может быть только одна задача.** В 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 фичами, сравниваются две стратегии:
+
+**Режим шведского стола (без ограничений)**: агент в сессии 1 одновременно активирует 5 фич. Производит ~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» — считается.
+- **Поверхность скоупа должна быть вынесена в файл** — не просто упомянута в разговоре, а записана в репо в машиночитаемом формате.
+- **Overreach и under-finish — симбиоз** — решая одно, решаешь и второе.
+- **«Меньше, но до конца» всегда побеждает «больше, но наполовину»** — строки кода агента и доля завершения фич отрицательно коррелируют. Качество всегда побеждает количество.
+
+## Дополнительное чтение
+
+- [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/) — полное изложение OpenAI о harness engineering
+- [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 атомарных единиц работы. Для каждой укажите: (a) описание одного поведения, (b) исполняемую команду верификации, (c) зависимости. Проверьте, удовлетворяет ли декомпозиция ограничению WIP=1.
+
+2. **Сравнительный эксперимент**: запустите один и тот же проект дважды — раз без ограничений, раз с принудительным WIP=1. Сравните: долю проверенного завершения, общее число строк, долю эффективного кода.
+
+3. **Аудит доказательств завершения**: пересмотрите вывод недавнего прогона агента, классифицируя каждое изменение кода как «завершённое поведение», «незавершённое поведение» или «каркас». Для каждого незавершённого поведения добавьте недостающую команду верификации.
diff --git a/docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature-list-validator.ts b/docs/ru/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/ru/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/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json b/docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/feature_list.json
new file mode 100644
index 0000000..8b973e3
--- /dev/null
+++ b/docs/ru/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/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md b/docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md
new file mode 100644
index 0000000..89473c4
--- /dev/null
+++ b/docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/index.md
@@ -0,0 +1,8 @@
+# Код к лекции 08
+
+Используйте эту папку для примеров:
+
+- гейтинг по состоянию passing
+- сквозная верификация
+- слабые против строгих критериев завершения
+- примеры evaluator-loop
diff --git a/docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md b/docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md
new file mode 100644
index 0000000..8da05f0
--- /dev/null
+++ b/docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/pass-gate-policy.md
@@ -0,0 +1,8 @@
+# Политика гейта прохождения
+
+Фича может перейти из `passes: false` в `passes: true`, только когда:
+
+- ожидаемый сценарий был реально пройден
+- доказательство успеха зафиксировано
+- на проверенном пути нет блокирующей ошибки
+- реализация не оставляет приложение в сломанном или неоднозначном состоянии
diff --git a/docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md b/docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
new file mode 100644
index 0000000..9270d9b
--- /dev/null
+++ b/docs/ru/lectures/lecture-08-why-feature-lists-are-harness-primitives/index.md
@@ -0,0 +1,137 @@
+[中文版本 →](../../../zh/lectures/lecture-08-why-feature-lists-are-harness-primitives/)
+
+> Примеры кода: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-08-why-feature-lists-are-harness-primitives/code/)
+> Практический проект: [Project 04. Runtime feedback and scope control](./../../projects/project-04-incremental-indexing/index.md)
+
+# Лекция 08. Используйте списки фич, чтобы ограничивать поведение агента
+
+Вы просите агента построить интернет-магазин. Когда он закончил, он говорит «готово». Вы смотрите код — аутентификация работает, но кнопка оформления заказа в корзине ничего не делает, а оплата вообще не подключена. Проблема: вы никогда не сказали, что значит «готово», поэтому он использовал свой собственный стандарт — «я написал много кода, и он выглядит достаточно полным».
+
+Список фич, в глазах многих, — просто памятка: записал, чтобы не забыть, и отложил. Но в мире harness'а список фич — не памятка для людей, а позвоночник всего harness'а. Планировщик опирается на него, чтобы выбирать задачи; верификатор — чтобы судить о завершении; репортёр handoff — чтобы генерировать саммари. Сломайте позвоночник — и тело парализовано.
+
+И 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["Одна строка фичи"] --> Behavior["Поведение<br/>например: POST /cart/items возвращает 201"]
+ Feature --> Check["Команда верификации<br/>точная проверка для запуска"]
+ Feature --> State["Состояние<br/>not_started / active / blocked / passing"]
+
+ Behavior --> Complete["Только при всех трёх полях<br/>строка фичи пригодна"]
+ Check --> Complete
+ State --> Complete
+```
+
+```mermaid
+flowchart LR
+ List["feature_list.json / features.md"] --> Scheduler["Берём следующий not_started"]
+ Scheduler --> Agent["Агент работает только над ним"]
+ Agent --> Verifier["Запускаем команду верификации этой записи"]
+ Verifier -->|pass| Passing["Помечаем passing<br/>и записываем доказательство"]
+ Verifier -->|fail| Active["Оставляем active"]
+ Verifier -->|проблема зависимости| Blocked["Помечаем blocked"]
+ Passing --> Handoff["Обновляем handoff-заметку<br/>и текущий прогресс"]
+ Active --> Agent
+```
+
+## Ключевые понятия
+
+- **Списки фич — примитивы harness'а**: не «опциональный инструмент планирования», а фундаментальная структура данных, от которой зависят все остальные компоненты harness'а. Как структура таблицы в БД — нельзя сказать «давайте обойдёмся без первичных ключей».
+- **Тройственная структура**: каждая запись фичи — это тройка `(описание поведения, команда верификации, текущее состояние)`. Без любого элемента запись неполная.
+- **Модель конечного автомата**: у каждой записи фичи четыре состояния — `not_started`, `active`, `blocked`, `passing`. Переходами управляет harness, а не агент по своему усмотрению.
+- **Гейт по состоянию passing**: единственный способ перевести фичу из `active` в `passing` — успешный запуск команды верификации. Это необратимо: став `passing`, нельзя вернуться. Сдал экзамен — значит сдал, оценку задним числом не поменяешь.
+- **Единственный источник истины**: вся информация «что нужно сделать» должна происходить из одного списка фич. Никаких противоречий между списком фич и историей разговора.
+- **Обратное давление**: число фич, ещё не получивших passing, — это давление, которое harness прикладывает к агенту. Нулевое давление = проект завершён.
+
+## Почему списки фич должны быть «примитивами»
+
+Документы — для чтения людьми; примитивы — для исполнения системой. Документы можно проигнорировать, примитивы — нельзя обойти.
+
+Это как ограничения через триггеры в БД против проверок на уровне приложения: первые обеспечиваются движком БД, никакой SQL их не пропустит; вторые зависят от корректности кода и могут быть случайно обойдены. Списки фич как примитивы harness'а конкретно обслуживают четыре компонента harness'а:
+
+1. **Планировщик**: читает состояния, выбирает следующую `not_started` фичу. Как система производственного планирования на заводе.
+2. **Верификатор**: исполняет команды верификации, решает, разрешить ли смену состояния. Как ОТК.
+3. **Репортёр handoff**: автоматически генерирует саммари сессии из списка фич. Как автоматический отчёт о смене.
+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 сессий заметки превращаются в «сделал auth и список товаров, корзина почти готова но баги, оплата не начата». Новая сессия тратит 20 минут на восстановление состояния и в итоге пере-реализует готовые фичи. Это как ваш список покупок гласит «молоко, хлеб и эта штука» — в магазине вы всё равно не знаете, что брать.
+
+**Режим позвоночника**: у каждой фичи чёткое состояние и команда верификации. Новая сессия читает список фич и за 3 минуты знает: F01–F05 — `passing`, F06 — `active`, F07–F10 — `not_started`. Сразу подхватывает с F06, никаких переделок.
+
+Количественно: проекты со структурированными списками фич показывают на 45% более высокую долю завершения по сравнению со свободной формой учёта, при нулевом дублировании реализаций.
+
+## Главные выводы
+
+- **Списки фич — позвоночник harness'а**, а не памятки для людей. Планировщик, верификатор и репортёр handoff все зависят от них.
+- **У каждой записи фичи должна быть тройка**: описание поведения + команда верификации + текущее состояние. Без одного элемента она неполна — как трёхногий табурет с потерянной ногой.
+- **Переходами состояний управляет 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/ru/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md b/docs/ru/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md
new file mode 100644
index 0000000..8c15a0c
--- /dev/null
+++ b/docs/ru/lectures/lecture-09-why-agents-declare-victory-too-early/code/clean-state-checklist.md
@@ -0,0 +1,6 @@
+# Чек-лист чистого состояния
+
+- Приложение запускается без ручного ремонта
+- Текущий прогресс зафиксирован
+- Не остаётся незадокументированных полудоделанных шагов импорта или индексации
+- Следующий агент может сразу выполнить стандартный путь запуска и верификации
diff --git a/docs/ru/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md b/docs/ru/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md
new file mode 100644
index 0000000..016aae6
--- /dev/null
+++ b/docs/ru/lectures/lecture-09-why-agents-declare-victory-too-early/code/index.md
@@ -0,0 +1,8 @@
+# Код к лекции 09
+
+Используйте эту папку для примеров:
+
+- логи как обратная связь
+- видимость состояния во время выполнения
+- проверки чистого состояния
+- примеры восстановления
diff --git a/docs/ru/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts b/docs/ru/lectures/lecture-09-why-agents-declare-victory-too-early/code/victory-detector.ts
new file mode 100644
index 0000000..fad1a3b
--- /dev/null
+++ b/docs/ru/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/ru/lectures/lecture-09-why-agents-declare-victory-too-early/index.md b/docs/ru/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
new file mode 100644
index 0000000..20e7c1c
--- /dev/null
+++ b/docs/ru/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
@@ -0,0 +1,2 @@
+ >> .text
+ bash -c .textfile /Users/sanbu/Code/github/learn-harness-engineering/docs/en/lectures/lecture-09-why-agents-declare-victory-too-early/index.md
\ No newline at end of file
diff --git a/docs/ru/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md b/docs/ru/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md
new file mode 100644
index 0000000..b52a04b
--- /dev/null
+++ b/docs/ru/lectures/lecture-10-why-end-to-end-testing-changes-results/code/architecture-rules.md
@@ -0,0 +1,6 @@
+# Архитектурные правила Electron
+
+- Код рендерера не должен напрямую обращаться к файловой системе.
+- Preload — единственный мост между рендерером и main-процессом Electron.
+- Логика поиска и индексации живёт в сервисных модулях, а не в UI-компонентах.
+- Логирование должно быть структурированным и исходить из границ сервисов.
diff --git a/docs/ru/lectures/lecture-10-why-end-to-end-testing-changes-results/code/e2e-runner.ts b/docs/ru/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/ru/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/ru/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md b/docs/ru/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md
new file mode 100644
index 0000000..f706111
--- /dev/null
+++ b/docs/ru/lectures/lecture-10-why-end-to-end-testing-changes-results/code/index.md
@@ -0,0 +1,8 @@
+# Код к лекции 10
+
+Используйте эту папку для примеров:
+
+- архитектурные ограничения
+- структурные тесты
+- инварианты вкуса
+- сообщения линтера, ориентированные на исправление
diff --git a/docs/ru/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md b/docs/ru/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md
new file mode 100644
index 0000000..7fc4a7c
--- /dev/null
+++ b/docs/ru/lectures/lecture-10-why-end-to-end-testing-changes-results/code/review-feedback-to-rule.md
@@ -0,0 +1,10 @@
+# Пример: превращение фидбэка с ревью в правило
+
+Повторяющийся комментарий с ревью:
+
+> Не вызывайте утилиты файловой системы из рендерера. Используйте preload-мост.
+
+Поднято до правила harness:
+
+- добавить правило линтера или импорта, запрещающее использование `fs` в коде рендерера
+- добавить текст с инструкцией, объясняющей границу preload
diff --git a/docs/ru/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md b/docs/ru/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
new file mode 100644
index 0000000..f62afdd
--- /dev/null
+++ b/docs/ru/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
@@ -0,0 +1,2 @@
+ >> .text
+ bash -c .textfile /Users/sanbu/Code/github/learn-harness-engineering/docs/en/lectures/lecture-10-why-end-to-end-testing-changes-results/index.md
\ No newline at end of file
diff --git a/docs/ru/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md b/docs/ru/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md
new file mode 100644
index 0000000..8574989
--- /dev/null
+++ b/docs/ru/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md
@@ -0,0 +1,8 @@
+# Пример рубрики оценщика
+
+Используйте оценку 1–5 по каждому измерению:
+
+- Заземлённость: явно ли ответы привязаны к импортированным источникам?
+- Качество цитирования: видны ли ссылки на источники и насколько они конкретны?
+- Функциональность: может ли пользователь пройти флоу «вопрос-ответ»?
+- Целостность продукта: ощущается ли воркфлоу как единое целое?
diff --git a/docs/ru/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md b/docs/ru/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md
new file mode 100644
index 0000000..6aa8a40
--- /dev/null
+++ b/docs/ru/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/index.md
@@ -0,0 +1,8 @@
+# Код к лекции 11
+
+Используйте эту папку для примеров:
+
+- выходы планировщика
+- рубрики оценщика
+- циклы generator/evaluator
+- сравнения одиночного агента и многоролевой схемы
diff --git a/docs/ru/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts b/docs/ru/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts
new file mode 100644
index 0000000..213dc19
--- /dev/null
+++ b/docs/ru/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/ru/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md b/docs/ru/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md
new file mode 100644
index 0000000..faa0042
--- /dev/null
+++ b/docs/ru/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md
@@ -0,0 +1,12 @@
+# Пример Sprint Contract
+
+Цель спринта:
+
+- Добавить видимые цитаты в результаты заземлённого Q&A
+
+Done означает:
+
+- Пользователь задаёт вопрос
+- Приложение возвращает ответ
+- Показана хотя бы одна цитата
+- Клик по цитате открывает место источника во вьюхе документа
diff --git a/docs/ru/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md b/docs/ru/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
new file mode 100644
index 0000000..139d8c7
--- /dev/null
+++ b/docs/ru/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
@@ -0,0 +1,155 @@
+[中文版本 →](../../../zh/lectures/lecture-11-why-observability-belongs-inside-the-harness/)
+
+> Примеры кода: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/)
+> Практический проект: [Проект 06. Полноценный harness (Capstone)](./../../projects/project-06-runtime-observability-and-debugging/index.md)
+
+# Лекция 11. Сделайте рантайм агента наблюдаемым
+
+## Какую проблему решает эта лекция?
+
+Вы просите агента реализовать фичу. Он работает 20 минут, меняет кучу файлов и сообщает: «готово, но два теста падают». Спрашиваете почему — «не уверен, может быть, проблема с таймингом». Спрашиваете, какие критические пути он изменил — «дайте посмотреть в код…»
+
+Дело не в том, что агенту не хватает способностей. Дело в том, что ваш harness не обеспечивает достаточной наблюдаемости. **Без наблюдаемости агенты принимают решения в условиях неопределённости, оценки превращаются в субъективные суждения, а ретраи — в слепое блуждание.** И OpenAI, и Anthropic определяют надёжность как проблему доказательств: harness должен раскрывать поведение во время выполнения и сигналы оценки в форме, которая может направлять следующее решение.
+
+## Ключевые понятия
+
+- **Рантайм-наблюдаемость**: сигналы системного уровня — логи, трейсы, события процессов, проверки здоровья. Отвечает на вопрос «что сделала система».
+- **Процессная наблюдаемость**: видимость артефактов решений harness — планов, рубрик оценки, критериев приёмки. Отвечает на вопрос «почему это изменение должно быть принято».
+- **Трейс задачи**: полная запись пути решения от начала задачи до завершения, аналогично трассировке запросов в распределённых системах. Каждый шаг агента, с контекстом, фиксируется.
+- **Sprint contract**: краткосрочное соглашение, согласованное до начала кодинга — определяет скоуп задачи, стандарты верификации и исключения. Основной инструмент процессной наблюдаемости.
+- **Рубрика оценщика**: превращает оценку качества из субъективного суждения в основанную на доказательствах структурированную систему баллов. Заставляет разных оценщиков выдавать схожие результаты для одного и того же выхода.
+- **Многослойная наблюдаемость**: наблюдаемость на системном и процессном уровнях, спроектированные одновременно и взаимно усиливающие друг друга. Рантайм-сигналы объясняют поведение; процессные артефакты объясняют намерение.
+
+## Многослойная наблюдаемость
+
+```mermaid
+flowchart LR
+ Contract["Сначала фиксируем задачу<br/>что менять / что не менять / критерии прохождения"] --> Generator["Generator"]
+ Generator --> Signals["Собираем логи приложения, трейсы<br/>и health-чеки во время работы"]
+ Contract --> Review["Проверяем результат пункт за пунктом<br/>поведение / тесты / границы"]
+ Signals --> Review
+ Review --> Verdict["Указываем на провалившуюся проверку<br/>и где её чинить"]
+ Verdict --> Generator
+```
+
+## Почему так происходит
+
+### Реальная цена отсутствия наблюдаемости
+
+Когда у harness нет наблюдаемости, систематически появляются четыре типа проблем:
+
+**Невозможно отличить «корректно» от «выглядит корректно»**: функция выглядит идеально на код-ревью — синтаксис правильный, логика здравая. Но во время выполнения ошибка обработки граничного случая выдаёт неверные результаты на конкретных входах. Только рантайм-трейсы могут показать, что фактический путь выполнения отклонился от ожиданий.
+
+**Оценка превращается в мистицизм**: без рубрик оценки и критериев приёмки оценщики (человек или агент) опираются на неявные предположения. Один и тот же выход может получить дико разные оценки от разных проверяющих. Оценка качества становится невоспроизводимой.
+
+**Ретраи превращаются в слепые догадки**: когда агент не знает, почему что-то не сработало, направление ретрая случайно. Он может многократно пытаться в неверном направлении — чинить несвязанные пути кода, игнорируя реальную корневую причину сбоя. Каждый слепой ретрай стоит токенов и времени.
+
+**Информационный обрыв при передаче сессии**: когда незавершённая работа передаётся следующей сессии, отсутствие наблюдаемости означает, что новая сессия должна диагностировать состояние системы с нуля. Наблюдения Anthropic за долгоработающими агентами показывают, что эта избыточная диагностика может съедать 30–50% общего времени сессии.
+
+### Реальный сценарий с Claude Code
+
+Представьте harness с трёхролевым воркфлоу «планировщик-генератор-оценщик», выполняющий задачу «добавить тёмную тему в приложение».
+
+**Без наблюдаемости**: планировщик выдаёт расплывчатое описание. Генератор реализует тёмную тему на основе этой расплывчатости, но это не совпадает с неявными ожиданиями планировщика. Оценщик отвергает результат на основе своих собственных неявных стандартов, но не может точно сформулировать, что именно не так. Генератор слепо ретраит на основе размытых причин отказа. Цикл повторяется 3–4 раза, занимает около 45 минут и даёт едва приемлемый выход.
+
+**С полной наблюдаемостью**: планировщик выдаёт sprint contract — список компонентов для модификации, стандарты верификации для каждого и исключения (никаких стилей для печати). Генератор реализует согласно контракту. Рантайм-наблюдаемость фиксирует процесс загрузки и применения стилей для каждого компонента. Оценщик использует балльную рубрику для оценки по измерениям с конкретными ссылками на доказательства. Одна итерация даёт высококачественный результат, около 15 минут.
+
+Разница в эффективности в 3 раза. Единственное изменение — наблюдаемость.
+
+### Почему агенты не могут решить это сами
+
+Вы можете подумать: «Почему агент сам не печатает свои логи?» Проблемы такие:
+
+1. Агент не знает того, чего не знает — он не станет проактивно записывать сигналы, о необходимости которых он не подозревает.
+2. Форматы логов несогласованы — разные сессии используют разные форматы логов, что делает систематический анализ невозможным.
+3. Процессную наблюдаемость нельзя решить логами — sprint contracts и рубрики оценки являются структурированными артефактами, которым нужна поддержка на уровне harness.
+
+## Как делать правильно
+
+### 1. Встройте сбор рантайм-сигналов в harness
+
+Не полагайтесь на то, что агент сам напечатает логи. Harness должен автоматически собирать эти сигналы:
+
+- **Жизненный цикл приложения**: состояния фаз startup, ready, running, shutdown
+- **Выполнение пути фичи**: записи выполнения критических путей, включая точки входа, контрольные точки и выходы
+- **Поток данных**: записи о потоке данных между компонентами
+- **Использование ресурсов**: аномальные паттерны использования ресурсов (например, постоянно растущая память)
+- **Ошибки и исключения**: полный контекст ошибки, а не просто сообщение об ошибке
+
+### 2. Внедрите Sprint Contracts
+
+Перед стартом каждой задачи генератор и оценщик (которые могут быть разными вызовами одного и того же агента) согласуют контракт:
+
+```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, span для каждой задачи и саб-span для каждого шага верификации. Используйте стандартные атрибуты для аннотации ключевой информации. Так данные наблюдаемости интегрируются со стандартными цепочками инструментов (Jaeger, Zipkin).
+
+## Реальный кейс
+
+Harness, использующий воркфлоу «планировщик-генератор-оценщик», выполняющий задачу «добавить поддержку тёмной темы»:
+
+**Версия без наблюдаемости**: 3–4 раунда слепых ретраев, 45 минут, едва приемлемый результат. Оценщик говорит «что-то не то», но не может сказать что именно. Генератор тратит много времени в неверных направлениях.
+
+**Полностью наблюдаемая версия**:
+- Sprint contract уточняет скоуп, стандарты и исключения
+- Рантайм-трейсы фиксируют процесс загрузки стилей каждого компонента
+- Балльная рубрика обеспечивает структурированную оценку по измерениям
+- Одна итерация даёт высококачественные результаты, 15 минут
+
+Прирост эффективности в 3 раза, более стабильное качество, воспроизводимые оценки.
+
+## Ключевые выводы
+
+- **Наблюдаемость — это архитектурное свойство harness** — не фича, добавляемая постфактум, а ключевая способность, которую нужно учитывать при проектировании.
+- **Оба слоя наблюдаемости обязательны** — рантайм-сигналы объясняют «что произошло», процессные артефакты объясняют «почему это сделано именно так».
+- **Sprint contracts заранее выравнивают понимание** — предотвращают ситуации, когда «генератор построил то, что оценщик сразу отвергает по предсказуемым причинам».
+- **Балльные рубрики делают оценку воспроизводимой** — разные оценщики выдают схожие баллы для одного и того же выхода.
+- **Отсутствие наблюдаемости тратит 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 contracts и рубрик оценщика
+- [Site Reliability Engineering — Google](https://sre.google/sre-book/table-of-contents/) — систематическое применение наблюдаемости в продакшен-системах
+
+## Упражнения
+
+1. **Анализ пробелов в наблюдаемости**: проведите аудит вашего текущего harness на предмет наблюдаемости системного и процессного уровней. Найдите состояния системы, которые невозможно различить по существующим сигналам, и предложите дополнения.
+
+2. **Практика Sprint Contract**: напишите sprint contract для реальной задачи. Заставьте агента выполнить её согласно контракту и сравните эффективность и качество с контрактом и без него.
+
+3. **Построение трейса задачи**: запишите каждый шаг операций агента в течение полной задачи кодинга. Аннотируйте семантическими конвенциями OpenTelemetry. Проанализируйте узкие места информации в трейсе — на каких шагах не хватает достаточных сигналов для решений.
+ bash -c .textfile /Users/sanbu/Code/github/learn-harness-engineering/docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md
\ No newline at end of file
diff --git a/docs/ru/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md b/docs/ru/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-comparison-template.md
new file mode 100644
index 0000000..01027c1
--- /dev/null
+++ b/docs/ru/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/ru/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts b/docs/ru/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/ru/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/ru/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md b/docs/ru/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md
new file mode 100644
index 0000000..7917810
--- /dev/null
+++ b/docs/ru/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-loop.md
@@ -0,0 +1,9 @@
+# Пример Cleanup Loop
+
+Регулярные задачи очистки:
+
+- сканирование устаревшей документации
+- сканирование структурных нарушений
+- обновление оценок качества
+- открытие точечных PR с очисткой
+- повторный прогон фиксированного среза бенчмарка после очистки
diff --git a/docs/ru/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts b/docs/ru/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/ru/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/ru/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md b/docs/ru/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md
new file mode 100644
index 0000000..cf7c3dd
--- /dev/null
+++ b/docs/ru/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/index.md
@@ -0,0 +1,8 @@
+# Код к лекции 12
+
+Используйте эту папку для примеров:
+
+- срезы бенчмарков
+- задачи очистки
+- примеры снижения энтропии
+- повторяемые запуски harness
diff --git a/docs/ru/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md b/docs/ru/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
new file mode 100644
index 0000000..af7edff
--- /dev/null
+++ b/docs/ru/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
@@ -0,0 +1,187 @@
+[中文版本 →](../../../zh/lectures/lecture-12-why-every-session-must-leave-a-clean-state/)
+
+> Примеры кода: [code/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/)
+> Практический проект: [Проект 06. Полноценный harness (Capstone)](./../../projects/project-06-runtime-observability-and-debugging/index.md)
+
+# Лекция 12. Чистая передача в конце каждой сессии
+
+## Какую проблему решает эта лекция?
+
+Ваш агент работает весь день, меняет 20 файлов, коммитит код, сессия заканчивается. Следующая сессия агента стартует и сразу обнаруживает: сборка сломана, тесты красные, повсюду временные дебаг-файлы, список фич не обновлён, прогресс совершенно неясен. Новая сессия тратит первые 30 минут просто на выяснение «что вообще делала прошлая сессия».
+
+И OpenAI, и Anthropic заявляют чётко: **долгосрочная надёжность зависит от операционной дисциплины, а не только от успеха одного запуска.** Качество состояния на выходе из сессии напрямую определяет эффективность следующей сессии. Думайте об этом как о лучших практиках Git — каждый коммит должен быть атомарным, компилируемым изменением, а не кучей полудоделанного кода.
+
+## Ключевые понятия
+
+- **Чистое состояние**: система удовлетворяет пяти условиям в конце сессии — сборка проходит, тесты проходят, прогресс зафиксирован, нет устаревших артефактов, доступен путь запуска. Если что-то одно отсутствует — сессия не «завершена».
+- **Целостность сессии**: аналогично транзакциям БД — либо полностью коммитим и оставляем чистое состояние, либо откатываемся к последнему согласованному состоянию. Никакой золотой середины.
+- **Документ качества**: активный артефакт, который непрерывно фиксирует рейтинги качества по каждому модулю. Не разовая оценка, а трекер, показывающий, становится ли кодовая база сильнее или слабее со временем.
+- **Cleanup loop**: регулярная сессия обслуживания, направленная на систематическое снижение энтропии в кодовой базе. Не аварийный фикс, а рутинные операции.
+- **Упрощение harness**: по мере роста возможностей моделей периодически удаляйте компоненты harness, которые больше не нужны. Ограничение, существенное сегодня, может оказаться ненужным оверхедом через три месяца.
+- **Идемпотентная очистка**: операции очистки дают тот же результат независимо от того, сколько раз они выполняются. Гарантирует безопасность очистки даже в сценариях «сбой-ретрай».
+
+## Пять измерений чистого состояния
+
+```mermaid
+flowchart LR
+ Work["Работа над фичей завершена"] --> Build{"Сборка проходит?"}
+ Build -->|да| Test{"Тесты проходят?"}
+ Build -->|нет| Fix["Починить перед выходом"]
+ Test -->|да| Record["Обновить список фич + прогресс"]
+ Test -->|нет| Fix
+ Record --> Cleanup["Удалить временные артефакты / дебаг-код"]
+ Cleanup --> Startup{"Стандартный путь запуска работает?"}
+ Startup -->|да| Clean["Чистая передача"]
+ Startup -->|нет| Fix
+ Fix --> Build
+```
+
+```mermaid
+flowchart LR
+ Dirty["Сессия заканчивается с<br/>красными тестами / временными файлами / без обновления прогресса"] --> Diagnose["Следующей сессии сначала придётся<br/>разбираться, что произошло"]
+ Diagnose --> Fragile["Новая работа стартует на грязном репозитории"]
+ Fragile --> More["Больше дебаг-файлов, больше сломанных проверок,<br/>больше неясного прогресса"]
+ More --> Dirty
+
+ Clean["Сессия заканчивается с<br/>зелёными тестами / обновлённым прогрессом / удалёнными временными файлами"] --> Fast["Следующая сессия может сразу начинать кодить"]
+ Fast --> Stable["Не нужно сначала спасать репозиторий"]
+ Stable --> Clean
+```
+
+## Почему так происходит
+
+### Рост энтропии — это состояние по умолчанию
+
+Законы эволюции ПО Лемана говорят нам: системы, подвергающиеся непрерывным изменениям, неизбежно усложняются, если ими активно не управлять. Это особенно верно для AI-агентов кодинга — каждая сессия вносит изменения, и без очистки на выходе технический долг накапливается экспоненциально.
+
+Реальные данные красноречивы. Проект, разрабатывавшийся с агентами 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%. Это не теория — это наблюдаемая разница.
+
+### Пять измерений чистого состояния
+
+Чистое состояние — это не просто «код собирается». Это пять измерений, оцениваемых вместе:
+
+**Измерение сборки**: собирается ли код без ошибок? Это самое базовое — следующей сессии не должно приходиться сначала чинить ошибки сборки.
+
+**Измерение тестов**: проходят ли все тесты? Включая тесты, существовавшие до сессии — сессия отвечает за то, чтобы не сломать существующую функциональность. И это должно быть проверено в CI, а не только «работает у меня на машине».
+
+**Измерение прогресса**: зафиксирован ли текущий прогресс в машиночитаемом артефакте? Завершённые подзадачи с критериями их прохождения, начатые, но незавершённые подзадачи с текущим состоянием, ещё не начатые подзадачи. Хорошие записи прогресса сокращают 60–80% времени диагностики при старте сессии.
+
+**Измерение артефактов**: есть ли устаревшие или неоднозначные временные артефакты? Дебаг-логи, временные файлы, закомментированный код, TODO-маркеры — всё это увеличивает когнитивную нагрузку для следующей сессии.
+
+**Измерение запуска**: доступен ли стандартный путь запуска? Может ли следующая сессия начать работу без ручного вмешательства? Инициализация окружения, загрузка кодовой базы, получение контекста, выбор задачи — эти пути не должны быть сломаны.
+
+### «Уберём потом» означает «никогда не убираем»
+
+Самая распространённая ментальная ловушка — «нет времени убирать в этой сессии, сделаю в следующий раз». Но следующая сессия агента не знает, что вы оставили — она видит беспорядок кода и неопределённое состояние. Она потратит много времени, выясняя «какие части этого кода намеренные, а какие временные».
+
+Хуже того, у каждой сессии свои цели. Новая сессия здесь, чтобы делать новую работу, а не убирать беспорядок предыдущей сессии. Она проигнорирует хаос и начнёт новую работу поверх него, добавляя ещё больше хаоса поверх хаоса. Это положительная обратная связь энтропии.
+
+## Как делать правильно
+
+### 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. Двухрежимная стратегия очистки
+
+Совместите два режима очистки:
+
+**Немедленная очистка (в конце каждой сессии)**: убрать временные артефакты, созданные за сессию, обновить состояние списка фич, убедиться, что сборка и тесты проходят. Это очистка по «подсчёту ссылок».
+
+**Периодическая очистка (еженедельно)**: полное сканирование системы — обработать накопившиеся структурные проблемы, обновить документы качества, прогнать бенчмарк-тесты для выявления дрейфа. Это «трассирующая» очистка.
+
+### 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. Периодически упрощайте harness
+
+Важный инсайт от Anthropic: **каждый компонент harness существует, потому что модель не может надёжно делать что-то самостоятельно. Но по мере улучшения моделей эти предположения устаревают.** Ограничение, существенное три месяца назад, может сегодня оказаться ненужным оверхедом.
+
+Рекомендуемая практика: каждый месяц выбирайте один компонент harness, временно отключайте его и прогоняйте бенчмарк-задачи. Если результаты не деградируют — удалите его навсегда. Если деградируют — восстановите или замените более лёгкой альтернативой.
+
+### 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
+```
+
+## Реальный кейс
+
+Electron-приложение, разрабатываемое с агентами 12 недель, сравнение двух подходов:
+
+**Без стратегии очистки** (контрольная группа): неделя 12, успех сборки 68%, успех тестов 61%, запуск новой сессии 60+ мин, устаревших артефактов 103.
+
+**Со стратегией очистки** (экспериментальная группа): полная проверка чистого состояния в конце каждой сессии + еженедельный cleanup loop. Неделя 12, успех сборки 97%, успех тестов 95%, запуск новой сессии 9 мин, устаревших артефактов 11.
+
+К 12-й неделе у экспериментальной группы успех сборки выше на 29 процентных пунктов, успех тестов — на 34 пункта, время запуска новой сессии ниже на 85%.
+
+## Ключевые выводы
+
+- **Чистое состояние — необходимое условие завершения сессии** — не опциональная уборка, а часть «definition of done».
+- **Все пять измерений обязательны** — сборка, тесты, прогресс, артефакты, запуск — каждое должно быть явно проверено.
+- **Документы качества делают здоровье кодовой базы отслеживаемым** — починить можно только то, о чьей деградации вы знаете.
+- **Периодически упрощайте 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, временно отключите его и прогоните бенчмарк-задачи. Сравните результаты с ним и без него. Решите, оставить, удалить или заменить.
+ bash -c .textfile /Users/sanbu/Code/github/learn-harness-engineering/docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md
\ No newline at end of file
diff --git a/docs/ru/projects/index.md b/docs/ru/projects/index.md
new file mode 100644
index 0000000..15c48fa
--- /dev/null
+++ b/docs/ru/projects/index.md
@@ -0,0 +1,23 @@
+# Добро пожаловать в Проекты
+
+Это практическая часть курса Learn Harness Engineering. Чтения лекций недостаточно — вам нужно собрать окружения самостоятельно и понаблюдать, как Codex, Claude Code или другие AI-агенты ведут себя при разных правилах.
+
+## Обзор проектов
+
+Курс включает 6 прогрессивных практических проектов, которые научат вас строить надёжное агентское рабочее окружение с нуля:
+
+1. **Только промпт vs. правила в первую очередь**: сравните, как агент справляется с одним лишь промптом против базового harness.
+2. **Воркспейс, читаемый агентом**: научитесь структурировать репозиторий так, чтобы он был дружелюбен к ИИ, и наладьте механизмы передачи работы.
+3. **Непрерывность между сессиями**: спроектируйте файлы состояния и инициализационные скрипты, чтобы агент мог бесшовно продолжать работу между сессиями.
+4. **Runtime-обратная связь и контроль скоупа**: внедрите инструменты, позволяющие агенту тестировать свой код и исправлять ошибки во время выполнения.
+5. **Самопроверка и разделение ролей**: постройте независимый механизм ревью, чтобы предотвратить галлюцинации и преждевременные объявления о победе.
+6. **Полный harness (capstone)**: соберите финальное, наблюдаемое, end-to-end агентское рабочее окружение.
+
+## Как двигаться
+
+В каждой папке проекта обычно есть:
+- `starter/`: ваш стартовый воркспейс.
+- `solution/`: эталонная реализация (если застряли).
+- Инструкции к задаче с описанием контекста и конкретных целей.
+
+Используйте предпочитаемый AI Coding Agent (например, Claude Code, Cursor, Trae) для выполнения задач внутри директории `starter/`.
diff --git a/docs/ru/projects/project-01-baseline-vs-minimal-harness/index.md b/docs/ru/projects/project-01-baseline-vs-minimal-harness/index.md
new file mode 100644
index 0000000..69c3a45
--- /dev/null
+++ b/docs/ru/projects/project-01-baseline-vs-minimal-harness/index.md
@@ -0,0 +1,25 @@
+[中文版本 →](../../../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/en/resources/templates/)
+
+# Проект 01. Только промпт vs. правила в первую очередь: насколько велика разница
+
+## Что вы делаете
+
+Соберите минимальный каркас Electron-приложения базы знаний — окно со списком документов слева, панелью Q&A справа и локальной директорией данных. Сама задача несложная. Сложно — заставить агента её выполнить.
+
+Вы запускаете её дважды. Первый раз: только промпт, без подготовки. Второй раз: `AGENTS.md`, `init.sh`, `feature_list.json` уже размещены в репозитории. Затем сравниваете.
+
+Суть этого проекта не в написании кода — а в том, чтобы понять, насколько велика разница между «потратить 15 минут на правила» и «просто отпустить агента».
+
+## Инструменты
+
+- Claude Code или Codex (выберите один, используйте для обоих запусков)
+- Git (управление ветками и сравнение)
+- Node.js + Electron (стек проекта)
+- Таймер (фиксируйте длительность каждого запуска)
+
+## Механизм harness
+
+Минимальный harness: `AGENTS.md` + `init.sh` + `feature_list.json`
diff --git a/docs/ru/projects/project-02-agent-readable-workspace/index.md b/docs/ru/projects/project-02-agent-readable-workspace/index.md
new file mode 100644
index 0000000..d86d5e1
--- /dev/null
+++ b/docs/ru/projects/project-02-agent-readable-workspace/index.md
@@ -0,0 +1,22 @@
+[中文版本 →](../../../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/en/resources/templates/)
+
+# Проект 02. Сделайте проект читаемым и продолжите с того места, где остановились
+
+## Что вы делаете
+
+Добавьте «читаемость» в репозиторий, чтобы новый агент мог быстро понять структуру проекта, узнать текущий прогресс и продолжить работу. Конкретно: реализуйте импорт документов, просмотр деталей документа и локальное хранение, выполнив всё за две сессии.
+
+Вы запускаете задачу дважды: первый раз — без какой-либо помощи, второй — с заранее размещёнными в репозитории `ARCHITECTURE.md`, `PRODUCT.md` и `session-handoff.md`.
+
+## Инструменты
+
+- Claude Code или Codex
+- Git
+- Node.js + Electron
+
+## Механизм harness
+
+Воркспейс, читаемый агентом + персистентные файлы состояния
diff --git a/docs/ru/projects/project-03-multi-session-continuity/index.md b/docs/ru/projects/project-03-multi-session-continuity/index.md
new file mode 100644
index 0000000..7ba3404
--- /dev/null
+++ b/docs/ru/projects/project-03-multi-session-continuity/index.md
@@ -0,0 +1,22 @@
+[中文版本 →](../../../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/en/resources/templates/)
+
+# Проект 03. Заставьте агента продолжать работу через перезапуски сессий
+
+## Что вы делаете
+
+Добавьте агенту контроль скоупа и проверочные шлюзы. Реализуйте чанкование документов, извлечение метаданных, отображение прогресса индексации и Q&A-флоу с цитатами. Используйте `feature_list.json` для отслеживания статуса фич — по одной фиче за раз, никакого «pass» без доказательств верификации.
+
+Вы запускаете задачу дважды: первый раз — без ограничений, второй — со строгим контролем.
+
+## Инструменты
+
+- Claude Code или Codex
+- Git
+- Node.js + Electron
+
+## Механизм harness
+
+Лог прогресса + handoff между сессиями + непрерывность между сессиями
diff --git a/docs/ru/projects/project-04-incremental-indexing/index.md b/docs/ru/projects/project-04-incremental-indexing/index.md
new file mode 100644
index 0000000..5a32ea9
--- /dev/null
+++ b/docs/ru/projects/project-04-incremental-indexing/index.md
@@ -0,0 +1,22 @@
+[中文版本 →](../../../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/en/resources/templates/)
+
+# Проект 04. Используйте runtime-обратную связь, чтобы корректировать поведение агента
+
+## Что вы делаете
+
+Добавьте runtime-наблюдаемость (логи запуска, логи импорта/индексации, состояния ошибок) и архитектурные ограничения, чтобы предотвратить нарушения границ слоёв. Подкиньте агенту runtime-баг для исправления.
+
+Вы запускаете задачу дважды: первый раз — без логов и ограничений, второй — с правильными инструментами и правилами.
+
+## Инструменты
+
+- Claude Code или Codex
+- Git
+- Node.js + Electron
+
+## Механизм harness
+
+Runtime-обратная связь + контроль скоупа + инкрементальная индексация
diff --git a/docs/ru/projects/project-05-grounded-qa-verification/index.md b/docs/ru/projects/project-05-grounded-qa-verification/index.md
new file mode 100644
index 0000000..41ce956
--- /dev/null
+++ b/docs/ru/projects/project-05-grounded-qa-verification/index.md
@@ -0,0 +1,22 @@
+[中文版本 →](../../../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/en/resources/templates/)
+
+# Проект 05. Заставьте агента самостоятельно проверять свою работу
+
+## Что вы делаете
+
+Реализуйте разделение ролей — генератор, который пишет код, evaluator, который ревьюит, и опционально планировщик. Запустите трижды, чтобы измерить эффект каждой добавленной роли.
+
+Выберите содержательную фичу-апгрейд (многоходовой диалог, редизайн панели цитирования или фильтрация документов) и удерживайте её одинаковой во всех запусках.
+
+## Инструменты
+
+- Claude Code или Codex
+- Git
+- Node.js + Electron
+
+## Механизм harness
+
+Самопроверка + Q&A с обоснованием + завершение по доказательствам
diff --git a/docs/ru/projects/project-06-runtime-observability-and-debugging/index.md b/docs/ru/projects/project-06-runtime-observability-and-debugging/index.md
new file mode 100644
index 0000000..ce41159
--- /dev/null
+++ b/docs/ru/projects/project-06-runtime-observability-and-debugging/index.md
@@ -0,0 +1,25 @@
+[中文版本 →](../../../zh/projects/project-06-runtime-observability-and-debugging/)
+
+> Связанные лекции: [Лекция 11. Сделайте runtime агента наблюдаемым](./../../lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md) · [Лекция 12. Чистый handoff в конце каждой сессии](./../../lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md)
+> Файлы шаблонов: [templates/](https://github.com/walkinglabs/learn-harness-engineering/blob/main/docs/en/resources/templates/)
+
+# Проект 06. Соберите полноценный агентский harness (Capstone)
+
+## Что вы делаете
+
+Это capstone-проект. Соберите всё, чему научились в первых пяти проектах, проведите полный бенчмарк, затем сделайте проход уборки, чтобы убедиться, что качество поддерживаемое.
+
+Используйте фиксированный набор multi-feature задач, охватывающий полный продуктовый срез: импорт документов, индексация, Q&A с цитатами, runtime-наблюдаемость и читаемое перезапускаемое состояние репозитория. Сначала запустите со слабым harness-baseline, затем с самым сильным harness, потом — уборку и повторный запуск. Наконец, проведите эксперимент с абляцией harness — убирайте по одному компоненту за раз и смотрите, какие из них реально важны.
+
+## Инструменты
+
+- Claude Code или Codex
+- Git
+- Node.js + Electron
+- Шаблон quality-документа
+- Рубрика evaluator
+- Все компоненты harness, накопленные за первые пять проектов
+
+## Механизм harness
+
+Полный harness: все механизмы + наблюдаемость + ablation-исследование
diff --git a/docs/ru/resources/index.md b/docs/ru/resources/index.md
new file mode 100644
index 0000000..2919761
--- /dev/null
+++ b/docs/ru/resources/index.md
@@ -0,0 +1,50 @@
+# Английская библиотека ресурсов
+
+Эта папка превращает методы курса в готовые к копированию шаблоны и компактные референсы, которые можно использовать в реальном репозитории.
+
+## Когда её использовать
+
+Начните отсюда, когда хотите, чтобы 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)
+- референс bootstrap-скрипта: `docs/en/resources/templates/init.sh`
+
+Затем добавьте:
+
+- session handoff: [`templates/session-handoff.md`](./templates/session-handoff.md)
+- чек-лист чистого выхода: [`templates/clean-state-checklist.md`](./templates/clean-state-checklist.md)
+- рубрика evaluator: [`templates/evaluator-rubric.md`](./templates/evaluator-rubric.md)
+
+Если вам нужна более полная структура репозитория в стиле OpenAI из поста «Harness engineering», используйте advanced-пак:
+
+- [`openai-advanced/index.md`](./openai-advanced/index.md)
+
+## Структура библиотеки
+
+- [`templates/`](./templates/index.md): шаблоны для копирования в реальный репозиторий
+- [`reference/`](./reference/index.md): заметки по методу, флоу старта и карты режимов отказа
+- [`openai-advanced/`](./openai-advanced/index.md): продвинутый каркас репозитория, документы system-of-record и шаблоны agent-first управления
+
+## Рекомендуемый минимальный пак
+
+- `AGENTS.md` или `CLAUDE.md`
+- `feature_list.json`
+- `claude-progress.md`
+- `init.sh`
+
+Этих четырёх файлов достаточно, чтобы заметно стабилизировать большинство агентских воркфлоу.
+
+Когда репозиторий вырастает в долгоживущую систему с несколькими доменами, активными планами, оценкой качества и политиками надёжности, переходите на пак [`openai-advanced/`](./openai-advanced/index.md), а не растягивайте минимальный пак сверх меры.
diff --git a/docs/ru/resources/openai-advanced/index.md b/docs/ru/resources/openai-advanced/index.md
new file mode 100644
index 0000000..dbb5dfe
--- /dev/null
+++ b/docs/ru/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` в стиле маршрутизатора
+- долговечные документы — система записи внутри репозитория
+- активные и завершённые exec plans
+- явные файлы политик по продукту, надёжности, безопасности и фронтенду
+- скоринг качества по продуктовым доменам и архитектурным слоям
+- папки со справочными материалами, удобными для модели
+- стандартные операционные процедуры по архитектуре, фиксации знаний и валидации в рантайме
+
+## Что входит в стартовую раскладку
+
+Стартовый пак в [`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) превращает диаграммы из статьи в пошаговые
+операционные процедуры:
+
+- настройка слоёной доменной архитектуры
+- кодирование скрытых знаний в репозиторий
+- локальный стек observability и feedback-loop рабочий процесс
+- цикл валидации UI через Chrome DevTools
+
+## Принципы дизайна
+
+- Короткая входная точка, более глубокие связанные документы
+- Репозиторий как система записи
+- Механические проверки лучше запомненных правил
+- Планы и история качества живут рядом с кодом
+- Уборка и упрощение — первоклассная ответственность
+
+Этот пак намеренно выверенный, но его всё равно следует адаптировать под ваш
+проект, а не копировать вслепую.
diff --git a/docs/ru/resources/openai-advanced/repo-template/AGENTS.md b/docs/ru/resources/openai-advanced/repo-template/AGENTS.md
new file mode 100644
index 0000000..e83759e
--- /dev/null
+++ b/docs/ru/resources/openai-advanced/repo-template/AGENTS.md
@@ -0,0 +1,61 @@
+# AGENTS.md
+
+Этот репозиторий заточен под долгие сессии работы coding-агентов. Держите этот
+файл коротким. Используйте его как маршрутизирующий слой к документам — системе
+записи, а не как огромный сброс инструкций.
+
+## Стартовый рабочий процесс
+
+Перед изменением кода:
+
+1. Подтвердите корень репозитория через `pwd`.
+2. Прочитайте `ARCHITECTURE.md` для текущей карты системы и жёстких правил зависимостей.
+3. Прочитайте `docs/QUALITY_SCORE.md`, чтобы увидеть, какие домены или слои самые слабые.
+4. Прочитайте `docs/PLANS.md`, затем откройте активный план, по которому работаете.
+5. Прочитайте релевантную продуктовую спецификацию в `docs/product-specs/`.
+6. Запустите стандартный путь bootstrap и верификации для этого репозитория.
+7. Если базовая верификация падает, почините её до расширения скоупа.
+
+## Карта маршрутизации
+
+- `ARCHITECTURE.md`: карта доменов, модель слоёв, правила зависимостей
+- `docs/design-docs/index.md`: дизайн-решения и базовые убеждения
+- `docs/product-specs/index.md`: текущее продуктовое поведение и критерии приёмки
+- `docs/PLANS.md`: жизненный цикл планов и политика exec plans
+- `docs/QUALITY_SCORE.md`: здоровье продуктовых доменов и слоёв
+- `docs/RELIABILITY.md`: рантайм-сигналы, бенчмарки и ожидания по перезапуску
+- `docs/SECURITY.md`: правила по секретам, песочнице, данным и внешним действиям
+- `docs/FRONTEND.md`: ограничения UI, правила дизайн-системы, проверки доступности
+
+## Рабочий контракт
+
+- Работайте по одному ограниченному плану или фиче-срезу за раз.
+- Не помечайте работу как готовую только по результатам инспекции кода; нужны
+ запускаемые доказательства.
+- Если вы меняете поведение, обновите соответствующие продуктовые, плановые
+ или reliability-документы в той же сессии.
+- Если вы видите повторяющийся фидбек на ревью, превратите его в механическое
+ правило, проверку или линтер вместо повторного объяснения в чате.
+- Храните сгенерированные материалы в `docs/generated/`, а исходные ссылки — в
+ `docs/references/`.
+- Предпочитайте добавлять небольшие актуальные документы вместо разрастания этого файла.
+
+## Definition Of Done
+
+Изменение считается готовым только когда выполнено всё:
+
+- целевое поведение реализовано
+- требуемая верификация действительно прошла
+- доказательство приложено в соответствующем плане или документе по качеству
+- затронутые документы остаются актуальными
+- репозиторий чисто перезапускается со стандартного стартового пути
+
+## Конец сессии
+
+Перед завершением сессии:
+
+1. Обновите активный exec plan.
+2. Обновите `docs/QUALITY_SCORE.md`, если какой-либо домен или слой существенно изменился.
+3. Запишите новый техдолг в `docs/exec-plans/tech-debt-tracker.md`, если вы его отложили.
+4. Перенесите завершённые планы в `docs/exec-plans/completed/`, когда уместно.
+5. Оставьте репозиторий в перезапускаемом состоянии с чётким следующим шагом.
diff --git a/docs/ru/resources/openai-advanced/repo-template/ARCHITECTURE.md b/docs/ru/resources/openai-advanced/repo-template/ARCHITECTURE.md
new file mode 100644
index 0000000..4d08356
--- /dev/null
+++ b/docs/ru/resources/openai-advanced/repo-template/ARCHITECTURE.md
@@ -0,0 +1,57 @@
+# ARCHITECTURE.md
+
+Этот файл — верхнеуровневая карта системы. Он должен оставаться лаконичным и
+указывать на более глубокие документы, когда нужно.
+
+## Форма системы
+
+- Продукт: `[замените названием продукта]`
+- Основной пользовательский сценарий: `[замените основным сценарием]`
+- Поверхности рантайма: `[desktop / web / cli / services / workers]`
+- Источник истины для продуктового поведения: `docs/product-specs/`
+
+## Карта доменов
+
+| Домен | Назначение | Основные точки входа | Связанная спецификация |
+|--------|---------|----------------------|--------------|
+| `[domain-a]` | `[чем владеет]` | `[модули / роуты / команды]` | `[путь к спецификации]` |
+| `[domain-b]` | `[чем владеет]` | `[модули / роуты / команды]` | `[путь к спецификации]` |
+
+## Модель слоёв
+
+Используйте фиксированную направленную модель, чтобы агенты не выдумывали ad hoc архитектуру:
+
+`Types -> Config -> Repo -> Service -> Runtime -> UI`
+
+Сквозные сущности должны попадать через явные провайдеры или границы адаптеров,
+а не тянуться напрямую через слои.
+
+## Жёсткие правила зависимостей
+
+- Нижние слои не должны зависеть от верхних.
+- UI не должен обходить контракты рантайма или сервисов.
+- Доступ к данным должен идти через репозитории или эквивалентные адаптеры.
+- Общие утилиты должны оставаться универсальными и не накапливать доменную логику.
+- Новые зависимости должны быть обоснованы в соответствующем плане или дизайн-документе.
+
+## Сквозные интерфейсы
+
+| Сущность | Утверждённая граница | Заметки |
+|--------|-------------------|-------|
+| Логирование и трейсинг | `[провайдер / путь утилиты]` | `[только структурированно, никакого ad hoc console]` |
+| Аутентификация | `[путь провайдера]` | `[правила токенов/сессий]` |
+| Внешние API | `[путь клиента или провайдера]` | `[ограничение скорости / правила ретраев]` |
+| Feature flags | `[граница флагов]` | `[владение]` |
+
+## Текущие горячие точки
+
+- `[область, которую агентам сложнее всего безопасно менять]`
+- `[область со слабыми границами или хрупкими тестами]`
+
+## Чеклист изменений
+
+Когда вы трогаете архитектурно значимый код:
+
+1. Обновите этот файл, если изменилась карта доменов или допустимые границы.
+2. Обновите соответствующий дизайн-документ в `docs/design-docs/`, если изменилась логика рассуждений.
+3. Добавьте или обновите исполняемую проверку, если правило должно быть проверено механически.
diff --git a/docs/ru/resources/openai-advanced/repo-template/docs/DESIGN.md b/docs/ru/resources/openai-advanced/repo-template/docs/DESIGN.md
new file mode 100644
index 0000000..159e9e7
--- /dev/null
+++ b/docs/ru/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`: общепроектные agent-first убеждения
+
+## Правила дизайна
+
+- Держите дизайн-документы небольшими и актуальными.
+- Предпочитайте один документ на одну зону решения.
+- Связывайте дизайн-документы из планов и спецификаций, когда изменение от них зависит.
+- Если дизайн-правило становится операционно критичным, превратите его в
+ автоматизированную проверку или обновите `ARCHITECTURE.md`.
diff --git a/docs/ru/resources/openai-advanced/repo-template/docs/FRONTEND.md b/docs/ru/resources/openai-advanced/repo-template/docs/FRONTEND.md
new file mode 100644
index 0000000..df535e6
--- /dev/null
+++ b/docs/ru/resources/openai-advanced/repo-template/docs/FRONTEND.md
@@ -0,0 +1,24 @@
+# FRONTEND.md
+
+Этот файл задаёт стабильные ожидания по фронтенду, чтобы агенты не изобретали
+UI-паттерны непредсказуемо.
+
+## Принципы UI
+
+- Оптимизируйте под ясность раньше, чем под новизну.
+- Делайте потоки взаимодействия обнаруживаемыми и перезапускаемыми.
+- Предпочитайте небольшое число переиспользуемых компонентов одноразовым вариантам.
+- Проверки доступности — часть обычной верификации, а не финального полирования.
+
+## Ограничители
+
+- Документируйте дизайн-систему или библиотеку компонентов в `docs/references/`.
+- Фиксируйте ключевые состояния, видимые пользователю: пустое, загрузка, успех, ошибка, повтор.
+- Сохраняйте согласованность копирайтинга, поведения клавиатуры и визуальной иерархии между потоками.
+- Когда UI-баг исправлен, добавьте или обновите соответствующий шаг валидации.
+
+## Ожидания по верификации
+
+- Захватывайте доказательства для критичных пользовательских сценариев.
+- Записывайте шаги валидации в браузере или рантайме в соответствующий план.
+- Если визуальные регрессии часты, стандартизируйте проверки скриншотов или DOM.
diff --git a/docs/ru/resources/openai-advanced/repo-template/docs/PLANS.md b/docs/ru/resources/openai-advanced/repo-template/docs/PLANS.md
new file mode 100644
index 0000000..531a673
--- /dev/null
+++ b/docs/ru/resources/openai-advanced/repo-template/docs/PLANS.md
@@ -0,0 +1,35 @@
+# PLANS.md
+
+Этот файл задаёт, как exec plans создаются, обновляются, завершаются и
+архивируются.
+
+## Когда план обязателен
+
+Создавайте exec plan, когда работа:
+
+- занимает более одной сессии
+- меняет более одной подсистемы
+- имеет нетривиальные риски верификации или раскатки
+- зависит от открытых решений, которые должны быть зафиксированы
+
+## Где живут планы
+
+- `docs/exec-plans/active/`: планы, которые сейчас ведут работу
+- `docs/exec-plans/completed/`: завершённые планы, сохранённые для будущего контекста агентов
+- `docs/exec-plans/tech-debt-tracker.md`: отложенная работа и follow-ups
+
+## Минимальные секции плана
+
+- цель
+- скоуп и out-of-scope
+- путь верификации
+- риски и блокеры
+- лог прогресса
+- открытые решения
+
+## Правила работы
+
+- У одного активного плана должен быть один чётко принадлежащий текущий шаг.
+- Обновляйте план по мере работы; не относитесь к нему как к статической прозе.
+- Если решение меняет направление реализации, зафиксируйте это в плане.
+- Перемещайте завершённые планы в `completed/`, чтобы агенты могли всё ещё находить прежний контекст.
diff --git a/docs/ru/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md b/docs/ru/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md
new file mode 100644
index 0000000..a88b2bc
--- /dev/null
+++ b/docs/ru/resources/openai-advanced/repo-template/docs/PRODUCT_SENSE.md
@@ -0,0 +1,26 @@
+# PRODUCT_SENSE.md
+
+Этот файл фиксирует долговечное продуктовое суждение, которое агенты не могут
+надёжно вывести из одного только кода.
+
+## Ядро продукта
+
+- Основной пользователь: `[заменить]`
+- Job to be done: `[заменить]`
+- Главное раздражение, которое нужно убрать: `[заменить]`
+- Планка качества для приёмки: `[заменить]`
+
+## Продуктовые правила
+
+- Предпочитайте видимую пользователю надёжность количеству фич.
+- Считайте неоднозначное поведение пробелом в спецификации, а не разрешением гадать.
+- Если реализация меняет то, что пользователи видят или чему доверяют, обновите соответствующую спецификацию.
+- Используйте продуктовые спецификации для конкретных потоков, а этот файл — для сквозных
+ продуктовых приоритетов.
+
+## Запрещённые паттерны
+
+- Скрытые разрушительные действия
+- Тихий сбой без обратной связи пользователю
+- Неясный источник истины для видимого состояния
+- Фичи, которые нельзя объяснить одним предложением
diff --git a/docs/ru/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md b/docs/ru/resources/openai-advanced/repo-template/docs/QUALITY_SCORE.md
new file mode 100644
index 0000000..f932475
--- /dev/null
+++ b/docs/ru/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 | `[компонент]` | `[ухудшилось / без изменений]` | `[вернуть / оставить удалённым]` |
diff --git a/docs/ru/resources/openai-advanced/repo-template/docs/RELIABILITY.md b/docs/ru/resources/openai-advanced/repo-template/docs/RELIABILITY.md
new file mode 100644
index 0000000..f33fefd
--- /dev/null
+++ b/docs/ru/resources/openai-advanced/repo-template/docs/RELIABILITY.md
@@ -0,0 +1,32 @@
+# RELIABILITY.md
+
+Этот файл задаёт, как система доказывает, что она здорова и перезапускаема.
+
+## Стандартные пути
+
+- Bootstrap: `[команда]`
+- Верификация: `[команда]`
+- Запуск приложения или сервиса: `[команда]`
+- Отладка или инспекция рантайма: `[команда]`
+
+## Обязательные рантайм-сигналы
+
+- структурированные логи для запуска и критичных потоков
+- health-проверки для ключевых сервисов
+- данные трейсинга или таймингов для медленных путей, когда доступно
+- видимые пользователю состояния ошибок для восстановимых сбоев
+
+## Golden journeys
+
+- `[сценарий 1]`
+- `[сценарий 2]`
+- `[сценарий 3]`
+
+У каждого golden journey должен быть повторяемый путь верификации и понятные сигналы сбоя.
+
+## Правила надёжности
+
+- Ни одна фича не считается завершённой, если после неё система не может чисто перезапуститься.
+- Сбои в рантайме должны быть диагностируемы по локальным сигналам репозитория.
+- Если появляется повторяющийся режим сбоя, добавьте бенчмарк или ограничитель для него.
+- Уборка — часть надёжности, а не отдельная забота.
diff --git a/docs/ru/resources/openai-advanced/repo-template/docs/SECURITY.md b/docs/ru/resources/openai-advanced/repo-template/docs/SECURITY.md
new file mode 100644
index 0000000..bdc3b2b
--- /dev/null
+++ b/docs/ru/resources/openai-advanced/repo-template/docs/SECURITY.md
@@ -0,0 +1,27 @@
+# SECURITY.md
+
+Этот файл задаёт правила безопасности, о которых агенты не должны догадываться.
+
+## Секреты и учётные данные
+
+- Никогда не зашивайте секреты в исходники или документы.
+- Документируйте здесь утверждённые пути загрузки секретов.
+- Скрывайте токены, API-ключи и персональные данные в логах и скриншотах.
+
+## Недоверенный ввод
+
+- Считайте внешний контент недоверенным, пока он не валидирован.
+- Записывайте здесь разрешённые границы fetch или выполнения.
+- Если есть риск prompt injection или command injection, документируйте ограничитель.
+
+## Внешние действия
+
+- Перечислите, какие действия требуют явного одобрения.
+- Запишите любые продакшн или разрушительные команды, которые агенты не должны запускать по умолчанию.
+- Предпочитайте sandbox-безопасные рабочие процессы для отладки и верификации.
+
+## Правила по зависимостям и ревью
+
+- Новые зависимости требуют обоснования в активном плане.
+- Изменения, чувствительные к безопасности, требуют явных шагов верификации.
+- Повторяющиеся комментарии security-ревью должны становиться проверками, а не племенным знанием.
diff --git a/docs/ru/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md b/docs/ru/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md
new file mode 100644
index 0000000..f6fb982
--- /dev/null
+++ b/docs/ru/resources/openai-advanced/repo-template/docs/design-docs/core-beliefs.md
@@ -0,0 +1,9 @@
+# Базовые убеждения
+
+- Репозиторий — это система записи для агентов.
+- `AGENTS.md` — это маршрутизатор, а не энциклопедия.
+- Доказательства верификации важнее уверенности.
+- Одна ограниченная задача лучше многих наполовину сделанных.
+- Повторяющийся фидбек от людей должен превращаться в переиспользуемые правила harness.
+- Уборка и упрощение — часть выпуска, а не довесок.
+- Если агент не может обнаружить факт внутри репозитория, считайте этот факт операционно недоступным.
diff --git a/docs/ru/resources/openai-advanced/repo-template/docs/design-docs/index.md b/docs/ru/resources/openai-advanced/repo-template/docs/design-docs/index.md
new file mode 100644
index 0000000..8c77a10
--- /dev/null
+++ b/docs/ru/resources/openai-advanced/repo-template/docs/design-docs/index.md
@@ -0,0 +1,21 @@
+# Индекс дизайн-документов
+
+Используйте этот индекс как обнаруживаемую карту истории дизайна.
+
+## Принятые
+
+- `core-beliefs.md`: agent-first операционные убеждения и долговечные нормы проекта
+
+## Предложенные
+
+- `[добавьте сюда пути новых дизайн-документов]`
+
+## Устаревшие
+
+- `[перенесите сюда старые или замещённые дизайн-документы со ссылками на замену]`
+
+## Правила сопровождения
+
+- У каждого дизайн-документа должен быть владелец или триггер обновления.
+- Удаляйте устаревшие документы или помечайте их как deprecated, не давая им дрейфовать.
+- Связывайте активные exec plans с дизайн-документами, от которых они зависят.
diff --git a/docs/ru/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md b/docs/ru/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md
new file mode 100644
index 0000000..4528587
--- /dev/null
+++ b/docs/ru/resources/openai-advanced/repo-template/docs/exec-plans/active/index.md
@@ -0,0 +1,10 @@
+# Активные планы
+
+Держите по одному markdown-файлу на каждый активный exec plan в этой папке.
+
+Рекомендуемый шаблон имени файла:
+
+- `YYYY-MM-DD-short-topic.md`
+
+Каждый активный план должен быть достаточно актуален, чтобы свежая сессия агента
+могла продолжить работу, опираясь только на репозиторий.
diff --git a/docs/ru/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md b/docs/ru/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md
new file mode 100644
index 0000000..395de51
--- /dev/null
+++ b/docs/ru/resources/openai-advanced/repo-template/docs/exec-plans/completed/index.md
@@ -0,0 +1,5 @@
+# Завершённые планы
+
+Перемещайте завершённые планы сюда вместо удаления. Завершённые планы — часть
+поверхности памяти репозитория, они помогают будущим запускам агентов понять,
+почему код выглядит так, как выглядит.
diff --git a/docs/ru/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md b/docs/ru/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md
new file mode 100644
index 0000000..92ec6f1
--- /dev/null
+++ b/docs/ru/resources/openai-advanced/repo-template/docs/exec-plans/tech-debt-tracker.md
@@ -0,0 +1,7 @@
+# Трекер техдолга
+
+Используйте этот файл для долга, который реален, осознан и сознательно отложен.
+
+| Дата | Область | Долг | Почему отложено | Риск | Следующий триггер |
+|------|------|------|--------------|------|--------------|
+| YYYY-MM-DD | `[область]` | `[долг]` | `[причина]` | `[риск]` | `[когда вернуться]` |
diff --git a/docs/ru/resources/openai-advanced/repo-template/docs/generated/db-schema.md b/docs/ru/resources/openai-advanced/repo-template/docs/generated/db-schema.md
new file mode 100644
index 0000000..62b60d1
--- /dev/null
+++ b/docs/ru/resources/openai-advanced/repo-template/docs/generated/db-schema.md
@@ -0,0 +1,14 @@
+# Схема базы данных
+
+Используйте эту папку для сгенерированных или производных артефактов, которые
+агенты должны иметь возможность инспектировать без реверс-инжиниринга из кода.
+
+## Источник
+
+- Сгенерировано из: `[команда или путь к источнику]`
+- Последнее обновление: `YYYY-MM-DD`
+
+## Заметки
+
+- Не редактируйте сгенерированные секции вручную.
+- Перегенерируйте этот файл, когда меняется исходная схема.
diff --git a/docs/ru/resources/openai-advanced/repo-template/docs/product-specs/index.md b/docs/ru/resources/openai-advanced/repo-template/docs/product-specs/index.md
new file mode 100644
index 0000000..da94c4c
--- /dev/null
+++ b/docs/ru/resources/openai-advanced/repo-template/docs/product-specs/index.md
@@ -0,0 +1,14 @@
+# Индекс продуктовых спецификаций
+
+Используйте эту папку для текущих спецификаций поведения, видимого пользователю.
+
+## Активные спецификации
+
+- `new-user-onboarding.md`
+
+## Правила
+
+- Спецификации должны описывать видимое пользователю поведение и критерии приёмки.
+- Если реализация расходится со спецификацией, обновите одно из них в той же
+ сессии.
+- Поддерживайте этот индекс актуальным, чтобы свежий агент мог быстро обнаружить продуктовый скоуп.
diff --git a/docs/ru/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md b/docs/ru/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md
new file mode 100644
index 0000000..7398a8c
--- /dev/null
+++ b/docs/ru/resources/openai-advanced/repo-template/docs/product-specs/new-user-onboarding.md
@@ -0,0 +1,26 @@
+# Онбординг нового пользователя
+
+## Цель
+
+Описать опыт первого запуска, который должен получить новый пользователь.
+
+## Условия входа
+
+- `[состояние перед началом потока]`
+
+## Пользовательский поток
+
+1. `[шаг один]`
+2. `[шаг два]`
+3. `[шаг три]`
+
+## Критерии приёмки
+
+- `[наблюдаемый результат]`
+- `[наблюдаемый результат]`
+- `[наблюдаемый результат]`
+
+## Состояния сбоев
+
+- `[восстановимая ошибка и обратная связь пользователю]`
+- `[заблокированное состояние и фолбэк]`
diff --git a/docs/ru/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txt b/docs/ru/resources/openai-advanced/repo-template/docs/references/design-system-reference-llms.txt
new file mode 100644
index 0000000..6f1c612
--- /dev/null
+++ b/docs/ru/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/ru/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txt b/docs/ru/resources/openai-advanced/repo-template/docs/references/nixpacks-llms.txt
new file mode 100644
index 0000000..c30cc9c
--- /dev/null
+++ b/docs/ru/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/ru/resources/openai-advanced/repo-template/docs/references/uv-llms.txt b/docs/ru/resources/openai-advanced/repo-template/docs/references/uv-llms.txt
new file mode 100644
index 0000000..f2ceba9
--- /dev/null
+++ b/docs/ru/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/ru/resources/openai-advanced/repo-template/index.md b/docs/ru/resources/openai-advanced/repo-template/index.md
new file mode 100644
index 0000000..7a94b19
--- /dev/null
+++ b/docs/ru/resources/openai-advanced/repo-template/index.md
@@ -0,0 +1,26 @@
+# Advanced Repo Template
+
+Скопируйте этот стартер в реальный репозиторий, когда вам нужна
+agent-first документационная поверхность в стиле 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/ru/resources/openai-advanced/sops/chrome-devtools-validation-loop.md b/docs/ru/resources/openai-advanced/sops/chrome-devtools-validation-loop.md
new file mode 100644
index 0000000..995cdbe
--- /dev/null
+++ b/docs/ru/resources/openai-advanced/sops/chrome-devtools-validation-loop.md
@@ -0,0 +1,51 @@
+# SOP: Цикл валидации Chrome DevTools
+
+Используйте этот SOP, когда работа с UI зависит от реального рантайм-взаимодействия и
+скриншоты, состояние DOM и вывод консоли важнее одной только инспекции кода.
+
+## Цель
+
+Превратить валидацию UI в повторяемый цикл взаимодействия, который агент может
+запускать, пока сценарий не станет чистым.
+
+## Основной цикл
+
+1. Выберите целевую страницу или экземпляр приложения.
+2. Очистите устаревший шум в консоли.
+3. Зафиксируйте состояние ДО.
+4. Триггерните UI-путь.
+5. Наблюдайте за рантайм-событиями во время взаимодействия.
+6. Зафиксируйте состояние ПОСЛЕ.
+7. Примените исправление и при необходимости перезапустите приложение.
+8. Повторяйте валидацию, пока сценарий не станет чистым.
+
+## Обязательные входы
+
+- стабильная команда запуска
+- воспроизводимый UI-сценарий
+- способ сделать снимок DOM, консоли или скриншоты
+- правило, что считается «чистым»
+
+## SOP исполнения
+
+1. Запишите целевой сценарий в активный план.
+2. Определите успех в наблюдаемых терминах: текст присутствует, кнопка активна, ошибка ушла,
+ консоль чистая, запрос успешен.
+3. Сделайте снимок начального состояния перед взаимодействием.
+4. Триггерьте ровно один путь за раз.
+5. Записывайте рантайм-события, изменения DOM и видимый вывод.
+6. Если сценарий падает, чините наименьший ответственный слой и перезапускайте.
+7. Перезапустите тот же путь и сравните доказательства ДО/ПОСЛЕ.
+
+## Критерии чистоты
+
+- задуманное видимое состояние присутствует
+- неожиданных ошибок нет
+- шум в консоли понят или очищен
+- повторный прогон того же пути даёт тот же результат
+
+## Артефакты репозитория для обновления
+
+- активный exec plan
+- `docs/RELIABILITY.md`, если сценарий стал golden path
+- продуктовая спецификация, если изменилось видимое поведение
diff --git a/docs/ru/resources/openai-advanced/sops/encode-knowledge-into-repo.md b/docs/ru/resources/openai-advanced/sops/encode-knowledge-into-repo.md
new file mode 100644
index 0000000..e2da3db
--- /dev/null
+++ b/docs/ru/resources/openai-advanced/sops/encode-knowledge-into-repo.md
@@ -0,0 +1,45 @@
+# 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. Удаляйте или помечайте как deprecated устаревшие копии, чтобы в репозитории сохранялась одна обнаруживаемая истина.
+
+## Правила хорошего кодирования
+
+- Пишите ради обнаруживаемости, а не литературной полноты.
+- Предпочитайте короткие документы с понятными именами файлов.
+- Связывайте родственные артефакты между собой.
+- Храните долговечные правила, а не транскрипты встреч.
+- Обновляйте репозиторий в той же сессии, в которой принято решение.
+
+## Definition Of Done
+
+- Свежий агент может обнаружить нужное правило, не спрашивая человека.
+- Один и тот же факт не разбросан по нескольким противоречивым файлам.
+- Новый артефакт живёт рядом с кодом или процессом, которым он управляет.
diff --git a/docs/ru/resources/openai-advanced/sops/index.md b/docs/ru/resources/openai-advanced/sops/index.md
new file mode 100644
index 0000000..06300a8
--- /dev/null
+++ b/docs/ru/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/ru/resources/openai-advanced/sops/layered-domain-architecture.md b/docs/ru/resources/openai-advanced/sops/layered-domain-architecture.md
new file mode 100644
index 0000000..239bf9e
--- /dev/null
+++ b/docs/ru/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. Обновите скоринг качества после изменения.
+
+## Definition Of Done
+
+- Свежий агент может сказать, какому слою принадлежит изменение.
+- UI-код больше не лезет напрямую в репозиторий или внешние сайд-эффекты.
+- У сквозных сущностей есть именованные точки входа.
+- Хотя бы одна важная граница соблюдается механически.
+
+## Артефакты репозитория для обновления
+
+- `ARCHITECTURE.md`
+- `docs/QUALITY_SCORE.md`
+- `docs/design-docs/`, когда изменилась обосновывающая логика
+- `docs/PLANS.md` или активный exec plan
diff --git a/docs/ru/resources/openai-advanced/sops/observability-feedback-loop.md b/docs/ru/resources/openai-advanced/sops/observability-feedback-loop.md
new file mode 100644
index 0000000..09c501b
--- /dev/null
+++ b/docs/ru/resources/openai-advanced/sops/observability-feedback-loop.md
@@ -0,0 +1,44 @@
+# SOP: Observability Feedback Loop
+
+Используйте этот SOP, когда отладка идёт медленно, агенты постоянно заявляют об успехе без
+доказательств, или поведение в рантайме сложнее инспектировать, чем сам код.
+
+## Цель
+
+Дать агенту локальный feedback-loop по логам, метрикам, трейсам и запускаемой
+нагрузке, чтобы он мог рассуждать от исполнения, а не только от инспекции кода.
+
+## Минимальный стек
+
+- приложение эмитит структурированные логи
+- приложение эмитит метрики и трейсы, когда возможно
+- локальный fan-out или collection-слой
+- интерфейсы запросов для логов, метрик и трейсов
+- повторяемая нагрузка или пользовательский сценарий, который можно перезапустить после каждого изменения
+
+## SOP исполнения
+
+1. Определите golden рантайм-сценарии, которые важнее всего.
+2. Добавьте структурированные логи на запуск и критический путь.
+3. Добавьте метрики для латентности, числа сбоев или глубины очереди, где это полезно.
+4. Добавьте трейсы или временны́е маркеры для медленных или многошаговых потоков.
+5. Сделайте сигналы запрашиваемыми из локального dev-окружения.
+6. Дайте агенту одну повторяемую нагрузку или сценарий для перезапуска.
+7. Требуйте цикл: запрос -> корреляция -> рассуждение -> реализация -> перезапуск ->
+ повтор -> верификация.
+
+## Чеклист сессии отладки
+
+- Что упало?
+- Какой сигнал доказывает сбой?
+- Какому слою принадлежит сбой?
+- Что изменилось после исправления?
+- Чисто ли перезапустилось приложение?
+- Прошла ли та же нагрузка после повторного запуска?
+
+## Definition Of Done
+
+- Агент может объяснить режим сбоя по рантайм-доказательствам.
+- Одну и ту же нагрузку можно перезапустить после каждого изменения.
+- Перезапуск и повторный прогон — часть обычного цикла задачи.
+- Сигналы надёжности задокументированы в `docs/RELIABILITY.md`.
diff --git a/docs/ru/resources/reference/coding-agent-startup-flow.md b/docs/ru/resources/reference/coding-agent-startup-flow.md
new file mode 100644
index 0000000..8997b24
--- /dev/null
+++ b/docs/ru/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. Прогоните базовый smoke- или end-to-end-путь.
+7. Если базовая верификация сломана, в первую очередь чините её.
+8. Выберите незавершённую фичу с самым высоким приоритетом.
+9. Работайте только над этой фичей, пока она не будет верифицирована или явно заблокирована.
+
+## Почему этот порядок важен
+
+- `pwd` предотвращает случайную работу в неправильной директории.
+- Файлы прогресса и фич восстанавливают долговечное состояние до начала новых правок.
+- Последние коммиты объясняют, что изменилось последним.
+- `init.sh` стандартизирует старт вместо того, чтобы полагаться на память.
+- Базовая верификация ловит сломанные стартовые состояния, прежде чем новая работа их замаскирует.
+
+## Зеркало конца сессии
+
+Та же сессия должна заканчиваться:
+
+1. фиксацией прогресса
+2. обновлением состояния фич
+3. написанием handoff, если нужно
+4. коммитом безопасной работы
+5. оставлением чистого пути рестарта
diff --git a/docs/ru/resources/reference/index.md b/docs/ru/resources/reference/index.md
new file mode 100644
index 0000000..cad319b
--- /dev/null
+++ b/docs/ru/resources/reference/index.md
@@ -0,0 +1,17 @@
+# Английский референс
+
+Эти заметки объясняют, как использовать шаблоны как рабочий 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): как держать корневые инструкции острыми, не делая их раздутыми и хрупкими
+
+## Рекомендуемый порядок чтения
+
+1. `method-map.md`
+2. `initializer-agent-playbook.md`
+3. `coding-agent-startup-flow.md`
+4. `prompt-calibration.md`
diff --git a/docs/ru/resources/reference/initializer-agent-playbook.md b/docs/ru/resources/reference/initializer-agent-playbook.md
new file mode 100644
index 0000000..b1359df
--- /dev/null
+++ b/docs/ru/resources/reference/initializer-agent-playbook.md
@@ -0,0 +1,35 @@
+# Playbook агента-инициализатора
+
+Используйте этот playbook для первой серьёзной сессии в репозитории, до того как начнётся инкрементальная работа над фичами.
+
+## Цель
+
+Создать стабильную операционную поверхность, чтобы последующие сессии могли реализовывать поведение, не выводя заново стартовые команды, текущий статус или границы задач.
+
+## Обязательные результаты
+
+Инициализатор должен оставить как минимум эти артефакты:
+
+- корневой файл инструкций — например, `AGENTS.md` или `CLAUDE.md`
+- машиночитаемая поверхность фич — например, `feature_list.json`
+- долговечный артефакт прогресса — например, `claude-progress.md`
+- стандартный хелпер старта — например, `init.sh`
+- начальный безопасный коммит, фиксирующий базовый каркас
+
+## Чек-лист
+
+1. Определите стандартный путь старта.
+2. Определите стандартный путь верификации.
+3. Создайте лог прогресса и зафиксируйте начальное состояние.
+4. Разложите работу на явные фичи со статусами.
+5. Сделайте первый чистый baseline-коммит.
+
+## Тест успеха
+
+Свежая сессия без предыдущего контекста чата должна уметь ответить:
+
+- что делает этот репозиторий
+- как его запустить
+- как его верифицировать
+- что не закончено
+- какой следующий лучший шаг
diff --git a/docs/ru/resources/reference/method-map.md b/docs/ru/resources/reference/method-map.md
new file mode 100644
index 0000000..8e76ce6
--- /dev/null
+++ b/docs/ru/resources/reference/method-map.md
@@ -0,0 +1,16 @@
+# Карта методов
+
+Эта таблица сопоставляет самые распространённые режимы отказа в долгих задачах агента-кодера с артефактом или операционным правилом, которое обычно решает их первым.
+
+| Режим отказа | Как это выглядит на практике | Первичный фикс | Поддерживающий артефакт |
+| --- | --- | --- | --- |
+| Cold-start confusion | Новая сессия тратит большую часть времени на повторное выяснение сетапа и статуса | Сделайте репозиторий системой учёта | `claude-progress.md` |
+| Scope sprawl | Агент начинает несколько фич и ни одну из них не доводит до чистого конца | Ограничьте активный скоуп | `feature_list.json` |
+| Premature completion | Агент заявляет о done после правок кода, но до runnable-доказательства | Привяжите завершение к доказательствам | `clean-state-checklist.md` |
+| Fragile startup | Каждая сессия заново учится, как поднимать проект | Стандартизируйте сетап и верификацию | `init.sh` |
+| Weak handoff | Следующая сессия не может понять, что верифицировано, что сломано и что дальше | Заканчивайте явным handoff | `session-handoff.md` |
+| Subjective review | Качество ревью зависит от вкуса или памяти | Оценивайте вывод по фиксированным категориям | `evaluator-rubric.md` |
+
+## Операционный принцип
+
+Добавляйте наименьший артефакт, который напрямую адресует наблюдаемый режим отказа. Не пытайтесь решить любую проблему надёжности, сваливая всё больше текста в один глобальный файл инструкций.
diff --git a/docs/ru/resources/reference/prompt-calibration.md b/docs/ru/resources/reference/prompt-calibration.md
new file mode 100644
index 0000000..d9e131b
--- /dev/null
+++ b/docs/ru/resources/reference/prompt-calibration.md
@@ -0,0 +1,23 @@
+# Калибровка промпта
+
+Корневые инструкции должны задавать операционный фрейм, а не каждое возможное действие.
+
+## Держите в корневом файле
+
+- цель и скоуп репозитория
+- путь старта
+- путь верификации
+- неподлежащие обсуждению ограничения
+- обязательные артефакты состояния
+- правила окончания сессии
+
+## Уберите из корневого файла
+
+- длинные исторические edge-кейсы
+- детали реализации, специфичные для тем
+- локальные архитектурные заметки, которым место рядом с кодом
+- примеры, применимые только к одной подсистеме
+
+## Рабочее правило
+
+Корневой файл должен помогать свежей сессии быстро сориентироваться. Если файл превращается в свалку каждого прошлого провала, вынесите детали в более мелкие документы и оставьте на них ссылки.
diff --git a/docs/ru/resources/templates/AGENTS.md b/docs/ru/resources/templates/AGENTS.md
new file mode 100644
index 0000000..9fcb4d6
--- /dev/null
+++ b/docs/ru/resources/templates/AGENTS.md
@@ -0,0 +1,50 @@
+# AGENTS.md
+
+Этот репозиторий рассчитан на длительную работу с агентом-кодером. Цель — не максимизировать сырой объём кода. Цель — оставить репозиторий в состоянии, в котором следующая сессия сможет продолжить, не гадая.
+
+## Стартовый воркфлоу
+
+Перед написанием кода:
+
+1. Подтвердите рабочую директорию командой `pwd`.
+2. Прочитайте `claude-progress.md`, чтобы узнать последнее проверенное состояние и следующий шаг.
+3. Прочитайте `feature_list.json` и выберите незавершённую фичу с самым высоким приоритетом.
+4. Просмотрите последние коммиты: `git log --oneline -5`.
+5. Запустите `./init.sh`.
+6. Перед началом новой работы выполните требуемую smoke- или end-to-end-верификацию.
+
+Если базовая верификация уже падает, в первую очередь чините именно её. Не наслаивайте новую работу над фичей поверх сломанного стартового состояния.
+
+## Рабочие правила
+
+- Работайте над одной фичей за раз.
+- Не помечайте фичу как завершённую только потому, что был добавлен код.
+- Удерживайте изменения внутри скоупа выбранной фичи, если только блокер не вынуждает сделать узкий вспомогательный фикс.
+- Не меняйте втихую правила верификации в процессе реализации.
+- Предпочитайте долговечные артефакты репозитория сводкам в чате.
+
+## Обязательные артефакты
+
+- `feature_list.json`: источник истины о состоянии фич
+- `claude-progress.md`: лог сессии и текущий проверенный статус
+- `init.sh`: стандартный путь старта и верификации
+- `session-handoff.md`: опциональный компактный handoff для крупных сессий
+
+## Definition Of Done
+
+Фича считается завершённой только когда выполнено всё следующее:
+
+- целевое поведение реализовано
+- требуемая верификация реально была запущена
+- доказательство зафиксировано в `feature_list.json` или `claude-progress.md`
+- репозиторий по-прежнему перезапускаем по стандартному стартовому пути
+
+## Окончание сессии
+
+Перед завершением сессии:
+
+1. Обновите `claude-progress.md`.
+2. Обновите `feature_list.json`.
+3. Запишите все нерешённые риски или блокеры.
+4. Закоммитьте с описательным сообщением, как только работа в безопасном состоянии.
+5. Оставьте репозиторий достаточно чистым, чтобы следующая сессия могла сразу запустить `./init.sh`.
diff --git a/docs/ru/resources/templates/CLAUDE.md b/docs/ru/resources/templates/CLAUDE.md
new file mode 100644
index 0000000..e7169ba
--- /dev/null
+++ b/docs/ru/resources/templates/CLAUDE.md
@@ -0,0 +1,43 @@
+# CLAUDE.md
+
+Вы работаете в репозитории, спроектированном под длительную работу по реализации. Ставьте надёжное завершение, непрерывность между сессиями и явную верификацию выше скорости.
+
+## Операционный цикл
+
+В начале каждой сессии:
+
+1. Запустите `pwd` и убедитесь, что вы в ожидаемом корне репозитория.
+2. Прочитайте `claude-progress.md`.
+3. Прочитайте `feature_list.json`.
+4. Просмотрите последние коммиты: `git log --oneline -5`.
+5. Запустите `./init.sh`.
+6. Проверьте, не сломан ли уже базовый smoke- или end-to-end-путь.
+
+Затем выберите ровно одну незавершённую фичу и работайте только над ней, пока не верифицируете её или не задокументируете причину блокировки.
+
+## Правила
+
+- Одна активная фича за раз.
+- Не заявляйте о завершении без runnable-доказательств.
+- Не переписывайте список фич, чтобы скрыть незавершённую работу.
+- Не удаляйте и не ослабляйте тесты только ради того, чтобы задача выглядела завершённой.
+- Используйте артефакты репозитория как систему учёта.
+
+## Обязательные файлы
+
+- `feature_list.json`
+- `claude-progress.md`
+- `init.sh`
+- `session-handoff.md`, когда полезен компактный handoff
+
+## Шлюз завершения
+
+Фича может перейти в `passing` только после того, как требуемая верификация прошла успешно и результат зафиксирован.
+
+## Перед остановкой
+
+1. Обновите лог прогресса.
+2. Обновите состояние фич.
+3. Запишите, что ещё сломано или не верифицировано.
+4. Закоммитьте, как только репозиторий безопасно возобновляем.
+5. Оставьте чистый путь рестарта для следующей сессии.
diff --git a/docs/ru/resources/templates/claude-progress.md b/docs/ru/resources/templates/claude-progress.md
new file mode 100644
index 0000000..93bc723
--- /dev/null
+++ b/docs/ru/resources/templates/claude-progress.md
@@ -0,0 +1,35 @@
+# Лог прогресса
+
+## Текущее проверенное состояние
+
+- Корень репозитория:
+- Стандартный путь старта:
+- Стандартный путь верификации:
+- Текущая незавершённая фича с наивысшим приоритетом:
+- Текущий блокер:
+
+## Лог сессий
+
+### Сессия 001
+
+- Дата:
+- Цель:
+- Сделано:
+- Запущенная верификация:
+- Зафиксированные доказательства:
+- Коммиты:
+- Обновлённые файлы или артефакты:
+- Известный риск или нерешённая проблема:
+- Следующий лучший шаг:
+
+### Сессия 002
+
+- Дата:
+- Цель:
+- Сделано:
+- Запущенная верификация:
+- Зафиксированные доказательства:
+- Коммиты:
+- Обновлённые файлы или артефакты:
+- Известный риск или нерешённая проблема:
+- Следующий лучший шаг:
diff --git a/docs/ru/resources/templates/clean-state-checklist.md b/docs/ru/resources/templates/clean-state-checklist.md
new file mode 100644
index 0000000..4ddfd84
--- /dev/null
+++ b/docs/ru/resources/templates/clean-state-checklist.md
@@ -0,0 +1,8 @@
+# Чек-лист чистого состояния
+
+- [ ] Стандартный путь старта по-прежнему работает.
+- [ ] Стандартный путь верификации по-прежнему запускается.
+- [ ] Текущий прогресс зафиксирован в логе прогресса.
+- [ ] Состояние фич отражает то, что реально проходит, против того, что не верифицировано.
+- [ ] Не осталось незадокументированных недоделанных шагов.
+- [ ] Следующая сессия может продолжить без ручного ремонта.
diff --git a/docs/ru/resources/templates/evaluator-rubric.md b/docs/ru/resources/templates/evaluator-rubric.md
new file mode 100644
index 0000000..76e3231
--- /dev/null
+++ b/docs/ru/resources/templates/evaluator-rubric.md
@@ -0,0 +1,24 @@
+# Рубрика evaluator
+
+Используйте эту рубрику после реализации и перед окончательным принятием.
+
+| Категория | Вопрос | Балл (0-2) | Заметки |
+| --- | --- | --- | --- |
+| Correctness | Соответствует ли реализованное поведение запрошенной фиче? | | |
+| Verification | Реально ли были запущены требуемые проверки, с доказательствами? | | |
+| Scope discipline | Оставалась ли сессия в рамках выбранного скоупа фичи? | | |
+| Reliability | Переживает ли результат перезапуск или повторный прогон без ремонта? | | |
+| Maintainability | Достаточно ли понятны код и документация для следующей сессии? | | |
+| Handoff readiness | Может ли свежая сессия продолжить работу только по артефактам репозитория? | | |
+
+## Вердикт
+
+- Accept
+- Revise
+- Block
+
+## Требуемые действия
+
+- Отсутствующие доказательства:
+- Требуемые фиксы:
+- Триггер следующего ревью:
diff --git a/docs/ru/resources/templates/feature_list.json b/docs/ru/resources/templates/feature_list.json
new file mode 100644
index 0000000..138adc6
--- /dev/null
+++ b/docs/ru/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/ru/resources/templates/index.md b/docs/ru/resources/templates/index.md
new file mode 100644
index 0000000..7314b27
--- /dev/null
+++ b/docs/ru/resources/templates/index.md
@@ -0,0 +1,226 @@
+# Гайд по шаблонам
+
+Эти шаблоны готовы к копированию в ваш проект. Каждый из них служит конкретной цели в воркфлоу агента. Редактируйте содержимое, чтобы оно соответствовало командам, путям, именам фич и шагам верификации вашего проекта.
+
+## Как начать
+
+Сначала скопируйте эти четыре файла в корень вашего проекта:
+
+1. `AGENTS.md` или `CLAUDE.md`
+2. `init.sh`
+3. `claude-progress.md`
+4. `feature_list.json`
+
+Добавляйте остальные файлы по мере роста проекта.
+
+---
+
+## AGENTS.md
+
+Корневой файл инструкций. Это первое, что читает агент в начале сессии. Он задаёт операционные правила: что делать перед написанием кода, как работать и как заканчивать.
+
+**Как использовать:**
+
+- Скопируйте в корневую директорию проекта
+- Замените шаги стартового воркфлоу на реальные пути и команды вашего проекта
+- Настройте рабочие правила под конвенции вашей команды
+- Сохраните секцию definition of done — это самая важная часть
+
+**Что он делает для агента:**
+
+- Заставляет читать прогресс и состояние фич перед началом работы
+- Требует работать над одной фичей за раз
+- Требует доказательства, прежде чем что-либо помечать как done
+- Определяет, как выглядит чистое окончание сессии
+
+Используйте `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
+
+Лог прогресса. Каждая сессия пишет в этот файл, и каждая новая сессия читает его первым делом.
+
+**Как использовать:**
+
+- Скопируйте в корень проекта
+- Заполните секцию «Current Verified State» информацией о вашем проекте
+- После каждой сессии обновляйте запись о сессии
+
+**Что значит каждое поле:**
+
+- **Current Verified State** — единственный источник истины о том, в каком состоянии проект
+ - `Repository root directory` — где живёт проект
+ - `Standard startup path` — команда для запуска проекта
+ - `Standard verification path` — команда для запуска тестов
+ - `Highest priority unfinished feature` — над чем должна работать следующая сессия
+ - `Current blocker` — всё, что застопорилось
+- **Session Record** — одна запись на сессию
+ - `Goal` — что вы планировали сделать
+ - `Completed` — что реально было сделано
+ - `Verification run` — какие тесты были запущены
+ - `Evidence recorded` — какие доказательства были зафиксированы
+ - `Commits` — что было закоммичено
+ - `Known risks` — что может быть сломано
+ - `Next best action` — с чего должна начать следующая сессия
+
+## 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
+
+Компактная заметка-передача между сессиями. Используйте её, когда сессия заканчивается, и вы хотите, чтобы следующая быстро подхватила работу.
+
+**Как использовать:**
+
+- Скопируйте в корень проекта
+- Заполняйте в конце каждой сессии (или попросите агента заполнить)
+
+**Что покрывает каждая секция:**
+
+- **Currently verified** — что подтверждённо работает и какая верификация была запущена
+- **Changes this session** — что изменилось в коде или инфраструктуре
+- **Still broken or unverified** — известные проблемы и рискованные участки
+- **Next best action** — что должна сделать следующая сессия и чего не трогать
+- **Commands** — команды старта, верификации и отладки для быстрого доступа
+
+Этот файл опционален для коротких сессий. Он становится важным, когда сессии длинные или когда у проекта несколько активных областей.
+
+## clean-state-checklist.md
+
+Чек-лист, который нужно пройти перед окончанием каждой сессии. Гарантирует, что репозиторий в хорошем состоянии для чистого старта следующей сессии.
+
+**Как использовать:**
+
+- Скопируйте в корень проекта
+- Пройдитесь по нему перед тем, как закрыть сессию
+- Агент тоже должен проверять эти пункты как часть своей end-of-session рутины
+
+**Что он проверяет:**
+
+- Стандартный старт всё ещё работает
+- Стандартная верификация всё ещё запускается
+- Лог прогресса обновлён
+- Список фич отражает реальное состояние (нет ложных записей `passing`)
+- Никаких незаписанных недоделанных шагов
+- Следующая сессия может продолжить без ручного ремонта
+
+## evaluator-rubric.md
+
+Оценочный лист для ревью качества вывода агента. Используйте после сессии или на майлстоунах проекта, чтобы оценить, дотягивает ли работа до планки.
+
+**Как использовать:**
+
+- Скопируйте в корень проекта
+- После сессии (или набора сессий) оценивайте работу агента по шести измерениям
+- Каждое измерение оценивается 0–2
+
+**Шесть измерений:**
+
+1. **Correctness** — соответствует ли реализация целевому поведению?
+2. **Verification** — реально ли были запущены требуемые проверки, с доказательствами?
+3. **Scope discipline** — оставался ли агент в рамках выбранной фичи?
+4. **Reliability** — переживает ли результат перезапуск или повторный прогон?
+5. **Maintainability** — достаточно ли понятны код и документация для следующей сессии?
+6. **Handoff readiness** — может ли новая сессия продолжить, опираясь только на артефакты репозитория?
+
+**Варианты заключения:**
+
+- Accept — соответствует планке
+- Revise — нужны фиксы перед принятием
+- Block — фундаментальные проблемы, которые надо решать в первую очередь
+
+**Важно: evaluator нужно калибровать.** «Из коробки» агенты — плохие судьи самих себя: они выявляют проблемы, а потом уговаривают себя одобрить. Вам придётся итерировать:
+
+1. Запустите evaluator на завершённом спринте.
+2. Сравните его оценки с собственным человеческим суждением.
+3. Где они расходятся — сделайте рубрику конкретнее по критериям pass/fail.
+4. Перезапустите и проверьте сходимость.
+5. Повторяйте, пока evaluator не начнёт стабильно совпадать с человеческим ревью.
+
+Закладывайте 3–5 раундов калибровки. Записывайте каждое изменение, чтобы отслеживать, что улучшило сходимость.
+
+## quality-document.md
+
+Снимок качества, оценивающий каждый продуктовый домен и архитектурный слой вашего проекта. Отслеживает здоровье кодовой базы во времени, а не только вывод отдельной сессии.
+
+**Как использовать:**
+
+- Скопируйте в корень проекта
+- Перед началом сессии: прочитайте, чтобы понять, где кодовая база слабее всего
+- После сессии: обновите оценки на основе того, что изменилось
+- Со временем: сравнивайте снимки, чтобы увидеть, какие изменения harness реально улучшили здоровье кодовой базы
+
+**Что он оценивает:**
+
+- **Продуктовые домены** (например, импорт документов, Q&A-флоу, индексация): каждому домену ставится оценка (A–D) по статусу верификации, читаемости для агента, стабильности тестов и ключевым пробелам
+- **Архитектурные слои** (например, main process, preload, renderer, services): каждому слою ставится оценка за соблюдение границ и читаемость для агента
+
+**Почему это важно:**
+
+Рубрика evaluator оценивает отдельные выводы агента. Quality-документ оценивает саму кодовую базу. Они отвечают на разные вопросы:
+
+- Рубрика evaluator: «Хорошо ли агент сработал в этой сессии?»
+- Quality-документ: «Проект становится сильнее или слабее со временем?»
+
+**Когда обновлять:**
+
+- После каждой значимой сессии
+- Перед сравнениями бенчмарков
+- После проходов по уборке или упрощению
+- При онбординге нового агента или модели в проект
+
+**Связь с упрощением harness:**
+
+Quality-документ также поддерживает упрощение harness. Каждый компонент harness кодирует предположение о том, чего модель не умеет. По мере улучшения моделей эти предположения устаревают. Чтобы проверить, нужен ли компонент:
+
+1. Сделайте снимок quality-документа.
+2. Удалите один компонент harness.
+3. Прогоните набор бенчмарк-задач.
+4. Сделайте ещё один снимок.
+5. Сравните — если оценки не упали, компонент был излишним. Если упали — верните его обратно.
diff --git a/docs/ru/resources/templates/init.sh b/docs/ru/resources/templates/init.sh
new file mode 100755
index 0000000..d7522d6
--- /dev/null
+++ b/docs/ru/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/ru/resources/templates/quality-document.md b/docs/ru/resources/templates/quality-document.md
new file mode 100644
index 0000000..502f615
--- /dev/null
+++ b/docs/ru/resources/templates/quality-document.md
@@ -0,0 +1,43 @@
+# Quality-документ
+
+Снимок качества для каждого продуктового домена и архитектурного слоя. Как агенты, так и люди могут использовать этот документ, чтобы быстро понять, где кодовая база сильна, а где требует работы.
+
+**Частота обновления:** после каждой значимой сессии или перед началом новой фазы работы.
+
+**Шкала оценок:**
+
+- **A**: вся верификация проходит, чистая архитектура, читаемо для агента, стабильные тесты
+- **B**: верификация проходит, в основном чисто, незначительные пробелы в читаемости или покрытии тестами
+- **C**: частично работает, известные пробелы, некоторые участки кода трудны для понимания агентом
+- **D**: не работает или серьёзные структурные проблемы
+
+---
+
+## Продуктовые домены
+
+| Домен | Оценка | Верификация | Читаемость для агента | Стабильность тестов | Ключевые пробелы | Последнее обновление |
+|--------|-------|-------------|-----------------|---------------|----------|-------------|
+| Импорт документов | - | - | - | - | - | - |
+| Управление документами | - | - | - | - | - | - |
+| Индексация документов | - | - | - | - | - | - |
+| Q&A-флоу | - | - | - | - | - | - |
+| Обоснованные ответы | - | - | - | - | - | - |
+
+## Архитектурные слои
+
+| Слой | Оценка | Соблюдение границ | Читаемость для агента | Ключевые пробелы | Последнее обновление |
+|-------|-------|---------------------|-----------------|----------|-------------|
+| Main Process | - | - | - | - | - |
+| Preload | - | - | - | - | - |
+| Renderer | - | - | - | - | - |
+| Services | - | - | - | - | - |
+
+## История изменений
+
+### YYYY-MM-DD
+
+- Изменения:
+- Повышенные домены:
+- Понижены:
+- Новые выявленные пробелы:
+- Закрытые пробелы:
diff --git a/docs/ru/resources/templates/session-handoff.md b/docs/ru/resources/templates/session-handoff.md
new file mode 100644
index 0000000..5753589
--- /dev/null
+++ b/docs/ru/resources/templates/session-handoff.md
@@ -0,0 +1,30 @@
+# Session Handoff
+
+## Проверено сейчас
+
+- Что сейчас работает:
+- Какая верификация реально была запущена:
+
+## Изменено в этой сессии
+
+- Добавленный код или поведение:
+- Изменения в инфраструктуре или harness:
+
+## Сломано или не верифицировано
+
+- Известный дефект:
+- Не верифицированный путь:
+- Риск для следующей сессии:
+
+## Следующий лучший шаг
+
+- Незавершённая фича с наивысшим приоритетом:
+- Почему именно она следующая:
+- Что считается прохождением:
+- Что нельзя менять во время этого шага:
+
+## Команды
+
+- Старт:
+- Верификация:
+- Точечная команда отладки:
diff --git a/docs/ru/skills/index.md b/docs/ru/skills/index.md
new file mode 100644
index 0000000..a374c44
--- /dev/null
+++ b/docs/ru/skills/index.md
@@ -0,0 +1,49 @@
+# Skills
+
+Эта директория содержит встроенные скилы AI-агентов, которые поставляются с курсом. Скилы — это самодостаточные шаблоны промптов, которые могут быть загружены AI-агентами для написания кода (Claude Code, Codex, Cursor, Windsurf и т. д.) для выполнения специализированных задач.
+
+## harness-creator
+
+Production-grade скил по harness-инжинирингу для AI-агентов. Помогает создавать, оценивать и улучшать пять ключевых подсистем harness: инструкции, состояние, верификация, скоуп и жизненный цикл сессии.
+
+### Что он делает
+
+- **Создаёт harness с нуля** — AGENTS.md, списки фич, флоу верификации
+- **Улучшает существующие harness** — оценка по пяти подсистемам с приоритизированными улучшениями
+- **Проектирует непрерывность сессий** — персистентность памяти, отслеживание прогресса, процедуры handoff
+- **Применяет production-паттерны** — память, контекст-инжиниринг, безопасность инструментов, координация мульти-агентов
+
+### Быстрый старт
+
+Файлы скила лежат в репозитории по пути [`skills/harness-creator/`](https://github.com/walkinglabs/learn-harness-engineering/tree/main/skills/harness-creator).
+
+Чтобы использовать его с Claude Code, скопируйте директорию `harness-creator/` в путь скилов вашего проекта или направьте агент на файл SKILL.md.
+
+### Референсные паттерны
+
+Скил включает 6 углублённых референсных документов:
+
+| Паттерн | Когда применять |
+|---------|-------------|
+| Memory Persistence | Агент забывает между сессиями |
+| Context Engineering | Управление бюджетом контекста, JIT-загрузка |
+| Tool Registry | Безопасность инструментов, контроль конкурентности |
+| Multi-Agent Coordination | Параллелизм, флоу со специализацией |
+| Lifecycle & Bootstrap | Хуки, фоновые задачи, инициализация |
+| Gotchas | 15 неочевидных режимов отказа с фиксами |
+
+### Шаблоны
+
+Скил содержит готовые к использованию шаблоны:
+
+- `agents.md` — каркас AGENTS.md с рабочими правилами
+- `feature-list.json` — JSON Schema + пример списка фич
+- `init.sh` — стандартный инициализационный скрипт
+- `progress.md` — шаблон лога прогресса сессии
+
+### Как был построен этот скил
+
+`harness-creator` был разработан с использованием методологии **skill-creator** — официальной мета-скила Anthropic для создания, тестирования и итерации над скилами агентов. skill-creator предоставляет структурированный воркфлоу (draft → test → evaluate → iterate) со встроенными eval-runner'ами, грейдерами и средством просмотра бенчмарков.
+
+- **Исходник skill-creator**: [anthropics/skills — skill-creator](https://github.com/anthropics/skills/tree/main/skills/skill-creator)
+- **Документация по скилам Claude Code**: [anthropics/claude-code — plugin-dev/skills](https://github.com/anthropics/claude-code/tree/main/plugins/plugin-dev/skills)