DD · Ремесло стройки: промпт-инжиниринг, версионирование, worktree

Углублённый модуль поверх курса. Продолжает Модуль 1 (Урок 1.4 — Skills), Модуль 2 (Урок 2.1 — критик), Модуль 3 (Урок 3.3 — git-память) и Модуль 9 (Урок 9.2 — «harness для кода»). Метки честности как в курсе: 🟢 проверено по первоисточнику, 🟡 иллюстративно/эвристика, 🔴 исправлено.

0. Зачем это отдельный модуль

Прошлые модули курса объясняют, ЧТО строить — оркестратор, память, guardrails, критика. Этот — про другое: КАК руками писать и не сломать. Это ремесло в буквальном смысле — привычки, отличающие хирурга, который двадцать лет ставит катетер не глядя, от того, кто вчера прочитал учебник. Оба знают анатомию — разница в технике руки.

Три навыка, без которых архитектурные модули курса остаются схемой на бумаге:

Как писать промпт агента/критика/CLAUDE.md, чтобы он реально работал — prompt/context engineering.
Как менять промпт, скилл, hook или конфиг оркестратора, не рискуя сломать фабрику ночью — безопасное версионирование.
Как параллельно пробовать несколько вариантов кода (веер MVP, Модуль 2.3), не наступая друг другу на файлы — git worktree.

Медицинская аналогия модуля: рецепт, история болезни, параллельные операционные. Рецепт должен исполняться без вопросов у аптекаря — расплывчатый рецепт хуже отсутствия рецепта. История болезни должна позволять откатить лечение к прошлой версии, не стирая память о пациенте. Параллельные операционные — пробовать разные протоколы на разных «версиях» пациента, не путая инструменты между палатами.

1. Prompt/context engineering как ремесло

1.1 Системный промпт — структура, а не поэзия

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

Как называется по-настоящему. System prompt задаёт роль, границы и формат поведения на всю сессию. Anthropic формулирует правило структуры прямо: искать «золотую середину» между жёстким кодированием сложной логики (хрупко) и расплывчатостью, рассчитывающей на общий контекст (модель домысливает не то) — «достаточно конкретно, чтобы направить поведение, но достаточно гибко, чтобы дать модели сильную эвристику». 🟢 [дословно, Effective context engineering for AI agents, Anthropic].

Рабочая структура, переносимая на любого агента завода (channel-forge, requirements-агент, критик видео): Роль (узкая, не «ассистент») → Контекст (минимум фактов) → Что делать (шаги) → Формат вывода (структура, не свободный текст) → Чего не делать (конкретные ограничения, не «будь аккуратен») → Few-shot примеры. Секции размечаются заголовками/XML-тегами — это облегчает модели навигацию так же, как человеку. 🟢 [тот же источник].

Пять ошибок, которые ловятся сразу. Роль-«ассистент» вместо узкой роли; инструкция без явного «чего не делать» (критик без запрета переписывать текст рано или поздно начинает его чинить вместо оценки); свободный формат вывода (источник тихих сбоев — парсер молча получит пустоту при малейшем отклонении формата, см. DD-nabludaemost.md §5); раздутый набор инструментов с пересекающимися названиями — «если разработчик не может однозначно выбрать инструмент, не сможет и агент» 🟢 [Anthropic, тот же источник]; промпт, проверенный на одном удачном примере вместо бенчмарка (§2.2).

1.2 Few-shot и CLAUDE.md

Few-shot. Few-shot prompting — примеры «вход → правильный выход» в самом промпте, в противоположность zero-shot. Примеры должны быть разнообразными и каноническими, показывающими типичное поведение — редкие edge case лучше выносить в CLAUDE.md/skill, а не раздувать ими промпт. 🟢 [«curate diverse, canonical examples… avoid stuffing edge cases» — Anthropic]. У критика (thumbnail-studio, будущий критик кода) 2-3 примера прошлых вердиктов заметно устойчивее к дрейфу оценки, чем абстрактное «найди проблемы».

CLAUDE.md. Персистентные инструкции, читаемые в начале каждой сессии — в отличие от auto memory (заметки, которые агент пишет о себе сам). 🟢 [официальная документация Claude Code]. Три правила: размер — держать под 200 строк, длиннее — хуже адherence, разбивать по .claude/rules/ с загрузкой по типу файла; конкретность — «отступ 2 пробела» вместо «форматируй аккуратно»; CLAUDE.md — это контекст, НЕ принудительная конфигурация — модель старается следовать, но гарантии нет. Правило, которое обязано выполняться железно (денежная красная линия), — задача hook (PreToolUse), исполняемого как код, а не промпт-инструкции. 🟢 [«use a PreToolUse hook instead» — официальная документация]. Это техническое обоснование решения Модуля 4.1: денежный гейт — hook, а не промпт.

Правило добавления в CLAUDE.md: агент дважды ошибся в одном месте / код-ревью поймало то, что он должен был знать / ты дважды вписал одну поправку в чат — совпадает с законом «повторил дважды → оформи», только для факта/конвенции, а не процедуры (та идёт в skill). _STYLE_PLAYBOOK.md и per-channel profile.json из memory-bank — это уже CLAUDE.md его завода, просто не названные так.

Для любопытных. Субагенты наследуют собственный system prompt, project CLAUDE.md и определения инструментов — но НЕ историю разговора и tool-результаты родителя. 🟢 [официальная таблица «What subagents inherit», Claude Agent SDK docs]. Изоляция критика от рассуждений генератора (Модуль 2.1) — поведение субагентов по умолчанию, а не то, что приходится специально настраивать; эхо-камера возникает именно когда её создают вручную, вставляя рассуждения генератора текстом в промпт критика.

1.3 Контекст-инжиниринг: что класть, чего не класть

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

Как называется по-настоящему. Context engineering — управление тем, что попадает в контекстное окно, в отличие от prompt engineering (что написано в промпте один раз). Правило: минимальный набор информации, полностью описывающий ожидаемое поведение — минимальный не значит короткий, значит без лишнего. 🟢 [«smallest possible set of high-signal tokens» — Anthropic]. Калибровка: начинать с минимального промпта на сильной модели, добавлять инструкции только когда конкретный отказ реально проявился — не защищаться заранее от гипотетических кейсов. 🟢 [тот же источник].

Прямая связь с токеномикой (Модуль 5) и не то же самое, что Git Context Controller (GCC, 🟢 верное название вместо «OneContext», verify/corrections-1.md №13, ~13.6% прирост SWE-bench) из Модуля 3.3: GCC — про рантайм-память ОДНОГО агента внутри долгой сессии; здесь — про то, что физически писать в промпт/CLAUDE.md ДО начала сессии. Конкретный пример: критику даётся только финальный артефакт + чек-лист, без черновиков и рассуждений генератора («я решил сделать так, потому что...») — иначе критик получает возможность согласиться с логикой генератора вместо проверки результата.

1.4 Промпт критика — особый случай

Промпт хирурга («сделай операцию») и промпт эксперта консилиума, проверяющего запись операции («оцени, всё ли правильно»), структурно разные документы. Три обязательных отличия от промпта-исполнителя: явный взвешенный чек-лист вместо «find bugs» (веса под слабые места модели — фактчек весит больше, потому что дороже по репутации канала); запрет на исправление — только вердикт и список проблем, иначе критик частично подменяет генератора; явное указание, что промпту НЕ показывают — черновики и рассуждения генератора, даже если технически субагент и так их не наследует. Структурированный вывод обязателен сильнее, чем для любого другого агента — от него зависит программное решение «фикс vs релиз»:

{"verdict":"fail","score":0.61,
 "criteria_scores":{"hook_strength":0.8,"fact_accuracy":0.3},
 "issues":[{"severity":"critical","criterion":"fact_accuracy","location":"00:42","detail":"дата события неверна"}]}

2. Безопасное версионирование и откат самой фабрики

2.1 Промпты, hooks, конфиг оркестратора — это код

По-человечески. Больница не выбрасывает старый протокол лечения при вводе нового — он остаётся в архиве, доступный для возврата, если новый окажется хуже.

Промпты, скиллы (.claude/skills/*/SKILL.md), hooks (JSON + скрипты), конфиг оркестратора — текстовые файлы, значит на них работает та же git-дисциплина: коммит с осмысленным сообщением на каждое изменение, тег на выпущенную версию, git diff/git log для видимости изменений.

git add prompts/critic-video/v3-current.md
git commit -m "critic-video: ужесточить порог фактчека (score>=0.8)"
git tag critic-video-v3.1

# новая версия оказалась хуже
git log --oneline -- prompts/critic-video/
git diff critic-video-v3.1 HEAD -- prompts/critic-video/v3-current.md
git checkout critic-video-v3.1 -- prompts/critic-video/v3-current.md
git commit -m "rollback critic-video to v3.1: v3.2 пропустил 3 видео без фактчека"

Откат — через явный checkout <tag> -- <файл> + новый коммит, НЕ через reset --hard (стирает историю, риск зацепить параллельные изменения). Именование: не полноценный semver, а v<major> (смена подхода — требует полного прогона бенчмарка) / v<major>.<minor> (точечная правка). Hooks заслуживают более строгого цикла, чем промпты, — ошибка в hook может не заблокировать деньги, которые обязан был заблокировать; изменения в budget-gate.json проходят synthetic-канал без исключений даже для «однострочной правки».

2.2 Стадии вместо «сразу в бой»

Индустриальная практика — прогон через dev → staging → production, сравнение версий side-by-side на тестовом наборе ПЕРЕД тем, как версия становится действующей. 🟡 [практика описана вторичным источником, не Anthropic — общая методология индустрии]. На масштабе одного человека: новая версия критика прогоняется на том же бенчмарке 30-50 эталонных видео (Модуль 4.2), сравнивается со старой; если расхождение хуже хотя бы на паре эталонов — не в прод. Конфиг оркестратора проходит через synthetic-канал (Модуль 3.2), не сразу боевой.

Если регрессия обнаруживается ночью, а не утром — откат не ждёт человека: это частный случай стоп-крана (Модуль 4.3, 5.3). Оркестратору нужна явная переменная последней рабочей версии (CRITIC_PROMPT_VERSION=critic-video-v3.1), откатываемая скриптом, а не просьбой к агенту «откатись».

Что НЕ версионировать вместе с промптами. Секреты (.env, OAuth, ключи) никогда не в том же репозитории — только .gitignore, независимо от размера репозитория фабрики.

3. Git worktree для параллельного веера MVP

По-человечески. Три протокола лечения нужно попробовать параллельно на одном пациенте (веер MVP: A — склад-фокус, B — брони-фокус, C — дашборд-фокус) — каждый в своей операционной со своими инструментами, но с общим доступом к истории болезни.

Как называется по-настоящему. Git worktree — отдельная рабочая директория со своими файлами и веткой, использующая ОДНУ историю репозитория и remote, что и основной чекаут. 🟢 [официальная документация Claude Code]. Прямое решение проблемы «параллельные агенты в одной директории ломают сборку друг другу» (orkestratsiya.md, «Missions»): у каждого explorer-агента физически своя папка.

git worktree add ../mvp-cafe-variant-a -b variant-a
git worktree list
git worktree remove ../mvp-cafe-variant-a

# в Claude Code — то же одним флагом
claude --worktree variant-a-warehouse-focus

По умолчанию worktree создаётся под .claude/worktrees/<имя>/ на ветке worktree-<имя>; можно также попросить Claude «работай в отдельном worktree» — он создаст его инструментом EnterWorktree сам. 🟢 [официальная документация].

Секреты и уборка. Worktree — чистый чекаут: .env не копируется автоматически. Файл .worktreeinclude (синтаксис .gitignore) явно указывает, какие gitignored-файлы копировать — секрет по-прежнему нигде не закоммичен. 🟢 [«only files that match a pattern and are also gitignored are copied» — официальная документация]. Без незакоммиченных изменений worktree удаляется автоматически при выходе; с изменениями — Claude спрашивает. Для ночных -p-прогонов автоматической уборки при выходе нет — воркер обязан сам вызвать git worktree remove после вердикта, иначе ветки копятся до утра (риск диска, Модуль 8.3/11.3). Subagents умеют isolation: worktree — временный worktree создаётся и удаляется автоматически по завершении субагента без изменений. 🟢 [официальная документация].

После турнира. Победитель НЕ обязан мёржиться в main сразу — для демо клиенту достаточно рабочей ветки; слияние имеет смысл, когда вариант становится продолжаемым продуктом. Ценная часть проигравшего варианта переносится точечно (git checkout mvp-cafe-booking-focus -- src/warehouse/), а не вся ветка. Проигравшие ветки не удаляются мгновенно по вердикту критика — остаются до утра (5-й закон, применённый к веткам), удаляются после подтверждения человеком. В память (LEARNING, Модуль 3.4) пишется коммит-хэш победителя, не только текстовое описание — иначе восстановить код через месяц нельзя.

Чек-лист внедрения

Вынести системные промпты агентов/критиков в отдельные версионируемые файлы со структурой роль/контекст/шаги/формат/ограничения/few-shot.
Добавить 2-3 канонических few-shot примера в промпт критика — типичные вердикты, не edge case.
Проверить существующие CLAUDE.md-подобные файлы (_STYLE_PLAYBOOK.md, profile.json) на длину (<200 строк) и конкретность.
Разграничить: мягкое правило → CLAUDE.md; жёсткая проверка (деньги, необратимое действие) → hook.
Создать репозиторий/раздел prompts/, skills/, hooks/, orchestrator-config/ с тегами на промоутнутые версии.
Внедрить staging-шаг: прогон новой версии на бенчмарке/synthetic-канале, сравнение со старой side-by-side.
Прописать и один раз вручную прогнать процедуру отката (checkout <tag> -- <файл> + коммит) — до того, как понадобится ночью.
Никогда не класть секреты в репозиторий промптов/конфигов; для worktree — .worktreeinclude.
Перевести первый веер MVP на git worktree/claude --worktree вместо параллельных агентов в одной директории.
Настроить автоматическую уборку worktree после вердикта судейской панели.

Мини-проверка себя. (1) Критик неделю в проде начал пропускать брак — переписывать с нуля или откатывать? (откат по тегу, правка вслепую под давлением сломанной ночи — риск.) (2) Правило про деньги — в CLAUDE.md или hook? (hook — CLAUDE.md не даёт гарантии.) (3) Три explorer-агента работают в одной папке — что сломается? (конфликт записи, «ломает сборку — блокирует всех»; решение — worktree.)

Куда это в курсе

Ремесленное дополнение Модуля 1 (Урок 1.4 — как физически писать SKILL.md/промпт), Модуля 2 (Урок 2.1 — few-shot и структура критика как реализация Verifier Pattern; изоляция субагентов по умолчанию) и Модуля 2.3 (worktree — техническая реализация «изолированных directory/branch» веера MVP). Продолжает Модуль 3.3 (git-память/GCC — не путать: GCC про рантайм-память сессии, этот модуль про версионирование инструкций между сессиями). Даёт техническое обоснование Модуля 4.1 (денежный гейт — hook, не промпт) через официальную документацию. Питает Модуль 6.3 (ночь без человека — уборка worktree) и Модуль 9.2 (harness для кода — конкретный git-layout) и 9.3 (сквозной сценарий ночи — §3 даёт исполняемые команды для шага «Ночь, генерация»). Кормит Модуль 11.3 (roadmap: изолированные worktree на веере MVP) и 11.4 (план первой недели — рецепт §2.1-2.2 внедряется в первый день без ожидания остальной архитектуры).