Что понадобится
Для ядра Harness обязательны Git и Python 3.11+. Для рабочей AI-сессии достаточно одной поддерживаемой среды исполнения: Codex или Claude Code. CLI для Pull Request — отдельная необязательная capability: GitHub использует gh, Gitea — tea. Без provider CLI Harness продолжает выполнять обычные Git-команды.
Git
Обязателен для состояния репозитория, ревизий, изменений, безопасных коммитов и публикации веток.
Python 3.11+
Обязателен для детерминированных инструментов и валидаторов Harness, включая разбор TOML стандартным модулем tomllib.
Codex или Claude Code
Для AI-сессии нужен один выбранный инструмент. Второй может отсутствовать и не считается блокирующей зависимостью.
PR CLI: gh или tea
Нужен только для GIT PR и GIT PR FINISH: gh для GitHub, tea для Gitea. Остальные Git-команды Harness используют обычный Git.
HARNESS DOCTOR отдельно показывает обязательные зависимости, выбранный runtime и configured Pull Request capability.1. Создайте репозиторий из шаблона
Создайте новый репозиторий на основе официального шаблона AI Development Harness: открыть форму создания репозитория на GitHub. GitHub создаст отдельный репозиторий вашего проекта с готовой структурой Harness. После этого клонируйте уже свой созданный репозиторий.
.harness/harness.lock.json. Он фиксирует известный BASE текущего релиза Harness. Допустимый маршрут будущего обновления определяется канонический .harness/harness-update-graph.json, а содержимое каждого перехода берётся только из неизменяемых release tags.2. Опишите проект своими словами
cp PROJECT_BRIEF.example.md PROJECT_BRIEF.local.mdБриф — локальное исходное описание проекта. Полезно указать цель, пользователей, сценарии, ограничения, обязательные или желательные технологии, то, что не входит в проект, и ссылки на примеры. Заранее оформлять REQ, ADR и STEP не требуется.
3. Откройте проект в Codex или Claude Code
Выберите среду исполнения, которой хотите пользоваться. Протокол Harness остаётся одним и тем же, а настройки конкретной среды уже лежат в репозитории.
Codex
.codex/config.toml регистрирует роли, а .codex/agents/*.toml задают модель и уровень рассуждений для каждой роли.
Claude Code
CLAUDE.md импортирует @AGENTS.md; .claude/settings.json и .claude/agents/*.md задают основной профиль и роли.
4. Перед PROJECT INIT проверьте актуальность Harness
Если после создания репозитория вышел новый релиз Harness, обновиться можно ещё до инициализации проекта:
HARNESS UPDATE CHECK
HARNESS UPDATE APPLY
inspect diff
GIT CHECK > COMMITproject.initialized: false не блокирует эти команды. Механизм обновления меняет только служебный слой Harness и lock, не выполняет PROJECT INIT и не создаёт продуктовые REQ/ADR/STEP. PROJECT_BRIEF.local.md остаётся файлом проекта. Проверка строит маршрут через канонический .harness/harness-update-graph.json, поэтому обязательные промежуточные релизы учитываются автоматически.
5. Запустите PROJECT INIT
PROJECT INITИнициализатор читает brief и создаёт базу знаний проекта: docs/PROJECT.md, канонические REQ-NNN-*.md, открытые вопросы, базовую архитектуру, необходимые ADR, долгоживущие инженерные принципы Project Principles (PRN-NNN) и дорожную карту STEP-NNN. SPEC.md, STATUS.md, PLAN.md и другие индексы остаются детерминированными проекциями, а не вторым источником истины.
Качество требований
Проверка Requirements Quality Gate оценивает полноту, ясность, измеримость и покрытие сценариев. Если существенного решения не хватает, INIT возвращает NEEDS_INPUT или BLOCKED, а ответ фиксируется в каноническом REQ/ADR/OQ/STEP.
Согласованность
В PROJECT INIT выполняются две независимые семантические проверки: сначала требований, затем дорожной карты. Между ними Harness проверяет архитектурную полноту. Противоречивая дорожная карта не становится исполнимой только потому, что её удалось записать.
Инженерные принципы
PRN-NNN создаются только для действительно проектных инвариантов, которые должны действовать на множество будущих решений. Обычные предпочтения код-стайла не превращаются в Project Principles.
После семантических проверок Harness пересобирает проекции, запускает валидатор и только через .harness/tools/finalize-project-init.py атомарно устанавливает project.initialized: true. PROJECT INIT не создаёт код продукта. Ручная правка project.initialized не считается корректным завершением инициализации.
6. Проверьте результат инициализации
Убедитесь, что требования не выдуманы, существенные неизвестные вынесены в OQ, ADR не создаются «на всякий случай», зависимости не потеряны, а два отчёта INIT-проверки имеют PASS для текущих оснований.
PROJECT STATUS
STEP NEXTЕсли вы изменили стандартные каталоги в .harness/manifest.yaml, основные инструменты должны работать через настроенные пути: стандартные docs/** и planning/** не являются скрытым вторым реестром.
7. Зафиксируйте основу
GIT CHECK > COMMIT > PUSHПравила работы с Git находятся в .harness/git-policy.toml. GIT COMMIT и GIT PUSH разделены: Harness не публикует изменения автоматически только потому, что реализация завершена.
8. Начните разработку
Можно выполнять этапы вручную цепочкой внутри домена STEP или запускать весь допустимый цикл одной управляющей командой. Перед запуском цепочка целиком проверяется по канонической таблице переходов.
STEP ADD и STEP PLAN сначала проверяют качество и непротиворечивость контракта. Планировщик получает Context Contract для конкретной задачи, проверяет связанные REQ/ADR/OQ и применимые Project Principles; только совпадающий PASS и актуальный отпечаток контекста планирования делают план готовым.
Ручной режим
STEP PLAN STEP-001STEP IMPLEMENT STEP-001STEP REVIEW STEP-001
Автоматический режим
STEP RUN STEP-001
Harness сам проходит допустимые стадии и останавливается при блокирующей проблеме.
После успешного ревью реализации Harness отдельно выполняет Completion / Convergence Gate: он проверяет, что закрыты все критерии приёмки, связанных REQ, готового плана и применимых специализированных проверок. Только после PASS STEP получает каноническое доказательство завершения.
Новая задача формулируется обычным языком через STEP ADD: <описание>.
9. Обновляйте Harness отдельно от работы над проектом
HARNESS UPDATE CHECK
HARNESS UPDATE APPLYСамообновление относится к служебному слою Harness, а не к работе над продуктом. Проверка использует lock как текущий BASE, канонический граф обновлений как маршрут до целевой версии и политику обновления как правила владения/слияния для каждого перехода. Обновление не создаёт STEP и не делает коммит/отправку/PR автоматически; общие конфигурации Codex и Claude сохраняют проектные настройки через трёхстороннее слияние.