Архитектура Harness

Три слоя с разной ответственностью

HARNESS / PROTOCOL
AGENTS + skills + commands + CTS + execution status + policies
             ↓
PROJECT KNOWLEDGE BASE
PROJECT + REQ + ADR + architecture + planning
             ↓
IMPLEMENTATION
code + tests + migrations + runtime config

Harness — слой процесса, а не фреймворк приложения. Каталоги реализации продукта намеренно отсутствуют в шаблоне до PROJECT INIT и реальных STEP.

REQ, ADR, PRN и STEP не смешиваются

Канонические источники и представления состояния

STEP-NNN.md, REQ-NNN-*.md, ADR и OQ — канонические документы. PLAN.md, проектный STATUS.md, SPEC.md/STATUS.md требований и OPEN_QUESTIONS.md строятся детерминированно через .harness/tools/sync-projections.py. Расхождение проекций считается дефектом целостности, а не альтернативным источником истины.

Иерархия источников истины

1. Фактический код / миграции / конфигурация / тесты.
2. Принятые ADR.
3. Архитектурная документация и документация подсистем.
4. Требования.
5. STEP.
6. Представления PLAN/STATUS.
7. Бриф, чат и неформальные заметки.

Командный протокол отделён от интерпретации модели

.harness/command-transitions.json остаётся машинным источником истины для допустимых команд и переходов, но обычный запуск теперь проходит через единую границу .harness/tools/harness-dispatch.py. Dispatcher нормализует вход, выполняет структурную проверку, регистрирует состояние выполнения, проверяет предусловия и либо вызывает детерминированный обработчик, либо передаёт модели точный semantic skill и минимальный контекст. .harness/tools/validate-command.py остаётся диагностической проверкой без изменений.

каноническая команда
    ↓
harness-dispatch.py
    ↓
CTS + состояние выполнения + предусловия
    ↓
детерминированный обработчик
    или
точная смысловая передача в Codex / Claude Code
    ↓
проверяемый результат + продолжение цепочки

После смысловой работы фактический результат возвращается dispatcher-у, поэтому продолжение цепочки, восстановление после прерывания и переходы между командами не зависят от того, как модель интерпретировала протокол.

Модель используется только там, где нужна смысловая работа

Граница между вычислениями модели и механикой является частью протокола. Для каждой канонической команды .harness/command-transitions.json хранит режим reasoning: none | required | conditional, а сгенерированная .harness/reasoning-boundaries.json даёт тот же контракт внешним инструментам. Модель формулирует требования, планы, изменения кода и смысловые выводы; маршрутизация, проверки, запись канонических артефактов, recovery и безопасные mutation выполняются скриптами там, где результат можно вычислить однозначно.

.harness/tools/harness-dispatch.py
.harness/tools/verification.py
.harness/tools/semantic-writer.py
.harness/tools/review_gates.py
.harness/tools/review_findings.py
.harness/tools/repair_cycle.py
.harness/tools/side_effect_recovery.py
.harness/tools/runtime_adapter_contract.py
.harness/tools/git-action.py
.harness/tools/harness-update.py
.harness/tools/validate.py

Например, обычный STEP RUN детерминированно переключает PLAN → IMPLEMENT → REVIEW → FIX, а Review Contract v2 и adaptive repair comparator дают машине устойчивый handoff и раннюю остановку без оценки «прогресса» моделью. Для mutation-команд recovery сначала доказывает внешний результат и только затем решает, можно ли повторять side effect.

Справочник валидаторов и проверок →

AI coding harness и фреймворк агентов решают разные задачи

AI Development Harness организует работу агента для программирования над репозиторием. Фреймворк агентов обычно становится частью среды исполнения самого приложения. Эти слои могут использоваться вместе и не являются взаимоисключающими.

Разобрать понятие AI coding harness на примерах →

Качество контракта проверяется отдельными этапами

Harness не считает существование STEP доказательством того, что задача уже пригодна к реализации. Проверки качества требований, согласованности планирования и архитектурной полноты разделяют полноту требований, непротиворечивость контрактов и сквозные архитектурные последствия.

Инженерные принципы Project Principles (PRN-NNN) добавляют отдельный слой долгоживущих инженерных инвариантов. Они не подменяют REQ или ADR: REQ задаёт требуемый результат, ADR фиксирует конкретное принятое решение, PRN ограничивает класс будущих решений.

Смысловые роли получают минимальный Context Contract

Планировщик, реализатор и проверяющий не обязаны загружать весь репозиторий. .harness/tools/context-contract.py строит независимый от среды исполнения манифест контекста задачи: точные разделы STEP, связанные REQ/ADR/OQ, нужные ссылки на разделы архитектуры и компактные проекции применимых Project Principles.

STEP + role + repository revision
        ↓
Context Contract
        ↓
Codex / Claude Code adapter

Для одинакового STEP и роли состав обязательного контекста одинаков вне зависимости от среды исполнения. Дополнительный контекст подключается только с явной причиной; недоступный обязательный артефакт блокирует работу вместо автоматического чтения всего репозитория.

Project State API даёт клиентам готовую проекцию

.harness/tools/project-state.py --json без вызова модели строит снимок состояния проекта, не изменяя репозиторий для UI, VSCode Navigator и других клиентов. Он нормализует REQ, ADR, STEP, OQ, REVIEW, навыки, связи, блокирующие проблемы, актуальность планов и диагностические разрывы.

Клиент отвечает за визуализацию, но не должен заново выводить семантику протокола из Markdown. Это снижает риск того, что CLI, UI и редактор покажут разные состояния одного проекта.

Крупный STEP может содержать проверяемый граф групп выполнения

Необязательное поле executionGroups описывает зависимости, mutationPaths и verificationResponsibilities внутри готового плана. Граф валидируется детерминированно и публикуется через Project State API.

Эволюция знаний имеет формальную семантику

Изменение REQ, ADR, OQ, STEP или блокирующего PRN изменяет контекст планирования только у действительно затронутых задач. .harness/tools/impact-analysis.py объясняет причину устаревания готового плана и выдаёт точное действие для повторного планирования.

Принятый ADR не переписывается задним числом как будто старого решения не существовало: новое долговечное решение оформляется через новый ADR, заменяющий предыдущее решение, а зависимые планы получают статус stale по тому же детерминированному механизму актуальности.

Роли и независимый контроль

Стадии с большим объёмом рассуждений можно отдавать сильным профилям планировщика и проверяющего, а механическую реализацию — более экономичному реализатору. Проверяющий остаётся независимым от реализатора. Смысл ролей задаётся протоколом Harness, а модель и уровень рассуждений настраиваются в конфигурации адаптера выбранной среды исполнения.

Codex и Claude Code — адаптеры одного Harness

.harness/runtime-adapter-contract.json фиксирует общий lifecycle API, capabilities и normalized events. Adapter переводит provider-specific lifecycle/auth/events, но CTS, REQ/ADR/STEP semantics и recovery остаются в Harness control plane. AGENTS.md, протокол выполнения и .agents/skills/ остаются общими источниками истины, поэтому смена среды исполнения не требует переносить проектный процесс в другой формат.

Подробнее о Runtime Adapter Contract, Codex и Claude Code →

Технологические знания подключаются по необходимости

Harness не вшивает в шаблон инструкции для всех возможных фреймворков. SKILL FIND ищет нужную возможность, пользователь выбирает кандидат, а SKILL INSTALL фиксирует происхождение и маршрутизацию. Каждый tracked skill bundle содержит UPSTREAM.md: для core/project-native skill там фиксируются provenance, references и rationale; для third-party — exact upstream/ref/license, inspection notes и локальные адаптации. Исполняемая семантика остаётся в SKILL.md, а provenance-файл не подменяет workflow. Сторонний навык никогда не получает приоритет над контрактом репозитория.