AIDiveДесять разработчиков, одна папка
Superpowers — это плагин Claude Code (286 000 звёзд на GitHub), чьи skills пишут specs и implementation plans в виде markdown-файлов и коммитят их в репозиторий. По умолчанию все эти файлы попадают в одну папку, docs/superpowers/. В июне мейнтейнеры Okama, финансовой библиотеки на Python, обнаружили, что восемь implementation plans, написанных там агентом — именно так, как задумывал плагин — были отрендерены как публичные веб-страницы на Read the Docs. Заметили это уже после релиза.
Теперь масштабируем: front-end команда из десяти разработчиков, четыре отряда, один репозиторий, и каждый разработчик генерирует такие файлы. На стол лида ложатся три вопроса. Что именно мы версионируем? Является ли дрейф проблемой, если spec называет путь, удалённый два спринта назад? И кто управляет папкой? Утечка Okama произошла не из-за коммита. Она произошла из-за коммита без правила. Эта статья даёт вам пять правил.
Каждый инструмент коммитит файлы
Superpowers никогда не спрашивает, коммитить ли файл. Строка 18 его planning skill сохраняет каждый план в docs/superpowers/plans/ с датой, один файл на фичу. Brainstorming skill пишет design-документ и коммитит его тем же шагом — раньше, чем вы увидели план.
Это не особенность Superpowers. Каждый крупный spec-driven инструмент делает тот же выбор:
| Инструмент | Издатель | Где живут specs |
|---|---|---|
| Superpowers (286 000 звёзд) | obra | docs/superpowers/, одна папка на всё |
| Spec Kit (136 000 звёзд) | GitHub | одна пронумерованная папка на фичу, в ветке этой фичи |
| Kiro | Amazon | .kiro/specs/, одна папка на фичу |
| AI-native SDLC playbook | Anthropic | один закоммиченный артефакт на каждый этап: intent, spec, plan, diff, review findings, incident record |
Kiro продаёт папки по фичам как способ дать команде параллельно работать над разными фичами. Плейбук Anthropic, опубликованный в августе, идёт дальше: каждый этап коммитит артефакт, который может прочитать следующий этап. Так что вопрос был не в том, коммитить ли, а на вопрос "куда" отвечает любой инструмент. Кто владеет файлом и когда он мёртв — не отвечает никто. Именно этот пробел закрывают пять правил.
Три сценария провала
Закоммиченные планы проваливаются тремя разными способами.
Провал 1: генератор документации. Сборка документации, которая рендерит любой markdown-файл под docs/, независимо от того, упомянут ли он в содержании, отправляет папку с планами вместе с руководством. Именно это случилось с Okama.
Провал 2: ветка. Superpowers issue 1246 сообщает, что brainstorm коммитит план прямо в main. Один пользователь считает 10–15 коммитов за сессию, новый каждые несколько изменений. Запрос из этого треда укладывается в одну строку: никаких plans и specs в main-ветке.
Провал 3: дрейф. Spec drift — это тихий провал: код развивается, а spec не меняется. Биргитта Бёкелер из Thoughtworks называет три уровня spec-driven разработки:
| Уровень | Значение |
|---|---|
| Spec-first | Написан, использован один раз |
| Spec-anchored | Поддерживается на протяжении жизни фичи |
| Spec-as-source | Человек редактирует только spec |
Superpowers пишет spec-first документы и хранит их навсегда. По умолчанию вы получаете spec-anchored хранение с заботой уровня первого черновика: никто не обновляет файл, а агент в следующем квартале читает его как истину. TrueFoundry формулирует это прямо: дрейф неизбежен в spec-first практике и управляем в spec-anchored практике, но только если расхождение обнаруживаемо.
Репозиторий с 41 spec и 9 agent-файлами — это не проблема аккуратности. Это 41 неверсионированный входной параметр поведения. Реакция самой Бёкелер: она лучше почитает код, чем все эти markdown-файлы. План, который никто больше не открывает — мусор. План, который открывает агент — это инструкция, а устаревшая инструкция — это неверная инструкция.
Правило 1: один дом на отряд, с владельцем
Правило 1: у папки есть владелец, и владелец — отряд, а не плагин. Начиная с версии 5 Superpowers уважает инструкции в CLAUDE.md вашего проекта больше своих собственных дефолтов. Скажите, куда идут планы — и они пойдут туда.
Однако таблицы путей недостаточно. В issue 939 пользователь написал таблицу output-путей, а модель следовала конкретному пути внутри skill и пропустила таблицу. Собственная заметка skill про override — это скобка в тексте. Одна жирная императивная строка исправила это с первой попытки: specs нужно сохранять здесь, а не там, с явным указанием дефолтного пути как того, что нужно избегать.
Разметка — одна папка на отряд (checkout, search, accounts, design-system), у каждой свои specs и plans. В монорепозитории строку размещают в CLAUDE.md самого пакета. Claude Code подгружает файл поддиректории по запросу, когда читает оттуда, а документация говорит, что за файл каждой директории обычно отвечает её владелец. Инженеров, которые никогда не устанавливали плагин, это не затрагивает: строка срабатывает только тогда, когда skill спрашивает, куда сохранять.
Затем дайте платформе закрепить владение. Одна строка CODEOWNERS на папку отряда — и каждое ревью spec попадает к людям, которым с ним жить. Одна оговорка: override — это prompt, а не настройка. Проверяйте первый spec после каждого релиза плагина.
Правило 2: личное против общего
Правило 2: не каждый план — командный артефакт. Первый, кто попросил у Superpowers настраиваемое расположение (issue 337), сформулировал это лучше всех: файлы планов могут быть личными рабочими документами, а не артефактами проекта.
У личной стороны есть свой файл. CLAUDE.local.md лежит рядом с общим файлом, загружается после него, а документация советует самому добавить его в git-ignore. Ваш редирект в личную папку живёт там, и больше никто его не видит. Для самой папки у Git есть ignore-файл, который никогда не касается общего дерева: .git/info/exclude — локальный для клона, никогда не коммитится и не требует pull request. Плагин уже делает это для собственного scratch-пространства: начиная с версии 6.0.3 его рабочая директория создаёт внутри себя .gitignore с содержимым *, так что она сама себя игнорирует, не трогая отслеживаемый файл.
Общая сторона — это всё, что прошло gate ревью, который brainstorm уже запускает: spec написан, ревью запрошено, одобрено вторым человеком. После одобрения он перемещается в папку отряда. Без одобрения — остаётся личным. Оба варианта пишутся в ветке, никогда в main. Две строки в общем CLAUDE.md делают это: specs и plans считаются началом фичи, и worktree создаётся до их написания.
Одно ограничение: git-ignored план не путешествует. Мейнтейнеры Okama сначала попробовали игнорировать папку и откатили это, потому что планы перестали синхронизироваться между машинами и агентами. Личное значит личное.
Правило 3: жизненный цикл, как у ADR
Правило 3: у spec есть статус, и мёртвый spec об этом говорит. Идее 15 лет. Майкл Найгард в 2011 году предложил хранить architecture decision records (ADR) в репозитории, по одному пронумерованному файлу на каждую. Решение сначала proposed, затем accepted. Когда более поздняя запись меняет его, старая помечается deprecated или superseded со ссылкой на замену. Если решение отменяется, старая запись сохраняется, но помечается superseded.
Применительно к specs, каждый общий spec открывается пятистрочным заголовком, который агент уже читает:
| Поле | Назначение |
|---|---|
| status | proposed, accepted, superseded |
| superseded-by | заменяющий spec |
| owner | отряд |
| touches | пути, о которых spec делает утверждения |
| review date | когда его проверяли последний раз |
Никогда не редактируйте accepted spec в другое решение. Напишите следующий, сославшись на него, и история останется честной. Одно исключение, сформулированное в плейбуке Anthropic: когда реализация отходит от плана, обновите план тем же коммитом. План путешествует вместе с diff, который его нарушил, и это можно закрепить хуком.
Spec Kit называет три способа жизни spec. Flow-forward: новая папка на каждую фичу, старые сохраняются как история. Living spec: spec — это контракт, а остальное перегенерируется. Flow-back: сборка переформирует spec. Их правило — не оставлять изменение в tasks или коде, если spec ещё говорит что-то другое. Это осознанный выбор spec-anchored.
Ограничение: статус — это метаданные, которые ставит человек. Агент не станет сам помечать свой spec как superseded, если ваш CLAUDE.md не скажет ему об этом, и даже тогда ревью должно это заметить.
Правило 4: gate на дрейф в CI
Правило 4: spec, который врёт о дереве файлов, роняет сборку. Статья, назвавшая эту проблему, опубликованная в июне, называет это silent spec-code drift: код развивается, спецификация не меняется, а расхождение остаётся невидимым, пока его исправление не становится дорогим. Её ответ — drift gate, блокирующее условие merge.
Проверка проще, чем звучит. Для каждого spec, чей заголовок говорит accepted, берутся пути, которые он называет — в backticks или в строке touches — и проверяется, что каждый существует. Отсутствующий путь — падающая сборка, с именем spec в логе. Файлы superseded и proposed пропускаются: только accepted specs делают утверждения о дереве файлов, поэтому только accepted specs проверяются. TrueFoundry описывает это как запланированный diff, а не археологию после инцидента: spec — это scaffold, а изменение spec — это изменение policy.
Люди уже запускают ручную версию этого. Один комментатор просит Claude сравнить файлы specs с кодовой базой и завести тикеты на то, что отсутствует. Скрипт делает это на каждом pull request, бесплатно.
Вторая защита — та, что применила Okama: исключить папку из сборки документации. Одна строка в конфигурации Sphinx оставляет файлы в Git, но убирает их из HTML.
Ограничение: проверка путей ловит удалённые файлы, а не изменённое поведение. Spec может называть каждый существующий файл и всё равно описывать API, которого больше нет. Для этого нужны ревью и правило того же коммита.
Правило 5: бюджет размера и его цена
Правило 5: большая часть работы не заслуживает spec. Данные о накладных расходах spec-driven подхода единообразны:
| Эксперимент | Результат |
|---|---|
| Marmelab, Spec Kit на фиче, показывающей текущую дату | 8 файлов, 1300 строк текста спецификации |
| OpenSpec bake-off, те же требования со spec-инструментом против Claude Code без него | на 50% больше кода, на 50% выше цикломатическая сложность, вдвое дольше, втрое дороже |
| Команда, месяцами работающая по spec-driven development | в 2–3 раза больше токенов, примерно вдвое дольше, большая цена координации для изменений, которым она не требовалась; никаких доказательств, что код стал лучше |
Bake-off — это один эксперимент, а не benchmark, и его автор сам это говорит. Но направление сохраняется. Поэтому правило: пишите spec, когда работа пересекает границу отряда или будет прочитана снова через 90 дней. Всё остальное — это prompt.
Superpowers уже сортирует каждый запрос по трём путям: spike, bounded, architectural. Spec пишется только на architectural-пути. Держите bounded-путь bounded, а spec — около 300 строк. Практики добавляют два правила: не делайте spec слишком большим и читайте сгенерированные specs.
Ограничение работает в обе стороны. Тот же bake-off нашёл три пробела, которые обычный прогон пропустил. Spec покупает покрытие, а не скорость. Платите за него там, где покрытие важно.
Вердикт: коммить, потом governance
Возвращаемся к трём вопросам лида. Что версионировать: одобренные specs и plans, в ветке, в папке отряда. Дрейф: заголовок со статусом и gate в CI. Governance: владельцы и правило размера.
Пять правил, и ни одно из них сегодня не закреплено инструментом. Issue про override открыт. Issue про main-ветку открыт. Pull request, переставивший инструкцию, закрыт без merge. Команда, которую обожгло, сохранила практику: 8 planов и 6 specs, закоммичены, исключены из сборки документации.
Возражение Бёкелер остаётся в силе. С заголовком статуса и бюджетом размера вы читаете только accepted specs, и их меньше. Что вы получаете в итоге — это то, что плейбук Anthropic называет audit trail: кто что запросил, что произвёл агент и кто это одобрил.
Это процесс, а не инструментарий: файл CLAUDE.md, файл CODEOWNERS, заголовок и скрипт на пятнадцать строк. И если команда не будет ревьюить запрос на CODEOWNERS, она не будет ревьюить и spec. В этом случае .gitignore был бы честным выбором.
