p-replicator: фабрика проектов и навыков для Claude Code

Начнём с боли, а не с команд. Открываешь пустой проект, запускаешь Claude Code — и он не знает про твой продукт ничего: ни каким документам верить, ни какие проверки обязательны, ни куда складывать решения. Каждый раз всё заново, и каждый раз чуть иначе.

Знакомься: Мира, участница harness-мастерской. Ей поручили поднять новый продукт — маркетплейс изделий ручной работы. Она уже умеет ставить пакеты и запускать команды, но «просто попросить ассистента написать код» её пугает: потом не найдёшь, почему сделано именно так.

Пакет @dzhechkov/p-replicator отвечает на это одним движением: он кладёт в проект готовый набор .claude — 10 навыков, 11 команд, 4 агента, 9 правил, 10 хуков и настроенный settings.json. То есть ассистент получает не чистый лист, а оснастку: описанные роли, обязательные проверки и панель, которая показывает, на какой фазе ты стоишь.

Дальше готовый набор .claude годится для двух основных сценариев:

1. Поднять новый проект с нуля — команда /replicate ведёт идею через пять фаз к документам, оснастке и контейнерам (45–90 минут).
2. Добавить функцию в существующий проект — команда /feature прогоняет одну функцию через тот же цикл проверки (10–30 минут).

Исходники и публичное зеркало: github.com/djd1m/dz-harness.

Компромиссы: пакет даёт готовую дисциплину и одинаковый результат от проекта к проекту, но он навязывает свои соглашения — пути документов, имена фаз, целевую архитектуру «распределённый монолит в Docker». Если у тебя другие соглашения, часть выигрыша уйдёт на подгонку.

💬 Просто попроси.
- «Расскажи, что такое p-replicator и зачем он мне» → ассистент откроет README пакета и перескажет раздел о двух сценариях применения.
- «Поставь мне оснастку Claude Code в этот проект» → ассистент предложит npx @dzhechkov/p-replicator init и объяснит, какие файлы появятся.

Мира боится ставить незнакомый пакет в рабочий проект: вдруг он затрёт её CLAUDE.md или самописные хуки. Это правильный страх, и у пакета на него есть прямой ответ — идемпотентность.

Команда init — единственная точка входа:

cd your-project
npx @dzhechkov/p-replicator init

Что появится: .claude/skills/ (10 навыков), .claude/commands/ (11 команд), .claude/agents/ (4 агента), .claude/rules/ (9 правил), .claude/hooks/ (10 сценариев на Node), .claude/settings.json и манифест установки .p-replicator.json.

Идемпотентность означает вот что: повторный запуск не перезаписывает существующие файлы без флага --force. Твой CLAUDE.md, твои команды и правленый settings.json остаются на месте. При обновлении с --force настройки не затираются, а сливаются: добавленный тобой хук сохраняется, изменённая тобой команда считается твоей и сохраняется, новый хук из шаблона добавляется, а исчезнувший из шаблона хук распознаётся как осиротевший и убирается. Полная перезапись — только явным --reset-settings.

Что ещё умеет утилита командной строки, кроме init: update (обновить файлы, сохранив правки), remove (удалить установленное), list (показать установленное), verify (проверить, что комплект цел) и doctor (то же самое плюс проверка окружения — например, есть ли git в PATH). Требования: Node ≥ 16, установленный Claude Code, инициализированный git, а для фазы сборки — Docker.

Проверка после установки: npx @dzhechkov/p-replicator verify возвращает 0, если комплект цел, и 1, если что-то потерялось; тогда положение исправит init --force.

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

💬 Просто попроси.
- «Поставь p-replicator, но не трогай мои настройки» → ассистент выполнит init без --force и покажет, что было создано, а что пропущено.
- «Проверь, что установка цела» → ассистент запустит verify или doctor и разберёт код выхода.
- «Покажи, что изменится, но ничего не пиши» → ассистент добавит --dry-run.

Мира набирает в Claude Code одну фразу — и дальше начинается самое интересное:

/replicate "Маркетплейс изделий ручной работы с рекомендациями на ИИ"

За этой фразой стоят пять фаз /replicate. Смотри на них как на конвейер, где у каждой фазы есть свой выход на диск, а между фазами стоит контрольная точка: ты оцениваешь результат и подтверждаешь переход.

1. Фаза 0 — Изучение продукта (необязательная). Навык reverse-engineering-unicorn разбирает похожие компании, «голубой океан» и задачи, ради которых продукт «нанимают» (JTBD). Выход: docs/00_product_discovery.md и docs/product-discovery-brief.md. Пропускается для внутренних инструментов и там, где документы уже есть.
2. Фаза 1 — Планирование. Навык sparc-prd-mini пишет 11 стандартных документов в docs/.
3. Фаза 2 — Проверка. Рой из пяти агентов оценивает документы и выносит вердикт.
4. Фаза 3 — Генерация оснастки. Навык cc-toolkit-generator-enhanced делает то, что зависит от ТВОЕГО проекта: агентов planner/code-reviewer/architect, правила безопасности и стиля, CLAUDE.md, дорожную карту функций.
5. Фаза 4 — Завершение. docker-compose.yml, Dockerfile, .gitignore и первый коммит.

Важная деталь третьей фазы: она не генерирует общие команды вроде /run или /feature — они приезжают готовыми при установке. Так было не всегда: до версии 1.4.0 фаза 3 пыталась породить вообще всё, и результат плавал от запуска к запуску, потому что модель то сокращала шаблон, то забывала его. Разделение на «привезённое» и «сгенерированное» — главное лекарство от этой нестабильности.

Полный проход занимает 45–90 минут. После него у Миры есть /start (поднять каркас по Architecture.md), /run mvp (автономно строить функции по дорожной карте) и /feature <id> (одна функция целиком).

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

💬 Просто попроси.
- «Проведи мою идею через полный конвейер» → ассистент запустит /replicate с твоим описанием и остановится на первой контрольной точке.
- «У меня уже есть техдокументация, начни со второй фазы» → ассистент положит файлы в docs/existing/ и запустит /replicate, пропустив фазу 0.

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

SPARC — это порядок работы: Specification (что требуется), Pseudocode (как это считается), Architecture (где это живёт), Refinement (что ломается по краям), Completion (как это выкатывается). Пакет разворачивает этот порядок в набор файлов в папке docs/:

• PRD.md — видение, роли пользователей, истории;
• Solution_Strategy.md — выбранный подход к решению;
• Specification.md — критерии приёмки и нефункциональные требования;
• Pseudocode.md — алгоритмы и потоки данных;
• Architecture.md — диаграммы C4 и стек;
• Refinement.md — краевые случаи и стратегия тестирования;
• Completion.md — выкатка, непрерывная сборка, наблюдаемость;
• Research_Findings.md, Final_Summary.md, C4_Diagrams.md, ADR.md.

Зачем такая нарезка? Потому что дальше по конвейеру документы соединяются по ключам. Требование FR-order-refund-1 объявляется в спецификации заголовком третьего уровня и должно найтись в псевдокоде строкой REQUIREMENT: внутри блока ### Algorithm:. Проверка считает разность двух множеств в обе стороны: и требование без алгоритма, и алгоритм без требования — это разрыв. Ключи здесь не украшение, а соединение.

Отдельная тонкость про решения: /replicate пишет их в один docs/ADR.md, а проекты, собранные иначе, держат папку docs/adr/*.md. Сканер оснастки читает обе формы и сводит их в один список решений.

Компромиссы: одиннадцать файлов дают прослеживаемость и дисциплину, но их надо поддерживать: устаревший Specification.md тут же роняет проверку связей. Совпадение ключей доказывает связь документов и ничего не говорит о том, что алгоритм действительно реализует требование.

💬 Просто попроси.
- «Собери SPARC-документы по моим существующим спекам» → ассистент запустит навык sparc-prd-mini в автоматическом режиме и пометит недостающие места как [GAP: ...].
- «Проверь, что все требования дошли до псевдокода» → ассистент запустит проверку связей и назовёт ключи, на которых рвётся цепочка.

Документы написаны. Как понять, что они годные, а не просто красиво звучат? Здесь Мира встречает вторую фазу: рой из пяти агентов, каждый со своим углом зрения.

• validator-stories — истории пользователей по INVEST: независима, обсуждаема, ценна, оцениваема, мала, проверяема;
• validator-acceptance — критерии приёмки по SMART: конкретно, измеримо, достижимо, уместно, ограничено сроком;
• validator-architecture — согласие архитектуры с целевыми ограничениями;
• validator-pseudocode — связность алгоритмов и потоков данных;
• validator-coherence — согласованность между документами.

Итог — вердикт валидации одного из трёх цветов, и у каждого свой следующий шаг:

1. 🟢 ГОТОВО — средняя оценка ≥ 70 и ни одного блокирующего замечания → идём на фазу 3.
2. 🟡 С ОГОВОРКАМИ — 50–69 без блокеров → идём дальше с записанными оговорками; в автоматическом режиме один повтор делается сам.
3. 🔴 НУЖНА РАБОТА — меньше 50 или есть блокер → возврат к фазе 1, максимум три повтора, потом конвейер останавливается и зовёт человека.

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

Выход фазы: docs/validation-report.md и docs/test-scenarios.md со сценариями в стиле BDD, выведенными из критериев приёмки.

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

💬 Просто попроси.
- «Проверь мои документы перед реализацией» → ассистент запустит навык requirements-validator и покажет вердикт с разбивкой по пяти валидаторам.
- «Почему у меня жёлтый вердикт?» → ассистент откроет docs/validation-report.md и назовёт конкретные оговорки и их вес.

Проект уже живой: код есть, документы есть, люди пользуются. Прогонять весь /replicate ради приёма платежей глупо — и Мира берёт для этого /feature.

Четыре фазы /feature повторяют большой конвейер в миниатюре:

1. PLAN — навык sparc-prd-mini пишет пять документов в docs/features/<id>/: спецификацию, псевдокод, архитектуру, доработку, завершение.
2. VALIDATE — тот же рой из пяти агентов, те же пороги 70/50 и та же логика повторов.
3. IMPLEMENT — независимые куски работы расходятся по параллельным агентам: каждый пишет код, тесты и коммит, координатор собирает результат и гоняет весь набор тестов.
4. REVIEW — навык brutal-honesty-review раскладывает замечания по тяжести: blocker чинится до слияния, high — в рамках этой же функции, medium уходит в отдельную задачу, low просто записывается.

Между PLAN и VALIDATE стоит жёсткий заслон: проверка связей по ключам. Только код выхода 0 пускает дальше. 1 возвращает в PLAN с точным списком разорванных ключей FR/NFR/AC, 2 останавливает работу, потому что карту ролей документов или сами документы не удалось прочитать.

Входить можно двумя путями. Режим 1 — проект уже поднят через /replicate. Режим 2 — существующий проект: ставишь пакет поверх (init бережёт CLAUDE.md), приводишь имена документов к стандартным docs/PRD.md, docs/Specification.md, docs/Architecture.md, и дальше цикл одинаков. Оговорки режима 2 честно перечислены: не запускать /start (он ждёт свежего каркаса), /feature-ent недоступна без документов DDD/ADR/C4, а хуки автокоммита могут поспорить с твоим порядком работы с git.

Компромиссы: цикл даёт проверенную функцию за 10–30 минут вместо часа с лишним, но требует стандартных путей к документам — флага вроде --prd-path нет, нужно один раз переименовать файлы или поставить ссылки.

💬 Просто попроси.
- «Добавь приём платежей как отдельную функцию с проверкой» → ассистент запустит /feature add-stripe-payments и остановится на вердикте валидации.
- «Собери все функции уровня mvp, каждую в своей ветке» → ассистент выполнит /run mvp --feature-branches.

Здесь самая ценная идея всего пакета, и Мира запоминает её на всю жизнь.

Обычная проверка отвечает двумя способами: всё хорошо или всё плохо. Проверки этого пакета отвечают тремя, и решающий — третий код выхода:

1. 0 — правило соблюдено в проверенной области;
2. 1 — правило нарушено, нарушитель назван поимённо;
3. 2 — проверка не выполнена: посмотреть не удалось, и об этом сказано вслух.

Почему это важно: проверка, которая отвечает «чисто», хотя посмотреть не смогла, превращает неизвестность в успокоение. Именно поэтому недоступный Docker, нечитаемая конфигурация или отсутствующий бриф дают 2, а не 0.

Три такие утилиты живут в .claude/hooks/ и намеренно не подключены ни к одному событию: обычный хук пакета по договору не блокирует — он может напечатать, но не может отказать, а проверка, которая обязана уметь сказать «нет», хуком быть не может.

• check-ports.cjs — проверяет, что ни одно хранилище не смотрит в интернет. Режим каталога читает нормализованную конфигурацию docker compose config; привязка к 127.0.0.1 законна. Отдельный режим --machine смотрит живые контейнеры текущего контекста Docker — и его чистая квитанция честно ограничена моментом снимка.
• check-docs-complete.cjs — дешёвый вопрос перед роем валидации.
• check-growth-trace.cjs — требования роста FR-GROWTH-nnn из брифа фазы 0 должны либо дойти до спецификации, либо быть отклонены с записанной причиной; молча потерять требование нельзя. Нет брифа — это 2, потому что «фаза 0 не запускалась» и «трассировать нечего» — разные утверждения.

Четвёртая проверка, check-pipeline-gaps.sh, живёт в самом пакете, а не среди хуков, и /feature вызывает её как блокирующий заслон.

Компромиссы: три кода выхода дают честную картину и не дают ложного спокойствия, но требуют дисциплины от вызывающей стороны: код 2 надо обрабатывать отдельно, иначе он по невнимательности сольётся с 0 и обесценит всю затею.

💬 Просто попроси.
- «Проверь, не торчит ли база наружу» → ассистент выполнит check-ports.cjs и разберёт код выхода, включая случай «проверка не выполнена».
- «Дошли ли требования роста до спецификации?» → ассистент запустит check-growth-trace.cjs и назовёт потерянные ключи.

Мира заглядывает внутрь .claude/ и видит там 10 навыков и 11 команд. Разница между ними простая: команда — это то, что ты набираешь (/replicate, /feature), а навык — это методика, которую команда подтягивает для работы.

Навыки собраны в три яруса:

1. Основание — самостоятельные, ни от кого не зависят: explore (сократовское прояснение задачи), problem-solver-enhanced (первые принципы и ТРИЗ), goap-research-ed25519 (исследование с подписанными источниками), brutal-honesty-review (жёсткий разбор замечаний по тяжести).
2. Составные — собираются из основания: sparc-prd-mini, requirements-validator, knowledge-extractor.
3. Главный распорядитель — cc-toolkit-generator-enhanced, самый крупный компонент (~165 тысяч знаков, девять модулей с проверками качества: от разбора документов до переиспользования наработок между проектами).

Склеивает их механизм view(): навык прямо в тексте пишет view() .claude/skills/explore/SKILL.md, и ассистент читает нужный файл в момент исполнения. Так навык A поручает работу навыку B, не копируя его содержимое. Ограничение честно записано: этот механизм работает только в Claude Code — для других сред содержимое навыка пришлось бы вклеивать при установке.

Команды: /replicate (полный конвейер), /start (каркас по документам), /run (автономная сборка по дорожной карте), /go (маршрутизатор: ≤3 файлов — в /plan, 4+ — в /feature), /next, /plan, /feature, /myinsights (копилка «граблей»), /docs, /harvest (вытащить переиспользуемые наработки), /deploy.

Про /harvest стоит знать деталь: у него обязательная проверка записи. Находка передаётся сценарию write-insight.cjs, и завершение засчитывается только по квитанции created, appended или duplicate. Пустые прогоны записей не выдумывают.

Компромиссы: ярусная сборка убирает дублирование и даёт огромный охват методик, но view() привязывает пакет к Claude Code, а объём навыков заметно расходует окно контекста.

💬 Просто попроси.
- «Какой навык отвечает за проверку требований?» → ассистент откроет .claude/skills/requirements-validator/SKILL.md и перескажет его критерии.
- «Вытащи из завершённого проекта переиспользуемые приёмы» → ассистент запустит /harvest и дождётся квитанции записи.

Мира ловила себя на одном и том же вопросе каждые полчаса: «а где я сейчас?». Панель статуса и хуки отвечают на него без единого запроса.

Панель — это шесть строк над приглашением Claude Code:

1. заголовок: версия пакета, пользователь, модель;
2. 🚀 Конвейер: текущая команда, фаза, шкала прогресса;
3. 🎯 Дорожная карта: сколько функций сделано, какая следующая, домен проекта;
4. 📊 SPARC: сколько документов из одиннадцати, оценка валидации, число планов и решений;
5. 🛠️ Оснастка: навыки, команды, агенты, правила, хуки — привезённые плюс сгенерированные;
6. 💡 Копилка: число «граблей», состояние тестов, серверы MCP, статус настроек.

Откуда берутся цифры: часть из файла состояния .claude/.p-replicator-state.json, который команды обновляют по ходу работы, часть — прямыми обходами файловой системы и разбором документов. Два защитных приёма стоит запомнить. Первый: каждая секция обёрнута в безопасный вызов, поэтому одна ошибка разбора гасит одну строку, а не всю панель. Второй: файл состояния старше тридцати минут игнорируется — и вместо вранья про «идёт фаза VALIDATE» панель показывает покой.

Хуки — десять сценариев на Node в .claude/hooks/. Часть работает сама: session-insights.cjs подсказывает при старте сессии и подмешивает нужные записи в момент запроса; три сценария автокоммита сохраняют дорожную карту, копилку и планы; statusline.cjs рисует панель. Все они обходятся без командной оболочки и зовут git напрямую, поэтому одинаково работают в Windows-cmd, bash и PowerShell. Каждый завёрнут в перехват ошибок и всегда завершается нулём: хук не имеет права заблокировать сессию.

Компромиссы: панель даёт постоянную обратную связь почти без затрат внимания, но её показатели — производные признаки, а не измерения: оценка валидации выдёргивается из отчёта регулярным выражением, а домен угадывается по ключевым словам в CLAUDE.md.

💬 Просто попроси.
- «Убери панель статуса, она мешает» → ассистент удалит поле statusLine из settings.json, и слияние сохранит это удаление при обновлении.
- «Почему панель показывает покой, хотя я в середине фазы?» → ассистент проверит возраст файла состояния и напомнит про порог в тридцать минут.

Сильный инструмент узнаётся по тому, как честно он перечисляет свои границы. Первым делом Мира открывает не список возможностей, а отдельный файл KNOWN_LIMITATIONS.md: восемь записей, и известные ограничения названы там прямо.

Вот те, что чаще всего задевают на практике:

1. M1 — поведение --feature-branches подтверждено только наличием описания, а не сквозным прогоном по git. То есть обещание есть, доказательства уровня теста — нет.
2. M2 — у входа «у меня уже есть техдокументация» нет формального флага командной строки, он работает только через фразу на естественном языке.
3. M3 — /feature требует стандартных путей к SPARC-документам; флага --prd-path нет, нужно один раз переименовать файлы или поставить символическую ссылку.
4. L5 — файл состояния не добавляется в .gitignore сам, его стоит вписать руками.

К ним добавляются два ограничения по существу. Первое: view() работает только в Claude Code — для других сред нужен отдельный путь со вклеиванием содержимого. Второе, самое важное по духу: ни одна проверка пакета не доказывает, что продукт хороший. Совпадение ключей доказывает связь документов, а не смысл; вердикт роя — это суждение модели; чистая квитанция проверки портов относится только к проверенной области.

А когда пакет вообще не нужен? Если задача — маленький скрипт, разовый разбор данных или правка в один файл, конвейер из пяти фаз обойдётся дороже самой работы. Пакет окупается там, где проект живёт долго и решения нужно будет объяснять через полгода.

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

💬 Просто попроси.
- «Покажи известные ограничения пакета» → ассистент откроет KNOWN_LIMITATIONS.md и перескажет записи по важности.
- «Стоит ли гнать эту задачу через полный конвейер?» → ассистент оценит объём и предложит /plan вместо /feature, если правка мелкая.

Последний раздел без новых понятий: ты ведёшь свой проект через конвейер сам, а Мира просто стоит рядом и задаёт неудобные вопросы.

Полный путь укладывается в шесть шагов:

1. npx @dzhechkov/p-replicator init — привозим готовый набор .claude;
2. npx @dzhechkov/p-replicator verify — убеждаемся, что комплект цел (код 0);
3. /replicate "<одна фраза про твой продукт>" — пять фаз с контрольными точками;
4. на границе фаз 1 и 2 — дешёвые проверки: полнота документов и трассировка требований роста;
5. /start — каркас по Architecture.md, затем /run mvp или /feature <id>;
6. /harvest в конце — вытащить наработки, которые пригодятся следующему проекту.

Три решения, которые придётся принять именно тебе, и ни одно из них не имеет единственно верного ответа:

• Запускать ли фазу 0. Для нового продукта на рынке — да; для внутреннего инструмента она сожжёт время на анализ конкурентов, которых нет.
• Что делать с жёлтым вердиктом. Идти дальше с оговорками быстрее, вернуться и дописать — надёжнее. Цена ошибки определяется тем, дорого ли переделывать позже.
• Оставлять ли хуки автокоммита. Они удобны и они же спорят с аккуратным порядком работы с git; правится это в settings.json сразу после установки.

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

Компромиссы: свобода решений делает конвейер применимым к разным проектам, но перекладывает ответственность на тебя — пакет не выберет за тебя ни глубину проработки, ни момент остановки.

💬 Просто попроси.
- «Проведи мой проект через конвейер и останавливайся на каждой контрольной точке» → ассистент запустит /replicate и будет спрашивать подтверждение между фазами.
- «Подведи итог: что у меня уже сделано и что дальше» → ассистент прочитает панель статуса, дорожную карту и отчёт валидации и назовёт следующий шаг.