Управление AI-спеками и планами в Git: пять правил, drift gate, источники и чеклист

TL;DR

• Коммитьте спеки и планы, написанные ИИ. Все инструменты и так делают это по умолчанию; открытый вопрос в управлении ими.
• Дайте каждой команде одну папку со строкой в CODEOWNERS, чтобы изменение спеки запрашивало ревью у владельцев кода.
• Добавьте в каждую общую спеку заголовок в стиле ADR: status, superseded-by, owner, затронутые пути, дата ревью. Никогда не переписывайте принятую спеку в новое решение.
• Запустите drift gate в CI: для каждой принятой спеки валите сборку, если путь, который она называет, больше не существует.
• Перенаправьте путь вывода одной жирной императивной строкой в CLAUDE.md, личные планы держите в CLAUDE.local.md и .git/info/exclude, пишите в ветке, а не в main.
• Пишите спеку только для работы, которая пересекает границу команды или будет перечитываться через 90 дней. Прогоны по спекам стоят примерно вдвое больше времени и втрое больше токенов.

Что говорят источники

Значения по умолчанию: коммитят все

Скилл writing-plans из Superpowers сохраняет планы в docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md, а строкой ниже сказано, что пользовательские настройки места хранения планов переопределяют это значение по умолчанию s1. Скилл brainstorming записывает утверждённый дизайн в docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md и заканчивается словами «Commit the design document to git» s2. Spec Kit раскладывает specs/[branch-name]/ с spec.md, plan.md и tasks.md, нумерованными 001, 002, плюс constitution в memory/constitution.md s6. Kiro хранит .kiro/specs/ с одной папкой на фичу и предлагает командам «collaborate with team members on different features simultaneously» s8. Плейбук Anthropic говорит прямо: «Every stage commits an artifact the next stage can read», «Commit the approved plan as plan.md» и «When implementation departs from the plan, update plan.md in the same commit» s5.

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

Сбой 1: утечка в публичную документацию

Issue 1690, открытый 2026-06-05, сообщает, что папка docs/superpowers/ по умолчанию может выпустить внутренние планы в опубликованную документацию через Sphinx и Read the Docs s15. Пострадал проект okama, Python-библиотека с 273 звёздами. Его фикс-коммит вернул 5 планов и 3 спеки, убрал одну строку из .gitignore и называется «track superpowers plans/specs in git, excluded from the Sphinx build» s21. В строке 84 docs/conf.py теперь exclude_patterns = ["_build", "Thumbs.db", "superpowers"] s22. Сегодня в папке 8 планов и 6 спек s15. Команда сохранила практику и починила сборку.

Сбой 2: планы в main

Issue 1246, открытый 2026-04-22 и всё ещё не закрытый, спрашивает, почему план коммитится до появления ветки разработки. Один пользователь пишет «I'm getting 10 to 15 commits», другой: «Yes please, no plans and specs on main branch!» s16. Плагин не навязывает правило про ветки; чеклист ниже навязывает.

Сбой 3: переопределения, которые модель пропускает

Issue 337 закрыт 2026-03-10 заметкой мейнтейнера: начиная с v5.0 плагин ставит CLAUDE.md проекта выше собственных значений по умолчанию, пример строки: «Save plans to ~/.superpowers/plans/ instead of docs/plans/» s17. Issue 939 на v5.0.6 показывает предел: таблица «Output Paths» в CLAUDE.md была проигнорирована, и спеки продолжали попадать в docs/superpowers/specs/. Сработал обходной путь: жирная императивная строка под таблицей, design specs MUST be saved to docs/design-docs/, NOT docs/superpowers/specs/ s18. Pull request 1020, менявший порядок инструкции, закрыт без слияния s19. Переопределение это промпт, а не настройка: перепроверяйте его после каждого релиза плагина. Для собственных временных файлов плагина issue 1780 закрыт в v6.0.3 самоигнорируемой папкой .superpowers/sdd/, которая кладёт в себя свой .gitignore с содержимым * s20.

Личное и общее

Claude Code документирует это разделение: «For private per-project preferences that shouldn't be checked into version control, create a CLAUDE.local.md at the project root. It loads alongside CLAUDE.md and is treated the same way. Add CLAUDE.local.md to your .gitignore so it isn't committed» s3. Файлы CLAUDE.md по каталогам подгружаются по требованию, «Commit these files to the repository so teammates inherit them. Each directory's owner typically maintains its file», а настройка claudeMdExcludes скрывает файлы других команд в монорепозитории s4. У Git три слоя игнорирования: $XDG_CONFIG_HOME/git/ignore, $GIT_COMMON_DIR/info/exclude и .gitignore s24; средний прячет папку с личными планами, не трогая общий файл. CODEOWNERS закрывает вторую половину, владение: «Code owners are automatically requested for review when someone opens a pull request that modifies code that they own» s23.

Жизненный цикл, как у ADR

Пост Майкла Найгарда 2011 года это образец: решение «may be 'proposed' if the project stakeholders haven't agreed with it yet, or 'accepted' once it is agreed. If a later ADR changes or reverses a decision, it may be marked as 'deprecated' or 'superseded' with a reference to its replacement», и «If a decision is reversed, we will keep the old one around, but mark it as superseded» s9. Thoughtworks делит использование спек на spec-first (пишется один раз под задачу), spec-anchored (поддерживается, чтобы развивать фичу) и spec-as-source (правится только спека), а автор добавляет: «I'd rather review code than all these markdown files» s10. Superpowers пишет файлы spec-first и хранит их вечно: дрейф по умолчанию.

Дрейф и gate

Статья на arXiv называет проблему «silent spec-code drift: code evolves, the specification does not, and the divergence becomes invisible until it is costly to repair» и предлагает «a drift gate that makes spec-code divergence a blocking merge condition» s11. Собственное руководство Spec Kit предупреждает: «Do not leave a lower-level change in tasks.md or code if spec.md still says something different» s7. TrueFoundry формулирует довод об управлении прямо: «forty-one specs and nine agent files aren't a tidiness problem», это «forty-one unversioned behavior inputs and nine competing standing policies», а дрейф «is unavoidable in spec-first practice and managed in spec-anchored practice, but only if divergence is detectable». Тот же пост советует около 300 строк на спеку и бюджет в 150-200 постоянных инструкций s13. Один практик описывает ручную версию: «I've had to have Claude compare the spec files to the codebase and see if anything is missing» s26.

Сколько это стоит

Сравнение это один эксперимент, и его автор так и говорит, но направление совпадает во всех трёх. Поэтому: пишите спеку для архитектурного пути, ограниченный путь держите ограниченным и следуйте двум фразам, которые повторяют практики, «don t spec too big / read the generated specs» s26.

Сделайте это в понедельник

• Создайте docs/specs/<squad>/ для каждой команды и добавьте по одной строке CODEOWNERS на папку, указывающей на ревьюеров этой команды.
• Добавьте в CLAUDE.md проекта одну жирную императивную строку: планы и спеки MUST be saved под docs/specs/<squad>/, NOT docs/superpowers/. Прогоните один brainstorm и проверьте, куда лёг файл.
• Перенесите личные планы в папку из .git/info/exclude и держите настройки каждого разработчика в CLAUDE.local.md, который тоже игнорируется.
• Поставьте заголовок на каждую общую спеку: status (proposed, accepted, superseded), superseded-by, owner, paths, review-by.
• Напишите drift gate: для каждой спеки со status: accepted извлеките названные в ней пути и валите pull request, если какого-то нет. Около пятнадцати строк на shell или Python.
• Добавьте правило про ветки: ни один коммит спеки или плана не попадает в main мимо pull request.
• Если репозиторий публикует документацию через Sphinx или подобное, добавьте папку со спеками в exclude_patterns сегодня.
• Задайте бюджет размера: спека держится около 300 строк, и она нужна только для работы, пересекающей границу команды или перечитываемой через 90 дней.

Идти дальше

• Прочитайте три категории использования спек (spec-first, spec-anchored, spec-as-source), прежде чем выбирать схему заголовка; жизненный цикл важен только для файлов spec-anchored s10.
• Статья на arXiv идёт дальше проверок путей, к архитектуре с полным контролем дрейфа; пригодится, когда пятнадцатистрочный gate станет слишком грубым s11.
• В руководстве Spec Kit названы три потока эволюции (Flow-Forward, Living Spec, Flow-Back), которые ложатся на правило одного коммита s7.
• Плейбук предлагает хук для синхронизации плана и диффа; в треде Reddit о нём 43 очка и 27 комментариев с отчётами из практики s5, s27.
• Довод TrueFoundry, что изменение спеки это изменение политики, а значит ему место за eval gate с метаданными запуска, следующий шаг после проверок путей в CI s13.
• Следите за двумя открытыми issue, 1246 (планы в main) и 939 (игнорируемые переопределения); когда одно из них закроют, одно правило из этого набора станет значением по умолчанию в плагине s16, s18.
• Полный разбор Marmelab объясняет, откуда взялись 1,300 строк и где Spec Kit всё-таки окупается s14.

Источники

• Superpowers writing-plans skill, GitHub. Зачем читать: точный путь по умолчанию и однострочная оговорка о переопределении, на которую вы опираетесь.
• Superpowers brainstorming skill, GitHub. Зачем читать: куда попадают спеки и шаг, который их коммитит.
• Claude Code memory, Anthropic. Зачем читать: CLAUDE.local.md это санкционированное место для личных настроек.
• Claude Code: working in large codebases, Anthropic. Зачем читать: файлы по каталогам, владельцы и claudeMdExcludes для монорепозиториев.
• The AI-native SDLC playbook, Anthropic. Зачем читать: довод об аудиторском следе и правило одного коммита от самого вендора.
• Spec Kit repository, GitHub. Зачем читать: раскладка спек по веткам для сравнения с раскладкой по командам.
• Spec Kit: evolving specs, GitHub. Зачем читать: самая ясная формулировка, что спека и код не должны расходиться.
• Kiro specs best practices, Kiro. Зачем читать: раскладка по папкам фич, рассчитанная на параллельную работу команд.
• Documenting architecture decisions, Michael Nygard. Зачем читать: словарь статусов, который заимствует заголовок.
• Spec-driven development: the tools, Thoughtworks. Зачем читать: различие spec-first и spec-anchored, определяющее, что хранить.
• The Spec Growth Engine, arXiv. Зачем читать: формальное обоснование блокирующего drift gate.
• OpenSpec bake-off discussion, GitHub. Зачем читать: единственные прямые сравнительные цифры по стоимости, с оговорками самого автора.
• Spec-driven development for AI agents, TrueFoundry. Зачем читать: спеки как версионируемая политика и бюджет в 300 строк.
• Spec-driven development: waterfall strikes back, Marmelab. Зачем читать: как выглядят 1,300 строк спеки для одной тривиальной фичи.
• Superpowers issue 1690, GitHub. Зачем читать: отчёт об утечке по шагам.
• Superpowers issue 1246, GitHub. Зачем читать: жалоба на main-ветку, всё ещё открытая.
• Superpowers issue 337, GitHub. Зачем читать: заявление мейнтейнера, что CLAUDE.md главнее начиная с v5.0.
• Superpowers issue 939, GitHub. Зачем читать: переопределение, которое не сработало, и формулировка, которая сработала.
• Superpowers pull request 1020, GitHub. Зачем читать: попытка исправления, закрытая без слияния.
• Superpowers issue 1780, GitHub. Зачем читать: как плагин самоигнорирует свою временную папку.
• okama fix commit, GitHub. Зачем читать: реальная команда, выбравшая хранить спеки и исключить их из сборки.
• okama docs/conf.py, GitHub. Зачем читать: однострочное исключение Sphinx, которое можно скопировать.
• About code owners, GitHub Docs. Зачем читать: механизм запроса ревью, на который опирается правило владения.
• gitignore documentation, Git. Зачем читать: info/exclude это слой личного игнорирования, о котором большинство забывает.
• We tried spec-driven development for months, Reddit r/SpecDrivenDevelopment. Зачем читать: отчёт о стоимости на уровне команды, за которым не стоит вендор.
• Does spec-driven development actually work for you?, Reddit r/ClaudeCode. Зачем читать: советы про размер и чтение спек от ежедневных пользователей.
• Has anyone tried Anthropic's AI-native SDLC playbook?, Reddit r/ClaudeCode. Зачем читать: отчёты о плейбуке в реальных репозиториях.

FAQ

Нужны ли все пять правил с первого дня?

Нет. Перенаправление в CLAUDE.md и исключение для Sphinx занимают десять минут. Добавьте CODEOWNERS и заголовок, когда спека впервые пересечёт границу команд, а drift gate, когда принятая спека проживёт спринт.

Что пропускает drift gate?

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

Почему просто не добавить папку в gitignore?

Потому что агенту, который позже читает спеку, она нужна, а аудиторский след работает, только если промежуточные звенья версионируются. Команда okama пробовала gitignore и вернулась к коммитам с исключением из сборки.