Спека после релиза: закрыть, а не хранить

Последний тикет смёржен, фича на проде. Перед вами спека: аккуратный текст про то, как устроена новая часть системы, понятный и человеку, и агенту. Рука тянется сохранить её в docs/specs/ — пусть будет документацией. Не спешите.

Зачем это нужно

Решение «что делать со спекой» кажется организационной мелочью, но оно напрямую влияет на то, что агент прочитает в следующий раз. Агент исследует репозиторий сам: ищет файлы, открывает то, что выглядит релевантным. Всё, что лежит в репозитории, рано или поздно попадёт к нему в контекст. Значит, вопрос звучит иначе: какой текст вы хотите, чтобы агент принял за правду о коде через полгода?

Как это устроено

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

Спека и код расходятся. Код меняется каждую неделю, а спеку никто не обновляет, пока она не мешает. Через несколько итераций «документация» описывает систему, которой уже нет.

Агент доверяет удобному. Спека короче, плотнее и проще для чтения, чем код. Если агент нашёл в репозитории старую спеку, высок шанс, что он остановится на ней и не пойдёт в первичный источник. Так появляются уверенные ответы и правки, основанные на устаревшем описании.

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

У трекера есть и другие плюсы перед markdown-файлом на ноутбуке:

• спека общая: её видит команда, её можно обсудить и найти, даже если вас не было на созвоне;
• состояние не зависит от рабочей копии: смена ветки, worktree или ноутбука не теряет и не дублирует спеки и тикеты.

Это расходится со spec-driven development, где спеки хранятся в репозитории и считаются источником правды вместо кода. Подход рабочий, если команда дисциплинированно обновляет спеки при каждом изменении. Если такой дисциплины нет, риск дрейфа ложится прямо на агента — и курс предлагает его не брать.

Практика

Откройте в Cadence трекер и найдите спеку, по которой вы уже сделали тикеты. Перед тем как закрыть её, спросите агента:

Read issue #4 and compare it with the current code of the analytics page.
List every place where the spec and the code disagree.

Посмотрите на ответ. Даже сразу после реализации обычно находится пара расхождений: решение, принятое на ревью, переименованное поле, урезанный сценарий. Это и есть дрейф, только в самом начале. Теперь закройте спеку как выполненную.

Подводные камни

• Удалять спеку тоже плохо. Вы теряете бесплатную историю решений: зачем сделали так, а не иначе.
• CLAUDE.md — не место для спеки. Он загружается в каждую сессию, и устаревший пересказ фичи будет стоить контекста и вводить агента в заблуждение каждый раз.
• Правило касается выполненных спек. Пока фича в работе, спека — живой документ, и её правят (об этом — в следующем Bite).

Вывод: спека — временный артефакт, который описывает кусок работы; когда работа сделана, правду о системе говорит код, а спека уходит в архив трекера.

Проверь себя

Источники

• Anthropic, How Claude remembers your project — CLAUDE.md загружается в начале каждой сессии
• По мотивам AI Coding Crash Course, AI Hero: «Should You Keep Your Specs?»