CatoCut

Практическое руководство по написанию работающих спеков. Паттерны из 200+ продакшн-спеков.

Анатомия спека

Пять секций. Пропустите любую — теряете надёжность.

spec:
  goal: "Что агент должен сделать"
  context: "Что агенту нужно знать"
  constraints: "Чего не должен делать"
  output: "Как выглядит результат"
  verification: "Как узнаем, что сработало"

Шаг 1: Цель

Одно предложение. Если нужны два — нужны два спека.

Плохо: «Помочь с кодом» / «Отрефакторить авторизацию и обновить тесты и задеплоить»

Хорошо: «Извлечь инлайн SQL в UserRepository в параметризованные prepared statements»

Тест: можно верифицировать да/нет? Если нет — заточите.

Шаг 2: Контекст

Не «всё, что может понадобиться». Минимум информации без вопросов.

context:
  repository: "payments-service"
  files_in_scope:
    - "src/repositories/UserRepository.ts"
  relevant_patterns:
    - "Репозитории используют DatabaseClient из src/db/client.ts"
    - "Параметризованные запросы: client.query(sql, params)"
  technical_constraints:
    - "TypeScript strict mode"
    - "Без ORM — только raw SQL"

Шаг 3: Ограничения

Самая важная секция. Три типа:

Граничные

do_not_modify: ["src/db/client.ts", "src/migrations/*"]
do_not_change: ["Сигнатуры API", "Схема БД"]

Поведенческие

behavior:
  - "Каждое изменение в отдельном коммите"
  - "Тесты проходят после каждого коммита"
  - "Без новых зависимостей"

Качественные

quality:
  - "Весь новый код с типами"
  - "Без any"
  - "SQL параметризован, без конкатенации"

Шаг 4: Формат вывода

output:
  format: "git-patch"
  structure:
    - commit_message: "Conventional Commits"
    - files_changed: "Список с описанием"
    - test_results: "Полный вывод"

Шаг 5: Верификация

verification:
  automated:
    - "TypeScript компилируется без ошибок"
    - "Все тесты проходят"
    - "Нет новых 'any'"
  manual:
    - "Ревью каждого коммита на семантику"

Частые ошибки

Неявные ограничения — не сказали «не удаляй» — агент может удалить.
Перегруженные цели — «и» в цели = разделите спек.
Недостающий контекст — неявное знание сделайте явным.
Без верификации — «посмотрю вручную» — не верификация.

Шаблон

spec:
  goal: "[одно предложение]"
  context:
    repository: ""
    files_in_scope: []
    relevant_patterns: []
  constraints:
    boundaries: []
    behavior: []
    quality: []
  output:
    format: ""
    structure: []
  verification:
    automated: []
    manual: []

«Хорошо написанный спек — контракт. Плохо написанный — пожелание.»