Вы не напишете спецификацию с первого раза, даже с помощью Fable

В блоге Anthropic вышла статья Thariq Shihipar, в которой он рассказывает, как агент помогает находить ему Неизвестные Неизвестные (Unknown Unknowns). Я думаю, что мысли из статьи также очень важны для Spec Driven Development, и хорошо объясняют, почему спецификация это живой документ, и получение финального документа возможно только после того, как код уже написан, (ну или во всяком случае, одновременно с этим моментом). Если вы считаете, что Spec Driven Development — это будущее AI‑assisted разработки (намеренно не говорю вайбкодинг), прошу под кат.

Начнем с базового постулата — карта местности это не реальная местность, а всего лишь карта, которая эту местность как‑то описывает. Если мы воспользуемся этой метафорой, то наша постановка задачи агенту это как раз предоставление ему карты. При этом разница между картой и реальным путем состоит из неизвестностей (unknowns), и каждая неизвестность — это место, где агенту приходится угадывать.

Автор оригинальной статьи раскладывает их на четыре типа:

• Известное известное (known knowns) — то, что вы уже можете сформулировать. Это ваше намерение.

• Известное неизвестное (known unknowns) — то, чего вы пока не поняли, но знаете, что не поняли.

• Неизвестное известное (unknown knowns) — то, что для вас настолько очевидно, что вы никогда не стали бы это записывать.

• Неизвестное неизвестное (unknown unknowns) — то, о чём вы вообще не задумывались.

И вот в чём загвоздка. Спецификация или промпт, написанные за один присест, вмещает только первую категорию. Остальные три живут не у вас в голове — они живут на местности. А местность, по которой вы не прошли, нанести на карту нельзя.

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

Начинаем с намерения

Мы начинаем с того, что знаем: что мы хотим получить и примерно как этого достичь. Наше известное известное (known knowns). Это первый грубый набросок карты — достаточно, чтобы задать направление, но недостаточно, чтобы по нему идти.

Разведка местности агентом

Прежде чем что‑либо строить, агент изучает местность, по которой предстоит пойти. Он проходит нашему коду. Он читает нашу базу знаний, если мы подключили её через MCP или иным способом. И вытаскивает наружу то, что мы упустили: детали, которые нам очевидны (неизвестное известное), и ограничения, которые мы не видели (неизвестное неизвестное).

Именно здесь чинится значительная часть первого черновика. Агент задаёт вопросы, ответить на которые мы сами не догадались (или намеренно пропустили), и карта обрастает деталями ещё до того, как маршрут будет построен.

Механизм комментирования кода и спецификаций в SpecBuddy позволяет это сделать сильно удобнее, чем писать в чат.

Пройдите — и перерисуйте

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

Теперь мы получаем план и запускаем его — по шагу за раз ну или все сразу, если мы смелые. Вот здесь и раскрывается настоящая местность. Постоянно находится что‑то новое: граничные случаи, ограничения, решения, которые противоречат той спецификации, с которой мы начинали.

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

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

Готовую карту стоит сохранить

Когда работа сделана, спецификация наконец совпадает с реальной местностью. Она объясняет, почему мы пошли конкретным путем. Закоммитьте её вместе с кодом.

Через полгода кто‑то спросит, почему фича работает именно так. И ответ не придётся выкапывать из диффа. Он в спецификации: что вы хотели, что нашёл агент, какие граничные случаи заставили что‑то поменять, какие решения вы приняли и почему.

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

Если вам нравится такой подход, попробуйте SpecBuddy. Плагин для JetBrains IDEs, бесплатный. Работает с OpenCode, Claude Code и Codex. В скором времени мы выпустим поддержку OpenSpec.

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

Источник: habr.com