Сначала спецификация, потом код: требования, сценарии и жизненный цикл изменения

Сначала договориться, потом писать код

Попросите агента: «Сделай ограничение попыток входа». Ему придётся решить за вас: сколько попыток, на какой срок блокировать, считать по IP или по логину, что ответить пользователю. Он решит. Завтра в новой сессии он решит ещё раз, и, возможно, иначе. Такой подход называют вайб-кодингом.

Spec-Driven Development (разработка от спецификации) меняет порядок. Сначала вы записываете решения в файл. Потом агент реализует ровно их. Минимальная единица — требование и сценарий его проверки:

### Requirement: Ограничение попыток входа
Система SHALL блокировать вход по логину на 15 минут
после 5 неудачных попыток подряд.

#### Scenario: Шестая попытка заблокирована
- **WHEN** пользователь 5 раз подряд ввёл неверный пароль
- **THEN** шестая попытка получает ответ 429
- **AND** вход по этому логину снова доступен через 15 минут

Как устроена спецификация и цикл изменения

Слова SHALL и MUST. Это слова обязательности из стандарта RFC 2119. MUST и SHALL значат «обязательно». SHOULD — «желательно». Слова «желательно, по возможности, быстро» агент прочитает как разрешение сделать как угодно.

Сценарии. Формат пришёл из BDD: GIVEN (дано, исходное состояние), WHEN (когда, действие), THEN (тогда, ожидаемый результат), AND (и ещё). Каждый сценарий — готовый тест.

Нефункциональные требования. Скорость, безопасность, ограничения. Тоже с числами: «ответ SHALL приходить быстрее 300 мс для 95% запросов», а не «должно работать быстро».

Цикл изменения. Возьмём инструмент OpenSpec. Текущая правда о системе лежит в openspec/specs/. Каждое изменение — отдельная папка в openspec/changes/<имя>/:

1. proposal.md — зачем меняем и что именно.
2. specs/<возможность>/spec.md — дельта: какие требования добавлены (ADDED), изменены (MODIFIED), удалены (REMOVED).
3. design.md — как будем делать технически, если это не очевидно.
4. tasks.md — шаги-чекбоксы для реализации.
5. Реализация и проверка: агент идёт по задачам, тесты из сценариев зелёные.
6. Архив: дельта вливается в openspec/specs/, папка изменения уходит в архив.

Похожий путь у GitHub Spec Kit: команды /specify, /plan, /tasks ведут от спецификации к плану и задачам. Инструменты разные, идея одна.

# openspec/changes/add-login-rate-limit/proposal.md
## Why
Ботами перебирают пароли. За неделю 12 000 неудачных входов с 40 логинов.

## What Changes
- Блокировка входа по логину после 5 неудачных попыток на 15 минут.
- Ответ 429 с понятным текстом и временем до разблокировки.

## Impact
- Затронуто: auth (вход), redis (счётчики).

# openspec/changes/add-login-rate-limit/specs/auth/spec.md
## ADDED Requirements
### Requirement: Ограничение попыток входа
Система SHALL блокировать вход по логину на 15 минут после 5 неудачных попыток подряд.

#### Scenario: Шестая попытка заблокирована
- **WHEN** пользователь 5 раз подряд ввёл неверный пароль
- **THEN** шестая попытка получает ответ 429

#### Scenario: Успешный вход сбрасывает счётчик
- **GIVEN** у логина 4 неудачные попытки
- **WHEN** пользователь ввёл верный пароль
- **THEN** счётчик неудачных попыток равен 0

# openspec/changes/add-login-rate-limit/tasks.md
## 1. Реализация
- [ ] 1.1 Счётчик неудачных попыток в redis с TTL 15 минут
- [ ] 1.2 Проверка лимита перед проверкой пароля, ответ 429
- [ ] 1.3 Сброс счётчика при успешном входе
## 2. Проверка
- [ ] 2.1 Тест на каждый сценарий из spec.md
- [ ] 2.2 Ручная проверка на стенде

Исполняемая спецификация и связь с harness

Спецификация как часть процесса. Она не лежит мёртвым документом. Harness встраивает её в работу агента:

• скил «реализуй изменение» читает tasks.md и берёт первую незакрытую задачу;
• после каждой задачи агент отмечает чекбокс, так прогресс переживает новую сессию;
• из каждого сценария получается тест, и тест падает, пока поведение не совпало с договором;
• проверяющий агент или скрипт сверяет: у каждого требования есть сценарий, у каждого сценария есть тест;
• несколько агентов (урок 10) делят задачи из одного tasks.md и не спорят о целях.

Три ловушки.

• Размытые слова. «Быстро», «удобно», «корректно», «по возможности». Агент трактует их как хочет. Замените числом или сценарием.
• Требование без сценария. Нельзя проверить — значит, нельзя доказать, что сделано.
• Спецификация разошлась с кодом. Код поменяли руками, а спецификацию нет. Через месяц агент «починит» код обратно по старой спецификации. Лечится архивом изменений и правилом: поведение меняем только через изменение спецификации.

<?php
// tests/Auth/LoginRateLimitTest.php — PHPUnit
final class LoginRateLimitTest extends WebTestCase
{
    /** Scenario: Шестая попытка заблокирована */
    public function testSixthAttemptIsBlocked(): void
    {
        $client = static::createClient();
        // WHEN пользователь 5 раз подряд ввёл неверный пароль
        for ($i = 0; $i < 5; $i++) {
            $client->jsonRequest('POST', '/api/login', ['login' => 'anna', 'password' => 'wrong']);
            self::assertResponseStatusCodeSame(401);
        }
        // THEN шестая попытка получает ответ 429
        $client->jsonRequest('POST', '/api/login', ['login' => 'anna', 'password' => 'wrong']);
        self::assertResponseStatusCodeSame(429);
    }
}

# tests/test_login_rate_limit.py — pytest
def test_sixth_attempt_is_blocked(client):
    """Scenario: Шестая попытка заблокирована"""
    # WHEN пользователь 5 раз подряд ввёл неверный пароль
    for _ in range(5):
        r = client.post("/api/login", json={"login": "anna", "password": "wrong"})
        assert r.status_code == 401
    # THEN шестая попытка получает ответ 429
    r = client.post("/api/login", json={"login": "anna", "password": "wrong"})
    assert r.status_code == 429

// test/login-rate-limit.test.js — node:test
import { test } from "node:test";
import assert from "node:assert/strict";
import { login } from "./helpers.js";

test("Scenario: Шестая попытка заблокирована", async () => {
  // WHEN пользователь 5 раз подряд ввёл неверный пароль
  for (let i = 0; i < 5; i++) {
    assert.equal((await login("anna", "wrong")).status, 401);
  }
  // THEN шестая попытка получает ответ 429
  assert.equal((await login("anna", "wrong")).status, 429);
});

// test/login-rate-limit.test.ts — node:test + TypeScript
import { test } from "node:test";
import assert from "node:assert/strict";
import { login } from "./helpers";

test("Scenario: Шестая попытка заблокирована", async () => {
  // WHEN пользователь 5 раз подряд ввёл неверный пароль
  for (let i = 0; i < 5; i++) {
    const res: Response = await login("anna", "wrong");
    assert.equal(res.status, 401);
  }
  // THEN шестая попытка получает ответ 429
  assert.equal((await login("anna", "wrong")).status, 429);
});