От промптов к спекам с AI-агентами

Зачем спека, если есть промпт

Открываете новый чат в Claude Code, пишете развёрнутый промпт — и агент генерирует отличный стартер. Закрываете сессию. На следующий день открываете новую и просите добавить авторизацию. Агент уверенно предлагает хранить сессии в Redis — хотя вчера вы обсуждали JWT и договорились обойтись без сессий. Через два запроса он пишет fetchUser() рядом с уже существующей getUserById().

Это не глюк — это предсказуемое следствие одного факта: промпт исчезает вместе с сессией.

Почему агент достраивает пробелы

У Cursor и Claude Code нет долгосрочной памяти о проекте между сессиями. При старте каждого нового чата агент видит только то, что лежит у него в контексте прямо сейчас. Нет ничего — значит, пробелы заполняются лучшими догадками.

Три симптома, которые появляются уже на третьем-четвёртом запросе:

• Дрейф решений — агент забывает про договорённости по стеку и предлагает альтернативы «потому что так проще».
• Дубли с вариацией — похожая функция пишется заново под другим именем, потому что агент не знает, что такая уже есть.
• Молчаливые допущения — вы не описали edge-case, агент придумал что-то сам, и это «что-то» меняется от сессии к сессии.

Промпт — отличный инструмент для одного шага. На проект целиком он не масштабируется.

Spec-first: один источник правды

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

Когда агент стартует новую задачу, вы кладёте ему в контекст не только промпт, но и спеку. Теперь у него есть «память» — не в голове, а в файловой системе проекта.

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

Цикл SDD: от конституции до кода

В SDD пять этапов, которые идут по кругу:

• Constitution («конституция») — файл CLAUDE.md (для Claude Code) или .cursor/rules/project.mdc (для Cursor). Описывает стек, соглашения по коду и неизменные принципы проекта. Агент читает его при каждом запуске автоматически.
• Specify — спека конкретной фичи: что должна делать, каковы граничные случаи, что считается «готово». Живёт в /specs/feature-name.md.
• Plan — агент превращает спеку в план реализации. Вы проверяете и корректируете.
• Tasks — план разбивается на плоский список в tasks.md. Каждую задачу можно выполнить и проверить отдельно.
• Implement — агент реализует задачи одну за другой, держась в рамках спеки.

В следующих подмодулях мы разберём каждый этап детально. Сейчас главное — понять структуру цикла и сразу завести нужные файлы.

Промпт или спека? Проверьте интуицию

Заводим структуру прямо сейчас

Минимальная структура pet-проекта на старте:

my-project/
├── CLAUDE.md        # конституция (Claude Code читает автоматически)
├── specs/
│   └── README.md    # «здесь живут спеки фич»
└── tasks.md         # появится позже, на этапе декомпозиции

Первый CLAUDE.md — не роман. Достаточно трёх блоков:

# [Название проекта]

## Что это
[Одна строка: что делает проект и для кого]

## Стек
- [Язык / фреймворк]
- [База данных и ORM]
- [Что явно НЕ используем]

## Соглашения
- [Именование файлов и папок]
- [Паттерны, которым следуем]

Для Cursor — создайте .cursor/rules/project.mdc с тем же содержимым плюс frontmatter:

---
alwaysApply: true
---

alwaysApply: true означает, что правило применяется ко всем файлам проекта. Claude Code читает CLAUDE.md из корня при каждом запуске — никаких дополнительных настроек не нужно.

Три шага прямо сейчас

1. Создайте репозиторий для pet-проекта.

2. Создайте CLAUDE.md в корне — заполните три блока: «Что это», «Стек», «Соглашения». Не думайте над ним дольше 10 минут: это живой документ, он будет обновляться.

3. Создайте specs/README.md с одной строкой: «Здесь живут спеки фич».

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