Golden path: template-репо харнеса (Phase 8)
Финальная фаза серии Harness Engineering: собираем всё, что построено в фазах 0–5.5, в форкаемое template-репо. Харнес перестаёт быть кустарной сборкой под каждый проект и становится golden path. Что кладём в шаблон с очисткой проектной специфики (AGENTS.md / CLAUDE.md со стабами, ExecPlan-шаблон, ADR _template, environment.md с ПУСТОЙ таблицей tool-selection, deterministic-конфиги как TODO-шаблоны, GC-джобы как tool-agnostic контракты, только универсальные .claude/skills/), migration-капсула (portable механизм + curated _core против project-bound шума), HOW_TO_FORK.md с оценкой 2–3 дня и горизонт «живого форка» — shared harness-kit. Стек- и инфра-агностично, с копируемым скелетом форка.
ПродвинутыйDevOps с AI20 минtemplate repo, git, AGENTS.md, ADR, CI
1
Зачем template: capture-once, reuse-everywhere
Все предыдущие фазы вы собирали харнес под конкретный репозиторий: аудит, AGENTS.md, ExecPlan, барьеры, GC, lessons-ledger. Пока это «кустарная сборка»: каждый новый проект начинается с нуля, и кто-то заново вспоминает, что AGENTS.md существует, что у ADR есть шаблон, что барьеры вешаются на pre-commit и CI. Phase 8 решает ровно эту проблему — capture-once, reuse-everywhere. Харнес перестаёт быть артефактом одного проекта и становится golden path: путём по умолчанию, по которому новый проект идёт, не изобретая структуру заново.
Цель измеримая, и формулировать её надо в этих терминах: «время от старта нового проекта до первого PR, сделанного агентом по правилам харнеса». Без template это недели; с проверенным template — стремится к < 1 дня на простом стеке и к 2–3 дням на нетривиальном. Это и есть DoD фазы в одну строку: template-репо существует, форкается и разворачивается на новом проекте независимо от его стека и инфраструктуры.
Важный сдвиг мышления: вы упаковываете не «готовый харнес», а скелет + механизм его наращивания. Готовым харнес не бывает — он накапливается. Template даёт новому проекту правильную форму с первого дня, а не финальное содержание.
🟥 Кустарная сборка
- Каждый проект начинается с нуля
- Заново вспоминают, что AGENTS.md вообще есть
- Старт до первого PR агента — недели
🟩 Golden path (template)
- Форкнул скелет — структура уже есть
- Capture-once: механизм наращивания встроен
- Старт до первого PR агента → < 1 дня / 2–3 дня
Метрика фазы — не «сколько файлов в шаблоне», а «время до первого PR агента по правилам». Если форк не сокращает это время, шаблон раздут: лишние конфиги под чужой стек только мешают, потому что новый проект всё равно начинает с очистки.
2
Что кладём в шаблон (со стабами и TODO, без зашитых выборов)
Содержимое template — это срез всех фаз, очищенный от проектной специфики. Контекст-инжиниринг: AGENTS.md и CLAUDE.md, где имя, домен и слои заменены на стабы <PROJECT_NAME>; rollout-документ HARNESS_ROLLOUT.md БЕЗ заполненного Progress (новый проект ведёт свой); ExecPlan-шаблон для длинных задач; ADR _template плюс README в docs/decisions/, объясняющий, как заводить ADR.
Ключевой принцип фазы — стек- и инфра-агностичность. Поэтому environment.md едет в шаблон как ШАБЛОН: та самая таблица tool-selection «роль → инструмент», но с ПУСТЫМИ строками. Новый проект выбирает инструменты на СВОЁМ Phase 0 — здесь мы не переучиваем, как это делать, и не зашиваем чужой выбор (как это делать — см. рецепт project-audit, который владеет таблицей «роль → инструмент»). Так же deterministic-конфиги (линтер границ, тайп-чек, dead-code) кладутся как TODO-шаблоны, а не готовые конфиги под один стек: «вот роль и форма, инструмент впишет твой Phase 0/3». GC-джобы — как tool-agnostic контракты: один «что мы делаем» (проверка ПРОИЗВОДИТ артефакт — PR/issue/обновлённый MD) плюс пара примеров реализации под популярные планировщики. В .claude/skills/ едут ТОЛЬКО универсальные навыки (создание ADR, normalize/maintain леджера) — проектные SKILL.md остаются позади. И CONTRIBUTING.md с агент-секцией: как агент работает в этом репо.
Содержимое template (стабы / TODO / только универсальное)
AGENTS.md + CLAUDE.md со стабами <PROJECT_NAME>, доменом и слоями
HARNESS_ROLLOUT.md БЕЗ заполненного Progress + ExecPlan-шаблон
ADR _template + README docs/decisions/
environment.md как ШАБЛОН: таблица tool-selection с ПУСТЫМИ строками
Конфиги барьеров — как TODO-шаблоны, не готовые под один стек
GC-джобы — tool-agnostic контракт + пара примеров под планировщики
.claude/skills/ — ТОЛЬКО универсальные навыки + CONTRIBUTING.md (агент-секция)
Зашить готовый eslint/mypy-конфиг и заполненную таблицу под один стек
Правило очистки на каждый файл: «это про механизм или про этот проект?». Имя, домен, слои, выбранные инструменты, заполненный Progress — выкинуть в стаб/TODO. Форма документа, его секции, контракт проверки — оставить. Зашитый чужой выбор хуже пустой строки: его молча унаследуют как факт.
3
Migration-капсула: portable механизм vs project-bound контекст
Самая тонкая часть фазы — что именно тащить в новый проект. Здесь два класса содержимого, и их нельзя смешивать. Portable — это МЕХАНИЗМ, общий для любого репо: промпты (normalize / maintain леджера), команда /wrong, retrieve-правило, Definition of Done, ADR-шаблон — и curated набор portable-уроков в _core/. Project-bound — всё, что привязано к модулям и контрактам ЭТОГО репо: уроки вида «в нашем persistence-слое грузим так», конкретные границы, имена сервисов. В новом проекте такие уроки — чистый шум: они описывают код, которого там нет, и агент будет «применять» несуществующие правила.
Отсюда определение миграции: форкнуть СКЕЛЕТ (механизм) плюс curated _core, а НЕ весь ledger целиком. _core — это капсула переносимых уроков, которые верны на любом проекте этого класса; разделение portable / project-bound и сам _core вводит рецепт lessons-ledger — здесь мы не переобъясняем устройство леджера, а пользуемся его различением. Куратор _core отбирает буквально единицы уроков: «маленькое ядро, которое верно везде» бьёт «перенесли всю тетрадку и засыпали новый проект чужим контекстом».
🟩 Portable (механизм)
- Промпты normalize / maintain, команда /wrong
- retrieve-правило, DoD, ADR-шаблон
- curated _core: уроки, верные на любом таком проекте
- Едет в форк — это и есть golden path
🟥 Project-bound (контекст)
- Уроки про модули и контракты ЭТОГО репо
- Конкретные границы, имена сервисов, домен
- Описывает код, которого в новом проекте нет
- Остаётся позади — в новом проекте это шум
Тест на _core в одну фразу: «этот урок верен на ЛЮБОМ проекте такого класса или только на этом?». Любой → _core. Только на этом → оставить в исходном репо. Когда сомневаешься — НЕ тащи: лишний project-bound урок в форке дороже отсутствующего portable, его всегда можно добавить позже руками.
4
HOW_TO_FORK.md: форк, апстрим, что кастомизировать в день 1
Template бесполезен без инструкции форка — иначе каждый разворачивает его по-своему и golden path расходится. HOW_TO_FORK.md отвечает на четыре вопроса. Первый: как форкнуть скелет в репозиторий нового проекта (и забрать curated _core, не весь ledger). Второй: как подтягивать апстрим, когда сам template обновился — rebase/merge изменений механизма (промпты, ADR-шаблон, _core), не затирая локальный слой проекта. Третий: что кастомизировать в день 1, а что позже. День 1 — это разлочить агента: заполнить стабы <PROJECT_NAME> в AGENTS.md, провести Phase 0 (baseline.md + environment.md с РЕАЛЬНЫМИ инструментами под стек), включить 1–2 самых дешёвых барьера. Позже — остальные барьеры, GC-расписание, наполнение ledger. Четвёртый: честная оценка 2–3 дня до состояния, в котором агент делает первый PR по правилам.
Ниже — копируемый скелет HOW_TO_FORK.md, обобщённый и стек-агностичный: подставьте инструменты своего Phase 0. Это не «вся настройка за раз», а минимальный путь до agent-ready и явный список того, что откладывается.
Форк скелета + curated _core
День 1: стабы <PROJECT_NAME>, Phase 0
Включить 1–2 дешёвых барьера
2–3 дня
Первый PR агента по правилам
накапливается
Позже: GC, остальные барьеры, ledger
# HOW_TO_FORK.md (generalized, stack-agnostic — fill in YOUR Phase 0 tools)
## 0. Fork
- Fork/clone this harness template into the new project's repo.
- Take the SKELETON + curated lessons/_core/ ONLY. Do NOT copy a source
project's full ledger or its project-bound lessons.
## 1. Day 1 — unlock the agent (target: first agent PR in 2–3 days)
- [ ] Replace every <PROJECT_NAME> / <DOMAIN> / <LAYER> stub in AGENTS.md + CLAUDE.md.
- [ ] Run Phase 0 (see the project-audit recipe): write baseline.md and fill
environment.md — the role->tool table with REAL tools for THIS stack.
- [ ] Turn on the 1-2 cheapest barriers (formatter + one boundary/type check)
on pre-commit + CI. One real barrier beats a perfect plan.
- [ ] Open ADR 0001-tool-selection from the _template (records the choices above).
## 2. Later — let the harness accrue (do NOT do all of this on day 1)
- [ ] Remaining barriers from the role table (Phase 3).
- [ ] GC schedule: wire the tool-agnostic job contracts to your scheduler (Phase 5).
- [ ] Start the ledger: enable /wrong; lessons accrue from real corrections.
## 3. Upstream updates (the template is a living dependency)
- The template ships MECHANISM (prompts, ADR _template, _core, DoD).
- To update: rebase/merge upstream into your fork; resolve so the MECHANISM
advances and your LOCAL project layer (filled AGENTS.md, your ADRs, your
lessons) is preserved. Never let an upstream pull overwrite local context.
# Honest estimate: simple stack -> ~1 day; non-trivial -> 2-3 days to agent-ready.
# This is a STARTING POINT, not a finished harness. The rest accrues over time.Не настраивайте всё в день 1. Цель форка — разлочить агента (заполненный AGENTS.md + 1–2 барьера + Phase 0), а не пройти все фазы сразу. Полный rollout — это тот самый scope creep, от которого защищает серия: один реальный барьер сегодня ценнее идеального плана на неделю.
5
Горизонт: «живой форк» и shared harness-kit
У template есть фундаментальный недостаток: форк — это снимок в момент времени. Улучшили промпт normalize или добавили урок в _core на проекте А — проекты B и C об этом не узнают, пока кто-то вручную не подтянет апстрим. Горизонт фазы — снять это: вынести _core и промпты (механизм) в общий пакет/репо — назовём его harness-kit, — от которого проекты ЗАВИСЯТ, а локальные уроки и ADR кладут поверх. Тогда улучшение ядра в одном месте подхватывают все проекты через обновление зависимости, а не через ручной merge в каждый форк.
Это горизонт ПОСЛЕ того, как template доказан на одном проекте, а не первый шаг. Сначала проверьте, что форк реально сокращает старт до 2–3 дней; вынос в shared-пакет до этого — преждевременная абстракция: вы зафиксируете в зависимости форму механизма, которая ещё не устоялась, и будете ломать все проекты при каждой её правке.
И честность про сам template — постоянная нота этой серии: template и harness-kit дают новому проекту правильную ФОРМУ, но не готовое содержание. Layer model, ADR, барьеры под стек и наполнение ledger всё равно накапливаются на каждом проекте со временем. Template сокращает «время до agent-ready», а не отменяет работу.
Локальный слой проекта (накапливается)
Заполненный AGENTS.md, свои ADR, project-bound уроки, барьеры под стек
Shared harness-kit (зависимость, обновляется в одном месте)
Промпты normalize/maintain, _core, ADR-шаблон, DoD — механизм
Стек и инфра проекта
Любой язык, любой CI, любой scheduler — kit агностичен к ним
Не выноси harness-kit, пока template не доказан хотя бы на одном-двух проектах. Преждевременная абстракция здесь особенно дорога: зависимость завязывает все проекты на форму механизма, и пока она не устоялась, каждая правка ядра — ломающее изменение для всех сразу.
6
Финал серии: что template НЕ делает, и карта
Это последняя фаза — серия Harness Engineering собрана. Вы прошли путь от аудита brownfield-проекта (Phase 0) через контекст-инжиниринг, ExecPlan, архитектурные барьеры, garbage collection и lessons-ledger (Phase 5.5) до упаковки всего этого в форкаемый golden path. DoD финальной фазы выполнен, когда template-репо существует, форкается и разворачивается на новом проекте независимо от стека и инфраструктуры.
И напоследок — честные границы харнеса, та же нота, что звучала всю серию. Харнес обеспечивает архитектурную целостность и поддерживаемость — но НЕ функциональную корректность: делает ли код то, что нужно пользователю, по-прежнему проверяют человек и продуктовые тесты. Он НЕ заменяет человеческое ревью. И он деградирует без дисциплины: барьеры ржавеют, документация дрейфует, ledger превращается в write-only кладбище, если за ним не следить (ровно для этого и нужны GC и maintain). Template тиражирует механизм, а не снимает обязанность его поддерживать.
На этом серия закончена. Возвращайтесь в хаб — там карта всех фаз и связи между ними.
Честные границы — что харнес НЕ делает
Обеспечивает архитектурную целостность и поддерживаемость
Template форкается и разворачивается независимо от стека и инфры (DoD)
НЕ валидирует функциональную корректность — это человек и продуктовые тесты
НЕ заменяет человеческое ревью
Деградирует без дисциплины: барьеры ржавеют, ledger превращается в кладбище
Самый частый провал тиражирования — спутать «форкнули template» с «харнес готов». Template даёт форму за 2–3 дня; целостность держится только дисциплиной поддержки (GC, maintain, ревью). Снимок без живой поддержки протухает так же, как любой другой документ.
Результат
Финальная фаза собрана: харнес перестал быть кустарной сборкой под каждый проект и стал golden path — форкаемым template-репо. Вы знаете, что кладётся в шаблон с очисткой проектной специфики (стабы <PROJECT_NAME>, environment.md с пустой таблицей tool-selection, конфиги барьеров и GC-джобы как TODO/контракты, только универсальные .claude/skills/), как устроена migration-капсула (portable механизм + curated _core против project-bound шума), что отвечает HOW_TO_FORK.md (форк, апстрим, день 1 vs позже, оценка 2–3 дня) и куда ведёт горизонт «живого форка» — shared harness-kit как зависимость. И главное — честность: template даёт форму, а не готовый харнес; целостность держится дисциплиной, харнес не валидирует функциональную корректность и не заменяет ревью. Серия Harness Engineering завершена — карта всех фаз в хабе.