AI Skill: от черновика к проверенному SRS
В посте D3: Разработка, управляемая документацией я доказывал, что самый выгодный ход в жизни фичи — написать полную спецификацию до того, как появится код. В посте Документация в эпоху ИИ — что документация стала новым исходным кодом, и что любой агентский скил хорош ровно настолько, насколько хороша документация, которую он читает. Оба поста опираются на одно негласное допущение: что хорошая спецификация действительно будет написана.
Именно на этом допущении команды всегда и спотыкались. Поэтому здесь я максимально приближаю объектив к одному конкретному ответу на вопрос «а как надёжно произвести эту спецификацию?» — к одному переиспользуемому скилу, который берёт черновой документ-исследование и превращает его в аккуратный SRS, опирающийся на код, а затем поручает второму агенту проверить результат, прежде чем вы на него положитесь.
Сначала — что такое скил?
Скил (skill) — это именованная переиспользуемая процедура, которую агент может вызвать: папка с файлом-инструкцией SKILL.md (и, опционально, со вспомогательными агентами, скриптами или шаблонами), в которой закодировано, как хорошо выполнять повторяющуюся задачу. Вместо того чтобы каждый раз заново объяснять один и тот же многошаговый процесс в новом промпте, вы записываете его один раз — и агент ему следует: те же шаги, та же планка качества, тот же формат вывода при каждом запуске.
Это разница между «иди напиши спецификацию», сказанным новичку, и чек-листом, который старший инженер отшлифовал на десятке фич. Скил — это и есть такой чек-лист, ставший исполняемым.
Проблема: разрыв между черновиком и спецификацией
Любая фича начинается с чего-то сырого — пунктов в документе, скриншота, абзаца от продакта, нескольких заметок с созвона. Превратить это в спецификацию, по которой разработчик сможет строить, — реальная работа, и она проваливается четырьмя предсказуемыми способами:
- Остаётся расплывчатой. В черновике написано «показать пользователю его элементы». Не написано, что видит разлогиненный пользователь, что показывается, пока список грузится, что — когда список пуст, и что происходит при ошибке запроса. Именно в этих пробелах и рождаются баги.
- Не опирается на код. Спецификация, написанная только по черновику, выдумывает имена модулей, угадывает форму API и игнорирует паттерны, которые уже есть в репозитории. Потом разработчик тратит первый день на сверку спецификации с реальностью.
- Расползается формат. Каждый пишет спецификации немного по-своему, поэтому никакие два документа не читаются одинаково — а LLM, которая прочитает их позже (см. два предыдущих поста), получает разнородный корпус.
- Никто её не проверяет. Спецификации верят потому, что она существует, а не потому, что её сверили. Ошибки доживают до самого кода.
Это и есть та дорогая, скучная работа, дешевизна которой — обязательное условие для D3. Скил — это способ сделать её дешёвой и надёжной: не за счёт того, что пишешь быстрее, а за счёт того, что вся дисциплина закодирована один раз.
Анатомия скила
Скил — это папка из двух частей: SKILL.md, задающий рабочий процесс, и вспомогательный агент-рецензент, которого он запускает ближе к концу. Вот метаданные-триггер в начале SKILL.md:
1 | --- |
description — не украшение, а то, как агент решает, когда взяться за этот скил. Формулировка вокруг реальных слов пользователя («у меня есть черновик», «задокументируй фичу») и делает вызов автоматическим, а не тем, что надо помнить самому.
Тело SKILL.md — это рабочий процесс из восьми шагов. По отдельности шаги важны меньше, чем форма, которую они образуют, поэтому вот он целиком:
1 | 1. Прочитать черновик → извлечь скоуп, экраны, модули, что расплывчато |
Четыре из этих шагов — там, где сосредоточена настоящая выгода.
Шаг 2 — закрыть пробелы по реальному коду
Это шаг, который отделяет настоящую спецификацию от красиво оформленной догадки. Вместо того чтобы развивать черновик в его же терминах, агент исследует код и документацию параллельно, чтобы заполнить всё, что черновик оставил расплывчатым:
- В документации: прочитать индекс, чтобы понять, что уже есть и как оно организовано; если у фичи уже есть папка — прочитать её спецификацию и сквозные технические заметки (навигация, авторизация, диплинки).
- В коде: найти grep’ом модули, относящиеся к фиче; прочитать соответствующие файлы состояния/логики, чтобы узнать реально реализованное поведение; свериться с графами навигации, где находятся экраны; прочитать интерфейсы API и модели данных; проверить флаги, управляющие раскаткой.
Главная инструкция здесь вот какая: если поведение выведено из кода, а не заявлено в черновике, его всё равно правильно включить — вы же его проверили. Именно это правило превращает расплывчатый черновик в спецификацию, опирающуюся на то, что система делает на самом деле.
Шаг 3 — спрашивать только то, что нельзя вывести
После исследования агент определяет, что всё ещё неясно, и спрашивает — но скил прямо требует, чтобы это был крайний случай, чтобы вопросы шли пачкой и только по настоящим неизвестным: неоднозначный скоуп, противоречия между черновиком и кодом, неописанное состояние пользователя («что должен видеть гость?») или интерфейс, у которого нигде нет дизайн-референса. Нельзя спрашивать о том, что можно выяснить самому из кода или документации. В этом и разница между ассистентом, который уважает ваше время, и тем, кто превращает любую задачу в допрос.
Шаг 5 — закрепить формат за каноническим примером
Скил не описывает формат вывода абстрактно — он указывает на реальную, уже существующую спецификацию как на эталон стиля и перечисляет обязательные разделы: обзор, таблицу «модуль → назначение», функциональные требования по каждому экрану с разбивкой по состояниям пользователя (гость, бесплатный, платный…), интеграцию с API и флаги. Правила стиля конкретны: повелительные формулировки («Нажатие на X открывает Y»), явная персистентность («хранится локально» против «только в рантайме»), точные имена модулей в обратных кавычках. Привязка к примеру и держит все спецификации скила одинаково читаемыми — что как раз и делает итоговый корпус понятным для следующего агента.
Шаги 6–7 — независимый рецензент со своим чек-листом
Эту часть чаще всего пропускают самодельные промпты — а она важнее всего. Когда SRS написан, скил запускает отдельного агента-рецензента со свежим контекстом и собственными инструкциями. Это не расплывчатое «глянь-ка» — у рецензента настоящий чек-лист:
- Полнота — покрыт ли каждый экран? Каждое состояние пользователя? Состояния загрузки, пустоты и ошибки? Каждый интерактивный элемент? Каждый флаг?
- Точность — действительно ли существуют в кодовой базе указанные имена модулей, эндпоинты API и имена флагов? Имя, которое никуда не ведёт, — это критическая проблема, а не придирка.
- Согласованность — не противоречит ли это какой-нибудь уже задокументированной фиче?
- Формат и открытые вопросы — соблюдена ли принятая структура и что разработчику всё ещё придётся спросить перед сборкой?
Рецензент завершает одним из трёх вердиктов — APPROVED, APPROVED WITH NOTES или NEEDS REVISION — и процесс ветвится по нему: одобрить и закончить, применить замечания и закончить либо доработать и запустить рецензента снова. Его финальную инструкцию стоит процитировать: «Будь прямым. Не раздувай находки ради видимости тщательности и не смягчай критические проблемы ради вежливости. Цель — пригодный документ, а не идеальная оценка».
Два агента, два контекста, две задачи: один пишет, полностью зная черновик и код, другой проверяет свежим взглядом по чек-листу. Именно это разделение и ловит слепые зоны автора — по той же причине, по которой мы не даём людям мёржить собственные PR без ревью.
Почему скил, а не просто хороший промпт
Всё это можно один раз вставить в чат и получить приличный SRS. Причина сделать из этого скил — во всём, что происходит во второй раз:
- Согласованность. Каждая спецификация выходит в одной и той же форме, поэтому корпус остаётся читаемым — и для людей, и для агентов, которые прочитают его позже.
- Планка качества путешествует. Правило закрытия пробелов, правило «не спрашивай то, что можно вывести», чек-лист рецензента — это выстраданные уроки. Скил фиксирует их один раз, чтобы они применялись при каждом запуске, а не жили в чьей-то голове.
- Это контрольная точка, а не чёрный ящик. Процесс намеренно заканчивается до реализации: SRS — это и есть результат, проверенный и согласованный, ровно тот артефакт, который D3 хочет зафиксировать до старта кода.
- Он компонуется. Этот скил производит спецификацию; другие скилы (спланировать фичу, реализовать её, отревьюить PR) её потребляют. Весь конвейер D3 — это скилы, передающие друг другу типизированные артефакты.
Промпт — это разовая вещь. Скил — это процесс, которому можно доверить отработать одинаково и в пятницу в 17:00, и в тот первый раз, когда вы его записали.
Об инструментах
Я описываю это на примере Claude и его формата скилов, потому что на нём это и работает, но сама идея переносима. Скил — это всего лишь записанная процедура плюс опциональный агент-рецензент; любая агентская среда, которая умеет читать файлы, искать по кодовой базе и запускать второй проход, способна сделать то же самое. Выгода не в вендоре, а в трёх вещах, которые доступны любой способной модели: рабочий процесс, достаточно конкретный, чтобы следовать ему по шагам; дисциплина сверять с реальным кодом, а не угадывать; и независимый рецензент, чтобы ничего не уехало непроверенным.
Итог
D3 говорит: пиши спецификацию до кода. «Документация — новый исходный код» говорит: эту спецификацию и будет читать каждый последующий агент. Этот скил — маленькая конкретная машина, которая делает производство такой спецификации дешёвым и заслуживающим доверия: прочитать черновик, закрыть его пробелы по реальному коду, спросить только то, что нельзя вывести, написать в единой форме и дать второму агенту разобрать её по косточкам, прежде чем на неё кто-то положится. Закодируйте эту дисциплину один раз — и сырой черновик станет проверенным справочником. Каждый раз, а не только когда кто-то вспомнит, что надо быть внимательным.