Все рецепты

Конфигуратор харнеса: стек → инструменты и DoD

Интерактивный инструмент серии Harness Engineering: выбираешь стек (JS/TS, Python, Java/Kotlin, Go, PHP) — получаешь персональный сетап. Таблица роль → инструмент (boundary-линтер, мёртвый код, строгие типы, циклы, security, pre-commit), чек-лист Definition of Done по всем фазам rollout (0→8) и готовые копируемые/скачиваемые артефакты под стек: скелет AGENTS.md, конфиг pre-commit и шаблон ExecPlan. Роль универсальна, инструмент — пример на выбор, который ты фиксируешь один раз в ADR. Стек-агностично.

СреднийDevOps с AI15 минAGENTS.md, pre-commit, ExecPlan, ADR, CI
1

Роль универсальна, инструмент — под стек

Вся серия Harness Engineering описывает не инструменты, а РОЛИ: «линтер границ модулей», «поиск мёртвого кода», «строгие типы». Это сделано нарочно — роль одинакова на любом стеке, а конкретный инструмент в ней свой. Так гайд не привязан к одному языку, и любая команда подставляет своё. Конфигуратор материализует это: он берёт абстрактные роли из rollout-плана и собирает из них конкретный сетап под выбранный стек. По сути это интерактивная версия environment.md из Фазы 0 (аудита) — той самой таблицы tool-selection, на которую опираются все последующие фазы. Только тут она ещё и сразу отдаёт готовые артефакты. Важно с самого начала держать в голове: инструмент в ячейке — это пример на выбор, а не закон. Финальный выбор ты делаешь сам и фиксируешь один раз в ADR 0001-tool-selection.

🟦 Роль (универсальна)

  • Линтер границ модулей
  • Поиск мёртвого кода
  • Строгие типы
  • Одна и та же на любом стеке

🟩 Инструмент (под стек, в ADR)

  • dependency-cruiser · import-linter · ArchUnit · deptrac
  • knip · vulture · deadcode · Psalm
  • tsc · mypy · PHPStan · компилятор
  • Выбираешь один и фиксируешь в ADR
Конфигуратор не заменяет Фазу 0. Если проект уже существует (brownfield), сначала аудит: какие роли реально нужны и что уже подключено. Конфигуратор хорош как стартовый набор и как способ не забыть ни одну роль.
2

Собери сетап: выбери стек

Ниже — сам конфигуратор. Выберите стек вверху, дальше три вкладки. «Инструменты» — таблица роль → конкретный инструмент под ваш стек с короткой причиной, зачем эта роль нужна, и пометкой фазы (барьер фазы 3 или GC фазы 5). «DoD по фазам» — компактный чек-лист Definition of Done на все фазы rollout от 0 (аудит) до 8 (тиражирование): по нему видно, что должно быть сделано на каждом шаге. «Шаблоны» — готовые артефакты под выбранный стек: скелет AGENTS.md с уже подставленными сенсорами, конфиг pre-commit и шаблон ExecPlan. Каждый можно скопировать или скачать файлом. Переключите стек — и таблица с шаблонами перестроятся под него. Это и есть «выбери ставку → получи готовый сетап под свой стек» из воронки серии.

Конфигуратор харнеса

СТЕК → СЕТАП

Выбери стек — получи персональный сетап: таблицу роль → инструмент, чек-лист Definition of Done по фазам и готовые артефакты (AGENTS.md, pre-commit, ExecPlan), которые можно скопировать или скачать. Роль универсальна, инструмент — пример на выбор; фиксируешь его один раз в ADR.

РольИнструментФаза
Форматтер
единый стиль, ноль споров на ревью
Prettier · BiomeФаза 3 · барьеры
Линтер общего назначения
типовые баги и анти-паттерны
ESLint · BiomeФаза 3 · барьеры
Линтер границ модулей
направление зависимостей, запрет обхода публичного API
dependency-cruiser · eslint-plugin-boundariesФаза 3 · барьеры
Строгие типы
легибельность среды — агент меньше додумывает
tsc --strictФаза 3 · барьеры
Циклы зависимостей
циклы размывают границы, на которых стоит архитектура
madgeФаза 3 · барьеры
Поиск мёртвого кода
orphan-код, который агент начнёт «чинить»
knip · ts-pruneФаза 5 · GC
Security / scanner зависимостей
CVE и дрейф зависимостей
npm audit · osv-scannerФаза 5 · GC
Pre-commit оркестратор
точка форса барьеров до коммита (CI повторяет на full)
husky + lint-stagedФаза 3 · барьеры

Инструменты — это примеры на выбор, а не закон. Выбери один в роли под свой проект и зафиксируй в ADR 0001-tool-selection. lefthook и pre-commit (framework) — стек-агностичны и годятся как оркестратор где угодно.

Шаблоны — это скелеты, а не готовая истина. AGENTS.md содержит плейсхолдеры (что делает проект, где живёт домен), которые надо заполнить руками: контекст проекта машина не угадает.
3

Не ищи «один инструмент на всё»

Главная ошибка при выборе — взять один популярный инструмент и объявить его законом вселенной. У каждой роли свой класс ошибок, и закрывается он отдельным барьером. ESLint не ловит циклы импортов так, как madge; tsc не заменяет линтер границ. Поэтому таблица — это набор отдельных ролей, а не «сетап на одном тулзе». Второе правило: роль выбирается по классу ошибок, который реально надо ловить, а не по моде. Если в репозитории нет циклов импортов — не тащи madge ради галочки: пустой барьер только замедляет сборку и быстро отключается. Лучше одна реальная роль с настроенным инструментом, чем семь предложенных «на будущее». И что не покрывает ни один готовый инструмент (своё проектное правило — «в domain-слое нет импортов из infra») — закрываешь самописным скриптом-проверкой в той же связке pre-commit + CI.

Дисциплина выбора инструмента

Одна роль — один инструмент, выбор зафиксирован в ADR
Роль берётся под реальный класс ошибок, не «на будущее»
Непокрытое готовым тулзом → самописный скрипт-проверка
Один популярный инструмент как «закон вселенной»
Пустой барьер ради галочки в дашборде
Зафиксируй каждую строку таблицы в ADR с обоснованием. Иначе следующий агент через месяц поставит второй инструмент в ту же роль — и появятся два расходящихся барьера, которые тихо конфликтуют.
4

Артефакты: скелеты, которые форсятся

Вкладка «Шаблоны» отдаёт три артефакта, и каждый — рабочая заготовка, а не теория. Скелет AGENTS.md уже содержит секцию сенсоров с подставленными под стек инструментами, working rules, Definition of Done и retrieve-правило для lessons-ledger — остаётся заполнить плейсхолдеры про сам проект. Конфиг pre-commit показывает связку: форматтер, линтер, границы и тайп-чек по диффу. Шаблон ExecPlan — для задач длиннее рабочего дня. Ключевой нюанс, который зашит в шаблоны: барьеры форсятся механически, а не «по дисциплине». pre-commit гоняется по диффу (быстро, до коммита), а CI повторяет всё на полной базе — обойти через --no-verify не получится. И про тесты в DoD: никакого мандата на покрытие (это Goodhart — агент напишет фиктивные тесты под процент). Вместо этого test-integrity: агент не имеет права ослаблять, удалять или скипать существующие тесты, и это проверяется по диффу в CI. Покрытие — сигнал здоровья, а не цель.
Выбрал стек
Заполнил плейсхолдеры
pre-commit (diff)
обойти нельзя
CI (full base)
# AGENTS.md — sensors section (auto-filled from the matrix for your stack)
## Sensors (Definition of Done — all must be green)
- boundaries: <module-boundary linter>     # e.g. dependency-cruiser / import-linter
- types:      <strict type checker>         # e.g. tsc --strict / mypy --strict
- dead code:  <dead-code finder>            # e.g. knip / vulture
- tests green; test-integrity — do NOT weaken / delete / skip existing tests
  (checked by diff in CI). Coverage is a SIGNAL, not a target.
Enforcement: <pre-commit orchestrator> on commit (diff), CI on the full base.
Скачивай артефакты прямо в свежий репозиторий и сразу подключай pre-commit. Барьер, который существует, но не подключён к хуку, — это конвенция: он держится на памяти агента, а не на механике.
5

Воронка: режим → стек → сетап

Конфигуратор — последнее звено воронки серии. Сначала на входе ты выбираешь режим разработки (A / B / B+ / C) — сколько ИИ вообще нужно проекту. Если это B+ или C (агент пишет код, нужен harness), ты приходишь сюда, выбираешь стек и получаешь готовый сетап: какие барьеры ставить, что считать сделанным по фазам и с каких файлов начать. Дальше — по карте серии: фаза за фазой, от аудита до тиражирования. Конфигуратор не строит харнес за тебя — он убирает паузу «а каким инструментом закрыть эту роль на моём стеке» и «с чего вообще начать». Реальную работу — настроить барьеры, описать слои, накопить уроки — делаешь по рецептам фаз. Возвращайтесь в хаб за полной картой и порядком внедрения.
Режим (A/B/B+/C)
B+ / C → нужен harness
Стек → конфигуратор
Фазы 0→8 по рецептам
Если режим проекта — A или B (человек ведёт, ИИ только ускоряет печать), полный сетап из конфигуратора избыточен. Возьми из него лёгкую часть: ADR на выбор инструментов, DoD и пару барьеров — без всей машинерии.

Результат

Конфигуратор превращает абстрактные роли харнеса в конкретный сетап под твой стек: таблицу роль → инструмент, чек-лист Definition of Done по всем фазам и копируемые/скачиваемые артефакты (AGENTS.md, pre-commit, ExecPlan). Ты понимаешь, что роль универсальна, а инструмент выбирается под стек и фиксируется в ADR; что барьеры должны форситься механически (pre-commit + CI), а тесты держатся на test-integrity, а не на мандате покрытия. Это последнее звено воронки серии: режим → стек → сетап. Дальше — фазы 0→8 по рецептам из хаба.