Harnessimo

Spec-driven development и харнесс, который не даёт ему остаться на бумаге.

Две половины, которые нужны друг другу. SDD: работа — это лан, нумерованная спека, критерии приёмки которой умеют запускаться. Харнесс: одиннадцать проверок, которые отказываются считать этот лан законченным, пока они не проходят. Спеки без принуждения — картотека; принуждение без спек — не с чем сверять.

harnessimo track new <slug> открывает лан, harnessimo check решает, закончен ли он. Работает и на пустом репозитории, и на том, где пятнадцать лет истории: чтобы начать, ничего переписывать не нужно, а одна включённая проверка — уже реальное улучшение.

Ноль зависимостей, один файл конфигурации, любой язык — инструмент читает ваши файлы, запускает ваши команды и ходит по истории git.

Это никто не писал вручную: npm run demo запускает эти команды во временном репозитории и записывает то, что они напечатали.

pnpmnpmyarnbun

pnpm add -D harnessimo
pnpm exec harnessimo init    # scans your repo, writes a config that already passes
pnpm exec harnessimo check   # run this in CI

npm i -D harnessimo
npx harnessimo init    # scans your repo, writes a config that already passes
npx harnessimo check   # run this in CI

yarn add -D harnessimo
yarn harnessimo init    # scans your repo, writes a config that already passes
yarn harnessimo check   # run this in CI

bun add -d harnessimo
bunx harnessimo init    # scans your repo, writes a config that already passes
bunx harnessimo check   # run this in CI

Кому это нужно

Вам, если агент пишет заметную долю вашего кода, а проверяете его работу только вы. Один человек с тремя агентами несёт ревью-нагрузку тимлида и не имеет команды. Эти проверки — та часть работы ревьюера, которую может сделать команда в терминале.

Конкретно:

	Что меняется
Соло-разработчик с агентами	Перестаёте перечитывать диффы, чтобы понять, действительно ли закончено то, что агент назвал законченным
Вайб-кодинг реального проекта	README остаётся правдой по мере движения проекта, и следующая сессия — ваша или агента — работает не по вымыслу
Команда на agentic SDLC	«Готово» становится кодом возврата команды, а не статусом, который кто-то проставил, и означает одно и то же для каждого человека и каждого агента
Долгоживущая кодовая база с агентами	Работа переживает границы сессий: треки и handoff'ы проверяются, а не подразумеваются

Это не для вас, если проект — скрипт на выходные, если вы пишете всё сами и сами же проверяете, или если proof-маркеры некому писать: это единственная ручная часть, и репозиторий, где их не пишут, получает гейт, который ничего не гарантирует.

Зачем это, когда есть Kiro и Spec Kit

Потому что они решают другую половину. Kiro, Spec Kit, BMAD, кодовый агент Copilot и агентные CLI — про производство работы: контекст, спеки, планирование, инструменты, песочницы. Их ответ на вопрос «это действительно готово» тот же, что и у всех: прогони тесты, спроси человека.

Здесь — вторая половина, та, которую никто не поставляет: арбитр. Документация, которая роняет сборку, когда перестаёт быть правдой. Очередь задач, состояние в которой пишет только прошедшая команда. Файлы, задающие оценку, к которым коммит агента не имеет доступа.

И это намеренно не платформа. Ни рантайма, ни демона, ни зависимостей, ни привязки: один npm-пакет и JSON-файл, которые одинаково работают под Claude Code, Cursor, Codex, Kiro или человеком с клавиатурой — и продолжают работать, когда вы пересядете на другое.

Полное сравнение, слой за слоем — Зачем это.

Что он ловит

Три настоящих провала из репозиториев, из которых он вырос.

README, который врёт. В нём было написано, что инфраструктура «поднимается одной Pulumi-программой в infra/». Каталога infra/ не существовало. В одном аудите нашлось десять таких утверждений.

FAIL  proof markers
  README.md:14  make deploy
      no make command named "deploy"

Каждое утверждение в ваших документах называет файл, тест или команду, которая за ним стоит. Удалите её — сборка сломается.

Задача, помеченная как готовая, которую никто не перезапускал. Она лежала в passing с выдуманным подтверждением.

FAIL  queue
  "checkout-totals" claims passing but its verification fails now
    command: npm test -- checkout
    fix:  fix the regression, or the claim was never true

passing пишет только инструмент и только после того, как собственная команда задачи вернула 0. CI перезапускает каждое такое утверждение.

Сессия, которая начинается вслепую. Агент переоткрывает полрепозитория, чтобы понять, где остановился предыдущий. Теперь ответ выдаётся ему на старте:

$ harnessimo brief
== specs/TRACKS.md (live work tracks — load a track's handoff first) ==
- Checkout totals — [handoff](specs/0007-checkout/handoff.md) — active, next: T3 currency rounding

== work queue ==
active: checkout-totals — an order total matches the sum of its lines, in every currency
  verify with: harnessimo queue verify checkout-totals

== enforced here ==
proof, tracks, tasks, queue, coldStart, cleanExit
not enforced: locked, instructions

Одна команда встраивает это в вашего агента: harnessimo hooks install --agent.

Все одиннадцать проверок

Команда	Падает, когда
harnessimo proof	файла, теста или команды, на которые ссылается документация, больше нет
harnessimo queue	задача заявляет passing, но при перезапуске падает
harnessimo tracks	трек ссылается на handoff, который удалили
harnessimo tasks	отмеченная галочка не называет ни одной проверки
harnessimo locked	коммит агента тронул файлы, которые его же и оценивают
harnessimo cold-start	свежий клон не может установиться и проверить себя
harnessimo clean-exit	сессия оставила TODO, debugger, .only(
harnessimo instructions	ваш AGENTS.md перерос лимит строк, который вы задали
harnessimo boundaries	запрещённый вами шаблон появился там, где вы его запретили
harnessimo thresholds	измеренная метрика упала ниже объявленного вами пола
harnessimo release	версия в манифесте, changelog и тегах разошлась

harnessimo doctor печатает, какие из них включены — и какие нет. Ничего не включается без вашего ведома.

Новый проект

pnpm exec harnessimo init && pnpm exec harnessimo check

init смотрит на то, что у вас уже есть — Makefile или Taskfile, раскладку исходников, миграции, CI — и пишет конфиг из этого. Первый запуск зелёный, поэтому первый красный что-то значит.

Заодно создаются .harness/ (правила, инструменты, окружение, состояние, обратная связь) и specs/ (треки работ и handoff'ы).

Внедрение в существующий проект

Включите одну проверку, доведите до зелёного, закоммитьте. Потом следующую.

Что идёт не так	Что включить
README описывает то, чего больше нет	docs
Каждая сессия начинается с нуля	tracks
Отмеченные галочки, которые ни к чему не привязаны	tracks.gateTasks
«Готово», которое оказывается не готово	queue
Работает только на той машине, где собиралось	coldStart
Отладочный мусор, протухшие заметки	cleanExit
Файл инструкций разросся в 600-строчное руководство	instructions
Агент правит то, что его оценивает	locked
Ключ, цвет или импорт не на своём месте	boundaries
Число качества, которое тихо просело	thresholds

Подробно: Внедрение в существующий репозиторий.

Любой агент, любая модель

Здесь ничто не знает, какая модель написала код. Проверки читают файлы, запускают ваши команды и ходят по истории git — поэтому одинаково работают под Claude Code, Codex, Cursor, Gemini CLI, self-hosted DeepSeek, двумя из них одновременно или вообще без агентов.

Единственная привязанная к инструменту часть — автоматический брифинг сессии, и только потому, что инструменты разные. harnessimo hooks install --agent ставит его SessionStart-хуком для Claude Code, у которого для этого есть API. Любой другой инструмент получает то же самое одной строкой: harnessimo agent печатает контракт, который надо вставить в тот файл инструкций, который он читает, — AGENTS.md, CLAUDE.md, GEMINI.md или правило Cursor:

$ harnessimo agent
## Harness

- Run `harnessimo brief` at the start of a session: it prints the live tracks, the
  head of each handoff and what is in flight. Read it before touching anything.
- Run `harnessimo check` before saying anything is done. Green is the claim; your
  summary is not.
- Never edit state in the queue file. `harnessimo queue verify <id>` runs the item's
  own command and records the outcome — that is the only way something becomes passing.

Это вся поверхность интеграции. Нет ни плагина, ни модели для настройки, ни того, что придётся мигрировать при переезде, — ради этого правила и держатся в файлах, а не в формате вендора.

Как этим пользоваться: руками и агентом

Проверки одни и те же, отличается способ, которым они до вас доходят.

Человек запускает harnessimo check перед пушем — или доверяет это pre-commit хуку — и harnessimo doctor, когда нужно понять, что этот репозиторий на самом деле гарантирует. Больше ничего не требуется: проверки читают файлы и запускают команды, поэтому работают и в репозитории, рядом с которым никаких агентов нет.

Агент получает три вещи, которых не даст строчка в файле инструкций. На старте сессии хук печатает состояние: живые треки, начало каждого handoff'а, что в работе. Во время работы harnessimo queue verify <id> — единственный способ перевести задачу в passing: агент запускает команду, инструмент записывает результат. На коммите — тот же гейт, что и у человека.

harnessimo hooks install --agent   # брифинг на старте сессии, в .claude/settings.json
harnessimo hooks install           # быстрые проверки перед каждым коммитом

Оба сценария подробно: Сценарии.

Почему этому можно доверять

Каждый пункт здесь проверяем — единственный вид доверия, на который этот проект вправе претендовать:

• Публикует workflow, а не человек. Релизы собираются и подписываются в GitHub Actions и аутентифицируются по OIDC — в этом репозитории и его секретах нет npm-токена, который можно украсть. Каждая версия несёт provenance-заявление с коммитом и workflow, из которых она собрана; npm audit signatures это проверяет.
• Ноль рантайм-зависимостей, и это правило, которое проверяет собственный CI. Ничто из того, что он тянет, не может сломать проект, который он охраняет.
• Он живёт по собственному стандарту. Десять из одиннадцати применяются к этому репозиторию, включая cold start, который клонирует его в пустой каталог и запускает документированные команды, и перепроверку каждого утверждения о прохождении.
• У каждого правила есть тест, доказывающий, что оно срабатывает на плохом входе — правило, которое умеет только проходить, это допущение в одежде правила.
• Используется в проде, а не только показывается. Два репозитория удалили свои версии этих проверок ради него; оба публичные и указаны ниже.
• MIT, и достаточно мал, чтобы прочитать. Около трёх тысяч строк. Если он исчезнет завтра, вы вендорите его за вечер.

Кто им пользуется

Два продакшн-репозитория, оба удалили собственные версии этих проверок:

• ledger-lens — Next.js, Supabase, Python. Передал сюда свои гейты документации; все 38 его собственных юнит-тестов прошли без правок, а числа совпали до маркера (183 маркера в 71 документе).
• code-knowledge-base — выбросил четыре локальных скрипта, получил proof-маркеры, треки работ и гейт задач.

Этот репозиторий применяет к себе десять из своих одиннадцати проверок, в том числе из свежего клона. Одиннадцатой, thresholds, нужна измеряемая метрика, а инструменту, которому нечего измерять, нечего и держать выше пола — harnessimo doctor говорит это прямо, а не намёком.

Чем он не является

• Не песочница. locked ловит агента, который правит собственную оценку, в CI. Того, кто целенаправленно обходит проверку, он не остановит.
• Не ревьюер кода. Он не судит о корректности, безопасности и стиле.
• Не проверяет качество тестов. Тест без единого ассерта проходит все правила здесь.
• Не инструмент контекста. Ставьте рядом code-graph или codebase-memory MCP: они отвечают на «что мне прочитать», этот — на «это закончено».

Документация

https://atamaniuc.github.io/Harnessimo/ru/ — каждая страница есть и на английском: in English, либо переключатель языка в шапке.

Каждая страница отвечает на один вопрос. Найдите свой:

Я хочу…	Читать
понять, стоит ли это внедрять	Зачем это
увидеть, что проверка ловит и что печатает	Справочник
дойти до первой зелёной проверки	Гайд
включить ещё одну проверку или выключить лишнюю	Гайд → включайте то, что болит
посмотреть ключ конфига	Конфигурация
внедрить в репозиторий, где уже есть свои скрипты	Гайд → внедрение
запустить несколько агентов на одном репозитории	Больше одного агента
понять, почему правило вообще существует	Стандарт
задать короткий вопрос, который не баг	FAQ
починить прогон, который только что стал красным	Что делать
узнать, что взято из OpenSpec, Spec Kit, BMAD и остальных	SDD
внести изменение	Как участвовать

Для агента: все страницы выше одним файлом — llms.txt.

Разработка

npm test          # весь набор, без установки — Node сам снимает типы с TypeScript
npm run check     # тесты, затем собственные проверки этого репозитория
npm run typecheck # tsc, strict, по src и test (нужен npm i)
npm run build     # то, что ставит потребитель: dist/ с декларациями

TypeScript, strict, ESM, ноль рантайм-зависимостей. Правила лежат в src/ чистыми функциями над строками и структурами в памяти; src/resolver.ts и src/cli.ts — единственные файлы, которые трогают диск.

Между исходником и запуском нет шага сборки: модули импортируют друг друга как .ts, и Node снимает типы сам — поэтому npm test не требует установки, а cold start измеряет репозиторий, а не npm. tsc собирает dist/ (переписывая специфаеры в .js), и публикуется именно он. Результат сборки не коммитится.

Лицензия

MIT. Форкайте, вендорите, используйте коммерчески. Если улучшите правило — пришлите PR: смысл в том, чтобы копия была одна.