spec-driven-development

---
name: spec-driven-development
description: Use when the user explicitly asks to work in spec-driven mode (spec-driven, «по спекам», «заведи спеку», «ведём спеку»), or asks where the spec, plan, decisions or known problems for a task live. Covers a separate specs repository rooted at SPECS_ROOT — work-unit folders, stage epics, living decision and problem journals, sketch notes and work items, and linking specs to code commits. Opt-in — never apply to ordinary tasks unless the user asked.
---

# Spec-driven: спеки, планы и журналы решений

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

**Корень репозитория спек — переменная `SPECS_ROOT`.** Не задана — спроси путь один раз и держи его на сессию. Путь в тексты и конфиги не хардкодить.

**Структура каталогов — дерево в разделе «Где что лежит» ниже** (шаблон для нового репозитория — `templates/specs-repo` в корне библиотеки, из base dir скилла это `../../templates/specs-repo`; локальные дополнения описывает README репозитория спек). **Правила ведения записей — `references/formats.md`** рядом с этим файлом. Скилл самодостаточен: ни структура, ни форматы не требуют чтения документов репозитория спек.

## Когда включать

Только по явной просьбе: «работаем по спекам», «spec-driven», «заведи спеку», «где спека по …». Режим держится до конца задачи или до явной отмены.

Можно **один раз предложить**, если задача совпала хотя бы по одному критерию:

- затрагивает 2+ кодовых репозитория;
- это проект с этапами или несколько эпиков, а не один тикет;
- работа рассчитана больше чем на неделю;
- есть архитектурные альтернативы, которые придётся обосновывать;
- результат нужен другим командам.

Предложить — не начать. Без согласия режим не включать и папку не заводить.

## Когда не включать

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

## Где что лежит

```none
<SPECS_ROOT>/
├── TASKS.md      # индекс: папка → ID → статус
├── README.md     # правила структуры: единица работы, этапы, форматы файлов
├── AGENTS.md     # те же правила языком агента
└── tasks/<папка>/
    ├── index.md       # обязателен всегда: статус, ID, ветки, PR, скоуп
    ├── decisions.md   # журнал решений, текущая редакция
    ├── problems.md    # журнал проблем, текущая редакция
    ├── notes.md       # черновики: мысль в работе, не история
    ├── todo.md        # действия вне этапов, не история
    ├── spec.md        # требования (когда их надо согласовывать)
    ├── plan.md        # карта этапов (когда порядок неочевиден)
    ├── analysis/      # собранные данные: замеры, дампы, разбор кода, чек-листы
    ├── sources/       # внешние документы: снапшот на дату, не канон
    ├── archive/       # карточки закрытых шагов, по умолчанию не читаются
    └── stages/NN-*.md # этапы проекта, если их несколько
```

`analysis/` и `sources/` — не спека: вывод переезжает в `spec.md` или `decisions.md`, решение читается без артефакта. `archive/` — история закрытых шагов: в неё заходят по ссылке и только за конкретикой.

## Перед работой: что прочитать

1. `TASKS.md` — если известен только ID задачи.
2. `tasks/<папка>/index.md` — вид работы (`project` / `problem` / `research`), статус, все ID, репозитории, ветки, PR, скоуп.
3. `decisions.md` — сводка `## Действующие решения` в начале, дальше заголовки. Полный текст — по номеру (`grep '^## D43'`). Это ответ на «почему так». Журнал целиком не читать: он растёт.
4. `problems.md` — до того, как чинить в затронутой области: возможно, уже наступали.
5. `spec.md` / `plan.md` / `stages/*` — по необходимости.
6. `analysis/` / `sources/` — по ссылке из `index.md` или журнала и только нужный кусок: факты оттуда, а не канон.
7. `notes.md` — черновики, если есть: не решение, не цитировать.
8. `todo.md` — действия вне этапов, если он есть: не решения, не история.
9. `archive/` — назначенная история: **по умолчанию не читать**, открывать только по ссылке из этапа или журнала.
10. Шапка `decisions.md`: `**Последняя ревизия:**`. Прошло больше недели (при активной работе — 2–3 дня) или набежало >8 записей — предложи ревизию.

Нет файлов кроме `index.md` — это lite-режим, вся суть в карточке. Не считать это незаполненной спекой.

## По ходу работы: что писать

Куда идёт решение, проблема, требование и черновик — в `references/formats.md`, абзац «Перед записью». Здесь только то, что не про запись:

- Закрыл этап или поменял статус → `index.md` и `TASKS.md` одним коммитом.
- Измерил, снял дамп, разобрал код → файл в `analysis/`: одна тема, шапка с датой и коммитом. Вывод переезжает в решение или требование, подробности остаются в артефакте.
- Документы, на которых стоит спека → `sources/`: снапшот на дату, не поддерживаемая копия.
- Мысль, которую рано фиксировать решением → `notes.md`, без номеров.
- Шаг закрыт → его карточка из `notes.md` переносится в `archive/<шаг>.md`, в этапе остаётся ссылка. Остальные блоки `notes.md` не трогаются.

**Перед любой записью в `decisions.md` прочитай `references/formats.md`**: там формат полей, бюджет строк, тест «если завтра запись исчезнет — кто-нибудь сделает иначе?», правила ревизии и запрет переписывать историю. Без этой сверки запись почти всегда уезжает в эссе.

## Связь с кодом

- Ветка: `<фактический TASK-ID>-<kebab-slug>`.
- Заголовок коммита: `[<фактический TASK-ID>] <English summary>`. Подзадача подписывается своим ID, а не ID проекта.
- В теле коммита или PR: `Spec: <SPECS_ROOT>/tasks/<папка>/`.
- Хеши значимых коммитов — в `index.md` или в записи журнала.

## Коммиты в репозитории спек

- Один коммит — одно изменение: новое решение, новая проблема, закрытый этап, смена статуса.
- Заголовок на английском, тело по-русски, по существу.
- Без `--amend`, rebase и squash: путь к решению — тоже артефакт.
- Не коммитить обрывки «чтобы не забыть» — для этого есть «Открытые вопросы» в `index.md`.

## Закрытие

- `index.md`: статус `done`, заполнен «Итог» — что сделали, чем закончилось, что осталось.
- Журналы отражают реальность: новые записи дописаны, статусы старых обновлены.
- `TASKS.md` обновлён.
- Если из спеки есть вывод, полезный команде, — он перенесён в вики. Каталог вики берётся из `WIKI_ROOT`, если переменная задана, иначе спроси, нужно ли переносить и куда.

## Антипаттерны

- Пересказывать описание задачи из трекера вместо ссылки на ID.
- Заводить пять файлов «по шаблону» на задачу без содержания.
- Писать спеку после релиза для отчётности — ценности нет, только вид работы.
- Складывать в спеку секреты, пароли, внутренние адреса с доступами.
- Разносить этапы одного проекта по отдельным папкам: теряется связь «прототип → кодогенерация → внедрение».
- Включать режим самовольно на любой крупной задаче.
- Писать запись-эссе на 30–50 строк: это либо несколько решений, либо не решение.
- Доливать в `Контекст` пересказ кода, замеры и дампы: через месяц это врёт, для данных есть `analysis/`.
- Ссылаться на лог или документ со своего диска либо тащить в папку гигабайтное сырьё: читателю нужны цифры и способ их получить.
- Сочинять альтернативы, которых не рассматривали, — фальшивый след мысли.
- Оформлять набросок сразу решением и потом «охранять» его от правок.

## Гейт

Детерминированная проверка формы — `scripts/spec_check.py` рядом с этим файлом. Запуск из base dir скилла:

```sh
python3 <base>/scripts/spec_check.py --spec <SPECS_ROOT>/tasks/<папка>
```

На Windows вместо `python3` подойдёт `py`. Гейт берёт репозитории из `repos:` в `index.md` и ищет их под `PROJECTS_ROOT` (по умолчанию родитель `SPECS_ROOT`, иначе `~/projects`). Проверяет, что отмеченный пункт ссылается на коммит, файл или тест, что имена из отмеченных пунктов встречаются в коде, что `repo@hash` и `файл:строка` резолвятся, что номера `D`/`P` и сводка сходятся. Имена сравниваются как текст, а не разрешаются как символы; вендорные и build-каталоги не читаются.

**Тесты гейт не запускает.** Прогон — работа исполнителя, результат живёт в карточке шага.

Что именно читается, какие флаги есть (`--strict`, `--index`, `--repo`, `--file-root`, `--projects-root`) и чем `--index strict` отличается от `summary` — в `--help` и докстринге скрипта.

• SKILL.md 13 KB
• references/formats.md 16 KB
• scripts/spec_check.py 30 KB
• scripts/test_spec_check.py 17 KB