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…

What is this?A complete course (written in Russian) on harness engineering: how to design the system around an AI coding agent - instructions, tools, environment, state and verification - so it writes code reliably.
Is this a course, a tool, or a library?It is a course, not a software library: 11 theory blocks, 14 modules, 8 hands-on projects, 14 labs, 60 problems with solutions, plus an executable test suite and a library of ready templates.
How do I get started with it?Start with the 30-minute quick start, before any theory: add an AGENTS.md (50-150 lines), a featurelist.json and a PROGRESS.md to your repo, plus one 'make check' command that returns green or red.
What do I need to know before taking it?Git, the command line, and some hands-on experience with at least one coding agent. Machine learning knowledge is not required at all.
Is this about the Harness.io CI/CD platform?No - despite the constant name confusion, it is not about the commercial Harness.io CI/CD platform; it covers harness engineering for AI coding agents. Note also that the material is written entirely in Russian.
Who is this course for?Developers whose coding agents give unstable results, those who want an agent to work for hours across sessions without supervision, and people building internal tooling or platforms around agents.
What exactly is a 'harness'?Everything outside the model weights that determines how much of its capability actually shows up in your project: instruction files (AGENTS.md, CLAUDE.md, .cursorrules, skills), available tools (shell, tests, linter, browser, MCP), the runtime environment, session state, and feedback loops such as verification commands and E2E tests.
Why does the course say upgrading the model is usually the wrong fix?Its core thesis is that model capability and execution reliability are two different things: the same model in a bare environment and in a well-built harness gives very different results, so upgrading the model is the most expensive and usually least effective way to fix an agent.
How do I check that my harness actually works?The course offers a cold-start test: open a fresh agent session, explain nothing verbally, and ask five questions - what the system is, how to run it, how to verify it, which rules must not be broken, and where the work currently stands. An executable harness test suite is included as well.
Creator
justxor
Size
0.4 MB
Stars
317
Updated
CommitOct 04
Age
2mo
Commits · 90 Days