Harness_ru README

The project's README from github.com/justxor/Harness_ru. As one markdown file: README.md.

Harness Engineering — полный курс на русском

harness-tests

Как заставить AI-агента писать код надёжно. Не «какую модель выбрать», а как спроектировать вокруг неё рабочую систему: инструкции, инструменты, среду, состояние и верификацию.

Курс — от нуля до продвинутых тем: теоретическая база из 11 блоков, 14 модулей, 8 практических проектов, 14 лабораторных работ, задачник из 60 задач с разборами, 13 схем, исполняемый набор тестов для вашей обвязки, диагностический протокол «как починить агента», библиотека готовых шаблонов, карта инструментов, 40 приёмов и каталог антипаттернов.

Главный тезис курса: способность модели и надёжность исполнения — это две разные вещи. Одна и та же модель в «голой» среде и в среде с продуманным harness даёт качественно разные результаты. Апгрейд модели — самый дорогой и обычно не самый эффективный способ починить агента.

Популярные ресурсы по Машинному Обучению, ИИ и анализу данных

🧠 Machine Learning — авторский Telegram-канал, который содержит всю базу для работы с ИИ-моделями. Дайджесты лучших проектов, разбор кода, инструкции по запуску LLM, подготовка к собесу и многое другое.

📚 Data Science — редкая литература, статьи, курсы и уникальные гайды для мл-специалистов любого уровня. Читайте, развивайтесь, практикуйте.

💼 Machine Interview — это база с 1900 вопросами с собеседований по машинному обучению. Вы легко получите оффер, изучив популярные вопросы.

🔥 Целая папка супер полезных ресурсов по ИИ

Оглавление

Введение

Часть 0. Теоретическая база

Часть I. Фундамент

Часть II. Состояние и время

Часть III. Скоуп и дисциплина

Часть IV. Верификация

Часть V. Эксплуатация

Часть VI. Автономия

Практика и справочники

Что такое harness

Harness (буквально «упряжь») — всё, что находится за пределами весов модели и определяет, какая часть её способностей реально проявится в вашем проекте.

Если это не веса модели — это harness:

Метафора, которая помогает: породистая лошадь без упряжи далеко не уедет. Модель — это лошадь. Harness — седло, узда, стремена и подковы. Апгрейд лошади не отменяет необходимости упряжи.

Диагностическое правило №1: когда агент сломался — сначала проверяйте harness, потом модель. Если та же модель успешно решает похожие задачи в хорошо структурированных репозиториях, проблема почти наверняка в вашей среде, а не в её способностях.

Это не Harness.io

Важное уточнение, потому что путаница возникает постоянно: Harness.io — это коммерческая CI/CD-платформа. Этот курс — не о ней. Здесь речь о harness engineering — инженерной дисциплине проектирования окружения для AI-кодинг-агентов (Claude Code, OpenAI Codex, Cursor, Gemini CLI, Aider и т. п.).

Кому нужен курс и как его проходить

Курс для вас, если вы:

Предварительные требования: git, командная строка, любой опыт с одним из кодинг-агентов. Знание ML не нужно вообще.

Три трека прохождения

Трек Время Что делать
Спринт (полдня) 3–4 ч Быстрый старт → диагностический протокол → модули 1, 2, 4, 8, 9 → лабораторные Л3, Л8, Л7, Л11
Основной (2 недели) ~20 ч Часть 0 (блоки Т1–Т5, Т7, Т8) → модули 1–12 подряд → после каждого блока соответствующий проект и связанные лабораторные
Полный (6 недель) ~60 ч Вся Часть 0 → все 14 модулей → все 8 проектов → все 14 лабораторных → собственный capstone на рабочем репозитории
Диагностика (30 минут) 0,5 ч Только протокол ремонта: подходит, если агент уже сломан и разбираться в теории некогда

Схема 1. Карта маршрута обучения

flowchart TD
    S(["Агент работает нестабильно"]) --> Q{"Сломано прямо сейчас?"}
    Q -- "да" --> D["Диагностический протокол<br/>30 минут"]
    Q -- "нет" --> B["Быстрый старт<br/>4 файла, 30 минут"]
    D --> B
    B --> T0["Часть 0<br/>теоретическая база"]
    T0 --> C1["Части I-III<br/>фундамент, состояние, скоуп"]
    C1 --> C2["Части IV-V<br/>верификация и эксплуатация"]
    C2 --> G{"Метрики стабильно зелёные?"}
    G -- "нет" --> LAB["Лабораторные Л1-Л14<br/>замеры до и после"]
    LAB --> C2
    G -- "да" --> C3["Часть VI<br/>автономия и графы"]
    C3 --> P["8 проектов + задачник"]
    P --> OWN(["Свой capstone<br/>на рабочем репозитории"])

Как учиться правильно. Каждый модуль устроен одинаково: симптом → механика → понятия → что делать → замер. Не переходите к следующему модулю, пока не сделали замер на своём проекте. Harness engineering — эмпирическая дисциплина: без цифр вы не отличите улучшение от самообмана.

Быстрый старт: минимальный harness за 30 минут

Четыре файла дают львиную долю эффекта. Сделайте их прямо сейчас, до чтения теории.

Шаг 1. AGENTS.md в корне репозитория (10 минут)

# AGENTS.md

## Проект
Backend платежей. Python 3.11, FastAPI, PostgreSQL 15, Redis 7.

## Команды
- Установка: `make setup`
- Запуск: `make dev`
- Тесты: `make test`
- Полная верификация: `make check`   # tests + types + lint

## Жёсткие ограничения (MUST)
- Все эндпоинты — только через OAuth 2.0.
- Только синтаксис SQLAlchemy 2.0 (`select()`, не `Query`).
- Все SQL — параметризованные запросы. Никогда не склеивать строки.
- Никогда не `eval()`, `exec()`, `pickle.loads()` на внешних данных.
- Нельзя менять `migrations/` без отдельного разрешения.

## Definition of Done
Фича готова = `make check` зелёный + E2E-сценарий фичи проходит.
«Код написан» — это не готово.

## Правила работы
- Одна фича за раз. Не начинать вторую, пока первая не прошла верификацию.
- Никакого рефакторинга «заодно», пока основная фича не проверена.
- Перед завершением сессии обновить `PROGRESS.md`.

## Куда смотреть подробности
- `docs/api-patterns.md` — обязательно при добавлении эндпоинта
- `docs/db-rules.md` — обязательно при изменении моделей и миграций
- `docs/testing.md` — при написании тестов

Правило: 50–150 строк, не больше. Всё остальное — в docs/.

Шаг 2. feature_list.json (7 минут)

[
  {
    "id": "F01",
    "behavior": "POST /api/cart/items с {product_id, quantity} возвращает 201 и товар в корзине",
    "verification": "pytest tests/e2e/test_cart.py::test_add_item",
    "state": "passing",
    "evidence": "commit a1b2c3d, 4 passed"
  },
  {
    "id": "F02",
    "behavior": "GET /api/cart возвращает корзину с итоговой суммой",
    "verification": "pytest tests/e2e/test_cart.py::test_get_cart",
    "state": "active",
    "evidence": null
  },
  {
    "id": "F03",
    "behavior": "POST /api/checkout создаёт заказ и очищает корзину",
    "verification": "pytest tests/e2e/test_checkout.py",
    "state": "not_started",
    "evidence": null
  }
]

Состояний ровно четыре: not_started, active, blocked, passing. Агент не имеет права ставить passing сам — только скрипт верификации.

Шаг 3. PROGRESS.md (5 минут)

# Прогресс

## Состояние на сейчас
- Коммит: a1b2c3d
- Тесты: 42/43 (падает test_pagination_empty)
- Линт/типы: чисто
- Активная фича: F02

## Сделано
- [x] F01 — добавление товара в корзину (passing)

## В работе
- [ ] F02 — получение корзины (90%, не сходится расчёт скидки)

## Заблокировано
- F05 — ждём доступ к sandbox платёжного провайдера

## Решения этой сессии
- Итоговая сумма считается на сервере, не на клиенте — клиенту нельзя доверять цены.

## Следующие шаги
1. Починить расчёт скидки в `services/cart.py:total()`
2. Прогнать `make check`
3. Начать F03

Шаг 4. make check (8 минут)

setup:
	uv sync

dev:
	uv run uvicorn app.main:app --reload

test:
	uv run pytest -x -q

types:
	uv run mypy src --strict

lint:
	uv run ruff check src

e2e:
	uv run pytest tests/e2e -q

check: lint types test e2e
	@echo "ALL CHECKS PASSED"

Одна команда, один зелёный/красный ответ. Это самая высокорентабельная часть harness.

Проверка результата: тест холодного старта

Откройте новую сессию агента, ничего не объясняйте голосом и задайте пять вопросов:

  1. Что это за система и зачем она?
  2. Как её запустить?
  3. Как её проверить (какие команды)?
  4. Какие правила нельзя нарушать?
  5. Где сейчас работа �

Harness_ru (justxor/Harness_ru)

Searching Database…

318 ·GitHub
Harness_ru
Что это такое?Полный курс (написанный на русском языке) про harness engineering: как спроектировать систему вокруг ИИ-агента для кода — инструкции, инструменты, окружение, состояние и проверку — чтобы он писал код надёжно.
Это курс, инструмент или библиотека?Это курс, а не программная библиотека: 11 теоретических блоков, 14 модулей, 8 практических проектов, 14 лабораторных работ, 60 задач с решениями, плюс исполняемый набор тестов и библиотека готовых шаблонов.
Как начать с этим работать?Начните с 30-минутного быстрого старта, ещё до всякой теории: добавьте в свой репозиторий AGENTS.md (50–150 строк), featurelist.json и PROGRESS.md, а также одну команду 'make check', которая возвращает зелёный или красный.
Что мне нужно знать перед началом?Git, командную строку и какой-никакой практический опыт хотя бы с одним агентом для кода. Знание машинного обучения вообще не требуется.
Речь про CI/CD-платформу Harness.io?Нет — несмотря на постоянную путаницу с названием, это не про коммерческую CI/CD-платформу Harness.io; курс рассказывает про harness engineering для ИИ-агентов, пишущих код. Учтите также, что материал целиком написан на русском языке.
Для кого этот курс?Для разработчиков, чьи агенты для кода выдают нестабильные результаты, для тех, кто хочет, чтобы агент работал часами в разных сессиях без присмотра, и для тех, кто строит вокруг агентов внутренние инструменты или платформы.
Что такое «harness» на самом деле?Всё, что находится вне весов модели и определяет, какая часть её способностей реально проявится в вашем проекте: файлы с инструкциями (AGENTS.md, CLAUDE.md, .cursorrules, skills), доступные инструменты (shell, тесты, линтер, браузер, MCP), среда выполнения, состояние сессии и обратные связи вроде команд проверки и E2E-тестов.
Почему в курсе говорится, что смена модели на новую — обычно неверное решение?Его главная мысль в том, что способности модели и надёжность её работы — две разные вещи: одна и та же модель в голом окружении и в хорошо построенном harness даёт очень разные результаты, поэтому обновление модели — самый дорогой и обычно наименее действенный способ починить агента.
Как мне убедиться, что мой harness действительно работает?В курсе предлагается тест на холодный старт: откройте новую сессию агента, ничего не объясняйте словами и задайте пять вопросов — что это за система, как её запустить, как проверить, какие правила нельзя нарушать и на каком этапе сейчас работа. Также в комплекте идёт исполняемый набор тестов для harness.
What are similar projects?learn-harness-engineering, vibe-coding-cn, superpowers-zh, skills, agency-agents, hello-agents, Orbital, advanced-context-engineering-for-coding-agents
Which topics is it in?graph-engineering, e2e-testing, agentic-coding, state-management, gemini-cli, context-engineering, curriculum, best-practices, course, coding-agents, prompt-engineering, shell
Creator
justxor
Size
0.4 MB
Stars
318
Updated
CommitOct 04
Age
2mo
Commits · 90 Days