Покажи мне свой харнесс — и я спрошу у Клода, кто ты

Я продолжаю пилить по вечерам и ночам локальный заметочник Nitinol. Это третья статья цикла: в первой я рассказывал, как десять лет терял заметки, во второй — про хранение и поиск без RAG. В этот раз — про кухню разработки: стек, модели и процесс, о которых спрашивали в комментариях.

Стек и инструментарий

Про технологический стек я подробно писал в прошлых частях, поэтому здесь одним абзацем. Nitinol — Electron-приложение: Electron 43, React 18, TypeScript, Tailwind. Rich text на ProseMirror, редактор кода и логов — CodeMirror 6, C4-диаграммы — React Flow, календарь — FullCalendar. Данные в SQLite через better-sqlite3-multiple-ciphers; база на диске шифруется — защита хранилища включается по желанию, у меня включена всегда. Тесты — Vitest и Playwright, местами мутационное тестирование на Stryker. На сайте можно, не скачивая, потыкать живое демо.

А вот с инструментами история интереснее, потому что она про эволюцию.

Изначально я решил не писать код руками вообще: весь этот проект задумывался как эксперимент над собой — докуда можно доехать, если руками только рулить, а код оставить моделям.

Начинал я в Cursor — первые версии и все эксперименты с RAG (в продукт он, как вы помните по второй части, так и не поехал) делал там, на штатном Composer. И довольно быстро упёрся: часть задач он просто не вытягивал, и я раз за разом переписывал промпт вместо того, чтобы получать заветный результат. Потом попробовал на тех же задачах Opus (тогда ещё 4.8) — и он решал их заметно лучше. В какой-то момент поймал себя на мысли: какого чёрта я сижу на Composer, если могу постоянно работать с Opus? И без долгих раздумий переехал на Claude Code полностью.

Отсюда, кстати, готовый ответ на вопрос «что бы ты изменил, если бы начинал заново»: сразу начинал пользоваться Claude Code — ну или другим фронтиром типа Codex.

Моделей в итоговом процессе у меня две, и роли у них принципиально разные:

• Claude Code — рабочий интерфейс. Пишет спеки, код и тесты, гоняет проверки, готовит коммиты. Это руки.

• Codex — независимый ревьюер. Работает строго read-only: получает спеку или дифф, возвращает комментарии, но кода не пишет никогда. Это вторая пара глаз — или один глаз, сколько их там у LLMок.

Живёт всё это на подписках, никакого API-биллинга. У Claude — тариф Max 20x, причём аккаунтов два: харнесс прожорливый, и в недельные лимиты одного аккаунта я просто не укладываюсь. С Codex история была поэтапная: начинал на обычном ChatGPT Plus за двадцатку, но квоты кончались быстро, перешёл на ChatGPT Pro за сотню — и про лимиты забыл вообще. Одна подписка вызывает другую через мост — зачем вообще понадобился второй вендор, расскажу дальше.

Сколько это заняло времени

Однозначно ответить сложно.

Началось всё не с кода, а с ресёрча. Меня — да чего уж греха таить, много кого — зацепила идея «второго мозга» из того самого поста Андрея Карпатого. Я копал RAG, MCP, подключение LLM к собственной базе, ставил эксперименты — и постепенно пришёл к тому, что RAG мне не заходит, а нужен нормальный полнотекстовый поиск (ровно про это была вторая часть). А дальше стало просто интересно сделать инструмент, который подходит лично мне. Отсюда и набор, который вы видите: заметки, код-страницы, схемы, таблицы, связи между ними, бэкапы, синхронизация. Изначально это инструмент, идеальный ровно для одного человека — меня. Но я подумал, что такая модель, возможно, зайдёт ещё кому-то. Уверенности, правда, нет — поэтому сделал всё это на всякий случай отключаемым: не нужны диаграммы или канбан — в настройках легко вырубить модуль.

То есть изначально цели построить свой заметочник не было вообще — я ресёрчил и экспериментировал, а продукт вырос из этих экспериментов сам. Поэтому заметная часть времени ушла не на разработку, а на то, чтобы вообще понять, что я строю. Часы я не трекал. Первые недели две вообще пилил прототип в Cursor без гита — репозиторий появился, только когда стало понятно, что это уже не одноразовый эксперимент: первый коммит так и называется baseline, и в него въехала уже живая кодовая база. Дальше уже легко посмотреть: от первого коммита 7 июня до снимка 2 августа прошло 56 календарных дней, за это время накопилось 1393 коммита и без малого три сотни файлов спецификаций в docs/product. Если поделить — выходит в среднем 25 коммитов в сутки без единого выходного.

Харнесс

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

Строил я его, к слову, тем же Claude Code + Codex. Может быть, не лучший способ, зато самый простой: делаешь, смотришь, где сломалось, правишь, идёшь дальше. Получается забавно: обвязка, которая не доверяет модели ни единого коммита, написана самой моделью.

Сначала задача получает класс — от него зависит, сколько проверок она обязана пройти.

Сомневаюсь между Normal и Risk — беру Risk. Дальше восемь шагов.

1. Спека-контракт. Проблема, сценарий, границы задачи, критерии приёмки, риски. Без спеки Normal и Risk не стартуют.

2. Ревью плана до кода. Спека уходит в Codex, замечания разбираются, следующий виток судит уже исправленную версию. На каждый виток поднимается отдельный процесс, контекст не переносится. Для Normal минимум один виток, для Risk — два, плюс числовой потолок, чтобы улучшение плана не превратилось в бесконечность.

3. Реализация. Claude пишет код и тесты по принятому контракту.

4. Ревью диффа в чистом контексте. Ревьюер не наследует рассуждения автора: только дифф, требования и контракт задачи. Normal читает свежий Claude-сабагент. У Risk дополнительно три специализированных прохода: diff — баги, регрессии, слои, пропущенные тесты; security — IPC, SQLite, секреты, сеть, маскировка закрытого контента; impact — радиус изменений: скрипт строит обратный граф импортов, а модель отделяет реальные зависимости от шума.

5. Адъюдикация. Находка модели — это только гипотеза. Три исхода: починить до коммита, отклонить с короткой причиной, или подтвердить, но вынести в техдолг. В отчёте остаётся found_by — потом видно, какой проход дал сигнал (на этом можно строить статистику).

6. Тестовый гейт. npm run verify: typecheck, линтер, юниты, гигиена диффа и браузерный слой в настоящем Chromium.

7. Условный гейт документации. Изменилось видимое поведение — обновляется реестр функций. Принят долговечный компромисс — записывается решение. Ничего этого не было — документацию не трогаем.

8. Сверка квитанций и коммит в master. Про квитанции чуть ниже.

На одну Risk-задачу уходит минимум пять вызовов Codex — это недёшево, но того стоит.

Роли: я — заказчик, модель — подрядчик

Ещё одна вещь, к которой я пришёл не сразу: я развёл процесс создания задач и процесс написания кода.

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

В какой-то момент отслеживать бэклог стало откровенно сложно — он разрастается очень быстро. Проблемы находятся легко: часть нахожу я, часть находит Claude прямо по ходу работы. А харнесс далеко не всегда разрешает чинить их в моменте: подтверждённая находка, которая выходит за границы текущей задачи, уезжает в реестр, а не в текущий коммит. Бэклог от этого пухнет ещё быстрее. Сами планы и бэклог проекта я давно веду в Nitinol — продукт дорос до того, чтобы разрабатывать сам себя)

Зачем так сложно: какие грабли это закрывает

Ни один из этих гейтов не появился из статьи про best practices — у каждого за спиной конкретная ошибка, которую я пытался больше не повторять.

С LLM и генерацией кода я вожусь давно — ещё с тех версий ChatGPT, которые осиливали строчек пять и очень собой гордились. Всю эволюцию наблюдал более-менее вживую, поэтому про слабые места представление имею, и стартовый набор проверок закладывал сразу: строгая типизация, линтеры, автотесты, собственные глаза поверх. Вопрос был не «проверять или нет», а что именно ставить первым.

Спека-контракт и спек-петля выросли из провала TDD. По дефолту я работал через TDD: тесты вперёд, реализация следом. С моделями этот подход быстро показал известную слабость: модель пишет кривые тесты, а потом под эти же кривые тесты подгоняет реализацию. Формально всё зелёное, по факту закреплено не то поведение. К SDD — spec-driven development, когда вперёд выносится не тест, а спецификация как источник истины, — я пришёл отчасти опытным путём, отчасти потому, что туда сегодня подталкивает вся индустрия. Модели с рассуждениями по своей природе сначала строят план и только потом пишут код — внятная спека для них естественный вход. Сами инструменты обросли внутренними харнесами: агентные циклы, планирование, самопроверки — идея «сначала контракт, потом код» зашита уже на уровне тулинга. Ну и спек-фреймворки повалили один за другим — это тоже о чём-то говорит.

Сейчас львиную долю усилий я вкладываю именно в то, чтобы написать корректную спеку. Этот этап у меня чуть ли не самый большой — заметно больше, чем собственно написание кода. Да, звучит странно. Но замечание к тексту спеки стоит копейки, а то же самое замечание к готовому коду — переделку.

Почему я не взял готовый SDD-фреймворк — Spec Kit, Kiro, OpenSpec? Здесь придётся честно признаться. Я слежу за развитием всей этой области, но за темпом не поспеваю: пока строил своё, пропустил момент, когда SDD-фреймворки превратились в новый стандарт для харнесов. Передний край сейчас движется так, что тяжело поспевать за всеми веяниями, не говоря уж о том, чтобы всё пробовать и щупать руками.

Когда наконец взялся за них, провёл честное сравнение их модели со своей (естественно, силами Claude — с Codex в роли оппонента). Вывод разбора можно уместить в одну строку: брать модель, а не инструмент.

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

При этом сравнение честно вскрыло в первой версии моего харнесса критические дыры, которых у фреймворков не было. Спека существовала только как имя markdown-файла — без машинной идентичности: ни id, ни класса задачи, ни risk-тегов. У критериев приёмки не было стабильных ID — ревью и коммитам было не на что ссылаться. И спека никак не привязывалась к коммитам и меткам времени: доказать, какой версии контракта соответствует код, было нечем. Закрыть эти дыры точечно — YAML-шапка, пронумерованные критерии приёмки, привязки к коммитам плюс подсмотренная там же секция «Дельта» — оказалось проще и дешевле, чем внедрять чужой фреймворк целиком.

Что отверг — и почему. Их CLI и структуру каталогов с changes/ и archive/: это по сути второй параллельный реестр задач, а у меня статус фичи уже живёт в роадмапе, бэклог и техдолг — в своих реестрах. Ещё одна структура папок стала бы новым источником дрейфа. Массовую миграцию старых спек под новый формат: шум больше ценности, конвенция действует только для новых. И поле «статус» в спеке — его не будет принципиально: готовность доказывается квитанциями и тестами, а не полем в файле, которое кто-то забыл обновить.

Все эти решения обратимые: фреймворки никуда не денутся, если вдруг решу-таки что-то внедрить.

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

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

• Правила процесса жили в нескольких файлах и противоречили сами себе: в одном месте Codex-ревью обязательно всегда, в другом — только для рискованных задач, в третьем оно вообще названо опциональным. Какой процесс выполнит агент — зависело от того, какой файл он прочитал первым. Отсюда один нормативный файл-канон, на который остальные только ссылаются, и классификация задач.

• CI был написан и не запускался ни разу: workflow-файлы лежат в .github/workflows, а репозиторий живёт на GitLab, где их некому исполнять. Чем это плохо, если попроще: я жил с ощущением, что код перед попаданием в master автоматически прогоняется через тесты и проверки, — а на деле этого барьера не существовало вовсе, всё держалось на «не забыл запустить руками». В документации при этом CI гордо назывался действующим — сам себе врал, получается. Отсюда npm run verify как единственный вход: одна команда со всеми проверками, которая обязана пройти перед каждым коммитом.

• Мост к Codex сводил все сбои к одному статусу: кончившаяся квота выглядела ровно как сломанная авторизация, а дифф длиннее 200 тысяч символов молча обрезался — и отчёт приходил со статусом OK. Неполное ревью выглядело полным. Отсюда честные статусы и отдельное поле «покрытие»: что случилось с вызовом и что судья вообще видел — два разных вопроса.

• Линтер выдавал 107 предупреждений, 74 из них — про неиспользуемые переменные. Новое предупреждение в таком фоне просто не видно. Отсюда правило: предупреждений ноль, шум выпиливается, а не накапливается.

• Проект сидел на Electron 30.5.1, а поддержка всей 30-й ветки кончилась ещё 15 октября 2024 года — то есть в рендерере, куда попадает недоверенный контент, крутился Chromium 124 без свежих патчей. Эту версию мне, кстати, подкинул ещё Composer на старте: у модели срез знаний, и с её точки зрения это и был актуальный стек. А я поначалу не обратил внимания — типичная ловушка генерации. Отсюда регулярный ритм обслуживания стека вместо «обновлю, когда что-то сломается» и привычка перепроверять руками всё, что модель называет «свежей версией».

Где не было инцидента или понятного риска — я старался ничего не добавлять. Харнесс, собранный «на всякий случай», разросся бы бесконечно.

Codex как второй судья

Схема работы простая. Codex получает контрактный срез спеки — то есть понимает, какая стоит задача, — плюс сам дифф, и работает изолированно. Код не пишет никогда, только комментарии, которые возвращаются Claude, тот вносит правки, дальше при необходимости ещё круг.

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

Пара практических наблюдений. Ревьюить слабыми моделями не имеет никакого смысла: фронтирные в этой роли работают нормально, всё, что слабее, — только шум и потраченное время. Была ещё идея подключить третью модель под UI-задачи: на Frontend Code Arena прямо сейчас первым стоит Kimi — свежий K3 обогнал там в том числе модели Anthropic. Но прикрутить его в конвейер руки пока не дошли.

Философия продукта: правила игры не только для кода

Харнесс отвечает на вопрос «как строить». Но есть второй вопрос — «что строить», и без ответа на него конвейер просто аккуратно и с гейтами едет не туда.

Хронологически, кстати, всё было наоборот: философия появилась раньше харнесса.

Когда я затевал проект, я пытался сам себя ограничить, чтобы продукт не разросся в монстра. И тут очень важно сразу прописать правила игры: чем продукт является и чем не является, где границы, какие продуктовые и технические решения разрешены, а какие запрещены. Я назвал это философией продукта — и она лежит не в голове, а отдельным md-файлом. Когда модель приносит варианты, она сразу помечает: это философии соответствует, это нет.

Формулируется философия коротко: функциональный минимализм и низкая когнитивная нагрузка. Возможность раскрывается тогда, когда нужна, и не раньше. Я называю этот принцип — ложка хороша к обеду.

Два главных принципа оттуда.

Прогрессивное раскрытие. Не надо вываливать на пользователя всё сразу. Поле времени появляется после даты, повтор — после срока, «Связи» — когда они реально есть, тулбар таблицы — после того, как таблицу создали. Сложная логика работает внутри и не вылезает наружу: в поиске куча правил релевантности, а пользователь видит одну строку. И скрывать, а не дизейблить: палитры и тулбары плотные, а по закону Хика время выбора растёт с числом вариантов перед глазами — каждая неактуальная кнопка замедляет поиск актуальной. Этот налог я считаю дороже обучаемости «серых» кнопок.

Свойства, а не типы. Новая способность — это свойство или режим существующей сущности, а не новый видимый тип. У меня из-за этого правила исчез отдельный тип «код»: он стал свойством body_format у страницы. Задача и Заметка для пользователя по сути слиты — их различает флаг «на доске». Прежде чем заводить новую сущность, я обязан проверить, нельзя ли обойтись свойством. Обратный порог тоже прописан, чтобы правило не стало догмой: отдельный тип заводится, когда кластер свойств меняется всегда вместе и живёт своим жизненным циклом.

И самое полезное, до чего я дошёл не сразу: в философии прописан порядок разрешения конфликтов. Ясность важнее DRY. YAGNI важнее преждевременной конфигурируемости. Открываемость важнее минимализма интерфейса.

Вот это, по-моему, ключевое. Набор красивых принципов без явного приоритета для модели бесполезен — она подведёт обоснование подо что угодно, потому что всегда найдётся принцип, оправдывающий выбранное решение. Проверено на собственных правилах ревью: пока там стояло «рекурсии нет», это не останавливало ничего — заработало, только когда появился числовой потолок кругов. Правило должно быть операциональным, иначе это просто украшение репозитория.

Три сорта паранойи

Дальше три коротких сюжета про то, как харнессу приходится защищаться — в том числе от самого себя.

Харнесс не проверяет себя собой. Для изменений самого конвейера у меня отдельный класс задач. Причина простая: скрипт ревью загружает промпт ревьюера из рабочего дерева. Меняю этот промпт и тут же запускаю проверку — правку судит уже новая версия того, что я правлю. Экзаменатор, который перед экзаменом переписал себе критерии. Поэтому харнесс меняется отдельной задачей, а его дифф проверяется версией из HEAD в чистом worktree.

Ревью должно пройти тот же код, который коммитится. Между отчётом ревьюера и git commit проходит время: я могу поправить файл руками, может приехать чужая правка. Поэтому отчёты и зелёный verify пишут fingerprint change-set и пофайловый снимок, а перед коммитом npm run evidence:check поимённо называет файлы, которые разошлись с квитанциями. Команда специально ничего не блокирует: инструмент показывает расхождение, а решать — моя работа.

Состояние конвейера должно быть видно. Параллельные worktree довольно быстро сделали процесс непрозрачным: у каждого свои незакоммиченные файлы, спеки, отчёты, квитанции. Однажды памяти не хватило — чужой незакоммиченный код уехал в коммит. Так появился npm run harness-status — read-only снимок всех рабочих деревьев.

Экономика: подписки против сеньора

Харнесс — штука прожорливая. Модели постоянно перепроверяют друг друга, спеки пишутся на каждую задачу, SDD сам по себе съедает прилично токенов. В деньгах это выглядит так: два аккаунта Claude Max 20x по 200 долларов плюс сотня за ChatGPT Pro ради Codex — итого порядка полутысячи долларов в месяц.

Звучит дорого, пока не сравнишь с реальными ценами на разработку: это в несколько раз дешевле, чем держать даже одного сеньора-фуллстека, — не месячная зарплата, а её малая часть. Здесь просто разные порядки величин.

Глазами на код смотреть приходится крайне редко, но на структуру — приходится. Модели регулярно пихают в репозиторий какую-то ерунду: не подчищают за собой временные папки, забывают удалять git worktree после задачи. Сам Claude Code тоже иногда подвешивает папки, хотя процессы там уже не крутятся. Хотя и это я стараюсь автоматизировать отдельным скиллом.

Это вообще практика, которой я придерживаюсь: появилась повторяющаяся задача — делаешь скилл. Так их накопился небольшой набор: оркестратор всего конвейера из этой статьи; релиз с перф-гейтами; предрелизный аудит по всей накопленной дельте; ресёрч — глубокий разбор идеи с Codex в роли оппонента; ну и та самая уборка зависших worktree и временных папок. Плюс отдельная пачка скиллов-промптов для осей ревью — spec, diff, security, impact.

Теперь про масштаб, и здесь будет самое спорное утверждение статьи. Мне стало интересно, сколько стоил бы этот проект, если делать его обычным путём. Считал двумя способами: от объёма кода (на снимке от 20 июля — порядка 187 тысяч строк продакшн-кода на TypeScript и ещё около 103 тысяч строк тестов) и снизу вверх по составу подсистем: оболочка, редакторы, диаграммы, шифрованное хранилище, поиск с морфологией, синхронизация, LLM-контур, импорт, сайт, релизный конвейер. Первый способ даёт 7–16 человеко-лет, второй — 4–6. Подсчёт по строкам всегда завышает, поэтому опираюсь на консервативную оценку: порядка 4–8 человеко-лет. Команда из четырёх человек занималась бы этим года полтора-два — и это ещё без командных накладных расходов.

У меня — две недели прототипа в Cursor ещё до появления репозитория и 56 календарных дней от первого коммита до рабочей версии, по вечерам и ночам: я часто оставляю агента работать на ночь (да чего уж там, почти всегда). И это не только само приложение — в те же 56 дней уместились сайт с живым демо, установщики под Windows и Linux, подписанный фид автообновлений и собственный APT-репозиторий для Linux.

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

Мы сейчас буквально своими руками собираем и проектируем то, как будет выглядеть разработка через два, три, пять лет. Хотя о сроках говорить сложно: скорость, с которой идёт прогресс, беспрецедентная — так быстро IT ещё никогда не развивалось. Исключительно моё мнение, конечно. Но времена нас ждут интересные.

Харнесс не высечен в камне

Если из всей статьи выносить одну мысль — вот эту.

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

Только расти он должен от измерений, а не от «мне кажется, так лучше». Без измерений вы будете бесконечно усложнять конструкцию и не получать лучшего результата.

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

А вот три правила, которые, по моему мнению, стоят примерно ничего и подойдут кому угодно:

1. Ревьюеру — чистый контекст, требования и дифф.

2. План проверять до кода. Замечание в спеке почти всегда дешевле того же замечания после реализации.

3. Для рискованных изменений отрицательный вердикт повторить независимо. «Ничего не найдено» — тоже утверждение, и его тоже надо проверять.

Что дальше

А что в итоге вышло из всего описанного — проще посмотреть, чем рассказывать: на nitinol.app прямо на главной есть живое демо, можно потыкать интерфейс без установки и примерно понять, что получилось. Сборки — Windows и Linux, для личного использования бесплатно.

А к вам три вопроса:

1. Используете ли вы харнесс и SDD в своих проектах? Собственную обвязку или готовый фреймворк вроде Spec Kit / Kiro / OpenSpec — и что вошло в ваш набор гейтов, а что выкинули как лишнее?

2. Гоняете ли вы ИИ-ревью на своём коде — и доверяете ли одиночному прогону? Особенно интересны те, кто попробовал и бросил: на чём перестала сходиться экономика — время на разбор шума, цена запусков или качество находок?

3. Где у вас проходит граница между «ИИ пишет» и «ИИ проверяет»? Даёте модели править то, что она же и написала, или разводите роли?

Спасибо всем, кто дочитал сей опус и комментировал предыдущие части.

Всем добра)