SPEC.md как контракт длинной задачи

1. SPEC.md появляется раньше кода

Когда задача маленькая, часть вещей действительно можно удержать в голове: один баг, один тест, один экран — хватает task spec на полстраницы. Но capstone — штука длинная, память у него хуже, чем хочется, а сюрпризы появляются чаще, чем кофе успевает остыть. Поэтому начинать его сразу с кода — всё равно что ехать в отпуск без билетов, маршрута и чемодана, но с очень уверенным лицом.

К этому моменту у вас уже есть две разные вещи, и их лучше не путать. CAPSTONE_BRIEF.md задаёт общие правила capstone для всех. SPEC.md — ваш личный контракт: формат, один core flow, non-goals и способ проверки вашего проекта. Рядом позже поселится EVIDENCE.md, но пока контракта нет — журналу нечего фиксировать.

У обычной задачи и у capstone разный масштаб неопределённости. Это хорошо видно в простой таблице.

Именно поэтому SPEC.md — не бумажка для галочки, а инженерный контракт длинной задачи. Он нужен не потому, что документация — это святое, а потому, что без него каждый додумывает своё: Claude гадает, ментор уточняет, ревьюер сомневается, а вы вспоминаете, зачем убрали уведомления и откуда взялась третья ветка «финал_точно_рабочий_2». Удобно думать о нём как о центральной точке согласования:

Идея проекта
    ↓
`SPEC.md`
    ↓
Планирование → реализация → проверки → demo
    ↑            ↑            ↑
  студент      Claude     mentor/reviewer

Сильный capstone начинается не с фразы «сейчас быстро накидаем MVP», а с этого документа, который уменьшает количество догадок. И не переживайте: это не роман на восемь глав — это просто ясный договор о том, что вы строите, чего не строите и как поймёте, что готово.

2. Состав SPEC.md по разделам

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

Problem

Target user

Current state

Desired state

Scope

Non-goals

Constraints

Критерии приёмки

План проверки

Risks and open questions

Каркас может выглядеть вот так:

# SPEC.md

## Проблема
## Целевой пользователь
## Текущее состояние
## Желаемое состояние
## Область изменений
## Не-цели
## Ограничения
## Критерии приёмки
## План проверки
## Риски и открытые вопросы

Обратите внимание на две вещи. Во-первых, раздела «сделаем красиво» здесь нет — компьютеры, ревьюеры и дедлайны с этим критерием работают плохо. Во-вторых, важна не полнота ради полноты, а ясность. Умещаете проект на одном экране — отлично. Пришлось писать шесть страниц — возможно, дело в том, что scope уже пытается вырваться из клетки и убежать в лес.

Чтобы не смешивать capstone со сквозным CashFlow Dashboard, в примерах дальше возьму отдельный учебный проект студента — Subscription Watch. Это маленький сервис для учёта подписок: пользователь видит активные подписки, ближайшие списания и может отметить отмену ненужной. Домен знаком по финансовой теме курса, но это отдельный репозиторий, а не продолжение CashFlow.

Дальше пример будет ближе к продуктовому проекту, потому что на нём проще всего увидеть разницу между проблемой, scope и проверками. Но те же разделы работают и для других форматов. В modernization или migration Target user — инженер, владелец сервиса или сама команда, Current state — legacy-поведение или ручной шаг, Desired state — проверенное изменение или pilot slice. В DevOps automation и team workflow design спецификация крутится вокруг .claude/, .github/, docs/, scripts/ и набора проверок: UI и src/ там не обязательны. А Критерии приёмки и План проверки никуда не деваются — вместо UI-сценария там регрессионные проверки, dry run, валидация hooks или evidence по пилотной миграции.

3. Пишем Problem, Current state и Desired state

В начале SPEC.md нужна не мечта, а наблюдаемая проблема. Самая частая ошибка звучит так: «Хочу сделать удобный сервис подписок» — симпатичная, честная, но всё же мечта. Проблема начинается там, где у пользователя уже болит что-то наблюдаемое: теряются деньги, пропускаются даты списания, нет единой картины расходов. Если этого нет в тексте, Claude позже начнёт помогать не вам, а абстрактной идее удобства. А абстрактные идеи, как известно, очень любят разрастаться.

Для нашего Subscription Watch первые разделы можно набросать так:

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

## Целевой пользователь
Фрилансер или соло-специалист с 5–10 активными подписками.

## Текущее состояние
Подписки хранятся в заметках или в голове. Единого списка нет.

## Желаемое состояние
Пользователь добавляет подписку, видит дату следующего списания
и может отметить подписку как отменённую.

Здесь важно, что Current state и Desired state описывают поведение, а не архитектурные фантазии. Не «PostgreSQL и красивый React-интерфейс», а «добавляет», «видит», «может отметить» — именно это потом можно проверять. Полезно держать в голове простой тест: вырежьте названия технологий — смысл проекта остался? Если нет, capstone быстро превращается в ремонт квартиры по фразе «давайте что-нибудь современное»: лишние розетки, странные решения и очень бодрые оправдания.

Ещё один важный нюанс: Desired state не должен обещать сразу весь прекрасный мир. Напоминания, импорт банковских операций, аналитика, мобильное приложение, AI-классификация расходов — не повод писать всё в один раздел. Зафиксируйте один внятный результат; остальное позже станет кандидатом в Non-goals.

4. Scope, Non-goals и Constraints

Именно здесь capstone чаще всего спасают от героической, но бесполезной гибели. Пока проект живёт в голове, всё кажется разумным: «Ну список сделаю, и ещё напоминания, и раз уж пошла такая пьянка — интеграцию с банком тоже». Потом наступает момент, когда список задач уже похож на резюме трёх разных стартапов. Чтобы такого не случилось, Scope и Non-goals пишутся рано и честно:

## Область изменений
- список активных подписок
- карточка подписки с суммой и датой следующего списания
- отметка «отменена»
- простое напоминание о близком списании

## Не-цели
- интеграция с банком
- мобильное приложение
- автоматическая категоризация через AI
- production deployment

Это тот случай, когда короткий список экономит очень много времени. Scope отвечает на вопрос «что мы реально довозим». Non-goals — «на что будет соблазн отвлечься, но мы этого не делаем». И именно второй раздел часто оказывается важнее первого: люди не забывают добавить задачу в проект — они забывают вовремя её не добавить.

После этого идут Constraints — жёсткие технические и процессные границы:

## Ограничения
- без новых платёжных сервисов
- без сложной авторизации
- один основной пользовательский сценарий
- проект должен запускаться локально по README
- все изменения должны быть проверяемы вручную и тестами

Constraints полезны тем, что не дают вам самим красиво себя обмануть. Фраза «сделаем сложную авторизацию потом» почти всегда означает, что вы её уже впустили в проект. А capstone очень не любит незваных гостей. Поэтому если вы заранее знаете, что без production deploy и тяжёлой auth-задачи проект будет сильнее, — лучше записать это прямо. Не стоит надеяться на внутреннюю стойкость: она работает ровно до первой мысли «ну это же небольшая доработка».

5. Критерии приёмки и План проверки

Очень многие проекты ломаются не на коде, а на фразе «ну вроде готово». В инженерной разработке это опасные слова, в capstone — особенно. Поэтому Критерии приёмки и План проверки появляются ещё до реализации. Один отвечает за то, что должно быть истинным в результате, второй — чем вы это докажете.

Критерии приёмки для Subscription Watch могут быть такими:

## Критерии приёмки
1. Можно добавить подписку с названием, суммой и датой списания.
2. На главном экране видны только активные подписки.
3. Отменённая подписка исчезает из активного списка.
4. Пользователь видит ближайшее списание без перехода в детали.

А рядом — план проверки:

## План проверки
- `./gradlew test` проходит без ошибок
- приложение стартует локально по инструкции из README
- вручную: добавить подписку, отметить её отменённой, открыть список снова
- вручную: проверить отображение ближайшей даты списания
- при падении проверки зафиксировать это в `EVIDENCE.md`

Если идея план проверки уже стала для вас привычной, то здесь происходит ровно то же самое, только в масштабе capstone: вы заранее договариваетесь с собой, ментором и ревьюером, какие сигналы считаются доказательством. Не «ткнул пару кнопок, вроде работает», а понятный набор действий и результатов.

Очень полезно разделять эти два блока в голове. Критерии приёмки — мир результата: «отменённая подписка не видна среди активных». План проверки — мир доказательств: «вот как именно мы это проверяем». Смешаете в кашу — текст убедителен, но не помогает ни реализовывать, ни защищать проект.

И ещё одна маленькая, но важная вещь: в План проверки полезно писать поведение при сбое. Тесты упали — что делаете? README не воспроизводится на чистом запуске — что это значит для статуса задачи? В длинном проекте такие мелочи внезапно оказываются очень взрослыми.

6. Claude как редактор SPEC.md, а не телепат

Claude великолепно находит двусмысленности, скрытый overscope и слабые места в постановке. Но есть один нюанс: он умеет это делать после того, как вы сами сформулировали мысль, а не вместо неё. Иначе начинается классическая история: вы просите «придумай мне capstone», он честно придумывает, а вы полкурса выясняете, нравится ли вам чужая идея, которую сами же попросили сгенерировать.

Безопасный способ — использовать Claude как внимательного редактора и интервьюера:

Проверь мой `SPEC.md`.
Не предлагай реализацию и не пиши код.
Найди:
1) двусмысленные места,
2) скрытый overscope,
3) слабые критерии приёмки,
4) недостающие проверки,
5) технические риски.
Верни замечания по разделам.

Такой запрос хорош тем, что не отдаёт Claude руль проекта: направление задали вы, а он помогает убрать туман. Иногда полезно идти ещё аккуратнее и сначала попросить только вопросы, без готовых решений:

Посмотри на мой `SPEC.md` и задай до 7 уточняющих вопросов.
Не предлагай код и не расширяй scope.
Твоя задача — найти места, где проект пока сформулирован неясно.

Это особенно полезно, когда вам кажется, что всё уже понятно: обычно именно в этот момент в спецификации живёт «удобные уведомления» или «простая авторизация» — красивые слова с очень разным техническим весом.

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

7. SPEC.md — живой документ, а не каменная плита

Было бы приятно один раз идеально написать спецификацию и больше к ней не возвращаться, но на практике так почти не бывает: в длинной задаче вы что-то уточняете, что-то сознательно убираете, где-то меняете способ проверки. Это нормально. Ненормально делать такие изменения молча — тогда через неделю вы уже не помните, почему отказались от push-уведомлений и с какой радости ручная проверка стала основной вместо теста.

Поэтому зрелый SPEC.md — живой документ. Меняете scope, non-goals или план проверки — обновляете файл и коротко фиксируете причину в EVIDENCE.md:

## 2026-05-24
Изменил scope: убрал push-уведомления, оставил только e-mail.
Причина: второй канал усложнял demo и ломал локальную проверку.
Обновил в `SPEC.md`: разделы Scope, Non-goals, План проверки.

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

И вот здесь capstone становится по-настоящему управляемым. Не тогда, когда вы с первого раза всё угадали идеально, а тогда, когда можете показать: вот исходная постановка, вот почему скорректировали границы, вот как это повлияло на проверки, вот чем подтверждается текущее состояние. Когда SPEC.md живёт вместе с evidence, проект перестаёт быть туманной «финальной работой» и становится серией ясных решений, каждое из которых можно прочитать, проверить и защитить.

1

Задача

Claude code, 25 уровень, 2 лекция

Недоступна

Создание skeleton SPEC.md через терминал

Создание skeleton SPEC.md через терминал

Открыть

1

Задача

Claude code, 25 уровень, 2 лекция

Недоступна

Первый draft SPEC.md для capstone

Первый draft SPEC.md для capstone

Открыть