От идеи к документам: курс по @dzhechkov/skills-idea2prd

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

А цена вот в чём. Код — самая дорогая форма мышления. Чтобы изменить решение, зашитое в код, нужно переписать код и все тесты вокруг него. Чтобы изменить решение, записанное в документе, нужно переписать абзац. Поэтому пакет @dzhechkov/skills-idea2prd вставляет между идеей и кодом слой документов, которые ты читаешь и оспариваешь до того, как написана первая строка.

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

Три выгоды, ради которых стоит потратить час:

1. неверное допущение ловится на уровне требований, а не после реализации;
2. у каждого архитектурного выбора есть записанная причина, а не «так вышло»;
3. готовый набор документов уходит дальше как одно цельное задание.

💬 Просто попроси.
- «сделай PRD пошагово для сервиса подбора подрядчиков» → ассистент включит скилл idea2prd-manual и начнёт с уточняющих вопросов, а не с кода.
- «у меня не идея, а боль: подрядчиков ищут только по знакомым» → ассистент поймёт, что на входе проблема, а не идея, и сначала запустит аналитическую ветку.

Ссылки: страница пакета на npm и исходники в зеркале репозитория.

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

npx @dzhechkov/skills-idea2prd init

Команда кладёт скиллы прямо в проект, в каталог .claude/skills/, и добавляет слэш-команду /idea2prd-manual. Глобально ничего не ставится: пак живёт внутри проекта, поэтому у двух проектов могут быть разные версии, и это нормально.

После установки ассистент подхватывает скилл сам, по фразам вроде «сделай PRD пошагово для …» или «idea to prd manual: …». Отдельно включать ничего не нужно.

Если в системе уже есть общий harness-инструмент dz, тот же пак ставится через него — команда dz init --select idea2prd-manual. Это удобно, когда собираешь проект сразу из нескольких паков, а не только из этого.

💬 Просто попроси.
- «поставь idea2prd в этот проект» → ассистент выполнит установку через npx @dzhechkov/skills-idea2prd init и покажет, что появилось в .claude/skills/.
- «проверь, что пак встал правильно» → ассистент запустит npx @dzhechkov/skills-idea2prd doctor.

Ссылки: страница пакета на npm и исходники в зеркале репозитория.

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

Внутри четыре скилла. idea2prd-manual — оркестратор, он ведёт весь путь и останавливается на контрольных точках. explore превращает расплывчатую задачу в бриф через вопросы. goap-research-ed25519 ведёт исследование с явными источниками и подписью. problem-solver-enhanced разбирает проблему девятью модулями — от первых принципов до ТРИЗ.

Плюс четыре скрипта, которые работают локально, без сети: c4_generator.py рисует диаграммы, fitness_validator.py проверяет fitness-функции, pseudocode_generator.py собирает псевдокод, ai_context_builder.py готовит каталог .ai-context/ для кодирующего ассистента.

Важная деталь про происхождение. Канонический артефакт этого пака — только idea2prd-manual. Тройка explore / goap-research-ed25519 / problem-solver-enhanced — отслеживаемая копия: их родной дом — пакет @dzhechkov/skills-analyst-manual, а расхождения подтягиваются командой dz sync-upstream. Знать это стоит: править копию внутри пака бессмысленно — правку затрёт следующая синхронизация.

💬 Просто попроси.
- «покажи, какие скиллы установил idea2prd» → ассистент выполнит npx @dzhechkov/skills-idea2prd list.
- «объясни, чем explore отличается от problem-solver-enhanced» → ассистент прочитает оба SKILL.md из .claude/skills/ и сравнит их роли.

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

Проблема — это боль без решения: «подрядчиков ищут только по знакомым, и качество лотерея». В формулировке есть боль и вопрос «как?», но нет продукта.

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

Развилка работает так:

1. на входе проблема → сначала аналитическая ветка, она превращает боль в проверенную идею продукта;
2. на входе идея → аналитическая ветка пропускается, сразу запускается конвейер PRD;
3. вход непонятен → ассистент задаёт ровно один уточняющий вопрос и не больше.

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

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

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

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

Шаг второй — goap-research-ed25519. Исследование: кто уже решает эту боль, какими способами, где дыры. Ключевая особенность — источники называются явно, а находки несут честную оценку уверенности. Исследование не доказывает истину, оно показывает, откуда взято утверждение.

Шаг третий — problem-solver-enhanced. Девять модулей разбора подряд: первые принципы, пять «почему», анализ ограничений, SCQA, теория игр, эффекты второго порядка, ТРИЗ, адвокат дьявола и синтез. На выходе — проверенная идея продукта: название, описание, аудитория, ключевые функции и то, чем она отличается от чужих решений.

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

💬 Просто попроси.
- «разбери мою боль по первым принципам, прежде чем предлагать продукт» → ассистент запустит problem-solver-enhanced и покажет разбор по модулям.
- «покажи, кто уже решает эту задачу и чем» → ассистент выполнит шаг исследования и приведёт находки с источниками.

Мира ожидала, что ассистент отработает всё разом и вывалит стопку файлов. Вместо этого он остановился после первой же фазы и спросил: «подтверди требования или внеси правки».

Это и есть режим MANUAL. Девять контрольных точек — три в аналитической ветке (бриф, исследование, идея продукта) и шесть в конвейере PRD (требования, стратегический DDD, архитектура, тактический DDD, псевдокод, тесты). После каждой конвейер печатает сводку сделанного и ждёт.

Отвечать можно по-разному:

• ok или «продолжай» — идём дальше;
• «скорректируй X» — правим конкретный элемент;
• «добавь Y» — дополняем недостающее;
• «пересмотри Z» — возвращаемся к решению;
• «стоп» — пауза с сохранением состояния.

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

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

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

Вот тот самый главный путь, ради которого ставят пакет. Мира прошла его целиком, и удобнее всего смотреть на него как на лестницу: каждая ступень опирается на предыдущую, и перепрыгнуть нельзя.

требования → стратегический DDD → решения ADR и схемы C4
     → тактический DDD → псевдокод → тесты и fitness → чек-лист выката

Что происходит на ступенях. Требования: функциональные и нефункциональные, пользовательские истории, пути пользователя, ограничения и допущения. Стратегический DDD — деление предметной области на ограниченные контексты, то есть на участки, внутри которых слова означают одно и то же; плюс карта связей между ними. ADR и C4: архитектурные решения с причинами и три уровня схем — контекст системы, контейнеры, компоненты.

Дальше конвейер спускается к деталям. Тактический DDD — агрегаты, сущности, объекты-значения, доменные события и схема базы. Псевдокод фиксирует алгоритмическую логику до кодогенерации, чтобы генератор реализовывал принятый дизайн, а не изобретал свой на ходу. Тесты и fitness-функции — сценарии на Gherkin и проверяемые архитектурные правила. Чек-лист выката закрывает путь: окружение, конвейер сборки, мониторинг, безопасность.

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

💬 Просто попроси.
- «покажи карту контекстов, прежде чем писать ADR» → ассистент остановится на фазе стратегического DDD и нарисует карту.
- «собери псевдокод только для агрегата заказов» → ассистент сузит фазу псевдокода до одного агрегата.

Мира дочитала черновик требований и споткнулась о фразу: «система ускоряет подбор подрядчика на 40%». Откуда сорок? Никто не мерил. Цифра появилась, потому что красиво звучит.

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

• MEASURED — измерено, и рядом назван воспроизводитель: команда, файл, прогон;
• CLAIMED — это чужое утверждение, которое ты пересказываешь, и назван автор;
• ESTIMATED — это оценка или цель, и названо основание, на котором она выбрана.

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

Проверить документы можно машинно: если в системе есть harness-инструмент dz, запусти dz claim-check docs/ --fail-on medium. Порог именно medium: на пороге high обычные непомеченные утверждения средней силы проскакивают мимо — то есть проверка становится зелёной ровно там, где она нужна.

💬 Просто попроси.
- «проверь мои документы на непомеченные числа» → ассистент запустит dz claim-check docs/ --fail-on medium и покажет находки.
- «убери из PRD все цифры, которые никто не мерил» → ассистент найдёт утверждения без пометки и либо удалит их, либо предложит тег с основанием.

Архитектурное решение легко написать так, что его невозможно проверить: «выбрали микросервисы ради масштабируемости». Красиво — и бесполезно: непонятно, что должно случиться, чтобы мы признали решение неверным.

Поэтому каждый ADR, который генерирует пакет, обязан нести стойку ## Confirmation. В ней два несущих поля. Load-bearing property — то самое свойство, ради которого решение принято. Required automated check — конкретная проверка, которая покраснеет, если свойство нарушено: fitness-функция вида FF-001 или сценарий .feature на Gherkin.

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

1. названный тест конкретен, а не заглушка вроде TBD или FF-NNN;
2. этот тест реально существует в выходе фазы 5 — идея FF-001 есть в таблице fitness-функций, файл .feature лежит в docs/tests/;
3. тест привязан именно к несущему свойству, то есть покраснеет при его нарушении, а не проверяет просто счастливый путь.

Любая незакрытая строка блокирует подпись фазы 5. Смысл в том, что стойка Confirmation превращает решение из прозы в обещание с механизмом проверки — и связывает фазу 3 с фазой 5 не по доброй воле автора, а по правилу конвейера.

💬 Просто попроси.
- «покажи таблицу ADR и их опровергающих тестов» → ассистент напечатает сводку с несущим свойством и названным тестом для каждого решения.
- «этот ADR ничем не проверяется — допиши fitness-функцию» → ассистент добавит проверку и привяжет её к несущему свойству.

Мира запустила конвейер во второй раз и сразу заметила разницу. Первый прогон был чистым листом; второй начался с того, что конвейер вспомнил уроки первого.

Механика простая: у этой петли два конца. В начале — recall. Ещё до ворот 0, если в системе есть harness-инструмент dz, конвейер выполняет dz recall по ключевым словам задачи и вкладывает найденные уроки в бриф. Это прошлые находки: удачная граница контекста, доменное ограничение, которое однажды укусило, форма fitness-функции, которая сработала.

В конце — teach. После последней фазы конвейер сравнивает свои новые уроки с тем, что уже вспомнил в начале. Уже известное не переучивается. По-настоящему новое записывается командой dz teach — по одному уроку за вызов. Честный результат «ноль новых уроков» тоже бывает и не считается провалом.

Одна деталь решает, работает ли петля вообще: склад должен быть один. И recall, и teach привязываются к одному и тому же абсолютному пути проекта через --project. Если начало читает из одного склада, а конец пишет в другой, уроки копятся в разных местах и не подкрепляют друг друга — петля разомкнута, хотя обе команды отработали успешно.

Всё это включается само, только если dz есть в системе. Нет — конвейер молча работает как раньше, без памяти.

💬 Просто попроси.
- «вспомни, что мы уже решали про границы контекстов в этом проекте» → ассистент выполнит dz recall и вложит находки в бриф.
- «запиши урок: эскроу нельзя моделировать внутри контекста каталога» → ассистент выполнит dz teach с привязкой к каноническому складу проекта.

Мира привыкла, что у инструмента десятки ключей и половина из них непонятна. Здесь всё короче: у пакета ровно пять команд, и каждая делает одну вещь.

init ставит пак в текущий проект и работает по умолчанию — если подкоманду не указать, выполнится именно она. update обновляет пак до свежей версии. remove убирает его из проекта. list показывает, что установлено. doctor проверяет здоровье установки — на месте ли скиллы, не побились ли файлы.

К любой из них добавляются четыре флага: --force продавливает действие, --dry-run показывает, что произошло бы, ничего не меняя, --help печатает справку, --version — версию.

Правило, которое экономит нервы: сначала --dry-run, потом без него. Особенно с remove и update — сухой прогон печатает список файлов, которых коснётся команда, и это единственный дешёвый способ убедиться, что она понимает твой проект так же, как ты.

Если что-то ведёт себя странно — скилл не подхватывается, слэш-команда не появилась, — начинай с doctor. Он отвечает на вопрос «установка вообще цела?» раньше, чем ты начнёшь искать причину в ассистенте.

💬 Просто попроси.
- «проверь установку idea2prd» → ассистент выполнит npx @dzhechkov/skills-idea2prd doctor и разберёт вывод.
- «покажи, что удалит remove, но не удаляй» → ассистент выполнит npx @dzhechkov/skills-idea2prd remove --dry-run.

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

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

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

Проверка уроков тоже про форму. Слой памяти отклоняет записи, похожие на личные данные, — почта, телефон, номер записи. Но он не решает, о методе урок или о человеке: это остаётся на суждении автора.

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

И одна деталь про подпись пакета. Манифест подписи описывает ровно те файлы, которые пакет отгружает, а не всё, что лежит у автора в рабочем дереве. Раньше он подписывал и то, что в поставку не попадает, — и у каждого получателя проверка честно сообщала о недостающих файлах, то есть пакет читался как подделанный. Урок общий: подпись должна описывать то, что реально доехало до получателя.

💬 Просто попроси.
- «набор документов готов — реализуй агрегат заказов по псевдокоду» → ассистент перейдёт к коду, взяв документы как задание.
- «пройдись по PRD и покажи все числа, которые я не могу подтвердить» → ассистент соберёт список утверждений, требующих твоей проверки.